@iislee/opencodex 2.11.0

package/src/oauth/anthropic.ts

@@ -0,0 +1,177 @@
+/** Anthropic OAuth flow (Claude Pro/Max). Ported from jawcode oauth/anthropic.ts. */
+import { OAuthCallbackFlow } from "./callback-server";
+import { generatePKCE } from "./pkce";
+import type { LocalTokenImportMode, OAuthController, OAuthCredentials } from "./types";
+
+const CLIENT_ID = atob("OWQxYzI1MGEtZTYxYi00NGQ5LTg4ZWQtNTk0NGQxOTYyZjVl");
+const AUTHORIZE_URL = "https://claude.ai/oauth/authorize";
+const TOKEN_URL = "https://api.anthropic.com/v1/oauth/token";
+const CALLBACK_PORT = 54545;
+const CALLBACK_PATH = "/callback";
+const SCOPES = "org:create_api_key user:profile user:inference";
+
+// ── OAuth-request requirements applied by the anthropic adapter when authMode==="oauth" ──
+export const ANTHROPIC_OAUTH_BETA = "claude-code-20250219,oauth-2025-04-20";
+export const CLAUDE_CODE_SYSTEM_INSTRUCTION = "You are a Claude agent, built on Anthropic's Claude Agent SDK.";
+const CLAUDE_TOOL_PREFIX = "custom_";
+const ANTHROPIC_BUILTIN_TOOLS = new Set(["web_search", "code_execution", "text_editor", "computer"]);
+
+/** OAuth tokens reject arbitrary tool names; prefix custom tools (Anthropic builtins are exempt). */
+export function applyClaudeToolPrefix(name: string): string {
+  if (ANTHROPIC_BUILTIN_TOOLS.has(name.toLowerCase()) || name.toLowerCase().startsWith(CLAUDE_TOOL_PREFIX)) return name;
+  return CLAUDE_TOOL_PREFIX + name;
+}
+
+/** Strip the custom_ prefix from a returned tool_use name so the caller (Codex) sees the original. */
+export function stripClaudeToolPrefix(name: string): string {
+  return name.startsWith(CLAUDE_TOOL_PREFIX) ? name.slice(CLAUDE_TOOL_PREFIX.length) : name;
+}
+
+interface AnthropicTokenResponse {
+  access_token: string;
+  refresh_token: string;
+  expires_in: number;
+  account?: { uuid?: string; email_address?: string };
+}
+
+export class AnthropicTokenError extends Error {
+  constructor(
+    message: string,
+    readonly httpStatus: number | undefined,
+    readonly oauthError: string | undefined,
+  ) {
+    super(message);
+    this.name = "AnthropicTokenError";
+  }
+}
+
+async function postJson(url: string, body: Record<string, string | number>): Promise<string> {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Accept: "application/json" },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(30_000),
+  });
+  const responseBody = await response.text();
+  if (!response.ok) {
+    let oauthError: string | undefined;
+    try {
+      const parsed = JSON.parse(responseBody) as { error?: unknown };
+      if (typeof parsed.error === "string") oauthError = parsed.error;
+    } catch {
+      // Best-effort only: malformed error bodies remain structured by HTTP status.
+    }
+    throw new AnthropicTokenError(
+      `Anthropic OAuth HTTP ${response.status}: ${responseBody}`,
+      response.status,
+      oauthError,
+    );
+  }
+  return responseBody;
+}
+
+function parseTokenResponse(responseBody: string): AnthropicTokenResponse {
+  try {
+    return JSON.parse(responseBody) as AnthropicTokenResponse;
+  } catch {
+    throw new Error(`Anthropic OAuth returned invalid JSON: ${responseBody.slice(0, 200)}`);
+  }
+}
+
+function credsFrom(data: AnthropicTokenResponse, refreshFallback?: string): OAuthCredentials {
+  const accountUuid = data.account?.uuid;
+  const email = data.account?.email_address;
+  return {
+    refresh: data.refresh_token || refreshFallback || "",
+    access: data.access_token,
+    expires: Date.now() + data.expires_in * 1000 - 5 * 60 * 1000,
+    accountId: typeof accountUuid === "string" && accountUuid.length > 0 ? accountUuid : undefined,
+    email: typeof email === "string" && email.length > 0 ? email : undefined,
+  };
+}
+
+export class AnthropicOAuthFlow extends OAuthCallbackFlow {
+  #verifier = "";
+
+  constructor(ctrl: OAuthController) {
+    super(ctrl, CALLBACK_PORT, CALLBACK_PATH);
+  }
+
+  async generateAuthUrl(state: string, redirectUri: string): Promise<{ url: string; instructions?: string }> {
+    const pkce = await generatePKCE();
+    this.#verifier = pkce.verifier;
+    const authParams = new URLSearchParams({
+      code: "true",
+      client_id: CLIENT_ID,
+      response_type: "code",
+      redirect_uri: redirectUri,
+      scope: SCOPES,
+      code_challenge: pkce.challenge,
+      code_challenge_method: "S256",
+      state,
+    });
+    return {
+      url: `${AUTHORIZE_URL}?${authParams.toString()}`,
+      instructions:
+        "Complete Claude login in your browser. If the browser cannot reach this machine, paste the final redirect URL or authorization code when prompted.",
+    };
+  }
+
+  async exchangeToken(code: string, state: string, redirectUri: string): Promise<OAuthCredentials> {
+    let exchangeCode = code;
+    let exchangeState = state;
+    const hash = code.indexOf("#");
+    if (hash >= 0) {
+      exchangeCode = code.slice(0, hash);
+      const frag = code.slice(hash + 1);
+      if (frag.length > 0) exchangeState = frag;
+    }
+    const responseBody = await postJson(TOKEN_URL, {
+      grant_type: "authorization_code",
+      client_id: CLIENT_ID,
+      code: exchangeCode,
+      state: exchangeState,
+      redirect_uri: redirectUri,
+      code_verifier: this.#verifier,
+    });
+    return credsFrom(parseTokenResponse(responseBody));
+  }
+}
+
+export async function loginAnthropic(
+  ctrl: OAuthController,
+  opts?: { importLocal?: LocalTokenImportMode },
+): Promise<OAuthCredentials> {
+  const importLocal = opts?.importLocal ?? "off";
+  if (importLocal !== "off") {
+    const { detectClaudeCodeToken } = await import("./local-token-detect");
+    const local = detectClaudeCodeToken();
+    if (local) {
+      ctrl.onProgress?.("Found Claude Code token, importing automatically");
+      if (local.expires >= Date.now() + 60_000) return local;
+      try {
+        return { ...(await refreshAnthropicToken(local.refresh)), source: "local-cli" };
+      } catch (error) {
+        if (importLocal === "only") {
+          throw new Error(`Claude Code token expired and could not be refreshed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+      }
+    } else if (importLocal === "only") {
+      throw new Error(
+        process.platform === "darwin"
+          ? "No Claude Code token found (Keychain or ~/.claude/.credentials.json). Run 'ocx login anthropic' for browser OAuth."
+          : "No Claude Code token found (~/.claude/.credentials.json). Run 'ocx login anthropic' for browser OAuth.",
+      );
+    }
+  }
+  return new AnthropicOAuthFlow(ctrl).login();
+}
+
+export async function refreshAnthropicToken(refreshToken: string): Promise<OAuthCredentials> {
+  const responseBody = await postJson(TOKEN_URL, {
+    grant_type: "refresh_token",
+    client_id: CLIENT_ID,
+    refresh_token: refreshToken,
+  });
+  return credsFrom(parseTokenResponse(responseBody), refreshToken);
+}

package/src/oauth/callback-server.ts

@@ -0,0 +1,294 @@
+/**
+ * Abstract base class for OAuth flows with local callback servers.
+ * Ported from jawcode packages/ai/src/utils/oauth/callback-server.ts.
+ *
+ * Change vs source: the success/error page is an inline HTML constant. opencodex's GUI polls
+ * GET /api/oauth/status, so it does not need OAuth state injected into the callback page.
+ *
+ * Handles: port allocation (preferred → random fallback), callback server, CSRF state,
+ * manual-input race, 300s timeout. Providers implement generateAuthUrl() + exchangeToken().
+ */
+import { isAddrInUse } from "../server/ports";
+import type { OAuthController, OAuthCredentials } from "./types";
+
+const DEFAULT_TIMEOUT = 300_000;
+const DEFAULT_HOSTNAME = "localhost";
+const DEFAULT_BIND_HOSTNAME = "127.0.0.1";
+const CALLBACK_PATH = "/callback";
+
+const SUCCESS_HTML =
+  "<!doctype html><html><head><meta charset='utf-8'><title>opencodex</title></head>" +
+  "<body style='font-family:system-ui,sans-serif;text-align:center;padding:4rem;color:#111'>" +
+  "<h2>&#9989; Login complete</h2><p>You can close this tab and return to opencodex.</p></body></html>";
+
+function escapeHtml(s: string): string {
+  return s.replace(/[&<>"']/g, (c) =>
+    ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c] ?? c,
+  );
+}
+
+function errorHtml(message: string): string {
+  return (
+    "<!doctype html><html><head><meta charset='utf-8'><title>opencodex</title></head>" +
+    "<body style='font-family:system-ui,sans-serif;text-align:center;padding:4rem;color:#111'>" +
+    `<h2>&#9888; Login failed</h2><p>${escapeHtml(message)}</p></body></html>`
+  );
+}
+
+export type CallbackResult = { code: string; state: string };
+
+/**
+ * The redirect URI advertised to providers must stay `localhost` (it is what the OAuth
+ * apps have registered), but Windows commonly resolves `localhost` to `::1` first while
+ * we historically bound IPv4-only — the browser then hits refusal/timeouts/wrong server.
+ * When advertising `localhost` over an IPv4 loopback bind, also bind `::1` best-effort.
+ */
+export function loopbackBindHostnames(callbackHostname: string, bindHostname: string): string[] {
+  if (callbackHostname.trim().toLowerCase() === "localhost" && bindHostname === "127.0.0.1") {
+    return ["127.0.0.1", "::1"];
+  }
+  return [bindHostname];
+}
+
+export interface OAuthCallbackFlowOptions {
+  preferredPort: number;
+  callbackPath?: string;
+  callbackHostname?: string;
+  /** Local listener hostname; defaults to callbackHostname when omitted. */
+  callbackBindHostname?: string;
+  /** Exact redirect URI advertised to the provider; disables port fallback. */
+  redirectUri?: string;
+}
+
+type BunServer = ReturnType<typeof Bun.serve>;
+
+export abstract class OAuthCallbackFlow {
+  ctrl: OAuthController;
+  preferredPort: number;
+  callbackPath: string;
+  callbackHostname: string;
+  callbackBindHostname: string;
+  redirectUri?: string;
+  #callbackResolve?: (result: CallbackResult) => void;
+  #callbackReject?: (error: string) => void;
+
+  constructor(
+    ctrl: OAuthController,
+    preferredPortOrOptions: number | OAuthCallbackFlowOptions,
+    callbackPath: string = CALLBACK_PATH,
+  ) {
+    this.ctrl = ctrl;
+    if (typeof preferredPortOrOptions === "number") {
+      this.preferredPort = preferredPortOrOptions;
+      this.callbackPath = callbackPath;
+      this.callbackHostname = DEFAULT_HOSTNAME;
+      this.callbackBindHostname = DEFAULT_BIND_HOSTNAME;
+      return;
+    }
+    this.preferredPort = preferredPortOrOptions.preferredPort;
+    this.callbackPath = preferredPortOrOptions.callbackPath ?? CALLBACK_PATH;
+    this.callbackHostname = preferredPortOrOptions.callbackHostname ?? DEFAULT_HOSTNAME;
+    this.callbackBindHostname = preferredPortOrOptions.callbackBindHostname ?? DEFAULT_BIND_HOSTNAME;
+    this.redirectUri = preferredPortOrOptions.redirectUri;
+  }
+
+  /** Build provider-specific authorization URL. */
+  abstract generateAuthUrl(state: string, redirectUri: string): Promise<{ url: string; instructions?: string }>;
+
+  /** Exchange authorization code for OAuth tokens. */
+  abstract exchangeToken(code: string, state: string, redirectUri: string): Promise<OAuthCredentials>;
+
+  /** Generate CSRF state token. */
+  generateState(): string {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes)
+      .map((value) => value.toString(16).padStart(2, "0"))
+      .join("");
+  }
+
+  /** Execute the OAuth login flow. */
+  async login(): Promise<OAuthCredentials> {
+    const state = this.generateState();
+    const { servers, redirectUri } = await this.#startCallbackServer(state);
+    try {
+      const { url: authUrl, instructions } = await this.generateAuthUrl(state, redirectUri);
+      this.ctrl.onAuth?.({ url: authUrl, instructions });
+      this.ctrl.onProgress?.("Waiting for browser authentication...");
+      const { code } = await this.#waitForCallback(state);
+      this.ctrl.onProgress?.("Exchanging authorization code for tokens...");
+      return await this.exchangeToken(code, state, redirectUri);
+    } finally {
+      for (const server of servers) server.stop();
+    }
+  }
+
+  async #startCallbackServer(expectedState: string): Promise<{ servers: BunServer[]; redirectUri: string }> {
+    try {
+      const servers = this.#createServers(this.preferredPort, expectedState);
+      if (this.redirectUri) {
+        return { servers, redirectUri: this.redirectUri };
+      }
+      const redirectUri = `http://${this.callbackHostname}:${this.preferredPort}${this.callbackPath}`;
+      return { servers, redirectUri };
+    } catch {
+      if (this.redirectUri) {
+        throw new Error(
+          `OAuth callback port ${this.preferredPort} unavailable; cannot fall back to a random port when redirectUri is set`,
+        );
+      }
+      const servers = this.#createServers(0, expectedState);
+      const actualPort = servers[0].port;
+      const redirectUri = `http://${this.callbackHostname}:${actualPort}${this.callbackPath}`;
+      this.ctrl.onProgress?.(`Preferred port ${this.preferredPort} unavailable, using port ${actualPort}`);
+      return { servers, redirectUri };
+    }
+  }
+
+  #createServers(port: number, expectedState: string): BunServer[] {
+    const fetch = (req: Request) => this.#handleCallback(req, expectedState);
+    const [primaryHost, ...extraHosts] = loopbackBindHostnames(this.callbackHostname, this.callbackBindHostname);
+    const primary = Bun.serve({ hostname: primaryHost, port, reusePort: false, fetch });
+    const servers = [primary];
+    for (const host of extraHosts) {
+      try {
+        servers.push(Bun.serve({ hostname: host, port: primary.port, reusePort: false, fetch }));
+      } catch (err) {
+        // extraHosts is only non-empty when we advertise ambiguous `localhost`. A foreign
+        // process HOLDING the IPv6 loopback port could then receive the browser's OAuth
+        // callback (localhost may resolve to ::1 first) — treat the whole port as unusable
+        // so the caller falls back to a fresh one. IPv6 merely unsupported/unavailable
+        // (EAFNOSUPPORT etc.) keeps the IPv4-only degradation.
+        if (isAddrInUse(err)) {
+          for (const server of servers) server.stop(true);
+          throw err;
+        }
+      }
+    }
+    return servers;
+  }
+
+  #handleCallback(req: Request, expectedState: string): Response {
+    const url = new URL(req.url);
+    if (url.pathname !== this.callbackPath) {
+      return new Response("Not Found", { status: 404 });
+    }
+
+    const code = url.searchParams.get("code");
+    const state = url.searchParams.get("state") || "";
+    const error = url.searchParams.get("error") || "";
+    const errorDescription = url.searchParams.get("error_description") || error;
+
+    let ok = false;
+    let consumeFlow = false;
+    let errMessage = "";
+    const stateMatches = !expectedState || state === expectedState;
+    if (error) {
+      errMessage = `Authorization failed: ${errorDescription}`;
+      consumeFlow = stateMatches;
+    } else if (!code) {
+      errMessage = "Missing authorization code";
+    } else if (!stateMatches) {
+      errMessage = "State mismatch - possible CSRF attack";
+    } else {
+      ok = true;
+      consumeFlow = true;
+    }
+
+    if (consumeFlow) {
+      // Capture refs before they could be cleared, then resolve on the next microtask.
+      const resolve = this.#callbackResolve;
+      const reject = this.#callbackReject;
+      queueMicrotask(() => {
+        if (ok && code) {
+          resolve?.({ code, state });
+        } else {
+          reject?.(errMessage || "Unknown error");
+        }
+      });
+    }
+
+    return new Response(ok ? SUCCESS_HTML : errorHtml(errMessage), {
+      status: ok ? 200 : consumeFlow ? 500 : 400,
+      headers: { "Content-Type": "text/html" },
+    });
+  }
+
+  #waitForCallback(expectedState: string): Promise<CallbackResult> {
+    const timeoutSignal = AbortSignal.timeout(DEFAULT_TIMEOUT);
+    const signal = this.ctrl.signal ? AbortSignal.any([this.ctrl.signal, timeoutSignal]) : timeoutSignal;
+
+    const callbackPromise = new Promise<CallbackResult>((resolve, reject) => {
+      this.#callbackResolve = resolve;
+      this.#callbackReject = (e: string) => reject(new Error(e));
+
+      signal.addEventListener("abort", () => {
+        this.#callbackResolve = undefined;
+        this.#callbackReject = undefined;
+        reject(new Error(`OAuth callback cancelled: ${signal.reason}`));
+      });
+    });
+
+    if (this.ctrl.onManualCodeInput) {
+      const requestManualInput = this.ctrl.onManualCodeInput;
+      const manualPromise = (async (): Promise<CallbackResult> => {
+        while (true) {
+          const result = await Promise.race([
+            callbackPromise,
+            requestManualInput(expectedState)
+              .then((input): CallbackResult | null => {
+                const parsed = parseCallbackInput(input);
+                if (!parsed.code) return null;
+                // Kind-aware state enforcement: url/query-shaped input is an authorization
+                // RESPONSE and must carry a matching state — missing state is rejected, not
+                // downgraded to raw. Only a syntactically raw code (same PKCE session) is
+                // exempt, so the CLI/GUI paste fallback still works.
+                if (parsed.kind !== "raw" && expectedState && parsed.state !== expectedState) return null;
+                return { code: parsed.code, state: parsed.state ?? expectedState };
+              })
+              .catch((): CallbackResult | null => null),
+          ]);
+          if (result) return result;
+        }
+      })();
+
+      return Promise.race([callbackPromise, manualPromise]);
+    }
+
+    return callbackPromise;
+  }
+}
+
+/**
+ * Parse a redirect URL or code string to extract code and state.
+ * `kind` records the syntactic shape so callers can enforce state on authorization
+ * responses (url/query) while exempting raw in-session codes.
+ */
+export function parseCallbackInput(input: string): { kind: "url" | "query" | "raw"; code?: string; state?: string } {
+  const value = input.trim();
+  if (!value) return { kind: "raw" };
+
+  try {
+    const url = new URL(value);
+    return {
+      kind: "url",
+      code: url.searchParams.get("code") ?? undefined,
+      state: url.searchParams.get("state") ?? undefined,
+    };
+  } catch {
+    // Not a URL - check for query string format
+  }
+
+  if (value.includes("code=")) {
+    const params = new URLSearchParams(value.replace(/^[?#]/, ""));
+    return {
+      kind: "query",
+      code: params.get("code") ?? undefined,
+      state: params.get("state") ?? undefined,
+    };
+  }
+
+  // Assume raw code, possibly with state after #
+  const [code, state] = value.split("#", 2);
+  return { kind: "raw", code, state };
+}

package/src/oauth/chatgpt.ts

@@ -0,0 +1,150 @@
+import { OAuthCallbackFlow } from "./callback-server";
+import type { OAuthController, OAuthCredentials } from "./types";
+import { generatePKCE } from "./pkce";
+
+const CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+const AUTH_URL = "https://auth.openai.com/oauth/authorize";
+const TOKEN_URL = "https://auth.openai.com/oauth/token";
+const SCOPE = "openid profile email offline_access api.connectors.read api.connectors.invoke";
+const CALLBACK_PORT = 1455;
+const CALLBACK_PATH = "/auth/callback";
+const ORIGINATOR = "opencodex";
+
+export function decodeJwtPayload(token: string): Record<string, unknown> | undefined {
+  const parts = token.split(".");
+  if (parts.length !== 3 || !parts[1]) return undefined;
+  try {
+    return JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8")) as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}
+
+export function extractAccountId(idToken?: string, accessToken?: string): string | undefined {
+  for (const token of [idToken, accessToken]) {
+    if (!token) continue;
+    const payload = decodeJwtPayload(token);
+    if (!payload) continue;
+    if (typeof payload.chatgpt_account_id === "string") return payload.chatgpt_account_id;
+    const ns = payload["https://api.openai.com/auth"];
+    if (ns && typeof ns === "object" && typeof (ns as Record<string, unknown>).chatgpt_account_id === "string") {
+      return (ns as Record<string, unknown>).chatgpt_account_id as string;
+    }
+    const orgs = payload.organizations;
+    if (Array.isArray(orgs) && orgs[0] && typeof orgs[0].id === "string") return orgs[0].id as string;
+  }
+  return undefined;
+}
+
+export function extractEmail(idToken?: string, accessToken?: string): string | undefined {
+  for (const token of [idToken, accessToken]) {
+    if (!token) continue;
+    const payload = decodeJwtPayload(token);
+    if (!payload) continue;
+    if (typeof payload.email === "string") return payload.email.toLowerCase();
+  }
+  return undefined;
+}
+
+function credsFromToken(data: Record<string, unknown>): OAuthCredentials {
+  const idToken = typeof data.id_token === "string" ? data.id_token : undefined;
+  const accessToken = data.access_token as string;
+  return {
+    access: accessToken,
+    refresh: (data.refresh_token as string) ?? "",
+    expires: Date.now() + ((data.expires_in as number) ?? 3600) * 1000,
+    accountId: extractAccountId(idToken, accessToken),
+    email: extractEmail(idToken, accessToken),
+  };
+}
+
+export class ChatGPTOAuthFlow extends OAuthCallbackFlow {
+  #verifier = "";
+  forceLogin = false;
+
+  constructor(ctrl: OAuthController) {
+    super(ctrl, {
+      preferredPort: CALLBACK_PORT,
+      callbackPath: CALLBACK_PATH,
+      callbackHostname: "localhost",
+      callbackBindHostname: "127.0.0.1",
+      redirectUri: `http://localhost:${CALLBACK_PORT}${CALLBACK_PATH}`,
+    });
+  }
+
+  async generateAuthUrl(state: string, redirectUri: string): Promise<{ url: string; instructions?: string }> {
+    const pkce = await generatePKCE();
+    this.#verifier = pkce.verifier;
+    const params = new URLSearchParams({
+      response_type: "code",
+      client_id: CLIENT_ID,
+      redirect_uri: redirectUri,
+      scope: SCOPE,
+      code_challenge: pkce.challenge,
+      code_challenge_method: "S256",
+      state,
+      codex_cli_simplified_flow: "true",
+      originator: ORIGINATOR,
+    });
+    params.set("id_token_add_organizations", "true");
+    if (this.forceLogin) params.set("prompt", "login");
+    return {
+      url: `${AUTH_URL}?${params}`,
+      instructions: "Complete ChatGPT login in your browser.",
+    };
+  }
+
+  async exchangeToken(code: string, _state: string, redirectUri: string): Promise<OAuthCredentials> {
+    if (!this.#verifier) throw new Error("ChatGPT PKCE verifier not initialized");
+    const resp = await fetch(TOKEN_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "authorization_code",
+        client_id: CLIENT_ID,
+        code,
+        redirect_uri: redirectUri,
+        code_verifier: this.#verifier,
+      }).toString(),
+    });
+    if (!resp.ok) {
+      const errDesc = await safeErrorDescription(resp);
+      throw new Error(`ChatGPT token exchange failed: ${resp.status} ${errDesc}`);
+    }
+    return credsFromToken((await resp.json()) as Record<string, unknown>);
+  }
+}
+
+function safeErrorDescription(resp: Response): Promise<string> {
+  return resp.text().catch(() => "").then(text => {
+    try {
+      const parsed = JSON.parse(text) as { error?: string; error_description?: string };
+      return [parsed.error, parsed.error_description].filter(Boolean).join(": ") || `HTTP ${resp.status}`;
+    } catch { return `HTTP ${resp.status}`; }
+  });
+}
+
+export async function loginChatGPT(ctrl: OAuthController, opts?: { forceLogin?: boolean }): Promise<OAuthCredentials> {
+  const flow = new ChatGPTOAuthFlow(ctrl);
+  if (opts?.forceLogin) flow.forceLogin = true;
+  return flow.login();
+}
+
+// Note: uses form-urlencoded per OAuth 2.0 spec (RFC 6749 §6).
+// Codex-rs uses JSON for refresh — intentional divergence; both accepted by auth.openai.com.
+export async function refreshChatGPTToken(refreshToken: string): Promise<OAuthCredentials> {
+  const resp = await fetch(TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      client_id: CLIENT_ID,
+      refresh_token: refreshToken,
+    }).toString(),
+  });
+  if (!resp.ok) {
+    const errDesc = await safeErrorDescription(resp);
+    throw new Error(`ChatGPT refresh failed: ${resp.status} ${errDesc}`);
+  }
+  return credsFromToken((await resp.json()) as Record<string, unknown>);
+}