@thotischner/observability-mcp 3.0.1 → 3.1.1

package/dist/auth/middleware.test.js

@@ -2,6 +2,7 @@ import { test } from "node:test";
 import assert from "node:assert/strict";
 import { buildSessionAttacher, buildRequireSession } from "./middleware.js";
 import { issueSession } from "./session.js";
+import { RevocationStore } from "./revocation.js";
 const secret = "x".repeat(48);
 const sessionCfg = { secret };
 function mkReq(opts = {}) {
@@ -56,6 +57,36 @@ test("session attacher — tampered cookie leaves session undefined and still fl
     assert.equal(called, true);
     assert.equal(req.session, undefined);
 });
+test("session attacher — a revoked session (by sid) is not attached", async () => {
+    const { cookie, payload } = issueSession({ sub: "alice", name: "Alice" }, sessionCfg);
+    const revocation = await RevocationStore.create();
+    await revocation.revokeSession(payload.sid);
+    const attach = buildSessionAttacher({ mode: "basic", session: sessionCfg, revocation });
+    const req = mkReq({ cookieHeader: `omcp_session=${cookie}` });
+    let called = false;
+    attach(req, mkRes(), () => { called = true; });
+    assert.equal(called, true);
+    assert.equal(req.session, undefined);
+});
+test("session attacher — a subject-revoked session is not attached", async () => {
+    const { cookie } = issueSession({ sub: "bob", name: "Bob" }, sessionCfg);
+    const revocation = await RevocationStore.create();
+    // Revoke into the future so the just-issued session's iat is <= cutoff.
+    await revocation.revokeSubject("bob", { reason: "offboarded" });
+    const attach = buildSessionAttacher({ mode: "basic", session: sessionCfg, revocation });
+    const req = mkReq({ cookieHeader: `omcp_session=${cookie}` });
+    attach(req, mkRes(), () => { });
+    assert.equal(req.session, undefined);
+});
+test("session attacher — an unrevoked session still attaches when a blocklist is present", async () => {
+    const { cookie } = issueSession({ sub: "carol", name: "Carol" }, sessionCfg);
+    const revocation = await RevocationStore.create();
+    await revocation.revokeSession("some-other-sid");
+    const attach = buildSessionAttacher({ mode: "basic", session: sessionCfg, revocation });
+    const req = mkReq({ cookieHeader: `omcp_session=${cookie}` });
+    attach(req, mkRes(), () => { });
+    assert.equal(req.session?.sub, "carol");
+});
 test("require-session — anonymous always allows", () => {
     const gate = buildRequireSession({ mode: "anonymous" });
     const req = mkReq();

package/dist/auth/password-policy.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Password policy for the management-plane "basic" auth mode.
+ *
+ * Where this is enforced: the only point in the system that ever sees a
+ * management password in plaintext is where one is *minted* — the
+ * `scripts/hash-password.mjs` helper. The users file stores scrypt
+ * hashes only, so password strength cannot be re-evaluated at load time
+ * (there is no plaintext to check), and there is no runtime endpoint that
+ * accepts a plaintext password to set. This module is therefore the
+ * canonical, dependency-free policy that the minting path enforces — and
+ * that any future "change my password" endpoint should call before
+ * hashing. Login (`verifyPassword`) never re-checks policy: that would
+ * lock out users whose passwords predate a tightened policy.
+ *
+ * "Basic" ruleset: a minimum length, a minimum number of character
+ * classes, a small builtin common-password denylist, and a guard against
+ * passwords that just echo the username. Deliberately small — this is a
+ * footgun guard for self-hosted operators, not a compliance engine.
+ */
+export interface PasswordPolicy {
+    /** Minimum length in Unicode code points. */
+    minLength: number;
+    /** Maximum length — a sanity bound so a megabyte "password" can't be
+     *  fed into scrypt. */
+    maxLength: number;
+    /** How many of the four classes (lower/upper/digit/symbol) are required. */
+    minClasses: number;
+    /** When true, reject passwords on the builtin common-password list. */
+    denylistEnabled: boolean;
+}
+export declare const DEFAULT_PASSWORD_POLICY: PasswordPolicy;
+/**
+ * A small list of the most-abused passwords + obvious app-specific ones.
+ * Not exhaustive — the real defenders are length + classes. Lowercased;
+ * comparison is case-insensitive.
+ */
+export declare const COMMON_PASSWORD_DENYLIST: ReadonlySet<string>;
+export interface PasswordCheckResult {
+    ok: boolean;
+    /** Human-readable reasons the password was rejected; empty when ok. */
+    errors: string[];
+}
+/**
+ * Validate a plaintext password against the policy. `username`, when
+ * given, additionally rejects passwords that are (or merely contain) the
+ * username — the single most common weak choice.
+ */
+export declare function validatePassword(password: string, policy?: PasswordPolicy, username?: string): PasswordCheckResult;
+/** Resolve the policy from env, falling back to the defaults. */
+export declare function passwordPolicyFromEnv(env?: NodeJS.ProcessEnv): PasswordPolicy;
+/** True when the policy is turned off entirely via env. */
+export declare function passwordPolicyDisabledFromEnv(env?: NodeJS.ProcessEnv): boolean;

package/dist/auth/password-policy.js

@@ -0,0 +1,125 @@
+/**
+ * Password policy for the management-plane "basic" auth mode.
+ *
+ * Where this is enforced: the only point in the system that ever sees a
+ * management password in plaintext is where one is *minted* — the
+ * `scripts/hash-password.mjs` helper. The users file stores scrypt
+ * hashes only, so password strength cannot be re-evaluated at load time
+ * (there is no plaintext to check), and there is no runtime endpoint that
+ * accepts a plaintext password to set. This module is therefore the
+ * canonical, dependency-free policy that the minting path enforces — and
+ * that any future "change my password" endpoint should call before
+ * hashing. Login (`verifyPassword`) never re-checks policy: that would
+ * lock out users whose passwords predate a tightened policy.
+ *
+ * "Basic" ruleset: a minimum length, a minimum number of character
+ * classes, a small builtin common-password denylist, and a guard against
+ * passwords that just echo the username. Deliberately small — this is a
+ * footgun guard for self-hosted operators, not a compliance engine.
+ */
+export const DEFAULT_PASSWORD_POLICY = {
+    minLength: 12,
+    maxLength: 1024,
+    minClasses: 3,
+    denylistEnabled: true,
+};
+/**
+ * A small list of the most-abused passwords + obvious app-specific ones.
+ * Not exhaustive — the real defenders are length + classes. Lowercased;
+ * comparison is case-insensitive.
+ */
+export const COMMON_PASSWORD_DENYLIST = new Set([
+    "password", "password1", "password123", "passw0rd", "p@ssw0rd", "p@ssword",
+    "123456", "1234567", "12345678", "123456789", "1234567890", "12345",
+    "qwerty", "qwerty123", "qwertyuiop", "asdfghjkl", "1q2w3e4r", "1qaz2wsx",
+    "letmein", "welcome", "welcome1", "admin", "admin123", "administrator",
+    "root", "toor", "changeme", "default", "guest", "iloveyou", "monkey",
+    "dragon", "sunshine", "princess", "football", "baseball", "abc123",
+    "654321", "111111", "000000", "superman", "trustno1", "master",
+    "hello123", "secret", "test", "test123", "user", "login", "passport",
+    "observability", "observability-mcp", "prometheus", "grafana", "loki",
+]);
+/**
+ * Count distinct character classes present. Classification is ASCII-based:
+ * a-z, A-Z, 0-9, and "everything else" (symbol). Non-ASCII letters (é, ü,
+ * emoji, CJK) therefore count as the symbol class, never lower/upper. This
+ * is deliberately conservative — it can only ever under-count classes, so
+ * it never lets a weaker password through than the rule implies.
+ */
+function countClasses(pw) {
+    let lower = false, upper = false, digit = false, symbol = false;
+    for (const ch of pw) {
+        if (ch >= "a" && ch <= "z")
+            lower = true;
+        else if (ch >= "A" && ch <= "Z")
+            upper = true;
+        else if (ch >= "0" && ch <= "9")
+            digit = true;
+        else
+            symbol = true;
+    }
+    return Number(lower) + Number(upper) + Number(digit) + Number(symbol);
+}
+/** Length in code points (so emoji / multibyte count as one). */
+function codePointLength(s) {
+    let n = 0;
+    for (const _ of s)
+        n++;
+    return n;
+}
+/**
+ * Validate a plaintext password against the policy. `username`, when
+ * given, additionally rejects passwords that are (or merely contain) the
+ * username — the single most common weak choice.
+ */
+export function validatePassword(password, policy = DEFAULT_PASSWORD_POLICY, username) {
+    const errors = [];
+    const len = codePointLength(password);
+    if (len < policy.minLength) {
+        errors.push(`must be at least ${policy.minLength} characters (got ${len})`);
+    }
+    if (len > policy.maxLength) {
+        errors.push(`must be at most ${policy.maxLength} characters`);
+    }
+    if (policy.minClasses > 1) {
+        const classes = countClasses(password);
+        if (classes < policy.minClasses) {
+            errors.push(`must mix at least ${policy.minClasses} of: lowercase, uppercase, digit, symbol (got ${classes})`);
+        }
+    }
+    if (policy.denylistEnabled && COMMON_PASSWORD_DENYLIST.has(password.toLowerCase())) {
+        errors.push("is on the common-password denylist");
+    }
+    if (username) {
+        const u = username.toLowerCase();
+        const p = password.toLowerCase();
+        if (u.length >= 3 && p.includes(u)) {
+            errors.push("must not contain the username");
+        }
+    }
+    return { ok: errors.length === 0, errors };
+}
+/** Resolve the policy from env, falling back to the defaults. */
+export function passwordPolicyFromEnv(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;
+    };
+    const truthy = (raw) => {
+        const v = raw?.trim().toLowerCase();
+        return v === "1" || v === "true" || v === "yes";
+    };
+    return {
+        minLength: num(env.OMCP_PASSWORD_MIN_LENGTH, DEFAULT_PASSWORD_POLICY.minLength),
+        maxLength: DEFAULT_PASSWORD_POLICY.maxLength,
+        minClasses: num(env.OMCP_PASSWORD_MIN_CLASSES, DEFAULT_PASSWORD_POLICY.minClasses),
+        denylistEnabled: !truthy(env.OMCP_PASSWORD_DENYLIST_DISABLED),
+    };
+}
+/** True when the policy is turned off entirely via env. */
+export function passwordPolicyDisabledFromEnv(env = process.env) {
+    const v = env.OMCP_PASSWORD_POLICY_DISABLED?.trim().toLowerCase();
+    return v === "1" || v === "true" || v === "yes";
+}

package/dist/auth/password-policy.test.d.ts

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

package/dist/auth/password-policy.test.js

@@ -0,0 +1,111 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { validatePassword, passwordPolicyFromEnv, passwordPolicyDisabledFromEnv, DEFAULT_PASSWORD_POLICY, COMMON_PASSWORD_DENYLIST, } from "./password-policy.js";
+test("a strong password passes the default policy", () => {
+    const r = validatePassword("Tr0ub4dour&3xtra");
+    assert.equal(r.ok, true);
+    assert.deepEqual(r.errors, []);
+});
+test("too-short password is rejected with a length error", () => {
+    const r = validatePassword("Ab1!xy");
+    assert.equal(r.ok, false);
+    assert.ok(r.errors.some((e) => e.includes("at least 12")));
+});
+test("insufficient character classes is rejected", () => {
+    // 16 lowercase letters — long enough, but only one class.
+    const r = validatePassword("abcdefghijklmnop");
+    assert.equal(r.ok, false);
+    assert.ok(r.errors.some((e) => e.includes("at least 3 of")));
+});
+test("two classes still fails the default min of three", () => {
+    const r = validatePassword("abcdefghijkl1234"); // lower + digit only
+    assert.equal(r.ok, false);
+    assert.ok(r.errors.some((e) => e.includes("at least 3 of")));
+});
+test("exactly three classes passes", () => {
+    const r = validatePassword("abcdefghABCD1234"); // lower+upper+digit = 3
+    assert.equal(r.ok, true);
+});
+test("common-password denylist is enforced case-insensitively", () => {
+    // Permissive length/classes so ONLY the denylist can reject — the
+    // denylist matches the whole password exactly (case-insensitively).
+    const permissive = { minLength: 1, maxLength: 1024, minClasses: 1, denylistEnabled: true };
+    const r = validatePassword("PaSsWoRd123", permissive);
+    assert.equal(r.ok, false);
+    assert.ok(r.errors.some((e) => e.includes("denylist")));
+});
+test("denylist entries themselves are all rejected when long enough is waived", () => {
+    // Sanity: the canonical app-specific entries are present.
+    assert.ok(COMMON_PASSWORD_DENYLIST.has("observability-mcp"));
+    assert.ok(COMMON_PASSWORD_DENYLIST.has("prometheus"));
+});
+test("password containing the username is rejected", () => {
+    const r = validatePassword("alice-Secret-99x", DEFAULT_PASSWORD_POLICY, "alice");
+    assert.equal(r.ok, false);
+    assert.ok(r.errors.some((e) => e.includes("username")));
+});
+test("short usernames (<3 chars) do not trigger the username check", () => {
+    // "al" is too short to meaningfully match; password is otherwise strong.
+    const r = validatePassword("alXyZ12345678!", DEFAULT_PASSWORD_POLICY, "al");
+    assert.equal(r.ok, true);
+});
+test("code-point length counts multibyte characters as one", () => {
+    // 11 emoji = 11 code points < 12 → too short despite a large byte length.
+    const eleven = "😀".repeat(11);
+    assert.equal(validatePassword(eleven).ok, false);
+    // 12 of them clears length; emoji count as the "symbol" class only → 1 class.
+    const twelve = "😀".repeat(12);
+    const r = validatePassword(twelve);
+    assert.equal(r.ok, false); // fails on classes, not length
+    assert.ok(r.errors.some((e) => e.includes("at least 3 of")));
+    assert.ok(!r.errors.some((e) => e.includes("at least 12")));
+});
+test("over-long password is rejected (scrypt DoS guard)", () => {
+    const r = validatePassword("Aa1!".repeat(300)); // 1200 chars > 1024
+    assert.equal(r.ok, false);
+    assert.ok(r.errors.some((e) => e.includes("at most")));
+});
+test("disabling the denylist lets a denylisted password through", () => {
+    const permissive = { minLength: 1, maxLength: 1024, minClasses: 1, denylistEnabled: false };
+    // 'password123' is on the denylist; with it disabled only length/classes
+    // apply, which this permissive policy waives.
+    assert.equal(validatePassword("password123", permissive).ok, true);
+});
+test("passwordPolicyFromEnv parses overrides and ignores bad input", () => {
+    const p = passwordPolicyFromEnv({
+        OMCP_PASSWORD_MIN_LENGTH: "16",
+        OMCP_PASSWORD_MIN_CLASSES: "bad",
+        OMCP_PASSWORD_DENYLIST_DISABLED: "true",
+    });
+    assert.equal(p.minLength, 16);
+    assert.equal(p.minClasses, DEFAULT_PASSWORD_POLICY.minClasses); // bad → default
+    assert.equal(p.denylistEnabled, false);
+});
+test("passwordPolicyDisabledFromEnv recognises truthy values", () => {
+    assert.equal(passwordPolicyDisabledFromEnv({ OMCP_PASSWORD_POLICY_DISABLED: "1" }), true);
+    assert.equal(passwordPolicyDisabledFromEnv({ OMCP_PASSWORD_POLICY_DISABLED: "false" }), false);
+    assert.equal(passwordPolicyDisabledFromEnv({}), false);
+});
+test("CLI hash-password.mjs stays in sync with the canonical policy", () => {
+    // The CLI deliberately duplicates the policy to stay dependency-free
+    // (same precedent as the scrypt params). This guard fails loudly if the
+    // two drift: every canonical denylist entry + the defaults must appear
+    // verbatim in the script. (__dirname → mcp-server/src/auth)
+    const here = dirname(fileURLToPath(import.meta.url));
+    const cliPath = join(here, "..", "..", "..", "scripts", "hash-password.mjs");
+    const cli = readFileSync(cliPath, "utf8");
+    for (const entry of COMMON_PASSWORD_DENYLIST) {
+        assert.ok(cli.includes(`"${entry}"`), `CLI denylist is missing "${entry}"`);
+    }
+    assert.ok(cli.includes(`"OMCP_PASSWORD_MIN_LENGTH", ${DEFAULT_PASSWORD_POLICY.minLength}`), "CLI minLength default drifted");
+    assert.ok(cli.includes(`"OMCP_PASSWORD_MIN_CLASSES", ${DEFAULT_PASSWORD_POLICY.minClasses}`), "CLI minClasses default drifted");
+    assert.ok(cli.includes(`PW_MAX_LENGTH = ${DEFAULT_PASSWORD_POLICY.maxLength}`), "CLI maxLength default drifted");
+});
+test("multiple violations are all reported", () => {
+    const r = validatePassword("admin"); // short, 1 class, on denylist
+    assert.equal(r.ok, false);
+    assert.ok(r.errors.length >= 2);
+});

package/dist/auth/revocation.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Session/JWT revocation blocklist for the management plane.
+ *
+ * OMCP sessions are stateless signed cookies (see ./session.ts) — there is
+ * no server-side session table to delete from, so a logout or a
+ * compromised-credential incident can't, on its own, invalidate an
+ * outstanding cookie before its `exp`. This blocklist closes that gap: a
+ * small append-only JSONL file of revocations that every request consults
+ * (in buildSessionAttacher) before a session payload is trusted.
+ *
+ * Two revocation shapes:
+ *   - session: drop one specific session by its `sid`.
+ *   - subject: drop every session for a `sub` issued at or before the
+ *     revocation timestamp ("force re-login"). A fresh login afterwards
+ *     mints a new session with a later `iat`, which is NOT caught — so
+ *     subject-revoke is a logout-everywhere, not a permanent ban.
+ *
+ * Backend is an on-disk JSONL file (one entry per line, mode 0600). When
+ * no path is configured the store is in-memory only (lost on restart);
+ * set OMCP_AUTH_REVOCATION_FILE so revocations survive a restart.
+ *
+ * Multi-replica caveat: the file is read once at startup and the writing
+ * replica updates its own in-memory index immediately, but there is no
+ * live cross-replica propagation — a revocation issued on replica A is
+ * not seen by replica B until B restarts. A shared-store backend (Redis,
+ * mirroring the SCIM / transport stores) is the planned path to
+ * fleet-wide live propagation; see docs/access-control.md.
+ */
+export type RevocationKind = "session" | "subject";
+export interface RevocationEntry {
+    kind: RevocationKind;
+    /** sid for kind "session"; sub for kind "subject". */
+    value: string;
+    /** Revocation time, seconds since epoch. */
+    revokedAt: number;
+    /** Optional free-text reason (truncated by the caller). */
+    reason?: string;
+    /** Optional actor who issued the revocation (admin sub). */
+    by?: string;
+}
+export interface RevocationStoreConfig {
+    /** JSONL file path. Omitted → in-memory only. */
+    path?: string;
+    /** Clock injection for tests. Returns seconds since epoch. */
+    now?: () => number;
+}
+/** The minimal session shape isRevoked needs to make a decision. */
+export interface RevocableSession {
+    sub: string;
+    iat: number;
+    sid?: string;
+}
+export declare class RevocationStore {
+    /** Revoked individual session ids. */
+    private readonly sids;
+    /** sub → latest subject-revocation cutoff (seconds since epoch). */
+    private readonly subjectCutoffs;
+    /** Full ordered history, kept so list() can mirror the file. */
+    private readonly entries;
+    private readonly path?;
+    private readonly now;
+    /** Serialises appends so two concurrent revokes can't interleave a line. */
+    private writeChain;
+    private constructor();
+    /** Build a store, loading any existing on-disk blocklist. */
+    static create(cfg?: RevocationStoreConfig): Promise<RevocationStore>;
+    /** True when this store persists to disk. */
+    get persistent(): boolean;
+    get filePath(): string | undefined;
+    /** Number of revocation entries currently held. */
+    get size(): number;
+    private load;
+    /** Apply an entry to the in-memory indices + history (no write). */
+    private index;
+    private persist;
+    /** Revoke one session by its sid. Idempotent. */
+    revokeSession(sid: string, opts?: {
+        reason?: string;
+        by?: string;
+    }): Promise<RevocationEntry>;
+    /** Revoke every session for a subject issued at or before now. */
+    revokeSubject(sub: string, opts?: {
+        reason?: string;
+        by?: string;
+    }): Promise<RevocationEntry>;
+    /**
+     * Decide whether a session is revoked. Pure + synchronous so it can run
+     * on the hot path of every request without an await.
+     */
+    isRevoked(session: RevocableSession): boolean;
+    /** Snapshot of all entries, newest last (file order). */
+    list(): RevocationEntry[];
+}

package/dist/auth/revocation.js

@@ -0,0 +1,193 @@
+/**
+ * Session/JWT revocation blocklist for the management plane.
+ *
+ * OMCP sessions are stateless signed cookies (see ./session.ts) — there is
+ * no server-side session table to delete from, so a logout or a
+ * compromised-credential incident can't, on its own, invalidate an
+ * outstanding cookie before its `exp`. This blocklist closes that gap: a
+ * small append-only JSONL file of revocations that every request consults
+ * (in buildSessionAttacher) before a session payload is trusted.
+ *
+ * Two revocation shapes:
+ *   - session: drop one specific session by its `sid`.
+ *   - subject: drop every session for a `sub` issued at or before the
+ *     revocation timestamp ("force re-login"). A fresh login afterwards
+ *     mints a new session with a later `iat`, which is NOT caught — so
+ *     subject-revoke is a logout-everywhere, not a permanent ban.
+ *
+ * Backend is an on-disk JSONL file (one entry per line, mode 0600). When
+ * no path is configured the store is in-memory only (lost on restart);
+ * set OMCP_AUTH_REVOCATION_FILE so revocations survive a restart.
+ *
+ * Multi-replica caveat: the file is read once at startup and the writing
+ * replica updates its own in-memory index immediately, but there is no
+ * live cross-replica propagation — a revocation issued on replica A is
+ * not seen by replica B until B restarts. A shared-store backend (Redis,
+ * mirroring the SCIM / transport stores) is the planned path to
+ * fleet-wide live propagation; see docs/access-control.md.
+ */
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+function defaultNow() {
+    return Math.floor(Date.now() / 1000);
+}
+export class RevocationStore {
+    /** Revoked individual session ids. */
+    sids = new Set();
+    /** sub → latest subject-revocation cutoff (seconds since epoch). */
+    subjectCutoffs = new Map();
+    /** Full ordered history, kept so list() can mirror the file. */
+    entries = [];
+    path;
+    now;
+    /** Serialises appends so two concurrent revokes can't interleave a line. */
+    writeChain = Promise.resolve();
+    constructor(cfg) {
+        this.path = cfg.path;
+        this.now = cfg.now ?? defaultNow;
+    }
+    /** Build a store, loading any existing on-disk blocklist. */
+    static async create(cfg = {}) {
+        const store = new RevocationStore(cfg);
+        await store.load();
+        return store;
+    }
+    /** True when this store persists to disk. */
+    get persistent() {
+        return !!this.path;
+    }
+    get filePath() {
+        return this.path;
+    }
+    /** Number of revocation entries currently held. */
+    get size() {
+        return this.entries.length;
+    }
+    async load() {
+        if (!this.path)
+            return;
+        let raw;
+        try {
+            raw = await readFile(this.path, "utf8");
+        }
+        catch (err) {
+            // ENOENT is expected on first boot — nothing to load.
+            if (err.code === "ENOENT")
+                return;
+            throw err;
+        }
+        for (const line of raw.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(trimmed);
+            }
+            catch {
+                // A torn / hand-edited line shouldn't take the whole store down.
+                continue;
+            }
+            const entry = coerceEntry(parsed);
+            if (entry)
+                this.index(entry);
+        }
+    }
+    /** Apply an entry to the in-memory indices + history (no write). */
+    index(entry) {
+        this.entries.push(entry);
+        if (entry.kind === "session") {
+            this.sids.add(entry.value);
+        }
+        else {
+            const prev = this.subjectCutoffs.get(entry.value);
+            // Keep the latest cutoff so re-revoking a subject only widens the window.
+            if (prev === undefined || entry.revokedAt > prev) {
+                this.subjectCutoffs.set(entry.value, entry.revokedAt);
+            }
+        }
+    }
+    async persist(entry) {
+        if (!this.path)
+            return;
+        const path = this.path;
+        const line = JSON.stringify(entry) + "\n";
+        // Chain appends; ensure the parent dir + 0600 mode on the first write.
+        this.writeChain = this.writeChain.then(async () => {
+            try {
+                await appendFile(path, line, { mode: 0o600 });
+            }
+            catch (err) {
+                if (err.code === "ENOENT") {
+                    await mkdir(dirname(path), { recursive: true });
+                    await writeFile(path, line, { mode: 0o600 });
+                    return;
+                }
+                throw err;
+            }
+        });
+        await this.writeChain;
+    }
+    /** Revoke one session by its sid. Idempotent. */
+    async revokeSession(sid, opts = {}) {
+        const entry = {
+            kind: "session",
+            value: sid,
+            revokedAt: this.now(),
+            ...(opts.reason ? { reason: opts.reason } : {}),
+            ...(opts.by ? { by: opts.by } : {}),
+        };
+        this.index(entry);
+        await this.persist(entry);
+        return entry;
+    }
+    /** Revoke every session for a subject issued at or before now. */
+    async revokeSubject(sub, opts = {}) {
+        const entry = {
+            kind: "subject",
+            value: sub,
+            revokedAt: this.now(),
+            ...(opts.reason ? { reason: opts.reason } : {}),
+            ...(opts.by ? { by: opts.by } : {}),
+        };
+        this.index(entry);
+        await this.persist(entry);
+        return entry;
+    }
+    /**
+     * Decide whether a session is revoked. Pure + synchronous so it can run
+     * on the hot path of every request without an await.
+     */
+    isRevoked(session) {
+        if (session.sid && this.sids.has(session.sid))
+            return true;
+        const cutoff = this.subjectCutoffs.get(session.sub);
+        // `<=` so a session issued in the same second as the revocation is
+        // also caught — the operator's intent is "kill what exists now".
+        if (cutoff !== undefined && session.iat <= cutoff)
+            return true;
+        return false;
+    }
+    /** Snapshot of all entries, newest last (file order). */
+    list() {
+        return this.entries.map((e) => ({ ...e }));
+    }
+}
+/** Validate + normalise an untrusted parsed JSON line into an entry. */
+function coerceEntry(v) {
+    if (!v || typeof v !== "object")
+        return null;
+    const o = v;
+    if (o.kind !== "session" && o.kind !== "subject")
+        return null;
+    if (typeof o.value !== "string" || !o.value)
+        return null;
+    if (typeof o.revokedAt !== "number" || !Number.isFinite(o.revokedAt))
+        return null;
+    const entry = { kind: o.kind, value: o.value, revokedAt: o.revokedAt };
+    if (typeof o.reason === "string")
+        entry.reason = o.reason;
+    if (typeof o.by === "string")
+        entry.by = o.by;
+    return entry;
+}

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

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