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

package/core/actions/decrypt/canDecryptValues.ts

@@ -1,10 +1,6 @@
-/* eslint-disable @typescript-eslint/unified-signatures */
 import type { Fhevm } from '../../types/coreFhevmClient.js';
 import type { FhevmChain } from '../../types/fhevmChain.js';
-import type {
-  SignedDelegatedDecryptionPermit,
-  SignedSelfDecryptionPermit,
-} from '../../types/signedDecryptionPermit.js';
+import type { SignedDecryptionPermit } from '../../types/signedDecryptionPermit.js';
 import type { TransportKeyPair } from '../../kms/TransportKeyPair-p.js';
 import type { EncryptedValueLike } from '../../types/encryptedTypes.js';
 import { canDecryptValuesFromPairs as canDecryptValuesFromPairs_ } from '../../host-contracts/canDecryptValuesFromPairs.js';
@@ -23,7 +19,7 @@ export type CanDecryptValuesWithUserAddressParameters = CanDecryptValuesParamete
 };
 
 export type CanDecryptValuesWithPermitParameters = CanDecryptValuesParametersBase & {
-  readonly signedPermit: SignedSelfDecryptionPermit | SignedDelegatedDecryptionPermit;
+  readonly signedPermit: SignedDecryptionPermit;
   readonly transportKeyPair?: TransportKeyPair | undefined;
 };
 
