@cofhe/sdk 0.0.0-alpha-20260409113701

package/node/config.test.ts

@@ -0,0 +1,68 @@
+import { arbSepolia } from '@/chains';
+
+import { describe, it, expect } from 'vitest';
+import { createCofheConfig, createCofheClient } from './index.js';
+
+describe('@cofhe/node - Config', () => {
+  describe('createCofheConfig', () => {
+    it('should automatically inject filesystem storage as default', () => {
+      const config = createCofheConfig({
+        supportedChains: [arbSepolia],
+      });
+
+      expect(config.fheKeyStorage).toBeDefined();
+      expect(config.fheKeyStorage).not.toBeNull();
+      expect(config.supportedChains).toEqual([arbSepolia]);
+    });
+
+    it('should allow overriding storage', async () => {
+      const customStorage = {
+        getItem: () => Promise.resolve(10),
+        setItem: () => Promise.resolve(),
+        removeItem: () => Promise.resolve(),
+      };
+      const config = createCofheConfig({
+        supportedChains: [arbSepolia],
+        fheKeyStorage: customStorage,
+      });
+
+      expect(await config.fheKeyStorage!.getItem('test')).toBe(10);
+    });
+
+    it('should allow null storage', () => {
+      const config = createCofheConfig({
+        supportedChains: [arbSepolia],
+        fheKeyStorage: null,
+      });
+
+      expect(config.fheKeyStorage).toBeNull();
+    });
+
+    it('should preserve all other config options', () => {
+      const config = createCofheConfig({
+        supportedChains: [arbSepolia],
+        mocks: {
+          decryptDelay: 0,
+        },
+      });
+
+      expect(config.supportedChains).toEqual([arbSepolia]);
+      expect(config.mocks.decryptDelay).toBe(0);
+      expect(config.fheKeyStorage).toBeDefined();
+    });
+  });
+
+  describe('createCofheClient with config', () => {
+    it('should create client with validated config', () => {
+      const config = createCofheConfig({
+        supportedChains: [arbSepolia],
+      });
+
+      const client = createCofheClient(config);
+
+      expect(client).toBeDefined();
+      expect(client.config).toBe(config);
+      expect(client.config.fheKeyStorage).toBeDefined();
+    });
+  });
+});

package/node/encryptInputs.test.ts

