informed-decision/history/20260909-initial-exploration/canonicalize.md

Canonicalization algorithm v0.2

Two hashes exist on every presentation.

Hash	Input	Enters the signature?
view_hash	binding document	yes, for every binding verb at organizational and above
awareness_hash	awareness document	no, unless a promote disposition copied named fields into awareness_promoted

That split is the whole point of pre-sign vs post-sign.

Reference implementation: canonicalize.py.

1. Profile

Restricted JCS (RFC 8785 subset):

1. UTF-8.
2. No insignificant whitespace.
3. Object keys sorted by raw UTF-8 bytes (all keys in this spec are ASCII).
4. Arrays keep author order except where this spec sorts (packet by item_id, highlights by id, hats/scopes/identities by id, permission lists lexicographically).
5. Numbers are integers only. Timestamps stay strings (YYYY-MM-DDTHH:MM:SSZ).
6. Strings use RFC 8259 escaping; U+0000–U+001F as \u00xx.
7. Drop keys whose value is null. Keep empty arrays.
8. Unknown keys are stripped. Adding a field to the live memo does not change a hash until it is added to the allow-list below.

2. Binding document (view_hash)

Allow-list, then normalize:

memo_id
memo_version
question
requested_act
binding_level
brief
locale
ui_release
packet[]           → {item_id, hash} sorted by item_id
highlights[]       → {id, item_id, locator, required_ack, severity} sorted by id
binding            → BindingSlice (pre-sign identity + scope)
awareness_promoted → only fields explicitly promoted into the bind

binding allow-list:

principal
available_identities[]   sorted by id
target                   the scope this act enters
available_bind_scopes[]  scopes choosable as *this* bind, sorted by id
granted_at_bind          roles/permissions sorted
justification
blast_radius
terms

Hats, last-used role, other-tenant orientation, situation notes do not appear here.

hash form is always alg:hex (sha256:…).

Then:

canonical = dumps(binding_document)
view_hash = SHA-256(UTF-8(canonical))

dumps is the JCS-subset serializer in canonicalize.py.

3. Awareness document (awareness_hash)

Allow-list:

memo_id
memo_version
locale
ui_release
proposed_hat
proposed_hat_source     system_default | last_used | policy | explicit | inferred
available_hats[]        sorted by id
available_scopes[]      sorted by id   (orientation only)
last_session
situation_note

Same dumps + SHA-256.

4. Dynamic linking

A binding disposition stores both hashes on the presentation and signs only view_hash.

Signed attributes (AES/QES) MUST contain at least:

memo_id
memo_version
disposition.verb
presentation.view_hash

They MUST NOT contain awareness_hash unless promote ran.

5. Promote

promote copies named awareness fields into binding.awareness_promoted on a new memo version. Typical case: an elevating hat (hat.elevates=true) must become part of the bind, or a tenant that looked like a hat is actually a bind-scope.

After promote:

• new view_hash
• previous presentations invalid
• route restarts or current step is re-presented

6. Test vectors

Computed with canonicalize.py.

V1 — login binding (identity + tenant)

Input: vectors/login-binding.json

view_hash.hex =

492d9d311bf44ec9de0d0abef28abac7d31df2781527e8fe276a3186ee1b06b8

What is inside: chosen principal, break-glass identity as an available bind identity, target tenant ACME, sibling tenant Beta as an available bind-scope, gate privileges authenticated + session.create, monitoring terms.

What is not inside: Finance Controller hat, last session, Payroll Admin.

V2 — login awareness (hats + last session)

Input: vectors/login-awareness.json

awareness_hash.hex =

2be7742970a01e7a879ae5040660659fb8c9a5c024e6c7fb338f3944a4fe05d1

Proposed hat hat:finance-controller source last_used. Payroll Admin is listed with elevates=true so the UI can show it and the state machine can refuse configure on it.

V3 — ADR accept

Input: vectors/adr-binding.json

view_hash.hex =

1c89ec07c3cc9d16f85a1ba1be5169456b3c55d21161f64037787779ae91f202

Isolation checks the implementation must keep green

1. Shuffling object keys in the input JSON does not change either hash.
2. Adding or changing awareness fields on a combined object does not change view_hash.
3. Changing binding.target.id from tenant:acme to tenant:beta does change view_hash (that is a different login).
4. Changing only proposed_hat changes awareness_hash only.
5. Selecting hat:finance-controller after login emits session.hat_selected and does not rewrite view_hash.

7. UI mapping (login)

┌─────────────────────────────────────────────────────────┐
│ PRE-SIGN  (editable, bound)                             │
│  Identity   [ Bernd Worsch            ▾ ]               │
│  Scope      [ ACME Corp / Payroll-Prod ▾ ]              │
│  At gate    authenticated · session.create              │
│  Terms      sessions recorded                           │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│ AWARENESS  (shown, not signed)                          │
│  After login you will wear                              │
│    Finance Controller   (last used, Tue 18:12)          │
│    other hats: Auditor · Payroll Admin (needs new bind) │
│  Other tenants you support: Beta GmbH (needs new bind)  │
└─────────────────────────────────────────────────────────┘
          [ Switch identity ]  [ Change tenant ]  [ Proceed ]

Proceed signs V1. After session start, hat dropdown is configure. Tenant dropdown to Beta opens a child memo.