@fhevm/sdk 1.1.0-alpha.5 → 1.1.0-alpha.6

package/core/modules/encrypt/module/init-p.ts

@@ -6,20 +6,112 @@ import type {
   TfheModuleInfo,
 } from '../types.js';
 import type { TfheLibApi } from '../../../../wasm/tfhe/TfheApi.js';
-import type { TfheAssetMetadata, TfheVersion } from '../../../../wasm/tfhe/loadTfheLib.js';
+import type { TfheAssetMetadata, TfheAssets, TfheVersion } from '../../../../wasm/tfhe/loadTfheLib.js';
+import type { WasmAssetLoadMode } from '../../../types/wasmAssets.js';
 import { isomorphicCompileVerifiedWasm, isomorphicCompileWasmFromBase64 } from '../../../base/wasm.js';
-import { isBlobWorkerSupported, isBrowserLike } from '../../../base/isomorphicWorker.js';
+import { isBlobWorkerSupported } from '../../../base/isomorphicWorker.js';
+import { isBrowserLike } from '../../../base/environment.js';
 import { threads } from 'wasm-feature-detect';
 import { assertIsFhevmRuntime } from '../../../runtime/CoreFhevmRuntime-p.js';
-// Pure JS file (not compiled by tsc) — provides cross-platform base URL
-// for resolving WASM paths. Uses import.meta.url in ESM, __filename in CJS.
-import { wasmBaseUrl } from '../../../../wasm/wasmBaseUrl.js';
 import { loadTfheLib, loadTfheWasmBase64, tfheAssetsWithVersion } from '../../../../wasm/tfhe/loadTfheLib.js';
