hostinfo 1.0.0 → 2.0.0

package/dist/locate.js

@@ -0,0 +1,59 @@
+import { hintFromHostname } from './hints.js';
+import { lookup } from './lookup.js';
+import { reverse } from './reverse.js';
+import { trace } from './trace.js';
+function fromHint(info, hint) {
+    return {
+        ip: info.ip,
+        city: hint.city,
+        // hostip.info's country name only applies if it agrees with the hint.
+        country: info.countryCode === hint.countryCode ? info.country : null,
+        countryCode: hint.countryCode,
+        latitude: hint.latitude,
+        longitude: hint.longitude,
+    };
+}
+/**
+ * Best-effort geolocation for an IPv4 address. Asks hostip.info first, then
+ * falls back to location codes in the target's reverse DNS name (e.g.
+ * "…lax01.example.net"), and optionally to a traceroute. Check `source` to see
+ * how much to trust the answer.
+ */
+export async function locate(ip, options = {}) {
+    const { trace: traceOption = false, ...lookupOptions } = options;
+    const { signal } = lookupOptions;
+    const [info, hostnames] = await Promise.all([
+        lookup(ip, lookupOptions),
+        // lookup() validates the address; a failed reverse lookup just means no hint.
+        reverse(ip, signal ? { signal } : {}).catch(() => []),
+    ]);
+    const hostname = hostnames[0] ?? null;
+    if (info.city !== null) {
+        return { ...info, hostname, source: 'hostip', via: null };
+    }
+    const hint = hostnames.map(hintFromHostname).find((h) => h !== null);
+    if (hint) {
+        return { ...fromHint(info, hint), hostname, source: 'hostname', via: null };
+    }
+    if (traceOption !== false) {
+        const traceOptions = {
+            ...(signal && { signal }),
+            ...(lookupOptions.endpoint !== undefined && { endpoint: lookupOptions.endpoint }),
+            ...(traceOption === true ? {} : traceOption),
+            geolocate: true,
+        };
+        const { hops } = await trace(ip, traceOptions);
+        // Walk back from the target: the nearest located router is the best proxy.
+        for (const hop of hops.toReversed()) {
+            if (hop.ip === null || hop.ip === ip)
+                continue;
+            if (hop.info?.city != null) {
+                return { ...hop.info, ip: info.ip, hostname, source: 'traceroute', via: hop };
+            }
+            if (hop.hint) {
+                return { ...fromHint(info, hop.hint), hostname, source: 'traceroute', via: hop };
+            }
+        }
+    }
+    return { ...info, hostname, source: null, via: null };
+}

package/dist/lookup.d.ts

@@ -0,0 +1,37 @@
+export interface LookupOptions {
+    /**
+     * 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 API endpoint. Default: "https://api.hostip.info/". */
+    endpoint?: string | URL;
+}
+export interface HostInfo {
+    /** The IP address the API answered for. */
+    ip: string | null;
+    /** City name, or null when unknown or a private address. */
+    city: string | null;
+    /** Country name (upper case), or null when unknown. */
+    country: string | null;
+    /** ISO-ish two-letter country code, or null when unknown. */
+    countryCode: string | null;
+    latitude: number | null;
+    longitude: number | null;
+}
+export type LookupCallback = (error: Error | null, result?: HostInfo) => void;
+export declare class HostInfoError extends Error {
+    name: 'HostInfoError';
+}
+/**
+ * Geocode an IPv4 address with the free hostip.info API. Omit `ip` to look up
+ * the caller's own public address. Returns a Promise unless a callback is
+ * given.
+ */
+export declare function lookup(ip?: string | null, options?: LookupOptions): Promise<HostInfo>;
+export declare function lookup(options: LookupOptions): Promise<HostInfo>;
+export declare function lookup(callback: LookupCallback): void;
+export declare function lookup(ip: string | null | undefined, callback: LookupCallback): void;
+export declare function lookup(ip: string | null | undefined, options: LookupOptions | undefined, callback: LookupCallback): void;

package/dist/lookup.js

