@serfab/cadre-core 1.13.0 → 1.15.0

package/src/node-claim-payload.ts

@@ -0,0 +1,259 @@
+/**
+ * The claim payload: what a host shows as a QR code (and as text) for a node that is
+ * waiting to be claimed, and what the owner's phone scans to claim it.
+ *
+ * `sereus-join:1.<base64url of canonical JSON>` where the JSON is
+ * `{ multiaddrs, peerId, secret }`: the node's peer id, every address the phone may
+ * dial it at (each ending in `/p2p/<peerId>`), and the node's one-time claim secret
+ * (`claim-proof.ts`). The phone hands all three to `CadreNode.claimNode`. The payload
+ * carries no party id: the claim supplies it, and the node records it.
+ *
+ * The decoder lives here, beside the encoder, because the phone and the host both need
+ * it and neither depends on the other. Imports only `@multiformats/multiaddr`,
+ * `@libp2p/peer-id` and `uint8arrays`, so it loads on React Native and in the browser.
+ */
+import { peerIdFromString } from '@libp2p/peer-id';
+import {
+	multiaddr,
+	CODE_DNS,
+	CODE_DNS4,
+	CODE_DNS6,
+	CODE_DNSADDR,
+	CODE_IP4,
+	CODE_IP6,
+	CODE_IP6ZONE,
+	CODE_P2P,
+	CODE_P2P_CIRCUIT,
+	CODE_WS,
+	CODE_WSS,
+} from '@multiformats/multiaddr';
+import { fromString as uint8ArrayFromString, toString as uint8ArrayToString } from 'uint8arrays';
+import { canonicalJson } from './canonical-json.js';
+import { parseClaimSecret } from './claim-proof.js';
+
+/** Version 1 of the payload; the only one either side reads. */
+export const NODE_CLAIM_PAYLOAD_PREFIX = 'sereus-join:1.';
+
+export interface NodeClaimPayload {
+	/** The node's peer id. */
+	peerId: string;
+	/** Addresses the phone may dial the node at, each ending in `/p2p/<peerId>`. */
+	multiaddrs: string[];
+	/** The node's claim secret, base64url (`parseClaimSecret`). */
+	secret: string;
+}
+
+/** Encode a payload as the text the host shows. Refuses what {@link decodeNodeClaimPayload} would. */
+export function encodeNodeClaimPayload(payload: NodeClaimPayload): string {
+	const checked = requireNodeClaimPayload(payload);
+	const json = canonicalJson({ multiaddrs: checked.multiaddrs, peerId: checked.peerId, secret: checked.secret });
+	return `${NODE_CLAIM_PAYLOAD_PREFIX}${uint8ArrayToString(new TextEncoder().encode(json), 'base64url')}`;
+}
+
+/**
+ * Decode the text a phone scanned or pasted. Refuses, naming the problem: any version but
+ * 1, a body that is not base64url JSON of the right shape, a peer id that does not parse,
+ * an empty address list, an address that does not parse or whose last `/p2p/` is not that
+ * peer id, and a secret {@link parseClaimSecret} refuses. The secret is never echoed.
+ */
+export function decodeNodeClaimPayload(text: string): NodeClaimPayload {
+	const trimmed = text.trim();
+	if (!trimmed.startsWith(NODE_CLAIM_PAYLOAD_PREFIX)) {
+		throw new Error(`A claim payload must start with "${NODE_CLAIM_PAYLOAD_PREFIX}" (this one starts with "${trimmed.slice(0, NODE_CLAIM_PAYLOAD_PREFIX.length)}")`);
+	}
+	let parsed: unknown;
+	try {
+		const json = new TextDecoder().decode(uint8ArrayFromString(trimmed.slice(NODE_CLAIM_PAYLOAD_PREFIX.length), 'base64url'));
+		parsed = JSON.parse(json);
+	} catch (error) {
+		throw new Error('A claim payload must carry base64url-encoded JSON after its prefix', { cause: error });
+	}
+	if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+		throw new Error('A claim payload must decode to a JSON object');
+	}
+	const { peerId, multiaddrs, secret } = parsed as Record<string, unknown>;
+	if (typeof peerId !== 'string') throw new Error('A claim payload must name the node\'s peer id');
+	if (!Array.isArray(multiaddrs) || !multiaddrs.every((a): a is string => typeof a === 'string')) {
+		throw new Error('A claim payload must carry the node\'s addresses as a list of strings');
+	}
+	if (typeof secret !== 'string') throw new Error('A claim payload must carry the claim secret');
+	return requireNodeClaimPayload({ peerId, multiaddrs, secret });
+}
+
+/** How {@link selectNodeClaimAddresses} narrows a node's addresses. */
+export interface NodeClaimAddressOptions {
+	/**
+	 * The machine's LAN address, the one a phone at home reaches it on. A string keeps only
+	 * the private addresses on that IP (dropping Docker bridges, VPN and other interfaces no
+	 * phone can reach); `null` drops every private address (a machine reached only by its
+	 * public name); absent keeps them all, for a caller that cannot tell.
+	 */
+	lan?: string | null;
+	/** Keep addresses a phone cannot dial: plain TCP. Default false, since phones dial WebSocket and relay only. */
+	includeTcp?: boolean;
+}
+
+/**
+ * The addresses a node code should carry, from the ones a node knows it has (`/status`,
+ * a NAT layer's public addresses). A phone dials them in turn, each on its own timeout, so
+ * every address it cannot reach only delays a failing claim, and makes the QR code bigger.
+ *
+ * - Each gains `/p2p/<peerId>` when it lacks a destination; loopback, unspecified and
+ *   unparsable ones are dropped, and so is plain TCP unless `includeTcp`.
+ * - Public names (`/dns*`) come first: they work away from home. Public IP addresses are
+ *   kept only when there is no public name, since they reach the same machine.
+ * - Private addresses follow, narrowed by {@link NodeClaimAddressOptions.lan}; relay
+ *   addresses last.
+ *
+ * Pure and dependency-light, like the codec beside it, so it loads on React Native too.
+ * Finding the LAN address is the caller's (Node: `@serfab/cadre-core/primary-lan-address`).
+ */
+export function selectNodeClaimAddresses(reported: readonly string[], peerId: string, options: NodeClaimAddressOptions = {}): string[] {
+	const names: string[] = [];
+	const publicIps: string[] = [];
+	const privates: string[] = [];
+	const relayed: string[] = [];
+	for (const raw of reported) {
+		const classified = classifyClaimAddress(raw.trim(), peerId, options);
+		if (!classified) continue;
+		({ name: names, public: publicIps, private: privates, relay: relayed })[classified.kind].push(classified.addr);
+	}
+	return [...new Set([...names, ...(names.length > 0 ? [] : publicIps), ...privates, ...relayed])];
+}
+
+/**
+ * `addr` as a node code carries it: with `/p2p/<peerId>` appended unless it already names a
+ * destination. A relay address that ends at its hop (`…/p2p/<relay>/p2p-circuit`) names none,
+ * so it gains the node's id too. Throws when `addr` does not parse. For callers that take
+ * exact addresses from an operator; {@link selectNodeClaimAddresses} applies it itself.
+ */
+export function withClaimDestination(addr: string, peerId: string): string {
+	const trimmed = addr.trim();
+	return destinationPeerIdOf(trimmed) === null ? `${trimmed}/p2p/${peerId}` : trimmed;
+}
+
+/**
+ * Where a phone could dial an address from: a relayed address (`/p2p-circuit`), a public name,
+ * a public IP, a private (LAN, VPN, link-local) IP, or this machine's own loopback.
+ */
+export type DialAddressKind = 'relay' | 'name' | 'public' | 'private' | 'loopback';
+
+/**
+ * Classify `addr` for a phone dialing it, or undefined when no phone can dial it at all: it
+ * does not parse, names the unspecified address, or is plain TCP without `includeTcp` (phones
+ * dial WebSocket and relay only).
+ */
+export function classifyDialAddress(addr: string, options: { includeTcp?: boolean } = {}): DialAddressKind | undefined {
+	const components = componentsOf(addr);
+	return components ? classifyComponents(components, options.includeTcp ?? false)?.kind : undefined;
+}
+
+type AddressComponents = ReturnType<ReturnType<typeof multiaddr>['getComponents']>;
+
+function componentsOf(addr: string): AddressComponents | undefined {
+	try {
+		return multiaddr(addr).getComponents();
+	} catch {
+		return undefined;
+	}
+}
+
+/** {@link classifyDialAddress}, keeping the IP for a caller that narrows private addresses by it. */
+function classifyComponents(components: AddressComponents, includeTcp: boolean): { kind: DialAddressKind; ip?: string } | undefined {
+	if (components.some((c) => c.code === CODE_P2P_CIRCUIT)) return { kind: 'relay' };
+	if (!includeTcp && !components.some((c) => c.code === CODE_WS || c.code === CODE_WSS)) return undefined;
+	const host = components[0];
+	if (!host?.value) return undefined;
+	if (host.code === CODE_DNS || host.code === CODE_DNS4 || host.code === CODE_DNS6 || host.code === CODE_DNSADDR) {
+		return { kind: host.value === 'localhost' ? 'loopback' : 'name' };
+	}
+	if (host.code !== CODE_IP4 && host.code !== CODE_IP6 && host.code !== CODE_IP6ZONE) return undefined;
+	const ip = host.code === CODE_IP6ZONE ? components[1]?.value ?? '' : host.value;
+	if (ip === '0.0.0.0' || ip === '::') return undefined;
+	if (ip.startsWith('127.') || ip === '::1') return { kind: 'loopback', ip };
+	if (host.code !== CODE_IP6ZONE && !isPrivateIp(ip)) return { kind: 'public', ip };
+	return { kind: 'private', ip };
+}
+
+/** One address's place in {@link selectNodeClaimAddresses}, or undefined to drop it. */
+function classifyClaimAddress(addr: string, peerId: string, options: NodeClaimAddressOptions): { kind: Exclude<DialAddressKind, 'loopback'>; addr: string } | undefined {
+	const components = componentsOf(addr);
+	if (!components) return undefined;
+	const classified = classifyComponents(components, options.includeTcp ?? false);
+	if (!classified || classified.kind === 'loopback') return undefined;
+	if (classified.kind === 'private' && (options.lan === null || (options.lan !== undefined && classified.ip !== options.lan))) {
+		return undefined;
+	}
+	return { kind: classified.kind, addr: destinationIn(components) === null ? `${addr}/p2p/${peerId}` : addr };
+}
+
+/** RFC 1918, carrier-grade NAT (100.64/10), link-local, and IPv6 unique-local / link-local. */
+function isPrivateIp(ip: string): boolean {
+	if (ip.includes(':')) return /^(f[cd]|fe[89ab])/i.test(ip);
+	const [a, b] = ip.split('.').map(Number) as [number, number];
+	return a === 10
+		|| (a === 172 && b >= 16 && b <= 31)
+		|| (a === 192 && b === 168)
+		|| (a === 169 && b === 254)
+		|| (a === 100 && b >= 64 && b <= 127);
+}
+
+/** The shape rules both directions apply. Returns the payload with its fields trimmed. */
+function requireNodeClaimPayload(payload: NodeClaimPayload): NodeClaimPayload {
+	const peerId = parsePeerId(payload.peerId);
+	const multiaddrs = payload.multiaddrs.map((a) => a.trim());
+	if (multiaddrs.length === 0) throw new Error('A claim payload must carry at least one address for the node');
+	for (const addr of multiaddrs) requireAddressOf(addr, peerId);
+	// The secret is checked, never kept in a message: see `parseClaimSecret`.
+	parseClaimSecret(payload.secret);
+	return { peerId: peerId.toString(), multiaddrs, secret: payload.secret.trim() };
+}
+
+function parsePeerId(text: string): ReturnType<typeof peerIdFromString> {
+	try {
+		return peerIdFromString(text.trim());
+	} catch (error) {
+		throw new Error(`A claim payload's peer id does not parse ("${text}")`, { cause: error });
+	}
+}
+
+/** `addr` parses, and its destination (the last `/p2p/`, past any relay hop) is `peerId`. */
+function requireAddressOf(addr: string, peerId: ReturnType<typeof peerIdFromString>): void {
+	let destination: string | null;
+	try {
+		destination = destinationPeerIdOf(addr);
+	} catch (error) {
+		throw new Error(`A claim payload address does not parse ("${addr}")`, { cause: error });
+	}
+	if (destination === null) {
+		throw new Error(`A claim payload address must end in /p2p/${peerId.toString()} ("${addr}" names no peer)`);
+	}
+	let named: ReturnType<typeof peerIdFromString>;
+	try {
+		named = peerIdFromString(destination);
+	} catch (error) {
+		throw new Error(`A claim payload address names a peer id that does not parse ("${addr}")`, { cause: error });
+	}
+	if (!named.equals(peerId)) {
+		throw new Error(`A claim payload address names another peer ("${addr}" is not an address of ${peerId.toString()})`);
+	}
+}
+
+/**
+ * The peer an address reaches: its last `/p2p/` component. A relayed address
+ * (`…/p2p/<relay>/p2p-circuit/p2p/<destination>`) names its destination after the
+ * circuit hop; one that ends at the hop names nobody. Same rule as
+ * `groupAddrsByPeerId` in `peer-addr-book.ts`. Throws when `addr` does not parse.
+ */
+export function destinationPeerIdOf(addr: string): string | null {
+	return destinationIn(multiaddr(addr).getComponents());
+}
+
+function destinationIn(components: AddressComponents): string | null {
+	for (let i = components.length - 1; i >= 0; i--) {
+		const component = components[i]!;
+		if (component.code === CODE_P2P_CIRCUIT) return null;
+		if (component.code === CODE_P2P && component.value) return component.value;
+	}
+	return null;
+}

