@serfab/cadre-core 1.16.0 → 1.18.0

package/src/owner-keys.ts

@@ -0,0 +1,178 @@
+/**
+ * Owner keys as an app lists, adds and removes them (`CadreNode.listOwnerKeys`,
+ * `CadreNode.addOwner`, `CadreNode.planOwnerKeyRemoval`, `CadreNode.removeOwner`): the
+ * projection of the live `OwnerKey` rows an owner-key screen shows, the read-only plan behind a
+ * removal's confirmation step, the check that a requested re-vouch stays inside that plan, and
+ * the by-name refusals. Pure; the reads and writes themselves are `CadreNode`'s and
+ * `ControlDatabase`'s.
+ */
+
+import type {
+	CadreOwnerKey,
+	CadrePeerRow,
+	OwnerGrantStatus,
+	OwnerKeyAddRefusal,
+	OwnerKeyDependents,
+	OwnerKeyRemovalPlan,
+	OwnerKeyRemovalRefusal,
+	OwnerKeyRow,
+	RemoveOwnerOptions,
+} from './types.js';
+
+/**
+ * `CadreNode.addOwner` refused by name, before any write. `code` says which rule
+ * ({@link OwnerKeyAddRefusal}), for an app to switch on; the message is for a log.
+ */
+export class OwnerKeyAddRefusedError extends Error {
+	readonly code: OwnerKeyAddRefusal;
+	readonly key: string;
+
+	constructor(key: string, code: OwnerKeyAddRefusal) {
+		super(`Cannot add owner key ${key}: ${OWNER_KEY_ADD_REFUSAL_REASON[code]}`);
+		this.name = 'OwnerKeyAddRefusedError';
+		this.code = code;
+		this.key = key;
+	}
+}
+
+const OWNER_KEY_ADD_REFUSAL_REASON: Record<OwnerKeyAddRefusal, string> = {
+	'alone': 'this node has no connection to the rest of the cadre, and an owner key added now would reach no other machine; try again once connected',
+};
+
+/**
+ * `CadreNode.removeOwner` refused by name, before any write. `code` says which rule
+ * ({@link OwnerKeyRemovalRefusal}), for an app to switch on; the message is for a log.
+ */
+export class OwnerKeyRemovalRefusedError extends Error {
+	readonly code: OwnerKeyRemovalRefusal;
+	readonly key: string;
+
+	constructor(key: string, code: OwnerKeyRemovalRefusal) {
+		super(`Cannot remove owner key ${key}: ${OWNER_KEY_REMOVAL_REFUSAL_REASON[code]}`);
+		this.name = 'OwnerKeyRemovalRefusedError';
+		this.code = code;
+		this.key = key;
+	}
+}
+
+const OWNER_KEY_REMOVAL_REFUSAL_REASON: Record<OwnerKeyRemovalRefusal, string> = {
+	'not-an-owner': 'this node holds no enrolled owner key',
+	'unknown': 'it is not a live owner key here',
+	'last-owner': 'it is the only live owner key',
+	'self': 'it is the owner key of this node, and an owner key cannot sign its own removal; ask another owner key',
+	'alone': 'this node has no connection to the rest of the cadre, and an owner key re-vouched now would reach no other machine; try again once connected',
+};
+
+/** An owner key as an approval prompt names it: `"label" (key)`, or the key alone when it has no label. */
+export function namedOwnerKey(key: string, label: string | null): string {
+	return label === null ? key : `"${label}" (${key})`;
+}
+
+/**
+ * One {@link CadreOwnerKey} per live row, in the rows' order. `heldKey` is the key of this
+ * node's owner signer, if one is wired; `anchor` is this node's trusted-owner anchor.
+ */
+export function describeOwnerKeys(rows: readonly OwnerKeyRow[], heldKey: string | null, anchor: ReadonlySet<string>): CadreOwnerKey[] {
+	return rows.map((row) => ({
+		key: row.key,
+		label: row.label,
+		vouchedBy: row.vouchOwner,
+		heldHere: row.key === heldKey,
+		trusted: anchor.has(row.key),
+	}));
+}
+
+/** What {@link planOwnerKeyRemoval} judges from: one node's live rows and its own standing. */
+export interface OwnerKeyRemovalPlanInput {
+	key: string;
+	/** Live `CadrePeer` rows (`ControlDatabase.queryCadrePeers`). */
+	rows: readonly CadrePeerRow[];
+	/** Live `OwnerKey` rows (`ControlDatabase.queryOwnerKeyRows`). */
+	owners: readonly OwnerKeyRow[];
+	/** Every owner grant with its standing (`ControlDatabase.listOwnerGrantStatuses`); the live ones the key issued are the plan's `grants`. */
+	grants: readonly OwnerGrantStatus[];
+	selfPeerId: string | null;
+	/** The key of this node's owner signer when it is an enrolled owner (`CadreNode.ownerSignerEnrolledIn`), or null when it cannot sign owner writes. */
+	selfOwnerKey: string | null;
+	/** This node's trusted-owner anchor, for the listed entry's `trusted`. */
+	anchor: ReadonlySet<string>;
+}
+
+/**
+ * The plan for removing owner key `key` from these rows. The refusals come first and by name: a
+ * node that cannot sign; a key with no live row; the only live owner key (`MinOneOwner`), ahead
+ * of `self` so a sole owner asking to remove its own key hears the rule no other owner could
+ * get past either; and this node's own key, since the schema's remove branch wants a signer
+ * other than the removed key. With this node enrolled, a different live key always leaves two
+ * owners in one read, so `last-owner` reaches only that case, and concurrent removals elsewhere
+ * leave the schema to decide.
+ *
+ * `dependents` are the rows the 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 not among them. Its own
+ * `CadrePeer` row is re-vouched unasked (`revouchesOwnRow`): left on the removed key, every other
+ * machine would drop the remover. Its own `OwnerKey` row is reported as `ownDependency`, since
+ * re-vouching it would mean signing its own removal.
+ *
+ * `grants` are the live owner grants the key issued: a redemption wants a live issuer, so they
+ * stop working with the removal. They are listed, not withdrawn (`removeOwner` leaves them: a
+ * tombstone over a grant that can no longer be redeemed would add nothing).
+ */
+export function planOwnerKeyRemoval(input: OwnerKeyRemovalPlanInput): OwnerKeyRemovalPlan {
+	const row = input.owners.find((owner) => owner.key === input.key) ?? null;
+	return {
+		ownerKey: row === null ? null : describeOwnerKeys([row], input.selfOwnerKey, input.anchor)[0],
+		refusal: removalRefusalFor(input, row !== null),
+		dependents: dependentsOf(input),
+		revouchesOwnRow: input.rows.some((own) => own.peerId === input.selfPeerId && own.vouchOwner === input.key),
+		ownDependency: input.owners.some((own) => own.key === input.selfOwnerKey && own.vouchOwner === input.key),
+		grants: input.grants.filter((status) => status.live && status.grant.issuerKey === input.key).map((status) => status.grant),
+	};
+}
+
+function removalRefusalFor(input: OwnerKeyRemovalPlanInput, live: boolean): OwnerKeyRemovalPlan['refusal'] {
+	if (input.selfOwnerKey === null) {
+		return 'not-an-owner';
+	}
+	if (!live) {
+		return 'unknown';
+	}
+	if (input.owners.length <= 1) {
+		return 'last-owner';
+	}
+	if (input.key === input.selfOwnerKey) {
+		return 'self';
+	}
+	return null;
+}
+
+function dependentsOf(input: OwnerKeyRemovalPlanInput): OwnerKeyDependents {
+	return {
+		owners: input.owners
+			.filter((owner) => owner.vouchOwner === input.key && owner.key !== input.key && owner.key !== input.selfOwnerKey)
+			.map((owner) => owner.key),
+		peers: input.rows
+			.filter((row) => row.vouchOwner === input.key && row.peerId !== input.selfPeerId)
+			.map((row) => row.peerId),
+	};
+}
+
+/**
+ * The re-vouch `CadreNode.removeOwner` makes: what the caller asked for, checked against the
+ * plan, plus this node's own row (`selfPeerId`, first) when `plan.revouchesOwnRow`. Every
+ * requested key and peer must be in `plan.dependents`, so a caller cannot re-vouch a row the
+ * removed key never vouched. Throws naming the offenders, before anything is written.
+ * Duplicates are dropped.
+ */
+export function revouchWithinPlan(plan: OwnerKeyRemovalPlan, revouch: RemoveOwnerOptions['revouch'], selfPeerId: string | null): OwnerKeyDependents {
+	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(
+			`removeOwner: re-vouch names rows the removed owner key did not vouch: ${[...strayOwners, ...strayPeers].join(', ')}`,
+		);
+	}
+	return { owners, peers: plan.revouchesOwnRow && selfPeerId !== null ? [selfPeerId, ...peers] : peers };
+}

