@bitkyc08/opencodex 0.1.0

package/src/oauth/kimi.ts

@@ -0,0 +1,160 @@
+/** Kimi Code OAuth flow (device authorization grant). Ported from jawcode oauth/kimi.ts. */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import * as os from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { getConfigDir } from "../config";
+import type { OAuthController, OAuthCredentials } from "./types";
+
+const CLIENT_ID = "17e5f671-d194-4dfb-9706-5516cb48c098";
+const DEFAULT_OAUTH_HOST = "https://auth.kimi.com";
+const DEVICE_ID_FILENAME = "kimi-device-id";
+const DEFAULT_POLL_INTERVAL_MS = 5000;
+const DEFAULT_DEVICE_FLOW_TTL_MS = 15 * 60 * 1000;
+const OAUTH_EXPIRY_SKEW_MS = 5 * 60 * 1000;
+const KIMI_CLI_VERSION = "1.0.0";
+
+interface DeviceAuthorizationResponse {
+  user_code?: string;
+  device_code?: string;
+  verification_uri?: string;
+  verification_uri_complete?: string;
+  expires_in?: number;
+  interval?: number;
+}
+
+interface TokenResponse {
+  access_token?: string;
+  refresh_token?: string;
+  expires_in?: number;
+  error?: string;
+  error_description?: string;
+  interval?: number;
+}
+
+function resolveOAuthHost(): string {
+  return process.env.KIMI_CODE_OAUTH_HOST || process.env.KIMI_OAUTH_HOST || DEFAULT_OAUTH_HOST;
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(new Error("Login cancelled"));
+    const t = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => { clearTimeout(t); reject(new Error("Login cancelled")); }, { once: true });
+  });
+}
+
+function getDeviceModel(): string {
+  const platform = os.platform();
+  const label = platform === "darwin" ? "macOS" : platform === "win32" ? "Windows" : platform === "linux" ? "Linux" : platform;
+  return [label, os.release(), os.arch()].filter(Boolean).join(" ").trim();
+}
+
+let deviceIdCache: string | undefined;
+function getDeviceId(): string {
+  if (deviceIdCache) return deviceIdCache;
+  const p = join(getConfigDir(), DEVICE_ID_FILENAME);
+  try {
+    const existing = readFileSync(p, "utf-8").trim();
+    if (existing) { deviceIdCache = existing; return existing; }
+  } catch (e) {
+    if ((e as { code?: string })?.code !== "ENOENT") throw e;
+  }
+  const id = randomUUID().replace(/-/g, "");
+  if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
+  writeFileSync(p, id + "\n", { mode: 0o600 });
+  deviceIdCache = id;
+  return id;
+}
+
+function getKimiCommonHeaders(): Record<string, string> {
+  return {
+    "User-Agent": `KimiCLI/${KIMI_CLI_VERSION}`,
+    "X-Msh-Platform": "kimi_cli",
+    "X-Msh-Version": KIMI_CLI_VERSION,
+    "X-Msh-Device-Name": os.hostname(),
+    "X-Msh-Device-Model": getDeviceModel(),
+    "X-Msh-Os-Version": os.version(),
+    "X-Msh-Device-Id": getDeviceId(),
+  };
+}
+
+async function requestDeviceAuthorization(): Promise<{
+  userCode: string; deviceCode: string; verificationUriComplete: string; expiresInMs: number; intervalMs: number;
+}> {
+  const response = await fetch(`${resolveOAuthHost()}/api/oauth/device_authorization`, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded", ...getKimiCommonHeaders() },
+    body: new URLSearchParams({ client_id: CLIENT_ID }),
+  });
+  if (!response.ok) {
+    throw new Error(`Kimi device authorization failed: ${response.status} ${await response.text()}`);
+  }
+  const payload = (await response.json()) as DeviceAuthorizationResponse;
+  if (!payload.user_code || !payload.device_code || !payload.verification_uri) {
+    throw new Error("Kimi device authorization response missing required fields");
+  }
+  return {
+    userCode: payload.user_code,
+    deviceCode: payload.device_code,
+    verificationUriComplete: payload.verification_uri_complete || payload.verification_uri,
+    expiresInMs: typeof payload.expires_in === "number" ? payload.expires_in * 1000 : DEFAULT_DEVICE_FLOW_TTL_MS,
+    intervalMs: typeof payload.interval === "number" && payload.interval > 0 ? payload.interval * 1000 : DEFAULT_POLL_INTERVAL_MS,
+  };
+}
+
+function parseTokenPayload(payload: TokenResponse, refreshFallback?: string): OAuthCredentials {
+  if (!payload.access_token || typeof payload.expires_in !== "number") {
+    throw new Error("Kimi token response missing required fields");
+  }
+  const refresh = payload.refresh_token ?? refreshFallback;
+  if (!refresh) throw new Error("Kimi token response missing refresh token");
+  return { access: payload.access_token, refresh, expires: Date.now() + payload.expires_in * 1000 - OAUTH_EXPIRY_SKEW_MS };
+}
+
+async function pollForToken(deviceCode: string, intervalMs: number, expiresInMs: number, signal?: AbortSignal): Promise<OAuthCredentials> {
+  const deadline = Date.now() + expiresInMs;
+  let waitMs = Math.max(1000, intervalMs);
+  while (Date.now() < deadline) {
+    if (signal?.aborted) throw new Error("Login cancelled");
+    const response = await fetch(`${resolveOAuthHost()}/api/oauth/token`, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded", ...getKimiCommonHeaders() },
+      body: new URLSearchParams({ client_id: CLIENT_ID, device_code: deviceCode, grant_type: "urn:ietf:params:oauth:grant-type:device_code" }),
+    });
+    const payload = (await response.json()) as TokenResponse;
+    if (response.ok && payload.access_token) return parseTokenPayload(payload);
+    const error = payload.error;
+    if (error === "authorization_pending") { await sleep(waitMs, signal); continue; }
+    if (error === "slow_down") {
+      waitMs += 5000;
+      const retryAfter = typeof payload.interval === "number" ? payload.interval * 1000 : undefined;
+      if (retryAfter && retryAfter > waitMs) waitMs = retryAfter;
+      await sleep(waitMs, signal);
+      continue;
+    }
+    if (error === "expired_token") throw new Error("Kimi device authorization expired");
+    if (error === "access_denied") throw new Error("Kimi device authorization denied");
+    throw new Error(`Kimi device flow failed: ${error ?? response.status}${payload.error_description ? `: ${payload.error_description}` : ""}`);
+  }
+  throw new Error("Kimi device flow timed out");
+}
+
+export async function loginKimi(ctrl: OAuthController): Promise<OAuthCredentials> {
+  const device = await requestDeviceAuthorization();
+  ctrl.onAuth?.({ url: device.verificationUriComplete, instructions: `Enter code: ${device.userCode}` });
+  return pollForToken(device.deviceCode, device.intervalMs, device.expiresInMs, ctrl.signal);
+}
+
+export async function refreshKimiToken(refreshToken: string): Promise<OAuthCredentials> {
+  const response = await fetch(`${resolveOAuthHost()}/api/oauth/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded", ...getKimiCommonHeaders() },
+    body: new URLSearchParams({ grant_type: "refresh_token", refresh_token: refreshToken, client_id: CLIENT_ID }),
+  });
+  if (!response.ok) {
+    const payload = (await response.json().catch(() => undefined)) as TokenResponse | undefined;
+    throw new Error(`Kimi token refresh failed: ${response.status}${payload?.error_description ? `: ${payload.error_description}` : ""}`);
+  }
+  return parseTokenPayload((await response.json()) as TokenResponse, refreshToken);
+}

package/src/oauth/local-token-detect.ts

@@ -0,0 +1,71 @@
+/**
+ * Local token auto-detection — reads an existing Grok CLI credential (~/.grok/auth.json).
+ * Read-only: never writes to external credential stores.
+ * Ported from jawcode packages/ai/src/utils/oauth/local-token-detect.ts (xAI portion).
+ */
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { OAuthCredentials } from "./types";
+
+const XAI_AUTH_KEY_PREFIX = "https://auth.x.ai::";
+const CLAUDE_KEYCHAIN_SERVICE = "Claude Code-credentials";
+
+export function detectGrokCliToken(): OAuthCredentials | null {
+  const authPath = join(homedir(), ".grok", "auth.json");
+  if (!existsSync(authPath)) return null;
+
+  try {
+    const raw = JSON.parse(readFileSync(authPath, "utf8")) as Record<string, Record<string, unknown>>;
+
+    const entry = Object.entries(raw).find(([key]) => key.startsWith(XAI_AUTH_KEY_PREFIX))?.[1];
+    if (!entry?.key || !entry?.refresh_token) return null;
+
+    const accessToken = entry.key as string;
+    const refreshToken = entry.refresh_token as string;
+    const expiresAt = entry.expires_at ? new Date(entry.expires_at as string).getTime() : 0;
+
+    return {
+      refresh: refreshToken,
+      access: accessToken,
+      expires: expiresAt,
+      accountId: entry.user_id as string | undefined,
+      email: entry.email as string | undefined,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Read the Claude Code OAuth credential from the OS secure store (macOS keychain / linux secret-tool). */
+function readClaudeSecureStorage(): string | null {
+  try {
+    if (process.platform === "darwin") {
+      return execSync(`security find-generic-password -s "${CLAUDE_KEYCHAIN_SERVICE}" -w`, {
+        encoding: "utf8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+    }
+    if (process.platform === "linux") {
+      return execSync(`secret-tool lookup service "${CLAUDE_KEYCHAIN_SERVICE}"`, {
+        encoding: "utf8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"],
+      }).trim();
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export function detectClaudeCodeToken(): OAuthCredentials | null {
+  const raw = readClaudeSecureStorage();
+  if (!raw) return null;
+  try {
+    const data = JSON.parse(raw) as { claudeAiOauth?: { accessToken?: string; refreshToken?: string; expiresAt?: number } };
+    const o = data.claudeAiOauth;
+    if (!o?.accessToken || !o?.refreshToken) return null;
+    return { access: o.accessToken, refresh: o.refreshToken, expires: o.expiresAt ?? 0 };
+  } catch {
+    return null;
+  }
+}

package/src/oauth/login-cli.ts

@@ -0,0 +1,90 @@
+import * as readline from "node:readline";
+import { exec } from "node:child_process";
+import { loadConfig, readPid, saveConfig } from "../config";
+import { OAUTH_PROVIDERS, runLogin } from "./index";
+import { KEY_LOGIN_PROVIDERS, isKeyLoginProvider, validateApiKey } from "./key-providers";
+
+function openBrowser(url: string): void {
+  const cmd =
+    process.platform === "darwin" ? "open" : process.platform === "win32" ? 'start ""' : "xdg-open";
+  exec(`${cmd} "${url}"`, () => {});
+}
+
+/** Push the new provider into a running proxy's live config so it routes without a restart. */
+async function notifyRunningProxy(name: string, provider: unknown): Promise<void> {
+  if (!readPid()) return;
+  const cfg = loadConfig();
+  try {
+    await fetch(`http://localhost:${cfg.port}/api/providers`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name, provider }),
+    });
+  } catch {
+    /* proxy unreachable; disk config loads on next start */
+  }
+}
+
+export async function handleLogin(provider?: string): Promise<void> {
+  const name = (provider ?? "").trim().toLowerCase();
+  if (OAUTH_PROVIDERS[name]) return handleOAuthLogin(name);
+  if (isKeyLoginProvider(name)) return handleKeyLogin(name);
+  console.error(
+    `Usage: ocx login <provider>\n` +
+      `  OAuth login:   ${Object.keys(OAUTH_PROVIDERS).join(", ")}\n` +
+      `  API-key login: ${Object.keys(KEY_LOGIN_PROVIDERS).join(", ")}`,
+  );
+  process.exit(1);
+}
+
+async function handleOAuthLogin(name: string): Promise<void> {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    await runLogin(name, {
+      onAuth: ({ url, instructions }) => {
+        console.log(`\n🔐 Opening browser for ${name} login...\n${url}\n`);
+        if (instructions) console.log(instructions);
+        openBrowser(url);
+      },
+      onProgress: (m) => console.log(`   ${m}`),
+      onManualCodeInput: () =>
+        new Promise((res) => rl.question("Paste redirect URL or code (or wait for browser): ", res)),
+    });
+  } finally {
+    rl.close();
+  }
+  await notifyRunningProxy(name, OAUTH_PROVIDERS[name].providerConfig);
+  console.log(`\n✅ Logged in to ${name}. Try: ocx sync`);
+}
+
+async function handleKeyLogin(name: string): Promise<void> {
+  const def = KEY_LOGIN_PROVIDERS[name];
+  console.log(`\n🔑 ${def.label} — opening ${def.dashboardUrl} so you can create/copy an API key...`);
+  openBrowser(def.dashboardUrl);
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const key = (await new Promise<string>((res) => rl.question(`Paste your ${def.label} API key: `, res))).trim();
+  rl.close();
+  if (!key) {
+    console.error("No key entered.");
+    process.exit(1);
+  }
+  process.stdout.write("   validating… ");
+  const valid = await validateApiKey(def.baseUrl, key);
+  console.log(valid === true ? "valid ✅" : valid === false ? "INVALID ❌" : "couldn't validate (may still work)");
+  if (valid === false) {
+    console.error("Provider rejected the key. Not saved.");
+    process.exit(1);
+  }
+  const provider = {
+    adapter: def.adapter,
+    baseUrl: def.baseUrl,
+    apiKey: key,
+    ...(def.defaultModel ? { defaultModel: def.defaultModel } : {}),
+    ...(def.models ? { models: def.models } : {}),
+  };
+  const config = loadConfig();
+  config.providers[name] = provider;
+  saveConfig(config);
+  await notifyRunningProxy(name, provider);
+  console.log(`✅ ${def.label} added. Try: ocx sync`);
+}

