@terminal3/t3n-sdk 0.10.0 → 0.12.0

package/dist/src/wasm/interface.d.ts

@@ -1,69 +1,110 @@
 /**
- * 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.
  */
-export interface ClientSessionKeys {
-    /** `encrypt_key || decrypt_key`, 64 bytes. */
-    blob: Uint8Array;
-    sid: Uint8Array;
-}
-export interface HandshakeOutcome {
-    keys: ClientSessionKeys;
-    authenticated: boolean;
-    did?: string;
-    expirySec: bigint;
+/**
+ * Result type for WASM next() operations
+ */
+export interface WasmNextResult {
+    state: Uint8Array;
+    request: Uint8Array;
 }
+/**
+ * Client handshake operations - completely opaque byte arrays only
+ */
 export interface ClientHandshake {
-    run(sid: Uint8Array, cookie: string | undefined): HandshakeOutcome;
-}
-export 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
+ */
 export 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;
-}
-export interface ServerSessionKeys {
-    c2s: Uint8Array;
-    s2c: Uint8Array;
-    sid: Uint8Array;
-}
-export 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>;
 }
-export interface ServerHandshake {
-    run(sid: Uint8Array, ciphertext: Uint8Array, cookieValue: string | undefined): ServerOutcome;
+/**
+ * Client authentication operations - completely opaque byte arrays only
+ */
+export 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
+ */
 export interface SessionCrypto {
-    encrypt(keys: Uint8Array, plaintext: Uint8Array): Uint8Array;
-    decrypt(keys: Uint8Array, ciphertext: Uint8Array): Uint8Array;
-}
-export interface Validation {
-    authenticated: boolean;
-    did?: string;
-    exp: bigint;
-}
-export 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.
+ */
 export 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;
 }

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

@@ -1,73 +1,43 @@
 /**
- * WASM Component Loader — async direct-call shape.
+ * WASM Component Loader
  *
- * 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:
- *
- *   - `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.
  */
 import { WasmComponent } from "./interface";
 import { Logger } from "../utils/logger";
-/**
- * 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`).
- */
-export 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
  */
 export 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'
