@sigrun/sigrun 0.0.0-stage → 0.1.0

package/dist/harness/health.js

@@ -0,0 +1,30 @@
+/**
+ * The §3 health contract (spec §3): a surface whose implementation can fail
+ * at runtime exposes a health producer; core aggregates the producers
+ * retained at boot into the §5 meta `health` block (Task 9e).
+ *
+ * Producers are SYNCHRONOUS status reads — the meta route calls them per
+ * request, so the route itself never touches the network or storage. In v1
+ * memory backends (through the extension factory result) and provider
+ * contributors implement the contract; a degenerate implementation reports
+ * `"ok"`, and BY CONVENTION the absence of a producer means the same — a
+ * degenerate surface need not synthesize a constant producer.
+ *
+ * SPLIT (build-and-webui Task 1): the `HealthStatus` union's canonical
+ * declaration lives in the `@sigrun/shared` package
+ * (`shared/src/views.ts` — it rides the §5 `meta.health` wire); this
+ * module owns the producer contract and aggregation runtime, re-exporting
+ * the union for server-side importers.
+ */
+/**
+ * Aggregate §3 producers for the §5 `health.providers` field: ANY producer
+ * reporting `"degraded"` degrades the surface; no producers — or all ok —
+ * is `"ok"` (degenerate surfaces report ok by absence, spec §3).
+ */
+export function aggregateHealth(producers) {
+    for (const producer of producers) {
+        if (producer.health() === "degraded")
+            return "degraded";
+    }
+    return "ok";
+}

package/dist/harness/identity/index.js

@@ -0,0 +1,37 @@
+/**
+ * The identity stores bundle (core hardening W1 Task 2): the directory,
+ * tokens, invites, and the setup code, opened over the resolved store
+ * roots — the object `openHarness` exposes as `OpenedHarness.identity`
+ * and the auth pipeline/routes consume.
+ *
+ - `<configDir>/users.json` — the user directory (0600; holds emails);
+ - `<configDir>/api-tokens.json` — the token digests (0600);
+ - `<stateDir>/invites.json` — the invite digests (0600);
+ - `<cacheDir>` — the setup code's home (pod-local, never backed up).
+ *
+ All four files: atomic writes (temp + rename), mtime-reload reads per
+ access (the CLI is a second writer), serialized mutations per store.
+ */
+import { join } from "node:path";
+import { UserDirectory } from "./users.js";
+import { TokenStore, generateToken, hashToken, } from "./tokens.js";
+import { InviteStore, DEFAULT_INVITE_EXPIRY_MS, } from "./invites.js";
+import { ensureSetupCode, readSetupCode, clearSetupCode, generateCode, setupCodePath, CODE_ALPHABET, } from "./setup-code.js";
+export { UserDirectory, TokenStore, generateToken, hashToken, InviteStore, DEFAULT_INVITE_EXPIRY_MS, ensureSetupCode, readSetupCode, clearSetupCode, generateCode, setupCodePath, CODE_ALPHABET, };
+/** The file names each store owns under its root. */
+const USERS_FILE = "users.json";
+const TOKENS_FILE = "api-tokens.json";
+const INVITES_FILE = "invites.json";
+/**
+ * Open the identity stores over resolved roots (cheap — no I/O; every
+ * file is created lazily by its first write). Called by boot after
+ * `ensureStoreRoots`, and by tests directly over tmp dirs.
+ */
+export function openIdentityStores(roots) {
+    return {
+        users: new UserDirectory(join(roots.configDir, USERS_FILE)),
+        tokens: new TokenStore(join(roots.configDir, TOKENS_FILE)),
+        invites: new InviteStore(join(roots.stateDir, INVITES_FILE)),
+        cacheDir: roots.cacheDir,
+    };
+}

package/dist/harness/identity/invites.js

