@yansigit/opencodex 2.31.0

package/src/oauth/token-guardian.ts

@@ -0,0 +1,309 @@
+/**
+ * Token Guardian — background proactive OAuth refresh.
+ *
+ * Keeps idle tokens from aging out server-side (the reported multi-account Codex-pool bug) by
+ * refreshing them BEFORE a request needs them. It is a CALLER of the existing refresh machinery —
+ * it adds no new refresh/locking logic:
+ *   - single-account providers → getValidAccessToken() (in-memory dedup + persist)
+ *   - multi-account Codex pool  → getValidCodexToken()  (file lock + generation CAS + grant fingerprint)
+ *
+ * Safety by construction: the guardian only touches a provider whose EFFECTIVE refreshPolicy is
+ * "proactive", and the global switch (config.tokenGuardian.enabled) defaults OFF, so a default
+ * install adds zero ToS-detection surface. See devlog 260703_oauth-multi-account-refresh-and-tos.
+ */
+import { loadConfig } from "../config";
+import type { OcxConfig, OcxTokenGuardianConfig } from "../types";
+import { listAccounts } from "./store";
+import { getValidAccessTokenForAccount, listOAuthProviders, OAuthLoginRequiredError, resolveRefreshPolicy } from "./index";
+import {
+  getValidCodexToken,
+  listCodexAccountIds,
+  markCodexAccountValidated,
+  markCodexAccountValidationFailed,
+  readCodexAccountRecord,
+  TokenRefreshError,
+  CodexCredentialRefreshBusyError,
+  CodexCredentialRefreshStaleError,
+} from "../codex/account-store";
+import { codexWarmupFailureReason, warmCodexAccount } from "../codex/warmup";
+import { getMainAccountToken, MAIN_CODEX_ACCOUNT_ID } from "../codex/main-account";
+import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
+import { providerCodexAccountMode } from "../providers/registry";
+import { captureConfigGeneration, type GenerationContext } from "../lib/state-store-sweeper";
+import { tryAcquireNativeMainProfileClaim } from "../codex/native-main-admission";
+
+export interface TokenGuardianHandle {
+  stop(): void;
+}
+
+export interface GuardianSweepResult {
+  enabled: boolean;
+  refreshed: string[];
+  warmed: string[];
+  failed: string[];
+  skippedBackoff: string[];
+}
+
+const DEFAULTS = {
+  tickSeconds: 21600, // 6h — matches codex-lb's guardian cadence
+  jitterSeconds: 300,
+  concurrency: 3,
+  leadSeconds: 900,
+  failureBackoffBaseSeconds: 300,
+  failureBackoffMaxSeconds: 3600,
+  codexWarmupMaxAgeSeconds: 691_200, // 8d — matches Codex managed-auth last_refresh cadence.
+  codexWarmupModel: "gpt-5.4-mini",
+};
+
+interface BackoffEntry {
+  attempts: number;
+  retryAfterMs: number;
+}
+
+// Module-scoped so backoff survives across sweeps within one process (keyed "oauth:<p>" / "codex:<id>").
+const backoff = new Map<string, BackoffEntry>();
+let lastReconciledGeneration = 0;
+let liveBackoffKeys = new Set<string>();
+
+/** Test hook: clear backoff state between cases. */
+export function __resetGuardianState(): void {
+  backoff.clear();
+}
+
+function num(value: number | undefined, fallback: number, min: number): number {
+  return typeof value === "number" && Number.isFinite(value) && value >= min ? value : fallback;
+}
+
+function resolved(g: OcxTokenGuardianConfig | undefined) {
+  return {
+    tickSeconds: num(g?.tickSeconds, DEFAULTS.tickSeconds, 60),
+    jitterSeconds: num(g?.jitterSeconds, DEFAULTS.jitterSeconds, 0),
+    concurrency: Math.max(1, Math.floor(num(g?.concurrency, DEFAULTS.concurrency, 1))),
+    leadSeconds: num(g?.leadSeconds, DEFAULTS.leadSeconds, 0),
+    backoffBaseSeconds: num(g?.failureBackoffBaseSeconds, DEFAULTS.failureBackoffBaseSeconds, 0),
+    backoffMaxSeconds: num(g?.failureBackoffMaxSeconds, DEFAULTS.failureBackoffMaxSeconds, 0),
+    codexWarmupEnabled: g?.codexWarmupEnabled === true,
+    codexWarmupMaxAgeSeconds: num(g?.codexWarmupMaxAgeSeconds, DEFAULTS.codexWarmupMaxAgeSeconds, 60),
+    codexWarmupModel: g?.codexWarmupModel?.trim() || DEFAULTS.codexWarmupModel,
+  };
+}
+
+function inBackoff(key: string, nowMs: number): boolean {
+  const entry = backoff.get(key);
+  return entry !== undefined && entry.retryAfterMs > nowMs;
+}
+
+function recordFailure(
+  key: string,
+  nowMs: number,
+  baseSeconds: number,
+  maxSeconds: number,
+  permanent: boolean,
+  writerGeneration = captureConfigGeneration(),
+): void {
+  if (writerGeneration < lastReconciledGeneration && !liveBackoffKeys.has(key)) return;
+  const prev = backoff.get(key);
+  const attempts = (prev?.attempts ?? 0) + 1;
+  // Permanent failures (revoked/expired refresh token) wait the full ceiling — nothing but a
+  // re-login fixes them, so there is no point retrying sooner.
+  const delaySeconds = permanent
+    ? maxSeconds
+    : Math.min(maxSeconds, baseSeconds * 2 ** (attempts - 1));
+  backoff.set(key, { attempts, retryAfterMs: nowMs + delaySeconds * 1000 });
+}
+
+async function runWithConcurrency(tasks: Array<() => Promise<void>>, limit: number): Promise<void> {
+  let cursor = 0;
+  const workers = Array.from({ length: Math.min(limit, tasks.length) }, async () => {
+    while (cursor < tasks.length) {
+      const task = tasks[cursor++];
+      if (task) await task();
+    }
+  });
+  await Promise.all(workers);
+}
+
+/**
+ * One refresh sweep. Reads live config + stores; refreshes every proactive-policy credential that
+ * will expire before the next sweep (tick + lead horizon). Never throws — per-credential failures
+ * are captured into backoff and the result. Returns a redacted summary (provider names / account
+ * ids only, never tokens).
+ */
+export async function guardianSweep(nowMs: number = Date.now()): Promise<GuardianSweepResult> {
+  const writerGeneration = captureConfigGeneration();
+  const config: OcxConfig = loadConfig();
+  const g = config.tokenGuardian;
+  const result: GuardianSweepResult = { enabled: !!g?.enabled, refreshed: [], warmed: [], failed: [], skippedBackoff: [] };
+  if (!g?.enabled) return result;
+
+  const opts = resolved(g);
+  const horizonMs = (opts.tickSeconds + opts.leadSeconds) * 1000;
+  const tasks: Array<() => Promise<void>> = [];
+
+  // A) OAuth providers — every account in each provider's set (multiauth keep-alive),
+  // skipping accounts already marked needsReauth (terminal; only a re-login fixes them).
+  for (const provider of listOAuthProviders()) {
+    if (resolveRefreshPolicy(provider, config) !== "proactive") continue;
+    for (const account of listAccounts(provider)) {
+      if (account.needsReauth) continue;
+      if (account.credential.expires > nowMs + horizonMs) continue;
+      const key = `oauth:${provider}:${account.id}`;
+      if (inBackoff(key, nowMs)) { result.skippedBackoff.push(key); continue; }
+      tasks.push(async () => {
+        try {
+          await getValidAccessTokenForAccount(provider, account.id);
+          backoff.delete(key);
+          result.refreshed.push(key);
+        } catch (err) {
+          // Terminal grant failures surface as OAuthLoginRequiredError (account marked
+          // needsReauth by the resolver) — back off at the ceiling; transient errors backoff exponentially.
+          const permanent = err instanceof OAuthLoginRequiredError;
+          recordFailure(key, nowMs, opts.backoffBaseSeconds, opts.backoffMaxSeconds, permanent, writerGeneration);
+          result.failed.push(key);
+        }
+      });
+    }
+  }
+
+  // B) canonical OpenAI Codex login. Direct warms main only; pool additionally maintains every
+  // added account. The direct branch returns before the managed account store is enumerated.
+  const openai = config.providers[OPENAI_CODEX_PROVIDER_ID];
+  if (
+    openai
+    && openai.disabled !== true
+    && isCanonicalOpenAiForwardProvider(openai)
+    && resolveRefreshPolicy(OPENAI_CODEX_PROVIDER_ID, config) === "proactive"
+  ) {
+    const mode = providerCodexAccountMode(OPENAI_CODEX_PROVIDER_ID, openai) ?? "pool";
+    if (opts.codexWarmupEnabled) {
+      const key = `codex:${MAIN_CODEX_ACCOUNT_ID}`;
+      if (!inBackoff(key, nowMs)) {
+        tasks.push(async () => {
+          const nativeMainLease = tryAcquireNativeMainProfileClaim();
+          if (!nativeMainLease) return;
+          try {
+            const mainToken = getMainAccountToken();
+            if (!mainToken) return;
+            await warmCodexAccount({
+              accessToken: mainToken.accessToken,
+              chatgptAccountId: mainToken.chatgptAccountId,
+              model: opts.codexWarmupModel,
+            });
+            backoff.delete(key);
+            result.warmed.push(key);
+          } catch (err) {
+            recordFailure(key, nowMs, opts.backoffBaseSeconds, opts.backoffMaxSeconds, false, writerGeneration);
+            result.failed.push(key);
+          } finally {
+            nativeMainLease.release();
+          }
+        });
+      } else {
+        result.skippedBackoff.push(key);
+      }
+    }
+
+    const addedAccountIds = mode === "pool" ? listCodexAccountIds() : [];
+    for (const id of addedAccountIds) {
+      const record = readCodexAccountRecord(id);
+      if (!record || record.deletedAt != null) continue;
+      const cred = record.credential;
+      if (!cred) continue;
+      const needsRefresh = cred.expiresAt <= nowMs + horizonMs;
+      const needsWarmup = opts.codexWarmupEnabled
+        && (record.lastCodexValidatedAt === undefined || nowMs - record.lastCodexValidatedAt > opts.codexWarmupMaxAgeSeconds * 1000);
+      if (!needsRefresh && !needsWarmup) continue;
+      const key = `codex:${id}`;
+      if (inBackoff(key, nowMs)) { result.skippedBackoff.push(key); continue; }
+      tasks.push(async () => {
+        try {
+          const token = await getValidCodexToken(id);
+          if (needsRefresh) result.refreshed.push(key);
+          if (needsWarmup) {
+            await warmCodexAccount({
+              accessToken: token.accessToken,
+              chatgptAccountId: token.chatgptAccountId,
+              model: opts.codexWarmupModel,
+            });
+            markCodexAccountValidated(id, Date.now());
+            result.warmed.push(key);
+          }
+          backoff.delete(key);
+        } catch (err) {
+          if (err instanceof CodexCredentialRefreshBusyError || err instanceof CodexCredentialRefreshStaleError) {
+            recordFailure(key, nowMs, opts.backoffBaseSeconds, opts.backoffMaxSeconds, false, writerGeneration);
+            result.skippedBackoff.push(key);
+            return;
+          }
+          const permanent = err instanceof TokenRefreshError && (err.reason === "revoked" || err.reason === "expired");
+          if (needsWarmup && !(err instanceof TokenRefreshError)) {
+            markCodexAccountValidationFailed(id, codexWarmupFailureReason(err));
+          }
+          recordFailure(key, nowMs, opts.backoffBaseSeconds, opts.backoffMaxSeconds, permanent, writerGeneration);
+          result.failed.push(key);
+        }
+      });
+    }
+  }
+
+  await runWithConcurrency(tasks, opts.concurrency);
+  return result;
+}
+
+export function reconcileGuardianBackoff(context: GenerationContext): number {
+  if (context.generation <= lastReconciledGeneration) return 0;
+  const valid = new Set<string>();
+  for (const id of context.codexAccountIds) valid.add(`codex:${id}`);
+  for (const key of context.oauthAccountKeys) {
+    const separator = key.indexOf("\0");
+    if (separator <= 0) continue;
+    valid.add(`oauth:${key.slice(0, separator)}:${key.slice(separator + 1)}`);
+  }
+  let removed = 0;
+  for (const key of backoff.keys()) {
+    if (valid.has(key)) continue;
+    backoff.delete(key);
+    removed += 1;
+  }
+  liveBackoffKeys = valid;
+  lastReconciledGeneration = context.generation;
+  return removed;
+}
+
+/**
+ * Start the background sweep loop. Returns a handle whose stop() clears the pending timer (in-flight
+ * refreshes settle on their own). Schedules recursively so each interval gets fresh jitter. The loop
+ * runs even when the guardian is disabled (each sweep is a cheap no-op) so toggling `enabled` in
+ * config takes effect on the next tick without a restart.
+ */
+export function startTokenGuardian(): TokenGuardianHandle {
+  let stopped = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const scheduleNext = () => {
+    if (stopped) return;
+    const opts = resolved(loadConfig().tokenGuardian);
+    const delayMs = (opts.tickSeconds + Math.random() * opts.jitterSeconds) * 1000;
+    timer = setTimeout(runSweep, delayMs);
+    if (typeof timer.unref === "function") timer.unref(); // never keep the process alive for a sweep
+  };
+
+  const runSweep = () => {
+    void guardianSweep()
+      .then(r => {
+        if (r.enabled && (r.refreshed.length || r.warmed.length || r.failed.length)) {
+          console.log(`🛡️  token-guardian: refreshed ${r.refreshed.length}, warmed ${r.warmed.length}, failed ${r.failed.length}`);
+        }
+      })
+      .catch(err => console.log(`token-guardian sweep error: ${err instanceof Error ? err.message : String(err)}`))
+      .finally(scheduleNext);
+  };
+
+  scheduleNext();
+  return {
+    stop() {
+      stopped = true;
+      if (timer) clearTimeout(timer);
+    },
+  };
+}

