@metalabel/dfos-protocol 0.0.2 → 0.1.0

package/PROTOCOL.md

@@ -10,34 +10,26 @@ This spec is under active review. Discuss it in the [clear.txt](https://clear.df
 
 ## 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.
+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.
 
-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.
+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.
 
-If you have content — from the official app, from an API export, 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.
-
-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.
-
-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.
-
----
-
-All artifacts in this document are deterministic and reproducible from fixed seeds. An independent implementer can verify every value using standard Ed25519 + dag-cbor libraries.
+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 two layers:
+The DFOS protocol has four components:
 
-| Layer                 | Concern                                                                      |
+| Component             | Concern                                                                      |
 | --------------------- | ---------------------------------------------------------------------------- |
 | **Crypto core**       | Identity chains + content chains — Ed25519 signatures, JWS tokens, CID links |
-| **Document envelope** | Standard wrapper: `content` + `baseDocumentCID` + `createdByDID` + timestamp |
+| **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. 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.
+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
 
@@ -49,47 +41,21 @@ The crypto core is the trust boundary — everything below it is cryptographical
 | 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 document envelope.
-
-### Document Envelope
-
-Every document committed to by a content chain uses a standard envelope, defined by JSON Schema at [`schemas/document-envelope.v1.json`](schemas/document-envelope.v1.json) (`https://schemas.dfos.com/document-envelope/v1`):
-
-```json
-{
-  "content": { "$schema": "https://schemas.dfos.com/post/v1", ... },
-  "baseDocumentCID": null,
-  "createdByDID": "did:dfos:...",
-  "createdAt": "2026-03-07T00:02:00.000Z"
-}
-```
-
-| Field             | Type         | Description                                                                 |
-| ----------------- | ------------ | --------------------------------------------------------------------------- |
-| `content`         | object       | Application-defined content — must include `$schema` URI, opaque to chains  |
-| `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 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.
+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 canonical representations:
-
-| Thing                  | Form                       | Example                           |
-| ---------------------- | -------------------------- | --------------------------------- |
-| Operation or document  | CID (dag-cbor + SHA-256)   | See below                         |
-| Entity (content chain) | `<hash>` (bare, no prefix) | `67t27rzc83v7c22n9t6z7c`          |
-| Identity (key chain)   | `did:dfos:<hash>`          | `did:dfos:e3vvtck42d4eacdnzvtrn6` |
+Three addressing modes, self-describing by format:
 
-Example CID:
+| 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` |
 
-```
-bafyreibanjpgcqffcfhr4sptzjfthh5szohhbo5tjfulemkw7uhden5uqy
-```
+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. 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.
+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 +65,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,23 +90,24 @@ 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.
+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.
 
-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.
+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.
 
-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.
+**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
 
 **What the protocol does NOT enforce (application concerns):**
 
 - 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
+- Ownership or attribution semantics between signers and content chains
 
 ### Terminal States and Special Operations
 
@@ -145,18 +115,28 @@ This is a deliberate asymmetry with identity chains. Identity chains are self-so
 
 **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 entity exists but its content is cleared. The chain continues — a subsequent update can set content again.
+**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`) aids routing but is not security-critical. Implementations SHOULD validate it but MUST NOT rely on it for security decisions.
+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`                  | Device auth tokens        |
+
+These are non-standard per JOSE convention, documented intentionally. 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. 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                              |
 | -------------------------------------------- | --------- | -------------------------------------- |
+| `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              |
@@ -310,19 +290,24 @@ DID:    did:dfos:e3vvtck42d4eacdnzvtrn6
 ```typescript
 // Genesis — starts the content chain, commits initial document
 { version: 1, type: "create",
-  documentCID: string,                    // CID of document content
+  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 }
 
-// Permanent entity destruction
+// Permanent destruction
 { version: 1, type: "delete",
+  did: string,                           // author DID
   previousOperationCID: string,
   createdAt: string,
   note: string | null }
@@ -379,11 +364,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.
 
@@ -405,6 +386,90 @@ Where `idEncode` is the 19-char alphabet encoding described above.
 
 ---
 
+## 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": "a3f8b2c1d4e5f6071829304a5b6c7d8e9f0a1b2c3d4e5f6071829304a5b6c7d8",
+  "createdAt": "2026-03-07T00:04: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_ez9a874tckr3dv933d3ckd",
+  "cid": "bafyrei..."
+}
+```
+
+### 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)))`.
+
+### 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.
+
+---
+
+## 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
@@ -427,15 +492,16 @@ Where `idEncode` is the 19-char alphabet encoding described above.
 2. First op must be `type: "create"`
 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. Resolve `kid` via external key resolver (caller provides)
