@iislee/opencodex 2.11.0 → 2.31.0

package/src/oauth/account-import/index.ts

@@ -0,0 +1,15 @@
+export { importAccounts } from "./service";
+export {
+  ACCOUNT_IMPORT_DEADLINE_MS,
+  ACCOUNT_IMPORT_FORMAT,
+  ACCOUNT_IMPORT_MAX_BYTES,
+  ACCOUNT_IMPORT_MAX_REQUEST_BYTES,
+  ACCOUNT_IMPORT_PROVIDER,
+} from "./types";
+export type {
+  AccountImportCode,
+  AccountImportRecordResult,
+  AccountImportRequest,
+  AccountImportResult,
+  AccountImportStatus,
+} from "./types";

package/src/oauth/account-import/parser.ts

@@ -0,0 +1,83 @@
+import {
+  ACCOUNT_IMPORT_MAX_BYTES,
+  ACCOUNT_IMPORT_MAX_EMAIL_LENGTH,
+  ACCOUNT_IMPORT_MAX_RECORDS,
+  ACCOUNT_IMPORT_MAX_REFRESH_TOKEN_BYTES,
+  type ParsedCockpitRecord,
+} from "./types";
+
+const encoder = new TextEncoder();
+const ALLOWED_RECORD_KEYS = new Set(["email", "refresh_token", "tags", "notes"]);
+
+export type CockpitDocumentParseResult =
+  | { ok: true; records: ParsedCockpitRecord[] }
+  | { ok: false; code: "invalid_document" };
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function serializedDocumentSize(document: unknown): number | null {
+  try {
+    const serialized = JSON.stringify(document);
+    return serialized === undefined ? null : encoder.encode(serialized).byteLength;
+  } catch {
+    return null;
+  }
+}
+
+function validEmail(value: unknown): value is string {
+  if (typeof value !== "string" || value.length === 0 || value.length > ACCOUNT_IMPORT_MAX_EMAIL_LENGTH) return false;
+  if (value !== value.trim() || /[\x00-\x20\x7f]/.test(value)) return false;
+  const at = value.indexOf("@");
+  return at > 0 && at === value.lastIndexOf("@") && at < value.length - 1;
+}
+
+function validRefreshToken(value: unknown): value is string {
+  return typeof value === "string"
+    && value.length > 0
+    && encoder.encode(value).byteLength <= ACCOUNT_IMPORT_MAX_REFRESH_TOKEN_BYTES
+    && !/[\s\x7f]/.test(value);
+}
+
+function validMetadata(record: Record<string, unknown>): boolean {
+  if (record.tags !== undefined && (
+    !Array.isArray(record.tags)
+    || record.tags.some(tag => typeof tag !== "string")
+  )) return false;
+  return record.notes === undefined || typeof record.notes === "string";
+}
+
+function parseRecord(value: unknown, index: number): ParsedCockpitRecord {
+  if (!isPlainRecord(value)) return { index, code: "invalid_record" };
+  if (Object.keys(value).some(key => !ALLOWED_RECORD_KEYS.has(key))) return { index, code: "invalid_record" };
+  if (!validEmail(value.email) || !validRefreshToken(value.refresh_token) || !validMetadata(value)) {
+    return { index, code: "invalid_record" };
+  }
+  return {
+    index,
+    record: {
+      email: value.email.toLowerCase(),
+      refreshToken: value.refresh_token,
+    },
+  };
+}
+
+export function parseCockpitAccountDocument(document: unknown): CockpitDocumentParseResult {
+  const size = serializedDocumentSize(document);
+  if (size === null || size > ACCOUNT_IMPORT_MAX_BYTES) return { ok: false, code: "invalid_document" };
+  if (!Array.isArray(document) || document.length === 0 || document.length > ACCOUNT_IMPORT_MAX_RECORDS) {
+    return { ok: false, code: "invalid_document" };
+  }
+  const seen = new Set<string>();
+  const records = document.map((value, index): ParsedCockpitRecord => {
+    const parsed = parseRecord(value, index);
+    if ("code" in parsed) return parsed;
+    if (seen.has(parsed.record.email)) return { index, code: "invalid_record" };
+    seen.add(parsed.record.email);
+    return parsed;
+  });
+  return { ok: true, records };
+}

package/src/oauth/account-import/registry.ts