package/src/oauth/types.ts

@@ -0,0 +1,62 @@
+/** Minimal OAuth types, ported from jawcode packages/ai/src/utils/oauth/types.ts. */
+export type OAuthCredentialSource = "oauth" | "local-cli" | "credential-file" | "environment" | "manual";
+
+/** Account-scoped Kiro data required for refresh and request routing. */
+export interface KiroOAuthMetadata {
+  profileArn?: string;
+  ssoRegion?: string;
+  apiRegion?: string;
+  clientId?: string;
+  clientSecret?: string;
+}
+
+export type OAuthCredentials = {
+  refresh: string;
+  access: string;
+  /** Epoch ms after any small provider-specific early-refresh margin; the shared gate adds 1 minute. */
+  expires: number;
+  email?: string;
+  accountId?: string;
+  source?: OAuthCredentialSource;
+  /** Google Antigravity (Cloud Code Assist) discovered project id; injected into the CCA envelope. */
+  projectId?: string;
+  /**
+   * GitHub Copilot allowlisted API origin from token `endpoints.api` (HTTPS `*.githubcopilot.com` only).
+   * Never reuse for Antigravity projectId; validated on write and again at request time.
+   */
+  apiBaseUrl?: string;
+  /** Never returned by management APIs; persisted only inside the protected auth-store boundary. */
+  kiro?: KiroOAuthMetadata;
+};
+
+/** One logged-in account inside a provider's account set (multiauth). */
+export interface ProviderAccount {
+  /** Stable short id, generated once at append time; never re-derived after rotation. */
+  id: string;
+  /** User-owned display label; never participates in auth identity or routing. */
+  alias?: string;
+  credential: OAuthCredentials;
+  /** Terminal refresh failure (invalid_grant / reused / revoked) — re-login required. */
+  needsReauth?: boolean;
+  addedAt?: number;
+}
+
+/** auth.json value per provider: N accounts + which one requests use. */
+export interface ProviderAccountSet {
+  activeAccountId: string;
+  accounts: ProviderAccount[];
+}
+
+export interface OAuthController {
+  onAuth?(info: { url: string; instructions?: string; deviceCode?: string }): void;
+  onProgress?(message: string): void;
+  onManualCodeInput?(expectedState?: string): Promise<string>;
+  signal?: AbortSignal;
+}
+
+/**
+ * How a login flow may use a locally detected CLI token.
+ * "off" goes straight to the real OAuth flow, "fallback" imports a local token when present
+ * and falls back to OAuth otherwise, "only" imports without any OAuth fallback.
+ */
+export type LocalTokenImportMode = "off" | "fallback" | "only";

