#22343: fix(gateway): treat private LAN hosts as local direct
gateway
size: XS
Cluster:
Gateway Resilience and Configuration
## Summary
- Allow `isLocalDirectRequest` to treat private/LAN addresses as local-direct when the request is otherwise trusted.
- Keep pairing bypass compatible with LAN-hosted gateway URLs (for example `wss://192.168.4.213:18789`).
- Add unit coverage for private-host and proxy-header edge cases in `src/gateway/auth.test.ts`.
## Why this fixes the issue
Sub-agent local URLs are built as WAN-safe private IP WebSocket URLs when `gateway.bind=lan`. Previously, local-direct detection only accepted loopback, which incorrectly marked LAN host connections as remote and forced pairing. This change accepts private/LAN origins for local-direct intent while preserving remote/public protections.
## Exact tests run
- `pnpm vitest run --config vitest.config.ts src/gateway/auth.test.ts`
- `pnpm vitest run --config vitest.config.ts src/gateway/auth.test.ts src/gateway/net.test.ts`
## Edge cases
- Forwarded headers disable local-direct unless the socket is trusted via `gateway.trustedProxies`.
- Public/non-private clients continue to be treated as non-local and still require normal pairing flow.
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Expanded local-direct detection to treat private LAN client IPs and hostnames as local, enabling silent pairing for same-host/LAN sub-agent connections. Previously only loopback addresses were considered local, causing LAN-bound gateway URLs (e.g., `192.168.1.213:18789`) to require pairing even when accessed from the local network.
**Key changes:**
- `isLocalDirectRequest` now uses `isPrivateOrLoopbackAddress` instead of `isLoopbackAddress` for client IP validation
- Host validation expanded from hardcoded `localhost`/`127.0.0.1`/`::1` to include any private IP address
- Preserves proxy header validation - forwarded headers from untrusted sources still block local-direct treatment
**Security posture:** The change correctly expands the trust boundary to include RFC1918 private networks while maintaining existing safeguards against header spoofing.
<h3>Confidence Score: 5/5</h3>
- Safe to merge - well-tested expansion of local-direct detection to LAN deployments with proper security boundaries maintained
- The implementation correctly expands local detection to private networks while preserving all security checks. The change leverages existing, well-tested `isPrivateOrLoopbackAddress` helper (40 test cases in net.test.ts). The three new test cases validate the key scenarios: private-to-private requests are local, public-to-private with untrusted proxy headers are rejected, and trusted proxy forwarding works correctly. The logic maintains defense-in-depth by requiring both client IP and host to be private/local, and still validates proxy header trust.
- No files require special attention
<sub>Last reviewed commit: a9bb584</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#19026: fix(gateway): use loopback for local CLI-to-gateway connections
by Phineas1500 · 2026-02-17
82.5%
#21697: fix(gateway): unblock local spawn pairing and gated private-LAN ws
by rjuanluis · 2026-02-20
81.9%
#18441: feat(gateway): add localNetworks config for subnet-scoped auto-pairing
by JayMishra-source · 2026-02-16
81.7%
#22056: fix(gateway): use loopback for self-connections regardless of bind ...
by usedhonda · 2026-02-20
80.3%
#22365: fix(gateway): auto-approve loopback scope upgrades
by AIflow-Labs · 2026-02-21
80.1%
#21436: fix(gateway): plaintext ws:// blocked for Docker bind=lan (SECURITY...
by xinhuagu · 2026-02-19
78.7%
#22712: fix(gateway): auto-approve all device pairing for localhost connect...
by NewdlDewdl · 2026-02-21
78.2%
#23708: fix(gateway): auto-approve scope upgrades for loopback clients
by widingmarcus-cyber · 2026-02-22
77.3%
#22110: fix(tools): prefer loopback for internal tool-to-gateway RPC calls
by pierreeurope · 2026-02-20
76.3%
#22347: Feature request: gateway.clientUrl config to decouple client URL
by AIflow-Labs · 2026-02-21
76.1%