create-evda 0.1.9 → 0.1.11

package/lib/attested-host.mjs

@@ -0,0 +1,287 @@
+// The gate a client goes through before it sends a hosted EVÐA anything: a record, a circle key, a
+// token. (HQ-2083, Spec 08 section 8: "If it doesn't match, your phone won't send anything.")
+//
+// lib/tdx-attestation.mjs answers "does this quote prove this VM?". This file is what makes that answer
+// decide whether bytes leave the device. A client gets a payload to a hosted EVÐA only through
+// `gate.open(...)` and then `session.send(...)`, and every path that is not a verified quote under a
+// pinned measurement ends in a refusal with nothing sent.
+//
+// The protocol, version 1. Over TLS to the host, on one connection:
+//   client -> host  POST /.well-known/evda-attestation  {"v":1,"nonce":"<base64, 32 bytes>"}
+//   host -> client  {"v":1,"platform":"tdx","quote":"<base64>","collateral":{tcbInfo,
+//                    tcbInfoIssuerChain,qeIdentity,qeIdentityIssuerChain},
+//                    "wrapKey":"<base64, 32 bytes, optional>"}
+// The VM puts reportDataFor(nonce, its TLS public key) in the quote's REPORTDATA. The client takes the
+// TLS key from the connection it is holding, never from the response body, so a host cannot name a key
+// other than the one it is actually serving with. Delivery then goes over a connection pinned to that
+// key (SHA-256 of its SPKI DER); a connection presenting any other key is refused before anything is
+// written to it.
+//
+// A host that will receive circle keys also names `wrapKey`, the X25519 public key it made inside the
+// VM, and binds it into REPORTDATA beside the nonce and TLS key (reportDataFor's second form). The
+// client has to take that key from the body, so the binding is what makes it trustworthy: a key the
+// quote does not bind is refused as NOT_BOUND. lib/attested-wrap.mjs wraps circle keys to it.
+//
+// The pinned measurement is the client's own configuration, never something a host supplies. With no
+// pinned measurement the gate refuses: an unconfigured client is not a client that trusts everyone.
+//
+// Not here yet: tying the pinned measurement to EVÐA's Sigstore log (lib/measurement-log.mjs checks a
+// logged digest; the statement that carries MRTD and RTMRs is a later slice), SEV-SNP, and the Swift
+// port of this gate in iris-mobile, which follows this file and its test vectors.
+
+import { createHash, createPublicKey, KeyObject, timingSafeEqual, X509Certificate } from "node:crypto";
+import { request as httpsRequest } from "node:https";
+import { createNonceBook, MEASUREMENT_NAMES, TDX_TRUST, verifyTdxAttestation, parseTdxQuote } from "./tdx-attestation.mjs";
+
+/** Where a hosted EVÐA answers the attestation challenge. */
+export const ATTESTATION_PATH = "/.well-known/evda-attestation";
+
+/** The protocol version this client speaks. A response naming another version is refused. */
+export const ATTESTATION_PROTOCOL_VERSION = 1;
+
+/** Why the gate refused, as a stable code. `message` carries the same thing for a person. */
+export const REFUSAL = Object.freeze({
+  NO_POLICY: "no-policy",
+  UNREACHABLE: "unreachable",
+  NO_QUOTE: "no-quote",
+  UNREADABLE_QUOTE: "unreadable-quote",
+  WRONG_MEASUREMENT: "wrong-measurement",
+  NOT_FRESH: "not-fresh",
+  NOT_BOUND: "not-bound",
+  NOT_PROVEN: "not-proven",
+  WRONG_CONNECTION: "wrong-connection",
+  NOT_DELIVERED: "not-delivered",
+  NO_WRAP_KEY: "no-wrap-key",
+  NOTHING_TO_WRAP: "nothing-to-wrap",
+});
+
+// What a person reads. Each says that nothing was sent and why, in words that need no TDX.
+const SAID = {
+  [REFUSAL.NO_POLICY]: "this app has no published EVÐA code to compare the server against, so it cannot tell whether the server is safe",
+  [REFUSAL.UNREACHABLE]: "the server could not be reached to ask it for proof",
+  [REFUSAL.NO_QUOTE]: "the server did not send any proof of what code it is running",
+  [REFUSAL.UNREADABLE_QUOTE]: "the server's proof could not be read",
+  [REFUSAL.WRONG_MEASUREMENT]: "the server is not running the code EVÐA publishes",
+  [REFUSAL.NOT_FRESH]: "the server's proof answered a request this phone did not just make, so it could be an old proof played back",
+  [REFUSAL.NOT_BOUND]: "the server's proof was not made for this request on this connection, so it could be an old proof played back or someone in the middle",
+  [REFUSAL.NOT_PROVEN]: "the server could not prove it is a locked, up to date part of the chip",
+  [REFUSAL.WRONG_CONNECTION]: "the connection is not the one the server proved, so someone else could be in the middle",
+  [REFUSAL.NOT_DELIVERED]: "the server was proven, and sending to it then failed",
+  [REFUSAL.NO_WRAP_KEY]: "the server did not prove it made a key of its own to receive your keys",
+  [REFUSAL.NOTHING_TO_WRAP]: "no keys were named to send",
+};
+
+const sha256Hex = (b) => createHash("sha256").update(b).digest("hex");
+
+/** A refusal: nothing was sent. `reason` is the detail for a log, `message` the sentence for a person. */
+export function refuse(code, reason) {
+  return { ok: false, sent: false, code, reason, message: `Nothing was sent: ${SAID[code]}.` };
+}
+
+const spkiDer = (key) => {
+  if (Buffer.isBuffer(key) || key instanceof Uint8Array) return createPublicKey({ key: Buffer.from(key), format: "der", type: "spki" }).export({ type: "spki", format: "der" });
+  if (key instanceof KeyObject && key.type === "public") return key.export({ type: "spki", format: "der" });
+  return createPublicKey(key).export({ type: "spki", format: "der" });
+};
+
+/** The pin for a TLS public key: SHA-256 of its SPKI DER, lowercase hex. The same value the verifier returns. */
+export function tlsKeyPin(tlsPublicKey) {
+  return sha256Hex(spkiDer(tlsPublicKey));
+}
+
+/** Whether `tlsPublicKey` is the key `pin` names. False for anything unreadable. */
+export function pinMatches(pin, tlsPublicKey) {
+  try {
+    const have = Buffer.from(tlsKeyPin(tlsPublicKey), "hex");
+    const want = Buffer.from(String(pin ?? ""), "hex");
+    return want.length === 32 && timingSafeEqual(have, want);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Why `policy` cannot gate anything, in words, or null when it can.
+ * policy: { platform: "tdx", measurements: { mrtd, rtmr0, rtmr1, rtmr2, rtmr3 }, minTcb: { tcbEvaluationDataNumber, statuses? } }
+ */
+export function hostPolicyProblem(policy) {
+  if (!policy) return "no pinned measurement is configured";
+  if (policy.platform !== "tdx") return `platform ${JSON.stringify(policy.platform ?? null)} is not one this client verifies (only tdx)`;
+  const m = policy.measurements;
+  const missing = MEASUREMENT_NAMES.filter((n) => !/^[0-9a-f]{96}$/.test(m?.[n] ?? ""));
+  if (missing.length) return `the pinned measurement does not name ${missing.join(", ")} as 96 lowercase hex characters each`;
+  if (!Number.isSafeInteger(policy.minTcb?.tcbEvaluationDataNumber)) return "the policy names no minimum TCB evaluation number";
+  return null;
+}
+
+/** The JSON body a client sends to ATTESTATION_PATH for `nonce` (32 bytes). */
+export function attestationRequest(nonce) {
+  const n = Buffer.from(nonce);
+  if (n.length !== 32) throw new Error("the nonce must be 32 bytes");
+  return { v: ATTESTATION_PROTOCOL_VERSION, nonce: n.toString("base64") };
+}
+
+/** Reads a host's answer. Returns { quote, collateral } or { error } in words; never throws. */
+export function parseAttestationResponse(body) {
+  let r = body;
+  if (typeof r === "string" || Buffer.isBuffer(r) || r instanceof Uint8Array) {
+    try { r = JSON.parse(Buffer.from(r).toString("utf8")); } catch { return { error: "the response is not JSON" }; }
+  }
+  if (!r || typeof r !== "object") return { error: "the response is empty" };
+  if (r.v !== ATTESTATION_PROTOCOL_VERSION) return { error: `the response speaks protocol ${JSON.stringify(r.v ?? null)}, not ${ATTESTATION_PROTOCOL_VERSION}` };
+  if (r.platform !== "tdx") return { error: `the response is for platform ${JSON.stringify(r.platform ?? null)}, not tdx` };
+  if (typeof r.quote !== "string" || r.quote.length === 0) return { error: "the response carries no quote", missing: true };
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(r.quote)) return { error: "the quote is not base64" };
+  let wrapKey = null;
+  if (r.wrapKey != null) {
+    if (typeof r.wrapKey !== "string" || !/^[A-Za-z0-9+/]+={0,2}$/.test(r.wrapKey)) return { error: "the wrap key is not base64" };
+    wrapKey = Buffer.from(r.wrapKey, "base64");
+    if (wrapKey.length !== 32) return { error: `the wrap key is ${wrapKey.length} bytes, not 32` };
+  }
+  return { quote: Buffer.from(r.quote, "base64"), collateral: r.collateral ?? null, wrapKey };
+}
+
+// The verifier's reasons, sorted into what a person needs to know. The tests hold one case per code,
+// so a reworded reason in tdx-attestation.mjs that stops matching fails there, not silently here.
+function classify(reason) {
+  if (/^(MRTD|RTMR\d) is /.test(reason)) return REFUSAL.WRONG_MEASUREMENT;
+  if (/^REPORTDATA /.test(reason)) return REFUSAL.NOT_BOUND;
+  if (/nonce/.test(reason)) return REFUSAL.NOT_FRESH;
+  if (/could not be read|truncated|too short|shorter than|not understood/.test(reason)) return REFUSAL.UNREADABLE_QUOTE;
+  return REFUSAL.NOT_PROVEN;
+}
+
+/**
+ * The gate. `policy` is the client's pinned measurement (see hostPolicyProblem); `clock` returns the
+ * time certificates, collateral and the nonce are judged at.
+ *
+ * gate.open({ challenge }) asks the host to prove itself. `challenge(requestBody)` is the transport: it
+ * POSTs the body to ATTESTATION_PATH and resolves { body, tlsPublicKey }, the host's answer and the TLS
+ * public key of the connection that answer came over. It resolves to an attested session, or a refusal.
+ *
+ * session.send(payload, { deliver }) hands `payload` to `deliver(payload, { pin })` once. `deliver` must
+ * send only over a connection whose TLS key matches `pin` (httpsHostTransport does this for Node) and
+ * resolve { tlsPublicKey, result } naming the key it actually used; a key other than the attested one is
+ * reported, and a transport that refuses the wrong key throws an error with code EVDA_PIN_MISMATCH. `payload` may be a function, called only after the host is proven, so key
+ * material can be produced only for a host that passed.
+ */
+export function createAttestedHostGate({ policy, nonces = createNonceBook(), clock = () => Date.now(), trust = TDX_TRUST } = {}) {
+  return {
+    async open({ challenge } = {}) {
+      const problem = hostPolicyProblem(policy);
+      if (problem) return refuse(REFUSAL.NO_POLICY, problem);
+      if (typeof challenge !== "function") return refuse(REFUSAL.UNREACHABLE, "no transport was given to reach the host");
+
+      const nonce = nonces.issue(clock());
+      let answer;
+      try {
+        answer = await challenge(attestationRequest(nonce));
+      } catch (err) {
+        return refuse(REFUSAL.UNREACHABLE, `the attestation request failed: ${err?.message ?? err}`);
+      }
+      const parsed = parseAttestationResponse(answer?.body);
+      if (parsed.error) return refuse(parsed.missing || answer?.body == null ? REFUSAL.NO_QUOTE : REFUSAL.UNREADABLE_QUOTE, parsed.error);
+      try {
+        parseTdxQuote(parsed.quote);
+      } catch (err) {
+        return refuse(REFUSAL.UNREADABLE_QUOTE, `the quote could not be read: ${err.message}`);
+      }
+      if (!answer.tlsPublicKey) return refuse(REFUSAL.WRONG_CONNECTION, "the transport did not report the TLS key of the connection the quote came over");
+
+      const v = verifyTdxAttestation({
+        quote: parsed.quote, nonce, nonces, tlsPublicKey: answer.tlsPublicKey, wrapPublicKey: parsed.wrapKey ?? undefined,
+        expected: policy.measurements, minTcb: policy.minTcb, collateral: parsed.collateral, now: clock(), trust,
+      });
+      if (!v.ok) return refuse(classify(v.reason), v.reason);
+      return session({ pin: v.tlsPublicKeySha256, measurements: v.measurements, tcb: v.tcb, wrapKey: v.wrapPublicKey ?? null });
+    },
+  };
+}
+
+function session({ pin, measurements, tcb, wrapKey }) {
+  return {
+    ok: true,
+    pin,
+    measurements,
+    tcb,
+    // The VM's key-wrapping key, only when the quote bound it; null when the host named none.
+    wrapKey,
+    async send(payload, { deliver } = {}) {
+      if (typeof deliver !== "function") return refuse(REFUSAL.NOT_DELIVERED, "no delivery transport was given");
+      let bytes;
+      try {
+        bytes = typeof payload === "function" ? await payload({ pin, measurements, wrapKey }) : payload;
+      } catch (err) {
+        return refuse(REFUSAL.NOT_DELIVERED, `the payload could not be prepared: ${err?.message ?? err}`);
+      }
+      let out;
+      try {
+        out = await deliver(bytes, { pin });
+      } catch (err) {
+        if (err?.code === "EVDA_PIN_MISMATCH") return refuse(REFUSAL.WRONG_CONNECTION, err.message);
+        return refuse(REFUSAL.NOT_DELIVERED, `delivery failed: ${err?.message ?? err}`);
+      }
+      // A transport that pins as it must never reaches this; one that does not has already sent, and says so.
+      if (!pinMatches(pin, out?.tlsPublicKey)) return { ok: false, sent: true, code: REFUSAL.WRONG_CONNECTION, reason: "the delivery went over a TLS key other than the attested one", message: `Sent over the wrong connection: ${SAID[REFUSAL.WRONG_CONNECTION]}. Treat what was sent as exposed.` };
+      return { ok: true, sent: true, pin, result: out.result };
+    },
+  };
+}
+
+// ─── the Node transport (the Mac client; the phone's is Swift) ──────────────────────────────────
+
+const keyOfCert = (cert) => (cert?.raw ? new X509Certificate(cert.raw).publicKey : null);
+
+function postJson(url, body, { pin } = {}) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(url);
+    if (u.protocol !== "https:") return reject(new Error(`${u.origin} is not https`));
+    const data = Buffer.from(JSON.stringify(body));
+    const req = httpsRequest(u, { method: "POST", rejectUnauthorized: false, agent: false, headers: { "content-type": "application/json", "content-length": data.length } }, (res) => {
+      const chunks = [];
+      res.on("data", (c) => chunks.push(c));
+      res.on("end", () => resolve({ status: res.statusCode, body: Buffer.concat(chunks), tlsPublicKey }));
+      res.on("error", reject);
+    });
+    let tlsPublicKey = null;
+    req.on("error", reject);
+    // Nothing is written until the handshake is done and the key is read, so a pinned request to the
+    // wrong key leaves with no header and no body.
+    req.on("socket", (socket) => {
+      socket.once("secureConnect", () => {
+        try { tlsPublicKey = keyOfCert(socket.getPeerCertificate(true)); } catch { tlsPublicKey = null; }
+        if (pin !== undefined && !pinMatches(pin, tlsPublicKey)) {
+          const err = Object.assign(new Error("the server's TLS key is not the attested one"), { code: "EVDA_PIN_MISMATCH" });
+          req.destroy(err);
+          return;
+        }
+        req.end(data);
+      });
+    });
+  });
+}
+
+/**
+ * The Node transport for one hosted EVÐA at `origin` (https). challenge() for gate.open, and
+ * deliver(path) for session.send, which posts the payload (JSON-serializable) over a connection pinned
+ * to the attested key: a server presenting any other key is dropped after the handshake, before any
+ * header or body is written. The VM's certificate is self-signed inside the VM, so the CA check is
+ * replaced by the attestation and the pin, not by nothing.
+ */
+export function httpsHostTransport(origin) {
+  return {
+    async challenge(requestBody) {
+      const r = await postJson(new URL(ATTESTATION_PATH, origin), requestBody);
+      if (r.status !== 200) throw new Error(`the host answered ${r.status}`);
+      return { body: r.body, tlsPublicKey: r.tlsPublicKey };
+    },
+    deliver(path) {
+      return async (payload, { pin }) => {
+        if (!pin) throw new Error("no pin was given, so delivery cannot be bound to the attested key");
+        const r = await postJson(new URL(path, origin), payload, { pin });
+        if (r.status < 200 || r.status >= 300) throw new Error(`the host answered ${r.status}`);
+        return { tlsPublicKey: r.tlsPublicKey, result: r.body };
+      };
+    },
+  };
+}

