fix(network): resolve IPv6 at /128 for allowlist matching (was masked to /64); document self-host proxy/break-glass/fail-open

Author: waleedlatif1

apps/docs/content/docs/en/platform/enterprise/ip-access.mdx

@@ -3,6 +3,7 @@ title: IP Access
 description: Restrict sign-in and API access to your organization's allowed IP ranges
 ---
 
+import { Callout } from 'fumadocs-ui/components/callout'
 import { FAQ } from '@/components/ui/faq'
 
 IP Access lets organization owners and admins on Enterprise plans restrict where members can use Sim from. When the allowlist is enabled, sign-in, session use, API-key requests, and live collaboration connections are only accepted from the listed addresses.
@@ -30,6 +31,22 @@ Deployed chats, public form shares, webhooks, and scheduled executions are **not
 
 Policy changes and denied access attempts are recorded in the [audit log](/platform/enterprise/audit-logs) — denials include the member and the blocked address, throttled per member so a polling client cannot flood the log.
 
+IPv6 addresses are matched at full precision, so you can allow an exact host (`2001:db8::1`) or a subnet (`2001:db8::/64`). Because IPv6 clients often rotate within their `/64`, allowing the `/64` is usually the more robust choice.
+
+---
+
+## Self-hosting
+
+<Callout type="warning">
+  IP access fails **closed**: when a policy is active and Sim cannot determine a trustworthy client address, the request is denied. A misconfigured proxy chain will therefore lock out your organization. Configure the two settings below before enabling a policy.
+</Callout>
+
+- **`AUTH_TRUSTED_PROXIES`** — the reverse-proxy IPs or CIDR ranges in front of Sim (your load balancer / ingress), comma-separated, for example `AUTH_TRUSTED_PROXIES=10.0.0.0/16`. Sim walks the `x-forwarded-for` chain right to left, skips these trusted hops, and uses the first untrusted address as the client IP — so forwarded headers cannot be forged. If this is unset (or wrong) behind a multi-hop proxy, no client address can be derived and every request is denied while a policy is active. The settings page's lockout guard also refuses to *enable* a policy when your own address is unresolvable, which is the first symptom of a missing value.
+- **`NODE_ENV=production`** — outside production, the auth layer resolves every client to `127.0.0.1`, so an allowlist that does not contain `127.0.0.1` would deny everyone. Run production deployments with `NODE_ENV=production`.
+- **`DISABLE_ORG_IP_ALLOWLIST=true`** — the break-glass. Setting it (read at request time, no restart needed) skips IP-allowlist enforcement across the app and realtime processes, restoring access if a policy or proxy misconfiguration locks the organization out. Remove it once the allowlist is corrected.
+
+Enforcement reads the compiled policy from a short-lived in-process cache, so a policy change (or a plan change) takes effect within about a minute across the fleet. If the database is briefly unreachable the policy resolver **fails open** (allows the request) rather than locking the whole organization out of the product on a transient blip — the primary boundary (an active policy that rejects an address) stays fail-closed.
+
 ---
 
 ## FAQ
