@serfab/cadre-core 0.6.0 → 0.8.1

package/dist/index.d.ts

@@ -1,13 +1,34 @@
 export * from './types.js';
+export { canonicalJson } from './canonical-json.js';
 export { CadreNode } from './cadre-node.js';
-export { ControlDatabase, type ControlDatabaseConfig } from './control-database.js';
+export { ControlDatabase, buildAuthorizationMessage, type ControlDatabaseConfig, type ControlTable } from './control-database.js';
+export { authorityKeyFromLibp2p, authorityPublicKeyFromPrivate, type AuthorityKeyPair } from './authority-key.js';
+export { InMemoryKeyStore, KeyStoreAccessError, DEFAULT_IDENTITY_KEY_ID, type KeyStore, type KeyId } from './key-store.js';
 export { StrandDatabase, type StrandDatabaseConfig } from './strand-database.js';
 export { StrandWatcher, type StrandWatcherCallbacks, type StrandQueryable, type SAppIdLookup, type StrandRowWithApp } from './strand-watcher.js';
-export { StrandInstanceManager, type StartStrandConfig, getStrandStoragePath } from './strand-instance-manager.js';
+export { StrandInstanceManager, type StartStrandConfig, type ResumeStrandOverrides, getStrandStoragePath } from './strand-instance-manager.js';
 export { HibernationManager, type HibernationCallbacks } from './hibernation-manager.js';
 export { ArachnodeStub, createArachnodeStub, type RingConfig } from './arachnode-stub.js';
 export { EnrollmentService, type MemberVerifier, type MemberRegistry } from './enrollment.js';
-export { StrandSolicitationService, type DisclosureValidator, type FormationUsageRecorder, type StrandProvisioner, type FormationSigner, type StrandSolicitationServiceOptions } from './strand-solicitation.js';
-export { SeedBootstrapService, SEED_PROTOCOL, type SeedBootstrapConfig, type SeedEventCallbacks } from './seed-bootstrap.js';
+export { StrandSolicitationService, createDefaultFormationResponseValidator, type DisclosureValidator, type FormationUsageRecorder, type ResolvedHostStrand, type StrandProvisioner, type FormationSigner, type FormationResponseValidator, type StrandSolicitationServiceOptions } from './strand-solicitation.js';
+export { ControlFormationUsageRecorder } from './control-formation-recorder.js';
+export { generateStrandMemberKey, strandMemberKeyPair } from './strand-member-key.js';
+export { signStrandPayload, verifyStrandPayload, bootstrapFounderMembership, issueInvite, consumeInvite, addMemberByAuthority, registerMemberPeer, addAuthority, removeAuthority, STRAND_ENGINE, STRAND_ENGINE_VERSION, type FounderBootstrapParams, type IssueInviteParams, type IssuedInvite, type ConsumeInviteParams, type AddMemberByAuthorityParams, type RegisterMemberPeerParams, type AddAuthorityParams, type RemoveAuthorityParams } from './strand-membership-writer.js';
+export { canonicalDatetime } from './canonical-datetime.js';
+export { StrandMemberRegistry, StrandMemberVerifier, memberRegistrationPayload, type StrandAdmission } from './strand-member-registry.js';
+export { SeedBootstrapService, SEED_PROTOCOL, ed25519PublicKeyB64FromPeerId, type SeedBootstrapConfig, type SeedEventCallbacks } from './seed-bootstrap.js';
+export { peerAuthorizationDigest, verifyPeerAuthorization } from './peer-authorization.js';
+export { StrandWakeService, dialWake, WAKE_PROTOCOL, type StrandWakeServiceOptions, type DialWakeOptions } from './strand-wake-protocol.js';
+export { StrandAddrService, collectStrandAddrs, STRAND_ADDR_PROTOCOL, type StrandAddrServiceOptions, type StrandAddrPeer, type CollectStrandAddrsOptions } from './strand-addr-protocol.js';
+export { peerRecordSignedPayload, signPeerRecord, verifyPeerRecordSignature, isPeerRecordFresh, isSignalingAddr, orderSignalingFirst, currentMemberTrustPolicy, DEFAULT_PEER_RECORD_MAX_AGE_MS, DEFAULT_PEER_RECORD_HEARTBEAT_MS } from './peer-record.js';
+export { deviceTokenSignedPayload, signDeviceTokenRecord, verifyDeviceTokenSignature, isPushPlatform } from './device-token.js';
+export { STRAND_WAKE_TYPE, type StrandWakePayload } from './strand-wake-payload.js';
+export type { PushNotifier, PushMessage, PushSendResult } from './push-notifier.js';
+export { validatePushCredentials, redactPushCredentials, REDACTED } from './push-credentials.js';
+export { PushFanoutService, DEFAULT_PUSH_COOLDOWN_MS, DEFAULT_PUSH_DEBOUNCE_MS, type PushFanoutOptions, type FanoutMember } from './push-fanout.js';
+export { selectControlCohortDials, DEFAULT_CONTROL_COHORT_RECONCILE_MS, DEFAULT_CONTROL_COHORT_TARGET_DEGREE, type ControlCohortSelection } from './control-cohort.js';
+export { dbAnchoredTrustPolicy, pinnedKeyTrustPolicy, tofuTrustPolicy, type SeedTrustPolicy, type SeedTrustContext, type SeedTrustDecision } from './seed-trust-policy.js';
 export { signSchema, verifySchema, assertSchemaSignature, SchemaVerificationError } from './schema-verification.js';
