@metalabel/dfos-web-relay 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Metalabel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @metalabel/dfos-web-relay
+
+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.
+
+## Install
+
+```bash
+npm install @metalabel/dfos-web-relay @metalabel/dfos-protocol
+```
+
+## Usage
+
+```typescript
+import { createRelay, MemoryRelayStore } from '@metalabel/dfos-web-relay';
+
+const relay = createRelay({
+  relayDID: 'did:dfos:myrelay00000000000000',
+  store: new MemoryRelayStore(),
+});
+
+// Mount on any Hono-compatible runtime
+export default relay;
+```
+
+## License
+
+MIT

package/RELAY.md

@@ -0,0 +1,210 @@
+# DFOS Web Relay
+
+An HTTP relay for the DFOS protocol — receives, verifies, stores, and serves identity chains, content chains, beacons, countersignatures, and content blobs.
+
+This spec is under active review. Discuss it in the [clear.txt](https://clear.dfos.com) space on DFOS.
+
+[Source](https://github.com/metalabel/dfos/tree/main/packages/dfos-web-relay) · [npm](https://www.npmjs.com/package/@metalabel/dfos-web-relay) · [Protocol](https://protocol.dfos.com)
+
+---
+
+## Philosophy
+
+The DFOS protocol defines signed chain primitives — identity and content chains, beacons, credentials — but says nothing about transport. A web relay is the HTTP layer that carries these primitives between participants.
+
+Relays are not authorities. They verify what they receive and serve what they've verified, but they don't issue identity, grant permissions, or define content semantics. Any relay implementing the same verification rules produces the same acceptance/rejection decisions for the same operations. Clients can replicate their data across multiple relays without coordination.
+
+A relay is a library, not a service. `createRelay()` returns a portable Hono application that any runtime can host — Node.js, Cloudflare Workers, Deno, Bun, a Docker container, a Raspberry Pi. The consumer provides a storage backend and configuration. The relay handles verification and HTTP semantics.
+
+---
+
+## Two Planes
+
+The relay serves two distinct planes of data with different access models:
+
+### Proof Plane (public)
+
+Signed chain operations, beacons, and countersignatures. These are cryptographic proofs — anyone can verify them with a public key. The proof plane gossips freely: relays push operations to peers, peers verify and store independently.
+
+All proof plane routes are unauthenticated. The operations themselves carry their own authentication (Ed25519 signatures).
+
+### Content Plane (private)
+
+Raw content blobs — the actual documents that content chains commit to via `documentCID`. The content plane never gossips. Blobs are stored by the relay that received them and served only to authorized readers.
+
+Content plane access requires two credentials:
+
+- **Auth token**: A DID-signed JWT proving the caller controls an identity (AuthN)
+- **Read credential** (for non-creators): A `DFOSContentRead` VC-JWT issued by the content creator, granting the caller read access (AuthZ)
+
+The content creator (the DID that signed the genesis content operation) can always read their own blobs with just an auth token.
+
+---
+
+## Operation Ingestion
+
+All proof plane artifacts enter through a single endpoint: `POST /operations`. The request body is an array of JWS tokens — identity operations, content operations, beacons, and countersignatures can be mixed freely in the same batch.
+
+### Classification
+
+Each token is classified by its JWS `typ` header:
+
+| `typ` header           | kid DID == payload DID? | Classification           |
+| ---------------------- | ----------------------- | ------------------------ |
+| `did:dfos:identity-op` | —                       | Identity chain operation |
+| `did:dfos:content-op`  | yes                     | Content chain operation  |
+| `did:dfos:content-op`  | no                      | Countersignature         |
+| `did:dfos:beacon`      | yes                     | Beacon announcement      |
+| `did:dfos:beacon`      | no                      | Beacon countersignature  |
+
+When the signing key's DID differs from the payload DID, the operation is classified as a countersignature (witness attestation) rather than a primary operation.
+
+### Dependency Sort
+
+Within a batch, operations are sorted by dependency priority before processing:
+
+1. **Identity operations** — must be processed first so their keys are available
+2. **Beacons** — reference identity keys
+3. **Content operations** — reference identity keys for signature verification
+4. **Countersignatures** — reference both identity keys and existing operations
+
+Within each priority level, genesis operations (no `previousOperationCID`) are processed before extensions. This ensures that a single batch can bootstrap an entire identity-and-content lifecycle — including chained create + update operations — without multiple round trips.
+
+### Verification
+
+Each operation is verified against the relay's stored state:
+
+- **Identity operations**: The full chain (stored log + new operation) is re-verified from genesis. The relay uses `verifyIdentityChain()` from the protocol library
+- **Content operations**: The full chain is re-verified with `enforceAuthorization: true`. Non-creator signers must include a `DFOSContentWrite` VC-JWT
+- **Beacons**: Signature, CID integrity, and clock skew are verified. Replace-on-newer: only the most recent beacon per DID is retained
+- **Countersignatures**: The referenced operation or beacon must already exist. Signature is verified against the witness DID's identity chain
+- **Beacon countersignatures**: The referenced beacon must exist and the countersignature CID must match the current beacon CID
+
+### Fork Policy
+
+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).
+
+### 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]`.
+
+---
+
+## Relay Identity
+
+Every relay has a DID, published at `GET /.well-known/dfos-relay`. The relay DID serves as:
+
+- **Auth token audience**: Auth tokens are scoped to a specific relay via the JWT `aud` claim, preventing cross-relay token replay
+- **Peer identity**: When relays gossip proof plane data to each other, the relay DID identifies the peer
+
+The relay does not currently sign operations or participate in the protocol as an identity. It's a passive verifier and store.
+
+---
+
+## Content Plane Access
+
+### Blob Upload (`PUT /content/:contentId/blob`)
+
+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)
+
+Blobs are stored by `(creatorDID, documentCID)` — if multiple content chains by the same creator reference the same document, the blob is shared (deduplication).
+
+### Blob Download (`GET /content/:contentId/blob[/:ref]`)
+
+Requirements:
+
+- Valid auth token (Bearer header)
+- If the caller is the chain creator: no further credentials needed
+- If the caller is not the creator: must present a `DFOSContentRead` VC-JWT in the `X-Credential` header, issued by the creator to the caller
+
+The optional `:ref` parameter selects which operation's document to return:
+
+- `head` (default): the current document at chain head
+- An operation CID: the document committed by that specific operation
+
+---
+
+## Key Resolution
+
+The relay uses two key resolution strategies:
+
+- **Historical resolver** (for chain re-verification): searches all keys that have ever appeared in an identity chain's log, including rotated-out keys. This is necessary because re-verifying a full content chain from genesis must resolve keys from operations signed before a key rotation.
+- **Current-state resolver** (for live authentication): only resolves keys in the identity's current state. After a key rotation, the old key immediately stops working for auth tokens and credentials. This prevents a compromised rotated-out key from being used to authenticate new requests.
+
+---
+
+## Storage Interface
+
+The relay delegates persistence to a `RelayStore` interface. Implementations handle how data is stored — the relay handles what to store and when.
+
+```typescript
+interface RelayStore {
+  getOperation(cid: string): Promise<StoredOperation | undefined>;
+  putOperation(op: StoredOperation): Promise<void>;
+
+  getIdentityChain(did: string): Promise<StoredIdentityChain | undefined>;
+  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[]>;
+  addCountersignature(operationCID: string, jwsToken: string): Promise<void>;
+}
+```
+
+The package includes `MemoryRelayStore` for development and testing. Production deployments would implement the interface over Postgres, SQLite, S3, or any durable store.
+
+---
+
+## Quick Start
+
+```typescript
+import { createRelay, MemoryRelayStore } from '@metalabel/dfos-web-relay';
+
+const relay = createRelay({
+  relayDID: 'did:dfos:myrelay00000000000000',
+  store: new MemoryRelayStore(),
+});
+
+// Mount on any Hono-compatible runtime
+export default relay;
+```
+
+The returned Hono app exposes:
+
+| Method | Path                                 | Plane   | Auth                    |
+| ------ | ------------------------------------ | ------- | ----------------------- |
+| `GET`  | `/.well-known/dfos-relay`            | meta    | none                    |
+| `POST` | `/operations`                        | proof   | none                    |
+| `GET`  | `/operations/:cid`                   | proof   | none                    |
+| `GET`  | `/operations/:cid/countersignatures` | proof   | none                    |
+| `GET`  | `/countersignatures/:cid`            | proof   | none                    |
+| `GET`  | `/identities/:did`                   | proof   | none                    |
+| `GET`  | `/content/:contentId`                | proof   | none                    |
+| `GET`  | `/beacons/:did`                      | proof   | none                    |
+| `PUT`  | `/content/:contentId/blob`           | content | auth token              |
+| `GET`  | `/content/:contentId/blob[/:ref]`    | content | auth token + credential |
+
+---
+
+## What's Deferred
+
+- **Peer gossip**: Proactive push of proof plane operations to other relays
+- **Rate limiting / anti-spam**: Operational concern, not protocol concern
+- **Docker/CF reference deployments**: Focus on the core library first
+- **Pagination**: Chain logs are returned in full — fine for v1, needs pagination at scale
+- **Blob size limits**: No enforcement yet — production deployments should add limits at the middleware layer

