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

package/lib/vault.d.mts

@@ -0,0 +1,26 @@
+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; platform?: NodeJS.Platform }): Vault;
+export function tooLongFor(value: string, platform?: NodeJS.Platform): string | null;

package/lib/vault.mjs

@@ -0,0 +1,89 @@
+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); },
+  };
+}
+
+// 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();
+
+  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) {
+      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)) {
+          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.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" } }

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