Require approval for setup-code device pairing [AI] by pgondhi987 · Pull Request #81292 · openclaw/openclaw

pgondhi987 · 2026-05-13T04:47:46Z

Summary

Problem: setup-code bootstrap could silently approve a fresh node pairing and mint extra operator-scoped device tokens.
Why it matters: setup-code pairing should not grant durable operator access before the device pairing state has been explicitly approved.
What changed: setup-code bootstrap profiles are now node-only, bootstrap connect no longer auto-approves remote pairing, and hello-ok no longer returns extra role tokens.
What did NOT change (scope boundary): existing approved device-token reconnects and explicit pairing approval flows remain in place.

AI-assisted: Yes

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

N/A
This PR addresses a bug or regression

Real behavior proof (required for external PRs)

Behavior or issue addressed: setup-code pairing no longer returns durable operator tokens before pairing approval.
Real environment tested: Not run in a live OpenClaw setup.
Exact steps or command run after this patch: node --import tsx -e "await import('./src/shared/device-bootstrap-profile.ts'); await import('./src/infra/device-bootstrap.ts'); await import('./src/infra/device-pairing.ts');" and node --import tsx -e "await import('./src/gateway/server/ws-connection/message-handler.ts');"
Evidence after fix: import smokes completed without output or errors.
Observed result after fix: touched TypeScript modules load successfully.
What was not tested: full test suite, live channel pairing, and end-to-end device pairing.
Before evidence: N/A

Root Cause (if applicable)

Root cause: the setup-code bootstrap profile included both node and operator roles, and the gateway handshake used that profile to silently approve pairing and return extra role tokens during a node connect.
Missing detection / guardrail: coverage allowed setup-code bootstrap to complete without an explicit pending pairing approval check.
Contributing context (if known): setup-code pairing and bootstrap token handoff shared profile state across roles.

Regression Test Plan (if applicable)

Coverage level that should have caught this:
- Unit test
- Seam / integration test
- End-to-end test
- Existing coverage already sufficient
Target test or file: src/gateway/server.auth.control-ui.suite.ts, src/infra/device-pairing.test.ts, src/infra/device-bootstrap.test.ts, src/shared/device-bootstrap-profile.test.ts, src/pairing/setup-code.test.ts
Scenario the test should lock in: setup-code bootstrap creates a pending node pairing, requires approval before a durable token is returned, and does not create operator tokens from node setup.
Why this is the smallest reliable guardrail: the gateway connect seam exercises the bootstrap token, pairing state, hello-ok auth payload, and token verification behavior together.
Existing test that already covers this (if any): updated gateway and infra pairing coverage.
If no new test is added, why not: N/A

User-visible / Behavior Changes

Setup-code pairing now requires an explicit pairing approval before the connecting device receives a durable node token. Setup-code bootstrap no longer grants operator role tokens as part of node setup.

Diagram (if applicable)

Before:
setup code -> node connect -> silent pairing approval -> node token + extra operator token

After:
setup code -> node connect -> pending pairing -> approval -> node token only

Security Impact (required)

New permissions/capabilities? No
Secrets/tokens handling changed? Yes
New/changed network calls? No
Command/tool execution surface changed? No
Data access scope changed? Yes
If any Yes, explain risk + mitigation: setup-code bootstrap now narrows token issuance to the approved node role and blocks operator token handoff from the node setup path.

Repro + Verification

Environment

OS: Linux workspace
Runtime/container: Node with tsx import smoke
Model/provider: N/A
Integration/channel (if any): Gateway setup-code/device pairing
Relevant config (redacted): N/A

Steps

Import the changed bootstrap/profile/pairing modules with node --import tsx.
Import the changed gateway WebSocket message handler with node --import tsx.

Expected

Modules load without syntax or missing-export failures.

Actual

Modules loaded successfully.

Evidence

Trace/log snippets

Import smokes completed without output or errors.

Human Verification (required)

What you personally verified (not just CI), and how:

Verified scenarios: TypeScript import smoke for the changed bootstrap, pairing, and gateway handshake modules.
Edge cases checked: static sweeps for stale operator-token handoff references and setup profile expectations.
What you did not verify: full test suite, live setup-code scan flow, and external channel flow.

Review Conversations

I replied to or resolved every bot review conversation I addressed in this PR.
I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

