@thotischner/observability-mcp 1.7.1 → 3.0.0

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

@@ -0,0 +1,68 @@
+/**
+ * File-backed local user store for the management-plane "basic" auth mode.
+ *
+ * Password verification uses node's built-in `scrypt` so the server has no
+ * extra runtime dependency. The on-disk format is a small JSON document:
+ *
+ *   {
+ *     "users": [
+ *       {
+ *         "username": "alice",
+ *         "name": "Alice Operator",
+ *         "roles": ["operator"],
+ *         "passwordHash": "scrypt$N$r$p$<salt-b64>$<hash-b64>"
+ *       },
+ *       ...
+ *     ]
+ *   }
+ *
+ * The `passwordHash` field uses the PHC-like format `scrypt$N$r$p$salt$hash`,
+ * which encodes the cost parameters alongside the digest so operators can
+ * rotate them without breaking existing entries.
+ *
+ * Use `hashPassword()` to mint a new entry, e.g. from a one-shot CLI helper.
+ */
+export interface LocalUser {
+    username: string;
+    name: string;
+    roles?: string[];
+    /** Optional tenant assignment. Missing → DEFAULT_TENANT. */
+    tenant?: string;
+    passwordHash: string;
+}
+export interface LocalUsersFile {
+    users: LocalUser[];
+}
+/** Default scrypt cost — N=2^15, r=8, p=1. Matches OWASP 2023 baseline. */
+export declare const DEFAULT_SCRYPT_N: number;
+export declare const DEFAULT_SCRYPT_R = 8;
+export declare const DEFAULT_SCRYPT_P = 1;
+/** Produce a `scrypt$…` formatted hash for the given plaintext. */
+export declare function hashPassword(plaintext: string, opts?: {
+    N?: number;
+    r?: number;
+    p?: number;
+}): string;
+/** Upper bounds on scrypt cost parameters accepted during verify.
+ * The users file is operator-controlled, but an accidental typo
+ * ("N=21474836480") shouldn't be able to hang the auth path. The
+ * caps are well above any realistic production setting. */
+export declare const MAX_SCRYPT_N: number;
+export declare const MAX_SCRYPT_R = 16;
+export declare const MAX_SCRYPT_P = 4;
+/** Constant-time verify of a plaintext against a `scrypt$…` hash. */
+export declare function verifyPassword(plaintext: string, encoded: string): boolean;
+/**
+ * Read + parse the users file. Returns `null` (not throws) when the file
+ * doesn't exist or the JSON is malformed so the caller can fall through to
+ * 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

@@ -0,0 +1,154 @@
+/**
+ * File-backed local user store for the management-plane "basic" auth mode.
+ *
+ * Password verification uses node's built-in `scrypt` so the server has no
+ * extra runtime dependency. The on-disk format is a small JSON document:
+ *
+ *   {
+ *     "users": [
+ *       {
+ *         "username": "alice",
+ *         "name": "Alice Operator",
+ *         "roles": ["operator"],
+ *         "passwordHash": "scrypt$N$r$p$<salt-b64>$<hash-b64>"
+ *       },
+ *       ...
+ *     ]
+ *   }
+ *
+ * The `passwordHash` field uses the PHC-like format `scrypt$N$r$p$salt$hash`,
+ * which encodes the cost parameters alongside the digest so operators can
+ * rotate them without breaking existing entries.
+ *
+ * Use `hashPassword()` to mint a new entry, e.g. from a one-shot CLI helper.
+ */
+import { promises as fs } from "node:fs";
+import { randomBytes, scryptSync, timingSafeEqual } from "node:crypto";
+/** Default scrypt cost — N=2^15, r=8, p=1. Matches OWASP 2023 baseline. */
+export const DEFAULT_SCRYPT_N = 1 << 15;
+export const DEFAULT_SCRYPT_R = 8;
+export const DEFAULT_SCRYPT_P = 1;
+const HASH_KEYLEN = 32;
+/** Produce a `scrypt$…` formatted hash for the given plaintext. */
+export function hashPassword(plaintext, opts = {}) {
+    const N = opts.N ?? DEFAULT_SCRYPT_N;
+    const r = opts.r ?? DEFAULT_SCRYPT_R;
+    const p = opts.p ?? DEFAULT_SCRYPT_P;
+    const salt = randomBytes(16);
+    const hash = scryptSync(plaintext, salt, HASH_KEYLEN, { N, r, p, maxmem: 64 * 1024 * 1024 });
+    return `scrypt$${N}$${r}$${p}$${salt.toString("base64")}$${hash.toString("base64")}`;
+}
+/** Upper bounds on scrypt cost parameters accepted during verify.
+ * The users file is operator-controlled, but an accidental typo
+ * ("N=21474836480") shouldn't be able to hang the auth path. The
+ * caps are well above any realistic production setting. */
+export const MAX_SCRYPT_N = 1 << 20; // 1 048 576 — ~1 second on a modern core
+export const MAX_SCRYPT_R = 16;
+export const MAX_SCRYPT_P = 4;
+/** Constant-time verify of a plaintext against a `scrypt$…` hash. */
+export function verifyPassword(plaintext, encoded) {
+    const parts = encoded.split("$");
+    if (parts.length !== 6 || parts[0] !== "scrypt")
+        return false;
+    const N = Number(parts[1]);
+    const r = Number(parts[2]);
+    const p = Number(parts[3]);
+    if (!Number.isFinite(N) || !Number.isFinite(r) || !Number.isFinite(p))
+        return false;
+    if (N <= 0 || r <= 0 || p <= 0)
+        return false;
+    if (N > MAX_SCRYPT_N || r > MAX_SCRYPT_R || p > MAX_SCRYPT_P)
+        return false;
+    let salt;
+    let expected;
+    try {
+        salt = Buffer.from(parts[4], "base64");
+        expected = Buffer.from(parts[5], "base64");
+    }
+    catch {
+        return false;
+    }
+    if (expected.length === 0)
+        return false;
+    let candidate;
+    try {
+        candidate = scryptSync(plaintext, salt, expected.length, { N, r, p, maxmem: 256 * 1024 * 1024 });
+    }
+    catch {
+        return false;
+    }
+    if (candidate.length !== expected.length)
+        return false;
+    return timingSafeEqual(candidate, expected);
+}
+/**
+ * Read + parse the users file. Returns `null` (not throws) when the file
+ * doesn't exist or the JSON is malformed so the caller can fall through to
+ * anonymous mode cleanly.
+ */
+export async function readUsersFile(path) {
+    let raw;
+    try {
+        raw = await fs.readFile(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isUsersFile(parsed))
+        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;
+    const o = v;
+    if (!Array.isArray(o.users))
+        return false;
+    return o.users.every((u) => {
+        if (!u || typeof u !== "object")
+            return false;
+        const r = u;
+        if (typeof r.username !== "string" || !r.username)
+            return false;
+        if (typeof r.name !== "string")
+            return false;
+        if (typeof r.passwordHash !== "string")
+            return false;
+        if (r.roles !== undefined && !(Array.isArray(r.roles) && r.roles.every((x) => typeof x === "string")))
+            return false;
+        if (r.tenant !== undefined && typeof r.tenant !== "string")
+            return false;
+        return true;
+    });
+}
+/** Find a user by username (case-sensitive) and verify the supplied password. */
+export function authenticate(username, password, store) {
+    const u = store.users.find((x) => x.username === username);
+    if (!u) {
+        // Spend roughly the same time as a real verify so a missing username
+        // isn't trivially distinguishable by response timing.
+        verifyPassword(password, "scrypt$32768$8$1$AAAA$AAAA");
+        return null;
+    }
+    if (!verifyPassword(password, u.passwordHash))
+        return null;
+    return u;
+}

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

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

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

@@ -0,0 +1,121 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { hashPassword, verifyPassword, readUsersFile, authenticate, } from "./local-users.js";
+// Use a smaller N so the test suite stays under a second even on slow CI runners.
+const fastOpts = { N: 1 << 10, r: 8, p: 1 };
+test("hashPassword + verifyPassword — accepts correct password", () => {
+    const hash = hashPassword("hunter2", fastOpts);
+    assert.match(hash, /^scrypt\$1024\$8\$1\$/);
+    assert.equal(verifyPassword("hunter2", hash), true);
+});
+test("verifyPassword — rejects wrong password", () => {
+    const hash = hashPassword("hunter2", fastOpts);
+    assert.equal(verifyPassword("hunter3", hash), false);
+});
+test("verifyPassword — rejects malformed hash", () => {
+    assert.equal(verifyPassword("anything", ""), false);
+    assert.equal(verifyPassword("anything", "plain-text"), false);
+    assert.equal(verifyPassword("anything", "argon2$x$y$z"), false);
+    assert.equal(verifyPassword("anything", "scrypt$$$$$" /* empty fields */), false);
+    assert.equal(verifyPassword("anything", "scrypt$1024$8$1$AAAA$"), false);
+});
+test("verifyPassword — rejects absurd scrypt cost params (DoS guard)", () => {
+    // Far above our MAX_SCRYPT_N / R / P caps. Should fail fast (no hash work).
+    assert.equal(verifyPassword("x", "scrypt$1073741824$8$1$AAAA$AAAA"), false); // N too big
+    assert.equal(verifyPassword("x", "scrypt$32768$1024$1$AAAA$AAAA"), false); // r too big
+    assert.equal(verifyPassword("x", "scrypt$32768$8$1024$AAAA$AAAA"), false); // p too big
+});
+test("readUsersFile — returns null when the file is missing or malformed", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "omcp-users-"));
+    try {
+        assert.equal(await readUsersFile(join(dir, "nope.json")), null);
+        const bad = join(dir, "bad.json");
+        await writeFile(bad, "not json", "utf8");
+        assert.equal(await readUsersFile(bad), null);
+        const wrongShape = join(dir, "wrong.json");
+        await writeFile(wrongShape, JSON.stringify({ users: "string-not-array" }), "utf8");
+        assert.equal(await readUsersFile(wrongShape), null);
+        const missingFields = join(dir, "missing.json");
+        await writeFile(missingFields, JSON.stringify({ users: [{ username: "alice" }] }), "utf8");
+        assert.equal(await readUsersFile(missingFields), null);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+test("authenticate — returns user on correct credentials", () => {
+    const store = {
+        users: [
+            {
+                username: "alice",
+                name: "Alice",
+                roles: ["operator"],
+                passwordHash: hashPassword("hunter2", fastOpts),
+            },
+        ],
+    };
+    const u = authenticate("alice", "hunter2", store);
+    assert.ok(u);
+    assert.equal(u.username, "alice");
+    assert.deepEqual(u.roles, ["operator"]);
+});
+test("authenticate — returns null for unknown user", () => {
+    const store = { users: [] };
+    assert.equal(authenticate("nobody", "x", store), null);
+});
+test("authenticate — returns null for wrong password", () => {
+    const store = {
+        users: [
+            {
+                username: "alice",
+                name: "Alice",
+                passwordHash: hashPassword("hunter2", fastOpts),
+            },
+        ],
+    };
+    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 });
+    }
+});

