@thotischner/observability-mcp 3.3.2 → 3.4.0

package/dist/auth/credentials.d.ts

@@ -16,6 +16,11 @@
  *                  # via the bypass_redaction tool arg. Off by default
  *                  # for every key — pair with the redaction:bypass
  *                  # RBAC permission for the management-plane angle.
+ *   OMCP_KEY_RAW_QUERY="agent,ci"
+ *                  # optional comma-separated list of key NAMES allowed to
+ *                  # run raw_query even when the global OMCP_RAW_QUERY
+ *                  # capability is off. Effective gate = global OR per-key,
+ *                  # so it only widens; off by default for every key.
  *   OMCP_KEY_TENANTS="agent=acme;ci=bigco"
  *                  # optional per-key tenant assignment. Unlisted keys
  *                  # land in the "default" tenant — identical to the
@@ -42,6 +47,11 @@ export interface Credential {
      *  to explicitly set `bypass_redaction: true` in the tool args —
      *  this flag only authorises it; it never auto-disables redaction. */
     bypassRedaction?: boolean;
+    /** True when the operator opted this credential into running `raw_query`
+     *  even with the global OMCP_RAW_QUERY capability off. Configured via
+     *  OMCP_KEY_RAW_QUERY. The effective gate is `global OR per-credential` —
+     *  it only widens access, never narrows a globally-enabled deployment. */
+    allowRawQuery?: boolean;
     /** Tenant this credential belongs to. Omitted → DEFAULT_TENANT. */
     tenant?: string;
     /** Product id this credential is bound to. When set, /mcp tools/list

package/dist/auth/credentials.js

@@ -16,6 +16,11 @@
  *                  # via the bypass_redaction tool arg. Off by default
  *                  # for every key — pair with the redaction:bypass
  *                  # RBAC permission for the management-plane angle.
+ *   OMCP_KEY_RAW_QUERY="agent,ci"
+ *                  # optional comma-separated list of key NAMES allowed to
+ *                  # run raw_query even when the global OMCP_RAW_QUERY
+ *                  # capability is off. Effective gate = global OR per-key,
+ *                  # so it only widens; off by default for every key.
  *   OMCP_KEY_TENANTS="agent=acme;ci=bigco"
  *                  # optional per-key tenant assignment. Unlisted keys
  *                  # land in the "default" tenant — identical to the
@@ -76,6 +81,7 @@ export function loadCredentials(env = process.env) {
         return [];
     const keySources = parseKeySources(env.OMCP_KEY_SOURCES);
     const bypassNames = parseBypassSet(env.OMCP_KEY_BYPASS_REDACTION);
+    const rawQueryNames = parseBypassSet(env.OMCP_KEY_RAW_QUERY);
     const keyTenants = parseKeyTenants(env.OMCP_KEY_TENANTS);
     const keyProducts = parseKeyProducts(env.OMCP_KEY_PRODUCTS);
     const creds = [];
@@ -90,6 +96,7 @@ export function loadCredentials(env = process.env) {
             token,
             allowedSources: keySources.get(name),
             bypassRedaction: bypassNames.has(name) || undefined,
+            allowRawQuery: rawQueryNames.has(name) || undefined,
             tenant: keyTenants.get(name) || undefined,
             productId: keyProducts.get(name) || undefined,
         });

package/dist/auth/credentials.test.js

@@ -11,7 +11,7 @@ describe("single-tenant auth primitive", () => {
     it("parses name:token and bare token", () => {
         const creds = loadCredentials({ OMCP_API_KEYS: "ci:tok_abc, tok_bare " });
         assert.equal(creds.length, 2);
-        assert.deepEqual(creds[0], { name: "ci", token: "tok_abc", allowedSources: undefined, bypassRedaction: undefined, tenant: undefined, productId: undefined });
+        assert.deepEqual(creds[0], { name: "ci", token: "tok_abc", allowedSources: undefined, bypassRedaction: undefined, allowRawQuery: undefined, tenant: undefined, productId: undefined });
         assert.equal(creds[1].name, "key");
         assert.equal(creds[1].token, "tok_bare");
     });
@@ -39,6 +39,21 @@ describe("single-tenant auth primitive", () => {
         for (const c of creds)
             assert.equal(c.bypassRedaction, undefined);
     });
+    it("parses OMCP_KEY_RAW_QUERY → flags only the listed names", () => {
+        const creds = loadCredentials({
+            OMCP_API_KEYS: "agent:tok1,ci:tok2,unprivileged:tok3",
+            OMCP_KEY_RAW_QUERY: "agent, ci",
+        });
+        assert.equal(creds.find((c) => c.name === "agent")?.allowRawQuery, true);
+        assert.equal(creds.find((c) => c.name === "ci")?.allowRawQuery, true);
+        // Unlisted keys MUST be undefined (not false) so it only widens.
+        assert.equal(creds.find((c) => c.name === "unprivileged")?.allowRawQuery, undefined);
+    });
+    it("OMCP_KEY_RAW_QUERY absent → no key may raw_query per-credential (global flag still applies)", () => {
+        const creds = loadCredentials({ OMCP_API_KEYS: "agent:tok1,ci:tok2" });
+        for (const c of creds)
+            assert.equal(c.allowRawQuery, undefined);
+    });
     it("parses OMCP_KEY_TENANTS → assigns tenant to named keys; unlisted stays undefined (default)", () => {
         const creds = loadCredentials({
             OMCP_API_KEYS: "agent:tok1,ci:tok2,nobody:tok3",

package/dist/auth/password-policy.test.js

@@ -1,6 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
+import { readFileSync, existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { validatePassword, passwordPolicyFromEnv, passwordPolicyDisabledFromEnv, DEFAULT_PASSWORD_POLICY, COMMON_PASSWORD_DENYLIST, } from "./password-policy.js";
@@ -89,14 +89,23 @@ test("passwordPolicyDisabledFromEnv recognises truthy values", () => {
     assert.equal(passwordPolicyDisabledFromEnv({ OMCP_PASSWORD_POLICY_DISABLED: "false" }), false);
     assert.equal(passwordPolicyDisabledFromEnv({}), false);
 });
-test("CLI hash-password.mjs stays in sync with the canonical policy", () => {
+// The CLI lives at the repo root (scripts/hash-password.mjs), reached via
+// ../../../scripts from mcp-server/src/auth. Under a partial mount that only
+// mounts mcp-server/ (e.g. the docker-first `docker run -v "$(pwd)/mcp-server:/app"`
+// unit-test command) the repo-root scripts/ dir isn't present. Skip there
+// rather than emit a spurious ENOENT failure — but in CI the full repo is
+// checked out, so a miss is a real move/rename and must still fail loudly.
+const _here = dirname(fileURLToPath(import.meta.url));
+const _cliPath = join(_here, "..", "..", "..", "scripts", "hash-password.mjs");
+const _cliSyncSkip = existsSync(_cliPath) || process.env.CI
+    ? {}
+    : { skip: "scripts/hash-password.mjs not reachable from this mount (run from the repo root or in CI)" };
+test("CLI hash-password.mjs stays in sync with the canonical policy", _cliSyncSkip, () => {
     // The CLI deliberately duplicates the policy to stay dependency-free
     // (same precedent as the scrypt params). This guard fails loudly if the
     // two drift: every canonical denylist entry + the defaults must appear
     // verbatim in the script. (__dirname → mcp-server/src/auth)
-    const here = dirname(fileURLToPath(import.meta.url));
-    const cliPath = join(here, "..", "..", "..", "scripts", "hash-password.mjs");
-    const cli = readFileSync(cliPath, "utf8");
+    const cli = readFileSync(_cliPath, "utf8");
     for (const entry of COMMON_PASSWORD_DENYLIST) {
         assert.ok(cli.includes(`"${entry}"`), `CLI denylist is missing "${entry}"`);
     }

package/dist/context.d.ts

@@ -23,6 +23,12 @@ export interface RequestContext {
      *  tool call ALSO sets `bypass_redaction: true` in its args. Default
      *  false. Configured via OMCP_KEY_BYPASS_REDACTION. */
     allowBypassRedaction?: boolean;
+    /** When true, this credential may run `raw_query` even if the global
+     *  OMCP_RAW_QUERY capability is off. Per-credential gating (configured via
+     *  OMCP_KEY_RAW_QUERY) — the effective gate is `global OR per-credential`,
+     *  so a global enable still works and this only widens, never narrows.
+     *  Default false. */
+    allowRawQuery?: boolean;
     /** Tenant the request operates in. ALWAYS set — defaults to
      *  "default" for anonymous principals + missing-tenant credentials,
      *  preserving the single-namespace behaviour of pre-E7 deployments. */
@@ -50,6 +56,7 @@ export declare function defaultContext(opts?: {
 /** Context for an authenticated API-key principal. */
 export declare function principalContext(principalId: string, allowedSources?: string[], opts?: {
     allowBypassRedaction?: boolean;
+    allowRawQuery?: boolean;
     tenant?: string;
     allowedTools?: string[];
 }): RequestContext;

package/dist/context.js

@@ -24,6 +24,7 @@ export function principalContext(principalId, allowedSources, opts = {}) {
         auth: "apikey",
         allowedSources: allowedSources && allowedSources.length > 0 ? allowedSources : undefined,
         allowBypassRedaction: opts.allowBypassRedaction || undefined,
+        allowRawQuery: opts.allowRawQuery || undefined,
         tenant: normaliseTenant(opts.tenant),
         allowedTools: opts.allowedTools && opts.allowedTools.length > 0 ? opts.allowedTools : undefined,
         correlationId: randomUUID(),

package/dist/context.test.js

@@ -29,6 +29,12 @@ test("principalContext — passes allowedTools through; empty array → undefine
     const ctx3 = principalContext("agent");
     assert.equal(ctx3.allowedTools, undefined);
 });
+test("principalContext — allowRawQuery passes through, off by default (R4 per-credential raw_query)", () => {
+    assert.equal(principalContext("agent").allowRawQuery, undefined);
+    assert.equal(principalContext("agent", undefined, {}).allowRawQuery, undefined);
+    assert.equal(principalContext("agent", undefined, { allowRawQuery: false }).allowRawQuery, undefined);
+    assert.equal(principalContext("agent", undefined, { allowRawQuery: true }).allowRawQuery, true);
+});
 test("defaultContext — no allowedTools (anonymous sees every tool, back-compat)", () => {
     const ctx = defaultContext();
     assert.equal(ctx.allowedTools, undefined);

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

@@ -13,13 +13,25 @@ export declare function parseCidr(cidr: string): {
     end: number;
     prefix: number;
 } | null;
+/** Parse an IPv6 string to a 128-bit BigInt, or null if invalid. Handles
+ *  `::` zero-compression and a trailing IPv4-mapped tail (`::ffff:1.2.3.4`). */
+export declare function ipv6ToBigInt(ip: string): bigint | null;
+/** Parse an IPv6 CIDR (or bare IPv6 = /128) to an inclusive BigInt range. */
+export declare function parseCidr6(cidr: string): {
+    start: bigint;
+    end: bigint;
+    prefix: number;
+} | null;
 export declare class IpEnrichmentDataset {
     private ranges;
-    /** Rows that couldn't be parsed (bad CIDR, IPv6, malformed) — surfaced for diagnostics. */
+    private ranges6;
+    /** Rows that couldn't be parsed (bad CIDR, 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. */
+    /** Look up an IPv4 or IPv6 string. Returns the most specific matching row, or null. */
     lookup(ip: string): IpEnrichment | null;
+    private lookup4;
+    private lookup6;
 }

package/dist/enrich/ip-dataset.js

@@ -9,9 +9,9 @@
 //   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.
+// - `network` is an IPv4 or IPv6 CIDR (or a bare address, treated as /32 or
+//   /128). Both families are supported; IPv4 uses fast 32-bit integer ranges,
+//   IPv6 uses 128-bit BigInt ranges. IPv4-mapped IPv6 (`::ffff:1.2.3.4`) parses.
 // - 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
@@ -50,20 +50,94 @@ export function parseCidr(cidr) {
     const end = (start + (hostBits === 32 ? 0xffffffff : (1 << hostBits) - 1)) >>> 0;
     return { start, end, prefix };
 }
+/** Parse an IPv6 string to a 128-bit BigInt, or null if invalid. Handles
+ *  `::` zero-compression and a trailing IPv4-mapped tail (`::ffff:1.2.3.4`). */
+export function ipv6ToBigInt(ip) {
+    let s = ip.trim();
+    if (s === "" || s.includes(":::"))
+        return null;
+    // A trailing embedded IPv4 (e.g. ::ffff:1.2.3.4) → two hextets.
+    const lastColon = s.lastIndexOf(":");
+    if (s.slice(lastColon + 1).includes(".")) {
+        const v4 = ipv4ToInt(s.slice(lastColon + 1));
+        if (v4 === null)
+            return null;
+        const hi = (v4 >>> 16) & 0xffff;
+        const lo = v4 & 0xffff;
+        s = s.slice(0, lastColon + 1) + hi.toString(16) + ":" + lo.toString(16);
+    }
+    const halves = s.split("::");
+    if (halves.length > 2)
+        return null; // at most one "::"
+    const parseGroups = (part) => {
+        if (part === "")
+            return [];
+        const groups = part.split(":");
+        const out = [];
+        for (const g of groups) {
+            if (!/^[0-9a-fA-F]{1,4}$/.test(g))
+                return null;
+            out.push(parseInt(g, 16));
+        }
+        return out;
+    };
+    let hextets;
+    if (halves.length === 2) {
+        const left = parseGroups(halves[0]);
+        const right = parseGroups(halves[1]);
+        if (left === null || right === null)
+            return null;
+        const fill = 8 - left.length - right.length;
+        if (fill < 1)
+            return null; // "::" must stand for at least one zero group
+        hextets = [...left, ...Array(fill).fill(0), ...right];
+    }
+    else {
+        const all = parseGroups(s);
+        if (all === null)
+            return null;
+        hextets = all;
+    }
+    if (hextets.length !== 8)
+        return null;
+    let n = 0n;
+    for (const h of hextets)
+        n = (n << 16n) | BigInt(h);
+    return n;
+}
+/** Parse an IPv6 CIDR (or bare IPv6 = /128) to an inclusive BigInt range. */
+export function parseCidr6(cidr) {
+    const [addr, prefixStr] = cidr.trim().split("/");
+    const base = ipv6ToBigInt(addr);
+    if (base === null)
+        return null;
+    const prefix = prefixStr === undefined ? 128 : Number(prefixStr);
+    if (!Number.isInteger(prefix) || prefix < 0 || prefix > 128)
+        return null;
+    const hostBits = BigInt(128 - prefix);
+    const full = (1n << 128n) - 1n;
+    const mask = prefix === 0 ? 0n : (full << hostBits) & full;
+    const start = base & mask;
+    const end = start | ((1n << hostBits) - 1n);
+    return { start, end, prefix };
+}
 export class IpEnrichmentDataset {
     ranges = [];
-    /** Rows that couldn't be parsed (bad CIDR, IPv6, malformed) — surfaced for diagnostics. */
+    ranges6 = [];
+    /** Rows that couldn't be parsed (bad CIDR, malformed) — surfaced for diagnostics. */
     skipped;
     size;
-    constructor(ranges, skipped) {
+    constructor(ranges, ranges6, 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.ranges6 = ranges6.sort((a, b) => (a.start < b.start ? -1 : a.start > b.start ? 1 : a.end < b.end ? -1 : a.end > b.end ? 1 : 0));
         this.skipped = skipped;
-        this.size = ranges.length;
+        this.size = ranges.length + ranges6.length;
     }
     static fromCsv(text) {
         const ranges = [];
+        const ranges6 = [];
         let skipped = 0;
         for (const rawLine of text.split(/\r?\n/)) {
             const line = rawLine.trim();
@@ -72,11 +146,6 @@ export class IpEnrichmentDataset {
             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];
@@ -89,12 +158,31 @@ export class IpEnrichmentDataset {
             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 });
+            // Route by family: a ':' in the network cell means IPv6.
+            if (cells[0].includes(":")) {
+                const r6 = parseCidr6(cells[0]);
+                if (!r6) {
+                    skipped++;
+                    continue;
+                }
+                ranges6.push({ start: r6.start, end: r6.end, prefix: r6.prefix, data });
+            }
+            else {
+                const r = parseCidr(cells[0]);
+                if (!r) {
+                    skipped++;
+                    continue;
+                }
+                ranges.push({ start: r.start, end: r.end, prefix: r.prefix, data });
+            }
         }
-        return new IpEnrichmentDataset(ranges, skipped);
+        return new IpEnrichmentDataset(ranges, ranges6, skipped);
     }
-    /** Look up an IPv4 string. Returns the most specific matching row, or null. */
+    /** Look up an IPv4 or IPv6 string. Returns the most specific matching row, or null. */
     lookup(ip) {
+        return ip.includes(":") ? this.lookup6(ip) : this.lookup4(ip);
+    }
+    lookup4(ip) {
         const n = ipv4ToInt(ip);
         if (n === null)
             return null;
@@ -110,4 +198,17 @@ export class IpEnrichmentDataset {
         }
         return best ? { ...best.data } : null;
     }
+    lookup6(ip) {
+        const n = ipv6ToBigInt(ip);
+        if (n === null)
+            return null;
+        let best = null;
+        for (const r of this.ranges6) {
+            if (r.start > n)
+                break; // sorted by start asc
+            if (n <= r.end && (best === null || r.prefix > best.prefix))
+                best = r;
+        }
+        return best ? { ...best.data } : null;
+    }
 }

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

@@ -1,6 +1,6 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
-import { ipv4ToInt, parseCidr, IpEnrichmentDataset } from "./ip-dataset.js";
+import { ipv4ToInt, parseCidr, ipv6ToBigInt, parseCidr6, IpEnrichmentDataset } from "./ip-dataset.js";
 describe("ipv4ToInt", () => {
     it("parses valid IPv4", () => {
         assert.equal(ipv4ToInt("0.0.0.0"), 0);
@@ -49,13 +49,13 @@ describe("IpEnrichmentDataset.fromCsv + lookup", () => {
         "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
+        "2001:db8::/32,XX,,,,", // IPv6 — now parsed, not skipped
         "garbage-row",
     ].join("\n");
-    it("parses rows, skips header/comments/blank, counts skipped", () => {
+    it("parses rows (v4 + v6), 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
+        assert.equal(ds.size, 4); // 3 IPv4 + 1 IPv6 row
+        assert.equal(ds.skipped, 1); // only the garbage row
     });
     it("returns the most specific (longest-prefix) match", () => {
         const ds = IpEnrichmentDataset.fromCsv(csv);
@@ -83,3 +83,79 @@ describe("IpEnrichmentDataset.fromCsv + lookup", () => {
         assert.equal(ds.lookup("not-an-ip"), null);
     });
 });
+describe("ipv6ToBigInt", () => {
+    it("parses a full address", () => {
+        assert.equal(ipv6ToBigInt("2001:0db8:0000:0000:0000:0000:0000:0001"), 0x20010db8000000000000000000000001n);
+    });
+    it("expands :: zero-compression", () => {
+        assert.equal(ipv6ToBigInt("2001:db8::1"), 0x20010db8000000000000000000000001n);
+        assert.equal(ipv6ToBigInt("::1"), 1n);
+        assert.equal(ipv6ToBigInt("::"), 0n);
+        assert.equal(ipv6ToBigInt("ff02::"), 0xff020000000000000000000000000000n);
+    });
+    it("parses an IPv4-mapped tail", () => {
+        // ::ffff:1.2.3.4 → the v4 lives in the low 32 bits with ffff above it
+        assert.equal(ipv6ToBigInt("::ffff:1.2.3.4"), 0x00000000000000000000ffff01020304n);
+    });
+    it("rejects malformed input", () => {
+        assert.equal(ipv6ToBigInt("2001:db8::1::2"), null); // two ::
+        assert.equal(ipv6ToBigInt("gggg::1"), null);
+        assert.equal(ipv6ToBigInt("1.2.3.4"), null); // v4 is not v6
+        assert.equal(ipv6ToBigInt("12345::"), null); // hextet too long
+        assert.equal(ipv6ToBigInt(""), null);
+    });
+});
+describe("parseCidr6", () => {
+    it("parses a /32 to its inclusive range", () => {
+        const r = parseCidr6("2001:db8::/32");
+        assert.equal(r?.prefix, 32);
+        assert.equal(r?.start, 0x20010db8000000000000000000000000n);
+        assert.equal(r?.end, 0x20010db8ffffffffffffffffffffffffn);
+    });
+    it("treats a bare address as /128", () => {
+        const r = parseCidr6("2001:db8::1");
+        assert.equal(r?.prefix, 128);
+        assert.equal(r?.start, r?.end);
+    });
+    it("handles /0 (whole space)", () => {
+        const r = parseCidr6("::/0");
+        assert.equal(r?.start, 0n);
+        assert.equal(r?.end, (1n << 128n) - 1n);
+    });
+    it("rejects bad prefixes / addresses", () => {
+        assert.equal(parseCidr6("2001:db8::/129"), null);
+        assert.equal(parseCidr6("nope::/32"), null);
+    });
+});
+describe("IpEnrichmentDataset IPv6 lookup", () => {
+    const csv = [
+        "network,country,city,asn,org,hosting",
+        "2001:db8::/32,US,,AS100,Example Cloud,true",
+        "2001:db8:1::/48,US,Ashburn,AS100,Example Cloud Edge,true",
+        "2606:4700::/32,US,,AS13335,Example CDN,true",
+        "10.0.0.0/8,DE,Berlin,AS3320,Example ISP,false", // v4 row alongside
+    ].join("\n");
+    it("returns the most specific v6 match", () => {
+        const ds = IpEnrichmentDataset.fromCsv(csv);
+        const hit = ds.lookup("2001:db8:1::abcd"); // inside both /32 and /48
+        assert.equal(hit?.city, "Ashburn");
+        assert.equal(hit?.org, "Example Cloud Edge");
+    });
+    it("falls back to the broader v6 range", () => {
+        const ds = IpEnrichmentDataset.fromCsv(csv);
+        const hit = ds.lookup("2001:db8:9::1"); // only in /32
+        assert.equal(hit?.asn, "AS100");
+        assert.equal(hit?.city, undefined);
+    });
+    it("keeps v4 and v6 lookups independent", () => {
+        const ds = IpEnrichmentDataset.fromCsv(csv);
+        assert.equal(ds.lookup("10.1.2.3")?.country, "DE"); // v4 path
+        assert.equal(ds.lookup("2606:4700::1")?.org, "Example CDN"); // v6 path
+        assert.equal(ds.lookup("2607:f8b0::1"), null); // unmatched v6
+    });
+    it("normalises an IPv4-mapped query against a v4 row? no — :: form hits v6 table only", () => {
+        const ds = IpEnrichmentDataset.fromCsv(csv);
+        // A ':'-bearing query goes to the v6 table; it won't match the 10.0.0.0/8 v4 row.
+        assert.equal(ds.lookup("::ffff:10.1.2.3"), null);
+    });
+});

package/dist/index.js

@@ -555,7 +555,7 @@ async function main() {
                 .describe("Optional escape hatch: a verbatim PromQL expression, run as-is over the range — for ad-hoc queries the curated `metric` catalog can't express (any series, any function, broken down by any label). When set, `metric`/`service`/`groupBy`/`labels` are ignored. DISABLED by default; the operator must enable the raw-query capability (OMCP_RAW_QUERY=on) or the call is refused. Still tenant-scoped and source-allow-listed."),
         }, { title: "Query Metrics", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async (args) => {
             await enforceEntitledAccess(ctx, { tool: "query_metrics", source: args?.source, service: args?.service });
-            const result = await withToolMetrics("query_metrics", () => queryMetricsHandler(registry, args, ctx, { allowRawQuery: RAW_QUERY_ENABLED }));
+            const result = await withToolMetrics("query_metrics", () => queryMetricsHandler(registry, args, ctx, { allowRawQuery: RAW_QUERY_ENABLED || ctx.allowRawQuery === true }));
             return chargeTokenBudget(result, ctx, "query_metrics");
         });
         registerTool("query_logs", [
@@ -623,7 +623,7 @@ async function main() {
                 .describe("Optional escape hatch: a verbatim LogQL log query, run as-is — for selectors/pipelines the curated params can't express. When set, `service`/`labels`/`level`/`query` are ignored and it is mutually exclusive with `aggregate` (express aggregation in the LogQL itself). DISABLED by default; the operator must enable the raw-query capability (OMCP_RAW_QUERY=on) or the call is refused. Redaction still applies to the returned log lines."),
         }, { title: "Query Logs", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, async (args) => {
             await enforceEntitledAccess(ctx, { tool: "query_logs", source: args?.source, service: args?.service });
-            const result = await withToolMetrics("query_logs", () => queryLogsHandler(registry, args, ctx, { allowRawQuery: RAW_QUERY_ENABLED }));
+            const result = await withToolMetrics("query_logs", () => queryLogsHandler(registry, args, ctx, { allowRawQuery: RAW_QUERY_ENABLED || ctx.allowRawQuery === true }));
             // Redact PII / secrets from the log payload before it crosses the
             // MCP boundary into the agent's context. Per-call bypass kicks in
             // only when BOTH (a) the credential is OMCP_KEY_BYPASS_REDACTION
@@ -3367,6 +3367,7 @@ async function main() {
         }
         return principalContext(cred.name, cred.allowedSources, {
             allowBypassRedaction: cred.bypassRedaction,
+            allowRawQuery: cred.allowRawQuery,
             tenant: cred.tenant,
             allowedTools,
         });
@@ -3607,6 +3608,7 @@ async function main() {
         return {
             ctx: principalContext(cred.name, cred.allowedSources, {
                 allowBypassRedaction: cred.bypassRedaction,
+                allowRawQuery: cred.allowRawQuery,
                 tenant: cred.tenant,
                 allowedTools,
             }),

package/dist/tools/enrich-ips.js

@@ -1,4 +1,4 @@
-import { ipv4ToInt } from "../enrich/ip-dataset.js";
+import { ipv4ToInt, ipv6ToBigInt } from "../enrich/ip-dataset.js";
 import { defaultContext } from "../context.js";
 import { errorResponse } from "./validation.js";
 // enrich_ips (issue #415 Gap B): resolve a batch of IPs to geo / ASN / org /
@@ -7,9 +7,13 @@ import { errorResponse } from "./validation.js";
 // when no dataset is configured.
 export const enrichIpsDefinition = {
     name: "enrich_ips",
-    description: "Resolve a batch of IPv4 addresses to geo (country/city), ASN/org, and a hosting/proxy flag from a local offline dataset. Use this to answer 'where are these visitors from / which are bots or datacenter IPs' without an out-of-band geo API call. Requires the operator to have configured an offline dataset (OMCP_IP_ENRICH_FILE); returns a clear notice otherwise.",
+    description: "Resolve a batch of IPv4 or IPv6 addresses to geo (country/city), ASN/org, and a hosting/proxy flag from a local offline dataset. Use this to answer 'where are these visitors from / which are bots or datacenter IPs' without an out-of-band geo API call. Requires the operator to have configured an offline dataset (OMCP_IP_ENRICH_FILE); returns a clear notice otherwise.",
 };
 const MAX_IPS = 1000;
+/** A string is a valid IP if it parses as either IPv4 or IPv6. */
+function isValidIp(ip) {
+    return ipv4ToInt(ip) !== null || ipv6ToBigInt(ip) !== null;
+}
 export 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
@@ -22,7 +26,7 @@ _ctx = defaultContext()) {
     }
     const ips = args.ips;
     if (!Array.isArray(ips) || ips.length === 0) {
-        return errorResponse("`ips` must be a non-empty array of IPv4 address strings.");
+        return errorResponse("`ips` must be a non-empty array of IPv4 or IPv6 address strings.");
     }
     if (ips.length > MAX_IPS) {
         return errorResponse(`Too many IPs (${ips.length}); max ${MAX_IPS} per call.`);
@@ -31,7 +35,7 @@ _ctx = defaultContext()) {
     let invalid = 0;
     let matched = 0;
     for (const ip of ips) {
-        if (typeof ip !== "string" || ipv4ToInt(ip) === null) {
+        if (typeof ip !== "string" || !isValidIp(ip)) {
             invalid++;
             results.push({ ip: String(ip), found: false });
             continue;

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

@@ -35,4 +35,15 @@ 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)", () => {
+        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 v6hit = out.results.find((r) => r.ip === "2001:db8::1");
+        assert.equal(v6hit.found, true);
+        assert.equal(v6hit.org, "Example Cloud");
+        const v6miss = out.results.find((r) => r.ip === "2606:4700::1");
+        assert.equal(v6miss.found, false);
+        // A valid-but-unmatched IPv6 is "unmatched", NOT "invalid".
+        assert.deepEqual(out.summary, { total: 3, matched: 2, unmatched: 1, invalid: 0 });
+    });
 });

package/dist/tools/generate-postmortem.js

@@ -60,16 +60,35 @@ export async function generatePostmortemHandler(registry, args, ctx = defaultCon
         traces,
         logHighlights,
     });
+    // Which primitives actually carried data. A post-mortem synthesised from
+    // ZERO signal still renders a full, authoritative-looking document — an
+    // on-call could paste it into a ticket as if it were a real finding. Make
+    // the coverage explicit so an empty report is self-labelling (the
+    // "absent ≠ zero" class, cf. #453/#462).
+    const coverage = {
+        anomalies: anomalies.length > 0,
+        traces: traces.length > 0,
+        topology: blastRadius.nodes.length > 0,
+        logs: logHighlights.length > 0,
+    };
+    const anySignal = Object.values(coverage).some(Boolean);
+    const reportWithCoverage = { ...report, coverage, builtFromSignal: anySignal };
     if ((args.format || "markdown").toLowerCase() === "json") {
         return {
-            content: [{ type: "text", text: JSON.stringify(report) }],
+            content: [{ type: "text", text: JSON.stringify(reportWithCoverage) }],
             isError: false,
         };
     }
-    // Default: return the markdown body. The structured sections live
-    // in JSON if the caller asked for them.
+    // Default: return the markdown body. When there was no signal at all, lead
+    // with a banner so the document isn't mistaken for a real finding.
+    const banner = anySignal
+        ? ""
+        : "> ⚠️ **No signal in this window.** This report was built from zero anomalies, traces, " +
+            "topology, and log highlights. Either the window was genuinely clean, or the relevant " +
+            "backends aren't configured/writing (anomaly-history sink, traces connector, topology " +
+            "connector). Verify coverage before relying on this.\n\n";
     return {
-        content: [{ type: "text", text: report.markdown }],
+        content: [{ type: "text", text: banner + report.markdown }],
         isError: false,
     };
 }

package/dist/tools/generate-postmortem.test.d.ts

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

package/dist/tools/generate-postmortem.test.js

@@ -0,0 +1,22 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { ConnectorRegistry } from "../connectors/registry.js";
+import { generatePostmortemHandler } from "./generate-postmortem.js";
+// R5 — a post-mortem built from ZERO signal (no anomaly/traces/topology/log
+// backend) must label itself, not render as an authoritative finding.
+describe("generatePostmortemHandler — no-signal honesty (R5)", () => {
+    it("markdown leads with a 'no signal' banner when nothing was found", async () => {
+        const reg = new ConnectorRegistry(); // no backends → every primitive empty
+        const out = await generatePostmortemHandler(reg, { service: "ghost-service", duration: "1h" });
+        const md = out.content[0].text;
+        assert.match(md, /No signal in this window/i);
+        assert.match(md, /backends aren't configured/i);
+    });
+    it("json form carries explicit coverage flags + builtFromSignal=false", async () => {
+        const reg = new ConnectorRegistry();
+        const out = await generatePostmortemHandler(reg, { service: "ghost-service", duration: "1h", format: "json" });
+        const report = JSON.parse(out.content[0].text);
+        assert.equal(report.builtFromSignal, false);
+        assert.deepEqual(report.coverage, { anomalies: false, traces: false, topology: false, logs: false });
+    });
+});

package/dist/tools/handlers.test.js

@@ -152,6 +152,36 @@ describe("listServicesHandler", () => {
         const data = JSON.parse(result.content[0].text);
         assert.equal(data.total, 0);
     });
+    it("no backends configured → note distinguishes 'none configured' from 'zero services' (R5)", async () => {
+        const data = JSON.parse((await listServicesHandler(new ConnectorRegistry(), {})).content[0].text);
+        assert.equal(data.total, 0);
+        assert.match(data.note, /No observability backends are configured/i);
+    });
+    it("all sources fail discovery → note + not a silent 'zero services' (R5)", async () => {
+        const reg = createRegistryWithMocks([
+            createMockConnector({ name: "prom1", type: "prometheus", signalType: "metrics", listServices: async () => { throw new Error("down"); } }),
+        ]);
+        const data = JSON.parse((await listServicesHandler(reg, {})).content[0].text);
+        assert.equal(data.total, 0);
+        assert.match(data.note, /failed on all 1 configured source/i);
+    });
+    it("partial source failure → result is flagged partial with the failed source (R5)", async () => {
+        const reg = createRegistryWithMocks([
+            createMockConnector({ name: "prom1", type: "prometheus", signalType: "metrics", listServices: async () => { throw new Error("down"); } }),
+            createMockConnector({ name: "loki1", type: "loki", signalType: "logs", listServices: async () => [{ name: "order-service", source: "loki1", signalType: "logs" }] }),
+        ]);
+        const data = JSON.parse((await listServicesHandler(reg, {})).content[0].text);
+        assert.equal(data.total, 1);
+        assert.equal(data.partial, true);
+        assert.deepEqual(data.failedSources, ["prom1"]);
+    });
+});
+describe("listSourcesHandler — no-data honesty (R5)", () => {
+    it("no backends configured → explanatory note, not a bare empty list", async () => {
+        const data = JSON.parse((await listSourcesHandler(new ConnectorRegistry())).content[0].text);
+        assert.deepEqual(data.sources, []);
+        assert.match(data.note, /No observability backends are configured/i);
+    });
 });
 describe("detectAnomaliesHandler — fleet coverage (issue #453B)", () => {
     it("fleet scan includes log-only services and reports per-service coverage", async () => {

package/dist/tools/list-services.js

@@ -16,6 +16,10 @@ export async function listServicesHandler(registry, args, ctx = defaultContext()
     // Tenant-scoped: only consult sources the caller can see.
     const connectors = registry.getByTenant(ctx.tenant);
     const allServices = [];
+    // Track per-connector discovery failures so an empty result isn't silently
+    // partial — a down source must not make half the fleet vanish without a
+    // signal (the "absent ≠ zero" class, cf. #453).
+    const failedSources = [];
     for (const connector of connectors) {
         try {
             const services = await connector.listServices();
@@ -23,6 +27,7 @@ export async function listServicesHandler(registry, args, ctx = defaultContext()
         }
         catch (err) {
             console.error(`Failed to list services from ${connector.name}:`, err);
+            failedSources.push(connector.name);
         }
     }
     // Deduplicate by name, merge signal types. Carry per-service `labels`
@@ -54,11 +59,33 @@ export async function listServicesHandler(registry, args, ctx = defaultContext()
         const f = args.filter.toLowerCase();
         services = services.filter((s) => s.name.toLowerCase().includes(f));
     }
+    // An empty result is ambiguous — say *why* so an agent doesn't read it as
+    // "this environment has no services". Distinguish: no backends configured,
+    // discovery failed on some/all sources, or genuinely none discovered.
+    let note;
+    if (connectors.length === 0) {
+        note = "No observability backends are configured for this tenant — add one via the Sources tab or config/sources.yaml. This is not 'zero services'.";
+    }
+    else if (failedSources.length === connectors.length) {
+        note = `Service discovery failed on all ${connectors.length} configured source(s) (${failedSources.join(", ")}) — the empty result is an error, not 'zero services'. Check source health via list_sources.`;
+    }
+    else if (services.length === 0 && !args.filter) {
+        note = "No services discovered — the configured backend(s) returned none in this tenant.";
+    }
     return {
         content: [
             {
                 type: "text",
-                text: JSON.stringify({ services, total: services.length }, null, 2),
+                text: JSON.stringify({
+                    services,
+                    total: services.length,
+                    // Only present when some (but not all) sources failed — a partial
+                    // result the caller should know is incomplete.
+                    ...(failedSources.length > 0 && failedSources.length < connectors.length
+                        ? { partial: true, failedSources }
+                        : {}),
+                    ...(note ? { note } : {}),
+                }, null, 2),
             },
         ],
     };

package/dist/tools/list-sources.js

@@ -21,11 +21,17 @@ export async function listSourcesHandler(registry, ctx = defaultContext()) {
         status: healthResults[c.name]?.status || "unknown",
         latencyMs: healthResults[c.name]?.latencyMs,
     }));
+    // An empty list is ambiguous on its own — name the cause so an agent
+    // doesn't read it as a transient/permission blip (the "absent ≠ zero"
+    // class). When nothing is configured, say so explicitly.
+    const note = sources.length === 0
+        ? "No observability backends are configured for this tenant. Add one via the Sources tab or config/sources.yaml — this is 'none configured', not a query error."
+        : undefined;
     return {
         content: [
             {
                 type: "text",
-                text: JSON.stringify({ sources }, null, 2),
+                text: JSON.stringify({ sources, ...(note ? { note } : {}) }, null, 2),
             },
         ],
     };

package/dist/tools/query-logs.js

@@ -59,7 +59,7 @@ export async function queryLogsHandler(registry, args, ctx = defaultContext(), o
         return errorResponse(rawErr);
     const isRaw = !!args.raw_query;
     if (isRaw && !opts.allowRawQuery) {
-        return errorResponse("raw_query is disabled. The operator must enable the raw-query capability (OMCP_RAW_QUERY=on) to run verbatim LogQL — it bypasses the curated log surface, so it is off by default.");
+        return errorResponse("raw_query is disabled. The operator must enable the raw-query capability (OMCP_RAW_QUERY=on globally, or per-credential via OMCP_KEY_RAW_QUERY) to run verbatim LogQL — it bypasses the curated log surface, so it is off by default.");
     }
     if (isRaw && args.aggregate) {
         return errorResponse("raw_query and aggregate are mutually exclusive — a raw LogQL query expresses its own aggregation.");

package/dist/tools/query-metrics.js

@@ -50,7 +50,7 @@ export async function queryMetricsHandler(registry, args, ctx = defaultContext()
         return errorResponse(rawErr);
     const isRaw = !!args.raw_query;
     if (isRaw && !opts.allowRawQuery) {
-        return errorResponse("raw_query is disabled. The operator must enable the raw-query capability (OMCP_RAW_QUERY=on) to run verbatim PromQL — it bypasses the curated metric surface, so it is off by default.");
+        return errorResponse("raw_query is disabled. The operator must enable the raw-query capability (OMCP_RAW_QUERY=on globally, or per-credential via OMCP_KEY_RAW_QUERY) to run verbatim PromQL — it bypasses the curated metric surface, so it is off by default.");
     }
     if (!isRaw) {
         if (!args.service)

package/dist/tools/topology.js

@@ -171,6 +171,25 @@ export const getBlastRadiusDefinition = {
 };
 export async function getBlastRadiusHandler(registry, args, ctx = defaultContext()) {
     const agg = await aggregateTopology(registry, ctx.tenant);
+    // No topology-capable connector → the resource can't be found because there
+    // IS no graph, not because the name is wrong. Say so explicitly instead of a
+    // generic "not found" that misattributes the cause (the "absent ≠ zero"
+    // class, consistent with get_topology's empty-graph note).
+    if (agg.sources.length === 0) {
+        return {
+            isError: true,
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        resource: args.resource,
+                        hosts: [],
+                        note: "No topology-capable connector is configured, so there is no blast radius to compute. " +
+                            "Add a topology source (the built-in `kubernetes` connector, or aws/gcp/istio/linkerd/consul) " +
+                            "— a metrics/logs-only deployment has no topology graph. This is not 'resource not found'.",
+                    }, null, 2),
+                }],
+        };
+    }
     const found = resolveResource(args.resource, agg.resources);
     if ("error" in found) {
         return {

package/dist/tools/topology.test.js

@@ -212,6 +212,16 @@ describe("get_blast_radius tool", () => {
         const out = parseTool(result);
         assert.match(out.error, /No resource found/);
     });
+    it("no topology connector → explicit note, not a misleading 'resource not found' (R5)", async () => {
+        // An empty registry has no topology source. The cause is "no graph", not
+        // "wrong name" — the response must say so rather than blame the resource.
+        const reg = new ConnectorRegistry(new PluginLoader());
+        const result = await getBlastRadiusHandler(reg, { resource: "anything" });
+        assert.equal(result.isError, true);
+        const out = parseTool(result);
+        assert.match(out.note, /No topology-capable connector is configured/i);
+        assert.ok(!out.error || !/No resource found/.test(out.error), "must not misattribute to a not-found name");
+    });
     it("uses ownership root, not direct owner, when grouping co-tenants", async () => {
         // api-aaa is OWNED_BY a ReplicaSet which is OWNED_BY a Deployment.
         // The blast-radius should bucket api-aaa under the Deployment, not the RS.

package/package.json

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