refactor(security): unify gateway scope authorization flows

src/gateway/call.test.ts

@@ -75,7 +75,8 @@ vi.mock("./client.js", () => ({
   },
 }));
 
-const { buildGatewayConnectionDetails, callGateway } = await import("./call.js");
+const { buildGatewayConnectionDetails, callGateway, callGatewayCli, callGatewayScoped } =
+  await import("./call.js");
 
 function resetGatewayCallMocks() {
   loadConfig.mockReset();
@@ -198,13 +199,23 @@ describe("callGateway url resolution", () => {
     expect(lastClientOptions?.token).toBe("explicit-token");
   });
 
-  it("keeps legacy admin scopes when call scopes are omitted", async () => {
+  it("uses least-privilege scopes by default for non-CLI callers", async () => {
     loadConfig.mockReturnValue({ gateway: { mode: "local", bind: "loopback" } });
     resolveGatewayPort.mockReturnValue(18789);
     pickPrimaryTailnetIPv4.mockReturnValue(undefined);
 
     await callGateway({ method: "health" });
 
+    expect(lastClientOptions?.scopes).toEqual(["operator.read"]);
+  });
+
+  it("keeps legacy admin scopes for explicit CLI callers", async () => {
+    loadConfig.mockReturnValue({ gateway: { mode: "local", bind: "loopback" } });
+    resolveGatewayPort.mockReturnValue(18789);
+    pickPrimaryTailnetIPv4.mockReturnValue(undefined);
+
+    await callGatewayCli({ method: "health" });
+
     expect(lastClientOptions?.scopes).toEqual([
       "operator.admin",
       "operator.approvals",
@@ -217,10 +228,10 @@ describe("callGateway url resolution", () => {
     resolveGatewayPort.mockReturnValue(18789);
     pickPrimaryTailnetIPv4.mockReturnValue(undefined);
 
-    await callGateway({ method: "health", scopes: ["operator.read"] });
+    await callGatewayScoped({ method: "health", scopes: ["operator.read"] });
     expect(lastClientOptions?.scopes).toEqual(["operator.read"]);
 
-    await callGateway({ method: "health", scopes: [] });
+    await callGatewayScoped({ method: "health", scopes: [] });
     expect(lastClientOptions?.scopes).toEqual([]);
   });
 });

src/gateway/call.ts

@@ -16,11 +16,15 @@ import {
   type GatewayClientName,
 } from "../utils/message-channel.js";
 import { GatewayClient } from "./client.js";
-import type { OperatorScope } from "./method-scopes.js";
+import {
+  CLI_DEFAULT_OPERATOR_SCOPES,
+  resolveLeastPrivilegeOperatorScopesForMethod,
+  type OperatorScope,
+} from "./method-scopes.js";
 import { isSecureWebSocketUrl, pickPrimaryLanIPv4 } from "./net.js";
 import { PROTOCOL_VERSION } from "./protocol/index.js";
 
-export type CallGatewayOptions = {
+type CallGatewayBaseOptions = {
   url?: string;
   token?: string;
   password?: string;
@@ -38,7 +42,6 @@ export type CallGatewayOptions = {
   instanceId?: string;
   minProtocol?: number;
   maxProtocol?: number;
-  scopes?: OperatorScope[];
   /**
    * Overrides the config path shown in connection error details.
    * Does not affect config loading; callers still control auth via opts.token/password/env/config.
@@ -46,6 +49,18 @@ export type CallGatewayOptions = {
   configPath?: string;
 };
 
+export type CallGatewayScopedOptions = CallGatewayBaseOptions & {
+  scopes: OperatorScope[];
+};
+
+export type CallGatewayCliOptions = CallGatewayBaseOptions & {
+  scopes?: OperatorScope[];
+};
+
+export type CallGatewayOptions = CallGatewayBaseOptions & {
+  scopes?: OperatorScope[];
+};
+
 export type GatewayConnectionDetails = {
   url: string;
   urlSource: string;
@@ -171,8 +186,9 @@ export function buildGatewayConnectionDetails(
   };
 }
 
-export async function callGateway<T = Record<string, unknown>>(
-  opts: CallGatewayOptions,
+async function callGatewayWithScopes<T = Record<string, unknown>>(
+  opts: CallGatewayBaseOptions,
+  scopes: OperatorScope[],
 ): Promise<T> {
   const timeoutMs =
     typeof opts.timeoutMs === "number" && Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : 10_000;
@@ -259,9 +275,6 @@ export async function callGateway<T = Record<string, unknown>>(
   };
   const formatTimeoutError = () =>
     `gateway timeout after ${timeoutMs}ms\n${connectionDetails.message}`;
-  const scopes = Array.isArray(opts.scopes)
-    ? opts.scopes
-    : ["operator.admin", "operator.approvals", "operator.pairing"];
   return await new Promise<T>((resolve, reject) => {
     let settled = false;
     let ignoreClose = false;
@@ -328,6 +341,44 @@ export async function callGateway<T = Record<string, unknown>>(
   });
 }
 
+export async function callGatewayScoped<T = Record<string, unknown>>(
+  opts: CallGatewayScopedOptions,
+): Promise<T> {
+  return await callGatewayWithScopes(opts, opts.scopes);
+}
+
+export async function callGatewayCli<T = Record<string, unknown>>(
+  opts: CallGatewayCliOptions,
+): Promise<T> {
+  const scopes = Array.isArray(opts.scopes) ? opts.scopes : CLI_DEFAULT_OPERATOR_SCOPES;
+  return await callGatewayWithScopes(opts, scopes);
+}
+
+export async function callGatewayLeastPrivilege<T = Record<string, unknown>>(
+  opts: CallGatewayBaseOptions,
+): Promise<T> {
+  const scopes = resolveLeastPrivilegeOperatorScopesForMethod(opts.method);
+  return await callGatewayWithScopes(opts, scopes);
+}
+
+export async function callGateway<T = Record<string, unknown>>(
+  opts: CallGatewayOptions,
+): Promise<T> {
+  if (Array.isArray(opts.scopes)) {
+    return await callGatewayWithScopes(opts, opts.scopes);
+  }
+  const callerMode = opts.mode ?? GATEWAY_CLIENT_MODES.BACKEND;
+  const callerName = opts.clientName ?? GATEWAY_CLIENT_NAMES.GATEWAY_CLIENT;
+  if (callerMode === GATEWAY_CLIENT_MODES.CLI || callerName === GATEWAY_CLIENT_NAMES.CLI) {
+    return await callGatewayCli(opts);
+  }
+  return await callGatewayLeastPrivilege({
+    ...opts,
+    mode: callerMode,
+    clientName: callerName,
+  });
+}
+
 export function randomIdempotencyKey() {
   return randomUUID();
 }

src/gateway/method-scopes.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import {
+  authorizeOperatorScopesForMethod,
+  resolveLeastPrivilegeOperatorScopesForMethod,
+} from "./method-scopes.js";
+
+describe("method scope resolution", () => {
+  it("classifies sessions.resolve as read and poll as write", () => {
+    expect(resolveLeastPrivilegeOperatorScopesForMethod("sessions.resolve")).toEqual([
+      "operator.read",
+    ]);
+    expect(resolveLeastPrivilegeOperatorScopesForMethod("poll")).toEqual(["operator.write"]);
+  });
+
+  it("returns empty scopes for unknown methods", () => {
+    expect(resolveLeastPrivilegeOperatorScopesForMethod("totally.unknown.method")).toEqual([]);
+  });
+});
+
+describe("operator scope authorization", () => {
+  it("allows read methods with operator.read or operator.write", () => {
+    expect(authorizeOperatorScopesForMethod("health", ["operator.read"])).toEqual({
+      allowed: true,
+    });
+    expect(authorizeOperatorScopesForMethod("health", ["operator.write"])).toEqual({
+      allowed: true,
+    });
+  });
+
+  it("requires operator.write for write methods", () => {
+    expect(authorizeOperatorScopesForMethod("send", ["operator.read"])).toEqual({
+      allowed: false,
+      missingScope: "operator.write",
+    });
+  });
+
+  it("requires approvals scope for approval methods", () => {
+    expect(authorizeOperatorScopesForMethod("exec.approval.resolve", ["operator.write"])).toEqual({
+      allowed: false,
+      missingScope: "operator.approvals",
+    });
+  });
+
+  it("requires admin for unknown methods", () => {
+    expect(authorizeOperatorScopesForMethod("unknown.method", ["operator.read"])).toEqual({
+      allowed: false,
+      missingScope: "operator.admin",
+    });
+  });
+});

src/gateway/method-scopes.ts

@@ -11,6 +11,12 @@ export type OperatorScope =
   | typeof APPROVALS_SCOPE
   | typeof PAIRING_SCOPE;
 
+export const CLI_DEFAULT_OPERATOR_SCOPES: OperatorScope[] = [
+  ADMIN_SCOPE,
+  APPROVALS_SCOPE,
+  PAIRING_SCOPE,
+];
+
 const APPROVAL_METHODS = new Set([
   "exec.approval.request",
   "exec.approval.waitDecision",
@@ -52,6 +58,7 @@ const READ_METHODS = new Set([
   "voicewake.get",
   "sessions.list",
   "sessions.preview",
+  "sessions.resolve",
   "cron.list",
   "cron.status",
   "cron.runs",
@@ -66,6 +73,7 @@ const READ_METHODS = new Set([
 
 const WRITE_METHODS = new Set([
   "send",
+  "poll",
   "agent",
   "agent.wait",
   "wake",
@@ -133,22 +141,50 @@ export function isAdminOnlyMethod(method: string): boolean {
   return ADMIN_METHODS.has(method);
 }
 
-export function resolveLeastPrivilegeOperatorScopesForMethod(method: string): OperatorScope[] {
+export function resolveRequiredOperatorScopeForMethod(method: string): OperatorScope | undefined {
   if (isApprovalMethod(method)) {
-    return [APPROVALS_SCOPE];
+    return APPROVALS_SCOPE;
   }
   if (isPairingMethod(method)) {
-    return [PAIRING_SCOPE];
+    return PAIRING_SCOPE;
   }
   if (isReadMethod(method)) {
-    return [READ_SCOPE];
+    return READ_SCOPE;
   }
   if (isWriteMethod(method)) {
-    return [WRITE_SCOPE];
+    return WRITE_SCOPE;
   }
   if (isAdminOnlyMethod(method)) {
-    return [ADMIN_SCOPE];
+    return ADMIN_SCOPE;
+  }
+  return undefined;
+}
+
+export function resolveLeastPrivilegeOperatorScopesForMethod(method: string): OperatorScope[] {
+  const requiredScope = resolveRequiredOperatorScopeForMethod(method);
+  if (requiredScope) {
+    return [requiredScope];
   }
   // Default-deny for unclassified methods.
   return [];
 }
+
+export function authorizeOperatorScopesForMethod(
+  method: string,
+  scopes: readonly string[],
+): { allowed: true } | { allowed: false; missingScope: OperatorScope } {
+  if (scopes.includes(ADMIN_SCOPE)) {
+    return { allowed: true };
+  }
+  const requiredScope = resolveRequiredOperatorScopeForMethod(method) ?? ADMIN_SCOPE;
+  if (requiredScope === READ_SCOPE) {
+    if (scopes.includes(READ_SCOPE) || scopes.includes(WRITE_SCOPE)) {
+      return { allowed: true };
+    }
+    return { allowed: false, missingScope: READ_SCOPE };
+  }
+  if (scopes.includes(requiredScope)) {
+    return { allowed: true };
+  }
+  return { allowed: false, missingScope: requiredScope };
+}

src/gateway/server-methods.ts

@@ -2,16 +2,8 @@ import { formatControlPlaneActor, resolveControlPlaneActor } from "./control-pla
 import { consumeControlPlaneWriteBudget } from "./control-plane-rate-limit.js";
 import {
   ADMIN_SCOPE,
-  APPROVALS_SCOPE,
-  isAdminOnlyMethod,
-  isApprovalMethod,
+  authorizeOperatorScopesForMethod,
   isNodeRoleMethod,
-  isPairingMethod,
-  isReadMethod,
-  isWriteMethod,
-  PAIRING_SCOPE,
-  READ_SCOPE,
-  WRITE_SCOPE,
 } from "./method-scopes.js";
 import { ErrorCodes, errorShape } from "./protocol/index.js";
 import { agentHandlers } from "./server-methods/agent.js";
@@ -64,34 +56,11 @@ function authorizeGatewayMethod(method: string, client: GatewayRequestOptions["c
   if (scopes.includes(ADMIN_SCOPE)) {
     return null;
   }
-  if (isApprovalMethod(method) && !scopes.includes(APPROVALS_SCOPE)) {
-    return errorShape(ErrorCodes.INVALID_REQUEST, "missing scope: operator.approvals");
+  const scopeAuth = authorizeOperatorScopesForMethod(method, scopes);
+  if (!scopeAuth.allowed) {
+    return errorShape(ErrorCodes.INVALID_REQUEST, `missing scope: ${scopeAuth.missingScope}`);
   }
-  if (isPairingMethod(method) && !scopes.includes(PAIRING_SCOPE)) {
-    return errorShape(ErrorCodes.INVALID_REQUEST, "missing scope: operator.pairing");
-  }
-  if (isReadMethod(method) && !(scopes.includes(READ_SCOPE) || scopes.includes(WRITE_SCOPE))) {
-    return errorShape(ErrorCodes.INVALID_REQUEST, "missing scope: operator.read");
-  }
-  if (isWriteMethod(method) && !scopes.includes(WRITE_SCOPE)) {
-    return errorShape(ErrorCodes.INVALID_REQUEST, "missing scope: operator.write");
-  }
-  if (isApprovalMethod(method)) {
-    return null;
-  }
-  if (isPairingMethod(method)) {
-    return null;
-  }
-  if (isReadMethod(method)) {
-    return null;
-  }
-  if (isWriteMethod(method)) {
-    return null;
-  }
-  if (isAdminOnlyMethod(method)) {
-    return errorShape(ErrorCodes.INVALID_REQUEST, "missing scope: operator.admin");
-  }
-  return errorShape(ErrorCodes.INVALID_REQUEST, "missing scope: operator.admin");
+  return null;
 }
 
 export const coreGatewayHandlers: GatewayRequestHandlers = {