@@ -0,0 +1,116 @@
+import { isIPv4 } from 'node:net';
+import { isPrivateIPv4 } from './private.js';
+const DEFAULT_ENDPOINT = 'https://api.hostip.info/';
+const DEFAULT_TIMEOUT = 10_000;
+export class HostInfoError extends Error {
+    name = 'HostInfoError';
+}
+const XML_ENTITIES = {
+    '&': '&',
+    '&lt;': '<',
+    '&gt;': '>',
+    '&quot;': '"',
+    '&apos;': "'",
+};
+function unescapeXml(text) {
+    return text.replace(/&(?:amp|lt|gt|quot|apos);|&#(\d+);|&#x([0-9a-fA-F]+);/g, (match, dec, hex) => {
+        if (dec)
+            return String.fromCodePoint(Number(dec));
+        if (hex)
+            return String.fromCodePoint(Number.parseInt(hex, 16));
+        return XML_ENTITIES[match] ?? match;
+    });
+}
+function extractField(xml, tag) {
+    const match = new RegExp(`<${tag}>([^<]*)</${tag}>`).exec(xml);
+    if (!match)
+        return null;
+    const value = unescapeXml(match[1].trim());
+    return value === '' ? null : value;
+}
+// The API reports unknowns as placeholders like "(Unknown city)" or
+// "(Private Address)", and an unknown country code as "XX"; normalize those
+// to null.
+function known(value) {
+    return value?.startsWith('(') || value === 'XX' ? null : value;
+}
+function parseHostipXml(xml) {
+    const inner = /<Hostip>([\s\S]*?)<\/Hostip>/.exec(xml)?.[1];
+    if (inner === undefined) {
+        throw new HostInfoError('Unexpected response from hostip.info: missing <Hostip> element');
+    }
+    let latitude = null;
+    let longitude = null;
+    const coordinates = extractField(inner, 'gml:coordinates');
+    if (coordinates !== null) {
+        // hostip.info returns "longitude,latitude"
+        const [lng, lat] = coordinates.split(',').map(Number);
+        if (Number.isFinite(lat) && Number.isFinite(lng)) {
+            latitude = lat;
+            longitude = lng;
+        }
+    }
+    return {
+        ip: extractField(inner, 'ip'),
+        city: known(extractField(inner, 'gml:name')),
+        country: known(extractField(inner, 'countryName')),
+        countryCode: known(extractField(inner, 'countryAbbrev')),
+        latitude,
+        longitude,
+    };
+}
+async function lookupAsync(ip, options) {
+    const { timeout = DEFAULT_TIMEOUT, signal, endpoint = DEFAULT_ENDPOINT } = options;
+    // hostip.info only knows IPv4 and answers anything else with a misleading
+    // "(Private Address)", so reject bad input up front.
+    if (ip !== undefined && !isIPv4(ip)) {
+        throw new TypeError(`Expected an IPv4 address, got ${JSON.stringify(ip)}`);
+    }
+    // hostip.info can't place these, so skip the round trip.
+    if (ip !== undefined && isPrivateIPv4(ip)) {
+        return { ip, city: null, country: null, countryCode: null, latitude: null, longitude: null };
+    }
+    const url = new URL(endpoint);
+    if (ip !== undefined)
+        url.searchParams.set('ip', ip);
+    const signals = [signal, timeout > 0 ? AbortSignal.timeout(timeout) : undefined].filter((s) => s !== undefined);
+    let response;
+    try {
+        response = await fetch(url, {
+            headers: { accept: 'text/xml' },
+            signal: signals.length > 0 ? AbortSignal.any(signals) : null,
+        });
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        throw new HostInfoError(`Request to hostip.info failed: ${message}`, { cause });
+    }
+    if (!response.ok) {
+        throw new HostInfoError(`hostip.info responded with HTTP ${response.status}`);
+    }
+    // The API serves ISO-8859-1, which response.text() would mangle.
+    const xml = new TextDecoder('iso-8859-1').decode(await response.arrayBuffer());
+    return parseHostipXml(xml);
+}
+export function lookup(ip, options, callback) {
+    if (typeof ip === 'function') {
+        callback = ip;
+        ip = undefined;
+        options = undefined;
+    }
+    else if (typeof options === 'function') {
+        callback = options;
+        options = undefined;
+    }
+    if (typeof ip === 'object' && ip !== null) {
+        options = ip;
+        ip = undefined;
+    }
+    const promise = lookupAsync(ip ?? undefined, options ?? {});
+    if (typeof callback !== 'function')
+        return promise;
+    const cb = callback;
+    // Call back outside the promise chain so an exception thrown by the
+    // callback surfaces as-is instead of becoming an unhandled rejection.
+    promise.then((result) => process.nextTick(cb, null, result), (error) => process.nextTick(cb, error));
+}

