@thotischner/observability-mcp 1.8.1 → 3.0.1

package/dist/analysis/history.d.ts

@@ -0,0 +1,70 @@
+export interface AnomalyRecord {
+    /** ISO-8601 timestamp (the moment the score was computed). */
+    ts: string;
+    service: string;
+    tenant: string;
+    /** Anomaly score, 0..1 typically. Numeric — the sample written to the TSDB. */
+    score: number;
+    /** "mad" | "seasonality" | "correlator" — the method that produced the score. */
+    method: string;
+    /** "info" | "warn" | "critical". */
+    severity: string;
+    /** Optional source label (which signal the score applied to). */
+    signal?: string;
+}
+export interface AnomalyHistoryConfig {
+    /** Remote-write URL. Setting this enables the history sink. */
+    url?: string;
+    /** Comma-separated key=value pairs for extra request headers. */
+    headers?: Record<string, string>;
+    /** Bearer token forwarded as Authorization header. */
+    bearerToken?: string;
+    /** Flush interval in ms. Default 10 000. */
+    flushIntervalMs?: number;
+    /** Max buffer size before a synchronous flush. Default 500. */
+    maxBufferSize?: number;
+    /** Per-request timeout (ms). Default 5 000. */
+    requestTimeoutMs?: number;
+    /** Inject fetch for tests. */
+    fetchImpl?: typeof fetch;
+}
+export declare function fromEnv(env?: NodeJS.ProcessEnv): AnomalyHistoryConfig;
+/**
+ * In-process buffer + remote-write client. Use one instance per
+ * gateway process; `record()` is called from the anomaly detector;
+ * `flush()` runs on the interval AND on SIGTERM.
+ */
+export declare class AnomalyHistory {
+    private readonly url?;
+    private readonly headers;
+    private readonly bearerToken?;
+    private readonly flushIntervalMs;
+    private readonly maxBufferSize;
+    private readonly requestTimeoutMs;
+    private readonly fetchImpl;
+    private buffer;
+    private timer?;
+    private flushing;
+    constructor(cfg?: AnomalyHistoryConfig);
+    /** Whether the history sink is enabled (URL configured). */
+    isEnabled(): boolean;
+    /** Begin the flush timer. Idempotent. No-op when sink is disabled. */
+    start(): void;
+    /** Stop the flush timer + flush one last time. */
+    stop(): Promise<void>;
+    /** Add one anomaly to the buffer. Silently drops when disabled.
+     *  Triggers a synchronous flush if the buffer crosses maxBufferSize. */
+    record(entry: AnomalyRecord): Promise<void>;
+    /** Send the current buffer to the remote-write endpoint. Drops the
+     *  buffer on success OR failure — history is best-effort. */
+    flush(): Promise<void>;
+    /** Test seam: number of currently-buffered entries. */
+    bufferSize(): number;
+    /** Visible-for-test: format the buffer as a JSON payload mirroring
+     *  the Prometheus remote-write metric shape. Real remote-write uses
+     *  Snappy-compressed protobuf — we ship JSON here as a portable
+     *  baseline that any TSDB-receiving collector can ingest via a tiny
+     *  shim. A protobuf+Snappy fast path is a follow-up. */
+    formatBatch(batch: AnomalyRecord[]): unknown;
+    private sendBatch;
+}

package/dist/analysis/history.js

