@timqi/pier 0.0.29 → 0.1.1

package/dist/web/auth.js

@@ -1,74 +1,48 @@
-// The boundary in front of every HTTP surface: one shared password.
-//
-// Single-account on purpose. Pier has one workspace, so there is nobody to
-// tell apart — an internet-facing deployment needs a *boundary*, not
-// identities. Multiple people using it share the page, and share the password.
-//
-// Nothing to configure before first run: the store generates a password on an
-// empty database, keeps only its scrypt hash, and prints the plaintext once to
-// the log. There is no window where the port is open and unclaimed — the
-// password exists before the listener does — and no env var for an operator to
-// get wrong. Forgot it? Delete the row and restart; a new one is printed.
-//
-// The cookie is "<id>.<token>", and the database keeps the token's SHA-256 —
-// one row per signed-in browser. Two things follow, and both are why this is
-// not the signed expiry it used to be: a copy of pier.db cannot be turned into
-// a session (there is no signing key in it to forge with), and a single
-// browser can be signed out without changing the password everyone shares. A
-// cookie (not a bearer header) because the workbench lives on SSE, and
-// EventSource sends no headers.
+// The boundary in front of every HTTP surface: one shared password, generated
+// before the listener opens and printed once. The cookie is "<id>.<token>" and
+// the database keeps only the token's SHA-256, one row per browser: a copy of
+// pier.db cannot be turned into a session, and one browser can be signed out
+// alone. A cookie, not a bearer header, because EventSource sends no headers.
 import { createHash, randomBytes, randomInt, scryptSync, timingSafeEqual } from "node:crypto";
 import { getConnInfo } from "@hono/node-server/conninfo";
 import { deleteCookie, getCookie, setCookie } from "hono/cookie";
 import { pierDb, statements, transact } from "../db.js";
+import { readCapped } from "../core/inbox.js";
 import { logger } from "../log.js";
 const log = logger("auth");
 const COOKIE = "pier_session";
-/** How long an idle browser stays signed in. Sliding: a session in daily use
- *  never expires, and a stolen cookie is dead a week after its last use. */
+/** Sliding: a stolen cookie is dead a week after its last use. */
 const TTL_MS = 7 * 24 * 60 * 60_000;
-/** How stale `seen_at` may get before a request writes. Renewal rides on it,
- *  so this is also how coarse "last seen" is — one write per browser per five
- *  minutes instead of one per request. */
+/** Absolute, so daily use cannot slide one cookie forever: every browser
+ *  re-authenticates a quarter after it signed in. */
+const MAX_AGE_MS = 90 * 24 * 60 * 60_000;
+/** One `seen_at` write per browser per five minutes instead of one per request. */
 const TOUCH_MS = 5 * 60_000;
-/** `revoke(ALL)` — not an id any row can have, so it cannot collide with one. */
+/** Not an id any row can have. */
 export const ALL = "*";
-/** 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. */
+/** The floor under which the throttle above stops being enough. */
 const MIN_LENGTH = 10;
+/** A password and a path fit; a stranger may not ask for more parsing than that. */
+const MAX_LOGIN_BODY = 4096;
 // scrypt at Node's defaults (N=16384): ~50ms per attempt, which is the point.
 const KEY_BYTES = 32;
-/**
- * Human-readable and unambiguous: no 0/O, 1/l/I, so it survives being read off
- * a terminal and typed into a phone. 15 characters from a 31-symbol alphabet is
- * ~74 bits — this is the only thing between the internet and a shell.
- *
- * `randomInt` rejection-samples. Folding a random byte with `% 31` would have
- * quietly favoured the first eight symbols, which is the kind of bias nothing
- * ever reports.
- */
+/** No 0/O, 1/l/I, so it survives being typed off a terminal into a phone; 15
+ *  of 31 symbols is ~74 bits. `randomInt` rejection-samples — `% 31` on a byte
+ *  would favour the first eight symbols. */
 function generatePassword() {
     const alphabet = "abcdefghjkmnpqrstuvwxyz23456789";
     const chars = Array.from({ length: 15 }, () => alphabet[randomInt(alphabet.length)]).join("");
     return `${chars.slice(0, 5)}-${chars.slice(5, 10)}-${chars.slice(10)}`;
 }