package/dist/mcp.d.ts

@@ -0,0 +1,27 @@
+type Id = string | number;
+export type McpResponse = {
+    jsonrpc: '2.0';
+    id: Id | null;
+    result: unknown;
+} | {
+    jsonrpc: '2.0';
+    id: Id | null;
+    error: {
+        code: number;
+        message: string;
+    };
+};
+export interface McpSession {
+    /** Handle one parsed JSON-RPC message. Resolves to the response, or null for notifications. */
+    handle(message: unknown): Promise<McpResponse | null>;
+    /** Abort every in-flight tool call. */
+    close(): void;
+}
+export declare function createMcpSession(): McpSession;
+export interface ServeMcpOptions {
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+}
+/** Serve MCP over newline-delimited JSON on stdin/stdout until the input ends. */
+export declare function serveMcp(options?: ServeMcpOptions): Promise<void>;
+export {};

package/dist/mcp.js

@@ -0,0 +1,243 @@
+// A zero-dependency Model Context Protocol server over stdio, so AI assistants
+// can call locate/trace/reverse/whois as tools. Messages are newline-delimited
+// JSON-RPC 2.0; see https://modelcontextprotocol.io/specification.
+import { createRequire } from 'node:module';
+import { createInterface } from 'node:readline';
+import { hintFromHostname } from './hints.js';
+import { locate } from './locate.js';
+import { lookup } from './lookup.js';
+import { toIP, toIPv4 } from './resolve.js';
+import { reverse } from './reverse.js';
+import { trace } from './trace.js';
+import { whois } from './whois.js';
+// Newest first. We only use features common to all of them.
+const PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
+const { version } = createRequire(import.meta.url)('../package.json');
+const TARGET = {
+    type: 'string',
+    description: 'IPv4 address or hostname (hostnames are resolved to their first IPv4 address).',
+};
+function str(args, key) {
+    const value = args[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new TypeError(`"${key}" must be a non-empty string`);
+    }
+    return value.trim();
+}
+function required(args, key) {
+    const value = str(args, key);
+    if (value === undefined)
+        throw new TypeError(`"${key}" is required`);
+    return value;
+}
+const TOOLS = [
+    {
+        name: 'locate',
+        title: 'Geolocate an IP address',
+        description: 'Find the city, country, and coordinates of an IPv4 address or hostname. Asks hostip.info first, ' +
+            'then falls back to location codes in the reverse DNS name, and optionally to a traceroute. ' +
+            'The `source` field says where the answer came from ("hostip" is most reliable, "traceroute" least). ' +
+            'Omit `target` to locate the machine running this server.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                target: TARGET,
+                trace: {
+                    type: 'boolean',
+                    description: 'If nothing else finds a city, traceroute to the target and use the nearest hop with a location. Slow (up to a minute).',
+                },
+            },
+        },
+        async run(args, signal) {
+            const target = str(args, 'target');
+            const ip = target === undefined ? (await lookup({ signal })).ip : await toIPv4(target);
+            if (ip === null)
+                throw new Error('hostip.info did not report a public IP for this machine');
+            return locate(ip, { signal, ...(args['trace'] === true && { trace: { signal } }) });
+        },
+    },
+    {
+        name: 'traceroute',
+        title: 'Traceroute',
+        description: 'Run a traceroute to an IPv4 address or hostname and report every hop with its reverse DNS name and ' +
+            'location. Useful for seeing where traffic goes or where it stops. Takes seconds to a minute.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                target: TARGET,
+                maxHops: { type: 'integer', minimum: 1, maximum: 64, description: 'Highest TTL to probe. Default 30.' },
+            },
+            required: ['target'],
+        },
+        async run(args, signal) {
+            const ip = await toIPv4(required(args, 'target'));
+            const maxHops = args['maxHops'];
+            if (maxHops !== undefined && (!Number.isInteger(maxHops) || maxHops < 1)) {
+                throw new TypeError('"maxHops" must be a positive integer');
+            }
+            return trace(ip, { signal, ...(maxHops !== undefined && { maxHops: maxHops }) });
+        },
+    },
+    {
+        name: 'reverse_dns',
+        title: 'Reverse DNS',
+        description: 'Look up the hostnames (PTR records) for an IPv4 or IPv6 address. Returns an empty list if there are none.',
+        inputSchema: {
+            type: 'object',
+            properties: { target: { type: 'string', description: 'IPv4/IPv6 address or hostname.' } },
+            required: ['target'],
+        },
+        async run(args, signal) {
+            return reverse(await toIP(required(args, 'target')), { signal });
+        },
+    },
+    {
+        name: 'whois',
+        title: 'IP WHOIS (RDAP)',
+        description: 'Who owns the network an IP address belongs to: organization, address range and CIDRs, allocation type, ' +
+            'abuse contact, and registration dates, from the regional internet registry via RDAP.',
+        inputSchema: {
+            type: 'object',
+            properties: { target: { type: 'string', description: 'IPv4/IPv6 address or hostname.' } },
+            required: ['target'],
+        },
+        async run(args, signal) {
+            return whois(await toIP(required(args, 'target')), { signal });
+        },
+    },
+    {
+        name: 'hostname_hint',
+        title: 'Guess location from a hostname',
+        description: 'Guess a location from the airport, CLLI, or city code that network operators embed in router and ' +
+            'server hostnames (e.g. "ae-5.r21.lsanca07.us.bb.gin.ntt.net" is Los Angeles). Offline; returns null if no code is recognized.',
+        inputSchema: {
+            type: 'object',
+            properties: { hostname: { type: 'string', description: 'A DNS hostname.' } },
+            required: ['hostname'],
+        },
+        async run(args) {
+            return hintFromHostname(required(args, 'hostname'));
+        },
+    },
+];
+function errorResponse(id, code, message) {
+    return { jsonrpc: '2.0', id, error: { code, message } };
+}
+export function createMcpSession() {
+    const inFlight = new Map();
+    async function callTool(id, params) {
+        const tool = TOOLS.find((t) => t.name === params['name']);
+        if (!tool)
+            throw Object.assign(new Error(`Unknown tool: ${String(params['name'])}`), { code: -32602 });
+        const args = (params['arguments'] ?? {});
+        const controller = new AbortController();
+        inFlight.set(id, controller);
+        try {
+            const result = await tool.run(args, controller.signal);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], isError: false };
+        }
+        catch (error) {
+            // Tool failures go back to the model as results so it can react to them.
+            const message = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: message }], isError: true };
+        }
+        finally {
+            inFlight.delete(id);
+        }
+    }
+    async function handle(raw) {
+        const message = (raw ?? {});
+        const isRequest = message.id !== undefined && message.id !== null;
+        const id = isRequest ? message.id : null;
+        if (message.jsonrpc !== '2.0' || typeof message.method !== 'string') {
+            return errorResponse(id, -32600, 'Invalid Request');
+        }
+        const params = message.params ?? {};
+        if (!isRequest) {
+            if (message.method === 'notifications/cancelled') {
+                inFlight.get(params['requestId'])?.abort(new Error('Cancelled by client'));
+            }
+            return null;
+        }
+        try {
+            switch (message.method) {
+                case 'initialize': {
+                    const requested = params['protocolVersion'];
+                    const protocolVersion = typeof requested === 'string' && PROTOCOL_VERSIONS.includes(requested)
+                        ? requested
+                        : PROTOCOL_VERSIONS[0];
+                    return {
+                        jsonrpc: '2.0',
+                        id,
+                        result: {
+                            protocolVersion,
+                            capabilities: { tools: {} },
+                            serverInfo: { name: 'hostinfo', title: 'hostinfo', version },
+                            instructions: 'IP geolocation and network lookups. Use `locate` for "where is this IP/host", `whois` for ' +
+                                '"who owns it", `reverse_dns` for its hostnames, and `traceroute` for the network path. ' +
+                                'Locations are approximate; check `source` on locate results.',
+                        },
+                    };
+                }
+                case 'ping':
+                    return { jsonrpc: '2.0', id, result: {} };
+                case 'tools/list':
+                    return {
+                        jsonrpc: '2.0',
+                        id,
+                        result: {
+                            tools: TOOLS.map(({ run: _run, ...tool }) => ({
+                                ...tool,
+                                annotations: { readOnlyHint: true, openWorldHint: tool.name !== 'hostname_hint' },
+                            })),
+                        },
+                    };
+                case 'tools/call':
+                    return { jsonrpc: '2.0', id, result: await callTool(id, params) };
+                default:
+                    return errorResponse(id, -32601, `Method not found: ${message.method}`);
+            }
+        }
+        catch (error) {
+            const code = error.code;
+            return errorResponse(id, typeof code === 'number' ? code : -32603, error instanceof Error ? error.message : String(error));
+        }
+    }
+    return {
+        handle,
+        close() {
+            for (const controller of inFlight.values())
+                controller.abort(new Error('Server closed'));
+        },
+    };
+}
+/** Serve MCP over newline-delimited JSON on stdin/stdout until the input ends. */
+export async function serveMcp(options = {}) {
+    const { input = process.stdin, output = process.stdout } = options;
+    const session = createMcpSession();
+    const pending = new Set();
+    const send = (response) => {
+        if (response)
+            output.write(`${JSON.stringify(response)}\n`);
+    };
+    for await (const line of createInterface({ input, crlfDelay: Infinity })) {
+        if (line.trim() === '')
+            continue;
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            send(errorResponse(null, -32700, 'Parse error'));
+            continue;
+        }
+        // Handle requests concurrently so a slow traceroute doesn't block pings or cancellation.
+        const task = session.handle(message).then(send);
+        pending.add(task);
+        void task.finally(() => pending.delete(task));
+    }
+    session.close();
+    await Promise.allSettled(pending);
+}