+export { FormationListener, dialFormation, isValidResponderCreatesResult, FORMATION_PROTOCOL, type FormationParty, type FormationContactMessage, type FormationResultMessage, type FormationProvisionResult, type FormationStrandInfo, type FormationDbConnectionInfo, type FormationListenerOptions, type FormationDialOptions, type ResponderProvisionOutcome } from './strand-formation-protocol.js';
 export { StrandFormationManager, createStrandFormationManager, type StrandFormationManagerConfig, type StrandFormationManagerOptions } from './strand-formation-manager.js';
+export { classifyTransport, classifyConnectionPath, summarizeConnectionPaths, emptyConnectionPathSummary, DEFAULT_SETTLE_WINDOW_MS, type ConnectionPathKind, type ConnectionTransport, type ConnectionPath, type ConnectionPathSummary, type ConnectionLike } from './diagnostics/connection-path.js';

package/dist/index.js

@@ -1,9 +1,19 @@
 // Core types
 export * from './types.js';
+// Canonical JSON serialization (shared signing payload format)
+export { canonicalJson } from './canonical-json.js';
 // Main CadreNode class
 export { CadreNode } from './cadre-node.js';
 // Control database
-export { ControlDatabase } from './control-database.js';
+export { ControlDatabase, buildAuthorizationMessage } from './control-database.js';
+// Authority key bridge (libp2p Ed25519 -> base64url authority keypair)
+export { authorityKeyFromLibp2p, authorityPublicKeyFromPrivate } from './authority-key.js';
+// Pluggable key store (backend-agnostic identity/authority key material seam).
+// Dependency-free: the interface, error, default slot id, and in-memory backend
+// are safe in every (RN/browser/Node) entry graph. The Node FileKeyStore is a
+// separate subpath module ('@serfab/cadre-core/key-store-file') so its node:fs
+// import never lands here.
+export { InMemoryKeyStore, KeyStoreAccessError, DEFAULT_IDENTITY_KEY_ID } from './key-store.js';
 // Strand database
 export { StrandDatabase } from './strand-database.js';
 // Strand management
@@ -16,11 +26,56 @@ export { ArachnodeStub, createArachnodeStub } from './arachnode-stub.js';
 // Enrollment
 export { EnrollmentService } from './enrollment.js';
 // Strand Solicitation
