Fix iOS operator bootstrap scope diagnostics by BunsDev · Pull Request #80189 · openclaw/openclaw

BunsDev · 2026-05-10T08:54:47Z

Summary

preserve full shared-token dashboard/native operator sessions, including operator.admin and operator.pairing
reuse cached device-token scopes for bootstrap handoff/trusted cached-token reconnects, so bootstrap-issued operator tokens do not request scopes they cannot carry
preserve explicit native scope requests such as openclaw-mac connect --scopes ... instead of replacing them with cached bootstrap scopes
propagate device-token scope mismatch failures as AUTH_SCOPE_MISMATCH instead of collapsing them into token mismatch diagnostics
update client recovery handling, docs, changelog, and targeted coverage for bootstrap-issued operator tokens

Security and stability

does not relax device-token verification; under-scoped tokens still fail and now report the correct recovery path
avoids broadening bootstrap handoff privilege by signing cached device-token reconnects with the token's cached approved scopes
preserves existing shared-token dashboard/native authority for admin and pairing RPCs instead of silently reducing those sessions
keeps scope mismatch out of shared-token repair flows so clients do not clear valid stored device tokens for an approval problem
security scan found no reportable findings; the only stability issue found was explicit Swift native scopes being swallowed by cached device-token scopes, now fixed and covered

Verification

swift test --package-path apps/macos --filter GatewayChannelConnectTests
swift test --package-path apps/shared/OpenClawKit --filter GatewayErrorsTests
pnpm test ui/src/ui/gateway.node.test.ts src/gateway/server.auth.control-ui.test.ts src/gateway/server/ws-connection/auth-context.test.ts src/gateway/protocol/connect-error-details.test.ts src/infra/device-pairing.test.ts src/gateway/server/ws-connection/auth-messages.test.ts src/gateway/server/ws-connection/handshake-auth-helpers.test.ts
pnpm exec oxfmt --check --threads=1 CHANGELOG.md ui/src/ui/gateway.ts ui/src/ui/gateway.node.test.ts src/gateway/protocol/connect-error-details.ts src/gateway/protocol/connect-error-details.test.ts src/gateway/server/ws-connection/auth-context.ts src/gateway/server/ws-connection/auth-context.test.ts src/gateway/server/ws-connection/auth-messages.ts src/gateway/server/ws-connection/auth-messages.test.ts src/gateway/server/ws-connection/handshake-auth-helpers.ts src/gateway/server/ws-connection/handshake-auth-helpers.test.ts src/infra/device-pairing.test.ts docs/cli/devices.md docs/gateway/protocol.md docs/gateway/troubleshooting.md docs/web/dashboard.md
git diff --check
rg -n "^(<<<<<<<|=======|>>>>>>>)" CHANGELOG.md apps src ui docs

Note: an earlier local command using src/gateway/server.auth.control-ui.suite.ts fanned out to the full gateway shard and hit unrelated session usage/reset failures. The scoped rerun uses the actual src/gateway/server.auth.control-ui.test.ts target and passes.

Issues and superseded PRs

Fixes #79292.

Related #78727, but does not close it; that issue is already closed as implemented by #79206.

Supersedes #79314, #79296, and #79295. Those attempts cover the server diagnostic slice only; this PR carries the fix through Control UI/native reconnect handling, Swift error UX, docs, and focused regression coverage.

clawsweeper · 2026-05-10T09:00:02Z

Codex review: needs maintainer review before merge.

Summary
The PR preserves full shared-token operator sessions, reuses cached/bootstrap device-token scopes for handoff reconnects, surfaces device-token scope mismatches as AUTH_SCOPE_MISMATCH, and updates related Swift, Control UI, docs, changelog, and regression coverage.

Reproducibility: yes. Source inspection gives a high-confidence path: current main returns scope-mismatch from verifyDeviceToken, then resolveConnectAuthDecision collapses that into device_token_mismatch before clients can recover correctly.

Real behavior proof
Not applicable: Not applicable because this is a member-authored, maintainer-labeled PR; the PR body’s targeted test commands are useful supplemental verification but the external contributor proof gate does not apply.

