@getfootgun/keys 0.0.0-stage → 0.1.0

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 };
+}

package/lib/vault.d.mts

@@ -0,0 +1,25 @@
+export interface KeyStore {
+  get(account: string): Promise<string | null>;
+  set(account: string, value: string): Promise<void>;
+  delete(account: string): Promise<void>;
+}
+export interface IndexEntry {
+  provider: string;
+  label: string;
+  envVar: string;
+  secret: boolean;
+  createdAt: string;
+  projects: string[];
+  health: { ok: boolean; reason?: string; checkedAt: string } | null;
+}
+export interface Vault {
+  put(provider: string, label: string, envVar: string, value: string, secret: boolean): Promise<void>;
+  get(provider: string, label: string, envVar: string): Promise<string | null>;
+  list(): Promise<IndexEntry[]>;
+  forProvider(provider: string, label?: string): Promise<IndexEntry[]>;
+  addProject(provider: string, label: string, envVar: string, projectPath: string): Promise<void>;
+  setHealth(provider: string, label: string, envVar: string, health: NonNullable<IndexEntry["health"]>): Promise<void>;
+}
+export function keychainStore(): KeyStore;
+export function memoryStore(): KeyStore;
+export function openVault(opts: { store: KeyStore; home?: string }): Vault;

package/lib/vault.mjs

@@ -0,0 +1,77 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Entry } from "@napi-rs/keyring";
+import { supportDir, ensureSupportDir, writePrivate } from "./paths.mjs";
+
+const SERVICE = "footgun-keys";
+const account = (provider, label, envVar) => `${provider}/${label}/${envVar}`;
+
+export function keychainStore() {
+  const entry = (a) => new Entry(SERVICE, a);
+  return {
+    async get(a) { return entry(a).getPassword() ?? null; },
+    async set(a, value) { entry(a).setPassword(value); },
+    async delete(a) { entry(a).deletePassword(); },
+  };
+}
+
+export function memoryStore() {
+  const m = new Map();
+  return {
+    async get(a) { return m.has(a) ? m.get(a) : null; },
+    async set(a, value) { m.set(a, value); },
+    async delete(a) { m.delete(a); },
+  };
+}
+
+export function openVault({ store, home }) {
+  const file = join(supportDir(home), "index.json");
+  let queue = Promise.resolve();
+
+  async function read() {
+    try { return JSON.parse(await readFile(file, "utf8")); }
+    catch (e) { if (e.code === "ENOENT") return []; throw e; }
+  }
+  // Serialize read-modify-write so concurrent calls cannot lose updates.
+  function mutate(fn) {
+    const run = queue.then(async () => {
+      await ensureSupportDir(home);
+      const entries = await read();
+      await fn(entries);
+      await writePrivate(file, JSON.stringify(entries, null, 2));
+    });
+    queue = run.catch(() => {});
+    return run;
+  }
+  const find = (entries, p, l, e) => entries.find((x) => x.provider === p && x.label === l && x.envVar === e);
+
+  return {
+    async put(provider, label, envVar, value, secret) {
+      await store.set(account(provider, label, envVar), value);
+      await mutate((entries) => {
+        if (!find(entries, provider, label, envVar)) {
+          entries.push({ provider, label, envVar, secret, createdAt: new Date().toISOString(), projects: [], health: null });
+        } else {
+          find(entries, provider, label, envVar).secret = secret;
+        }
+      });
+    },
+    get(provider, label, envVar) { return store.get(account(provider, label, envVar)); },
+    async list() { return read(); },
+    async forProvider(provider, label = "default") {
+      return (await read()).filter((x) => x.provider === provider && x.label === label);
+    },
+    addProject(provider, label, envVar, projectPath) {
+      return mutate((entries) => {
+        const e = find(entries, provider, label, envVar);
+        if (e && !e.projects.includes(projectPath)) e.projects.push(projectPath);
+      });
+    },
+    setHealth(provider, label, envVar, health) {
+      return mutate((entries) => {
+        const e = find(entries, provider, label, envVar);
+        if (e) e.health = health;
+      });
+    },
+  };
+}

