@metalabel/dfos-web-relay 0.3.0 → 0.4.1

package/README.md

@@ -2,7 +2,7 @@
 
 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.
 
-See [RELAY.md](./RELAY.md) for the full protocol specification.
+See [RELAY.md](./RELAY.md) for the full relay specification.
 
 ## Install
 
@@ -12,6 +12,8 @@ npm install @metalabel/dfos-web-relay @metalabel/dfos-protocol
 
 ## Usage
 
+### Embedded (Hono app)
+
 ```typescript
 import { createRelay, MemoryRelayStore } from '@metalabel/dfos-web-relay';
 
@@ -24,6 +26,77 @@ const relay = createRelay({
 export default relay;
 ```
 
+### Standalone (Node.js)
+
+```typescript
+import { serve } from '@metalabel/dfos-web-relay/node';
+
+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 (auth + credential)                        |
+| `GET`  | `/content/:contentId/blob/:ref`          | Download blob at specific operation ref                          |
+
+## Blob Authorization
+
+**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/
+```
+
+71 tests covering:
+
+- Well-known discovery
+- Identity lifecycle (create, update, delete, batch, idempotency, controller key rotation)
+- Content lifecycle (create, update, delete, fork rejection, 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)
+
+The conformance suite depends on [`dfos-protocol-go`](../dfos-protocol-go) for protocol operations.
+
+## Custom Store
+
+Implement the `RelayStore` interface to use any persistence backend:
+
+```typescript
+import type { RelayStore } from '@metalabel/dfos-web-relay';
+```
+
+`MemoryRelayStore` is provided as a reference implementation and for testing.
+
 ## License
 
 MIT

package/RELAY.md

@@ -84,7 +84,23 @@ Each operation is verified against the relay's stored state:
 
 First-seen-wins. If a chain head has already advanced past the `previousOperationCID` referenced by an incoming operation, the new operation is rejected. The relay does not attempt to resolve forks — the first valid extension wins.
 
-Duplicate submissions (same operation CID) are silently accepted (idempotent).
+Duplicate submissions (same operation CID, same JWS token) are silently accepted (idempotent). Submissions with the same CID but a different JWS token are rejected — since Ed25519 is deterministic, a different token for the same payload means a different signing key, which is either a self-countersign attempt or an unauthorized re-sign.
+
+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).
+
+### Deletion Semantics
+
+Deletion means the identity stops being an active participant. Historical operations remain verifiable — keys persist in state for signature verification — but no new acts flow from a deleted identity.
+
+Specifically:
+
+- **Identity operations after deletion**: Rejected. A deleted identity chain is sealed.
+- **Content operations after deletion**: Rejected. A deleted content chain is sealed.
+- **Beacons from deleted identities**: Rejected. A deleted identity MUST NOT publish new beacons.
+- **Credentials from deleted issuers**: Rejected. Identity deletion revokes all authority, including outstanding `DFOSContentRead` and `DFOSContentWrite` credentials issued by the deleted identity. Credentials that were valid at time of issuance cease to be honored once the issuer is deleted.
+- **Countersignatures on existing operations**: Still accepted. Deletion of the original author does not prevent other identities from attesting to operations that already exist in the relay.
+
+Self-countersignatures — where the witness DID matches the operation author DID — are rejected. A countersignature's semantic is "a distinct witness attests." Signing your own operation is redundant with the original signature.
 
 ### Result Ordering
 
@@ -105,16 +121,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 +214,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

@@ -135,7 +135,16 @@ var ingestIdentityOp = async (jwsToken, store) => {
   const encoded = await dagCborCanonicalEncode(payload);
   const cid = encoded.cid.toString();
   const existing = await store.getOperation(cid);
-  if (existing) return { cid, status: "accepted", kind: "identity-op", chainId: existing.chainId };
+  if (existing) {
+    if (existing.jwsToken !== jwsToken) {
+      return {
+        cid,
+        status: "rejected",
+        error: "operation already exists with a different signature"
+      };
+    }
+    return { cid, status: "accepted", kind: "identity-op", chainId: existing.chainId };
+  }
   const opType = payload["type"];
   const isGenesis = opType === "create";
   if (isGenesis) {
@@ -165,7 +174,23 @@ var ingestContentOp = async (jwsToken, store) => {
   const encoded = await dagCborCanonicalEncode(payload);
   const cid = encoded.cid.toString();
   const existing = await store.getOperation(cid);
-  if (existing) return { cid, status: "accepted", kind: "content-op", chainId: existing.chainId };
+  if (existing) {
+    if (existing.jwsToken !== jwsToken) {
+      return {
+        cid,
+        status: "rejected",
+        error: "operation already exists with a different signature"
+      };
+    }
+    return { cid, status: "accepted", kind: "content-op", chainId: existing.chainId };
+  }
+  const signerDID = payload["did"];
+  if (typeof signerDID === "string") {
+    const signerIdentity = await store.getIdentityChain(signerDID);
+    if (signerIdentity?.state.isDeleted) {
+      return { cid, status: "rejected", error: "signer identity is deleted" };
+    }
+  }
   const resolveKey = createKeyResolver(store);
   const opType = payload["type"];
   const isGenesis = opType === "create";
@@ -198,6 +223,10 @@ var ingestContentOp = async (jwsToken, store) => {
   const chain = await store.getContentChain(prevOp.chainId);
   if (!chain)
     return { cid, status: "rejected", error: `content chain not found: ${prevOp.chainId}` };
+  const creatorIdentity = await store.getIdentityChain(chain.state.creatorDID);
+  if (creatorIdentity?.state.isDeleted) {
+    return { cid, status: "rejected", error: "content creator identity is deleted" };
+  }
   if (chain.state.headCID !== previousCID) {
     return { cid, status: "rejected", error: "chain has diverged (first-seen-wins)" };
   }
@@ -228,6 +257,10 @@ var ingestBeacon = async (jwsToken, store) => {
   }
   const did = verified.payload.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.payload.createdAt).getTime();
@@ -512,32 +545,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 +579,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({
@@ -630,6 +660,10 @@ var verifyReadCredential = async (auth, chain, contentId, credHeader, store) =>
     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,
@@ -651,6 +685,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 +729,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.1",
   "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",