@metalabel/dfos-web-relay 0.5.0 → 0.6.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 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,53 @@ 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>;
+    /** Store a raw JWS token by CID — idempotent, ignores duplicates */
+    putRawOp(cid: string, jwsToken: string): Promise<void>;
+    /** Return JWS tokens for unsequenced (pending) ops */
+    getUnsequencedOps(limit: number): Promise<string[]>;
+    /** Mark ops as successfully sequenced */
+    markOpsSequenced(cids: string[]): Promise<void>;
+    /** Mark an op as permanently rejected */
+    markOpRejected(cid: string, reason: string): Promise<void>;
+    /** Count of pending (unsequenced) raw ops */
+    countUnsequenced(): Promise<number>;
+    /** Reset all non-rejected raw ops to pending (re-sequence) */
+    resetSequencer(): Promise<void>;
+}
+/** Result of a sequencer run */
+interface SequenceResult {
+    sequenced: number;
+    rejected: number;
+    pending: number;
 }
 interface IngestionResult {
     cid: string;
-    status: 'accepted' | 'rejected';
+    status: 'new' | 'duplicate' | 'rejected';
     error?: string;
     /** What was ingested */
     kind?: OperationKind;
@@ -115,6 +207,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 +233,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 +248,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 +269,23 @@ 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>;
+    private rawOps;
+    putRawOp(cid: string, jwsToken: string): Promise<void>;
+    getUnsequencedOps(limit: number): Promise<string[]>;
+    markOpsSequenced(cids: string[]): Promise<void>;
+    markOpRejected(cid: string, _reason: string): Promise<void>;
+    countUnsequenced(): Promise<number>;
+    resetSequencer(): Promise<void>;
 }
 
 /**
@@ -191,6 +318,25 @@ 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[]>;
+
+/**
+ * Returns true if the rejection is due to a missing dependency that may
+ * arrive later via sync or gossip. Only these specific patterns are
+ * retryable — everything else is treated as permanent.
+ */
+declare const isDependencyFailure: (error: string) => boolean;
+/** Derive the operation CID from a JWS token */
+declare const computeOpCID: (jwsToken: string) => Promise<string | undefined>;
+/**
+ * Process unsequenced raw ops in a fixed-point loop until no more progress
+ * is made. Returns the JWS tokens of newly sequenced ops and aggregate stats.
+ */
+declare const sequenceOps: (store: RelayStore) => Promise<{
+    newOps: string[];
+    result: SequenceResult;
+}>;
 
-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 SequenceResult, type StoredBeacon, type StoredContentChain, type StoredIdentityChain, type StoredOperation, bootstrapRelayIdentity, computeOpCID, createCurrentKeyResolver, createHttpPeerClient, createKeyResolver, createRelay, ingestOperations, isDependencyFailure, sequenceOps };