fix(security): mask IPv6 rate-limit keys to the routed /64

A single IPv6 client is delegated a whole /64 — the standard residential and
cloud allocation — so it can legitimately source every request from a different
address. Keying a per-IP throttle on the full /128 therefore left the exact
bypass this fix exists to close wide open over IPv6, with no header spoofing at
all: the proxy itself writes the varying value and nothing looks wrong.

Mask IPv6 to its routed prefix when producing a key, so one subscriber is one
bucket. Matches Better Auth's `ipv6Subnet` default, so session and throttle keys
agree. IPv4 is untouched — a v4 address is already a single host.

Masking happens only where a key is produced, never before the trusted-proxy
comparison, which must see the full address. `getAssertedOriginIp` stays
unmasked: the webhook allowlist needs the exact sender.

Also corrects what the docs claim about Better Auth. With no trusted proxies
configured it does not walk the chain — `getIPFromHeader` returns null for any
multi-value header — so the previous wording (and the env.ts line this replaces,
which had been accurate) overstated the agreement between the two. Each surface
now states where they align and where they deliberately differ, warns against a
trusted range broad enough to cover clients, and notes that none of it helps an
app exposed without a proxy.

- values.schema.json carried the same stale claim as values.yaml
- profound.ts compares against UNKNOWN_CLIENT_IP instead of a bare literal
- cover the env -> parseTrustedProxies wiring, which was globally mocked and so
  never executed in CI, and de-vacuum the IPv6/IPv4 kind-mismatch test

Author: waleedlatif1

apps/docs/app/api/chat/route.ts

@@ -71,8 +71,12 @@ const RATE_LIMIT_WINDOW_MS = 60_000
 const rateLimitHits = new Map<string, { count: number; resetAt: number }>()
 
 /**
- * Reverse-proxy hops trusted for forwarded-IP resolution — the same
- * `AUTH_TRUSTED_PROXIES` the main app reads. Parsed once at module load.
+ * Reverse-proxy hops trusted for forwarded-IP resolution, named after the main
+ * app's setting so the two behave alike where both are deployed. The docs site
+ * ships separately and does not normally set it, so this is usually empty —
+ * which is safe (the rightmost, proxy-written hop wins) but coarse: if the docs
+ * edge presents more than one hop, visitors share one bucket. Set it here too if
+ * that shows up as spurious 429s.
  */
 const trustedProxies = parseTrustedProxies(process.env.AUTH_TRUSTED_PROXIES)
 

apps/sim/.env.example

@@ -19,7 +19,7 @@ BETTER_AUTH_URL=http://localhost:3000
 NEXT_PUBLIC_APP_URL=http://localhost:3000
 # INTERNAL_API_BASE_URL=http://sim-app.default.svc.cluster.local:3000  # Optional: internal URL for server-side /api self-calls; defaults to NEXT_PUBLIC_APP_URL
 # TRUSTED_ORIGINS=https://www.example.com,https://app.example.com  # Optional: comma-separated additional public origins to trust for auth (apex+www, alias domains). Merged into Better Auth trustedOrigins.
-# AUTH_TRUSTED_PROXIES=10.0.0.0/24,192.0.2.10  # Optional: reverse-proxy IPs/CIDRs in front of the app. Better Auth and Sim's own per-IP throttles walk x-forwarded-for right to left, skip these hops, and use the first untrusted address as the client IP (the leftmost entry is caller-supplied and would otherwise let anyone mint a fresh rate-limit bucket per request). Unset trusts no hop and keys on the rightmost entry — safe, but a multi-hop chain collapses callers onto the edge addresses. Use your proxies' actual addresses, not broad private ranges that also cover clients.
+# AUTH_TRUSTED_PROXIES=10.0.0.0/24,192.0.2.10  # Optional: reverse-proxy IPs/CIDRs in front of the app. When set, Better Auth and Sim's own per-IP throttles both walk x-forwarded-for right to left, skip these hops, and use the first untrusted address as the client IP (the leftmost entry is caller-supplied and would otherwise let anyone mint a fresh rate-limit bucket per request). Unset, the two differ: Better Auth trusts only single-value headers, while Sim's throttles key on the rightmost, proxy-written entry — never spoofable, but a multi-hop chain collapses callers onto the edge addresses. Use your proxies' actual addresses, NOT broad private ranges that also cover clients: a caller whose own address falls inside a trusted range makes the whole chain trusted.
 
 # Chat (Optional)
 # COPILOT_API_KEY=                      # Mint one at https://sim.ai. Without it the Sim Chat block, prompt jobs, and Inbox cannot run

