@thotischner/observability-mcp 1.7.1 → 3.0.0

package/dist/openapi.test.d.ts

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

package/dist/openapi.test.js

@@ -0,0 +1,98 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { buildOpenApiSpec } from "./openapi.js";
+test("openapi — every user-visible /api path is documented", () => {
+    // If a future PR adds an endpoint here, also document it in
+    // openapi.ts. The list intentionally excludes admin-only routes the
+    // spec deliberately keeps internal — add to that allow-list rather
+    // than mass-adding routes to the spec.
+    const documentedRoutes = [
+        "/api/health",
+        "/api/services",
+        "/api/sources",
+        "/api/sources/{name}",
+        "/api/sources/{name}/metrics",
+        "/api/source-types",
+        "/api/tools/registry",
+        "/api/settings",
+        "/api/health-thresholds",
+        "/api/me",
+        "/api/auth/login",
+        "/api/auth/logout",
+        "/api/auth/oidc/login",
+        "/api/auth/oidc/callback",
+        "/api/auth/oidc/logout",
+        "/api/audit",
+        "/api/usage",
+        "/api/policy",
+        "/api/subjects",
+        "/api/users/{username}/roles",
+        "/api/policy/roles/{name}",
+        "/api/catalog",
+        "/api/products",
+        "/api/products/{id}",
+        "/api/products/{id}/preview",
+        "/api/info",
+        "/api/openapi.json",
+    ];
+    const spec = buildOpenApiSpec("test-1.0.0");
+    const paths = Object.keys(spec.paths || {});
+    for (const route of documentedRoutes) {
+        assert.ok(paths.includes(route), `expected ${route} to be in the OpenAPI spec, paths=${paths.join(", ")}`);
+    }
+});
+test("openapi — /api/info governance block schema documents every field the handler returns", () => {
+    const spec = buildOpenApiSpec("test-1.0.0");
+    const info = spec.paths?.["/api/info"]?.get;
+    assert.ok(info, "/api/info should be documented");
+    // Walk down to the governance properties; the schema is inlined so
+    // we don't have to chase $refs.
+    const schema = info.responses["200"].content["application/json"].schema;
+    const gov = schema.properties?.governance?.properties;
+    assert.ok(gov, "governance block should be a documented object schema");
+    for (const field of [
+        "authMode",
+        "authSecretEphemeral",
+        "oidcIssuer",
+        "auditPersisted",
+        "catalogConfigured",
+        "redaction",
+        "trustProxy",
+        "toolRatePerMin",
+    ]) {
+        assert.ok(field in gov, `governance.${field} should be in the schema (got: ${Object.keys(gov).join(", ")})`);
+    }
+});
+test("openapi — info.version is the version string the caller passed in", () => {
+    const spec = buildOpenApiSpec("9.9.9-test");
+    assert.equal(spec.info?.version, "9.9.9-test");
+});
+test("openapi — SOURCE_SCHEMA exposes the tenant field (tenant-aware sources contract)", () => {
+    // Source entries gained a `tenant` field when per-tenant connector
+    // scoping shipped. The spec is the contract operators write
+    // generated clients against — drift = broken downstream clients.
+    const spec = buildOpenApiSpec("test-1.0.0");
+    // SOURCE_SCHEMA is inlined into both `items` of GET /api/sources and
+    // the requestBody of POST/PUT — pick the GET response, the canonical
+    // read path.
+    const sources = spec.paths?.["/api/sources"]?.get;
+    const items = sources.responses["200"].content["application/json"].schema.items;
+    assert.ok(items.properties.tenant, "SOURCE_SCHEMA must document `tenant` (added when per-tenant scoping shipped)");
+});
+test("openapi — /api/sources GET documents the admin `?tenant=` drill-down query param", () => {
+    const spec = buildOpenApiSpec("test-1.0.0");
+    const get = spec.paths?.["/api/sources"]?.get;
+    const params = get.parameters || [];
+    const tenantParam = params.find((p) => p.name === "tenant" && p.in === "query");
+    assert.ok(tenantParam, "GET /api/sources must document the admin `?tenant=` drill-down param");
+});
+test("openapi — /api/policy GET documents the `?tenant=` probe param + `tenantAware` snapshot field", () => {
+    const spec = buildOpenApiSpec("test-1.0.0");
+    const get = spec.paths?.["/api/policy"]?.get;
+    const params = get.parameters || [];
+    assert.ok(params.some((p) => p.name === "tenant" && p.in === "query"), "GET /api/policy must document the `?tenant=` probe param");
+    const schema = get.responses["200"].content["application/json"].schema;
+    assert.ok(schema.properties.tenantAware, "snapshot must document the `tenantAware` field");
+    const dryRun = schema.properties.dryRun;
+    assert.ok(dryRun?.properties?.tenant, "dryRun must echo the `tenant` field so operators see which tenant the verdict ran under");
+});

