js-cloudip 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rez Moss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# js-cloudip
+
+Fast cloud-provider IP detection for Node.js and the browser — the JavaScript port of [go-cloudip](https://github.com/rezmoss/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](https://github.com/rezmoss/cloudip-db) (MessagePack, ~743 KB gzipped, SHA-256 verified).
+
+## Install
+
+```bash
+npm install js-cloudip
+```
+
+## Quick start
+
+```ts
+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
+
+```ts
+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
+
+```ts
+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
+
+```bash
+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.
+
+```ts
+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](https://github.com/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](LICENSE).

package/bin/cli.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import {
+  checkUpdate,
+  clearCache,
+  getIPs,
+  getProvider,
+  lookup,
+  providers,
+  rangeCount,
+  update,
+  version,
+} from '../dist/index.js';
+
+const HELP = `cloudip — cloud provider IP utilities (js-cloudip)
+
+Usage:
+  cloudip lookup <ip>                Reverse-lookup an IP address
+  cloudip get <provider>[,...]       Print CIDRs for one or more providers
+  cloudip provider <ip>              Print provider name for an IP
+  cloudip providers                  List supported providers
+  cloudip version                    Print local data version + range count
+  cloudip check-update               Check if a newer upstream version exists
+  cloudip update                     Force a refresh from cloudip-db
+  cloudip clear-cache                Delete the local cache
+  cloudip help                       Show this help
+
+Data source: rezmoss/cloudip-db
+`;
+
+async function main() {
+  const [cmd, ...args] = process.argv.slice(2);
+  switch (cmd) {
+    case undefined:
+    case 'help':
+    case '-h':
+    case '--help':
+      process.stdout.write(HELP);
+      return;
+    case 'lookup': {
+      const ip = args[0];
+      if (!ip) throw new Error('usage: cloudip lookup <ip>');
+      const r = await lookup(ip);
+      console.log(JSON.stringify(r, null, 2));
+      if (!r.found) process.exitCode = 1;
+      return;
+    }
+    case 'provider': {
+      const ip = args[0];
+      if (!ip) throw new Error('usage: cloudip provider <ip>');
+      const p = await getProvider(ip);
+      if (!p) {
+        process.exitCode = 1;
+        console.log('unknown');
+      } else {
+        console.log(p);
+      }
+      return;
+    }
+    case 'get': {
+      const arg = args[0];
+      if (!arg) throw new Error('usage: cloudip get <provider>[,<provider>]');
+      const want = arg.split(',').map((s) => s.trim()).filter(Boolean);
+      const entries = await getIPs(want);
+      for (const e of entries) console.log(e.ip_address);
+      return;
+    }
+    case 'providers': {
+      const list = await providers();
+      for (const p of list) console.log(p);
+      return;
+    }
+    case 'version': {
+      const v = await version();
+      const n = await rangeCount();
+      console.log(`${v} (${n} ranges)`);
+      return;
+    }
+    case 'check-update': {
+      const result = await checkUpdate();
+      console.log(JSON.stringify(result, null, 2));
+      if (!result.hasUpdate) process.exitCode = 1;
+      return;
+    }
+    case 'update':
+      await update();
+      console.log('updated');
+      return;
+    case 'clear-cache':
+      await clearCache();
+      console.log('cache cleared');
+      return;
+    default:
+      process.stderr.write(`unknown command: ${cmd}\n${HELP}`);
+      process.exit(2);
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`error: ${err?.message ?? err}\n`);
+  process.exit(1);
+});

package/dist/constants-Ba3IHVdP.d.cts

@@ -0,0 +1,90 @@
+type Provider = string;
+interface Range {
+    cidr: string;
+    provider: Provider;
+    region?: string;
+    service?: string;
+}
+interface IPEntry {
+    ip_address: string;
+    ip_type: 'ipv4' | 'ipv6';
+    provider: Provider;
+    region?: string;
+    service?: string;
+}
+interface LookupResult {
+    found: boolean;
+    provider?: Provider;
+    region?: string;
+    service?: string;
+    cidr?: string;
+    ip_type?: 'ipv4' | 'ipv6';
+}
+interface VersionInfo {
+    version: string;
+    build_time: number;
+    sha256: string;
+    ranges: number;
+    size: number;
+    size_gzip: number;
+}
+interface Database {
+    version: string;
+    build_time: number;
+    providers: Provider[];
+    ranges: Range[];
+}
+interface DetectorOptions {
+    dataDir?: string | null;
+    autoUpdateMs?: number;
+    offline?: boolean;
+    fetch?: typeof fetch;
+    dataURL?: string;
+    versionURL?: string;
+    verifySha256?: boolean;
+    ttlMs?: number;
+    signal?: AbortSignal;
+}
+interface CheckUpdateResult {
+    hasUpdate: boolean;
+    info?: VersionInfo;
+}
+
+declare class Detector {
+    private state?;
+    private readonly opts;
+    private autoUpdateTimer?;
+    constructor(options?: DetectorOptions);
+    ready(): Promise<this>;
+    close(): void;
+    private fetchEnv;
+    private loadInitial;
+    update(): Promise<void>;
+    checkUpdate(): Promise<CheckUpdateResult>;
+    clearCache(): Promise<void>;
+    private requireState;
+    lookup(ip: string): LookupResult;
+    getProvider(ip: string): Provider;
+    isCloudProvider(ip: string): boolean;
+    isAws(ip: string): boolean;
+    isGcp(ip: string): boolean;
+    isAzure(ip: string): boolean;
+    isCloudflare(ip: string): boolean;
+    isDigitalOcean(ip: string): boolean;
+    isOracle(ip: string): boolean;
+    getIPs(providers?: Provider | Provider[]): IPEntry[];
+    version(): string;
+    buildTime(): number;
+    rangeCount(): number;
+    providers(): readonly Provider[];
+}
+declare function newDetector(options?: DetectorOptions): Promise<Detector>;
+
+declare const PROVIDER_AWS = "aws";
+declare const PROVIDER_GCP = "gcp";
+declare const PROVIDER_AZURE = "azure";
+declare const PROVIDER_CLOUDFLARE = "cloudflare";
+declare const PROVIDER_DIGITALOCEAN = "digitalocean";
+declare const PROVIDER_ORACLE = "oracle";
+
+export { type CheckUpdateResult as C, type Database as D, type IPEntry as I, type LookupResult as L, type Provider as P, type Range as R, type VersionInfo as V, Detector as a, PROVIDER_AWS as b, PROVIDER_AZURE as c, PROVIDER_CLOUDFLARE as d, PROVIDER_DIGITALOCEAN as e, PROVIDER_GCP as f, PROVIDER_ORACLE as g, type DetectorOptions as h, newDetector as n };

package/dist/constants-Ba3IHVdP.d.ts

@@ -0,0 +1,90 @@
+type Provider = string;
+interface Range {
+    cidr: string;
+    provider: Provider;
+    region?: string;
+    service?: string;
+}
+interface IPEntry {
+    ip_address: string;
+    ip_type: 'ipv4' | 'ipv6';
+    provider: Provider;
+    region?: string;
+    service?: string;
+}
+interface LookupResult {
+    found: boolean;
+    provider?: Provider;
+    region?: string;
+    service?: string;
+    cidr?: string;
+    ip_type?: 'ipv4' | 'ipv6';
+}
+interface VersionInfo {
+    version: string;
+    build_time: number;
+    sha256: string;
+    ranges: number;
+    size: number;
+    size_gzip: number;
+}
+interface Database {
+    version: string;
+    build_time: number;
+    providers: Provider[];
+    ranges: Range[];
+}
+interface DetectorOptions {
+    dataDir?: string | null;
+    autoUpdateMs?: number;
+    offline?: boolean;
+    fetch?: typeof fetch;
+    dataURL?: string;
+    versionURL?: string;
+    verifySha256?: boolean;
+    ttlMs?: number;
+    signal?: AbortSignal;
+}
+interface CheckUpdateResult {
+    hasUpdate: boolean;
+    info?: VersionInfo;
+}
+
+declare class Detector {
+    private state?;
+    private readonly opts;
+    private autoUpdateTimer?;
+    constructor(options?: DetectorOptions);
+    ready(): Promise<this>;
+    close(): void;
+    private fetchEnv;
+    private loadInitial;
+    update(): Promise<void>;
+    checkUpdate(): Promise<CheckUpdateResult>;
+    clearCache(): Promise<void>;
+    private requireState;
+    lookup(ip: string): LookupResult;
+    getProvider(ip: string): Provider;
+    isCloudProvider(ip: string): boolean;
+    isAws(ip: string): boolean;
+    isGcp(ip: string): boolean;
+    isAzure(ip: string): boolean;
+    isCloudflare(ip: string): boolean;
+    isDigitalOcean(ip: string): boolean;
+    isOracle(ip: string): boolean;
+    getIPs(providers?: Provider | Provider[]): IPEntry[];
+    version(): string;
+    buildTime(): number;
+    rangeCount(): number;
+    providers(): readonly Provider[];
+}
+declare function newDetector(options?: DetectorOptions): Promise<Detector>;
+
+declare const PROVIDER_AWS = "aws";
+declare const PROVIDER_GCP = "gcp";
+declare const PROVIDER_AZURE = "azure";
+declare const PROVIDER_CLOUDFLARE = "cloudflare";
+declare const PROVIDER_DIGITALOCEAN = "digitalocean";
+declare const PROVIDER_ORACLE = "oracle";
+
+export { type CheckUpdateResult as C, type Database as D, type IPEntry as I, type LookupResult as L, type Provider as P, type Range as R, type VersionInfo as V, Detector as a, PROVIDER_AWS as b, PROVIDER_AZURE as c, PROVIDER_CLOUDFLARE as d, PROVIDER_DIGITALOCEAN as e, PROVIDER_GCP as f, PROVIDER_ORACLE as g, type DetectorOptions as h, newDetector as n };