@serfab/cadre-core 1.9.0 → 1.11.0

package/src/strand-formation-rejection.ts

@@ -0,0 +1,129 @@
+/**
+ * How a formation dial fails, as types a joining device can branch on without reading the
+ * human-facing wording: a responder's refusal carries a fixed {@link FormationRejectionCode}
+ * on the wire and surfaces as a {@link FormationRejectedError}; a dial that never got an
+ * answer surfaces as a {@link FormationUnreachableError}.
+ */
+
+/**
+ * Why a formation responder refused a join. Sent beside the free-text `reason` on every
+ * `approved: false` result frame (`FormationResultMessage.code`).
+ */
+export type FormationRejectionCode =
+  /**
+   * No invitation row for this token on THIS responder. Retryable: a sibling machine of the
+   * inviter may not have received the row yet. Leaks nothing — only a holder of the token can
+   * ask, and an unknown token means the same as one never minted.
+   */
+  | 'token-unknown'
+  /**
+   * The invitation expired, or every allowed use is recorded. The loser of a redemption race
+   * and a latecomer both get this code, so neither can tell the two apart.
+   */
+  | 'token-spent'
+  /** The joiner's consent signature does not verify (or `partyId` does not embed `peerKey`). */
+  | 'consent-invalid'
+  /** The responder's disclosure validator refused the disclosure. */
+  | 'disclosure-invalid'
+  | 'disclosure-too-large'
+  /** The invitation's outside approval hook answered no. */
+  | 'approval-refused'
+  /** The invitation's outside approval hook could not be reached or did not answer in time. */
+  | 'approval-unavailable'
+  /** The inviter's approval setup is wrong: a malformed answer, an unenrolled key, or a misconfigured hook. */
+  | 'approval-invalid'
+  /**
+   * The host strand is not running (or not yet replicated) on this responder, or issuing the
+   * joiner's membership invitation into it failed.
+   */
+  | 'host-strand-unavailable'
+  /** The host strand predates the per-party identity split and can never admit a joiner. */
+  | 'host-strand-must-be-recreated'
+  /** The responder is at its cap on concurrent formation sessions. */
+  | 'busy'
+  /** Provisioning outran the responder's budget; the invitation is left unspent. */
+  | 'provisioning-timeout'
+  /** The consent write failed for a reason other than a spent invitation. */
+  | 'conflict'
+  /** An unexpected responder-side failure. */
+  | 'internal';
+
+/**
+ * Which rejections are worth retrying — the single place that says so. A retry repeats the
+ * same redemption later (or against another of the inviter's machines); a final code means
+ * no retry of this invitation can succeed.
+ */
+export const FORMATION_REJECTION_RETRYABLE: Readonly<Record<FormationRejectionCode, boolean>> = {
+  'token-unknown': true,
+  'token-spent': false,
+  'consent-invalid': false,
+  'disclosure-invalid': false,
+  'disclosure-too-large': false,
+  'approval-refused': false,
+  'approval-unavailable': true,
+  'approval-invalid': false,
+  'host-strand-unavailable': true,
+  'host-strand-must-be-recreated': false,
+  'busy': true,
+  'provisioning-timeout': true,
+  'conflict': true,
+  'internal': true
+};
+
+/** Is `value` a code this build knows? Own keys only, so a peer's `'constructor'` does not pass. */
+export function isFormationRejectionCode(value: unknown): value is FormationRejectionCode {
+  return typeof value === 'string' && Object.prototype.hasOwnProperty.call(FORMATION_REJECTION_RETRYABLE, value);
+}
+
+/**
+ * The responder answered and refused the join.
+ *
+ * `code` is `'unrecognized'` when the frame carried no code or one this build does not know
+ * — formation runs between two parties on different versions — and such a rejection counts
+ * as retryable: retrying an unknown answer until the invitation expires is safe, while giving
+ * up on one that would have succeeded is not.
+ */
+export class FormationRejectedError extends Error {
+  readonly code: FormationRejectionCode | 'unrecognized';
+  readonly reason: string;
+  readonly retryable: boolean;
+
+  /** Both arguments come straight off the wire, so neither is trusted to have its declared type. */
+  constructor(code: unknown, reason: unknown) {
+    const text = typeof reason === 'string' ? reason : 'no reason provided';
+    super(`Formation rejected: ${text}`);
+    this.name = 'FormationRejectedError';
+    this.code = isFormationRejectionCode(code) ? code : 'unrecognized';
+    this.reason = text;
+    this.retryable = this.code === 'unrecognized' || FORMATION_REJECTION_RETRYABLE[this.code];
+  }
+}
+
+/**
+ * The dial ended before a result frame was read: no responder address parsed, every address
+ * failed to dial, a deadline passed, or the stream closed early. Always retryable. Keeps the
+ * underlying failure's message, and the failure itself as `cause`.
+ */
+export class FormationUnreachableError extends Error {
+  readonly retryable = true;
+
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = 'FormationUnreachableError';
+  }
+}
+
+/**
+ * The responder approved the join, so the invitation's one-time token is spent, and then a
+ * step on the joining machine failed: persisting the party's membership identity, or
+ * remembering the join. Never retryable: the same invitation can only answer `token-spent`
+ * from now on, so recovery is fixing the local cause and redeeming a fresh invitation.
+ */
+export class FormationPostApprovalError extends Error {
+  readonly retryable = false;
+
+  constructor(readonly strandId: string, message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = 'FormationPostApprovalError';
+  }
+}

