@getfootgun/keys 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# @getfootgun/keys
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Footgun Keys: guided API key setup for your Mac. Keys go to your Keychain, and only to an env file you ask for.
+
+Mac only. Needs Node 20 or newer.
+
+## Install
+
+    npx @getfootgun/keys setup
+
+Setup installs a stable copy of the helper, registers it with Chrome and with a daily check, and asks for your Footgun API key. Create one free at https://getfootgun.com/account.
+
+## Commands
+
+    footgun-keys <setup|mcp|native-host|health|protect>
+
+- `setup`: one-time install and registration, described above.
+- `mcp`: runs the MCP server that Claude Code and Cursor talk to. Connect it with `claude mcp add footgun-keys -- npx -y @getfootgun/keys mcp`, or add the same command under MCP servers in Cursor.
+- `native-host`: the bridge the Chrome extension uses to hand a key to the helper. Chrome starts it; you do not run it yourself.
+- `health`: the daily key check that launchd runs at 9:30. It tells you when a saved key stops working.
+- `protect`: adds a Claude Code rule to the current project so Claude Code's Read tool will not open your env files (shell commands still can). It asks first.
+
+## What is stored where
+
+- Your Mac Keychain, service `footgun-keys`: every key you capture, and your Footgun API key. Key values live nowhere else except an env file you ask for.
+- The support folder, `~/Library/Application Support/Footgun Keys/`: the installed helper, the two launcher scripts, and session and guide files. It holds names and statuses only, never key values.
+- Chrome and launchd: a native host manifest in Chrome's NativeMessagingHosts folder, and a launch agent at `~/Library/LaunchAgents/com.getfootgun.keys.health.plist`.
+- Never on Footgun's servers: your keys are never sent to Footgun. The only thing the helper sends is your Footgun API key, to check your plan.
+
+## Release checklist
+
+The Claude Code plugin does not start this helper until all of these are done, in order:
+
+1. Publish the Footgun Keys extension to the Chrome Web Store.
+2. Add the store extension id to `shared/extension-id.json` (`{ "ids": ["<store id>"] }`).
+3. `npm publish` this package as `@getfootgun/keys`.
+4. Add the footgun-keys stdio entry to `plugin/footgun/.mcp.json` under `mcpServers`:
+
+       "footgun-keys": { "command": "npx", "args": ["-y", "@getfootgun/keys", "mcp"] }
+
+   Then bump `version` in `plugin/footgun/.claude-plugin/plugin.json`.

package/bin/footgun-keys.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { dispatch } from "../lib/dispatch.mjs";
+
+process.exit(await dispatch(process.argv.slice(2)));

package/lib/check.d.mts

@@ -0,0 +1,3 @@
+import type { IndexEntry } from "./vault.mjs";
+export function groupByProviderLabel(entries: IndexEntry[]): IndexEntry[][];
+export function healthRecord(t: { ok: boolean; reason?: string }, now: () => Date): NonNullable<IndexEntry["health"]>;

package/lib/check.mjs

@@ -0,0 +1,14 @@
+// Shared by keys_check and the daily health check.
+export function groupByProviderLabel(entries) {
+  const groups = new Map();
+  for (const e of entries) {
+    const k = `${e.provider}\u0000${e.label}`;
+    if (!groups.has(k)) groups.set(k, []);
+    groups.get(k).push(e);
+  }
+  return [...groups.values()];
+}
+
+export function healthRecord(t, now) {
+  return { ok: t.ok, ...(t.ok ? {} : { reason: t.reason ?? "unexpected" }), checkedAt: now().toISOString() };
+}

package/lib/dispatch.d.mts

@@ -0,0 +1,2 @@
+export const COMMANDS: string[];
+export function dispatch(argv: string[], libDir?: string): Promise<number>;

package/lib/dispatch.mjs

