@cofhe/sdk 0.1.0 → 0.2.0

package/permits/validation.test.ts

@@ -0,0 +1,288 @@
+import { describe, it, expect } from 'vitest';
+import {
+  ValidationUtils,
+  validateSelfPermitOptions,
+  validateSharingPermitOptions,
+  validateImportPermitOptions,
+  validateSelfPermit,
+  validateSharingPermit,
+  validateImportPermit,
+  type Permit,
+  type CreateSelfPermitOptions,
+  type CreateSharingPermitOptions,
+  type ImportSharedPermitOptions,
+} from './index.js';
+import { createMockPermit } from './test-utils.js';
+
+describe('Validation Tests', () => {
+  describe('validateSelfPermitOptions', () => {
+    it('should validate valid self permit options', () => {
+      const options: CreateSelfPermitOptions = {
+        type: 'self',
+        issuer: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', // Bob's address
+        name: 'Test Permit',
+      };
+
+      const result = validateSelfPermitOptions(options);
+      expect(result.success).toBe(true);
+      expect(result.data).toBeDefined();
+    });
+
+    it('should reject invalid address', () => {
+      const options: CreateSelfPermitOptions = {
+        type: 'self',
+        issuer: 'invalid-address',
+        name: 'Test Permit',
+      };
+
+      const result = validateSelfPermitOptions(options);
+      expect(result.success).toBe(false);
+      expect(result.error).toBeDefined();
+    });
+
+    it('should reject zero address', () => {
+      const options: CreateSelfPermitOptions = {
+        type: 'self',
+        issuer: '0x0000000000000000000000000000000000000000',
+        name: 'Test Permit',
+      };
+
+      const result = validateSelfPermitOptions(options);
+      expect(result.success).toBe(false);
+      expect(result.error).toBeDefined();
+    });
+  });
+
+  describe('validateSharingPermitOptions', () => {
+    it('should validate valid sharing permit options', () => {
+      const options: CreateSharingPermitOptions = {
+        type: 'sharing',
+        issuer: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', // Bob's address
+        recipient: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8', // Alice's address
+        name: 'Sharing Permit',
+      };
+
+      const result = validateSharingPermitOptions(options);
+      expect(result.success).toBe(true);
+    });
+
+    it('should reject sharing permit with zero recipient', () => {
+      const options: CreateSharingPermitOptions = {
+        type: 'sharing',
+        issuer: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', // Bob's address
+        recipient: '0x0000000000000000000000000000000000000000',
+        name: 'Sharing Permit',
+      };
+
+      const result = validateSharingPermitOptions(options);
+      expect(result.success).toBe(false);
+    });
+
+    it('should reject sharing permit with invalid recipient', () => {
+      const options: CreateSharingPermitOptions = {
+        type: 'sharing',
+        issuer: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', // Bob's address
+        recipient: 'invalid-address',
+        name: 'Sharing Permit',
+      };
+
+      const result = validateSharingPermitOptions(options);
+      expect(result.success).toBe(false);
+    });
+  });
+
+  describe('validateImportPermitOptions', () => {
+    it('should validate valid import permit options', () => {
+      const options: ImportSharedPermitOptions = {
+        issuer: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', // Bob's address
+        recipient: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8', // Alice's address
+        issuerSignature: '0x1234567890abcdef',
+        name: 'Import Permit',
+      };
+
+      const result = validateImportPermitOptions(options);
+      expect(result.success).toBe(true);
+    });
+
+    it('should reject import permit with empty signature', () => {
+      const options: ImportSharedPermitOptions = {
+        issuer: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', // Bob's address
+        recipient: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8', // Alice's address
+        issuerSignature: '0x',
+        name: 'Import Permit',
+      };
+
+      const result = validateImportPermitOptions(options);
+      expect(result.success).toBe(false);
+    });
+
+    it('should reject import permit with invalid signature', () => {
+      const options: ImportSharedPermitOptions = {
+        issuer: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', // Bob's address
+        recipient: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8', // Alice's address
+        issuerSignature: '0x',
+        name: 'Import Permit',
+      };
+
+      const result = validateImportPermitOptions(options);
+      expect(result.success).toBe(false);
+    });
+  });
+
+  describe('validateSelfPermit', () => {
+    it('should validate valid self permit', async () => {
+      const permit = await createMockPermit();
+      permit.type = 'self';
+      permit.issuerSignature = '0x1234567890abcdef';
+
+      const result = validateSelfPermit(permit);
+      expect(result.success).toBe(true);
+    });
+
+    it('should reject self permit with missing sealing pair', async () => {
+      const permit = { ...(await createMockPermit()), sealingPair: undefined };
+      permit.type = 'self';
+      const result = validateSelfPermit(permit as unknown as Permit);
+      expect(result.success).toBe(false);
+    });
+  });
+
+  describe('validateSharingPermit', () => {
+    it('should validate valid sharing permit', async () => {
+      const permit = await createMockPermit();
+      permit.type = 'sharing';
+      permit.issuerSignature = '0x1234567890abcdef';
+      permit.recipient = '0x70997970C51812dc3A010C7d01b50e0d17dc79C8'; // Alice's address
+
+      const result = validateSharingPermit(permit);
+      expect(result.success).toBe(true);
+    });
+
+    it('should reject sharing permit with zero recipient', async () => {
+      const permit = await createMockPermit();
+      permit.type = 'sharing';
+      permit.issuerSignature = '0x1234567890abcdef';
+      permit.recipient = '0x0000000000000000000000000000000000000000';
+
+      const result = validateSharingPermit(permit);
+      expect(result.success).toBe(false);
+    });
+  });
+
+  describe('validateImportPermit', () => {
+    it('should validate valid import permit', async () => {
+      const permit = await createMockPermit();
+      permit.type = 'recipient';
+      permit.issuerSignature = '0x1234567890abcdef';
+      permit.recipient = '0x70997970C51812dc3A010C7d01b50e0d17dc79C8'; // Alice's address
+      permit.recipientSignature = '0xabcdef1234567890';
+
+      const result = validateImportPermit(permit);
+      expect(result.success).toBe(true);
+    });
+
+    it('should reject import permit with empty recipient signature', async () => {
+      const permit = await createMockPermit();
+      permit.type = 'recipient';
+      permit.issuerSignature = '0x1234567890abcdef';
+      permit.recipient = '0x70997970C51812dc3A010C7d01b50e0d17dc79C8'; // Alice's address
+      permit.recipientSignature = '0x';
+
+      const result = validateImportPermit(permit);
+      expect(result.success).toBe(false);
+    });
+  });
+
+  describe('ValidationUtils', () => {
+    describe('isExpired', () => {
+      it('should return true for expired permit', async () => {
+        const permit = {
+          ...(await createMockPermit()),
+          expiration: Math.floor(Date.now() / 1000) - 3600, // 1 hour ago
+        };
+        expect(ValidationUtils.isExpired(permit)).toBe(true);
+      });
+
+      it('should return false for non-expired permit', async () => {
+        const permit = {
+          ...(await createMockPermit()),
+          expiration: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
+        };
+        expect(ValidationUtils.isExpired(permit)).toBe(false);
+      });
+    });
+
+    describe('isSigned', () => {
+      it('should return true for signed self permit', async () => {
+        const permit = {
+          ...(await createMockPermit()),
+          type: 'self' as const,
+          issuerSignature: '0x1234567890abcdef' as `0x${string}`,
+        };
+        expect(ValidationUtils.isSigned(permit)).toBe(true);
+      });
+
+      it('should return false for unsigned self permit', async () => {
+        const permit = {
+          ...(await createMockPermit()),
+          type: 'self' as const,
+          issuerSignature: '0x' as `0x${string}`,
+        };
+        expect(ValidationUtils.isSigned(permit)).toBe(false);
+      });
+
+      it('should return true for signed recipient permit', async () => {
+        const permit = {
+          ...(await createMockPermit()),
+          type: 'recipient' as const,
+          recipientSignature: '0x1234567890abcdef' as `0x${string}`,
+        };
+        expect(ValidationUtils.isSigned(permit)).toBe(true);
+      });
+
+      it('should return false for unsigned recipient permit', async () => {
+        const permit = {
+          ...(await createMockPermit()),
+          type: 'recipient' as const,
+          recipientSignature: '0x' as `0x${string}`,
+        };
+        expect(ValidationUtils.isSigned(permit)).toBe(false);
+      });
+    });
+
+    describe('isValid', () => {
+      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);
+        expect(result.valid).toBe(true);
+        expect(result.error).toBeNull();
+      });
+
+      it('should return invalid for expired permit', async () => {
+        const permit = {
+          ...(await createMockPermit()),
+          expiration: Math.floor(Date.now() / 1000) - 3600,
+          issuerSignature: '0x1234567890abcdef' as `0x${string}`,
+        };
+        const result = ValidationUtils.isValid(permit);
+        expect(result.valid).toBe(false);
+        expect(result.error).toBe('expired');
+      });
+
+      it('should return invalid for unsigned permit', async () => {
+        const permit = {
+          ...(await createMockPermit()),
+          expiration: Math.floor(Date.now() / 1000) + 3600,
+          issuerSignature: '0x' as `0x${string}`,
+        };
+        const result = ValidationUtils.isValid(permit);
+        expect(result.valid).toBe(false);
+        expect(result.error).toBe('not-signed');
+      });
+    });
+  });
+});