@@ -0,0 +1,94 @@
+/**
+ * The invite store (core hardening W1 Task 2, spec §5.8): ONE
+ * `invites.json` under the state root — admin-issued single-use codes
+ * that admit one directory user each.
+ *
+ - codes are the setup-code alphabet shape (`XXXX-XXXX`) but UNPINNED
+   by any env var — every `create` draws a fresh one;
+ - only the SHA-256 digest is stored (the same `hashToken` discipline
+   as tokens — a leaked file admits no one);
+ - single-use: a redeemed row keeps its `usedBy` FOREVER (Review
+   Focus 4) — an expired redeem returns undefined without touching the
+   row, and a used row past its expiry stays used, never re-openable;
+ - expiry compares epoch-ms `expiresAt` against the (injectable) now,
+   so clock-skewed cases are testable;
+ - mode `0600`, atomic writes, mtime-reload reads, mutating calls
+   serialized on the store's {@link MutationQueue} — two concurrent
+   redeems of one code yield exactly one success.
+ *
+ * The SETUP CODE is deliberately not a row here: it lives under the
+ * cache root (never a backup section) and is compared directly. It is
+ * the first invite only as a behavioral equivalence — it admits one
+ * admin claim.
+ */
+import { randomUUID, timingSafeEqual } from "node:crypto";
+import { generateCode } from "./setup-code.js";
+import { hashToken } from "./tokens.js";
+import { MutationQueue, readRecords, writeJson } from "./json-store.js";
+/** Default invite expiry: 7 days in ms (spec §5.8). */
+export const DEFAULT_INVITE_EXPIRY_MS = 604_800_000;
+/** Constant-time digest equality (delegates to the token discipline). */
+function matchesCode(record, digest) {
+    if (record.sha256.length !== digest.length)
+        return false;
+    return timingSafeEqual(Buffer.from(record.sha256, "hex"), Buffer.from(digest, "hex"));
+}
+/**
+ * The file-backed invite store. `redeem` is the single mutator; both
+ * methods serialize on the store's {@link MutationQueue}.
+ */
+export class InviteStore {
+    path;
+    mutations = new MutationQueue();
+    constructor(path) {
+        this.path = path;
+    }
+    list() {
+        return readRecords(this.path);
+    }
+    /**
+     * Issue one invite: draws a fresh code, stores only its digest plus
+     * the grant and expiry (`expiresInMs` defaults to 7 days), and
+     * returns `{id, code, expiresAt}` — the code is shown once, by the
+     * caller; the expiry rides along so the issuing route serves the
+     * wire's `expiresAt` from the stored row, not a recomputed clock.
+     */
+    create(opts) {
+        return this.mutations.run(async () => {
+            const code = generateCode();
+            const record = {
+                id: randomUUID(),
+                sha256: hashToken(code),
+                admin: opts.admin,
+                expiresAt: Date.now() + (opts.expiresInMs ?? DEFAULT_INVITE_EXPIRY_MS),
+            };
+            await writeJson(this.path, [...this.list(), record]);
+            return { id: record.id, code, expiresAt: record.expiresAt };
+        });
+    }
+    /**
+     * Redeem one code for `user`: undefined when no record matches the
+     * digest, when the row is already used (single-use, forever), or
+     * when `now` is past `expiresAt` — and in every undefined case the
+     * row is left untouched (an expired-but-unused invite is not marked,
+     * a used row keeps its `usedBy` past expiry). A success stamps
+     * `usedBy` atomically and returns the grant.
+     */
+    redeem(code, user, now = Date.now()) {
+        return this.mutations.run(async () => {
+            const records = this.list();
+            const digest = hashToken(code);
+            const index = records.findIndex((record) => matchesCode(record, digest));
+            const record = index === -1 ? undefined : records[index];
+            if (record === undefined)
+                return undefined;
+            if (record.usedBy !== undefined)
+                return undefined;
+            if (now > record.expiresAt)
+                return undefined;
+            records[index] = { ...record, usedBy: user };
+            await writeJson(this.path, records);
+            return { admin: record.admin };
+        });
+    }
+}

