fix: rate limiting X-Real-IP from the real peer

features/trusted_proxy_client_ip_for_rate_limiting.qa.md

@@ -0,0 +1,70 @@
+# QA procedure: trusted_proxy_client_ip_for_rate_limiting
+
+Package: `test` (black-box), extending `test/login_and_password_reset_rate_limiting_http_test.go`'s
+setup (`mockUserRepo`, `stubHasher`, `mockMailRepo`, the full `useCases` set, `auth.NewHandler(...)`).
+
+## Test infrastructure additions needed first
+
+1. Implement `api/middleware.TrustedProxyRealIP(trustedProxies []string) func(http.Handler) http.Handler`.
+2. In tests, build a `chi.NewRouter()` mirroring `NewAuthRouter`'s `/login` and `/password-reset`
+   groups: `middleware.TrustedProxyRealIP(trustedProxies)` then
+   `middleware.NewRateLimiter(maxAttempts, window)` then the handler. `chimiddleware.RealIP` is not
+   part of this router.
+3. Simulate a request's connection address by setting `req.RemoteAddr = "<ip>:<port>"` (host:port,
+   matching real request shape) before calling the router. Simulate a proxy-forwarded header with
+   `req.Header.Set("X-Real-IP", "<ip>")` or `req.Header.Set("X-Forwarded-For", "<ip>")` as needed.
+
+## Setup shared by every case
+
+4. Call `validator.InitValidator()` once.
+5. Build `mockUserRepo`, `mockMailRepo`, `stubHasher`, and the full `useCases` set, then
+   `auth.NewHandler(...)`.
+6. Use `AUTH_RATE_LIMIT_MAX_ATTEMPTS=1` and a window covering the whole test
+   (`window=time.Hour`) throughout, so a second request from the same effective key is always the
+   one that trips 429 and no scenario needs to wait out a window.
+7. Seed `mockUserRepo` with user "alice", a correct password hash, so `POST /v1/auth/login` can
+   return 200 where a scenario needs a non-429, non-403 baseline; a wrong-password body works
+   equally well to prove "not rejected by rate limiting" since only the status code being not 429
+   matters for these cases (assert `!= 429` in addition to whatever status login returns for the
+   given credentials).
+
+## HTTP-level checks
+
+8. `trustedProxies = nil` (empty). Send `POST /v1/auth/login` with `RemoteAddr = "203.0.113.5:1"`
+   and header `X-Real-IP: 198.51.100.1`. Assert the response is not `429`. Send a second, identical
+   request (same `RemoteAddr`, same header). Assert it is `429` — proves the header had no effect;
+   both requests hit the connection-address counter.
+9. `trustedProxies = ["10.0.0.1"]`. Send `POST /v1/auth/login` with `RemoteAddr = "203.0.113.5:1"`
+   (not in the trusted list) and header `X-Real-IP: 1.1.1.1`. Assert not `429`. Send a second
+   request from the same `RemoteAddr` with header `X-Real-IP: 2.2.2.2` (a different value). Assert
+   it is `429` — proves an untrusted source can't split its own attempts across counters by varying
+   the header.
+10. `trustedProxies = ["10.0.0.1"]`. Send `POST /v1/auth/login` with `RemoteAddr = "10.0.0.1:1"` and
+    header `X-Real-IP: 198.51.100.9`. Assert not `429`. Send a second request with the same
+    `RemoteAddr` and the same header. Assert `429` — proves the trusted proxy's forwarded client is
+    honored as the counter key.
+11. `trustedProxies = ["10.0.0.1"]`. Send `POST /v1/auth/login` with `RemoteAddr = "10.0.0.1:1"` and
+    header `X-Real-IP: 198.51.100.9`, consuming that forwarded client's limit (assert not `429`).
+    Then send a second request with the same `RemoteAddr` but header `X-Real-IP: 198.51.100.10`.
+    Assert not `429` — a different forwarded client behind the same trusted proxy has its own
+    counter.
+12. `trustedProxies = ["10.0.0.1"]`. Send `POST /v1/auth/login` with `RemoteAddr = "10.0.0.1:1"` and
+    header `X-Forwarded-For: 198.51.100.9` (no `X-Real-IP`). Assert not `429`. Send a second,
+    identical request. Assert `429` — proves `X-Forwarded-For` is never read, even from a trusted
+    proxy; both requests are keyed on the proxy's own address `10.0.0.1`.
+13. `trustedProxies = ["10.0.0.1"]`. Send `POST /v1/auth/login` with `RemoteAddr = "10.0.0.1:1"` and
+    no forwarding header at all. Assert not `429`. Send a second, identical request. Assert `429` —
+    a trusted proxy with nothing to forward falls back to its own address as the key.
+
+## Manual verification (not exercised by the Go test)
+
+- Real behaviour behind the documented nginx and Caddy reverse proxies (`docs/deployment.md`) —
+  that each sets `X-Real-IP` from the actual peer address rather than a client-controlled value,
+  and that `TRUSTED_PROXIES` on the RenewCMS host is set to the proxy's real address (e.g.
+  `127.0.0.1` when co-located) — is not exercised by an in-process `httptest` router and should be
+  checked by hand against a real reverse-proxy deployment.
+- `config.NewSettingsFromEnv` parsing `TRUSTED_PROXIES` from the environment (semicolon-separated,
+  matching `CORS_ALLOWED_ORIGINS`) is a use-case-free config concern; if a pure Go test for
+  `internal/infrastructure/config` already exists for `CORS_ALLOWED_ORIGINS`
+  (`test/runtime_settings_from_env_test.go`), extend it with a parallel case rather than adding it
+  here — flagged for the coder/qa stage to place correctly.