Bucket IPv6 rate-limit keys by /64 (closes #125)

Rate-limit keys were per-address, i.e. per /128 for IPv6. A routed /64
is the normal residential and mobile allocation, so a client rotated
source addresses inside its own prefix and minted a fresh bucket per
request — evading every limiter at the network layer, with no spoofing
and nothing to detect. #88 closed the header half of this control; this
is the network half.

IPv6 now keys on the /64, IPv4 on the full address, via stdlib
net/netip. IPv4-mapped form is unmapped rather than masked, so clients
behind a mapping proxy do not collapse into one bucket.

Independently reviewed twice. The first round found the trusted-proxy
forwarded path — the one carrying production traffic — had no coverage
at all, so a silent revert there was undetectable; that is now pinned.
The reviewer confirmed both branches are independently mutation-tested:
reverting either the direct-peer return or the forwarded return alone
fails only that branch's tests. The 18-site test-constant refactor was
verified byte-identical against next, with no pre-existing assertion
changed.

Known remaining coverage gap, judged not a defect: the fallback when the
peer is trusted but the forwarded address does not parse has no test.
Only operator-controlled addresses inside TRUSTED_PROXIES reach it, they
already share the proxy's single bucket, and masking there can only
merge operator proxies — fail-closed, nothing attacker-controlled.

internal/middleware/ratelimit.go

@@ -48,6 +48,12 @@ const (
 	// bound every request pays a walk proportional to whatever the
 	// client sent.
 	maxForwardedHops = 64
+
+	// ipv6BucketBits is the prefix length IPv6 clients are bucketed
+	// on. A routed /64 is the normal residential and mobile
+	// allocation, so it is the unit an attacker gets addresses in
+	// and therefore the unit worth limiting.
+	ipv6BucketBits = 64
 )
 
 // normalizeAddr strips the IPv4-in-IPv6 wrapper and any zone from
@@ -56,6 +62,40 @@ func normalizeAddr(addr netip.Addr) netip.Addr {
 	return addr.Unmap().WithZone("")
 }
 
+// bucketKey is the rate-limit bucket identity of a client address.
+// IPv4 keys on the full address; IPv6 keys on its /64 prefix,
+// because keying IPv6 per /128 lets one ordinary subscriber rotate
+// source addresses inside its own routed /64 and mint a fresh bucket
+// per request — evading every limiter here at the network layer,
+// with no spoofing and nothing to detect.
+//
+// An IPv4-mapped address (::ffff:1.2.3.4) is keyed as the IPv4
+// address it carries, never masked to a /64: mapped form all shares
+// the ::ffff:0:0/96 prefix, so masking would collapse every IPv4
+// client reaching a proxy that emits it into one bucket. Callers
+// pass addresses through normalizeAddr, which already unmaps; the
+// unmap here keeps the property true of the key function itself.
+//
+// The two families cannot collide: an IPv4 key is a bare dotted
+// quad, and an IPv6 key always carries a "/64" suffix.
+func bucketKey(addr netip.Addr) string {
+	addr = addr.Unmap()
+
+	if addr.Is4() {
+		return addr.String()
+	}
+
+	// Prefix errors only on a negative bit count, on over 32 bits
+	// for an IPv4 address, or on over 128 for IPv6. The count here
+	// is the constant 64 and the IPv4 case returned above, so the
+	// error is unreachable. (The zero Addr does not error either: it
+	// yields the zero Prefix. Neither call site can produce one,
+	// since both parse the address first.)
+	prefix, _ := addr.Prefix(ipv6BucketBits)
+
+	return prefix.String()
+}
+
 // isTrustedProxy reports whether addr belongs to a network the
 // operator listed in TRUSTED_PROXIES. The list is empty by default,
 // so by default nothing is trusted.
@@ -143,6 +183,9 @@ func (m *Middleware) forwardedClientAddr(
 // another client's bucket, by picking an X-Forwarded-For value —
 // which makes every limit here decorative against a deliberate
 // attacker.
+//
+// The address that identifies the client is then reduced to a bucket
+// by bucketKey: full address for IPv4, /64 prefix for IPv6.
 func (m *Middleware) rateLimitKey(r *http.Request) (string, error) {
 	return m.clientKey(r), nil
 }
@@ -152,23 +195,25 @@ func (m *Middleware) clientKey(r *http.Request) string {
 	peer, err := netip.ParseAddr(ipFromHostPort(r.RemoteAddr))
 	if err != nil {
 		// Not an address we can reason about; key on the raw
-		// value, the most specific identity left. On a
-		// Unix-socket listener every peer carries the same
-		// RemoteAddr and so shares one bucket, which is the
-		// fail-closed direction.
+		// value, the most specific identity left. Distinct
+		// RemoteAddr values stay in distinct buckets, so this
+		// path cannot silently collapse unrelated clients
+		// together. On a Unix-socket listener every peer
+		// carries the same RemoteAddr and so shares one bucket,
+		// which is the fail-closed direction.
 		return r.RemoteAddr
 	}
 
 	peer = normalizeAddr(peer)
 	if !m.isTrustedProxy(peer) {
-		return peer.String()
+		return bucketKey(peer)
 	}
 
 	if addr, ok := m.forwardedClientAddr(r); ok {
-		return addr.String()
+		return bucketKey(addr)
 	}
 
-	return peer.String()
+	return bucketKey(peer)
 }
 
 // tooManyRequests returns the 429 handler used by the login,