@arcjet/ip

@arcjet/ip

Arcjet utilities for finding the originating IP of a request.

Installation

npm install -S @arcjet/ip

Example

import ip from "@arcjet/ip";

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

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

// Also optionally takes a platform for additional protection
const platformGuardedGloablIp = ip(request, { platform: "fly-io" });

// You can also pass a list of trusted proxies to ignore
const proxyExcludedGlobalIp = ip(request, { proxies: ["103.31.4.0"] });

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.

Implementation

The implementation of this library is based on the Parser, global ipv4 comparisons, and global ipv6 comparisons in the Rust stdlib and the header lookups in the request-ip package. Both licensed MIT with licenses included in our source code.

We've chosen the approach of porting Rust's IP Parser because capturing RegExps can be the source of ReDoS attacks, which we need to avoid. We also wanted to keep our implementation as close to Rust as possible because we will be relying on the Rust stdlib implementation in the future, with a fallback to this implementation. As such, we'll need to track changes in Rust's implementation, even though it seems to change infrequently.

License

Licensed under the Apache License, Version 2.0.

Changelog

1.0.0-beta.2 (2025-02-04)

🚀 New Features

• env: Support MODE environment variable for isDevelopment detection (#3012) (f3a45a7)
• Implement Astro integration (#2992) (a48eea8), closes #1075
• nestjs: Allow NestJS v11 as peerDependency (#3042) (4a75963), closes #2921
• redact: Pre-compile WebAssembly on module load (#3037) (c12bec5)

🪲 Bug Fixes

• analyze: Always lowercase headers and iterate in insertion order (#2865) (a9af1e4)
• arcjet: Ensure Characteristics are readonly type on protect signup options (#3013) (1f16a99)
• protocol: Double timeout when email rule configured (#2934) (23f9a9e), closes #1697

🧹 Miscellaneous Chores

• ci: Add dependabot for Astro example (#3068) (d4d8f82)
• ci: Avoid upgrading Tailwind where it breaks things (#3081) (5c25abe)
• ci: Restrict tailwind-merge where tailwind restricted (#3089) (a3437a5)
• docs: Add a link to the Redact reference page (#3038) (6095b6a)
• Refresh root & Next.js READMEs (#3066) (57a38d7)
• rollup-config: Consolidate wasmToModule plugin (#3039) (c3b8e36)