-/**
- * The stored credential: one row, one password, hashed.
- *
- * Generation happens in the constructor because "no password" is not a state
- * Pier may ever serve in — a boot that cannot print the password it just made
- * should fail at boot, not open a door.
- */
+/** Generation happens in the constructor: "no password" is not a state Pier
+ *  may ever serve in. */
 export class AuthStore {
     #db;
-    /** Compiled once each: `check()` runs two of these on every request that
-     *  carries a cookie, which is every request the workbench makes. */
     #sql;
     #revokeListeners = new Set();
     constructor(db = pierDb(), print = (m) => log.info(m)) {
@@ -79,11 +53,8 @@ export class AuthStore {
             const password = generatePassword();
             const salt = randomBytes(16).toString("hex");
             row = { salt, hash: hash(password, salt), createdAt: Date.now() };
-            // Recovery is "DELETE FROM auth and restart", so this branch is also how
-            // a forgotten password is replaced — and the browsers signed in under the
-            // old one must not walk through it. Their rows go with the credential,
-            // in one transaction: half of this leaves a new password and live old
-            // cookies, which is the state recovery exists to end.
+            // Also the forgotten-password path ("DELETE FROM auth"): browsers signed
+            // in under the old one must not walk through it.
             transact(this.#db, () => {
                 this.#sql("INSERT INTO auth(id, salt, hash, created_at) VALUES (1, ?, ?, ?)")
                     .run(salt, hash(password, salt), Date.now());
@@ -93,48 +64,34 @@ export class AuthStore {
                 `only its hash is stored — it is not printed again. ` +
                 `Lost it? "DELETE FROM auth" in the database, then restart.\n`);
         }
-        // Boot is the one moment that comes around on its own. Without it, a
-        // session that expired while Pier was down would sit there notifying a
-        // phone until somebody happened to sign in.
+        // A session that expired while Pier was down must not keep notifying a phone.
         this.sweep();
     }
     #row() {
         return this.#sql("SELECT salt, hash, created_at AS createdAt FROM auth WHERE id = 1")
             .get();
     }
-    /** Every signed-in browser at once. Private: the callers that mean it also
-     *  have to tell the listeners, and `revoke(ALL)` is that pair in public. */
+    /** Private: callers must also tell the listeners; `revoke(ALL)` is that pair. */
     #dropSessions() {
         this.#sql("DELETE FROM web_sessions").run();
     }
-    /** Sessions nobody may use any more, deleted rather than merely refused: a
-     *  row is what a push subscription hangs off, so "expired" has to become
-     *  "gone" without waiting for the browser to come back and be told. Run at
-     *  boot and whenever somebody signs in — the two moments the process has a
-     *  reason to look at this table at all. */
+    /** Deleted, not merely refused: a push subscription hangs off the row. */
     sweep() {
-        const swept = this.#sql("DELETE FROM web_sessions WHERE seen_at <= ? RETURNING id")
-            .all(Date.now() - TTL_MS);
+        const now = Date.now();
+        const swept = this.#sql("DELETE FROM web_sessions WHERE seen_at <= ? OR created_at <= ? RETURNING id").all(now - TTL_MS, now - MAX_AGE_MS);
         for (const row of swept)
             this.#revoked(row.id);
         if (swept.length)
             log.info(`swept ${String(swept.length)} expired session(s)`);
     }
-    /** Whether this is the password, compared in constant time. */
     verify(password) {
         const row = this.#row();
         return row ? sameSecret(hash(password, row.salt), row.hash) : false;
     }
-    /**
-     * Replace the password, salt and all — and with it every session, the
-     * caller's own included. That is the point: a password is changed because the
-     * old one may be known, so nothing that was signed in under it stays signed
-     * in. Listeners hear it after the commit, never before.
-     */
+    /** Every session goes too, the caller's included: a password is changed
+     *  because the old one may be known. Listeners hear it after the commit. */
     setPassword(password) {
         const salt = randomBytes(16).toString("hex");
-        // Credential and sessions change together or not at all — a crash between
-        // the two writes is exactly the state "everyone signs in again" denies.
         transact(this.#db, () => {
             this.#sql("UPDATE auth SET salt = ?, hash = ?, created_at = ? WHERE id = 1")
                 .run(salt, hash(password, salt), Date.now());
@@ -142,37 +99,30 @@ export class AuthStore {
         });
         this.#revoked(ALL);
     }
