@metalabel/dfos-web-relay 0.9.0 → 0.11.0

package/README.md

@@ -38,19 +38,18 @@ 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 (standing auth, or auth + credential)      |
-| `GET`  | `/content/:contentId/blob/:ref`          | Download blob at specific operation ref                          |
+| Method | Path                                     | Description                                                 |
+| ------ | ---------------------------------------- | ----------------------------------------------------------- |
+| `GET`  | `/.well-known/dfos-relay`                | Relay metadata (DID, protocol version)                      |
+| `POST` | `/operations`                            | Submit signed operations (identity, content, 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`  | `/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 (standing auth, or auth + credential) |
+| `GET`  | `/content/:contentId/blob/:ref`          | Download blob at specific operation ref                     |
 
 ## Blob Authorization
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { VerifiedIdentity, VerifiedContentChain, VerifiedBeacon } from '@metalabel/dfos-protocol/chain';
+import { VerifiedIdentity, VerifiedContentChain } from '@metalabel/dfos-protocol/chain';
 import { Attenuation } from '@metalabel/dfos-protocol/credentials';
 import { Hono } from 'hono';
 
@@ -21,6 +21,12 @@ interface RelayOptions {
     peers?: PeerConfig[];
     /** Injected peer client — if omitted, a default HTTP implementation is used */
     peerClient?: PeerClient;
+    /**
+     * Max lifetime (exp-iat, seconds) honored on a self-signed auth token.
+     * Default 86400 (24h); a value <= 0 disables the ceiling. Applies only to auth
+     * tokens, never to DFOS credentials.
+     */
+    maxAuthTokenTTLSeconds?: number;
 }
 interface PeerConfig {
     url: string;
@@ -84,18 +90,12 @@ interface StoredContentChain {
     lastCreatedAt: 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' | 'artifact' | 'beacon' | 'countersign' | 'revocation' | 'credential';
-    /** The chain identifier — DID for identity/beacon/artifact, contentId for content, targetCID for countersign */
+    chainType: 'identity' | 'content' | 'artifact' | 'countersign' | 'revocation' | 'credential';
+    /** The chain identifier — DID for identity/artifact, contentId for content, targetCID for countersign */
     chainId: string;
 }
 /** Key for blob storage — deduplicates across chains sharing the same document */
@@ -111,7 +111,7 @@ interface LogEntry {
     chainId: string;
 }
 /** All operation kinds in the protocol */
-type OperationKind = 'identity-op' | 'content-op' | 'beacon' | 'artifact' | 'countersign' | 'revocation' | 'credential';
+type OperationKind = 'identity-op' | 'content-op' | 'artifact' | 'countersign' | 'revocation' | 'credential';
 interface StoredRevocation {
     cid: string;
     issuerDID: string;
@@ -150,8 +150,6 @@ interface RelayStore {
     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[]>;
@@ -236,6 +234,14 @@ interface IngestionResult {
     kind?: OperationKind;
     /** Chain identifier if applicable */
     chainId?: string;
+    /**
+     * Structured dependency-failure signal. When true, the rejection is due to a
+     * missing dependency that may arrive later via sync or gossip, so the
+     * sequencer must keep the op pending (retryable) rather than durably reject
+     * it. This is the discriminator the sequencer branches on — NOT substring
+     * matching of the human-readable `error` string.
+     */
+    dependencyMissing?: boolean;
 }
 
 /**
@@ -247,6 +253,20 @@ interface IngestionResult {
  * they are available via the relay's proof plane routes.
  */
 declare const bootstrapRelayIdentity: (store: RelayStore) => Promise<RelayIdentity>;
+/**
+ * Bootstrap a relay identity from an EXISTING key + key ID, with optional pinned
+ * timestamps and profile name. Used for deterministic bootstrap — e.g. the
+ * dual-relay parity harness pins one key + one createdAt across both twins so
+ * the relay's own genesis + profile log entries are byte-identical, and durable
+ * relays that reload their key from storage. Mirrors the Go twin's
+ * BootstrapRelayIdentityFromKey.
+ */
+declare const bootstrapRelayIdentityFromKey: (store: RelayStore, params: {
+    privateKey: Uint8Array;
+    keyId: string;
+    name?: string;
+    createdAt?: string;
+}) => Promise<RelayIdentity>;
 
 /**
  * Create an HTTP-based PeerClient.
@@ -265,6 +285,13 @@ interface CreatedRelay {
     /** Sync operations from all configured sync peers (call on a schedule) */
     syncFromPeers: () => Promise<void>;
 }
+/**
+ * Split items into batches of at most `size`, preserving order with no loss.
+ * gossip() uses this to stay within the receiver's per-batch cap; exported so
+ * the split behavior is directly testable (mirrors Go's maxGossipBatch chunking,
+ * whose TestGossipChunksLargeBatches drives the split directly).
+ */
+declare const chunkOps: <T>(items: T[], size: number) => T[][];
 /**
  * Create a DFOS web relay Hono application
  *
@@ -285,7 +312,6 @@ declare class MemoryRelayStore implements RelayStore {
     private operations;
     private identityChains;
     private contentChains;
-    private beacons;
     private blobs;
     private countersignatures;
     private operationLog;
@@ -300,8 +326,6 @@ declare class MemoryRelayStore implements RelayStore {
     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[]>;
@@ -346,6 +370,13 @@ declare class MemoryRelayStore implements RelayStore {
     resetSequencer(): Promise<void>;
 }
 
+/**
+ * Derive the operation CID from a JWS token by re-encoding the decoded payload.
+ * Returns the empty string for an undecodable token. Used at verify-failure
+ * sites so a rejection still carries a CID and can be durably rejected by the
+ * sequencer (instead of being skipped forever by `if (!res.cid) continue`).
+ */
+declare const computeOpCID: (jwsToken: string) => Promise<string>;
 /**
  * Create a key resolver that looks up Ed25519 public keys from identity chains
  * in the store. Used for chain re-verification during ingestion.
@@ -390,6 +421,11 @@ declare const createHistoricalIdentityResolver: (store: RelayStore) => (did: str
     }[];
     did: string;
     isDeleted: boolean;
+    services: {
+        [x: string]: unknown;
+        id: string;
+        type: string;
+    }[];
 } | undefined>;
 /**
  * Create a key resolver that only resolves current-state keys.
@@ -403,7 +439,7 @@ declare const createCurrentKeyResolver: (store: RelayStore) => (kid: string) =>
  * 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.
+ * are processed first so content chains can resolve their keys.
  * Within each kind, genesis operations are processed before extensions.
  */
 declare const ingestOperations: (tokens: string[], store: RelayStore, options?: {
@@ -411,13 +447,13 @@ declare const ingestOperations: (tokens: string[], store: RelayStore, options?:
 }) => 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.
+ * Returns true if a rejection is retryable (a missing dependency that may
+ * arrive later via sync or gossip). The sequencer branches on the STRUCTURED
+ * `dependencyMissing` flag set by the ingest producer — not on substring
+ * matching of the human-readable `error` string. Mirrors the Go twin's
+ * structured discriminator.
  */
-declare const isDependencyFailure: (error: string) => boolean;
-/** Derive the operation CID from a JWS token */
-declare const computeOpCID: (jwsToken: string) => Promise<string | undefined>;
+declare const isDependencyFailure: (res: Pick<IngestionResult, "dependencyMissing">) => boolean;
 /**
  * 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.
@@ -427,4 +463,4 @@ declare const sequenceOps: (store: RelayStore) => Promise<{
     result: SequenceResult;
 }>;
 
-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, createHistoricalIdentityResolver, createHttpPeerClient, createKeyResolver, createRelay, ingestOperations, isDependencyFailure, sequenceOps };
+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 StoredContentChain, type StoredIdentityChain, type StoredOperation, bootstrapRelayIdentity, bootstrapRelayIdentityFromKey, chunkOps, computeOpCID, createCurrentKeyResolver, createHistoricalIdentityResolver, createHttpPeerClient, createKeyResolver, createRelay, ingestOperations, isDependencyFailure, sequenceOps };