From 21f5941a8dcf4f89a35ad004d7da921a987379d9 Mon Sep 17 00:00:00 2001 From: Pat Downey Date: Sun, 15 Nov 2026 22:54:11 +0000 Subject: [PATCH] feat(http): add ClientAddr and ClientIPConfig for trusted-proxy client addresses ClientIPResolver.ClientAddr returns a netip.Addr and ClientIP is deprecated. Trusted-proxy mode now reads Forwarded when X-Forwarded-For is absent, accepts entries with ports, and stops at a malformed hop instead of skipping it. ClientIPConfig takes the trust model from configuration. GetClientIP is documented as display and logging only. Co-Authored-By: Claude Sonnet 5.5 --- http/client_ip.go | 203 +++++++++++++++++++++++++-------------- http/client_ip_config.go | 58 +++++++++++ http/client_ip_test.go | 146 +++++++++++++++++++++++++++- 3 files changed, 330 insertions(+), 77 deletions(-) create mode 100644 http/client_ip_config.go diff --git a/http/client_ip.go b/http/client_ip.go index dc50ed78..d59dc970 100644 --- a/http/client_ip.go +++ b/http/client_ip.go @@ -2,7 +2,6 @@ package http import ( "context" - "net" "net/http" "net/netip" "slices" @@ -32,6 +31,10 @@ func ClientIPFromContext(ctx context.Context) (string, bool) { // It checks X-Forwarded-For and X-Real-IP headers first (for proxied requests), // then falls back to RemoteAddr. // +// It is suitable for display and logging only. For a rate-limit key, access +// control or any other trust decision use ClientIPResolver.ClientAddr, which +// ignores these headers unless the peer is a configured trusted proxy. +// // X-Forwarded-For, Forwarded, and X-Real-IP are ordinary request headers: // any client can set them to an arbitrary value, and this function trusts // them unconditionally with no allowlist of known proxy addresses. Unless @@ -103,24 +106,27 @@ func parseForwardedHeader(f string) string { return "" } -// ClientIPResolver resolves a request's client IP address under an -// explicit trust model, unlike the package-level GetClientIP, which trusts -// forwarding headers unconditionally (see its doc comment). Zero or one -// trust mode may be configured: +// ClientIPResolver resolves a request's client address under an explicit +// trust model, unlike the package-level GetClientIP, which trusts forwarding +// headers unconditionally (see its doc comment). Zero or one trust mode may +// be configured: // // - WithTrustedHeader trusts one named header verbatim, for platforms // whose edge sets a header this process can only receive by going // through that edge (e.g. fly.io's Fly-Client-IP -- see // NewFlyClientIPResolver). -// - WithTrustedProxyCIDRs walks X-Forwarded-For from the right against a -// caller-supplied set of trusted proxy ranges, for platforms that -// publish stable ranges (AWS ALB, Azure Application Gateway, -// Cloudflare, self-hosted nginx, etc). +// - WithTrustedProxyCIDRs walks X-Forwarded-For, or failing that +// Forwarded, from the right against a caller-supplied set of trusted +// proxy ranges, for platforms that publish stable ranges (AWS ALB, +// Azure Application Gateway, Cloudflare, self-hosted nginx, etc). +// +// If both are configured, WithTrustedHeader takes precedence. If neither is +// configured, ClientAddr is the request's direct peer address (RemoteAddr) +// only -- it never trusts a client-supplied header, unlike GetClientIP. // -// If both are configured, WithTrustedHeader takes precedence. If neither -// is configured, ClientIP falls back to the request's direct peer address -// (RemoteAddr) only -- it never trusts a client-supplied header, unlike -// GetClientIP. +// When the listener understands the PROXY protocol (see WithProxyProtocol), +// RemoteAddr is already the real client, so the zero-configuration resolver +// is the right choice behind such a proxy. type ClientIPResolver struct { trustedHeader string trustedProxyCIDRs []netip.Prefix @@ -137,13 +143,16 @@ func WithTrustedHeader(name string) ClientIPResolverOption { return func(c *ClientIPResolver) { c.trustedHeader = name } } -// WithTrustedProxyCIDRs configures the resolver to walk X-Forwarded-For -// from the right, skipping entries whose address falls within the given -// CIDR ranges, and returning the first entry that doesn't -- the RFC -// 7239-style trusted-proxy-list algorithm. The request's direct peer -// (RemoteAddr) must also fall within the trusted set for X-Forwarded-For -// to be consulted at all; otherwise the peer is untrusted and is used -// directly, since any header it presents is unverified. +// WithTrustedProxyCIDRs configures the resolver to walk X-Forwarded-For (or +// Forwarded, when that is absent) from the right, skipping entries whose +// address falls within the given CIDR ranges, and returning the first entry +// that doesn't -- the RFC 7239-style trusted-proxy-list algorithm. The +// request's direct peer (RemoteAddr) must also fall within the trusted set +// for the headers to be consulted at all; otherwise the peer is untrusted and +// is used directly, since any header it presents is unverified. +// +// An entry that cannot be parsed ends the walk: it was written by a hop this +// process cannot vouch for, so the nearest address before it is returned. func WithTrustedProxyCIDRs(cidrs ...netip.Prefix) ClientIPResolverOption { return func(c *ClientIPResolver) { c.trustedProxyCIDRs = append(c.trustedProxyCIDRs, cidrs...) } } @@ -172,54 +181,78 @@ func NewFlyClientIPResolver() *ClientIPResolver { return NewClientIPResolver(WithTrustedHeader("Fly-Client-IP")) } -// ClientIP resolves r's client IP under the configured trust mode. -func (c *ClientIPResolver) ClientIP(r *http.Request) string { +// ClientAddr resolves r's client address under the configured trust mode. It +// returns the zero Addr when neither the headers nor RemoteAddr yield a valid +// address. IPv4-mapped IPv6 addresses are returned as IPv4 and zones are +// dropped, so the result is a stable key. +func (c *ClientIPResolver) ClientAddr(r *http.Request) netip.Addr { if c.trustedHeader != "" { - return c.clientIPFromTrustedHeader(r) + return c.clientAddrFromTrustedHeader(r) } if len(c.trustedProxyCIDRs) > 0 { - return c.clientIPFromTrustedProxyCIDRs(r) + return c.clientAddrFromTrustedProxyCIDRs(r) } - return c.remoteAddrString(r) + return remoteAddrIP(r) +} + +// ClientIP resolves r's client address as a string, falling back to the raw +// RemoteAddr when it cannot be parsed. +// +// Deprecated: Use ClientAddr, which returns a netip.Addr. +func (c *ClientIPResolver) ClientIP(r *http.Request) string { + return c.clientAddrString(r) } -// PrincipalFunc adapts ClientIP to the PrincipalFunc signature, for use +// PrincipalFunc adapts ClientAddr to the PrincipalFunc signature, for use // with WithRateLimiterPrincipalFunc/WithPrincipalFunc. func (c *ClientIPResolver) PrincipalFunc(r *http.Request) (string, error) { - return c.ClientIP(r), nil + return c.clientAddrString(r), nil } -func (c *ClientIPResolver) clientIPFromTrustedHeader(r *http.Request) string { - if v := strings.TrimSpace(r.Header.Get(c.trustedHeader)); v != "" { - return v +func (c *ClientIPResolver) clientAddrString(r *http.Request) string { + if addr := c.ClientAddr(r); addr.IsValid() { + return addr.String() } - // The trusted header is unexpectedly absent (e.g. something hit this + + return r.RemoteAddr +} + +func (c *ClientIPResolver) clientAddrFromTrustedHeader(r *http.Request) netip.Addr { + if addr, ok := parseForwardedIP(r.Header.Get(c.trustedHeader)); ok { + return addr + } + // The trusted header is absent or unusable (e.g. something hit this // process directly, bypassing the edge that normally sets it). - return c.remoteAddrString(r) + return remoteAddrIP(r) } -func (c *ClientIPResolver) clientIPFromTrustedProxyCIDRs(r *http.Request) string { - peer, ok := remoteAddrIP(r) - if !ok || !c.isTrustedProxy(peer) { +func (c *ClientIPResolver) clientAddrFromTrustedProxyCIDRs(r *http.Request) netip.Addr { + peer := remoteAddrIP(r) + if !peer.IsValid() || !c.isTrustedProxy(peer) { // The immediate peer isn't a trusted proxy (or couldn't be - // parsed), so any X-Forwarded-For it presents is unverified -- - // the peer itself is the only address that can be trusted. - return c.remoteAddrString(r) + // parsed), so any header it presents is unverified -- the peer + // itself is the only address that can be trusted. + return peer } - for entry := range reverseSplitSeq(r.Header.Get("X-Forwarded-For"), ",") { - addr, ok := parseForwardedIP(entry) + hops := forwardedHops(r) + + // nearest is the closest hop already known to be a trusted proxy. + nearest := peer + for _, hop := range slices.Backward(hops) { + addr, ok := parseForwardedIP(hop) if !ok { - continue + return nearest } if !c.isTrustedProxy(addr) { - return addr.String() + return addr } + nearest = addr } - // Every entry (or none at all) was a trusted proxy; fall back to the peer. - return peer.String() + // Every entry (or none at all) was a trusted proxy. + return peer } func (c *ClientIPResolver) isTrustedProxy(addr netip.Addr) bool { @@ -232,50 +265,72 @@ func (c *ClientIPResolver) isTrustedProxy(addr netip.Addr) bool { return false } -// remoteAddrString returns r.RemoteAddr's IP, or the raw RemoteAddr if it -// can't be parsed. -func (c *ClientIPResolver) remoteAddrString(r *http.Request) string { - if peer, ok := remoteAddrIP(r); ok { - return peer.String() +// forwardedHops returns the hop addresses from X-Forwarded-For, or failing +// that the for= values of Forwarded, in the order the proxies appended them. +func forwardedHops(r *http.Request) []string { + if xff := r.Header.Values("X-Forwarded-For"); len(xff) > 0 { + return splitHeaderList(xff) } - return r.RemoteAddr + var hops []string + for _, h := range splitHeaderList(r.Header.Values("Forwarded")) { + hops = append(hops, forwardedFor(h)) + } + + return hops } -// remoteAddrIP extracts and parses the IP portion of r.RemoteAddr, which -// net/http guarantees to be in "IP:port" form. -func remoteAddrIP(r *http.Request) (netip.Addr, bool) { - host, _, err := net.SplitHostPort(r.RemoteAddr) - if err != nil { - host = r.RemoteAddr +// splitHeaderList splits repeated, comma-separated header values into +// elements, in order. +func splitHeaderList(values []string) []string { + out := make([]string, 0, len(values)) + for _, v := range values { + out = append(out, strings.Split(v, ",")...) } - addr, err := netip.ParseAddr(host) - return addr, err == nil + return out } -// parseForwardedIP parses a single X-Forwarded-For entry, tolerating -// surrounding whitespace and bracketed IPv6 literals. +// forwardedFor returns the for= value of one Forwarded element, or "" when it +// has none. +func forwardedFor(element string) string { + for part := range strings.SplitSeq(element, ";") { + before, after, ok := strings.Cut(strings.TrimSpace(part), "=") + if ok && strings.EqualFold(before, "for") { + return strings.Trim(strings.TrimSpace(after), "\"") + } + } + + return "" +} + +// remoteAddrIP extracts and parses the IP portion of r.RemoteAddr, which +// net/http guarantees to be in "IP:port" form. It returns the zero Addr when +// that cannot be parsed. +func remoteAddrIP(r *http.Request) netip.Addr { + addr, _ := parseForwardedIP(r.RemoteAddr) + + return addr +} + +// parseForwardedIP parses a single address as it appears in a forwarding +// header or RemoteAddr, tolerating surrounding whitespace, an optional port +// and bracketed IPv6 literals. The result is unmapped and has no zone. func parseForwardedIP(s string) (netip.Addr, bool) { s = strings.TrimSpace(s) + if ap, err := netip.ParseAddrPort(s); err == nil { + return normaliseAddr(ap.Addr()), true + } s = strings.TrimPrefix(s, "[") s = strings.TrimSuffix(s, "]") addr, err := netip.ParseAddr(s) + if err != nil { + return netip.Addr{}, false + } - return addr, err == nil + return normaliseAddr(addr), true } -// reverseSplitSeq splits s on sep and yields the parts from right to left. -func reverseSplitSeq(s, sep string) func(yield func(string) bool) { - return func(yield func(string) bool) { - if s == "" { - return - } - parts := strings.Split(s, sep) - for _, part := range slices.Backward(parts) { - if !yield(part) { - return - } - } - } +func normaliseAddr(addr netip.Addr) netip.Addr { + return addr.Unmap().WithZone("") } diff --git a/http/client_ip_config.go b/http/client_ip_config.go new file mode 100644 index 00000000..9a9bda56 --- /dev/null +++ b/http/client_ip_config.go @@ -0,0 +1,58 @@ +package http + +import ( + "net/netip" + + "github.com/dioad/config/configcheck" +) + +// ClientIPConfig is the trust model of ClientIPResolver, in the form services +// take it in their configuration. An empty config trusts no header, so the +// client address is the connection's address. +type ClientIPConfig struct { + // TrustedProxies are the ranges of the proxies in front of the service, + // in CIDR notation. Forwarding headers are honoured only from a peer in + // one of them. + TrustedProxies []string `desc:"CIDR ranges of proxies whose forwarding headers are trusted" mapstructure:"trusted-proxies"` + + // TrustedHeader names a header set by an edge that this process can only + // be reached through, such as Fly-Client-IP on fly.io. It takes + // precedence over TrustedProxies. + TrustedHeader string `desc:"header set by the edge proxy that is trusted verbatim" mapstructure:"trusted-header"` +} + +// Check reports to c a trusted proxy that is not a CIDR range, and trust +// modes set together. c is positioned at the config's own block. +func (c ClientIPConfig) Check(findings *configcheck.Collector) { + for i, p := range c.TrustedProxies { + if _, err := netip.ParsePrefix(p); err != nil { + findings.Field("trusted-proxies").Index(i).Errorf("%q is not a CIDR range: %v", p, err) + } + } + if c.TrustedHeader != "" && len(c.TrustedProxies) > 0 { + findings.Field("trusted-header").Errorf("is set together with trusted-proxies, which it takes precedence over; set only one") + } +} + +// Resolver returns the ClientIPResolver for c. It returns an error for a +// trusted proxy that is not a CIDR range; Check reports the same. +func (c ClientIPConfig) Resolver() (*ClientIPResolver, error) { + var opts []ClientIPResolverOption + if c.TrustedHeader != "" { + opts = append(opts, WithTrustedHeader(c.TrustedHeader)) + } + + prefixes := make([]netip.Prefix, 0, len(c.TrustedProxies)) + for _, p := range c.TrustedProxies { + prefix, err := netip.ParsePrefix(p) + if err != nil { + return nil, err + } + prefixes = append(prefixes, prefix) + } + if len(prefixes) > 0 { + opts = append(opts, WithTrustedProxyCIDRs(prefixes...)) + } + + return NewClientIPResolver(opts...), nil +} diff --git a/http/client_ip_test.go b/http/client_ip_test.go index ba1be197..ca676bfb 100644 --- a/http/client_ip_test.go +++ b/http/client_ip_test.go @@ -6,6 +6,7 @@ import ( "net/netip" "testing" + "github.com/dioad/config/configcheck" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" ) @@ -188,12 +189,12 @@ func TestClientIPResolver_TrustedProxyCIDRs(t *testing.T) { assert.Equal(t, "10.0.0.2", resolver.ClientIP(req)) }) - t.Run("skips a malformed XFF entry and continues walking left", func(t *testing.T) { + t.Run("a malformed XFF entry ends the walk at the nearest trusted hop", func(t *testing.T) { req := httptest.NewRequestWithContext(t.Context(), http.MethodGet, "/test", nil) - req.Header.Set("X-Forwarded-For", "198.51.100.1, not-an-ip, 10.0.0.2") + req.Header.Set("X-Forwarded-For", "198.51.100.1, not-an-ip, 10.0.0.3") req.RemoteAddr = "10.0.0.2:12345" - assert.Equal(t, "198.51.100.1", resolver.ClientIP(req)) + assert.Equal(t, "10.0.0.3", resolver.ClientIP(req), "an address left of a malformed hop was not vouched for by a trusted proxy") }) } @@ -217,3 +218,142 @@ func TestClientIPResolver_PrincipalFunc(t *testing.T) { require.NoError(t, err) assert.Equal(t, "203.0.113.5", principal) } + +func clientAddrRequest(t *testing.T, remote string, headers map[string][]string) *http.Request { + t.Helper() + req := httptest.NewRequestWithContext(t.Context(), http.MethodGet, "/test", nil) + req.RemoteAddr = remote + for k, vs := range headers { + for _, v := range vs { + req.Header.Add(k, v) + } + } + + return req +} + +func TestClientIPResolver_ClientAddr_UntrustedPeerCannotChooseAddress(t *testing.T) { + resolver := NewClientIPResolver(WithTrustedProxyCIDRs(mustPrefix(t, "10.0.0.0/8"))) + + for _, header := range []string{"X-Forwarded-For", "Forwarded", "X-Real-IP"} { + t.Run(header, func(t *testing.T) { + value := "1.2.3.4" + if header == "Forwarded" { + value = "for=1.2.3.4" + } + req := clientAddrRequest(t, "203.0.113.9:4000", map[string][]string{header: {value}}) + + assert.Equal(t, netip.MustParseAddr("203.0.113.9"), resolver.ClientAddr(req)) + }) + } +} + +func TestClientIPResolver_ClientAddr_NoTrustMode(t *testing.T) { + resolver := NewClientIPResolver() + req := clientAddrRequest(t, "[2001:db8::7]:4000", map[string][]string{"X-Forwarded-For": {"1.2.3.4"}}) + + assert.Equal(t, netip.MustParseAddr("2001:db8::7"), resolver.ClientAddr(req)) +} + +func TestClientIPResolver_ClientAddr_TrustedProxyChains(t *testing.T) { + resolver := NewClientIPResolver(WithTrustedProxyCIDRs(mustPrefix(t, "10.0.0.0/8"), mustPrefix(t, "fd00::/8"))) + + tests := []struct { + name string + remote string + headers map[string][]string + want string + }{ + {"multiple hops", "10.0.0.1:1", map[string][]string{"X-Forwarded-For": {"198.51.100.1, 10.0.0.3, 10.0.0.2"}}, "198.51.100.1"}, + {"client-forged left entries are ignored", "10.0.0.1:1", map[string][]string{"X-Forwarded-For": {"9.9.9.9, 198.51.100.1, 10.0.0.2"}}, "198.51.100.1"}, + {"repeated XFF header lines", "10.0.0.1:1", map[string][]string{"X-Forwarded-For": {"9.9.9.9", "198.51.100.1, 10.0.0.2"}}, "198.51.100.1"}, + {"IPv6 client", "10.0.0.1:1", map[string][]string{"X-Forwarded-For": {"2001:db8::5, 10.0.0.2"}}, "2001:db8::5"}, + {"IPv6 proxies", "[fd00::1]:1", map[string][]string{"X-Forwarded-For": {"2001:db8::5, fd00::2"}}, "2001:db8::5"}, + {"bracketed IPv6 with port", "10.0.0.1:1", map[string][]string{"X-Forwarded-For": {`[2001:db8::5]:4711, 10.0.0.2`}}, "2001:db8::5"}, + {"IPv4 with port", "10.0.0.1:1", map[string][]string{"X-Forwarded-For": {"198.51.100.1:5000"}}, "198.51.100.1"}, + {"IPv4-mapped IPv6", "10.0.0.1:1", map[string][]string{"X-Forwarded-For": {"::ffff:198.51.100.1"}}, "198.51.100.1"}, + {"Forwarded header", "10.0.0.1:1", map[string][]string{"Forwarded": {`for=198.51.100.1;proto=https, for=10.0.0.2`}}, "198.51.100.1"}, + {"Forwarded quoted IPv6", "10.0.0.1:1", map[string][]string{"Forwarded": {`for="[2001:db8::5]:4711", for=10.0.0.2`}}, "2001:db8::5"}, + {"Forwarded obfuscated identifier ends the walk", "10.0.0.1:1", map[string][]string{"Forwarded": {`for=_hidden, for=10.0.0.2`}}, "10.0.0.2"}, + {"XFF wins over Forwarded", "10.0.0.1:1", map[string][]string{"X-Forwarded-For": {"198.51.100.1"}, "Forwarded": {"for=198.51.100.2"}}, "198.51.100.1"}, + {"empty XFF", "10.0.0.1:1", map[string][]string{"X-Forwarded-For": {""}}, "10.0.0.1"}, + {"whitespace only XFF", "10.0.0.1:1", map[string][]string{"X-Forwarded-For": {" , "}}, "10.0.0.1"}, + {"only malformed entries", "10.0.0.1:1", map[string][]string{"X-Forwarded-For": {"garbage"}}, "10.0.0.1"}, + {"all hops trusted", "10.0.0.1:1", map[string][]string{"X-Forwarded-For": {"10.0.0.3, 10.0.0.2"}}, "10.0.0.1"}, + {"no headers", "10.0.0.1:1", nil, "10.0.0.1"}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + assert.Equal(t, netip.MustParseAddr(tt.want), resolver.ClientAddr(clientAddrRequest(t, tt.remote, tt.headers))) + }) + } +} + +func TestClientIPResolver_ClientAddr_TrustedHeader(t *testing.T) { + resolver := NewFlyClientIPResolver() + + tests := []struct { + name string + value string + want string + }{ + {"valid", "203.0.113.5", "203.0.113.5"}, + {"malformed falls back to the peer", "garbage", "10.0.0.5"}, + {"absent falls back to the peer", "", "10.0.0.5"}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + headers := map[string][]string{} + if tt.value != "" { + headers["Fly-Client-IP"] = []string{tt.value} + } + + assert.Equal(t, netip.MustParseAddr(tt.want), resolver.ClientAddr(clientAddrRequest(t, "10.0.0.5:1", headers))) + }) + } +} + +func TestClientIPResolver_ClientAddr_UnparseableRemoteAddr(t *testing.T) { + resolver := NewClientIPResolver(WithTrustedProxyCIDRs(mustPrefix(t, "10.0.0.0/8"))) + req := clientAddrRequest(t, "@", map[string][]string{"X-Forwarded-For": {"1.2.3.4"}}) + + assert.False(t, resolver.ClientAddr(req).IsValid()) + assert.Equal(t, "@", resolver.ClientIP(req)) +} + +func TestClientIPConfig_Check(t *testing.T) { + tests := []struct { + name string + cfg ClientIPConfig + wantErr bool + }{ + {"empty", ClientIPConfig{}, false}, + {"valid proxies", ClientIPConfig{TrustedProxies: []string{"10.0.0.0/8", "fd00::/8"}}, false}, + {"header only", ClientIPConfig{TrustedHeader: "Fly-Client-IP"}, false}, + {"bad prefix", ClientIPConfig{TrustedProxies: []string{"10.0.0.0/8", "10.0.0.1"}}, true}, + {"both modes", ClientIPConfig{TrustedHeader: "Fly-Client-IP", TrustedProxies: []string{"10.0.0.0/8"}}, true}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + c := configcheck.NewCollector() + tt.cfg.Check(c) + + if tt.wantErr { + require.Error(t, c.Err()) + } else { + require.NoError(t, c.Err()) + } + }) + } +} + +func TestClientIPConfig_Resolver(t *testing.T) { + resolver, err := ClientIPConfig{TrustedProxies: []string{"10.0.0.0/8"}}.Resolver() + require.NoError(t, err) + + req := clientAddrRequest(t, "10.0.0.1:1", map[string][]string{"X-Forwarded-For": {"198.51.100.1"}}) + assert.Equal(t, netip.MustParseAddr("198.51.100.1"), resolver.ClientAddr(req)) + + _, err = ClientIPConfig{TrustedProxies: []string{"nope"}}.Resolver() + require.Error(t, err) +}