package/src/oauth/xai.ts

@@ -0,0 +1,241 @@
+/** xAI OAuth flow (Grok account login). Ported from jawcode oauth/xai.ts. */
+import { OAuthCallbackFlow, type OAuthCallbackFlowOptions } from "./callback-server";
+import { generatePKCE } from "./pkce";
+import type { LocalTokenImportMode, OAuthController, OAuthCredentials } from "./types";
+
+const XAI_OAUTH_ISSUER = "https://auth.x.ai";
+export const XAI_OAUTH_DISCOVERY_URL = `${XAI_OAUTH_ISSUER}/.well-known/openid-configuration`;
+export const XAI_OAUTH_CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828";
+export const XAI_OAUTH_SCOPE = "openid profile email offline_access grok-cli:access api:access";
+const XAI_OAUTH_CALLBACK_PORT = 56121;
+const XAI_OAUTH_CALLBACK_PATH = "/callback";
+const XAI_OAUTH_REFRESH_SKEW_MS = 2 * 60 * 1000;
+const TOKEN_REQUEST_TIMEOUT_MS = 30_000;
+
+export const XAI_LOCAL_CLI_DETACH_WARNING =
+  "[oauth:xai] Grok CLI credential was stale; refreshed into OpenCodex ownership. Grok CLI may require login again.";
+
+interface XaiDiscovery {
+  authorizationEndpoint: string;
+  tokenEndpoint: string;
+}
+
+interface XaiDiscoveryPayload {
+  authorization_endpoint?: unknown;
+  token_endpoint?: unknown;
+}
+
+export interface XaiTokenPayload {
+  access_token?: unknown;
+  refresh_token?: unknown;
+  expires_in?: unknown;
+  id_token?: unknown;
+  token_type?: unknown;
+}
+
+interface XaiJwtPayload {
+  sub?: unknown;
+  email?: unknown;
+  [key: string]: unknown;
+}
+
+function requestSignal(signal: AbortSignal | undefined): AbortSignal {
+  const timeoutSignal = AbortSignal.timeout(TOKEN_REQUEST_TIMEOUT_MS);
+  return signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+}
+
+function validateXaiEndpoint(rawUrl: string): string {
+  const parsed = new URL(rawUrl);
+  const host = parsed.hostname.toLowerCase();
+  if (parsed.protocol !== "https:" || (host !== "x.ai" && !host.endsWith(".x.ai"))) {
+    throw new Error(`xAI OAuth discovery returned an unexpected endpoint: ${rawUrl}`);
+  }
+  return parsed.toString();
+}
+
+export async function discoverXaiOAuthEndpoints(signal?: AbortSignal): Promise<XaiDiscovery> {
+  const response = await fetch(XAI_OAUTH_DISCOVERY_URL, {
+    headers: { Accept: "application/json" },
+    signal: requestSignal(signal),
+  });
+  if (!response.ok) {
+    throw new Error(`xAI OAuth discovery failed: ${response.status} ${await response.text()}`);
+  }
+
+  const payload = (await response.json()) as XaiDiscoveryPayload;
+  if (typeof payload.authorization_endpoint !== "string" || typeof payload.token_endpoint !== "string") {
+    throw new Error("xAI OAuth discovery response missing authorization/token endpoints");
+  }
+
+  return {
+    authorizationEndpoint: validateXaiEndpoint(payload.authorization_endpoint),
+    tokenEndpoint: validateXaiEndpoint(payload.token_endpoint),
+  };
+}
+
+function decodeJwtPayload(token: string): XaiJwtPayload | 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("utf8")) as XaiJwtPayload;
+  } catch {
+    return undefined;
+  }
+}
+
+function getTokenIdentity(accessToken: string, idToken: string | undefined): { accountId?: string; email?: string } {
+  const payload = (idToken ? decodeJwtPayload(idToken) : undefined) ?? decodeJwtPayload(accessToken);
+  const accountId = typeof payload?.sub === "string" && payload.sub.length > 0 ? payload.sub : undefined;
+  const email =
+    typeof payload?.email === "string" && payload.email.length > 0 ? payload.email.toLowerCase() : undefined;
+  return { accountId, email };
+}
+
+export class XaiTokenRequestError extends Error { constructor(public readonly status?:number,public readonly oauthError?:string,message="xAI token request failed",options?:{cause?:unknown}){super(message,options);this.name="XaiTokenRequestError";} }
+export interface XaiTokenRetryDeps { sleep?:(ms:number)=>Promise<void>; random?:()=>number }
+function isAbortError(error:unknown):boolean{return error instanceof DOMException&&error.name==="AbortError";}
+function retryDelay(attempt:number,retryAfter:string|null,random:()=>number):number{const base=attempt===1?100:250,j=Math.round(base*(.75+random()*.5)),seconds=retryAfter!==null&&/^\d+$/.test(retryAfter)?Number(retryAfter):0;return Math.min(2000,Math.max(j,seconds*1000));}
+async function readTokenError(response:Response):Promise<XaiTokenRequestError>{let oauthError:string|undefined,detail="";try{const body=await response.json() as {error?:unknown;error_description?:unknown};if(typeof body.error==="string")oauthError=body.error;if(typeof body.error_description==="string")detail=body.error_description;}catch{}const suffix=detail?`: ${detail}`:oauthError?`: ${oauthError}`:"";return new XaiTokenRequestError(response.status,oauthError,`xAI token request failed: ${response.status}${suffix}`);}
+export async function postXaiToken(
+  tokenEndpoint: string,
+  body: Record<string, string>,
+  signal?: AbortSignal, deps:XaiTokenRetryDeps={},
+): Promise<XaiTokenPayload> {
+ const sleep=deps.sleep??(ms=>Bun.sleep(ms)),random=deps.random??Math.random;let last:unknown;
+ for(let attempt=1;attempt<=3;attempt++){let response:Response;try{response=await fetch(tokenEndpoint, {
+    method: "POST",
+    headers: {
+      Accept: "application/json",
+      "Content-Type": "application/x-www-form-urlencoded",
+    },
+    body: new URLSearchParams(body).toString(),
+    signal: requestSignal(signal),
+  });}catch(error){if(isAbortError(error)&&signal?.aborted)throw error;last=error;if(attempt===3)throw new XaiTokenRequestError(undefined,undefined,"xAI token request failed: network error",{cause:error});await sleep(retryDelay(attempt,null,random));continue;}if(response.ok)return await response.json() as XaiTokenPayload;const error=await readTokenError(response);last=error;if(!(response.status===429||response.status>=500)||attempt===3)throw error;await sleep(retryDelay(attempt,response.headers.get("retry-after"),random));}throw last;
+}
+
+function credentialsFromTokenPayload(payload: XaiTokenPayload, refreshFallback = ""): OAuthCredentials {
+  if (typeof payload.access_token !== "string" || payload.access_token.length === 0) {
+    throw new Error("xAI token response did not include an access token");
+  }
+  const refresh =
+    typeof payload.refresh_token === "string" && payload.refresh_token.length > 0
+      ? payload.refresh_token
+      : refreshFallback;
+  if (!refresh) {
+    throw new Error("xAI token response did not include a refresh token");
+  }
+  const expiresIn =
+    typeof payload.expires_in === "number" && Number.isFinite(payload.expires_in) ? payload.expires_in : 3600;
+  const idToken = typeof payload.id_token === "string" ? payload.id_token : undefined;
+  const { accountId, email } = getTokenIdentity(payload.access_token, idToken);
+  return {
+    refresh,
+    access: payload.access_token,
+    expires: Date.now() + expiresIn * 1000 - XAI_OAUTH_REFRESH_SKEW_MS,
+    accountId,
+    email,
+  };
+}
+
+export class XaiOAuthFlow extends OAuthCallbackFlow {
+  #verifier = "";
+  #discovery: XaiDiscovery | undefined;
+
+  constructor(ctrl: OAuthController) {
+    super(ctrl, {
+      preferredPort: XAI_OAUTH_CALLBACK_PORT,
+      callbackPath: XAI_OAUTH_CALLBACK_PATH,
+      callbackHostname: "127.0.0.1",
+      callbackBindHostname: "127.0.0.1",
+      redirectUri: `http://127.0.0.1:${XAI_OAUTH_CALLBACK_PORT}${XAI_OAUTH_CALLBACK_PATH}`,
+    } satisfies OAuthCallbackFlowOptions);
+  }
+
+  async generateAuthUrl(state: string, redirectUri: string): Promise<{ url: string; instructions?: string }> {
+    const pkce = await generatePKCE();
+    this.#verifier = pkce.verifier;
+    this.#discovery = await discoverXaiOAuthEndpoints(this.ctrl.signal);
+    const params = new URLSearchParams({
+      response_type: "code",
+      client_id: XAI_OAUTH_CLIENT_ID,
+      redirect_uri: redirectUri,
+      scope: XAI_OAUTH_SCOPE,
+      code_challenge: pkce.challenge,
+      code_challenge_method: "S256",
+      state,
+      nonce: crypto.randomUUID(),
+    });
+    return {
+      url: `${this.#discovery.authorizationEndpoint}?${params.toString()}`,
+      instructions:
+        "Complete xAI/Grok 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> {
+    if (!this.#verifier) {
+      throw new Error("xAI OAuth PKCE verifier was not initialized");
+    }
+    const discovery = this.#discovery ?? (await discoverXaiOAuthEndpoints(this.ctrl.signal));
+    const tokenPayload = await postXaiToken(
+      discovery.tokenEndpoint,
+      {
+        grant_type: "authorization_code",
+        client_id: XAI_OAUTH_CLIENT_ID,
+        code,
+        redirect_uri: redirectUri,
+        code_verifier: this.#verifier,
+      },
+      this.ctrl.signal,
+    );
+    return credentialsFromTokenPayload(tokenPayload);
+  }
+}
+
+export async function loginXai(
+  ctrl: OAuthController,
+  opts?: { importLocal?: LocalTokenImportMode },
+): Promise<OAuthCredentials> {
+  const importLocal = opts?.importLocal ?? "off";
+  if (importLocal !== "off") {
+    const { detectGrokCliToken } = await import("./local-token-detect");
+    const local = detectGrokCliToken();
+    if (local) {
+      ctrl.onProgress?.("Found Grok CLI token, importing automatically");
+      if (local.expires >= Date.now() + 60_000) return local;
+      try {
+        const fresh = await refreshXaiToken(local.refresh, ctrl.signal);
+        ctrl.onProgress?.(XAI_LOCAL_CLI_DETACH_WARNING);
+        return { ...fresh, source: "oauth" };
+      } catch (error) {
+        if (importLocal === "only") {
+          throw new Error(
+            `Grok CLI token is expired and could not be refreshed: ${error instanceof Error ? error.message : String(error)}`,
+          );
+        }
+      }
+    } else if (importLocal === "only") {
+      throw new Error("No Grok CLI token found at ~/.grok/auth.json. Run 'ocx login xai' for browser OAuth.");
+    }
+  }
+
+  return new XaiOAuthFlow(ctrl).login();
+}
+
+export async function refreshXaiToken(refreshToken: string, signal?: AbortSignal): Promise<OAuthCredentials> {
+  if (!refreshToken) {
+    throw new Error("xAI credentials are expired and do not include a refresh token");
+  }
+  const discovery = await discoverXaiOAuthEndpoints(signal);
+  const tokenPayload = await postXaiToken(
+    discovery.tokenEndpoint,
+    {
+      grant_type: "refresh_token",
+      client_id: XAI_OAUTH_CLIENT_ID,
+      refresh_token: refreshToken,
+    },
+    signal,
+  );
+  return credentialsFromTokenPayload(tokenPayload, refreshToken);
+}

package/src/providers/alibaba-region-backup.ts

@@ -0,0 +1,75 @@
+import { copyFileSync, existsSync, linkSync, readFileSync, rmSync } from "node:fs";
+import { getConfigPath } from "../config";
+
+export interface AlibabaBackupIO {
+  exists: (path: string) => boolean;
+  read: (path: string) => Buffer;
+  copy: (source: string, destination: string) => void;
+  /** Publish with no-replace semantics: fails with EEXIST if the destination exists. */
+  publishNoReplace: (temp: string, destination: string) => void;
+  remove: (path: string) => void;
+}
+
+const DEFAULT_IO: AlibabaBackupIO = {
+  exists: existsSync,
+  read: path => readFileSync(path),
+  copy: (source, destination) => copyFileSync(source, destination),
+  publishNoReplace: linkSync,
+  remove: path => rmSync(path, { force: true }),
+};
+
+export class AlibabaBackupIntegrityError extends Error {}
+
+/**
+ * Immutable pre-migration snapshot of `config.json`.
+ *
+ * Written to a temp file first and published by `link`, which fails with EEXIST
+ * rather than replacing. Exclusive *creation* alone is not enough: a crash
+ * mid-copy can leave a truncated destination that the next run would accept as a
+ * valid rollback point. Copy-verify-link means a published snapshot is always a
+ * complete one.
+ *
+ * An existing snapshot is NOT required to equal the current config. Demanding
+ * that has a false positive that would brick a working install: a run that
+ * created the snapshot and then aborted for an unrelated reason leaves a
+ * perfectly valid snapshot, the user then edits `config.json` legitimately, and
+ * every subsequent start would throw out of `startServer` and refuse to boot. A
+ * safety net must never become the thing that stops the product.
+ *
+ * So an existing snapshot is reused as-is — it is the earliest one, which is
+ * exactly what a rollback point should be. Integrity is carried by publication.
+ *
+ * Deliberately not built on `backupConfigBeforeOpenAiTierMigration`: that
+ * function's stale/rollback classification exists for a repeatable migration and
+ * would be wrong here.
+ */
+export function backupConfigBeforeAlibabaRegionMigration(
+  configPath = getConfigPath(),
+  io: AlibabaBackupIO = DEFAULT_IO,
+): "absent" | "created" | "reused" {
+  if (!io.exists(configPath)) return "absent";
+  const backup = `${configPath}.pre-alibaba-region-v1.bak`;
+  // The earliest snapshot is the most valuable one: it predates every migration
+  // this config has been through.
+  if (io.exists(backup)) return "reused";
+
+  const source = io.read(configPath);
+  const temp = `${backup}.${process.pid}.tmp`;
+  try {
+    io.copy(configPath, temp);
+    // Verify before publishing: a short copy must never become the snapshot.
+    if (!io.read(temp).equals(source)) {
+      throw new AlibabaBackupIntegrityError(`failed to write a complete backup to ${temp}`);
+    }
+    io.publishNoReplace(temp, backup);
+    return "created";
+  } catch (error) {
+    // Another process published between our `exists` check and the link. It went
+    // through the same copy-verify-link sequence, so it is complete by
+    // construction — nothing else writes this filename.
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") return "reused";
+    throw error;
+  } finally {
+    io.remove(temp);
+  }
+}