From 7c48f9a85f9b96d2b7f5aed91dbc228b4a963b79 Mon Sep 17 00:00:00 2001 From: shaw Date: Fri, 17 Jul 2026 09:33:18 +0800 Subject: [PATCH] fix(security): unify audit log & session binding client IP with API key ACL trust toggle Behind a reverse proxy (e.g. nginx with X-Real-IP), admin audit logs and session IP/UA binding always recorded 127.0.0.1 because they hardcoded the gin trusted_proxies chain, while API key IP restriction already honored the "trust forwarded client IP" system setting. - add ip.GetSecurityClientIP(c, trustForwarded) as the single source of truth for security-sensitive client IP selection; API key auth middlewares (main + google) refactored onto it with zero behavior change - SessionBindingContext(cfg) now resolves the client IP via the same toggle and injects it into the request context; token issuance, binding enforcement and its mismatch audit record all read the injected value, so issue/verify can never diverge - audit log middleware and audit-log clear trace record the same security client IP (middleware.SecurityClientIP), falling back to the trusted proxy chain when the injection is absent - settings UI hint (zh/en) documents the broadened toggle scope and the one-time re-login after toggling while session binding is enabled With the toggle off (default) behavior is byte-for-byte unchanged. Co-Authored-By: Claude --- .../handler/admin/audit_log_handler.go | 3 +- backend/internal/pkg/ip/ip.go | 11 ++ backend/internal/pkg/ip/ip_test.go | 30 +++++ .../server/middleware/api_key_auth.go | 5 +- .../server/middleware/api_key_auth_google.go | 5 +- .../internal/server/middleware/audit_log.go | 3 +- .../server/middleware/session_binding.go | 43 ++++++-- .../server/middleware/session_binding_test.go | 103 ++++++++++++++++++ backend/internal/server/router.go | 5 +- .../src/i18n/locales/en/admin/settings.ts | 5 +- .../src/i18n/locales/zh/admin/settings.ts | 4 +- 11 files changed, 188 insertions(+), 29 deletions(-) create mode 100644 backend/internal/server/middleware/session_binding_test.go diff --git a/backend/internal/handler/admin/audit_log_handler.go b/backend/internal/handler/admin/audit_log_handler.go index 67d528a1e..a54135c86 100644 --- a/backend/internal/handler/admin/audit_log_handler.go +++ b/backend/internal/handler/admin/audit_log_handler.go @@ -6,7 +6,6 @@ import ( "strings" "time" - "github.com/Wei-Shaw/sub2api/internal/pkg/ip" "github.com/Wei-Shaw/sub2api/internal/pkg/response" "github.com/Wei-Shaw/sub2api/internal/server/middleware" "github.com/Wei-Shaw/sub2api/internal/service" @@ -150,7 +149,7 @@ func (h *AuditLogHandler) Clear(c *gin.Context) { CredentialMasked: middleware.MaskedRequestCredential(c), Method: http.MethodPost, Path: c.FullPath(), - ClientIP: ip.GetTrustedClientIP(c), + ClientIP: middleware.SecurityClientIP(c), UserAgent: c.Request.UserAgent(), StatusCode: http.StatusOK, } diff --git a/backend/internal/pkg/ip/ip.go b/backend/internal/pkg/ip/ip.go index f6f77c86e..2702b1353 100644 --- a/backend/internal/pkg/ip/ip.go +++ b/backend/internal/pkg/ip/ip.go @@ -54,6 +54,17 @@ func GetTrustedClientIP(c *gin.Context) string { return normalizeIP(c.ClientIP()) } +// GetSecurityClientIP 返回安全敏感场景（API Key IP 限制、审计日志、会话 IP/UA 绑定） +// 使用的客户端 IP。trustForwarded 对应系统设置「信任反代传递的客户端 IP」： +// 开启时信任反代转发头（CF-Connecting-IP / X-Real-IP / X-Forwarded-For）， +// 关闭时走 Gin trusted_proxies 解析链。 +func GetSecurityClientIP(c *gin.Context, trustForwarded bool) string { + if trustForwarded { + return GetClientIP(c) + } + return GetTrustedClientIP(c) +} + // normalizeIP 规范化 IP 地址，去除端口号和空格。 func normalizeIP(ip string) string { ip = strings.TrimSpace(ip) diff --git a/backend/internal/pkg/ip/ip_test.go b/backend/internal/pkg/ip/ip_test.go index 403b2d59e..7e579bf7a 100644 --- a/backend/internal/pkg/ip/ip_test.go +++ b/backend/internal/pkg/ip/ip_test.go @@ -94,3 +94,33 @@ func TestCheckIPRestrictionWithCompiledRules_InvalidWhitelistStillDenies(t *test require.False(t, allowed) require.Equal(t, "access denied", reason) } + +func TestGetSecurityClientIPHonorsTrustToggle(t *testing.T) { + gin.SetMode(gin.TestMode) + + for _, tc := range []struct { + name string + trustForwarded bool + want string + }{ + {name: "trust disabled uses trusted proxy chain", trustForwarded: false, want: "9.9.9.9"}, + {name: "trust enabled uses forwarded header", trustForwarded: true, want: "1.2.3.4"}, + } { + t.Run(tc.name, func(t *testing.T) { + r := gin.New() + require.NoError(t, r.SetTrustedProxies(nil)) + r.GET("/t", func(c *gin.Context) { + c.String(200, GetSecurityClientIP(c, tc.trustForwarded)) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/t", nil) + req.RemoteAddr = "9.9.9.9:12345" + req.Header.Set("X-Real-IP", "1.2.3.4") + r.ServeHTTP(w, req) + + require.Equal(t, 200, w.Code) + require.Equal(t, tc.want, w.Body.String()) + }) + } +} diff --git a/backend/internal/server/middleware/api_key_auth.go b/backend/internal/server/middleware/api_key_auth.go index a8fece044..b9013815a 100644 --- a/backend/internal/server/middleware/api_key_auth.go +++ b/backend/internal/server/middleware/api_key_auth.go @@ -97,10 +97,7 @@ func apiKeyAuthWithSubscription(apiKeyService *service.APIKeyService, subscripti // 检查 IP 限制（白名单/黑名单） // 注意：错误信息故意模糊，避免暴露具体的 IP 限制机制 if len(apiKey.IPWhitelist) > 0 || len(apiKey.IPBlacklist) > 0 { - clientIP := ip.GetTrustedClientIP(c) - if cfg.TrustForwardedIPForAPIKeyACL() { - clientIP = ip.GetClientIP(c) - } + clientIP := ip.GetSecurityClientIP(c, cfg.TrustForwardedIPForAPIKeyACL()) allowed, _ := ip.CheckIPRestrictionWithCompiledRules(clientIP, apiKey.CompiledIPWhitelist, apiKey.CompiledIPBlacklist) if !allowed { if clientIP == "" { diff --git a/backend/internal/server/middleware/api_key_auth_google.go b/backend/internal/server/middleware/api_key_auth_google.go index b910dd9fa..49bf6b426 100644 --- a/backend/internal/server/middleware/api_key_auth_google.go +++ b/backend/internal/server/middleware/api_key_auth_google.go @@ -59,10 +59,7 @@ func APIKeyAuthWithSubscriptionGoogle(apiKeyService *service.APIKeyService, subs // 检查 IP 限制（白名单/黑名单）。与主中间件保持一致，避免 Gemini 端点绕过 Key 的 IP ACL。 if len(apiKey.IPWhitelist) > 0 || len(apiKey.IPBlacklist) > 0 { - clientIP := ip.GetTrustedClientIP(c) - if cfg.TrustForwardedIPForAPIKeyACL() { - clientIP = ip.GetClientIP(c) - } + clientIP := ip.GetSecurityClientIP(c, cfg.TrustForwardedIPForAPIKeyACL()) allowed, _ := ip.CheckIPRestrictionWithCompiledRules(clientIP, apiKey.CompiledIPWhitelist, apiKey.CompiledIPBlacklist) if !allowed { if clientIP == "" { diff --git a/backend/internal/server/middleware/audit_log.go b/backend/internal/server/middleware/audit_log.go index 1cb510f06..16403a82b 100644 --- a/backend/internal/server/middleware/audit_log.go +++ b/backend/internal/server/middleware/audit_log.go @@ -7,7 +7,6 @@ import ( "time" "github.com/Wei-Shaw/sub2api/internal/pkg/ctxkey" - "github.com/Wei-Shaw/sub2api/internal/pkg/ip" "github.com/Wei-Shaw/sub2api/internal/service" "github.com/gin-gonic/gin" @@ -147,7 +146,7 @@ func NewAuditLogMiddleware(auditService *service.AuditLogService) AuditLogMiddle Action: action, Method: c.Request.Method, Path: c.FullPath(), - ClientIP: ip.GetTrustedClientIP(c), + ClientIP: SecurityClientIP(c), UserAgent: c.Request.UserAgent(), RequestBody: bodyRedacted, StatusCode: status, diff --git a/backend/internal/server/middleware/session_binding.go b/backend/internal/server/middleware/session_binding.go index b31e2a39e..31edd110b 100644 --- a/backend/internal/server/middleware/session_binding.go +++ b/backend/internal/server/middleware/session_binding.go @@ -1,19 +1,25 @@ package middleware import ( + "strings" + + "github.com/Wei-Shaw/sub2api/internal/config" "github.com/Wei-Shaw/sub2api/internal/pkg/ip" "github.com/Wei-Shaw/sub2api/internal/service" "github.com/gin-gonic/gin" ) -// SessionBindingContext 全局中间件：将请求的可信客户端 IP 与 User-Agent 注入 -// request context，供 token 签发路径（登录 / 刷新 / OAuth 回调）读取并写入会话绑定。 -// 必须使用 GetTrustedClientIP（走 trusted_proxies 链），不可信头会导致绑定被伪造绕过。 -func SessionBindingContext() gin.HandlerFunc { +// SessionBindingContext 全局中间件：将请求的客户端 IP 与 User-Agent 注入 +// request context，供 token 签发路径（登录 / 刷新 / OAuth 回调）读取并写入会话绑定， +// 同时作为审计日志、会话绑定校验的统一客户端 IP 来源。 +// IP 取值与 API Key IP 限制共用「信任反代传递的客户端 IP」系统开关： +// 开启时信任反代转发头（CF-Connecting-IP / X-Real-IP / X-Forwarded-For）， +// 关闭时走 trusted_proxies 解析链，避免不可信头伪造绕过绑定。 +func SessionBindingContext(cfg *config.Config) gin.HandlerFunc { return func(c *gin.Context) { binding := &service.SessionBinding{ - IP: ip.GetTrustedClientIP(c), + IP: ip.GetSecurityClientIP(c, cfg.TrustForwardedIPForAPIKeyACL()), UserAgent: c.Request.UserAgent(), } c.Request = c.Request.WithContext(service.WithSessionBinding(c.Request.Context(), binding)) @@ -21,13 +27,27 @@ func SessionBindingContext() gin.HandlerFunc { } } -// currentSessionBindingHash 计算当前请求的会话指纹哈希。 -func currentSessionBindingHash(c *gin.Context) string { - binding := &service.SessionBinding{ +// requestSessionBinding 返回当前请求的会话指纹，优先取 SessionBindingContext +// 注入的解析结果（保证与 token 签发路径取值一致）；注入缺失时按 trusted_proxies +// 链回退兜底（等价于开关关闭时的行为）。 +func requestSessionBinding(c *gin.Context) *service.SessionBinding { + if binding := service.SessionBindingFromContext(c.Request.Context()); binding != nil { + return binding + } + return &service.SessionBinding{ IP: ip.GetTrustedClientIP(c), UserAgent: c.Request.UserAgent(), } - return binding.Hash() +} + +// SecurityClientIP 返回当前请求用于安全敏感记录（审计日志等）的客户端 IP。 +// 与会话绑定、API Key IP 限制共用同一套「信任反代传递的客户端 IP」开关语义。 +func SecurityClientIP(c *gin.Context) string { + if binding := service.SessionBindingFromContext(c.Request.Context()); binding != nil && + strings.TrimSpace(binding.IP) != "" { + return binding.IP + } + return ip.GetTrustedClientIP(c) } // enforceSessionBinding 校验 access token 的会话指纹（IP/UA 绑定）。 @@ -49,7 +69,8 @@ func enforceSessionBinding( if claims == nil || claims.BindingHash == "" { return true } - current := currentSessionBindingHash(c) + binding := requestSessionBinding(c) + current := binding.Hash() if current == "" || current == claims.BindingHash { return true } @@ -71,7 +92,7 @@ func enforceSessionBinding( Action: service.AuditActionSessionBindingMismatch, Method: c.Request.Method, Path: path, - ClientIP: ip.GetTrustedClientIP(c), + ClientIP: binding.IP, UserAgent: c.Request.UserAgent(), StatusCode: 401, }) diff --git a/backend/internal/server/middleware/session_binding_test.go b/backend/internal/server/middleware/session_binding_test.go new file mode 100644 index 000000000..2823dc6ee --- /dev/null +++ b/backend/internal/server/middleware/session_binding_test.go @@ -0,0 +1,103 @@ +//go:build unit + +package middleware + +import ( + "net/http/httptest" + "testing" + + "github.com/Wei-Shaw/sub2api/internal/config" + "github.com/Wei-Shaw/sub2api/internal/service" + + "github.com/gin-gonic/gin" + "github.com/stretchr/testify/require" +) + +// 反代场景：RemoteAddr 为 127.0.0.1，真实客户端 IP 在 X-Real-IP 中。 +// 会话绑定注入与审计 IP 必须与 API Key IP 限制共用「信任反代传递的客户端 IP」开关语义。 +func TestSessionBindingContextHonorsTrustForwardedToggle(t *testing.T) { + gin.SetMode(gin.TestMode) + + for _, tc := range []struct { + name string + trustForwarded bool + wantIP string + }{ + {name: "trust disabled records proxy address", trustForwarded: false, wantIP: "127.0.0.1"}, + {name: "trust enabled records forwarded client IP", trustForwarded: true, wantIP: "1.2.3.4"}, + } { + t.Run(tc.name, func(t *testing.T) { + cfg := &config.Config{} + cfg.SetTrustForwardedIPForAPIKeyACL(tc.trustForwarded) + + r := gin.New() + require.NoError(t, r.SetTrustedProxies(nil)) + r.Use(SessionBindingContext(cfg)) + r.GET("/t", func(c *gin.Context) { + binding := service.SessionBindingFromContext(c.Request.Context()) + require.NotNil(t, binding) + require.Equal(t, tc.wantIP, binding.IP) + require.Equal(t, "test-agent", binding.UserAgent) + require.Equal(t, tc.wantIP, SecurityClientIP(c)) + c.Status(200) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/t", nil) + req.RemoteAddr = "127.0.0.1:54321" + req.Header.Set("X-Real-IP", "1.2.3.4") + req.Header.Set("User-Agent", "test-agent") + r.ServeHTTP(w, req) + + require.Equal(t, 200, w.Code) + }) + } +} + +// 未经过 SessionBindingContext 注入时（异常挂载顺序/单测直调），回退 trusted_proxies 链， +// 等价于开关关闭时的历史行为。 +func TestSecurityClientIPFallsBackWithoutInjectedBinding(t *testing.T) { + gin.SetMode(gin.TestMode) + + r := gin.New() + require.NoError(t, r.SetTrustedProxies(nil)) + r.GET("/t", func(c *gin.Context) { + c.String(200, SecurityClientIP(c)) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/t", nil) + req.RemoteAddr = "9.9.9.9:12345" + req.Header.Set("X-Real-IP", "1.2.3.4") + r.ServeHTTP(w, req) + + require.Equal(t, 200, w.Code) + require.Equal(t, "9.9.9.9", w.Body.String()) +} + +// requestSessionBinding 优先取注入值：开关开启时校验哈希必须基于注入的转发 IP 计算， +// 与 token 签发路径取值一致，否则同一客户端会被误判为指纹变化。 +func TestRequestSessionBindingPrefersInjectedBinding(t *testing.T) { + gin.SetMode(gin.TestMode) + + cfg := &config.Config{} + cfg.SetTrustForwardedIPForAPIKeyACL(true) + + r := gin.New() + require.NoError(t, r.SetTrustedProxies(nil)) + r.Use(SessionBindingContext(cfg)) + r.GET("/t", func(c *gin.Context) { + issued := &service.SessionBinding{IP: "1.2.3.4", UserAgent: "test-agent"} + require.Equal(t, issued.Hash(), requestSessionBinding(c).Hash()) + c.Status(200) + }) + + w := httptest.NewRecorder() + req := httptest.NewRequest("GET", "/t", nil) + req.RemoteAddr = "127.0.0.1:54321" + req.Header.Set("X-Real-IP", "1.2.3.4") + req.Header.Set("User-Agent", "test-agent") + r.ServeHTTP(w, req) + + require.Equal(t, 200, w.Code) +} diff --git a/backend/internal/server/router.go b/backend/internal/server/router.go index 0030ee5cb..5396a94eb 100644 --- a/backend/internal/server/router.go +++ b/backend/internal/server/router.go @@ -54,8 +54,9 @@ func SetupRouter( // 应用中间件 r.Use(middleware2.RequestLogger()) - // 将可信客户端 IP + UA 注入 request context，供 token 签发路径写入会话绑定 - r.Use(middleware2.SessionBindingContext()) + // 将客户端 IP + UA 注入 request context，供 token 签发/会话绑定/审计日志统一读取。 + // IP 取值与 API Key IP 限制共用「信任反代传递的客户端 IP」系统开关。 + r.Use(middleware2.SessionBindingContext(cfg)) r.Use(middleware2.Logger()) r.Use(middleware2.CORS(cfg.CORS)) r.Use(middleware2.SecurityHeaders(cfg.Security.CSP, func() []string { diff --git a/frontend/src/i18n/locales/en/admin/settings.ts b/frontend/src/i18n/locales/en/admin/settings.ts index d6bfb88e0..f177122e7 100644 --- a/frontend/src/i18n/locales/en/admin/settings.ts +++ b/frontend/src/i18n/locales/en/admin/settings.ts @@ -146,10 +146,11 @@ export default { }, apiKeyAcl: { title: 'API Key IP Access Control', - description: 'Choose which client IP is used by API Key allowlists and denylists', + description: + 'Choose which client IP is used by API Key allowlists/denylists, admin audit logs, and session IP/UA binding', trustForwardedIp: 'Trust forwarded client IP', trustForwardedIpHint: - 'Disabled by default. Enable only when the origin is reachable only through Cloudflare or Nginx reverse proxy. When enabled, API Key IP allowlists and denylists use CF-Connecting-IP, X-Real-IP, or X-Forwarded-For, matching the request IP shown in usage records.' + 'Disabled by default. Enable only when the origin is reachable only through Cloudflare or Nginx reverse proxy. When enabled, API Key IP allowlists/denylists, admin audit logs, and session IP/UA binding use CF-Connecting-IP, X-Real-IP, or X-Forwarded-For, matching the request IP shown in usage records. Toggling this switch changes the IP fingerprint of existing sessions; with session binding enabled they must sign in again.' }, linuxdo: { title: 'LinuxDo Connect Login', diff --git a/frontend/src/i18n/locales/zh/admin/settings.ts b/frontend/src/i18n/locales/zh/admin/settings.ts index b62ffb508..3b4b56861 100644 --- a/frontend/src/i18n/locales/zh/admin/settings.ts +++ b/frontend/src/i18n/locales/zh/admin/settings.ts @@ -146,10 +146,10 @@ export default { }, apiKeyAcl: { title: 'API Key IP 访问控制', - description: '控制 API Key 白名单和黑名单使用哪个客户端 IP 判断', + description: '控制 API Key 白/黑名单、操作审计日志与会话 IP/UA 绑定使用哪个客户端 IP 判断', trustForwardedIp: '信任反代传递的客户端 IP', trustForwardedIpHint: - '默认关闭。仅在源站只允许 Cloudflare 或 Nginx 反代访问时开启；开启后 API Key IP 白/黑名单会使用 CF-Connecting-IP、X-Real-IP 或 X-Forwarded-For，与使用记录中的请求 IP 保持一致。' + '默认关闭。仅在源站只允许 Cloudflare 或 Nginx 反代访问时开启；开启后 API Key IP 白/黑名单、操作审计日志与会话 IP/UA 绑定会使用 CF-Connecting-IP、X-Real-IP 或 X-Forwarded-For，与使用记录中的请求 IP 保持一致。切换本开关会改变已登录会话的 IP 指纹，开启会话绑定时现有会话需重新登录。' }, linuxdo: { title: 'LinuxDo Connect 登录',