@cofhe/sdk 0.7.1 → 1.0.0-alpha.0

package/dist/web.d.cts

@@ -1,12 +1,17 @@
-import { I as IStorage, C as CofheInputConfig, a as CofheConfig, b as CofheClient, E as EncryptableItem } from './clientTypes-CYZjFznO.cjs';
+import { I as IStorage, C as CofheInputConfig, a as CofheConfig, b as CofheClient, E as EncryptableItem } from './clientTypes-C0A9ji5O.cjs';
 import 'viem';
 import './types-C07FK-cL.cjs';
 import 'zod';
-import './acp-Wi6isVQI.cjs';
+import './onchain-utils-D9Z33IP7.cjs';
 import 'zustand/vanilla';
 
 declare function createSsrStorage(): IStorage;
 
+/**
+ * Worker Manager for ZK Proof Generation
+ * Manages worker lifecycle and request/response handling
+ */
+
 /**
  * Terminate the worker
  */
@@ -16,8 +21,49 @@ declare function terminateWorker(): void;
  */
 declare function areWorkersAvailable(): boolean;
 
+/**
+ * Rayon thread pool setup for the browser build of tfhe.
+ *
+ * `tfhe` is built with wasm-bindgen-rayon, so the ZK proof (the
+ * `build_with_proof_packed` call, by far the most expensive step of
+ * `encryptInputs`) can run across several threads. Those threads are real Web
+ * Workers that share the wasm linear memory, and `initThreadPool` hands them
+ * that memory over `postMessage`.
+ *
+ * Sharing memory across threads is only allowed in a cross-origin-isolated
+ * context, so the host page must be served with:
+ *
+ *   Cross-Origin-Opener-Policy:   same-origin
+ *   Cross-Origin-Embedder-Policy: require-corp   (or `credentialless`)
+ *
+ * Plenty of apps can't or don't set those headers, and calling
+ * `initThreadPool` without them throws ("SharedArrayBuffer transfer requires
+ * self.crossOriginIsolated"). So this is strictly an optimisation: we probe for
+ * isolation, and when it isn't available we leave tfhe single-threaded rather
+ * than failing the encryption. Single-threaded tfhe works in every context.
+ */
+
+type TfheThreadPoolResult = {
+    /** Whether a multi-threaded rayon pool is now running */
+    enabled: boolean;
+    /** Threads requested from `initThreadPool` (1 when single-threaded) */
+    threads: number;
+    /** Why the pool was not started, when `enabled` is false */
+    reason?: string;
+};
+
 declare const hasDOM: boolean;
 
+/**
+ * Outcome of the rayon thread pool setup on the main thread, or `null` if the
+ * main thread hasn't had to generate a proof yet. `enabled: false` carries a
+ * `reason`.
+ *
+ * Note this reflects the *main thread* only. When workers are enabled (the
+ * default) proving happens inside the zkProve worker, which runs its own pool,
+ * and the main thread never starts one — so `null` is the normal value there.
+ */
+declare function getTfheThreadPoolStatus(): TfheThreadPoolResult | null;
 /**
  * Creates a CoFHE configuration for web with IndexedDB storage as default
  * @param config - The CoFHE input configuration (fheKeyStorage will default to IndexedDB if not provided)
@@ -39,4 +85,4 @@ declare function createCofheClient<TConfig extends CofheConfig>(config: TConfig)
  */
 declare function createCofheClientWithCustomWorker(config: CofheConfig, customZkProveWorkerFn: (fheKeyHex: string, crsHex: string, items: EncryptableItem[], metadata: Uint8Array) => Promise<Uint8Array>): CofheClient;
 
-export { areWorkersAvailable, createCofheClient, createCofheClientWithCustomWorker, createCofheConfig, createSsrStorage, hasDOM, terminateWorker };
+export { areWorkersAvailable, createCofheClient, createCofheClientWithCustomWorker, createCofheConfig, createSsrStorage, getTfheThreadPoolStatus, hasDOM, terminateWorker };

package/dist/web.d.ts

@@ -1,12 +1,17 @@
-import { I as IStorage, C as CofheInputConfig, a as CofheConfig, b as CofheClient, E as EncryptableItem } from './clientTypes-BN3nbzYM.js';
+import { I as IStorage, C as CofheInputConfig, a as CofheConfig, b as CofheClient, E as EncryptableItem } from './clientTypes-CcU5WvdV.js';
 import 'viem';
 import './types-C07FK-cL.js';
 import 'zod';
