@getfootgun/keys 0.1.0 → 0.2.0-rc.1

package/README.md

@@ -1,8 +1,8 @@
 # @getfootgun/keys
 
-Footgun Keys: guided API key setup for your Mac. Keys go to your Keychain, and only to an env file you ask for.
+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.
 
-Mac only. Needs Node 20 or newer.
+Works on macOS and Windows. Needs Node 20 or newer.
 
 ## Install
 
@@ -15,16 +15,27 @@ Setup installs a stable copy of the helper, registers it with Chrome and with a
     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.
+- `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 that launchd runs at 9:30. It tells you when a saved key stops working.
+- `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

package/lib/dispatch.d.mts

@@ -1,2 +1,2 @@
 export const COMMANDS: string[];
-export function dispatch(argv: string[], libDir?: string): Promise<number>;
+export function dispatch(argv: string[], libDir?: string, importModule?: (specifier: string) => Promise<{ run(args: string[]): unknown }>): Promise<number>;

package/lib/dispatch.mjs

@@ -1,13 +1,14 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { fileURLToPath } from "node:url";
+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.
-export async function dispatch(argv, libDir = LIB) {
+// 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]`);
@@ -18,6 +19,6 @@ export async function dispatch(argv, libDir = LIB) {
     console.error("not built yet");
     return 2;
   }
-  const mod = await import(file);
+  const mod = await importModule(pathToFileURL(file).href);
   return (await mod.run(args)) ?? 0;
 }

package/lib/envfile.d.mts

@@ -2,5 +2,9 @@ export function envFileFor(projectPath: string): Promise<string>;
 export function writeEnv(
   projectPath: string,
   vars: { name: string; value: string }[],
-  opts?: { git?: (args: string[]) => Promise<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

@@ -84,7 +84,7 @@ async function ensureIgnored(projectPath, file, git) {
   return true;
 }
 
-export async function writeEnv(projectPath, vars, { git = realGit } = {}) {
+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.
@@ -96,6 +96,9 @@ export async function writeEnv(projectPath, vars, { git = realGit } = {}) {
   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);
+  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.mjs

@@ -1,15 +1,13 @@
-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";
+import { notify } from "./platform.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())));
+// 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.
@@ -92,7 +90,7 @@ export async function runHealth({ vault, server, notify, fetch: fetchFn, now = (
 export async function run() {
   const store = keychainStore();
   try {
-    await runHealth({ vault: openVault({ store }), server: makeServer({ store }), notify: macNotify });
+    await runHealth({ vault: openVault({ store }), server: makeServer({ store }), notify });
     return 0;
   } catch {
     return 1;

package/lib/mcp.d.mts

@@ -2,6 +2,7 @@ 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: {

package/lib/mcp.mjs

@@ -1,4 +1,4 @@
-import { execFile } from "node:child_process";
+import { readFileSync } from "node:fs";
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/server";
 import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
@@ -8,11 +8,15 @@ 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.";
 
@@ -237,15 +241,11 @@ export const SPECS = {
   },
 };
 
-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.
+// 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") {
-    return Object.fromEntries(Object.keys(SPECS).map((name) => [name, async () => reply("Footgun Keys runs on macOS for now.")]));
+  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());
 }
@@ -255,7 +255,7 @@ export async function runMcp() {
     const store = keychainStore();
     return { vault: openVault({ store }), server: makeServer({ store }), openUrl };
   });
-  const mcp = new McpServer({ name: "footgun-keys", version: "0.1.0" }, { instructions: INSTRUCTIONS });
+  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));
   }

package/lib/native.mjs

@@ -1,7 +1,7 @@
 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 { openVault, tooLongFor } from "./vault.mjs";
 import { makeServer } from "./server.mjs";
 import { writeEnv } from "./envfile.mjs";
 import { runTest } from "./testcall.mjs";
@@ -92,7 +92,13 @@ async function dispatchRequest(req, deps) {
   }
 
   const label = session ? session.label : req.label;
-  const vault = openVault({ store, home });
+  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) };
 

package/lib/paths.d.mts

@@ -1,4 +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>;
+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

@@ -1,18 +1,23 @@
 import { homedir } from "node:os";
-import { join } from "node:path";
+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()) { return join(home, "Library", "Application Support", "Footgun Keys"); }
+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.
-export async function ensureSupportDir(home = homedir()) {
-  const dir = supportDir(home);
-  for (const d of [dir, join(dir, "sessions"), join(dir, "guides")]) {
+// 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 });
-    await chmod(d, 0o700);
+    if (platform !== "win32") await chmod(d, 0o700);
   }
   return dir;
 }

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/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>;

package/lib/schedule.mjs

