refactor(permission-controller)!: decouple permission middleware via messenger actions (MetaMask#8532)

Advances MetaMask#4238
Reverts MetaMask#8502 

- Rewrites `permission-middleware.ts` as a standalone
`createPermissionMiddleware({ messenger, subject })` factory that
dispatches through the `PermissionController:executeRestrictedMethod`
and `PermissionController:hasUnrestrictedMethod` messenger actions
instead of bound controller hooks. Removes the
`createPermissionMiddleware` property from `PermissionController`.
- Adds `createPermissionMiddlewareV2`, a `JsonRpcEngineV2` variant of
the same factory. Consumers using the legacy `JsonRpcEngine` can
continue to use the now-deprecated `createPermissionMiddleware`; new
integrations should prefer V2.
- Exposes `hasUnrestrictedMethod` as a public method / messenger action,
and makes `getRestrictedMethod` `#`-private (it has no remaining
external consumers now that the middleware goes through the messenger).
- When a restricted method returns `undefined`, the middleware now
propagates the plain `Error` thrown by `executeRestrictedMethod`; the
JSON-RPC engine serializes it as a standard internal error response
instead of a custom `internalError` with a `request` data payload.
- If properly typed, it's impossible for restricted methods to return
`undefined`. We nevertheless retain this check to minimize changes.


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **High Risk**
> High risk because it introduces a breaking API change by removing
`PermissionController.createPermissionMiddleware`/`getRestrictedMethod`
and rerouting enforcement through new messenger actions and a new
`JsonRpcEngineV2` middleware, which could affect all RPC permissioning
integrations.
> 
> **Overview**
> **Decouples permission enforcement middleware from
`PermissionController`.** The `json-rpc-engine` permission middleware is
removed from the controller and replaced with standalone exports
`createPermissionMiddleware` (legacy, *deprecated*) and
`createPermissionMiddlewareV2` (for `JsonRpcEngineV2`) that dispatch
permission checks/execution via messenger actions.
> 
> **Expands and reshapes the controller’s public surface via
messenger.** Adds `PermissionController:hasUnrestrictedMethod` and
`PermissionController:executeRestrictedMethod` action types/handlers,
makes `getRestrictedMethod` private, and updates error behavior when
restricted methods return no result (now a plain `Error`, which engines
serialize as internal errors). Documentation and tests are updated to
use the new middleware factories and the `JsonRpcEngineV2` path.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
257feaa. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: rekmarks

packages/permission-controller/ARCHITECTURE.md

@@ -326,18 +326,29 @@ const permissionController = new PermissionController({
 
 ### Adding the permission middleware
 
+The permission middleware is created via `createPermissionMiddlewareV2` for
+`JsonRpcEngineV2`, or via the deprecated `createPermissionMiddleware` for the
+legacy `JsonRpcEngine`. Both factories take a messenger with the
+`PermissionController:executeRestrictedMethod` and
+`PermissionController:hasUnrestrictedMethod` actions, typically obtained by
+delegating them from a root messenger to a subject-scoped messenger.
+
 ```typescript
 // This should take place where a middleware stack is created for a particular
 // subject.
 
 // The subject could be a port, stream, socket, etc.
 const origin = getOrigin(subject);
 
-const engine = new JsonRpcEngine();
-engine.push(/* your various middleware*/);
-engine.push(permissionController.createPermissionMiddleware({ origin }));
-// Your middleware stack is now permissioned
-engine.push(/* your other various middleware*/);
+// `messenger` is a messenger delegated the two actions listed above, e.g.
+// via `rootMessenger.delegate({ actions: [...], messenger: subjectMessenger })`.
+const engine = JsonRpcEngineV2.create({
+  middleware: [
+    /* your various middleware */
+    createPermissionMiddlewareV2({ messenger, subject: { origin } }),
+    /* your other various middleware */
+  ],
+});
 ```
 
 ### Calling a restricted method internally

packages/permission-controller/CHANGELOG.md

@@ -9,14 +9,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Expose `createPermissionMiddleware` through the messenger ([#8502](https://github.com/MetaMask/core/pull/8502))
+- Add `createPermissionMiddlewareV2`, a `JsonRpcEngineV2` variant of the standalone permission middleware factory ([#8532](https://github.com/MetaMask/core/pull/8532))
 
 ### Changed
 
+- **BREAKING:** Decouple the permission middleware from `PermissionController` and expose it as a standalone function ([#8532](https://github.com/MetaMask/core/pull/8532))
+  - The standalone `createPermissionMiddleware` replaces the former `PermissionController.createPermissionMiddleware`; it is imported from `@metamask/permission-controller` and called with a messenger and subject metadata, and targets the legacy `JsonRpcEngine`.
+  - New integrations should prefer `createPermissionMiddlewareV2`, which targets `JsonRpcEngineV2`.
+  - `PermissionController.getRestrictedMethod` no longer serves a purpose, and is removed. Restricted methods should be invoked via the `:executeRestrictedMethod` action instead.
 - Bump `@metamask/controller-utils` from `^11.19.0` to `^11.20.0` ([#8344](https://github.com/MetaMask/core/pull/8344))
 - Bump `@metamask/messenger` from `^1.0.0` to `^1.1.1` ([#8364](https://github.com/MetaMask/core/pull/8364), [#8373](https://github.com/MetaMask/core/pull/8373))
 - Bump `@metamask/base-controller` from `^9.0.1` to `^9.1.0` ([#8457](https://github.com/MetaMask/core/pull/8457))
 
+### Deprecated
+
+- Deprecate `createPermissionMiddleware` in favor of `createPermissionMiddlewareV2`, which targets `JsonRpcEngineV2` ([#8532](https://github.com/MetaMask/core/pull/8532))
+
 ## [12.3.0]
 
 ### Added
@@ -186,7 +194,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     ["Are the Types Wrong?"](https://arethetypeswrong.github.io/) tool as
     ["masquerading as CJS"](https://github.com/arethetypeswrong/arethetypeswrong.github.io/blob/main/docs/problems/FalseCJS.md).
     All of the ATTW checks now pass.
-- Remove chunk files ([#4648](https://github.com/MetaMask/core/pull/4648)).
+- Remove chunk files ([#4648](https://github.com/MetaMask/core/pull/4648))
   - Previously, the build tool we used to generate JavaScript files extracted
     common code to "chunk" files. While this was intended to make this package
     more tree-shakeable, it also made debugging more difficult for our

packages/permission-controller/src/PermissionController-method-action-types.ts

@@ -6,35 +6,25 @@
 import type { PermissionController } from './PermissionController';
 
 /**
- * Clears the state of the controller.
+ * Checks whether the given method was declared as unrestricted at
+ * construction time. Methods unknown to the controller return `false` and
+ * would be treated as restricted by callers such as the permission
+ * middleware.
+ *
+ * @param method - The name of the method to check.
+ * @returns Whether the method is unrestricted.
  */
-export type PermissionControllerClearStateAction = {
-  type: `PermissionController:clearState`;
-  handler: PermissionController['clearState'];
+export type PermissionControllerHasUnrestrictedMethodAction = {
+  type: `PermissionController:hasUnrestrictedMethod`;
+  handler: PermissionController['hasUnrestrictedMethod'];
 };
 
 /**
- * Creates a permission middleware function. Like any {@link JsonRpcEngine}
- * middleware, each middleware will only receive requests from a particular
- * subject / origin.
- *
- * The middlewares returned will pass through requests for
- * unrestricted methods, and attempt to execute restricted methods. If a method
- * is neither restricted nor unrestricted, a "method not found" error will be
- * returned.
- * If a method is restricted, the middleware will first attempt to retrieve the
- * subject's permission for that method. If the permission is found, the method
- * will be executed. Otherwise, an "unauthorized" error will be returned.
- *
- * The middleware **must** be added in the correct place in the middleware
- * stack in order for it to work. See the README for an example.
- *
- * @param subject The permission subject.
- * @returns A `json-rpc-engine` middleware.
+ * Clears the state of the controller.
  */
-export type PermissionControllerCreatePermissionMiddlewareAction = {
-  type: `PermissionController:createPermissionMiddleware`;
-  handler: PermissionController['createPermissionMiddleware'];
+export type PermissionControllerClearStateAction = {
+  type: `PermissionController:clearState`;
+  handler: PermissionController['clearState'];
 };
 
 /**
@@ -86,7 +76,7 @@ export type PermissionControllerHasPermissionsAction = {
 /**
  * Revokes all permissions from the specified origin.
  *
- * Throws an error of the origin has no permissions.
+ * Throws an error if the origin has no permissions.
  *
  * @param origin - The origin whose permissions to revoke.
  */
@@ -293,12 +283,42 @@ export type PermissionControllerGetEndowmentsAction = {
   handler: PermissionController['getEndowments'];
 };
 
+/**
+ * Executes a restricted method as the subject with the given origin.
+ * The specified params, if any, will be passed to the method implementation.
+ *
+ * ATTN: Great caution should be exercised in the use of this method.
+ * Methods that cause side effects or affect application state should
+ * be avoided.
+ *
+ * This method will first attempt to retrieve the requested restricted method
+ * implementation, throwing if it does not exist. The method will then be
+ * invoked as though the subject with the specified origin had invoked it with
+ * the specified parameters. This means that any existing caveats will be
+ * applied to the restricted method, and this method will throw if the
+ * restricted method or its caveat decorators throw.
+ *
+ * In addition, this method will throw if the subject does not have a
+ * permission for the specified restricted method.
+ *
+ * @param origin - The origin of the subject to execute the method on behalf
+ * of.
+ * @param targetName - The name of the method to execute. This must be a valid
+ * permission target name.
+ * @param params - The parameters to pass to the method implementation.
+ * @returns The result of the executed method.
+ */
+export type PermissionControllerExecuteRestrictedMethodAction = {
+  type: `PermissionController:executeRestrictedMethod`;
+  handler: PermissionController['executeRestrictedMethod'];
+};
+
 /**
  * Union of all PermissionController action types.
  */
 export type PermissionControllerMethodActions =
+  | PermissionControllerHasUnrestrictedMethodAction
   | PermissionControllerClearStateAction
-  | PermissionControllerCreatePermissionMiddlewareAction
   | PermissionControllerGetSubjectNamesAction
   | PermissionControllerGetPermissionsAction
   | PermissionControllerHasPermissionAction
@@ -312,4 +332,5 @@ export type PermissionControllerMethodActions =
   | PermissionControllerGrantPermissionsIncrementalAction
   | PermissionControllerRequestPermissionsAction
   | PermissionControllerRequestPermissionsIncrementalAction
-  | PermissionControllerGetEndowmentsAction;
+  | PermissionControllerGetEndowmentsAction
+  | PermissionControllerExecuteRestrictedMethodAction;