Backward compatible? Yes
Config/env changes? No
Migration needed? No
If yes, exact upgrade steps: N/A

Risks and Mitigations

Risk: setup-code pairing flows that expected immediate token return now require approval.
- Mitigation: the existing pairing approval path remains available and the gateway coverage now locks in the pending-then-approve flow.

clawsweeper · 2026-05-13T04:51:23Z

Codex review: needs real behavior proof before merge.

Summary
This PR makes setup-code bootstrap profiles node-only, stops fresh bootstrap-token node connects from silent pairing approval, removes extra role tokens from hello-ok, and updates gateway/bootstrap/pairing tests.

Reproducibility: yes. for the current-main behavior and the PR regression from source inspection: current main auto-approves the baseline QR bootstrap path, while the PR makes that path return PAIRING_REQUIRED until a later retry. No live PR behavior was demonstrated.

Real behavior proof
Needs stronger real behavior proof before merge: The PR body says no live OpenClaw setup was run and only import smokes completed; before merge, please add a screenshot/recording, terminal output, or redacted logs from a real setup-code pairing flow, redacting IPs, keys, phone numbers, and private endpoints, then update the PR body to trigger review or ask a maintainer for @clawsweeper re-review.

Next step before merge
This is a protected, security-sensitive gateway/auth PR with a blocking behavior regression and missing real setup-code proof, so it needs contributor proof plus maintainer product/security judgment rather than an automated repair lane.

Security
Cleared: No supply-chain or new secret-exposure issue was found in the diff; the blocking concern is the functional/auth-flow regression above.

Review findings

[P1] Preserve the QR bootstrap handoff — src/gateway/server/ws-connection/message-handler.ts:1023-1026

Review details

Best possible solution:

Keep the hardening goal as a maintainer security/product decision: if operator handoff must be removed, preserve a one-handshake node bootstrap path or add coordinated client wait/retry onboarding with real setup-code proof.

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

Yes for the current-main behavior and the PR regression from source inspection: current main auto-approves the baseline QR bootstrap path, while the PR makes that path return PAIRING_REQUIRED until a later retry. No live PR behavior was demonstrated.

Is this the best way to solve the issue?

No. Deleting gateway silent approval alone is not the narrowest maintainable fix because it reopens the shipped QR onboarding failure unless native clients or the setup-code flow are updated and proven live.

Full review comments:

[P1] Preserve the QR bootstrap handoff — src/gateway/server/ws-connection/message-handler.ts:1023-1026
This removes the baseline bootstrap-token node path from the silent pairing decision, so a fresh setup-code scan now returns PAIRING_REQUIRED instead of the hello-ok device-token handoff. Current clients treat that detail as non-recoverable, and the merged fix(pairing): restore qr bootstrap onboarding handoff #58382 explicitly restored this one-handshake QR onboarding path to avoid a stalled manual-approval loop. Keep the hardening, but preserve the baseline node handoff or update the clients/onboarding flow together.
Confidence: 0.9

Overall correctness: patch is incorrect
Overall confidence: 0.88

Acceptance criteria:

pnpm test -- src/gateway/server.auth.control-ui.test.ts -t bootstrap
pnpm test -- src/infra/device-bootstrap.test.ts src/infra/device-pairing.test.ts src/shared/device-bootstrap-profile.test.ts src/pairing/setup-code.test.ts
Run a real setup-code pairing flow showing pending/approval/retry behavior or preserved one-handshake handoff with secrets redacted.

What I checked:

Live PR state and proof gate: The live PR is open with the protected maintainer label, touches gateway/auth token behavior, and its body says a live OpenClaw setup was not run; the only after-patch commands were TypeScript import smokes. (7a6ec4f096f6)
Current setup profile includes node and bounded operator handoff: Current main's setup bootstrap profile grants node plus bounded operator scopes, which is the behavior the PR changes to node-only. (src/shared/device-bootstrap-profile.ts:22, 8fd0f9965e24)
Current gateway silently approves the baseline bootstrap node path: Current main explicitly computes allowSilentBootstrapPairing, includes it in the silent pairing decision, and records handoffBootstrapProfile after approving that baseline path. (src/gateway/server/ws-connection/message-handler.ts:1042, 8fd0f9965e24)
Current regression test locks the auto-approved QR handoff: The existing gateway suite expects fresh QR setup-code bootstrap pairing to auto-approve, return a node device token, and include a bounded operator handoff token with no pending request left behind. (src/gateway/server.auth.control-ui.suite.ts:983, 8fd0f9965e24)
PR removes the silent bootstrap approval branch: At the PR head, the requestDevicePairing call no longer includes allowSilentBootstrapPairing, so a remote fresh bootstrap-token node connect creates a pending request and returns PAIRING_REQUIRED until a later retry. (src/gateway/server/ws-connection/message-handler.ts:1023, 7a6ec4f096f6)
Current clients pause reconnect on pairing required: Current Swift and Android gateway clients classify PAIRING_REQUIRED as a non-recoverable auth failure, so the server-side change needs coordinated client retry/onboarding handling or live proof that the setup-code flow still completes. (apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayErrors.swift:155, 8fd0f9965e24)

