@thotischner/observability-mcp 1.7.1 → 3.0.0

package/dist/audit/log.js

@@ -0,0 +1,200 @@
+/**
+ * Append-only audit log for the management plane.
+ *
+ * Distinct from the enterprise-gate audit (`enterprise/audit/`) which
+ * records every gated MCP tool call. This one records every mutating
+ * `/api/*` request (sources/settings/health-thresholds/connectors)
+ * so an operator can answer "who changed what, when".
+ *
+ * On-disk format is JSONL with one entry per line. Each line includes
+ * `prevHash` and `hash` (SHA-256 over the canonical JSON of the entry
+ * without the hash field itself, plus the previous hash) — a
+ * tamper-evident chain that `scripts/verify-audit.mjs` can walk.
+ *
+ * In-memory mode (no `OMCP_MGMT_AUDIT_FILE`) keeps the last
+ * `inMemoryCap` entries in a ring buffer so the UI's audit tab still
+ * shows something even without persistence configured. This is the
+ * default in the demo / single-user case.
+ */
+import { createHash } from "node:crypto";
+import { appendFile, readFile } from "node:fs/promises";
+export const DEFAULT_IN_MEMORY_CAP = 500;
+const GENESIS_HASH = "0".repeat(64);
+export class AuditLog {
+    cap;
+    file;
+    sinks;
+    ring = [];
+    lastHash = GENESIS_HASH;
+    seq = 0;
+    writeQueue = Promise.resolve();
+    bootstrapped = null;
+    constructor(cfg = {}) {
+        this.cap = cfg.inMemoryCap ?? DEFAULT_IN_MEMORY_CAP;
+        this.file = cfg.file;
+        this.sinks = cfg.sinks ?? [];
+    }
+    /**
+     * If a file is configured, replay it to recover seq + lastHash so a
+     * server restart picks up the chain exactly where it left off.
+     * Safe to call multiple times — bootstraps once and caches.
+     */
+    async bootstrap() {
+        if (!this.file)
+            return;
+        if (this.bootstrapped)
+            return this.bootstrapped;
+        this.bootstrapped = (async () => {
+            let raw;
+            try {
+                raw = await readFile(this.file, "utf8");
+            }
+            catch {
+                return; // first run, fine
+            }
+            for (const line of raw.split("\n")) {
+                const t = line.trim();
+                if (!t)
+                    continue;
+                try {
+                    const entry = JSON.parse(t);
+                    if (typeof entry.seq === "number")
+                        this.seq = Math.max(this.seq, entry.seq);
+                    if (typeof entry.hash === "string")
+                        this.lastHash = entry.hash;
+                    if (this.ring.length === this.cap)
+                        this.ring.shift();
+                    this.ring.push(entry);
+                }
+                catch {
+                    // skip malformed line — don't fail boot on a single corrupt entry
+                }
+            }
+        })();
+        return this.bootstrapped;
+    }
+    /**
+     * Record an event. Returns the canonical entry (with chain fields)
+     * once enqueued; persistence to disk completes asynchronously.
+     */
+    async record(input) {
+        if (this.bootstrapped)
+            await this.bootstrapped;
+        this.seq += 1;
+        const ts = new Date().toISOString();
+        const base = { ts, seq: this.seq, prevHash: this.lastHash, ...input };
+        const hash = chainHash(base);
+        const entry = { ...base, hash };
+        this.lastHash = hash;
+        if (this.ring.length === this.cap)
+            this.ring.shift();
+        this.ring.push(entry);
+        if (this.file) {
+            const file = this.file;
+            // Serialize disk writes so concurrent records don't interleave bytes.
+            this.writeQueue = this.writeQueue.then(() => appendFile(file, JSON.stringify(entry) + "\n", "utf8").catch(() => {
+                // intentionally swallow — losing a single audit line is
+                // strictly better than crashing the management plane.
+            }));
+        }
+        // Fan out to any external sinks (webhook, archive, ...). Sinks
+        // are mirrors: failures are swallowed inside the sink so a sick
+        // SIEM never takes down the gateway. The JSONL master remains
+        // the authoritative chain.
+        for (const sink of this.sinks) {
+            // Intentionally not awaited: record() must stay fast and
+            // independent of receiver health.
+            sink.write(entry).catch((err) => {
+                console.warn("AuditLog: sink %s write failed: %s", sink.name, err instanceof Error ? err.message : String(err));
+            });
+        }
+        return entry;
+    }
+    /** Flush every configured sink. Called from SIGTERM and tests. */
+    async flushSinks() {
+        await this.writeQueue;
+        await Promise.all(this.sinks.map((s) => s.flush
+            ? s.flush().catch((err) => console.warn("AuditLog: sink %s flush failed: %s", s.name, err instanceof Error ? err.message : String(err)))
+            : Promise.resolve()));
+    }
+    /** Snapshot of the in-memory ring (most recent last). */
+    list(opts = {}) {
+        // Coerce non-finite / non-positive limits (NaN from a bad query
+        // string, negative, undefined) to the 100 default. Previously
+        // NaN propagated through Math.min / Math.max and the comparison
+        // `out.length < NaN` was always false, so `?limit=foo` returned
+        // an empty array instead of the default page.
+        const requested = typeof opts.limit === "number" && Number.isFinite(opts.limit) && opts.limit > 0
+            ? Math.floor(opts.limit)
+            : 100;
+        const lim = Math.min(requested, this.cap);
+        const out = [];
+        for (let i = this.ring.length - 1; i >= 0 && out.length < lim; i--) {
+            const e = this.ring[i];
+            if (opts.from && e.ts < opts.from)
+                continue;
+            if (opts.to && e.ts > opts.to)
+                continue;
+            if (opts.actor && e.actor.sub !== opts.actor)
+                continue;
+            if (opts.action && e.action !== opts.action)
+                continue;
+            if (opts.tenant) {
+                const entryTenant = e.tenant || "default";
+                if (entryTenant !== opts.tenant)
+                    continue;
+            }
+            out.push(e);
+        }
+        return out;
+    }
+    /** For verification scripts. */
+    get tipHash() { return this.lastHash; }
+    get nextSeq() { return this.seq + 1; }
+}
+/** Stable hash of an entry-without-hash, against `prevHash` already present. */
+export function chainHash(entryWithoutHash) {
+    // Canonical JSON: recursively sort keys so the digest is reproducible
+    // independent of insertion order. Cannot use JSON.stringify's
+    // string-array replacer here — that one filters at every level, which
+    // would strip nested properties (e.g. actor.sub) and collapse two
+    // distinct entries to the same canonical form.
+    return createHash("sha256").update(canonicalJson(entryWithoutHash)).digest("hex");
+}
+/** Deterministic JSON for hashing — keys sorted at every depth.
+ * Mirrors JSON.stringify's "drop undefined values" rule so a freshly-
+ * recorded entry and a round-tripped JSON.parse() of the same entry
+ * (which silently drops undefineds) hash identically. */
+function canonicalJson(v) {
+    if (v === undefined)
+        return ""; // caller must filter at the parent level
+    if (v === null || typeof v !== "object")
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return "[" + v.map((x) => canonicalJson(x ?? null)).join(",") + "]";
+    const o = v;
+    const keys = Object.keys(o).filter((k) => o[k] !== undefined).sort();
+    return "{" +
+        keys
+            .map((k) => JSON.stringify(k) + ":" + canonicalJson(o[k]))
+            .join(",") +
+        "}";
+}
+/** Walk a JSONL file end-to-end and confirm every entry's hash matches
+ * the chain. Used by the offline verifier CLI. */
+export function verifyChain(entries) {
+    let prev = GENESIS_HASH;
+    for (let i = 0; i < entries.length; i++) {
+        const e = entries[i];
+        if (e.prevHash !== prev) {
+            return { ok: false, brokenAt: i, reason: `prevHash mismatch (expected ${prev}, got ${e.prevHash})` };
+        }
+        const { hash: _ignored, ...without } = e;
+        const expectedHash = chainHash(without);
+        if (e.hash !== expectedHash) {
+            return { ok: false, brokenAt: i, reason: `hash mismatch (expected ${expectedHash}, got ${e.hash})` };
+        }
+        prev = e.hash;
+    }
+    return { ok: true };
+}

