@thotischner/observability-mcp 1.8.1 → 3.0.1

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

@@ -0,0 +1,162 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { WebhookSink } from "./webhook.js";
+function sampleEntry(seq = 1) {
+    return {
+        ts: "2026-06-05T20:00:00.000Z",
+        seq,
+        actor: { sub: "alice", name: "alice" },
+        tenant: "default",
+        resource: "sources",
+        action: "write",
+        method: "POST",
+        path: "/api/sources",
+        status: 200,
+        prevHash: "0".repeat(64),
+        hash: "ff".repeat(32),
+    };
+}
+function tmpDLQ() {
+    return join(mkdtempSync(join(tmpdir(), "webhook-dlq-")), "dlq.jsonl");
+}
+function fakeFetchSequence(statuses) {
+    let i = 0;
+    const calls = { count: 0 };
+    const fetchImpl = (async () => {
+        calls.count++;
+        const next = statuses[Math.min(i, statuses.length - 1)];
+        i++;
+        return {
+            ok: next.ok,
+            status: next.status ?? (next.ok ? 200 : 500),
+            statusText: next.ok ? "OK" : "Server Error",
+            text: async () => next.text ?? "",
+        };
+    });
+    return { fetchImpl, calls };
+}
+test("WebhookSink: happy path POSTs once and flushes cleanly", async () => {
+    const { fetchImpl, calls } = fakeFetchSequence([{ ok: true }]);
+    const sink = new WebhookSink({
+        url: "https://example.com/audit",
+        fetchImpl,
+        sleepImpl: async () => undefined,
+    });
+    await sink.write(sampleEntry());
+    await sink.flush();
+    assert.equal(calls.count, 1);
+});
+test("WebhookSink: retries with backoff on 500, succeeds on attempt 3", async () => {
+    const { fetchImpl, calls } = fakeFetchSequence([
+        { ok: false, status: 500 },
+        { ok: false, status: 503 },
+        { ok: true },
+    ]);
+    let sleeps = 0;
+    const sink = new WebhookSink({
+        url: "https://example.com/audit",
+        fetchImpl,
+        sleepImpl: async () => {
+            sleeps++;
+        },
+        initialBackoffMs: 10,
+        maxBackoffMs: 100,
+        maxAttempts: 5,
+    });
+    await sink.write(sampleEntry());
+    await sink.flush();
+    assert.equal(calls.count, 3);
+    assert.equal(sleeps, 2, "slept once between each failed attempt and the next");
+});
+test("WebhookSink: exhausts retries and writes to DLQ", async () => {
+    const { fetchImpl, calls } = fakeFetchSequence([{ ok: false, status: 500 }]);
+    const dlq = tmpDLQ();
+    const sink = new WebhookSink({
+        url: "https://example.com/audit",
+        fetchImpl,
+        sleepImpl: async () => undefined,
+        initialBackoffMs: 1,
+        maxAttempts: 3,
+        deadLetterFile: dlq,
+    });
+    await sink.write(sampleEntry(42));
+    await sink.flush();
+    assert.equal(calls.count, 3, "tried maxAttempts times");
+    assert.ok(existsSync(dlq), "DLQ file written");
+    const written = readFileSync(dlq, "utf8");
+    assert.match(written, /"seq":42/);
+});
+test("WebhookSink: write() does not throw even when underlying request fails", async () => {
+    const fetchImpl = (async () => {
+        throw new Error("network down");
+    });
+    const sink = new WebhookSink({
+        url: "https://example.com/audit",
+        fetchImpl,
+        sleepImpl: async () => undefined,
+        maxAttempts: 2,
+        initialBackoffMs: 1,
+    });
+    // The contract: write() returns successfully (does NOT throw) even
+    // when delivery fails — the failure is logged and DLQ-handled.
+    await assert.doesNotReject(async () => {
+        await sink.write(sampleEntry());
+        await sink.flush();
+    });
+});
+test("WebhookSink: bearer token forwarded as Authorization header", async () => {
+    let seenAuth;
+    const fetchImpl = (async (_url, init) => {
+        const headers = init.headers;
+        seenAuth = headers["authorization"];
+        return { ok: true, status: 200, statusText: "OK", text: async () => "" };
+    });
+    const sink = new WebhookSink({
+        url: "https://example.com/audit",
+        token: "secret-abc",
+        fetchImpl,
+        sleepImpl: async () => undefined,
+    });
+    await sink.write(sampleEntry());
+    await sink.flush();
+    assert.equal(seenAuth, "Bearer secret-abc");
+});
+test("WebhookSink: write order is preserved across retries (serialized queue)", async () => {
+    const seen = [];
+    let nextOk = false;
+    const fetchImpl = (async (_url, init) => {
+        const body = JSON.parse(init.body);
+        seen.push(body.seq);
+        const wasOk = nextOk;
+        nextOk = !wasOk; // alternate: first fails, second ok, etc.
+        return {
+            ok: wasOk,
+            status: wasOk ? 200 : 500,
+            statusText: "x",
+            text: async () => "",
+        };
+    });
+    const sink = new WebhookSink({
+        url: "https://example.com/audit",
+        fetchImpl,
+        sleepImpl: async () => undefined,
+        initialBackoffMs: 1,
+        maxAttempts: 4,
+    });
+    // Fire two writes concurrently; they must be delivered in order
+    // because the internal queue serializes them.
+    const p1 = sink.write(sampleEntry(1));
+    const p2 = sink.write(sampleEntry(2));
+    await Promise.all([p1, p2]);
+    await sink.flush();
+    // First entry's POSTs should all precede the second entry's POSTs.
+    const firstIdx = seen.indexOf(1);
+    const secondIdx = seen.indexOf(2);
+    assert.ok(firstIdx >= 0 && secondIdx > firstIdx, `order broken: ${seen.join(",")}`);
+});
+test("WebhookSink: throws on missing url", () => {
+    assert.throws(() => new WebhookSink({ url: "" }), /url is required/);
+});

