create-evda 0.1.7 → 0.1.9

package/lib/measurement-log.mjs

@@ -0,0 +1,246 @@
+// Is this enclave image's measurement in Sigstore's public log, signed by the workflow that built it?
+// (HQ-2083, Spec 08 section 8: "The client checks inclusion in that log, never a list EVÐA hosts.")
+//
+// The phone runs this before it trusts a hosted EVÐA: the attested VM reports a measurement, and the
+// phone accepts it only if a Sigstore bundle proves that exact digest was logged by EVÐA's CI. This
+// file is the reference the Swift port follows, and its tests run against a real bundle from the
+// public log, so the port can replay the same fixture.
+//
+// What it checks, all offline against the pinned trust root (lib/sigstore-trust.json):
+//   1. the DSSE envelope holds an in-toto statement whose subject carries the digest asked about;
+//   2. the envelope's signature verifies under the leaf certificate's key;
+//   3. the leaf chains to Fulcio's intermediate and root, is for code signing, and was valid when the
+//      log integrated the entry; its SAN and OIDC issuer are exactly the signer asked about;
+//   4. the log entry (Rekor `dsse` 0.0.1) names this payload, this signature and this certificate;
+//   5. an RFC 6962 inclusion proof takes that entry to a root hash, and that root and tree size are
+//      the ones in a checkpoint signed by Rekor's key.
+//
+// Not checked here, on purpose: the signed entry timestamp (the inclusion proof plus a signed
+// checkpoint is the stronger claim), certificate transparency SCTs, and Rekor v2 logs, which use other
+// entry kinds. A bundle from a log this file does not know is refused rather than half-checked.
+//
+// Every failure returns { ok: false, reason } in words; nothing a bundle contains can make it throw.
+
+import { createHash, createPublicKey, verify as verifySig, X509Certificate } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+export const SIGSTORE_TRUST = JSON.parse(readFileSync(new URL("./sigstore-trust.json", import.meta.url), "utf8"));
+
+/** The in-toto predicate type EVÐA's CI logs an enclave image under. */
+export const ENCLAVE_STATEMENT_TYPE = "https://evda.io/enclave-measurement/v1";
+
+/** The only signer whose enclave measurements the phone accepts: EVÐA's image workflow on main. */
+export const ENCLAVE_SIGNER = Object.freeze({
+  issuer: "https://token.actions.githubusercontent.com",
+  san: "https://github.com/mikedouzinas/evda/.github/workflows/enclave-image.yml@refs/heads/main",
+});
+
+const OID_ISSUER_V1 = "1.3.6.1.4.1.57264.1.1";
+const OID_ISSUER_V2 = "1.3.6.1.4.1.57264.1.8";
+const OID_SAN = "2.5.29.17";
+const EKU_CODE_SIGNING = "1.3.6.1.5.5.7.3.3";
+
+const sha256 = (b) => createHash("sha256").update(b).digest();
+const fromB64 = (s) => (typeof s === "string" && s.length ? Buffer.from(s, "base64") : null);
+const fail = (reason) => ({ ok: false, reason });
+
+// ─── DER, only as much as a certificate's extensions need ────────────────────────────────────────
+
+function tlv(buf, at) {
+  if (at + 2 > buf.length) throw new Error("short");
+  const tag = buf[at];
+  let len = buf[at + 1];
+  let hdr = 2;
+  if (len & 0x80) {
+    const n = len & 0x7f;
+    if (n === 0 || n > 4 || at + 2 + n > buf.length) throw new Error("length");
+    len = 0;
+    for (let i = 0; i < n; i++) len = len * 256 + buf[at + 2 + i];
+    hdr += n;
+  }
+  const start = at + hdr;
+  if (start + len > buf.length) throw new Error("overrun");
+  return { tag, start, end: start + len, next: start + len };
+}
+
+function children(buf, node) {
+  const out = [];
+  for (let at = node.start; at < node.end;) { const c = tlv(buf, at); out.push(c); at = c.next; }
+  return out;
+}
+
+function oid(bytes) {
+  const parts = [Math.floor(bytes[0] / 40), bytes[0] % 40];
+  let v = 0;
+  for (let i = 1; i < bytes.length; i++) { v = v * 128 + (bytes[i] & 0x7f); if (!(bytes[i] & 0x80)) { parts.push(v); v = 0; } }
+  return parts.join(".");
+}
+
+/** The OIDC issuer and the SAN URIs and emails of a Fulcio leaf, read from its DER. */
+export function certificateIdentity(der) {
+  const buf = Buffer.from(der);
+  const tbs = children(buf, tlv(buf, 0))[0];
+  const extWrap = children(buf, tbs).find((c) => c.tag === 0xa3);
+  const out = { issuer: null, sans: [] };
+  if (!extWrap) return out;
+  let v1 = null;
+  for (const ext of children(buf, children(buf, extWrap)[0])) {
+    const parts = children(buf, ext);
+    const id = oid(buf.subarray(parts[0].start, parts[0].end));
+    const value = parts.at(-1);
+    const raw = buf.subarray(value.start, value.end);
+    if (id === OID_ISSUER_V2) { const s = tlv(raw, 0); out.issuer = raw.subarray(s.start, s.end).toString("utf8"); }
+    else if (id === OID_ISSUER_V1) v1 = raw.toString("utf8");
+    else if (id === OID_SAN) {
+      for (const g of children(raw, tlv(raw, 0))) if (g.tag === 0x86 || g.tag === 0x81) out.sans.push(raw.subarray(g.start, g.end).toString("utf8"));
+    }
+  }
+  out.issuer ??= v1;
+  return out;
+}
+
+// ─── RFC 6962 inclusion, and the checkpoint that signs its root ──────────────────────────────────
+
+const node = (l, r) => sha256(Buffer.concat([Buffer.from([1]), l, r]));
+
+/** True when `proof` takes `leaf` (a leaf hash) at `index` to `root` in a tree of `size`. */
+export function verifyInclusion({ index, size, leaf, proof, root }) {
+  if (!Number.isSafeInteger(index) || !Number.isSafeInteger(size) || index < 0 || index >= size) return false;
+  if (!Buffer.isBuffer(leaf) || !Buffer.isBuffer(root) || !Array.isArray(proof)) return false;
+  // BigInt, because a log index passes 2^31 and JavaScript's bitwise operators stop at 32 bits.
+  const i = BigInt(index);
+  const x = i ^ BigInt(size - 1);
+  const inner = x === 0n ? 0 : x.toString(2).length;
+  const border = (i >> BigInt(inner)).toString(2).replace(/0/g, "").length;
+  if (proof.length !== inner + border) return false;
+  let h = leaf;
+  for (let k = 0; k < inner; k++) h = ((i >> BigInt(k)) & 1n) === 0n ? node(h, proof[k]) : node(proof[k], h);
+  for (let k = inner; k < proof.length; k++) h = node(proof[k], h);
+  return h.equals(root);
+}
+
+/** Verifies a Rekor checkpoint (a signed note) against one pinned log; returns its origin, size and root. */
+export function verifyCheckpoint(envelope, log) {
+  if (typeof envelope !== "string") return fail("the checkpoint is missing");
+  const split = envelope.indexOf("\n\n");
+  if (split < 0) return fail("the checkpoint is not a signed note");
+  const body = envelope.slice(0, split + 1);
+  const [origin, sizeLine, rootLine] = body.split("\n");
+  const keyId = fromB64(log.logId);
+  const key = createPublicKey({ key: fromB64(log.publicKey), format: "der", type: "spki" });
+  const host = new URL(log.baseUrl).host;
+  for (const line of envelope.slice(split + 2).split("\n")) {
+    const m = /^\u2014 (\S+) (\S+)$/.exec(line);
+    if (!m || m[1] !== host) continue;
+    const sig = Buffer.from(m[2], "base64");
+    if (sig.length < 5 || !sig.subarray(0, 4).equals(keyId.subarray(0, 4))) continue;
+    if (!verifySig("sha256", Buffer.from(body), key, sig.subarray(4))) continue;
+    const size = Number(sizeLine);
+    if (!origin?.startsWith(`${host} - `) || !Number.isSafeInteger(size) || !/^[A-Za-z0-9+/]+=*$/.test(rootLine ?? "")) return fail("the checkpoint is signed but malformed");
+    return { ok: true, origin, size, root: Buffer.from(rootLine, "base64") };
+  }
+  return fail(`the checkpoint carries no valid signature from ${host}`);
+}
+
+// ─── the bundle ──────────────────────────────────────────────────────────────────────────────────
+
+function pae(type, payload) {
+  const t = Buffer.from(type, "utf8");
+  return Buffer.concat([Buffer.from(`DSSEv1 ${t.length} `), t, Buffer.from(` ${payload.length} `), payload]);
+}
+
+const pem = (der) => `-----BEGIN CERTIFICATE-----\n${der.toString("base64").match(/.{1,64}/g).join("\n")}\n-----END CERTIFICATE-----\n`;
+
+function checkChain(leaf, trust, at) {
+  const chain = trust.fulcio.chain.map((c) => new X509Certificate(fromB64(c)));
+  const certs = [leaf, ...chain];
+  for (let i = 0; i < certs.length; i++) {
+    const issuer = certs[Math.min(i + 1, certs.length - 1)];
+    if (!certs[i].checkIssued(issuer) || !certs[i].verify(issuer.publicKey)) return `the certificate chain breaks at ${certs[i].subject || "the leaf"}`;
+    if (at < new Date(certs[i].validFrom) || at > new Date(certs[i].validTo)) return "a certificate in the chain was not valid when the entry was logged";
+  }
+  if (leaf.ca) return "the signing certificate is a CA, not a Fulcio leaf";
+  if (!(leaf.keyUsage ?? []).includes(EKU_CODE_SIGNING)) return "the signing certificate is not for code signing";
+  return null;
+}
+
+/**
+ * Confirms `digest` ({ algorithm, hex }) is the subject of an in-toto statement that `signer`
+ * ({ issuer, san }) signed through Fulcio and that Rekor logged, from a Sigstore bundle (v0.3, DSSE).
+ * Pass `predicateType` to also require the statement's type (ENCLAVE_STATEMENT_TYPE for an image).
+ */
+export function verifyLoggedMeasurement({ bundle, digest, signer, predicateType, trust = SIGSTORE_TRUST } = {}) {
+  try {
+    return check({ bundle, digest, signer, predicateType, trust });
+  } catch (err) {
+    return fail(`the bundle could not be read: ${err.message}`);
+  }
+}
+
+function check({ bundle, digest, signer, predicateType, trust }) {
+  if (!signer?.issuer || !signer?.san) return fail("no signer was named, so nothing says who must have logged it");
+  if (!digest?.algorithm || !/^[0-9a-f]+$/.test(digest?.hex ?? "")) return fail("no digest was named");
+  if (!bundle || typeof bundle !== "object") return fail("there is no bundle");
+
+  // 1. The statement.
+  const env = bundle.dsseEnvelope;
+  const payload = fromB64(env?.payload);
+  const sigs = env?.signatures;
+  if (!payload || !Array.isArray(sigs) || sigs.length !== 1) return fail("the bundle has no single-signature DSSE envelope");
+  if (env.payloadType !== "application/vnd.in-toto+json") return fail("the envelope does not hold an in-toto statement");
+  const statement = JSON.parse(payload.toString("utf8"));
+  if (!/^https:\/\/in-toto\.io\/Statement\/v(1|0\.1)$/.test(statement?._type ?? "")) return fail("the envelope does not hold an in-toto statement");
+  if (predicateType && statement.predicateType !== predicateType) return fail(`the statement type is ${statement.predicateType}, not ${predicateType}`);
+  const subjects = Array.isArray(statement.subject) ? statement.subject : [];
+  if (!subjects.some((s) => typeof s?.digest?.[digest.algorithm] === "string" && s.digest[digest.algorithm].toLowerCase() === digest.hex)) {
+    return fail(`the statement does not name ${digest.algorithm} digest ${digest.hex.slice(0, 16)}...`);
+  }
+
+  // 2 and 3. The signature, the certificate and who it was issued to.
+  const leafDer = fromB64(bundle.verificationMaterial?.certificate?.rawBytes);
+  if (!leafDer) return fail("the bundle carries no signing certificate");
+  const leaf = new X509Certificate(leafDer);
+  const sig = fromB64(sigs[0].sig);
+  if (!sig || !verifySig("sha256", pae(env.payloadType, payload), leaf.publicKey, sig)) return fail("the envelope's signature does not verify under its certificate");
+
+  const entries = bundle.verificationMaterial?.tlogEntries;
+  if (!Array.isArray(entries) || entries.length === 0) return fail("the bundle carries no log entry");
+  const entry = entries[0];
+  const integratedTime = Number(entry.integratedTime);
+  if (!Number.isSafeInteger(integratedTime)) return fail("the log entry has no integration time");
+  const chainProblem = checkChain(leaf, trust, new Date(integratedTime * 1000));
+  if (chainProblem) return fail(chainProblem);
+  const id = certificateIdentity(leafDer);
+  if (id.issuer !== signer.issuer) return fail(`the certificate's issuer is ${id.issuer}, not ${signer.issuer}`);
+  if (!id.sans.includes(signer.san)) return fail(`the certificate's signer is ${id.sans.join(", ") || "nobody"}, not ${signer.san}`);
+
+  // 4. The log entry names exactly this envelope.
+  const log = trust.tlogs.find((l) => l.logId === entry.logId?.keyId);
+  if (!log) return fail("the entry is from a log this phone does not trust");
+  if (integratedTime * 1000 < Date.parse(log.validFrom)) return fail("the entry predates the log's key");
+  const bodyBytes = fromB64(entry.canonicalizedBody);
+  if (!bodyBytes) return fail("the log entry has no body");
+  const body = JSON.parse(bodyBytes.toString("utf8"));
+  if (body.kind !== "dsse" || body.apiVersion !== "0.0.1" || entry.kindVersion?.kind !== "dsse" || entry.kindVersion?.version !== "0.0.1") {
+    return fail(`the log entry is ${body.kind} ${body.apiVersion}, and only dsse 0.0.1 is understood`);
+  }
+  if (body.spec?.payloadHash?.algorithm !== "sha256" || body.spec.payloadHash.value !== sha256(payload).toString("hex")) return fail("the log entry is for a different statement");
+  const logged = body.spec.signatures;
+  if (!Array.isArray(logged) || logged.length !== 1 || logged[0].signature !== sigs[0].sig) return fail("the log entry is for a different signature");
+  if (fromB64(logged[0].verifier)?.toString("utf8") !== pem(leafDer)) return fail("the log entry is for a different certificate");
+
+  // 5. The entry is in the tree whose root Rekor signed.
+  const proof = entry.inclusionProof;
+  if (!proof) return fail("the log entry has no inclusion proof");
+  const index = Number(proof.logIndex);
+  const size = Number(proof.treeSize);
+  const root = fromB64(proof.rootHash) ?? Buffer.alloc(0);
+  const hashes = Array.isArray(proof.hashes) ? proof.hashes.map((h) => Buffer.from(h, "base64")) : [];
+  const leafHash = sha256(Buffer.concat([Buffer.from([0]), bodyBytes]));
+  if (root.length !== 32 || !verifyInclusion({ index, size, leaf: leafHash, proof: hashes, root })) return fail("the inclusion proof does not reach the root");
+  const cp = verifyCheckpoint(proof.checkpoint?.envelope, log);
+  if (!cp.ok) return fail(cp.reason);
+  if (cp.size !== size || !cp.root.equals(root)) return fail("the checkpoint signs a different tree than the inclusion proof");
+
+  return { ok: true, logIndex: index, treeSize: size, integratedTime, statement };
+}

