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

• Repository: openclaw/openclaw
• Author: openperf
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/59092

Description (problem / solution / changelog)

Summary

• Problem: v2026.3.31 breaks exec tool connections on local loopback setups (Issue #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

1. Start a local OpenClaw instance on main or v2026.3.31.
2. Connect a local client (e.g., CLI) with the operator role to establish initial pairing.
3. Attempt to use the exec tool or connect a node host from the same local loopback address.
4. Observe the connection being rejected with a 1008 "pairing required" error.
5. 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

Changed files

• CHANGELOG.md (modified, +2/-0)
• src/gateway/server/ws-connection/handshake-auth-helpers.test.ts (modified, +31/-1)
• src/gateway/server/ws-connection/handshake-auth-helpers.ts (modified, +3/-1)
• src/infra/device-pairing.test.ts (modified, +15/-0)
• src/infra/device-pairing.ts (modified, +9/-2)