hostinfo 0.0.2 → 2.0.0

package/dist/trace.js

@@ -0,0 +1,146 @@
+import childProcess from 'node:child_process';
+import { isIPv4 } from 'node:net';
+import { createInterface } from 'node:readline';
+import { hintFromHostname } from './hints.js';
+import { HostInfoError, lookup } from './lookup.js';
+import { isPrivateIPv4 } from './private.js';
+import { reverse } from './reverse.js';
+const IPV4 = /\b(\d{1,3}(?:\.\d{1,3}){3})\b/;
+const RTT = /<?(\d+(?:\.\d+)?)\s*ms\b/;
+// Parses one hop line from BSD/Linux `traceroute -n` or Windows `tracert -d`:
+//    3  108.254.2.1  11.268 ms
+//    7  *
+//    2    <1 ms    <1 ms    <1 ms  192.168.1.254
+//    4     *        *        *     Request timed out.
+function parseHopLine(line) {
+    const match = /^\s*(\d+)\s+(.*)$/.exec(line);
+    if (!match)
+        return null;
+    const rest = match[2];
+    const ip = IPV4.exec(rest)?.[1] ?? null;
+    const rtt = RTT.exec(rest)?.[1];
+    return {
+        hop: Number(match[1]),
+        ip: ip !== null && isIPv4(ip) ? ip : null,
+        rtt: ip !== null && rtt !== undefined ? Number(rtt) : null,
+    };
+}
+function tracerouteCommand(ip, maxHops, probeTimeout) {
+    if (process.platform === 'win32') {
+        return ['tracert', ['-d', '-h', String(maxHops), '-w', String(probeTimeout), ip]];
+    }
+    const seconds = String(Math.max(1, Math.ceil(probeTimeout / 1000)));
+    return ['traceroute', ['-n', '-q', '1', '-w', seconds, '-m', String(maxHops), ip]];
+}
+function runTraceroute(ip, options) {
+    const { maxHops, probeTimeout, giveUpAfter, timeout, signal } = options;
+    signal?.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const [command, args] = tracerouteCommand(ip, maxHops, probeTimeout);
+        const child = childProcess.spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        const hops = [];
+        let stopped;
+        let silentRun = 0;
+        let stderr = '';
+        let settled = false;
+        const stop = (reason) => {
+            stopped ??= reason;
+            child.kill();
+        };
+        const timer = timeout > 0 ? setTimeout(() => stop('timeout'), timeout) : undefined;
+        const onAbort = () => {
+            child.kill();
+            finish(() => reject(signal.reason));
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+        function finish(settle) {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            settle();
+        }
+        createInterface({ input: child.stdout }).on('line', (line) => {
+            const hop = parseHopLine(line);
+            // Ignore headers, repeated hop numbers (extra probes), and anything
+            // printed after we decided to stop.
+            if (hop === null || stopped !== undefined || hops.some((h) => h.hop === hop.hop))
+                return;
+            hops.push(hop);
+            if (hop.ip === ip)
+                return stop('reached');
+            silentRun = hop.ip === null ? silentRun + 1 : 0;
+            if (giveUpAfter > 0 && silentRun >= giveUpAfter)
+                stop('gave-up');
+        });
+        child.stderr.setEncoding('utf8').on('data', (chunk) => {
+            stderr += chunk;
+        });
+        child.on('error', (error) => {
+            const message = error.code === 'ENOENT'
+                ? `\`${command}\` was not found; install it to use trace()`
+                : `Could not run ${command}: ${error.message}`;
+            finish(() => reject(new HostInfoError(message, { cause: error })));
+        });
+        child.on('close', (code) => {
+            if (stopped === undefined && code !== 0 && hops.length === 0) {
+                const detail = stderr.trim() || `exit code ${code}`;
+                return finish(() => reject(new HostInfoError(`${command} failed: ${detail}`)));
+            }
+            finish(() => resolve({ hops, stopped: stopped ?? 'max-hops' }));
+        });
+    });
+}
+async function mapLimit(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const i = next++;
+            results[i] = await fn(items[i]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return results;
+}
+async function geolocateHop(hop, options) {
+    const located = { ...hop, hostname: null, info: null, hint: null };
+    if (hop.ip === null || isPrivateIPv4(hop.ip))
+        return located;
+    const { signal, endpoint } = options;
+    // One failed lookup shouldn't sink the whole trace, so failures become null.
+    const [hostnames, info] = await Promise.all([
+        reverse(hop.ip, signal ? { signal } : {}).catch(() => []),
+        lookup(hop.ip, { ...(signal && { signal }), ...(endpoint !== undefined && { endpoint }) }).catch(() => null),
+    ]);
+    signal?.throwIfAborted();
+    located.hostname = hostnames[0] ?? null;
+    located.info = info;
+    located.hint = hostnames.map(hintFromHostname).find((hint) => hint !== null) ?? null;
+    return located;
+}
+/**
+ * Run the system traceroute (`traceroute` on macOS/Linux, `tracert` on
+ * Windows) to an IPv4 address and report each hop, optionally with its
+ * hostname and location. When the target never answers, `lastResponding` is
+ * the furthest router that did — often the edge of the target's network.
+ */
+export async function trace(ip, options = {}) {
+    const { maxHops = 30, probeTimeout = 1000, giveUpAfter = 5, timeout = 60_000, signal, geolocate = true, endpoint, } = options;
+    if (!isIPv4(ip)) {
+        throw new TypeError(`Expected an IPv4 address, got ${JSON.stringify(ip)}`);
+    }
+    const raw = await runTraceroute(ip, { maxHops, probeTimeout, giveUpAfter, timeout, signal });
+    const hops = geolocate
+        ? await mapLimit(raw.hops, 4, (hop) => geolocateHop(hop, { signal, endpoint }))
+        : raw.hops.map((hop) => ({ ...hop, hostname: null, info: null, hint: null }));
+    const reached = raw.stopped === 'reached' || hops.some((hop) => hop.ip === ip);
+    return {
+        target: ip,
+        hops,
+        reached,
+        stopped: reached ? 'reached' : raw.stopped,
+        lastResponding: hops.findLast((hop) => hop.ip !== null) ?? null,
+    };
+}

package/dist/whois.d.ts

@@ -0,0 +1,56 @@
+export interface WhoisOptions {
+    /** Milliseconds before the request is aborted. Set to 0 to disable. Default: 10000. */
+    timeout?: number;
+    /** Abort the request yourself. Combined with `timeout`; whichever fires first wins. */
+    signal?: AbortSignal;
+    /** Alternate RDAP base URL; the IP is appended. Default: "https://rdap.arin.net/registry/ip/". */
+    endpoint?: string | URL;
+}
+export interface WhoisContact {
+    /** Registry handle, e.g. "ABUSE5250-ARIN". */
+    handle: string | null;
+    /** RDAP roles such as "registrant", "abuse", "technical", "administrative". */
+    roles: string[];
+    /** vCard kind: "org", "group", "individual", ... */
+    kind: string | null;
+    name: string | null;
+    org: string | null;
+    email: string | null;
+    phone: string | null;
+    /** Postal address as a single multi-line string. */
+    address: string | null;
+}
+export interface WhoisInfo {
+    /** The address that was looked up. */
+    ip: string;
+    /** Network handle, e.g. "NET-8-8-8-0-2". */
+    handle: string | null;
+    /** Network name, e.g. "GOGL". */
+    name: string | null;
+    /** Allocation type, e.g. "DIRECT ALLOCATION". */
+    type: string | null;
+    parentHandle: string | null;
+    /** Two-letter country code, when the registry records one. */
+    country: string | null;
+    startAddress: string | null;
+    endAddress: string | null;
+    /** The network in CIDR notation, e.g. ["8.8.8.0/24"]. */
+    cidrs: string[];
+    status: string[];
+    /** Organization the network is registered to. */
+    organization: string | null;
+    /** Where to report abuse from this network. */
+    abuseEmail: string | null;
+    /** ISO 8601 timestamps from the registry. */
+    registered: string | null;
+    updated: string | null;
+    /** The registry's whois server, e.g. "whois.arin.net" or "whois.ripe.net". */
+    registry: string | null;
+    contacts: WhoisContact[];
+}
+/**
+ * Registration data for the network an IPv4 or IPv6 address belongs to: who
+ * owns it, its range, and its abuse contact. Queries ARIN's RDAP service,
+ * which hands off to the right regional registry for non-ARIN space.
+ */
+export declare function whois(ip: string, options?: WhoisOptions): Promise<WhoisInfo>;

package/dist/whois.js

@@ -0,0 +1,136 @@
+import { isIP } from 'node:net';
+import { HostInfoError } from './lookup.js';
+// ARIN's RDAP service answers for its own space and redirects everything else
+// to the registry that holds it (RIPE, APNIC, LACNIC, AFRINIC), which fetch
+// follows for us.
+const DEFAULT_ENDPOINT = 'https://rdap.arin.net/registry/ip/';
+const DEFAULT_TIMEOUT = 10_000;
+function text(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    return trimmed === '' ? null : trimmed;
+}
+function vcardField(entity, name) {
+    const property = entity.vcardArray?.[1]?.find((p) => p[0] === name);
+    if (!property)
+        return null;
+    // Addresses carry the formatted text in a "label" parameter; the structured
+    // value is usually blank.
+    if (name === 'adr')
+        return text(property[1]['label']);
+    return text(property[3]);
+}
+function toContact(entity) {
+    return {
+        handle: text(entity.handle),
+        roles: [...(entity.roles ?? [])],
+        kind: vcardField(entity, 'kind'),
+        name: vcardField(entity, 'fn'),
+        org: vcardField(entity, 'org'),
+        email: vcardField(entity, 'email'),
+        phone: vcardField(entity, 'tel'),
+        address: vcardField(entity, 'adr'),
+    };
+}
+// Contacts nest (ARIN hangs abuse/tech under the registrant) and repeat once
+// per role (RIPE), so flatten them and merge roles by handle.
+function collectContacts(entities = []) {
+    const contacts = [];
+    const byHandle = new Map();
+    const visit = (list) => {
+        for (const entity of list) {
+            const contact = toContact(entity);
+            const existing = contact.handle === null ? undefined : byHandle.get(contact.handle);
+            if (existing) {
+                for (const role of contact.roles) {
+                    if (!existing.roles.includes(role))
+                        existing.roles.push(role);
+                }
+                for (const key of ['kind', 'name', 'org', 'email', 'phone', 'address']) {
+                    existing[key] ??= contact[key];
+                }
+            }
+            else {
+                contacts.push(contact);
+                if (contact.handle !== null)
+                    byHandle.set(contact.handle, contact);
+            }
+            visit(entity.entities ?? []);
+        }
+    };
+    visit(entities);
+    return contacts;
+}
+function eventDate(network, action) {
+    return text(network.events?.find((e) => e.eventAction === action)?.eventDate);
+}
+function parseRdap(ip, network) {
+    if (network.objectClassName !== 'ip network') {
+        throw new HostInfoError('Unexpected RDAP response: not an IP network');
+    }
+    const contacts = collectContacts(network.entities);
+    const withRole = (role) => contacts.filter((c) => c.roles.includes(role));
+    // RIPE also lists maintainer objects as registrants; prefer the organization.
+    const registrants = withRole('registrant');
+    const registrant = registrants.find((c) => c.kind === 'org') ?? registrants[0];
+    return {
+        ip,
+        handle: text(network.handle),
+        name: text(network.name),
+        type: text(network.type),
+        parentHandle: text(network.parentHandle),
+        country: text(network.country),
+        startAddress: text(network.startAddress),
+        endAddress: text(network.endAddress),
+        cidrs: (network.cidr0_cidrs ?? []).flatMap((c) => {
+            const prefix = c.v4prefix ?? c.v6prefix;
+            return prefix && c.length !== undefined ? [`${prefix}/${c.length}`] : [];
+        }),
+        status: [...(network.status ?? [])],
+        organization: registrant?.name ?? registrant?.org ?? null,
+        abuseEmail: withRole('abuse').find((c) => c.email !== null)?.email ?? null,
+        registered: eventDate(network, 'registration'),
+        updated: eventDate(network, 'last changed'),
+        registry: text(network.port43),
+        contacts,
+    };
+}
+/**
+ * Registration data for the network an IPv4 or IPv6 address belongs to: who
+ * owns it, its range, and its abuse contact. Queries ARIN's RDAP service,
+ * which hands off to the right regional registry for non-ARIN space.
+ */
+export async function whois(ip, options = {}) {
+    const { timeout = DEFAULT_TIMEOUT, signal, endpoint = DEFAULT_ENDPOINT } = options;
+    if (!isIP(ip)) {
+        throw new TypeError(`Expected an IP address, got ${JSON.stringify(ip)}`);
+    }
+    const base = new URL(endpoint);
+    if (!base.pathname.endsWith('/'))
+        base.pathname += '/';
+    const url = new URL(encodeURIComponent(ip), base);
+    const signals = [signal, timeout > 0 ? AbortSignal.timeout(timeout) : undefined].filter((s) => s !== undefined);
+    let response;
+    try {
+        response = await fetch(url, {
+            headers: { accept: 'application/rdap+json' },
+            signal: signals.length > 0 ? AbortSignal.any(signals) : null,
+        });
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        throw new HostInfoError(`RDAP request for ${ip} failed: ${message}`, { cause });
+    }
+    if (!response.ok) {
+        throw new HostInfoError(`RDAP lookup for ${ip} responded with HTTP ${response.status}`);
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (cause) {
+        throw new HostInfoError('Unexpected RDAP response: not JSON', { cause });
+    }
+    return parseRdap(ip, (body ?? {}));
+}

package/llms.txt

@@ -0,0 +1,35 @@
+# hostinfo
+
+> Zero-dependency Node.js (>=22.12) library, CLI, and MCP server for IP geolocation (via the free hostip.info API, with reverse-DNS and traceroute fallbacks), reverse DNS, traceroute, and IP WHOIS (RDAP). ESM with bundled TypeScript types; `require('hostinfo')` also works.
+
+Every function returns a Promise and accepts an `options` object with `signal` (AbortSignal) and usually `timeout` (ms, 0 disables). Network/HTTP/parse failures reject with `HostInfoError` (underlying error on `.cause`). Non-IP input rejects with `TypeError`. Unknown fields are `null`, never placeholder strings. Results are approximate: hostip.info is community-maintained.
+
+## API
+
+- `lookup(ip?, { timeout=10000, signal, endpoint }) → HostInfo` — hostip.info only. IPv4 only. Omit `ip` for the caller's public IP. Private addresses return all-null fields without a request. `HostInfo = { ip, city, country, countryCode, latitude, longitude }`.
+- `locate(ip, { ...lookupOptions, trace?: boolean | TraceOptions }) → Location` — preferred for "where is this IP". Tries hostip.info, then location codes in the reverse-DNS hostname, then (only if `trace` is set) the nearest traceroute hop with a location. `Location = HostInfo & { hostname, source: 'hostip'|'hostname'|'traceroute'|null, via: TraceHop|null }`. Trust `source` in that order.
+- `trace(ip, { maxHops=30, probeTimeout=1000, giveUpAfter=5, timeout=60000, signal, geolocate=true, endpoint }) → TraceResult` — shells out to `traceroute`/`tracert` (must be installed). `TraceResult = { target, hops: TraceHop[], reached, stopped: 'reached'|'max-hops'|'gave-up'|'timeout', lastResponding }`; `TraceHop = { hop, ip|null, rtt|null, hostname, info: HostInfo|null, hint: LocationHint|null }`.
+- `reverse(ip, { timeout=5000, signal }) → string[]` — PTR records, IPv4 or IPv6; `[]` when none.
+- `whois(ip, { timeout=10000, signal, endpoint }) → WhoisInfo` — ARIN RDAP (redirects to other registries). Fields include `organization, name, handle, startAddress, endAddress, cidrs, type, country, abuseEmail, registered, updated, registry, contacts[]`.
+- `hintFromHostname(hostname) → LocationHint | null` — synchronous, offline. `LocationHint = { code, city, countryCode, latitude, longitude }`.
+- `isPrivateIPv4(ip) → boolean` — synchronous. TEST-NET ranges count as public.
+- Legacy: `lookup(ip, (err, info) => …)` callback form still works.
+
+```js
+import { locate, whois } from 'hostinfo';
+const where = await locate('8.8.8.8');   // { city: 'Mountain View, CA', source: 'hostip', … }
+const owner = await whois('8.8.8.8');    // { organization: 'Google LLC', cidrs: ['8.8.8.0/24'], … }
+```
+
+## CLI
+
+`npx hostinfo [ip|host] [--trace]`, `npx hostinfo trace|reverse|whois <ip|host>`, `--json` for machine-readable output. Hostnames resolve to their first IPv4 address.
+
+## MCP server
+
+`npx -y hostinfo mcp` runs a stdio MCP server with read-only tools: `locate` (`target?`, `trace?`), `traceroute` (`target`, `maxHops?`), `reverse_dns` (`target`), `whois` (`target`), `hostname_hint` (`hostname`). Tool results are the JSON-serialized return values of the functions above.
+
+## Docs
+
+- [README](https://github.com/neopunisher/node-hostip#readme): full API reference and examples
+- [Types](https://unpkg.com/hostinfo/dist/index.d.ts): bundled TypeScript declarations

package/package.json

@@ -1,32 +1,61 @@
 {
-    "name": "hostinfo",
-    "description": "Uses the hostinfo database to geocode ip addresses",
-    "version": "0.0.2",
-        "tags" : ["geoip", "hostinfo", "util", "utility"],
-    "author" : "Carter Cole <node@cartercole.com>",
-    "maintainers":[
-        {
-            "name":"Carter Cole",
-            "email":"node@cartercole.com"
-        }
-    ],
-    "homepage": "http://blog.cartercole.com",
-    "repository" : {
-        "type" : "git",
-        "url" : "git://github.com/neopunisher/node-hostip.git"
+  "name": "hostinfo",
+  "version": "2.0.0",
+  "description": "Geocode IP addresses to city, country, and coordinates with the free hostip.info API, with reverse-DNS and traceroute fallbacks, plus WHOIS and an MCP server for AI assistants. Zero dependencies.",
+  "keywords": [
+    "geoip",
+    "hostinfo",
+    "hostip",
+    "geocode",
+    "geolocation",
+    "ip",
+    "reverse-dns",
+    "traceroute",
+    "whois",
+    "rdap",
+    "mcp",
+    "mcp-server",
+    "model-context-protocol"
+  ],
+  "homepage": "https://github.com/neopunisher/node-hostip#readme",
+  "bugs": {
+    "url": "https://github.com/neopunisher/node-hostip/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neopunisher/node-hostip.git"
+  },
+  "license": "MIT",
+  "author": "Carter Cole <node@cartercole.com>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     },
-    "main" : "main.js",
-    "licenses" : [
-        {
-            "type": "MIT",
-            "url": "http://www.opensource.org/licenses/mit-license.php"
-        }
-    ],"bugs" :
-  { "web" : "https://github.com/neopunisher/node-hostip/issues" },
-    "dependencies": {
-        "xml2js": ">= 0.1.9",
-       "request": ">= 2.1.0"
-    },
-    "engine": [ "node >=0.4.1" ]
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "hostinfo": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "llms.txt"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.12"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "npm run build && tsc",
+    "test": "npm run build && node --test \"test/**/*.test.ts\"",
+    "test:live": "LIVE_TEST=1 npm test",
+    "prepack": "npm run build"
+  },
+  "types": "./dist/index.d.ts",
+  "devDependencies": {
+    "@types/node": "^22.20.4",
+    "typescript": "^7.0.2"
+  }
 }
-

package/README

@@ -1 +0,0 @@
-This uses the free api from http://www.hostip.info/ to provide ip to city geocoding

package/main.js

@@ -1,12 +0,0 @@
-var xml2js = require('xml2js'),
-    request = require('request');
-
-exports.lookup = function (ip,cb){
-request({uri: "http://api.hostip.info/?ip="+ip}, function (error, response, body) {
-var parser = new xml2js.Parser();
-parser.addListener('end', function(obj){
-cb(null,obj);
-});
-parser.parseString(body);
-});
-}