fix(gateway): allow silent role upgrades for local loopback clients by openperf · Pull Request #59092 · openclaw/openclaw

openperf · 2026-04-01T15:06:54Z

Summary

Problem: v2026.3.31 breaks exec tool connections on local loopback setups (Issue [Bug]: v2026.3.31 breaks exec on local loopback setups #59045). When a local client connects with a new role (e.g., node host connecting after an operator client), the connection is rejected with a 1008 "pairing required" error, even though the device is already paired.
Root Cause: The issue stems from two interacting changes in v2026.3.31:
1. listEffectivePairedDeviceRoles (in src/infra/device-pairing.ts, line 169) incorrectly returns an empty array [] when device.tokens is an empty object {}, failing to fall back to the legacy device.roles field. This happens because the original guard if (device.tokens) is truthy for {}, but listActiveTokenRoles({}) returns undefined (since Object.values({}) yields no entries), resulting in undefined ?? [] = [].
2. When a role upgrade is triggered (because the requested role is not in the effective roles), shouldAllowSilentLocalPairing (in src/gateway/server/ws-connection/handshake-auth-helpers.ts, line 58) does not support the role-upgrade reason. This prevents local loopback clients from automatically approving the role upgrade via silent pairing, causing a 1008 close.
Fix:
1. Updated listEffectivePairedDeviceRoles to fall back to legacy role fields (device.roles, device.role) when the tokens map is present but has no entries (empty object {}). When token entries exist but are all revoked, the function still returns [] to preserve the security invariant that revoked tokens permanently remove role access.
2. Updated shouldAllowSilentLocalPairing to explicitly allow the role-upgrade reason for local clients, ensuring that loopback connections can seamlessly acquire new roles without manual intervention.
What changed:
- src/infra/device-pairing.ts: Fixed listEffectivePairedDeviceRoles fallback logic to distinguish empty tokens map from revoked tokens.
- src/infra/device-pairing.test.ts: Added regression test for the empty tokens map fallback scenario.
- src/gateway/server/ws-connection/handshake-auth-helpers.ts: Added role-upgrade to the allowed reasons in shouldAllowSilentLocalPairing.
- src/gateway/server/ws-connection/handshake-auth-helpers.test.ts: Updated existing test and added new test for silent role-upgrade boundary (local vs remote).
What did NOT change (scope boundary):
- Remote client pairing logic remains unchanged — silent role upgrades are still rejected for non-local clients.
- The security property that revoked tokens permanently remove role access is preserved — the existing test "derives effective roles from active tokens instead of sticky historical roles" continues to pass unchanged.
- Scope upgrade logic (reason === "scope-upgrade" is force-set to silent: false in requirePairing) is untouched.
- General authentication flows, bootstrap token handling, and metadata-upgrade pairing are not affected.

Reproduction

Start a local OpenClaw instance on main or v2026.3.31.
Connect a local client (e.g., CLI) with the operator role to establish initial pairing.
Attempt to use the exec tool or connect a node host from the same local loopback address.
Observe the connection being rejected with a 1008 "pairing required" error.
Apply this patch and repeat steps 1-3; the connection should succeed silently.

Risk / Mitigation

Risk: Allowing silent role upgrades for local clients could theoretically allow a compromised local process to escalate its privileges to other roles without user interaction.
Mitigation: This risk is mitigated by the existing isLocalClient guard, which restricts this behavior strictly to loopback connections (127.0.0.1 / ::1). Remote connections still require explicit approval for role upgrades. Additionally, the fix in listEffectivePairedDeviceRoles preserves the security invariant that explicitly revoked tokens cannot be bypassed — only empty token maps (from fresh or legacy pairing records) trigger the fallback. Comprehensive unit tests have been added to verify both the positive path (local role-upgrade succeeds) and the negative boundary (remote role-upgrade is rejected; revoked tokens remain ineffective).

Change Type (select all)

Bug fix

Scope (select all touched areas)

Gateway
Infra

Linked Issue/PR

Fixes #59045

greptile-apps · 2026-04-01T15:11:27Z

Greptile Summary

This PR fixes a regression from v2026.3.31 that broke exec tool connections on local loopback setups (issue #59045). It addresses two interacting bugs: an incorrect empty-tokens fallback in listEffectivePairedDeviceRoles, and a missing role-upgrade case in shouldAllowSilentLocalPairing.

Key changes:

src/infra/device-pairing.ts: listEffectivePairedDeviceRoles now correctly distinguishes between an empty tokens map ({}, fall back to legacy role fields) and a non-empty map with all tokens revoked (authoritative revocation, return []). The old guard if (device.tokens) was truthy for {}, causing listActiveTokenRoles({}) → undefined to collapse to [] and discard legacy roles.
src/gateway/server/ws-connection/handshake-auth-helpers.ts: shouldAllowSilentLocalPairing now accepts \"role-upgrade\" as an allowed reason, enabling loopback clients to acquire new roles without manual approval (scoped to isLocalClient only; remote clients remain unchanged).
Tests: regression test for empty-tokens fallback added in device-pairing.test.ts; new boundary tests for role-upgrade (local → true, remote → false) and a scope-upgrade positive assertion added in handshake-auth-helpers.test.ts (addressing the prior review thread).

Confidence Score: 5/5

Safe to merge — minimal, targeted changes with strong test coverage and no logic errors found.

Both fixes are logically correct. The listEffectivePairedDeviceRoles rewrite correctly separates the three distinct states (active tokens, all-revoked tokens, absent/empty tokens) and preserves the security invariant for revoked tokens. The shouldAllowSilentLocalPairing addition is appropriately guarded by isLocalClient with no impact on remote clients. Test coverage is thorough: the regression test for empty-tokens fallback, the existing revocation test (unchanged), and the new boundary tests for role-upgrade all pass. The prior review thread concern about the missing scope-upgrade assertion was addressed in a follow-up commit. No remaining P0/P1 findings.

No files require special attention.

_{Reviews (2): Last reviewed commit: "fix(gateway ): allow silent role upgrade..." | Re-trigger Greptile}

openperf · 2026-04-01T16:33:22Z

Quick context on the approach and a follow-up on the greptile feedback.

The core issue is a JS truthy trap — {} passes the if (device.tokens) guard in listEffectivePairedDeviceRoles, so freshly paired devices with an empty tokens map get routed into the token-based role path instead of falling back to the legacy device.roles field. The result is an empty role set, which then triggers a role-upgrade pairing request that shouldAllowSilentLocalPairing didn't know how to handle silently. Two things going wrong in sequence, but the first one is the actual root cause introduced in v2026.3.31 — the second was a latent blind spot that just never mattered until now.

I deliberately kept the fix narrow: the Object.keys length check in listEffectivePairedDeviceRoles only kicks in for truly empty maps, so devices with revoked tokens still correctly get [] (no sneaking past a revocation). And the role-upgrade addition to shouldAllowSilentLocalPairing is gated behind the existing isLocalClient check, so remote clients are completely unaffected.

Regarding @greptile-apps's review — good catch on the scope-upgrade assertion gap. The test title promised coverage for three reasons but only asserted two. Pushed a follow-up commit (57460f1) that adds the missing scope-upgrade positive assertion. As greptile noted, this doesn't change runtime behavior today since requirePairing hard-codes silent: false for scope-upgrade anyway, but it keeps the test honest about the helper's own contract.

Ready for review.

When a local loopback client connects with a role not covered by existing device tokens, listEffectivePairedDeviceRoles incorrectly returns an empty role set for devices whose tokens map is an empty object. This triggers a role-upgrade pairing request that shouldAllowSilentLocalPairing rejects because it does not recognise the role-upgrade reason. Fix listEffectivePairedDeviceRoles to fall back to legacy role fields when the tokens map has no entries, and extend shouldAllowSilentLocalPairing to accept role-upgrade for local clients. Fixes openclaw#59045

…penperf

…penperf)

obviyus

Reviewed latest changes; landing now.

obviyus · 2026-04-02T02:43:54Z

Landed on main.

Landed source commit: e2d08e5
Merge commit: 51edd30

Thanks @openperf.

…penperf

…penperf) * fix(gateway ): allow silent role upgrades for local loopback clients When a local loopback client connects with a role not covered by existing device tokens, listEffectivePairedDeviceRoles incorrectly returns an empty role set for devices whose tokens map is an empty object. This triggers a role-upgrade pairing request that shouldAllowSilentLocalPairing rejects because it does not recognise the role-upgrade reason. Fix listEffectivePairedDeviceRoles to fall back to legacy role fields when the tokens map has no entries, and extend shouldAllowSilentLocalPairing to accept role-upgrade for local clients. Fixes openclaw#59045 * fix: restore local loopback role upgrades (openclaw#59092) (thanks @openperf) --------- Co-authored-by: Ayaan Zaidi <[email protected]>

