…ration

Fixes three gaps surfaced by the PR #967 review (failing tests added in the
previous commit now pass):

1. v4-mapped IPv6 in XFF escaping a v4 trusted prefix. netip.Prefix.Contains
   returns false for ::ffff:a.b.c.d checked against a.b.c.0/N, so an attacker
   able to inject the v4-mapped form of an internal address could escape the
   trust list. Fix: a single parseHeaderAddr helper Unmap()s before the
   prefix check and before storage. Applied uniformly in
   ClientIPFromHeader, the rightmost-untrusted XFF walk, and the
   ClientIPFromXFFTrustedProxies slot lookup.

2. Zoned IPv6 in XFF escaping a v6 trusted prefix. netip.Prefix.Contains
   returns false for any zoned IP, and zone identifiers carry no meaning
   across the network, so an attacker-injected zone suffix bypassed the
   trust check. Fix: parseHeaderAddr strips zones via WithZone("") at
   parse time; zones are by definition not valid in header-sourced IPs.

3. ClientIPFromRemoteAddr returning ::ffff:a.b.c.d for v4 clients on
   dual-stack listeners, splitting one logical client into two
   rate-limit / log / ACL keys. Fix: Unmap() before storing. Zone is
   preserved here because RemoteAddr can legitimately be link-local.

Also:
- Pre-canonicalize the user-supplied header name in ClientIPFromHeader
  at construction time, matching the realip.go pattern and saving a
  per-request canonicalization on the hot path. A package-level
  xForwardedForHeader constant documents the canonical XFF spelling.
- Per-function godoc explicitly notes the v4-mapped folding and zone
  stripping so downstream callers understand the normalization contract.
- New regression-pin tests: empties don't shift the
  ClientIPFromXFFTrustedProxies slot index; positive normalization tests
  for v4-mapped and zoned inputs in each entry point.
- README: deprecate the RealIP row, add ClientIPFrom* entries, and
  introduce a "Choosing a ClientIP middleware" section with copy-paste
  recipes for the common deployments (direct internet, Cloudflare,
  CloudFront, dynamic-IP proxy pools).

Co-authored-by: Cursor <cursoragent@cursor.com>

PR #967 Copilot review: the previous implementation read the trusted
single-IP header with r.Header.Get(header), which returns only the first
value. If the trusted header reaches us with multiple values -- a
client-supplied "spoofed" entry plus the proxy's real entry, or two
proxy-set entries because of upstream chain quirks -- we surfaced the
attacker-controlled first value.

Switch to r.Header.Values(header) and take the LAST entry. The last value
is the one added by the hop closest to us in the chain, which is by
definition the most trusted (the rightmost-untrusted principle we already
apply to X-Forwarded-For). Fail-closed on garbage at the last position:
we do NOT fall back to earlier values, as those came from less-trusted
hops further from us.

Correctly configured proxies (single value, proxy overwrites instead of
appends) are unaffected -- len(values)==1, so first == last == that value.

The four cases pinned in the previous commit's
TestClientIPFromHeader_MultiValueLastWins now pass:

  - attacker_then_proxy        (last value wins)
  - three_values_last_wins     (last value wins)
  - last_unparseable_no_fallback (fail-closed)
  - last_empty_no_fallback     (fail-closed)

Existing ClientIPFromHeader tests stay green. Godoc updated with one
short paragraph naming the multi-value contract.

Co-authored-by: Cursor <cursoragent@cursor.com>

PR #967 Copilot review claimed walkXFF is O(n^2) in the number of XFF
entries because it calls strings.LastIndexByte on progressively shorter
substrings, and suggested a DoS-prone CPU cost on attacker-supplied
large XFF headers.

Benchmark refutes the claim. walkXFF is strictly O(M) in total chain
length M -- linear in the entry count n, near-constant for the
single-trusted-hop case (visitor returns true on the first entry).

BenchmarkWalkXFF (visitor walks every entry, worst case for
ClientIPFromXFF when all entries are inside trusted prefixes):

  n=1        5.6 ns/op
  n=10      57.6 ns/op       (5.8 ns/entry)
  n=100    541.1 ns/op       (5.4 ns/entry)
  n=1000   5228   ns/op      (5.2 ns/entry)
  n=10000  55148  ns/op      (5.5 ns/entry)

BenchmarkWalkXFF_RightmostStop (visitor stops at the first entry, the
common case for ClientIPFromXFF with no trusted prefixes and
ClientIPFromXFFTrustedProxies(1)):

  n=1      5.2 ns/op
  n=10     6.0 ns/op
  n=100    6.1 ns/op
  n=1000   6.1 ns/op
  n=10000  6.1 ns/op  -- truly constant

Why the analysis is O(M): strings.LastIndexByte scans BACKWARD from the
end of its input and stops at the first match. After we slice off the
rightmost entry, the next call only scans up to the next comma -- O(L)
where L is that entry's length. Sum over n iterations is O(n*L) = O(M).
On arm64/amd64 it's also SIMD-optimized in the Go runtime, so a
hand-rolled byte loop would lose, not win.

Benchmark stays in the codebase as a regression pin: any future
refactor that accidentally drops back to O(n^2) gets caught here.
Zero allocations preserved across both shapes.

Co-authored-by: Cursor <cursoragent@cursor.com>

…-continue

PR #967 Copilot review: the godoc said "Calling with no arguments returns
the rightmost parseable XFF IP", implying skip-and-continue past garbage.
That phrasing predates the fail-closed change in 5dd2243; the actual
behavior is now "try the rightmost; if it doesn't parse, no IP is set".
Update the line to match.

Co-authored-by: Cursor <cursoragent@cursor.com>

PR #967 fresh review: the inline comment summarizing the XFF middleware
said it "walks right-to-left, skipping trusted entries" but stopped
short of mentioning the fail-closed-on-garbage contract that landed in
5dd2243. Add three words to match the godoc.

Co-authored-by: Cursor <cursoragent@cursor.com>

PR #967 Copilot review: the godoc on this test still described the
pre-fix behavior in present tense ("Today we surface values[0]"), even
though a8e3dbf already switched the implementation to read
r.Header.Values() and use the last entry.

Reword the godoc to frame the test as a regression pin for the gap
fixed in a8e3dbf -- past-tense bug description, present-tense
post-fix contract. Same body, same test cases, same assertions.

Co-authored-by: Cursor <cursoragent@cursor.com>

PR #967 Copilot review: the BenchmarkWalkXFF godoc referenced
rightmostUntrustedXFF, an internal helper that was consolidated into
the single walkXFF primitive back in 1863339 and no longer exists in
the package. Rename the reference to ClientIPFromXFF (the public
caller whose worst case this benchmark actually exercises). No code
change.

Co-authored-by: Cursor <cursoragent@cursor.com>