@cofhe/sdk 0.0.0-alpha-20260409113701

package/permits/permit.ts

@@ -0,0 +1,386 @@
+import { keccak256, toHex, zeroAddress, parseAbi, type PublicClient, type WalletClient } from 'viem';
+import {
+  type Permit,
+  type SelfPermit,
+  type SharingPermit,
+  type RecipientPermit,
+  type CreateSelfPermitOptions,
+  type CreateSharingPermitOptions,
+  type ImportSharedPermitOptions,
+  type SerializedPermit,
+  type EIP712Domain,
+  type Permission,
+  type EthEncryptedData,
+  type PermitHashFields,
+} from './types.js';
+import {
+  validateSelfPermitOptions,
+  validateSharingPermitOptions,
+  validateImportPermitOptions,
+  validateSelfPermit,
+  validateSharingPermit,
+  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';
+
+/**
+ * Main Permit utilities - functional approach for React compatibility
+ */
+export const PermitUtils = {
+  /**
+   * Create a self permit for personal use
+   */
+  createSelf: (options: CreateSelfPermitOptions): SelfPermit => {
+    const validation = validateSelfPermitOptions(options);
+
+    // Always generate a new sealing key - users cannot provide their own
+    const sealingPair = GenerateSealingKey();
+
+    const permit = {
+      hash: PermitUtils.getHash(validation),
+      ...validation,
+      sealingPair,
+      _signedDomain: undefined,
+    } satisfies SelfPermit;
+
+    return permit;
+  },
+
+  /**
+   * Create a sharing permit to be shared with another user
+   */
+  createSharing: (options: CreateSharingPermitOptions): SharingPermit => {
+    const validation = validateSharingPermitOptions(options);
+
+    // Always generate a new sealing key - users cannot provide their own
+    const sealingPair = GenerateSealingKey();
+
+    const permit = {
+      hash: PermitUtils.getHash(validation),
+      ...validation,
+      sealingPair,
+      _signedDomain: undefined,
+    } satisfies SharingPermit;
+
+    return permit;
+  },
+
+  /**
+   * Import a shared permit from various input formats
+   */
+  importShared: (options: ImportSharedPermitOptions | string): RecipientPermit => {
+    let parsedOptions: ImportSharedPermitOptions;
+
+    // Handle different input types
+    if (typeof options === 'string') {
+      // Parse JSON string
+      try {
+        parsedOptions = JSON.parse(options);
+      } catch (error) {
+        throw new Error(`Failed to parse JSON string: ${error}`);
+      }
+    } else if (typeof options === 'object' && options !== null) {
+      // Handle both ImportSharedPermitOptions and any object
+      parsedOptions = options;
+    } else {
+      throw new Error('Invalid input type, expected ImportSharedPermitOptions, object, or string');
+    }
+
+    // Validate type if provided
+    if (parsedOptions.type != null && parsedOptions.type !== 'sharing') {
+      throw new Error(`Invalid permit type <${parsedOptions.type}>, must be "sharing"`);
+    }
+
+    const validation = validateImportPermitOptions({ ...parsedOptions, type: 'recipient' });
+
+    // Always generate a new sealing key - users cannot provide their own
+    const sealingPair = GenerateSealingKey();
+
+    const permit = {
+      hash: PermitUtils.getHash(validation),
+      ...validation,
+      sealingPair,
+      _signedDomain: undefined,
+    } satisfies RecipientPermit;
+
+    return permit;
+  },
+
+  /**
+   * Sign a permit with the provided wallet client
+   */
+  sign: async <T extends Permit>(permit: T, publicClient: PublicClient, walletClient: WalletClient): Promise<T> => {
+    if (walletClient == null || walletClient.account == null) {
+      throw new Error(
+        'Missing walletClient, you must pass in a `walletClient` for the connected user to create a permit signature'
+      );
+    }
+
+    const primaryType = SignatureUtils.getPrimaryType(permit.type);
+    const domain = await getAclEIP712Domain(publicClient);
+    const { types, message } = SignatureUtils.getSignatureParams(PermitUtils.getPermission(permit, true), primaryType);
+
+    const signature = await walletClient.signTypedData({
+      domain,
+      types,
+      primaryType,
+      message,
+      account: walletClient.account,
+    });
+
+    let updatedPermit: Permit;
+    if (permit.type === 'self' || permit.type === 'sharing') {
+      updatedPermit = {
+        ...permit,
+        issuerSignature: signature,
+        _signedDomain: domain,
+      };
+    } else {
+      updatedPermit = {
+        ...permit,
+        recipientSignature: signature,
+        _signedDomain: domain,
+      };
+    }
+
+    return updatedPermit as T;
+  },
+
+  /**
+   * Create and sign a self permit in one operation
+   */
+  createSelfAndSign: async (
+    options: CreateSelfPermitOptions,
+    publicClient: PublicClient,
+    walletClient: WalletClient
+  ): Promise<SelfPermit> => {
+    const permit = PermitUtils.createSelf(options);
+    return PermitUtils.sign(permit, publicClient, walletClient);
+  },
+
+  /**
+   * Create and sign a sharing permit in one operation
+   */
+  createSharingAndSign: async (
+    options: CreateSharingPermitOptions,
+    publicClient: PublicClient,
+    walletClient: WalletClient
+  ): Promise<SharingPermit> => {
+    const permit = PermitUtils.createSharing(options);
+    return PermitUtils.sign(permit, publicClient, walletClient);
+  },
+
+  /**
+   * Import and sign a shared permit in one operation from various input formats
+   */
+  importSharedAndSign: async (
+    options: ImportSharedPermitOptions | string,
+    publicClient: PublicClient,
+    walletClient: WalletClient
+  ): Promise<RecipientPermit> => {
+    const permit = PermitUtils.importShared(options);
+    return PermitUtils.sign(permit, publicClient, walletClient);
+  },
+
+  /**
+   * Deserialize a permit from serialized data
+   */
+  deserialize: (data: SerializedPermit): Permit => {
+    return {
+      ...data,
+      sealingPair: SealingKey.deserialize(data.sealingPair.privateKey, data.sealingPair.publicKey),
+    };
+  },
+
+  /**
+   * Serialize a permit for storage
+   */
+  serialize: (permit: Permit): SerializedPermit => {
+    return {
+      hash: permit.hash,
+      name: permit.name,
+      type: permit.type,
+      issuer: permit.issuer,
+      expiration: permit.expiration,
+      recipient: permit.recipient,
+      validatorId: permit.validatorId,
+      validatorContract: permit.validatorContract,
+      issuerSignature: permit.issuerSignature,
+      recipientSignature: permit.recipientSignature,
+      _signedDomain: permit._signedDomain,
+      sealingPair: permit.sealingPair.serialize(),
+    };
+  },
+
+  /**
+   * Validate a permit (schema-level validation)
+   */
+  validateSchema: (permit: Permit) => {
+    if (permit.type === 'self') {
+      return validateSelfPermit(permit);
+    } else if (permit.type === 'sharing') {
+      return validateSharingPermit(permit);
+    } else if (permit.type === 'recipient') {
+      return validateImportPermit(permit);
+    } else {
+      throw new Error('Invalid permit type');
+    }
+  },
+
+  /**
+   * 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.validateSchema(permit);
+    }
+
+    return {
+      issuer: permit.issuer,
+      expiration: permit.expiration,
+      recipient: permit.recipient,
+      validatorId: permit.validatorId,
+      validatorContract: permit.validatorContract,
+      sealingKey: `0x${permit.sealingPair.publicKey}`,
+      issuerSignature: permit.issuerSignature,
+      recipientSignature: permit.recipientSignature,
+    };
+  },
+
+  /**
+   * Get a stable hash for the permit (used as key in storage)
+   */
+  getHash: (permit: PermitHashFields): string => {
+    const data = JSON.stringify({
+      type: permit.type,
+      issuer: permit.issuer,
+      expiration: permit.expiration,
+      recipient: permit.recipient,
+      validatorId: permit.validatorId,
+      validatorContract: permit.validatorContract,
+    });
+    return keccak256(toHex(data));
+  },
+
+  /**
+   * Export permit data for sharing (removes sensitive fields)
+   */
+  export: (permit: Permit): string => {
+    const cleanedPermit: Record<string, unknown> = {
+      name: permit.name,
+      type: permit.type,
+      issuer: permit.issuer,
+      expiration: permit.expiration,
+    };
+
+    if (permit.recipient !== zeroAddress) cleanedPermit.recipient = permit.recipient;
+    if (permit.validatorId !== 0) cleanedPermit.validatorId = permit.validatorId;
+    if (permit.validatorContract !== zeroAddress) cleanedPermit.validatorContract = permit.validatorContract;
+    if (permit.type === 'sharing' && permit.issuerSignature !== '0x')
+      cleanedPermit.issuerSignature = permit.issuerSignature;
+
+    return JSON.stringify(cleanedPermit, undefined, 2);
+  },
+
+  /**
+   * Unseal encrypted data using the permit's sealing key
+   */
+  unseal: (permit: Permit, ciphertext: EthEncryptedData): bigint => {
+    return permit.sealingPair.unseal(ciphertext);
+  },
+
+  /**
+   * Check if permit is expired
+   */
+  isExpired: (permit: Permit): boolean => {
+    return ValidationUtils.isExpired(permit);
+  },
+
+  /**
+   * Check if permit is signed
+   */
+  isSigned: (permit: Permit): boolean => {
+    return ValidationUtils.isSigned(permit);
+  },
+
+  /**
+   * 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);
+  },
+
+  /**
+   * Update permit name (returns new permit instance)
+   */
+  updateName: (permit: Permit, name: string): Permit => {
+    return { ...permit, name };
+  },
+
+  /**
+   * Fetch EIP712 domain from the blockchain
+   */
+  fetchEIP712Domain: async (publicClient: PublicClient): Promise<EIP712Domain> => {
+    return getAclEIP712Domain(publicClient);
+  },
+
+  /**
+   * Check if permit's signed domain matches the provided domain
+   */
+  matchesDomain: (permit: Permit, domain: EIP712Domain): boolean => {
+    return (
+      permit._signedDomain?.name === domain.name &&
+      permit._signedDomain?.version === domain.version &&
+      permit._signedDomain?.verifyingContract === domain.verifyingContract &&
+      permit._signedDomain?.chainId === domain.chainId
+    );
+  },
+
+  /**
+   * Check if permit's signed domain is valid for the current chain
+   */
+  checkSignedDomainValid: async (permit: Permit, publicClient: PublicClient): Promise<boolean> => {
+    if (permit._signedDomain == null) return false;
+    const domain = await getAclEIP712Domain(publicClient);
+    return PermitUtils.matchesDomain(permit, domain);
+  },
+
+  /**
+   * Check if permit passes the on-chain validation
+   */
+  checkValidityOnChain: async (permit: Permit, publicClient: PublicClient): Promise<boolean> => {
+    const permission = PermitUtils.getPermission(permit);
+    return checkPermitValidityOnChain(permission, publicClient);
+  },
+};

package/permits/sealing.test.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect } from 'vitest';
+import { SealingKey, GenerateSealingKey } from './index.js';
+
+describe('SealingKey', () => {
+  it('should create a SealingKey with valid keys', () => {
+    const privateKey = 'a'.repeat(64);
+    const publicKey = 'b'.repeat(64);
+
+    const sealingKey = new SealingKey(privateKey, publicKey);
+
+    expect(sealingKey.privateKey).toBe(privateKey);
+    expect(sealingKey.publicKey).toBe(publicKey);
+  });
+
+  it('should throw error for invalid private key length', () => {
+    const privateKey = 'a'.repeat(32); // Too short
+    const publicKey = 'b'.repeat(64);
+
+    expect(() => {
+      new SealingKey(privateKey, publicKey);
+    }).toThrow('Private key must be of length 64');
+  });
+
+  it('should throw error for invalid public key length', () => {
+    const privateKey = 'a'.repeat(64);
+    const publicKey = 'b'.repeat(32); // Too short
+
+    expect(() => {
+      new SealingKey(privateKey, publicKey);
+    }).toThrow('Public key must be of length 64');
+  });
+
+  it('should seal and unseal data correctly', () => {
+    const publicKey = 'b'.repeat(64);
+    const value = BigInt(12345);
+
+    // Seal the data
+    const encryptedData = SealingKey.seal(value, publicKey);
+
+    expect(encryptedData).toHaveProperty('data');
+    expect(encryptedData).toHaveProperty('public_key');
+    expect(encryptedData).toHaveProperty('nonce');
+    expect(encryptedData.data).toBeInstanceOf(Uint8Array);
+    expect(encryptedData.public_key).toBeInstanceOf(Uint8Array);
+    expect(encryptedData.nonce).toBeInstanceOf(Uint8Array);
+  });
+
+  it('should throw error for invalid public key in seal', () => {
+    const value = BigInt(12345);
+    const invalidPublicKey = 'invalid';
+
+    expect(() => {
+      SealingKey.seal(value, invalidPublicKey);
+    }).toThrow('bad public key size');
+  });
+
+  it('should throw error for invalid value in seal', () => {
+    const publicKey = 'b'.repeat(64);
+    const invalidValue = 'not a number';
+
+    expect(() => {
+      // @ts-expect-error - invalid value
+      SealingKey.seal(invalidValue, publicKey);
+    }).toThrow('Value not a number is not a number or bigint: string');
+  });
+});
+
+describe('GenerateSealingKey', () => {
+  it('should generate a valid SealingKey', async () => {
+    const sealingKey = GenerateSealingKey();
+
+    expect(sealingKey).toBeInstanceOf(SealingKey);
+    expect(sealingKey.privateKey).toHaveLength(64);
+    expect(sealingKey.publicKey).toHaveLength(64);
+  });
+
+  it('should generate different keys on each call', async () => {
+    const key1 = GenerateSealingKey();
+    const key2 = GenerateSealingKey();
+
+    expect(key1.privateKey).not.toBe(key2.privateKey);
+    expect(key1.publicKey).not.toBe(key2.publicKey);
+  });
+});

