@terminal3/t3n-sdk 0.2.1

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

@@ -0,0 +1,17 @@
+/**
+ * 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;

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

@@ -0,0 +1,35 @@
+/**
+ * Configuration types for T3n Client
+ */
+import { WasmComponent } from "../wasm";
+import { SessionId, GuestToHostHandlers } from "../types";
+import { Logger, LogLevel } from "../utils/logger";
+import { Transport } from "./transport";
+/**
+ * Configuration interface for T3n Client
+ */
+export interface T3nClientConfig {
+    /** Base URL of the T3n node (used if transport not provided) */
+    baseUrl?: string;
+    /** WASM component instance for cryptographic operations */
+    wasmComponent: WasmComponent;
+    /** Optional transport layer - if not provided, uses HttpTransport with baseUrl */
+    transport?: Transport;
+    /** Optional session ID - will be generated if not provided */
+    sessionId?: SessionId;
+    /** Optional request timeout in milliseconds (default: 30000) - used for HttpTransport */
+    timeout?: number;
+    /** Optional custom headers to include in requests */
+    headers?: Record<string, string>;
+    /**
+     * 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 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,45 @@
+/**
+ * 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";
+/**
+ * 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: any, 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 MlKemPublicKey handler that returns the environment-specific root public key
+ * Note: The Rust PkWithRho type serializes as an array of bytes, not a base64 string
+ */
+export declare function createMlKemPublicKeyHandler(): 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
+ */
+export declare function createDefaultHandlers(): GuestToHostHandlers;
+/**
+ * Merge consumer-provided handlers with defaults (user handlers take precedence)
+ */
+export declare function mergeWithDefaultHandlers(handlers?: GuestToHostHandlers): GuestToHostHandlers;

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

@@ -0,0 +1,10 @@
+/**
+ * Client exports for T3n SDK
+ */
+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

@@ -0,0 +1,70 @@
+/**
+ * T3n Client - Main SDK class
+ *
+ * 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 wasmState;
+    private did;
+    private handshakeResult;
+    constructor(config: T3nClientConfig);
+    /**
+     * Start the handshake process with the T3n node
+     */
+    handshake(): Promise<HandshakeResult>;
+    /**
+     * Authenticate with the T3n node
+     */
+    authenticate(authInput: AuthInput): Promise<Did>;
+    /**
+     * Execute an action on the T3n node
+     */
+    execute(payload: unknown): Promise<string>;
+    getSessionId(): SessionId;
+    getStatus(): SessionStatus;
+    getDid(): Did | null;
+    getLastSetCookie(): string | null;
+    getLastResponseHeaders(): Record<string, string>;
+    isAuthenticated(): boolean;
+    /**
+     * Run a WASM state machine flow to completion
+     */
+    private runFlow;
+    /**
+     * Try to finalize the current flow
+     */
+    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 current session state for encryption
+     */
+    private getSessionState;
+}

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

@@ -0,0 +1,107 @@
+/**
+ * Transport layer for T3n SDK
+ *
+ * Abstracts the communication with T3n nodes, allowing for different
+ * implementations (HTTP, WebSocket, Mock) and easy testing.
+ */
+/**
+ * JSON-RPC request structure
+ */
+export interface JsonRpcRequest {
+    jsonrpc: "2.0";
+    method: string;
+    params: any;
+    id: string | number;
+}
+/**
+ * JSON-RPC response structure
+ */
+export interface JsonRpcResponse {
+    jsonrpc: "2.0";
+    result?: any;
+    error?: {
+        code: number;
+        message: string;
+        data?: any;
+    };
+    id: string | number;
+}
+/**
+ * Transport interface for sending requests to T3n nodes
+ */
+export interface Transport {
+    /**
+     * Send a JSON-RPC request to the T3n node
+     * @param request - The JSON-RPC request to send
+     * @param headers - Additional headers to include
+     * @returns Promise that resolves to the JSON-RPC response
+     */
+    send(request: JsonRpcRequest, headers: Record<string, string>): Promise<JsonRpcResponse>;
+    /**
+     * Optional accessor for the latest Set-Cookie header value.
+     * (Useful in Node.js demos/tests; browsers block HttpOnly cookies.)
+     */
+    getLastSetCookie?(): string | null;
+    /**
+     * Optional accessor for the last response headers (debugging).
+     */
+    getLastResponseHeaders?(): Record<string, string>;
+}
+/**
+ * HTTP transport implementation using fetch
+ */
+export declare class HttpTransport implements Transport {
+    private baseUrl;
+    private timeout;
+    private lastSetCookie;
+    private lastResponseHeaders;
+    constructor(baseUrl: string, timeout?: number);
+    getLastSetCookie(): string | null;
+    getLastResponseHeaders(): Record<string, string>;
+    send(request: JsonRpcRequest, headers: Record<string, string>): Promise<JsonRpcResponse>;
+}
+/**
+ * Mock transport for testing
+ *
+ * @example
+ * ```typescript
+ * const mockTransport = new MockTransport();
+ * mockTransport.mockResponse("auth.handshake", { result: "..." });
+ *
+ * const client = new T3nClient({
+ *   transport: mockTransport,
+ *   wasmComponent: mockWasm,
+ * });
+ * ```
+ */
+export declare class MockTransport implements Transport {
+    private responses;
+    private requests;
+    /**
+     * Mock a response for a specific method
+     */
+    mockResponse(method: string, response: Partial<JsonRpcResponse>): void;
+    /**
+     * Mock an error response for a specific method
+     */
+    mockError(method: string, code: number, message: string, data?: any): void;
+    /**
+     * Get all requests that were sent
+     */
+    getRequests(): Array<{
+        request: JsonRpcRequest;
+        headers: Record<string, string>;
+    }>;
+    /**
+     * Get requests for a specific method
+     */
+    getRequestsForMethod(method: string): Array<{
+        request: JsonRpcRequest;
+        headers: Record<string, string>;
+    }>;
+    /**
+     * Clear all recorded requests
+     */
+    clearRequests(): void;
+    send(request: JsonRpcRequest, headers: Record<string, string>): Promise<JsonRpcResponse>;
+}

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

