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

package/lib/mcp.mjs

@@ -0,0 +1,271 @@
+import { readFileSync } from "node:fs";
+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 { openUrl } from "./platform.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.
+const HELPER_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+export const SERVER_INFO = { name: "footgun-keys", version: HELPER_VERSION };
+
+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.") }),
+  },
+};
+
+// On other platforms the server still answers initialize and tools/list (so a plugin that starts it does not
+// crash), but every tool call says Footgun Keys runs on macOS and Windows only.
+export function toolsFor(platform, makeDeps) {
+  if (platform !== "darwin" && platform !== "win32") {
+    return Object.fromEntries(Object.keys(SPECS).map((name) => [name, async () => reply("Footgun Keys runs on macOS and Windows 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(SERVER_INFO, { 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;
+}

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,150 @@
+import { readFileSync } from "node:fs";
+import { validateRequest, FREE_GUIDES } from "../shared/contract.mjs";
+import { EXTENSION_IDS } from "../shared/extension-ids.mjs";
+import { openVault, tooLongFor } 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 platform = deps.platform ?? process.platform;
+  // Check every value first, so a too-long one stores nothing (not even earlier values in this request).
+  for (const x of req.values) {
+    const tooLong = tooLongFor(x.value, platform);
+    if (tooLong) return fail(tooLong);
+  }
+  const vault = openVault({ store, home, platform });
+  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, platform?: string, env?: NodeJS.ProcessEnv): string;
+export function ensureSupportDir(home?: string, platform?: string, env?: NodeJS.ProcessEnv): Promise<string>;
+export function writePrivate(file: string, data: string | Uint8Array): Promise<void>;

package/lib/paths.mjs

@@ -0,0 +1,36 @@
+import { homedir } from "node:os";
+import { join, win32 } 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(), platform = process.platform, env = process.env) {
+  if (platform === "win32") return win32.join(env.LOCALAPPDATA || win32.join(home, "AppData", "Local"), "Footgun Keys");
+  return join(home, "Library", "Application Support", "Footgun Keys");
+}
+
+// mkdir's mode is masked by the umask, so chmod each folder explicitly.
+// Windows has no POSIX modes, so the chmod is skipped there.
+export async function ensureSupportDir(home = homedir(), platform = process.platform, env = process.env) {
+  const dir = supportDir(home, platform, env);
+  const j = platform === "win32" ? win32.join : join;
+  for (const d of [dir, j(dir, "sessions"), j(dir, "guides")]) {
+    await mkdir(d, { recursive: true, mode: 0o700 });
+    if (platform !== "win32") 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/platform.d.mts

@@ -0,0 +1,5 @@
+type Exec = (file: string, ...rest: any[]) => unknown;
+
+export const WIN_NOTIFY_SCRIPT: string;
+export function notify(title: string, body: string, opts?: { platform?: string; exec?: Exec }): Promise<void>;
+export function openUrl(url: string, opts?: { platform?: string; exec?: Exec }): Promise<void>;

package/lib/platform.mjs

@@ -0,0 +1,38 @@
+import { execFile } from "node:child_process";
+
+// Title and body travel as argv (Mac) or environment variables (Windows), never inside the script text.
+const MAC_SCRIPT = "on run argv\ndisplay notification (item 2 of argv) with title (item 1 of argv)\nend run";
+
+// Joined with "; " because a .cmd launcher carries it on one line. It must stay free of newlines, double quotes and %.
+// Not executed on Windows in tests (this runs on a Mac); the tests check how it is called, not that a toast appears.
+// The app id is PowerShell's own: a toast from an unregistered app id shows nothing on Windows.
+export const WIN_NOTIFY_SCRIPT = [
+  "[void][Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime]",
+  "$xml = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02)",
+  "$text = $xml.GetElementsByTagName('text')",
+  "[void]$text.Item(0).AppendChild($xml.CreateTextNode($env:FOOTGUN_NOTIFY_TITLE))",
+  "[void]$text.Item(1).AppendChild($xml.CreateTextNode($env:FOOTGUN_NOTIFY_BODY))",
+  "$toast = [Windows.UI.Notifications.ToastNotification]::new($xml)",
+  "[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\\WindowsPowerShell\\v1.0\\powershell.exe').Show($toast)",
+].join("; ");
+
+export function notify(title, body, { platform = process.platform, exec = execFile } = {}) {
+  return new Promise((resolve, reject) => {
+    const done = (e) => (e ? reject(e) : resolve());
+    if (platform === "win32") {
+      exec("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", WIN_NOTIFY_SCRIPT],
+        { env: { ...process.env, FOOTGUN_NOTIFY_TITLE: title, FOOTGUN_NOTIFY_BODY: body } }, done);
+    } else {
+      exec("osascript", ["-e", MAC_SCRIPT, title, body], done);
+    }
+  });
+}
+
+export function openUrl(url, { platform = process.platform, exec = execFile } = {}) {
+  return new Promise((resolve, reject) => {
+    const done = (e) => (e ? reject(e) : resolve());
+    // rundll32 takes the url as one argument, so an & in it needs no shell quoting.
+    if (platform === "win32") exec("rundll32", ["url.dll,FileProtocolHandler", url], done);
+    else exec("open", [url], done);
+  });
+}

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/schedule.d.mts

@@ -0,0 +1,11 @@
+type Exec = (file: string, args: string[]) => Promise<unknown>;
+
+export function registerNativeHost(opts: {
+  platform: string;
+  exec: Exec;
+  home: string;
+  support: string;
+  manifest: { name: string; [key: string]: unknown };
+}): Promise<void>;
+export function healthTaskXml(launcher: string, now?: Date): string;
+export function scheduleDaily(opts: { platform: string; exec: Exec; home: string; launcher: string; uid?: number; support?: string; now?: () => Date }): Promise<void>;