@cello-protocol/crypto 0.0.2

package/dist/checkpoint.d.ts

@@ -0,0 +1,52 @@
+/**
+ * FEDERATION-002 — Canonical checkpoint TBS (to-be-signed) serialization.
+ *
+ * buildCheckpointTbs produces the canonical byte representation for the checkpoint hash:
+ *   SHA-256(mmr_peaks_serialized || identity_merkle_root || checkpoint_id)
+ *
+ * where mmr_peaks_serialized is a canonical JSON array of hex-encoded peak hashes
+ * ordered by MMR position ascending — e.g. '["aabb...","ccdd..."]' with no
+ * whitespace and no object keys, UTF-8 encoded.
+ *
+ * This function MUST live in @cello-protocol/crypto so both:
+ *   - the coordinator (which computes the hash to broadcast)
+ *   - the non-coordinator (which independently recomputes to verify)
+ * import the same serialization. AC-010-canonical-tbs: no inline serialization
+ * of mmr_peaks exists in packages/directory.
+ *
+ * References: FIPS 180-4 (SHA-256), RFC 8032 (Ed25519).
+ */
+/**
+ * Produce the canonical TBS bytes for a checkpoint hash.
+ *
+ * Pseudocode:
+ *   1. Serialize mmr_peaks as a compact JSON array: JSON.stringify(mmrPeaks)
+ *      mmrPeaks must be an array of hex strings ordered by MMR position ascending.
+ *      JSON.stringify produces no whitespace: '["aabb...","ccdd..."]' — FIPS 180-4.
+ *   2. Encode mmr_peaks_serialized as UTF-8 bytes.
+ *   3. Encode identity_merkle_root as UTF-8 bytes.
+ *   4. Encode checkpoint_id as UTF-8 bytes.
+ *   5. Concatenate: mmr_peaks_serialized_bytes || identity_merkle_root_bytes || checkpoint_id_bytes
+ *   6. Compute SHA-256(concatenation) — FIPS 180-4.
+ *   7. Return the 32-byte digest as a Uint8Array.
+ *
+ * @param mmrPeaks - Hex-encoded peak hashes ordered by MMR position ascending.
+ *                   Example: ["aabb...", "ccdd..."] for a 3-leaf MMR with 2 peaks.
+ * @param identityMerkleRoot - Hex-encoded identity Merkle root (32 bytes as hex).
+ * @param checkpointId - UUID string for this checkpoint (as issued by the coordinator).
+ * @returns 32-byte SHA-256 digest — FIPS 180-4.
+ */
+export declare function buildCheckpointTbs(mmrPeaks: readonly string[], identityMerkleRoot: string, checkpointId: string): Uint8Array;
+/**
+ * Compute the hex-encoded checkpoint hash from canonical TBS.
+ *
+ * Convenience wrapper around buildCheckpointTbs that returns a hex string
+ * (matching the `checkpoint_hash` column type in directory_checkpoints).
+ *
+ * @param mmrPeaks - Hex-encoded peak hashes ordered by MMR position ascending.
+ * @param identityMerkleRoot - Hex-encoded identity Merkle root.
+ * @param checkpointId - UUID string for this checkpoint.
+ * @returns 64-character lowercase hex string (32-byte SHA-256 digest).
+ */
+export declare function computeCheckpointHash(mmrPeaks: readonly string[], identityMerkleRoot: string, checkpointId: string): string;
+//# sourceMappingURL=checkpoint.d.ts.map

package/dist/checkpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../src/checkpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,kBAAkB,EAAE,MAAM,EAC1B,YAAY,EAAE,MAAM,GACnB,UAAU,CAkBZ;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,kBAAkB,EAAE,MAAM,EAC1B,YAAY,EAAE,MAAM,GACnB,MAAM,CAER"}

package/dist/checkpoint.js