@@ -0,0 +1,18 @@
+import { createAntigravityAccountImportAdapter } from "./google-antigravity-adapter";
+import {
+  ACCOUNT_IMPORT_FORMAT,
+  ACCOUNT_IMPORT_PROVIDER,
+  type AccountImportAdapter,
+} from "./types";
+
+export type AccountImportRegistryResult =
+  | { ok: true; adapter: AccountImportAdapter }
+  | { ok: false; code: "unsupported_provider" | "unsupported_format" };
+
+const antigravityAdapter = createAntigravityAccountImportAdapter();
+
+export function resolveAccountImportAdapter(provider: string, format: string): AccountImportRegistryResult {
+  if (provider !== ACCOUNT_IMPORT_PROVIDER) return { ok: false, code: "unsupported_provider" };
+  if (format !== ACCOUNT_IMPORT_FORMAT) return { ok: false, code: "unsupported_format" };
+  return { ok: true, adapter: antigravityAdapter };
+}

package/src/oauth/account-import/service.ts

@@ -0,0 +1,75 @@
+import { parseCockpitAccountDocument } from "./parser";
+import { resolveAccountImportAdapter, type AccountImportRegistryResult } from "./registry";
+import {
+  AccountImportAbortError,
+  throwIfAccountImportAborted,
+} from "./types";
+import type {
+  AccountImportRequest,
+  AccountImportResult,
+  AccountImportRecordResult,
+} from "./types";
+
+export type AccountImportServiceResult =
+  | { ok: true; result: AccountImportResult }
+  | {
+    ok: false;
+    status: 400 | 408;
+    code: "unsupported_provider" | "unsupported_format" | "invalid_document" | "import_cancelled";
+    /** True when at least one credential was committed before the terminal failure. */
+    changed?: boolean;
+  };
+
+export interface AccountImportServiceDeps {
+  resolveAdapter(provider: string, format: string): AccountImportRegistryResult;
+}
+
+export async function importAccounts(
+  request: AccountImportRequest,
+  deps: AccountImportServiceDeps = { resolveAdapter: resolveAccountImportAdapter },
+): Promise<AccountImportServiceResult> {
+  // Provider/format admission intentionally precedes any traversal or serialization of the
+  // credential-bearing document.
+  const resolved = deps.resolveAdapter(request.provider, request.format);
+  if (!resolved.ok) return { ok: false, status: 400, code: resolved.code };
+
+  const parsed = parseCockpitAccountDocument(request.document);
+  if (!parsed.ok) return { ok: false, status: 400, code: parsed.code };
+
+  const results: AccountImportRecordResult[] = [];
+  try {
+    for (const item of parsed.records) {
+      throwIfAccountImportAborted(request.signal);
+      if ("code" in item) {
+        results.push({ index: item.index, status: "failed", code: item.code });
+        continue;
+      }
+      const outcome = await resolved.adapter.importRecord(item.record, request.signal);
+      results.push({ index: item.index, ...outcome });
+      // Record the committed outcome before observing cancellation. The route uses this
+      // internal signal to reconcile live stores and caches even when the public response
+      // is the terminal 408 DTO.
+      throwIfAccountImportAborted(request.signal);
+    }
+  } catch (error) {
+    if (error instanceof AccountImportAbortError) {
+      const changed = results.some(result => result.status === "imported" || result.status === "updated");
+      return { ok: false, status: 408, code: "import_cancelled", ...(changed ? { changed: true } : {}) };
+    }
+    throw error;
+  }
+
+  const count = (status: AccountImportRecordResult["status"]) =>
+    results.filter(result => result.status === status).length;
+  return {
+    ok: true,
+    result: {
+      totalCount: results.length,
+      importedCount: count("imported"),
+      updatedCount: count("updated"),
+      failedCount: count("failed"),
+      unsupportedCount: count("unsupported"),
+      results,
+    },
+  };
+}

package/src/oauth/account-import/types.ts