-6. Verify EdDSA JWS signature
-7. Apply state change (set document, clear, or delete)
+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. Apply state change (set document, clear, or delete)
 
 ---
 
 ## 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)
 
@@ -510,7 +576,7 @@ JWS Signature (hex):
 JWS Token:
 
 ```
-eyJhbGciOiJFZERTQSIsInR5cCI6ImRpZDpkZm9zOmlkZW50aXR5LW9wIiwia2lkIjoia2V5X3I5ZXYzNGZ2YzIzejk5OXZlYWFmdDgiLCJjaWQiOiJiYWZ5cmVpYmFuanBnY3FmZmNmaHI0c3B0empmdGhoNXN6b2hoYm81dGpmdWxlbWt3N3VoZGVuNXVxeSJ9.eyJ2ZXJzaW9uIjoxLCJ0eXBlIjoiY3JlYXRlIiwiYXV0aEtleXMiOlt7ImlkIjoia2V5X3I5ZXYzNGZ2YzIzejk5OXZlYWFmdDgiLCJ0eXBlIjoiTXVsdGlrZXkiLCJwdWJsaWNLZXlNdWx0aWJhc2UiOiJ6Nk1rcnpMTU53b0pTVjRQM1ljY1djYnRrOHZkOUx0Z01LbkxlYURMVXFMdUFTamIifV0sImFzc2VydEtleXMiOlt7ImlkIjoia2V5X3I5ZXYzNGZ2YzIzejk5OXZlYWFmdDgiLCJ0eXBlIjoiTXVsdGlrZXkiLCJwdWJsaWNLZXlNdWx0aWJhc2UiOiJ6Nk1rcnpMTU53b0pTVjRQM1ljY1djYnRrOHZkOUx0Z01LbkxlYURMVXFMdUFTamIifV0sImNvbnRyb2xsZXJLZXlzIjpbeyJpZCI6ImtleV9yOWV2MzRmdmMyM3o5OTl2ZWFhZnQ4IiwidHlwZSI6Ik11bHRpa2V5IiwicHVibGljS2V5TXVsdGliYXNlIjoiejZNa3J6TE1Od29KU1Y0UDNZY2NXY2J0azh2ZDlMdGdNS25MZWFETFVxTHVBU2piIn1dLCJjcmVhdGVkQXQiOiIyMDI2LTAzLTA3VDAwOjAwOjAwLjAwMFoifQ.EDryDK1uvtix-17cHun9t6MacFIx2rMmMF1QLzfD5TFlSsOvMcue97pCgGn3CXeLVFtVxgpCoh0kGSXioKKzAw
+eyJhbGciOiJFZERTQSIsInR5cCI6ImRpZDpkZm9zOmlkZW50aXR5LW9wIiwia2lkIjoia2V5X3I5ZXYzNGZ2YzIzejk5OXZlYWFmdDgiLCJjaWQiOiJiYWZ5cmVpYmFuanBnY3FmZmNmaHI0c3B0empmdGhoNXN6b2hoYm81dGpmdWxlbWt3N3VoZGVuNXVxeSJ9.eyJ2ZXJzaW9uIjoxLCJ0eXBlIjoiY3JlYXRlIiwiYXV0aEtleXMiOlt7ImlkIjoia2V5X3I5ZXYzNGZ2YzIzejk5OXZlYWFmdDgiLCJ0eXBlIjoiTXVsdGlrZXkiLCJwdWJsaWNLZXlNdWx0aWJhc2UiOiJ6Nk1rcnpMTU53b0pTVjRQM1ljY1djYnRrOHZkOUx0Z01LbkxlYURMVXFMdUFTamIifV0sImFzc2VydEtleXMiOlt7ImlkIjoia2V5X3I5ZXYzNGZ2YzIzejk5OXZlYWFmdDgiLCJ0eXBlIjoiTXVsdGlrZXkiLCJwdWJsaWNLZXlNdWx0aWJhc2UiOiJ6Nk1rcnpMTU53b0pTVjRQM1ljY1djYnRrOHZkOUx0Z01LbkxlYURMVXFMdUFTamIifV0sImNvbnRyb2xsZXJLZXlzIjpbeyJpZCI6ImtleV9yOWV2MzRmdmMyM3o5OTF2ZWFhZnQ4IiwidHlwZSI6Ik11bHRpa2V5IiwicHVibGljS2V5TXVsdGliYXNlIjoiejZNa3J6TE1Od29KU1Y0UDNZY2NXY2J0azh2ZDlMdGdNS25MZWFETFVxTHVBU2piIn1dLCJjcmVhdGVkQXQiOiIyMDI2LTAzLTA3VDAwOjAwOjAwLjAwMFoifQ.EDryDK1uvtix-17cHun9t6MacFIx2rMmMF1QLzfD5TFlSsOvMcue97pCgGn3CXeLVFtVxgpCoh0kGSXioKKzAw
 ```
 
 Operation CID:
