@serfab/cadre-core 0.8.1 → 0.10.0

package/src/strand-formation-protocol.ts

@@ -23,12 +23,27 @@ import { multiaddr } from '@multiformats/multiaddr';
 import type { Libp2p } from '@libp2p/interface';
 import type { StrandFormationDisclosure } from './types.js';
 import { type ControlStream, writeFrame, withTimeout } from './control-stream.js';
+import { canonicalJson } from './canonical-json.js';
+import { requireEd25519PublicKeyB64 } from './ed25519-key.js';
+import { verifyFormationConsent } from './peer-authorization.js';
+// seed-bootstrap imports neither this protocol nor the manager/solicitation layers,
+// so this import introduces no cycle.
+import { ed25519PublicKeyB64FromPeerId } from './seed-bootstrap.js';
 
 const log = debug('sereus:cadre:formation-proto');
 
 /** Protocol id for the native formation transport (parallel to `/sereus/seed/1.0.0`). */
 export const FORMATION_PROTOCOL = '/sereus/formation/1.0.0';
 
+/**
+ * Rejection reason for an invitation that cannot be redeemed at all — unknown, expired, or
+ * fully spent. Shared with `StrandFormationManager`, which reports an
+ * `InvitationExhaustedError` (an invite spent out from under a redemption already in flight)
+ * with this SAME wording on purpose: a joiner that lost the race must be indistinguishable
+ * from a non-racing latecomer, so the two sites must never drift apart.
+ */
+export const INVALID_TOKEN_REASON = 'Invalid token';
+
 /** Maximum formation message size (1MB). */
 const MAX_FORMATION_MSG_SIZE = 1024 * 1024;
 
@@ -36,7 +51,63 @@ const MAX_FORMATION_MSG_SIZE = 1024 * 1024;
 const DEFAULT_SESSION_TIMEOUT_MS = 30_000;
 /** Default per-step (single read/write) timeout (ms). */
 const DEFAULT_STEP_TIMEOUT_MS = 5_000;
-/** Default cap on concurrent inbound formation sessions. */
+/**
+ * Default provisioning budget (ms) — distinct from {@link DEFAULT_STEP_TIMEOUT_MS} because
+ * `provisionStrand` is real work (DB writes, and an outbound approval-hook HTTP call when
+ * the invite carries a `ValidationUrl`), not a bare wire read/write.
+ *
+ * Ordering is deliberate — each layer must be able to fail and report before the layer above
+ * it gives up:
+ *
+ *   approval hook (10 s, `formation-approval.ts`)
+ *     < responder provisioning (12 s)
+ *     < initiator await-response (15 s)
+ *     < session (30 s)
+ *
+ * The 3 s margin between responder provisioning and initiator await-response is the wire
+ * latency budget for the result frame to travel back.
+ *
+ * The last {@link PROVISION_SETTLE_GRACE_MS} of this budget is a settle grace, so the default
+ * WORK budget (12 s − 2 s = 10 s) EQUALS the hook's own 10 s: a dead hook races 'Formation
+ * approval unavailable, retry' against 'Formation provisioning timed out'. Both are retryable
+ * and both leave the invite unspent, so the race is benign.
+ */
+const DEFAULT_PROVISION_TIMEOUT_MS = 12_000;
+/**
+ * Settle grace (ms), carved OUT of `provisionTimeoutMs` — never added on top, so the budget
+ * ladder above is untouched. The listener aborts the provisioning hook when the work budget
+ * ({@link splitProvisionBudget}) expires, then waits up to this grace for the work to settle
+ * anyway: once the `FormationUsage` insert has been issued nothing can un-spend it (the table
+ * is append-only), so a provisioning that lands late is ADOPTED and reported as a real
+ * approval rather than lying "timed out" over a spent invite. A hook that observes the
+ * abort before writing leaves the invite unspent.
+ */
+const PROVISION_SETTLE_GRACE_MS = 2_000;
+/**
+ * Wire-latency margin (ms) added to the responder's provisioning budget to get the
+ * initiator's await-response budget — the travel time for the result frame to come back
+ * after the responder finishes (see {@link DEFAULT_PROVISION_TIMEOUT_MS}).
+ * `StrandFormationManager` reuses this constant so a CONFIGURED budget preserves the same
+ * margin the defaults do, instead of applying the same number to both sides and racing the
+ * initiator's own timeout against the responder's clean rejection reply. The responder's
+ * clamp ({@link provisionCeilingMs}) holds the same margin back, so the ordering survives a
+ * budget large enough that BOTH roles get clamped.
+ *
+ * NOTE: 3 s is a fixed assumption about how long the result frame takes to travel back. If
+ * formation ever runs over paths where that frame can take longer (a slow circuit relay, a
+ * congested mobile link), the margin is too thin and the initiator's timeout races the
+ * responder's reply again — raise it, or derive it from an observed round-trip.
+ */
+export const PROVISION_RESPONSE_TRAVEL_MARGIN_MS = 3_000;
+/** Default initiator await-response budget (ms); see {@link DEFAULT_PROVISION_TIMEOUT_MS}. */
+const DEFAULT_INITIATOR_PROVISION_TIMEOUT_MS = DEFAULT_PROVISION_TIMEOUT_MS + PROVISION_RESPONSE_TRAVEL_MARGIN_MS;
+/**
+ * Default cap on concurrent inbound formation sessions.
+ * NOTE: a longer provisioning budget holds a session's slot longer, so a slow hook can
+ * exhaust this cap and make the listener reject fresh joiners with 'Too many concurrent
+ * formation sessions'. Fine at the current default; revisit if `provisionTimeoutMs` is
+ * raised well above its default or this cap is lowered.
+ */
 const DEFAULT_MAX_CONCURRENT_SESSIONS = 100;
 
 // ── Roles ────────────────────────────────────────────────────────────────────
