fix(ratelimit): canonicalise client keys — IPv6 /64 + mapped-v4 unification (FIX-RLKEY)

[vanlongme]

Summary

• internal/ratelimit.canon now Unmap()s every parseable address before rendering, so the IPv4-mapped spellings (::ffff:a.b.c.d, 0:0:0:0:0:ffff:a.b.c.d) land on the single native v4 key — a dual-stack client can no longer double its budget by switching family spelling.
• IPv6 client keys fold to the /64 prefix (rendered as the masked base address): temporary/privacy-address rotation or deliberate /128-hopping inside the prefix one subscriber controls now draws one budget. IPv4 stays per-/32. /64 is the smallest prefix an end site is delegated, hence the finest granularity a single client can still rotate inside. Consequence: all hosts inside one shared /64 — a LAN segment, subscribers an ISP delegates a single prefix to — share one rate-limit budget.
• The fold applies to rate-limit keys only. One selection feeds two renders: ClientKey (folded key) and the new ClientAddr (unmapped but unfolded real address). The gateway's forwarded-header rebuild (X-Forwarded-For/Forwarded/X-Real-IP toward the runtime, S18) uses ClientAddr, so the runtime still sees the client's exact address — TestProxy_IPv6ForwardsExactAddrKeyFolds pins the split.
• The socket-peer paths canonicalise too, so a direct (unproxied) IPv6 client keys identically to an XFF-derived one. The same key string keys the local buckets and the shared Postgres window rows end to end — TestShared_IPv6WindowAndLocalShareKey pins that.
• Docs: chart README + values.yaml and docs/runbooks/capacity.md describe the canonicalisation, the shared-/64 budget consequence, and the edge invariant (the right-most-untrusted XFF entry is only meaningful when every proxy hop in front is in -trusted-proxies — a pass-through trusted hop hands the key to client bytes; dual-stack edges must list their IPv6 ranges). docs/security/threat-model.md S14 residual updated.
• One-time key-format change on upgrade, no migration: IPv6 window rows move from per-address to per-/64 keys (IPv4 keys unchanged). Rows under the old format expire inside their minute window; an IPv6 client mid-window at upgrade time gets at most one fresh window's budget.

Regression test (fails on v0.5.0, passes here)

go test ./internal/ratelimit/ -run 'TestClientKey_IPv6FoldedTo64|TestClientKey_MappedFormsUnified|TestShared_IPv6WindowAndLocalShareKey' -v

On v0.5.0 all three fail (per-/128 keys, ::ffff: split from native v4); with this change all pass. Verified: go build ./..., gofmt clean, go vet, go test -race ./internal/ratelimit/, plus the ./internal/gateway/ and ./internal/api/ suites and a 25 s FuzzClientKey run.

Test plan

• v6 addresses in one /64 share a bucket; different /64s do not (peer + XFF paths)
• ::ffff:v4 == native v4 (XFF + socket peer)
• window + local bucket share the key string
• gateway forwards the exact v6 address while the limiter key is the /64 base
• regression fails on v0.5.0
• CI

Diff stat vs origin/main

 deploy/helm/tinycdi/README.md        | 27 +++++++++++++-
 deploy/helm/tinycdi/values.yaml      |  7 ++--
 docs/runbooks/capacity.md            | 28 +++++++++++++--
 docs/security/threat-model.md        |  2 +-
 internal/gateway/forwarded_test.go   | 44 +++++++++++++++++++++++
 internal/gateway/proxy.go            | 10 +++---
 internal/ratelimit/fuzz_test.go      |  2 +-
 internal/ratelimit/ratelimit.go      | 63 ++++++++++++++++++++++++++++----
 internal/ratelimit/ratelimit_test.go | 69 ++++++++++++++++++++++++++++++++++++
 internal/ratelimit/shared_test.go    | 39 ++++++++++++++++++++
 10 files changed, 272 insertions(+), 19 deletions(-)

Generated with Devin

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.