@cofhe/sdk 0.0.0-alpha-20260409113701

package/permits/store.test.ts

@@ -0,0 +1,88 @@
+/**
+ * @vitest-environment node
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  permitStore,
+  getPermit,
+  getActivePermit,
+  getPermits,
+  setPermit,
+  removePermit,
+  getActivePermitHash,
+  setActivePermitHash,
+  PermitUtils,
+} from './index.js';
+
+import { createMockPermit } from './test-utils.js';
+
+describe('Storage Tests', () => {
+  const chainId = 1;
+  const account = '0x1234567890123456789012345678901234567890';
+
+  beforeEach(() => {
+    permitStore.resetStore();
+  });
+
+  afterEach(() => {
+    permitStore.resetStore();
+  });
+
+  describe('Permit Storage', () => {
+    it('should store and retrieve permits', async () => {
+      const permit = await createMockPermit();
+
+      setPermit(chainId, account, permit);
+      const retrieved = getPermit(chainId, account, permit.hash);
+
+      expect(retrieved).toBeDefined();
+      expect(PermitUtils.serialize(retrieved!)).toEqual(PermitUtils.serialize(permit));
+    });
+
+    it('should handle multiple permits per account', async () => {
+      const permit1 = await createMockPermit();
+      const permit2 = await createMockPermit({
+        issuer: '0x0987654321098765432109876543210987654321' as `0x${string}`,
+      });
+
+      setPermit(chainId, account, permit1);
+      setPermit(chainId, account, permit2);
+
+      const permits = getPermits(chainId, account);
+      expect(Object.keys(permits)).toHaveLength(2);
+
+      expect(PermitUtils.serialize(permits[permit1.hash])).toEqual(PermitUtils.serialize(permit1));
+      expect(PermitUtils.serialize(permits[permit2.hash])).toEqual(PermitUtils.serialize(permit2));
+    });
+
+    it('should handle active permit hash', async () => {
+      const permit = await createMockPermit();
+
+      setPermit(chainId, account, permit);
+      setActivePermitHash(chainId, account, permit.hash);
+
+      const activeHash = getActivePermitHash(chainId, account);
+      expect(activeHash).toBe(permit.hash);
+
+      const activePermit = getActivePermit(chainId, account);
+      expect(activePermit).toBeDefined();
+      expect(PermitUtils.serialize(activePermit!)).toEqual(PermitUtils.serialize(permit));
+    });
+
+    it('should remove permits', async () => {
+      const permit = await createMockPermit();
+
+      setPermit(chainId, account, permit);
+      setActivePermitHash(chainId, account, permit.hash);
+
+      removePermit(chainId, account, permit.hash);
+
+      const retrieved = getPermit(chainId, account, permit.hash);
+      expect(retrieved).toBeUndefined();
+
+      const activeHash = getActivePermitHash(chainId, account);
+      expect(activeHash).toBeUndefined();
+    });
+  });
+});

package/permits/store.ts

@@ -0,0 +1,156 @@
+import { createStore } from 'zustand/vanilla';
+import { persist } from 'zustand/middleware';
+import { produce } from 'immer';
+import { type Permit, type SerializedPermit } from './types.js';
+import { PermitUtils } from './permit.js';
+
+type ChainRecord<T> = Record<number, T>;
+type AccountRecord<T> = Record<string, T>;
+type HashRecord<T> = Record<string, T>;
+
+type PermitsStore = {
+  permits: ChainRecord<AccountRecord<HashRecord<SerializedPermit | undefined>>>;
+  activePermitHash: ChainRecord<AccountRecord<string | undefined>>;
+};
+
+// Stores generated permits for each user, a hash indicating the active permit for each user
+// Can be used to create reactive hooks
+export const PERMIT_STORE_DEFAULTS: PermitsStore = {
+  permits: {},
+  activePermitHash: {},
+};
+export const _permitStore = createStore<PermitsStore>()(
+  persist(() => PERMIT_STORE_DEFAULTS, { name: 'cofhesdk-permits' })
+);
+
+export const clearStaleStore = () => {
+  // Any is used here because we do not have types of the previous store
+  const state = _permitStore.getState() as any;
+
+  // Check if the store has the expected structure
+  const hasExpectedStructure =
+    state &&
+    typeof state === 'object' &&
+    'permits' in state &&
+    'activePermitHash' in state &&
+    typeof state.permits === 'object' &&
+    typeof state.activePermitHash === 'object';
+
+  if (hasExpectedStructure) return;
+  // Invalid structure detected - clear the store
+  _permitStore.setState({ permits: {}, activePermitHash: {} });
+};
+
+export const getPermit = (
+  chainId: number | undefined,
+  account: string | undefined,
+  hash: string | undefined
+): Permit | undefined => {
+  clearStaleStore();
+  if (chainId == null || account == null || hash == null) return;
+
+  const savedPermit = _permitStore.getState().permits[chainId]?.[account]?.[hash];
+  if (savedPermit == null) return;
+
+  return PermitUtils.deserialize(savedPermit);
+};
+
+export const getActivePermit = (chainId: number | undefined, account: string | undefined): Permit | undefined => {
+  clearStaleStore();
+  if (chainId == null || account == null) return;
+
+  const activePermitHash = _permitStore.getState().activePermitHash[chainId]?.[account];
+  return getPermit(chainId, account, activePermitHash);
+};
+
+export const getPermits = (chainId: number | undefined, account: string | undefined): Record<string, Permit> => {
+  clearStaleStore();
+  if (chainId == null || account == null) return {};
+
+  return Object.entries(_permitStore.getState().permits[chainId]?.[account] ?? {}).reduce(
+    (acc, [hash, permit]) => {
+      if (permit == undefined) return acc;
+      return { ...acc, [hash]: PermitUtils.deserialize(permit) };
+    },
+    {} as Record<string, Permit>
+  );
+};
+
+export const setPermit = (chainId: number, account: string, permit: Permit) => {
+  clearStaleStore();
+  _permitStore.setState(
+    produce<PermitsStore>((state) => {
+      if (state.permits[chainId] == null) state.permits[chainId] = {};
+      if (state.permits[chainId][account] == null) state.permits[chainId][account] = {};
+      state.permits[chainId][account][permit.hash] = PermitUtils.serialize(permit);
+    })
+  );
+};
+
+export const removePermit = (chainId: number, account: string, hash: string) => {
+  clearStaleStore();
+  _permitStore.setState(
+    produce<PermitsStore>((state) => {
+      if (state.permits[chainId] == null) state.permits[chainId] = {};
+      if (state.activePermitHash[chainId] == null) state.activePermitHash[chainId] = {};
+
+      const accountPermits = state.permits[chainId][account];
+      if (accountPermits == null) return;
+
+      if (accountPermits[hash] == null) return;
+
+      if (state.activePermitHash[chainId][account] === hash) {
+        // if the active permit is the one to be removed - unset it
+        state.activePermitHash[chainId][account] = undefined;
+      }
+      // Remove the permit
+      accountPermits[hash] = undefined;
+    })
+  );
+};
+
+export const getActivePermitHash = (chainId: number | undefined, account: string | undefined): string | undefined => {
+  clearStaleStore();
+  if (chainId == null || account == null) return undefined;
+  return _permitStore.getState().activePermitHash[chainId]?.[account];
+};
+
+export const setActivePermitHash = (chainId: number, account: string, hash: string) => {
+  clearStaleStore();
+  _permitStore.setState(
+    produce<PermitsStore>((state) => {
+      if (state.activePermitHash[chainId] == null) state.activePermitHash[chainId] = {};
+      state.activePermitHash[chainId][account] = hash;
+    })
+  );
+};
+
+export const removeActivePermitHash = (chainId: number, account: string) => {
+  clearStaleStore();
+  _permitStore.setState(
+    produce<PermitsStore>((state) => {
+      if (state.activePermitHash[chainId]) state.activePermitHash[chainId][account] = undefined;
+    })
+  );
+};
+
+export const resetStore = () => {
+  clearStaleStore();
+  _permitStore.setState({ permits: {}, activePermitHash: {} });
+};
+
+export const permitStore = {
+  store: _permitStore,
+
+  getPermit,
+  getActivePermit,
+  getPermits,
+  setPermit,
+  removePermit,
+
+  getActivePermitHash,
+  setActivePermitHash,
+  removeActivePermitHash,
+
+  resetStore,
+};

package/permits/test-utils.ts

@@ -0,0 +1,28 @@
+import { type Permit, type SerializedPermit, GenerateSealingKey, PermitUtils } from './index.js';
+
+// Mock permit for testing - using Bob's address as issuer
+export const createMockPermit = async (overrides: Partial<Permit> = {}): Promise<Permit> => {
+  const sealingPair = GenerateSealingKey();
+
+  const fields = {
+    name: 'Test Permit',
+    type: 'self',
+    issuer: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', // Bob's address
+    expiration: 1000000000000,
+    recipient: '0x0000000000000000000000000000000000000000',
+    validatorId: 0,
+    validatorContract: '0x0000000000000000000000000000000000000000',
+    sealingPair: sealingPair.serialize(),
+    issuerSignature: '0x',
+    recipientSignature: '0x',
+    _signedDomain: undefined,
+    ...overrides,
+  } as const;
+
+  const serializedPermit: SerializedPermit = {
+    hash: PermitUtils.getHash(fields),
+    ...fields,
+  };
+
+  return PermitUtils.deserialize(serializedPermit);
+};

package/permits/types.ts

@@ -0,0 +1,204 @@
+import { SealingKey as SealingKeyClass, type EthEncryptedData } from './sealing.js';
+import { type Hex } from 'viem';
+
+/**
+ * EIP712 related types
+ */
+export type EIP712Type = { name: string; type: string };
+export type EIP712Types = Record<string, EIP712Type[]>;
+export type EIP712Message = Record<string, string>;
+export type EIP712Domain = {
+  chainId: number;
+  name: string;
+  verifyingContract: Hex;
+  version: string;
+};
+
+/**
+ * Sealing key type - using the actual SealingKey class
+ */
+export type SealingKey = SealingKeyClass;
+
+/**
+ * Re-export EthEncryptedData from sealing module
+ */
+export type { EthEncryptedData };
+
+// Viem client types will be imported from viem package
+
+/**
+ * Core Permit interface - immutable design for React compatibility
+ */
+export interface Permit {
+  /**
+   * Stable hash of relevant permit data, used as key in storage
+   */
+  hash: string;
+  /**
+   * Name for this permit, for organization and UI usage, not included in signature.
+   */
+  name: string;
+  /**
+   * The type of the Permit (self / sharing)
+   * (self) Permit that will be signed and used by the issuer
+   * (sharing) Permit that is signed by the issuer, but intended to be shared with recipient
+   * (recipient) Permit that has been received, and signed by the recipient
+   */
+  type: 'self' | 'sharing' | 'recipient';
+  /**
+   * (base) User that initially created the permission, target of data fetching
+   */
+  issuer: Hex;
+  /**
+   * (base) Expiration timestamp
+   */
+  expiration: number;
+  /**
+   * (sharing) The user that this permission will be shared with
+   * ** optional, use `address(0)` to disable **
+   */
+  recipient: Hex;
+  /**
+   * (issuer defined validation) An id used to query a contract to check this permissions validity
+   * ** optional, use `0` to disable **
+   */
+  validatorId: number;
+  /**
+   * (issuer defined validation) The contract to query to determine permission validity
+   * ** optional, user `address(0)` to disable **
+   */
+  validatorContract: Hex;
+  /**
+   * (base) The publicKey of a sealingPair used to re-encrypt `issuer`s confidential data
+   *   (non-sharing) Populated by `issuer`
+   *   (sharing)     Populated by `recipient`
+   */
+  sealingPair: SealingKey;
+  /**
+   * (base) `signTypedData` signature created by `issuer`.
+   * (base) Shared- and Self- permissions differ in signature format: (`sealingKey` absent in shared signature)
+   *   (non-sharing) < issuer, expiration, recipient, validatorId, validatorContract, sealingKey >
+   *   (sharing)     < issuer, expiration, recipient, validatorId, validatorContract >
+   */
+  issuerSignature: Hex;
+  /**
+   * (sharing) `signTypedData` signature created by `recipient` with format:
+   * (sharing) < sealingKey, issuerSignature>
+   * ** required for shared permits **
+   */
+  recipientSignature: Hex;
+  /**
+   * EIP712 domain used to sign this permit.
+   * Should not be set manually, included in metadata as part of serialization flows.
+   */
+  _signedDomain?: EIP712Domain;
+}
+
+/**
+ * Permit discriminant helpers
+ */
+export type PermitType = Permit['type'];
+
+/**
+ * Utility type to narrow a permit to a specific discriminant.
+ *
+ * Note: this only narrows the `type` field. Runtime/validation constraints
+ * (e.g. recipient == zeroAddress for self permits) are enforced elsewhere.
+ */
+export type PermitOf<T extends PermitType> = Expand<Omit<Permit, 'type'> & { type: T }>;
+
+export type SelfPermit = PermitOf<'self'>;
+export type SharingPermit = PermitOf<'sharing'>;
+export type RecipientPermit = PermitOf<'recipient'>;
+
+/**
+ * Optional additional metadata of a Permit
+ * Can be passed into the constructor, but not necessary
+ * Useful for deserialization
+ */
+export interface PermitMetadata {
+  /**
+   * EIP712 domain used to sign this permit.
+   * Should not be set manually, included in metadata as part of serialization flows.
+   */
+  _signedDomain?: EIP712Domain;
+}
+
+/**
+ * Utility types for permit creation
+ */
+
+// Specific option types for each permit creation method
+export type CreateSelfPermitOptions = {
+  type?: 'self';
+  issuer: string;
+  name?: string;
+  expiration?: number;
+  validatorId?: number;
+  validatorContract?: string;
+};
+
+export type CreateSharingPermitOptions = {
+  type?: 'sharing';
+  issuer: string;
+  recipient: string;
+  name?: string;
+  expiration?: number;
+  validatorId?: number;
+  validatorContract?: string;
+};
+
+export type ImportSharedPermitOptions = {
+  type?: 'sharing';
+  issuer: string;
+  recipient: string;
+  issuerSignature: string;
+  name?: string;
+  expiration: number;
+  validatorId?: number;
+  validatorContract?: string;
+};
+
+export type SerializedPermit = Omit<Permit, 'sealingPair'> & {
+  _signedDomain?: EIP712Domain;
+  sealingPair: {
+    privateKey: string;
+    publicKey: string;
+  };
+};
+
+/**
+ * A type representing the Permission struct that is passed to Permissioned.sol to grant encrypted data access.
+ */
+export type Permission = Expand<
+  Omit<Permit, 'name' | 'type' | 'sealingPair' | 'hash'> & {
+    sealingKey: Hex;
+  }
+>;
+
+/**
+ * A type representing the permit fields that are used to generate the hash
+ */
+export type PermitHashFields = Pick<
+  Permit,
+  'type' | 'issuer' | 'expiration' | 'recipient' | 'validatorId' | 'validatorContract'
+>;
+
+/**
+ * Validation result type
+ */
+export interface ValidationResult {
+  valid: boolean;
+  error: 'invalid-schema' | 'expired' | 'not-signed' | null;
+}
+
+/**
+ * Signature types for EIP712 signing
+ */
+export type PermitSignaturePrimaryType =
+  | 'PermissionedV2IssuerSelf'
+  | 'PermissionedV2IssuerShared'
+  | 'PermissionedV2Recipient';
+
+// Utils
+export type Expand<T> = T extends infer O ? { [K in keyof O]: O[K] } : never;

