cursedbelt-server 1.0.0

package/src/server/jobs/types.ts

@@ -0,0 +1,188 @@
+import type { Database } from 'bun:sqlite';
+
+/**
+ * The cursedbelt job runner's public types — the engine both apps share.
+ *
+ * cursedbelt owns the *mechanism* (durable cron scheduling, restart-surviving
+ * pollers, the due-row fire queue, run auditing); the *job definitions* —
+ * reminder delivery, recurrence materialization, backup, metrics flush, caSync —
+ * stay app-business and consume these primitives.
+ *
+ * Three primitives cover every in-process scheduled-work shape:
+ *   - {@link JobRunner}  — durable cron jobs (plainjob-backed; survive restart).
+ *   - PollingJob         — a periodic timer that records its last successful run.
+ *   - FireQueue          — the "select due rows → deliver → mark sent" pattern.
+ *
+ * (cwip/taskq is the *other* model — lease-locked, multi-process, cross-machine —
+ * and stays in cwip. These primitives are single-server / in-process only.)
+ */
+
+/**
+ * A minimal structured logger (winston-compatible, so it can be passed straight
+ * through to the underlying plainjob queue/worker). Consumers inject their app
+ * logger; the default ({@link defaultJobLogger}) writes warn/info/error to the
+ * console and silences `debug` (plainjob logs at debug every poll).
+ */
+export interface JobLogger {
+  error(message: string, ...meta: unknown[]): void;
+  warn(message: string, ...meta: unknown[]): void;
+  info(message: string, ...meta: unknown[]): void;
+  debug(message: string, ...meta: unknown[]): void;
+}
+
+/** Everything a job handler is handed when it runs. */
+export interface JobContext {
+  /** The shared SQLite connection (same instance the app uses). */
+  db: Database;
+  /**
+   * Aborted when the runner/poller is stopped, or when a {@link JobDef.timeout}
+   * elapses. Long-running handlers should observe it and short-circuit; a promise
+   * cannot be force-killed, so cooperation is the only way to stop work early.
+   */
+  signal: AbortSignal;
+  logger: JobLogger;
+}
+
+/** A durable, cron-scheduled job registered with a {@link JobRunner}. */
+export interface JobDef {
+  /** Unique name — the audit key (`job_runs.job_name`) and plainjob job type. */
+  name: string;
+  /**
+   * Cron expression. 5-field (minute precision) or 6-field with a leading
+   * seconds column — e.g. `0 3 * * *` is 3am daily, and a seconds step of the
+   * form `(asterisk-slash-10) * * * * *` fires every 10s. Omit for a job that is
+   * only ever fired manually via {@link JobRunner.runOnce}.
+   */
+  cron?: string;
+  /** The work. Rejecting (or timing out) records an `error` run. */
+  run(context: JobContext): Promise<void> | void;
+  /**
+   * Max run time in ms before the context signal is aborted and the run is
+   * recorded as a timeout error. Default {@link DEFAULT_JOB_TIMEOUT_MS}. Set a
+   * larger value (or `0` to disable) for legitimately long jobs like backups.
+   */
+  timeout?: number;
+}
+
+/** A single row of a job's run history (newest first via {@link JobRunner.getLastRun}). */
+export interface JobRunRecord {
+  startedAt: string;
+  /** Null while the run is still in flight (or if the process died mid-run). */
+  endedAt?: string;
+  /** `running` | `ok` | `error`. */
+  status: string;
+  /** Present only on an `error` run. */
+  error?: string;
+}
+
+export interface CreateJobRunnerOptions {
+  logger?: JobLogger;
+  /**
+   * How often each worker polls for due cron jobs, in ms. Default 1000. Set lower
+   * only if you need sub-second cron precision; the cost is one cheap SQLite query
+   * per worker per interval.
+   */
+  pollIntervalMs?: number;
+  /**
+   * Bounds on the runner's persisted history. Without bounds a high-frequency
+   * cron (e.g. a 5s engine janitor) grows `job_runs` and plainjob's internal
+   * `plainjob_jobs` forever — thousands of rows per day on a completely idle
+   * daemon. Retention is ON by default ({@link DEFAULT_JOB_RETENTION});
+   * override a field to tune it, or set a field to `0` to disable that bound.
+   */
+  retention?: JobRetentionOptions;
+}
+
+/** Retention bounds for {@link JobRunner} history. `0` disables that bound. */
+export interface JobRetentionOptions {
+  /** Delete `job_runs` audit rows older than this. Default 7 days. */
+  auditMaxAgeMs?: number;
+  /**
+   * Keep at most this many newest `job_runs` rows PER job name — the bound that
+   * matters for sub-minute crons, where an age window alone still admits tens of
+   * thousands of rows. Default 2000.
+   */
+  auditMaxRowsPerJob?: number;
+  /** Minimum gap between prune passes (pruning is lazy, after a run finishes). Default 1 hour. */
+  pruneIntervalMs?: number;
+  /** plainjob maintenance: remove its internal done-job rows older than this. Default 6 hours. */
+  doneJobsMaxAgeMs?: number;
+  /** plainjob maintenance: remove its internal failed-job rows older than this. Default 7 days. */
+  failedJobsMaxAgeMs?: number;
+}
+
+/** Default {@link JobRetentionOptions} — bounded history out of the box. */
+export const DEFAULT_JOB_RETENTION: Required<JobRetentionOptions> = {
+  auditMaxAgeMs: 7 * 24 * 60 * 60 * 1000,
+  auditMaxRowsPerJob: 2000,
+  pruneIntervalMs: 60 * 60 * 1000,
+  doneJobsMaxAgeMs: 6 * 60 * 60 * 1000,
+  failedJobsMaxAgeMs: 7 * 24 * 60 * 60 * 1000,
+};
+
+/**
+ * The durable cron job runner — a thin facade over plainjob (SQLite-backed, no
+ * Redis). Schedules persist in the shared DB, so a registered cron survives a
+ * restart. (plainjob does NOT retroactively fire a cron missed while the process
+ * was down; for "must catch up on boot" work use a PollingJob with `runOnBoot`.)
+ */
+export interface JobRunner {
+  /** Register a job. Call before {@link start}; registering a cron after start spins its worker up immediately. */
+  register(job: JobDef): void;
+  /** Begin processing: one worker per cron job starts polling. Idempotent. */
+  start(): void;
+  /** Stop all workers (signaling in-flight handlers) and release the queue. Does NOT close the shared DB. */
+  stop(): Promise<void>;
+  /** Run a registered job once, right now (admin/manual trigger). Bypasses the schedule; still audited. Throws ApiError(404) if unknown. */
+  runOnce(name: string): Promise<void>;
+  /** The most recent run of `name`, or null if it has never run. */
+  getLastRun(name: string): JobRunRecord | null;
+}
+
+/** A periodic timer started/stopped as a unit. Returned by `createPollingJob`/`createFireQueue`. */
+export interface PollingJob {
+  name: string;
+  /** Start the timer (and fire once immediately unless `runOnBoot` is false). Idempotent. */
+  start(): void;
+  /** Stop the timer and signal any in-flight run via its abort signal. */
+  stop(): void;
+}
+
+export interface PollingJobOpts {
+  name: string;
+  /** Fire cadence in ms. */
+  intervalMs: number;
+  /** Fire once immediately on {@link PollingJob.start}. Default true. */
+  runOnBoot?: boolean;
+  /** The shared SQLite connection. `job_state.last_run_at` is upserted after each successful run. */
+  db: Database;
+  run(context: JobContext): Promise<void> | void;
+  logger?: JobLogger;
+}
+
+/** A {@link PollingJob} specialized for the "deliver every due row" pattern. */
+export type FireQueue = PollingJob;
+
+export interface FireQueueOpts<T> {
+  name: string;
+  db: Database;
+  /** Poll cadence in ms. Default {@link DEFAULT_FIRE_INTERVAL_MS} (30s). */
+  intervalMs?: number;
+  /** Fire once immediately on start. Default true. */
+  runOnBoot?: boolean;
+  /** Return the rows currently due for delivery. */
+  getDue(db: Database): T[];
+  /** Deliver one item. Throwing skips `markSent` for that item and routes to `onError`; the loop continues. */
+  deliver(item: T, db: Database): Promise<void> | void;
+  /** Mark one item delivered (only called after a successful `deliver`). */
+  markSent(item: T, db: Database): void;
+  /** Per-item failure hook (the loop still continues to the next item). */
+  onError?(item: T, err: unknown): void;
+  logger?: JobLogger;
+}
+
+/** Default per-run timeout for a cron {@link JobDef} (1 minute). */
+export const DEFAULT_JOB_TIMEOUT_MS = 60_000;
+
+/** Default poll cadence for a {@link FireQueue} (30 seconds). */
+export const DEFAULT_FIRE_INTERVAL_MS = 30_000;