Likely related people:

ngutman: Introduced the merged QR bootstrap onboarding handoff that this PR changes, including the one-handshake baseline behavior and iOS reconnect context. (role: feature owner; confidence: high; commits: 69fe999373fd, a9140abea6d4, 226ca1f324a4; files: src/gateway/server/ws-connection/message-handler.ts, src/infra/device-bootstrap.ts, src/infra/device-pairing.ts)
obviyus: Authored earlier bootstrap token revocation/redemption and operator pairing setup-code work that current main builds on. (role: introduced adjacent auth behavior; confidence: high; commits: 2dced6b4a004, a42f000b537f, b08d58c91718; files: src/infra/device-bootstrap.ts, src/gateway/server/ws-connection/message-handler.ts)
steipete: Recent history shows bootstrap profile centralization and follow-up auth/pairing fixes in the same device-bootstrap surface. (role: recent area contributor; confidence: medium; commits: 6686f1cb2ce3, 7d22a16adb21, 72072d8b2eba; files: src/shared/device-bootstrap-profile.ts, src/infra/device-bootstrap.ts, src/gateway/server/ws-connection/message-handler.ts)
eleqtrizit: Authored the merged bounded bootstrap handoff scope change that defines the operator-scope allowlist this PR removes from the default setup profile. (role: adjacent hardening contributor; confidence: medium; commits: b8372a714ccc; files: src/shared/device-bootstrap-profile.ts, src/infra/device-bootstrap.ts)
pgondhi987: Beyond authoring this PR, recent merged main history shows adjacent gateway auth and bootstrap pairing hardening work in the same files. (role: recent area contributor; confidence: medium; commits: 1c85eff9b1e6, 2d00bedc1e73, 0e702f106313; files: src/gateway/server/ws-connection/message-handler.ts, src/infra/device-bootstrap.ts)

Remaining risk / open question:

The PR conflicts with a merged QR bootstrap onboarding fix that intentionally preserved baseline silent approval.
The branch does not update native client retry/onboarding behavior even though current clients pause on PAIRING_REQUIRED.
The contributor did not provide real setup-code/device-pairing proof after the patch.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 8fd0f9965e24.

pgondhi987 · 2026-05-13T10:38:13Z

Not applicable to this automation stage; changelog/release-note and external real behavior proof requirements are handled outside auto-pr stages.

Quoted comment from @clawsweeper:

Codex review: needs real behavior proof before merge.

Summary
This PR makes setup-code bootstrap profiles node-only, stops fresh bootstrap-token node connects from silent pairing approval, removes extra role tokens from hello-ok, and updates gateway/bootstrap/pairing tests.

Reproducibility: yes. for the current-main behavior and the PR regression from source inspection: current main auto-approves the baseline QR bootstrap path, while the PR makes that path return PAIRING_REQUIRED until a later retry. No live PR behavior was demonstrated.

Real behavior proof
Needs stronger real behavior proof before merge: The PR body says no live OpenClaw setup was run and only import smokes completed; before merge, please add a screenshot/recording, terminal output, or redacted logs from a real setup-code pairing flow, redacting IPs, keys, phone numbers, and private endpoints, then update the PR body to trigger review or ask a maintainer for @clawsweeper re-review.

Next step before merge
This is a protected, security-sensitive gateway/auth PR with a blocking behavior regression and missing real setup-code proof, so it needs contributor proof plus maintainer product/security judgment rather than an automated repair lane.

Security
Cleared: No supply-chain or new secret-exposure issue was found in the diff; the blocking concern is the functional/auth-flow regression above.

Review findings

