agent-dag 3.19.0 → 3.21.0

package/src/server/deck-home.mjs

@@ -0,0 +1,243 @@
+// Where the deck keeps its OWN things, as opposed to where Claude Code keeps
+// its things.
+//
+// For a year those were one directory. `~/.claude/agent-dag/` held the hook
+// Claude Code reads, the deck's private key, its pairings, its port registry
+// and a hundred megabytes of event log — and the only reason was that the deck
+// already knew that path, because it has to read `~/.claude` to do its job at
+// all.
+//
+// THREE THINGS THAT COST, and none of them is tidiness:
+//
+//   A person who deletes ~/.claude to fix Claude Code deletes this deck's
+//   identity. The key is what every paired machine has pinned, so it is not a
+//   setting that comes back — every colleague has to accept this deck again.
+//
+//   CLAUDE_CONFIG_DIR is Claude Code's knob for keeping a second profile, and
+//   pointing it somewhere gave the deck a brand new identity and no pairings,
+//   silently. That is a footgun with a fifty-machine blast radius and no error
+//   message anywhere.
+//
+//   The event log is a hundred megabytes of the deck's data inside another
+//   application's configuration directory. Nothing about a rotating log is
+//   configuration.
+//
+// So the deck's own state moves to where this platform keeps application data,
+// and the two things that CANNOT move stay where they are: `hook.js`, because
+// Claude Code reads it from there, and the per-pid port registry, because a
+// deck of any version has to be able to list the others — see
+// registeredDeckPorts, which reads that directory by name.
+//
+// The layout is env-paths', which is what Node command-line tools converge on,
+// and its rule is the one worth repeating: XDG is a Linux specification, so it
+// applies on Linux and nowhere else. macOS has Application Support and Logs;
+// Windows has LocalAppData. A tool that puts ~/.config on a Mac is a tool that
+// read half the page.
+//
+// NOTHING IS DELETED BY THE MOVE. Every file is COPIED to its new home and the
+// original left where it was, so a deck downgraded to the version before this
+// one finds exactly what it had. See migrateDeckFiles.
+import { homedir } from "node:os";
+import { join, posix as posixPath, win32 as winPath } from "node:path";
+import { claudeConfigDir } from "./claude-dir.mjs";
+// The Windows ladder, not `rename` (#786). MoveFileExW refuses while any other
+// process holds the destination open — a scanner, the indexer, a backup agent —
+// and the file this one renames into place is a private key. Losing that rename
+// to a virus scanner would be a deck with no identity, which is the one outcome
+// this whole module is written to prevent.
+import { renameWithRetry } from "./installer.mjs";
+
+/** The name this deck files itself under. No `-nodejs` suffix, which env-paths
+ *  adds to keep a script from colliding with a native app of the same name —
+ *  there is no other ccdeck on any of these platforms. */
+const APP = "ccdeck";
+
+/** Point the deck's whole home somewhere else in one variable. The escape
+ *  hatch for a portable install, a test, or anybody who simply wants it
+ *  elsewhere; it wins over every rule below. */
+export const HOME_ENV = "CCDECK_HOME";
+
+/** Where the deck kept everything before this, and where two of its files still
+ *  live. Also the place a migration reads from. */
+export function legacyDeckDir(env = process.env, home = homedir(), platform = process.platform) {
+  const { join } = platform === "win32" ? winPath : posixPath;
+  return join(claudeConfigDir(env, home), "agent-dag");
+}
+
+/**
+ * The deck's own durable state: its key, its pairings, the accounts it offers.
+ *
+ * CLAUDE_CONFIG_DIR IS HONOURED RATHER THAN OVERRIDDEN, and that is deliberate.
+ * Somebody who set it has asked for a separate Claude profile and has been
+ * getting a separate deck along with it for a year — separate identity,
+ * separate pairings, separate share list. Moving those people to one
+ * machine-wide deck would collapse two profiles into one on upgrade, which is
+ * exactly the kind of silent change this file exists to stop. They keep what
+ * they have; everybody else moves.
+ */
+export function deckDataDir(platform = process.platform, env = process.env, home = homedir()) {
+  // THE TARGET PLATFORM'S SEPARATOR, NOT THE HOST'S — the same reason
+  // claudeCliCandidates does it, which is that the only way a Windows answer
+  // stays right is if it can be checked from a Mac. `node:path` joins with
+  // whatever the machine running the code uses, so a bare `join` here answers
+  // `\home\u\Library\...` on Windows for a question about macOS.
+  // `resolve` for the same reason as `join` just below it: it is host-bound
+  // too, so a posix path resolved on a Windows runner comes back with the
+  // runner's drive letter glued to the front of it.
+  const { join, resolve } = platform === "win32" ? winPath : posixPath;
+  const forced = env[HOME_ENV]?.trim();
+  if (forced) return resolve(forced);
+  if (env.CLAUDE_CONFIG_DIR?.trim()) return legacyDeckDir(env, home, platform);
+  if (platform === "darwin") return join(home, "Library", "Application Support", APP);
+  if (platform === "win32") return join(localAppData(env, home, platform), APP, "Data");
+  return join(env.XDG_DATA_HOME?.trim() || join(home, ".local", "share"), APP);
+}
+
+/**
+ * Where a log belongs, which is not where a preference belongs.
+ *
+ * On Linux that is the state directory rather than the data one: XDG separates
+ * "data the user would miss" from "state the program can rebuild", and an event
+ * log that rotates at 50 MB is the second. macOS and Windows have a named place
+ * for logs and this uses it.
+ */
+export function deckLogDir(platform = process.platform, env = process.env, home = homedir()) {
+  const { join, resolve } = platform === "win32" ? winPath : posixPath;
+  const forced = env[HOME_ENV]?.trim();
+  if (forced) return resolve(forced);
+  if (env.CLAUDE_CONFIG_DIR?.trim()) return legacyDeckDir(env, home, platform);
+  if (platform === "darwin") return join(home, "Library", "Logs", APP);
+  if (platform === "win32") return join(localAppData(env, home, platform), APP, "Log");
+  return join(env.XDG_STATE_HOME?.trim() || join(home, ".local", "state"), APP);
+}
+
+/** %LOCALAPPDATA%, or the path it points at on every Windows since Vista. The
+ *  fallback is not decoration: a service account or a stripped environment can
+ *  reach this code with the variable unset, and a deck that throws there is a
+ *  deck that will not start. */
+function localAppData(env = process.env, home = homedir(), platform = process.platform) {
+  const { join } = platform === "win32" ? winPath : posixPath;
+  return env.LOCALAPPDATA?.trim() || join(home, "AppData", "Local");
+}
+
+/**
+ * WHAT MOVES, and the two things that do not.
+ *
+ * `hook.js` stays: Claude Code reads it out of ~/.claude/agent-dag and would
+ * find nothing if it moved. The per-pid `NNNNN.json` files stay: a deck lists
+ * that directory to find the other decks on this machine, and a deck of the
+ * previous version reads it by name — move them and two versions running side
+ * by side stop seeing each other.
+ *
+ * `mode` is the file's, not the directory's, and 0600 on the preferences is
+ * load-bearing: it is the one file with a private key in it.
+ */
+export const MOVED = Object.freeze([
+  Object.freeze({ name: "prefs.json", where: "data", mode: 0o600 }),
+  Object.freeze({ name: "events.jsonl", where: "log", mode: 0o644 }),
+  Object.freeze({ name: "events.jsonl.1", where: "log", mode: 0o644 }),
+]);
+
+/**
+ * Bring a deck's files to their new home, once, and never at the cost of one.
+ *
+ * FOUR RULES, and each one is a way this could have lost somebody's key:
+ *
+ *   A destination that already exists is never touched. That is what makes
+ *   this safe to run at every boot, and it is also what stops a stale copy in
+ *   the old directory from overwriting live state later.
+ *
+ *   The copy lands on a temp file in the destination directory and is renamed
+ *   into place. A copy interrupted half-way is a truncated prefs.json, and a
+ *   truncated prefs.json is a deck with no key — which is the whole thing this
+ *   is trying not to do.
+ *
+ *   The original is LEFT WHERE IT IS. Somebody who downgrades finds what they
+ *   had. It costs four kilobytes and a hundred megabytes of log that was
+ *   already there, and it buys a move nobody can be hurt by.
+ *
+ *   A failure is reported and swallowed. A read-only home, a full disk, a
+ *   permission the installer never had — none of those is a reason for the
+ *   deck not to start, and the caller falls back to reading the old path.
+ *
+ * Returns what it did, so the caller can say so once rather than every boot.
+ */
+export async function migrateDeckFiles({
+  from,
+  data,
+  log,
+  fs,
+  /** Separate from `fs` because it is not `fs.rename`: see the import above. */
+  rename = renameWithRetry,
+  onError,
+} = {}) {
+  const moved = [];
+  const failed = [];
+  for (const file of MOVED) {
+    const dir = file.where === "log" ? log : data;
+    const src = join(from, file.name);
+    const dst = join(dir, file.name);
+    if (src === dst) continue;
+    try {
+      // Both questions asked before anything is written: there is something to
+      // move, and there is nothing already there.
+      if (!(await exists(fs, src))) continue;
+      if (await exists(fs, dst)) continue;
+      await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+      const tmp = `${dst}.${process.pid}.migrating`;
+      await fs.copyFile(src, tmp);
+      await fs.chmod(tmp, file.mode).catch(() => {});
+      await rename(tmp, dst);
+      moved.push(file.name);
+    } catch (err) {
+      failed.push(file.name);
+      onError?.(file.name, err);
+    }
+  }
+  return { moved, failed };
+}
+
+async function exists(fs, path) {
+  try { await fs.stat(path); return true; } catch { return false; }
+}
+
+/** An hour. A temp file younger than this may belong to a write happening in
+ *  another deck right now, and deleting one of those turns an atomic write into
+ *  a lost one. Nothing legitimate is an hour old: the rename that retires a
+ *  temp file happens within milliseconds of its creation. */
+export const TEMP_STALE_MS = 60 * 60 * 1000;
+
+/**
+ * The litter an atomic write leaves when the process is killed between the
+ * write and the rename.
+ *
+ * Ninety-seven of them were found in one directory, the oldest six days old:
+ * two waves, one from decks that crashed and one from decks killed by hand
+ * mid-write. Nothing has ever swept them, because the code that makes them is
+ * the code that is not running any more when they are made.
+ *
+ * So the sweep belongs at START, where a process that is alive can clean up
+ * after the ones that are not — and it is deliberately blind to WHICH deck made
+ * a file, because it cannot know: it goes by age instead, which is a fact about
+ * the file rather than a guess about a pid.
+ */
+export async function sweepTempFiles({ dirs, fs, now = Date.now(), onError } = {}) {
+  let removed = 0;
+  for (const dir of dirs ?? []) {
+    let names;
+    try { names = await fs.readdir(dir); } catch { continue; }
+    for (const name of names) {
+      if (!name.endsWith(".tmp") && !name.endsWith(".migrating")) continue;
+      const path = join(dir, name);
+      try {
+        const st = await fs.stat(path);
+        if (now - st.mtimeMs < TEMP_STALE_MS) continue;
+        await fs.unlink(path);
+        removed++;
+      } catch (err) {
+        onError?.(path, err);
+      }
+    }
+  }
+  return removed;
+}

