The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
feat: add TRUSTED_PROXIES + TRUSTED_PROXY_HEADER for real client IP resolution (#297)
Kennan LeJeune8da0f0b2a2d3
diff --git a/CLAUDE.md b/CLAUDE.mdindex cab4089b..2ca99993 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -242,6 +242,8 @@ if err != nil {```JWT_SECRET=<min 32 char secret for JWT signing>APP_BASE_URL= # public origin of this server (e.g. https://traceway.example.com). Used as the OAuth issuer / device verification URL and SSO redirect base. If unset, the device-auth + well-known endpoints derive it per-request from the Host / X-Forwarded-* headers; set it explicitly behind a proxy that doesn't forward Host.+TRUSTED_PROXIES=127.0.0.1,::1 # comma-separated IPs/CIDRs of reverse proxies whose X-Forwarded-For gin trusts when resolving c.ClientIP(), the per-IP rate-limit key (cmd/run.go SetTrustedProxies via cfg.TrustedProxyList; default loopback so a direct client cannot spoof it, "*" restores gin's trust-everything behavior). The unauthenticated credential endpoints sit behind middleware.RateLimitPerIP — budgets live in routes.go — placed before Transactional so throttled requests never open a transaction.+TRUSTED_PROXY_HEADER= # optional header trusted verbatim as the client IP (gin TrustedPlatform, e.g. X-Real-IP behind ingress-nginx, CF-Connecting-IP behind Cloudflare); takes precedence over TRUSTED_PROXIES. Only safe when every request path goes through a proxy that overwrites the headerCLICKHOUSE_SERVER=localhost:9000CLICKHOUSE_DATABASE=tracewayCLICKHOUSE_USERNAME=defaultdiff --git a/backend/app/config/config.go b/backend/app/config/config.goindex bee7cb9a..83f35059 100644--- a/backend/app/config/config.go+++ b/backend/app/config/config.go@@ -3,6 +3,7 @@ package configimport ("os""strconv"+ "strings""time")@@ -84,6 +85,8 @@ type Cfg struct {SMTPFrom stringAppBaseURL string+ TrustedProxies string+ TrustedProxyHeader stringEmailPreviewEnabled stringCloudMode stringMonitoringTracewayURL string@@ -136,6 +139,26 @@ func (c *Cfg) PasswordLoginDisabled() bool {return c.DisablePasswordLogin == "true"}+// TrustedProxyList returns the proxy IPs/CIDRs whose X-Forwarded-For gin may+// trust when resolving c.ClientIP() for per-IP rate limiters.+// Defaults to loopback so a direct client can't spoof a bypass+func (c *Cfg) TrustedProxyList() []string {+ raw := strings.TrimSpace(c.TrustedProxies)+ if raw == "" {+ return []string{"127.0.0.1", "::1"}+ }+ if raw == "*" {+ return []string{"0.0.0.0/0", "::/0"}+ }+ var proxies []string+ for _, p := range strings.Split(raw, ",") {+ if p = strings.TrimSpace(p); p != "" {+ proxies = append(proxies, p)+ }+ }+ return proxies+}+// TwilioEnabled reports whether SMS sending is configured: account credentials// plus at least one sender (a from-number or a messaging service).func (c *Cfg) TwilioEnabled() bool {@@ -222,6 +245,8 @@ func LoadFromEnv() *Cfg {SMTPFrom: os.Getenv("SMTP_FROM"),AppBaseURL: os.Getenv("APP_BASE_URL"),+ TrustedProxies: os.Getenv("TRUSTED_PROXIES"),+ TrustedProxyHeader: os.Getenv("TRUSTED_PROXY_HEADER"),EmailPreviewEnabled: os.Getenv("EMAIL_PREVIEW_ENABLED"),CloudMode: os.Getenv("CLOUD_MODE"),MonitoringTracewayURL: os.Getenv("MONITORING_TRACEWAY_URL"),diff --git a/backend/app/config/config_test.go b/backend/app/config/config_test.gonew file mode 100644index 00000000..f5c73e6c--- /dev/null+++ b/backend/app/config/config_test.go@@ -0,0 +1,28 @@+package config++import (+ "slices"+ "testing"+)++func TestTrustedProxyList(t *testing.T) {+ tests := []struct {+ name string+ value string+ want []string+ }{+ {"default is loopback", "", []string{"127.0.0.1", "::1"}},+ {"whitespace only is loopback", " ", []string{"127.0.0.1", "::1"}},+ {"wildcard trusts everything", "*", []string{"0.0.0.0/0", "::/0"}},+ {"list with spaces and empty entries", " 10.0.0.1, 192.168.0.0/16,, ", []string{"10.0.0.1", "192.168.0.0/16"}},+ {"only separators trusts nobody", ",,", nil},+ }+ for _, tt := range tests {+ t.Run(tt.name, func(t *testing.T) {+ c := &Cfg{TrustedProxies: tt.value}+ if got := c.TrustedProxyList(); !slices.Equal(got, tt.want) {+ t.Errorf("TrustedProxyList(%q) = %v, want %v", tt.value, got, tt.want)+ }+ })+ }+}diff --git a/backend/cmd/run.go b/backend/cmd/run.goindex e65954a9..d2b91b0d 100644--- a/backend/cmd/run.go+++ b/backend/cmd/run.go@@ -182,6 +182,10 @@ func Run(opts ...Option) {router = gin.Default()}+ if err := configureClientIP(router, cfg); err != nil {+ panic(fmt.Errorf("invalid TRUSTED_PROXIES: %w", err))+ }+if monitoringTracewayUrl := cfg.MonitoringTracewayURL; monitoringTracewayUrl != "" {twmw := tracewaygin.New(monitoringTracewayUrl,@@ -291,6 +295,19 @@ func Run(opts ...Option) {}}+func configureClientIP(router *gin.Engine, cfg *config.Cfg) error {+ // Gin trusts X-Forwarded-For from any peer by default, which would let a+ // direct client pick its own ClientIP() and rotate out of the per-IP limits.+ if err := router.SetTrustedProxies(cfg.TrustedProxyList()); err != nil {+ return err+ }+ // Taken verbatim as the client IP when present, bypassing the proxy list —+ // only safe when every path to the backend runs through a proxy that+ // overwrites the header (e.g. ingress-nginx X-Real-IP, CF-Connecting-IP).+ router.TrustedPlatform = cfg.TrustedProxyHeader+ return nil+}+// applyEnvOverrides forwards env vars to a config the embedded Run(opts...)// path built without LoadFromEnv; new Cfg fields belong in this table.func applyEnvOverrides(cfg *config.Cfg) {@@ -316,6 +333,8 @@ func applyEnvOverrides(cfg *config.Cfg) {{"SYNTHETICS_SCREENSHOT_RETENTION_DAYS", &cfg.SyntheticsScreenshotRetentionDays},{"SYNTHETICS_RUNNER_SECRET", &cfg.SyntheticsRunnerSecret},{"HEALTH_DEEP_TOKEN", &cfg.HealthDeepToken},+ {"TRUSTED_PROXIES", &cfg.TrustedProxies},+ {"TRUSTED_PROXY_HEADER", &cfg.TrustedProxyHeader},{"TWILIO_ACCOUNT_SID", &cfg.TwilioAccountSID},{"TWILIO_AUTH_TOKEN", &cfg.TwilioAuthToken},{"TWILIO_FROM_NUMBER", &cfg.TwilioFromNumber},diff --git a/backend/cmd/run_test.go b/backend/cmd/run_test.gonew file mode 100644index 00000000..63c5216b--- /dev/null+++ b/backend/cmd/run_test.go@@ -0,0 +1,72 @@+package cmd++import (+ "net/http"+ "net/http/httptest"+ "testing"++ "github.com/gin-gonic/gin"+ "github.com/tracewayapp/traceway/backend/app/config"+)++func TestConfigureClientIPRejectsForwardingHeadersFromUntrustedPeers(t *testing.T) {+ router := clientIPRouter(t, &config.Cfg{})+ request := httptest.NewRequest(http.MethodGet, "/", nil)+ request.RemoteAddr = "203.0.113.10:1234"+ request.Header.Set("X-Forwarded-For", "198.51.100.20")+ response := httptest.NewRecorder()++ router.ServeHTTP(response, request)++ if got := response.Body.String(); got != "203.0.113.10" {+ t.Fatalf("ClientIP() = %q, want direct peer address", got)+ }+}++func TestConfigureClientIPAcceptsForwardingHeadersFromTrustedPeers(t *testing.T) {+ router := clientIPRouter(t, &config.Cfg{TrustedProxies: "10.0.0.0/8"})+ request := httptest.NewRequest(http.MethodGet, "/", nil)+ request.RemoteAddr = "10.1.2.3:1234"+ request.Header.Set("X-Forwarded-For", "198.51.100.20")+ response := httptest.NewRecorder()++ router.ServeHTTP(response, request)++ if got := response.Body.String(); got != "198.51.100.20" {+ t.Fatalf("ClientIP() = %q, want forwarded client address", got)+ }+}++func TestConfigureClientIPUsesExplicitTrustedPlatformHeader(t *testing.T) {+ router := clientIPRouter(t, &config.Cfg{TrustedProxyHeader: "CF-Connecting-IP"})+ request := httptest.NewRequest(http.MethodGet, "/", nil)+ request.RemoteAddr = "203.0.113.10:1234"+ request.Header.Set("CF-Connecting-IP", "198.51.100.20")+ response := httptest.NewRecorder()++ router.ServeHTTP(response, request)++ if got := response.Body.String(); got != "198.51.100.20" {+ t.Fatalf("ClientIP() = %q, want trusted platform address", got)+ }+}++func TestConfigureClientIPRejectsInvalidTrustedProxy(t *testing.T) {+ router := gin.New()+ if err := configureClientIP(router, &config.Cfg{TrustedProxies: "not-a-cidr"}); err == nil {+ t.Fatal("configureClientIP accepted an invalid proxy")+ }+}++func clientIPRouter(t *testing.T, cfg *config.Cfg) *gin.Engine {+ t.Helper()+ gin.SetMode(gin.TestMode)+ router := gin.New()+ if err := configureClientIP(router, cfg); err != nil {+ t.Fatalf("configure client IP: %v", err)+ }+ router.GET("/", func(c *gin.Context) {+ c.String(http.StatusOK, c.ClientIP())+ })+ return router+}diff --git a/docs/pages/server/all-in-one.mdx b/docs/pages/server/all-in-one.mdxindex d792ebb7..397c0144 100644--- a/docs/pages/server/all-in-one.mdx+++ b/docs/pages/server/all-in-one.mdx@@ -62,6 +62,8 @@ All environment variables have working defaults, no configuration required. Over| `JWT_SECRET` | *(built-in default, **override in production**)* | Signs all authentication tokens: dashboard sessions and CLI/MCP device logins. The built-in default is public; set a strong unique secret (min 32 chars, `openssl rand -hex 32`) and keep it stable. See [CLI Authentication](/learn/cli-auth#set-a-strong-jwt_secret). || `GIN_MODE` | `release` | Gin framework mode || `APP_BASE_URL` | *(none)* | Public URL of your Traceway instance (e.g. `https://traceway.example.com`). Used for SDK setup instructions, email links, OAuth callback URLs, and the CLI/MCP OAuth issuer plus device-login verification URL. If unset, the device-auth and `/.well-known` endpoints derive it per-request from the `Host` / `X-Forwarded-*` headers; set it explicitly behind a proxy that rewrites `Host`. See [CLI Authentication](/learn/cli-auth). |+| `TRUSTED_PROXIES` | `127.0.0.1,::1` | Comma-separated IPs/CIDRs of reverse proxies whose `X-Forwarded-For` is trusted when resolving the client IP for the per-IP rate limits (login, registration, password reset, device auth, public status pages). The loopback default covers a proxy on the same host; add your proxy's address or network (e.g. `172.16.0.0/12` for Docker bridge networks) when it connects from elsewhere, or `*` to trust any peer — which lets clients spoof their IP and rotate out of the limits. |+| `TRUSTED_PROXY_HEADER` | *(none)* | A header trusted verbatim as the client IP, taking precedence over `TRUSTED_PROXIES` — e.g. `X-Real-IP` behind ingress-nginx or `CF-Connecting-IP` behind Cloudflare. Only safe when every request provably passes through a proxy that overwrites the header; a directly reachable backend lets clients set it freely. || `STORAGE_TYPE` | `local` | Blob storage backend for source maps, session recordings, and AI traces: `local` or `s3`. See [Blob Storage](/server/storage) for the S3 variables. || `STORAGE_PATH` | `./storage` | Folder for local blob storage, `/app/storage` in this image. Mount a volume there. Ignored when `STORAGE_TYPE=s3`. || `SESSION_RECORDING_RETENTION_DAYS` | `30` | Days to keep session recording files on disk under `STORAGE_PATH/recordings/`. Files older than the TTL are deleted hourly and on startup. No effect when `STORAGE_TYPE=s3`. Set to `0` to disable. |diff --git a/docs/pages/server/docker-compose.mdx b/docs/pages/server/docker-compose.mdxindex d7781e21..52f0fb15 100644--- a/docs/pages/server/docker-compose.mdx+++ b/docs/pages/server/docker-compose.mdx@@ -100,6 +100,8 @@ Edit the environment variables in your compose file as needed:| `POSTGRES_SSLMODE` | `disable` | PostgreSQL SSL mode || `JWT_SECRET` | `change-this-to-a-secure-secret-at-least-32-chars` | Signs all authentication tokens (dashboard sessions and CLI/MCP device logins). Replace the placeholder with a strong, unique secret of at least 32 chars (`openssl rand -hex 32`) and keep it stable. See [CLI Authentication](/learn/cli-auth#set-a-strong-jwt_secret). || `APP_BASE_URL` | *(none)* | Public URL of your Traceway instance (e.g. `https://traceway.example.com`). Used for SDK setup instructions, email links, OAuth callback URLs, and the CLI/MCP OAuth issuer plus device-login verification URL. If unset, the device-auth and `/.well-known` endpoints derive it per-request from the `Host` / `X-Forwarded-*` headers; set it explicitly behind a proxy that rewrites `Host`. See [CLI Authentication](/learn/cli-auth). |+| `TRUSTED_PROXIES` | `127.0.0.1,::1` | Comma-separated IPs/CIDRs of reverse proxies whose `X-Forwarded-For` is trusted when resolving the client IP for the per-IP rate limits (login, registration, password reset, device auth, public status pages). The loopback default covers a proxy on the same host; add your proxy's address or network (e.g. `172.16.0.0/12` for Docker bridge networks) when it connects from elsewhere, or `*` to trust any peer — which lets clients spoof their IP and rotate out of the limits. |+| `TRUSTED_PROXY_HEADER` | *(none)* | A header trusted verbatim as the client IP, taking precedence over `TRUSTED_PROXIES` — e.g. `X-Real-IP` behind ingress-nginx or `CF-Connecting-IP` behind Cloudflare. Only safe when every request provably passes through a proxy that overwrites the header; a directly reachable backend lets clients set it freely. || `STORAGE_TYPE` | `local` | Blob storage backend for source maps, session recordings, and AI traces: `local` or `s3`. See [Blob Storage](/server/storage) for the S3 variables. || `STORAGE_PATH` | `./storage` | Folder for local blob storage, `/app/storage` in the minimal image. Mount a volume there. Ignored when `STORAGE_TYPE=s3`. || `SESSION_RECORDING_RETENTION_DAYS` | `30` | Days to keep session recording files on disk under `STORAGE_PATH/recordings/`. A worker deletes older files hourly and on startup. No effect when `STORAGE_TYPE=s3`. Set to `0` to disable. |diff --git a/docs/pages/server/minimal.mdx b/docs/pages/server/minimal.mdxindex fd8cc485..b721b60e 100644--- a/docs/pages/server/minimal.mdx+++ b/docs/pages/server/minimal.mdx@@ -58,6 +58,8 @@ Then use `traceway:minimal` instead of `ghcr.io/tracewayapp/traceway:minimal` in| `POSTGRES_SSLMODE` | PostgreSQL SSL mode | `disable` || `JWT_SECRET` | Signs all authentication tokens (dashboard sessions and CLI/MCP device logins). Use a strong, unique secret of at least 32 chars; keep it stable. See [CLI Authentication](/learn/cli-auth#set-a-strong-jwt_secret). | `your-secret-here` || `APP_BASE_URL` | Public URL of your instance. Used for SDK setup instructions, email links, OAuth callback URLs, and the CLI/MCP OAuth issuer plus device-login verification URL. If unset, derived per-request from `Host` / `X-Forwarded-*`. | `https://traceway.example.com` |+| `TRUSTED_PROXIES` | Comma-separated IPs/CIDRs of reverse proxies whose `X-Forwarded-For` is trusted when resolving the client IP for the per-IP rate limits. Defaults to loopback (`127.0.0.1,::1`); add your proxy's address or network when it connects from elsewhere, or `*` to trust any peer (lets clients spoof their IP past the limits). | `172.16.0.0/12` |+| `TRUSTED_PROXY_HEADER` | A header trusted verbatim as the client IP, taking precedence over `TRUSTED_PROXIES` — e.g. behind ingress-nginx or Cloudflare. Only safe when every request provably passes through a proxy that overwrites the header. | `X-Real-IP` || `STORAGE_TYPE` | Blob storage backend for source maps, session recordings, and AI traces: `local` (default) or `s3`. See [Blob Storage](/server/storage) for the S3 variables. | `local` || `STORAGE_PATH` | Folder for local blob storage. Defaults to `./storage`, which is `/app/storage` in this image. Mount a volume there. Ignored when `STORAGE_TYPE=s3`. | `/app/storage` || `SESSION_RECORDING_RETENTION_DAYS` | Days to keep on-disk session recordings under `STORAGE_PATH/recordings/`. Defaults to `30`. Worker runs hourly and on startup. `0` disables; no effect when `STORAGE_TYPE=s3`. | `30` |diff --git a/docs/pages/server/sqlite.mdx b/docs/pages/server/sqlite.mdxindex 2a21dfd6..96e41d24 100644--- a/docs/pages/server/sqlite.mdx+++ b/docs/pages/server/sqlite.mdx@@ -62,6 +62,8 @@ If `STORAGE_TYPE` is unset (or set to `local`), blobs are written to `/data/stor|----------|---------|-------------|| `JWT_SECRET` | *(required)* | Signs all authentication tokens (dashboard sessions and CLI/MCP device logins). Use a strong, unique secret of at least 32 characters (`openssl rand -hex 32`) and keep it stable. See [CLI Authentication](/learn/cli-auth#set-a-strong-jwt_secret). || `APP_BASE_URL` | *(unset)* | Public URL of your instance. Used for SDK setup snippets, password-reset emails, OAuth callback URLs, and the CLI/MCP OAuth issuer plus device-login verification URL. If unset, the device-auth and `/.well-known` endpoints derive it per-request from the `Host` / `X-Forwarded-*` headers. See [CLI Authentication](/learn/cli-auth) |+| `TRUSTED_PROXIES` | `127.0.0.1,::1` | Comma-separated IPs/CIDRs of reverse proxies whose `X-Forwarded-For` is trusted when resolving the client IP for the per-IP rate limits (login, registration, password reset, device auth, public status pages). The loopback default covers a proxy on the same host; add your proxy's address or network (e.g. `172.16.0.0/12` for Docker bridge networks) when it connects from elsewhere, or `*` to trust any peer — which lets clients spoof their IP and rotate out of the limits |+| `TRUSTED_PROXY_HEADER` | *(none)* | A header trusted verbatim as the client IP, taking precedence over `TRUSTED_PROXIES` — e.g. `X-Real-IP` behind ingress-nginx or `CF-Connecting-IP` behind Cloudflare. Only safe when every request provably passes through a proxy that overwrites the header || `SQLITE_PATH` | `/data/traceway.db` | Main SQLite file. Telemetry DB is derived as `<path>_telemetry.db` || `STORAGE_TYPE` | `local` | Blob storage backend. `local` or `s3` || `STORAGE_PATH` | `/data/storage` | Folder for local blob storage. Ignored when `STORAGE_TYPE=s3` |diff --git a/helm/traceway/templates/configmap.yaml b/helm/traceway/templates/configmap.yamlindex c48e771c..6c14589f 100644--- a/helm/traceway/templates/configmap.yaml+++ b/helm/traceway/templates/configmap.yaml@@ -1,3 +1,6 @@+{{- if and .Values.ingress.enabled (not .Values.app.trustedProxies) (not .Values.app.trustedProxyHeader) }}+{{- fail "set app.trustedProxies or app.trustedProxyHeader when ingress.enabled=true so clients do not share the ingress controller's rate-limit bucket" }}+{{- end }}apiVersion: v1kind: ConfigMapmetadata:@@ -44,6 +47,12 @@ data:{{- if .Values.app.baseURL }}APP_BASE_URL: {{ .Values.app.baseURL | quote }}{{- end }}+ {{- if .Values.app.trustedProxies }}+ TRUSTED_PROXIES: {{ .Values.app.trustedProxies | quote }}+ {{- end }}+ {{- if .Values.app.trustedProxyHeader }}+ TRUSTED_PROXY_HEADER: {{ .Values.app.trustedProxyHeader | quote }}+ {{- end }}{{- if .Values.app.apiOnly }}API_ONLY: {{ .Values.app.apiOnly | quote }}{{- end }}diff --git a/helm/traceway/values.yaml b/helm/traceway/values.yamlindex 4a10670a..4c45ecf2 100644--- a/helm/traceway/values.yaml+++ b/helm/traceway/values.yaml@@ -62,6 +62,15 @@ app:jwtSecret: ""# Optional. Base URL used in password reset emails, e.g. "https://traceway.example.com"baseURL: ""+ # Comma-separated IPs/CIDRs of proxies whose X-Forwarded-For is trusted for+ # per-IP rate limiting, or "*". Defaults to loopback. Required when ingress+ # is enabled unless trustedProxyHeader is set; use the controller's pod CIDR.+ trustedProxies: ""+ # Alternative for ingress. A header trusted verbatim as the client IP, e.g. "X-Real-IP"+ # (overwritten by ingress-nginx on every request) or "CF-Connecting-IP".+ # Takes precedence over trustedProxies. Only safe when a NetworkPolicy+ # forces all traffic through the proxy that overwrites the header.+ trustedProxyHeader: ""# Optional. Set to "true" to serve only the API without the embedded frontend.apiOnly: ""