@@ -588,26 +654,22 @@ Post-rotation: DID unchanged (`did:dfos:e3vvtck42d4eacdnzvtrn6`), controller rot
 
 ### Content Chain: Document + Create
 
-Document (application layer):
+Document (flat content object):
 
 ```json
 {
-  "content": {
-    "$schema": "https://schemas.dfos.com/post/v1",
-    "format": "short-post",
-    "title": "Hello World",
-    "body": "First post on the protocol."
-  },
-  "baseDocumentCID": null,
-  "createdByDID": "did:dfos:e3vvtck42d4eacdnzvtrn6",
-  "createdAt": "2026-03-07T00:02:00.000Z"
+  "$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:
 
 ```
-bafyreifpvwuarml62sfogdpi2vlltvg2ev6o4xtw74zfud7cpkg7426zne
+bafyreihzwuoupfg3dxip6xmgzmxsywyii2jeoxxzbgx3zxm2in7knoi3g4
 ```
 
 Content Create JWS Header:
@@ -617,7 +679,7 @@ Content Create JWS Header:
   "alg": "EdDSA",
   "typ": "did:dfos:content-op",
   "kid": "did:dfos:e3vvtck42d4eacdnzvtrn6#key_ez9a874tckr3dv933d3ckd",
-  "cid": "bafyreia5z7zxknae5ds72euihuf2rg3ixl6t4fbzjefhcogg3nqppyogqu"
+  "cid": "bafyreiaedhjq64aajpwociahl5w37j6uoxr5mojoq5dnah6fpvxr5d4lxu"
 }
 ```
 
@@ -627,7 +689,9 @@ Content Create Payload:
 {
   "version": 1,
   "type": "create",
-  "documentCID": "bafyreifpvwuarml62sfogdpi2vlltvg2ev6o4xtw74zfud7cpkg7426zne",
+  "did": "did:dfos:e3vvtck42d4eacdnzvtrn6",
+  "documentCID": "bafyreihzwuoupfg3dxip6xmgzmxsywyii2jeoxxzbgx3zxm2in7knoi3g4",
+  "baseDocumentCID": null,
   "createdAt": "2026-03-07T00:02:00.000Z",
   "note": null
 }
