@thotischner/observability-mcp 3.6.0 → 3.7.0

package/dist/conformance/mcp-2025-11-25.test.js

@@ -439,3 +439,13 @@ test("E2E: initialize advertises non-empty instructions pointing at the usage gu
     assert.match(r.instructions, /omcp:\/\/guide\/agent-usage/, "must point at the usage-guide resource");
     assert.match(r.instructions, /aggregate/i, "must carry the filter+aggregate golden rule");
 });
+test("E2E: enrich_ips advertises IPv6 in its description + ips param (issue #476)", opts, async () => {
+    const session = await newSession();
+    const { response } = await jsonRpc("tools/list", {}, { id: 40, session });
+    const r = response.result;
+    const tool = r.tools?.find((t) => t.name === "enrich_ips");
+    assert.ok(tool, "enrich_ips must be advertised");
+    assert.match(tool.description ?? "", /IPv6/, "description must mention IPv6 (not IPv4-only)");
+    const ipsDesc = tool.inputSchema?.properties?.ips?.description ?? "";
+    assert.match(ipsDesc, /IPv6/, "the ips param must mention IPv6");
+});

package/dist/enrich/rdap.d.ts

@@ -0,0 +1,40 @@
+import type { IpEnrichment } from "./ip-dataset.js";
+/** Minimal fetch surface so tests can inject a stub (no real network). */
+export type FetchLike = (url: string, init?: {
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json: () => Promise<unknown>;
+}>;
+export interface RdapResolverOptions {
+    /** Bootstrap base; rdap.org redirects to the authoritative RIR. */
+    baseUrl?: string;
+    /** Cache TTL in ms (default 1h). Negative results cached for a shorter time. */
+    ttlMs?: number;
+    /** Per-request timeout in ms (default 4000). */
+    timeoutMs?: number;
+    /** Injected fetch (defaults to global fetch). */
+    fetch?: FetchLike;
+    /** Max cache entries (LRU-ish trim). */
+    maxCache?: number;
+}
+/** Parse an RDAP IP-network response into our enrichment shape. country +
+ *  org/name only; RDAP carries no city or hosting flag. */
+export declare function parseRdapResponse(body: unknown): IpEnrichment | null;
+export declare class RdapResolver {
+    private readonly baseUrl;
+    private readonly ttlMs;
+    private readonly negTtlMs;
+    private readonly timeoutMs;
+    private readonly fetch;
+    private readonly maxCache;
+    private cache;
+    /** Monotonic clock injected for tests; defaults to Date.now via a getter. */
+    now: () => number;
+    constructor(opts?: RdapResolverOptions);
+    /** Look up one IP via RDAP. Returns null on miss/error (never throws —
+     *  a flaky RIR must not fail the batch). Cached by IP with a TTL. */
+    lookup(ip: string): Promise<IpEnrichment | null>;
+    private put;
+}

package/dist/enrich/rdap.js

@@ -0,0 +1,122 @@
+// Optional ONLINE IP enrichment via RDAP (RFC 9082/9083) — issue #477.
+//
+// OFF by default. The offline OMCP_IP_ENRICH_FILE dataset is the preferred,
+// air-gapped path; RDAP is a zero-setup fallback for non-air-gapped operators
+// who don't want to provision a MaxMind licence just to answer "where is this
+// IP / is it a datacenter". When enabled (OMCP_IP_ENRICH_RDAP=on) the gateway
+// queries the authoritative RIR over HTTPS via the rdap.org bootstrap.
+//
+// Privacy: RDAP queries the authoritative registry (not a third-party geo
+// broker) and yields country + org/network-name only (no city, no hosting
+// flag — same limits called out in #477). Results are cached with a TTL to
+// respect RIR rate limits.
+//
+// This module makes NO network call unless an operator has opted in and the
+// resolver is actually constructed (see index.ts) — the air-gapped default of
+// enrich_ips is preserved.
+import { ipv4ToInt, ipv6ToBigInt } from "./ip-dataset.js";
+/** Pull a display org name out of an RDAP entity's jCard (vcardArray). */
+function orgFromEntities(entities) {
+    if (!Array.isArray(entities))
+        return undefined;
+    // Prefer registrant, then any entity with an fn.
+    const ordered = [...entities].sort((a, b) => roleRank(b) - roleRank(a));
+    for (const e of ordered) {
+        const fn = fnFromVcard(e.vcardArray);
+        if (fn)
+            return fn;
+    }
+    return undefined;
+}
+function roleRank(e) {
+    const roles = e.roles;
+    if (Array.isArray(roles) && roles.includes("registrant"))
+        return 2;
+    if (Array.isArray(roles) && roles.includes("registrar"))
+        return 1;
+    return 0;
+}
+function fnFromVcard(vcardArray) {
+    // jCard shape: ["vcard", [ ["version",{},"text","4.0"], ["fn",{},"text","Google LLC"], ... ]]
+    if (!Array.isArray(vcardArray) || vcardArray.length < 2 || !Array.isArray(vcardArray[1]))
+        return undefined;
+    for (const prop of vcardArray[1]) {
+        if (Array.isArray(prop) && prop[0] === "fn" && typeof prop[3] === "string" && prop[3].trim()) {
+            return prop[3].trim();
+        }
+    }
+    return undefined;
+}
+/** Parse an RDAP IP-network response into our enrichment shape. country +
+ *  org/name only; RDAP carries no city or hosting flag. */
+export function parseRdapResponse(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    const b = body;
+    const country = typeof b.country === "string" && b.country.trim() ? b.country.trim() : undefined;
+    const org = orgFromEntities(b.entities) || (typeof b.name === "string" && b.name.trim() ? b.name.trim() : undefined);
+    if (!country && !org)
+        return null;
+    const out = {};
+    if (country)
+        out.country = country;
+    if (org)
+        out.org = org;
+    return out;
+}
+export class RdapResolver {
+    baseUrl;
+    ttlMs;
+    negTtlMs;
+    timeoutMs;
+    fetch;
+    maxCache;
+    cache = new Map();
+    /** Monotonic clock injected for tests; defaults to Date.now via a getter. */
+    now;
+    constructor(opts = {}) {
+        this.baseUrl = (opts.baseUrl || "https://rdap.org").replace(/\/$/, "");
+        this.ttlMs = opts.ttlMs ?? 3_600_000;
+        this.negTtlMs = Math.min(this.ttlMs, 300_000);
+        this.timeoutMs = opts.timeoutMs ?? 4000;
+        this.fetch = opts.fetch ?? globalThis.fetch;
+        this.maxCache = opts.maxCache ?? 10_000;
+        this.now = () => Date.now();
+    }
+    /** Look up one IP via RDAP. Returns null on miss/error (never throws —
+     *  a flaky RIR must not fail the batch). Cached by IP with a TTL. */
+    async lookup(ip) {
+        if (ipv4ToInt(ip) === null && ipv6ToBigInt(ip) === null)
+            return null;
+        const cached = this.cache.get(ip);
+        if (cached && cached.expiresAt > this.now())
+            return cached.value;
+        let value = null;
+        try {
+            const ac = new AbortController();
+            const timer = setTimeout(() => ac.abort(), this.timeoutMs);
+            try {
+                const res = await this.fetch(`${this.baseUrl}/ip/${encodeURIComponent(ip)}`, { signal: ac.signal });
+                if (res.ok)
+                    value = parseRdapResponse(await res.json());
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        catch {
+            value = null; // network/timeout/parse — treat as a miss
+        }
+        this.put(ip, { value, expiresAt: this.now() + (value ? this.ttlMs : this.negTtlMs) });
+        return value;
+    }
+    put(ip, entry) {
+        if (this.cache.size >= this.maxCache) {
+            // Drop the oldest insertion (Map preserves insertion order).
+            const oldest = this.cache.keys().next().value;
+            if (oldest !== undefined)
+                this.cache.delete(oldest);
+        }
+        this.cache.set(ip, entry);
+    }
+}

package/dist/enrich/rdap.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/enrich/rdap.test.js

@@ -0,0 +1,78 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { parseRdapResponse, RdapResolver } from "./rdap.js";
+// A realistic RDAP IP-network response (trimmed). org comes from the
+// registrant entity's jCard fn; country is top-level.
+const RDAP_GOOGLE = {
+    handle: "GOGL",
+    name: "GOGL",
+    country: "US",
+    entities: [
+        { roles: ["registrant"], vcardArray: ["vcard", [["version", {}, "text", "4.0"], ["fn", {}, "text", "Google LLC"]]] },
+    ],
+};
+describe("parseRdapResponse", () => {
+    it("extracts country + org (entity fn preferred over name)", () => {
+        assert.deepEqual(parseRdapResponse(RDAP_GOOGLE), { country: "US", org: "Google LLC" });
+    });
+    it("falls back to network `name` when no entity fn", () => {
+        assert.deepEqual(parseRdapResponse({ country: "DE", name: "DTAG" }), { country: "DE", org: "DTAG" });
+    });
+    it("returns null when neither country nor org is present", () => {
+        assert.equal(parseRdapResponse({ handle: "x" }), null);
+        assert.equal(parseRdapResponse(null), null);
+        assert.equal(parseRdapResponse("nope"), null);
+    });
+});
+function stubFetch(handler) {
+    const calls = [];
+    const fetch = async (url) => {
+        calls.push(url);
+        const r = handler(url);
+        return { ok: r.ok, status: r.status, json: async () => r.body };
+    };
+    return { fetch, calls };
+}
+describe("RdapResolver", () => {
+    it("looks up an IP and parses the response", async () => {
+        const { fetch, calls } = stubFetch(() => ({ ok: true, status: 200, body: RDAP_GOOGLE }));
+        const r = new RdapResolver({ fetch });
+        assert.deepEqual(await r.lookup("8.8.8.8"), { country: "US", org: "Google LLC" });
+        assert.equal(calls.length, 1);
+        assert.match(calls[0], /\/ip\/8\.8\.8\.8$/);
+    });
+    it("caches a hit — second lookup does not re-fetch", async () => {
+        const { fetch, calls } = stubFetch(() => ({ ok: true, status: 200, body: RDAP_GOOGLE }));
+        const r = new RdapResolver({ fetch });
+        await r.lookup("8.8.8.8");
+        await r.lookup("8.8.8.8");
+        assert.equal(calls.length, 1, "second lookup served from cache");
+    });
+    it("caches a negative result (miss) too", async () => {
+        const { fetch, calls } = stubFetch(() => ({ ok: false, status: 404, body: {} }));
+        const r = new RdapResolver({ fetch });
+        assert.equal(await r.lookup("203.0.113.7"), null);
+        assert.equal(await r.lookup("203.0.113.7"), null);
+        assert.equal(calls.length, 1, "negative result cached");
+    });
+    it("re-fetches after the TTL expires", async () => {
+        const { fetch, calls } = stubFetch(() => ({ ok: true, status: 200, body: RDAP_GOOGLE }));
+        const r = new RdapResolver({ fetch, ttlMs: 1000 });
+        let t = 1000;
+        r.now = () => t;
+        await r.lookup("8.8.8.8");
+        t = 2001; // past TTL
+        await r.lookup("8.8.8.8");
+        assert.equal(calls.length, 2, "expired entry re-fetched");
+    });
+    it("returns null for an invalid IP WITHOUT making a request", async () => {
+        const { fetch, calls } = stubFetch(() => ({ ok: true, status: 200, body: RDAP_GOOGLE }));
+        const r = new RdapResolver({ fetch });
+        assert.equal(await r.lookup("not-an-ip"), null);
+        assert.equal(calls.length, 0, "no network call for an invalid IP");
+    });
+    it("never throws on a fetch error — returns null", async () => {
+        const r = new RdapResolver({ fetch: (async () => { throw new Error("network down"); }) });
+        assert.equal(await r.lookup("8.8.8.8"), null);
+    });
+});

package/dist/index.js

@@ -61,6 +61,7 @@ import { queryMetricsHandler } from "./tools/query-metrics.js";
 import { queryLogsHandler } from "./tools/query-logs.js";
 import { enrichIpsHandler } from "./tools/enrich-ips.js";
 import { IpEnrichmentDataset } from "./enrich/ip-dataset.js";
+import { RdapResolver } from "./enrich/rdap.js";
 import { queryTracesHandler } from "./tools/query-traces.js";
 import { getAnomalyHistoryHandler } from "./tools/get-anomaly-history.js";
 import { generatePostmortemHandler } from "./tools/generate-postmortem.js";
@@ -299,6 +300,14 @@ async function main() {
             console.error(`[enrich] failed to load OMCP_IP_ENRICH_FILE (${ipEnrichFile}): ${err instanceof Error ? err.message : String(err)} — enrich_ips will report 'not configured'`);
         }
     }
+    // Optional ONLINE RDAP fallback (issue #477) — OFF by default to keep the
+    // air-gapped guarantee. Built only when OMCP_IP_ENRICH_RDAP is truthy; the
+    // offline CSV stays preferred and RDAP only fills gaps it didn't cover.
+    let ipRdap = null;
+    if (["on", "true", "1"].includes(String(process.env.OMCP_IP_ENRICH_RDAP ?? "").toLowerCase())) {
+        ipRdap = new RdapResolver({ baseUrl: process.env.OMCP_IP_ENRICH_RDAP_URL?.trim() || undefined });
+        console.log("[enrich] RDAP online fallback ENABLED (OMCP_IP_ENRICH_RDAP) — enrich_ips will query rdap.org for gaps the offline dataset doesn't cover");
+    }
     function redactToolText(result, opts = {}) {
         if (!REDACTION_ENABLED)
             return result;
@@ -781,17 +790,17 @@ async function main() {
             return withToolMetrics("get_blast_radius", () => getBlastRadiusHandler(registry, args, ctx));
         });
         registerTool("enrich_ips", [
-            "Resolve a batch of IPv4 addresses to geo (country/city), ASN/org, and a hosting/proxy flag.",
-            "When to use: answering 'where are these visitors from?' or 'which of these IPs are bots / datacenter / VPN exit nodes?' over access logs, without an out-of-band geo-API call per IP.",
-            "Behavior: read-only. Looks each IP up in a LOCAL offline dataset the operator configured (OMCP_IP_ENRICH_FILE) — there is no external network call, so it is safe in air-gapped deployments. Returns one row per input IP with found=true/false plus any known fields. If no dataset is configured it returns a clear notice explaining how to enable it.",
+            "Resolve a batch of IPv4 or IPv6 addresses to geo (country/city), ASN/org, and a hosting/proxy flag.",
+            "When to use: answering 'where are these visitors from?' or 'which of these IPs are bots / datacenter / VPN exit nodes?' over access logs, without an out-of-band geo-API call per IP. Both IPv4 and IPv6 clients are resolved — don't pre-filter v6 out.",
+            "Behavior: read-only. By default looks each IP up in a LOCAL offline dataset the operator configured (OMCP_IP_ENRICH_FILE) with NO external network call — safe in air-gapped deployments. Optionally, if the operator enabled OMCP_IP_ENRICH_RDAP, IPs the dataset doesn't cover fall back to an online RDAP query (country/org only) and the result carries via:'rdap'; the offline dataset is always preferred. Returns one row per input IP with found=true/false plus any known fields. If neither is configured it returns a clear notice explaining how to enable them.",
             "Related: pull the IPs from `query_logs` (use `labels`/`aggregate` to find the IPs of interest first).",
         ].join(" "), {
             ips: z
                 .array(z.string())
-                .describe("Required. IPv4 address strings to enrich (e.g. ['203.0.113.5','198.51.100.9']). Max 1000 per call; invalid entries are returned with found=false rather than failing the batch."),
+                .describe("Required. IPv4 or IPv6 address strings to enrich (e.g. ['203.0.113.5','2001:db8::1']). Max 1000 per call; invalid entries are returned with found=false rather than failing the batch."),
         }, { title: "Enrich IPs", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async (args) => {
             await enforceEntitledAccess(ctx, { tool: "enrich_ips" });
-            return withToolMetrics("enrich_ips", async () => enrichIpsHandler(ipEnrichment, args, ctx));
+            return withToolMetrics("enrich_ips", async () => enrichIpsHandler(ipEnrichment, args, ctx, ipRdap));
         });
         // Phase F10: federated tools — every upstream MCP server's tools
         // show up here under `<prefix>.<upstream-tool>`. The handler is a

package/dist/net/egress-policy.js

@@ -27,6 +27,7 @@ export const EGRESS_ALLOWLIST = [
     { prefix: "index.ts", reason: "connector-hub plugin install of an operator/registry-requested tarball URL" },
     { prefix: "auth/oidc/", reason: "OIDC client calls the operator-configured OMCP_OIDC_ISSUER for discovery, JWKS, and code-exchange" },
     { prefix: "auth/policy/", reason: "OpaPolicyEngine queries the operator-configured OMCP_OPA_URL on every RBAC decision" },
+    { prefix: "enrich/rdap.ts", reason: "enrich_ips RDAP fallback — OFF by default; only when the operator opts in with OMCP_IP_ENRICH_RDAP does it query the RDAP bootstrap. No call otherwise; the air-gapped default is preserved" },
 ];
 /**
  * Hard-blocked analytics/telemetry SDKs — matches an *import/require of the

package/dist/tools/enrich-ips.d.ts

@@ -1,4 +1,5 @@
 import { IpEnrichmentDataset } from "../enrich/ip-dataset.js";
+import type { RdapResolver } from "../enrich/rdap.js";
 import { type RequestContext } from "../context.js";
 export declare const enrichIpsDefinition: {
     name: "enrich_ips";
@@ -15,8 +16,11 @@ export interface IpEnrichmentResult {
     asn?: string;
     org?: string;
     hosting?: boolean;
+    /** Which backend produced the hit — "dataset" (offline CSV) or "rdap"
+     *  (online fallback). Absent when not found. */
+    via?: "dataset" | "rdap";
 }
-export declare function enrichIpsHandler(dataset: IpEnrichmentDataset | null, args: EnrichIpsArgs, _ctx?: RequestContext): {
+export declare function enrichIpsHandler(dataset: IpEnrichmentDataset | null, args: EnrichIpsArgs, _ctx?: RequestContext, rdap?: RdapResolver | null): Promise<{
     content: {
         type: "text";
         text: string;
@@ -27,4 +31,4 @@ export declare function enrichIpsHandler(dataset: IpEnrichmentDataset | null, ar
         type: "text";
         text: string;
     }[];
-};
+}>;

package/dist/tools/enrich-ips.js

@@ -14,15 +14,18 @@ const MAX_IPS = 1000;
 function isValidIp(ip) {
     return ipv4ToInt(ip) !== null || ipv6ToBigInt(ip) !== null;
 }
-export function enrichIpsHandler(dataset, args, 
+export async function enrichIpsHandler(dataset, args, 
 // The RequestContext seam — enrich_ips doesn't scope by tenant today (the
 // dataset is a single process-wide table), but every tool handler threads
 // ctx so access-control / audit can attach without a signature change later.
-_ctx = defaultContext()) {
-    if (!dataset) {
+_ctx = defaultContext(), 
+// Optional online RDAP fallback (issue #477). Present only when the operator
+// set OMCP_IP_ENRICH_RDAP=on; absent → no external call (air-gapped default).
+rdap) {
+    if (!dataset && !rdap) {
         return errorResponse("IP enrichment is not configured. Set OMCP_IP_ENRICH_FILE to a local CSV " +
-            "(network,country,city,asn,org,hosting) to enable offline geo/ASN/hosting " +
-            "lookups — there is no external API call, so it stays air-gapped.");
+            "(network,country,city,asn,org,hosting) for offline lookups (air-gapped), " +
+            "or OMCP_IP_ENRICH_RDAP=on for an online RDAP fallback (country/org only).");
     }
     const ips = args.ips;
     if (!Array.isArray(ips) || ips.length === 0) {
@@ -34,20 +37,31 @@ _ctx = defaultContext()) {
     const results = [];
     let invalid = 0;
     let matched = 0;
+    let viaRdap = 0;
     for (const ip of ips) {
         if (typeof ip !== "string" || !isValidIp(ip)) {
             invalid++;
             results.push({ ip: String(ip), found: false });
             continue;
         }
-        const hit = dataset.lookup(ip);
+        // Offline CSV is preferred (city precision, air-gapped). RDAP only fills
+        // gaps the dataset didn't cover, and only when the operator opted in.
+        const hit = dataset ? dataset.lookup(ip) : null;
         if (hit) {
             matched++;
-            results.push({ ip, found: true, ...hit });
+            results.push({ ip, found: true, via: "dataset", ...hit });
+            continue;
         }
-        else {
-            results.push({ ip, found: false });
+        if (rdap) {
+            const r = await rdap.lookup(ip);
+            if (r) {
+                matched++;
+                viaRdap++;
+                results.push({ ip, found: true, via: "rdap", ...r });
+                continue;
+            }
         }
+        results.push({ ip, found: false });
     }
     return {
         content: [
@@ -55,8 +69,15 @@ _ctx = defaultContext()) {
                 type: "text",
                 text: JSON.stringify({
                     results,
-                    summary: { total: ips.length, matched, unmatched: ips.length - matched - invalid, invalid },
-                    datasetSize: dataset.size,
+                    summary: {
+                        total: ips.length,
+                        matched,
+                        unmatched: ips.length - matched - invalid,
+                        invalid,
+                        ...(rdap ? { viaRdap } : {}),
+                    },
+                    datasetSize: dataset?.size ?? 0,
+                    ...(rdap ? { rdapEnabled: true } : {}),
                 }, null, 2),
             },
         ],

package/dist/tools/enrich-ips.test.js

@@ -7,21 +7,21 @@ function parse(result) {
 }
 const ds = IpEnrichmentDataset.fromCsv(["1.2.3.0/24,US,Ashburn,AS14618,Example Cloud,true", "203.0.113.5,DE,Berlin,AS3320,Example ISP,false"].join("\n"));
 describe("enrichIpsHandler (R6, issue #415 Gap B)", () => {
-    it("returns a clear 'not configured' notice when no dataset is loaded", () => {
-        const out = parse(enrichIpsHandler(null, { ips: ["1.2.3.4"] }));
+    it("returns a clear 'not configured' notice when no dataset is loaded", async () => {
+        const out = parse(await enrichIpsHandler(null, { ips: ["1.2.3.4"] }));
         assert.match(out.error, /not configured/i);
         assert.match(out.error, /OMCP_IP_ENRICH_FILE/);
     });
-    it("rejects empty / missing ips", () => {
-        assert.match(parse(enrichIpsHandler(ds, { ips: [] })).error, /non-empty array/i);
-        assert.match(parse(enrichIpsHandler(ds, {})).error, /non-empty array/i);
+    it("rejects empty / missing ips", async () => {
+        assert.match(parse(await enrichIpsHandler(ds, { ips: [] })).error, /non-empty array/i);
+        assert.match(parse(await enrichIpsHandler(ds, {})).error, /non-empty array/i);
     });
-    it("rejects an over-large batch", () => {
+    it("rejects an over-large batch", async () => {
         const many = Array.from({ length: 1001 }, (_, i) => `1.2.3.${i % 255}`);
-        assert.match(parse(enrichIpsHandler(ds, { ips: many })).error, /Too many IPs/i);
+        assert.match(parse(await enrichIpsHandler(ds, { ips: many })).error, /Too many IPs/i);
     });
-    it("enriches known IPs and reports found=false for misses + invalid", () => {
-        const out = parse(enrichIpsHandler(ds, { ips: ["1.2.3.99", "8.8.8.8", "not-an-ip"] }));
+    it("enriches known IPs and reports found=false for misses + invalid", async () => {
+        const out = parse(await enrichIpsHandler(ds, { ips: ["1.2.3.99", "8.8.8.8", "not-an-ip"] }));
         assert.equal(out.results.length, 3);
         const matched = out.results.find((r) => r.ip === "1.2.3.99");
         assert.equal(matched.found, true);
@@ -35,9 +35,9 @@ describe("enrichIpsHandler (R6, issue #415 Gap B)", () => {
         assert.deepEqual(out.summary, { total: 3, matched: 1, unmatched: 1, invalid: 1 });
         assert.equal(out.datasetSize, 2);
     });
-    it("accepts IPv6 inputs and enriches them (not counted invalid)", () => {
+    it("accepts IPv6 inputs and enriches them (not counted invalid)", async () => {
         const ds6 = IpEnrichmentDataset.fromCsv(["2001:db8::/32,US,,AS14618,Example Cloud,true", "1.2.3.0/24,DE,Berlin,AS3320,Example ISP,false"].join("\n"));
-        const out = parse(enrichIpsHandler(ds6, { ips: ["2001:db8::1", "2606:4700::1", "1.2.3.9"] }));
+        const out = parse(await enrichIpsHandler(ds6, { ips: ["2001:db8::1", "2606:4700::1", "1.2.3.9"] }));
         const v6hit = out.results.find((r) => r.ip === "2001:db8::1");
         assert.equal(v6hit.found, true);
         assert.equal(v6hit.org, "Example Cloud");
@@ -47,3 +47,47 @@ describe("enrichIpsHandler (R6, issue #415 Gap B)", () => {
         assert.deepEqual(out.summary, { total: 3, matched: 2, unmatched: 1, invalid: 0 });
     });
 });
+describe("enrichIpsHandler — optional RDAP fallback (issue #477)", () => {
+    // Minimal RdapResolver stub: returns a fixed hit for one IP, null otherwise,
+    // and records which IPs it was asked about (to prove CSV-first).
+    function rdapStub(hit) {
+        const asked = [];
+        return {
+            asked,
+            resolver: { lookup: async (ip) => { asked.push(ip); return hit[ip] ?? null; } },
+        };
+    }
+    it("with no dataset but RDAP enabled → not 'not configured'; resolves via RDAP", async () => {
+        const { resolver } = rdapStub({ "8.8.8.8": { country: "US", org: "Google LLC" } });
+        const out = parse(await enrichIpsHandler(null, { ips: ["8.8.8.8", "203.0.113.9"] }, undefined, resolver));
+        const hit = out.results.find((r) => r.ip === "8.8.8.8");
+        assert.equal(hit.found, true);
+        assert.equal(hit.via, "rdap");
+        assert.equal(hit.org, "Google LLC");
+        assert.equal(out.results.find((r) => r.ip === "203.0.113.9").found, false);
+        assert.equal(out.summary.viaRdap, 1);
+        assert.equal(out.rdapEnabled, true);
+    });
+    it("offline dataset is PREFERRED — RDAP is not consulted for a covered IP", async () => {
+        const { asked, resolver } = rdapStub({ "1.2.3.9": { country: "XX", org: "should-not-be-used" } });
+        const out = parse(await enrichIpsHandler(ds, { ips: ["1.2.3.9"] }, undefined, resolver));
+        const hit = out.results.find((r) => r.ip === "1.2.3.9");
+        assert.equal(hit.via, "dataset");
+        assert.equal(hit.city, "Ashburn"); // from the CSV, not RDAP
+        assert.deepEqual(asked, [], "RDAP must not be queried for a dataset-covered IP");
+    });
+    it("RDAP fills only the gaps the dataset didn't cover", async () => {
+        const { asked, resolver } = rdapStub({ "9.9.9.9": { country: "US", org: "Quad9" } });
+        const out = parse(await enrichIpsHandler(ds, { ips: ["1.2.3.9", "9.9.9.9"] }, undefined, resolver));
+        assert.equal(out.results.find((r) => r.ip === "1.2.3.9").via, "dataset");
+        assert.equal(out.results.find((r) => r.ip === "9.9.9.9").via, "rdap");
+        assert.deepEqual(asked, ["9.9.9.9"], "RDAP queried only for the uncovered IP");
+        assert.equal(out.summary.matched, 2);
+        assert.equal(out.summary.viaRdap, 1);
+    });
+    it("no dataset and no RDAP → still 'not configured', and names both options", async () => {
+        const out = parse(await enrichIpsHandler(null, { ips: ["8.8.8.8"] }));
+        assert.match(out.error, /not configured/i);
+        assert.match(out.error, /OMCP_IP_ENRICH_RDAP/);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thotischner/observability-mcp",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "description": "Unified observability gateway for AI agents — one MCP server for Prometheus, Loki, and any backend",
   "type": "module",
   "license": "Apache-2.0",