@metalabel/dfos-protocol 0.0.1

package/README.md

@@ -0,0 +1,50 @@
+# @metalabel/dfos-protocol
+
+Ed25519 signed chain primitives, verifiable content, and registry for the DFOS Protocol.
+
+## Install
+
+```bash
+npm install @metalabel/dfos-protocol
+```
+
+## Usage
+
+```ts
+// Chain verification
+import { verifyContentChain, verifyIdentityChain } from '@metalabel/dfos-protocol/chain';
+// Crypto primitives
+import { createJws, dagCborCanonicalEncode, verifyJws } from '@metalabel/dfos-protocol/crypto';
+// Reference registry server
+import { createRegistryServer } from '@metalabel/dfos-protocol/registry';
+```
+
+## Subpath Exports
+
+| Export                              | Description                                                         |
+| ----------------------------------- | ------------------------------------------------------------------- |
+| `@metalabel/dfos-protocol/chain`    | Identity and content chain signing, verification, multikey encoding |
+| `@metalabel/dfos-protocol/crypto`   | Ed25519, JWS, JWT, dag-cbor, base64url, ID generation               |
+| `@metalabel/dfos-protocol/registry` | Hono-based registry server, in-memory store, Zod schemas            |
+
+## Protocol Specification
+
+See [PROTOCOL.md](./PROTOCOL.md) for the complete protocol specification with worked examples and test vectors.
+
+## Examples
+
+The `examples/` directory contains deterministic reference chain 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
+
+## API Documentation
+
+See [openapi.yaml](./openapi.yaml) for the registry API specification.
+
+## License
+
+MIT

package/dist/chain/index.d.ts