@@ -0,0 +1,23 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const COMMANDS = ["setup", "mcp", "native-host", "health", "protect"];
+const LIB = fileURLToPath(new URL(".", import.meta.url));
+
+// "Not built yet" means the subcommand's own module file is absent. Any error thrown while loading
+// an existing module (such as a missing dependency) propagates.
+export async function dispatch(argv, libDir = LIB) {
+  const [cmd, ...args] = argv;
+  if (!COMMANDS.includes(cmd)) {
+    console.error(`Usage: footgun-keys <${COMMANDS.join("|")}> [args]`);
+    return 2;
+  }
+  const file = join(libDir, `${cmd}.mjs`);
+  if (!existsSync(file)) {
+    console.error("not built yet");
+    return 2;
+  }
+  const mod = await import(file);
+  return (await mod.run(args)) ?? 0;
+}

package/lib/envfile.d.mts

@@ -0,0 +1,6 @@
+export function envFileFor(projectPath: string): Promise<string>;
+export function writeEnv(
+  projectPath: string,
+  vars: { name: string; value: string }[],
+  opts?: { git?: (args: string[]) => Promise<string> },
+): Promise<{ file: string; addedGitignore: boolean }>;

package/lib/envfile.mjs

@@ -0,0 +1,101 @@
+import { readFile, writeFile, chmod, stat } from "node:fs/promises";
+import { join, dirname, resolve } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const realGit = async (args) => (await execFileAsync("git", args)).stdout;
+
+async function readOrNull(file) {
+  try { return await readFile(file, "utf8"); } catch (e) { if (e.code === "ENOENT") return null; throw e; }
+}
+
+export async function envFileFor(projectPath) {
+  const text = await readOrNull(join(projectPath, "package.json"));
+  if (text === null) return ".env";
+  let pkg;
+  try { pkg = JSON.parse(text); } catch { return ".env"; }
+  const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+  return "next" in deps || "vite" in deps ? ".env.local" : ".env";
+}
+
+// Bare when only [A-Za-z0-9_./:+-]; otherwise single-quoted with no escaping (dotenv reads
+// single-quoted values literally and dotenv-expand does not expand them). Values with a single
+// quote or a newline cannot be represented, so they are refused (the value is never echoed).
+function formatValue(value) {
+  if (/^[A-Za-z0-9_./:+-]*$/.test(value)) return value;
+  if (/[\r\n]/.test(value)) throw new Error("A key value cannot contain a newline.");
+  if (value.includes("'")) throw new Error("A key value cannot contain a single quote.");
+  return `'${value}'`;
+}
+
+// Every line that assigns name (indented, or with "export ") is replaced: the first keeps its place
+// (and its "export " with the indent before it), later ones are dropped with their line ending.
+// All other bytes stay as they were.
+function upsert(text, name, value) {
+  const line = `${name}=${formatValue(value)}`;
+  const assigns = new RegExp(`^([ \\t]*export[ \\t]+)?[ \\t]*${name}[ \\t]*=`);
+  const parts = text.split(/(\r?\n)/); // content, eol, content, eol, ... (last is content)
+  const lines = [];
+  for (let i = 0; i < parts.length; i += 2) lines.push({ content: parts[i], eol: parts[i + 1] ?? "" });
+  let found = false;
+  const out = [];
+  for (const l of lines) {
+    if (!assigns.test(l.content)) { out.push(l); continue; }
+    if (!found) { out.push({ content: (assigns.exec(l.content)[1] ?? "") + line, eol: l.eol }); found = true; continue; }
+    // A dropped last line takes the line ending before it, so no stray newline is left.
+    if (l.eol === "" && out.length > 0) out[out.length - 1].eol = "";
+  }
+  if (found) return out.map((l) => l.content + l.eol).join("");
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  if (text !== "" && !/\n$/.test(text)) text += eol;
+  return `${text}${line}${eol}`;
+}
+
+const IGNORING = (file) => new Set([file, `/${file}`, ".env*", ".env.local*", "/.env*", "/.env.local*",
+  ...(file.endsWith(".local") ? [".env*.local", "*.local"] : [])]);
+
+// True when projectPath or a folder above it has a .git entry (a folder, or a file for a worktree).
+async function underGit(projectPath) {
+  for (let dir = resolve(projectPath); ; dir = dirname(dir)) {
+    try { await stat(join(dir, ".git")); return true; } catch { /* keep walking */ }
+    if (dirname(dir) === dir) return false;
+  }
+}
+
+// Inside a git work tree git itself decides (negations, parent folders, nested rules); outside one,
+// a plain pattern match on the project's .gitignore. Git is not run at all without a .git above.
+async function isIgnored(projectPath, file, text, git) {
+  let inside = false;
+  if (await underGit(projectPath)) try { inside = (await git(["-C", projectPath, "rev-parse", "--is-inside-work-tree"])).trim() === "true"; } catch { /* not a repo, or no git */ }
+  if (inside) {
+    try { await git(["-C", projectPath, "check-ignore", "-q", file]); return true; } catch { return false; }
+  }
+  const ok = IGNORING(file);
+  return text.split(/\r?\n/).some((l) => ok.has(l.trim()));
+}
+
+async function ensureIgnored(projectPath, file, git) {
+  const gi = join(projectPath, ".gitignore");
+  const text = (await readOrNull(gi)) ?? "";
+  if (await isIgnored(projectPath, file, text, git)) return false;
+  const add = `\n# Footgun Keys\n${file}\n`;
+  await writeFile(gi, text === "" ? add.slice(1) : text + add);
+  return true;
+}
+
+export async function writeEnv(projectPath, vars, { git = realGit } = {}) {
+  for (const { value } of vars) formatValue(value); // refuse a bad value before touching any file
+  const file = await envFileFor(projectPath);
+  // Ignore first, so a key never sits in a file git could pick up.
+  const addedGitignore = await ensureIgnored(projectPath, file, git);
+  const full = join(projectPath, file);
+  const prior = await readOrNull(full);
+  const existed = prior !== null;
+  let text = prior ?? "";
+  for (const { name, value } of vars) text = upsert(text, name, value);
+  // writeFile on an existing file keeps its mode; a new file gets 0600 (umask can only tighten it).
+  await writeFile(full, text, { mode: 0o600 });
+  if (!existed) await chmod(full, 0o600);
+  return { file, addedGitignore };
+}

