@metalabel/dfos-web-relay 0.3.0 → 0.4.0

package/RELAY.md

@@ -86,6 +86,8 @@ First-seen-wins. If a chain head has already advanced past the `previousOperatio
 
 Duplicate submissions (same operation CID) are silently accepted (idempotent).
 
+Duplicate countersignatures (same witness DID, same target CID) MUST be deduplicated. The relay MUST NOT increase the countersignature count on resubmission. Resubmission SHOULD return `accepted` (idempotent).
+
 ### Result Ordering
 
 Ingestion results are returned in the same order as the input `operations` array, regardless of internal processing order. `results[i]` corresponds to `operations[i]`.
@@ -105,16 +107,18 @@ The relay does not currently sign operations or participate in the protocol as a
 
 ## Content Plane Access
 
-### Blob Upload (`PUT /content/:contentId/blob`)
+### Blob Upload (`PUT /content/:contentId/blob/:operationCID`)
+
+The upload path mirrors the download path — the operation CID identifies which operation's document is being uploaded.
 
 Requirements:
 
 - Valid auth token (Bearer header)
-- The authenticated DID must be the content chain creator
-- The `X-Document-CID` header must reference a `documentCID` that appears in the chain's operation log
-- The uploaded bytes must hash to the claimed `documentCID` (dag-cbor + sha-256 verification)
+- The operation CID must reference an operation in this content chain that has a `documentCID`
+- The authenticated DID must be either the chain creator OR the signer of the referenced operation (enabling delegated uploads)
+- The uploaded bytes must hash to the operation's `documentCID` (dag-cbor + sha-256 verification)
 
-Blobs are stored by `(creatorDID, documentCID)` — if multiple content chains by the same creator reference the same document, the blob is shared (deduplication).
+Blobs are stored by `(creatorDID, documentCID)` — always keyed to the chain creator regardless of who uploads. If multiple content chains by the same creator reference the same document, the blob is shared (deduplication).
 
 ### Blob Download (`GET /content/:contentId/blob[/:ref]`)
 
@@ -196,7 +200,7 @@ The returned Hono app exposes:
 | `GET`  | `/identities/:did`                   | proof   | none                    |
 | `GET`  | `/content/:contentId`                | proof   | none                    |
 | `GET`  | `/beacons/:did`                      | proof   | none                    |
-| `PUT`  | `/content/:contentId/blob`           | content | auth token              |
+| `PUT`  | `/content/:contentId/blob/:opCID`    | content | auth token              |
 | `GET`  | `/content/:contentId/blob[/:ref]`    | content | auth token + credential |
 
 ---

package/dist/index.js

@@ -512,32 +512,29 @@ var createRelay = (options) => {
       payload: beacon.state.payload
     });
   });
-  app.put("/content/:contentId/blob", async (c) => {
+  app.put("/content/:contentId/blob/:operationCID", async (c) => {
     const contentId = c.req.param("contentId");
-    const documentCID = c.req.header("x-document-cid");
-    if (!documentCID) {
-      return c.json({ error: "missing X-Document-CID header" }, 400);
-    }
+    const operationCID = c.req.param("operationCID");
     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: "content chain not found" }, 404);
-    if (chain.state.creatorDID !== auth.iss) {
-      return c.json({ error: "not the chain creator" }, 403);
-    }
-    const chainLog = chain.log;
-    let documentReferenced = false;
-    for (const token of chainLog) {
+    let documentCID = null;
+    let operationSignerDID = null;
+    for (const token of chain.log) {
       const decoded = decodeJwsUnsafe3(token);
       if (!decoded) continue;
+      if (decoded.header.cid !== operationCID) continue;
       const payload = decoded.payload;
-      if (payload["documentCID"] === documentCID) {
-        documentReferenced = true;
-        break;
-      }
+      documentCID = typeof payload["documentCID"] === "string" ? payload["documentCID"] : null;
+      operationSignerDID = typeof payload["did"] === "string" ? payload["did"] : null;
+      break;
+    }
+    if (!documentCID) {
+      return c.json({ error: "operation not found in chain or has no documentCID" }, 404);
     }
-    if (!documentReferenced) {
-      return c.json({ error: "documentCID not referenced in chain" }, 400);
+    if (auth.iss !== chain.state.creatorDID && auth.iss !== operationSignerDID) {
+      return c.json({ error: "not authorized \u2014 must be chain creator or operation signer" }, 403);
     }
     const bytes = new Uint8Array(await c.req.arrayBuffer());
     try {
@@ -549,8 +546,8 @@ var createRelay = (options) => {
     } catch {
       return c.json({ error: "blob bytes do not match documentCID" }, 400);
     }
-    await store.putBlob({ creatorDID: auth.iss, documentCID }, bytes);
-    return c.json({ status: "stored", contentId, documentCID });
+    await store.putBlob({ creatorDID: chain.state.creatorDID, documentCID }, bytes);
+    return c.json({ status: "stored", contentId, documentCID, operationCID });
   });
   app.get("/content/:contentId/blob", async (c) => {
     return await readBlob({
@@ -651,6 +648,7 @@ var verifyReadCredential = async (auth, chain, contentId, credHeader, store) =>
 };
 
 // src/store.ts
+import { decodeJwsUnsafe as decodeJwsUnsafe4 } from "@metalabel/dfos-protocol/crypto";
 var blobKeyString = (key) => `${key.creatorDID}::${key.documentCID}`;
 var MemoryRelayStore = class {
   operations = /* @__PURE__ */ new Map();
@@ -694,7 +692,18 @@ var MemoryRelayStore = class {
   }
   async addCountersignature(operationCID, jwsToken) {
     const existing = this.countersignatures.get(operationCID) ?? [];
-    if (existing.includes(jwsToken)) return;
+    const decoded = decodeJwsUnsafe4(jwsToken);
+    if (decoded) {
+      const kid = decoded.header.kid;
+      const witnessDID = kid.includes("#") ? kid.split("#")[0] : kid;
+      for (const cs of existing) {
+        const d = decodeJwsUnsafe4(cs);
+        if (!d) continue;
+        const existingKid = d.header.kid;
+        const existingDID = existingKid.includes("#") ? existingKid.split("#")[0] : existingKid;
+        if (existingDID === witnessDID) return;
+      }
+    }
     existing.push(jwsToken);
     this.countersignatures.set(operationCID, existing);
   }

package/dist/serve.d.ts

@@ -0,0 +1,21 @@
+import { Server } from 'node:http';
+import { Hono } from 'hono';
+
+interface ServeOptions {
+    port?: number;
+    hostname?: string;
+}
+/**
+ * Start a Node HTTP server for a DFOS web relay.
+ *
+ * ```ts
+ * import { createRelay, MemoryRelayStore } from '@metalabel/dfos-web-relay';
+ * import { serve } from '@metalabel/dfos-web-relay/node';
+ *
+ * const relay = createRelay({ relayDID: 'did:dfos:myrelay', store: new MemoryRelayStore() });
+ * serve(relay, { port: 4444 });
+ * ```
+ */
+declare const serve: (app: Hono, options?: ServeOptions) => Server;
+
+export { type ServeOptions, serve };

package/dist/serve.js

@@ -0,0 +1,31 @@
+// src/serve.ts
+import { createServer } from "http";
+var serve = (app, options = {}) => {
+  const { port = 4444, hostname } = options;
+  const server = createServer(async (req, res) => {
+    const url = new URL(req.url ?? "/", `http://${hostname ?? "localhost"}:${port}`);
+    const chunks = [];
+    for await (const chunk of req) chunks.push(chunk);
+    const body = Buffer.concat(chunks);
+    const headers = new Headers();
+    for (const [k, v] of Object.entries(req.headers)) {
+      if (v) headers.set(k, Array.isArray(v) ? v.join(", ") : v);
+    }
+    const method = req.method ?? "GET";
+    const init = { method, headers };
+    if (!["GET", "HEAD"].includes(method)) {
+      init.body = body;
+    }
+    const response = await app.fetch(new Request(url.toString(), init));
+    res.writeHead(response.status, Object.fromEntries(response.headers.entries()));
+    const buf = Buffer.from(await response.arrayBuffer());
+    res.end(buf);
+  });
+  server.listen(port, hostname, () => {
+    console.log(`DFOS web relay listening on http://${hostname ?? "localhost"}:${port}`);
+  });
+  return server;
+};
+export {
+  serve
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metalabel/dfos-web-relay",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "DFOS Web Relay — verifying HTTP relay for identity chains, content chains, beacons, and content blobs",
   "license": "MIT",
@@ -28,6 +28,10 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./node": {
+      "import": "./dist/serve.js",
+      "types": "./dist/serve.d.ts"
     }
   },
   "files": [
@@ -42,13 +46,13 @@
     "zod": "^4.3.6"
   },
   "peerDependencies": {
-    "@metalabel/dfos-protocol": "^0.3.0"
+    "@metalabel/dfos-protocol": "^0.4.0"
   },
   "devDependencies": {
     "@types/node": "^24.10.4",
     "tsup": "^8.5.1",
     "vitest": "^4.0.18",
-    "@metalabel/dfos-protocol": "0.3.0"
+    "@metalabel/dfos-protocol": "0.4.0"
   },
   "scripts": {
     "build": "tsup",