@sigrun/sigrun 0.0.0-stage → 0.1.1

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,28 @@
+# Third-party notices
+
+## hermes-webui
+
+- <https://github.com/nesquena/hermes-webui>
+- sigrun's web UI visual design is adapted from hermes-webui.
+
+MIT License
+
+Copyright (c) 2025 Hermes Web UI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/backup/marker.js

@@ -0,0 +1,80 @@
+/**
+ * The backup last-success marker (core-hardening §6.8, R15 — "backup
+ * honesty"): `run-backup.ts` stamps `<stateDir>/backup/last-success.json`
+ * after a successful run, and `GET /v1/meta` reads it PER REQUEST to
+ * derive `health.backup` — before this, a configured-but-silently-failing
+ * CronJob still reported "configured" (the badge lied).
+ *
+ * Read posture: the marker is observability, never a gate. An absent,
+ * unreadable, unparseable, or wrong-shape marker reads as `undefined`
+ * — which DERIDES health ("degraded") but never fails the request. A
+ * corrupt marker must cost the badge, not the endpoint.
+ */
+import { mkdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { writeFileAtomic } from "../harness/stores.js";
+/** The marker's directory + filename under the state root. */
+export const BACKUP_MARKER_DIR = "backup";
+export const BACKUP_MARKER_NAME = "last-success.json";
+/** The marker's path under a state root. */
+export function backupMarkerPath(stateDir) {
+    return join(stateDir, BACKUP_MARKER_DIR, BACKUP_MARKER_NAME);
+}
+/**
+ * Write the marker: mkdir the `backup/` dir, then atomic-replace with
+ * mode 0644 (an operator file — unlike secrets, nothing in it is
+ * sensitive; 0644 keeps `kubectl exec … cat` and restores simple).
+ */
+export async function writeBackupMarker(stateDir, marker) {
+    await mkdir(join(stateDir, BACKUP_MARKER_DIR), { recursive: true });
+    await writeFileAtomic(backupMarkerPath(stateDir), `${JSON.stringify(marker, null, "\t")}\n`, 0o644);
+}
+/** Structural check: every field present and correctly typed — `at`
+ * must PARSE as a timestamp too (a marker whose `at` is garbage reads as
+ * no marker: surfacing an unparseable `lastSuccessAt` on the wire would
+ * trade a honest degraded badge for a confusing one). */
+function isBackupMarker(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    return (typeof record.at === "string" &&
+        Number.isFinite(Date.parse(record.at)) &&
+        (record.target === "path" || record.target === "s3") &&
+        typeof record.bytes === "number" &&
+        Number.isFinite(record.bytes));
+}
+/**
+ * Read the marker from a state root. `undefined` when absent (ENOENT) —
+ * and when anything else is wrong with it (unreadable, unparseable,
+ * wrong shape): a marker that cannot be trusted must not read as a
+ * success.
+ */
+export async function readBackupMarker(stateDir) {
+    let raw;
+    try {
+        raw = await readFile(backupMarkerPath(stateDir), "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    return isBackupMarker(parsed) ? parsed : undefined;
+}
+/**
+ * Whether a marker is stale: `now - at` strictly beyond
+ * `staleAfterHours` hours. A marker whose `at` does not parse as a
+ * timestamp is stale by definition (the derivation never surfaces it,
+ * but the pure rule stays total).
+ */
+export function isBackupMarkerStale(marker, staleAfterHours, now = Date.now()) {
+    const at = Date.parse(marker.at);
+    if (!Number.isFinite(at))
+        return true;
+    return now - at > staleAfterHours * 60 * 60 * 1000;
+}

package/dist/backup/run-backup.js

@@ -0,0 +1,339 @@
+/**
+ * The optional backup script (spec §4.3, Task 11) — the CronJob's payload.
+ *
+ * Invoked (tsx / node) with `SIGRUN_STORAGE_PATH` pointing at the live
+ * harness sqlite database plus the backup target env (see
+ * `parseBackupConfig`). It takes a `sqlite3 .backup` — sqlite3's online
+ * backup API (`.backup`): ONLINE-SAFE, it locks the source only per
+ * page, so the copy is consistent even while the harness process holds
+ * the database in WAL mode (a second process touching the file is
+ * exactly the class of assumption spec §4.3's App C ledger rule covers;
+ * the restore drill in test/backup.test.ts verifies it live).
+ *
+ * Flow, fail-loud at every step:
+ *  1. `sqlite3 <db> ".backup '<tmpfile>'"` into a sibling temp file (same
+ *     filesystem as the target for the atomic rename; never a half-written
+ *     target). A sqlite3 failure deletes the temp file and exits non-zero
+ *     (sqlite3 leaves a 0-byte file on failure — it must not survive).
+ *  2. path target: rename into `<dir>/sigrun-<UTC timestamp>.db`, then
+ *     30-day retention (`applyRetention`).
+ *  2'. s3 target: `PutObject` the temp file to
+ *     `s3://<bucket>[/<prefix>]sigrun-<UTC timestamp>.db`. Endpoint and
+ *     credentials come from the environment (`AWS_*`,
+ *     `SIGRUN_BACKUP_S3_ENDPOINT`) — core secrets per spec §4.3, injected
+ *     into the CronJob from a Secret. A failed upload exits non-zero.
+ *  3. No backup target env → exit 1 with a config error (the CronJob must
+ *     not silently do nothing).
+ *
+ * Last-success marker (§6.8 backup honesty): after a run succeeds — the
+ * db rename/upload AND every enabled section — the script writes
+ * `<SIGRUN_STATE_DIR>/backup/last-success.json` (`{at, target, bytes}`, 0644,
+ * atomic; see `marker.ts`), which `GET /v1/meta` reads per request to
+ * derive `health.backup` (absent or older than `server.backup.staleAfterHours`,
+ * default 36 h → "degraded"). With `SIGRUN_STATE_DIR` unset the script WARNS
+ * and skips the marker — the backup itself still succeeds; refusing to
+ * guess the state root matters because a marker written where the server
+ * does not read it would read as fresh backups that exist nowhere.
+ *
+ * The script deliberately touches NOTHING but the db file and the target —
+ * no pi-durable internals, no lock negotiation; that is the whole point of
+ * `sqlite3 .backup` over an application-level snapshot.
+ */
+import { spawn } from "node:child_process";
+import { chmod, mkdtemp, readdir, rename, rm, stat, unlink } from "node:fs/promises";
+import { realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { PutObjectCommand, S3Client, } from "@aws-sdk/client-s3";
+import { readFile } from "node:fs/promises";
+import { parseBackupConfig } from "../config.js";
+import { resolveStoreRoots } from "../harness/stores.js";
+import { writeBackupMarker } from "./marker.js";
+/** Retention floor (spec §4.3: "retention ≥ 30 days"). */
+export const BACKUP_RETENTION_DAYS = 30;
+/** The db path under backup — `SIGRUN_STORAGE_PATH` in deployment. */
+const DB_PATH = process.env.SIGRUN_STORAGE_PATH ?? "";
+/** Promise-wrapped spawn: a step's exit code and stderr. */
+function run(command, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: ["ignore", "ignore", "pipe"] });
+        let stderr = "";
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+        });
+        child.on("error", reject);
+        child.on("close", (code) => resolve({ code: code ?? -1, stderr }));
+    });
+}
+/**
+ * Timestamp segment of a backup filename: `2026-10-07T03-15-02Z` — UTC,
+ * sortable, colon-free (safe on every filesystem / object-store key).
+ */
+function timestampSegment(date = new Date()) {
+    return date.toISOString().replace(/:/g, "-").slice(0, 19) + "Z";
+}
+/** Run `sqlite3 <db> ".backup '<dest>'"`; fail loud on a non-zero exit. */
+async function sqliteBackup(dbPath, dest) {
+    // The quoting inside the dot-command is sqlite3's own (the dot-command
+    // parser treats the quoted string as one filename; an unquoted path with
+    // spaces would split).
+    const result = await run("sqlite3", [dbPath, `.backup '${dest}'`]);
+    if (result.code !== 0) {
+        // sqlite3 leaves a 0-byte dest on failure — a later restore would
+        // open a valid EMPTY database and "resume" to nothing. Delete it.
+        await rm(dest, { force: true });
+        throw new Error(`sqlite3 .backup failed with exit ${result.code}: ${result.stderr.trim()}`);
+    }
+}
+/**
+ * Path-target retention: delete `sigrun-*.db` files in `dir` whose mtime is
+ * older than {@link BACKUP_RETENTION_DAYS} days. Non-matching names are
+ * never touched (the directory is the deployment's backup dir, but it is
+ * still conservative to prune only what this script produced).
+ */
+export async function applyRetention(dir) {
+    const cutoff = Date.now() - BACKUP_RETENTION_DAYS * 24 * 60 * 60 * 1000;
+    for (const name of await readdir(dir)) {
+        if (!name.startsWith("sigrun-") || !name.endsWith(".db"))
+            continue;
+        const path = join(dir, name);
+        const info = await stat(path);
+        if (info.mtimeMs < cutoff)
+            await unlink(path);
+    }
+}
+/**
+ * The S3 client the uploads go through. A module-level factory with the
+ * real client as its default: the test swaps in a recording fake, and the
+ * deployment path is untouched (no public API surface beyond this seam).
+ *
+ * Credentials come from the SDK's own default provider chain — the
+ * standard `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` /
+ * `AWS_REGION` env, or an AWS config file. sigrun adds no credential
+ * settings of its own.
+ */
+/** The production client factory — what a restore puts back. */
+const defaultS3ClientFactory = (config) => new S3Client(config);
+let s3ClientFactory = defaultS3ClientFactory;
+/** Replace the S3 client factory; `undefined` restores the production one. */
+export function setS3ClientFactory(factory) {
+    s3ClientFactory = factory ?? defaultS3ClientFactory;
+}
+/**
+ * The client config for a backup target: an endpoint means an
+ * S3-COMPATIBLE store (MinIO, RustFS, …), which needs path-style
+ * addressing — `bucket.host` virtual-host addressing does not resolve
+ * there. No endpoint = AWS's own endpoints, virtual-host style.
+ */
+function s3ClientConfig() {
+    const endpoint = process.env.SIGRUN_BACKUP_S3_ENDPOINT;
+    return endpoint === undefined || endpoint === ""
+        ? {}
+        : { endpoint, forcePathStyle: true };
+}
+/**
+ * Put one local file at `key` in the target bucket. The bytes are read
+ * once and sent as a Buffer: the SDK would otherwise want a stream, and
+ * the files here are a sqlite snapshot and small tarballs — reading them
+ * is the honest, testable shape. Failures reject with the SDK's error.
+ */
+async function s3Put(backup, key, file) {
+    const client = s3ClientFactory(s3ClientConfig());
+    try {
+        await client.send(new PutObjectCommand({
+            Bucket: backup.bucket,
+            Key: key,
+            Body: await readFile(file),
+        }));
+    }
+    catch (cause) {
+        throw new Error(`s3 upload of ${key} to ${backup.bucket} failed: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    }
+    finally {
+        client.destroy();
+    }
+}
+/** Upload the backup to the s3 target; fail loud when the upload fails. */
+async function s3Upload(backup, file) {
+    await s3Put(backup, `${backup.prefix ?? ""}sigrun-${timestampSegment()}.db`, file);
+}
+/**
+ * One backup run: take the sqlite backup, then ship it to the target.
+ * Exported for the test's direct (in-process) invocation; the script's
+ * main() wraps it with env parsing and process exit codes.
+ *
+ * `stateDir` (§6.8): where the last-success marker is written after the
+ * WHOLE run settles (db + sections) — a run whose section leg failed must
+ * not refresh the marker, or the badge would hide the failure the exit
+ * code records. `undefined` skips the marker with a warning (the run
+ * itself still succeeds).
+ */
+export async function runBackup(dbPath, backup, stateDir) {
+    if (!dbPath) {
+        throw new Error("SIGRUN_STORAGE_PATH is required (the db to back up)");
+    }
+    // sqlite3 opens its source with create flags: a MISSING db file backs up
+    // "successfully" as an empty database (a SIGRUN_STORAGE_PATH typo or a
+    // CronJob firing before first boot would then produce nightly empty
+    // backups indistinguishable from real ones). Fail loud instead.
+    const dbStat = await stat(dbPath).catch(() => undefined);
+    if (dbStat === undefined || dbStat.size === 0) {
+        throw new Error(`database ${dbPath} does not exist or is empty — refusing to back up nothing`);
+    }
+    // Temp file in the TARGET's filesystem (path target) so the final move
+    // is an atomic rename, not a copy; for s3 the temp dir is irrelevant to
+    // atomicity (the upload is the move) so the OS temp dir serves.
+    const tempDir = backup.target === "path" ? backup.path : tmpdir();
+    const tempFile = join(await mkdtemp(join(tempDir, ".sigrun-backup-")), `backup-${timestampSegment()}.db`);
+    // The shipped size for the marker — captured inside the try after the
+    // sqlite step, read by the marker write below (rename/upload/cleanup all
+    // consume the temp file, so the size must be taken while it exists).
+    let bytes = 0;
+    try {
+        await sqliteBackup(dbPath, tempFile);
+        bytes = (await stat(tempFile)).size;
+        if (backup.target === "path") {
+            const dest = join(backup.path, `sigrun-${timestampSegment()}.db`);
+            await rename(tempFile, dest);
+            await applyRetention(backup.path);
+        }
+        else {
+            await s3Upload(backup, tempFile);
+        }
+    }
+    finally {
+        // The temp file survives only on the failure paths between sqlite
+        // success and the rename/upload — always clean it up.
+        await rm(tempFile, { force: true });
+        await rm(dirname(tempFile), { force: true, recursive: true });
+    }
+    // Sections fold in AFTER the DB steps (Task 7): with no sections
+    // enabled the loop is a no-op and the run is byte-identical to the
+    // DB-only contract.
+    await backupSections(backup);
+    // §6.8: the marker — after EVERYTHING above succeeded (see the
+    // docblock for why a sections failure must leave it stale). A marker
+    // WRITE failure warns and is swallowed (fix round 1): the marker is
+    // observability, never a gate — a read-only state dir or a full disk
+    // must not turn a completed backup into a failed one. The consequence
+    // is honest: the server reads no marker and reports degraded.
+    if (stateDir === undefined) {
+        console.warn("SIGRUN_STATE_DIR is not set — skipping the backup last-success marker " +
+            "(the backup itself succeeded; set SIGRUN_STATE_DIR on the CronJob and " +
+            "the server to the same root so health.backup can see it)");
+        return;
+    }
+    try {
+        await writeBackupMarker(stateDir, {
+            at: new Date().toISOString(),
+            target: backup.target,
+            bytes,
+        });
+    }
+    catch (error) {
+        console.warn(`backup succeeded but writing the last-success marker under ${stateDir} failed: ${String(error)} ` +
+            "(health.backup will report degraded until this is fixed)");
+    }
+}
+/** The store root each backup section tars. */
+const SECTION_ROOTS = {
+    // config and secrets both live under the config root (settings.json /
+    // auth.json); secrets differs by its 0600 tarball mode.
+    config: "configDir",
+    secrets: "configDir",
+    data: "dataDir",
+    state: "stateDir",
+};
+/**
+ * Sections whose content can carry secret files → tarball mode 0600
+ * (fix round 1). `config` tars the same root as `secrets`, so its
+ * archive carries auth.json too and must share the mode; `data` and
+ * `state` carry no key material and stay at the umask default.
+ */
+const SECRET_SECTIONS = new Set([
+    "config",
+    "secrets",
+]);
+/** Tar one section's root directory into `tarball`; fail loud on error. */
+async function tarSection(sourceDir, tarball) {
+    // `-C source .` keeps the entries relative (settings.json, not
+    // /data/config/settings.json) and sidesteps tar's leading-`/` strip.
+    const result = await run("tar", ["-czf", tarball, "-C", sourceDir, "."]);
+    if (result.code !== 0) {
+        await rm(tarball, { force: true });
+        throw new Error(`tar of ${sourceDir} failed with exit ${result.code}: ${result.stderr.trim()}`);
+    }
+}
+/** Upload one section tarball to the s3 target; fail loud when it fails. */
+async function s3UploadSection(backup, file, name) {
+    await s3Put(backup, `${backup.prefix ?? ""}${name}`, file);
+}
+/**
+ * The per-section opt-in (Task 7): for each enabled section, tar its
+ * store root (`resolveStoreRoots(process.env)` — the same chain boot
+ * uses) into `<section>-<UTC timestamp>.tar.gz` and ship it to the
+ * target. Sections whose content can carry secret files get mode 0600
+ * (fix round 1: config tars the same root as secrets — auth.json rides
+ * BOTH tarballs, and in-archive modes don't gate extraction, so the
+ * config ARCHIVE itself must be 0600 too or enabling `config` would
+ * defeat the secrets tarball's mode). No enabled sections → no-op.
+ */
+async function backupSections(backup) {
+    const enabled = Object.keys(SECTION_ROOTS).filter((name) => backup.sections?.[name] === true);
+    if (enabled.length === 0)
+        return;
+    const roots = resolveStoreRoots(process.env);
+    for (const name of enabled) {
+        const tarballName = `${name}-${timestampSegment()}.tar.gz`;
+        if (backup.target === "path") {
+            const dest = join(backup.path, tarballName);
+            await tarSection(roots[SECTION_ROOTS[name]], dest);
+            if (SECRET_SECTIONS.has(name))
+                await chmod(dest, 0o600);
+        }
+        else {
+            // Tar to the OS temp dir, upload, clean up — same shape as the
+            // DB's s3 leg (the upload is the move).
+            const tempFile = join(await mkdtemp(join(tmpdir(), ".sigrun-backup-section-")), tarballName);
+            try {
+                await tarSection(roots[SECTION_ROOTS[name]], tempFile);
+                await s3UploadSection(backup, tempFile, tarballName);
+            }
+            finally {
+                await rm(tempFile, { force: true });
+                await rm(dirname(tempFile), { force: true, recursive: true });
+            }
+        }
+    }
+}
+/**
+ * Script entry — runs only when executed directly (tsx run-backup.ts / a
+ * built node dist), not when the test imports `runBackup` in-process.
+ * Compares the realpath of argv[1] with this module (tsx and ts-node both
+ * keep argv[1] as the script path).
+ */
+const invokedAsScript = (() => {
+    if (process.argv[1] === undefined)
+        return false;
+    try {
+        return fileURLToPath(import.meta.url) === realpathSync(process.argv[1]);
+    }
+    catch {
+        return false;
+    }
+})();
+if (invokedAsScript) {
+    const backup = parseBackupConfig(process.env);
+    if (backup === undefined) {
+        console.error("No backup target configured: set SIGRUN_BACKUP_PATH or SIGRUN_BACKUP_S3_BUCKET");
+        process.exit(1);
+    }
+    try {
+        await runBackup(DB_PATH, backup, process.env.SIGRUN_STATE_DIR?.trim() || undefined);
+    }
+    catch (error) {
+        console.error(`sigrun backup failed: ${String(error)}`);
+        process.exit(1);
+    }
+}