is-private-host


Determines if a URL or hostname resolves to a "private" IP, for instance 127.0.0.1, 192.168.x.x, ::1 or similar. Can also be used to check a specific IP.

> [!CAUTION]
> It is not safe to cache the results for long - a host may change their DNS records to point to a private IP immediately after a lookup, theoretically.

Supported engines

- Node.js >= 18
- Deno >= 1.30
- Bun >= 1.1.23

…and any other Javascript environment that implements lookup() from node:dns/promises.

Installation

``bash
npm install --save is-private-host
`

Usage

$3

`ts
import {isPrivateHost} from 'is-private-host'

if (await isPrivateHost('espen.codes')) {
console.log('It is private! Do not run a request against it!')
} else {
console.log('It is not private! You should be good to go.')
}
`

$3

`ts
import {isPrivateHost} from 'is-private-host'

const {isPrivate, addresses} = await isPrivateHost('espen.codes', {withResolveInfo: true})

const ips = addresses.map(({address, family}) => {
// eg 127.0.0.1 (IPv4) or ::1 (IPv6)
return ${address} (IPv${family})
})

if (isPrivate) {
console.log(It is private! It resolves to ${ips.join(' / ')})
} else {
console.log('It is not private! You should be good to go.')
}
`

$3

`ts
import {isPrivateUrl} from 'is-private-host'

if (await isPrivateUrl('https://espen.codes/projects')) {
console.log('It is private! Do not run a request against it!')
} else {
console.log('It is not private! You should be good to go.')
}
`

$3

`ts
import {isPrivateUrl} from 'is-private-host'

const {isPrivate, parsedUrl, addresses} = await isPrivateUrl('https://espen.codes/projects', {
withResolveInfo: true,
})

const ip = addresses[0].address

if (isPrivate) {
console.log(It is private! It resolves to ${ip}!)
} else {
console.log(It is not private! Requesting with validated IP (${ip}))

// Already an URL instance, but cloning to prevent mutation of parsed
const newUrl = new URL(parsedUrl)

// Reassign hostname keeping rest of URL intact (protocol, port, path…)
newUrl.hostname = ip

// Send to the resolved IP, but keep the original host header
await fetch(newUrl, {headers: {host: parsedUrl.host}})
}
`

$3

`ts
import {isPrivateIP} from 'is-private-host'

isPrivateIP('127.0.0.1') // true
isPrivateIP('192.168.1.1') // true
isPrivateIP('8.8.8.8') // false
isPrivateIP('foobar') // throws Error, not an IP
``

License

MIT © Espen Hovlandsdal