@@ -85,8 +156,20 @@ export type ResponderProvisionOutcome =
 export interface FormationContactMessage {
   /** The real invitation token. */
   token: string;
-  /** Initiator's member key (peer id). */
+  /** Initiator's member key (peer id) — human-facing identity in logs and `FormStrandResult.memberKey`. */
   partyId: string;
+  /**
+   * Initiator's base64url ed25519 public key — the key behind `partyId`, written to
+   * `FormationUsage.PeerKey` and covered by BOTH signed digests.
+   */
+  peerKey: string;
+  /** Joiner-minted single-use nonce for THIS redemption; both signed digests cover it. */
+  usageStampId: string;
+  /**
+   * The joiner's signature over the `'consent'` digest (see `formationConsentMessage`
+   * in control-database.ts) — proof the named peer agreed to this redemption.
+   */
+  peerSignature: string;
   /** The real disclosure, carried verbatim. */
   disclosure: StrandFormationDisclosure;
   /** Initiator's real multiaddrs. */
@@ -174,7 +257,7 @@ const PLACEHOLDER_CADRE_ADDR = /^cadre-[ab]-\d+\.local$/;
  * placeholders), and returned a strand vouched for by the responder party with a real id.
  *
  * `createdBy: 'responder'` means "the responder party vouches for / returns this strand."
- * Under provision-then-record that strand was minted authority-signed earlier (not created
+ * Under provision-then-record that strand was minted owner-signed earlier (not created
  * in-session), but it is still the responder party returning its own strand, so the marker
  * — and this structural validator — stay unchanged.
  *
@@ -193,6 +276,62 @@ export function isValidResponderCreatesResult(response: FormationResultMessage):
   return true;
 }
 