package/lib/messages.mjs

@@ -1,5 +1,8 @@
-// Dispatch through the record (HQ-1246): the owner's agent writes a message, the phone app shows it
-// as a card, and the owner's reply comes back as a file the agent reads on its next run.
+// Dispatch through the record (HQ-1246): the owner's agent writes a message, the EVÐA phone app
+// shows it as a card once it is paired and has synced, and the owner's reply comes back as a file
+// the agent reads on its next run. This module only writes the file -- it has no way to see whether
+// a phone ever reads it, so callers (lib/mcp.mjs, bin/evda.mjs) must not claim the card happened
+// (HQ-2161: the tool told the model it had shown a card when the owner's phone app was not running).
 //
 // The format, which the phone app (iris-mobile, the EVÐA target) reads exactly:
 //

package/lib/pairing.mjs

@@ -0,0 +1,403 @@
+// Device pairing for the evda CLI and the MCP (HQ-1217): pair a phone, list and remove devices, sync.
+//
+// The pairing code itself is atlas-local's (atlas/block/atlas-local/src/node/pairing.ts), shipped
+// in this package as one bundled file, dist/pairing.mjs (scripts/build-pairing.mjs). It is loaded
+// only when a pairing command runs, because it needs node:sqlite, which the rest of this package
+// does not: an owner on an older Node still has every other command.
+//
+// Everything a person reads from here is plain words. The one credential shown is the pairing code,
+// because typing or scanning it on the phone is the point; no id, key or hash is printed.
+
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { EvdaError } from "./errors.mjs";
+import { openEvda } from "./manifest.mjs";
+import { SYNC_BUSY, acquireSyncLock, withSyncLock } from "./sync-lock.mjs";
+
+const PKG = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+export const PAIRING_BUNDLE = join(PKG, "dist", "pairing.mjs");
+
+// node:sqlite is unflagged from Node 22.13 (and 23.4); before that it needs --experimental-sqlite.
+export const PAIRING_NODE = "22.13";
+
+/** Why pairing cannot run on this Node, in plain words, or null when it can. */
+export function pairingUnsupported(version = process.versions.node) {
+  const [major, minor] = String(version).split(".").map(Number);
+  const ok = major > 23 || (major === 23 && minor >= 4) || (major === 22 && minor >= 13);
+  return ok ? null : `Pairing a device needs Node ${PAIRING_NODE} or newer, and this is Node ${version}. Everything else in evda works on this Node; install a newer one to pair.`;
+}
+
+let loaded = null;
+
+/** The bundled pairing module, pointed at this package's own lib/. Throws in plain words when it cannot load. */
+export async function loadPairing({ bundle = PAIRING_BUNDLE, version = process.versions.node } = {}) {
+  const unsupported = pairingUnsupported(version);
+  if (unsupported) throw new EvdaError(unsupported, { code: "NODE_TOO_OLD", exit: 2 });
+  if (loaded?.bundle === bundle) return loaded.mod;
+  if (!existsSync(bundle)) {
+    throw new EvdaError("This copy of evda was installed without device pairing. Run it from the published package (npx -p create-evda evda pair), or build it here with `node scripts/build-pairing.mjs`.", { code: "NOT_BUILT", exit: 2 });
+  }
+  // Node 22 and 23 announce node:sqlite as experimental on stderr. That line is for developers, not
+  // for someone pairing a phone, so it is dropped while the bundle loads and nothing else is.
+  const emit = process.emitWarning;
+  process.emitWarning = function (warning, ...rest) {
+    if (/SQLite/i.test(String(warning?.message ?? warning))) return;
+    return emit.call(process, warning, ...rest);
+  };
+  try {
+    const mod = await import(pathToFileURL(bundle).href);
+    mod.usePersonRecord(PKG);
+    loaded = { bundle, mod };
+    return mod;
+  } catch (error) {
+    // A Node that has the version but not the module (started with --no-experimental-sqlite, or a
+    // build without it) fails here, and is told the same thing in the same words.
+    if (error?.code === "ERR_UNKNOWN_BUILTIN_MODULE") {
+      throw new EvdaError(`Pairing a device needs Node ${PAIRING_NODE} or newer with its built-in SQLite, and this Node cannot load it. Everything else in evda works on this Node.`, { code: "NODE_TOO_OLD", exit: 2 });
+    }
+    throw error;
+  } finally {
+    process.emitWarning = emit;
+  }
+}
+
+// A refusal wrote nothing and is exit 2; anything else (the relay unreachable) is exit 1.
+const REFUSALS = /^(Stopped: this disk has|Your EVÐA has no private|Your EVÐA is busy|Your EVÐA's keys|This record has no private part|This record has private parts|This record keeps its day folder|There is already a device|There is no paired device|Give the device a name|Name at least one part)/;
+function asEvdaError(error) {
+  if (error instanceof EvdaError) return error;
+  const message = error instanceof Error ? error.message : String(error);
+  return new EvdaError(message, { code: "PAIRING", exit: REFUSALS.test(message) ? 2 : 1 });
+}
+
+/** Where the computer keeps its device state: `<home>/.evda/<record>/`, never inside the record. */
+export function ownerOptions(dir, { env = process.env, relay } = {}) {
+  return { record: dir, home: resolve(env.HOME || homedir()), relayUrl: relay || env.EVDA_RELAY || undefined };
+}
+
+const partsList = (value) => (Array.isArray(value) ? value : String(value ?? "").split(",")).map((s) => String(s).trim()).filter(Boolean);
+
+export async function pair(dir, { name, parts, relay, env } = {}) {
+  const p = await loadPairing();
+  try {
+    return await p.pairDevice(ownerOptions(dir, { env, relay }), { name: name ?? "phone", parts: partsList(parts) });
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+export const NO_DEVICES = "No devices are paired with this EVÐA.";
+
+// The computer's list of devices lives beside its device state (pairing.ts, paired-devices.json).
+// A record with no id, or no list there, has paired nothing: that is answered without loading the
+// bundle, so listing devices on a fresh record, or on a Node or a copy that cannot pair, is an
+// answer and not an error.
+function pairedList(dir, env) {
+  let id;
+  try { id = openEvda(dir).manifest.id; } catch { return null; }
+  if (typeof id !== "string" || !id || /[/\\]/.test(id)) return null;
+  return join(resolve(env.HOME || homedir()), ".evda", id, "paired-devices.json");
+}
+
+export async function devices(dir, { relay, env = process.env, bundle } = {}) {
+  const list = pairedList(dir, env);
+  if (!list || !existsSync(list)) return [NO_DEVICES];
+  const p = await loadPairing(bundle ? { bundle } : {});
+  try {
+    return await p.deviceLines(ownerOptions(dir, { env, relay }));
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+/** The devices as data, for an app (HQ-1925): `[{name, state, parts, since}]`, empty when nothing is paired. No id. */
+export async function deviceData(dir, { relay, env = process.env, bundle } = {}) {
+  const list = pairedList(dir, env);
+  if (!list || !existsSync(list)) return [];
+  const p = await loadPairing(bundle ? { bundle } : {});
+  try {
+    return await p.deviceList(ownerOptions(dir, { env, relay }));
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+/** One sync as data, for an app (HQ-1925): `{paired: [names], received, sent, refused}`. No id. */
+export async function syncData(dir, { relay, env } = {}) {
+  const p = await loadPairing();
+  try {
+    return await withSyncLock(dir, () => p.syncOnce(ownerOptions(dir, { env, relay })), { env });
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+// Finish a pairing whose code was used, without scanning the record (HQ-2017). It never waits: a
+// sync that holds the record answers `busy`, and that sync collects the code itself. The Mac app
+// runs this every few seconds while a code is waiting.
+async function finishWith(dir, fn, { env = process.env } = {}) {
+  let release;
+  try {
+    release = await acquireSyncLock(dir, { waitMs: 0, env });
+  } catch (error) {
+    if (error?.code === "SYNC_BUSY") return null;
+    throw error;
+  }
+  try {
+    return await fn();
+  } finally {
+    await release();
+  }
+}
+
+/** One finish as data, for an app: `{paired: [names], waiting: [names], busy?: line}`. No id. */
+export async function finishData(dir, { relay, env = process.env } = {}) {
+  const list = pairedList(dir, env);
+  if (!list || !existsSync(list)) return { paired: [], waiting: [] };
+  const p = await loadPairing();
+  try {
+    const r = await finishWith(dir, () => p.finishPairing(ownerOptions(dir, { env, relay })), { env });
+    return r ?? { paired: [], waiting: (await p.deviceList(ownerOptions(dir, { env, relay }))).filter((d) => d.state.startsWith("waiting")).map((d) => d.name), busy: SYNC_BUSY };
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+/** One finish, in plain words. */
+export async function finish(dir, { relay, env = process.env } = {}) {
+  const r = await finishData(dir, { relay, env });
+  if (r.busy) return [r.busy];
+  const lines = [
+    ...r.paired.map((n) => `${n} is now paired.`),
+    // What went to it (HQ-2106): a finish that paired a device says what it sent and what failed.
+    ...(r.paired.length ? [`Sent ${(r.sent ?? 0).toLocaleString("en-US")} change(s) of your record to it.`] : []),
+    ...(r.errors ?? []).map((e) => `Could not send everything yet: ${e}. The next sync sends the rest.`),
+    ...r.waiting.map((n) => `Waiting for ${n} to use its code.`),
+  ];
+  return lines.length ? lines : ["No device is waiting to be added."];
+}
+
+/**
+ * What is syncing on this computer now, as data for an app (HQ-2041): `{holder: {by, op, since} | null,
+ * owed}`, read from the state's lock and outbox. A record that never paired anything answers
+ * `{holder: null, owed: null}` without loading the bundle. No id.
+ */
+export async function statusData(dir, { relay, env = process.env, bundle } = {}) {
+  const list = pairedList(dir, env);
+  if (!list || !existsSync(list)) return { holder: null, owed: null };
+  const p = await loadPairing(bundle ? { bundle } : {});
+  try {
+    return await p.syncState(ownerOptions(dir, { env, relay }));
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+// Removing a device syncs at its end (the re-keyed parts go out at once), so it holds the record's
+// sync lock as a sync does (HQ-2040): a remove and a sync never talk to the relay for one record at once.
+export async function remove(dir, name, { relay, env } = {}) {
+  if (!name || !String(name).trim()) throw new EvdaError("Say which device to remove: evda remove <device>. `evda devices` lists them.", { code: "USAGE", exit: 2 });
+  const p = await loadPairing();
+  try {
+    return await withSyncLock(dir, () => p.removeDeviceWords(ownerOptions(dir, { env, relay }), String(name).trim()), { env });
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+/**
+ * What removing a device would do, in plain words, read only (HQ-2040): the MCP says this and asks
+ * before it removes anything. Refuses a name that is not a device here, naming the ones that are.
+ */
+export async function describeRemoval(dir, name, { env = process.env } = {}) {
+  const wanted = String(name ?? "").trim();
+  if (!wanted) throw new EvdaError("Say which device to remove. evda_devices lists them.", { code: "USAGE", exit: 2 });
+  const list = (await deviceData(dir, { env })).filter((d) => d.state !== "removed");
+  const d = list.find((x) => x.name === wanted);
+  if (!d) {
+    throw new EvdaError(`There is no device called ${wanted} to remove. ${list.length ? `The devices are: ${list.map((x) => x.name).join(", ")}.` : NO_DEVICES}`, { code: "NO_DEVICE", exit: 2 });
+  }
+  if (d.state !== "paired") {
+    return [`${wanted} has not used its code (${d.state}). Removing it cancels the code, so it can never be used. Nothing else changes.`];
+  }
+  return [
+    `Removing ${wanted} would:`,
+    `1. take away its access to ${d.parts.join(", ")}, so it can no longer add to your EVÐA;`,
+    "2. change the keys of those parts, so nothing written from now on reaches it;",
+    "3. sync, so the change goes out at once.",
+    `What ${wanted} already has stays on it; removing cannot reach a copy already opened. It cannot be undone: to use ${wanted} again, pair it anew.`,
+  ];
+}
+
+/**
+ * The relay mailboxes this computer reads, one per paired device, for the watcher that takes in a
+ * device's note within seconds (HQ-2068). Empty when nothing is paired; null when a sync holds the
+ * state, so the watcher looks again later instead of waiting on it. Held in memory, never printed.
+ */
+export async function inboundMailboxes(dir, { relay, env = process.env, bundle } = {}) {
+  const list = pairedList(dir, env);
+  if (!list || !existsSync(list)) return [];
+  const p = await loadPairing(bundle ? { bundle } : {});
+  return p.inboundMailboxes(ownerOptions(dir, { env, relay }));
+}
+
+/** Every device's sync state, in plain words (HQ-2040). */
+export async function syncStatus(dir, { relay, env = process.env, bundle } = {}) {
+  const list = pairedList(dir, env);
+  if (!list || !existsSync(list)) return [NO_DEVICES];
+  const p = await loadPairing(bundle ? { bundle } : {});
+  try {
+    return await p.syncStatusWords(ownerOptions(dir, { env, relay }));
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+/** Every device with when this computer last heard from it, naming the computer (HQ-2040). */
+export async function deviceContacts(dir, { relay, env = process.env, bundle } = {}) {
+  const list = pairedList(dir, env);
+  if (!list || !existsSync(list)) return [NO_DEVICES];
+  const p = await loadPairing(bundle ? { bundle } : {});
+  try {
+    return await p.deviceContactLines(ownerOptions(dir, { env, relay }));
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+// Finishing a pairing from the MCP (HQ-2040). Both forms poll finishData, which takes the record's
+// sync lock without waiting and the state's lock without waiting: a running sync answers busy and
+// collects the code itself. So nothing here ever holds a lock between polls, and nothing runs in
+// a child process.
+export const FINISH_POLL_MS = 2_000;
+export const FINISH_WAIT_MAX_S = 120;
+const pausing = (ms) => new Promise((ok) => setTimeout(ok, ms));
+
+/**
+ * Wait up to `seconds` for a device that has a code open to use it, adding it when it does. Returns
+ * plain lines. Stops as soon as no device is waiting, whatever the deadline.
+ */
+export async function finishWaiting(dir, { seconds = 60, relay, env = process.env, pollMs } = {}) {
+  const every = pollMs ?? (Number(env.EVDA_FINISH_POLL_MS) > 0 ? Number(env.EVDA_FINISH_POLL_MS) : FINISH_POLL_MS);
+  const wait = Math.max(0, Math.min(FINISH_WAIT_MAX_S, Number(seconds) || 0)) * 1000;
+  const deadline = Date.now() + wait;
+  const paired = [];
+  let r = await finishData(dir, { relay, env });
+  paired.push(...r.paired);
+  while (r.waiting.length && Date.now() + every <= deadline) {
+    await pausing(every);
+    r = await finishData(dir, { relay, env });
+    paired.push(...r.paired);
+  }
+  const lines = paired.map((n) => `${n} is now paired.`);
+  if (r.waiting.length) lines.push(`Still waiting for ${r.waiting.join(", ")} to use the code. It is added on its own when it does, while this server runs, until the code runs out.`);
+  if (lines.length === 0) lines.push("No device is waiting to be added.");
+  return lines;
+}
+
+// One watcher a record, in this process. It stops when nothing is waiting, when `until` passes, or
+// when stopWatching is called; its timer never keeps the process alive.
+const watchers = new Map();
+
+/**
+ * After a code is made, keep finishing in the background until the device uses it or the code runs
+ * out (HQ-2040): the MCP's evda_pair completes the join itself, bounded by the code's own expiry.
+ */
+export function watchPairing(dir, { until, relay, env = process.env, everyMs } = {}) {
+  const every = everyMs ?? (Number(env.EVDA_FINISH_POLL_MS) > 0 ? Number(env.EVDA_FINISH_POLL_MS) : FINISH_POLL_MS);
+  const key = resolve(dir);
+  const prior = watchers.get(key);
+  const w = { until: Math.max(until ?? 0, prior?.until ?? 0), timer: null, paired: [...(prior?.paired ?? [])], stopped: false };
+  if (prior) clearTimeout(prior.timer);
+  watchers.set(key, w);
+  const tick = async () => {
+    if (w.stopped) return;
+    try {
+      const r = await finishData(dir, { relay, env });
+      w.paired.push(...r.paired);
+      if (!r.waiting.length && !r.busy) return stop();
+    } catch {
+      // the relay unreachable for a moment: try again on the next tick, until the code runs out
+    }
+    if (Date.now() >= w.until) return stop();
+    schedule();
+  };
+  const schedule = () => {
+    w.timer = setTimeout(tick, every);
+    w.timer.unref?.();
+  };
+  const stop = () => {
+    w.stopped = true;
+    clearTimeout(w.timer);
+    if (watchers.get(key) === w) watchers.delete(key);
+  };
+  schedule();
+  return { paired: w.paired, stop, get running() { return !w.stopped; } };
+}
+
+/** Stop every watcher in this process (for tests, and a server that is closing). */
+export function stopWatching() {
+  for (const w of watchers.values()) { w.stopped = true; clearTimeout(w.timer); }
+  watchers.clear();
+}
+
+// Both syncs hold the record's sync lock (lib/sync-lock.mjs), so the Mac app, launchd, the MCP and a
+// terminal never sync one record at the same time.
+export async function sync(dir, { relay, env } = {}) {
+  const p = await loadPairing();
+  try {
+    return await withSyncLock(dir, () => p.syncWords(ownerOptions(dir, { env, relay })), { env });
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+// Give back the space the computer's sync state holds for sealed copies nothing needs (HQ-2017):
+// media, which travels by name only, and copies no device is still owed. Prints what it would remove
+// unless `yes`. Holds the state's lock, as a sync does.
+export async function compact(dir, { yes = false, env = process.env } = {}) {
+  const p = await loadPairing();
+  try {
+    const { record, home } = ownerOptions(dir, { env });
+    return await p.compactWords({ record, home, yes: yes === true });
+  } catch (error) {
+    throw asEvdaError(error);
+  }
+}
+
+/** The MCP tool's answer: the code, the QR link, and what to do on the phone, step by step. */
+export function pairText(r) {
+  return [
+    `Pairing code for ${r.name}: ${r.code}`,
+    `QR link (make it a QR code, or open it on the phone): ${r.qr}`,
+    "",
+    "On the phone:",
+    ...r.phoneSteps.map((s, i) => `${i + 1}. ${s}`),
+    "",
+    `${r.name} will be able to read and add to ${r.parts.join(", ")}, and nothing else. The code is a key until it is used: show it only to the owner.`,
+  ].join("\n");
+}
+
+/**
+ * evda_pair's answer (HQ-2040): which computer the phone pairs to, the code, the QR as text, the
+ * steps, and that this server finishes the join on its own until the code runs out.
+ */
+export function pairToolText(r, { qrText, until } = {}) {
+  const clock = (ms) => new Date(ms).toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" });
+  return [
+    `This pairs ${r.name} to ${r.computer}, the computer this EVÐA server runs on. ${r.name} will sync with the copy of the record on ${r.computer}, and ${r.computer} is where it shows up in the device list.`,
+    "",
+    `Pairing code for ${r.name}: ${r.code}`,
+    `QR link: ${r.qr}`,
+    ...(qrText ? ["", "The QR code to scan with the phone's camera (show it to the owner exactly as it is, in a code block):", "", qrText] : []),
+    "",
+    "On the phone:",
+    "1. Scan the QR code with the camera, or open the EVÐA app, choose to join an EVÐA, and paste the code.",
+    `2. Say yes to "Pair with ${r.computer}?". The code works once, until ${clock(r.expiresAt)}.`,
+    `3. Nothing to do here: this server adds ${r.name} on its own once it uses the code, until ${clock(until ?? r.expiresAt)}. evda_finish_pairing waits for it and says when it is in.`,
+    `4. ${r.name} then holds ${r.parts.join(", ")}, and what is written there lands in today's page on ${r.computer} on the next sync.`,
+    "",
+    `${r.name} will be able to read and add to ${r.parts.join(", ")}, and nothing else. The code is a key until it is used: show it only to the owner.`,
+  ].join("\n");
+}