@metalabel/dfos-protocol 0.0.3 → 0.2.0

package/PROTOCOL.md

@@ -20,14 +20,17 @@ The protocol is not coupled to the DFOS platform. Any system implementing the sa
 
 ## Protocol Overview
 
-The DFOS protocol has two layers:
+The DFOS protocol has five 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 |
+| **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. 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
 
@@ -39,45 +42,19 @@ 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                         |
-| Content chain         | `<hash>` (bare, no prefix) | `67t27rzc83v7c22n9t6z7c`          |
-| Identity 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. 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.
 
@@ -116,19 +93,21 @@ This is a self-sovereign invariant: the identity chain defines its own valid sig
 
 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.
 
-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.
+**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 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 content chains
+- Ownership or attribution semantics beyond creator sovereignty
 
 ### Terminal States and Special Operations
 
@@ -140,7 +119,17 @@ Identity chains are self-sovereign — they define their own valid signers via `
 
 ### `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`                  | 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
 
@@ -148,6 +137,7 @@ The protocol defines maximum sizes for all operation fields as abuse-prevention
 
 | 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              |
@@ -301,22 +291,29 @@ 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 }
+  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 }
+  note: string | null,
+  authorization?: string }               // VC-JWT for delegated operations
 ```
 
 ### MultikeyPublicKey
@@ -372,7 +369,7 @@ Every operation JWS (identity-op and content-op) includes a `cid` field in the p
 
 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.
+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
 
@@ -392,6 +389,310 @@ 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
@@ -411,12 +712,14 @@ Where `idEncode` is the 19-char alphabet encoding described above.
 ### Content Chain
 
 1. Decode each JWS, parse payload as ContentOperation
-2. First op must be `type: "create"`
+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. 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. 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)
 
 ---
 
@@ -497,7 +800,7 @@ JWS Signature (hex):
 JWS Token:
 
 ```
-eyJhbGciOiJFZERTQSIsInR5cCI6ImRpZDpkZm9zOmlkZW50aXR5LW9wIiwia2lkIjoia2V5X3I5ZXYzNGZ2YzIzejk5OXZlYWFmdDgiLCJjaWQiOiJiYWZ5cmVpYmFuanBnY3FmZmNmaHI0c3B0empmdGhoNXN6b2hoYm81dGpmdWxlbWt3N3VoZGVuNXVxeSJ9.eyJ2ZXJzaW9uIjoxLCJ0eXBlIjoiY3JlYXRlIiwiYXV0aEtleXMiOlt7ImlkIjoia2V5X3I5ZXYzNGZ2YzIzejk5OXZlYWFmdDgiLCJ0eXBlIjoiTXVsdGlrZXkiLCJwdWJsaWNLZXlNdWx0aWJhc2UiOiJ6Nk1rcnpMTU53b0pTVjRQM1ljY1djYnRrOHZkOUx0Z01LbkxlYURMVXFMdUFTamIifV0sImFzc2VydEtleXMiOlt7ImlkIjoia2V5X3I5ZXYzNGZ2YzIzejk5OXZlYWFmdDgiLCJ0eXBlIjoiTXVsdGlrZXkiLCJwdWJsaWNLZXlNdWx0aWJhc2UiOiJ6Nk1rcnpMTU53b0pTVjRQM1ljY1djYnRrOHZkOUx0Z01LbkxlYURMVXFMdUFTamIifV0sImNvbnRyb2xsZXJLZXlzIjpbeyJpZCI6ImtleV9yOWV2MzRmdmMyM3o5OTl2ZWFhZnQ4IiwidHlwZSI6Ik11bHRpa2V5IiwicHVibGljS2V5TXVsdGliYXNlIjoiejZNa3J6TE1Od29KU1Y0UDNZY2NXY2J0azh2ZDlMdGdNS25MZWFETFVxTHVBU2piIn1dLCJjcmVhdGVkQXQiOiIyMDI2LTAzLTA3VDAwOjAwOjAwLjAwMFoifQ.EDryDK1uvtix-17cHun9t6MacFIx2rMmMF1QLzfD5TFlSsOvMcue97pCgGn3CXeLVFtVxgpCoh0kGSXioKKzAw
+eyJhbGciOiJFZERTQSIsInR5cCI6ImRpZDpkZm9zOmlkZW50aXR5LW9wIiwia2lkIjoia2V5X3I5ZXYzNGZ2YzIzejk5OXZlYWFmdDgiLCJjaWQiOiJiYWZ5cmVpYmFuanBnY3FmZmNmaHI0c3B0empmdGhoNXN6b2hoYm81dGpmdWxlbWt3N3VoZGVuNXVxeSJ9.eyJ2ZXJzaW9uIjoxLCJ0eXBlIjoiY3JlYXRlIiwiYXV0aEtleXMiOlt7ImlkIjoia2V5X3I5ZXYzNGZ2YzIzejk5OXZlYWFmdDgiLCJ0eXBlIjoiTXVsdGlrZXkiLCJwdWJsaWNLZXlNdWx0aWJhc2UiOiJ6Nk1rcnpMTU53b0pTVjRQM1ljY1djYnRrOHZkOUx0Z01LbkxlYURMVXFMdUFTamIifV0sImFzc2VydEtleXMiOlt7ImlkIjoia2V5X3I5ZXYzNGZ2YzIzejk5OXZlYWFmdDgiLCJ0eXBlIjoiTXVsdGlrZXkiLCJwdWJsaWNLZXlNdWx0aWJhc2UiOiJ6Nk1rcnpMTU53b0pTVjRQM1ljY1djYnRrOHZkOUx0Z01LbkxlYURMVXFMdUFTamIifV0sImNvbnRyb2xsZXJLZXlzIjpbeyJpZCI6ImtleV9yOWV2MzRmdmMyM3o5OTF2ZWFhZnQ4IiwidHlwZSI6Ik11bHRpa2V5IiwicHVibGljS2V5TXVsdGliYXNlIjoiejZNa3J6TE1Od29KU1Y0UDNZY2NXY2J0azh2ZDlMdGdNS25MZWFETFVxTHVBU2piIn1dLCJjcmVhdGVkQXQiOiIyMDI2LTAzLTA3VDAwOjAwOjAwLjAwMFoifQ.EDryDK1uvtix-17cHun9t6MacFIx2rMmMF1QLzfD5TFlSsOvMcue97pCgGn3CXeLVFtVxgpCoh0kGSXioKKzAw
 ```
 
 Operation CID:
@@ -575,26 +878,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:
@@ -604,7 +903,7 @@ Content Create JWS Header:
   "alg": "EdDSA",
   "typ": "did:dfos:content-op",
   "kid": "did:dfos:e3vvtck42d4eacdnzvtrn6#key_ez9a874tckr3dv933d3ckd",
-  "cid": "bafyreia5z7zxknae5ds72euihuf2rg3ixl6t4fbzjefhcogg3nqppyogqu"
+  "cid": "bafyreiaedhjq64aajpwociahl5w37j6uoxr5mojoq5dnah6fpvxr5d4lxu"
 }
 ```
 
@@ -614,7 +913,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
 }
@@ -623,19 +924,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
@@ -646,39 +947,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
 ```
 
 ---
@@ -718,24 +1025,31 @@ 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. **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).
 
-10. **Chain completeness**: all operation CIDs, DID derivation, key rotation, and content chain linkage verified end-to-end.
+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.
 
 ---
 
 ## 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. 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`
@@ -744,22 +1058,28 @@ All source lives in [`packages/dfos-protocol/`](https://github.com/metalabel/dfo
 - [`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 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 | 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)   |
 
 ---