@metalabel/dfos-protocol 0.0.1 → 0.0.3

package/PROTOCOL.md

@@ -1,45 +1,33 @@
-# DFOS Protocol: Complete Reference
+# DFOS Protocol
 
-- **Date**: 2026-03-10
-- **Status**: Implemented and tested — TypeScript + Go + Python + Rust + Swift cross-language verification. This spec is currently under review. Discuss the DFOS protocol in the [clear.txt](https://clear.dfos.com) space.
-- **Source**: `packages/dfos-protocol` (self-contained, zero monorepo dependencies, OSS-ready)
-- **Gist**: https://gist.github.com/bvalosek/ed4c96fd4b841302de544ffaee871648 (synced from this file)
+Verifiable identity and content chains — Ed25519 signatures, content-addressed CIDs, W3C DIDs. Cross-language verification in TypeScript, Go, Python, Rust, and Swift.
 
----
-
-## 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 forest floor is dark by default.
-
-But the cryptographic proof layer is public and verifiable. Every piece of content, every identity, every edit has a signed chain of commitments that anyone can independently verify. You don't need to trust the platform. You don't need access to the database. You need a public key and a chain of JWS tokens.
-
-If you have content — from the official app, from an API export, from a screenshot someone sent you, from a pirate mirror, from anywhere — you can verify it's authentic. Hash the content, check the CID, walk the chain, verify the signature. The content is dark; the proof is light.
+This spec is under active review. Discuss it in the [clear.txt](https://clear.dfos.com) space on DFOS.
 
-The protocol makes this verification radically simple. Two chain types — identity and content — using the same mechanics: Ed25519 signatures, JWS compact tokens, content-addressed CIDs. The protocol is deliberately minimal. It knows about keys and document hashes. It doesn't know about posts, profiles, or any application concept. Document semantics are entirely application layer — free to evolve without protocol changes.
+[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)
 
-This means the protocol is not coupled to DFOS. Any system could implement the same identity and content chain primitives — a fork, an alternative client, a completely independent platform — and produce interoperable, cross-verifiable proofs. An identity created on one system can sign content on another. A proof chain started here can be extended there. The protocol is a shared substrate, not a product feature. DFOS is one application built on it. There could be others.
+---
 
-The result: a signed content ledger that any standard EdDSA library can verify, in any language, without DFOS-specific dependencies. The dark forest has public roots.
+## 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.
 
-This document is a complete, self-contained reference for the DFOS protocol. All artifacts are deterministic and reproducible from fixed seeds. An independent implementer can verify every value using standard Ed25519 + dag-cbor libraries.
+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.
 
-**To regenerate**: `pnpm --filter @metalabel/dfos-protocol exec vitest run tests/protocol-reference.spec.ts`
+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 three layers:
+The DFOS protocol has two layers:
 
 | Layer                 | Concern                                                                      |
 | --------------------- | ---------------------------------------------------------------------------- |
 | **Crypto core**       | Identity chains + content chains — Ed25519 signatures, JWS tokens, CID links |
 | **Document envelope** | Standard wrapper: `content` + `baseDocumentCID` + `createdByDID` + timestamp |
-| **Content schemas**   | JSON Schema definitions for what goes inside `content` (post, profile, etc.) |
 
-The crypto core is the trust boundary — everything below it is cryptographically verified. The document envelope provides structural metadata (attribution, edit lineage, timestamps). Content schemas define the application-level semantics.
+The crypto core is the trust boundary — everything below it is cryptographically verified. The document envelope provides structural metadata (attribution, edit lineage, timestamps). What goes inside the envelope's `content` field is application-defined — see the [DFOS Content Model](https://protocol.dfos.com/content-model) for the standard schema library.
 
 ### Crypto Core: Two Chain Types
 
@@ -60,7 +48,7 @@ Every document committed to by a content chain uses a standard envelope, defined
 ```json
 {
   "content": { "$schema": "https://schemas.dfos.com/post/v1", ... },
-  "baseDocumentCID": "bafyrei..." | null,
+  "baseDocumentCID": null,
   "createdByDID": "did:dfos:...",
   "createdAt": "2026-03-07T00:02:00.000Z"
 }
@@ -69,27 +57,29 @@ Every document committed to by a content chain uses a standard envelope, defined
 | Field             | Type         | Description                                                                 |
 | ----------------- | ------------ | --------------------------------------------------------------------------- |
 | `content`         | object       | Application-defined content — must include `$schema` URI, opaque to chains  |
-| `baseDocumentCID` | string\|null | CID of the previous document version (edit lineage). Null for first version |
+| `baseDocumentCID` | string\|null | Optional CID of a prior document version. Semantics are application-defined |
 | `createdByDID`    | string       | DID of the identity that created this document version                      |
 | `createdAt`       | ISO 8601     | When this document version was created                                      |
 
-The `documentCID` in a content chain operation is `CID(dagCborEncode(envelope))`. The envelope provides attribution and edit history at the protocol level. The `content` field is where application-defined JSON Schema types live. The `content` object must include a `$schema` property identifying its content type — this makes every document self-describing and its schema cryptographically committed via the CID.
-
-### Content Schemas
-
-The `content` field inside the document envelope is validated by JSON Schema. The protocol ships a standard library of schemas (post, profile) — see [Standard Document Schemas](#standard-document-schemas). These are conventions, not requirements. Any implementation can define custom schemas.
+The `documentCID` in a content chain operation is `CID(dagCborEncode(envelope))`. The envelope provides attribution at the protocol level. The `content` object must include a `$schema` property identifying its content type — this makes every document self-describing and its schema cryptographically committed via the CID.
 
 ### Addressing
 
 Three canonical representations:
 
-| Thing                  | Form                       | Example                                                       |
-| ---------------------- | -------------------------- | ------------------------------------------------------------- |
-| Operation or document  | CID (dag-cbor + SHA-256)   | `bafyreibanjpgcqffcfhr4sptzjfthh5szohhbo5tjfulemkw7uhden5uqy` |
-| Entity (content chain) | `<hash>` (bare, no prefix) | `67t27rzc83v7c22n9t6z7c`                                      |
-| Identity (key chain)   | `did:dfos:<hash>`          | `did:dfos:e3vvtck42d4eacdnzvtrn6`                             |
+| Thing                 | Form                       | Example                           |
+| --------------------- | -------------------------- | --------------------------------- |
+| Operation or document | CID (dag-cbor + SHA-256)   | See below                         |
+| Content chain         | `<hash>` (bare, no prefix) | `67t27rzc83v7c22n9t6z7c`          |
+| Identity chain        | `did:dfos:<hash>`          | `did:dfos:e3vvtck42d4eacdnzvtrn6` |
 
-Operations and documents are CIDs — standard IPLD content addresses. Entities and identities are derived identifiers — `customAlpha(SHA-256(genesis CID bytes))`. Same derivation for both. Identity chains prepend `did:dfos:` (W3C DID spec). Entity identifiers are bare — just the 22-char hash, no prefix.
+Example CID:
+
+```
+bafyreibanjpgcqffcfhr4sptzjfthh5szohhbo5tjfulemkw7uhden5uqy
+```
+
+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.
 
@@ -99,17 +89,20 @@ Application code may add prefixes for routing (e.g., `post_xxxx`) — these are
 
 ### Commitment Scheme
 
-The protocol requires a **deterministic payload commitment**: given the same logical operation, the commitment (CID) MUST be identical regardless of implementation language or platform. The commitment scheme is **dag-cbor canonical encoding + SHA-256 + CIDv1**. This is not a recommendation — it is the protocol.
+Both operations and documents are content-addressed via **CID** (`dagCborCanonicalEncode(payload)` → SHA-256 → CIDv1). Operations are additionally signed via **JWS**.
 
-Implementations MUST use dag-cbor canonical encoding as defined by the [IPLD dag-cbor codec specification](https://ipld.io/specs/codecs/dag-cbor/spec/). Raw JSON serialization, pretty-printed JSON, or any non-canonical encoding MUST NOT be used for CID derivation. The dag-cbor hex test vectors in this document allow byte-level verification of any implementation's canonical encoding.
+| 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                         |
 
-**JWS signing vs CID derivation are intentionally different representations of the same payload.** JWS signs `base64url(JSON.stringify(payload))` — the UTF-8 bytes of the JSON serialization. CID commits to `dagCborCanonicalEncode(payload)` — the dag-cbor canonical encoding of the parsed object. These produce different bytes from the same logical data. This is by design: JWS uses standard JSON for maximum interoperability with existing JWS libraries, while CID uses dag-cbor for deterministic content addressing.
+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. In DFOS's custodial model, forks are prevented by database-level advisory locks. A non-custodial implementation would need its own fork resolution strategy (e.g., longest chain, first-seen, application-specified preference).
+**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.
 
@@ -121,11 +114,9 @@ This is a self-sovereign invariant: the identity chain defines its own valid sig
 
 ### Content Chain Signer Model
 
-Content chain verification requires a **valid EdDSA signature** — nothing more. The protocol does not define which identities may sign operations on a content chain, does not track or enforce key roles, and does not restrict a chain to a single signer.
-
-The signing key is resolved via the `kid` (DID URL), which references a key on an external identity. The content chain verifier delegates key resolution to the caller via a `resolveKey` callback — the protocol does not prescribe how to look up an identity's current key state.
+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.
 
-This is a deliberate asymmetry with identity chains. Identity chains are self-sovereign — they define their own valid signers internally. Content chains are externally signed — the signing authority model is entirely an application concern, delegated through `resolveKey`. A content chain with operations signed by multiple different identities is valid at the protocol level, as long as each operation's signature verifies against the resolved key.
+Identity chains are self-sovereign — they define their own valid signers via `controllerKeys`. Content chains are externally signed — a content chain with operations signed by multiple different identities is valid at the protocol level, as long as each signature verifies against the resolved key.
 
 **What the protocol enforces:**
 
@@ -137,37 +128,23 @@ This is a deliberate asymmetry with identity chains. Identity chains are self-so
 - Which identities are authorized to sign operations on a given chain
 - Which key role (auth, assert, controller) the signing key must have
 - Whether a chain must have a single signer or may have multiple signers
-- Ownership or attribution semantics between signers and entities
-
-### Terminal States
+- Ownership or attribution semantics between signers and content chains
 
-**`delete` is the only terminal state.** No valid operations may follow a delete in either chain type. An implementation MUST reject any operation that appears after a delete.
+### Terminal States and Special Operations
 
-`delete` is a terminal marker that prevents future operations on the chain but does NOT remove data. The complete chain — including all prior operations and their signatures — MUST remain intact for verification. Any party holding the chain can still walk it, verify every signature, and confirm the history up to and including the delete. Data removal (e.g., purging content from storage) is an application-layer concern, not a protocol operation.
+**`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
+**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.
 
-`update` operations on identity chains MUST include at least one controller key. Validation MUST reject any `update` with an empty `controllerKeys` array. This ensures that an identity always has a path forward — if decommissioning is intended, `delete` is the correct terminal operation.
-
-### Content-Null Semantics
-
-An `update` operation on a content chain with `documentCID: null` means **the entity exists but its current content is cleared**. This is not a delete — the chain continues, and a subsequent update can set content again. Think of it as "unpublish" rather than "destroy."
+**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 (`did:dfos:identity-op`, `did:dfos:content-op`) is advisory — it aids routing and dispatch but is not a security-critical field. Verification checks the signature and chain integrity, not the `typ` value. Implementations SHOULD validate `typ` for correctness but MUST NOT rely on it for security decisions.
-
-### JWT `kid` vs Operation `kid`
-
-JWT tokens (for device auth, MCP sessions, etc.) use `kid` as a simple key identifier for lookup — e.g., `key_ez9a874tckr3dv933d3ckd`. This does NOT follow the same DID URL convention used in operation JWS headers. Operation `kid` uses bare key ID for identity genesis and DID URL (`did:dfos:xxx#key_id`) for everything else. JWT `kid` is always a bare key ID — the JWT's `sub` claim carries the DID separately.
-
-### ID Modulo Bias
-
-The ID encoding uses `byte % 19` where each byte ranges 0-255. Since 256 is not evenly divisible by 19, values 0-8 (alphabet positions) appear with probability ~5.26% while values 9-18 appear with probability ~5.22%. This is a ~0.3% bias — not security-relevant for identifiers but acknowledged here for completeness. A rejection-sampling approach (retry if `byte >= 247`) would eliminate the bias entirely.
+The JWS `typ` header (`did:dfos:identity-op`, `did:dfos:content-op`) 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. These are abuse-prevention ceilings — deliberately loose, not tight validation. Implementations MUST reject operations that exceed these bounds. Implementations MAY impose stricter 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                              |
 | -------------------------------------------- | --------- | -------------------------------------- |
@@ -188,84 +165,6 @@ The protocol does NOT limit:
 
 ---
 
-## Standard Document Schemas
-
-The crypto core commits to `documentCID` values without inspecting their contents. The document envelope provides structural metadata. The **content** inside the envelope is where JSON Schema validation applies.
-
-The protocol ships a standard library of content schemas as JSON Schema (draft 2020-12) definitions. These are not required — any implementation can define its own content types. They are provided as a starting point for content built on the DFOS protocol, and they are what DFOS uses internally.
-
-### Schema Convention
-
-Documents declare their type via a `$schema` field pointing to a schema URI:
-
-```json
-{
-  "$schema": "https://schemas.dfos.com/post/v1",
-  "format": "short-post",
-  "body": "Hello world."
-}
-```
-
-Because the `$schema` field is part of the document, it is behind the `documentCID` — cryptographically committed in the content chain. Any verifier can resolve the document, read `$schema`, and validate against the schema.
-
-### Schema Evolution
-
-Schemas are versioned via the URI path (`/post/v1`, `/post/v2`). Evolution rules:
-
-- **Strictly additive within a version** — new optional fields can be added to an existing version at any time without breaking existing documents
-- **Breaking changes require a new version** — removing fields, changing types, or adding new required fields means a new version URI
-- **Implementations declare which versions they understand** — a registry or application can accept `post/v1` and `post/v2` simultaneously, or only `post/v1`
-
-### Standard Schemas
-
-Schema files live in `schemas/` in the protocol package. Each is a standalone JSON Schema (draft 2020-12).
-
-#### Post (`https://schemas.dfos.com/post/v1`)
-
-The primary content type. Covers short posts, long-form posts, comments, and replies via the `format` discriminator.
-
-| Field         | Type     | Required | Description                                                                        |
-| ------------- | -------- | -------- | ---------------------------------------------------------------------------------- |
-| `$schema`     | string   | yes      | `"https://schemas.dfos.com/post/v1"`                                               |
-| `format`      | enum     | yes      | `"short-post"`, `"long-post"`, `"comment"`, `"reply"` — immutable, set at creation |
-| `title`       | string   | no       | Post title (typically for long-post format)                                        |
-| `body`        | string   | no       | Post body content                                                                  |
-| `cover`       | media    | no       | Cover image                                                                        |
-| `attachments` | media[]  | no       | Attached media objects                                                             |
-| `topics`      | string[] | no       | Topic names (stored as names for portability)                                      |
-
-#### Profile (`https://schemas.dfos.com/profile/v1`)
-
-The displayable identity for any agent, person, group, or space.
-
-| Field         | Type   | Required | Description                             |
-| ------------- | ------ | -------- | --------------------------------------- |
-| `$schema`     | string | yes      | `"https://schemas.dfos.com/profile/v1"` |
-| `name`        | string | no       | Display name                            |
-| `description` | string | no       | Short bio or description                |
-| `avatar`      | media  | no       | Avatar image                            |
-| `banner`      | media  | no       | Banner image                            |
-| `background`  | media  | no       | Background image                        |
-
-### Media Object
-
-Several schemas reference media objects. The standard representation:
-
-```json
-{
-  "id": "media_abc123",
-  "uri": "https://cdn.example.com/media/abc123.jpg"
-}
-```
-
-`id` is required (opaque identifier). `uri` is optional.
-
-### Custom Schemas
-
-Any implementation can define custom document schemas following the same pattern — a JSON Schema with a `$schema` const field pointing to a unique URI. The protocol will commit to the document via CID regardless of what's inside. The standard schemas are conventions, not constraints.
-
----
-
 ## Standards and Dependencies
 
 | Component           | Standard / Library                                                         |
@@ -275,7 +174,6 @@ Any implementation can define custom document schemas following the same pattern
 | 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`)            |
-| Auth tokens         | JWT (RFC 7519) with `alg: "EdDSA"`                                         |
 | ID encoding         | SHA-256 → custom 19-char alphabet, 22 characters                           |
 
 ### ID Alphabet
@@ -286,7 +184,7 @@ Length:   22 characters
 Entropy:  ~93.4 bits (19^22)
 ```
 
-Process: `SHA-256(input) → for each of first 22 bytes: alphabet[byte % 19]`
+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.
@@ -414,7 +312,7 @@ DID:    did:dfos:e3vvtck42d4eacdnzvtrn6
   createdAt: string,
   note: string | null }
 
-// Permanent entity destruction
+// Permanent destruction
 { version: 1, type: "delete",
   previousOperationCID: string,
   createdAt: string,
@@ -443,11 +341,18 @@ token = signingInput + "." + base64url(signature)
 
 ### kid Rules
 
-| Context                   | kid format  | Example                                                      |
-| ------------------------- | ----------- | ------------------------------------------------------------ |
-| Identity create (genesis) | Bare key ID | `key_r9ev34fvc23z999veaaft8`                                 |
-| Identity update/delete    | DID URL     | `did:dfos:e3vvtck42d4eacdnzvtrn6#key_r9ev34fvc23z999veaaft8` |
-| All content ops           | DID URL     | `did:dfos:e3vvtck42d4eacdnzvtrn6#key_ez9a874tckr3dv933d3ckd` |
+| 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
 
@@ -465,11 +370,7 @@ Every operation JWS (identity-op and content-op) includes a `cid` field in the p
 - `header.cid` is missing
 - `header.cid` does not match the derived CID
 
-This provides three benefits:
-
-- **Pre-verification routing**: The operation CID can be read from the header without parsing the payload or running dag-cbor encoding
-- **Cross-implementation consistency**: A CID mismatch between header and derived value immediately surfaces dag-cbor encoding disagreements across implementations
-- **Self-documenting tokens**: Each JWS token declares its content-addressed identity
+A CID mismatch between header and derived value immediately surfaces dag-cbor encoding disagreements across implementations.
 
 Note: JWT tokens (device auth) do NOT include a `cid` header — this field is specific to operation JWS tokens.
 
@@ -521,7 +422,7 @@ Where `idEncode` is the 19-char alphabet encoding described above.
 
 ## Deterministic Reference Artifacts
 
-All values below are deterministic and reproducible. Private keys are derived from `SHA-256(UTF8("dfos-protocol-reference-key-N"))`.
+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)
 
@@ -599,7 +500,11 @@ JWS Token:
 eyJhbGciOiJFZERTQSIsInR5cCI6ImRpZDpkZm9zOmlkZW50aXR5LW9wIiwia2lkIjoia2V5X3I5ZXYzNGZ2YzIzejk5OXZlYWFmdDgiLCJjaWQiOiJiYWZ5cmVpYmFuanBnY3FmZmNmaHI0c3B0empmdGhoNXN6b2hoYm81dGpmdWxlbWt3N3VoZGVuNXVxeSJ9.eyJ2ZXJzaW9uIjoxLCJ0eXBlIjoiY3JlYXRlIiwiYXV0aEtleXMiOlt7ImlkIjoia2V5X3I5ZXYzNGZ2YzIzejk5OXZlYWFmdDgiLCJ0eXBlIjoiTXVsdGlrZXkiLCJwdWJsaWNLZXlNdWx0aWJhc2UiOiJ6Nk1rcnpMTU53b0pTVjRQM1ljY1djYnRrOHZkOUx0Z01LbkxlYURMVXFMdUFTamIifV0sImFzc2VydEtleXMiOlt7ImlkIjoia2V5X3I5ZXYzNGZ2YzIzejk5OXZlYWFmdDgiLCJ0eXBlIjoiTXVsdGlrZXkiLCJwdWJsaWNLZXlNdWx0aWJhc2UiOiJ6Nk1rcnpMTU53b0pTVjRQM1ljY1djYnRrOHZkOUx0Z01LbkxlYURMVXFMdUFTamIifV0sImNvbnRyb2xsZXJLZXlzIjpbeyJpZCI6ImtleV9yOWV2MzRmdmMyM3o5OTl2ZWFhZnQ4IiwidHlwZSI6Ik11bHRpa2V5IiwicHVibGljS2V5TXVsdGliYXNlIjoiejZNa3J6TE1Od29KU1Y0UDNZY2NXY2J0azh2ZDlMdGdNS25MZWFETFVxTHVBU2piIn1dLCJjcmVhdGVkQXQiOiIyMDI2LTAzLTA3VDAwOjAwOjAwLjAwMFoifQ.EDryDK1uvtix-17cHun9t6MacFIx2rMmMF1QLzfD5TFlSsOvMcue97pCgGn3CXeLVFtVxgpCoh0kGSXioKKzAw
 ```
 
-Operation CID: `bafyreibanjpgcqffcfhr4sptzjfthh5szohhbo5tjfulemkw7uhden5uqy`
+Operation CID:
+
+```
+bafyreibanjpgcqffcfhr4sptzjfthh5szohhbo5tjfulemkw7uhden5uqy
+```
 
 **Derived DID: `did:dfos:e3vvtck42d4eacdnzvtrn6`**
 
@@ -660,7 +565,11 @@ JWS Token:
 eyJhbGciOiJFZERTQSIsInR5cCI6ImRpZDpkZm9zOmlkZW50aXR5LW9wIiwia2lkIjoiZGlkOmRmb3M6ZTN2dnRjazQyZDRlYWNkbnp2dHJuNiNrZXlfcjlldjM0ZnZjMjN6OTk5dmVhYWZ0OCIsImNpZCI6ImJhZnlyZWljeW00Y3lpZWRubGQ3M3NtYngzMnN6YWVpN3hkdWxxbjRnM3N0ZTVlMncydWxhanIzb3FtIn0.eyJ2ZXJzaW9uIjoxLCJ0eXBlIjoidXBkYXRlIiwicHJldmlvdXNPcGVyYXRpb25DSUQiOiJiYWZ5cmVpYmFuanBnY3FmZmNmaHI0c3B0empmdGhoNXN6b2hoYm81dGpmdWxlbWt3N3VoZGVuNXVxeSIsImF1dGhLZXlzIjpbeyJpZCI6ImtleV9lejlhODc0dGNrcjNkdjkzM2QzY2tkIiwidHlwZSI6Ik11bHRpa2V5IiwicHVibGljS2V5TXVsdGliYXNlIjoiejZNa2ZVZDY1SnJBaGZkZ0Z1TUNjY1U5VGhRdmpCMmZKQU1VSGt1dWFqRjk5MmdLIn1dLCJhc3NlcnRLZXlzIjpbeyJpZCI6ImtleV9lejlhODc0dGNrcjNkdjkzM2QzY2tkIiwidHlwZSI6Ik11bHRpa2V5IiwicHVibGljS2V5TXVsdGliYXNlIjoiejZNa2ZVZDY1SnJBaGZkZ0Z1TUNjY1U5VGhRdmpCMmZKQU1VSGt1dWFqRjk5MmdLIn1dLCJjb250cm9sbGVyS2V5cyI6W3siaWQiOiJrZXlfZXo5YTg3NHRja3IzZHY5MzNkM2NrZCIsInR5cGUiOiJNdWx0aWtleSIsInB1YmxpY0tleU11bHRpYmFzZSI6Ino2TWtmVWQ2NUpyQWhmZGdGdU1DY2NVOVRoUXZqQjJmSkFNVUhrdXVhakY5OTJnSyJ9XSwiY3JlYXRlZEF0IjoiMjAyNi0wMy0wN1QwMDowMTowMC4wMDBaIn0.MScuoBlgOK3j5QX9tFcw1ou0o4LgJziGJEsZ5pvqiBr1SagAyAv5h-wajQhtg8IP7dLlM0U4leW2iRra945cDg
 ```
 
-Operation CID: `bafyreicym4cyiednld73smbx32szaei7xdulqn4g3ste5e2w2ulajr3oqm`
+Operation CID:
+
+```
+bafyreicym4cyiednld73smbx32szaei7xdulqn4g3ste5e2w2ulajr3oqm
+```
 
 Post-rotation: DID unchanged (`did:dfos:e3vvtck42d4eacdnzvtrn6`), controller rotated to `key_ez9a874tckr3dv933d3ckd`.
 
@@ -682,7 +591,11 @@ Document (application layer):
 }
 ```
 
-Document CID: `bafyreifpvwuarml62sfogdpi2vlltvg2ev6o4xtw74zfud7cpkg7426zne`
+Document CID:
+
+```
+bafyreifpvwuarml62sfogdpi2vlltvg2ev6o4xtw74zfud7cpkg7426zne
+```
 
 Content Create JWS Header:
 
@@ -719,7 +632,11 @@ Content Create JWS Token:
 eyJhbGciOiJFZERTQSIsInR5cCI6ImRpZDpkZm9zOmNvbnRlbnQtb3AiLCJraWQiOiJkaWQ6ZGZvczplM3Z2dGNrNDJkNGVhY2RuenZ0cm42I2tleV9lejlhODc0dGNrcjNkdjkzM2QzY2tkIiwiY2lkIjoiYmFmeXJlaWE1ejd6eGtuYWU1ZHM3MmV1aWh1ZjJyZzNpeGw2dDRmYnpqZWZoY29nZzNucXBweW9ncXUifQ.eyJ2ZXJzaW9uIjoxLCJ0eXBlIjoiY3JlYXRlIiwiZG9jdW1lbnRDSUQiOiJiYWZ5cmVpZnB2d3Vhcm1sNjJzZm9nZHBpMnZsbHR2ZzJldjZvNHh0dzc0emZ1ZDdjcGtnNzQyNnpuZSIsImNyZWF0ZWRBdCI6IjIwMjYtMDMtMDdUMDA6MDI6MDAuMDAwWiIsIm5vdGUiOm51bGx9.t_DDkJ_TmNekIGUFO22G-W78QoE4XTg9LKQ4gzAQHaK3B6491Tir9b-wtp-hcwmENu2Hqnieqv5ASiqfFrEbDw
 ```
 