package/dist/private.d.ts

@@ -0,0 +1,5 @@
+/**
+ * True for IPv4 addresses that aren't publicly routable: loopback,
+ * link-local, RFC 1918, CGNAT, multicast, benchmarking, and reserved space.
+ */
+export declare function isPrivateIPv4(ip: string): boolean;

package/dist/private.js

@@ -0,0 +1,24 @@
+import { BlockList, isIPv4 } from 'node:net';
+// Addresses that never identify a place on the public internet, so there is
+// nothing to geolocate. The TEST-NET documentation ranges are left out: they
+// don't appear in real traffic, and examples and tests use them as stand-ins
+// for public addresses.
+const PRIVATE = new BlockList();
+PRIVATE.addSubnet('0.0.0.0', 8); // "this network"
+PRIVATE.addSubnet('10.0.0.0', 8);
+PRIVATE.addSubnet('100.64.0.0', 10); // carrier-grade NAT
+PRIVATE.addSubnet('127.0.0.0', 8);
+PRIVATE.addSubnet('169.254.0.0', 16);
+PRIVATE.addSubnet('172.16.0.0', 12);
+PRIVATE.addSubnet('192.0.0.0', 24); // IETF protocol assignments
+PRIVATE.addSubnet('192.168.0.0', 16);
+PRIVATE.addSubnet('198.18.0.0', 15); // benchmarking
+PRIVATE.addSubnet('224.0.0.0', 4); // multicast
+PRIVATE.addSubnet('240.0.0.0', 4); // reserved, including 255.255.255.255
+/**
+ * True for IPv4 addresses that aren't publicly routable: loopback,
+ * link-local, RFC 1918, CGNAT, multicast, benchmarking, and reserved space.
+ */
+export function isPrivateIPv4(ip) {
+    return isIPv4(ip) && PRIVATE.check(ip, 'ipv4');
+}

