github/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-05-07 22:51:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix: harden agent gateway authorization scopes

Browse Source
This commit is contained in:
Peter Steinberger
2026-02-19 14:37:56 +01:00
parent 165c18819e
commit a40c10d3e2
19 changed files with 319 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
src/gateway/call.test.ts
View File

@@ -10,6 +10,7 @@ let lastClientOptions: {
url?: string;
token?: string;
password?: string;
scopes?: string[];
onHelloOk?: () => void | Promise<void>;
onClose?: (code: number, reason: string) => void;
} | null = null;
@@ -54,6 +55,7 @@ vi.mock("./client.js", () => ({
url?: string;
token?: string;
password?: string;
scopes?: string[];
onHelloOk?: () => void | Promise<void>;
onClose?: (code: number, reason: string) => void;
}) {
@@ -195,6 +197,32 @@ describe("callGateway url resolution", () => {
expect(lastClientOptions?.url).toBe("wss://override.example/ws");
expect(lastClientOptions?.token).toBe("explicit-token");
});
it("keeps legacy admin scopes when call scopes are omitted", async () => {
loadConfig.mockReturnValue({ gateway: { mode: "local", bind: "loopback" } });
resolveGatewayPort.mockReturnValue(18789);
pickPrimaryTailnetIPv4.mockReturnValue(undefined);
await callGateway({ method: "health" });
expect(lastClientOptions?.scopes).toEqual([
"operator.admin",
"operator.approvals",
"operator.pairing",
]);
});
it("passes explicit scopes through, including empty arrays", async () => {
loadConfig.mockReturnValue({ gateway: { mode: "local", bind: "loopback" } });
resolveGatewayPort.mockReturnValue(18789);
pickPrimaryTailnetIPv4.mockReturnValue(undefined);
await callGateway({ method: "health", scopes: ["operator.read"] });
expect(lastClientOptions?.scopes).toEqual(["operator.read"]);
await callGateway({ method: "health", scopes: [] });
expect(lastClientOptions?.scopes).toEqual([]);
});
});
describe("buildGatewayConnectionDetails", () => {

7
src/gateway/call.ts
View File

@@ -16,6 +16,7 @@ import {
type GatewayClientName,
} from "../utils/message-channel.js";
import { GatewayClient } from "./client.js";
import type { OperatorScope } from "./method-scopes.js";
import { isSecureWebSocketUrl, pickPrimaryLanIPv4 } from "./net.js";
import { PROTOCOL_VERSION } from "./protocol/index.js";
@@ -37,6 +38,7 @@ 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.
@@ -257,6 +259,9 @@ 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;
@@ -285,7 +290,7 @@ export async function callGateway<T = Record<string, unknown>>(
platform: opts.platform,
mode: opts.mode ?? GATEWAY_CLIENT_MODES.CLI,
role: "operator",
scopes: ["operator.admin", "operator.approvals", "operator.pairing"],
scopes,
deviceIdentity: loadOrCreateDeviceIdentity(),
minProtocol: opts.minProtocol ?? PROTOCOL_VERSION,
maxProtocol: opts.maxProtocol ?? PROTOCOL_VERSION,

154
src/gateway/method-scopes.ts Normal file
View File

@@ -0,0 +1,154 @@
export const ADMIN_SCOPE = "operator.admin" as const;
export const READ_SCOPE = "operator.read" as const;
export const WRITE_SCOPE = "operator.write" as const;
export const APPROVALS_SCOPE = "operator.approvals" as const;
export const PAIRING_SCOPE = "operator.pairing" as const;
export type OperatorScope =
| typeof ADMIN_SCOPE
| typeof READ_SCOPE
| typeof WRITE_SCOPE
| typeof APPROVALS_SCOPE
| typeof PAIRING_SCOPE;
const APPROVAL_METHODS = new Set([
"exec.approval.request",
"exec.approval.waitDecision",
"exec.approval.resolve",
]);
const NODE_ROLE_METHODS = new Set(["node.invoke.result", "node.event", "skills.bins"]);
const PAIRING_METHODS = new Set([
"node.pair.request",
"node.pair.list",
"node.pair.approve",
"node.pair.reject",
"node.pair.verify",
"device.pair.list",
"device.pair.approve",
"device.pair.reject",
"device.pair.remove",
"device.token.rotate",
"device.token.revoke",
"node.rename",
]);
const ADMIN_METHOD_PREFIXES = ["exec.approvals."];
const READ_METHODS = new Set([
"health",
"logs.tail",
"channels.status",
"status",
"usage.status",
"usage.cost",
"tts.status",
"tts.providers",
"models.list",
"agents.list",
"agent.identity.get",
"skills.status",
"voicewake.get",
"sessions.list",
"sessions.preview",
"cron.list",
"cron.status",
"cron.runs",
"system-presence",
"last-heartbeat",
"node.list",
"node.describe",
"chat.history",
"config.get",
"talk.config",
]);
const WRITE_METHODS = new Set([
"send",
"agent",
"agent.wait",
"wake",
"talk.mode",
"tts.enable",
"tts.disable",
"tts.convert",
"tts.setProvider",
"voicewake.set",
"node.invoke",
"chat.send",
"chat.abort",
"browser.request",
"push.test",
]);
const ADMIN_METHODS = new Set([
"channels.logout",
"agents.create",
"agents.update",
"agents.delete",
"skills.install",
"skills.update",
"cron.add",
"cron.update",
"cron.remove",
"cron.run",
"sessions.patch",
"sessions.reset",
"sessions.delete",
"sessions.compact",
]);
export function isApprovalMethod(method: string): boolean {
return APPROVAL_METHODS.has(method);
}
export function isPairingMethod(method: string): boolean {
return PAIRING_METHODS.has(method);
}
export function isReadMethod(method: string): boolean {
return READ_METHODS.has(method);
}
export function isWriteMethod(method: string): boolean {
return WRITE_METHODS.has(method);
}
export function isNodeRoleMethod(method: string): boolean {
return NODE_ROLE_METHODS.has(method);
}
export function isAdminOnlyMethod(method: string): boolean {
if (ADMIN_METHOD_PREFIXES.some((prefix) => method.startsWith(prefix))) {
return true;
}
if (
method.startsWith("config.") ||
method.startsWith("wizard.") ||
method.startsWith("update.")
) {
return true;
}
return ADMIN_METHODS.has(method);
}
export function resolveLeastPrivilegeOperatorScopesForMethod(method: string): OperatorScope[] {
if (isApprovalMethod(method)) {
return [APPROVALS_SCOPE];
}
if (isPairingMethod(method)) {
return [PAIRING_SCOPE];
}
if (isReadMethod(method)) {
return [READ_SCOPE];
}
if (isWriteMethod(method)) {
return [WRITE_SCOPE];
}
if (isAdminOnlyMethod(method)) {
return [ADMIN_SCOPE];
}
// Default-deny for unclassified methods.
return [];
}

126
src/gateway/server-methods.ts
View File

@@ -1,5 +1,18 @@
import { formatControlPlaneActor, resolveControlPlaneActor } from "./control-plane-audit.js";
import { consumeControlPlaneWriteBudget } from "./control-plane-rate-limit.js";
import {
ADMIN_SCOPE,
APPROVALS_SCOPE,
isAdminOnlyMethod,
isApprovalMethod,
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";
import { agentsHandlers } from "./server-methods/agents.js";
@@ -29,86 +42,14 @@ import { voicewakeHandlers } from "./server-methods/voicewake.js";
import { webHandlers } from "./server-methods/web.js";
import { wizardHandlers } from "./server-methods/wizard.js";
const ADMIN_SCOPE = "operator.admin";
const READ_SCOPE = "operator.read";
const WRITE_SCOPE = "operator.write";
const APPROVALS_SCOPE = "operator.approvals";
const PAIRING_SCOPE = "operator.pairing";
const APPROVAL_METHODS = new Set([
"exec.approval.request",
"exec.approval.waitDecision",
"exec.approval.resolve",
]);
const NODE_ROLE_METHODS = new Set(["node.invoke.result", "node.event", "skills.bins"]);
const PAIRING_METHODS = new Set([
"node.pair.request",
"node.pair.list",
"node.pair.approve",
"node.pair.reject",
"node.pair.verify",
"device.pair.list",
"device.pair.approve",
"device.pair.reject",
"device.pair.remove",
"device.token.rotate",
"device.token.revoke",
"node.rename",
]);
const ADMIN_METHOD_PREFIXES = ["exec.approvals."];
const READ_METHODS = new Set([
"health",
"logs.tail",
"channels.status",
"status",
"usage.status",
"usage.cost",
"tts.status",
"tts.providers",
"models.list",
"agents.list",
"agent.identity.get",
"skills.status",
"voicewake.get",
"sessions.list",
"sessions.preview",
"cron.list",
"cron.status",
"cron.runs",
"system-presence",
"last-heartbeat",
"node.list",
"node.describe",
"chat.history",
"config.get",
"talk.config",
]);
const WRITE_METHODS = new Set([
"send",
"agent",
"agent.wait",
"wake",
"talk.mode",
"tts.enable",
"tts.disable",
"tts.convert",
"tts.setProvider",
"voicewake.set",
"node.invoke",
"chat.send",
"chat.abort",
"browser.request",
"push.test",
]);
const CONTROL_PLANE_WRITE_METHODS = new Set(["config.apply", "config.patch", "update.run"]);
function authorizeGatewayMethod(method: string, client: GatewayRequestOptions["client"]) {
if (!client?.connect) {
return null;
}
const role = client.connect.role ?? "operator";
const scopes = client.connect.scopes ?? [];
if (NODE_ROLE_METHODS.has(method)) {
if (isNodeRoleMethod(method)) {
if (role === "node") {
return null;
}
@@ -123,52 +64,31 @@ function authorizeGatewayMethod(method: string, client: GatewayRequestOptions["c
if (scopes.includes(ADMIN_SCOPE)) {
return null;
}
if (APPROVAL_METHODS.has(method) && !scopes.includes(APPROVALS_SCOPE)) {
if (isApprovalMethod(method) && !scopes.includes(APPROVALS_SCOPE)) {
return errorShape(ErrorCodes.INVALID_REQUEST, "missing scope: operator.approvals");
}
if (PAIRING_METHODS.has(method) && !scopes.includes(PAIRING_SCOPE)) {
if (isPairingMethod(method) && !scopes.includes(PAIRING_SCOPE)) {
return errorShape(ErrorCodes.INVALID_REQUEST, "missing scope: operator.pairing");
}
if (READ_METHODS.has(method) && !(scopes.includes(READ_SCOPE) || scopes.includes(WRITE_SCOPE))) {
if (isReadMethod(method) && !(scopes.includes(READ_SCOPE) || scopes.includes(WRITE_SCOPE))) {
return errorShape(ErrorCodes.INVALID_REQUEST, "missing scope: operator.read");
}
if (WRITE_METHODS.has(method) && !scopes.includes(WRITE_SCOPE)) {
if (isWriteMethod(method) && !scopes.includes(WRITE_SCOPE)) {
return errorShape(ErrorCodes.INVALID_REQUEST, "missing scope: operator.write");
}
if (APPROVAL_METHODS.has(method)) {
if (isApprovalMethod(method)) {
return null;
}
if (PAIRING_METHODS.has(method)) {
if (isPairingMethod(method)) {
return null;
}
if (READ_METHODS.has(method)) {
if (isReadMethod(method)) {
return null;
}
if (WRITE_METHODS.has(method)) {
if (isWriteMethod(method)) {
return null;
}
if (ADMIN_METHOD_PREFIXES.some((prefix) => method.startsWith(prefix))) {
return errorShape(ErrorCodes.INVALID_REQUEST, "missing scope: operator.admin");
}
if (
method.startsWith("config.") ||
method.startsWith("wizard.") ||
method.startsWith("update.") ||
method === "channels.logout" ||
method === "agents.create" ||
method === "agents.update" ||
method === "agents.delete" ||
method === "skills.install" ||
method === "skills.update" ||
method === "cron.add" ||
method === "cron.update" ||
method === "cron.remove" ||
method === "cron.run" ||
method === "sessions.patch" ||
method === "sessions.reset" ||
method === "sessions.delete" ||
method === "sessions.compact"
) {
if (isAdminOnlyMethod(method)) {
return errorShape(ErrorCodes.INVALID_REQUEST, "missing scope: operator.admin");
}
return errorShape(ErrorCodes.INVALID_REQUEST, "missing scope: operator.admin");