#23425: Gateway: require trusted-proxy allowlist unless allowAll is explicit
docs
gateway
commands
size: M
trusted-contributor
Cluster:
Security Enhancements and Fixes
## Summary
- enforce trusted-proxy safe defaults by requiring `gateway.auth.trustedProxy.allowUsers` unless `gateway.auth.trustedProxy.allowAll=true`
- reject trusted-proxy requests at auth time when neither allowlist nor explicit allow-all is configured
- update security audit checks, trusted-proxy docs, and gateway configure flows so users must choose allowlist or explicit allow-all
## Validation
- `pnpm test src/gateway/auth.test.ts src/gateway/server-runtime-config.test.ts src/security/audit.test.ts`
- `pnpm test:e2e src/commands/configure.gateway-auth.e2e.test.ts src/commands/configure.gateway.e2e.test.ts`
- `pnpm tsgo`
- `pnpm check`
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
This PR strengthens trusted-proxy authentication security by requiring an explicit allowlist of users (`allowUsers`) or an explicit opt-in to allow all authenticated proxy users (`allowAll=true`). Previously, an empty `allowUsers` array would silently allow any authenticated proxy user, which could lead to unintended access.
**Key changes:**
- Added `allowAll` boolean field to trusted-proxy configuration as an explicit break-glass override
- Modified validation in `assertGatewayAuthConfigured` (src/gateway/auth.ts:311) to reject configurations missing both `allowUsers` and `allowAll=true`
- Added runtime enforcement in `authorizeTrustedProxy` (src/gateway/auth.ts:356-357) to reject requests when neither is configured
- Updated security audit to flag missing configuration as `critical` severity instead of `warn`
- Modified `configure gateway` interactive prompts to loop until user provides allowlist or explicitly confirms allow-all
- Updated all documentation and examples to include `allowUsers` configuration
- Comprehensive test coverage for new validation paths
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with minimal risk - it strengthens security defaults without breaking existing functionality
- The changes are well-implemented with defense-in-depth: validation at config assertion time (startup), runtime authorization checks, security audit updates, comprehensive test coverage including edge cases (missing allowlist, explicit allowAll, empty allowUsers), thorough documentation updates, and backward-compatible handling (existing configs with allowUsers continue working). The interactive configuration prevents users from accidentally creating insecure configurations.
- No files require special attention
<sub>Last reviewed commit: 61211ed</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#23355: Gateway: fail closed on untrusted proxy headers
by bmendonca3 · 2026-02-22
84.6%
#17705: fix(gateway): allow trusted-proxy auth to bypass device-pairing gates
by dashed · 2026-02-16
80.8%
#23364: Gateway: add risk-ack interlock for dangerous Control UI flags
by bmendonca3 · 2026-02-22
78.3%
#17378: fix(gateway): allow dangerouslyDisableDeviceAuth with trusted-proxy...
by ar-nadeem · 2026-02-15
78.0%
#21120: Security/Gateway: guard dangerous HTTP /tools/invoke re-enables
by bmendonca3 · 2026-02-19
77.6%
#7654: feat(security): zero-trust localhost auth with DNS rebinding protec...
by joncode · 2026-02-03
77.0%
#8513: Gateway: require auth for plugin HTTP
by coygeek · 2026-02-04
76.6%
#22766: fix(security): enable gateway auth rate limiting by default (CWE-307)
by brandonwise · 2026-02-21
76.5%
#21100: Security/Gateway: require explicit break-glass env for Control UI b...
by bmendonca3 · 2026-02-19
76.5%
#17746: fix(gateway): add shared-secret fallback to trusted-proxy auth disp...
by dashed · 2026-02-16
76.4%