fix(apiserver): trust X-Forwarded-For only from configured proxies (bug-1948)

Cause: the router used gin.Default() without SetTrustedProxies, and gin
then trusts forwarding headers from every peer, so ClientIP() returned
whatever X-Forwarded-For a client sent: the IP whitelist and the IP bound
into JWTs could be spoofed.

Fix: new app.yaml option security.trusted_proxies (IP or CIDR list,
default empty = trust no proxy, validated at startup) passed to
SetTrustedProxies in Router(); an invalid list falls back to trusting
none. The nginx samples note that the proxy must be listed there.

Tests: TestRouter_IgnoresForwardedForByDefault,
TestRouter_HonoursForwardedForFromTrustedProxy, TestResolveTrustedProxies.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

src/frontend/apiserver/utils/config.go

@@ -4,6 +4,7 @@ import (
 	"errors"
 	"fmt"
 	"log"
+	"net"
 	"os"
 	"runtime"
 	"strconv"
@@ -56,6 +57,10 @@ type Authentication struct {
 
 type Security struct {
 	HTTPS HTTPSConfig `yaml:"https"`
+	// TrustedProxies lists the reverse proxies (IP or CIDR) whose
+	// X-Forwarded-For / X-Real-IP headers set the client IP. Empty (the
+	// default) trusts no proxy: the client IP is the TCP peer address.
+	TrustedProxies []string `yaml:"trusted_proxies"`
 }
 type HTTPSConfig struct {
 	Enabled  bool   `yaml:"enabled"`
@@ -105,6 +110,7 @@ var (
 	AppYamlConfig            *AppConfig
 	AuthenticationYamlConfig *Authentication
 	HttpsYamlConfig          *HTTPSConfig
+	TrustedProxiesYamlConfig []string
 	RateLimitYamlConfig      *RateLimitConfig
 	WhitelistYamlConfig      *WhitelistConfig
 	FileUploadYamlConfig     *FileUploadConfig
@@ -172,6 +178,11 @@ func InitConf() error {
 		CertFile: viper.GetString("security.https.cert_file"),
 		KeyFile:  viper.GetString("security.https.key_file"),
 	}
+	trustedProxies, err := resolveTrustedProxies(viper.GetStringSlice("security.trusted_proxies"))
+	if err != nil {
+		return err
+	}
+	TrustedProxiesYamlConfig = trustedProxies
 
 	// parse rate limit section
 	RateLimitYamlConfig = &RateLimitConfig{
@@ -310,6 +321,25 @@ func resolveMaxArraySize(v int) (effective int, clamped bool, err error) {
 	}
 }
 
+// resolveTrustedProxies validates security.trusted_proxies: every entry must
+// be an IP address or a CIDR. An empty list means no proxy is trusted.
+func resolveTrustedProxies(entries []string) ([]string, error) {
+	proxies := make([]string, 0, len(entries))
+	for _, e := range entries {
+		e = strings.TrimSpace(e)
+		if e == "" {
+			continue
+		}
+		if net.ParseIP(e) == nil {
+			if _, _, err := net.ParseCIDR(e); err != nil {
+				return nil, fmt.Errorf("invalid security.trusted_proxies entry %q: must be an IP address or CIDR", e)
+			}
+		}
+		proxies = append(proxies, e)
+	}
+	return proxies, nil
+}
+
 // resolveJWTSecret returns the JWT secret from XCE_JWT_SECRET env var if set and non-empty,
 // otherwise falls back to the value from config file.
 func resolveJWTSecret(configValue string) string {

src/frontend/apiserver/utils/config_test.go

@@ -40,6 +40,40 @@ func TestResolveJWTSecret_EmptyEnvUsesConfig(t *testing.T) {
 	}
 }
 
+// bug-1948: security.trusted_proxies accepts IPs and CIDRs only; empty
+// means no trusted proxy.
+func TestResolveTrustedProxies(t *testing.T) {
+	cases := []struct {
+		name    string
+		in      []string
+		want    []string
+		wantErr bool
+	}{
+		{"unset trusts none", nil, []string{}, false},
+		{"IP and CIDR", []string{"127.0.0.1", " 10.0.0.0/8 ", "::1"}, []string{"127.0.0.1", "10.0.0.0/8", "::1"}, false},
+		{"blank entries dropped", []string{""}, []string{}, false},
+		{"hostname refused", []string{"proxy.example.com"}, nil, true},
+		{"bad CIDR refused", []string{"10.0.0.0/33"}, nil, true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got, err := resolveTrustedProxies(tc.in)
+			if tc.wantErr {
+				if err == nil || !strings.Contains(err.Error(), "security.trusted_proxies") {
+					t.Fatalf("expected a security.trusted_proxies error, got %v (%v)", err, got)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error %v", err)
+			}
+			if strings.Join(got, ",") != strings.Join(tc.want, ",") || got == nil {
+				t.Errorf("resolveTrustedProxies(%q) = %q, want %q", tc.in, got, tc.want)
+			}
+		})
+	}
+}
+
 func TestResolveMaxArraySize(t *testing.T) {
 	cases := []struct {
 		name        string