@mandujs/core 0.39.3 → 0.40.1

package/src/brain/adapters/openai-oauth.ts

@@ -0,0 +1,463 @@
+/**
+ * Brain — OpenAI OAuth adapter (Issue #235).
+ *
+ * Connects to the OpenAI Chat Completions API using a token obtained
+ * via OAuth authorization code + PKCE. Mandu never owns an OpenAI API
+ * key — the user's OAuth credentials are loaded from the OS keychain
+ * (`packages/core/src/brain/credentials.ts`) and forwarded on each
+ * request.
+ *
+ * Failure modes handled here:
+ *   - Missing token            → adapter reports `available: false`, the
+ *                                resolver falls to the next tier.
+ *   - 401 on complete()        → one silent refresh attempt. On repeat
+ *                                failure the token is deleted and the
+ *                                adapter returns an empty completion,
+ *                                letting Brain fall back to template.
+ *   - Network / 5xx            → surfaced as an Error (isolated by Brain
+ *                                via `isolatedBrainExecution`).
+ *
+ * Redaction is applied to every prompt BEFORE it hits `fetch`. Redacted
+ * hits are appended to `<projectRoot>/.mandu/brain-redactions.jsonl`
+ * for user audit. A consent prompt runs on the first cloud call per
+ * (provider, project).
+ */
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+import { BaseLLMAdapter } from "./base";
+import type {
+  AdapterConfig,
+  AdapterStatus,
+  ChatMessage,
+  CompletionOptions,
+  CompletionResult,
+} from "../types";
+import {
+  CredentialStore,
+  getCredentialStore,
+  type StoredToken,
+} from "../credentials";
+import {
+  ensureConsent,
+  type ConsentPromptDeps,
+} from "../consent";
+import { redactSecrets } from "../redactor";
+import {
+  refreshAccessToken,
+  runAuthorizationCodeFlow,
+  type HttpClient,
+  type OAuthEndpoints,
+} from "./oauth-flow";
+
+/* -------------------------------------------------------------------- */
+/* Defaults                                                             */
+/* -------------------------------------------------------------------- */
+
+/**
+ * OpenAI OAuth endpoints. These mirror the ChatGPT developer OAuth
+ * surface documented at platform.openai.com/oauth. Tests + CI override
+ * via `options.endpoints` so this module never dials the real host in
+ * unit tests.
+ */
+export const OPENAI_OAUTH_ENDPOINTS: OAuthEndpoints = {
+  authorizationUrl: "https://platform.openai.com/oauth/authorize",
+  tokenUrl: "https://platform.openai.com/oauth/token",
+};
+
+/**
+ * OpenAI OAuth public client id. Registered by Mandu; no secret is
+ * required (PKCE covers the exchange). The client id is not sensitive;
+ * it is already embedded in every authorization URL the user clicks.
+ */
+export const OPENAI_OAUTH_CLIENT_ID = "mandu-brain-cli";
+export const OPENAI_OAUTH_SCOPE = "openai.chat";
+
+/**
+ * Default model — GPT-5.4 (current-generation OpenAI flagship as of
+ * 2026-04). Gives brain doctor triage the quality it needs to produce
+ * actionable patches, which was the whole motivation for moving off
+ * the local ministral-3:3b adapter. Override via
+ * `ManduConfig.brain.openai.model` (e.g. set to a cheaper tier for
+ * low-stakes automated runs).
+ */
+export const OPENAI_DEFAULT_MODEL = "gpt-5.4";
+export const OPENAI_API_BASE = "https://api.openai.com/v1";
+
+export const DEFAULT_OPENAI_CONFIG: AdapterConfig = {
+  baseUrl: OPENAI_API_BASE,
+  model: OPENAI_DEFAULT_MODEL,
+  timeout: 60_000,
+};
+
+/* -------------------------------------------------------------------- */
+/* Options                                                              */
+/* -------------------------------------------------------------------- */
+
+export interface OpenAIOAuthAdapterOptions extends Partial<AdapterConfig> {
+  /** Injection point — tests supply an in-memory fetch stub. */
+  httpClient?: HttpClient;
+  /** Injection point — tests swap in a canned endpoint pair. */
+  endpoints?: OAuthEndpoints;
+  /** OAuth client id override (for enterprise OpenAI proxies). */
+  clientId?: string;
+  /** OAuth scope override. */
+  scope?: string;
+  /** Credential store — default singleton; tests inject an in-memory one. */
+  credentialStore?: CredentialStore;
+  /** Project root — consent prompts are scoped per-project. */
+  projectRoot?: string;
+  /** Force-disable the consent prompt (telemetryOptOut path). */
+  skipConsent?: boolean;
+  /** Consent-prompt deps (stdout, readline) — test injection. */
+  consentDeps?: ConsentPromptDeps;
+  /**
+   * When true, attempted adapter use without a token throws instead of
+   * silently returning `available: false`. Used by the CLI `brain login`
+   * command to loudly fail if the flow never wrote a token.
+   */
+  strict?: boolean;
+}
+
+/* -------------------------------------------------------------------- */
+/* Adapter                                                              */
+/* -------------------------------------------------------------------- */
+
+export class OpenAIOAuthAdapter extends BaseLLMAdapter {
+  readonly name = "openai-oauth";
+  private httpClient: HttpClient;
+  private endpoints: OAuthEndpoints;
+  private clientId: string;
+  private scope: string;
+  private credentialStore: CredentialStore;
+  private projectRoot: string;
+  private skipConsent: boolean;
+  private consentDeps?: ConsentPromptDeps;
+  private strict: boolean;
+  private refreshInFlight: Promise<StoredToken | null> | null = null;
+
+  constructor(options: OpenAIOAuthAdapterOptions = {}) {
+    super({
+      ...DEFAULT_OPENAI_CONFIG,
+      ...options,
+    });
+    this.httpClient =
+      options.httpClient ?? globalThis.fetch.bind(globalThis);
+    this.endpoints = options.endpoints ?? OPENAI_OAUTH_ENDPOINTS;
+    this.clientId = options.clientId ?? OPENAI_OAUTH_CLIENT_ID;
+    this.scope = options.scope ?? OPENAI_OAUTH_SCOPE;
+    this.credentialStore = options.credentialStore ?? getCredentialStore();
+    this.projectRoot = options.projectRoot ?? process.cwd();
+    this.skipConsent = options.skipConsent ?? false;
+    this.consentDeps = options.consentDeps;
+    this.strict = options.strict ?? false;
+  }
+
+  /* ----------------------- Status / login ---------------------------- */
+
+  async checkStatus(): Promise<AdapterStatus> {
+    const token = await this.credentialStore.load("openai");
+    if (!token) {
+      return {
+        available: false,
+        model: null,
+        error:
+          "No OpenAI OAuth token stored. Run `mandu brain login --provider=openai` first.",
+      };
+    }
+    return {
+      available: true,
+      model: this.config.model,
+    };
+  }
+
+  /**
+   * Run the authorization-code + PKCE flow and persist the token.
+   * Returns the stored token shape on success.
+   */
+  async login(
+    opts: {
+      onAuthUrl?: (url: string) => void;
+      openBrowser?: (url: string) => Promise<void> | void;
+      timeoutMs?: number;
+    } = {},
+  ): Promise<StoredToken> {
+    const tokenResponse = await runAuthorizationCodeFlow({
+      endpoints: this.endpoints,
+      client: { clientId: this.clientId, scope: this.scope },
+      httpClient: this.httpClient,
+      onAuthUrl: opts.onAuthUrl,
+      openBrowser: opts.openBrowser,
+      timeoutMs: opts.timeoutMs,
+    });
+
+    const stored: StoredToken = {
+      access_token: tokenResponse.access_token,
+      refresh_token: tokenResponse.refresh_token,
+      expires_at:
+        typeof tokenResponse.expires_in === "number"
+          ? Math.floor(Date.now() / 1000) + tokenResponse.expires_in
+          : undefined,
+      scope: tokenResponse.scope ?? this.scope,
+      default_model: this.config.model,
+      provider: "openai",
+      last_used_at: new Date().toISOString(),
+    };
+    await this.credentialStore.save("openai", stored);
+    return stored;
+  }
+
+  /** Delete the stored token. Idempotent. */
+  async logout(): Promise<void> {
+    await this.credentialStore.delete("openai");
+  }
+
+  /* ------------------------ Completion ------------------------------- */
+
+  async complete(
+    messages: ChatMessage[],
+    options: CompletionOptions = {},
+  ): Promise<CompletionResult> {
+    const token = await this.loadTokenOrReject();
+    if (!token) {
+      if (this.strict) {
+        throw new Error(
+          "OpenAIOAuthAdapter.complete() called without a stored token",
+        );
+      }
+      return emptyCompletion();
+    }
+
+    // Consent prompt — skipped when telemetryOptOut is active (the
+    // resolver never constructs us in that case) OR when the caller
+    // has already vetted consent out of band.
+    if (!this.skipConsent) {
+      const ok = await ensureConsent(
+        {
+          projectRoot: this.projectRoot,
+          provider: "openai",
+          model: this.config.model,
+          payloadDescription: describeChatPayload(messages),
+        },
+        this.consentDeps,
+      );
+      if (!ok) {
+        // User declined — Brain must fall back. Return empty so the
+        // template path takes over.
+        return emptyCompletion();
+      }
+    }
+
+    // Redact every message before the prompt leaves the machine.
+    const redactedMessages: ChatMessage[] = [];
+    const audit: string[] = [];
+    for (const m of messages) {
+      const { redacted, hits } = redactSecrets(m.content);
+      redactedMessages.push({ role: m.role, content: redacted });
+      for (const hit of hits) {
+        audit.push(
+          JSON.stringify({
+            ts: new Date().toISOString(),
+            provider: "openai",
+            model: this.config.model,
+            role: m.role,
+            kind: hit.kind,
+            sample: hit.sample,
+          }),
+        );
+      }
+    }
+    if (audit.length > 0) {
+      await appendRedactionLog(this.projectRoot, audit);
+    }
+
+    // First attempt — fresh token.
+    let attemptToken = token.access_token;
+    let result = await this.callChatApi(
+      attemptToken,
+      redactedMessages,
+      options,
+    );
+    if (result.status === 401 && token.refresh_token) {
+      const refreshed = await this.trySilentRefresh(token);
+      if (refreshed) {
+        attemptToken = refreshed.access_token;
+        result = await this.callChatApi(
+          attemptToken,
+          redactedMessages,
+          options,
+        );
+      }
+    }
+    if (result.status === 401) {
+      // Persistent auth failure — scrub the token so subsequent runs
+      // skip straight to the next resolver tier.
+      await this.credentialStore.delete("openai");
+      return emptyCompletion();
+    }
+    if (!result.ok) {
+      throw new Error(
+        `OpenAI request failed (${result.status}): ${result.bodySnippet}`,
+      );
+    }
+    await this.credentialStore.touch("openai");
+    return result.completion;
+  }
+
+  private async loadTokenOrReject(): Promise<StoredToken | null> {
+    const token = await this.credentialStore.load("openai");
+    return token ?? null;
+  }
+
+  private async trySilentRefresh(
+    existing: StoredToken,
+  ): Promise<StoredToken | null> {
+    if (!existing.refresh_token) return null;
+    if (this.refreshInFlight) return this.refreshInFlight;
+    this.refreshInFlight = (async () => {
+      try {
+        const refreshed = await refreshAccessToken({
+          endpoints: this.endpoints,
+          clientId: this.clientId,
+          refreshToken: existing.refresh_token!,
+          httpClient: this.httpClient,
+          scope: existing.scope ?? this.scope,
+        });
+        const stored: StoredToken = {
+          access_token: refreshed.access_token,
+          refresh_token: refreshed.refresh_token ?? existing.refresh_token,
+          expires_at:
+            typeof refreshed.expires_in === "number"
+              ? Math.floor(Date.now() / 1000) + refreshed.expires_in
+              : undefined,
+          scope: refreshed.scope ?? existing.scope,
+          default_model: existing.default_model,
+          provider: "openai",
+          last_used_at: new Date().toISOString(),
+        };
+        await this.credentialStore.save("openai", stored);
+        return stored;
+      } catch {
+        return null;
+      } finally {
+        this.refreshInFlight = null;
+      }
+    })();
+    return this.refreshInFlight;
+  }
+
+  private async callChatApi(
+    accessToken: string,
+    messages: ChatMessage[],
+    options: CompletionOptions,
+  ): Promise<
+    | { ok: true; status: number; completion: CompletionResult }
+    | { ok: false; status: number; bodySnippet: string; completion: CompletionResult }
+  > {
+    const body = {
+      model: this.config.model,
+      messages: messages.map((m) => ({ role: m.role, content: m.content })),
+      temperature: options.temperature ?? 0.2,
+      max_tokens: options.maxTokens ?? 2048,
+      stop: options.stop,
+    };
+
+    const res = await this.httpClient(`${this.baseUrl}/chat/completions`, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${accessToken}`,
+        "content-type": "application/json",
+        accept: "application/json",
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!res.ok) {
+      const txt = await res.text().catch(() => "");
+      return {
+        ok: false,
+        status: res.status,
+        bodySnippet: txt.slice(0, 256),
+        completion: emptyCompletion(),
+      };
+    }
+
+    const json = (await res.json()) as {
+      choices?: Array<{ message?: { content?: string } }>;
+      usage?: {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+        total_tokens?: number;
+      };
+    };
+    const content = json.choices?.[0]?.message?.content ?? "";
+    return {
+      ok: true,
+      status: res.status,
+      completion: {
+        content,
+        usage: {
+          promptTokens: json.usage?.prompt_tokens ?? 0,
+          completionTokens: json.usage?.completion_tokens ?? 0,
+          totalTokens: json.usage?.total_tokens ?? 0,
+        },
+      },
+    };
+  }
+}
+
+/* -------------------------------------------------------------------- */
+/* Helpers                                                              */
+/* -------------------------------------------------------------------- */
+
+function emptyCompletion(): CompletionResult {
+  return {
+    content: "",
+    usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+  };
+}
+
+/**
+ * One-line human summary of the chat payload for the consent prompt.
+ *
+ * Not exported — Anthropic has its own copy to avoid a cross-module
+ * name collision in the adapters barrel. Keep implementations in sync
+ * if the format changes.
+ */
+function describeChatPayload(messages: ChatMessage[]): string {
+  const totalChars = messages.reduce((a, m) => a + m.content.length, 0);
+  const roleCounts = new Map<string, number>();
+  for (const m of messages) {
+    roleCounts.set(m.role, (roleCounts.get(m.role) ?? 0) + 1);
+  }
+  const roleSummary = [...roleCounts.entries()]
+    .map(([r, n]) => `${n} ${r}`)
+    .join(", ");
+  return `${messages.length} messages (${roleSummary}), ~${totalChars} chars`;
+}
+
+/**
+ * Append redaction audit entries as JSON-lines to
+ * `<projectRoot>/.mandu/brain-redactions.jsonl`. Best-effort — an IO
+ * error here must not block the actual adapter request.
+ */
+async function appendRedactionLog(
+  projectRoot: string,
+  entries: string[],
+): Promise<void> {
+  try {
+    const dir = path.join(projectRoot, ".mandu");
+    await fs.mkdir(dir, { recursive: true });
+    const file = path.join(dir, "brain-redactions.jsonl");
+    await fs.appendFile(file, `${entries.join("\n")}\n`, { mode: 0o600 });
+  } catch {
+    /* best-effort */
+  }
+}
+
+export function createOpenAIOAuthAdapter(
+  options: OpenAIOAuthAdapterOptions = {},
+): OpenAIOAuthAdapter {
+  return new OpenAIOAuthAdapter(options);
+}

package/src/brain/consent.ts

@@ -0,0 +1,240 @@
+/**
+ * Brain — first-use consent prompt + cache (Issue #235).
+ *
+ * On the first `brain_doctor --useLLM` call that would dispatch to a
+ * cloud adapter, Mandu prints a one-line summary of what will be
+ * transmitted (diff excerpt, violation report shape, target model) and
+ * prompts `y/N`. Consent is cached per-provider, per-project at
+ * `~/.mandu/brain-consent.json` so the prompt only appears once.
+ *
+ * The CI escape hatch is `MANDU_BRAIN_AUTO_CONSENT=1` — used by
+ * non-interactive pipelines that have already reviewed the data policy
+ * out of band.
+ *
+ * Privacy invariants:
+ *   - If consent is not granted, the adapter MUST fall through to the
+ *     next tier in the resolver (ollama → template).
+ *   - `telemetryOptOut: true` in config bypasses this module entirely —
+ *     cloud adapters are never constructed in that case.
+ *   - The consent cache only stores `{ providerId, projectFingerprint,
+ *     grantedAt }`; no prompt content ever reaches this file.
+ */
+
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createHash } from "node:crypto";
+
+const CONSENT_DIR = path.join(os.homedir(), ".mandu");
+const CONSENT_FILE = path.join(CONSENT_DIR, "brain-consent.json");
+
+export type ConsentProvider = "openai" | "anthropic";
+
+export interface ConsentEntry {
+  provider: ConsentProvider;
+  /** SHA-256 of the absolute project root. Lets us re-prompt per-project. */
+  project: string;
+  /** ISO timestamp of the grant. */
+  grantedAt: string;
+  /** Model the user was informed about at grant time. */
+  modelAtGrant: string;
+}
+
+export interface ConsentContext {
+  /** Absolute path of the project root — identifies the consent scope. */
+  projectRoot: string;
+  provider: ConsentProvider;
+  /** Model the adapter will transmit to — printed in the prompt. */
+  model: string;
+  /**
+   * One-line human summary of the payload shape that will be sent.
+   * Example: "Guard violation report (3 entries) + 120-line diff excerpt".
+   * Adapters compose this from their prompt shape.
+   */
+  payloadDescription: string;
+}
+
+export interface ConsentPromptDeps {
+  /** stdout writer — default process.stdout.write. Tests inject a stub. */
+  write?: (msg: string) => void;
+  /** Read one line of input. Tests inject a stub; production wraps readline. */
+  ask?: (prompt: string) => Promise<string>;
+  /** Environment — tests can force `MANDU_BRAIN_AUTO_CONSENT`. */
+  env?: NodeJS.ProcessEnv;
+}
+
+/**
+ * Fingerprint a project root so the cache key is collision-resistant
+ * AND does not leak the absolute path to the on-disk file. We normalize
+ * the path (lowercase on win32) before hashing so a case-variant path
+ * resolves to the same entry.
+ */
+export function fingerprintProject(projectRoot: string): string {
+  const normalized =
+    process.platform === "win32" ? projectRoot.toLowerCase() : projectRoot;
+  return createHash("sha256")
+    .update(normalized)
+    .digest("hex")
+    .slice(0, 32);
+}
+
+async function readAllConsent(): Promise<ConsentEntry[]> {
+  try {
+    const raw = await fs.readFile(CONSENT_FILE, "utf8");
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed)) return parsed as ConsentEntry[];
+    return [];
+  } catch (err) {
+    if (
+      err instanceof Error &&
+      (err as NodeJS.ErrnoException).code === "ENOENT"
+    ) {
+      return [];
+    }
+    return [];
+  }
+}
+
+async function writeAllConsent(all: ConsentEntry[]): Promise<void> {
+  await fs.mkdir(CONSENT_DIR, { recursive: true, mode: 0o700 });
+  const tmp = `${CONSENT_FILE}.${process.pid}.tmp`;
+  await fs.writeFile(tmp, JSON.stringify(all, null, 2), { mode: 0o600 });
+  await fs.rename(tmp, CONSENT_FILE);
+  try {
+    await fs.chmod(CONSENT_FILE, 0o600);
+  } catch {
+    /* best-effort on Windows */
+  }
+}
+
+/**
+ * Check whether a (provider, project) pair already has stored consent.
+ */
+export async function hasConsent(
+  provider: ConsentProvider,
+  projectRoot: string,
+): Promise<boolean> {
+  const fp = fingerprintProject(projectRoot);
+  const all = await readAllConsent();
+  return all.some((e) => e.provider === provider && e.project === fp);
+}
+
+/**
+ * Record consent for a (provider, project) pair. Idempotent.
+ */
+export async function grantConsent(
+  ctx: ConsentContext,
+): Promise<void> {
+  const fp = fingerprintProject(ctx.projectRoot);
+  const all = await readAllConsent();
+  const existing = all.find(
+    (e) => e.provider === ctx.provider && e.project === fp,
+  );
+  if (existing) return;
+  all.push({
+    provider: ctx.provider,
+    project: fp,
+    grantedAt: new Date().toISOString(),
+    modelAtGrant: ctx.model,
+  });
+  await writeAllConsent(all);
+}
+
+/**
+ * Revoke consent — used by `mandu brain logout --provider=...`.
+ */
+export async function revokeConsent(
+  provider: ConsentProvider,
+  projectRoot?: string,
+): Promise<void> {
+  const all = await readAllConsent();
+  const fp = projectRoot ? fingerprintProject(projectRoot) : null;
+  const next = all.filter((e) => {
+    if (e.provider !== provider) return true;
+    if (fp === null) return false; // revoke all projects for this provider
+    return e.project !== fp;
+  });
+  await writeAllConsent(next);
+}
+
+/**
+ * Ensure consent exists for the given context. Prompts the user if
+ * necessary. Returns `true` when consent is granted (fresh or cached),
+ * `false` when the user declined or non-interactive stdin is closed.
+ *
+ * Never throws — Brain is isolated from the Core execution path.
+ */
+export async function ensureConsent(
+  ctx: ConsentContext,
+  deps: ConsentPromptDeps = {},
+): Promise<boolean> {
+  const env = deps.env ?? process.env;
+
+  // Already consented — fast path.
+  if (await hasConsent(ctx.provider, ctx.projectRoot)) {
+    return true;
+  }
+
+  // CI / pipeline opt-in.
+  if (env.MANDU_BRAIN_AUTO_CONSENT === "1") {
+    await grantConsent(ctx);
+    return true;
+  }
+
+  const write = deps.write ?? ((m: string) => process.stdout.write(m));
+  const ask = deps.ask ?? defaultReadLine;
+
+  write(
+    [
+      "",
+      "Mandu Brain — cloud adapter consent",
+      "-----------------------------------",
+      `  Provider : ${ctx.provider}`,
+      `  Model    : ${ctx.model}`,
+      `  Payload  : ${ctx.payloadDescription}`,
+      "",
+      "Secrets detected in source code are scrubbed before transmission",
+      "(audit log: .mandu/brain-redactions.jsonl).",
+      "",
+      "Consent is cached per-project at ~/.mandu/brain-consent.json.",
+      "Set MANDU_BRAIN_AUTO_CONSENT=1 in CI to skip this prompt.",
+      "",
+    ].join("\n"),
+  );
+
+  const answer = (await ask("Proceed? [y/N]: ")).trim().toLowerCase();
+  if (answer === "y" || answer === "yes") {
+    await grantConsent(ctx);
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Default interactive reader — wraps node:readline. Returns an empty
+ * string when stdin is non-TTY so non-interactive shells treat the
+ * prompt as declined (safer default than auto-accepting).
+ */
+async function defaultReadLine(prompt: string): Promise<string> {
+  if (!process.stdin.isTTY) return "";
+  process.stdout.write(prompt);
+  // Inline readline to avoid a top-level import — keeps the Brain
+  // module graph small and avoids pulling readline into the SSR bundle.
+  const readline = await import("node:readline");
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: true,
+  });
+  return new Promise<string>((resolve) => {
+    rl.question("", (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+
+/** Consent file path — surfaced to the user in `mandu brain status`. */
+export function consentFilePath(): string {
+  return CONSENT_FILE;
+}