package/src/server/deck-prefs.mjs

@@ -31,15 +31,21 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 // this call. See the note over the write below (#786).
 import { renameWithRetry } from "./installer.mjs";
 import { join } from "node:path";
-import { claudeConfigDir } from "./claude-dir.mjs";
+import { deckDataDir } from "./deck-home.mjs";
 
 /** Set to "1" to keep the deck off the desktop whatever the stored preference
  *  says. Same sheet of switches as AGENTS_DECK_NO_DOWNLOAD and
  *  AGENTS_DECK_NO_INSTALL, and unchanged in meaning by this file. */
 export const OFF_ENV = "AGENTS_DECK_NO_NOTIFY";
 
-const prefsDir = (home = claudeConfigDir()) => join(home, "agent-dag");
-export const prefsPath = (home = claudeConfigDir()) => join(prefsDir(home), "prefs.json");
+/* WHERE THIS FILE LIVES, AND WHY IT MOVED. It sat in ~/.claude/agent-dag — the
+   directory Claude Code owns — which meant a person clearing Claude Code's
+   configuration cleared this deck's private key, and every machine that had
+   pinned it had to be told to trust this one again. deck-home.mjs owns the new
+   answer and the reasons; what matters here is that the parameter is still a
+   DIRECTORY, so every caller that passes one is unchanged. */
+const prefsDir = (home = deckDataDir()) => home;
+export const prefsPath = (home = deckDataDir()) => join(prefsDir(home), "prefs.json");
 
 /**
  * Every preference the deck keeps, with the answer it gives when there is no
@@ -52,9 +58,32 @@ export const prefsPath = (home = claudeConfigDir()) => join(prefsDir(home), "pre
  */
 export const DEFAULTS = Object.freeze({
   notifications: true,
+  // Whether the deck may update itself: restart into code already on disk once
+  // it is idle, and — while nobody is looking — install a newer release and
+  // restart into that (auto-update.mjs). ON, because this is the banner's
+  // `auto when idle`, which defaulted on as a localStorage key; it moved here so
+  // the server can read it with no page open.
+  autoUpdate: true,
   // LAN sync, off until somebody turns it on. `passphrase` is the only secret
   // this file has ever held, which is why the write below now names a mode.
-  lan: Object.freeze({ enabled: false, name: "", secret: "", shared: [], manual: [], trusted: [], port: 0 }),
+  lan: Object.freeze({
+    enabled: false, name: "", secret: "", shared: [], manual: [], trusted: [], port: 0,
+    // WHO PAIRS WITH WHOM, WITHOUT ANYBODY PRESSING ANYTHING. Both on, so two
+    // decks on one network find each other and pair themselves — which is what
+    // a person with three of their own machines wants and had to do by hand
+    // six times.
+    //
+    // Read this next to the two switches that gate it. `enabled` above is off,
+    // so nothing here happens until somebody deliberately puts this deck on the
+    // network; `shared` is empty, so a deck that pairs is offered nothing until
+    // somebody ticks a login. These say what happens AFTER both of those, and
+    // the dialog that turns the feature on prints them.
+    autoAsk: true,
+    autoAccept: true,
+    // What somebody HERE calls another deck, keyed by its fingerprint. The name
+    // a deck gives itself is its owner's to choose; this is the other half.
+    aliases: Object.freeze({}),
+  }),
 });
 
 /** The mode prefs.json is created with.
@@ -70,6 +99,40 @@ export const DEFAULTS = Object.freeze({
  *  window between the two, which is exactly when a secret is in it. */
 export const PREFS_MODE = 0o600;
 
