@serfab/cadre-core 1.13.0 → 1.15.0

package/src/key-store-file.ts

@@ -1,141 +1,142 @@
-/**
- * Node-only file-backed {@link KeyStore}: one file per slot under a configured
- * directory, holding the raw key material bytes.
- *
- * This module imports `node:fs/promises`, `node:path`, and `node:crypto`, so it
- * is deliberately kept OUT of the package's cross-platform default entry
- * (`./index.js`). Import it from the dedicated subpath instead:
- *
- * ```ts
- * import { FileKeyStore } from '@serfab/cadre-core/key-store-file';
- * ```
- *
- * A React Native / browser entry graph never resolves this path, so the
- * `node:fs` edge never reaches a bundler that cannot satisfy it.
- */
-import debug from 'debug';
-import { readFile, rm, readdir } from 'node:fs/promises';
-import { join } from 'node:path';
-import { randomBytes } from 'node:crypto';
-import type { KeyId, KeyStore } from './key-store.js';
-import { KeyStoreAccessError } from './key-store.js';
-import { encodeFileSafeComponent, isNotFound, writeFileAtomically } from './fs-atomic.js';
-
-const log = debug('sereus:cadre:key-store-file');
-
-/** Suffix appended to the encoded keyId to form a slot filename. */
-const SLOT_SUFFIX = '.key';
-
-/**
- * Suffix for the transient file written then atomically renamed over the slot.
- * Distinct from {@link SLOT_SUFFIX}, so {@link FileKeyStore.list} (which matches
- * only `.key`) never surfaces an in-flight or crash-orphaned temp file.
- */
-const TEMP_SUFFIX = '.tmp';
-
-/**
- * Percent-encode a keyId into a filesystem-safe filename component (see
- * {@link encodeFileSafeComponent} — `.` is escaped so the `.key` suffix is the
- * only literal dot, making suffix-stripping in {@link decodeKeyId} unambiguous;
- * {@link decodeKeyId} reverses every escape via `decodeURIComponent`).
- */
-function encodeKeyId(keyId: KeyId): string {
-	return encodeFileSafeComponent(keyId);
-}
-
-/**
- * Reverse {@link encodeKeyId}: strip the slot suffix and percent-decode. Returns
- * `undefined` for a `.key` filename this store did not write, so
- * {@link FileKeyStore.list} can skip it rather than letting one undecodable
- * entry throw and break enumeration of every real slot. That includes a name
- * that decodes but is not the one {@link encodeKeyId} produces for the result
- * (e.g. a slot written before uppercase letters were escaped):
- * {@link FileKeyStore.get} looks only at the canonical name, so listing it
- * would name a key id that reads back as absent.
- */
-function decodeKeyId(fileName: string): KeyId | undefined {
-	const encoded = fileName.slice(0, -SLOT_SUFFIX.length);
-	let keyId: KeyId;
-	try {
-		keyId = decodeURIComponent(encoded);
-	} catch (error) {
-		log('FileKeyStore: skipping undecodable slot filename %s: %o', fileName, error);
-		return undefined;
-	}
-	if (encodeKeyId(keyId) !== encoded) {
-		log('FileKeyStore: skipping non-canonical slot filename %s', fileName);
-		return undefined;
-	}
-	return keyId;
-}
-
-/**
- * File-backed {@link KeyStore}. Each slot is `<dir>/<encoded keyId>.key`
- * containing the raw material bytes. The directory is created lazily on first
- * {@link set}. Suitable for headless Node cadre nodes and tests; for mobile use
- * a platform secure-enclave backend instead.
- */
-export class FileKeyStore implements KeyStore {
-	constructor(private readonly dir: string) {}
-
-	private slotPath(keyId: KeyId): string {
-		return join(this.dir, `${encodeKeyId(keyId)}${SLOT_SUFFIX}`);
-	}
-
-	/**
-	 * Sibling path for the temp file written before the atomic rename. The random
-	 * component makes concurrent {@link set}s to the same slot (and crash-orphaned
-	 * leftovers) collide-free; it lives in the same directory as the slot so the
-	 * final {@link rename} stays within one filesystem and is therefore atomic.
-	 */
-	private tempPath(keyId: KeyId): string {
-		const unique = randomBytes(6).toString('hex');
-		return join(this.dir, `${encodeKeyId(keyId)}.${unique}${TEMP_SUFFIX}`);
-	}
-
-	async get(keyId: KeyId): Promise<Uint8Array | undefined> {
-		try {
-			const buf = await readFile(this.slotPath(keyId));
-			// Copy into a plain Uint8Array decoupled from Node's Buffer pool.
-			return new Uint8Array(buf);
-		} catch (error) {
-			// A missing slot is "empty" (undefined), NOT an error — so a
-			// load-or-create caller generates a key rather than mistaking a
-			// permission failure for absence. Any other failure (e.g. EACCES) is
-			// surfaced as access-denied so callers do not clobber an existing key.
-			if (isNotFound(error)) return undefined;
-			throw new KeyStoreAccessError(keyId, `FileKeyStore: failed to read key slot ${keyId}`, { cause: error });
-		}
-	}
-
-	/**
-	 * Crash-atomic write: a concurrent reader sees either the complete previous
-	 * bytes or the complete new bytes, never a torn slot. The new material is
-	 * written to a sibling temp file, fsync'd, then atomically renamed over the
-	 * slot (see {@link writeFileAtomically}). A failure at any point removes the
-	 * temp file and leaves the previous slot untouched.
-	 */
-	async set(keyId: KeyId, keyMaterial: Uint8Array): Promise<void> {
-		await writeFileAtomically(this.dir, this.tempPath(keyId), this.slotPath(keyId), keyMaterial);
-	}
-
-	async delete(keyId: KeyId): Promise<void> {
-		// force:true makes removing an absent slot a no-op (idempotent).
-		await rm(this.slotPath(keyId), { force: true });
-	}
-
-	async list(): Promise<KeyId[]> {
-		let entries: string[];
-		try {
-			entries = await readdir(this.dir);
-		} catch (error) {
-			// An absent directory means no slots yet — not a failure.
-			if (isNotFound(error)) return [];
-			throw new Error('FileKeyStore: failed to list key directory', { cause: error });
-		}
-		return entries
-			.filter((name) => name.endsWith(SLOT_SUFFIX))
-			.map(decodeKeyId)
-			.filter((id): id is KeyId => id !== undefined);
-	}
-}
+/**
+ * Node-only file-backed {@link KeyStore}: one file per slot under a configured
+ * directory, holding the raw key material bytes.
+ *
+ * This module imports `node:fs/promises`, `node:path`, and `node:crypto`, so it
+ * is deliberately kept OUT of the package's cross-platform default entry
+ * (`./index.js`). Import it from the dedicated subpath instead:
+ *
+ * ```ts
+ * import { FileKeyStore } from '@serfab/cadre-core/key-store-file';
+ * ```
+ *
+ * A React Native / browser entry graph never resolves this path, so the
+ * `node:fs` edge never reaches a bundler that cannot satisfy it.
+ */
+import debug from 'debug';
+import { readFile, rm, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import type { KeyId, KeyStore } from './key-store.js';
+import { KeyStoreAccessError } from './key-store.js';
+import { isNotFound, writeFileAtomically } from './fs-atomic.js';
+import { encodeFileSafeComponent } from './file-safe-name.js';
+
+const log = debug('sereus:cadre:key-store-file');
+
+/** Suffix appended to the encoded keyId to form a slot filename. */
+const SLOT_SUFFIX = '.key';
+
+/**
+ * Suffix for the transient file written then atomically renamed over the slot.
+ * Distinct from {@link SLOT_SUFFIX}, so {@link FileKeyStore.list} (which matches
+ * only `.key`) never surfaces an in-flight or crash-orphaned temp file.
+ */
+const TEMP_SUFFIX = '.tmp';
+
+/**
+ * Percent-encode a keyId into a filesystem-safe filename component (see
+ * {@link encodeFileSafeComponent} — `.` is escaped so the `.key` suffix is the
+ * only literal dot, making suffix-stripping in {@link decodeKeyId} unambiguous;
+ * {@link decodeKeyId} reverses every escape via `decodeURIComponent`).
+ */
+function encodeKeyId(keyId: KeyId): string {
+	return encodeFileSafeComponent(keyId);
+}
+
+/**
+ * Reverse {@link encodeKeyId}: strip the slot suffix and percent-decode. Returns
+ * `undefined` for a `.key` filename this store did not write, so
+ * {@link FileKeyStore.list} can skip it rather than letting one undecodable
+ * entry throw and break enumeration of every real slot. That includes a name
+ * that decodes but is not the one {@link encodeKeyId} produces for the result
+ * (e.g. a slot written before uppercase letters were escaped):
+ * {@link FileKeyStore.get} looks only at the canonical name, so listing it
+ * would name a key id that reads back as absent.
+ */
+function decodeKeyId(fileName: string): KeyId | undefined {
+	const encoded = fileName.slice(0, -SLOT_SUFFIX.length);
+	let keyId: KeyId;
+	try {
+		keyId = decodeURIComponent(encoded);
+	} catch (error) {
+		log('FileKeyStore: skipping undecodable slot filename %s: %o', fileName, error);
+		return undefined;
+	}
+	if (encodeKeyId(keyId) !== encoded) {
+		log('FileKeyStore: skipping non-canonical slot filename %s', fileName);
+		return undefined;
+	}
+	return keyId;
+}
+
+/**
+ * File-backed {@link KeyStore}. Each slot is `<dir>/<encoded keyId>.key`
+ * containing the raw material bytes. The directory is created lazily on first
+ * {@link set}. Suitable for headless Node cadre nodes and tests; for mobile use
+ * a platform secure-enclave backend instead.
+ */
+export class FileKeyStore implements KeyStore {
+	constructor(private readonly dir: string) {}
+
+	private slotPath(keyId: KeyId): string {
+		return join(this.dir, `${encodeKeyId(keyId)}${SLOT_SUFFIX}`);
+	}
+
+	/**
+	 * Sibling path for the temp file written before the atomic rename. The random
+	 * component makes concurrent {@link set}s to the same slot (and crash-orphaned
+	 * leftovers) collide-free; it lives in the same directory as the slot so the
+	 * final {@link rename} stays within one filesystem and is therefore atomic.
+	 */
+	private tempPath(keyId: KeyId): string {
+		const unique = randomBytes(6).toString('hex');
+		return join(this.dir, `${encodeKeyId(keyId)}.${unique}${TEMP_SUFFIX}`);
+	}
+
+	async get(keyId: KeyId): Promise<Uint8Array | undefined> {
+		try {
+			const buf = await readFile(this.slotPath(keyId));
+			// Copy into a plain Uint8Array decoupled from Node's Buffer pool.
+			return new Uint8Array(buf);
+		} catch (error) {
+			// A missing slot is "empty" (undefined), NOT an error — so a
+			// load-or-create caller generates a key rather than mistaking a
+			// permission failure for absence. Any other failure (e.g. EACCES) is
+			// surfaced as access-denied so callers do not clobber an existing key.
+			if (isNotFound(error)) return undefined;
+			throw new KeyStoreAccessError(keyId, `FileKeyStore: failed to read key slot ${keyId}`, { cause: error });
+		}
+	}
+
+	/**
+	 * Crash-atomic write: a concurrent reader sees either the complete previous
+	 * bytes or the complete new bytes, never a torn slot. The new material is
+	 * written to a sibling temp file, fsync'd, then atomically renamed over the
+	 * slot (see {@link writeFileAtomically}). A failure at any point removes the
+	 * temp file and leaves the previous slot untouched.
+	 */
+	async set(keyId: KeyId, keyMaterial: Uint8Array): Promise<void> {
+		await writeFileAtomically(this.dir, this.tempPath(keyId), this.slotPath(keyId), keyMaterial);
+	}
+
+	async delete(keyId: KeyId): Promise<void> {
+		// force:true makes removing an absent slot a no-op (idempotent).
+		await rm(this.slotPath(keyId), { force: true });
+	}
+
+	async list(): Promise<KeyId[]> {
+		let entries: string[];
+		try {
+			entries = await readdir(this.dir);
+		} catch (error) {
+			// An absent directory means no slots yet — not a failure.
+			if (isNotFound(error)) return [];
+			throw new Error('FileKeyStore: failed to list key directory', { cause: error });
+		}
+		return entries
+			.filter((name) => name.endsWith(SLOT_SUFFIX))
+			.map(decodeKeyId)
+			.filter((id): id is KeyId => id !== undefined);
+	}
+}

package/src/link-budget.ts

@@ -73,9 +73,7 @@
  * Every row that opens a relayed connection counts opening the relay connection too
  * ({@link RELAYED_DIAL_ROUND_TRIPS}), because a dialer cannot know beforehand whether it holds
  * one, and a budget that is too short fails as silently as an absent peer. The
- * reservation-request row is {@link RELAY_RESERVE_REQUEST_ROUND_TRIPS}, which also sizes how long
- * a party-run relay waits for a stranger's reservation ({@link relayAdmissionReserveDeadlineMs}).
- * The commit row is a measurement of a whole write, not a count of exchanges; its doc comment
+ * reservation-request row is {@link RELAY_RESERVE_REQUEST_ROUND_TRIPS}. The commit row is a measurement of a whole write, not a count of exchanges; its doc comment
  * ({@link COMMIT_ROUND_TRIPS}) holds the figures and says when to re-measure it.
  *
  * **Measured** 2026-09-26, one Windows machine, loopback dedicated relay: a relayed dial over a
@@ -198,10 +196,10 @@
  *   the host derives its provisioning budget from its own, so a joiner declaring a faster
  *   link than the host gives up on a reply the host is still entitled to send. Declare the
  *   same link on every machine of a party.
- *   Relay admission too: a party-run relay derives how long a stranger has to ask for a
- *   reservation from ITS declaration ({@link relayAdmissionReserveDeadlineMs}), so a relay
- *   declaring a faster link than a client closes that client's connection before its request
- *   arrives.
+ *   Provisional admission too: a member derives how long it keeps a connection from a peer it
+ *   cannot place from ITS declaration ({@link relayedRequestBudgetMs}), so a member declaring a
+ *   faster link than a redeeming device can close that device's connection while the device is
+ *   still waiting on its redemption.
  */
 
 import { resolveLinkDeadlines, type Libp2pConnectionTimeouts, type RpcDeadlineDefaults } from '@optimystic/db-p2p';
@@ -261,20 +259,19 @@ export const RELAY_DIAL_ROUND_TRIPS = 1;
 export const RELAYED_DIAL_ROUND_TRIPS = RELAY_DIAL_ROUND_TRIPS + CIRCUIT_DIAL_ROUND_TRIPS;
 
 /**
- * Link round trips from the moment a party-run relay admits a stranger's connection for relay
- * use to the moment that stranger's RESERVE request reaches it. libp2p's reservation store
- * (`@libp2p/circuit-relay-v2`'s `addRelay`) opens the hop stream the instant its dial resolves,
- * without waiting for identify, so:
+ * Link round trips from the moment a relay accepts a client's connection to the moment that
+ * client's RESERVE request reaches it. libp2p's reservation store (`@libp2p/circuit-relay-v2`'s
+ * `addRelay`) opens the hop stream the instant its dial resolves, without waiting for identify,
+ * so:
  *
  * 1. The client's last Noise handshake message and its hop-stream open arrive at the relay
- *    together. The relay's gate runs on the handshake message (and arms the reserve deadline),
- *    then the relay answers the protocol negotiation.
+ *    together. A party-run relay's gate runs on the handshake message, then the relay answers
+ *    the protocol negotiation.
  * 2. The answer reaches the client and the client's RESERVE request reaches the relay: one round
  *    trip on the client-to-relay hop, which is the whole link round trip when all of the link's
  *    delay is on the client's own hop (a phone on a congested mobile link).
  *
- * The relay's decision on that request is local time, not link time;
- * {@link relayAdmissionReserveDeadlineMs} adds it separately.
+ * The relay's decision on that request is local time, not link time.
  */
 export const RELAY_RESERVE_REQUEST_ROUND_TRIPS = 1;
 
@@ -285,10 +282,15 @@ export const RELAY_RESERVE_REQUEST_ROUND_TRIPS = 1;
  *
  * The protocol work measured is 2 — dial the relay ({@link RELAY_DIAL_ROUND_TRIPS}) plus request
  * the reservation ({@link RELAY_RESERVE_REQUEST_ROUND_TRIPS}). It is budgeted at twice that,
- * because the wait afterwards may instead be satisfied by libp2p's own relay discovery, which
- * repeats both legs after identify has run; 4 is therefore the largest thing this one deadline
- * can be asked to contain, and the poll interval (`DEFAULT_RELAY_RESERVE_POLL_MS`) rounds up on
- * top of it.
+ * because on a node that keeps libp2p's own relay discovery (a browser tab driving a bare
+ * `/p2p-circuit` through `reserveRelays`) the wait afterwards may instead be satisfied by
+ * discovery, which repeats both legs after identify has run; 4 is therefore the largest thing
+ * this one deadline can be asked to contain, and the poll interval
+ * (`DEFAULT_RELAY_RESERVE_POLL_MS`) rounds up on top of it.
+ *
+ * NOTE: on a node with configured relays discovery is off (`node-transports.ts`), so there the
+ * doubling is only headroom, and it is what an unreachable configured relay costs every launch
+ * (the whole deadline is polled out). If that launch cost ever matters, budget those nodes at 2.
  */
 export const RELAY_RESERVATION_ROUND_TRIPS = 2 * (RELAY_DIAL_ROUND_TRIPS + RELAY_RESERVE_REQUEST_ROUND_TRIPS);
 
