@worldcoin/idkit-core 4.0.1 → 4.0.2

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+export { RpSignature, signRequest } from './signing.js';
+export { hashSignal } from './hashing.js';
+
 /**
  * Configuration types for IDKit
  *
@@ -80,20 +83,22 @@ type IDKitSessionConfig = {
     environment?: "production" | "staging";
 };
 
-type CredentialType = "orb" | "face" | "secure_document" | "document" | "device";
+interface OrbLegacyPreset {
+    type: "OrbLegacy";
+    signal?: string;
+}
 
-interface CredentialRequestType {
-    type: CredentialType;
-    /** Signal can be a string or raw bytes (Uint8Array) */
-    signal?: string | Uint8Array;
-    genesis_issued_at_min?: number;
-    expires_at_min?: number;
+interface SecureDocumentLegacyPreset {
+    type: "SecureDocumentLegacy";
+    signal?: string;
 }
 
-type ConstraintNode =
-    | CredentialRequestType
-    | { any: ConstraintNode[] }
-    | { all: ConstraintNode[] };
+interface DocumentLegacyPreset {
+    type: "DocumentLegacy";
+    signal?: string;
+}
+
+type Preset = OrbLegacyPreset | SecureDocumentLegacyPreset | DocumentLegacyPreset;
 
 
 
@@ -223,131 +228,20 @@ type Status$1 =
 
 
 
-interface OrbLegacyPreset {
-    type: "OrbLegacy";
-    signal?: string;
-}
-
-interface SecureDocumentLegacyPreset {
-    type: "SecureDocumentLegacy";
-    signal?: string;
-}
-
-interface DocumentLegacyPreset {
-    type: "DocumentLegacy";
-    signal?: string;
-}
-
-type Preset = OrbLegacyPreset | SecureDocumentLegacyPreset | DocumentLegacyPreset;
-/**
- * Unified builder for creating `IDKit` requests and sessions (WASM)
- */
-declare class IDKitBuilder$1 {
-  free(): void;
-  [Symbol.dispose](): void;
-  /**
-   * Creates a `BridgeConnection` with the given constraints
-   */
-  constraints(constraints_json: any): Promise<any>;
-  /**
-   * Creates a new builder for proving an existing session
-   */
-  static forProveSession(session_id: string, app_id: string, rp_context: RpContextWasm, action_description?: string | null, bridge_url?: string | null, override_connect_base_url?: string | null, environment?: string | null): IDKitBuilder$1;
-  /**
-   * Creates a new builder for creating a new session
-   */
-  static forCreateSession(app_id: string, rp_context: RpContextWasm, action_description?: string | null, bridge_url?: string | null, override_connect_base_url?: string | null, environment?: string | null): IDKitBuilder$1;
-  /**
-   * Creates a new builder for uniqueness requests
-   */
-  constructor(app_id: string, action: string, rp_context: RpContextWasm, action_description: string | null | undefined, bridge_url: string | null | undefined, allow_legacy_proofs: boolean, override_connect_base_url?: string | null, environment?: string | null);
-  /**
-   * Creates a `BridgeConnection` from a preset (works for all request types)
-   */
-  preset(preset_json: any): Promise<any>;
-}
-/**
- * RP Context for protocol-level proof requests (WASM binding)
- *
- * Contains RP-specific data needed to construct a `ProofRequest`.
- */
-declare class RpContextWasm {
-  free(): void;
-  [Symbol.dispose](): void;
-  /**
-   * Creates a new RP context
-   *
-   * # Arguments
-   * * `rp_id` - The registered RP ID (e.g., `"rp_123456789abcdef0"`)
-   * * `nonce` - Unique nonce for this proof request
-   * * `created_at` - Unix timestamp (seconds since epoch) when created
-   * * `expires_at` - Unix timestamp (seconds since epoch) when expires
-   * * `signature` - The RP's ECDSA signature of the `nonce` and `created_at` timestamp
-   *
-   * # Errors
-   *
-   * Returns an error if `rp_id` is not a valid RP ID (must start with `rp_`)
-   */
-  constructor(rp_id: string, nonce: string, created_at: bigint, expires_at: bigint, signature: string);
-}
-
-
+type CredentialType = "orb" | "face" | "secure_document" | "document" | "device";
 
-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;
+interface CredentialRequestType {
+    type: CredentialType;
+    /** Signal can be a string or raw bytes (Uint8Array) */
+    signal?: string | Uint8Array;
+    genesis_issued_at_min?: number;
+    expires_at_min?: number;
 }
 