package/dist/audit/log.test.d.ts

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

package/dist/audit/log.test.js

@@ -0,0 +1,147 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AuditLog, verifyChain, chainHash } from "./log.js";
+function sample(seq, prevHash) {
+    const base = {
+        ts: `2026-05-28T00:00:${String(seq).padStart(2, "0")}Z`,
+        seq,
+        prevHash,
+        actor: { sub: "alice" },
+        resource: "sources",
+        action: "write",
+        method: "POST",
+        path: "/api/sources",
+        status: 200,
+    };
+    const hash = chainHash(base);
+    return { ...base, hash };
+}
+test("AuditLog in-memory — record + list", async () => {
+    const log = new AuditLog();
+    await log.record({
+        actor: { sub: "alice", name: "Alice" },
+        resource: "sources",
+        action: "write",
+        method: "POST",
+        path: "/api/sources",
+        status: 200,
+    });
+    await log.record({
+        actor: { sub: "bob" },
+        resource: "settings",
+        action: "write",
+        method: "PUT",
+        path: "/api/settings",
+        status: 200,
+    });
+    const entries = log.list();
+    assert.equal(entries.length, 2);
+    // Most recent first.
+    assert.equal(entries[0].actor.sub, "bob");
+    assert.equal(entries[1].actor.sub, "alice");
+    // Chain is intact: prevHash of entry 2 equals hash of entry 1
+    // (entries[1] is the FIRST chronologically here).
+    assert.equal(entries[0].prevHash, entries[1].hash);
+});
+test("AuditLog — list filters by actor + action + window", async () => {
+    const log = new AuditLog();
+    await log.record({ actor: { sub: "alice" }, resource: "sources", action: "write", method: "POST", path: "/api/sources", status: 200 });
+    await log.record({ actor: { sub: "bob" }, resource: "sources", action: "delete", method: "DELETE", path: "/api/sources/x", status: 200 });
+    await log.record({ actor: { sub: "alice" }, resource: "settings", action: "write", method: "PUT", path: "/api/settings", status: 200 });
+    assert.equal(log.list({ actor: "alice" }).length, 2);
+    assert.equal(log.list({ action: "delete" }).length, 1);
+    assert.equal(log.list({ actor: "bob", action: "delete" }).length, 1);
+    // Empty window → nothing
+    assert.equal(log.list({ from: "2099-01-01", to: "2099-12-31" }).length, 0);
+});
+test("AuditLog — tenant filter scopes results; entries with no tenant treated as 'default'", async () => {
+    const log = new AuditLog();
+    await log.record({ actor: { sub: "alice" }, tenant: "acme", resource: "sources", action: "write", method: "POST", path: "/api/sources", status: 200 });
+    await log.record({ actor: { sub: "bob" }, tenant: "bigco", resource: "sources", action: "write", method: "POST", path: "/api/sources", status: 200 });
+    // No tenant on this entry → treated as "default" when filtering
+    await log.record({ actor: { sub: "carol" }, resource: "sources", action: "write", method: "POST", path: "/api/sources", status: 200 });
+    assert.equal(log.list({ tenant: "acme" }).length, 1);
+    assert.equal(log.list({ tenant: "bigco" }).length, 1);
+    assert.equal(log.list({ tenant: "default" }).length, 1);
+    // No tenant filter → all three visible
+    assert.equal(log.list({}).length, 3);
+});
+test("AuditLog — in-memory ring honours cap", async () => {
+    const log = new AuditLog({ inMemoryCap: 3 });
+    for (let i = 0; i < 10; i++) {
+        await log.record({ actor: { sub: `u${i}` }, resource: "sources", action: "write", method: "POST", path: "/api/sources", status: 200 });
+    }
+    const entries = log.list({ limit: 100 });
+    assert.equal(entries.length, 3);
+    // Only the three most recent should survive.
+    assert.deepEqual(entries.map((e) => e.actor.sub), ["u9", "u8", "u7"]);
+});
+test("AuditLog.list — non-finite / non-positive limit falls back to the 100 default", async () => {
+    const log = new AuditLog({ inMemoryCap: 10 });
+    for (let i = 0; i < 5; i++) {
+        await log.record({ actor: { sub: `u${i}` }, resource: "sources", action: "write", method: "POST", path: "/api/sources", status: 200 });
+    }
+    // NaN — what /api/audit?limit=foo previously produced via parseInt
+    assert.equal(log.list({ limit: Number.NaN }).length, 5);
+    // Negative — no point pretending the caller meant "minus three entries"
+    assert.equal(log.list({ limit: -3 }).length, 5);
+    // Zero — same. The default keeps the response useful.
+    assert.equal(log.list({ limit: 0 }).length, 5);
+    // Sanity: a sensible positive limit still constrains the result
+    assert.equal(log.list({ limit: 2 }).length, 2);
+    // Decimal positive — floored, so 2.9 → 2
+    assert.equal(log.list({ limit: 2.9 }).length, 2);
+});
+test("AuditLog — file mode persists and bootstraps", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "omcp-audit-"));
+    const file = join(dir, "audit.jsonl");
+    try {
+        const log1 = new AuditLog({ file });
+        await log1.bootstrap();
+        await log1.record({ actor: { sub: "alice" }, resource: "sources", action: "write", method: "POST", path: "/api/sources", status: 200 });
+        await log1.record({ actor: { sub: "alice" }, resource: "sources", action: "write", method: "POST", path: "/api/sources", status: 200 });
+        // Allow the write queue to flush.
+        await new Promise((r) => setTimeout(r, 30));
+        const raw = await readFile(file, "utf8");
+        const lines = raw.trim().split("\n");
+        assert.equal(lines.length, 2);
+        // Restart: bootstrap should pick up seq + lastHash.
+        const log2 = new AuditLog({ file });
+        await log2.bootstrap();
+        assert.equal(log2.nextSeq, 3, "expected nextSeq to resume at 3 after replay");
+        const next = await log2.record({ actor: { sub: "alice" }, resource: "sources", action: "write", method: "POST", path: "/api/sources", status: 200 });
+        assert.equal(next.seq, 3);
+        // prevHash chain continued from the replayed tip.
+        const firstChain = JSON.parse(lines[0]);
+        const secondChain = JSON.parse(lines[1]);
+        assert.equal(secondChain.prevHash, firstChain.hash);
+        assert.equal(next.prevHash, secondChain.hash);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+test("verifyChain — accepts a clean chain", () => {
+    const e1 = sample(1, "0".repeat(64));
+    const e2 = sample(2, e1.hash);
+    const r = verifyChain([e1, e2]);
+    assert.deepEqual(r, { ok: true });
+});
+test("verifyChain — rejects a flipped prevHash", () => {
+    const e1 = sample(1, "0".repeat(64));
+    const e2 = { ...sample(2, e1.hash), prevHash: "deadbeef".repeat(8) };
+    const r = verifyChain([e1, e2]);
+    assert.equal(r.ok, false);
+    if (!r.ok)
+        assert.equal(r.brokenAt, 1);
+});
+test("verifyChain — rejects an entry whose hash doesn't match its content", () => {
+    const e1 = sample(1, "0".repeat(64));
+    // Tamper with `actor` AFTER hashing.
+    const e1Tampered = { ...e1, actor: { sub: "mallory" } };
+    const r = verifyChain([e1Tampered]);
+    assert.equal(r.ok, false);
+});

package/dist/audit/middleware.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Express middleware that records one audit entry per mutating
+ * /api/* request after the response has been sent. Skips read-only
+ * methods. In anonymous mode the actor is reported as
+ * `anonymous`; in basic mode the session's sub/name are used.
+ */
+import type { RequestHandler } from "express";
+import { AuditLog } from "./log.js";
+export interface AuditMiddlewareConfig {
+    audit: AuditLog;
+    resource: string;
+    action: string;
+}
+/**
+ * Build a per-route audit middleware. Pairs cleanly with the RBAC
+ * `need(resource, action)` calls already on the route — pass the same
+ * (resource, action) pair so the audit entry matches the policy
+ * decision that just ran.
+ */
+export declare function buildAuditMiddleware(cfg: AuditMiddlewareConfig): RequestHandler;

package/dist/audit/middleware.js

@@ -0,0 +1,50 @@
+/**
+ * Express middleware that records one audit entry per mutating
+ * /api/* request after the response has been sent. Skips read-only
+ * methods. In anonymous mode the actor is reported as
+ * `anonymous`; in basic mode the session's sub/name are used.
+ */
+const MUTATING = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+/**
+ * Build a per-route audit middleware. Pairs cleanly with the RBAC
+ * `need(resource, action)` calls already on the route — pass the same
+ * (resource, action) pair so the audit entry matches the policy
+ * decision that just ran.
+ */
+export function buildAuditMiddleware(cfg) {
+    return function audit(req, res, next) {
+        if (!MUTATING.has(req.method)) {
+            next();
+            return;
+        }
+        res.on("finish", () => {
+            const sess = req.session;
+            // Pick the most-likely identifier from the route params so the
+            // audit entry's `target` lines up with what the operator
+            // typed. Most routes use `:name`; products use `:id`; fall
+            // through if neither (the entry still records method+path).
+            const target = typeof req.params?.name === "string"
+                ? req.params.name
+                : typeof req.params?.id === "string" ? req.params.id : undefined;
+            cfg.audit
+                .record({
+                actor: sess
+                    ? { sub: sess.sub, name: sess.name }
+                    : { sub: "anonymous" },
+                tenant: sess?.tenant || "default",
+                resource: cfg.resource,
+                action: cfg.action,
+                method: req.method,
+                path: req.path,
+                status: res.statusCode,
+                ip: req.ip || undefined,
+                target,
+            })
+                .catch(() => {
+                // record() already swallows file errors — this catch only
+                // covers the synchronous Promise wiring.
+            });
+        });
+        next();
+    };
+}

package/dist/audit/redaction-bypass.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Pure helpers for the redaction-bypass forensic trail.
+ *
+ * The bypass surface deliberately writes to TWO channels:
+ *
+ *   1. A sanitised stderr breadcrumb — for SIEM tail-and-forward
+ *      setups that ingest the container's stdio. It carries the
+ *      correlationId so an investigator can join it with the
+ *      tamper-evident chain entry, but it intentionally does NOT
+ *      include the credential name / token / actor sub — those would
+ *      land in unstructured operator logs that CodeQL flags as a
+ *      taint sink.
+ *
+ *   2. The management-plane audit chain — full identity (actor.sub +
+ *      tenant), hashed alongside every other mutating /api/* call.
+ *      Survives a process restart when OMCP_MGMT_AUDIT_FILE is set;
+ *      otherwise lives in the 500-entry in-memory ring.
+ *
+ * The bypass code path is small but security-critical: a regression
+ * that drops either channel weakens the audit story. The pure
+ * helpers below let unit tests pin the shape of both records, plus
+ * the boundary properties:
+ *
+ *   - resource === "redaction", action === "bypass" (RBAC vocabulary)
+ *   - status === 200 on engage, 403 on deny
+ *   - stderr breadcrumb omits anything credential-shaped
+ *   - target === args.service (when present)
+ */
+import type { RequestContext } from "../context.js";
+export type BypassEvent = "redaction_bypass_engaged" | "redaction_bypass_denied";
+/** Stderr-breadcrumb payload. JSON-serialised by the caller. */
+export interface BypassBreadcrumb {
+    event: BypassEvent;
+    ts: string;
+    auth: RequestContext["auth"];
+    tool: string;
+    service: string | null;
+    correlationId: string;
+    /** Only populated on the deny branch — explains why the request
+     *  was rejected, never carries the credential name itself. */
+    reason?: "credential_not_in_OMCP_KEY_BYPASS_REDACTION";
+}
+export interface BypassAuditParams {
+    actor: {
+        sub: string;
+    };
+    tenant: string;
+    resource: "redaction";
+    action: "bypass";
+    method: "MCP";
+    path: string;
+    status: 200 | 403;
+    target?: string;
+}
+/** Shape the stderr breadcrumb. Deliberately credential-free; the
+ *  joining key to the audit chain is the correlationId. */
+export declare function buildBypassBreadcrumb(event: BypassEvent, ctx: RequestContext, args: unknown, opts?: {
+    tool?: string;
+    nowIso?: string;
+}): BypassBreadcrumb;
+/** Shape the management-plane audit record. Engaged = 200 (the
+ *  bypass actually fired), denied = 403 (the agent asked but the
+ *  credential wasn't allow-listed). Either way the chain captures
+ *  the attempt. */
+export declare function buildBypassAuditParams(engaged: boolean, ctx: RequestContext, args: unknown, opts?: {
+    tool?: string;
+}): BypassAuditParams;

package/dist/audit/redaction-bypass.js

@@ -0,0 +1,64 @@
+/**
+ * Pure helpers for the redaction-bypass forensic trail.
+ *
+ * The bypass surface deliberately writes to TWO channels:
+ *
+ *   1. A sanitised stderr breadcrumb — for SIEM tail-and-forward
+ *      setups that ingest the container's stdio. It carries the
+ *      correlationId so an investigator can join it with the
+ *      tamper-evident chain entry, but it intentionally does NOT
+ *      include the credential name / token / actor sub — those would
+ *      land in unstructured operator logs that CodeQL flags as a
+ *      taint sink.
+ *
+ *   2. The management-plane audit chain — full identity (actor.sub +
+ *      tenant), hashed alongside every other mutating /api/* call.
+ *      Survives a process restart when OMCP_MGMT_AUDIT_FILE is set;
+ *      otherwise lives in the 500-entry in-memory ring.
+ *
+ * The bypass code path is small but security-critical: a regression
+ * that drops either channel weakens the audit story. The pure
+ * helpers below let unit tests pin the shape of both records, plus
+ * the boundary properties:
+ *
+ *   - resource === "redaction", action === "bypass" (RBAC vocabulary)
+ *   - status === 200 on engage, 403 on deny
+ *   - stderr breadcrumb omits anything credential-shaped
+ *   - target === args.service (when present)
+ */
+/** Shape the stderr breadcrumb. Deliberately credential-free; the
+ *  joining key to the audit chain is the correlationId. */
+export function buildBypassBreadcrumb(event, ctx, args, opts = {}) {
+    const out = {
+        event,
+        ts: opts.nowIso ?? new Date().toISOString(),
+        auth: ctx.auth,
+        tool: opts.tool ?? "query_logs",
+        service: args?.service ?? null,
+        correlationId: ctx.correlationId,
+    };
+    if (event === "redaction_bypass_denied") {
+        out.reason = "credential_not_in_OMCP_KEY_BYPASS_REDACTION";
+    }
+    return out;
+}
+/** Shape the management-plane audit record. Engaged = 200 (the
+ *  bypass actually fired), denied = 403 (the agent asked but the
+ *  credential wasn't allow-listed). Either way the chain captures
+ *  the attempt. */
+export function buildBypassAuditParams(engaged, ctx, args, opts = {}) {
+    const tool = opts.tool ?? "query_logs";
+    const params = {
+        actor: { sub: ctx.principalId },
+        tenant: ctx.tenant,
+        resource: "redaction",
+        action: "bypass",
+        method: "MCP",
+        path: `/mcp/${tool}`,
+        status: engaged ? 200 : 403,
+    };
+    const service = args?.service;
+    if (typeof service === "string" && service)
+        params.target = service;
+    return params;
+}

package/dist/audit/redaction-bypass.test.d.ts

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

package/dist/audit/redaction-bypass.test.js

@@ -0,0 +1,72 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { buildBypassBreadcrumb, buildBypassAuditParams, } from "./redaction-bypass.js";
+function ctxFor(overrides = {}) {
+    return {
+        principalId: "agent",
+        auth: "apikey",
+        tenant: "acme",
+        correlationId: "corr-123",
+        ...overrides,
+    };
+}
+test("buildBypassBreadcrumb — engaged path carries auth + tool + service + correlationId, NO credential fields", () => {
+    const bc = buildBypassBreadcrumb("redaction_bypass_engaged", ctxFor(), { service: "payment-service" }, { nowIso: "2026-06-03T00:00:00.000Z" });
+    assert.equal(bc.event, "redaction_bypass_engaged");
+    assert.equal(bc.ts, "2026-06-03T00:00:00.000Z");
+    assert.equal(bc.auth, "apikey");
+    assert.equal(bc.tool, "query_logs");
+    assert.equal(bc.service, "payment-service");
+    assert.equal(bc.correlationId, "corr-123");
+    assert.equal(bc.reason, undefined, "engaged path must not carry a deny reason");
+    // Guard: no credential-shaped fields. If a future edit adds the
+    // principalId / token / cred-name to the breadcrumb, this fails.
+    // We match KEY names (followed by ":") not value-string contents,
+    // so the legitimate auth: "apikey" field survives.
+    const serialised = JSON.stringify(bc);
+    assert.doesNotMatch(serialised, /"(principalId|token|credential|apiKey|api_key|sub|name)"\s*:/i);
+});
+test("buildBypassBreadcrumb — denied path adds the deny reason; still no credential leak", () => {
+    const bc = buildBypassBreadcrumb("redaction_bypass_denied", ctxFor({ principalId: "ci-bot" }), { service: "svc" });
+    assert.equal(bc.event, "redaction_bypass_denied");
+    assert.equal(bc.reason, "credential_not_in_OMCP_KEY_BYPASS_REDACTION");
+    const serialised = JSON.stringify(bc);
+    assert.doesNotMatch(serialised, /ci-bot/, "principalId must not appear in stderr breadcrumb");
+});
+test("buildBypassBreadcrumb — missing service becomes explicit null (not undefined)", () => {
+    const bc = buildBypassBreadcrumb("redaction_bypass_engaged", ctxFor(), {});
+    // Important: JSON.stringify omits undefined keys; null serialises
+    // as `"service":null`, which downstream SIEM parsers can match on.
+    assert.equal(bc.service, null);
+    assert.match(JSON.stringify(bc), /"service":null/);
+});
+test("buildBypassAuditParams — engaged status 200, RBAC vocabulary, full identity", () => {
+    const p = buildBypassAuditParams(true, ctxFor(), { service: "payment-service" });
+    assert.equal(p.status, 200);
+    assert.equal(p.resource, "redaction");
+    assert.equal(p.action, "bypass");
+    assert.equal(p.method, "MCP");
+    assert.equal(p.path, "/mcp/query_logs");
+    assert.equal(p.actor.sub, "agent");
+    assert.equal(p.tenant, "acme");
+    assert.equal(p.target, "payment-service");
+});
+test("buildBypassAuditParams — denied status 403 (not 200) so audit-log readers can distinguish attempt vs success", () => {
+    const p = buildBypassAuditParams(false, ctxFor(), { service: "svc" });
+    assert.equal(p.status, 403);
+    // Critical: the deny path must still record actor.sub + tenant so
+    // an investigator can see WHO tried, not just THAT someone tried.
+    assert.equal(p.actor.sub, "agent");
+    assert.equal(p.tenant, "acme");
+});
+test("buildBypassAuditParams — omits target when args.service is absent (not empty-string)", () => {
+    const p = buildBypassAuditParams(true, ctxFor(), {});
+    assert.equal(p.target, undefined);
+    // Defence: an empty-string service should not become an audit target.
+    const p2 = buildBypassAuditParams(true, ctxFor(), { service: "" });
+    assert.equal(p2.target, undefined);
+});
+test("buildBypassAuditParams — tool name flows into the path so audit readers can filter per-tool", () => {
+    const p = buildBypassAuditParams(true, ctxFor(), { service: "s" }, { tool: "query_metrics" });
+    assert.equal(p.path, "/mcp/query_metrics");
+});

package/dist/audit/sinks/types.d.ts

@@ -0,0 +1,18 @@
+import type { AuditEntry } from "../log.js";
+/**
+ * A destination that receives every chained audit entry. The on-disk
+ * JSONL chain stays the authoritative master (so the hash chain is
+ * never split-brain across sinks); sinks are mirrors for SIEM /
+ * archive / webhook fan-out.
+ *
+ * write() must NEVER throw — sinks log+swallow internally. A sink that
+ * dies must not take down the management plane.
+ */
+export interface AuditSink {
+    /** Stable identifier, used in logs and env selection. */
+    readonly name: string;
+    /** Persist one chained entry. Best-effort; failures are logged. */
+    write(entry: AuditEntry): Promise<void>;
+    /** Flush any buffered state. Called on SIGTERM and in tests. */
+    flush?(): Promise<void>;
+}

package/dist/audit/sinks/types.js

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