penthera 1.7.0 → 1.8.0

package/src/ui/api/data.js

@@ -8,7 +8,7 @@
  * findings and bundles are addressed by ids this module hands out.
  */
 import { readdirSync, readFileSync, lstatSync, realpathSync, existsSync, statSync, mkdirSync, openSync, writeSync, closeSync, constants as FS } from "node:fs";
-import { join, resolve, relative, sep, isAbsolute, dirname } from "node:path";
+import { join, resolve, relative, sep, isAbsolute, dirname, basename } from "node:path";
 import { createHash } from "node:crypto";
 import { openMemory, buildViews, buildHistory } from "../../../lib/memory/index.js";
 import { referencesFor } from "../../../lib/references.js";
@@ -79,9 +79,27 @@ export function assertNoSymlinks(root, target) {
 }
 
 /**
- * Write a new file in `dir` (which must be `root` or below it): exclusive
- * create, never through a symlink, never over an existing file. A name is a
- * single path segment.
+ * Throws unless `dir` still resolves to itself: `dir` is a real path checked
+ * at startup, and a folder swapped for a symlink since then would send the
+ * write somewhere else.
+ */
+export function assertResolvesTo(dir, { missingOk = false } = {}) {
+  let real;
+  try {
+    real = realpathSync(dir);
+  } catch (e) {
+    // Not created yet: its parent must resolve to itself, so mkdir lands here.
+    if (missingOk && e.code === "ENOENT") return assertResolvesTo(dirname(dir));
+    throw new Error(`Refusing to write into ${dir}: ${e.code || e.message}`);
+  }
+  if (real !== dir) throw new Error(`Refusing to write into ${dir}: it now resolves to ${real}`);
+}
+
+/**
+ * Write a new file in `dir` (which must be `root` or below it, as a real
+ * path): exclusive create, never through a symlink, never over an existing
+ * file, and only while `dir` still resolves to itself. A name is a single
+ * path segment.
  */
 export function writeNewFile(root, dir, name, content) {
   if (typeof name !== "string" || !name || name.includes("/") || name.includes("\\") || name.includes("\0") || name === "." || name === "..") {
@@ -89,8 +107,10 @@ export function writeNewFile(root, dir, name, content) {
   }
   const target = join(dir, name);
   assertNoSymlinks(root, target);
+  assertResolvesTo(root, { missingOk: true });
   mkdirSync(dir, { recursive: true });
   assertNoSymlinks(root, target); // again, after mkdir
+  assertResolvesTo(dir);
   const fd = openSync(target, FS.O_WRONLY | FS.O_CREAT | FS.O_EXCL | (FS.O_NOFOLLOW || 0), 0o644);
   try {
     const buf = Buffer.from(content, "utf-8");
@@ -104,9 +124,16 @@ export function writeNewFile(root, dir, name, content) {
 
 const idFor = (s) => createHash("sha256").update(s).digest("hex").slice(0, 16);
 
+/** Real path of `p`; for a missing folder, its parent's real path plus its name. */
+function realOrPlanned(p) {
+  const abs = resolve(p);
+  try { return realpathSync(abs); } catch { /* missing */ }
+  try { return join(realpathSync(dirname(abs)), basename(abs)); } catch { return abs; }
+}
+
 export function createDataSource({ projects, reportsDir, home, memoryRoot, settings, version = "dev" }) {
   const projectRoots = realRoots(projects);
-  const reportsReal = realRoots([reportsDir])[0];
+  const reportsReal = realOrPlanned(reportsDir);
   const roots = realRoots([...projects, reportsDir, home]);
   let cache = null;
 
@@ -257,7 +284,13 @@ export function createDataSource({ projects, reportsDir, home, memoryRoot, setti
       const dir = join(reportsReal, "evidence", `${slug(project)}-${new Date().toISOString().slice(0, 19).replace(/[:T]/g, "-")}`);
       if (dirname(dirname(dir)) !== reportsReal) return null;
       assertNoSymlinks(reportsReal, dir); // reports/evidence must not be a planted symlink
-      writeEvidence(latest.data, { evidence: dir }, { version, mdOpts: { version }, argv: ["ui", "evidence", "create"] });
+      assertResolvesTo(reportsReal, { missingOk: true });
+      mkdirSync(dirname(dir), { recursive: true });
+      assertNoSymlinks(reportsReal, dir);
+      assertResolvesTo(dirname(dir));
+      // The bundle is built in a private temp folder under reports/evidence and
+      // renamed into place only while that folder still resolves to itself.
+      writeEvidence(latest.data, { evidence: dir, evidenceParent: dirname(dir) }, { version, mdOpts: { version }, argv: ["ui", "evidence", "create"] });
       cache = null;
       return { id: idFor(dir), path: relative(reportsReal, dir) };
     },

package/src/ui/api/routes.js

@@ -1,40 +1,56 @@
 /**
  * JSON API for the dashboard. Every route here runs after the gate in
- * ../security.js (Host, session cookie, Origin), so handlers only validate
+ * ../security.js (Host, Origin, bearer session), so handlers only validate
  * their own input.
  */
 import { RunError } from "./runs.js";
 
 const MAX_BODY = 64 * 1024;
+const MAX_STREAMS = 16;
 const ID = /^[0-9a-f]{16}$/;
 
-export function sendJson(res, status, body) {
+export function sendJson(res, status, body, headers = {}) {
   const buf = Buffer.from(JSON.stringify(body));
-  res.writeHead(status, { "Content-Type": "application/json; charset=utf-8", "Content-Length": buf.length });
+  res.writeHead(status, { "Content-Type": "application/json; charset=utf-8", "Content-Length": buf.length, ...headers });
   res.end(buf);
 }
 
+/** A 413 that the client can read: the rest of the body is not read, and the connection closes after the answer. */
+function tooLarge() {
+  const e = new RunError("Request body too large.", 413);
+  e.close = true;
+  return e;
+}
+
 export function readJson(req) {
   return new Promise((resolve, reject) => {
     const type = String(req.headers["content-type"] || "").split(";")[0].trim().toLowerCase();
     if (type !== "application/json") { reject(new RunError("Send JSON (Content-Type: application/json).", 415)); return; }
+    if (Number(req.headers["content-length"]) > MAX_BODY) { reject(tooLarge()); return; }
     let size = 0;
+    let over = false;
     const chunks = [];
     req.on("data", (c) => {
+      if (over) return;
       size += c.length;
-      if (size > MAX_BODY) { reject(new RunError("Request body too large.", 413)); req.destroy(); return; }
+      if (size > MAX_BODY) { over = true; chunks.length = 0; reject(tooLarge()); return; }
       chunks.push(c);
     });
     req.on("end", () => {
+      if (over) return;
       if (!size) { resolve({}); return; }
       try { resolve(JSON.parse(Buffer.concat(chunks).toString("utf-8"))); } catch { reject(new RunError("Body is not valid JSON.")); }
     });
-    req.on("error", reject);
+    // A client that hangs up (or an idle socket the server times out) is not an internal error.
+    req.on("error", () => reject(new RunError("The request body did not arrive.", 400)));
   });
 }
 
-function stream(req, res, runs, id) {
+export function stream(req, res, runs, id, onEnd = () => {}) {
   const last = Number(req.headers["last-event-id"]) || 0;
+  // The stream is long-lived by design: no idle timeout on its socket. The
+  // keep-alive comment below keeps proxies and the browser from giving up.
+  req.socket?.setTimeout?.(0);
   res.writeHead(200, {
     "Content-Type": "text/event-stream; charset=utf-8",
     "Cache-Control": "no-store",
@@ -43,18 +59,32 @@ function stream(req, res, runs, id) {
   });
   res.write(": penthera\n\n");
   const beat = setInterval(() => res.write(": keep-alive\n\n"), 15_000);
-  const end = () => { clearInterval(beat); unsubscribe?.(); if (!res.writableEnded) res.end(); };
-  const unsubscribe = runs.subscribe(id, last, (ev) => {
+  // subscribe() replays history synchronously and calls fn(null) at once for a
+  // run that already finished, so end() can run before subscribe() returns.
+  let unsubscribe = null;
+  let ended = false;
+  const end = () => {
+    if (ended) return;
+    ended = true;
+    clearInterval(beat);
+    unsubscribe?.();
+    onEnd();
+    if (!res.writableEnded) res.end();
+  };
+  unsubscribe = runs.subscribe(id, last, (ev) => {
+    if (ended) return;
     if (!ev) { res.write("event: end\ndata: {}\n\n"); end(); return; }
     res.write(`id: ${ev.seq}\nevent: ${ev.type}\ndata: ${JSON.stringify(ev)}\n\n`);
   });
+  if (ended) unsubscribe?.();
   req.on("close", end);
 }
 
 /**
  * @returns {(req, res, path: string, query: URLSearchParams) => Promise<boolean>} true when handled
  */
-export function createApi({ source, runs, version, settings }) {
+export function createApi({ source, runs, version, settings, maxStreams = MAX_STREAMS }) {
+  let streams = 0;
   const routes = [
     ["GET", /^\/api\/meta$/, () => ({ version, demo: source.demo, ...source.meta(), settings: settings.get() })],
     ["GET", /^\/api\/overview$/, () => source.overview()],
@@ -110,7 +140,10 @@ export function createApi({ source, runs, version, settings }) {
     const sse = path.match(/^\/api\/runs\/([0-9a-f]{16})\/stream$/);
     if (sse && req.method === "GET") {
       if (!runs.get(sse[1])) { sendJson(res, 404, { error: "No such run." }); return true; }
-      stream(req, res, runs, sse[1]);
+      if (streams >= maxStreams) { sendJson(res, 429, { error: "Too many open run streams. Close a dashboard tab." }, { "Retry-After": "5" }); return true; }
+      streams++;
+      let counted = true;
+      stream(req, res, runs, sse[1], () => { if (counted) { counted = false; streams--; } });
       return true;
     }
     const matching = routes.filter(([, re]) => re.test(path));
@@ -127,7 +160,7 @@ export function createApi({ source, runs, version, settings }) {
       sendJson(res, 200, out);
     } catch (e) {
       const status = e instanceof RunError ? e.status : 500;
-      sendJson(res, status, { error: status === 500 ? "Internal error. Check the terminal running penthera ui." : e.message });
+      sendJson(res, status, { error: status === 500 ? "Internal error. Check the terminal running penthera ui." : e.message }, e.close ? { Connection: "close" } : {});
       if (status === 500) process.stderr.write(`  penthera ui: ${e.stack || e.message}\n`);
     }
     return true;

package/src/ui/api/runs.js

@@ -13,11 +13,13 @@
  * Output is an append-only event list per run, streamed over SSE. Events are
  * plain data; the frontend renders them as text.
  */
-import { randomBytes } from "node:crypto";
+import { randomBytes, createHash } from "node:crypto";
 import { normalizeBaseUrl, urlToFilename } from "../../utils/url.js";
 import { confineDir } from "./data.js";
 
 const MAX_EVENTS = 5000;
+const MAX_FINISHED = 20; // finished runs kept for replay; older ones are dropped
+export const MAX_DIFF = 60000;
 const LOCAL_HOST = /^(localhost|127\.\d+\.\d+\.\d+|\[::1\]|[a-z0-9-]+\.localhost)$/i;
 const ANSI = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
 const CONTROL = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g;
@@ -31,6 +33,8 @@ export class RunError extends Error {
 
 export const cleanLine = (s) => String(s ?? "").replace(ANSI, "").replace(CONTROL, "").slice(0, 4000);
 
+export const diffSha256 = (s) => createHash("sha256").update(String(s), "utf-8").digest("hex");
+
 export function isLocalHost(hostname) {
   return LOCAL_HOST.test(hostname);
 }
@@ -91,7 +95,9 @@ export function createRunManager(deps) {
   let active = null;
 
   function emit(run, type, data = {}) {
-    const ev = { seq: run.events.length + 1, type, ts: new Date().toISOString(), data };
+    // Ids keep counting after the buffer drops old events, so a reconnect
+    // with Last-Event-ID replays exactly what it missed.
+    const ev = { seq: ++run.nextSeq, type, ts: new Date().toISOString(), data };
     run.events.push(ev);
     if (run.events.length > MAX_EVENTS) run.events.splice(0, run.events.length - MAX_EVENTS);
     for (const fn of run.listeners) fn(ev);
@@ -126,17 +132,21 @@ export function createRunManager(deps) {
         ask: (q) => new Promise((resolveAnswer) => {
           const approvalId = randomBytes(8).toString("hex");
           const p = q.plan || {};
+          // The page shows at most MAX_DIFF characters. It says so (truncated,
+          // fullLength), and an approval names the SHA-256 of what it showed.
+          const fullDiff = String(p.diff || "");
+          const diff = fullDiff.slice(0, MAX_DIFF);
           const request = {
             approvalId, iteration: q.iteration, index: q.index, total: q.total, memory: q.memory || null,
             plan: {
               title: cleanLine(p.title), recipe: cleanLine(p.recipe), framework: p.framework ? cleanLine(p.framework) : null,
               confidence: cleanLine(p.confidence), source: cleanLine(p.source),
-              files: (p.files || []).map(cleanLine), diff: String(p.diff || "").slice(0, 60000),
+              files: (p.files || []).map(cleanLine), diff, truncated: diff.length < fullDiff.length, fullLength: fullDiff.length,
               findings: (p.findings || []).map((f) => ({ title: cleanLine(f.title), severity: cleanLine(f.severity) })),
               ownerActions: (p.ownerActions || []).map(cleanLine), redacted: Boolean(p.redacted),
             },
           };
-          run.pending = { request, resolve: resolveAnswer };
+          run.pending = { request, resolve: resolveAnswer, diffSha256: diffSha256(diff), truncated: diff.length < fullDiff.length };
           emit(run, "approval", request);
         }),
       });
@@ -185,9 +195,11 @@ export function createRunManager(deps) {
     start(body) {
       if (active && active.status === "running") throw new RunError("A run is already in progress. Stop it first.", 409);
       const req = validateRunRequest(body, deps.projectRoots, deps.confineDir);
+      const finished = [...runs.values()].filter((r) => r.status !== "running");
+      for (const old of finished.slice(0, Math.max(0, finished.length - MAX_FINISHED + 1))) runs.delete(old.id);
       const run = {
         id: randomBytes(8).toString("hex"), kind: req.kind, repo: req.repo, url: req.url, status: "running",
-        startedAt: new Date().toISOString(), events: [], listeners: new Set(), pending: null, summary: null,
+        startedAt: new Date().toISOString(), events: [], nextSeq: 0, listeners: new Set(), pending: null, summary: null,
         controller: new AbortController(),
       };
       runs.set(run.id, run);
@@ -205,13 +217,26 @@ export function createRunManager(deps) {
       return publicRun(run);
     },
 
-    decide(id, { approvalId, answer } = {}) {
+    /**
+     * An approval must name the SHA-256 of the diff the page showed
+     * (`diffSha256`), and for a diff cut at MAX_DIFF characters also
+     * `acknowledgeTruncated: true`. Skip and stop need neither.
+     */
+    decide(id, { approvalId, answer, diffSha256: shown, acknowledgeTruncated } = {}) {
       const run = runs.get(id);
       if (!run) throw new RunError("No such run.", 404);
       if (!run.pending || run.pending.request.approvalId !== approvalId) throw new RunError("Nothing is waiting for that decision.", 409);
       const map = { approve: "y", y: "y", skip: "n", n: "n", later: "skip", stop: "quit", quit: "quit" };
-      const a = map[answer];
+      const a = typeof answer === "string" && Object.hasOwn(map, answer) ? map[answer] : null;
       if (!a) throw new RunError("answer must be approve, skip or stop.");
+      if (a === "y") {
+        if (typeof shown !== "string" || shown.toLowerCase() !== run.pending.diffSha256) {
+          throw new RunError("This approval does not match the diff on offer. Reload the run and review the diff again.", 409);
+        }
+        if (run.pending.truncated && acknowledgeTruncated !== true) {
+          throw new RunError(`The diff is ${run.pending.request.plan.fullLength} characters and only the first ${MAX_DIFF} were shown. Acknowledge that to apply it, or skip it and review the change in the repo.`, 409);
+        }
+      }
       const { resolve: done } = run.pending;
       run.pending = null;
       emit(run, "decision", { approvalId, answer: a });

package/src/ui/security.js

@@ -5,8 +5,13 @@
  *
  *   1. Host check   Host must be 127.0.0.1:<port> or localhost:<port>. Blocks
  *                   DNS rebinding (attacker.com resolving to 127.0.0.1).
- *   2. Session      The one-time URL token is swapped for an HttpOnly,
- *                   SameSite=Strict cookie; every other request needs it.
+ *   2. Session      The one-time token travels in the URL fragment (never
+ *                   sent over the network), the page swaps it for a session
+ *                   id through POST /api/session and keeps that in
+ *                   sessionStorage. Every other /api request needs it as
+ *                   `Authorization: Bearer`. No cookie: cookies are not bound
+ *                   to a port, so every other server on 127.0.0.1 would get
+ *                   one. The id lives in this origin's sessionStorage only.
  *   3. Origin       State-changing requests need an Origin equal to the
  *                   server's own and a JSON body (no simple cross-site POSTs).
  *
@@ -14,8 +19,6 @@
  */
 import { randomBytes, timingSafeEqual, createHash } from "node:crypto";
 
-export const COOKIE_NAME = "penthera_ui";
-
 export const CSP = [
   "default-src 'self'",
   "script-src 'self'",
@@ -70,14 +73,11 @@ export function hostAllowed(hostHeader, port) {
   return typeof hostHeader === "string" && allowedHosts(port).has(hostHeader.toLowerCase());
 }
 
-export function readCookie(header, name) {
+/** The token of an `Authorization: Bearer <token>` header, or null. */
+export function readBearer(header) {
   if (typeof header !== "string") return null;
-  for (const part of header.split(";")) {
-    const i = part.indexOf("=");
-    if (i < 0) continue;
-    if (part.slice(0, i).trim() === name) return part.slice(i + 1).trim();
-  }
-  return null;
+  const m = /^Bearer ([A-Za-z0-9_-]{16,128})$/.exec(header.trim());
+  return m ? m[1] : null;
 }
 
 /**
@@ -100,7 +100,7 @@ export function isStateChanging(method) {
 
 /**
  * Fixed-window limiter for requests that fail the session check. A signed-in
- * browser never hits it (it always has the cookie), so anything that does is
+ * browser never hits it (it always sends its session), so anything that does is
  * another page or process guessing. Unauthenticated state-changing requests
  * have no legitimate source at all and get a much smaller budget.
  */
@@ -120,11 +120,11 @@ export function createAuthLimiter({ windowMs = 60_000, maxReads = 120, maxWrites
 }
 
 /**
- * Session state: one bootstrap token (single use, printed in the URL) and the
- * session cookie. The cookie value is minted when the link is redeemed, handed
- * to the browser once in Set-Cookie, and never kept: the server holds only its
- * SHA-256, so nothing readable from this process (or a heap dump) is a
- * working session.
+ * Session state: one bootstrap token (single use, printed in the URL fragment)
+ * and the session id. The id is minted when the link is redeemed, handed to
+ * the page once in the POST /api/session response, and never kept: the server
+ * holds only its SHA-256, so nothing readable from this process (or a heap
+ * dump) is a working session.
  */
 export function createSession({ bootstrap = randomToken(), mint = () => randomBytes(32).toString("base64url") } = {}) {
   let used = false;
@@ -141,13 +141,10 @@ export function createSession({ bootstrap = randomToken(), mint = () => randomBy
       return sid;
     },
     get redeemed() { return used; },
-    check(cookieHeader) {
-      const v = readCookie(cookieHeader, COOKIE_NAME);
+    /** True for an `Authorization: Bearer <session id>` header that matches. */
+    check(authorizationHeader) {
+      const v = readBearer(authorizationHeader);
       return digest != null && typeof v === "string" && safeEqual(hash(v), digest);
     },
-    /** The Set-Cookie header for a session id that redeem() just returned. */
-    cookie(sid) {
-      return `${COOKIE_NAME}=${sid}; HttpOnly; SameSite=Strict; Path=/`;
-    },
   };
 }

package/src/ui/server.js

@@ -7,14 +7,15 @@
  * request goes through the gate in ./security.js first.
  */
 import { createServer } from "node:http";
-import { readdirSync, readFileSync } from "node:fs";
+import { readdirSync, readFileSync, lstatSync } from "node:fs";
 import { join, relative, extname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import {
   SECURITY_HEADERS, createSession, createAuthLimiter, hostAllowed, originAllowed, isStateChanging,
 } from "./security.js";
-import { createApi, sendJson } from "./api/routes.js";
+import { createApi, sendJson, readJson } from "./api/routes.js";
+import { RunError } from "./api/runs.js";
 import { createRunManager } from "./api/runs.js";
 import { createDataSource } from "./api/data.js";
 import { memoryRoot as defaultMemoryRoot } from "../../lib/memory/index.js";
@@ -28,6 +29,7 @@ const TYPES = {
   ".svg": "image/svg+xml",
   ".png": "image/png",
   ".ico": "image/x-icon",
+  ".woff2": "font/woff2",
   ".txt": "text/plain; charset=utf-8",
 };
 
@@ -70,16 +72,26 @@ export function createSettings(initial = {}) {
  * @param {object} opts
  * @param {number} [opts.port=0]
  * @param {string[]} [opts.projects]   folders the dashboard may read and run in (default: cwd)
- * @param {string} [opts.reportsDir]   report JSON folder (default: <first project>/reports)
+ * @param {string} [opts.reportsDir]   report JSON folder (default: <first project>/reports, which
+ *                                     must not be a symlink; an explicit folder may be one)
  * @param {boolean} [opts.demo]        seed realistic fake data, no disk reads
  * @param {string} [opts.version]
  * @param {object} [opts.source]       data source override (tests)
  * @param {object} [opts.runDeps]      run manager deps override (tests)
+ * @param {{ request?: number, idle?: number }} [opts.timeouts]  ms; the event stream is exempt from idle
  * @returns {Promise<{ server, port, url, origin, session, close }>}
  */
 export async function startUiServer(opts = {}) {
   const projects = (opts.projects?.length ? opts.projects : [process.cwd()]).map((p) => resolve(p));
   const reportsDir = resolve(opts.reportsDir || join(projects[0], "reports"));
+  // A cloned repo can ship `reports -> ../elsewhere`. The default folder is
+  // taken only when it is a real folder (or missing); --reports is the user's
+  // own choice and may point anywhere.
+  if (!opts.reportsDir && !opts.demo && !opts.source) {
+    let st = null;
+    try { st = lstatSync(reportsDir); } catch { /* missing: created on first write */ }
+    if (st?.isSymbolicLink()) throw new Error(`${reportsDir} is a symlink. Pass --reports <dir> to use it on purpose.`);
+  }
   const home = process.env.PENTHERA_HOME ? resolve(process.env.PENTHERA_HOME) : join(homedir(), ".penthera");
   const memoryRoot = opts.memoryRoot || defaultMemoryRoot();
   const settings = createSettings({ offline: true, memoryRoot, reportsDir });
@@ -130,43 +142,56 @@ export async function startUiServer(opts = {}) {
       const url = new URL(req.url, `http://127.0.0.1:${port}`);
       if (req.method === "OPTIONS") return plain(res, 405, "Method not allowed.", { Allow: "GET, POST" });
 
-      // 2. Session: the one-time URL token becomes an HttpOnly cookie.
-      const token = url.searchParams.get("token");
-      if (token != null && req.method === "GET" && url.pathname === "/") {
-        const sid = session.redeem(token);
-        if (!sid) { const wait = limiter.hit(req.method); if (wait) return tooMany(res, wait); }
-        if (!sid) return plain(res, 403, "This link was already used or is wrong. Restart `penthera ui` for a new one.");
-        res.writeHead(303, { "Set-Cookie": session.cookie(sid), Location: "/" });
-        return res.end();
-      }
-      if (!session.check(req.headers.cookie)) {
-        const wait = limiter.hit(req.method);
-        if (wait) return tooMany(res, wait);
-        return url.pathname.startsWith("/api/")
-          ? sendJson(res, 401, { error: "Not signed in. Open the one-time URL printed by penthera ui." })
-          : plain(res, 401, "Open the one-time URL printed by `penthera ui` in the terminal.");
+      // Static files: the page and its scripts hold no data, so they need no
+      // session (there is no cookie to carry one). Everything under /api does.
+      if (!url.pathname.startsWith("/api/")) {
+        if (req.method !== "GET" && req.method !== "HEAD") return plain(res, 405, "Method not allowed.", { Allow: "GET" });
+        const file = files.get(url.pathname);
+        if (!file) return plain(res, 404, "Not found.");
+        res.writeHead(200, { "Content-Type": file.type, "Content-Length": file.body.length });
+        return res.end(req.method === "HEAD" ? undefined : file.body);
       }
 
-      // 3. Origin on anything that changes state.
+      // 3. Origin on anything that changes state, the sign-in included.
       if (isStateChanging(req.method) && !originAllowed(req, port)) {
+        const wait = session.check(req.headers.authorization) ? 0 : limiter.hit(req.method);
+        if (wait) return tooMany(res, wait);
         return sendJson(res, 403, { error: "Cross-origin request refused." });
       }
 
-      if (await api(req, res, url.pathname, url.searchParams)) return;
+      // 2. Session: the page posts the one-time token from the URL fragment
+      // and gets the session id back, once.
+      if (url.pathname === "/api/session" && req.method === "POST") {
+        let body;
+        try { body = await readJson(req); } catch (e) { return sendJson(res, e instanceof RunError ? e.status : 400, { error: e.message }, e.close ? { Connection: "close" } : undefined); }
+        const sid = session.redeem(typeof body?.token === "string" ? body.token : "");
+        if (!sid) {
+          const wait = limiter.hit(req.method);
+          if (wait) return tooMany(res, wait);
+          return sendJson(res, 403, { error: "This link was already used or is wrong. Restart penthera ui for a new one." });
+        }
+        return sendJson(res, 200, { session: sid });
+      }
+      if (!session.check(req.headers.authorization)) {
+        const wait = limiter.hit(req.method);
+        if (wait) return tooMany(res, wait);
+        return sendJson(res, 401, { error: "Not signed in. Open the one-time URL printed by penthera ui." });
+      }
 
-      if (req.method !== "GET" && req.method !== "HEAD") return plain(res, 405, "Method not allowed.", { Allow: "GET" });
-      const file = files.get(url.pathname);
-      if (!file) return plain(res, 404, "Not found.");
-      res.writeHead(200, { "Content-Type": file.type, "Content-Length": file.body.length });
-      res.end(req.method === "HEAD" ? undefined : file.body);
+      if (await api(req, res, url.pathname, url.searchParams)) return;
+      return sendJson(res, 404, { error: "Not found." });
     } catch (e) {
       process.stderr.write(`  penthera ui: ${e.stack || e.message}\n`);
       if (!res.headersSent) plain(res, 500, "Internal error.");
       else res.end();
     }
   });
+  // Bounded request reads and idle sockets; the run event stream turns the
+  // idle timeout off for its own socket (routes.js) and keeps itself alive.
   server.headersTimeout = 20_000;
-  server.requestTimeout = 0; // SSE streams stay open
+  server.requestTimeout = opts.timeouts?.request ?? 30_000;
+  server.timeout = opts.timeouts?.idle ?? 120_000;
+  if (server.requestTimeout) server.headersTimeout = Math.min(server.headersTimeout, server.requestTimeout);
 
   await new Promise((resolveListen, reject) => {
     server.once("error", reject);
@@ -178,7 +203,7 @@ export async function startUiServer(opts = {}) {
     server,
     port,
     origin,
-    url: `${origin}/?token=${session.bootstrap}`,
+    url: `${origin}/#t=${session.bootstrap}`,
     session,
     runs,
     close: () => new Promise((r) => { server.closeAllConnections?.(); server.close(() => r()); }),