@serfab/cadre-core 1.16.0 → 1.18.0

package/src/cadre-invite-protocol.ts

@@ -1,1052 +1,740 @@
-/**
- * Cadre invitation redemption transport: `/sereus/cadre-invite/1.0.0`.
- *
- * A device holding a cadre invitation (an owner-signed `CadreInvite` row plus the private
- * half of the invitation keypair, see {@link CadreInvitation}) dials ANY member machine the
- * invitation names and proves possession; the member seats the row if it does not hold it
- * yet, writes the device's `CadrePeer` row (and `OwnerKey` row, when the invitation grants
- * ownership) through `ControlDatabase.redeemCadreInvite`, and answers with the party id,
- * the row and dial hints. The owner that minted the invitation need not be online.
- *
- * Same shape as the seed and wake protocols: one length-prefixed JSON frame each way over
- * the shared primitives in `control-stream.ts`. Stranger-facing by design — the device is
- * not a member when it dials — so the connection gate admits a stranger while a live
- * invitation exists (`membership-connection-gater.ts`), and the handler's own trust
- * decision is the proof of possession: nothing touches the database for a caller that
- * cannot prove it holds the invitation and is the identity it names.
- *
- * The seed protocol is left untouched so `SeedMessage` can grow independently.
- */
-
-import debug from 'debug';
-import { multiaddr, type Multiaddr } from '@multiformats/multiaddr';
-import type { Connection, Libp2p } from '@libp2p/interface';
-import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } from 'uint8arrays';
-import { sign } from '@optimystic/quereus-plugin-crypto';
-import { type ControlStream, withDeadline, exchangeFrame, readStreamToEnd, replyAndClose } from './control-stream.js';
-import { decodeLengthPrefixedFrame } from './seed-bootstrap.js';
-import { relayedRequestBudgetMs } from './link-budget.js';
-import {
-  cadreInviteRedeemMessage,
-  cadreInviteConsentMessage,
-  CadreInviteIssuerUnknownError,
-  InvitationExhaustedError,
-  parseNullableStoredDatetimeMs,
-  type ControlDatabase
-} from './control-database.js';
-import { verifyCadreInviteRow, verifyCadreInviteRedemption } from './peer-authorization.js';
-import { ed25519PublicKeyB64FromPeerId, requireEd25519PublicKeyB64 } from './ed25519-key.js';
-import { dialAddr, nextMacrotask, trailingPeerId } from './peer-dial.js';
-import { chainMessages } from './control-retry.js';
-import { isRetriableControlWriteFailure } from './control-write-retry.js';
-import { CADRE_INVITATION_PREFIX, CADRE_JOIN_REQUEST_PREFIX } from './cadre-join-request.js';
-import type { CadreInviteRow, CadreJoinProgress, SeedPeer } from './types.js';
-
-const log = debug('sereus:cadre:invite-proto');
-
-/** Protocol id for cadre invitation redemption (parallel to `/sereus/seed/1.0.0`). */
-export const CADRE_INVITE_PROTOCOL = '/sereus/cadre-invite/1.0.0';
-
-/**
- * Cap on either frame. A request is one signed row, two signatures and a few addresses;
- * a reply adds a peer list of a cadre's size. Both fit in a few KB; 64 KiB is the
- * defensive bound a stranger can make the handler buffer.
- */
-const MAX_CADRE_INVITE_MSG_SIZE = 64 * 1024;
-
-/**
- * Default time the member waits for the request frame before aborting the read (ms). The
- * read only: a stranger opens the stream, so the bound is on a caller that opens one and
- * never sends. Same figure as the seed handler's.
- */
-// eslint-disable-next-line no-restricted-syntax -- link-independent: a receiver cap on one frame on a stream the peer already opened; it bounds a peer that opens a stream and never sends, not the dial
-const DEFAULT_REDEEM_READ_TIMEOUT_MS = 10_000;
-
-/** Default cap on concurrent inbound redemptions; over it the handler answers `busy`. */
-const DEFAULT_MAX_CONCURRENT_REDEMPTIONS = 100;
-
-/** Longest string field accepted off the wire; a stamp is 342 base64url chars, a signature 86. */
-const MAX_WIRE_FIELD_LENGTH = 1024;
-
-/** Most addresses a request may carry for the device, and a reply per peer (`sanitizeAddrs`). */
-const MAX_ADDRS = 16;
-
-/** Most machines an invitation bundle may name; the issuer caps its own list far below this. */
-const MAX_BUNDLE_MEMBERS = 64;
-
-/** Most peers a reply may carry as dial hints. */
-const MAX_REPLY_PEERS = 256;
-
-const BASE64URL = /^[A-Za-z0-9_-]+$/;
-
-// ── The invitation bundle ────────────────────────────────────────────────────
-
-/**
- * What an owner hands out (QR, paste, link) and a device redeems. An invitation is an
- * ed25519 keypair: the row holds the public half, `invitePrivateKey` is the proof of
- * possession, and whoever holds this bundle can redeem it — treat it as a bearer
- * credential for the row's lifetime (an untargeted owner-granting one defaults to a
- * 15-minute expiry for that reason).
- *
- * Carrying the signed row is what makes redemption work at a member that has not received
- * the row by replication: the member seats it from the bundle under its stored issuer
- * signature. The row's own signature covers every column, so a bundle whose row was
- * altered cannot be seated anywhere.
- */
-export interface CadreInvitation {
-  v: 1;
-  /** The cadre the invitation joins; a device refuses one for another party. */
-  partyId: string;
-  /** The invitation's ed25519 seed, base64url: the proof of possession. */
-  invitePrivateKey: string;
-  /** The owner-signed row exactly as issued (`ControlDatabase.insertCadreInvite`). */
-  invite: CadreInviteRow;
-  /**
-   * The issuer's anchored owner keys. The redeeming device pins them before it dials
-   * (`CadreNode.trustOwnerKeys`) and checks the member's reply against them. Sourced from
-   * the issuer's node-local anchor only, never the replicated `OwnerKey` table, for the
-   * reason the seed invite gives: the device anchors whatever arrives here.
-   */
-  ownerKeys: string[];
-  /**
-   * Multiaddrs ending in `/p2p/<peerId>`: the issuer's own first, then other members', at
-   * most `CADRE_INVITATION_MAX_ADDRS` in all (`selectCadreInvitationMembers` in
-   * `invitation-bootstrap.ts`). The device tries them in order.
-   */
-  members: string[];
-}
-
-/**
- * Encode a bundle for out-of-band delivery: {@link CADRE_INVITATION_PREFIX}, then base64url
- * over JSON. The prefix lets an app tell an invitation from a join request
- * (`cadre-join-request.ts`) and name the mistake when one is pasted for the other.
- */
-export function encodeCadreInvitation(invitation: CadreInvitation): string {
-  return `${CADRE_INVITATION_PREFIX}${uint8ArrayToString(new TextEncoder().encode(JSON.stringify(invitation)), 'base64url')}`;
-}
-
-/**
- * Decode a bundle, refusing anything that is not a well-formed version-1
- * {@link CadreInvitation} behind {@link CADRE_INVITATION_PREFIX}. Standalone so a client
- * without a node (a settings screen that wants to show which cadre an invitation joins) can
- * decode one.
- *
- * @throws on a join request, a string without the prefix or that is not base64url JSON after
- *   it, or one that decodes to another shape or version.
- */
-export function decodeCadreInvitation(encoded: string): CadreInvitation {
-  const trimmed = encoded.trim();
-  if (trimmed.startsWith(CADRE_JOIN_REQUEST_PREFIX)) {
-    throw new Error('This is a join request, not a cadre invitation; paste it into the app that manages your cadre');
-  }
-  if (!trimmed.startsWith(CADRE_INVITATION_PREFIX)) {
-    throw new Error(`Cadre invitation must start with "${CADRE_INVITATION_PREFIX}" (this one starts with "${trimmed.slice(0, CADRE_INVITATION_PREFIX.length)}")`);
-  }
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(new TextDecoder().decode(uint8ArrayFromString(trimmed.slice(CADRE_INVITATION_PREFIX.length), 'base64url')));
-  } catch (error) {
-    throw new Error('Cadre invitation does not decode as base64url JSON', { cause: error });
-  }
-  if (!isWellFormedCadreInvitation(parsed)) {
-    throw new Error('Cadre invitation is malformed or of an unsupported version');
-  }
-  return parsed;
-}
-
-function isWellFormedCadreInvitation(value: unknown): value is CadreInvitation {
-  if (typeof value !== 'object' || value === null) return false;
-  const { v, partyId, invitePrivateKey, invite, ownerKeys, members } = value as Record<string, unknown>;
-  return v === 1
-    && isBoundedString(partyId)
-    && isEd25519KeyB64(invitePrivateKey)
-    && isWellFormedCadreInviteRow(invite)
-    && Array.isArray(ownerKeys) && ownerKeys.length > 0 && ownerKeys.every((key) => isEd25519KeyB64(key))
-    && Array.isArray(members) && members.length <= MAX_BUNDLE_MEMBERS && members.every((addr) => isBoundedString(addr));
-}
-
-// ── Wire messages ────────────────────────────────────────────────────────────
-
-/** Device → member: one frame, the whole redemption. */
-export interface CadreInviteRedeemRequest {
-  v: 1;
-  /** The cadre the device believes it is joining; a machine serving another party refuses by name. */
-  partyId: string;
-  /** The owner-signed row from the bundle. */
-  invite: CadreInviteRow;
-  /** The device's ed25519 public key, base64url; must be the key behind the connecting peer id. */
-  peerKey: string;
-  /** The device's dialable addresses; empty for a phone. Stored on its `CadrePeer` row. */
-  multiaddrs: string[];
-  /** Single-use nonce the device minted (`generateStampId`); both signatures cover it. */
-  usageStampId: string;
-  /** By `invitePrivateKey` over the `'redeem'` digest. */
-  inviteSig: string;
-  /** By the device's identity key over the `'consent'` digest. */
-  peerSig: string;
-}
-
-/**
- * Why a member refused a redemption. Retryability is {@link CADRE_INVITE_REJECTION_RETRYABLE}'s;
- * a retryable code moves the device to the next address the bundle names.
- */
-export type CadreInviteRejectionCode =
-  /**
-   * The issuer's `OwnerKey` row is not on this member (not replicated yet), or the issuer was
-   * removed; the member cannot tell which, so the device tries the next address.
-   */
-  | 'issuer-unknown'
-  /**
-   * A signature does not verify, the peer key is not the connecting identity, the request or
-   * the row is malformed, or the invitation names another device.
-   */
-  | 'invite-invalid'
-  /** Expired, withdrawn, exhausted, or issued by a key that is no longer an owner here. */
-  | 'invite-spent'
-  /** This machine serves another cadre than the one the invitation names. */
-  | 'party-mismatch'
-  /** The member is at its cap on concurrent redemptions. */
-  | 'busy'
-  /** The write failed transiently (the write retry gave up); nothing was recorded. */
-  | 'conflict'
-  /**
-   * An unexpected member-side failure, or a request frame the member could not read (timed
-   * out, oversized, not JSON): nothing was proved either way, so the device tries the next
-   * address, as the formation responder's `internal` is read.
-   */
-  | 'internal';
-
-/** Which refusals are worth repeating at the next address — the one place that says so. */
-export const CADRE_INVITE_REJECTION_RETRYABLE: Readonly<Record<CadreInviteRejectionCode, boolean>> = {
-  'issuer-unknown': true,
-  'invite-invalid': false,
-  'invite-spent': false,
-  'party-mismatch': false,
-  'busy': 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 isCadreInviteRejectionCode(value: unknown): value is CadreInviteRejectionCode {
-  return typeof value === 'string' && Object.prototype.hasOwnProperty.call(CADRE_INVITE_REJECTION_RETRYABLE, value);
-}
-
-/** Member → device. */
-export interface CadreInviteRedeemReply {
-  accepted: boolean;
-  /** Present iff `!accepted`. */
-  code?: CadreInviteRejectionCode;
-  /** Human-facing text; present iff `!accepted`. */
-  reason?: string;
-  /** The member's party id; present iff `accepted`. */
-  partyId?: string;
-  /** The invitation row as this member holds it; present iff `accepted`. */
-  invite?: CadreInviteRow;
-  /**
-   * Dial hints for the rest of the cadre, unsigned: the member's own projection of its
-   * `CadrePeer` rows (`ControlDatabase.querySeedPeers`). `isOwner` is a dial hint only, as
-   * the seed's NOTE says; the device derives trust from its anchor, never from this.
-   */
-  peers?: SeedPeer[];
-}
-
-/** An accepting reply, every optional field present. */
-export interface CadreInviteAccepted extends CadreInviteRedeemReply {
-  accepted: true;
-  partyId: string;
-  invite: CadreInviteRow;
-  peers: SeedPeer[];
-}
-
-/** A refusal as the member sends it: a code, a reason, nothing else. */
-interface CadreInviteRejection extends CadreInviteRedeemReply {
-  accepted: false;
-  code: CadreInviteRejectionCode;
-  reason: string;
-}
-
-/**
- * A refusal as the device reads it: the code and reason verbatim off the wire, untyped, so
- * {@link CadreInviteRejectedError} is the one place that classifies a code this build does
- * not know (as `'unrecognized'`, retryable) rather than the decoder folding it into a code
- * it does.
- */
-interface CadreInviteRefusalFrame {
-  accepted: false;
-  code: unknown;
-  reason: unknown;
-}
-
-function rejection(code: CadreInviteRejectionCode, reason: string): CadreInviteRejection {
-  return { accepted: false, code, reason };
-}
-
-// ── Errors the device sees ───────────────────────────────────────────────────
-
-/**
- * A member answered and refused. `code` is `'unrecognized'` when the frame carried none this
- * build knows (the two machines may run different versions), and such a refusal counts as
- * retryable: trying the next address on an unknown answer is safe, giving up is not.
- */
-export class CadreInviteRejectedError extends Error {
-  readonly code: CadreInviteRejectionCode | '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(`Cadre invitation refused: ${text}`);
-    this.name = 'CadreInviteRejectedError';
-    this.code = isCadreInviteRejectionCode(code) ? code : 'unrecognized';
-    this.reason = text;
-    this.retryable = this.code === 'unrecognized' || CADRE_INVITE_REJECTION_RETRYABLE[this.code];
-  }
-}
-
-/** What one address the bundle named came to. */
-export interface CadreInviteAddressOutcome {
-  addr: string;
-  /** A dial or exchange failure, or a retryable {@link CadreInviteRejectedError}. */
-  error: Error;
-}
-
-/**
- * Every address the bundle names was tried and none accepted: each failed to dial, answered
- * malformed, or refused retryably. Always retryable; `outcomes` says what each address did.
- */
-export class CadreInviteUnreachableError extends Error {
-  readonly retryable = true;
-
-  constructor(readonly outcomes: readonly CadreInviteAddressOutcome[]) {
-    super(outcomes.length === 0
-      ? 'Cadre invitation names no dialable member'
-      : `Cadre invitation could not be redeemed at any of its ${outcomes.length} address(es): `
-        + outcomes.map((outcome) => `${outcome.addr}: ${outcome.error.message}`).join('; '));
-    this.name = 'CadreInviteUnreachableError';
-  }
-}
-
-/**
- * A member accepted but its reply does not check out: another party id, another invitation
- * key, or a row not signed by one of the pinned owner keys. Final: a machine that answers
- * like this is not a member of the cadre the invitation names, and the row it wrote (if any)
- * is in a database the device will never trust.
- */
-export class CadreInviteReplyInvalidError extends Error {
-  readonly retryable = false;
-
-  constructor(message: string) {
-    super(`Cadre invitation reply refused: ${message}`);
-    this.name = 'CadreInviteReplyInvalidError';
-  }
-}
-
-// ── Shape checks (both directions) ───────────────────────────────────────────
-
-function isBoundedString(value: unknown, max = MAX_WIRE_FIELD_LENGTH): value is string {
-  return typeof value === 'string' && value.length > 0 && value.length <= max;
-}
-
-function isEd25519KeyB64(value: unknown): value is string {
-  if (!isBoundedString(value) || !BASE64URL.test(value)) return false;
-  try {
-    requireEd25519PublicKeyB64(value, 'key');
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/** Is `value` a {@link CadreInviteRow} with every column in its stored form and bounded? */
-export function isWellFormedCadreInviteRow(value: unknown): value is CadreInviteRow {
-  if (typeof value !== 'object' || value === null) return false;
-  const row = value as Record<string, unknown>;
-  return isEd25519KeyB64(row.key)
-    && (row.peerId === null || isBoundedString(row.peerId))
-    && typeof row.grantsOwner === 'boolean'
-    && (row.expiresAt === null || isBoundedString(row.expiresAt))
-    && (row.totalUses === null || (Number.isInteger(row.totalUses) && (row.totalUses as number) >= 1))
-    && isBoundedString(row.stampId)
-    && isEd25519KeyB64(row.issuerKey)
-    && isBoundedString(row.issuerSig);
-}
-
-function isWellFormedRedeemRequest(value: unknown): value is CadreInviteRedeemRequest {
-  if (typeof value !== 'object' || value === null) return false;
-  const { v, partyId, invite, peerKey, multiaddrs, usageStampId, inviteSig, peerSig } = value as Record<string, unknown>;
-  return v === 1
-    && isBoundedString(partyId)
-    && isWellFormedCadreInviteRow(invite)
-    && isEd25519KeyB64(peerKey)
-    && Array.isArray(multiaddrs)
-    && isBoundedString(usageStampId)
-    && isBoundedString(inviteSig)
-    && isBoundedString(peerSig);
-}
-
-/**
- * Keep only parsable, distinct multiaddr strings, capped at {@link MAX_ADDRS}, order kept.
- * Applied on both sides: the member bounds what it stores on the device's row, the device
- * bounds what it merges into its peer store. A malformed entry is skipped, not fatal.
- */
-export function sanitizeAddrs(addrs: unknown): string[] {
-  if (!Array.isArray(addrs)) return [];
-  const out: string[] = [];
-  const seen = new Set<string>();
-  for (const entry of addrs) {
-    if (out.length >= MAX_ADDRS) break;
-    if (!isBoundedString(entry) || seen.has(entry)) continue;
-    try {
-      multiaddr(entry);
-    } catch (error) {
-      log('addrs: skipping unparsable entry: %o', error);
-      continue;
-    }
-    seen.add(entry);
-    out.push(entry);
-  }
-  return out;
-}
-
-/** The reply's peer list, bounded and each entry's addresses sanitized; anything else dropped. */
-function sanitizePeers(peers: unknown): SeedPeer[] {
-  if (!Array.isArray(peers)) return [];
-  const out: SeedPeer[] = [];
-  for (const entry of peers) {
-    if (out.length >= MAX_REPLY_PEERS) break;
-    if (typeof entry !== 'object' || entry === null) continue;
-    const { peerId, multiaddrs, isOwner, publicKey } = entry as Record<string, unknown>;
-    if (!isBoundedString(peerId)) continue;
-    out.push({
-      peerId,
-      multiaddrs: sanitizeAddrs(multiaddrs),
-      isOwner: isOwner === true,
-      ...(isEd25519KeyB64(publicKey) ? { publicKey } : {})
-    });
-  }
-  return out;
-}
-
-/**
- * Read a reply frame into a typed reply, sanitizing the attacker-influenced fields of an
- * acceptance. A refusal keeps only its code and reason, as sent. Throws on a frame that is
- * neither.
- */
-function decodeReply(value: unknown): CadreInviteAccepted | CadreInviteRefusalFrame {
-  if (typeof value !== 'object' || value === null) {
-    throw new Error('Cadre invitation reply is not an object');
-  }
-  const reply = value as Record<string, unknown>;
-  if (reply.accepted !== true) {
-    return { accepted: false, code: reply.code, reason: reply.reason };
-  }
-  if (!isBoundedString(reply.partyId) || !isWellFormedCadreInviteRow(reply.invite)) {
-    throw new Error('Cadre invitation acceptance is missing its party id or a well-formed row');
-  }
-  return { accepted: true, partyId: reply.partyId, invite: reply.invite, peers: sanitizePeers(reply.peers) };
-}
-
-// ── Request construction (device side) ───────────────────────────────────────
-
-/** What the device signs with: its identity keypair in the crypto plugin's base64url form. */
-export interface RedeemSigner {
-  /** The device's ed25519 public key, base64url — the key behind its peer id. */
-  peerKey: string;
-  /** The device's ed25519 seed, base64url. */
-  peerPrivateKey: string;
-}
-
-/**
- * Build and sign the request for `invitation`: the holder's `'redeem'` signature with the
- * invitation's private key and the device's `'consent'` signature with its own, both over
- * (invitation key, `usageStampId`, device key) for the invitation's party. The same bytes
- * the schema verifies at the member (`cadreInviteRedeemMessage` / `cadreInviteConsentMessage`),
- * whose own `party_id()` must therefore be the party the bundle names.
- */
-export function signRedeemRequest(
-  invitation: CadreInvitation,
-  signer: RedeemSigner,
-  usageStampId: string,
-  multiaddrs: string[]
-): CadreInviteRedeemRequest {
-  const fields = { inviteKey: invitation.invite.key, usageStampId, peerKey: signer.peerKey };
-  const signB64 = (message: Uint8Array, privateKey: string): string =>
-    sign(message, privateKey, 'ed25519', 'bytes', 'base64url', 'base64url') as string;
-  return {
-    v: 1,
-    partyId: invitation.partyId,
-    invite: invitation.invite,
-    peerKey: signer.peerKey,
-    multiaddrs: sanitizeAddrs(multiaddrs),
-    usageStampId,
-    inviteSig: signB64(cadreInviteRedeemMessage(invitation.partyId, fields), invitation.invitePrivateKey),
-    peerSig: signB64(cadreInviteConsentMessage(invitation.partyId, fields), signer.peerPrivateKey)
-  };
-}
-
-/**
- * The device's check on an acceptance: the same party, the same invitation key, and a row
- * signed by an issuer the device pinned from the bundle. Throws
- * {@link CadreInviteReplyInvalidError} naming the first failure.
- *
- * What it proves is bounded: the request already carried the owner-signed row, so a machine
- * that is not a member can echo it. The check catches a reply for another party or
- * invitation and a row the pinned owners never signed; whether the answering machine is a
- * member is settled afterwards, when the device syncs the control database and judges every
- * row against its anchor (`CadreNode.listAuthorizedMembers`).
- */
-export function verifyRedeemReply(
-  reply: CadreInviteAccepted,
-  invitation: CadreInvitation,
-  isTrustedIssuer: (ownerKey: string) => boolean
-): void {
-  if (reply.partyId !== invitation.partyId) {
-    throw new CadreInviteReplyInvalidError(`the member serves party ${reply.partyId}, the invitation names ${invitation.partyId}`);
-  }
-  if (reply.invite.key !== invitation.invite.key) {
-    throw new CadreInviteReplyInvalidError('the member answered for a different invitation');
-  }
-  if (!isTrustedIssuer(reply.invite.issuerKey)) {
-    throw new CadreInviteReplyInvalidError('the row the member holds is not issued by one of the invitation\'s owner keys');
-  }
-  if (!verifyCadreInviteRow(invitation.partyId, reply.invite)) {
-    throw new CadreInviteReplyInvalidError('the row the member holds is not signed by its issuer');
-  }
-}
-
-// ── Member side (handler) ────────────────────────────────────────────────────
-
-/** The control-database surface a redemption needs; a `ControlDatabase` satisfies it. */
-export type CadreInviteStore = Pick<ControlDatabase, 'seatCadreInvite' | 'isCadreInviteLive' | 'redeemCadreInvite' | 'querySeedPeers'>;
-
-export interface CadreInviteHandlerOptions {
-  /** This member's party id; a request for another party is refused by name. */
-  partyId: string;
-  store: CadreInviteStore;
-  /**
-   * Push this member's control store to the device, resolving once the push has finished, and
-   * keep the device counted in this member's control write cohort until the returned release
-   * is called. Called after the request verified and before the row is seated and the
-   * admission is written; the handler releases once both have settled. Absent, the writes go
-   * ahead with the device neither caught up nor in the cohort, so it does not hold them; see
-   * `admitDeviceIfLive`.
-   */
-  admitDevice?: (peerId: string) => Promise<() => void>;
-  /** Time to wait for the request frame; default {@link DEFAULT_REDEEM_READ_TIMEOUT_MS}. */
-  redeemReadTimeoutMs?: number;
-  /** Cap on concurrent inbound redemptions; default {@link DEFAULT_MAX_CONCURRENT_REDEMPTIONS}. */
-  maxConcurrentRedemptions?: number;
-}
-
-/** Constraint names the schema refuses a redemption with, and the code each maps to. */
-const REDEEM_CONSTRAINT_CODES: ReadonlyArray<[RegExp, CadreInviteRejectionCode, string]> = [
-  [/CHECK constraint failed: Authorized\b/, 'invite-spent', 'The invitation is expired, withdrawn, exhausted, or its issuer is no longer an owner'],
-  [/CHECK constraint failed: (InvitePossessed|PeerConsented|PeerExists|OwnerExists)\b/, 'invite-invalid', 'The redemption does not satisfy the invitation'],
-  [/CHECK constraint failed: NotRevoked\b/, 'invite-spent', 'The invitation was withdrawn'],
-];
-
-/** Which named constraint, if any, refused the write — read off the error's cause chain. */
-function constraintRejection(error: unknown): CadreInviteRejection | null {
-  if (!(error instanceof Error)) return null;
-  const messages = chainMessages(error);
-  for (const [pattern, code, reason] of REDEEM_CONSTRAINT_CODES) {
-    if (messages.some((message) => pattern.test(message))) return rejection(code, reason);
-  }
-  return null;
-}
-
-/** A write failure that is not a refusal: the retry gave up (`conflict`), or something else (`internal`). */
-function writeFailureRejection(error: unknown): CadreInviteRejection {
-  // NOTE: a seat torn on a member alone with an uncaught-up device was measured answering
-  // `internal`, not `conflict` (cadre-invite-redeemed-at-a-member-without-the-row). Both are
-  // retryable, so the device is unaffected; if the two codes ever diverge in retryability,
-  // find which tear `isRetriableControlWriteFailure` does not recognise.
-  return isRetriableControlWriteFailure(error)
-    ? rejection('conflict', 'The redemption write failed transiently; nothing was recorded')
-    : rejection('internal', 'Internal redemption error');
-}
-
-/**
- * Member side: registers the handler and drives each inbound stream through the checks in
- * cost order — shape, connecting identity, both signatures, target device — so no database
- * work happens for a stranger that cannot prove anything, then admits the device to this
- * member's control replication (`admitDevice`), seats the row and redeems.
- * Hardened as the seed handler is: a concurrency cap (over it, `busy`) and a read timeout.
- *
- * Registered only by a started `CadreNode`, after its control database is up, like the
- * formation responder; nothing here is reachable on a node without one.
- */
-export class CadreInviteHandler {
-  private readonly options: CadreInviteHandlerOptions;
-  private readonly readTimeoutMs: number;
-  private readonly maxConcurrent: number;
-  private readonly registered = new Set<Libp2p>();
-  private active = 0;
-
-  constructor(options: CadreInviteHandlerOptions) {
-    this.options = options;
-    this.readTimeoutMs = options.redeemReadTimeoutMs ?? DEFAULT_REDEEM_READ_TIMEOUT_MS;
-    this.maxConcurrent = options.maxConcurrentRedemptions ?? DEFAULT_MAX_CONCURRENT_REDEMPTIONS;
-  }
-
-  /** In-flight inbound redemptions. */
-  get activeCount(): number {
-    return this.active;
-  }
-
-  /**
-   * Register on `node`; rejects when libp2p refuses the registration. `runOnLimitedConnection`
-   * because a phone redeems through a relay, whose connection libp2p marks limited; the
-   * exchange is two small frames, well inside any relay's cap.
-   */
-  async register(node: Libp2p, protocolId: string = CADRE_INVITE_PROTOCOL): Promise<void> {
-    if (this.registered.has(node)) return;
-    await node.handle(protocolId, async (rawStream: unknown, rawConnection: unknown) => {
-      await this.handleStream(rawStream as ControlStream, (rawConnection as Connection).remotePeer.toString());
-    }, { runOnLimitedConnection: true });
-    this.registered.add(node);
-    log('cadre invitation handler registered (%s)', protocolId);
-  }
-
-  async unregister(node: Libp2p, protocolId: string = CADRE_INVITE_PROTOCOL): Promise<void> {
-    if (!this.registered.has(node)) return;
-    await node.unhandle(protocolId);
-    this.registered.delete(node);
-    log('cadre invitation handler unregistered (%s)', protocolId);
-  }
-
-  /**
-   * One inbound redemption: read the frame, decide, reply, close. Public as the seam the
-   * protocol spec drives directly; `remotePeerId` is the connection's authenticated peer.
-   */
-  async handleStream(stream: ControlStream, remotePeerId: string): Promise<void> {
-    if (this.active >= this.maxConcurrent) {
-      log('refusing redemption from %s: %d in flight at cap %d', remotePeerId, this.active, this.maxConcurrent);
-      await replyAndClose(stream, rejection('busy', 'Too many concurrent redemptions'), 'Cadre invite');
-      return;
-    }
-    this.active++;
-    try {
-      const reply = await this.decide(stream, remotePeerId);
-      log('redemption from %s: %s', remotePeerId, reply.accepted ? 'accepted' : `refused (${reply.code})`);
-      await replyAndClose(stream, reply, 'Cadre invite');
-    } catch (error) {
-      log('redemption from %s failed: %o', remotePeerId, error);
-      await replyAndClose(stream, rejection('internal', 'Internal redemption error'), 'Cadre invite');
-    } finally {
-      this.active--;
-    }
-  }
-
-  /**
-   * Read the request frame to EOF, bounded and size-capped; JSON only, shape is `decide`'s.
-   * Throws on a frame that cannot be read, which {@link handleStream} answers `internal`:
-   * a read timeout or a cut frame proves nothing about the invitation, so the device must
-   * stay free to try the next address.
-   */
-  private async readRequest(stream: ControlStream): Promise<unknown> {
-    const data = await readStreamToEnd(stream, { maxBytes: MAX_CADRE_INVITE_MSG_SIZE, timeoutMs: this.readTimeoutMs, label: 'Cadre invite' });
-    return JSON.parse(new TextDecoder().decode(decodeLengthPrefixedFrame(data, MAX_CADRE_INVITE_MSG_SIZE)));
-  }
-
-  private async decide(stream: ControlStream, remotePeerId: string): Promise<CadreInviteRedeemReply> {
-    const request = await this.readRequest(stream);
-    const refused = this.checkRequest(request, remotePeerId);
-    if (refused) return refused;
-    return await this.seatAndRedeem(request as CadreInviteRedeemRequest, remotePeerId);
-  }
-
-  /**
-   * The checks that cost no database work, in order: shape, party, connecting identity (an
-   * ed25519 peer id is an identity multihash of the very key, and this is the only layer that
-   * can check the pair), both signatures, and a targeted invitation's device.
-   */
-  private checkRequest(request: unknown, remotePeerId: string): CadreInviteRejection | null {
-    if (!isWellFormedRedeemRequest(request)) {
-      return rejection('invite-invalid', 'Malformed redemption request');
-    }
-    if (request.partyId !== this.options.partyId) {
-      return rejection('party-mismatch', 'This machine serves another cadre');
-    }
-    if (ed25519PublicKeyB64FromPeerId(remotePeerId) !== request.peerKey) {
-      return rejection('invite-invalid', 'The peer key is not the connecting identity');
-    }
-    const fields = { inviteKey: request.invite.key, usageStampId: request.usageStampId, peerKey: request.peerKey };
-    if (!verifyCadreInviteRedemption(this.options.partyId, fields, request.inviteSig, request.peerSig)) {
-      return rejection('invite-invalid', 'The redemption signatures do not verify');
-    }
-    if (request.invite.peerId !== null && request.invite.peerId !== remotePeerId) {
-      return rejection('invite-invalid', 'The invitation names another device');
-    }
-    return null;
-  }
-
-  /**
-   * Admit the device to this member's control replication (see {@link admitDeviceIfLive}),
-   * seat the row from the bundle (its own transaction; a no-op when held), then redeem. The
-   * admission comes first because the seat is already a write the device takes part in. An
-   * issuer this member does not know as an owner is the one retryable refusal left: the device
-   * tries the next address, which may hold the issuer's row.
-   */
-  private async seatAndRedeem(request: CadreInviteRedeemRequest, remotePeerId: string): Promise<CadreInviteRedeemReply> {
-    const release = await this.admitDeviceIfLive(request.invite, remotePeerId);
-    try {
-      return await this.seatAndRedeemAdmitted(request, remotePeerId);
-    } finally {
-      release();
-    }
-  }
-
-  /** {@link seatAndRedeem}'s two writes, each answered by name when it fails. */
-  private async seatAndRedeemAdmitted(request: CadreInviteRedeemRequest, remotePeerId: string): Promise<CadreInviteRedeemReply> {
-    const { store } = this.options;
-    try {
-      await store.seatCadreInvite(request.invite);
-    } catch (error) {
-      if (error instanceof CadreInviteIssuerUnknownError) {
-        return rejection('issuer-unknown', 'The invitation\'s issuer is not known as an owner here');
-      }
-      log('seating invitation %s from %s failed: %o', request.invite.key, remotePeerId, error);
-      return constraintRejection(error) ?? writeFailureRejection(error);
-    }
-    try {
-      const result = await store.redeemCadreInvite({
-        inviteKey: request.invite.key,
-        peerId: remotePeerId,
-        peerKey: request.peerKey,
-        multiaddrs: sanitizeAddrs(request.multiaddrs),
-        usageStampId: request.usageStampId,
-        inviteSig: request.inviteSig,
-        peerSig: request.peerSig
-      });
-      log('invitation %s redeemed by %s (alreadyMember=%s)', request.invite.key, remotePeerId, result.alreadyMember);
-    } catch (error) {
-      if (error instanceof InvitationExhaustedError) {
-        return rejection('invite-spent', 'The invitation has no uses left');
-      }
-      log('redeeming invitation %s for %s failed: %o', request.invite.key, remotePeerId, error);
-      return constraintRejection(error) ?? writeFailureRejection(error);
-    }
-    // The row as held: the seat inserted this copy verbatim, or found the same row (its key
-    // is the primary key and every column is under the issuer's signature).
-    return { accepted: true, partyId: this.options.partyId, invite: request.invite, peers: await this.peersBestEffort() };
-  }
-
-  /**
-   * Admit the device to this member's control replication before the first write of the
-   * exchange (the seat, when this member does not hold the row; otherwise the admission), and
-   * resolve to the release that ends the admission. The device is not a member until the
-   * admission is written, so only this puts it in this member's control write cohort, and it
-   * must be there to hold the rows that admit it. It is pushed the control store first,
-   * because a cohort node with no base revision of a block refuses a commit to it; a member
-   * alone with the device would then have half its cohort refusing, and the write would tear
-   * instead of committing.
-   *
-   * Only for an invitation still live here, judged on the row this member holds or, before
-   * the seat, on the bundle's copy once its issuer signature verifies
-   * (`ControlDatabase.isCadreInviteLive`): the holder of a withdrawn, expired or spent one,
-   * or of a forged copy naming a real owner, is refused without being sent anything. The
-   * retry of an admission already written can read as spent too and is sent nothing; it
-   * needs nothing, since the device is a member and the ordinary catch-up reaches it.
-   * Best-effort: a failed check or push is logged and the writes go ahead without the device
-   * admitted, then commit or are answered retryably.
-   */
-  private async admitDeviceIfLive(invite: CadreInviteRow, remotePeerId: string): Promise<() => void> {
-    const { admitDevice, store } = this.options;
-    const notAdmitted = (): void => undefined;
-    if (!admitDevice) return notAdmitted;
-    try {
-      if (!await store.isCadreInviteLive(invite)) {
-        log('invitation %s is not live here; %s is not admitted before the write', invite.key, remotePeerId);
-        return notAdmitted;
-      }
-      // NOTE: accepted tradeoff — when a write then fails (the seat refused, the last use
-      // taken by a race, the row expiring between this check and the write), the device keeps
-      // a copy of a control store it was not admitted to. It holds a live owner-signed
-      // invitation and proved possession and consent, and a seed hands an un-enrolled machine
-      // the same information. Revisit if a control table ever carries data a non-member must not see.
-      return await admitDevice(remotePeerId);
-    } catch (error) {
-      log('admitting %s before its admission write failed (writing anyway): %o', remotePeerId, error);
-      return notAdmitted;
-    }
-  }
-
-  /** Dial hints are an optimization; a failed read costs the device its hints, not its membership. */
-  private async peersBestEffort(): Promise<SeedPeer[]> {
-    try {
-      return await this.options.store.querySeedPeers();
-    } catch (error) {
-      log('peer projection for the reply failed (continuing without hints): %o', error);
-      return [];
-    }
-  }
-}
-
-// ── Device side (dialer) ─────────────────────────────────────────────────────
-
-export interface RedeemAtMembersOptions {
-  /** The bundle: its `members` are dialed in order. */
-  invitation: CadreInvitation;
-  /** The signed request ({@link signRedeemRequest}); the same one goes to every address. */
-  request: CadreInviteRedeemRequest;
-  /** Is this owner key one the device pinned from the bundle? The reply check's input. */
-  isTrustedIssuer: (ownerKey: string) => boolean;
-  /**
-   * This machine's declared link round trip (`NetworkConfig.linkRoundTripMs`), from which
-   * the per-address deadline derives: a dial that may need a relay plus one request
-   * (`relayedRequestBudgetMs`, 28.5 s at the default declaration), as seed delivery's is.
-   */
-  linkRoundTripMs?: number;
-  /** Per-address deadline override; default derived from `linkRoundTripMs`. */
-  addressBudgetMs?: number;
-  protocolId?: string;
-  /** Cancels the dial or stream in flight and ends the pass; the call throws the signal's reason. */
-  signal?: AbortSignal;
-}
-
-/** What a successful redemption yields the device. */
-export interface CadreInviteRedemption {
-  reply: CadreInviteAccepted;
-  /** The answering member's peer id, from the address's trailing `/p2p/`; null when it named none. */
-  memberPeerId: string | null;
-  /** The address that answered. */
-  memberAddr: string;
-}
-
-/**
- * Dial `addr`, open one stream to it, send the request, half-close, read the one reply frame.
- * `signal` is the per-address deadline: it cancels the dial and resets a live stream.
- *
- * The address is dialed outside libp2p's dial queue (`dialAddr`), so another dial of the
- * member in flight cannot capture this attempt; an open connection is still reused.
- */
-async function exchangeRedemption(
-  node: Libp2p,
-  addr: Multiaddr,
-  request: CadreInviteRedeemRequest,
-  signal: AbortSignal,
-  budgetMs: number,
-  protocolId: string
-): Promise<CadreInviteAccepted | CadreInviteRefusalFrame> {
-  const connection = await dialAddr(node, addr, signal, 'Cadre invitation redemption');
-  // `runOnLimitedConnection`: a member may be reachable only through a relay (see `register`).
-  const rawStream = await connection.newStream(protocolId, { runOnLimitedConnection: true, signal });
-  return await exchangeFrame(
-    rawStream as unknown as ControlStream,
-    signal,
-    request,
-    async (stream) => {
-      const data = await readStreamToEnd(stream, { maxBytes: MAX_CADRE_INVITE_MSG_SIZE, timeoutMs: budgetMs, label: 'Cadre invite reply' });
-      return decodeReply(JSON.parse(new TextDecoder().decode(decodeLengthPrefixedFrame(data, MAX_CADRE_INVITE_MSG_SIZE))));
-    },
-    'Cadre invitation redemption aborted by its deadline'
-  );
-}
-
-function asError(error: unknown): Error {
-  if (error instanceof Error) return error;
-  // A WebSocket transport rejects a refused dial with an `ErrorEvent`, whose text is its `message`.
-  const message = (error as { message?: unknown } | null)?.message;
-  return new Error(typeof message === 'string' && message.length > 0 ? message : String(error), { cause: error });
-}
-
-/**
- * Run `op` with a signal that aborts when either `deadline` or the caller's `signal` does.
- * Relayed by hand rather than with `AbortSignal.any`, which the phone runtimes lack.
- */
-async function underDeadlineAndCaller<T>(
-  deadline: AbortSignal,
-  caller: AbortSignal | undefined,
-  op: (signal: AbortSignal) => Promise<T>
-): Promise<T> {
-  if (!caller) return await op(deadline);
-  const either = new AbortController();
-  const abort = (): void => either.abort();
-  deadline.addEventListener('abort', abort, { once: true });
-  caller.addEventListener('abort', abort, { once: true });
-  // An abort between the caller's last check and the listener above fired no event.
-  if (caller.aborted) abort();
-  try {
-    return await op(either.signal);
-  } finally {
-    deadline.removeEventListener('abort', abort);
-    caller.removeEventListener('abort', abort);
-  }
-}
-
-/**
- * Device side: try the bundle's addresses one at a time, each under its own deadline, and
- * stop at the first acceptance or the first final refusal. A dial failure, a malformed
- * reply or a retryable refusal moves to the next address.
- *
- * Every address gets the SAME request, with one `usageStampId`: `CadreInviteUsage` is keyed
- * by it, so a member the device gave up on that was still committing cannot admit it twice,
- * and a retry at the next member after a dropped reply is answered as already a member.
- *
- * @throws {CadreInviteRejectedError} on a final refusal (its `retryable` is false).
- * @throws {CadreInviteReplyInvalidError} on an acceptance that fails {@link verifyRedeemReply}.
- * @throws {CadreInviteUnreachableError} when every address was tried and none accepted.
- * @throws the reason of `options.signal` once it aborts.
- */
-export async function redeemAtMembers(node: Libp2p, options: RedeemAtMembersOptions): Promise<CadreInviteRedemption> {
-  const protocolId = options.protocolId ?? CADRE_INVITE_PROTOCOL;
-  const budgetMs = options.addressBudgetMs ?? relayedRequestBudgetMs(options.linkRoundTripMs);
-  const outcomes: CadreInviteAddressOutcome[] = [];
-  for (const addr of options.invitation.members) {
-    options.signal?.throwIfAborted();
-    // Between attempts: a relayed address's relay leg goes through libp2p's dial queue, which
-    // needs a macrotask to drop an aborted job (see `tryAddrsInTurn`).
-    if (outcomes.length > 0) await nextMacrotask();
-    let parsed: Multiaddr;
-    try {
-      parsed = multiaddr(addr);
-    } catch (error) {
-      outcomes.push({ addr, error: new Error('not a multiaddr', { cause: error }) });
-      continue;
-    }
-    try {
-      const reply = await withDeadline(budgetMs, `Cadre invitation redemption via ${addr}`,
-        (deadline) => underDeadlineAndCaller(deadline, options.signal,
-          (signal) => exchangeRedemption(node, parsed, options.request, signal, budgetMs, protocolId)));
-      if (!reply.accepted) {
-        const refusal = new CadreInviteRejectedError(reply.code, reply.reason);
-        if (!refusal.retryable) throw refusal;
-        log('redemption via %s refused retryably (%s); trying the next address', addr, refusal.code);
-        outcomes.push({ addr, error: refusal });
-        continue;
-      }
-      verifyRedeemReply(reply, options.invitation, options.isTrustedIssuer);
-      return { reply, memberPeerId: trailingPeerId(parsed), memberAddr: addr };
-    } catch (error) {
-      if (error instanceof CadreInviteRejectedError || error instanceof CadreInviteReplyInvalidError) throw error;
-      // The caller's abort cut this attempt short; its reason, not the cut, is the answer.
-      options.signal?.throwIfAborted();
-      log('redemption via %s failed before an answer (%s); trying the next address', addr, asError(error).message);
-      outcomes.push({ addr, error: asError(error) });
-    }
-  }
-  throw new CadreInviteUnreachableError(outcomes);
-}
-
-/** Pause after the first pass in which no member accepted; doubled after each further one. */
-const REDEEM_PASS_FIRST_PAUSE_MS = 5_000;
-
-/** Longest pause between passes. */
-const REDEEM_PASS_MAX_PAUSE_MS = 60_000;
-
-export interface RedeemInPassesOptions extends RedeemAtMembersOptions {
-  /** Keep making passes while every answer is retryable; false makes exactly one. */
-  waitForMember: boolean;
-  /** Called at each pass and each pause; an exception it throws is logged and ignored. */
-  onProgress?: (progress: CadreJoinProgress) => void;
-}
-
-/**
- * Device side, in passes: one {@link redeemAtMembers} pass over the bundle's addresses, or,
- * with `waitForMember`, as many as it takes, pausing between them (5 s after the first,
- * doubling to 60 s, never past the invitation's expiry). Every pass sends the same signed
- * request, so a member that admitted the device on a pass whose reply was lost answers a later
- * pass as already a member, with no second usage row.
- *
- * A wait ends at the first acceptance, at a final refusal or an invalid reply (thrown as
- * {@link redeemAtMembers} throws them), when the invitation expires by this device's clock
- * (thrown as the `invite-spent` refusal a member would give), when `signal` aborts (its reason
- * thrown), and when `node` stops. A bundle that names no address has nothing to wait for and
- * throws at once.
- */
-export async function redeemInPasses(node: Libp2p, options: RedeemInPassesOptions): Promise<CadreInviteRedemption> {
-  for (let pass = 1; ; pass++) {
-    if (options.waitForMember) {
-      // One pass leaves expiry to the member, whose clock decides; a wait has nothing else to end it.
-      refuseIfExpired(options.invitation.invite);
-      refuseIfStopped(node);
-    }
-    reportProgress(options.onProgress, { state: 'redeeming', pass });
-    try {
-      return await redeemAtMembers(node, options);
-    } catch (error) {
-      if (!options.waitForMember || !(error instanceof CadreInviteUnreachableError) || error.outcomes.length === 0) throw error;
-      const pauseMs = pauseAfterPass(pass, options.invitation.invite);
-      reportProgress(options.onProgress, {
-        state: 'waiting', pass, retryAtMs: Date.now() + pauseMs, reason: waitReason(error.outcomes), outcomes: error.outcomes
-      });
-      log('redemption pass %d found no member ready; the next pass in %d ms', pass, pauseMs);
-      await pause(pauseMs, options.signal, node);
-    }
-  }
-}
-
-// NOTE: judged by this device's clock, so one running ahead ends a wait before the members
-// would refuse it. If waits are seen ending early on skewed phones, allow a grace margin here.
-function refuseIfExpired(invite: CadreInviteRow): void {
-  const expiresAtMs = parseNullableStoredDatetimeMs(invite.expiresAt);
-  if (expiresAtMs !== null && expiresAtMs <= Date.now()) {
-    throw new CadreInviteRejectedError('invite-spent', 'the invitation expired before a member accepted it');
-  }
-}
-
-/** A stopped node's every dial fails at once, which would otherwise read as "no member answered" until expiry. */
-function refuseIfStopped(node: Libp2p): void {
-  if (node.status !== 'started') {
-    throw new Error(`Cadre invitation redemption stopped waiting: the node is ${node.status}`);
-  }
-}
-
-/** The pause after pass `pass`, cut short at the invitation's expiry so the next check ends the wait then. */
-function pauseAfterPass(pass: number, invite: CadreInviteRow): number {
-  const backoffMs = Math.min(REDEEM_PASS_FIRST_PAUSE_MS * 2 ** (pass - 1), REDEEM_PASS_MAX_PAUSE_MS);
-  const expiresAtMs = parseNullableStoredDatetimeMs(invite.expiresAt);
-  return expiresAtMs === null ? backoffMs : Math.max(0, Math.min(backoffMs, expiresAtMs - Date.now()));
-}
-
-/** Any refusal means a member answered and is not ready yet; otherwise none answered at all. */
-function waitReason(outcomes: readonly CadreInviteAddressOutcome[]): 'no-member-answered' | 'member-not-ready' {
-  return outcomes.some((outcome) => outcome.error instanceof CadreInviteRejectedError) ? 'member-not-ready' : 'no-member-answered';
-}
-
-/** A UI callback must not break the join. */
-function reportProgress(onProgress: ((progress: CadreJoinProgress) => void) | undefined, progress: CadreJoinProgress): void {
-  if (!onProgress) return;
-  try {
-    onProgress(progress);
-  } catch (error) {
-    log('redemption progress callback threw (ignored): %o', error);
-  }
-}
-
-/**
- * Wait `ms`, or reject with `signal`'s reason as soon as it aborts. Ends early, resolving, when
- * `node` stops (or is already stopped), so the next pass's stop check ends the wait without a
- * timer holding the process open. Listeners and timer are cleared however it ends.
- */
-function pause(ms: number, signal: AbortSignal | undefined, node: Libp2p): Promise<void> {
-  return new Promise((resolve, reject) => {
-    if (signal?.aborted) {
-      reject(signal.reason);
-      return;
-    }
-    if (node.status !== 'started') {
-      resolve();
-      return;
-    }
-    const settle = (): void => {
-      clearTimeout(timer);
-      signal?.removeEventListener('abort', onAbort);
-      node.removeEventListener('stop', onStop);
-    };
-    const onAbort = (): void => {
-      settle();
-      reject(signal!.reason);
-    };
-    const onStop = (): void => {
-      settle();
-      resolve();
-    };
-    const timer = setTimeout(onStop, ms);
-    signal?.addEventListener('abort', onAbort, { once: true });
-    node.addEventListener('stop', onStop, { once: true });
-  });
-}
+/**
+ * Cadre invitation redemption transport: `/sereus/cadre-invite/1.0.0`.
+ *
+ * A device holding a cadre invitation (an owner-signed `CadreInvite` row plus the private
+ * half of the invitation keypair, see {@link CadreInvitation}) dials ANY member machine the
+ * invitation names and proves possession; the member seats the row if it does not hold it
+ * yet, writes the device's `CadrePeer` row (and `OwnerKey` row, when the invitation grants
+ * ownership) through `ControlDatabase.redeemCadreInvite`, and answers with the party id,
+ * the row and dial hints. The owner that minted the invitation need not be online.
+ *
+ * The exchange shape — one frame each way, the member's hardening and admission of the
+ * device, the device's address-by-address dialing in passes — is `member-redemption.ts`'s,
+ * shared with the owner-grant protocol; this module supplies the invitation's bundle, request,
+ * checks, writes and refusal codes. Stranger-facing by design — the device is not a member
+ * when it dials — so the connection gate admits a stranger while a live invitation exists
+ * (`membership-connection-gater.ts`), and the handler's own trust decision is the proof of
+ * possession: nothing touches the database for a caller that cannot prove it holds the
+ * invitation and is the identity it names.
+ *
+ * The seed protocol is left untouched so `SeedMessage` can grow independently.
+ */
+
+import debug from 'debug';
+import { multiaddr } from '@multiformats/multiaddr';
+import type { Libp2p } from '@libp2p/interface';
+import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } from 'uint8arrays';
+import { sign } from '@optimystic/quereus-plugin-crypto';
+import {
+  cadreInviteRedeemMessage,
+  cadreInviteConsentMessage,
+  CadreInviteIssuerUnknownError,
+  InvitationExhaustedError,
+  type ControlDatabase
+} from './control-database.js';
+import { verifyCadreInviteRow, verifyCadreInviteRedemption } from './peer-authorization.js';
+import { verifyPeerRecordSignature } from './peer-record.js';
+import { ed25519PublicKeyB64FromPeerId } from './ed25519-key.js';
+import { CADRE_INVITATION_PREFIX, CADRE_JOIN_REQUEST_PREFIX, OWNER_GRANT_PREFIX, OWNER_KEY_EXPORT_STEM } from './cadre-join-request.js';
+import {
+  MemberRedemptionHandler,
+  constraintRefusal,
+  dialRedemption,
+  dialRedemptionInPasses,
+  isBoundedString,
+  isEd25519KeyB64,
+  isNullableBoundedString,
+  isNullableUseCap,
+  rejection,
+  writeFailureRefusal,
+  type ConstraintRefusalRow,
+  type MemberRedemption,
+  type MemberRedemptionHandlerOptions,
+  type MemberRedemptionOptions,
+  type MemberRedemptionPassOptions,
+  type RedemptionAddressOutcome,
+  type RedemptionRejection
+} from './member-redemption.js';
+import type { CadreInviteRow, CadreJoinProgress, PeerAddressRecord, SeedPeer } from './types.js';
+
+const log = debug('sereus:cadre:invite-proto');
+
+/** Protocol id for cadre invitation redemption (parallel to `/sereus/seed/1.0.0`). */
+export const CADRE_INVITE_PROTOCOL = '/sereus/cadre-invite/1.0.0';
+
+/** What the dialer calls the credential in log lines, deadline labels and error text. */
+const LABEL = 'Cadre invitation';
+
+/** Most addresses a request may carry for the device, and a reply per peer (`sanitizeAddrs`). */
+const MAX_ADDRS = 16;
+
+/** Most machines an invitation bundle may name; the issuer caps its own list far below this. */
+const MAX_BUNDLE_MEMBERS = 64;
+
+/** Most peers a reply may carry as dial hints. */
+const MAX_REPLY_PEERS = 256;
+
+// ── The invitation bundle ────────────────────────────────────────────────────
+
+/**
+ * What an owner hands out (QR, paste, link) and a device redeems. An invitation is an
+ * ed25519 keypair: the row holds the public half, `invitePrivateKey` is the proof of
+ * possession, and whoever holds this bundle can redeem it — treat it as a bearer
+ * credential for the row's lifetime. It admits a machine and grants nothing else; an owner
+ * grant (`owner-grant-protocol.ts`) is the credential that makes a key an owner.
+ *
+ * Carrying the signed row is what makes redemption work at a member that has not received
+ * the row by replication: the member seats it from the bundle under its stored issuer
+ * signature. The row's own signature covers every column, so a bundle whose row was
+ * altered cannot be seated anywhere.
+ */
+export interface CadreInvitation {
+  v: 1;
+  /** The cadre the invitation joins; a device refuses one for another party. */
+  partyId: string;
+  /** The invitation's ed25519 seed, base64url: the proof of possession. */
+  invitePrivateKey: string;
+  /** The owner-signed row exactly as issued (`ControlDatabase.insertCadreInvite`). */
+  invite: CadreInviteRow;
+  /**
+   * The issuer's anchored owner keys. The redeeming device pins them before it dials
+   * (`CadreNode.trustOwnerKeys`) and checks the member's reply against them. Sourced from
+   * the issuer's node-local anchor only, never the replicated `OwnerKey` table, for the
+   * reason the seed invite gives: the device anchors whatever arrives here.
+   */
+  ownerKeys: string[];
+  /**
+   * Multiaddrs ending in `/p2p/<peerId>`: the issuer's own first, then other members', at
+   * most `CADRE_INVITATION_MAX_ADDRS` in all (`selectCadreInvitationMembers` in
+   * `invitation-bootstrap.ts`). The device tries them in order.
+   */
+  members: string[];
+}
+
+/**
+ * Encode a bundle for out-of-band delivery: {@link CADRE_INVITATION_PREFIX}, then base64url
+ * over JSON. The prefix lets an app tell an invitation from a join request
+ * (`cadre-join-request.ts`) or an owner grant (`owner-grant-protocol.ts`) and name the mistake
+ * when one is pasted for the other.
+ */
+export function encodeCadreInvitation(invitation: CadreInvitation): string {
+  return `${CADRE_INVITATION_PREFIX}${uint8ArrayToString(new TextEncoder().encode(JSON.stringify(invitation)), 'base64url')}`;
+}
+
+/**
+ * Decode a bundle, refusing anything that is not a well-formed version-1
+ * {@link CadreInvitation} behind {@link CADRE_INVITATION_PREFIX}. Standalone so a client
+ * without a node (a settings screen that wants to show which cadre an invitation joins) can
+ * decode one.
+ *
+ * @throws on an owner key, an owner grant or a join request, a string without the prefix or
+ *   that is not base64url JSON after it, or one that decodes to another shape or version.
+ */
+export function decodeCadreInvitation(encoded: string): CadreInvitation {
+  const trimmed = encoded.trim();
+  if (trimmed.startsWith(OWNER_KEY_EXPORT_STEM)) {
+    throw new Error('This is an owner key, not a cadre invitation; it is private, so import it only where the app asks for an owner key');
+  }
+  if (trimmed.startsWith(OWNER_GRANT_PREFIX)) {
+    throw new Error('This is an owner grant, not a cadre invitation; paste it where the app asks for an owner grant');
+  }
+  if (trimmed.startsWith(CADRE_JOIN_REQUEST_PREFIX)) {
+    throw new Error('This is a join request, not a cadre invitation; paste it into the app that manages your cadre');
+  }
+  if (!trimmed.startsWith(CADRE_INVITATION_PREFIX)) {
+    throw new Error(`Cadre invitation must start with "${CADRE_INVITATION_PREFIX}" (this one starts with "${trimmed.slice(0, CADRE_INVITATION_PREFIX.length)}")`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(new TextDecoder().decode(uint8ArrayFromString(trimmed.slice(CADRE_INVITATION_PREFIX.length), 'base64url')));
+  } catch (error) {
+    throw new Error('Cadre invitation does not decode as base64url JSON', { cause: error });
+  }
+  if (!isWellFormedCadreInvitation(parsed)) {
+    throw new Error('Cadre invitation is malformed or of an unsupported version');
+  }
+  return parsed;
+}
+
+function isWellFormedCadreInvitation(value: unknown): value is CadreInvitation {
+  if (typeof value !== 'object' || value === null) return false;
+  const { v, partyId, invitePrivateKey, invite, ownerKeys, members } = value as Record<string, unknown>;
+  return v === 1
+    && isBoundedString(partyId)
+    && isEd25519KeyB64(invitePrivateKey)
+    && isWellFormedCadreInviteRow(invite)
+    && Array.isArray(ownerKeys) && ownerKeys.length > 0 && ownerKeys.every((key) => isEd25519KeyB64(key))
+    && Array.isArray(members) && members.length <= MAX_BUNDLE_MEMBERS && members.every((addr) => isBoundedString(addr));
+}
+
+// ── Wire messages ────────────────────────────────────────────────────────────
+
+/**
+ * The device's own address record as a request carries it: a {@link PeerAddressRecord} without
+ * the peer id, which the connection gives, and the key, which is the request's `peerKey`.
+ */
+export type RedeemSelfRecord = Pick<PeerAddressRecord, 'addrs' | 'updatedAt' | 'profile' | 'sig'>;
+
+/** Device → member: one frame, the whole redemption. */
+export interface CadreInviteRedeemRequest {
+  v: 2;
+  /** The cadre the device believes it is joining; a machine serving another party refuses by name. */
+  partyId: string;
+  /** The owner-signed row from the bundle. */
+  invite: CadreInviteRow;
+  /** The device's ed25519 public key, base64url; must be the key behind the connecting peer id. */
+  peerKey: string;
+  /**
+   * The device's own address record for its `CadrePeer` row, self-signed for the invitation's
+   * party as `CadreNode.registerSelf` signs it (`signPeerRecord`); `addrs` is empty for a phone.
+   * The member stores `addrs` and, when the signature verifies over them, the rest of the
+   * record too ({@link admittedRecord}), so the device's first publish is its admission.
+   */
+  record: RedeemSelfRecord;
+  /** Single-use nonce the device minted (`generateStampId`); both signatures cover it. */
+  usageStampId: string;
+  /** By `invitePrivateKey` over the `'redeem'` digest. */
+  inviteSig: string;
+  /** By the device's identity key over the `'consent'` digest. */
+  peerSig: string;
+}
+
+/**
+ * Why a member refused a redemption. Retryability is {@link CADRE_INVITE_REJECTION_RETRYABLE}'s;
+ * a retryable code moves the device to the next address the bundle names.
+ */
+export type CadreInviteRejectionCode =
+  /**
+   * The issuer's `OwnerKey` row is not on this member (not replicated yet), or the issuer was
+   * removed; the member cannot tell which, so the device tries the next address.
+   */
+  | 'issuer-unknown'
+  /**
+   * A signature does not verify, the peer key is not the connecting identity, the request or
+   * the row is malformed, or the invitation names another device.
+   */
+  | 'invite-invalid'
+  /** Expired, withdrawn, exhausted, or issued by a key that is no longer an owner here. */
+  | 'invite-spent'
+  /** This machine serves another cadre than the one the invitation names. */
+  | 'party-mismatch'
+  /** The member is at its cap on concurrent redemptions. */
+  | 'busy'
+  /** The write failed transiently (the write retry gave up), or the member has not synced the invitation row the cadre holds; nothing was recorded. */
+  | 'conflict'
+  /**
+   * An unexpected member-side failure, or a request frame the member could not read (timed
+   * out, oversized, not JSON): nothing was proved either way, so the device tries the next
+   * address, as the formation responder's `internal` is read.
+   */
+  | 'internal';
+
+/** Which refusals are worth repeating at the next address — the one place that says so. */
+export const CADRE_INVITE_REJECTION_RETRYABLE: Readonly<Record<CadreInviteRejectionCode, boolean>> = {
+  'issuer-unknown': true,
+  'invite-invalid': false,
+  'invite-spent': false,
+  'party-mismatch': false,
+  'busy': 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 isCadreInviteRejectionCode(value: unknown): value is CadreInviteRejectionCode {
+  return typeof value === 'string' && Object.prototype.hasOwnProperty.call(CADRE_INVITE_REJECTION_RETRYABLE, value);
+}
+
+/** Member → device. */
+export interface CadreInviteRedeemReply {
+  accepted: boolean;
+  /** Present iff `!accepted`. */
+  code?: CadreInviteRejectionCode;
+  /** Human-facing text; present iff `!accepted`. */
+  reason?: string;
+  /** The member's party id; present iff `accepted`. */
+  partyId?: string;
+  /** The invitation row as this member holds it; present iff `accepted`. */
+  invite?: CadreInviteRow;
+  /**
+   * Dial hints for the rest of the cadre, unsigned: the member's own projection of its
+   * `CadrePeer` rows (`ControlDatabase.querySeedPeers`), the answering member and every
+   * always-on machine marked `preferred`. The device derives trust from its anchor, never
+   * from this.
+   */
+  peers?: SeedPeer[];
+}
+
+/** An accepting reply, every optional field present. */
+export interface CadreInviteAccepted extends CadreInviteRedeemReply {
+  accepted: true;
+  partyId: string;
+  invite: CadreInviteRow;
+  peers: SeedPeer[];
+}
+
+/** A refusal as the member sends it: a code, a reason, nothing else. */
+type CadreInviteRejection = RedemptionRejection<CadreInviteRejectionCode>;
+
+// ── Errors the device sees ───────────────────────────────────────────────────
+
+/**
+ * A member answered and refused. `code` is `'unrecognized'` when the frame carried none this
+ * build knows (the two machines may run different versions), and such a refusal counts as
+ * retryable: trying the next address on an unknown answer is safe, giving up is not.
+ */
+export class CadreInviteRejectedError extends Error {
+  readonly code: CadreInviteRejectionCode | '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(`Cadre invitation refused: ${text}`);
+    this.name = 'CadreInviteRejectedError';
+    this.code = isCadreInviteRejectionCode(code) ? code : 'unrecognized';
+    this.reason = text;
+    this.retryable = this.code === 'unrecognized' || CADRE_INVITE_REJECTION_RETRYABLE[this.code];
+  }
+}
+
+/** What one address the bundle named came to; the owner-grant redemption reports the same shape. */
+export type CadreInviteAddressOutcome = RedemptionAddressOutcome;
+
+/**
+ * Every address the bundle names was tried and none accepted: each failed to dial, answered
+ * malformed, or refused retryably. Always retryable; `outcomes` says what each address did.
+ */
+export class CadreInviteUnreachableError extends Error {
+  readonly retryable = true;
+
+  constructor(readonly outcomes: readonly CadreInviteAddressOutcome[]) {
+    super(outcomes.length === 0
+      ? 'Cadre invitation names no dialable member'
+      : `Cadre invitation could not be redeemed at any of its ${outcomes.length} address(es): `
+        + outcomes.map((outcome) => `${outcome.addr}: ${outcome.error.message}`).join('; '));
+    this.name = 'CadreInviteUnreachableError';
+  }
+}
+
+/**
+ * A member accepted but its reply does not check out: another party id, another invitation
+ * key, or a row not signed by one of the pinned owner keys. Final: a machine that answers
+ * like this is not a member of the cadre the invitation names, and the row it wrote (if any)
+ * is in a database the device will never trust.
+ */
+export class CadreInviteReplyInvalidError extends Error {
+  readonly retryable = false;
+
+  constructor(message: string) {
+    super(`Cadre invitation reply refused: ${message}`);
+    this.name = 'CadreInviteReplyInvalidError';
+  }
+}
+
+// ── Shape checks (both directions) ───────────────────────────────────────────
+
+/** Is `value` a {@link CadreInviteRow} with every column in its stored form and bounded? */
+export function isWellFormedCadreInviteRow(value: unknown): value is CadreInviteRow {
+  if (typeof value !== 'object' || value === null) return false;
+  const row = value as Record<string, unknown>;
+  return isEd25519KeyB64(row.key)
+    && isNullableBoundedString(row.peerId)
+    && isNullableBoundedString(row.expiresAt)
+    && isNullableUseCap(row.totalUses)
+    && isBoundedString(row.stampId)
+    && isEd25519KeyB64(row.issuerKey)
+    && isBoundedString(row.issuerSig);
+}
+
+/**
+ * The record's other fields are left to {@link admittedRecord}: a bad value there costs the
+ * device its signature on the row, not its admission.
+ */
+function isWellFormedRedeemRequest(value: unknown): value is CadreInviteRedeemRequest {
+  if (typeof value !== 'object' || value === null) return false;
+  const { v, partyId, invite, peerKey, record, usageStampId, inviteSig, peerSig } = value as Record<string, unknown>;
+  return v === 2
+    && isBoundedString(partyId)
+    && isWellFormedCadreInviteRow(invite)
+    && isEd25519KeyB64(peerKey)
+    && typeof record === 'object' && record !== null && Array.isArray((record as Record<string, unknown>).addrs)
+    && isBoundedString(usageStampId)
+    && isBoundedString(inviteSig)
+    && isBoundedString(peerSig);
+}
+
+/** What the member writes on the device's `CadrePeer` row from the request's record. */
+interface AdmittedRecord {
+  /** The record's addresses, sanitized ({@link sanitizeAddrs}): stored whether or not the rest is. */
+  addrs: string[];
+  /** The record's freshness, profile and signature, or null when they cannot be stored as the device's own. */
+  signed: Pick<PeerAddressRecord, 'updatedAt' | 'profile' | 'sig'> | null;
+  /** Why `signed` is null; absent when it is not. */
+  unsignedBecause?: string;
+}
+
+/**
+ * Judge the device's record (`request.record`) for its admission row. The signature covers the
+ * exact address list, so it is kept only when sanitizing dropped nothing, the profile is one the
+ * schema's `KnownProfile` check admits, the stamp and signature are in their stored forms, and
+ * the signature verifies for `partyId` under the device's key. Anything less admits the device
+ * with its addresses and no signature, as an owner-written row is, and the device's next
+ * publish fills it in. No clock check: a stamp in the future or the past is one the device's own
+ * self-publish could write too.
+ */
+function admittedRecord(partyId: string, remotePeerId: string, request: Pick<CadreInviteRedeemRequest, 'peerKey' | 'record'>): AdmittedRecord {
+  const { addrs: offered, updatedAt, profile, sig } = request.record as Partial<Record<keyof RedeemSelfRecord, unknown>>;
+  const addrs = sanitizeAddrs(offered);
+  const unsigned = (because: string): AdmittedRecord => ({ addrs, signed: null, unsignedBecause: because });
+  // Sanitizing only drops entries, so an unchanged length is an unchanged list.
+  if (!Array.isArray(offered) || addrs.length !== offered.length) {
+    return unsigned('sanitizing changed the signed address list');
+  }
+  if (profile !== null && profile !== 'transaction' && profile !== 'storage') {
+    return unsigned('unknown profile');
+  }
+  if (typeof updatedAt !== 'number' || !Number.isSafeInteger(updatedAt) || updatedAt <= 0 || !isBoundedString(sig)) {
+    return unsigned('malformed stamp or signature');
+  }
+  if (!verifyPeerRecordSignature(partyId, { peerId: remotePeerId, publicKey: request.peerKey, addrs, updatedAt, profile, sig })) {
+    return unsigned('signature does not verify');
+  }
+  return { addrs, signed: { updatedAt, profile, sig } };
+}
+
+/**
+ * Keep only parsable, distinct multiaddr strings, capped at {@link MAX_ADDRS}, order kept.
+ * Applied on both sides: the member bounds what it stores on the device's row, the device
+ * bounds what it merges into its peer store. A malformed entry is skipped, not fatal.
+ */
+export function sanitizeAddrs(addrs: unknown): string[] {
+  if (!Array.isArray(addrs)) return [];
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const entry of addrs) {
+    if (out.length >= MAX_ADDRS) break;
+    if (!isBoundedString(entry) || seen.has(entry)) continue;
+    try {
+      multiaddr(entry);
+    } catch (error) {
+      log('addrs: skipping unparsable entry: %o', error);
+      continue;
+    }
+    seen.add(entry);
+    out.push(entry);
+  }
+  return out;
+}
+
+/** The reply's peer list, bounded and each entry's addresses sanitized; anything else dropped. */
+function sanitizePeers(peers: unknown): SeedPeer[] {
+  if (!Array.isArray(peers)) return [];
+  const out: SeedPeer[] = [];
+  for (const entry of peers) {
+    if (out.length >= MAX_REPLY_PEERS) break;
+    if (typeof entry !== 'object' || entry === null) continue;
+    const { peerId, multiaddrs, preferred } = entry as Record<string, unknown>;
+    if (!isBoundedString(peerId)) continue;
+    out.push({ peerId, multiaddrs: sanitizeAddrs(multiaddrs), preferred: preferred === true });
+  }
+  return out;
+}
+
+/** An acceptance frame's fields, the attacker-influenced ones sanitized. Throws on a malformed one. */
+function decodeAccepted(reply: Record<string, unknown>): CadreInviteAccepted {
+  if (!isBoundedString(reply.partyId) || !isWellFormedCadreInviteRow(reply.invite)) {
+    throw new Error('Cadre invitation acceptance is missing its party id or a well-formed row');
+  }
+  return { accepted: true, partyId: reply.partyId, invite: reply.invite, peers: sanitizePeers(reply.peers) };
+}
+
+// ── Request construction (device side) ───────────────────────────────────────
+
+/** What the device signs with: its identity keypair in the crypto plugin's base64url form. */
+export interface RedeemSigner {
+  /** The device's ed25519 public key, base64url — the key behind its peer id. */
+  peerKey: string;
+  /** The device's ed25519 seed, base64url. */
+  peerPrivateKey: string;
+}
+
+/**
+ * Build and sign the request for `invitation`: the holder's `'redeem'` signature with the
+ * invitation's private key and the device's `'consent'` signature with its own, both over
+ * (invitation key, `usageStampId`, device key) for the invitation's party. The same bytes
+ * the schema verifies at the member (`cadreInviteRedeemMessage` / `cadreInviteConsentMessage`),
+ * whose own `party_id()` must therefore be the party the bundle names.
+ *
+ * @param record - the device's address record, already signed for the invitation's party over
+ *   sanitized addresses ({@link sanitizeAddrs}); copied in unchanged, since the signature
+ *   covers the exact list.
+ */
+export function signRedeemRequest(
+  invitation: CadreInvitation,
+  signer: RedeemSigner,
+  usageStampId: string,
+  record: RedeemSelfRecord
+): CadreInviteRedeemRequest {
+  const fields = { inviteKey: invitation.invite.key, usageStampId, peerKey: signer.peerKey };
+  const signB64 = (message: Uint8Array, privateKey: string): string =>
+    sign(message, privateKey, 'ed25519', 'bytes', 'base64url', 'base64url') as string;
+  return {
+    v: 2,
+    partyId: invitation.partyId,
+    invite: invitation.invite,
+    peerKey: signer.peerKey,
+    record: { addrs: [...record.addrs], updatedAt: record.updatedAt, profile: record.profile, sig: record.sig },
+    usageStampId,
+    inviteSig: signB64(cadreInviteRedeemMessage(invitation.partyId, fields), invitation.invitePrivateKey),
+    peerSig: signB64(cadreInviteConsentMessage(invitation.partyId, fields), signer.peerPrivateKey)
+  };
+}
+
+/**
+ * The device's check on an acceptance: the same party, the same invitation key, and a row
+ * signed by an issuer the device pinned from the bundle. Throws
+ * {@link CadreInviteReplyInvalidError} naming the first failure.
+ *
+ * What it proves is bounded: the request already carried the owner-signed row, so a machine
+ * that is not a member can echo it. The check catches a reply for another party or
+ * invitation and a row the pinned owners never signed; whether the answering machine is a
+ * member is settled afterwards, when the device syncs the control database and judges every
+ * row against its anchor (`CadreNode.listAuthorizedMembers`).
+ */
+export function verifyRedeemReply(
+  reply: CadreInviteAccepted,
+  invitation: CadreInvitation,
+  isTrustedIssuer: (ownerKey: string) => boolean
+): void {
+  if (reply.partyId !== invitation.partyId) {
+    throw new CadreInviteReplyInvalidError(`the member serves party ${reply.partyId}, the invitation names ${invitation.partyId}`);
+  }
+  if (reply.invite.key !== invitation.invite.key) {
+    throw new CadreInviteReplyInvalidError('the member answered for a different invitation');
+  }
+  if (!isTrustedIssuer(reply.invite.issuerKey)) {
+    throw new CadreInviteReplyInvalidError('the row the member holds is not issued by one of the invitation\'s owner keys');
+  }
+  if (!verifyCadreInviteRow(invitation.partyId, reply.invite)) {
+    throw new CadreInviteReplyInvalidError('the row the member holds is not signed by its issuer');
+  }
+}
+
+// ── Member side (handler) ────────────────────────────────────────────────────
+
+/** The control-database surface a redemption needs; a `ControlDatabase` satisfies it. */
+export type CadreInviteStore = Pick<ControlDatabase, 'queryCadreInvite' | 'seatCadreInvite' | 'isCadreInviteLive' | 'redeemCadreInvite' | 'querySeedPeers'>;
+
+export interface CadreInviteHandlerOptions extends MemberRedemptionHandlerOptions {
+  /** This member's peer id: the reply's peer list marks it preferred, since the device just reached it. */
+  peerId: string;
+  store: CadreInviteStore;
+}
+
+/** Constraint names the schema refuses a redemption with, and the code each maps to. */
+const REDEEM_CONSTRAINT_CODES: ReadonlyArray<ConstraintRefusalRow<CadreInviteRejectionCode>> = [
+  [/CHECK constraint failed: Authorized\b/, 'invite-spent', 'The invitation is expired, withdrawn, exhausted, or its issuer is no longer an owner'],
+  [/CHECK constraint failed: (InvitePossessed|PeerConsented|PeerExists)\b/, 'invite-invalid', 'The redemption does not satisfy the invitation'],
+  [/CHECK constraint failed: NotRevoked\b/, 'invite-spent', 'The invitation was withdrawn'],
+];
+
+/**
+ * Member side of the invitation protocol (`MemberRedemptionHandler` has the shape): after the
+ * request's shape, it checks the party, the connecting identity (an ed25519 peer id is an
+ * identity multihash of the very key, and this is the only layer that can check the pair),
+ * both signatures and a targeted invitation's device, then seats the row from the bundle when
+ * this member holds none and redeems. An issuer this member does not know as an owner is the
+ * one retryable refusal left: the device tries the next address, which may hold the issuer's row.
+ */
+export class CadreInviteHandler extends MemberRedemptionHandler<CadreInviteRedeemRequest, CadreInviteRedeemReply, CadreInviteRow> {
+  private readonly peerId: string;
+  private readonly store: CadreInviteStore;
+  protected readonly busyRefusal = rejection('busy', 'Too many concurrent redemptions');
+  protected readonly internalRefusal = rejection('internal', 'Internal redemption error');
+  protected readonly malformedRefusal = rejection('invite-invalid', 'Malformed redemption request');
+
+  constructor(options: CadreInviteHandlerOptions) {
+    super('Cadre invite', CADRE_INVITE_PROTOCOL, options);
+    this.peerId = options.peerId;
+    this.store = options.store;
+  }
+
+  protected isWellFormedRequest(value: unknown): value is CadreInviteRedeemRequest {
+    return isWellFormedRedeemRequest(value);
+  }
+
+  protected checkRequest(request: CadreInviteRedeemRequest, remotePeerId: string): CadreInviteRejection | null {
+    if (request.partyId !== this.partyId) {
+      return rejection('party-mismatch', 'This machine serves another cadre');
+    }
+    if (ed25519PublicKeyB64FromPeerId(remotePeerId) !== request.peerKey) {
+      return rejection('invite-invalid', 'The peer key is not the connecting identity');
+    }
+    const fields = { inviteKey: request.invite.key, usageStampId: request.usageStampId, peerKey: request.peerKey };
+    if (!verifyCadreInviteRedemption(this.partyId, fields, request.inviteSig, request.peerSig)) {
+      return rejection('invite-invalid', 'The redemption signatures do not verify');
+    }
+    if (request.invite.peerId !== null && request.invite.peerId !== remotePeerId) {
+      return rejection('invite-invalid', 'The invitation names another device');
+    }
+    return null;
+  }
+
+  protected readHeld(request: CadreInviteRedeemRequest): Promise<CadreInviteRow | null> {
+    return this.store.queryCadreInvite(request.invite.key);
+  }
+
+  protected isLive(request: CadreInviteRedeemRequest, held: CadreInviteRow | null): Promise<boolean> {
+    return this.store.isCadreInviteLive(request.invite, held);
+  }
+
+  /**
+   * The two writes — the seat (its own transaction), only when this member holds no row, and
+   * the redemption — each answered by name when it fails. The held row is carried into the
+   * redemption so it is not read again in the write lock; after a fresh seat nothing is carried
+   * and the redemption reads the row it seated, since the bundle's copy is the requester's.
+   */
+  protected async redeemAdmitted(request: CadreInviteRedeemRequest, remotePeerId: string, held: CadreInviteRow | null): Promise<CadreInviteRedeemReply> {
+    if (held === null) {
+      const refused = await this.seat(request, remotePeerId);
+      if (refused) return refused;
+    }
+    // Built before the write: the `CadrePeer` membership view is normally warm then (the
+    // connection gate read it when the device connected), and the redemption's commit drops it.
+    // The list lacks the device's own row, which the device drops from it anyway.
+    const peers = await this.peersBestEffort();
+    const record = admittedRecord(this.partyId, remotePeerId, request);
+    if (record.signed === null) {
+      log('admitting %s without its own record signature: %s', remotePeerId, record.unsignedBecause);
+    }
+    try {
+      const result = await this.store.redeemCadreInvite({
+        inviteKey: request.invite.key,
+        ...(held ? { held } : {}),
+        peerId: remotePeerId,
+        peerKey: request.peerKey,
+        multiaddrs: record.addrs,
+        ...(record.signed ? { record: record.signed } : {}),
+        usageStampId: request.usageStampId,
+        inviteSig: request.inviteSig,
+        peerSig: request.peerSig
+      });
+      log('invitation %s redeemed by %s (alreadyMember=%s)', request.invite.key, remotePeerId, result.alreadyMember);
+    } catch (error) {
+      if (error instanceof InvitationExhaustedError) {
+        return rejection('invite-spent', 'The invitation has no uses left');
+      }
+      log('redeeming invitation %s for %s failed: %o', request.invite.key, remotePeerId, error);
+      return constraintRefusal(error, REDEEM_CONSTRAINT_CODES) ?? writeFailureRefusal(error);
+    }
+    // The row as held: read before the write, or the bundle's copy the seat inserted verbatim
+    // or found already held (its key is the primary key and every column is under the issuer's
+    // signature).
+    return { accepted: true, partyId: this.partyId, invite: held ?? request.invite, peers };
+  }
+
+  /** Seat the bundle's copy of the row; a refusal answered by name, or null once it is held. */
+  private async seat(request: CadreInviteRedeemRequest, remotePeerId: string): Promise<CadreInviteRejection | null> {
+    try {
+      await this.store.seatCadreInvite(request.invite);
+      return null;
+    } catch (error) {
+      if (error instanceof CadreInviteIssuerUnknownError) {
+        return rejection('issuer-unknown', 'The invitation\'s issuer is not known as an owner here');
+      }
+      log('seating invitation %s from %s failed: %o', request.invite.key, remotePeerId, error);
+      return constraintRefusal(error, REDEEM_CONSTRAINT_CODES) ?? writeFailureRefusal(error);
+    }
+  }
+
+  /** Dial hints are an optimization; a failed read costs the device its hints, not its membership. */
+  private async peersBestEffort(): Promise<SeedPeer[]> {
+    try {
+      return await this.store.querySeedPeers(this.peerId);
+    } catch (error) {
+      log('peer projection for the reply failed (continuing without hints): %o', error);
+      return [];
+    }
+  }
+}
+
+// ── Device side (dialer) ─────────────────────────────────────────────────────
+
+export interface RedeemAtMembersOptions {
+  /** The bundle: its `members` are dialed in order. */
+  invitation: CadreInvitation;
+  /** The signed request ({@link signRedeemRequest}); the same one goes to every address. */
+  request: CadreInviteRedeemRequest;
+  /** Is this owner key one the device pinned from the bundle? The reply check's input. */
+  isTrustedIssuer: (ownerKey: string) => boolean;
+  /** See `MemberRedemptionOptions.linkRoundTripMs`. */
+  linkRoundTripMs?: number;
+  /** Per-address deadline override; default derived from `linkRoundTripMs`. */
+  addressBudgetMs?: number;
+  protocolId?: string;
+  /** Cancels the dial or stream in flight and ends the pass; the call throws the signal's reason. */
+  signal?: AbortSignal;
+}
+
+/** What a successful redemption yields the device. */
+export type CadreInviteRedemption = MemberRedemption<CadreInviteAccepted>;
+
+/** The invitation's half of the shared dial loop: its label, protocol, bundle, codec, checks and errors. */
+function inviteRedemption(options: RedeemAtMembersOptions): MemberRedemptionOptions<CadreInviteAccepted> {
+  return {
+    label: LABEL,
+    protocolId: options.protocolId ?? CADRE_INVITE_PROTOCOL,
+    members: options.invitation.members,
+    request: options.request,
+    decodeAccepted,
+    refusal: (code, reason) => new CadreInviteRejectedError(code, reason),
+    verifyAccepted: (reply) => verifyRedeemReply(reply, options.invitation, options.isTrustedIssuer),
+    unreachable: (outcomes) => new CadreInviteUnreachableError(outcomes),
+    ...(options.linkRoundTripMs !== undefined ? { linkRoundTripMs: options.linkRoundTripMs } : {}),
+    ...(options.addressBudgetMs !== undefined ? { addressBudgetMs: options.addressBudgetMs } : {}),
+    ...(options.signal ? { signal: options.signal } : {}),
+  };
+}
+
+/**
+ * Device side: try the bundle's addresses one at a time, each under its own deadline, and
+ * stop at the first acceptance or the first final refusal (`dialRedemption` in
+ * `member-redemption.ts`). Every address gets the SAME request, with one `usageStampId`:
+ * `CadreInviteUsage` is keyed by it, so a member the device gave up on that was still
+ * committing cannot admit it twice, and a retry at the next member after a dropped reply is
+ * answered as already a member.
+ *
+ * @throws {CadreInviteRejectedError} on a final refusal (its `retryable` is false).
+ * @throws {CadreInviteReplyInvalidError} on an acceptance that fails {@link verifyRedeemReply}.
+ * @throws {CadreInviteUnreachableError} when every address was tried and none accepted.
+ * @throws the reason of `options.signal` once it aborts.
+ */
+export function redeemAtMembers(node: Libp2p, options: RedeemAtMembersOptions): Promise<CadreInviteRedemption> {
+  return dialRedemption(node, inviteRedemption(options));
+}
+
+export interface RedeemInPassesOptions extends RedeemAtMembersOptions {
+  /** Keep making passes while every answer is retryable; false makes exactly one. */
+  waitForMember: boolean;
+  /** Called at each pass and each pause; an exception it throws is logged and ignored. */
+  onProgress?: (progress: CadreJoinProgress) => void;
+}
+
+/**
+ * Device side, in passes (`dialRedemptionInPasses` in `member-redemption.ts`): one
+ * {@link redeemAtMembers} pass, or, with `waitForMember`, as many as it takes, pausing between
+ * them and never past the invitation's expiry, which by this device's clock is thrown as the
+ * `invite-spent` refusal a member would give.
+ */
+export function redeemInPasses(node: Libp2p, options: RedeemInPassesOptions): Promise<CadreInviteRedemption> {
+  const passes: MemberRedemptionPassOptions<CadreInviteAccepted> = {
+    ...inviteRedemption(options),
+    waitForMember: options.waitForMember,
+    expiresAt: options.invitation.invite.expiresAt,
+    expired: () => new CadreInviteRejectedError('invite-spent', 'the invitation expired before a member accepted it'),
+    ...(options.onProgress ? { onProgress: options.onProgress } : {}),
+  };
+  return dialRedemptionInPasses(node, passes);
+}