@@ -37,16 +33,6 @@ export type CanDecryptValuesReturnType = {
 
 ////////////////////////////////////////////////////////////////////////////////
 
-export async function canDecryptValues(
-  fhevm: Fhevm<FhevmChain>,
-  parameters: CanDecryptValuesWithUserAddressParameters,
-): Promise<CanDecryptValuesReturnType>;
-
-export async function canDecryptValues(
-  fhevm: Fhevm<FhevmChain>,
-  parameters: CanDecryptValuesWithPermitParameters,
-): Promise<CanDecryptValuesReturnType>;
-
 export async function canDecryptValues(
   fhevm: Fhevm<FhevmChain>,
   parameters: CanDecryptValuesWithUserAddressParameters | CanDecryptValuesWithPermitParameters,

package/core/actions/decrypt/canDecryptValuesFromPairs.ts

@@ -1,10 +1,6 @@
-/* eslint-disable @typescript-eslint/unified-signatures */
 import type { Fhevm } from '../../types/coreFhevmClient.js';
 import type { FhevmChain } from '../../types/fhevmChain.js';
-import type {
-  SignedDelegatedDecryptionPermit,
-  SignedSelfDecryptionPermit,
-} from '../../types/signedDecryptionPermit.js';
+import type { SignedDecryptionPermit } from '../../types/signedDecryptionPermit.js';
 import type { TransportKeyPair } from '../../kms/TransportKeyPair-p.js';
 import type { EncryptedValueLike } from '../../types/encryptedTypes.js';
 import { canDecryptValuesFromPairs as canDecryptValuesFromPairs_ } from '../../host-contracts/canDecryptValuesFromPairs.js';
@@ -25,7 +21,7 @@ export type CanDecryptValuesFromPairsWithUserAddressParameters = CanDecryptValue
 };
 
 export type CanDecryptValuesFromPairsWithPermitParameters = CanDecryptValuesFromPairsParametersBase & {
-  readonly signedPermit: SignedSelfDecryptionPermit | SignedDelegatedDecryptionPermit;
+  readonly signedPermit: SignedDecryptionPermit;
   readonly transportKeyPair?: TransportKeyPair | undefined;
 };
 
@@ -39,16 +35,6 @@ export type CanDecryptValuesFromPairsReturnType = {
 
 ////////////////////////////////////////////////////////////////////////////////
 
-export async function canDecryptValuesFromPairs(
-  fhevm: Fhevm<FhevmChain>,
-  parameters: CanDecryptValuesFromPairsWithUserAddressParameters,
-): Promise<CanDecryptValuesFromPairsReturnType>;
-
-export async function canDecryptValuesFromPairs(
-  fhevm: Fhevm<FhevmChain>,
-  parameters: CanDecryptValuesFromPairsWithPermitParameters,
-): Promise<CanDecryptValuesFromPairsReturnType>;
-
 export async function canDecryptValuesFromPairs(
   fhevm: Fhevm<FhevmChain>,
   parameters: CanDecryptValuesFromPairsWithUserAddressParameters | CanDecryptValuesFromPairsWithPermitParameters,

package/core/actions/decrypt/decryptValue.ts

@@ -38,6 +38,7 @@ export async function decryptValue(
     {
       handle: toFhevmHandle(encryptedValue),
       contractAddress: sanitizedContractAddress,
+      ownerAddress: addressToChecksummedAddress(parameters.signedPermit.encryptedDataOwnerAddress),
     },
   ];
 
@@ -46,7 +47,7 @@ export async function decryptValue(
   const typedValues = await decryptValuesFromPairs_(f, {
     ...rest,
     pairs: sanitizedPairs,
-  } as Parameters<typeof decryptValuesFromPairs_>[1]);
+  });
 
   // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
   return typedValues[0]!;

package/core/actions/decrypt/decryptValues.ts

@@ -34,10 +34,12 @@ export async function decryptValues(
   assertIsAddress(contractAddress, {});
   const sanitizedContractAddress = addressToChecksummedAddress(contractAddress);
 
+  const ownerAddress = addressToChecksummedAddress(parameters.signedPermit.encryptedDataOwnerAddress);
   const sanitizedPairs = encryptedValues.map((ev) => {
     return {
       handle: toFhevmHandle(ev),
       contractAddress: sanitizedContractAddress,
+      ownerAddress,
     };
   });
 
@@ -46,5 +48,5 @@ export async function decryptValues(
   return decryptValuesFromPairs_(f, {
     ...rest,
     pairs: sanitizedPairs,
-  } as Parameters<typeof decryptValuesFromPairs_>[1]);
+  });
 }

package/core/actions/decrypt/decryptValuesFromPairs.ts

@@ -33,11 +33,13 @@ export async function decryptValuesFromPairs(
 ): Promise<DecryptValuesFromPairsReturnType> {
   const { pairs, ...rest } = parameters;
 
+  const ownerAddress = addressToChecksummedAddress(parameters.signedPermit.encryptedDataOwnerAddress);
   const sanitizedPairs = pairs.map((pair) => {
     assertIsAddress(pair.contractAddress, {});
     return {
       handle: toFhevmHandle(pair.encryptedValue),
       contractAddress: addressToChecksummedAddress(pair.contractAddress),
+      ownerAddress,
     };
   });
 
@@ -46,5 +48,5 @@ export async function decryptValuesFromPairs(
   return decryptValuesFromPairs_(f, {
     ...rest,
     pairs: sanitizedPairs,
-  } as Parameters<typeof decryptValuesFromPairs_>[1]);
+  });
 }

package/core/actions/decrypt/index.ts