package/dist/harness/identity/json-store.js

@@ -0,0 +1,108 @@
+/**
+ * The mtime-reloading JSON file helper behind every identity store
+ * (core hardening W1 Task 2, spec §5.4 "Store semantics"): identity
+ * files are small, mutated by whole-file read-modify-write, and shared
+ * with the CLI — a SEPARATE process — so:
+ *
+ - reads are SYNCHRONOUS and reload whenever the file's
+   `(mtimeMs, size)` fingerprint changes, checked per access (a CLI
+   revoke or user add is honored live, no restart);
+ - writes go through {@link writeFileAtomic} (temp file + rename, mode
+   `0600`), so a concurrent reader sees the old complete file or the
+   new complete file — never a half-written one (Review Focus 5).
+ *
+ * The read cache is module-wide and keyed by path: store instances on
+ * the same path share one entry, validated against the file's CURRENT
+ * stat per access, so a write through one instance is immediately
+ * visible through another. Cross-process, the same stat check is the
+ * contract (mtime granularity + size; a same-ms same-size clobber is
+ * the accepted last-writer-wins at household scale).
+ *
+ * A malformed file (unparseable JSON, or a non-array where a record
+ * array is expected) fails LOUD, naming the path — the
+ * `readJsonObject` posture: never a silent reset of identity data.
+ */
+import { readFileSync, statSync } from "node:fs";
+import { writeFileAtomic } from "../stores.js";
+/**
+ * path → the last parse and the stat it was read under. Module-wide
+ * (never per-store): two store instances over one file are one cache.
+ */
+const cache = new Map();
+/**
+ * Read one JSON file, reloading when its stat fingerprint changed since
+ * the last read of this path (checked on EVERY call). Absent file →
+ * `fallback` (first use is not an error); the absent state is uncached
+ * so the file's creation is seen by the very next read. Unparseable
+ * JSON fails loud, naming the path (never a silent reset of identity
+ * data).
+ */
+export function readJson(path, fallback) {
+    let stat;
+    try {
+        stat = statSync(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            cache.delete(path);
+            return fallback;
+        }
+        throw error;
+    }
+    const cached = cache.get(path);
+    if (cached !== undefined &&
+        cached.mtimeMs === stat.mtimeMs &&
+        cached.size === stat.size) {
+        return cached.value;
+    }
+    let value;
+    try {
+        value = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`sigrun: malformed JSON in ${path}: ${String(error)}`, { cause: error });
+    }
+    cache.set(path, { mtimeMs: stat.mtimeMs, size: stat.size, value });
+    return value;
+}
+/**
+ * Read a record-array store file: absent → `[]`; anything but a JSON
+ * array is a malformed store, loud with the path named.
+ */
+export function readRecords(path) {
+    const value = readJson(path, []);
+    if (!Array.isArray(value)) {
+        throw new Error(`sigrun: ${path} must contain a JSON array of records`);
+    }
+    return value;
+}
+/**
+ * Write one JSON value the house way (tabs, trailing newline),
+ * atomically, mode `0600` — identity files all carry credential
+ * material (token hashes, emails, invite hashes). The path's cache
+ * entry is invalidated (never eagerly re-statted): the next read
+ * re-stats and sees the new file.
+ */
+export async function writeJson(path, value) {
+    await writeFileAtomic(path, `${JSON.stringify(value, null, "\t")}\n`, 0o600);
+    cache.delete(path);
+}
+/**
+ * A per-store-instance FIFO mutex (the "store semantics" serialization
+ * rule): every mutating method chains on one tail promise, so
+ * concurrent calls run strictly one-at-a-time and each sees the prior
+ * one's write — two concurrent redeems of one invite code yield
+ * exactly one success. A rejected operation never poisons the tail.
+ * Two instances over one path each serialize their OWN calls; across
+ * instances (and processes) atomic rename keeps files whole, with
+ * last-writer-wins the accepted resolution.
+ */
+export class MutationQueue {
+    tail = Promise.resolve();
+    /** Chain `op` on the tail; resolves/rejects with op's own outcome. */
+    run(op) {
+        const next = this.tail.then(op, op);
+        this.tail = next.then(() => undefined, () => undefined);
+        return next;
+    }
+}

