@thotischner/observability-mcp 3.0.1 → 3.1.1

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/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)) {

package/dist/auth/csrf.test.js

@@ -89,6 +89,28 @@ test("enforcer: bearer auth bypasses CSRF when bypassBearer=true", () => {
     });
     assert.equal(r.nexted, true);
 });
+test("enforcer: skip predicate exempts a matching request (no token needed)", () => {
+    // Mirror the production predicate, which checks BOTH req.path and
+    // req.originalUrl — under `app.use("/api", ...)` Express strips the
+    // mount prefix from req.path (→ "/csp-violations"), so originalUrl is
+    // what actually matches at runtime.
+    const skip = (r) => r.method === "POST" &&
+        (r.path === "/api/csp-violations" || (r.originalUrl || "").split("?")[0] === "/api/csp-violations");
+    const mw = buildCsrfEnforcer({ bypassBearer: false, secureCookie: () => false, skip });
+    // Mounted shape: path stripped to "/csp-violations", originalUrl intact.
+    const mounted = call(mw, { method: "POST", path: "/csp-violations", originalUrl: "/api/csp-violations", headers: {} });
+    assert.equal(mounted.nexted, true, "originalUrl match must exempt under the /api mount");
+    // Query string can't widen the match.
+    const withQuery = call(mw, { method: "POST", path: "/csp-violations", originalUrl: "/api/csp-violations?x=1", headers: {} });
+    assert.equal(withQuery.nexted, true);
+    // A different path is still enforced (rejected without a token).
+    const other = call(mw, { method: "POST", path: "/settings", originalUrl: "/api/settings", headers: {} });
+    assert.equal(other.nexted, false);
+    assert.equal(other.res.status_, 403);
+    // GET is exempt anyway (safe method) regardless of skip.
+    const get = call(mw, { method: "GET", path: "/settings", originalUrl: "/api/settings", headers: {} });
+    assert.equal(get.nexted, true);
+});
 test("enforcer: X-API-Key also bypasses when bypassBearer=true", () => {
     const mw = buildCsrfEnforcer(defaultCfg({ bypassBearer: true }));
     const r = call(mw, {

package/dist/auth/lockout.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Local-account lockout for the management-plane "basic" auth login.
+ *
+ * The per-IP rate limiter on /api/auth/login (20/min) blunts a noisy
+ * brute-force, but it's keyed on the source IP — a distributed attempt, or
+ * a slow drip under the IP cap, can still grind a single account's
+ * password. This adds a per-username failed-login counter with progressive
+ * backoff: after N failures inside a sliding window the account is
+ * temporarily locked, and each subsequent lock lasts longer
+ * (base · 2^(level-1), capped). A successful login clears the streak.
+ *
+ * State lives in the shared {@link SessionStore} so a Redis-backed
+ * deployment locks consistently across replicas (and self-cleans via TTL).
+ * The in-memory default keeps the single-process behaviour with no new dep.
+ *
+ * Lockout is tracked by the *submitted* username, whether or not it exists,
+ * so it can't be used as a user-enumeration oracle and a known username
+ * can't be singled out. Read-modify-write is best-effort under concurrency
+ * (matching the store's eventually-consistent contract) — the worst case is
+ * a couple of extra attempts slipping past the threshold, which the IP rate
+ * limiter still bounds. It is never a lockout bypass for the *locked* state:
+ * once `lockedUntil` is written, every replica that reads it honours it.
+ */
+import type { SessionStore } from "../transport/sessionStore.js";
+export interface LockoutConfig {
+    /** Consecutive failures within the window before a lock triggers. */
+    maxFailures: number;
+    /** Sliding window (seconds) over which failures accumulate. */
+    windowSeconds: number;
+    /** First lock duration (seconds). Doubles each subsequent lock. */
+    baseLockSeconds: number;
+    /** Upper bound on a single lock duration (seconds). */
+    maxLockSeconds: number;
+}
+export declare const DEFAULT_LOCKOUT_CONFIG: LockoutConfig;
+export interface LockoutStatus {
+    locked: boolean;
+    /** Seconds the caller must wait, when locked. */
+    retryAfterSeconds?: number;
+    /** Attempts left before a lock, when not locked. */
+    remainingAttempts?: number;
+}
+/** Resolve config from env, falling back to the defaults. */
+export declare function lockoutConfigFromEnv(env?: NodeJS.ProcessEnv): LockoutConfig;
+/** True when OMCP_AUTH_LOCKOUT_DISABLED is set to a truthy value. */
+export declare function lockoutDisabledFromEnv(env?: NodeJS.ProcessEnv): boolean;
+export declare class AccountLockout {
+    private readonly store;
+    private readonly cfg;
+    private readonly now;
+    /** TTL applied to every persisted entry so stale streaks self-clean. */
+    private readonly ttlSeconds;
+    constructor(store: SessionStore, cfg?: Partial<LockoutConfig>, now?: () => number);
+    private key;
+    /** Lock duration for a given (1-based) lock level, capped. */
+    private lockDuration;
+    /**
+     * Inspect lock state without mutating it. Call before verifying the
+     * password — a locked account should never reach the (expensive) hash
+     * comparison.
+     */
+    check(username: string): Promise<LockoutStatus>;
+    /** Failures still inside the sliding window (0 if the window lapsed). */
+    private activeFailures;
+    /**
+     * Record a failed login. Returns the resulting status — `locked: true`
+     * when this failure tripped (or fell inside) a lock.
+     */
+    recordFailure(username: string): Promise<LockoutStatus>;
+    /** Clear the streak on a successful login. Keeps no history. */
+    recordSuccess(username: string): Promise<void>;
+}

package/dist/auth/lockout.js

@@ -0,0 +1,134 @@
+/**
+ * Local-account lockout for the management-plane "basic" auth login.
+ *
+ * The per-IP rate limiter on /api/auth/login (20/min) blunts a noisy
+ * brute-force, but it's keyed on the source IP — a distributed attempt, or
+ * a slow drip under the IP cap, can still grind a single account's
+ * password. This adds a per-username failed-login counter with progressive
+ * backoff: after N failures inside a sliding window the account is
+ * temporarily locked, and each subsequent lock lasts longer
+ * (base · 2^(level-1), capped). A successful login clears the streak.
+ *
+ * State lives in the shared {@link SessionStore} so a Redis-backed
+ * deployment locks consistently across replicas (and self-cleans via TTL).
+ * The in-memory default keeps the single-process behaviour with no new dep.
+ *
+ * Lockout is tracked by the *submitted* username, whether or not it exists,
+ * so it can't be used as a user-enumeration oracle and a known username
+ * can't be singled out. Read-modify-write is best-effort under concurrency
+ * (matching the store's eventually-consistent contract) — the worst case is
+ * a couple of extra attempts slipping past the threshold, which the IP rate
+ * limiter still bounds. It is never a lockout bypass for the *locked* state:
+ * once `lockedUntil` is written, every replica that reads it honours it.
+ */
+export const DEFAULT_LOCKOUT_CONFIG = {
+    maxFailures: 5,
+    windowSeconds: 15 * 60,
+    baseLockSeconds: 60,
+    maxLockSeconds: 60 * 60,
+};
+function nowSeconds() {
+    return Math.floor(Date.now() / 1000);
+}
+/** Resolve config from env, falling back to the defaults. */
+export function lockoutConfigFromEnv(env = process.env) {
+    const num = (raw, fallback) => {
+        if (raw === undefined)
+            return fallback;
+        const n = Number(raw);
+        return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
+    };
+    return {
+        maxFailures: num(env.OMCP_AUTH_LOCKOUT_MAX_FAILURES, DEFAULT_LOCKOUT_CONFIG.maxFailures),
+        windowSeconds: num(env.OMCP_AUTH_LOCKOUT_WINDOW, DEFAULT_LOCKOUT_CONFIG.windowSeconds),
+        baseLockSeconds: num(env.OMCP_AUTH_LOCKOUT_BASE, DEFAULT_LOCKOUT_CONFIG.baseLockSeconds),
+        maxLockSeconds: num(env.OMCP_AUTH_LOCKOUT_MAX, DEFAULT_LOCKOUT_CONFIG.maxLockSeconds),
+    };
+}
+/** True when OMCP_AUTH_LOCKOUT_DISABLED is set to a truthy value. */
+export function lockoutDisabledFromEnv(env = process.env) {
+    const v = env.OMCP_AUTH_LOCKOUT_DISABLED?.trim().toLowerCase();
+    return v === "1" || v === "true" || v === "yes";
+}
+export class AccountLockout {
+    store;
+    cfg;
+    now;
+    /** TTL applied to every persisted entry so stale streaks self-clean. */
+    ttlSeconds;
+    constructor(store, cfg = {}, now = nowSeconds) {
+        this.store = store;
+        this.cfg = { ...DEFAULT_LOCKOUT_CONFIG, ...cfg };
+        this.now = now;
+        // Outlast both the streak window and the longest possible lock so an
+        // abandoned entry always expires, but a live lock never does early.
+        this.ttlSeconds = Math.max(this.cfg.windowSeconds, this.cfg.maxLockSeconds) + 60;
+    }
+    key(username) {
+        return `lockout:${username}`;
+    }
+    /** Lock duration for a given (1-based) lock level, capped. */
+    lockDuration(level) {
+        const exp = this.cfg.baseLockSeconds * Math.pow(2, Math.max(0, level - 1));
+        return Math.min(this.cfg.maxLockSeconds, Math.floor(exp));
+    }
+    /**
+     * Inspect lock state without mutating it. Call before verifying the
+     * password — a locked account should never reach the (expensive) hash
+     * comparison.
+     */
+    async check(username) {
+        const state = await this.store.get(this.key(username));
+        const now = this.now();
+        if (state?.lockedUntil && state.lockedUntil > now) {
+            return { locked: true, retryAfterSeconds: state.lockedUntil - now };
+        }
+        const failures = this.activeFailures(state, now);
+        return { locked: false, remainingAttempts: Math.max(0, this.cfg.maxFailures - failures) };
+    }
+    /** Failures still inside the sliding window (0 if the window lapsed). */
+    activeFailures(state, now) {
+        if (!state)
+            return 0;
+        if (now - state.firstFailureAt > this.cfg.windowSeconds)
+            return 0;
+        return state.failures;
+    }
+    /**
+     * Record a failed login. Returns the resulting status — `locked: true`
+     * when this failure tripped (or fell inside) a lock.
+     */
+    async recordFailure(username) {
+        const k = this.key(username);
+        const now = this.now();
+        const prev = await this.store.get(k);
+        // If an existing lock is still active, just report it — don't extend
+        // it on every blocked attempt (that would let an attacker grow the
+        // legitimate user's lock unboundedly).
+        if (prev?.lockedUntil && prev.lockedUntil > now) {
+            return { locked: true, retryAfterSeconds: prev.lockedUntil - now };
+        }
+        // Continue the streak only if the window is still open; otherwise reset.
+        const windowOpen = prev && now - prev.firstFailureAt <= this.cfg.windowSeconds;
+        const next = windowOpen
+            ? { ...prev, failures: prev.failures + 1 }
+            : { failures: 1, firstFailureAt: now, lockLevel: prev?.lockLevel ?? 0 };
+        if (next.failures >= this.cfg.maxFailures) {
+            // Trip a lock: escalate the level, set the deadline, reset the
+            // counter so the next batch of failures earns a longer lock.
+            next.lockLevel += 1;
+            const duration = this.lockDuration(next.lockLevel);
+            next.lockedUntil = now + duration;
+            next.failures = 0;
+            next.firstFailureAt = now;
+            await this.store.setEx(k, this.ttlSeconds, next);
+            return { locked: true, retryAfterSeconds: duration };
+        }
+        await this.store.setEx(k, this.ttlSeconds, next);
+        return { locked: false, remainingAttempts: this.cfg.maxFailures - next.failures };
+    }
+    /** Clear the streak on a successful login. Keeps no history. */
+    async recordSuccess(username) {
+        await this.store.del(this.key(username));
+    }
+}

package/dist/auth/lockout.test.d.ts

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

package/dist/auth/lockout.test.js

@@ -0,0 +1,133 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { InMemorySessionStore } from "../transport/sessionStore.js";
+import { AccountLockout, lockoutConfigFromEnv, lockoutDisabledFromEnv, DEFAULT_LOCKOUT_CONFIG, } from "./lockout.js";
+const cfg = { maxFailures: 3, windowSeconds: 100, baseLockSeconds: 60, maxLockSeconds: 600 };
+function mk(now) {
+    return new AccountLockout(new InMemorySessionStore(), cfg, () => now.t);
+}
+test("unknown account is not locked and reports full remaining attempts", async () => {
+    const now = { t: 1000 };
+    const lock = mk(now);
+    const status = await lock.check("alice");
+    assert.equal(status.locked, false);
+    assert.equal(status.remainingAttempts, 3);
+});
+test("failures below the threshold decrement remaining attempts", async () => {
+    const now = { t: 1000 };
+    const lock = mk(now);
+    assert.deepEqual(await lock.recordFailure("alice"), { locked: false, remainingAttempts: 2 });
+    assert.deepEqual(await lock.recordFailure("alice"), { locked: false, remainingAttempts: 1 });
+});
+test("the Nth failure trips a lock with the base duration", async () => {
+    const now = { t: 1000 };
+    const lock = mk(now);
+    await lock.recordFailure("alice");
+    await lock.recordFailure("alice");
+    const tripped = await lock.recordFailure("alice");
+    assert.equal(tripped.locked, true);
+    assert.equal(tripped.retryAfterSeconds, 60);
+    // check() reflects the lock and counts down with the clock.
+    now.t += 10;
+    const status = await lock.check("alice");
+    assert.equal(status.locked, true);
+    assert.equal(status.retryAfterSeconds, 50);
+});
+test("a lapsed lock clears and lets attempts resume", async () => {
+    const now = { t: 1000 };
+    const lock = mk(now);
+    await lock.recordFailure("alice");
+    await lock.recordFailure("alice");
+    await lock.recordFailure("alice"); // locked for 60s
+    now.t += 61;
+    const status = await lock.check("alice");
+    assert.equal(status.locked, false);
+});
+test("progressive backoff doubles each lock, capped at maxLockSeconds", async () => {
+    const now = { t: 0 };
+    const lock = mk(now);
+    async function tripLock() {
+        let last = { locked: false };
+        for (let i = 0; i < cfg.maxFailures; i++)
+            last = await lock.recordFailure("bob");
+        return last.retryAfterSeconds;
+    }
+    // Level 1 → 60, level 2 → 120, level 3 → 240, level 4 → 480, level 5 → 600 (capped).
+    const durations = [];
+    for (let lvl = 0; lvl < 5; lvl++) {
+        const d = await tripLock();
+        durations.push(d);
+        now.t += d + 1; // wait out the lock before the next streak
+    }
+    assert.deepEqual(durations, [60, 120, 240, 480, 600]);
+});
+test("a blocked attempt during an active lock does not extend it", async () => {
+    const now = { t: 1000 };
+    const lock = mk(now);
+    await lock.recordFailure("alice");
+    await lock.recordFailure("alice");
+    const tripped = await lock.recordFailure("alice"); // locked 60s at t=1000
+    assert.equal(tripped.retryAfterSeconds, 60);
+    now.t += 30;
+    const blocked = await lock.recordFailure("alice"); // still locked, t=1030
+    assert.equal(blocked.locked, true);
+    // Deadline unchanged (1060) → 30s left, NOT re-extended to 60.
+    assert.equal(blocked.retryAfterSeconds, 30);
+});
+test("failures outside the window reset the streak", async () => {
+    const now = { t: 1000 };
+    const lock = mk(now);
+    await lock.recordFailure("alice"); // failures=1, firstFailureAt=1000
+    await lock.recordFailure("alice"); // failures=2
+    now.t += cfg.windowSeconds + 1; // window lapsed
+    const status = await lock.recordFailure("alice"); // resets to failures=1
+    assert.equal(status.locked, false);
+    assert.equal(status.remainingAttempts, 2);
+});
+test("recordSuccess clears the streak", async () => {
+    const now = { t: 1000 };
+    const lock = mk(now);
+    await lock.recordFailure("alice");
+    await lock.recordFailure("alice");
+    await lock.recordSuccess("alice");
+    const status = await lock.check("alice");
+    assert.equal(status.locked, false);
+    assert.equal(status.remainingAttempts, 3);
+});
+test("lockout is tracked per username — one account's lock doesn't touch another", async () => {
+    const now = { t: 1000 };
+    const lock = mk(now);
+    await lock.recordFailure("alice");
+    await lock.recordFailure("alice");
+    await lock.recordFailure("alice"); // alice locked
+    assert.equal((await lock.check("alice")).locked, true);
+    assert.equal((await lock.check("bob")).locked, false);
+    assert.equal((await lock.check("bob")).remainingAttempts, 3);
+});
+test("state persists with a TTL so it self-cleans", async () => {
+    const store = new InMemorySessionStore();
+    const now = { t: 1000 };
+    const lock = new AccountLockout(store, cfg, () => now.t);
+    await lock.recordFailure("alice");
+    // One key written under the lockout: prefix.
+    const keys = await store.keys("lockout:");
+    assert.deepEqual(keys, ["lockout:alice"]);
+});
+test("lockoutConfigFromEnv parses overrides and falls back on bad input", () => {
+    const parsed = lockoutConfigFromEnv({
+        OMCP_AUTH_LOCKOUT_MAX_FAILURES: "10",
+        OMCP_AUTH_LOCKOUT_WINDOW: "300",
+        OMCP_AUTH_LOCKOUT_BASE: "nonsense",
+        OMCP_AUTH_LOCKOUT_MAX: "-5",
+    });
+    assert.equal(parsed.maxFailures, 10);
+    assert.equal(parsed.windowSeconds, 300);
+    assert.equal(parsed.baseLockSeconds, DEFAULT_LOCKOUT_CONFIG.baseLockSeconds); // bad → default
+    assert.equal(parsed.maxLockSeconds, DEFAULT_LOCKOUT_CONFIG.maxLockSeconds); // negative → default
+});
+test("lockoutDisabledFromEnv recognises truthy values", () => {
+    assert.equal(lockoutDisabledFromEnv({ OMCP_AUTH_LOCKOUT_DISABLED: "true" }), true);
+    assert.equal(lockoutDisabledFromEnv({ OMCP_AUTH_LOCKOUT_DISABLED: "1" }), true);
+    assert.equal(lockoutDisabledFromEnv({ OMCP_AUTH_LOCKOUT_DISABLED: "no" }), false);
+    assert.equal(lockoutDisabledFromEnv({}), false);
+});

package/dist/auth/middleware.d.ts

@@ -14,6 +14,7 @@
 import type { Request, RequestHandler } from "express";
 import { type SessionPayload, type SessionConfig } from "./session.js";
 import type { OidcRuntime } from "./oidc/runtime.js";
+import type { RevocationStore } from "./revocation.js";
 export type AuthMode = "anonymous" | "basic" | "oidc";
 export interface AuthRuntime {
     mode: AuthMode;
@@ -30,6 +31,10 @@ export interface AuthRuntime {
      *  runtime coupling — middleware.ts still doesn't depend on the
      *  OIDC sub-module's node:crypto path. */
     oidc?: OidcRuntime;
+    /** Session revocation blocklist. Present in basic / oidc mode; the
+     *  session attacher consults it on every request so a revoked but
+     *  not-yet-expired cookie is treated as logged out. */
+    revocation?: RevocationStore;
 }
 export interface AuthedRequest extends Request {
     session?: SessionPayload;

package/dist/auth/middleware.js

@@ -34,8 +34,13 @@ export function buildSessionAttacher(runtime) {
         // branch decides whether the check runs.
         const raw = readCookie(req.headers.cookie || "");
         const payload = verifySession(raw, sessionCfg);
-        if (payload)
+        // A valid signature is necessary but not sufficient: a session whose
+        // sid (or whose subject, before the revocation cutoff) is on the
+        // blocklist is treated as absent. isRevoked is a synchronous in-memory
+        // lookup, so this stays a no-await hot path.
+        if (payload && !runtime.revocation?.isRevoked(payload)) {
             req.session = payload;
+        }
         next();
     };
 }