feat: update time handling to ensure UTC consistency and local timezone conversion (#277)

* feat: update time handling to ensure UTC consistency and local timezone conversion

- Updated the localization strings in en.json to clarify that "Start Time" and "Expiry" are in UTC.
- Modified DateTimePickerField to use forceToLocalZone for displaying values in the local timezone.
- Added utility functions forceToUTC and forceToLocalZone to handle timezone conversions correctly.
- Enhanced tests for time utility functions to cover various scenarios including timezone offsets and formatting.
- Updated test cases across multiple components to reflect the changes in time handling and ensure consistency in displaying UTC times.

* feat: replace iso8601ToTimestamp with iso8601ToTimestampIgnoreTimezone for consistent UTC handling

* feat: allow past start dates for periodic and stream permissions

* feat: allow past dates for erc20 and native token periodic and stream permissions

Author: mj-kiwi

packages/gator-permissions-snap/locales/en.json

@@ -50,7 +50,7 @@
       "message": "The maximum amount of tokens that can be streamed."
     },
     "startTimeLabel": {
-      "message": "Start Time"
+      "message": "Start Time (UTC)"
     },
     "startTimeTooltip": {
       "message": "The time at which the first period begins"
@@ -59,7 +59,7 @@
       "message": "The start time of the stream"
     },
     "expiryLabel": {
-      "message": "Expiry"
+      "message": "Expiry (UTC)"
     },
     "expiryTooltip": {
       "message": "The expiry date of the permission"

packages/gator-permissions-snap/src/permissions/erc20TokenPeriodic/rules.ts

@@ -7,7 +7,7 @@ import {
   getClosestTimePeriod,
   TIME_PERIOD_TO_SECONDS,
   timestampToISO8601,
-  iso8601ToTimestamp,
+  iso8601ToTimestampIgnoreTimezone,
 } from '../../utils/time';
 import { getIconData } from '../iconUtil';
 import type {
@@ -102,14 +102,14 @@ export const startTimeRule: RuleDefinition<
     isVisible: true,
     tooltip: t('startTimeTooltip'),
     error: metadata.validationErrors.startTimeError,
-    allowPastDate: false,
+    allowPastDate: true, // start time can be in the past for periodic permissions
     isEditable: context.isAdjustmentAllowed,
   }),
   updateContext: (context: Erc20TokenPeriodicContext, value: string) => ({
     ...context,
     permissionDetails: {
       ...context.permissionDetails,
-      startTime: iso8601ToTimestamp(value),
+      startTime: iso8601ToTimestampIgnoreTimezone(value),
     },
   }),
 };

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

@@ -1,6 +1,9 @@
 import type { RuleDefinition } from '../../core/types';
 import { TimePeriod } from '../../core/types';
-import { timestampToISO8601, iso8601ToTimestamp } from '../../utils/time';
+import {
+  timestampToISO8601,
+  iso8601ToTimestampIgnoreTimezone,
+} from '../../utils/time';
 import { getIconData } from '../iconUtil';
 import { createExpiryRule } from '../rules';
 import type {
@@ -74,14 +77,14 @@ export const startTimeRule: Erc20TokenStreamRuleDefinition = {
     isVisible: true,
     tooltip: t('streamStartTimeTooltip'),
     error: metadata.validationErrors.startTimeError,
-    allowPastDate: false,
+    allowPastDate: true, // start time can be in the past
     isEditable: context.isAdjustmentAllowed,
   }),
   updateContext: (context: Erc20TokenStreamContext, value: string) => ({
     ...context,
     permissionDetails: {
       ...context.permissionDetails,
-      startTime: iso8601ToTimestamp(value),
+      startTime: iso8601ToTimestampIgnoreTimezone(value),
     },
   }),
 };

packages/gator-permissions-snap/src/permissions/nativeTokenPeriodic/rules.ts