@@ -0,0 +1,97 @@
+import { mkdir } from "node:fs/promises";
+import { join, win32 } from "node:path";
+import { writePrivate } from "./paths.mjs";
+import { launchdPlist } from "./launchd.mjs";
+
+const LABEL = "com.getfootgun.keys.health";
+const WIN_HOST_KEY = "HKCU\\Software\\Google\\Chrome\\NativeMessagingHosts\\com.getfootgun.keys";
+const TASK = "Footgun Keys health";
+
+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]);
+  }
+}
+
+// Chrome finds the helper through a manifest: a file in Chrome's folder on macOS, a registry
+// pointer to a file in the support folder on Windows (per user, no admin rights).
+export async function registerNativeHost({ platform, exec, home, support, manifest }) {
+  const text = JSON.stringify(manifest, null, 2) + "\n";
+  if (platform === "win32") {
+    const file = win32.join(support, `${manifest.name}.json`);
+    await writePrivate(file, text);
+    await exec("reg", ["add", WIN_HOST_KEY, "/ve", "/t", "REG_SZ", "/d", file, "/f"]);
+    return;
+  }
+  const hostDir = join(home, "Library", "Application Support", "Google", "Chrome", "NativeMessagingHosts");
+  await mkdir(hostDir, { recursive: true });
+  await writePrivate(join(hostDir, `${manifest.name}.json`), text);
+}
+
+const xmlEscape = (s) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&apos;" })[c]);
+const pad = (n) => String(n).padStart(2, "0");
+
+// Task Scheduler definition for the daily check: runs on battery, catches up a missed run, and starts
+// the launcher through a headless console so no window shows. It names the launcher only, never a key.
+export function healthTaskXml(launcher, now = new Date()) {
+  const start = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}T09:30:00`;
+  return [
+    '<?xml version="1.0" encoding="UTF-16"?>',
+    '<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">',
+    "  <RegistrationInfo>",
+    "    <Description>Footgun Keys daily key check</Description>",
+    "  </RegistrationInfo>",
+    "  <Triggers>",
+    "    <CalendarTrigger>",
+    `      <StartBoundary>${start}</StartBoundary>`,
+    "      <Enabled>true</Enabled>",
+    "      <ScheduleByDay>",
+    "        <DaysInterval>1</DaysInterval>",
+    "      </ScheduleByDay>",
+    "    </CalendarTrigger>",
+    "  </Triggers>",
+    "  <Principals>",
+    '    <Principal id="Author">',
+    "      <LogonType>InteractiveToken</LogonType>",
+    "      <RunLevel>LeastPrivilege</RunLevel>",
+    "    </Principal>",
+    "  </Principals>",
+    "  <Settings>",
+    "    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>",
+    "    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>",
+    "    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>",
+    "    <StartWhenAvailable>true</StartWhenAvailable>",
+    "    <ExecutionTimeLimit>PT10M</ExecutionTimeLimit>",
+    "    <Enabled>true</Enabled>",
+    "  </Settings>",
+    '  <Actions Context="Author">',
+    "    <Exec>",
+    "      <Command>conhost.exe</Command>",
+    `      <Arguments>${xmlEscape(`--headless "${launcher}" health`)}</Arguments>`,
+    "    </Exec>",
+    "  </Actions>",
+    "</Task>",
+    "",
+  ].join("\r\n");
+}
+
+// Daily 9:30 run of "<launcher> health". Throws if the OS scheduler refuses.
+export async function scheduleDaily({ platform, exec, home, launcher, uid, support, now = () => new Date() }) {
+  if (platform === "win32") {
+    // schtasks reads /XML files as UTF-16LE with a byte order mark.
+    const xmlPath = win32.join(support, "health-task.xml");
+    const body = Buffer.from(healthTaskXml(launcher, now()), "utf16le");
+    await writePrivate(xmlPath, Buffer.concat([Buffer.from([0xff, 0xfe]), body]));
+    await exec("schtasks", ["/Create", "/F", "/TN", TASK, "/XML", xmlPath]);
+    return;
+  }
+  const agents = join(home, "Library", "LaunchAgents");
+  await mkdir(agents, { recursive: true });
+  const plist = join(agents, `${LABEL}.plist`);
+  await writePrivate(plist, launchdPlist(launcher));
+  await loadAgent(exec, uid, plist);
+}

package/lib/setup.d.mts

@@ -10,10 +10,13 @@ export function setup(deps: {
   print: (line: string) => void;
   extensionIds?: string[];
   uid?: number;
+  env?: Record<string, string | undefined>;
+  now?: () => Date;
 }): Promise<number>;
 export function run(): Promise<number>;
-export function launcherScript(nodePath: string, bin: string, subcommand: string, fallbackPath?: string): string;
+export function launcherScript(nodePath: string, bin: string, subcommand: string, options?: { platform?: string; fallbackPath?: string }): string;
 export function hiddenPrompt(
   question: string,
   io?: { input?: NodeJS.ReadableStream; write?: (text: string) => void; exit?: (code: number) => void },
 ): Promise<string>;
+export function npmInstallCommand(platform: string, dir: string, version: string, env?: Record<string, string | undefined>, nodePath?: string): { file: string; args: string[] };

package/lib/setup.mjs

@@ -1,28 +1,56 @@
 import { execFile } from "node:child_process";
 import { readFileSync } from "node:fs";
-import { mkdir, chmod, writeFile } from "node:fs/promises";
+import { chmod, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, win32 } 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 { registerNativeHost, scheduleDaily } from "./schedule.mjs";
 import { keychainStore } from "./vault.mjs";
+import { WIN_NOTIFY_SCRIPT } from "./platform.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"];
 
+// The Windows .cmd launcher: same fallback order, but the notification text travels as environment
+// variables read by the fixed PowerShell script, and cmd gets no path it could expand or break on.
+function windowsLauncher(nodePath, bin, subcommand) {
+  for (const p of [nodePath, bin]) {
+    if (/["%]/.test(p)) throw new Error(`Cannot write a Windows launcher for a path containing " or %: ${p}`);
+  }
+  const sub = subcommand ? ` ${subcommand}` : "";
+  return [
+    "@echo off",
+    "setlocal",
+    `set "NODE=${nodePath}"`,
+    'if not exist "%NODE%" (',
+    "  set \"NODE=\"",
+    "  set \"FOOTGUN_FOUND=\"",
+    "  for /f \"delims=\" %%i in ('where node 2^>nul') do if not defined FOOTGUN_FOUND (set \"NODE=%%i\" & set \"FOOTGUN_FOUND=1\")",
+    ")",
+    'if not exist "%NODE%" (',
+    '  set "FOOTGUN_NOTIFY_TITLE=Footgun Keys"',
+    `  set "FOOTGUN_NOTIFY_BODY=${NO_NODE}"`,
+    `  powershell.exe -NoProfile -NonInteractive -Command "${WIN_NOTIFY_SCRIPT}" >nul 2>&1`,
+    "  exit /b 1",
+    ")",
+    `"%NODE%" "${bin}"${sub} %*`,
+    "",
+  ].join("\r\n");
+}
+
 // 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") {