package/dist/harness/identity/setup-code.js

@@ -0,0 +1,81 @@
+/**
+ * The setup code (core hardening W1 Task 2, spec §5.8): the one-shot
+ * onboarding credential an unclaimed server accepts — `XXXX-XXXX`,
+ * eight characters from a 32-char unambiguous alphabet (no `I`/`O`/`0`/
+ * `1` — readable over a pod log or a phone).
+ *
+ - pinned by `SIGRUN_SETUP_CODE` (env only — the k8s Secret shape) or
+   generated fresh at each unclaimed boot;
+ - written to `<cacheDir>/setup-code`, mode `0600`, atomically — the
+   CACHE root is pod-local and never a backup section, so the code
+   never lands in a backup, while `kubectl exec … cat` retrieves it;
+ - the cache root is deliberately NOT assumed to exist (the wiped-
+   `emptyDir` posture, stores.ts Review Focus 5): every write recreates
+   it at call time;
+ - deleted at claim (`clearSetupCode`), idempotently.
+ *
+ * The code is NOT an `InviteStore` row (see invites.ts): it is compared
+ * directly by the onboarding route — "the first invite" is a behavioral
+ * equivalence, not a storage fact.
+ */
+import { readFileSync } from "node:fs";
+import { mkdir, rm } from "node:fs/promises";
+import { randomInt } from "node:crypto";
+import { join } from "node:path";
+import { writeFileAtomic } from "../stores.js";
+/** The unambiguous alphabet (spec §5.8): 32 chars, no `I`/`O`/`0`/`1`. */
+export const CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+/** The code file name under the cache root. */
+const SETUP_CODE_FILE = "setup-code";
+/** The env var that pins the code (k8s Secret shape; env only). */
+const SETUP_CODE_ENV = "SIGRUN_SETUP_CODE";
+/** `<cacheDir>/setup-code`. */
+export function setupCodePath(cacheDir) {
+    return join(cacheDir, SETUP_CODE_FILE);
+}
+/**
+ * Draw one code: `XXXX-XXXX`, 8 characters from {@link CODE_ALPHABET}
+ * (`randomInt` — unbiased over the 32-symbol space). Invites reuse this
+ * draw for their code shape.
+ */
+export function generateCode() {
+    const pick = () => CODE_ALPHABET.charAt(randomInt(CODE_ALPHABET.length));
+    return `${pick()}${pick()}${pick()}${pick()}-${pick()}${pick()}${pick()}${pick()}`;
+}
+/**
+ * Ensure the setup code exists and return it: the `SIGRUN_SETUP_CODE`
+ * pin wins (trimmed; an empty value counts as unset, the module-wide
+ * ""-means-unset reading), else a fresh code is drawn. The code is
+ * (re)written to `<cacheDir>/setup-code` mode `0600` atomically every
+ * call — each unclaimed boot refreshes the file, and a pinned code
+ * self-heals a wiped cache root.
+ */
+export async function ensureSetupCode(cacheDir, env) {
+    const pinned = env[SETUP_CODE_ENV];
+    const code = pinned !== undefined && pinned !== "" ? pinned.trim() : generateCode();
+    await mkdir(cacheDir, { recursive: true });
+    await writeFileAtomic(setupCodePath(cacheDir), `${code}\n`, 0o600);
+    return code;
+}
+/**
+ * Read the persisted code; absent file → undefined. Whitespace is
+ * trimmed (the file carries one trailing newline); an empty file reads
+ * as undefined.
+ */
+export function readSetupCode(cacheDir) {
+    let text;
+    try {
+        text = readFileSync(setupCodePath(cacheDir), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    const code = text.trim();
+    return code === "" ? undefined : code;
+}
+/** Delete the code file (the claim step); absent file is a no-op. */
+export async function clearSetupCode(cacheDir) {
+    await rm(setupCodePath(cacheDir), { force: true });
+}

package/dist/harness/identity/tokens.js

@@ -0,0 +1,101 @@
+/**
+ * The API token store (core hardening W1 Task 2, spec §5.4): ONE
+ * `api-tokens.json` at the config root — the bearer-credential surface
+ * for TUI `attach`, scripts, and browser login.
+ *
+ - tokens are `sgr_` + base64url(32 random bytes) — shown ONCE at
+   create, never persisted;
+ - only the SHA-256 hex digest is stored (`sha256`), and verification
+   compares digests with `timingSafeEqual` on equal-length buffers;
+ - mode `0600`, atomic writes, mtime-reload reads (the CLI's
+   `sigrun token` subcommands are a second writer, honored live);
+ - `user` names the directory user whose rights the token carries —
+   admin is a property of the user, never of the token.
+ */
+import { createHash, randomBytes, randomUUID, timingSafeEqual, } from "node:crypto";
+import { MutationQueue, readRecords, writeJson } from "./json-store.js";
+/** The token wire prefix (the `sk-`/`sgr_` convention; spec §5.4). */
+const TOKEN_PREFIX = "sgr_";
+/** A fresh token: `sgr_` + 32 random bytes in base64url (43 chars). */
+export function generateToken() {
+    return `${TOKEN_PREFIX}${randomBytes(32).toString("base64url")}`;
+}
+/** The stored form of a token: its SHA-256 hex digest. */
+export function hashToken(token) {
+    return createHash("sha256").update(token).digest("hex");
+}
+/** Constant-time digest equality (equal-length buffers, spec §5.4). */
+function sameDigest(stored, digest) {
+    if (stored.length !== digest.length)
+        return false;
+    return timingSafeEqual(Buffer.from(stored, "hex"), Buffer.from(digest, "hex"));
+}
+/**
+ * The file-backed token store. Reads/verifications are synchronous
+ * (mtime reload per access); creates/revokes serialize on the store's
+ * {@link MutationQueue}.
+ */
+export class TokenStore {
+    path;
+    mutations = new MutationQueue();
+    constructor(path) {
+        this.path = path;
+    }
+    /** All records, or one user's with `user` given (no secrets exist to omit). */
+    list(user) {
+        const records = readRecords(this.path);
+        return user === undefined
+            ? records
+            : records.filter((record) => record.user === user);
+    }
+    /**
+     * Verify a presented token: hash it, compare against every stored
+     * digest with `timingSafeEqual`. Absent/unknown/malformed → undefined.
+     */
+    verify(token) {
+        const digest = hashToken(token);
+        return this.list().find((record) => sameDigest(record.sha256, digest));
+    }
+    /**
+     * Mint one token for `user`: generates the secret, stores ONLY its
+     * digest, and returns both — the token is shown once, by the caller.
+     */
+    create(name, user) {
+        return this.mutations.run(async () => {
+            const token = generateToken();
+            const record = {
+                id: randomUUID(),
+                name,
+                user,
+                sha256: hashToken(token),
+                createdAt: Date.now(),
+            };
+            await writeJson(this.path, [...this.list(), record]);
+            return { record, token };
+        });
+    }
+    /** Revoke by record id; false when no such record existed. */
+    revoke(id) {
+        return this.mutations.run(async () => {
+            const records = this.list();
+            const index = records.findIndex((record) => record.id === id);
+            if (index === -1)
+                return false;
+            records.splice(index, 1);
+            await writeJson(this.path, records);
+            return true;
+        });
+    }
+    /** Revoke every token of one user (user removal's companion); returns the count. */
+    revokeAllFor(user) {
+        return this.mutations.run(async () => {
+            const records = this.list();
+            const kept = records.filter((record) => record.user !== user);
+            const removed = records.length - kept.length;
+            if (removed > 0) {
+                await writeJson(this.path, kept);
+            }
+            return removed;
+        });
+    }
+}

package/dist/harness/identity/users.js

@@ -0,0 +1,93 @@
+/**
+ * The user directory (core hardening W1 Task 2, spec §5.8): ONE
+ * `users.json` at the config root — the identity source for owner
+ * stamping, share pickers, and admin checks. Mode `0600` (it holds
+ * emails), atomic writes, mtime-reload reads (the shared json-store
+ * discipline — the CLI is a second writer, honored live).
+ *
+ * `user` matches `^[a-z0-9][a-z0-9._-]*$` and is IMMUTABLE — the
+ * identity other records key on; renames are delete + add by design.
+ * The server is unclaimed while the directory is empty and claimed
+ * after the first add (`isClaimed`); `admin` is a property of the USER
+ * (tokens carry their user's rights — never their own admin flag).
+ */
+import { MutationQueue, readRecords, writeJson } from "./json-store.js";
+/** The username rule (spec §5.8): lowercase-first, then `[a-z0-9._-]`. */
+const USERNAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+/**
+ * The file-backed user directory. Reads are synchronous (mtime reload
+ * per access); every mutation is a whole-file read-modify-write that
+ * serializes on the store's {@link MutationQueue}.
+ */
+export class UserDirectory {
+    path;
+    mutations = new MutationQueue();
+    constructor(path) {
+        this.path = path;
+    }
+    /** Every user, insertion order (the first add is the onboarding claim). */
+    list() {
+        return readRecords(this.path);
+    }
+    /** One user by exact username; absent → undefined. */
+    get(user) {
+        return this.list().find((record) => record.user === user);
+    }
+    /** True once the first user exists — the server's claimed state. */
+    isClaimed() {
+        return this.list().length > 0;
+    }
+    /** How many users carry `admin` (invite-issuing route guards read it). */
+    recordAdminCount() {
+        return this.list().filter((record) => record.admin).length;
+    }
+    /**
+     * Add one user (spec §5.8): rejects an invalid username and a
+     * duplicate, both loud with the username named. `createdAt` is
+     * stamped here, never by the caller.
+     */
+    add(user) {
+        return this.mutations.run(async () => {
+            if (!USERNAME_PATTERN.test(user.user)) {
+                throw new Error(`invalid username "${user.user}": must match ^[a-z0-9][a-z0-9._-]*$`);
+            }
+            const records = this.list();
+            if (records.some((record) => record.user === user.user)) {
+                throw new Error(`user "${user.user}" already exists`);
+            }
+            const record = { ...user, createdAt: Date.now() };
+            await writeJson(this.path, [...records, record]);
+            return record;
+        });
+    }
+    /**
+     * Patch one user's mutable fields (`name`/`email`/`admin` — the
+     * username itself is immutable). Absent user throws; the file is
+     * rewritten atomically.
+     */
+    update(user, patch) {
+        return this.mutations.run(async () => {
+            const records = this.list();
+            const index = records.findIndex((record) => record.user === user);
+            if (index === -1) {
+                throw new Error(`unknown user "${user}"`);
+            }
+            const updated = { ...records[index], ...patch };
+            records[index] = updated;
+            await writeJson(this.path, records);
+            return updated;
+        });
+    }
+    /** Remove one user (their tokens are NOT revoked here — caller's job). */
+    remove(user) {
+        return this.mutations.run(async () => {
+            const records = this.list();
+            const index = records.findIndex((record) => record.user === user);
+            if (index === -1) {
+                throw new Error(`unknown user "${user}"`);
+            }
+            records.splice(index, 1);
+            await writeJson(this.path, records);
+        });
+    }
+}