@@ -16,12 +16,6 @@ export { type DecryptValueParameters, type DecryptValueReturnType, decryptValue
 
 export { type DecryptValuesParameters, type DecryptValuesReturnType, decryptValues } from './decryptValues.js';
 
-export {
-  type DecryptKmsSigncryptedSharesParameters,
-  type DecryptKmsSigncryptedSharesReturnType,
-  decryptKmsSigncryptedShares,
-} from './decryptKmsSigncryptedShares.js';
-
 export {
   type CanDecryptValuesFromPairsWithUserAddressParameters,
   type CanDecryptValuesFromPairsWithPermitParameters,

package/core/actions/host/index.ts

@@ -10,24 +10,4 @@ export {
   isAllowedForDecryption,
 } from './isAllowedForDecryption.js';
 
-export { type ResolveChainIdParameters, type ResolveChainIdReturnType, resolveChainId } from './resolveChainId.js';
-
-export {
-  type ReadFhevmExecutorContractDataParameters,
-  type ReadFhevmExecutorContractDataReturnType,
-  readFhevmExecutorContractData,
-} from './readFhevmExecutorContractData.js';
-
-export {
-  type ReadKmsVerifierContractDataParameters,
-  type ReadKmsVerifierContractDataReturnType,
-  readKmsVerifierContractData,
-} from './readKmsVerifierContractData.js';
-
 export { type PersistAllowedParameters, type PersistAllowedReturnType, persistAllowed } from './persistAllowed.js';
-
-export {
-  type ReadInputVerifierContractDataParameters,
-  type ReadInputVerifierContractDataReturnType,
-  readInputVerifierContractData,
-} from './readInputVerifierContractData.js';

package/core/base/bytes.ts

@@ -37,6 +37,7 @@ import { is0x, isNo0x, remove0x } from './string.js';
 import { InvalidPropertyError } from './errors/InvalidPropertyError.js';
 import { InvalidTypeError } from './errors/InvalidTypeError.js';
 import { isUintForByteLength } from './uint.js';
+import { Sha256VerificationError } from './errors/Sha256VerificationError.js';
 
 ////////////////////////////////////////////////////////////////////////////////
 
@@ -1446,7 +1447,7 @@ export async function verifySha256(
 
   if (actual !== expected) {
     const subject = options?.subject ?? 'bytes';
-    throw new Error(`SHA-256 mismatch for ${subject}: expected ${expected}, got ${actual}`);
+    throw new Sha256VerificationError({ subject, expected, actual }, {});
   }
 }
 

package/core/base/cachedFetch.ts

@@ -23,6 +23,7 @@ type CachedFetchOptions<TContext, TParams, TResult> = {
 };
 
 export const CACHE_TTL_24H = 24 * 60 * 60 * 1000; // 24 hours
+export const CACHE_TTL_15MIN = 15 * 1000; // 15 min
 
 /**
  * Creates a cached, deduplicating wrapper around an async fetch function.

package/core/base/environment.ts

@@ -0,0 +1,210 @@
+/**
+ * JS-runtime environment detection and capability probes.
+ *
+ * Everything in this file answers one of two questions about the host
+ * environment the SDK happens to be running in:
+ *
+ * - *Which* runtime is this? — {@link isNodeLike}, {@link isBrowserLike}
+ * - *What* does it support? — {@link getNodeBuffer}
+ *
+ * Detection is intentionally capability-leaning rather than UA-based: edge
+ * runtimes (Vercel Edge, Cloudflare Workers, Next.js edge) are neither Node nor
+ * browser, so probes return the safe answer (`false` / `undefined`) and callers
+ * fall back to web-standard APIs.
+ */
+
+export function isNodeLike(): boolean {
+  return (
+    // eslint-disable-next-line no-restricted-globals
+    typeof process !== 'undefined' &&
+    // eslint-disable-next-line no-restricted-globals, @typescript-eslint/no-unnecessary-condition
+    typeof process.versions?.node === 'string'
+  );
+}
+
+export function isBrowserLike(): boolean {
+  return (
+    // @ts-expect-error - Bun is a runtime global only under Bun
+    typeof Bun === 'undefined' &&
+    !isNodeLike() &&
+    typeof location !== 'undefined' &&
+    typeof location.href === 'string' &&
+    typeof addEventListener === 'function' &&
+    typeof removeEventListener === 'function'
+  );
+}
+
+/**
+ * Imports a Node built-in module by name, returning `undefined` when it isn't
+ * importable (browsers, and edge runtimes: Vercel Edge, Cloudflare Workers,
+ * Next.js edge). The id is built indirectly so bundlers don't statically
+ * resolve/polyfill the module (a polyfill would bloat browser bundles).
+ *
+ * Every major bundler must be told NOT to analyze this computed dynamic import,
+ * each via its own magic comment, or it errors at build/runtime:
+ * - `@vite-ignore` — Vite.
+ * - `webpackIgnore` — webpack.
+ * - `turbopackIgnore` — Turbopack (Next.js). Without it, Turbopack can't analyze
+ *   the parameter-derived specifier, can't bundle a `node:` builtin as a
+ *   candidate, and replaces the call with a stub that throws
+ *   `Cannot find module 'unknown'` — which silently disabled the Node
+ *   `worker_threads` backend (→ single-threaded TFHE) in Next server components.
+ *
+ * Each comment instructs its bundler to emit a plain native `import()` that the
+ * runtime resolves; in the browser that throws and is caught below (→ undefined).
+ * Each capability accessor below wraps this and memoizes its result.
+ */
+async function _importNodeModule<mod>(name: string): Promise<mod | undefined> {
+  try {
+    const id = `node:${name}`;
+    return (await import(/* @vite-ignore */ /* webpackIgnore: true */ /* turbopackIgnore: true */ id)) as mod;
+  } catch {
+    return undefined;
+  }
+}
+
+type NodeBuffer = { from(str: string, encoding: string): BufferSource };
+
+let _nodeBufferPromise: Promise<NodeBuffer | undefined> | undefined;
+
+/**
+ * Resolves Node's `Buffer` if `node:buffer` is importable, else `undefined`.
+ *
+ * Memoized — the answer can't change within a process lifetime. Returns the
+ * `Buffer` reference (not a boolean) because `Buffer` is not a global: the
+ * caller needs the actual constructor, so probing and use share one import.
+ *
+ * Returns `undefined` in non-Node runtimes that also lack `node:buffer`
+ * (browsers, and edge runtimes: Vercel Edge, Cloudflare Workers, Next.js edge).
+ */
+export function getNodeBuffer(): Promise<NodeBuffer | undefined> {
+  _nodeBufferPromise ??= (async () => {
+    const mod = await _importNodeModule<{ Buffer?: NodeBuffer }>('buffer');
+    return typeof mod?.Buffer?.from === 'function' ? mod.Buffer : undefined;
+  })();
+  return _nodeBufferPromise;
+}
+
+// Node's `readFile` returns a `Buffer`, which extends `Uint8Array` but whose
+// `.buffer` TS 5.7+ widens to `ArrayBufferLike` (includes `SharedArrayBuffer`),
+// making it incompatible with `BufferSource`. At runtime a `Buffer` is always
+// backed by an `ArrayBuffer`, so typing the result as `BufferSource` here is a
+// safe cast that lets callers pass the bytes to `WebAssembly.compile` directly.
+type NodeFs = {
+  readFile(path: string): Promise<BufferSource>;
+  access(path: string): Promise<void>;
+};
+
+let _nodeFsPromise: Promise<NodeFs | undefined> | undefined;
+
+/**
+ * Resolves Node's `fs/promises` (`readFile`, `access`) if importable, else
+ * `undefined` (browsers and edge runtimes). Memoized. See {@link getNodeBuffer}
+ * for why this returns the module reference rather than a boolean.
+ */
+export function getNodeFs(): Promise<NodeFs | undefined> {
+  _nodeFsPromise ??= (async () => {
+    const mod = await _importNodeModule<NodeFs>('fs/promises');
+    return typeof mod?.readFile === 'function' ? mod : undefined;
+  })();
+  return _nodeFsPromise;
+}
+
+type NodeUrl = { fileURLToPath(url: URL | string): string };
+
+let _nodeUrlPromise: Promise<NodeUrl | undefined> | undefined;
+
+/**
+ * Resolves Node's `url` (`fileURLToPath`) if importable, else `undefined`
+ * (browsers and edge runtimes). Memoized. See {@link getNodeBuffer} for why
+ * this returns the module reference rather than a boolean.
+ */
+export function getNodeUrl(): Promise<NodeUrl | undefined> {
+  _nodeUrlPromise ??= (async () => {
+    const mod = await _importNodeModule<NodeUrl>('url');
+    return typeof mod?.fileURLToPath === 'function' ? mod : undefined;
+  })();
+  return _nodeUrlPromise;
+}
+
+/**
+ * Returns whether the Web Worker API is available (browsers, Deno, and other
+ * web-standard runtimes). Synchronous — checks for the required globals only.
+ */
+export function supportsWebWorkerApi(): boolean {
+  return (
+    typeof Worker === 'function' &&
+    typeof Blob === 'function' &&
+    typeof URL !== 'undefined' &&
+    typeof URL.createObjectURL === 'function'
+  );
+}
+
+let _decompressionStreamSupported: boolean | undefined;
+
+/**
+ * Returns whether `DecompressionStream` is actually *usable* (plus the `Blob`
+ * pipeline it feeds). Needed to inflate compressed embedded WASM.
+ *
+ * A `typeof` presence check is insufficient: some runtimes — notably the Next.js
+ * Edge Runtime — expose `DecompressionStream` as a global **stub that throws on
+ * construction**, so presence is a false positive that crashes later inside the
+ * compile path. We therefore *construct* one (synchronous, cheap) and memoize the
+ * result (support can't change within a process lifetime).
+ *
+ * Returns `false` on older browsers (Firefox <113, Safari <16.4) and edge runtimes,
+ * so callers fall back (uncompressed / URL-based / JS-inflate WASM loading).
+ */
+export function supportsDecompressionStream(): boolean {
+  if (_decompressionStreamSupported === undefined) {
+    if (typeof DecompressionStream !== 'function' || typeof Blob !== 'function') {
+      _decompressionStreamSupported = false;
+    } else {
+      try {
+        // Construction is the probe — the Next.js Edge stub throws here; a real
+        // implementation does not. Assigned (not bare `new`) so it reads as a value
+        // probe, and discarded.
+        const probe = new DecompressionStream('gzip');
+        void probe;
+        _decompressionStreamSupported = true;
+      } catch {
+        _decompressionStreamSupported = false;
+      }
+    }
+  }
+  return _decompressionStreamSupported;
+}
+
+/** Message envelope exchanged with a Node `worker_threads` worker. */
+export interface MessageData {
+  type: string;
+  [key: string]: unknown;
+}
+
+/** Shape of a Node `worker_threads` worker instance the SDK relies on. */
+export interface NodeMessagePort {
+  on(event: 'error', listener: (error: Error) => void): void;
+  on(event: 'exit', listener: (code: number) => void): void;
+  on(event: string, listener: (data: MessageData) => void): void;
+  off(event: string, listener: (data: MessageData) => void): void;
+  postMessage(value: unknown): void;
+  terminate(): Promise<number>;
+}
+
+type NodeWorkerConstructor = new (code: string | URL, options?: Record<string, unknown>) => NodeMessagePort;
+
+let _nodeWorkerPromise: Promise<NodeWorkerConstructor | undefined> | undefined;
+
+/**
+ * Resolves Node's `worker_threads` `Worker` constructor if importable, else
+ * `undefined` (browser, sandboxed Electron renderer, edge runtimes). Memoized.
+ * See {@link getNodeBuffer} for why this returns the constructor rather than a
+ * boolean.
+ */
+export function getNodeWorker(): Promise<NodeWorkerConstructor | undefined> {
+  _nodeWorkerPromise ??= (async () => {
+    const mod = await _importNodeModule<{ Worker?: NodeWorkerConstructor }>('worker_threads');
+    return typeof mod?.Worker === 'function' ? mod.Worker : undefined;
+  })();
+  return _nodeWorkerPromise;
+}

package/core/base/errors/Sha256VerificationError.ts

@@ -0,0 +1,22 @@
+import type { ErrorMetadataParams } from './ErrorBase.js';
+import { ErrorBase } from './ErrorBase.js';
+
+export type Sha256VerificationErrorType = Sha256VerificationError & {
+  name: 'Sha256VerificationError';
+};
+
+export type Sha256VerificationErrorParams = Readonly<{
+  subject: string;
+  expected: string;
+  actual: string;
+}>;
+
+export class Sha256VerificationError extends ErrorBase {
+  constructor(params: Sha256VerificationErrorParams, options: ErrorMetadataParams) {
+    super({
+      ...options,
+      message: `SHA-256 mismatch for ${params.subject}: expected ${params.expected}, got ${params.actual}`,
+      name: 'Sha256VerificationError',
+    });
+  }
+}