package/lib/attested-wrap.mjs

@@ -0,0 +1,147 @@
+// Circle keys go to a hosted EVÐA only sealed to a key born inside the attested VM. (HQ-2083, Spec 08
+// section 8: the VM holds a person's circle keys and EVÐA's operators cannot read them.)
+//
+// The VM side, createEnclaveKey(): the VM makes an X25519 key pair when it starts, keeps the private
+// half in this closure (inside TDX-encrypted memory on a c3 VM), and puts the public half into every
+// quote's REPORTDATA beside the nonce and TLS key (tdx-attestation.mjs reportDataFor, second form). It
+// names the public half as `wrapKey` in its attestation answer (lib/attested-host.mjs).
+//
+// The client side, wrapCircleKeysTo(session, ...): `session` is what gate.open returned. Only a session
+// whose quote verified under the pinned measurement AND bound the wrap key gets anything; the client's
+// key holder is not asked to seal a single circle key before that. The holder is the HostCrypto shape
+// every EVÐA device already has (`sealCircleKeyTo(circleId, epoch, publicKey)`, contracts/src/host.ts),
+// so the raw scalar never passes through this file on a real device.
+//
+// The envelope is the circle key delivery wire (xania/seal/v1, the same bytes `sealCircleKeyTo` makes
+// and `importCircleKey` opens, pinned by ekati's circle-seal vectors):
+//   [version 0x01][ephemeral X25519 public:32][ChaCha20-Poly1305 ciphertext][tag:16]
+//   key||nonce = HKDF-SHA256(ECDH, salt empty, info "xania/seal/v1" || ephemeral public || recipient public, 44)
+//   AAD = the 33-byte header.
+// sealToKey and openSealed are the dependency-free copies person-record and the VM use; the test opens
+// the frozen vectors with them, so a drift from the wire fails there.
+//
+// The payload the client delivers, version 1:
+//   { "v": 1, "wrapKey": "<base64>", "keys": [{ "circleId", "epoch", "sealedKey": "<base64>" }] }
+//
+// Not here yet: the Swift port of the client side in iris-mobile, the VM's server that holds what it
+// unwrapped, and a signed key-delivery string (the relay path signs deliveries because a relay could
+// plant a key; here the gate's pinned TLS key carries the payload, so the host is already the proven VM).
+
+import { createCipheriv, createDecipheriv, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync } from "node:crypto";
+import { REFUSAL, refuse } from "./attested-host.mjs";
+import { reportDataFor } from "./tdx-attestation.mjs";
+
+/** The length of a key-wrapping public key: raw X25519. */
+export const WRAP_KEY_BYTES = 32;
+
+/** The version of the wrapped-keys payload. */
+export const WRAPPED_KEYS_VERSION = 1;
+
+const SEAL_VERSION = 1;
+const SEAL_KDF_DOMAIN = Buffer.from("xania/seal/v1", "utf8");
+const X25519_SPKI_PREFIX = Buffer.from("302a300506032b656e032100", "hex");
+
+const rawPublic = (keyObject) => keyObject.export({ type: "spki", format: "der" }).subarray(-32);
+const x25519Public = (raw) => {
+  const b = Buffer.from(raw);
+  if (b.length !== WRAP_KEY_BYTES) throw new Error(`an X25519 public key is 32 bytes, not ${b.length}`);
+  return createPublicKey({ key: Buffer.concat([X25519_SPKI_PREFIX, b]), format: "der", type: "spki" });
+};
+
+function sealDerive(shared, ephemeralPublic, recipientPublic) {
+  const okm = Buffer.from(hkdfSync("sha256", shared, Buffer.alloc(0), Buffer.concat([SEAL_KDF_DOMAIN, ephemeralPublic, recipientPublic]), 44));
+  return { key: okm.subarray(0, 32), nonce: okm.subarray(32, 44) };
+}
+
+/** Seals `plaintext` to the raw X25519 `recipientPublicKey`, with a fresh ephemeral key per call. */
+export function sealToKey(recipientPublicKey, plaintext) {
+  const recipient = Buffer.from(recipientPublicKey);
+  const ephemeral = generateKeyPairSync("x25519");
+  const ephemeralPublic = rawPublic(ephemeral.publicKey);
+  const shared = diffieHellman({ privateKey: ephemeral.privateKey, publicKey: x25519Public(recipient) });
+  const header = Buffer.concat([Buffer.from([SEAL_VERSION]), ephemeralPublic]);
+  const { key, nonce } = sealDerive(shared, ephemeralPublic, recipient);
+  const cipher = createCipheriv("chacha20-poly1305", key, nonce, { authTagLength: 16 });
+  cipher.setAAD(header, { plaintextLength: plaintext.length });
+  const body = Buffer.concat([cipher.update(Buffer.from(plaintext)), cipher.final()]);
+  return Buffer.concat([header, body, cipher.getAuthTag()]);
+}
+
+/** Opens an envelope with the X25519 private KeyObject it was sealed to. Throws when it does not open. */
+export function openSealed(privateKey, envelope) {
+  const buf = Buffer.from(envelope);
+  if (buf.length < 1 + 32 + 16) throw new Error(`the envelope is ${buf.length} bytes, too short to be one`);
+  if (buf[0] !== SEAL_VERSION) throw new Error(`unknown envelope version ${buf[0]}`);
+  const header = buf.subarray(0, 33);
+  const ephemeralPublic = buf.subarray(1, 33);
+  const ciphertext = buf.subarray(33, buf.length - 16);
+  const shared = diffieHellman({ privateKey, publicKey: x25519Public(ephemeralPublic) });
+  const { key, nonce } = sealDerive(shared, ephemeralPublic, rawPublic(createPublicKey(privateKey)));
+  const decipher = createDecipheriv("chacha20-poly1305", key, nonce, { authTagLength: 16 });
+  decipher.setAAD(header, { plaintextLength: ciphertext.length });
+  decipher.setAuthTag(buf.subarray(buf.length - 16));
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+
+// ─── the VM ──────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The VM's key-wrapping key, made inside the VM. Returns a frozen object holding the public half and two
+ * functions; the private half is reachable only through them.
+ *   reportDataFor(nonce, tlsPublicKey): the REPORTDATA the VM asks the TDX module to sign.
+ *   unwrapAll(payload): opens a wrapped-keys payload addressed to this key. Throws when the payload
+ *     names another key or any envelope does not open. Returns [{ circleId, epoch, scalar }].
+ */
+export function createEnclaveKey() {
+  const pair = generateKeyPairSync("x25519");
+  const publicKey = rawPublic(pair.publicKey);
+  return Object.freeze({
+    publicKey,
+    reportDataFor: (nonce, tlsPublicKey) => reportDataFor(nonce, tlsPublicKey, publicKey),
+    unwrapAll(payload) {
+      if (payload?.v !== WRAPPED_KEYS_VERSION) throw new Error(`the payload speaks version ${JSON.stringify(payload?.v ?? null)}, not ${WRAPPED_KEYS_VERSION}`);
+      if (!Buffer.from(String(payload.wrapKey ?? ""), "base64").equals(publicKey)) throw new Error("the payload was wrapped to another key");
+      if (!Array.isArray(payload.keys)) throw new Error("the payload carries no keys");
+      return payload.keys.map((k) => {
+        const scalar = openSealed(pair.privateKey, Buffer.from(String(k.sealedKey ?? ""), "base64"));
+        if (scalar.length !== 32) throw new Error("a circle key is 32 bytes");
+        return { circleId: k.circleId, epoch: k.epoch, scalar };
+      });
+    },
+  });
+}
+
+// ─── the client ──────────────────────────────────────────────────────────────────────────────────
+
+function circlesProblem(circles) {
+  if (!Array.isArray(circles) || circles.length === 0) return "no circle keys were named";
+  for (const c of circles) {
+    if (typeof c?.circleId !== "string" || c.circleId.length === 0) return "a circle key was named without its circle";
+    if (!Number.isInteger(c.epoch) || c.epoch < 1) return `circle ${c.circleId} was named with epoch ${JSON.stringify(c.epoch ?? null)}, not a whole number from 1`;
+  }
+  return null;
+}
+
+/**
+ * Wraps the named circle keys to the attested VM's own key and delivers them once over the attested
+ * connection. `session` is gate.open's result; `crypto` has `sealCircleKeyTo(circleId, epoch, publicKey)`;
+ * `circles` is [{ circleId, epoch }]; `deliver` is the transport session.send takes.
+ * Returns session.send's result, or a refusal with nothing sealed and nothing sent.
+ */
+export async function wrapCircleKeysTo(session, { crypto, circles, deliver } = {}) {
+  if (!session?.ok) return session?.code ? session : refuse(REFUSAL.NOT_PROVEN, "no attested session was given");
+  const wrapKey = session.wrapKey;
+  if (!wrapKey) return refuse(REFUSAL.NO_WRAP_KEY, "the host's quote bound no key-wrapping key");
+  if (Buffer.from(wrapKey).length !== WRAP_KEY_BYTES) return refuse(REFUSAL.NO_WRAP_KEY, "the session's wrap key is not 32 bytes");
+  const problem = circlesProblem(circles);
+  if (problem) return refuse(REFUSAL.NOTHING_TO_WRAP, problem);
+  if (typeof crypto?.sealCircleKeyTo !== "function") return refuse(REFUSAL.NOTHING_TO_WRAP, "no key holder was given to seal the circle keys");
+  return session.send(async ({ wrapKey: bound }) => {
+    const keys = [];
+    for (const { circleId, epoch } of circles) {
+      const sealed = await crypto.sealCircleKeyTo(circleId, epoch, new Uint8Array(bound));
+      keys.push({ circleId, epoch, sealedKey: Buffer.from(sealed).toString("base64") });
+    }
+    return { v: WRAPPED_KEYS_VERSION, wrapKey: Buffer.from(bound).toString("base64"), keys };
+  }, { deliver });
+}

package/lib/checkout-freshness.mjs

@@ -0,0 +1,88 @@
+// Is the doctor that is about to give a verdict the doctor on origin/main? (HQ-2736)
+//
+// On 2026-10-19 a session checked a vault change with `evda doctor` from a checkout sitting on a
+// branch merged two weeks earlier, read exit 0, and the change broke every evda PR's Argus
+// baseline, because the doctor on origin/main refused what the stale one passed. The verdict was
+// true of the code that ran; nothing said that code was not main's.
+//
+// So the doctor says, before its verdict, when its own checkout is behind origin/main or not on
+// main. It says nothing on current main. It never changes the exit code: the exit is the record's
+// verdict, and Argus runs the doctor from PR branches, where "not on main" is the expected state.
+//
+// The comparison target is origin/main after one bounded `git fetch` (FETCH_TIMEOUT_MS, no
+// prompts, ssh in batch mode), because the local ref alone goes stale with the checkout: a
+// checkout nobody fetched in two weeks would compare equal to its own two-week-old origin/main
+// and read as current, which is the same false clean. A fetch only moves remote-tracking refs,
+// never the working tree. EVDA_DOCTOR_FETCH=0 skips it and compares against the ref as last
+// fetched, and says so. A failed fetch, no origin remote, or no git at all still lets every check
+// run; the doctor then says it could not compare, and why.
+
+import { spawnSync } from "node:child_process";
+
+export const FETCH_TIMEOUT_MS = 5000;
+const GIT_TIMEOUT_MS = 3000;
+
+function git(root, args, timeout = GIT_TIMEOUT_MS, env = process.env) {
+  const r = spawnSync("git", ["-C", root, ...args], { encoding: "utf8", timeout, env, stdio: ["ignore", "pipe", "pipe"] });
+  if (r.error) return { ok: false, out: "", err: r.error.code === "ETIMEDOUT" ? `timed out after ${timeout}ms` : String(r.error.message) };
+  // git's reason is its first `fatal:` line; the lines after it are advice ("and the repository exists.").
+  const errLines = (r.stderr ?? "").trim().split("\n").filter(Boolean);
+  const err = (errLines.find((l) => l.startsWith("fatal:")) ?? errLines[0] ?? "").replace(/^fatal:\s*/, "");
+  return { ok: r.status === 0, out: (r.stdout ?? "").trim(), err };
+}
+
+const short = (sha) => sha.slice(0, 7);
+
+// Returns { state, lines }. `lines` is what the doctor prints; it is empty exactly when the
+// checkout is main at origin/main as of a fetch that just succeeded.
+// state: "current" | "behind" | "off-main" | "not-compared" | "not-a-checkout"
+export function checkoutFreshness(root, { fetch = process.env.EVDA_DOCTOR_FETCH !== "0", fetchTimeoutMs = FETCH_TIMEOUT_MS } = {}) {
+  const top = git(root, ["rev-parse", "--show-toplevel"]);
+  if (!top.ok) {
+    return { state: "not-a-checkout", lines: [`could not compare this doctor against origin/main: ${root} is not a git checkout (an installed or copied doctor). Its verdict is this copy's.`] };
+  }
+  const head = git(root, ["rev-parse", "HEAD"]);
+  if (!head.ok) return { state: "not-compared", lines: [`could not compare this doctor against origin/main: the checkout has no commit (${head.err}).`] };
+  const branch = git(root, ["symbolic-ref", "--short", "-q", "HEAD"]).out || null;
+  const where = branch ? `branch ${branch}` : "a detached HEAD";
+
+  if (!git(root, ["remote", "get-url", "origin"]).ok) {
+    return { state: "not-compared", lines: [`could not compare this doctor against origin/main: the checkout has no origin remote. It runs from ${where} at ${short(head.out)}.`] };
+  }
+
+  let fetchNote = null;
+  if (fetch) {
+    const env = { ...process.env, GIT_TERMINAL_PROMPT: "0" };
+    if (!env.GIT_SSH_COMMAND) env.GIT_SSH_COMMAND = "ssh -o BatchMode=yes -o ConnectTimeout=3";
+    const f = git(root, ["fetch", "--quiet", "--no-tags", "origin", "main"], fetchTimeoutMs, env);
+    if (!f.ok) fetchNote = `git fetch failed (${f.err || "no reason given"})`;
+  } else {
+    fetchNote = "fetch skipped (EVDA_DOCTOR_FETCH=0)";
+  }
+
+  const ref = git(root, ["rev-parse", "--verify", "-q", "refs/remotes/origin/main"]);
+  if (!ref.ok) {
+    return { state: "not-compared", lines: [`could not compare this doctor against origin/main: ${fetchNote ?? "the fetch succeeded"} and there is no origin/main ref. It runs from ${where} at ${short(head.out)}.`] };
+  }
+  const behind = Number(git(root, ["rev-list", "--count", `HEAD..${ref.out}`]).out || 0);
+  const ahead = Number(git(root, ["rev-list", "--count", `${ref.out}..HEAD`]).out || 0);
+  const onMain = branch === "main";
+  const against = fetchNote ? `origin/main as last fetched (${short(ref.out)}; ${fetchNote}, so main may be further ahead)` : `origin/main ${short(ref.out)}`;
+
+  const lines = [];
+  let state;
+  if (behind > 0) {
+    state = "behind";
+    lines.push(`this doctor runs from ${where} at ${short(head.out)}, ${behind} commit(s) behind ${against}. Its verdict can differ from main's; rerun from an up-to-date main before trusting it.`);
+  } else if (!onMain) {
+    state = "off-main";
+    lines.push(`this doctor runs from ${where} at ${short(head.out)}, not main (${ahead} commit(s) ahead of ${against}). Its verdict is this branch's, which main may not share.`);
+  } else {
+    state = "current";
+  }
+  if (fetchNote && state === "current") {
+    state = "not-compared";
+    lines.push(`could not compare this doctor against current origin/main: ${fetchNote}. It matches ${against.replace(/ \(.*$/, "")} at ${short(ref.out)}.`);
+  }
+  return { state, lines };
+}

package/lib/circles.mjs

@@ -74,6 +74,7 @@ import { resolveRole } from "./roles.mjs";
 import { boundaries, insideAny } from "./records.mjs";
 import { parseYaml, toYaml } from "./yaml.mjs";
 import { EvdaError } from "./errors.mjs";
+import { outsideRecord } from "./record-walk.mjs";
 
 export const ECO_SCHEMA_VERSION = "0.1";
 // atlas-arch:yaml-encoding: the eco manifest is a config file the substrate names by its suffix, not an entity key
@@ -544,13 +545,14 @@ export function frontmatterOf(text) {
   }
 }
 
