create-evda 0.1.4 → 0.1.6

package/lib/mcp-auth.mjs

@@ -0,0 +1,370 @@
+// The authorization server behind `evda mcp --http` (HQ-1378): OAuth 2.1 for one owner, so the
+// Claude apps can reach a record from Anthropic's cloud and nobody else can.
+//
+// What a claude.ai custom connector needs, and nothing more: RFC 9728 protected resource metadata,
+// RFC 8414 authorization server metadata, RFC 7591 dynamic client registration of public clients,
+// the authorization code grant with PKCE (S256 only), rotating refresh tokens, RFC 7009 revocation.
+//
+// There are no accounts and no passwords. The one person who may approve a client is whoever holds
+// the machine: `evda mcp token --new` prints a one-time owner code there, and the authorization
+// page asks for it. A code works once, expires, and is kept only as its hash.
+//
+// Everything is on disk under ~/.evda/<record id>/mcp-auth/, the directory 0700 and every file
+// 0600, written by rename so a crash cannot leave half a file. Tokens, codes and owner codes are
+// stored as SHA-256 hashes, so reading the state file hands nobody a working credential.
+//
+// The test hooks. Each one breaks exactly one refusal so the tests can be watched failing.
+//   EVDA_MCP_FALSIFY=no-token-check        /mcp answers without a token (read in lib/mcp-http.mjs)
+//   EVDA_MCP_FALSIFY=accept-expired        an expired access token is accepted
+//   EVDA_MCP_FALSIFY=accept-revoked        revocation removes nothing
+//   EVDA_MCP_FALSIFY=skip-pkce             the code verifier is not checked
+//   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)
+
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+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);
+
+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
+export const CODE_TTL_MS = 5 * 60 * 1000;
+export const OWNER_CODE_TTL_MS = 24 * 60 * 60 * 1000;
+export const MAX_CLIENTS = 50;
+export const SCOPE = "evda";
+
+// Where a client may send the owner back. The hosted Claude surfaces (web, desktop, mobile) use the
+// first two; Claude Code uses a loopback redirect on a port it picks each session, so a loopback
+// URI matches with the port ignored (RFC 8252 section 7.3). A registration naming anything else is
+// refused, so an authorization code can only ever travel to Claude or to this machine.
+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]"]);
+
+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));
+
+// A code a person types from one screen into another: 16 characters in four groups, from an alphabet
+// with no 0/O or 1/I/L, about 80 bits.
+const OWNER_ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
+function ownerCodeString() {
+  const bytes = randomBytes(16);
+  let s = "";
+  for (const b of bytes) s += OWNER_ALPHABET[b % OWNER_ALPHABET.length];
+  return s.match(/.{4}/g).join("-");
+}
+const normalizeOwnerCode = (s) => String(s ?? "").toUpperCase().replace(/[^A-Z0-9]/g, "");
+
+// ~/.evda/<record id>/mcp-auth, the same parent as the device key file (HQ-1219).
+export function authDir(evda, env = process.env) {
+  const id = String(evda.manifest?.id ?? evda.manifest?.name ?? "").trim();
+  if (!/^[A-Za-z0-9._-]+$/.test(id)) throw new EvdaError(`REFUSED: this record's evda.json has no usable "id" (got ${JSON.stringify(id)}), so there is no place to keep the remote server's authorization state.`, { code: "NO_RECORD_ID", exit: 2 });
+  return join(env.HOME ?? homedir(), ".evda", id, "mcp-auth");
+}
+
+const EMPTY = () => ({ v: 1, clients: {}, codes: {}, access: {}, refresh: {}, owner: {} });
+
+// The state is one small JSON file. Every change is a read, a change and a rename under a lock
+// directory, so the server and `evda mcp token` on the same machine never lose each other's writes.
+export function openStore(dir) {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodSync(dir, 0o700);
+  const file = join(dir, "state.json");
+  const lock = join(dir, "state.lock");
+  const read = () => {
+    if (!existsSync(file)) return EMPTY();
+    const mode = statSync(file).mode & 0o777;
+    if (mode !== 0o600) throw new EvdaError(`REFUSED: ${file} has mode ${mode.toString(8)}, not 600. Something other than evda wrote it; check it, then chmod 600 it.`, { code: "BAD_MODE", exit: 2 });
+    return { ...EMPTY(), ...JSON.parse(readFileSync(file, "utf8")) };
+  };
+  const write = (state) => {
+    const tmp = join(dir, `state.json.${process.pid}.${Date.now()}.tmp`);
+    writeFileSync(tmp, JSON.stringify(state, null, 1), { mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, file);
+  };
+  const withLock = (fn) => {
+    const deadline = Date.now() + 3000;
+    for (;;) {
+      try { mkdirSync(lock); break; } catch (e) {
+        if (e.code !== "EEXIST") throw e;
+        try { if (Date.now() - statSync(lock).mtimeMs > 10_000) rmSync(lock, { recursive: true, force: true }); } catch { /* gone already */ }
+        if (Date.now() > deadline) throw new EvdaError(`REFUSED: ${lock} has been held for over 3 seconds.`, { code: "LOCKED", exit: 1 });
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+      }
+    }
+    try { return fn(); } finally { rmSync(lock, { recursive: true, force: true }); }
+  };
+  return {
+    dir,
+    file,
+    read,
+    update(fn, now = Date.now()) {
+      return withLock(() => {
+        const s = read();
+        prune(s, now);
+        const out = fn(s);
+        write(s);
+        return out;
+      });
+    },
+  };
+}
+
+function prune(s, now) {
+  for (const k of ["codes", "access", "refresh", "owner"]) {
+    for (const [h, r] of Object.entries(s[k])) if (r.expires <= now) delete s[k][h];
+  }
+}
+
+// ---- the owner code, from `evda mcp token` ----
+
+export function newOwnerCode(store, { ttlMs = OWNER_CODE_TTL_MS, now = Date.now() } = {}) {
+  const code = ownerCodeString();
+  const expires = now + ttlMs;
+  store.update((s) => { s.owner[sha256(normalizeOwnerCode(code))] = { created: now, expires }; }, now);
+  return { code, expires };
+}
+
+// Spend an owner code: true once, for a code that exists and has not expired, and never again.
+export function spendOwnerCode(store, typed, now = Date.now()) {
+  const h = sha256(normalizeOwnerCode(typed));
+  return store.update((s) => {
+    const hit = Object.keys(s.owner).find((k) => timingSafeEqual(Buffer.from(k), Buffer.from(h)));
+    if (!hit) return false;
+    delete s.owner[hit];
+    return true;
+  }, now);
+}
+
+export function burnOwnerCodes(store, now = Date.now()) {
+  return store.update((s) => { const n = Object.keys(s.owner).length; s.owner = {}; return n; }, now);
+}
+
+// Everything off at once: every client, code and token. The connector stops at its next call.
+export function revokeAll(store, now = Date.now()) {
+  return store.update((s) => {
+    const n = { clients: Object.keys(s.clients).length, access: Object.keys(s.access).length, refresh: Object.keys(s.refresh).length, owner: Object.keys(s.owner).length };
+    Object.assign(s, EMPTY());
+    return n;
+  }, now);
+}
+
+export function status(store, now = Date.now()) {
+  const s = store.read();
+  prune(s, now);
+  const live = (o) => Object.values(o).filter((r) => !r.used);
+  return {
+    clients: Object.values(s.clients).map((c) => ({ client_id: c.client_id, client_name: c.client_name ?? null, created: c.created, redirects: c.redirect_uris })),
+    access: live(s.access).length,
+    refresh: live(s.refresh).length,
+    ownerCodes: Object.values(s.owner).map((o) => ({ expires: o.expires })),
+  };
+}
+
+// ---- registration (RFC 7591) ----
+
+const oauthError = (status, error, description) => ({ status, body: { error, error_description: description } });
+
+function isLoopback(u) {
+  return u.protocol === "http:" && LOOPBACK.has(u.hostname.startsWith("[") ? u.hostname : u.hostname);
+}
+
+export function redirectAllowed(uri) {
+  if (HOSTED_REDIRECTS.includes(uri)) return true;
+  try { const u = new URL(uri); return isLoopback(u) && !u.username && !u.password && !u.hash; } catch { return false; }
+}
+
+// Does `asked` match one of the client's registered URIs? Exact, except the port on a loopback URI.
+export function redirectMatches(registered, asked, env = process.env) {
+  if (FALSIFY("skip-redirect-check", env)) return true;
+  if (typeof asked !== "string") return false;
+  if (registered.includes(asked)) return true;
+  let a;
+  try { a = new URL(asked); } catch { return false; }
+  if (!isLoopback(a)) return false;
+  return registered.some((r) => {
+    try {
+      const u = new URL(r);
+      return isLoopback(u) && u.hostname === a.hostname && u.pathname === a.pathname && u.search === a.search;
+    } catch { return false; }
+  });
+}
+
+export function registerClient(store, body, { now = Date.now() } = {}) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return oauthError(400, "invalid_client_metadata", "The registration body must be a JSON object.");
+  const uris = body.redirect_uris;
+  if (!Array.isArray(uris) || uris.length === 0 || uris.length > 10 || !uris.every((u) => typeof u === "string" && u.length < 500)) return oauthError(400, "invalid_redirect_uri", "redirect_uris must be a list of one to ten URIs.");
+  const bad = uris.find((u) => !redirectAllowed(u));
+  if (bad) return oauthError(400, "invalid_redirect_uri", "This server sends authorization codes only to Claude (claude.ai or claude.com) or to a loopback address on this machine.");
+  const grants = body.grant_types ?? ["authorization_code", "refresh_token"];
+  if (!Array.isArray(grants) || grants.some((g) => !["authorization_code", "refresh_token"].includes(g))) return oauthError(400, "invalid_client_metadata", "Only the authorization_code and refresh_token grants are supported.");
+  const types = body.response_types ?? ["code"];
+  if (!Array.isArray(types) || types.some((t) => t !== "code")) return oauthError(400, "invalid_client_metadata", "Only the code response type is supported.");
+  const name = typeof body.client_name === "string" ? body.client_name.slice(0, 80) : null;
+  const client = {
+    client_id: `evda-${newSecret(18)}`,
+    client_id_issued_at: Math.floor(now / 1000),
+    client_name: name,
+    redirect_uris: [...uris],
+    grant_types: ["authorization_code", "refresh_token"],
+    response_types: ["code"],
+    token_endpoint_auth_method: "none",
+    created: now,
+  };
+  store.update((s) => {
+    s.clients[client.client_id] = client;
+    // A connector that is removed and added again registers again; keep the newest fifty.
+    const all = Object.values(s.clients).sort((a, b) => b.created - a.created);
+    for (const old of all.slice(MAX_CLIENTS)) delete s.clients[old.client_id];
+  }, now);
+  const { created, ...out } = client;
+  return { status: 201, body: out };
+}
+
+// ---- authorization (the part before the owner types the code) ----
+
+// Validate an authorization request. Returns { ok: true, req } or { ok: false, redirect?, status,
+// error, description }: an error is sent back to the client's redirect URI only once that URI is
+// known to be the client's own, and shown on the page otherwise (RFC 6749 section 4.1.2.1).
+export function checkAuthorizeRequest(store, q, { resource, env = process.env } = {}) {
+  const client = typeof q.client_id === "string" ? store.read().clients[q.client_id] : null;
+  if (!client) return { ok: false, status: 400, error: "invalid_client", description: "This client is not registered with this server. Remove the connector and add it again." };
+  const registered = client.redirect_uris;
+  const redirect = q.redirect_uri ?? (registered.length === 1 ? registered[0] : undefined);
+  if (!redirectMatches(registered, redirect, env)) return { ok: false, status: 400, error: "invalid_request", description: "The redirect URI does not match the one this client registered." };
+  const back = (error, description) => ({ ok: false, redirect, state: q.state, status: 302, error, description });
+  if (q.response_type !== "code") return back("unsupported_response_type", "Only response_type=code is supported.");
+  if (typeof q.code_challenge !== "string" || !/^[A-Za-z0-9_-]{43,128}$/.test(q.code_challenge)) return back("invalid_request", "A PKCE code_challenge is required.");
+  if (q.code_challenge_method !== "S256") return back("invalid_request", "code_challenge_method must be S256.");
+  if (q.resource !== undefined && !sameResource(q.resource, resource)) return back("invalid_target", "This server is the authorization server for its own /mcp only.");
+  return { ok: true, req: { client_id: client.client_id, client_name: client.client_name, redirect_uri: redirect, code_challenge: q.code_challenge, state: typeof q.state === "string" ? q.state : undefined, scope: SCOPE, resource } };
+}
+
+export function sameResource(asked, resource) {
+  const strip = (s) => String(s).replace(/\/+$/, "");
+  return strip(asked) === strip(resource);
+}
+
+// The owner said yes: mint a code bound to the client, the redirect URI and the challenge.
+export function issueCode(store, req, { now = Date.now() } = {}) {
+  const code = newSecret(32);
+  store.update((s) => {
+    s.codes[sha256(code)] = { client_id: req.client_id, redirect_uri: req.redirect_uri, code_challenge: req.code_challenge, scope: req.scope, resource: req.resource, expires: now + CODE_TTL_MS, used: false, family: null };
+  }, now);
+  return code;
+}
+
+// ---- the token endpoint ----
+
+function mintPair(s, { client_id, scope, resource, family }, now) {
+  const access = newSecret(32);
+  const refresh = newSecret(32);
+  s.access[sha256(access)] = { client_id, scope, resource, family, expires: now + ACCESS_TTL_MS };
+  s.refresh[sha256(refresh)] = { client_id, scope, resource, family, expires: now + REFRESH_TTL_MS, used: false };
+  return { access_token: access, token_type: "Bearer", expires_in: Math.floor(ACCESS_TTL_MS / 1000), refresh_token: refresh, scope };
+}
+
+function revokeFamily(s, family) {
+  if (!family) return;
+  for (const k of ["access", "refresh"]) for (const [h, r] of Object.entries(s[k])) if (r.family === family) delete s[k][h];
+}
+
+const pkceOk = (verifier, challenge, env) => {
+  if (FALSIFY("skip-pkce", env)) return true;
+  if (typeof verifier !== "string" || !/^[A-Za-z0-9._~-]{43,128}$/.test(verifier)) return false;
+  const got = Buffer.from(b64url(createHash("sha256").update(verifier).digest()));
+  const want = Buffer.from(challenge);
+  return got.length === want.length && timingSafeEqual(got, want);
+};
+
+export function token(store, form, { resource, now = Date.now(), env = process.env } = {}) {
+  const grant = form.grant_type;
+  if (grant === "authorization_code") {
+    if (typeof form.code !== "string" || typeof form.client_id !== "string") return oauthError(400, "invalid_request", "code and client_id are required.");
+    return store.update((s) => {
+      const h = sha256(form.code);
+      const c = s.codes[h];
+      if (!c) return oauthError(400, "invalid_grant", "The authorization code is not valid.");
+      if (c.used) {
+        // A code presented twice was intercepted or replayed: whatever the first exchange issued goes.
+        revokeFamily(s, c.family);
+        delete s.codes[h];
+        return oauthError(400, "invalid_grant", "The authorization code was already used.");
+      }
+      if (c.client_id !== form.client_id || !s.clients[c.client_id]) return oauthError(400, "invalid_grant", "The code was issued to a different client.");
+      if (!FALSIFY("skip-redirect-check", env) && form.redirect_uri !== c.redirect_uri) return oauthError(400, "invalid_grant", "redirect_uri does not match the authorization request.");
+      if (!pkceOk(form.code_verifier, c.code_challenge, env)) return oauthError(400, "invalid_grant", "The PKCE code_verifier does not match the code_challenge.");
+      if (form.resource !== undefined && !sameResource(form.resource, resource)) return oauthError(400, "invalid_target", "This server issues tokens for its own /mcp only.");
+      c.used = true;
+      c.family = newSecret(12);
+      return { status: 200, body: mintPair(s, { client_id: c.client_id, scope: c.scope, resource, family: c.family }, now) };
+    }, now);
+  }
+  if (grant === "refresh_token") {
+    if (typeof form.refresh_token !== "string" || typeof form.client_id !== "string") return oauthError(400, "invalid_request", "refresh_token and client_id are required.");
+    return store.update((s) => {
+      const h = sha256(form.refresh_token);
+      const r = s.refresh[h];
+      if (!r) return oauthError(400, "invalid_grant", "The refresh token is not valid.");
+      if (r.client_id !== form.client_id) return oauthError(400, "invalid_grant", "The refresh token was issued to a different client.");
+      if (r.used) {
+        // A rotated-out refresh token came back: someone holds a copy. End the whole connection.
+        revokeFamily(s, r.family);
+        return oauthError(400, "invalid_grant", "The refresh token was already used.");
+      }
+      r.used = true;
+      return { status: 200, body: mintPair(s, { client_id: r.client_id, scope: r.scope, resource, family: r.family }, now) };
+    }, now);
+  }
+  return oauthError(400, "unsupported_grant_type", "Only authorization_code and refresh_token are supported.");
+}
+
+// RFC 7009: always 200, whether or not the token existed. Revoking either half ends the connection.
+export function revoke(store, form, { now = Date.now(), env = process.env } = {}) {
+  if (FALSIFY("accept-revoked", env)) return { status: 200, body: {} };
+  if (typeof form.token !== "string") return oauthError(400, "invalid_request", "token is required.");
+  store.update((s) => {
+    const h = sha256(form.token);
+    const hit = s.access[h] ?? s.refresh[h];
+    if (hit && (form.client_id === undefined || form.client_id === hit.client_id)) revokeFamily(s, hit.family);
+  }, now);
+  return { status: 200, body: {} };
+}
+
+// Is this bearer token good for this resource now? Returns the token's record, or null.
+export function verifyAccess(store, bearer, { resource, now = Date.now(), env = process.env } = {}) {
+  if (typeof bearer !== "string" || bearer.length < 20) return null;
+  const s = store.read();
+  const r = s.access[sha256(bearer)];
+  if (!r) return null;
+  if (r.expires <= now && !FALSIFY("accept-expired", env)) return null;
+  if (!sameResource(r.resource, resource)) return null;
+  return r;
+}
+
+// ---- metadata ----
+
+export function authServerMetadata(base) {
+  return {
+    issuer: base,
+    authorization_endpoint: `${base}/authorize`,
+    token_endpoint: `${base}/token`,
+    registration_endpoint: `${base}/register`,
+    revocation_endpoint: `${base}/revoke`,
+    response_types_supported: ["code"],
+    grant_types_supported: ["authorization_code", "refresh_token"],
+    code_challenge_methods_supported: ["S256"],
+    token_endpoint_auth_methods_supported: ["none"],
+    revocation_endpoint_auth_methods_supported: ["none"],
+    scopes_supported: [SCOPE, "offline_access"],
+  };
+}
+
+export function protectedResourceMetadata(base, resource) {
+  return { resource, authorization_servers: [base], scopes_supported: [SCOPE], bearer_methods_supported: ["header"], resource_name: "EVDA" };
+}