fix(gateway): authorize webchat session mutations by scope

steipete · steipete · commit 6e20935154a7 · 2026-07-18T12:15:14.000-07:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,7 @@ Docs: https://docs.openclaw.ai
 
 ### Changes
 
+- **Gateway session mutation authorization:** authorize WebChat and other Gateway clients by negotiated operator scopes instead of client ID or mode, so approved clients can manage sessions without impersonating Control UI.
 - **External gateway supervision:** add `OPENCLAW_SUPERVISOR_MODE=external` for lifecycle owners such as OCM, preserving verified restart and deferral behavior without exposing native service authority, blocking native service mutation and self-update, and providing a versioned atomic restart-handoff consume contract. Thanks @shakkernerd.
 - **ClickClack guided setup:** configure ClickClack from `openclaw onboard` or `openclaw channels add clickclack` with URL, token, and workspace prompts, default-account env fallback, nonfatal live connection validation, and gateway-aware next steps that connect automatically when OpenClaw is already running. Thanks @shakkernerd.
 - **ClickClack command menus:** publish each bot's native OpenClaw commands to ClickClack composer autocomplete at gateway startup, with per-account opt-out and nonfatal compatibility handling for older tokens and servers. Thanks @shakkernerd.
diff --git a/docs/gateway/operator-scopes.md b/docs/gateway/operator-scopes.md
@@ -58,6 +58,11 @@ the concrete thing being approved or mutated:
 This lets lower-scope operators perform low-risk pairing actions without
 making all pairing approval admin-only.
 
+Session mutation RPCs are authorized by their negotiated operator scopes,
+independent of the connecting client's `client.id` or `client.mode`. Client
+identity can still affect connection and device-auth policy, but it neither
+grants nor removes session mutation authority.
+
 ## Device pairing approvals
 
 Device pairing records are the durable source of approved roles and scopes.
