@serfab/cadre-core 0.10.0 → 0.11.0

package/src/identity-key.ts

@@ -1,109 +1,109 @@
-/**
- * identity-key — the load-or-create rule for a {@link KeyStore}-backed node
- * identity, plus the "prove you hold this node key" signer built on top of it.
- *
- * Both live here because both are needed *outside* `CadreNode`: an embedding app
- * (the React Native reference app) has to resolve its identity key before the node
- * is constructed, so it can sign an out-of-band HTTP request with the same key the
- * node will then load. Keeping one copy of the load-or-create rule is load-bearing
- * — a second copy that drifted could generate a fresh key and orphan the real
- * identity.
- *
- * Dependency-free beyond `@libp2p/crypto` + `uint8arrays` (both already core
- * dependencies), so this module is safe in every (RN / browser / Node) entry graph.
- */
-import debug from 'debug';
-import { generateKeyPair, privateKeyToProtobuf, privateKeyFromProtobuf, publicKeyToProtobuf } from '@libp2p/crypto/keys';
-import { toString as uint8ArrayToString } from 'uint8arrays';
-import type { PrivateKey } from '@libp2p/interface';
-import { DEFAULT_IDENTITY_KEY_ID, type KeyId, type KeyStore } from './key-store.js';
-
-const log = debug('sereus:cadre:identity-key');
-
-/**
- * Load the node identity key from `keyStore`, generating and persisting a fresh
- * Ed25519 key when the slot is empty.
- *
- * A rejected `get` (e.g. {@link KeyStoreAccessError} from a cancelled biometric
- * prompt) **propagates** — we never fall through to generation on a read error,
- * because that would silently orphan an existing but momentarily unreadable
- * identity. Corrupt bytes in the slot likewise throw rather than regenerate.
- *
- * Idempotent in effect: a second call on a populated store loads the stored key
- * and writes nothing.
- *
- * @param keyStore - Backend the identity is read from / persisted to.
- * @param keyId - Slot id; defaults to {@link DEFAULT_IDENTITY_KEY_ID}.
- * @returns The resolved libp2p private key.
- */
-export async function loadOrCreateIdentityKey(
-  keyStore: KeyStore,
-  keyId: KeyId = DEFAULT_IDENTITY_KEY_ID
-): Promise<PrivateKey> {
-  // A rejection here (e.g. KeyStoreAccessError) must propagate — do NOT fall
-  // through to generation, which would orphan an existing but unreadable key.
-  const bytes = await keyStore.get(keyId);
-  if (bytes) {
-    // Corrupt/garbage bytes throw here; surface loudly rather than
-    // regenerating (which would orphan the real identity).
-    const loaded = privateKeyFromProtobuf(bytes);
-    log('Identity key loaded from key store (slot present)');
-    return loaded;
-  }
-
-  const generated = await generateKeyPair('Ed25519');
-  await keyStore.set(keyId, privateKeyToProtobuf(generated));
-  log('Identity key generated and persisted to key store (first run)');
-  return generated;
-}
-
-/**
- * Proof-of-possession signer for a node key, for out-of-band HTTP services that
- * want to attribute a request to a peer id.
- *
- * Deliberately generic — it carries no ICE/TURN vocabulary, and the message it
- * signs is the caller's business. The one consumer today is the reference apps'
- * `loadIceConfig`, which signs the TURN credential issuer's peer assertion; those
- * files mirror this interface structurally rather than importing it, so they stay
- * dependency-free.
- */
-export interface PeerKeySigner {
-  /** base58btc peer id — the same string libp2p reports for this node. */
-  readonly peerId: string;
-  /** base64url of the libp2p protobuf-encoded public key. */
-  readonly publicKeyB64: string;
-  /** Sign the UTF-8 bytes of `message`; resolves to a base64url signature. */
-  sign(message: string): Promise<string>;
-}
-
-/**
- * Wrap a libp2p private key as a {@link PeerKeySigner}.
- *
- * Ed25519 only: the peer id is derived as an identity multihash (so
- * `publicKey.toString()` already *is* the base58btc peer id — no `@libp2p/peer-id`
- * round trip needed), and verifiers of this proof accept nothing else.
- *
- * @param privateKey - The node's libp2p Ed25519 private key.
- * @returns A signer exposing the peer id, the encoded public key, and `sign`.
- * @throws If the key is not Ed25519.
- */
-export function peerKeySigner(privateKey: PrivateKey): PeerKeySigner {
-  if (privateKey.type !== 'Ed25519') {
-    throw new Error(`peerKeySigner requires an Ed25519 key, got ${privateKey.type}`);
-  }
-
-  const publicKey = privateKey.publicKey;
-  // For Ed25519 the public key's digest is an identity multihash, so its string
-  // form is the peer id itself — the same value `peerIdFromPrivateKey` produces.
-  const peerId = publicKey.toString();
-  const publicKeyB64 = uint8ArrayToString(publicKeyToProtobuf(publicKey), 'base64url');
-
-  return {
-    peerId,
-    publicKeyB64,
-    async sign(message: string): Promise<string> {
-      const signature = await privateKey.sign(new TextEncoder().encode(message));
-      return uint8ArrayToString(signature, 'base64url');
-    }
-  };
-}
+/**
+ * identity-key — the load-or-create rule for a {@link KeyStore}-backed node
+ * identity, plus the "prove you hold this node key" signer built on top of it.
+ *
+ * Both live here because both are needed *outside* `CadreNode`: an embedding app
+ * (the React Native reference app) has to resolve its identity key before the node
+ * is constructed, so it can sign an out-of-band HTTP request with the same key the
+ * node will then load. Keeping one copy of the load-or-create rule is load-bearing
+ * — a second copy that drifted could generate a fresh key and orphan the real
+ * identity.
+ *
+ * Dependency-free beyond `@libp2p/crypto` + `uint8arrays` (both already core
+ * dependencies), so this module is safe in every (RN / browser / Node) entry graph.
+ */
+import debug from 'debug';
+import { generateKeyPair, privateKeyToProtobuf, privateKeyFromProtobuf, publicKeyToProtobuf } from '@libp2p/crypto/keys';
+import { toString as uint8ArrayToString } from 'uint8arrays';
+import type { PrivateKey } from '@libp2p/interface';
+import { DEFAULT_IDENTITY_KEY_ID, type KeyId, type KeyStore } from './key-store.js';
+
+const log = debug('sereus:cadre:identity-key');
+
+/**
+ * Load the node identity key from `keyStore`, generating and persisting a fresh
+ * Ed25519 key when the slot is empty.
+ *
+ * A rejected `get` (e.g. {@link KeyStoreAccessError} from a cancelled biometric
+ * prompt) **propagates** — we never fall through to generation on a read error,
+ * because that would silently orphan an existing but momentarily unreadable
+ * identity. Corrupt bytes in the slot likewise throw rather than regenerate.
+ *
+ * Idempotent in effect: a second call on a populated store loads the stored key
+ * and writes nothing.
+ *
+ * @param keyStore - Backend the identity is read from / persisted to.
+ * @param keyId - Slot id; defaults to {@link DEFAULT_IDENTITY_KEY_ID}.
+ * @returns The resolved libp2p private key.
+ */
+export async function loadOrCreateIdentityKey(
+  keyStore: KeyStore,
+  keyId: KeyId = DEFAULT_IDENTITY_KEY_ID
+): Promise<PrivateKey> {
+  // A rejection here (e.g. KeyStoreAccessError) must propagate — do NOT fall
+  // through to generation, which would orphan an existing but unreadable key.
+  const bytes = await keyStore.get(keyId);
+  if (bytes) {
+    // Corrupt/garbage bytes throw here; surface loudly rather than
+    // regenerating (which would orphan the real identity).
+    const loaded = privateKeyFromProtobuf(bytes);
+    log('Identity key loaded from key store (slot present)');
+    return loaded;
+  }
+
+  const generated = await generateKeyPair('Ed25519');
+  await keyStore.set(keyId, privateKeyToProtobuf(generated));
+  log('Identity key generated and persisted to key store (first run)');
+  return generated;
+}
+
+/**
+ * Proof-of-possession signer for a node key, for out-of-band HTTP services that
+ * want to attribute a request to a peer id.
+ *
+ * Deliberately generic — it carries no ICE/TURN vocabulary, and the message it
+ * signs is the caller's business. The one consumer today is the reference apps'
+ * `loadIceConfig`, which signs the TURN credential issuer's peer assertion; those
+ * files mirror this interface structurally rather than importing it, so they stay
+ * dependency-free.
+ */
+export interface PeerKeySigner {
+  /** base58btc peer id — the same string libp2p reports for this node. */
+  readonly peerId: string;
+  /** base64url of the libp2p protobuf-encoded public key. */
+  readonly publicKeyB64: string;
+  /** Sign the UTF-8 bytes of `message`; resolves to a base64url signature. */
+  sign(message: string): Promise<string>;
+}
+
+/**
+ * Wrap a libp2p private key as a {@link PeerKeySigner}.
+ *
+ * Ed25519 only: the peer id is derived as an identity multihash (so
+ * `publicKey.toString()` already *is* the base58btc peer id — no `@libp2p/peer-id`
+ * round trip needed), and verifiers of this proof accept nothing else.
+ *
+ * @param privateKey - The node's libp2p Ed25519 private key.
+ * @returns A signer exposing the peer id, the encoded public key, and `sign`.
+ * @throws If the key is not Ed25519.
+ */
+export function peerKeySigner(privateKey: PrivateKey): PeerKeySigner {
+  if (privateKey.type !== 'Ed25519') {
+    throw new Error(`peerKeySigner requires an Ed25519 key, got ${privateKey.type}`);
+  }
+
+  const publicKey = privateKey.publicKey;
+  // For Ed25519 the public key's digest is an identity multihash, so its string
+  // form is the peer id itself — the same value `peerIdFromPrivateKey` produces.
+  const peerId = publicKey.toString();
+  const publicKeyB64 = uint8ArrayToString(publicKeyToProtobuf(publicKey), 'base64url');
+
+  return {
+    peerId,
+    publicKeyB64,
+    async sign(message: string): Promise<string> {
+      const signature = await privateKey.sign(new TextEncoder().encode(message));
+      return uint8ArrayToString(signature, 'base64url');
+    }
+  };
+}