@@ -636,19 +700,19 @@ Content Create Payload:
 Content Create JWS Signature (hex):
 
 ```
-b7f0c3909fd398d7a42065053b6d86f96efc4281385d383d2ca4388330101da2b707ae3dd538abf5bfb0b69fa173098436ed87aa789eaafe404a2a9f16b11b0f
+46feaf973e4c7ebc2a0d4ad25481ace197de05b91051205c5e1c7067a85fb9d4abe4cc61625d3c853a8b0ce0345b534c8cdd07b34216f635d3c0bc0fd5d30306
 ```
 
 Content Create JWS Token:
 
 ```
-eyJhbGciOiJFZERTQSIsInR5cCI6ImRpZDpkZm9zOmNvbnRlbnQtb3AiLCJraWQiOiJkaWQ6ZGZvczplM3Z2dGNrNDJkNGVhY2RuenZ0cm42I2tleV9lejlhODc0dGNrcjNkdjkzM2QzY2tkIiwiY2lkIjoiYmFmeXJlaWE1ejd6eGtuYWU1ZHM3MmV1aWh1ZjJyZzNpeGw2dDRmYnpqZWZoY29nZzNucXBweW9ncXUifQ.eyJ2ZXJzaW9uIjoxLCJ0eXBlIjoiY3JlYXRlIiwiZG9jdW1lbnRDSUQiOiJiYWZ5cmVpZnB2d3Vhcm1sNjJzZm9nZHBpMnZsbHR2ZzJldjZvNHh0dzc0emZ1ZDdjcGtnNzQyNnpuZSIsImNyZWF0ZWRBdCI6IjIwMjYtMDMtMDdUMDA6MDI6MDAuMDAwWiIsIm5vdGUiOm51bGx9.t_DDkJ_TmNekIGUFO22G-W78QoE4XTg9LKQ4gzAQHaK3B6491Tir9b-wtp-hcwmENu2Hqnieqv5ASiqfFrEbDw
+eyJhbGciOiJFZERTQSIsInR5cCI6ImRpZDpkZm9zOmNvbnRlbnQtb3AiLCJraWQiOiJkaWQ6ZGZvczplM3Z2dGNrNDJkNGVhY2RuenZ0cm42I2tleV9lejlhODc0dGNrcjNkdjkzM2QzY2tkIiwiY2lkIjoiYmFmeXJlaWFlZGhqcTY0YWFqcHdvY2lhaGw1dzM3ajZ1b3hyNW1vam9xNWRuYWg2ZnB2eHI1ZDRseHUifQ.eyJ2ZXJzaW9uIjoxLCJ0eXBlIjoiY3JlYXRlIiwiZGlkIjoiZGlkOmRmb3M6ZTN2dnRjazQyZDRlYWNkbnp2dHJuNiIsImRvY3VtZW50Q0lEIjoiYmFmeXJlaWh6d3VvdXBmZzNkeGlwNnhtZ3pteHN5d3lpaTJqZW94eHpiZ3gzenhtMmluN2tub2kzZzQiLCJiYXNlRG9jdW1lbnRDSUQiOm51bGwsImNyZWF0ZWRBdCI6IjIwMjYtMDMtMDdUMDA6MDI6MDAuMDAwWiIsIm5vdGUiOm51bGx9.Rv6vlz5MfrwqDUrSVIGs4ZfeBbkQUSBcXhxwZ6hfudSr5MxhYl08hTqLDOA0W1NMjN0Hs0IW9jXTwLwP1dMDBg
 ```
 
 Content Operation CID:
 
 ```
-bafyreia5z7zxknae5ds72euihuf2rg3ixl6t4fbzjefhcogg3nqppyogqu
+bafyreiaedhjq64aajpwociahl5w37j6uoxr5mojoq5dnah6fpvxr5d4lxu
 ```
 
 ### Content Chain: Update
