@metalabel/dfos-protocol 0.0.1 → 0.0.2

package/REGISTRY-API.md

@@ -0,0 +1,242 @@
+# DFOS Registry API
+
+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.
+
+[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)
+
+---
+
+## Overview
+
+The registry stores verified chains and serves resolved state. It enforces **linear chain integrity** — it accepts chains that are the same length or longer than what's stored, and rejects forks (two different operations at the same chain position).
+
+Six endpoints, two concerns:
+
+| Concern             | Endpoints                                       |
+| ------------------- | ----------------------------------------------- |
+| **Identity chains** | Submit chain, resolve identity, list operations |
+| **Content chains**  | Submit chain, resolve entity, list operations   |
+| **Lookup**          | Resolve operation by CID                        |
+
+All request and response bodies are JSON (`application/json`).
+
+---
+
+## Identity Endpoints
+
+### `POST /identities` — Submit or extend an identity chain
+
+Submit an ordered array of JWS tokens (genesis-first). The registry verifies the chain, derives the DID from the genesis CID, and stores it.
+
+**Request:**
+
+```json
+{
+  "chain": ["eyJhbGciOiJFZERTQSI...", "eyJhbGciOiJFZERTQSI..."]
+}
+```
+
+| Field   | Type     | Description                                                |
+| ------- | -------- | ---------------------------------------------------------- |
+| `chain` | string[] | Ordered JWS compact tokens, genesis-first. Minimum 1 item. |
+
+**Responses:**
+
+| Status | Meaning                                                    |
+| ------ | ---------------------------------------------------------- |
+| `201`  | Chain accepted (new or extended) — returns `IdentityState` |
+| `200`  | Chain already stored, no change — returns `IdentityState`  |
+| `400`  | Invalid chain (verification failed)                        |
+| `409`  | Fork conflict with stored chain                            |
+
+---
+
+### `GET /identities/{did}` — Resolve current identity state
+
+Returns the current key state for a DID.
+
+**Parameters:**
+
+| Name  | In   | Pattern                              | Example                           |
+| ----- | ---- | ------------------------------------ | --------------------------------- |
+| `did` | path | `did:dfos:[2346789acdefhknrtvz]{22}` | `did:dfos:e3vvtck42d4eacdnzvtrn6` |
+
+**Response (`IdentityState`):**
+
+```json
+{
+  "did": "did:dfos:e3vvtck42d4eacdnzvtrn6",
+  "isDeleted": false,
+  "authKeys": [{ "id": "key_...", "type": "Multikey", "publicKeyMultibase": "z6Mk..." }],
+  "assertKeys": [{ "id": "key_...", "type": "Multikey", "publicKeyMultibase": "z6Mk..." }],
+  "controllerKeys": [{ "id": "key_...", "type": "Multikey", "publicKeyMultibase": "z6Mk..." }]
+}
+```
+
+---
+
+### `GET /identities/{did}/operations` — List identity chain operations
+
+Returns operations newest-first, paginated.
+
+**Parameters:**
+
+| Name     | In    | Description                                                  |
+| -------- | ----- | ------------------------------------------------------------ |
+| `did`    | path  | The DID to list operations for                               |
+| `cursor` | query | Opaque pagination cursor (CID of last item on previous page) |
+| `limit`  | query | Page size, 1–100, default 25                                 |
+
+**Response (`PaginatedOperations`):**
+
+```json
+{
+  "operations": [
+    { "cid": "bafyrei...", "jwsToken": "eyJ...", "createdAt": "2026-03-07T00:01:00.000Z" },
+    { "cid": "bafyrei...", "jwsToken": "eyJ...", "createdAt": "2026-03-07T00:00:00.000Z" }
+  ],
+  "nextCursor": null
+}
+```
+
+---
+
+## Content Endpoints
+
+### `POST /entities` — 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.
+
+**Request:** Same `{ "chain": [...] }` format as identity submission.
+
+**Responses:** Same status code semantics — `201` accepted, `200` noop, `400` invalid, `409` fork.
+
+---
+
+### `GET /entities/{entityId}` — Resolve current entity state
+
+Returns the current state for a content chain entity.
+
+**Parameters:**
+
+| Name       | In   | Pattern                     | Example                  |
+| ---------- | ---- | --------------------------- | ------------------------ |
+| `entityId` | path | `[2346789acdefhknrtvz]{22}` | `67t27rzc83v7c22n9t6z7c` |
+
+**Response (`EntityState`):**
+
+```json
+{
+  "entityId": "67t27rzc83v7c22n9t6z7c",
+  "isDeleted": false,
+  "currentDocumentCID": "bafyrei...",
+  "genesisCID": "bafyrei...",
+  "headCID": "bafyrei..."
+}
+```
+
+| Field                | Description                                         |
+| -------------------- | --------------------------------------------------- |
+| `currentDocumentCID` | CID of current document, null if cleared or deleted |
+| `genesisCID`         | CID of the genesis operation                        |
+| `headCID`            | CID of the most recent operation                    |
+
+---
+
+### `GET /entities/{entityId}/operations` — List content chain operations
+
+Same pagination mechanics as identity operations.
+
+---
+
+## Lookup Endpoints
+
+### `GET /operations/{cid}` — Resolve a single operation by CID
+
+Returns the JWS token for any operation (identity or content) by its CID.
+
+**Response:**
+
+```json
+{
+  "cid": "bafyrei...",
+  "jwsToken": "eyJ..."
+}
+```
+
+---
+
+## Errors
+
+All error responses follow a standard shape:
+
+```json
+{
+  "error": "BAD_REQUEST",
+  "message": "Human-readable description"
+}
+```
+
+| Error Code    | Used By                                                    |
+| ------------- | ---------------------------------------------------------- |
+| `BAD_REQUEST` | Invalid chain, malformed request                           |
+| `NOT_FOUND`   | Identity, entity, operation, or document not found         |
+| `CONFLICT`    | Fork detected — submitted chain diverges from stored chain |
+
+---
+
+## Chain Submission Semantics
+
+The registry enforces **linear chain extension**:
+
+- **New chain** — genesis operation not seen before → store and return `201`
+- **Extension** — submitted chain is longer than stored, shares the same prefix → replace stored chain, return `201`
+- **Noop** — submitted chain is identical to stored → return `200`
+- **Fork** — submitted chain diverges from stored chain at some operation → reject with `409`
+
+This means a registry is **eventually consistent with the longest valid chain** it receives. It does not implement consensus — if two registries receive different valid extensions, they may diverge. Fork detection is the caller's responsibility.
+
+---
+
+## Authentication
+
+Registry endpoints that require authentication use **EdDSA JWTs** signed with the same Ed25519 keys from identity chains. The JWT convention is not part of the chain protocol — it's an application-layer auth mechanism for services.
+
+```json
+{
+  "alg": "EdDSA",
+  "typ": "JWT",
+  "kid": "key_ez9a874tckr3dv933d3ckd"
+}
+```
+
+```json
+{
+  "iss": "dfos",
+  "sub": "did:dfos:e3vvtck42d4eacdnzvtrn6",
+  "aud": "dfos-api",
+  "exp": 1772902800,
+  "iat": 1772899200,
+  "jti": "session_ref_example_01"
+}
+```
+
+| Field | Description                                                   |
+| ----- | ------------------------------------------------------------- |
+| `kid` | Bare key ID (not a DID URL — the `sub` claim carries the DID) |
+| `sub` | The DID of the authenticating identity                        |
+| `aud` | Target audience (e.g., `"dfos-api"`)                          |
+
+The signing mechanics are identical to operation JWS — `ed25519.sign(UTF8(base64url(header) + "." + base64url(payload)), privateKey)`. The key is resolved from the identity chain via `kid` + `sub`.
+
+---
+
+## Reference Implementation
+
+A complete reference server is available in the protocol package:
+
+- [`registry/server.ts`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/registry/server.ts) — Hono-based HTTP server implementing all endpoints
+- [`registry/store.ts`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/src/registry/store.ts) — In-memory chain store with linear enforcement
+- [`openapi.yaml`](https://github.com/metalabel/dfos/blob/main/packages/dfos-protocol/openapi.yaml) — OpenAPI 3.1 machine-readable specification

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

@@ -54,10 +54,6 @@ var ResolveOperationResponse = z.strictObject({
   cid: z.string(),
   jwsToken: z.string()
 });
-var ResolveDocumentResponse = z.strictObject({
-  cid: z.string(),
-  content: z.unknown()
-});
 var RegistryError = z.strictObject({
   error: z.string(),
   message: z.string()
@@ -70,7 +66,6 @@ import { Hono } from "hono";
 var ChainStore = class {
   identities = /* @__PURE__ */ new Map();
   entities = /* @__PURE__ */ new Map();
-  documents = /* @__PURE__ */ new Map();
   // --- identities ---
   getIdentityChain(did) {
     return this.identities.get(did);
@@ -91,13 +86,6 @@ var ChainStore = class {
   submitEntityChain(entityId, operations) {
     return this.submitChain(this.entities, entityId, operations);
   }
-  // --- documents ---
-  getDocument(cid) {
-    return this.documents.get(cid);
-  }
-  setDocument(cid, content) {
-    this.documents.set(cid, content);
-  }
   // --- operations (lookup across all chains) ---
   getOperation(cid) {
     for (const chain of this.identities.values()) {
@@ -302,12 +290,6 @@ var createRegistryServer = (store = new ChainStore()) => {
     if (!op) return c.json(err("NOT_FOUND", "operation not found"), 404);
     return c.json({ cid: op.cid, jwsToken: op.jwsToken });
   });
-  app.get("/documents/:cid", (c) => {
-    const cid = c.req.param("cid");
-    const content = store.getDocument(cid);
-    if (content === void 0) return c.json(err("NOT_FOUND", "document not found"), 404);
-    return c.json({ cid, content });
-  });
   return { app, store };
 };
 
@@ -323,7 +305,6 @@ export {
   EntityOperationsParams,
   EntityOperationsResponse,
   ResolveOperationResponse,
-  ResolveDocumentResponse,
   RegistryError,
   ChainStore,
   createRegistryServer

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, ResolveDocumentResponse, ResolveEntityResponse, ResolveIdentityResponse, ResolveOperationResponse, StoredChain, SubmitContentChainRequest, SubmitContentChainResponse, SubmitIdentityChainRequest, SubmitIdentityChainResponse, createRegistryServer } from './registry/index.js';
+export { ChainStore, EntityOperationsParams, EntityOperationsResponse, IdentityOperationsParams, IdentityOperationsResponse, OperationEntry, PaginationParams, RegistryError, ResolveEntityResponse, ResolveIdentityResponse, ResolveOperationResponse, StoredChain, SubmitContentChainRequest, SubmitContentChainResponse, SubmitIdentityChainRequest, SubmitIdentityChainResponse, createRegistryServer } from './registry/index.js';
 import 'multiformats';
 import 'multiformats/cid';
 import 'zod';

package/dist/index.js

@@ -5,7 +5,6 @@ import {
   IdentityOperationsParams,
   IdentityOperationsResponse,
   RegistryError,
-  ResolveDocumentResponse,
   ResolveEntityResponse,
   ResolveIdentityResponse,
   ResolveOperationResponse,
@@ -14,7 +13,7 @@ import {
   SubmitIdentityChainRequest,
   SubmitIdentityChainResponse,
   createRegistryServer
-} from "./chunk-3PB644X2.js";
+} from "./chunk-4MMWM2PC.js";
 import {
   ContentOperation,
   ED25519_PRIV_MULTICODEC,
@@ -68,7 +67,6 @@ export {
   JwtVerificationError,
   MultikeyPublicKey,
   RegistryError,
-  ResolveDocumentResponse,
   ResolveEntityResponse,
   ResolveIdentityResponse,
   ResolveOperationResponse,

package/dist/registry/index.d.ts

@@ -108,11 +108,6 @@ declare const ResolveOperationResponse: z.ZodObject<{
     jwsToken: z.ZodString;
 }, z.core.$strict>;
 type ResolveOperationResponse = z.infer<typeof ResolveOperationResponse>;
-declare const ResolveDocumentResponse: z.ZodObject<{
-    cid: z.ZodString;
-    content: z.ZodUnknown;
-}, z.core.$strict>;
-type ResolveDocumentResponse = z.infer<typeof ResolveDocumentResponse>;
 declare const RegistryError: z.ZodObject<{
     error: z.ZodString;
     message: z.ZodString;
@@ -126,7 +121,6 @@ interface StoredChain {
 declare class ChainStore {
     private identities;
     private entities;
-    private documents;
     getIdentityChain(did: string): StoredChain | undefined;
     /**
      * Submit an identity chain. Returns 'accepted' | 'noop' | 'conflict'.
@@ -137,8 +131,6 @@ declare class ChainStore {
     submitIdentityChain(did: string, operations: OperationEntry[]): 'accepted' | 'noop' | 'conflict';
     getEntityChain(entityId: string): StoredChain | undefined;
     submitEntityChain(entityId: string, operations: OperationEntry[]): 'accepted' | 'noop' | 'conflict';
-    getDocument(cid: string): unknown | undefined;
-    setDocument(cid: string, content: unknown): void;
     getOperation(cid: string): OperationEntry | undefined;
     private submitChain;
 }
@@ -148,4 +140,4 @@ declare const createRegistryServer: (store?: ChainStore) => {
     store: ChainStore;
 };
 
-export { ChainStore, EntityOperationsParams, EntityOperationsResponse, IdentityOperationsParams, IdentityOperationsResponse, OperationEntry, PaginationParams, RegistryError, ResolveDocumentResponse, ResolveEntityResponse, ResolveIdentityResponse, ResolveOperationResponse, type StoredChain, SubmitContentChainRequest, SubmitContentChainResponse, SubmitIdentityChainRequest, SubmitIdentityChainResponse, createRegistryServer };
+export { ChainStore, EntityOperationsParams, EntityOperationsResponse, IdentityOperationsParams, IdentityOperationsResponse, OperationEntry, PaginationParams, RegistryError, ResolveEntityResponse, ResolveIdentityResponse, ResolveOperationResponse, type StoredChain, SubmitContentChainRequest, SubmitContentChainResponse, SubmitIdentityChainRequest, SubmitIdentityChainResponse, createRegistryServer };

package/dist/registry/index.js

@@ -5,7 +5,6 @@ import {
   IdentityOperationsParams,
   IdentityOperationsResponse,
   RegistryError,
-  ResolveDocumentResponse,
   ResolveEntityResponse,
   ResolveIdentityResponse,
   ResolveOperationResponse,
@@ -14,7 +13,7 @@ import {
   SubmitIdentityChainRequest,
   SubmitIdentityChainResponse,
   createRegistryServer
-} from "../chunk-3PB644X2.js";
+} from "../chunk-4MMWM2PC.js";
 import "../chunk-LWC4PWGZ.js";
 import "../chunk-ZXXP5W5N.js";
 export {
@@ -24,7 +23,6 @@ export {
   IdentityOperationsParams,
   IdentityOperationsResponse,
   RegistryError,
-  ResolveDocumentResponse,
   ResolveEntityResponse,
   ResolveIdentityResponse,
   ResolveOperationResponse,

package/openapi.yaml

@@ -203,29 +203,6 @@ paths:
               schema:
                 $ref: '#/components/schemas/Error'
 
-  /documents/{cid}:
-    get:
-      operationId: resolveDocument
-      summary: Resolve a document by CID
-      description: |
-        This is the only endpoint that touches actual content.
-        All other endpoints deal purely in chain mechanics.
-      parameters:
-        - $ref: '#/components/parameters/cid'
-      responses:
-        '200':
-          description: Document found
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Document'
-        '404':
-          description: Document not found
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
-
 # ---------------------------------------------------------------------------
 
 components:
@@ -388,15 +365,6 @@ components:
         jwsToken:
           type: string
 
-    Document:
-      type: object
-      required: [cid, content]
-      properties:
-        cid:
-          type: string
-        content:
-          description: Opaque document content (application-defined)
-
     Error:
       type: object
       required: [error, message]

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "@metalabel/dfos-protocol",
-  "version": "0.0.1",
+  "version": "0.0.2",
+  "type": "module",
   "description": "DFOS Protocol — Ed25519 signed chain primitives, registry, and verification",
   "license": "MIT",
   "author": "Metalabel <hello@metalabel.com> (https://metalabel.com)",
   "repository": {
     "type": "git",
-    "url": "https://github.com/metalabel/metalabel-dfos.git",
+    "url": "https://github.com/metalabel/dfos.git",
     "directory": "packages/dfos-protocol"
   },
-  "homepage": "https://github.com/metalabel/metalabel-dfos/tree/main/packages/dfos-protocol",
+  "homepage": "https://protocol.dfos.com",
   "keywords": [
     "dfos",
     "protocol",
@@ -23,7 +24,6 @@
     "cid",
     "metalabel"
   ],
-  "type": "module",
   "exports": {
     ".": {
       "import": "./dist/index.js",
@@ -47,6 +47,9 @@
     "schemas",
     "examples",
     "PROTOCOL.md",
+    "DID-METHOD.md",
+    "CONTENT-MODEL.md",
+    "REGISTRY-API.md",
     "openapi.yaml",
     "LICENSE",
     "README.md"
@@ -68,8 +71,10 @@
     "vitest": "^4.0.18"
   },
   "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "generate-examples": "vitest run --config vitest.scripts.config.ts",
-    "build": "tsup"
+    "generate-examples": "vitest run --config vitest.scripts.config.ts"
   }
 }