@thotischner/observability-mcp 3.6.1 → 3.8.0

package/dist/inspect/signature.test.js

@@ -0,0 +1,136 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { deriveSignature, countBucket, durationToSeconds, durationBucket, numBucket, queryFingerprint, } from "./signature.js";
+describe("buckets", () => {
+    it("countBucket bands", () => {
+        assert.equal(countBucket(0), "1");
+        assert.equal(countBucket(1), "1");
+        assert.equal(countBucket(7), "2-10");
+        assert.equal(countBucket(50), "11-100");
+        assert.equal(countBucket(900), "101-1000");
+        assert.equal(countBucket(5000), ">1000");
+    });
+    it("durationToSeconds parses prom/loki durations", () => {
+        assert.equal(durationToSeconds("5m"), 300);
+        assert.equal(durationToSeconds("1h"), 3600);
+        assert.equal(durationToSeconds("1h30m"), 5400);
+        assert.equal(durationToSeconds("2d"), 172800);
+        assert.equal(durationToSeconds("250ms"), 0.25);
+    });
+    it("durationToSeconds rejects non-durations", () => {
+        assert.equal(durationToSeconds("not-a-duration"), null);
+        assert.equal(durationToSeconds("100"), null);
+        assert.equal(durationToSeconds(""), null);
+    });
+    it("durationBucket bands + 'other' for junk", () => {
+        assert.equal(durationBucket("30s"), "<=5m");
+        assert.equal(durationBucket("45m"), "<=1h");
+        assert.equal(durationBucket("12h"), "<=1d");
+        assert.equal(durationBucket("7d"), ">1d");
+        assert.equal(durationBucket("garbage"), "other");
+    });
+    it("numBucket bands", () => {
+        assert.equal(numBucket(5), "<=10");
+        assert.equal(numBucket(50), "<=100");
+        assert.equal(numBucket(500), "<=1000");
+        assert.equal(numBucket(9999), ">1000");
+    });
+});
+describe("queryFingerprint", () => {
+    it("blank → empty", () => {
+        assert.equal(queryFingerprint(""), "empty");
+        assert.equal(queryFingerprint("   "), "empty");
+    });
+    it("extracts func + metric + label from a PromQL rate query", () => {
+        const fp = queryFingerprint('rate(http_requests_total{job="api"}[5m])');
+        assert.match(fp, /f:rate/);
+        assert.match(fp, /m:http_requests_total/);
+        assert.match(fp, /l:job/);
+        // the range fragment "m" and the quoted value "api" are NOT metrics
+        assert.ok(!/[, ]m[, ]|m:.*\bm\b/.test(fp.replace("http_requests_total", "")));
+        assert.ok(!fp.includes("api"));
+    });
+    it("treats by()-grouping labels as labels, not metrics", () => {
+        const fp = queryFingerprint("sum by (instance) (up)");
+        assert.match(fp, /f:sum/);
+        assert.match(fp, /m:up/);
+        assert.match(fp, /l:instance/);
+    });
+    it("LogQL stream selector → label keys", () => {
+        const fp = queryFingerprint('{service_name="payment", level="error"} |= "boom"');
+        assert.match(fp, /l:level,service_name/);
+        assert.ok(!fp.includes("payment") && !fp.includes("boom"));
+    });
+    it("is deterministic + sorted + capped", () => {
+        const a = queryFingerprint('sum(rate(a_total[1m])) + avg(b_total)');
+        const b = queryFingerprint('avg(b_total) + sum(rate(a_total[1m]))');
+        assert.equal(a, b);
+        assert.match(a, /f:avg,rate,sum/);
+        assert.match(a, /m:a_total,b_total/);
+    });
+    it("is fast on a huge attacker-supplied query (no ReDoS)", () => {
+        const t0 = Date.now();
+        queryFingerprint("a".repeat(100000));
+        queryFingerprint("(".repeat(50000));
+        queryFingerprint("rate(".repeat(20000));
+        assert.ok(Date.now() - t0 < 100, "fingerprint stays linear/bounded on large input");
+    });
+    it("non-query free text with no structure → present", () => {
+        assert.equal(queryFingerprint("just some words"), "m:just,some,words"); // bare idents count as metrics
+        assert.equal(queryFingerprint("!!!"), "present");
+    });
+});
+describe("deriveSignature query fingerprinting", () => {
+    it("query/expr keys get a fingerprint, not 'present'", () => {
+        const sig = deriveSignature("query_metrics", { service: "pay", query: 'rate(http_requests_total[5m])' });
+        assert.match(sig.argShape.query, /m:http_requests_total/);
+        assert.match(sig.argShape.query, /f:rate/);
+    });
+    it("non-query free text still collapses to 'present'", () => {
+        const sig = deriveSignature("x", { note: "hello world" });
+        assert.equal(sig.argShape.note, "present");
+    });
+});
+describe("deriveSignature", () => {
+    it("lifts source/service/namespace as real resource dimensions", () => {
+        const sig = deriveSignature("query_logs", { source: "prom-eu", service: "payment", namespace: "omcp" });
+        assert.equal(sig.source, "prom-eu");
+        assert.equal(sig.service, "payment");
+        assert.equal(sig.namespace, "omcp");
+    });
+    it("buckets array length, never keeps elements", () => {
+        const sig = deriveSignature("enrich_ips", { ips: ["1.2.3.4", "5.6.7.8", "9.9.9.9"] });
+        assert.equal(sig.argShape.ips, "n=2-10");
+        assert.ok(!("source" in sig));
+    });
+    it("buckets duration-shaped keys, fingerprints queries (literal never kept)", () => {
+        const sig = deriveSignature("query_metrics", { query: "rate(http_requests_total[5m])", window: "1h", limit: 500 });
+        assert.match(sig.argShape.query, /m:http_requests_total/); // structural, not the literal
+        assert.ok(!sig.argShape.query.includes("[5m]"));
+        assert.equal(sig.argShape.window, "<=1h");
+        assert.equal(sig.argShape.limit, "<=1000");
+    });
+    it("handles booleans, empty strings, nested objects, and non-objects", () => {
+        const sig = deriveSignature("x", { flag: true, empty: "", nested: { a: 1 } });
+        assert.equal(sig.argShape.flag, "true");
+        assert.equal(sig.argShape.empty, "empty");
+        assert.equal(sig.argShape.nested, "object");
+        assert.deepEqual(deriveSignature("x", null), { argShape: {} });
+        assert.deepEqual(deriveSignature("x", "str"), { argShape: {} });
+    });
+    it("drops prototype-polluting arg keys (__proto__/constructor/prototype)", () => {
+        const sig = deriveSignature("x", JSON.parse('{"__proto__":"p","constructor":"c","prototype":"q","ok":5}'));
+        const keys = Object.keys(sig.argShape);
+        assert.ok(!keys.includes("__proto__"));
+        assert.ok(!keys.includes("constructor"));
+        assert.ok(!keys.includes("prototype"));
+        assert.equal(sig.argShape.ok, "<=10");
+        // prototype not polluted
+        assert.equal({}.p, undefined);
+    });
+    it("is deterministic", () => {
+        const a = deriveSignature("query_logs", { source: "s", service: "v", limit: 5, window: "5m" });
+        const b = deriveSignature("query_logs", { window: "5m", limit: 5, service: "v", source: "s" });
+        assert.deepEqual(a, b);
+    });
+});

