seisin 0.4.0 → 0.5.0

package/src/serve.js

@@ -11,158 +11,123 @@
  * key each role can read, which is a map of where the credentials live.
  */
 import { createServer } from "node:http";
-import { randomBytes } from "node:crypto";
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { readFileSync, existsSync, statSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { loadConfig } from "./config.js";
-import { read, logPath } from "./log.js";
+import { read, logPath, logSegments } from "./log.js";
 import { settingsFor } from "./srt.js";
-import { pending, requestsPath, settle, applyGrant, refuseIfBarred, markStale } from "./requests.js";
-import { walls } from "./walls.js";
-import { explain } from "./owners.js";
+import { pending, requestsPath, settle, applyGrant, refuseIfBarred, editPolicy, cleanReason } from "./requests.js";
+import { causesOf, describeWalls, parseSince, queue, verdicts, wallsByRole } from "./views.js";
+import { planEdit, hashOf } from "./controls.js";
+
+// Moved to views.js, which the MCP server shares; kept importable from here.
+export { causesOf } from "./views.js";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
 /**
- * Everything the page needs, read fresh on each request.
- *
- * Read fresh rather than cached because the file on disk is the truth and the
- * page is a view of it — someone editing seisin.toml in an editor should see
- * the console change, not wonder why it disagrees.
+ * `?since=<ISO date>`, or null for no filter. Anything that does not parse is
+ * ignored rather than refused: a bad filter should show everything, not an error.
  */
+export function sinceOf(url) {
+  return parseSince(new URLSearchParams((url ?? "").split("?")[1] ?? "").get("since"));
+}
+
 /**
- * Today's denials, grouped by what was denied rather than by who asked.
- *
- * Called `causes` and not `friction`: `seisin review` already has a `friction`
- * that counts something narrower — repeated denials that are not about keys —
- * and two screens of one product reporting different numbers under one label
- * is the kind of thing nobody notices until they are compared.
+ * The files the state is made of, as they are on disk now: the policy's text,
+ * and the size and mtime of every log segment and of the queue.
  *
- * The console used to show them per role, which is the same list a hundred
- * times over: measured on one deployment, 1,080 of 1,422 refusals were a
- * single lock file across six repositories, and per-role that reads as six
- * hundred identical rows instead of one sentence. Grouped, the shape of the
- * day is visible at a glance and it is almost never a territory dispute.
+ * It was read fresh on every request, because the file on disk is the truth
+ * and the page is a view of it — someone editing seisin.toml in an editor
+ * should see the console change. That still holds: anything that changes one
+ * of these files changes the signature. What no longer happens is recomputing
+ * 1–2 s of causes and walls every two seconds to find nothing had moved
+ * (measured on a multi-repo workspace's log, 7,728 lines, 32 roles).
+ */
+const memo = { path: null, hash: null, bucket: null, cfg: null, logSig: null, all: null, derived: new Map(), bodies: new Map() };
+
+/**
+ * How long a loaded config and what was derived from it are trusted.
  *
- * `stillRefused` is recomputed against the policy as it stands, not read out
- * of the log — a cause that has been granted since is history, not friction,
- * and leaving it on the page sends somebody to fix what is already fixed.
+ * Not everything the page shows is a function of these files. Some of it is
+ * the disk around them — a key directory that became a symlink, a provider's
+ * executable that appeared, a control file that now exists (settingsFor, the
+ * walls' "would still be refused today") — and with the key made of file
+ * signatures alone, that stayed as it was first seen for the server's life,
+ * defeating the one-minute memory views.verdicts keeps for the same reason.
+ * A minute is that memory's own span.
  */
-export function causesOf(cfg, entries) {
-  const by = new Map();
-  for (const e of entries) {
-    if (e.verdict !== "denied" || !e.target || !e.action) continue;
-    const k = `${e.action}\u0000${e.target}`;
-    const g = by.get(k) ?? { action: e.action, target: e.target, times: 0, roles: new Set(), owners: e.owners ?? [] };
-    g.times++;
-    g.roles.add(e.role);
-    by.set(k, g);
-  }
-  const total = [...by.values()].reduce((n, g) => n + g.times, 0);
+const MEMO_SPAN = 60_000;
 
-  /**
-   * The same grouping again, one level coarser: by the NAME at the end of the
-   * path rather than the path.
-   *
-   * Grouping by path alone gets the most important reading backwards. Measured
-   * here: six of the top seven causes were `.git/index.lock` in six different
-   * repositories, no single one above 17% — so "no cause dominates" is what the
-   * arithmetic says and the opposite of what is true. Three quarters of the
-   * window was one *kind* of thing, and that is a tooling problem with a
-   * mechanical fix, not a territory question anybody needs to rule on.
-   *
-   * By last segment, and nothing cleverer. A regex that recognised lock files,
-   * caches and build outputs would be a list of guesses about other people's
-   * toolchains that quietly goes stale; a repeated filename is a fact about
-   * this log.
-   */
-  const fams = new Map();
-  for (const g of by.values()) {
-    const name = g.target.split("/").filter(Boolean).pop() ?? g.target;
-    const f = fams.get(name) ?? { name, times: 0, paths: 0, where: [], roles: new Set() };
-    f.times += g.times;
-    f.paths++;
-    // The places, so the console can show what a name is made of instead of
-    // asserting a percentage the reader has to take on faith.
-    f.where.push({ target: g.target, times: g.times });
-    for (const r of g.roles) f.roles.add(r);
-    fams.set(name, f);
-  }
-  const families = [...fams.values()]
-    .sort((a, b) => b.times - a.times)
-    .map((f) => ({
-      name: f.name, times: f.times, paths: f.paths,
-      share: total ? f.times / total : 0,
-      roles: [...f.roles].sort(),
-      where: f.where.sort((a, b) => b.times - a.times).slice(0, 20),
-    }));
+/** How many causes the page is sent; it shows twelve and says how many more. */
+const CAUSES_SHOWN = 200;
 
-  /**
-   * What a `grep` over the log cannot tell you.
-   *
-   * The headline used to be "74% of it is one name", and a field review
-   * applied this project's own test to it: *did the number tell you something
-   * you did not know?* For somebody who reads the raw log, no — they had
-   * already counted that. The console was repeating the log back.
-   *
-   * These two are different, because they need the **policy** and the log does
-   * not contain it. `unowned` is the count of causes on paths no role claims:
-   * no grant resolves those until somebody decides who owns them, which is a
-   * decision rather than a number. `settled` is friction that has since been
-   * granted — real yesterday, noise today.
-   */
-  const live = [...by.values()];
-  const unowned = live.filter((g) => !(g.owners ?? []).length).length;
+function statSig(p) {
+  try { const s = statSync(p); return `${p}:${s.ino}:${s.size}:${s.mtimeMs}`; } catch { return `${p}:-`; }
+}
 
-  return {
-    total,
-    unowned,
-    // The real number of distinct causes, not the length of the list below.
-    // The page says "over N distinct paths" and the list is capped at twelve,
-    // so taking N from the list reported the cap as if it were the count —
-    // a wrong number stated confidently, which is worse than no number.
-    distinct: by.size,
-    families: families.slice(0, 8),
-    causes: [...by.values()]
-      .sort((a, b) => b.times - a.times)
-      .slice(0, 12)
-      .map((g) => ({
-        action: g.action,
-        target: g.target,
-        times: g.times,
-        share: total ? g.times / total : 0,
-        roles: [...g.roles].sort(),
-        owners: g.owners,
-        // How many of the roles that hit this would still hit it. `some` and
-        // not `every`: two roles out of three still blocked is still friction,
-        // and requiring all of them would quietly retire a live cause the day
-        // one role got a grant.
-        stillRefused: [...g.roles].filter((r) => cfg.roles[r] && !explain(cfg, r, g.action, g.target).allowed).length,
-      })),
-  };
+function snapshot(configPath) {
+  const text = readFileSync(configPath, "utf8");
+  const hash = createHash("sha256").update(text).digest("hex");
+  const bucket = Math.floor(Date.now() / MEMO_SPAN);
+  if (memo.path !== configPath || memo.hash !== hash || memo.bucket !== bucket) {
+    Object.assign(memo, { path: configPath, hash, bucket, cfg: loadConfig(configPath), logSig: null, all: null });
+    memo.derived.clear();
+    memo.bodies.clear();
+  }
+  const cfg = memo.cfg;
+  const file = logPath(cfg.root);
+  const logSig = logSegments(file).map(statSig).join("|");
+  if (logSig !== memo.logSig) {
+    memo.all = read(file);
+    memo.logSig = logSig;
+    memo.derived.clear();
+  }
+  return { cfg, text, all: memo.all, key: `${hash}|${bucket}|${logSig}|${statSig(requestsPath(cfg.root))}` };
+}
+
+/** Keeps the last few entries of a memo map. */
+function remember(map, key, value, max = 4) {
+  map.set(key, value);
+  while (map.size > max) map.delete(map.keys().next().value);
+  return value;
 }
 
 /**
- * `?since=<ISO date>`, or null for no filter. Anything that does not parse is
- * ignored rather than refused: a bad filter should show everything, not an error.
+ * Everything the page needs.
+ *
+ * Without each role's generated settings: they were 70 % of the 749 KB the
+ * page downloaded every two seconds and it drew none of them. One role's are
+ * served on demand by /api/settings.
  */
-export function sinceOf(url) {
-  const raw = new URLSearchParams((url ?? "").split("?")[1] ?? "").get("since");
-  const t = raw ? Date.parse(raw) : NaN;
-  return Number.isNaN(t) ? null : new Date(t).toISOString();
-}
+export function state(configPath, { since = null, snap = snapshot(configPath) } = {}) {
+  const { cfg, text, all } = snap;
 
-export function state(configPath, { since = null } = {}) {
-  const cfg = loadConfig(configPath);
   // The date filter narrows everything read from the log: activity, causes,
   // walls and the per-role counts. Not the request queue, which is what is
-  // waiting now whatever the window.
-  const entries = read(logPath(cfg.root), { limit: 200, since });
-  // The whole window, not a tail. "All" used to mean the last 4000 lines, so a
-  // 30-day window could show more denials than "all" did (6k against 4k on a
-  // real log). Every count on the page comes from this list.
-  const forShape = read(logPath(cfg.root), since ? { since } : {});
+  // waiting now whatever the window. (An entry with no `at` is kept, as
+  // read({ since }) always did.)
+  const derived = memo.derived.get(since) ?? remember(memo.derived, since, (() => {
+    const win = since ? all.filter((e) => !(e.at < since)) : all;
+    const blocks = new Map();
+    for (const e of win) if (e.verdict === "denied") blocks.set(e.role, (blocks.get(e.role) ?? 0) + 1);
+    const ask = verdicts(cfg);
+    return {
+      blocks,
+      log: win.slice(-60).reverse(),
+      // The whole window, not a tail. "All" used to mean the last 4000 lines, so a
+      // 30-day window could show more denials than "all" did (6k against 4k on a
+      // real log). Every count on the page comes from this list.
+      // More than the MCP's twelve: the page lists twelve and offers the rest,
+      // rather than cutting the list without saying so.
+      causes: causesOf(cfg, win, { ask, limit: CAUSES_SHOWN }),
+      // What each role keeps being refused AND would still be refused today.
+      // Empty for a role that has hit nothing twice, which is most of them.
+      walls: describeWalls(cfg, wallsByRole(cfg, win, { ask }), win),
+    };
+  })());
 
   const roles = Object.values(cfg.roles).map((r) => ({
     name: r.name,
@@ -174,44 +139,67 @@ export function state(configPath, { since = null } = {}) {
     localPorts: r.localPorts ?? [],
     mcp: r.mcp ?? null,
     trustd: r.trustd === true,
+    controlFiles: r.controlFiles ?? [],
     // Counted over the same window as the causes, so the KPI and the screen it
     // links to agree.
-    blocks: forShape.filter((e) => e.role === r.name && e.verdict === "denied").length,
-    settings: settingsFor(cfg, r.name),
+    blocks: derived.blocks.get(r.name) ?? 0,
   }));
 
-  // Read once for every role's walls, rather than once per role.
-  const whole = read(logPath(cfg.root), { verdict: "denied", since });
-  // Staleness is about the role's whole history, never the window: a request
-  // is not old just because the filter hides the runs that made it old.
-  const history = since ? read(logPath(cfg.root), { verdict: "denied" }) : whole;
   return {
     root: cfg.root,
     config: cfg.path,
-    requests: markStale(pending(requestsPath(cfg.root)), history),
+    // Staleness is about the role's whole history, never the window: a request
+    // is not old just because the filter hides the runs that made it old. The
+    // whole log, every verdict, as `seisin requests` and the MCP read it — this
+    // counted runs over denials only, and marked differently from both.
+    requests: queue(cfg.root, all, cfg.keyDirs),
     since,
     // The file itself, not a regeneration of it. The page can render a policy
     // from its own model, and that model has no comments — so showing it under
     // the heading "seisin.toml" next to "copy this back" invites someone to
     // paste away the provenance a grant just wrote.
-    toml: readFileSync(cfg.path, "utf8"),
+    toml: text,
     keyDirs: cfg.keyDirs,
+    protect: { instructions: cfg.protect?.instructions === true },
+    // What the control-files preview is computed against; a save sends it back
+    // so a policy edited in between is not overwritten by a stale decision.
+    base: hashOf(text),
     allowedDomains: cfg.allowedDomains,
     roles,
-    causes: causesOf(cfg, forShape),
-    // What each role keeps being refused AND would still be refused today.
-    // Empty for a role that has hit nothing twice, which is most of them.
-    walls: Object.fromEntries(
-      Object.keys(cfg.roles)
-        .map((r) => [r, walls(cfg, r, { entries: whole })])
-        .filter(([, w]) => w.length)),
-    log: entries.slice(-60).reverse(),
+    causes: derived.causes,
+    walls: derived.walls,
+    log: derived.log,
     live: true,
   };
 }
 
 /**
- * Approve or refuse one pending request, as a person.
+ * `state` as the response body, the same string for as long as nothing on disk
+ * moved — and a tag naming it, so a poll that already has it gets a 304 and
+ * no body at all.
+ */
+function stateBody(configPath, since) {
+  // One snapshot for the tag and the body. Each used to take its own, so a
+  // file that moved between the two calls got a body filed under the tag of
+  // what was there before — and a 304 for it until something else moved.
+  const snap = snapshot(configPath);
+  const k = `${snap.key}|${since}`;
+  return memo.bodies.get(k) ?? remember(memo.bodies, k, {
+    body: JSON.stringify(state(configPath, { since, snap })),
+    etag: `"${createHash("sha256").update(k).digest("hex").slice(0, 24)}"`,
+  });
+}
+
+/** One role's generated sandbox settings — what `seisin run` would hand the runtime. */
+function settingsOf(configPath, role) {
+  const { cfg } = snapshot(configPath);
+  if (typeof role !== "string" || !Object.hasOwn(cfg.roles, role))
+    throw Object.assign(new Error(`unknown role ${JSON.stringify(role)}`), { status: 404 });
+  return settingsFor(cfg, role);
+}
+
+/**
+ * Grant or decline one pending request, as a person.
  *
  * This is the only thing in seisin that writes policy, and it lives here rather
  * than in the MCP server for one reason: an agent cannot reach this. Measured,
@@ -220,71 +208,239 @@ export function state(configPath, { since = null } = {}) {
  * an exception for loopback. That is what lets the console hold the half the
  * MCP server deliberately does not.
  */
-function decide(configPath, { number, decision, reason }) {
+function decide(configPath, { key, decision, reason }) {
+  /**
+   * By the request's id, never by its place in the queue.
+   *
+   * It took a row number, counted against the queue as it stood when the
+   * request arrived — not when the person read the page. Agents keep writing
+   * to that queue, and another channel can settle an entry in between, so
+   * "grant #2" could grant whatever had moved into second place, with the
+   * reason typed for something else. Re-sending the POST granted the next one.
+   * The CLI stopped doing this long ago; the console had not.
+   */
+  if (typeof key !== "string" || !key) throw bad("key is required — the id of the request on screen");
+  /**
+   * A person declines; the boundary denies. The console sends "declined".
+   * "denied" is still accepted from anything that scripted against the old
+   * value, and is what the queue stores either way — renaming a stored value
+   * is a breaking change, listed in docs/glossary.md, not made here.
+   */
+  if (decision === "denied") decision = "declined";
+  if (decision !== "granted" && decision !== "declined")
+    throw bad(`decision must be granted or declined`);
+  /**
+   * A reason, always. A decision from the console used to be one click with an
+   * optional box beside it, so most grants reached seisin.toml with no word of
+   * why — and the provenance comment is the only record a later reader has.
+   * The CLI can still be terse; a click is too easy to be.
+   */
+  if (typeof reason !== "string" || !cleanReason(reason))
+    throw bad("a reason is required — it is written next to the decision");
+  // It grants the folder the request is keyed by (docs/api.md asked, docs/**
+  // granted), and the page says so before the click. Granting the one file
+  // instead would need the queue to key by file: a later ask for a sibling
+  // folds into this settled request and would never reach the queue.
   const cfg = loadConfig(configPath);
   const file = requestsPath(cfg.root);
-  const req = pending(file)[Number(number) - 1];
-  if (!req) throw new Error(`no pending request #${number}`);
-  if (decision !== "granted" && decision !== "denied")
-    throw new Error(`decision must be granted or denied`);
 
-  if (decision === "granted") {
-    // The config is edited as text, so comments and order survive. Written
-    // before the queue is settled: if this throws, the request is still open
-    // rather than marked done against a file that never changed.
-    refuseIfBarred(cfg, req);
-    const { toml, changed } = applyGrant(readFileSync(cfg.path, "utf8"), req, reason);
-    if (changed) writeFileSync(cfg.path, toml);
+  /**
+   * Looked up, applied and settled under one lock — the policy's, the one
+   * every grant takes (editPolicy). The lookup used to happen before it and
+   * the settle after it, so the console and `seisin grant` could both find the
+   * same request pending and both act on it. A decline takes the lock as well,
+   * though it writes no policy, for the same reason.
+   *
+   * The config is edited as text, so comments and order survive, and it is
+   * written before the queue is settled: if the write throws, the request is
+   * still open rather than marked done against a file that never changed.
+   */
+  let req = null;
+  let result = null;
+  try {
+    result = editPolicy(cfg, (before) => {
+      req = pending(file, { keyDirs: cfg.keyDirs }).find((r) => r.key === key);
+      if (!req) throw bad(`request ${key} is no longer pending — reload to see the queue as it is now`);
+      if (decision !== "granted") return { toml: before, changed: false };
+      refuseIfBarred(cfg, req);
+      return applyGrant(before, req, reason);
+    }, { after: () => settle(file, req.key, decision === "granted" ? "granted" : "denied", reason) });
+  } catch (e) {
+    if (e.code === "ELOCKED") throw Object.assign(new Error("another grant is in progress — try again in a moment"), { status: 503 });
+    throw e;
+  }
+  return {
+    ok: true, role: req.role, grant: req.grant, decision,
+    // The line the grant wrote, and where, so the page can say exactly what
+    // changed instead of "done". Null when nothing was written (a decline, or
+    // a grant the policy already held).
+    line: decision === "granted" && result?.changed ? grantLine(result.toml, req.grant) : null,
+  };
+}
+
+/** Where a grant landed in the policy: the text of its line and its number. */
+function grantLine(toml, grant) {
+  const lines = toml.split("\n");
+  for (let i = lines.length - 1; i >= 0; i--)
+    if (lines[i].includes(`"${grant}"`) && lines[i].includes("# granted")) return { text: lines[i].trim(), number: i + 1 };
+  return null;
+}
+
+/**
+ * The lines an edit changes, and where: what the preview shows before a save
+ * and the confirmation names after it. The file is edited in one place, so a
+ * common head and tail leave exactly the lines that moved.
+ */
+export function lineDiff(before, after) {
+  const a = before.split("\n"), b = after.split("\n");
+  let head = 0;
+  while (head < a.length && head < b.length && a[head] === b[head]) head++;
+  let tail = 0;
+  while (tail < a.length - head && tail < b.length - head && a[a.length - 1 - tail] === b[b.length - 1 - tail]) tail++;
+  return { at: head + 1, removed: a.slice(head, a.length - tail), added: b.slice(head, b.length - tail) };
+}
+
+/**
+ * Hand a role a family of control files, or protect instruction files — the
+ * second thing a person can change from the console, and the same kind of
+ * write as a grant: through editPolicy, under the policy's lock, atomically,
+ * with a stamp saying it came from here and when.
+ *
+ * `dryRun` answers what the edit would do — the denyWrite entries each role's
+ * profile gains or loses, and who could then write each family — and writes
+ * nothing. The page shows that and asks before it sends the real one. `base`
+ * is the hash of the text the preview was computed from: a policy that moved
+ * in between (a grant, an editor) is a 409, not a save over a decision the
+ * person never saw.
+ *
+ * One edit per call: `{ role, families }` for a role, or `{ protect }` for
+ * `[protect] instructions`. The families are config.js's own list; asking
+ * for `.claude` or git hooks is a 400, as it is in the file.
+ */
+function controlFiles(configPath, args, { lockWaitMs = 10000 } = {}) {
+  const { role, families, protect, reason, dryRun, base } = args;
+  const forRole = role !== undefined || families !== undefined;
+  if (forRole === (protect !== undefined))
+    throw bad("send either { role, families } or { protect } — one edit at a time");
+  if (reason !== undefined && typeof reason !== "string") throw bad("reason must be text");
+  // Strictly a boolean: "true" as a string must not be read as a save.
+  if (dryRun !== undefined && typeof dryRun !== "boolean") throw bad("dryRun must be true or false");
+  if (base !== undefined && typeof base !== "string") throw bad("base must be the hash the preview returned");
+  const edit = forRole ? { kind: "role", role, families, reason } : { kind: "protect", on: protect, reason };
+  const cfg = loadConfig(configPath);
+  // The roles an edit reaches, and of those the ones whose profile it leaves
+  // as it is — named, so a preview that lists two roles does not read as
+  // "the other five were forgotten".
+  const reached = () => edit.kind === "role" ? [edit.role] : Object.keys(cfg.roles);
+  const unaffected = (p) => p.changed ? reached(p).filter((r) => !p.diff.some((d) => d.role === r)) : [];
+  if (dryRun === true) {
+    const before = readFileSync(configPath, "utf8");
+    const { toml, ...plan } = planEdit(cfg, before, edit);
+    return { ok: true, dryRun: true, ...plan, unaffected: unaffected(plan), lines: plan.changed ? lineDiff(before, toml) : null };
   }
-  settle(file, req.key, decision, reason ?? "");
-  return { ok: true, role: req.role, grant: req.grant, decision };
+  let plan = null;
+  let lines = null;
+  try {
+    editPolicy(cfg, (before) => {
+      if (base !== undefined && hashOf(before) !== base)
+        throw Object.assign(new Error("the policy changed since this preview — look at it again before saving"), { status: 409 });
+      // Planned against the text under the lock, and against a config loaded
+      // from it: a grant that landed a moment ago is kept, not overwritten.
+      plan = planEdit(loadConfig(configPath, before), before, edit);
+      if (plan.changed) lines = lineDiff(before, plan.toml);
+      return { toml: plan.toml, changed: plan.changed };
+    }, { waitMs: lockWaitMs });
+  } catch (e) {
+    if (e.code === "ELOCKED") throw Object.assign(new Error("another edit of the policy is in progress — try again in a moment"), { status: 503 });
+    throw e;
+  }
+  const { toml, ...rest } = plan;
+  return { ok: true, dryRun: false, ...rest, unaffected: unaffected(plan), lines };
+}
+
+/** An error that is the request's fault. */
+function bad(message) {
+  return Object.assign(new Error(message), { status: 400 });
+}
+
+/**
+ * The status for an error thrown while answering: its own when it has one; a
+ * failed read or write of a file (it carries a syscall) is the server's; what
+ * is left — a bad field, a grant the policy refuses — is the request's.
+ */
+function statusOf(e) {
+  if (Number.isInteger(e?.status)) return e.status;
+  return e?.syscall ? 500 : 400;
 }
 
-/** The body of a POST, capped: this endpoint takes three short fields. */
 /**
  * A request body, capped. The cap is per route: one decision is a few hundred
  * bytes, but "decline all" carries every key on screen — 109 of them were
  * 9.3 KB, over the old flat 4 KB, and the connection was cut with nothing but
- * "Failed to fetch" in the browser. Found by Carlos on the first real use.
+ * "Failed to fetch" in the browser. Found on first real use.
+ *
+ * Over the cap it is refused with 413, not cut: the caller answers first and
+ * the connection is closed after the answer has gone (see `answer`).
  */
 function readBody(req, max = 4096) {
   return new Promise((ok, fail) => {
     let s = "";
+    let over = false;
+    req.setEncoding("utf8");
     req.on("data", (c) => {
+      if (over) return;
       s += c;
-      if (s.length > max) { fail(new Error("body too large")); req.destroy(); }
+      if (Buffer.byteLength(s) > max) {
+        over = true;
+        s = "";
+        fail(Object.assign(new Error(`body too large — this route takes at most ${max} bytes`), { status: 413 }));
+      }
     });
-    req.on("end", () => ok(s));
+    req.on("end", () => { if (!over) ok(s); });
+    req.on("error", (e) => { if (!over) fail(Object.assign(e, { status: 400 })); });
   });
 }
 
 /**
- * Refuse every request the page was showing, in one go.
+ * Decline every request the page was showing, in one go.
  *
- * Only refusing. There is no "approve all" and there will not be: a grant is a
+ * Only declining. There is no "grant all" and there will not be: a grant is a
  * decision about one path and one owner, and doing forty of them without
  * reading them is the permissive default this tool exists to stand against.
- * Refusing in bulk is safe — it grants nothing and changes no policy — and it
+ * Declining in bulk is safe — it grants nothing and changes no policy — and it
  * is what a queue full of noise from a bug already fixed needs.
  *
  * By key, not "whatever is pending now": a request that arrived after the page
- * drew is one the person has not seen, and it stays.
+ * drew is one the person has not seen, and it stays. Under the policy lock,
+ * like a single decision, so a grant from another channel cannot land between
+ * the lookup and the settle.
  */
 function declineAll(configPath, { keys, reason }) {
-  if (!Array.isArray(keys) || !keys.length) throw new Error("keys must list the requests on screen");
+  if (!Array.isArray(keys) || !keys.length) throw bad("keys must list the requests on screen");
+  if (typeof reason !== "string" || !cleanReason(reason))
+    throw bad("a reason is required — it is written next to every request declined");
   const cfg = loadConfig(configPath);
   const file = requestsPath(cfg.root);
   const wanted = new Set(keys.map(String));
   let declined = 0;
-  for (const req of pending(file)) {
-    if (!wanted.has(req.key)) continue;
-    settle(file, req.key, "denied", reason ?? "");
-    declined++;
+  try {
+    editPolicy(cfg, (before) => ({ toml: before, changed: false }), {
+      after: () => {
+        for (const req of pending(file)) {
+          if (!wanted.has(req.key)) continue;
+          settle(file, req.key, "denied", reason);
+          declined++;
+        }
+      },
+    });
+  } catch (e) {
+    if (e.code === "ELOCKED") throw Object.assign(new Error("another grant is in progress — try again in a moment"), { status: 503 });
+    throw e;
   }
   return { ok: true, declined };
 }
 
-export function serve(configPath, port = 4178) {
+export function serve(configPath, port = 4178, { lockWaitMs = 10000 } = {}) {
   const page = join(HERE, "..", "ui", "index.html");
   if (!existsSync(page)) throw new Error("the console is missing from this install");
 
@@ -294,7 +450,7 @@ export function serve(configPath, port = 4178) {
    * Loopback is not a boundary against the browser: any site the operator has
    * open can POST to 127.0.0.1. It cannot read this token, and asking for it in
    * a custom header also forces a preflight that this server never answers. So
-   * the page can approve and a tab from somewhere else cannot.
+   * the page can grant and a tab from somewhere else cannot.
    */
   const token = randomBytes(24).toString("hex");
 
@@ -315,7 +471,16 @@ export function serve(configPath, port = 4178) {
    * from there, keeps it for the tab, and removes it from the address bar and
    * the history entry. Anything that fetches `/` gets a page with no token in it.
    */
-  const authorized = (req) => req.headers["x-seisin-token"] === token;
+  // Constant-time compare: `===` on a secret leaks its length and a prefix
+  // through timing. Loopback with a Host check makes it near-theoretical, but a
+  // role with local_binding can reach this port, so it is not free.
+  const tokenBuf = Buffer.from(token);
+  const authorized = (req) => {
+    const got = req.headers["x-seisin-token"];
+    if (typeof got !== "string") return false;
+    const gotBuf = Buffer.from(got);
+    return gotBuf.length === tokenBuf.length && timingSafeEqual(gotBuf, tokenBuf);
+  };
 
   /**
    * The Host header has to name this server.
@@ -349,42 +514,67 @@ export function serve(configPath, port = 4178) {
       res.writeHead(403, { "content-type": "application/json" });
       return res.end(JSON.stringify({ error: "bad or missing token — open the URL `seisin ui` printed" }));
     }
-    if (req.method === "POST" && pathOf(req.url) === "/api/decline-all") {
-      try {
-        // ~85 bytes per key: 1 MB is ten thousand requests on one screen.
-        const out = declineAll(configPath, JSON.parse((await readBody(req, 1024 * 1024)) || "{}"));
-        res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" });
-        return res.end(JSON.stringify(out));
-      } catch (e) {
-        res.writeHead(400, { "content-type": "application/json" });
-        return res.end(JSON.stringify({ error: e.message }));
-      }
-    }
-    if (req.method === "POST" && pathOf(req.url) === "/api/decide") {
+    /**
+     * A JSON answer. On an error the connection is closed once the answer has
+     * gone: a body refused half-read would otherwise be parsed as the next
+     * request on a keep-alive socket.
+     */
+    const answer = (status, obj, close = false) => {
+      res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store", ...(close && { connection: "close" }) });
+      res.end(JSON.stringify(obj), () => { if (close) req.socket?.destroy(); });
+    };
+    const post = async (max, fn) => {
+      let body;
+      try { body = await readBody(req, max); }
+      catch (e) { return answer(e.status ?? 400, { error: e.message }, true); }
       try {
-        const out = decide(configPath, JSON.parse((await readBody(req)) || "{}"));
-        res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" });
-        return res.end(JSON.stringify(out));
+        let args;
+        try { args = JSON.parse(body || "{}"); } catch { throw bad("the body is not JSON"); }
+        return answer(200, fn(args ?? {}));
       } catch (e) {
-        res.writeHead(400, { "content-type": "application/json" });
-        return res.end(JSON.stringify({ error: e.message }));
+        return answer(statusOf(e), { error: e.message });
       }
-    }
+    };
+    // ~85 bytes per key: 1 MB is ten thousand requests on one screen.
+    if (req.method === "POST" && pathOf(req.url) === "/api/decline-all")
+      return post(1024 * 1024, (args) => declineAll(configPath, args));
+    if (req.method === "POST" && pathOf(req.url) === "/api/decide")
+      return post(4096, (args) => decide(configPath, args));
+    if (req.method === "POST" && pathOf(req.url) === "/api/control-files")
+      return post(4096, (args) => controlFiles(configPath, args, { lockWaitMs }));
     if (req.method !== "GET" && req.method !== "HEAD") {
       res.writeHead(405).end("method not allowed");
       return;
     }
-    if (pathOf(req.url) === "/api/state") {
-      let body;
-      try {
-        body = JSON.stringify(state(configPath, { since: sinceOf(req.url) }));
-      } catch (e) {
-        res.writeHead(500, { "content-type": "application/json" });
-        return res.end(JSON.stringify({ error: e.message }));
+    if (pathOf(req.url).startsWith("/api/")) {
+      // HEAD computed the whole state and threw the body away — a request that
+      // cost what a GET does and answered nothing. The API is GET only.
+      if (req.method !== "GET") {
+        res.writeHead(405, { allow: "GET" });
+        return res.end();
+      }
+      if (pathOf(req.url) === "/api/state") {
+        let got;
+        try {
+          got = stateBody(configPath, sinceOf(req.url));
+        } catch (e) {
+          return answer(500, { error: e.message });
+        }
+        // The page polls, so tell every cache in between to stay out of it;
+        // the page itself sends the tag back and is told when nothing moved.
+        const head = { "content-type": "application/json", "cache-control": "no-store", etag: got.etag };
+        if (req.headers["if-none-match"] === got.etag) { res.writeHead(304, head); return res.end(); }
+        res.writeHead(200, head);
+        return res.end(got.body);
+      }
+      if (pathOf(req.url) === "/api/settings") {
+        try {
+          const role = new URLSearchParams(req.url.split("?")[1] ?? "").get("role");
+          return answer(200, { role, settings: settingsOf(configPath, role) });
+        } catch (e) {
+          return answer(e.status ?? 500, { error: e.message });
+        }
       }
-      // The page polls, so tell every cache in between to stay out of it.
-      res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" });
-      return res.end(body);
     }
     if (pathOf(req.url) === "/" || pathOf(req.url) === "/index.html") {
       // No token in here. It used to be inlined, which handed it to anything