@@ -0,0 +1,91 @@
+import type { OAuthCredentials } from "../types";
+
+export const ACCOUNT_IMPORT_PROVIDER = "google-antigravity" as const;
+export const ACCOUNT_IMPORT_FORMAT = "cockpit-tools" as const;
+export const ACCOUNT_IMPORT_MAX_BYTES = 256 * 1024;
+// The HTTP request also carries the fixed provider/format envelope. Keep that envelope bounded
+// without making a valid document at the 256 KiB contract boundary fail at the API layer.
+export const ACCOUNT_IMPORT_MAX_REQUEST_BYTES = ACCOUNT_IMPORT_MAX_BYTES + 1024;
+// Shared CLI POST timeout and management-route deadline. Individual provider requests keep
+// shorter timeouts; this bounds the full admitted batch (up to ACCOUNT_IMPORT_MAX_RECORDS).
+export const ACCOUNT_IMPORT_DEADLINE_MS = 600_000;
+export const ACCOUNT_IMPORT_MAX_RECORDS = 25;
+export const ACCOUNT_IMPORT_MAX_EMAIL_LENGTH = 254;
+export const ACCOUNT_IMPORT_MAX_REFRESH_TOKEN_BYTES = 16 * 1024;
+
+export type AccountImportStatus = "imported" | "updated" | "failed" | "unsupported";
+
+export type AccountImportCode =
+  | "imported"
+  | "updated"
+  | "import_cancelled"
+  | "unsupported_provider"
+  | "unsupported_format"
+  | "invalid_document"
+  | "invalid_record"
+  | "credential_rejected"
+  | "identity_mismatch"
+  | "missing_project"
+  | "persist_failed";
+
+export interface AccountImportRecordResult {
+  index: number;
+  status: AccountImportStatus;
+  code: AccountImportCode;
+}
+
+export interface AccountImportResult {
+  totalCount: number;
+  importedCount: number;
+  updatedCount: number;
+  failedCount: number;
+  unsupportedCount: number;
+  results: AccountImportRecordResult[];
+}
+
+export interface AccountImportRequest {
+  provider: string;
+  format: string;
+  document: unknown;
+  signal?: AbortSignal;
+}
+
+/** A secret-free terminal signal for a cancelled import request. */
+export class AccountImportAbortError extends Error {
+  constructor() {
+    super("Account import cancelled");
+    this.name = "AccountImportAbortError";
+  }
+}
+
+export function throwIfAccountImportAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) throw new AccountImportAbortError();
+}
+
+export interface CockpitAccountRecord {
+  email: string;
+  refreshToken: string;
+}
+
+export type ParsedCockpitRecord =
+  | { index: number; record: CockpitAccountRecord }
+  | { index: number; code: "invalid_record" };
+
+export type AccountImportRecordOutcome =
+  | { status: "imported"; code: "imported" }
+  | { status: "updated"; code: "updated" }
+  | {
+    status: "failed";
+    code: "credential_rejected" | "identity_mismatch" | "missing_project" | "persist_failed";
+  };
+
+export interface AccountImportAdapter {
+  readonly provider: typeof ACCOUNT_IMPORT_PROVIDER;
+  readonly format: typeof ACCOUNT_IMPORT_FORMAT;
+  importRecord(record: CockpitAccountRecord, signal?: AbortSignal): Promise<AccountImportRecordOutcome>;
+}
+
+export interface ValidatedAntigravityCredential extends OAuthCredentials {
+  email?: string;
+  projectId?: string;
+}

package/src/oauth/anthropic.ts

@@ -81,10 +81,21 @@ function parseTokenResponse(responseBody: string): AnthropicTokenResponse {
 function credsFrom(data: AnthropicTokenResponse, refreshFallback?: string): OAuthCredentials {
   const accountUuid = data.account?.uuid;
   const email = data.account?.email_address;
+  // Guard against a missing/non-finite/negative expires_in (malformed upstream
+  // response): a NaN expiry would never compare 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 - 5 * 60 * 1000;
+  const expires = Number.isFinite(computedExpires) ? computedExpires : Date.now() + 3600 * 1000 - 5 * 60 * 1000;
   return {
     refresh: data.refresh_token || refreshFallback || "",
     access: data.access_token,
-    expires: Date.now() + data.expires_in * 1000 - 5 * 60 * 1000,
+    expires,
     accountId: typeof accountUuid === "string" && accountUuid.length > 0 ? accountUuid : undefined,
     email: typeof email === "string" && email.length > 0 ? email : undefined,
   };

package/src/oauth/callback-server.ts

@@ -5,7 +5,7 @@
  * 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,
+ * Handles: port allocation (preferred → random/manual-only fallback), callback server, CSRF state,
  * manual-input race, 300s timeout. Providers implement generateAuthUrl() + exchangeToken().
  */
 import { isAddrInUse } from "../server/ports";
@@ -131,8 +131,14 @@ export abstract class OAuthCallbackFlow {
       }
       const redirectUri = `http://${this.callbackHostname}:${this.preferredPort}${this.callbackPath}`;
       return { servers, redirectUri };
-    } catch {
+    } catch (error) {
       if (this.redirectUri) {
+        // Fixed OAuth redirect URIs cannot move to a random port. Remote dashboards can
+        // still complete the same state/PKCE flow by pasting the final redirect URL or
+        // authorization code, so do not make a local listener a prerequisite for that path.
+        if (this.ctrl.onManualCodeInput && isAddrInUse(error)) {
+          return { servers: [], redirectUri: this.redirectUri };
+        }
         throw new Error(
           `OAuth callback port ${this.preferredPort} unavailable; cannot fall back to a random port when redirectUri is set`,
         );

package/src/oauth/chatgpt.ts

@@ -49,10 +49,21 @@ export function extractEmail(idToken?: string, accessToken?: string): string | u
 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: Date.now() + ((data.expires_in as number) ?? 3600) * 1000,
+    expires,
     accountId: extractAccountId(idToken, accessToken),
     email: extractEmail(idToken, accessToken),
   };

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" };
+}