package/dist/resolve.d.ts

@@ -0,0 +1,4 @@
+/** An IPv4 address as-is, or the first IPv4 address a hostname resolves to. */
+export declare function toIPv4(target: string): Promise<string>;
+/** An IPv4 or IPv6 address as-is, or the first IPv4 address a hostname resolves to. */
+export declare function toIP(target: string): Promise<string>;

package/dist/resolve.js

@@ -0,0 +1,13 @@
+import dns from 'node:dns';
+import { isIP, isIPv4 } from 'node:net';
+/** An IPv4 address as-is, or the first IPv4 address a hostname resolves to. */
+export async function toIPv4(target) {
+    if (isIPv4(target))
+        return target;
+    const { address } = await dns.promises.lookup(target, { family: 4 });
+    return address;
+}
+/** An IPv4 or IPv6 address as-is, or the first IPv4 address a hostname resolves to. */
+export async function toIP(target) {
+    return isIP(target) ? target : toIPv4(target);
+}

package/dist/reverse.d.ts

@@ -0,0 +1,11 @@
+export interface ReverseOptions {
+    /** Milliseconds before the DNS query gives up. Set to 0 for the system default. Default: 5000. */
+    timeout?: number;
+    /** Cancel the query yourself. */
+    signal?: AbortSignal;
+}
+/**
+ * Reverse DNS: the hostnames (PTR records) registered for an IPv4 or IPv6
+ * address. Resolves to an empty array when there are none.
+ */
+export declare function reverse(ip: string, options?: ReverseOptions): Promise<string[]>;