@@ -0,0 +1,70 @@
+/**
+ * FEDERATION-002 — Canonical checkpoint TBS (to-be-signed) serialization.
+ *
+ * buildCheckpointTbs produces the canonical byte representation for the checkpoint hash:
+ *   SHA-256(mmr_peaks_serialized || identity_merkle_root || checkpoint_id)
+ *
+ * where mmr_peaks_serialized is a canonical JSON array of hex-encoded peak hashes
+ * ordered by MMR position ascending — e.g. '["aabb...","ccdd..."]' with no
+ * whitespace and no object keys, UTF-8 encoded.
+ *
+ * This function MUST live in @cello-protocol/crypto so both:
+ *   - the coordinator (which computes the hash to broadcast)
+ *   - the non-coordinator (which independently recomputes to verify)
+ * import the same serialization. AC-010-canonical-tbs: no inline serialization
+ * of mmr_peaks exists in packages/directory.
+ *
+ * References: FIPS 180-4 (SHA-256), RFC 8032 (Ed25519).
+ */
+import { createHash } from "node:crypto";
+/**
+ * Produce the canonical TBS bytes for a checkpoint hash.
+ *
+ * Pseudocode:
+ *   1. Serialize mmr_peaks as a compact JSON array: JSON.stringify(mmrPeaks)
+ *      mmrPeaks must be an array of hex strings ordered by MMR position ascending.
+ *      JSON.stringify produces no whitespace: '["aabb...","ccdd..."]' — FIPS 180-4.
+ *   2. Encode mmr_peaks_serialized as UTF-8 bytes.
+ *   3. Encode identity_merkle_root as UTF-8 bytes.
+ *   4. Encode checkpoint_id as UTF-8 bytes.
+ *   5. Concatenate: mmr_peaks_serialized_bytes || identity_merkle_root_bytes || checkpoint_id_bytes
+ *   6. Compute SHA-256(concatenation) — FIPS 180-4.
+ *   7. Return the 32-byte digest as a Uint8Array.
+ *
+ * @param mmrPeaks - Hex-encoded peak hashes ordered by MMR position ascending.
+ *                   Example: ["aabb...", "ccdd..."] for a 3-leaf MMR with 2 peaks.
+ * @param identityMerkleRoot - Hex-encoded identity Merkle root (32 bytes as hex).
+ * @param checkpointId - UUID string for this checkpoint (as issued by the coordinator).
+ * @returns 32-byte SHA-256 digest — FIPS 180-4.
+ */
+export function buildCheckpointTbs(mmrPeaks, identityMerkleRoot, checkpointId) {
+    // Step 1+2: canonical JSON serialization of the peak array — no whitespace (FIPS 180-4 §6.2)
+    const mmrPeaksSerialized = JSON.stringify(mmrPeaks);
+    // Steps 3-5: UTF-8 encode and concatenate components
+    const encoder = new TextEncoder();
+    const peakBytes = encoder.encode(mmrPeaksSerialized);
+    const identityBytes = encoder.encode(identityMerkleRoot);
+    const checkpointBytes = encoder.encode(checkpointId);
+    // Step 6: SHA-256(mmr_peaks_serialized || identity_merkle_root || checkpoint_id)
+    const combined = Buffer.concat([
+        Buffer.from(peakBytes),
+        Buffer.from(identityBytes),
+        Buffer.from(checkpointBytes),
+    ]);
+    return new Uint8Array(createHash("sha256").update(combined).digest());
+}
+/**
+ * Compute the hex-encoded checkpoint hash from canonical TBS.
+ *
+ * Convenience wrapper around buildCheckpointTbs that returns a hex string
+ * (matching the `checkpoint_hash` column type in directory_checkpoints).
+ *
+ * @param mmrPeaks - Hex-encoded peak hashes ordered by MMR position ascending.
+ * @param identityMerkleRoot - Hex-encoded identity Merkle root.
+ * @param checkpointId - UUID string for this checkpoint.
+ * @returns 64-character lowercase hex string (32-byte SHA-256 digest).
+ */
+export function computeCheckpointHash(mmrPeaks, identityMerkleRoot, checkpointId) {
+    return Buffer.from(buildCheckpointTbs(mmrPeaks, identityMerkleRoot, checkpointId)).toString("hex");
+}
+//# sourceMappingURL=checkpoint.js.map

