@worldcoin/idkit-core 2.0.2 → 4.0.1-dev.123c6a8

package/dist/index.d.ts

@@ -0,0 +1,490 @@
+/**
+ * Configuration types for IDKit
+ *
+ * Note: CredentialType, CredentialRequestType, and ConstraintNode are now
+ * re-exported from WASM (source of truth: rust/core/src/wasm_bindings.rs)
+ */
+declare const brand: unique symbol;
+type Brand<T, TBrand extends string> = T & {
+    [brand]: TBrand;
+};
+type AbiEncodedValue = Brand<{
+    types: string[];
+    values: unknown[];
+}, "AbiEncodedValue">;
+/**
+ * Relying Party context for protocol-level proof requests
+ *
+ * Required for creating a verification session. Contains RP-specific data
+ * needed to construct a ProofRequest. In production, this should be generated
+ * and signed by your backend.
+ */
+type RpContext = {
+    /** The registered RP ID (e.g., "rp_123456789abcdef0") */
+    rp_id: string;
+    /** Unique nonce for this proof request */
+    nonce: string;
+    /** Unix timestamp (seconds since epoch) when created */
+    created_at: number;
+    /** Unix timestamp (seconds since epoch) when expires */
+    expires_at: number;
+    /** The RP's ECDSA signature of the nonce and created_at timestamp */
+    signature: string;
+};
+/**
+ * Configuration for IDKit.request()
+ */
+type IDKitRequestConfig = {
+    /** Unique identifier for the app verifying the action. This should be the app ID obtained from the Developer Portal. */
+    app_id: `app_${string}`;
+    /** Identifier for the action the user is performing. Should be left blank for [Sign in with Worldcoin](https://docs.world.org/id/sign-in). */
+    action: AbiEncodedValue | string;
+    /** RP context for protocol-level proof requests (required) */
+    rp_context: RpContext;
+    /** The description of the specific action (shown to users in World App). Only recommended for actions created on-the-fly. */
+    action_description?: string;
+    /** URL to a third-party bridge to use when connecting to the World App. Optional. */
+    bridge_url?: string;
+};
+
+/** V4 response item (protocol version 4.0 / World ID v4) */
+interface ResponseItemV4 {
+    /** Credential identifier */
+    identifier: CredentialType;
+    /** Compressed Groth16 proof (hex) */
+    proof: string;
+    /** RP-scoped nullifier (hex) */
+    nullifier: string;
+    /** Authenticator merkle root (hex) */
+    merkle_root: string;
+    /** Unix timestamp when proof was generated */
+    proof_timestamp: number;
+    /** Credential issuer schema ID (hex) */
+    issuer_schema_id: string;
+}
+
+/** V3 response item (protocol version 3.0 / World ID v3 - legacy format) */
+interface ResponseItemV3 {
+    /** Credential identifier */
+    identifier: CredentialType;
+    /** ABI-encoded proof (hex) */
+    proof: string;
+    /** Merkle root (hex) */
+    merkle_root: string;
+    /** Nullifier hash (hex) */
+    nullifier_hash: string;
+}
+
+/**
+ * A single credential response item - unified type for both bridge and SDK.
+ * Type narrowing: use 'proof_timestamp' in item for V4, 'nullifier_hash' in item for V3.
+ */
+type ResponseItem = ResponseItemV4 | ResponseItemV3;
+
+/** V3 result (legacy format - no session support) */
+interface IDKitResultV3 {
+    /** Protocol version 3.0 */
+    protocol_version: "3.0";
+    /** Array of V3 credential responses */
+    responses: ResponseItemV3[];
+}
+
+/** V4 result (current format - supports sessions) */
+interface IDKitResultV4 {
+    /** Protocol version 4.0 */
+    protocol_version: "4.0";
+    /** Session ID (for session proofs) */
+    session_id?: string;
+    /** Array of V4 credential responses */
+    responses: ResponseItemV4[];
+}
+
+/** The unified response structure - discriminated union by protocol_version */
+type IDKitResult = IDKitResultV3 | IDKitResultV4;
+
+/** Status returned from pollForStatus() */
+type Status$1 =
+    | { type: "waiting_for_connection" }
+    | { type: "awaiting_confirmation" }
+    | { type: "confirmed"; result: IDKitResult }
+    | { type: "failed"; error: string };
+
+
+
+type CredentialType = "orb" | "face" | "secure_document" | "document" | "device";
+
+interface CredentialRequestType {
+    type: CredentialType;
+    signal?: string;
+    genesis_issued_at_min?: number;
+}
+
+type ConstraintNode =
+    | CredentialRequestType
+    | { any: ConstraintNode[] }
+    | { all: ConstraintNode[] };
+
+
+
+interface RpSignature {
+    sig: string;
+    nonce: string;
+    createdAt: number;
+    expiresAt: number;
+    toJSON(): { sig: string; nonce: string; createdAt: number; expiresAt: number };
+}
+declare class RpSignature {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Converts to JSON
+   *
+   * # Errors
+   *
+   * Returns an error if setting object properties fails
+   */
+  toJSON(): any;
+  /**
+   * Gets the creation timestamp
+   */
+  readonly createdAt: bigint;
+  /**
+   * Gets the expiration timestamp
+   */
+  readonly expiresAt: bigint;
+  /**
+   * Gets the signature as hex string (0x-prefixed, 65 bytes)
+   */
+  readonly sig: string;
+  /**
+   * Gets the nonce as hex string (0x-prefixed field element)
+   */
+  readonly nonce: string;
+}
+
+/**
+ * WASM initialization and management
+ */
+
+/**
+ * Initializes the WASM module for browser environments
+ * Uses fetch-based loading (works with http/https URLs)
+ * This must be called before using any WASM-powered functions
+ * Safe to call multiple times - initialization only happens once
+ */
+declare function initIDKit(): Promise<void>;
+/**
+ * Initializes the WASM module for Node.js/server environments
+ * Uses fs-based loading since Node.js fetch doesn't support file:// URLs
+ * This must be called before using any WASM-powered functions
+ * Safe to call multiple times - initialization only happens once
+ */
+declare function initIDKitServer(): Promise<void>;
+
+declare enum AppErrorCodes {
+    ConnectionFailed = "connection_failed",
+    VerificationRejected = "verification_rejected",
+    MaxVerificationsReached = "max_verifications_reached",
+    CredentialUnavailable = "credential_unavailable",
+    MalformedRequest = "malformed_request",
+    InvalidNetwork = "invalid_network",
+    InclusionProofFailed = "inclusion_proof_failed",
+    InclusionProofPending = "inclusion_proof_pending",
+    UnexpectedResponse = "unexpected_response",
+    FailedByHostApp = "failed_by_host_app",
+    GenericError = "generic_error"
+}
+declare enum VerificationState {
+    PreparingClient = "loading_widget",
+    WaitingForConnection = "awaiting_connection",
+    WaitingForApp = "awaiting_app",
+    Confirmed = "confirmed",
+    Failed = "failed"
+}
+declare enum ResponseStatus {
+    Retrieved = "retrieved",
+    Completed = "completed",
+    Initialized = "initialized"
+}
+
+/**
+ * IDKit Request
+ * Pure functional API for World ID verification - no dependencies
+ */
+
+/** Options for pollForUpdates() */
+interface WaitOptions {
+    /** Milliseconds between polls (default: 1000) */
+    pollInterval?: number;
+    /** Total timeout in milliseconds (default: 300000 = 5 minutes) */
+    timeout?: number;
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+}
+/** Status returned from pollOnce() */
+interface Status {
+    type: "waiting_for_connection" | "awaiting_confirmation" | "confirmed" | "failed";
+    result?: IDKitResult;
+    error?: AppErrorCodes;
+}
+
+/**
+ * A World ID verification request
+ *
+ * Provides a clean, promise-based API for World ID verification flows.
+ * Each request represents a single verification attempt.
+ */
+interface IDKitRequest {
+    /** QR code URL for World App - display this as a QR code for users to scan */
+    readonly connectorURI: string;
+    /** Unique request ID for this verification */
+    readonly requestId: string;
+    /** Poll once for current status (for manual polling) */
+    pollOnce(): Promise<Status>;
+    /** Poll continuously until completion or timeout */
+    pollForUpdates(options?: WaitOptions): Promise<IDKitResult>;
+}
+/**
+ * Creates a CredentialRequest for a credential type
+ *
+ * @param credential_type - The type of credential to request (e.g., 'orb', 'face')
+ * @param options - Optional signal and genesis_issued_at_min
+ * @returns A CredentialRequest object
+ *
+ * @example
+ * ```typescript
+ * const orb = CredentialRequest('orb', { signal: 'user-123' })
+ * const face = CredentialRequest('face')
+ * ```
+ */
+declare function CredentialRequest(credential_type: CredentialType, options?: {
+    signal?: string;
+    genesis_issued_at_min?: number;
+}): CredentialRequestType;
+/**
+ * Creates an OR constraint - at least one child must be satisfied
+ *
+ * @param nodes - Constraint nodes (CredentialRequests or nested constraints)
+ * @returns An "any" constraint node
+ *
+ * @example
+ * ```typescript
+ * const constraint = any(CredentialRequest('orb'), CredentialRequest('face'))
+ * ```
+ */
+declare function any(...nodes: ConstraintNode[]): {
+    any: ConstraintNode[];
+};
+/**
+ * Creates an AND constraint - all children must be satisfied
+ *
+ * @param nodes - Constraint nodes (CredentialRequests or nested constraints)
+ * @returns An "all" constraint node
+ *
+ * @example
+ * ```typescript
+ * const constraint = all(CredentialRequest('orb'), any(CredentialRequest('document'), CredentialRequest('secure_document')))
+ * ```
+ */
+declare function all(...nodes: ConstraintNode[]): {
+    all: ConstraintNode[];
+};
+/**
+ * OrbLegacy preset configuration
+ */
+interface OrbLegacyPreset {
+    type: "OrbLegacy";
+    data: {
+        signal?: string;
+    };
+}
+/**
+ * Preset types for simplified session creation
+ */
+type Preset = OrbLegacyPreset;
+/**
+ * Creates an OrbLegacy preset for World ID 3.0 legacy support
+ *
+ * This preset creates a session compatible with both World ID 4.0 and 3.0 protocols.
+ * Use this when you need backward compatibility with older World App versions.
+ *
+ * @param opts - Optional configuration with signal
+ * @returns An OrbLegacy preset
+ *
+ * @example
+ * ```typescript
+ * const session = await verify({ app_id, action, rp_context })
+ *   .preset(orbLegacy({ signal: 'user-123' }))
+ * ```
+ */
+declare function orbLegacy(opts?: {
+    signal?: string;
+}): OrbLegacyPreset;
+/**
+ * Builder for creating IDKit requests
+ */
+declare class IDKitRequestBuilder {
+    private config;
+    constructor(config: IDKitRequestConfig);
+    /**
+     * Creates an IDKit request with the given constraints
+     *
+     * @param constraints - Constraint tree (CredentialRequest or any/all combinators)
+     * @returns A new IDKitRequest instance
+     *
+     * @example
+     * ```typescript
+     * const request = await IDKit.request({ app_id, action, rp_context })
+     *   .constraints(any(CredentialRequest('orb'), CredentialRequest('face')))
+     * ```
+     */
+    constraints(constraints: ConstraintNode): Promise<IDKitRequest>;
+    /**
+     * Creates an IDKit request from a preset
+     *
+     * Presets provide a simplified way to create requests with predefined
+     * credential configurations. The preset is converted to both World ID 4.0
+     * constraints and World ID 3.0 legacy fields for backward compatibility.
+     *
+     * @param preset - A preset object from orbLegacy()
+     * @returns A new IDKitRequest instance
+     *
+     * @example
+     * ```typescript
+     * const request = await IDKit.request({ app_id, action, rp_context })
+     *   .preset(orbLegacy({ signal: 'user-123' }))
+     * ```
+     */
+    preset(preset: Preset): Promise<IDKitRequest>;
+}
+/**
+ * Creates an IDKit request builder
+ *
+ * This is the main entry point for creating World ID verification requests.
+ * Use the builder pattern with constraints to specify which credentials to accept.
+ *
+ * @param config - Request configuration
+ * @returns An IDKitRequestBuilder instance
+ *
+ * @example
+ * ```typescript
+ * import { IDKit, CredentialRequest, any } from '@worldcoin/idkit-core'
+ *
+ * // Initialize WASM (only needed once)
+ * await IDKit.init()
+ *
+ * // Create request items
+ * const orb = CredentialRequest('orb', { signal: 'user-123' })
+ * const face = CredentialRequest('face')
+ *
+ * // Create a verification request with constraints
+ * const request = await IDKit.request({
+ *   app_id: 'app_staging_xxxxx',
+ *   action: 'my-action',
+ *   rp_context: {
+ *     rp_id: 'rp_123456789abcdef0',
+ *     nonce: 'unique-nonce',
+ *     created_at: Math.floor(Date.now() / 1000),
+ *     expires_at: Math.floor(Date.now() / 1000) + 3600,
+ *     signature: 'ecdsa-signature-from-backend',
+ *   },
+ * }).constraints(any(orb, face))
+ *
+ * // Display QR code
+ * console.log('Scan this:', request.connectorURI)
+ *
+ * // Wait for proof
+ * const proof = await request.pollForUpdates()
+ * console.log('Success:', proof)
+ * ```
+ */
+declare function createRequest(config: IDKitRequestConfig): IDKitRequestBuilder;
+/**
+ * IDKit namespace providing the main API entry points
+ *
+ * @example
+ * ```typescript
+ * import { IDKit, CredentialRequest, any } from '@worldcoin/idkit-core'
+ *
+ * // Initialize (only needed once)
+ * await IDKit.init()
+ *
+ * // Create a request
+ * const request = await IDKit.request({
+ *   app_id: 'app_staging_xxxxx',
+ *   action: 'my-action',
+ *   rp_context: { ... },
+ * }).constraints(any(CredentialRequest('orb'), CredentialRequest('face')))
+ *
+ * // Display QR and wait for proof
+ * console.log(request.connectorURI)
+ * const proof = await request.pollForUpdates()
+ * ```
+ */
+declare const IDKit: {
+    /** Initialize WASM for browser environments */
+    init: typeof initIDKit;
+    /** Initialize WASM for Node.js/server environments */
+    initServer: typeof initIDKitServer;
+    /** Create a new verification request */
+    request: typeof createRequest;
+    /** Create a CredentialRequest for a credential type */
+    CredentialRequest: typeof CredentialRequest;
+    /** Create an OR constraint - at least one child must be satisfied */
+    any: typeof any;
+    /** Create an AND constraint - all children must be satisfied */
+    all: typeof all;
+    /** Create an OrbLegacy preset for World ID 3.0 legacy support */
+    orbLegacy: typeof orbLegacy;
+};
+
+/**
+ * Platform detection utilities
+ *
+ * These functions help detect the runtime environment (React Native, Web, Node.js)
+ * to enable platform-specific behavior or warnings.
+ */
+/**
+ * Checks if the code is running in React Native environment
+ * @returns true if running in React Native, false otherwise
+ */
+declare const isReactNative: () => boolean;
+/**
+ * Checks if the code is running in a web browser environment
+ * @returns true if running in a browser, false otherwise
+ */
+declare const isWeb: () => boolean;
+/**
+ * Checks if the code is running in Node.js environment
+ * @returns true if running in Node.js, false otherwise
+ */
+declare const isNode: () => boolean;
+
+/**
+ * Signs an RP request for World ID proof verification
+ *
+ * **Backend-only**: This function should ONLY be used in Node.js/server environments.
+ * Never use this in browser/client-side code as it requires access to your signing key.
+ *
+ * This function generates a cryptographic signature that authenticates your proof request.
+ * The returned signature, nonce, and timestamps should be passed as `rp_context` to the client.
+ *
+ * @param action - The action tied to the proof request
+ * @param signingKeyHex - The ECDSA private key as hex (0x-prefixed or not, 32 bytes)
+ * @param ttlSeconds - Optional time-to-live in seconds (defaults to 300 = 5 minutes)
+ * @returns RpSignature object with sig, nonce, createdAt, expiresAt to use as rp_context
+ * @throws Error if called in non-Node.js environment or if parameters are invalid
+ *
+ * @example
+ * ```typescript
+ * import { signRequest } from '@worldcoin/idkit-core'
+ *
+ * const signingKey = process.env.RP_SIGNING_KEY // Load from secure env var
+ * const signature = signRequest('my-action', signingKey)
+ * console.log(signature.sig, signature.nonce, signature.createdAt, signature.expiresAt)
+ * ```
+ */
+declare function signRequest(action: string, signingKeyHex: string, ttlSeconds?: number): RpSignature;
+
+export { type AbiEncodedValue, AppErrorCodes, type ConstraintNode, CredentialRequest, type CredentialRequestType, type CredentialType, IDKit, type IDKitRequest, type IDKitRequestConfig, type IDKitResult, type OrbLegacyPreset, type Preset, type ResponseItem, type ResponseItemV3, type ResponseItemV4, ResponseStatus, type RpContext, RpSignature, type Status$1 as Status, VerificationState, type WaitOptions, all, any, isNode, isReactNative, isWeb, orbLegacy, signRequest };