Next step before merge
No repair lane is needed; the remaining action is normal maintainer validation and landing for an open protected member PR.

Security
Cleared: The diff changes auth diagnostics and requested scope selection without adding dependencies, workflows, secret handling, or acceptance of under-scoped tokens.

Review details

Best possible solution:

Land this direction after normal maintainer validation, keeping shared-token operator sessions full while making bootstrap/cached device-token reconnects use their approved scope contract and surface scope mismatches as pairing approval guidance.

Do we have a high-confidence way to reproduce the issue?

Yes. Source inspection gives a high-confidence path: current main returns scope-mismatch from verifyDeviceToken, then resolveConnectAuthDecision collapses that into device_token_mismatch before clients can recover correctly.

Is this the best way to solve the issue?

Yes. The PR fixes the reason propagation at the auth decision boundary, adds an additive protocol detail, stops retry loops, preserves valid stored tokens, and limits scope narrowing to bootstrap/cached device-token sessions rather than weakening shared-token authority.

What I checked:

Protected PR state: Provided GitHub context shows the PR is open, authored by BunsDev with author association MEMBER, and labeled maintainer, so cleanup close is not allowed even when the patch is reviewable. (ec990fe2cef1)
Current-main bug path: verifyDeviceToken returns reason: "scope-mismatch" when the token is valid but its scopes do not cover the approved baseline or requested scopes. (src/infra/device-pairing.ts:915, 3dd2c1a8b850)
Current-main diagnostic collapse: Current main types device-token verification as { ok: boolean } and maps explicit device-token failures to device_token_mismatch, losing the underlying scope-mismatch reason. (src/gateway/server/ws-connection/auth-context.ts:35, 3dd2c1a8b850)
PR preserves scope mismatch reason: The PR widens the verification result type, maps scope-mismatch/scope_mismatch to scope_mismatch, and uses that mapped reason when device-token verification fails. (src/gateway/server/ws-connection/auth-context.ts:35, ec990fe2cef1)
PR adds protocol and reconnect handling: The PR adds AUTH_SCOPE_MISMATCH, maps scope_mismatch to that detail, and includes it in both browser and shared GatewayClient non-recoverable reconnect gates. (src/gateway/protocol/connect-error-details.ts:14, ec990fe2cef1)
PR preserves intended scope boundaries: Swift now filters bootstrap-token handoff scopes and reuses stored scopes only for non-explicit stored device-token sessions, while explicit --scopes sets scopesAreExplicit in the macOS CLI. (apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayChannel.swift:613, ec990fe2cef1)

Likely related people:

steipete: Recent merged pairing-scope work and shortlog history point to Peter Steinberger as a heavy contributor across gateway, pairing, and release-adjacent surfaces touched by this PR. (role: recent gateway/pairing area contributor; confidence: high; commits: c9053ff20853, 88673b2fad28, 1365b71f0285; files: src/infra/device-pairing.ts, src/gateway/server/ws-connection/auth-context.ts, apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayChannel.swift)
BunsDev: Beyond this PR, git history shows Val Alexander/BunsDev has prior current-main work in the Control UI and gateway connect path, including gateway nonce handling and UI gateway work. (role: adjacent current-main contributor and PR author with prior UI/gateway history; confidence: medium; commits: 42b3c5235080, e697ec273a85, 629869800844; files: ui/src/ui/gateway.ts, ui/src/ui/gateway.node.test.ts)
shakkernerd: Current-main blame and history point to Shakker on recent gateway auth diagnostics and earlier pairing scope checks in the affected area. (role: recent gateway auth/test contributor; confidence: medium; commits: 5be22e778129, 9d0669cfa356, 525d6e0671f7; files: src/gateway/server/ws-connection/auth-context.ts, ui/src/ui/gateway.ts, src/gateway/reconnect-gating.test.ts)
ngutman: History shows Nimrod Gutman on iOS and macOS gateway discovery/configuration flows adjacent to the Swift recovery UX changed here. (role: adjacent iOS/macOS gateway contributor; confidence: low; commits: a6131438eaa0, 3d3e8fe78c91, 1eb7198badbb; files: apps/ios/Sources/Model/NodeAppModel.swift, apps/macos/Sources/OpenClawMacCLI/ConnectCommand.swift, apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayConnectionProblem.swift)

