@cello-protocol/daemon 0.0.227 → 0.0.229

package/dist/network-directory-node.d.ts

@@ -0,0 +1,136 @@
+/**
+ * NetworkDirectoryNode — DirectoryNodeStub backed by a real libp2p connection.
+ *
+ * Implements the DirectoryNodeStub interface by dialing the directory node's
+ * /cello/frost/1.0.0 endpoint. Used in live e2e mode instead of InProcessDirectoryNodeStub.
+ *
+ * Wire protocol (one stream per operation, CBOR + it-length-prefixed):
+ *   frost_bootstrap:      push share material to directory (called from bootstrapKeyShares)
+ *   frost_commit_request: ask directory to generate a nonce commitment
+ *   frost_sign_request:   ask directory to compute a partial signature
+ */
+import { FrostThresholdSigner } from "@cello-protocol/crypto";
+import type { CelloNode } from "@cello-protocol/transport";
+import type { Logger } from "./types.js";
+import type { DirectoryNodeStub, StubCommitment, StubSignParams } from "@cello-protocol/crypto/frost/types.js";
+export type FrostAuthSigner = (hash: Uint8Array) => Promise<Uint8Array>;
+/**
+ * The evidence a seal ceremony forwards to every share-holding directory, plus where their answers
+ * go when they say no.
+ *
+ * `onRefused` — review F6. A holder refusing is the strongest signal this system produces, and its
+ * only trace was a log line on a machine the operator does not own plus a `warn` here. The ceremony
+ * dies with "threshold not met", which is a COUNT and says nothing about why any holder declined, so
+ * the reason has to be carried back to whoever records the failure.
+ */
+export interface SealCeremonyEvidence {
+    leaves: unknown[];
+    closeTimestamp: number;
+    onRefused?: (nodeReason: string) => void;
+}
+export declare class NetworkDirectoryNode implements DirectoryNodeStub {
+    #private;
+    readonly id: string;
+    /** Attach the seal evidence for the ceremony about to run. Cleared by passing `null`. */
+    setSealEvidence(evidence: SealCeremonyEvidence | null): void;
+    constructor(opts: {
+        id: string;
+        node: CelloNode;
+        directoryPeerId: string;
+        directoryMultiaddrs: string[];
+        logger?: Logger;
+    });
+    isReachable(): boolean;
+    /** Return the FrostPublic from the last receiveShare call. Used by tests to construct signRound params. */
+    getLastPub(): Parameters<DirectoryNodeStub["receiveShare"]>[1] | null;
+    receiveShare(...[secret, pub]: Parameters<DirectoryNodeStub["receiveShare"]>): Promise<void>;
+    generateCommitment(): Promise<StubCommitment>;
+    signRound(params: StubSignParams): Promise<Uint8Array | null>;
+    setBootstrapContext(agentPubkeyHex: string, epochId: string, signAuth?: FrostAuthSigner): void;
+    /** Open a /cello/frost/1.0.0 stream to this directory node. Used by DKG coordinator. */
+    openStream(): Promise<import("@libp2p/interface").Stream>;
+}
+/**
+ * Run a real 3-round FROST DKG ceremony with directory nodes over /cello/frost/1.0.0.
+ *
+ * Production path for key establishment. The client acts as DKG coordinator:
+ *   Round 1: All nodes generate their secret polynomials. Client does the same.
+ *   Round 2: Client collects all round1 broadcasts and distributes them to all nodes.
+ *            All nodes compute shares for every other participant.
+ *   Round 3: Client routes round2 shares to recipients and all nodes finalize.
+ *            All nodes return shareCommitment = group public key.
+ *
+ * Validates that all nodes derive the same primary_pubkey before returning.
+ *
+ * After a successful DKG:
+ *   - Each directory node has its FrostSecret stored (via dkgRound3)
+ *   - The client's local share is stored via storeDkgResult
+ *   - Returns a FrostThresholdSigner for future signing ceremonies
+ *
+ * Crypto reference: RFC 9591 (FROST DKG)
+ *
+ * @param agentPubkey - client's Ed25519 K_local public key (32 bytes)
+ * @param opts.threshold - minimum signers required (t in t-of-n)
+ * @param opts.directoryNodes - the n directory nodes (each will hold a share)
+ */
+/**
+ * Refuse a DKG whose participants do not hold DISTINCT FROST identifiers.
+ *
+ * A node's identifier is derived from its OWN deployed `NODE_ID`, not from the manifest entry naming
+ * it — so two entries with distinct nodeIds, deployed on boxes that share one `NODE_ID`, collide here
+ * and pass every string comparison in the consortium. Two participants sharing an identifier are ONE
+ * participant, so the quorum is smaller than it looks.
+ *
+ * `DKG.round2` does reject this (`@noble/curves` throws `Duplicate id=…`), so the value here is
+ * DIAGNOSIS, not detection: that throw arrives from inside a crypto library and has to survive every
+ * catch between there and the operator — one of which was discarding it entirely until recently.
+ * Refusing here names the cause while the participant list is still in hand.
+ *
+ * Exported for test: the call site can only be reached through a live multi-node DKG, so the logic is
+ * proven here and its PLACEMENT (before round 2, and before the share-routing map that would silently
+ * merge two colliding participants' shares) is a review property.
+ *
+ * @param identifiers round-1 identifiers, in participant order
+ * @param describe    names participant `i` for the message — index 0 is the client
+ */
+export declare function assertDistinctFrostIdentifiers(identifiers: readonly string[], describe: (index: number) => string): void;
+export declare function runNetworkDkg(agentPubkey: Uint8Array, opts: {
+    threshold: number;
+    participants: number;
+    directoryNodes: NetworkDirectoryNode[];
+    /** Pre-authorization token to present in the Round 1 frame. */
+    preAuthToken?: string;
+    /** K_local signer for the DKG-time commit/sign requests' auth. */
+    signAuth?: FrostAuthSigner;
+}): Promise<{
+    signer: FrostThresholdSigner;
+    primaryPubkey: Uint8Array;
+    /** Serializable FROST share data for DB persistence. NEVER log signingShare. */
+    signingShare: Uint8Array;
+    identifier: string;
+    commitments: Uint8Array[];
+    verifyingShares: Record<string, Uint8Array>;
+    threshold: number;
+    participants: number;
+}>;
+/**
+ * Run a proactive share refresh across the consortium. Rotates the client's + every directory node's share
+ * from epoch `fromEpochN` to `fromEpochN + 1`, leaving the group public key byte-identical. Verifies every
+ * party reports the same (unchanged) group key before returning the client's serializable new-epoch share.
+ */
+export declare function runNetworkRefresh(agentPubkey: Uint8Array, opts: {
+    threshold: number;
+    participants: number;
+    directoryNodes: NetworkDirectoryNode[];
+    fromEpochN: number;
+    /** K_local signer for any commit/sign auth during the refresh. */
+    signAuth?: FrostAuthSigner;
+}): Promise<{
+    toEpochN: number;
+    primaryPubkey: Uint8Array;
+    signingShare: Uint8Array;
+    identifier: string;
+    commitments: Uint8Array[];
+    verifyingShares: Record<string, Uint8Array>;
+}>;
+//# sourceMappingURL=network-directory-node.d.ts.map

package/dist/network-directory-node.d.ts.map

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