@thotischner/observability-mcp 3.0.0 → 3.1.0

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();
     };
 }

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 {};