Gate forwarded-header trust behind trusted-proxy config (closes #88)

Every rate limiter keyed on httprate.KeyByRealIP, which believes
True-Client-IP, X-Real-IP and the first X-Forwarded-For entry from
any peer. A client could therefore mint a fresh bucket per request
by rotating a spoofed header, or drain another client's bucket by
claiming its address, which left the receiver, login and password
change limits with no value against a deliberate attacker.

The receiver, login and password change limiters now share one key
function: the connection's own address, unless the direct peer is
inside a network listed in the new TRUSTED_PROXIES CIDR list, in
which case the forwarded client address is used. The list is empty
by default, so nothing is trusted until an operator names their
proxy; a set-but-unparseable value aborts startup, matching the
handling of the other parsed variables.

X-Forwarded-For is the only forwarded header read, from any peer.
Reverse proxies append to it but pass other client headers through
verbatim, so believing a single-valued X-Real-IP or True-Client-IP
would hand a client behind the trusted proxy a fresh bucket per
request - the same bypass, inside the deployment TRUSTED_PROXIES
exists to serve. Within a trusted request the chain is walked right
to left, since the rightmost entry is the one the nearest proxy
appended, and the first hop that is not itself a trusted proxy is
taken as the client. A hop that is not a bare address - ip:port, a
bracketed IPv6 literal, the token unknown - ends the walk and the
peer address is used, rather than continuing left into entries the
client controls.

Trusted-proxy prefixes written in IPv4-mapped form are unmapped at
parse time, since peer addresses are unmapped before matching and
such a prefix would otherwise silently never match.

Also folds in two cleanups from the same review: the 429 responder
shared by all three limiters is extracted, and the
RECEIVER_RATE_LIMIT error-path tests now assert that the failure
names the variable and wraps ErrNonPositiveValue rather than only
that some error occurred.

internal/middleware/ratelimit.go

@@ -2,6 +2,9 @@ package middleware
 
 import (
 	"net/http"
+	"net/netip"
+	"slices"
+	"strings"
 	"time"
 
 	"github.com/go-chi/httprate"
@@ -31,13 +34,120 @@ const (
 	receiverRateInterval = 1 * time.Minute
 )
 
+// normalizeAddr strips the IPv4-in-IPv6 wrapper and any zone from
+// addr so that comparisons and bucket keys are canonical.
+func normalizeAddr(addr netip.Addr) netip.Addr {
+	return addr.Unmap().WithZone("")
+}
+
+// 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.
+func (m *Middleware) isTrustedProxy(addr netip.Addr) bool {
+	for _, prefix := range m.params.Config.TrustedProxies {
+		if prefix.Contains(addr) {
+			return true
+		}
+	}
+
+	return false
+}
+
+// forwardedClientAddr returns the client address named by this
+// request's X-Forwarded-For chain. It is consulted only for requests
+// whose direct peer is a trusted proxy.
+//
+// X-Forwarded-For is the only header read. X-Real-IP and
+// True-Client-IP are deliberately ignored: the reverse proxies in
+// common use append to X-Forwarded-For and pass any other header the
+// client sent through untouched, so believing a single-valued header
+// would let a client behind the trusted proxy name its own bucket —
+// the very bypass this gating exists to close.
+//
+// The chain is walked right to left, because the rightmost entry is
+// the one the nearest proxy appended and everything to its left may
+// have been written by the client. The first hop that is not itself
+// a trusted proxy is the client. A hop that cannot be read as a bare
+// address ends the walk: past it the chain is not the shape assumed
+// here, so the caller falls back to the peer address.
+func (m *Middleware) forwardedClientAddr(
+	r *http.Request,
+) (netip.Addr, bool) {
+	hops := strings.Split(
+		strings.Join(r.Header.Values("X-Forwarded-For"), ","), ",",
+	)
+
+	for _, hop := range slices.Backward(hops) {
+		hop = strings.TrimSpace(hop)
+		if hop == "" {
+			continue
+		}
+
+		addr, err := netip.ParseAddr(hop)
+		if err != nil {
+			return netip.Addr{}, false
+		}
+
+		if addr = normalizeAddr(addr); !m.isTrustedProxy(addr) {
+			return addr, true
+		}
+	}
+
+	return netip.Addr{}, false
+}
+
+// rateLimitKey is the client identity every rate limiter in this
+// package buckets on. Forwarded headers are honoured only when the
+// direct peer (RemoteAddr) is inside the configured trusted-proxy
+// set; otherwise the peer address itself is the key. Without that
+// gate any client could mint a fresh bucket per request, or starve
+// another client's bucket, by picking an X-Forwarded-For value —
+// which makes every limit here decorative against a deliberate
+// attacker.
+func (m *Middleware) rateLimitKey(r *http.Request) (string, error) {
+	return m.clientKey(r), nil
+}
+
+// clientKey computes the bucket key described on rateLimitKey.
+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 rather than collapsing such peers into one
+		// shared bucket.
+		return r.RemoteAddr
+	}
+
+	peer = normalizeAddr(peer)
+	if !m.isTrustedProxy(peer) {
+		return peer.String()
+	}
+
+	if addr, ok := m.forwardedClientAddr(r); ok {
+		return addr.String()
+	}
+
+	return peer.String()
+}
+
+// tooManyRequests returns the 429 handler shared by every limiter:
+// it logs the rejection with logMessage and answers with
+// responseMessage. httprate adds the Retry-After header (RFC 6585).
+func (m *Middleware) tooManyRequests(
+	logMessage, responseMessage string,
+) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		m.log.Warn(logMessage, "path", r.URL.Path)
+		http.Error(w, responseMessage, http.StatusTooManyRequests)
+	}
+}
+
 // LoginRateLimit returns middleware that enforces per-IP rate
 // limiting on login attempts using go-chi/httprate. Only POST
 // requests are rate-limited; GET requests (rendering the login
 // form) pass through unaffected. When the rate limit is exceeded,