package/permits/sealing.ts

@@ -0,0 +1,131 @@
+import nacl from 'tweetnacl';
+import { fromHexString, toBeArray, toBigInt, toHexString, isBigIntOrNumber, isString } from './utils.js';
+
+const PRIVATE_KEY_LENGTH = 64;
+const PUBLIC_KEY_LENGTH = 64;
+
+export type EthEncryptedData = {
+  data: Uint8Array;
+  public_key: Uint8Array;
+  nonce: Uint8Array;
+};
+
+/**
+ * A class representing a SealingKey which provides cryptographic sealing (encryption)
+ * and unsealing (decryption) capabilities.
+ */
+export class SealingKey {
+  /**
+   * The private key used for decryption.
+   */
+  privateKey: string;
+  /**
+   * The public key used for encryption.
+   */
+  publicKey: string;
+
+  /**
+   * Constructs a SealingKey instance with the given private and public keys.
+   *
+   * @param {string} privateKey - The private key used for decryption.
+   * @param {string} publicKey - The public key used for encryption.
+   * @throws Will throw an error if the provided keys lengths do not match
+   *         the required lengths for private and public keys.
+   */
+  constructor(privateKey: string, publicKey: string) {
+    if (privateKey.length !== PRIVATE_KEY_LENGTH) {
+      throw new Error(`Private key must be of length ${PRIVATE_KEY_LENGTH}`);
+    }
+
+    if (publicKey.length !== PUBLIC_KEY_LENGTH) {
+      throw new Error(`Public key must be of length ${PUBLIC_KEY_LENGTH}`);
+    }
+
+    this.privateKey = privateKey;
+    this.publicKey = publicKey;
+  }
+
+  unseal = (parsedData: EthEncryptedData): bigint => {
+    // Ensure all parameters are Uint8Array
+    const nonce = parsedData.nonce instanceof Uint8Array ? parsedData.nonce : new Uint8Array(parsedData.nonce);
+
+    const ephemPublicKey =
+      parsedData.public_key instanceof Uint8Array ? parsedData.public_key : new Uint8Array(parsedData.public_key);
+
+    const dataToDecrypt = parsedData.data instanceof Uint8Array ? parsedData.data : new Uint8Array(parsedData.data);
+
+    // Make sure the private key is also a Uint8Array
+    const privateKeyBytes = fromHexString(this.privateKey);
+
+    // Debug information
+    // console.log("nonce length:", nonce.length);
+    // console.log("ephemPublicKey length:", ephemPublicKey.length);
+    // console.log("privateKeyBytes length:", privateKeyBytes.length);
+    // console.log("dataToDecrypt length:", dataToDecrypt.length);
+
+    // call the nacl box function to decrypt the data
+    const decryptedMessage = nacl.box.open(dataToDecrypt, nonce, ephemPublicKey, privateKeyBytes);
+
+    if (!decryptedMessage) {
+      throw new Error('Failed to decrypt message');
+    }
+
+    return toBigInt(decryptedMessage);
+  };
+
+  /**
+   * Serializes the SealingKey to a JSON object.
+   */
+  serialize = () => {
+    return {
+      privateKey: this.privateKey,
+      publicKey: this.publicKey,
+    };
+  };
+
+  /**
+   * Deserializes the SealingKey from a JSON object.
+   */
+  static deserialize = (privateKey: string, publicKey: string): SealingKey => {
+    return new SealingKey(privateKey, publicKey);
+  };
+
+  /**
+   * Seals (encrypts) the provided message for a receiver with the specified public key.
+   *
+   * @param {bigint | number} value - The message to be encrypted.
+   * @param {string} publicKey - The public key of the intended recipient.
+   * @returns string - The encrypted message in hexadecimal format.
+   * @static
+   * @throws Will throw if the provided publicKey or value do not meet defined preconditions.
+   */
+  static seal = (value: bigint | number, publicKey: string): EthEncryptedData => {
+    isString(publicKey);
+    isBigIntOrNumber(value);
+
+    // generate ephemeral keypair
+    const ephemeralKeyPair = nacl.box.keyPair();
+
+    const nonce = nacl.randomBytes(nacl.box.nonceLength);
+
+    const encryptedMessage = nacl.box(toBeArray(value), nonce, fromHexString(publicKey), ephemeralKeyPair.secretKey);
+
+    return {
+      data: encryptedMessage,
+      public_key: ephemeralKeyPair.publicKey,
+      nonce: nonce,
+    };
+  };
+}
+
+/**
+ * Asynchronously generates a new SealingKey.
+ * This function uses the 'nacl' library to create a new public/private key pair for sealing purposes.
+ * A sealing key is used to encrypt data such that it can only be unsealed (decrypted) by the owner of the corresponding private key.
+ * @returns {SealingKey} - A new SealingKey object containing the hexadecimal strings of the public and private keys.
+ */
+export const GenerateSealingKey = (): SealingKey => {
+  const sodiumKeypair = nacl.box.keyPair();
+
+  return new SealingKey(toHexString(sodiumKeypair.secretKey), toHexString(sodiumKeypair.publicKey));
+};

