fix(gateway): resolve plugin method scope from channel-pinned registry

Jacky Tan · jackytan123 · commit 5317a1555744 · 2026-06-11T23:13:01.000-07:00
In gateway mode the plugin registry is installed on the channel surface via
pinActivePluginChannelRegistry(); the flat `activeRegistry` field is never set
in that code path. resolveScopedMethod() and resolveSessionActionRegisteredScopes()
read getPluginRegistryState()?.activeRegistry directly, so every plugin-registered
gateway method / session action fails to resolve its scope, falls through to the
ADMIN_SCOPE default, and rejects operator.write clients (e.g. a bridge plugin
calling its own registered gateway method).

Use getActivePluginChannelRegistryFromState() (channel.registry ?? activeRegistry)
— the accessor already used throughout the channel/gateway code — so scope
resolution works in both gateway and standalone/test modes.

Add regression tests exercising the channel-pinned path; previously only the
activeRegistry/standalone path was covered, which is why this shipped.
diff --git a/src/gateway/method-scopes.test.ts b/src/gateway/method-scopes.test.ts
@@ -3,7 +3,11 @@
  */
 import { afterEach, describe, expect, it } from "vitest";
 import { createEmptyPluginRegistry } from "../plugins/registry-empty.js";
-import { setActivePluginRegistry } from "../plugins/runtime.js";
+import {
+  pinActivePluginChannelRegistry,
+  resetPluginRuntimeStateForTest,
+  setActivePluginRegistry,
+} from "../plugins/runtime.js";
 import {
   authorizeOperatorScopesForMethod,
   isGatewayMethodClassified,
@@ -227,6 +231,60 @@ describe("method scope resolution", () => {
   });
 });
 
+describe("plugin scope resolution in gateway (channel-pinned) mode", () => {
+  // Regression: in gateway mode the plugin registry is installed via
+  // pinActivePluginChannelRegistry (channel surface) and `activeRegistry` is
+  // never set. Scope resolution must read the channel-pinned registry; otherwise
+  // every plugin-registered gateway method falls through to the admin default
+  // and rejects operator.write clients (e.g. a bridge plugin's own gateway
+  // method registered with operator.write).
+  afterEach(() => {
+    resetPluginRuntimeStateForTest();
+  });
+
+  it("resolves a plugin gateway method scope from the channel-pinned registry", () => {
+    const registry = createEmptyPluginRegistry();
+    registry.gatewayHandlers["plugin.bridge.register"] = pluginHandler;
+    registry.gatewayMethodDescriptors.push(
+      createPluginGatewayMethodDescriptor({
+        pluginId: "bridge",
+        name: "plugin.bridge.register",
+        handler: pluginHandler,
+        scope: "operator.write",
+      }),
+    );
+    pinActivePluginChannelRegistry(registry);
+
+    expect(resolveLeastPrivilegeOperatorScopesForMethod("plugin.bridge.register")).toEqual([
+      "operator.write",
+    ]);
+  });
+
+  it("resolves a plugin session action scope from the channel-pinned registry", () => {
+    const registry = createEmptyPluginRegistry();
+    registry.sessionActions = [
+      {
+        pluginId: "scope-plugin",
+        pluginName: "Scope Plugin",
+        source: "test",
+        action: {
+          id: "view",
+          requiredScopes: ["operator.read"],
+          handler: () => ({ result: { ok: true } }),
+        },
+      },
+    ];
+    pinActivePluginChannelRegistry(registry);
+
+    expect(
+      resolveLeastPrivilegeOperatorScopesForMethod("plugins.sessionAction", {
+        pluginId: "scope-plugin",
+        actionId: "view",
+      }),
+    ).toEqual(["operator.read"]);
+  });
+});
+
 describe("operator scope authorization", () => {
   it.each([
     ["health", ["operator.read"], { allowed: true }],
diff --git a/src/gateway/method-scopes.ts b/src/gateway/method-scopes.ts
@@ -1,7 +1,7 @@
 // Gateway method authorization scope resolver.
 // Maps static and plugin-defined gateway methods to operator scopes.
 import { normalizeOptionalString as normalizeSessionActionParam } from "@openclaw/normalization-core/string-coerce";
-import { getPluginRegistryState } from "../plugins/runtime-state.js";
+import { getActivePluginChannelRegistryFromState } from "../plugins/runtime-state.js";
 import { resolveReservedGatewayMethodScope } from "../shared/gateway-method-policy.js";
 import {
   isCoreGatewayMethodClassified,
@@ -51,9 +51,13 @@ function resolveScopedMethod(method: string): OperatorScope | undefined {
   if (reservedScope) {
     return reservedScope;
   }
-  const pluginDescriptor = getPluginRegistryState()?.activeRegistry?.gatewayMethodDescriptors?.find(
-    (descriptor) => descriptor.name === method,
-  );
+  // In gateway mode plugins are pinned to the channel/httpRoute surfaces, not
+  // activeRegistry. Use the channel-surface helper, which returns
+  // channel.registry ?? activeRegistry and so covers gateway + standalone/test.
+  const pluginDescriptor =
+    getActivePluginChannelRegistryFromState()?.gatewayMethodDescriptors?.find(
+      (descriptor) => descriptor.name === method,
+    );
   const pluginScope = pluginDescriptor?.scope;
   return pluginScope === "node" || pluginScope === "dynamic" ? undefined : pluginScope;
 }
@@ -102,7 +106,7 @@ function resolveSessionActionRegisteredScopes(params: unknown): OperatorScope[]
   if (!pluginId || !actionId) {
     return undefined;
   }
-  const registration = getPluginRegistryState()?.activeRegistry?.sessionActions?.find(
+  const registration = getActivePluginChannelRegistryFromState()?.sessionActions?.find(
     (entry) => entry.pluginId === pluginId && entry.action.id === actionId,
   );
   if (!registration) {