package/permits/utils.ts

@@ -0,0 +1,58 @@
+// Utility functions for sealing key operations
+
+declare const BigInt: (value: string | number | bigint) => bigint;
+
+export 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)));
+};
+
+export const toHexString = (bytes: Uint8Array) =>
+  bytes.reduce((str, byte) => str + byte.toString(16).padStart(2, '0'), '');
+
+export function toBigInt(value: number | string | bigint | Uint8Array): bigint {
+  if (typeof value === 'string') {
+    return BigInt(value);
+  } else if (typeof value === 'number') {
+    return BigInt(value);
+  } else if (typeof value === 'object') {
+    // Uint8Array
+    return BigInt('0x' + toHexString(value));
+  } else {
+    return value as bigint;
+  }
+}
+
+export function toBeArray(value: bigint | number): Uint8Array {
+  const bigIntValue = typeof value === 'number' ? BigInt(value) : value;
+  const hex = bigIntValue.toString(16);
+  const paddedHex = hex.length % 2 === 0 ? hex : '0' + hex;
+  return fromHexString(paddedHex);
+}
+
+export function isString(value: unknown) {
+  if (typeof value !== 'string') {
+    throw new Error(`Expected value which is \`string\`, received value of type \`${typeof value}\`.`);
+  }
+}
+
+export function isNumber(value: unknown) {
+  const is = typeof value === 'number' && !Number.isNaN(value);
+  if (!is) {
+    throw new Error(`Expected value which is \`number\`, received value of type \`${typeof value}\`.`);
+  }
+}
+
+export function isBigIntOrNumber(value: unknown) {
+  const is = typeof value === 'bigint';
+
+  if (!is) {
+    try {
+      isNumber(value);
+    } catch (e) {
+      throw new Error(`Value ${value} is not a number or bigint: ${typeof value}`);
+    }
+  }
+}