package/src/server/master-lock/guard.spec.ts

@@ -0,0 +1,347 @@
+/**
+ * The guard's decisions, over a real {@link MasterLock}.
+ *
+ * The property under test is the owner's sentence: *"until the master password is entered a
+ * user logged in as me cannot see anything about the site, not even text or images, nothing
+ * at all."* So the assertions are mostly about what does NOT come back.
+ */
+import { beforeAll, describe, expect, test } from "bun:test";
+import {
+	MASTER_LOCK_PATHS,
+	MASTER_LOCK_STATE_HEADER,
+	type MasterLockKdfParams,
+	deriveMasterLockVerifier,
+	newMasterLockKdfParams,
+} from "cursedbelt-core/master-lock";
+import { createMasterLockGuard } from "./guard";
+import { MasterLock } from "./masterLock";
+import { createMemoryMasterLockStore } from "./store";
+
+const KDF: MasterLockKdfParams = {
+	v: 1,
+	alg: "PBKDF2-SHA256",
+	iter: 1,
+	salt: "AAECAwQFBgcICQoLDA0ODw",
+};
+let VERIFIER = "";
+let SEED = "";
+
+beforeAll(async () => {
+	VERIFIER = await deriveMasterLockVerifier("open sesame", KDF);
+	SEED = JSON.stringify({
+		kdf: KDF,
+		verifierHash: await Bun.password.hash(VERIFIER, { algorithm: "argon2id" }),
+	});
+});
+
+function build(allow?: (url: URL) => boolean) {
+	const lock = new MasterLock({ store: createMemoryMasterLockStore(), seedJson: SEED });
+	const guard = createMasterLockGuard({
+		lock,
+		appLabel: "Test App",
+		...(allow ? { allow } : {}),
+	});
+	return { lock, guard };
+}
+
+const doc = (path: string, cookie?: string): Request =>
+	new Request(`http://app.test${path}`, {
+		headers: {
+			"sec-fetch-dest": "document",
+			...(cookie ? { cookie } : {}),
+		},
+	});
+const xhr = (path: string, cookie?: string): Request =>
+	new Request(`http://app.test${path}`, {
+		headers: { "sec-fetch-dest": "empty", ...(cookie ? { cookie } : {}) },
+	});
+const post = (path: string, body: unknown, cookie?: string): Request =>
+	new Request(`http://app.test${path}`, {
+		method: "POST",
+		headers: { "content-type": "application/json", ...(cookie ? { cookie } : {}) },
+		body: JSON.stringify(body),
+	});
+
+/** Unlock and return the cookie header the browser would send back. */
+async function open(guard: ReturnType<typeof build>["guard"]): Promise<string> {
+	const res = await guard.handle(post(MASTER_LOCK_PATHS.unlock, { verifier: VERIFIER }));
+	expect(res?.status).toBe(200);
+	const setCookie = res?.headers.get("set-cookie") ?? "";
+	// The NAME as well as the value: it is per app now, and a helper that hardcoded
+	// `master_lock=` would keep passing on the day the guard stopped setting that.
+	const pair = setCookie.split(";")[0] ?? "";
+	expect((pair.split("=")[1] ?? "").length).toBeGreaterThan(10);
+	return pair;
+}
+
+describe("while locked", () => {
+	test("a page request gets the lock page IN PLACE — same url, no app", async () => {
+		const { guard } = build();
+		const res = await guard.handle(doc("/some/deep/page?q=1"));
+		expect(res?.status).toBe(200);
+		expect(res?.headers.get(MASTER_LOCK_STATE_HEADER)).toBe("locked");
+		const html = (await res?.text()) ?? "";
+		expect(html).toContain("Master password");
+		expect(html).toContain("Test App");
+		// Nothing of the app, and nothing fetched from anywhere else: every `src`/`href` is a
+		// same-origin path or an inline `data:` URI. Checked on the ATTRIBUTES rather than on
+		// the string, because the inline favicon legitimately contains the SVG namespace URI —
+		// which is an identifier, not a request, and a naive "no http" grep fails on it.
+		expect(html).not.toContain("<script>");
+		for (const [, value] of html.matchAll(/\b(?:src|href)="([^"]*)"/g)) {
+			expect(value.startsWith("/") || value.startsWith("data:")).toBe(true);
+		}
+	});
+
+	test("everything else is the SAME 401, whatever it asked for", async () => {
+		const { guard } = build();
+		for (const request of [
+			xhr("/api/items"),
+			xhr("/media/secret.jpg"),
+			post("/api/delete", {}),
+			new Request("http://app.test/anything"),
+		]) {
+			const res = await guard.handle(request);
+			expect(res?.status).toBe(401);
+			expect(res?.headers.get(MASTER_LOCK_STATE_HEADER)).toBe("locked");
+			expect(await res?.json()).toEqual({ error: "locked", retryAfterMs: 0 });
+		}
+	});
+
+	test("nothing it serves may be cached", async () => {
+		const { guard } = build();
+		const page = await guard.handle(doc("/"));
+		expect(page?.headers.get("cache-control")).toContain("no-store");
+		const status = await guard.handle(xhr(MASTER_LOCK_PATHS.status));
+		expect(status?.headers.get("cache-control")).toContain("no-store");
+	});
+
+	test("the lock page carries a wall of its own", async () => {
+		const { guard } = build();
+		const res = await guard.handle(doc("/"));
+		const csp = res?.headers.get("content-security-policy") ?? "";
+		expect(csp).toContain("default-src 'none'");
+		expect(csp).toContain("frame-ancestors 'none'");
+		expect(res?.headers.get("x-content-type-options")).toBe("nosniff");
+	});
+
+	test("its own page, style, script and status stay reachable — they are how you unlock", async () => {
+		const { guard } = build();
+		for (const path of [
+			MASTER_LOCK_PATHS.page,
+			MASTER_LOCK_PATHS.style,
+			MASTER_LOCK_PATHS.script,
+			MASTER_LOCK_PATHS.status,
+		]) {
+			const res = await guard.handle(xhr(path));
+			expect(res?.status).toBe(200);
+		}
+	});
+
+	test("status discloses the params and no more", async () => {
+		const { guard } = build();
+		const res = await guard.handle(xhr(MASTER_LOCK_PATHS.status));
+		const body = (await res?.json()) as Record<string, unknown>;
+		expect(body).toEqual({
+			configured: true,
+			enrollable: false,
+			locked: true,
+			kdf: KDF,
+			idleMs: 5 * 60_000,
+			remainingMs: 0,
+			retryAfterMs: 0,
+		});
+		expect(JSON.stringify(body)).not.toContain("argon2");
+	});
+
+	test("an `allow` path is passed through — that is where a machine surface lives", async () => {
+		const { guard } = build((url) => url.pathname === "/healthz");
+		expect(await guard.handle(xhr("/healthz"))).toBeNull();
+		expect((await guard.handle(xhr("/api/items")))?.status).toBe(401);
+	});
+
+	test("a mutation route refuses before it can change anything", async () => {
+		const { lock, guard } = build();
+		expect((await guard.handle(post(MASTER_LOCK_PATHS.lock, {})))?.status).toBe(401);
+		expect((await guard.handle(post(MASTER_LOCK_PATHS.settings, { idleMs: 60_000 })))?.status).toBe(401);
+		expect(lock.idleMs).toBe(5 * 60_000);
+	});
+});
+
+describe("unlocking", () => {
+	test("the right verifier mints a cookie and the app is served again", async () => {
+		const { guard } = build();
+		const cookie = await open(guard);
+		expect(await guard.handle(doc("/", cookie))).toBeNull();
+		expect(await guard.handle(xhr("/api/items", cookie))).toBeNull();
+	});
+
+	test("the cookie is HttpOnly + SameSite=Strict, and Secure only on https", async () => {
+		const { guard } = build();
+		const plain = await guard.handle(post(MASTER_LOCK_PATHS.unlock, { verifier: VERIFIER }));
+		const header = plain?.headers.get("set-cookie") ?? "";
+		expect(header).toContain("HttpOnly");
+		expect(header).toContain("SameSite=Strict");
+		expect(header).not.toContain("Secure");
+		// A session cookie — closing the browser drops it; the server clock is the real expiry.
+		expect(header).not.toContain("Max-Age");
+
+		const { guard: guard2 } = build();
+		const forwarded = new Request(`http://app.test${MASTER_LOCK_PATHS.unlock}`, {
+			method: "POST",
+			headers: { "content-type": "application/json", "x-forwarded-proto": "https" },
+			body: JSON.stringify({ verifier: VERIFIER }),
+		});
+		expect((await guard2.handle(forwarded))?.headers.get("set-cookie")).toContain("Secure");
+	});
+
+	test("a wrong verifier answers the same refusal as being locked out", async () => {
+		const { guard } = build();
+		const res = await guard.handle(post(MASTER_LOCK_PATHS.unlock, { verifier: "nope" }));
+		expect(res?.status).toBe(401);
+		expect(await res?.json()).toEqual({ error: "locked", retryAfterMs: 0 });
+	});
+
+	test("a garbage body is refused, not crashed on", async () => {
+		const { guard } = build();
+		const raw = new Request(`http://app.test${MASTER_LOCK_PATHS.unlock}`, {
+			method: "POST",
+			body: "not json",
+		});
+		expect((await guard.handle(raw))?.status).toBe(401);
+	});
+
+	test("visiting the lock page while unlocked sends you to the app", async () => {
+		const { guard } = build();
+		const cookie = await open(guard);
+		const res = await guard.handle(doc(MASTER_LOCK_PATHS.page, cookie));
+		expect(res?.status).toBe(303);
+		expect(res?.headers.get("location")).toBe("http://app.test/");
+	});
+});
+
+describe("while unlocked", () => {
+	test("the manual lock closes the site and clears the cookie", async () => {
+		const { guard } = build();
+		const cookie = await open(guard);
+		const res = await guard.handle(post(MASTER_LOCK_PATHS.lock, {}, cookie));
+		expect(res?.status).toBe(200);
+		expect(res?.headers.get("set-cookie")).toContain("Max-Age=0");
+		expect((await guard.handle(xhr("/api/items", cookie)))?.status).toBe(401);
+	});
+
+	test("the ping reports how much idle time is left", async () => {
+		const { guard } = build();
+		const cookie = await open(guard);
+		const res = await guard.handle(post(MASTER_LOCK_PATHS.ping, {}, cookie));
+		const body = (await res?.json()) as { remainingMs: number };
+		expect(body.remainingMs).toBeGreaterThan(4 * 60_000);
+	});
+
+	test("the timeout is settable and clamped", async () => {
+		const { guard, lock } = build();
+		const cookie = await open(guard);
+		const res = await guard.handle(post(MASTER_LOCK_PATHS.settings, { idleMs: 1 }, cookie));
+		expect(await res?.json()).toEqual({ ok: true, idleMs: 30_000 });
+		expect(lock.idleMs).toBe(30_000);
+	});
+
+	test("rotation needs the current password and locks the site behind it", async () => {
+		const { guard } = build();
+		const cookie = await open(guard);
+		const nextKdf = newMasterLockKdfParams();
+		const nextVerifier = await deriveMasterLockVerifier("something else", nextKdf);
+
+		const refused = await guard.handle(
+			post(MASTER_LOCK_PATHS.change, { currentVerifier: "no", kdf: nextKdf, verifier: nextVerifier }, cookie),
+		);
+		expect(refused?.status).toBe(400);
+		expect(await refused?.json()).toEqual({ error: "wrong" });
+
+		const done = await guard.handle(
+			post(
+				MASTER_LOCK_PATHS.change,
+				{ currentVerifier: VERIFIER, kdf: nextKdf, verifier: nextVerifier },
+				cookie,
+			),
+		);
+		expect(done?.status).toBe(200);
+		expect(done?.headers.get("set-cookie")).toContain("Max-Age=0");
+		expect((await guard.handle(xhr("/api/items", cookie)))?.status).toBe(401);
+	});
+});
+
+describe("an app with no master password configured", () => {
+	test("is served normally — an unopenable lock would brick it", async () => {
+		const lock = new MasterLock({ store: createMemoryMasterLockStore(), seedJson: null });
+		const guard = createMasterLockGuard({ lock, appLabel: "Test App" });
+		expect(await guard.handle(doc("/"))).toBeNull();
+		const status = await guard.handle(xhr(MASTER_LOCK_PATHS.status));
+		expect(await status?.json()).toMatchObject({ configured: false, locked: false, kdf: null });
+	});
+});
+
+/**
+ * 🔴 Two locked apps on ONE HOST — the bug a browser found and a unit test never could.
+ *
+ * A cookie is scoped by host, not by origin, so `localhost:3358` and `localhost:3098` share
+ * one jar. While both apps wrote a cookie called `master_lock`, whichever was unlocked last
+ * owned it, and the other app's `presents(req)` began answering false — which silently
+ * disabled "Lock this site", the idle-timeout setting, the password rotation and the
+ * activity ping on an app that still LOOKED open. See `masterLockCookieName`.
+ */
+describe("two locked apps sharing a hostname", () => {
+	const buildNamed = (appLabel: string) => {
+		const lock = new MasterLock({ store: createMemoryMasterLockStore(), seedJson: SEED });
+		return { lock, guard: createMasterLockGuard({ lock, appLabel }) };
+	};
+
+	test("each app names its own cookie, so neither can overwrite the other", async () => {
+		const first = await open(buildNamed("Collections").guard);
+		const second = await open(buildNamed("binary-server · file inspector").guard);
+		expect(first.split("=")[0]).toBe("master_lock_collections");
+		expect(second.split("=")[0]).toBe("master_lock_binary-server-file-inspector");
+		expect(first.split("=")[0]).not.toBe(second.split("=")[0]);
+	});
+
+	/**
+	 * ONE host's cookie jar, behaving as a browser's does: a `Set-Cookie` REPLACES any
+	 * cookie of the same name. That replacement is the whole bug, so a test that joins two
+	 * `Set-Cookie` strings with `; ` proves nothing — `presentedTokens` reads both halves
+	 * and every assertion passes on the broken code too. Measured while writing this.
+	 */
+	const jarOf = (...pairs: string[]): string => {
+		const jar = new Map<string, string>();
+		for (const pair of pairs) {
+			const [name, ...value] = pair.split("=");
+			jar.set(name ?? "", value.join("="));
+		}
+		return [...jar].map(([name, value]) => `${name}=${value}`).join("; ");
+	};
+
+	test("a browser holding BOTH cookies still works each app's own controls", async () => {
+		const a = buildNamed("Collections");
+		const b = buildNamed("binary-server · file inspector");
+		const jar = jarOf(await open(a.guard), await open(b.guard));
+
+		// The exact four routes the collision broke, asked of the app that was unlocked FIRST
+		// — i.e. the one whose cookie the old shared name would have thrown away.
+		expect((await a.guard.handle(post(MASTER_LOCK_PATHS.ping, {}, jar)))?.status).toBe(200);
+		expect(
+			(await a.guard.handle(post(MASTER_LOCK_PATHS.settings, { idleMs: 60_000 }, jar)))?.status,
+		).toBe(200);
+		expect((await a.guard.handle(post(MASTER_LOCK_PATHS.lock, {}, jar)))?.status).toBe(200);
+		expect(a.lock.unlocked).toBe(false);
+		// ...and locking one app left the other exactly as it was.
+		expect(b.lock.unlocked).toBe(true);
+	});
+
+	test("one app's token is not the other's key", async () => {
+		const a = buildNamed("Collections");
+		const b = buildNamed("binary-server · file inspector");
+		const onlyB = jarOf(await open(b.guard));
+		// `a` was never unlocked, so a jar carrying only b's cookie must not open it.
+		expect(a.lock.presents(post(MASTER_LOCK_PATHS.ping, {}, onlyB))).toBe(false);
+		expect((await a.guard.handle(xhr("/api/items", onlyB)))?.status).toBe(401);
+	});
+});