create-evda 0.1.4 → 0.1.6

package/lib/mcp-http.mjs

@@ -0,0 +1,336 @@
+// `evda mcp --http`: the same server as `evda mcp`, over MCP's streamable HTTP transport, so a
+// record can be reached by the Claude apps, which connect from Anthropic's cloud to a public HTTPS
+// address (HQ-1378). The tools, the instructions and the per-session nudge are lib/mcp.mjs's; this
+// file adds the transport, the OAuth gate in front of it (lib/mcp-auth.mjs), a rate limit, and a
+// call log that holds tool names, statuses and durations and never a word of content.
+//
+// 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.
+//
+// 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.
+//
+// Routes, and nothing else answers:
+//   POST|GET|DELETE /mcp                              the MCP endpoint (bearer token required)
+//   GET /.well-known/oauth-protected-resource[/mcp]   RFC 9728
+//   GET /.well-known/oauth-authorization-server       RFC 8414
+//   POST /register   GET|POST /authorize   POST /token   POST /revoke
+
+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 { callerFrom } from "./readers.mjs";
+import * as auth from "./mcp-auth.mjs";
+
+const TOOL_NAMES = new Set(TOOLS.map((t) => t.name));
+const METHODS = new Set(["initialize", "ping", "tools/list", "tools/call", "resources/list", "resources/read", "resources/templates/list", "prompts/list", "notifications/initialized", "notifications/cancelled"]);
+export const MCP_BODY_LIMIT = 4 * 1024 * 1024;
+const FORM_BODY_LIMIT = 16 * 1024;
+export const SESSION_IDLE_MS = 12 * 60 * 60 * 1000;
+const MAX_SESSIONS = 200;
+const PENDING_TTL_MS = 10 * 60 * 1000;
+export const OWNER_CODE_MAX_FAILURES = 5;
+
+// Fixed-window counters. The numbers are generous for one person's connector and small for anyone
+// probing: an MCP session makes a few calls a minute, an authorization makes three requests once.
+export const LIMITS = {
+  mcp: { max: 240, windowMs: 60_000 }, // per connection (token family)
+  anon: { max: 60, windowMs: 60_000 }, // per address, every unauthenticated request
+  owner: { max: 10, windowMs: 15 * 60_000 }, // owner code attempts, per address
+};
+
+function limiter() {
+  const hits = new Map();
+  return (key, { max, windowMs }, now) => {
+    const h = hits.get(key);
+    if (!h || now - h.start >= windowMs) { hits.set(key, { start: now, n: 1 }); if (hits.size > 5000) hits.clear(); return 0; }
+    h.n += 1;
+    return h.n > max ? Math.ceil((h.start + windowMs - now) / 1000) : 0;
+  };
+}
+
+const esc = (s) => String(s ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+const shortId = (s) => auth.sha256(String(s)).slice(0, 8);
+
+export function createMcpHttpServer({ dir, version, publicUrl, env = process.env, log = (line) => process.stderr.write(`${line}\n`), clock = () => Date.now() }) {
+  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})`);
+  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
+  const store = auth.openStore(auth.authDir(evda, env));
+  const sessions = new Map();
+  const pending = new Map();
+  const limit = limiter();
+  let ownerFailures = [];
+  const readerEnv = { EVDA_READER: "claude" };
+  const record = (o) => log(JSON.stringify({ t: new Date(clock()).toISOString(), ...o }));
+
+  const server = createServer(async (req, res) => {
+    const started = clock();
+    const url = new URL(req.url, base);
+    const path = url.pathname;
+    const ip = clientIp(req);
+    const note = { who: 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 } : {}) });
+    };
+    try {
+      const now = clock();
+      if (path === "/mcp") return await mcp(req, res, { send, now, ip, note });
+      const wait = limit(`anon:${ip}`, LIMITS.anon, now);
+      if (wait) return send(429, { error: "rate_limited" }, { "retry-after": String(wait) });
+      if (req.method === "GET" && (path === "/.well-known/oauth-protected-resource" || path === "/.well-known/oauth-protected-resource/mcp")) return send(200, auth.protectedResourceMetadata(base, resource));
+      if (req.method === "GET" && path === "/.well-known/oauth-authorization-server") return send(200, auth.authServerMetadata(base));
+      if (req.method === "POST" && path === "/register") {
+        const body = await readJson(req, FORM_BODY_LIMIT);
+        if (body === undefined) return send(400, { error: "invalid_client_metadata", error_description: "The body must be JSON." });
+        const r = auth.registerClient(store, body, { now });
+        return send(r.status, r.body);
+      }
+      if (path === "/authorize" && req.method === "GET") return authorizePage(url, send, now);
+      if (path === "/authorize" && req.method === "POST") return await authorizeSubmit(req, send, now, ip);
+      if (req.method === "POST" && path === "/token") {
+        const form = await readForm(req);
+        if (!form) return send(400, { error: "invalid_request", error_description: "The body must be application/x-www-form-urlencoded." });
+        const r = auth.token(store, form, { resource, now, env });
+        return send(r.status, r.body);
+      }
+      if (req.method === "POST" && path === "/revoke") {
+        const form = await readForm(req);
+        if (!form) return send(400, { error: "invalid_request" });
+        const r = auth.revoke(store, form, { now, env });
+        return send(r.status, r.body);
+      }
+      return send(404, { error: "not_found" });
+    } catch (e) {
+      if (e?.code === "TOO_LARGE") return send(413, { error: "too_large" });
+      record({ error: e?.code ?? "internal", path: knownPath(path) });
+      log(e?.stack ?? String(e));
+      if (!res.headersSent) return send(500, { error: "server_error" });
+    }
+  });
+
+  async function mcp(req, res, { send, now, ip, note }) {
+    const origin = req.headers.origin;
+    if (origin && origin !== baseUrl.origin) return send(403, { error: "forbidden_origin" });
+    const m = /^Bearer ([A-Za-z0-9._~+/-]+=*)$/.exec(req.headers.authorization ?? "");
+    let grant = null;
+    if (auth.FALSIFY("no-token-check", env)) grant = { family: "falsified" };
+    else if (m) grant = auth.verifyAccess(store, m[1], { resource, now, env });
+    if (!grant) {
+      const wait = limit(`anon:${ip}`, LIMITS.anon, now);
+      if (wait) return send(429, { error: "rate_limited" }, { "retry-after": String(wait) });
+      const challenge = `Bearer resource_metadata="${prmUrl}", scope="${auth.SCOPE}"${m ? ', error="invalid_token"' : ""}`;
+      return send(401, { error: m ? "invalid_token" : "unauthorized" }, { "www-authenticate": challenge });
+    }
+    note.who = shortId(grant.family);
+    const wait = limit(`mcp:${grant.family}`, LIMITS.mcp, now);
+    if (wait) return send(429, { error: "rate_limited" }, { "retry-after": String(wait) });
+    const asked = req.headers["mcp-protocol-version"];
+    if (asked && !["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"].includes(asked)) return send(400, { jsonrpc: "2.0", id: null, error: { code: -32600, message: `unsupported MCP-Protocol-Version ${String(asked).slice(0, 20)}` } });
+    const sid = req.headers["mcp-session-id"];
+    if (req.method === "GET") return send(405, { error: "method_not_allowed" }, { allow: "POST, DELETE" });
+    if (req.method === "DELETE") {
+      const s = sessions.get(sid);
+      if (s && s.family === grant.family) sessions.delete(sid);
+      return send(s ? 204 : 404, null);
+    }
+    if (req.method !== "POST") return send(405, { error: "method_not_allowed" }, { allow: "POST, DELETE" });
+    if (!String(req.headers["content-type"] ?? "").includes("application/json")) return send(415, { error: "unsupported_media_type" });
+    let msg;
+    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];
+    const isInit = batch.some((x) => x?.method === "initialize");
+    let session;
+    let newSid = null;
+    if (isInit) {
+      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 }) } };
+      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" } });
+      session = sessions.get(sid);
+      if (!session || session.family !== grant.family) return send(404, { jsonrpc: "2.0", id: null, error: { code: -32001, message: "session not found; initialize again" } });
+      session.last = now;
+    }
+    const answers = [];
+    for (const one of batch) {
+      const t0 = clock();
+      const method = typeof one?.method === "string" ? one.method : null;
+      const tool = method === "tools/call" ? one.params?.name : null;
+      // The server decides who is calling, whatever clientInfo says.
+      const r = await handle(one, session.ctx).catch((e) => { log(e?.stack ?? String(e)); return { jsonrpc: "2.0", id: one?.id ?? null, error: { code: -32603, message: "internal error" } }; });
+      session.ctx.caller = callerFrom({ env: readerEnv });
+      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 };
+        if (auth.FALSIFY("log-content", env)) line.args = one.params?.arguments;
+        record(line);
+      }
+      if (r) answers.push(r);
+    }
+    if (!answers.length) return send(202, null);
+    return send(200, Array.isArray(msg) ? answers : answers[0], newSid ? { "mcp-session-id": newSid } : {});
+  }
+
+  function evictSessions(now) {
+    for (const [k, s] of sessions) if (now - s.last > SESSION_IDLE_MS) sessions.delete(k);
+    while (sessions.size >= MAX_SESSIONS) sessions.delete(sessions.keys().next().value);
+    for (const [k, p] of pending) if (p.expires <= now) pending.delete(k);
+  }
+
+  function authorizePage(url, send, now) {
+    const q = Object.fromEntries(url.searchParams);
+    const v = auth.checkAuthorizeRequest(store, q, { resource, env });
+    if (!v.ok) {
+      if (v.redirect) return send(302, null, { location: withParams(v.redirect, { error: v.error, error_description: v.description, state: v.state, iss: base }) });
+      return send(v.status, page("This connection cannot go ahead", `<p>${esc(v.description)}</p>`), { "content-type": "text/html; charset=utf-8", ...pageHeaders() });
+    }
+    evictSessions(now);
+    const id = randomBytes(24).toString("hex");
+    pending.set(id, { ...v.req, expires: now + PENDING_TTL_MS });
+    return send(200, consentPage(id, v.req), { "content-type": "text/html; charset=utf-8", ...pageHeaders(v.req.redirect_uri) });
+  }
+
+  async function authorizeSubmit(req, send, now, ip) {
+    // The form posts to itself. A browser sends Origin on a POST; anything else is not this page.
+    const origin = req.headers.origin;
+    if (origin && origin !== baseUrl.origin) return send(403, page("Refused", "<p>That form did not come from this page.</p>"), { "content-type": "text/html; charset=utf-8", ...pageHeaders() });
+    const form = await readForm(req);
+    const p = form && pending.get(form.request);
+    if (!p || p.expires <= now) return send(400, page("This page expired", "<p>Go back to Claude and connect again.</p>"), { "content-type": "text/html; charset=utf-8", ...pageHeaders() });
+    const html = { "content-type": "text/html; charset=utf-8", ...pageHeaders(p.redirect_uri) };
+    if (form.decision === "deny") {
+      pending.delete(form.request);
+      return send(302, null, { location: withParams(p.redirect_uri, { error: "access_denied", state: p.state, iss: base }) });
+    }
+    const wait = limit(`owner:${ip}`, LIMITS.owner, now);
+    if (wait) return send(429, page("Too many tries", "<p>Wait a few minutes, then try again.</p>"), { ...html, "retry-after": String(wait) });
+    if (!auth.spendOwnerCode(store, form.owner_code, now)) {
+      ownerFailures = ownerFailures.filter((t) => now - t < LIMITS.owner.windowMs).concat(now);
+      record({ owner_code: "wrong", failures: ownerFailures.length });
+      if (ownerFailures.length >= OWNER_CODE_MAX_FAILURES) {
+        // Five wrong codes in fifteen minutes: every open owner code is spent. A new one comes from
+        // the machine, which is the whole point of having one.
+        auth.burnOwnerCodes(store, now);
+        ownerFailures = [];
+        pending.delete(form.request);
+        record({ owner_code: "burned" });
+        return send(403, page("Owner codes cancelled", "<p>Too many wrong codes, so every open owner code was cancelled. Ask your agent for a new one.</p>"), html);
+      }
+      return send(401, consentPage(form.request, p, "That code is not right, or it has already been used."), html);
+    }
+    pending.delete(form.request);
+    const code = auth.issueCode(store, p, { now });
+    record({ owner_code: "accepted", client: shortId(p.client_id) });
+    return send(302, null, { location: withParams(p.redirect_uri, { code, state: p.state, iss: base }) });
+  }
+
+  function consentPage(id, r, problem = "") {
+    const host = (() => { try { return new URL(r.redirect_uri).host; } catch { return "?"; } })();
+    const body = `
+<p><b>${esc(r.client_name || "A client")}</b> wants to read and write your EVÐA through this server. When you allow it, you are sent back to <b>${esc(host)}</b>.</p>
+${problem ? `<p class="bad">${esc(problem)}</p>` : ""}
+<form method="post" action="/authorize">
+<input type="hidden" name="request" value="${esc(id)}">
+<label for="c">Owner code. Ask your agent for one.</label>
+<input id="c" name="owner_code" autocomplete="one-time-code" autocapitalize="characters" spellcheck="false" placeholder="XXXX-XXXX-XXXX-XXXX" required>
+<div class="row"><button name="decision" value="allow" type="submit">Allow</button><button name="decision" value="deny" type="submit" formnovalidate class="quiet">Deny</button></div>
+</form>`;
+    return page("Connect to your EVÐA", body);
+  }
+
+  function pageHeaders(redirect) {
+    let to = "";
+    try { if (redirect) to = ` ${new URL(redirect).origin}`; } catch { /* no redirect */ }
+    return { "content-security-policy": `default-src 'none'; style-src 'unsafe-inline'; form-action 'self'${to}; frame-ancestors 'none'; base-uri 'none'`, "x-frame-options": "DENY", "referrer-policy": "same-origin" };
+  }
+
+  return { server, store, sessions, resource, base };
+}
+
+function page(title, body) {
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${esc(title)}</title>
+<style>:root{color-scheme:light dark}body{font:16px/1.5 -apple-system,system-ui,sans-serif;max-width:32rem;margin:3rem auto;padding:0 16px}input{font:inherit;width:100%;padding:.6rem;margin:.4rem 0 1rem;box-sizing:border-box;letter-spacing:.08em}button{font:inherit;padding:.6rem 1.2rem;margin-right:.5rem}.quiet{background:none;border:1px solid #888}.bad{color:#c33}code{font-size:.9em}</style>
+</head><body><h1>${esc(title)}</h1>${body}</body></html>`;
+}
+
+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);
+  return u.toString();
+}
+
+function knownPath(p) {
+  return ["/mcp", "/register", "/authorize", "/token", "/revoke", "/.well-known/oauth-protected-resource", "/.well-known/oauth-protected-resource/mcp", "/.well-known/oauth-authorization-server"].includes(p) ? p : "other";
+}
+
+// Behind the tunnel every connection comes from loopback, and the tunnel names the real address in
+// X-Forwarded-For. A direct connection from anywhere else is its own address.
+function clientIp(req) {
+  const remote = req.socket.remoteAddress ?? "";
+  const loop = remote === "127.0.0.1" || remote === "::1" || remote === "::ffff:127.0.0.1";
+  const fwd = String(req.headers["x-forwarded-for"] ?? "").split(",")[0].trim();
+  return loop && fwd ? fwd : remote;
+}
+
+function readBody(req, max) {
+  return new Promise((resolveBody, reject) => {
+    let n = 0;
+    const chunks = [];
+    req.on("data", (c) => {
+      n += c.length;
+      if (n > max) { const e = new Error("too large"); e.code = "TOO_LARGE"; req.destroy(); reject(e); return; }
+      chunks.push(c);
+    });
+    req.on("end", () => resolveBody(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+  });
+}
+
+async function readJson(req, max) {
+  try { return JSON.parse(await readBody(req, max)); } catch (e) { if (e.code === "TOO_LARGE") throw e; return undefined; }
+}
+
+// /token and /revoke take form bodies (RFC 6749); JSON is accepted too, for clients that send it.
+async function readForm(req) {
+  const type = String(req.headers["content-type"] ?? "");
+  const raw = await readBody(req, FORM_BODY_LIMIT);
+  if (type.includes("application/x-www-form-urlencoded")) return Object.fromEntries(new URLSearchParams(raw));
+  if (type.includes("application/json")) { try { const j = JSON.parse(raw); return j && typeof j === "object" && !Array.isArray(j) ? j : null; } catch { return null; } }
+  return null;
+}
+
+// Serve until killed. `lifeline: "ppid"` exits when the process that started this one goes away,
+// which is how a server started through `ssh localhost` by launchd stops when launchd stops the ssh:
+// with no terminal, nothing else would tell it, and an orphan would hold the port.
+export function serveHttp({ dir, version, port, host = "127.0.0.1", publicUrl, logFile, lifeline, env = process.env }) {
+  const log = logFile ? (line) => appendFileSync(logFile, `${line}\n`, { mode: 0o600 }) : (line) => process.stderr.write(`${line}\n`);
+  const { server, resource } = createMcpHttpServer({ dir, version, publicUrl, env, log });
+  return new Promise((resolveDone, reject) => {
+    server.on("error", reject);
+    server.listen(port, host, () => {
+      log(JSON.stringify({ t: new Date().toISOString(), started: true, listen: `${host}:${server.address().port}`, resource }));
+      if (lifeline === "ppid") {
+        const parent = process.ppid;
+        setInterval(() => { if (process.ppid !== parent) { log(JSON.stringify({ t: new Date().toISOString(), stopped: "parent gone" })); process.exit(0); } }, 2000).unref();
+      }
+    });
+    const stop = () => server.close(() => resolveDone());
+    process.on("SIGTERM", stop);
+    process.on("SIGINT", stop);
+  });
+}