From e76bf80ce0a0fbcfac7fc34b4579bcef2c905be5 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-sync[bot]" Date: Sun, 26 Apr 2026 06:30:50 +0000 Subject: [PATCH] chore(sync): mirror docs from openclaw/openclaw@8bbb143ab87e0a45f9d3f986768d75168750b672 --- .openclaw-sync/source.json | 4 ++-- docs/channels/pairing.md | 2 ++ docs/cli/devices.md | 17 +++++++++++------ docs/gateway/protocol.md | 16 ++++++++-------- 4 files changed, 23 insertions(+), 16 deletions(-) diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index fa7245703..b0b73395a 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "8368026986a9309c92e7367b9b597d0d5c3971e5", - "syncedAt": "2026-04-26T06:25:03.104Z" + "sha": "8bbb143ab87e0a45f9d3f986768d75168750b672", + "syncedAt": "2026-04-26T06:29:25.319Z" } diff --git a/docs/channels/pairing.md b/docs/channels/pairing.md index 90e5b14f8..6ad636f77 100644 --- a/docs/channels/pairing.md +++ b/docs/channels/pairing.md @@ -83,6 +83,8 @@ That bootstrap token carries the built-in pairing bootstrap profile: - bootstrap scope checks are role-prefixed, not one flat scope pool: operator scope entries only satisfy operator requests, and non-operator roles must still request scopes under their own role prefix +- later token rotation/revocation remains bounded by both the device's approved + role contract and the caller session's operator scopes Treat the setup code like a password while it is valid. diff --git a/docs/cli/devices.md b/docs/cli/devices.md index 03c90af17..bd26cf400 100644 --- a/docs/cli/devices.md +++ b/docs/cli/devices.md @@ -95,9 +95,9 @@ If you omit `--scope`, later reconnects with the stored rotated token reuse that token's cached approved scopes. If you pass explicit `--scope` values, those become the stored scope set for future cached-token reconnects. Non-admin paired-device callers can rotate only their **own** device token. -Also, any explicit `--scope` values must stay within the caller session's own -operator scopes; rotation cannot mint a broader operator token than the caller -already has. +The target token scope set must stay within the caller session's own operator +scopes; rotation cannot mint or preserve a broader operator token than the +caller already has. ``` openclaw devices rotate --device --role operator --scope operator.read --scope operator.write @@ -111,6 +111,8 @@ Revoke a device token for a specific role. Non-admin paired-device callers can revoke only their **own** device token. Revoking some other device's token requires `operator.admin`. +The target token scope set must also fit within the caller session's own +operator scopes; pairing-only callers cannot revoke admin/write operator tokens. ``` openclaw devices revoke --device --role node @@ -135,12 +137,15 @@ Pass `--token` or `--password` explicitly. Missing explicit credentials is an er - These commands require `operator.pairing` (or `operator.admin`) scope. - `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 stays inside the approved pairing role set and approved scope - baseline for that device. A stray cached token entry does not grant a new - rotate target. +- Token rotation and revocation stay inside the approved pairing role set and + approved scope baseline for that device. A stray cached token entry does not + grant a token-management target. - For paired-device token sessions, cross-device management is admin-only: `remove`, `rotate`, and `revoke` are self-only unless the caller has `operator.admin`. +- Token mutation is also caller-scope contained: a pairing-only session cannot + rotate or revoke a token that currently carries `operator.admin` or + `operator.write`. - `devices clear` is intentionally gated by `--yes`. - If pairing scope is unavailable on local loopback (and no explicit `--url` is passed), list/approve can use a local pairing fallback. - `devices approve` requires an explicit request ID before minting tokens; omitting `requestId` or passing `--latest` only previews the newest pending request. diff --git a/docs/gateway/protocol.md b/docs/gateway/protocol.md index 47a95f474..12276812e 100644 --- a/docs/gateway/protocol.md +++ b/docs/gateway/protocol.md @@ -360,8 +360,8 @@ enumeration of `src/gateway/server-methods/*.ts`. - `device.pair.list` returns pending and approved paired devices. - `device.pair.approve`, `device.pair.reject`, and `device.pair.remove` manage device-pairing records. - - `device.token.rotate` rotates a paired device token within its approved role and scope bounds. - - `device.token.revoke` revokes a paired device token. + - `device.token.rotate` rotates a paired device token within its approved role and caller scope bounds. + - `device.token.revoke` revokes a paired device token within its approved role and caller scope bounds. @@ -549,15 +549,15 @@ rather than the pre-handshake defaults. reused when the client is reusing the stored per-device token. - Device tokens can be rotated/revoked via `device.token.rotate` and `device.token.revoke` (requires `operator.pairing` scope). -- Token issuance/rotation stays bounded to the approved role set recorded in - that device's pairing entry; rotating a token cannot expand the device into a - role that pairing approval never granted. +- Token issuance, rotation, and revocation stay bounded to the approved role set + recorded in that device's pairing entry; token mutation cannot expand or + target a device role that pairing approval never granted. - For paired-device token sessions, device management is self-scoped unless the caller also has `operator.admin`: non-admin callers can remove/revoke/rotate only their **own** device entry. -- `device.token.rotate` also checks the requested operator scope set against the - caller's current session scopes. Non-admin callers cannot rotate a token into - a broader operator scope set than they already hold. +- `device.token.rotate` and `device.token.revoke` also check the target operator + token scope set against the caller's current session scopes. Non-admin callers + cannot rotate or revoke a broader operator token than they already hold. - Auth failures include `error.details.code` plus recovery hints: - `error.details.canRetryWithDeviceToken` (boolean) - `error.details.recommendedNextStep` (`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`)