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.

Considerations

The IP should not be trusted as it can be spoofed in most cases, especially when loaded via the Headers object. We apply additional platform guards if a platform is supplied in the options argument.

If a private/internal address is encountered, it will be skipped. If only those are detected, an empty string is returned.

Install

npm install -S @arcjet/ip

Usage

import ip from "@arcjet/ip";

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

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

Platform protections

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

import ip from "@arcjet/ip";

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

// Also optionally takes a platform for additional protection
const platformGuardedPublicIp = ip(request, { platform: "fly-io" });
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.

import ip from "@arcjet/ip";

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

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

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:

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

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

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

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.

Discussion