+/** The longest name somebody here may give another deck. The same order as a
+ *  deck's own name, and short enough to stay one line in the panel's column. */
+export const ALIAS_MAX = 48;
+
+/** A name somebody typed for another deck, cleaned — or "" for one with
+ *  nothing left in it, which is how an alias is taken away. Control characters
+ *  go the way cleanName sends them: this string reaches a terminal as well as a
+ *  page. */
+export function cleanAlias(raw) {
+  if (typeof raw !== "string") return "";
+  const flat = raw.replace(/\p{Cc}/gu, " ").replace(/\s+/g, " ").trim();
+  return [...flat].slice(0, ALIAS_MAX).join("").trim();
+}
+
+/** A fingerprint an alias may be kept under. Real ones are `abc-def-012-345`;
+ *  what matters here is only that a typed address's placeholder — which has a
+ *  colon in it and names no deck — can never be one, and that nothing exotic
+ *  becomes a key in an object this file writes back to disk. */
+export function isAliasKey(fp) {
+  return typeof fp === "string" && /^[A-Za-z0-9-]{1,64}$/.test(fp);
+}
+
+/** The alias map, coerced. A page writes it; a hand-edited file can hold
+ *  anything. Capped, because nothing legitimate is anywhere near it. */
+function aliasesFrom(raw) {
+  const out = {};
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return out;
+  for (const [fp, name] of Object.entries(raw).slice(0, 256)) {
+    const clean = cleanAlias(name);
+    if (isAliasKey(fp) && clean) out[fp] = clean;
+  }
+  return out;
+}
+
 /** One LAN section, coerced. Unknown keys dropped like everything else here,
  *  and the two lists forced to arrays of strings — they arrive from a page and
  *  are then compared against account keys and dialled as addresses. */
