@serfab/cadre-core 1.9.0 → 1.10.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-instance-manager.ts

@@ -43,7 +43,7 @@ import { DEFAULT_CONNECTION_MONITOR, resolveStrandClusterSize, strandClusterPoli
 import { strandNodeAddrs } from './strand-network-config.js';
 import { resolveRelayServer } from './relay-server.js';
 import { superviseRelayReservation, type RelayReservationSupervisor } from './relay-reservation.js';
-import { declaredCohortReadDeadlineMs, peerJoinPushBudget, relayReservationBudgetMs, resolveLinkRoundTripMs } from './link-budget.js';
+import { declaredCohortReadDeadlineMs, optimysticDialLimits, peerJoinPushBudget, relayReservationBudgetMs, resolveLinkRoundTripMs } from './link-budget.js';
 
 const log = debug('sereus:cadre:strand-manager');
 const timing = debug('sereus:cadre:timing');
@@ -812,6 +812,9 @@ export class StrandInstanceManager {
         // node is also the listener for every other member's strand node, and Optimystic
         // derives that listener's limit from this (`link-budget.ts`).
         linkRoundTripMs: resolveLinkRoundTripMs(config.network?.linkRoundTripMs),
+        // The same dial limits as the control node: a strand node dials the same machines,
+        // through the same relays and gates.
+        ...optimysticDialLimits(config.network?.linkRoundTripMs),
         // Listen entries plus the WebSocket transport switch they imply — a strand node
         // announces nothing the operator configured (`strand-network-config.ts`), and
         // spreads AFTER `transports` above because the switch is a no-op whenever the

package/src/strand-solicitation.ts

@@ -16,6 +16,7 @@ import { ed25519KeyPairFromLibp2p } from './ed25519-key.js';
 import { mintPlaceholderStrandId } from './strand-id.js';
 import {
   StrandFormationManager,
+  type CadrePeerAddrsSource,
   type MembershipInviteIssuer,
   type StrandFormationManagerConfig
 } from './strand-formation-manager.js';
@@ -110,9 +111,11 @@ export interface FormationUsageRecorder {
   isTokenUsed(token: string): Promise<boolean>;
 
   /**
-   * Check if a token is valid and not expired
+   * Check if a token is valid and not expired. An invalid answer says why: `'unknown'` (no
+   * invitation row here — it may not have replicated yet) or `'expired'`. An answer without
+   * a reason is treated as `'unknown'`, the retryable one.
    */
-  isTokenValid(token: string): Promise<{ valid: boolean; invitation?: OpenInvitation }>;
+  isTokenValid(token: string): Promise<{ valid: boolean; reason?: 'unknown' | 'expired'; invitation?: OpenInvitation }>;
 
   /**
    * Resolve the host strand an invite binds to, classifying it as unbound / bound /
@@ -213,7 +216,7 @@ export interface StrandSolicitationServiceOptions {
   /** Party ID for this node (used in protocol messages) */
   partyId?: string;
   /** Cadre peer addresses for this node */
-  cadrePeerAddrs?: string[];
+  cadrePeerAddrs?: CadrePeerAddrsSource;
   /**
    * This node's live STRAND-network multiaddrs for a strand it is running (responder
    * side), carried back to a validated joiner as its cross-party discovery seed. Wired
@@ -251,7 +254,7 @@ export class StrandSolicitationService {
   private readonly strandProvisioner?: StrandProvisioner;
   private readonly formationResponseValidator?: FormationResponseValidator;
   private readonly partyId: string;
-  private readonly cadrePeerAddrs: string[];
+  private readonly cadrePeerAddrs: CadrePeerAddrsSource;
   private readonly resolveStrandAddrs?: (strandId: string) => string[];
   private readonly issueMembershipInvite?: MembershipInviteIssuer;
   private formationManager?: StrandFormationManager;
@@ -446,6 +449,16 @@ export class StrandSolicitationService {
     log('Registered minted invitation %s (expires %d)', token, expiresAtMs);
   }
 
+  /**
+   * Take over every token `previous` minted or published, so a service that replaces it
+   * on a node keeps the connection gate open for invitations already handed out.
+   */
+  adoptMintedInvitations(previous: StrandSolicitationService): void {
+    for (const [token, expiresAtMs] of previous.mintedInvitations) {
+      this.mintedInvitations.set(token, expiresAtMs);
+    }
+  }
+
   /**
    * Does this node currently expect a stranger — i.e. is at least one open
    * invitation unexpired and not yet fully consumed? Sole input to the

package/src/types.ts

@@ -17,6 +17,7 @@ import type { JoinedStrandStore } from './joined-strand-store.js';
 import type { PushNotifier } from './push-notifier.js';
 import type { RevocableTable } from './control-authorization.js';
 import type { ControlRetryAbandonment } from './control-retry.js';
+import type { FormationRejectionCode } from './strand-formation-rejection.js';
 
 /**
  * Extended Libp2p node with the coordinatedRepo attached by db-p2p's
@@ -478,8 +479,9 @@ export interface NetworkConfig {
    * reservation drive, the control-cohort dial budgets, and the per-peer cohort read deadline
    * ({@link cohortQueryTimeoutMs}, unless set explicitly). It is also handed to Optimystic
    * (`NodeOptions.linkRoundTripMs`), default included, which derives its own deadlines from it:
-   * its request dials and responses, its block pushes, and libp2p's `dialTimeout` and
-   * `inboundUpgradeTimeout` on every node. Reaching another machine through a
+   * its request dials and responses, its block pushes, and libp2p's `addressDialTimeout`,
+   * `dialTimeout` and `inboundUpgradeTimeout` on every node, cadre adding its admission decisions
+   * to the three that open a connection. Reaching another machine through a
    * relay costs a fixed number of exchanges, so a deadline written as milliseconds has a link
    * speed above which it can never open a connection — which is the defect this declaration
    * exists to make impossible to reintroduce one budget at a time. The counts, the measurement behind them,
@@ -496,8 +498,12 @@ export interface NetworkConfig {
    * Refused where the libp2p node is built — inside `CadreNode.start()` for the control
    * network, inside `CadreNode.addStrand` for a strand — if it is not a finite number above
    * zero, because every consumer multiplies it into a deadline where a zero means "give up at
-   * once" and a `NaN` means "never". Optimystic refuses, in the same place, a value above its
-   * `MAX_LINK_ROUND_TRIP_MS` (about 1.66 days).
+   * once" and a `NaN` means "never". A value above about 10.8 hours is refused in the same place,
+   * by Optimystic: the request dial cadre states from it (eleven round trips plus two admission
+   * decisions, `optimysticDialLimits` in `link-budget.ts`) then exceeds its
+   * `MAX_RPC_DIAL_TIMEOUT_MS` (about 4.97 days), and its error names `rpcDeadlines.dialTimeoutMs`.
+   * That is below Optimystic's own `MAX_LINK_ROUND_TRIP_MS` (about 13.3 hours) and far above any
+   * real link, so cadre adds no check of its own.
    */
   linkRoundTripMs?: number;
   /**
@@ -569,8 +575,8 @@ export interface NetworkConfig {
      * so an address that never answers cannot use up the time the peer's other
      * addresses needed. Defaults to
      * {@link DEFAULT_CONTROL_COHORT_PER_ADDRESS_DIAL_TIMEOUT_MS}. A value given
-     * here replaces that whole derived budget, including its allowance for the
-     * called machine's admission decision (`relayedDialBudgetMs`).
+     * here replaces that whole derived budget, including its allowances for the
+     * relay's and the called machine's admission decisions (`relayedDialBudgetMs`).
      */
     perAddressDialTimeoutMs?: number;
     /**
@@ -631,15 +637,11 @@ export interface NetworkConfig {
  *
  * WHY THE DEADLINE IS PINNED rather than given room to adapt. `pingTimeout` is an
  * adaptive-timeout init, and equal `minTimeout`/`maxTimeout` clamp it to one value on
- * every libp2p version. Under libp2p 3.1.3, which sereus resolves today, it is already
- * flat at `minTimeout`: `ConnectionMonitor` asks its `AdaptiveTimeout` for a deadline but
- * never calls `cleanUp` to report how long the ping took, so the moving average the
- * deadline derives from stays at zero. libp2p 3.3 does report ping durations back, and a
- * ceiling above `pingInterval` would then let the deadline grow past the interval and put
- * the overlapping-ping abort above straight back. Pinning both ends keeps the interval's
- * margin true on the version bump instead of making it something to remember. It also
- * sidesteps 3.3's other surprise: the monitor keeps one `AdaptiveTimeout` for all of a
- * node's connections, so one slow peer would otherwise lengthen the deadline for every
+ * every libp2p version. libp2p 3.3 reports each ping's duration back to the monitor's
+ * `AdaptiveTimeout`, so a ceiling above `pingInterval` would let the deadline grow past the
+ * interval and put the overlapping-ping abort above straight back. Pinning both ends keeps
+ * the interval's margin true. It also sidesteps the monitor keeping one `AdaptiveTimeout`
+ * for all of a node's connections, so one slow peer cannot lengthen the deadline for every
  * connection on that node.
  */
 export const DEFAULT_CONNECTION_MONITOR = Object.freeze({
@@ -1198,6 +1200,69 @@ export interface StrandRow {
   FounderOwnerKey: string | null;
 }
 
+/**
+ * A `CadreControl.PendingJoin` row: a join this party asked for through another party's
+ * invitation, readable by every machine of the party. Each outcome carries only its own
+ * columns (the schema's `OutcomeShape` check): `'joined'` sets `StrandId` (and, for a
+ * closed strand, `MembershipInvite`), `'failed'` sets `FailureCode`, and a pending row
+ * (`Outcome: null`) sets neither.
+ */
+export interface PendingJoinRow {
+  /** base64url sha256 of the invitation token (`pendingJoinId`). */
+  Id: string;
+  /** `CadreNode.encodeInvitation` of the invitation. A bearer credential. */
+  Invitation: string;
+  /** `canonicalJson` of the disclosure the requester gave. */
+  Disclosure: string;
+  /** Epoch ms. */
+  RequestedAt: number;
+  /** Epoch ms; no attempt starts at or after it. */
+  ExpiresAt: number;
+  Outcome: null | 'joined' | 'failed';
+  /** Epoch ms the outcome was recorded; null while pending. */
+  OutcomeAt: number | null;
+  /** `'joined'`: the strand the formation returned. */
+  StrandId: string | null;
+  /** `'joined'`, closed strand: JSON of the {@link StrandMembershipInvite} the formation delivered. */
+  MembershipInvite: string | null;
+  /** `'failed'`: a `FormationRejectionCode`, `'expired'` or `'local'`. Not constrained by the schema. */
+  FailureCode: string | null;
+  /** `'failed'`: human-readable text. */
+  FailureReason: string | null;
+  /** Single-use nonce of this row incarnation; `ControlDatabase.replacePendingJoin` names it as the row it replaces. */
+  StampId: string;
+}
+
+/**
+ * A join this party asked for through `CadreNode.requestJoin`, as one machine sees it.
+ *
+ * `pending`, `joined` and `failed` come from the party-wide `PendingJoin` row and read the same
+ * on every machine. `trying` (an attempt is running on this machine) and `waiting` (this
+ * machine's last attempt failed in a way worth retrying) are this machine's own view of a
+ * pending row, so two machines can report different states for it.
+ */
+export interface PendingJoinStatus {
+  /** `PendingJoin.Id`: the sha256 of the invitation token. */
+  id: string;
+  sAppId: string;
+  /** Epoch ms. */
+  requestedAt: number;
+  /** Epoch ms; no attempt starts at or after it. */
+  expiresAt: number;
+  state: 'pending' | 'trying' | 'waiting' | 'joined' | 'failed';
+  /** `'waiting'`: when this machine tries again, epoch ms. */
+  nextAttemptAt?: number;
+  /**
+   * `'waiting'`: why this machine's last attempt failed. `'unreachable'` means no answer came
+   * back; `'local'` means the attempt failed on this machine before an answer.
+   */
+  lastError?: { code: FormationRejectionCode | 'unrecognized' | 'unreachable' | 'local'; reason: string };
+  /** `'joined'`: the strand the join produced. */
+  strandId?: string;
+  /** `'failed'`: a `FormationRejectionCode`, `'expired'`, or `'local'` (approved, then a step on the joining machine failed). */
+  failure?: { code: string; reason: string };
+}
+
 /**
  * sApp configuration provided by the hosting application when creating a strand.
  * This is what the app developer provides - NOT loaded from the network.
@@ -1374,7 +1439,13 @@ export interface OpenInvitation {
   sAppId: string;
   /** When this invitation expires */
   expiration: Date;
-  /** Bootstrap addresses to contact the inviter's cadre */
+  /**
+   * Addresses of the inviting party's machines, each ending in `/p2p/<peerId>`: the minting
+   * machine's own first, then up to three of its siblings with up to four addresses each
+   * (`CadreNode.createOpenInvitation`). A joiner tries the machines in order, one formation
+   * session each, so an entry may be dead by the time it is used; one that names no machine
+   * is ignored.
+   */
   bootstrap: string[];
 }
 
@@ -1394,7 +1465,11 @@ export interface StrandMembershipInvite {
    * The invite ed25519 PRIVATE seed (base64url). A single-use bearer credential:
    * whoever holds it can `consumeInvite` exactly once. Same sensitivity class and
    * handling as `memberPrivateKey` — delivered only inside the validated,
-   * post-approval formation result, never written to either side's control DB.
+   * post-approval formation result. The inviting side never writes it to its control
+   * DB. The joining side may copy it into its own `PendingJoin` row
+   * (`MembershipInvite`), owner-signed and party-private like
+   * `JoinedStrand.MemberPrivateKey`, so a join finished on one machine of the party
+   * can be seated by whichever machine launches the strand first.
    */
   invitePrivateKey: string;
 }
@@ -1601,6 +1676,13 @@ export interface CadreNodeEvents {
    * or connection state change.
    */
   'control:write-abandoned': ControlRetryAbandonment;
+  /**
+   * Emitted when this machine's view of a join asked for with `CadreNode.requestJoin` changes:
+   * its own attempt started or ended, or a pass read an outcome another owner machine wrote.
+   * Owner machines only, since only they run the retry loop. A dismissed join emits nothing
+   * further; `listPendingJoins` no longer names it.
+   */
+  'pendingJoin:changed': PendingJoinStatus;
   /** Emitted when a seed is received via the seed protocol */
   'seed:received': { partyId: string; peerId: string };
   /** Emitted when a seed is successfully applied */