-import './acp-Wi6isVQI.js';
+import './onchain-utils-D9Z33IP7.js';
 import 'zustand/vanilla';
 
 declare function createSsrStorage(): IStorage;
 
+/**
+ * Worker Manager for ZK Proof Generation
+ * Manages worker lifecycle and request/response handling
+ */
+
 /**
  * Terminate the worker
  */
@@ -16,8 +21,49 @@ declare function terminateWorker(): void;
  */
 declare function areWorkersAvailable(): boolean;
 
+/**
+ * Rayon thread pool setup for the browser build of tfhe.
+ *
+ * `tfhe` is built with wasm-bindgen-rayon, so the ZK proof (the
+ * `build_with_proof_packed` call, by far the most expensive step of
+ * `encryptInputs`) can run across several threads. Those threads are real Web
+ * Workers that share the wasm linear memory, and `initThreadPool` hands them
+ * that memory over `postMessage`.
+ *
+ * Sharing memory across threads is only allowed in a cross-origin-isolated
+ * context, so the host page must be served with:
+ *
+ *   Cross-Origin-Opener-Policy:   same-origin
+ *   Cross-Origin-Embedder-Policy: require-corp   (or `credentialless`)
+ *
+ * Plenty of apps can't or don't set those headers, and calling
+ * `initThreadPool` without them throws ("SharedArrayBuffer transfer requires
+ * self.crossOriginIsolated"). So this is strictly an optimisation: we probe for
+ * isolation, and when it isn't available we leave tfhe single-threaded rather
+ * than failing the encryption. Single-threaded tfhe works in every context.
+ */
+
+type TfheThreadPoolResult = {
+    /** Whether a multi-threaded rayon pool is now running */
+    enabled: boolean;
+    /** Threads requested from `initThreadPool` (1 when single-threaded) */
+    threads: number;
+    /** Why the pool was not started, when `enabled` is false */
+    reason?: string;
+};
+
 declare const hasDOM: boolean;
 
+/**
+ * Outcome of the rayon thread pool setup on the main thread, or `null` if the
+ * main thread hasn't had to generate a proof yet. `enabled: false` carries a
+ * `reason`.
+ *
+ * Note this reflects the *main thread* only. When workers are enabled (the
+ * default) proving happens inside the zkProve worker, which runs its own pool,
+ * and the main thread never starts one — so `null` is the normal value there.
+ */
+declare function getTfheThreadPoolStatus(): TfheThreadPoolResult | null;
 /**
  * Creates a CoFHE configuration for web with IndexedDB storage as default
  * @param config - The CoFHE input configuration (fheKeyStorage will default to IndexedDB if not provided)
@@ -39,4 +85,4 @@ declare function createCofheClient<TConfig extends CofheConfig>(config: TConfig)
  */
 declare function createCofheClientWithCustomWorker(config: CofheConfig, customZkProveWorkerFn: (fheKeyHex: string, crsHex: string, items: EncryptableItem[], metadata: Uint8Array) => Promise<Uint8Array>): CofheClient;
 
-export { areWorkersAvailable, createCofheClient, createCofheClientWithCustomWorker, createCofheConfig, createSsrStorage, hasDOM, terminateWorker };
+export { areWorkersAvailable, createCofheClient, createCofheClientWithCustomWorker, createCofheConfig, createSsrStorage, getTfheThreadPoolStatus, hasDOM, terminateWorker };

package/dist/web.js

@@ -1,7 +1,9 @@
-import { createCofheConfigBase, createCofheClientBase, fheTypeToString } from './chunk-43USWPEH.js';
-import './chunk-N6IDQRRU.js';
-import './chunk-Q7CBWGQX.js';
-import { TFHE_RS_SAFE_SERIALIZATION_SIZE_LIMIT } from './chunk-ESMZCFJY.js';
+import { createCofheConfigBase, createCofheClientBase } from './chunk-OL3DZN7A.js';
+import './chunk-UKQAJK4N.js';
+import './chunk-BQWHPIYU.js';
+import { initTfheThreadPool } from './chunk-KSOV5B4B.js';
+import { fheTypeToString, fromHexString } from './chunk-6ZW76ZKB.js';
+import { TFHE_RS_SAFE_SERIALIZATION_SIZE_LIMIT } from './chunk-XQ32JG3T.js';
 import { constructClient } from 'iframe-shared-storage';
 
 // web/const.ts