@@ -0,0 +1,155 @@
+import { Encryptable, FheTypes, type CofheClient, CofheErrorCode, CofheError } from '@/core';
+import { arbSepolia as cofheArbSepolia } from '@/chains';
+
+import { describe, it, expect, beforeAll, beforeEach } from 'vitest';
+import type { PublicClient, WalletClient } from 'viem';
+import { createPublicClient, createWalletClient, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { arbitrumSepolia as viemArbitrumSepolia } from 'viem/chains';
+import { createCofheClient, createCofheConfig } from './index.js';
+
+// Real test setup - using actual node-tfhe
+const TEST_PRIVATE_KEY = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80';
+
+describe('@cofhe/node - Encrypt Inputs', () => {
+  let cofheClient: CofheClient;
+  let publicClient: PublicClient;
+  let walletClient: WalletClient;
+
+  beforeAll(() => {
+    // Create real viem clients
+    publicClient = createPublicClient({
+      chain: viemArbitrumSepolia,
+      transport: http(),
+    });
+
+    const account = privateKeyToAccount(TEST_PRIVATE_KEY);
+    walletClient = createWalletClient({
+      chain: viemArbitrumSepolia,
+      transport: http(),
+      account,
+    });
+  });
+
+  beforeEach(() => {
+    const config = createCofheConfig({
+      supportedChains: [cofheArbSepolia],
+    });
+    cofheClient = createCofheClient(config);
+  });
+
+  describe('Real TFHE Initialization', () => {
+    it('should initialize node-tfhe on first encryption', async () => {
+      await cofheClient.connect(publicClient, walletClient);
+
+      // This will trigger real TFHE initialization
+      const encrypted = await cofheClient.encryptInputs([Encryptable.uint128(100n)]).execute();
+
+      // If we get here, TFHE was initialized successfully
+      expect(encrypted).toBeDefined();
+    }, 60000); // Longer timeout for real operations
+
+    it('should handle multiple encryptions without re-initializing', async () => {
+      await cofheClient.connect(publicClient, walletClient);
+
+      // First encryption
+      await cofheClient.encryptInputs([Encryptable.uint128(100n)]).execute();
+
+      // Second encryption should reuse initialization
+      await cofheClient.encryptInputs([Encryptable.uint64(50n)]).execute();
+    }, 120000);
+  });
+
+  describe('Real Encryption', () => {
+    it('should encrypt a bool with real TFHE', async () => {
+      await cofheClient.connect(publicClient, walletClient);
+
+      const encrypted = await cofheClient.encryptInputs([Encryptable.bool(true)]).execute();
+
+      expect(encrypted.length).toBe(1);
+      expect(encrypted[0].utype).toBe(FheTypes.Bool);
+      expect(encrypted[0].ctHash).toBeDefined();
+      expect(typeof encrypted[0].ctHash).toBe('bigint');
+      expect(encrypted[0].signature).toBeDefined();
+      expect(typeof encrypted[0].signature).toBe('string');
+      expect(encrypted[0].securityZone).toBe(0);
+    }, 60000);
+
+    it('should encrypt all supported types together', async () => {
+      await cofheClient.connect(publicClient, walletClient);
+
+      const inputs = [
+        Encryptable.bool(false),
+        Encryptable.uint8(1n),
+        Encryptable.uint16(2n),
+        Encryptable.uint32(3n),
+        Encryptable.uint64(4n),
+        Encryptable.uint128(5n),
+        Encryptable.address('0x742d35Cc6634C0532925a3b844D16faC4c175E99'),
+      ];
+
+      const encrypted = await cofheClient.encryptInputs(inputs).execute();
+
+      expect(encrypted.length).toBe(7);
+      // Verify each type
+      expect(encrypted[0].utype).toBe(FheTypes.Bool);
+      expect(encrypted[1].utype).toBe(FheTypes.Uint8);
+      expect(encrypted[2].utype).toBe(FheTypes.Uint16);
+      expect(encrypted[3].utype).toBe(FheTypes.Uint32);
+      expect(encrypted[4].utype).toBe(FheTypes.Uint64);
+      expect(encrypted[5].utype).toBe(FheTypes.Uint128);
+      expect(encrypted[6].utype).toBe(FheTypes.Uint160);
+    }, 90000); // Longer timeout for multiple encryptions
+  });
+
+  describe('Real Builder Pattern', () => {
+    it('should support chaining builder methods with real encryption', async () => {
+      await cofheClient.connect(publicClient, walletClient);
+
+      const snapshot = cofheClient.getSnapshot();
+      const encrypted = await cofheClient
+        .encryptInputs([Encryptable.uint128(100n)])
+        .setChainId(snapshot.chainId!)
+        .setAccount(snapshot.account!)
+        .setSecurityZone(0)
+        .execute();
+
+      expect(encrypted.length).toBe(1);
+      expect(encrypted[0].utype).toBe(FheTypes.Uint128);
+    }, 60000);
+  });
+
+  describe('Real Error Handling', () => {
+    it('should fail gracefully when not connected', async () => {
+      // Don't connect the client
+      try {
+        await cofheClient.encryptInputs([Encryptable.uint128(100n)]).execute();
+      } catch (error) {
+        expect(error).toBeInstanceOf(CofheError);
+        expect((error as CofheError).code).toBe(CofheErrorCode.NotConnected);
+      }
+    }, 30000);
+
+    it('should handle invalid CoFHE URL', async () => {
+      const badConfig = createCofheConfig({
+        supportedChains: [
+          {
+            ...cofheArbSepolia,
+            coFheUrl: 'http://invalid-cofhe-url.local',
+            verifierUrl: 'http://invalid-verifier-url.local',
+          },
+        ],
+      });
+
+      const badClient = createCofheClient(badConfig);
+      await badClient.connect(publicClient, walletClient);
+
+      try {
+        await badClient.encryptInputs([Encryptable.uint128(100n)]).execute();
+      } catch (error) {
+        expect(error).toBeInstanceOf(CofheError);
+        expect((error as CofheError).code).toBe(CofheErrorCode.ZkVerifyFailed);
+      }
+    }, 60000);
+  });
+});

package/node/index.ts

@@ -0,0 +1,97 @@
+// Node.js specific functionality only
+
+import {
+  createCofheClientBase,
+  createCofheConfigBase,
+  type CofheClient,
+  type CofheConfig,
+  type CofheInputConfig,
+  type ZkBuilderAndCrsGenerator,
+  type FheKeyDeserializer,
+} from '@/core';
+
+// Import node-specific storage (internal use only)
+import { createNodeStorage } from './storage.js';
+
+// Import node-tfhe for Node.js
+import { TfheCompactPublicKey, ProvenCompactCiphertextList, CompactPkeCrs, init_panic_hook } from 'node-tfhe';
+
+/**
+ * Internal function to initialize TFHE for Node.js
+ * Called automatically on first encryption - users don't need to call this manually
+ * @returns true if TFHE was initialized, false if already initialized
+ */
+let tfheInitialized = false;
+async function initTfhe(): Promise<boolean> {
+  if (tfheInitialized) return false;
+  await init_panic_hook();
+  tfheInitialized = true;
+  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)));
+};
+
+/**
+ * Serializer for TFHE public keys
+ * Validates that the buffer can be deserialized into a TfheCompactPublicKey
+ */
+const tfhePublicKeyDeserializer: FheKeyDeserializer = (buff: string): void => {
+  TfheCompactPublicKey.deserialize(fromHexString(buff));
+};
+
+/**
+ * Serializer for Compact PKE CRS
+ * Validates that the buffer can be deserialized into ZkCompactPkePublicParams
+ */
+const compactPkeCrsDeserializer: FheKeyDeserializer = (buff: string): void => {
+  CompactPkeCrs.deserialize(fromHexString(buff));
+};
+
+/**
+ * Creates a ZK builder and CRS from FHE public key and CRS buffers
+ * This is used internally by the SDK to create encrypted inputs
+ */
+const zkBuilderAndCrsGenerator: ZkBuilderAndCrsGenerator = (fhe: string, crs: string) => {
+  const fhePublicKey = TfheCompactPublicKey.deserialize(fromHexString(fhe));
+  const zkBuilder = ProvenCompactCiphertextList.builder(fhePublicKey);
+  const zkCrs = CompactPkeCrs.deserialize(fromHexString(crs));
+
+  return { zkBuilder, zkCrs };
+};
+
+/**
+ * Creates a CoFHE configuration for Node.js with filesystem storage as default
+ * @param config - The CoFHE input configuration (fheKeyStorage will default to filesystem if not provided)
+ * @returns The CoFHE configuration with Node.js defaults applied
+ */
+export function createCofheConfig(config: CofheInputConfig): CofheConfig {
+  return createCofheConfigBase({
+    environment: 'node',
+    ...config,
+    fheKeyStorage: config.fheKeyStorage === null ? null : config.fheKeyStorage ?? createNodeStorage(),
+  });
+}
+
+/**
+ * Creates a CoFHE client instance for Node.js with node-tfhe automatically configured
+ * TFHE will be initialized automatically on first encryption - no manual setup required
+ * @param config - The CoFHE configuration (use createCofheConfig to create with Node.js defaults)
+ * @returns The CoFHE client instance
+ */
+export function createCofheClient(config: CofheConfig): CofheClient {
+  return createCofheClientBase({
+    config,
+    zkBuilderAndCrsGenerator,
+    tfhePublicKeyDeserializer,
+    compactPkeCrsDeserializer,
+    initTfhe,
+  });
+}