package/src/node-default-transports.ts

@@ -0,0 +1,38 @@
+/**
+ * Node-only: `@optimystic/db-p2p`'s default transport list, for `NetworkConfig.defaultTransports`.
+ *
+ * A node with configured relays is built from an explicit transport list, so that libp2p's relay
+ * discovery can be switched off in it (`node-transports.ts`). A Node host that supplies no
+ * `network.transports` passes this function so that list still matches what db-p2p would have
+ * built. A subpath module (`@serfab/cadre-core/node-default-transports`), like `push-node`,
+ * because it names `@libp2p/tcp`: some bundlers (the NativeScript reference app's webpack) take
+ * its Node implementation rather than its browser stub, and that needs `net`, `os` and `path`.
+ */
+
+import { tcp } from '@libp2p/tcp';
+import { webSockets } from '@libp2p/websockets';
+import { circuitRelayTransport } from '@libp2p/circuit-relay-v2';
+import type { Libp2pTransports } from '@optimystic/db-p2p';
+import type { ListenTransportOptions } from './relay-addrs.js';
+
+/**
+ * TCP, WebSocket exactly when the node's listen entries switch it on, and the circuit-relay
+ * transport.
+ *
+ * Passing an explicit list makes db-p2p ignore `wsPort` for transports, which is why WebSocket is
+ * decided here from the same switch. Its other use of `wsPort`, a default WebSocket listen
+ * address, never applies: a node with configured relays always has explicit listen entries.
+ *
+ * NOTE: mirrors `createLibp2pNode`'s default list in
+ * `../optimystic/packages/db-p2p/src/libp2p-node.ts` (cadre never sets its `disableTcp`). That file
+ * is the source of truth; if its defaults change, this list has to follow. If db-p2p ever takes an
+ * option to build its default list with relay discovery off, use that and drop this module and
+ * `NetworkConfig.defaultTransports`.
+ */
+export function nodeDefaultTransports({ wsPort }: ListenTransportOptions): Libp2pTransports {
+  return [
+    tcp(),
+    ...(wsPort === undefined ? [] : [webSockets()]),
+    circuitRelayTransport()
+  ];
+}

