@serfab/cadre-core 0.10.0 → 0.12.0

package/src/trusted-owner-store-file.ts

@@ -1,41 +1,41 @@
-/**
- * Node-only file-backed {@link TrustedOwnerStore}: one JSON file per party under
- * a configured directory (the node's state directory — `cadre-cli` passes
- * `ResolvedConfig.nodeStateDir`), holding the node-local, non-replicated
- * trusted-owner anchor.
- *
- * Nothing but the file itself lives here: the anchor's envelope, load policy,
- * per-entry validation and serialised snapshot writes are cross-platform in
- * `PersistentTrustedOwnerStore` / `node-local-snapshot.ts`, and the file is a
- * `FileDurableSlot`. This module exists only so the `node:fs` edge stays out of
- * the package's cross-platform default entry (`./index.js`) — import it from
- * the dedicated subpath instead:
- *
- * ```ts
- * import { FileTrustedOwnerStore } from '@serfab/cadre-core/trusted-owner-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 (same
- * isolation pattern as `key-store-file.ts`).
- */
-import { FileDurableSlot } from './file-durable-slot.js';
-import { PersistentTrustedOwnerStore } from './trusted-owner-store.js';
-import type { TrustedOwnerStore } from './trusted-owner-store.js';
-
-/** Base name of the anchor file: `<dir>/trusted-owners.<encoded partyId>.json`. */
-const SLOT_NAME = 'trusted-owners';
-
-/**
- * File-backed {@link TrustedOwnerStore}. Open via {@link open}, which loads the
- * existing file and returns the cross-platform store over it; an absent, corrupt, or wrong-party file is a cold
- * start (empty anchor), while a present-but-unreadable file throws. Those rules
- * and their reasoning live on `NodeLocalSnapshot.open` — they are properties of
- * every persistent backend, not of this one.
- */
-export const FileTrustedOwnerStore = {
-	/** Load (or cold-start) the party's anchor from a file in `dir`. */
-	async open(dir: string, partyId: string): Promise<TrustedOwnerStore> {
-		return PersistentTrustedOwnerStore.open(new FileDurableSlot(dir, SLOT_NAME, partyId), partyId);
-	}
-};
+/**
+ * Node-only file-backed {@link TrustedOwnerStore}: one JSON file per party under
+ * a configured directory (the node's state directory — `cadre-cli` passes
+ * `ResolvedConfig.nodeStateDir`), holding the node-local, non-replicated
+ * trusted-owner anchor.
+ *
+ * Nothing but the file itself lives here: the anchor's envelope, load policy,
+ * per-entry validation and serialised snapshot writes are cross-platform in
+ * `PersistentTrustedOwnerStore` / `node-local-snapshot.ts`, and the file is a
+ * `FileDurableSlot`. This module exists only so the `node:fs` edge stays out of
+ * the package's cross-platform default entry (`./index.js`) — import it from
+ * the dedicated subpath instead:
+ *
+ * ```ts
+ * import { FileTrustedOwnerStore } from '@serfab/cadre-core/trusted-owner-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 (same
+ * isolation pattern as `key-store-file.ts`).
+ */
+import { FileDurableSlot } from './file-durable-slot.js';
+import { PersistentTrustedOwnerStore } from './trusted-owner-store.js';
+import type { TrustedOwnerStore } from './trusted-owner-store.js';
+
+/** Base name of the anchor file: `<dir>/trusted-owners.<encoded partyId>.json`. */
+const SLOT_NAME = 'trusted-owners';
+
+/**
+ * File-backed {@link TrustedOwnerStore}. Open via {@link open}, which loads the
+ * existing file and returns the cross-platform store over it; an absent, corrupt, or wrong-party file is a cold
+ * start (empty anchor), while a present-but-unreadable file throws. Those rules
+ * and their reasoning live on `NodeLocalSnapshot.open` — they are properties of
+ * every persistent backend, not of this one.
+ */
+export const FileTrustedOwnerStore = {
+	/** Load (or cold-start) the party's anchor from a file in `dir`. */
+	async open(dir: string, partyId: string): Promise<TrustedOwnerStore> {
+		return PersistentTrustedOwnerStore.open(new FileDurableSlot(dir, SLOT_NAME, partyId), partyId);
+	}
+};

package/src/trusted-owner-store.ts

@@ -1,171 +1,171 @@
-/**
- * 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 `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() });
+	}
+}