@metalabel/dfos-web-relay 0.7.1 → 0.8.1

package/README.md

@@ -1,6 +1,6 @@
 # @metalabel/dfos-web-relay
 
-Portable HTTP relay for the [DFOS protocol](https://protocol.dfos.com). Receives, verifies, stores, and serves identity chains, content chains, beacons, countersignatures, and content blobs.
+Relays verify everything they receive and serve everything they've verified. No trust between relays, no hierarchy, no central authority. Topology is emergent. Portable HTTP relay for the [DFOS protocol](https://protocol.dfos.com).
 
 See [WEB-RELAY.md](../../specs/WEB-RELAY.md) for the full relay specification.
 
@@ -56,39 +56,7 @@ serve({ port: 4444 });
 
 **Upload**: Auth token required. Caller must be the chain creator or the signer of the referenced operation (enables delegated upload).
 
-**Download**: Auth token required. Chain creator can download directly. Other identities must present a `DFOSContentRead` VC-JWT credential (issued by the creator) in the `X-Credential` header.
-
-## Conformance Test Suite
-
-The `conformance/` directory contains a Go integration test suite that exercises the full relay HTTP surface. It runs against any live relay via the `RELAY_URL` environment variable.
-
-```bash
-# Run against a local relay
-RELAY_URL=http://localhost:4444 go test -v -count=1 ./conformance/
-
-# Run against a remote relay
-RELAY_URL=https://registry.imajin.ai/relay go test -v -count=1 ./conformance/
-```
-
-77 tests covering:
-
-- Well-known discovery
-- Identity lifecycle (create, update, delete, batch, idempotency, controller key rotation)
-- Content lifecycle (create, update, delete, fork acceptance, DAG logs, deterministic head selection, post-delete rejection, notes, long chains)
-- Content update after auth key rotation, multiple independent chains
-- Operations by CID
-- Beacons (create, replacement, not-found, unknown/deleted identity)
-- Countersignatures (dedup, empty result, multi-witness, self-countersign, non-existent operation)
-- Blob upload/download (CID verification, auth, credential-based access, multi-version, idempotent upload)
-- Delegated content operations (write credentials, delegated blob upload, delegated delete)
-- Credentials (expiry, scope mismatch, type enforcement, deleted issuer behavior)
-- Signature verification (tampered signature, wrong signing key)
-- Auth edge cases (wrong audience, expired token, rotated-out key)
-- Batch processing (3-step dependency sort, content-identity sort, large batch, dedup, mixed valid/invalid, multi-chain)
-- Input validation (malformed JSON, empty operations, invalid JWS)
-- Future timestamp guard (reject identity/content ops >24h ahead)
-
-The conformance suite depends on [`dfos-protocol-go`](../dfos-protocol-go) for protocol operations.
+**Download**: Auth token required. Chain creator can download directly. Other identities must present a DFOS read credential (issued by the creator) in the `X-Credential` header.
 
 ## Peering
 

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { VerifiedIdentity, VerifiedContentChain, VerifiedBeacon } from '@metalabel/dfos-protocol/chain';
+import { Attenuation } from '@metalabel/dfos-protocol/credentials';
 import { Hono } from 'hono';
 
 interface RelayIdentity {
@@ -93,7 +94,7 @@ interface StoredOperation {
     cid: string;
     jwsToken: string;
     /** Which chain type this operation belongs to */
-    chainType: 'identity' | 'content' | 'artifact' | 'beacon' | 'countersign';
+    chainType: 'identity' | 'content' | 'artifact' | 'beacon' | 'countersign' | 'revocation' | 'credential';
     /** The chain identifier — DID for identity/beacon/artifact, contentId for content, targetCID for countersign */
     chainId: string;
 }
@@ -110,7 +111,27 @@ interface LogEntry {
     chainId: string;
 }
 /** All operation kinds in the protocol */
-type OperationKind = 'identity-op' | 'content-op' | 'beacon' | 'artifact' | 'countersign';
+type OperationKind = 'identity-op' | 'content-op' | 'beacon' | 'artifact' | 'countersign' | 'revocation' | 'credential';
+interface StoredRevocation {
+    cid: string;
+    issuerDID: string;
+    credentialCID: string;
+    jwsToken: string;
+}
+interface StoredDocument {
+    operationCID: string;
+    documentCID: string | null;
+    document: unknown | null;
+    signerDID: string;
+    createdAt: string;
+}
+interface StoredPublicCredential {
+    cid: string;
+    issuerDID: string;
+    att: Attenuation[];
+    exp: number;
+    jwsToken: string;
+}
 /**
  * Storage backend for a DFOS web relay
  *
@@ -164,6 +185,26 @@ interface RelayStore {
         state: VerifiedContentChain;
         lastCreatedAt: string;
     } | null>;
+    /** Get all revoked credential CIDs for an issuer */
+    getRevocations(issuerDID: string): Promise<string[]>;
+    /** Add a revocation to the revocation set */
+    addRevocation(revocation: StoredRevocation): Promise<void>;
+    /** Check if a specific credential CID has been revoked by a specific issuer */
+    isCredentialRevoked(issuerDID: string, credentialCID: string): Promise<boolean>;
+    /** Get public credentials covering a specific resource */
+    getPublicCredentials(resource: string): Promise<string[]>;
+    /** Add a public credential as standing authorization */
+    addPublicCredential(credential: StoredPublicCredential): Promise<void>;
+    /** Remove a public credential (e.g., after revocation) */
+    removePublicCredential(credentialCID: string): Promise<void>;
+    /** Get paginated documents for a content chain */
+    getDocuments(contentId: string, params: {
+        after?: string;
+        limit: number;
+    }): Promise<{
+        documents: StoredDocument[];
+        cursor: string | null;
+    }>;
     /** Get last-synced log cursor for a peer relay */
     getPeerCursor(peerUrl: string): Promise<string | undefined>;
     /** Update last-synced log cursor for a peer relay */
@@ -249,6 +290,10 @@ declare class MemoryRelayStore implements RelayStore {
     private countersignatures;
     private operationLog;
     private peerCursors;
+    /** Keyed by `issuerDID::credentialCID` for issuer-scoped revocation */
+    private revocations;
+    /** Keyed by credential CID */
+    private publicCredentials;
     getOperation(cid: string): Promise<StoredOperation | undefined>;
     putOperation(op: StoredOperation): Promise<void>;
     getIdentityChain(did: string): Promise<StoredIdentityChain | undefined>;
@@ -261,6 +306,19 @@ declare class MemoryRelayStore implements RelayStore {
     putBlob(key: BlobKey, data: Uint8Array): Promise<void>;
     getCountersignatures(operationCID: string): Promise<string[]>;
     addCountersignature(operationCID: string, jwsToken: string): Promise<void>;
+    getRevocations(issuerDID: string): Promise<string[]>;
+    addRevocation(revocation: StoredRevocation): Promise<void>;
+    isCredentialRevoked(issuerDID: string, credentialCID: string): Promise<boolean>;
+    getPublicCredentials(resource: string): Promise<string[]>;
+    addPublicCredential(credential: StoredPublicCredential): Promise<void>;
+    removePublicCredential(credentialCID: string): Promise<void>;
+    getDocuments(contentId: string, params: {
+        after?: string;
+        limit: number;
+    }): Promise<{
+        documents: StoredDocument[];
+        cursor: string | null;
+    }>;
     appendToLog(entry: LogEntry): Promise<void>;
     readLog(params: {
         after?: string;
@@ -303,6 +361,36 @@ declare class MemoryRelayStore implements RelayStore {
  * deterministic CIDs for identical payloads.
  */
 declare const createKeyResolver: (store: RelayStore) => (kid: string) => Promise<Uint8Array>;
+/**
+ * Create an identity resolver that includes all historical keys.
+ *
+ * Credentials are long-lived artifacts — their validity persists across key
+ * rotations. This resolver walks the full identity chain log to collect all
+ * keys that have ever appeared in create and update operations, ensuring
+ * credentials signed by rotated-out keys still verify. Revocation (not key
+ * rotation) is the invalidation mechanism.
+ *
+ * Used for credential verification at both ingestion and access-check time.
+ */
+declare const createHistoricalIdentityResolver: (store: RelayStore) => (did: string) => Promise<{
+    authKeys: {
+        id: string;
+        type: "Multikey";
+        publicKeyMultibase: string;
+    }[];
+    assertKeys: {
+        id: string;
+        type: "Multikey";
+        publicKeyMultibase: string;
+    }[];
+    controllerKeys: {
+        id: string;
+        type: "Multikey";
+        publicKeyMultibase: string;
+    }[];
+    did: string;
+    isDeleted: boolean;
+} | undefined>;
 /**
  * Create a key resolver that only resolves current-state keys.
  *
@@ -339,4 +427,4 @@ declare const sequenceOps: (store: RelayStore) => Promise<{
     result: SequenceResult;
 }>;
 
-export { type BlobKey, type CreatedRelay, type IngestionResult, type LogEntry, MemoryRelayStore, type OperationKind, type PeerClient, type PeerConfig, type PeerLogEntry, type RelayIdentity, type RelayOptions, type RelayStore, type SequenceResult, type StoredBeacon, type StoredContentChain, type StoredIdentityChain, type StoredOperation, bootstrapRelayIdentity, computeOpCID, createCurrentKeyResolver, createHttpPeerClient, createKeyResolver, createRelay, ingestOperations, isDependencyFailure, sequenceOps };
+export { type BlobKey, type CreatedRelay, type IngestionResult, type LogEntry, MemoryRelayStore, type OperationKind, type PeerClient, type PeerConfig, type PeerLogEntry, type RelayIdentity, type RelayOptions, type RelayStore, type SequenceResult, type StoredBeacon, type StoredContentChain, type StoredIdentityChain, type StoredOperation, bootstrapRelayIdentity, computeOpCID, createCurrentKeyResolver, createHistoricalIdentityResolver, createHttpPeerClient, createKeyResolver, createRelay, ingestOperations, isDependencyFailure, sequenceOps };

package/dist/index.js

@@ -19,8 +19,12 @@ import {
   verifyContentExtensionFromTrustedState,
   verifyCountersignature,
   verifyIdentityChain,
-  verifyIdentityExtensionFromTrustedState
+  verifyIdentityExtensionFromTrustedState,
+  verifyRevocation
 } from "@metalabel/dfos-protocol/chain";
+import {
+  verifyDFOSCredential
+} from "@metalabel/dfos-protocol/credentials";
 import { dagCborCanonicalEncode, decodeJwsUnsafe } from "@metalabel/dfos-protocol/crypto";
 var MAX_FUTURE_TIMESTAMP_MS = 24 * 60 * 60 * 1e3;
 var isFutureTimestamp = (createdAt) => {
@@ -91,6 +95,31 @@ var classify = (jwsToken) => {
       previousCID: null
     };
   }
+  if (typ === "did:dfos:revocation") {
+    const revocationDID = typeof payload["did"] === "string" ? payload["did"] : null;
+    return {
+      ...base,
+      kind: "revocation",
+      referencedDID: revocationDID,
+      signerDID: null,
+      priority: 1,
+      // same as beacons — needs identity keys to verify
+      previousCID: null
+    };
+  }
+  if (typ === "did:dfos:credential") {
+    const aud = typeof payload["aud"] === "string" ? payload["aud"] : null;
+    if (aud !== "*") return unknown;
+    return {
+      ...base,
+      kind: "credential",
+      referencedDID: kidDID,
+      signerDID: null,
+      priority: 1,
+      // needs identity keys to verify
+      previousCID: null
+    };
+  }
   return unknown;
 };
 var createKeyResolver = (store) => async (kid) => {
@@ -126,6 +155,42 @@ var createKeyResolver = (store) => async (kid) => {
   }
   throw new Error(`unknown key ${keyId} on identity ${did}`);
 };
+var createHistoricalIdentityResolver = (store) => async (did) => {
+  const chain = await store.getIdentityChain(did);
+  if (!chain) return void 0;
+  const { state, log } = chain;
+  const keyMaps = {
+    authKeys: new Map(state.authKeys.map((k) => [k.id, k])),
+    assertKeys: new Map(state.assertKeys.map((k) => [k.id, k])),
+    controllerKeys: new Map(state.controllerKeys.map((k) => [k.id, k]))
+  };
+  for (const token of log) {
+    const decoded = decodeJwsUnsafe(token);
+    if (!decoded) continue;
+    const payload = decoded.payload;
+    const opType = payload["type"];
+    if (opType !== "create" && opType !== "update") continue;
+    for (const arrayName of ["authKeys", "assertKeys", "controllerKeys"]) {
+      const keys = payload[arrayName];
+      if (!Array.isArray(keys)) continue;
+      const map = keyMaps[arrayName];
+      for (const k of keys) {
+        if (k && typeof k === "object" && "id" in k && "publicKeyMultibase" in k && !map.has(k.id)) {
+          map.set(
+            k.id,
+            k
+          );
+        }
+      }
+    }
+  }
+  return {
+    ...state,
+    authKeys: [...keyMaps.authKeys.values()],
+    assertKeys: [...keyMaps.assertKeys.values()],
+    controllerKeys: [...keyMaps.controllerKeys.values()]
+  };
+};
 var createCurrentKeyResolver = (store) => async (kid) => {
   const hashIdx = kid.indexOf("#");
   if (hashIdx < 0) throw new Error(`kid must be a DID URL: ${kid}`);
@@ -279,13 +344,15 @@ var ingestContentOp = async (jwsToken, store, logEnabled) => {
     }
   }
   const resolveKey = createKeyResolver(store);
+  const resolveIdentity = createHistoricalIdentityResolver(store);
   const opType = payload["type"];
   const isGenesis = opType === "create";
   if (isGenesis) {
     const content = await verifyContentChain({
       log: [jwsToken],
       resolveKey,
-      enforceAuthorization: true
+      enforceAuthorization: true,
+      resolveIdentity
     });
     const createdAt = payload["createdAt"];
     const chain2 = {
@@ -325,7 +392,8 @@ var ingestContentOp = async (jwsToken, store, logEnabled) => {
       lastCreatedAt: chain.lastCreatedAt,
       newOp: jwsToken,
       resolveKey,
-      enforceAuthorization: true
+      enforceAuthorization: true,
+      resolveIdentity
     });
     const updated2 = {
       contentId: chain.contentId,
@@ -353,7 +421,8 @@ var ingestContentOp = async (jwsToken, store, logEnabled) => {
     lastCreatedAt: forkState.lastCreatedAt,
     newOp: jwsToken,
     resolveKey,
-    enforceAuthorization: true
+    enforceAuthorization: true,
+    resolveIdentity
   });
   const updatedLog = [...chain.log, jwsToken];
   const head = selectDeterministicHead(updatedLog);
@@ -386,7 +455,7 @@ var ingestBeacon = async (jwsToken, store, logEnabled) => {
     const message = err instanceof Error ? err.message : "verification failed";
     return { cid: "", status: "rejected", error: message };
   }
-  const did = verified.payload.did;
+  const did = verified.did;
   const cid = verified.beaconCID;
   const identity = await store.getIdentityChain(did);
   if (identity?.state.isDeleted) {
@@ -394,8 +463,8 @@ var ingestBeacon = async (jwsToken, store, logEnabled) => {
   }
   const existing = await store.getBeacon(did);
   if (existing) {
-    const existingTime = new Date(existing.state.payload.createdAt).getTime();
-    const newTime = new Date(verified.payload.createdAt).getTime();
+    const existingTime = new Date(existing.state.createdAt).getTime();
+    const newTime = new Date(verified.createdAt).getTime();
     if (newTime <= existingTime) {
       return { cid, status: "duplicate", kind: "beacon", chainId: did };
     }
@@ -498,6 +567,86 @@ var ingestArtifact = async (jwsToken, store, logEnabled) => {
   }
   return { cid, status: "new", kind: "artifact", chainId: did };
 };
+var ingestRevocation = async (jwsToken, store, logEnabled) => {
+  const resolveKey = createKeyResolver(store);
+  let verified;
+  try {
+    verified = await verifyRevocation({ jwsToken, resolveKey });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "verification failed";
+    return { cid: "", status: "rejected", error: message };
+  }
+  const cid = verified.revocationCID;
+  const did = verified.did;
+  const existing = await store.getOperation(cid);
+  if (existing) {
+    if (existing.jwsToken !== jwsToken) {
+      return {
+        cid,
+        status: "rejected",
+        error: "revocation already exists with a different signature"
+      };
+    }
+    return { cid, status: "duplicate", kind: "revocation", chainId: did };
+  }
+  const identity = await store.getIdentityChain(did);
+  if (identity?.state.isDeleted) {
+    return { cid, status: "rejected", error: "identity is deleted" };
+  }
+  await store.addRevocation({
+    cid,
+    issuerDID: did,
+    credentialCID: verified.credentialCID,
+    jwsToken
+  });
+  await store.removePublicCredential(verified.credentialCID);
+  await store.putOperation({ cid, jwsToken, chainType: "revocation", chainId: did });
+  if (logEnabled) {
+    await store.appendToLog({ cid, jwsToken, kind: "revocation", chainId: did });
+  }
+  return { cid, status: "new", kind: "revocation", chainId: did };
+};
+var ingestPublicCredential = async (jwsToken, store, logEnabled) => {
+  const resolveIdentity = createHistoricalIdentityResolver(store);
+  let verified;
+  try {
+    verified = await verifyDFOSCredential(jwsToken, { resolveIdentity });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "verification failed";
+    return { cid: "", status: "rejected", error: message };
+  }
+  const cid = verified.credentialCID;
+  if (verified.aud !== "*") {
+    return { cid: "", status: "rejected", error: "not a public credential" };
+  }
+  const existing = await store.getOperation(cid);
+  if (existing) {
+    if (existing.jwsToken !== jwsToken) {
+      return {
+        cid,
+        status: "rejected",
+        error: "credential already exists with a different signature"
+      };
+    }
+    return { cid, status: "duplicate", kind: "credential", chainId: verified.iss };
+  }
+  const revoked = await store.isCredentialRevoked(verified.iss, cid);
+  if (revoked) {
+    return { cid, status: "rejected", error: "credential is revoked" };
+  }
+  await store.addPublicCredential({
+    cid,
+    issuerDID: verified.iss,
+    att: verified.att,
+    exp: verified.exp,
+    jwsToken
+  });
+  await store.putOperation({ cid, jwsToken, chainType: "credential", chainId: verified.iss });
+  if (logEnabled) {
+    await store.appendToLog({ cid, jwsToken, kind: "credential", chainId: verified.iss });
+  }
+  return { cid, status: "new", kind: "credential", chainId: verified.iss };
+};
 var dependencySort = (ops) => {
   const buckets = /* @__PURE__ */ new Map();
   for (const op of ops) {
@@ -607,6 +756,12 @@ var ingestOperations = async (tokens, store, options) => {
         case "artifact":
           result = await ingestArtifact(op.jwsToken, store, logEnabled);
           break;
+        case "revocation":
+          result = await ingestRevocation(op.jwsToken, store, logEnabled);
+          break;
+        case "credential":
+          result = await ingestPublicCredential(op.jwsToken, store, logEnabled);
+          break;
         default:
           result = { cid: "", status: "rejected", error: "unrecognized operation type" };
       }
@@ -722,13 +877,18 @@ var createHttpPeerClient = () => {
 };
 
 // src/relay.ts
-import { VC_TYPE_CONTENT_READ, verifyCredential } from "@metalabel/dfos-protocol/credentials";
+import { createRequire } from "module";
 import { dagCborCanonicalEncode as dagCborCanonicalEncode3, decodeJwsUnsafe as decodeJwsUnsafe4 } from "@metalabel/dfos-protocol/crypto";
 import { Hono } from "hono";
 import { z } from "zod";
 
 // src/auth.ts
-import { verifyAuthToken } from "@metalabel/dfos-protocol/credentials";
+import {
+  matchesResource,
+  verifyAuthToken,
+  verifyDelegationChain,
+  verifyDFOSCredential as verifyDFOSCredential2
+} from "@metalabel/dfos-protocol/credentials";
 import { decodeJwsUnsafe as decodeJwsUnsafe2 } from "@metalabel/dfos-protocol/crypto";
 var authenticateRequest = async (authHeader, relayDID, store) => {
   if (!authHeader) return null;
@@ -752,6 +912,73 @@ var authenticateRequest = async (authHeader, relayDID, store) => {
     return null;
   }
 };
+var verifyContentAccess = async (options) => {
+  const { credentialJWS, requestedResource, action, store, creatorDID, requesterDID } = options;
+  if (requesterDID && requesterDID === creatorDID) {
+    return { granted: true, source: "creator" };
+  }
+  const resolveIdentity = createHistoricalIdentityResolver(store);
+  const isRevoked = async (issuerDID, credentialCID) => store.isCredentialRevoked(issuerDID, credentialCID);
+  const manifestLookup = async (manifestContentId) => {
+    const chain = await store.getContentChain(manifestContentId);
+    if (!chain) return [];
+    const docCID = chain.state.currentDocumentCID;
+    if (!docCID) return [];
+    const blob = await store.getBlob({ creatorDID: chain.state.creatorDID, documentCID: docCID });
+    if (!blob) return [];
+    try {
+      const doc = JSON.parse(new TextDecoder().decode(blob));
+      const entries = doc["entries"];
+      if (!entries || typeof entries !== "object") return [];
+      return Object.values(entries).filter(
+        (v) => typeof v === "string" && !v.startsWith("did:") && !v.startsWith("bafyrei")
+      );
+    } catch {
+      return [];
+    }
+  };
+  const publicCreds = await store.getPublicCredentials(requestedResource);
+  for (const credJws of publicCreds) {
+    try {
+      const cred = await verifyDFOSCredential2(credJws, { resolveIdentity });
+      const leafRevoked = await isRevoked(cred.iss, cred.credentialCID);
+      if (leafRevoked) continue;
+      const covers = await matchesResource(cred.att, requestedResource, action, {
+        manifestLookup
+      });
+      if (!covers) continue;
+      await verifyDelegationChain(cred, { resolveIdentity, rootDID: creatorDID, isRevoked });
+      return { granted: true, source: "public-credential", credential: cred };
+    } catch {
+      continue;
+    }
+  }
+  if (credentialJWS) {
+    try {
+      const cred = await verifyDFOSCredential2(credentialJWS, { resolveIdentity });
+      const leafRevoked = await isRevoked(cred.iss, cred.credentialCID);
+      if (leafRevoked) {
+        return { granted: false, source: "none" };
+      }
+      await verifyDelegationChain(cred, { resolveIdentity, rootDID: creatorDID, isRevoked });
+      if (cred.aud !== "*") {
+        if (!requesterDID || cred.aud !== requesterDID) {
+          return { granted: false, source: "none" };
+        }
+      }
+      const covers = await matchesResource(cred.att, requestedResource, action, {
+        manifestLookup
+      });
+      if (!covers) {
+        return { granted: false, source: "none" };
+      }
+      return { granted: true, source: "request-credential", credential: cred };
+    } catch {
+      return { granted: false, source: "none" };
+    }
+  }
+  return { granted: false, source: "none" };
+};
 
 // src/sequencer.ts
 import { dagCborCanonicalEncode as dagCborCanonicalEncode2, decodeJwsUnsafe as decodeJwsUnsafe3 } from "@metalabel/dfos-protocol/crypto";
@@ -807,6 +1034,8 @@ var sequenceOps = async (store) => {
 };
 
 // src/relay.ts
+var require2 = createRequire(import.meta.url);
+var { version: RELAY_VERSION } = require2("../package.json");
 var IngestBody = z.object({
   operations: z.array(z.string()).min(1).max(100)
 });
@@ -856,10 +1085,13 @@ var createRelay = async (options) => {
     return c.json({
       did: relayDID,
       protocol: "dfos-web-relay",
-      version: "0.6.0",
-      proof: true,
-      content: contentEnabled,
-      log: logEnabled,
+      version: RELAY_VERSION,
+      capabilities: {
+        proof: true,
+        content: contentEnabled,
+        documents: contentEnabled,
+        log: logEnabled
+      },
       profile: profileArtifactJws
     });
   });
@@ -953,6 +1185,33 @@ var createRelay = async (options) => {
     const cursor = page.length === limit ? page[page.length - 1].cid : null;
     return c.json({ entries: page, cursor });
   });
+  app.get("/content/:contentId/documents", async (c) => {
+    if (!contentEnabled) return c.json({ error: "content plane not available" }, 501);
+    const contentId = c.req.param("contentId");
+    const auth = await authenticateRequest(c.req.header("authorization"), relayDID, store);
+    if (!auth) return c.json({ error: "authentication required" }, 401);
+    const chain = await store.getContentChain(contentId);
+    if (!chain) return c.json({ error: "not found" }, 404);
+    const accessError = await verifyReadAccess(
+      auth,
+      chain,
+      contentId,
+      c.req.header("x-credential"),
+      store
+    );
+    if (accessError) return accessError;
+    const after = c.req.query("after");
+    const limit = Math.min(Number(c.req.query("limit") || 100), 1e3);
+    const result = await store.getDocuments(contentId, {
+      ...after ? { after } : {},
+      limit
+    });
+    return c.json({
+      contentId,
+      documents: result.documents,
+      nextCursor: result.cursor
+    });
+  });
   app.get("/content/:contentId", async (c) => {
     const contentId = c.req.param("contentId");
     let chain = await store.getContentChain(contentId);
@@ -1007,7 +1266,8 @@ var createRelay = async (options) => {
       did: beacon.did,
       jwsToken: beacon.jwsToken,
       beaconCID: beacon.beaconCID,
-      payload: beacon.state.payload
+      manifestContentId: beacon.state.manifestContentId,
+      createdAt: beacon.state.createdAt
     });
   });
   app.get("/log", async (c) => {
@@ -1106,7 +1366,7 @@ var readBlob = async (params) => {
   if (!auth) return jsonResponse({ error: "authentication required" }, 401);
   const chain = await store.getContentChain(contentId);
   if (!chain) return jsonResponse({ error: "content chain not found" }, 404);
-  const credError = await verifyReadCredential(auth, chain, contentId, credHeader, store);
+  const credError = await verifyReadAccess(auth, chain, contentId, credHeader, store);
   if (credError) return credError;
   let documentCID = null;
   let operationFound = ref === "head";
@@ -1135,45 +1395,17 @@ var readBlob = async (params) => {
     }
   });
 };
-var verifyReadCredential = async (auth, chain, contentId, credHeader, store) => {
-  if (auth.iss === chain.state.creatorDID) return null;
-  if (!credHeader) {
-    return jsonResponse({ error: "DFOSContentRead credential required" }, 403);
-  }
-  const resolveKey = createCurrentKeyResolver(store);
-  try {
-    const vcDecoded = decodeJwsUnsafe4(credHeader);
-    if (!vcDecoded) throw new Error("invalid credential format");
-    const vcHeader = vcDecoded.header;
-    if (!vcHeader.kid) throw new Error("credential missing kid");
-    const kidHashIdx = vcHeader.kid.indexOf("#");
-    if (kidHashIdx < 0) throw new Error("credential kid must be a DID URL");
-    const vcIssuerDID = vcHeader.kid.substring(0, kidHashIdx);
-    if (vcIssuerDID !== chain.state.creatorDID) {
-      throw new Error("credential must be issued by the chain creator");
-    }
-    const issuerIdentity = await store.getIdentityChain(vcIssuerDID);
-    if (issuerIdentity?.state.isDeleted) {
-      throw new Error("credential issuer identity is deleted");
-    }
-    const creatorKey = await resolveKey(vcHeader.kid);
-    const credential = verifyCredential({
-      token: credHeader,
-      publicKey: creatorKey,
-      subject: auth.iss,
-      expectedType: VC_TYPE_CONTENT_READ
-    });
-    if (credential.iss !== chain.state.creatorDID) {
-      throw new Error("credential issuer is not the chain creator");
-    }
-    if (credential.contentId && credential.contentId !== contentId) {
-      return jsonResponse({ error: "credential contentId does not match" }, 403);
-    }
-  } catch (err) {
-    const message = err instanceof Error ? err.message : "credential verification failed";
-    return jsonResponse({ error: message }, 403);
-  }
-  return null;
+var verifyReadAccess = async (auth, chain, contentId, credHeader, store) => {
+  const result = await verifyContentAccess({
+    ...credHeader ? { credentialJWS: credHeader } : {},
+    requestedResource: `chain:${contentId}`,
+    action: "read",
+    store,
+    creatorDID: chain.state.creatorDID,
+    requesterDID: auth.iss
+  });
+  if (result.granted) return null;
+  return jsonResponse({ error: "read credential required" }, 403);
 };
 
 // src/store.ts
@@ -1189,6 +1421,10 @@ var MemoryRelayStore = class {
   countersignatures = /* @__PURE__ */ new Map();
   operationLog = [];
   peerCursors = /* @__PURE__ */ new Map();
+  /** Keyed by `issuerDID::credentialCID` for issuer-scoped revocation */
+  revocations = /* @__PURE__ */ new Map();
+  /** Keyed by credential CID */
+  publicCredentials = /* @__PURE__ */ new Map();
   async getOperation(cid) {
     return this.operations.get(cid);
   }
@@ -1239,6 +1475,98 @@ var MemoryRelayStore = class {
     existing.push(jwsToken);
     this.countersignatures.set(operationCID, existing);
   }
+  // --- revocations ---
+  async getRevocations(issuerDID) {
+    const cids = [];
+    for (const rev of this.revocations.values()) {
+      if (rev.issuerDID === issuerDID) cids.push(rev.credentialCID);
+    }
+    return cids;
+  }
+  async addRevocation(revocation) {
+    const key = `${revocation.issuerDID}::${revocation.credentialCID}`;
+    this.revocations.set(key, revocation);
+  }
+  async isCredentialRevoked(issuerDID, credentialCID) {
+    return this.revocations.has(`${issuerDID}::${credentialCID}`);
+  }
+  // --- public credentials ---
+  async getPublicCredentials(resource) {
+    const tokens = [];
+    const isChainRequest = resource.startsWith("chain:");
+    for (const cred of this.publicCredentials.values()) {
+      for (const att of cred.att) {
+        if (att.resource === resource) {
+          tokens.push(cred.jwsToken);
+          break;
+        }
+        if (isChainRequest && att.resource === "chain:*") {
+          tokens.push(cred.jwsToken);
+          break;
+        }
+        if (isChainRequest && att.resource.startsWith("manifest:")) {
+          tokens.push(cred.jwsToken);
+          break;
+        }
+      }
+    }
+    return tokens;
+  }
+  async addPublicCredential(credential) {
+    this.publicCredentials.set(credential.cid, credential);
+  }
+  async removePublicCredential(credentialCID) {
+    this.publicCredentials.delete(credentialCID);
+  }
+  // --- documents ---
+  async getDocuments(contentId, params) {
+    const chain = this.contentChains.get(contentId);
+    if (!chain) return { documents: [], cursor: null };
+    const entries = [];
+    for (const jws of chain.log) {
+      const decoded = decodeJwsUnsafe5(jws);
+      if (!decoded) continue;
+      const payload = decoded.payload;
+      const cid = typeof decoded.header.cid === "string" ? decoded.header.cid : "";
+      const documentCID = typeof payload["documentCID"] === "string" ? payload["documentCID"] : null;
+      const signerDID = typeof payload["did"] === "string" ? payload["did"] : "";
+      const createdAt = typeof payload["createdAt"] === "string" ? payload["createdAt"] : "";
+      entries.push({ cid, documentCID, signerDID, createdAt });
+    }
+    let startIdx = 0;
+    if (params.after) {
+      const idx = entries.findIndex((e) => e.cid === params.after);
+      startIdx = idx >= 0 ? idx + 1 : entries.length;
+    }
+    const page = entries.slice(startIdx, startIdx + params.limit);
+    const documents = [];
+    for (const entry of page) {
+      let document = null;
+      if (entry.documentCID) {
+        const blob = await this.getBlob({
+          creatorDID: chain.state.creatorDID,
+          documentCID: entry.documentCID
+        });
+        if (blob) {
+          try {
+            document = JSON.parse(new TextDecoder().decode(blob));
+          } catch {
+            document = null;
+          }
+        }
+      }
+      documents.push({
+        operationCID: entry.cid,
+        documentCID: entry.documentCID,
+        document,
+        signerDID: entry.signerDID,
+        createdAt: entry.createdAt
+      });
+    }
+    const cursor = page.length === params.limit ? page[page.length - 1].cid : null;
+    return { documents, cursor };
+  }
+  // --- operation log ---
   async appendToLog(entry) {
     this.operationLog.push(entry);
   }
@@ -1301,7 +1629,16 @@ var MemoryRelayStore = class {
       currentCID = op.previousCID;
     }
     const resolveKey = createKeyResolver(this);
-    const content = await verifyContentChain2({ log: path, resolveKey, enforceAuthorization: true });
+    const resolveIdentity = async (did) => {
+      const chain2 = await this.getIdentityChain(did);
+      return chain2?.state;
+    };
+    const content = await verifyContentChain2({
+      log: path,
+      resolveKey,
+      enforceAuthorization: true,
+      resolveIdentity
+    });
     const targetDecoded = decodeJwsUnsafe5(opsByCID.get(cid).jws);
     const lastCreatedAt = typeof targetDecoded?.payload?.["createdAt"] === "string" ? (targetDecoded?.payload)["createdAt"] : "";
     return { state: content, lastCreatedAt };
@@ -1357,6 +1694,7 @@ export {
   bootstrapRelayIdentity,
   computeOpCID,
   createCurrentKeyResolver,
+  createHistoricalIdentityResolver,
   createHttpPeerClient,
   createKeyResolver,
   createRelay,

package/openapi.yaml

@@ -8,7 +8,7 @@ info:
 
     Two data planes:
     - **Proof plane** (public): signed chain operations, beacons, countersignatures
-    - **Content plane** (authenticated): raw content blobs gated by DID auth tokens and VC-JWT credentials
+    - **Content plane** (authenticated): raw content blobs gated by DID auth tokens and DFOS credentials
 
 servers:
   - url: http://localhost:3000
@@ -28,7 +28,7 @@ paths:
             application/json:
               schema:
                 type: object
-                required: [did, protocol, version, proof, content, log, profile]
+                required: [did, protocol, version, capabilities, profile]
                 properties:
                   did:
                     type: string
@@ -39,16 +39,23 @@ paths:
                     enum: [dfos-web-relay]
                   version:
                     type: string
-                    example: '0.1.0'
-                  proof:
-                    type: boolean
-                    description: Always true — a relay without proof plane is not a relay
-                  content:
-                    type: boolean
-                    description: Whether the relay supports content plane (blob upload/download)
-                  log:
-                    type: boolean
-                    description: Whether the global operation log is available (GET /log)
+                    example: '0.8.0'
+                  capabilities:
+                    type: object
+                    required: [proof, content, documents, log]
+                    properties:
+                      proof:
+                        type: boolean
+                        description: Always true — a relay without proof plane is not a relay
+                      content:
+                        type: boolean
+                        description: Whether the relay supports content plane (blob upload/download)
+                      documents:
+                        type: boolean
+                        description: Whether the relay serves the documents endpoint
+                      log:
+                        type: boolean
+                        description: Whether the global operation log is available (GET /log)
                   profile:
                     type: string
                     description: The relay's profile artifact as a compact JWS token
@@ -189,13 +196,14 @@ paths:
         '404':
           $ref: '#/components/responses/NotFound'
 
-  /content/{contentId}/blob:
+  /content/{contentId}/blob/{operationCID}:
     put:
       operationId: uploadBlob
       summary: Upload a content blob
       description: |
-        Upload raw bytes for a document referenced by a content chain.
-        Requires auth token. Caller must be the chain creator.
+        Upload raw bytes for a document referenced by a content chain operation.
+        Requires auth token. Caller must be the chain creator or the signer of the
+        referenced operation.
       tags: [Content Plane]
       security:
         - BearerAuth: []
@@ -205,12 +213,12 @@ paths:
           required: true
           schema:
             type: string
-        - name: X-Document-CID
-          in: header
+        - name: operationCID
+          in: path
           required: true
           schema:
             type: string
-          description: The documentCID this blob corresponds to
+          description: CID of the content operation whose documentCID this blob satisfies
       requestBody:
         required: true
         content:
@@ -243,12 +251,13 @@ paths:
         '404':
           $ref: '#/components/responses/NotFound'
 
+  /content/{contentId}/blob:
     get:
       operationId: downloadBlob
       summary: Download a content blob at head
       description: |
         Download the raw bytes of the current document at chain head.
-        Requires auth token. Non-creators must present a DFOSContentRead credential.
+        Requires auth token. Non-creators must present a DFOS read credential.
       tags: [Content Plane]
       security:
         - BearerAuth: []
@@ -263,7 +272,7 @@ paths:
           required: false
           schema:
             type: string
-          description: DFOSContentRead VC-JWT (required for non-creators)
+          description: DFOS read credential JWS (required for non-creators)
       responses:
         '200':
           description: Blob data
@@ -311,7 +320,7 @@ paths:
           required: false
           schema:
             type: string
-          description: DFOSContentRead VC-JWT (required for non-creators)
+          description: DFOS read credential JWS (required for non-creators)
       responses:
         '200':
           description: Blob data
@@ -331,6 +340,188 @@ paths:
         '404':
           $ref: '#/components/responses/NotFound'
 
+  /content/{contentId}/documents:
+    get:
+      operationId: getDocuments
+      summary: List documents in a content chain
+      description: |
+        Returns all documents committed to a content chain as an ordered list,
+        from genesis to head. Cursor-based pagination.
+      tags: [Content Plane]
+      security:
+        - BearerAuth: []
+      parameters:
+        - name: contentId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: after
+          in: query
+          required: false
+          schema:
+            type: string
+          description: CID cursor — start after this operation CID
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+            default: 100
+            maximum: 1000
+        - name: X-Credential
+          in: header
+          required: false
+          schema:
+            type: string
+          description: DFOS read credential JWS (required for non-creators)
+      responses:
+        '200':
+          description: Document list
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [contentId, documents, nextCursor]
+                properties:
+                  contentId:
+                    type: string
+                  documents:
+                    type: array
+                    items:
+                      type: object
+                      required: [operationCID, documentCID, document, signerDID, createdAt]
+                      properties:
+                        operationCID:
+                          type: string
+                        documentCID:
+                          type: string
+                          nullable: true
+                        document:
+                          nullable: true
+                        signerDID:
+                          type: string
+                        createdAt:
+                          type: string
+                          format: date-time
+                  nextCursor:
+                    type: string
+                    nullable: true
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '501':
+          description: Documents capability not enabled
+
+  /identities/{did}/log:
+    get:
+      operationId: getIdentityLog
+      summary: Paginated log of identity chain operations
+      description: |
+        Returns operations belonging to this identity chain in chain order.
+        Cursor-based pagination.
+      tags: [Proof Plane]
+      parameters:
+        - name: did
+          in: path
+          required: true
+          schema:
+            type: string
+          description: DID of the identity
+        - name: after
+          in: query
+          required: false
+          schema:
+            type: string
+          description: CID cursor — start after this operation CID
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+            default: 100
+            maximum: 1000
+      responses:
+        '200':
+          description: Identity chain log entries
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [entries, cursor]
+                properties:
+                  entries:
+                    type: array
+                    items:
+                      type: object
+                      required: [cid, jwsToken]
+                      properties:
+                        cid:
+                          type: string
+                        jwsToken:
+                          type: string
+                  cursor:
+                    type: string
+                    nullable: true
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+  /content/{contentId}/log:
+    get:
+      operationId: getContentLog
+      summary: Paginated log of content chain operations
+      description: |
+        Returns operations belonging to this content chain in chain order.
+        Cursor-based pagination.
+      tags: [Proof Plane]
+      parameters:
+        - name: contentId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Content identifier (22-char hash)
+        - name: after
+          in: query
+          required: false
+          schema:
+            type: string
+          description: CID cursor — start after this operation CID
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+            default: 100
+            maximum: 1000
+      responses:
+        '200':
+          description: Content chain log entries
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [entries, cursor]
+                properties:
+                  entries:
+                    type: array
+                    items:
+                      type: object
+                      required: [cid, jwsToken]
+                      properties:
+                        cid:
+                          type: string
+                        jwsToken:
+                          type: string
+                  cursor:
+                    type: string
+                    nullable: true
+        '404':
+          $ref: '#/components/responses/NotFound'
+
   /countersignatures/{cid}:
     get:
       operationId: getCountersignaturesByCID
@@ -406,7 +597,7 @@ components:
           description: Error message if rejected
         kind:
           type: string
-          enum: [identity-op, content-op, beacon, countersig, beacon-countersig]
+          enum: [identity-op, content-op, beacon, artifact, countersign, revocation, credential]
         chainId:
           type: string
           description: Chain identifier (DID or contentId)
@@ -421,21 +612,19 @@ components:
           type: string
         chainType:
           type: string
-          enum: [identity, content]
+          enum: [identity, content, artifact, beacon, countersign, revocation, credential]
         chainId:
           type: string
 
     IdentityChainResponse:
       type: object
-      required: [did, log, state]
+      required: [did, headCID, state]
       properties:
         did:
           type: string
-        log:
-          type: array
-          items:
-            type: string
-          description: Ordered JWS tokens from genesis to head
+        headCID:
+          type: string
+          description: CID of the current head operation
         state:
           type: object
           required: [did, isDeleted, authKeys, assertKeys, controllerKeys]
@@ -492,7 +681,7 @@ components:
 
     BeaconResponse:
       type: object
-      required: [did, jwsToken, beaconCID, payload]
+      required: [did, jwsToken, beaconCID, manifestContentId, createdAt]
       properties:
         did:
           type: string
@@ -500,24 +689,12 @@ components:
           type: string
         beaconCID:
           type: string
-        payload:
-          type: object
-          required: [version, type, did, merkleRoot, createdAt]
-          properties:
-            version:
-              type: integer
-              enum: [1]
-            type:
-              type: string
-              enum: [beacon]
-            did:
-              type: string
-            merkleRoot:
-              type: string
-              pattern: '^[0-9a-f]{64}$'
-            createdAt:
-              type: string
-              format: date-time
+        manifestContentId:
+          type: string
+          description: Content ID of the manifest chain
+        createdAt:
+          type: string
+          format: date-time
 
     MultikeyPublicKey:
       type: object

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metalabel/dfos-web-relay",
-  "version": "0.7.1",
+  "version": "0.8.1",
   "type": "module",
   "description": "DFOS Web Relay — verifying HTTP relay for identity chains, content chains, beacons, and content blobs",
   "license": "MIT",
@@ -41,7 +41,7 @@
     "README.md"
   ],
   "dependencies": {
-    "hono": "^4.12.8",
+    "hono": "^4.12.9",
     "zod": "^4.3.6"
   },
   "peerDependencies": {
@@ -51,14 +51,13 @@
     "@types/node": "^24.10.4",
     "tsup": "^8.5.1",
     "tsx": "^4.20.3",
-    "vitest": "^4.1.0",
-    "@metalabel/dfos-protocol": "0.7.1"
+    "vitest": "^4.1.2",
+    "@metalabel/dfos-protocol": "0.8.1"
   },
   "scripts": {
     "build": "tsup",
     "clean": "rm -rf dist",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:conformance": "./tests/run-conformance.sh"
+    "test": "vitest run"
   }
 }