package/dist/reverse.js

@@ -0,0 +1,34 @@
+import dns from 'node:dns';
+import { isIP } from 'node:net';
+import { HostInfoError } from './lookup.js';
+// Answers that just mean "this address has no PTR record".
+const NO_RECORD = new Set(['ENOTFOUND', 'ENODATA', 'ESERVFAIL', 'ENONAME']);
+/**
+ * Reverse DNS: the hostnames (PTR records) registered for an IPv4 or IPv6
+ * address. Resolves to an empty array when there are none.
+ */
+export async function reverse(ip, options = {}) {
+    const { timeout = 5000, signal } = options;
+    if (!isIP(ip)) {
+        throw new TypeError(`Expected an IP address, got ${JSON.stringify(ip)}`);
+    }
+    signal?.throwIfAborted();
+    const resolver = new dns.promises.Resolver({ timeout: timeout > 0 ? timeout : -1, tries: 1 });
+    const cancel = () => resolver.cancel();
+    signal?.addEventListener('abort', cancel, { once: true });
+    try {
+        return await resolver.reverse(ip);
+    }
+    catch (cause) {
+        const code = cause.code;
+        if (code !== undefined && NO_RECORD.has(code))
+            return [];
+        if (signal?.aborted)
+            throw signal.reason;
+        const message = cause instanceof Error ? cause.message : String(cause);
+        throw new HostInfoError(`Reverse DNS lookup for ${ip} failed: ${message}`, { cause });
+    }
+    finally {
+        signal?.removeEventListener('abort', cancel);
+    }
+}

package/dist/trace.d.ts

@@ -0,0 +1,56 @@
+import { type LocationHint } from './hints.ts';
+import { type HostInfo } from './lookup.ts';
+export interface TraceOptions {
+    /** Highest TTL to probe. Default: 30. */
+    maxHops?: number;
+    /** Milliseconds to wait for each probe (rounded up to whole seconds on macOS/Linux). Default: 1000. */
+    probeTimeout?: number;
+    /**
+     * Stop after this many hops in a row that don't answer — past that point
+     * the trail has usually gone cold for good. Set to 0 to always run to
+     * `maxHops`. Default: 5.
+     */
+    giveUpAfter?: number;
+    /** Milliseconds before the traceroute is cut short (the hops so far are still returned). 0 disables. Default: 60000. */
+    timeout?: number;
+    /** Abort the trace; the promise rejects with the signal's reason. */
+    signal?: AbortSignal;
+    /** Look up each hop's hostname and location. Default: true. */
+    geolocate?: boolean;
+    /** Alternate hostip.info endpoint for hop lookups. */
+    endpoint?: string | URL;
+}
+export interface TraceHop {
+    /** TTL of the probe, starting at 1. */
+    hop: number;
+    /** Address that answered, or null if the probe timed out ("*"). */
+    ip: string | null;
+    /** Round-trip time of the first answer in milliseconds. */
+    rtt: number | null;
+    /** Reverse DNS name, when `geolocate` is on and one exists. */
+    hostname: string | null;
+    /** hostip.info's answer for this hop; null for private, silent, or failed lookups. */
+    info: HostInfo | null;
+    /** Location guessed from the hostname; see `hintFromHostname`. */
+    hint: LocationHint | null;
+}
+export interface TraceResult {
+    target: string;
+    hops: TraceHop[];
+    /** Whether the target itself answered. */
+    reached: boolean;
+    /**
+     * Why the trace ended: the target answered, `maxHops` ran out, too many
+     * silent hops in a row (`giveUpAfter`), or the overall `timeout` fired.
+     */
+    stopped: 'reached' | 'max-hops' | 'gave-up' | 'timeout';
+    /** The furthest hop that answered — where the trail goes cold when the target isn't reached. */
+    lastResponding: TraceHop | null;
+}
+/**
+ * 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 declare function trace(ip: string, options?: TraceOptions): Promise<TraceResult>;