@thotischner/observability-mcp 3.0.0 → 3.1.0

package/dist/analysis/history.d.ts

@@ -27,6 +27,14 @@ export interface AnomalyHistoryConfig {
     requestTimeoutMs?: number;
     /** Inject fetch for tests. */
     fetchImpl?: typeof fetch;
+    /** In-process ring retention window (ms). Default 3 600 000 (1h).
+     *  Powers the Health-tab sparkline; independent of remote-write. */
+    retentionMs?: number;
+    /** Hard cap on ring entries (defends memory under a score storm).
+     *  Default 5 000. */
+    ringMax?: number;
+    /** Clock injection for tests. Returns epoch ms. */
+    now?: () => number;
 }
 export declare function fromEnv(env?: NodeJS.ProcessEnv): AnomalyHistoryConfig;
 /**
@@ -42,7 +50,14 @@ export declare class AnomalyHistory {
     private readonly maxBufferSize;
     private readonly requestTimeoutMs;
     private readonly fetchImpl;
+    private readonly retentionMs;
+    private readonly ringMax;
+    private readonly nowFn;
     private buffer;
+    /** Bounded, time-windowed in-process tier of the sink — powers the
+     *  Health-tab sparkline. Captured on every record() regardless of
+     *  remote-write so the sparkline works out of the box. */
+    private ring;
     private timer?;
     private flushing;
     constructor(cfg?: AnomalyHistoryConfig);
