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. Within a trusted request
X-Forwarded-For is walked right to left and the first hop that is
not itself a trusted proxy wins, so client-prepended entries cannot
be selected.

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"
@@ -59,6 +61,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 +97,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 +227,60 @@ 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).
+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
+		}
+
+		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 +351,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 +368,7 @@ func loadFromEnv() (*Config, error) {
 		RetentionSweepInterval: retentionSweepInterval,
 		SessionIdleTimeout:     sessionIdleTimeout,
 		ReceiverRateLimit:      receiverRateLimit,
+		TrustedProxies:         trustedProxies,
 	}, nil
 }
 
@@ -335,6 +410,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 != "",