@taceo/oprf-client 0.8.0

package/dist/index.d.cts

@@ -0,0 +1,207 @@
+import { PartialDLogEqualityCommitments, PartialDLogCommitmentsShamir, DLogCommitmentsShamir, DLogProofShareShamir, DLogEqualityProof } from '@taceo/oprf-core';
+import { AffinePoint } from '@noble/curves/abstract/curve.js';
+
+/**
+ * Wire and API types for OPRF client.
+ * Matches nullifier-oracle-service oprf-types (OprfRequest, OprfResponse, etc.).
+ */
+
+/**
+ * Affine point as JSON: a 2-element array [x, y] of decimal strings.
+ * Matches Rust ark_serde_compat::babyjubjub::serialize_affine / deserialize_affine.
+ */
+type AffinePointWire = [string, string];
+/** DLogCommitmentsShamir wire (server expects snake_case: contributing_parties). */
+interface DLogCommitmentsShamirWire {
+    c: AffinePointWire;
+    d1: AffinePointWire;
+    d2: AffinePointWire;
+    e1: AffinePointWire;
+    e2: AffinePointWire;
+    contributing_parties: number[];
+}
+/** OprfPublicKeyWithEpoch (internal: affine points). */
+interface OprfPublicKeyWithEpoch {
+    key: AffinePoint<bigint>;
+    epoch: number;
+}
+/** OprfRequest (internal: affine for blinded_query). */
+interface OprfRequest<Auth = unknown> {
+    request_id: string;
+    blinded_query: AffinePoint<bigint>;
+    auth: Auth;
+}
+/** OprfResponse (internal: affine points). */
+interface OprfResponse {
+    commitments: PartialDLogEqualityCommitments;
+    party_id: number;
+    oprf_pub_key_with_epoch: OprfPublicKeyWithEpoch;
+}
+
+/**
+ * WebSocket session for a single OPRF service connection.
+ * Takes a pre-built WS URL (see uri.ts). Errors are NodeError variants.
+ */
+
+/**
+ * Thin WebSocket session: connect, send JSON, receive JSON, handle close.
+ * Uses text (JSON) frames. Browser WebSocket cannot set headers; version is sent as query param.
+ * All errors are thrown as NodeError.
+ */
+declare class WebSocketSession {
+    private ws;
+    private readonly service;
+    private constructor();
+    get serviceUrl(): string;
+    /**
+     * Open a new WebSocket to the given pre-built WS URL.
+     * Connect errors throw NodeError('WsError', ...).
+     */
+    static connect(url: string): Promise<WebSocketSession>;
+    /** Send a JSON-serializable message as text frame. Throws NodeError('WsError') on failure. */
+    send<T extends object>(msg: T): void;
+    /**
+     * Read next message. Returns text data.
+     * Rejects with NodeError on:
+     *  - Binary frame → UnexpectedMessage
+     *  - Non-normal close → ServiceError
+     *  - Normal/1005 close → UnexpectedMessage('Server closed websocket')
+     *  - Error event → WsError
+     *  - null/end → UnexpectedMessage('Server closed connection')
+     */
+    private readNext;
+    /** Read and parse OprfResponse. Parse errors → NodeError('UnexpectedMessage'). */
+    readOprfResponse(): Promise<OprfResponse>;
+    /** Read and parse DLogProofShareShamir. Parse errors → NodeError('UnexpectedMessage'). */
+    readProofShare(): Promise<{
+        value: bigint;
+    }>;
+    /** Send challenge (DLogCommitmentsShamir wire). */
+    sendChallenge(wire: DLogCommitmentsShamirWire): void;
+    /** Gracefully close with normal code. */
+    close(): void;
+}
+
+/**
+ * Session management: initSessions (parallel connect, collect by epoch to threshold),
+ * finishSessions (send challenge, collect proof shares). Mirrors Rust oprf-client sessions.
+ */
+
+interface OprfSessions {
+    readonly ws: WebSocketSession[];
+    readonly partyIds: number[];
+    readonly commitments: PartialDLogCommitmentsShamir[];
+    readonly oprfPublicKeys: AffinePointLike[];
+    readonly epoch: number;
+}
+/** Internal: we only need key as affine for verification. */
+interface AffinePointLike {
+    x: bigint;
+    y: bigint;
+}
+/**
+ * Open WebSockets to each service in parallel, send oprfRequest, collect OprfResponse.
+ * Services must be pre-built WS URLs (see toOprfUri / toOprfUriMany).
+ * Group by epoch; when an epoch has >= threshold responses with distinct party_id, return those sessions (sorted by party_id).
+ * On failure: throws NodeError[] (caller wraps via aggregateError).
+ */
+declare function initSessions<Auth>(services: string[], threshold: number, oprfRequest: OprfRequest<Auth>): Promise<OprfSessions>;
+/**
+ * Send the same challenge to each session, read proof share, then close.
+ * Returns proof shares in the same order as sessions.ws.
+ * Errors bubble up as NodeError (thrown from ws methods).
+ */
+declare function finishSessions(sessions: OprfSessions, challenge: DLogCommitmentsShamir): Promise<DLogProofShareShamir[]>;
+
+/**
+ * High-level client: generateChallengeRequest, verifyDlogEquality, distributedOprf.
+ */
+
+interface VerifiableOprfOutput {
+    output: bigint;
+    dlogProof: DLogEqualityProof;
+    blindedRequest: AffinePoint<bigint>;
+    blindedResponse: AffinePoint<bigint>;
+    unblindedResponse: AffinePoint<bigint>;
+    oprfPublicKey: AffinePoint<bigint>;
+    epoch: number;
+}
+/**
+ * Build challenge from sessions: contributingParties = party_id + 1 per party, then combineCommitments.
+ */
+declare function generateChallengeRequest(sessions: OprfSessions): DLogCommitmentsShamir;
+/**
+ * Combine proof shares, verify DLog proof. Throws OprfClientError if invalid.
+ */
+declare function verifyDlogEquality(requestId: string, oprfPublicKey: AffinePoint<bigint>, blindedRequest: AffinePoint<bigint>, proofShares: DLogProofShareShamir[], challenge: DLogCommitmentsShamir): DLogEqualityProof;
+interface DistributedOprfOptions<Auth = unknown> {
+    /** Auth payload sent in OprfRequest (must be JSON-serializable). */
+    auth?: Auth;
+}
+/**
+ * Full distributed OPRF: blind → init sessions → challenge → finish → verify → unblind → finalize.
+ * Services must be pre-built WS URLs (use toOprfUri / toOprfUriMany).
+ */
+declare function distributedOprf(services: string[], threshold: number, query: bigint, domainSeparator: bigint, options?: DistributedOprfOptions): Promise<VerifiableOprfOutput>;
+
+/**
+ * Client error types matching the Rust oprf-client Error enum.
+ * Two-tier model: NodeError (per-node) and OprfClientError (protocol-level).
+ */
+/**
+ * Application-level error received in a WebSocket close frame from a node.
+ */
+declare class ServiceError extends Error {
+    readonly errorCode: number;
+    readonly msg?: string;
+    constructor(errorCode: number, msg?: string);
+}
+type NodeErrorCode = 'ServiceError' | 'WsError' | 'UnexpectedMessage' | 'Unknown';
+/**
+ * Per-node error, discriminated by `code`.
+ */
+declare class NodeError extends Error {
+    readonly code: NodeErrorCode;
+    readonly reason?: string;
+    readonly cause?: Error;
+    readonly serviceError?: ServiceError;
+    constructor(code: NodeErrorCode, opts?: {
+        reason?: string;
+        cause?: Error;
+        serviceError?: ServiceError;
+    });
+}
+declare function isNodeError(err: unknown): err is NodeError;
+type OprfClientErrorCode = 'NonUniqueServices' | 'InvalidDLogProof' | 'InconsistentOprfPublicKeys' | 'ThresholdServiceError' | 'Networking' | 'UnexpectedMessage' | 'CannotFinishSession' | 'NodeErrorDisagreement' | 'Unknown';
+interface OprfClientErrorDetails {
+    nodeErrors?: NodeError[];
+    serviceError?: ServiceError;
+    cause?: NodeError;
+    networkingErrors?: Error[];
+}
+declare class OprfClientError extends Error {
+    readonly code: OprfClientErrorCode;
+    readonly details?: OprfClientErrorDetails;
+    constructor(code: OprfClientErrorCode, message: string, details?: OprfClientErrorDetails);
+}
+declare function isOprfClientError(err: unknown): err is OprfClientError;
+/**
+ * Aggregate per-node errors into a protocol-level OprfClientError.
+ * Mirrors Rust oprf-client aggregate_error logic:
+ *  - >= threshold ServiceErrors with same code → ThresholdServiceError
+ *  - >= threshold UnexpectedMessage with same reason → UnexpectedMessage
+ *  - >= threshold WsErrors → Networking
+ *  - Otherwise → NodeErrorDisagreement
+ */
+declare function aggregateError(threshold: number, errors: NodeError[]): OprfClientError;
+
+/**
+ * URI construction helpers for OPRF service endpoints.
+ */
+/**
+ * Build a WebSocket URL for a single OPRF service.
+ * http → ws, https → wss. Appends /api/{auth_module_name}/oprf?version={clientVersion}.
+ */
+declare function toOprfUri(service: string, auth_module_name: string, clientVersion?: string): string;
+
+export { NodeError, type NodeErrorCode, OprfClientError, type OprfClientErrorCode, type OprfPublicKeyWithEpoch, type OprfRequest, type OprfResponse, type OprfSessions, ServiceError, type VerifiableOprfOutput, aggregateError, distributedOprf, finishSessions, generateChallengeRequest, initSessions, isNodeError, isOprfClientError, toOprfUri, verifyDlogEquality };

