@terminal3/t3n-sdk 0.10.0 → 0.12.0

package/dist/src/client/actions.d.ts

@@ -0,0 +1,22 @@
+/**
+ * WASM Action Creators
+ *
+ * Creates the initial action payloads for WASM state machines.
+ * These are JSON-serialized and passed to the WASM component to start flows.
+ */
+import { AuthInput } from "../types";
+/**
+ * Create the initial handshake request
+ * This kicks off the handshake state machine in WASM
+ */
+export declare function createHandshakeAction(): Uint8Array;
+/**
+ * Create the initial authentication request based on auth method
+ * @param authInput - The authentication input (Ethereum or OIDC)
+ */
+export declare function createAuthAction(authInput: AuthInput): Uint8Array;
+/**
+ * Create the OIDC SubmitToken action for the second step of nonce-bound auth.
+ * @param idToken - The id_token JWT obtained from the OIDC provider with the nonce
+ */
+export declare function createOidcSubmitTokenAction(idToken: string): Uint8Array;

package/dist/src/client/config.d.ts

@@ -2,7 +2,7 @@
  * Configuration types for T3n Client
  */
 import { WasmComponent } from "../wasm";
-import { SessionId } from "../types";
+import { SessionId, GuestToHostHandlers } from "../types";
 import { Logger, LogLevel } from "../utils/logger";
 import { Transport } from "./transport";
 /**
@@ -11,7 +11,7 @@ import { Transport } from "./transport";
 export 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;
@@ -21,35 +21,15 @@ export 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;
 }

package/dist/src/client/encryption.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Session Encryption Service
+ *
+ * Handles encryption and decryption of data using the established WASM session.
+ * Keeps cryptographic operations isolated and simple.
+ */
+import { SessionCrypto } from "../wasm";
+import { Logger } from "../utils/logger";
+/**
+ * Encrypts and decrypts data using an established session
+ */
+export declare class SessionEncryption {
+    private sessionCrypto;
+    private logger;
+    constructor(sessionCrypto: SessionCrypto, logger: Logger);
+    /**
+     * Encrypt data using the session
+     * @param sessionState - The session state bytes (from handshake)
+     * @param data - The plaintext data to encrypt
+     * @returns Base64-encoded encrypted data
+     */
+    encrypt(sessionState: Uint8Array, data: Uint8Array): Promise<string>;
+    /**
+     * Decrypt data using the session
+     * @param sessionState - The session state bytes (from handshake)
+     * @param encryptedData - Base64-encoded encrypted data
+     * @returns Decrypted plaintext bytes
+     */
+    decrypt(sessionState: Uint8Array, encryptedData: string): Promise<Uint8Array>;
+}

package/dist/src/client/handlers.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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.
+ */
+import { GuestToHostHandler, GuestToHostHandlers } from "../types";
+import { Logger } from "../utils/logger";
+/**
+ * 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)
+ */
+export declare function metamask_sign(account: EthAccount, logger?: Logger, privateKey?: string | undefined): GuestToHostHandler;
+/**
+ * Get the current MetaMask address
+ * @returns Ethereum address (lowercase, 0x prefixed)
+ */
+export 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)
+ */
+export 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.
+ */
+export 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
+ */
+export 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.
+ */
+export declare function createDefaultHandlers(baseUrl: string): GuestToHostHandlers;
+/**
+ * Merge consumer-provided handlers with defaults (user handlers take precedence).
+ *
+ * @param handlers - Optional consumer overrides.
+ * @param baseUrl  - **Required**. Forwarded to the default handler set so the
+ *                   ML-KEM key fetch hits the right node.
+ */
+export declare function mergeWithDefaultHandlers(handlers: GuestToHostHandlers | undefined, baseUrl: string): GuestToHostHandlers;
+export {};

package/dist/src/client/index.d.ts

@@ -4,3 +4,7 @@
 export * from "./config";
 export * from "./transport";
 export * from "./t3n-client";
+export * from "./handlers";
+export * from "./encryption";
+export * from "./actions";
+export * from "./request-parser";

package/dist/src/client/request-parser.d.ts

@@ -0,0 +1,48 @@
+/**
+ * WASM Request Parser
+ *
+ * Parses and categorizes requests from the WASM state machine.
+ * The WASM component outputs JSON with a `guest_to_host` tag that determines
+ * how the SDK should handle the request.
+ *
+ * See node/session/src/abi.rs for the GuestToHost enum definition.
+ */
+/**
+ * Types of requests that can come from WASM
+ */
+export declare enum WasmRequestType {
+    /** Send data to remote server (PeerReply with action) */
+    SendRemote = "SendRemote",
+    /** Request to host (SDK) for side effects (MlKemPublicKey, Random, EthSign, etc.) */
+    GuestToHost = "GuestToHost",
+    /** Flow complete (Suspend) */
+    Suspend = "Suspend"
+}
+/**
+ * Parsed result from WASM request
+ */
+export interface ParsedRequest {
+    type: WasmRequestType;
+    data: Record<string, unknown>;
+    raw: string;
+}
+/**
+ * Parses WASM request bytes into a categorized request type
+ */
+export declare function parseWasmRequest(requestBytes: Uint8Array): ParsedRequest;
+/**
+ * Check if a request should be sent to the remote server
+ */
+export declare function isSendRemote(parsed: ParsedRequest): boolean;
+/**
+ * Check if a request indicates flow completion
+ */
+export declare function isCompletion(parsed: ParsedRequest): boolean;
+/**
+ * Check if a request needs a guest-to-host handler
+ */
+export declare function isGuestToHost(parsed: ParsedRequest): boolean;
+/**
+ * Get the guest-to-host request type name (e.g., "MlKemPublicKey", "Random", "EthSign")
+ */
+export declare function getGuestToHostType(parsed: ParsedRequest): string | null;