package/src/oauth/pkce.ts

@@ -0,0 +1,15 @@
+/**
+ * Generate PKCE code verifier and challenge (S256).
+ * Ported verbatim from jawcode packages/ai/src/utils/oauth/pkce.ts.
+ */
+export async function generatePKCE(): Promise<{ verifier: string; challenge: string }> {
+  const verifierBytes = new Uint8Array(96);
+  crypto.getRandomValues(verifierBytes);
+  const verifier = Buffer.from(verifierBytes).toString("base64url");
+
+  const data = new TextEncoder().encode(verifier);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  const challenge = Buffer.from(hashBuffer).toString("base64url");
+
+  return { verifier, challenge };
+}

package/src/oauth/store.ts

@@ -0,0 +1,39 @@
+/** OAuth token store at ~/.opencodex/auth.json, keyed by provider name. */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getConfigDir } from "../config";
+import type { OAuthCredentials } from "./types";
+
+const AUTH_PATH = join(getConfigDir(), "auth.json");
+type AuthStore = Record<string, OAuthCredentials>;
+
+export function loadAuthStore(): AuthStore {
+  if (!existsSync(AUTH_PATH)) return {};
+  try {
+    return JSON.parse(readFileSync(AUTH_PATH, "utf-8")) as AuthStore;
+  } catch {
+    return {};
+  }
+}
+
+function persist(store: AuthStore): void {
+  const dir = getConfigDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(AUTH_PATH, JSON.stringify(store, null, 2) + "\n", "utf-8");
+}
+
+export function getCredential(provider: string): OAuthCredentials | null {
+  return loadAuthStore()[provider] ?? null;
+}
+
+export function saveCredential(provider: string, cred: OAuthCredentials): void {
+  const store = loadAuthStore();
+  store[provider] = cred;
+  persist(store);
+}
+
+export function removeCredential(provider: string): void {
+  const store = loadAuthStore();
+  delete store[provider];
+  persist(store);
+}

