@almightygpt/core 0.7.2 → 0.8.0

package/src/auth/keychain.ts

@@ -0,0 +1,132 @@
+/**
+ * OS keychain wrapper — @napi-rs/keyring loaded via DYNAMIC IMPORT.
+ *
+ * The native binary is an OPTIONAL runtime capability:
+ *   - If @napi-rs/keyring is installed and loads → real keychain access
+ *     (macOS Keychain, Windows Credential Manager, Linux Secret Service).
+ *   - If it's NOT installed (optionalDependencies skipped on exotic OS,
+ *     or just plain missing) → returns an unavailable shim. Resolver
+ *     falls through to env vars without crashing.
+ *
+ * This pattern means `npm install almightygpt` NEVER blocks on keychain
+ * binary failure. Codex's review explicitly flagged this as the
+ * correct strategy.
+ *
+ * Service name: `almightygpt` (consistent across all platforms; what
+ * users see in macOS Keychain Access.app, Windows credential UI, etc.)
+ */
+
+import type { ProviderId } from "./types.js";
+
+const KEYCHAIN_SERVICE = "almightygpt";
+
+export interface KeychainAdapter {
+  available: boolean;
+  get(provider: ProviderId): Promise<string | undefined>;
+  set(provider: ProviderId, key: string): Promise<void>;
+  remove(provider: ProviderId): Promise<boolean>;
+  /** Optional diagnostic — backend name, or "unavailable". */
+  describeBackend(): string;
+}
+
+/**
+ * Lazy-loaded singleton. We never throw on import failure; instead the
+ * resulting adapter reports `available: false` and the resolver knows
+ * to skip it.
+ */
+let cached: KeychainAdapter | null = null;
+
+export async function getKeychain(): Promise<KeychainAdapter> {
+  if (cached) return cached;
+  cached = await loadKeychain();
+  return cached;
+}
+
+async function loadKeychain(): Promise<KeychainAdapter> {
+  try {
+    // Dynamic import — never crashes the module if the package is
+    // missing or its native binary fails to load on the host.
+    const mod = (await import("@napi-rs/keyring")) as {
+      Entry: new (service: string, account: string) => {
+        getPassword(): string | null;
+        setPassword(password: string): void;
+        deletePassword(): boolean;
+      };
+    };
+
+    const entryFor = (provider: ProviderId) =>
+      new mod.Entry(KEYCHAIN_SERVICE, provider);
+
+    // Probe: try to construct an Entry. If the native binding throws
+    // (no Secret Service daemon on Linux, etc.), we degrade.
+    try {
+      entryFor("openai");
+    } catch {
+      return makeUnavailable("native binding failed to initialize");
+    }
+
+    return {
+      available: true,
+      describeBackend: () => detectBackend(),
+      async get(provider) {
+        try {
+          const v = entryFor(provider).getPassword();
+          return v === null ? undefined : v;
+        } catch {
+          return undefined;
+        }
+      },
+      async set(provider, key) {
+        entryFor(provider).setPassword(key);
+      },
+      async remove(provider) {
+        try {
+          return entryFor(provider).deletePassword();
+        } catch {
+          return false;
+        }
+      },
+    };
+  } catch (err) {
+    return makeUnavailable(
+      err instanceof Error ? err.message : "import failed",
+    );
+  }
+}
+
+function makeUnavailable(reason: string): KeychainAdapter {
+  return {
+    available: false,
+    describeBackend: () => `unavailable (${reason})`,
+    async get() {
+      return undefined;
+    },
+    async set() {
+      throw new Error(
+        `Keychain unavailable: ${reason}. Set the API key via an environment ` +
+          `variable instead (e.g. ANTHROPIC_API_KEY).`,
+      );
+    },
+    async remove() {
+      return false;
+    },
+  };
+}
+
+function detectBackend(): string {
+  switch (process.platform) {
+    case "darwin":
+      return "macos-keychain";
+    case "win32":
+      return "windows-credential-manager";
+    case "linux":
+      return "linux-secret-service";
+    default:
+      return process.platform;
+  }
+}
+
+/** Exposed for tests that want to reset the singleton between cases. */
+export function _resetKeychainCache(): void {
+  cached = null;
+}

package/src/auth/resolver.ts