package/node/storage.ts

@@ -0,0 +1,51 @@
+/* eslint-disable turbo/no-undeclared-env-vars */
+
+import type { IStorage } from '@/core';
+
+import { promises as fs } from 'fs';
+import { join } from 'path';
+
+// Memory storage fallback
+const memoryStorage: Record<string, string> = {};
+
+/**
+ * Creates a node storage implementation using the filesystem
+ * @returns IStorage implementation for Node.js environments
+ */
+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 filePath = join(storageDir, `${name}.json`);
+        const data = await fs.readFile(filePath, 'utf8').catch(() => null);
+        return data ? JSON.parse(data) : null;
+      } catch (e) {
+        console.warn('Node.js filesystem modules not available, falling back to memory storage' + e);
+        return memoryStorage[name] || null;
+      }
+    },
+    setItem: async (name: string, value: any) => {
+      try {
+        const storageDir = join(process.env.HOME || process.env.USERPROFILE || '.', '.cofhesdk');
+        await fs.mkdir(storageDir, { recursive: true });
+        const filePath = join(storageDir, `${name}.json`);
+        await fs.writeFile(filePath, JSON.stringify(value));
+      } catch (e) {
+        console.warn('Node.js filesystem modules not available, falling back to memory storage' + e);
+        memoryStorage[name] = JSON.stringify(value);
+      }
+    },
+    removeItem: async (name: string) => {
+      try {
+        const storageDir = join(process.env.HOME || process.env.USERPROFILE || '.', '.cofhesdk');
+        const filePath = join(storageDir, `${name}.json`);
+        await fs.unlink(filePath).catch(() => {});
+      } catch (e) {
+        console.warn('Node.js filesystem modules not available, falling back to memory storage' + e);
+        delete memoryStorage[name];
+      }
+    },
+  };
+};

package/package.json