…penperf

…penperf) * fix(gateway ): allow silent role upgrades for local loopback clients When a local loopback client connects with a role not covered by existing device tokens, listEffectivePairedDeviceRoles incorrectly returns an empty role set for devices whose tokens map is an empty object. This triggers a role-upgrade pairing request that shouldAllowSilentLocalPairing rejects because it does not recognise the role-upgrade reason. Fix listEffectivePairedDeviceRoles to fall back to legacy role fields when the tokens map has no entries, and extend shouldAllowSilentLocalPairing to accept role-upgrade for local clients. Fixes openclaw#59045 * fix: restore local loopback role upgrades (openclaw#59092) (thanks @openperf) --------- Co-authored-by: Ayaan Zaidi <[email protected]>

…penperf

…penperf) * fix(gateway ): allow silent role upgrades for local loopback clients When a local loopback client connects with a role not covered by existing device tokens, listEffectivePairedDeviceRoles incorrectly returns an empty role set for devices whose tokens map is an empty object. This triggers a role-upgrade pairing request that shouldAllowSilentLocalPairing rejects because it does not recognise the role-upgrade reason. Fix listEffectivePairedDeviceRoles to fall back to legacy role fields when the tokens map has no entries, and extend shouldAllowSilentLocalPairing to accept role-upgrade for local clients. Fixes openclaw#59045 * fix: restore local loopback role upgrades (openclaw#59092) (thanks @openperf) --------- Co-authored-by: Ayaan Zaidi <[email protected]>

