refactor(snaps-rpc-methods)!: Use messenger for permitted methods (#3987)

Migrate the permitted method handlers to use the `messenger` where
applicable.

https://consensyssoftware.atlassian.net/browse/WPC-995

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Refactors many permitted RPC handlers to route through controller
`messenger.call` actions instead of direct hook functions, which can
subtly change permission checks, origin handling, and side effects
across core Snap RPC methods.
> 
> **Overview**
> **Permitted Snap RPC methods are migrated from hook-based
implementations to `messenger`-driven controller actions.** Handlers now
declare `actionNames`, accept `JsonRpcRequestWithOrigin`, and call into
actions like `PermissionController:hasPermission`, `SnapController:*`,
`CronjobController:*`, `WebSocketService:*`,
`KeyringController:getState`, and `SnapInterfaceController:*`.
> 
> This removes the exported permitted `handlers` list and updates schema
generation to read permitted methods from `src/permitted/middleware.ts`
instead of the deleted `handlers.ts`, with associated test updates to
use `MockControllerMessenger` and origin middleware.
> 
> Also tightens the `get-file` example by asserting `snap_getFile`
returns content before `JSON.parse`, updates its manifest shasum, and
adjusts Jest coverage thresholds slightly.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
399e36b. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: FrederikBolding

packages/examples/packages/get-file/snap.manifest.json

@@ -7,7 +7,7 @@
     "url": "https://github.com/MetaMask/snaps.git"
   },
   "source": {
-    "shasum": "YEIejIfr+8rWTP0dSPc4HcLO1JwM/QQCwA/BItw5goE=",
+    "shasum": "HwhCRDjZxqIRT9rbHCNT11CoQ/YS8tO7ZFXrjxllpZ0=",
     "location": {
       "npm": {
         "filePath": "dist/bundle.js",

packages/examples/packages/get-file/src/index.ts

@@ -1,5 +1,6 @@
 import {
   MethodNotFoundError,
+  assert,
   type OnRpcRequestHandler,
 } from '@metamask/snaps-sdk';
 
@@ -28,6 +29,7 @@ export const onRpcRequest: OnRpcRequestHandler = async ({ request }) => {
         method: 'snap_getFile',
         params: { path: './files/foo.json', encoding: 'utf8' },
       });
+      assert(fileInPlaintext);
       return JSON.parse(fileInPlaintext);
     }
 

packages/snaps-rpc-methods/jest.config.js

@@ -10,10 +10,10 @@ module.exports = deepmerge(baseConfig, {
   ],
   coverageThreshold: {
     global: {
-      branches: 97.29,
-      functions: 98.85,
-      lines: 99.14,
-      statements: 98.81,
+      branches: 97.28,
+      functions: 98.88,
+      lines: 99.19,
+      statements: 98.91,
     },
   },
 });

packages/snaps-rpc-methods/scripts/generate-schema.mts

