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

package/core/base/wasm.ts

@@ -1,7 +1,8 @@
 import { verifySha256 } from './bytes.js';
 import { FetchError } from './errors/FetchError.js';
 import { isDataUrlFetchSupported } from './fetch.js';
-import { isBrowserLike } from './isomorphicWorker.js';
+import { getNodeBuffer, getNodeFs, getNodeUrl, isBrowserLike, supportsDecompressionStream } from './environment.js';
+import { inflateDecompress } from './inflate.js';
 
 /**
  * Decodes a base64 string to bytes using the fastest available method.
@@ -12,8 +13,12 @@ import { isBrowserLike } from './isomorphicWorker.js';
  */
 async function _isomorphicDecodeBase64(base64: string): Promise<BufferSource> {
   if (!isBrowserLike()) {
-    const { Buffer } = await import('node:buffer');
-    return Buffer.from(base64, 'base64');
+    const NodeBuffer = await getNodeBuffer();
+    if (NodeBuffer) {
+      return NodeBuffer.from(base64, 'base64');
+    }
+    // Not a browser, but no node:buffer either (edge runtime). Fall through to
+    // the web-standard data-URL fetch / atob paths below, which edge supports.
   }
 
   if (await isDataUrlFetchSupported()) {
@@ -47,43 +52,21 @@ async function _isomorphicFetchWasmResponse(wasmUrl: URL): Promise<Response> {
 
 async function _isomorphicReadWasmBytes(wasmUrl: URL): Promise<BufferSource> {
   if (!isBrowserLike() && wasmUrl.protocol === 'file:') {
-    const { readFile } = await import('node:fs/promises');
-    const { fileURLToPath } = await import('node:url');
-
-    // Node's Buffer extends Uint8Array but TS 5.7+ considers its .buffer as
-    // ArrayBufferLike (includes SharedArrayBuffer), making it incompatible with
-    // BufferSource. At runtime Buffer is always backed by ArrayBuffer, so the
-    // cast at WebAssembly.compile is safe and avoids copying.
-    return readFile(fileURLToPath(wasmUrl));
+    const [fs, url] = await Promise.all([getNodeFs(), getNodeUrl()]);
+    if (fs && url) {
+      // The BufferSource-safe cast for Node's Buffer lives in getNodeFs's
+      // return type (see environment.ts), so the bytes can flow straight into
+      // WebAssembly.compile without copying.
+      return fs.readFile(url.fileURLToPath(wasmUrl));
+    }
+    // Not a browser, but no node:fs either (edge runtime). Fall through to
+    // fetch below — a file: URL will fail there, surfacing a clear error.
   }
 
   const res = await _isomorphicFetchWasmResponse(wasmUrl);
   return res.arrayBuffer();
 }
 
-/**
- * Compiles a WASM module from a URL, isomorphically (browser and Node.js).
- *
- * - Node + `file://`: uses `readFile` (Node `fetch` doesn't support `file://`)
- * - Browser + streaming: uses `WebAssembly.compileStreaming` (fastest path)
- * - Fallback: `fetch` + `arrayBuffer` + `WebAssembly.compile`
- */
-export async function isomorphicCompileWasm(wasmUrl: URL): Promise<WebAssembly.Module> {
-  const isBrowser = isBrowserLike();
-
-  if (isBrowser) {
-    const res = await _isomorphicFetchWasmResponse(wasmUrl);
-    if (typeof WebAssembly.compileStreaming === 'function') {
-      return await WebAssembly.compileStreaming(res);
-    }
-    return WebAssembly.compile(await res.arrayBuffer());
-  }
-
-  const bytes = await _isomorphicReadWasmBytes(wasmUrl);
-  // Safe cast: Node's Buffer is always backed by ArrayBuffer at runtime.
-  return WebAssembly.compile(bytes);
-}
-
 /**
  * Fetches/reads a WASM module, verifies its SHA-256 digest, then compiles it.
  *
@@ -120,9 +103,19 @@ export async function isomorphicCompileWasmFromBase64(
 
   if (compressionFormat === undefined) {
     return WebAssembly.compile(bytes);
-  } else {
+  }
+
+  // Preferred: stream through the platform DecompressionStream (native, zero-copy).
+  if (supportsDecompressionStream()) {
     const stream = new Blob([bytes]).stream().pipeThrough(new DecompressionStream(compressionFormat));
     // compileStreaming requires Content-Type: application/wasm — supply it explicitly.
     return WebAssembly.compileStreaming(new Response(stream, { headers: { 'Content-Type': 'application/wasm' } }));
   }
+
+  // Fallback for runtimes without a usable DecompressionStream — older browsers
+  // (Firefox <113, Safari <16.4) and the Next.js Edge Runtime (whose stub throws on
+  // construction). Inflate in pure JS, then compile. Keeps the small compressed
+  // embedded payload working everywhere with no caller action.
+  const compressed = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes as ArrayBuffer);
+  return WebAssembly.compile(inflateDecompress(compressed, compressionFormat));
 }

package/core/kms/TransportKeyPair-p.ts

@@ -237,11 +237,6 @@ export async function toTransportKeyPair(
     expectedType: 'Bytes | BytesHex',
     ...options,
   });
-  assertRecordNonNullableProperty(value, 'tkmsVersion', name, {
-    expectedType: 'string',
-    ...options,
-  });
-
   const rawPublicKey = value.publicKey;
   const rawPrivateKey = value.privateKey;
   const rawTkmsVersion = value.tkmsVersion;

package/core/kms/createKmsUserDecryptEip712.ts

@@ -16,6 +16,7 @@ import { assertIsUint64, assertIsUintNumber } from '../base/uint.js';
 import { assertIsKmsExtraData } from './kmsExtraData.js';
 import { kmsUserDecryptEip712Types } from './kmsUserDecryptEip712Types.js';
 import { isDeepEqual } from '../base/object.js';
+import { kmsDelegatedUserDecryptEip712Types } from './kmsDelegatedUserDecryptEip712Types.js';
 
 ////////////////////////////////////////////////////////////////////////////////
 
@@ -121,7 +122,13 @@ export function _assertIsKmsUserDecryptEip712Base(
   assertIsKmsEip712Domain((value as Record<string, unknown>).domain, `${name}.domain`, options);
 
   assertRecordNonNullableProperty(value, 'types', name, options);
-  if (!isDeepEqual(value.types, kmsUserDecryptEip712Types)) {
+
+  const expectedTypes =
+    primaryType === 'DelegatedUserDecryptRequestVerification'
+      ? kmsDelegatedUserDecryptEip712Types
+      : kmsUserDecryptEip712Types;
+
+  if (!isDeepEqual(value.types, expectedTypes)) {
     throw new Error('Unexpected KmsUserDecryptEip712Types');
   }
 

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

@@ -6,91 +6,167 @@ import type {
   TkmsModuleInfo,
 } from '../types.js';
 import type { KmsLibApi, TkmsVersion } from '../../../../wasm/tkms/KmsLibApi.js';
-import type { KmsAssetMetadata } from '../../../../wasm/tkms/loadKmsLib.js';
-import { isBrowserLike } from '../../../base/isomorphicWorker.js';
+import type { KmsAssetMetadata, KmsAssets } from '../../../../wasm/tkms/loadKmsLib.js';
+import { isBrowserLike } from '../../../base/environment.js';
 import { isomorphicCompileVerifiedWasm, isomorphicCompileWasmFromBase64 } from '../../../base/wasm.js';
 import { assertIsFhevmRuntime } from '../../../runtime/CoreFhevmRuntime-p.js';
-import { wasmBaseUrl } from '../../../../wasm/wasmBaseUrl.js';
 import { kmsAssetsWithVersion, loadKmsLib, loadKmsWasmBase64 } from '../../../../wasm/tkms/loadKmsLib.js';
+import { isomorphicFileUrlExists } from '../../../base/isomorphicFs.js';
 
 ////////////////////////////////////////////////////////////////////////////////
 
-const ownerUidByVersion = new Map<TkmsVersion, string>();
-const cachedTkmsModulePromiseByVersion = new Map<TkmsVersion, Promise<KmsLibApi>>();
-const moduleInfoByVersion = new Map<TkmsVersion, TkmsModuleInfo>();
-
-////////////////////////////////////////////////////////////////////////////////
-
-// 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.
-
 // (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(`./tkms/${file}`, wasmBaseUrl);
 };
 
+////////////////////////////////////////////////////////////////////////////////
+
+type KmsAssetResolution = 'user' | 'node' | 'none';
+
 type ResolvedKmsAsset = KmsAssetMetadata & {
   readonly url: URL | undefined;
+  readonly resolution: KmsAssetResolution;
 };
 
-function _resolveKmsAsset(asset: KmsAssetMetadata, locateFile: FhevmRuntimeConfig['locateFile']): ResolvedKmsAsset {
+type ResolvedKmsAssets = {
+  readonly wasm: ResolvedKmsAsset;
+};
+
+////////////////////////////////////////////////////////////////////////////////
+
+async function _resolveSingleKmsAsset(
+  asset: KmsAssetMetadata,
+  locateFile: FhevmRuntimeConfig['locateFile'],
+): Promise<ResolvedKmsAsset> {
   let url: URL | undefined;
+  let resolution: KmsAssetResolution = '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 TKMS 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, resolution });
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+async function _resolveKmsAssets(
+  assets: KmsAssets,
+  locateFile: FhevmRuntimeConfig['locateFile'],
+): Promise<{ readonly wasm: ResolvedKmsAsset }> {
+  let wasm = await _resolveSingleKmsAsset(assets.wasm, 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 isomorphicFileUrlExists(wasm.url);
+    if (!allExist) {
+      wasm = Object.freeze({ ...wasm, url: undefined });
+    }
   }
 
-  return Object.freeze({ ...asset, url });
+  return { wasm };
+}
+
+////////////////////////////////////////////////////////////////////////////////
+
+function _logResolvedKmsAssets(resolvedAssets: ResolvedKmsAssets, logger: FhevmRuntimeConfig['logger']): void {
+  const { wasm } = resolvedAssets;
+  if (wasm.resolution === 'user') {
+    logger?.debug(`resolve tkms wasm filename using 'locateFile' function: ${wasm.filename} -> url: ${wasm.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 _resolveTkmsAssets -> base64.
+      logger?.debug(
+        `tkms auto-derived assets not found on disk (bundler relocation?); using embedded base64 ` +
+          `(wasm: ${wasm.localRelativePath})`,
+      );
+    } else {
+      logger?.debug(`resolve tkms wasm local path: ${wasm.localRelativePath} -> url: ${wasm.url}`);
+    }
+  } else {
+    // 'none': browser zero-config (no 'locateFile', not Node) -> embedded base64.
+    logger?.debug(`resolve tkms assets using embedded base64 (browser, no 'locateFile')`);
+  }
 }
 
+////////////////////////////////////////////////////////////////////////////////
+
 type ResolvedTkmsModuleConfig = {
   readonly version: TkmsVersion;
-  readonly wasm: ResolvedKmsAsset;
+  readonly assets: ResolvedKmsAssets;
   readonly logger: FhevmRuntimeConfig['logger'];
 };
 
 const resolvedTkmsModuleConfigByVersion = new Map<TkmsVersion, ResolvedTkmsModuleConfig>();
+const resolvingTkmsModuleConfigPromiseByVersion = new Map<TkmsVersion, Promise<ResolvedTkmsModuleConfig>>();
 
 /**
  * @internal
- * Returns the existing resolved config, or resolves it from the runtime config.
+ * Returns the existing resolved config for a TKMS version, or resolves it from
+ * the runtime config.
  */
-function _getOrResolveTkmsModuleConfig(runtime: FhevmRuntime, tkmsVersion: TkmsVersion): ResolvedTkmsModuleConfig {
-  let resolvedTkmsModuleConfig = resolvedTkmsModuleConfigByVersion.get(tkmsVersion);
+async function _getOrResolveTkmsModuleConfig(
+  runtime: FhevmRuntime,
+  tkmsVersion: TkmsVersion,
+): Promise<ResolvedTkmsModuleConfig> {
+  const resolvedTkmsModuleConfig = resolvedTkmsModuleConfigByVersion.get(tkmsVersion);
   if (resolvedTkmsModuleConfig !== undefined) {
     return resolvedTkmsModuleConfig;
   }
 
-  resolvedTkmsModuleConfig = _resolveTkmsModuleConfig(runtime.config, tkmsVersion);
-
-  resolvedTkmsModuleConfigByVersion.set(tkmsVersion, resolvedTkmsModuleConfig);
+  let resolvingTkmsModuleConfigPromise = resolvingTkmsModuleConfigPromiseByVersion.get(tkmsVersion);
+  if (resolvingTkmsModuleConfigPromise === undefined) {
+    resolvingTkmsModuleConfigPromise = _resolveTkmsModuleConfig(runtime.config, tkmsVersion)
+      .then((cfg) => {
+        resolvedTkmsModuleConfigByVersion.set(tkmsVersion, cfg);
+        return cfg;
+      })
+      .catch((error: unknown) => {
+        resolvingTkmsModuleConfigPromiseByVersion.delete(tkmsVersion);
+        throw error;
+      });
+
+    resolvingTkmsModuleConfigPromiseByVersion.set(tkmsVersion, resolvingTkmsModuleConfigPromise);
+  }
 
-  return resolvedTkmsModuleConfig;
+  return resolvingTkmsModuleConfigPromise;
 }
 
-function _resolveTkmsModuleConfig(parameters: FhevmRuntimeConfig, version: TkmsVersion): ResolvedTkmsModuleConfig {
+async function _resolveTkmsModuleConfig(
+  parameters: FhevmRuntimeConfig,
+  version: TkmsVersion,
+): Promise<ResolvedTkmsModuleConfig> {
   const { locateFile } = parameters;
 
   const assets = kmsAssetsWithVersion(version);
-  const wasm = _resolveKmsAsset(assets.wasm, locateFile);
 
-  if (locateFile !== undefined) {
-    parameters.logger?.debug(`resolve kms wasm filename: ${wasm.filename} -> url: ${wasm.url}`);
-  } else {
-    /*
-      if run in Node only, use defaultLocateFile!
-    */
-    if (!isBrowserLike()) {
-      parameters.logger?.debug(`resolve kms wasm local path: ${wasm.localRelativePath} -> url: ${wasm.url}`);
-    }
-  }
+  const resolvedAssets = await _resolveKmsAssets(assets, locateFile);
+
+  _logResolvedKmsAssets(resolvedAssets, parameters.logger);
 
   // if wasmUrl is undefined, use base64 code instead
   const cfg = {
     version,
-    wasm,
+    assets: resolvedAssets,
     logger: parameters.logger,
   };
 
@@ -103,6 +179,12 @@ function _resolveTkmsModuleConfig(parameters: FhevmRuntimeConfig, version: TkmsV
 // initTkmsModule
 ////////////////////////////////////////////////////////////////////////////////
 
+const ownerUidByVersion = new Map<TkmsVersion, string>();
+const cachedTkmsModulePromiseByVersion = new Map<TkmsVersion, Promise<KmsLibApi>>();
+const moduleInfoByVersion = new Map<TkmsVersion, TkmsModuleInfo>();
+
+////////////////////////////////////////////////////////////////////////////////
+
 type TkmsInitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
 
 type TkmsLibInitAsyncParameters = {
@@ -121,40 +203,47 @@ export async function initTkmsModule(runtime: FhevmRuntime, parameters: InitTkms
 
   ownerUidByVersion.set(parameters.tkmsVersion, runtime.uid);
 
-  // Cache the TKMS initialization promise once and keep it cached even if it
-  // rejects.
+  // Cache the whole initialization promise before the first await. Several
+  // clients may call initTkmsModule concurrently during startup.
   //
-  // Retry is not supported:
-  // -----------------------
-  // The underlying KMS/WASM bindings
-  // keep module-level state that cannot be reset reliably after a partial
-  // initialization failure; later callers should observe the original error
-  // instead of retrying against half-initialized state.
+  // Retry is not supported
 
   let cachedTkmsModulePromise = cachedTkmsModulePromiseByVersion.get(parameters.tkmsVersion);
   if (cachedTkmsModulePromise === undefined) {
-    // resolve is sync
-    const cfg = _getOrResolveTkmsModuleConfig(runtime, parameters.tkmsVersion);
-    cachedTkmsModulePromise = _initTkmsModule(cfg);
+    cachedTkmsModulePromise = (async () => {
+      // resolve is async
+      const cfg = await _getOrResolveTkmsModuleConfig(runtime, parameters.tkmsVersion);
+      return await _initTkmsModule(cfg);
+    })();
+
     cachedTkmsModulePromiseByVersion.set(parameters.tkmsVersion, cachedTkmsModulePromise);
   }
 
   return cachedTkmsModulePromise;
 }
 
+async function _compileWasmModule(cfg: ResolvedTkmsModuleConfig): Promise<WebAssembly.Module> {
+  let wasmModule;
+
+  if (cfg.assets.wasm.url !== undefined) {
+    cfg.logger?.debug(`compile tkms verified wasm at: ${cfg.assets.wasm.url}`);
+    wasmModule = await isomorphicCompileVerifiedWasm(cfg.assets.wasm.url, cfg.assets.wasm.sha256);
+  } else {
+    const { tkmsWasmBase64, tkmsWasmBase64CompressionFormat } = await loadKmsWasmBase64(cfg.version);
+    cfg.logger?.debug(
+      `compile tkms wasm from embedded base64 (compression:${tkmsWasmBase64CompressionFormat ?? 'none'})`,
+    );
+    wasmModule = await isomorphicCompileWasmFromBase64(tkmsWasmBase64, tkmsWasmBase64CompressionFormat);
+  }
+
+  return wasmModule;
+}
+
 async function _initTkmsModule(cfg: ResolvedTkmsModuleConfig): Promise<KmsLibApi> {
   const kmsLib = await loadKmsLib(cfg.version);
 
   // Compile WASM module (see matrix in types.ts)
-  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);
-  } else {
-    const { tkmsWasmBase64, tkmsWasmBase64IsGzipped } = await loadKmsWasmBase64(cfg.version);
-    cfg.logger?.debug(`compile wasm from embedded base64 (compression:${tkmsWasmBase64IsGzipped})`);
-    wasmModule = await isomorphicCompileWasmFromBase64(tkmsWasmBase64, tkmsWasmBase64IsGzipped ? 'gzip' : undefined);
-  }
+  const wasmModule = await _compileWasmModule(cfg);
 
   const input: TkmsLibInitAsyncParameters = { module_or_path: wasmModule };
 
@@ -171,7 +260,7 @@ async function _initTkmsModule(cfg: ResolvedTkmsModuleConfig): Promise<KmsLibApi
   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,
       memory,