og/docs/RELEASE-VERIFICATION-CHECKPOINT-22.md

Checkpoint 22 — IP-bypass / trusted-proxy hardening

Date: 2026-09-08

Security issue addressed

Before checkpoint 22, Authenticator.Authenticate evaluated auth.ip_bypass against the fully resolved client IP. If the immediate peer was in auth.trusted_proxies, that address could originate from X-Forwarded-For. A deployment that trusted a broad reachable subnet could therefore allow a direct client in that subnet to present a bypass address such as 127.0.0.1.

New default

• ClientIP() still resolves trusted forwarding chains for observability.
• auth.ip_bypass is evaluated against the direct TCP peer by default.
• Identity.ClientIP remains the resolved client address for usage/logging.
• Legacy forwarded-IP bypass is available only with explicit auth.ip_bypass_use_forwarded_ip=true.
• Config preflight warns when forwarded bypass is enabled and when auth.trusted_proxies contains broad non-loopback CIDRs.

API-key and OIDC authentication semantics are unchanged. No persistent-state schema change is introduced.

Regression coverage

Tests prove that:

1. a trusted peer with X-Forwarded-For: 127.0.0.1 cannot satisfy loopback IP bypass by default,
2. forwarded client-IP resolution still reports 127.0.0.1 for observability in that test,
3. explicit compatibility mode restores forwarded-IP bypass,
4. a direct loopback peer still satisfies the normal loopback bypass,
5. preflight warns on compatibility mode and a broad 10.0.0.0/8 trusted-proxy range while not flagging loopback-only proxy ranges.

Built-binary spoof E2E

A release Linux-amd64 gateway was started with a trusted loopback proxy peer and an IP-bypass rule for 192.0.2.123/32.

With the new default (ip_bypass_use_forwarded_ip=false), a request from the trusted TCP peer carrying X-Forwarded-For: 192.0.2.123 returned 401 Unauthorized.

The same test with the explicit compatibility flag set to true returned 200 OK with an ip-bypass admin identity and resolved client_ip=192.0.2.123. This proves both the secure default and the intentional compatibility escape hatch in the release binary.

Production-config preflight

The user's two-worker configuration validates successfully with the checkpoint-22 candidate. Preflight reports broad trusted-proxy warnings for 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16; these no longer permit forwarded headers to satisfy IP bypass under the default, but should still be narrowed to improve client-IP attribution integrity.