@mandujs/core 0.39.3 → 0.40.1

package/src/brain/credentials.ts

@@ -0,0 +1,396 @@
+/**
+ * Brain — OS keychain adapter for OAuth tokens (Issue #235).
+ *
+ * Zero new dependencies — we shell out to the native secret-store CLI
+ * on each platform, with a filesystem fallback at
+ * `~/.mandu/credentials.json` (mode 0600) when no CLI is available.
+ *
+ *   - macOS   → `security find-generic-password` / `add-generic-password`
+ *   - Windows → `cmdkey` (read) + PowerShell `ConvertFrom-SecureString`
+ *               is too heavyweight; we use a narrow `cmdkey /add` +
+ *               `cmdkey /list` shell dance instead. Windows does NOT let
+ *               `cmdkey` read back the password, so we fall through to
+ *               the filesystem store on Windows and mark it 0600 — the
+ *               file lives under the user profile which is already
+ *               ACL'd to the current user. This matches the behavior of
+ *               `gh auth`, `npm`, and `docker-credential-wincred`
+ *               when run without their companion helper installed.
+ *   - Linux   → `secret-tool store` / `secret-tool lookup` (libsecret).
+ *
+ * API surface is intentionally minimal:
+ *
+ *   - `saveToken(provider, token)`    → persist
+ *   - `loadToken(provider)`           → returns token or null
+ *   - `deleteToken(provider)`         → idempotent delete
+ *   - `listProviders()`               → for `mandu brain status`
+ *
+ * The token type is arbitrary JSON (access_token + refresh_token +
+ * expires_at) — `CredentialStore` serializes it as a JSON string.
+ */
+
+import { promises as fs, constants as fsConstants } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const SERVICE = "mandu-brain";
+const FALLBACK_DIR = path.join(os.homedir(), ".mandu");
+const FALLBACK_FILE = path.join(FALLBACK_DIR, "credentials.json");
+
+/**
+ * Stored token shape. `access_token` is required; the refresh fields
+ * are optional because template-only adapters never write them.
+ */
+export interface StoredToken {
+  access_token: string;
+  refresh_token?: string;
+  /** Unix-epoch seconds when the access_token expires. */
+  expires_at?: number;
+  /** ISO timestamp of last successful use — for `mandu brain status`. */
+  last_used_at?: string;
+  /** Cached default model chosen at login time (override via config). */
+  default_model?: string;
+  /** Scope string returned by the OAuth provider. */
+  scope?: string;
+  /** Provider identifier — for audit. */
+  provider?: "openai" | "anthropic";
+}
+
+/**
+ * Pluggable backend for the credential store. Tests inject an
+ * in-memory backend; production auto-selects by OS.
+ */
+export interface CredentialBackend {
+  readonly name: string;
+  save(provider: string, token: StoredToken): Promise<void>;
+  load(provider: string): Promise<StoredToken | null>;
+  delete(provider: string): Promise<void>;
+  list(): Promise<string[]>;
+}
+
+/* -------------------------------------------------------------------- */
+/* Filesystem fallback — always available, always the safety net.       */
+/* -------------------------------------------------------------------- */
+
+/**
+ * Read the fallback credentials file. Missing file → empty object.
+ * Corrupt file → empty object + a warning to stderr (so a bad edit
+ * does not brick `mandu brain status`).
+ */
+async function readFallback(): Promise<Record<string, StoredToken>> {
+  try {
+    const raw = await fs.readFile(FALLBACK_FILE, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object") {
+      return parsed as Record<string, StoredToken>;
+    }
+    return {};
+  } catch (err) {
+    if (
+      err instanceof Error &&
+      (err as NodeJS.ErrnoException).code === "ENOENT"
+    ) {
+      return {};
+    }
+    // Corrupt JSON — treat as empty, do not throw (Brain never blocks).
+    return {};
+  }
+}
+
+async function writeFallback(all: Record<string, StoredToken>): Promise<void> {
+  await fs.mkdir(FALLBACK_DIR, { recursive: true, mode: 0o700 });
+  const payload = JSON.stringify(all, null, 2);
+  // Write atomically: write to tmp then rename, setting 0600 on the
+  // final file. mode on `writeFile` is advisory on Windows, enforced
+  // on POSIX.
+  const tmp = `${FALLBACK_FILE}.${process.pid}.tmp`;
+  await fs.writeFile(tmp, payload, { mode: 0o600 });
+  await fs.rename(tmp, FALLBACK_FILE);
+  try {
+    await fs.chmod(FALLBACK_FILE, 0o600);
+  } catch {
+    // chmod is best-effort on Windows.
+  }
+}
+
+export const filesystemBackend: CredentialBackend = {
+  name: "filesystem",
+  async save(provider, token) {
+    const all = await readFallback();
+    all[provider] = token;
+    await writeFallback(all);
+  },
+  async load(provider) {
+    const all = await readFallback();
+    return all[provider] ?? null;
+  },
+  async delete(provider) {
+    const all = await readFallback();
+    if (provider in all) {
+      delete all[provider];
+      await writeFallback(all);
+    }
+  },
+  async list() {
+    const all = await readFallback();
+    return Object.keys(all);
+  },
+};
+
+/* -------------------------------------------------------------------- */
+/* Native backends — best-effort; fall through to filesystem on error.  */
+/* -------------------------------------------------------------------- */
+
+/**
+ * Shell out to a binary with a short stdin payload and return stdout.
+ * Never throws — returns `null` on any non-zero exit. We never log the
+ * stderr verbatim because some utilities echo the payload back on
+ * failure.
+ */
+async function runWithStdin(
+  cmd: string,
+  args: string[],
+  stdin: string,
+): Promise<{ ok: boolean; stdout: string } | null> {
+  try {
+    const proc = Bun.spawn([cmd, ...args], {
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    proc.stdin.write(stdin);
+    await proc.stdin.end();
+    const [stdout, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      proc.exited,
+    ]);
+    return { ok: exitCode === 0, stdout };
+  } catch {
+    return null;
+  }
+}
+
+async function runCapture(
+  cmd: string,
+  args: string[],
+): Promise<{ ok: boolean; stdout: string } | null> {
+  try {
+    const proc = Bun.spawn([cmd, ...args], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [stdout, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      proc.exited,
+    ]);
+    return { ok: exitCode === 0, stdout };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * macOS Keychain backend — uses the `security` CLI.
+ *
+ * `security add-generic-password -U -a <provider> -s mandu-brain -w <json>`
+ * to store; `find-generic-password -a <provider> -s mandu-brain -w`
+ * to read the password back. Deletion uses `delete-generic-password`.
+ */
+export const macosBackend: CredentialBackend = {
+  name: "macos-keychain",
+  async save(provider, token) {
+    const payload = JSON.stringify(token);
+    const res = await runCapture("security", [
+      "add-generic-password",
+      "-U", // update if exists
+      "-a",
+      provider,
+      "-s",
+      SERVICE,
+      "-w",
+      payload,
+    ]);
+    if (!res || !res.ok) {
+      // Fall back to filesystem — never let a keychain hiccup block login.
+      await filesystemBackend.save(provider, token);
+    }
+  },
+  async load(provider) {
+    const res = await runCapture("security", [
+      "find-generic-password",
+      "-a",
+      provider,
+      "-s",
+      SERVICE,
+      "-w",
+    ]);
+    if (!res || !res.ok) {
+      return filesystemBackend.load(provider);
+    }
+    try {
+      return JSON.parse(res.stdout.trim()) as StoredToken;
+    } catch {
+      return null;
+    }
+  },
+  async delete(provider) {
+    await runCapture("security", [
+      "delete-generic-password",
+      "-a",
+      provider,
+      "-s",
+      SERVICE,
+    ]);
+    // Also scrub filesystem fallback, in case a previous save hit it.
+    await filesystemBackend.delete(provider);
+  },
+  async list() {
+    // `security` has no "list by service" flag that returns accounts
+    // without the full dump; use filesystem fallback as the source of
+    // truth for the list, since saves always also go through keychain
+    // (or fell back to the file).
+    return filesystemBackend.list();
+  },
+};
+
+/**
+ * Linux libsecret backend — `secret-tool`.
+ */
+export const linuxBackend: CredentialBackend = {
+  name: "linux-secret-tool",
+  async save(provider, token) {
+    const payload = JSON.stringify(token);
+    const res = await runWithStdin(
+      "secret-tool",
+      ["store", "--label=mandu-brain", "service", SERVICE, "account", provider],
+      payload,
+    );
+    if (!res || !res.ok) {
+      await filesystemBackend.save(provider, token);
+    }
+  },
+  async load(provider) {
+    const res = await runCapture("secret-tool", [
+      "lookup",
+      "service",
+      SERVICE,
+      "account",
+      provider,
+    ]);
+    if (!res || !res.ok || res.stdout.trim().length === 0) {
+      return filesystemBackend.load(provider);
+    }
+    try {
+      return JSON.parse(res.stdout.trim()) as StoredToken;
+    } catch {
+      return null;
+    }
+  },
+  async delete(provider) {
+    await runCapture("secret-tool", [
+      "clear",
+      "service",
+      SERVICE,
+      "account",
+      provider,
+    ]);
+    await filesystemBackend.delete(provider);
+  },
+  async list() {
+    return filesystemBackend.list();
+  },
+};
+
+/**
+ * Windows — `cmdkey` can store but cannot read back the password
+ * portion without the Credential Manager API (which we would need a
+ * native binding for). Use filesystem fallback directly; the file
+ * lives under `%USERPROFILE%\.mandu\credentials.json` which is ACL'd
+ * to the current user by default. This matches the behavior of
+ * `gh auth login` when the Git Credential Manager is not installed.
+ */
+export const windowsBackend: CredentialBackend = {
+  name: "windows-filesystem",
+  save: filesystemBackend.save,
+  load: filesystemBackend.load,
+  delete: filesystemBackend.delete,
+  list: filesystemBackend.list,
+};
+
+/**
+ * Pick the best backend for the current platform. Tests override this
+ * by constructing a `CredentialStore` with an explicit backend.
+ */
+export function pickPlatformBackend(): CredentialBackend {
+  if (process.platform === "darwin") return macosBackend;
+  if (process.platform === "win32") return windowsBackend;
+  if (process.platform === "linux") return linuxBackend;
+  return filesystemBackend;
+}
+
+/* -------------------------------------------------------------------- */
+/* Public store                                                         */
+/* -------------------------------------------------------------------- */
+
+export class CredentialStore {
+  constructor(private backend: CredentialBackend = pickPlatformBackend()) {}
+
+  /** Which backend is active — surfaced in `mandu brain status`. */
+  get backendName(): string {
+    return this.backend.name;
+  }
+
+  async save(provider: string, token: StoredToken): Promise<void> {
+    await this.backend.save(provider, token);
+  }
+
+  async load(provider: string): Promise<StoredToken | null> {
+    return this.backend.load(provider);
+  }
+
+  async delete(provider: string): Promise<void> {
+    await this.backend.delete(provider);
+  }
+
+  async list(): Promise<string[]> {
+    return this.backend.list();
+  }
+
+  /**
+   * Touch the last_used_at timestamp on an existing token without
+   * rotating the secret. Best-effort — swallow errors (telemetry).
+   */
+  async touch(provider: string): Promise<void> {
+    try {
+      const tok = await this.load(provider);
+      if (tok) {
+        tok.last_used_at = new Date().toISOString();
+        await this.save(provider, tok);
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+
+  /**
+   * File path of the filesystem fallback — used by tests + the CLI
+   * `mandu brain status` to point users at the 0600 file. Always
+   * returns the same path regardless of backend.
+   */
+  static fallbackPath(): string {
+    return FALLBACK_FILE;
+  }
+}
+
+/** Default singleton — production path. */
+let defaultStore: CredentialStore | null = null;
+export function getCredentialStore(): CredentialStore {
+  if (!defaultStore) {
+    defaultStore = new CredentialStore();
+  }
+  return defaultStore;
+}
+
+/** Override the singleton (test affordance). */
+export function setCredentialStore(store: CredentialStore): void {
+  defaultStore = store;
+}

package/src/brain/index.ts

@@ -10,9 +10,47 @@
 // Types
 export * from "./types";
 
-// Adapters
+// Adapters (includes Ollama, OpenAI OAuth, Anthropic OAuth, and the
+// `createBrainAdapter` / `resolveBrainAdapter` resolver — Issue #235).
 export * from "./adapters";
 
+// Credential store (OS keychain + filesystem fallback).
+export {
+  CredentialStore,
+  getCredentialStore,
+  setCredentialStore,
+  filesystemBackend,
+  macosBackend,
+  linuxBackend,
+  windowsBackend,
+  pickPlatformBackend,
+  type CredentialBackend,
+  type StoredToken,
+} from "./credentials";
+
+// Consent prompt + cache (Issue #235).
+export {
+  ensureConsent,
+  hasConsent,
+  grantConsent,
+  revokeConsent,
+  fingerprintProject,
+  consentFilePath,
+  type ConsentContext,
+  type ConsentEntry,
+  type ConsentProvider,
+  type ConsentPromptDeps,
+} from "./consent";
+
+// Redactor (pre-transmission secret scrubbing — Issue #235).
+export {
+  redact,
+  redactSecrets,
+  type RedactionHit,
+  type RedactionKind,
+  type RedactionResult,
+} from "./redactor";
+
 // Permissions
 export {
   detectEnvironment,

package/src/brain/redactor.ts

@@ -0,0 +1,196 @@
+/**
+ * Brain — pre-transmission secret redactor (Issue #235)
+ *
+ * Every payload destined for a cloud adapter is passed through
+ * `redactSecrets()` FIRST. The function returns:
+ *
+ *   - `{ redacted, hits }` — redacted payload + list of what matched, so
+ *     the CLI / adapter can print an audit line and append to
+ *     `.mandu/brain-redactions.jsonl` for user inspection.
+ *
+ * Design principles (user feedback — Mandu as connector, not owner):
+ *   - Mandu NEVER transmits a prompt without passing it through here.
+ *   - Patterns are conservative (false positives preferred over leaks).
+ *   - No regex is anchored; we scan the full text so embedded secrets
+ *     inside a diff block are still caught.
+ *   - All replacements collapse to a single token `[[REDACTED:<kind>]]`
+ *     so the cloud model sees a stable shape rather than a mangled
+ *     partial key that could still be reconstructed.
+ *
+ * @see docs/brain/oauth-adapters.md (if that ever ships — for now this
+ *   file + its tests are the source of truth).
+ */
+export type RedactionKind =
+  | "openai-key"
+  | "stripe-key"
+  | "github-token"
+  | "slack-token"
+  | "aws-key"
+  | "bearer-token"
+  | "env-ref"
+  | "api-key-assignment"
+  | "jwt"
+  | "long-base64";
+
+export interface RedactionHit {
+  /** The kind of secret matched (for audit logging). */
+  kind: RedactionKind;
+  /** Byte offset into the original input where the match started. */
+  start: number;
+  /** Byte offset into the original input where the match ended. */
+  end: number;
+  /**
+   * Short sample of the redacted material — always prefix + ellipsis,
+   * never the full secret. Safe to log.
+   */
+  sample: string;
+}
+
+export interface RedactionResult {
+  /** Input with every match replaced by `[[REDACTED:<kind>]]`. */
+  redacted: string;
+  /** One entry per match, in scan order. */
+  hits: RedactionHit[];
+}
+
+/**
+ * Ordered pattern list. Earlier patterns win — specific formats (e.g.
+ * `sk-...`) are checked before the generic "long base64" fallback so
+ * their `kind` tag is accurate.
+ *
+ * Every pattern is intentionally over-conservative — we would rather
+ * redact a false-positive hash than leak a real key. Users can inspect
+ * `.mandu/brain-redactions.jsonl` to spot over-redaction.
+ */
+const PATTERNS: Array<{ kind: RedactionKind; regex: RegExp }> = [
+  // OpenAI-style keys: sk-XXXX, sk-proj-XXXX, pk-XXXX.
+  { kind: "openai-key", regex: /\b(?:sk|pk)-(?:proj-)?[A-Za-z0-9_\-]{16,}\b/g },
+  // Stripe live/test keys.
+  { kind: "stripe-key", regex: /\brk_(?:live|test)_[A-Za-z0-9]{16,}\b/g },
+  // GitHub PATs — ghp_, gho_, ghu_, ghs_, ghr_.
+  { kind: "github-token", regex: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g },
+  // Slack bot / user tokens.
+  { kind: "slack-token", regex: /\bxox[abpors]-[A-Za-z0-9-]{10,}\b/g },
+  // AWS access key id (fixed-width 20 char uppercase starting w/ AKIA / ASIA).
+  { kind: "aws-key", regex: /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g },
+  // Authorization: Bearer ...
+  {
+    kind: "bearer-token",
+    regex: /(?:Authorization:\s*)?\bBearer\s+[A-Za-z0-9._\-]{16,}/gi,
+  },
+  // `.env` path references — we redact the path itself, not the
+  // surrounding sentence. "see .env" → "see [[REDACTED:env-ref]]".
+  // Trailing lookahead matches sentence punctuation / whitespace /
+  // end-of-string so "see .env." / ".env.production." both redact.
+  { kind: "env-ref", regex: /\.env(?:\.[a-z]+)?(?=[\s,.;:!?'")`]|$)/g },
+  // KEY="value" / KEY=value assignments, where KEY contains
+  // API_KEY/SECRET/TOKEN/PASSWORD. Matches the whole assignment.
+  {
+    kind: "api-key-assignment",
+    regex:
+      /\b[A-Z][A-Z0-9_]*(?:API_KEY|SECRET|TOKEN|PASSWORD|PASSWD)[A-Z0-9_]*\s*=\s*["']?[^\s"'\n]+["']?/g,
+  },
+  // JWTs (three base64url segments separated by dots).
+  {
+    kind: "jwt",
+    regex: /\beyJ[A-Za-z0-9_\-]{10,}\.[A-Za-z0-9_\-]{10,}\.[A-Za-z0-9_\-]{10,}\b/g,
+  },
+  // Generic long base64/hex blob (20+ chars, mixed case or digit-heavy).
+  // Runs last so more specific kinds claim first.
+  {
+    kind: "long-base64",
+    regex: /\b[A-Za-z0-9+/=_\-]{24,}\b/g,
+  },
+];
+
+/**
+ * Sample a match for audit logging — never return the full secret.
+ *
+ * Returns `"<first 4 chars>...<last 2 chars>"` for entries longer
+ * than 8 characters, and a hard-coded stub otherwise. The sample is
+ * deliberately short so it cannot be used to reconstruct the key.
+ */
+function sampleOf(match: string): string {
+  if (match.length <= 8) return "***";
+  return `${match.slice(0, 4)}...${match.slice(-2)}`;
+}
+
+/**
+ * Scan `input` for secrets and return a redacted copy + hit list.
+ *
+ * The scan is non-overlapping: once a region is claimed by an earlier
+ * pattern, later patterns cannot match inside it. This is enforced by
+ * walking the hit set and rebuilding the string in one pass rather than
+ * running `.replace()` per-pattern (which would allow the generic
+ * "long-base64" to fire on the already-inserted `[[REDACTED:...]]`
+ * marker).
+ *
+ * @param input Raw text about to be transmitted to a cloud adapter.
+ * @returns Redacted text plus audit-safe hit list.
+ */
+export function redactSecrets(input: string): RedactionResult {
+  if (!input || input.length === 0) {
+    return { redacted: input ?? "", hits: [] };
+  }
+
+  // 1. Collect every candidate hit across every pattern.
+  const raw: RedactionHit[] = [];
+  for (const { kind, regex } of PATTERNS) {
+    regex.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = regex.exec(input)) !== null) {
+      if (m[0].length === 0) {
+        regex.lastIndex += 1;
+        continue;
+      }
+      raw.push({
+        kind,
+        start: m.index,
+        end: m.index + m[0].length,
+        sample: sampleOf(m[0]),
+      });
+    }
+  }
+
+  if (raw.length === 0) {
+    return { redacted: input, hits: [] };
+  }
+
+  // 2. Sort by start offset; on tie prefer the earlier pattern (which
+  // means the more specific kind since PATTERNS is ordered).
+  raw.sort((a, b) => (a.start - b.start) || (a.end - b.end));
+
+  // 3. Greedy non-overlap: keep the first match; skip anything that
+  // starts before the last accepted match ended.
+  const accepted: RedactionHit[] = [];
+  let cursor = -1;
+  for (const h of raw) {
+    if (h.start < cursor) continue;
+    accepted.push(h);
+    cursor = h.end;
+  }
+
+  // 4. Rebuild the output in one pass.
+  let out = "";
+  let i = 0;
+  for (const h of accepted) {
+    out += input.slice(i, h.start);
+    out += `[[REDACTED:${h.kind}]]`;
+    i = h.end;
+  }
+  out += input.slice(i);
+
+  return { redacted: out, hits: accepted };
+}
+
+/**
+ * Convenience — returns only the redacted string.
+ *
+ * Use `redactSecrets()` directly when you also need the hit list (for
+ * audit logging). Use this when you just want "scrub and forward".
+ */
+export function redact(input: string): string {
+  return redactSecrets(input).hits.length === 0
+    ? input
+    : redactSecrets(input).redacted;
+}

package/src/config/mandu.ts

@@ -618,6 +618,45 @@ export interface ManduConfig {
     /** Domain → locale map; required when strategy === "domain". */
     domains?: Record<string, LocaleCode>;
   };
+  /**
+   * Issue #235 — Brain LLM adapter selection.
+   *
+   * Mandu is a CONNECTOR for third-party LLMs, not an LLM owner. Cloud
+   * adapters forward requests using the user's own OAuth credentials,
+   * obtained via `mandu brain login --provider=<name>` and stored in
+   * the OS keychain. No API keys ever live in Mandu's process memory;
+   * Mandu-controlled billing is not a thing.
+   *
+   * Fields:
+   *   - `adapter`          — Which connector to use. Default `"auto"`.
+   *                          Auto resolves in priority order:
+   *                          openai → anthropic → ollama → template.
+   *                          Explicit values pin the choice but still
+   *                          degrade to template when the dependency is
+   *                          unreachable (no hard failures).
+   *   - `openai.model`     — Override the OpenAI model (default
+   *                          `"gpt-4o-mini"`).
+   *   - `anthropic.model`  — Override the Anthropic model (default
+   *                          `"claude-haiku-4-5-20251001"`).
+   *   - `ollama.model`     — Override the local Ollama model (default
+   *                          `"ministral-3:3b"`).
+   *   - `telemetryOptOut`  — When `true`, cloud adapters are disabled
+   *                          entirely regardless of stored tokens. The
+   *                          resolver falls to ollama/template. Use for
+   *                          privacy-strict environments.
+   *
+   * Omitting this block is equivalent to `{ adapter: "auto" }`.
+   *
+   * @see `@mandujs/core/brain/adapters` for the resolver implementation.
+   * @see `docs/brain/oauth-adapters.md` (when authored).
+   */
+  brain?: {
+    adapter?: "auto" | "openai" | "anthropic" | "ollama" | "template";
+    openai?: { model?: string };
+    anthropic?: { model?: string };
+    ollama?: { model?: string; baseUrl?: string };
+    telemetryOptOut?: boolean;
+  };
 }
 
 export const CONFIG_FILES = [