package/src/oauth/types.ts

@@ -0,0 +1,22 @@
+/** Minimal OAuth types, ported from jawcode packages/ai/src/utils/oauth/types.ts. */
+export type OAuthCredentials = {
+  refresh: string;
+  access: string;
+  expires: number; // epoch ms (already skew-adjusted by the provider flow)
+  email?: string;
+  accountId?: string;
+};
+
+export interface OAuthController {
+  onAuth?(info: { url: string; instructions?: string }): void;
+  onProgress?(message: string): void;
+  onManualCodeInput?(): 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,234 @@
+/** 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;
+
+interface XaiDiscovery {
+  authorizationEndpoint: string;
+  tokenEndpoint: string;
+}
+
+interface XaiDiscoveryPayload {
+  authorization_endpoint?: unknown;
+  token_endpoint?: unknown;
+}
+
+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 };
+}
+
+async function postXaiToken(
+  tokenEndpoint: string,
+  body: Record<string, string>,
+  signal?: AbortSignal,
+): Promise<XaiTokenPayload> {
+  const 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),
+  });
+  if (!response.ok) {
+    throw new Error(`xAI token request failed: ${response.status} ${await response.text()}`);
+  }
+  return (await response.json()) as XaiTokenPayload;
+}
+
+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 {
+        return await refreshXaiToken(local.refresh, ctrl.signal);
+      } 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);
+}