Skip to content

The only tool you need to know what is happening and how to fix it.

feat: add TRUSTED_PROXIES + TRUSTED_PROXY_HEADER for real client IP resolution (#297)

Kennan LeJeune8da0f0b2a2d3
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 header
CLICKHOUSE_SERVER=localhost:9000
CLICKHOUSE_DATABASE=traceway
CLICKHOUSE_USERNAME=default
diff --git a/backend/app/config/config.go b/backend/app/config/config.go
index bee7cb9a..83f35059 100644
--- a/backend/app/config/config.go
+++ b/backend/app/config/config.go
@@ -3,6 +3,7 @@ package config
import (
"os"
"strconv"
+ "strings"
"time"
)
@@ -84,6 +85,8 @@ type Cfg struct {
SMTPFrom string
AppBaseURL string
+ TrustedProxies string
+ TrustedProxyHeader string
EmailPreviewEnabled string
CloudMode string
MonitoringTracewayURL 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.go
new file mode 100644
index 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.go
index 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.go
new file mode 100644
index 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.mdx
index 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.mdx
index 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.mdx
index 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.mdx
index 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.yaml
index 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: v1
kind: ConfigMap
metadata:
@@ -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.yaml
index 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: ""