package/lib/health.d.mts

@@ -0,0 +1,17 @@
+import type { Vault } from "./vault.mjs";
+import type { Server } from "./server.mjs";
+
+export function macNotify(
+  title: string,
+  body: string,
+  exec?: (file: string, args: string[], cb: (e: Error | null) => void) => unknown,
+): Promise<void>;
+export function runHealth(deps: {
+  vault: Vault;
+  server: Server;
+  notify: (title: string, body: string) => Promise<void>;
+  fetch?: typeof fetch;
+  now?: () => Date;
+  retryDelayMs?: number;
+}): Promise<{ checked: number; failing: string[] }>;
+export function run(): Promise<number>;

package/lib/health.mjs

@@ -0,0 +1,100 @@
+import { execFile } from "node:child_process";
+import { keychainStore, openVault } from "./vault.mjs";
+import { makeServer } from "./server.mjs";
+import { runTest } from "./testcall.mjs";
+import { groupByProviderLabel, healthRecord } from "./check.mjs";
+
+const TITLE = "Footgun Keys";
+// Title and body travel as argv, never inside the script text.
+const SCRIPT = "on run argv\ndisplay notification (item 2 of argv) with title (item 1 of argv)\nend run";
+
+export function macNotify(title, body, exec = execFile) {
+  return new Promise((resolve, reject) => exec("osascript", ["-e", SCRIPT, title, body], (e) => (e ? reject(e) : resolve())));
+}
+
+// The env var a failed test is about: the one the test call authenticates with.
+function testedVar(guide, fallback) {
+  const a = guide.test?.auth;
+  return a?.envVar ?? a?.userEnvVar ?? fallback;
+}
+
+// Test each provider and label group once. Returns the test results without recording them.
+async function testGroups(groups, vault, server, fetchFn) {
+  const results = [];
+  const unavailable = [];
+  for (const list of groups) {
+    const { provider, label } = list[0];
+    const g = await server.guide(provider);
+    if (!g.ok) { unavailable.push(provider); continue; }
+    const values = {};
+    for (const c of g.guide.captures) {
+      const v = await vault.get(provider, label, c.envVar);
+      if (v !== null) values[c.envVar] = v;
+    }
+    results.push({ list, guide: g.guide, t: await runTest(g.guide, values, { fetch: fetchFn }) });
+  }
+  return { results, unavailable };
+}
+
+const allUnreachable = (results) => results.length > 0 && results.every((r) => r.t.reason === "unreachable");
+
+// Test every stored key once per provider and label. Silence must always mean healthy, so a check that
+// cannot run notifies too. Notification text carries env var names and reasons only.
+export async function runHealth({ vault, server, notify, fetch: fetchFn, now = () => new Date(), retryDelayMs = 60000 }) {
+  try {
+    const ent = await server.entitlement();
+    if (ent === null) {
+      // Never set up: nothing to check. A key that exists but gets no entitlement must not go quiet.
+      if (!(await server.apiKey())) return { checked: 0, failing: [] };
+      throw new Error("could not confirm your Footgun plan (offline, or the Footgun API key was not accepted)");
+    }
+    if (ent.health !== true) return { checked: 0, failing: [] };
+
+    const groups = groupByProviderLabel(await vault.list());
+
+    // Every test unreachable means this Mac is offline, not that every key broke: wait, retry once,
+    // and if still offline keep the old health records.
+    let run = await testGroups(groups, vault, server, fetchFn);
+    if (allUnreachable(run.results)) {
+      await new Promise((r) => setTimeout(r, retryDelayMs));
+      run = await testGroups(groups, vault, server, fetchFn);
+      if (allUnreachable(run.results)) throw new Error("no internet connection.");
+    }
+
+    let checked = 0;
+    const failures = [];
+    for (const { list, guide, t } of run.results) {
+      const health = healthRecord(t, now);
+      for (const e of list) await vault.setHealth(e.provider, e.label, e.envVar, health);
+      checked += list.length;
+      if (!t.ok) failures.push({ name: testedVar(guide, list[0].envVar), reason: health.reason, provider: guide.name });
+    }
+
+    if (failures.length === 1) {
+      const f = failures[0];
+      await notify(TITLE, `${f.name} stopped working (${f.reason}). Run the ${f.provider} guide again.`);
+    } else if (failures.length > 1) {
+      await notify(TITLE, `${failures.length} keys stopped working: ${failures.map((f) => f.name).join(", ")}`);
+    }
+    if (run.unavailable.length > 0) throw new Error(`could not load the guide for ${run.unavailable.join(", ")}`);
+    return { checked, failing: failures.map((f) => f.name) };
+  } catch (e) {
+    const msg = e instanceof Error && e.message ? e.message : "unknown error";
+    try {
+      await notify(TITLE, `Footgun Keys could not run today's key check: ${msg}`);
+    } catch {
+      // Nothing more can be done if notifying itself fails; the original error still surfaces.
+    }
+    throw e;
+  }
+}
+
+export async function run() {
+  const store = keychainStore();
+  try {
+    await runHealth({ vault: openVault({ store }), server: makeServer({ store }), notify: macNotify });
+    return 0;
+  } catch {
+    return 1;
+  }
+}