@@ -511,23 +513,6 @@ export function relayReservationBudgetMs(linkRoundTripMs?: number): number {
 	return RELAY_RESERVATION_ROUND_TRIPS * resolveLinkRoundTripMs(linkRoundTripMs) + 2 * ADMISSION_DECISION_TIMEOUT_MS;
 }
 
-/**
- * How long a party-run relay keeps a connection it admitted only for relay use
- * (`membership-connection-gater.ts`'s `'admit-for-relay'`) before closing it, unless a
- * reservation is admitted on it first: {@link RELAY_RESERVE_REQUEST_ROUND_TRIPS} at the declared
- * link round trip, plus one {@link ADMISSION_DECISION_TIMEOUT_MS} for the relay's own decision on
- * the reservation (`denyInboundRelayReservation`), which disarms the timer only once it settles.
- * 3 500 + 2 000 = 5 500 ms at the default declaration.
- *
- * The declaration is the RELAY's own, because the relay is the machine that decides.
- *
- * What it costs, against the fixed 5 000 ms it replaced: a stranger that connects and never
- * reserves holds a mute connection 0.5 s longer at the default declaration.
- */
-export function relayAdmissionReserveDeadlineMs(linkRoundTripMs?: number): number {
-	return RELAY_RESERVE_REQUEST_ROUND_TRIPS * resolveLinkRoundTripMs(linkRoundTripMs) + ADMISSION_DECISION_TIMEOUT_MS;
-}
-
 /**
  * Deadline for one request and its answer over a circuit that is already open —
  * {@link CIRCUIT_REQUEST_ROUND_TRIPS} at the declared link round trip, plus `transferAllowanceMs`
@@ -549,6 +534,10 @@ export function circuitRequestBudgetMs(
  *
  * No transfer allowance, unlike {@link circuitRequestBudgetMs}: the requests this bounds are a few
  * hundred bytes to a few KB, so their bytes cost nothing a round trip does not already cover.
+ *
+ * A control node also keeps a connection it admitted provisionally this long, at its own
+ * declaration, because a cadre invitation redemption is bounded by this budget on the device's
+ * side (`membership-connection-gater.ts`, `PROVISIONAL_ADMISSION_DEADLINE_MS`).
  */
 export function relayedRequestBudgetMs(linkRoundTripMs?: number): number {
 	return relayedDialBudgetMs(linkRoundTripMs) + CIRCUIT_REQUEST_ROUND_TRIPS * resolveLinkRoundTripMs(linkRoundTripMs);

package/src/machine-removal.ts

@@ -0,0 +1,216 @@
+/**
+ * Removing a machine from a cadre: the listing an app shows (`CadreNode.listMachines`), the
+ * read-only plan behind its confirmation step (`CadreNode.planMachineRemoval`), and the
+ * check that a requested re-vouch stays inside that plan. Pure projections over rows the
+ * node has already read; the reads and writes themselves are `CadreNode.removeMachine`'s and
+ * `ControlDatabase.removeMachine`'s.
+ *
+ * A machine's owner key is its own identity key: an owner-granting invitation seats
+ * `OwnerKey.Key = CadrePeer.PublicKey`, and `addOwner` takes the key behind a peer id. So
+ * "this machine is an owner" is "the ed25519 key behind its peer id is a live `OwnerKey`",
+ * and an owner key with no machine row is still listed, as the machine it names.
+ */
+
+import { ed25519PublicKeyB64FromPeerId, peerIdFromEd25519PublicKeyB64 } from './ed25519-key.js';
+import { verifyPeerRecordSignature } from './peer-record.js';
+import type {
+  CadreInviteStatus,
+  CadreInviteUsageRow,
+  CadreMachine,
+  CadrePeerRow,
+  MachineRemovalPlan,
+  MachineRemovalRefusal,
+  OwnerKeyRow,
+  RemoveMachineOptions,
+} from './types.js';
+
+/**
+ * `CadreNode.removeMachine` refused by name, before any write. `code` says which rule
+ * (`MachineRemovalRefusal`), for an app to switch on; the message is for a log.
+ */
+export class MachineRemovalRefusedError extends Error {
+  readonly code: MachineRemovalRefusal;
+  readonly peerId: string;
+
+  constructor(peerId: string, code: MachineRemovalRefusal) {
+    super(`Cannot remove machine ${peerId}: ${MACHINE_REMOVAL_REFUSAL_REASON[code]}`);
+    this.name = 'MachineRemovalRefusedError';
+    this.code = code;
+    this.peerId = peerId;
+  }
+}
+
+const MACHINE_REMOVAL_REFUSAL_REASON: Record<MachineRemovalRefusal, string> = {
+  'not-an-owner': 'this node holds no enrolled owner key',
+  'self': 'an owner cannot remove its own machine; ask another owner',
+  'last-owner': 'it holds the only live owner key',
+};
+
+/** What {@link describeMachines} projects from: one node's live rows and its own predicate. */
+export interface MachineListingInput {
+  partyId: string;
+  selfPeerId: string | null;
+  /** Live `CadrePeer` rows (`ControlDatabase.queryCadrePeers`). */
+  rows: readonly CadrePeerRow[];
+  /** Live `OwnerKey` rows (`ControlDatabase.queryOwnerKeyRows`). */
+  owners: readonly OwnerKeyRow[];
+  /** This node's authorized-membership predicate for one row (`CadreNode.listAuthorizedMembers`'s). */
+  trusted: (row: CadrePeerRow) => boolean;
+}
+
+/**
+ * One entry per live `CadrePeer` row, then one per live `OwnerKey` whose key derives a peer
+ * id with no row. `profile` and `lastPublishedAt` are reported only when the row's
+ * self-signature verifies under the key behind its peer id, as `CadreNode.resolvePeerAddrs`
+ * judges the same record: no insert rule constrains `Profile`, and an owner re-vouch may
+ * bump `UpdatedAt` without re-signing.
+ */
+export function describeMachines(input: MachineListingInput): CadreMachine[] {
+  const ownerKeys = new Set(input.owners.map((owner) => owner.key));
+  const machines = input.rows.map((row) => describeMemberRow(input, row, ownerKeys));
+  const listed = new Set(machines.map((machine) => machine.peerId));
+  for (const owner of input.owners) {
+    const peerId = peerIdFromEd25519PublicKeyB64(owner.key);
+    if (peerId === null || listed.has(peerId)) {
+      continue;
+    }
+    listed.add(peerId);
+    machines.push({
+      peerId,
+      publicKey: owner.key,
+      isSelf: peerId === input.selfPeerId,
+      isOwner: true,
+      isMember: false,
+      trusted: false,
+      profile: null,
+      lastPublishedAt: null,
+      vouchedBy: owner.vouchOwner,
+    });
+  }
+  return machines;
+}
+
+function describeMemberRow(input: MachineListingInput, row: CadrePeerRow, ownerKeys: ReadonlySet<string>): CadreMachine {
+  const publicKey = ed25519PublicKeyB64FromPeerId(row.peerId);
+  const selfPublished = publicKey !== null && row.publicKey === publicKey && row.sig !== null
+    && verifyPeerRecordSignature(input.partyId, {
+      peerId: row.peerId,
+      publicKey,
+      addrs: row.multiaddr ? row.multiaddr.split(',') : [],
+      updatedAt: row.updatedAt,
+      profile: row.profile,
+      sig: row.sig,
+    });
+  return {
+    peerId: row.peerId,
+    publicKey,
+    isSelf: row.peerId === input.selfPeerId,
+    isOwner: publicKey !== null && ownerKeys.has(publicKey),
+    isMember: true,
+    trusted: input.trusted(row),
+    profile: selfPublished ? row.profile : null,
+    lastPublishedAt: selfPublished ? row.updatedAt : null,
+    vouchedBy: row.vouchOwner,
+  };
+}
+
+/** What {@link planMachineRemoval} judges from. */
+export interface MachineRemovalPlanInput {
+  peerId: string;
+  machines: readonly CadreMachine[];
+  rows: readonly CadrePeerRow[];
+  owners: readonly OwnerKeyRow[];
+  selfPeerId: string | null;
+  /** This node's enrolled owner key (`CadreNode.enrolledOwnerSigningKey`), or null when it cannot sign owner writes. */
+  selfOwnerKey: string | null;
+  invites: readonly CadreInviteStatus[];
+  usages: readonly CadreInviteUsageRow[];
+}
+
+/**
+ * The plan for removing `peerId` from these rows. The refusals come first and by name: a
+ * node that cannot sign, the node itself (an owner cannot sign its own `OwnerKey` removal;
+ * refusing the whole self-removal keeps one rule for owners and non-owners), and a machine
+ * holding the only live owner key. The last cannot coexist with this node being a different
+ * owner, but the local count can be wrong under concurrency, so the name stays.
+ *
+ * `dependents` are the rows the machine's owner key vouched, which every reader judges
+ * against its anchor through `VouchOwner`: once the key is removed they stop passing the
+ * membership predicate on every machine unless re-vouched first. This node's own rows are
+ * reported as `ownDependency` instead, since it cannot re-vouch them itself.
+ *
+ * `invitations` are the live ones the machine could redeem to come back: targeted at it,
+ * or already redeemed by it and still redeemable (a multi-use invitation, or an open
+ * owner invitation inside its lifetime). The schema's rule: keeping a device out is removing
+ * its row and withdrawing the invitation.
+ */
+export function planMachineRemoval(input: MachineRemovalPlanInput): MachineRemovalPlan {
+  const machine = input.machines.find((candidate) => candidate.peerId === input.peerId) ?? null;
+  const key = machine?.isOwner ? machine.publicKey : null;
+  const refusal = refusalFor(input, machine);
+  const removesOwnerKey = key !== null;
+  return {
+    machine,
+    refusal,
+    removesOwnerKey,
+    dependents: removesOwnerKey ? dependentsOf(input, key) : { owners: [], peers: [] },
+    invitations: invitationsOpenTo(input),
+    ownDependency: removesOwnerKey && isOwnDependency(input, key),
+  };
+}
+
+function refusalFor(input: MachineRemovalPlanInput, machine: CadreMachine | null): MachineRemovalRefusal | null {
+  if (input.selfOwnerKey === null) {
+    return 'not-an-owner';
+  }
+  if (input.peerId === input.selfPeerId) {
+    return 'self';
+  }
+  if (machine?.isOwner && input.owners.length <= 1) {
+    return 'last-owner';
+  }
+  return null;
+}
+
+function dependentsOf(input: MachineRemovalPlanInput, key: string): MachineRemovalPlan['dependents'] {
+  return {
+    owners: input.owners
+      .filter((owner) => owner.vouchOwner === key && owner.key !== key && owner.key !== input.selfOwnerKey)
+      .map((owner) => owner.key),
+    peers: input.rows
+      .filter((row) => row.vouchOwner === key && row.peerId !== input.peerId && row.peerId !== input.selfPeerId)
+      .map((row) => row.peerId),
+  };
+}
+
+function isOwnDependency(input: MachineRemovalPlanInput, key: string): boolean {
+  const ownRow = input.rows.find((row) => row.peerId === input.selfPeerId);
+  const ownOwner = input.owners.find((owner) => owner.key === input.selfOwnerKey);
+  return ownRow?.vouchOwner === key || ownOwner?.vouchOwner === key;
+}
+
+function invitationsOpenTo(input: MachineRemovalPlanInput): string[] {
+  const redeemed = new Set(input.usages.filter((usage) => usage.peerId === input.peerId).map((usage) => usage.inviteKey));
+  return input.invites
+    .filter((status) => status.live && (status.invite.peerId === input.peerId || redeemed.has(status.invite.key)))
+    .map((status) => status.invite.key);
+}
+
+/**
+ * The re-vouch a caller asked for, checked against the plan: every key and peer must be in
+ * `plan.dependents`, so a caller cannot re-vouch a row the removed owner never vouched (nor
+ * the machine itself, which `dependents.peers` excludes). Throws naming the offenders, before
+ * `CadreNode.removeMachine` writes anything. Duplicates are dropped.
+ */
+export function revouchWithinPlan(plan: MachineRemovalPlan, revouch: RemoveMachineOptions['revouch']): MachineRemovalPlan['dependents'] {
+  const owners = [...new Set(revouch?.owners ?? [])];
+  const peers = [...new Set(revouch?.peers ?? [])];
+  const strayOwners = owners.filter((key) => !plan.dependents.owners.includes(key));
+  const strayPeers = peers.filter((peerId) => !plan.dependents.peers.includes(peerId));
+  if (strayOwners.length > 0 || strayPeers.length > 0) {
+    throw new Error(
+      `removeMachine: re-vouch names rows the removed machine did not vouch: ${[...strayOwners, ...strayPeers].join(', ')}`,
+    );
+  }
+  return { owners, peers };
+}