@@ -0,0 +1,121 @@
+{
+  "name": "@cofhe/sdk",
+  "version": "0.0.0-alpha-20260409113701",
+  "type": "module",
+  "description": "SDK for Fhenix COFHE coprocessor interaction",
+  "main": "./dist/core.cjs",
+  "module": "./dist/core.js",
+  "types": "./dist/core.d.ts",
+  "browser": "./dist/web.js",
+  "exports": {
+    ".": {
+      "import": "./dist/core.js",
+      "require": "./dist/core.cjs",
+      "types": "./dist/core.d.ts"
+    },
+    "./adapters": {
+      "import": "./dist/adapters.js",
+      "require": "./dist/adapters.cjs",
+      "types": "./dist/adapters.d.ts"
+    },
+    "./chains": {
+      "import": "./dist/chains.js",
+      "require": "./dist/chains.cjs",
+      "types": "./dist/chains.d.ts"
+    },
+    "./permits": {
+      "import": "./dist/permits.js",
+      "require": "./dist/permits.cjs",
+      "types": "./dist/permits.d.ts"
+    },
+    "./node": {
+      "import": "./dist/node.js",
+      "require": "./dist/node.cjs",
+      "types": "./dist/node.d.ts"
+    },
+    "./web": {
+      "import": "./dist/web.js",
+      "require": "./dist/web.cjs",
+      "types": "./dist/web.d.ts"
+    }
+  },
+  "sideEffects": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/FhenixProtocol/cofhesdk.git",
+    "directory": "packages/sdk"
+  },
+  "files": [
+    "dist/**",
+    "core/**",
+    "adapters/**",
+    "chains/**",
+    "permits/**",
+    "node/**",
+    "web/**",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "iframe-shared-storage": "^1.0.34",
+    "immer": "^10.1.1",
+    "node-tfhe": "0.11.1",
+    "tfhe": "0.11.1",
+    "tweetnacl": "^1.0.3",
+    "viem": "^2.38.6",
+    "zod": "^4.0.0",
+    "zustand": "^5.0.1"
+  },
+  "peerDependencies": {
+    "@nomicfoundation/hardhat-ethers": "^3.0.0",
+    "@wagmi/core": "^2.0.0",
+    "ethers": "^5.0.0 || ^6.0.0",
+    "hardhat": "^2.0.0",
+    "viem": "^2.38.6"
+  },
+  "peerDependenciesMeta": {
+    "@wagmi/core": {
+      "optional": true
+    },
+    "ethers": {
+      "optional": true
+    },
+    "hardhat": {
+      "optional": true
+    },
+    "@nomicfoundation/hardhat-ethers": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nomicfoundation/hardhat-ethers": "^3.0.0",
+    "@types/node": "^20.0.0",
+    "@vitest/browser": "^3.0.0",
+    "@vitest/coverage-v8": "^3.0.0",
+    "eslint": "^8.57.0",
+    "ethers5": "npm:ethers@^5.7.2",
+    "ethers6": "npm:ethers@^6.13.0",
+    "happy-dom": "^15.0.0",
+    "hardhat": "^2.19.0",
+    "playwright": "^1.55.0",
+    "tsup": "^8.0.2",
+    "typescript": "5.5.4",
+    "vitest": "^3.0.0",
+    "@cofhe/eslint-config": "0.2.1",
+    "@cofhe/tsconfig": "0.1.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint \"**/*.ts*\"",
+    "check:types": "tsc --noEmit",
+    "clean": "rm -rf .turbo && rm -rf node_modules && rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
+}

package/permits/index.ts

@@ -0,0 +1,68 @@
+// Core types
+export type {
+  Permit,
+  CreateSelfPermitOptions as SelfPermitOptions,
+  CreateSharingPermitOptions as SharingPermitOptions,
+  ImportSharedPermitOptions as ImportPermitOptions,
+  SerializedPermit,
+  PermitMetadata,
+  Permission,
+  EIP712Domain,
+  EIP712Types,
+  EIP712Message,
+  ValidationResult,
+  PermitSignaturePrimaryType,
+} from './types.js';
+
+// Main utilities
+export { PermitUtils } from './permit.js';
+
+// Validation utilities
+export {
+  // Self permit validators
+  SelfPermitOptionsValidator,
+  SelfPermitValidator,
+  validateSelfPermitOptions,
+  validateSelfPermit,
+  // Sharing permit validators
+  SharingPermitOptionsValidator,
+  SharingPermitValidator,
+  validateSharingPermitOptions,
+  validateSharingPermit,
+  // Import permit validators
+  ImportPermitOptionsValidator,
+  ImportPermitValidator,
+  validateImportPermitOptions,
+  validateImportPermit,
+  // Common utilities
+  ValidationUtils,
+} from './validation.js';
+
+// Signature utilities
+export { SignatureUtils, getSignatureTypesAndMessage, SignatureTypes } from './signature.js';
+
+// Storage utilities
+export {
+  permitStore,
+  getPermit,
+  getActivePermit,
+  getPermits,
+  setPermit,
+  removePermit,
+  getActivePermitHash,
+  setActivePermitHash,
+  removeActivePermitHash,
+  clearStaleStore,
+  PERMIT_STORE_DEFAULTS,
+} from './store.js';
+
+// Sealing utilities
+export { SealingKey, GenerateSealingKey } from './sealing.js';
+export type { EthEncryptedData } from './sealing.js';
+
+// Re-export everything for convenience
+export * from './types.js';
+export * from './permit.js';
+export * from './validation.js';
+export * from './signature.js';
+export * from './store.js';