package/dist/inspect/store.d.ts

@@ -0,0 +1,62 @@
+export type Outcome = "ok" | "error";
+export type Decision = "allow" | "would-block" | "blocked";
+/** A single recorded tool-call observation (a signature, never raw args). */
+export interface Observation {
+    ts: string;
+    seq: number;
+    principal: string;
+    auth: string;
+    tenant: string;
+    tool: string;
+    source?: string;
+    service?: string;
+    namespace?: string;
+    argShape: Record<string, string>;
+    outcome: Outcome;
+    decision: Decision;
+    /** Deviation kind when the call fell outside the profile (dry-run/enforce). */
+    deviation?: string;
+    /** How many PII matches the redactor stripped from the args before shaping. */
+    redactions: number;
+}
+export type ObservationInput = Omit<Observation, "ts" | "seq"> & {
+    ts?: string;
+};
+export interface QueryOpts {
+    from?: string;
+    to?: string;
+    principal?: string;
+    tool?: string;
+    outcome?: Outcome;
+    decision?: Decision;
+    limit?: number;
+}
+export interface InspectStoreOptions {
+    /** JSONL mirror path. When unset, the store is memory-only. */
+    file?: string;
+    /** Ring-buffer capacity (default 5000). */
+    cap?: number;
+    /** Clock seam for tests. */
+    now?: () => number;
+    /** Best-effort async appender seam for tests (defaults to fs append). */
+    appender?: (file: string, line: string) => Promise<void>;
+}
+export declare class InspectStore {
+    private ring;
+    private readonly cap;
+    private readonly file?;
+    private readonly now;
+    private readonly appender;
+    private seqCounter;
+    constructor(opts?: InspectStoreOptions);
+    /** Record one observation. Never throws. */
+    record(input: ObservationInput): Observation;
+    /** Newest-first query with optional filters. */
+    list(opts?: QueryOpts): Observation[];
+    /** All observations at or after `sinceMs` (epoch millis), oldest-first. */
+    since(sinceMs: number): Observation[];
+    /** Every observation currently retained (oldest-first). */
+    all(): Observation[];
+    get size(): number;
+    get persisted(): boolean;
+}

