@metalabel/dfos-web-relay 0.5.0 → 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

@@ -14,6 +14,55 @@ interface RelayOptions {
     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;
@@ -94,10 +143,35 @@ interface RelayStore {
         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?: OperationKind;
@@ -115,6 +189,23 @@ interface IngestionResult {
  */
 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
  *
@@ -124,7 +215,7 @@ declare const bootstrapRelayIdentity: (store: RelayStore) => Promise<RelayIdenti
  * 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) => Promise<Hono>;
+declare const createRelay: (options: RelayOptions) => Promise<CreatedRelay>;
 
 /**
  * In-memory relay store — all data lives in Maps, lost on restart
@@ -139,6 +230,7 @@ declare class MemoryRelayStore implements RelayStore {
     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>;
@@ -159,6 +251,16 @@ declare class MemoryRelayStore implements RelayStore {
         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>;
 }
 
 /**
@@ -191,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, type LogEntry, MemoryRelayStore, type OperationKind, type RelayIdentity, type RelayOptions, type RelayStore, type StoredBeacon, type StoredContentChain, type StoredIdentityChain, type StoredOperation, bootstrapRelayIdentity, 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 };