@@ -7,7 +7,7 @@ import {
   getClosestTimePeriod,
   TIME_PERIOD_TO_SECONDS,
   timestampToISO8601,
-  iso8601ToTimestamp,
+  iso8601ToTimestampIgnoreTimezone,
 } from '../../utils/time';
 import { getIconData } from '../iconUtil';
 import type {
@@ -102,14 +102,14 @@ export const startTimeRule: RuleDefinition<
     isVisible: true,
     tooltip: t('startTimeTooltip'),
     error: metadata.validationErrors.startTimeError,
-    allowPastDate: false,
+    allowPastDate: true, // start time can be in the past
     isEditable: context.isAdjustmentAllowed,
   }),
   updateContext: (context: NativeTokenPeriodicContext, value: string) => ({
     ...context,
     permissionDetails: {
       ...context.permissionDetails,
-      startTime: iso8601ToTimestamp(value),
+      startTime: iso8601ToTimestampIgnoreTimezone(value),
     },
   }),
 };

packages/gator-permissions-snap/src/permissions/nativeTokenStream/rules.ts

@@ -1,6 +1,9 @@
 import type { RuleDefinition } from '../../core/types';
 import { TimePeriod } from '../../core/types';
-import { timestampToISO8601, iso8601ToTimestamp } from '../../utils/time';
+import {
+  timestampToISO8601,
+  iso8601ToTimestampIgnoreTimezone,
+} from '../../utils/time';
 import { getIconData } from '../iconUtil';
 import { createExpiryRule } from '../rules';
 import type {
@@ -75,14 +78,14 @@ export const startTimeRule: NativeTokenStreamRuleDefinition = {
     isVisible: true,
     tooltip: t('streamStartTimeTooltip'),
     error: metadata.validationErrors.startTimeError,
-    allowPastDate: false,
+    allowPastDate: true, // start time can be in the past
     isEditable: context.isAdjustmentAllowed,
   }),
   updateContext: (context: NativeTokenStreamContext, value: string) => ({
     ...context,
     permissionDetails: {
       ...context.permissionDetails,
-      startTime: iso8601ToTimestamp(value),
+      startTime: iso8601ToTimestampIgnoreTimezone(value),
     },
   }),
 };

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

@@ -15,7 +15,7 @@ import type {
 } from '../core/types';
 import type { TranslateFunction } from '../utils/i18n';
 import {
-  iso8601ToTimestamp,
+  iso8601ToTimestampIgnoreTimezone,
   TIME_PERIOD_TO_SECONDS,
   timestampToISO8601,
 } from '../utils/time';
@@ -72,7 +72,7 @@ export const createExpiryRule = <
           value === ''
             ? Math.floor(Date.now() / 1000) +
               Number(TIME_PERIOD_TO_SECONDS[TimePeriod.MONTHLY])