package/dist/inspect/store.js

@@ -0,0 +1,76 @@
+// Inspect — observation store.
+//
+// Mirrors the audit-log storage pattern: an in-memory ring buffer (always on)
+// plus an optional append-only JSONL mirror for durability. The ring is the
+// query surface; the file is a write-only durable copy. Writes are best-effort
+// and never throw — observation must never be able to slow down or fail a tool
+// call.
+import { appendFile } from "node:fs/promises";
+const DEFAULT_CAP = 5000;
+export class InspectStore {
+    ring = [];
+    cap;
+    file;
+    now;
+    appender;
+    seqCounter = 0;
+    constructor(opts = {}) {
+        this.cap = opts.cap && opts.cap > 0 ? opts.cap : DEFAULT_CAP;
+        this.file = opts.file;
+        this.now = opts.now ?? (() => Date.now());
+        this.appender = opts.appender ?? ((f, line) => appendFile(f, line));
+    }
+    /** Record one observation. Never throws. */
+    record(input) {
+        const obs = {
+            ...input,
+            ts: input.ts ?? new Date(this.now()).toISOString(),
+            seq: ++this.seqCounter,
+        };
+        this.ring.push(obs);
+        if (this.ring.length > this.cap)
+            this.ring.shift();
+        if (this.file) {
+            // Fire-and-forget durable mirror; a failing disk never affects the call.
+            void this.appender(this.file, JSON.stringify(obs) + "\n").catch(() => { });
+        }
+        return obs;
+    }
+    /** Newest-first query with optional filters. */
+    list(opts = {}) {
+        const limit = opts.limit && opts.limit > 0 ? Math.min(opts.limit, this.cap) : 200;
+        const out = [];
+        for (let i = this.ring.length - 1; i >= 0 && out.length < limit; i--) {
+            const e = this.ring[i];
+            if (opts.from && e.ts < opts.from)
+                continue;
+            if (opts.to && e.ts > opts.to)
+                continue;
+            if (opts.principal && e.principal !== opts.principal)
+                continue;
+            if (opts.tool && e.tool !== opts.tool)
+                continue;
+            if (opts.outcome && e.outcome !== opts.outcome)
+                continue;
+            if (opts.decision && e.decision !== opts.decision)
+                continue;
+            out.push(e);
+        }
+        return out;
+    }
+    /** All observations at or after `sinceMs` (epoch millis), oldest-first. */
+    since(sinceMs) {
+        const cutoff = new Date(sinceMs).toISOString();
+        return this.ring.filter((e) => e.ts >= cutoff);
+    }
+    /** Every observation currently retained (oldest-first). */
+    all() {
+        return [...this.ring];
+    }
+    get size() {
+        return this.ring.length;
+    }
+    get persisted() {
+        return !!this.file;
+    }
+}

package/dist/inspect/store.test.d.ts

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

package/dist/inspect/store.test.js

