@metalabel/dfos-protocol 0.0.2 → 0.0.3

package/CONTENT-MODEL.md

@@ -86,7 +86,7 @@ A content chain is a signed append-only log. The protocol enforces ordering, aut
 
 ### Living Document
 
-The chain represents a single evolving thing — a profile, a post, a policy document. Each operation is a **revision**. The resolved state is the latest `documentCID`. History is audit trail. The entity _is_ the current version.
+The chain represents a single evolving thing — a profile, a post, a policy document. Each operation is a **revision**. The resolved state is the latest `documentCID`. History is audit trail. The content _is_ the current version.
 
 This is the default interpretation for the standard schemas. The document envelope's `baseDocumentCID` field supports edit lineage — each new document version can point back to the one it replaced.
 

package/PROTOCOL.md

@@ -10,21 +10,11 @@ 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.
 
 ---
 
@@ -77,11 +67,11 @@ The `documentCID` in a content chain operation is `CID(dagCborEncode(envelope))`
 
 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` |
+| 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` |
 
 Example CID:
 
@@ -89,7 +79,7 @@ Example CID:
 bafyreibanjpgcqffcfhr4sptzjfthh5szohhbo5tjfulemkw7uhden5uqy
 ```
 
-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 +89,20 @@ Application code may add prefixes for routing (e.g., `post_xxxx`) — these are
 
 ### Commitment Scheme
 
-The protocol requires a **deterministic payload commitment**: given the same logical operation, the commitment (CID) MUST be identical regardless of implementation language or platform. The commitment scheme is **dag-cbor canonical encoding + SHA-256 + CIDv1**. This is not a recommendation — it is the protocol.
+Both operations and documents are content-addressed via **CID** (`dagCborCanonicalEncode(payload)` → SHA-256 → CIDv1). Operations are additionally signed via **JWS**.
 
-Implementations MUST use dag-cbor canonical encoding as defined by the [IPLD dag-cbor codec specification](https://ipld.io/specs/codecs/dag-cbor/spec/). Raw JSON serialization, pretty-printed JSON, or any non-canonical encoding MUST NOT be used for CID derivation. The dag-cbor hex test vectors in this document allow byte-level verification of any implementation's canonical encoding.
+| Representation | Encoding                                                                                                       | Purpose                                                       |
+| -------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| CID            | `dagCborCanonicalEncode(payload)` → SHA-256 → CIDv1                                                            | Deterministic content addressing for operations and documents |
+| JWS            | `base64url(JSON.stringify(header))` + `.` + `base64url(JSON.stringify(payload))` → EdDSA signature covers both | Signature verification for operations                         |
 
-**JWS signing vs CID derivation are intentionally different representations of the same payload.** JWS signs `base64url(JSON.stringify(payload))` — the UTF-8 bytes of the JSON serialization. CID commits to `dagCborCanonicalEncode(payload)` — the dag-cbor canonical encoding of the parsed object. These produce different bytes from the same logical data. This is by design: JWS uses standard JSON for maximum interoperability with existing JWS libraries, while CID uses dag-cbor for deterministic content addressing.
+CID uses [dag-cbor canonical encoding](https://ipld.io/specs/codecs/dag-cbor/spec/) for determinism — given the same logical payload, the CID MUST be identical regardless of implementation language or platform. JWS uses standard JSON for library interoperability. The dag-cbor hex test vectors in this document allow byte-level verification.
 
 ### Chain Validity
 
 A valid chain is a **linear sequence** of operations. Each operation (after genesis) links to its predecessor via `previousOperationCID`. The chain provides structural ordering independent of timestamps.
 
-**Forks are invalid at the protocol level.** Two operations referencing the same `previousOperationCID` constitute a fork. The protocol does not define fork resolution — this is application-defined. In DFOS's custodial model, forks are prevented by database-level advisory locks. A non-custodial implementation would need its own fork resolution strategy (e.g., longest chain, first-seen, application-specified preference).
+**Forks are invalid at the protocol level.** Two operations referencing the same `previousOperationCID` constitute a fork. The protocol does not define fork resolution — this is application-defined (e.g., longest chain, first-seen, advisory locks).
 
 **Timestamp ordering**: `createdAt` SHOULD be strictly increasing within a chain. Implementations SHOULD reject operations with non-increasing timestamps as a sanity check against replayed or mis-ordered operations. However, the chain link (CID reference) is the authoritative ordering mechanism, not the timestamp. Implementations MAY relax timestamp ordering in constrained environments where clock synchronization is impractical.
 
@@ -121,11 +114,9 @@ This is a self-sovereign invariant: the identity chain defines its own valid sig
 
 ### Content Chain Signer Model
 
-Content chain verification requires a **valid EdDSA signature** — nothing more. The protocol does not define which identities may sign operations on a content chain, does not track or enforce key roles, and does not restrict a chain to a single signer.
+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.
-
-This is a deliberate asymmetry with identity chains. Identity chains are self-sovereign — they define their own valid signers internally. Content chains are externally signed — the signing authority model is entirely an application concern, delegated through `resolveKey`. A content chain with operations signed by multiple different identities is valid at the protocol level, as long as each operation's signature verifies against the resolved key.
+Identity chains are self-sovereign — they define their own valid signers via `controllerKeys`. Content chains are externally signed — a content chain with operations signed by multiple different identities is valid at the protocol level, as long as each signature verifies against the resolved key.
 
 **What the protocol enforces:**
 
@@ -137,7 +128,7 @@ This is a deliberate asymmetry with identity chains. Identity chains are self-so
 - Which identities are authorized to sign operations on a given chain
 - Which key role (auth, assert, controller) the signing key must have
 - Whether a chain must have a single signer or may have multiple signers
-- Ownership or attribution semantics between signers and entities
+- Ownership or attribution semantics between signers and content chains
 
 ### Terminal States and Special Operations
 
@@ -145,7 +136,7 @@ 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
 
@@ -153,7 +144,7 @@ The JWS `typ` header (`did:dfos:identity-op`, `did:dfos:content-op`) aids routin
 
 ### 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                              |
 | -------------------------------------------- | --------- | -------------------------------------- |
@@ -321,7 +312,7 @@ DID:    did:dfos:e3vvtck42d4eacdnzvtrn6
   createdAt: string,
   note: string | null }
 
-// Permanent entity destruction
+// Permanent destruction
 { version: 1, type: "delete",
   previousOperationCID: string,
   createdAt: string,
@@ -379,11 +370,7 @@ Every operation JWS (identity-op and content-op) includes a `cid` field in the p
 - `header.cid` is missing
 - `header.cid` does not match the derived CID
 
-This provides three benefits:
-
-- **Pre-verification routing**: The operation CID can be read from the header without parsing the payload or running dag-cbor encoding
-- **Cross-implementation consistency**: A CID mismatch between header and derived value immediately surfaces dag-cbor encoding disagreements across implementations
-- **Self-documenting tokens**: Each JWS token declares its content-addressed identity
+A CID mismatch between header and derived value immediately surfaces dag-cbor encoding disagreements across implementations.
 
 Note: JWT tokens (device auth) do NOT include a `cid` header — this field is specific to operation JWS tokens.
 
@@ -435,7 +422,7 @@ Where `idEncode` is the 19-char alphabet encoding described above.
 
 ## Deterministic Reference Artifacts
 
-All values below are deterministic and reproducible. Private keys are derived from `SHA-256(UTF8("dfos-protocol-reference-key-N"))`.
+All artifacts below are deterministic and reproducible from fixed seeds. An independent implementer can verify every value using standard Ed25519 + dag-cbor libraries. Private keys are derived from `SHA-256(UTF8("dfos-protocol-reference-key-N"))`.
 
 ### Key 1 (Genesis Controller)
 
@@ -707,7 +694,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:
 
@@ -756,7 +743,7 @@ 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`
 
 ### Related Specifications
 
