Arcjet IP detection reference

The Arcjet IP detection library provides a utility to find the public IP of a Request.

What are Arcjet utilities?

Arcjet utilities are independent libraries that do not require the use of the main Arcjet SDK - they can be used with or without other Arcjet rules.

We take the pain out of implementing security tasks through these utilities to provide a security as code approach to developer-first security.

Why

The public IP of a Request is difficult to discern, but some platforms provide specific mechanisms for accessing it - such as the X-Real-IP header added or overwritten by Vercel. The @arcjet/ip library provides a streamlined API over these mechanisms based on the current platform.

Install

npm install -S @arcjet/ip

Usage

1
import ip from "@arcjet/ip";
2

3
// Some Request-like object, such as node's `http.IncomingMessage`, `Request` or
4
// Next.js' `NextRequest`
5
const request = new Request("/your-route");
6

7
// Returns the first non-private IP address detected
8
const publicIp = ip(request);
9
console.log(publicIp);

Platform protections

Additional guards can be applied with the platform option, such as { platform: "fly-io" }, { platform: "cloudflare" }, or { platform: "vercel" }.

1
import ip from "@arcjet/ip";
2

3
// Some Request-like object, such as node's `http.IncomingMessage`, `Request` or
4
// Next.js' `NextRequest`
5
const request = new Request("/your-route");
6

7
// Also optionally takes a platform for additional protection
8
const platformGuardedPublicIp = ip(request, { platform: "fly-io" });
9
console.log(platformGuardedPublicIp);

Proxy filtering

Most proxies will add themselves in the chain of public IP addresses. Trusted proxies may be specified with the proxies option, and they will be ignored when detecting a public IP.

1
import ip from "@arcjet/ip";
2

3
// Some Request-like object, such as node's `http.IncomingMessage`, `Request` or
4
// Next.js' `NextRequest`
5
const request = new Request("/your-route");
6

7
// You can also pass a list of trusted proxies to ignore
8
const proxyExcludedPublicIp = ip(request, {
9
  proxies: [
10
    "100.100.100.100", // A single IP
11
    "100.100.100.0/24", // A CIDR for the range
12
  ],
13
});
14
console.log(proxyExcludedPublicIp);

Proxy services

The proxies option also accepts proxy services alongside plain IP addresses. A proxy service knows the IP ranges that belong to a particular provider and the header that provider uses to pass through the real client IP. When a request arrives from one of the service’s IP ranges, the real client IP is read from that header instead of the connecting address.

This is safer than trusting a header on its own: the header is only used when the connecting address falls within the service’s verified IP ranges, so a direct client cannot spoof it.

Cloudflare

The cloudflare() helper is the proxy service for Cloudflare. When a request comes from a Cloudflare IP range, ip() reads the real client IP from the CF-Connecting-IP (or CF-Connecting-IPv6) header that Cloudflare sets.

1
import ip, { cloudflare } from "@arcjet/ip";
2

3
// Some Request-like object, such as node's `http.IncomingMessage`, `Request` or
4
// Next.js' `NextRequest`
5
const request = new Request("/your-route");
6

7
// Pass the `cloudflare()` proxy service to read the real client IP from
8
// Cloudflare's `CF-Connecting-IP` header, but only when the request comes from
9
// a known Cloudflare IP range
10
const publicIp = ip(request, {
11
  proxies: [cloudflare()],
12
});
13
console.log(publicIp);

The Cloudflare IP ranges are bundled with @arcjet/ip and kept up to date as the package is released. If Cloudflare publishes a new range before the SDK has been updated, you can override the bundled ranges with the ranges option. This replaces the bundled list rather than adding to it, so supply the full set of ranges from cloudflare.com/ips plus any new range:

1
import ip, { cloudflare } from "@arcjet/ip";
2

3
const request = new Request("/your-route");
4

5
// Override the bundled Cloudflare ranges with your own list. This *replaces*
6
// the bundled ranges, so include the full list from https://www.cloudflare.com/ips/
7
// plus any new range Cloudflare has added that the SDK doesn't know about yet.
8
const publicIp = ip(request, {
9
  proxies: [
10
    cloudflare({
11
      ranges: [
12
        // The current Cloudflare ranges...
13
        "173.245.48.0/20",
14
        "103.21.244.0/22",
15
        // ...plus a new range not yet bundled in the SDK
16
        "203.0.113.0/24",
17
      ],
18
    }),
19
  ],
20
});
21
console.log(publicIp);

API

`ip(request: RequestLike, options?: Options)`

Look up an IP address in a Request-like object, such as Request, Node’s http.IncomingMessage, or Next.js’ NextRequest.

Types:

1
type RequestLike = {
2
  info?: PartialInfo | null | undefined;
3
  ip?: unknown;
4
  requestContext?: PartialRequestContext | null | undefined;
5
  socket?: PartialSocket | null | undefined;
6
  headers: Headers | Record<string, string[] | string | undefined>;
7
};

1
type Options = {
2
  platform?: Platform | null | undefined;
3
  proxies?: readonly (string | Cidr | ProxyService)[] | null | undefined;
4
};

1
type Platform = "cloudflare" | "firebase" | "fly-io" | "render" | "vercel";

`cloudflare(options?: CloudflareOptions)`

Returns a ProxyService for Cloudflare that can be passed in the proxies option. Pass ranges to override the bundled Cloudflare IP ranges (this replaces the bundled list).

Types:

1
type ProxyService = {
2
  kind: "service";
3
  name: string;
4
  ranges: ReadonlyArray<string | Cidr>;
5
  clientIp: ReadonlyArray<ClientIpHeader>;
6
};

1
type CloudflareOptions = {
2
  ranges?: readonly string[] | null | undefined;
3
};

What next?

Arcjet can protect your entire app or individual routes with just a few lines of code. Using the main Arcjet SDK you can setup bot protection, rate limiting for your API, minimize fraudulent registrations with the signup form protection and more.

Example apps Check out the examples.

Learn how Arcjet works Arcjet's architecture.

SDK reference Node.js SDK reference guide.