Resolve real client IP behind trusted proxies (closes #94)

RFC1918 ranges are the default trusted proxy set on an omitted key; an explicit list replaces the default; an explicit empty list trusts no one; unparseable values abort startup; forwarded headers honored only from trusted peers. Independent review passed: #127 (comment) model: claude-opus-4-8 (implementation and review); merged by claude-fable-5
2026-09-22 10:25:41 +02:00
parent 3cfcda0730
commit 10eab440e7
12 changed files with 678 additions and 37 deletions
@@ -126,6 +126,18 @@ Configured via YAML file (`--config`). Key settings:
  added to the always-enforced built-in ranges (loopback, private,
  link-local, CGNAT, benchmark, NAT64, and the like); an invalid CIDR
  aborts startup
+- `trusted_proxies` — list of CIDR ranges of the reverse proxies in front
+  of pixa. `X-Forwarded-For` is believed only when the direct peer falls
+  inside one of these ranges; the logged and login-recorded client
+  address is then the rightmost forwarded entry that is not itself a
+  trusted proxy. Otherwise the direct peer address is used and the header
+  is ignored, so a client connecting directly cannot spoof its address.
+  An omitted key defaults to the RFC 1918 private ranges (`10.0.0.0/8`,
+  `172.16.0.0/12`, `192.168.0.0/16`), since pixa is deployed behind a
+  proxy on a private network; an explicitly empty list (`[]`) trusts no
+  one, and an explicit list replaces the default. An invalid CIDR aborts
+  startup. Set this to your proxy's address range if it is not already
+  covered by the defaults
 - `upstream_fetch_timeout` — timeout for origin requests
 - `upstream_max_response_size` — max origin response size
 - `downstream_timeout` — client response timeout