# `@arcjet/ip`

[Arcjet][arcjet] utilities for finding the originating IP of a request. - [npm package (`@arcjet/ip`)](https://www.npmjs.com/package/@arcjet/ip) - [GitHub source code (`ip/` in `arcjet/arcjet-js`)](https://github.com/arcjet/arcjet-js/tree/main/ip) ## 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][rust-parser] and also contains some code from [`pbojinov/request-ip`][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: ```sh npm install @arcjet/ip ``` ## Use ```ts 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`][api-find-ip] and [`parseProxy`][api-parse-proxy]. The default export is [`findIp`][api-find-ip]. This package exports the [TypeScript][] types [`Cidr`][api-cidr], [`Options`][api-options], [`Platform`][api-platform], and [`RequestLike`][api-request-like]. ### `Cidr` This type represents a parsed CIDR range that you can use as a trusted proxy. ###### Type ```ts type Cidr = Ipv4Cidr | Ipv6Cidr; // Where each is an instance roughly equivalent to // `{bits: number, partSize: 8 | 16, parts: Array, 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`][api-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`, optional) — a list of trusted proxies to skip when resolving the client IP ### `Platform` This type represents the platform names that `findIp` recognizes. ###### Type ```ts 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 | 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`][api-request-like]) — the request to extract an IP from - `options` ([`Options`][api-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`][api-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`][api-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][apache-license] © [Arcjet Labs, Inc.][arcjet] Derivative work based on [`Parser` in `std::net`][rust-parser], [`is_global` on `Ipv4Addr`][rust-ipv4-is-global], and [`is_global` on `Ipv6Addr`][rust-ipv6-is-global] from `rust-lang/rust`, dual licensed under [MIT][rust-license-mit] and [Apache-2.0][rust-license-apache] © contributors. Our work ports to TypeScript so that we have the same functionality in both languages. Derivative work based on [`getClientIp` from `request-ip`][request-ip-client-ip] licensed under [MIT][request-ip-license] © Petar Bojinov. Our work cherry picks only what we need. [api-cidr]: #cidr [api-find-ip]: #findiprequest-options [api-options]: #options [api-parse-proxy]: #parseproxyvalue [api-platform]: #platform [api-request-like]: #requestlike [arcjet]: https://arcjet.com [request-ip-client-ip]: https://github.com/pbojinov/request-ip/blob/e1d0f4b/src/index.js#L55 [request-ip-license]: https://github.com/pbojinov/request-ip/blob/e1d0f4b/LICENSE.md [request-ip]: https://github.com/pbojinov/request-ip [rust-ipv4-is-global]: https://github.com/rust-lang/rust/blob/87e1447/library/core/src/net/ip_addr.rs#L749 [rust-ipv6-is-global]: https://github.com/rust-lang/rust/blob/87e1447/library/core/src/net/ip_addr.rs#L1453 [rust-license-apache]: https://github.com/rust-lang/rust/blob/07921b5/LICENSE-APACHE [rust-license-mit]: https://github.com/rust-lang/rust/blob/07921b5/LICENSE-MIT [rust-parser]: https://github.com/rust-lang/rust/blob/07921b5/library/core/src/net/parser.rs#L34 [typescript]: https://www.typescriptlang.org/ [apache-license]: http://www.apache.org/licenses/LICENSE-2.0