@getfootgun/keys 0.0.0-stage → 0.1.0

package/lib/native-host.mjs

@@ -0,0 +1,7 @@
+import { keychainStore } from "./vault.mjs";
+import { runNativeHost } from "./native.mjs";
+
+// Chrome passes the caller origin first (chrome-extension://<id>/), and on some platforms a window id after it.
+export async function run(args) {
+  return runNativeHost(process.stdin, process.stdout, { store: keychainStore(), origin: args[0] });
+}

package/lib/native.d.mts

@@ -0,0 +1,15 @@
+import type { Readable, Writable } from "node:stream";
+import type { KeyStore } from "./vault.mjs";
+
+export interface HostDeps {
+  store: KeyStore;
+  home?: string;
+  fetch?: typeof fetch;
+  now?: () => Date;
+  origin?: string;
+  extensionIds?: string[];
+}
+export function readMessage(stream: Readable): Promise<unknown | null>;
+export function writeMessage(stream: Writable, obj: unknown): Promise<void>;
+export function handle(req: unknown, deps: HostDeps): Promise<Record<string, unknown>>;
+export function runNativeHost(stdin: Readable, stdout: Writable, deps: HostDeps): Promise<number>;

package/lib/native.mjs

@@ -0,0 +1,144 @@
+import { readFileSync } from "node:fs";
+import { validateRequest, FREE_GUIDES } from "../shared/contract.mjs";
+import { EXTENSION_IDS } from "../shared/extension-ids.mjs";
+import { openVault } from "./vault.mjs";
+import { makeServer } from "./server.mjs";
+import { writeEnv } from "./envfile.mjs";
+import { runTest } from "./testcall.mjs";
+import { readSession, finishSession, isExpired } from "./sessions.mjs";
+
+// Nothing here writes a key value to stdout: responses carry env var names and statuses only.
+const MAX_FRAME = 1048576;
+const BAD = { __bad: true };
+const HELPER_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
+async function readBytes(stream, n) {
+  for (;;) {
+    const c = stream.read(n);
+    if (c) return c;
+    if (stream.readableEnded || stream.destroyed) return null;
+    await new Promise((resolve) => {
+      const done = () => {
+        stream.off("readable", done); stream.off("end", done); stream.off("close", done); stream.off("error", done);
+        resolve();
+      };
+      stream.on("readable", done); stream.on("end", done); stream.on("close", done); stream.on("error", done);
+    });
+  }
+}
+
+export async function readMessage(stream) {
+  const head = await readBytes(stream, 4);
+  if (!head || head.length < 4) return null;
+  const len = head.readUInt32LE(0);
+  if (len === 0 || len > MAX_FRAME) return { ...BAD };
+  const body = await readBytes(stream, len);
+  if (!body || body.length < len) return { ...BAD };
+  try { return JSON.parse(body.toString("utf8")); } catch { return { ...BAD }; }
+}
+
+export function writeMessage(stream, obj) {
+  const body = Buffer.from(JSON.stringify(obj), "utf8");
+  const head = Buffer.alloc(4);
+  head.writeUInt32LE(body.length, 0);
+  return new Promise((resolve, reject) => stream.write(Buffer.concat([head, body]), (e) => (e ? reject(e) : resolve())));
+}
+
+const fail = (error) => ({ ok: false, error });
+
+export async function handle(req, deps) {
+  const v = validateRequest(req);
+  if (!v.ok) return fail("bad message");
+  try {
+    return await dispatchRequest(v.req, deps);
+  } catch {
+    return fail("Something went wrong in the Footgun Keys helper.");
+  }
+}
+
+async function dispatchRequest(req, deps) {
+  const { store, home, fetch: fetchFn } = deps;
+  const now = deps.now ?? (() => new Date());
+  const server = makeServer({ store, home, fetch: fetchFn, now });
+
+  if (req.type === "hello") {
+    return { ok: true, helperVersion: HELPER_VERSION, signedIn: (await server.apiKey()) !== null, entitlement: await server.entitlement() };
+  }
+  if (req.type === "guide") return server.guide(req.slug);
+  if (req.type === "session") {
+    const s = await readSession(req.id, home);
+    if (!s) return fail("unknown session");
+    if (isExpired(s, now())) return fail("expired");
+    return { ok: true, provider: s.provider, envVars: s.envVars };
+  }
+
+  // save
+  if (!FREE_GUIDES.includes(req.guide)) {
+    const ent = await server.entitlement();
+    if (ent?.allGuides !== true) return fail("This guide is part of Footgun Pro.");
+  }
+  const g = await server.guide(req.guide);
+  if (!g.ok) return fail(g.error);
+  const guide = g.guide;
+  const secretOf = new Map(guide.captures.map((c) => [c.envVar, c.secret]));
+  if (req.values.some((x) => !secretOf.has(x.envVar))) return fail("unknown value");
+
+  let session = null;
+  if (req.session !== undefined) {
+    session = await readSession(req.session, home);
+    if (!session) return fail("unknown session");
+    if (isExpired(session, now())) return fail("expired");
+    if (session.provider !== req.guide) return fail("unknown session");
+  }
+
+  const label = session ? session.label : req.label;
+  const vault = openVault({ store, home });
+  for (const x of req.values) await vault.put(req.guide, label, x.envVar, x.value, secretOf.get(x.envVar));
+  if (!req.final) return { ok: true, saved: req.values.map((x) => x.envVar) };
+
+  // With a session, only the env vars it asked for are written and reported; without one, every capture.
+  const wanted = session ? session.envVars : guide.captures.map((c) => c.envVar);
+  if (wanted.some((n) => !secretOf.has(n))) return fail("unknown value");
+  const all = {};
+  for (const c of guide.captures) {
+    const val = await vault.get(req.guide, label, c.envVar);
+    if (val !== null) all[c.envVar] = val;
+  }
+  const chosen = Object.fromEntries(Object.entries(all).filter(([name]) => wanted.includes(name)));
+  // A final save reports every value gathered for this request, not just this message's.
+  const saved = Object.keys(chosen);
+  // The test call may need a capture the session did not ask for, so it sees every saved one.
+  const test = await runTest(guide, all, { fetch: fetchFn });
+  const result = { saved, test };
+  if (session?.projectPath) {
+    try {
+      result.wrote = await writeEnv(session.projectPath, Object.entries(chosen).map(([name, value]) => ({ name, value })));
+    } catch (e) {
+      const error = e instanceof Error ? e.message : "Could not write the env file.";
+      await finishSession(session.id, { saved, error }, home);
+      return fail(error);
+    }
+    for (const envVar of saved) await vault.addProject(req.guide, label, envVar, session.projectPath);
+  }
+  if (session) await finishSession(session.id, result, home);
+  return { ok: true, ...result };
+}
+
+export async function runNativeHost(stdin, stdout, deps) {
+  const ids = deps.extensionIds ?? EXTENSION_IDS;
+  const m = /^chrome-extension:\/\/([A-Za-z0-9]{1,64})\/?$/.exec(deps.origin ?? "");
+  if (!m || !ids.includes(m[1])) {
+    await writeMessage(stdout, fail("unknown extension"));
+    return 1;
+  }
+  for (;;) {
+    const msg = await readMessage(stdin);
+    if (msg === null) return 0;
+    if (msg.__bad) {
+      // The frame is unreadable, so the stream can no longer be trusted: answer once and stop.
+      await writeMessage(stdout, fail("bad message"));
+      return 1;
+    }
+    await writeMessage(stdout, await handle(msg, deps));
+  }
+}

