@metalabel/dfos-protocol 0.4.0 → 0.6.0

package/PROTOCOL.md

@@ -1,1121 +0,0 @@
-# DFOS Protocol
-
-Verifiable identity and content chains — Ed25519 signatures, content-addressed CIDs, W3C DIDs. Cross-language verification in TypeScript, Go, Python, Rust, and Swift.
-
-This spec is under active review. Discuss it in the [clear.txt](https://clear.dfos.com) space on DFOS.
-
-[Source](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol) · [npm](https://www.npmjs.com/package/@metalabel/dfos-protocol) · [Gist](https://gist.github.com/bvalosek/ed4c96fd4b841302de544ffaee871648)
-
----
-
-## Philosophy
-
-DFOS is a dark forest operating system. Content lives in private spaces — visible only to members, governed by the communities that create it. The cryptographic proof layer is public: signed chains of commitments that anyone can independently verify with a public key and any standard EdDSA library.
-
-Two chain types — identity and content — use the same mechanics: Ed25519 signatures, JWS compact tokens, content-addressed CIDs. The protocol knows about keys and document hashes. It doesn't know about posts, profiles, or any application concept. Document semantics are application layer — free to evolve without protocol changes.
-
-The protocol is not coupled to the DFOS platform. Any system implementing the same chain primitives produces interoperable, cross-verifiable proofs. An identity created on one system can sign content on another.
-
----
-
-## Protocol Overview
-
-The DFOS protocol has five components:
-
-| Component             | Concern                                                                      |
-| --------------------- | ---------------------------------------------------------------------------- |
-| **Crypto core**       | Identity chains + content chains — Ed25519 signatures, JWS tokens, CID links |
-| **Credentials**       | Auth tokens (DID-signed JWT) and VC-JWT credentials for authorization        |
-| **Beacons**           | Signed merkle root announcements — periodic commitment over content sets     |
-| **Countersignatures** | Witness attestation — third-party signatures over existing chain operations  |
-| **Merkle trees**      | SHA-256 binary trees over content IDs — inclusion proofs for beacon roots    |
-
-The crypto core is the trust boundary — everything below it is cryptographically verified. Documents are flat content objects, content-addressed directly: `documentCID = CID(dagCborCanonicalEncode(contentObject))`. What goes inside the content object is application-defined — see the [DFOS Content Model](https://protocol.dfos.com/content-model) for the standard schema library.
-
-### Crypto Core: Two Chain Types
-
-|                | Identity Chain             | Content Chain                    |
-| -------------- | -------------------------- | -------------------------------- |
-| Commits to     | Key sets (embedded)        | Documents (by CID reference)     |
-| Identifier     | `did:dfos:<hash>`          | `<hash>` (bare)                  |
-| Operations     | create, update, delete     | create, update, delete           |
-| JWS typ        | `did:dfos:identity-op`     | `did:dfos:content-op`            |
-| Self-sovereign | Yes (signs own operations) | No (signed by external identity) |
-
-Both chains are signed linked lists of state commitments. Identity chains embed their state (key sets). Content chains reference their state via `documentCID` — a content-addressed pointer to a flat content object.
-
-### Addressing
-
-Three addressing modes, self-describing by format:
-
-| Thing                 | Form                     | Example                           |
-| --------------------- | ------------------------ | --------------------------------- |
-| Operation or document | CID (dag-cbor + SHA-256) | `bafyrei...` (base32lower)        |
-| Content chain         | contentId (22-char hash) | `a82z92a3hndk6c97thcrn8`          |
-| Identity chain        | DID                      | `did:dfos:e3vvtck42d4eacdnzvtrn6` |
-
-CIDs are specific immutable artifacts — a pointer to an exact operation or document. Content IDs are living content chain entities — the 22-char bare hash derived from the genesis CID. DIDs are living identity chain entities.
-
-Operations and documents are CIDs — standard IPLD content addresses. Content chains and identity chains use derived identifiers — `customAlpha(SHA-256(genesis CID bytes))`. Same derivation for both. Identity chains prepend `did:dfos:` (W3C DID spec). Content identifiers are bare — just the 22-char hash, no prefix.
-
-Application code may add prefixes for routing (e.g., `post_xxxx`) — these are strippable semantic sugar, not part of the protocol identifier.
-
----
-
-## Protocol Rules
-
-### Commitment Scheme
-
-Both operations and documents are content-addressed via **CID** (`dagCborCanonicalEncode(payload)` → SHA-256 → CIDv1). Operations are additionally signed via **JWS**.
-
-| Representation | Encoding                                                                                                       | Purpose                                                       |
-| -------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| CID            | `dagCborCanonicalEncode(payload)` → SHA-256 → CIDv1                                                            | Deterministic content addressing for operations and documents |
-| JWS            | `base64url(JSON.stringify(header))` + `.` + `base64url(JSON.stringify(payload))` → EdDSA signature covers both | Signature verification for operations                         |
-
-CID uses [dag-cbor canonical encoding](https://ipld.io/specs/codecs/dag-cbor/spec/) for determinism — given the same logical payload, the CID MUST be identical regardless of implementation language or platform. JWS uses standard JSON for library interoperability. The dag-cbor hex test vectors in this document allow byte-level verification.
-
-### Chain Validity
-
-A valid chain is a **linear sequence** of operations. Each operation (after genesis) links to its predecessor via `previousOperationCID`. The chain provides structural ordering independent of timestamps.
-
-**Forks are invalid at the protocol level.** Two operations referencing the same `previousOperationCID` constitute a fork. The protocol does not define fork resolution — this is application-defined (e.g., longest chain, first-seen, advisory locks).
-
-**Timestamp ordering**: `createdAt` SHOULD be strictly increasing within a chain. Implementations SHOULD reject operations with non-increasing timestamps as a sanity check against replayed or mis-ordered operations. However, the chain link (CID reference) is the authoritative ordering mechanism, not the timestamp. Implementations MAY relax timestamp ordering in constrained environments where clock synchronization is impractical.
-
-### Identity Chain Signer Validity
-
-An identity chain operation is valid only if the signing key was a **controller key in the immediately prior state**. For genesis operations, the signing key MUST be one of the controller keys declared in that same operation — this is the bootstrap: the genesis operation introduces and simultaneously authorizes its own keys.
-
-This is a self-sovereign invariant: the identity chain defines its own valid signers via `controllerKeys`, and the protocol enforces this. No external authority is consulted.
-
-### Content Chain Signer Model
-
-Content chain verification requires a **valid EdDSA signature** and delegates key resolution to the caller. The `kid` in each operation's JWS header is a DID URL (`did:dfos:<id>#<keyId>`). The verifier calls `resolveKey(kid)` to obtain the raw Ed25519 public key bytes for that key on that identity. How the resolver obtains and validates the identity's key state is application-defined.
-
-**Creator sovereignty**: The DID that signs the genesis (create) operation is the **chain creator** and permanently owns the chain. The creator can sign subsequent operations directly — no credential needed. Other DIDs require a **DFOSContentWrite** VC-JWT credential in the operation's `authorization` field, issued by the creator DID. See [Credentials](#credentials) for the VC-JWT format.
-
-**Signer-payload consistency**: The `kid` DID in the JWS header MUST match the `did` field in the content operation payload. This enables discrimination between author operations and countersignatures — if the kid DID differs from the payload `did`, it is a countersignature (witness attestation), not a chain operation.
-
-**What the protocol enforces:**
-
-- The EdDSA signature on each operation is valid against the key returned by `resolveKey(kid)`
-- Chain integrity (CID links, timestamp ordering, terminal state)
-- The `kid` DID matches the payload `did` for chain operations
-- Creator-sovereignty authorization (when `enforceAuthorization` is enabled): non-creator signers must present a valid DFOSContentWrite VC-JWT issued by the creator
-
-**What the protocol does NOT enforce (application concerns):**
-
-- Which key role (auth, assert, controller) the signing key must have
-- Ownership or attribution semantics beyond creator sovereignty
-
-### Terminal States and Special Operations
-
-**`delete` is the only terminal state.** No valid operations may follow a delete. An implementation MUST reject any operation after a delete. Delete prevents future operations but does NOT remove data — the complete chain remains intact for verification. Data removal is an application concern.
-
-**Controller key requirement:** `update` operations on identity chains MUST include at least one controller key. If decommissioning is intended, `delete` is the correct terminal operation.
-
-**Content-null:** An `update` on a content chain with `documentCID: null` means the content exists but its document is cleared. The chain continues — a subsequent update can set content again.
-
-### `typ` Header
-
-The JWS `typ` header uses protocol-specific values (not IANA media types):
-
-| `typ` value            | Usage                                         |
-| ---------------------- | --------------------------------------------- |
-| `did:dfos:identity-op` | Identity chain operations                     |
-| `did:dfos:content-op`  | Content chain operations                      |
-| `did:dfos:beacon`      | Beacon announcements                          |
-| `JWT`                  | Auth tokens (DID-signed relay authentication) |
-| `vc+jwt`               | VC-JWT credentials (W3C VC Data Model v2)     |
-
-Protocol-specific `typ` values are non-standard per JOSE convention, documented intentionally. `JWT` and `vc+jwt` follow IANA conventions. The `typ` header aids routing but is not security-critical. Implementations SHOULD validate it but MUST NOT rely on it for security decisions.
-
-### Operation Field Limits
-
-The protocol defines maximum sizes for all operation fields as abuse-prevention ceilings. Implementations MUST reject operations that exceed these bounds. Implementations MAY impose stricter limits.
-
-| Field                                        | Max       | Rationale                              |
-| -------------------------------------------- | --------- | -------------------------------------- |
-| `did`                                        | 256 chars | ~8× typical `did:dfos:` (~31 chars)    |
-| `key.id`                                     | 64 chars  | ~3× typical key ID (`key_` + 22 chars) |
-| `key.publicKeyMultibase`                     | 128 chars | ~2× Ed25519 multikey (~50 chars)       |
-| `authKeys` / `assertKeys` / `controllerKeys` | 16 items  | Generous for key rotation              |
-| `previousOperationCID`                       | 256 chars | ~4× typical CIDv1 (~60 chars)          |
-| `documentCID`                                | 256 chars | Same as above                          |
-| `note`                                       | 256 chars | Short annotation, not prose            |
-
-These limits are enforced by the Zod schemas in `src/chain/schemas.ts`. Any implementation parsing operations MUST reject values exceeding these bounds.
-
-The protocol does NOT limit:
-
-- **Document content size** — the protocol commits to a CID, not the document. Document size limits are application/registry concerns.
-- **Chain length** — no maximum operations per chain.
-- **Number of chains per identity** — application scaling concern.
-
----
-
-## Standards and Dependencies
-
-| Component           | Standard / Library                                                         |
-| ------------------- | -------------------------------------------------------------------------- |
-| Key generation      | Ed25519 (RFC 8032) via `@noble/curves/ed25519`                             |
-| Signature algorithm | EdDSA over Ed25519 (pure, no prehash — Ed25519 handles SHA-512 internally) |
-| Key encoding        | W3C Multikey (multicodec `0xed01` + base58btc multibase)                   |
-| Signed envelopes    | JWS Compact Serialization (RFC 7515) with `alg: "EdDSA"`                   |
-| Content addressing  | CIDv1 with dag-cbor codec (`0x71`) + SHA-256 multihash (`0x12`)            |
-| ID encoding         | SHA-256 → custom 19-char alphabet, 22 characters                           |
-
-### ID Alphabet
-
-```
-Alphabet: 2346789acdefhknrtvz  (19 characters)
-Length:   22 characters
-Entropy:  ~93.4 bits (19^22)
-```
-
-Process: `SHA-256(input) → for each of first 22 bytes: alphabet[byte % 19]`. The modulo introduces a ~0.3% bias (256 is not evenly divisible by 19) — not security-relevant for identifiers.
-
-DIDs: `did:dfos:` + 22-char ID derived from `SHA-256(genesis CID raw bytes)`
-Key IDs: `key_` + 22-char ID. Convention: derive from public key hash (`key_` + `customAlpha(SHA-256(publicKey))`), making key IDs deterministic and verifiable. Not a protocol requirement — key IDs can be any string.
-
-### Multikey Encoding (W3C Multikey for Ed25519)
-
-```
-Encode:
-  1. Take 32-byte Ed25519 public key
-  2. Prepend multicodec varint prefix [0xed, 0x01] (unsigned varint for 0xed = 237 = ed25519-pub)
-  3. Base58btc encode the 34-byte result
-  4. Prepend 'z' multibase prefix
-  → "z6Mk..."
-
-Decode:
-  1. Strip 'z' multibase prefix
-  2. Base58btc decode → 34 bytes
-  3. First 2 bytes must be [0xed, 0x01] (ed25519-pub multicodec varint)
-  4. Remaining 32 bytes = raw Ed25519 public key
-```
-
-**Worked example:**
-
-```
-Public key (hex):     ba421e272fad4f941c221e47f87d9253bdc04f7d4ad2625ae667ab9f0688ce32
-Prefix + key (hex):   ed01 ba421e272fad4f941c221e47f87d9253bdc04f7d4ad2625ae667ab9f0688ce32
-Base58btc + 'z':      z6MkrzLMNwoJSV4P3YccWcbtk8vd9LtgMKnLeaDLUqLuASjb
-```
-
-Note: `[0xed, 0x01]` is the unsigned varint encoding of 237 (`0xed`). Since `0xed > 0x7f`, it requires two bytes in varint format: `0xed` (low 7 bits + continuation bit) then `0x01` (high bits). This is NOT big-endian `[0x00, 0xed]`.
-
-### CID Construction (dag-cbor + SHA-256)
-
-```
-1. JSON payload → dag-cbor canonical encoding → CBOR bytes
-2. SHA-256(CBOR bytes) → 32-byte hash
-3. Construct CIDv1:
-   - Version: 1 (varint: 0x01)
-   - Codec: dag-cbor (varint: 0x71)
-   - Multihash: SHA-256 (function: 0x12, length: 0x20, digest: 32 bytes)
-4. CID binary = [0x01, 0x71, 0x12, 0x20, ...32 hash bytes]
-5. Base32lower multibase encode → "bafyrei..."
-```
-
-dag-cbor canonical ordering: map keys sorted by encoded byte length first, then lexicographic. Strings to CBOR text strings. Null to CBOR null. Arrays to CBOR arrays. Objects to CBOR maps with sorted keys.
-
-#### Number Encoding (Critical for CID Determinism)
-
-JSON has a single number type (IEEE 754 double). CBOR has distinct integer and floating-point types with different byte encodings. This difference is the most common source of CID divergence across implementations.
-
-**Rule: JSON numbers that are mathematically integers (no fractional part) MUST be encoded as CBOR integers (major type 0/1), never as CBOR floats.** This is consistent with the [IPLD data model](https://ipld.io/docs/data-model/) integer/float distinction and required by the [dag-cbor codec spec](https://ipld.io/specs/codecs/dag-cbor/spec/).
-
-Why this matters: CBOR integer `1` encodes as a single byte `0x01`. CBOR float `1.0` encodes as three bytes `0xf9 0x3c 0x00` (half-precision). Same logical value, different bytes, different SHA-256, different CID. An implementation that encodes `version: 1` as a float will produce a valid CBOR document but a wrong CID — silent, undetectable without cross-implementation testing.
-
-**Common trap**: Languages that decode JSON into untyped maps (Go's `map[string]any`, Python's `dict`, etc.) typically represent all JSON numbers as floating-point. When this decoded value is then CBOR-encoded, it becomes a CBOR float instead of an integer. Implementations MUST normalize number types after JSON deserialization and before CBOR encoding.
-
-**Integer bounds**: dag-cbor integers are limited to the range `[-(2^64), 2^64 - 1]`. All integer fields in the current protocol (`version: 1`) are small positive values. Future protocol extensions SHOULD NOT introduce integer fields that exceed JSON's safe integer range (`2^53 - 1`), as JSON serialization would lose precision.
-
-**Verification test vector** — encodes `{"version": 1, "type": "test"}`:
-
-```
-Integer encoding (CORRECT):
-  CBOR: a2647479706564746573746776657273696f6e01
-  CID:  bafyreihp6omsp6icc6ee63ox2ovsaxm6s7ikd2a7k5eh2qz2qd5soh5bsa
-
-Float encoding (WRONG — different bytes, different CID):
-  CBOR: a2647479706564746573746776657273696f6ef93c00
-  CID:  bafyreiawbms4476m5jlrmqtyvtwe5ta3eo2bh7mdprtomfgfype7j57o4q
-```
-
-If your implementation produces the float CID, your number encoding is incorrect. The byte at offset 19 in the CBOR output is the discriminator: `0x01` = correct (CBOR integer), `0xf9` = wrong (CBOR float16 header).
-
-**Worked example (genesis identity operation):**
-
-```
-CBOR bytes (441 bytes, hex):
-a66474797065666372656174656776657273696f6e0168617574684b65797381a3626964781a6b
-65795f72396576333466766332337a393939766561616674386474797065684d756c74696b6579
-727075626c69634b65794d756c74696261736578307a364d6b727a4c4d4e776f4a535634503359
-6363576362746b387664394c74674d4b6e4c6561444c55714c7541536a62696372656174656441
-747818323032362d30332d30375430303a30303a30302e3030305a6a6173736572744b65797381
-a3626964781a6b65795f72396576333466766332337a393939766561616674386474797065684d
-756c74696b6579727075626c69634b65794d756c74696261736578307a364d6b727a4c4d4e776f
-4a5356345033596363576362746b387664394c74674d4b6e4c6561444c55714c7541536a626e63
-6f6e74726f6c6c65724b65797381a3626964781a6b65795f72396576333466766332337a393939
-766561616674386474797065684d756c74696b6579727075626c69634b65794d756c7469626173
-6578307a364d6b727a4c4d4e776f4a5356345033596363576362746b387664394c74674d4b6e4c
-6561444c55714c7541536a62
-
-CID bytes (hex): 01711220206a5e6140a5114f1e49f3ca4b339fb2cb8e70bbb34968b23156fd0e3237b486
-CID string:      bafyreibanjpgcqffcfhr4sptzjfthh5szohhbo5tjfulemkw7uhden5uqy
-```
-
-### DID Derivation (worked example)
-
-```
-Input:  CID bytes (hex) = 01711220206a5e6140a5114f1e49f3ca4b339fb2cb8e70bbb34968b23156fd0e3237b486
-Step 1: SHA-256(CID bytes) = 4360cfbcbbb3f1614c8e02dbfe8d55935e1195cd2129820ab8aef94bde12ea8a
-Step 2: Take first 22 bytes: 43 60 cf bc bb b3 f1 61 4c 8e 02 db fe 8d 55 93 5e 11 95 cd 21 29
-Step 3: For each byte, alphabet[byte % 19]:
-        43=67  → 67%19=10  → 'e'
-        60=96  → 96%19=1   → '3'
-        cf=207 → 207%19=17 → 'v'
-        bc=188 → 188%19=17 → 'v'
-        ...
-Result: e3vvtck42d4eacdnzvtrn6
-DID:    did:dfos:e3vvtck42d4eacdnzvtrn6
-```
-
----
-
-## Operation Schemas
-
-### Identity Operations
-
-```typescript
-// Genesis — starts the identity chain
-{ version: 1, type: "create",
-  authKeys: MultikeyPublicKey[],
-  assertKeys: MultikeyPublicKey[],
-  controllerKeys: MultikeyPublicKey[],   // must have at least one
-  createdAt: string }                     // ISO 8601, ms precision, UTC
-
-// Key rotation / modification
-{ version: 1, type: "update",
-  previousOperationCID: string,                    // CID of previous operation
-  authKeys: MultikeyPublicKey[],
-  assertKeys: MultikeyPublicKey[],
-  controllerKeys: MultikeyPublicKey[],   // must have at least one
-  createdAt: string }
-
-// Permanent destruction
-{ version: 1, type: "delete",
-  previousOperationCID: string,
-  createdAt: string }
-```
-
-### Content Operations
-
-```typescript
-// Genesis — starts the content chain, commits initial document
-{ version: 1, type: "create",
-  did: string,                           // author DID, committed to by CID
-  documentCID: string,                   // CID of flat content object
-  baseDocumentCID: string | null,        // edit lineage — CID of prior document version
-  createdAt: string,
-  note: string | null }
-
-// Content change (null documentCID = clear content)
-{ version: 1, type: "update",
-  did: string,                           // author DID
-  previousOperationCID: string,
-  documentCID: string | null,
-  baseDocumentCID: string | null,
-  createdAt: string,
-  note: string | null,
-  authorization?: string }               // VC-JWT for delegated operations
-
-// Permanent destruction
-{ version: 1, type: "delete",
-  did: string,                           // author DID
-  previousOperationCID: string,
-  createdAt: string,
-  note: string | null,
-  authorization?: string }               // VC-JWT for delegated operations
-```
-
-### MultikeyPublicKey
-
-```typescript
-{ id: string,                             // e.g. "key_r9ev34fvc23z999veaaft8"
-  type: "Multikey",                       // literal discriminator
-  publicKeyMultibase: string }            // e.g. "z6MkrzLMNwoJSV4P3YccWcbtk8vd9LtgMKnLeaDLUqLuASjb"
-```
-
----
-
-## JWS Envelope Format
-
-### Signing
-
-```
-signingInput = base64url(JSON.stringify(header)) + "." + base64url(JSON.stringify(payload))
-signature = ed25519.sign(UTF8_bytes(signingInput), privateKey)
-token = signingInput + "." + base64url(signature)
-```
-
-### kid Rules
-
-| Context                   | kid format  | Example                      |
-| ------------------------- | ----------- | ---------------------------- |
-| Identity create (genesis) | Bare key ID | `key_r9ev34fvc23z999veaaft8` |
-| Identity update/delete    | DID URL     | See below                    |
-| All content ops           | DID URL     | See below                    |
-
-DID URL examples:
-
-```
-did:dfos:e3vvtck42d4eacdnzvtrn6#key_r9ev34fvc23z999veaaft8
-did:dfos:e3vvtck42d4eacdnzvtrn6#key_ez9a874tckr3dv933d3ckd
-```
-
-### `cid` Header
-
-Every operation JWS (identity-op and content-op) includes a `cid` field in the protected header. This is the CIDv1 string of the operation payload, derived from `dagCborCanonicalEncode(payload) → SHA-256 → CIDv1 → base32lower`. The `cid` is computed before signing and embedded in the protected header, so it is covered by the EdDSA signature.
-
-**Signing order:**
-
-1. Construct the operation payload
-2. Derive the operation CID: `dagCborCanonicalEncode(payload) → CIDv1`
-3. Build the protected header including `cid`
-4. Sign: `ed25519.sign(UTF8(base64url(header) + "." + base64url(payload)), privateKey)`
-
-**Verification rule:** After verifying the JWS signature and deriving the operation CID from the parsed payload, implementations MUST reject operations where:
-
-- `header.cid` is missing
-- `header.cid` does not match the derived CID
-
-A CID mismatch between header and derived value immediately surfaces dag-cbor encoding disagreements across implementations.
-
-Note: JWT auth tokens and VC-JWT credentials do NOT include a `cid` header — this field is specific to operation JWS tokens and beacons.
-
-### CID Derivation
-
-```
-operation CID = dagCborCanonicalEncode(operation_payload) → SHA-256 → CIDv1 → base32lower string
-```
-
-The CID is derived from the JWS payload (the unsigned operation JSON), NOT from the JWS token itself.
-
-### DID Derivation
-
-```
-DID = "did:dfos:" + idEncode(SHA-256(genesis_CID_raw_bytes))
-```
-
-Where `idEncode` is the 19-char alphabet encoding described above.
-
----
-
-## Credentials
-
-Two credential types handle authentication and authorization. Both are DID-signed JWTs using Ed25519 (`alg: "EdDSA"`).
-
-### Auth Tokens (Relay Authentication)
-
-A DID-signed JWT proving the caller controls a DID. Short-lived, scoped to a specific relay via the `aud` (audience) claim. Used for relay AuthN — establishing identity before making requests.
-
-**JWT Header:**
-
-```json
-{
-  "alg": "EdDSA",
-  "typ": "JWT",
-  "kid": "did:dfos:e3vvtck42d4eacdnzvtrn6#key_r9ev34fvc23z999veaaft8"
-}
-```
-
-**JWT Payload:**
-
-```json
-{
-  "iss": "did:dfos:e3vvtck42d4eacdnzvtrn6",
-  "sub": "did:dfos:e3vvtck42d4eacdnzvtrn6",
-  "aud": "relay.example.com",
-  "exp": 1772845200,
-  "iat": 1772841600
-}
-```
-
-| Field | Type   | Description                                                |
-| ----- | ------ | ---------------------------------------------------------- |
-| `iss` | string | DID proving identity (the signer)                          |
-| `sub` | string | Same as `iss` for auth tokens                              |
-| `aud` | string | Target relay hostname (prevents cross-relay replay)        |
-| `exp` | number | Expiration — unix seconds (short-lived, typically minutes) |
-| `iat` | number | Issued-at — unix seconds                                   |
-
-**Verification:** Standard JWT verification — EdDSA signature check, temporal validity (`iat` must not be in the future, `exp` must be after current time), audience match. The `kid` MUST be a DID URL (`did:dfos:xxx#key_yyy`) and the `kid` DID MUST match `iss`.
-
-Auth tokens do NOT include a `cid` header — they are ephemeral session tokens, not content-addressed artifacts.
-
-### VC-JWT Credentials (Authorization)
-
-W3C Verifiable Credential Data Model v2 credentials encoded as JWT (`typ: "vc+jwt"`). Two credential types:
-
-| Credential Type    | Purpose                                                      |
-| ------------------ | ------------------------------------------------------------ |
-| `DFOSContentWrite` | Authorize extending a content chain (embedded in operations) |
-| `DFOSContentRead`  | Authorize reading content plane data (presented to relay)    |
-
-**VC-JWT Header:**
-
-```json
-{
-  "alg": "EdDSA",
-  "typ": "vc+jwt",
-  "kid": "did:dfos:e3vvtck42d4eacdnzvtrn6#key_r9ev34fvc23z999veaaft8"
-}
-```
-
-**VC-JWT Payload:**
-
-```json
-{
-  "iss": "did:dfos:e3vvtck42d4eacdnzvtrn6",
-  "sub": "did:dfos:nzkf838efr424433rn2rzk",
-  "exp": 1798761600,
-  "iat": 1772841600,
-  "vc": {
-    "@context": ["https://www.w3.org/ns/credentials/v2"],
-    "type": ["VerifiableCredential", "DFOSContentWrite"],
-    "credentialSubject": {}
-  }
-}
-```
-
-| Field                  | Type     | Description                                              |
-| ---------------------- | -------- | -------------------------------------------------------- |
-| `iss`                  | string   | DID granting the credential (content creator/controller) |
-| `sub`                  | string   | DID receiving the credential (collaborator/reader)       |
-| `exp`                  | number   | Expiration — unix seconds                                |
-| `iat`                  | number   | Issued-at — unix seconds                                 |
-| `vc.@context`          | string[] | Must be `["https://www.w3.org/ns/credentials/v2"]`       |
-| `vc.type`              | string[] | `["VerifiableCredential", "<DFOSCredentialType>"]`       |
-| `vc.credentialSubject` | object   | Optional narrowing — see scope narrowing below           |
-
-**Scope narrowing:** The `credentialSubject` object may contain a `contentId` field. If absent, the credential grants broad access to all content by the issuer. If present, the credential is narrowed to the specific content chain.
-
-```json
-// Broad — all content by this DID
-{ "credentialSubject": {} }
-
-// Narrow — specific content chain only
-{ "credentialSubject": { "contentId": "a82z92a3hndk6c97thcrn8" } }
-```
-
-**Verification:** EdDSA signature check, temporal validity (`iat` must not be in the future, `exp` must be after current time — using operation `createdAt` for chain-embedded VCs, wall clock for relay-presented VCs), `kid` DID URL format, `kid` DID matches `iss`, payload structure via Zod schema. Optionally verify `sub` and credential type match expectations.
-
-### Content Chain Authorization
-
-When `enforceAuthorization` is enabled on content chain verification:
-
-1. **Genesis operation**: The signer is the chain creator, always authorized
-2. **Creator signs subsequent ops**: Authorized directly — no credential needed
-3. **Different DID signs**: Must include an `authorization` field containing a valid `DFOSContentWrite` VC-JWT where:
-   - `iss` matches the chain creator DID
-   - `sub` matches the signing DID
-   - The credential is temporally valid (`iat <= op.createdAt < exp`, not wall clock)
-   - If `contentId` is present in `credentialSubject`, it must match this chain's contentId
-   - The credential type is `DFOSContentWrite`
-
-The `authorization` field is available on `update` and `delete` content operations. It is absent for creator-signed operations.
-
----
-
-## Beacons
-
-A beacon is a signed announcement of a merkle root — a periodic commitment over a set of content IDs. Beacons are floating signed artifacts, not chained. They provide a compact, verifiable snapshot of an identity's content set at a point in time.
-
-### Beacon Payload
-
-```json
-{
-  "version": 1,
-  "type": "beacon",
-  "did": "did:dfos:e3vvtck42d4eacdnzvtrn6",
-  "merkleRoot": "7e80d4780f454e0fca0b090d8c646f572b49354f54154531606105aad2fda28e",
-  "createdAt": "2026-03-07T00:05:00.000Z"
-}
-```
-
-| Field        | Type   | Description                                             |
-| ------------ | ------ | ------------------------------------------------------- |
-| `version`    | 1      | Protocol version                                        |
-| `type`       | string | Literal `"beacon"`                                      |
-| `did`        | string | DID of the identity publishing the beacon               |
-| `merkleRoot` | string | Hex-encoded SHA-256 root (64 chars, `/^[0-9a-f]{64}$/`) |
-| `createdAt`  | string | ISO 8601 timestamp                                      |
-
-### Beacon JWS Header
-
-```json
-{
-  "alg": "EdDSA",
-  "typ": "did:dfos:beacon",
-  "kid": "did:dfos:e3vvtck42d4eacdnzvtrn6#key_r9ev34fvc23z999veaaft8",
-  "cid": "bafyreihholuui7s7ns74iem6ahfxsb472hwogbqd32yrrp5fztc3kxa5qu"
-}
-```
-
-### Worked Example: Beacon
-
-Using the reference identity (`did:dfos:e3vvtck42d4eacdnzvtrn6`) and key 1 from the identity chain examples. The beacon commits to a merkle root over 5 content IDs (see Merkle Tree worked example below).
-
-**Beacon CID** (dag-cbor canonical encode → CIDv1):
-
-```
-bafyreihholuui7s7ns74iem6ahfxsb472hwogbqd32yrrp5fztc3kxa5qu
-```
-
-**Controller JWS** (key 1 signs):
-
-```
-kid:          did:dfos:e3vvtck42d4eacdnzvtrn6#key_r9ev34fvc23z999veaaft8
-typ:          did:dfos:beacon
-cid:          bafyreihholuui7s7ns74iem6ahfxsb472hwogbqd32yrrp5fztc3kxa5qu
-```
-
-**Witness countersignature** (key 2 signs the same payload — same CID, different kid):
-
-```
-kid:          did:dfos:e3vvtck42d4eacdnzvtrn6#key_ez9a874tckr3dv933d3ckd
-typ:          did:dfos:beacon
-cid:          bafyreihholuui7s7ns74iem6ahfxsb472hwogbqd32yrrp5fztc3kxa5qu
-```
-
-Both JWS tokens commit to identical bytes (same CID). The controller/witness distinction is determined at verification time by comparing the `kid` DID to the payload `did`.
-
-Full JWS tokens are in [`examples/beacon.json`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/examples/beacon.json).
-
-### Beacon Semantics
-
-Beacons are not chained — there is no `previousOperationCID`. For a given DID, the latest beacon with a strictly-greater `createdAt` timestamp wins. Beacons replace, not accumulate.
-
-**Clock skew tolerance**: Implementations MUST reject beacons with a `createdAt` more than 5 minutes in the future relative to the verifier's clock. This prevents pre-dating attacks while accommodating reasonable clock drift.
-
-**merkleRoot**: A hex-encoded SHA-256 hash (64 characters). This is a commitment, not a CID — it uses raw SHA-256, not dag-cbor encoding. See the Merkle Tree section below for construction. An empty content set produces a `null` merkle root (no beacon needed).
-
----
-
-## Merkle Trees
-
-Beacons commit to a set of content IDs via a pure SHA-256 binary Merkle tree. The tree has no dag-cbor dependency — it uses only SHA-256 over raw bytes.
-
-### Construction
-
-1. **Collect** all content IDs (22-char bare hashes) in the set
-2. **Sort** content IDs lexicographically (UTF-8 byte order)
-3. **Hash leaves**: for each content ID, `SHA-256(UTF-8(contentId))` → 32-byte leaf hash
-4. **Build tree**: recursively pair adjacent hashes. For each pair, `SHA-256(left || right)` → 32 bytes. If a level has an odd number of nodes, the last node is promoted to the next level unpaired.
-5. **Root**: the final 32-byte hash, hex-encoded to a 64-character string
-
-An empty set of content IDs produces a `null` root. A single content ID produces a root equal to `hex(SHA-256(UTF-8(contentId)))`.
-
-### Worked Example: Merkle Tree
-
-5 content IDs: `["alpha", "bravo", "charlie", "delta", "echo"]`
-
-Already sorted lexicographically. Hash each leaf:
-
-```
-alpha   → SHA-256("alpha")   → 8ed3f6ad685b959ead7022518e1af76cd816f8e8ec7ccdda1ed4018e8f2223f8
-bravo   → SHA-256("bravo")   → 4f4a9410ffcdf895c4adb880659e9b5c0dd1f23a30790684340b3eaacb045398
-charlie → SHA-256("charlie") → 36ef585cd42d49706cd2827a77d86c91bfdaf87a3f22b8f0e0308bd2c16cf85f
-delta   → SHA-256("delta")   → 18ac3e7343f016890c510e93f935261169d9e3f565436429830faf0934f4f8e4
-echo    → SHA-256("echo")    → 092c79e8f80e559e404bcf660c48f3522b67aba9ff1484b0367e1a4ddef7431d
-```
-
-Build tree bottom-up, pairing left-to-right. Odd nodes promote unpaired:
-
-```
-Level 0 (leaves):    [alpha]  [bravo]  [charlie]  [delta]  [echo]
-Level 1:             [alpha‖bravo]     [charlie‖delta]     [echo]  ← promoted
-Level 2:             [L1-left‖L1-mid]                      [echo]  ← promoted
-Level 3 (root):      [L2-left‖echo]
-```
-
-Interior hashes:
-
-```
-SHA-256(alpha‖bravo)          → 90d39555bb3c223e12f5a375c3011d2462fe2e1e36b8416a0b623d5831a9b4f3
-SHA-256(charlie‖delta)        → 6b55e77bef32937d9ccce2bd4b18127b0483f0be8e5b63c30bcc2b0d09f7dd44
-SHA-256(alpha‖bravo ‖ charlie‖delta) → 23c83cb862e3b6a86eb2dfa0ea8ba0edcf1c3f3b8f14abc5eb9d72eab2edc2f7
-```
-
-**Root** (level 3):
-
-```
-SHA-256(23c83c...edc2f7 ‖ 092c79...f7431d) → 7e80d4780f454e0fca0b090d8c646f572b49354f54154531606105aad2fda28e
-```
-
-### Inclusion Proofs
-
-A Merkle inclusion proof demonstrates that a specific content ID is part of the committed set without revealing the full set. The proof consists of sibling hashes along the path from leaf to root, plus a direction (left/right) for each step.
-
-### Worked Example: Inclusion Proof for "charlie"
-
-Starting from the leaf hash of "charlie" (`36ef58...`), walk to the root using sibling hashes:
-
-```
-Step 1: charlie (index 2) paired with delta (index 3)
-        sibling: 4f4a9410...045398 (delta leaf)  position: right
-        → SHA-256(charlie ‖ delta) → 6b55e77b...f7dd44
-
-Step 2: charlie‖delta paired with alpha‖bravo
-        sibling: 90d39555...a9b4f3 (alpha‖bravo) position: left
-        → SHA-256(alpha‖bravo ‖ charlie‖delta) → 23c83cb8...edc2f7
-
-Step 3: L2-left paired with echo (promoted)
-        sibling: 092c79e8...f7431d (echo leaf)   position: right
-        → SHA-256(L2-left ‖ echo) → 7e80d478...fda28e ✓ matches root
-```
-
-Proof path (from [`examples/merkle-tree.json`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/examples/merkle-tree.json)):
-
-```json
-[
-  {
-    "hash": "4f4a9410ffcdf895c4adb880659e9b5c0dd1f23a30790684340b3eaacb045398",
-    "position": "right"
-  },
-  {
-    "hash": "90d39555bb3c223e12f5a375c3011d2462fe2e1e36b8416a0b623d5831a9b4f3",
-    "position": "left"
-  },
-  {
-    "hash": "092c79e8f80e559e404bcf660c48f3522b67aba9ff1484b0367e1a4ddef7431d",
-    "position": "right"
-  }
-]
-```
-
----
-
-## Countersignatures
-
-A countersignature is a witness attestation — a third-party identity signing the same CID-committed bytes as an existing chain operation. Countersignatures use the same JWS format and `typ` (`did:dfos:content-op`) as the original operation.
-
-### Discrimination Rule
-
-The protocol distinguishes author operations from countersignatures by comparing the `kid` DID in the JWS header to the `did` field in the operation payload:
-
-- **`kid` DID === payload `did`** → author operation (chain operation)
-- **`kid` DID !== payload `did`** → witness countersignature
-
-### Semantics
-
-A countersignature proves that a witness identity has seen and attested to a specific operation. The witness signs the exact same payload (same CID), but with their own key. The countersignature's JWS header will contain the witness's `kid` (their DID URL), while the payload's `did` field remains the original author's DID.
-
-Countersignatures are not part of the chain — they do not have `previousOperationCID` links and do not affect chain state. They are auxiliary attestations stored alongside chain operations.
-
----
-
-## Verification
-
-### Identity Chain
-
-1. Decode each JWS, parse payload as IdentityOperation
-2. First op MUST be `type: "create"` — this is the genesis bootstrap:
-   - The controller keys declared in the genesis payload are trusted because the identity does not exist before this operation. There is no prior state to verify against.
-   - The signing key (resolved from `kid`) MUST be one of the controller keys declared in this same operation. The genesis simultaneously introduces and authorizes its own keys.
-   - Derive the operation CID via dag-cbor canonical encoding. Verify `header.cid` matches the derived CID. Derive the DID from the CID.
-3. For each subsequent op: verify `previousOperationCID` matches previous op's derived CID. Verify `createdAt` is strictly increasing (SHOULD — see Protocol Rules).
-4. Verify the chain is not in a terminal state (deleted) before applying any operation.
-5. Resolve `kid` — genesis uses bare key ID, non-genesis uses DID URL (extract DID, verify it matches the derived DID; extract key ID).
-6. Find controller key matching key ID **in the current state** (i.e., the state after all preceding operations). Decode multikey → raw Ed25519 public key.
-7. Verify EdDSA JWS signature over the signing input bytes.
-8. Apply state change: `create` initializes key state, `update` replaces key state (must have at least one controller key), `delete` marks terminal.
-
-### Content Chain
-
-1. Decode each JWS, parse payload as ContentOperation
-2. First op must be `type: "create"` — the signer is the chain creator
-3. For each subsequent op: verify `previousOperationCID` matches, verify `createdAt` increasing
-4. Derive the operation CID via dag-cbor canonical encoding. Verify `header.cid` matches the derived CID.
-5. Verify the `kid` DID matches the payload `did` field (mismatches indicate a countersignature, not a chain operation)
-6. Resolve `kid` via external key resolver (caller provides)
-7. Verify EdDSA JWS signature
-8. If `enforceAuthorization` is enabled and the signer DID differs from the chain creator: verify the `authorization` field contains a valid `DFOSContentWrite` VC-JWT issued by the creator DID, with `sub` matching the signer, not expired at `op.createdAt`, and `contentId` (if present) matching this chain
-9. Apply state change (set document, clear, or delete)
-
----
-
-## Deterministic Reference Artifacts
-
-All artifacts below are deterministic and reproducible from fixed seeds. An independent implementer can verify every value using standard Ed25519 + dag-cbor libraries. Private keys are derived from `SHA-256(UTF8("dfos-protocol-reference-key-N"))`.
-
-### Key 1 (Genesis Controller)
-
-```
-Seed:        SHA-256("dfos-protocol-reference-key-1")
-Private key: 132d4bebdb6e62359afb930fe15d756a92ad96e6b0d47619988f5a1a55272aac
-Public key:  ba421e272fad4f941c221e47f87d9253bdc04f7d4ad2625ae667ab9f0688ce32
-Multikey:    z6MkrzLMNwoJSV4P3YccWcbtk8vd9LtgMKnLeaDLUqLuASjb
-Key ID:      key_r9ev34fvc23z999veaaft8
-```
-
-### Key 2 (Rotated Controller)
-
-```
-Seed:        SHA-256("dfos-protocol-reference-key-2")
-Private key: 384f5626906db84f6a773ec46475ff2d4458e92dd4dd13fe03dbb7510f4ca2a8
-Public key:  0f350f994f94d675f04a325bd316ebedd740ca206eaaf609bdb641b5faa0f78c
-Multikey:    z6MkfUd65JrAhfdgFuMCccU9ThQvjB2fJAMUHkuuajF992gK
-Key ID:      key_ez9a874tckr3dv933d3ckd
-```
-
-### Identity Chain: Create (Genesis)
-
-Operation:
-
-```json
-{
-  "version": 1,
-  "type": "create",
-  "authKeys": [
-    {
-      "id": "key_r9ev34fvc23z999veaaft8",
-      "type": "Multikey",
-      "publicKeyMultibase": "z6MkrzLMNwoJSV4P3YccWcbtk8vd9LtgMKnLeaDLUqLuASjb"
-    }
-  ],
-  "assertKeys": [
-    {
-      "id": "key_r9ev34fvc23z999veaaft8",
-      "type": "Multikey",
-      "publicKeyMultibase": "z6MkrzLMNwoJSV4P3YccWcbtk8vd9LtgMKnLeaDLUqLuASjb"
-    }
-  ],
-  "controllerKeys": [
-    {
-      "id": "key_r9ev34fvc23z999veaaft8",
-      "type": "Multikey",
-      "publicKeyMultibase": "z6MkrzLMNwoJSV4P3YccWcbtk8vd9LtgMKnLeaDLUqLuASjb"
-    }
-  ],
-  "createdAt": "2026-03-07T00:00:00.000Z"
-}
-```
-
-JWS Header:
-
-```json
-{
-  "alg": "EdDSA",
-  "typ": "did:dfos:identity-op",
-  "kid": "key_r9ev34fvc23z999veaaft8",
-  "cid": "bafyreibanjpgcqffcfhr4sptzjfthh5szohhbo5tjfulemkw7uhden5uqy"
-}
-```
-
-JWS Signature (hex):
-
-```
-103af20cad6ebed8b1fb5edc1ee9fdb7a31a705231dab326305d502f37c3e531654ac3af31cb9ef7ba428069f709778b545b55c60a42a21d241925e2a0a2b303
-```
-
-JWS Token:
-
-```
-eyJhbGciOiJFZERTQSIsInR5cCI6ImRpZDpkZm9zOmlkZW50aXR5LW9wIiwia2lkIjoia2V5X3I5ZXYzNGZ2YzIzejk5OXZlYWFmdDgiLCJjaWQiOiJiYWZ5cmVpYmFuanBnY3FmZmNmaHI0c3B0empmdGhoNXN6b2hoYm81dGpmdWxlbWt3N3VoZGVuNXVxeSJ9.eyJ2ZXJzaW9uIjoxLCJ0eXBlIjoiY3JlYXRlIiwiYXV0aEtleXMiOlt7ImlkIjoia2V5X3I5ZXYzNGZ2YzIzejk5OXZlYWFmdDgiLCJ0eXBlIjoiTXVsdGlrZXkiLCJwdWJsaWNLZXlNdWx0aWJhc2UiOiJ6Nk1rcnpMTU53b0pTVjRQM1ljY1djYnRrOHZkOUx0Z01LbkxlYURMVXFMdUFTamIifV0sImFzc2VydEtleXMiOlt7ImlkIjoia2V5X3I5ZXYzNGZ2YzIzejk5OXZlYWFmdDgiLCJ0eXBlIjoiTXVsdGlrZXkiLCJwdWJsaWNLZXlNdWx0aWJhc2UiOiJ6Nk1rcnpMTU53b0pTVjRQM1ljY1djYnRrOHZkOUx0Z01LbkxlYURMVXFMdUFTamIifV0sImNvbnRyb2xsZXJLZXlzIjpbeyJpZCI6ImtleV9yOWV2MzRmdmMyM3o5OTF2ZWFhZnQ4IiwidHlwZSI6Ik11bHRpa2V5IiwicHVibGljS2V5TXVsdGliYXNlIjoiejZNa3J6TE1Od29KU1Y0UDNZY2NXY2J0azh2ZDlMdGdNS25MZWFETFVxTHVBU2piIn1dLCJjcmVhdGVkQXQiOiIyMDI2LTAzLTA3VDAwOjAwOjAwLjAwMFoifQ.EDryDK1uvtix-17cHun9t6MacFIx2rMmMF1QLzfD5TFlSsOvMcue97pCgGn3CXeLVFtVxgpCoh0kGSXioKKzAw
-```
-
-Operation CID:
-
-```
-bafyreibanjpgcqffcfhr4sptzjfthh5szohhbo5tjfulemkw7uhden5uqy
-```
-
-**Derived DID: `did:dfos:e3vvtck42d4eacdnzvtrn6`**
-
-### Identity Chain: Update (Key Rotation)
-
-JWS Header:
-
-```json
-{
-  "alg": "EdDSA",
-  "typ": "did:dfos:identity-op",
-  "kid": "did:dfos:e3vvtck42d4eacdnzvtrn6#key_r9ev34fvc23z999veaaft8",
-  "cid": "bafyreicym4cyiednld73smbx32szaei7xdulqn4g3ste5e2w2ulajr3oqm"
-}
-```
-
-Operation:
-
-```json
-{
-  "version": 1,
-  "type": "update",
-  "previousOperationCID": "bafyreibanjpgcqffcfhr4sptzjfthh5szohhbo5tjfulemkw7uhden5uqy",
-  "authKeys": [
-    {
-      "id": "key_ez9a874tckr3dv933d3ckd",
-      "type": "Multikey",
-      "publicKeyMultibase": "z6MkfUd65JrAhfdgFuMCccU9ThQvjB2fJAMUHkuuajF992gK"
-    }
-  ],
-  "assertKeys": [
-    {
-      "id": "key_ez9a874tckr3dv933d3ckd",
-      "type": "Multikey",
-      "publicKeyMultibase": "z6MkfUd65JrAhfdgFuMCccU9ThQvjB2fJAMUHkuuajF992gK"
-    }
-  ],
-  "controllerKeys": [
-    {
-      "id": "key_ez9a874tckr3dv933d3ckd",
-      "type": "Multikey",
-      "publicKeyMultibase": "z6MkfUd65JrAhfdgFuMCccU9ThQvjB2fJAMUHkuuajF992gK"
-    }
-  ],
-  "createdAt": "2026-03-07T00:01:00.000Z"
-}
-```
-
-JWS Signature (hex):
-
-```
-31272ea0196038ade3e505fdb45730d68bb4a382e0273886244b19e69bea881af549a800c80bf987ec1a8d086d83c20fedd2e533453895e5b6891adaf78e5c0e
-```
-
-JWS Token:
-
-```
-eyJhbGciOiJFZERTQSIsInR5cCI6ImRpZDpkZm9zOmlkZW50aXR5LW9wIiwia2lkIjoiZGlkOmRmb3M6ZTN2dnRjazQyZDRlYWNkbnp2dHJuNiNrZXlfcjlldjM0ZnZjMjN6OTk5dmVhYWZ0OCIsImNpZCI6ImJhZnlyZWljeW00Y3lpZWRubGQ3M3NtYngzMnN6YWVpN3hkdWxxbjRnM3N0ZTVlMncydWxhanIzb3FtIn0.eyJ2ZXJzaW9uIjoxLCJ0eXBlIjoidXBkYXRlIiwicHJldmlvdXNPcGVyYXRpb25DSUQiOiJiYWZ5cmVpYmFuanBnY3FmZmNmaHI0c3B0empmdGhoNXN6b2hoYm81dGpmdWxlbWt3N3VoZGVuNXVxeSIsImF1dGhLZXlzIjpbeyJpZCI6ImtleV9lejlhODc0dGNrcjNkdjkzM2QzY2tkIiwidHlwZSI6Ik11bHRpa2V5IiwicHVibGljS2V5TXVsdGliYXNlIjoiejZNa2ZVZDY1SnJBaGZkZ0Z1TUNjY1U5VGhRdmpCMmZKQU1VSGt1dWFqRjk5MmdLIn1dLCJhc3NlcnRLZXlzIjpbeyJpZCI6ImtleV9lejlhODc0dGNrcjNkdjkzM2QzY2tkIiwidHlwZSI6Ik11bHRpa2V5IiwicHVibGljS2V5TXVsdGliYXNlIjoiejZNa2ZVZDY1SnJBaGZkZ0Z1TUNjY1U5VGhRdmpCMmZKQU1VSGt1dWFqRjk5MmdLIn1dLCJjb250cm9sbGVyS2V5cyI6W3siaWQiOiJrZXlfZXo5YTg3NHRja3IzZHY5MzNkM2NrZCIsInR5cGUiOiJNdWx0aWtleSIsInB1YmxpY0tleU11bHRpYmFzZSI6Ino2TWtmVWQ2NUpyQWhmZGdGdU1DY2NVOVRoUXZqQjJmSkFNVUhrdXVhakY5OTJnSyJ9XSwiY3JlYXRlZEF0IjoiMjAyNi0wMy0wN1QwMDowMTowMC4wMDBaIn0.MScuoBlgOK3j5QX9tFcw1ou0o4LgJziGJEsZ5pvqiBr1SagAyAv5h-wajQhtg8IP7dLlM0U4leW2iRra945cDg
-```
-
-Operation CID:
-
-```
-bafyreicym4cyiednld73smbx32szaei7xdulqn4g3ste5e2w2ulajr3oqm
-```
-
-Post-rotation: DID unchanged (`did:dfos:e3vvtck42d4eacdnzvtrn6`), controller rotated to `key_ez9a874tckr3dv933d3ckd`.
-
-### Content Chain: Document + Create
-
-Document (flat content object):
-
-```json
-{
-  "$schema": "https://schemas.dfos.com/post/v1",
-  "format": "short-post",
-  "title": "Hello World",
-  "body": "First post on the protocol.",
-  "createdByDID": "did:dfos:e3vvtck42d4eacdnzvtrn6"
-}
-```
-
-Document CID:
-
-```
-bafyreihzwuoupfg3dxip6xmgzmxsywyii2jeoxxzbgx3zxm2in7knoi3g4
-```
-
-Content Create JWS Header:
-
-```json
-{
-  "alg": "EdDSA",
-  "typ": "did:dfos:content-op",
-  "kid": "did:dfos:e3vvtck42d4eacdnzvtrn6#key_ez9a874tckr3dv933d3ckd",
-  "cid": "bafyreiaedhjq64aajpwociahl5w37j6uoxr5mojoq5dnah6fpvxr5d4lxu"
-}
-```
-
-Content Create Payload:
-
-```json
-{
-  "version": 1,
-  "type": "create",
-  "did": "did:dfos:e3vvtck42d4eacdnzvtrn6",
-  "documentCID": "bafyreihzwuoupfg3dxip6xmgzmxsywyii2jeoxxzbgx3zxm2in7knoi3g4",
-  "baseDocumentCID": null,
-  "createdAt": "2026-03-07T00:02:00.000Z",
-  "note": null
-}
-```
-
-Content Create JWS Signature (hex):
-
-```
-46feaf973e4c7ebc2a0d4ad25481ace197de05b91051205c5e1c7067a85fb9d4abe4cc61625d3c853a8b0ce0345b534c8cdd07b34216f635d3c0bc0fd5d30306
-```
-
-Content Create JWS Token:
-
-```
-eyJhbGciOiJFZERTQSIsInR5cCI6ImRpZDpkZm9zOmNvbnRlbnQtb3AiLCJraWQiOiJkaWQ6ZGZvczplM3Z2dGNrNDJkNGVhY2RuenZ0cm42I2tleV9lejlhODc0dGNrcjNkdjkzM2QzY2tkIiwiY2lkIjoiYmFmeXJlaWFlZGhqcTY0YWFqcHdvY2lhaGw1dzM3ajZ1b3hyNW1vam9xNWRuYWg2ZnB2eHI1ZDRseHUifQ.eyJ2ZXJzaW9uIjoxLCJ0eXBlIjoiY3JlYXRlIiwiZGlkIjoiZGlkOmRmb3M6ZTN2dnRjazQyZDRlYWNkbnp2dHJuNiIsImRvY3VtZW50Q0lEIjoiYmFmeXJlaWh6d3VvdXBmZzNkeGlwNnhtZ3pteHN5d3lpaTJqZW94eHpiZ3gzenhtMmluN2tub2kzZzQiLCJiYXNlRG9jdW1lbnRDSUQiOm51bGwsImNyZWF0ZWRBdCI6IjIwMjYtMDMtMDdUMDA6MDI6MDAuMDAwWiIsIm5vdGUiOm51bGx9.Rv6vlz5MfrwqDUrSVIGs4ZfeBbkQUSBcXhxwZ6hfudSr5MxhYl08hTqLDOA0W1NMjN0Hs0IW9jXTwLwP1dMDBg
-```
-
-Content Operation CID:
-
-```
-bafyreiaedhjq64aajpwociahl5w37j6uoxr5mojoq5dnah6fpvxr5d4lxu
-```
-
-### Content Chain: Update
-
-Content Update Payload:
-
-```json
-{
-  "version": 1,
-  "type": "update",
-  "did": "did:dfos:e3vvtck42d4eacdnzvtrn6",
-  "previousOperationCID": "bafyreiaedhjq64aajpwociahl5w37j6uoxr5mojoq5dnah6fpvxr5d4lxu",
-  "documentCID": "bafyreidh7e36cvwy3uw5ypitcqk7uoktbkkkj7e6hxhky4o75rxn7kxilu",
-  "baseDocumentCID": "bafyreihzwuoupfg3dxip6xmgzmxsywyii2jeoxxzbgx3zxm2in7knoi3g4",
-  "createdAt": "2026-03-07T00:03:00.000Z",
-  "note": "edited title and body"
-}
-```
-
-Updated document (flat content object):
-
-```json
-{
-  "$schema": "https://schemas.dfos.com/post/v1",
-  "format": "short-post",
-  "title": "Hello World (edited)",
-  "body": "Updated content.",
-  "createdByDID": "did:dfos:e3vvtck42d4eacdnzvtrn6"
-}
-```
-
-Document CID (edited):
-
-```
-bafyreidh7e36cvwy3uw5ypitcqk7uoktbkkkj7e6hxhky4o75rxn7kxilu
-```
-
-Content Update CID:
-
-```
-bafyreih6e5cbjitpozhzhgmfktmiohmxyn3ucwhqd3mjixizvwmlhv7hm4
-```
-
-### Content Chain Verified State
-
-```
-Content ID:   a82z92a3hndk6c97thcrn8
-Genesis CID:  bafyreiaedhjq64aajpwociahl5w37j6uoxr5mojoq5dnah6fpvxr5d4lxu
-Head CID:     bafyreih6e5cbjitpozhzhgmfktmiohmxyn3ucwhqd3mjixizvwmlhv7hm4
-```
-
----
-
-## Verification Checklist (For Independent Implementers)
-
-Given the artifacts above, verify:
-
-1. **Multikey decode**: strip `z`, base58btc decode, strip `[0xed, 0x01]` prefix → raw public key:
-
-   ```
-   z6MkrzLMNwoJSV4P3YccWcbtk8vd9LtgMKnLeaDLUqLuASjb
-   → ba421e272fad4f941c221e47f87d9253bdc04f7d4ad2625ae667ab9f0688ce32
-   ```
-
-2. **Genesis JWS verify**: split token on `.`, take first two segments as signing input (UTF-8 bytes), base64url-decode third segment as 64-byte signature, `ed25519.verify(signature, signingInputBytes, publicKey)` → true. The header contains `cid` alongside `alg`, `typ`, and `kid`.
-
-3. **Genesis CID**: base64url-decode JWS payload → parse JSON → dag-cbor canonical encode → SHA-256 → CIDv1 → should be:
-
-   ```
-   bafyreibanjpgcqffcfhr4sptzjfthh5szohhbo5tjfulemkw7uhden5uqy
-   ```
-
-4. **CID header**: Verify each operation JWS header contains `cid` matching the derived operation CID
-
-5. **DID derivation**: take raw CID bytes of genesis CID → SHA-256 → first 22 bytes → `byte % 19` → alphabet lookup → should be `e3vvtck42d4eacdnzvtrn6` → DID = `did:dfos:e3vvtck42d4eacdnzvtrn6`
-
-6. **Rotation JWS**: signed by OLD controller key (key 1). Verify with key 1's public key. kid:
-
-   ```
-   did:dfos:e3vvtck42d4eacdnzvtrn6#key_r9ev34fvc23z999veaaft8
-   ```
-
-7. **Content create JWS**: signed by NEW controller key (key 2, post-rotation). Verify with key 2's public key. kid:
-
-   ```
-   did:dfos:e3vvtck42d4eacdnzvtrn6#key_ez9a874tckr3dv933d3ckd
-   ```
-
-8. **Document CID**: dag-cbor canonical encode the flat content object → SHA-256 → CIDv1 → should be:
-
-   ```
-   bafyreihzwuoupfg3dxip6xmgzmxsywyii2jeoxxzbgx3zxm2in7knoi3g4
-   ```
-
-9. **Content operation `did` field**: verify the `did` field in each content operation matches the `kid` DID in the JWS header
-
-10. **Content chain integrity**: update's `previousOperationCID` matches create's operation CID
-
-11. **Chain completeness**: all operation CIDs, DID derivation, key rotation, and content chain linkage verified end-to-end.
-
-12. **VC-JWT credential verify**: using the issuer's public key, verify a `DFOSContentWrite` or `DFOSContentRead` credential: check EdDSA signature, `typ: "vc+jwt"`, expiration, `kid` DID URL format, `kid` DID matches `iss`, `vc` claim structure matches W3C VC Data Model v2, credential type matches expected DFOS type. Test vectors in [`examples/credential-write.json`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/examples/credential-write.json) and [`examples/credential-read.json`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/examples/credential-read.json).
-
-13. **Delegated content chain verify**: using [`examples/content-delegated.json`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/examples/content-delegated.json), verify a content chain where the genesis is signed by the creator and a subsequent update is signed by a delegate with an embedded `DFOSContentWrite` VC-JWT in the `authorization` field. The VC must be issued by the creator DID, with `sub` matching the delegate DID.
-
-14. **Number encoding determinism**: dag-cbor encode `{"version": 1, "type": "test"}` and verify:
-    - CBOR hex is `a2647479706564746573746776657273696f6e01` (20 bytes)
-    - CID is `bafyreihp6omsp6icc6ee63ox2ovsaxm6s7ikd2a7k5eh2qz2qd5soh5bsa`
-    - Byte at offset 19 is `0x01` (CBOR integer 1), NOT `0xf9` (CBOR float header)
-    - If your implementation decodes this payload from JSON (e.g., from a JWS token) and then re-encodes to dag-cbor, the CID MUST still match. This catches the JSON `float64` → CBOR float trap.
-
----
-
-## Source and Verification
-
-All source lives in [`packages/dfos-protocol/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol) — self-contained, zero monorepo dependencies. 293 checks across 5 languages.
-
-- [`crypto/ed25519`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/crypto/ed25519.ts) — `createNewEd25519Keypair`, `importEd25519Keypair`, `signPayloadEd25519`, `isValidEd25519Signature`
-- [`crypto/jws`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/crypto/jws.ts) — `createJws`, `verifyJws`, `decodeJwsUnsafe`
-- [`crypto/jwt`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/crypto/jwt.ts) — `createJwt`, `verifyJwt`
-- [`crypto/base64url`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/crypto/base64url.ts) — `base64urlEncode`, `base64urlDecode`
-- [`crypto/multiformats`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/crypto/multiformats.ts) — `dagCborCanonicalEncode`, `dagCborCanonicalEqual`
-- [`crypto/id`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/crypto/id.ts) — `generateId`, `generateIdNoPrefix`, `isValidId`
-- [`chain/multikey`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/chain/multikey.ts) — `encodeEd25519Multikey`, `decodeMultikey`
-- [`chain/schemas`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/chain/schemas.ts) — `IdentityOperation`, `ContentOperation`, `MultikeyPublicKey`, `VerifiedIdentity`
-- [`chain/identity-chain`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/chain/identity-chain.ts) — `signIdentityOperation`, `verifyIdentityChain`
-- [`chain/content-chain`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/chain/content-chain.ts) — `signContentOperation`, `verifyContentChain`
-- [`chain/derivation`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/chain/derivation.ts) — `deriveChainIdentifier`, `deriveContentId`
-- [`chain/beacon`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/chain/beacon.ts) — `signBeacon`, `verifyBeacon`
-- [`chain/countersign`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/chain/countersign.ts) — `signCountersignature`, `verifyCountersignature`
-- [`credentials/auth-token`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/credentials/auth-token.ts) — `createAuthToken`, `verifyAuthToken`
-- [`credentials/credential`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/credentials/credential.ts) — `createCredential`, `verifyCredential`, `decodeCredentialUnsafe`
-- [`credentials/schemas`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/credentials/schemas.ts) — `AuthTokenClaims`, `CredentialClaims`, `VCClaim`, `DFOSCredentialType`
-- [`merkle/tree`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/merkle/tree.ts) — `buildMerkleTree`, `hashLeaf`
-- [`merkle/proof`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/merkle/proof.ts) — `generateMerkleProof`, `verifyMerkleProof`
-
-### Related Specifications
-
-- [DID Method: `did:dfos`](https://protocol.dfos.com/did-method) — W3C DID method specification for identity chains
-- [Content Model](https://protocol.dfos.com/content-model) — Standard content schemas (post, profile) for document content objects
-
-### Cross-Language Verification
-
-| Language   | Tests | Source                                                                                               |
-| ---------- | ----- | ---------------------------------------------------------------------------------------------------- |
-| TypeScript | 190   | [`tests/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol/tests)                 |
-| Python     | 59    | [`verify/python/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol/verify/python) |
-| Go         | 15    | [`verify/go/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol/verify/go)         |
-| Rust       | 15    | [`verify/rust/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol/verify/rust)     |
-| Swift      | 14    | [`verify/swift/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol/verify/swift)   |
-
----
-
-## Special Thanks
-
-- **Vinny Bellavia** — [stcisgood.com](https://stcisgood.com)
-- **Allison Clift-Jennings** — [Jura Labs](https://juralabs.com)