package/permits/signature.ts

@@ -0,0 +1,79 @@
+import { type EIP712Message, type EIP712Types, type Permission, type PermitSignaturePrimaryType } from './types.js';
+
+const PermitSignatureAllFields = [
+  { name: 'issuer', type: 'address' },
+  { name: 'expiration', type: 'uint64' },
+  { name: 'recipient', type: 'address' },
+  { name: 'validatorId', type: 'uint256' },
+  { name: 'validatorContract', type: 'address' },
+  { name: 'sealingKey', type: 'bytes32' },
+  { name: 'issuerSignature', type: 'bytes' },
+] as const;
+
+type PermitSignatureFieldOption = (typeof PermitSignatureAllFields)[number]['name'];
+
+export const SignatureTypes = {
+  PermissionedV2IssuerSelf: [
+    'issuer',
+    'expiration',
+    'recipient',
+    'validatorId',
+    'validatorContract',
+    'sealingKey',
+  ] satisfies PermitSignatureFieldOption[],
+  PermissionedV2IssuerShared: [
+    'issuer',
+    'expiration',
+    'recipient',
+    'validatorId',
+    'validatorContract',
+  ] satisfies PermitSignatureFieldOption[],
+  PermissionedV2Recipient: ['sealingKey', 'issuerSignature'] satisfies PermitSignatureFieldOption[],
+} as const;
+
+/**
+ * Get signature types and message for EIP712 signing
+ */
+export const getSignatureTypesAndMessage = <T extends PermitSignatureFieldOption>(
+  primaryType: PermitSignaturePrimaryType,
+  fields: T[] | readonly T[],
+  values: Pick<Permission, T> & Partial<Permission>
+): { types: EIP712Types; primaryType: string; message: EIP712Message } => {
+  const types = {
+    [primaryType]: PermitSignatureAllFields.filter((fieldType) => fields.includes(fieldType.name as T)),
+  };
+
+  const message: Record<T, string | string[] | number | number[]> = {} as Record<
+    T,
+    string | string[] | number | number[]
+  >;
+  fields.forEach((field) => {
+    if (field in values) {
+      message[field] = values[field];
+    }
+  });
+
+  return { types, primaryType, message: message as EIP712Message };
+};
+
+/**
+ * Signature utilities for permit operations
+ */
+export const SignatureUtils = {
+  /**
+   * Get signature parameters for a permit
+   */
+  getSignatureParams: (permit: Permission, primaryType: PermitSignaturePrimaryType) => {
+    return getSignatureTypesAndMessage(primaryType, SignatureTypes[primaryType], permit);
+  },
+
+  /**
+   * Determine the required signature type based on permit type
+   */
+  getPrimaryType: (permitType: 'self' | 'sharing' | 'recipient'): PermitSignaturePrimaryType => {
+    if (permitType === 'self') return 'PermissionedV2IssuerSelf';
+    if (permitType === 'sharing') return 'PermissionedV2IssuerShared';
+    if (permitType === 'recipient') return 'PermissionedV2Recipient';
+    throw new Error(`Unknown permit type: ${permitType}`);
+  },
+};