@terminal3/t3n-sdk 0.10.0 → 0.11.0

package/README.md

@@ -586,7 +586,7 @@ To use the real WASM component:
 
    ```bash
    cd node
-   cargo build -p session --target wasm32-wasip2 --release
+   cargo build -p session-client --target wasm32-wasip2 --release
    ```
 
 2. **Copy the WASM file** to the SDK directory:

package/dist/demo.d.ts

@@ -0,0 +1,25 @@
+/**
+ * T3n SDK Real WASM Demo Script
+ *
+ * This script demonstrates the T3n SDK using the actual WASM component
+ * built from the node session module.
+ */
+import { SessionStatus, Did } from "./src/index";
+import { type ChildProcess } from "child_process";
+declare global {
+    var __oidcServerProcess: ChildProcess | undefined;
+}
+interface DemoResult {
+    sessionId: {
+        value: string;
+    };
+    status: SessionStatus;
+    wasmLoaded: boolean;
+    authenticated: boolean;
+    did: Did | null;
+}
+/**
+ * Main Demo Function
+ */
+declare function runRealWasmDemo(): Promise<DemoResult>;
+export { runRealWasmDemo, type DemoResult };

package/dist/index.d.ts

@@ -1,71 +1,112 @@
 /**
- * WASM Component Interface — async direct-call.
+ * WASM Component Interface - Mirrors the WIT specification exactly
  *
- * Mirrors `tee:session@1.0.0` WIT world. The SDK talks to the WASM
- * only through these exports (plus host imports supplied at
- * instantiation); all protocol glue lives inside the contract.
+ * This interface works with completely opaque byte arrays, just like the WIT interface.
+ * The TypeScript SDK doesn't know about internal state machine phases or details.
  */
