@serfab/cadre-core 1.14.0 → 1.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serfab/cadre-core",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "type": "module",
   "description": "Core library for Sereus cadre nodes - manages control networks and strand participation",
   "main": "dist/index.js",
@@ -24,6 +24,10 @@
       "types": "./dist/key-store-file.d.ts",
       "import": "./dist/key-store-file.js"
     },
+    "./primary-lan-address": {
+      "types": "./dist/primary-lan-address.d.ts",
+      "import": "./dist/primary-lan-address.js"
+    },
     "./trusted-owner-store-file": {
       "types": "./dist/trusted-owner-store-file.d.ts",
       "import": "./dist/trusted-owner-store-file.js"
@@ -43,6 +47,10 @@
     "./push-node": {
       "types": "./dist/push-node.d.ts",
       "import": "./dist/push-node.js"
+    },
+    "./node-default-transports": {
+      "types": "./dist/node-default-transports.d.ts",
+      "import": "./dist/node-default-transports.js"
     }
   },
   "repository": {
@@ -70,14 +78,11 @@
   "devDependencies": {
     "@chainsafe/libp2p-noise": "^17.0.0",
     "@chainsafe/libp2p-yamux": "^8.0.1",
-    "@libp2p/circuit-relay-v2": "^4.2.13",
     "@libp2p/identify": "4.1.14",
     "@libp2p/logger": "^6.2.13",
     "@libp2p/peer-store": "^12.0.28",
-    "@libp2p/tcp": "^11.0.28",
     "@libp2p/webrtc": "6.0.33",
-    "@libp2p/websockets": "^10.1.21",
-    "@optimystic/db-p2p-storage-fs": "^1.12.0",
+    "@optimystic/db-p2p-storage-fs": "^1.13.0",
     "@types/debug": "^4.1.12",
     "@types/node": "^25.0.10",
     "@vitest/coverage-v8": "^4.0.17",
@@ -88,18 +93,21 @@
     "vitest": "^4.0.17"
   },
   "dependencies": {
+    "@libp2p/circuit-relay-v2": "^4.2.13",
     "@libp2p/crypto": "^5.1.23",
     "@libp2p/interface": "^3.3.0",
     "@libp2p/peer-id": "^6.0.15",
     "@libp2p/peer-record": "^9.0.16",
+    "@libp2p/tcp": "^11.0.28",
+    "@libp2p/websockets": "^10.1.21",
     "@multiformats/multiaddr": "^13.0.3",
     "@noble/hashes": "^2.0.0",
-    "@optimystic/db-core": "^1.12.0",
-    "@optimystic/db-p2p": "^1.12.0",
-    "@optimystic/quereus-plugin-crypto": "^1.12.0",
-    "@optimystic/quereus-plugin-optimystic": "^1.12.0",
+    "@optimystic/db-core": "^1.13.0",
+    "@optimystic/db-p2p": "^1.13.0",
+    "@optimystic/quereus-plugin-crypto": "^1.13.0",
+    "@optimystic/quereus-plugin-optimystic": "^1.13.0",
     "@quereus/quereus": "^4.20.1",
-    "@serfab/quereus-plugin-sereus": "^1.14.0",
+    "@serfab/quereus-plugin-sereus": "^1.15.0",
     "debug": "^4.4.3",
     "libp2p": "^3.3.11",
     "uint8arrays": "^6.1.1"

package/src/cadre-invite-protocol.ts

@@ -31,15 +31,16 @@ import {
   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 { trailingPeerId } from './peer-record.js';
-import { nextMacrotask } from './peer-dial.js';
+import { dialAddr, nextMacrotask, trailingPeerId } from './peer-dial.js';
 import { chainMessages } from './control-retry.js';
 import { isRetriableControlWriteFailure } from './control-write-retry.js';
-import type { CadreInviteRow, SeedPeer } from './types.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');
 
@@ -108,29 +109,42 @@ export interface CadreInvitation {
    */
   ownerKeys: string[];
   /**
-   * Multiaddrs ending in `/p2p/<peerId>`: the issuer's own first, then up to
-   * `INVITATION_SIBLING_MACHINES` other members (`invitation-bootstrap.ts`). The device
-   * tries them in order.
+   * 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: base64url over JSON, as seeds and open invitations are. */
+/**
+ * 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 uint8ArrayToString(new TextEncoder().encode(JSON.stringify(invitation)), 'base64url');
+  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}. Standalone so a client without a node (a settings screen that
- * wants to show which cadre an invitation joins) can decode one.
+ * {@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 string that is not base64url JSON, or decodes to another shape or version.
+ * @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(encoded.trim(), 'base64url')));
+    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 });
   }
@@ -512,12 +526,14 @@ export interface CadreInviteHandlerOptions {
   partyId: string;
   store: CadreInviteStore;
   /**
-   * Push this member's control store to the device and resolve once the push has finished,
-   * called after the request verified and before the row is seated and the admission is
-   * written. Absent, the writes go ahead with the device holding nothing; see
-   * `catchUpDeviceIfLive` for why that tears on a member alone with the device.
+   * 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`.
    */
-  catchUpDevice?: (peerId: string) => Promise<void>;
+  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}. */
@@ -555,8 +571,8 @@ function writeFailureRejection(error: unknown): CadreInviteRejection {
 /**
  * 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 hands the device the control
- * store (`catchUpDevice`), seats the row and redeems.
+ * 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
@@ -668,15 +684,24 @@ export class CadreInviteHandler {
   }
 
   /**
-   * Hand the device this member's control store, seat the row from the bundle (its own
-   * transaction; a no-op when held), then redeem. The push comes first because the seat is
-   * already a write the device takes part in (see {@link catchUpDeviceIfLive}). 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.
+   * 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;
-    await this.catchUpDeviceIfLive(request.invite, remotePeerId);
     try {
       await store.seatCadreInvite(request.invite);
     } catch (error) {
@@ -710,12 +735,14 @@ export class CadreInviteHandler {
   }
 
   /**
-   * Push this member's control store to the device before the first write of the exchange
-   * (the seat, when this member does not hold the row; otherwise the admission). The device
-   * joined this member's control write cohort when it connected, and a cohort node with no
-   * base revision of a block refuses a commit to it; a member alone with the device then has
-   * half its cohort refusing, and the write tears instead of committing. With the store in
-   * hand the device holds the write too.
+   * 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
@@ -723,25 +750,27 @@ export class CadreInviteHandler {
    * 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, then commit or are
-   * answered retryably.
+   * 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 catchUpDeviceIfLive(invite: CadreInviteRow, remotePeerId: string): Promise<void> {
-    const { catchUpDevice, store } = this.options;
-    if (!catchUpDevice) return;
+  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 caught up before the write', invite.key, remotePeerId);
-        return;
+        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.
-      await catchUpDevice(remotePeerId);
+      return await admitDevice(remotePeerId);
     } catch (error) {
-      log('catching up %s before its admission failed (writing anyway): %o', remotePeerId, error);
+      log('admitting %s before its admission write failed (writing anyway): %o', remotePeerId, error);
+      return notAdmitted;
     }
   }
 
@@ -774,6 +803,8 @@ export interface RedeemAtMembersOptions {
   /** 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. */
@@ -786,8 +817,11 @@ export interface CadreInviteRedemption {
 }
 
 /**
- * Open one stream to `addr`, send the request, half-close, read the one reply frame.
+ * 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,
@@ -797,8 +831,9 @@ async function exchangeRedemption(
   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 node.dialProtocol(addr, protocolId, { runOnLimitedConnection: true, signal });
+  const rawStream = await connection.newStream(protocolId, { runOnLimitedConnection: true, signal });
   return await exchangeFrame(
     rawStream as unknown as ControlStream,
     signal,
@@ -812,7 +847,34 @@ async function exchangeRedemption(
 }
 
 function asError(error: unknown): Error {
-  return error instanceof Error ? error : new Error(String(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);
+  }
 }
 
 /**
@@ -827,13 +889,16 @@ function asError(error: unknown): Error {
  * @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) {
-    // Between attempts: libp2p's dial queue needs a macrotask to drop an aborted job.
+    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 {
@@ -844,7 +909,8 @@ export async function redeemAtMembers(node: Libp2p, options: RedeemAtMembersOpti
     }
     try {
       const reply = await withDeadline(budgetMs, `Cadre invitation redemption via ${addr}`,
-        (signal) => exchangeRedemption(node, parsed, options.request, signal, budgetMs, protocolId));
+        (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;
@@ -856,9 +922,131 @@ export async function redeemAtMembers(node: Libp2p, options: RedeemAtMembersOpti
       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 });
+  });
+}

package/src/cadre-join-request.ts

@@ -0,0 +1,167 @@
+/**
+ * The join request: the text an app that wants to join a cadre copies (or shows as a QR code)
+ * so the app that manages the cadre can mint an invitation for it alone
+ * (`CadreNode.createCadreInvitation({ peerId: request.peerId, grantsOwner })`).
+ *
+ * `sereus-join-request:1.<base64url of canonical JSON>` where the JSON is
+ * `{ appName, peerId, reply?, v }`. Nothing in it is secret or signed: the peer id is public, and
+ * the name is only what the requester calls itself, shown in the owner's approval prompt. The
+ * safety is in the response: an invitation targeted at that peer id can be redeemed only by
+ * the key behind it.
+ *
+ * `reply` is present only on a request opened as a link from another app on the same phone
+ * (`@serfab/cadre-rn/app-link`): the owner app answers by opening `<reply.scheme>://…`, a link it
+ * builds itself, so the scheme is restricted to an app's own custom scheme and never a web or
+ * system one, which would send the invitation's machine addresses off the phone.
+ *
+ * Imports only `@libp2p/peer-id` and `uint8arrays`, so it loads on React Native and in the
+ * browser.
+ */
+import { peerIdFromString } from '@libp2p/peer-id';
+import { fromString as uint8ArrayFromString, toString as uint8ArrayToString } from 'uint8arrays';
+import { canonicalJson } from './canonical-json.js';
+
+/** Version 1 of the join request; the only one either side reads. */
+export const CADRE_JOIN_REQUEST_PREFIX = 'sereus-join-request:1.';
+
+/**
+ * Version 1 of an encoded cadre invitation (`encodeCadreInvitation`). Declared here, beside
+ * the request's prefix, so each decoder can name the other kind of text when it is pasted in
+ * the wrong place without this codec importing the redemption protocol.
+ */
+export const CADRE_INVITATION_PREFIX = 'sereus-invite:1.';
+
+/** Longest `appName` a request carries: one line in an approval prompt. */
+export const CADRE_JOIN_REQUEST_MAX_APP_NAME = 64;
+
+/**
+ * Schemes a reply may not name, though they match {@link CADRE_JOIN_REPLY_SCHEME}: each opens a
+ * web page, a file, a system action or another app's content rather than a Sereus app.
+ */
+const REFUSED_REPLY_SCHEMES: ReadonlySet<string> = new Set([
+	'http', 'https', 'ws', 'wss', 'ftp', 'file', 'content', 'data', 'blob',
+	'javascript', 'about', 'intent', 'mailto', 'tel', 'sms',
+]);
+
+/**
+ * The form of a reply's scheme: lowercase, as an app's custom URL scheme is declared.
+ * NOTE: `@serfab/cadre-rn`'s CommonJS config plugin keeps a copy (`APP_SCHEME`) to check extra
+ * apps' schemes; change it with this one.
+ */
+const CADRE_JOIN_REPLY_SCHEME = /^[a-z][a-z0-9+.-]{0,63}$/;
+
+/** The form of a reply's nonce: base64url, long enough that it cannot be guessed. */
+const CADRE_JOIN_REPLY_NONCE = /^[A-Za-z0-9_-]{16,64}$/;
+
+/** Where and how the owner app answers a request that arrived as a link. */
+export interface CadreJoinReply {
+	/** The requesting app's own custom URL scheme; the owner app opens `<scheme>://cadre-join-response/<response>`. */
+	scheme: string;
+	/** Echoed in the response, so the requesting app takes only an answer to a request it has open. */
+	nonce: string;
+}
+
+export interface CadreJoinRequest {
+	v: 1;
+	/** The requesting node's peer id: an Ed25519 peer id, since the invitation targets that key. */
+	peerId: string;
+	/** What the requester calls itself, for the owner's approval prompt. Unverified; at most 64 characters, trimmed, non-empty. */
+	appName: string;
+	/** Present only on a request opened as a link: where and how the owner app answers. */
+	reply?: CadreJoinReply;
+}
+
+/** Encode a request as the text the requesting app copies. Refuses what {@link decodeCadreJoinRequest} would. */
+export function encodeCadreJoinRequest(request: CadreJoinRequest): string {
+	const checked = requireCadreJoinRequest(request);
+	// canonicalJson drops an undefined `reply`, so a request without one encodes as it always has.
+	const json = canonicalJson({ appName: checked.appName, peerId: checked.peerId, reply: checked.reply, v: checked.v });
+	return `${CADRE_JOIN_REQUEST_PREFIX}${uint8ArrayToString(new TextEncoder().encode(json), 'base64url')}`;
+}
+
+/**
+ * Decode the text the owner's app was given. Refuses, naming the problem: an invitation
+ * pasted here, any prefix but version 1's, a body that is not base64url JSON of the request's
+ * shape, a peer id that does not parse or is not Ed25519, an `appName` that is empty or
+ * longer than {@link CADRE_JOIN_REQUEST_MAX_APP_NAME} characters once trimmed, and a `reply`
+ * that {@link requireCadreJoinReply} refuses.
+ */
+export function decodeCadreJoinRequest(text: string): CadreJoinRequest {
+	const trimmed = text.trim();
+	if (trimmed.startsWith(CADRE_INVITATION_PREFIX)) {
+		throw new Error('This is a cadre invitation, not a join request; paste it where the app asks for an invitation');
+	}
+	if (!trimmed.startsWith(CADRE_JOIN_REQUEST_PREFIX)) {
+		throw new Error(`A join request must start with "${CADRE_JOIN_REQUEST_PREFIX}" (this one starts with "${trimmed.slice(0, CADRE_JOIN_REQUEST_PREFIX.length)}")`);
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(new TextDecoder().decode(uint8ArrayFromString(trimmed.slice(CADRE_JOIN_REQUEST_PREFIX.length), 'base64url')));
+	} catch (error) {
+		throw new Error('A join request must carry base64url-encoded JSON after its prefix', { cause: error });
+	}
+	if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+		throw new Error('A join request must decode to a JSON object');
+	}
+	const { v, peerId, appName, reply } = parsed as Record<string, unknown>;
+	if (v !== 1) throw new Error(`A join request must be version 1 (this one says ${JSON.stringify(v)})`);
+	if (typeof peerId !== 'string') throw new Error('A join request must name the requesting node\'s peer id');
+	if (typeof appName !== 'string') throw new Error('A join request must carry the requesting app\'s name');
+	return requireCadreJoinRequest({ v, peerId, appName, ...(reply === undefined ? {} : { reply: replyShape(reply) }) });
+}
+
+/**
+ * Refuses, naming the problem, a reply whose scheme is not a lowercase URL scheme of at most 64
+ * characters or is a web or system scheme (`https`, `file`, `intent`, …), and a nonce that is
+ * not 16 to 64 base64url characters. The owner app checks it again before it opens a reply.
+ */
+export function requireCadreJoinReply(reply: CadreJoinReply): CadreJoinReply {
+	const { scheme, nonce } = reply;
+	if (!CADRE_JOIN_REPLY_SCHEME.test(scheme)) {
+		throw new Error(`A join request's reply scheme must be a lowercase URL scheme of at most 64 characters (this one is ${JSON.stringify(scheme)})`);
+	}
+	if (REFUSED_REPLY_SCHEMES.has(scheme)) {
+		throw new Error(`A join request's reply scheme must be an app's own scheme, not "${scheme}"`);
+	}
+	if (!CADRE_JOIN_REPLY_NONCE.test(nonce)) {
+		throw new Error('A join request\'s reply nonce must be 16 to 64 base64url characters');
+	}
+	return { scheme, nonce };
+}
+
+/** The decoded `reply`'s types, before {@link requireCadreJoinReply} judges its values. */
+function replyShape(reply: unknown): CadreJoinReply {
+	if (typeof reply !== 'object' || reply === null || Array.isArray(reply)) {
+		throw new Error('A join request\'s reply must be an object');
+	}
+	const { scheme, nonce } = reply as Record<string, unknown>;
+	if (typeof scheme !== 'string' || typeof nonce !== 'string') {
+		throw new Error('A join request\'s reply must carry a scheme and a nonce');
+	}
+	return { scheme, nonce };
+}
+
+/** The shape rules both directions apply. Returns the request with its fields trimmed. */
+function requireCadreJoinRequest(request: CadreJoinRequest): CadreJoinRequest {
+	const peerId = requireEd25519PeerId(request.peerId);
+	const appName = request.appName.trim();
+	if (appName.length === 0) throw new Error('A join request must name the requesting app');
+	if (appName.length > CADRE_JOIN_REQUEST_MAX_APP_NAME) {
+		throw new Error(`A join request's app name must be at most ${CADRE_JOIN_REQUEST_MAX_APP_NAME} characters (this one has ${appName.length})`);
+	}
+	return { v: 1, peerId, appName, ...(request.reply ? { reply: requireCadreJoinReply(request.reply) } : {}) };
+}
+
+/** An invitation targeted at the peer id names its key, so only an Ed25519 id could ever redeem one. */
+function requireEd25519PeerId(text: string): string {
+	let parsed: ReturnType<typeof peerIdFromString>;
+	try {
+		parsed = peerIdFromString(text.trim());
+	} catch (error) {
+		throw new Error(`A join request's peer id does not parse ("${text}")`, { cause: error });
+	}
+	if (parsed.type !== 'Ed25519') {
+		throw new Error(`A join request's peer id must be an Ed25519 peer id (this one is ${parsed.type})`);
+	}
+	return parsed.toString();
+}