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

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/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,22 @@
+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;
+  env?: Record<string, string | undefined>;
+  now?: () => Date;
+}): Promise<number>;
+export function run(): Promise<number>;
+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

@@ -0,0 +1,226 @@
+import { execFile } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { chmod, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+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 { 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 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, { 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 [
+    "#!/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, platform) {
+  await writeFile(file, text, { mode: 0o700 });
+  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?.(), env = process.env, now = () => new Date() }) {
+  if (platform !== "darwin" && platform !== "win32") {
+    print("Footgun Keys runs on macOS and Windows for now.");
+    return 1;
+  }
+
+  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(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}`);
+    return 1;
+  }
+  print("Installed a stable copy of the helper.");
+
+  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.");
+
+  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.");
+
+  let scheduled = true;
+  try {
+    await scheduleDaily({ platform, exec, home, launcher, uid, support, now });
+    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 ${win ? "Windows Credential Manager" : "Keychain"}.`);
+
+  print("Next steps:");
+  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 ${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);
+}
+
+// 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);
+
+// 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"));
+  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() {
+  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),
+  });
+}

package/lib/testcall.d.mts

@@ -0,0 +1,11 @@
+import type { GuideBody } from "../shared/types";
+
+export function runTest(
+  guide: GuideBody,
+  values: Record<string, string>,
+  opts?: { fetch?: typeof fetch; timeoutMs?: number },
+): Promise<{
+  ok: boolean;
+  reason?: "revoked" | "out_of_credit" | "rate_limited" | "unreachable" | "unexpected";
+  status?: number;
+}>;

package/lib/testcall.mjs

@@ -0,0 +1,103 @@
+// The one request that may carry a key value off the machine, and only to the provider's own host.
+// Results and errors never include a key value.
+
+// Same rule as lib/keys/guide.ts: last two labels.
+const registrable = (host) => host.split(".").slice(-2).join(".");
+
+const ownHost = (guide, url) => {
+  try {
+    const own = new Set([...guide.domains, new URL(guide.docsUrl).hostname].map(registrable));
+    return own.has(registrable(new URL(url).hostname));
+  } catch {
+    return false;
+  }
+};
+
+const BAD = { ok: false, reason: "unexpected" };
+
+// Same list as lib/keys/guide.ts; checked again here in case a guide skipped validation.
+const RESERVED = new Set(["authorization", "cookie", "host", "content-type", "content-length", "proxy-authorization"]);
+const CONTENT_TYPES = { json: "application/json", form: "application/x-www-form-urlencoded" };
+
+export async function runTest(guide, values, opts = {}) {
+  const t = guide.test;
+  if (!t) return { ok: true };
+  if (!ownHost(guide, t.url)) return { ...BAD };
+
+  const a = t.auth;
+  const headers = {};
+  let url;
+  try {
+    url = new URL(t.url);
+  } catch {
+    return { ...BAD };
+  }
+  if (url.protocol !== "https:") return { ...BAD };
+  const need = (name) => (typeof values[name] === "string" && values[name] !== "" ? values[name] : null);
+
+  if (a.type === "bearer") {
+    const v = need(a.envVar);
+    if (v === null) return { ...BAD };
+    headers.Authorization = `Bearer ${v}`;
+  } else if (a.type === "header") {
+    const v = need(a.envVar);
+    if (v === null) return { ...BAD };
+    headers[a.name] = v;
+  } else if (a.type === "basic") {
+    const u = need(a.userEnvVar);
+    const p = need(a.passEnvVar);
+    if (u === null || p === null) return { ...BAD };
+    headers.Authorization = "Basic " + Buffer.from(`${u}:${p}`).toString("base64");
+  } else if (a.type === "query") {
+    const v = need(a.envVar);
+    if (v === null) return { ...BAD };
+    url.searchParams.set(a.name, v);
+  } else if (a.type !== "none") {
+    return { ...BAD };
+  }
+
+  // Fixed extra headers never replace auth or the ones set here.
+  const taken = new Set(Object.keys(headers).map((h) => h.toLowerCase()));
+  for (const [name, value] of Object.entries(t.headers ?? {})) {
+    const n = name.toLowerCase();
+    if (taken.has(n) || RESERVED.has(n)) continue;
+    headers[name] = value;
+  }
+  let body;
+  if (t.body !== undefined) {
+    if (t.method !== "POST" || !CONTENT_TYPES[t.contentType]) return { ...BAD };
+    headers["Content-Type"] = CONTENT_TYPES[t.contentType];
+    body = t.body;
+  }
+
+  const doFetch = opts.fetch ?? globalThis.fetch;
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), opts.timeoutMs ?? 10000);
+  let status;
+  let reply = null;
+  try {
+    const res = await doFetch(url.toString(), { method: t.method, headers, body, signal: ctl.signal, redirect: "manual" });
+    status = res.status;
+    if (status === t.expectStatus && t.failIfJsonHas) reply = await res.text();
+  } catch {
+    return { ok: false, reason: "unreachable" };
+  } finally {
+    clearTimeout(timer);
+  }
+
+  if (status === t.expectStatus) {
+    if (!t.failIfJsonHas) return { ok: true };
+    // The reply is read only to look for the named keys; nothing from it is returned.
+    let parsed;
+    try {
+      parsed = JSON.parse(reply);
+    } catch {
+      return { ok: false, reason: "unexpected", status };
+    }
+    if (parsed === null || typeof parsed !== "object") return { ok: false, reason: "unexpected", status };
+    const hit = t.failIfJsonHas.some((k) => parsed[k] !== undefined && parsed[k] !== null);
+    return hit ? { ok: false, reason: "revoked", status } : { ok: true };
+  }
+  const reason = t.failures[String(status)];
+  return { ok: false, reason: reason ?? "unexpected", status };
+}