…penperf

…penperf) * fix(gateway ): allow silent role upgrades for local loopback clients When a local loopback client connects with a role not covered by existing device tokens, listEffectivePairedDeviceRoles incorrectly returns an empty role set for devices whose tokens map is an empty object. This triggers a role-upgrade pairing request that shouldAllowSilentLocalPairing rejects because it does not recognise the role-upgrade reason. Fix listEffectivePairedDeviceRoles to fall back to legacy role fields when the tokens map has no entries, and extend shouldAllowSilentLocalPairing to accept role-upgrade for local clients. Fixes openclaw#59045 * fix: restore local loopback role upgrades (openclaw#59092) (thanks @openperf) --------- Co-authored-by: Ayaan Zaidi <[email protected]>

…penperf

…penperf) * fix(gateway ): allow silent role upgrades for local loopback clients When a local loopback client connects with a role not covered by existing device tokens, listEffectivePairedDeviceRoles incorrectly returns an empty role set for devices whose tokens map is an empty object. This triggers a role-upgrade pairing request that shouldAllowSilentLocalPairing rejects because it does not recognise the role-upgrade reason. Fix listEffectivePairedDeviceRoles to fall back to legacy role fields when the tokens map has no entries, and extend shouldAllowSilentLocalPairing to accept role-upgrade for local clients. Fixes openclaw#59045 * fix: restore local loopback role upgrades (openclaw#59092) (thanks @openperf) --------- Co-authored-by: Ayaan Zaidi <[email protected]>

…penperf