-export { StrandSolicitationService } from './strand-solicitation.js';
+export { StrandSolicitationService, createDefaultFormationResponseValidator } from './strand-solicitation.js';
+// DB-backed FormationUsageRecorder (reads/writes the real CadreControl tables)
+export { ControlFormationUsageRecorder } from './control-formation-recorder.js';
+// Closed-strand member key generation (ed25519 protobuf, base64) + the
+// protobuf->base64url bridge that derives the founding Member/Authority key.
+export { generateStrandMemberKey, strandMemberKeyPair } from './strand-member-key.js';
+// Strand membership writer (founder bootstrap, invite issuance/consumption,
+// authority-admit, member-peer registration, authority rotation, + shared signing
+// primitives reused across the flows).
+export { signStrandPayload, verifyStrandPayload, bootstrapFounderMembership, issueInvite, consumeInvite, addMemberByAuthority, registerMemberPeer, addAuthority, removeAuthority, STRAND_ENGINE, STRAND_ENGINE_VERSION } from './strand-membership-writer.js';
+// Engine-canonical datetime helper (shared by control + strand signed-write flows
+// so a signed timestamp byte-matches the datetime-coerced column the CHECK sees).
+export { canonicalDatetime } from './canonical-datetime.js';
+// Strand-DB-backed EnrollmentService backing: concrete MemberRegistry +
+// MemberVerifier that write/read the real Strand.* membership tables.
+export { StrandMemberRegistry, StrandMemberVerifier, memberRegistrationPayload } from './strand-member-registry.js';
 // Seed Bootstrap
-export { SeedBootstrapService, SEED_PROTOCOL } from './seed-bootstrap.js';
+export { SeedBootstrapService, SEED_PROTOCOL, ed25519PublicKeyB64FromPeerId } from './seed-bootstrap.js';
+// Peer Authorization (shared authority-signature digest + offline verifier)
+export { peerAuthorizationDigest, verifyPeerAuthorization } from './peer-authorization.js';
+// Strand Wake (control-network push-wake protocol)
+export { StrandWakeService, dialWake, WAKE_PROTOCOL } from './strand-wake-protocol.js';
+// Strand Address (control-network strand-address RPC) — wire types come via
+// `export * from './types.js'` (StrandAddrRequest / StrandAddrResponse).
+export { StrandAddrService, collectStrandAddrs, STRAND_ADDR_PROTOCOL } from './strand-addr-protocol.js';
+// Peer-address record (self-published, signed, freshness-stamped CadrePeer row)
+export { peerRecordSignedPayload, signPeerRecord, verifyPeerRecordSignature, isPeerRecordFresh, isSignalingAddr, orderSignalingFirst, currentMemberTrustPolicy, DEFAULT_PEER_RECORD_MAX_AGE_MS, DEFAULT_PEER_RECORD_HEARTBEAT_MS } from './peer-record.js';
+// Device-token record (self-published, signed FCM/APNs push token — CadrePeer sibling)
+export { deviceTokenSignedPayload, signDeviceTokenRecord, verifyDeviceTokenSignature, isPushPlatform } from './device-token.js';
+// Strand-wake payload contract (canonical; shared by the server sender + RN receiver)
+export { STRAND_WAKE_TYPE } from './strand-wake-payload.js';
+// Push-credential validation + log redaction. Dependency-free (type-only imports),
+// so a provisioner (cadre-host / cadre-provider) can reject a partial credential
+// set and produce a key-safe log view without pulling the FCM/APNs sender graph.
+export { validatePushCredentials, redactPushCredentials, REDACTED } from './push-credentials.js';
+// Server-side push-wake trigger policy + fan-out (who/when to wake). Cross-platform
+// clean — it imports only the PushNotifier *type*, so exporting it as a runtime
+// value pulls no node:http2/node:crypto edge into the RN/browser graph.
+export { PushFanoutService, DEFAULT_PUSH_COOLDOWN_MS, DEFAULT_PUSH_DEBOUNCE_MS } from './push-fanout.js';
+// Control-cohort dial selection (backbone-preferential, bounded out-degree) +
+// the cadence/degree defaults the proactive reconcile routine reads.
+export { selectControlCohortDials, DEFAULT_CONTROL_COHORT_RECONCILE_MS, DEFAULT_CONTROL_COHORT_TARGET_DEGREE } from './control-cohort.js';
+// Seed trust policy (trust anchor for incoming seeds)
+export { dbAnchoredTrustPolicy, pinnedKeyTrustPolicy, tofuTrustPolicy } from './seed-trust-policy.js';
 // Schema Verification
 export { signSchema, verifySchema, assertSchemaSignature, SchemaVerificationError } from './schema-verification.js';