package/lib/paths.d.mts

@@ -0,0 +1,4 @@
+export function SITE(): string;
+export function supportDir(home?: string): string;
+export function ensureSupportDir(home?: string): Promise<string>;
+export function writePrivate(file: string, data: string): Promise<void>;

package/lib/paths.mjs

@@ -0,0 +1,31 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { mkdir, chmod, writeFile, rename, rm } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+
+export function SITE() { return process.env.FOOTGUN_KEYS_SITE ?? "https://getfootgun.com"; }
+
+export function supportDir(home = homedir()) { return join(home, "Library", "Application Support", "Footgun Keys"); }
+
+// mkdir's mode is masked by the umask, so chmod each folder explicitly.
+export async function ensureSupportDir(home = homedir()) {
+  const dir = supportDir(home);
+  for (const d of [dir, join(dir, "sessions"), join(dir, "guides")]) {
+    await mkdir(d, { recursive: true, mode: 0o700 });
+    await chmod(d, 0o700);
+  }
+  return dir;
+}
+
+// Atomic: write a sibling temp file with mode 0600, then rename over the target.
+export async function writePrivate(file, data) {
+  const tmp = `${file}.${randomBytes(6).toString("hex")}.tmp`;
+  try {
+    await writeFile(tmp, data, { mode: 0o600 });
+    await chmod(tmp, 0o600);
+    await rename(tmp, file);
+  } catch (e) {
+    await rm(tmp, { force: true });
+    throw e;
+  }
+}