package/dist/auth/credentials.d.ts

@@ -21,6 +21,13 @@
  *                  # land in the "default" tenant — identical to the
  *                  # pre-E7 single-namespace world. See docs/tenancy.md
  *                  # (slice 5) for the cross-cutting model.
+ *   OMCP_KEY_PRODUCTS="agent=ops-bundle;ci=dev-bundle"
+ *                  # optional per-key Product binding. When set, the
+ *                  # /mcp tools/list response is filtered to the named
+ *                  # Product's `tools` allow-list (Product without a
+ *                  # tools list = no restriction). Unlisted keys see
+ *                  # every registered tool — back-compat with the
+ *                  # pre-Products world. See docs/products.md.
  *
  * Rich role-based access control (tools/services/lookback/read-only, the
  * full governance object) is intentionally NOT here — this is only the
@@ -37,6 +44,10 @@ export interface Credential {
     bypassRedaction?: boolean;
     /** Tenant this credential belongs to. Omitted → DEFAULT_TENANT. */
     tenant?: string;
+    /** Product id this credential is bound to. When set, /mcp tools/list
+     *  is filtered to the Product's `tools` allow-list. Resolved against
+     *  the credential's tenant so cross-tenant Products don't leak. */
+    productId?: string;
 }
 /** Parse credentials from env. Returns an empty list when unconfigured. */
 export declare function loadCredentials(env?: NodeJS.ProcessEnv): Credential[];

package/dist/auth/credentials.js

@@ -21,6 +21,13 @@
  *                  # land in the "default" tenant — identical to the
  *                  # pre-E7 single-namespace world. See docs/tenancy.md
  *                  # (slice 5) for the cross-cutting model.
+ *   OMCP_KEY_PRODUCTS="agent=ops-bundle;ci=dev-bundle"
+ *                  # optional per-key Product binding. When set, the
+ *                  # /mcp tools/list response is filtered to the named
+ *                  # Product's `tools` allow-list (Product without a
+ *                  # tools list = no restriction). Unlisted keys see
+ *                  # every registered tool — back-compat with the
+ *                  # pre-Products world. See docs/products.md.
  *
  * Rich role-based access control (tools/services/lookback/read-only, the
  * full governance object) is intentionally NOT here — this is only the
@@ -39,6 +46,24 @@ function parseKeySources(raw) {
     }
     return m;
 }
