@lelouchhe/webagent 0.2.6 → 0.4.0

package/lib/attachments.js

@@ -0,0 +1,154 @@
+// Helpers for the attachment upload pipeline. The upload handler in
+// routes.ts threads request -> busboy -> stream-to-disk -> DB row using
+// these primitives. Everything here is server-only; clients never see
+// realpaths or temp filenames.
+import { fileTypeFromBuffer } from "file-type";
+/**
+ * Server-controlled mime → file extension map (uploads-plan v2.6 §14).
+ *
+ * The disk extension is derived from the mime type, NOT the client-supplied
+ * filename. That way a client lying about the extension cannot trick disk
+ * tooling that uses extension-based heuristics. Anything not in the table
+ * falls through to `.bin` so `mime` and `ext` stay consistent.
+ */
+const MIME_TO_EXT = {
+    "image/png": "png",
+    "image/jpeg": "jpg",
+    "image/gif": "gif",
+    "image/webp": "webp",
+    "image/svg+xml": "svg",
+    "application/pdf": "pdf",
+    "text/plain": "txt",
+    "text/markdown": "md",
+    "text/html": "html",
+    "text/csv": "csv",
+    "text/javascript": "js",
+    "application/json": "json",
+    "application/javascript": "js",
+    "application/xml": "xml",
+    "text/xml": "xml",
+    "application/zip": "zip",
+    "application/gzip": "gz",
+    "application/x-tar": "tar",
+    "application/x-7z-compressed": "7z",
+    "application/x-rar-compressed": "rar",
+};
+export function mimeToExt(mime) {
+    return MIME_TO_EXT[mime.toLowerCase()] ?? "bin";
+}
+/**
+ * Detect the real mime type of an uploaded file by inspecting its content,
+ * not the client-supplied Content-Type or filename extension. Resolves the
+ * "user uploads `.clj` → browser sends application/octet-stream → agents
+ * skip reading binary blobs" failure mode (uploads-plan dev log 2026-04-30).
+ *
+ * Strategy:
+ *   1. `file-type` checks magic bytes for ~200 binary formats (PDF, PNG,
+ *      ZIP, office, audio, video, ...). If it hits, trust that.
+ *   2. No magic match → check whether the buffer is plausibly text:
+ *      - no NUL bytes (binary marker)
+ *      - decodes cleanly as UTF-8
+ *      → return "text/plain". Source code (Clojure, Lua, Rust, Go, ...)
+ *        all land here regardless of how the OS / browser tagged them.
+ *   3. Otherwise fall through to "application/octet-stream".
+ *
+ * Pass `head` as a buffer of at least the first 4 KB of file content; that's
+ * enough for every magic signature `file-type` knows about.
+ */
+export async function sniffMime(head) {
+    const detected = await fileTypeFromBuffer(head);
+    if (detected)
+        return detected.mime;
+    if (looksLikeUtf8Text(head))
+        return "text/plain";
+    return "application/octet-stream";
+}
+function looksLikeUtf8Text(buf) {
+    if (buf.length === 0)
+        return true;
+    for (const byte of buf) {
+        if (byte === 0)
+            return false;
+    }
+    try {
+        const decoder = new TextDecoder("utf-8", { fatal: true });
+        decoder.decode(buf);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Mimes we are willing to render inline in <img>. Everything else is forced
+ * to download via Content-Disposition: attachment so a malicious upload (HTML,
+ * SVG, text/plain interpreted as HTML by Chrome) cannot script the page.
+ */
+const INLINE_MIMES = new Set([
+    "image/png",
+    "image/jpeg",
+    "image/gif",
+    "image/webp",
+]);
+export function isInlineMime(mime) {
+    return INLINE_MIMES.has(mime.toLowerCase());
+}
+/**
+ * Classify an upload as "image" (sent as ACP image block, inlined as base64)
+ * or "file" (sent as ACP resource_link). Decision is mime-prefix-based —
+ * anything with `image/*` is "image", everything else is "file". Clients
+ * cannot override this.
+ */
+export function classifyKind(mime) {
+    return mime.toLowerCase().startsWith("image/") ? "image" : "file";
+}
+/**
+ * Normalize a client-supplied filename for safe display + disk use:
+ *  - NFC-normalize Unicode (combining characters → composed form).
+ *  - Strip ASCII control characters (CR, LF, tab, NUL, etc).
+ *  - Strip path separators ("/", "\") so the name cannot encode a
+ *    sub-path on its own.
+ *  - Reject "." and ".." outright (path-traversal sentinels).
+ *  - Cap to 255 UTF-8 bytes (POSIX NAME_MAX).
+ *
+ * Returns null if normalization would produce an empty name or one of the
+ * forbidden sentinels. Callers should fall back to a generated default
+ * (e.g. `image-N` / `file-N`).
+ */
+export function normalizeDisplayName(raw) {
+    if (typeof raw !== "string")
+        return null;
+    let s = raw.normalize("NFC");
+    // eslint-disable-next-line no-control-regex
+    s = s.replace(/[\x00-\x1f\x7f]/g, "");
+    s = s.replace(/[/\\]/g, "");
+    s = s.trim();
+    if (s.length === 0)
+        return null;
+    if (s === "." || s === "..")
+        return null;
+    // Cap at 255 UTF-8 bytes — slice in code units first as a fast path,
+    // then verify byte-length and trim if needed.
+    if (Buffer.byteLength(s, "utf8") > 255) {
+        while (Buffer.byteLength(s, "utf8") > 255 && s.length > 0) {
+            s = s.slice(0, -1);
+        }
+        if (s.length === 0)
+            return null;
+    }
+    return s;
+}
+/**
+ * Build a Content-Disposition value with both an ASCII fallback (filename=)
+ * and an RFC 5987 percent-encoded UTF-8 form (filename*=) so non-ASCII names
+ * survive every browser's download dialog.
+ *
+ * `disposition` is "inline" or "attachment". "attachment" forces the browser
+ * to download instead of rendering, which is what we use for non-image
+ * mimes (decision 3).
+ */
+export function buildContentDisposition(disposition, displayName) {
+    const ascii = displayName.replace(/[^\x20-\x7e]/g, "_").replace(/"/g, "");
+    const utf8 = encodeURIComponent(displayName);
+    return `${disposition}; filename="${ascii}"; filename*=UTF-8''${utf8}`;
+}

package/lib/auth-middleware.js

@@ -0,0 +1,102 @@
+// All whitelisted paths must be GETs that read non-sensitive data, or static
+// assets needed before the user can present a token.
+const WHITELIST = [
+    // Public probes
+    { method: "GET", test: (p) => p === "/api/v1/version" },
+    { method: "GET", test: (p) => p === "/api/beta/push/vapid-key" },
+    // Static shell + login UI
+    { method: "GET", test: (p) => p === "/" },
+    { method: "GET", test: (p) => p === "/login" },
+    { method: "GET", test: (p) => p === "/login.html" },
+    { method: "GET", test: (p) => p === "/manifest.json" },
+    { method: "GET", test: (p) => p === "/sw.js" },
+    { method: "GET", test: (p) => p === "/favicon.ico" },
+    { method: "GET", test: (p) => p === "/theme-init.js" },
+    // Hashed bundles (must match build output naming)
+    { method: "GET", test: (p) => /^\/js\/[A-Za-z0-9._-]+\.js$/.test(p) },
+    { method: "GET", test: (p) => /^\/styles\.[A-Za-z0-9._-]+\.css$/.test(p) },
+    { method: "GET", test: (p) => p === "/styles.css" },
+    // Icons directory (no traversal: enforced by the check below)
+    { method: "GET", test: (p) => /^\/icons\/[A-Za-z0-9._-]+$/.test(p) },
+    // SSE streams — authenticated via short-lived ticket in query string
+    // (EventSource cannot send custom headers).
+    { method: "GET", test: (p) => p === "/api/v1/events/stream" },
+    {
+        method: "GET",
+        test: (p) => /^\/api\/v1\/sessions\/[A-Za-z0-9_-]+\/events\/stream$/.test(p),
+    },
+    // Image GETs — authenticated via HMAC sig+exp query string (an <img>
+    // tag cannot send Authorization headers). The image route handler does
+    // its own verification before serving bytes.
+    {
+        method: "GET",
+        test: (p) => /^\/api\/v1\/sessions\/[A-Za-z0-9_-]+\/attachments\/[A-Za-z0-9._-]+$/.test(p),
+    },
+    // --- Share viewer (public read-only snapshots) ---
+    // Viewer HTML shell + image proxy + viewer-namespaced static assets
+    // (CSS/JS) all live under /s/* — see src/share/routes.ts. The auth gate
+    // only applies to /api/**, so /s/* paths fall through to share routes
+    // without needing a whitelist entry. The viewer's event stream is the
+    // only public /api/ path: it serves a frozen snapshot identified solely
+    // by the share token in the URL.
+    {
+        method: "GET",
+        test: (p) => /^\/api\/v1\/shared\/[A-Za-z0-9_-]{24}\/events$/.test(p),
+    },
+];
+/**
+ * True if the request can bypass authentication. Path must be normalized
+ * (no `..`, no `//`); we reject anything containing those segments to avoid
+ * traversal-based whitelist bypass.
+ */
+export function isWhitelistedPath(method, path) {
+    if (!path || path.includes("..") || path.includes("//"))
+        return false;
+    const m = method.toUpperCase();
+    for (const entry of WHITELIST) {
+        if (entry.method === m && entry.test(path))
+            return true;
+    }
+    return false;
+}
+/**
+ * Validate the Authorization header against the auth store.
+ * Touches lastUsedAt on success. Pure header parsing + store lookup —
+ * no I/O beyond the in-memory map.
+ */
+export function authenticate(headers, store) {
+    const raw = headers.authorization ?? headers.Authorization;
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime safety for dynamic headers
+    if (raw === undefined || raw === null)
+        return { ok: false, reason: "missing" };
+    if (Array.isArray(raw))
+        return { ok: false, reason: "invalid" };
+    if (typeof raw !== "string")
+        return { ok: false, reason: "invalid" };
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return { ok: false, reason: "missing" };
+    // Parse "Bearer <token>" case-insensitively. Reject scheme-only or extra spaces.
+    const match = /^Bearer\s+(\S+)\s*$/i.exec(trimmed);
+    if (!match)
+        return { ok: false, reason: "invalid" };
+    const token = match[1];
+    const principal = store.findByToken(token);
+    if (!principal)
+        return { ok: false, reason: "invalid" };
+    store.touchLastUsed(token);
+    return { ok: true, principal };
+}
+/**
+ * Returns true if the auth result has at least the required scope.
+ * admin > api (admin is a superset).
+ */
+export function requireScope(result, required) {
+    if (!result.ok)
+        return false;
+    const have = result.principal.scope;
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- exhaustive check for type safety
+    if (required === "api")
+        return have === "api" || have === "admin";
+    return have === "admin";
+}

package/lib/auth-store.js

@@ -0,0 +1,269 @@
+import { promises as fs, existsSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import lockfile from "proper-lockfile";
+import { generateToken, hashToken, verifyToken } from "./auth.js";
+import { atomicWriteFile } from "./atomic-write.js";
+const VALID_NAME = /^[A-Za-z0-9_-]{1,64}$/;
+const VALID_SCOPE = new Set(["admin", "api"]);
+const FILE_MODE = 0o600;
+const LOCK_OPTS = {
+    retries: { retries: 10, factor: 2, minTimeout: 20, maxTimeout: 200 },
+    stale: 5_000,
+    realpath: false,
+};
+export class AuthStore {
+    tokens = new Map(); // keyed by hash
+    dirtyHashes = new Set(); // touched lastUsedAt waiting to flush
+    loaded = false;
+    flushTimer = null;
+    path;
+    flushIntervalMs;
+    constructor(path, flushIntervalMs = 60_000) {
+        this.path = path;
+        this.flushIntervalMs = flushIntervalMs;
+    }
+    /** Read auth.json into memory. Missing file = empty store. Throws on corrupt JSON. */
+    async load() {
+        await fs.mkdir(dirname(this.path), { recursive: true });
+        if (!existsSync(this.path)) {
+            this.tokens = new Map();
+            this.loaded = true;
+            this.startFlushTimer();
+            return;
+        }
+        const raw = readFileSync(this.path, "utf8");
+        const data = parseAuthFile(raw);
+        this.tokens = new Map(data.tokens.map((t) => [t.hash, t]));
+        this.loaded = true;
+        this.startFlushTimer();
+    }
+    /** Reload from disk, discarding any in-memory dirty state. */
+    async reload() {
+        this.dirtyHashes.clear();
+        this.loaded = false;
+        await this.load();
+    }
+    list() {
+        return Array.from(this.tokens.values()).map((t) => ({ ...t }));
+    }
+    findByToken(token) {
+        if (!token.startsWith("wat_"))
+            return null;
+        const h = hashToken(token);
+        const rec = this.tokens.get(h);
+        if (!rec)
+            return null;
+        // defense in depth: also verify timing-safe (cheap, same hash already)
+        if (!verifyToken(token, rec.hash))
+            return null;
+        return { ...rec };
+    }
+    /** True if a token with this name is still active. Used by SSE heartbeat
+     *  to detect revocation mid-stream. */
+    hasTokenName(name) {
+        for (const rec of this.tokens.values()) {
+            if (rec.name === name)
+                return true;
+        }
+        return false;
+    }
+    /** Update lastUsedAt in memory; persisted on next flush(). */
+    touchLastUsed(token) {
+        if (!token)
+            return;
+        const h = hashToken(token);
+        const rec = this.tokens.get(h);
+        if (!rec)
+            return;
+        rec.lastUsedAt = Date.now();
+        this.dirtyHashes.add(h);
+    }
+    async addToken(name, scope) {
+        this.assertLoaded();
+        if (!VALID_NAME.test(name)) {
+            throw new Error(`Invalid token name: ${JSON.stringify(name)} (use [A-Za-z0-9_-], 1-64 chars)`);
+        }
+        if (!VALID_SCOPE.has(scope)) {
+            throw new Error(`Invalid scope: ${scope}`);
+        }
+        return this.withLock(async () => {
+            // Reload to merge any external changes before mutating.
+            const onDisk = await this.readFromDisk();
+            const merged = this.mergeWithDisk(onDisk);
+            if (merged.some((t) => t.name === name)) {
+                throw new Error(`Token name already exists: ${name}`);
+            }
+            const token = generateToken();
+            const record = {
+                name,
+                scope,
+                hash: hashToken(token),
+                createdAt: Date.now(),
+                lastUsedAt: null,
+            };
+            merged.push(record);
+            await this.writeToDisk({ tokens: merged });
+            this.replaceInMemory(merged);
+            this.dirtyHashes.clear();
+            return { token, record: { ...record } };
+        });
+    }
+    async revokeToken(name) {
+        this.assertLoaded();
+        return this.withLock(async () => {
+            const onDisk = await this.readFromDisk();
+            const merged = this.mergeWithDisk(onDisk);
+            const idx = merged.findIndex((t) => t.name === name);
+            if (idx === -1) {
+                // Sync memory with disk anyway.
+                this.replaceInMemory(merged);
+                this.dirtyHashes.clear();
+                return false;
+            }
+            merged.splice(idx, 1);
+            await this.writeToDisk({ tokens: merged });
+            this.replaceInMemory(merged);
+            this.dirtyHashes.clear();
+            return true;
+        });
+    }
+    /**
+     * Persist dirty lastUsedAt fields to disk, preserving any external edits
+     * (revokes, additions). Safe to call frequently; no-op if nothing dirty.
+     */
+    async flush() {
+        if (this.dirtyHashes.size === 0)
+            return;
+        await this.withLock(async () => {
+            const onDisk = await this.readFromDisk();
+            // Build merged list: start from disk (authoritative for membership)
+            // then overlay our dirty lastUsedAt where the hash still exists.
+            const merged = onDisk.map((diskRec) => {
+                if (this.dirtyHashes.has(diskRec.hash)) {
+                    const memRec = this.tokens.get(diskRec.hash);
+                    if (memRec?.lastUsedAt &&
+                        (!diskRec.lastUsedAt || memRec.lastUsedAt > diskRec.lastUsedAt)) {
+                        return { ...diskRec, lastUsedAt: memRec.lastUsedAt };
+                    }
+                }
+                return diskRec;
+            });
+            await this.writeToDisk({ tokens: merged });
+            this.replaceInMemory(merged);
+            this.dirtyHashes.clear();
+        });
+    }
+    async close() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        if (this.loaded && this.dirtyHashes.size > 0) {
+            try {
+                await this.flush();
+            }
+            catch {
+                // best-effort on shutdown
+            }
+        }
+    }
+    // ---- internals -----------------------------------------------------------
+    assertLoaded() {
+        if (!this.loaded)
+            throw new Error("AuthStore not loaded; call load() first");
+    }
+    startFlushTimer() {
+        if (this.flushTimer || this.flushIntervalMs <= 0)
+            return;
+        this.flushTimer = setInterval(() => {
+            void this.flush().catch(() => { });
+        }, this.flushIntervalMs);
+        this.flushTimer.unref();
+    }
+    async readFromDisk() {
+        if (!existsSync(this.path))
+            return [];
+        const raw = await fs.readFile(this.path, "utf8");
+        return parseAuthFile(raw).tokens;
+    }
+    /**
+     * Merge in-memory tokens onto disk-authoritative list:
+     *   - Membership comes from disk (deletions external = honored).
+     *   - lastUsedAt: take the max of memory vs disk for matching hashes.
+     *   - In-memory-only tokens (added by us, not yet on disk) — won't happen
+     *     because addToken always writes synchronously. So disk is full truth.
+     */
+    mergeWithDisk(onDisk) {
+        return onDisk.map((diskRec) => {
+            const memRec = this.tokens.get(diskRec.hash);
+            if (!memRec)
+                return diskRec;
+            const lastUsedAt = Math.max(diskRec.lastUsedAt ?? 0, memRec.lastUsedAt ?? 0) || null;
+            return { ...diskRec, lastUsedAt };
+        });
+    }
+    replaceInMemory(records) {
+        this.tokens = new Map(records.map((t) => [t.hash, { ...t }]));
+    }
+    async writeToDisk(data) {
+        await atomicWriteFile(this.path, JSON.stringify(data, null, 2), FILE_MODE);
+    }
+    async withLock(fn) {
+        // Ensure file exists (proper-lockfile requires the target to exist).
+        if (!existsSync(this.path)) {
+            const fh = await fs.open(this.path, "w", FILE_MODE);
+            await fh.writeFile(JSON.stringify({ tokens: [] }, null, 2));
+            await fh.close();
+        }
+        const release = await lockfile.lock(this.path, LOCK_OPTS);
+        try {
+            return await fn();
+        }
+        finally {
+            await release();
+        }
+    }
+}
+function parseAuthFile(raw) {
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`auth.json is not valid JSON: ${err.message}`, {
+            cause: err,
+        });
+    }
+    if (!data ||
+        typeof data !== "object" ||
+        !Array.isArray(data.tokens)) {
+        throw new Error("auth.json must have a 'tokens' array");
+    }
+    const tokens = data.tokens.map((entry, i) => {
+        if (!entry || typeof entry !== "object")
+            throw new Error(`auth.json tokens[${i}] not an object`);
+        const e = entry;
+        if (typeof e.name !== "string")
+            throw new Error(`auth.json tokens[${i}].name missing`);
+        if (e.scope !== "admin" && e.scope !== "api")
+            throw new Error(`auth.json tokens[${i}].scope invalid`);
+        if (typeof e.hash !== "string" || !/^[a-f0-9]{64}$/i.test(e.hash)) {
+            throw new Error(`auth.json tokens[${i}].hash invalid`);
+        }
+        if (typeof e.createdAt !== "number")
+            throw new Error(`auth.json tokens[${i}].createdAt missing`);
+        const lastUsedAt = e.lastUsedAt;
+        if (lastUsedAt !== null && typeof lastUsedAt !== "number") {
+            throw new Error(`auth.json tokens[${i}].lastUsedAt invalid`);
+        }
+        return {
+            name: e.name,
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion -- narrowed by line 280 check but TSC needs cast from unknown
+            scope: e.scope,
+            hash: e.hash.toLowerCase(),
+            createdAt: e.createdAt,
+            lastUsedAt: lastUsedAt,
+        };
+    });
+    return { tokens };
+}

package/lib/auth.js

@@ -0,0 +1,89 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { generateApiToken } from "./tokens.js";
+const HASH_HEX_LEN = 64; // SHA-256 hex
+/**
+ * Generate a fresh API token. Thin re-export — the canonical generator
+ * lives in `src/tokens.ts` alongside the other auth-bearing token
+ * generators (share, SSE) for a single audit surface.
+ */
+export function generateToken() {
+    return generateApiToken();
+}
+/** Hash a token with SHA-256 -> 64-char lowercase hex. */
+export function hashToken(token) {
+    return createHash("sha256").update(token).digest("hex");
+}
+/**
+ * Constant-time check that the given token hashes to the given hex hash.
+ * Returns false on any malformed input rather than throwing.
+ */
+export function verifyToken(token, expectedHashHex) {
+    if (!token || expectedHashHex.length !== HASH_HEX_LEN) {
+        return false;
+    }
+    if (!/^[a-f0-9]+$/i.test(expectedHashHex))
+        return false;
+    const actual = Buffer.from(hashToken(token), "hex");
+    const expected = Buffer.from(expectedHashHex, "hex");
+    if (actual.length !== expected.length)
+        return false;
+    return timingSafeEqual(actual, expected);
+}
+// --- Image URL signing -------------------------------------------------------
+function hmacHex(secret, data) {
+    return createHmac("sha256", secret).update(data).digest("hex");
+}
+/** Build the canonical input string for HMAC. Path + ":" + exp. */
+function canonical(path, exp) {
+    return `${path}:${exp}`;
+}
+/**
+ * Returns "exp=<unix>&sig=<hex>" — appendable as a query string to the path.
+ * ttlSeconds may be negative (yields an already-expired URL, useful in tests).
+ */
+export function signAttachmentUrl(path, secret, ttlSeconds) {
+    const exp = Math.floor(Date.now() / 1000) + ttlSeconds;
+    const sig = hmacHex(secret, canonical(path, exp));
+    return `exp=${exp}&sig=${sig}`;
+}
+/**
+ * Verify a signed image URL. Returns false on any malformed input or expired/tampered URL.
+ * HMAC binds (path, exp) so altering either invalidates the signature.
+ */
+export function verifyAttachmentSig(path, expRaw, sigHex, secret) {
+    if (!path || !expRaw || !sigHex)
+        return false;
+    if (!/^\d+$/.test(expRaw))
+        return false;
+    if (!/^[a-f0-9]+$/i.test(sigHex))
+        return false;
+    const exp = Number(expRaw);
+    if (!Number.isFinite(exp))
+        return false;
+    if (exp < Math.floor(Date.now() / 1000))
+        return false;
+    const expected = Buffer.from(hmacHex(secret, canonical(path, expRaw)), "hex");
+    let actual;
+    try {
+        actual = Buffer.from(sigHex, "hex");
+    }
+    catch {
+        return false;
+    }
+    if (actual.length !== expected.length)
+        return false;
+    return timingSafeEqual(actual, expected);
+}
+/**
+ * Rewrite every `/api/v1/sessions/:id/attachments/:file` URL inside a JSON-serialized
+ * payload to carry a fresh `?exp=&sig=`. Applied at egress (history GET, SSE
+ * push) so a 1h-old stored URL is re-signed on the way out — the user can
+ * reload history days later and images still resolve.
+ */
+const ATTACHMENT_URL_RE = /\/api\/v1\/sessions\/[A-Za-z0-9_-]+\/attachments\/[A-Za-z0-9._-]+(?:\?(?:exp=\d+&sig=[a-f0-9]+|sig=[a-f0-9]+&exp=\d+))?/g;
+export function reSignAttachmentUrlsInJson(json, secret, ttlSeconds = 3600) {
+    return json.replace(ATTACHMENT_URL_RE, (match) => {
+        const basePath = match.split("?")[0];
+        return `${basePath}?${signAttachmentUrl(basePath, secret, ttlSeconds)}`;
+    });
+}

package/lib/bootstrap.js

@@ -0,0 +1,70 @@
+// First-run bootstrap policy + presentation.
+//
+// Pure functions only — no I/O, no globals. Side effects (token mint,
+// stdout write, process exit) belong in server.ts; this module owns the
+// decision and the banner formatting so tests can lock down behavior
+// without spinning up a server.
+//
+// Decision matrix (decideBootstrap):
+//   tokenCount > 0                                              → proceed
+//   tokenCount = 0  +  authJsonExists                           → exit-config
+//                      (file existed but parsed empty = config
+//                       anomaly; do NOT silently re-mint admin)
+//   tokenCount = 0  +  !authJsonExists  +  !isTTY               → exit-config
+//                      (daemon path: user must use --create-token)
+//   tokenCount = 0  +  !authJsonExists  +  isTTY  +  !enabled   → exit-config
+//                      (operator opted out; preserve old UX)
+//   tokenCount = 0  +  !authJsonExists  +  isTTY  +  enabled    → mint
+//
+// On mint, the banner prints the token verbatim and asks the operator
+// to paste it into the /login form. We deliberately do NOT print a
+// clickable URL with the token in the fragment: although fragments
+// don't reach the server in HTTP requests, they do leak via browser
+// history sync, history-permission extensions, and "looks like a link
+// → click it" muscle memory. Plain-token + manual paste matches the
+// existing `--create-token` flow's mental model.
+export function decideBootstrap(input) {
+    if (input.tokenCount > 0)
+        return { kind: "proceed" };
+    if (input.authJsonExists)
+        return { kind: "exit-config" };
+    if (!input.isTTY)
+        return { kind: "exit-config" };
+    if (!input.firstRunEnabled)
+        return { kind: "exit-config" };
+    return { kind: "mint" };
+}
+/**
+ * Banner printed to stdout on first-run mint. Token is printed verbatim
+ * and the operator is asked to paste it into the /login form. ANSI is
+ * gated on isTTY so log capture / journald / supervisor pipes get plain
+ * text.
+ */
+export function formatBootstrapBanner(opts) {
+    const { token, port, isTTY } = opts;
+    const bold = isTTY ? "\x1b[1m" : "";
+    const cyan = isTTY ? "\x1b[36m" : "";
+    const dim = isTTY ? "\x1b[2m" : "";
+    const reset = isTTY ? "\x1b[0m" : "";
+    const url = `http://localhost:${port}/`;
+    const lines = [
+        "",
+        `${bold}┌─ first-run ──────────────────────────────────────────────${reset}`,
+        `${bold}│${reset}`,
+        `${bold}│${reset}  Welcome. WebAgent has minted a one-time admin token`,
+        `${bold}│${reset}  for this device. Copy it and paste it into the`,
+        `${bold}│${reset}  login form:`,
+        `${bold}│${reset}`,
+        `${bold}│${reset}    1. open ${cyan}${url}${reset} in your browser`,
+        `${bold}│${reset}    2. paste this token:`,
+        `${bold}│${reset}`,
+        `${bold}│${reset}       ${bold}${cyan}${token}${reset}`,
+        `${bold}│${reset}`,
+        `${bold}│${reset}  ${dim}Treat this token like a password — it appears in${reset}`,
+        `${bold}│${reset}  ${dim}your terminal scrollback. Revoke from /tokens later${reset}`,
+        `${bold}│${reset}  ${dim}if needed.${reset}`,
+        `${bold}└──────────────────────────────────────────────────────────${reset}`,
+        "",
+    ];
+    return lines.join("\n");
+}