package/lib/protect.d.mts

@@ -0,0 +1,6 @@
+export const DENY_RULES: string[];
+export type ProtectResult = { changed: boolean; file: string; added: string[] };
+export function protect(projectPath: string, confirm: () => Promise<boolean>): Promise<ProtectResult>;
+export function protectSummary(r: ProtectResult): string;
+export function run(args: string[]): Promise<number>;
+export function isProtected(projectPath: string): Promise<boolean>;

package/lib/protect.mjs

@@ -0,0 +1,63 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+
+// Syntax per https://code.claude.com/docs/en/settings (permissions.deny, "Read(./.env)").
+export const DENY_RULES = ["Read(./.env)", "Read(./.env.local)", "Read(./.env.*)"];
+
+// True when the project's Claude Code settings already deny reading every env file pattern.
+export async function isProtected(projectPath) {
+  try {
+    const deny = JSON.parse(await readFile(join(projectPath, ".claude", "settings.json"), "utf8"))?.permissions?.deny;
+    return Array.isArray(deny) && DENY_RULES.every((r) => deny.includes(r));
+  } catch {
+    return false;
+  }
+}
+
+export async function protect(projectPath, confirm) {
+  const file = join(projectPath, ".claude", "settings.json");
+  let settings = {};
+  try {
+    const text = await readFile(file, "utf8");
+    try { settings = JSON.parse(text); } catch { throw new Error(`${file} is not valid JSON; fix it first. Nothing was changed.`); }
+    if (settings === null || typeof settings !== "object" || Array.isArray(settings)) throw new Error(`${file} is not a JSON object. Nothing was changed.`);
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+  }
+  const deny = Array.isArray(settings.permissions?.deny) ? settings.permissions.deny : [];
+  const missing = DENY_RULES.filter((r) => !deny.includes(r));
+  if (missing.length === 0) return { changed: false, file, added: [] };
+  if (!(await confirm())) return { changed: false, file, added: [] };
+  settings.permissions = { ...settings.permissions, deny: [...deny, ...missing] };
+  await mkdir(join(projectPath, ".claude"), { recursive: true });
+  await writeFile(file, JSON.stringify(settings, null, 2) + "\n");
+  return { changed: true, file, added: missing };
+}
+
+// The deny rules only stop Claude Code's Read tool, so the message says that and no more.
+export function protectSummary(r) {
+  if (!r.changed) return `No changes made to ${r.file}.`;
+  return [
+    "Added read-deny rules for env files to .claude/settings.json. Claude Code's Read tool will not open them; shell commands can still read them.",
+    ...r.added.map((rule) => `  ${rule}`),
+  ].join("\n");
+}
+
+export async function run(args) {
+  const project = resolve(args[0] ?? process.cwd());
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const r = await protect(project, async () => {
+      const a = (await rl.question("Stop Claude Code's Read tool from opening env files in this project? (y/n) ")).trim().toLowerCase();
+      return a === "y" || a === "yes";
+    });
+    console.log(protectSummary(r));
+    return 0;
+  } catch (e) {
+    console.error(e.message);
+    return 1;
+  } finally {
+    rl.close();
+  }
+}

package/lib/server.d.mts

