@thotischner/observability-mcp 3.1.0 → 3.2.0

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

@@ -113,6 +113,47 @@ test("MCP 2025-11-25: tools/list returns a Tool[] each with name + inputSchema",
         assert.ok(t.inputSchema && typeof t.inputSchema === "object", `tool ${t.name} missing inputSchema`);
     }
 });
+test("MCP 2025-11-25: query_logs advertises labels + aggregate params (issue #415)", opts, async () => {
+    // Regression guard for the v3.1.0 ship gap: the labels/aggregate handler
+    // code existed but the inline MCP schema in createMcpServer never declared
+    // them, so a live tools/list omitted them and the SDK stripped them from
+    // calls — a silent no-op. Assert the live server advertises both.
+    const session = await newSession();
+    const { response } = await jsonRpc("tools/list", {}, { id: 2, session });
+    const r = response.result;
+    const queryLogs = r.tools?.find((t) => t.name === "query_logs");
+    assert.ok(queryLogs, "query_logs tool must be advertised");
+    const props = queryLogs.inputSchema?.properties ?? {};
+    assert.ok("labels" in props, "query_logs must advertise a `labels` param (issue #415 #1)");
+    assert.ok("aggregate" in props, "query_logs must advertise an `aggregate` param (issue #415 #2)");
+});
+test("MCP 2025-11-25: query_metrics advertises labels param (issue #415 #4)", opts, async () => {
+    const session = await newSession();
+    const { response } = await jsonRpc("tools/list", {}, { id: 2, session });
+    const r = response.result;
+    const queryMetrics = r.tools?.find((t) => t.name === "query_metrics");
+    assert.ok(queryMetrics, "query_metrics tool must be advertised");
+    const props = queryMetrics.inputSchema?.properties ?? {};
+    assert.ok("labels" in props, "query_metrics must advertise a `labels` param (issue #415 #4)");
+});
+test("MCP 2025-11-25: query_metrics + query_logs advertise raw_query (issue #415 #3)", opts, async () => {
+    const session = await newSession();
+    const { response } = await jsonRpc("tools/list", {}, { id: 2, session });
+    const r = response.result;
+    for (const name of ["query_metrics", "query_logs"]) {
+        const tool = r.tools?.find((t) => t.name === name);
+        assert.ok(tool, `${name} tool must be advertised`);
+        assert.ok("raw_query" in (tool.inputSchema?.properties ?? {}), `${name} must advertise a raw_query param`);
+    }
+});
+test("MCP 2025-11-25: enrich_ips tool is advertised (issue #415 Gap B)", opts, async () => {
+    const session = await newSession();
+    const { response } = await jsonRpc("tools/list", {}, { id: 2, session });
+    const r = response.result;
+    const tool = r.tools?.find((t) => t.name === "enrich_ips");
+    assert.ok(tool, "enrich_ips tool must be advertised");
+    assert.ok("ips" in (tool.inputSchema?.properties ?? {}), "enrich_ips must advertise an `ips` param");
+});
 test("MCP 2025-11-25: tools/call dispatches and returns CallToolResult", opts, async () => {
     const session = await newSession();
     const { response } = await jsonRpc("tools/call", { name: "list_sources", arguments: {} }, { id: 3, session });

package/dist/connectors/loki.js

@@ -166,22 +166,31 @@ export class LokiConnector {
     async queryLogs(params) {
         const { start, end } = this.parseTimeRange(params.duration);
         const limit = Math.min(Math.max(params.limit || 100, 1), 1000);
-        // Resolve label + actual selector value. For the 'container' label the
-        // value stored in Loki may be '/my-app-1' while the caller passes the
-        // sanitized 'my-app-1' — return the prefixed form so the LogQL selector
-        // matches the real stream.
-        const { label: matchedLabel, value: rawValue } = await this.resolveServiceSelector(params.service);
-        const service = this.escapeLogQLValue(rawValue);
-        let logql = `{${matchedLabel}="${service}"} | json`;
-        if (params.level) {
-            logql += ` | level="${this.escapeLogQLValue(params.level)}"`;
+        let logql;
+        if (params.rawQuery) {
+            // Raw LogQL passthrough (capability-gated at the tool layer): the caller
+            // supplied a verbatim log-selector query. Skip the curated stream
+            // selector / | json / label-filter construction and run it as-is.
+            logql = params.rawQuery;
         }
-        // Structured equality filters (method/status/url/environment/…) — run
-        // after `| json` so backend-extracted fields are selectable.
-        logql += logqlLabelFilters(params.labels);
-        if (params.query) {
-            const query = this.escapeLogQLRegex(params.query);
-            logql += ` |~ \`${query}\``;
+        else {
+            // Resolve label + actual selector value. For the 'container' label the
+            // value stored in Loki may be '/my-app-1' while the caller passes the
+            // sanitized 'my-app-1' — return the prefixed form so the LogQL selector
+            // matches the real stream.
+            const { label: matchedLabel, value: rawValue } = await this.resolveServiceSelector(params.service);
+            const service = this.escapeLogQLValue(rawValue);
+            logql = `{${matchedLabel}="${service}"} | json`;
+            if (params.level) {
+                logql += ` | level="${this.escapeLogQLValue(params.level)}"`;
+            }
+            // Structured equality filters (method/status/url/environment/…) — run
+            // after `| json` so backend-extracted fields are selectable.
+            logql += logqlLabelFilters(params.labels);
+            if (params.query) {
+                const query = this.escapeLogQLRegex(params.query);
+                logql += ` |~ \`${query}\``;
+            }
         }
         const url = `/loki/api/v1/query_range?query=${encodeURIComponent(logql)}` +
             `&start=${start}000000000&end=${end}000000000&limit=${limit}`;

package/dist/connectors/loki.test.js

@@ -81,6 +81,21 @@ describe("Q-LOG1: queryLogs LogQL assembly", () => {
         const q = await captureQuery({});
         assert.equal(q, '{service_name="payment"} | json');
     });
+    it("R4: rawQuery is sent verbatim, bypassing the curated selector", async () => {
+        const q = await captureQuery({
+            rawQuery: '{app="x", env="prod"} | json | status>=`500`',
+        });
+        assert.equal(q, '{app="x", env="prod"} | json | status>=`500`');
+    });
+    it("R4: rawQuery ignores service/labels/level/query", async () => {
+        const q = await captureQuery({
+            rawQuery: '{job="raw"}',
+            labels: { method: "GET" },
+            level: "error",
+            query: "ignored",
+        });
+        assert.equal(q, '{job="raw"}');
+    });
 });
 describe("Q-LOG2: parseDurationSeconds / defaultBucketSeconds", () => {
     it("parses m/h/d", () => {

package/dist/connectors/prometheus.d.ts

@@ -22,6 +22,7 @@ export declare class PrometheusConnector implements ObservabilityConnector {
     private listServicesFromJobLabel;
     listAvailableMetrics(_service: string): Promise<MetricInfo[]>;
     queryMetrics(params: MetricQuery): Promise<MetricResult>;
+    private queryRaw;
     private buildQuery;
     private groupKey;
     private getDistinctLabelValues;

package/dist/connectors/prometheus.js

@@ -196,7 +196,13 @@ export class PrometheusConnector {
         return metrics;
     }
     async queryMetrics(params) {
-        const { promql, label, candidate } = await this.buildQuery(params.service, params.metric, params.groupBy);
+        // Raw passthrough: the caller supplied verbatim PromQL (capability-gated
+        // at the tool layer). Skip the curated catalog/selector machinery and the
+        // breakdown-hint probe; run the query as-is over query_range.
+        if (params.rawQuery) {
+            return this.queryRaw(params.rawQuery, params.duration, params.step);
+        }
+        const { promql, label, candidate } = await this.buildQuery(params.service, params.metric, params.groupBy, params.labels);
         const { start, end, step } = this.parseTimeRange(params.duration, params.step);
         const data = await this.apiGet(`/api/v1/query_range?query=${encodeURIComponent(promql)}&start=${start}&end=${end}&step=${step}`);
         const seriesList = data?.data?.result || [];
@@ -253,8 +259,48 @@ export class PrometheusConnector {
         }
         return result;
     }
+    // Raw PromQL passthrough — used by queryMetrics when params.rawQuery is set.
+    // Returns the same MetricResult shape: one group per returned series, the
+    // top-level values/summary mirroring the first series. service/metric are
+    // reported as "(raw)" since the curated catalog doesn't apply.
+    async queryRaw(rawQuery, duration, step) {
+        const { start, end, step: resolvedStep } = this.parseTimeRange(duration, step);
+        const data = await this.apiGet(`/api/v1/query_range?query=${encodeURIComponent(rawQuery)}&start=${start}&end=${end}&step=${resolvedStep}`);
+        const seriesList = data?.data?.result || [];
+        const groups = [];
+        for (const series of seriesList) {
+            const seriesValues = [];
+            const rawValues = [];
+            for (const [ts, val] of series.values || []) {
+                const numVal = parseFloat(val);
+                if (!isNaN(numVal)) {
+                    seriesValues.push({ timestamp: new Date(ts * 1000).toISOString(), value: numVal });
+                    rawValues.push(numVal);
+                }
+            }
+            groups.push({
+                key: this.groupKey(series.metric || {}),
+                values: seriesValues,
+                summary: this.computeSummary(rawValues),
+            });
+        }
+        const top = groups[0] || { values: [], summary: this.computeSummary([]) };
+        const result = {
+            source: this.name,
+            service: "(raw)",
+            metric: "(raw)",
+            unit: "",
+            values: top.values,
+            summary: top.summary,
+            resolvedSeries: rawQuery,
+            resolvedLabel: "",
+        };
+        if (groups.length > 1)
+            result.groups = groups;
+        return result;
+    }
     // --- Private helpers ---
-    async buildQuery(service, metric, groupBy) {
+    async buildQuery(service, metric, groupBy, labels) {
         // Resolve the service-filter label first. Candidate probing uses this
         // label to scope existence checks per-service rather than per-source.
         const escaped = service.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
@@ -272,13 +318,39 @@ export class PrometheusConnector {
             const def = this.metrics.find((m) => m.name === metric);
             template = def?.query || `${metric}{ {{selector}} }`;
         }
+        // Extra exact-match label filters (caller-supplied), AND'd into every
+        // {{selector}} occurrence. Label names are constrained to the safe
+        // Prometheus identifier set (the tool layer already validated them, but
+        // we re-constrain here so the connector is safe in isolation); values are
+        // escaped for the surrounding PromQL double-quoted string, same as the
+        // service value above.
+        let extraMatchers = "";
+        if (labels) {
+            const parts = [];
+            for (const [k, v] of Object.entries(labels)) {
+                if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(k))
+                    continue;
+                // Escape backslash first, then quote, then control chars — matches
+                // the Loki escapeLogQLValue sibling so a value with a newline yields
+                // a valid PromQL string literal rather than a 400 parse error.
+                const ev = v
+                    .replace(/\\/g, "\\\\")
+                    .replace(/"/g, '\\"')
+                    .replace(/\n/g, "\\n")
+                    .replace(/\r/g, "\\r")
+                    .replace(/\t/g, "\\t");
+                parts.push(`${k}="${ev}"`);
+            }
+            if (parts.length)
+                extraMatchers = ", " + parts.join(", ");
+        }
         let promql = template;
         if (template.includes("{{selector}}")) {
             // Resolve label here for non-candidate paths that haven't done it yet.
             if (label === "job" && !PROMETHEUS_METRIC_CANDIDATES[metric]) {
                 label = await this.resolveServiceLabel(service);
             }
-            const selector = `${label}="${escaped}"`;
+            const selector = `${label}="${escaped}"${extraMatchers}`;
             promql = promql.replace(/\{\{selector\}\}/g, selector);
         }
         if (groupBy && template.includes("{{groupBy}}")) {

package/dist/connectors/prometheus.test.js

@@ -117,5 +117,86 @@ describe("PrometheusConnector", () => {
             const { promql } = await proto.buildQuery.call(connector, "api", "custom");
             assert.equal(promql, 'my_custom_metric{svc="api"}');
         });
+        it("AND's labels into the {{selector}} (issue #415 #4)", async () => {
+            const connector = new PrometheusConnector();
+            await connector.connect({
+                ...fakeSource,
+                metrics: [{ name: "reqs", query: "http_requests_total{ {{selector}} }", unit: "", description: "" }],
+            });
+            // Stub the network label-resolver so the test is hermetic.
+            connector.resolveServiceLabel =
+                async () => "job";
+            const { promql } = await proto.buildQuery.call(connector, "api", "reqs", undefined, {
+                status: "500",
+                route: "/checkout",
+            });
+            // Insertion order preserved: status then route, after the service matcher.
+            assert.equal(promql, 'http_requests_total{ job="api", status="500", route="/checkout" }');
+        });
+        it("escapes quotes/backslashes in label values (PromQL injection guard)", async () => {
+            const connector = new PrometheusConnector();
+            await connector.connect({
+                ...fakeSource,
+                metrics: [{ name: "reqs", query: "http_requests_total{ {{selector}} }", unit: "", description: "" }],
+            });
+            connector.resolveServiceLabel =
+                async () => "job";
+            const { promql } = await proto.buildQuery.call(connector, "api", "reqs", undefined, {
+                path: 'a"b\\c',
+            });
+            assert.equal(promql, 'http_requests_total{ job="api", path="a\\"b\\\\c" }');
+        });
+        it("escapes newlines/control chars in label values (Loki parity)", async () => {
+            const connector = new PrometheusConnector();
+            await connector.connect({
+                ...fakeSource,
+                metrics: [{ name: "reqs", query: "http_requests_total{ {{selector}} }", unit: "", description: "" }],
+            });
+            connector.resolveServiceLabel =
+                async () => "job";
+            const { promql } = await proto.buildQuery.call(connector, "api", "reqs", undefined, {
+                note: "a\nb\tc",
+            });
+            assert.equal(promql, 'http_requests_total{ job="api", note="a\\nb\\tc" }');
+        });
+        it("ignores labels when the template has no {{selector}}", async () => {
+            const connector = new PrometheusConnector();
+            await connector.connect({
+                ...fakeSource,
+                metrics: [{ name: "explicit", query: 'm{job="{{service}}"}', unit: "", description: "" }],
+            });
+            const { promql } = await proto.buildQuery.call(connector, "svc", "explicit", undefined, {
+                status: "500",
+            });
+            assert.equal(promql, 'm{job="svc"}');
+        });
+    });
+    describe("queryMetrics rawQuery passthrough (R4, issue #415 #3)", () => {
+        const fakeSource = { name: "test", type: "prometheus", url: "http://localhost:9090", enabled: true };
+        it("sends raw PromQL verbatim to query_range, bypassing the catalog", async () => {
+            const connector = new PrometheusConnector();
+            await connector.connect({ ...fakeSource });
+            let captured = "";
+            const orig = globalThis.fetch;
+            globalThis.fetch = (async (url) => {
+                captured = decodeURIComponent((String(url).match(/query=([^&]+)/) || [])[1] || "");
+                return {
+                    ok: true,
+                    status: 200,
+                    json: async () => ({ data: { result: [{ metric: { foo: "bar" }, values: [[1700000000, "42"]] }] } }),
+                };
+            });
+            try {
+                const raw = "topk(5, sum by(route) (rate(http_requests_total[5m])))";
+                const result = await connector.queryMetrics({ service: "", metric: "", duration: "15m", rawQuery: raw });
+                assert.equal(captured, raw);
+                assert.equal(result.resolvedSeries, raw);
+                assert.equal(result.metric, "(raw)");
+                assert.equal(result.values[0].value, 42);
+            }
+            finally {
+                globalThis.fetch = orig;
+            }
+        });
     });
 });

package/dist/context.d.ts

@@ -36,8 +36,17 @@ export interface RequestContext {
     /** Correlates all tool calls within one transport request/session. */
     correlationId: string;
 }
-/** Default all-access anonymous context — preserves current behaviour. */
-export declare function defaultContext(): RequestContext;
+/** Default all-access anonymous context — preserves current behaviour.
+ *  `opts.allowBypassRedaction` lets an operator opt the anonymous identity
+ *  into per-call redaction bypass (OMCP_BYPASS_REDACTION_ANON) — in an
+ *  anonymous deployment there is no named credential to add to
+ *  OMCP_KEY_BYPASS_REDACTION, so this is the only way a single-user
+ *  self-hosted agent can see raw IPs on its own logs without the blunt
+ *  global OMCP_REDACTION=off. Defaults off; all existing call sites that
+ *  omit opts are unchanged. */
+export declare function defaultContext(opts?: {
+    allowBypassRedaction?: boolean;
+}): RequestContext;
 /** Context for an authenticated API-key principal. */
 export declare function principalContext(principalId: string, allowedSources?: string[], opts?: {
     allowBypassRedaction?: boolean;

package/dist/context.js

@@ -1,11 +1,19 @@
 import { randomUUID } from "node:crypto";
 import { DEFAULT_TENANT, normaliseTenant } from "./tenancy/context.js";
-/** Default all-access anonymous context — preserves current behaviour. */
-export function defaultContext() {
+/** Default all-access anonymous context — preserves current behaviour.
+ *  `opts.allowBypassRedaction` lets an operator opt the anonymous identity
+ *  into per-call redaction bypass (OMCP_BYPASS_REDACTION_ANON) — in an
+ *  anonymous deployment there is no named credential to add to
+ *  OMCP_KEY_BYPASS_REDACTION, so this is the only way a single-user
+ *  self-hosted agent can see raw IPs on its own logs without the blunt
+ *  global OMCP_REDACTION=off. Defaults off; all existing call sites that
+ *  omit opts are unchanged. */
+export function defaultContext(opts = {}) {
     return {
         principalId: "anonymous",
         auth: "anonymous",
         tenant: DEFAULT_TENANT,
+        allowBypassRedaction: opts.allowBypassRedaction || undefined,
         correlationId: randomUUID(),
     };
 }

package/dist/context.test.js

@@ -34,6 +34,12 @@ test("defaultContext — no allowedTools (anonymous sees every tool, back-compat
     assert.equal(ctx.allowedTools, undefined);
     assert.equal(allowsTool(ctx.allowedTools, "any_tool"), true);
 });
+test("defaultContext — allowBypassRedaction is off by default, opt-in via opts (R5, issue #415 Gap A)", () => {
+    assert.equal(defaultContext().allowBypassRedaction, undefined);
+    assert.equal(defaultContext({}).allowBypassRedaction, undefined);
+    assert.equal(defaultContext({ allowBypassRedaction: false }).allowBypassRedaction, undefined);
+    assert.equal(defaultContext({ allowBypassRedaction: true }).allowBypassRedaction, true);
+});
 import { sessionContext } from "./context.js";
 test("sessionContext — undefined session → defaultContext shape (anonymous, default tenant)", () => {
     const ctx = sessionContext(undefined);

package/dist/enrich/ip-dataset.d.ts

@@ -0,0 +1,25 @@
+export interface IpEnrichment {
+    country?: string;
+    city?: string;
+    asn?: string;
+    org?: string;
+    hosting?: boolean;
+}
+/** Parse an IPv4 string to an unsigned 32-bit integer, or null if invalid. */
+export declare function ipv4ToInt(ip: string): number | null;
+/** Parse an IPv4 CIDR (or bare IPv4 = /32) to an inclusive integer range. */
+export declare function parseCidr(cidr: string): {
+    start: number;
+    end: number;
+    prefix: number;
+} | null;
+export declare class IpEnrichmentDataset {
+    private ranges;
+    /** Rows that couldn't be parsed (bad CIDR, IPv6, malformed) — surfaced for diagnostics. */
+    readonly skipped: number;
+    readonly size: number;
+    private constructor();
+    static fromCsv(text: string): IpEnrichmentDataset;
+    /** Look up an IPv4 string. Returns the most specific matching row, or null. */
+    lookup(ip: string): IpEnrichment | null;
+}

package/dist/enrich/ip-dataset.js

@@ -0,0 +1,113 @@
+// Offline IPv4 enrichment dataset (issue #415 Gap B).
+//
+// Air-gapped by construction: enrichment comes from a LOCAL dataset the
+// operator supplies (OMCP_IP_ENRICH_FILE), never a per-line phone-home to an
+// external geo/ASN API. The format is a dependency-free CSV so no parser
+// library (and no npm install on the host) is needed:
+//
+//   network,country,city,asn,org,hosting
+//   1.2.3.0/24,US,Ashburn,AS14618,Example Cloud,true
+//   203.0.113.5,DE,Berlin,AS3320,Example ISP,false
+//
+// - `network` is an IPv4 CIDR (or a bare IPv4, treated as /32). IPv6 rows are
+//   skipped (logged by the caller) — IPv4 covers the access-log case the
+//   report was about; IPv6 can follow.
+// - Remaining columns are optional; an empty cell is omitted from the result.
+// - `hosting` is the "is this a datacenter / hosting / proxy range" flag — the
+//   signal that separates real humans from bots/scanners/VPN-exit-nodes. Parsed
+//   truthily from true/1/yes (case-insensitive); anything else is false.
+// - Lines that are blank or start with `#` are ignored. A header row whose
+//   first cell is literally `network` is skipped.
+/** Parse an IPv4 string to an unsigned 32-bit integer, or null if invalid. */
+export function ipv4ToInt(ip) {
+    const parts = ip.trim().split(".");
+    if (parts.length !== 4)
+        return null;
+    let n = 0;
+    for (const p of parts) {
+        if (!/^\d{1,3}$/.test(p))
+            return null;
+        const o = Number(p);
+        if (o > 255)
+            return null;
+        n = n * 256 + o;
+    }
+    return n >>> 0;
+}
+/** Parse an IPv4 CIDR (or bare IPv4 = /32) to an inclusive integer range. */
+export function parseCidr(cidr) {
+    const [addr, prefixStr] = cidr.trim().split("/");
+    const base = ipv4ToInt(addr);
+    if (base === null)
+        return null;
+    const prefix = prefixStr === undefined ? 32 : Number(prefixStr);
+    if (!Number.isInteger(prefix) || prefix < 0 || prefix > 32)
+        return null;
+    // Mask: top `prefix` bits. prefix 0 → whole space; 32 → single host.
+    const hostBits = 32 - prefix;
+    const mask = prefix === 0 ? 0 : (0xffffffff << hostBits) >>> 0;
+    const start = (base & mask) >>> 0;
+    const end = (start + (hostBits === 32 ? 0xffffffff : (1 << hostBits) - 1)) >>> 0;
+    return { start, end, prefix };
+}
+export class IpEnrichmentDataset {
+    ranges = [];
+    /** Rows that couldn't be parsed (bad CIDR, IPv6, malformed) — surfaced for diagnostics. */
+    skipped;
+    size;
+    constructor(ranges, skipped) {
+        // Sort by start asc; lookup picks the most specific (largest prefix)
+        // containing range so nested/overlapping rows resolve deterministically.
+        this.ranges = ranges.sort((a, b) => a.start - b.start || a.end - b.end);
+        this.skipped = skipped;
+        this.size = ranges.length;
+    }
+    static fromCsv(text) {
+        const ranges = [];
+        let skipped = 0;
+        for (const rawLine of text.split(/\r?\n/)) {
+            const line = rawLine.trim();
+            if (!line || line.startsWith("#"))
+                continue;
+            const cells = line.split(",").map((c) => c.trim());
+            if (cells[0].toLowerCase() === "network")
+                continue; // header
+            const r = parseCidr(cells[0]);
+            if (!r) {
+                skipped++;
+                continue;
+            }
+            const data = {};
+            if (cells[1])
+                data.country = cells[1];
+            if (cells[2])
+                data.city = cells[2];
+            if (cells[3])
+                data.asn = cells[3];
+            if (cells[4])
+                data.org = cells[4];
+            if (cells[5] !== undefined && cells[5] !== "") {
+                data.hosting = ["true", "1", "yes"].includes(cells[5].toLowerCase());
+            }
+            ranges.push({ start: r.start, end: r.end, prefix: r.prefix, data });
+        }
+        return new IpEnrichmentDataset(ranges, skipped);
+    }
+    /** Look up an IPv4 string. Returns the most specific matching row, or null. */
+    lookup(ip) {
+        const n = ipv4ToInt(ip);
+        if (n === null)
+            return null;
+        let best = null;
+        // Linear scan is fine for the dataset sizes this is meant for (curated
+        // ranges of interest, not a full global table). Pick the most specific
+        // (largest prefix) range that contains the IP.
+        for (const r of this.ranges) {
+            if (r.start > n)
+                break; // sorted by start asc — all remaining ranges start after n
+            if (n <= r.end && (best === null || r.prefix > best.prefix))
+                best = r;
+        }
+        return best ? { ...best.data } : null;
+    }
+}

package/dist/enrich/ip-dataset.test.d.ts

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

package/dist/enrich/ip-dataset.test.js

@@ -0,0 +1,85 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { ipv4ToInt, parseCidr, IpEnrichmentDataset } from "./ip-dataset.js";
+describe("ipv4ToInt", () => {
+    it("parses valid IPv4", () => {
+        assert.equal(ipv4ToInt("0.0.0.0"), 0);
+        assert.equal(ipv4ToInt("255.255.255.255"), 4294967295);
+        assert.equal(ipv4ToInt("1.2.3.4"), 0x01020304);
+    });
+    it("rejects malformed / out-of-range / non-IPv4", () => {
+        assert.equal(ipv4ToInt("1.2.3"), null);
+        assert.equal(ipv4ToInt("1.2.3.256"), null);
+        assert.equal(ipv4ToInt("1.2.3.4.5"), null);
+        assert.equal(ipv4ToInt("a.b.c.d"), null);
+        assert.equal(ipv4ToInt("::1"), null);
+        assert.equal(ipv4ToInt(""), null);
+    });
+});
+describe("parseCidr", () => {
+    it("parses a /24 to its inclusive range", () => {
+        const r = parseCidr("1.2.3.0/24");
+        assert.deepEqual(r, { start: 0x01020300, end: 0x010203ff, prefix: 24 });
+    });
+    it("treats a bare IP as /32", () => {
+        const r = parseCidr("203.0.113.5");
+        assert.equal(r?.prefix, 32);
+        assert.equal(r?.start, r?.end);
+    });
+    it("normalises a non-aligned base to the network address", () => {
+        // 1.2.3.42/24 → network 1.2.3.0
+        const r = parseCidr("1.2.3.42/24");
+        assert.equal(r?.start, 0x01020300);
+    });
+    it("handles /0 (whole space)", () => {
+        const r = parseCidr("0.0.0.0/0");
+        assert.deepEqual(r, { start: 0, end: 4294967295, prefix: 0 });
+    });
+    it("rejects bad prefixes / addresses", () => {
+        assert.equal(parseCidr("1.2.3.0/33"), null);
+        assert.equal(parseCidr("1.2.3.0/-1"), null);
+        assert.equal(parseCidr("nope/24"), null);
+    });
+});
+describe("IpEnrichmentDataset.fromCsv + lookup", () => {
+    const csv = [
+        "network,country,city,asn,org,hosting", // header skipped
+        "# a comment line",
+        "",
+        "10.0.0.0/8,US,,AS100,Example Cloud,true",
+        "10.1.2.0/24,US,Ashburn,AS100,Example Cloud Edge,true",
+        "203.0.113.5,DE,Berlin,AS3320,Example ISP,false",
+        "2001:db8::/32,XX,,,,", // IPv6 → skipped
+        "garbage-row",
+    ].join("\n");
+    it("parses rows, skips header/comments/blank, counts skipped", () => {
+        const ds = IpEnrichmentDataset.fromCsv(csv);
+        assert.equal(ds.size, 3); // 3 valid IPv4 rows
+        assert.equal(ds.skipped, 2); // IPv6 + garbage
+    });
+    it("returns the most specific (longest-prefix) match", () => {
+        const ds = IpEnrichmentDataset.fromCsv(csv);
+        // 10.1.2.5 is inside both /8 and /24 → the /24 (more specific) wins.
+        const hit = ds.lookup("10.1.2.5");
+        assert.equal(hit?.city, "Ashburn");
+        assert.equal(hit?.org, "Example Cloud Edge");
+        assert.equal(hit?.hosting, true);
+    });
+    it("falls back to the broader range when no specific one matches", () => {
+        const ds = IpEnrichmentDataset.fromCsv(csv);
+        const hit = ds.lookup("10.5.5.5"); // only in /8
+        assert.equal(hit?.asn, "AS100");
+        assert.equal(hit?.city, undefined); // empty cell omitted
+    });
+    it("matches a /32 exactly and parses hosting=false", () => {
+        const ds = IpEnrichmentDataset.fromCsv(csv);
+        const hit = ds.lookup("203.0.113.5");
+        assert.equal(hit?.country, "DE");
+        assert.equal(hit?.hosting, false);
+    });
+    it("returns null for an unmatched or invalid IP", () => {
+        const ds = IpEnrichmentDataset.fromCsv(csv);
+        assert.equal(ds.lookup("8.8.8.8"), null);
+        assert.equal(ds.lookup("not-an-ip"), null);
+    });
+});