-    /** Sign a browser in: one row, and the cookie value that opens it. */
     open(ip, agent) {
         const now = Date.now();
         this.sweep();
-        // The id names the row and the token proves it: 72 bits is plenty for a
-        // name, and the 256-bit token is the only part that has to resist guessing.
+        // The id names the row; the 256-bit token is the only part that resists guessing.
         const id = randomBytes(9).toString("base64url");
         const token = randomBytes(32).toString("base64url");
         this.#sql("INSERT INTO web_sessions(id, token_hash, created_at, seen_at, ip, agent)" +
             " VALUES (?, ?, ?, ?, ?, ?)").run(id, digest(token), now, now, ip, agent.slice(0, 200));
         return `${id}.${token}`;
     }
-    /**
-     * The row this cookie names, if the token matches and the row is live.
-     * `renewed` says the deadline just moved, which is the caller's cue to send
-     * the browser a cookie with the new Max-Age — the sliding window has to slide
-     * on both sides or the browser drops a cookie the database still honours.
-     */
+    /** `renewed` is the cue to resend the cookie with a new Max-Age: the window
+     *  must slide on both sides or the browser drops a cookie the database honours. */
     check(cookie) {
         const [id, token] = (cookie ?? "").split(".");
         if (!id || !token)
             return undefined;
-        const row = this.#sql("SELECT token_hash AS tokenHash, seen_at AS seenAt FROM web_sessions WHERE id = ?").get(id);
+        const row = this.#sql("SELECT token_hash AS tokenHash, seen_at AS seenAt, created_at AS createdAt" +
+            " FROM web_sessions WHERE id = ?").get(id);
         const now = Date.now();
-        // One clock: last use is the deadline, so there is no second column that
-        // can disagree with it about when this session ends. An expired row is
-        // deleted here rather than left for the next login to sweep — a session
-        // nobody may use must stop being a device Pier notifies at the same moment.
+        // Deleted here, not left for the next sweep: a session nobody may use must
+        // stop being a device Pier notifies at the same moment.
         if (!row)
             return undefined;