@@ -0,0 +1,81 @@
+/**
+ * API key resolver — the single entry point every adapter must call
+ * to find its key. Replaces direct `process.env[...]` reads.
+ *
+ * Priority order (top to bottom):
+ *   1. Explicit parameter (caller passed a key — tests, extension handoff)
+ *   2. Environment variable (per-process override; wins over keychain)
+ *   3. OS keychain (persistent convenience; optional capability)
+ *   4. Missing → throw AuthMissingError
+ *
+ * Env wins over keychain by design — see types.ts header for the
+ * bug-class reasoning that drove the decision.
+ */
+
+import { getKeychain } from "./keychain.js";
+import {
+  AuthMissingError,
+  PROVIDER_ENV_VARS,
+  type KeyResolution,
+  type ProviderId,
+} from "./types.js";
+
+export interface ResolveOptions {
+  /** Optional caller-supplied key — wins over all other sources. */
+  explicit?: string;
+  /** Skip keychain lookup entirely (used by tests). */
+  skipKeychain?: boolean;
+}
+
+/**
+ * Resolve where the API key for `provider` lives.
+ * Returns a KeyResolution describing the source even when not found
+ * (caller can decide whether to throw).
+ */
+export async function resolveApiKey(
+  provider: ProviderId,
+  options: ResolveOptions = {},
+): Promise<KeyResolution> {
+  // 1. Explicit override
+  if (options.explicit) {
+    return { provider, source: "explicit", key: options.explicit };
+  }
+
+  // 2. Environment variable
+  for (const envVar of PROVIDER_ENV_VARS[provider]) {
+    const v = process.env[envVar];
+    if (v && v.length > 0) {
+      return { provider, source: "env", key: v, envVar };
+    }
+  }
+
+  // 3. OS keychain (optional)
+  if (!options.skipKeychain) {
+    const keychain = await getKeychain();
+    if (keychain.available) {
+      const v = await keychain.get(provider);
+      if (v && v.length > 0) {
+        return { provider, source: "keychain", key: v };
+      }
+    }
+  }
+
+  // 4. Missing
+  return { provider, source: "missing" };
+}
+
+/**
+ * Convenience wrapper that throws AuthMissingError on absence — for
+ * callers (adapters) that need the key or can't proceed.
+ */
+export async function requireApiKey(
+  provider: ProviderId,
+  options: ResolveOptions = {},
+): Promise<string> {
+  const resolved = await resolveApiKey(provider, options);
+  if (resolved.source === "missing") {
+    const primaryEnv = PROVIDER_ENV_VARS[provider][0]!;
+    throw new AuthMissingError(provider, primaryEnv);
+  }
+  return resolved.key!;
+}

package/src/auth/types.ts

@@ -0,0 +1,68 @@
+/**
+ * Auth subsystem types — provider identifiers, resolution sources,
+ * error classes.
+ *
+ * The auth module's job is to answer one question per call:
+ * "where is the API key for <provider>, and what is it?"
+ *
+ * Resolution priority (top to bottom):
+ *   1. Explicit parameter (passed by caller — tests, extension handoff)
+ *   2. Environment variable (per-process override; wins over keychain)
+ *   3. OS keychain (persistent convenience; @napi-rs/keyring optional)
+ *   4. Missing -> throw AuthMissingError
+ *
+ * Env-wins-over-keychain is intentional. The original draft had the
+ * order flipped; Codex's independent review caught that it would
+ * silently override the VS Code extension's freshly-stored key with
+ * a stale keychain copy. See docs/claude/v0.8-auth-plan.md.
+ */
+
+export type ProviderId = "openai" | "anthropic" | "google";
+
+export type KeySource = "explicit" | "env" | "keychain" | "missing";
+
+export interface KeyResolution {
+  provider: ProviderId;
+  source: KeySource;
+  /** Present iff source !== "missing". */
+  key?: string;
+  /** Which env var was used (only set when source === "env"). */
+  envVar?: string;
+}
+
+/**
+ * Thrown when no key is found in any source. Caller should surface
+ * the message verbatim — it tells the user exactly how to fix it.
+ */
+export class AuthMissingError extends Error {
+  readonly provider: ProviderId;
+  readonly envVar: string;
+  constructor(provider: ProviderId, envVar: string) {
+    super(
+      `No API key found for ${provider}. ` +
+        `Run "almightygpt auth ${provider}" to set one up interactively, ` +
+        `or export ${envVar} in your shell.`,
+    );
+    this.name = "AuthMissingError";
+    this.provider = provider;
+    this.envVar = envVar;
+  }
+}
+
+/** Maps each provider to the canonical env var name(s) we read. */
+export const PROVIDER_ENV_VARS: Record<ProviderId, readonly string[]> = {
+  openai: ["OPENAI_API_KEY"],
+  anthropic: ["ANTHROPIC_API_KEY"],
+  // Google's SDK historically accepted both names; honor both.
+  google: ["GOOGLE_API_KEY", "GEMINI_API_KEY"],
+};
+
+/**
+ * Browser-launchable URL where a user creates / manages keys for each
+ * provider. Used by the `almightygpt auth <provider>` flow.
+ */
+export const PROVIDER_KEY_URLS: Record<ProviderId, string> = {
+  openai: "https://platform.openai.com/api-keys",
+  anthropic: "https://console.anthropic.com/settings/keys",
+  google: "https://aistudio.google.com/apikey",
+};

package/src/auth/validator.ts