@@ -659,39 +723,45 @@ Content Update Payload:
 {
   "version": 1,
   "type": "update",
-  "previousOperationCID": "bafyreia5z7zxknae5ds72euihuf2rg3ixl6t4fbzjefhcogg3nqppyogqu",
-  "documentCID": "bafyreieuo26zfmjxwpmw5jk6bqzqhvivxcbckgxtyeuc7ypf3p4sihgq4q",
+  "did": "did:dfos:e3vvtck42d4eacdnzvtrn6",
+  "previousOperationCID": "bafyreiaedhjq64aajpwociahl5w37j6uoxr5mojoq5dnah6fpvxr5d4lxu",
+  "documentCID": "bafyreidh7e36cvwy3uw5ypitcqk7uoktbkkkj7e6hxhky4o75rxn7kxilu",
+  "baseDocumentCID": "bafyreihzwuoupfg3dxip6xmgzmxsywyii2jeoxxzbgx3zxm2in7knoi3g4",
   "createdAt": "2026-03-07T00:03:00.000Z",
   "note": "edited title and body"
 }
 ```
 
-Updated document:
+Updated document (flat content object):
 
 ```json
 {
-  "content": {
-    "$schema": "https://schemas.dfos.com/post/v1",
-    "format": "short-post",
-    "title": "Hello World (edited)",
-    "body": "Updated content."
-  },
-  "baseDocumentCID": "bafyreifpvwuarml62sfogdpi2vlltvg2ev6o4xtw74zfud7cpkg7426zne",
-  "createdByDID": "did:dfos:e3vvtck42d4eacdnzvtrn6",
-  "createdAt": "2026-03-07T00:03:00.000Z"
+  "$schema": "https://schemas.dfos.com/post/v1",
+  "format": "short-post",
+  "title": "Hello World (edited)",
+  "body": "Updated content.",
+  "createdByDID": "did:dfos:e3vvtck42d4eacdnzvtrn6"
 }
 ```
 
 Document CID (edited):
 
 ```
-bafyreieuo26zfmjxwpmw5jk6bqzqhvivxcbckgxtyeuc7ypf3p4sihgq4q
+bafyreidh7e36cvwy3uw5ypitcqk7uoktbkkkj7e6hxhky4o75rxn7kxilu
 ```
 
 Content Update CID:
 
 ```
-bafyreibb4lsvqmz4j76rsvhkqw3v2b4vp23t7dimm6vl5g5wlninvkemxq
+bafyreih6e5cbjitpozhzhgmfktmiohmxyn3ucwhqd3mjixizvwmlhv7hm4
+```
+
+### Content Chain Verified State
+
+```
+Content ID:   a82z92a3hndk6c97thcrn8
+Genesis CID:  bafyreiaedhjq64aajpwociahl5w37j6uoxr5mojoq5dnah6fpvxr5d4lxu
+Head CID:     bafyreih6e5cbjitpozhzhgmfktmiohmxyn3ucwhqd3mjixizvwmlhv7hm4
 ```
 
 ---
@@ -707,7 +777,7 @@ Given the artifacts above, verify:
    → 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. Note the header now contains `cid` alongside `alg`, `typ`, and `kid`.
+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:
 
@@ -731,21 +801,23 @@ Given the artifacts above, verify:
    did:dfos:e3vvtck42d4eacdnzvtrn6#key_ez9a874tckr3dv933d3ckd
    ```
 
-8. **Document CID**: dag-cbor canonical encode the document JSON → SHA-256 → CIDv1 → should be:
+8. **Document CID**: dag-cbor canonical encode the flat content object → SHA-256 → CIDv1 → should be:
 
    ```
-   bafyreifpvwuarml62sfogdpi2vlltvg2ev6o4xtw74zfud7cpkg7426zne
+   bafyreihzwuoupfg3dxip6xmgzmxsywyii2jeoxxzbgx3zxm2in7knoi3g4
    ```
 
-9. **Content chain integrity**: update's `previousOperationCID` matches create's operation CID
+9. **Content operation `did` field**: verify the `did` field in each content operation matches the `kid` DID in the JWS header
 
-10. **Chain completeness**: all operation CIDs, DID derivation, key rotation, and content chain linkage verified end-to-end.
+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.
 
 ---
 
 ## 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. 160 checks across 5 languages.
