@arcjet/ip

@arcjet/ip

Arcjet utilities for finding the originating IP of a request.

• npm package (@arcjet/ip)
• GitHub source code (ip/ in arcjet/arcjet-js)

What is this?

This is an internal utility to help us deal with IP addresses. It includes code from the Rust standard library code to parse IPv4 and IPv6 and also contains some code from pbojinov/request-ip. We turned the Rust IP parser into TypeScript so that we have the exact same functionality in both languages. Similar functionality in alternative JavaScript libraries often uses regular expressions but those can cause ReDoS attacks. We sidestep that problem because the Rust IP parser algorithm does not use regular expressions. We chose to copy code from request-ip so that we only keep the functionality that we use and keep our dependency tree as light as possible. Our code is different: if we know we are running on Cloudflare for example then we do not trust headers typically set by fly.io.

When should I use this?

You should not use this but use one of the alternatives instead. This package matches our current needs which are likely different from yours.

Install

This package is ESM only. Install with npm in Node.js:

npm install @arcjet/ip

Use

import { findIp } from "@arcjet/ip";

const ip = findIp({ headers: { "x-real-ip": "1.1.1.1" } });
console.log(ip); // => "1.1.1.1"

API

This package exports the identifiers findIp and parseProxy. The default export is findIp.

This package exports the TypeScript types Cidr, Options, Platform, and RequestLike.

Cidr

This type represents a parsed CIDR range that you can use as a trusted proxy.

Type

type Cidr = Ipv4Cidr | Ipv6Cidr;
// Where each is an instance roughly equivalent to
// `{bits: number, partSize: 8 | 16, parts: Array<number>, type: "v4" | "v6"}`,
// with a `contains` function that can be passed an array of octets.

Options

You can pass these options to configure how findIp looks up the client IP.

Fields

• platform (Platform, optional) — the platform your code is running on; we use this to only trust headers that are known to be set by that platform
• proxies (Array<Cidr | string>, optional) — a list of trusted proxies to skip when resolving the client IP

Platform

This type represents the platform names that findIp recognizes.

Type

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

RequestLike

This type represents a request-like object that findIp can extract an IP address from. It supports several shapes because different platforms expose request information differently.

Fields

• headers (Headers | Record<string, Array<string> | string | undefined>) — the request headers
• info ({remoteAddress?: string}, optional) — some platforms pass connection info here
• ip (unknown, optional) — some platforms provide the IP directly on the request object
• requestContext ({identity?: {sourceIp?: string}}, optional) — some platforms pass a request context with identity info
• socket ({remoteAddress?: string}, optional) — some platforms pass a socket with the remote address

findIp(request[, options])

Finds the client IP address from a request-like object. If you pass a platform in the options, we only trust headers that are known to be set by that platform.

Parameters

• request (RequestLike) — the request to extract an IP from
• options (Options, optional) — configuration for platform and trusted proxies

Returns

The found IP address (string), or an empty string if no IP could be determined.

parseProxy(value)

Parses a CIDR address string into a Cidr object, or returns the value as-is if it is a plain IP address. You can use this to build a list of trusted proxies.

Parameters

• value (string) — an IP address or CIDR range to parse

Returns

A parsed Cidr if the value is a range, or the given value string if it is a plain IP.

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.

License

Apache License, Version 2.0 © Arcjet Labs, Inc.

Derivative work based on Parser in std::net, is_global on Ipv4Addr, and is_global on Ipv6Addr from rust-lang/rust, dual licensed under MIT and Apache-2.0 © contributors. Our work ports to TypeScript so that we have the same functionality in both languages.

Derivative work based on getClientIp from request-ip licensed under MIT © Petar Bojinov. Our work cherry picks only what we need.