+import { isomorphicFileUrlExists } from '../../../base/isomorphicFs.js';
+
+////////////////////////////////////////////////////////////////////////////////
+
+/**
+ * TFHE asset loading rules
+ *
+ * 1. Asset URL resolution
+ *    - If `locateFile` is provided:
+ *      - `URL` return value: that asset has a URL.
+ *      - `null` / `undefined`: that asset has no URL and must use embedded base64
+ *        if the selected load path allows it.
+ *      - Any other value: invalid `locateFile` result.
+ *      - Each asset is resolved independently; advanced callers may intentionally
+ *        mix URL and embedded-base64 asset loading.
+ *      - User-provided URLs are not checked for on-disk existence, even when
+ *        they use the `file:` protocol. They are explicit caller input and fail
+ *        later during read/fetch/SHA verification if wrong.
+ *    - If `locateFile` is not provided:
+ *      - Node: derive default `file://` URLs as an all-or-none set. If any
+ *        auto-derived file is missing, clear all TFHE URLs and fall back to
+ *        embedded base64. This preserves predictable behavior for unexpected
+ *        bundler/package relocation.
+ *      - Browser: no asset URL; use embedded base64 paths.
+ *
+ * 2. WASM module loading
+ *    - If the WASM asset has a URL: load, SHA-verify, and compile from that URL.
+ *    - If the WASM asset has no URL: compile from embedded base64.
+ *    - `wasmAssetLoadMode` does not control WASM module loading.
+ *
+ * 3. Worker script loading
+ *    - If single-threaded: no worker is loaded.
+ *    - If threaded: `wasmAssetLoadMode` controls how the worker script is loaded.
+ *    - The worker URL only makes a URL-backed worker mode possible; it does not
+ *      force the worker to use that URL.
+ *
+ * 4. Worker mode precedence
+ *    - `embedded-base64`: ignore any worker URL and use embedded worker source.
+ *    - `verified-blob`: require worker URL, SHA-verify fetched bytes, execute those bytes.
+ *    - `precheck-direct-url`: require worker URL, SHA precheck, then execute URL directly.
+ *    - `trusted-direct-url`: require worker URL, execute URL directly without SDK verification.
+ *    - `auto`: if worker URL exists, try `verified-blob`; on non-SHA failure, fall back
+ *      to embedded base64. If no worker URL exists, use embedded base64.
+ *
+ * 5. Failure
+ *    - Explicit URL worker modes with no worker URL: throw.
+ *    - SHA mismatch: always throw, never fall back.
+ *    - Explicit worker-mode runtime failures are surfaced by `startWorkers.js`.
+ *
+ * 6. Degradation:
+ *    - Auto-derived Node URLs are best effort only. If either the WASM or worker
+ *      file is missing on disk, both URLs are cleared and the SDK falls back to the
+ *      no-URL paths.
+ *    - With no WASM URL, the WASM module compiles from embedded base64.
+ *    - With no worker URL, `auto` and `embedded-base64` worker modes use embedded
+ *      worker source; explicit URL worker modes throw.
+ *    - If threads are unsupported, unavailable, or configured with zero threads,
+ *      TFHE runs single-threaded.
+ *    - If `auto` mode would need a blob/eval worker but blob/eval workers are
+ *      unavailable, TFHE runs single-threaded.
+ *    - Single-threaded TFHE never loads a worker; WASM still loads from its resolved
+ *      URL or embedded base64.
+ *
+ * 7. Security model:
+ *    - Mixed transports are allowed for user-resolved assets when chosen explicitly.
+ *    - External WASM URLs are SHA-verified before compilation.
+ *    - `verified-blob` verifies and executes the exact worker bytes.
+ *    - `precheck-direct-url` and `trusted-direct-url` intentionally trust the runtime
+ *      worker URL fetch semantics described in `startWorkers.js`.
+ *
+ * Turbopack / relocated package behavior:
+ *    - In Node, without `locateFile`, the SDK derives default `file://` URLs from
+ *      the package's wasm base URL.
+ *    - Some bundlers can relocate/package the JS in a way that makes those derived
+ *      `file://` URLs point to paths that do not exist on disk.
+ *    - Passing such URLs to the WASM or worker loaders would fail at runtime instead
+ *      of using the embedded assets.
+ *    - To avoid that, auto-derived Node URLs are checked as an all-or-none set before
+ *      loading: if either the WASM or worker file is missing, both URLs are cleared.
+ *    - Once cleared, WASM loads from embedded base64 and worker loading follows
+ *      `wasmAssetLoadMode` with no worker URL available.
+ *    - User-provided `locateFile` URLs, including `file:` URLs, are not probed here;
+ *      they are explicit caller input and fail loud later if wrong.
+ */
+
+////////////////////////////////////////////////////////////////////////////////
+
+function _requiresAssetUrl(wasmAssetLoadMode: WasmAssetLoadMode | undefined): boolean {
+  return wasmAssetLoadMode !== undefined && wasmAssetLoadMode !== 'auto' && wasmAssetLoadMode !== 'embedded-base64';
+}
 
 ////////////////////////////////////////////////////////////////////////////////
 
 // (Node only) Path relative to src/wasm/ where wasmBaseUrl is anchored