-// Strand Formation (strand-proto integration)
+// Strand Formation transport (native cadre-core protocol)
+export { FormationListener, dialFormation, isValidResponderCreatesResult, FORMATION_PROTOCOL } from './strand-formation-protocol.js';
+// Strand Formation manager (drives the native transport)
 export { StrandFormationManager, createStrandFormationManager } from './strand-formation-manager.js';
+// Connection-path diagnostics (relayed vs direct classification + summary)
+export { classifyTransport, classifyConnectionPath, summarizeConnectionPaths, emptyConnectionPathSummary, DEFAULT_SETTLE_WINDOW_MS } from './diagnostics/connection-path.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,aAAa;AACb,cAAc,YAAY,CAAC;AAE3B,uBAAuB;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,mBAAmB;AACnB,OAAO,EAAE,eAAe,EAA8B,MAAM,uBAAuB,CAAC;AAEpF,kBAAkB;AAClB,OAAO,EAAE,cAAc,EAA6B,MAAM,sBAAsB,CAAC;AAEjF,oBAAoB;AACpB,OAAO,EACL,aAAa,EAKd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,qBAAqB,EAErB,oBAAoB,EACrB,MAAM,8BAA8B,CAAC;AAEtC,cAAc;AACd,OAAO,EACL,kBAAkB,EAEnB,MAAM,0BAA0B,CAAC;AAElC,mBAAmB;AACnB,OAAO,EACL,aAAa,EACb,mBAAmB,EAEpB,MAAM,qBAAqB,CAAC;AAE7B,aAAa;AACb,OAAO,EACL,iBAAiB,EAGlB,MAAM,iBAAiB,CAAC;AAEzB,sBAAsB;AACtB,OAAO,EACL,yBAAyB,EAM1B,MAAM,0BAA0B,CAAC;AAElC,iBAAiB;AACjB,OAAO,EACL,oBAAoB,EACpB,aAAa,EAGd,MAAM,qBAAqB,CAAC;AAE7B,sBAAsB;AACtB,OAAO,EACL,UAAU,EACV,YAAY,EACZ,qBAAqB,EACrB,uBAAuB,EACxB,MAAM,0BAA0B,CAAC;AAElC,8CAA8C;AAC9C,OAAO,EACL,sBAAsB,EACtB,4BAA4B,EAG7B,MAAM,+BAA+B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/key-store-file.d.ts

@@ -0,0 +1,52 @@
+import type { KeyId, KeyStore } from './key-store.js';
+/**
+ * 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 declare class FileKeyStore implements KeyStore {
+    private readonly dir;
+    constructor(dir: string);
+    private slotPath;
+    /**
+     * 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;
+    get(keyId: KeyId): Promise<Uint8Array | undefined>;
+    /**
+     * 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. A failure at any point removes the temp file and leaves the previous
+     * slot untouched.
+     */
+    set(keyId: KeyId, keyMaterial: Uint8Array): Promise<void>;
+    /**
+     * Write material to `tmpPath`, durably land it, then atomically swap it onto
+     * `finalPath`.
+     *
+     * Durability bar: the temp file is fsync'd before the rename so a power loss
+     * cannot surface a slot whose bytes never reached the platter, and the slot
+     * directory is fsync'd afterwards (best-effort — see {@link syncDir}) so the
+     * rename itself survives a crash. On POSIX `rename(2)` replaces atomically;
+     * Node maps to `MoveFileEx(MOVEFILE_REPLACE_EXISTING)` on Windows, which is
+     * also atomic — though it can fail with `EPERM`/`EBUSY` if another process
+     * holds the destination open. That cross-process case is out of scope here
+     * (the in-process identity path is single-flight); such a failure surfaces
+     * to the caller with the previous slot left intact.
+     */
+    private writeSlotAtomically;
+    /**
+     * Best-effort fsync of the slot directory so a fresh slot's directory entry is
+     * durable across power loss. Opening a directory for fsync is not portable
+     * (unsupported on Windows and some filesystems), and rename atomicity does not
+     * depend on it — so a failure here is logged and swallowed, never surfaced.
+     */
+    private syncDir;
+    delete(keyId: KeyId): Promise<void>;
+    list(): Promise<KeyId[]>;
+}

