create-evda 0.1.8 → 0.1.10

package/lib/keychain.mjs

@@ -0,0 +1,181 @@
+// macOS Keychain storage for the credential lines gather finds (HQ-1916, builds on HQ-1368).
+// First version, his own words: "it just needs to be super initial versioning" -- the smallest thing
+// that takes the password off disk.
+//
+// At `evda gather apply`, a note gather caught as holding a credential (lib/gather.mjs CRED_LINE, or
+// a bare token line shaped like a secret) is still sealed into Credentials/ as it is today, but each
+// value found in it is written into the login Keychain (service EVÐA) instead of staying in the
+// file. The line keeps its own label; only the value becomes a plain pointer:
+//   Password: in your Keychain (EVÐA, wifi.md, password)
+// Not macOS, or the Keychain write fails: the value stays in the file, unchanged, as it did before
+// this ticket, and gather-apply says so in one line. Nothing here calls any MCP tool, and nothing
+// here is registered as one: the owner reads a secret with `evda secret <file>`, on their own Mac,
+// printed to their own terminal only (Spec 07, the sealed folder's own guarantee).
+//
+// EVDA_KEYCHAIN_FALSIFY=<mode,...>, for the tests:
+//   no-keychain    keychainAvailable() always says no, so a credential file is never redacted
+//   write-fails    every "security add-generic-password" fails, so the value stays in the file
+//
+// HQ-2051: under node's test runner, nothing here may reach the default (login) keychain. A test run
+// that names no keychain, or names one that does not exist (`security` then falls back to the
+// default instead of failing), throws before `security` runs. On Hestia's CI runner the default
+// keychain does not exist under the throwaway HOME, so such a call raised a "Keychain Not Found"
+// dialog that sat on the screen for hours and failed every Mac journey. A test that truly means the
+// login keychain sets EVDA_KEYCHAIN_ALLOW_DEFAULT=1; none does.
+
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { CRED_LINE } from "./gather.mjs";
+import { secretShape } from "./references.mjs";
+
+export const SERVICE = "EVÐA";
+export const KEYCHAIN_FALSIFY_MODES = ["no-keychain", "write-fails"];
+const falsified = (mode) => (process.env.EVDA_KEYCHAIN_FALSIFY ?? "").split(",").map((s) => s.trim()).includes(mode);
+
+// The account a credential's Keychain item is filed under: the record file it came from, and its
+// label, so `evda secret <file>` can find every value a file's pointers name.
+export const accountFor = (fileName, label) => `${fileName} :: ${label}`;
+
+// Whether this machine can hold a secret in the Keychain at all. Never throws.
+export function keychainAvailable() {
+  if (falsified("no-keychain")) return false;
+  if (process.platform !== "darwin") return false;
+  try {
+    execFileSync("security", ["list-keychains"], { stdio: ["ignore", "ignore", "ignore"] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// True inside a `node --test` run: its children carry NODE_TEST_CONTEXT, and so does every CLI a
+// test spawns with the inherited env; --test-isolation=none runs in-process with --test in execArgv.
+export function underTestRunner(env = process.env, execArgv = process.execArgv) {
+  return Boolean(env.NODE_TEST_CONTEXT) || execArgv.some((a) => a === "--test" || a.startsWith("--test-"));
+}
+
+// Throws when a test run would reach the default keychain. Every Keychain call below goes through it.
+export function assertKeychainAllowed(keychainPath, env = process.env) {
+  if (!underTestRunner(env) || env.EVDA_KEYCHAIN_ALLOW_DEFAULT === "1") return;
+  if (!keychainPath) throw new Error("evda refuses the default keychain under a test run: pass a throwaway keychainPath or set EVDA_KEYCHAIN_FALSIFY (HQ-2051)");
+  if (!existsSync(keychainPath)) throw new Error(`evda refuses a keychain that does not exist under a test run (${keychainPath}): \`security\` would fall back to the default keychain (HQ-2051)`);
+}
+
+const keychainArgs = (keychainPath) => (keychainPath ? [keychainPath] : []);
+
+// `security add-generic-password`, overwriting an item already at this account (a second gather of
+// the same file lands on the same value). Throws on failure; the caller decides what that means.
+export function addSecret({ account, value, keychainPath = null } = {}) {
+  if (falsified("write-fails")) throw new Error("EVDA_KEYCHAIN_FALSIFY=write-fails");
+  assertKeychainAllowed(keychainPath);
+  execFileSync("security", ["add-generic-password", "-a", account, "-s", SERVICE, "-w", value, "-U", ...keychainArgs(keychainPath)], { stdio: ["ignore", "ignore", "pipe"] });
+}
+
+// Never throws on a missing item: revert removes what it can and says what it removed. Under a test
+// run it does throw when it would reach the default keychain (HQ-2051).
+export function removeSecret({ account, keychainPath = null } = {}) {
+  assertKeychainAllowed(keychainPath);
+  try {
+    execFileSync("security", ["delete-generic-password", "-a", account, "-s", SERVICE, ...keychainArgs(keychainPath)], { stdio: ["ignore", "ignore", "ignore"] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// The value at an account, or throws (no item, or the Keychain refused to read it).
+export function readSecret({ account, keychainPath = null } = {}) {
+  assertKeychainAllowed(keychainPath);
+  return execFileSync("security", ["find-generic-password", "-a", account, "-s", SERVICE, "-w", ...keychainArgs(keychainPath)], { stdio: ["ignore", "pipe", "ignore"] }).toString("utf8").replace(/\n$/, "");
+}
+
+// Every credential value on its own line in `text`: a labeled line (CRED_LINE, the same shape that
+// typed the note in the first place) keeps its label and the text before the value, so only the
+// value itself is later replaced; a bare line shaped like a secret (a token with no "label:") has no
+// label of its own, so it is numbered "secret", "secret 2", ... in the order it appears. A labeled
+// line whose value is empty (the code sits on the next line instead) is left alone: multi-line values
+// are out of this first version's scope.
+// A line already holding a pointer is not a value, so a file sealed once has nothing left to move
+// (HQ-2622: the migration's second run is a no-op because of this). Two lines with the same label
+// ("password" twice, or a "secret:" line beside a bare token) get "<label> 2", "<label> 3", ... so
+// each lands on its own Keychain account and neither overwrites the other.
+export function extractSecrets(text) {
+  const lines = text.split("\n");
+  const out = [];
+  let bare = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (POINTER.test(line)) continue;
+    const m = CRED_LINE.exec(line);
+    if (m) {
+      const label = (m[1] ?? m[2]).toLowerCase().replace(/[\s_-]+/g, " ");
+      const value = m[3].replace(/[*_\x60]+$/g, "").trim();
+      if (!value) continue;
+      out.push({ index: i, label, prefix: line.slice(0, line.length - m[3].length), value, whole: false });
+      continue;
+    }
+    if (secretShape(line.trim())) {
+      bare += 1;
+      out.push({ index: i, label: bare === 1 ? "secret" : `secret ${bare}`, prefix: "", value: line, whole: true });
+    }
+  }
+  const used = new Set();
+  for (const s of out) {
+    let label = s.label;
+    for (let n = 2; used.has(label); n++) label = `${s.label} ${n}`;
+    used.add(label);
+    s.label = label;
+  }
+  return out;
+}
+
+// A pointer line reads back its account: "in your Keychain (EVÐA, wifi.md, password)".
+const POINTER = /in your Keychain \(([^,]+), ([^,]+), ([^)]+)\)/;
+export const pointerFor = (fileName, label) => `in your Keychain (${SERVICE}, ${fileName}, ${label})`;
+
+// Move every credential value in `text` into the Keychain, one item per line, and return the text
+// with each replaced by its pointer. All-or-nothing per file: if any value fails to write, every
+// item this call added is removed again and the original text comes back unchanged, so a file is
+// never left half in the Keychain and half redacted.
+// Returns { ok: true, text, accounts } or { ok: false, why }.
+export function sealForKeychain(text, fileName, { keychainPath = null } = {}) {
+  if (!keychainAvailable()) return { ok: false, why: "not on macOS, or the Keychain is unavailable" };
+  const secrets = extractSecrets(text);
+  if (!secrets.length) return { ok: false, why: "no credential value was found on its own line" };
+  const added = [];
+  try {
+    for (const s of secrets) {
+      const account = accountFor(fileName, s.label);
+      addSecret({ account, value: s.value, keychainPath });
+      added.push(account);
+    }
+  } catch (e) {
+    for (const account of added) removeSecret({ account, keychainPath });
+    return { ok: false, why: `the Keychain write failed (${String(e.message ?? e).split("\n")[0]})` };
+  }
+  const lines = text.split("\n");
+  for (const s of secrets) lines[s.index] = s.whole ? pointerFor(fileName, s.label) : `${s.prefix}${pointerFor(fileName, s.label)}`;
+  return { ok: true, text: lines.join("\n"), accounts: added };
+}
+
+// The owner's own read: every pointer in `text` resolved back to its value, for `evda secret <file>`
+// only. No MCP tool calls this.
+export function resolvePointers(text, { keychainPath = null } = {}) {
+  const lines = text.split("\n");
+  let resolved = 0;
+  let failed = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const m = POINTER.exec(lines[i]);
+    if (!m) continue;
+    const account = accountFor(m[2], m[3]);
+    try {
+      const value = readSecret({ account, keychainPath });
+      lines[i] = lines[i].slice(0, m.index) + value + lines[i].slice(m.index + m[0].length);
+      resolved += 1;
+    } catch {
+      lines[i] = `${lines[i]}  (could not read this from the Keychain)`;
+      failed += 1;
+    }
+  }
+  return { text: lines.join("\n"), resolved, failed };
+}

package/lib/manifest.mjs

@@ -16,7 +16,11 @@ export const SCHEMA_VERSION = 1;
 export const KNOWN_LAYERS = ["record", "ledger", "circles"];
 // `filing` (HQ-1385) is the owner's answer to the one setup question, "everything" or "asked";
 // lib/day-file.mjs filingOf reads it for every agent and hook.
-export const KNOWN_KEYS = ["evda", "id", "name", "owner", "created", "layers", "mapping", "subrecords", "read_by", "filing"];
+// `every_chat` (HQ-2205) is, per chat app, whether the owner put the every-chat line in that app's
+// settings ("set") or does not want it ("declined"); lib/every-chat.mjs reads it, evda_every_chat writes it.
+// `corrections` (HQ-2325) is the file a correction is appended to, when the owner keeps them in
+// their own file rather than the operating layer's "What I have been taught"; lib/corrections.mjs reads it.
+export const KNOWN_KEYS = ["evda", "id", "name", "owner", "created", "layers", "mapping", "subrecords", "read_by", "filing", "every_chat", "sync", "corrections"];
 
 // Whether a record's circles stop at its sub-records (HQ-1371). A sub-record is a directory below
 // the root holding its own evda.json. "bounded": the parent's circles, coverage, scan and release

package/lib/mcp-auth.mjs

@@ -21,6 +21,9 @@
 //   EVDA_MCP_FALSIFY=skip-redirect-check   the redirect URI is not compared, at /authorize or /token
 //   EVDA_MCP_FALSIFY=log-content           the call log carries the tool arguments (lib/mcp-http.mjs)
 //   EVDA_MCP_FALSIFY=log-args              every tool call logs its arguments, stdio and HTTP (lib/mcp.mjs)
+//
+// None of them may be set on a server the internet can reach: a --public-url outside loopback and the
+// reserved test names refuses to start while any switch is set (HQ-2082, refuseFalsifyOnPublicServer).
 
 import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
@@ -28,7 +31,11 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { EvdaError } from "./errors.mjs";
 
-export const FALSIFY = (mode, env = process.env) => String(env.EVDA_MCP_FALSIFY ?? "").split(",").map((m) => m.trim()).includes(mode);
+// Every switch, so the startup guard can name the ones that are set rather than ask about each.
+export const MCP_FALSIFY_MODES = ["no-token-check", "accept-expired", "accept-revoked", "skip-pkce", "skip-redirect-check", "log-content", "log-args"];
+
+export const falsifyModes = (env = process.env) => String(env.EVDA_MCP_FALSIFY ?? "").split(",").map((m) => m.trim()).filter(Boolean);
+export const FALSIFY = (mode, env = process.env) => falsifyModes(env).includes(mode);
 
 export const ACCESS_TTL_MS = 60 * 60 * 1000; // one hour; Claude refreshes on a 401
 export const REFRESH_TTL_MS = 30 * 24 * 60 * 60 * 1000; // thirty days, renewed on every rotation
@@ -44,6 +51,39 @@ export const SCOPE = "evda";
 export const HOSTED_REDIRECTS = ["https://claude.ai/api/mcp/auth_callback", "https://claude.com/api/mcp/auth_callback"];
 const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]"]);
 
+// Can a stranger on the internet reach this address? Loopback is this machine, and the reserved names
+// (RFC 6761 .test .invalid .example .localhost, RFC 2606 example.com and its siblings) resolve nowhere,
+// which is what the tests serve on. Anything else counts as reachable, including an address nobody can
+// parse: a value this cannot read is the one most likely to be a real address typed wrong.
+const RESERVED_TLDS = new Set(["test", "invalid", "example", "localhost"]);
+const RESERVED_NAMES = new Set(["example.com", "example.net", "example.org"]);
+export function isPublicUrl(url) {
+  let host;
+  try { host = new URL(String(url)).hostname.toLowerCase(); } catch { return true; }
+  if (LOOPBACK.has(host) || host === "::1" || /^127\./.test(host)) return false;
+  return !(RESERVED_TLDS.has(host.split(".").pop()) || RESERVED_NAMES.has(host));
+}
+
+/**
+ * HQ-2082: each test hook above turns off one of this server's refusals, and no-token-check turns off
+ * authentication altogether, so a switch set on the machine that serves the public address would open
+ * the record to anyone who finds it. One can arrive without anybody choosing it: exported from a shell
+ * profile, or carried in a run script copied from a test. So the server refuses to start instead.
+ *
+ * Config time, once, before anything listens. A per-request check would already have served the first
+ * request of a process that should never have started, and would leave the switches half working.
+ *
+ * Returns the switches that are set, which on loopback is where they go on working.
+ */
+export function refuseFalsifyOnPublicServer(publicUrl, env = process.env) {
+  const set = falsifyModes(env);
+  if (!set.length || !isPublicUrl(publicUrl)) return set;
+  throw new EvdaError(
+    `REFUSED: EVDA_MCP_FALSIFY is set to ${set.join(", ")}, and --public-url ${publicUrl} is an address the internet can reach. Every one of those switches turns off a refusal this server makes, so serving that address with one set would hand the record to anyone who finds it. Unset EVDA_MCP_FALSIFY, or serve on loopback (--public-url http://127.0.0.1:<port>) to use them.`,
+    { code: "FALSIFY_ON_PUBLIC_URL", exit: 2 }
+  );
+}
+
 export const sha256 = (s) => createHash("sha256").update(s).digest("hex");
 const b64url = (buf) => buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 export const newSecret = (bytes = 32) => b64url(randomBytes(bytes));

package/lib/mcp-http.mjs

@@ -7,6 +7,8 @@
 // It binds to 127.0.0.1 by default and speaks plain HTTP: TLS and the public name belong to the
 // tunnel in front of it (Tailscale Funnel on Hestia). --public-url is the address the world uses,
 // and every URL in the metadata is built from it rather than from a Host header anyone can send.
+// When that address is one the internet can reach, no EVDA_MCP_FALSIFY switch may be set: the server
+// refuses to start rather than serve the world with a refusal turned off (HQ-2082).
 //
 // The caller is always Claude. A remote client cannot be a model on the owner's own devices, and its
 // clientInfo is whatever it says, so read_by (HQ-1374) applies as it does to Claude locally.
@@ -21,7 +23,7 @@ import { createServer } from "node:http";
 import { appendFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { openEvda } from "./manifest.mjs";
-import { handle, newSession, TOOLS } from "./mcp.mjs";
+import { handle, newSession, TOOLS, clientInfoOf } from "./mcp.mjs";
 import { callerFrom } from "./readers.mjs";
 import * as auth from "./mcp-auth.mjs";
 
@@ -52,6 +54,23 @@ function limiter() {
   };
 }
 
+// HQ-2330: what a request carries beyond the protocol, by NAME only, so the log can show whether an
+// app sends something that names the conversation (claude.ai reuses one Mcp-Session-Id across chats).
+// Values are never logged: a header or a _meta value can carry anything.
+const PLAIN_HEADERS = new Set(["host", "content-type", "content-length", "authorization", "accept", "accept-encoding", "accept-language", "user-agent", "connection", "origin", "mcp-session-id", "mcp-protocol-version", "last-event-id", "via", "forwarded", "x-real-ip", "cache-control", "pragma", "te", "keep-alive"]);
+const clipName = (k) => String(k).replace(/[^\x21-\x7e]/g, "").slice(0, 64);
+export function extraNames(headers, params) {
+  const out = {};
+  const h = Object.keys(headers ?? {}).map((k) => k.toLowerCase()).filter((k) => !PLAIN_HEADERS.has(k) && !k.startsWith("x-forwarded-") && !k.startsWith("tailscale-") && !k.startsWith("sec-fetch-")).map(clipName).slice(0, 20);
+  if (h.length) out.header_names = h;
+  const meta = params?._meta;
+  if (meta && typeof meta === "object" && !Array.isArray(meta)) {
+    const m = Object.keys(meta).map(clipName).slice(0, 20);
+    if (m.length) out.meta_keys = m;
+  }
+  return out;
+}
+
 const esc = (s) => String(s ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
 const shortId = (s) => auth.sha256(String(s)).slice(0, 8);
 
@@ -59,6 +78,7 @@ export function createMcpHttpServer({ dir, version, publicUrl, env = process.env
   const base = String(publicUrl).replace(/\/+$/, "");
   const baseUrl = new URL(base);
   if (baseUrl.protocol !== "https:" && !["127.0.0.1", "localhost"].includes(baseUrl.hostname)) throw new Error(`--public-url must be https (got ${base})`);
+  auth.refuseFalsifyOnPublicServer(base, env); // HQ-2082: no test switch on an address the world can reach
   const resource = `${base}/mcp`;
   const prmUrl = `${base}/.well-known/oauth-protected-resource/mcp`;
   const evda = openEvda(dir); // refuse to start on something that is not a record
@@ -75,14 +95,17 @@ export function createMcpHttpServer({ dir, version, publicUrl, env = process.env
     const url = new URL(req.url, base);
     const path = url.pathname;
     const ip = clientIp(req);
-    const note = { who: null };
+    const note = { who: null, method: null, tool: null, reason: null };
     const send = (status, body, headers = {}) => {
       const isJson = body !== null && typeof body === "object";
       res.writeHead(status, { "cache-control": "no-store", "x-content-type-options": "nosniff", ...(isJson ? { "content-type": "application/json" } : {}), ...headers });
       res.end(body === null || body === undefined ? undefined : isJson ? JSON.stringify(body) : body);
       // Path only: a query string on /authorize carries a state and a challenge, and on a bad
       // request could carry anything.
-      record({ http: req.method, path: knownPath(path), status, ms: clock() - started, ...(note.who ? { conn: note.who } : {}) });
+      // A refusal names why (HQ-2235): the error text this server wrote and the JSON-RPC method when
+      // the body parsed, never the body itself, so four different 400s can be told apart afterwards.
+      const why = status >= 400 && status < 500 ? { reason: note.reason ?? reasonOf(body), ...(note.method ? { method: note.method } : {}), ...(note.tool ? { tool: note.tool } : {}) } : {};
+      record({ http: req.method, path: knownPath(path), status, ms: clock() - started, ...(note.who ? { conn: note.who } : {}), ...why });
     };
     try {
       const now = clock();
@@ -143,6 +166,7 @@ export function createMcpHttpServer({ dir, version, publicUrl, env = process.env
     if (req.method === "DELETE") {
       const s = sessions.get(sid);
       if (s && s.family === grant.family) sessions.delete(sid);
+      if (!s) note.reason = "session not found";
       return send(s ? 204 : 404, null);
     }
     if (req.method !== "POST") return send(405, { error: "method_not_allowed" }, { allow: "POST, DELETE" });
@@ -151,6 +175,8 @@ export function createMcpHttpServer({ dir, version, publicUrl, env = process.env
     const raw = await readBody(req, MCP_BODY_LIMIT);
     try { msg = JSON.parse(raw); } catch { return send(400, { jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } }); }
     const batch = Array.isArray(msg) ? msg : [msg];
+    note.method = batch.map((x) => (typeof x?.method !== "string" ? "none" : METHODS.has(x.method) ? x.method : "unknown_method")).join(",");
+    if (batch.length === 1 && batch[0]?.method === "tools/call") note.tool = TOOL_NAMES.has(batch[0].params?.name) ? batch[0].params.name : "unknown_tool";
     const isInit = batch.some((x) => x?.method === "initialize");
     let session;
     let newSid = null;
@@ -158,7 +184,7 @@ export function createMcpHttpServer({ dir, version, publicUrl, env = process.env
       if (batch.length !== 1) return send(400, { jsonrpc: "2.0", id: null, error: { code: -32600, message: "initialize must be sent alone" } });
       evictSessions(now);
       newSid = randomBytes(24).toString("hex");
-      session = { family: grant.family, last: now, ctx: { version, log: (s) => log(s), env: readerEnv, evda: () => openEvda(dir), session: newSession(), caller: callerFrom({ env: readerEnv }) } };
+      session = { family: grant.family, last: now, ctx: { version, log: (s) => log(s), clock, env: readerEnv, evda: () => openEvda(dir), session: newSession(), caller: callerFrom({ env: readerEnv }), keepsToolList: true } };
       sessions.set(newSid, session);
     } else {
       if (!sid) return send(400, { jsonrpc: "2.0", id: null, error: { code: -32600, message: "Mcp-Session-Id header required; initialize first" } });
@@ -177,6 +203,9 @@ export function createMcpHttpServer({ dir, version, publicUrl, env = process.env
       if (method && one?.id !== undefined && one?.id !== null) {
         const st = r?.error ? "error" : r?.result?.isError ? "refused" : "ok";
         const line = { call: method === "tools/call" ? (TOOL_NAMES.has(tool) ? tool : "unknown_tool") : METHODS.has(method) ? method : "unknown_method", status: st, ms: clock() - t0, session: shortId(sid ?? newSid), conn: note.who };
+        // Which app connected (HQ-2207): initialize's clientInfo name and version, nothing else of it.
+        if (method === "initialize") { const ci = clientInfoOf(one.params); line.client_name = ci.name; line.client_version = ci.version; }
+        Object.assign(line, extraNames(req.headers, one.params));
         if (auth.FALSIFY("log-content", env)) line.args = one.params?.arguments;
         record(line);
       }
@@ -268,6 +297,15 @@ function page(title, body) {
 </head><body><h1>${esc(title)}</h1>${body}</body></html>`;
 }
 
+// The error text of a refusal this server wrote: a JSON-RPC error message, an OAuth error_description
+// or error code, or an HTML page's title. Server-authored strings only, capped.
+function reasonOf(body) {
+  let r = null;
+  if (typeof body === "string") r = /<title>([^<]*)<\/title>/.exec(body)?.[1] ?? null;
+  else if (body && typeof body === "object") r = typeof body.error === "object" ? body.error?.message : body.error_description ?? body.error;
+  return typeof r === "string" ? r.slice(0, 200) : null;
+}
+
 function withParams(uri, params) {
   const u = new URL(uri);
   for (const [k, v] of Object.entries(params)) if (v !== undefined && v !== null) u.searchParams.set(k, v);