package/src/strand-fret-addrs.ts

@@ -1,145 +1,145 @@
-/**
- * Reading the signed address records a running strand node's FRET routing table holds,
- * as per-peer addresses ready for that node's own address book (`peer-addr-book.ts`).
- *
- * Why a strand node needs this. libp2p's peerStore hides every address one hour after
- * it was first observed (the `NOTE:` on `mergePeerAddrs`), and FRET does not re-apply
- * the records it holds: it hands a record to the peerStore when a neighbour's snapshot
- * delivers it or a saved table is imported, and the peerStore refuses a record whose
- * sequence number it already has. So a strand node that has been up for more than an
- * hour would have no address for a peer whose connection then drops, although FRET
- * still holds that peer's record. `CadreNode.refreshStrandPeerAddrs` re-merges the
- * records on every pass, which is what keeps another party's strand nodes dialable;
- * own-party siblings are re-resolved separately, over the strand-addr RPC.
- *
- * How long a record is available here is FRET's rule, not this module's: while FRET
- * holds the entry, and at most 14 days after the record was last confirmed (a peer
- * connected at export time counts as confirmed then).
- *
- * Every record is opened and verified here rather than taken on FRET's word. A record
- * is self-certifying, the table is reached through a structural type rather than an
- * interface this package depends on, and the address book write is attributed from what
- * the record proves, not from the id the table filed it under.
- */
-
-import debug from 'debug';
-import { PeerRecord, RecordEnvelope } from '@libp2p/peer-record';
-import { peerIdFromPublicKey } from '@libp2p/peer-id';
-import { multiaddr, type Multiaddr } from '@multiformats/multiaddr';
-import { fromString as uint8ArrayFromString } from 'uint8arrays';
-import { withTrailingPeerId } from './peer-record.js';
-
-const log = debug('sereus:cadre:strand-fret-addrs');
-
-/** The slice of FRET's exported routing table read here (`SerializedTable` in `p2p-fret`). */
-interface FretTableSlice {
-  entries: ReadonlyArray<{
-    id: string;
-    /** `envelope` is the base64url of a marshaled libp2p record envelope. */
-    addressRecord?: { envelope: string };
-  }>;
-}
-
-/** The slice of FRET's libp2p service called here. */
-interface FretTableSource {
-  exportTable(): FretTableSlice;
-}
-
-/**
- * The slice of a strand's libp2p node this module touches. Structurally satisfied by
- * `Libp2p`; db-p2p registers FRET as `services.fret`.
- */
-export interface FretAddrHost {
-  peerId: { toString(): string };
-  services?: Record<string, unknown>;
-}
-
-/** What one read of a strand node's FRET table yields. */
-export interface FretPeerAddrs {
-  /** Peer id → the addresses its record lists, each bound to that peer. Table order. */
-  peers: Map<string, Multiaddr[]>;
-  /**
-   * Records left out because they did not decode, did not verify, or were not signed
-   * by and about the peer the table filed them under.
-   */
-  rejected: number;
-}
-
-/**
- * The addresses of every peer `host`'s FRET table holds a usable signed record for,
- * `host` itself excluded. A node with no FRET service (a db-p2p build without it, a
- * test double) reads as an empty table. One bad record never costs the others: it is
- * counted in `rejected` and skipped.
- *
- * Throws only what `exportTable()` throws, which a caller treats like any other
- * failure of a pass over a node that may be mid-teardown.
- */
-export async function strandFretPeerAddrs(host: FretAddrHost): Promise<FretPeerAddrs> {
-  const result: FretPeerAddrs = { peers: new Map(), rejected: 0 };
-  const fret = host.services?.fret;
-  if (!isFretTableSource(fret)) {
-    return result;
-  }
-  const selfId = host.peerId.toString();
-  for (const entry of fret.exportTable().entries) {
-    if (entry.id === selfId || entry.addressRecord === undefined) {
-      continue;
-    }
-    const addrs = await verifiedRecordAddrs(entry.id, entry.addressRecord.envelope);
-    if (addrs === null) {
-      result.rejected++;
-    } else if (addrs.length > 0) {
-      result.peers.set(entry.id, addrs);
-    }
-  }
-  return result;
-}
-
-function isFretTableSource(service: unknown): service is FretTableSource {
-  return typeof service === 'object' && service !== null
-    && typeof (service as { exportTable?: unknown }).exportTable === 'function';
-}
-
-/**
- * The addresses one record lists, bound to `peerId`; null when the record must not be
- * used. `openAndCertify` proves only that the envelope's own key signed it, so the
- * signer and the peer the payload describes are each held against `peerId` here:
- * without that, any peer could sign a record rewriting another peer's addresses.
- */
-async function verifiedRecordAddrs(peerId: string, envelope: string): Promise<Multiaddr[] | null> {
-  try {
-    const opened = await RecordEnvelope.openAndCertify(uint8ArrayFromString(envelope, 'base64url'), PeerRecord.DOMAIN);
-    const record = PeerRecord.createFromProtobuf(opened.payload);
-    const signer = peerIdFromPublicKey(opened.publicKey).toString();
-    const subject = record.peerId.toString();
-    if (signer !== peerId || subject !== peerId) {
-      log('skipping the address record filed under %s: signed by %s about %s', peerId, signer, subject);
-      return null;
-    }
-    return bindToPeer(record.multiaddrs.map((addr) => addr.toString()), peerId);
-  } catch (error) {
-    log('skipping the address record filed under %s: %o', peerId, error);
-    return null;
-  }
-}
-
-/**
- * A record names its peer once, in `peerId`, so its addresses carry no trailing
- * `/p2p/<peerId>` and a relay-only peer's circuit address ends at the relay hop
- * (`…/p2p/<relay>/p2p-circuit`). Each is given the suffix that makes it a complete
- * dial target; one already terminating in a different peer id does not reach this peer
- * and is dropped.
- *
- * Takes strings because `@libp2p/peer-record` carries its own `@multiformats/multiaddr`
- * copy, a structurally different type from the one `withTrailingPeerId` takes.
- */
-function bindToPeer(addrs: string[], peerId: string): Multiaddr[] {
-  const bound: Multiaddr[] = [];
-  for (const addr of addrs) {
-    const withPeer = withTrailingPeerId(multiaddr(addr), peerId);
-    if (withPeer !== null) {
-      bound.push(withPeer);
-    }
-  }
-  return bound;
-}
+/**
+ * Reading the signed address records a running strand node's FRET routing table holds,
+ * as per-peer addresses ready for that node's own address book (`peer-addr-book.ts`).
+ *
+ * Why a strand node needs this. libp2p's peerStore hides every address one hour after
+ * it was first observed (the `NOTE:` on `mergePeerAddrs`), and FRET does not re-apply
+ * the records it holds: it hands a record to the peerStore when a neighbour's snapshot
+ * delivers it or a saved table is imported, and the peerStore refuses a record whose
+ * sequence number it already has. So a strand node that has been up for more than an
+ * hour would have no address for a peer whose connection then drops, although FRET
+ * still holds that peer's record. `CadreNode.refreshStrandPeerAddrs` re-merges the
+ * records on every pass, which is what keeps another party's strand nodes dialable;
+ * own-party siblings are re-resolved separately, over the strand-addr RPC.
+ *
+ * How long a record is available here is FRET's rule, not this module's: while FRET
+ * holds the entry, and at most 14 days after the record was last confirmed (a peer
+ * connected at export time counts as confirmed then).
+ *
+ * Every record is opened and verified here rather than taken on FRET's word. A record
+ * is self-certifying, the table is reached through a structural type rather than an
+ * interface this package depends on, and the address book write is attributed from what
+ * the record proves, not from the id the table filed it under.
+ */
+
+import debug from 'debug';
+import { PeerRecord, RecordEnvelope } from '@libp2p/peer-record';
+import { peerIdFromPublicKey } from '@libp2p/peer-id';
+import { multiaddr, type Multiaddr } from '@multiformats/multiaddr';
+import { fromString as uint8ArrayFromString } from 'uint8arrays';
+import { withTrailingPeerId } from './peer-record.js';
+
+const log = debug('sereus:cadre:strand-fret-addrs');
+
+/** The slice of FRET's exported routing table read here (`SerializedTable` in `p2p-fret`). */
+interface FretTableSlice {
+  entries: ReadonlyArray<{
+    id: string;
+    /** `envelope` is the base64url of a marshaled libp2p record envelope. */
+    addressRecord?: { envelope: string };
+  }>;
+}
+
+/** The slice of FRET's libp2p service called here. */
+interface FretTableSource {
+  exportTable(): FretTableSlice;
+}
+
+/**
+ * The slice of a strand's libp2p node this module touches. Structurally satisfied by
+ * `Libp2p`; db-p2p registers FRET as `services.fret`.
+ */
+export interface FretAddrHost {
+  peerId: { toString(): string };
+  services?: Record<string, unknown>;
+}
+
+/** What one read of a strand node's FRET table yields. */
+export interface FretPeerAddrs {
+  /** Peer id → the addresses its record lists, each bound to that peer. Table order. */
+  peers: Map<string, Multiaddr[]>;
+  /**
+   * Records left out because they did not decode, did not verify, or were not signed
+   * by and about the peer the table filed them under.
+   */
+  rejected: number;
+}
+
+/**
+ * The addresses of every peer `host`'s FRET table holds a usable signed record for,
+ * `host` itself excluded. A node with no FRET service (a db-p2p build without it, a
+ * test double) reads as an empty table. One bad record never costs the others: it is
+ * counted in `rejected` and skipped.
+ *
+ * Throws only what `exportTable()` throws, which a caller treats like any other
+ * failure of a pass over a node that may be mid-teardown.
+ */
+export async function strandFretPeerAddrs(host: FretAddrHost): Promise<FretPeerAddrs> {
+  const result: FretPeerAddrs = { peers: new Map(), rejected: 0 };
+  const fret = host.services?.fret;
+  if (!isFretTableSource(fret)) {
+    return result;
+  }
+  const selfId = host.peerId.toString();
+  for (const entry of fret.exportTable().entries) {
+    if (entry.id === selfId || entry.addressRecord === undefined) {
+      continue;
+    }
+    const addrs = await verifiedRecordAddrs(entry.id, entry.addressRecord.envelope);
+    if (addrs === null) {
+      result.rejected++;
+    } else if (addrs.length > 0) {
+      result.peers.set(entry.id, addrs);
+    }
+  }
+  return result;
+}
+
+function isFretTableSource(service: unknown): service is FretTableSource {
+  return typeof service === 'object' && service !== null
+    && typeof (service as { exportTable?: unknown }).exportTable === 'function';
+}
+
+/**
+ * The addresses one record lists, bound to `peerId`; null when the record must not be
+ * used. `openAndCertify` proves only that the envelope's own key signed it, so the
+ * signer and the peer the payload describes are each held against `peerId` here:
+ * without that, any peer could sign a record rewriting another peer's addresses.
+ */
+async function verifiedRecordAddrs(peerId: string, envelope: string): Promise<Multiaddr[] | null> {
+  try {
+    const opened = await RecordEnvelope.openAndCertify(uint8ArrayFromString(envelope, 'base64url'), PeerRecord.DOMAIN);
+    const record = PeerRecord.createFromProtobuf(opened.payload);
+    const signer = peerIdFromPublicKey(opened.publicKey).toString();
+    const subject = record.peerId.toString();
+    if (signer !== peerId || subject !== peerId) {
+      log('skipping the address record filed under %s: signed by %s about %s', peerId, signer, subject);
+      return null;
+    }
+    return bindToPeer(record.multiaddrs.map((addr) => addr.toString()), peerId);
+  } catch (error) {
+    log('skipping the address record filed under %s: %o', peerId, error);
+    return null;
+  }
+}
+
+/**
+ * A record names its peer once, in `peerId`, so its addresses carry no trailing
+ * `/p2p/<peerId>` and a relay-only peer's circuit address ends at the relay hop
+ * (`…/p2p/<relay>/p2p-circuit`). Each is given the suffix that makes it a complete
+ * dial target; one already terminating in a different peer id does not reach this peer
+ * and is dropped.
+ *
+ * Takes strings because `@libp2p/peer-record` carries its own `@multiformats/multiaddr`
+ * copy, a structurally different type from the one `withTrailingPeerId` takes.
+ */
+function bindToPeer(addrs: string[], peerId: string): Multiaddr[] {
+  const bound: Multiaddr[] = [];
+  for (const addr of addrs) {
+    const withPeer = withTrailingPeerId(multiaddr(addr), peerId);
+    if (withPeer !== null) {
+      bound.push(withPeer);
+    }
+  }
+  return bound;
+}