@thotischner/observability-mcp 3.1.1 → 3.2.1

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

@@ -127,6 +127,33 @@ test("MCP 2025-11-25: query_logs advertises labels + aggregate params (issue #41
     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 });
@@ -218,3 +245,133 @@ test("MCP 2025-11-25: server advertises protocolVersion equal to or newer than 2
     // recognised date-style version string.
     assert.match(r.protocolVersion, /^\d{4}-\d{2}-\d{2}$/, "protocolVersion must be a YYYY-MM-DD date");
 });
+// ---------------------------------------------------------------------------
+// Behavioural tools/call E2E (post-#415 hardening).
+//
+// These run over the REAL /mcp Streamable-HTTP transport against the booted
+// demo stack (integration.yml sets OMCP_CONFORMANCE_URL). They close the gap
+// that let #415 ship: a param can be ADVERTISED in tools/list yet silently
+// stripped by the SDK before it reaches the handler — an advertise-only
+// assertion passes anyway. Here we call the tool and assert the param TAKES
+// EFFECT over the wire. The demo mcp-server runs with OMCP_RAW_QUERY unset and
+// OMCP_IP_ENRICH_FILE unset, so the gate/not-configured assertions are
+// deterministic regardless of backend data.
+// ---------------------------------------------------------------------------
+async function callTool(session, name, args, id = 50) {
+    const { response } = await jsonRpc("tools/call", { name, arguments: args }, { id, session });
+    if (response.error)
+        return { error: response.error };
+    const r = response.result;
+    const text = r?.content?.[0]?.text;
+    let parsed;
+    try {
+        parsed = text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        parsed = undefined;
+    }
+    return { isError: r?.isError, parsed, text };
+}
+async function discoverService(session) {
+    const r = await callTool(session, "list_services", {}, 40);
+    const list = Array.isArray(r.parsed) ? r.parsed : r.parsed?.services;
+    const name = Array.isArray(list) && list[0] && (list[0].name || list[0].service);
+    return name || "payment-service"; // demo k3s service as fallback
+}
+test("E2E tools/call: query_logs raw_query is refused over the wire when capability off (#415 #3)", opts, async () => {
+    const session = await newSession();
+    const r = await callTool(session, "query_logs", { raw_query: '{job="x"}' });
+    // Proves raw_query SURVIVES transport (not stripped) AND the gate fires E2E.
+    const msg = JSON.stringify(r.parsed ?? r.text ?? "");
+    assert.match(msg, /raw_query is disabled/i, `expected gate refusal, got ${msg}`);
+});
+test("E2E tools/call: query_metrics raw_query is refused over the wire when capability off (#415 #3)", opts, async () => {
+    const session = await newSession();
+    const r = await callTool(session, "query_metrics", { raw_query: "up" });
+    const msg = JSON.stringify(r.parsed ?? r.text ?? "");
+    assert.match(msg, /raw_query is disabled/i, `expected gate refusal, got ${msg}`);
+});
+test("E2E tools/call: enrich_ips dispatches and reports not-configured over the wire (Gap B)", opts, async () => {
+    const session = await newSession();
+    const r = await callTool(session, "enrich_ips", { ips: ["203.0.113.5"] });
+    const msg = JSON.stringify(r.parsed ?? r.text ?? "");
+    // Proves the ips param survives transport and the tool dispatches; demo has
+    // no OMCP_IP_ENRICH_FILE so the deterministic "not configured" path fires.
+    assert.match(msg, /not configured/i, `expected not-configured notice, got ${msg}`);
+});
+test("E2E tools/call: query_logs aggregate takes effect over the wire — grouped result, not raw rows (#415 #2)", opts, async () => {
+    const session = await newSession();
+    const service = await discoverService(session);
+    const r = await callTool(session, "query_logs", {
+        service,
+        aggregate: { op: "count_over_time", step: "15m" },
+        duration: "1h",
+    });
+    // The aggregate result shape (op/mode/series) is structurally distinct from
+    // the raw-rows shape (entries/summary). Asserting the aggregate shape proves
+    // the `aggregate` param survived the SDK input parsing and reached the
+    // connector — even if the series is empty on a sparse demo window.
+    const p = Array.isArray(r.parsed) ? r.parsed[0] : r.parsed;
+    assert.ok(p, `expected an aggregate result, got ${JSON.stringify(r)}`);
+    assert.equal(p.op, "count_over_time", "result must carry the aggregate op");
+    assert.ok("mode" in p && Array.isArray(p.series), "result must be the aggregate shape (mode + series)");
+    assert.ok(!("entries" in p), "aggregate path must NOT return the raw-rows shape");
+});
+test("E2E tools/call: query_metrics labels param is accepted over the wire (#415 #4)", opts, async () => {
+    const session = await newSession();
+    const service = await discoverService(session);
+    const r = await callTool(session, "query_metrics", {
+        service,
+        metric: "cpu",
+        labels: { job: service },
+        duration: "5m",
+    });
+    // Must not be a transport/dispatch error; the labels param must be accepted
+    // (a structured "no data" result is fine — proves it reached the handler).
+    assert.ok(!r.error, `unexpected JSON-RPC error: ${JSON.stringify(r.error)}`);
+    assert.ok(r.parsed !== undefined || r.text !== undefined, "expected a CallToolResult payload");
+});
+test("E2E tools/call: get_anomaly_history dispatches without a PromQL 400 crash (H1 over the wire)", opts, async () => {
+    const session = await newSession();
+    const service = await discoverService(session);
+    const r = await callTool(session, "get_anomaly_history", { service, duration: "1h", method: "mad" });
+    // After the rawQuery fix the emitted PromQL is valid; empty data is a clean
+    // non-error result. The bug produced an invalid-query path that still
+    // returned non-error empty, so we assert the dispatch shape is well-formed.
+    assert.ok(!r.error, `unexpected JSON-RPC error: ${JSON.stringify(r.error)}`);
+    assert.ok(r.parsed !== undefined || r.text !== undefined, "expected a CallToolResult payload");
+});
+test("E2E tools/call: every registered tool dispatches over MCP and returns a CallToolResult", opts, async () => {
+    const session = await newSession();
+    const service = await discoverService(session);
+    // Minimal valid args per tool; tools with required args get discovered/dummy
+    // values. A clean isError result (e.g. query_traces 'no trace backends') is
+    // acceptable — we only require a shape-conformant dispatch, never a -32xxx.
+    const calls = {
+        list_sources: {},
+        list_services: {},
+        query_metrics: { service, metric: "cpu" },
+        query_logs: { service },
+        get_anomaly_history: { service },
+        generate_postmortem: { service },
+        query_traces: { service },
+        get_service_health: { service },
+        detect_anomalies: {},
+        get_topology: {},
+        get_blast_radius: { resource: service },
+        enrich_ips: { ips: ["203.0.113.5"] },
+    };
+    const { response: list } = await jsonRpc("tools/list", {}, { id: 41, session });
+    const names = (list.result?.tools ?? []).map((t) => t.name);
+    assert.ok(names.length >= 12, `expected >=12 tools, got ${names.length}`);
+    let id = 60;
+    for (const name of names) {
+        const args = calls[name] ?? {};
+        const { response } = await jsonRpc("tools/call", { name, arguments: args }, { id: id++, session });
+        if (response.error) {
+            assert.fail(`tool ${name} returned a JSON-RPC dispatch error: ${JSON.stringify(response.error)}`);
+        }
+        const r = response.result;
+        assert.ok(Array.isArray(r.content), `tool ${name} must return content[]`);
+    }
+});

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 {};