package/dist/checkpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.js","sourceRoot":"","sources":["../src/checkpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAA2B,EAC3B,kBAA0B,EAC1B,YAAoB;IAEpB,6FAA6F;IAC7F,MAAM,kBAAkB,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAEpD,qDAAqD;IACrD,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;IAClC,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;IACrD,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;IACzD,MAAM,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAErD,iFAAiF;IACjF,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC;QAC7B,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC;QACtB,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC;QAC1B,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC;KAC7B,CAAC,CAAC;IAEH,OAAO,IAAI,UAAU,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;AACxE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CACnC,QAA2B,EAC3B,kBAA0B,EAC1B,YAAoB;IAEpB,OAAO,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,QAAQ,EAAE,kBAAkB,EAAE,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACrG,CAAC"}

package/dist/ed25519.d.ts

@@ -0,0 +1,25 @@
+import type { KeyProvider, PublicKey, Signature } from "./types.js";
+declare const INSPECT: unique symbol;
+export declare class InMemoryKeyProvider implements KeyProvider {
+    #private;
+    constructor(seed: Uint8Array);
+    getPublicKey(): Promise<PublicKey>;
+    sign(data: Uint8Array): Promise<Signature>;
+    toJSON(): Record<string, string>;
+    toString(): string;
+    [INSPECT](): string;
+}
+export declare class FileKeyProvider implements KeyProvider {
+    #private;
+    private constructor();
+    static load(path: string): Promise<FileKeyProvider>;
+    getPublicKey(): Promise<PublicKey>;
+    sign(data: Uint8Array): Promise<Signature>;
+    toJSON(): Record<string, unknown>;
+    toString(): string;
+    [INSPECT](): string;
+}
+export declare function generateKeypair(): InMemoryKeyProvider;
+export declare function verify(publicKey: PublicKey, data: Uint8Array, signature: Signature): boolean;
+export {};
+//# sourceMappingURL=ed25519.d.ts.map

package/dist/ed25519.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ed25519.d.ts","sourceRoot":"","sources":["../src/ed25519.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEpE,QAAA,MAAM,OAAO,eAA2C,CAAC;AAOzD,qBAAa,mBAAoB,YAAW,WAAW;;gBAIzC,IAAI,EAAE,UAAU;IAMtB,YAAY,IAAI,OAAO,CAAC,SAAS,CAAC;IAIlC,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC;IAIhD,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAIhC,QAAQ,IAAI,MAAM;IAIlB,CAAC,OAAO,CAAC,IAAI,MAAM;CAGpB;AAED,qBAAa,eAAgB,YAAW,WAAW;;IAGjD,OAAO;WAIM,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAuDnD,YAAY,IAAI,OAAO,CAAC,SAAS,CAAC;IAIlC,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC;IAIhD,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAIjC,QAAQ,IAAI,MAAM;IAIlB,CAAC,OAAO,CAAC,IAAI,MAAM;CAGpB;AAED,wBAAgB,eAAe,IAAI,mBAAmB,CAErD;AAED,wBAAgB,MAAM,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAM5F"}

package/dist/ed25519.js