@@ -0,0 +1,196 @@
+import { z } from 'zod';
+
+/** Function that signs a byte array and returns a signature */
+type Signer = (message: Uint8Array) => Promise<Uint8Array>;
+declare const MultikeyPublicKey: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodLiteral<"Multikey">;
+    publicKeyMultibase: z.ZodString;
+}, z.core.$strict>;
+type MultikeyPublicKey = z.infer<typeof MultikeyPublicKey>;
+declare const IdentityOperation: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"create">;
+    authKeys: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodLiteral<"Multikey">;
+        publicKeyMultibase: z.ZodString;
+    }, z.core.$strict>>;
+    assertKeys: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodLiteral<"Multikey">;
+        publicKeyMultibase: z.ZodString;
+    }, z.core.$strict>>;
+    controllerKeys: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodLiteral<"Multikey">;
+        publicKeyMultibase: z.ZodString;
+    }, z.core.$strict>>;
+    createdAt: z.ZodISODateTime;
+}, z.core.$strict>, z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"update">;
+    previousOperationCID: z.ZodString;
+    authKeys: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodLiteral<"Multikey">;
+        publicKeyMultibase: z.ZodString;
+    }, z.core.$strict>>;
+    assertKeys: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodLiteral<"Multikey">;
+        publicKeyMultibase: z.ZodString;
+    }, z.core.$strict>>;
+    controllerKeys: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodLiteral<"Multikey">;
+        publicKeyMultibase: z.ZodString;
+    }, z.core.$strict>>;
+    createdAt: z.ZodISODateTime;
+}, z.core.$strict>, z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"delete">;
+    previousOperationCID: z.ZodString;
+    createdAt: z.ZodISODateTime;
+}, z.core.$strict>], "type">;
+type IdentityOperation = z.infer<typeof IdentityOperation>;
+declare const VerifiedIdentity: z.ZodObject<{
+    did: z.ZodString;
+    isDeleted: z.ZodBoolean;
+    authKeys: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodLiteral<"Multikey">;
+        publicKeyMultibase: z.ZodString;
+    }, z.core.$strict>>;
+    assertKeys: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodLiteral<"Multikey">;
+        publicKeyMultibase: z.ZodString;
+    }, z.core.$strict>>;
+    controllerKeys: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodLiteral<"Multikey">;
+        publicKeyMultibase: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type VerifiedIdentity = z.infer<typeof VerifiedIdentity>;
+declare const ContentOperation: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"create">;
+    documentCID: z.ZodString;
+    createdAt: z.ZodISODateTime;
+    note: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"update">;
+    previousOperationCID: z.ZodString;
+    documentCID: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodISODateTime;
+    note: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"delete">;
+    previousOperationCID: z.ZodString;
+    createdAt: z.ZodISODateTime;
+    note: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>], "type">;
+type ContentOperation = z.infer<typeof ContentOperation>;
+
+/** Ed25519 public key multicodec value */
+declare const ED25519_PUB_MULTICODEC = 237;
+/** Ed25519 private key multicodec value */
+declare const ED25519_PRIV_MULTICODEC = 4864;
+/**
+ * Encode an Ed25519 public key as a W3C Multikey multibase string
+ *
+ * Format: 'z' + base58btc([0xed, 0x01] + publicKeyBytes)
+ * Result starts with "z6Mk..."
+ */
+declare const encodeEd25519Multikey: (publicKeyBytes: Uint8Array) => string;
+/**
+ * Decode a Multikey multibase string to raw key bytes and codec
+ *
+ * Supports Ed25519 public keys (z6Mk... prefix)
+ */
+declare const decodeMultikey: (multibase: string) => {
+    keyBytes: Uint8Array;
+    codec: number;
+};
+
+/**
+ * Derive a prefixed chain identifier from CID bytes
+ *
+ * Used for identity DIDs: deriveChainIdentifier(cidBytes, 'did:dfos') → 'did:dfos:xxxx'
+ */
+declare const deriveChainIdentifier: (cidBytes: Uint8Array, prefix: string) => string;
+/**
+ * Derive a bare entity 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;
+
+/**
+ * Sign an identity operation as a JWS and derive the operation CID
+ */
+declare const signIdentityOperation: (input: {
+    operation: IdentityOperation;
+    signer: Signer;
+    keyId: string;
+    /** DID of the identity — omit for genesis (bare kid) */
+    identityDID?: string;
+}) => Promise<{
+    jwsToken: string;
+    operationCID: string;
+}>;
+/**
+ * Verify a log of JWS identity operations and derive the identity
+ *
+ * Walks the chain from genesis, verifying signatures and chain integrity.
+ * Returns the final verified identity state.
+ */
+declare const verifyIdentityChain: (input: {
+    didPrefix: string;
+    log: string[];
+}) => Promise<VerifiedIdentity>;
+
+interface VerifiedContentChain {
+    /** Entity identifier — bare 22-char hash derived from genesis CID */
+    entityId: string;
+    /** CID of the genesis operation */
+    genesisCID: string;
+    /** CID of the most recent operation */
+    headCID: string;
+    /** Whether the chain has been terminated by a delete */
+    isDeleted: boolean;
+    /** The current documentCID (null if cleared or deleted) */
+    currentDocumentCID: string | null;
+    /** Number of operations in the chain */
+    length: number;
+}
+/**
+ * Sign a content chain operation as a JWS and derive the operation CID
+ */
+declare const signContentOperation: (input: {
+    operation: ContentOperation;
+    signer: Signer;
+    /** kid for the JWS header — should be a DID URL: "did:dfos:xxx#key_yyy" */
+    kid: string;
+}) => Promise<{
+    jwsToken: string;
+    operationCID: string;
+}>;
+/**
+ * Verify a content chain's structural integrity and signatures
+ *
+ * The caller provides a key resolver to look up public keys from kid values.
+ * This keeps the content chain protocol independent of identity resolution.
+ */
+declare const verifyContentChain: (input: {
+    log: string[];
+    /** Resolve a kid (DID URL) to the raw Ed25519 public key bytes */
+    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 };

package/dist/chain/index.js

@@ -0,0 +1,33 @@
+import {
+  ContentOperation,
+  ED25519_PRIV_MULTICODEC,
+  ED25519_PUB_MULTICODEC,
+  IdentityOperation,
+  MultikeyPublicKey,
+  VerifiedIdentity,
+  decodeMultikey,
+  deriveChainIdentifier,
+  deriveEntityId,
+  encodeEd25519Multikey,
+  signContentOperation,
+  signIdentityOperation,
+  verifyContentChain,
+  verifyIdentityChain
+} from "../chunk-LWC4PWGZ.js";
+import "../chunk-ZXXP5W5N.js";
+export {
+  ContentOperation,
+  ED25519_PRIV_MULTICODEC,
+  ED25519_PUB_MULTICODEC,
+  IdentityOperation,
+  MultikeyPublicKey,
+  VerifiedIdentity,
+  decodeMultikey,
+  deriveChainIdentifier,
+  deriveEntityId,
+  encodeEd25519Multikey,
+  signContentOperation,
+  signIdentityOperation,
+  verifyContentChain,
+  verifyIdentityChain
+};

package/dist/chunk-3PB644X2.js

@@ -0,0 +1,330 @@
+import {
+  MultikeyPublicKey,
+  decodeMultikey,
+  verifyContentChain,
+  verifyIdentityChain
+} from "./chunk-LWC4PWGZ.js";
+import {
+  dagCborCanonicalEncode,
+  decodeJwsUnsafe
+} from "./chunk-ZXXP5W5N.js";
+
+// src/registry/schemas.ts
+import { z } from "zod";
+var OperationEntry = z.strictObject({
+  cid: z.string(),
+  jwsToken: z.string(),
+  createdAt: z.string()
+});
+var PaginatedOperations = z.strictObject({
+  operations: z.array(OperationEntry),
+  nextCursor: z.string().nullable()
+});
+var PaginationParams = z.object({
+  cursor: z.string().optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(25)
+});
+var SubmitIdentityChainRequest = z.strictObject({
+  chain: z.array(z.string()).min(1)
+});
+var SubmitIdentityChainResponse = z.strictObject({
+  did: z.string(),
+  isDeleted: z.boolean(),
+  authKeys: z.array(MultikeyPublicKey),
+  assertKeys: z.array(MultikeyPublicKey),
+  controllerKeys: z.array(MultikeyPublicKey)
+});
+var ResolveIdentityResponse = SubmitIdentityChainResponse;
+var IdentityOperationsParams = PaginationParams;
+var IdentityOperationsResponse = PaginatedOperations;
+var SubmitContentChainRequest = z.strictObject({
+  chain: z.array(z.string()).min(1)
+});
+var SubmitContentChainResponse = z.strictObject({
+  entityId: 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 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()
+});
+
+// src/registry/server.ts
+import { Hono } from "hono";
+
+// src/registry/store.ts
+var ChainStore = class {
+  identities = /* @__PURE__ */ new Map();
+  entities = /* @__PURE__ */ new Map();
+  documents = /* @__PURE__ */ new Map();
+  // --- identities ---
+  getIdentityChain(did) {
+    return this.identities.get(did);
+  }
+  /**
+   * Submit an identity chain. Returns 'accepted' | 'noop' | 'conflict'.
+   * - accepted: chain was stored or extended
+   * - noop: submitted chain is same as or prefix of stored chain
+   * - conflict: submitted chain diverges from stored chain (fork)
+   */
+  submitIdentityChain(did, operations) {
+    return this.submitChain(this.identities, did, operations);
+  }
+  // --- entities ---
+  getEntityChain(entityId) {
+    return this.entities.get(entityId);
+  }
+  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()) {
+      const op = chain.operations.find((o) => o.cid === cid);
+      if (op) return op;
+    }
+    for (const chain of this.entities.values()) {
+      const op = chain.operations.find((o) => o.cid === cid);
+      if (op) return op;
+    }
+    return void 0;
+  }
+  // --- shared chain submission logic ---
+  submitChain(store, id, operations) {
+    const existing = store.get(id);
+    if (!existing) {
+      store.set(id, { operations });
+      return "accepted";
+    }
+    if (operations.length <= existing.operations.length) {
+      for (let i = 0; i < operations.length; i++) {
+        if (operations[i].cid !== existing.operations[i].cid) {
+          return "conflict";
+        }
+      }
+      return "noop";
+    }
+    for (let i = 0; i < existing.operations.length; i++) {
+      if (operations[i].cid !== existing.operations[i].cid) {
+        return "conflict";
+      }
+    }
+    store.set(id, { operations });
+    return "accepted";
+  }
+};
+
+// src/registry/server.ts
+var err = (code, message) => ({
+  error: code,
+  message
+});
+var extractOperationEntries = async (chain) => {
+  const entries = [];
+  for (const jwsToken of chain) {
+    const decoded = decodeJwsUnsafe(jwsToken);
+    if (!decoded) throw new Error("invalid JWS token");
+    const payload = decoded.payload;
+    const encoded = await dagCborCanonicalEncode(payload);
+    entries.push({
+      cid: encoded.cid.toString(),
+      jwsToken,
+      createdAt: payload.createdAt ?? ""
+    });
+  }
+  return entries;
+};
+var paginate = (operations, cursor, limit) => {
+  const reversed = [...operations].reverse();
+  let startIdx = 0;
+  if (cursor) {
+    const cursorIdx = reversed.findIndex((op) => op.cid === cursor);
+    if (cursorIdx >= 0) startIdx = cursorIdx + 1;
+  }
+  const page = reversed.slice(startIdx, startIdx + limit);
+  const hasMore = startIdx + limit < reversed.length;
+  return {
+    operations: page,
+    nextCursor: hasMore ? page[page.length - 1].cid : null
+  };
+};
+var paginationParams = (c) => ({
+  cursor: c.query("cursor"),
+  limit: Math.min(Math.max(parseInt(c.query("limit") ?? "25"), 1), 100)
+});
+var createKeyResolver = (store) => async (kid) => {
+  const hashIdx = kid.indexOf("#");
+  if (hashIdx < 0) throw new Error(`invalid kid format: ${kid}`);
+  const did = kid.substring(0, hashIdx);
+  const keyId = kid.substring(hashIdx + 1);
+  const identityChain = store.getIdentityChain(did);
+  if (!identityChain) throw new Error(`identity not found: ${did}`);
+  const identity = await verifyIdentityChain({
+    didPrefix: "did:dfos",
+    log: identityChain.operations.map((o) => o.jwsToken)
+  });
+  const allKeys = [...identity.authKeys, ...identity.assertKeys, ...identity.controllerKeys];
+  const key = allKeys.find((k) => k.id === keyId);
+  if (!key) throw new Error(`key not found: ${keyId}`);
+  return decodeMultikey(key.publicKeyMultibase).keyBytes;
+};
+var createRegistryServer = (store = new ChainStore()) => {
+  const app = new Hono();
+  const resolveKey = createKeyResolver(store);
+  app.post("/identities", 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);
+    }
+    let verified;
+    try {
+      verified = await verifyIdentityChain({
+        didPrefix: "did:dfos",
+        log: body.chain
+      });
+    } catch (e) {
+      return c.json(err("BAD_REQUEST", `chain verification failed: ${e.message}`), 400);
+    }
+    const operations = await extractOperationEntries(body.chain);
+    const result = store.submitIdentityChain(verified.did, operations);
+    if (result === "conflict") {
+      return c.json(err("CONFLICT", "submitted chain conflicts with stored chain"), 409);
+    }
+    return c.json(
+      {
+        did: verified.did,
+        isDeleted: verified.isDeleted,
+        authKeys: verified.authKeys,
+        assertKeys: verified.assertKeys,
+        controllerKeys: verified.controllerKeys
+      },
+      result === "accepted" ? 201 : 200
+    );
+  });
+  app.get("/identities/:did", async (c) => {
+    const did = c.req.param("did");
+    const chain = store.getIdentityChain(did);
+    if (!chain) return c.json(err("NOT_FOUND", "identity not found"), 404);
+    const verified = await verifyIdentityChain({
+      didPrefix: "did:dfos",
+      log: chain.operations.map((o) => o.jwsToken)
+    });
+    return c.json({
+      did: verified.did,
+      isDeleted: verified.isDeleted,
+      authKeys: verified.authKeys,
+      assertKeys: verified.assertKeys,
+      controllerKeys: verified.controllerKeys
+    });
+  });
+  app.get("/identities/:did/operations", (c) => {
+    const did = c.req.param("did");
+    const chain = store.getIdentityChain(did);
+    if (!chain) return c.json(err("NOT_FOUND", "identity not found"), 404);
+    const { cursor, limit } = paginationParams(c.req);
+    return c.json(paginate(chain.operations, cursor, limit));
+  });
+  app.post("/entities", 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);
+    }
+    const operations = await extractOperationEntries(body.chain);
+    let verified;
+    try {
+      verified = await verifyContentChain({ log: body.chain, resolveKey });
+    } catch (e) {
+      return c.json(err("BAD_REQUEST", `chain verification failed: ${e.message}`), 400);
+    }
+    const result = store.submitEntityChain(verified.entityId, operations);
+    if (result === "conflict") {
+      return c.json(err("CONFLICT", "submitted chain conflicts with stored chain"), 409);
+    }
+    return c.json(
+      {
+        entityId: verified.entityId,
+        isDeleted: verified.isDeleted,
+        currentDocumentCID: verified.currentDocumentCID,
+        genesisCID: verified.genesisCID,
+        headCID: verified.headCID
+      },
+      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);
+    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,
+      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);
+    const { cursor, limit } = paginationParams(c.req);
+    return c.json(paginate(chain.operations, cursor, limit));
+  });
+  app.get("/operations/:cid", (c) => {
+    const cid = c.req.param("cid");
+    const op = store.getOperation(cid);
+    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 };
+};
+
+export {
+  SubmitIdentityChainRequest,
+  SubmitIdentityChainResponse,
+  ResolveIdentityResponse,
+  IdentityOperationsParams,
+  IdentityOperationsResponse,
+  SubmitContentChainRequest,
+  SubmitContentChainResponse,
+  ResolveEntityResponse,
+  EntityOperationsParams,
+  EntityOperationsResponse,
+  ResolveOperationResponse,
+  ResolveDocumentResponse,
+  RegistryError,
+  ChainStore,
+  createRegistryServer
+};