diff --git a/src/gateway/server-methods/sessions-compact.ts b/src/gateway/server-methods/sessions-compact.ts
@@ -35,15 +35,14 @@ import {
 import {
   emitSessionOperation,
   loadAccessorSessionEntryForGatewayTarget,
-  rejectWebchatSessionMutation,
   requireSessionKey,
   resolveGatewaySessionTargetFromKey,
 } from "./sessions-shared.js";
 import type { GatewayRequestHandlers } from "./types.js";
 import { assertValidParams } from "./validation.js";
 
 export const sessionCompactHandlers: GatewayRequestHandlers = {
-  "sessions.compact": async ({ params, respond, context, client, isWebchatConnect }) => {
+  "sessions.compact": async ({ params, respond, context }) => {
     if (!assertValidParams(params, validateSessionsCompactParams, "sessions.compact", respond)) {
       return;
     }
@@ -52,10 +51,6 @@ export const sessionCompactHandlers: GatewayRequestHandlers = {
     if (!key) {
       return;
     }
-    if (rejectWebchatSessionMutation({ action: "compact", client, isWebchatConnect, respond })) {
-      return;
-    }
-
     const maxLines =
       typeof p.maxLines === "number" && Number.isFinite(p.maxLines)
         ? Math.max(1, Math.floor(p.maxLines))
diff --git a/src/gateway/server-methods/sessions-compaction-checkpoints.ts b/src/gateway/server-methods/sessions-compaction-checkpoints.ts
@@ -24,7 +24,6 @@ import { emitSessionsChanged } from "./session-change-event.js";
 import { interruptSessionRunIfActive } from "./sessions-messaging.js";
 import {
   loadAccessorSessionEntryForGatewayTarget,
-  rejectWebchatSessionMutation,
   requireSessionKey,
   resolveSessionWorkerPlacementMutationError,
   respondSessionWorkerPlacementMutationError,
@@ -38,7 +37,7 @@ const MODEL_SELECTION_LOCKED_CHECKPOINT_MESSAGE =
   "Checkpoint branch and restore are unavailable while model selection is locked.";
 
 export const sessionCheckpointHandlers: GatewayRequestHandlers = {
-  "sessions.compaction.branch": async ({ params, respond, context, client, isWebchatConnect }) => {
+  "sessions.compaction.branch": async ({ params, respond, context }) => {
     if (
       !assertValidParams(
         params,
@@ -54,9 +53,6 @@ export const sessionCheckpointHandlers: GatewayRequestHandlers = {
     if (!key) {
       return;
     }
-    if (rejectWebchatSessionMutation({ action: "branch", client, isWebchatConnect, respond })) {
-      return;
-    }
     const checkpointId =
       typeof p.checkpointId === "string" && p.checkpointId.trim() ? p.checkpointId.trim() : "";
     if (!checkpointId) {
@@ -184,9 +180,6 @@ export const sessionCheckpointHandlers: GatewayRequestHandlers = {
     if (!key) {
       return;
     }
-    if (rejectWebchatSessionMutation({ action: "restore", client, isWebchatConnect, respond })) {
-      return;
-    }
     const checkpointId =
       typeof p.checkpointId === "string" && p.checkpointId.trim() ? p.checkpointId.trim() : "";
     if (!checkpointId) {
diff --git a/src/gateway/server-methods/sessions-delete.ts b/src/gateway/server-methods/sessions-delete.ts
@@ -32,7 +32,6 @@ import {
   loadAccessorSessionEntryForGatewayTarget,
   loadSessionsRuntimeModule,
   rejectPluginRuntimeDeleteMismatch,
-  rejectWebchatSessionMutation,
   requireSessionKey,
   resolveGatewaySessionTargetFromKey,
   resolveSessionWorkerPlacementMutationError,
@@ -52,10 +51,6 @@ export const sessionDeleteHandlers: GatewayRequestHandlers = {
     if (!key) {
       return;
     }
-    if (rejectWebchatSessionMutation({ action: "delete", client, isWebchatConnect, respond })) {
-      return;
-    }
-
     const cfg = context.getRuntimeConfig();
     const requestedAgent = resolveRequestedGlobalAgentId(cfg, key, p.agentId);
     if (!requestedAgent.ok) {
diff --git a/src/gateway/server-methods/sessions-dispatch.ts b/src/gateway/server-methods/sessions-dispatch.ts
@@ -17,24 +17,20 @@ import {
 import {
   isWorkerDispatchInputError,
   loadAccessorSessionEntryForGatewayTarget,
-  rejectWebchatSessionMutation,
   requireSessionKey,
 } from "./sessions-shared.js";
 import type { GatewayRequestHandlers } from "./types.js";
 import { assertValidParams } from "./validation.js";
 
 export const sessionDispatchHandlers: GatewayRequestHandlers = {
-  "sessions.dispatch": async ({ params, respond, context, client, isWebchatConnect }) => {
+  "sessions.dispatch": async ({ params, respond, context }) => {
     if (!assertValidParams(params, validateSessionsDispatchParams, "sessions.dispatch", respond)) {
       return;
     }
     const key = requireSessionKey(params.key, respond);
     if (!key) {
       return;
     }
-    if (rejectWebchatSessionMutation({ action: "dispatch", client, isWebchatConnect, respond })) {
-      return;
-    }
     const dispatchService = context.workerPlacementDispatchService;
     const placementReader = context.workerSessionPlacementService;
     if (!dispatchService || !placementReader) {
@@ -163,17 +159,14 @@ export const sessionDispatchHandlers: GatewayRequestHandlers = {
       );
     }
   },
-  "sessions.reclaim": async ({ params, respond, context, client, isWebchatConnect }) => {
+  "sessions.reclaim": async ({ params, respond, context }) => {
     if (!assertValidParams(params, validateSessionsReclaimParams, "sessions.reclaim", respond)) {
       return;
     }
     const key = requireSessionKey(params.key, respond);
     if (!key) {
       return;
     }
-    if (rejectWebchatSessionMutation({ action: "reclaim", client, isWebchatConnect, respond })) {
-      return;
-    }
     const placementService = context.workerPlacementDispatchService;
     const placementReader = context.workerSessionPlacementService;
     if (!placementService?.reclaim || !placementReader) {
diff --git a/src/gateway/server-methods/sessions-mutations.ts b/src/gateway/server-methods/sessions-mutations.ts
@@ -39,7 +39,6 @@ import { emitSessionsChanged } from "./session-change-event.js";
 import {
   isAgentMainSessionKey,
   loadSessionsRuntimeModule,
-  rejectWebchatSessionMutation,
   requireSessionKey,
   resolveGatewaySessionTargetFromKey,
   resolveSessionWorkerPlacementPatchError,
@@ -49,7 +48,7 @@ import type { GatewayRequestHandlers } from "./types.js";
 import { assertValidParams } from "./validation.js";
 
 export const sessionMutationHandlers: GatewayRequestHandlers = {
-  "sessions.patch": async ({ params, respond, context, client, isWebchatConnect }) => {
+  "sessions.patch": async ({ params, respond, context, client }) => {
     if (!assertValidParams(params, validateSessionsPatchParams, "sessions.patch", respond)) {
       return;
     }
@@ -58,10 +57,6 @@ export const sessionMutationHandlers: GatewayRequestHandlers = {
     if (!key) {
       return;
     }
-    if (rejectWebchatSessionMutation({ action: "patch", client, isWebchatConnect, respond })) {
-      return;
-    }
-
     const cfg = context.getRuntimeConfig();
     const requestedAgent = resolveRequestedGlobalAgentId(cfg, key, p.agentId);
     if (!requestedAgent.ok) {
@@ -315,7 +310,7 @@ export const sessionMutationHandlers: GatewayRequestHandlers = {
       reason: "patch",
     });
   },
-  "sessions.pluginPatch": async ({ params, respond, context, client, isWebchatConnect }) => {
+  "sessions.pluginPatch": async ({ params, respond, context, client }) => {
     if (
       !assertValidParams(params, validateSessionsPluginPatchParams, "sessions.pluginPatch", respond)
     ) {
@@ -325,9 +320,6 @@ export const sessionMutationHandlers: GatewayRequestHandlers = {
     if (!key) {
       return;
     }
-    if (rejectWebchatSessionMutation({ action: "patch", client, isWebchatConnect, respond })) {
-      return;
-    }
     const scopes = Array.isArray(client?.connect.scopes) ? client.connect.scopes : [];
     if (!scopes.includes(ADMIN_SCOPE)) {
       respond(
diff --git a/src/gateway/server-methods/sessions-rewind.ts b/src/gateway/server-methods/sessions-rewind.ts
@@ -31,7 +31,6 @@ import { hasVisibleActiveSessionRun } from "./session-active-runs.js";
 import { emitSessionsChanged } from "./session-change-event.js";
 import {
   loadAccessorSessionEntryForGatewayTarget,
-  rejectWebchatSessionMutation,
   resolveSessionWorkerPlacementMutationError,
   respondSessionWorkerPlacementMutationError,
 } from "./sessions-shared.js";
@@ -145,7 +144,7 @@ async function mutateSessionAtMessage(
   options: GatewayRequestHandlerOptions,
   action: MessageCutAction,
 ): Promise<void> {
-  const { params, respond, context, client, isWebchatConnect } = options;
+  const { params, respond, context } = options;
   const sessionKey = typeof params.sessionKey === "string" ? params.sessionKey.trim() : "";
   const entryId =
     action === "switch"
@@ -155,16 +154,6 @@ async function mutateSessionAtMessage(
       : typeof params.entryId === "string"
         ? params.entryId.trim()
         : "";
-  if (
-    rejectWebchatSessionMutation({
-      action,
-      client,
-      isWebchatConnect,
-      respond,
-    })
-  ) {
-    return;
-  }
   const cfg = context.getRuntimeConfig();
   const requestedAgent = resolveRequestedGlobalAgentId(
     cfg,
diff --git a/src/gateway/server-methods/sessions-shared.ts b/src/gateway/server-methods/sessions-shared.ts
@@ -1,6 +1,5 @@
 // Shared session-handler target resolution and mutation guards.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
-import { GATEWAY_CLIENT_IDS } from "../../../packages/gateway-protocol/src/client-info.js";
 import {
   ErrorCodes,
   errorShape,
@@ -277,39 +276,6 @@ export function emitSessionOperation(
   );
 }
 
-export function rejectWebchatSessionMutation(params: {
-  action:
-    | "patch"
-    | "delete"
-    | "compact"
-    | "branch"
-    | "restore"
-    | "rewind"
-    | "fork"
-    | "switch"
-    | "dispatch"
-    | "reclaim";
-  client: GatewayClient | null;
-  isWebchatConnect: (params: GatewayClient["connect"] | null | undefined) => boolean;
-  respond: RespondFn;
-}): boolean {
-  if (!params.client?.connect || !params.isWebchatConnect(params.client.connect)) {
-    return false;
-  }
-  if (params.client.connect.client.id === GATEWAY_CLIENT_IDS.CONTROL_UI) {
-    return false;
-  }
-  params.respond(
-    false,
-    undefined,
-    errorShape(
-      ErrorCodes.INVALID_REQUEST,
-      `webchat clients cannot ${params.action} sessions; use chat.send for session-scoped updates`,
-    ),
-  );
-  return true;
-}
-
 export function isWorkerDispatchInputError(error: unknown): boolean {
   if (typeof error !== "object" || error === null || !("code" in error)) {
     return false;
diff --git a/src/gateway/server.sessions.permissions-hooks.test.ts b/src/gateway/server.sessions.permissions-hooks.test.ts
diff --git a/src/gateway/test-helpers.server.ts b/src/gateway/test-helpers.server.ts
