feat: Trusted load balancers and proxies (#302)

package.json

@@ -11,21 +11,21 @@
   },
   "dependencies": {
     "@ai-sdk/openai": "1.0.6",
-    "@arcjet/body": "1.0.0-alpha.33",
-    "@arcjet/bun": "1.0.0-alpha.33",
-    "@arcjet/decorate": "1.0.0-alpha.33",
-    "@arcjet/deno": "1.0.0-alpha.33",
-    "@arcjet/env": "1.0.0-alpha.33",
-    "@arcjet/eslint-config": "1.0.0-alpha.33",
-    "@arcjet/headers": "1.0.0-alpha.33",
-    "@arcjet/nest": "1.0.0-alpha.33",
-    "@arcjet/next": "1.0.0-alpha.33",
-    "@arcjet/node": "1.0.0-alpha.33",
-    "@arcjet/protocol": "1.0.0-alpha.33",
-    "@arcjet/redact": "1.0.0-alpha.33",
-    "@arcjet/remix": "^1.0.0-alpha.33",
-    "@arcjet/sveltekit": "1.0.0-alpha.33",
-    "@arcjet/tsconfig": "1.0.0-alpha.33",
+    "@arcjet/body": "1.0.0-alpha.34",
+    "@arcjet/bun": "1.0.0-alpha.34",
+    "@arcjet/decorate": "1.0.0-alpha.34",
+    "@arcjet/deno": "1.0.0-alpha.34",
+    "@arcjet/env": "1.0.0-alpha.34",
+    "@arcjet/eslint-config": "1.0.0-alpha.34",
+    "@arcjet/headers": "1.0.0-alpha.34",
+    "@arcjet/nest": "1.0.0-alpha.34",
+    "@arcjet/next": "1.0.0-alpha.34",
+    "@arcjet/node": "1.0.0-alpha.34",
+    "@arcjet/protocol": "1.0.0-alpha.34",
+    "@arcjet/redact": "1.0.0-alpha.34",
+    "@arcjet/remix": "^1.0.0-alpha.34",
+    "@arcjet/sveltekit": "1.0.0-alpha.34",
+    "@arcjet/tsconfig": "1.0.0-alpha.34",
     "@astrojs/check": "0.9.4",
     "@astrojs/react": "3.6.3",
     "@astrojs/starlight": "0.29.2",
@@ -49,7 +49,7 @@
     "@remix-run/node": "2.15.0",
     "@sveltejs/kit": "2.9.0",
     "ai": "4.0.10",
-    "arcjet": "1.0.0-alpha.33",
+    "arcjet": "1.0.0-alpha.34",
     "astro": "4.16.16",
     "astro-embed": "0.9.0",
     "astro-robots-txt": "1.0.0",

src/content/docs/reference/bun.mdx

@@ -18,6 +18,7 @@ import MultipleRulesTS from "/src/snippets/reference/bun/MultipleRules.ts?raw";
 import MultipleRulesJS from "/src/snippets/reference/bun/MultipleRules.js?raw";
 import LoggerTS from "/src/snippets/reference/bun/Logger.ts?raw";
 import LoggerJS from "/src/snippets/reference/bun/Logger.js?raw";
+import ProxiesTS from "/src/snippets/reference/bun/Proxies.ts?raw";
 import ProtectTS from "/src/snippets/reference/bun/Protect.ts?raw";
 import ProtectJS from "/src/snippets/reference/bun/Protect.js?raw";
 import DecisionLogTS from "/src/snippets/reference/bun/DecisionLog.ts?raw";
@@ -76,6 +77,11 @@ The optional fields are:
 - `characteristics` (`string[]`) - A list of
   [characteristics](/architecture#built-in-characteristics) to be used to
   uniquely identify clients.
+- `proxies` (`string[]`) - A list of one or more trusted proxies. These
+  addresses will be excluded when Arcjet is determining the client IP address.
+  This is useful if you are behind a load balancer or proxy that sets the client
+  IP address in a header. See [Load balancers &
+  proxies](#load-balancers--proxies) below for an example.
 
 <Tabs>
   <TabItem label="TS">
@@ -153,7 +159,7 @@ execution ordering is automatically optimized for performance.
   </TabItem>
 </Tabs>
 
-## Environment variables
+### Environment variables
 
 - `ARCJET_BASE_URL` - Will override the decision API which the SDK communicates
   with. This defaults to `https://decide.arcjet.com` and should only be changed
@@ -193,6 +199,40 @@ print in development:
   </TabItem>
 </Tabs>
 
+### Load balancers & proxies
+
+If your application is behind a load balancer, Arcjet will only see the IP
+address of the load balancer and not the real client IP address.
+
+To fix this, most load balancers will set the `X-Forwarded-For` header with the
+real client IP address plus a list of proxies that the request has passed
+through.
+
+The problem with is that the `X-Forwarded-For` header can be spoofed by the
+client, so you should only trust it if you are sure that the load balancer is
+setting it correctly. See [the MDN
+docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)
+for more details.
+
+You can configure Arcjet to trust IP addresses in the `X-Forwarded-For` header
+by setting the `proxies` field in the configuration. This should be a list of
+the IP addresses of your load balancers to be removed, so that the last IP
+address in the list is the real client IP address.
+
+#### Example
+
+For example, if the load balancer is at `100.100.100.100` and the client IP
+address is `192.168.1.1`, the `X-Forwarded-For` header will be:
+
+```http
+X-Forwarded-For: 192.168.1.1, 100.100.100.100
+```
+
+You should set the `proxies` field to `["100.100.100.100"]` so Arcjet will use
+`192.168.1.1` as the client IP address.
+
+<Code code={ProxiesTS} lang="ts" />
+
 ## Protect
 
 Arcjet provides a single `protect` function that is used to execute your

src/content/docs/reference/nestjs.mdx

@@ -10,6 +10,7 @@ import SDKVersionNestjs from "/src/components/SDKVersionNestjs.astro";
 import WhatIsArcjet from "/src/components/WhatIsArcjet.astro";
 
 import LoggerTS from "/src/snippets/reference/nestjs/ClientLogger.ts?raw";
+import ProxiesTS from "/src/snippets/reference/nestjs/Proxies.ts?raw";
 import ConfigurationTS from "/src/snippets/reference/nestjs/Configuration.ts?raw";
 import IPLocationTS from "/src/snippets/reference/nestjs/IPLocation.ts?raw";
 import NodeVersions from "/src/snippets/reference/node-versions.mdx";
@@ -76,6 +77,11 @@ The optional fields are:
 - `characteristics` (`string[]`) - A list of
   [characteristics](/architecture#built-in-characteristics) to be used to
   uniquely identify clients.
+- `proxies` (`string[]`) - A list of one or more trusted proxies. These
+  addresses will be excluded when Arcjet is determining the client IP address.
+  This is useful if you are behind a load balancer or proxy that sets the client
+  IP address in a header. See [Load balancers &
+  proxies](#load-balancers--proxies) below for an example.
 
 <Code code={ConfigurationTS} lang="ts" title="src/app.module.ts" />
 
@@ -123,6 +129,40 @@ controllers.
 
 <Code code={LoggerTS} lang="ts" title="src/app.module.ts" />
 
+### Load balancers & proxies
+
+If your application is behind a load balancer, Arcjet will only see the IP
+address of the load balancer and not the real client IP address.
+
+To fix this, most load balancers will set the `X-Forwarded-For` header with the
+real client IP address plus a list of proxies that the request has passed
+through.
+
+The problem with is that the `X-Forwarded-For` header can be spoofed by the
+client, so you should only trust it if you are sure that the load balancer is
+setting it correctly. See [the MDN
+docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)
+for more details.
+
+You can configure Arcjet to trust IP addresses in the `X-Forwarded-For` header
+by setting the `proxies` field in the configuration. This should be a list of
+the IP addresses of your load balancers to be removed, so that the last IP
+address in the list is the real client IP address.
+
+#### Example
+
+For example, if the load balancer is at `100.100.100.100` and the client IP
+address is `192.168.1.1`, the `X-Forwarded-For` header will be:
+
+```http
+X-Forwarded-For: 192.168.1.1, 100.100.100.100
+```
+
+You should set the `proxies` field to `["100.100.100.100"]` so Arcjet will use
+`192.168.1.1` as the client IP address.
+
+<Code code={ProxiesTS} lang="ts" />
+
 ## Decision
 
 Arcjet can be integrated into NestJS in several places using NestJS

src/content/docs/reference/nextjs.mdx

@@ -18,6 +18,7 @@ import MultipleRulesTS from "/src/snippets/reference/nextjs/MultipleRules.ts?raw
 import MultipleRulesJS from "/src/snippets/reference/nextjs/MultipleRules.js?raw";
 import LoggerTS from "/src/snippets/reference/nextjs/Logger.ts?raw";
 import LoggerJS from "/src/snippets/reference/nextjs/Logger.js?raw";
+import ProxiesTS from "/src/snippets/reference/nextjs/Proxies.ts?raw";
 import ClientOverrideTS from "/src/snippets/reference/nextjs/ClientOverride.ts?raw";
 import ClientOverrideJS from "/src/snippets/reference/nextjs/ClientOverride.js?raw";
 import ProtectAppTS from "/src/snippets/reference/nextjs/ProtectApp.ts?raw";
@@ -107,6 +108,11 @@ The optional fields are:
 - `characteristics` (`string[]`) - A list of
   [characteristics](/architecture#built-in-characteristics) to be used to
   uniquely identify clients.
+- `proxies` (`string[]`) - A list of one or more trusted proxies. These
+  addresses will be excluded when Arcjet is determining the client IP address.
+  This is useful if you are behind a load balancer or proxy that sets the client
+  IP address in a header. See [Load balancers &
+  proxies](#load-balancers--proxies) below for an example.
 
 <Tabs>
   <TabItem label="TS">
@@ -244,6 +250,40 @@ const nextConfig = {
 module.exports = nextConfig;
 ```
 
+### Load balancers & proxies
+
+If your application is behind a load balancer, Arcjet will only see the IP
+address of the load balancer and not the real client IP address.
+
+To fix this, most load balancers will set the `X-Forwarded-For` header with the
+real client IP address plus a list of proxies that the request has passed
+through.
+
+The problem with is that the `X-Forwarded-For` header can be spoofed by the
+client, so you should only trust it if you are sure that the load balancer is
+setting it correctly. See [the MDN
+docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)
+for more details.
+
+You can configure Arcjet to trust IP addresses in the `X-Forwarded-For` header
+by setting the `proxies` field in the configuration. This should be a list of
+the IP addresses of your load balancers to be removed, so that the last IP
+address in the list is the real client IP address.
+
+#### Example
+
+For example, if the load balancer is at `100.100.100.100` and the client IP
+address is `192.168.1.1`, the `X-Forwarded-For` header will be:
+
+```http
+X-Forwarded-For: 192.168.1.1, 100.100.100.100
+```
+
+You should set the `proxies` field to `["100.100.100.100"]` so Arcjet will use
+`192.168.1.1` as the client IP address.
+
+<Code code={ProxiesTS} lang="ts" />
+
 ## Protect
 
 Arcjet provides a single `protect` function that is used to execute your

src/content/docs/reference/nodejs.mdx

@@ -12,6 +12,7 @@ import ProtectTS from "/src/snippets/reference/nodejs/Protect.ts?raw";
 import ProtectJS from "/src/snippets/reference/nodejs/Protect.js?raw";
 import LoggerTS from "/src/snippets/reference/nodejs/Logger.ts?raw";
 import LoggerJS from "/src/snippets/reference/nodejs/Logger.js?raw";
+import ProxiesTS from "/src/snippets/reference/nodejs/Proxies.ts?raw";
 import IPLocationTS from "/src/snippets/reference/nodejs/IPLocation.ts?raw";
 import IPLocationJS from "/src/snippets/reference/nodejs/IPLocation.js?raw";
 import WithRuleTS from "/src/snippets/reference/nodejs/WithRule.ts?raw";
@@ -84,6 +85,11 @@ The optional fields are:
 - `characteristics` (`string[]`) - A list of
   [characteristics](/architecture#built-in-characteristics) to be used to
   uniquely identify clients.
+- `proxies` (`string[]`) - A list of one or more trusted proxies. These
+  addresses will be excluded when Arcjet is determining the client IP address.
+  This is useful if you are behind a load balancer or proxy that sets the client
+  IP address in a header. See [Load balancers &
+  proxies](#load-balancers--proxies) below for an example.
 
 <Tabs>
   <TabItem label="TS">
@@ -174,6 +180,40 @@ print in development:
   </TabItem>
 </Tabs>
 
+### Load balancers & proxies
+
+If your application is behind a load balancer, Arcjet will only see the IP
+address of the load balancer and not the real client IP address.
+
+To fix this, most load balancers will set the `X-Forwarded-For` header with the
+real client IP address plus a list of proxies that the request has passed
+through.
+
+The problem with is that the `X-Forwarded-For` header can be spoofed by the
+client, so you should only trust it if you are sure that the load balancer is
+setting it correctly. See [the MDN
+docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)
+for more details.
+
+You can configure Arcjet to trust IP addresses in the `X-Forwarded-For` header
+by setting the `proxies` field in the configuration. This should be a list of
+the IP addresses of your load balancers to be removed, so that the last IP
+address in the list is the real client IP address.
+
+#### Example
+
+For example, if the load balancer is at `100.100.100.100` and the client IP
+address is `192.168.1.1`, the `X-Forwarded-For` header will be:
+
+```http
+X-Forwarded-For: 192.168.1.1, 100.100.100.100
+```
+
+You should set the `proxies` field to `["100.100.100.100"]` so Arcjet will use
+`192.168.1.1` as the client IP address.
+
+<Code code={ProxiesTS} lang="ts" />
+
 ## Protect
 
 Arcjet provides a single `protect` function that is used to execute your

src/content/docs/reference/remix.mdx

@@ -12,6 +12,7 @@ import ProtectTS from "/src/snippets/reference/remix/Protect.ts?raw";
 import ProtectJS from "/src/snippets/reference/remix/Protect.js?raw";
 import LoggerTS from "/src/snippets/reference/remix/Logger.ts?raw";
 import LoggerJS from "/src/snippets/reference/remix/Logger.js?raw";
+import ProxiesTS from "/src/snippets/reference/remix/Proxies.ts?raw";
 import IPLocationTS from "/src/snippets/reference/remix/IPLocation.ts?raw";
 import IPLocationJS from "/src/snippets/reference/remix/IPLocation.js?raw";
 import WithRuleTS from "/src/snippets/reference/remix/WithRule.ts?raw";
@@ -84,6 +85,11 @@ The optional fields are:
 - `characteristics` (`string[]`) - A list of
   [characteristics](/architecture#built-in-characteristics) to be used to
   uniquely identify clients.
+- `proxies` (`string[]`) - A list of one or more trusted proxies. These
+  addresses will be excluded when Arcjet is determining the client IP address.
+  This is useful if you are behind a load balancer or proxy that sets the client
+  IP address in a header. See [Load balancers &
+  proxies](#load-balancers--proxies) below for an example.
 
 <Tabs>
   <TabItem label="TS">
@@ -174,6 +180,40 @@ print in development:
   </TabItem>
 </Tabs>
 
+### Load balancers & proxies
+
+If your application is behind a load balancer, Arcjet will only see the IP
+address of the load balancer and not the real client IP address.
+
+To fix this, most load balancers will set the `X-Forwarded-For` header with the
+real client IP address plus a list of proxies that the request has passed
+through.
+
+The problem with is that the `X-Forwarded-For` header can be spoofed by the
+client, so you should only trust it if you are sure that the load balancer is
+setting it correctly. See [the MDN
+docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)
+for more details.
+
+You can configure Arcjet to trust IP addresses in the `X-Forwarded-For` header
+by setting the `proxies` field in the configuration. This should be a list of
+the IP addresses of your load balancers to be removed, so that the last IP
+address in the list is the real client IP address.
+
+#### Example
+
+For example, if the load balancer is at `100.100.100.100` and the client IP
+address is `192.168.1.1`, the `X-Forwarded-For` header will be:
+
+```http
+X-Forwarded-For: 192.168.1.1, 100.100.100.100
+```
+
+You should set the `proxies` field to `["100.100.100.100"]` so Arcjet will use
+`192.168.1.1` as the client IP address.
+
+<Code code={ProxiesTS} lang="ts" />
+
 ## Protect
 
 Arcjet provides a single `protect` function that is used to execute your