+All source lives in [`packages/dfos-protocol/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol) — self-contained, zero monorepo dependencies. 235 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`
@@ -756,23 +828,26 @@ All source lives in [`packages/dfos-protocol/`](https://github.com/metalabel/dfo
 - [`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`
+- [`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`
+- [`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 the document envelope
-- [Registry API](https://protocol.dfos.com/registry-api) — HTTP API for chain storage and resolution
+- [Content Model](https://protocol.dfos.com/content-model) — Standard content schemas (post, profile) for document content objects
 
 ### Cross-Language Verification
 
 | 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)   |
+| TypeScript | 149   | [`tests/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol/tests)                 |
+| Python     | 48    | [`verify/python/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol/verify/python) |
+| Go         | 13    | [`verify/go/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol/verify/go)         |
+| Rust       | 13    | [`verify/rust/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol/verify/rust)     |
+| Swift      | 12    | [`verify/swift/`](https://github.com/metalabel/dfos/tree/main/packages/dfos-protocol/verify/swift)   |
 
 ---
 
@@ -780,7 +855,3 @@ All source lives in [`packages/dfos-protocol/`](https://github.com/metalabel/dfo
 
 - **Vinny Bellavia** — [stcisgood.com](https://stcisgood.com)
 - **Allison Clift-Jennings** — [Jura Labs](https://juralabs.com)
-
----
-
-Yancey · Ilya · Brandon · Lena

package/README.md

@@ -1,6 +1,6 @@
 # @metalabel/dfos-protocol
 
-Ed25519 signed chain primitives, verifiable content, and registry for the DFOS Protocol.
+Cryptographic identity and content proof — Ed25519 signed chains, content-addressed CIDs, W3C DIDs. The protocol knows about keys and document hashes. It doesn't know about posts, profiles, or any application concept.
 
 ## Install
 
@@ -15,17 +15,17 @@ npm install @metalabel/dfos-protocol
 import { verifyContentChain, verifyIdentityChain } from '@metalabel/dfos-protocol/chain';
 // Crypto primitives
 import { createJws, dagCborCanonicalEncode, verifyJws } from '@metalabel/dfos-protocol/crypto';
-// Reference registry server
-import { createRegistryServer } from '@metalabel/dfos-protocol/registry';
+// Merkle trees
+import { buildMerkleTree, verifyMerkleProof } from '@metalabel/dfos-protocol/merkle';
 ```
 
 ## Subpath Exports
 
-| Export                              | Description                                                         |
-| ----------------------------------- | ------------------------------------------------------------------- |
-| `@metalabel/dfos-protocol/chain`    | Identity and content chain signing, verification, multikey encoding |
-| `@metalabel/dfos-protocol/crypto`   | Ed25519, JWS, JWT, dag-cbor, base64url, ID generation               |
-| `@metalabel/dfos-protocol/registry` | Hono-based registry server, in-memory store, Zod schemas            |
+| Export                            | Description                                                             |
+| --------------------------------- | ----------------------------------------------------------------------- |
+| `@metalabel/dfos-protocol/chain`  | Identity and content chain signing, verification, beacons, countersigns |
+| `@metalabel/dfos-protocol/crypto` | Ed25519, JWS, JWT, dag-cbor, base64url, ID generation                   |
+| `@metalabel/dfos-protocol/merkle` | SHA-256 binary merkle tree, inclusion proofs                            |
 
 ## Specifications
 
@@ -33,9 +33,7 @@ import { createRegistryServer } from '@metalabel/dfos-protocol/registry';
 | -------------------------------------- | -------------------------------------------------------------- |
 | [PROTOCOL.md](./PROTOCOL.md)           | Core protocol — chains, signatures, verification, test vectors |
 | [DID-METHOD.md](./DID-METHOD.md)       | W3C DID method specification for `did:dfos`                    |
-| [CONTENT-MODEL.md](./CONTENT-MODEL.md) | Standard content schemas (post, profile, media)                |
-| [REGISTRY-API.md](./REGISTRY-API.md)   | HTTP API for chain storage and resolution                      |
-| [openapi.yaml](./openapi.yaml)         | OpenAPI 3.1 machine-readable registry spec                     |
+| [CONTENT-MODEL.md](./CONTENT-MODEL.md) | Standard content schemas (post, profile, manifest)             |
 
 ## Examples