minstrel/internal/auth/clientip.go

package auth

import (
	"net"
	"net/http"
	"strings"
)

// ClientIP returns the caller's address, reading through trustedProxyHops
// reverse proxies.
//
// X-Forwarded-For grows left-to-right: every proxy APPENDS the peer it
// received the request from. For client -> CDN -> own-proxy -> Minstrel the
// app sees XFF = [client, CDN] and RemoteAddr = own-proxy. Each trusted proxy
// therefore accounts for one entry counting from the right, and the first
// address we were NOT told to trust is the client:
//
//	hops 0  -> RemoteAddr; XFF ignored entirely
//	hops 1  -> XFF[1] = CDN — trusting only our own proxy, the most we can
//	           honestly claim is the address it told us about
//	hops 2  -> XFF[0] = client
//
// Ignoring XFF whenever RemoteAddr is public would be safe but useless: behind
// a proxy on a public address (a separate host, or a CDN) every session would
// record the proxy, and the active-sessions list could never show an address
// change.
//
// # What the hop count asserts
//
// hops >= 1 is a DECLARATION that a proxy sits in front. Two ways to get it
// wrong, both worth understanding rather than papering over:
//
//   - Set to 1+ with NO proxy: any client can forge X-Forwarded-For and pick
//     what its own session row shows, defeating the compromise detection.
//   - Set HIGHER than the real chain: the index runs past the proxy-written
//     entries into attacker-supplied ones, same result.
//
// Both are inherent to the trusted-hop model (Rails, Caddy, Traefik and nginx
// behave the same way), which is why 0 is the default and the admin card asks
// for the number of proxies in front.
func ClientIP(r *http.Request, trustedProxyHops int) string {
	remote := hostOf(r.RemoteAddr)
	if trustedProxyHops <= 0 {
		return remote
	}
	chain := forwardedChain(r)
	if len(chain) == 0 {
		// No forwarding header: either there's genuinely no proxy, or one is
		// misconfigured. The socket peer is the only thing we actually know.
		return remote
	}
	// Clamp rather than reject: a chain shorter than the configured depth
	// means the hops were over-counted, and the leftmost entry is the closest
	// thing to a client on offer. The caveat above covers the risk.
	idx := len(chain) - trustedProxyHops
	if idx < 0 {
		idx = 0
	}
	if ip := net.ParseIP(chain[idx]); ip != nil {
		return ip.String()
	}
	// A proxy wrote something that isn't an address. Positional meaning is
	// lost, so fall back to what we can verify ourselves.
	return remote
}

// IsHTTPS reports whether the client reached us over HTTPS, reading through
// trustedProxyHops reverse proxies by the same rule as ClientIP.
//
// TLS terminates at the reverse proxy, so r.TLS is nil in every real
// deployment and only X-Forwarded-Proto can say what the client used.
// That header is believed only when hops >= 1: with no trusted proxy it is
// just something any client can send. Proxies that append rather than
// overwrite produce a comma list, read positionally like X-Forwarded-For.
//
// This decides only HTTPS-only behaviour (the cookie Secure flag, HSTS). It
// must never drive a redirect: plain-HTTP and LAN use keep working.
func IsHTTPS(r *http.Request, trustedProxyHops int) bool {
	if r.TLS != nil {
		return true
	}
	if trustedProxyHops <= 0 {
		return false
	}
	raw := r.Header.Get("X-Forwarded-Proto")
	if strings.TrimSpace(raw) == "" {
		return false
	}
	parts := strings.Split(raw, ",")
	idx := len(parts) - trustedProxyHops
	if idx < 0 {
		idx = 0
	}
	return strings.EqualFold(strings.TrimSpace(parts[idx]), "https")
}

// forwardedChain returns the X-Forwarded-For entries in wire order, or the
// single X-Real-IP value when XFF is absent.
//
// Entries are kept verbatim, including unparseable ones: their POSITION is
// what carries meaning here, so silently dropping a malformed hop would
// shift every index and could hand back an attacker-supplied entry.
func forwardedChain(r *http.Request) []string {
	raw := r.Header.Get("X-Forwarded-For")
	if strings.TrimSpace(raw) == "" {
		// Some proxies set only X-Real-IP, which by construction is a single
		// hop — the address that proxy saw.
		if real := strings.TrimSpace(r.Header.Get("X-Real-IP")); real != "" {
			return []string{real}
		}
		return nil
	}
	parts := strings.Split(raw, ",")
	out := make([]string, 0, len(parts))
	for _, p := range parts {
		if p = strings.TrimSpace(p); p != "" {
			out = append(out, p)
		}
	}
	return out
}

// hopsOf reads a trusted-depth accessor, treating a nil one as "trust
// nothing". Test contexts and any future caller that hasn't wired the
// settings service get the safe reading rather than a panic.
func hopsOf(fn func() int) int {
	if fn == nil {
		return 0
	}
	return fn()
}

// hostOf strips the port from a RemoteAddr, tolerating values that have none.
func hostOf(remoteAddr string) string {
	host, _, err := net.SplitHostPort(remoteAddr)
	if err != nil {
		return strings.TrimSpace(remoteAddr)
	}
	return host
}