Add method decodePermissionFromPermissionContextForOrigin to GatorPermissionsController

- rejects any request from an origin other than the gator permission snap
- attempts to identify the permission type, and decode the data
- rejects any request where a unique permission is unable to be decoded

Also renames GatorPermissionsController.test.ts

Author: jeffsmale90

packages/gator-permissions-controller/package.json

@@ -49,6 +49,8 @@
   "dependencies": {
     "@metamask/7715-permission-types": "^0.3.0",
     "@metamask/base-controller": "^8.3.0",
+    "@metamask/delegation-core": "^0.2.0-rc.1",
+    "@metamask/delegation-deployments": "^0.12.0",
     "@metamask/snaps-sdk": "^9.0.0",
     "@metamask/snaps-utils": "^11.0.0",
     "@metamask/utils": "^11.4.2"

packages/gator-permissions-controller/src/GatorPermissionContoller.test.ts renamed to packages/gator-permissions-controller/src/GatorPermissionsController.test.ts

@@ -3,6 +3,16 @@ import { Messenger, deriveStateFromMetadata } from '@metamask/base-controller';
 import type { HandleSnapRequest, HasSnap } from '@metamask/snaps-controllers';
 import type { SnapId } from '@metamask/snaps-sdk';
 import type { Hex } from '@metamask/utils';
+import {
+  CHAIN_ID,
+  DELEGATOR_CONTRACTS,
+} from '@metamask/delegation-deployments';
+import {
+  createTimestampTerms,
+  createNativeTokenStreamingTerms,
+  encodeDelegations,
+} from '@metamask/delegation-core';
+import { toHex } from '@metamask/controller-utils';
 
 import type { GatorPermissionsControllerMessenger } from './GatorPermissionsController';
 import GatorPermissionsController from './GatorPermissionsController';
@@ -23,6 +33,7 @@ import type {
   ExtractAvailableAction,
   ExtractAvailableEvent,
 } from '../../base-controller/tests/helpers';
+import { DELEGATION_FRAMEWORK_VERSION } from './decodePermission';
 
 const MOCK_CHAIN_ID_1: Hex = '0xaa36a7';
 const MOCK_CHAIN_ID_2: Hex = '0x1';
@@ -453,6 +464,179 @@ describe('GatorPermissionsController', () => {
       `);
     });
   });
+
+  describe('decodePermissionFromPermissionContextForOrigin', () => {
+    const chainId = CHAIN_ID.sepolia;
+    const contracts =
+      DELEGATOR_CONTRACTS[DELEGATION_FRAMEWORK_VERSION][chainId];
+
+    let controller: GatorPermissionsController;
+
+    beforeEach(() => {
+      controller = new GatorPermissionsController({
+        messenger: getMessenger(),
+      });
+    });
+
+    it('decodes a native-token-stream permission context successfully', async () => {
+      const {
+        TimestampEnforcer,
+        NativeTokenStreamingEnforcer,
+        ExactCalldataEnforcer,
+      } = contracts;
+
+      const delegator = '0x1111111111111111111111111111111111111111';
+      const delegate = '0x2222222222222222222222222222222222222222';
+
+      const timestampBeforeThreshold = 1720000;
+      const expiryTerms = createTimestampTerms(
+        { timestampAfterThreshold: 0, timestampBeforeThreshold },
+        { out: 'hex' },
+      );
+
+      const initialAmount = 123456n;
+      const maxAmount = 999999n;
+      const amountPerSecond = 1n;
+      const startTime = 1715664;
+      const streamTerms = createNativeTokenStreamingTerms(
+        { initialAmount, maxAmount, amountPerSecond, startTime },
+        { out: 'hex' },
+      );
+
+      const caveats = [
+        {
+          enforcer: TimestampEnforcer,
+          terms: expiryTerms,
+          args: '0x',
+        } as const,
+        {
+          enforcer: NativeTokenStreamingEnforcer,
+          terms: streamTerms,
+          args: '0x',
+        } as const,
+        { enforcer: ExactCalldataEnforcer, terms: '0x', args: '0x' } as const,
+      ];
+
+      const permissionContext = encodeDelegations(
+        [
+          {
+            delegate,
+            delegator,
+            authority: '0x',
+            caveats,
+            salt: 0n,
+            signature: '0x',
+          },
+        ],
+        { out: 'hex' },
+      );
+
+      const result =
+        await controller.decodePermissionFromPermissionContextForOrigin({
+          origin: controller.permissionsProviderSnapId,
+          chainId,
+          permissionContext,
+        });
+
+      expect(result.chainId).toBe(toHex(chainId));
+      expect(result.address).toBe(delegator);
+      expect(result.signer).toStrictEqual({
+        type: 'account',
+        data: { address: delegate },
+      });
+      expect(result.permission.type).toBe('native-token-stream');
+      expect(result.expiry).toBe(timestampBeforeThreshold);
+      expect(result.permission.data).toStrictEqual({
+        initialAmount,
+        maxAmount,
+        amountPerSecond,
+        startTime,
+      });
+    });
+
+    it('throws when origin does not match permissions provider', async () => {
+      await expect(
+        controller.decodePermissionFromPermissionContextForOrigin({
+          origin: 'not-the-provider',
+          chainId: 1,
+          permissionContext: '0x',
+        }),
+      ).rejects.toThrow('Origin not-the-provider not allowed');
+    });
+
+    it('throws when the permission context contains multiple delegations', async () => {
+      const permissionContext = encodeDelegations(
+        [
+          {
+            delegate: '0x1',
+            delegator: '0x2',
+            authority: '0x',
+            caveats: [],
+            salt: 0n,
+            signature: '0x',
+          },
+          {
+            delegate: '0x3',
+            delegator: '0x4',
+            authority: '0x',
+            caveats: [],
+            salt: 0n,
+            signature: '0x',
+          },
+        ],
+        { out: 'hex' },
+      );
+
+      await expect(
+        controller.decodePermissionFromPermissionContextForOrigin({
+          origin: controller.permissionsProviderSnapId,
+          chainId: 1,
+          permissionContext,
+        }),
+      ).rejects.toThrow('Failed to decode permission');
+    });
+
+    it('throws when enforcers do not identify a supported permission', async () => {
+      const { TimestampEnforcer, ValueLteEnforcer } = contracts;
+
+      const expiryTerms = createTimestampTerms(
+        { timestampAfterThreshold: 0, timestampBeforeThreshold: 100 },
+        { out: 'hex' },
+      );
+
+      const caveats = [
+        {
+          enforcer: TimestampEnforcer,
+          terms: expiryTerms,
+          args: '0x',
+        } as const,
+        // Include a forbidden/irrelevant enforcer without required counterparts
+        { enforcer: ValueLteEnforcer, terms: '0x', args: '0x' } as const,
+      ];
+
+      const permissionContext = encodeDelegations(
+        [
+          {
+            delegate: '0x1111111111111111111111111111111111111111',
+            delegator: '0x2222222222222222222222222222222222222222',
+            authority: '0x',
+            caveats,
+            salt: 0n,
+            signature: '0x',
+          },
+        ],
+        { out: 'hex' },
+      );
+
+      await expect(
+        controller.decodePermissionFromPermissionContextForOrigin({
+          origin: controller.permissionsProviderSnapId,
+          chainId,
+          permissionContext,
+        }),
+      ).rejects.toThrow('Unable to identify permission type');
+    });
+  });
 });
 
 /**

packages/gator-permissions-controller/src/GatorPermissionsController.ts

@@ -1,4 +1,4 @@
-import type { Signer } from '@metamask/7715-permission-types';
+import type { Hex, Signer } from '@metamask/7715-permission-types';
 import type {
   RestrictedMessenger,
   ControllerGetStateAction,
@@ -14,6 +14,8 @@ import {
   GatorPermissionsFetchError,
   GatorPermissionsNotEnabledError,
   GatorPermissionsProviderError,
+  OriginNotAllowedError,
+  PermissionDecodingError,
 } from './errors';
 import { controllerLog } from './logger';
 import type { StoredGatorPermissionSanitized } from './types';
@@ -27,6 +29,13 @@ import {
   deserializeGatorPermissionsMap,
   serializeGatorPermissionsMap,
 } from './utils';
+import { decodeDelegations } from '@metamask/delegation-core';
+import {
+  DecodedPermission,
+  getPermissionDataAndExpiry,
+  identifyPermissionByEnforcers,
+  reconstructDecodedPermission,
+} from './decodePermission';
 
 // === GENERAL ===
 
@@ -155,6 +164,12 @@ export type GatorPermissionsControllerDisableGatorPermissionsAction = {
   handler: GatorPermissionsController['disableGatorPermissions'];
 };
 
+export type GatorPermissionsControllerDecodePermissionFromPermissionContextForOriginAction =
+  {
+    type: `${typeof controllerName}:decodePermissionFromPermissionContextForOrigin`;
+    handler: GatorPermissionsController['decodePermissionFromPermissionContextForOrigin'];
+  };
+
 /**
  * All actions that {@link GatorPermissionsController} registers, to be called
  * externally.
@@ -163,7 +178,8 @@ export type GatorPermissionsControllerActions =
   | GatorPermissionsControllerGetStateAction
   | GatorPermissionsControllerFetchAndUpdateGatorPermissionsAction
   | GatorPermissionsControllerEnableGatorPermissionsAction
-  | GatorPermissionsControllerDisableGatorPermissionsAction;
+  | GatorPermissionsControllerDisableGatorPermissionsAction
+  | GatorPermissionsControllerDecodePermissionFromPermissionContextForOriginAction;
 
 /**
  * All actions that {@link GatorPermissionsController} calls internally.
@@ -268,6 +284,11 @@ export default class GatorPermissionsController extends BaseController<
       `${controllerName}:disableGatorPermissions`,
       this.disableGatorPermissions.bind(this),
     );
+
+    this.messagingSystem.registerActionHandler(
+      `${controllerName}:decodePermissionFromPermissionContextForOrigin`,
+      this.decodePermissionFromPermissionContextForOrigin.bind(this),
+    );
   }
 
   /**
@@ -490,4 +511,73 @@ export default class GatorPermissionsController extends BaseController<
       this.#setIsFetchingGatorPermissions(false);
     }
   }
+
+  /**
+   * Decodes a permission context into a structured permission for a specific origin.
+   *
+   * This method validates the caller origin, decodes the provided `permissionContext`
+   * into delegations, identifies the permission type from the caveat enforcers,
+   * extracts the permission-specific data and expiry, and reconstructs a
+   * {@link DecodedPermission} containing chainId, account addresses, signer, type and data.
+   *
+   * @param origin - The caller's origin; must match the configured permissions provider Snap id.
+   * @param chainId - Numeric EIP-155 chain id used for resolving enforcer contracts and encoding.
+   * @param permissionContext - Encoded delegation payload (hex) containing the permission.
+   * @returns A decoded permission object suitable for UI consumption and follow-up actions.
+   * @throws If the origin is not allowed, the context cannot be decoded into exactly one delegation,
+   *         or the enforcers/terms do not match a supported permission type.
+   */
+  public async decodePermissionFromPermissionContextForOrigin({
+    origin,
+    chainId,
+    permissionContext,
+  }: {
+    origin: string;
+    chainId: number;
+    permissionContext: Hex;
+  }): Promise<DecodedPermission> {
+    if (origin !== this.permissionsProviderSnapId) {
+      throw new OriginNotAllowedError({ origin });
+    }
+
+    const delegations = decodeDelegations(permissionContext);
+
+    if (delegations.length !== 1) {
+      throw new PermissionDecodingError({
+        cause: 'Multiple delegations found',
+      });
+    }
+
+    const [{ caveats, delegator, delegate }] = delegations;
+
+    try {
+      const enforcers = caveats.map((caveat) => caveat.enforcer);
+
+      const permissionType = identifyPermissionByEnforcers({
+        enforcers,
+        chainId,
+      });
+
+      const { expiry, data } = getPermissionDataAndExpiry({
+        chainId,
+        caveats,
+        permissionType,
+      });
+
+      const permission = reconstructDecodedPermission({
+        chainId,
+        permissionType,
+        delegator,
+        delegate,
+        expiry,
+        data,
+      });
+
+      return permission;
+    } catch (error) {
+      throw new PermissionDecodingError({
+        cause: error as Error,
+      });
+    }
+  }
 }