create-evda 0.1.8 → 0.1.10

package/lib/attested-host.mjs

@@ -0,0 +1,269 @@
+// 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}}
+// 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.
+//
+// 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",
+});
+
+// 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",
+};
+
+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. */
+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" };
+  return { quote: Buffer.from(r.quote, "base64"), collateral: r.collateral ?? null };
+}
+
+// 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,
+        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 });
+    },
+  };
+}
+
+function session({ pin, measurements, tcb }) {
+  return {
+    ok: true,
+    pin,
+    measurements,
+    tcb,
+    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 }) : 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/browse.mjs

@@ -0,0 +1,354 @@
+// The whole record as a folder tree, for the owner's own app (HQ-2038).
+//
+// The EVÐA Mac app shows every folder of the record, not only the record roles, one folder at a
+// time so a record of tens of thousands of files opens fast. Three rules decide what it lists, and
+// each is the rule another reader already uses, never a copy of it:
+//
+//   what the scan reads   sync-rules `scanSkip` with the plan's excludes and the sub-record
+//                         boundaries, the same predicate the shadow scan and doctor walk with, so
+//                         the app and the sync agree on what is in the record. Dot-named entries
+//                         (.obsidian, .claude) are left out of the view on top of that.
+//   which circle          circles `homesOf` through readers `readersFor`, the resolver doctor and
+//                         the MCP server use: a file shows the circle that homes it.
+//   what stays closed     `noted: true` and `sealed: true` entries (readers `isNotedFile`,
+//                         `isSealedFile`), and a part whose read_by says no AI reads it (`none`)
+//                         or does not parse: the app hosts the owner's AI connection, so it keeps
+//                         those closed as the phone keeps a noted entry closed.
+//
+// `openEntry` opens exactly what `browse` lists as text: it walks the same rules down the path, so
+// a path the listing would not show is refused however it is spelled.
+//
+// Listing never reads a file iCloud holds only in the cloud (a dataless file): reading it would
+// download it. Such a file is listed with `cloud: true` and its frontmatter unread; opening it reads
+// it, and a noted or sealed entry is refused then.
+
+import { lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { scanSkip, datalessAmong, isTextPath } from "./sync-rules.mjs";
+import { planBeside } from "./circle-plan.mjs";
+import { boundaries } from "./records.mjs";
+import { resolveRole } from "./roles.mjs";
+import { readContext, readersFor, isNotedFile, isSealedFile, aiView } from "./readers.mjs";
+import { EvdaError } from "./errors.mjs";
+import { FENCE_OPEN } from "./agents.mjs";
+import { write as writeToday, todayPath } from "./tools.mjs";
+
+// The default preset: the roles pinned above the tree, in this order, when the mapping gives each a
+// folder. The journal first. `work` is a live source (harlequin:), not a folder, so it is never pinned.
+export const DEFAULT_PINS = ["record/daily", "record/captures", "record/people", "collections", "collections/areas", "knowledge"];
+
+// The record roles keep the names the phone gives them; any other pin is named by its folder.
+const ROLE_TITLES = { "record/daily": "Journal", "record/captures": "Captures", "record/people": "People" };
+
+// The largest file the app opens as text. Bigger text is listed and stays closed.
+export const MAX_OPEN_BYTES = 4 * 1024 * 1024;
+
+const DATED = /^\d{4}-\d{2}-\d{2}/;
+
+// Tooling the view leaves out, by kind (HQ-2038, round 2): a package manifest or lockfile, a shell
+// script, a license, a backup copy, an empty file. It stays in the record and in the sync; the app
+// does not list or open it, and each folder says how many it left out. Dot-named entries are left
+// out the same way.
+const LOCKFILE = /(^package(-lock)?\.json$)|(-lock\.json$)|(^pnpm-lock\.yaml$)|(^yarn\.lock$)/i;
+export function isTooling(name, size) {
+  if (name.startsWith(".")) return true;
+  if (size === 0) return true;
+  if (LOCKFILE.test(name)) return true;
+  if (/\.(sh|zsh|bash)$/i.test(name)) return true;
+  if (/^(LICENSE|LICENCE|COPYING)(\.(md|txt))?$/i.test(name)) return true;
+  if (/\.bak($|[.-])|~$/i.test(name)) return true;
+  return false;
+}
+
+// The files that say how the record and its agent work: the manifest, the operating layer the
+// mapping names, the agent pointer files create-evda writes, and any root file carrying the
+// generated core fence (his IRIS.md). Only at the record's root. The app groups them under one
+// entry instead of mixing them with notes.
+const AGENT_FILES = ["evda.json", "AGENTS.md", "CLAUDE.md", "GEMINI.md"];
+function isOperating(bctx, name) {
+  if (AGENT_FILES.includes(name)) return true;
+  const agents = bctx.evda.manifest?.mapping?.agents;
+  if (typeof agents === "string" && agents.replace(/^\.\//, "") === name) return true;
+  if (!/\.md$/i.test(name)) return false;
+  if (datalessAmong(bctx.evda.dir, [name]).size) return false;
+  try {
+    return readFileSync(join(bctx.evda.dir, name), "utf8").includes(FENCE_OPEN);
+  } catch {
+    return false;
+  }
+}
+
+// "01_Projects" -> "Projects", "03_Resources/Wiki" -> "Wiki".
+export function folderTitle(rel) {
+  const last = rel.split("/").pop() ?? rel;
+  const t = last.replace(/^\d+[\s_.-]+/, "").replace(/[_-]+/g, " ").trim();
+  return t ? t[0].toUpperCase() + t.slice(1) : last;
+}
+
+// Everything one listing needs, read once: the scan's skip rule, the circles and the readers.
+export function browseContext(evda) {
+  let extra = [];
+  try { extra = planBeside(evda)?.plan?.exclude ?? []; } catch { extra = []; }
+  const skip = scanSkip([...extra, ...boundaries(evda)]);
+  return { evda, skip, readers: readContext(evda) };
+}
+
+// Why the app keeps a file closed, or null when it opens. `cloud` skips the frontmatter read.
+export function closedBecause(bctx, abs, { cloud = false } = {}) {
+  if (!cloud && isSealedFile(abs)) return "sealed";
+  if (!cloud && isNotedFile(abs)) return "noted";
+  const r = readersFor(bctx.readers, abs);
+  if (r.broken) return "reader";
+  if (Array.isArray(r.readers) && r.readers.length > 0 && r.readers.every((x) => x.kind === "none")) return "reader";
+  return null;
+}
+
+const circleOf = (bctx, abs) => readersFor(bctx.readers, abs).circle;
+
+const shown = (name) => !name.startsWith(".");
+
+// A relative folder or file path, refused unless every segment is a plain, visible name.
+function cleanRel(rel, what) {
+  const r = String(rel ?? "").replace(/^\/+|\/+$/g, "");
+  if (r === "") return "";
+  const parts = r.split("/");
+  if (parts.some((p) => p === "" || p === "." || p === ".." || !shown(p))) throw new EvdaError(`${rel} is not ${what} in your record.`, { code: "OUTSIDE", exit: 2 });
+  return parts.join("/");
+}
+
+// Walk the rules down `rel` from the root: every segment visible, not skipped by the scan, and no
+// symlink on the way. Returns the lstat of the last segment, or null when the path is not one the
+// listing shows (missing included).
+function reachable(bctx, rel) {
+  const parts = rel.split("/");
+  let st = null;
+  for (let i = 0; i < parts.length; i++) {
+    const sub = parts.slice(0, i + 1).join("/");
+    try { st = lstatSync(join(bctx.evda.dir, sub)); } catch { return null; }
+    if (st.isSymbolicLink() || bctx.skip(sub, st)) return null;
+    if (i < parts.length - 1 && !st.isDirectory()) return null;
+  }
+  return st;
+}
+
+// The pinned folders: each DEFAULT_PINS role the mapping gives a folder, with whether it is there.
+// A role the mapping leaves out is not pinned, except the record roles, which read from
+// `record/<x>` as everywhere else.
+export function pins(evda, { bctx = browseContext(evda) } = {}) {
+  const out = [];
+  const seen = new Set();
+  for (const role of DEFAULT_PINS) {
+    let r;
+    try { r = resolveRole(evda, role); } catch { continue; }
+    if (r.kind === "source") continue;
+    if (!r.mapped && !role.startsWith("record/")) continue;
+    let folder;
+    try { folder = cleanRel(r.mapped ? String(r.rel).replace(/^(\.\/)+/, "") : role, "a folder"); } catch { continue; }
+    if (folder === "" || seen.has(folder)) continue;
+    seen.add(folder);
+    const st = reachable(bctx, folder);
+    out.push({ role, title: ROLE_TITLES[role] ?? folderTitle(folder), folder, exists: Boolean(st?.isDirectory()) });
+  }
+  return out;
+}
+
+const byName = (a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+
+// Dated names newest first, ahead of the rest; the rest by name.
+function fileOrder(a, b) {
+  const da = DATED.test(a.name), db = DATED.test(b.name);
+  if (da && db) return -byName(a, b);
+  if (da !== db) return da ? -1 : 1;
+  return a.name.localeCompare(b.name, undefined, { numeric: true, sensitivity: "base" });
+}
+
+// One folder's children: its folders and its files, each file with the circle that homes it.
+// `hidden` counts the files kept closed (noted, sealed, a part no AI reads), never their names.
+// `noted` gives each noted entry by its date alone (HQ-2049), newest first: the date its name
+// starts with, else the day it was last written. Never a name, a title or a word of it.
+// `tooling` counts what the view leaves out by kind (isTooling). At the root, the files that say
+// how the record works are left to `operating` instead.
+export function browse(evda, folder = "", { bctx = browseContext(evda) } = {}) {
+  const rel = cleanRel(folder, "a folder");
+  if (rel !== "") {
+    const st = reachable(bctx, rel);
+    if (!st || !st.isDirectory()) throw new EvdaError(`${rel} is not a folder in your record.`, { code: "NOT_FOUND", exit: 2 });
+  }
+  const abs = rel === "" ? evda.dir : join(evda.dir, rel);
+  const dirs = [];
+  const files = [];
+  let hidden = 0;
+  let tooling = 0;
+  const noted = [];
+  const candidates = [];
+  for (const name of readdirSync(abs)) {
+    const child = rel === "" ? name : `${rel}/${name}`;
+    let st;
+    try { st = lstatSync(join(evda.dir, child)); } catch { continue; }
+    if (st.isSymbolicLink() || bctx.skip(child, st)) continue;
+    if (!shown(name)) { tooling++; continue; }
+    if (st.isDirectory()) dirs.push({ path: child, name });
+    else if (!st.isFile()) continue;
+    else if (rel === "" && isOperating(bctx, name)) continue;
+    else if (isTooling(name, st.size)) tooling++;
+    else candidates.push({ child, name, size: st.size, mtime: st.mtimeMs });
+  }
+  // Every file, not only notes: a PDF or an image iCloud holds only in the cloud is listed as such,
+  // so the app says so and fetches it on a click instead of downloading it by opening (HQ-2071).
+  const cloud = datalessAmong(evda.dir, candidates.map((c) => c.child));
+  for (const c of candidates) {
+    const fabs = join(evda.dir, c.child);
+    const inCloud = cloud.has(c.child);
+    const why = closedBecause(bctx, fabs, { cloud: inCloud });
+    if (why) {
+      hidden++;
+      if (why === "noted") noted.push(notedDate(c.name, c.mtime));
+      continue;
+    }
+    files.push({ path: c.child, name: c.name, size: c.size, circle: circleOf(bctx, fabs), text: isTextPath(c.child) && c.size <= MAX_OPEN_BYTES, cloud: inCloud });
+  }
+  dirs.sort(byName);
+  files.sort(fileOrder);
+  noted.sort().reverse();
+  return { folder: rel, dirs, files, hidden, noted, tooling };
+}
+
+// A noted entry's date and nothing else: the YYYY-MM-DD its name starts with, else the local day
+// it was last written.
+export function notedDate(name, mtimeMs) {
+  const m = DATED.exec(name);
+  if (m) return m[0];
+  const d = new Date(mtimeMs);
+  const two = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${two(d.getMonth() + 1)}-${two(d.getDate())}`;
+}
+
+// The files that say how the record and its agent work, from the root (isOperating), each with its
+// circle, by name. Closed ones are left out as anywhere else.
+export function operating(evda, { bctx = browseContext(evda) } = {}) {
+  const out = [];
+  for (const name of readdirSync(evda.dir).sort((a, b) => a.localeCompare(b, undefined, { sensitivity: "base" }))) {
+    let st;
+    try { st = lstatSync(join(evda.dir, name)); } catch { continue; }
+    if (!st.isFile() || st.isSymbolicLink() || bctx.skip(name, st) || !shown(name) || !isOperating(bctx, name)) continue;
+    const abs = join(evda.dir, name);
+    if (closedBecause(bctx, abs)) continue;
+    out.push({ path: name, name, size: st.size, circle: circleOf(bctx, abs), text: isTextPath(name) && st.size <= MAX_OPEN_BYTES, cloud: false });
+  }
+  return out;
+}
+
+// Append the owner's words to today's daily note, verbatim, under a new timestamped section: the
+// same write evda_write makes (lib/tools.mjs write, lib/day-file.mjs appendToDay), so nothing is
+// ever replaced. Returns { path, bytes, section }.
+export const CAPTURE_CONTEXT = "Typed into the capture box in the EVÐA app.";
+export function capture(evda, words, { now = new Date() } = {}) {
+  return writeToday(evda, { words, context: CAPTURE_CONTEXT }, { now });
+}
+
+// The circle a file at the record's root would land in: the record's default home. The app tags a
+// file with its circle only when it is not this one, so the usual circle is not on every row.
+export function defaultCircle(evda, { bctx = browseContext(evda) } = {}) {
+  return circleOf(bctx, join(evda.dir, "evda-default-home.md"));
+}
+
+// Today's Journal (HQ-2038): today's daily note, always there for the app even before it is
+// written. `exists` false means an empty page; the first capture creates it through `write`.
+// `path` is null only when the record maps no daily role.
+export function today(evda, { now = new Date(), bctx = browseContext(evda) } = {}) {
+  const home = defaultCircle(evda, { bctx });
+  let path;
+  try { path = todayPath(evda, { now }); } catch { return { path: null, exists: false, text: "", circle: home, home }; }
+  const st = reachable(bctx, path);
+  if (!st?.isFile()) return { path, exists: false, text: "", circle: home, home };
+  const opened = openEntry(evda, path, { bctx });
+  return { path, exists: true, text: opened.text, circle: opened.circle, home };
+}
+
+// Every text file the listing shows, the whole record walked one `browse` at a time, plus the
+// operating files at the root (HQ-2049): the app's quick open and its link resolution read this,
+// so a name the tree would not show (noted, sealed, a part no AI reads, tooling, excluded) is never
+// offered or resolved. Paths only, in walk order; nothing of any file's words.
+export function index(evda, { bctx = browseContext(evda) } = {}) {
+  const out = operating(evda, { bctx }).filter((f) => f.text).map((f) => f.path);
+  const walk = (folder) => {
+    const f = browse(evda, folder, { bctx });
+    for (const file of f.files) if (file.text) out.push(file.path);
+    for (const d of f.dirs) walk(d.path);
+  };
+  walk("");
+  return out;
+}
+
+// One listed text file, opened: its words with any sealed section replaced by one line, and its
+// circle. Anything `browse` would not list as text is refused, with nothing of it returned.
+export function openEntry(evda, path, { bctx = browseContext(evda) } = {}) {
+  const rel = cleanRel(path, "a file");
+  const refused = () => new EvdaError(`${path} is not in your record.`, { code: "OUTSIDE", exit: 2 });
+  if (rel === "") throw refused();
+  const st = reachable(bctx, rel);
+  if (!st) throw refused();
+  if (!st.isFile()) throw refused();
+  const name = rel.split("/").pop();
+  if (isTooling(name, st.size) && !(rel === name && isOperating(bctx, name))) throw refused();
+  const abs = join(evda.dir, rel);
+  // A hard path check after the walk: the resolved file is inside the resolved record.
+  const root = realpathSync(evda.dir);
+  if (!realpathSync(abs).startsWith(root + "/")) throw refused();
+  if (!isTextPath(rel)) throw new EvdaError(`${rel} is not text, so it opens in Finder, not here.`, { code: "NOT_TEXT", exit: 2 });
+  if (st.size > MAX_OPEN_BYTES) throw new EvdaError(`${rel} is too large to open here.`, { code: "TOO_LARGE", exit: 2 });
+  if (closedBecause(bctx, abs)) throw refused();
+  const text = readFileSync(abs, "utf8");
+  return { path: rel, text: aiView(text).text, circle: circleOf(bctx, abs) };
+}
+
+// ─── Attachments: PDFs, images and every other file the tree lists (HQ-2071) ───────────────────
+//
+// The app shows a PDF or an image itself and hands any other attachment to the Mac's default app.
+// What it may show is what `browse` lists and `openEntry` would not open as text: the same walk,
+// the same closed rules, decided from names and stat alone, so asking never downloads a file iCloud
+// holds only in the cloud. The app serves the bytes itself, only for a path this answered.
+
+const IMAGE_EXTENSIONS = new Set(["png", "jpg", "jpeg", "heic", "heif", "gif", "webp"]);
+
+// "pdf", "image", or "other", by the name alone.
+export function attachmentKind(rel) {
+  const name = String(rel ?? "").split("/").pop() ?? "";
+  const dot = name.lastIndexOf(".");
+  const ext = dot <= 0 ? "" : name.slice(dot + 1).toLowerCase();
+  if (ext === "pdf") return "pdf";
+  if (IMAGE_EXTENSIONS.has(ext)) return "image";
+  return "other";
+}
+
+// One listed file that is not text: its kind, size, circle, and whether its bytes are only in
+// iCloud. Refused, with nothing of it returned, whenever `browse` would not list it.
+export function attachEntry(evda, path, { bctx = browseContext(evda) } = {}) {
+  const rel = cleanRel(path, "a file");
+  const refused = () => new EvdaError(`${path} is not in your record.`, { code: "OUTSIDE", exit: 2 });
+  if (rel === "") throw refused();
+  const st = reachable(bctx, rel);
+  if (!st || !st.isFile()) throw refused();
+  const name = rel.split("/").pop();
+  if (isTooling(name, st.size)) throw refused();
+  const abs = join(evda.dir, rel);
+  const root = realpathSync(evda.dir);
+  if (!realpathSync(abs).startsWith(root + "/")) throw refused();
+  if (isTextPath(rel)) throw new EvdaError(`${rel} is text, so it opens as a note.`, { code: "TEXT", exit: 2 });
+  const cloud = datalessAmong(evda.dir, [rel]).has(rel);
+  if (closedBecause(bctx, abs, { cloud })) throw refused();
+  return { path: rel, kind: attachmentKind(rel), size: st.size, circle: circleOf(bctx, abs), cloud };
+}
+
+// Every listed file that is not text, by path, the whole tree walked as `index` walks it: what a
+// link or an embed to a PDF or an image resolves against. Paths only.
+export function attachments(evda, { bctx = browseContext(evda) } = {}) {
+  const out = [];
+  const walk = (folder) => {
+    const f = browse(evda, folder, { bctx });
+    for (const file of f.files) if (!file.text && !isTextPath(file.path)) out.push(file.path);
+    for (const d of f.dirs) walk(d.path);
+  };
+  walk("");
+  return out;
+}

package/lib/circles.mjs

@@ -552,7 +552,11 @@ export function markdownFiles(root) {
     for (const name of readdirSync(abs).sort()) {
       if (name.startsWith(".") || name === "node_modules") continue;
       const p = join(abs, name);
-      const st = statSync(p);
+      // 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
+      // way, so skip it rather than let the whole walk crash on one broken pointer.
+      let st;
+      try { st = statSync(p); } catch { continue; }
       if (st.isDirectory()) walk(p);
       else if (st.isFile() && /\.md$/i.test(name)) out.push(p);
     }