@@ -0,0 +1,170 @@
+// Anomaly history — persists per-anomaly scores to an external TSDB
+// via Prometheus remote-write so post-mortems can replay what the
+// gateway saw at a specific time. Opt-in via
+// OMCP_ANOMALY_HISTORY_REMOTE_WRITE; default OFF preserves the
+// pre-F15 "scores live in process memory only" behaviour.
+//
+// Wire format: a single time-series sample per recorded anomaly,
+// labelled with service / tenant / signal / method (mad / seasonality
+// / correlator) / severity. The TSDB-side query then becomes a
+// `omcp_anomaly_score{service="payment"}` PromQL.
+//
+// Buffering: writes are batched on a fixed flush interval so the
+// remote-write side never sees a request per anomaly. Failure to
+// flush logs once and drops the buffer — the gateway must never
+// block on a sick TSDB.
+export function fromEnv(env = process.env) {
+    const url = env.OMCP_ANOMALY_HISTORY_REMOTE_WRITE?.trim();
+    const headers = {};
+    const raw = env.OMCP_ANOMALY_HISTORY_HEADERS;
+    if (raw) {
+        for (const part of raw.split(",")) {
+            const [k, ...rest] = part.split("=");
+            const key = k?.trim();
+            const value = rest.join("=").trim();
+            if (key && value)
+                headers[key] = value;
+        }
+    }
+    return {
+        url: url || undefined,
+        headers: Object.keys(headers).length > 0 ? headers : undefined,
+        bearerToken: env.OMCP_ANOMALY_HISTORY_TOKEN?.trim() || undefined,
+    };
+}
+/**
+ * In-process buffer + remote-write client. Use one instance per
+ * gateway process; `record()` is called from the anomaly detector;
+ * `flush()` runs on the interval AND on SIGTERM.
+ */
+export class AnomalyHistory {
+    url;
+    headers;
+    bearerToken;
+    flushIntervalMs;
+    maxBufferSize;
+    requestTimeoutMs;
+    fetchImpl;
+    buffer = [];
+    timer;
+    flushing = false;
+    constructor(cfg = {}) {
+        this.url = cfg.url;
+        this.headers = cfg.headers ?? {};
+        this.bearerToken = cfg.bearerToken;
+        this.flushIntervalMs = cfg.flushIntervalMs ?? 10_000;
+        this.maxBufferSize = cfg.maxBufferSize ?? 500;
+        this.requestTimeoutMs = cfg.requestTimeoutMs ?? 5_000;
+        this.fetchImpl = cfg.fetchImpl ?? fetch;
+    }
+    /** Whether the history sink is enabled (URL configured). */
+    isEnabled() {
+        return Boolean(this.url);
+    }
+    /** Begin the flush timer. Idempotent. No-op when sink is disabled. */
+    start() {
+        if (!this.isEnabled())
+            return;
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            void this.flush().catch(() => {
+                /* swallow — flush() already logs */
+            });
+        }, this.flushIntervalMs);
+        // unref so the timer doesn't keep the process alive when the
+        // main loop is otherwise idle.
+        this.timer.unref?.();
+    }
+    /** Stop the flush timer + flush one last time. */
+    async stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+        if (this.isEnabled())
+            await this.flush().catch(() => undefined);
+    }
+    /** Add one anomaly to the buffer. Silently drops when disabled.
+     *  Triggers a synchronous flush if the buffer crosses maxBufferSize. */
+    async record(entry) {
+        if (!this.isEnabled())
+            return;
+        this.buffer.push(entry);
+        if (this.buffer.length >= this.maxBufferSize) {
+            await this.flush().catch(() => undefined);
+        }
+    }
+    /** Send the current buffer to the remote-write endpoint. Drops the
+     *  buffer on success OR failure — history is best-effort. */
+    async flush() {
+        if (!this.isEnabled() || this.buffer.length === 0 || this.flushing)
+            return;
+        this.flushing = true;
+        const batch = this.buffer.splice(0, this.buffer.length);
+        try {
+            await this.sendBatch(batch);
+        }
+        catch (err) {
+            console.warn("AnomalyHistory: flush dropped %d entries (%s). History is best-effort; check the remote-write endpoint.", batch.length, err instanceof Error ? err.message : String(err));
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+    /** Test seam: number of currently-buffered entries. */
+    bufferSize() {
+        return this.buffer.length;
+    }
+    /** Visible-for-test: format the buffer as a JSON payload mirroring
+     *  the Prometheus remote-write metric shape. Real remote-write uses
+     *  Snappy-compressed protobuf — we ship JSON here as a portable
+     *  baseline that any TSDB-receiving collector can ingest via a tiny
+     *  shim. A protobuf+Snappy fast path is a follow-up. */
+    formatBatch(batch) {
+        return {
+            // The schema mirrors prometheus.WriteRequest as a JSON object
+            // so collectors that already know "labels + samples" can ingest
+            // it directly.
+            timeseries: batch.map((r) => ({
+                labels: {
+                    __name__: "omcp_anomaly_score",
+                    service: r.service,
+                    tenant: r.tenant,
+                    method: r.method,
+                    severity: r.severity,
+                    ...(r.signal ? { signal: r.signal } : {}),
+                },
+                samples: [{ value: r.score, timestamp: Date.parse(r.ts) }],
+            })),
+        };
+    }
+    async sendBatch(batch) {
+        if (!this.url)
+            return;
+        const body = JSON.stringify(this.formatBatch(batch));
+        const headers = {
+            "content-type": "application/json",
+            ...this.headers,
+        };
+        if (this.bearerToken)
+            headers["authorization"] = `Bearer ${this.bearerToken}`;
+        const ctl = new AbortController();
+        const t = setTimeout(() => ctl.abort(), this.requestTimeoutMs).unref?.();
+        try {
+            const res = await this.fetchImpl(this.url, {
+                method: "POST",
+                headers,
+                body,
+                signal: ctl.signal,
+            });
+            if (!res.ok) {
+                const snippet = (await res.text().catch(() => "")).slice(0, 200);
+                throw new Error(`remote-write returned ${res.status} ${res.statusText}: ${snippet}`);
+            }
+        }
+        finally {
+            if (typeof t === "object" && t)
+                clearTimeout(t);
+        }
+    }
+}

package/dist/analysis/history.test.d.ts

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

package/dist/analysis/history.test.js

@@ -0,0 +1,141 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { AnomalyHistory, fromEnv } from "./history.js";
+function entry(overrides = {}) {
+    return {
+        ts: "2026-06-06T00:00:00.000Z",
+        service: "payment",
+        tenant: "default",
+        score: 0.87,
+        method: "mad",
+        severity: "warn",
+        ...overrides,
+    };
+}
+function captureFetch(captureBody) {
+    const f = (async (_url, init) => {
+        if (captureBody) {
+            captureBody.body = JSON.parse(init.body);
+            captureBody.headers = init.headers;
+        }
+        return { ok: true, status: 200, statusText: "OK", text: async () => "" };
+    });
+    return f;
+}
+test("fromEnv: missing URL → disabled config", () => {
+    assert.equal(fromEnv({}).url, undefined);
+});
+test("fromEnv: parses URL + headers + token", () => {
+    const cfg = fromEnv({
+        OMCP_ANOMALY_HISTORY_REMOTE_WRITE: "https://tsdb/api/v1/write",
+        OMCP_ANOMALY_HISTORY_HEADERS: "x-scope=tenant-a,x-extra=foo=bar",
+        OMCP_ANOMALY_HISTORY_TOKEN: "secret-token",
+    });
+    assert.equal(cfg.url, "https://tsdb/api/v1/write");
+    assert.deepEqual(cfg.headers, { "x-scope": "tenant-a", "x-extra": "foo=bar" });
+    assert.equal(cfg.bearerToken, "secret-token");
+});
+test("isEnabled: false without url, true with url", () => {
+    assert.equal(new AnomalyHistory({}).isEnabled(), false);
+    assert.equal(new AnomalyHistory({ url: "https://x" }).isEnabled(), true);
+});
+test("record: disabled instance silently drops, buffer stays empty", async () => {
+    const h = new AnomalyHistory({});
+    await h.record(entry());
+    assert.equal(h.bufferSize(), 0);
+});
+test("record + flush: posts the buffer as a remote-write-shaped JSON", async () => {
+    const captured = {};
+    const h = new AnomalyHistory({
+        url: "https://tsdb/api/v1/write",
+        fetchImpl: captureFetch(captured),
+    });
+    await h.record(entry({ score: 0.9 }));
+    await h.record(entry({ service: "orders", score: 0.42 }));
+    await h.flush();
+    const body = captured.body;
+    assert.equal(body.timeseries.length, 2);
+    assert.equal(body.timeseries[0].labels.__name__, "omcp_anomaly_score");
+    assert.equal(body.timeseries[0].labels.service, "payment");
+    assert.equal(body.timeseries[0].samples[0].value, 0.9);
+    assert.equal(body.timeseries[1].labels.service, "orders");
+});
+test("flush: bearer token forwarded as Authorization header", async () => {
+    const captured = {};
+    const h = new AnomalyHistory({
+        url: "https://tsdb/api/v1/write",
+        bearerToken: "tok-abc",
+        fetchImpl: captureFetch(captured),
+    });
+    await h.record(entry());
+    await h.flush();
+    assert.equal(captured.headers["authorization"], "Bearer tok-abc");
+});
+test("flush: clears the buffer on success", async () => {
+    const h = new AnomalyHistory({
+        url: "https://tsdb/api/v1/write",
+        fetchImpl: captureFetch(),
+    });
+    await h.record(entry());
+    await h.record(entry());
+    assert.equal(h.bufferSize(), 2);
+    await h.flush();
+    assert.equal(h.bufferSize(), 0);
+});
+test("flush: HTTP error logs + drops buffer (does NOT retry)", async () => {
+    const f = (async () => ({
+        ok: false,
+        status: 503,
+        statusText: "Service Unavailable",
+        text: async () => "tsdb overloaded",
+    }));
+    const h = new AnomalyHistory({
+        url: "https://tsdb/api/v1/write",
+        fetchImpl: f,
+    });
+    await h.record(entry());
+    await h.flush();
+    // Best-effort policy: buffer cleared even on error.
+    assert.equal(h.bufferSize(), 0);
+});
+test("flush: empty buffer is a no-op (no fetch call)", async () => {
+    let called = 0;
+    const f = (async () => {
+        called++;
+        return { ok: true, status: 200, statusText: "OK", text: async () => "" };
+    });
+    const h = new AnomalyHistory({
+        url: "https://tsdb/api/v1/write",
+        fetchImpl: f,
+    });
+    await h.flush();
+    assert.equal(called, 0);
+});
+test("record: synchronous auto-flush triggers when buffer crosses maxBufferSize", async () => {
+    let calls = 0;
+    const f = (async () => {
+        calls++;
+        return { ok: true, status: 200, statusText: "OK", text: async () => "" };
+    });
+    const h = new AnomalyHistory({
+        url: "https://tsdb/api/v1/write",
+        fetchImpl: f,
+        maxBufferSize: 3,
+    });
+    await h.record(entry());
+    await h.record(entry());
+    assert.equal(calls, 0);
+    await h.record(entry()); // crosses threshold → auto-flush
+    assert.equal(calls, 1);
+    assert.equal(h.bufferSize(), 0);
+});
+test("formatBatch: omits empty optional signal label", async () => {
+    const h = new AnomalyHistory({ url: "https://x" });
+    const out = h.formatBatch([entry({ signal: "" })]);
+    assert.equal("signal" in out.timeseries[0].labels, false);
+});
+test("formatBatch: includes signal label when set", () => {
+    const h = new AnomalyHistory({ url: "https://x" });
+    const out = h.formatBatch([entry({ signal: "request_latency" })]);
+    assert.equal(out.timeseries[0].labels.signal, "request_latency");
+});

package/dist/audit/log.d.ts

@@ -16,6 +16,7 @@
  * shows something even without persistence configured. This is the
  * default in the demo / single-user case.
  */
+import type { AuditSink } from "./sinks/types.js";
 export interface AuditEntry {
     /** RFC-3339 UTC timestamp. */
     ts: string;
@@ -51,11 +52,17 @@ export interface AuditLogConfig {
     file?: string;
     /** How many recent entries to keep in memory regardless of file mode. */
     inMemoryCap?: number;
+    /** Mirror every chained entry to one or more external sinks
+     * (Splunk/SIEM webhook, S3 archive, ...). The on-disk JSONL chain
+     * stays the authoritative master — sinks are best-effort mirrors
+     * and never block record(). */
+    sinks?: AuditSink[];
 }
 export declare const DEFAULT_IN_MEMORY_CAP = 500;
 export declare class AuditLog {
     private readonly cap;
     private readonly file;
+    private readonly sinks;
     private ring;
     private lastHash;
     private seq;
@@ -73,6 +80,8 @@ export declare class AuditLog {
      * once enqueued; persistence to disk completes asynchronously.
      */
     record(input: Omit<AuditEntry, "ts" | "seq" | "prevHash" | "hash">): Promise<AuditEntry>;
+    /** Flush every configured sink. Called from SIGTERM and tests. */
+    flushSinks(): Promise<void>;
     /** Snapshot of the in-memory ring (most recent last). */
     list(opts?: {
         from?: string;

package/dist/audit/log.js

@@ -23,6 +23,7 @@ const GENESIS_HASH = "0".repeat(64);
 export class AuditLog {
     cap;
     file;
+    sinks;
     ring = [];
     lastHash = GENESIS_HASH;
     seq = 0;
@@ -31,6 +32,7 @@ export class AuditLog {
     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
@@ -95,8 +97,26 @@ export class AuditLog {
                 // 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

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");
+});