apps/sim/lib/analytics/profound.ts

@@ -6,6 +6,7 @@
  * @see https://docs.tryprofound.com/agent-analytics/custom
  */
 import { createLogger } from '@sim/logger'
+import { UNKNOWN_CLIENT_IP } from '@sim/security/client-ip'
 import { env } from '@/lib/core/config/env'
 import { isHosted } from '@/lib/core/config/env-flags'
 import { getClientIp } from '@/lib/core/utils/client-ip'
@@ -104,7 +105,7 @@ export function sendToProfound(request: Request, statusCode: number): void {
       status_code: statusCode,
       ip: (() => {
         const resolved = getClientIp(request)
-        return resolved === 'unknown' ? '0.0.0.0' : resolved
+        return resolved === UNKNOWN_CLIENT_IP ? '0.0.0.0' : resolved
       })(),
       user_agent: request.headers.get('user-agent') || '',
       ...(Object.keys(queryParams).length > 0 && { query_params: queryParams }),

apps/sim/lib/core/config/env.ts

@@ -507,7 +507,7 @@ export const env = createEnv({
     REACT_SCAN_ENABLED:                    z.boolean().optional(),                 // Enable React Scan for performance debugging (dev only)
 
     // Network / proxy trust
-    AUTH_TRUSTED_PROXIES:                  z.string().optional(),                  // Comma-separated reverse-proxy IPs or CIDR ranges. Better Auth and getClientIp (per-IP rate-limit keys, audit rows) walk the forwarded-IP chain right to left, skip these trusted hops, and use the first untrusted address as the client IP. Unset trusts no hop and keys on the rightmost, proxy-written entry — never the caller-supplied leftmost one.
+    AUTH_TRUSTED_PROXIES:                  z.string().optional(),                  // Comma-separated reverse-proxy IPs or CIDR ranges. When set, Better Auth and getClientIp (per-IP rate-limit keys, audit rows) both walk the forwarded-IP chain right to left, skip these trusted hops, and use the first untrusted address as the client IP. Leave unset and the two differ: Better Auth trusts only single-value IP headers (recording no IP for a multi-hop chain), while getClientIp keys on the rightmost, proxy-written entry — never the caller-supplied leftmost one.
 
     // SSO Configuration (for script-based registration)
     SSO_ENABLED:                           z.boolean().optional(),                 // Enable SSO functionality

apps/sim/lib/core/utils/client-ip.test.ts

@@ -0,0 +1,67 @@
+/**
+ * Covers the wiring between `AUTH_TRUSTED_PROXIES` and the shared resolver.
+ * `@/lib/core/utils/client-ip` is mocked globally in `vitest.setup.ts` (it is
+ * what every route consumes), so without the `vi.unmock` below the real module
+ * — and therefore the env read that makes trusted proxies take effect — would
+ * never execute anywhere in CI.
+ *
+ * @vitest-environment node
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { mockEnv } = vi.hoisted(() => ({
+  mockEnv: { AUTH_TRUSTED_PROXIES: undefined as string | undefined },
+}))
+
+vi.mock('@/lib/core/config/env', () => ({ env: mockEnv }))
+vi.unmock('@/lib/core/utils/client-ip')
+
+/**
+ * The module parses the env once at import — that is the behavior under test —
+ * so each case needs a fresh module instance. This is the deliberate exception
+ * to the repo's "no `vi.resetModules()` + dynamic import" performance rule
+ * (`.cursor/rules/sim-testing.mdc`): module-init behavior cannot be observed any
+ * other way, and the cost here is four imports of a six-line module.
+ */
+async function loadGetClientIp(trustedProxies: string | undefined) {
+  mockEnv.AUTH_TRUSTED_PROXIES = trustedProxies
+  vi.resetModules()
+  return (await import('@/lib/core/utils/client-ip')).getClientIp
+}
+
+function req(headers: Record<string, string>) {
+  return { headers: new Headers(headers) }
+}
+
+describe('getClientIp', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('keys on the proxy-appended hop, not the caller-supplied leftmost one', async () => {
+    const getClientIp = await loadGetClientIp(undefined)
+
+    expect(getClientIp(req({ 'x-forwarded-for': '203.0.113.7, 10.0.0.1' }))).toBe('10.0.0.1')
+  })
+
+  it('honors AUTH_TRUSTED_PROXIES, resolving past the configured hop', async () => {
+    const getClientIp = await loadGetClientIp('10.0.0.0/24')
+
+    expect(getClientIp(req({ 'x-forwarded-for': '203.0.113.7, 10.0.0.1' }))).toBe('203.0.113.7')
+  })
+
+  it('gives one bucket per caller no matter what they prepend', async () => {
+    const getClientIp = await loadGetClientIp(undefined)
+    const keys = ['9.9.9.9', 'unknown', '203.0.113.250'].map((spoof) =>
+      getClientIp(req({ 'x-forwarded-for': `${spoof}, 10.0.0.1` }))
+    )
+
+    expect(new Set(keys)).toEqual(new Set(['10.0.0.1']))
+  })
+
+  it('falls back to a shared bucket when no header yields an address', async () => {
+    const getClientIp = await loadGetClientIp(undefined)
+
+    expect(getClientIp(req({}))).toBe('unknown')
+  })
+})

apps/sim/lib/core/utils/client-ip.ts

@@ -6,9 +6,14 @@ import {
 import { env } from '@/lib/core/config/env'
 
 /**
- * Reverse-proxy hops trusted for forwarded-IP resolution, shared with Better
- * Auth's `advanced.ipAddress.trustedProxies` so session IPs and Sim's own
- * rate-limit keys agree on who the caller is. Parsed once at module load.
+ * Reverse-proxy hops trusted for forwarded-IP resolution, read from the same
+ * `AUTH_TRUSTED_PROXIES` as Better Auth's `advanced.ipAddress.trustedProxies`
+ * (see `lib/auth/auth.ts`). Parsed once at module load.
+ *
+ * Configured, the two agree on who the caller is. Left unset they diverge by
+ * design: Better Auth trusts only a single-value header and records no IP for a
+ * longer chain, whereas a throttle cannot opt out of having a key, so this falls
+ * back to the rightmost — still proxy-written, never caller-authored.
  */
 const trustedProxies = parseTrustedProxies(env.AUTH_TRUSTED_PROXIES)
 

docker-compose.prod.yml

@@ -21,15 +21,20 @@ services:
       # (apex + www, alias hostnames, reverse-proxy IPs). Empty by default.
       - TRUSTED_ORIGINS=${TRUSTED_ORIGINS:-}
       # AUTH_TRUSTED_PROXIES: comma-separated reverse-proxy IPs or CIDR ranges in
-      # front of the app (ingress, load balancer). Better Auth AND Sim's own
-      # per-IP throttles walk x-forwarded-for right to left, skip these hops, and
-      # use the first untrusted address as the client IP — never the leftmost
-      # entry, which the caller supplies and could otherwise rotate to mint a
-      # fresh rate-limit bucket per request. Empty by default, which trusts no
-      # hop and keys on the rightmost (proxy-written) entry: safe, but behind a
-      # multi-hop chain (e.g. CDN in front of ingress) it collapses callers onto
-      # the edge addresses. Set it to your real hops for per-client keying and
-      # correct session IPs.
+      # front of the app (ingress, load balancer). When set, Better Auth AND
+      # Sim's own per-IP throttles walk x-forwarded-for right to left, skip these
+      # hops, and use the first untrusted address as the client IP — never the
+      # leftmost entry, which the caller supplies and could otherwise be rotated
+      # to mint a fresh rate-limit bucket per request. Empty by default, and then
+      # the two differ: Better Auth trusts only a single-value header (recording
+      # no IP for a multi-hop chain), while Sim's throttles key on the rightmost
+      # (proxy-written) entry — not spoofable, but behind a multi-hop chain
+      # (e.g. CDN in front of ingress) it collapses callers onto the edge
+      # addresses. Set your real hops for per-client keying and correct session
+      # IPs. Use the proxies' actual addresses, NOT a broad private range that
+      # also covers clients: a caller inside a trusted range makes the whole
+      # chain trusted. This all assumes a proxy that appends the peer address —
+      # an app exposed directly to the internet sees only what the caller wrote.
       - AUTH_TRUSTED_PROXIES=${AUTH_TRUSTED_PROXIES:-}
       - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}
       - ENCRYPTION_KEY=${ENCRYPTION_KEY}

helm/sim/values.schema.json

@@ -157,7 +157,7 @@
             },
             "AUTH_TRUSTED_PROXIES": {
               "type": "string",
-              "description": "Comma-separated reverse-proxy IPs or CIDR ranges in front of the app (e.g. '10.0.0.0/16'). Better Auth walks x-forwarded-for right to left, skips these hops, and uses the first untrusted address as the client IP."
+              "description": "Comma-separated reverse-proxy IPs or CIDR ranges in front of the app (e.g. the ingress pods, '10.42.0.0/24'). When set, Better Auth and Sim's per-IP rate limits both walk x-forwarded-for right to left, skip these hops, and use the first untrusted address as the client IP. Leave empty and the two differ: Better Auth trusts only a single-value header, while Sim's throttles key on the rightmost, proxy-written entry. Do not use a range broad enough to also cover client traffic — a caller inside a trusted range makes the whole chain trusted."
             },
             "SSO_TRUSTED_PROVIDER_IDS": {
               "type": "string",

helm/sim/values.yaml

@@ -80,13 +80,16 @@ app:
     # Merged into Better Auth `trustedOrigins` alongside NEXT_PUBLIC_APP_URL. Leave empty when serving from a single origin.
     TRUSTED_ORIGINS: ""
     # AUTH_TRUSTED_PROXIES: comma-separated reverse-proxy IPs or CIDR ranges in front of the app
-    # (ingress controller, load balancer). Better Auth AND Sim's own per-IP throttles walk
-    # x-forwarded-for right to left, skip these hops, and use the first untrusted address as the
-    # client IP — never the leftmost entry, which the caller supplies and could otherwise be
-    # rotated to mint a fresh rate-limit bucket per request. Empty trusts no hop and keys on the
-    # rightmost (proxy-written) entry: safe, but behind a multi-hop chain (e.g. CDN in front of
-    # ingress) it collapses callers onto the edge addresses. Set your real hops (e.g. "10.0.0.0/16")
-    # for per-client keying and correct session IPs.
+    # (ingress controller, load balancer). When set, Better Auth AND Sim's own per-IP throttles
+    # walk x-forwarded-for right to left, skip these hops, and use the first untrusted address as
+    # the client IP — never the leftmost entry, which the caller supplies and could otherwise be
+    # rotated to mint a fresh rate-limit bucket per request. Empty, the two differ: Better Auth
+    # trusts only a single-value header (recording no IP for a multi-hop chain), while Sim's
+    # throttles key on the rightmost (proxy-written) entry — not spoofable, but behind a multi-hop
+    # chain (e.g. CDN in front of ingress) it collapses callers onto the edge addresses.
+    # Set the ingress pods' actual addresses (e.g. "10.42.0.0/24"). Do NOT use a range broad enough
+    # to also cover client traffic: a caller whose own address falls inside a trusted range makes
+    # the whole chain trusted and can then forge the value Sim keys on.
     AUTH_TRUSTED_PROXIES: ""
     # SOCKET_SERVER_URL: Auto-detected when realtime.enabled=true (uses internal service)
     # NEXT_PUBLIC_SOCKET_URL: public WebSocket URL for browsers. Leave empty to default to the

packages/security/src/client-ip.test.ts

@@ -27,12 +27,51 @@ describe('resolveClientIp', () => {
     })
 
     it('strips IPv6 zone ids so they cannot mint unbounded distinct keys', () => {
+      // `ipaddr.isValid` accepts an arbitrary-length zone and `process()` keeps
+      // it verbatim, so an unstripped zone would be attacker-chosen text in the
+      // key. The /64 mask happens to drop zones from v6 keys too — the
+      // getAssertedOriginIp cases below pin the stripping on its own, since
+      // that path is deliberately unmasked.
       const zoned = ['fe80::1%eth0', 'fe80::1%evil', `fe80::1%${'x'.repeat(200)}`].map((value) =>
         resolveClientIp(req({ 'x-forwarded-for': value }))
       )
-      expect(new Set(zoned)).toEqual(new Set(['fe80::1']))
-      expect(resolveClientIp(req({ 'x-real-ip': 'fe80::1%evil' }))).toBe('fe80::1')
-      expect(resolveClientIp(req({ 'x-forwarded-for': '[fe80::1%eth0]:8080' }))).toBe('fe80::1')
+      expect(new Set(zoned)).toEqual(new Set(['fe80::']))
+      expect(resolveClientIp(req({ 'x-real-ip': 'fe80::1%evil' }))).toBe('fe80::')
+      expect(canonicalizeIp('fe80::1%evil')).toBe('fe80::1')
+    })
+
+    it('masks IPv6 to its routed /64 so one subscriber is one bucket', () => {
+      // A single IPv6 client is delegated a whole /64, so the proxy honestly
+      // writes a different address per request. Keying on the full /128 would
+      // leave per-IP throttles bypassable with no spoofing at all.
+      const withinOnePrefix = [
+        '2001:db8:1:2::1',
+        '2001:db8:1:2::dead:beef',
+        '2001:db8:1:2:ffff:ffff:ffff:ffff',
+      ].map((value) => resolveClientIp(req({ 'x-forwarded-for': value })))
+      expect(new Set(withinOnePrefix)).toEqual(new Set(['2001:db8:1:2::']))
+    })
+
+    it('keeps distinct IPv6 /64s in distinct buckets', () => {
+      const a = resolveClientIp(req({ 'x-forwarded-for': '2001:db8:1:2::1' }))
+      const b = resolveClientIp(req({ 'x-forwarded-for': '2001:db8:1:3::1' }))
+      expect(a).not.toBe(b)
+    })
+
+    it('does not mask IPv4, which is already a single host', () => {
+      expect(resolveClientIp(req({ 'x-forwarded-for': '198.51.100.4' }))).toBe('198.51.100.4')
+    })
+
+    it('masks the x-real-ip fallback too', () => {
+      expect(resolveClientIp(req({ 'x-real-ip': '2001:db8:1:2::99' }))).toBe('2001:db8:1:2::')
+    })
+
+    it('matches a trusted range against the full address, not the masked key', () => {
+      // Masking before the trust check would compare a different address.
+      const trusted = parseTrustedProxies('2001:db8:1:2::abcd/128')
+      expect(
+        resolveClientIp(req({ 'x-forwarded-for': '203.0.113.7, 2001:db8:1:2::abcd' }), trusted)
+      ).toBe('203.0.113.7')
     })
 
     it('collapses equivalent spellings of one address onto a single value', () => {
@@ -86,10 +125,12 @@ describe('resolveClientIp', () => {
     })
 
     it('does not treat an IPv6 hop as matching an IPv4 trusted range', () => {
+      // Two hops, so a wrongly-trusted rightmost entry would visibly shift the
+      // answer left rather than merely avoiding a kind-mismatch throw.
       const trusted = parseTrustedProxies('0.0.0.0/0')
-      expect(resolveClientIp(req({ 'x-forwarded-for': '2001:db8::1' }), trusted)).toBe(
-        '2001:db8::1'
-      )
+      expect(
+        resolveClientIp(req({ 'x-forwarded-for': '2001:db8:1::1, 2001:db8:2::2' }), trusted)
+      ).toBe('2001:db8:2::')
     })
 
     it('matches an IPv4-mapped IPv6 trusted range against the unwrapped hop', () => {
@@ -113,11 +154,13 @@ describe('resolveClientIp', () => {
     })
 
     it('strips brackets and ports from IPv6 hops', () => {
-      expect(resolveClientIp(req({ 'x-forwarded-for': '[2001:db8::1]:8080' }))).toBe('2001:db8::1')
+      // Masked to /64 like every IPv6 key; unmasked forms are covered by
+      // getAssertedOriginIp below.
+      expect(resolveClientIp(req({ 'x-forwarded-for': '[2001:db8::1]:8080' }))).toBe('2001:db8::')
     })
 
-    it('preserves a bare IPv6 literal', () => {
-      expect(resolveClientIp(req({ 'x-forwarded-for': '2001:db8::1' }))).toBe('2001:db8::1')
+    it('accepts a bare IPv6 literal', () => {
+      expect(resolveClientIp(req({ 'x-forwarded-for': '2001:db8::1' }))).toBe('2001:db8::')
     })
 
     it('skips unparseable hops while walking right to left', () => {
@@ -186,6 +229,19 @@ describe('getAssertedOriginIp', () => {
     ).toBe('203.0.113.7')
   })
 
+  it('does not mask IPv6 — an allowlist needs the exact address', () => {
+    expect(getAssertedOriginIp(req({ 'x-forwarded-for': '2001:db8:1:2::99' }))).toBe(
+      '2001:db8:1:2::99'
+    )
+  })
+
+  it('strips brackets, ports, and zone ids like the resolver does', () => {
+    expect(getAssertedOriginIp(req({ 'x-forwarded-for': '[2001:db8::1%eth0]:8080' }))).toBe(
+      '2001:db8::1'
+    )
+    expect(getAssertedOriginIp(req({ 'x-forwarded-for': '203.0.113.7:4444' }))).toBe('203.0.113.7')
+  })
+
   it('returns null when no header yields an address', () => {
     expect(getAssertedOriginIp(req({}))).toBeNull()
     expect(getAssertedOriginIp(req({ 'x-forwarded-for': 'unknown' }))).toBeNull()