diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index e4d90149a..5d15e6dc9 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "f30dc0aeb4ce87ada1aef40042fda5729951a0bf", - "syncedAt": "2026-05-03T00:07:48.136Z" + "sha": "e8f13c625e3458e8d97fbc1441a23a8ed9e0a536", + "syncedAt": "2026-05-03T00:39:49.253Z" } diff --git a/docs/cli/devices.md b/docs/cli/devices.md index 31724f9b7..9942c80de 100644 --- a/docs/cli/devices.md +++ b/docs/cli/devices.md @@ -137,7 +137,9 @@ When you set `--url`, the CLI does not fall back to config or environment creden ## Notes - Token rotation returns a new token (sensitive). Treat it like a secret. -- These commands require `operator.pairing` (or `operator.admin`) scope. +- These commands require `operator.pairing` (or `operator.admin`) scope. Some + approvals also require the caller to hold the operator scopes that the target + device would mint or inherit; see [Operator scopes](/gateway/operator-scopes). - `gateway.nodes.pairing.autoApproveCidrs` is an opt-in Gateway policy for fresh node device pairing only; it does not change CLI approval authority. - Token rotation and revocation stay inside the approved pairing role set and diff --git a/docs/docs.json b/docs/docs.json index a393be9c0..b7e6dd074 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1519,6 +1519,7 @@ "pages": [ "gateway/security/index", "gateway/security/audit-checks", + "gateway/operator-scopes", "gateway/sandboxing", "gateway/openshell", "gateway/sandbox-vs-tool-policy-vs-elevated" @@ -3006,6 +3007,7 @@ "pages": [ "zh-TW/gateway/security/index", "zh-TW/gateway/security/audit-checks", + "zh-TW/gateway/operator-scopes", "zh-TW/gateway/sandboxing", "zh-TW/gateway/openshell", "zh-TW/gateway/sandbox-vs-tool-policy-vs-elevated" @@ -3878,6 +3880,7 @@ "pages": [ "ja-JP/gateway/security/index", "ja-JP/gateway/security/audit-checks", + "ja-JP/gateway/operator-scopes", "ja-JP/gateway/sandboxing", "ja-JP/gateway/openshell", "ja-JP/gateway/sandbox-vs-tool-policy-vs-elevated" @@ -4750,6 +4753,7 @@ "pages": [ "es/gateway/security/index", "es/gateway/security/audit-checks", + "es/gateway/operator-scopes", "es/gateway/sandboxing", "es/gateway/openshell", "es/gateway/sandbox-vs-tool-policy-vs-elevated" @@ -5622,6 +5626,7 @@ "pages": [ "pt-BR/gateway/security/index", "pt-BR/gateway/security/audit-checks", + "pt-BR/gateway/operator-scopes", "pt-BR/gateway/sandboxing", "pt-BR/gateway/openshell", "pt-BR/gateway/sandbox-vs-tool-policy-vs-elevated" @@ -6494,6 +6499,7 @@ "pages": [ "ko/gateway/security/index", "ko/gateway/security/audit-checks", + "ko/gateway/operator-scopes", "ko/gateway/sandboxing", "ko/gateway/openshell", "ko/gateway/sandbox-vs-tool-policy-vs-elevated" @@ -7366,6 +7372,7 @@ "pages": [ "de/gateway/security/index", "de/gateway/security/audit-checks", + "de/gateway/operator-scopes", "de/gateway/sandboxing", "de/gateway/openshell", "de/gateway/sandbox-vs-tool-policy-vs-elevated" @@ -8238,6 +8245,7 @@ "pages": [ "fr/gateway/security/index", "fr/gateway/security/audit-checks", + "fr/gateway/operator-scopes", "fr/gateway/sandboxing", "fr/gateway/openshell", "fr/gateway/sandbox-vs-tool-policy-vs-elevated" @@ -9110,6 +9118,7 @@ "pages": [ "ar/gateway/security/index", "ar/gateway/security/audit-checks", + "ar/gateway/operator-scopes", "ar/gateway/sandboxing", "ar/gateway/openshell", "ar/gateway/sandbox-vs-tool-policy-vs-elevated" @@ -9982,6 +9991,7 @@ "pages": [ "it/gateway/security/index", "it/gateway/security/audit-checks", + "it/gateway/operator-scopes", "it/gateway/sandboxing", "it/gateway/openshell", "it/gateway/sandbox-vs-tool-policy-vs-elevated" @@ -10854,6 +10864,7 @@ "pages": [ "vi/gateway/security/index", "vi/gateway/security/audit-checks", + "vi/gateway/operator-scopes", "vi/gateway/sandboxing", "vi/gateway/openshell", "vi/gateway/sandbox-vs-tool-policy-vs-elevated" @@ -11726,6 +11737,7 @@ "pages": [ "nl/gateway/security/index", "nl/gateway/security/audit-checks", + "nl/gateway/operator-scopes", "nl/gateway/sandboxing", "nl/gateway/openshell", "nl/gateway/sandbox-vs-tool-policy-vs-elevated" @@ -12598,6 +12610,7 @@ "pages": [ "tr/gateway/security/index", "tr/gateway/security/audit-checks", + "tr/gateway/operator-scopes", "tr/gateway/sandboxing", "tr/gateway/openshell", "tr/gateway/sandbox-vs-tool-policy-vs-elevated" @@ -13470,6 +13483,7 @@ "pages": [ "uk/gateway/security/index", "uk/gateway/security/audit-checks", + "uk/gateway/operator-scopes", "uk/gateway/sandboxing", "uk/gateway/openshell", "uk/gateway/sandbox-vs-tool-policy-vs-elevated" @@ -14342,6 +14356,7 @@ "pages": [ "id/gateway/security/index", "id/gateway/security/audit-checks", + "id/gateway/operator-scopes", "id/gateway/sandboxing", "id/gateway/openshell", "id/gateway/sandbox-vs-tool-policy-vs-elevated" @@ -15214,6 +15229,7 @@ "pages": [ "pl/gateway/security/index", "pl/gateway/security/audit-checks", + "pl/gateway/operator-scopes", "pl/gateway/sandboxing", "pl/gateway/openshell", "pl/gateway/sandbox-vs-tool-policy-vs-elevated" diff --git a/docs/gateway/operator-scopes.md b/docs/gateway/operator-scopes.md new file mode 100644 index 000000000..83c1a08f4 --- /dev/null +++ b/docs/gateway/operator-scopes.md @@ -0,0 +1,110 @@ +--- +summary: "Operator roles, scopes, and approval-time checks for Gateway clients" +read_when: + - Debugging missing operator scope errors + - Reviewing device or node pairing approvals + - Adding or classifying Gateway RPC methods +title: "Operator scopes" +--- + +Operator scopes define what a Gateway client may do after it authenticates. +They are a control-plane guardrail inside one trusted Gateway operator domain, +not hostile multi-tenant isolation. If you need strong separation between +people, teams, or machines, run separate Gateways under separate OS users or +hosts. + +Related: [Security](/gateway/security), [Gateway protocol](/gateway/protocol), +[Gateway pairing](/gateway/pairing), [Devices CLI](/cli/devices). + +## Roles + +Gateway WebSocket clients connect with one role: + +- `operator`: control-plane clients such as CLI, Control UI, automation, and + trusted helper processes. +- `node`: capability hosts such as macOS, iOS, Android, or headless nodes that + expose commands through `node.invoke`. + +Operator RPC methods require the `operator` role. Node-originated methods +require the `node` role. + +## Scope levels + +| Scope | Meaning | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `operator.read` | Read-only status, lists, catalog, logs, session reads, and other non-mutating control-plane calls. | +| `operator.write` | Normal mutating operator actions such as sending messages, invoking tools, updating talk/voice settings, and node command relay. Also satisfies `operator.read`. | +| `operator.admin` | Administrative control-plane access. Satisfies every `operator.*` scope. Required for config mutation, updates, native hooks, sensitive reserved namespaces, and high-risk approvals. | +| `operator.pairing` | Device and node pairing management, including listing, approving, rejecting, removing, rotating, and revoking pairing records or device tokens. | +| `operator.approvals` | Exec and plugin approval APIs. | +| `operator.talk.secrets` | Reading Talk configuration with secrets included. | + +Unknown future `operator.*` scopes require an exact match unless the caller has +`operator.admin`. + +## Method scope is only the first gate + +Each Gateway RPC has a least-privilege method scope. That method scope decides +whether the request can reach the handler. Some handlers then apply stricter +approval-time checks based on the concrete thing being approved or mutated. + +Examples: + +- `device.pair.approve` is reachable with `operator.pairing`, but approving an + operator device can only mint or preserve scopes the caller already holds. +- `node.pair.approve` is reachable with `operator.pairing`, then derives extra + approval scopes from the pending node command list. +- `chat.send` is normally a write-scoped method, but persistent `/config set` + and `/config unset` require `operator.admin` at command level. + +This lets lower-scope operators perform low-risk pairing actions without making +all pairing approval admin-only. + +## Device pairing approvals + +Device pairing records are the durable source of approved roles and scopes. +Already paired devices do not get broader access silently: reconnects that ask +for a broader role or broader scopes create a new pending upgrade request. + +When approving a device request: + +- A request with no operator role does not need operator token scope approval. +- A request for `operator.read`, `operator.write`, `operator.approvals`, + `operator.pairing`, or `operator.talk.secrets` requires the caller to hold + those scopes, or `operator.admin`. +- A request for `operator.admin` requires `operator.admin`. +- A repair request with no explicit scopes can inherit the existing operator + token scopes. If that existing token is admin-scoped, approval still requires + `operator.admin`. + +For paired-device token sessions, management is self-scoped unless the caller +also has `operator.admin`: non-admin callers can rotate, revoke, or remove only +their own device entry. + +## Node pairing approvals + +Legacy `node.pair.*` uses a separate Gateway-owned node pairing store. WS nodes +use device pairing with `role: node`, but the same approval-level vocabulary +applies. + +`node.pair.approve` uses the pending request command list to derive additional +required scopes: + +- Commandless request: `operator.pairing` +- Non-exec node commands: `operator.pairing` + `operator.write` +- `system.run`, `system.run.prepare`, or `system.which`: + `operator.pairing` + `operator.admin` + +Node pairing establishes identity and trust. It does not replace the node's +own `system.run` exec approval policy. + +## Shared-secret auth + +Shared gateway token/password auth is treated as trusted operator access for +that Gateway. OpenAI-compatible HTTP surfaces and `/tools/invoke` restore the +normal full operator default scope set for shared-secret bearer auth, even if a +caller sends narrower declared scopes. + +Identity-bearing modes, such as trusted proxy auth or private-ingress `none`, +can still honor explicit declared scopes. Use separate Gateways for real trust +boundary separation. diff --git a/docs/gateway/pairing.md b/docs/gateway/pairing.md index 86d84bc2b..89bec8918 100644 --- a/docs/gateway/pairing.md +++ b/docs/gateway/pairing.md @@ -69,6 +69,8 @@ Notes: metadata and the latest allowlisted declared command snapshot for operator visibility. - Approval **always** generates a fresh token; no token is ever returned from `node.pair.request`. +- Operator scope levels and approval-time checks are summarized in + [Operator scopes](/gateway/operator-scopes). - Requests may include `silent: true` as a hint for auto-approval flows. - `node.pair.approve` uses the pending request's declared commands to enforce extra approval scopes: diff --git a/docs/gateway/protocol.md b/docs/gateway/protocol.md index 0b467135f..b15ee802b 100644 --- a/docs/gateway/protocol.md +++ b/docs/gateway/protocol.md @@ -211,6 +211,9 @@ Side-effecting methods require **idempotency keys** (see schema). ## Roles + scopes +For the full operator scope model, approval-time checks, and shared-secret +semantics, see [Operator scopes](/gateway/operator-scopes). + ### Roles - `operator` = control plane client (CLI/UI/automation). diff --git a/docs/gateway/security/index.md b/docs/gateway/security/index.md index 482818a93..d46d32ee4 100644 --- a/docs/gateway/security/index.md +++ b/docs/gateway/security/index.md @@ -92,6 +92,8 @@ Treat Gateway and node as one operator trust domain, with different roles: - **Gateway** is the control plane and policy surface (`gateway.auth`, tool policy, routing). - **Node** is remote execution surface paired to that Gateway (commands, device actions, host-local capabilities). - A caller authenticated to the Gateway is trusted at Gateway scope. After pairing, node actions are trusted operator actions on that node. +- Operator scope levels and approval-time checks are summarized in + [Operator scopes](/gateway/operator-scopes). - Direct loopback backend clients authenticated with the shared gateway token/password can make internal control-plane RPCs without presenting a user device identity. This is not a remote or browser pairing bypass: network