-/**
- * 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>;
+type ConstraintNode =
+    | CredentialRequestType
+    | { any: ConstraintNode[] }
+    | { all: ConstraintNode[] };
 
 /**
  * Result types - re-exported from WASM bindings
@@ -377,6 +271,19 @@ declare enum IDKitErrorCodes {
     Cancelled = "cancelled"
 }
 
+interface BuilderConfig {
+    type: "request" | "session" | "proveSession";
+    app_id: string;
+    action?: string;
+    session_id?: string;
+    rp_context?: RpContext;
+    action_description?: string;
+    bridge_url?: string;
+    allow_legacy_proofs?: boolean;
+    override_connect_base_url?: string;
+    environment?: string;
+}
+
 /**
  * IDKit Request
  * Pure functional API for World ID verification - no dependencies
@@ -482,7 +389,7 @@ declare function all(...nodes: ConstraintNode[]): {
  *
  * @example
  * ```typescript
- * const request = await IDKit.request({ app_id, action, rp_context })
+ * const request = await IDKit.request({ app_id, action, rp_context, allow_legacy_proofs: true })
  *   .preset(orbLegacy({ signal: 'user-123' }))
  * ```
  */
@@ -500,7 +407,7 @@ declare function orbLegacy(opts?: {
  *
  * @example
  * ```typescript
- * const request = await IDKit.request({ app_id, action, rp_context })
+ * const request = await IDKit.request({ app_id, action, rp_context, allow_legacy_proofs: true })
  *   .preset(secureDocumentLegacy({ signal: 'user-123' }))
  * ```
  */
@@ -518,7 +425,7 @@ declare function secureDocumentLegacy(opts?: {
  *
  * @example
  * ```typescript
- * const request = await IDKit.request({ app_id, action, rp_context })
+ * const request = await IDKit.request({ app_id, action, rp_context, allow_legacy_proofs: true })
  *   .preset(documentLegacy({ signal: 'user-123' }))
  * ```
  */
@@ -526,11 +433,15 @@ declare function documentLegacy(opts?: {
     signal?: string;
 }): DocumentLegacyPreset;
 /**
- * Merged builder for IDKit requests
+ * Builder for IDKit requests
+ *
+ * Stores configuration and defers transport selection to `.preset()` / `.constraints()`.
+ * In World App: uses native postMessage transport (no WASM needed).
+ * On web: uses WASM bridge transport (QR code + polling).
  */
 declare class IDKitBuilder {
-    private wasmBuilder;
-    constructor(wasmBuilder: IDKitBuilder$1);
+    private config;
+    constructor(config: BuilderConfig);
     /**
      * Creates an IDKit request with the given constraints
      *
@@ -539,67 +450,64 @@ declare class IDKitBuilder {
      *
      * @example
      * ```typescript
-     * const builder = await IDKit.request({ app_id, action, rp_context });
-     * const request = await builder.constraints(any(CredentialRequest('orb'), CredentialRequest('face')));
+     * const request = await IDKit.request({ app_id, action, rp_context, allow_legacy_proofs: false })
+     *   .constraints(any(CredentialRequest('orb'), CredentialRequest('face')));
      * ```
      */
+    constraints(constraints: ConstraintNode): Promise<IDKitRequest>;
     /**
      * Creates an IDKit request from a preset (works for all request types)
      *
      * Presets provide a simplified way to create requests with predefined
      * credential configurations.
      *
-     * @param preset - A preset object from orbLegacy()
+     * @param preset - A preset object from orbLegacy(), secureDocumentLegacy(), or documentLegacy()
      * @returns A new IDKitRequest instance
      *
      * @example
      * ```typescript
-     * const builder = await IDKit.request({ app_id, action, rp_context });
-     * const request = await builder.preset(orbLegacy({ signal: 'user-123' }));
+     * const request = await IDKit.request({ app_id, action, rp_context, allow_legacy_proofs: true })
+     *   .preset(orbLegacy({ signal: 'user-123' }));
      * ```
      */
     preset(preset: Preset): Promise<IDKitRequest>;
 }
 /**
- * Creates an IDKit request builder
+ * Creates an IDKit verification 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.
+ * Use the builder pattern with `.preset()` or `.constraints()` to specify
+ * which credentials to accept.
  *
  * @param config - Request configuration
  * @returns IDKitBuilder - A builder instance
  *
  * @example
  * ```typescript
- * import { IDKit, CredentialRequest, any } from '@worldcoin/idkit-core'
- *
- * // Initialize WASM (only needed once)
- * await IDKit.init()
+ * import { IDKit, CredentialRequest, any, orbLegacy } from '@worldcoin/idkit-core'
  *
- * // Create request items
- * const orb = CredentialRequest('orb', { signal: 'user-123' })
- * const face = CredentialRequest('face')
+ * // With preset (legacy support)
+ * const request = await IDKit.request({
+ *   app_id: 'app_staging_xxxxx',
+ *   action: 'my-action',
+ *   rp_context: { ... },
+ *   allow_legacy_proofs: true,
+ * }).preset(orbLegacy({ signal: 'user-123' }));
  *
- * // Create a verification request with constraints
+ * // With constraints (v4 only)
  * 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',
- *   },
+ *   rp_context: { ... },
  *   allow_legacy_proofs: false,
- * }).constraints(any(orb, face));
+ * }).constraints(any(CredentialRequest('orb'), CredentialRequest('face')));
  *
- * // Display QR code
- * console.log('Scan this:', request.connectorURI)
+ * // In World App: connectorURI is empty, result comes via postMessage
+ * // On web: connectorURI is the QR URL to display
+ * console.log(request.connectorURI);
  *
- * // Wait for proof
- * const proof = await request.pollUntilCompletion()
- * console.log('Success:', proof)
+ * // Wait for result — same interface in both environments
+ * const proof = await request.pollUntilCompletion();
  * ```
  */
 declare function createRequest(config: IDKitRequestConfig): IDKitBuilder;
@@ -661,28 +569,23 @@ declare function proveSession(sessionId: string, config: IDKitSessionConfig): ID
  *
  * @example
  * ```typescript
- * import { IDKit, CredentialRequest, any } from '@worldcoin/idkit-core'
+ * import { IDKit, CredentialRequest, any, orbLegacy } from '@worldcoin/idkit-core'
  *
- * // Initialize (only needed once)
- * await IDKit.init()
- *
- * // Create a request
+ * // Create a verification request
  * const request = await IDKit.request({
  *   app_id: 'app_staging_xxxxx',
  *   action: 'my-action',
  *   rp_context: { ... },
- * }).constraints(any(CredentialRequest('orb'), CredentialRequest('face')))
+ *   allow_legacy_proofs: true,
+ * }).preset(orbLegacy({ signal: 'user-123' }))
  *
- * // Display QR and wait for proof
+ * // In World App: result comes via postMessage (no QR needed)
+ * // On web: display QR code and wait for proof
  * console.log(request.connectorURI)
  * const proof = await request.pollUntilCompletion()
  * ```
  */
 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 new session (no action, no existing session_id) */
@@ -725,39 +628,4 @@ declare const isWeb: () => boolean;
  */
 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;
-
-/**
- * Hashes a Signal (string or Uint8Array) to its hash representation.
- * This is the same hashing used internally when constructing proof requests.
- *
- * @param signal - The signal to hash (string or Uint8Array)
- * @returns 0x-prefixed hex string representing the signal hash
- */
-declare function hashSignal(signal: string | Uint8Array): string;
-
-export { type AbiEncodedValue, type ConstraintNode, CredentialRequest, type CredentialRequestType, type CredentialType, type DocumentLegacyPreset, IDKit, type IDKitCompletionResult, type IDKitErrorCode, IDKitErrorCodes, type IDKitRequest, type IDKitRequestConfig, type IDKitResult, type IDKitResultSession, type IDKitSessionConfig, type OrbLegacyPreset, type Preset, type ResponseItemSession, type ResponseItemV3, type ResponseItemV4, type RpContext, RpSignature, type SecureDocumentLegacyPreset, type Status$1 as Status, type WaitOptions, all, any, documentLegacy, hashSignal, isNode, isReactNative, isWeb, orbLegacy, secureDocumentLegacy, signRequest };
+export { type AbiEncodedValue, type ConstraintNode, CredentialRequest, type CredentialRequestType, type CredentialType, type DocumentLegacyPreset, IDKit, type IDKitCompletionResult, type IDKitErrorCode, IDKitErrorCodes, type IDKitRequest, type IDKitRequestConfig, type IDKitResult, type IDKitResultSession, type IDKitSessionConfig, type OrbLegacyPreset, type Preset, type ResponseItemSession, type ResponseItemV3, type ResponseItemV4, type RpContext, type SecureDocumentLegacyPreset, type Status$1 as Status, type WaitOptions, all, any, documentLegacy, isNode, isReactNative, isWeb, orbLegacy, secureDocumentLegacy };