-interface ClientSessionKeys {
-    /** `encrypt_key || decrypt_key`, 64 bytes. */
-    blob: Uint8Array;
-    sid: Uint8Array;
-}
-interface HandshakeOutcome {
-    keys: ClientSessionKeys;
-    authenticated: boolean;
-    did?: string;
-    expirySec: bigint;
+/**
+ * Result type for WASM next() operations
+ */
+interface WasmNextResult {
+    state: Uint8Array;
+    request: Uint8Array;
 }
+/**
+ * Client handshake operations - completely opaque byte arrays only
+ */
 interface ClientHandshake {
-    run(sid: Uint8Array, cookie: string | undefined): HandshakeOutcome;
-}
-interface AuthOutcome {
-    did: string;
-    cookie?: string;
+    /**
+     * Process next step in handshake
+     * @param state - Current handshake state (null for initial call)
+     * @param action - Action to process (opaque bytes)
+     * @returns Promise with new state and request to send
+     */
+    next(state: Uint8Array | null, action: Uint8Array): Promise<WasmNextResult>;
+    /**
+     * Attempt to finalize handshake
+     * @param state - Current handshake state
+     * @returns Promise with session bytes if successful
+     * @throws Error containing "not yet finalized" if the state machine
+     *         has not reached its terminal phase. The SDK runtime treats
+     *         this as the loop's "keep going" signal, not a real error.
+     */
+    finish(state: Uint8Array): Promise<Uint8Array>;
 }
+/**
+ * Client authentication operations - completely opaque byte arrays only
+ */
 interface ClientAuth {
-    runEth(sessionKeys: Uint8Array, ethAddress: string, siweDomain: string | undefined, siweUrl: string | undefined, siweChainId: bigint | undefined): AuthOutcome;
     /**
-     * Run the full OIDC flow in one call. The contract drives both
-     * server round-trips and invokes the SDK's `getIdToken(provider,
-     * nonce)` host import in between to obtain the IdP-signed token.
+     * Process next step in authentication
+     * @param state - Current auth state (null for initial call)
+     * @param action - Action to process (opaque bytes)
+     * @returns Promise with new state and request to send
      */
-    runOidc(sessionKeys: Uint8Array, provider: string): AuthOutcome;
-}
-interface ServerSessionKeys {
-    c2s: Uint8Array;
-    s2c: Uint8Array;
-    sid: Uint8Array;
-}
-interface ServerOutcome {
-    keys: ServerSessionKeys;
-    authenticated: boolean;
-    did?: string;
-    expirySec: bigint;
-    refreshedCookie?: string;
+    next(state: Uint8Array | null, action: Uint8Array): Promise<WasmNextResult>;
+    /**
+     * Attempt to finalize authentication
+     * @param state - Current auth state
+     * @returns Promise with DID bytes if successful
+     * @throws Error containing "not yet finalized" if the state machine
+     *         has not reached its terminal phase. The SDK runtime treats
+     *         this as the loop's "keep going" signal, not a real error.
+     */
+    finish(state: Uint8Array): Promise<Uint8Array>;
 }
-interface ServerHandshake {
-    run(sid: Uint8Array, ciphertext: Uint8Array, cookieValue: string | undefined): ServerOutcome;
+/**
+ * Client authentication operations - completely opaque byte arrays only
+ */
+interface ClientExecute {
+    /**
+     * Process next step in authentication
+     * @param state - Current auth state (null for initial call)
+     * @param action - Action to process (opaque bytes)
+     * @returns Promise with new state and request to send
+     */
+    next(state: Uint8Array | null, action: Uint8Array): Promise<WasmNextResult>;
+    /**
+     * Attempt to finalize authentication
+     * @param state - Current auth state
+     * @returns Promise with DID bytes if successful
+     * @throws Error containing "not yet finalized" if the state machine
+     *         has not reached its terminal phase. The SDK runtime treats
+     *         this as the loop's "keep going" signal, not a real error.
+     */
+    finish(state: Uint8Array): Promise<Uint8Array>;
 }
+/**
+ * Session encryption/decryption operations - completely opaque byte arrays only
+ */
 interface SessionCrypto {
-    encrypt(keys: Uint8Array, plaintext: Uint8Array): Uint8Array;
-    decrypt(keys: Uint8Array, ciphertext: Uint8Array): Uint8Array;
-}
-interface Validation {
-    authenticated: boolean;
-    did?: string;
-    exp: bigint;
-}
-interface CookieIface {
-    validate(cookieValue: string, teeAddress: Uint8Array, nowSec: bigint): Validation;
+    /**
+     * Encrypt plaintext using session
+     * @param session - Session state (opaque bytes)
+     * @param plaintext - Data to encrypt
+     * @returns Promise with encrypted bytes
+     */
+    encrypt(session: Uint8Array, plaintext: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Decrypt ciphertext using session
+     * @param session - Session state (opaque bytes)
+     * @param ciphertext - Data to decrypt
+     * @returns Promise with decrypted bytes
+     */
+    decrypt(session: Uint8Array, ciphertext: Uint8Array): Promise<Uint8Array>;
 }
-/** Fully instantiated session component. */
+/**
+ * Main WASM Component interface - mirrors the WIT interface exactly
+ *
+ * This is completely opaque to the TypeScript layer. All state machine logic,
+ * authentication flows, and cryptographic operations are handled in WASM.
+ */
 interface WasmComponent {
-    clientHandshake: ClientHandshake;
-    clientAuth: ClientAuth;
-    serverHandshake: ServerHandshake;
-    sessionCrypto: SessionCrypto;
-    cookie: CookieIface;
+    /** Client-side state machines exported by the WASM component. */
+    flow: {
+        handshake: ClientHandshake;
+        auth: ClientAuth;
+        execute: ClientExecute;
+    };
+    session: SessionCrypto;
 }
 
 /**
@@ -172,75 +213,38 @@ declare function createLogger(level?: LogLevel): Logger;
 declare function getLogger(): Logger;
 
 /**
- * WASM Component Loader — async direct-call shape.
- *
- * Loads the `tee:session@1.0.0` jco-transpiled component. Host
- * imports (`host:session-interfaces/*`) are supplied at
- * instantiation; the caller can override any of them via
- * `WasmLoadConfig.hostImports` to plug a custom KEM public-key
- * source, ETH signer, etc. Defaults cover the common case for the
- * browser SDK:
+ * WASM Component Loader
  *
- *   - `entropy.random`:        WebCrypto `getRandomValues`
- *   - `kem.mlKemPublicKey`:    HTTP fetch of /pubkey (caller sets URL)
- *   - `kem.decapsulate`:       server-only; client-side stub returns error
- *   - `eth-signer.eth-sign`:   injected wallet (window.ethereum) if present
- *   - `session-ops.now-ms`:    Date.now()
- *   - `session-ops.tee-address`, `set-cookie`: caller-supplied or stubs
+ * This module provides utilities for loading and initializing the WASM component.
+ * The actual WASM loading implementation will depend on the build system and
+ * deployment environment.
  */
 
-/**
- * Host imports supplied at WASM instantiation. Any subset may be
- * overridden by the caller; unset ones fall back to a safe default
- * (or an error stub for server-only methods like `decapsulate`).
- */
-interface SessionHostImports {
-    /** Fetch the server's ML-KEM public key (client-side). */
-    mlKemPublicKey?: () => Uint8Array | Promise<Uint8Array>;
-    /** CSPRNG. Defaults to WebCrypto `getRandomValues`. */
-    random?: (len: number) => Uint8Array;
-    /** EIP-191 / SIWE signer. Defaults to error (caller must supply). */
-    ethSign?: (message: Uint8Array) => Uint8Array | Promise<Uint8Array>;
-    /**
-     * OIDC user-interaction callback. The contract supplies the
-     * server-bound `nonce`; the SDK consumer runs whatever popup /
-     * redirect flow is appropriate for `provider` and returns the
-     * IdP-signed `id_token`. Defaults to error (caller must supply
-     * when using OIDC auth).
-     */
-    getIdToken?: (provider: string, nonce: string) => string | Promise<string>;
-    /** Current time in ms. Defaults to Date.now() (as bigint). */
-    nowMs?: () => bigint;
-    /** TEE address — server-only; client stub returns 20 zero bytes. */
-    teeAddress?: () => Uint8Array;
-    /** Called when the guest emits a refreshed cookie. */
-    setCookie?: (value: string) => void;
-    /**
-     * HTTP transport the contract uses to POST JSON-RPC requests. The
-     * SDK wires this to its `Transport` under the hood — the contract
-     * supplies the method name and params bytes; the SDK layers on the
-     * Session-Id header, JSON-RPC envelope, and returns the raw result
-     * bytes.
-     */
-    postRpc?: (method: string, sessionId: string, params: string) => string | Promise<string>;
-}
 /**
  * Configuration for WASM component loading
  */
 interface WasmLoadConfig {
     /** Path or URL to the WASM module */
     wasmPath?: string;
+    /** Custom fetch function for loading WASM */
+    fetchFn?: typeof fetch;
+    /** Additional initialization options */
+    initOptions?: Record<string, unknown>;
     /** Optional logger instance - if not provided, uses global default */
     logger?: Logger;
-    /** Overrides for the host-import functions. */
-    hostImports?: SessionHostImports;
 }
 /**
- * Load and initialize the T3n WASM component (async direct-call).
+ * Load and initialize the T3n WASM component
  *
- * The caller normally only needs to override `mlKemPublicKey` (to
- * point at the node URL) and `ethSign` (to bridge to the browser
- * wallet). All other imports have sensible defaults.
+ * @param config - Optional configuration for loading the WASM component
+ * @returns Promise that resolves to the initialized WASM component
+ *
+ * @example
+ * ```typescript
+ * const wasmComponent = await loadWasmComponent({
+ *   wasmPath: '/path/to/t3n.wasm'
+ * });
+ * ```
  */
 declare function loadWasmComponent(config?: WasmLoadConfig): Promise<WasmComponent>;
 
@@ -282,15 +286,14 @@ declare enum AuthMethod {
 /**
  * OIDC credentials interface.
  *
- * The TEE generates a session-binding nonce; the user-interaction
- * step is wired at WASM load time via `hostImports.getIdToken`
- * (see `loadWasmComponent`), mirroring how `hostImports.ethSign`
- * supplies wallet access. The contract calls `getIdToken(provider,
- * nonce)` from inside `runOidc` and feeds the returned `id_token`
- * to the server.
+ * The TEE generates a session-binding nonce that must be included in
+ * the Google authorization URL (`&nonce=…`). The `getIdToken` callback
+ * receives this nonce and must return the `id_token` JWT obtained
+ * from the OIDC provider with the nonce baked into its claims.
  */
 interface OidcCredentials {
     provider: string;
+    getIdToken: (nonce: string) => Promise<string>;
 }
 /**
  * Base authentication input with method discriminator
@@ -322,6 +325,47 @@ type AuthInput = EthAuthInput | OidcAuthInput;
 declare function createEthAuthInput(address: string): EthAuthInput;
 declare function createOidcAuthInput(credentials: OidcCredentials): OidcAuthInput;
 
+/**
+ * Public types export for T3n SDK
+ */
+/**
+ * Guest-to-Host request handler function type
+ *
+ * Handles requests from WASM guest that need host (SDK) to perform side
+ * effects. The exact shape of `requestData` depends on the specific
+ * handler — see `GuestToHostHandlers` below for the per-handler shapes.
+ * The wrapper layer in `T3nClient.handleGuestToHost` parses the JSON
+ * envelope and calls the matching handler with the parsed data, so
+ * each handler's implementation should narrow `requestData` to its
+ * own expected shape.
+ */
+type GuestToHostHandler = (requestData: Record<string, unknown>) => Promise<Uint8Array>;
+/**
+ * Map of guest-to-host request handlers
+ * Keys match the guest_to_host tag values from the WASM
+ */
+interface GuestToHostHandlers {
+    /**
+     * Handle Ethereum signature requests
+     * requestData: { guest_to_host: "EthSign", challenge: string (base64) }
+     * Returns: JSON bytes of { host_to_guest: "EthSign", challenge: string, signature: string }
+     */
+    EthSign?: GuestToHostHandler;
+    /**
+     * Handle MlKem public key requests
+     * requestData: { guest_to_host: "MlKemPublicKey" }
+     * Returns: JSON bytes of { host_to_guest: "MlKemPublicKey", key: string }
+     */
+    MlKemPublicKey?: GuestToHostHandler;
+    /**
+     * Handle random bytes requests
+     * requestData: { guest_to_host: "Random", len?: number }
+     * Returns: JSON bytes of { host_to_guest: "Random", bytes: string (base64) }
+     */
+    Random?: GuestToHostHandler;
+    [key: string]: GuestToHostHandler | undefined;
+}
+
 /**
  * Transport layer for T3n SDK
  *
@@ -440,7 +484,7 @@ declare class MockTransport implements Transport {
 interface T3nClientConfig {
     /** Base URL of the T3n node (used if transport not provided) */
     baseUrl?: string;
-    /** WASM component instance (async direct-call — `tee:session@1.0.0`). */
+    /** WASM component instance for cryptographic operations */
     wasmComponent: WasmComponent;
     /** Optional transport layer - if not provided, uses HttpTransport with baseUrl */
     transport?: Transport;
@@ -450,90 +494,221 @@ interface T3nClientConfig {
     timeout?: number;
     /** Optional custom headers to include in requests */
     headers?: Record<string, string>;
-    /** Log level for this client instance. */
+    /**
+     * Log level for this client instance.
+     * Defaults to global log level (LogLevel.ERROR) if not specified.
+     * Use LogLevel.DEBUG for verbose logging, LogLevel.INFO for informational messages,
+     * LogLevel.WARN for warnings, or LogLevel.ERROR for errors only.
+     */
     logLevel?: LogLevel;
     /** Optional custom logger - if provided, overrides logLevel */
     logger?: Logger;
-    /**
-     * Optional signer bridge used by `authenticate()` for the ETH
-     * (SIWE) flow. Given the SIWE message bytes, the callback must
-     * produce a 65-byte `(r || s || v)` signature over the EIP-191
-     * personal-sign digest — matching `cryptography::ecdsa::eth`
-     * recovery on the node. A convenience wrapper for raw-private-key
-     * signing is planned for the follow-up commit that lands full
-     * ETH auth support.
-     */
-    ethSign?: (message: Uint8Array) => Promise<Uint8Array>;
-    /**
-     * Ethereum address (0x-prefixed, 20 bytes hex) of the user
-     * authenticating. Required by `authenticate()` for the ETH flow —
-     * the server recovers the signer from the SIWE message and
-     * compares to this address.
-     */
-    ethAddress?: string;
-    /**
-     * SIWE domain / URI / chain-id used in the message the SDK builds.
-     * Matches `SiwePolicy` on the server — the server's allowlist
-     * policy (if configured in NodeConfig) only accepts matching
-     * values. Defaults: domain `"localhost"`, URL `"https://trinity.io"`,
-     * chain ID `1` (Ethereum mainnet).
-     */
-    siweDomain?: string;
-    siweUrl?: string;
-    siweChainId?: number;
+    /** Optional guest-to-host request handlers - provides custom behavior for WASM requests */
+    handlers?: GuestToHostHandlers;
 }
 
 /**
- * T3n Client — thin host-function provider + WASM sequencer.
- *
- * The SDK communicates with the session contract strictly through
- * WIT:
- *   - Calls `clientHandshake.run(sid)` — contract handles ML-KEM
- *     encapsulation, HKDF, POSTs via `host.transport.postRpc`,
- *     derives session keys, returns them.
- *   - Calls `clientAuth.runEth(keys, address, ...)` — contract
- *     builds the SIWE message, signs via `host.eth-signer.ethSign`,
- *     POSTs + parses the Finish response, returns the DID.
- *   - For `execute()`, the SDK just encrypts the JSON-RPC payload
- *     via `sessionCrypto.encrypt` and POSTs it through its transport.
+ * T3n Client - Main SDK class
  *
- * No SIWE building, no HKDF, no hex/base64 shuffling, no wire
- * envelopes outside the contract. The contract is the single source
- * of protocol truth.
+ * Provides a simple interface for establishing secure sessions with T3n nodes.
+ * All cryptographic complexity is handled in WASM components.
  */
 
+/**
+ * Main T3n SDK Client
+ */
 declare class T3nClient {
     private readonly config;
     private readonly transport;
     private readonly sessionId;
     private readonly logger;
+    private readonly encryption;
     private status;
-    private sessionKeys;
+    /**
+     * In-flight WASM state-machine bytes. Holds the opaque state
+     * returned by `flow[method].next()` between iterations of
+     * `runFlow`. Always cleared at the top of `runFlow` and again
+     * once `tryFinalize` has extracted the terminal payload — so
+     * outside of an active loop these slots are always `null`.
+     */
+    private wasmState;
+    /**
+     * Terminal payloads produced by `flow[method].finish()`:
+     * - `handshake` → serialized session blob, used by
+     *   `getSessionState()` for subsequent `session.encrypt` calls.
+     * - `auth` → serialized DID; the public `authenticate()` decodes
+     *   it into `this.did` and the slot is otherwise unused.
+     * - `execute` → unused (executes return immediately to the caller).
+     *
+     * Stored in a dedicated field instead of reusing `wasmState`
+     * because the two meanings — "in-flight state machine" vs
+     * "finalized payload" — are semantically different and merging
+     * them invites the bug-class Devin flagged in PR #1140.
+     */
+    private finalizedPayload;
     private did;
+    private handshakeResult;
     constructor(config: T3nClientConfig);
+    /**
+     * Start the handshake process with the T3n node
+     */
     handshake(): Promise<HandshakeResult>;
+    /**
+     * Authenticate with the T3n node.
+     *
+     * For OIDC, this runs a two-step nonce-bound flow:
+     * 1. Sends `InitOidcAuth` to server → receives session-binding nonce.
+     * 2. Calls `getIdToken(nonce)` callback so the app can include the
+     *    nonce in the Google authorization URL.
+     * 3. Sends `SubmitIdToken` with the nonce-bearing token → receives DID.
+     */
     authenticate(authInput: AuthInput): Promise<Did>;
+    /**
+     * OIDC two-step authentication with session-binding nonce.
+     *
+     * Bypasses the WASM client state machine and makes two encrypted
+     * RPC calls directly:
+     * 1. `InitOidcAuth { provider }` → server generates nonce → returns
+     *    `ProvideNonce { nonce }`.
+     * 2. App calls `getIdToken(nonce)` to obtain a nonce-bound `id_token`.
+     * 3. `SubmitIdToken { id_token }` → server verifies token + nonce →
+     *    returns `Finish { did }`.
+     */
+    private authenticateOidc;
+    /**
+     * Execute an action on the T3n node
+     */
     execute(payload: unknown): Promise<string>;
     getSessionId(): SessionId;
     getStatus(): SessionStatus;
     getDid(): Did | null;
-    isAuthenticated(): boolean;
     getLastSetCookie(): string | null;
     getLastResponseHeaders(): Record<string, string>;
+    isAuthenticated(): boolean;
     /**
-     * Build the `host.transport.postRpc` callback the contract uses for
-     * all its HTTP round-trips. Must be passed into `loadWasmComponent`
-     * at instantiation time so the contract can POST during handshake
-     * and auth.
+     * Run a WASM state machine flow to completion.
+     *
+     * Clears both `wasmState[method]` and `finalizedPayload[method]`
+     * at entry so a flow that previously threw partway (e.g. an RPC
+     * error) starts from a clean slate on retry. Without the reset,
+     * stale state from the failed attempt leaks into the new flow
+     * and `tryFinalize` may either spuriously succeed or run `next()`
+     * against a state that no longer matches the action we're sending.
      *
-     * `params` from the contract is the opaque JSON-RPC params (already
-     * encrypted where encryption is needed). The SDK wraps in the
-     * JSON-RPC envelope and injects the Session-Id header.
+     * The `tryFinalize`-then-`next` order is load-bearing: the loop's
+     * exit condition fires *after* the previous iteration's
+     * `handleWasmRequest` has flushed the outbound peer reply, so
+     * every state-machine emission reaches the wire before we extract
+     * the final payload.
      */
-    buildPostRpcHostImport(): (method: string, _sessionIdFromGuest: string, params: string) => Promise<string>;
-    private sendRpcRaw;
+    private runFlow;
+    /**
+     * Try to finalize the current flow. Returns the finish() payload
+     * (a serialized Session for handshake, a serialized DID for auth)
+     * or `null` if the state machine has not reached its terminal phase
+     * yet.
+     *
+     * The "not yet finalized" case is the loop's signal to keep
+     * iterating, not a real error. Any *other* failure must propagate
+     * so callers see real WASM errors instead of silent retries that
+     * spin forever.
+     *
+     * The terminal payload is stored in `finalizedPayload[method]`
+     * (a separate field from `wasmState[method]`) so the in-flight
+     * state-machine bytes and the finalized session/DID bytes never
+     * occupy the same slot. `getSessionState()` reads from
+     * `finalizedPayload.handshake`.
+     */
+    private tryFinalize;
+    /**
+     * Handle a WASM request based on its type
+     */
+    private handleWasmRequest;
+    /**
+     * Handle a send-remote request by calling the RPC endpoint
+     */
+    private handleSendRemote;
+    private captureHandshakeResult;
+    /**
+     * Handle a guest-to-host request using configured handlers
+     */
+    private handleGuestToHost;
+    /**
+     * Send an RPC request with automatic encryption/decryption
+     */
+    private sendRpcRequest;
+    /**
+     * Get the finalized session blob (for `session.encrypt` calls).
+     * Populated by `tryFinalize` once the handshake state machine
+     * reaches its terminal phase.
+     */
+    private getSessionState;
 }
 
+/**
+ * Guest-to-Host Request Handlers
+ *
+ * These handle requests from WASM that need the host environment to perform side effects.
+ * Examples: signing challenges, providing public keys, generating random bytes.
+ */
+
+/**
+ * Account — MetaMask handler accepts either a plain address string or an
+ * object with an `address` field (for compatibility with various wallet
+ * libraries).
+ */
+type EthAccount = string | {
+    address: string;
+};
+/**
+ * Create an EthSign handler using MetaMask (window.ethereum)
+ * @param account - MetaMask account (string address or object with address property)
+ * @param logger - Optional logger instance. Defaults to a logger using the global log level (LogLevel.ERROR).
+ *   Pass a custom logger to override logging behavior for this handler.
+ * @param privateKey - Optional private key for signing (if provided, MetaMask is not used)
+ */
+declare function metamask_sign(account: EthAccount, logger?: Logger, privateKey?: string | undefined): GuestToHostHandler;
+/**
+ * Get the current MetaMask address
+ * @returns Ethereum address (lowercase, 0x prefixed)
+ */
+declare function metamask_get_address(): Promise<string>;
+/**
+ * Get the address for a given private key
+ * @param privateKey - Ethereum private key (0x prefixed hex string)
+ * @returns Ethereum address (lowercase, 0x prefixed)
+ */
+declare function eth_get_address(privateKey: string): string;
+/**
+ * Create an MlKemPublicKey handler that lazily fetches the root public key
+ * from `${baseUrl}/status` on first invocation and caches the encoded
+ * response for subsequent calls.
+ *
+ * @param baseUrl - **Required**. The node URL whose `/status` endpoint should
+ *                  serve the ML-KEM public key. Must be the same URL the
+ *                  T3nClient is constructed with — otherwise the handshake
+ *                  encrypts to one node and sends ciphertext to another.
+ *
+ *                  Was optional in 0.3.x, where omitting it caused the lazy
+ *                  fetch to silently fall back to `NODE_URLS[currentEnv]` and
+ *                  hit the wrong node. Three downstream consumers (demo.ts,
+ *                  t3-apps dev wallet hooks, t3n-mcp session manager) all
+ *                  hit this trap before we tightened the type.
+ */
+declare function createMlKemPublicKeyHandler(baseUrl: string): GuestToHostHandler;
+/**
+ * Create Random handler backed by crypto.getRandomValues
+ * Note: The Rust Vec<u8> type serializes as an array of bytes, not a base64 string
+ */
+declare function createRandomHandler(): GuestToHostHandler;
+/**
+ * Create the default handler set required by the T3n handshake.
+ *
+ * @param baseUrl - **Required**. Forwarded to `createMlKemPublicKeyHandler`
+ *                  so the lazy /status fetch hits the right node.
+ */
+declare function createDefaultHandlers(baseUrl: string): GuestToHostHandlers;
+
 /**
  * Cryptographic utilities for T3n SDK
  *
@@ -817,5 +992,5 @@ declare function clearKeyCache(): void;
  */
 declare function loadConfig(baseUrl?: string): SdkConfig;
 
-export { AuthMethod, AuthenticationError, HandshakeError, HttpTransport, LogLevel, MockTransport, NODE_URLS, RpcError, SessionStateError, SessionStatus, T3nClient, T3nError, WasmError, bytesToString, clearKeyCache, createEthAuthInput, createLogger, createOidcAuthInput, decodeWasmErrorMessage, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, loadConfig, loadWasmComponent, redactSecrets, redactSecretsFromJson, setEnvironment, setGlobalLogLevel, setNodeUrl, stringToBytes, validateConfig, verifyDkgAttestation, verifyTdxQuote };
-export type { AuthInput, AuthOutcome, ClientAuth, ClientHandshake, ClientSessionKeys, ConfigValidationResult, CookieIface, Did, DkgAttestation, DkgVerifyResult, Environment, EthAuthInput, HandshakeOutcome, HandshakeResult, JsonRpcRequest, JsonRpcResponse, Logger, OidcAuthInput, OidcCredentials, PeerQuoteResult, QuoteVerifyResult, SdkConfig, ServerHandshake, ServerOutcome, ServerSessionKeys, SessionCrypto, SessionHostImports, SessionId, T3nClientConfig, Transport, Validation, WasmComponent };
+export { AuthMethod, AuthenticationError, HandshakeError, HttpTransport, LogLevel, MockTransport, NODE_URLS, RpcError, SessionStateError, SessionStatus, T3nClient, T3nError, WasmError, bytesToString, clearKeyCache, createDefaultHandlers, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createRandomHandler, decodeWasmErrorMessage, eth_get_address, extractWasmError, fetchDkgAttestation, fetchMlKemPublicKey, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, loadConfig, loadWasmComponent, metamask_get_address, metamask_sign, redactSecrets, redactSecretsFromJson, setEnvironment, setGlobalLogLevel, setNodeUrl, stringToBytes, validateConfig, verifyDkgAttestation, verifyTdxQuote };
+export type { AuthInput, ClientAuth, ClientHandshake, ConfigValidationResult, Did, DkgAttestation, DkgVerifyResult, Environment, EthAuthInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, JsonRpcRequest, JsonRpcResponse, Logger, OidcAuthInput, OidcCredentials, PeerQuoteResult, QuoteVerifyResult, SdkConfig, SessionCrypto, SessionId, T3nClientConfig, Transport, WasmComponent, WasmNextResult };