-// a 429 Too Many Requests response is returned. IP extraction
-// honours X-Forwarded-For, X-Real-IP, and True-Client-IP headers
-// for reverse-proxy setups.
+// a 429 Too Many Requests response is returned. Clients are
+// identified by rateLimitKey.
 func (m *Middleware) LoginRateLimit() func(http.Handler) http.Handler {
 	return m.postRateLimit(
 		loginRateLimit,
@@ -66,9 +176,7 @@ func (m *Middleware) PasswordChangeRateLimit() func(http.Handler) http.Handler {
 // limit on POST requests only; all other methods pass through
 // unaffected. Requests over the limit receive a 429 with the
 // given response message, and each rejection is logged with the
-// given log message. IP extraction honours X-Forwarded-For,
-// X-Real-IP, and True-Client-IP headers for reverse-proxy
-// setups.
+// given log message. Clients are identified by rateLimitKey.
 func (m *Middleware) postRateLimit(
 	limit int,
 	interval time.Duration,
@@ -77,19 +185,10 @@ func (m *Middleware) postRateLimit(
 	limiter := httprate.Limit(
 		limit,
 		interval,
-		httprate.WithKeyFuncs(httprate.KeyByRealIP),
-		httprate.WithLimitHandler(http.HandlerFunc(
-			func(w http.ResponseWriter, r *http.Request) {
-				m.log.Warn(logMessage,
-					"path", r.URL.Path,
-				)
-				http.Error(
-					w,
-					responseMessage,
-					http.StatusTooManyRequests,
-				)
-			},
-		)),
+		httprate.WithKeyFuncs(m.rateLimitKey),
+		httprate.WithLimitHandler(
+			m.tooManyRequests(logMessage, responseMessage),
+		),
 	)
 
 	return func(next http.Handler) http.Handler {
@@ -116,31 +215,19 @@ func (m *Middleware) postRateLimit(
 // path (the path contains the entrypoint UUID, so each sender
 // is limited per entrypoint without affecting other senders or
 // other entrypoints). The limit is Config.ReceiverRateLimit
-// requests per minute. Requests over the limit receive a 429;
-// httprate adds the Retry-After header (RFC 6585). IP
-// extraction honours X-Forwarded-For, X-Real-IP, and
-// True-Client-IP headers for reverse-proxy setups.
+// requests per minute. Requests over the limit receive a 429.
+// Clients are identified by rateLimitKey.
 func (m *Middleware) ReceiverRateLimit() func(http.Handler) http.Handler {
 	return httprate.Limit(
 		m.params.Config.ReceiverRateLimit,
 		receiverRateInterval,
 		httprate.WithKeyFuncs(
-			httprate.KeyByRealIP,
+			m.rateLimitKey,
 			httprate.KeyByEndpoint,
 		),
-		httprate.WithLimitHandler(http.HandlerFunc(
-			func(w http.ResponseWriter, r *http.Request) {
-				m.log.Warn(
-					"webhook receiver rate limit exceeded",
-					"path", r.URL.Path,
-				)
-				http.Error(
-					w,
-					"Too many requests. "+
-						"Please slow down.",
-					http.StatusTooManyRequests,
-				)
-			},
+		httprate.WithLimitHandler(m.tooManyRequests(
+			"webhook receiver rate limit exceeded",
+			"Too many requests. Please slow down.",
 		)),
 	)
 }