docs: deployment recipe + verify checklist for ClientIPFromXFFTrustedProxies

Replace the counting prose and ASCII diagram with a recipe table mapping
common deployments to numTrustedProxies values, plus a "verify with a
known IP" step. Steer users toward ClientIPFromXFF with explicit CIDRs
(added pointers to CDN-published IP lists from Cloudflare, AWS, Fastly,
GCP) since CIDR-based trust cannot off-by-one. Add one fail-closed test
case.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: VojtechVitek

README.md

@@ -464,6 +464,11 @@ is folded to plain IPv4, and IPv6 zone identifiers carried in headers are
 stripped, so one logical client maps to a single canonical key for logs,
 rate limits, and ACLs.
 
+For `ClientIPFromXFFTrustedProxies`, `numTrustedProxies` is the total proxy
+hops between client and server. Prefer `ClientIPFromXFF` with explicit CIDRs
+when you can — CIDR-based trust cannot off-by-one. See the godoc for a
+deployment recipe and a verify checklist.
+
 See the per-function godoc for the full semantics of each middleware, and
 [adam-p's "The perils of the 'real' client IP"](https://adam-p.ca/blog/2022/03/x-forwarded-for/)
 for the underlying threat model.

middleware/client_ip.go

@@ -62,7 +62,14 @@ func ClientIPFromHeader(trustedHeader string) func(http.Handler) http.Handler {
 // set (fail-closed) — we can't safely trust anything left of garbage.
 //
 // Use this when you sit behind one or more reverse proxies whose IP ranges
-// you can enumerate as CIDRs:
+// you can enumerate as CIDRs. Most CDNs publish their IPs:
+//
+//	Cloudflare:   https://www.cloudflare.com/ips/
+//	AWS:          https://ip-ranges.amazonaws.com/ip-ranges.json
+//	Fastly:       https://api.fastly.com/public-ip-list
+//	Google Cloud: https://www.gstatic.com/ipranges/cloud.json
+//
+// Example (CloudFront):
 //
 //	r.Use(middleware.ClientIPFromXFF(
 //	    "13.32.0.0/15",   // CloudFront IPv4
@@ -109,30 +116,34 @@ func ClientIPFromXFF(trustedIPPrefixes ...string) func(http.Handler) http.Handle
 	}
 }
 
-// ClientIPFromXFFTrustedProxies stores the client IP read from the
-// X-Forwarded-For header, given the exact number of trusted reverse proxies
-// between this server and the public internet. It returns the IP at position
-// len(xff) - numTrustedProxies in the merged X-Forwarded-For list — the IP
-// added by the outermost of your trusted proxies, the only IP in the chain
-// that none of your proxies have allowed an attacker to forge. Read it with
-// [GetClientIP].
+// ClientIPFromXFFTrustedProxies stores the client IP read from
+// X-Forwarded-For, given the exact number of trusted reverse proxies
+// between this server and the public internet. Read it with [GetClientIP].
+//
+// PREFER [ClientIPFromXFF] with explicit CIDRs whenever you can — it
+// cannot off-by-one and is robust to architecture changes. Most CDNs
+// publish their IP ranges (Cloudflare, AWS, Fastly, Google Cloud). Use
+// this counting variant only when proxy IPs are dynamic and unpublishable.
+//
+// numTrustedProxies = total proxy hops between the client and this server.
+// Count every hop in the request path:
 //
-// Use this when:
-//   - You know exactly how many proxies you sit behind, AND
-//   - Their IP addresses are dynamic (autoscaling proxy pools, ephemeral
-//     containers, dynamic CDN edges) so listing CIDRs with [ClientIPFromXFF]
-//     is impractical.
+//	Single proxy (one LB / nginx / Heroku / Fly.io / Render) ....... 1
+//	Two proxies  (Cloudflare → ALB, CloudFront → ALB) .............. 2
+//	Three proxies (CDN → API gateway → LB) ......................... 3
 //
-// WARNING: This variant is brittle to network architecture changes. If you
-// add or remove a proxy level, numTrustedProxies silently becomes wrong and
-// you may start trusting an attacker-supplied IP. Prefer [ClientIPFromXFF]
-// with explicit trusted CIDRs whenever you can.
+// VERIFY BEFORE GOING LIVE: send a request from a known IP and confirm
+// [GetClientIP] returns that IP. If it returns a proxy IP, your count is
+// too LOW — a client can spoof their IP, fix immediately. If it returns
+// "", your count is too HIGH — no leak, but no client IP either.
 //
-// If the XFF chain has fewer than numTrustedProxies entries (header missing
-// or architecture changed), no client IP is set and [GetClientIP] returns "".
+// This middleware reads ONLY X-Forwarded-For; it does not inspect
+// r.RemoteAddr. Guarantee at the network layer (security group / firewall)
+// that only your proxies can reach this server.
 //
-// Like [ClientIPFromXFF], v4-mapped IPv6 folds to plain v4 and IPv6 zones
-// are stripped before storage.
+// If the XFF chain has fewer than numTrustedProxies entries, no client IP
+// is set (fail-closed). Like [ClientIPFromXFF], v4-mapped IPv6 folds to v4
+// and IPv6 zones are stripped before storage.
 //
 // Panics at startup if numTrustedProxies < 1.
 func ClientIPFromXFFTrustedProxies(numTrustedProxies int) func(http.Handler) http.Handler {

middleware/client_ip_example_test.go

@@ -77,3 +77,32 @@ func Example_clientIP() {
 	fmt.Print(w.Body.String())
 	// Output: 198.51.100.42
 }
+
+// Example_clientIPFromXFFTrustedProxies shows that with two proxies the
+// client sits at XFF[len-2] and any client-prepended entries to the left of
+// that position are ignored.
+func Example_clientIPFromXFFTrustedProxies() {
+	r := chi.NewRouter()
+	r.Use(middleware.ClientIPFromXFFTrustedProxies(2)) // P1 (inner) + P2 (outer).
+	r.Get("/", func(w http.ResponseWriter, r *http.Request) {
+		fmt.Fprintln(w, middleware.GetClientIP(r.Context()))
+	})
+
+	// Each chain ends in "<client>, <P1>"; P2's address is in RemoteAddr,
+	// not in X-Forwarded-For. Leading entries are client-controlled.
+	for _, xff := range []string{
+		"109.81.118.93, 3.172.119.73",
+		"8.8.8.8, 109.81.118.93, 3.172.119.73",
+		"8.8.8.8, 8.8.8.8, 8.8.8.8, 109.81.118.93, 3.172.119.73",
+	} {
+		req := httptest.NewRequest("GET", "/", nil)
+		req.Header.Set("X-Forwarded-For", xff)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+		fmt.Print(w.Body.String())
+	}
+	// Output:
+	// 109.81.118.93
+	// 109.81.118.93
+	// 109.81.118.93
+}

middleware/client_ip_test.go

@@ -196,8 +196,10 @@ func TestClientIPFromXFFTrustedProxies(t *testing.T) {
 
 		// XFF shorter than N: no IP set. This is intentionally fail-closed so a
 		// proxy-count mismatch doesn't silently fall through to attacker-controlled
-		// values.
+		// values. The index len(xff)-N is negative/out-of-range here; the walk
+		// must never panic or wrap around to an entry the client controls.
 		{"shorter_than_n", 3, []string{"1.1.1.1, 2.2.2.2"}, ""},
+		{"single_entry_n_two", 2, []string{"2.2.2.2"}, ""},
 		{"missing_header", 1, nil, ""},
 
 		// Spoofing: prepended attacker values are to the LEFT of the chosen