-Content Operation CID: `bafyreia5z7zxknae5ds72euihuf2rg3ixl6t4fbzjefhcogg3nqppyogqu`
+Content Operation CID:
+
+```
+bafyreia5z7zxknae5ds72euihuf2rg3ixl6t4fbzjefhcogg3nqppyogqu
+```
 
 ### Content Chain: Update
 
@@ -752,34 +669,16 @@ Updated document:
 }
 ```
 
-Document CID (edited): `bafyreieuo26zfmjxwpmw5jk6bqzqhvivxcbckgxtyeuc7ypf3p4sihgq4q`
-Content Update CID: `bafyreibb4lsvqmz4j76rsvhkqw3v2b4vp23t7dimm6vl5g5wlninvkemxq`
-
-### EdDSA JWT
-
-Header:
+Document CID (edited):
 
-```json
-{ "alg": "EdDSA", "typ": "JWT", "kid": "key_ez9a874tckr3dv933d3ckd" }
 ```
-
-Payload:
-
-```json
-{
-  "iss": "dfos",
-  "sub": "did:dfos:e3vvtck42d4eacdnzvtrn6",
-  "aud": "dfos-api",
-  "exp": 1772902800,
-  "iat": 1772899200,
-  "jti": "session_ref_example_01"
-}
+bafyreieuo26zfmjxwpmw5jk6bqzqhvivxcbckgxtyeuc7ypf3p4sihgq4q
 ```
 
-JWT Token:
+Content Update CID:
 
 ```
-eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6ImtleV9lejlhODc0dGNrcjNkdjkzM2QzY2tkIn0.eyJpc3MiOiJkZm9zIiwic3ViIjoiZGlkOmRmb3M6ZTN2dnRjazQyZDRlYWNkbnp2dHJuNiIsImF1ZCI6ImRmb3MtYXBpIiwiZXhwIjoxNzcyOTAyODAwLCJpYXQiOjE3NzI4OTkyMDAsImp0aSI6InNlc3Npb25fcmVmX2V4YW1wbGVfMDEifQ.zhKeXJHHF7a1-MwF4QoUTRptCplAwh20-rLnuWGDFT6uJheN4E_SA5NhqvMNflLHxd7h97gdaVnMZGE67SXEBA
+bafyreibb4lsvqmz4j76rsvhkqw3v2b4vp23t7dimm6vl5g5wlninvkemxq
 ```
 
 ---
@@ -788,86 +687,83 @@ eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCIsImtpZCI6ImtleV9lejlhODc0dGNrcjNkdjkzM2QzY2tk
 
 Given the artifacts above, verify:
 
-1. **Multikey decode**: `z6MkrzLMNwoJSV4P3YccWcbtk8vd9LtgMKnLeaDLUqLuASjb` → strip `z`, base58btc decode, strip `[0xed, 0x01]` → public key `ba421e272fad4f941c221e47f87d9253bdc04f7d4ad2625ae667ab9f0688ce32`
+1. **Multikey decode**: strip `z`, base58btc decode, strip `[0xed, 0x01]` prefix → raw public key:
 
-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. Note the header now contains `cid` alongside `alg`, `typ`, and `kid`.
+   ```
+   z6MkrzLMNwoJSV4P3YccWcbtk8vd9LtgMKnLeaDLUqLuASjb
+   → ba421e272fad4f941c221e47f87d9253bdc04f7d4ad2625ae667ab9f0688ce32
+   ```
 
-3. **Genesis CID**: base64url-decode JWS payload → parse JSON → dag-cbor canonical encode → SHA-256 → CIDv1 → should be `bafyreibanjpgcqffcfhr4sptzjfthh5szohhbo5tjfulemkw7uhden5uqy`
+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**: kid = `did:dfos:e3vvtck42d4eacdnzvtrn6#key_r9ev34fvc23z999veaaft8` — signed by OLD controller key (key 1). Verify with key 1's public key.
+6. **Rotation JWS**: signed by OLD controller key (key 1). Verify with key 1's public key. kid:
 