+ * });
+ * ```
  */
 export declare function loadWasmComponent(config?: WasmLoadConfig): Promise<WasmComponent>;
+/**
+ * Load the real T3n WASM component
+ *
+ * @param logger - Logger instance for WASM operations
+ * @returns Promise that resolves to the initialized WASM component
+ */
+export declare function loadRealWasmComponent(logger: Logger): Promise<WasmComponent>;

package/dist/wasm/generated/interfaces/component-session-client-auth.d.ts

@@ -0,0 +1,12 @@
+/** @module Interface component:session/client-auth@0.1.0 **/
+export function next(state: State | undefined, action: HostToGuest): NewState;
+export function finish(state: State): Did;
+export type GuestToHost = Uint8Array;
+export type State = Uint8Array;
+export type HostToGuest = Uint8Array;
+export type Did = Uint8Array;
+export type Error = Uint8Array;
+export interface NewState {
+  state: State,
+  request: GuestToHost,
+}

package/dist/wasm/generated/interfaces/component-session-client-handshake.d.ts

@@ -0,0 +1,12 @@
+/** @module Interface component:session/client-handshake@0.1.0 **/
+export function next(state: State | undefined, action: HostToGuest): NewState;
+export function finish(state: State): SessionState;
+export type GuestToHost = Uint8Array;
+export type State = Uint8Array;
+export type HostToGuest = Uint8Array;
+export type SessionState = Uint8Array;
+export type Error = Uint8Array;
+export interface NewState {
+  state: State,
+  request: GuestToHost,
+}

package/dist/wasm/generated/interfaces/component-session-cookie.d.ts

@@ -0,0 +1,8 @@
+/** @module Interface component:session/cookie@0.1.0 **/
+export function validate(cookieValue: string, teeAddress: Uint8Array, nowSec: bigint): Validation;
+export interface Validation {
+  authenticated: boolean,
+  did?: string,
+  exp: bigint,
+}
+export type Error = Uint8Array;

package/dist/wasm/generated/interfaces/component-session-session.d.ts

@@ -0,0 +1,7 @@
+/** @module Interface component:session/session@0.1.0 **/
+export function encrypt(session: Session, plaintext: Plaintext): Ciphertext;
+export function decrypt(session: Session, ciphertext: Ciphertext): Plaintext;
+export type Error = Uint8Array;
+export type Session = Uint8Array;
+export type Plaintext = Uint8Array;
+export type Ciphertext = Uint8Array;

package/dist/wasm/generated/session.d.ts

@@ -1,88 +1,11 @@
 // world root:component/root
-import type * as HostSessionInterfacesContractDispatch from './interfaces/host-session-interfaces-contract-dispatch.js'; // host:session-interfaces/contract-dispatch@1.0.0
-import type * as HostSessionInterfacesEntropy from './interfaces/host-session-interfaces-entropy.js'; // host:session-interfaces/entropy@1.0.0
-import type * as HostSessionInterfacesEthSigner from './interfaces/host-session-interfaces-eth-signer.js'; // host:session-interfaces/eth-signer@1.0.0
-import type * as HostSessionInterfacesKem from './interfaces/host-session-interfaces-kem.js'; // host:session-interfaces/kem@1.0.0
-import type * as HostSessionInterfacesOidcClient from './interfaces/host-session-interfaces-oidc-client.js'; // host:session-interfaces/oidc-client@1.0.0
-import type * as HostSessionInterfacesOidc from './interfaces/host-session-interfaces-oidc.js'; // host:session-interfaces/oidc@1.0.0
-import type * as HostSessionInterfacesSessionOps from './interfaces/host-session-interfaces-session-ops.js'; // host:session-interfaces/session-ops@1.0.0
-import type * as HostSessionInterfacesTransport from './interfaces/host-session-interfaces-transport.js'; // host:session-interfaces/transport@1.0.0
-import type * as WasiCliEnvironment from './interfaces/wasi-cli-environment.js'; // wasi:cli/environment@0.2.9
-import type * as WasiCliExit from './interfaces/wasi-cli-exit.js'; // wasi:cli/exit@0.2.9
-import type * as WasiCliStderr from './interfaces/wasi-cli-stderr.js'; // wasi:cli/stderr@0.2.9
-import type * as WasiIoError from './interfaces/wasi-io-error.js'; // wasi:io/error@0.2.9
-import type * as WasiIoStreams from './interfaces/wasi-io-streams.js'; // wasi:io/streams@0.2.9
-import type * as WasiRandomRandom from './interfaces/wasi-random-random.js'; // wasi:random/random@0.2.9
-import type * as TeeSessionClientHandshake from './interfaces/tee-session-client-handshake.js'; // tee:session/client-handshake@1.0.0
-import type * as TeeSessionClientAuth from './interfaces/tee-session-client-auth.js'; // tee:session/client-auth@1.0.0
-import type * as TeeSessionServerHandshake from './interfaces/tee-session-server-handshake.js'; // tee:session/server-handshake@1.0.0
-import type * as TeeSessionServerAuth from './interfaces/tee-session-server-auth.js'; // tee:session/server-auth@1.0.0
-import type * as TeeSessionServerAdmin from './interfaces/tee-session-server-admin.js'; // tee:session/server-admin@1.0.0
-import type * as TeeSessionServerWebhook from './interfaces/tee-session-server-webhook.js'; // tee:session/server-webhook@1.0.0
-import type * as TeeSessionSessionCrypto from './interfaces/tee-session-session-crypto.js'; // tee:session/session-crypto@1.0.0
-import type * as TeeSessionCookie from './interfaces/tee-session-cookie.js'; // tee:session/cookie@1.0.0
-export interface ImportObject {
-  'host:session-interfaces/contract-dispatch@1.0.0': typeof HostSessionInterfacesContractDispatch,
-  'host:session-interfaces/entropy@1.0.0': typeof HostSessionInterfacesEntropy,
-  'host:session-interfaces/eth-signer@1.0.0': typeof HostSessionInterfacesEthSigner,
-  'host:session-interfaces/kem@1.0.0': typeof HostSessionInterfacesKem,
-  'host:session-interfaces/oidc-client@1.0.0': typeof HostSessionInterfacesOidcClient,
-  'host:session-interfaces/oidc@1.0.0': typeof HostSessionInterfacesOidc,
-  'host:session-interfaces/session-ops@1.0.0': typeof HostSessionInterfacesSessionOps,
-  'host:session-interfaces/transport@1.0.0': typeof HostSessionInterfacesTransport,
-  'wasi:cli/environment@0.2.9': typeof WasiCliEnvironment,
-  'wasi:cli/exit@0.2.9': typeof WasiCliExit,
-  'wasi:cli/stderr@0.2.9': typeof WasiCliStderr,
-  'wasi:io/error@0.2.9': typeof WasiIoError,
-  'wasi:io/streams@0.2.9': typeof WasiIoStreams,
-  'wasi:random/random@0.2.9': typeof WasiRandomRandom,
-}
-export interface Root {
-  'tee:session/client-handshake@1.0.0': typeof TeeSessionClientHandshake,
-  clientHandshake: typeof TeeSessionClientHandshake,
-  'tee:session/client-auth@1.0.0': typeof TeeSessionClientAuth,
-  clientAuth: typeof TeeSessionClientAuth,
-  'tee:session/server-handshake@1.0.0': typeof TeeSessionServerHandshake,
-  serverHandshake: typeof TeeSessionServerHandshake,
-  'tee:session/server-auth@1.0.0': typeof TeeSessionServerAuth,
-  serverAuth: typeof TeeSessionServerAuth,
-  'tee:session/server-admin@1.0.0': typeof TeeSessionServerAdmin,
-  serverAdmin: typeof TeeSessionServerAdmin,
-  'tee:session/server-webhook@1.0.0': typeof TeeSessionServerWebhook,
-  serverWebhook: typeof TeeSessionServerWebhook,
-  'tee:session/session-crypto@1.0.0': typeof TeeSessionSessionCrypto,
-  sessionCrypto: typeof TeeSessionSessionCrypto,
-  'tee:session/cookie@1.0.0': typeof TeeSessionCookie,
-  cookie: typeof TeeSessionCookie,
-}
-
-/**
-* Instantiates this component with the provided imports and
-* returns a map of all the exports of the component.
-*
-* This function is intended to be similar to the
-* `WebAssembly.instantiate` function. The second `imports`
-* argument is the "import object" for wasm, except here it
-* uses component-model-layer types instead of core wasm
-* integers/numbers/etc.
-*
-* The first argument to this function, `getCoreModule`, is
-* used to compile core wasm modules within the component.
-* Components are composed of core wasm modules and this callback
-* will be invoked per core wasm module. The caller of this
-* function is responsible for reading the core wasm module
-* identified by `path` and returning its compiled
-* `WebAssembly.Module` object. This would use `compileStreaming`
-* on the web, for example.
-*/
-export function instantiate(
-getCoreModule: (path: string) => WebAssembly.Module,
-imports: ImportObject,
-instantiateCore?: (module: WebAssembly.Module, imports: Record<string, any>) => WebAssembly.Instance
-): Root;
-export function instantiate(
-getCoreModule: (path: string) => WebAssembly.Module | Promise<WebAssembly.Module>,
-imports: ImportObject,
-instantiateCore?: (module: WebAssembly.Module, imports: Record<string, any>) => WebAssembly.Instance | Promise<WebAssembly.Instance>
-): Root | Promise<Root>;
-
+export type * as WasiCliEnvironment029 from './interfaces/wasi-cli-environment.js'; // import wasi:cli/environment@0.2.9
+export type * as WasiCliExit029 from './interfaces/wasi-cli-exit.js'; // import wasi:cli/exit@0.2.9
+export type * as WasiCliStderr029 from './interfaces/wasi-cli-stderr.js'; // import wasi:cli/stderr@0.2.9
+export type * as WasiIoError029 from './interfaces/wasi-io-error.js'; // import wasi:io/error@0.2.9
+export type * as WasiIoStreams029 from './interfaces/wasi-io-streams.js'; // import wasi:io/streams@0.2.9
+export type * as WasiRandomRandom029 from './interfaces/wasi-random-random.js'; // import wasi:random/random@0.2.9
+export * as clientAuth from './interfaces/component-session-client-auth.js'; // export component:session/client-auth@0.1.0
+export * as clientHandshake from './interfaces/component-session-client-handshake.js'; // export component:session/client-handshake@0.1.0
+export * as session from './interfaces/component-session-session.js'; // export component:session/session@0.1.0
+export * as cookie from './interfaces/component-session-cookie.js'; // export component:session/cookie@0.1.0