is-localhost-ip

is-localhost-ip is a small Node.js utility that determines whether a given hostname or IP address refers to the local machine, a loopback address, or a private/reserved network range (RFC 1918, link-local, unique-local IPv6, etc.). It resolves hostnames via DNS before checking, so it correctly catches cases like a public-looking domain that actually resolves to 127.0.0.1 or an internal IP.

This kind of check is a standard building block for Server-Side Request Forgery (SSRF) protection: before an application fetches a user-supplied URL, it can use is-localhost-ip to reject requests that would otherwise reach internal services, cloud metadata endpoints, or the server’s own loopback interface.

What You Get

• A single async function that accepts a hostname or IP and resolves to a boolean
• DNS resolution before the check, so hostnames that resolve to local/private IPs are caught, not just literal IP strings
• IPv4 and IPv6 support, including private ranges (10.x, 172.16-31.x, 192.168.x), loopback, link-local, and unique-local addresses
• TypeScript type definitions (index.d.ts) included
• Zero runtime dependencies beyond Node.js core modules

Common Use Cases

• SSRF protection: rejecting user-supplied URLs before an application server fetches them
• Validating webhook target URLs so they can’t be pointed at internal infrastructure
• Guarding proxy or URL-preview services against requests to loopback/private addresses
• Sanitizing outbound HTTP client requests in multi-tenant applications

Under The Hood

Architecture - The entire implementation lives in a single ~108-line index.js: a set of precompiled regular expressions (IP_RANGES) covering RFC 1918 private ranges, loopback, link-local IPv4, and IPv6 unique-local/link-local ranges are combined into one IP_TESTER_RE; a separate VALID_HOSTNAME regex validates hostname syntax before the function calls Node’s dns.promises.lookup to resolve a hostname to an address, which is then tested against the IP range regex.

Tech Stack - Plain Node.js (>=18) with zero external runtime dependencies — it uses only node:net, node:dgram, and node:dns from the standard library, keeping the supply-chain surface minimal, which matters for a security-adjacent utility.

Code Quality - The __tests__/ directory splits coverage across concerns (addresses.test.js, dns-mock.test.js, hosts-regexp.test.js, hosts.test.js, coverage-edge.test.js), including DNS-mocked tests to verify hostname resolution behavior without real network calls, and edge-case tests for the regex boundaries. Tests run on Node’s built-in test runner with coverage reporting enabled, and the project uses oxlint/oxfmt for linting/formatting plus lefthook for pre-commit hooks.

API Design - The API is intentionally minimal: one async function, one boolean return value, no configuration object or options to get wrong — appropriate for a security-check utility where a large API surface would only increase the chance of misuse.