@getfootgun/keys 0.0.0-stage → 0.2.0-rc.1

package/README.md

@@ -1,3 +1,52 @@
-# 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 or Windows PC. Keys go to your Mac Keychain or Windows Credential Manager, and only to an env file you ask for.
+
+Works on macOS and Windows. 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` (on Windows: `claude mcp add footgun-keys -- cmd /c 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 at 9:30, run by launchd on Mac and by Task Scheduler on Windows. 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
+
+On a Mac:
+
+- 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`.
+
+On Windows:
+
+- Windows Credential Manager, in entries whose names include `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, `%LOCALAPPDATA%\Footgun Keys`: the installed helper, the two launcher scripts (`footgun-keys.cmd` and `native-host.cmd`), and session and guide files. It holds names and statuses only, never key values.
+- Chrome and Task Scheduler: a native host manifest in the support folder, registered under `HKCU\Software\Google\Chrome\NativeMessagingHosts\com.getfootgun.keys`, and a Task Scheduler task named "Footgun Keys health" (defined in `health-task.xml` in the support folder). The task runs without a window, on battery too, and catches up after a missed 9:30. Both are per user and need no admin rights.
+
+On both:
+
+- 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, importModule?: (specifier: string) => Promise<{ run(args: string[]): unknown }>): Promise<number>;

package/lib/dispatch.mjs

@@ -0,0 +1,24 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } 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. The module is imported by file: URL,
+// since Windows rejects a plain absolute path (C:\...) as an ESM specifier.
+export async function dispatch(argv, libDir = LIB, importModule = (specifier) => import(specifier)) {
+  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 importModule(pathToFileURL(file).href);
+  return (await mod.run(args)) ?? 0;
+}

package/lib/envfile.d.mts

@@ -0,0 +1,10 @@
+export function envFileFor(projectPath: string): Promise<string>;
+export function writeEnv(
+  projectPath: string,
+  vars: { name: string; value: string }[],
+  opts?: {
+    git?: (args: string[]) => Promise<string>;
+    platform?: NodeJS.Platform;
+    chmodFn?: (path: string, mode: number) => Promise<void>;
+  },
+): Promise<{ file: string; addedGitignore: boolean }>;

package/lib/envfile.mjs

@@ -0,0 +1,104 @@
+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, platform = process.platform, chmodFn = chmod } = {}) {
+  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) {
+    // Windows has no POSIX modes, so a chmod failure there is harmless; elsewhere it must surface.
+    try { await chmodFn(full, 0o600); } catch (e) { if (platform !== "win32") throw e; }
+  }
+  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,98 @@
+import { keychainStore, openVault } from "./vault.mjs";
+import { makeServer } from "./server.mjs";
+import { runTest } from "./testcall.mjs";
+import { groupByProviderLabel, healthRecord } from "./check.mjs";
+import { notify } from "./platform.mjs";
+
+const TITLE = "Footgun Keys";
+// Kept for existing callers: the Mac notification, with an optional exec.
+export function macNotify(title, body, exec) {
+  return notify(title, body, { platform: "darwin", exec });
+}
+
+// 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 });
+    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,25 @@
+import type { Vault } from "./vault.mjs";
+import type { Server } from "./server.mjs";
+
+export type ToolResult = { content: { type: "text"; text: string }[]; isError?: boolean };
+export const SERVER_INFO: { name: string; version: string };
+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>;