@cello-protocol/client 0.0.2

package/dist/client.d.ts

@@ -0,0 +1,249 @@
+/**
+ * CELLO Client — client.ts (MSG-002, SESSION-002)
+ *
+ * CelloClientImpl: peer registry, send path, inbound stream handler,
+ * and receive queue for the M0 one-shot message exchange protocol.
+ * SESSION-002 additions: receiveSessionAssignment, listSessions.
+ *
+ * PSEUDOCODE (Phase P):
+ *
+ * send(peerPubkeyHex, content):
+ *   1. Look up peerPubkeyHex → peer_not_connected if absent
+ *   2. buildEnvelope(content, keyProvider, Date.now()) → content_too_large if rejected
+ *   3. serializeEnvelope → bytes
+ *   4. node.newStream(peerId, CELLO_PROTOCOL_ID):
+ *      - structured error → peer_unreachable or connection_lost
+ *   5. stream.send(lp.encode.single(bytes))
+ *   6. stream.close() — half-close write side
+ *   7. Drain read side (for await lp.decode(stream)):
+ *      - clean EOF → delivered:true
+ *      - stream.status === 'reset' → remote_rejected
+ *      - transport error → connection_lost
+ *
+ * inbound handler (stream):
+ *   1. AbortController with 5s timeout
+ *   2. Read one LP frame via lp.decode(stream) — abort if timeout fires
+ *   3. deserializeEnvelope(payload) → malformed_envelope + stream.abort on error
+ *   4. validateEnvelope(envelope) → stream.abort on error
+ *   5. enqueue to receiveQueue keyed by sender_pubkey hex
+ *   6. stream.close() — clean close signals delivered:true to sender
+ *
+ * sendRaw(peerPubkeyHex, bytes) [internal, exposed for tests]:
+ *   Open stream, write raw bytes as single LP frame, await close type.
+ *   Used by tests to inject tampered envelopes.
+ *
+ * receiveSessionAssignment(assignment, myPubkey):
+ *   SESSION-002 AC-002, AC-003, AC-004, AC-005, SI-003
+ *   SESSION-004 changes: replace M1 Ed25519 verify with FROST verify path.
+ *
+ *   SESSION-004 pseudocode (Phase P rev2):
+ *   RFC 9591 (FROST), RFC 8032 (Ed25519), FIPS 180-4 (SHA-256)
+ *
+ *   1. Check signature_type (SESSION-004 SI-003, AC-003):
+ *      if assignment.signature_type === 'single':
+ *        return { ok:false, reason:"unsupported_signature_type" }
+ *        // Hard cut — even if the single-key sig itself verifies (SI-003 is absolute)
+ *        // No session record is created (SI-003). No I/O is attempted.
+ *
+ *   2. Determine role and verification key (SESSION-004 AC-007):
+ *      isInitiator = (Buffer.from(myPubkey).equals(Buffer.from(pubA)))
+ *      if isInitiator:
+ *        // CRITICAL-1 FIX: initiator MUST have a thresholdSigner injected.
+ *        // There is NO fallback to assignment.signer_pubkey — that is frame-provided
+ *        // and attacker-controlled. Absence of a signer is a hard error.
+ *        if this.#thresholdSigner is null:
+ *          return { ok:false, reason:"frost_signer_not_configured" }
+ *        verifyKey = this.#thresholdSigner.getPrimaryPubkey()  // HIGH-4: on IThresholdSigner
+ *      else:
+ *        // Counterparty: use signer_pubkey embedded in the frame (A's primary_pubkey)
+ *        // TypeScript discriminated union guarantees signer_pubkey is present for 'frost' frames
+ *        verifyKey = assignment.signer_pubkey  // guaranteed non-undefined by type system
+ *
+ *   3. Compute genesis_prev_root (same as M1):
+ *      genesis_prev_root = computeGenesisPrevRoot(pubA, pubB, session_id, session_timestamp)
+ *
+ *   4. Build session establishment TBS (HIGH-5: uses buildSessionEstablishmentTbs from protocol-types):
+ *      tbs = buildSessionEstablishmentTbs(session_id, pubA, pubB, genesis_prev_root, session_timestamp)
+ *
+ *   5. Verify FROST signature (SESSION-004 AC-002, SI-001):
+ *      //  Use FrostThresholdSigner.verifySignature() which handles framing internally:
+ *      //    framedMsg = <context>\0<tbs>  (domain separation per CONTEXT.md)
+ *      //  OR use ed25519_FROST.verify(sig, frameMessage(context, tbs), verifyKey) directly
+ *      //  The client imports ed25519_FROST from @noble/curves/ed25519 (not from @cello-protocol/crypto)
+ *      //  to keep the verify path independent from any signer state.
+ *      framedMsg = frameMessage(CONTEXT_SESSION_ESTABLISHMENT, tbs)  // context\0tbs
+ *      isValid = ed25519_FROST.verify(assignment.directory_signature, framedMsg, verifyKey)
+ *      if !isValid:
+ *        return { ok:false, reason:"frost_signature_invalid" }
+ *        // Never accept a tampered signature (SI-001 absolute)
+ *
+ *   6-9. (same as M1: content handler, relay auth, counterparty dial, store session)
+ *
+ * IMPORTANT NOTE on CelloClientImpl constructor and createClient factory changes:
+ *   - Add optional #thresholdSigner: IThresholdSigner | null field
+ *   - createClient accepts optional thresholdSigner in opts
+ *   - No @cello-protocol/directory import — IThresholdSigner comes from @cello-protocol/crypto
+ *
+ * IMPORTANT NOTE on ReceiveAssignmentResult (IMPORTANT-9):
+ *   Add 'frost_signature_invalid' | 'unsupported_signature_type' | 'frost_signer_not_configured'
+ *   to the reason union in types.ts
+ *
+ *   1. Build TBS = CBOR([session_id, participant_a.pubkey, participant_b.pubkey, session_timestamp])
+ *   2. Verify Ed25519(TBS, assignment.directory_pubkey, assignment.directory_signature) [M1, REMOVED in M2]
+ *      → { ok:false, reason:"directory_signature_invalid" } if fails
+ *   3. Determine counterparty: if myPubkey == participant_a.pubkey then counterparty = B, else A
+ *   4. Compute genesis_prev_root = computeGenesisPrevRoot(pubA, pubB, session_id, session_timestamp)
+ *      per FIPS 180-4 / SESSION-002
+ *   5. Register /cello/content/1.0.0 handler on node (if not yet registered)
+ *   6. Dial relay on /cello/relay/1.0.0, complete challenge-response auth:
+ *      a. Read relay_auth_challenge frame
+ *      b. Compute authMsg = SHA-256("CELLO-RELAY-AUTH-v1" || nonce || myPubkey)  [RFC 8032, FIPS 180-4]
+ *      c. Sign authMsg with keyProvider → signature
+ *      d. Send relay_auth_response{pubkey, signature}
+ *      → { ok:false, reason:"relay_auth_failed" } or "relay_auth_error" on failure
+ *   7. Dial counterparty on /cello/content/1.0.0
+ *      → { ok:false, reason:"dial_counterparty_failed" } if unreachable
+ *   8. Store SessionRecord with status:"active", last_seen_seq:0
+ *   9. Return { ok:true, sessionId }
+ */
+import type { IThresholdSigner } from "@cello-protocol/crypto";
+import type { KeyProvider } from "@cello-protocol/crypto";
+import type { CelloNode } from "@cello-protocol/transport";
+import type { Stream } from "@libp2p/interface";
+import type { CelloClient, SendResult, SessionRecord } from "./types.js";
+import type { Logger } from "@cello-protocol/interfaces";
+export declare function createClient(node: CelloNode, keyProvider: KeyProvider, opts?: {
+    onMessageQueued?: (senderPubkeyHex: string) => void;
+    contentGraceMs?: number;
+    /** SESSION-006: ms to attempt relay reconnect before giving up. Default: 60000. */
+    reconnectTimeoutMs?: number;
+    /** SESSION-004/SESSION-005: optional FROST threshold signer for initiator role and seal ceremony coordination. */
+    thresholdSigner?: IThresholdSigner;
+    /** SESSION-005: ms to wait for FROST seal after bilateral exchange. Default: 15000. */
+    sealFrostTimeoutMs?: number;
+    /** ADAPTER-003: directory endpoint for initiateSession. */
+    directoryEndpoint?: {
+        peer_id: string;
+        multiaddrs: string[];
+    };
+    /** REG-001: path for persisting ML-DSA-44 keypair. If set, FileMlDsaKeyProvider.load() is used. */
+    mlDsaKeyFile?: string;
+    /** CONNREQ-002: connection policy for evaluating inbound connection_request_inbound frames. */
+    connectionPolicy?: import("./connection-policy.js").SignalRequirementPolicy;
+    /** CONNREQ-002: overall connection timeout in ms. Default: 300000. */
+    connectionTimeoutMs?: number;
+    /** CONNREQ-002: Round 2 silence timeout in ms. Default: 120000. */
+    round2TimeoutMs?: number;
+    /** CONNREQ-002: if true, expose _evaluateCallCount on the instance for test assertions. */
+    trackEvaluateCount?: boolean;
+    /** CONNREQ-002: sender pubkeys that bypass evaluateConnectionPackage. */
+    whitelist?: string[];
+    /** CONNREQ-002: callback fired when an inbound connection_request_inbound is queued for agent review. */
+    onConnectionPendingReview?: (event: import("@cello-protocol/protocol-types").ConnectionRequestInbound) => void;
+    /** DB-003: attempt cross-check of sender's ml_dsa_pubkey on inbound requests. */
+    crossCheckDirectoryOnInbound?: boolean;
+    /** PERSIST-014: injected logger for observability events. */
+    logger?: Logger;
+}): CelloClient & {
+    sendRaw(peerPubkeyHex: string, bytes: Uint8Array): Promise<SendResult>;
+    openRawStream(peerPubkeyHex: string): Promise<Stream>;
+    openContentStreamByPeerId(peerId: string): Promise<Stream>;
+    /** SESSION-005: register the client's FROST primary_pubkey for seal verification. */
+    setPrimaryPubkey(primaryPubkey: Uint8Array): void;
+    injectDirectoryFrame(sessionIdHex: string, frame: Record<string, unknown>): void;
+    injectLeafDeliver(sessionIdHex: string, frame: Record<string, unknown>): void;
+    injectRelayDisconnect(sessionIdHex: string): void;
+    /** TEST-ONLY: register a minimal session record without a real relay connection. */
+    injectTestSession(sessionIdHex: string, sessionId: Uint8Array, myPubkeyHex: string, directoryPubkey: Uint8Array, status?: SessionRecord["status"], opts?: {
+        isInitiator?: boolean;
+    }): void;
+    /** CONNREQ-002: list active connection records. */
+    listConnections(): import("@cello-protocol/protocol-types").ClientConnectionRecord[];
+    /** CONNREQ-002: send connection_request to target B and await final outcome. */
+    cello_request_connection(opts: {
+        target_pubkey: string;
+        package_cbor: Uint8Array;
+    }): Promise<{
+        result: "established";
+        connection_id: string;
+    } | {
+        result: "rejected";
+        reason: string;
+    } | {
+        result: "insufficient";
+        unmet_requirements: unknown[];
+    } | {
+        result: "disclosure_requested";
+        connection_request_id: string;
+        requested_items: unknown[];
+    } | {
+        result: "timeout";
+    } | {
+        result: "error";
+        reason: string;
+    }>;
+    /** CONNREQ-002: respond to disclosure_request (Round 2 sender side). */
+    cello_respond_to_disclosure_request(opts: {
+        connection_request_id: string;
+        package_cbor: Uint8Array;
+    }): Promise<{
+        result: "established";
+        connection_id: string;
+    } | {
+        result: "rejected";
+        reason: string;
+    } | {
+        result: "insufficient";
+        unmet_requirements: unknown[];
+    } | {
+        result: "timeout";
+    } | {
+        result: "error";
+        reason: string;
+    }>;
+    /** CONNREQ-002: request more disclosure from sender (Round 2, target side). */
+    cello_request_more_disclosure(opts: {
+        connection_request_id: string;
+        requested_items: unknown[];
+    }): Promise<{
+        error: "max_rounds_reached";
+    } | {
+        ok: true;
+    }>;
+    /** CONNREQ-002: register connection_established event handler. */
+    onConnectionEstablished(handler: (event: import("@cello-protocol/protocol-types").ConnectionEstablished) => void): void;
+    /** CONNREQ-002: register disclosure_request_inbound event handler (sender side). */
+    onDisclosureRequested(handler: (event: import("@cello-protocol/protocol-types").DisclosureRequestInbound) => void): void;
+    /** CONNREQ-002: reconnect the persistent directory signaling stream. */
+    reconnectDirectory(): Promise<boolean>;
+    /** PERSIST-015: send seal_unilateral to directory after delivery_grace_seconds. */
+    initiateUnilateralSeal(sessionIdHex: string): Promise<{
+        ok: true;
+        sealed_root: Uint8Array;
+        sealed_at: number;
+    } | {
+        ok: false;
+        reason: "too_early";
+        remaining_seconds: number;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    /** TEST-ONLY: inject a pending inbound connection request into state. */
+    _injectPendingConnectionRequest(opts: {
+        connection_request_id: string;
+        from_pubkey: string;
+        package_cbor: Uint8Array;
+        round: number;
+    }): void;
+    /**
+     * CONNREQ-003 TEST-ONLY: route a synthetic connection outcome frame through the
+     * resolver Map — used by SI-001 adversarial test to verify cross-target isolation.
+     */
+    _injectConnectionFrame(frame: Record<string, unknown>): void;
+    /** CONNREQ-003 TEST-ONLY: current size of the pending resolver Map. */
+    _pendingConnectionRequestResolverCount: number;
+    /** TEST-ONLY: evaluate call counter (only incremented when trackEvaluateCount=true). */
+    _evaluateCallCount: number;
+};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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