@@ -128,7 +130,7 @@ var ZkProveWorkerManager = class {
   /**
    * Submit a proof generation request to the worker
    */
-  async submitProof(fheKeyHex, crsHex, items, metadata) {
+  async submitProof(fheKeyHex, crsHex, items, metadata, tfheThreads) {
     await this.initializeWorker();
     const id = `zkprove-${Date.now()}-${this.requestCounter++}`;
     return new Promise((resolve, reject) => {
@@ -143,7 +145,8 @@ var ZkProveWorkerManager = class {
         fheKeyHex,
         crsHex,
         items,
-        metadata: Array.from(metadata)
+        metadata: Array.from(metadata),
+        tfheThreads
       };
       this.worker.postMessage(message);
     });
@@ -191,14 +194,39 @@ function areWorkersAvailable() {
 // web/index.ts
 var tfheModule = null;
 var tfheInitialized = false;
-async function initTfhe() {
+var tfheInitPromise = null;
+var threadPoolPromise = null;
+var threadPoolResult = null;
+function getTfheThreadPoolStatus() {
+  return threadPoolResult;
+}
+var initTfhe = async () => {
   if (tfheInitialized)
     return false;
-  tfheModule = await import('tfhe');
-  await tfheModule.default();
-  await tfheModule.init_panic_hook();
-  tfheInitialized = true;
+  if (tfheInitPromise) {
+    await tfheInitPromise;
+    return false;
+  }
+  tfheInitPromise = (async () => {
+    const mod = await import('tfhe');
+    await mod.default();
+    await mod.init_panic_hook();
+    tfheModule = mod;
+    tfheInitialized = true;
+  })();
+  try {
+    await tfheInitPromise;
+  } catch (error) {
+    tfheInitPromise = null;
+    throw error;
+  }
   return true;
+};
+function createStartMainThreadPool(tfheThreads) {
+  return async () => {
+    threadPoolPromise ??= initTfheThreadPool(requireTfhe(), tfheThreads);
+    threadPoolResult = await threadPoolPromise;
+  };
 }
 function requireTfhe() {
   if (!tfheModule) {
@@ -206,13 +234,6 @@ function requireTfhe() {
   }
   return tfheModule;
 }
-var fromHexString = (hexString) => {
-  const cleanString = hexString.length % 2 === 1 ? `0${hexString}` : hexString;
-  const arr = cleanString.replace(/^0x/, "").match(/.{1,2}/g);
-  if (!arr)
-    return new Uint8Array();
-  return new Uint8Array(arr.map((byte) => parseInt(byte, 16)));
-};
 var _deserializeTfhePublicKey = (buff) => {
   return requireTfhe().TfheCompactPublicKey.safe_deserialize(
     fromHexString(buff),
@@ -234,13 +255,15 @@ var zkBuilderAndCrsGenerator = (fhe, crs) => {
   const zkCrs = _deserializeCompactPkeCrs(crs);
   return { zkBuilder, zkCrs };
 };
-async function zkProveWithWorker(fheKeyHex, crsHex, items, metadata) {
-  const serializedItems = items.map((item) => ({
-    utype: fheTypeToString(item.utype),
-    data: typeof item.data === "bigint" ? item.data.toString() : item.data
-  }));
-  const workerManager2 = getWorkerManager();
-  return await workerManager2.submitProof(fheKeyHex, crsHex, serializedItems, metadata);
+function createZkProveWithWorker(tfheThreads) {
+  return async function zkProveWithWorker(fheKeyHex, crsHex, items, metadata) {
+    const serializedItems = items.map((item) => ({
+      utype: fheTypeToString(item.utype),
+      data: typeof item.data === "bigint" ? item.data.toString() : item.data
+    }));
+    const workerManager2 = getWorkerManager();
+    return await workerManager2.submitProof(fheKeyHex, crsHex, serializedItems, metadata, tfheThreads);
+  };
 }
 function createCofheConfig(config) {
   return createCofheConfigBase({
@@ -256,9 +279,10 @@ function createCofheClient(config) {
     tfhePublicKeyDeserializer,
     compactPkeCrsDeserializer,
     initTfhe,
+    beforeMainThreadProve: createStartMainThreadPool(config.tfheThreads),
     // Always provide the worker function if available - config.useWorkers controls usage
     // areWorkersAvailable will return true if the Worker API is available and false in Node.js
-    zkProveWorkerFn: areWorkersAvailable() ? zkProveWithWorker : void 0
+    zkProveWorkerFn: areWorkersAvailable() ? createZkProveWithWorker(config.tfheThreads) : void 0
   });
 }
 function createCofheClientWithCustomWorker(config, customZkProveWorkerFn) {
@@ -268,8 +292,9 @@ function createCofheClientWithCustomWorker(config, customZkProveWorkerFn) {
     tfhePublicKeyDeserializer,
     compactPkeCrsDeserializer,
     initTfhe,
+    beforeMainThreadProve: createStartMainThreadPool(config.tfheThreads),
     zkProveWorkerFn: customZkProveWorkerFn
   });
 }
 
-export { areWorkersAvailable, createCofheClient, createCofheClientWithCustomWorker, createCofheConfig, createSsrStorage, hasDOM, terminateWorker };
+export { areWorkersAvailable, createCofheClient, createCofheClientWithCustomWorker, createCofheConfig, createSsrStorage, getTfheThreadPoolStatus, hasDOM, terminateWorker };

package/dist/zkProve.worker.cjs

@@ -1,35 +1,96 @@
 'use strict';
 
+require('viem');
+
 // core/consts.ts
 var TFHE_RS_SAFE_SERIALIZATION_SIZE_LIMIT = BigInt(1 << 30);
 
-// web/zkProve.worker.ts
-var tfheModule = null;
-var initialized = false;
-async function initTfhe() {
-  if (initialized)
-    return;
+// web/tfheThreadPool.ts
+var MAX_AUTO_THREADS = 8;
+function resolveThreadCount(setting = "auto") {
+  if (setting === false)
+    return 1;
+  if (typeof setting === "number") {
+    return Number.isFinite(setting) && setting >= 1 ? Math.floor(setting) : 1;
+  }
+  const cores = globalThis.navigator?.hardwareConcurrency ?? 1;
+  if (!Number.isFinite(cores) || cores < 1)
+    return 1;
+  return Math.min(Math.floor(cores), MAX_AUTO_THREADS);
+}
+function isCrossOriginIsolated() {
+  return globalThis.crossOriginIsolated === true;
+}
+async function initTfheThreadPool(mod, setting = "auto") {
+  if (setting === false) {
+    return { enabled: false, threads: 1, reason: "disabled via config.tfheThreads" };
+  }
+  if (typeof mod.initThreadPool !== "function") {
+    return { enabled: false, threads: 1, reason: "tfhe build has no initThreadPool (single-threaded wasm)" };
+  }
+  if (typeof Worker === "undefined") {
+    return { enabled: false, threads: 1, reason: "Worker is unavailable" };
+  }
+  if (!isCrossOriginIsolated()) {
+    return {
+      enabled: false,
+      threads: 1,
+      reason: "not cross-origin isolated \u2014 serve the page with Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp (or credentialless) to enable multi-threaded proving"
+    };
+  }
+  const threads = resolveThreadCount(setting);
+  if (threads <= 1) {
+    return { enabled: false, threads: 1, reason: "resolved to a single thread" };
+  }
   try {
-    tfheModule = await import('tfhe');
-    await tfheModule.default();
-    await tfheModule.init_panic_hook();
-    initialized = true;
-    console.log("[Worker] TFHE initialized");
+    await mod.initThreadPool(threads);
+    return { enabled: true, threads };
   } catch (error) {
-    console.error("[Worker] Failed to initialize TFHE:", error);
-    throw error;
+    return {
+      enabled: false,
+      threads: 1,
+      reason: `initThreadPool failed: ${error instanceof Error ? error.message : String(error)}`
+    };
   }
 }
-function fromHexString(hexString) {
-  const cleanString = hexString.length % 2 === 1 ? `0${hexString}` : hexString;
-  const arr = cleanString.replace(/^0x/, "").match(/.{1,2}/g);
+var HEX_BODY_REGEX = /^[0-9a-fA-F]*$/;
+var fromHexString = (hexString) => {
+  const body = hexString.replace(/^0x/, "");
+  if (!HEX_BODY_REGEX.test(body)) {
+    throw new Error("Invalid hex string: contains non-hexadecimal characters");
+  }
+  const padded = body.length % 2 === 1 ? `0${body}` : body;
+  const arr = padded.match(/.{1,2}/g);
   if (!arr)
     return new Uint8Array();
   return new Uint8Array(arr.map((byte) => parseInt(byte, 16)));
+};
+
+// web/zkProve.worker.ts
+var tfheModule = null;
+var initPromise = null;
+var threadPool = null;
+function initTfhe(tfheThreads = "auto") {
+  initPromise ??= (async () => {
+    try {
+      tfheModule = await import('tfhe');
+      await tfheModule.default();
+      await tfheModule.init_panic_hook();
+      threadPool = await initTfheThreadPool(tfheModule, tfheThreads);
+      console.log(
+        threadPool.enabled ? `[Worker] TFHE initialized (rayon thread pool: ${threadPool.threads} threads)` : `[Worker] TFHE initialized (single-threaded: ${threadPool.reason})`
+      );
+    } catch (error) {
+      console.error("[Worker] Failed to initialize TFHE:", error);
+      initPromise = null;
+      throw error;
+    }
+  })();
+  return initPromise;
 }
 if (typeof self !== "undefined") {
   self.onmessage = async (event) => {
-    const { id, type, fheKeyHex, crsHex, items, metadata } = event.data;
+    const { id, type, fheKeyHex, crsHex, items, metadata, tfheThreads } = event.data;
     if (type !== "zkProve") {
       self.postMessage({
         id,
@@ -39,7 +100,7 @@ if (typeof self !== "undefined") {
       return;
     }
     try {
-      await initTfhe();
+      await initTfhe(tfheThreads);
       if (!tfheModule) {
         throw new Error("TFHE module not initialized");
       }

package/dist/zkProve.worker.js

@@ -1,32 +1,32 @@
-import { TFHE_RS_SAFE_SERIALIZATION_SIZE_LIMIT } from './chunk-ESMZCFJY.js';
+import { initTfheThreadPool } from './chunk-KSOV5B4B.js';
+import { fromHexString } from './chunk-6ZW76ZKB.js';
+import { TFHE_RS_SAFE_SERIALIZATION_SIZE_LIMIT } from './chunk-XQ32JG3T.js';
 
 // web/zkProve.worker.ts
 var tfheModule = null;
-var initialized = false;
-async function initTfhe() {
-  if (initialized)
-    return;
-  try {
-    tfheModule = await import('tfhe');
-    await tfheModule.default();
-    await tfheModule.init_panic_hook();
-    initialized = true;
-    console.log("[Worker] TFHE initialized");
-  } catch (error) {
-    console.error("[Worker] Failed to initialize TFHE:", error);
-    throw error;
-  }
-}
-function fromHexString(hexString) {
-  const cleanString = hexString.length % 2 === 1 ? `0${hexString}` : hexString;
-  const arr = cleanString.replace(/^0x/, "").match(/.{1,2}/g);
-  if (!arr)
-    return new Uint8Array();
-  return new Uint8Array(arr.map((byte) => parseInt(byte, 16)));
+var initPromise = null;
+var threadPool = null;
+function initTfhe(tfheThreads = "auto") {
+  initPromise ??= (async () => {
+    try {
+      tfheModule = await import('tfhe');
+      await tfheModule.default();
+      await tfheModule.init_panic_hook();
+      threadPool = await initTfheThreadPool(tfheModule, tfheThreads);
+      console.log(
+        threadPool.enabled ? `[Worker] TFHE initialized (rayon thread pool: ${threadPool.threads} threads)` : `[Worker] TFHE initialized (single-threaded: ${threadPool.reason})`
+      );
+    } catch (error) {
+      console.error("[Worker] Failed to initialize TFHE:", error);
+      initPromise = null;
+      throw error;
+    }
+  })();
+  return initPromise;
 }
 if (typeof self !== "undefined") {
   self.onmessage = async (event) => {
-    const { id, type, fheKeyHex, crsHex, items, metadata } = event.data;
+    const { id, type, fheKeyHex, crsHex, items, metadata, tfheThreads } = event.data;
     if (type !== "zkProve") {
       self.postMessage({
         id,
@@ -36,7 +36,7 @@ if (typeof self !== "undefined") {
       return;
     }
     try {
-      await initTfhe();
+      await initTfhe(tfheThreads);
       if (!tfheModule) {
         throw new Error("TFHE module not initialized");
       }

package/node/index.ts

@@ -10,6 +10,7 @@ import {
   type FheKeyDeserializer,
   TFHE_RS_SAFE_SERIALIZATION_SIZE_LIMIT,
 } from '@/core';
+import { fromHexString } from '../core/utils.js';
 
 // Import node-specific storage (internal use only)
 import { createNodeStorage } from './storage.js';
@@ -30,16 +31,6 @@ async function initTfhe(): Promise<boolean> {
   return true;
 }
 
-/**
- * Utility to convert the hex string key to a Uint8Array for use with tfhe
- */
-const fromHexString = (hexString: string): Uint8Array => {
-  const cleanString = hexString.length % 2 === 1 ? `0${hexString}` : hexString;
-  const arr = cleanString.replace(/^0x/, '').match(/.{1,2}/g);
-  if (!arr) return new Uint8Array();
-  return new Uint8Array(arr.map((byte) => parseInt(byte, 16)));
-};
-
 const _deserializeTfhePublicKey = (buff: string): TfheCompactPublicKey => {
   return TfheCompactPublicKey.safe_deserialize(fromHexString(buff), TFHE_RS_SAFE_SERIALIZATION_SIZE_LIMIT);
 };

package/node/storage.ts

@@ -6,7 +6,18 @@ import { promises as fs } from 'fs';
 import { join } from 'path';
 
 // Memory storage fallback
-const memoryStorage: Record<string, string> = {};
+const memoryStorage: Record<string, unknown> = {};
+
+const getStorageDir = () => join(process.env.HOME || process.env.USERPROFILE || '.', '.cofhesdk');
+
+/**
+ * Keep the directory and files private to the current user. `mode` only applies
+ * on creation, so chmod also tightens directories/files created by earlier SDK versions.
+ */
+const ensureStorageDir = async (storageDir: string) => {
+  await fs.mkdir(storageDir, { recursive: true, mode: 0o700 });
+  await fs.chmod(storageDir, 0o700).catch(() => {});
+};
 
 /**
  * Creates a node storage implementation using the filesystem
@@ -16,8 +27,8 @@ export const createNodeStorage = (): IStorage => {
   return {
     getItem: async (name: string) => {
       try {
-        const storageDir = join(process.env.HOME || process.env.USERPROFILE || '.', '.cofhesdk');
-        await fs.mkdir(storageDir, { recursive: true });
+        const storageDir = getStorageDir();
+        await ensureStorageDir(storageDir);
         const filePath = join(storageDir, `${name}.json`);
         const data = await fs.readFile(filePath, 'utf8').catch(() => null);
         return data ? JSON.parse(data) : null;
@@ -28,19 +39,19 @@ export const createNodeStorage = (): IStorage => {
     },
     setItem: async (name: string, value: any) => {
       try {
-        const storageDir = join(process.env.HOME || process.env.USERPROFILE || '.', '.cofhesdk');
-        await fs.mkdir(storageDir, { recursive: true });
+        const storageDir = getStorageDir();
+        await ensureStorageDir(storageDir);
         const filePath = join(storageDir, `${name}.json`);
-        await fs.writeFile(filePath, JSON.stringify(value));
+        await fs.writeFile(filePath, JSON.stringify(value), { mode: 0o600 });
+        await fs.chmod(filePath, 0o600).catch(() => {});
       } catch (e) {
         console.warn('Node.js filesystem modules not available, falling back to memory storage' + e);
-        memoryStorage[name] = JSON.stringify(value);
+        memoryStorage[name] = value;
       }
     },
     removeItem: async (name: string) => {
       try {
-        const storageDir = join(process.env.HOME || process.env.USERPROFILE || '.', '.cofhesdk');
-        const filePath = join(storageDir, `${name}.json`);
+        const filePath = join(getStorageDir(), `${name}.json`);
         await fs.unlink(filePath).catch(() => {});
       } catch (e) {
         console.warn('Node.js filesystem modules not available, falling back to memory storage' + e);

package/node/test/inherited.test.ts

@@ -16,6 +16,10 @@ import { privateKeyToAccount } from 'viem/accounts';
 import { arbitrumSepolia, baseSepolia, sepolia } from 'viem/chains';
 import { createCofheClient, createCofheConfig } from '../index.js';
 
+// Live-chain suite: needs the funded TEST_PRIVATE_KEY (transacts against pre-deployed
+// testnet fixtures). Without it — fork PRs, where secrets are unavailable — the suite
+// skips; CI runs it separately with the key (test-live job).
+const LIVE_TESTS = Boolean(TEST_PRIVATE_KEY);
 const DEFAULT_TEST_PRIVATE_KEY = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80';
 const BOB_PRIVATE_KEY = (TEST_PRIVATE_KEY || DEFAULT_TEST_PRIVATE_KEY) as `0x${string}`;
 const ALICE_PRIVATE_KEY = '0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d';
@@ -32,7 +36,7 @@ const VIEM_CHAINS: Record<number, Chain> = {
 const testViemChain = STAGING_TESTS ? stagingViemChain : arbitrumSepolia;
 const testCofheChain = STAGING_TESTS ? stagingCofhe : cofheArbSepolia;
 
-describe('@cofhe/node - Inherited Client Tests', () => {
+describe.skipIf(!LIVE_TESTS)('@cofhe/node - Inherited Client Tests', () => {
   let cofheClient: CofheClient;
   let publicClient: PublicClient;
   let bobWalletClient: WalletClient;

package/node/test/storage-memory-fallback.test.ts

@@ -0,0 +1,47 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { promises as fs } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+import { createNodeStorage } from '../storage.js';
+
+describe('createNodeStorage memory fallback', () => {
+  let originalHome: string | undefined;
+  let testDir: string;
+  let invalidHome: string;
+
+  beforeEach(async () => {
+    originalHome = process.env.HOME;
+    testDir = await fs.mkdtemp(join(tmpdir(), 'cofhesdk-storage-fallback-'));
+
+    // HOME points to a regular file, so creating HOME/.cofhesdk fails.
+    invalidHome = join(testDir, 'not-a-directory');
+    await fs.writeFile(invalidHome, 'file', 'utf8');
+    process.env.HOME = invalidHome;
+  });
+
+  afterEach(async () => {
+    if (originalHome === undefined) {
+      delete process.env.HOME;
+    } else {
+      process.env.HOME = originalHome;
+    }
+
+    await fs.rm(testDir, { recursive: true, force: true });
+  });
+
+  it('round-trips the same value when filesystem storage is unavailable', async () => {
+    const storage = createNodeStorage();
+    const value = {
+      state: {
+        fhe: { 1: { 0: 'key' } },
+        crs: { 1: 'crs' },
+      },
+      version: 0,
+    };
+
+    await storage.setItem('fallback-roundtrip', value);
+
+    await expect(storage.getItem('fallback-roundtrip')).resolves.toEqual(value);
+  });
+});

package/node/test/storage-permissions.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'vitest';
+import { promises as fs } from 'fs';
+import os from 'os';
+import path from 'path';
+import { createNodeStorage } from '../storage.js';
+
+const withTempHome = async (fn: (home: string) => Promise<void>) => {
+  const home = await fs.mkdtemp(path.join(os.tmpdir(), 'cofhe-home-'));
+  const oldHome = process.env.HOME;
+  process.env.HOME = home;
+  try {
+    await fn(home);
+  } finally {
+    if (oldHome === undefined) delete process.env.HOME;
+    else process.env.HOME = oldHome;
+    await fs.rm(home, { recursive: true, force: true });
+  }
+};
+
+describe('node storage permissions', () => {
+  it.skipIf(process.platform === 'win32')('does not make stored data readable by other users', () =>
+    withTempHome(async (home) => {
+      await createNodeStorage().setItem('t', { value: 1 });
+      const st = await fs.stat(path.join(home, '.cofhesdk', 't.json'));
+      expect(st.mode & 0o077).toBe(0);
+    })
+  );
+
+  it.skipIf(process.platform === 'win32')('tightens permissions of a file created with loose permissions', () =>
+    withTempHome(async (home) => {
+      const dir = path.join(home, '.cofhesdk');
+      await fs.mkdir(dir, { mode: 0o755 });
+      const file = path.join(dir, 't.json');
+      await fs.writeFile(file, '{}', { mode: 0o644 });
+      await createNodeStorage().setItem('t', { value: 1 });
+      expect((await fs.stat(file)).mode & 0o077).toBe(0);
+      expect((await fs.stat(dir)).mode & 0o077).toBe(0);
+    })
+  );
+});