…penperf) * fix(gateway ): allow silent role upgrades for local loopback clients When a local loopback client connects with a role not covered by existing device tokens, listEffectivePairedDeviceRoles incorrectly returns an empty role set for devices whose tokens map is an empty object. This triggers a role-upgrade pairing request that shouldAllowSilentLocalPairing rejects because it does not recognise the role-upgrade reason. Fix listEffectivePairedDeviceRoles to fall back to legacy role fields when the tokens map has no entries, and extend shouldAllowSilentLocalPairing to accept role-upgrade for local clients. Fixes openclaw#59045 * fix: restore local loopback role upgrades (openclaw#59092) (thanks @openperf) --------- Co-authored-by: Ayaan Zaidi <[email protected]>

openperf requested a review from a team as a code owner April 1, 2026 15:06

openclaw-barnacle Bot added gateway Gateway runtime size: S labels Apr 1, 2026

greptile-apps Bot reviewed Apr 1, 2026

View reviewed changes

Comment thread src/gateway/server/ws-connection/handshake-auth-helpers.test.ts

openperf force-pushed the fix/59045-exec-loopback-pairing branch from 2682a7b to 57460f1 Compare April 1, 2026 15:38

openperf mentioned this pull request Apr 1, 2026

[Bug]: v2026.3.31 breaks exec on local loopback setups #59045

Closed

obviyus self-assigned this Apr 2, 2026

openperf and others added 2 commits April 2, 2026 08:11

fix: restore local loopback role upgrades (openclaw#59092) (thanks @o…

e2d08e5

…penperf)

obviyus force-pushed the fix/59045-exec-loopback-pairing branch from 57460f1 to e2d08e5 Compare April 2, 2026 02:42

obviyus approved these changes Apr 2, 2026

View reviewed changes

obviyus merged commit 51edd30 into openclaw:main Apr 2, 2026
24 of 25 checks passed

obviyus mentioned this pull request Apr 2, 2026

fix(gateway): silently auto-approve local role-upgrade pairing requests #39840

Closed

15 tasks

github-actions Bot mentioned this pull request Apr 2, 2026

📡 Upstream Digest — 2026-04-02 04:23 UTC curtismercier/openclaw-mods#439

Open

TheBlippo mentioned this pull request Apr 2, 2026

[Bug]: sessions_spawn sub-agent fails with "pairing required" (1008) on v2026.4.1 #59428

Closed

openperf mentioned this pull request Apr 2, 2026

fix(gateway): allow silent scope upgrades for local loopback clients #59503

Closed

4 tasks

This was referenced Apr 3, 2026

Compaction death spiral on copilot proxy: heavier upstream compaction + provider timeout ceiling = unrecoverable sessions karmaterminal/openclaw#61

Open

review: upstream 2026.3.28 → 2026.4.02 impact assessment karmaterminal/openclaw#65

Closed

martingarramon mentioned this pull request Apr 4, 2026

[Bug]: exec host=node regression in 2026.4.2 — agent exec always routes to gateway #60772

Closed

kdmonroe mentioned this pull request Apr 5, 2026

upgrade: openclaw 2026.3.14 -> 2026.4.2 kdmonroe/openclaw-deploy#1

Merged

11 tasks

steipete mentioned this pull request Apr 25, 2026

[Bug]: exec tool cannot authenticate to gateway in loopback mode #59215

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix(gateway): allow silent role upgrades for local loopback clients#59092

fix(gateway): allow silent role upgrades for local loopback clients#59092
obviyus merged 2 commits into
openclaw:mainfrom
openperf:fix/59045-exec-loopback-pairing

openperf commented Apr 1, 2026

Uh oh!

greptile-apps Bot commented Apr 1, 2026 •

edited

Loading

Uh oh!

Uh oh!

openperf commented Apr 1, 2026

Uh oh!

obviyus left a comment

Uh oh!

Uh oh!

obviyus commented Apr 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

openperf commented Apr 1, 2026

Summary

Reproduction

Risk / Mitigation

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Uh oh!

greptile-apps Bot commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Uh oh!

Uh oh!

openperf commented Apr 1, 2026

Uh oh!

obviyus left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

obviyus commented Apr 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

greptile-apps Bot commented Apr 1, 2026 •

edited

Loading