-const nodeDefaultLocateFile = (file: string): URL => {
+const nodeDefaultLocateFile = async (file: string): Promise<URL> => {
+  // Pure JS file (not compiled by tsc) — provides cross-platform base URL
+  // for resolving WASM paths. Uses import.meta.url in ESM, __filename in CJS.
+  const { wasmBaseUrl } = await import('../../../../wasm/wasmBaseUrl.js');
   return new URL(`./tfhe/${file}`, wasmBaseUrl);
 };
 
@@ -34,20 +126,106 @@ type TfheLibInitAsyncParameters = {
   readonly num_threads?: number;
 };
 
+type TfheAssetResolution = 'user' | 'node' | 'none';
 type ResolvedTfheAsset = TfheAssetMetadata & {
   readonly url: URL | undefined;
+  readonly resolution: TfheAssetResolution;
 };
 
-function _resolveTfheAsset(asset: TfheAssetMetadata, locateFile: FhevmRuntimeConfig['locateFile']): ResolvedTfheAsset {
+type ResolvedTfheAssets = {
+  readonly wasm: ResolvedTfheAsset;
+  readonly worker: ResolvedTfheAsset;
+};
+
+async function _resolveSingleTfheAsset(
+  asset: TfheAssetMetadata,
+  locateFile: FhevmRuntimeConfig['locateFile'],
+): Promise<ResolvedTfheAsset> {
   let url: URL | undefined;
+  let resolution: TfheAssetResolution = 'none';
 
   if (locateFile !== undefined) {
-    url = locateFile(asset.filename);
+    const located = locateFile(asset.filename) as unknown;
+    if (located === null || located === undefined) {
+      url = undefined;
+    } else if (located instanceof URL) {
+      url = located;
+    } else {
+      throw new TypeError(
+        `Invalid locateFile result for TFHE asset '${asset.filename}': expected URL, null, or undefined.`,
+      );
+    }
+    resolution = 'user';
   } else if (!isBrowserLike()) {
-    url = nodeDefaultLocateFile(asset.localRelativePath);
+    url = await nodeDefaultLocateFile(asset.localRelativePath);
+    resolution = 'node';
   }
 
-  return Object.freeze({ ...asset, url });
+  return Object.freeze({ ...asset, url, resolution });
+}
+
+/**
+ * Resolves TFHE asset URLs for wasm and worker scripts.
+ *
+ * With user `locateFile` resolution, each asset is independent: returning a URL
+ * opts that asset into URL loading, while returning null/undefined opts that asset
+ * into embedded base64 when its selected load path supports it.
+ *
+ * For `'node'` resolution (auto-derived `file://` URLs), every URL is validated
+ * on disk: if any one is missing — e.g. a bundler such as Turbopack relocated the
+ * package and the derived `file://ROOT/...` path no longer exists — then ALL URLs
+ * are cleared so the whole set falls back to embedded base64 consistently.
+ *
+ * `'none'` has no URL to validate.
+ */
+async function _resolveTfheAssets(
+  assets: TfheAssets,
+  locateFile: FhevmRuntimeConfig['locateFile'],
+): Promise<{ readonly wasm: ResolvedTfheAsset; readonly worker: ResolvedTfheAsset }> {
+  let wasm = await _resolveSingleTfheAsset(assets.wasm, locateFile);
+  let worker = await _resolveSingleTfheAsset(assets.worker, locateFile);
+
+  // Only auto-derived ('node') file:// URLs need on-disk validation; the mode is
+  // shared across all assets, so checking one is enough to know the set's mode.
+  if (wasm.resolution === 'node') {
+    const allExist = (
+      await Promise.all([isomorphicFileUrlExists(wasm.url), isomorphicFileUrlExists(worker.url)])
+    ).every(Boolean);
+    if (!allExist) {
+      wasm = Object.freeze({ ...wasm, url: undefined });
+      worker = Object.freeze({ ...worker, url: undefined });
+    }
+  }
+
+  return { wasm, worker };
+}
+
+/**
+ * Emits debug traces describing how the TFHE assets were resolved (user-provided
+ * `locateFile`, auto-derived on-disk path, embedded base64, or bundler-relocated
+ * fallback). Pure logging — no control flow.
+ */
+function _logResolvedTfheAssets(resolvedAssets: ResolvedTfheAssets, logger: FhevmRuntimeConfig['logger']): void {
+  const { wasm, worker } = resolvedAssets;
+  if (wasm.resolution === 'user') {
+    logger?.debug(`resolve tfhe wasm filename using 'locateFile' function: ${wasm.filename} -> url: ${wasm.url}`);
+    logger?.debug(`resolve tfhe worker filename using 'locateFile' function: ${worker.filename} -> url: ${worker.url}`);
+  } else if (wasm.resolution === 'node') {
+    if (wasm.url === undefined) {
+      // Auto-derived assets were missing on disk (e.g. a bundler such as Turbopack
+      // relocated the package) and were cleared by _resolveTfheAssets -> base64.
+      logger?.debug(
+        `tfhe auto-derived assets not found on disk (bundler relocation?); using embedded base64 ` +
+          `(wasm: ${wasm.localRelativePath}, worker: ${worker.localRelativePath})`,
+      );
+    } else {
+      logger?.debug(`resolve tfhe wasm local path: ${wasm.localRelativePath} -> url: ${wasm.url}`);
+      logger?.debug(`resolve tfhe worker local path: ${worker.localRelativePath} -> url: ${worker.url}`);
+    }
+  } else {
+    // 'none': browser zero-config (no 'locateFile', not Node) -> embedded base64.
+    logger?.debug(`resolve tfhe assets using embedded base64 (browser, no 'locateFile')`);
+  }
 }
 
 ////////////////////////////////////////////////////////////////////////////////
@@ -56,9 +234,8 @@ function _resolveTfheAsset(asset: TfheAssetMetadata, locateFile: FhevmRuntimeCon
 
 type ResolvedTfheModuleConfig = {
   readonly version: TfheVersion;
-  readonly worker: ResolvedTfheAsset;
+  readonly assets: ResolvedTfheAssets;
   readonly wasmAssetLoadMode: FhevmRuntimeConfig['wasmAssetLoadMode'];
-  readonly wasm: ResolvedTfheAsset;
   /* if `true`, then `numberOfThreads` is 0, if `false` then `numberOfThreads` > 0 */
   readonly singleThread: boolean;
   readonly numberOfThreads: number;
@@ -102,54 +279,88 @@ async function _getOrResolveTfheModuleConfig(
 }
 
 /**
- * @internal
- * Resolves user-provided {@link FhevmRuntimeConfig} into a fully resolved config
- * (thread count, worker URL, WASM URL). Must be called before WASM initialization.
+ * Fails fast on impossible / contradictory TFHE configurations, before any
+ * wasm or worker work begins.
+ *
+ * Only genuinely unsatisfiable configs throw here. Recoverable situations —
+ * missing SAB/thread support, or `auto` mode without blob/eval worker support —
+ * degrade to single-threaded later. Single-threaded TFHE needs no worker, and
+ * wasm still loads from its resolved URL or embedded base64. Do not add
+ * degradable cases to this function.
  */
-async function _resolveTfheModuleConfig(
-  parameters: FhevmRuntimeConfig,
-  version: TfheVersion,
-): Promise<ResolvedTfheModuleConfig> {
-  const {
-    locateFile,
-    wasmAssetLoadMode,
-    singleThread: singleThreadConfig,
-    numberOfThreads: numberOfThreadsConfig,
-  } = parameters;
+function _assertSatisfiableTfheConfig(resolvedAssets: ResolvedTfheAssets, parameters: FhevmRuntimeConfig): void {
+  const { wasmAssetLoadMode, numberOfThreads } = parameters;
+  const { wasm, worker } = resolvedAssets;
 
-  let singleThread = false;
-  if (singleThreadConfig !== undefined) {
-    singleThread = singleThreadConfig;
+  if (wasm.resolution !== worker.resolution) {
+    // internal error
+    throw new Error('Internal error');
   }
 
-  const canUseBlob = await isBlobWorkerSupported();
+  // (1) Auto-derived Node URLs must remain all-or-none. User `locateFile`
+  //     resolution may intentionally mix URL and embedded-base64 assets, but a
+  //     partial Node file set means the package/bundler layout is inconsistent.
+  if (wasm.resolution === 'node') {
+    if ((wasm.url === undefined) !== (worker.url === undefined)) {
+      throw new Error(
+        `Inconsistent auto-derived TFHE asset URLs: Node resolution must resolve both the wasm and worker assets, or neither ` +
+          `(wasm: ${wasm.url ? 'url' : 'none'}, worker: ${worker.url ? 'url' : 'none'}).`,
+      );
+    }
+  }
 
-  const assets = tfheAssetsWithVersion(version);
-  const wasm = _resolveTfheAsset(assets.wasm, locateFile);
-  const worker = _resolveTfheAsset(assets.worker, locateFile);
+  // (2) A URL-requiring worker mode (verified-blob / precheck-direct-url /
+  //     trusted-direct-url) was selected, but no worker URL is available.
+  //     We refuse to silently downgrade an explicit URL/verification choice to base64.
+  if (worker.url === undefined && _requiresAssetUrl(wasmAssetLoadMode)) {
+    throw new Error(
+      `wasmAssetLoadMode '${wasmAssetLoadMode}' requires a resolvable worker URL, but none is available. ` +
+        `Use 'auto' or 'embedded-base64', or provide a worker URL via 'locateFile'.`,
+    );
+  }
 
-  if (locateFile !== undefined) {
-    parameters.logger?.debug(`resolve tfhe wasm filename: ${wasm.filename} -> url: ${wasm.url}`);
-    parameters.logger?.debug(`resolve tfhe worker filename: ${worker.filename} -> url: ${worker.url}`);
-  } else {
-    /*
-      if run in Node only, use defaultLocateFile!
-    */
-    if (isBrowserLike()) {
-      if (!canUseBlob) {
-        throw new Error('Missing locate file function');
-      }
-    } else {
-      parameters.logger?.debug(`resolve tfhe wasm local path: ${wasm.localRelativePath} -> url: ${wasm.url}`);
-      parameters.logger?.debug(`resolve tfhe worker local path: ${worker.localRelativePath} -> url: ${worker.url}`);
-    }
+  // (3) Invalid thread count: must be a non-negative integer when provided.
+  //     (Negative / NaN would otherwise be silently coerced to single-threaded,
+  //     hiding the caller's mistake.)
+  if (numberOfThreads !== undefined && (!Number.isInteger(numberOfThreads) || numberOfThreads < 0)) {
+    throw new Error(`numberOfThreads must be a non-negative integer, received: ${String(numberOfThreads)}`);
   }
+}
+
+////////////////////////////////////////////////////////////////////////////////
 
-  let numberOfThreads: number | undefined;
+type ResolvedThreadConfig = {
+  readonly singleThread: boolean;
+  readonly numberOfThreads: number;
+  readonly supportsThreads: boolean | undefined;
+};
+
+/**
+ * Resolves the effective threading config. Degrades to single-threaded when
+ * multi-threading is requested but cannot run — no SharedArrayBuffer/COOP-COEP
+ * support, or no way to spawn a worker. Never throws: single-threaded always works
+ * (it needs no worker, and the wasm still loads via URL or embedded base64).
+ */
+async function _resolveThreadConfig(args: {
+  readonly preferredSingleThread: boolean;
+  readonly numberOfThreadsConfig: number | undefined;
+  readonly wasmAssetLoadMode: WasmAssetLoadMode;
+  readonly canUseBlob: boolean;
+  readonly logger: FhevmRuntimeConfig['logger'];
+}): Promise<ResolvedThreadConfig> {
+  const { preferredSingleThread, numberOfThreadsConfig, wasmAssetLoadMode, canUseBlob, logger } = args;
+
+  let singleThread = preferredSingleThread;
+  let numberOfThreads = 0;
   let supportsThreads: boolean | undefined;
 
   if (!singleThread) {
-    numberOfThreads = numberOfThreadsConfig ?? navigator.hardwareConcurrency; // Node 21+
+    // `navigator` is absent in some edge runtimes (and Node <21); guard it so a
+    // missing global degrades to single-threaded (0) instead of a ReferenceError.
+    // This single-threaded fallback is also the only viable mode on edge anyway:
+    // Cloudflare Workers and Vercel Edge support neither Web Workers (`new Worker`)
+    // nor `node:worker_threads`, so the worker pool could not be spawned there.
+    numberOfThreads = numberOfThreadsConfig ?? (typeof navigator !== 'undefined' ? navigator.hardwareConcurrency : 0);
 
     if (numberOfThreads > 0) {
       // SharedArrayBuffer requires COOP/COEP headers in browsers.
@@ -163,28 +374,115 @@ async function _resolveTfheModuleConfig(
         );
         singleThread = true;
         numberOfThreads = 0;
+      } else if (!canUseBlob && wasmAssetLoadMode === 'auto') {
+        // Threads are supported, but the selected mode spawns its worker from code
+        // (embedded-base64 / verified-blob / auto — blob in browser, eval in Node),
+        // and blob/eval workers are unavailable here. The direct-url modes use
+        // `new Worker(url)` and don't need blob support, so they're exempt.
+        // Degrade to single-threaded (single-threaded TFHE needs no worker).
+        logger?.warn?.(
+          `Cannot spawn a '${wasmAssetLoadMode}' worker (blob/eval workers unavailable); running single-threaded.`,
+        );
+        singleThread = true;
+        numberOfThreads = 0;
       }
     } else {
       singleThread = true;
       numberOfThreads = 0;
     }
-  } else {
-    numberOfThreads = 0;
   }
 
+  return { singleThread, numberOfThreads, supportsThreads };
+}
+
+/**
+ * @internal
+ * Resolves user-provided {@link FhevmRuntimeConfig} into a fully resolved config
+ * (thread count, worker URL, WASM URL). Must be called before WASM initialization.
+ */
+async function _resolveTfheModuleConfig(
+  parameters: FhevmRuntimeConfig,
+  version: TfheVersion,
+): Promise<ResolvedTfheModuleConfig> {
+  const {
+    locateFile,
+    wasmAssetLoadMode: requestedWasmAssetLoadMode,
+    singleThread: preferredSingleThread,
+    numberOfThreads: numberOfThreadsConfig,
+  } = parameters;
+
+  const wasmAssetLoadMode = requestedWasmAssetLoadMode ?? 'auto';
+  const canUseBlob = await isBlobWorkerSupported();
+
+  const assets = tfheAssetsWithVersion(version);
+
+  const resolvedAssets = await _resolveTfheAssets(assets, locateFile);
+
+  // ── TFHE asset resolution & degradation rules ───────────────────────────────
+  //
+  // POLICY: user-resolved assets may intentionally mix transports (e.g. URL
+  // wasm + embedded worker). Auto-derived Node assets remain all-or-none because
+  // missing local files are unexpected and usually mean bundler/package relocation.
+  //
+  // Asset URL resolution:
+  //
+  //   locateFile  runtime / on-disk      resolution  asset url       policy
+  //   ----------  ---------------------  ----------  --------------  --------------------------
+  //   provided    any                    'user'      per asset       caller controls each asset
+  //   none        Node, files present    'node'      file://…        all TFHE URLs kept
+  //   none        Node, files missing *  'node'      undefined       all TFHE URLs cleared
+  //   none        browser                'none'      undefined       embedded base64
+  //   * e.g. a bundler (Turbopack) relocated the package; URLs cleared by _resolveTfheAssets.
+  //
+  // Worker load mode (wasmAssetLoadMode) requirements:
+  //
+  //   mode                 needs URL?  needs blob/eval worker (canUseBlob)?
+  //   -------------------  ----------  ------------------------------------
+  //   embedded-base64      no          yes
+  //   verified-blob        yes         yes
+  //   auto                 no          yes   (verified-blob if URL, else embedded)
+  //   precheck-direct-url  yes         no    (new Worker(url))
+  //   trusted-direct-url   yes         no    (new Worker(url))
+  //
+  // Failure / degradation (in order):
+  //   1. explicit URL mode but no URL is available       -> throw (unsatisfiable config)
+  //   2. threads requested but unsupported (no SAB)      -> degrade to single-threaded
+  //   3. auto mode cannot spawn blob/eval workers        -> degrade to single-threaded
+  //
+  // Explicit worker modes are not downgraded here:
+  // startWorkers.js owns their worker-loading behavior and surfaces their failures.
+  // Single-threaded never needs a worker; wasm still loads (URL or embedded base64).
+
+  // Early validation: throw on impossible/contradictory configs. Recoverable
+  // cases (no worker source, no thread support) degrade later — they are NOT here.
+  _assertSatisfiableTfheConfig(resolvedAssets, parameters);
+
+  _logResolvedTfheAssets(resolvedAssets, parameters.logger);
+
+  const { singleThread, numberOfThreads, supportsThreads } = await _resolveThreadConfig({
+    preferredSingleThread: preferredSingleThread ?? false,
+    numberOfThreadsConfig,
+    wasmAssetLoadMode,
+    canUseBlob,
+    logger: parameters.logger,
+  });
+
   const tfheLib = await loadTfheLib(version);
+
   tfheLib.setWorkerUrlConfig({
-    workerUrl: worker.url,
+    workerUrl: resolvedAssets.worker.url,
     wasmAssetLoadMode,
+    // Single source of truth for browser-vs-Node, resolved on the main thread
+    // (robust to bundler `process` shims) — the worker bootstrap no longer detects it.
+    isBrowserLike: isBrowserLike(),
     logger: parameters.logger,
   });
 
   const cfg = {
     version,
     numberOfThreads,
-    worker,
+    assets: resolvedAssets,
     wasmAssetLoadMode,
-    wasm,
     singleThread,
     logger: parameters.logger,
     supportsThreads,
@@ -270,20 +568,27 @@ export async function initTfheModule(runtime: FhevmRuntime, parameters: InitTfhe
   return cachedTfheModulePromise;
 }
 
-async function _initTfheModule(cfg: ResolvedTfheModuleConfig): Promise<TfheLibApi> {
-  const tfheLib = await loadTfheLib(cfg.version);
-
-  // Compile WASM module (see matrix in types.ts)
+async function _compileWasmModule(cfg: ResolvedTfheModuleConfig): Promise<WebAssembly.Module> {
   let wasmModule;
-  if (cfg.wasm.url !== undefined) {
-    cfg.logger?.debug(`compile verified wasm at: ${cfg.wasm.url}`);
-    wasmModule = await isomorphicCompileVerifiedWasm(cfg.wasm.url, cfg.wasm.sha256);
+
+  if (cfg.assets.wasm.url !== undefined) {
+    cfg.logger?.debug(`compile verified wasm at: ${cfg.assets.wasm.url}`);
+    wasmModule = await isomorphicCompileVerifiedWasm(cfg.assets.wasm.url, cfg.assets.wasm.sha256);
   } else {
     const { tfheWasmBase64, tfheWasmBase64CompressionFormat } = await loadTfheWasmBase64(cfg.version);
     cfg.logger?.debug(`compile wasm from embedded base64 (compression:${tfheWasmBase64CompressionFormat ?? 'none'})`);
     wasmModule = await isomorphicCompileWasmFromBase64(tfheWasmBase64, tfheWasmBase64CompressionFormat);
   }
 
+  return wasmModule;
+}
+
+async function _initTfheModule(cfg: ResolvedTfheModuleConfig): Promise<TfheLibApi> {
+  const tfheLib = await loadTfheLib(cfg.version);
+
+  // 1. Compile WASM module
+  const wasmModule = await _compileWasmModule(cfg);
+
   const input: TfheLibInitAsyncParameters = { module_or_path: wasmModule };
 
   // 2. Load and instantiate the TFHE WASM binary
@@ -308,10 +613,10 @@ async function _initTfheModule(cfg: ResolvedTfheModuleConfig): Promise<TfheLibAp
   moduleInfoByVersion.set(
     cfg.version,
     Object.freeze({
-      wasmUrl: cfg.wasm.url ? new URL(cfg.wasm.url) : undefined,
+      wasmUrl: cfg.assets.wasm.url ? new URL(cfg.assets.wasm.url) : undefined,
       version: wasmInfo.version,
       name: wasmInfo.name,
-      workerUrl: cfg.worker.url ? new URL(cfg.worker.url) : undefined,
+      workerUrl: cfg.assets.worker.url ? new URL(cfg.assets.worker.url) : undefined,
       numberOfThreads: cfg.singleThread ? 0 : cfg.numberOfThreads,
       threadsAvailable: cfg.supportsThreads,
       memory,

package/core/runtime/HyperWasmSolver-p.ts

@@ -87,8 +87,8 @@ const HYPER_WASM_SOLVER_CONFIG = {
       // pubKeyCrs.version <= 1.5.x (ex: mainnet 1.4.0-alpha.3)
       pubKeyCrs: { version: '1.6.0', comparator: 'lt' },
       tfhe: {
-        canonical: '1.6.1',
-        compatible: ['1.5.3', '1.6.1'],
+        canonical: '1.6.2',
+        compatible: ['1.5.3', '1.6.2'],
       },
       kms: {
         canonical: '0.13.20-0',
@@ -101,8 +101,8 @@ const HYPER_WASM_SOLVER_CONFIG = {
       // pubKeyCrs.version >= 1.6.0 (ex: localstack_v13)
       pubKeyCrs: { version: '1.6.0', comparator: 'ge' },
       tfhe: {
-        canonical: '1.6.1',
-        compatible: ['1.6.1'],
+        canonical: '1.6.2',
+        compatible: ['1.6.2'],
       },
       kms: {
         canonical: '0.13.20-0',

package/core/runtime/initFhevmEncryptRuntime-p.ts

@@ -5,5 +5,5 @@ import { verifyFhevmRuntime } from './CoreFhevmRuntime-p.js';
 export async function initFhevmEncryptRuntime(runtime: FhevmRuntime, ownerToken: symbol): Promise<void> {
   verifyFhevmRuntime(runtime, ownerToken);
   const encryptRuntime = runtime.extend(encryptModule);
-  await encryptRuntime.encrypt.initTfheModule({ tfheVersion: '1.6.1' });
+  await encryptRuntime.encrypt.initTfheModule({ tfheVersion: '1.6.2' });
 }

package/core/runtime/initFhevmRuntime-p.ts

@@ -8,6 +8,6 @@ export async function initFhevmRuntime(runtime: FhevmRuntime, ownerToken: symbol
   const fullRuntime = runtime.extend(decryptModule).extend(encryptModule);
   await Promise.all([
     fullRuntime.decrypt.initTkmsModule({ tkmsVersion: '0.13.20-0' }),
-    fullRuntime.encrypt.initTfheModule({ tfheVersion: '1.6.1' }),
+    fullRuntime.encrypt.initTfheModule({ tfheVersion: '1.6.2' }),
   ]);
 }

package/core/types/wasmAssets.ts

@@ -1,3 +1,61 @@
+/*
+ * verified-blob:
+ * --------------
+ * Creates a worker from the configured URL after SHA-256 verification.
+ * 1. Reuse cached verified bytes.
+ * 2. Execute those exact bytes as a Blob worker in browsers.
+ * 3. Execute those exact bytes as an eval worker in Node.
+ *
+ * - Transport: url
+ * - Blob: yes
+ * - SHA256: yes
+ *
+ * precheck-direct-url:
+ * --------------------
+ * Creates a worker by passing the configured URL directly to the runtime, after a pre-flight SHA-256 probe.
+ *
+ * IMPORTANT: this is NOT an integrity check. The SDK fetches the URL once to validate
+ * the hash, then hands the URL to the runtime, which fetches it a SECOND time and
+ * executes those bytes. The two fetches are independent — the executed bytes are
+ * never verified. Use only for fail-fast on misconfigured URLs / build mismatches.
+ *
+ * For an actual integrity guarantee, use `verified-blob` (requires CSP allowing blob: workers).
+ *
+ * 1. Fetch the URL and verify its SHA-256 against __TFHE_WORKER_URL_SHA256_JSON__ — fails fast on mismatch.
+ * 2. Discard the verified bytes.
+ * 3. Let the runtime fetch the same URL again and execute it (no verification on this fetch).
+ *
+ * - Transport: url
+ * - Blob: no
+ * - SHA256: yes
+ *
+ * trusted-direct-url:
+ * -------------------
+ * Creates a worker by passing the configured URL directly to the runtime.
+ * 1. Require a configured worker URL.
+ * 2. Do not perform SDK byte verification.
+ * 3. Let the browser or Node runtime load and execute the URL directly.
+ *
+ * - Transport: url
+ * - Blob: no
+ * - SHA256: no
+ *
+ * embedded-base64:
+ * ----------------
+ * Creates a worker from the SDK-embedded base64 worker source.
+ * 1. Read the base64-encoded JavaScript source baked into this module.
+ * 2. Decode into a Blob URL and create a module Worker in browsers.
+ * 3. Decode into UTF-8 JavaScript and create a worker_threads eval Worker in Node.
+ *
+ * - Transport: base64
+ * - Blob: yes
+ * - SHA256: no
+ *
+ * auto:
+ * -----
+ * if workerUrl is defined, try it using `verified-blob`.
+ * if workerUrl failed or is undefined go for `embedded-base64`
+ */
 export type WasmAssetLoadMode =
   | 'embedded-base64'
   | 'verified-blob'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fhevm/sdk",
   "description": "TypeScript Interface for FHEVM",
-  "version": "1.1.0-alpha.5",
+  "version": "1.1.0-alpha.6",
   "type": "module",
   "main": "./_cjs/index.js",
   "module": "./_esm/index.js",