package/src/owner-signer.ts

@@ -0,0 +1,94 @@
+/**
+ * The owner signer: the one interface a node's owner signatures go through
+ * (`docs/architecture.md` → Owner Keys → The owner signer).
+ *
+ * cadre-core needs owner signatures, never an owner private key, so a backend that keeps the
+ * key where the node cannot read it (a hardware key, a vault behind biometrics) fits the same
+ * seam as {@link softwareOwnerSigner}.
+ *
+ * Imports only `@optimystic/quereus-plugin-crypto` and `uint8arrays`, so it loads on React
+ * Native and in the browser.
+ */
+import { toString as uint8ArrayToString } from 'uint8arrays';
+import { sign } from '@optimystic/quereus-plugin-crypto';
+import { ed25519PublicKeyFromPrivate, requireEd25519PrivateKeyB64 } from './ed25519-key.js';
+
+/** What a backend that asks the user shows them. */
+export interface OwnerSigningRequest {
+	/** The cadre the signatures are for. Every owner digest already binds it (`party_id()`); a prompting backend shows it. */
+	partyId: string;
+	/** What the user is approving, in plain words ("Remove the machine 12D3…", "Add owner key ‹label›"). */
+	action: string;
+}
+
+/** Signs one message (the raw bytes of an owner digest, e.g. `buildAuthorizationMessage` output); resolves to a base64url Ed25519 signature. */
+export type OwnerSign = (message: Uint8Array) => Promise<string>;
+
+/**
+ * An owner key the node can ask for signatures.
+ *
+ * One action, one {@link approve} call, however many rows it signs: the control schema verifies
+ * one signature per row, and one owner action writes several (a removal signs the delete and its
+ * `Revocation` tombstone; a machine removal signs many). A hardware or biometric backend prompts
+ * once per call, as PIV touch caching and the platform vaults' authentication-validity windows
+ * allow. Handing the signer every digest up front was declined: each writer reads the stamps it
+ * signs inside its write lock, so precomputing them would duplicate each writer's digest
+ * construction outside it.
+ */
+export interface OwnerSigner {
+	/** base64url Ed25519 public key — the `OwnerKey.Key` this signer signs for. */
+	readonly publicKey: string;
+	/**
+	 * Run one user-approved action. A backend that prompts does so at most once per call and may
+	 * keep the user's presence until `body` settles. Rejects with {@link OwnerSigningDeclinedError}
+	 * when the user declines, and with whatever `body` rejects with otherwise.
+	 */
+	approve<T>(request: OwnerSigningRequest, body: (sign: OwnerSign) => Promise<T>): Promise<T>;
+}
+
+/**
+ * Run `body` inside the caller's open approval when it passes `sign`, else inside one new
+ * approval of `signer` for `request`. An owner write that is sometimes a whole action and
+ * sometimes one step of a larger one takes an optional `sign` and goes through this, so the
+ * larger action still asks once.
+ */
+export async function withinOwnerApproval<T>(
+	signer: OwnerSigner,
+	request: OwnerSigningRequest,
+	sign: OwnerSign | undefined,
+	body: (sign: OwnerSign) => Promise<T>
+): Promise<T> {
+	return sign ? await body(sign) : await signer.approve(request, body);
+}
+
+/** Thrown by a prompting backend when the user declines or the prompt times out. */
+export class OwnerSigningDeclinedError extends Error {
+	readonly request: OwnerSigningRequest;
+
+	constructor(request: OwnerSigningRequest, options?: { cause?: unknown }) {
+		super(`Owner approval was declined or timed out: ${request.action}`, options);
+		this.name = 'OwnerSigningDeclinedError';
+		this.request = request;
+	}
+}
+
+/**
+ * An {@link OwnerSigner} over a private key held in memory: never prompts, signs whatever its
+ * `approve` body asks. Its signed input is the digest bytes, base64url-encoded, so its signatures
+ * are byte-for-byte those of any signer that signs the raw bytes with the same key (Ed25519 is
+ * deterministic).
+ *
+ * @param privateKeyB64 - The owner key's 32-byte Ed25519 seed, base64url.
+ * @throws If `privateKeyB64` is not a 32-byte seed in base64url.
+ */
+export function softwareOwnerSigner(privateKeyB64: string): OwnerSigner {
+	const privateKey = requireEd25519PrivateKeyB64(privateKeyB64, 'owner private key');
+	const signMessage: OwnerSign = async (message) =>
+		sign(uint8ArrayToString(message, 'base64url'), privateKey, 'ed25519', 'base64url', 'base64url', 'base64url') as string;
+	return {
+		publicKey: ed25519PublicKeyFromPrivate(privateKey),
+		async approve<T>(_request: OwnerSigningRequest, body: (sign: OwnerSign) => Promise<T>): Promise<T> {
+			return await body(signMessage);
+		},
+	};
+}