package/src/node-transports.ts

@@ -0,0 +1,49 @@
+/**
+ * The `transports` option for a cadre-built libp2p node, control and strand alike.
+ *
+ * A node whose bare `/p2p-circuit` search entries cadre generated for configured relays gets its
+ * transports through {@link withoutRelayDiscovery}, so libp2p's relay discovery cannot hand those
+ * slots to some other relay-capable peer before the per-relay supervisors fill them (see
+ * `relay-reservation.ts`, "WHY LIBP2P'S RELAY DISCOVERY IS SWITCHED OFF"). Every other node gets
+ * the embedder's list as it was, or no option at all, and `@optimystic/db-p2p` builds its own
+ * default list.
+ *
+ * The wrapper needs a list to wrap. React Native and browser embedders always supply one
+ * (`network.transports`); a Node host supplies the default list through
+ * `network.defaultTransports` instead, since db-p2p builds its default internally and it names
+ * `@libp2p/tcp`, which this module's graph must not reach (`node-default-transports.ts`).
+ */
+
+import debug from 'debug';
+import type { Libp2pTransports } from '@optimystic/db-p2p';
+import { withoutRelayDiscovery } from './relay-reservation.js';
+import type { ListenTransportOptions } from './relay-addrs.js';
+import type { NetworkConfig } from './types.js';
+
+const log = debug('sereus:cadre:node-transports');
+
+/**
+ * The `transports` option to spread into a node's `createLibp2pNode` options.
+ *
+ * @param listenTransports what the node's resolved listen entries imply (`resolveTransportOptions`
+ *   in `relay-addrs.ts`), handed to `network.defaultTransports`.
+ * @param relaySlotsSupervised whether cadre generated this node's bare `/p2p-circuit` entries for
+ *   configured relays and runs a supervisor over them — `network.relayAddrs` on the control node,
+ *   a non-empty relay list from `strandNodeAddrs` on a strand node.
+ */
+export function nodeTransportsOption(
+  network: NetworkConfig | undefined,
+  listenTransports: ListenTransportOptions,
+  relaySlotsSupervised: boolean
+): { transports?: Libp2pTransports } {
+  if (!relaySlotsSupervised) {
+    return network?.transports ? { transports: network.transports } : {};
+  }
+  const transports = network?.transports ?? network?.defaultTransports?.(listenTransports);
+  if (transports === undefined) {
+    log('Relays are configured but no transport list was supplied (network.transports or ' +
+      'network.defaultTransports); libp2p relay discovery stays on and can take their slots');
+    return {};
+  }
+  return { transports: withoutRelayDiscovery(transports) };
+}

