refactor: rename trusted_proxies package to middleware and update function calls

2026-07-27 16:48:23 +08:00
parent b8bb3f40ac
commit 8aa5e754a8
3 changed files with 10 additions and 10 deletions
@@ -0,0 +1,51 @@
+package middleware
+
+import (
+	"errors"
+	"fmt"
+	"log"
+	"os"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+)
+
+var defaultTrustedProxyCIDRs = []string{
+	"127.0.0.0/8",
+	"::1",
+	"10.0.0.0/8",
+	"172.16.0.0/12",
+	"192.168.0.0/16",
+	"fc00::/7",
+}
+
+func ConfigureTrustedProxies(engine *gin.Engine) error {
+	rawTrustedProxies := strings.TrimSpace(os.Getenv("TRUSTED_PROXIES"))
+	if rawTrustedProxies == "" {
+		log.Print("WARNING: TRUSTED_PROXIES is unset or blank; trusting loopback, RFC 1918, and IPv6 ULA proxy addresses for compatibility. Set TRUSTED_PROXIES=none to trust no proxies, or configure explicit proxy IPs/CIDRs to replace these defaults.")
+		return engine.SetTrustedProxies(defaultTrustedProxyCIDRs)
+	}
+	if strings.EqualFold(rawTrustedProxies, "none") {
+		return engine.SetTrustedProxies(nil)
+	}
+
+	parts := strings.Split(rawTrustedProxies, ",")
+	trustedProxies := make([]string, 0, len(parts))
+	for _, part := range parts {
+		trustedProxy := strings.TrimSpace(part)
+		if trustedProxy == "" {
+			continue
+		}
+		if strings.EqualFold(trustedProxy, "none") {
+			return errors.New("TRUSTED_PROXIES=none must be used alone")
+		}
+		trustedProxies = append(trustedProxies, trustedProxy)
+	}
+	if len(trustedProxies) == 0 {
+		return errors.New("TRUSTED_PROXIES does not contain an IP address or CIDR")
+	}
+	if err := engine.SetTrustedProxies(trustedProxies); err != nil {
+		return fmt.Errorf("invalid TRUSTED_PROXIES: %w", err)
+	}
+	return nil
+}
@@ -0,0 +1,127 @@
+package middleware
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func requestClientIP(router http.Handler, remoteAddr string, forwardedFor string) string {
+	recorder := httptest.NewRecorder()
+	request := httptest.NewRequest(http.MethodGet, "/client-ip", nil)
+	request.RemoteAddr = remoteAddr
+	if forwardedFor != "" {
+		request.Header.Set("X-Forwarded-For", forwardedFor)
+	}
+	router.ServeHTTP(recorder, request)
+	return recorder.Body.String()
+}
+
+func newClientIPRouter() *gin.Engine {
+	router := gin.New()
+	router.GET("/client-ip", func(c *gin.Context) {
+		c.String(http.StatusOK, c.ClientIP())
+	})
+	return router
+}
+
+func TestConfigureTrustedProxiesDefaultsToLoopbackAndPrivateNetworks(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	t.Setenv("TRUSTED_PROXIES", "")
+	router := newClientIPRouter()
+	require.NoError(t, ConfigureTrustedProxies(router))
+
+	testCases := []struct {
+		name       string
+		remoteAddr string
+	}{
+		{name: "IPv4 loopback", remoteAddr: "127.0.0.1:12345"},
+		{name: "IPv6 loopback", remoteAddr: "[::1]:12345"},
+		{name: "10 private network", remoteAddr: "10.20.30.40:12345"},
+		{name: "172 private network", remoteAddr: "172.20.0.2:12345"},
+		{name: "192 private network", remoteAddr: "192.168.10.2:12345"},
+		{name: "IPv6 unique local network", remoteAddr: "[fd12:3456::2]:12345"},
+	}
+
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			clientIP := requestClientIP(router, testCase.remoteAddr, "203.0.113.10")
+			assert.Equal(t, "203.0.113.10", clientIP)
+		})
+	}
+}
+
+func TestConfigureTrustedProxiesDefaultRejectsPublicPeerHeaders(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	t.Setenv("TRUSTED_PROXIES", " \t ")
+	router := newClientIPRouter()
+	require.NoError(t, ConfigureTrustedProxies(router))
+
+	clientIP := requestClientIP(router, "198.51.100.10:12345", "203.0.113.10")
+	assert.Equal(t, "198.51.100.10", clientIP, "a public peer must not make a spoofed X-Forwarded-For authoritative")
+}
+
+func TestConfigureTrustedProxiesDefaultStopsAtPublicClientInForwardedChain(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	t.Setenv("TRUSTED_PROXIES", "")
+	router := newClientIPRouter()
+	require.NoError(t, ConfigureTrustedProxies(router))
+
+	clientIP := requestClientIP(router, "172.20.0.2:12345", "192.0.2.99, 203.0.113.10")
+	assert.Equal(t, "203.0.113.10", clientIP, "the first public hop from the trusted proxy must win over a client-supplied prefix")
+}
+
+func TestConfigureTrustedProxiesNoneDisablesForwardedHeaders(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	t.Setenv("TRUSTED_PROXIES", " NoNe ")
+	router := newClientIPRouter()
+	require.NoError(t, ConfigureTrustedProxies(router))
+
+	clientIP := requestClientIP(router, "127.0.0.1:12345", "203.0.113.10")
+	assert.Equal(t, "127.0.0.1", clientIP)
+}
+
+func TestConfigureTrustedProxiesAcceptsTrimmedIPsAndCIDRs(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	t.Setenv("TRUSTED_PROXIES", " 192.0.2.0/24, 198.51.100.30 ")
+	router := newClientIPRouter()
+	require.NoError(t, ConfigureTrustedProxies(router))
+
+	trustedClientIP := requestClientIP(router, "192.0.2.10:12345", "203.0.113.20")
+	assert.Equal(t, "203.0.113.20", trustedClientIP)
+
+	trustedExactIP := requestClientIP(router, "198.51.100.30:12345", "203.0.113.21")
+	assert.Equal(t, "203.0.113.21", trustedExactIP)
+
+	untrustedClientIP := requestClientIP(router, "198.51.100.20:12345", "203.0.113.22")
+	assert.Equal(t, "198.51.100.20", untrustedClientIP)
+
+	defaultProxyIP := requestClientIP(router, "127.0.0.1:12345", "203.0.113.23")
+	assert.Equal(t, "127.0.0.1", defaultProxyIP, "an explicit list must replace, not extend, the compatibility defaults")
+}
+
+func TestConfigureTrustedProxiesRejectsInvalidConfiguration(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	testCases := []struct {
+		name  string
+		value string
+	}{
+		{name: "no entries", value: ", ,"},
+		{name: "invalid entry", value: "not-an-ip"},
+		{name: "mixed valid and invalid entries", value: "127.0.0.1, not-an-ip"},
+		{name: "none mixed with valid entry", value: "none,127.0.0.1"},
+		{name: "valid entry mixed with none", value: "127.0.0.1,NONE"},
+	}
+
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			t.Setenv("TRUSTED_PROXIES", testCase.value)
+			router := newClientIPRouter()
+			assert.Error(t, ConfigureTrustedProxies(router))
+		})
+	}
+}