package/dist/policy/redact.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Conservative PII / secret redaction for tool outputs that may contain
+ * arbitrary log payloads.
+ *
+ * Scope of this module: pure string redaction with deterministic
+ * patterns. Returns the rewritten string plus a per-category count so
+ * callers can surface a "redacted N matches" hint to the user / agent
+ * without leaking what was matched. Designed to be safe-by-default
+ * (over-redact rather than under-redact) and explicit (each category
+ * tagged in the replacement marker, e.g. `[redacted-email]`).
+ *
+ * Bypass today is process-wide only: set `OMCP_REDACTION=off` if the
+ * upstream is already PII-clean. A per-request `redaction:bypass` RBAC
+ * permission for interactive admin sessions is on the roadmap — see
+ * docs/access-control.md "Why are my logs returning [redacted-email]?"
+ * and docs/redaction.md for the current state.
+ */
+export type RedactionCategory = "email" | "ipv4" | "ipv6" | "bearer" | "jwt" | "api-key" | "aws-key" | "slack-token" | "private-key" | "gh-pat" | "credit-card";
+export interface RedactionResult {
+    text: string;
+    matches: Record<RedactionCategory, number>;
+    totalMatches: number;
+}
+/** Run all patterns in a deterministic order; later patterns won't
+ * re-match content already replaced by an earlier one (the marker
+ * starts with `[redacted-` which none of the patterns match). */
+export declare function redactText(input: string): RedactionResult;
+/** Maximum nesting depth the walker will descend into. Operational
+ * log payloads are essentially flat (objects of strings + a few
+ * nested arrays); a pathologically deep structure is almost certainly
+ * a bug or an attack, and stack-overflowing the auth path is worse
+ * than truncating. The cap is generous — well above anything a
+ * Prometheus / Loki record would ever produce. */
+export declare const MAX_REDACT_DEPTH = 64;
+/** Walk an arbitrary parsed-JSON value and redact every string leaf,
+ * accumulating match counts. Non-string leaves and structural keys are
+ * left untouched. Returns a new value (does not mutate input). Bails
+ * out below `MAX_REDACT_DEPTH` levels of nesting and returns the raw
+ * sub-tree untouched at that point. */
+export declare function redactValue(input: unknown): {
+    value: unknown;
+    matches: Record<RedactionCategory, number>;
+    totalMatches: number;
+};

package/dist/policy/redact.js