-            : iso8601ToTimestamp(value);
+            : iso8601ToTimestampIgnoreTimezone(value);
 
         expiry = {
           timestamp,

packages/gator-permissions-snap/src/ui/components/DateTimePickerField.tsx

@@ -3,6 +3,7 @@ import { DateTimePicker } from '@metamask/snaps-sdk/jsx';
 import type { BaseFieldProps } from './Field';
 import { Field } from './Field';
 import { TextField } from './TextField';
+import { forceToLocalZone } from '../../utils/time';
 
 export type DateTimePickerFieldParams = Pick<
   BaseFieldProps,
@@ -36,11 +37,13 @@ export const DateTimePickerField = ({
   const isFieldEnabled = value !== null && value !== undefined;
 
   if (!isEditable) {
-    // Format the ISO date to a readable format for display
+    // Format the ISO date to a readable format for display.
+    // We convert to local timezone for display purposes so users see the time
+    // they're familiar with, even though the internal timestamp representation is in UTC.
     let displayValue = value ?? '';
     if (value) {
       try {
-        const date = new Date(value);
+        const date = new Date(forceToLocalZone(value));
         if (!isNaN(date.getTime())) {
           displayValue = date.toLocaleString();
         }
@@ -67,9 +70,16 @@ export const DateTimePickerField = ({
       addFieldButtonName={addFieldButtonName}
       removeFieldButtonName={removeFieldButtonName}
     >
+      {/*
+        The DateTimePicker component from Snaps SDK shows times in the user's local timezone.
+        We convert the UTC timestamp to local timezone representation for display.
+        The user sees and edits times in their local timezone, but internally these are
+        converted back to UTC (via iso8601ToTimestampIgnoreTimezone) for consistent blockchain
+        execution regardless of the user's timezone.
+      */}
       <DateTimePicker
         name={name}
-        value={value}
+        value={forceToLocalZone(value)}
         type="datetime"
         disablePast={disablePast}
       />

packages/gator-permissions-snap/src/utils/time.ts

@@ -112,6 +112,40 @@ export const zPeriodDuration = zTimestamp
     return Number(TIME_PERIOD_TO_SECONDS[periodType]);
   });
 
+/**
+ * Forces any ISO 8601 string to be treated as UTC, ignoring the original timezone.
+ * e.g. "2026-04-17T18:14:00.000+12:00" → "2026-04-17T18:14:00.000Z"
+ * @param iso - The input ISO 8601 string, which may include a timezone offset.
+ * @returns The input ISO string with the timezone removed and replaced with 'Z' to indicate UTC.
+ */
+export const forceToUTC = (iso: string): string => {
+  const normalized = iso.replace(/([+-]\d{2}:\d{2}|Z)$/u, '');
+  return `${normalized}Z`;
+};
+
+/**
+ * Forces any ISO 8601 string to be treated as the local timezone, ignoring the original timezone.
+ * e.g. "2026-04-17T06:14:00.000Z" → "2026-04-17T06:14:00.000+12:00" (in NZ)
+ * e.g. "2026-04-17T06:14:00.000+05:00" → "2026-04-17T06:14:00.000+12:00" (in NZ)
+ * @param iso - The input ISO 8601 string, which may include a timezone offset.
+ * @returns The input ISO string with the timezone removed and replaced with the local timezone offset.
+ */
+export const forceToLocalZone = (iso: string | undefined): string => {
+  if (!iso) {
+    return '';
+  }
+  const normalized = iso.replace(/([+-]\d{2}:\d{2}|Z)$/u, '');
+  const date = new Date(normalized);
+  const offsetMinutes = -date.getTimezoneOffset();
+  const sign = offsetMinutes >= 0 ? '+' : '-';
+  const hours = String(Math.floor(Math.abs(offsetMinutes) / 60)).padStart(
+    2,
+    '0',
+  );
+  const minutes = String(Math.abs(offsetMinutes) % 60).padStart(2, '0');
+  return `${normalized}${sign}${hours}:${minutes}`;
+};
+
 /**
  * Converts a Unix timestamp (in seconds) to an ISO 8601 date string with timezone.
  * This format is required by the snaps-sdk DateTimePicker component.
@@ -133,17 +167,21 @@ export const timestampToISO8601 = (timestamp: number): string => {
 
 /**
  * Converts an ISO 8601 date string to a Unix timestamp (in seconds).
+ * This function ignores any timezone information in the input string and treats
+ * the time as UTC. For example, "2024-01-01T10:00:00.000+02:00" is treated as
+ * "2024-01-01T10:00:00.000Z", not as the UTC equivalent.
  * This is used to convert DateTimePicker values back to timestamps.
  *
- * @param iso - The ISO 8601 formatted date string.
+ * @param iso - The ISO 8601 formatted date string (timezone info will be ignored).
  * @returns The Unix timestamp in seconds.
  */
-export const iso8601ToTimestamp = (iso: string): number => {
-  const date = new Date(iso);
+export const iso8601ToTimestampIgnoreTimezone = (iso: string): number => {
+  const normalizedIso = forceToUTC(iso);
+  const date = new Date(normalizedIso);
 
   if (isNaN(date.getTime())) {
     throw new InvalidInputError(
-      `iso8601ToTimestamp: Invalid ISO 8601 string: ${iso}`,
+      `iso8601ToTimestampIgnoreTimezone: Invalid ISO 8601 string: ${iso}`,
     );
   }