js-cloudip

Fast cloud-provider IP detection for Node.js and the browser — the JavaScript port of go-cloudip.

Determine if an IP belongs to AWS, GCP, Azure, Cloudflare, DigitalOcean, or Oracle Cloud, with sub-millisecond lookups using a binary CIDR trie. Plus a forward-lookup mode JS apps actually want: "give me every Cloudflare CIDR."

Data comes from cloudip-db (MessagePack, ~743 KB gzipped, SHA-256 verified).

Install

npm install js-cloudip

Quick start

import {
  lookup,
  getProvider,
  isAws,
  isCloudProvider,
  getIPs,
} from 'js-cloudip';

await isAws('52.94.76.1');             // true
await getProvider('34.64.0.1');        // "gcp"
await isCloudProvider('104.16.0.1');   // true

const r = await lookup('52.94.76.1');
// { found: true, provider: 'aws', region: 'us-east-1', service: 'EC2', cidr: '52.94.0.0/16', ip_type: 'ipv4' }

const cf = await getIPs('cloudflare');
// [{ ip_address: '104.16.0.0/13', ip_type: 'ipv4', provider: 'cloudflare' }, ...]

First call fetches the database from cloudip-db, verifies its SHA-256, and caches it in ~/.cache/js-cloudip/. Subsequent calls reuse the in-memory copy.

How data loads

The default Detector tries each source in order:

1. Network — fetches cloudip.msgpack.gz + version.json from cloudip-db and verifies SHA-256.
2. Cache — uses ~/.cache/js-cloudip/cloudip.msgpack.gz if network is unavailable.
3. Embedded — falls back to the copy of data/cloudip.msgpack.gz shipped inside the package (air-gapped / browser-bundle friendly).

Use offline: true to skip step 1 entirely.

Custom Detector

import { newDetector } from 'js-cloudip';

const detector = await newDetector({
  dataDir: './cache',          // null disables fs cache
  autoUpdateMs: 24 * 60 * 60 * 1000,
  offline: false,
  fetch: globalThis.fetch,
});

detector.lookup('52.94.76.1');
detector.isAws('52.94.76.1');
detector.getIPs('cloudflare');

await detector.update();
const { hasUpdate, info } = await detector.checkUpdate();

detector.close(); // stop the auto-update timer

Options

Option	Default	Notes
dataDir	~/.cache/js-cloudip	null disables the filesystem cache
autoUpdateMs	0	Minimum effective interval is 1 hour
offline	false	Skip network; use cache → embedded only
fetch	globalThis.fetch	Custom fetch (e.g., undici with a proxy)
dataURL	cloudip-db raw URL	Override for a mirror
versionURL	cloudip-db raw URL	Override for a mirror
verifySha256	true	Disable only if you trust the transport
ttlMs	24 * 60 * 60 * 1000	Cache freshness window before forcing a re-fetch

Embedded entry point

import { lookup, getIPs } from 'js-cloudip/embedded';

await lookup('52.94.76.1'); // never touches the network

The /embedded subpath pre-configures offline: true, no fs cache. It loads the bundled data/cloudip.msgpack.gz shipped with the package. Good for tests, build pipelines, and air-gapped environments.

CLI

npx cloudip lookup 52.94.76.1
npx cloudip get cloudflare
npx cloudip provider 34.64.0.1
npx cloudip providers
npx cloudip check-update
npx cloudip update

Browser

The default entry uses fetch against raw.githubusercontent.com, which sets Access-Control-Allow-Origin: * — no proxy needed. The filesystem cache is a no-op in browsers; the in-memory cache still applies.

import { lookup } from 'js-cloudip';
const r = await lookup('1.1.1.1');

API parity with go-cloudip

Package-level (uses lazy default detector)	Detector instance method
lookup(ip)	detector.lookup(ip)
getProvider(ip)	detector.getProvider(ip)
isCloudProvider(ip)	detector.isCloudProvider(ip)
isAws / isGcp / isAzure / isCloudflare / isDigitalOcean / isOracle	same on detector
getIPs(provider | provider[])	detector.getIPs(...)
version()	detector.version()
rangeCount()	detector.rangeCount()
providers()	detector.providers()
update()	detector.update()
checkUpdate()	detector.checkUpdate()
clearCache()	detector.clearCache()
remoteVersion()	—

Data source

IP ranges come from rezmoss/cloudip-db, which compiles official cloud-provider feeds into a MessagePack database. SHA-256 of the uncompressed payload is published in version.json and verified on every fetch.

License

MIT — see LICENSE.