@serfab/cadre-core 1.13.0 → 1.15.0

package/src/trusted-owner-store.ts

@@ -1,171 +1,242 @@
-/**
- * Node-local, NON-replicated trusted-owner anchor.
- *
- * The replicated `CadreControl.OwnerKey` table cannot anchor trust: any
- * connecting node can genesis-insert its own key into its local table and that
- * row replicates into every peer's copy, so "is this key in `OwnerKey`?" can be
- * made true by a stranger. This store is the anchor that CAN be trusted — a
- * per-party, on-device record of owner keys established OUT OF BAND: founding
- * the party (genesis self-trust), the pinned keys carried by the `CadreInvite`
- * that enrolled this node, or an explicit operator pin. It is never written
- * from replicated control state; that is the whole point.
- *
- * Three implementations:
- *  - {@link MemoryTrustedOwnerStore} (this module, cross-platform) — ephemeral;
- *    the default when no store is injected via `CadreNodeConfig.trustedOwners`.
- *  - {@link PersistentTrustedOwnerStore} (this module, cross-platform) — durable
- *    over any `DurableSlot` the embedding app supplies (IndexedDB, SecureStore,
- *    SQLite, …). The load/persist policy lives in `node-local-snapshot.ts`; read
- *    {@link NodeLocalSnapshot.open} for what an absent, corrupt, foreign-party
- *    or unreadable slot does.
- *  - `FileTrustedOwnerStore` — the above over a Node file in the node's state
- *    directory; Node-only, behind the subpath
- *    `@serfab/cadre-core/trusted-owner-store-file` (same isolation pattern as
- *    `key-store-file`) so `node:fs` never lands in the RN/browser entry graph.
- *
- * Keys are additive: nothing in this interface removes a key (owner revocation
- * is out of scope here and tracked with the broader control-sync design).
- */
-import debug from 'debug';
-import { NodeLocalSnapshot, type DurableSlot, type NodeLocalSnapshotSpec } from './node-local-snapshot.js';
-
-const log = debug('sereus:cadre:trusted-owner-store');
-
-/** How an owner key entered the anchor (out-of-band provenance). */
-export type TrustSource = 'genesis' | 'invite' | 'operator';
-
-export interface TrustedOwnerStore {
-	/** Party this anchor is scoped to. */
-	readonly partyId: string;
-
-	/** Is this ed25519 (base64url) key one of my party's out-of-band-trusted owners? */
-	has(ownerKey: string): boolean;
-
-	/**
-	 * All anchored owner keys (e.g. for seed-trust `knownOwnerKeys`).
-	 *
-	 * NOTE: every backend copies into a fresh Set per call (so the result is a
-	 * snapshot decoupled from later `trust()` calls). Anchors hold a handful of
-	 * keys and callers are per-seed, so the copy is free today; if a hot path
-	 * ever calls this per message, prefer `has()` or cache the snapshot.
-	 */
-	all(): ReadonlySet<string>;
-
-	/**
-	 * Add a key established out of band (genesis self-trust / invite pin /
-	 * operator pin). Idempotent: re-trusting a known key is a no-op that keeps
-	 * the original source. Implementations MUST reflect the key in {@link has} /
-	 * {@link all} synchronously; the returned promise tracks durability only
-	 * (a persistent backend's write), so a synchronous caller may safely consult
-	 * the store right after invoking this.
-	 */
-	trust(ownerKey: string, source: TrustSource): Promise<void>;
-}
-
-/**
- * Ephemeral in-memory anchor for nodes without durable storage (tests, browser
- * demos, not-yet-persisted mobile). Same contract, no disk: trust established
- * here must be re-supplied (invite / operator pin) on the next process.
- */
-export class MemoryTrustedOwnerStore implements TrustedOwnerStore {
-	private readonly keys = new Map<string, TrustSource>();
-
-	constructor(readonly partyId: string) {}
-
-	has(ownerKey: string): boolean {
-		return this.keys.has(ownerKey);
-	}
-
-	all(): ReadonlySet<string> {
-		return new Set(this.keys.keys());
-	}
-
-	async trust(ownerKey: string, source: TrustSource): Promise<void> {
-		if (this.keys.has(ownerKey)) {
-			return;
-		}
-		this.keys.set(ownerKey, source);
-		log('trusted owner key anchored (party=%s, source=%s)', this.partyId, source);
-	}
-}
-
-/** One anchored key as persisted: provenance + wall-clock trust time (ms). */
-interface TrustedOwnerEntry {
-	source: TrustSource;
-	trustedAt: number;
-}
-
-const KNOWN_SOURCES: ReadonlySet<string> = new Set<TrustSource>(['genesis', 'invite', 'operator']);
-
-/**
- * What the anchor persists: `owners` maps ownerKey (base64url) -> provenance.
- *
- * One unusable entry discards the WHOLE record: trusting a subset of the keys a
- * record claims is a silent, security-relevant downgrade, so a record that
- * cannot be read in full is treated as no anchor at all (see
- * `UnusableEntryPolicy` in `node-local-snapshot.ts`).
- */
-const TRUSTED_OWNER_SNAPSHOT: NodeLocalSnapshotSpec<TrustedOwnerEntry> = {
-	label: 'trusted-owner anchor',
-	payloadKey: 'owners',
-	unusableEntry: 'discard-all',
-	acceptEntry: (_ownerKey, entry) => {
-		if (typeof entry !== 'object' || entry === null) return undefined;
-		const { source, trustedAt } = entry as { source?: unknown; trustedAt?: unknown };
-		if (typeof source !== 'string' || !KNOWN_SOURCES.has(source)) return undefined;
-		if (typeof trustedAt !== 'number') return undefined;
-		return { source: source as TrustSource, trustedAt };
-	}
-};
-
-/**
- * Durable {@link TrustedOwnerStore} over an app-supplied {@link DurableSlot} —
- * the cross-platform half of every persistent backend (the Node
- * `FileTrustedOwnerStore` is this class over a file slot).
- *
- * Construct via {@link open}. Load and persist policy — what an absent,
- * corrupt, foreign-party or unreadable slot does, and what a failed persist
- * does — is documented once on `NodeLocalSnapshot`; this class only supplies
- * the payload shape and the anchor's whole-record-on-bad-entry policy.
- */
-export class PersistentTrustedOwnerStore implements TrustedOwnerStore {
-	private constructor(private readonly snapshot: NodeLocalSnapshot<TrustedOwnerEntry>) {}
-
-	/** Load (or cold-start) the party's anchor from `slot`. */
-	static async open(slot: DurableSlot, partyId: string): Promise<PersistentTrustedOwnerStore> {
-		return new PersistentTrustedOwnerStore(
-			await NodeLocalSnapshot.open(slot, partyId, TRUSTED_OWNER_SNAPSHOT)
-		);
-	}
-
-	get partyId(): string {
-		return this.snapshot.partyId;
-	}
-
-	has(ownerKey: string): boolean {
-		return this.snapshot.has(ownerKey);
-	}
-
-	all(): ReadonlySet<string> {
-		return this.snapshot.keySnapshot();
-	}
-
-	/**
-	 * Anchor a key: visible via {@link has} / {@link all} synchronously, then the
-	 * full snapshot is persisted (see `NodeLocalSnapshot.put`).
-	 */
-	trust(ownerKey: string, source: TrustSource): Promise<void> {
-		if (this.snapshot.has(ownerKey)) {
-			// Idempotent: re-enrollment / restart re-seeding keeps the original
-			// provenance and skips the write entirely.
-			// NOTE: this resolves immediately rather than joining the write chain, so
-			// re-trusting a key whose first persist is still in flight does not await
-			// that persist. Harmless for the seeding callers (they re-trust only after
-			// the original settled, or do not await at all); chain it if a caller ever
-			// needs "durable by the time trust() resolves" for a repeat key.
-			return Promise.resolve();
-		}
-		log('trusted owner key anchored (party=%s, source=%s); persisting', this.partyId, source);
-		return this.snapshot.put(ownerKey, { source, trustedAt: Date.now() });
-	}
-}
+/**
+ * Node-local, NON-replicated trusted-owner anchor.
+ *
+ * The replicated `CadreControl.OwnerKey` table cannot anchor trust: any
+ * connecting node can genesis-insert its own key into its local table and that
+ * row replicates into every peer's copy, so "is this key in `OwnerKey`?" can be
+ * made true by a stranger. This store is the anchor that CAN be trusted — a
+ * per-party, on-device record of owner keys established OUT OF BAND: founding
+ * the party (genesis self-trust), the pinned keys carried by the cadre invitation
+ * that enrolled this node, an explicit operator pin, or the claim of a brand-new
+ * node by whoever holds its one-time claim secret. It is never written from
+ * replicated control state; that is the whole point.
+ *
+ * Three implementations:
+ *  - {@link MemoryTrustedOwnerStore} (this module, cross-platform) — ephemeral;
+ *    the default when no store is injected via `CadreNodeConfig.trustedOwners`.
+ *  - {@link PersistentTrustedOwnerStore} (this module, cross-platform) — durable
+ *    over any `DurableSlot` the embedding app supplies (IndexedDB, SecureStore,
+ *    SQLite, …). The load/persist policy lives in `node-local-snapshot.ts`; read
+ *    {@link NodeLocalSnapshot.open} for what an absent, corrupt, foreign-party
+ *    or unreadable slot does.
+ *  - `FileTrustedOwnerStore` — the above over a Node file in the node's state
+ *    directory; Node-only, behind the subpath
+ *    `@serfab/cadre-core/trusted-owner-store-file` (same isolation pattern as
+ *    `key-store-file`) so `node:fs` never lands in the RN/browser entry graph.
+ *
+ * The anchor follows the replicated `OwnerKey` table along VERIFIABLE chains only
+ * (`CadreNode.syncOwnerAnchor`, `owner-anchor-sync.ts`): a key whose stored proof verifies
+ * against a key already anchored enters under source `chain`, and a key named by a
+ * tombstone whose stored signer is anchored leaves. The out-of-band entries are the base
+ * that derivation starts from; a replicated row can never seat itself here.
+ *
+ * Two callers remove keys: the claim-secret trust policy rolling back a claim whose
+ * persist failed (`claimSecretTrustPolicy` in `seed-trust-policy.ts`), and the anchor
+ * sync applying a verifiable `OwnerKey` tombstone or pruning a `chain` entry whose row
+ * is gone. Nothing else removes a key.
+ */
+import debug from 'debug';
+import { NodeLocalSnapshot, type DurableSlot, type NodeLocalSnapshotSpec } from './node-local-snapshot.js';
+
+const log = debug('sereus:cadre:trusted-owner-store');
+
+/**
+ * How an owner key entered the anchor. Every source but `chain` is out-of-band provenance
+ * and forms the base the anchor sync derives from; `claim` is the durable "this node has
+ * been claimed" marker: the first seed whose sender proved it held the node's claim secret
+ * anchored its signer under this source. `chain` marks a key derived from the replicated
+ * `OwnerKey` table through a proof that verified against a key already anchored
+ * (`CadreNode.syncOwnerAnchor`); the sync keeps such an entry while its row is live and
+ * prunes it once the row is gone, which a base entry never is.
+ */
+export type TrustSource = 'genesis' | 'invite' | 'operator' | 'claim' | 'chain';
+
+export interface TrustedOwnerStore {
+	/** Party this anchor is scoped to. */
+	readonly partyId: string;
+
+	/** Is this ed25519 (base64url) key one of my party's out-of-band-trusted owners? */
+	has(ownerKey: string): boolean;
+
+	/**
+	 * All anchored owner keys (e.g. for seed-trust `knownOwnerKeys`).
+	 *
+	 * NOTE: every backend copies into a fresh Set per call (so the result is a
+	 * snapshot decoupled from later `trust()` calls). Anchors hold a handful of
+	 * keys and callers are per-seed, so the copy is free today; if a hot path
+	 * ever calls this per message, prefer `has()` or cache the snapshot.
+	 */
+	all(): ReadonlySet<string>;
+
+	/**
+	 * Every anchored key with its provenance, as a snapshot (same copy contract as
+	 * {@link all}). The anchor sync splits the base (every source but `chain`) from the
+	 * derived entries with this.
+	 */
+	sources(): ReadonlyMap<string, TrustSource>;
+
+	/**
+	 * Add a key. Idempotent with one asymmetry in provenance: re-trusting a known key
+	 * keeps its source, EXCEPT that an out-of-band source over an existing `chain` entry
+	 * rewrites the provenance (out of band wins: the key is then base, and a later sync
+	 * no longer prunes it when its row goes), while `trust(key, 'chain')` over any
+	 * existing entry is a no-op. Implementations MUST reflect the key in {@link has} /
+	 * {@link all} synchronously; the returned promise tracks durability only
+	 * (a persistent backend's write), so a synchronous caller may safely consult
+	 * the store right after invoking this.
+	 */
+	trust(ownerKey: string, source: TrustSource): Promise<void>;
+
+	/**
+	 * Drop a key, with {@link trust}'s contract: gone from {@link has} / {@link all}
+	 * synchronously, the returned promise tracks durability. Removing an absent key
+	 * is a no-op. See the module doc for who may call this.
+	 */
+	remove(ownerKey: string): Promise<void>;
+}
+
+/**
+ * Ephemeral in-memory anchor for nodes without durable storage (tests, browser
+ * demos, not-yet-persisted mobile). Same contract, no disk: trust established
+ * here must be re-supplied (invite / operator pin) on the next process.
+ */
+export class MemoryTrustedOwnerStore implements TrustedOwnerStore {
+	private readonly keys = new Map<string, TrustSource>();
+
+	constructor(readonly partyId: string) {}
+
+	has(ownerKey: string): boolean {
+		return this.keys.has(ownerKey);
+	}
+
+	all(): ReadonlySet<string> {
+		return new Set(this.keys.keys());
+	}
+
+	sources(): ReadonlyMap<string, TrustSource> {
+		return new Map(this.keys);
+	}
+
+	async trust(ownerKey: string, source: TrustSource): Promise<void> {
+		if (!provenanceChanges(this.keys.get(ownerKey), source)) {
+			return;
+		}
+		this.keys.set(ownerKey, source);
+		log('trusted owner key anchored (party=%s, source=%s)', this.partyId, source);
+	}
+
+	async remove(ownerKey: string): Promise<void> {
+		if (this.keys.delete(ownerKey)) {
+			log('trusted owner key removed (party=%s)', this.partyId);
+		}
+	}
+}
+
+/**
+ * Does `trust(key, source)` write, given the key's current provenance (`undefined` when
+ * absent)? The one rule both backends share (see {@link TrustedOwnerStore.trust}): an absent
+ * key always lands; a `chain` entry is promoted by any out-of-band source; everything else
+ * keeps its original provenance.
+ */
+function provenanceChanges(current: TrustSource | undefined, source: TrustSource): boolean {
+	return current === undefined || (current === 'chain' && source !== 'chain');
+}
+
+/** One anchored key as persisted: provenance + wall-clock trust time (ms). */
+interface TrustedOwnerEntry {
+	source: TrustSource;
+	trustedAt: number;
+}
+
+// Every TrustSource must be listed: under the discard-all policy below, one entry with a
+// source this set does not know discards the WHOLE anchor on reload, so a node whose only
+// owner was anchored by a claim would silently come back unclaimed.
+const KNOWN_SOURCES: ReadonlySet<string> = new Set<TrustSource>(['genesis', 'invite', 'operator', 'claim', 'chain']);
+
+/**
+ * What the anchor persists: `owners` maps ownerKey (base64url) -> provenance.
+ *
+ * One unusable entry discards the WHOLE record: trusting a subset of the keys a
+ * record claims is a silent, security-relevant downgrade, so a record that
+ * cannot be read in full is treated as no anchor at all (see
+ * `UnusableEntryPolicy` in `node-local-snapshot.ts`).
+ */
+const TRUSTED_OWNER_SNAPSHOT: NodeLocalSnapshotSpec<TrustedOwnerEntry> = {
+	label: 'trusted-owner anchor',
+	payloadKey: 'owners',
+	unusableEntry: 'discard-all',
+	acceptEntry: (_ownerKey, entry) => {
+		if (typeof entry !== 'object' || entry === null) return undefined;
+		const { source, trustedAt } = entry as { source?: unknown; trustedAt?: unknown };
+		if (typeof source !== 'string' || !KNOWN_SOURCES.has(source)) return undefined;
+		if (typeof trustedAt !== 'number') return undefined;
+		return { source: source as TrustSource, trustedAt };
+	}
+};
+
+/**
+ * Durable {@link TrustedOwnerStore} over an app-supplied {@link DurableSlot} —
+ * the cross-platform half of every persistent backend (the Node
+ * `FileTrustedOwnerStore` is this class over a file slot).
+ *
+ * Construct via {@link open}. Load and persist policy — what an absent,
+ * corrupt, foreign-party or unreadable slot does, and what a failed persist
+ * does — is documented once on `NodeLocalSnapshot`; this class only supplies
+ * the payload shape and the anchor's whole-record-on-bad-entry policy.
+ */
+export class PersistentTrustedOwnerStore implements TrustedOwnerStore {
+	private constructor(private readonly snapshot: NodeLocalSnapshot<TrustedOwnerEntry>) {}
+
+	/** Load (or cold-start) the party's anchor from `slot`. */
+	static async open(slot: DurableSlot, partyId: string): Promise<PersistentTrustedOwnerStore> {
+		return new PersistentTrustedOwnerStore(
+			await NodeLocalSnapshot.open(slot, partyId, TRUSTED_OWNER_SNAPSHOT)
+		);
+	}
+
+	get partyId(): string {
+		return this.snapshot.partyId;
+	}
+
+	has(ownerKey: string): boolean {
+		return this.snapshot.has(ownerKey);
+	}
+
+	all(): ReadonlySet<string> {
+		return this.snapshot.keySnapshot();
+	}
+
+	sources(): ReadonlyMap<string, TrustSource> {
+		return new Map(Array.from(this.snapshot.entrySnapshot(), ([key, entry]) => [key, entry.source]));
+	}
+
+	/**
+	 * Anchor a key: visible via {@link has} / {@link all} synchronously, then the
+	 * full snapshot is persisted (see `NodeLocalSnapshot.put`).
+	 */
+	trust(ownerKey: string, source: TrustSource): Promise<void> {
+		if (!provenanceChanges(this.snapshot.get(ownerKey)?.source, source)) {
+			// Idempotent: re-enrollment / restart re-seeding keeps the original
+			// provenance and skips the write entirely.
+			// NOTE: this resolves immediately rather than joining the write chain, so
+			// re-trusting a key whose first persist is still in flight does not await
+			// that persist. Harmless for the seeding callers (they re-trust only after
+			// the original settled, or do not await at all); chain it if a caller ever
+			// needs "durable by the time trust() resolves" for a repeat key.
+			return Promise.resolve();
+		}
+		log('trusted owner key anchored (party=%s, source=%s); persisting', this.partyId, source);
+		return this.snapshot.put(ownerKey, { source, trustedAt: Date.now() });
+	}
+
+	/**
+	 * Drop a key: gone from {@link has} / {@link all} synchronously, then the full
+	 * snapshot is persisted (see `NodeLocalSnapshot.remove`).
+	 */
+	remove(ownerKey: string): Promise<void> {
+		if (this.snapshot.has(ownerKey)) {
+			log('trusted owner key removed (party=%s); persisting', this.partyId);
+		}
+		return this.snapshot.remove(ownerKey);
+	}
+}