@@ -0,0 +1,120 @@
+import { ed25519 } from "@noble/curves/ed25519.js";
+import { randomBytes } from "@noble/hashes/utils.js";
+import { readFile, rename, mkdir, open as fsOpen } from "node:fs/promises";
+import { dirname, join } from "node:path";
+const INSPECT = Symbol.for("nodejs.util.inspect.custom");
+const KEY_FILE_MAGIC = new Uint8Array([0xce, 0x11, 0x0e, 0x01]); // "CELLO\x01"
+const KEY_FILE_VERSION = 1;
+const SEED_BYTES = 32;
+// Magic(4) + version(1) + seed(32) = 37 bytes
+const KEY_FILE_SIZE = KEY_FILE_MAGIC.length + 1 + SEED_BYTES;
+export class InMemoryKeyProvider {
+    #seed;
+    #publicKey;
+    constructor(seed) {
+        if (seed.length !== SEED_BYTES)
+            throw new Error("seed must be 32 bytes");
+        this.#seed = seed;
+        this.#publicKey = ed25519.getPublicKey(seed);
+    }
+    async getPublicKey() {
+        return this.#publicKey;
+    }
+    async sign(data) {
+        return ed25519.sign(data, this.#seed);
+    }
+    toJSON() {
+        return { type: "InMemoryKeyProvider", publicKey: Buffer.from(this.#publicKey).toString("hex") };
+    }
+    toString() {
+        return `InMemoryKeyProvider(pubkey=${Buffer.from(this.#publicKey).toString("hex")})`;
+    }
+    [INSPECT]() {
+        return this.toString();
+    }
+}
+export class FileKeyProvider {
+    #inner;
+    constructor(inner) {
+        this.#inner = inner;
+    }
+    static async load(path) {
+        // Attempt to read without existsSync to avoid TOCTOU: if the file disappears
+        // between a check and a read, readFile throws ENOENT — treated as "not found".
+        let raw = null;
+        try {
+            raw = await readFile(path);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "ENOENT") {
+                throw { reason: "key_file_corrupt", message: `cannot read key file: ${err.message}` };
+            }
+            // ENOENT → fall through to generation
+        }
+        if (raw !== null) {
+            if (raw.length !== KEY_FILE_SIZE) {
+                throw { reason: "key_file_corrupt", message: `key file has wrong length: expected ${KEY_FILE_SIZE}, got ${raw.length}` };
+            }
+            for (let i = 0; i < KEY_FILE_MAGIC.length; i++) {
+                if (raw[i] !== KEY_FILE_MAGIC[i]) {
+                    throw { reason: "key_file_corrupt", message: "key file has invalid magic bytes" };
+                }
+            }
+            if (raw[KEY_FILE_MAGIC.length] !== KEY_FILE_VERSION) {
+                throw { reason: "key_file_corrupt", message: `key file has unsupported version: ${raw[KEY_FILE_MAGIC.length]}` };
+            }
+            const seed = raw.slice(KEY_FILE_MAGIC.length + 1, KEY_FILE_MAGIC.length + 1 + SEED_BYTES);
+            return new FileKeyProvider(new InMemoryKeyProvider(seed));
+        }
+        // Generate and atomically write a new key file.
+        // Tmp file lives in the same directory as the target so rename() is same-filesystem.
+        const seed = randomBytes(SEED_BYTES);
+        const buf = Buffer.alloc(KEY_FILE_SIZE);
+        KEY_FILE_MAGIC.forEach((b, i) => { buf[i] = b; });
+        buf[KEY_FILE_MAGIC.length] = KEY_FILE_VERSION;
+        seed.forEach((b, i) => { buf[KEY_FILE_MAGIC.length + 1 + i] = b; });
+        const dir = dirname(path);
+        await mkdir(dir, { recursive: true });
+        const tmp = join(dir, `.cello-key-tmp-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+        // Write to tmp fd with O_CREAT|O_EXCL, fchmod before close, then rename — so the file
+        // arrives at its final path with 0o600 already set (no post-rename chmod race window).
+        const fd = await fsOpen(tmp, "wx", 0o600);
+        try {
+            await fd.write(buf);
+            await fd.chmod(0o600);
+        }
+        finally {
+            await fd.close();
+        }
+        await rename(tmp, path);
+        return new FileKeyProvider(new InMemoryKeyProvider(seed));
+    }
+    async getPublicKey() {
+        return this.#inner.getPublicKey();
+    }
+    async sign(data) {
+        return this.#inner.sign(data);
+    }
+    toJSON() {
+        return { type: "FileKeyProvider", publicKey: this.#inner.toJSON().publicKey };
+    }
+    toString() {
+        return `FileKeyProvider(pubkey=${this.#inner.toJSON().publicKey})`;
+    }
+    [INSPECT]() {
+        return this.toString();
+    }
+}
+export function generateKeypair() {
+    return new InMemoryKeyProvider(randomBytes(SEED_BYTES));
+}
+export function verify(publicKey, data, signature) {
+    try {
+        return ed25519.verify(signature, data, publicKey);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=ed25519.js.map

package/dist/ed25519.js.map

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

package/dist/frost/frost-threshold-signer.d.ts

@@ -0,0 +1,178 @@
+/**
+ * FrostThresholdSigner — FROST threshold signing over Ed25519 (RFC 9591)
+ *
+ * CELLO-CRYPTO-003
+ *
+ * Crypto reference: FROST / RFC 9591, Ed25519 / RFC 8032
+ * Implementation: @noble/curves/ed25519 — ed25519_FROST
+ *
+ * ─── Phase P: Pseudocode ─────────────────────────────────────────────────────
+ *
+ * bootstrapKeyShares(agentPubkey, config):
+ *   // TEST-ONLY shortcut — NOT real multi-round DKG (that's M3)
+ *   // Guard: only callable in NODE_ENV=test
+ *   assert NODE_ENV === 'test'
+ *   identifiers = [derive(stub.id) for stub in stubs]
+ *   dealerShares = trustedDealer({ min: threshold, max: participants }, identifiers)
+ *   // Distribute each stub its share (persists in stub.#key)
+ *   for each stub, share in dealerShares.secretShares:
+ *     stub.receiveShare(share, dealerShares.public)
+ *   // primary_pubkey = commitments[0] from the shared public package
+ *   primary_pubkey = dealerShares.public.commitments[0]
+ *   // Persist client's local key share (stored in module-level map keyed by agentPubkey)
+ *   storeLocalShare(agentPubkey, { share: agentShare, pub: dealerShares.public })
+ *   return { primaryPubkey: primary_pubkey }
+ *   // NOTE: signing share NEVER returned or logged
+ *
+ * FrostThresholdSigner.participateInCeremony(ceremonyId, tbs, context):
+ *   // Coordinator flow — RFC 9591 Section 5
+ *   frame(tbs, context) → msg = encode(context + '\0' + tbs)  // domain separation
+ *   localShare = loadLocalShare(agentPubkey)
+ *   if localShare is null: throw "not bootstrapped"
+ *   availableStubs = stubs (or directoryNodes via stream in production)
+ *
+ *   // Attempt loop — up to maxRetries
+ *   for attempt in 1..maxRetries (honoring ceremonyTimeout):
+ *     reachableStubs = stubs where not excluded
+ *     if |reachableStubs| < threshold: return DIRECTORY_BELOW_THRESHOLD
+ *     selectedStubs = reachableStubs[0..threshold-1]
+ *
+ *     // Round 1 — collect commitments (coordinator generates local nonce too)
+ *     localNonce = commit(localShare.secret)
+ *     commitments = [localNonce.commitments]
+ *     for each stub in selectedStubs:
+ *       c = stub.generateCommitment()
+ *       commitments.push(c.commitment)
+ *     commitmentList = sort(commitments, by identifier)
+ *
+ *     // Round 2 — collect partial signatures (with per-node timeout)
+ *     validShares = {}
+ *     excludedInThisRound = []
+ *     for each (stub, stubCommitment) in selectedStubs (with roundTimeout):
+ *       partialSig = await stub.signRound(pub, commitmentList, msg)  // timeout → null
+ *       if partialSig is null: excludedInThisRound.push(stub); continue
+ *       if !verifyShare(pub, commitmentList, msg, stub.id, partialSig):
+ *         excludedInThisRound.push(stub); continue  // invalid partial — same as timeout
+ *       validShares[stub.id] = partialSig
+ *
+ *     // Also compute coordinator's own partial sig
+ *     coordinatorPartialSig = signShare(localShare.secret, pub, localNonce.nonces, commitmentList, msg)
+ *     validShares[coordinatorId] = coordinatorPartialSig
+ *
+ *     if |validShares| >= threshold:
+ *       signature = aggregate(pub, commitmentList, msg, validShares)
+ *       return { ok: true, signature }
+ *     else:
+ *       // Not enough valid shares — retry with different participants
+ *       continue
+ *
+ *   return { ok: false, error: { reason: 'CEREMONY_EXHAUSTED' } }
+ *
+ * primary_pubkey derivation:
+ *   // In trustedDealer mode: commitments[0] is the group public key
+ *   // This is the constant term of the dealer's Shamir polynomial commitment
+ *   // It is deterministic given the dealer's secret polynomial
+ *   // All participants' public shares verify against the same commitments[0]
+ *   primary_pubkey = dealerShares.public.commitments[0]
+ *
+ * Round timeout / node replacement:
+ *   // Each stub.signRound wraps in Promise.race([real, timeoutPromise])
+ *   // If timeout wins → stub treated as excluded (same path as invalid sig)
+ *   // On retry, excluded stubs are filtered from available pool
+ *   // If available < threshold → DIRECTORY_BELOW_THRESHOLD (not retried)
+ *
+ * ─── End Pseudocode ──────────────────────────────────────────────────────────
+ */
+import type { FrostPublic, FrostSecret } from "@noble/curves/abstract/frost.js";
+import type { IThresholdSigner, ThresholdSignature, FrostThresholdSignerConfig, BootstrapResult, FrostContext } from "./types.js";
+import { CONTEXT_SESSION_ESTABLISHMENT, CONTEXT_SEAL } from "./types.js";
+/**
+ * Clear all local key shares stored in the module-level map.
+ *
+ * TEST-ONLY: guards against accumulation of key material across test cases.
+ * Call in afterEach/afterAll to evict shares seeded by bootstrapKeyShares.
+ *
+ * Throws if called outside NODE_ENV=test so it can never be misused in
+ * production (where it would collapse multi-party FROST to zero-share state).
+ */
+export declare function clearTestShares(): void;
+/**
+ * Store the client's local DKG key share after a real DKG ceremony completes.
+ *
+ * Production path: called after runNetworkDkg completes successfully.
+ * No NODE_ENV guard — this is the production key storage path (unlike bootstrapKeyShares).
+ *
+ * SECURITY: validates the secret against the public before storing.
+ * The FrostSecret is stored in the module-level map keyed by agentPubkeyHex.
+ */
+export declare function storeDkgResult(agentPubkeyHex: string, secret: FrostSecret, pub: FrostPublic): void;
+/**
+ * Test-harness shortcut for key share bootstrap.
+ *
+ * GUARD: Only callable in NODE_ENV=test. This is NOT a real multi-round DKG
+ * (that comes in M3). It uses trustedDealer to pre-populate shares for testing.
+ *
+ * Behavior:
+ * 1. Generate FROST shares via trustedDealer for all n stub nodes
+ * 2. Distribute each stub its signing share
+ * 3. One of the identifiers is the "client" (coordinator) — its share is stored locally
+ * 4. primary_pubkey = commitments[0] from the shared public package
+ * 5. Return { primaryPubkey } — no key material beyond the group public key
+ */
+export declare function bootstrapKeyShares(agentPubkey: Uint8Array, config: FrostThresholdSignerConfig): Promise<BootstrapResult>;
+export declare class FrostThresholdSigner implements IThresholdSigner {
+    #private;
+    constructor(config: FrostThresholdSignerConfig, agentPubkey: Uint8Array);
+    /**
+     * Get the group public key (primary_pubkey) for this signer.
+     * Returns the key from the stored local share (populated by bootstrapKeyShares).
+     */
+    getPrimaryPubkey(): Uint8Array;
+    /**
+     * Verify a threshold signature against a public key and TBS with context.
+     * Used by callers (and tests) to verify signatures produced by participateInCeremony.
+     */
+    verifySignature(signature: Uint8Array, tbs: Uint8Array, context: string, publicKey: Uint8Array): boolean;
+    /**
+     * Participate in a FROST threshold signing ceremony as coordinator.
+     *
+     * RFC 9591 Section 5 coordinator flow with in-process stubs.
+     * Full round coordination, timeout handling, and participant exclusion.
+     */
+    participateInCeremony(ceremonyId: string, tbs: Uint8Array, context: FrostContext, onProgress?: import("./types.js").CeremonyProgressCallback): Promise<ThresholdSignature>;
+}
+/**
+ * Verify a FROST threshold signature without a signer instance.
+ *
+ * Used by the client when it is the counterparty (participant B) and has no
+ * IThresholdSigner injected. Verifies the domain-separated FROST signature
+ * against the provided public key.
+ *
+ * @param signature - 64-byte threshold signature from the SessionAssignment
+ * @param tbs - to-be-signed bytes (from buildSessionEstablishmentTbs)
+ * @param context - domain context string (e.g. CONTEXT_SESSION_ESTABLISHMENT)
+ * @param publicKey - 32-byte Ed25519 group public key to verify against
+ * @returns true if signature verifies; false otherwise (never throws)
+ */
+export declare function verifyFrostSignature(signature: Uint8Array, tbs: Uint8Array, context: string, publicKey: Uint8Array): boolean;
+/**
+ * MockThresholdSigner: confirms the IThresholdSigner swap point is real.
+ *
+ * Implements IThresholdSigner without any FROST crypto. Used by AC-010 to
+ * verify that callers work correctly against the interface without knowing
+ * the concrete implementation.
+ *
+ * Returns a deterministic 64-byte signature (not cryptographically valid,
+ * but structurally correct for interface tests).
+ */
+export declare class MockThresholdSigner implements IThresholdSigner {
+    participateInCeremony(_ceremonyId: string, tbs: Uint8Array, _context: FrostContext, _onProgress?: import("./types.js").CeremonyProgressCallback): Promise<ThresholdSignature>;
+    /**
+     * Return a deterministic 32-byte mock primary pubkey.
+     * Not a real Ed25519 point — only for interface shape testing.
+     */
+    getPrimaryPubkey(): Uint8Array;
+    verifySignature(_signature: Uint8Array, _tbs: Uint8Array, _context: FrostContext, _publicKey: Uint8Array): boolean;
+}
+export { CONTEXT_SESSION_ESTABLISHMENT, CONTEXT_SEAL };
+//# sourceMappingURL=frost-threshold-signer.d.ts.map

package/dist/frost/frost-threshold-signer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frost-threshold-signer.d.ts","sourceRoot":"","sources":["../../src/frost/frost-threshold-signer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AAGH,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACZ,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EACV,gBAAgB,EAChB,kBAAkB,EAClB,0BAA0B,EAE1B,eAAe,EACf,YAAY,EACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,6BAA6B,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAgBzE;;;;;;;;GAQG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAKtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,WAAW,EACnB,GAAG,EAAE,WAAW,GACf,IAAI,CAGN;AA+BD;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,UAAU,EACvB,MAAM,EAAE,0BAA0B,GACjC,OAAO,CAAC,eAAe,CAAC,CAwD1B;AAID,qBAAa,oBAAqB,YAAW,gBAAgB;;gBAa/C,MAAM,EAAE,0BAA0B,EAAE,WAAW,EAAE,UAAU;IAgBvE;;;OAGG;IACH,gBAAgB,IAAI,UAAU;IAU9B;;;OAGG;IACH,eAAe,CACb,SAAS,EAAE,UAAU,EACrB,GAAG,EAAE,UAAU,EACf,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,UAAU,GACpB,OAAO;IASV;;;;;OAKG;IACG,qBAAqB,CACzB,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,UAAU,EACf,OAAO,EAAE,YAAY,EACrB,UAAU,CAAC,EAAE,OAAO,YAAY,EAAE,wBAAwB,GACzD,OAAO,CAAC,kBAAkB,CAAC;CA2M/B;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,UAAU,EACrB,GAAG,EAAE,UAAU,EACf,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,UAAU,GACpB,OAAO,CAOT;AAID;;;;;;;;;GASG;AACH,qBAAa,mBAAoB,YAAW,gBAAgB;IACpD,qBAAqB,CACzB,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,UAAU,EACf,QAAQ,EAAE,YAAY,EACtB,WAAW,CAAC,EAAE,OAAO,YAAY,EAAE,wBAAwB,GAC1D,OAAO,CAAC,kBAAkB,CAAC;IAW9B;;;OAGG;IACH,gBAAgB,IAAI,UAAU;IAO9B,eAAe,CACb,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,YAAY,EACtB,UAAU,EAAE,UAAU,GACrB,OAAO;CAIX;AAGD,OAAO,EAAE,6BAA6B,EAAE,YAAY,EAAE,CAAC"}