@cofhe/sdk 0.4.0 → 0.5.1

package/node/test/inherited.test.ts

@@ -0,0 +1,244 @@
+import { Encryptable, FheTypes, type CofheClient } from '@/core';
+import { arbSepolia as cofheArbSepolia, getChainById } from '@/chains';
+import {
+  TEST_PRIVATE_KEY,
+  PRIMARY_TEST_CHAIN,
+  primaryTestChainRegistry,
+  isPrimaryTestChainReady,
+} from '@cofhe/test-setup';
+
+import { describe, it, expect, beforeAll, beforeEach } from 'vitest';
+import type { Chain, PublicClient, WalletClient } from 'viem';
+import { createPublicClient, createWalletClient, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { arbitrumSepolia, baseSepolia, sepolia } from 'viem/chains';
+import { createCofheClient, createCofheConfig } from '../index.js';
+
+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';
+
+const bobAccount = privateKeyToAccount(BOB_PRIVATE_KEY);
+const aliceAccount = privateKeyToAccount(ALICE_PRIVATE_KEY);
+
+const VIEM_CHAINS: Record<number, Chain> = {
+  421614: arbitrumSepolia,
+  84532: baseSepolia,
+  11155111: sepolia,
+};
+
+describe('@cofhe/node - Inherited Client Tests', () => {
+  let cofheClient: CofheClient;
+  let publicClient: PublicClient;
+  let bobWalletClient: WalletClient;
+  let aliceWalletClient: WalletClient;
+
+  beforeAll(() => {
+    publicClient = createPublicClient({
+      chain: arbitrumSepolia,
+      transport: http(),
+    });
+
+    bobWalletClient = createWalletClient({
+      chain: arbitrumSepolia,
+      transport: http(),
+      account: bobAccount,
+    });
+
+    aliceWalletClient = createWalletClient({
+      chain: arbitrumSepolia,
+      transport: http(),
+      account: aliceAccount,
+    });
+  });
+
+  beforeEach(() => {
+    const config = createCofheConfig({
+      supportedChains: [cofheArbSepolia],
+    });
+    cofheClient = createCofheClient(config);
+  });
+
+  describe('Client Creation', () => {
+    it('should create a client with expected surface', () => {
+      expect(cofheClient).toBeDefined();
+      expect(cofheClient.config).toBeDefined();
+      expect(cofheClient.connected).toBe(false);
+      expect(typeof cofheClient.connect).toBe('function');
+      expect(typeof cofheClient.disconnect).toBe('function');
+      expect(typeof cofheClient.encryptInputs).toBe('function');
+      expect(typeof cofheClient.decryptForView).toBe('function');
+      expect(typeof cofheClient.decryptForTx).toBe('function');
+      expect(typeof cofheClient.getSnapshot).toBe('function');
+      expect(typeof cofheClient.subscribe).toBe('function');
+      expect(cofheClient.permits).toBeDefined();
+    });
+  });
+
+  describe('Connection', () => {
+    it('should connect to a real chain', async () => {
+      await cofheClient.connect(publicClient, bobWalletClient);
+
+      expect(cofheClient.connected).toBe(true);
+
+      const snapshot = cofheClient.getSnapshot();
+      expect(snapshot.connected).toBe(true);
+      expect(snapshot.chainId).toBe(cofheArbSepolia.id);
+      expect(snapshot.account).toBe(bobAccount.address);
+    }, 30000);
+  });
+
+  describe('Encrypt Input', () => {
+    it('should encrypt a uint128 value', async () => {
+      await cofheClient.connect(publicClient, bobWalletClient);
+
+      const encrypted = await cofheClient.encryptInputs([Encryptable.uint128(100n)]).execute();
+
+      expect(encrypted).toBeDefined();
+      expect(encrypted.length).toBe(1);
+      expect(encrypted[0].utype).toBe(FheTypes.Uint128);
+      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);
+  });
+
+  describe('Self Permit', () => {
+    it('should create a self permit', async () => {
+      await cofheClient.connect(publicClient, bobWalletClient);
+
+      const permit = await cofheClient.permits.createSelf({
+        issuer: bobAccount.address,
+        name: 'Test Self Permit',
+      });
+
+      expect(permit).toBeDefined();
+      expect(permit.type).toBe('self');
+      expect(permit.name).toBe('Test Self Permit');
+      expect(permit.issuer).toBe(bobAccount.address);
+      expect(permit.issuerSignature).not.toBe('0x');
+      expect(permit.sealingPair).toBeDefined();
+      expect(permit.sealingPair.publicKey).toBeDefined();
+
+      const activePermit = cofheClient.permits.getActivePermit();
+      expect(activePermit).toBeDefined();
+      expect(activePermit!.hash).toBe(permit.hash);
+    }, 30000);
+  });
+
+  describe('Sharing Permit', () => {
+    it('should create a sharing permit, export it, and import it as another user', async () => {
+      await cofheClient.connect(publicClient, bobWalletClient);
+
+      const sharingPermit = await cofheClient.permits.createSharing({
+        issuer: bobAccount.address,
+        recipient: aliceAccount.address,
+        name: 'Test Sharing Permit',
+      });
+
+      expect(sharingPermit).toBeDefined();
+      expect(sharingPermit.type).toBe('sharing');
+      expect(sharingPermit.issuer).toBe(bobAccount.address);
+      expect(sharingPermit.recipient).toBe(aliceAccount.address);
+      expect(sharingPermit.issuerSignature).not.toBe('0x');
+
+      const exported = cofheClient.permits.export(sharingPermit);
+      expect(exported).toBeDefined();
+      const parsed = JSON.parse(exported);
+      expect(parsed.type).toBe('sharing');
+      expect(parsed.issuer).toBe(bobAccount.address);
+      expect(parsed.recipient).toBe(aliceAccount.address);
+      expect(parsed.issuerSignature).toBeDefined();
+      expect(parsed).not.toHaveProperty('sealingPair');
+
+      const aliceConfig = createCofheConfig({
+        supportedChains: [cofheArbSepolia],
+      });
+      const aliceClient = createCofheClient(aliceConfig);
+      await aliceClient.connect(publicClient, aliceWalletClient);
+
+      const importedPermit = await aliceClient.permits.importShared(exported);
+
+      expect(importedPermit).toBeDefined();
+      expect(importedPermit.type).toBe('recipient');
+      expect(importedPermit.issuer).toBe(bobAccount.address);
+      expect(importedPermit.recipient).toBe(aliceAccount.address);
+      expect(importedPermit.recipientSignature).not.toBe('0x');
+      expect(importedPermit.sealingPair).toBeDefined();
+    }, 30000);
+  });
+
+  describe('Decrypt (read-only, pre-stored values)', () => {
+    let decryptClient: CofheClient;
+    let decryptPublicClient: PublicClient;
+    let decryptWalletClient: WalletClient;
+
+    let privateCtHash: `0x${string}`;
+    let privateValue: bigint;
+    let publicCtHash: `0x${string}`;
+    let publicValue: bigint;
+
+    beforeAll(() => {
+      if (!isPrimaryTestChainReady(primaryTestChainRegistry)) {
+        throw new Error('Primary test chain registry not initialized. Run `pnpm test:setup` first.');
+      }
+
+      const reg = primaryTestChainRegistry;
+      const viemChain = VIEM_CHAINS[reg.chainId];
+      if (!viemChain) throw new Error(`No viem chain mapping for chain ${reg.chainId}`);
+
+      const cofheChain = getChainById(reg.chainId);
+      if (!cofheChain) throw new Error(`No cofhe chain config for chain ${reg.chainId}`);
+
+      privateCtHash = reg.privateValue.ctHash as `0x${string}`;
+      privateValue = BigInt(reg.privateValue.value);
+      publicCtHash = reg.publicValue.ctHash as `0x${string}`;
+      publicValue = BigInt(reg.publicValue.value);
+
+      decryptPublicClient = createPublicClient({ chain: viemChain, transport: http() });
+      decryptWalletClient = createWalletClient({ chain: viemChain, transport: http(), account: bobAccount });
+
+      const config = createCofheConfig({ supportedChains: [cofheChain] });
+      decryptClient = createCofheClient(config);
+    });
+
+    it('decryptForView — private value with permit', async () => {
+      await decryptClient.connect(decryptPublicClient, decryptWalletClient);
+
+      await decryptClient.permits.createSelf({
+        issuer: bobAccount.address,
+        name: 'Decrypt View Permit',
+      });
+
+      const result = await decryptClient.decryptForView(privateCtHash, FheTypes.Uint32).execute();
+      expect(result).toBe(privateValue);
+    }, 180000);
+
+    it('decryptForTx — public value without permit', async () => {
+      await decryptClient.connect(decryptPublicClient, decryptWalletClient);
+
+      const result = await decryptClient.decryptForTx(publicCtHash).withoutPermit().execute();
+
+      expect(BigInt(result.ctHash)).toBe(BigInt(publicCtHash));
+      expect(result.decryptedValue).toBe(publicValue);
+      expect(result.signature).toMatch(/^0x[0-9a-fA-F]+$/);
+    }, 180000);
+
+    it('decryptForTx — private value with permit', async () => {
+      await decryptClient.connect(decryptPublicClient, decryptWalletClient);
+
+      const permit = await decryptClient.permits.createSelf({
+        issuer: bobAccount.address,
+        name: 'Decrypt Tx Permit',
+      });
+
+      const result = await decryptClient.decryptForTx(privateCtHash).withPermit(permit).execute();
+
+      expect(BigInt(result.ctHash)).toBe(BigInt(privateCtHash));
+      expect(result.decryptedValue).toBe(privateValue);
+      expect(result.signature).toBeDefined();
+    }, 180000);
+  });
+});

package/node/test/tfheinit.test.ts

@@ -0,0 +1,56 @@
+import { Encryptable, type CofheClient } 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';
+
+const TEST_PRIVATE_KEY = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80';
+
+describe('@cofhe/node - TFHE Initialization Tests', () => {
+  let cofheClient: CofheClient;
+  let publicClient: PublicClient;
+  let walletClient: WalletClient;
+
+  beforeAll(() => {
+    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('Node TFHE Initialization', () => {
+    it('should initialize node-tfhe on first encryption', async () => {
+      await cofheClient.connect(publicClient, walletClient);
+
+      const result = await cofheClient.encryptInputs([Encryptable.uint128(100n)]).execute();
+
+      expect(result).toBeDefined();
+    }, 60000);
+
+    it('should handle multiple encryptions without re-initializing', async () => {
+      await cofheClient.connect(publicClient, walletClient);
+
+      await cofheClient.encryptInputs([Encryptable.uint128(100n)]).execute();
+
+      await cofheClient.encryptInputs([Encryptable.uint64(50n)]).execute();
+    }, 120000);
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cofhe/sdk",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "type": "module",
   "description": "SDK for Fhenix COFHE coprocessor interaction",
   "main": "./dist/core.cjs",
@@ -57,14 +57,14 @@
     "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"
+    "iframe-shared-storage": "1.0.34",
+    "immer": "10.1.1",
+    "node-tfhe": "1.5.3",
+    "tfhe": "1.5.3",
+    "tweetnacl": "1.0.3",
+    "viem": "2.38.6",
+    "zod": "4.0.0",
+    "zustand": "5.0.1"
   },
   "peerDependencies": {
     "@nomicfoundation/hardhat-ethers": "^3.0.0",
@@ -88,24 +88,26 @@
     }
   },
   "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",
+    "@nomicfoundation/hardhat-ethers": "3.1.0",
+    "@types/node": "20.19.15",
+    "@vitest/browser": "3.2.4",
+    "@vitest/coverage-v8": "3.2.4",
+    "eslint": "8.57.1",
+    "ethers5": "npm:ethers@5.8.0",
+    "ethers6": "npm:ethers@6.15.0",
+    "happy-dom": "15.11.7",
+    "hardhat": "2.26.3",
+    "playwright": "1.55.0",
+    "tsup": "8.0.2",
     "typescript": "5.5.4",
-    "vitest": "^3.0.0",
+    "vitest": "3.2.4",
     "@cofhe/eslint-config": "0.2.1",
+    "@cofhe/test-setup": "0.0.0",
     "@cofhe/tsconfig": "0.1.2"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
     "build": "tsup",

package/permits/permit.ts

@@ -22,7 +22,6 @@ import {
   validateImportPermit,
   ValidationUtils,
 } from './validation.js';
-import * as z from 'zod';
 import { SignatureUtils } from './signature.js';
 import { GenerateSealingKey, SealingKey } from './sealing.js';
 import { checkPermitValidityOnChain, getAclEIP712Domain } from './onchain-utils.js';
@@ -217,9 +216,9 @@ export const PermitUtils = {
   },
 
   /**
-   * Validate a permit
+   * Validate a permit (schema-level validation)
    */
-  validate: (permit: Permit) => {
+  validateSchema: (permit: Permit) => {
     if (permit.type === 'self') {
       return validateSelfPermit(permit);
     } else if (permit.type === 'sharing') {
@@ -231,12 +230,28 @@ export const PermitUtils = {
     }
   },
 
+  /**
+   * Validate a permit (holistic validation).
+   *
+   * This validates:
+   * - Permit schema (shape + invariants)
+   * - Permit is signed
+   * - Permit is not expired
+   *
+   * For schema-only validation, use `validateSchema(permit)`.
+   */
+  validate: (permit: Permit) => {
+    const validated = PermitUtils.validateSchema(permit);
+    ValidationUtils.assertSignedAndNotExpired(validated as Permit);
+    return validated;
+  },
+
   /**
    * Get the permission object from a permit (for use in contracts)
    */
   getPermission: (permit: Permit, skipValidation = false): Permission => {
     if (!skipValidation) {
-      PermitUtils.validate(permit);
+      PermitUtils.validateSchema(permit);
     }
 
     return {
@@ -308,8 +323,19 @@ export const PermitUtils = {
   },
 
   /**
-   * Check if permit is valid
+   * Check if permit is signed and not expired
    */
+  isSignedAndNotExpired: (permit: Permit) => {
+    return ValidationUtils.isSignedAndNotExpired(permit);
+  },
+
+  /**
+   * Assert that permit is signed and not expired
+   */
+  assertSignedAndNotExpired: (permit: Permit): void => {
+    return ValidationUtils.assertSignedAndNotExpired(permit);
+  },
+
   isValid: (permit: Permit) => {
     return ValidationUtils.isValid(permit);
   },

package/permits/sealing.ts

@@ -1,4 +1,4 @@
-import * as nacl from 'tweetnacl';
+import nacl from 'tweetnacl';
 import { fromHexString, toBeArray, toBigInt, toHexString, isBigIntOrNumber, isString } from './utils.js';
 
 const PRIVATE_KEY_LENGTH = 64;

package/permits/{localstorage.test.ts → test/localstorage.test.ts}

@@ -11,8 +11,8 @@ import {
   setActivePermitHash,
   PermitUtils,
   permitStore,
-} from './index.js';
-import { createMockPermit } from './test-utils.js';
+} from '../index.js';
+import { createMockPermit } from '../test-utils.js';
 
 // Type declarations for happy-dom environment
 declare const localStorage: {

package/permits/{permit.test.ts → test/permit.test.ts}

@@ -4,7 +4,7 @@ import {
   type CreateSelfPermitOptions,
   type CreateSharingPermitOptions,
   type ImportSharedPermitOptions,
-} from './index.js';
+} from '../index.js';
 import { createPublicClient, createWalletClient, http, type PublicClient, type WalletClient } from 'viem';
 import { arbitrumSepolia } from 'viem/chains';
 import { privateKeyToAccount } from 'viem/accounts';
@@ -399,6 +399,29 @@ describe('PermitUtils Tests', () => {
       expect(parsed).not.toHaveProperty('sealingPair');
       expect(parsed).not.toHaveProperty('issuerSignature');
     });
+
+    it('should export sharing permit data with recipient and issuerSignature', async () => {
+      const permit = await PermitUtils.createSharingAndSign(
+        {
+          issuer: bobAddress,
+          recipient: aliceAddress,
+          name: 'Test Sharing Permit',
+        },
+        publicClient,
+        bobWalletClient
+      );
+
+      const exported = PermitUtils.export(permit);
+      const parsed = JSON.parse(exported);
+
+      expect(parsed.name).toBe('Test Sharing Permit');
+      expect(parsed.type).toBe('sharing');
+      expect(parsed.issuer).toBe(bobAddress);
+      expect(parsed.recipient).toBe(aliceAddress);
+      expect(parsed.issuerSignature).toBeDefined();
+      expect(parsed.issuerSignature).not.toBe('0x');
+      expect(parsed).not.toHaveProperty('sealingPair');
+    });
   });
 
   describe('updateName', () => {
@@ -459,6 +482,17 @@ describe('PermitUtils Tests', () => {
       expect(validation.valid).toBe(true);
       expect(validation.error).toBeNull();
     });
+
+    it('should throw on validate() for expired signed permit', async () => {
+      const expiredPermit = PermitUtils.createSelf({
+        issuer: bobAddress,
+        name: 'Expired Permit',
+        expiration: Math.floor(Date.now() / 1000) - 3600,
+      });
+
+      const signedExpiredPermit = await PermitUtils.sign(expiredPermit, publicClient, bobWalletClient);
+      expect(() => PermitUtils.validate(signedExpiredPermit)).toThrow('Permit is expired');
+    });
   });
 
   describe('real contract interactions', () => {

package/permits/{sealing.test.ts → test/sealing.test.ts}

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { SealingKey, GenerateSealingKey } from './index.js';
+import { SealingKey, GenerateSealingKey } from '../index.js';
 
 describe('SealingKey', () => {
   it('should create a SealingKey with valid keys', () => {

package/permits/{store.test.ts → test/store.test.ts}

@@ -13,9 +13,9 @@ import {
   getActivePermitHash,
   setActivePermitHash,
   PermitUtils,
-} from './index.js';
+} from '../index.js';
 
-import { createMockPermit } from './test-utils.js';
+import { createMockPermit } from '../test-utils.js';
 
 describe('Storage Tests', () => {
   const chainId = 1;

package/permits/{validation.test.ts → test/validation.test.ts}

@@ -11,8 +11,8 @@ import {
   type CreateSelfPermitOptions,
   type CreateSharingPermitOptions,
   type ImportSharedPermitOptions,
-} from './index.js';
-import { createMockPermit } from './test-utils.js';
+} from '../index.js';
+import { createMockPermit } from '../test-utils.js';
 
 describe('Validation Tests', () => {
   describe('validateSelfPermitOptions', () => {
@@ -247,14 +247,14 @@ describe('Validation Tests', () => {
       });
     });
 
-    describe('isValid', () => {
+    describe('isSignedAndNotExpired', () => {
       it('should return valid for valid permit', async () => {
         const permit = {
           ...(await createMockPermit()),
           expiration: Math.floor(Date.now() / 1000) + 3600,
           issuerSignature: '0x1234567890abcdef' as `0x${string}`,
         };
-        const result = ValidationUtils.isValid(permit);
+        const result = ValidationUtils.isSignedAndNotExpired(permit);
         expect(result.valid).toBe(true);
         expect(result.error).toBeNull();
       });
@@ -265,7 +265,7 @@ describe('Validation Tests', () => {
           expiration: Math.floor(Date.now() / 1000) - 3600,
           issuerSignature: '0x1234567890abcdef' as `0x${string}`,
         };
-        const result = ValidationUtils.isValid(permit);
+        const result = ValidationUtils.isSignedAndNotExpired(permit);
         expect(result.valid).toBe(false);
         expect(result.error).toBe('expired');
       });
@@ -276,10 +276,86 @@ describe('Validation Tests', () => {
           expiration: Math.floor(Date.now() / 1000) + 3600,
           issuerSignature: '0x' as `0x${string}`,
         };
-        const result = ValidationUtils.isValid(permit);
+        const result = ValidationUtils.isSignedAndNotExpired(permit);
         expect(result.valid).toBe(false);
         expect(result.error).toBe('not-signed');
       });
     });
+
+    describe('assertSignedAndNotExpired', () => {
+      it('should not throw for valid permit', async () => {
+        const permit = {
+          ...(await createMockPermit()),
+          expiration: Math.floor(Date.now() / 1000) + 3600,
+          issuerSignature: '0x1234567890abcdef' as `0x${string}`,
+        };
+        expect(() => ValidationUtils.assertSignedAndNotExpired(permit)).not.toThrow();
+      });
+
+      it('should throw for expired permit', async () => {
+        const permit = {
+          ...(await createMockPermit()),
+          expiration: Math.floor(Date.now() / 1000) - 3600,
+          issuerSignature: '0x1234567890abcdef' as `0x${string}`,
+        };
+        expect(() => ValidationUtils.assertSignedAndNotExpired(permit)).toThrow('Permit is expired');
+      });
+
+      it('should throw for unsigned permit', async () => {
+        const permit = {
+          ...(await createMockPermit()),
+          expiration: Math.floor(Date.now() / 1000) + 3600,
+          issuerSignature: '0x' as `0x${string}`,
+        };
+        expect(() => ValidationUtils.assertSignedAndNotExpired(permit)).toThrow('Permit is not signed');
+      });
+    });
+
+    describe('isValid', () => {
+      it('should return invalid-schema for schema-invalid permit', async () => {
+        const permit = {
+          ...(await createMockPermit()),
+          type: 'self' as const,
+          expiration: Math.floor(Date.now() / 1000) + 3600,
+          issuerSignature: '0x1234567890abcdef' as `0x${string}`,
+          // Self permits must have recipient == zeroAddress per schema.
+          recipient: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8' as `0x${string}`,
+        };
+
+        const result = ValidationUtils.isValid(permit as unknown as Permit);
+        expect(result.valid).toBe(false);
+        expect(result.error).toBe('invalid-schema');
+      });
+
+      it('should return expired for expired but otherwise schema-valid permit', async () => {
+        const permit = {
+          ...(await createMockPermit()),
+          type: 'self' as const,
+          expiration: Math.floor(Date.now() / 1000) - 3600,
+          issuerSignature: '0x1234567890abcdef' as `0x${string}`,
+          recipient: '0x0000000000000000000000000000000000000000' as `0x${string}`,
+          recipientSignature: '0x' as `0x${string}`,
+        };
+
+        const result = ValidationUtils.isValid(permit as unknown as Permit);
+        expect(result.valid).toBe(false);
+        expect(result.error).toBe('expired');
+      });
+
+      it('should return valid for schema-valid, signed, non-expired permit', async () => {
+        const permit = {
+          ...(await createMockPermit()),
+          type: 'self' as const,
+          expiration: Math.floor(Date.now() / 1000) + 3600,
+          issuerSignature: '0x1234567890abcdef' as `0x${string}`,
+          recipient: '0x0000000000000000000000000000000000000000' as `0x${string}`,
+          recipientSignature: '0x' as `0x${string}`,
+        };
+
+        const result = ValidationUtils.isValid(permit as unknown as Permit);
+        expect(result.valid).toBe(true);
+        expect(result.error).toBeNull();
+      });
+    });
   });
 });

package/permits/types.ts

@@ -189,7 +189,7 @@ export type PermitHashFields = Pick<
  */
 export interface ValidationResult {
   valid: boolean;
-  error: string | null;
+  error: 'invalid-schema' | 'expired' | 'not-signed' | null;
 }
 
 /**