@@ -1294,7 +1294,7 @@ async function processPermittedHandler(
 }
 
 /**
- * Process the permitted handlers defined in `src/permitted/handlers.ts`,
+ * Process the permitted handlers defined in `src/permitted/middleware.ts`,
  * extracting the method names, descriptions, parameters, return types, and
  * subject types for each handler.
  *
@@ -1303,7 +1303,7 @@ async function processPermittedHandler(
  * @returns An array of method schemas extracted from the permitted handlers.
  */
 async function processPermittedHandlers(project: Project) {
-  const handlersFile = project.getSourceFile('src/permitted/handlers.ts');
+  const handlersFile = project.getSourceFile('src/permitted/middleware.ts');
   assert(handlersFile, 'Handlers file not found.');
 
   const permittedHandlers =

packages/snaps-rpc-methods/src/index.ts

@@ -1,10 +1,6 @@
-export {
-  handlers as permittedMethods,
-  createSnapsMethodMiddleware,
-} from './permitted';
+export { createSnapsMethodMiddleware } from './permitted';
 export type { PermittedRpcMethodHooks } from './permitted';
 export { SnapCaveatType } from '@metamask/snaps-utils';
-export { selectHooks } from './utils';
 export * from './endowments';
 export * from './middleware';
 export * from './permissions';

packages/snaps-rpc-methods/src/permitted/cancelBackgroundEvent.test.ts

@@ -1,55 +1,74 @@
-import { JsonRpcEngine } from '@metamask/json-rpc-engine';
+import {
+  JsonRpcEngine,
+  createOriginMiddleware,
+} from '@metamask/json-rpc-engine';
 import type {
   CancelBackgroundEventParams,
   CancelBackgroundEventResult,
+  SnapId,
 } from '@metamask/snaps-sdk';
-import { MOCK_SNAP_ID } from '@metamask/snaps-utils/test-utils';
+import {
+  MOCK_SNAP_ID,
+  MockControllerMessenger,
+} from '@metamask/snaps-utils/test-utils';
 import type { JsonRpcRequest, PendingJsonRpcResponse } from '@metamask/utils';
 
+import type { CancelBackgroundEventMethodActions } from './cancelBackgroundEvent';
 import { cancelBackgroundEventHandler } from './cancelBackgroundEvent';
 
 describe('snap_cancelBackgroundEvent', () => {
   describe('cancelBackgroundEventHandler', () => {
     it('has the expected shape', () => {
       expect(cancelBackgroundEventHandler).toMatchObject({
-        methodNames: ['snap_cancelBackgroundEvent'],
         implementation: expect.any(Function),
-        hookNames: {
-          cancelBackgroundEvent: true,
-        },
+        actionNames: [
+          'PermissionController:hasPermission',
+          'CronjobController:cancel',
+        ],
       });
     });
   });
 
   describe('implementation', () => {
-    const createOriginMiddleware =
-      (origin: string) =>
-      (request: any, _response: unknown, next: () => void, _end: unknown) => {
-        request.origin = origin;
-        next();
-      };
-
-    it('returns null after calling the `cancelBackgroundEvent` hook', async () => {
-      const { implementation } = cancelBackgroundEventHandler;
+    const getMessenger = () => {
+      const messenger = new MockControllerMessenger<
+        CancelBackgroundEventMethodActions,
+        never
+      >();
+
+      messenger.registerActionHandler(
+        'PermissionController:hasPermission',
+        () => true,
+      );
 
-      const cancelBackgroundEvent = jest.fn();
-      const hasPermission = jest.fn().mockImplementation(() => true);
+      messenger.registerActionHandler(
+        'CronjobController:cancel',
+        () => undefined,
+      );
 
-      const hooks = {
-        cancelBackgroundEvent,
-        hasPermission,
-      };
+      jest.spyOn(messenger, 'call');
+
+      return messenger;
+    };
+
+    it('returns null after calling the `CronjobController:cancel` action', async () => {
+      const { implementation } = cancelBackgroundEventHandler;
+
+      const messenger = getMessenger();
 
       const engine = new JsonRpcEngine();
 
       engine.push(createOriginMiddleware(MOCK_SNAP_ID));
       engine.push((request, response, next, end) => {
         const result = implementation(
-          request as JsonRpcRequest<CancelBackgroundEventParams>,
+          request as JsonRpcRequest<CancelBackgroundEventParams> & {
+            origin: SnapId;
+          },
           response as PendingJsonRpcResponse<CancelBackgroundEventResult>,
           next,
           end,
-          hooks,
+          {} as never,
+          messenger,
         );
 
         result?.catch(end);
@@ -70,24 +89,21 @@ describe('snap_cancelBackgroundEvent', () => {
     it('cancels a background event', async () => {
       const { implementation } = cancelBackgroundEventHandler;
 
-      const cancelBackgroundEvent = jest.fn();
-      const hasPermission = jest.fn().mockImplementation(() => true);
-
-      const hooks = {
-        cancelBackgroundEvent,
-        hasPermission,
-      };
+      const messenger = getMessenger();
 
       const engine = new JsonRpcEngine();
 
       engine.push(createOriginMiddleware(MOCK_SNAP_ID));
       engine.push((request, response, next, end) => {
         const result = implementation(
-          request as JsonRpcRequest<CancelBackgroundEventParams>,
+          request as JsonRpcRequest<CancelBackgroundEventParams> & {
+            origin: SnapId;
+          },
           response as PendingJsonRpcResponse<CancelBackgroundEventResult>,
           next,
           end,
-          hooks,
+          {} as never,
+          messenger,
         );
 
         result?.catch(end);
@@ -102,30 +118,36 @@ describe('snap_cancelBackgroundEvent', () => {
         },
       });
 
-      expect(cancelBackgroundEvent).toHaveBeenCalledWith('foo');
+      expect(messenger.call).toHaveBeenCalledWith(
+        'CronjobController:cancel',
+        MOCK_SNAP_ID,
+        'foo',
+      );
     });
 
     it('throws if a snap does not have the "endowment:cronjob" permission', async () => {
       const { implementation } = cancelBackgroundEventHandler;
 
-      const cancelBackgroundEvent = jest.fn();
-      const hasPermission = jest.fn().mockImplementation(() => false);
+      const messenger = getMessenger();
 
-      const hooks = {
-        cancelBackgroundEvent,
-        hasPermission,
-      };
+      messenger.registerActionHandler(
+        'PermissionController:hasPermission',
+        () => false,
+      );
 
       const engine = new JsonRpcEngine();
 
       engine.push(createOriginMiddleware(MOCK_SNAP_ID));
       engine.push((request, response, next, end) => {
         const result = implementation(
-          request as JsonRpcRequest<CancelBackgroundEventParams>,
+          request as JsonRpcRequest<CancelBackgroundEventParams> & {
+            origin: SnapId;
+          },
           response as PendingJsonRpcResponse<CancelBackgroundEventResult>,
           next,
           end,
-          hooks,
+          {} as never,
+          messenger,
         );
 
         result?.catch(end);
@@ -155,24 +177,21 @@ describe('snap_cancelBackgroundEvent', () => {
     it('throws on invalid params', async () => {
       const { implementation } = cancelBackgroundEventHandler;
 
-      const cancelBackgroundEvent = jest.fn();
-      const hasPermission = jest.fn().mockImplementation(() => true);
-
-      const hooks = {
-        cancelBackgroundEvent,
-        hasPermission,
-      };
+      const messenger = getMessenger();
 
       const engine = new JsonRpcEngine();
 
       engine.push(createOriginMiddleware(MOCK_SNAP_ID));
       engine.push((request, response, next, end) => {
         const result = implementation(
-          request as JsonRpcRequest<CancelBackgroundEventParams>,
+          request as JsonRpcRequest<CancelBackgroundEventParams> & {
+            origin: SnapId;
+          },
           response as PendingJsonRpcResponse<CancelBackgroundEventResult>,
           next,
           end,
-          hooks,
+          {} as never,
+          messenger,
         );
 
         result?.catch(end);

packages/snaps-rpc-methods/src/permitted/cancelBackgroundEvent.ts

@@ -1,29 +1,28 @@
-import type { JsonRpcEngineEndCallback } from '@metamask/json-rpc-engine';
+import type {
+  JsonRpcEngineEndCallback,
+  MethodHandler,
+} from '@metamask/json-rpc-engine';
+import type { Messenger } from '@metamask/messenger';
+import type { PermissionControllerHasPermissionAction } from '@metamask/permission-controller';
 import { providerErrors, rpcErrors } from '@metamask/rpc-errors';
 import type {
-  JsonRpcRequest,
   CancelBackgroundEventParams,
   CancelBackgroundEventResult,
+  SnapId,
 } from '@metamask/snaps-sdk';
 import { type InferMatching } from '@metamask/snaps-utils';
 import { StructError, create, object, string } from '@metamask/superstruct';
 import { type PendingJsonRpcResponse } from '@metamask/utils';
 
 import { SnapEndowments } from '../endowments';
-import type { PermittedHandlerExport } from '../types';
-import type { MethodHooksObject } from '../utils';
-
-const methodName = 'snap_cancelBackgroundEvent';
-
-const hookNames: MethodHooksObject<CancelBackgroundEventMethodHooks> = {
-  cancelBackgroundEvent: true,
-  hasPermission: true,
-};
+import type {
+  CronjobControllerCancelAction,
+  JsonRpcRequestWithOrigin,
+} from '../types';
 
-export type CancelBackgroundEventMethodHooks = {
-  cancelBackgroundEvent: (id: string) => void;
-  hasPermission: (permissionName: string) => boolean;
-};
+export type CancelBackgroundEventMethodActions =
+  | PermissionControllerHasPermissionAction
+  | CronjobControllerCancelAction;
 
 /**
  * Cancel a background event created by
@@ -46,13 +45,17 @@ export type CancelBackgroundEventMethodHooks = {
  * ```
  */
 export const cancelBackgroundEventHandler = {
-  methodNames: [methodName] as const,
   implementation: getCancelBackgroundEventImplementation,
-  hookNames,
-} satisfies PermittedHandlerExport<
-  CancelBackgroundEventMethodHooks,
+  actionNames: [
+    'PermissionController:hasPermission',
+    'CronjobController:cancel',
+  ],
+} satisfies MethodHandler<
+  never,
+  CancelBackgroundEventMethodActions,
   CancelBackgroundEventParameters,
-  CancelBackgroundEventResult
+  CancelBackgroundEventResult,
+  { origin: SnapId }
 >;
 
 const CancelBackgroundEventsParametersStruct = object({
@@ -72,21 +75,27 @@ export type CancelBackgroundEventParameters = InferMatching<
  * @param _next - The `json-rpc-engine` "next" callback. Not used by this
  * function.
  * @param end - The `json-rpc-engine` "end" callback.
- * @param hooks - The RPC method hooks.
- * @param hooks.cancelBackgroundEvent - The function to cancel a background event.
- * @param hooks.hasPermission - The function to check if a snap has the `endowment:cronjob` permission.
+ * @param _hooks - The RPC method hooks. Not used by this function.
+ * @param messenger - The messenger used to call controller actions.
  * @returns Nothing.
  */
 async function getCancelBackgroundEventImplementation(
-  req: JsonRpcRequest<CancelBackgroundEventParameters>,
+  req: JsonRpcRequestWithOrigin<CancelBackgroundEventParameters>,
   res: PendingJsonRpcResponse<CancelBackgroundEventResult>,
   _next: unknown,
   end: JsonRpcEngineEndCallback,
-  { cancelBackgroundEvent, hasPermission }: CancelBackgroundEventMethodHooks,
+  _hooks: never,
+  messenger: Messenger<string, CancelBackgroundEventMethodActions>,
 ): Promise<void> {
-  const { params } = req;
+  const { params, origin } = req;
 
-  if (!hasPermission(SnapEndowments.Cronjob)) {
+  if (
+    !messenger.call(
+      'PermissionController:hasPermission',
+      origin,
+      SnapEndowments.Cronjob,
+    )
+  ) {
     return end(providerErrors.unauthorized());
   }
 
@@ -95,7 +104,7 @@ async function getCancelBackgroundEventImplementation(
 
     const { id } = validatedParams;
 
-    cancelBackgroundEvent(id);
+    messenger.call('CronjobController:cancel', origin, id);
     res.result = null;
   } catch (error) {
     return end(error);