centralize permission context validation logic

Extracted and reused shared validation functions across token stream and periodic permission contexts. Updated docs formatting and test assertions to reflect revised validation messages.

Author: jeffsmale90

docs/addingNewPermissionTypes.md

@@ -5,6 +5,7 @@ This guide explains how to add a new permission type to the MetaMask Permissions
 ## Overview
 
 A permission type consists of several components:
+
 1. Permission definition and registration
 2. Type definitions
 3. Validation logic
@@ -17,6 +18,7 @@ A permission type consists of several components:
 ### 1. Create Permission Directory
 
 Create a new directory under `packages/gator-permissions-snap/src/permissions/` for your permission type. For example:
+
 ```
 packages/gator-permissions-snap/src/permissions/yourPermissionType/
 ```
@@ -27,7 +29,11 @@ Create a `types.ts` file in your permission directory with the following structu
 
 ```typescript
 import { z } from 'zod';
-import { zHexStr, zPermission, zMetaMaskPermissionData } from '@metamask/7715-permissions-shared/types';
+import {
+  zHexStr,
+  zPermission,
+  zMetaMaskPermissionData,
+} from '@metamask/7715-permissions-shared/types';
 
 // Define your permission metadata type
 // Metadata is anything derived from the context that is not editable, such as validtion errors
@@ -177,13 +183,15 @@ export const yourPermissionDefinition: PermissionDefinition<
 ### 8. Register the Permission
 
 1. Add your permission type to the permission handler factory:
+
 ```typescript
 case 'your-permission-type':
   handler = createPermissionHandler(yourPermissionDefinition);
   break;
 ```
 
 2. Add your permission to the default offers in `snap-permission-registry.ts`:
+
 ```typescript
 export const DEFAULT_OFFERS: GatorPermission[] = [
   // ... existing permissions
@@ -258,11 +266,13 @@ export const YourPermissionForm = ({
 Then, add your form to the permission type selector in `packages/site/src/pages/index.tsx`:
 
 1. Import your form component:
+
 ```typescript
 import { YourPermissionForm } from '../components/permissions';
 ```
 
 2. Add your permission type to the select options:
+
 ```typescript
 <select
   id="permissionType"
@@ -276,6 +286,7 @@ import { YourPermissionForm } from '../components/permissions';
 ```
 
 3. Add the form component to the conditional rendering:
+
 ```typescript
 {permissionType === 'your-permission-type' && (
   <YourPermissionForm
@@ -287,6 +298,7 @@ import { YourPermissionForm } from '../components/permissions';
 ```
 
 Key points for implementing permission forms:
+
 1. Use the `StyledForm` component for consistent styling
 2. Implement proper type safety with TypeScript
 3. Use controlled form components with React state

packages/gator-permissions-snap/snap.manifest.json

@@ -7,7 +7,7 @@
     "url": "https://github.com/MetaMask/snap-7715-permissions.git"
   },
   "source": {
-    "shasum": "/p0aPugcJzMS6wNekI/ZtyJUQ/5EsupvbPDiT4cPebg=",
+    "shasum": "ZA6QEmzn+1LTSlIH7hGCFhIyeu9eO8g2xw312S4bdSE=",
     "location": {
       "npm": {
         "filePath": "dist/bundle.js",

packages/gator-permissions-snap/src/permissions/contextValidation.ts

@@ -0,0 +1,145 @@
+import { parseUnits, formatUnits } from 'viem';
+import {
+  convertReadableDateToTimestamp,
+  getStartOfTodayUTC,
+  TIME_PERIOD_TO_SECONDS,
+} from '../utils/time';
+import { TimePeriod } from '../core/types';
+
+export interface ValidationErrors {
+  [key: string]: string;
+}
+
+/**
+ * Validates and parses a token amount string to BigInt
+ * @param amount - The amount string to validate
+ * @param decimals - Token decimals
+ * @param fieldName - Name of the field for error messages
+ * @param allowZero - Whether zero values are allowed (default: false)
+ * @returns Object containing the parsed amount and any validation error
+ */
+export function validateAndParseAmount(
+  amount: string | undefined,
+  decimals: number,
+  fieldName: string,
+  allowZero = false,
+): { amount: bigint | undefined; error: string | undefined } {
+  if (!amount) {
+    return { amount: undefined, error: undefined };
+  }
+
+  try {
+    const parsedAmount = parseUnits(amount, decimals);
+    if (!allowZero && parsedAmount <= 0n) {
+      return {
+        amount: undefined,
+        error: `${fieldName} must be greater than 0`,
+      };
+    }
+    if (allowZero && parsedAmount < 0n) {
+      return {
+        amount: undefined,
+        error: `${fieldName} must be greater than or equal to 0`,
+      };
+    }
+    return { amount: parsedAmount, error: undefined };
+  } catch (error) {
+    return { amount: undefined, error: `Invalid ${fieldName.toLowerCase()}` };
+  }
+}
+
+/**
+ * Validates a start time to ensure it's today or later
+ * @param startTime - The start time string to validate
+ * @returns Validation error message or undefined if valid
+ */
+export function validateStartTime(startTime: string): string | undefined {
+  try {
+    const startTimeDate = convertReadableDateToTimestamp(startTime);
+    if (startTimeDate < getStartOfTodayUTC()) {
+      return 'Start time must be today or later';
+    }
+    return undefined;
+  } catch (error) {
+    return 'Invalid start time';
+  }
+}
+
+/**
+ * Validates an expiry time to ensure it's in the future
+ * @param expiry - The expiry time string to validate
+ * @returns Validation error message or undefined if valid
+ */
+export function validateExpiry(expiry: string): string | undefined {
+  try {
+    const expiryDate = convertReadableDateToTimestamp(expiry);
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    if (expiryDate < nowSeconds) {
+      return 'Expiry must be in the future';
+    }
+    return undefined;
+  } catch (error) {
+    return 'Invalid expiry';
+  }
+}
+
+/**
+ * Validates that max amount is greater than initial amount
+ * @param maxAmount - The maximum amount as BigInt
+ * @param initialAmount - The initial amount as BigInt
+ * @returns Validation error message or undefined if valid
+ */
+export function validateMaxAmountVsInitialAmount(
+  maxAmount: bigint | undefined,
+  initialAmount: bigint | undefined,
+): string | undefined {
+  if (
+    maxAmount !== undefined &&
+    initialAmount !== undefined &&
+    maxAmount < initialAmount
+  ) {
+    return 'Max amount must be greater than initial amount';
+  }
+  return undefined;
+}
+
+/**
+ * Calculates amount per second from amount per period
+ * @param amountPerPeriod - The amount per period as BigInt
+ * @param timePeriod - The time period
+ * @param decimals - Token decimals
+ * @returns Formatted amount per second string
+ */
+export function calculateAmountPerSecond(
+  amountPerPeriod: bigint,
+  timePeriod: TimePeriod,
+  decimals: number,
+): string {
+  return formatUnits(
+    amountPerPeriod / TIME_PERIOD_TO_SECONDS[timePeriod],
+    decimals,
+  );
+}
+
+/**
+ * Validates a period duration (for periodic permissions)
+ * @param periodDuration - The period duration string to validate
+ * @returns Object containing parsed duration and any validation error
+ */
+export function validatePeriodDuration(periodDuration: string): {
+  duration: number | undefined;
+  error: string | undefined;
+} {
+  try {
+    const duration = parseInt(periodDuration, 10);
+    if (isNaN(duration) || duration <= 0) {
+      return {
+        duration: undefined,
+        error: 'Period duration must be greater than 0',
+      };
+    }
+    return { duration, error: undefined };
+  } catch (error) {
+    return { duration: undefined, error: 'Invalid period duration' };
+  }
+}

packages/gator-permissions-snap/src/permissions/erc20TokenStream/context.ts

@@ -8,9 +8,15 @@ import { formatUnitsFromString } from '../../utils/balance';
 import {
   convertReadableDateToTimestamp,
   convertTimestampToReadableDate,
-  getStartOfTodayUTC,
   TIME_PERIOD_TO_SECONDS,
 } from '../../utils/time';
+import {
+  validateAndParseAmount,
+  validateStartTime,
+  validateExpiry,
+  validateMaxAmountVsInitialAmount,
+  calculateAmountPerSecond,
+} from '../contextValidation';
 import type {
   Erc20TokenStreamContext,
   Erc20TokenStreamPermissionRequest,
@@ -212,88 +218,64 @@ export async function deriveMetadata({
 
   const validationErrors: Erc20TokenStreamMetadata['validationErrors'] = {};
 
-  let maxAmountBigInt: bigint | undefined;
-  let initialAmountBigInt: bigint | undefined;
-  let amountPerSecondBigInt: bigint | undefined;
-  let amountPerSecond = 'Unknown';
-  if (permissionDetails.maxAmount) {
-    try {
-      maxAmountBigInt = parseUnits(permissionDetails.maxAmount, decimals);
-      if (maxAmountBigInt < 0n) {
-        validationErrors.maxAmountError = 'Max amount must be greater than 0';
-        maxAmountBigInt = undefined;
-      }
-    } catch (error) {
-      validationErrors.maxAmountError = 'Invalid max amount';
-    }
+  // Validate max amount
+  const maxAmountResult = validateAndParseAmount(
+    permissionDetails.maxAmount,
+    decimals,
+    'Max amount',
+    false, // Disallow zero for max amount
+  );
+  if (maxAmountResult.error) {
+    validationErrors.maxAmountError = maxAmountResult.error;
   }
 
-  if (permissionDetails.initialAmount) {
-    try {
-      initialAmountBigInt = parseUnits(
-        permissionDetails.initialAmount,
-        decimals,
-      );
-      if (initialAmountBigInt < 0n) {
-        validationErrors.initialAmountError =
-          'Initial amount must be greater than 0';
-        initialAmountBigInt = undefined;
-      }
-    } catch (error) {
-      validationErrors.initialAmountError = 'Invalid initial amount';
-    }
+  // Validate initial amount
+  const initialAmountResult = validateAndParseAmount(
+    permissionDetails.initialAmount,
+    decimals,
+    'Initial amount',
+    true, // Allow zero for initial amount
+  );
+  if (initialAmountResult.error) {
+    validationErrors.initialAmountError = initialAmountResult.error;
   }
 
-  try {
-    amountPerSecondBigInt = parseUnits(
-      permissionDetails.amountPerPeriod,
+  // Validate amount per period
+  const amountPerPeriodResult = validateAndParseAmount(
+    permissionDetails.amountPerPeriod,
+    decimals,
+    'Amount per period',
+  );
+  let amountPerSecond = 'Unknown';
+  if (amountPerPeriodResult.error) {
+    validationErrors.amountPerPeriodError = amountPerPeriodResult.error;
+  } else if (amountPerPeriodResult.amount) {
+    amountPerSecond = calculateAmountPerSecond(
+      amountPerPeriodResult.amount,
+      permissionDetails.timePeriod,
       decimals,
     );
-    if (amountPerSecondBigInt <= 0n) {
-      validationErrors.amountPerPeriodError =
-        'Amount per period must be greater than 0';
-      amountPerSecondBigInt = undefined;
-    } else {
-      amountPerSecond = formatUnits(
-        amountPerSecondBigInt /
-          TIME_PERIOD_TO_SECONDS[permissionDetails.timePeriod],
-        decimals,
-      );
-    }
-  } catch (error) {
-    validationErrors.amountPerPeriodError = 'Invalid amount per period';
   }
 
-  try {
-    const startTimeDate = convertReadableDateToTimestamp(
-      permissionDetails.startTime,
-    );
-
-    if (startTimeDate < getStartOfTodayUTC()) {
-      validationErrors.startTimeError = 'Start time must be today or later';
-    }
-  } catch (error) {
-    validationErrors.startTimeError = 'Invalid start time';
+  // Validate start time
+  const startTimeError = validateStartTime(permissionDetails.startTime);
+  if (startTimeError) {
+    validationErrors.startTimeError = startTimeError;
   }
 
-  try {
-    const expiryDate = convertReadableDateToTimestamp(expiry);
-    const nowSeconds = Math.floor(Date.now() / 1000);
-
-    if (expiryDate < nowSeconds) {
-      validationErrors.expiryError = 'Expiry must be in the future';
-    }
-  } catch (error) {
-    validationErrors.expiryError = 'Invalid expiry';
+  // Validate expiry
+  const expiryError = validateExpiry(expiry);
+  if (expiryError) {
+    validationErrors.expiryError = expiryError;
   }
 
-  if (
-    maxAmountBigInt !== undefined &&
-    initialAmountBigInt !== undefined &&
-    maxAmountBigInt < initialAmountBigInt
-  ) {
-    validationErrors.maxAmountError =
-      'Max amount must be greater than initial amount';
+  // Validate max amount vs initial amount
+  const maxVsInitialError = validateMaxAmountVsInitialAmount(
+    maxAmountResult.amount,
+    initialAmountResult.amount,
+  );
+  if (maxVsInitialError) {
+    validationErrors.maxAmountError = maxVsInitialError;
   }
 
   return {