package/dist/auth/middleware.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Express middleware wiring for the management-plane auth mode.
+ *
+ * Split into two pieces by design — the cookie-parsing middleware always
+ * runs (so identity-aware handlers like /api/me always see req.session),
+ * and the protected-route gate is mounted explicitly on the routes that
+ * need it. There is no `if (publicPath) next()` shortcut anywhere — the
+ * decision of "what is public" is encoded by which middleware Express
+ * registers on which route, not by a string match at request time.
+ *
+ * When `OMCP_AUTH` is unset or "anonymous" (the default) both middlewares
+ * are no-ops and every existing handler behaves exactly as before.
+ */
+import type { Request, RequestHandler } from "express";
+import { type SessionPayload, type SessionConfig } from "./session.js";
+import type { OidcRuntime } from "./oidc/runtime.js";
+export type AuthMode = "anonymous" | "basic" | "oidc";
+export interface AuthRuntime {
+    mode: AuthMode;
+    /** Present when mode is "basic" or "oidc" — both mint OMCP session
+     *  cookies the same way, just sourced from local creds vs. an IdP. */
+    session?: SessionConfig;
+    /** When true and `secret` not provided, the server generated one for this
+     * process — sessions will not survive a restart. The wire-up code logs a
+     * warning once when this happens. */
+    secretEphemeral?: boolean;
+    /** OIDC runtime, present only when mode === "oidc". The OIDC HTTP
+     *  endpoints in src/index.ts consume it. The import above is
+     *  type-only and erased at compile time, so this typing adds zero
+     *  runtime coupling — middleware.ts still doesn't depend on the
+     *  OIDC sub-module's node:crypto path. */
+    oidc?: OidcRuntime;
+}
+export interface AuthedRequest extends Request {
+    session?: SessionPayload;
+}
+/**
+ * Best-effort cookie resolver. Attaches `req.session` when present and
+ * valid; otherwise leaves it undefined. Always calls `next()`. Mount this
+ * globally so every handler can read the identity.
+ */
+export declare function buildSessionAttacher(runtime: AuthRuntime): RequestHandler;
+/**
+ * Gate. Rejects requests that lack a valid session with HTTP 401 + a JSON
+ * body the UI's fetch wrapper recognises. Mount this on each protected
+ * route or router, NOT globally — paths the operator wants public
+ * (login, /api/me, /api/info, /healthz, ...) simply don't register it.
+ */
+export declare function buildRequireSession(runtime: AuthRuntime): RequestHandler;