package/lib/launchd.d.mts

@@ -0,0 +1 @@
+export function launchdPlist(launcherPath: string): string;

package/lib/launchd.mjs

@@ -0,0 +1,28 @@
+const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+// Daily 9:30 run of "footgun-keys health". Writing and loading this file is the caller's job.
+export function launchdPlist(launcherPath) {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.getfootgun.keys.health</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${esc(launcherPath)}</string>
+    <string>health</string>
+  </array>
+  <key>StartCalendarInterval</key>
+  <dict>
+    <key>Hour</key>
+    <integer>9</integer>
+    <key>Minute</key>
+    <integer>30</integer>
+  </dict>
+  <key>RunAtLoad</key>
+  <false/>
+</dict>
+</plist>
+`;
+}

package/lib/mcp.d.mts

@@ -0,0 +1,24 @@
+import type { Vault } from "./vault.mjs";
+import type { Server } from "./server.mjs";
+
+export type ToolResult = { content: { type: "text"; text: string }[]; isError?: boolean };
+export const INSTRUCTIONS: string;
+export const SPECS: Record<"keys_list" | "keys_guides" | "keys_write_env" | "keys_request" | "keys_check", { description: string; inputSchema: import("zod").ZodType }>;
+export function buildTools(deps: {
+  vault: Vault;
+  server: Server;
+  openUrl: (url: string) => Promise<void>;
+  home?: string;
+  now?: () => Date;
+  waitMs?: number;
+  fetch?: typeof fetch;
+}): {
+  keys_list(): Promise<ToolResult>;
+  keys_guides(): Promise<ToolResult>;
+  keys_write_env(args: { project_path: string; env_vars: string[] }): Promise<ToolResult>;
+  keys_request(args: { provider: string; project_path: string; env_vars?: string[]; label?: string; session?: string }): Promise<ToolResult>;
+  keys_check(args?: { env_var?: string }): Promise<ToolResult>;
+};
+export function toolsFor(platform: string, makeDeps: () => Parameters<typeof buildTools>[0]): ReturnType<typeof buildTools>;
+export function runMcp(): Promise<void>;
+export function run(): Promise<number>;

package/lib/mcp.mjs

@@ -0,0 +1,271 @@
+import { execFile } from "node:child_process";
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/server";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { keychainStore, openVault } from "./vault.mjs";
+import { makeServer } from "./server.mjs";
+import { writeEnv } from "./envfile.mjs";
+import { runTest } from "./testcall.mjs";
+import { createSession, readSession, isExpired } from "./sessions.mjs";
+import { SITE } from "./paths.mjs";
+import { groupByProviderLabel, healthRecord } from "./check.mjs";
+import { isProtected } from "./protect.mjs";
+import { LABEL_RE, FREE_GUIDES } from "../shared/contract.mjs";
+
+// Every result here carries names, statuses and messages. A key value is never read into a result.
+export const INSTRUCTIONS =
+  "When a project needs a third-party API key, call keys_request instead of asking the user to paste it. Tool results never contain key values.";
+
+const NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const PROVIDER_RE = /^[a-z0-9][a-z0-9-]{0,63}$/; // the server's guide slug rule
+const BAD_PROVIDER = "That is not a valid guide name. Use a slug such as stripe or openai.";
+const BAD_LABEL = "A label can use letters, numbers, spaces, dots, dashes and underscores, up to 64 characters.";
+const PROTECT_TIP = 'Run "npx @getfootgun/keys protect" in this project so Claude Code\'s Read tool will not open it.';
+
+const reply = (t, isError = false) => ({ content: [{ type: "text", text: t }], ...(isError ? { isError: true } : {}) });
+const proText = () => `This needs Footgun Pro. ${SITE()}/#pricing`;
+const SETUP_TEXT = "Run npx @getfootgun/keys setup to connect your Footgun account (it is free).";
+const UNCONFIRMED_TEXT = "Footgun Keys could not confirm your Footgun plan (offline, or your API key was not accepted). Check your connection or run npx @getfootgun/keys setup again.";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// After an env file is written: say when .gitignore changed, and show the protect tip until the project denies reads.
+async function writeNotes(wrote, projectPath) {
+  if (!wrote) return [];
+  const lines = wrote.addedGitignore ? [`Added ${wrote.file} to .gitignore.`] : [];
+  if (!(await isProtected(projectPath))) lines.push(PROTECT_TIP);
+  return lines;
+}
+
+export function buildTools({ vault, server, openUrl, home, now = () => new Date(), waitMs = 120000, fetch: fetchFn }) {
+  // Why a paid tool cannot run, or null when it can. Only a confirmed plan that lacks it gets the Pro message.
+  async function planBlock(tool, slug) {
+    const ent = await server.entitlement();
+    if (ent === null) return (await server.apiKey()) === null ? SETUP_TEXT : UNCONFIRMED_TEXT;
+    if (!ent.tools.includes(tool)) return proText();
+    if (slug !== undefined && !FREE_GUIDES.includes(slug) && ent.allGuides !== true) return proText();
+    return null;
+  }
+  async function guideAllowed(slug) {
+    if (FREE_GUIDES.includes(slug)) return true;
+    return (await server.entitlement())?.allGuides === true;
+  }
+  // Test with every stored value the guide captures; the values stay inside this function.
+  async function testGuide(guide, provider, label) {
+    const values = {};
+    for (const c of guide.captures) {
+      const v = await vault.get(provider, label, c.envVar);
+      if (v !== null) values[c.envVar] = v;
+    }
+    return runTest(guide, values, { fetch: fetchFn });
+  }
+  const testLine = (t) => (!t ? "Test call: skipped." : t.ok ? "Test call: ok." : `Test call: failed (${t.reason ?? "unexpected"}).`);
+
+  async function savedText(r, projectPath) {
+    const lines = [`Saved ${r.saved.join(", ")}.`];
+    if (r.wrote) lines.push(`Wrote to ${r.wrote.file} in the project.`);
+    lines.push(testLine(r.test));
+    lines.push(...(await writeNotes(r.wrote, projectPath)));
+    return lines.join("\n");
+  }
+
+  const tools = {
+    async keys_list() {
+      const entries = await vault.list();
+      if (entries.length === 0) return reply("No keys saved yet.");
+      return reply(entries.map((e) => {
+        const status = e.health === null ? "not checked" : e.health.ok ? "ok" : `failing: ${e.health.reason ?? "unknown"}`;
+        return `${e.envVar} (${e.provider}, ${e.label}): ${status}; used in ${e.projects.length} projects`;
+      }).join("\n"));
+    },
+
+    async keys_guides() {
+      const r = await server.guides();
+      if (!r.ok) return reply(`Could not load the guide list: ${r.error}`, true);
+      return reply(r.guides.map((g) => `${g.name} (${g.slug}): ${g.tier === "pro" ? "Pro" : "Free"}, ${g.status}`).join("\n"));
+    },
+
+    async keys_write_env({ project_path, env_vars }) {
+      const bad = env_vars.find((n) => !NAME_RE.test(n));
+      if (bad !== undefined) return reply("One of the names is not a valid env var name.", true);
+      const entries = await vault.list();
+      const found = [];
+      const missing = [];
+      for (const name of env_vars) {
+        const hits = entries.filter((e) => e.envVar === name).sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+        const value = hits[0] ? await vault.get(hits[0].provider, hits[0].label, name) : null;
+        if (value === null) missing.push(name);
+        else found.push({ name, value, entry: hits[0] });
+      }
+      const lines = [];
+      let wrote = null;
+      if (found.length > 0) {
+        try {
+          wrote = await writeEnv(project_path, found.map(({ name, value }) => ({ name, value })));
+        } catch (e) {
+          return reply(e instanceof Error && e.message ? e.message : "Could not write the env file.", true);
+        }
+        for (const f of found) await vault.addProject(f.entry.provider, f.entry.label, f.name, project_path);
+        lines.push(`Wrote ${found.map((f) => f.name).join(", ")} to ${wrote.file}.`);
+      }
+      for (const m of missing) lines.push(`${m}: missing (nothing written)`);
+      lines.push(...(await writeNotes(wrote, project_path)));
+      return reply(lines.join("\n"));
+    },
+
+    async keys_request({ provider, project_path, env_vars, label = "default", session }) {
+      if (typeof provider !== "string" || !PROVIDER_RE.test(provider)) return reply(BAD_PROVIDER, true);
+      if (typeof label !== "string" || !LABEL_RE.test(label)) return reply(BAD_LABEL, true);
+      const blocked = await planBlock("keys_request", provider);
+      if (blocked) return reply(blocked);
+      if (env_vars?.some((n) => !NAME_RE.test(n))) return reply("One of the names is not a valid env var name.", true);
+
+      if (session !== undefined) {
+        const s = await readSession(session, home);
+        if (!s) return reply("That guide session was not found. Call keys_request without a session to start again.", true);
+        if (isExpired(s, now())) return reply("That guide session expired.");
+        return waitFor(s.id);
+      }
+
+      if (env_vars?.length === 0) return reply("Name at least one env var, or leave env_vars out to get everything the guide captures.", true);
+      const g = await server.guide(provider);
+      if (!g.ok && !env_vars) return reply(`Could not load the ${provider} guide: ${g.error}`, true);
+      if (g.ok && env_vars) {
+        const captured = g.guide.captures.map((c) => c.envVar);
+        const extra = env_vars.filter((n) => !captured.includes(n));
+        if (extra.length) return reply(`The ${provider} guide does not capture ${extra.join(", ")}. It captures ${captured.join(", ")}.`, true);
+      }
+      const needed = env_vars ?? g.guide.captures.map((c) => c.envVar);
+
+      const values = [];
+      for (const name of needed) {
+        const v = await vault.get(provider, label, name);
+        if (v === null) break;
+        values.push({ name, value: v });
+      }
+      if (values.length === needed.length && needed.length > 0) {
+        let wrote;
+        try {
+          wrote = await writeEnv(project_path, values);
+        } catch (e) {
+          return reply(e instanceof Error && e.message ? e.message : "Could not write the env file.", true);
+        }
+        for (const name of needed) await vault.addProject(provider, label, name, project_path);
+        const test = g.ok ? await testGuide(g.guide, provider, label) : undefined;
+        return reply(await savedText({ saved: needed, wrote, test }, project_path));
+      }
+
+      const s = await createSession({ provider, envVars: needed, projectPath: project_path, label, home });
+      const url = `${SITE()}/keys/go/${provider}?s=${s.id}`;
+      try {
+        await openUrl(url);
+      } catch {
+        return reply(`Could not open Chrome. Open ${url} yourself, then call keys_request again with session "${s.id}".`, true);
+      }
+      return waitFor(s.id);
+    },
+
+    async keys_check({ env_var } = {}) {
+      const blocked = await planBlock("keys_check");
+      if (blocked) return reply(blocked);
+      const entries = (await vault.list()).filter((e) => env_var === undefined || e.envVar === env_var);
+      if (entries.length === 0) return reply(env_var ? `${env_var}: missing` : "No keys saved yet.");
+      const groups = groupByProviderLabel(entries);
+      const lines = [];
+      for (const list of groups) {
+        const { provider, label } = list[0];
+        const mark = (e, s) => `${e.envVar} (${e.provider}, ${e.label}): ${s}`;
+        if (!(await guideAllowed(provider))) { lines.push(...list.map((e) => mark(e, "needs Footgun Pro"))); continue; }
+        const g = await server.guide(provider);
+        if (!g.ok) { lines.push(...list.map((e) => mark(e, "not checked (guide unavailable)"))); continue; }
+        const t = await testGuide(g.guide, provider, label);
+        const health = healthRecord(t, now);
+        for (const e of list) {
+          await vault.setHealth(e.provider, e.label, e.envVar, health);
+          lines.push(mark(e, t.ok ? "ok" : `failing: ${health.reason}`));
+        }
+      }
+      return reply(lines.join("\n"));
+    },
+  };
+
+  // Poll the session file once a second, up to waitMs.
+  async function waitFor(id) {
+    const deadline = Date.now() + waitMs;
+    for (;;) {
+      const s = await readSession(id, home);
+      if (!s) return reply("That guide session was not found. Call keys_request without a session to start again.", true);
+      if (isExpired(s, now())) return reply("That guide session expired.");
+      if (s.status === "done" && s.result) return reply(await savedText(s.result, s.projectPath));
+      if (s.status === "failed") return reply(`The guide could not finish: ${s.result?.error ?? "unknown error"}`, true);
+      const left = deadline - Date.now();
+      if (left <= 0) break;
+      await sleep(Math.min(1000, left));
+    }
+    return reply(`Still waiting for the guide in Chrome. Call keys_request again with session "${id}".`);
+  }
+
+  return Object.fromEntries(Object.entries(tools).map(([name, fn]) => [name, async (args) => {
+    try {
+      return await fn(args ?? {});
+    } catch {
+      return reply("Something went wrong in Footgun Keys.", true);
+    }
+  }]));
+}
+
+const names = z.array(z.string().regex(NAME_RE, "Use a plain env var name like STRIPE_SECRET_KEY."));
+
+export const SPECS = {
+  keys_list: { description: "List the saved keys by env var name, provider, label and health. Never shows values.", inputSchema: z.object({}) },
+  keys_guides: { description: "List the available setup guides and whether each is Free or Pro.", inputSchema: z.object({}) },
+  keys_write_env: {
+    description: "Write already-saved keys into the project's env file (git-ignored). Names missing from the vault are reported, not written.",
+    inputSchema: z.object({ project_path: z.string().describe("Absolute path of the project folder."), env_vars: names.describe("Env var names to write.") }),
+  },
+  keys_request: {
+    description: "Get a provider's API key into a project. Writes it from the Keychain if saved, otherwise opens a guided setup in Chrome and waits. If it returns a session, call it again with that session.",
+    inputSchema: z.object({
+      provider: z.string().regex(PROVIDER_RE, BAD_PROVIDER).describe("Guide slug, such as stripe or openai."),
+      project_path: z.string().describe("Absolute path of the project folder."),
+      env_vars: names.optional().describe("Env var names needed. Defaults to all the guide captures."),
+      label: z.string().regex(LABEL_RE, BAD_LABEL).optional().describe("Name for this key set. Defaults to default."),
+      session: z.string().optional().describe("Session id from an earlier keys_request that was still waiting."),
+    }),
+  },
+  keys_check: {
+    description: "Test saved keys against their provider and record whether each still works.",
+    inputSchema: z.object({ env_var: z.string().optional().describe("Check just this env var. Defaults to all saved keys.") }),
+  },
+};
+
+function openUrl(url) {
+  return new Promise((resolve, reject) => execFile("open", [url], (e) => (e ? reject(e) : resolve())));
+}
+
+// Off macOS the server still answers initialize and tools/list (so a plugin that starts it does not
+// crash), but every tool call says Footgun Keys is Mac only.
+export function toolsFor(platform, makeDeps) {
+  if (platform !== "darwin") {
+    return Object.fromEntries(Object.keys(SPECS).map((name) => [name, async () => reply("Footgun Keys runs on macOS for now.")]));
+  }
+  return buildTools(makeDeps());
+}
+
+export async function runMcp() {
+  const tools = toolsFor(process.platform, () => {
+    const store = keychainStore();
+    return { vault: openVault({ store }), server: makeServer({ store }), openUrl };
+  });
+  const mcp = new McpServer({ name: "footgun-keys", version: "0.1.0" }, { instructions: INSTRUCTIONS });
+  for (const [name, spec] of Object.entries(SPECS)) {
+    mcp.registerTool(name, { title: name, ...spec }, async (args) => tools[name](args));
+  }
+  const transport = new StdioServerTransport();
+  const closed = new Promise((resolve) => { transport.onclose = resolve; });
+  await mcp.connect(transport);
+  await closed;
+}
+
+export async function run() {
+  await runMcp();
+  return 0;
+}