Remaining risk / open question:

I did not run the targeted test commands or a live iOS/browser session in this read-only review; the verdict is based on source inspection and the PR body's reported verification.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 3dd2c1a8b850.

BunsDev · 2026-05-10T10:31:30Z

Addressed the ClawSweeper P2 findings in d50f089.

Restored the full Control UI, OpenClawKit, and macOS CLI default operator scope bundle for shared-token/dashboard/native sessions, including operator.admin and operator.pairing.
Limited bootstrap-safe narrowing to bootstrap-token connects and cached device-token reconnects by reusing the stored token's approved scope set.
Updated tests so full shared-token sessions and bootstrap/cached-token sessions are covered separately.

Verification after the fix:

pnpm test ui/src/ui/gateway.node.test.ts src/gateway/server.auth.control-ui.suite.ts src/gateway/server/ws-connection/auth-context.test.ts src/gateway/protocol/connect-error-details.test.ts src/infra/device-pairing.test.ts
swift test --package-path apps/shared/OpenClawKit --filter GatewayErrorsTests
swift test --package-path apps/macos --filter GatewayChannelConnectTests
pnpm exec oxfmt --check --threads=1 ui/src/ui/gateway.ts ui/src/ui/gateway.node.test.ts CHANGELOG.md
git diff --check

BunsDev · 2026-05-11T12:00:38Z

@clawsweeper re-review

clawsweeper · 2026-05-11T12:02:31Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Complete
Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
Run: https://github.com/openclaw/clawsweeper/actions/runs/25668906004
Updated: 2026-05-11T12:09:06.386Z

BunsDev · 2026-05-11T15:31:22Z

@clawsweeper re-review

clawsweeper · 2026-05-11T15:33:11Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Failed
Detail: The targeted re-review did not finish cleanly. Check the workflow run for details.
Run: https://github.com/openclaw/clawsweeper/actions/runs/25680039044
Updated: 2026-05-11T15:46:33.789Z

BunsDev · 2026-05-11T19:03:54Z

@clawsweeper re-review

clawsweeper · 2026-05-11T19:05:25Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Complete
Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
Run: https://github.com/openclaw/clawsweeper/actions/runs/25691238517
Updated: 2026-05-11T19:13:18.206Z

BunsDev · 2026-05-11T19:14:19Z

Maintainer validation for ec990fe2cef1c113d919885b515beb8eea7b9f67:

pnpm test ui/src/ui/gateway.node.test.ts src/gateway/reconnect-gating.test.ts src/gateway/client.test.ts src/gateway/protocol/connect-error-details.test.ts
pnpm test ui/src/ui/gateway.node.test.ts src/gateway/server.auth.control-ui.test.ts src/gateway/server/ws-connection/auth-context.test.ts src/gateway/protocol/connect-error-details.test.ts src/infra/device-pairing.test.ts src/gateway/server/ws-connection/auth-messages.test.ts src/gateway/server/ws-connection/handshake-auth-helpers.test.ts src/gateway/reconnect-gating.test.ts src/gateway/client.test.ts
pnpm exec oxfmt --check --threads=1 ui/src/ui/gateway.ts ui/src/ui/gateway.node.test.ts src/gateway/client.ts src/gateway/client.test.ts src/gateway/reconnect-gating.test.ts src/gateway/protocol/connect-error-details.ts src/gateway/protocol/connect-error-details.test.ts
swift test --package-path apps/macos --filter GatewayChannelConnectTests
swift test --package-path apps/shared/OpenClawKit --filter GatewayErrorsTests
git diff --check
Conflict marker scan: no unresolved markers; only existing literal separator lines in scripts/codesign-mac-app.sh matched the raw delimiter pattern.

Review/security gates:

ClawSweeper re-review completed: https://github.com/openclaw/clawsweeper/actions/runs/25691238517
ClawSweeper verdict: security cleared; no repair lane needed; normal maintainer validation and landing.
GitHub CI at merge decision: no failed checks; 42 passing / 39 queued / 8 skipped. Passing includes macos-swift, macos-node, security-fast, security-scm-fast, security-dependency-audit, checks-fast-protocol, and focused core/gateway shards. Queued checks are broad optional CI/security lanes waiting on runners; branch reports no required checks.

Landing scope:

BunsDev requested a review from a team as a code owner May 10, 2026 08:54

openclaw-barnacle Bot added docs Improvements or additions to documentation app: macos App: macos app: web-ui App: web-ui gateway Gateway runtime size: M maintainer Maintainer-authored PR labels May 10, 2026

BunsDev force-pushed the meow/ios-operator-bootstrap-scopes branch from 1c9f28a to 9fc98c2 Compare May 10, 2026 08:56

BunsDev force-pushed the meow/ios-operator-bootstrap-scopes branch 2 times, most recently from 138132c to 8f3984d Compare May 11, 2026 12:00

BunsDev added 3 commits May 11, 2026 10:29

fix: align operator bootstrap scopes

4a01a4a

fix: preserve full operator scope sessions

ca1da35

fix: preserve explicit native scopes

92d697c

BunsDev force-pushed the meow/ios-operator-bootstrap-scopes branch from 8f3984d to 92d697c Compare May 11, 2026 15:30

BunsDev and others added 3 commits May 11, 2026 13:46

Merge branch 'main' into meow/ios-operator-bootstrap-scopes

a583309

Merge branch 'main' into meow/ios-operator-bootstrap-scopes

16f7a5a

fix: stop scope mismatch reconnect loops

ec990fe

openclaw-barnacle Bot added size: L and removed size: M labels May 11, 2026

BunsDev merged commit 51b73b3 into main May 11, 2026
93 of 95 checks passed

BunsDev deleted the meow/ios-operator-bootstrap-scopes branch May 11, 2026 19:14

This was referenced May 11, 2026

fix(auth): operator scope mismatch silently rejected as device token mismatch #79292

Closed

fix(auth): propagate scope-mismatch reason instead of collapsing to device_token_mismatch #79314

Closed

clawsweeper Bot mentioned this pull request Jun 30, 2026

iOS app loses Gateway Token after QR pairing; mobile chat stays disconnected over LAN #98033

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Fix iOS operator bootstrap scope diagnostics#80189

Fix iOS operator bootstrap scope diagnostics#80189
BunsDev merged 6 commits into
mainfrom
meow/ios-operator-bootstrap-scopes

BunsDev commented May 10, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented May 10, 2026 •

edited

Loading

Uh oh!

BunsDev commented May 10, 2026

Uh oh!

BunsDev commented May 11, 2026

Uh oh!

clawsweeper Bot commented May 11, 2026 •

edited

Loading

Uh oh!

BunsDev commented May 11, 2026

Uh oh!

clawsweeper Bot commented May 11, 2026 •

edited

Loading

Uh oh!

BunsDev commented May 11, 2026

Uh oh!

clawsweeper Bot commented May 11, 2026 •

edited

Loading

Uh oh!

BunsDev commented May 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Uh oh!

Conversation

BunsDev commented May 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Security and stability

Verification

Issues and superseded PRs

Uh oh!

clawsweeper Bot commented May 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

BunsDev commented May 10, 2026

Uh oh!

BunsDev commented May 11, 2026

Uh oh!

clawsweeper Bot commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

BunsDev commented May 11, 2026

Uh oh!

clawsweeper Bot commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

BunsDev commented May 11, 2026

Uh oh!

clawsweeper Bot commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

BunsDev commented May 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

BunsDev commented May 10, 2026 •

edited

Loading

clawsweeper Bot commented May 10, 2026 •

edited

Loading

clawsweeper Bot commented May 11, 2026 •

edited

Loading

clawsweeper Bot commented May 11, 2026 •

edited

Loading

clawsweeper Bot commented May 11, 2026 •

edited

Loading