[P1] Preserve the QR bootstrap handoff — src/gateway/server/ws-connection/message-handler.ts:1023-1026

Review details

Best possible solution:

Keep the hardening goal as a maintainer security/product decision: if operator handoff must be removed, preserve a one-handshake node bootstrap path or add coordinated client wait/retry onboarding with real setup-code proof.

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

Yes for the current-main behavior and the PR regression from source inspection: current main auto-approves the baseline QR bootstrap path, while the PR makes that path return PAIRING_REQUIRED until a later retry. No live PR behavior was demonstrated.

Is this the best way to solve the issue?

No. Deleting gateway silent approval alone is not the narrowest maintainable fix because it reopens the shipped QR onboarding failure unless native clients or the setup-code flow are updated and proven live.

Full review comments:

[P1] Preserve the QR bootstrap handoff — src/gateway/server/ws-connection/message-handler.ts:1023-1026
This removes the baseline bootstrap-token node path from the silent pairing decision, so a fresh setup-code scan now returns PAIRING_REQUIRED instead of the hello-ok device-token handoff. Current clients treat that detail as non-recoverable, and the merged fix(pairing): restore qr bootstrap onboarding handoff #58382 explicitly restored this one-handshake QR onboarding path to avoid a stalled manual-approval loop. Keep the hardening, but preserve the baseline node handoff or update the clients/onboarding flow together.
Confidence: 0.9

Overall correctness: patch is incorrect
Overall confidence: 0.88

Acceptance criteria:

pnpm test -- src/gateway/server.auth.control-ui.test.ts -t bootstrap

pnpm test -- src/infra/device-bootstrap.test.ts src/infra/device-pairing.test.ts src/shared/device-bootstrap-profile.test.ts src/pairing/setup-code.test.ts

Run a real setup-code pairing flow showing pending/approval/retry behavior or preserved one-handshake handoff with secrets redacted.

What I checked:

Live PR state and proof gate: The live PR is open with the protected maintainer label, touches gateway/auth token behavior, and its body says a live OpenClaw setup was not run; the only after-patch commands were TypeScript import smokes. (7a6ec4f096f6)

Current setup profile includes node and bounded operator handoff: Current main's setup bootstrap profile grants node plus bounded operator scopes, which is the behavior the PR changes to node-only. (src/shared/device-bootstrap-profile.ts:22, 8fd0f9965e24)

Current gateway silently approves the baseline bootstrap node path: Current main explicitly computes allowSilentBootstrapPairing, includes it in the silent pairing decision, and records handoffBootstrapProfile after approving that baseline path. (src/gateway/server/ws-connection/message-handler.ts:1042, 8fd0f9965e24)

Current regression test locks the auto-approved QR handoff: The existing gateway suite expects fresh QR setup-code bootstrap pairing to auto-approve, return a node device token, and include a bounded operator handoff token with no pending request left behind. (src/gateway/server.auth.control-ui.suite.ts:983, 8fd0f9965e24)

PR removes the silent bootstrap approval branch: At the PR head, the requestDevicePairing call no longer includes allowSilentBootstrapPairing, so a remote fresh bootstrap-token node connect creates a pending request and returns PAIRING_REQUIRED until a later retry. (src/gateway/server/ws-connection/message-handler.ts:1023, 7a6ec4f096f6)

Current clients pause reconnect on pairing required: Current Swift and Android gateway clients classify PAIRING_REQUIRED as a non-recoverable auth failure, so the server-side change needs coordinated client retry/onboarding handling or live proof that the setup-code flow still completes. (apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayErrors.swift:155, 8fd0f9965e24)

Likely related people:

ngutman: Introduced the merged QR bootstrap onboarding handoff that this PR changes, including the one-handshake baseline behavior and iOS reconnect context. (role: feature owner; confidence: high; commits: 69fe999373fd, a9140abea6d4, 226ca1f324a4; files: src/gateway/server/ws-connection/message-handler.ts, src/infra/device-bootstrap.ts, src/infra/device-pairing.ts)

obviyus: Authored earlier bootstrap token revocation/redemption and operator pairing setup-code work that current main builds on. (role: introduced adjacent auth behavior; confidence: high; commits: 2dced6b4a004, a42f000b537f, b08d58c91718; files: src/infra/device-bootstrap.ts, src/gateway/server/ws-connection/message-handler.ts)

