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/config/config.go

@@ -5,8 +5,10 @@ import (
 	"errors"
 	"fmt"
 	"log/slog"
+	"net/netip"
 	"os"
 	"strconv"
+	"strings"
 	"time"
 
 	"go.uber.org/fx"
@@ -45,6 +47,11 @@ const (
 	// maxPort is the highest valid TCP port number. The lower
 	// bound (at least 1) is enforced by envPositiveInt.
 	maxPort = 65535
+
+	// mappedV4Offset is the number of leading bits an IPv4-mapped
+	// IPv6 prefix spends on the ::ffff:0:0/96 wrapper, so a /104
+	// covers the same addresses as an IPv4 /8.
+	mappedV4Offset = 96
 )
 
 // ErrInvalidEnvironment is returned when WEBHOOKER_ENVIRONMENT
@@ -59,6 +66,11 @@ var ErrNonPositiveValue = errors.New("value must be positive")
 // TCP port number is set above the valid port range.
 var ErrInvalidPort = errors.New("invalid port")
 
+// ErrInvalidCIDR is returned when an environment variable holding a
+// list of CIDR blocks contains an entry that is neither a CIDR block
+// nor a bare IP address.
+var ErrInvalidCIDR = errors.New("invalid CIDR")
+
 //nolint:revive // ConfigParams is a standard fx naming convention.
 type ConfigParams struct {
 	fx.In
@@ -90,6 +102,14 @@ type Config struct {
 	// client IP may send to a single webhook receiver entrypoint.
 	ReceiverRateLimit int
 
+	// TrustedProxies is the set of networks whose members are
+	// allowed to speak for the client with forwarded headers
+	// (X-Forwarded-For, X-Real-IP, True-Client-IP). It is empty
+	// unless TRUSTED_PROXIES is set, and empty means no peer is
+	// trusted: forwarded headers are then ignored entirely and
+	// clients are identified by the connection's own address.
+	TrustedProxies []netip.Prefix
+
 	params *ConfigParams
 	log    *slog.Logger
 }
@@ -212,6 +232,71 @@ func envDuration(
 	return d, nil
 }
 
+// parseCIDR parses one trusted-proxy list entry, which may be a
+// CIDR block ("10.0.0.0/8") or a bare address ("10.0.0.1", treated
+// as a single-host block).
+//
+// Both forms are unmapped, because peer addresses are unmapped
+// before they are matched against the list: an IPv4-mapped prefix
+// left in that form would silently never match.
+func parseCIDR(entry string) (netip.Prefix, error) {
+	if strings.Contains(entry, "/") {
+		prefix, err := netip.ParsePrefix(entry)
+		if err != nil {
+			return netip.Prefix{}, err //nolint:wrapcheck // wrapped by caller
+		}
+
+		if addr := prefix.Addr(); addr.Is4In6() &&
+			prefix.Bits() >= mappedV4Offset {
+			prefix = netip.PrefixFrom(
+				addr.Unmap(), prefix.Bits()-mappedV4Offset,
+			)
+		}
+
+		return prefix.Masked(), nil
+	}
+
+	addr, err := netip.ParseAddr(entry)
+	if err != nil {
+		return netip.Prefix{}, err //nolint:wrapcheck // wrapped by caller
+	}
+
+	return netip.PrefixFrom(addr.Unmap(), addr.Unmap().BitLen()), nil
+}
+
+// envPrefixList returns the value of the named environment variable
+// parsed as a comma-separated list of CIDR blocks (bare addresses
+// allowed). An unset, empty, or blank value yields an empty list. A
+// set value containing an unparseable entry is a hard error naming
+// the key and the bad entry, so startup fails loudly rather than
+// silently running with a list the operator did not intend.
+func envPrefixList(key string) ([]netip.Prefix, error) {
+	v := strings.TrimSpace(os.Getenv(key))
+	if v == "" {
+		return nil, nil
+	}
+
+	var prefixes []netip.Prefix
+
+	for entry := range strings.SplitSeq(v, ",") {
+		entry = strings.TrimSpace(entry)
+		if entry == "" {
+			continue
+		}
+
+		prefix, err := parseCIDR(entry)
+		if err != nil {
+			return nil, fmt.Errorf(
+				"%w: %s: %q: %w", ErrInvalidCIDR, key, entry, err,
+			)
+		}
+
+		prefixes = append(prefixes, prefix)
+	}
+
+	return prefixes, nil
+}
+
 // resolveEnvironment reads WEBHOOKER_ENVIRONMENT, defaulting to
 // dev, and rejects unrecognised values.
 func resolveEnvironment() (string, error) {
@@ -282,6 +367,11 @@ func loadFromEnv() (*Config, error) {
 		return nil, err
 	}
 
+	trustedProxies, err := envPrefixList("TRUSTED_PROXIES")
+	if err != nil {
+		return nil, err
+	}
+
 	return &Config{
 		DataDir:                envString("DATA_DIR"),
 		Debug:                  debug,
@@ -294,6 +384,7 @@ func loadFromEnv() (*Config, error) {
 		RetentionSweepInterval: retentionSweepInterval,
 		SessionIdleTimeout:     sessionIdleTimeout,
 		ReceiverRateLimit:      receiverRateLimit,
+		TrustedProxies:         trustedProxies,
 	}, nil
 }
 
@@ -335,6 +426,7 @@ func New(lc fx.Lifecycle, params ConfigParams) (*Config, error) {
 		"dataDir", s.DataDir,
 		"retentionSweepInterval", s.RetentionSweepInterval.String(),
 		"receiverRateLimit", s.ReceiverRateLimit,
+		"trustedProxies", len(s.TrustedProxies),
 		"hasSentryDSN", s.SentryDSN != "",
 		"hasMetricsAuth",
 		s.MetricsUsername != "" && s.MetricsPassword != "",