package/src/index.ts

@@ -317,6 +317,7 @@ export {
 // the cadence/degree defaults the proactive reconcile routine reads.
 export {
   selectControlCohortDials,
+  DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS,
   DEFAULT_CONTROL_COHORT_RECONCILE_MS,
   DEFAULT_CONTROL_COHORT_TARGET_DEGREE,
   type ControlCohortSelection

package/src/key-store-file.ts

@@ -1,132 +1,132 @@
-/**
- * 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 (a foreign file
- * with an invalid percent-sequence), so {@link FileKeyStore.list} can skip it
- * rather than letting one undecodable entry throw and break enumeration of every
- * real slot.
- */
-function decodeKeyId(fileName: string): KeyId | undefined {
-	const encoded = fileName.slice(0, -SLOT_SUFFIX.length);
-	try {
-		return decodeURIComponent(encoded);
-	} catch (error) {
-		log('FileKeyStore: skipping undecodable slot filename %s: %o', fileName, error);
-		return undefined;
-	}
-}
-
-/**
- * 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 { 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 (a foreign file
+ * with an invalid percent-sequence), so {@link FileKeyStore.list} can skip it
+ * rather than letting one undecodable entry throw and break enumeration of every
+ * real slot.
+ */
+function decodeKeyId(fileName: string): KeyId | undefined {
+	const encoded = fileName.slice(0, -SLOT_SUFFIX.length);
+	try {
+		return decodeURIComponent(encoded);
+	} catch (error) {
+		log('FileKeyStore: skipping undecodable slot filename %s: %o', fileName, error);
+		return undefined;
+	}
+}
+
+/**
+ * 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);
+	}
+}