@@ -780,7 +767,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
 

package/REGISTRY-API.md

@@ -2,7 +2,7 @@
 
 Minimal HTTP API for chain storage, retrieval, and resolution. Any server implementing these endpoints with these semantics is a compatible DFOS registry.
 
-The protocol is transport-agnostic — chains can be exchanged through any mechanism. This API defines one standard transport binding: a REST interface for submitting chains, resolving identities and entities, and retrieving operations and documents.
+The protocol is transport-agnostic — chains can be exchanged through any mechanism. This API defines one standard transport binding: a REST interface for submitting chains, resolving identities and content, and retrieving operations and documents.
 
 [Protocol Specification](https://protocol.dfos.com/spec) · [OpenAPI Spec](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/openapi.yaml) · [Reference Implementation](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/registry/server.ts)
 
@@ -17,7 +17,7 @@ Six endpoints, two concerns:
 | Concern             | Endpoints                                       |
 | ------------------- | ----------------------------------------------- |
 | **Identity chains** | Submit chain, resolve identity, list operations |
-| **Content chains**  | Submit chain, resolve entity, list operations   |
+| **Content chains**  | Submit chain, resolve content, list operations  |
 | **Lookup**          | Resolve operation by CID                        |
 
 All request and response bodies are JSON (`application/json`).
@@ -105,9 +105,9 @@ Returns operations newest-first, paginated.
 
 ## Content Endpoints
 
-### `POST /entities` — Submit or extend a content chain
+### `POST /content` — Submit or extend a content chain
 
-Same mechanics as identity submission. The registry verifies the chain (resolving signing keys from stored identity chains), derives the entity ID from the genesis CID, and stores it.
+Same mechanics as identity submission. The registry verifies the chain (resolving signing keys from stored identity chains), derives the content ID from the genesis CID, and stores it.
 
 **Request:** Same `{ "chain": [...] }` format as identity submission.
 
@@ -115,21 +115,21 @@ Same mechanics as identity submission. The registry verifies the chain (resolvin
 
 ---
 
-### `GET /entities/{entityId}` — Resolve current entity state
+### `GET /content/{contentId}` — Resolve current content state
 
-Returns the current state for a content chain entity.
+Returns the current state for a content chain.
 
 **Parameters:**
 
-| Name       | In   | Pattern                     | Example                  |
-| ---------- | ---- | --------------------------- | ------------------------ |
-| `entityId` | path | `[2346789acdefhknrtvz]{22}` | `67t27rzc83v7c22n9t6z7c` |
+| Name        | In   | Pattern                     | Example                  |
+| ----------- | ---- | --------------------------- | ------------------------ |
+| `contentId` | path | `[2346789acdefhknrtvz]{22}` | `67t27rzc83v7c22n9t6z7c` |
 
-**Response (`EntityState`):**
+**Response (`ContentState`):**
 
 ```json
 {
-  "entityId": "67t27rzc83v7c22n9t6z7c",
+  "contentId": "67t27rzc83v7c22n9t6z7c",
   "isDeleted": false,
   "currentDocumentCID": "bafyrei...",
   "genesisCID": "bafyrei...",
@@ -145,7 +145,7 @@ Returns the current state for a content chain entity.
 
 ---
 
-### `GET /entities/{entityId}/operations` — List content chain operations
+### `GET /content/{contentId}/operations` — List content chain operations
 
 Same pagination mechanics as identity operations.
 
@@ -182,7 +182,7 @@ All error responses follow a standard shape:
 | Error Code    | Used By                                                    |
 | ------------- | ---------------------------------------------------------- |
 | `BAD_REQUEST` | Invalid chain, malformed request                           |
-| `NOT_FOUND`   | Identity, entity, operation, or document not found         |
+| `NOT_FOUND`   | Identity, content, or operation not found                  |
 | `CONFLICT`    | Fork detected — submitted chain diverges from stored chain |
 
 ---

package/dist/chain/index.d.ts

@@ -124,12 +124,12 @@ declare const decodeMultikey: (multibase: string) => {
  */
 declare const deriveChainIdentifier: (cidBytes: Uint8Array, prefix: string) => string;
 /**
- * Derive a bare entity identifier from CID bytes
+ * Derive a bare content identifier from CID bytes
  *
  * Returns the raw 22-char hash with no prefix. Applications may add
  * their own prefix for routing (e.g., post_xxxx) — that's semantic sugar.
  */
-declare const deriveEntityId: (cidBytes: Uint8Array) => string;
+declare const deriveContentId: (cidBytes: Uint8Array) => string;
 
 /**
  * Sign an identity operation as a JWS and derive the operation CID
@@ -156,8 +156,8 @@ declare const verifyIdentityChain: (input: {
 }) => Promise<VerifiedIdentity>;
 
 interface VerifiedContentChain {
-    /** Entity identifier — bare 22-char hash derived from genesis CID */
-    entityId: string;
+    /** Content identifier — bare 22-char hash derived from genesis CID */
+    contentId: string;
     /** CID of the genesis operation */
     genesisCID: string;
     /** CID of the most recent operation */
@@ -193,4 +193,4 @@ declare const verifyContentChain: (input: {
     resolveKey: (kid: string) => Promise<Uint8Array>;
 }) => Promise<VerifiedContentChain>;
 
-export { ContentOperation, ED25519_PRIV_MULTICODEC, ED25519_PUB_MULTICODEC, IdentityOperation, MultikeyPublicKey, type Signer, type VerifiedContentChain, VerifiedIdentity, decodeMultikey, deriveChainIdentifier, deriveEntityId, encodeEd25519Multikey, signContentOperation, signIdentityOperation, verifyContentChain, verifyIdentityChain };
+export { ContentOperation, ED25519_PRIV_MULTICODEC, ED25519_PUB_MULTICODEC, IdentityOperation, MultikeyPublicKey, type Signer, type VerifiedContentChain, VerifiedIdentity, decodeMultikey, deriveChainIdentifier, deriveContentId, encodeEd25519Multikey, signContentOperation, signIdentityOperation, verifyContentChain, verifyIdentityChain };

package/dist/chain/index.js

@@ -7,13 +7,13 @@ import {
   VerifiedIdentity,
   decodeMultikey,
   deriveChainIdentifier,
-  deriveEntityId,
+  deriveContentId,
   encodeEd25519Multikey,
   signContentOperation,
   signIdentityOperation,
   verifyContentChain,
   verifyIdentityChain
-} from "../chunk-LWC4PWGZ.js";
+} from "../chunk-VEBMLR37.js";
 import "../chunk-ZXXP5W5N.js";
 export {
   ContentOperation,
@@ -24,7 +24,7 @@ export {
   VerifiedIdentity,
   decodeMultikey,
   deriveChainIdentifier,
-  deriveEntityId,
+  deriveContentId,
   encodeEd25519Multikey,
   signContentOperation,
   signIdentityOperation,

package/dist/{chunk-4MMWM2PC.js → chunk-U6DANYPT.js}

@@ -3,7 +3,7 @@ import {
   decodeMultikey,
   verifyContentChain,
   verifyIdentityChain
-} from "./chunk-LWC4PWGZ.js";
+} from "./chunk-VEBMLR37.js";
 import {
   dagCborCanonicalEncode,
   decodeJwsUnsafe
@@ -41,15 +41,15 @@ var SubmitContentChainRequest = z.strictObject({
   chain: z.array(z.string()).min(1)
 });
 var SubmitContentChainResponse = z.strictObject({
-  entityId: z.string(),
+  contentId: z.string(),
   isDeleted: z.boolean(),
   currentDocumentCID: z.string().nullable(),
   genesisCID: z.string(),
   headCID: z.string()
 });
-var ResolveEntityResponse = SubmitContentChainResponse;
-var EntityOperationsParams = PaginationParams;
-var EntityOperationsResponse = PaginatedOperations;
+var ResolveContentResponse = SubmitContentChainResponse;
+var ContentOperationsParams = PaginationParams;
+var ContentOperationsResponse = PaginatedOperations;
 var ResolveOperationResponse = z.strictObject({
   cid: z.string(),
   jwsToken: z.string()
@@ -64,11 +64,11 @@ import { Hono } from "hono";
 
 // src/registry/store.ts
 var ChainStore = class {
-  identities = /* @__PURE__ */ new Map();
-  entities = /* @__PURE__ */ new Map();
-  // --- identities ---
+  identityChains = /* @__PURE__ */ new Map();
+  contentChains = /* @__PURE__ */ new Map();
+  // --- identityChains ---
   getIdentityChain(did) {
-    return this.identities.get(did);
+    return this.identityChains.get(did);
   }
   /**
    * Submit an identity chain. Returns 'accepted' | 'noop' | 'conflict'.
@@ -77,22 +77,22 @@ var ChainStore = class {
    * - conflict: submitted chain diverges from stored chain (fork)
    */
   submitIdentityChain(did, operations) {
-    return this.submitChain(this.identities, did, operations);
+    return this.submitChain(this.identityChains, did, operations);
   }
-  // --- entities ---
-  getEntityChain(entityId) {
-    return this.entities.get(entityId);
+  // --- contentChains ---
+  getContentChain(contentId) {
+    return this.contentChains.get(contentId);
   }
-  submitEntityChain(entityId, operations) {
-    return this.submitChain(this.entities, entityId, operations);
+  submitContentChain(contentId, operations) {
+    return this.submitChain(this.contentChains, contentId, operations);
   }
   // --- operations (lookup across all chains) ---
   getOperation(cid) {
-    for (const chain of this.identities.values()) {
+    for (const chain of this.identityChains.values()) {
       const op = chain.operations.find((o) => o.cid === cid);
       if (op) return op;
     }
-    for (const chain of this.entities.values()) {
+    for (const chain of this.contentChains.values()) {
       const op = chain.operations.find((o) => o.cid === cid);
       if (op) return op;
     }
@@ -233,7 +233,7 @@ var createRegistryServer = (store = new ChainStore()) => {
     const { cursor, limit } = paginationParams(c.req);
     return c.json(paginate(chain.operations, cursor, limit));
   });
-  app.post("/entities", async (c) => {
+  app.post("/content", async (c) => {
     const body = await c.req.json();
     if (!body.chain || !Array.isArray(body.chain) || body.chain.length === 0) {
       return c.json(err("BAD_REQUEST", "chain must be a non-empty array of JWS tokens"), 400);
@@ -245,13 +245,13 @@ var createRegistryServer = (store = new ChainStore()) => {
     } catch (e) {
       return c.json(err("BAD_REQUEST", `chain verification failed: ${e.message}`), 400);
     }
-    const result = store.submitEntityChain(verified.entityId, operations);
+    const result = store.submitContentChain(verified.contentId, operations);
     if (result === "conflict") {
       return c.json(err("CONFLICT", "submitted chain conflicts with stored chain"), 409);
     }
     return c.json(
       {
-        entityId: verified.entityId,
+        contentId: verified.contentId,
         isDeleted: verified.isDeleted,
         currentDocumentCID: verified.currentDocumentCID,
         genesisCID: verified.genesisCID,
@@ -260,27 +260,27 @@ var createRegistryServer = (store = new ChainStore()) => {
       result === "accepted" ? 201 : 200
     );
   });
-  app.get("/entities/:entityId", (c) => {
-    const entityId = c.req.param("entityId");
-    const chain = store.getEntityChain(entityId);
-    if (!chain) return c.json(err("NOT_FOUND", "entity not found"), 404);
+  app.get("/content/:contentId", (c) => {
+    const contentId = c.req.param("contentId");
+    const chain = store.getContentChain(contentId);
+    if (!chain) return c.json(err("NOT_FOUND", "content not found"), 404);
     const genesis = chain.operations[0];
     const head = chain.operations[chain.operations.length - 1];
     const headDecoded = decodeJwsUnsafe(head.jwsToken);
     const headPayload = headDecoded?.payload;
     const headType = headPayload?.type;
     return c.json({
-      entityId,
+      contentId,
       isDeleted: headType === "delete",
       currentDocumentCID: headType === "delete" ? null : headPayload?.documentCID ?? null,
       genesisCID: genesis.cid,
       headCID: head.cid
     });
   });
-  app.get("/entities/:entityId/operations", (c) => {
-    const entityId = c.req.param("entityId");
-    const chain = store.getEntityChain(entityId);
-    if (!chain) return c.json(err("NOT_FOUND", "entity not found"), 404);
+  app.get("/content/:contentId/operations", (c) => {
+    const contentId = c.req.param("contentId");
+    const chain = store.getContentChain(contentId);
+    if (!chain) return c.json(err("NOT_FOUND", "content not found"), 404);
     const { cursor, limit } = paginationParams(c.req);
     return c.json(paginate(chain.operations, cursor, limit));
   });
@@ -301,9 +301,9 @@ export {
   IdentityOperationsResponse,
   SubmitContentChainRequest,
   SubmitContentChainResponse,
-  ResolveEntityResponse,
-  EntityOperationsParams,
-  EntityOperationsResponse,
+  ResolveContentResponse,
+  ContentOperationsParams,
+  ContentOperationsResponse,
   ResolveOperationResponse,
   RegistryError,
   ChainStore,

package/dist/{chunk-LWC4PWGZ.js → chunk-VEBMLR37.js}

@@ -127,7 +127,7 @@ var deriveChainIdentifier = (cidBytes, prefix) => {
   const id = generateIdNoPrefix({ seed: cidBytes });
   return `${prefix}:${id}`;
 };
-var deriveEntityId = (cidBytes) => {
+var deriveContentId = (cidBytes) => {
   return generateIdNoPrefix({ seed: cidBytes });
 };
 
@@ -289,7 +289,7 @@ var signContentOperation = async (input) => {
 var verifyContentChain = async (input) => {
   if (input.log.length === 0) throw new Error("log must have at least one operation");
   const state = {
-    entityId: null,
+    contentId: null,
     genesisCID: null,
     headCID: null,
     isDeleted: false,
@@ -339,7 +339,7 @@ var verifyContentChain = async (input) => {
     }
     if (idx === 0) {
       state.genesisCID = operationCID;
-      state.entityId = deriveEntityId(encoded.cid.bytes);
+      state.contentId = deriveContentId(encoded.cid.bytes);
     }
     state.headCID = operationCID;
     state.previousCID = operationCID;
@@ -358,7 +358,7 @@ var verifyContentChain = async (input) => {
     }
   }
   return {
-    entityId: state.entityId,
+    contentId: state.contentId,
     genesisCID: state.genesisCID,
     headCID: state.headCID,
     isDeleted: state.isDeleted,
@@ -377,7 +377,7 @@ export {
   encodeEd25519Multikey,
   decodeMultikey,
   deriveChainIdentifier,
-  deriveEntityId,
+  deriveContentId,
   signIdentityOperation,
   verifyIdentityChain,
   signContentOperation,

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { JwsHeader, JwsVerificationError, JwtClaims, JwtCreateOptions, JwtHeader, JwtVerificationError, JwtVerifyOptions, PrefixedID, base64urlDecode, base64urlEncode, createJws, createJwt, createNewEd25519Keypair, dagCborCanonicalEncode, decodeJwsUnsafe, decodeJwtUnsafe, generateId, generateIdNoPrefix, importEd25519Keypair, isCanonicallyEqual, isValidEd25519Signature, isValidId, normalizedId, parseDagCborCID, signPayloadEd25519, verifyJws, verifyJwt } from './crypto/index.js';
-export { ContentOperation, ED25519_PRIV_MULTICODEC, ED25519_PUB_MULTICODEC, IdentityOperation, MultikeyPublicKey, Signer, VerifiedContentChain, VerifiedIdentity, decodeMultikey, deriveChainIdentifier, deriveEntityId, encodeEd25519Multikey, signContentOperation, signIdentityOperation, verifyContentChain, verifyIdentityChain } from './chain/index.js';
-export { ChainStore, EntityOperationsParams, EntityOperationsResponse, IdentityOperationsParams, IdentityOperationsResponse, OperationEntry, PaginationParams, RegistryError, ResolveEntityResponse, ResolveIdentityResponse, ResolveOperationResponse, StoredChain, SubmitContentChainRequest, SubmitContentChainResponse, SubmitIdentityChainRequest, SubmitIdentityChainResponse, createRegistryServer } from './registry/index.js';
+export { ContentOperation, ED25519_PRIV_MULTICODEC, ED25519_PUB_MULTICODEC, IdentityOperation, MultikeyPublicKey, Signer, VerifiedContentChain, VerifiedIdentity, decodeMultikey, deriveChainIdentifier, deriveContentId, encodeEd25519Multikey, signContentOperation, signIdentityOperation, verifyContentChain, verifyIdentityChain } from './chain/index.js';
+export { ChainStore, ContentOperationsParams, ContentOperationsResponse, IdentityOperationsParams, IdentityOperationsResponse, OperationEntry, PaginationParams, RegistryError, ResolveContentResponse, ResolveIdentityResponse, ResolveOperationResponse, StoredChain, SubmitContentChainRequest, SubmitContentChainResponse, SubmitIdentityChainRequest, SubmitIdentityChainResponse, createRegistryServer } from './registry/index.js';
 import 'multiformats';
 import 'multiformats/cid';
 import 'zod';

package/dist/index.js

@@ -1,11 +1,11 @@
 import {
   ChainStore,
-  EntityOperationsParams,
-  EntityOperationsResponse,
+  ContentOperationsParams,
+  ContentOperationsResponse,
   IdentityOperationsParams,
   IdentityOperationsResponse,
   RegistryError,
-  ResolveEntityResponse,
+  ResolveContentResponse,
   ResolveIdentityResponse,
   ResolveOperationResponse,
   SubmitContentChainRequest,
@@ -13,7 +13,7 @@ import {
   SubmitIdentityChainRequest,
   SubmitIdentityChainResponse,
   createRegistryServer
-} from "./chunk-4MMWM2PC.js";
+} from "./chunk-U6DANYPT.js";
 import {
   ContentOperation,
   ED25519_PRIV_MULTICODEC,
@@ -23,13 +23,13 @@ import {
   VerifiedIdentity,
   decodeMultikey,
   deriveChainIdentifier,
-  deriveEntityId,
+  deriveContentId,
   encodeEd25519Multikey,
   signContentOperation,
   signIdentityOperation,
   verifyContentChain,
   verifyIdentityChain
-} from "./chunk-LWC4PWGZ.js";
+} from "./chunk-VEBMLR37.js";
 import {
   JwsVerificationError,
   JwtVerificationError,
@@ -56,10 +56,10 @@ import {
 export {
   ChainStore,
   ContentOperation,
+  ContentOperationsParams,
+  ContentOperationsResponse,
   ED25519_PRIV_MULTICODEC,
   ED25519_PUB_MULTICODEC,
-  EntityOperationsParams,
-  EntityOperationsResponse,
   IdentityOperation,
   IdentityOperationsParams,
   IdentityOperationsResponse,
@@ -67,7 +67,7 @@ export {
   JwtVerificationError,
   MultikeyPublicKey,
   RegistryError,
-  ResolveEntityResponse,
+  ResolveContentResponse,
   ResolveIdentityResponse,
   ResolveOperationResponse,
   SubmitContentChainRequest,
@@ -86,7 +86,7 @@ export {
   decodeJwtUnsafe,
   decodeMultikey,
   deriveChainIdentifier,
-  deriveEntityId,
+  deriveContentId,
   encodeEd25519Multikey,
   generateId,
   generateIdNoPrefix,

package/dist/registry/index.d.ts

@@ -75,26 +75,26 @@ declare const SubmitContentChainRequest: z.ZodObject<{
 }, z.core.$strict>;
 type SubmitContentChainRequest = z.infer<typeof SubmitContentChainRequest>;
 declare const SubmitContentChainResponse: z.ZodObject<{
-    entityId: z.ZodString;
+    contentId: z.ZodString;
     isDeleted: z.ZodBoolean;
     currentDocumentCID: z.ZodNullable<z.ZodString>;
     genesisCID: z.ZodString;
     headCID: z.ZodString;
 }, z.core.$strict>;
 type SubmitContentChainResponse = z.infer<typeof SubmitContentChainResponse>;
-declare const ResolveEntityResponse: z.ZodObject<{
-    entityId: z.ZodString;
+declare const ResolveContentResponse: z.ZodObject<{
+    contentId: z.ZodString;
     isDeleted: z.ZodBoolean;
     currentDocumentCID: z.ZodNullable<z.ZodString>;
     genesisCID: z.ZodString;
     headCID: z.ZodString;
 }, z.core.$strict>;
-type ResolveEntityResponse = SubmitContentChainResponse;
-declare const EntityOperationsParams: z.ZodObject<{
+type ResolveContentResponse = SubmitContentChainResponse;
+declare const ContentOperationsParams: z.ZodObject<{
     cursor: z.ZodOptional<z.ZodString>;
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strip>;
-declare const EntityOperationsResponse: z.ZodObject<{
+declare const ContentOperationsResponse: z.ZodObject<{
     operations: z.ZodArray<z.ZodObject<{
         cid: z.ZodString;
         jwsToken: z.ZodString;
@@ -102,7 +102,7 @@ declare const EntityOperationsResponse: z.ZodObject<{
     }, z.core.$strict>>;
     nextCursor: z.ZodNullable<z.ZodString>;
 }, z.core.$strict>;
-type EntityOperationsResponse = z.infer<typeof EntityOperationsResponse>;
+type ContentOperationsResponse = z.infer<typeof ContentOperationsResponse>;
 declare const ResolveOperationResponse: z.ZodObject<{
     cid: z.ZodString;
     jwsToken: z.ZodString;
@@ -119,8 +119,8 @@ interface StoredChain {
     operations: OperationEntry[];
 }
 declare class ChainStore {
-    private identities;
-    private entities;
+    private identityChains;
+    private contentChains;
     getIdentityChain(did: string): StoredChain | undefined;
     /**
      * Submit an identity chain. Returns 'accepted' | 'noop' | 'conflict'.
@@ -129,8 +129,8 @@ declare class ChainStore {
      * - conflict: submitted chain diverges from stored chain (fork)
      */
     submitIdentityChain(did: string, operations: OperationEntry[]): 'accepted' | 'noop' | 'conflict';
-    getEntityChain(entityId: string): StoredChain | undefined;
-    submitEntityChain(entityId: string, operations: OperationEntry[]): 'accepted' | 'noop' | 'conflict';
+    getContentChain(contentId: string): StoredChain | undefined;
+    submitContentChain(contentId: string, operations: OperationEntry[]): 'accepted' | 'noop' | 'conflict';
     getOperation(cid: string): OperationEntry | undefined;
     private submitChain;
 }
@@ -140,4 +140,4 @@ declare const createRegistryServer: (store?: ChainStore) => {
     store: ChainStore;
 };
 
-export { ChainStore, EntityOperationsParams, EntityOperationsResponse, IdentityOperationsParams, IdentityOperationsResponse, OperationEntry, PaginationParams, RegistryError, ResolveEntityResponse, ResolveIdentityResponse, ResolveOperationResponse, type StoredChain, SubmitContentChainRequest, SubmitContentChainResponse, SubmitIdentityChainRequest, SubmitIdentityChainResponse, createRegistryServer };
+export { ChainStore, ContentOperationsParams, ContentOperationsResponse, IdentityOperationsParams, IdentityOperationsResponse, OperationEntry, PaginationParams, RegistryError, ResolveContentResponse, ResolveIdentityResponse, ResolveOperationResponse, type StoredChain, SubmitContentChainRequest, SubmitContentChainResponse, SubmitIdentityChainRequest, SubmitIdentityChainResponse, createRegistryServer };

package/dist/registry/index.js

@@ -1,11 +1,11 @@
 import {
   ChainStore,
-  EntityOperationsParams,
-  EntityOperationsResponse,
+  ContentOperationsParams,
+  ContentOperationsResponse,
   IdentityOperationsParams,
   IdentityOperationsResponse,
   RegistryError,
-  ResolveEntityResponse,
+  ResolveContentResponse,
   ResolveIdentityResponse,
   ResolveOperationResponse,
   SubmitContentChainRequest,
@@ -13,17 +13,17 @@ import {
   SubmitIdentityChainRequest,
   SubmitIdentityChainResponse,
   createRegistryServer
-} from "../chunk-4MMWM2PC.js";
-import "../chunk-LWC4PWGZ.js";
+} from "../chunk-U6DANYPT.js";
+import "../chunk-VEBMLR37.js";
 import "../chunk-ZXXP5W5N.js";
 export {
   ChainStore,
-  EntityOperationsParams,
-  EntityOperationsResponse,
+  ContentOperationsParams,
+  ContentOperationsResponse,
   IdentityOperationsParams,
   IdentityOperationsResponse,
   RegistryError,
-  ResolveEntityResponse,
+  ResolveContentResponse,
   ResolveIdentityResponse,
   ResolveOperationResponse,
   SubmitContentChainRequest,

package/examples/content-delete.json

@@ -20,7 +20,7 @@
     }
   ],
   "expected": {
-    "entityId": "67t27rzc83v7c22n9t6z7c",
+    "contentId": "67t27rzc83v7c22n9t6z7c",
     "isDeleted": true,
     "currentDocumentCID": null,
     "length": 2

package/examples/content-lifecycle.json

@@ -31,7 +31,7 @@
     }
   ],
   "expected": {
-    "entityId": "67t27rzc83v7c22n9t6z7c",
+    "contentId": "67t27rzc83v7c22n9t6z7c",
     "isDeleted": false,
     "currentDocumentCID": "bafyreieuo26zfmjxwpmw5jk6bqzqhvivxcbckgxtyeuc7ypf3p4sihgq4q",
     "length": 2

package/openapi.yaml

@@ -101,13 +101,13 @@ paths:
               schema:
                 $ref: '#/components/schemas/Error'
 
-  /entities:
+  /content:
     post:
       operationId: submitContentChain
       summary: Submit or extend a content chain
       description: |
         Verifies the chain (resolving signing keys from stored identity chains),
-        derives the entity ID from the genesis CID, and stores it.
+        derives the content ID from the genesis CID, and stores it.
         Same status code semantics as identity submission.
       requestBody:
         required: true
@@ -121,13 +121,13 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/EntityState'
+                $ref: '#/components/schemas/ContentState'
         '200':
           description: Chain already stored (noop)
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/EntityState'
+                $ref: '#/components/schemas/ContentState'
         '400':
           description: Invalid chain
           content:
@@ -141,32 +141,32 @@ paths:
               schema:
                 $ref: '#/components/schemas/Error'
 
-  /entities/{entityId}:
+  /content/{contentId}:
     get:
-      operationId: resolveEntity
-      summary: Resolve current entity state
+      operationId: resolveContent
+      summary: Resolve current content state
       parameters:
-        - $ref: '#/components/parameters/entityId'
+        - $ref: '#/components/parameters/contentId'
       responses:
         '200':
-          description: Entity state
+          description: Content state
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/EntityState'
+                $ref: '#/components/schemas/ContentState'
         '404':
-          description: Entity not found
+          description: Content not found
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
 
-  /entities/{entityId}/operations:
+  /content/{contentId}/operations:
     get:
-      operationId: listEntityOperations
+      operationId: listContentOperations
       summary: List content chain operations (newest-first, paginated)
       parameters:
-        - $ref: '#/components/parameters/entityId'
+        - $ref: '#/components/parameters/contentId'
         - $ref: '#/components/parameters/cursor'
         - $ref: '#/components/parameters/limit'
       responses:
@@ -177,7 +177,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/PaginatedOperations'
         '404':
-          description: Entity not found
+          description: Content not found
           content:
             application/json:
               schema:
@@ -216,8 +216,8 @@ components:
         pattern: '^did:dfos:[2346789acdefhknrtvz]{22}$'
       example: 'did:dfos:e3vvtck42d4eacdnzvtrn6'
 
-    entityId:
-      name: entityId
+    contentId:
+      name: contentId
       in: path
       required: true
       schema:
@@ -305,11 +305,11 @@ components:
           items:
             $ref: '#/components/schemas/MultikeyPublicKey'
 
-    EntityState:
+    ContentState:
       type: object
-      required: [entityId, isDeleted, currentDocumentCID, genesisCID, headCID]
+      required: [contentId, isDeleted, currentDocumentCID, genesisCID, headCID]
       properties:
-        entityId:
+        contentId:
           type: string
           example: '67t27rzc83v7c22n9t6z7c'
         isDeleted:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metalabel/dfos-protocol",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "type": "module",
   "description": "DFOS Protocol — Ed25519 signed chain primitives, registry, and verification",
   "license": "MIT",