package/permits/localstorage.test.ts

@@ -0,0 +1,113 @@
+/**
+ * @vitest-environment happy-dom
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  getPermit,
+  setPermit,
+  removePermit,
+  getActivePermitHash,
+  setActivePermitHash,
+  PermitUtils,
+  permitStore,
+} from './index.js';
+import { createMockPermit } from './test-utils.js';
+
+// Type declarations for happy-dom environment
+declare const localStorage: {
+  clear: () => void;
+  getItem: (name: string) => string | null;
+  setItem: (name: string, value: string) => void;
+};
+
+describe('Permits localStorage Tests', () => {
+  const chainId = 1;
+  const account = '0x1234567890123456789012345678901234567890';
+
+  beforeEach(() => {
+    // Clear localStorage and reset store state
+    localStorage.clear();
+    permitStore.resetStore();
+  });
+
+  afterEach(() => {
+    // Clean up after each test
+    localStorage.clear();
+    permitStore.resetStore();
+  });
+
+  it('should persist permits to localStorage', async () => {
+    const permit = await createMockPermit();
+
+    setPermit(chainId, account, permit);
+
+    // Verify data is stored in localStorage
+    const storedData = localStorage.getItem('cofhesdk-permits');
+    expect(storedData).toBeDefined();
+
+    const parsedData = JSON.parse(storedData!);
+    expect(parsedData.state.permits[chainId][account][permit.hash]).toBeDefined();
+  });
+
+  it('should persist active permit hash to localStorage', async () => {
+    const permit = await createMockPermit();
+
+    setPermit(chainId, account, permit);
+    setActivePermitHash(chainId, account, permit.hash);
+
+    // Verify active permit hash is stored
+    const storedData = localStorage.getItem('cofhesdk-permits');
+    expect(storedData).toBeDefined();
+
+    const parsedData = JSON.parse(storedData!);
+    expect(parsedData.state.activePermitHash[chainId][account]).toBe(permit.hash);
+  });
+
+  it('should restore permits from localStorage', async () => {
+    const permit = await createMockPermit();
+
+    // Add permit to localStorage
+    setPermit(chainId, account, permit);
+    setActivePermitHash(chainId, account, permit.hash);
+    const serializedPermit = PermitUtils.serialize(permit);
+
+    // Verify data is restored
+    const retrievedPermit = getPermit(chainId, account, permit.hash);
+    expect(retrievedPermit).toBeDefined();
+    expect(PermitUtils.serialize(retrievedPermit!)).toEqual(serializedPermit);
+
+    const activeHash = getActivePermitHash(chainId, account);
+    expect(activeHash).toBe(permit.hash);
+  });
+
+  it('should handle corrupted localStorage data gracefully', () => {
+    // Set invalid JSON in localStorage
+    localStorage.setItem('cofhesdk-permits', 'invalid json');
+
+    // Store should handle this gracefully
+    expect(() => {
+      permitStore.store.getState();
+    }).not.toThrow();
+  });
+
+  it('should clean up localStorage when permits are removed', async () => {
+    const permit = await createMockPermit();
+
+    setPermit(chainId, account, permit);
+    setActivePermitHash(chainId, account, permit.hash);
+
+    // Verify data exists
+    let storedData = localStorage.getItem('cofhesdk-permits');
+    expect(storedData).toBeDefined();
+
+    // Remove permit
+    removePermit(chainId, account, permit.hash);
+
+    // Verify data is cleaned up
+    storedData = localStorage.getItem('cofhesdk-permits');
+    const parsedData = JSON.parse(storedData!);
+    expect(parsedData.state.permits[chainId][account][permit.hash]).toBeUndefined();
+    expect(parsedData.state.activePermitHash[chainId][account]).toBeUndefined();
+  });
+});