@timqi/pier 0.0.1 → 0.0.3

package/dist/web/auth.js

@@ -16,7 +16,8 @@
 // whole revocation story a single-user system needs. A cookie (not a bearer
 // header) because the workbench lives on SSE, and EventSource sends no headers.
 import { createHash, createHmac, randomBytes, randomInt, scryptSync, timingSafeEqual, } from "node:crypto";
-import { getCookie, setCookie } from "hono/cookie";
+import { getConnInfo } from "@hono/node-server/conninfo";
+import { deleteCookie, getCookie, setCookie } from "hono/cookie";
 import { pierDb } from "../db.js";
 import { logger } from "../log.js";
 const log = logger("auth");
@@ -25,6 +26,9 @@ const TTL_MS = 90 * 24 * 60 * 60_000;
 /** Failed attempts one client may make before it has to wait out the window. */
 const MAX_FAILURES = 10;
 const WINDOW_MS = 15 * 60_000;
+/** Distinct throttle buckets retained at once; the last is shared overflow. */
+const MAX_FAILURE_CLIENTS = 1024;
+const OVERFLOW_CLIENT = "\0overflow";
 /** Shortest password a human may choose. The generated one is longer; this is
  *  the floor under which the throttle above stops being enough. */
 const MIN_LENGTH = 10;
