#17705: fix(gateway): allow trusted-proxy auth to bypass device-pairing gates
gateway
size: L
Cluster:
Device Auth and Security Fixes
## Summary
- Trusted-proxy auth connections were rejected with `"device identity required"` (code 1008) because the device-pairing layer only recognized `token` and `password` auth methods
- Two gates in `message-handler.ts` now also accept `authOk && authMethod === "trusted-proxy"`
- Added 4 e2e tests covering both gates and negative cases
## Root Cause
`sharedAuthOk` (used by both `canSkipDevice` and `skipPairing` gates) only checks for `"token"` or `"password"` methods. Trusted-proxy auth correctly sets `authOk = true` and `authMethod = "trusted-proxy"` via the primary `authorizeGatewayConnect()` call, but this was never consulted by the device-pairing layer.
## Changes
Two lines changed in `src/gateway/server/ws-connection/message-handler.ts`:
**Gate 1** (`canSkipDevice`, line 434):
```diff
- const canSkipDevice = sharedAuthOk;
+ const canSkipDevice = sharedAuthOk || (authOk && authMethod === "trusted-proxy");
```
**Gate 2** (`skipPairing`, line 652):
```diff
- const skipPairing = allowControlUiBypass && sharedAuthOk;
+ const skipPairing =
+ (allowControlUiBypass && sharedAuthOk) || (authOk && authMethod === "trusted-proxy");
```
## Comparison with PR #17378
This fix is more complete than #17378:
| Aspect | This PR | PR #17378 |
|--------|---------|-----------|
| Gate 1 (`canSkipDevice`) | Fixed | Fixed |
| Gate 2 (`skipPairing`) | **Fixed** | **Not fixed** |
| Requires `dangerouslyDisableDeviceAuth`? | No | Yes |
| Scope | Trusted-proxy inherently skips device pairing | Only skips when operator sets config flag |
Trusted-proxy inherently proves user identity via the reverse proxy — requiring an additional `dangerouslyDisableDeviceAuth` flag is redundant and creates unnecessary operator friction.
## Test Plan
4 new e2e tests in `server.auth.e2e.test.ts`:
- [x] Trusted-proxy connection without device identity succeeds (Gate 1)
- [x] Trusted-proxy control-ui with device identity skips pairing (Gate 2)
- [x] Connection from untrusted IP is rejected
- [x] Connection with missing user header is rejected
- [x] All 26 existing auth e2e tests pass (no regressions)
- [x] Lint, format, and type checks pass
Closes #8529
Related: #7384, #4833
Supersedes #17378
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Fixed trusted-proxy auth connections that were incorrectly rejected with "device identity required" errors. The device-pairing layer now recognizes `trusted-proxy` auth method alongside `token` and `password` methods in two critical gates (`canSkipDevice` and `skipPairing`).
- Two conditional checks in `message-handler.ts` now accept `authOk && authMethod === "trusted-proxy"` to allow trusted-proxy connections to bypass device pairing
- Added comprehensive e2e test coverage for both bypass gates plus negative cases (untrusted IP, missing header)
- Memory test file changes are formatting-only (oxfmt auto-formatting)
- Fix is more complete than #17378 by addressing both gates and not requiring additional config flags
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with minimal risk
- The fix is minimal, well-tested, and addresses a clear bug. The two-line logic change correctly extends the existing device-pairing bypass mechanism to include trusted-proxy auth. Comprehensive e2e tests cover both success and failure scenarios. The only other changes are formatting-only updates from oxfmt.
- No files require special attention
<sub>Last reviewed commit: 8f5d07b</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#17378: fix(gateway): allow dangerouslyDisableDeviceAuth with trusted-proxy...
by ar-nadeem · 2026-02-15
89.6%
#19389: Fix #2248: Allow insecure auth bypass when device signature validat...
by cedillarack · 2026-02-17
84.7%
#17746: fix(gateway): add shared-secret fallback to trusted-proxy auth disp...
by dashed · 2026-02-16
83.0%
#16310: fix(ws-connection): skip device pairing when client authenticates w...
by nawinsharma · 2026-02-14
81.5%
#23503: fix: preserve pairing state on device token mismatch + migrate lega...
by dorukardahan · 2026-02-22
81.4%
#17572: fix: make dangerouslyDisableDeviceAuth bypass device identity checks
by gitwithuli · 2026-02-15
81.4%
#19885: test(gateway,browser): isolate tests from ambient OPENCLAW_GATEWAY_...
by NewdlDewdl · 2026-02-18
80.9%
#23425: Gateway: require trusted-proxy allowlist unless allowAll is explicit
by bmendonca3 · 2026-02-22
80.8%
#23361: Gateway: reject scope assertions without identity binding
by bmendonca3 · 2026-02-22
80.7%
#22381: Security/Gateway: block cross-origin silent auto-pairing in auth mo...
by bmendonca3 · 2026-02-21
80.7%