package/src/owner-anchor-sync.ts

@@ -0,0 +1,171 @@
+/**
+ * How the node-local trusted-owner anchor follows the replicated `OwnerKey` table along
+ * VERIFIABLE chains — the pure rule, with no I/O, so it can be tested without a database.
+ * `CadreNode.syncOwnerAnchor` reads the table, the tombstones and the invitation chain,
+ * calls {@link deriveOwnerAnchor}, and applies the difference to the store.
+ *
+ * Why not simply trust the table: an empty local copy can seat any key through the
+ * schema's genesis branch and that row replicates (`docs/architecture.md` → "Node-local
+ * trusted-owner anchor"). So every node grows its anchor only through rows whose stored
+ * proof verifies against a key it already trusts, on every membership refresh. The terms
+ * used throughout:
+ *
+ * - **base**: the anchor's entries whose provenance is not `chain` (trusted out of band).
+ * - **live row**: an `OwnerKey` row whose stamp no tombstone retires.
+ * - **kept**: a `chain` entry that still has a live row. A derived entry is state, not
+ *   recomputed from the base each pass: it entered through a proof that verified then, and
+ *   it stays until its own row is retired or a verifiable tombstone removes it. This is what
+ *   lets an owner rotate (A adds A', A' removes A): A' keeps its place after A's row is
+ *   retired, although nothing could re-derive it from the remaining base.
+ * - **derivable from S**: a live row whose stored proof verifies against S — owner-signed
+ *   (`vouchSig` set): `vouchOwner` is in S and `verifyOwnerKeyVoucher` holds;
+ *   invitation-admitted (`vouchSig` null, `vouchUsage` set): `verifyInvitationOwnerAdmission`
+ *   holds with S as the anchor. The founding row (all three null) is never derivable:
+ *   founders enter anchors only out of band.
+ * - **derived**: the least fixpoint from base ∪ kept — add every key whose live row is
+ *   derivable from what is already in the set, until nothing changes. **chainDerived** is the
+ *   keys whose live row was derivable in this pass, base keys included.
+ * - **removed**: a key K in derived is removed when an `OwnerKey` tombstone names K, its
+ *   signer is in derived and is not K, its stored signature verifies
+ *   (`verifyRevocationSigner`), AND K is not in chainDerived. The last condition is what
+ *   makes a re-add win over an older tombstone: a removed owner re-added under a fresh
+ *   stamp has a live derivable row again, and the old stamp's tombstone no longer applies.
+ * - **target** = derived minus removed. If that would be empty, no removal is applied this
+ *   pass (target = derived) and the refused removals are reported for the caller to log.
+ *
+ * Every tombstone is judged against the pass-start set (derived) at once, so the outcome
+ * does not depend on the order they are read in: a signer that is itself removed in this
+ * pass still counts, and a mutual removal of the last two owners is refused rather than
+ * decided by read order.
+ *
+ * An owner C that a removed owner B had added therefore stays where it was already derived
+ * (its row is live) and cannot be derived on a machine that never held it (the chain from
+ * that machine's base runs through B's retired row) until a remaining owner re-adds it or
+ * an invitation pins it there. The rotation case above is the same shape with C = A', so the
+ * two cannot be told apart from replicated state; keeping is the only rule under which a
+ * sole owner can rotate at all.
+ */
+import { verifyInvitationOwnerAdmission, verifyOwnerKeyVoucher, verifyRevocationSigner } from './peer-authorization.js';
+import type { TrustSource } from './trusted-owner-store.js';
+import type { InvitationChain, OwnerKeyRow, RevocationRow } from './types.js';
+
+export interface OwnerAnchorInputs {
+	/** The party whose table is being read; every stored proof is judged for it, so a voucher or tombstone signed for another party neither seats nor removes a key. */
+	partyId: string;
+	/** The anchor at the start of the pass, every key with its provenance (`TrustedOwnerStore.sources`). */
+	anchor: ReadonlyMap<string, TrustSource>;
+	/** `OwnerKey` rows as read; rows whose stamp a tombstone in `tombstones` retires are dropped here too. */
+	rows: readonly OwnerKeyRow[];
+	/** `Revocation` rows; only those with `tableName === 'OwnerKey'` are consulted. */
+	tombstones: readonly RevocationRow[];
+	/** The usage and invitation rows, when some owner row is invitation-admitted; null skips those rows. */
+	chain: InvitationChain | null;
+}
+
+export interface OwnerAnchorDerivation {
+	/** The keys the anchor should hold after this pass. */
+	target: ReadonlySet<string>;
+	/** Keys whose verifiable removal was NOT applied because the anchor would have emptied. */
+	refusedRemovals: readonly string[];
+}
+
+/** The rule above, as one pure function. */
+export function deriveOwnerAnchor({ partyId, anchor, rows, tombstones, chain }: OwnerAnchorInputs): OwnerAnchorDerivation {
+	const ownerTombstones = tombstones.filter(tombstone => tombstone.tableName === 'OwnerKey');
+	// NOTE: a stamp is retired by any tombstone that names it, verified or not — the same
+	// reading `queryCadrePeers` and `getOwnerKeys` give the table. A forged tombstone can
+	// therefore prune a derived entry (its row goes) but never seat or keep one; if tombstone
+	// pollution is ever closed at the write side, judge retirement by the verified signer too.
+	const retired = new Set(ownerTombstones.map(tombstone => tombstone.stampId));
+	const liveRows = rows.filter(row => !retired.has(row.stampId));
+
+	const derived = passStartSet(anchor, liveRows);
+	const chainDerived = deriveFixpoint(partyId, derived, liveRows, chain);
+
+	const removed = removedKeys(partyId, derived, chainDerived, ownerTombstones);
+	if (removed.size > 0 && removed.size === derived.size) {
+		return { target: derived, refusedRemovals: Array.from(removed) };
+	}
+	const target = new Set(Array.from(derived).filter(key => !removed.has(key)));
+	return { target, refusedRemovals: [] };
+}
+
+/** base ∪ kept: every out-of-band entry, and every `chain` entry whose row is still live. */
+function passStartSet(anchor: ReadonlyMap<string, TrustSource>, liveRows: readonly OwnerKeyRow[]): Set<string> {
+	const liveKeys = new Set(liveRows.map(row => row.key));
+	const start = new Set<string>();
+	for (const [key, source] of anchor) {
+		if (source !== 'chain' || liveKeys.has(key)) {
+			start.add(key);
+		}
+	}
+	return start;
+}
+
+/**
+ * Grow `derived` to the least fixpoint and return chainDerived: every key whose live row was
+ * derivable. A row is judged once its voucher is in the set, and settled either way then:
+ * trust only grows within a pass, and a proof that failed against a trusted voucher cannot
+ * pass later, so no row is verified twice.
+ */
+function deriveFixpoint(partyId: string, derived: Set<string>, liveRows: readonly OwnerKeyRow[], chain: InvitationChain | null): Set<string> {
+	const chainDerived = new Set<string>();
+	const pending = new Set(liveRows);
+	let progress = true;
+	while (progress) {
+		progress = false;
+		for (const row of pending) {
+			if (row.vouchOwner === null || !derived.has(row.vouchOwner)) {
+				continue;
+			}
+			pending.delete(row);
+			if (proofVerifies(partyId, row, derived, chain)) {
+				chainDerived.add(row.key);
+				derived.add(row.key);
+				progress = true;
+			}
+		}
+	}
+	return chainDerived;
+}
+
+/** Does `row`'s stored proof verify against `trusted`, for `partyId`, by the kind of proof it carries (see the module doc)? */
+function proofVerifies(partyId: string, row: OwnerKeyRow, trusted: ReadonlySet<string>, chain: InvitationChain | null): boolean {
+	if (row.vouchOwner === null) {
+		return false;
+	}
+	if (row.vouchSig !== null) {
+		return verifyOwnerKeyVoucher(partyId, row.key, row.stampId, row.vouchOwner, row.vouchSig);
+	}
+	if (row.vouchUsage === null) {
+		return false;
+	}
+	const usage = chain?.usages.get(row.vouchUsage);
+	const invite = usage === undefined ? undefined : chain?.invites.get(usage.inviteKey);
+	if (usage === undefined || invite === undefined) {
+		return false;
+	}
+	return verifyInvitationOwnerAdmission(partyId, row, usage, invite, key => trusted.has(key));
+}
+
+/**
+ * The keys of `derived` that a verifiable tombstone removes (see the module doc), every
+ * tombstone judged against the same pass-start set. A tombstone for a key outside `derived`
+ * changes nothing and is skipped before any signature work.
+ */
+function removedKeys(partyId: string, derived: ReadonlySet<string>, chainDerived: ReadonlySet<string>, ownerTombstones: readonly RevocationRow[]): Set<string> {
+	const removed = new Set<string>();
+	for (const tombstone of ownerTombstones) {
+		const key = tombstone.rowKey;
+		if (!derived.has(key) || chainDerived.has(key) || removed.has(key)) {
+			continue;
+		}
+		if (tombstone.signerKey === key || !derived.has(tombstone.signerKey)) {
+			continue;
+		}
+		if (verifyRevocationSigner(partyId, tombstone)) {
+			removed.add(key);
+		}
+	}
+	return removed;
+}