@@ -93,7 +156,13 @@ function normaliseLan(raw) {
     // cannot be checked is worse than no entry at all.
     trusted: (Array.isArray(src.trusted) ? src.trusted : [])
       .filter(t => t && typeof t.fp === "string" && typeof t.pub === "string")
-      .map(t => ({ fp: t.fp, pub: t.pub, name: typeof t.name === "string" ? t.name : "" })),
+      .map(t => ({
+        fp: t.fp, pub: t.pub, name: typeof t.name === "string" ? t.name : "",
+        // When somebody here said yes. Absent on every pin made before this was
+        // kept, and absent is drawn as "before" rather than guessed.
+        ...(Number.isFinite(t.at) && t.at > 0 ? { at: t.at } : {}),
+      })),
+    aliases: aliasesFrom(src.aliases),
     // The port this deck listened on last time, so an address somebody typed on
     // the other machine still works after a restart. It asked the OS for a new
     // one every start, which is invisible while broadcast works and is exactly
@@ -102,6 +171,16 @@ function normaliseLan(raw) {
     // A PREFERENCE, never a requirement: a port already taken falls through to
     // an OS-chosen one and this is rewritten. 0 means "none yet".
     port: Number.isInteger(src.port) && src.port > 0 && src.port < 65_536 ? src.port : 0,
+    // ASK FIRST. A deck heard on the broadcast is sent a pairing request without
+    // anybody pressing `ask` — the outbound half, which gives nothing away: the
+    // machine on the other end still answers it, by hand or by the switch below.
+    autoAsk: typeof src.autoAsk === "boolean" ? src.autoAsk : true,
+    // AND SAY YES. Every deck that finishes a handshake and is not already
+    // trusted is pinned without anybody being asked — the accept button pressed
+    // in advance, and it hands whoever asks a copy of every login this deck
+    // shares. Absent means the default above; only a real boolean overrides it,
+    // because a truthy string from a hand-edited file is not an answer.
+    autoAccept: typeof src.autoAccept === "boolean" ? src.autoAccept : true,
   };
 }
 
