@metalabel/dfos-web-relay 0.4.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,10 +84,24 @@ 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
 
 Ingestion results are returned in the same order as the input `operations` array, regardless of internal processing order. `results[i]` corresponds to `operations[i]`.

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();
@@ -627,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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metalabel/dfos-web-relay",
-  "version": "0.4.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",