@metalabel/dfos-web-relay 0.11.0 → 0.13.0

package/README.md

@@ -38,18 +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, 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`  | `/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

@@ -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 */
@@ -405,16 +412,19 @@ 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;

package/dist/index.js

@@ -934,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) => {
@@ -947,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());
@@ -955,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());
@@ -963,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());
@@ -972,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 })
@@ -1173,6 +1179,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;
@@ -1235,14 +1242,17 @@ var createRelay = async (options) => {
       version: RELAY_VERSION,
       capabilities: {
         proof: true,
+        write: writeEnabled,
         content: contentEnabled,
-        documents: contentEnabled,
         log: logEnabled
       },
       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);
     }
@@ -1259,7 +1269,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);
@@ -1270,7 +1280,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);
@@ -1289,7 +1299,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) {
@@ -1316,7 +1326,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);
@@ -1370,7 +1380,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) {
@@ -1398,7 +1408,7 @@ var createRelay = async (options) => {
       state: chain.state
     });
   });
-  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) {
@@ -1409,14 +1419,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("/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);

package/openapi.yaml

@@ -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,12 +58,12 @@ 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
@@ -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,9 +419,9 @@ 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
@@ -472,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
@@ -525,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
@@ -578,7 +583,7 @@ paths:
         '404':
           $ref: '#/components/responses/NotFound'
 
-  /countersignatures/{cid}:
+  /proof/v1/countersignatures/{cid}:
     get:
       operationId: getCountersignaturesByCID
       summary: Get countersignatures for an operation CID

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metalabel/dfos-web-relay",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "type": "module",
   "description": "DFOS Web Relay — verifying HTTP relay for identity chains, content chains, and content blobs",
   "license": "MIT",
@@ -45,14 +45,14 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@metalabel/dfos-protocol": "^0.11.0"
+    "@metalabel/dfos-protocol": "^0.13.0"
   },
   "devDependencies": {
     "@types/node": "^24.10.4",
     "tsup": "^8.5.1",
     "tsx": "^4.22.4",
     "vitest": "^4.1.8",
-    "@metalabel/dfos-protocol": "0.11.0"
+    "@metalabel/dfos-protocol": "0.13.0"
   },
   "scripts": {
     "build": "tsup",