@metalabel/dfos-protocol 0.1.0 → 0.3.0

package/PROTOCOL.md

@@ -20,11 +20,12 @@ The protocol is not coupled to the DFOS platform. Any system implementing the sa
 
 ## Protocol Overview
 
-The DFOS protocol has four components:
+The DFOS protocol has five components:
 
 | Component             | Concern                                                                      |
 | --------------------- | ---------------------------------------------------------------------------- |
 | **Crypto core**       | Identity chains + content chains — Ed25519 signatures, JWS tokens, CID links |
+| **Credentials**       | Auth tokens (DID-signed JWT) and VC-JWT credentials for authorization        |
 | **Beacons**           | Signed merkle root announcements — periodic commitment over content sets     |
 | **Countersignatures** | Witness attestation — third-party signatures over existing chain operations  |
 | **Merkle trees**      | SHA-256 binary trees over content IDs — inclusion proofs for beacon roots    |
@@ -92,7 +93,7 @@ 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.
 
@@ -101,13 +102,12 @@ Identity chains are self-sovereign — they define their own valid signers via `
 - 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
 
@@ -121,14 +121,15 @@ Identity chains are self-sovereign — they define their own valid signers via `
 
 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        |
+| `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)     |
 
-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.
+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
 
@@ -303,14 +304,16 @@ DID:    did:dfos:e3vvtck42d4eacdnzvtrn6
   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
@@ -366,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
 
@@ -386,6 +389,122 @@ 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.
@@ -397,8 +516,8 @@ A beacon is a signed announcement of a merkle root — a periodic commitment ove
   "version": 1,
   "type": "beacon",
   "did": "did:dfos:e3vvtck42d4eacdnzvtrn6",
-  "merkleRoot": "a3f8b2c1d4e5f6071829304a5b6c7d8e9f0a1b2c3d4e5f6071829304a5b6c7d8",
-  "createdAt": "2026-03-07T00:04:00.000Z"
+  "merkleRoot": "7e80d4780f454e0fca0b090d8c646f572b49354f54154531606105aad2fda28e",
+  "createdAt": "2026-03-07T00:05:00.000Z"
 }
 ```
 