@@ -115,13 +194,14 @@ export function normalise(raw) {
   const src = raw && typeof raw === "object" ? raw : {};
   return {
     notifications: typeof src.notifications === "boolean" ? src.notifications : DEFAULTS.notifications,
+    autoUpdate: typeof src.autoUpdate === "boolean" ? src.autoUpdate : DEFAULTS.autoUpdate,
     lan: normaliseLan(src.lan),
   };
 }
 
 /** What is on disk, or the defaults. A corrupt or absent file is not an error
  *  the user can act on mid-session, so it reads as "nothing chosen yet". */
-export async function readPrefs(home = claudeConfigDir(), deps = {}) {
+export async function readPrefs(home = deckDataDir(), deps = {}) {
   const read = deps.readFile ?? readFile;
   try { return normalise(JSON.parse(await read(prefsPath(home), "utf8"))); }
   catch { return { ...DEFAULTS }; }
@@ -142,7 +222,7 @@ let _chain = Promise.resolve();
  * Serialized for the same reason the other store is: two pages toggling two
  * different switches in the same second must not lose one of them.
  */
-export async function writePrefs(patch, home = claudeConfigDir(), deps = {}) {
+export async function writePrefs(patch, home = deckDataDir(), deps = {}) {
   const job = async () => {
     const mk = deps.mkdir ?? mkdir;
     const write = deps.writeFile ?? writeFile;
@@ -159,7 +239,7 @@ export async function writePrefs(patch, home = claudeConfigDir(), deps = {}) {
     // nothing has to send a secret it was never given.
     const merged = { ...prev, ...patch, lan: { ...prev.lan, ...(patch?.lan ?? {}) } };
     const next = normalise(merged);
-    await mk(prefsDir(home), { recursive: true });
+    await mk(prefsDir(home), { recursive: true, mode: 0o700 });
     const tmp = `${prefsPath(home)}.${process.pid}.tmp`;
     await write(tmp, JSON.stringify(next, null, 2) + "\n", { encoding: "utf8", mode: PREFS_MODE });
     await mv(tmp, prefsPath(home));

package/src/server/deck-probe.mjs

@@ -0,0 +1,111 @@
+// Is that process a deck, and is it still there — asked from anywhere.
+//
+// These four lived in src/server/index.mjs, which is the whole server: 5,800
+// lines, a dozen watchers, and timers that arm the moment the module is
+// imported. Everything that had to ask one of these questions therefore had to
+// import all of that, and three callers cannot:
+//
+//   • running-deck.mjs, read on the boot path before anything else, which for
+//     one commit took both of these as PARAMETERS purely to avoid the import.
+//   • `ccdeck --stop` and `--status`, one-shot commands that talk to a deck and
+//     exit. Starting a server to ask a server to stop is absurd on its face,
+//     and on a cold start it is also slower than the thing it is asking for.
+//   • the tests, which pin these against hook/hook.js's copy and should cost a
+//     millisecond rather than a server boot.
+//
+// So they moved down here, to a leaf that imports two node builtins and nothing
+// else. index.mjs imports them from here and RE-EXPORTS them under the names it
+// always had, so every existing caller and every existing test is untouched —
+// and there is still exactly one spelling of the handshake in the package.
+//
+// hook/hook.js keeps its own duplicate of challengeProof for the one reason
+// that has always justified it: that script is copied out of the package and
+// installed into ~/.claude, where it cannot import from anywhere. A test pins
+// the two spellings against each other, and that test is the only thing
+// standing between a changed hash and a deck that silently stops being told
+// anything.
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { request as httpRequest } from "node:http";
+
+// The same deadline hook.js gives a challenge, and for the same reason: a
+// bodyless GET to a loopback port is sub-millisecond when a deck is there and an
+// instant ECONNREFUSED when nothing is.
+export const DECK_CHALLENGE_TIMEOUT_MS = 400;
+
+// Signal 0 delivers nothing; it asks whether the pid could be signalled.
+//
+// BOTH ERRNOS, and the second one is the Windows spelling. POSIX `kill(2)`
+// answers EPERM for a process this account may not signal. On Windows
+// `uv_kill` calls `OpenProcess`, a denial is ERROR_ACCESS_DENIED, and libuv
+// maps that to EACCES — so a deck started from an elevated terminal, or under
+// another account, read as DEAD to every probe in this repo. What followed was
+// silent: the live deck's discovery file was unlinked on the next hook fire,
+// rewritten five seconds later by keepDiscovery, and its banner went on
+// claiming it was receiving events it had stopped receiving.
+export function isProcessAlive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (e) { return !!e && (e.code === "EPERM" || e.code === "EACCES"); }
+}
+
+/**
+ * The proof of knowing `token`, for a nonce the challenger chose.
+ *
+ * hook/hook.js spells this out a second time — it is installed outside the
+ * package and cannot import from here — and a test pins the two against each
+ * other. Changing one without the other silently blinds the deck.
+ */
+export function challengeProof(token, nonce) {
+  return createHash("sha256").update(`${token}:${nonce}`).digest("hex");
+}
+
+/**
+ * One challenge round trip, resolving true only on a correct proof.
+ *
+ * The compare is constant-time for the reason hook.js's sameProof is: whatever
+ * is on that port may not be a deck, and it must not be able to walk the
+ * expected proof out of us one byte at a time by timing how long we take to hang
+ * up. The nonce is fresh per call, so an answer overheard earlier is worth
+ * nothing, and the token itself never leaves this process.
+ */
+export function challengeDeck(port, token) {
+  return new Promise(resolve => {
+    let settled = false;
+    const finish = ok => { if (settled) return; settled = true; resolve(ok); };
+    const nonce = randomBytes(16).toString("hex");
+    const want = challengeProof(token, nonce);
+    const req = httpRequest({
+      hostname: "127.0.0.1",
+      port,
+      path: `/api/hook-challenge?nonce=${nonce}`,
+      method: "GET",
+      timeout: DECK_CHALLENGE_TIMEOUT_MS,
+    }, res => {
+      if (res.statusCode !== 200) { res.resume(); return res.on("end", () => finish(false)); }
+      let answer = "";
+      res.setEncoding("utf8");
+      res.on("data", c => {
+        answer += c;
+        // A deck answers in ~100 bytes. Anything pouring data at us is not one,
+        // and must not be allowed to grow this buffer without bound.
+        if (answer.length > 4096) { req.destroy(); finish(false); }
+      });
+      res.on("end", () => {
+        if (settled) return;
+        let proof;
+        try { proof = JSON.parse(answer).proof; } catch { return finish(false); }
+        finish(sameProof(proof, want));
+      });
+    });
+    req.on("error", () => finish(false));
+    req.on("timeout", () => req.destroy());
+    req.end();
+  });
+}
+
+/** hook.js's sameProof, for the same reason it is constant-time there. */
+export function sameProof(got, want) {
+  if (typeof got !== "string") return false;
+  const a = Buffer.from(got, "utf8");
+  const b = Buffer.from(want, "utf8");
+  return a.length === b.length && timingSafeEqual(a, b);
+}