package/dist/key-store-file.js

@@ -0,0 +1,194 @@
+/**
+ * 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 { mkdir, readFile, rm, readdir, rename, open } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { KeyStoreAccessError } from './key-store.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';
+/** Best-effort POSIX permissions (ignored on Windows / unsupported FSes). */
+const DIR_MODE = 0o700;
+const FILE_MODE = 0o600;
+/**
+ * Percent-encode a keyId into a filesystem-safe filename component. Beyond
+ * `encodeURIComponent` (which already escapes `/`, spaces, and unicode), this
+ * also escapes the unreserved characters `encodeURIComponent` leaves intact but
+ * that are unsafe in filenames on some platforms (notably `*` on Windows) — and
+ * `.` so the `.key` suffix is the only literal dot, making suffix-stripping in
+ * {@link decodeKeyId} unambiguous. {@link decodeKeyId} reverses every escape via
+ * `decodeURIComponent`. The result contains only `A-Za-z0-9-_` and `%XX`.
+ */
+function encodeKeyId(keyId) {
+    return encodeURIComponent(keyId).replace(/[!'()*~.]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+/**
+ * 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) {
+    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;
+    }
+}
+/** Whether an unknown error is a Node "file/dir not found" (ENOENT). */
+function isNotFound(error) {
+    return typeof error === 'object' && error !== null
+        && error.code === 'ENOENT';
+}
+/**
+ * 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 {
+    constructor(dir) {
+        this.dir = dir;
+    }
+    slotPath(keyId) {
+        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.
+     */
+    tempPath(keyId) {
+        const unique = randomBytes(6).toString('hex');
+        return join(this.dir, `${encodeKeyId(keyId)}.${unique}${TEMP_SUFFIX}`);
+    }
+    async get(keyId) {
+        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. A failure at any point removes the temp file and leaves the previous
+     * slot untouched.
+     */
+    async set(keyId, keyMaterial) {
+        await mkdir(this.dir, { recursive: true, mode: DIR_MODE });
+        await this.writeSlotAtomically(this.tempPath(keyId), this.slotPath(keyId), keyMaterial);
+    }
+    /**
+     * Write material to `tmpPath`, durably land it, then atomically swap it onto
+     * `finalPath`.
+     *
+     * Durability bar: the temp file is fsync'd before the rename so a power loss
+     * cannot surface a slot whose bytes never reached the platter, and the slot
+     * directory is fsync'd afterwards (best-effort — see {@link syncDir}) so the
+     * rename itself survives a crash. On POSIX `rename(2)` replaces atomically;
+     * Node maps to `MoveFileEx(MOVEFILE_REPLACE_EXISTING)` on Windows, which is
+     * also atomic — though it can fail with `EPERM`/`EBUSY` if another process
+     * holds the destination open. That cross-process case is out of scope here
+     * (the in-process identity path is single-flight); such a failure surfaces
+     * to the caller with the previous slot left intact.
+     */
+    async writeSlotAtomically(tmpPath, finalPath, keyMaterial) {
+        // 'wx' creates the temp file exclusively; a name collision (astronomically
+        // unlikely given the random component) fails here before we own anything.
+        const handle = await open(tmpPath, 'wx', FILE_MODE);
+        try {
+            try {
+                await handle.writeFile(keyMaterial);
+                await handle.sync(); // land bytes on disk before the rename exposes them
+            }
+            finally {
+                await handle.close().catch(() => { });
+            }
+            await rename(tmpPath, finalPath);
+        }
+        catch (error) {
+            // Any failure after creation (write, sync, or rename): drop the temp
+            // file so a retry leaves no `.tmp` debris. The slot is only ever
+            // swapped by the atomic rename, so the previous bytes stay intact.
+            await rm(tmpPath, { force: true }).catch(() => { });
+            throw error;
+        }
+        await this.syncDir();
+    }
+    /**
+     * Best-effort fsync of the slot directory so a fresh slot's directory entry is
+     * durable across power loss. Opening a directory for fsync is not portable
+     * (unsupported on Windows and some filesystems), and rename atomicity does not
+     * depend on it — so a failure here is logged and swallowed, never surfaced.
+     */
+    async syncDir() {
+        let dirHandle;
+        try {
+            dirHandle = await open(this.dir, 'r');
+            await dirHandle.sync();
+        }
+        catch (error) {
+            log('FileKeyStore: directory fsync skipped for %s: %o', this.dir, error);
+        }
+        finally {
+            await dirHandle?.close().catch(() => { });
+        }
+    }
+    async delete(keyId) {
+        // force:true makes removing an absent slot a no-op (idempotent).
+        await rm(this.slotPath(keyId), { force: true });
+    }
+    async list() {
+        let entries;
+        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 !== undefined);
+    }
+}
+//# sourceMappingURL=key-store-file.js.map

