From 8fd53cdf867f2e6afaf40f5ac40a9b7d087333bc Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 4 Apr 2026 18:46:30 +0100 Subject: [PATCH] docs: refresh bootstrap scope role-prefix refs --- docs/channels/pairing.md | 3 +++ docs/gateway/protocol.md | 4 +++- docs/help/faq.md | 1 + 3 files changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/channels/pairing.md b/docs/channels/pairing.md index dadabb89248..dd768686d34 100644 --- a/docs/channels/pairing.md +++ b/docs/channels/pairing.md @@ -82,6 +82,9 @@ That bootstrap token carries the built-in pairing bootstrap profile: - primary handed-off `node` token stays `scopes: []` - any handed-off `operator` token stays bounded to the bootstrap allowlist: `operator.approvals`, `operator.read`, `operator.talk.secrets`, `operator.write` +- 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 Treat the setup code like a password while it is valid. diff --git a/docs/gateway/protocol.md b/docs/gateway/protocol.md index 2df0086b570..1f8dc0f1857 100644 --- a/docs/gateway/protocol.md +++ b/docs/gateway/protocol.md @@ -112,7 +112,9 @@ bounded role entries in `deviceTokens`: For the built-in node/operator bootstrap flow, the primary node token stays `scopes: []` and any handed-off operator token stays bounded to the bootstrap operator allowlist (`operator.approvals`, `operator.read`, -`operator.talk.secrets`, `operator.write`). +`operator.talk.secrets`, `operator.write`). Bootstrap scope checks stay +role-prefixed: operator entries only satisfy operator requests, and non-operator +roles still need scopes under their own role prefix. ### Node example diff --git a/docs/help/faq.md b/docs/help/faq.md index 0e20410b491..2df190a655d 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -2659,6 +2659,7 @@ Related: [/concepts/oauth](/concepts/oauth) (OAuth flows, token storage, multi-a - On `AUTH_TOKEN_MISMATCH`, trusted clients can attempt one bounded retry with a cached device token when the gateway returns retry hints (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`). - That cached-token retry now reuses the cached approved scopes stored with the device token. Explicit `deviceToken` / explicit `scopes` callers still keep their requested scope set instead of inheriting cached scopes. - Outside that retry path, connect auth precedence is explicit shared token/password first, then explicit `deviceToken`, then stored device token, then bootstrap token. + - Bootstrap token scope checks are role-prefixed. The built-in bootstrap operator allowlist only satisfies operator requests; node or other non-operator roles still need scopes under their own role prefix. Fix: