@yansigit/opencodex 2.31.0

package/src/oauth/chatgpt.ts

@@ -0,0 +1,161 @@
+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;
+  // ?? only guards null/undefined; NaN or a string expires_in would otherwise
+  // produce a NaN expiry that never compares as expired, and a negative duration
+  // would stamp an already-past expiry — both block refresh semantics.
+  const expiresIn =
+    typeof data.expires_in === "number" && Number.isFinite(data.expires_in) && data.expires_in >= 0
+      ? data.expires_in
+      : 3600;
+  // The computed timestamp itself must stay finite: Number.MAX_VALUE passes
+  // Number.isFinite but overflows to Infinity once multiplied by 1000.
+  const computedExpires = Date.now() + expiresIn * 1000;
+  const expires = Number.isFinite(computedExpires) ? computedExpires : Date.now() + 3600 * 1000;
+  return {
+    access: accessToken,
+    refresh: (data.refresh_token as string) ?? "",
+    expires,
+    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>);
+}

package/src/oauth/command-code.ts

@@ -0,0 +1,239 @@
+import type { OAuthController, OAuthCredentials } from "./types";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { isAddrInUse } from "../server/ports";
+import { parseCallbackInput } from "./callback-server";
+
+const COMMAND_CODE_STUDIO_URL = "https://commandcode.ai";
+const COMMAND_CODE_CALLBACK_PORT = 5959;
+const LOGIN_TIMEOUT_MS = 120_000;
+const CALLBACK_PATH = "/callback";
+
+interface CommandCodeCallback {
+  apiKey: string;
+  state: string;
+  userId: string;
+  userName: string;
+  keyName: string;
+}
+
+interface CommandCodeLocalAuth {
+  apiKey?: unknown;
+  userId?: unknown;
+}
+
+export interface CommandCodeLoginOptions {
+  /** Add-account and reauthentication flows must select a fresh browser identity. */
+  importLocal?: "fallback" | "off";
+}
+
+export function shouldImportLocalCommandCodeAuth(options: CommandCodeLoginOptions = {}): boolean {
+  return options.importLocal !== "off";
+}
+
+async function importLocalCommandCodeAuth(signal?: AbortSignal): Promise<OAuthCredentials | undefined> {
+  if (signal?.aborted) {
+    throw signal.reason ?? new DOMException("Command Code login aborted", "AbortError");
+  }
+  let parsed: CommandCodeLocalAuth;
+  try {
+    parsed = JSON.parse(await Bun.file(join(homedir(), ".commandcode", "auth.json")).text()) as CommandCodeLocalAuth;
+  } catch {
+    return undefined;
+  }
+  if (typeof parsed.apiKey !== "string" || parsed.apiKey.length === 0) return undefined;
+  let accountId: string | undefined;
+  try {
+    const response = await fetch("https://api.commandcode.ai/alpha/whoami", {
+      headers: { Authorization: `Bearer ${parsed.apiKey}`, Accept: "application/json" },
+      signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(10_000)]) : AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) return undefined;
+    // Carry the validated whoami identity so an imported credential keeps multi-account
+    // semantics even when the local auth.json omits userId.
+    const body = (await response.json()) as { user?: { id?: unknown } };
+    if (typeof body.user?.id === "string" && body.user.id.length > 0) accountId = body.user.id;
+  } catch (error) {
+    if (signal?.aborted) throw signal.reason ?? new DOMException("Command Code login aborted", "AbortError");
+    return undefined;
+  }
+  if (!accountId && typeof parsed.userId === "string" && parsed.userId.length > 0) accountId = parsed.userId;
+  return {
+    access: parsed.apiKey,
+    refresh: parsed.apiKey,
+    expires: Number.MAX_SAFE_INTEGER,
+    ...(accountId ? { accountId } : {}),
+    source: "local-cli",
+  };
+}
+
+function randomState(): string {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return Buffer.from(bytes).toString("base64url");
+}
+
+export function parseCommandCodeCallback(value: unknown, expectedState: string): CommandCodeCallback {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Command Code callback must be an object");
+  }
+  const body = value as Record<string, unknown>;
+  if (body.state !== expectedState) throw new Error("Command Code OAuth state mismatch");
+  for (const field of ["apiKey", "userId", "userName", "keyName"] as const) {
+    if (typeof body[field] !== "string" || body[field].length === 0) {
+      throw new Error(`Command Code callback missing ${field}`);
+    }
+  }
+  return body as unknown as CommandCodeCallback;
+}
+
+function createCallbackServer(state: string): {
+  servers: Array<ReturnType<typeof Bun.serve>>;
+  callback: Promise<CommandCodeCallback>;
+} {
+  let resolve!: (value: CommandCodeCallback) => void;
+  const callback = new Promise<CommandCodeCallback>((res) => { resolve = res; });
+  const fetch = async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+    const origin = request.headers.get("origin");
+    const headers = new Headers({
+      "Content-Type": "application/json",
+      "Access-Control-Allow-Origin": origin === COMMAND_CODE_STUDIO_URL ? origin : COMMAND_CODE_STUDIO_URL,
+      "Access-Control-Allow-Methods": "POST, OPTIONS",
+      "Access-Control-Allow-Headers": "Content-Type",
+    });
+    if (request.method === "OPTIONS") return new Response(null, { status: 204, headers });
+    if (url.pathname !== CALLBACK_PATH) return Response.json({ success: false, error: "Not found" }, { status: 404, headers });
+    if (request.method !== "POST") return Response.json({ success: false, error: "Method not allowed" }, { status: 405, headers });
+    try {
+      const body = await request.json();
+      const parsed = parseCommandCodeCallback(body, state);
+      queueMicrotask(() => resolve(parsed));
+      return Response.json({ success: true }, { headers });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return Response.json({ success: false, error: message }, { status: 400, headers });
+    }
+  };
+  const create = (port: number): Array<ReturnType<typeof Bun.serve>> => {
+    // The advertised callback host is `127.0.0.1`; on Windows `localhost` commonly resolves to `::1`
+    // first, so also bind the IPv6 loopback best-effort (mirrors the shared OAuthCallbackFlow).
+    const servers = [Bun.serve({ hostname: "127.0.0.1", port, fetch })];
+    try {
+      servers.push(Bun.serve({ hostname: "::1", port: servers[0].port, fetch }));
+    } catch (error) {
+      if (isAddrInUse(error)) {
+        for (const server of servers) server.stop(true);
+        throw error;
+      }
+      // IPv6 unsupported (EAFNOSUPPORT etc.) degrades to the IPv4-only listener.
+    }
+    return servers;
+  };
+  try {
+    return { servers: create(COMMAND_CODE_CALLBACK_PORT), callback };
+  } catch {
+    return { servers: create(0), callback };
+  }
+}
+
+/** Validate a raw pasted Command Code API key and return the validated identity. */
+async function validatePastedApiKey(apiKey: string): Promise<{ userId: string; userName: string } | undefined> {
+  try {
+    const response = await fetch("https://api.commandcode.ai/alpha/whoami", {
+      headers: { Authorization: `Bearer ${apiKey}`, Accept: "application/json" },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) return undefined;
+    const body = (await response.json()) as { user?: { id?: unknown; userName?: unknown } };
+    const userId = body.user?.id;
+    const userName = body.user?.userName;
+    if (typeof userId !== "string" || typeof userName !== "string") return undefined;
+    if (!userId.trim() || !userName.trim()) return undefined;
+    return { userId, userName };
+  } catch {
+    return undefined;
+  }
+}
+
+/** Manual-paste fallback: a raw API key, or a pasted callback JSON/URL that carries `apiKey`. */
+function parsePastedCommandCodeInput(input: string, expectedState: string): CommandCodeCallback | undefined {
+  const trimmed = input.trim();
+  if (!trimmed) return undefined;
+  if (trimmed.startsWith("{")) {
+    try {
+      return parseCommandCodeCallback(JSON.parse(trimmed) as unknown, expectedState);
+    } catch {
+      return undefined;
+    }
+  }
+  const parsed = parseCallbackInput(trimmed);
+  const apiKey = parsed.code?.trim();
+  if (!apiKey) return undefined;
+  // A URL/query-shaped paste is an authorization response and must carry a matching state,
+  // mirroring the shared OAuth callback flow; a stale or attacker-supplied URL from another
+  // session must not be accepted. Raw in-session keys are exempt (no state to compare).
+  if (parsed.kind !== "raw" && parsed.state !== expectedState) return undefined;
+  return { apiKey, state: expectedState, userId: "", userName: "", keyName: "manual" };
+}
+
+export async function loginCommandCode(ctrl: OAuthController, options: CommandCodeLoginOptions = {}): Promise<OAuthCredentials> {
+  if (ctrl.signal?.aborted) {
+    throw ctrl.signal.reason ?? new DOMException("Command Code login aborted", "AbortError");
+  }
+  if (shouldImportLocalCommandCodeAuth(options)) {
+    const local = await importLocalCommandCodeAuth(ctrl.signal);
+    if (local) {
+      ctrl.onProgress?.("Imported existing Command Code CLI authentication.");
+      return local;
+    }
+  }
+  const state = randomState();
+  let servers: Array<ReturnType<typeof Bun.serve>> = [];
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const created = createCallbackServer(state);
+    servers = created.servers;
+    const callbackUrl = `http://127.0.0.1:${servers[0].port}${CALLBACK_PATH}`;
+    const authUrl = `${COMMAND_CODE_STUDIO_URL}/studio/auth/cli?callback=${encodeURIComponent(callbackUrl)}&state=${encodeURIComponent(state)}`;
+    ctrl.onAuth?.({ url: authUrl, instructions: "Sign in with Command Code in the browser." });
+    ctrl.onProgress?.("Waiting for Command Code authentication...");
+    const timeout = new Promise<never>((_, reject) => {
+      timeoutId = setTimeout(() => reject(new Error("Command Code OAuth callback timed out")), LOGIN_TIMEOUT_MS);
+      ctrl.signal?.addEventListener("abort", () => { if (timeoutId) clearTimeout(timeoutId); reject(ctrl.signal?.reason); }, { once: true });
+    });
+    const manual = ctrl.onManualCodeInput
+      ? (async (): Promise<CommandCodeCallback> => {
+          while (true) {
+            // The loop keeps waiting until a valid paste arrives; invalid pastes re-prompt.
+            // Yield between iterations so an abort signal can interrupt a fast re-prompt loop.
+            if (ctrl.signal?.aborted) throw ctrl.signal.reason ?? new DOMException("Command Code login aborted", "AbortError");
+            const input = await ctrl.onManualCodeInput?.(state);
+            if (input === undefined) continue;
+            const pasted = parsePastedCommandCodeInput(input, state);
+            if (!pasted) continue;
+            const identity = await validatePastedApiKey(pasted.apiKey);
+            if (identity) return { ...pasted, ...identity };
+            await new Promise(resolve => setTimeout(resolve, 0));
+          }
+        })()
+      : undefined;
+    const result = await Promise.race([created.callback, timeout, ...(manual ? [manual] : [])]);
+    if (result === undefined) throw new Error("Command Code OAuth callback cancelled");
+    return {
+      access: result.apiKey,
+      refresh: result.apiKey,
+      expires: Number.MAX_SAFE_INTEGER,
+      accountId: result.userId,
+      source: "oauth",
+    };
+  } finally {
+    if (timeoutId) clearTimeout(timeoutId);
+    for (const server of servers) server.stop(true);
+  }
+}
+
+export async function refreshCommandCodeToken(apiKey: string): Promise<OAuthCredentials> {
+  if (!apiKey) throw new Error("Command Code API key missing; run ocx login command-code");
+  return { access: apiKey, refresh: apiKey, expires: Number.MAX_SAFE_INTEGER, source: "oauth" };
+}

package/src/oauth/cursor.ts

@@ -0,0 +1,252 @@
+/**
+ * Cursor OAuth — PKCE poll flow. Standalone: talks directly to cursor.com / api2.cursor.sh,
+ * with no dependency on a local Cursor IDE/CLI install or on jawcode. Ported from jawcode
+ * packages/ai/src/utils/oauth/cursor.ts and adapted to opencodex's OAuthController (see kimi.ts).
+ *
+ * Security: the login URL carries only the PKCE challenge (SHA-256 of the verifier); the verifier
+ * is sent only to /auth/poll. Tokens and the verifier are never logged — thrown errors and progress
+ * messages are status/string only.
+ */
+import { generatePKCE } from "./pkce";
+import type { OAuthController, OAuthCredentials } from "./types";
+
+const CURSOR_LOGIN_URL = "https://cursor.com/loginDeepControl";
+const CURSOR_POLL_URL = "https://api2.cursor.sh/auth/poll";
+const CURSOR_REFRESH_URL = "https://api2.cursor.sh/auth/exchange_user_api_key";
+
+const POLL_MAX_ATTEMPTS = 150;
+const POLL_BASE_DELAY_MS = 1000;
+const POLL_MAX_DELAY_MS = 10_000;
+const POLL_BACKOFF = 1.2;
+const EXPIRY_SKEW_MS = 5 * 60 * 1000;
+const FALLBACK_TTL_MS = 60 * 60 * 1000;
+
+const REFRESH_TIMEOUT_MS = 15_000;
+const REFRESH_ATTEMPTS = 3;
+const REFRESH_RETRY_BASE_MS = 300;
+
+export interface CursorAuthParams {
+  verifier: string;
+  challenge: string;
+  uuid: string;
+  loginUrl: string;
+}
+
+interface CursorJwtPayload {
+  sub?: unknown;
+  email?: unknown;
+  exp?: unknown;
+}
+
+function decodeCursorJwtPayload(token: string): CursorJwtPayload | undefined {
+  const parts = token.split(".");
+  const payload = parts[1];
+  if (parts.length !== 3 || !payload) return undefined;
+  try {
+    return JSON.parse(Buffer.from(payload, "base64url").toString("utf-8")) as CursorJwtPayload;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Build OAuthCredentials from Cursor tokens, extracting stable identity from JWT `sub` for multiauth. */
+export function credentialsFromCursorTokens(accessToken: string, refreshToken: string): OAuthCredentials {
+  const payload = decodeCursorJwtPayload(accessToken) ?? decodeCursorJwtPayload(refreshToken);
+  const accountId = cursorJwtIdentity(payload?.sub);
+  const email = cursorJwtEmail(payload?.email);
+  return {
+    access: accessToken,
+    refresh: refreshToken,
+    expires: getTokenExpiry(accessToken),
+    ...(accountId ? { accountId } : {}),
+    ...(email ? { email } : {}),
+  };
+}
+
+/** Coerce JWT `sub` (string or safe integer) into a stable multiauth account id. */
+function cursorJwtIdentity(value: unknown): string | undefined {
+  if (typeof value === "string" && value.length > 0) return value;
+  if (typeof value === "number" && Number.isSafeInteger(value)) return String(value);
+  return undefined;
+}
+
+function cursorJwtEmail(value: unknown): string | undefined {
+  if (typeof value !== "string" || value.length === 0) return undefined;
+  return value.toLowerCase();
+}
+
+/** Generate PKCE params + the cursor.com deep-link login URL (challenge only — never the verifier). */
+export async function generateCursorAuthParams(_opts?: { forceLogin?: boolean }): Promise<CursorAuthParams> {
+  const { verifier, challenge } = await generatePKCE();
+  const uuid = crypto.randomUUID();
+  // Cursor's deep-control page has no documented account-picker query; only the stable
+  // PKCE params are sent. forceLogin is honored only in loginCursor instructions.
+  const params = new URLSearchParams({ challenge, uuid, mode: "login", redirectTarget: "cli" });
+  return { verifier, challenge, uuid, loginUrl: `${CURSOR_LOGIN_URL}?${params.toString()}` };
+}
+
+/** Abort-aware delay (mirrors kimi.ts) — rejects if the controller signal aborts. */
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(new Error("Cursor login cancelled"));
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(new Error("Cursor login cancelled"));
+      },
+      { once: true },
+    );
+  });
+}
+
+/** Terminal poll statuses (T07, senpi PR #905): the login is denied/expired — retrying cannot succeed. */
+const POLL_TERMINAL_STATUSES = new Set([400, 401, 403, 410]);
+
+export class CursorAuthTerminalError extends Error {
+  readonly status: number;
+
+  constructor(status: number) {
+    super(`Cursor login rejected by the auth server (HTTP ${status}); start a new login`);
+    this.name = "CursorAuthTerminalError";
+    this.status = status;
+  }
+}
+
+/**
+ * Poll cursor.com for login completion. 404 = still pending (back off), 200 = tokens.
+ * `baseDelayMs` is injectable so tests can avoid the real 1s cadence; production uses the default.
+ */
+export async function pollCursorAuth(
+  uuid: string,
+  verifier: string,
+  signal?: AbortSignal,
+  baseDelayMs: number = POLL_BASE_DELAY_MS,
+): Promise<{ accessToken: string; refreshToken: string }> {
+  let delay = baseDelayMs;
+  let consecutiveErrors = 0;
+
+  for (let attempt = 0; attempt < POLL_MAX_ATTEMPTS; attempt++) {
+    await sleep(delay, signal);
+
+    try {
+      const url = `${CURSOR_POLL_URL}?uuid=${encodeURIComponent(uuid)}&verifier=${encodeURIComponent(verifier)}`;
+      const response = await fetch(url, { signal });
+
+      if (response.status === 404) {
+        consecutiveErrors = 0;
+        delay = Math.min(delay * POLL_BACKOFF, POLL_MAX_DELAY_MS);
+        continue;
+      }
+
+      if (response.ok) {
+        const data = (await response.json()) as { accessToken?: string; refreshToken?: string };
+        if (!data.accessToken || !data.refreshToken) {
+          throw new Error("Cursor auth response missing tokens");
+        }
+        return { accessToken: data.accessToken, refreshToken: data.refreshToken };
+      }
+
+      // T07: a terminal auth status means the login attempt itself is dead (denied,
+      // expired, revoked). Fail on the FIRST such response instead of burning the
+      // 3-strike retry budget and masking the reason behind a generic error.
+      if (POLL_TERMINAL_STATUSES.has(response.status)) {
+        throw new CursorAuthTerminalError(response.status);
+      }
+
+      throw new Error(`Cursor auth poll failed: ${response.status}`);
+    } catch (err) {
+      if (signal?.aborted) throw err instanceof Error ? err : new Error("Cursor login cancelled");
+      if (err instanceof CursorAuthTerminalError) throw err;
+      consecutiveErrors++;
+      if (consecutiveErrors >= 3) {
+        throw new Error("Too many consecutive errors during Cursor auth polling");
+      }
+      delay = Math.min(delay * POLL_BACKOFF, POLL_MAX_DELAY_MS);
+    }
+  }
+
+  throw new Error("Cursor authentication polling timeout");
+}
+
+/** Run the standalone Cursor login: surface the URL via `onAuth`, then poll until approved. */
+export async function loginCursor(
+  ctrl: OAuthController,
+  pollBaseDelayMs: number = POLL_BASE_DELAY_MS,
+  opts?: { forceLogin?: boolean },
+): Promise<OAuthCredentials> {
+  const { verifier, uuid, loginUrl } = await generateCursorAuthParams({ forceLogin: opts?.forceLogin === true });
+  ctrl.onAuth?.({
+    url: loginUrl,
+    instructions: opts?.forceLogin
+      ? "Log out of Cursor in the browser (or use a private window), sign in as the account you want to add, then approve and return here."
+      : "Approve the Cursor login in your browser, then return here.",
+  });
+  ctrl.onProgress?.("Waiting for Cursor login approval…");
+  const { accessToken, refreshToken } = await pollCursorAuth(uuid, verifier, ctrl.signal, pollBaseDelayMs);
+  return credentialsFromCursorTokens(accessToken, refreshToken);
+}
+
+function isRetryableRefreshStatus(status: number): boolean {
+  return status === 429 || status === 500 || status === 502 || status === 503 || status === 504;
+}
+
+function refreshRetryDelayMs(attempt: number): number {
+  const exp = REFRESH_RETRY_BASE_MS * 2 ** attempt;
+  return Math.floor(exp * (0.8 + Math.random() * 0.4));
+}
+
+function refreshTimeoutSignal(parent: AbortSignal | undefined): AbortSignal {
+  const timeout = AbortSignal.timeout(REFRESH_TIMEOUT_MS);
+  return parent ? AbortSignal.any([parent, timeout]) : timeout;
+}
+
+/**
+ * Exchange a refresh token for fresh credentials. Keeps the old refresh if the server omits one.
+ *
+ * Hardened with a per-attempt timeout and bounded retry on transient failures (network errors and
+ * 429/5xx). Non-retryable statuses (e.g. 401/403 from an expired refresh token) fail fast so the
+ * caller can surface a re-auth prompt. Errors never include the token value.
+ */
+export async function refreshCursorToken(refresh: string, signal?: AbortSignal): Promise<OAuthCredentials> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt < REFRESH_ATTEMPTS; attempt++) {
+    if (signal?.aborted) throw signal.reason ?? new Error("Cursor token refresh aborted");
+    let response: Response;
+    try {
+      response = await fetch(CURSOR_REFRESH_URL, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${refresh}`, "Content-Type": "application/json" },
+        body: "{}",
+        signal: refreshTimeoutSignal(signal),
+      });
+    } catch (err) {
+      // Network/timeout error: retry unless the caller aborted or we are out of attempts.
+      if (signal?.aborted) throw err;
+      lastError = err;
+      if (attempt === REFRESH_ATTEMPTS - 1) break;
+      await new Promise(resolve => setTimeout(resolve, refreshRetryDelayMs(attempt)));
+      continue;
+    }
+    if (response.ok) {
+      const data = (await response.json()) as { accessToken?: string; refreshToken?: string };
+      if (!data.accessToken) throw new Error("Cursor refresh response missing access token");
+      return credentialsFromCursorTokens(data.accessToken, data.refreshToken || refresh);
+    }
+    if (!isRetryableRefreshStatus(response.status) || attempt === REFRESH_ATTEMPTS - 1) {
+      throw new Error(`Cursor token refresh failed: ${response.status}`);
+    }
+    lastError = new Error(`Cursor token refresh failed: ${response.status}`);
+    await response.body?.cancel().catch(() => {});
+    await new Promise(resolve => setTimeout(resolve, refreshRetryDelayMs(attempt)));
+  }
+  throw lastError instanceof Error ? lastError : new Error("Cursor token refresh failed");
+}
+
+/** Resolve a token's expiry (epoch ms) from its JWT `exp`, minus a 5-minute skew; ~1h fallback. */
+export function getTokenExpiry(token: string): number {
+  const decoded = decodeCursorJwtPayload(token);
+  if (typeof decoded?.exp === "number") return decoded.exp * 1000 - EXPIRY_SKEW_MS;
+  return Date.now() + FALLBACK_TTL_MS;
+}