package/dist/key-store-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-store-file.js","sourceRoot":"","sources":["../src/key-store-file.ts"],"names":[],"mappings":"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"}

package/dist/key-store.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Backend-agnostic store for raw private key material.
+ *
+ * Mobile cadre nodes hold sensitive key material at rest: the libp2p
+ * peer/node identity key and (in the single-key reference model) the authority
+ * signing key derived from it. This module defines the seam those keys flow
+ * through so a platform-secure backend (iOS Keychain / Android Keystore) can be
+ * plugged in without `@serfab/cadre-core` taking any platform dependency.
+ *
+ * This file is dependency-free (no node:/RN imports) so it is safe in every
+ * entry graph. The Node reference {@link FileKeyStore} lives in a separate
+ * subpath module (`./key-store-file.js`) so its `node:fs` import never lands in
+ * the cross-platform default entry.
+ */
+/** Opaque identifier for a stored key slot (e.g. 'cadre/identity'). */
+export type KeyId = string;
+/**
+ * Default slot id for the node identity key. `CadreNode` reads/persists its
+ * libp2p identity here when a {@link KeyStore} is configured without an explicit
+ * `identityKeyId`.
+ */
+export declare const DEFAULT_IDENTITY_KEY_ID: KeyId;
+/**
+ * Backend-agnostic store for raw private key material. Implementations may be
+ * file-based, OS-keyring, or platform secure-enclave backed (iOS Keychain /
+ * Android Keystore). The interface makes no assumption about the backend and
+ * never logs, returns, or throws key material.
+ *
+ * Key material is raw bytes (e.g. libp2p protobuf-serialized private keys).
+ * Text-only backends encode/decode (base64) internally; byte-native backends
+ * (LevelDB) store as-is.
+ */
+export interface KeyStore {
+    /** Resolves to the stored material, or undefined if the slot is empty. */
+    get(keyId: KeyId): Promise<Uint8Array | undefined>;
+    /** Writes/overwrites the slot. */
+    set(keyId: KeyId, keyMaterial: Uint8Array): Promise<void>;
+    /** Removes the slot. Idempotent — succeeds even if absent. */
+    delete(keyId: KeyId): Promise<void>;
+    /** Enumerates the keyIds this store knows about. */
+    list(): Promise<KeyId[]>;
+}
+/**
+ * Thrown by {@link KeyStore.get} when access was denied or could not be
+ * satisfied (e.g. a biometric/device-unlock prompt was cancelled or failed).
+ * Distinguishes "access refused" from "slot empty" (which is a plain `undefined`
+ * return). Biometric gating itself is out of scope here, but `get` rejecting
+ * with this error is the contract a gated backend uses, so callers must not
+ * treat it as "no key" (which would trigger key regeneration and silent
+ * identity loss).
+ *
+ * Carries only the {@link keyId} — never key material — so it is safe to log.
+ */
+export declare class KeyStoreAccessError extends Error {
+    readonly keyId: KeyId;
+    constructor(keyId: KeyId, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * In-memory {@link KeyStore} backed by a `Map`. For tests and ephemeral nodes;
+ * nothing is persisted across process restarts. Dependency-free, so it is safe
+ * in every entry graph.
+ *
+ * Material is defensively copied on both {@link set} and {@link get} so a caller
+ * mutating its own buffer cannot alter stored state (and vice versa), matching
+ * the fresh-buffer semantics a file/keyring backend produces.
+ */
+export declare class InMemoryKeyStore implements KeyStore {
+    private readonly slots;
+    get(keyId: KeyId): Promise<Uint8Array | undefined>;
+    set(keyId: KeyId, keyMaterial: Uint8Array): Promise<void>;
+    delete(keyId: KeyId): Promise<void>;
+    list(): Promise<KeyId[]>;
+}

package/dist/key-store.js

@@ -0,0 +1,66 @@
+/**
+ * Backend-agnostic store for raw private key material.
+ *
+ * Mobile cadre nodes hold sensitive key material at rest: the libp2p
+ * peer/node identity key and (in the single-key reference model) the authority
+ * signing key derived from it. This module defines the seam those keys flow
+ * through so a platform-secure backend (iOS Keychain / Android Keystore) can be
+ * plugged in without `@serfab/cadre-core` taking any platform dependency.
+ *
+ * This file is dependency-free (no node:/RN imports) so it is safe in every
+ * entry graph. The Node reference {@link FileKeyStore} lives in a separate
+ * subpath module (`./key-store-file.js`) so its `node:fs` import never lands in
+ * the cross-platform default entry.
+ */
+/**
+ * Default slot id for the node identity key. `CadreNode` reads/persists its
+ * libp2p identity here when a {@link KeyStore} is configured without an explicit
+ * `identityKeyId`.
+ */
+export const DEFAULT_IDENTITY_KEY_ID = 'cadre/identity';
+/**
+ * Thrown by {@link KeyStore.get} when access was denied or could not be
+ * satisfied (e.g. a biometric/device-unlock prompt was cancelled or failed).
+ * Distinguishes "access refused" from "slot empty" (which is a plain `undefined`
+ * return). Biometric gating itself is out of scope here, but `get` rejecting
+ * with this error is the contract a gated backend uses, so callers must not
+ * treat it as "no key" (which would trigger key regeneration and silent
+ * identity loss).
+ *
+ * Carries only the {@link keyId} — never key material — so it is safe to log.
+ */
+export class KeyStoreAccessError extends Error {
+    constructor(keyId, message, options) {
+        super(message, options);
+        this.name = 'KeyStoreAccessError';
+        this.keyId = keyId;
+    }
+}
+/**
+ * In-memory {@link KeyStore} backed by a `Map`. For tests and ephemeral nodes;
+ * nothing is persisted across process restarts. Dependency-free, so it is safe
+ * in every entry graph.
+ *
+ * Material is defensively copied on both {@link set} and {@link get} so a caller
+ * mutating its own buffer cannot alter stored state (and vice versa), matching
+ * the fresh-buffer semantics a file/keyring backend produces.
+ */
+export class InMemoryKeyStore {
+    constructor() {
+        this.slots = new Map();
+    }
+    async get(keyId) {
+        const stored = this.slots.get(keyId);
+        return stored ? stored.slice() : undefined;
+    }
+    async set(keyId, keyMaterial) {
+        this.slots.set(keyId, keyMaterial.slice());
+    }
+    async delete(keyId) {
+        this.slots.delete(keyId);
+    }
+    async list() {
+        return [...this.slots.keys()];
+    }
+}
+//# sourceMappingURL=key-store.js.map

package/dist/key-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-store.js","sourceRoot":"","sources":["../src/key-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAU,gBAAgB,CAAC;AA0B/D;;;;;;;;;;GAUG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAG7C,YAAY,KAAY,EAAE,OAAe,EAAE,OAA6B;QACvE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACpB,CAAC;CACD;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,gBAAgB;IAA7B;QACkB,UAAK,GAAG,IAAI,GAAG,EAAqB,CAAC;IAkBvD,CAAC;IAhBA,KAAK,CAAC,GAAG,CAAC,KAAY;QACrB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACrC,OAAO,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,KAAY,EAAE,WAAuB;QAC9C,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,WAAW,CAAC,KAAK,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,KAAY;QACxB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAED,KAAK,CAAC,IAAI;QACT,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAC/B,CAAC;CACD"}

package/dist/peer-authorization.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Canonical digest an authority signs to authorize a peer.
+ *
+ * This is the exact byte construction {@link SeedBootstrapService.authorizePeer}
+ * signs over when it inserts an authorized `CadrePeer` row:
+ * `digest([peerId], 'sha256', 'base64url')`. Factored into one place so the
+ * producer (authority signing) and the verifier (the offline `cadre enroll
+ * register` check) can never drift apart — change the digest here and both move
+ * together. The SQL mirror is the bare single-field `digest(coalesce(new.PeerId, old.PeerId))`.
+ */
+export declare function peerAuthorizationDigest(peerId: string): string;
+/**
+ * Verify that `signature` is a valid authority ed25519 signature over `peerId`'s
+ * authorization digest, using `authorityPublicKey` (base64url).
+ *
+ * This is the mirror of the signing done in
+ * {@link SeedBootstrapService.authorizePeer}: it checks the signature against
+ * {@link peerAuthorizationDigest}. A `true` result means the holder of the
+ * authority private key vouched for this peer ID — it does NOT mean the peer is
+ * registered anywhere.
+ *
+ * Returns a boolean and never throws: malformed base64url, a bad/garbage key, or
+ * any crypto failure resolves to `false` (callers want a verdict, not an
+ * exception). The catch is logged at debug.
+ */
+export declare function verifyPeerAuthorization(peerId: string, authorityPublicKey: string, signature: string): boolean;

package/dist/peer-authorization.js

@@ -0,0 +1,40 @@
+import debug from 'debug';
+import { digest, verify } from '@optimystic/quereus-plugin-crypto';
+const log = debug('sereus:cadre:peer-authorization');
+/**
+ * Canonical digest an authority signs to authorize a peer.
+ *
+ * This is the exact byte construction {@link SeedBootstrapService.authorizePeer}
+ * signs over when it inserts an authorized `CadrePeer` row:
+ * `digest([peerId], 'sha256', 'base64url')`. Factored into one place so the
+ * producer (authority signing) and the verifier (the offline `cadre enroll
+ * register` check) can never drift apart — change the digest here and both move
+ * together. The SQL mirror is the bare single-field `digest(coalesce(new.PeerId, old.PeerId))`.
+ */
+export function peerAuthorizationDigest(peerId) {
+    return digest([peerId], 'sha256', 'base64url');
+}
+/**
+ * Verify that `signature` is a valid authority ed25519 signature over `peerId`'s
+ * authorization digest, using `authorityPublicKey` (base64url).
+ *
+ * This is the mirror of the signing done in
+ * {@link SeedBootstrapService.authorizePeer}: it checks the signature against
+ * {@link peerAuthorizationDigest}. A `true` result means the holder of the
+ * authority private key vouched for this peer ID — it does NOT mean the peer is
+ * registered anywhere.
+ *
+ * Returns a boolean and never throws: malformed base64url, a bad/garbage key, or
+ * any crypto failure resolves to `false` (callers want a verdict, not an
+ * exception). The catch is logged at debug.
+ */
+export function verifyPeerAuthorization(peerId, authorityPublicKey, signature) {
+    try {
+        return verify(peerAuthorizationDigest(peerId), signature, authorityPublicKey, 'ed25519', 'base64url', 'base64url', 'base64url');
+    }
+    catch (error) {
+        log('verifyPeerAuthorization failed: %o', error);
+        return false;
+    }
+}
+//# sourceMappingURL=peer-authorization.js.map

package/dist/peer-authorization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-authorization.js","sourceRoot":"","sources":["../src/peer-authorization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,mCAAmC,CAAC;AAEnE,MAAM,GAAG,GAAG,KAAK,CAAC,iCAAiC,CAAC,CAAC;AAErD;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAc;IACpD,OAAO,MAAM,CAAC,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,WAAW,CAAW,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,uBAAuB,CACrC,MAAc,EACd,kBAA0B,EAC1B,SAAiB;IAEjB,IAAI,CAAC;QACH,OAAO,MAAM,CACX,uBAAuB,CAAC,MAAM,CAAC,EAC/B,SAAS,EACT,kBAAkB,EAClB,SAAS,EACT,WAAW,EACX,WAAW,EACX,WAAW,CACZ,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,GAAG,CAAC,oCAAoC,EAAE,KAAK,CAAC,CAAC;QACjD,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}