@metalabel/dfos-web-relay 0.10.0 → 0.12.0

package/README.md

@@ -38,19 +38,18 @@ serve({ port: 4444 });
 
 ## Routes
 
-| Method | Path                                     | Description                                                      |
-| ------ | ---------------------------------------- | ---------------------------------------------------------------- |
-| `GET`  | `/.well-known/dfos-relay`                | Relay metadata (DID, protocol version)                           |
-| `POST` | `/operations`                            | Submit signed operations (identity, content, beacon, countersig) |
-| `GET`  | `/identities/:did`                       | Get identity chain state and operation log                       |
-| `GET`  | `/content/:contentId`                    | Get content chain state and operation log                        |
-| `GET`  | `/operations/:cid`                       | Get a single operation by CID                                    |
-| `GET`  | `/beacons/:did`                          | Get beacon for an identity                                       |
-| `GET`  | `/countersignatures/:cid`                | Get countersignatures for an operation                           |
-| `GET`  | `/operations/:cid/countersignatures`     | Same as above (alias)                                            |
-| `PUT`  | `/content/:contentId/blob/:operationCID` | Upload blob (auth required)                                      |
-| `GET`  | `/content/:contentId/blob`               | Download blob at head (standing auth, or auth + credential)      |
-| `GET`  | `/content/:contentId/blob/:ref`          | Download blob at specific operation ref                          |
+| Method | Path                                          | Description                                                 |
+| ------ | --------------------------------------------- | ----------------------------------------------------------- |
+| `GET`  | `/.well-known/dfos-relay`                     | Relay metadata (DID, protocol version)                      |
+| `POST` | `/proof/v1/operations`                        | Submit signed operations (identity, content, countersig)    |
+| `GET`  | `/proof/v1/identities/:did`                   | Get identity chain state and operation log                  |
+| `GET`  | `/proof/v1/content/:contentId`                | Get content chain state and operation log                   |
+| `GET`  | `/proof/v1/operations/:cid`                   | Get a single operation by CID                               |
+| `GET`  | `/proof/v1/countersignatures/:cid`            | Get countersignatures for an operation                      |
+| `GET`  | `/proof/v1/operations/:cid/countersignatures` | Same as above (alias)                                       |
+| `PUT`  | `/content/:contentId/blob/:operationCID`      | Upload blob (auth required)                                 |
+| `GET`  | `/content/:contentId/blob`                    | Download blob at head (standing auth, or auth + credential) |
+| `GET`  | `/content/:contentId/blob/:ref`               | Download blob at specific operation ref                     |
 
 ## Blob Authorization
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { VerifiedIdentity, VerifiedContentChain, VerifiedBeacon } from '@metalabel/dfos-protocol/chain';
+import { VerifiedIdentity, VerifiedContentChain } from '@metalabel/dfos-protocol/chain';
 import { Attenuation } from '@metalabel/dfos-protocol/credentials';
 import { Hono } from 'hono';
 
