create-evda 0.1.8 → 0.1.9

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";
 
@@ -59,6 +61,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 +78,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 +149,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 +158,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 +167,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 }) } };
       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 +186,8 @@ 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; }
         if (auth.FALSIFY("log-content", env)) line.args = one.params?.arguments;
         record(line);
       }
@@ -268,6 +279,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);