package/dist/auth/middleware.js

@@ -0,0 +1,65 @@
+/**
+ * Express middleware wiring for the management-plane auth mode.
+ *
+ * Split into two pieces by design — the cookie-parsing middleware always
+ * runs (so identity-aware handlers like /api/me always see req.session),
+ * and the protected-route gate is mounted explicitly on the routes that
+ * need it. There is no `if (publicPath) next()` shortcut anywhere — the
+ * decision of "what is public" is encoded by which middleware Express
+ * registers on which route, not by a string match at request time.
+ *
+ * When `OMCP_AUTH` is unset or "anonymous" (the default) both middlewares
+ * are no-ops and every existing handler behaves exactly as before.
+ */
+import { readCookie, verifySession } from "./session.js";
+/**
+ * Best-effort cookie resolver. Attaches `req.session` when present and
+ * valid; otherwise leaves it undefined. Always calls `next()`. Mount this
+ * globally so every handler can read the identity.
+ */
+export function buildSessionAttacher(runtime) {
+    const sessionCfg = runtime.session;
+    // In anonymous mode the secret is meaningless — verifySession would
+    // throw on an empty secret — so install a true no-op middleware and
+    // skip every per-request branch.
+    if (runtime.mode === "anonymous" || !sessionCfg) {
+        return function noopAttacher(_req, _res, next) {
+            next();
+        };
+    }
+    return function sessionAttacher(req, _res, next) {
+        // verifySession is a pure parse + HMAC verify. It safely returns
+        // null on empty / null / malformed input, so call it unconditionally
+        // and let the result speak for itself — no attacker-controlled
+        // branch decides whether the check runs.
+        const raw = readCookie(req.headers.cookie || "");
+        const payload = verifySession(raw, sessionCfg);
+        if (payload)
+            req.session = payload;
+        next();
+    };
+}
+/**
+ * Gate. Rejects requests that lack a valid session with HTTP 401 + a JSON
+ * body the UI's fetch wrapper recognises. Mount this on each protected
+ * route or router, NOT globally — paths the operator wants public
+ * (login, /api/me, /api/info, /healthz, ...) simply don't register it.
+ */
+export function buildRequireSession(runtime) {
+    return function requireSession(req, res, next) {
+        if (runtime.mode === "anonymous" || !runtime.session) {
+            next();
+            return;
+        }
+        if (req.session) {
+            next();
+            return;
+        }
+        res.status(401).json({
+            error: "authentication required",
+            mode: runtime.mode,
+            // Recognised by the UI's fetch wrapper to trigger the login modal.
+            code: "OMCP_AUTH_REQUIRED",
+        });
+    };
+}

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

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