steipete: Recent history shows bootstrap profile centralization and follow-up auth/pairing fixes in the same device-bootstrap surface. (role: recent area contributor; confidence: medium; commits: 6686f1cb2ce3, 7d22a16adb21, 72072d8b2eba; files: src/shared/device-bootstrap-profile.ts, src/infra/device-bootstrap.ts, src/gateway/server/ws-connection/message-handler.ts)

eleqtrizit: Authored the merged bounded bootstrap handoff scope change that defines the operator-scope allowlist this PR removes from the default setup profile. (role: adjacent hardening contributor; confidence: medium; commits: b8372a714ccc; files: src/shared/device-bootstrap-profile.ts, src/infra/device-bootstrap.ts)

pgondhi987: Beyond authoring this PR, recent merged main history shows adjacent gateway auth and bootstrap pairing hardening work in the same files. (role: recent area contributor; confidence: medium; commits: 1c85eff9b1e6, 2d00bedc1e73, 0e702f106313; files: src/gateway/server/ws-connection/message-handler.ts, src/infra/device-bootstrap.ts)

Remaining risk / open question:

The PR conflicts with a merged QR bootstrap onboarding fix that intentionally preserved baseline silent approval.

The branch does not update native client retry/onboarding behavior even though current clients pause on PAIRING_REQUIRED.

The contributor did not provide real setup-code/device-pairing proof after the patch.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 8fd0f9965e24.

* fix: require approval for setup-code bootstrap pairing * addressing review-skill * addressing codex review * addressing codex review * addressing codex review * addressing codex review * addressing codex review * addressing ci * addressing ci * docs: add changelog entry for PR merge

fix: require approval for setup-code bootstrap pairing

72a9083

pgondhi987 requested a review from a team as a code owner May 13, 2026 04:47

openclaw-barnacle Bot added gateway Gateway runtime size: M maintainer Maintainer-authored PR labels May 13, 2026

pgondhi987 added 2 commits May 13, 2026 04:54

addressing review-skill

7a6ec4f

addressing codex review

653d549

openclaw-barnacle Bot added docs Improvements or additions to documentation channel: telegram Channel integration: telegram labels May 13, 2026

addressing codex review

de98637

openclaw-barnacle Bot added app: android App: android app: web-ui App: web-ui size: L and removed size: M labels May 13, 2026

pgondhi987 added 3 commits May 13, 2026 10:56

addressing codex review

c90e729

addressing codex review

0940da2

addressing codex review

3537eef

openclaw-barnacle Bot added size: XL and removed size: L labels May 13, 2026

pgondhi987 added 4 commits May 13, 2026 11:32

addressing ci

fa23970

addressing ci

5298eaa

Merge remote-tracking branch 'origin/main' into fix/fix-638

43ad5e9

docs: add changelog entry for PR merge

5f05627

pgondhi987 merged commit b17e77a into openclaw:main May 13, 2026
15 of 16 checks passed

github-actions Bot mentioned this pull request May 13, 2026

📡 Upstream Digest — 2026-05-13 14:10 UTC curtismercier/openclaw-mods#846

Open

ngutman mentioned this pull request May 18, 2026

[codex] restore QR bootstrap operator handoff #83684

Merged

dlebee mentioned this pull request May 19, 2026

[Bug]: openclaw nodes approve requires operator.admin — blocks automation after 2026.5.18 node surface gate #84144

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Require approval for setup-code device pairing [AI]#81292

Require approval for setup-code device pairing [AI]#81292
pgondhi987 merged 11 commits into
openclaw:mainfrom
pgondhi987:fix/fix-638

pgondhi987 commented May 13, 2026

Uh oh!

clawsweeper Bot commented May 13, 2026 •

edited

Loading

Uh oh!

pgondhi987 commented May 13, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

pgondhi987 commented May 13, 2026

Summary

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Real behavior proof (required for external PRs)

Root Cause (if applicable)

Regression Test Plan (if applicable)

User-visible / Behavior Changes

Diagram (if applicable)

Security Impact (required)

Repro + Verification

Environment

Steps

Expected

Actual

Evidence

Human Verification (required)

Review Conversations

Compatibility / Migration

Risks and Mitigations

Uh oh!

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

Uh oh!

Uh oh!

pgondhi987 commented May 13, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

clawsweeper Bot commented May 13, 2026 •

edited

Loading