-        if (now - row.seenAt >= TTL_MS) {
+        if (now - row.seenAt >= TTL_MS || now - row.createdAt >= MAX_AGE_MS) {
             this.revoke(id);
             return undefined;
         }
@@ -183,8 +133,7 @@ export class AuthStore {
         this.#sql("UPDATE web_sessions SET seen_at = ? WHERE id = ?").run(now, id);
         return { id, renewed: true };
     }
-    /** Sign out one browser, or every one of them (`ALL`). Listeners hear the
-     *  same id: a revoked cookie must also close what it opened. */
+    /** Listeners hear the same id: a revoked cookie must also close what it opened. */
     revoke(id) {
         if (id === ALL)
             this.#dropSessions();
@@ -192,20 +141,15 @@ export class AuthStore {
             this.#sql("DELETE FROM web_sessions WHERE id = ?").run(id);
         this.#revoked(id);
     }
-    /** Signed-in browsers, most recently seen first. Never the token — the list
-     *  is shown to whoever is signed in, and it is not a set of credentials. */
     list() {
         return this.#sql("SELECT id, created_at AS createdAt, seen_at AS seenAt, ip, agent" +
             " FROM web_sessions WHERE seen_at > ? ORDER BY seen_at DESC").all(Date.now() - TTL_MS);
     }
-    /** A long-lived authenticated surface closes itself when a cookie is
-     *  revoked. The store and listeners share the process lifetime. */
+    /** A long-lived authenticated surface (SSE) closes itself when its cookie is revoked. */
     onRevoke(listener) {
         this.#revokeListeners.add(listener);
     }
-    /** One listener throwing must not cost the next one its notification: the
-     *  row is already gone, so a surface that never hears about it stays open on
-     *  a session that no longer exists. */
+    /** The row is already gone; a surface that never hears stays open on a dead session. */
     #revoked(id) {
         for (const listener of this.#revokeListeners) {
             try {
@@ -218,17 +162,9 @@ export class AuthStore {
     }
 }
 const hash = (password, salt) => scryptSync(password, salt, KEY_BYTES).toString("hex");
-/** What the database keeps instead of the cookie's token. */
 const digest = (token) => createHash("sha256").update(token).digest("hex");
-/**
- * What a logged-out visitor must still reach: the login form, published
- * boards, and the stylesheet those boards link — a published board rendering
- * unstyled for the person it was published to is the same bug as not serving
- * it. Both live under `/p/*` (the stylesheet at `/p/_assets/pier.css`), the
- * single exempt prefix `docs/architecture.md` reserved for this, so the rule
- * is one prefix here and one prefix in anything fronting Pier; `/boards/*`
- * stays behind the boundary.
- */
+/** The login form and `/p/*` — published boards and their stylesheet — are the
+ *  single exempt prefix docs/architecture.md reserves; `/boards/*` stays behind. */
 function isPublic(method, path) {
     if (path === "/login")
         return method === "GET" || method === "HEAD" || method === "POST";
@@ -241,17 +177,16 @@ function sameSecret(a, b) {
     const bytes = (s) => createHash("sha256").update(s).digest();
     return timingSafeEqual(bytes(a), bytes(b));
 }
-/**
- * Only a same-origin path may be returned to after login. `//evil.example` is a
- * protocol-relative URL rather than a path, and browsers normalize a backslash
- * to a slash, so `/\evil.example` is the same trick spelled differently — both
- * are what a `startsWith("/")` check alone hands an open redirect to.
- */
-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. Expired entries are pruned, and fresh identities spill into one
-// overflow bucket once the fixed map cap is reached.
+/** `//evil.example` is protocol-relative and browsers normalize `/\evil.example`
+ *  to it — and they strip whitespace and control characters from a Location
+ *  first, which turns `/<TAB>/evil.example` into one as well. Only a plain
+ *  path survives; anything else is an open redirect. */
+const safeNext = (raw) => typeof raw === "string" && /^\/(?![/\\])\S*$/.test(raw) &&
+    ![...raw].some((ch) => ch <= "\u001f" || ch === "\u007f")
+    ? raw
+    : "/";
+// In memory: the window is minutes, and the point is to make guessing slow.
+// Fresh identities spill into one overflow bucket once the cap is reached.
 const failures = new Map();
 const loopback = (address) => address === "::1" || address.startsWith("127.") || address.startsWith("::ffff:127.");
 function remoteOf(c) {
@@ -260,8 +195,8 @@ function remoteOf(c) {
         ? 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. */
+/** A forwarded address is trusted only from a local reverse proxy, and only
+ *  the rightmost hop, which that proxy appended. */
 function clientOf(c) {
     const remote = remoteOf(c);
     if (remote && !loopback(remote))
@@ -288,8 +223,7 @@ function noteFailure(client) {
     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. */
+/** Hosts, not schemes: TLS commonly terminates at the reverse proxy. */
 function originMatches(origin, host) {
     if (!origin)
         return true; // curl and other non-browser clients
@@ -310,29 +244,36 @@ function sameOrigin(c) {
         : undefined;
     return originMatches(c.req.header("origin"), forwarded || c.req.header("host") || new URL(c.req.url).host);
 }
-/** Which row this request's cookie names. The boundary already verified the
- *  token; this reads the id back off the value it accepted. Exported so a
- *  surface that belongs to one browser (its push subscription) names it the
- *  same way, rather than parsing the cookie a second way. */
+/** The boundary already verified the token; exported so a push subscription
+ *  names its browser the same way. */
 export const sessionIdOf = (c) => (getCookie(c, COOKIE) ?? "").split(".")[0] ?? "";
-/** Every route, in one place — no per-route opt-in to forget on the next one. */
+/** Stamped on the response the route actually returned: a route that hands
+ *  back a native `Response` (`Response.json`, `queueResponse`) replaces `c.res`
+ *  and loses anything set on the context before it. Absent-only, so a board
+ *  keeps the headers it chose (boards/boards.ts). */
+function sealBoundary(c) {
+    // Public responses too: the login form must not be frameable either, and a
+    // served file must not be sniffed into a type its content-type denies.
+    if (!c.res.headers.has("x-frame-options"))
+        c.header("x-frame-options", "DENY");
+    if (!c.res.headers.has("x-content-type-options"))
+        c.header("x-content-type-options", "nosniff");
+}
 export function requireAuth(store) {
     return async (c, next) => {
-        // 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();
+        if (isPublic(c.req.method, c.req.path)) {
+            await next();
+            sealBoundary(c);
+            return;
+        }
         const cookie = getCookie(c, COOKIE);
         const session = store.check(cookie);
         const unsafe = c.req.method !== "GET" && c.req.method !== "HEAD";
         if (session && 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);
+            c.res = c.json({ error: "forbidden origin" }, 403);
         }
-        if (session) {
-            // The database just moved the deadline; the browser is told the same, or
-            // it would drop a cookie that is still good.
+        else if (session) {
             if (session.renewed && cookie)
                 setSessionCookie(c, cookie);
             await next();
@@ -340,48 +281,61 @@ export function requireAuth(store) {
             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/") || unsafe) {
-            return c.json({ error: "unauthorized" }, 401);
+        else if (c.req.path.startsWith("/api/") || unsafe) {
+            // An API caller gets a status it can act on; a navigation gets the form.
+            c.res = c.json({ error: "unauthorized" }, 401);
+        }
+        else {
+            c.res = c.redirect(`/login?next=${encodeURIComponent(c.req.path)}`);
         }
-        return c.redirect(`/login?next=${encodeURIComponent(c.req.path)}`);
+        sealBoundary(c);
     };
 }
 export function registerAuthRoutes(app, store) {
     app.get("/login", (c) => c.html(loginPage(safeNext(c.req.query("next")))));
     app.post("/login", async (c) => {
         const client = clientOf(c);
-        const form = await c.req.parseBody();
-        const next = safeNext(form.next);
+        // Before the body is touched: parsing is work, and this is the one write a
+        // stranger may reach. The remembered destination is a casualty of that.
         if (throttled(client)) {
-            // The one surface strangers can reach: a burst here is the only warning
-            // an operator gets that the port is being knocked on.
+            // A burst here is the only warning an operator gets that the port is being knocked on.
             log.warn(`login throttled for ${client}`);
-            return c.html(loginPage(next, "Too many attempts. Wait a few minutes."), 429);
+            return c.html(loginPage("/", "Too many attempts. Wait a few minutes."), 429);
+        }
+        if (!c.req.header("content-type")?.startsWith("application/x-www-form-urlencoded")) {
+            return c.text("expected the sign-in form", 400);
+        }
+        // The read is the bound, not `content-length`: a chunked request declares
+        // no length, and a parser handed the whole stream is the work being denied.
+        let body;
+        try {
+            body = await readCapped(c.req.raw.body, MAX_LOGIN_BODY);
+        }
+        catch (err) {
+            log.warn(`sign-in body refused from ${client}: ${String(err)}`);
+            return c.text("sign-in body too large", 413);
         }
-        if (!store.verify(typeof form.password === "string" ? form.password : "")) {
+        const form = new URLSearchParams(new TextDecoder().decode(body));
+        const next = safeNext(form.get("next"));
+        if (!store.verify(form.get("password") ?? "")) {
             noteFailure(client);
             log.warn(`wrong password from ${client}`);
             return c.html(loginPage(next, "Wrong password."), 401);
         }
         failures.delete(client);
         log.info(`login from ${client}`);
-        // Signing in again replaces this browser's session rather than adding one:
-        // the cookie it is about to drop would otherwise stay valid for a week, as
-        // a row nobody can recognize in the device list. Verified first — the id in
-        // an unverified cookie is a string the caller chose, and `ALL` is one of
-        // the strings they could choose.
+        // Replaces this browser's session rather than adding one. Verified first:
+        // the id in an unverified cookie is a string the caller chose, and `ALL` is
+        // one of them.
         const previous = store.check(getCookie(c, COOKIE));
         if (previous)
             store.revoke(previous.id);
         setSessionCookie(c, store.open(client, c.req.header("user-agent") ?? ""));
         return c.redirect(next);
     });
-    // Re-authenticate before rotating the credential. The global boundary also
-    // requires a live cookie; knowing a password is not permission to call APIs.
+    // Re-authenticates: the boundary requires a live cookie, and 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));
@@ -398,27 +352,20 @@ export function registerAuthRoutes(app, store) {
         }
         failures.delete(client);
         store.setPassword(next);
-        // The rotation drops every session row, 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.
+        // The rotation dropped this caller's row too; clear the dead cookie.
         deleteCookie(c, COOKIE, { path: "/" });
         return c.json({ ok: true });
     });
-    // Signed-in browsers, so "sign out that one" is something an operator can
-    // see before doing. Not /api/sessions: that is the agent's sessions, and one
-    // vocabulary for two unrelated things is how the wrong one gets ended.
+    // Not /api/sessions: that is the agent's sessions, and one vocabulary for
+    // two unrelated things is how the wrong one gets ended.
     app.get("/api/devices", (c) => {
         const current = sessionIdOf(c);
         return c.json(store.list().map((d) => ({ ...d, current: d.id === current })));
     });
-    // Real revocation: the row goes, and the cookie holding its token opens
-    // nothing on the next request. Ending this browser's own session is the same
-    // call, so the client clears the cookie it is about to stop being able to use.
     app.post("/api/devices/:id/signout", (c) => {
         const id = c.req.param("id");
-        // One row per call. Signing everyone out is the password change above,
-        // which is the only thing that also invalidates the password they know.
+        // Signing everyone out is the password change, which also invalidates
+        // the password they know.
         if (id === ALL)
             return c.json({ error: "not a session id" }, 400);
         store.revoke(id);
@@ -427,36 +374,28 @@ export function registerAuthRoutes(app, store) {
             deleteCookie(c, COOKIE, { path: "/" });
         return c.json({ ok: true });
     });
-    // Signs out this browser: the row is deleted, not just the cookie cleared,
-    // so a copy of that cookie taken beforehand is dead too. Behind the boundary
-    // like every write — only a signed-in browser has anything to end.
+    // The row is deleted, not just the cookie cleared, so a copy of that cookie is dead too.
     app.post("/logout", (c) => {
         store.revoke(sessionIdOf(c));
         deleteCookie(c, COOKIE, { path: "/" });
         return c.json({ ok: true });
     });
 }
-/** The signed-in cookie — set at login, and again whenever the sliding window
- *  moved, which is why it takes the value rather than making one. */
 function setSessionCookie(c, value) {
     setCookie(c, COOKIE, value, {
         path: "/",
         httpOnly: true,
         sameSite: "Lax",
-        // Set only over TLS: a Secure cookie on plain http is dropped, which
-        // would lock out the loopback and SSH-tunnel setups. The forwarded scheme
-        // counts only from a local proxy — anywhere else it is a header the client
-        // wrote, and a stranger must not get to decide this flag.
+        // A Secure cookie on plain http is dropped, locking out loopback and SSH
+        // tunnels. The forwarded scheme counts only from a local proxy: anywhere
+        // else a stranger wrote the header.
         secure: new URL(c.req.url).protocol === "https:" ||
             (c.req.header("x-forwarded-proto")?.split(",").at(-1)?.trim() === "https" &&
                 loopback(remoteOf(c) ?? "")),
         maxAge: TTL_MS / 1000,
     });
 }
-/**
- * Self-contained HTML: the login page must render before the workbench bundle
- * is reachable, so it links nothing the boundary would refuse to serve.
- */
+/** Self-contained: it links nothing the boundary would refuse to serve. */
 function loginPage(next, error) {
     const attr = (s) => s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
     return `<!doctype html>

package/dist/web/config-sync.js

@@ -82,8 +82,8 @@ export function registerConfigSyncRoutes(app, deps) {
             try {
                 await deps.reconcile();
             }
-            catch {
-                log.error("Could not reconcile configuration sync task");
+            catch (reconcile) {
+                log.error("Could not reconcile configuration sync task", reconcile);
             }
             return c.json({ error: err instanceof Error ? err.message : "Configuration sync failed", status: deps.status() }, 409);
         }

package/dist/web/config.js

@@ -1,12 +1,8 @@
-// The agent files a scope is configured by — Pi's own config, skills and
-// extensions — read and written through the ConfigStore, never as paths. A
-// scope is "global" or a project cwd Pi already knows, which is why this is
-// the one filesystem-shaped surface that does not go through web/fs.ts: it
-// never takes a path from the browser at all.
+// The agent files a scope is configured by, through the ConfigStore. Not via
+// web/fs.ts: a scope is "global" or a cwd Pi already knows, never a browser path.
 import { guarded } from "./route.js";
 export function registerConfigRoutes(app, { factory, config, 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.
+    // Only cwds Pi already knows are accepted — never an arbitrary path.
     const parseScope = async (raw) => {
         if (!raw || raw === "global")
             return { kind: "global" };

package/dist/web/explorer.js

@@ -1,21 +1,17 @@
-// What git knows about a project directory, for the Console's Files view: the
-// refs, commits and worktrees its pickers offer, and the diffs it tones into a
-// file. Every route here runs git and nothing else — reading the directory and
-// the files themselves is web/fs.ts, which also owns the scoping both share.
+// What git knows about a project directory, for the Files view. Every route
+// runs git and nothing else; reading files is web/fs.ts.
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { scoped } from "./fs.js";
 import { guarded } from "./route.js";
 const run = promisify(execFile);
 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. */
+/** execFile blocks the shell; this blocks the argument parser (`--output=…` is a write). */
 const REF_RE = /^[^-\s][^\s]*$/;
-/** git in `root`, output capped — a diff is display data, not an archive. */
+/** 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) {
-    // Git refs for the diff pickers: current branch, branches+tags, recent
-    // commits. Not a repo → { branch: null }, which the UI renders as "no git".
+    // 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 scoped(c.req.query("root"));
@@ -27,19 +23,14 @@ export function registerExplorerRoutes(app) {
             // not a repo, or no commits yet
             return c.json({ branch: null, refs: [], commits: [], worktrees: [] });
         }
-        // Three reads of the same repository, none of which is an argument to
-        // another: one wait, not three. The rev-parse above stays alone — it is
-        // the guard that decides whether these three are asked at all.
         const [worktreeList, refList, commitLog] = await Promise.all([
             git(root, "worktree", "list", "--porcelain"),
             git(root, "for-each-ref", "--format=%(refname:short)\t%(subject)", "refs/heads", "refs/tags"),
             // Unit/record separators, because a body is multi-line by nature.
             git(root, "log", "-20", "--format=%h\u001f%at\u001f%an\u001f%ae\u001f%s\u001f%b\u001e"),
         ]);
-        // Every checkout of this repository, from git rather than from the
-        // sessions that happen to live in one: a worktree created ten seconds ago
-        // has no session in it yet, and that is exactly when its files are worth
-        // opening. Detached heads have no `branch` line, so the path stands alone.
+        // From git, not from sessions: a worktree created ten seconds ago has no
+        // session yet. Detached heads have no `branch` line.
         const worktrees = worktreeList
             .split("\n\n")
             .map((block) => {
@@ -65,9 +56,8 @@ export function registerExplorerRoutes(app) {
         });
         return c.json({ branch, refs, commits, worktrees });
     });
-    // 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.
+    // Without `file` the changed-file list, with it that file's diff. `head`
+    // empty means the working tree.
     guarded(app, "GET", "/api/explorer/diff", 404, async (c) => {
         c.header("cache-control", "no-store");
         const root = await scoped(c.req.query("root"));
@@ -76,8 +66,7 @@ export function registerExplorerRoutes(app) {
         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.
+        // The UI asks for a huge radius to render the whole file with changes toned inline.
         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) {