@@ -0,0 +1,78 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { InspectStore } from "./store.js";
+function mk(over = {}) {
+    return {
+        principal: "key:bot",
+        auth: "apikey",
+        tenant: "default",
+        tool: "query_logs",
+        argShape: {},
+        outcome: "ok",
+        decision: "allow",
+        redactions: 0,
+        ...over,
+    };
+}
+describe("InspectStore", () => {
+    it("assigns ts + monotonic seq and returns the stored observation", () => {
+        let t = 1_700_000_000_000;
+        const s = new InspectStore({ now: () => t });
+        const a = s.record(mk());
+        t += 1000;
+        const b = s.record(mk());
+        assert.equal(a.seq, 1);
+        assert.equal(b.seq, 2);
+        assert.ok(a.ts < b.ts);
+        assert.equal(s.size, 2);
+    });
+    it("rings out the oldest beyond cap", () => {
+        const s = new InspectStore({ cap: 3 });
+        for (let i = 0; i < 5; i++)
+            s.record(mk({ tool: `t${i}` }));
+        assert.equal(s.size, 3);
+        const tools = s.all().map((o) => o.tool);
+        assert.deepEqual(tools, ["t2", "t3", "t4"]);
+    });
+    it("filters by principal / tool / outcome / decision, newest-first", () => {
+        const s = new InspectStore();
+        s.record(mk({ principal: "a", tool: "query_logs", outcome: "ok" }));
+        s.record(mk({ principal: "b", tool: "query_metrics", outcome: "error" }));
+        s.record(mk({ principal: "a", tool: "query_metrics", decision: "would-block" }));
+        assert.equal(s.list({ principal: "a" }).length, 2);
+        assert.equal(s.list({ tool: "query_metrics" }).length, 2);
+        assert.equal(s.list({ outcome: "error" }).length, 1);
+        assert.equal(s.list({ decision: "would-block" }).length, 1);
+        // newest first
+        assert.equal(s.list({ principal: "a" })[0].decision, "would-block");
+    });
+    it("respects limit", () => {
+        const s = new InspectStore();
+        for (let i = 0; i < 10; i++)
+            s.record(mk());
+        assert.equal(s.list({ limit: 4 }).length, 4);
+    });
+    it("since() returns observations at/after a cutoff", () => {
+        let t = 1_700_000_000_000;
+        const s = new InspectStore({ now: () => t });
+        s.record(mk({ tool: "old" }));
+        t += 60_000;
+        const cut = t;
+        t += 1000;
+        s.record(mk({ tool: "new" }));
+        const recent = s.since(cut);
+        assert.equal(recent.length, 1);
+        assert.equal(recent[0].tool, "new");
+    });
+    it("mirrors to the file appender when configured; never throws on append failure", () => {
+        const lines = [];
+        const s = new InspectStore({ file: "inspect-store-test.jsonl", appender: async (_f, l) => { lines.push(l); } });
+        assert.equal(s.persisted, true);
+        s.record(mk({ tool: "logged" }));
+        // appender is fire-and-forget; the line is queued synchronously here
+        assert.equal(lines.length, 1);
+        assert.match(lines[0], /"tool":"logged"/);
+        const boom = new InspectStore({ file: "inspect-store-test.jsonl", appender: async () => { throw new Error("disk full"); } });
+        assert.doesNotThrow(() => boom.record(mk()));
+    });
+});

package/dist/metrics/self.d.ts

@@ -6,6 +6,9 @@ export declare const connectorCalls: Counter<"type" | "source" | "outcome" | "op
 export declare const apiRequests: Counter<"status" | "route" | "method">;
 export declare const mcpActiveSessions: Gauge<string>;
 export declare const auditDlqDepth: Gauge<string>;
+export declare const inspectEvents: Counter<"tool" | "outcome" | "decision">;
+/** Record one inspection observation in the self-metrics registry. Never throws. */
+export declare function recordInspectEvent(tool: string, outcome: string, decision: string): void;
 /**
  * Wrap a (potentially async) tool handler to record call count + latency.
  * Outcome is "ok" or "error" — never throws on its own.

package/dist/metrics/self.js

@@ -48,6 +48,25 @@ export const auditDlqDepth = new Gauge({
     help: "Number of audit entries waiting in the webhook-sink dead-letter queue.",
     registers: [selfRegistry],
 });
+// Inspect: one counter per recorded tool-call observation, labelled by tool,
+// outcome (ok/error) and decision (allow/would-block/blocked). Lets operators
+// graph deviation/block rates straight from Prometheus alongside the in-app
+// Flows view.
+export const inspectEvents = new Counter({
+    name: "obsmcp_inspect_events_total",
+    help: "Inspect observations by tool, outcome and policy decision.",
+    labelNames: ["tool", "outcome", "decision"],
+    registers: [selfRegistry],
+});
+/** Record one inspection observation in the self-metrics registry. Never throws. */
+export function recordInspectEvent(tool, outcome, decision) {
+    try {
+        inspectEvents.inc({ tool, outcome, decision });
+    }
+    catch {
+        /* metrics must never affect the call path */
+    }
+}
 /**
  * Wrap a (potentially async) tool handler to record call count + latency.
  * Outcome is "ok" or "error" — never throws on its own.

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/tenancy/context.d.ts

@@ -43,3 +43,10 @@ export declare function tenantFromClaim(claims: Record<string, unknown>, claimPa
  *  cognitive load stays low. Invalid tenant strings normalise to
  *  DEFAULT_TENANT silently. */
 export declare function parseKeyTenants(raw: string | undefined): Map<string, string>;
