@thotischner/observability-mcp 3.3.2 → 3.5.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/postmortem/synthesizer.d.ts

@@ -45,6 +45,13 @@ export interface PostmortemInput {
     traces: TraceSummary[];
     /** Optional log-error summary lines, e.g. ["payment-service: 412 5xx in window"]. */
     logHighlights?: string[];
+    /** Optional custom report template (issue: v3.3 candidate). When set, the
+     *  markdown body is rendered by interpolating `{{placeholder}}` tokens
+     *  instead of the built-in layout. Unset → the default report (unchanged).
+     *  Available tokens: service, window, from, to, tenant, synopsis, timeline,
+     *  blastRadius, signals, traces, logHighlights, followUps. An unknown token
+     *  is left verbatim so a typo is visible rather than silently dropped. */
+    template?: string;
 }
 export interface PostmortemReport {
     service: string;
@@ -81,3 +88,20 @@ export interface PostmortemReport {
 /** Synthesise one report from already-fetched primitives. Pure
  *  compute — no I/O. */
 export declare function synthesizePostmortem(input: PostmortemInput): PostmortemReport;
+type RenderCtx = {
+    input: PostmortemInput;
+    timeline: PostmortemReport["sections"]["timeline"];
+    contributingSignals: PostmortemReport["sections"]["contributingSignals"];
+    peakNode: BlastRadiusNode | undefined;
+    peakScore: number;
+    errorTraces: number;
+    blastSize: number;
+    followUps: string[];
+    synopsis: string;
+};
+/** Build the `{{token}}` → markdown-block map for a custom template. */
+export declare function buildTemplateVars(ctx: RenderCtx): Record<string, string>;
+/** Interpolate `{{token}}` placeholders. An unknown token is left verbatim so
+ *  a typo is visible in the output rather than silently producing a blank. */
+export declare function renderTemplate(template: string, vars: Record<string, string>): string;
+export {};

package/dist/postmortem/synthesizer.js

@@ -22,7 +22,7 @@ export function synthesizePostmortem(input) {
     const blastSize = input.blastRadius.nodes.length;
     const followUps = inferFollowUps(input, { peakScore, errorTraces, blastSize });
     const synopsis = synopsisFor(input, peakScore, errorTraces, blastSize);
-    const markdown = renderMarkdown({
+    const renderCtx = {
         input,
         timeline,
         contributingSignals,
@@ -32,7 +32,12 @@ export function synthesizePostmortem(input) {
         blastSize,
         followUps,
         synopsis,
-    });
+    };
+    // Default layout unless the operator supplied a custom template — the
+    // default path is byte-for-byte unchanged.
+    const markdown = input.template
+        ? renderTemplate(input.template, buildTemplateVars(renderCtx))
+        : renderMarkdown(renderCtx);
     return {
         service: input.service,
         window: input.window,
@@ -203,3 +208,51 @@ function renderMarkdown(ctx) {
     // could approach MB without the slice() caps above.
     return lines.join("\n");
 }
+/** Build the `{{token}}` → markdown-block map for a custom template. */
+export function buildTemplateVars(ctx) {
+    const { input, timeline, contributingSignals, peakNode, errorTraces, followUps, synopsis } = ctx;
+    const timelineBlock = timeline.length === 0
+        ? "_No anomaly samples in this window._"
+        : ["| ts | service | score | severity | method |", "|---|---|---|---|---|",
+            ...timeline.slice(0, 20).map((t) => `| \`${t.ts}\` | \`${t.service}\` | ${t.score} | ${t.severity} | ${t.method} |`),
+            ...(timeline.length > 20 ? [`| … | _${timeline.length - 20} more rows_ |  |  |  |`] : [])].join("\n");
+    const brLines = [];
+    brLines.push(peakNode ? `Root node: **\`${peakNode.name}\`** (\`${peakNode.kind}\`).` : "_Topology snapshot empty._");
+    if (input.blastRadius.nodes.length > 0) {
+        brLines.push("", "| node | kind |", "|---|---|", ...input.blastRadius.nodes.slice(0, 30).map((n) => `| \`${n.name}\`${n.root ? " *(root)*" : ""} | \`${n.kind}\` |`));
+    }
+    brLines.push("", `Edges in radius: **${input.blastRadius.edges.length}**.`);
+    const blastRadiusBlock = brLines.join("\n");
+    const signalsBlock = contributingSignals.length === 0
+        ? "_No anomaly samples to rank._"
+        : ["| signal | samples | mean score |", "|---|---|---|",
+            ...contributingSignals.slice(0, 10).map((s) => `| \`${s.signal}\` | ${s.count} | ${s.meanScore} |`)].join("\n");
+    const tracesBlock = input.traces.length === 0
+        ? "_No traces returned for the window. Configure a Tempo / Jaeger source if traces are expected._"
+        : ["| trace | service | duration ms | error |", "|---|---|---|---|",
+            ...input.traces.slice(0, 10).map((t) => `| \`${t.traceId}\` | \`${t.rootService}\` | ${t.durationMs} | ${t.hasError ? "yes" : "no"} |`),
+            ...(errorTraces > 0 ? [`\n_${errorTraces} of the returned traces carried error spans._`] : [])].join("\n");
+    const logHighlightsBlock = (input.logHighlights ?? []).length === 0
+        ? "_No log highlights._"
+        : input.logHighlights.map((l) => `- ${l}`).join("\n");
+    const followUpsBlock = followUps.map((f) => `- ${f}`).join("\n");
+    return {
+        service: input.service,
+        window: input.window,
+        from: input.fromIso,
+        to: input.toIso,
+        tenant: input.tenant,
+        synopsis,
+        timeline: timelineBlock,
+        blastRadius: blastRadiusBlock,
+        signals: signalsBlock,
+        traces: tracesBlock,
+        logHighlights: logHighlightsBlock,
+        followUps: followUpsBlock,
+    };
+}
+/** Interpolate `{{token}}` placeholders. An unknown token is left verbatim so
+ *  a typo is visible in the output rather than silently producing a blank. */
+export function renderTemplate(template, vars) {
+    return template.replace(/\{\{\s*([a-zA-Z][\w]*)\s*\}\}/g, (whole, key) => Object.prototype.hasOwnProperty.call(vars, key) ? vars[key] : whole);
+}

package/dist/postmortem/synthesizer.test.js

@@ -139,3 +139,30 @@ test("synthesizePostmortem: report carries the input window + iso bounds back in
     assert.equal(r.fromIso, "2026-06-06T00:00:00.000Z");
     assert.equal(r.toIso, "2026-06-06T01:00:00.000Z");
 });
+test("custom template: tokens are interpolated; default path unchanged when no template", () => {
+    const data = input({
+        anomalies: [anomaly("2026-06-06T00:10:00Z", 0.7, "mad", "warn", "cpu")],
+        blastRadius: { nodes: [{ id: "n1", kind: "pod", name: "payment-1", root: true }], edges: [] },
+        logHighlights: ["payment: 5xx spike"],
+    });
+    // Default (no template) still produces the built-in report.
+    const def = synthesizePostmortem(data);
+    assert.match(def.markdown, /^# Post-mortem — payment/);
+    // Custom template interpolates the known tokens.
+    const tpl = "INCIDENT {{service}} ({{window}})\n\n{{synopsis}}\n\nTIMELINE:\n{{timeline}}\n\nFOLLOWUPS:\n{{followUps}}\n\nLOGS:\n{{logHighlights}}";
+    const out = synthesizePostmortem({ ...data, template: tpl }).markdown;
+    assert.match(out, /^INCIDENT payment \(1h\)/);
+    assert.ok(!out.includes("# Post-mortem"), "custom template replaces the default layout");
+    assert.match(out, /TIMELINE:\n\| ts \| service \| score/);
+    assert.match(out, /LOGS:\n- payment: 5xx spike/);
+    assert.ok(out.includes(def.synopsis), "synopsis token expands to the computed synopsis");
+});
+test("custom template: unknown token is left verbatim (visible typo, not silent blank)", () => {
+    const out = synthesizePostmortem({ ...input(), template: "{{service}} / {{nope}}" }).markdown;
+    assert.equal(out, "payment / {{nope}}");
+});
+test("custom template: empty sections render their placeholder text, not a crash", () => {
+    const out = synthesizePostmortem({ ...input(), template: "T:{{timeline}} L:{{logHighlights}}" }).markdown;
+    assert.match(out, /T:_No anomaly samples in this window\._/);
+    assert.match(out, /L:_No log highlights\._/);
+});