#9421: Trusted proxies + auto-pairing for reverse proxy deployments
gateway
Cluster:
Gateway Resilience and Configuration
## Summary
Extends `gateway.trustedProxies` configuration to support wildcard (`*`), single IP, and CIDR range entries. Adds `skipDevicePairingForTrustedProxy` option to auto-approve device pairing for authenticated requests through trusted proxies.
## Motivation
Reverse-proxy deployments frequently fail pairing when trusted proxy detection is too strict. This makes proxy trust more reliable and allows automatic pairing when the proxy is trusted.
## How It Works
1. Parse `trustedProxies` as wildcards and CIDR ranges
2. Normalize entries (strip `:port`) before CIDR checks
3. If request is from trusted proxy, optionally bypass device pairing
## Flow
```mermaid
sequenceDiagram
participant Client
participant Proxy
participant Gateway
Client->>Proxy: WS/HTTP request
Proxy->>Gateway: X-Forwarded-For + request
Gateway->>Gateway: trustedProxies check (wildcard/CIDR)
alt trusted + skipDevicePairingForTrustedProxy
Gateway->>Gateway: auto-approve pairing
else not trusted
Gateway->>Gateway: normal pairing flow
end
```
## Key Code Changes
1. **CIDR Matching (`src/gateway/net.ts`):**
- `parseIPv4Octets()` - Parses IPv4 into octet array
- `ipv4ToNumber()` - Converts IPv4 to 32-bit integer for bitwise operations
- `matchesCidr(ip, cidr)` - Returns true if IP falls within CIDR range
- `matchesProxyEntry(ip, proxy)` - Handles wildcard, CIDR with stripped ports, and exact IP match
- Updated `isTrustedProxyAddress()` - Supports `*` wildcard and CIDR entries
2. **Auto-Approval Logic (`src/gateway/server/ws-connection/message-handler.ts`):**
- New `shouldAutoApproveForTrustedProxy` flag checks:
- `config.gateway.auth.skipDevicePairingForTrustedProxy === true`
- Request comes from trusted proxy (`remoteIsTrustedProxy`)
- Valid shared auth (token or password)
- Sets `silent: true` on device pairing when auto-approval conditions met
3. **Config Schema (`src/config/types.gateway.ts`, `src/config/zod-schema.ts`):**
- New `GatewayAuthConfig.skipDevicePairingForTrustedProxy?: boolean`
## Port Stripping
Handles malformed entries like `"192.168.0.0/16:1234"` by stripping port after CIDR prefix length.
Most Similar PRs
#8752: fix: add CIDR notation support for trustedProxies config
by revenuestack · 2026-02-04
75.4%
#17705: fix(gateway): allow trusted-proxy auth to bypass device-pairing gates
by dashed · 2026-02-16
70.0%
#17746: fix(gateway): add shared-secret fallback to trusted-proxy auth disp...
by dashed · 2026-02-16
69.6%
#23425: Gateway: require trusted-proxy allowlist unless allowAll is explicit
by bmendonca3 · 2026-02-22
68.2%
#23355: Gateway: fail closed on untrusted proxy headers
by bmendonca3 · 2026-02-22
67.5%
#18441: feat(gateway): add localNetworks config for subnet-scoped auto-pairing
by JayMishra-source · 2026-02-16
66.7%
#17378: fix(gateway): allow dangerouslyDisableDeviceAuth with trusted-proxy...
by ar-nadeem · 2026-02-15
63.9%
#21305: Fix/proxy-ip-allow-list
by janaka · 2026-02-19
62.9%
#7654: feat(security): zero-trust localhost auth with DNS rebinding protec...
by joncode · 2026-02-03
61.4%
#15564: fix: webchat messages disappear during concurrent session activity
by Automatedcapitalist · 2026-02-13
61.3%