package/package.json

@@ -1,6 +1 @@
-{
-  "name": "@getfootgun/keys",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{ "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" } }

package/shared/contract.d.mts

@@ -0,0 +1,36 @@
+import type { KeysEntitlement, GuideBody } from "./types";
+
+export const MESSAGE_TYPES: readonly ["hello", "guide", "session", "save"];
+export const SESSION_RE: RegExp;
+export const MAX_VALUE: number;
+export const LABEL_RE: RegExp;
+export const FREE_GUIDES: readonly string[];
+
+export type HelloRequest = { type: "hello" };
+export type GuideRequest = { type: "guide"; slug: string };
+export type SessionRequest = { type: "session"; id: string };
+export type SaveRequest = {
+  type: "save";
+  session?: string;
+  guide: string;
+  version: number;
+  label: string;
+  values: { envVar: string; value: string }[];
+  final: boolean;
+};
+export type KeysRequest = HelloRequest | GuideRequest | SessionRequest | SaveRequest;
+
+export type HelloResponse = { ok: true; helperVersion: string; signedIn: boolean; entitlement: KeysEntitlement | null };
+export type GuideResponse =
+  | { ok: true; guide: GuideBody; version: number; status: string }
+  | { ok: false; error: string; upgradeUrl?: string };
+export type SessionResponse =
+  | { ok: true; provider: string; envVars: string[] }
+  | { ok: false; error: "unknown session" | "expired" };
+export type SaveResponse =
+  | { ok: true; saved: string[]; wrote?: { file: string; addedGitignore: boolean }; test?: { ok: boolean; reason?: string } }
+  | { ok: false; error: string };
+export type BadMessageResponse = { ok: false; error: "bad message" };
+export type KeysResponse = HelloResponse | GuideResponse | SessionResponse | SaveResponse | BadMessageResponse;
+
+export function validateRequest(msg: unknown): { ok: true; req: KeysRequest } | { ok: false };

package/shared/contract.mjs

@@ -0,0 +1,49 @@
+// Native messaging contract between the Chrome extension and the Mac helper.
+
+export const MESSAGE_TYPES = ["hello", "guide", "session", "save"];
+export const SESSION_RE = /^[A-Za-z0-9_-]{16,64}$/;
+export const MAX_VALUE = 4096;
+// Guides free on every plan. Same list as lib/keys/guide.ts (a test keeps them equal).
+export const FREE_GUIDES = ["openai", "anthropic", "google-ai-studio", "stripe", "resend", "supabase", "github", "vercel"];
+
+const ENV_VAR = /^[A-Z][A-Z0-9_]*$/;
+export const LABEL_RE = /^[A-Za-z0-9 ._-]{1,64}$/;
+const SLUG = /^[a-z0-9-]+$/;
+const KEYS = {
+  hello: [[], []],
+  guide: [["slug"], []],
+  session: [["id"], []],
+  save: [["guide", "version", "label", "values", "final"], ["session"]],
+};
+
+const isObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+
+function validValue(v) {
+  return isObject(v) && Object.keys(v).length === 2 && typeof v.envVar === "string" && ENV_VAR.test(v.envVar)
+    && typeof v.value === "string" && v.value.length > 0 && v.value.length <= MAX_VALUE;
+}
+
+export function validateRequest(msg) {
+  if (!isObject(msg) || typeof msg.type !== "string" || !MESSAGE_TYPES.includes(msg.type)) return { ok: false };
+  const [required, optional] = KEYS[msg.type];
+  const keys = Object.keys(msg).filter((k) => k !== "type");
+  if (keys.some((k) => !required.includes(k) && !optional.includes(k))) return { ok: false };
+  if (required.some((k) => !Object.hasOwn(msg, k))) return { ok: false };
+  switch (msg.type) {
+    case "guide":
+      if (typeof msg.slug !== "string" || msg.slug.length > 100 || !SLUG.test(msg.slug)) return { ok: false };
+      break;
+    case "session":
+      if (typeof msg.id !== "string" || !SESSION_RE.test(msg.id)) return { ok: false };
+      break;
+    case "save":
+      if (Object.hasOwn(msg, "session") && (typeof msg.session !== "string" || !SESSION_RE.test(msg.session))) return { ok: false };
+      if (typeof msg.guide !== "string" || msg.guide.length > 100 || !SLUG.test(msg.guide)) return { ok: false };
+      if (!Number.isInteger(msg.version) || msg.version < 1) return { ok: false };
+      if (typeof msg.label !== "string" || !LABEL_RE.test(msg.label)) return { ok: false };
+      if (!Array.isArray(msg.values) || !msg.values.every(validValue)) return { ok: false };
+      if (typeof msg.final !== "boolean") return { ok: false };
+      break;
+  }
+  return { ok: true, req: msg };
+}