package/src/peer-addr-book.ts

@@ -4,7 +4,7 @@
  * — Optimystic's cluster client, repo client, FRET ping/announce, all funnelling
  * into `libp2p.dialProtocol(peerId, …)` — has an address to use for a sibling
  * whose connection has dropped, instead of failing with `NoValidAddressesError`
- * until the next reconcile pass happens to re-dial it.
+ * until the reconcile pass the drop starts re-dials it.
  *
  * Shared by the control-cohort reconcile pass and the strand one (both in
  * `CadreNode`): each resolves a peer's addresses its own way and then needs
@@ -190,9 +190,10 @@ function lastAddressedPeerId(parsed: Multiaddr): string | null {
  * that id is the address's FIRST `/p2p/` component (`dedupe-addresses.js`), so a
  * plain address round-trips without its suffix while a relayed one — whose first
  * `/p2p/` names the relay — keeps it. Comparing and de-duplicating on this
- * suffix-stripped form matches either shape.
+ * suffix-stripped form matches either shape. `CadreNode.claimNode` compares a QR
+ * code's addresses with a connection's remote address on it for the same reason.
  */
-function addrKey(addr: string, peerId: PeerId): string {
+export function addrKey(addr: string, peerId: PeerId): string {
   const suffix = `/p2p/${peerId.toString()}`;
   return addr.endsWith(suffix) ? addr.slice(0, -suffix.length) : addr;
 }