package/dist/index.d.ts

@@ -0,0 +1,207 @@
+import { PartialDLogEqualityCommitments, PartialDLogCommitmentsShamir, DLogCommitmentsShamir, DLogProofShareShamir, DLogEqualityProof } from '@taceo/oprf-core';
+import { AffinePoint } from '@noble/curves/abstract/curve.js';
+
+/**
+ * Wire and API types for OPRF client.
+ * Matches nullifier-oracle-service oprf-types (OprfRequest, OprfResponse, etc.).
+ */
+
+/**
+ * Affine point as JSON: a 2-element array [x, y] of decimal strings.
+ * Matches Rust ark_serde_compat::babyjubjub::serialize_affine / deserialize_affine.
+ */
+type AffinePointWire = [string, string];
+/** DLogCommitmentsShamir wire (server expects snake_case: contributing_parties). */
+interface DLogCommitmentsShamirWire {
+    c: AffinePointWire;
+    d1: AffinePointWire;
+    d2: AffinePointWire;
+    e1: AffinePointWire;
+    e2: AffinePointWire;
+    contributing_parties: number[];
+}
+/** OprfPublicKeyWithEpoch (internal: affine points). */
+interface OprfPublicKeyWithEpoch {
+    key: AffinePoint<bigint>;
+    epoch: number;
+}
+/** OprfRequest (internal: affine for blinded_query). */
+interface OprfRequest<Auth = unknown> {
+    request_id: string;
+    blinded_query: AffinePoint<bigint>;
+    auth: Auth;
+}
+/** OprfResponse (internal: affine points). */
+interface OprfResponse {
+    commitments: PartialDLogEqualityCommitments;
+    party_id: number;
+    oprf_pub_key_with_epoch: OprfPublicKeyWithEpoch;
+}
+
+/**
+ * WebSocket session for a single OPRF service connection.
+ * Takes a pre-built WS URL (see uri.ts). Errors are NodeError variants.
+ */
+
+/**
+ * Thin WebSocket session: connect, send JSON, receive JSON, handle close.
+ * Uses text (JSON) frames. Browser WebSocket cannot set headers; version is sent as query param.
+ * All errors are thrown as NodeError.
+ */
+declare class WebSocketSession {
+    private ws;
+    private readonly service;
+    private constructor();
+    get serviceUrl(): string;
+    /**
+     * Open a new WebSocket to the given pre-built WS URL.
+     * Connect errors throw NodeError('WsError', ...).
+     */
+    static connect(url: string): Promise<WebSocketSession>;
+    /** Send a JSON-serializable message as text frame. Throws NodeError('WsError') on failure. */
+    send<T extends object>(msg: T): void;
+    /**
+     * Read next message. Returns text data.
+     * Rejects with NodeError on:
+     *  - Binary frame → UnexpectedMessage
+     *  - Non-normal close → ServiceError
+     *  - Normal/1005 close → UnexpectedMessage('Server closed websocket')
+     *  - Error event → WsError
+     *  - null/end → UnexpectedMessage('Server closed connection')
+     */
+    private readNext;
+    /** Read and parse OprfResponse. Parse errors → NodeError('UnexpectedMessage'). */
+    readOprfResponse(): Promise<OprfResponse>;
+    /** Read and parse DLogProofShareShamir. Parse errors → NodeError('UnexpectedMessage'). */
+    readProofShare(): Promise<{
+        value: bigint;
+    }>;
+    /** Send challenge (DLogCommitmentsShamir wire). */
+    sendChallenge(wire: DLogCommitmentsShamirWire): void;
+    /** Gracefully close with normal code. */
+    close(): void;
+}
+
+/**
+ * Session management: initSessions (parallel connect, collect by epoch to threshold),
+ * finishSessions (send challenge, collect proof shares). Mirrors Rust oprf-client sessions.
+ */
+
+interface OprfSessions {
+    readonly ws: WebSocketSession[];
+    readonly partyIds: number[];
+    readonly commitments: PartialDLogCommitmentsShamir[];
+    readonly oprfPublicKeys: AffinePointLike[];
+    readonly epoch: number;
+}
+/** Internal: we only need key as affine for verification. */
+interface AffinePointLike {
+    x: bigint;
+    y: bigint;
+}
+/**
+ * Open WebSockets to each service in parallel, send oprfRequest, collect OprfResponse.
+ * Services must be pre-built WS URLs (see toOprfUri / toOprfUriMany).
+ * Group by epoch; when an epoch has >= threshold responses with distinct party_id, return those sessions (sorted by party_id).
+ * On failure: throws NodeError[] (caller wraps via aggregateError).
+ */
+declare function initSessions<Auth>(services: string[], threshold: number, oprfRequest: OprfRequest<Auth>): Promise<OprfSessions>;
+/**
+ * Send the same challenge to each session, read proof share, then close.
+ * Returns proof shares in the same order as sessions.ws.
+ * Errors bubble up as NodeError (thrown from ws methods).
+ */
+declare function finishSessions(sessions: OprfSessions, challenge: DLogCommitmentsShamir): Promise<DLogProofShareShamir[]>;
+
+/**
+ * High-level client: generateChallengeRequest, verifyDlogEquality, distributedOprf.
+ */
+
+interface VerifiableOprfOutput {
+    output: bigint;
+    dlogProof: DLogEqualityProof;
+    blindedRequest: AffinePoint<bigint>;
+    blindedResponse: AffinePoint<bigint>;
+    unblindedResponse: AffinePoint<bigint>;
+    oprfPublicKey: AffinePoint<bigint>;
+    epoch: number;
+}
+/**
+ * Build challenge from sessions: contributingParties = party_id + 1 per party, then combineCommitments.
+ */
+declare function generateChallengeRequest(sessions: OprfSessions): DLogCommitmentsShamir;
+/**
+ * Combine proof shares, verify DLog proof. Throws OprfClientError if invalid.
+ */
+declare function verifyDlogEquality(requestId: string, oprfPublicKey: AffinePoint<bigint>, blindedRequest: AffinePoint<bigint>, proofShares: DLogProofShareShamir[], challenge: DLogCommitmentsShamir): DLogEqualityProof;
+interface DistributedOprfOptions<Auth = unknown> {
+    /** Auth payload sent in OprfRequest (must be JSON-serializable). */
+    auth?: Auth;
+}
+/**
+ * Full distributed OPRF: blind → init sessions → challenge → finish → verify → unblind → finalize.
+ * Services must be pre-built WS URLs (use toOprfUri / toOprfUriMany).
+ */
+declare function distributedOprf(services: string[], threshold: number, query: bigint, domainSeparator: bigint, options?: DistributedOprfOptions): Promise<VerifiableOprfOutput>;
+
+/**
+ * Client error types matching the Rust oprf-client Error enum.
+ * Two-tier model: NodeError (per-node) and OprfClientError (protocol-level).
+ */
+/**
+ * Application-level error received in a WebSocket close frame from a node.
+ */
+declare class ServiceError extends Error {
+    readonly errorCode: number;
+    readonly msg?: string;
+    constructor(errorCode: number, msg?: string);
+}
+type NodeErrorCode = 'ServiceError' | 'WsError' | 'UnexpectedMessage' | 'Unknown';
+/**
+ * Per-node error, discriminated by `code`.
+ */
+declare class NodeError extends Error {
+    readonly code: NodeErrorCode;
+    readonly reason?: string;
+    readonly cause?: Error;
+    readonly serviceError?: ServiceError;
+    constructor(code: NodeErrorCode, opts?: {
+        reason?: string;
+        cause?: Error;
+        serviceError?: ServiceError;
+    });
+}
+declare function isNodeError(err: unknown): err is NodeError;
+type OprfClientErrorCode = 'NonUniqueServices' | 'InvalidDLogProof' | 'InconsistentOprfPublicKeys' | 'ThresholdServiceError' | 'Networking' | 'UnexpectedMessage' | 'CannotFinishSession' | 'NodeErrorDisagreement' | 'Unknown';
+interface OprfClientErrorDetails {
+    nodeErrors?: NodeError[];
+    serviceError?: ServiceError;
+    cause?: NodeError;
+    networkingErrors?: Error[];
+}
+declare class OprfClientError extends Error {
+    readonly code: OprfClientErrorCode;
+    readonly details?: OprfClientErrorDetails;
+    constructor(code: OprfClientErrorCode, message: string, details?: OprfClientErrorDetails);
+}
+declare function isOprfClientError(err: unknown): err is OprfClientError;
+/**
+ * Aggregate per-node errors into a protocol-level OprfClientError.
+ * Mirrors Rust oprf-client aggregate_error logic:
+ *  - >= threshold ServiceErrors with same code → ThresholdServiceError
+ *  - >= threshold UnexpectedMessage with same reason → UnexpectedMessage
+ *  - >= threshold WsErrors → Networking
+ *  - Otherwise → NodeErrorDisagreement
+ */
+declare function aggregateError(threshold: number, errors: NodeError[]): OprfClientError;
+
+/**
+ * URI construction helpers for OPRF service endpoints.
+ */
+/**
+ * Build a WebSocket URL for a single OPRF service.
+ * http → ws, https → wss. Appends /api/{auth_module_name}/oprf?version={clientVersion}.
+ */
+declare function toOprfUri(service: string, auth_module_name: string, clientVersion?: string): string;
+
+export { NodeError, type NodeErrorCode, OprfClientError, type OprfClientErrorCode, type OprfPublicKeyWithEpoch, type OprfRequest, type OprfResponse, type OprfSessions, ServiceError, type VerifiableOprfOutput, aggregateError, distributedOprf, finishSessions, generateChallengeRequest, initSessions, isNodeError, isOprfClientError, toOprfUri, verifyDlogEquality };