@@ -0,0 +1,24 @@
+import type { KeyStore } from "./vault.mjs";
+// KeysEntitlement and GuideBody mirror lib/keys/entitlement.ts and lib/keys/guide.ts; defined once in ../shared/types.d.ts.
+import type { KeysEntitlement, GuideBody } from "../shared/types.js";
+
+export type GuideSummary = {
+  slug: string;
+  name: string;
+  tier: "free" | "pro";
+  version: number;
+  status: string;
+  lastVerifiedAt: string | null;
+};
+export type GuideResult =
+  | { ok: true; guide: GuideBody; version: number; status: string }
+  | { ok: false; error: string; upgradeUrl?: string };
+
+export interface Server {
+  apiKey(): Promise<string | null>;
+  setApiKey(key: string): Promise<{ ok: boolean; error?: string }>;
+  entitlement(): Promise<KeysEntitlement | null>;
+  guide(slug: string): Promise<GuideResult>;
+  guides(): Promise<{ ok: true; guides: GuideSummary[] } | { ok: false; error: string }>;
+}
+export function makeServer(opts: { store: KeyStore; home?: string; fetch?: typeof fetch; now?: () => Date }): Server;

package/lib/server.mjs

@@ -0,0 +1,105 @@
+import { readFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { SITE, supportDir, ensureSupportDir, writePrivate } from "./paths.mjs";
+
+const API_KEY_ACCOUNT = "footgun/api-key";
+const ENTITLEMENT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const TIMEOUT_MS = 8000;
+
+// The only thing this module ever sends to the server is the Footgun API key
+// in the Authorization header. Vault values are never read here.
+export function makeServer({ store, home, fetch: fetchFn = globalThis.fetch, now = () => new Date() }) {
+  const dir = () => supportDir(home);
+
+  async function readJson(file) {
+    try { return JSON.parse(await readFile(file, "utf8")); } catch { return null; }
+  }
+  async function apiKey() { return store.get(API_KEY_ACCOUNT); }
+  // A stalled request is aborted, so callers fall back to the cache as for any network error.
+  // The timer stays armed through the body read and never holds the process open.
+  async function get(path, key) {
+    const headers = key ? { Authorization: `Bearer ${key}` } : {};
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+    timer.unref?.();
+    return fetchFn(`${SITE()}${path}`, { method: "GET", headers, signal: ctrl.signal });
+  }
+  async function bodyOf(res) {
+    try { return await res.json(); } catch { return null; }
+  }
+
+  async function setApiKey(key) {
+    if (typeof key !== "string" || !key.startsWith("fg_")) {
+      return { ok: false, error: `That does not look like a Footgun key. Create one at ${SITE()}/account.` };
+    }
+    let res;
+    try { res = await get("/api/keys/entitlement", key); }
+    catch { return { ok: false, error: "Could not reach Footgun to check that key. Check your connection and try again." }; }
+    if (res.status === 401) return { ok: false, error: `That key was not accepted. Create one at ${SITE()}/account.` };
+    if (res.status !== 200) return { ok: false, error: `Footgun could not check that key (status ${res.status}). Try again in a moment.` };
+    await store.set(API_KEY_ACCOUNT, key);
+    return { ok: true };
+  }
+
+  async function entitlement() {
+    const key = await apiKey();
+    if (!key) return null;
+    const file = join(dir(), "entitlement.json");
+    try {
+      const res = await get("/api/keys/entitlement", key);
+      if (res.status === 401) {
+        // A revoked or invalid key must not keep paid behavior from the cache.
+        await rm(file, { force: true });
+        return null;
+      }
+      if (res.status === 200) {
+        const ent = await bodyOf(res);
+        if (ent) {
+          await ensureSupportDir(home);
+          await writePrivate(file, JSON.stringify({ fetchedAt: now().toISOString(), entitlement: ent }));
+          return ent;
+        }
+      }
+    } catch { /* offline: fall through to the cache */ }
+    const cached = await readJson(file);
+    if (cached?.entitlement && now().getTime() - Date.parse(cached.fetchedAt) < ENTITLEMENT_TTL_MS) return cached.entitlement;
+    return null;
+  }
+
+  async function guide(slug) {
+    if (typeof slug !== "string" || !SLUG.test(slug)) return { ok: false, error: "Unknown guide name." };
+    const file = join(dir(), "guides", `${slug}.json`);
+    const key = await apiKey();
+    try {
+      const res = await get(`/api/keys/guides/${slug}`, key);
+      const body = await bodyOf(res);
+      if (res.status === 200 && body?.guide) {
+        const out = { guide: body.guide, version: body.version, status: body.status };
+        await ensureSupportDir(home);
+        await writePrivate(file, JSON.stringify(out));
+        return { ok: true, ...out };
+      }
+      const fail = { ok: false, error: body?.error ?? `Footgun answered with status ${res.status}.` };
+      if (body?.upgradeUrl) fail.upgradeUrl = body.upgradeUrl;
+      return fail;
+    } catch {
+      const cached = await readJson(file);
+      if (cached?.guide) return { ok: true, guide: cached.guide, version: cached.version, status: cached.status };
+      return { ok: false, error: "Could not reach Footgun and there is no saved copy of that guide." };
+    }
+  }
+
+  async function guides() {
+    try {
+      const res = await get("/api/keys/guides", await apiKey());
+      const body = await bodyOf(res);
+      if (res.status === 200 && Array.isArray(body?.guides)) return { ok: true, guides: body.guides };
+      return { ok: false, error: body?.error ?? `Footgun answered with status ${res.status}.` };
+    } catch {
+      return { ok: false, error: "Could not reach Footgun." };
+    }
+  }
+
+  return { apiKey, setApiKey, entitlement, guide, guides };
+}

package/lib/sessions.d.mts

@@ -0,0 +1,19 @@
+export interface Session {
+  id: string;
+  provider: string;
+  envVars: string[];
+  projectPath: string | null;
+  label: string;
+  createdAt: string;
+  status: "pending" | "done" | "failed";
+  result?: {
+    saved: string[];
+    wrote?: { file: string; addedGitignore: boolean };
+    test?: { ok: boolean; reason?: string; status?: number };
+    error?: string;
+  };
+}
+export function createSession(opts: { provider: string; envVars: string[]; projectPath: string | null; label?: string; home?: string }): Promise<Session>;
+export function readSession(id: string, home?: string): Promise<Session | null>;
+export function finishSession(id: string, result: NonNullable<Session["result"]>, home?: string): Promise<Session | null>;
+export function isExpired(s: Session, now?: Date | number): boolean;

package/lib/sessions.mjs

@@ -0,0 +1,37 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { SESSION_RE } from "../shared/contract.mjs";
+import { supportDir, ensureSupportDir, writePrivate } from "./paths.mjs";
+
+const MAX_AGE_MS = 60 * 60 * 1000;
+
+// A session says which provider and env var names a setup run is about. It never holds a value.
+const fileFor = (id, home) => join(supportDir(home), "sessions", `${id}.json`);
+
+export async function createSession({ provider, envVars, projectPath, label = "default", home }) {
+  const id = randomBytes(32).toString("base64url").slice(0, 43);
+  const session = { id, provider, envVars: [...envVars], projectPath: projectPath ?? null, label, createdAt: new Date().toISOString(), status: "pending" };
+  await ensureSupportDir(home);
+  await writePrivate(fileFor(id, home), JSON.stringify(session));
+  return session;
+}
+
+export async function readSession(id, home) {
+  if (typeof id !== "string" || !SESSION_RE.test(id)) return null;
+  try { return JSON.parse(await readFile(fileFor(id, home), "utf8")); } catch { return null; }
+}
+
+export async function finishSession(id, result, home) {
+  const s = await readSession(id, home);
+  if (!s) return null;
+  s.status = result.error ? "failed" : "done";
+  s.result = result;
+  await writePrivate(fileFor(id, home), JSON.stringify(s));
+  return s;
+}
+
+export function isExpired(s, now = new Date()) {
+  const t = now instanceof Date ? now.getTime() : now;
+  return !(t - Date.parse(s.createdAt) <= MAX_AGE_MS);
+}

package/lib/setup.d.mts

@@ -0,0 +1,19 @@
+import type { Server } from "./server.mjs";
+
+export function setup(deps: {
+  home: string;
+  platform: string;
+  prompt: (question: string) => Promise<string>;
+  exec: (file: string, args: string[]) => Promise<unknown>;
+  installApp: (dir: string) => Promise<string>;
+  server: Pick<Server, "setApiKey">;
+  print: (line: string) => void;
+  extensionIds?: string[];
+  uid?: number;
+}): Promise<number>;
+export function run(): Promise<number>;
+export function launcherScript(nodePath: string, bin: string, subcommand: string, fallbackPath?: string): string;
+export function hiddenPrompt(
+  question: string,
+  io?: { input?: NodeJS.ReadableStream; write?: (text: string) => void; exit?: (code: number) => void },
+): Promise<string>;

package/lib/setup.mjs

@@ -0,0 +1,185 @@
+import { execFile } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { mkdir, chmod, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+import { Writable } from "node:stream";
+import { promisify } from "node:util";
+import { EXTENSION_IDS } from "../shared/extension-ids.mjs";
+import { SITE, ensureSupportDir, writePrivate } from "./paths.mjs";
+import { launchdPlist } from "./launchd.mjs";
+import { keychainStore } from "./vault.mjs";
+import { makeServer } from "./server.mjs";
+
+const HOST = "com.getfootgun.keys";
+const LABEL = "com.getfootgun.keys.health";
+const MAX_TRIES = 3;
+
+const NO_NODE = "Footgun Keys cannot find Node. Run npx @getfootgun/keys setup again.";
+const NOTIFY_SCRIPT = ["on run argv", "display notification (item 2 of argv) with title (item 1 of argv)", "end run"];
+
+// A launcher survives a Node upgrade: it tries the Node that ran setup, then any node on PATH
+// (with the Homebrew and /usr/local bins added, since launchd and Chrome start with a bare PATH),
+// and otherwise shows a notification instead of failing silently. Notification text travels as argv.
+export function launcherScript(nodePath, bin, subcommand, fallbackPath = "/opt/homebrew/bin:/usr/local/bin") {
+  const sub = subcommand ? ` ${subcommand}` : "";
+  const script = NOTIFY_SCRIPT.map((l) => `-e '${l}'`).join(" ");
+  return [
+    "#!/bin/sh",
+    `NODE="${nodePath}"`,
+    'if [ ! -x "$NODE" ]; then',
+    `  PATH="$PATH:${fallbackPath}"`,
+    "  export PATH",
+    '  NODE="$(command -v node)"',
+    "fi",
+    'if [ -z "$NODE" ] || [ ! -x "$NODE" ]; then',
+    `  osascript ${script} "Footgun Keys" "${NO_NODE}" >/dev/null 2>&1`,
+    "  exit 1",
+    "fi",
+    `exec "$NODE" "${bin}"${sub} "$@"`,
+    "",
+  ].join("\n");
+}
+
+async function writeExecutable(file, text) {
+  await writeFile(file, text, { mode: 0o700 });
+  await chmod(file, 0o700);
+}
+
+async function loadAgent(exec, uid, plist) {
+  try {
+    await exec("launchctl", ["bootstrap", `gui/${uid}`, plist]);
+  } catch {
+    // Already loaded: unload it, then load the fresh plist.
+    await exec("launchctl", ["bootout", `gui/${uid}/${LABEL}`]).catch(() => {});
+    await exec("launchctl", ["bootstrap", `gui/${uid}`, plist]);
+  }
+}
+
+// Every dependency is injected so tests never touch the real Library, launchctl, npm or Keychain.
+export async function setup({ home, platform, prompt, exec, installApp, server, print, extensionIds = EXTENSION_IDS, uid = process.getuid?.() }) {
+  if (platform !== "darwin") {
+    print("Footgun Keys runs on macOS for now.");
+    return 1;
+  }
+
+  const support = await ensureSupportDir(home);
+  print("Created the Footgun Keys support folder.");
+
+  let bin;
+  try {
+    bin = await installApp(join(support, "app"));
+  } catch (e) {
+    const msg = (e instanceof Error && e.message ? e.message : "unknown error").split("\n")[0];
+    print(`Could not install Footgun Keys: ${msg}`);
+    return 1;
+  }
+  print("Installed a stable copy of the helper.");
+
+  const launcher = join(support, "footgun-keys");
+  const nativeLauncher = join(support, "native-host");
+  await writeExecutable(launcher, launcherScript(process.execPath, bin, ""));
+  await writeExecutable(nativeLauncher, launcherScript(process.execPath, bin, "native-host"));
+  print("Wrote the launchers.");
+
+  const hostDir = join(home, "Library", "Application Support", "Google", "Chrome", "NativeMessagingHosts");
+  await mkdir(hostDir, { recursive: true });
+  await writePrivate(join(hostDir, `${HOST}.json`), JSON.stringify({
+    name: HOST,
+    description: "Footgun Keys helper",
+    path: nativeLauncher,
+    type: "stdio",
+    allowed_origins: extensionIds.map((id) => `chrome-extension://${id}/`),
+  }, null, 2) + "\n");
+  print("Registered the helper with Chrome.");
+  if (extensionIds.length === 0) print("The Chrome extension id is not set yet; guides will not save until it is.");
+
+  const agents = join(home, "Library", "LaunchAgents");
+  await mkdir(agents, { recursive: true });
+  const plist = join(agents, `${LABEL}.plist`);
+  await writePrivate(plist, launchdPlist(launcher));
+  let scheduled = true;
+  try {
+    await loadAgent(exec, uid, plist);
+    print("Scheduled the daily key check.");
+  } catch {
+    scheduled = false;
+    print("Could not schedule the daily key check. Run setup again to retry.");
+  }
+  // A failed schedule must not end in apparent success, so it is repeated last and fails the run.
+  const finish = (code) => {
+    if (scheduled) return code;
+    print("The daily key check is NOT scheduled. Run npx @getfootgun/keys setup again.");
+    return 1;
+  };
+
+  let stored = false;
+  let lastError = "";
+  for (let i = 0; i < MAX_TRIES && !stored; i++) {
+    const key = (await prompt(`Paste your Footgun API key (create one free at ${SITE()}/account):`)).trim();
+    const res = await server.setApiKey(key);
+    if (res.ok) stored = true;
+    else {
+      lastError = res.error ?? "That key was not accepted.";
+      print(lastError);
+    }
+  }
+  if (!stored) {
+    print("No API key was saved. Run footgun-keys setup again when you have one.");
+    return finish(1);
+  }
+  print("Saved your Footgun API key to the Keychain.");
+
+  print("Next steps:");
+  print("Claude Code: claude mcp add footgun-keys -- npx -y @getfootgun/keys mcp");
+  print("Cursor: add the same command under MCP servers.");
+  print("Chrome: install the Footgun Keys extension.");
+  print("Your keys live in your Mac's Keychain and in the env files you choose. AI tools can still read those env files; run npx @getfootgun/keys protect in a project so Claude Code's Read tool will not open them (shell commands still can).");
+  return finish(0);
+}
+
+// Reads one line without echoing what is typed. Ctrl-C closes the prompt and exits 130.
+export function hiddenPrompt(question, {
+  input = process.stdin,
+  write = (t) => process.stdout.write(t),
+  exit = (code) => process.exit(code),
+} = {}) {
+  const muted = new Writable({ write(_chunk, _enc, cb) { cb(); } });
+  const rl = createInterface({ input, output: muted, terminal: true });
+  write(`${question} `);
+  return new Promise((resolve) => {
+    rl.on("SIGINT", () => {
+      rl.close();
+      write("\n");
+      exit(130);
+    });
+    rl.question("", (answer) => {
+      rl.close();
+      write("\n");
+      resolve(answer);
+    });
+  });
+}
+
+const execAsync = promisify(execFile);
+
+function realInstallApp(dir) {
+  const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+  return execAsync("npm", ["install", "--prefix", dir, `@getfootgun/keys@${version}`]).then(
+    () => join(dir, "node_modules", "@getfootgun", "keys", "bin", "footgun-keys.mjs"),
+  );
+}
+
+export async function run() {
+  const home = homedir();
+  return setup({
+    home,
+    platform: process.platform,
+    prompt: hiddenPrompt,
+    exec: (file, args) => execAsync(file, args),
+    installApp: realInstallApp,
+    server: makeServer({ store: keychainStore(), home }),
+    print: (line) => console.log(line),
+  });
+}