+/** Is the deployment ACTIVELY multi-tenant — i.e. configured to place any
+ *  identity in a NON-default tenant? True when an OIDC tenant claim is set,
+ *  or OMCP_KEY_TENANTS maps a credential to a tenant other than `default`.
+ *  The single-tenant default (no claim, no non-default key mapping) returns
+ *  false, so the open-source path stays free. This is the predicate the boot
+ *  sequence uses to decide whether the `tenancy` entitlement is required. */
+export declare function isMultiTenantConfigured(oidcTenantClaim: string | undefined, keyTenantsEnv: string | undefined): boolean;

package/dist/tenancy/context.js

@@ -95,3 +95,18 @@ export function parseKeyTenants(raw) {
     }
     return out;
 }
+/** Is the deployment ACTIVELY multi-tenant — i.e. configured to place any
+ *  identity in a NON-default tenant? True when an OIDC tenant claim is set,
+ *  or OMCP_KEY_TENANTS maps a credential to a tenant other than `default`.
+ *  The single-tenant default (no claim, no non-default key mapping) returns
+ *  false, so the open-source path stays free. This is the predicate the boot
+ *  sequence uses to decide whether the `tenancy` entitlement is required. */
+export function isMultiTenantConfigured(oidcTenantClaim, keyTenantsEnv) {
+    if (oidcTenantClaim && oidcTenantClaim.trim().length > 0)
+        return true;
+    for (const t of parseKeyTenants(keyTenantsEnv).values()) {
+        if (t && t !== DEFAULT_TENANT)
+            return true;
+    }
+    return false;
+}

package/dist/tenancy/context.test.js

@@ -1,6 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { DEFAULT_TENANT, MAX_TENANT_LENGTH, normaliseTenant, tenantFromClaim, parseKeyTenants, } from "./context.js";
+import { DEFAULT_TENANT, MAX_TENANT_LENGTH, normaliseTenant, tenantFromClaim, parseKeyTenants, isMultiTenantConfigured, } from "./context.js";
 test("normaliseTenant — happy paths", () => {
     assert.equal(normaliseTenant("acme"), "acme");
     assert.equal(normaliseTenant("ACME"), "acme", "lowercases");
@@ -70,3 +70,20 @@ test("parseKeyTenants — undefined / empty returns empty map", () => {
     assert.equal(parseKeyTenants(undefined).size, 0);
     assert.equal(parseKeyTenants("").size, 0);
 });
+test("isMultiTenantConfigured — single-tenant default is false (OSS path stays free)", () => {
+    // No OIDC tenant claim, no key-tenant mapping → single-tenant.
+    assert.equal(isMultiTenantConfigured(undefined, undefined), false);
+    assert.equal(isMultiTenantConfigured("", ""), false);
+    // Mappings that only ever resolve to `default` are NOT multi-tenant.
+    assert.equal(isMultiTenantConfigured("", "agent=default;ci=default"), false);
+    // Invalid tenant strings normalise to `default`, so they don't trip it.
+    assert.equal(isMultiTenantConfigured("", "agent=!!!bad!!!"), false);
+});
+test("isMultiTenantConfigured — true once a non-default tenant is configured", () => {
+    // An OIDC tenant claim alone activates multi-tenancy.
+    assert.equal(isMultiTenantConfigured("tid", undefined), true);
+    assert.equal(isMultiTenantConfigured("  tenant  ", undefined), true);
+    // A non-default key→tenant mapping activates it.
+    assert.equal(isMultiTenantConfigured("", "agent=acme"), true);
+    assert.equal(isMultiTenantConfigured("", "agent=default;ci=bigco"), true);
+});

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),
             },
         ],