package/dist/src/client/t3n-client.d.ts

@@ -1,51 +1,138 @@
 /**
- * T3n Client — thin host-function provider + WASM sequencer.
+ * T3n Client - Main SDK class
  *
- * 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.
- *
- * 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.
  */
 import { T3nClientConfig } from "./config";
 import { SessionId, Did, SessionStatus, AuthInput, HandshakeResult } from "../types";
+/**
+ * Main T3n SDK Client
+ */
 export 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.
+     */
+    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.
      */
-    buildPostRpcHostImport(): (method: string, _sessionIdFromGuest: string, params: string) => Promise<string>;
-    private sendRpcRaw;
+    private getSessionState;
 }

package/dist/src/index.d.ts

@@ -1,11 +1,9 @@
 /**
  * T3n TypeScript SDK
  *
- * A thin host-function provider over the `tee:session` WASM
- * contract. The SDK supplies host imports (transport, wallet, OIDC
- * popup, KEM pubkey, RNG, time, cookie sink) at jco instantiation
- * time and calls the contract's typed exports for handshake, auth,
- * and session crypto. The contract owns every protocol detail.
+ * A minimal TypeScript SDK that mirrors the server's RPC handler approach,
+ * keeping all state machine logic hidden in WASM and providing a clean,
+ * agnostic wrapper that doesn't expose authentication methods or internal states.
  */
 export { T3nClient } from "./client";
 export type { T3nClientConfig } from "./client";
@@ -14,9 +12,10 @@ export type { Logger } from "./utils/logger";
 export { LogLevel, createLogger, getLogger, setGlobalLogLevel, getGlobalLogLevel, } from "./utils/logger";
 export type { Transport, JsonRpcRequest, JsonRpcResponse } from "./client";
 export { HttpTransport, MockTransport } from "./client";
-export type { SessionId, Did, OidcCredentials, AuthInput, EthAuthInput, OidcAuthInput, } from "./types";
+export type { SessionId, Did, OidcCredentials, AuthInput, EthAuthInput, OidcAuthInput, GuestToHostHandler, GuestToHostHandlers, } from "./types";
 export { SessionStatus, AuthMethod, createEthAuthInput, createOidcAuthInput, } from "./types";
-export type { WasmComponent, ClientHandshake, ClientAuth, ServerHandshake, SessionCrypto, CookieIface, ClientSessionKeys, ServerSessionKeys, HandshakeOutcome, AuthOutcome, ServerOutcome, Validation, SessionHostImports, } from "./wasm";
+export { metamask_sign, metamask_get_address, eth_get_address, createDefaultHandlers, createMlKemPublicKeyHandler, createRandomHandler, } from "./client/handlers";
+export type { WasmComponent, ClientHandshake, ClientAuth, SessionCrypto, WasmNextResult, } from "./wasm";
 export { loadWasmComponent } from "./wasm";
 export { generateRandomString, generateUUID, getScriptVersion, stringToBytes, bytesToString, redactSecrets, redactSecretsFromJson, } from "./utils";
 export { T3nError, SessionStateError, AuthenticationError, HandshakeError, RpcError, WasmError, decodeWasmErrorMessage, extractWasmError, } from "./utils/errors";

package/dist/src/types/auth.d.ts

@@ -18,15 +18,14 @@ export interface EthereumSigner {
 /**
  * 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.
  */
 export interface OidcCredentials {
     provider: string;
+    getIdToken: (nonce: string) => Promise<string>;
 }
 /**
  * Base authentication input with method discriminator

package/dist/src/types/index.d.ts

@@ -1,18 +1,42 @@
 /**
- * Public types export for T3n SDK.
- *
- * The legacy `GuestToHostHandler` / `GuestToHostHandlers` types are
- * gone — the SDK is now strictly a thin host-function provider. The
- * `tee:session` contract owns every protocol detail (SIWE message
- * build, HKDF, AES-GCM, wire-envelope wrapping); the SDK supplies a
- * small set of host imports (`mlKemPublicKey`, `random`, `ethSign`,
- * `getIdToken`, `nowMs`, `setCookie`, `postRpc`) at jco instantiation
- * time and calls the contract's typed WIT exports
- * (`clientHandshake.run`, `clientAuth.runEth` / `runOidc`,
- * `sessionCrypto.encrypt` / `decrypt`).
+ * Public types export for T3n SDK
+ */
+/**
+ * Guest-to-Host request handler function type
  *
- * See `src/wasm/loader.ts` for the host-import surface and
- * `src/client/t3n-client.ts` for the consumer-facing API.
+ * 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.
+ */
+export 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
  */
+export 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;
+}
 export * from "./session";
 export * from "./auth";

package/dist/src/utils/index.d.ts

@@ -4,7 +4,6 @@
 export * from "./crypto";
 export * from "./contract-version";
 export * from "./errors";
-export * from "./hkdf";
 export * from "./logger";
 export * from "./redaction";
 export * from "./session";