-// Every markdown file under the record root, skipping dot-directories and node_modules. The mark
+// Every markdown file under the record root, skipping dot-directories and what outsideRecord names
+// (node_modules, any *.nosync). The mark
 // walk reads the whole record, not only the record roles: a released fact may live anywhere.
 export function markdownFiles(root) {
   const out = [];
   const walk = (abs) => {
     for (const name of readdirSync(abs).sort()) {
-      if (name.startsWith(".") || name === "node_modules") continue;
+      if (name.startsWith(".") || outsideRecord(name)) continue;
       const p = join(abs, name);
       // A dangling symlink (target lives only on another machine, e.g. raw media kept
       // outside the synced vault) has nothing to stat. It is not markdown content either

package/lib/clients.mjs

@@ -40,6 +40,17 @@ export function clientsFor(command, args, { desktopConfig = null, filing = null
       text: JSON.stringify({ mcpServers: { [SERVER_NAME]: { command, args } } }, null, 2),
       file: desktopConfig ?? "claude_desktop_config.json",
     },
+    {
+      // Cowork starts no server from claude_desktop_config.json and reads no folder's hooks; a plugin
+      // is the one way in (HQ-2802, lib/plugin.mjs). The same command as the server, with plugin for mcp.
+      key: "cowork",
+      label: "Claude Cowork",
+      steps: [
+        "Cowork does not use the desktop config above. Run this once to build a plugin for this record, then in the Claude app open Customize, then Plugins, then Add, then Upload plugin, and choose the zip it names.",
+      ],
+      text: [command, ...args.map((a, i) => (i === args.length - 2 && a === "mcp" ? "plugin" : a))].map(shellQuote).join(" "),
+      file: null,
+    },
     {
       key: "project",
       label: "One folder only (.mcp.json)",

package/lib/connect.mjs

@@ -82,7 +82,7 @@ export function guardStatus(recordDir) {
 
 // A `node` on PATH that is this same binary, when there is one: Homebrew's /opt/homebrew/bin/node
 // survives an upgrade, and the versioned Cellar path process.execPath reports does not.
-function stableNode(execPath, env) {
+export function stableNode(execPath = process.execPath, env = process.env) {
   let target;
   try { target = realpathSync(execPath); } catch { return execPath; }
   for (const d of String(env.PATH ?? "").split(delimiter)) {

package/lib/connecting-apps.mjs

@@ -0,0 +1,56 @@
+// Which app is connecting, from initialize's clientInfo.name (HQ-2218). One table names each app once,
+// and both uses read it: clientProfile in lib/mcp.mjs (which sections, how large a part) by the exact
+// names in `names`, and chatAppOf in lib/every-chat.mjs (which every-chat setup words) by `like`.
+// Before this the two were separate tables (HQ-2207, HQ-2205) that agreed only by care.
+// No node: imports, because lib/every-chat.mjs reads this file and lib/clients.mjs, rendered in the
+// EVDA app's webview, reads that one.
+//
+// names: the exact clientInfo.name values, compared trimmed and case-insensitively. claude-code and
+// codex-mcp-client measured 2026-10-05 (a probe server logging clientInfo, driven by `claude -p` and
+// `codex exec`). claude.ai sends Anthropic/ClaudeAI, measured 2026-10-05 in the remote server's log
+// from a fresh web chat; claude-ai stays as the published form. openai-mcp is the name ChatGPT
+// publishes and is unmeasured until Hestia's evda-mcp log holds one (it held none on 2026-10-15).
+//
+// like: a pattern for names nobody has measured yet, read top to bottom, first match wins. Every
+// coding agent comes before the chat apps, because its every-session file is AGENTS.md or
+// CLAUDE.md, which create-evda already writes into the record, so it gets no every-chat words
+// (chat: null). A name no row matches is "other", asked with GENERIC_WHERE, so a new app still gets
+// the line.
+//
+// surface, max, budget: what clientProfile serves an app it knows by name. max null is the smallest
+// documented cap, LAYER_PART_MAX in lib/mcp.mjs; budget null is CHAT_LAYER_BUDGET there.
+// Limits: claude.ai and the desktop app take a tool result of about 150,000 characters
+// (claude.com/docs/connectors/building, "Design within the size and timeout limits"); Claude Code
+// 25,000 tokens (same page, MAX_MCP_OUTPUT_TOKENS); OpenAI publishes no figure for ChatGPT and
+// truncates an over-budget result at a line, so ChatGPT and every unknown app get the smallest
+// cap. Codex documents none either and gets the same.
+// claude.ai's budget is its own (HQ-2327): his chat layer measured 2026-10-07 at about 90,000
+// characters whole (head 5,000, core 28,717, owner sections 56,041), and at the shared 70,000 his
+// "Proactive Context Loading" (20,238, the Deep Work Queue, Weekends & Trips and friction rules)
+// reached claude.ai as one listed heading, fetched 0 times in 21 layer loads. 100,000 serves it
+// whole and leaves 40,000 of the 140,000 cap for what the first call adds after the layer
+// (openChat: replies, recent days, people).
+export const CLAUDE_AI_LAYER_BUDGET = 100_000;
+
+export const CONNECTING_APPS = [
+  { app: "Claude Code", names: ["claude-code"], like: /claude[-_ ]?code/i, chat: null, surface: "terminal", max: null, budget: null },
+  { app: "Codex", names: ["codex-mcp-client"], like: /codex/i, chat: null, surface: "terminal", max: null, budget: null },
+  // Coding agents nobody has measured. No exact name, so clientProfile treats them as unknown apps.
+  { app: "another coding agent", names: [], like: /cursor|copilot|vscode|windsurf|zed|opencode|cline|aider|gemini[-_ ]?cli|goose|mcp-inspector|inspector/i, chat: null, surface: null, max: null, budget: null },
+  { app: "claude.ai", names: ["claude-ai", "anthropic/claudeai"], like: /claude|anthropic/i, chat: "claude", surface: "chat", max: 140_000, budget: CLAUDE_AI_LAYER_BUDGET },
+  { app: "ChatGPT", names: ["openai-mcp"], like: /openai|chatgpt/i, chat: "chatgpt", surface: "chat", max: null, budget: null },
+];
+
+const clean = (name) => (typeof name === "string" ? name.trim() : "");
+
+// The row whose exact names include this one, or null.
+export function appNamed(name) {
+  const n = clean(name).toLowerCase();
+  return n ? CONNECTING_APPS.find((a) => a.names.includes(n)) ?? null : null;
+}
+
+// The first row whose pattern matches this name, or null.
+export function appLike(name) {
+  const n = String(name ?? "").trim();
+  return CONNECTING_APPS.find((a) => a.like.test(n)) ?? null;
+}