+export function launcherScript(nodePath, bin, subcommand, { platform = process.platform, fallbackPath = "/opt/homebrew/bin:/usr/local/bin" } = {}) {
+  if (platform === "win32") return windowsLauncher(nodePath, bin, subcommand);
   const sub = subcommand ? ` ${subcommand}` : "";
   const script = NOTIFY_SCRIPT.map((l) => `-e '${l}'`).join(" ");
   return [
@@ -42,34 +70,26 @@ export function launcherScript(nodePath, bin, subcommand, fallbackPath = "/opt/h
   ].join("\n");
 }
 
-async function writeExecutable(file, text) {
+async function writeExecutable(file, text, platform) {
   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]);
-  }
+  if (platform !== "win32") await chmod(file, 0o700);
 }
 
 // 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.");
+export async function setup({ home, platform, prompt, exec, installApp, server, print, extensionIds = EXTENSION_IDS, uid = process.getuid?.(), env = process.env, now = () => new Date() }) {
+  if (platform !== "darwin" && platform !== "win32") {
+    print("Footgun Keys runs on macOS and Windows for now.");
     return 1;
   }
 
-  const support = await ensureSupportDir(home);
+  const win = platform === "win32";
+  const j = win ? win32.join : join;
+  const support = await ensureSupportDir(home, platform, env);
   print("Created the Footgun Keys support folder.");
 
   let bin;
   try {
-    bin = await installApp(join(support, "app"));
+    bin = await installApp(j(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}`);
@@ -77,31 +97,44 @@ export async function setup({ home, platform, prompt, exec, installApp, server,
   }
   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"));
+  const ext = win ? ".cmd" : "";
+  const launcher = j(support, `footgun-keys${ext}`);
+  const nativeLauncher = j(support, `native-host${ext}`);
+  let mainScript, nativeScript;
+  try {
+    mainScript = launcherScript(process.execPath, bin, "", { platform });
+    nativeScript = launcherScript(process.execPath, bin, "native-host", { platform });
+  } catch {
+    // Only the Windows .cmd launcher refuses a path; cmd would expand or break on " and %.
+    print("Footgun Keys can't install into a folder whose path contains \" or %.");
+    return 1;
+  }
+  await writeExecutable(launcher, mainScript, platform);
+  await writeExecutable(nativeLauncher, nativeScript, platform);
   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");
+  try {
+    await registerNativeHost({
+      platform, exec, home, support,
+      manifest: {
+        name: HOST,
+        description: "Footgun Keys helper",
+        path: nativeLauncher,
+        type: "stdio",
+        allowed_origins: extensionIds.map((id) => `chrome-extension://${id}/`),
+      },
+    });
+  } catch (e) {
+    if (!win) throw e;
+    print(`Could not register the helper with Chrome: ${(e instanceof Error && e.message ? e.message : "unknown error").split("\n")[0]}`);
+    return 1;
+  }
   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);