package/dist/index.d.ts

@@ -0,0 +1,143 @@
+import { Hono } from 'hono';
+import { VerifiedIdentity, VerifiedContentChain, VerifiedBeacon } from '@metalabel/dfos-protocol/chain';
+
+interface RelayOptions {
+    /** The relay's DID — used as auth token audience and published in well-known */
+    relayDID: string;
+    /** Storage backend */
+    store: RelayStore;
+}
+interface StoredIdentityChain {
+    did: string;
+    /** Ordered JWS tokens from genesis to head */
+    log: string[];
+    state: VerifiedIdentity;
+}
+interface StoredContentChain {
+    contentId: string;
+    genesisCID: string;
+    /** Ordered JWS tokens from genesis to head */
+    log: 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';
+    /** The chain identifier — DID for identity, contentId for content */
+    chainId: string;
+}
+/** Key for blob storage — deduplicates across chains sharing the same document */
+interface BlobKey {
+    creatorDID: string;
+    documentCID: string;
+}
+/**
+ * Storage backend for a DFOS web relay
+ *
+ * Implementations handle persistence (memory, SQLite, Postgres, S3, etc.).
+ * The relay core handles verification — the store just reads and writes.
+ *
+ * Concurrency contract: the in-memory store is safe under single-threaded JS.
+ * Durable implementations must enforce optimistic concurrency (compare-and-swap
+ * on chain head CID) or pessimistic locking to prevent concurrent extensions
+ * from silently overwriting each other.
+ */
+interface RelayStore {
+    getOperation(cid: string): Promise<StoredOperation | undefined>;
+    putOperation(op: StoredOperation): Promise<void>;
+    getIdentityChain(did: string): Promise<StoredIdentityChain | undefined>;
+    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[]>;
+    addCountersignature(operationCID: string, jwsToken: string): Promise<void>;
+}
+interface IngestionResult {
+    cid: string;
+    status: 'accepted' | 'rejected';
+    error?: string;
+    /** What was ingested */
+    kind?: 'identity-op' | 'content-op' | 'beacon' | 'countersig' | 'beacon-countersig';
+    /** Chain identifier if applicable */
+    chainId?: string;
+}
+
+/**
+ * Create a DFOS web relay Hono application
+ *
+ * The returned app is portable — mount it on any Hono-compatible runtime
+ * (Node.js, Cloudflare Workers, Deno, Bun, etc.).
+ */
+declare const createRelay: (options: RelayOptions) => Hono;
+
+/**
+ * In-memory relay store — all data lives in Maps, lost on restart
+ *
+ * Suitable for development, testing, and short-lived relay instances.
+ */
+declare class MemoryRelayStore implements RelayStore {
+    private operations;
+    private identityChains;
+    private contentChains;
+    private beacons;
+    private blobs;
+    private countersignatures;
+    getOperation(cid: string): Promise<StoredOperation | undefined>;
+    putOperation(op: StoredOperation): Promise<void>;
+    getIdentityChain(did: string): Promise<StoredIdentityChain | undefined>;
+    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[]>;
+    addCountersignature(operationCID: string, jwsToken: string): Promise<void>;
+}
+
+/**
+ * Create a key resolver that looks up Ed25519 public keys from identity chains
+ * in the store. Used for chain re-verification during ingestion.
+ *
+ * Searches all keys that have ever appeared in the identity chain log, not just
+ * current state. This is necessary because re-verifying a full content chain log
+ * needs to resolve keys from operations signed before a key rotation.
+ *
+ * CID fidelity invariant: countersignature ingestion derives the operation CID
+ * by re-encoding the decoded payload via dagCborCanonicalEncode. This relies on
+ * the JWS decode round-trip preserving payload fidelity through JSON→CBOR→JSON→CBOR.
+ * The protocol library's canonical encoding (dag-cbor + sha-256) guarantees
+ * deterministic CIDs for identical payloads.
+ */
+declare const createKeyResolver: (store: RelayStore) => (kid: string) => Promise<Uint8Array>;
+/**
+ * Create a key resolver that only resolves current-state keys.
+ *
+ * Used for live authentication (auth tokens, credentials) where rotated-out
+ * keys must NOT be accepted. After a key rotation, the old key should no
+ * longer authenticate new requests.
+ */
+declare const createCurrentKeyResolver: (store: RelayStore) => (kid: string) => Promise<Uint8Array>;
+/**
+ * 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.
+ * Within each kind, genesis operations are processed before extensions.
+ */
+declare const ingestOperations: (tokens: string[], store: RelayStore) => Promise<IngestionResult[]>;
+
+export { type BlobKey, type IngestionResult, MemoryRelayStore, type RelayOptions, type RelayStore, type StoredBeacon, type StoredContentChain, type StoredIdentityChain, type StoredOperation, createCurrentKeyResolver, createKeyResolver, createRelay, ingestOperations };