@@ -0,0 +1,67 @@
+/**
+ * Configuration entry point for T3n SDK
+ *
+ * This module imports all environment keys as base64 strings. All keys are included
+ * in the bundle, and the active key is selected at runtime via setEnvironment().
+ *
+ * Runtime key selection:
+ * - All keys (local, staging, production, test) are included in the bundle
+ * - Default environment is "production"
+ * - Use setEnvironment(env) to change the active key at runtime
+ *
+ * Binary files are converted to base64 strings at build time by the rollup binary plugin.
+ * In development mode (when running with tsx), files are read from the filesystem.
+ */
+import type { SdkConfig, Environment } from "./types";
+/**
+ * Set the active environment for key selection
+ *
+ * This function allows engineers to configure which ML-KEM public key
+ * should be used at runtime. All keys are included in the bundle, so
+ * switching environments doesn't require rebuilding.
+ *
+ * @param env - The environment identifier (local, staging, production, or test)
+ * @throws Error if the environment is invalid
+ *
+ * @example
+ * ```typescript
+ * import { setEnvironment } from '@terminal3/t3n-sdk';
+ *
+ * // Use staging environment
+ * setEnvironment('staging');
+ * ```
+ */
+export declare function setEnvironment(env: Environment): void;
+/**
+ * Get the current environment identifier
+ *
+ * Returns the currently active environment, which defaults to "production".
+ * Use setEnvironment() to change the active environment.
+ *
+ * @returns The current environment identifier
+ */
+export declare function getEnvironment(): Environment;
+/**
+ * Load configuration for the current environment
+ *
+ * Returns the SDK configuration with the ML-KEM public key for the
+ * currently active environment (set via setEnvironment()).
+ *
+ * @returns A minimal SdkConfig object with the ML-KEM public key
+ */
+export declare function loadConfig(): SdkConfig;
+/**
+ * Get the ML-KEM public key from the current configuration
+ * This is the main entry point used by handlers
+ *
+ * @returns The base64-encoded ML-KEM public key for the current environment
+ */
+export declare function getMlKemPublicKey(): string;
+/**
+ * Get the current environment identifier
+ *
+ * @returns The current environment name
+ */
+export declare function getEnvironmentName(): string;
+export type { SdkConfig, Environment, ConfigValidationResult } from "./types";
+export { validateConfig } from "./loader";

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

@@ -0,0 +1,11 @@
+/**
+ * Configuration loader for T3n SDK
+ *
+ * This module provides configuration validation utilities.
+ * All environment keys are included in the bundle, and runtime selection is done via setEnvironment().
+ */
+import type { ConfigValidationResult } from "./types";
+/**
+ * Validate SDK configuration
+ */
+export declare function validateConfig(config: unknown): ConfigValidationResult;

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

@@ -0,0 +1,25 @@
+/**
+ * Configuration types for T3n SDK
+ */
+/**
+ * Environment type for SDK configuration
+ */
+export type Environment = "local" | "staging" | "production" | "test";
+/**
+ * SDK configuration structure
+ */
+export interface SdkConfig {
+    /** Environment identifier */
+    environment: Environment;
+    /** Base64-encoded ML-KEM root public key */
+    mlKemPublicKey: string;
+    /** Configuration version */
+    version: string;
+}
+/**
+ * Configuration validation result
+ */
+export interface ConfigValidationResult {
+    valid: boolean;
+    errors: string[];
+}