+    await scheduleDaily({ platform, exec, home, launcher, uid, support, now });
     print("Scheduled the daily key check.");
   } catch {
     scheduled = false;
@@ -129,13 +162,13 @@ export async function setup({ home, platform, prompt, exec, installApp, server,
     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(`Saved your Footgun API key to the ${win ? "Windows Credential Manager" : "Keychain"}.`);
 
   print("Next steps:");
-  print("Claude Code: claude mcp add footgun-keys -- npx -y @getfootgun/keys mcp");
+  print(`Claude Code: claude mcp add footgun-keys -- ${win ? "cmd /c " : ""}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).");
+  print(`Your keys live in ${win ? "the Windows Credential Manager" : "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);
 }
 
@@ -164,11 +197,19 @@ export function hiddenPrompt(question, {
 
 const execAsync = promisify(execFile);
 
+// Node 20.12+ will not execFile a .cmd without a shell, so on Windows npm runs through node itself.
+export function npmInstallCommand(platform, dir, version, env = process.env, nodePath = process.execPath) {
+  const args = ["install", "--prefix", dir, `@getfootgun/keys@${version}`];
+  if (platform !== "win32") return { file: "npm", args };
+  const cli = env.npm_execpath?.endsWith(".js") ? env.npm_execpath : win32.join(win32.dirname(nodePath), "node_modules", "npm", "bin", "npm-cli.js");
+  return { file: nodePath, args: [cli, ...args] };
+}
+
 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"),
-  );
+  const { file, args } = npmInstallCommand(process.platform, dir, version);
+  const j = process.platform === "win32" ? win32.join : join;
+  return execAsync(file, args).then(() => j(dir, "node_modules", "@getfootgun", "keys", "bin", "footgun-keys.mjs"));
 }
 
 export async function run() {

package/lib/vault.d.mts

@@ -22,4 +22,5 @@ export interface Vault {
 }
 export function keychainStore(): KeyStore;
 export function memoryStore(): KeyStore;
-export function openVault(opts: { store: KeyStore; home?: string }): Vault;
+export function openVault(opts: { store: KeyStore; home?: string; platform?: NodeJS.Platform }): Vault;
+export function tooLongFor(value: string, platform?: NodeJS.Platform): string | null;

package/lib/vault.mjs

@@ -24,7 +24,17 @@ export function memoryStore() {
   };
 }
 
-export function openVault({ store, home }) {
+// Windows Credential Manager holds at most 2,560 bytes per credential, counted as UTF-16.
+const WIN_MAX_BYTES = 2560;
+
+// The fixed refusal message when value cannot be stored on this platform, else null. Never contains the value.
+export function tooLongFor(value, platform = process.platform) {
+  return platform === "win32" && Buffer.byteLength(value, "utf16le") > WIN_MAX_BYTES
+    ? "This value is too long for Windows Credential Manager."
+    : null;
+}
+
+export function openVault({ store, home, platform = process.platform }) {
   const file = join(supportDir(home), "index.json");
   let queue = Promise.resolve();
 
@@ -47,6 +57,8 @@ export function openVault({ store, home }) {
 
   return {
     async put(provider, label, envVar, value, secret) {
+      const tooLong = tooLongFor(value, platform);
+      if (tooLong) throw new Error(tooLong);
       await store.set(account(provider, label, envVar), value);
       await mutate((entries) => {
         if (!find(entries, provider, label, envVar)) {

package/package.json

@@ -1 +1 @@
-{ "name": "@getfootgun/keys", "version": "0.1.0", "description": "Footgun Keys: guided API key setup that saves keys to your Mac Keychain.", "bin": { "footgun-keys": "bin/footgun-keys.mjs" }, "type": "module", "license": "MIT", "files": ["bin", "lib", "shared", "README.md"], "dependencies": { "@modelcontextprotocol/server": "2.3.1", "@napi-rs/keyring": "2.1.2", "zod": "4.6.7" }, "engines": { "node": ">=20" } }
+{ "name": "@getfootgun/keys", "version": "0.2.0-rc.1", "description": "Footgun Keys: guided API key setup that saves keys to the Mac Keychain or Windows Credential Manager.", "bin": { "footgun-keys": "bin/footgun-keys.mjs" }, "type": "module", "license": "MIT", "files": ["bin", "lib", "shared", "README.md"], "dependencies": { "@modelcontextprotocol/server": "2.3.1", "@napi-rs/keyring": "2.1.2", "zod": "4.6.7" }, "engines": { "node": ">=20" } }