@@ -52,9 +67,28 @@ export declare class AnomalyHistory {
     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. */
+    /** Add one anomaly. Always captured into the in-process ring (powers
+     *  the sparkline); additionally buffered for remote-write only when the
+     *  sink is enabled. Triggers a synchronous flush past maxBufferSize. */
     record(entry: AnomalyRecord): Promise<void>;
+    /** Append to the ring + evict anything outside the retention window or
+     *  beyond the hard cap. O(n) prune is fine — anomaly records are
+     *  infrequent and n is bounded by ringMax. */
+    private pushRing;
+    /**
+     * Recent records from the in-process ring, oldest-first. Filters by
+     * service and/or tenant when supplied and drops anything older than the
+     * retention window. Returns a fresh array (safe for the caller to map).
+     */
+    recent(opts?: {
+        service?: string;
+        tenant?: string;
+    }): AnomalyRecord[];
+    /** Distinct services with at least one record in the retention window,
+     *  optionally tenant-scoped. */
+    recentServices(tenant?: string): string[];
+    /** Retention window in ms — surfaced so the API/UI can label the range. */
+    get windowMs(): number;
     /** Send the current buffer to the remote-write endpoint. Drops the
      *  buffer on success OR failure — history is best-effort. */
     flush(): Promise<void>;

package/dist/analysis/history.js

@@ -45,7 +45,14 @@ export class AnomalyHistory {
     maxBufferSize;
     requestTimeoutMs;
     fetchImpl;
+    retentionMs;
+    ringMax;
+    nowFn;
     buffer = [];
+    /** Bounded, time-windowed in-process tier of the sink — powers the
+     *  Health-tab sparkline. Captured on every record() regardless of
+     *  remote-write so the sparkline works out of the box. */
+    ring = [];
     timer;
     flushing = false;
     constructor(cfg = {}) {
@@ -56,6 +63,9 @@ export class AnomalyHistory {
         this.maxBufferSize = cfg.maxBufferSize ?? 500;
         this.requestTimeoutMs = cfg.requestTimeoutMs ?? 5_000;
         this.fetchImpl = cfg.fetchImpl ?? fetch;
+        this.retentionMs = cfg.retentionMs ?? 60 * 60 * 1000;
+        this.ringMax = cfg.ringMax ?? 5_000;
+        this.nowFn = cfg.now ?? Date.now;
     }
     /** Whether the history sink is enabled (URL configured). */
     isEnabled() {
@@ -84,9 +94,11 @@ export class AnomalyHistory {
         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. */
+    /** Add one anomaly. Always captured into the in-process ring (powers
+     *  the sparkline); additionally buffered for remote-write only when the
+     *  sink is enabled. Triggers a synchronous flush past maxBufferSize. */
     async record(entry) {
+        this.pushRing(entry);
         if (!this.isEnabled())
             return;
         this.buffer.push(entry);
@@ -94,6 +106,52 @@ export class AnomalyHistory {
             await this.flush().catch(() => undefined);
         }
     }
+    /** Append to the ring + evict anything outside the retention window or
+     *  beyond the hard cap. O(n) prune is fine — anomaly records are
+     *  infrequent and n is bounded by ringMax. */
+    pushRing(entry) {
+        this.ring.push(entry);
+        const cutoff = this.nowFn() - this.retentionMs;
+        this.ring = this.ring.filter((r) => {
+            const t = Date.parse(r.ts);
+            return Number.isFinite(t) && t >= cutoff;
+        });
+        if (this.ring.length > this.ringMax) {
+            this.ring = this.ring.slice(this.ring.length - this.ringMax);
+        }
+    }
+    /**
+     * Recent records from the in-process ring, oldest-first. Filters by
+     * service and/or tenant when supplied and drops anything older than the
+     * retention window. Returns a fresh array (safe for the caller to map).
+     */
+    recent(opts = {}) {
+        const cutoff = this.nowFn() - this.retentionMs;
+        return this.ring
+            .filter((r) => {
+            const t = Date.parse(r.ts);
+            if (!Number.isFinite(t) || t < cutoff)
+                return false;
+            if (opts.service && r.service !== opts.service)
+                return false;
+            if (opts.tenant && r.tenant !== opts.tenant)
+                return false;
+            return true;
+        })
+            .sort((a, b) => Date.parse(a.ts) - Date.parse(b.ts));
+    }
+    /** Distinct services with at least one record in the retention window,
+     *  optionally tenant-scoped. */
+    recentServices(tenant) {
+        const seen = new Set();
+        for (const r of this.recent({ tenant }))
+            seen.add(r.service);
+        return [...seen];
+    }
+    /** Retention window in ms — surfaced so the API/UI can label the range. */
+    get windowMs() {
+        return this.retentionMs;
+    }
     /** Send the current buffer to the remote-write endpoint. Drops the
      *  buffer on success OR failure — history is best-effort. */
     async flush() {

package/dist/analysis/history.test.js

@@ -71,6 +71,52 @@ test("flush: bearer token forwarded as Authorization header", async () => {
     await h.flush();
     assert.equal(captured.headers["authorization"], "Bearer tok-abc");
 });
+// --- Q21: in-process ring (Health-tab sparkline) ----------------------
+const NOW = Date.parse("2026-06-06T12:00:00.000Z");
+function at(msAgo) {
+    return new Date(NOW - msAgo).toISOString();
+}
+test("ring captures records even when remote-write is disabled", async () => {
+    const h = new AnomalyHistory({ now: () => NOW });
+    assert.equal(h.isEnabled(), false);
+    await h.record(entry({ ts: at(0), score: 0.5 }));
+    const recent = h.recent();
+    assert.equal(recent.length, 1);
+    assert.equal(recent[0].score, 0.5);
+    // ...but the remote-write buffer stays empty when disabled.
+    assert.equal(h.bufferSize(), 0);
+});
+test("recent: drops records outside the retention window", async () => {
+    const h = new AnomalyHistory({ now: () => NOW, retentionMs: 60 * 60 * 1000 });
+    await h.record(entry({ ts: at(30 * 60 * 1000) })); // 30m ago — kept
+    await h.record(entry({ ts: at(90 * 60 * 1000) })); // 90m ago — evicted on next push/prune
+    const recent = h.recent();
+    assert.equal(recent.length, 1);
+    assert.equal(recent[0].ts, at(30 * 60 * 1000));
+});
+test("recent: oldest-first and filterable by service + tenant", async () => {
+    const h = new AnomalyHistory({ now: () => NOW });
+    await h.record(entry({ ts: at(3000), service: "payment", tenant: "a", score: 0.1 }));
+    await h.record(entry({ ts: at(1000), service: "payment", tenant: "a", score: 0.3 }));
+    await h.record(entry({ ts: at(2000), service: "orders", tenant: "a", score: 0.2 }));
+    await h.record(entry({ ts: at(500), service: "payment", tenant: "b", score: 0.9 }));
+    const pay = h.recent({ service: "payment", tenant: "a" });
+    assert.deepEqual(pay.map((r) => r.score), [0.1, 0.3], "oldest-first, service+tenant filtered");
+    const tenantA = h.recentServices("a").sort();
+    assert.deepEqual(tenantA, ["orders", "payment"]);
+    assert.deepEqual(h.recentServices("b"), ["payment"]);
+});
+test("ring honours the hard cap (ringMax)", async () => {
+    const h = new AnomalyHistory({ now: () => NOW, ringMax: 3 });
+    for (let i = 0; i < 10; i++)
+        await h.record(entry({ ts: at(10_000 - i), score: i / 10 }));
+    const recent = h.recent();
+    assert.equal(recent.length, 3, "ring capped at ringMax");
+});
+test("windowMs surfaces the retention window", () => {
+    assert.equal(new AnomalyHistory({ retentionMs: 1234 }).windowMs, 1234);
+    assert.equal(new AnomalyHistory({}).windowMs, 60 * 60 * 1000);
+});
 test("flush: clears the buffer on success", async () => {
     const h = new AnomalyHistory({
         url: "https://tsdb/api/v1/write",

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

@@ -0,0 +1,61 @@
+import type { AuditEntry } from "../log.js";
+import type { AuditSink } from "./types.js";
+/** Minimal subset of the AWS SDK S3Client we depend on. */
+export interface S3ClientLike {
+    send(command: unknown): Promise<unknown>;
+}
+export interface S3SinkOptions {
+    /** Target bucket. Required. */
+    bucket: string;
+    /** Region — required for AWS, ignored by MinIO. Default us-east-1. */
+    region?: string;
+    /**
+     * Object key prefix. Default empty. The final key is
+     * `<prefix>/YYYY/MM/DD/HH/<minute>-<seqStart>-<seqEnd>.jsonl`.
+     * Trailing slash optional.
+     */
+    prefix?: string;
+    /**
+     * Override the AWS endpoint URL for S3-compatible backends
+     * (MinIO, R2, B2). Empty = use AWS regional endpoint.
+     */
+    endpoint?: string;
+    /** Force path-style addressing — required for MinIO + B2. */
+    forcePathStyle?: boolean;
+    /** Flush every N milliseconds. Default 60000 (1 minute). */
+    flushIntervalMs?: number;
+    /** Flush when buffer holds N entries. Default 1000. */
+    maxBufferSize?: number;
+    /** Optional path for unrecoverable batches. */
+    deadLetterFile?: string;
+    /** Inject a client for unit tests. */
+    client?: S3ClientLike;
+}
+export declare class S3Sink implements AuditSink {
+    readonly name = "s3";
+    private readonly bucket;
+    private readonly region;
+    private readonly prefix;
+    private readonly endpoint?;
+    private readonly forcePathStyle;
+    private readonly flushIntervalMs;
+    private readonly maxBufferSize;
+    private readonly deadLetterFile?;
+    private client;
+    private putCommand;
+    private sdkLoadError;
+    private buffer;
+    private flushTimer;
+    private writeQueue;
+    constructor(opts: S3SinkOptions);
+    /** Resolve the SDK lazily so the gateway still boots if @aws-sdk/client-s3
+     *  isn't installed. Called on the first flush attempt only. */
+    private ensureClient;
+    write(entry: AuditEntry): Promise<void>;
+    flush(): Promise<void>;
+    /** Stop the timer + flush remaining. Called on SIGTERM. */
+    shutdown(): Promise<void>;
+    private flushNow;
+    private buildKey;
+    private deadLetter;
+}

package/dist/audit/sinks/s3.js

@@ -0,0 +1,179 @@
+// S3Sink: ship audit entries to an S3-compatible object store
+// (AWS S3, MinIO, Cloudflare R2, Backblaze B2, Wasabi, …).
+//
+// Buffer audit entries in memory; every flush window (default 60 s)
+// or whenever the buffer crosses the cap (default 1000 entries),
+// concatenate as JSONL and PUT one object under
+// `<prefix>/YYYY/MM/DD/HH/<minute>-<seqStart>-<seqEnd>.jsonl`.
+//
+// Why per-minute rollups, not per-entry? S3 charges per PUT (5x per
+// LIST / 1x per GET). An audit-heavy gateway generates 100s of
+// entries/minute — per-entry PUT is wasteful on cost AND on SDK
+// concurrency. One PUT/min keeps the bill low and still lets the
+// operator scrape a minute-grained timeline in the storage console.
+//
+// Failures dead-letter to a local JSONL so a recovered S3 backend
+// can be replayed by an external tool. The on-disk audit chain stays
+// the authoritative master.
+import { appendFile } from "node:fs/promises";
+let _sdk = null;
+async function loadSdk() {
+    if (_sdk)
+        return _sdk;
+    // @aws-sdk/client-s3 is an optional runtime dependency — operators
+    // only pull it in when they enable this sink. The specifier is
+    // resolved at runtime so TypeScript doesn't require the types at
+    // build time (matches the AWS-connector lazy-load pattern from Q1).
+    const specifier = "@aws-sdk/client-s3";
+    const s3 = (await import(specifier));
+    _sdk = { S3Client: s3.S3Client, PutObjectCommand: s3.PutObjectCommand };
+    return _sdk;
+}
+export class S3Sink {
+    name = "s3";
+    bucket;
+    region;
+    prefix;
+    endpoint;
+    forcePathStyle;
+    flushIntervalMs;
+    maxBufferSize;
+    deadLetterFile;
+    client = null;
+    putCommand = null;
+    sdkLoadError = null;
+    buffer = [];
+    flushTimer = null;
+    writeQueue = Promise.resolve();
+    constructor(opts) {
+        if (!opts.bucket)
+            throw new Error("S3Sink: bucket is required");
+        this.bucket = opts.bucket;
+        this.region = opts.region ?? process.env.AWS_REGION ?? "us-east-1";
+        // Normalise to "prefix/" form (trailing slash) when non-empty so
+        // we don't ever build `<prefix>YYYY/...` with a missing slash.
+        const rawPrefix = (opts.prefix ?? "").replace(/^\/+|\/+$/g, "");
+        this.prefix = rawPrefix ? `${rawPrefix}/` : "";
+        this.endpoint = opts.endpoint || undefined;
+        this.forcePathStyle = opts.forcePathStyle ?? false;
+        this.flushIntervalMs = opts.flushIntervalMs ?? 60_000;
+        this.maxBufferSize = opts.maxBufferSize ?? 1_000;
+        this.deadLetterFile = opts.deadLetterFile;
+        if (opts.client) {
+            this.client = opts.client;
+            // Tests inject a fake client AND need PutObjectCommand to be
+            // construct-able as a plain class. We stub here so the
+            // command-pattern API surface still works.
+            const Stub = class {
+                input;
+                constructor(input) { this.input = input; }
+            };
+            Object.defineProperty(Stub, "name", { value: "PutObjectCommand" });
+            this.putCommand = Stub;
+        }
+    }
+    /** Resolve the SDK lazily so the gateway still boots if @aws-sdk/client-s3
+     *  isn't installed. Called on the first flush attempt only. */
+    async ensureClient() {
+        if (this.client && this.putCommand)
+            return true;
+        if (this.sdkLoadError)
+            return false;
+        try {
+            const sdk = await loadSdk();
+            const S3Client = sdk.S3Client;
+            this.client = new S3Client({
+                region: this.region,
+                endpoint: this.endpoint,
+                forcePathStyle: this.forcePathStyle,
+            });
+            this.putCommand = sdk.PutObjectCommand;
+            return true;
+        }
+        catch (err) {
+            this.sdkLoadError = err instanceof Error ? err.message : String(err);
+            console.warn("S3Sink: @aws-sdk/client-s3 not installed (%s) — entries will dead-letter", this.sdkLoadError);
+            return false;
+        }
+    }
+    async write(entry) {
+        this.buffer.push(entry);
+        if (!this.flushTimer && this.flushIntervalMs > 0) {
+            this.flushTimer = setInterval(() => { void this.flush(); }, this.flushIntervalMs);
+            if (this.flushTimer && typeof this.flushTimer.unref === "function") {
+                this.flushTimer.unref();
+            }
+        }
+        if (this.buffer.length >= this.maxBufferSize) {
+            // Buffer cap reached — flush in background, never block record().
+            this.writeQueue = this.writeQueue.then(() => this.flushNow());
+        }
+    }
+    async flush() {
+        this.writeQueue = this.writeQueue.then(() => this.flushNow());
+        await this.writeQueue;
+    }
+    /** Stop the timer + flush remaining. Called on SIGTERM. */
+    async shutdown() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        await this.flush();
+    }
+    // --- internals ----------------------------------------------------
+    async flushNow() {
+        if (this.buffer.length === 0)
+            return;
+        const batch = this.buffer.splice(0, this.buffer.length);
+        const ok = await this.ensureClient();
+        if (!ok) {
+            await this.deadLetter(batch);
+            return;
+        }
+        const body = batch.map((e) => JSON.stringify(e)).join("\n") + "\n";
+        const key = this.buildKey(batch);
+        try {
+            const cmd = new this.putCommand({
+                Bucket: this.bucket,
+                Key: key,
+                Body: body,
+                ContentType: "application/x-ndjson",
+                // Server-side encryption when running on AWS. MinIO + R2 + B2
+                // ignore the header gracefully.
+                ServerSideEncryption: "AES256",
+            });
+            await this.client.send(cmd);
+        }
+        catch (err) {
+            console.warn("S3Sink: PUT s3://%s/%s failed: %s — batch dead-letters", this.bucket, key, err instanceof Error ? err.message : String(err));
+            await this.deadLetter(batch);
+        }
+    }
+    buildKey(batch) {
+        // Derive the time bucket from the first entry's timestamp so a
+        // late-arriving entry stays grouped with its peers.
+        const t = new Date(batch[0]?.ts ?? new Date().toISOString());
+        const yyyy = String(t.getUTCFullYear());
+        const mm = String(t.getUTCMonth() + 1).padStart(2, "0");
+        const dd = String(t.getUTCDate()).padStart(2, "0");
+        const hh = String(t.getUTCHours()).padStart(2, "0");
+        const mi = String(t.getUTCMinutes()).padStart(2, "0");
+        const seqStart = batch[0]?.seq ?? 0;
+        const seqEnd = batch[batch.length - 1]?.seq ?? seqStart;
+        return `${this.prefix}${yyyy}/${mm}/${dd}/${hh}/${mi}-${seqStart}-${seqEnd}.jsonl`;
+    }
+    async deadLetter(batch) {
+        if (!this.deadLetterFile) {
+            console.warn("S3Sink: %d entries dropped (no deadLetterFile configured)", batch.length);
+            return;
+        }
+        try {
+            const body = batch.map((e) => JSON.stringify(e)).join("\n") + "\n";
+            await appendFile(this.deadLetterFile, body, "utf8");
+        }
+        catch (err) {
+            console.warn("S3Sink: DLQ write failed: %s", err instanceof Error ? err.message : String(err));
+        }
+    }
+}

package/dist/audit/sinks/s3.test.d.ts

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

package/dist/audit/sinks/s3.test.js

@@ -0,0 +1,175 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { S3Sink } from "./s3.js";
+function entry(seq, ts, action = "write") {
+    return {
+        seq,
+        ts,
+        actor: { sub: "alice@example.com", name: "alice" },
+        tenant: "default",
+        resource: "sources",
+        action,
+        method: "POST",
+        path: `/api/sources/s${seq}`,
+        status: 201,
+        ip: "10.0.0.7",
+        prevHash: "0".repeat(64),
+        hash: String(seq).padStart(64, "0"),
+    };
+}
+function fakeClient() {
+    const sent = [];
+    let throws = false;
+    const client = {
+        sent,
+        setThrow(v) { throws = v; },
+        async send(command) {
+            if (throws)
+                throw new Error("S3 unavailable (test)");
+            const input = command.input;
+            sent.push({ Bucket: input.Bucket, Key: input.Key, Body: input.Body });
+            return { $metadata: { httpStatusCode: 200 } };
+        },
+    };
+    return client;
+}
+test("constructor: bucket is required", () => {
+    assert.throws(() => new S3Sink({ bucket: "" }), /bucket is required/);
+});
+test("write+flush: one entry → one PUT with correct key shape", async () => {
+    const client = fakeClient();
+    const sink = new S3Sink({
+        bucket: "audit-bucket",
+        prefix: "omcp",
+        flushIntervalMs: 0,
+        client,
+    });
+    await sink.write(entry(1, "2026-06-06T15:23:00Z"));
+    await sink.flush();
+    assert.equal(client.sent.length, 1);
+    const put = client.sent[0];
+    assert.equal(put.Bucket, "audit-bucket");
+    assert.equal(put.Key, "omcp/2026/06/06/15/23-1-1.jsonl");
+    assert.equal(put.Body.trim().split("\n").length, 1);
+});
+test("multiple entries are batched into one PUT on flush", async () => {
+    const client = fakeClient();
+    const sink = new S3Sink({ bucket: "b", flushIntervalMs: 0, client });
+    await sink.write(entry(1, "2026-06-06T15:23:00Z"));
+    await sink.write(entry(2, "2026-06-06T15:23:01Z"));
+    await sink.write(entry(3, "2026-06-06T15:23:02Z"));
+    await sink.flush();
+    assert.equal(client.sent.length, 1);
+    const lines = client.sent[0].Body.trim().split("\n");
+    assert.equal(lines.length, 3);
+    // Key range reflects the seq span
+    assert.match(client.sent[0].Key, /23-1-3\.jsonl$/);
+});
+test("empty buffer flush is a no-op", async () => {
+    const client = fakeClient();
+    const sink = new S3Sink({ bucket: "b", flushIntervalMs: 0, client });
+    await sink.flush();
+    assert.equal(client.sent.length, 0);
+});
+test("maxBufferSize triggers an out-of-band flush", async () => {
+    const client = fakeClient();
+    const sink = new S3Sink({ bucket: "b", flushIntervalMs: 0, maxBufferSize: 2, client });
+    await sink.write(entry(1, "2026-06-06T15:23:00Z"));
+    await sink.write(entry(2, "2026-06-06T15:23:00Z"));
+    // The second write crosses the cap → background flush
+    await sink.flush();
+    assert.equal(client.sent.length, 1);
+});
+test("PUT failure dead-letters the batch", async () => {
+    const client = fakeClient();
+    client.setThrow(true);
+    const dlq = join(mkdtempSync(join(tmpdir(), "omcp-s3-dlq-")), "dlq.jsonl");
+    const sink = new S3Sink({
+        bucket: "b",
+        flushIntervalMs: 0,
+        client,
+        deadLetterFile: dlq,
+    });
+    await sink.write(entry(1, "2026-06-06T15:23:00Z"));
+    await sink.write(entry(2, "2026-06-06T15:23:01Z"));
+    await sink.flush();
+    // No successful PUT
+    assert.equal(client.sent.length, 0);
+    // DLQ file has both entries
+    const lines = readFileSync(dlq, "utf8").trim().split("\n");
+    assert.equal(lines.length, 2);
+    assert.match(lines[0], /"seq":1/);
+});
+test("missing SDK + no client → dead-letter (no throw)", async () => {
+    // Sink with neither an injected client nor the SDK installed.
+    // We can't really uninstall the SDK in tests, but constructing the
+    // sink without `client` AND without ever populating sdkLoadError
+    // exercises the load path. Validate that flush handles the "no
+    // client" state by relying on DLQ.
+    const dlq = join(mkdtempSync(join(tmpdir(), "omcp-s3-dlq2-")), "dlq.jsonl");
+    // Forcibly break the SDK loader by trying an obviously absent bucket
+    // path with a fake client whose `send` throws "MissingCredentials" —
+    // the deadLetter path catches it.
+    const sink = new S3Sink({
+        bucket: "b",
+        flushIntervalMs: 0,
+        deadLetterFile: dlq,
+        client: {
+            async send() { throw new Error("MissingCredentials"); },
+        },
+    });
+    await sink.write(entry(1, "2026-06-06T15:23:00Z"));
+    await sink.flush();
+    const lines = readFileSync(dlq, "utf8").trim().split("\n");
+    assert.equal(lines.length, 1);
+});
+test("prefix handles both with-trailing and without-trailing slash", async () => {
+    const c1 = fakeClient();
+    const s1 = new S3Sink({ bucket: "b", prefix: "audits", flushIntervalMs: 0, client: c1 });
+    await s1.write(entry(1, "2026-06-06T15:00:00Z"));
+    await s1.flush();
+    assert.match(c1.sent[0].Key, /^audits\/2026\//);
+    const c2 = fakeClient();
+    const s2 = new S3Sink({ bucket: "b", prefix: "/audits/", flushIntervalMs: 0, client: c2 });
+    await s2.write(entry(1, "2026-06-06T15:00:00Z"));
+    await s2.flush();
+    assert.match(c2.sent[0].Key, /^audits\/2026\//);
+    assert.doesNotMatch(c2.sent[0].Key, /^\/audits/);
+    const c3 = fakeClient();
+    const s3 = new S3Sink({ bucket: "b", flushIntervalMs: 0, client: c3 });
+    await s3.write(entry(1, "2026-06-06T15:00:00Z"));
+    await s3.flush();
+    // No prefix → key starts directly with YYYY
+    assert.match(c3.sent[0].Key, /^2026\//);
+});
+test("flush serialises — concurrent calls don't lose entries", async () => {
+    const client = fakeClient();
+    const sink = new S3Sink({ bucket: "b", flushIntervalMs: 0, client });
+    for (let i = 1; i <= 50; i++)
+        await sink.write(entry(i, "2026-06-06T15:00:00Z"));
+    // Multiple parallel flushes
+    await Promise.all([sink.flush(), sink.flush(), sink.flush()]);
+    // All 50 entries land in one (or at most a few) PUTs; total lines = 50
+    const allLines = client.sent.flatMap((p) => p.Body.trim().split("\n"));
+    assert.equal(allLines.length, 50);
+});
+test("shutdown stops the timer + flushes the remainder", async () => {
+    const client = fakeClient();
+    const sink = new S3Sink({ bucket: "b", flushIntervalMs: 1_000_000, client });
+    await sink.write(entry(1, "2026-06-06T15:00:00Z"));
+    await sink.write(entry(2, "2026-06-06T15:00:01Z"));
+    await sink.shutdown();
+    assert.equal(client.sent.length, 1);
+    assert.equal(client.sent[0].Body.trim().split("\n").length, 2);
+});
+test("uses entry's own ts for the key bucket (not wall-clock)", async () => {
+    const client = fakeClient();
+    const sink = new S3Sink({ bucket: "b", flushIntervalMs: 0, client });
+    // Entry from 5 minutes earlier — key must reflect THAT minute.
+    await sink.write(entry(1, "2026-06-06T15:18:00Z"));
+    await sink.flush();
+    assert.match(client.sent[0].Key, /15\/18-1-1\.jsonl$/);
+});

package/dist/auth/csrf.d.ts

@@ -13,6 +13,12 @@ export interface CsrfConfig {
     /** Set cookies with `Secure` flag. Default mirrors the existing
      *  session-cookie behaviour: only when the request is on https. */
     secureCookie: (req: Request) => boolean;
+    /** Optional predicate to exempt specific requests from CSRF entirely.
+     *  Used for unauthenticated browser-initiated POSTs that can't carry a
+     *  token by construction — e.g. CSP violation reports, which the browser
+     *  sends with no credentials and no custom headers. Keep this list
+     *  minimal: an exempt endpoint must be safe to accept cross-site. */
+    skip?: (req: Request) => boolean;
 }
 export declare function csrfBypassFromEnv(env?: NodeJS.ProcessEnv): boolean;
 /** Issue a fresh token cookie if the request doesn't already carry a

package/dist/auth/csrf.js

@@ -69,6 +69,10 @@ export function buildCsrfEnforcer(cfg) {
             next();
             return;
         }
+        if (cfg.skip?.(req)) {
+            next();
+            return;
+        }
         if (cfg.bypassBearer) {
             const auth = req.headers["authorization"];
             if (typeof auth === "string" && /^Bearer\s+/i.test(auth)) {