-7. **Content create JWS**: kid = `did:dfos:e3vvtck42d4eacdnzvtrn6#key_ez9a874tckr3dv933d3ckd` — signed by NEW controller key (key 2, post-rotation). Verify with key 2's public key.
+   ```
+   did:dfos:e3vvtck42d4eacdnzvtrn6#key_r9ev34fvc23z999veaaft8
+   ```
 
-8. **Document CID**: dag-cbor canonical encode the document JSON → SHA-256 → CIDv1 → should be `bafyreifpvwuarml62sfogdpi2vlltvg2ev6o4xtw74zfud7cpkg7426zne`
+7. **Content create JWS**: signed by NEW controller key (key 2, post-rotation). Verify with key 2's public key. kid:
 
-9. **Content chain integrity**: update's `previousOperationCID` matches create's operation CID
+   ```
+   did:dfos:e3vvtck42d4eacdnzvtrn6#key_ez9a874tckr3dv933d3ckd
+   ```
 
-10. **JWT verify**: same signing mechanics as JWS — `ed25519.verify(signature, UTF8(header.payload), key2_publicKey)` → true. Check `exp > currentTime`, `iss == "dfos"`, `aud == "dfos-api"`.
+8. **Document CID**: dag-cbor canonical encode the document JSON → SHA-256 → CIDv1 → should be:
 
