@serfab/cadre-core 0.7.1 → 0.9.0

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 owner
+ * 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 owner
+ * 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,48 @@
+/**
+ * Canonical digest an owner 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 (owner 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;
+/**
+ * Canonical digest an owner signs to VOUCH a `CadrePeer` membership row (insert
+ * and the owner re-touch update). Binds the peer id to the row's single-use
+ * `StampId` nonce, so a captured signed insert cannot be replayed (the `StampId` is
+ * unique) and — because {@link cadrePeerRemoveDigest} scopes a DIFFERENT payload — the
+ * stored voucher (`VouchSig`) cannot be replayed to authorize a delete.
+ *
+ * The SQL mirror is `digest(new.PeerId, new.StampId)` (two TEXT fields), matching the
+ * canonical multi-field framing in control-database.ts:buildAuthorizationMessage.
+ */
+export declare function cadrePeerVoucherDigest(peerId: string, stampId: string): string;
+/**
+ * Canonical digest an owner signs to REMOVE a `CadrePeer` row. Deliberately a
+ * distinct payload from {@link cadrePeerVoucherDigest} (adds the `'remove'` action
+ * tag) so the row's stored voucher — a signature over the voucher digest — can never
+ * satisfy this delete check. The signature is supplied in write context and never
+ * stored, so no reader can replay it; binding the live row's `StampId` also invalidates
+ * any captured remove after a delete+reinsert (the nonce rotates).
+ *
+ * SQL mirror: `digest(old.PeerId, old.StampId, 'remove')`.
+ */
+export declare function cadrePeerRemoveDigest(peerId: string, stampId: string): string;
+/**
+ * Verify that `signature` is a valid owner ed25519 signature over `peerId`'s
+ * authorization digest, using `ownerPublicKey` (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
+ * owner 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, ownerPublicKey: string, signature: string): boolean;

package/dist/peer-authorization.js

@@ -0,0 +1,66 @@
+import debug from 'debug';
+import { digest, verify } from '@optimystic/quereus-plugin-crypto';
+const log = debug('sereus:cadre:peer-authorization');
+/**
+ * Canonical digest an owner 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 (owner 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');
+}
+/**
+ * Canonical digest an owner signs to VOUCH a `CadrePeer` membership row (insert
+ * and the owner re-touch update). Binds the peer id to the row's single-use
+ * `StampId` nonce, so a captured signed insert cannot be replayed (the `StampId` is
+ * unique) and — because {@link cadrePeerRemoveDigest} scopes a DIFFERENT payload — the
+ * stored voucher (`VouchSig`) cannot be replayed to authorize a delete.
+ *
+ * The SQL mirror is `digest(new.PeerId, new.StampId)` (two TEXT fields), matching the
+ * canonical multi-field framing in control-database.ts:buildAuthorizationMessage.
+ */
+export function cadrePeerVoucherDigest(peerId, stampId) {
+    return digest([peerId, stampId], 'sha256', 'base64url');
+}
+/**
+ * Canonical digest an owner signs to REMOVE a `CadrePeer` row. Deliberately a
+ * distinct payload from {@link cadrePeerVoucherDigest} (adds the `'remove'` action
+ * tag) so the row's stored voucher — a signature over the voucher digest — can never
+ * satisfy this delete check. The signature is supplied in write context and never
+ * stored, so no reader can replay it; binding the live row's `StampId` also invalidates
+ * any captured remove after a delete+reinsert (the nonce rotates).
+ *
+ * SQL mirror: `digest(old.PeerId, old.StampId, 'remove')`.
+ */
+export function cadrePeerRemoveDigest(peerId, stampId) {
+    return digest([peerId, stampId, 'remove'], 'sha256', 'base64url');
+}
+/**
+ * Verify that `signature` is a valid owner ed25519 signature over `peerId`'s
+ * authorization digest, using `ownerPublicKey` (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
+ * owner 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, ownerPublicKey, signature) {
+    try {
+        return verify(peerAuthorizationDigest(peerId), signature, ownerPublicKey, '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;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAc,EAAE,OAAe;IACpE,OAAO,MAAM,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,WAAW,CAAW,CAAC;AACpE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAc,EAAE,OAAe;IACnE,OAAO,MAAM,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,QAAQ,EAAE,WAAW,CAAW,CAAC;AAC9E,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,uBAAuB,CACrC,MAAc,EACd,cAAsB,EACtB,SAAiB;IAEjB,IAAI,CAAC;QACH,OAAO,MAAM,CACX,uBAAuB,CAAC,MAAM,CAAC,EAC/B,SAAS,EACT,cAAc,EACd,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"}

package/dist/peer-record.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Peer-address record helpers: the single source of truth for the bytes a node
+ * signs when publishing its own `CadrePeer` row and re-verifies when resolving
+ * another peer's row.
+ *
+ * The signed payload is a single SHA-256 digest of a delimited string of the
+ * authenticated fields. It is intentionally NOT JSON-canonicalized: a delimited
+ * digest is trivially deterministic across node/browser/RN (plain string concat
+ * + sha256, no key ordering) and — crucially — is reconstructable inside the
+ * `CadrePeer.AuthorizedUpdate` SQL constraint from the row's own columns:
+ *
+ *   digest(new.PeerId || '|' || new.Multiaddr || '|' || cast(new.UpdatedAt as text))
+ *
+ * Keep {@link peerRecordSignedPayload} and that constraint byte-for-byte in
+ * sync. The `'|'` delimiter is safe: a base58btc PeerId, a multiaddr (which uses
+ * `/`), and a base-10 integer never contain it.
+ *
+ * `publicKey` is deliberately excluded from the payload — it is the key the
+ * signature is verified *with* (so a signature already commits to exactly one
+ * key), and its binding to `peerId` is checked separately at resolve time.
+ */
+import type { PeerAddressRecord, PeerResolveTrustPolicy } from './types.js';
+/**
+ * Default freshness ceiling for resolved peer-address records (15 minutes).
+ * A record older than this is treated as stale and filtered out, so a resolver
+ * never hands back a dead relay reservation. The publish path re-stamps at
+ * roughly half this interval (see {@link DEFAULT_PEER_RECORD_HEARTBEAT_MS}).
+ */
+export declare const DEFAULT_PEER_RECORD_MAX_AGE_MS: number;
+/**
+ * TTL heartbeat interval for re-publishing the self record — half the freshness
+ * ceiling, so a record is refreshed well before it can go stale.
+ */
+export declare const DEFAULT_PEER_RECORD_HEARTBEAT_MS: number;
+/**
+ * Build the base64url SHA-256 digest that the self-signature covers. Mirrors the
+ * `CadrePeer.AuthorizedUpdate` constraint exactly; both sides take the default
+ * base64url output of a single `digest(...)`, which round-trips cleanly (unlike
+ * concatenating several base64url digests).
+ *
+ * @param peerId - base58btc libp2p peer id (the row key)
+ * @param multiaddr - the comma-joined `Multiaddr` string EXACTLY as stored
+ * @param updatedAt - epoch-ms freshness stamp
+ */
+export declare function peerRecordSignedPayload(peerId: string, multiaddr: string, updatedAt: number): string;
+/**
+ * Sign a peer-address record with the ed25519 private key behind its `peerId`.
+ * Returns a fully-populated {@link PeerAddressRecord} (the `addrs` order is
+ * preserved and is the order signed over).
+ *
+ * @param fields - the record fields to sign (signaling addr first by convention)
+ * @param privateKeyB64 - base64url ed25519 seed (see `ed25519KeyPairFromLibp2p`)
+ */
+export declare function signPeerRecord(fields: {
+    peerId: string;
+    publicKey: string;
+    addrs: string[];
+    updatedAt: number;
+}, privateKeyB64: string): PeerAddressRecord;
+/**
+ * Verify a record's self-signature against its own `publicKey`. Reconstructs the
+ * signed bytes from the record exactly as {@link signPeerRecord} produced them.
+ * Returns false on a missing key/sig or any verification failure.
+ */
+export declare function verifyPeerRecordSignature(record: PeerAddressRecord): boolean;
+/**
+ * Freshness predicate: true when `updatedAt` is a positive stamp within
+ * `maxAgeMs` of `now`. A non-positive `updatedAt` (never self-published) is
+ * never fresh.
+ */
+export declare function isPeerRecordFresh(updatedAt: number, maxAgeMs: number, now: number): boolean;
+/** True if `addr` is a `/p2p-circuit` signaling/relay multiaddr. */
+export declare function isSignalingAddr(addr: string): boolean;
+/**
+ * Return `addrs` with signaling (`/p2p-circuit`) addrs first, otherwise stable.
+ * Used to present the WebRTC dial input ahead of direct addrs. Does NOT mutate
+ * the input and must not be used before signature verification (verification
+ * uses the original on-record order).
+ */
+export declare function orderSignalingFirst(addrs: string[]): string[];
+/**
+ * Default resolve trust gate: trust any peer that has a `CadrePeer` row.
+ *
+ * A row only exists because an owner signed its `AuthorizedInsert`, so row
+ * presence already means "owner-vouched member". This is the seam where a
+ * stricter policy (trust circle, pinned keys) plugs in — see
+ * {@link PeerResolveTrustPolicy}.
+ */
+export declare function currentMemberTrustPolicy(): PeerResolveTrustPolicy;