package/dist/src/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * T3n TypeScript SDK
+ *
+ * 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";
+export type { HandshakeResult } from "./types";
+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, GuestToHostHandler, GuestToHostHandlers, } from "./types";
+export { SessionStatus, AuthMethod, createEthAuthInput, createOidcAuthInput, } from "./types";
+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";
+export type { SdkConfig, Environment, ConfigValidationResult } from "./config";
+export { loadConfig, getMlKemPublicKey, getEnvironmentName, getEnvironment, setEnvironment, validateConfig, } from "./config";

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

@@ -0,0 +1,54 @@
+/**
+ * Authentication-related types for T3n SDK
+ */
+/**
+ * Authentication method enum
+ */
+export declare enum AuthMethod {
+    Ethereum = "eth",
+    OIDC = "oidc"
+}
+/**
+ * Ethereum signer interface - only what user provides to start auth
+ */
+export interface EthereumSigner {
+    getPublicKey(): string;
+    signMessage(message: Uint8Array): Promise<Uint8Array>;
+}
+/**
+ * OIDC credentials interface
+ */
+export interface OidcCredentials {
+    provider: string;
+    idToken: string;
+}
+/**
+ * Base authentication input with method discriminator
+ */
+interface BaseAuthInput {
+    method: AuthMethod;
+}
+/**
+ * Ethereum authentication input
+ */
+export interface EthAuthInput extends BaseAuthInput {
+    method: AuthMethod.Ethereum;
+    address: string;
+}
+/**
+ * OIDC authentication input
+ */
+export interface OidcAuthInput extends BaseAuthInput {
+    method: AuthMethod.OIDC;
+    credentials: OidcCredentials;
+}
+/**
+ * Union type for all supported authentication inputs
+ */
+export type AuthInput = EthAuthInput | OidcAuthInput;
+/**
+ * Helper functions to create auth inputs
+ */
+export declare function createEthAuthInput(address: string): EthAuthInput;
+export declare function createOidcAuthInput(credentials: OidcCredentials): OidcAuthInput;
+export {};

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

@@ -0,0 +1,35 @@
+/**
+ * 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
+ */
+export type GuestToHostHandler = (requestData: any) => 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/types/session.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Session-related types for T3n SDK
+ */
+export interface SessionId {
+    readonly value: string;
+}
+export interface Did {
+    readonly value: string;
+    toString(): string;
+}
+export interface HandshakeResult {
+    readonly sessionId: SessionId;
+    readonly expiry: number;
+    readonly authenticated: boolean;
+    readonly did?: Did;
+}
+/**
+ * Simple status enum - mirrors server SessionStatus only
+ */
+export declare enum SessionStatus {
+    Init = 0,
+    Encrypted = 1,
+    Authenticated = 2
+}

package/dist/src/utils/contract-version.d.ts

@@ -0,0 +1,5 @@
+export interface CurrentVersionResponse {
+    current_version: string;
+}
+export declare function getScriptVersion(rpcUrl: string, scriptName: string): Promise<string>;
+export declare function resetScriptVersionCacheForTests(): void;

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

@@ -0,0 +1,52 @@
+/**
+ * Cryptographic utilities for T3n SDK
+ *
+ * Cross-platform crypto support:
+ * - Browsers: Uses Web Crypto API (global crypto)
+ * - Node.js 19+: Uses global crypto
+ * - Node.js 16-18: Imports crypto module
+ */
+/**
+ * Generate a cryptographically secure random string
+ * @param length - Length of the random string in bytes
+ * @returns Base64-encoded random string
+ */
+export declare function generateRandomString(length?: number): string;
+/**
+ * Generate a UUID v4
+ * @returns UUID string
+ */
+export declare function generateUUID(): string;
+/**
+ * Fill an array with cryptographically secure random values
+ * Cross-platform wrapper for crypto.getRandomValues
+ * @param array - Array to fill with random values
+ * @returns The same array (for compatibility with Web Crypto API)
+ */
+export declare function getRandomValues(array: Uint8Array): Uint8Array;
+/**
+ * Convert a string to Uint8Array
+ * @param str - String to convert
+ * @returns Uint8Array representation
+ */
+export declare function stringToBytes(str: string): Uint8Array;
+/**
+ * Convert Uint8Array to string
+ * @param bytes - Bytes to convert
+ * @returns String representation
+ */
+export declare function bytesToString(bytes: Uint8Array): string;
+export declare function bytesToBase64(bytes: Uint8Array): string;
+export declare function base64ToBytes(base64: string): Uint8Array;
+/**
+ * Sign raw bytes using EIP-191 format (Ethereum Signed Message)
+ * This is used for signing webhook payloads for provider authentication
+ *
+ * Format: "\x19Ethereum Signed Message:\n{len}" + bytes
+ * Then hash with Keccak256 and sign
+ *
+ * @param privateKey - Ethereum private key (0x prefixed hex string)
+ * @param bytes - Raw bytes to sign
+ * @returns Hex-encoded signature with 0x prefix (65 bytes: r + s + v)
+ */
+export declare function signRawBytesWithEip191(privateKey: string, bytes: Uint8Array): Promise<string>;