@@ -17,6 +17,13 @@ interface RelayOptions {
     content?: boolean;
     /** Whether the global operation log is enabled (default: true) */
     log?: boolean;
+    /**
+     * Whether this relay accepts writes (default: true). When false, it is a LITE
+     * pull-only proof node: POST /proof/v1/operations is rejected (501), so neither
+     * client writes nor peer gossip-in are accepted. The node still ingests by
+     * PULLING from peers (syncFromPeers polls their /log).
+     */
+    write?: boolean;
     /** Peer relay configurations */
     peers?: PeerConfig[];
     /** Injected peer client — if omitted, a default HTTP implementation is used */
@@ -90,18 +97,12 @@ interface StoredContentChain {
     lastCreatedAt: string;
     state: VerifiedContentChain;
 }
-interface StoredBeacon {
-    did: string;
-    jwsToken: string;
-    beaconCID: string;
-    state: VerifiedBeacon;
-}
 interface StoredOperation {
     cid: string;
     jwsToken: string;
     /** Which chain type this operation belongs to */
-    chainType: 'identity' | 'content' | 'artifact' | 'beacon' | 'countersign' | 'revocation' | 'credential';
-    /** The chain identifier — DID for identity/beacon/artifact, contentId for content, targetCID for countersign */
+    chainType: 'identity' | 'content' | 'artifact' | 'countersign' | 'revocation' | 'credential';
+    /** The chain identifier — DID for identity/artifact, contentId for content, targetCID for countersign */
     chainId: string;
 }
 /** Key for blob storage — deduplicates across chains sharing the same document */
@@ -117,7 +118,7 @@ interface LogEntry {
     chainId: string;
 }
 /** All operation kinds in the protocol */
-type OperationKind = 'identity-op' | 'content-op' | 'beacon' | 'artifact' | 'countersign' | 'revocation' | 'credential';
+type OperationKind = 'identity-op' | 'content-op' | 'artifact' | 'countersign' | 'revocation' | 'credential';
 interface StoredRevocation {
     cid: string;
     issuerDID: string;
@@ -156,8 +157,6 @@ interface RelayStore {
     putIdentityChain(chain: StoredIdentityChain): Promise<void>;
     getContentChain(contentId: string): Promise<StoredContentChain | undefined>;
     putContentChain(chain: StoredContentChain): Promise<void>;
-    getBeacon(did: string): Promise<StoredBeacon | undefined>;
-    putBeacon(beacon: StoredBeacon): Promise<void>;
     getBlob(key: BlobKey): Promise<Uint8Array | undefined>;
     putBlob(key: BlobKey, data: Uint8Array): Promise<void>;
     getCountersignatures(operationCID: string): Promise<string[]>;
@@ -320,7 +319,6 @@ declare class MemoryRelayStore implements RelayStore {
     private operations;
     private identityChains;
     private contentChains;
-    private beacons;
     private blobs;
     private countersignatures;
     private operationLog;
@@ -335,8 +333,6 @@ declare class MemoryRelayStore implements RelayStore {
     putIdentityChain(chain: StoredIdentityChain): Promise<void>;
     getContentChain(contentId: string): Promise<StoredContentChain | undefined>;
     putContentChain(chain: StoredContentChain): Promise<void>;
-    getBeacon(did: string): Promise<StoredBeacon | undefined>;
-    putBeacon(beacon: StoredBeacon): Promise<void>;
     getBlob(key: BlobKey): Promise<Uint8Array | undefined>;
     putBlob(key: BlobKey, data: Uint8Array): Promise<void>;
     getCountersignatures(operationCID: string): Promise<string[]>;
@@ -416,22 +412,30 @@ declare const createKeyResolver: (store: RelayStore) => (kid: string) => Promise
  */
 declare const createHistoricalIdentityResolver: (store: RelayStore) => (did: string) => Promise<{
     authKeys: {
+        [x: string]: unknown;
         id: string;
         type: "Multikey";
         publicKeyMultibase: string;
     }[];
     assertKeys: {
+        [x: string]: unknown;
         id: string;
         type: "Multikey";
         publicKeyMultibase: string;
     }[];
     controllerKeys: {
+        [x: string]: unknown;
         id: string;
         type: "Multikey";
         publicKeyMultibase: string;
     }[];
     did: string;
     isDeleted: boolean;
+    services: {
+        [x: string]: unknown;
+        id: string;
+        type: string;
+    }[];
 } | undefined>;
 /**
  * Create a key resolver that only resolves current-state keys.
@@ -445,7 +449,7 @@ declare const createCurrentKeyResolver: (store: RelayStore) => (kid: string) =>
  * Ingest a batch of JWS operations
  *
  * Classifies, dependency-sorts, and processes each token. Identity operations
- * are processed first so content chains and beacons can resolve their keys.
+ * are processed first so content chains can resolve their keys.
  * Within each kind, genesis operations are processed before extensions.
  */
 declare const ingestOperations: (tokens: string[], store: RelayStore, options?: {
@@ -469,4 +473,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, bootstrapRelayIdentityFromKey, chunkOps, computeOpCID, createCurrentKeyResolver, createHistoricalIdentityResolver, 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 StoredContentChain, type StoredIdentityChain, type StoredOperation, bootstrapRelayIdentity, bootstrapRelayIdentityFromKey, chunkOps, computeOpCID, createCurrentKeyResolver, createHistoricalIdentityResolver, createHttpPeerClient, createKeyResolver, createRelay, ingestOperations, isDependencyFailure, sequenceOps };

package/dist/index.js

@@ -15,7 +15,6 @@ import {
 import {
   decodeMultikey,
   verifyArtifact,
-  verifyBeacon,
   verifyContentChain,
   verifyContentExtensionFromTrustedState,
   verifyCountersignature,
@@ -71,17 +70,6 @@ var classify = (jwsToken) => {
     const opDID = typeof payload["did"] === "string" ? payload["did"] : null;
     return { ...base, kind: "content-op", referencedDID: null, signerDID: opDID, priority: 2 };
   }
-  if (typ === "did:dfos:beacon") {
-    const beaconDID = typeof payload["did"] === "string" ? payload["did"] : null;
-    return {
-      ...base,
-      kind: "beacon",
-      referencedDID: beaconDID,
-      signerDID: null,
-      priority: 1,
-      previousCID: null
-    };
-  }
   if (typ === "did:dfos:countersign") {
     const witnessDID = typeof payload["did"] === "string" ? payload["did"] : null;
     return {
@@ -102,7 +90,7 @@ var classify = (jwsToken) => {
       referencedDID: artifactDID,
       signerDID: null,
       priority: 1,
-      // same as beacons — needs identity keys resolved first
+      // needs identity keys resolved first
       previousCID: null
     };
   }
@@ -114,7 +102,7 @@ var classify = (jwsToken) => {
       referencedDID: revocationDID,
       signerDID: null,
       priority: 1,
-      // same as beacons — needs identity keys to verify
+      // needs identity keys to verify
       previousCID: null
     };
   }
@@ -548,41 +536,6 @@ var ingestContentOp = async (jwsToken, store, logEnabled) => {
   }
   return { cid, status: "new", kind: "content-op", chainId: chain.contentId };
 };
-var ingestBeacon = async (jwsToken, store, logEnabled) => {
-  const resolveKey = createCurrentKeyResolver(store);
-  let verified;
-  try {
-    verified = await verifyBeacon({ jwsToken, resolveKey });
-  } catch (err) {
-    const message = err instanceof Error ? err.message : "verification failed";
-    return {
-      cid: await computeOpCID(jwsToken),
-      status: "rejected",
-      error: message,
-      dependencyMissing: isKeyResolutionFailure(message)
-    };
-  }
-  const did = verified.did;
-  const cid = verified.beaconCID;
-  const identity = await store.getIdentityChain(did);
-  if (identity?.state.isDeleted) {
-    return { cid, status: "rejected", error: "identity is deleted" };
-  }
-  const existing = await store.getBeacon(did);
-  if (existing) {
-    const existingTime = new Date(existing.state.createdAt).getTime();
-    const newTime = new Date(verified.createdAt).getTime();
-    if (newTime < existingTime || newTime === existingTime && cid <= existing.beaconCID) {
-      return { cid, status: "duplicate", kind: "beacon", chainId: did };
-    }
-  }
-  await store.putBeacon({ did, jwsToken, beaconCID: cid, state: verified });
-  await store.putOperation({ cid, jwsToken, chainType: "beacon", chainId: did });
-  if (logEnabled) {
-    await store.appendToLog({ cid, jwsToken, kind: "beacon", chainId: did });
-  }
-  return { cid, status: "new", kind: "beacon", chainId: did };
-};
 var ingestCountersign = async (jwsToken, store, logEnabled) => {
   const resolveKey = createKeyResolver(store);
   let verified;
@@ -880,9 +833,6 @@ var ingestOperations = async (tokens, store, options) => {
         case "content-op":
           result = await ingestContentOp(op.jwsToken, store, logEnabled);
           break;
-        case "beacon":
-          result = await ingestBeacon(op.jwsToken, store, logEnabled);
-          break;
         case "countersign":
           result = await ingestCountersign(op.jwsToken, store, logEnabled);
           break;
@@ -984,6 +934,9 @@ var bootstrapWithKeyMaterial = async (store, params) => {
   return { did, profileArtifactJws };
 };
 
+// src/types.ts
+var PROOF_BASE_PATH = "/proof/v1";
+
 // src/peer-client.ts
 var createHttpPeerClient = () => {
   const fetchJSON = async (url) => {
@@ -997,7 +950,7 @@ var createHttpPeerClient = () => {
   };
   return {
     async getIdentityLog(peerUrl, did, params) {
-      const url = new URL(`/identities/${encodeURIComponent(did)}/log`, peerUrl);
+      const url = new URL(`${PROOF_BASE_PATH}/identities/${encodeURIComponent(did)}/log`, peerUrl);
       if (params?.after) url.searchParams.set("after", params.after);
       if (params?.limit) url.searchParams.set("limit", String(params.limit));
       const data = await fetchJSON(url.toString());
@@ -1005,7 +958,10 @@ var createHttpPeerClient = () => {
       return { entries: data.entries, cursor: data.cursor ?? null };
     },
     async getContentLog(peerUrl, contentId, params) {
-      const url = new URL(`/content/${encodeURIComponent(contentId)}/log`, peerUrl);
+      const url = new URL(
+        `${PROOF_BASE_PATH}/content/${encodeURIComponent(contentId)}/log`,
+        peerUrl
+      );
       if (params?.after) url.searchParams.set("after", params.after);
       if (params?.limit) url.searchParams.set("limit", String(params.limit));
       const data = await fetchJSON(url.toString());
@@ -1013,7 +969,7 @@ var createHttpPeerClient = () => {
       return { entries: data.entries, cursor: data.cursor ?? null };
     },
     async getOperationLog(peerUrl, params) {
-      const url = new URL("/log", peerUrl);
+      const url = new URL(`${PROOF_BASE_PATH}/log`, peerUrl);
       if (params?.after) url.searchParams.set("after", params.after);
       if (params?.limit) url.searchParams.set("limit", String(params.limit));
       const data = await fetchJSON(url.toString());
@@ -1022,7 +978,7 @@ var createHttpPeerClient = () => {
     },
     async submitOperations(peerUrl, operations) {
       try {
-        const res = await fetch(new URL("/operations", peerUrl).toString(), {
+        const res = await fetch(new URL(`${PROOF_BASE_PATH}/operations`, peerUrl).toString(), {
           method: "POST",
           headers: { "Content-Type": "application/json" },
           body: JSON.stringify({ operations })
@@ -1106,6 +1062,27 @@ var hasPublicStandingAuth = async (contentId, action, store) => {
   }
   return false;
 };
+var derivePublicGrants = async (contentId, creatorDID, store) => {
+  const resource = `chain:${contentId}`;
+  const publicCreds = await store.getPublicCredentials(resource);
+  if (publicCreds.length === 0) return [];
+  const resolveIdentity = createHistoricalIdentityResolver(store);
+  const isRevoked = async (issuerDID, credentialCID) => store.isCredentialRevoked(issuerDID, credentialCID);
+  const grants = [];
+  for (const credJws of publicCreds) {
+    try {
+      const cred = await verifyDFOSCredential2(credJws, { resolveIdentity });
+      if (await isRevoked(cred.iss, cred.credentialCID)) continue;
+      if (!await matchesResource(cred.att, resource, "read")) continue;
+      await verifyDelegationChain(cred, { resolveIdentity, rootDID: creatorDID, isRevoked });
+      grants.push(credJws);
+    } catch {
+      continue;
+    }
+  }
+  grants.sort();
+  return grants;
+};
 var verifyContentAccess = async (options) => {
   const { credentialJWS, requestedResource, action, store, creatorDID, requesterDID } = options;
   if (requesterDID && requesterDID === creatorDID) {
@@ -1223,6 +1200,7 @@ var createRelay = async (options) => {
   const { store } = options;
   const contentEnabled = options.content !== false;
   const logEnabled = options.log !== false;
+  const writeEnabled = options.write !== false;
   const maxAuthTokenTTLSeconds = options.maxAuthTokenTTLSeconds ?? DEFAULT_MAX_AUTH_TOKEN_TTL_SECONDS;
   const peers = options.peers ?? [];
   const peerClient = options.peerClient;
@@ -1285,6 +1263,7 @@ var createRelay = async (options) => {
       version: RELAY_VERSION,
       capabilities: {
         proof: true,
+        write: writeEnabled,
         content: contentEnabled,
         documents: contentEnabled,
         log: logEnabled
@@ -1292,7 +1271,10 @@ var createRelay = async (options) => {
       profile: profileArtifactJws
     });
   });
-  app.post("/operations", async (c) => {
+  app.post(`${PROOF_BASE_PATH}/operations`, async (c) => {
+    if (!writeEnabled) {
+      return c.json({ error: "this relay is pull-only; writes are disabled" }, 501);
+    }
     if (exceedsBodyCap(c.req.header("content-length"))) {
       return c.json({ error: "request body too large" }, 413);
     }
@@ -1309,7 +1291,7 @@ var createRelay = async (options) => {
     const results = await ingestWithGossip(parsed.data.operations);
     return c.json({ results });
   });
-  app.get("/operations/:cid", async (c) => {
+  app.get(`${PROOF_BASE_PATH}/operations/:cid`, async (c) => {
     const cid = c.req.param("cid");
     const op = await store.getOperation(cid);
     if (!op) return c.json({ error: "not found" }, 404);
@@ -1320,7 +1302,7 @@ var createRelay = async (options) => {
       chainId: op.chainId
     });
   });
-  app.get("/identities/:did/log", async (c) => {
+  app.get(`${PROOF_BASE_PATH}/identities/:did/log`, async (c) => {
     const did = c.req.param("did");
     const chain = await store.getIdentityChain(did);
     if (!chain) return c.json({ error: "not found" }, 404);
@@ -1339,7 +1321,7 @@ var createRelay = async (options) => {
     const cursor = page.length === limit ? page[page.length - 1].cid : null;
     return c.json({ entries: page, cursor });
   });
-  app.get("/identities/:did{.+}", async (c) => {
+  app.get(`${PROOF_BASE_PATH}/identities/:did{.+}`, async (c) => {
     const did = c.req.param("did");
     let chain = await store.getIdentityChain(did);
     if (!chain && readThroughPeers.length > 0 && peerClient) {
@@ -1366,7 +1348,7 @@ var createRelay = async (options) => {
       state: chain.state
     });
   });
-  app.get("/content/:contentId/log", async (c) => {
+  app.get(`${PROOF_BASE_PATH}/content/:contentId/log`, async (c) => {
     const contentId = c.req.param("contentId");
     const chain = await store.getContentChain(contentId);
     if (!chain) return c.json({ error: "not found" }, 404);
@@ -1420,7 +1402,7 @@ var createRelay = async (options) => {
       nextCursor: result.cursor
     });
   });
-  app.get("/content/:contentId", async (c) => {
+  app.get(`${PROOF_BASE_PATH}/content/:contentId`, async (c) => {
     const contentId = c.req.param("contentId");
     let chain = await store.getContentChain(contentId);
     if (!chain && readThroughPeers.length > 0 && peerClient) {
@@ -1445,10 +1427,11 @@ var createRelay = async (options) => {
       contentId: chain.contentId,
       genesisCID: chain.genesisCID,
       headCID: chain.state.headCID,
-      state: chain.state
+      state: chain.state,
+      publicGrants: await derivePublicGrants(contentId, chain.state.creatorDID, store)
     });
   });
-  app.get("/countersignatures/:cid", async (c) => {
+  app.get(`${PROOF_BASE_PATH}/countersignatures/:cid`, async (c) => {
     const cid = c.req.param("cid");
     const op = await store.getOperation(cid);
     if (!op) {
@@ -1459,26 +1442,14 @@ var createRelay = async (options) => {
     const countersigs = await store.getCountersignatures(cid);
     return c.json({ operationCID: cid, countersignatures: countersigs });
   });
-  app.get("/operations/:cid/countersignatures", async (c) => {
+  app.get(`${PROOF_BASE_PATH}/operations/:cid/countersignatures`, async (c) => {
     const cid = c.req.param("cid");
     const op = await store.getOperation(cid);
     if (!op) return c.json({ error: "not found" }, 404);
     const countersigs = await store.getCountersignatures(cid);
     return c.json({ operationCID: cid, countersignatures: countersigs });
   });
-  app.get("/beacons/:did{.+}", async (c) => {
-    const did = c.req.param("did");
-    const beacon = await store.getBeacon(did);
-    if (!beacon) return c.json({ error: "not found" }, 404);
-    return c.json({
-      did: beacon.did,
-      jwsToken: beacon.jwsToken,
-      beaconCID: beacon.beaconCID,
-      manifestContentId: beacon.state.manifestContentId,
-      createdAt: beacon.state.createdAt
-    });
-  });
-  app.get("/log", async (c) => {
+  app.get(`${PROOF_BASE_PATH}/log`, async (c) => {
     if (!logEnabled) return c.json({ error: "global log not available" }, 501);
     const afterParam = c.req.query("after");
     const limit = parseLimit(c.req.query("limit"), 100, 1e3);
@@ -1643,7 +1614,6 @@ var MemoryRelayStore = class {
   operations = /* @__PURE__ */ new Map();
   identityChains = /* @__PURE__ */ new Map();
   contentChains = /* @__PURE__ */ new Map();
-  beacons = /* @__PURE__ */ new Map();
   blobs = /* @__PURE__ */ new Map();
   countersignatures = /* @__PURE__ */ new Map();
   operationLog = [];
@@ -1670,12 +1640,6 @@ var MemoryRelayStore = class {
   async putContentChain(chain) {
     this.contentChains.set(chain.contentId, chain);
   }
-  async getBeacon(did) {
-    return this.beacons.get(did);
-  }
-  async putBeacon(beacon) {
-    this.beacons.set(beacon.did, beacon);
-  }
   async getBlob(key) {
     return this.blobs.get(blobKeyString(key));
   }

package/openapi.yaml

@@ -4,10 +4,10 @@ info:
   version: 0.9.0
   description: |
     HTTP relay for the DFOS protocol. Receives, verifies, stores, and serves
-    identity chains, content chains, beacons, countersignatures, and content blobs.
+    identity chains, content chains, countersignatures, and content blobs.
 
     Two data planes:
-    - **Proof plane** (public): signed chain operations, beacons, countersignatures
+    - **Proof plane** (public): signed chain operations, countersignatures
     - **Content plane** (authenticated): raw content blobs gated by DID auth tokens and DFOS credentials
 
 servers:
@@ -33,7 +33,7 @@ paths:
                   did:
                     type: string
                     description: The relay's DID
-                    example: 'did:dfos:e3vvtck42d4eacdnzvtrn6'
+                    example: 'did:dfos:cnnnft9f8a2rn938d6nkz38r847v2kr'
                   protocol:
                     type: string
                     enum: [dfos-web-relay]
@@ -42,11 +42,14 @@ paths:
                     example: '0.8.0'
                   capabilities:
                     type: object
-                    required: [proof, content, documents, log]
+                    required: [proof, write, content, documents, log]
                     properties:
                       proof:
                         type: boolean
                         description: Always true — a relay without proof plane is not a relay
+                      write:
+                        type: boolean
+                        description: Whether the relay accepts writes via POST /proof/v1/operations (false = lite pull-only node)
                       content:
                         type: boolean
                         description: Whether the relay supports content plane (blob upload/download)
@@ -55,18 +58,18 @@ paths:
                         description: Whether the relay serves the documents endpoint
                       log:
                         type: boolean
-                        description: Whether the global operation log is available (GET /log)
+                        description: Whether the global operation log is available (GET /proof/v1/log)
                   profile:
                     type: string
                     description: The relay's profile artifact as a compact JWS token
 
-  /operations:
+  /proof/v1/operations:
     post:
       operationId: ingestOperations
       summary: Submit operations for ingestion
       description: |
         Accept a batch of JWS tokens — identity operations, content operations,
-        beacons, and countersignatures. The relay classifies, dependency-sorts,
+        and countersignatures. The relay classifies, dependency-sorts,
         verifies, and stores each token.
       tags: [Proof Plane]
       requestBody:
@@ -99,8 +102,10 @@ paths:
                       $ref: '#/components/schemas/IngestionResult'
         '400':
           $ref: '#/components/responses/BadRequest'
+        '501':
+          description: Writes disabled — relay is a lite pull-only node (capabilities.write is false)
 
-  /operations/{cid}:
+  /proof/v1/operations/{cid}:
     get:
       operationId: getOperation
       summary: Get an operation by CID
@@ -122,7 +127,7 @@ paths:
         '404':
           $ref: '#/components/responses/NotFound'
 
-  /operations/{cid}/countersignatures:
+  /proof/v1/operations/{cid}/countersignatures:
     get:
       operationId: getCountersignatures
       summary: Get countersignatures for an operation
@@ -152,7 +157,7 @@ paths:
         '404':
           $ref: '#/components/responses/NotFound'
 
-  /identities/{did}:
+  /proof/v1/identities/{did}:
     get:
       operationId: getIdentityChain
       summary: Get an identity chain by DID
@@ -163,7 +168,7 @@ paths:
           required: true
           schema:
             type: string
-          description: 'DID of the identity (e.g., did:dfos:e3vvtck42d4eacdnzvtrn6)'
+          description: 'DID of the identity (e.g., did:dfos:cnnnft9f8a2rn938d6nkz38r847v2kr)'
       responses:
         '200':
           description: Identity chain state and log
@@ -174,7 +179,7 @@ paths:
         '404':
           $ref: '#/components/responses/NotFound'
 
-  /content/{contentId}:
+  /proof/v1/content/{contentId}:
     get:
       operationId: getContentChain
       summary: Get a content chain by content ID
@@ -414,15 +419,15 @@ paths:
         '404':
           $ref: '#/components/responses/NotFound'
         '501':
-          description: Documents capability not enabled
+          description: Content plane not enabled (the documents endpoint is part of the content plane)
 
-  /log:
+  /proof/v1/log:
     get:
       operationId: getLog
       summary: Paginated global log of all accepted operations
       description: |
         Returns every operation the relay has accepted — across all identity and
-        content chains, plus beacons and countersignatures — in acceptance order.
+        content chains, plus countersignatures — in acceptance order.
         Cursor-based pagination. Used by peer relays to background-sync. Available
         only when the relay advertises the `log` capability; otherwise returns 501.
       tags: [Proof Plane]
@@ -462,15 +467,7 @@ paths:
                         kind:
                           type: string
                           enum:
-                            [
-                              identity-op,
-                              content-op,
-                              beacon,
-                              artifact,
-                              countersign,
-                              revocation,
-                              credential,
-                            ]
+                            [identity-op, content-op, artifact, countersign, revocation, credential]
                         chainId:
                           type: string
                           description: Chain identifier (DID or contentId)
@@ -480,7 +477,7 @@ paths:
         '501':
           description: Global log capability not enabled
 
-  /identities/{did}/log:
+  /proof/v1/identities/{did}/log:
     get:
       operationId: getIdentityLog
       summary: Paginated log of identity chain operations
@@ -533,7 +530,7 @@ paths:
         '404':
           $ref: '#/components/responses/NotFound'
 
-  /content/{contentId}/log:
+  /proof/v1/content/{contentId}/log:
     get:
       operationId: getContentLog
       summary: Paginated log of content chain operations
@@ -586,10 +583,10 @@ paths:
         '404':
           $ref: '#/components/responses/NotFound'
 
-  /countersignatures/{cid}:
+  /proof/v1/countersignatures/{cid}:
     get:
       operationId: getCountersignaturesByCID
-      summary: Get countersignatures for any CID (operation or beacon)
+      summary: Get countersignatures for an operation CID
       tags: [Proof Plane]
       parameters:
         - name: cid
@@ -597,7 +594,7 @@ paths:
           required: true
           schema:
             type: string
-          description: CIDv1 of the operation or beacon
+          description: CIDv1 of the operation
       responses:
         '200':
           description: Countersignatures
@@ -617,27 +614,6 @@ paths:
         '404':
           $ref: '#/components/responses/NotFound'
 
-  /beacons/{did}:
-    get:
-      operationId: getBeacon
-      summary: Get the latest beacon for a DID
-      tags: [Proof Plane]
-      parameters:
-        - name: did
-          in: path
-          required: true
-          schema:
-            type: string
-      responses:
-        '200':
-          description: Latest beacon
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/BeaconResponse'
-        '404':
-          $ref: '#/components/responses/NotFound'
-
 components:
   securitySchemes:
     BearerAuth:
@@ -661,7 +637,7 @@ components:
           description: Error message if rejected
         kind:
           type: string
-          enum: [identity-op, content-op, beacon, artifact, countersign, revocation, credential]
+          enum: [identity-op, content-op, artifact, countersign, revocation, credential]
         chainId:
           type: string
           description: Chain identifier (DID or contentId)
@@ -676,7 +652,7 @@ components:
           type: string
         chainType:
           type: string
-          enum: [identity, content, artifact, beacon, countersign, revocation, credential]
+          enum: [identity, content, artifact, countersign, revocation, credential]
         chainId:
           type: string
 
@@ -691,7 +667,7 @@ components:
           description: CID of the current head operation
         state:
           type: object
-          required: [did, isDeleted, authKeys, assertKeys, controllerKeys]
+          required: [did, isDeleted, authKeys, assertKeys, controllerKeys, services]
           properties:
             did:
               type: string
@@ -709,6 +685,22 @@ components:
               type: array
               items:
                 $ref: '#/components/schemas/MultikeyPublicKey'
+            services:
+              type: array
+              description: >-
+                Resolved discovery vocabulary (controller-signed). Each entry has
+                a common envelope {id, type}; recognized types DfosRelay and
+                ContentAnchor carry type-specific fields. The namespace is open —
+                unrecognized types are preserved verbatim.
+              items:
+                type: object
+                required: [id, type]
+                properties:
+                  id:
+                    type: string
+                  type:
+                    type: string
+                additionalProperties: true
 
     ContentChainResponse:
       type: object
@@ -743,23 +735,6 @@ components:
             creatorDID:
               type: string
 
-    BeaconResponse:
-      type: object
-      required: [did, jwsToken, beaconCID, manifestContentId, createdAt]
-      properties:
-        did:
-          type: string
-        jwsToken:
-          type: string
-        beaconCID:
-          type: string
-        manifestContentId:
-          type: string
-          description: Content ID of the manifest chain
-        createdAt:
-          type: string
-          format: date-time
-
     MultikeyPublicKey:
       type: object
       required: [id, type, publicKeyMultibase]
@@ -809,6 +784,6 @@ tags:
   - name: Meta
     description: Relay metadata and discovery
   - name: Proof Plane
-    description: Public routes for signed chain operations, beacons, and countersignatures
+    description: Public routes for signed chain operations and countersignatures
   - name: Content Plane
     description: Authenticated routes for content blob storage and retrieval

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@metalabel/dfos-web-relay",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "type": "module",
-  "description": "DFOS Web Relay — verifying HTTP relay for identity chains, content chains, beacons, and content blobs",
+  "description": "DFOS Web Relay — verifying HTTP relay for identity chains, content chains, and content blobs",
   "license": "MIT",
   "author": "Metalabel <hello@metalabel.com> (https://metalabel.com)",
   "repository": {
@@ -45,14 +45,14 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@metalabel/dfos-protocol": "^0.10.0"
+    "@metalabel/dfos-protocol": "^0.12.0"
   },
   "devDependencies": {
     "@types/node": "^24.10.4",
     "tsup": "^8.5.1",
     "tsx": "^4.22.4",
     "vitest": "^4.1.8",
-    "@metalabel/dfos-protocol": "0.10.0"
+    "@metalabel/dfos-protocol": "0.12.0"
   },
   "scripts": {
     "build": "tsup",