@cello-protocol/crypto 0.0.2

package/dist/frost/stubs.js

@@ -0,0 +1,157 @@
+/**
+ * In-process directory node stubs for FROST tests.
+ *
+ * CELLO-CRYPTO-003
+ *
+ * These stubs mimic the behavior of a real directory node's /cello/frost/1.0.0
+ * protocol handler. They exercise the same ceremony protocol logic as real nodes
+ * but run in-process for fast, deterministic tests.
+ *
+ * Stub configuration options:
+ * - Normal: responds with valid partial signatures
+ * - Unreachable: node is not reachable at initiation (caught by pre-ceremony check)
+ * - Unresponsive: reachable at initiation, but signRound times out (returns null)
+ * - InvalidResponse: returns random bytes (simulates malformed partial sig)
+ */
+import { ed25519_FROST } from "@noble/curves/ed25519.js";
+import { randomBytes } from "@noble/hashes/utils.js";
+// ─── InProcessDirectoryNodeStub ───────────────────────────────────────────────
+export class InProcessDirectoryNodeStub {
+    id;
+    // Signing key — received via receiveShare() during bootstrap
+    #key = null;
+    // Behavior flags
+    // #unreachable: not reachable at initiation (isReachable() → false)
+    #unreachable = false;
+    // #unresponsive: reachable at initiation, but signRound returns null (timeout simulation)
+    #unresponsive = false;
+    // #invalidResponse: returns random bytes on signRound (malformed partial sig)
+    #invalidResponse = false;
+    constructor(id) {
+        this.id = id;
+    }
+    // ─── DirectoryNodeStub: receiveShare ─────────────────────────────────────────
+    /**
+     * Receive a FROST signing share from the bootstrap ceremony.
+     * Called by bootstrapKeyShares during setup.
+     */
+    async receiveShare(secret, pub) {
+        this.#key = { secret, pub };
+    }
+    /**
+     * TEST-ONLY: Return the stored FROST key pair for use by external test harnesses
+     * (e.g., to inject a share into a FrostDirectoryHandler via injectShareForTest).
+     *
+     * This deliberately exposes the raw FrostSecret for test setup purposes.
+     * MUST NOT be called outside of test code.
+     */
+    getShareForTest() {
+        return this.#key;
+    }
+    // ─── Test control methods ────────────────────────────────────────────────────
+    /**
+     * Mark this node as unreachable at ceremony initiation.
+     * isReachable() will return false, causing the coordinator to exclude
+     * this node before any rounds begin.
+     */
+    setUnreachable(flag) {
+        this.#unreachable = flag;
+    }
+    /**
+     * Mark this node as unresponsive during signing rounds.
+     * isReachable() returns true (node is connectable) but signRound returns null
+     * (simulates a timeout after connection is established).
+     */
+    setUnresponsive(flag) {
+        this.#unresponsive = flag;
+    }
+    /** Make this stub return random bytes (simulate malformed partial sig) */
+    setInvalidResponse(flag) {
+        this.#invalidResponse = flag;
+    }
+    // ─── DirectoryNodeStub interface ─────────────────────────────────────────────
+    /**
+     * Returns whether this node is reachable at ceremony initiation.
+     * The coordinator uses this for the pre-ceremony availability check:
+     * if fewer than `threshold` nodes are reachable, fail immediately
+     * with DIRECTORY_BELOW_THRESHOLD.
+     */
+    isReachable() {
+        return !this.#unreachable;
+    }
+    // Cache the pending nonce between generateCommitment() and signRound()
+    // Per RFC 9591: nonces are one-time-use — consumed after signRound
+    #pendingNonce = null;
+    /**
+     * Generate a nonce commitment for the next signing round.
+     * Called by the coordinator before collecting partial signatures.
+     * Caches the nonce scalars for use in signRound().
+     */
+    async generateCommitment() {
+        if (!this.#key) {
+            throw new Error(`Stub ${this.id} has no key share (not bootstrapped)`);
+        }
+        const nonce = ed25519_FROST.commit(this.#key.secret);
+        // Cache nonce scalars so signRound can use them
+        this.#pendingNonce = nonce.nonces;
+        return {
+            nodeId: this.id,
+            nonceCommitment: nonce.commitments,
+            nonces: nonce.nonces,
+        };
+    }
+    /**
+     * Participate in a signing round.
+     *
+     * Uses the nonce cached from the preceding generateCommitment() call.
+     * Returns a never-resolving Promise to simulate timeout (the coordinator's
+     * per-node timer will fire first). Returns random bytes to simulate
+     * an invalid partial sig.
+     *
+     * @returns Partial signature bytes, or a hanging Promise (simulate timeout)
+     */
+    async signRound(params) {
+        // Unresponsive: simulate a node that never responds.
+        // Return a Promise that never resolves — the coordinator's roundTimeoutMs
+        // timer will fire first, treating this as a timeout.
+        if (this.#unresponsive) {
+            return new Promise(() => {
+                // intentionally never resolve — coordinator timeout fires instead
+            });
+        }
+        if (!this.#key) {
+            return null;
+        }
+        // InvalidResponse: return random bytes (not a valid partial sig)
+        if (this.#invalidResponse) {
+            return new Uint8Array(randomBytes(32));
+        }
+        // Use the nonce cached from generateCommitment()
+        if (!this.#pendingNonce) {
+            // No pending nonce — should not happen in normal ceremony flow
+            return null;
+        }
+        const nonces = this.#pendingNonce;
+        this.#pendingNonce = null; // consume nonce (one-time use per RFC 9591)
+        try {
+            const sig = ed25519_FROST.signShare(this.#key.secret, params.pub, nonces, params.commitmentList, params.msg);
+            return sig;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+// ─── createInProcessStubs ─────────────────────────────────────────────────────
+/**
+ * Create n in-process directory node stubs.
+ * Each stub has a unique deterministic ID.
+ */
+export function createInProcessStubs(n) {
+    return Array.from({ length: n }, (_, i) => {
+        // Use a stable, deterministic ID that works as a FROST identifier input
+        const id = `cello-test-node-${i.toString().padStart(4, "0")}`;
+        return new InProcessDirectoryNodeStub(id);
+    });
+}
+//# sourceMappingURL=stubs.js.map

package/dist/frost/stubs.js.map

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

package/dist/frost/types.d.ts

@@ -0,0 +1,173 @@
+/**
+ * FROST Threshold Signing Abstraction — Type Definitions
+ *
+ * CELLO-CRYPTO-003
+ *
+ * Design decisions:
+ * - `IThresholdSigner` is separate from `KeyProvider`. `KeyProvider` handles K_local
+ *   envelope signing; `IThresholdSigner` handles the multi-party threshold ceremony.
+ * - Two domain context strings are defined (M2 only):
+ *   - "cello-frost-session-establishment-v1" — session establishment TBS
+ *   - "cello-frost-seal-v1"                 — conversation seal TBS
+ * - Context is prepended to the TBS before signing to achieve domain separation.
+ *   FROST over ed25519 does not support a native context parameter, so we use
+ *   a framed encoding: `<context>\0<tbs>`.
+ * - `primary_pubkey` is the group public key (commitments[0] from FROST public package).
+ *   It is derived deterministically from all n nodes' share commitments. Per-agent.
+ */
+export declare const CONTEXT_SESSION_ESTABLISHMENT: "cello-frost-session-establishment-v1";
+export declare const CONTEXT_SEAL: "cello-frost-seal-v1";
+export type FrostContext = typeof CONTEXT_SESSION_ESTABLISHMENT | typeof CONTEXT_SEAL;
+export type ThresholdSignatureOk = {
+    readonly ok: true;
+    readonly signature: Uint8Array;
+};
+export type ThresholdSignatureError = {
+    readonly ok: false;
+    readonly error: {
+        readonly reason: "DIRECTORY_BELOW_THRESHOLD" | "CEREMONY_TIMEOUT" | "CEREMONY_EXHAUSTED";
+    };
+};
+export type ThresholdSignature = ThresholdSignatureOk | ThresholdSignatureError;
+export type CeremonyProgressEvent = {
+    type: "commit_collected";
+    index: number;
+    total: number;
+} | {
+    type: "partial_sig_collected";
+    index: number;
+    total: number;
+};
+export type CeremonyProgressCallback = (event: CeremonyProgressEvent) => void;
+/**
+ * IThresholdSigner: the swap point for all threshold signing in the protocol.
+ *
+ * Implementations MUST:
+ * - Keep the local FROST key share within the crypto package boundary
+ * - Never log or return key share material in any error or diagnostic path
+ * - Use the context string for domain separation (framed: `<context>\0<tbs>`)
+ */
+export interface IThresholdSigner {
+    /**
+     * Participate in a threshold signing ceremony as coordinator.
+     *
+     * Opens streams to `threshold` directory nodes, runs the FROST protocol
+     * with the given `context` string for domain separation, collects partial
+     * signature shares, combines them, and returns the aggregated signature.
+     *
+     * @param ceremonyId - Unique identifier for this ceremony instance
+     * @param tbs - The to-be-signed bytes (domain-specific payload)
+     * @param context - Domain context string for separation (e.g. CONTEXT_SESSION_ESTABLISHMENT)
+     */
+    participateInCeremony(ceremonyId: string, tbs: Uint8Array, context: FrostContext, onProgress?: CeremonyProgressCallback): Promise<ThresholdSignature>;
+    /**
+     * Return the group public key (primary_pubkey) for this threshold signer.
+     *
+     * This is commitments[0] from the FROST public package — the constant term
+     * of the dealer's Shamir polynomial commitment. It is the same 32-byte
+     * Ed25519 point used to verify threshold signatures produced by participateInCeremony.
+     *
+     * Called by the directory to embed primary_pubkey in the SessionAssignment
+     * (signer_pubkey field) so the counterparty can verify without a round-trip.
+     *
+     * Throws if not bootstrapped (no local share available).
+     */
+    getPrimaryPubkey(): Uint8Array;
+    /**
+     * Verify a combined FROST threshold signature.
+     *
+     * Used by the seal verifier (both initiator and counterparty) to confirm
+     * that a session_sealed FROST signature is valid before transitioning to sealed.
+     *
+     * @param signature - 64-byte combined FROST signature
+     * @param tbs - The to-be-signed bytes (same as passed to participateInCeremony)
+     * @param context - Domain context string used during signing
+     * @param publicKey - 32-byte group public key (primary_pubkey) to verify against
+     * @returns true if the signature is valid
+     */
+    verifySignature(signature: Uint8Array, tbs: Uint8Array, context: FrostContext, publicKey: Uint8Array): boolean;
+}
+/**
+ * Configuration for FrostThresholdSigner.
+ *
+ * `directoryNodes` is used in production; `directoryNodeStubs` is an injection
+ * point for in-process test stubs that exercise the same ceremony logic.
+ */
+export interface FrostThresholdSignerConfig {
+    /** t in t-of-n: minimum signers required */
+    readonly threshold: number;
+    /** n: total participants */
+    readonly participants: number;
+    /** Production: multiaddr strings pointing to directory nodes */
+    readonly directoryNodes?: string[];
+    /** Test injection: in-process stubs that mimic directory node behavior */
+    readonly directoryNodeStubs?: DirectoryNodeStub[];
+    /** Timeout for a single round (one node response), default 3000ms */
+    readonly roundTimeoutMs?: number;
+    /** Timeout for the entire ceremony across all retries, default 30000ms */
+    readonly ceremonyTimeoutMs?: number;
+    /** Maximum ceremony attempts before CEREMONY_EXHAUSTED, default 3 */
+    readonly maxRetries?: number;
+}
+/**
+ * DirectoryNodeStub: in-process stand-in for a real directory node's
+ * /cello/frost/1.0.0 protocol handler.
+ *
+ * The stub holds its own FROST secret share and responds to ceremony rounds.
+ * Stubs can be configured to timeout or return invalid partial signatures.
+ */
+export interface DirectoryNodeStub {
+    /** Stable identifier for this stub node */
+    readonly id: string;
+    /**
+     * Returns whether this node is reachable at ceremony initiation time.
+     * An unreachable node is excluded before any rounds begin.
+     * Used by the coordinator's pre-ceremony availability check.
+     */
+    isReachable(): boolean;
+    /**
+     * Participate in a signing round.
+     *
+     * Returns a partial signature share for the given commitment list and message,
+     * or null to simulate a timeout.
+     *
+     * @param pub - The shared FROST public package
+     * @param commitmentList - Nonce commitments from all signers in this round
+     * @param msg - The framed message (context + tbs)
+     * @returns Partial signature bytes, or null to simulate timeout
+     */
+    signRound(params: StubSignParams): Promise<Uint8Array | null>;
+    /**
+     * Generate nonce commitment for a round.
+     * Called by the coordinator before collecting partial signatures.
+     * Returns a Promise to support both in-process stubs and network nodes.
+     */
+    generateCommitment(): Promise<StubCommitment>;
+    /**
+     * Receive a FROST signing share from the bootstrap ceremony.
+     * Called by bootstrapKeyShares during setup.
+     * Returns a Promise to support both in-process stubs and network nodes.
+     */
+    receiveShare(secret: import("@noble/curves/abstract/frost.js").FrostSecret, pub: import("@noble/curves/abstract/frost.js").FrostPublic): Promise<void>;
+}
+export interface StubSignParams {
+    pub: import("@noble/curves/abstract/frost.js").FrostPublic;
+    commitmentList: import("@noble/curves/abstract/frost.js").NonceCommitments[];
+    msg: Uint8Array;
+    /** Unique ID for this ceremony instance — passed through so network nodes can use it for conflict detection. */
+    ceremonyId: string;
+}
+export interface StubCommitment {
+    nodeId: string;
+    nonceCommitment: import("@noble/curves/abstract/frost.js").NonceCommitments;
+    nonces: import("@noble/curves/abstract/frost.js").Nonces;
+}
+export interface BootstrapResult {
+    /**
+     * The group public key derived deterministically from all n nodes' share commitments.
+     * 32-byte Ed25519 point. Stored alongside K_local.
+     * This is the only key material returned from bootstrapKeyShares.
+     */
+    readonly primaryPubkey: Uint8Array;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/frost/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/frost/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,eAAO,MAAM,6BAA6B,EACxC,sCAA+C,CAAC;AAClD,eAAO,MAAM,YAAY,EAAG,qBAA8B,CAAC;AAE3D,MAAM,MAAM,YAAY,GACpB,OAAO,6BAA6B,GACpC,OAAO,YAAY,CAAC;AAIxB,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,MAAM,EACX,2BAA2B,GAC3B,kBAAkB,GAClB,oBAAoB,CAAC;KAC1B,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,oBAAoB,GAAG,uBAAuB,CAAC;AAIhF,MAAM,MAAM,qBAAqB,GAC7B;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,uBAAuB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpE,MAAM,MAAM,wBAAwB,GAAG,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;AAI9E;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;OAUG;IACH,qBAAqB,CACnB,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,UAAU,EACf,OAAO,EAAE,YAAY,EACrB,UAAU,CAAC,EAAE,wBAAwB,GACpC,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAE/B;;;;;;;;;;;OAWG;IACH,gBAAgB,IAAI,UAAU,CAAC;IAE/B;;;;;;;;;;;OAWG;IACH,eAAe,CACb,SAAS,EAAE,UAAU,EACrB,GAAG,EAAE,UAAU,EACf,OAAO,EAAE,YAAY,EACrB,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC;CACZ;AAID;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4BAA4B;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,gEAAgE;IAChE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,kBAAkB,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAClD,qEAAqE;IACrE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,0EAA0E;IAC1E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,qEAAqE;IACrE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAID;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,WAAW,IAAI,OAAO,CAAC;IAEvB;;;;;;;;;;OAUG;IACH,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAE9D;;;;OAIG;IACH,kBAAkB,IAAI,OAAO,CAAC,cAAc,CAAC,CAAC;IAE9C;;;;OAIG;IACH,YAAY,CACV,MAAM,EAAE,OAAO,iCAAiC,EAAE,WAAW,EAC7D,GAAG,EAAE,OAAO,iCAAiC,EAAE,WAAW,GACzD,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,OAAO,iCAAiC,EAAE,WAAW,CAAC;IAC3D,cAAc,EAAE,OAAO,iCAAiC,EAAE,gBAAgB,EAAE,CAAC;IAC7E,GAAG,EAAE,UAAU,CAAC;IAChB,gHAAgH;IAChH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,OAAO,iCAAiC,EAAE,gBAAgB,CAAC;IAC5E,MAAM,EAAE,OAAO,iCAAiC,EAAE,MAAM,CAAC;CAC1D;AAID,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC;CACpC"}

package/dist/frost/types.js

@@ -0,0 +1,21 @@
+/**
+ * FROST Threshold Signing Abstraction — Type Definitions
+ *
+ * CELLO-CRYPTO-003
+ *
+ * Design decisions:
+ * - `IThresholdSigner` is separate from `KeyProvider`. `KeyProvider` handles K_local
+ *   envelope signing; `IThresholdSigner` handles the multi-party threshold ceremony.
+ * - Two domain context strings are defined (M2 only):
+ *   - "cello-frost-session-establishment-v1" — session establishment TBS
+ *   - "cello-frost-seal-v1"                 — conversation seal TBS
+ * - Context is prepended to the TBS before signing to achieve domain separation.
+ *   FROST over ed25519 does not support a native context parameter, so we use
+ *   a framed encoding: `<context>\0<tbs>`.
+ * - `primary_pubkey` is the group public key (commitments[0] from FROST public package).
+ *   It is derived deterministically from all n nodes' share commitments. Per-agent.
+ */
+// ─── Domain context strings ──────────────────────────────────────────────────
+export const CONTEXT_SESSION_ESTABLISHMENT = "cello-frost-session-establishment-v1";
+export const CONTEXT_SEAL = "cello-frost-seal-v1";
+//# sourceMappingURL=types.js.map

package/dist/frost/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/frost/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,gFAAgF;AAEhF,MAAM,CAAC,MAAM,6BAA6B,GACxC,sCAA+C,CAAC;AAClD,MAAM,CAAC,MAAM,YAAY,GAAG,qBAA8B,CAAC"}

package/dist/hashing.d.ts

@@ -0,0 +1,17 @@
+export declare function hash(data: Uint8Array): Uint8Array;
+export declare function msgLeafHash(data: Uint8Array): Uint8Array;
+export declare function nodeHash(left: Uint8Array, right: Uint8Array): Uint8Array;
+export declare function ctrlLeafHash(data: Uint8Array): Uint8Array;
+/**
+ * Build the to-be-signed bytes for a relay hash-submit ACK.
+ *
+ * TBS = SHA-256(hash_bytes || seq_BE4 || ts_BE8)
+ *   hash_bytes: 32 raw bytes (the Structure 1 content_hash — NOT hex-encoded)
+ *   seq_BE4:    sequence_number as 4-byte big-endian uint32
+ *   ts_BE8:     timestamp as 8-byte big-endian uint64
+ *
+ * Both the relay (signer) and the client (verifier) must use this function so
+ * they cannot diverge. RFC 8032 (Ed25519), FIPS 180-4 (SHA-256).
+ */
+export declare function buildRelayAckTbs(hashBytes: Uint8Array, sequenceNumber: number, timestamp: number): Uint8Array;
+//# sourceMappingURL=hashing.d.ts.map

package/dist/hashing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hashing.d.ts","sourceRoot":"","sources":["../src/hashing.ts"],"names":[],"mappings":"AAcA,wBAAgB,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAEjD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAExD;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,GAAG,UAAU,CASxE;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAEzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,UAAU,EACrB,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,GAChB,UAAU,CASZ"}

package/dist/hashing.js

@@ -0,0 +1,50 @@
+import { createHash } from "node:crypto";
+import { sha256 } from "@noble/hashes/sha2.js";
+const MSG_LEAF = 0x00;
+const INTERNAL_NODE = 0x01;
+const CTRL_LEAF = 0x02;
+function prefixed(prefix, data) {
+    const buf = new Uint8Array(1 + data.length);
+    buf[0] = prefix;
+    buf.set(data, 1);
+    return buf;
+}
+export function hash(data) {
+    return sha256(data);
+}
+export function msgLeafHash(data) {
+    return sha256(prefixed(MSG_LEAF, data));
+}
+export function nodeHash(left, right) {
+    if (left.length !== 32 || right.length !== 32) {
+        throw new Error(`nodeHash: expected 32-byte inputs, got left=${left.length} right=${right.length}`);
+    }
+    const buf = new Uint8Array(1 + left.length + right.length);
+    buf[0] = INTERNAL_NODE;
+    buf.set(left, 1);
+    buf.set(right, 1 + left.length);
+    return sha256(buf);
+}
+export function ctrlLeafHash(data) {
+    return sha256(prefixed(CTRL_LEAF, data));
+}
+/**
+ * Build the to-be-signed bytes for a relay hash-submit ACK.
+ *
+ * TBS = SHA-256(hash_bytes || seq_BE4 || ts_BE8)
+ *   hash_bytes: 32 raw bytes (the Structure 1 content_hash — NOT hex-encoded)
+ *   seq_BE4:    sequence_number as 4-byte big-endian uint32
+ *   ts_BE8:     timestamp as 8-byte big-endian uint64
+ *
+ * Both the relay (signer) and the client (verifier) must use this function so
+ * they cannot diverge. RFC 8032 (Ed25519), FIPS 180-4 (SHA-256).
+ */
+export function buildRelayAckTbs(hashBytes, sequenceNumber, timestamp) {
+    const seqBuf = Buffer.allocUnsafe(4);
+    seqBuf.writeUInt32BE(sequenceNumber >>> 0, 0);
+    const tsBuf = Buffer.allocUnsafe(8);
+    tsBuf.writeBigUInt64BE(BigInt(timestamp), 0);
+    const preimage = Buffer.concat([Buffer.from(hashBytes), seqBuf, tsBuf]);
+    return new Uint8Array(createHash("sha256").update(preimage).digest());
+}
+//# sourceMappingURL=hashing.js.map

package/dist/hashing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hashing.js","sourceRoot":"","sources":["../src/hashing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE/C,MAAM,QAAQ,GAAG,IAAI,CAAC;AACtB,MAAM,aAAa,GAAG,IAAI,CAAC;AAC3B,MAAM,SAAS,GAAG,IAAI,CAAC;AAEvB,SAAS,QAAQ,CAAC,MAAc,EAAE,IAAgB;IAChD,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5C,GAAG,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC;IAChB,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACjB,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,IAAgB;IACnC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAgB;IAC1C,OAAO,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,IAAgB,EAAE,KAAiB;IAC1D,IAAI,IAAI,CAAC,MAAM,KAAK,EAAE,IAAI,KAAK,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CAAC,+CAA+C,IAAI,CAAC,MAAM,UAAU,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACtG,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IAC3D,GAAG,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC;IACvB,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACjB,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAChC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAgB;IAC3C,OAAO,MAAM,CAAC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAC9B,SAAqB,EACrB,cAAsB,EACtB,SAAiB;IAEjB,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IACrC,MAAM,CAAC,aAAa,CAAC,cAAc,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;IAE9C,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IACpC,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC;IAE7C,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;IACxE,OAAO,IAAI,UAAU,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;AACxE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export type { KeyProvider, PublicKey, Signature, KeyFileCorruptError } from "./types.js";
+export { InMemoryKeyProvider, FileKeyProvider, generateKeypair, verify } from "./ed25519.js";
+export type { MlDsaPublicKey, MlDsaSignature, MlDsaKeyPair, MlDsaKeyProvider } from "./ml-dsa.js";
+export { InMemoryMlDsaKeyProvider, FileMlDsaKeyProvider, mlDsaKeygen, mlDsaSign, mlDsaVerify, mlDsaEnsureLoaded, } from "./ml-dsa.js";
+export { hash, msgLeafHash, nodeHash, ctrlLeafHash, buildRelayAckTbs } from "./hashing.js";
+export type { MerkleTree, LeafInput } from "./merkle.js";
+export { buildMerkleTree, merkleRoot, inclusionProof, verifyInclusion } from "./merkle.js";
+export type { IThresholdSigner, ThresholdSignature, ThresholdSignatureOk, ThresholdSignatureError, FrostThresholdSignerConfig, FrostContext, BootstrapResult, } from "./frost/index.js";
+export { CONTEXT_SESSION_ESTABLISHMENT, CONTEXT_SEAL, FrostThresholdSigner, MockThresholdSigner, } from "./frost/index.js";
+export { verifyFrostSignature } from "./frost/frost-threshold-signer.js";
+export { ed25519_FROST } from "@noble/curves/ed25519.js";
+export { buildCheckpointTbs, computeCheckpointHash } from "./checkpoint.js";
+export { buildRelayRegistrationTbs, verifyRelayRegistrationSignature } from "./relay-registration.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACzF,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC7F,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAClG,OAAO,EACL,wBAAwB,EACxB,oBAAoB,EACpB,WAAW,EACX,SAAS,EACT,WAAW,EACX,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC3F,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC3F,YAAY,EACV,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,EACvB,0BAA0B,EAC1B,YAAY,EACZ,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,6BAA6B,EAC7B,YAAY,EACZ,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAGzE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAGzD,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAG5E,OAAO,EAAE,yBAAyB,EAAE,gCAAgC,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+export { InMemoryKeyProvider, FileKeyProvider, generateKeypair, verify } from "./ed25519.js";
+export { InMemoryMlDsaKeyProvider, FileMlDsaKeyProvider, mlDsaKeygen, mlDsaSign, mlDsaVerify, mlDsaEnsureLoaded, } from "./ml-dsa.js";
+export { hash, msgLeafHash, nodeHash, ctrlLeafHash, buildRelayAckTbs } from "./hashing.js";
+export { buildMerkleTree, merkleRoot, inclusionProof, verifyInclusion } from "./merkle.js";
+export { CONTEXT_SESSION_ESTABLISHMENT, CONTEXT_SEAL, FrostThresholdSigner, MockThresholdSigner, } from "./frost/index.js";
+// SESSION-004: standalone FROST verify (no signer instance needed — used by counterparty client)
+export { verifyFrostSignature } from "./frost/frost-threshold-signer.js";
+// REG-001: re-export ed25519_FROST for DKG coordinator in @cello-protocol/client
+export { ed25519_FROST } from "@noble/curves/ed25519.js";
+// FEDERATION-002: canonical checkpoint TBS serialization and hash computation
+export { buildCheckpointTbs, computeCheckpointHash } from "./checkpoint.js";
+// FEDERATION-003: relay registration TBS and signature verification
+export { buildRelayRegistrationTbs, verifyRelayRegistrationSignature } from "./relay-registration.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE7F,OAAO,EACL,wBAAwB,EACxB,oBAAoB,EACpB,WAAW,EACX,SAAS,EACT,WAAW,EACX,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAE3F,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAU3F,OAAO,EACL,6BAA6B,EAC7B,YAAY,EACZ,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAE1B,iGAAiG;AACjG,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAEzE,iFAAiF;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEzD,8EAA8E;AAC9E,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAE5E,oEAAoE;AACpE,OAAO,EAAE,yBAAyB,EAAE,gCAAgC,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/merkle.d.ts

@@ -0,0 +1,162 @@
+/**
+ * RFC 6962 Merkle Tree Primitives
+ *
+ * PSEUDOCODE (Phase P)
+ * ====================
+ * References:
+ *   RFC 6962 §2.1   — Merkle Hash Trees: construction
+ *   RFC 6962 §2.1.1 — Merkle Audit Paths (inclusion proofs)
+ *   FIPS 180-4      — SHA-256 specification
+ *
+ * --- build(leaves: Uint8Array[]) ---
+ *   if leaves is empty:
+ *     return SHA-256("")  // RFC 6962 §2.1: D[0] = {}
+ *   level := [leafHash(l) for l in leaves]  // SHA-256(0x00 || l)
+ *   while level.length > 1:
+ *     next := []
+ *     for i in 0..level.length step 2:
+ *       if i+1 < level.length:
+ *         next.push(nodeHash(level[i], level[i+1]))  // SHA-256(0x01 || left || right)
+ *       else:
+ *         next.push(level[i])   // promote odd node — RFC 6962 §2.1: left-balanced
+ *     level := next
+ *   return level[0]  // root
+ *
+ * --- inclusionProof(tree, index) ---
+ *   // RFC 6962 §2.1.1: PATH(m, D[n]) = [] if n=1
+ *   //   otherwise siblings from leaf level up to root
+ *   level := tree.levelHashes[0]  // leaf hashes
+ *   proof := []
+ *   idx := index
+ *   while level.length > 1:
+ *     sibling := idx XOR 1  // flips last bit: 0→1 (right sibling), 1→0 (left sibling)
+ *     if sibling < level.length:
+ *       proof.push(level[sibling])
+ *     // else: odd node was promoted — no sibling hash in proof
+ *     next := ... (pair-and-promote)
+ *     idx := idx >> 1
+ *     level := next
+ *   return proof
+ *
+ * --- verify(leafHash, index, treeSize, proof, expectedRoot) ---
+ *   if treeSize == 0 or index >= treeSize: return false
+ *   if treeSize == 1 and proof.empty: return leafHash == expectedRoot
+ *   cur := leafHash
+ *   idx := index; sz := treeSize; pi := 0
+ *   while sz > 1:
+ *     if idx is last at this level AND idx is even (promoted, no sibling):
+ *       // cur carries up unchanged
+ *     else:
+ *       if pi >= proof.length: return false
+ *       if proof[pi].length != 32: return false  // AC-008: 31-byte sibling
+ *       if idx is odd: cur := nodeHash(proof[pi], cur)   // sibling is on the left
+ *       else:          cur := nodeHash(cur, proof[pi])   // sibling is on the right
+ *       pi++
+ *     idx := idx >> 1
+ *     sz := ceil(sz / 2)
+ *   if pi != proof.length: return false  // wrong proof length (extra elements)
+ *   return cur == expectedRoot
+ *
+ * --- edge cases ---
+ *   index >= treeSize → false, no throw
+ *   wrong proof length → false, no throw
+ *   31-byte sibling hash → false, no throw
+ *   empty tree → SHA-256("") per RFC 6962 §2.1
+ *
+ * --- second-preimage protection (SI-001) ---
+ *   Leaves are hashed as SHA-256(0x00 || data) — the 0x00 prefix ensures a crafted
+ *   leaf payload that begins with 0x01 cannot collide with an internal nodeHash,
+ *   because nodeHash uses 0x01 prefix on the already-hashed children, not the raw data.
+ */
+/**
+ * Internal representation of a built Merkle tree.
+ * Stores all level hashes from leaf level (index 0) to root level (last index).
+ * Root is levelHashes[levelHashes.length - 1][0].
+ */
+export interface MerkleTree {
+    /** The number of leaves in this tree. */
+    readonly size: number;
+    /**
+     * All levels of the tree.
+     * levelHashes[0] = leaf hashes (SHA-256(prefix || data) for each leaf)
+     * levelHashes[k] = hashes at level k (pairs merged with nodeHash, odd promoted)
+     * levelHashes[levelHashes.length - 1] = [root]
+     *
+     * Empty tree: levelHashes = [] and root is SHA-256("").
+     */
+    readonly levelHashes: readonly (readonly Uint8Array[])[];
+}
+/**
+ * A leaf input with an explicit kind for domain separation.
+ * - "msg":  hashed as SHA-256(0x00 || data) — message leaves
+ * - "ctrl": hashed as SHA-256(0x02 || data) — control leaves (SEAL, etc.)
+ * - "hash": data is already a 32-byte leaf hash; used directly (no prefix applied)
+ */
+export type LeafInput = {
+    kind: "msg";
+    data: Uint8Array;
+} | {
+    kind: "ctrl";
+    data: Uint8Array;
+} | {
+    kind: "hash";
+    data: Uint8Array;
+};
+/**
+ * Build a left-balanced Merkle tree from an ordered list of leaf inputs.
+ *
+ * Per RFC 6962 §2.1:
+ *   - "msg"  leaves: SHA-256(0x00 || data) using msgLeafHash from hashing.ts
+ *   - "ctrl" leaves: SHA-256(0x02 || data) using ctrlLeafHash from hashing.ts
+ *   - "hash" leaves: data used as-is (caller pre-computed the leaf hash)
+ *   - Internal nodes: SHA-256(0x01 || left || right) using nodeHash from hashing.ts
+ *   - Odd nodes at each level are promoted unchanged (not duplicated)
+ *   - Empty tree root = SHA-256("") (SHA-256 of empty byte string)
+ *
+ * @param leaves - Leaf inputs with explicit kind for correct prefix application.
+ * @returns MerkleTree with all level hashes stored for O(log n) proof generation.
+ */
+export declare function buildMerkleTree(leaves: LeafInput[]): MerkleTree;
+/**
+ * Return the Merkle root of a built tree.
+ *
+ * Per RFC 6962 §2.1:
+ *   - Empty tree → SHA-256("") (SHA-256 of empty byte string)
+ *   - Otherwise → the single hash at the top level of levelHashes
+ *
+ * @param tree - A MerkleTree returned by buildMerkleTree.
+ * @returns 32-byte root hash.
+ */
+export declare function merkleRoot(tree: MerkleTree): Uint8Array;
+/**
+ * Produce an RFC 6962 §2.1.1 inclusion proof for leaf at index.
+ *
+ * The proof is an ordered list of sibling hashes from the leaf level to the root.
+ * For each level, the sibling of the current node is included. Promoted (odd, last)
+ * nodes have no sibling at their level, so no hash is added.
+ *
+ * @param tree   - A MerkleTree returned by buildMerkleTree.
+ * @param index  - Zero-based index of the target leaf.
+ * @returns      Array of 32-byte sibling hashes (may be empty for a single-leaf tree).
+ * @throws       If index is out of range.
+ */
+export declare function inclusionProof(tree: MerkleTree, index: number): Uint8Array[];
+/**
+ * Verify an RFC 6962 §2.1.1 inclusion proof.
+ *
+ * Reconstructs the root by traversing the proof from leaf to root and compares
+ * byte-for-byte to expectedRoot. Returns false (never throws) for all invalid inputs:
+ *   - index out of range
+ *   - wrong proof length
+ *   - any sibling hash not exactly 32 bytes
+ *   - reconstructed root doesn't match expectedRoot
+ *
+ * @param leafHash     - Pre-computed leaf hash (SHA-256(0x00 || data)).
+ * @param index        - Zero-based index of the leaf in the tree.
+ * @param treeSize     - Total number of leaves in the tree.
+ * @param proof        - Ordered sibling hashes from inclusionProof.
+ * @param expectedRoot - The expected 32-byte Merkle root.
+ * @returns true iff the proof is valid for the given leaf and root.
+ */
+export declare function verifyInclusion(leafHash: Uint8Array, index: number, treeSize: number, proof: Uint8Array[], expectedRoot: Uint8Array): boolean;
+//# sourceMappingURL=merkle.d.ts.map

package/dist/merkle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merkle.d.ts","sourceRoot":"","sources":["../src/merkle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AAIH;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,EAAE,SAAS,CAAC,SAAS,UAAU,EAAE,CAAC,EAAE,CAAC;CAC1D;AAED;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC;AAEvC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,UAAU,CA4B/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAMvD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,EAAE,CAsB5E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,UAAU,EACpB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,UAAU,EAAE,EACnB,YAAY,EAAE,UAAU,GACvB,OAAO,CAkDT"}