+/** Parse OMCP_KEY_PRODUCTS — `name=productId;name2=productId2`. Same
+ *  shape as parseKeyTenants (single id per credential — Products are
+ *  bundles, not bundles-of-bundles). */
+function parseKeyProducts(raw) {
+    const m = new Map();
+    if (!raw)
+        return m;
+    for (const entry of raw.split(";").map((s) => s.trim()).filter(Boolean)) {
+        const eq = entry.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const name = entry.slice(0, eq).trim();
+        const productId = entry.slice(eq + 1).trim();
+        if (name && productId)
+            m.set(name, productId);
+    }
+    return m;
+}
 function parseBypassSet(raw) {
     if (!raw)
         return new Set();
@@ -52,6 +77,7 @@ export function loadCredentials(env = process.env) {
     const keySources = parseKeySources(env.OMCP_KEY_SOURCES);
     const bypassNames = parseBypassSet(env.OMCP_KEY_BYPASS_REDACTION);
     const keyTenants = parseKeyTenants(env.OMCP_KEY_TENANTS);
+    const keyProducts = parseKeyProducts(env.OMCP_KEY_PRODUCTS);
     const creds = [];
     for (const part of raw.split(",").map((s) => s.trim()).filter(Boolean)) {
         const idx = part.indexOf(":");
@@ -65,6 +91,7 @@ export function loadCredentials(env = process.env) {
             allowedSources: keySources.get(name),
             bypassRedaction: bypassNames.has(name) || undefined,
             tenant: keyTenants.get(name) || undefined,
+            productId: keyProducts.get(name) || undefined,
         });
     }
     return creds;

package/dist/auth/credentials.test.js

@@ -11,7 +11,7 @@ describe("single-tenant auth primitive", () => {
     it("parses name:token and bare token", () => {
         const creds = loadCredentials({ OMCP_API_KEYS: "ci:tok_abc, tok_bare " });
         assert.equal(creds.length, 2);
-        assert.deepEqual(creds[0], { name: "ci", token: "tok_abc", allowedSources: undefined, bypassRedaction: undefined, tenant: undefined });
+        assert.deepEqual(creds[0], { name: "ci", token: "tok_abc", allowedSources: undefined, bypassRedaction: undefined, tenant: undefined, productId: undefined });
         assert.equal(creds[1].name, "key");
         assert.equal(creds[1].token, "tok_bare");
     });
@@ -48,6 +48,26 @@ describe("single-tenant auth primitive", () => {
         assert.equal(creds.find((c) => c.name === "ci")?.tenant, "bigcorp", "lowercased");
         assert.equal(creds.find((c) => c.name === "nobody")?.tenant, undefined);
     });
+    it("parses OMCP_KEY_PRODUCTS → assigns productId to named keys; unlisted stays undefined", () => {
+        const creds = loadCredentials({
+            OMCP_API_KEYS: "agent:tok1,ci:tok2,nobody:tok3",
+            OMCP_KEY_PRODUCTS: "agent=ops-bundle;ci=dev-bundle",
+        });
+        assert.equal(creds.find((c) => c.name === "agent")?.productId, "ops-bundle");
+        assert.equal(creds.find((c) => c.name === "ci")?.productId, "dev-bundle");
+        assert.equal(creds.find((c) => c.name === "nobody")?.productId, undefined);
+    });
+    it("OMCP_KEY_PRODUCTS — malformed entries (no =, empty value) silently skipped", () => {
+        const creds = loadCredentials({
+            OMCP_API_KEYS: "agent:tok1,ci:tok2,x:tok3",
+            // "noeq" lacks "=" → skip; "ci=" has empty value → skip;
+            // "agent=ops" parses cleanly.
+            OMCP_KEY_PRODUCTS: "agent=ops;noeq;ci=;x=dev",
+        });
+        assert.equal(creds.find((c) => c.name === "agent")?.productId, "ops");
+        assert.equal(creds.find((c) => c.name === "ci")?.productId, undefined);
+        assert.equal(creds.find((c) => c.name === "x")?.productId, "dev");
+    });
     it("extractToken handles Bearer and X-API-Key", () => {
         assert.equal(extractToken({ authorization: "Bearer abc" }), "abc");
         assert.equal(extractToken({ authorization: "bearer  xyz " }), "xyz");

package/dist/auth/csrf.d.ts

@@ -0,0 +1,26 @@
+import type { Request, Response, NextFunction } from "express";
+export declare const CSRF_COOKIE = "omcp-csrf";
+export declare const CSRF_HEADER = "x-csrf-token";
+export declare const CSRF_TOKEN_BYTES = 32;
+export declare function newCsrfToken(): string;
+export interface CsrfConfig {
+    /** Skip protection when an Authorization: Bearer header is present.
+     *  Default true — bearer-token clients are non-browser by
+     *  definition and cannot carry cookies, so they can't be a
+     *  confused-deputy target. Set false to require CSRF on every
+     *  state-changing call regardless of auth method. */
+    bypassBearer: boolean;
+    /** Set cookies with `Secure` flag. Default mirrors the existing
+     *  session-cookie behaviour: only when the request is on https. */
+    secureCookie: (req: Request) => boolean;
+}
+export declare function csrfBypassFromEnv(env?: NodeJS.ProcessEnv): boolean;
+/** Issue a fresh token cookie if the request doesn't already carry a
+ *  valid one. The handler runs as a top-of-pipe middleware so every
+ *  rendered page picks up a token the SPA can echo back. */
+export declare function buildCsrfIssuer(cfg: CsrfConfig): (req: Request, res: Response, next: NextFunction) => void;
+/** Reject state-changing requests that don't carry a matching
+ *  X-CSRF-Token. Safe methods (GET/HEAD/OPTIONS) and bearer-auth
+ *  requests (when bypassBearer is on) flow through. */
+export declare function buildCsrfEnforcer(cfg: CsrfConfig): (req: Request, res: Response, next: NextFunction) => void;
+export declare function constantTimeStringEquals(a: string, b: string): boolean;

package/dist/auth/csrf.js

@@ -0,0 +1,128 @@
+// CSRF protection for the SPA — double-submit cookie pattern.
+//
+// The threat model the gateway protects against:
+//   - A browser session that has already authenticated against the
+//     SPA (carrying a session cookie) cannot have its credential
+//     borrowed by a third-party site to mutate state via a hidden
+//     form/XHR. The third-party site cannot read the CSRF cookie,
+//     so it cannot echo the token back in the X-CSRF-Token header,
+//     so the gateway rejects the request.
+//
+// The protection is intentionally narrow:
+//   - Bearer-token API clients (CI, agents, MCP clients) cannot
+//     set cookies and would never carry one. They bypass CSRF via
+//     OMCP_CSRF_BYPASS_BEARER=true (default ON since bearer auth
+//     is itself proof of intent — there's no browser confused-deputy
+//     scenario with a static API token in an Authorization header).
+//   - The /mcp endpoint is bearer-only in practice; the SPA only
+//     mutates state via /api/*.
+//
+// Token shape:
+//   - 32 random bytes, base64url encoded.
+//   - Issued lazily: every authenticated SPA page render that lacks
+//     a valid omcp-csrf cookie gets a fresh one.
+//   - Server-side validation: header X-CSRF-Token MUST equal cookie
+//     omcp-csrf on any state-changing /api/* request.
+import { randomBytes, timingSafeEqual } from "node:crypto";
+export const CSRF_COOKIE = "omcp-csrf";
+export const CSRF_HEADER = "x-csrf-token";
+export const CSRF_TOKEN_BYTES = 32;
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+export function newCsrfToken() {
+    return randomBytes(CSRF_TOKEN_BYTES).toString("base64url");
+}
+export function csrfBypassFromEnv(env = process.env) {
+    // Default ON; only the literal opt-out values disable it.
+    return !/^(0|false|no|off)$/i.test(env.OMCP_CSRF_BYPASS_BEARER ?? "true");
+}
+/** Issue a fresh token cookie if the request doesn't already carry a
+ *  valid one. The handler runs as a top-of-pipe middleware so every
+ *  rendered page picks up a token the SPA can echo back. */
+export function buildCsrfIssuer(cfg) {
+    return (req, res, next) => {
+        const existing = readCookie(req, CSRF_COOKIE);
+        if (!existing) {
+            const token = newCsrfToken();
+            const flags = [
+                `${CSRF_COOKIE}=${token}`,
+                "Path=/",
+                "SameSite=Lax",
+                // Intentionally NOT HttpOnly — the SPA's fetch wrapper
+                // needs to read this cookie to echo it back in
+                // X-CSRF-Token. That's the whole point of double-submit:
+                // the value isn't a secret, the proof is "you can read
+                // this cookie from your own origin".
+            ];
+            if (cfg.secureCookie(req))
+                flags.push("Secure");
+            appendSetCookie(res, flags.join("; "));
+        }
+        next();
+    };
+}
+/** Reject state-changing requests that don't carry a matching
+ *  X-CSRF-Token. Safe methods (GET/HEAD/OPTIONS) and bearer-auth
+ *  requests (when bypassBearer is on) flow through. */
+export function buildCsrfEnforcer(cfg) {
+    return (req, res, next) => {
+        if (SAFE_METHODS.has(req.method.toUpperCase())) {
+            next();
+            return;
+        }
+        if (cfg.bypassBearer) {
+            const auth = req.headers["authorization"];
+            if (typeof auth === "string" && /^Bearer\s+/i.test(auth)) {
+                next();
+                return;
+            }
+            // Also bypass if X-API-Key is set (matches /mcp's accepted shapes).
+            if (req.headers["x-api-key"]) {
+                next();
+                return;
+            }
+        }
+        const headerToken = req.headers[CSRF_HEADER];
+        const cookieToken = readCookie(req, CSRF_COOKIE);
+        if (typeof headerToken !== "string" ||
+            typeof cookieToken !== "string" ||
+            !constantTimeStringEquals(headerToken, cookieToken)) {
+            res
+                .status(403)
+                .json({
+                error: "csrf_token_mismatch",
+                message: "X-CSRF-Token header is missing or does not match the omcp-csrf cookie",
+            });
+            return;
+        }
+        next();
+    };
+}
+function readCookie(req, name) {
+    const raw = req.headers["cookie"];
+    if (typeof raw !== "string")
+        return undefined;
+    for (const part of raw.split(";")) {
+        const i = part.indexOf("=");
+        if (i < 0)
+            continue;
+        const k = part.slice(0, i).trim();
+        if (k === name)
+            return decodeURIComponent(part.slice(i + 1).trim());
+    }
+    return undefined;
+}
+function appendSetCookie(res, value) {
+    const existing = res.getHeader("Set-Cookie");
+    if (!existing) {
+        res.setHeader("Set-Cookie", value);
+        return;
+    }
+    res.setHeader("Set-Cookie", Array.isArray(existing) ? [...existing, value] : [String(existing), value]);
+}
+export function constantTimeStringEquals(a, b) {
+    if (a.length !== b.length)
+        return false;
+    const aBuf = Buffer.from(a);
+    const bBuf = Buffer.from(b);
+    return timingSafeEqual(aBuf, bBuf);
+}

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

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

package/dist/auth/csrf.test.js

@@ -0,0 +1,143 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import { buildCsrfIssuer, buildCsrfEnforcer, newCsrfToken, csrfBypassFromEnv, constantTimeStringEquals, CSRF_COOKIE, CSRF_HEADER, } from "./csrf.js";
+class MockRes extends EventEmitter {
+    status_ = 200;
+    headers = {};
+    body;
+    status(code) {
+        this.status_ = code;
+        return this;
+    }
+    json(body) {
+        this.body = body;
+        return this;
+    }
+    setHeader(name, value) {
+        this.headers[name] = value;
+    }
+    getHeader(name) {
+        return this.headers[name];
+    }
+}
+function call(mw, req) {
+    const res = new MockRes();
+    let nexted = false;
+    mw(req, res, () => {
+        nexted = true;
+    });
+    return { res, nexted };
+}
+function defaultCfg(overrides = {}) {
+    return {
+        bypassBearer: overrides.bypassBearer ?? true,
+        secureCookie: () => false,
+    };
+}
+test("newCsrfToken: returns base64url, 32-byte (43-44 char) string", () => {
+    const t = newCsrfToken();
+    assert.match(t, /^[A-Za-z0-9_-]+$/);
+    assert.ok(t.length >= 42 && t.length <= 44, `unexpected length ${t.length}`);
+    assert.notEqual(newCsrfToken(), newCsrfToken(), "tokens must differ");
+});
+test("constantTimeStringEquals: matches equal, rejects different lengths + values", () => {
+    assert.equal(constantTimeStringEquals("abc", "abc"), true);
+    assert.equal(constantTimeStringEquals("abc", "abd"), false);
+    assert.equal(constantTimeStringEquals("abc", "abcd"), false);
+    assert.equal(constantTimeStringEquals("", ""), true);
+});
+test("csrfBypassFromEnv: defaults true, only literal off values opt out", () => {
+    assert.equal(csrfBypassFromEnv({}), true);
+    assert.equal(csrfBypassFromEnv({ OMCP_CSRF_BYPASS_BEARER: "true" }), true);
+    for (const v of ["0", "false", "no", "off", "FALSE", "Off"]) {
+        assert.equal(csrfBypassFromEnv({ OMCP_CSRF_BYPASS_BEARER: v }), false, v);
+    }
+});
+test("issuer: sets cookie when missing, no-op when present", () => {
+    const mw = buildCsrfIssuer(defaultCfg());
+    // Missing cookie -> set
+    const r1 = call(mw, { headers: {} });
+    assert.equal(r1.nexted, true);
+    const set = r1.res.getHeader("Set-Cookie");
+    assert.match(set, /^omcp-csrf=[A-Za-z0-9_-]+;/);
+    assert.match(set, /Path=\//);
+    assert.match(set, /SameSite=Lax/);
+    assert.doesNotMatch(set, /HttpOnly/);
+    // Present cookie -> no Set-Cookie emitted
+    const r2 = call(mw, { headers: { cookie: "omcp-csrf=abc" } });
+    assert.equal(r2.nexted, true);
+    assert.equal(r2.res.getHeader("Set-Cookie"), undefined);
+});
+test("issuer: Secure flag honors secureCookie callback", () => {
+    const mw = buildCsrfIssuer({ bypassBearer: true, secureCookie: () => true });
+    const r = call(mw, { headers: {} });
+    assert.match(r.res.getHeader("Set-Cookie"), /Secure/);
+});
+test("enforcer: GET/HEAD/OPTIONS always pass", () => {
+    const mw = buildCsrfEnforcer(defaultCfg());
+    for (const m of ["GET", "HEAD", "OPTIONS"]) {
+        const r = call(mw, { method: m, headers: {} });
+        assert.equal(r.nexted, true, m);
+    }
+});
+test("enforcer: bearer auth bypasses CSRF when bypassBearer=true", () => {
+    const mw = buildCsrfEnforcer(defaultCfg({ bypassBearer: true }));
+    const r = call(mw, {
+        method: "POST",
+        headers: { authorization: "Bearer abc.def.ghi" },
+    });
+    assert.equal(r.nexted, true);
+});
+test("enforcer: X-API-Key also bypasses when bypassBearer=true", () => {
+    const mw = buildCsrfEnforcer(defaultCfg({ bypassBearer: true }));
+    const r = call(mw, {
+        method: "POST",
+        headers: { "x-api-key": "abc" },
+    });
+    assert.equal(r.nexted, true);
+});
+test("enforcer: bypassBearer=false requires CSRF even for bearer clients", () => {
+    const mw = buildCsrfEnforcer(defaultCfg({ bypassBearer: false }));
+    const r = call(mw, {
+        method: "POST",
+        headers: { authorization: "Bearer abc" },
+    });
+    assert.equal(r.nexted, false);
+    assert.equal(r.res.status_, 403);
+});
+test("enforcer: cookie-session POST without header is rejected with 403", () => {
+    const mw = buildCsrfEnforcer(defaultCfg());
+    const r = call(mw, {
+        method: "POST",
+        headers: { cookie: "omcp-csrf=tok123" },
+    });
+    assert.equal(r.nexted, false);
+    assert.equal(r.res.status_, 403);
+});
+test("enforcer: cookie + matching header passes", () => {
+    const mw = buildCsrfEnforcer(defaultCfg());
+    const r = call(mw, {
+        method: "POST",
+        headers: { cookie: `${CSRF_COOKIE}=tok123`, [CSRF_HEADER]: "tok123" },
+    });
+    assert.equal(r.nexted, true);
+});
+test("enforcer: header != cookie is rejected (token mismatch attack)", () => {
+    const mw = buildCsrfEnforcer(defaultCfg());
+    const r = call(mw, {
+        method: "POST",
+        headers: { cookie: `${CSRF_COOKIE}=cookie-token`, [CSRF_HEADER]: "header-token" },
+    });
+    assert.equal(r.nexted, false);
+    assert.equal(r.res.status_, 403);
+});
+test("enforcer: missing cookie + header is rejected (no token at all)", () => {
+    const mw = buildCsrfEnforcer(defaultCfg());
+    const r = call(mw, {
+        method: "POST",
+        headers: {},
+    });
+    assert.equal(r.nexted, false);
+    assert.equal(r.res.status_, 403);
+});

package/dist/auth/local-users.d.ts

@@ -58,5 +58,11 @@ export declare function verifyPassword(plaintext: string, encoded: string): bool
  * anonymous mode cleanly.
  */
 export declare function readUsersFile(path: string): Promise<LocalUsersFile | null>;
+/** Atomic write of the users file. Same tmp+rename pattern the
+ *  products + token-budget snapshot writers use, so a crash mid-write
+ *  leaves the previous file intact — never zero-byte. The file is
+ *  the only persistent source of basic-mode credentials, so a
+ *  half-write would lock every user out. */
+export declare function writeUsersFile(path: string, file: LocalUsersFile): Promise<void>;
 /** Find a user by username (case-sensitive) and verify the supplied password. */
 export declare function authenticate(username: string, password: string, store: LocalUsersFile): LocalUser | null;

package/dist/auth/local-users.js

@@ -105,6 +105,17 @@ export async function readUsersFile(path) {
         return null;
     return parsed;
 }
+/** Atomic write of the users file. Same tmp+rename pattern the
+ *  products + token-budget snapshot writers use, so a crash mid-write
+ *  leaves the previous file intact — never zero-byte. The file is
+ *  the only persistent source of basic-mode credentials, so a
+ *  half-write would lock every user out. */
+export async function writeUsersFile(path, file) {
+    const text = JSON.stringify(file, null, 2) + "\n";
+    const tmp = path + ".tmp";
+    await fs.writeFile(tmp, text, { encoding: "utf8", mode: 0o600 });
+    await fs.rename(tmp, path);
+}
 function isUsersFile(v) {
     if (!v || typeof v !== "object")
         return false;

package/dist/auth/local-users.test.js

@@ -78,3 +78,44 @@ test("authenticate — returns null for wrong password", () => {
     };
     assert.equal(authenticate("alice", "wrong", store), null);
 });
+import { writeUsersFile } from "./local-users.js";
+test("writeUsersFile — atomic round-trip preserves shape", async () => {
+    const { mkdtemp, rm } = await import("node:fs/promises");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const dir = await mkdtemp(join(tmpdir(), "omcp-users-"));
+    try {
+        const path = join(dir, "users.json");
+        const file = {
+            users: [
+                { username: "alice", name: "Alice", roles: ["operator", "viewer"], tenant: "acme", passwordHash: "scrypt$dummy" },
+                { username: "bob", name: "Bob", passwordHash: "scrypt$dummy2" },
+            ],
+        };
+        await writeUsersFile(path, file);
+        const back = await readUsersFile(path);
+        assert.ok(back);
+        assert.equal(back.users.length, 2);
+        assert.deepEqual(back.users[0].roles, ["operator", "viewer"]);
+        assert.equal(back.users[0].tenant, "acme");
+        assert.equal(back.users[1].passwordHash, "scrypt$dummy2");
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+test("writeUsersFile — no .tmp leftover after success (atomic rename)", async () => {
+    const { mkdtemp, rm, readdir } = await import("node:fs/promises");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const dir = await mkdtemp(join(tmpdir(), "omcp-users-tmp-"));
+    try {
+        const path = join(dir, "users.json");
+        await writeUsersFile(path, { users: [{ username: "u", name: "U", passwordHash: "scrypt$x" }] });
+        const entries = await readdir(dir);
+        assert.deepEqual(entries.sort(), ["users.json"]);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});