----
+   ```
+   bafyreifpvwuarml62sfogdpi2vlltvg2ev6o4xtw74zfud7cpkg7426zne
+   ```
 
-## Source Code Reference
-
-All source lives in `packages/dfos-protocol/` — self-contained, zero monorepo dependencies.
-
-| File                                | Contents                                                                                           |
-| ----------------------------------- | -------------------------------------------------------------------------------------------------- |
-| `src/crypto/ed25519.ts`             | `createNewEd25519Keypair`, `importEd25519Keypair`, `signPayloadEd25519`, `isValidEd25519Signature` |
-| `src/crypto/jws.ts`                 | `createJws`, `verifyJws`, `decodeJwsUnsafe`, `JwsVerificationError`                                |
-| `src/crypto/jwt.ts`                 | `createJwt`, `verifyJwt`, `decodeJwtUnsafe` (EdDSA only)                                           |
-| `src/crypto/base64url.ts`           | `base64urlEncode`, `base64urlDecode`                                                               |
-| `src/crypto/multiformats.ts`        | `dagCborCanonicalEncode`, `dagCborCanonicalEqual`                                                  |
-| `src/crypto/id.ts`                  | `generateId`, `generateIdNoPrefix`, `isValidId`                                                    |
-| `src/chain/multikey.ts`             | `encodeEd25519Multikey`, `decodeMultikey`                                                          |
-| `src/chain/schemas.ts`              | `IdentityOperation`, `ContentOperation`, `MultikeyPublicKey`, `VerifiedIdentity`                   |
-| `src/chain/identity-chain.ts`       | `signIdentityOperation`, `verifyIdentityChain`                                                     |
-| `src/chain/content-chain.ts`        | `signContentOperation`, `verifyContentChain`                                                       |
-| `src/chain/derivation.ts`           | `deriveChainIdentifier`                                                                            |
-| `src/registry/schemas.ts`           | Registry API Zod types (wire contract)                                                             |
-| `src/registry/server.ts`            | Reference Hono registry server                                                                     |
-| `src/registry/store.ts`             | In-memory chain store with linear enforcement                                                      |
-| `openapi.yaml`                      | OpenAPI 3.1 spec for registry API                                                                  |
-| `schemas/document-envelope.v1.json` | JSON Schema for the document envelope wrapper                                                      |
-| `schemas/post.v1.json`              | JSON Schema for post documents                                                                     |
-| `schemas/profile.v1.json`           | JSON Schema for profile documents                                                                  |
-| `tests/protocol-reference.spec.ts`  | Deterministic artifact generator (this doc's source)                                               |
-| `verify/go/`                        | Go cross-language verification (9 tests)                                                           |
-| `verify/python/`                    | Python cross-language verification (32 checks)                                                     |
-| `verify/rust/`                      | Rust cross-language verification (9 tests)                                                         |
-| `verify/swift/`                     | Swift cross-language verification (8 tests)                                                        |
+9. **Content chain integrity**: update's `previousOperationCID` matches create's operation CID
 
----
+10. **Chain completeness**: all operation CIDs, DID derivation, key rotation, and content chain linkage verified end-to-end.
 
-## Test Coverage (160 checks across 5 languages)
+---
 
-### TypeScript — dfos-protocol (99 tests)
+## Source and Verification
 
-- `tests/crypto.spec.ts` (13): ed25519 keypair/sign/verify, JWS round-trip/wrong key/tampered/decode/malformed
-- `tests/chain.spec.ts` (39): multikey encoding, identity chain (genesis, DID, rotation, delete, cid header, errors), content chain (lifecycle, clear, delete, cid header, errors)
-- `tests/registry.spec.ts` (18): HTTP contract — submission, resubmission, extension, fork rejection, pagination, cross-chain key resolution, 404s
-- `tests/schemas.spec.ts` (28): JSON Schema compilation + validation for document envelope, post, profile — conforming documents, missing fields, invalid values, additional properties
-- `tests/protocol-reference.spec.ts` (1): deterministic artifact generator
+All source lives in [`packages/dfos-protocol/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol) — self-contained, zero monorepo dependencies. 160 checks across 5 languages.
 
-### Python — verify/ (35 checks)
+- [`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/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`
 
-- Key derivation, multikey, dag-cbor bytes, CID/DID derivation, JWS/JWT signatures, CID header verification, document CID
-- Dependencies: `pynacl`, `dag-cbor`, `base58`
+### Related Specifications
 
-### Go — verify/ (9 tests)
+- [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 the document envelope
+- [Registry API](https://protocol.dfos.com/registry-api) — HTTP API for chain storage and resolution
 
-- Key derivation, multikey, dag-cbor, CID/DID derivation, JWS/JWT signatures, CID header verification
-- Dependencies: `fxamacker/cbor/v2`, `mr-tron/base58`
+### Cross-Language Verification
 
-### Rust — verify/ (9 tests)
+| Language   | Tests | Source                                                                                               |
+| ---------- | ----- | ---------------------------------------------------------------------------------------------------- |
+| TypeScript | 99    | [`tests/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol/tests)                 |
+| Python     | 35    | [`verify/python/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol/verify/python) |
+| Go         | 9     | [`verify/go/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol/verify/go)         |
+| Rust       | 9     | [`verify/rust/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol/verify/rust)     |
+| Swift      | 8     | [`verify/swift/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol/verify/swift)   |
 
-- Key derivation, multikey, dag-cbor, CID/DID derivation, JWS/JWT signatures, CID header verification
-- Dependencies: `ed25519-dalek`, `ciborium`, `sha2`, `bs58`, `base64`, `data-encoding`
+---
 
-### Swift — verify/ (8 tests)
+## Special Thanks
 
-- Key derivation, multikey, CID/DID derivation, JWS/JWT signatures, CID header verification
-- Dependencies: Apple `Crypto` (swift-crypto)
+- **Vinny Bellavia** — [stcisgood.com](https://stcisgood.com)
+- **Allison Clift-Jennings** — [Jura Labs](https://juralabs.com)