@metalabel/dfos-web-relay 0.4.1 → 0.6.0

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 relay specification.
+See [WEB-RELAY.md](../../specs/WEB-RELAY.md) for the full relay specification.
 
 ## Install
 
@@ -17,13 +17,15 @@ npm install @metalabel/dfos-web-relay @metalabel/dfos-protocol
 ```typescript
 import { createRelay, MemoryRelayStore } from '@metalabel/dfos-web-relay';
 
-const relay = createRelay({
-  relayDID: 'did:dfos:myrelay00000000000000',
+const relay = await createRelay({
   store: new MemoryRelayStore(),
 });
 
-// Mount on any Hono-compatible runtime
-export default relay;
+// relay.app  — Hono application
+// relay.did  — the relay's auto-generated DID
+// relay.syncFromPeers() — pull operations from configured peers
+
+export default relay.app;
 ```
 
 ### Standalone (Node.js)
@@ -68,11 +70,11 @@ RELAY_URL=http://localhost:4444 go test -v -count=1 ./conformance/
 RELAY_URL=https://registry.imajin.ai/relay go test -v -count=1 ./conformance/
 ```
 
-71 tests covering:
+77 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 lifecycle (create, update, delete, fork acceptance, DAG logs, deterministic head selection, 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)
@@ -84,9 +86,30 @@ RELAY_URL=https://registry.imajin.ai/relay go test -v -count=1 ./conformance/
 - 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)
+- Future timestamp guard (reject identity/content ops >24h ahead)
 
 The conformance suite depends on [`dfos-protocol-go`](../dfos-protocol-go) for protocol operations.
 
+## Peering
+
+Relays can replicate operations via three composable behaviors configured per-peer:
+
+- **Gossip-out**: push new operations to peers (fire-and-forget)
+- **Read-through**: fetch from peers on local 404
+- **Sync-in**: cursor-based log polling from peers
+
+```typescript
+import { createHttpPeerClient, createRelay, MemoryRelayStore } from '@metalabel/dfos-web-relay';
+
+const relay = await createRelay({
+  store: new MemoryRelayStore(),
+  peerClient: createHttpPeerClient(),
+  peers: [{ url: 'https://other-relay.example.com' }],
+});
+```
+
+See [WEB-RELAY.md](../../specs/WEB-RELAY.md) for the full peering specification.
+
 ## Custom Store
 
 Implement the `RelayStore` interface to use any persistence backend:

package/dist/index.d.ts

@@ -1,16 +1,77 @@
-import { Hono } from 'hono';
 import { VerifiedIdentity, VerifiedContentChain, VerifiedBeacon } from '@metalabel/dfos-protocol/chain';
+import { Hono } from 'hono';
 
+interface RelayIdentity {
+    /** The relay's DID */
+    did: string;
+    /** Profile artifact JWS token (signed by the relay DID) */
+    profileArtifactJws: string;
+}
 interface RelayOptions {
-    /** The relay's DID — used as auth token audience and published in well-known */
-    relayDID: string;
     /** Storage backend */
     store: RelayStore;
+    /** Pre-created relay identity — if omitted, a JIT identity and profile are generated */
+    identity?: RelayIdentity;
+    /** Whether content plane routes are enabled (default: true) */
+    content?: boolean;
+    /** Whether the global operation log is enabled (default: true) */
+    log?: boolean;
+    /** Peer relay configurations */
+    peers?: PeerConfig[];
+    /** Injected peer client — if omitted, a default HTTP implementation is used */
+    peerClient?: PeerClient;
+}
+interface PeerConfig {
+    url: string;
+    /** Push new ops to this peer (default: true) */
+    gossip?: boolean;
+    /** Fetch from this peer on local 404 (default: true) */
+    readThrough?: boolean;
+    /** Poll this peer's /log for background sync (default: true) */
+    sync?: boolean;
+}
+/** A log entry returned by a peer — CID and JWS token */
+interface PeerLogEntry {
+    cid: string;
+    jwsToken: string;
+}
+/** Injected peer transport — the relay expresses intent, the caller decides transport */
+interface PeerClient {
+    /** Fetch identity chain log from a peer */
+    getIdentityLog(peerUrl: string, did: string, params?: {
+        after?: string;
+        limit?: number;
+    }): Promise<{
+        entries: PeerLogEntry[];
+        cursor: string | null;
+    } | null>;
+    /** Fetch content chain log from a peer */
+    getContentLog(peerUrl: string, contentId: string, params?: {
+        after?: string;
+        limit?: number;
+    }): Promise<{
+        entries: PeerLogEntry[];
+        cursor: string | null;
+    } | null>;
+    /** Fetch global operation log from a peer */
+    getOperationLog(peerUrl: string, params?: {
+        after?: string;
+        limit?: number;
+    }): Promise<{
+        entries: PeerLogEntry[];
+        cursor: string | null;
+    } | null>;
+    /** Push operations to a peer (fire-and-forget) */
+    submitOperations(peerUrl: string, operations: string[]): Promise<void>;
 }
 interface StoredIdentityChain {
     did: string;
     /** Ordered JWS tokens from genesis to head */
     log: string[];
+    /** CID of the most recent operation */
+    headCID: string;
+    /** createdAt timestamp of the most recent operation */
+    lastCreatedAt: string;
     state: VerifiedIdentity;
 }
 interface StoredContentChain {
@@ -18,6 +79,8 @@ interface StoredContentChain {
     genesisCID: string;
     /** Ordered JWS tokens from genesis to head */
     log: string[];
+    /** createdAt timestamp of the most recent operation */
+    lastCreatedAt: string;
     state: VerifiedContentChain;
 }
 interface StoredBeacon {
@@ -30,8 +93,8 @@ 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 */
+    chainType: 'identity' | 'content' | 'artifact' | 'beacon' | 'countersign';
+    /** The chain identifier — DID for identity/beacon/artifact, contentId for content, targetCID for countersign */
     chainId: string;
 }
 /** Key for blob storage — deduplicates across chains sharing the same document */
@@ -39,6 +102,15 @@ interface BlobKey {
     creatorDID: string;
     documentCID: string;
 }
+/** A single entry in the global append-only operation log */
+interface LogEntry {
+    cid: string;
+    jwsToken: string;
+    kind: OperationKind;
+    chainId: string;
+}
+/** All operation kinds in the protocol */
+type OperationKind = 'identity-op' | 'content-op' | 'beacon' | 'artifact' | 'countersign';
 /**
  * Storage backend for a DFOS web relay
  *
@@ -63,24 +135,87 @@ interface RelayStore {
     putBlob(key: BlobKey, data: Uint8Array): Promise<void>;
     getCountersignatures(operationCID: string): Promise<string[]>;
     addCountersignature(operationCID: string, jwsToken: string): Promise<void>;
+    appendToLog(entry: LogEntry): Promise<void>;
+    readLog(params: {
+        after?: string;
+        limit: number;
+    }): Promise<{
+        entries: LogEntry[];
+        cursor: string | null;
+    }>;
+    /**
+     * Get the materialized identity state at a specific operation CID.
+     *
+     * Used by fork verification — the ingestion pipeline needs state at the fork
+     * point to verify signer authority and createdAt ordering.
+     *
+     * Implementations decide how to compute this:
+     * - MemoryStore: replay from genesis (chains are short in tests)
+     * - SQLiteStore: check snapshot table, replay from nearest snapshot
+     *
+     * Returns null if the CID is not in this chain's log.
+     */
+    getIdentityStateAtCID(did: string, cid: string): Promise<{
+        state: VerifiedIdentity;
+        lastCreatedAt: string;
+    } | null>;
+    /** Same for content chains */
+    getContentStateAtCID(contentId: string, cid: string): Promise<{
+        state: VerifiedContentChain;
+        lastCreatedAt: string;
+    } | null>;
+    /** Get last-synced log cursor for a peer relay */
+    getPeerCursor(peerUrl: string): Promise<string | undefined>;
+    /** Update last-synced log cursor for a peer relay */
+    setPeerCursor(peerUrl: string, cursor: string): Promise<void>;
 }
 interface IngestionResult {
     cid: string;
-    status: 'accepted' | 'rejected';
+    status: 'new' | 'duplicate' | 'rejected';
     error?: string;
     /** What was ingested */
-    kind?: 'identity-op' | 'content-op' | 'beacon' | 'countersig' | 'beacon-countersig';
+    kind?: OperationKind;
     /** Chain identifier if applicable */
     chainId?: string;
 }
 
+/**
+ * Generate a relay identity and profile artifact, ingest both into the store
+ *
+ * Creates an Ed25519 keypair, signs an identity genesis operation, derives
+ * the DID, then signs a profile artifact with the relay's name. Both the
+ * identity genesis and profile artifact are ingested into the store so
+ * they are available via the relay's proof plane routes.
+ */
+declare const bootstrapRelayIdentity: (store: RelayStore) => Promise<RelayIdentity>;
+
+/**
+ * Create an HTTP-based PeerClient.
+ *
+ * Each method makes a single HTTP request to the peer relay URL. On any
+ * failure (network error, non-2xx response, invalid JSON), returns null
+ * for read operations or silently fails for write operations.
+ */
+declare const createHttpPeerClient: () => PeerClient;
+
+interface CreatedRelay {
+    /** Hono application implementing the DFOS web relay HTTP API */
+    app: Hono;
+    /** The relay's DID */
+    did: string;
+    /** Sync operations from all configured sync peers (call on a schedule) */
+    syncFromPeers: () => Promise<void>;
+}
 /**
  * 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.).
+ *
+ * When `identity` is provided, the relay uses the given DID and profile. When
+ * omitted, a JIT identity and profile artifact are generated at startup.
  */
-declare const createRelay: (options: RelayOptions) => Hono;
+declare const createRelay: (options: RelayOptions) => Promise<CreatedRelay>;
 
 /**
  * In-memory relay store — all data lives in Maps, lost on restart
@@ -94,6 +229,8 @@ declare class MemoryRelayStore implements RelayStore {
     private beacons;
     private blobs;
     private countersignatures;
+    private operationLog;
+    private peerCursors;
     getOperation(cid: string): Promise<StoredOperation | undefined>;
     putOperation(op: StoredOperation): Promise<void>;
     getIdentityChain(did: string): Promise<StoredIdentityChain | undefined>;
@@ -106,6 +243,24 @@ declare class MemoryRelayStore implements RelayStore {
     putBlob(key: BlobKey, data: Uint8Array): Promise<void>;
     getCountersignatures(operationCID: string): Promise<string[]>;
     addCountersignature(operationCID: string, jwsToken: string): Promise<void>;
+    appendToLog(entry: LogEntry): Promise<void>;
+    readLog(params: {
+        after?: string;
+        limit: number;
+    }): Promise<{
+        entries: LogEntry[];
+        cursor: string | null;
+    }>;
+    getIdentityStateAtCID(did: string, cid: string): Promise<{
+        state: VerifiedIdentity;
+        lastCreatedAt: string;
+    } | null>;
+    getContentStateAtCID(contentId: string, cid: string): Promise<{
+        state: VerifiedContentChain;
+        lastCreatedAt: string;
+    } | null>;
+    getPeerCursor(peerUrl: string): Promise<string | undefined>;
+    setPeerCursor(peerUrl: string, cursor: string): Promise<void>;
 }
 
 /**
@@ -138,6 +293,8 @@ declare const createCurrentKeyResolver: (store: RelayStore) => (kid: string) =>
  * 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[]>;
+declare const ingestOperations: (tokens: string[], store: RelayStore, options?: {
+    logEnabled?: boolean;
+}) => Promise<IngestionResult[]>;
 
-export { type BlobKey, type IngestionResult, MemoryRelayStore, type RelayOptions, type RelayStore, type StoredBeacon, type StoredContentChain, type StoredIdentityChain, type StoredOperation, createCurrentKeyResolver, createKeyResolver, createRelay, ingestOperations };
+export { type BlobKey, type CreatedRelay, type IngestionResult, type LogEntry, MemoryRelayStore, type OperationKind, type PeerClient, type PeerConfig, type PeerLogEntry, type RelayIdentity, type RelayOptions, type RelayStore, type StoredBeacon, type StoredContentChain, type StoredIdentityChain, type StoredOperation, bootstrapRelayIdentity, createCurrentKeyResolver, createHttpPeerClient, createKeyResolver, createRelay, ingestOperations };