@@ -416,11 +535,41 @@ A beacon is a signed announcement of a merkle root — a periodic commitment ove
 {
   "alg": "EdDSA",
   "typ": "did:dfos:beacon",
-  "kid": "did:dfos:e3vvtck42d4eacdnzvtrn6#key_ez9a874tckr3dv933d3ckd",
-  "cid": "bafyrei..."
+  "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.
@@ -445,10 +594,84 @@ Beacons commit to a set of content IDs via a pure SHA-256 binary Merkle tree. Th
 
 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
@@ -489,13 +712,14 @@ Countersignatures are not part of the chain — they do not have `previousOperat
 ### 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. 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)
+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)
 
 ---
 
@@ -813,14 +1037,19 @@ Given the artifacts above, verify:
 
 11. **Chain completeness**: all operation CIDs, DID derivation, key rotation, and content chain linkage verified end-to-end.
 
+12. **VC-JWT credential verify**: using the issuer's public key, verify a `DFOSContentWrite` or `DFOSContentRead` credential: check EdDSA signature, `typ: "vc+jwt"`, expiration, `kid` DID URL format, `kid` DID matches `iss`, `vc` claim structure matches W3C VC Data Model v2, credential type matches expected DFOS type. Test vectors in [`examples/credential-write.json`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/examples/credential-write.json) and [`examples/credential-read.json`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/examples/credential-read.json).
+
+13. **Delegated content chain verify**: using [`examples/content-delegated.json`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/examples/content-delegated.json), verify a content chain where the genesis is signed by the creator and a subsequent update is signed by a delegate with an embedded `DFOSContentWrite` VC-JWT in the `authorization` field. The VC must be issued by the creator DID, with `sub` matching the delegate DID.
+
 ---
 
 ## 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. 235 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`
@@ -831,6 +1060,9 @@ All source lives in [`packages/dfos-protocol/`](https://github.com/metalabel/dfo
 - [`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`
 
@@ -843,11 +1075,11 @@ All source lives in [`packages/dfos-protocol/`](https://github.com/metalabel/dfo
 
 | Language   | Tests | Source                                                                                               |
 | ---------- | ----- | ---------------------------------------------------------------------------------------------------- |
-| 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)   |
+| 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)   |
 
 ---
 

package/README.md

@@ -13,6 +13,8 @@ npm install @metalabel/dfos-protocol
 ```ts
 // Chain verification
 import { verifyContentChain, verifyIdentityChain } from '@metalabel/dfos-protocol/chain';
+// Credentials (auth tokens + VC-JWT)
+import { createAuthToken, verifyCredential } from '@metalabel/dfos-protocol/credentials';
 // Crypto primitives
 import { createJws, dagCborCanonicalEncode, verifyJws } from '@metalabel/dfos-protocol/crypto';
 // Merkle trees
@@ -21,11 +23,12 @@ import { buildMerkleTree, verifyMerkleProof } from '@metalabel/dfos-protocol/mer
 
 ## Subpath Exports
 
-| 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                            |
+| Export                                 | Description                                                             |
+| -------------------------------------- | ----------------------------------------------------------------------- |
+| `@metalabel/dfos-protocol/chain`       | Identity and content chain signing, verification, beacons, countersigns |
+| `@metalabel/dfos-protocol/credentials` | Auth tokens (DID-signed JWT) and VC-JWT credentials for authorization   |
+| `@metalabel/dfos-protocol/crypto`      | Ed25519, JWS, JWT, dag-cbor, base64url, ID generation                   |
+| `@metalabel/dfos-protocol/merkle`      | SHA-256 binary merkle tree, inclusion proofs                            |
 
 ## Specifications
 
@@ -37,13 +40,18 @@ import { buildMerkleTree, verifyMerkleProof } from '@metalabel/dfos-protocol/mer
 
 ## Examples
 
-The `examples/` directory contains deterministic reference chain fixtures that can be independently verified by any Ed25519 + dag-cbor implementation:
+The `examples/` directory contains deterministic reference fixtures that can be independently verified by any Ed25519 + dag-cbor implementation:
 
 - `identity-genesis.json` — single create operation
 - `identity-rotation.json` — genesis + key rotation
 - `identity-delete.json` — genesis + delete (terminal)
 - `content-lifecycle.json` — create + update (with both documents)
 - `content-delete.json` — create + delete
+- `content-delegated.json` — creator genesis + delegated update with DFOSContentWrite VC-JWT
+- `credential-write.json` — DFOSContentWrite VC-JWT (broad + content-narrowed)
+- `credential-read.json` — DFOSContentRead VC-JWT
+- `merkle-tree.json` — 5 content IDs → sorted tree → root, with inclusion proof
+- `beacon.json` — signed merkle root announcement with witness countersignature
 
 ## License
 

package/dist/chain/index.d.ts

@@ -91,6 +91,8 @@ declare const ContentOperation: z.ZodDiscriminatedUnion<[z.ZodObject<{
     baseDocumentCID: z.ZodNullable<z.ZodString>;
     createdAt: z.ZodISODateTime;
     note: z.ZodNullable<z.ZodString>;
+    /** VC-JWT authorizing this operation when signer is not the chain creator */
+    authorization: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>, z.ZodObject<{
     version: z.ZodLiteral<1>;
     type: z.ZodLiteral<"delete">;
@@ -98,6 +100,8 @@ declare const ContentOperation: z.ZodDiscriminatedUnion<[z.ZodObject<{
     previousOperationCID: z.ZodString;
     createdAt: z.ZodISODateTime;
     note: z.ZodNullable<z.ZodString>;
+    /** VC-JWT authorizing this operation when signer is not the chain creator */
+    authorization: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>], "type">;
 type ContentOperation = z.infer<typeof ContentOperation>;
 /** Beacon: floating signed merkle root announcement */
@@ -182,6 +186,8 @@ interface VerifiedContentChain {
     currentDocumentCID: string | null;
     /** Number of operations in the chain */
     length: number;
+    /** The DID that created the chain (signer of genesis operation) */
+    creatorDID: string;
 }
 /**
  * Sign a content chain operation as a JWS and derive the operation CID
@@ -196,15 +202,30 @@ declare const signContentOperation: (input: {
     operationCID: string;
 }>;
 /**
- * Verify a content chain's structural integrity and signatures
+ * Verify a content chain's structural integrity, signatures, and authorization
  *
  * The caller provides a key resolver to look up public keys from kid values.
  * This keeps the content chain protocol independent of identity resolution.
+ *
+ * Authorization rules:
+ * - Genesis (create) operation: the signer is the chain creator, always authorized
+ * - Subsequent operations signed by the creator DID: authorized (no credential needed)
+ * - Subsequent operations signed by a different DID: must include an `authorization`
+ *   field containing a valid DFOSContentWrite VC-JWT issued by the creator DID
  */
 declare const verifyContentChain: (input: {
     log: string[];
     /** Resolve a kid (DID URL) to the raw Ed25519 public key bytes */
     resolveKey: (kid: string) => Promise<Uint8Array>;
+    /**
+     * Enforce creator-sovereignty authorization. When true, non-creator signers
+     * must include a DFOSContentWrite VC-JWT in the operation's `authorization`
+     * field. When false (default), any signer with a valid signature is accepted.
+     *
+     * Web relays should set this to true. Applications migrating to VC-based
+     * authorization can enable this once all chains include authorization fields.
+     */
+    enforceAuthorization?: boolean;
 }) => Promise<VerifiedContentChain>;
 
 /**

package/dist/chain/index.js

@@ -19,7 +19,8 @@ import {
   verifyContentChain,
   verifyCountersignature,
   verifyIdentityChain
-} from "../chunk-ASGEXSVT.js";
+} from "../chunk-GEVJ3SEV.js";
+import "../chunk-CZSEEZLL.js";
 import "../chunk-ZXXP5W5N.js";
 export {
   BeaconPayload,