@@ -0,0 +1,144 @@
+/**
+ * Conservative PII / secret redaction for tool outputs that may contain
+ * arbitrary log payloads.
+ *
+ * Scope of this module: pure string redaction with deterministic
+ * patterns. Returns the rewritten string plus a per-category count so
+ * callers can surface a "redacted N matches" hint to the user / agent
+ * without leaking what was matched. Designed to be safe-by-default
+ * (over-redact rather than under-redact) and explicit (each category
+ * tagged in the replacement marker, e.g. `[redacted-email]`).
+ *
+ * Bypass today is process-wide only: set `OMCP_REDACTION=off` if the
+ * upstream is already PII-clean. A per-request `redaction:bypass` RBAC
+ * permission for interactive admin sessions is on the roadmap — see
+ * docs/access-control.md "Why are my logs returning [redacted-email]?"
+ * and docs/redaction.md for the current state.
+ */
+// Patterns chosen for low false-positive on operational log text:
+// - Email: standard local@domain.tld with limited TLD chars.
+// - IPv4: strict 0-255 quads to avoid matching version numbers etc.
+// - IPv6: full / compressed; we accept the common forms only.
+// - Bearer: "Authorization: Bearer <token>" — pulls the token out.
+// - JWT: 3-part base64url joined by dots.
+// - Generic API-key: long alnum + base64-ish run after a key= marker.
+const PATTERNS = [
+    // High-confidence cloud-vendor secrets go first — their prefixes are
+    // distinctive enough that they don't conflict with generic patterns.
+    // - AWS access key id: 16-32 chars after AKIA/ASIA/AROA prefix.
+    // - Slack tokens: xoxa-/xoxb-/xoxp-/xoxr-/xoxs- + 10+ chars.
+    // - GitHub PAT: github_pat_<base62 segments> or ghp_/gho_/ghs_/ghu_/ghr_ + 36 chars.
+    // - PEM private-key blocks: greedy match across newlines.
+    { category: "aws-key", re: /\b(?:AKIA|ASIA|AROA)[0-9A-Z]{16,20}\b/g },
+    { category: "slack-token", re: /\bxox[abprsu]-[A-Za-z0-9-]{10,}\b/g },
+    { category: "gh-pat", re: /\b(?:github_pat_[A-Za-z0-9_]{40,}|gh[opsuru]_[A-Za-z0-9]{36})\b/g },
+    { category: "private-key", re: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY-----/g },
+    // emails before other patterns so they don't get eaten partially
+    { category: "email", re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,24}\b/g },
+    { category: "jwt", re: /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g },
+    { category: "bearer", re: /\b[Bb]earer\s+[A-Za-z0-9._\-+/=]{12,}\b/g },
+    { category: "api-key", re: /\b(?:api[_-]?key|x-api-key|token|secret)[=:]\s*['"]?[A-Za-z0-9._\-+/=]{16,}['"]?/gi },
+    // ipv6 — covers full, mid-compressed, leading "::loopback" / "::ffff:v4"
+    // mapped forms, and "::1". Trailing-only `xxxx::` shapes are rare in
+    // operational logs and intentionally not covered. MUST run before
+    // ipv4 so that the IPv4-mapped form (`::ffff:192.168.1.42`) is
+    // classified as IPv6 rather than having ipv4 eat the dotted tail
+    // and leave a half-redacted `::ffff:[redacted-ipv4]` token.
+    { category: "ipv6", re: /\b(?:[0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}\b|\b(?:[0-9a-fA-F]{1,4}:){1,6}(?::[0-9a-fA-F]{1,4}){1,6}\b|::1\b|::ffff:(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\b/g },
+    { category: "ipv4", re: /\b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\b/g },
+];
+function emptyCounts() {
+    return {
+        email: 0, ipv4: 0, ipv6: 0, bearer: 0, jwt: 0, "api-key": 0,
+        "aws-key": 0, "slack-token": 0, "private-key": 0, "gh-pat": 0,
+        "credit-card": 0,
+    };
+}
+/** Luhn check — accepts digits-only string of 13–19 chars. Used to
+ * keep the credit-card redaction from over-matching random digit
+ * strings (order IDs, timestamps, etc.). */
+function luhn(digits) {
+    let sum = 0;
+    let alt = false;
+    for (let i = digits.length - 1; i >= 0; i--) {
+        let n = digits.charCodeAt(i) - 48;
+        if (n < 0 || n > 9)
+            return false;
+        if (alt) {
+            n *= 2;
+            if (n > 9)
+                n -= 9;
+        }
+        sum += n;
+        alt = !alt;
+    }
+    return sum % 10 === 0;
+}
+/** Run all patterns in a deterministic order; later patterns won't
+ * re-match content already replaced by an earlier one (the marker
+ * starts with `[redacted-` which none of the patterns match). */
+export function redactText(input) {
+    const matches = emptyCounts();
+    let text = input;
+    for (const { category, re } of PATTERNS) {
+        text = text.replace(re, () => {
+            matches[category] += 1;
+            return `[redacted-${category}]`;
+        });
+    }
+    // Credit-card pass runs last so an inner-substring of a longer
+    // already-redacted token can't accidentally match. Luhn-validated
+    // so order numbers / timestamps / random digit strings stay intact.
+    text = text.replace(/\b(?:\d[ -]?){12,18}\d\b/g, (match) => {
+        const digits = match.replace(/[ -]/g, "");
+        if (digits.length < 13 || digits.length > 19)
+            return match;
+        if (!luhn(digits))
+            return match;
+        matches["credit-card"] += 1;
+        return "[redacted-credit-card]";
+    });
+    let total = 0;
+    for (const k of Object.keys(matches))
+        total += matches[k];
+    return { text, matches, totalMatches: total };
+}
+/** Maximum nesting depth the walker will descend into. Operational
+ * log payloads are essentially flat (objects of strings + a few
+ * nested arrays); a pathologically deep structure is almost certainly
+ * a bug or an attack, and stack-overflowing the auth path is worse
+ * than truncating. The cap is generous — well above anything a
+ * Prometheus / Loki record would ever produce. */
+export const MAX_REDACT_DEPTH = 64;
+/** Walk an arbitrary parsed-JSON value and redact every string leaf,
+ * accumulating match counts. Non-string leaves and structural keys are
+ * left untouched. Returns a new value (does not mutate input). Bails
+ * out below `MAX_REDACT_DEPTH` levels of nesting and returns the raw
+ * sub-tree untouched at that point. */
+export function redactValue(input) {
+    const counts = emptyCounts();
+    function walk(v, depth) {
+        if (depth > MAX_REDACT_DEPTH)
+            return v;
+        if (typeof v === "string") {
+            const r = redactText(v);
+            for (const k of Object.keys(counts))
+                counts[k] += r.matches[k];
+            return r.text;
+        }
+        if (Array.isArray(v))
+            return v.map((x) => walk(x, depth + 1));
+        if (v && typeof v === "object") {
+            const out = {};
+            for (const [k, vv] of Object.entries(v))
+                out[k] = walk(vv, depth + 1);
+            return out;
+        }
+        return v;
+    }
+    const value = walk(input, 0);
+    let total = 0;
+    for (const k of Object.keys(counts))
+        total += counts[k];
+    return { value, matches: counts, totalMatches: total };
+}

package/dist/policy/redact.test.d.ts

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

package/dist/policy/redact.test.js

@@ -0,0 +1,172 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { redactText, redactValue } from "./redact.js";
+test("redactText — emails are redacted, counted", () => {
+    const r = redactText("alert from alice@example.com to bob@corp.co.uk");
+    assert.equal(r.matches.email, 2);
+    assert.equal(r.totalMatches, 2);
+    assert.match(r.text, /\[redacted-email\].*\[redacted-email\]/);
+});
+test("redactText — IPv4 quads redacted, version numbers left alone", () => {
+    const r = redactText("client 192.168.1.42 connected to 10.0.0.1; version 1.2.3.4");
+    // "1.2.3.4" technically matches as IPv4 — that's fine, it's a valid IPv4
+    // and our threat model errs on the side of over-redaction.
+    assert.ok(r.matches.ipv4 >= 2);
+    assert.match(r.text, /\[redacted-ipv4\]/);
+});
+test("redactText — bearer tokens stripped", () => {
+    const r = redactText('GET /api/foo Authorization: Bearer abcdef1234567890XYZ');
+    assert.equal(r.matches.bearer, 1);
+    assert.match(r.text, /\[redacted-bearer\]/);
+    assert.doesNotMatch(r.text, /abcdef1234567890XYZ/);
+});
+test("redactText — JWTs detected by eyJ prefix + three-part shape", () => {
+    const jwt = "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjMifQ.abcdefghijk-_ABC";
+    const r = redactText(`token=${jwt} for user`);
+    assert.ok(r.matches.jwt >= 1);
+    assert.doesNotMatch(r.text, /eyJ/);
+});
+test("redactText — api-key / cloud-token style assignments", () => {
+    // r1: generic prefix-based api-key match.
+    // r2: x-api-key with an opaque body — falls through to api-key.
+    // r3: token= with a Slack-shape value — the new slack-token pattern
+    //     wins because it runs before api-key; either outcome is fine,
+    //     the contract is "the secret is gone after one pass".
+    const r1 = redactText('api_key="abc123def456ghi789jkl"');
+    const r2 = redactText("x-api-key: sk_test_abcdefghijklmnopqrstuvwxyz");
+    const r3 = redactText("token=xoxb-1234567890-abcdefghijklm");
+    assert.ok(r1.totalMatches >= 1, "expected r1 to be redacted somewhere");
+    assert.ok(r2.totalMatches >= 1, "expected r2 to be redacted somewhere");
+    assert.ok(r3.totalMatches >= 1, "expected r3 to be redacted somewhere");
+    assert.doesNotMatch(r1.text, /abc123def456ghi789jkl/);
+    assert.doesNotMatch(r2.text, /sk_test_abcdefghijklmnopqrstuvwxyz/);
+    assert.doesNotMatch(r3.text, /xoxb-1234567890/);
+});
+test("redactText — leaves harmless text alone", () => {
+    const r = redactText("the order-service replied with 200 OK after 45ms");
+    assert.equal(r.totalMatches, 0);
+    assert.equal(r.text, "the order-service replied with 200 OK after 45ms");
+});
+test("redactText — long digit strings without Luhn don't trigger credit-card", () => {
+    // 16-digit telemetry sequence (UNIX nanos + service id) — should pass through.
+    const r = redactText("ts=1717000000000000000 seq=4242424242424242 user=test");
+    // 4242424242424242 IS Luhn-valid (Visa test number), so that counts as a hit;
+    // but ts=1717... starts with a non-bordered digit run that includes "1717" pattern.
+    // The assertion: only the Luhn-valid 16-digit string is counted as credit-card.
+    assert.equal(r.matches["credit-card"], 1);
+});
+test("redactText — already-redacted markers don't re-match in further passes", () => {
+    // Run the redactor twice; the second pass should be a no-op.
+    const first = redactText("contact alice@example.com");
+    const second = redactText(first.text);
+    assert.equal(second.totalMatches, 0);
+});
+test("redactValue — walks nested objects / arrays, mutates only strings", () => {
+    const input = {
+        user: "bob@corp.co.uk",
+        nested: {
+            ip: "10.0.0.1",
+            count: 42,
+            tags: ["audit", "client=alice@example.com"],
+        },
+        flag: true,
+    };
+    const r = redactValue(input);
+    const v = r.value;
+    assert.equal(v.user, "[redacted-email]");
+    assert.equal(v.nested.ip, "[redacted-ipv4]");
+    assert.equal(v.nested.count, 42);
+    assert.equal(v.nested.tags[0], "audit");
+    assert.equal(v.nested.tags[1], "client=[redacted-email]");
+    assert.equal(v.flag, true);
+    assert.equal(r.matches.email, 2);
+    assert.equal(r.matches.ipv4, 1);
+    assert.equal(r.totalMatches, 3);
+});
+test("redactText — AWS access key IDs (AKIA / ASIA / AROA) are redacted", () => {
+    const r1 = redactText("log: assumed role AKIAIOSFODNN7EXAMPLE today");
+    const r2 = redactText("temporary creds ASIAY34FZKBOKMUTVV7A logged");
+    const r3 = redactText("role-arn AROAIIAFOO2ZBADBCEXAMPLE");
+    assert.equal(r1.matches["aws-key"], 1);
+    assert.equal(r2.matches["aws-key"], 1);
+    assert.equal(r3.matches["aws-key"], 1);
+    assert.match(r1.text, /\[redacted-aws-key\]/);
+    assert.doesNotMatch(r1.text, /AKIAIOSFODNN7EXAMPLE/);
+});
+test("redactText — Slack tokens (xoxa / xoxb / xoxp / …) are redacted", () => {
+    const r = redactText("slack notify: token=xoxb-1234567890-abcdefghijklm result: ok");
+    assert.equal(r.matches["slack-token"], 1);
+    assert.doesNotMatch(r.text, /xoxb-1234567890/);
+});
+test("redactText — GitHub PATs are redacted (ghp_ / github_pat_)", () => {
+    const r1 = redactText("git remote set-url origin https://ghp_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789@github.com/x/y.git");
+    // Use a 40-char body, which matches `[A-Za-z0-9_]{40,}` (note: includes underscore)
+    const r2 = redactText("token github_pat_ABCDEFGH_IJKLMNOPQRSTUVWXYZ012345678ABCDEFGHIJKLMNOP");
+    assert.equal(r1.matches["gh-pat"], 1);
+    assert.equal(r2.matches["gh-pat"], 1);
+});
+test("redactText — Luhn-valid credit-card numbers are redacted, invalid ones pass through", () => {
+    // Visa test number 4111 1111 1111 1111 (Luhn-valid)
+    const r1 = redactText("charge attempted on card 4111111111111111 for $42.00");
+    assert.equal(r1.matches["credit-card"], 1);
+    assert.match(r1.text, /\[redacted-credit-card\]/);
+    // Same number with separators
+    const r2 = redactText("card 4111-1111-1111-1111 declined");
+    assert.equal(r2.matches["credit-card"], 1);
+    assert.doesNotMatch(r2.text, /4111-1111-1111-1111/);
+    // Random 16 digits that DON'T pass Luhn → left alone (e.g. order ID)
+    const r3 = redactText("order 1234567890123456 created");
+    assert.equal(r3.matches["credit-card"], 0);
+    assert.match(r3.text, /1234567890123456/);
+    // Too short / too long stays as-is
+    const r4 = redactText("seq 123456789012 and 12345678901234567890");
+    assert.equal(r4.matches["credit-card"], 0);
+});
+test("redactText — PEM private-key blocks are redacted greedily", () => {
+    const pem = `-----BEGIN RSA PRIVATE KEY-----
+MIIEpAIBAAKCAQEAwLPVKj…
+-----END RSA PRIVATE KEY-----`;
+    const r = redactText(`config:\n${pem}\nend`);
+    assert.equal(r.matches["private-key"], 1);
+    assert.doesNotMatch(r.text, /MIIEpAIBAA/);
+});
+test("redactValue — pathologically deep nesting hits the depth cap, returns sub-tree untouched", () => {
+    // Build a structure deeper than MAX_REDACT_DEPTH (64). At the cap,
+    // the walker should return the remaining sub-tree as-is — no
+    // mutations beyond depth 64, and no stack overflow.
+    let leaf = "alice@example.com";
+    for (let i = 0; i < 200; i++)
+        leaf = { wrap: leaf };
+    // Wrap the deep sub-tree inside a shallow root so a string near
+    // the surface still gets redacted.
+    const r = redactValue({ shallow: "bob@example.com", deep: leaf });
+    const v = r.value;
+    assert.equal(v.shallow, "[redacted-email]", "shallow leaf still redacted");
+    assert.equal(r.matches.email, 1, "only the shallow email is redacted past the depth cap");
+});
+test("redactText — IPv6 addresses are redacted across full / compressed / mapped forms", () => {
+    // Full 8-group address
+    const r1 = redactText("peer 2001:0db8:85a3:0000:0000:8a2e:0370:7334 connected");
+    assert.ok(r1.matches.ipv6 >= 1, "expected full IPv6 to be redacted");
+    assert.doesNotMatch(r1.text, /2001:0db8/);
+    // Mid-compressed (single :: collapsing one zero run)
+    const r2 = redactText("client 2001:db8::8a2e:370:7334 disconnected");
+    assert.ok(r2.matches.ipv6 >= 1, "expected compressed IPv6 to be redacted");
+    // Loopback
+    const r3 = redactText("listening on ::1 port 8080");
+    assert.ok(r3.matches.ipv6 >= 1, "expected ::1 loopback to be redacted");
+    assert.doesNotMatch(r3.text, /::1\b/);
+    // IPv4-mapped IPv6
+    const r4 = redactText("source ::ffff:192.168.1.42 forwarded");
+    assert.ok(r4.matches.ipv6 >= 1, "expected ::ffff: mapped form to be redacted");
+    // Pure version string — must NOT match IPv6 (only two colons, not 7-group)
+    const r5 = redactText("server version 1.2.3 build 4");
+    assert.equal(r5.matches.ipv6, 0, "version string must not look like IPv6");
+});
+test("redactValue — null / undefined leaves are preserved", () => {
+    const r = redactValue({ a: null, b: undefined, c: "alice@example.com" });
+    const v = r.value;
+    assert.equal(v.a, null);
+    assert.equal(v.b, undefined);
+    assert.equal(v.c, "[redacted-email]");
+});

package/dist/postmortem/synthesizer.d.ts

@@ -0,0 +1,83 @@
+export interface AnomalySample {
+    ts: string;
+    service: string;
+    score: number;
+    method: string;
+    severity: string;
+    signal?: string;
+}
+export interface BlastRadiusNode {
+    id: string;
+    kind: string;
+    name: string;
+    /** Whether this node is the suspected root cause (the input service). */
+    root?: boolean;
+}
+export interface TraceSummary {
+    traceId: string;
+    rootName: string;
+    rootService: string;
+    durationMs: number;
+    hasError: boolean;
+}
+export interface PostmortemInput {
+    /** Suspected root-cause service (the operator's first guess). */
+    service: string;
+    /** Rolling window the incident took place in, e.g. "2h", "6h". */
+    window: string;
+    /** Tenant the incident occurred in. */
+    tenant: string;
+    /** RFC-3339 start + end of the incident window for human display. */
+    fromIso: string;
+    toIso: string;
+    /** Live anomaly samples within the window. */
+    anomalies: AnomalySample[];
+    /** Blast-radius graph at peak. */
+    blastRadius: {
+        nodes: BlastRadiusNode[];
+        edges: Array<{
+            from: string;
+            to: string;
+            relation: string;
+        }>;
+    };
+    /** Trace summaries (top by duration). */
+    traces: TraceSummary[];
+    /** Optional log-error summary lines, e.g. ["payment-service: 412 5xx in window"]. */
+    logHighlights?: string[];
+}
+export interface PostmortemReport {
+    service: string;
+    window: string;
+    fromIso: string;
+    toIso: string;
+    /** Compact synopsis the UI puts at the top of the report. */
+    synopsis: string;
+    /** Markdown body of the full report. */
+    markdown: string;
+    /** Structured form for callers that want to render their own UI. */
+    sections: {
+        timeline: Array<{
+            ts: string;
+            service: string;
+            score: number;
+            severity: string;
+            method: string;
+        }>;
+        blastRadius: {
+            nodes: BlastRadiusNode[];
+            edgeCount: number;
+        };
+        topTraces: TraceSummary[];
+        contributingSignals: Array<{
+            signal: string;
+            count: number;
+            meanScore: number;
+        }>;
+        followUps: string[];
+        logHighlights: string[];
+    };
+}
+/** Synthesise one report from already-fetched primitives. Pure
+ *  compute — no I/O. */
+export declare function synthesizePostmortem(input: PostmortemInput): PostmortemReport;