@@ -44,7 +61,7 @@ Policy changes and denied access attempts are recorded in the [audit log](/platf
     {
       question: 'Can I lock myself out?',
       answer:
-        'Not in a single save — the settings page rejects any list that excludes your current IP. If your network changes afterwards, another admin on an allowed network (or Sim support) can update the list.',
+        'Not in a single save — the settings page rejects any list that excludes your current IP. If your network changes afterwards, another admin on an allowed network can update the list. Self-hosted operators can set DISABLE_ORG_IP_ALLOWLIST=true as a break-glass to restore access (see Self-hosting above).',
     },
     {
       question: 'Does this affect deployed chats and webhooks?',

apps/sim/lib/auth/auth.ts

@@ -675,11 +675,16 @@ export const auth = betterAuth({
           }
 
           // Org IP allowlists must block session establishment, not just
-          // later requests. `session.ipAddress` is Better Auth's
-          // trusted-proxy-resolved client address. Thrown APIErrors must
-          // propagate — deliberately outside the try below.
+          // later requests. Resolve the client IP the same way the request
+          // path does (full-precision, via getTrustedClientIp) rather than
+          // Better Auth's `session.ipAddress`, which is masked to /64 for
+          // rate-limit keying and would reject exact IPv6 hosts. Thrown
+          // APIErrors must propagate — deliberately outside the try below.
           if (!session.impersonatedBy) {
-            const network = await enforceOrgNetworkPolicy(session.userId, () => session.ipAddress)
+            const signInHeaders = await headers()
+            const network = await enforceOrgNetworkPolicy(session.userId, () =>
+              getTrustedClientIp(new Request('http://localhost/', { headers: signInHeaders }))
+            )
             if (!network.allowed) {
               logger.warn('Blocking session creation by org network policy', {
                 userId: session.userId,

apps/sim/lib/auth/network-policy-resolution.test.ts

@@ -0,0 +1,52 @@
+/**
+ * @vitest-environment node
+ *
+ * Integration test for the client-IP RESOLUTION layer that the matcher's own
+ * unit tests bypass: Better Auth's `getIp` (which masks IPv6 to `ipv6Subnet`)
+ * composed with `buildIpResolutionOptions` and the allowlist matcher. Guards
+ * against IPv6 addresses being silently collapsed to /64 before matching,
+ * which would make exact-host (/128) entries impossible in production.
+ */
+import { getIp } from '@better-auth/core/utils/ip'
+import {
+  buildIpResolutionOptions,
+  compileAllowlist,
+  isAddressAllowed,
+  parseTrustedProxies,
+} from '@sim/platform-authz/network'
+import { describe, expect, it } from 'vitest'
+
+const OPTIONS = buildIpResolutionOptions(parseTrustedProxies(undefined))
+
+function resolve(forwardedFor: string): string | null {
+  const headers = new Headers({ 'x-forwarded-for': forwardedFor })
+  return getIp(new Request('http://localhost/', { headers }), OPTIONS)
+}
+
+describe('network-policy IP resolution', () => {
+  it('resolves IPv6 at full /128 precision (not masked to /64)', () => {
+    // If ipv6Subnet defaulted to 64, this would return 2001:db8:1234:5678::.
+    const resolved = resolve('2001:db8:1234:5678::1')
+    expect(resolved).not.toBeNull()
+    expect(isAddressAllowed(resolved as string, compileAllowlist(['2001:db8:1234:5678::1']))).toBe(
+      true
+    )
+  })
+
+  it('does not let a different host in the same /64 match an exact /128 entry', () => {
+    const resolved = resolve('2001:db8:1234:5678::99')
+    expect(isAddressAllowed(resolved as string, compileAllowlist(['2001:db8:1234:5678::1']))).toBe(
+      false
+    )
+    // …but a /64 entry covers the whole subnet.
+    expect(
+      isAddressAllowed(resolved as string, compileAllowlist(['2001:db8:1234:5678::/64']))
+    ).toBe(true)
+  })
+
+  it('resolves IPv4 unchanged', () => {
+    const resolved = resolve('203.0.113.7')
+    expect(resolved).toBe('203.0.113.7')
+    expect(isAddressAllowed(resolved as string, compileAllowlist(['203.0.113.0/24']))).toBe(true)
+  })
+})

packages/platform-authz/src/network.ts

@@ -214,14 +214,26 @@ export function parseTrustedProxies(raw: string | undefined): string[] {
 
 /**
  * Builds the `advanced.ipAddress` options object Better Auth's `getIp`
- * expects from a parsed trusted-proxy list.
+ * expects from a parsed trusted-proxy list, for NETWORK-POLICY resolution.
+ *
+ * `ipv6Subnet: 128` overrides Better Auth's `/64` default so IPv6 client
+ * addresses are matched at full host precision — the allowlist supports exact
+ * IPv6 hosts and `/128` entries, and without this every IPv6 address would be
+ * masked to its `/64` and could never match a more specific entry. This
+ * options object is passed only to the network-policy `getIp` calls; Better
+ * Auth's own session-IP and rate-limit keying (configured on the auth
+ * instance) keep the `/64` default, so IPv6 rate-limit collapsing is
+ * unaffected.
  */
 export function buildIpResolutionOptions(trustedProxies: readonly string[]): {
-  advanced: { ipAddress: { trustedProxies?: string[] } }
+  advanced: { ipAddress: { trustedProxies?: string[]; ipv6Subnet: number } }
 } {
   return {
     advanced: {
-      ipAddress: trustedProxies.length > 0 ? { trustedProxies: [...trustedProxies] } : {},
+      ipAddress: {
+        ipv6Subnet: 128,
+        ...(trustedProxies.length > 0 ? { trustedProxies: [...trustedProxies] } : {}),
+      },
     },
   }
 }