feat(gateway): trust forwarded client IPs only from trusted proxies

CHANGELOG.md

@@ -6,6 +6,7 @@
 
 - Removed the distributable Kubernetes administrator `Secret` and historical placeholder credential. Production deployments must provision `waf-ids-ai-soc-admin` / `ADMIN_TOKEN` through the external secret-management control plane; the workload's `secretKeyRef` is explicitly non-optional.
 - Added a structural regression contract that rejects shipped administrator Secret objects, placeholder credentials, decoy workloads, init-container false positives, and optional administrator Secret references.
+- Forwarded client IP headers are now ignored unless the direct peer matches `TRUSTED_PROXY_CIDRS`. Trusted chains are parsed right to left, malformed chains fail closed to the peer address, and IPv4-mapped trusted peers normalize correctly before rate limiting and DNSBL attribution.
 
 ### Operations
 

docs/runbooks/operations.md

@@ -53,6 +53,23 @@ cargo run
 Health reports `credentials_source` (`file` / `env` / `none`) and
 `admin_auth_configured` (boolean) without exposing secret values.
 
+## Trusted proxy client IP attribution
+
+Forwarded client IP headers are untrusted by default. Gateway rate limiting,
+DNSBL matching, and event attribution use the direct peer address unless that
+peer matches `TRUSTED_PROXY_CIDRS`.
+
+```bash
+TRUSTED_PROXY_CIDRS=192.0.2.0/24,2001:db8::/32 \
+cargo run
+```
+
+When a peer is trusted, Wardnet parses the complete `X-Forwarded-For` chain
+from right to left and picks the first hop that is not itself a trusted proxy.
+If the header is absent, Wardnet may use `X-Real-IP` from that same trusted
+context. If any forwarded hop is empty or invalid, the whole chain is rejected
+and Wardnet falls back to the direct peer without consulting `X-Real-IP`.
+
 ## Health Check
 
 ```bash