@@ -0,0 +1,145 @@
+/**
+ * Model-level key validation.
+ *
+ * Codex's review caught that listing models (e.g. `GET /v1/models`) can
+ * succeed when the key lacks model permission, has quota issues, or
+ * has billing-state problems. The user doesn't care that list-models
+ * works — they care that AlmightyGPT can run the configured review
+ * model.
+ *
+ * So we validate with the same operation class real reviews use:
+ *   - OpenAI:    tiny chat completion against gpt-4o
+ *   - Anthropic: tiny messages call against claude-sonnet-4-6
+ *   - Google:    tiny generateContent call against gemini-2.5-flash
+ *
+ * Cost is fractions of a cent per call. Latency is ~1-3 seconds.
+ * Failure surfaces the provider's exact error message so the user
+ * can fix it.
+ */
+
+import type { ProviderId } from "./types.js";
+
+export interface ValidationResult {
+  ok: boolean;
+  /** Provider-reported model used (e.g. "gpt-4o-2024-08-06"). */
+  model?: string;
+  /** Provider's error message verbatim if ok === false. */
+  error?: string;
+}
+
+const DEFAULT_VALIDATION_MODELS: Record<ProviderId, string> = {
+  openai: "gpt-4o",
+  anthropic: "claude-sonnet-4-6",
+  google: "gemini-2.5-flash",
+};
+
+const VALIDATION_TIMEOUT_MS = 15_000;
+
+/**
+ * Validate that a key can actually invoke the model real reviews use.
+ * Returns a result object — never throws on validation failure (only
+ * on programmer errors like an unsupported provider).
+ */
+export async function validateKey(
+  provider: ProviderId,
+  key: string,
+): Promise<ValidationResult> {
+  try {
+    switch (provider) {
+      case "openai":
+        return await validateOpenAI(key);
+      case "anthropic":
+        return await validateAnthropic(key);
+      case "google":
+        return await validateGoogle(key);
+    }
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+async function validateOpenAI(key: string): Promise<ValidationResult> {
+  const model = DEFAULT_VALIDATION_MODELS.openai;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), VALIDATION_TIMEOUT_MS);
+  try {
+    const res = await fetch("https://api.openai.com/v1/chat/completions", {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${key}`,
+      },
+      body: JSON.stringify({
+        model,
+        messages: [{ role: "user", content: "hi" }],
+        max_tokens: 1,
+      }),
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      return { ok: false, error: await res.text().catch(() => res.statusText) };
+    }
+    const data = (await res.json()) as { model?: string };
+    return { ok: true, model: data.model ?? model };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function validateAnthropic(key: string): Promise<ValidationResult> {
+  const model = DEFAULT_VALIDATION_MODELS.anthropic;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), VALIDATION_TIMEOUT_MS);
+  try {
+    const res = await fetch("https://api.anthropic.com/v1/messages", {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-api-key": key,
+        "anthropic-version": "2023-06-01",
+      },
+      body: JSON.stringify({
+        model,
+        max_tokens: 5,
+        messages: [{ role: "user", content: "hi" }],
+      }),
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      return { ok: false, error: await res.text().catch(() => res.statusText) };
+    }
+    const data = (await res.json()) as { model?: string };
+    return { ok: true, model: data.model ?? model };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function validateGoogle(key: string): Promise<ValidationResult> {
+  const model = DEFAULT_VALIDATION_MODELS.google;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), VALIDATION_TIMEOUT_MS);
+  try {
+    const url =
+      `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=` +
+      encodeURIComponent(key);
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        contents: [{ parts: [{ text: "hi" }] }],
+        generationConfig: { maxOutputTokens: 5 },
+      }),
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      return { ok: false, error: await res.text().catch(() => res.statusText) };
+    }
+    return { ok: true, model };
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/index.ts

@@ -13,7 +13,7 @@
  *   - budget/     ✅ task #14 BudgetTracker + BudgetExceededError
  */
 
-export const VERSION = "0.7.2";
+export const VERSION = "0.8.0";
 
 // Git safety primitives
 export {
@@ -127,3 +127,24 @@ export type {
   ReviewEventHandler,
   AgentRoleInRun,
 } from "./review/events.js";
+
+// Auth subsystem (v0.8.0+) — resolver, keychain, validator
+export {
+  resolveApiKey,
+  requireApiKey,
+  type ResolveOptions,
+} from "./auth/resolver.js";
+export {
+  getKeychain,
+  _resetKeychainCache,
+  type KeychainAdapter,
+} from "./auth/keychain.js";
+export { validateKey, type ValidationResult } from "./auth/validator.js";
+export {
+  AuthMissingError,
+  PROVIDER_ENV_VARS,
+  PROVIDER_KEY_URLS,
+  type ProviderId,
+  type KeySource,
+  type KeyResolution,
+} from "./auth/types.js";