package/permits/validation.ts

@@ -0,0 +1,369 @@
+import { z } from 'zod';
+import { isAddress, zeroAddress } from 'viem';
+import { type Permit, type ValidationResult } from './types.js';
+import { is0xPrefixed } from './utils.js';
+
+const SerializedSealingPair = z.object({
+  privateKey: z.string(),
+  publicKey: z.string(),
+});
+
+const DEFAULT_EXPIRATION_FN = () => Math.round(Date.now() / 1000) + 7 * 24 * 60 * 60; // 7 days from now
+
+const zPermitWithDefaults = z.object({
+  name: z.string().optional().default('Unnamed Permit'),
+  type: z.enum(['self', 'sharing', 'recipient']),
+  issuer: z
+    .string()
+    .refine((val) => isAddress(val), {
+      message: 'Permit issuer :: invalid address',
+    })
+    .refine((val) => val !== zeroAddress, {
+      message: 'Permit issuer :: must not be zeroAddress',
+    }),
+  expiration: z.number().optional().default(DEFAULT_EXPIRATION_FN),
+  recipient: z
+    .string()
+    .optional()
+    .default(zeroAddress)
+    .refine((val) => isAddress(val), {
+      message: 'Permit recipient :: invalid address',
+    }),
+  validatorId: z.number().optional().default(0),
+  validatorContract: z
+    .string()
+    .optional()
+    .default(zeroAddress)
+    .refine((val) => isAddress(val), {
+      message: 'Permit validatorContract :: invalid address',
+    }),
+  issuerSignature: z.string().optional().default('0x'),
+  recipientSignature: z.string().optional().default('0x'),
+});
+
+const zPermitWithSealingPair = zPermitWithDefaults.extend({
+  sealingPair: SerializedSealingPair.optional(),
+});
+
+type zPermitType = z.infer<typeof zPermitWithDefaults>;
+
+/**
+ * Permits allow a hook into an optional external validator contract,
+ * this check ensures that IF an external validator is applied, that both `validatorId` and `validatorContract` are populated,
+ * ELSE ensures that both `validatorId` and `validatorContract` are empty
+ */
+const ValidatorContractRefinement = [
+  (data: zPermitType) =>
+    (data.validatorId !== 0 && data.validatorContract !== zeroAddress) ||
+    (data.validatorId === 0 && data.validatorContract === zeroAddress),
+  {
+    message: 'Permit external validator :: validatorId and validatorContract must either both be set or both be unset.',
+    path: ['validatorId', 'validatorContract'] as string[],
+  },
+] as const;
+
+// ============================================================================
+// SELF PERMIT VALIDATORS
+// ============================================================================
+
+/**
+ * Validator for self permit creation options
+ */
+export const SelfPermitOptionsValidator = z
+  .object({
+    type: z.literal('self').optional().default('self'),
+    issuer: z
+      .string()
+      .refine((val) => isAddress(val), {
+        message: 'Self permit issuer :: invalid address',
+      })
+      .refine((val) => is0xPrefixed(val), {
+        message: 'Self permit issuer :: must be 0x prefixed',
+      })
+      .refine((val) => val !== zeroAddress, {
+        message: 'Self permit issuer :: must not be zeroAddress',
+      }),
+    name: z.string().optional().default('Unnamed Permit'),
+    expiration: z.number().optional().default(DEFAULT_EXPIRATION_FN),
+    recipient: z
+      .string()
+      .optional()
+      .default(zeroAddress)
+      .refine((val) => isAddress(val), {
+        message: 'Self permit recipient :: invalid address',
+      })
+      .refine((val) => is0xPrefixed(val), {
+        message: 'Self permit recipient :: must be 0x prefixed',
+      })
+      .refine((val) => val === zeroAddress, {
+        message: 'Self permit recipient :: must be zeroAddress',
+      }),
+    validatorId: z.number().optional().default(0),
+    validatorContract: z
+      .string()
+      .optional()
+      .default(zeroAddress)
+      .refine((val) => isAddress(val), {
+        message: 'Self permit validatorContract :: invalid address',
+      }),
+    issuerSignature: z
+      .string()
+      .optional()
+      .default('0x')
+      .refine((val) => is0xPrefixed(val), {
+        message: 'Self permit issuerSignature :: must be 0x prefixed',
+      }),
+    recipientSignature: z
+      .string()
+      .optional()
+      .default('0x')
+      .refine((val) => is0xPrefixed(val), {
+        message: 'Self permit recipientSignature :: must be 0x prefixed',
+      }),
+  })
+  .refine(...ValidatorContractRefinement);
+
+/**
+ * Validator for fully formed self permits
+ */
+export const SelfPermitValidator = zPermitWithSealingPair
+  .refine((data) => data.type === 'self', {
+    message: "Self permit :: type must be 'self'",
+  })
+  .refine((data) => data.recipient === zeroAddress, {
+    message: 'Self permit :: recipient must be zeroAddress',
+  })
+  .refine((data) => data.issuerSignature !== '0x', {
+    message: 'Self permit :: issuerSignature must be populated',
+  })
+  .refine((data) => data.recipientSignature === '0x', {
+    message: 'Self permit :: recipientSignature must be empty',
+  })
+  .refine(...ValidatorContractRefinement);
+
+// ============================================================================
+// SHARING PERMIT VALIDATORS
+// ============================================================================
+
+/**
+ * Validator for sharing permit creation options
+ */
+export const SharingPermitOptionsValidator = z
+  .object({
+    type: z.literal('sharing').optional().default('sharing'),
+    issuer: z
+      .string()
+      .refine((val) => isAddress(val), {
+        message: 'Sharing permit issuer :: invalid address',
+      })
+      .refine((val) => is0xPrefixed(val), {
+        message: 'Sharing permit issuer :: must be 0x prefixed',
+      })
+      .refine((val) => val !== zeroAddress, {
+        message: 'Sharing permit issuer :: must not be zeroAddress',
+      }),
+    recipient: z
+      .string()
+      .refine((val) => isAddress(val), {
+        message: 'Sharing permit recipient :: invalid address',
+      })
+      .refine((val) => is0xPrefixed(val), {
+        message: 'Sharing permit recipient :: must be 0x prefixed',
+      })
+      .refine((val) => val !== zeroAddress, {
+        message: 'Sharing permit recipient :: must not be zeroAddress',
+      }),
+    name: z.string().optional().default('Unnamed Permit'),
+    expiration: z.number().optional().default(DEFAULT_EXPIRATION_FN),
+    validatorId: z.number().optional().default(0),
+    validatorContract: z
+      .string()
+      .optional()
+      .default(zeroAddress)
+      .refine((val) => isAddress(val), {
+        message: 'Sharing permit validatorContract :: invalid address',
+      }),
+    issuerSignature: z
+      .string()
+      .optional()
+      .default('0x')
+      .refine((val) => is0xPrefixed(val), {
+        message: 'Sharing permit issuerSignature :: must be 0x prefixed',
+      }),
+    recipientSignature: z
+      .string()
+      .optional()
+      .default('0x')
+      .refine((val) => is0xPrefixed(val), {
+        message: 'Sharing permit recipientSignature :: must be 0x prefixed',
+      }),
+  })
+  .refine(...ValidatorContractRefinement);
+
+/**
+ * Validator for fully formed sharing permits
+ */
+export const SharingPermitValidator = zPermitWithSealingPair
+  .refine((data) => data.type === 'sharing', {
+    message: "Sharing permit :: type must be 'sharing'",
+  })
+  .refine((data) => data.recipient !== zeroAddress, {
+    message: 'Sharing permit :: recipient must not be zeroAddress',
+  })
+  .refine((data) => data.issuerSignature !== '0x', {
+    message: 'Sharing permit :: issuerSignature must be populated',
+  })
+  .refine((data) => data.recipientSignature === '0x', {
+    message: 'Sharing permit :: recipientSignature must be empty',
+  })
+  .refine(...ValidatorContractRefinement);
+
+// ============================================================================
+// IMPORT/RECIPIENT PERMIT VALIDATORS
+// ============================================================================
+
+/**
+ * Validator for import permit creation options (recipient receiving shared permit)
+ */
+export const ImportPermitOptionsValidator = z
+  .object({
+    type: z.literal('recipient').optional().default('recipient'),
+    issuer: z
+      .string()
+      .refine((val) => isAddress(val), {
+        message: 'Import permit issuer :: invalid address',
+      })
+      .refine((val) => is0xPrefixed(val), {
+        message: 'Import permit issuer :: must be 0x prefixed',
+      })
+      .refine((val) => val !== zeroAddress, {
+        message: 'Import permit issuer :: must not be zeroAddress',
+      }),
+    recipient: z
+      .string()
+      .refine((val) => isAddress(val), {
+        message: 'Import permit recipient :: invalid address',
+      })
+      .refine((val) => is0xPrefixed(val), {
+        message: 'Import permit recipient :: must be 0x prefixed',
+      })
+      .refine((val) => val !== zeroAddress, {
+        message: 'Import permit recipient :: must not be zeroAddress',
+      }),
+    issuerSignature: z
+      .string()
+      .refine((val) => is0xPrefixed(val), {
+        message: 'Import permit issuerSignature :: must be 0x prefixed',
+      })
+      .refine((val) => val !== '0x', {
+        message: 'Import permit :: issuerSignature must be provided',
+      }),
+    name: z.string().optional().default('Unnamed Permit'),
+    expiration: z.number().optional().default(DEFAULT_EXPIRATION_FN),
+    validatorId: z.number().optional().default(0),
+    validatorContract: z
+      .string()
+      .optional()
+      .default(zeroAddress)
+      .refine((val) => isAddress(val), {
+        message: 'Import permit validatorContract :: invalid address',
+      }),
+    recipientSignature: z
+      .string()
+      .optional()
+      .default('0x')
+      .refine((val) => is0xPrefixed(val), {
+        message: 'Import permit recipientSignature :: must be 0x prefixed',
+      }),
+  })
+  .refine(...ValidatorContractRefinement);
+
+/**
+ * Validator for fully formed import/recipient permits
+ */
+export const ImportPermitValidator = zPermitWithSealingPair
+  .refine((data) => data.type === 'recipient', {
+    message: "Import permit :: type must be 'recipient'",
+  })
+  .refine((data) => data.recipient !== zeroAddress, {
+    message: 'Import permit :: recipient must not be zeroAddress',
+  })
+  .refine((data) => data.issuerSignature !== '0x', {
+    message: 'Import permit :: issuerSignature must be populated',
+  })
+  .refine((data) => data.recipientSignature !== '0x', {
+    message: 'Import permit :: recipientSignature must be populated',
+  })
+  .refine(...ValidatorContractRefinement);
+
+// ============================================================================
+// VALIDATION FUNCTIONS
+// ============================================================================
+
+/**
+ * Validates self permit creation options
+ */
+export const validateSelfPermitOptions = (options: any) => SelfPermitOptionsValidator.safeParse(options);
+
+/**
+ * Validates sharing permit creation options
+ */
+export const validateSharingPermitOptions = (options: any) => SharingPermitOptionsValidator.safeParse(options);
+
+/**
+ * Validates import permit creation options
+ */
+export const validateImportPermitOptions = (options: any) => ImportPermitOptionsValidator.safeParse(options);
+
+/**
+ * Validates a fully formed self permit
+ */
+export const validateSelfPermit = (permit: any) => SelfPermitValidator.safeParse(permit);
+
+/**
+ * Validates a fully formed sharing permit
+ */
+export const validateSharingPermit = (permit: any) => SharingPermitValidator.safeParse(permit);
+
+/**
+ * Validates a fully formed import/recipient permit
+ */
+export const validateImportPermit = (permit: any) => ImportPermitValidator.safeParse(permit);
+
+/**
+ * Simple validation functions for common checks
+ */
+export const ValidationUtils = {
+  /**
+   * Check if permit is expired
+   */
+  isExpired: (permit: Permit): boolean => {
+    return permit.expiration < Math.floor(Date.now() / 1000);
+  },
+
+  /**
+   * Check if permit is signed by the active party
+   */
+  isSigned: (permit: Permit): boolean => {
+    if (permit.type === 'self' || permit.type === 'sharing') {
+      return permit.issuerSignature !== '0x';
+    }
+    if (permit.type === 'recipient') {
+      return permit.recipientSignature !== '0x';
+    }
+    return false;
+  },
+
+  /**
+   * Overall validity checker of a permit
+   */
+  isValid: (permit: Permit): ValidationResult => {
+    if (ValidationUtils.isExpired(permit)) {
+      return { valid: false, error: 'expired' };
+    }
+    if (!ValidationUtils.isSigned(permit)) {
+      return { valid: false, error: 'not-signed' };
+    }
+    return { valid: true, error: null };
+  },
+};