@terminal3/t3n-sdk 0.2.1 → 0.4.0

package/dist/index.d.ts

@@ -587,19 +587,34 @@ declare function metamask_get_address(): Promise<string>;
  */
 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
+ * 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(): GuestToHostHandler;
+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
+ * 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(): GuestToHostHandlers;
+declare function createDefaultHandlers(baseUrl: string): GuestToHostHandlers;
 
 /**
  * Cryptographic utilities for T3n SDK
@@ -724,8 +739,8 @@ type Environment = "local" | "staging" | "production" | "test";
 interface SdkConfig {
     /** Environment identifier */
     environment: Environment;
-    /** Base64-encoded ML-KEM root public key */
-    mlKemPublicKey: string;
+    /** Resolved node URL (used both for RPC and for fetching the ML-KEM key) */
+    nodeUrl: string;
     /** Configuration version */
     version: string;
 }
@@ -738,10 +753,7 @@ interface ConfigValidationResult {
 }
 
 /**
- * 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().
+ * Configuration validation for T3n SDK
  */
 
 /**
@@ -752,68 +764,49 @@ declare function validateConfig(config: unknown): ConfigValidationResult;
 /**
  * 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.
+ * The SDK no longer bundles ML-KEM root public keys. Instead, the active node
+ * URL is derived from the current environment (or an explicit override / the
+ * client's `baseUrl`), and the ML-KEM public key is fetched lazily from
+ * `${nodeUrl}/status` (`encaps_key` field) and cached per-URL.
  */
 
 /**
- * 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');
- * ```
+ * Default node URLs per environment. Override at runtime via `setNodeUrl()`
+ * or by passing `baseUrl` to `T3nClient`.
  */
-declare function setEnvironment(env: Environment): void;
+declare const NODE_URLS: Record<Environment, string>;
 /**
- * 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
+ * Set the active environment. Clears any previous URL override and the key
+ * cache so the next fetch uses the new environment's default URL.
  */
+declare function setEnvironment(env: Environment): void;
 declare function getEnvironment(): Environment;
+declare function getEnvironmentName(): string;
 /**
- * Load configuration for the current environment
- *
- * Returns the SDK configuration with the ML-KEM public key for the
- * currently active environment (set via setEnvironment()).
+ * Override the node URL for the current process. Pass `null` to clear and
+ * fall back to the environment default.
  *
- * @returns A minimal SdkConfig object with the ML-KEM public key
+ * Always clears the per-URL key cache, including the `setNodeUrl(sameUrl)`
+ * case — that's the explicit "force a refresh after a node-side ML-KEM
+ * rotation" entry point. Keeping a no-op-call optimization here would
+ * silently defeat that contract; an extra fetch on a no-op call is cheap.
  */
-declare function loadConfig(): SdkConfig;
+declare function setNodeUrl(url: string | null): void;
+/** Resolve the active node URL: explicit `baseUrl` > override > env default. */
+declare function getNodeUrl(baseUrl?: string): string;
 /**
- * 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
+ * Fetch the ML-KEM root public key from `${nodeUrl}/status`. Cached per URL.
+ * The node must be in the `Ready` phase and expose `encaps_key`.
  */
-declare function getMlKemPublicKey(): string;
+declare function fetchMlKemPublicKey(baseUrl?: string): Promise<string>;
+/** Clear the cached ML-KEM public keys. Useful in tests. */
+declare function clearKeyCache(): void;
 /**
- * Get the current environment identifier
- *
- * @returns The current environment name
+ * Return the resolved SDK configuration for the current environment.
+ * Note: this no longer includes the ML-KEM key — fetch it via
+ * `fetchMlKemPublicKey()`.
  */
-declare function getEnvironmentName(): string;
+declare function loadConfig(baseUrl?: string): SdkConfig;
 
-export { AuthMethod, AuthenticationError, HandshakeError, HttpTransport, LogLevel, MockTransport, RpcError, SessionStateError, SessionStatus, T3nClient, T3nError, WasmError, bytesToString, createDefaultHandlers, createEthAuthInput, createLogger, createMlKemPublicKeyHandler, createOidcAuthInput, createRandomHandler, decodeWasmErrorMessage, eth_get_address, extractWasmError, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getMlKemPublicKey, getScriptVersion, loadConfig, loadWasmComponent, metamask_get_address, metamask_sign, redactSecrets, redactSecretsFromJson, setEnvironment, setGlobalLogLevel, stringToBytes, validateConfig };
+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, fetchMlKemPublicKey, generateRandomString, generateUUID, getEnvironment, getEnvironmentName, getGlobalLogLevel, getLogger, getNodeUrl, getScriptVersion, loadConfig, loadWasmComponent, metamask_get_address, metamask_sign, redactSecrets, redactSecretsFromJson, setEnvironment, setGlobalLogLevel, setNodeUrl, stringToBytes, validateConfig };
 export type { AuthInput, ClientAuth, ClientHandshake, ConfigValidationResult, Did, Environment, EthAuthInput, GuestToHostHandler, GuestToHostHandlers, HandshakeResult, JsonRpcRequest, JsonRpcResponse, Logger, OidcAuthInput, OidcCredentials, SdkConfig, SessionCrypto, SessionId, T3nClientConfig, Transport, WasmComponent, WasmNextResult };