@terminal3/t3n-sdk 0.2.1 → 0.4.0

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

@@ -26,20 +26,39 @@ export declare function metamask_get_address(): Promise<string>;
  */
 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
+ * 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(): GuestToHostHandler;
+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
+ * 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(): GuestToHostHandlers;
+export declare function createDefaultHandlers(baseUrl: string): GuestToHostHandlers;
 /**
- * Merge consumer-provided handlers with defaults (user handlers take precedence)
+ * 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): GuestToHostHandlers;
+export declare function mergeWithDefaultHandlers(handlers: GuestToHostHandlers | undefined, baseUrl: string): GuestToHostHandlers;

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

@@ -1,67 +1,48 @@
 /**
  * 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.
  */
 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');
- * ```
+ * Default node URLs per environment. Override at runtime via `setNodeUrl()`
+ * or by passing `baseUrl` to `T3nClient`.
  */
-export declare function setEnvironment(env: Environment): void;
+export 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.
  */
+export declare function setEnvironment(env: Environment): void;
 export declare function getEnvironment(): Environment;
+export 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.
  */
-export declare function loadConfig(): SdkConfig;
+export declare function setNodeUrl(url: string | null): void;
+/** Resolve the active node URL: explicit `baseUrl` > override > env default. */
+export 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`.
  */
-export declare function getMlKemPublicKey(): string;
+export declare function fetchMlKemPublicKey(baseUrl?: string): Promise<string>;
+/** Clear the cached ML-KEM public keys. Useful in tests. */
+export 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()`.
  */
-export declare function getEnvironmentName(): string;
+export declare function loadConfig(baseUrl?: string): SdkConfig;
 export type { SdkConfig, Environment, ConfigValidationResult } from "./types";
 export { validateConfig } from "./loader";

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

@@ -1,8 +1,5 @@
 /**
- * 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
  */
 import type { ConfigValidationResult } from "./types";
 /**

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

@@ -11,8 +11,8 @@ export type Environment = "local" | "staging" | "production" | "test";
 export 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;
 }

package/dist/src/index.d.ts

@@ -20,4 +20,4 @@ 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";
+export { loadConfig, fetchMlKemPublicKey, clearKeyCache, getEnvironmentName, getEnvironment, setEnvironment, setNodeUrl, getNodeUrl, NODE_URLS, validateConfig, } from "./config";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terminal3/t3n-sdk",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "type": "module",
   "description": "T3n TypeScript SDK - A minimal SDK that mirrors the server's RPC handler approach",
   "main": "dist/index.js",
@@ -22,6 +22,28 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "cross-env NODE_ENV=production T3N_SDK_SOURCEMAP=true rollup -c && pnpm run copy-wasm",
+    "build:public": "pnpm run clean && cross-env NODE_ENV=production T3N_SDK_SOURCEMAP=false rollup -c && pnpm run copy-wasm && node scripts/obfuscate-dist.js",
+    "build:watch": "cross-env NODE_ENV=development T3N_SDK_SOURCEMAP=true rollup -c -w",
+    "dev": "pnpm run build:watch",
+    "copy-wasm": "mkdir -p dist/wasm/generated && cp -r src/wasm/generated/* dist/wasm/generated/",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src --ext .ts,.tsx",
+    "lint:fix": "eslint src --ext .ts,.tsx --fix",
+    "type-check": "tsc --noEmit",
+    "clean": "rimraf dist",
+    "demo": "pnpm build && tsx demo.ts",
+    "demo:dev": "tsx demo.ts",
+    "demo:real-wasm": "tsx demo.ts",
+    "verify:pack": "node scripts/verify-pack.js",
+    "prepublishOnly": "pnpm run build:public && pnpm run verify:pack",
+    "release": "node scripts/release.js release",
+    "release:tag-only": "node scripts/release.js tag-only",
+    "release:verify-version": "node scripts/release.js verify-version"
+  },
   "keywords": [
     "t3n",
     "blockchain",
@@ -36,12 +58,12 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/Terminal-3/trinity",
-    "directory": "t3n-sdk"
+    "directory": "client/t3n-sdk"
   },
   "bugs": {
     "url": "https://github.com/Terminal-3/trinity/issues"
   },
-  "homepage": "https://github.com/Terminal-3/trinity/tree/main/t3n-sdk#readme",
+  "homepage": "https://github.com/Terminal-3/trinity/tree/main/client/t3n-sdk#readme",
   "devDependencies": {
     "@rollup/plugin-commonjs": "^25.0.7",
     "@rollup/plugin-json": "^6.1.0",
@@ -79,26 +101,5 @@
     "@bytecodealliance/jco": "^1.15.3",
     "@bytecodealliance/preview2-shim": "^0.17.5",
     "ethers": "^6.15.0"
-  },
-  "scripts": {
-    "build": "cross-env NODE_ENV=production T3N_SDK_SOURCEMAP=true rollup -c && pnpm run copy-wasm",
-    "build:public": "pnpm run clean && cross-env NODE_ENV=production T3N_SDK_SOURCEMAP=false rollup -c && pnpm run copy-wasm && node scripts/obfuscate-dist.js",
-    "build:watch": "cross-env NODE_ENV=development T3N_SDK_SOURCEMAP=true rollup -c -w",
-    "dev": "pnpm run build:watch",
-    "copy-wasm": "mkdir -p dist/wasm/generated && cp -r src/wasm/generated/* dist/wasm/generated/",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "lint": "eslint src --ext .ts,.tsx",
-    "lint:fix": "eslint src --ext .ts,.tsx --fix",
-    "type-check": "tsc --noEmit",
-    "clean": "rimraf dist",
-    "demo": "pnpm build && tsx demo.ts",
-    "demo:dev": "tsx demo.ts",
-    "demo:real-wasm": "tsx demo.ts",
-    "verify:pack": "node scripts/verify-pack.js",
-    "release": "node scripts/release.js release",
-    "release:tag-only": "node scripts/release.js tag-only",
-    "release:verify-version": "node scripts/release.js verify-version"
   }
-}
+}