@@ -109,11 +113,12 @@ const hash = (password, salt) => scryptSync(password, salt, KEY_BYTES).toString(
  * it. `/boards/*` stays behind the boundary; `/p/*` is the published mirror,
  * the single exempt prefix `docs/architecture.md` reserved for this.
  */
-function isPublic(path) {
-    return (path === "/login" ||
-        path === "/p" ||
-        path.startsWith("/p/") ||
-        path === "/boards/_assets/pier.css");
+function isPublic(method, path) {
+    if (path === "/login")
+        return method === "GET" || method === "HEAD" || method === "POST";
+    if (method !== "GET" && method !== "HEAD")
+        return false;
+    return path.startsWith("/p/") || path === "/boards/_assets/pier.css";
 }
 const sign = (secret, expiresAt) => createHmac("sha256", secret).update(String(expiresAt)).digest("base64url");
 /** Constant-time equality that also hides length: both sides are digested. */
@@ -137,40 +142,90 @@ function valid(secret, cookie) {
 const safeNext = (raw) => typeof raw === "string" && /^\/(?![/\\])/.test(raw) ? raw : "/";
 // Failed logins per client, in memory: a restart clearing them is fine, since
 // the window is minutes and the point is to make guessing slow, not to keep
-// books. Bounded by pruning every expired entry on each check.
+// books. Expired entries are pruned, and fresh identities spill into one
+// overflow bucket once the fixed map cap is reached.
 const failures = new Map();
-/**
- * Behind a reverse proxy every request shares one socket address, so the
- * forwarded hop is the only thing separating two clients. It is spoofable when
- * Pier is exposed directly — that is an argument for the proxy, not against
- * the limit: a password is the thing being protected here, the counter only
- * decides how fast someone may guess.
- */
+const loopback = (address) => address === "::1" || address.startsWith("127.") || address.startsWith("::ffff:127.");
+function remoteOf(c) {
+    const env = c.env;
+    return env?.incoming || env?.server?.incoming
+        ? getConnInfo(c).remote.address
+        : undefined;
+}
+/** Trust a forwarded address only from a local reverse proxy. The rightmost
+ * hop is the address that proxy appended, not one the client put at the front. */
 function clientOf(c) {
-    return c.req.header("x-forwarded-for")?.split(",")[0]?.trim() || "local";
+    const remote = remoteOf(c);
+    if (remote && !loopback(remote))
+        return remote;
+    return c.req.header("x-forwarded-for")?.split(",").at(-1)?.trim() || remote || "local";
+}
+function failureClient(client) {
+    if (failures.has(client) || failures.size < MAX_FAILURE_CLIENTS - 1)
+        return client;
+    return OVERFLOW_CLIENT;
 }
 function throttled(client) {
     const now = Date.now();
     for (const [id, entry] of failures)
         if (entry.resetAt <= now)
             failures.delete(id);
-    return (failures.get(client)?.count ?? 0) >= MAX_FAILURES;
+    return (failures.get(failureClient(client))?.count ?? 0) >= MAX_FAILURES;
 }
 function noteFailure(client) {
+    client = failureClient(client);
     const entry = failures.get(client);
     if (entry && entry.resetAt > Date.now())
         entry.count += 1;
     else
         failures.set(client, { count: 1, resetAt: Date.now() + WINDOW_MS });
 }
+/** Browsers name the source of unsafe requests. Compare hosts rather than
+ * schemes because TLS commonly terminates at the reverse proxy. */
+function sameOrigin(c) {
+    const origin = c.req.header("origin");
+    if (!origin)
+        return true; // curl and other non-browser clients
+    try {
+        const parsed = new URL(origin);
+        const remote = remoteOf(c);
+        const forwarded = remote && loopback(remote)
+            ? c.req.header("x-forwarded-host")?.split(",").at(-1)?.trim()
+            : undefined;
+        const host = forwarded || c.req.header("host") || new URL(c.req.url).host;
+        const external = new URL(`${parsed.protocol}//${host}`);
+        return parsed.origin === origin && external.origin === parsed.origin &&
+            external.pathname === "/" && !external.search && !external.hash;
+    }
+    catch {
+        return false;
+    }
+}
 /** Every route, in one place — no per-route opt-in to forget on the next one. */
 export function requireAuth(store) {
     return async (c, next) => {
-        if (isPublic(c.req.path) || valid(store.cookieKey, getCookie(c, COOKIE)))
+        // On every response, public ones included: the login form is the one page
+        // strangers reach, and it must not be frameable either.
+        c.header("x-frame-options", "DENY");
+        if (isPublic(c.req.method, c.req.path))
             return next();
+        const authenticated = valid(store.cookieKey, getCookie(c, COOKIE));
+        const unsafe = c.req.method !== "GET" && c.req.method !== "HEAD";
+        if (authenticated && unsafe && !sameOrigin(c)) {
+            log.warn(`blocked ${c.req.method} ${c.req.path} from origin ${c.req.header("origin")}`);
+            return c.json({ error: "forbidden origin" }, 403);
+        }
+        if (authenticated) {
+            await next();
+            // Cookie-authenticated content must not become public in a shared proxy.
+            if (!c.res.headers.has("cache-control")) {
+                c.header("cache-control", c.req.path.startsWith("/api/") ? "private, no-store" : "private");
+            }
+            return;
+        }
         // An API caller gets a status it can act on; a navigation gets the form.
         // Anything non-GET is a client call too — never a link worth redirecting.
-        if (c.req.path.startsWith("/api/") || c.req.method !== "GET") {
+        if (c.req.path.startsWith("/api/") || unsafe) {
             return c.json({ error: "unauthorized" }, 401);
         }
         return c.redirect(`/login?next=${encodeURIComponent(c.req.path)}`);
@@ -198,10 +253,8 @@ export function registerAuthRoutes(app, store) {
         issueCookie(c, store);
         return c.redirect(next);
     });
-    // Changing the password is a login — it takes the current one, and it is
-    // throttled by the same counter, because "change" answers the same guess
-    // "sign in" does. So it needs no cookie of its own: whoever knows the current
-    // password can already get one.
+    // Re-authenticate before rotating the credential. The global boundary also
+    // requires a live cookie; knowing a password is not permission to call APIs.
     app.post("/api/password", async (c) => {
         const client = clientOf(c);
         const body = (await c.req.json().catch(() => null));
@@ -211,16 +264,26 @@ export function registerAuthRoutes(app, store) {
             return c.json({ error: "Too many attempts. Wait a few minutes." }, 429);
         if (!store.verify(current)) {
             noteFailure(client);
-            return c.json({ error: "Wrong current password." }, 401);
+            return c.json({ error: "Wrong current password." }, 403);
         }
         if (next.length < MIN_LENGTH) {
             return c.json({ error: `Use at least ${MIN_LENGTH} characters.` }, 400);
         }
         failures.delete(client);
         store.setPassword(next);
-        // The rotation just killed this caller's cookie too; re-issue rather than
-        // bounce the person who is holding the new password to the login form.
-        issueCookie(c, store);
+        // The rotation just killed every cookie out there, this caller's included —
+        // a password is changed because the old one may be known, and "everyone
+        // signs in again" is the whole point. Clear the dead cookie; the client
+        // sends the person to the login form with the password they just chose.
+        deleteCookie(c, COOKIE, { path: "/" });
+        return c.json({ ok: true });
+    });
+    // Signs out this browser by clearing its cookie. The value itself stays
+    // verifiable until it expires — it is a signature, not a stored id — so the
+    // full revocation story remains the password change above. Behind the
+    // boundary like every write: only a signed-in browser has anything to end.
+    app.post("/logout", (c) => {
+        deleteCookie(c, COOKIE, { path: "/" });
         return c.json({ ok: true });
     });
 }

package/dist/web/explorer.js

@@ -0,0 +1,147 @@
+// Files view backend: read-only directory listing, file bytes and git
+// ref/diff queries for the Console's Files view. `root` is any directory the
+// process can read — sessions work in worktrees and siblings of their cwd, and
+// an owner who is already past the Console password can reach those paths
+// anyway. `path` is still confined to the `root` it was asked under, so a
+// listing can never widen itself, and nothing here writes.
+import { execFile } from "node:child_process";
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
+import { basename, extname, isAbsolute, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+import { guarded } from "./files.js";
+const run = promisify(execFile);
+// Inline-renderable binary types; text is sniffed, everything else downloads.
+const BINARY_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".avif": "image/avif",
+    ".bmp": "image/bmp",
+    ".svg": "image/svg+xml",
+    ".pdf": "application/pdf",
+};
+const MAX_FILE_BYTES = 32 * 1024 * 1024;
+const MAX_DIFF_BYTES = 2 * 1024 * 1024;
+/** A ref never starts with `-`: execFile blocks the shell, this blocks the
+ *  argument parser (`--output=…` is a write). Git validates the rest. */
+const REF_RE = /^[^-\s][^\s]*$/;
+/** git in `root`, output capped — a diff is display data, not an archive. */
+const git = async (root, ...args) => (await run("git", ["-C", root, ...args], { maxBuffer: MAX_DIFF_BYTES })).stdout;
+export function registerExplorerRoutes(app) {
+    /** The scope check every route shares: `root` must be an absolute directory,
+     *  and `path` must resolve inside it (realpath both ends — neither `..` nor a
+     *  symlink steps outside). Returns the real target. */
+    const resolveScoped = async (root, path = "") => {
+        if (!root || !isAbsolute(root))
+            throw new Error("root must be an absolute directory");
+        const real = await realpath(root);
+        if (!(await stat(real)).isDirectory())
+            throw new Error("root must be an absolute directory");
+        const target = await realpath(resolve(real, path));
+        if (target !== real && !target.startsWith(real + sep))
+            throw new Error("path escapes root");
+        return target;
+    };
+    // Directory listing, names only. `.git` is plumbing, not content.
+    guarded(app, "GET", "/api/explorer/ls", 404, async (c) => {
+        c.header("cache-control", "no-store");
+        const dir = await resolveScoped(c.req.query("root"), c.req.query("path"));
+        const entries = (await readdir(dir, { withFileTypes: true }))
+            .filter((e) => e.name !== ".git" && (e.isDirectory() || e.isFile()))
+            .map((e) => ({ name: e.name, dir: e.isDirectory() }))
+            .sort((a, b) => Number(b.dir) - Number(a.dir) || a.name.localeCompare(b.name));
+        return c.json({ entries });
+    });
+    // File bytes, read-only. Known binary types render inline; anything else is
+    // sniffed — a NUL in the head means bytes we can't vouch for, so it
+    // downloads instead of rendering (that is how a file starts executing).
+    guarded(app, "GET", "/api/explorer/file", 404, async (c) => {
+        const file = await resolveScoped(c.req.query("root"), c.req.query("path"));
+        if (!(await stat(file)).isFile())
+            throw new Error("not a file");
+        const bytes = await readFile(file);
+        if (bytes.byteLength > MAX_FILE_BYTES)
+            return c.json({ error: "file too large" }, 413);
+        const binary = BINARY_TYPES[extname(file).toLowerCase()];
+        const text = !binary && !bytes.subarray(0, 8192).includes(0);
+        return c.body(bytes, 200, {
+            "content-type": binary ?? (text ? "text/plain; charset=utf-8" : "application/octet-stream"),
+            "content-disposition": `${binary || text ? "inline" : "attachment"}; filename*=UTF-8''${encodeURIComponent(basename(file))}`,
+            "cache-control": "no-store",
+        });
+    });
+    // Git refs for the diff pickers: current branch, branches+tags, recent
+    // commits. Not a repo → { branch: null }, which the UI renders as "no git".
+    guarded(app, "GET", "/api/explorer/git", 404, async (c) => {
+        c.header("cache-control", "no-store");
+        const root = await resolveScoped(c.req.query("root"));
+        let branch;
+        try {
+            branch = (await git(root, "rev-parse", "--abbrev-ref", "HEAD")).trim();
+        }
+        catch {
+            return c.json({ branch: null, refs: [], commits: [] }); // not a repo, or no commits yet
+        }
+        const refs = (await git(root, "for-each-ref", "--format=%(refname:short)\t%(subject)", "refs/heads", "refs/tags"))
+            .split("\n")
+            .filter(Boolean)
+            .map((line) => {
+            const tab = line.indexOf("\t");
+            return { name: line.slice(0, tab), subject: line.slice(tab + 1) };
+        });
+        // Unit/record separators, because a body is multi-line by nature.
+        const commits = (await git(root, "log", "-20", "--format=%h\u001f%at\u001f%an\u001f%s\u001f%b\u001e"))
+            .split("\u001e")
+            .map((r) => r.trimStart())
+            .filter(Boolean)
+            .map((r) => {
+            const [hash = "", at = "", author = "", subject = "", body = ""] = r.split("\u001f");
+            return { hash, at: Number(at) * 1000, author, subject, body: body.trim() };
+        });
+        return c.json({ branch, refs, commits });
+    });
+    // One endpoint, two shapes: without `file` the changed-file list
+    // (name-status), with it that file's unified diff. `head` empty or absent
+    // means the working tree.
+    guarded(app, "GET", "/api/explorer/diff", 404, async (c) => {
+        c.header("cache-control", "no-store");
+        const root = await resolveScoped(c.req.query("root"));
+        const base = c.req.query("base") ?? "";
+        const head = c.req.query("head") ?? "";
+        if (!REF_RE.test(base) || (head !== "" && !REF_RE.test(head)))
+            return c.json({ error: "invalid ref" }, 400);
+        const range = head ? [base, head] : [base];
+        // Context radius for per-file diffs — the UI asks for a huge one to render
+        // the whole file with changes toned inline, not a bare patch.
+        const context = Math.min(99_999, Math.max(0, Math.trunc(Number(c.req.query("context"))) || 0));
+        const file = c.req.query("file");
+        if (file === undefined) {
+            // name-status carries the letter, numstat the +/- counts; joined by path.
+            const [nameStatus, numstat] = await Promise.all([
+                git(root, "diff", "--name-status", ...range, "--"),
+                git(root, "diff", "--numstat", ...range, "--"),
+            ]);
+            // numstat spells a rename "a/{old => new}.ts" — reduce it to the new path.
+            const newPath = (p) => p.replace(/\{([^{}]*) => ([^{}]*)\}/g, "$2").replace(/^(.*) => (.*)$/, "$2");
+            const counts = new Map(numstat.split("\n").filter(Boolean).map((line) => {
+                const [add = "", del = "", ...path] = line.split("\t");
+                // "-" on both sides means binary — no line counts to report.
+                return [newPath(path.join("\t")), { add: Number(add) || 0, del: Number(del) || 0 }];
+            }));
+            const files = nameStatus
+                .split("\n")
+                .filter(Boolean)
+                .map((line) => {
+                // Renames/copies are "R100\told\tnew" — show the new path.
+                const [status = "", ...paths] = line.split("\t");
+                const path = paths[paths.length - 1] ?? "";
+                return { status: status.charAt(0), path, ...(counts.get(path) ?? { add: 0, del: 0 }) };
+            });
+            return c.json({ files });
+        }
+        // The path only reaches git behind `--`, so it is data, never an option.
+        return c.json({ diff: await git(root, "diff", `-U${context || 3}`, ...range, "--", file) });
+    });
+}

package/dist/web/files.js

@@ -5,6 +5,7 @@
 import { mkdir, readdir, readFile, realpath, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, extname, isAbsolute, resolve, sep } from "node:path";
+import { INBOX_DIR } from "../core/inbox.js";
 // Content types for the attachment route. Anything unlisted downloads as
 // bytes — guessing a type we can't vouch for is how a file starts executing.
 const FILE_TYPES = {
@@ -38,7 +39,7 @@ export function guarded(app, method, path, status, fn) {
         }
     });
 }
-export function registerFileRoutes(app, { factory, config, nascentCwd }) {
+export function registerFileRoutes(app, { factory, config, nascentCwd, onConfigWritten }) {
     // Scope comes from the client as "global" or a project cwd; only cwds Pi
     // already knows (the session list) are accepted — never an arbitrary path.
     const parseScope = async (raw) => {
@@ -48,15 +49,19 @@ export function registerFileRoutes(app, { factory, config, nascentCwd }) {
         return known.some((s) => s.cwd === raw) ? { kind: "project", cwd: raw } : null;
     };
     app.get("/api/config", async (c) => {
+        c.header("cache-control", "no-store");
         const scope = await parseScope(c.req.query("scope"));
         if (!scope)
             return c.json({ error: "unknown scope" }, 400);
         return c.json({
+            // Where this scope's files live on disk — the UI labels "Global" with it.
+            dir: scope.kind === "global" ? config.globalDir : scope.cwd,
             files: await config.listFiles(scope),
             resources: await config.listResources(scope),
         });
     });
     guarded(app, "GET", "/api/config/files/:name", 400, async (c) => {
+        c.header("cache-control", "no-store");
         const scope = await parseScope(c.req.query("scope"));
         if (!scope)
             return c.json({ error: "unknown scope" }, 400);
@@ -67,13 +72,17 @@ export function registerFileRoutes(app, { factory, config, nascentCwd }) {
         if (!scope)
             return c.json({ error: "unknown scope" }, 400);
         const body = await c.req.json().catch(() => null);
-        if (typeof body?.content !== "string")
-            return c.json({ error: "content required" }, 400);
-        await config.writeFile(scope, c.req.param("name"), body.content);
-        return c.json({ ok: true });
+        if (typeof body?.content !== "string" || typeof body?.expected !== "string") {
+            return c.json({ error: "content and expected content required" }, 400);
+        }
+        const name = c.req.param("name");
+        await config.writeFile(scope, name, body.content, body.expected);
+        onConfigWritten?.();
+        return c.json({ ok: true, content: await config.readFile(scope, name) });
     });
     // Resource names may contain slashes — query params, not path params.
     guarded(app, "GET", "/api/config/resource", 400, async (c) => {
+        c.header("cache-control", "no-store");
         const scope = await parseScope(c.req.query("scope"));
         if (!scope)
             return c.json({ error: "unknown scope" }, 400);
@@ -84,16 +93,23 @@ export function registerFileRoutes(app, { factory, config, nascentCwd }) {
         }
         return c.json({ content: await config.readResource(scope, kind, name) });
     });
-    /** Real path of a file a session may expose: inside its cwd, nothing else. */
+    /** Real path of a file a session may expose: inside its cwd or the inbox
+     *  (where inbound user attachments land — core/inbox.ts), nothing else. */
     const resolveFile = async (id, raw) => {
         const cwd = nascentCwd(id) ?? (await factory.list()).find((s) => s.id === id)?.cwd;
         if (!cwd || !isAbsolute(raw))
             return null;
         try {
             // realpath both ends, so neither `..` nor a symlink can step outside.
-            const root = await realpath(cwd);
-            const target = await realpath(resolve(root, raw));
-            if (target !== root && !target.startsWith(root + sep))
+            const roots = [await realpath(cwd)];
+            try {
+                roots.push(await realpath(INBOX_DIR));
+            }
+            catch {
+                /* no inbox yet — nothing was ever uploaded */
+            }
+            const target = await realpath(resolve(roots[0], raw));
+            if (!roots.some((root) => target === root || target.startsWith(root + sep)))
                 return null;
             return (await stat(target)).isFile() ? target : null;
         }
@@ -101,9 +117,9 @@ export function registerFileRoutes(app, { factory, config, nascentCwd }) {
             return null; // missing, unreadable, or not a file
         }
     };
-    // Agent attachments: the agent links a file it produced (`file:///abs/path`)
-    // and the client fetches the bytes here — read-only, and only from within
-    // the session's own working directory.
+    // Attachments, both directions: the agent links a file it produced, the
+    // chat renders a file the user sent — the client fetches the bytes here,
+    // read-only, and only from the session's own cwd or the inbox.
     app.get("/api/sessions/:id/files", async (c) => {
         const raw = c.req.query("path");
         if (!raw)

package/dist/web/instance.js

@@ -0,0 +1,165 @@
+// Routes about the Pier instance itself — settings, update availability,
+// layer-1 secrets control, the browser's error reports. Nothing here touches
+// a session; server.ts stays the session/event surface.
+import { logger } from "../log.js";
+import { normalizeModelMenu, normalizePublicUrl } from "../settings.js";
+/** Client reports per minute, for the whole server: a browser bug can fire in
+ *  a loop, and the journal is shared with everything else Pier says. */
+const CLIENT_LOG_PER_MINUTE = 60;
+export function registerInstanceRoutes(app, deps) {
+    const { settings, updates, updater = null, secrets, onUnlocked, onSettingsChanged } = deps;
+    const updateLog = logger("update");
+    // How long POST /api/update may hold its response open. A busy Pier drains
+    // first, which can take minutes, and a response held that long dies at every
+    // proxy on the way (principle 7): past this cap the answer is "draining".
+    const APPLY_REPLY_CAP_MS = 10_000;
+    // The browser's half of the log. A workbench that threw after the response
+    // left the server is otherwise invisible here (ui/report.ts) — this is the
+    // one route whose entire purpose is to make it visible.
+    const clientLog = logger("client");
+    let reports = [];
+    app.post("/api/client-log", async (c) => {
+        const body = (await c.req.json().catch(() => null));
+        if (typeof body?.message !== "string" || !body.message.trim()) {
+            return c.json({ error: "message required" }, 400);
+        }
+        const now = Date.now();
+        reports = reports.filter((at) => now - at < 60_000);
+        if (reports.length >= CLIENT_LOG_PER_MINUTE)
+            return c.body(null, 429);
+        reports.push(now);
+        const cap = (value, max) => typeof value === "string" ? value.slice(0, max) : "";
+        const where = cap(body.view, 120);
+        const stack = cap(body.stack, 2000);
+        // One line, ua included: "only on iOS" is the answer half these questions
+        // have, and the report is the only place it exists.
+        clientLog.warn(`${cap(body.message, 500)} [${where || "/"}] ${cap(c.req.header("user-agent"), 160)}` +
+            (stack ? `\n${stack}` : ""));
+        return c.body(null, 204);
+    });
+    // Instance settings. The password lives behind its own route (web/auth.ts):
+    // it is a credential, and changing it takes the old one.
+    app.get("/api/settings", (c) => c.json(settings.get()));
+    // What the version badge reads: the two versions, whether this instance can
+    // do anything about the gap, and whether it is allowed to do it unattended.
+    // `statusNow` so a browser opened seconds after a restart is told the truth
+    // rather than "no idea yet".
+    app.get("/api/update", async (c) => c.json({
+        ...(await updates.statusNow()),
+        canApply: updater !== null,
+        autoUpdate: settings.get().autoUpdate,
+        // Reported whether or not an update is pending: the repair is the same,
+        // and finding out at the next restart is finding out too late.
+        problem: updater?.problem() ?? null,
+    }));
+    // Applying. Nothing is installed here: the work is handed to the service
+    // manager's own oneshot unit, which stops Pier, backs the database up,
+    // installs and starts Pier again — an npm child of this process would be
+    // killed by the very restart it is performing.
+    app.post("/api/update", async (c) => {
+        if (!updater) {
+            return c.json({ error: "no service manager owns this Pier — update it with: pier update" }, 409);
+        }
+        const { current, latest, available } = await updates.statusNow();
+        if (!available) {
+            return c.json({ error: latest === null ? "the registry could not be reached" : `${current} is the latest` }, 409);
+        }
+        const problem = updater.problem();
+        if (problem !== null) {
+            updateLog.error(`update to ${latest} refused: ${problem}`);
+            return c.json({ error: problem }, 409);
+        }
+        const applied = updater.apply().catch((err) => {
+            updateLog.error("update handover failed", err);
+            return "failed";
+        });
+        const started = await Promise.race([
+            applied,
+            new Promise((resolve) => setTimeout(resolve, APPLY_REPLY_CAP_MS, "draining").unref()),
+        ]);
+        if (started === "draining") {
+            // The handover keeps running behind this response; if it fails later,
+            // main.ts's takeWorkAgain reports it and reopens the gate (§5b).
+            updateLog.info(`updating to ${latest} on the Console's request — waiting for running work to finish`);
+            return c.json({ started: true, draining: true, latest }, 202);
+        }
+        if (started === "busy") {
+            return c.json({ error: "an update or restart is already in progress" }, 409);
+        }
+        if (started !== "started") {
+            updateLog.error(`update to ${latest} refused by the updater: ${started}`);
+            return c.json({
+                error: started === "not-installed"
+                    ? "the systemd unit is not installed — run: pier service install"
+                    : "the updater could not be started; see the journal",
+            }, 500);
+        }
+        updateLog.info(`updating to ${latest} on the Console's request — Pier stops and starts again`);
+        return c.json({ started: true, latest });
+    });
+    // Partial on purpose: each surface sends only the setting it edits, and a
+    // malformed field is rejected before anything is written.
+    app.put("/api/settings", async (c) => {
+        const body = await c.req.json().catch(() => null);
+        if (!body || (body.publicUrl === undefined && body.modelMenu === undefined && body.autoUpdate === undefined)) {
+            return c.json({ error: "publicUrl, modelMenu or autoUpdate required" }, 400);
+        }
+        if (body.publicUrl !== undefined) {
+            if (typeof body.publicUrl !== "string")
+                return c.json({ error: "publicUrl must be a string" }, 400);
+            const publicUrl = normalizePublicUrl(body.publicUrl);
+            if (publicUrl === null) {
+                return c.json({ error: "not a URL: expected http(s)://host, no query or fragment" }, 400);
+            }
+            settings.setPublicUrl(publicUrl);
+        }
+        if (body.modelMenu !== undefined) {
+            const menu = normalizeModelMenu(body.modelMenu);
+            if (menu === null) {
+                return c.json({ error: "modelMenu must be [{provider, id, note?}] (≤32 entries)" }, 400);
+            }
+            settings.setModelMenu(menu);
+        }
+        if (body.autoUpdate !== undefined) {
+            if (typeof body.autoUpdate !== "boolean")
+                return c.json({ error: "autoUpdate must be a boolean" }, 400);
+            settings.setAutoUpdate(body.autoUpdate);
+        }
+        // Only the URL: the model menu is read per picker call, not per session.
+        if (body.publicUrl !== undefined)
+            onSettingsChanged?.();
+        return c.json(settings.get());
+    });
+    // Layer-1 key status and control (Console → Settings → Security). The GET
+    // is what a locked instance shows; unlock is how it recovers without a
+    // restart, and rotate is the only way to change how the KEK is protected.
+    const secretsStatus = () => ({
+        state: secrets.state,
+        mode: secrets.mode ?? null,
+        ...(secrets.state === "locked" ? { reason: secrets.lockedReason } : {}),
+    });
+    app.get("/api/secrets", (c) => c.json(secretsStatus()));
+    app.post("/api/secrets/unlock", async (c) => {
+        try {
+            await secrets.unlock();
+        }
+        catch (err) {
+            return c.json({ error: String(err) }, 500);
+        }
+        onUnlocked?.();
+        return c.json(secretsStatus());
+    });
+    app.post("/api/secrets/rotate", async (c) => {
+        const body = (await c.req.json().catch(() => ({})));
+        if (body.mode !== undefined && body.mode !== "vt" && body.mode !== "file") {
+            return c.json({ error: "mode must be vt or file" }, 400);
+        }
+        try {
+            await secrets.rotateKek(body.mode);
+        }
+        catch (err) {
+            return c.json({ error: String(err) }, 500);
+        }
+        return c.json(secretsStatus());
+    });
+}