+/**
+ * Ceiling for a resolved provisioning budget.
+ *
+ * The session budget also has to cover the wire step that PRECEDES provisioning (the
+ * responder's contact read, the initiator's dial-connect), so a whole step is held back
+ * rather than triggering only on a literal overrun.
+ *
+ * `reserveMs` is the EXTRA room only the responder holds back, so its own budget still
+ * lands strictly before the initiator's larger await-response budget even when both are
+ * clamped — without it, any configured budget at or above `sessionTimeoutMs -
+ * stepTimeoutMs` clamps both roles onto the same number and the responder's clean
+ * rejection races the initiator's timeout again. Capped at half the remaining room (like
+ * {@link splitProvisionBudget}) so a small session config still spends most of it working.
+ */
+function provisionCeilingMs(sessionTimeoutMs: number, stepTimeoutMs: number, reserveMs: number): number {
+  const roomMs = sessionTimeoutMs - stepTimeoutMs;
+  return Math.max(1, roomMs - Math.min(reserveMs, Math.floor(roomMs / 2)));
+}
+
+/**
+ * Resolve a caller-supplied provisioning budget: `0`/negative means "unset" (use
+ * `defaultMs`). If the result would let provisioning outlive the session — no result
+ * frame is ever sent, exactly the failure this budget exists to prevent — clamp it to
+ * {@link provisionCeilingMs} and log a warning.
+ */
+function resolveProvisionTimeoutMs(
+  configured: number | undefined,
+  defaultMs: number,
+  sessionTimeoutMs: number,
+  stepTimeoutMs: number,
+  role: string,
+  reserveMs = 0
+): number {
+  const requested = configured && configured > 0 ? configured : defaultMs;
+  const ceilingMs = provisionCeilingMs(sessionTimeoutMs, stepTimeoutMs, reserveMs);
+  if (requested >= ceilingMs) {
+    log(
+      '%s provisionTimeoutMs %dms leaves no room under sessionTimeoutMs %dms (step %dms, reserve %dms); clamping to %dms',
+      role, requested, sessionTimeoutMs, stepTimeoutMs, reserveMs, ceilingMs
+    );
+    return ceilingMs;
+  }
+  return requested;
+}
+
+/**
+ * Split a resolved provisioning budget into the WORK budget and the trailing settle grace.
+ *
+ * The grace is carved OUT of the budget (see {@link PROVISION_SETTLE_GRACE_MS}), and capped at
+ * half of it so a small configured budget still spends at least half its time doing work.
+ */
+function splitProvisionBudget(provisionTimeoutMs: number): { workMs: number; graceMs: number } {
+  const graceMs = Math.min(PROVISION_SETTLE_GRACE_MS, Math.floor(provisionTimeoutMs / 2));
+  return { workMs: provisionTimeoutMs - graceMs, graceMs };
+}
+
 // ── Responder (listener) ─────────────────────────────────────────────────────
 
 export interface FormationListenerOptions {
@@ -202,18 +341,31 @@ export interface FormationListenerOptions {
   validateDisclosure(token: string, disclosure: StrandFormationDisclosure): Promise<boolean>;
   /**
    * Provision (or, for provision-then-record, resolve + record consent against) the
-   * strand (`responderCreates`) for the given initiator. The REAL token is threaded
-   * in so the hook can map it to the bound host strand and its membership key.
+   * strand (`responderCreates`) for the given initiator. The WHOLE contact message is
+   * threaded in: the hook needs the REAL token to map the bound host strand, and the
+   * joiner's `peerKey`/`usageStampId`/`peerSignature` to write the consent columns.
    *
    * Returns a {@link ResponderProvisionOutcome}: the hook may REJECT post-validation
    * (e.g. an unconverged host strand) and the listener turns that into a clean,
    * non-disclosing `approved: false` reply rather than dropping the result frame.
+   *
+   * `signal` is aborted when the listener's work budget expires: a hook that observes it
+   * BEFORE writing abandons the redemption and leaves the invite unspent. Optional so
+   * signal-unaware hooks (tests, mocks) stay assignable.
    */
-  provisionStrand(token: string, initiatorPartyId: string, disclosure: StrandFormationDisclosure): Promise<ResponderProvisionOutcome>;
+  provisionStrand(contact: FormationContactMessage, signal?: AbortSignal): Promise<ResponderProvisionOutcome>;
   /** Responder identity, disclosed only AFTER token + disclosure validation passes. */
   getResponderIdentity(): { partyId: string; cadrePeerAddrs: string[] };
   sessionTimeoutMs?: number;
   stepTimeoutMs?: number;
+  /**
+   * Budget for the `provisionStrand` hook call — distinct from `stepTimeoutMs` because
+   * provisioning is real work, not a bare wire read/write. Default 12 s; `0`/unset uses
+   * the default; a value that would outlive the session is clamped ({@link
+   * provisionCeilingMs}). See {@link DEFAULT_PROVISION_TIMEOUT_MS} for the full ordering
+   * rationale.
+   */
+  provisionTimeoutMs?: number;
   maxConcurrentSessions?: number;
 }
 
@@ -227,6 +379,8 @@ export class FormationListener {
   private readonly options: FormationListenerOptions;
   private readonly sessionTimeoutMs: number;
   private readonly stepTimeoutMs: number;
+  private readonly provisionWorkMs: number;
+  private readonly provisionGraceMs: number;
   private readonly maxConcurrentSessions: number;
   private readonly registered = new Set<Libp2p>();
   private activeSessions = 0;
@@ -236,6 +390,13 @@ export class FormationListener {
     this.options = options;
     this.sessionTimeoutMs = options.sessionTimeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS;
     this.stepTimeoutMs = options.stepTimeoutMs ?? DEFAULT_STEP_TIMEOUT_MS;
+    const split = splitProvisionBudget(resolveProvisionTimeoutMs(
+      options.provisionTimeoutMs, DEFAULT_PROVISION_TIMEOUT_MS,
+      this.sessionTimeoutMs, this.stepTimeoutMs, 'FormationListener',
+      PROVISION_RESPONSE_TRAVEL_MARGIN_MS
+    ));
+    this.provisionWorkMs = split.workMs;
+    this.provisionGraceMs = split.graceMs;
     this.maxConcurrentSessions = options.maxConcurrentSessions ?? DEFAULT_MAX_CONCURRENT_SESSIONS;
   }
 
@@ -282,6 +443,125 @@ export class FormationListener {
     }
   }
 
+  /**
+   * Run the provisioning hook under its WORK budget — the configured provisioning budget minus
+   * the trailing settle grace ({@link splitProvisionBudget}, {@link PROVISION_SETTLE_GRACE_MS}).
+   *
+   * When the work budget expires the hook's signal is aborted, then
+   * {@link settleWithinGrace} waits out the grace for the aborted work to settle anyway.
+   * Returns `undefined` for "timed out" — which the caller turns into a retryable rejection
+   * frame — and rethrows every other failure so it reaches the internal-error path.
+   *
+   * Deliberately not `withDeadline`: that exposes neither the timed-out flag nor the signal
+   * outside its `op`, and both are needed here.
+   */
+  private async provision(id: number, contact: FormationContactMessage): Promise<ResponderProvisionOutcome | undefined> {
+    const controller = new AbortController();
+    let timedOut = false;
+    const pending = this.options.provisionStrand(contact, controller.signal);
+    try {
+      return await withTimeout(
+        this.provisionWorkMs,
+        `Formation provisioning#${id}`,
+        () => pending,
+        () => { timedOut = true; controller.abort(); }
+      );
+    } catch (err) {
+      if (!timedOut) throw err;
+      log(
+        'formation session #%d provisioning work budget expired after %dms; aborted, settling up to %dms',
+        id, this.provisionWorkMs, this.provisionGraceMs
+      );
+      return await this.settleWithinGrace(id, pending);
+    }
+  }
+
+  /**
+   * Wait out the settle grace for an ABORTED provisioning, adopting a late success.
+   *
+   * A hook that observed the abort before issuing its `FormationUsage` insert rejects (with
+   * `FormationAbortedError`) and leaves the invite unspent → reported as a timeout. A hook
+   * that had already written cannot be un-written (the table is append-only), so if it lands
+   * inside the grace its outcome is ADOPTED — the joiner is told the truth (approved, or the
+   * hook's own rejection reason) rather than "timed out" over a spent invite.
+   *
+   * NOTE: one window stays open — a work budget that expires after the `FormationUsage`
+   * insert was issued AND a commit that outlasts the grace. The joiner is told 'timed out'
+   * while its one-time invite is in fact spent, and since every retry mints a fresh keypair
+   * no recovery path can match it. Nothing can un-spend an append-only row, so the late-settle
+   * logging below is the observability for it; widen the grace only if it is seen in the wild.
+   */
+  private async settleWithinGrace(
+    id: number,
+    pending: Promise<ResponderProvisionOutcome>
+  ): Promise<ResponderProvisionOutcome | undefined> {
+    let stillPending = false;
+    try {
+      const outcome = await withTimeout(
+        this.provisionGraceMs,
+        `Formation settle#${id}`,
+        () => pending,
+        () => { stillPending = true; }
+      );
+      log('formation session #%d provisioning settled within its grace: approved=%s — adopting', id, outcome.approved);
+      return outcome;
+    } catch (err) {
+      if (!stillPending) {
+        log('formation session #%d provisioning failed after its abort: %o', id, err);
+        return undefined;
+      }
+      log('formation session #%d provisioning still pending after its %dms grace', id, this.provisionGraceMs);
+      // Log how it eventually settled so a late failure is not swallowed by the two
+      // abandoned `withTimeout` calls.
+      void pending.then(
+        (late) => log('formation session #%d provisioning settled after its grace: approved=%s', id, late.approved),
+        (err2) => log('formation session #%d provisioning failed after its grace: %o', id, err2)
+      );
+      return undefined;
+    }
+  }
+
+  /**
+   * Joiner-consent pre-check — the legibility twin of the schema's
+   * `FormationUsage.PeerConsented` CHECK, exactly as `verifyFormationApproval` is for the
+   * approver's vouch. The database constraint stays the authority; this turns a bad consent
+   * into a clean 'Invalid joiner consent' rejection instead of an opaque CHECK failure at
+   * commit. Runs BEFORE token/disclosure validation: it is the cheapest check (pure local
+   * crypto, no DB read) and a rejection discloses nothing.
+   *
+   * Also pins `partyId` to `peerKey`: an ed25519 peer id is an identity multihash of the
+   * very key, and this is the ONLY layer that can check the match — SQL cannot unwrap a
+   * multihash, and `partyId` itself is never stored.
+   */
+  private isJoinerConsentValid(id: number, contact: FormationContactMessage): boolean {
+    try {
+      requireEd25519PublicKeyB64(contact.peerKey, 'joiner peer key');
+    } catch {
+      // Deliberately not rethrown or echoed: the helper's error message embeds the whole
+      // rejected value, and this one arrived from a remote peer (the cap-the-echo case its
+      // own NOTE warns about). Log without the raw value instead.
+      log('formation session #%d: joiner peer key is not a base64url ed25519 public key', id);
+      return false;
+    }
+    const embedded = ed25519PublicKeyB64FromPeerId(contact.partyId);
+    if (!embedded || embedded !== contact.peerKey) {
+      log('formation session #%d: partyId does not embed the presented peer key', id);
+      return false;
+    }
+    const consentOk = verifyFormationConsent({
+      token: contact.token,
+      usageStampId: contact.usageStampId,
+      peerKey: contact.peerKey,
+      disclosure: canonicalJson(contact.disclosure),
+      peerSig: contact.peerSignature
+    });
+    if (!consentOk) {
+      log('formation session #%d: joiner consent signature failed verification', id);
+      return false;
+    }
+    return true;
+  }
+
   private async runSession(id: number, stream: ControlStream): Promise<void> {
     // Track whether ANY frame has been written so the catch below can convert an
     // unexpected internal error into a non-disclosing rejection ONLY when nothing has
@@ -297,9 +577,14 @@ export class FormationListener {
       const contact = await withTimeout(this.stepTimeoutMs, `Formation await-contact#${id}`, () => reader.read<FormationContactMessage>());
       log('formation session #%d contact: token=%s party=%s', id, contact.token, contact.partyId);
 
+      if (!this.isJoinerConsentValid(id, contact)) {
+        send({ approved: false, reason: 'Invalid joiner consent' });
+        return;
+      }
+
       const tokenResult = await this.options.validateToken(contact.token);
       if (!tokenResult.valid) {
-        send({ approved: false, reason: 'Invalid token' });
+        send({ approved: false, reason: INVALID_TOKEN_REASON });
         return;
       }
 
@@ -309,7 +594,13 @@ export class FormationListener {
         return;
       }
 
-      const outcome = await this.options.provisionStrand(contact.token, contact.partyId, contact.disclosure);
+      const outcome = await this.provision(id, contact);
+      if (!outcome) {
+        // Reported as its own retryable reason rather than falling through to the generic
+        // catch below, which would report the misleading 'Internal formation error'.
+        send({ approved: false, reason: 'Formation provisioning timed out' });
+        return;
+      }
       if (!outcome.approved) {
         // A post-validation rejection still discloses NEITHER identity NOR cadre,
         // exactly like the token/disclosure rejections above.
@@ -351,6 +642,12 @@ export interface FormationDialOptions {
   validateResponse(response: FormationResultMessage): Promise<boolean>;
   sessionTimeoutMs?: number;
   stepTimeoutMs?: number;
+  /**
+   * Budget for the `await-response` read only (the responder's provisioning + reply travel
+   * time) — `dial-connect` keeps using `stepTimeoutMs`. Default 15 s; `0`/unset uses the
+   * default. See {@link DEFAULT_PROVISION_TIMEOUT_MS} for the full ordering rationale.
+   */
+  provisionTimeoutMs?: number;
   protocolId?: string;
 }
 
@@ -366,6 +663,10 @@ export async function dialFormation(node: Libp2p, options: FormationDialOptions)
   const protocolId = options.protocolId ?? FORMATION_PROTOCOL;
   const sessionTimeoutMs = options.sessionTimeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS;
   const stepTimeoutMs = options.stepTimeoutMs ?? DEFAULT_STEP_TIMEOUT_MS;
+  const provisionTimeoutMs = resolveProvisionTimeoutMs(
+    options.provisionTimeoutMs, DEFAULT_INITIATOR_PROVISION_TIMEOUT_MS,
+    sessionTimeoutMs, stepTimeoutMs, 'dialFormation'
+  );
   const addr = multiaddr(options.responderAddrs[0]);
 
   return withTimeout(sessionTimeoutMs, 'Formation dial', async () => {
@@ -375,7 +676,7 @@ export async function dialFormation(node: Libp2p, options: FormationDialOptions)
       const reader = new FrameReader(stream);
       writeFrame(stream, options.contact);
 
-      const response = await withTimeout(stepTimeoutMs, 'Formation await-response', () => reader.read<FormationResultMessage>());
+      const response = await withTimeout(provisionTimeoutMs, 'Formation await-response', () => reader.read<FormationResultMessage>());
       if (!response.approved) {
         throw new Error(`Formation rejected: ${response.reason ?? 'no reason provided'}`);
       }