package/shared/extension-id.json

@@ -0,0 +1,5 @@
+{
+  "ids": [
+    "cippejafibclbiifcljjikkpppfelhpe"
+  ]
+}

package/shared/extension-ids.d.mts

@@ -0,0 +1 @@
+export const EXTENSION_IDS: string[];

package/shared/extension-ids.mjs

@@ -0,0 +1,13 @@
+// Node-only: the Chrome extension ids the helper trusts. Kept out of contract.mjs so that file stays browser-safe.
+import { readFileSync } from "node:fs";
+
+function loadIds() {
+  let ids = [];
+  try {
+    const j = JSON.parse(readFileSync(new URL("./extension-id.json", import.meta.url), "utf8"));
+    if (Array.isArray(j.ids)) ids = j.ids.filter((x) => typeof x === "string");
+  } catch { /* file absent until the extension is built */ }
+  if (process.env.FOOTGUN_KEYS_EXTENSION_ID) ids.push(process.env.FOOTGUN_KEYS_EXTENSION_ID);
+  return ids;
+}
+export const EXTENSION_IDS = loadIds();

package/shared/types.d.ts

@@ -0,0 +1,60 @@
+// Plain TypeScript copies of server types, so the helper and the extension need no zod.
+// Sources: KeysEntitlement and KeysTool from lib/keys/entitlement.ts, GuideBody from lib/keys/guide.ts (guideBodySchema).
+// Keep in sync by hand when those change.
+
+export type KeysTool = "keys_list" | "keys_write_env" | "keys_request" | "keys_check" | "keys_guides";
+
+export type KeysEntitlement = {
+  plan: "free" | "pro" | "team";
+  allGuides: boolean;
+  tools: KeysTool[];
+  health: boolean;
+  launchFree: boolean;
+  checkedAt: string;
+};
+
+export type GuideStep = {
+  id: string;
+  instruction: string;
+  url?: string;
+  target?: { selectors: string[]; text?: string };
+  trap?: string;
+};
+
+export type GuideCapture = {
+  step: string;
+  pattern: string;
+  envVar: string;
+  label: string;
+  secret: boolean;
+};
+
+export type GuideTestAuth =
+  | { type: "bearer"; envVar: string }
+  | { type: "header"; name: string; envVar: string }
+  | { type: "basic"; userEnvVar: string; passEnvVar: string }
+  | { type: "query"; name: string; envVar: string }
+  | { type: "none" };
+
+export type GuideTest = {
+  method: "GET" | "POST";
+  url: string;
+  auth: GuideTestAuth;
+  headers?: Record<string, string>;
+  body?: string;
+  contentType?: "json" | "form";
+  expectStatus: number;
+  failures: Record<string, "revoked" | "out_of_credit" | "rate_limited" | "unreachable">;
+  failIfJsonHas?: string[];
+};
+
+export type GuideBody = {
+  slug: string;
+  name: string;
+  tier: "free" | "pro";
+  docsUrl: string;
+  domains: string[];
+  steps: GuideStep[];
+  captures: GuideCapture[];
+  test: GuideTest | null;
+};