feat(xai): add xAI Grok provider with OAuth + API key auth + image

Adapted from PR #1286 (mugnimaestra/feat/xai-grok-provider) to match existing app architecture. Includes: - OAuth 2.0 with PKCE on loopback port 56121 (Grok Build) - API key auth path (console.x.ai) - Token refresh wiring (open-sse + sse tokenRefresh) - Dashboard OAuth modal with fixed-port flow + manual code fallback - Provider registry entries (OAuth + API key) - xAI image generation via OpenAI-compatible adapter (grok-2-image-1212 model, no size/quality/style params) Excludes (intentionally, to match app patterns): - Custom xAI Responses executor (DefaultExecutor handles /chat/completions) - xAI-specific translators (app uses OpenAI as intermediate format) - Image edits (not supported by current imageGenerationCore) - Video endpoints (app has no video subsystem yet) - CLI xai-login command Refs decolua#1286 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-21 10:18:12 +07:00
parent 0654d7bb35
commit d976f4cc87
21 changed files with 1058 additions and 72 deletions
--- a/src/lib/oauth/constants/xai.js
+++ b/src/lib/oauth/constants/xai.js
@@ -0,0 +1,61 @@
+/**
+ * xAI (Grok) OAuth Configuration
+ *
+ * Source of truth: router-for-me/CLIProxyAPI internal/auth/xai/types.go
+ * Mirrors the upstream Go constants 1:1.
+ */
+
+// xAI client_id for OAuth (PKCE public client)
+export const XAI_CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828";
+
+// OAuth issuer + endpoints
+export const XAI_ISSUER = "https://auth.x.ai";
+export const XAI_AUTH_ENDPOINT_PATH = "/oauth2/authorize";
+export const XAI_TOKEN_ENDPOINT_PATH = "/oauth2/token";
+export const XAI_DISCOVERY_PATH = "/.well-known/openid-configuration";
+
+// Scopes (space-separated, matches Go upstream)
+export const XAI_SCOPE = "openid profile email offline_access grok-cli:access api:access";
+
+// xAI inference API base URL
+export const XAI_API_BASE = "https://api.x.ai/v1";
+
+// Loopback callback (PKCE)
+export const XAI_LOOPBACK_PORT = 56121;
+export const XAI_CALLBACK_PATH = "/callback";
+export const XAI_REDIRECT_URI = `http://127.0.0.1:${XAI_LOOPBACK_PORT}${XAI_CALLBACK_PATH}`;
+
+// PKCE verifier length (bytes pre-base64url)
+export const XAI_PKCE_VERIFIER_BYTES = 96;
+
+// Refresh tokens this many seconds before expiry
+export const XAI_REFRESH_LEAD_SECONDS = 5 * 60;
+
+// User-Agent — mirror Go grok-cli UA. Version is best-effort; xAI does not pin a specific version.
+export const XAI_USER_AGENT = "grok-cli/9router";
+
+/**
+ * Aggregated config object — mirrors the shape of CLAUDE_CONFIG/CODEX_CONFIG in oauth.js.
+ * Includes both the discovery-derived defaults and the static fallbacks used when
+ * discovery is unavailable. Discovery results override authorizeUrl/tokenUrl at runtime.
+ */
+export const XAI_CONFIG = {
+  clientId: XAI_CLIENT_ID,
+  issuer: XAI_ISSUER,
+  authEndpointPath: XAI_AUTH_ENDPOINT_PATH,
+  tokenEndpointPath: XAI_TOKEN_ENDPOINT_PATH,
+  discoveryPath: XAI_DISCOVERY_PATH,
+  // Static fallbacks (these are also the values returned by xAI discovery today)
+  authorizeUrl: `${XAI_ISSUER}${XAI_AUTH_ENDPOINT_PATH}`,
+  tokenUrl: `${XAI_ISSUER}${XAI_TOKEN_ENDPOINT_PATH}`,
+  discoveryUrl: `${XAI_ISSUER}${XAI_DISCOVERY_PATH}`,
+  scope: XAI_SCOPE,
+  apiBaseUrl: XAI_API_BASE,
+  redirectUri: XAI_REDIRECT_URI,
+  loopbackPort: XAI_LOOPBACK_PORT,
+  callbackPath: XAI_CALLBACK_PATH,
+  pkceVerifierBytes: XAI_PKCE_VERIFIER_BYTES,
+  refreshLeadSeconds: XAI_REFRESH_LEAD_SECONDS,
+  userAgent: XAI_USER_AGENT,
+  codeChallengeMethod: "S256",
+};
--- a/src/lib/oauth/providers.js
+++ b/src/lib/oauth/providers.js
@@ -5,6 +5,7 @@

 // Ensure outbound fetch respects HTTP(S)_PROXY/ALL_PROXY in Node runtime
 import "open-sse/index.js";
+import crypto from "crypto";

 import { generatePKCE, generateState } from "./utils/pkce";
 import {
@@ -25,6 +26,11 @@ import {
  CODEBUDDY_CONFIG,
  getOAuthClientMetadata,
 } from "./constants/oauth";
+import { XAI_CONFIG, XAI_PKCE_VERIFIER_BYTES } from "./constants/xai";
+import {
+  decodeIdTokenEmail as decodeXaiIdTokenEmail,
+  discoverEndpoints as discoverXaiEndpoints,
+} from "./services/xai";

 const BASE64_BLOCK_SIZE = 4;

@@ -186,6 +192,77 @@ const PROVIDERS = {
    },
  },

+  xai: {
+    config: XAI_CONFIG,
+    flowType: "authorization_code_pkce",
+    fixedPort: XAI_CONFIG.loopbackPort,
+    callbackPath: XAI_CONFIG.callbackPath,
+    pkceVerifierBytes: XAI_PKCE_VERIFIER_BYTES,
+    prepareConfig: async (config) => {
+      const endpoints = await discoverXaiEndpoints();
+      return {
+        ...config,
+        authorizeUrl: endpoints.authorizeUrl,
+        tokenUrl: endpoints.tokenUrl,
+      };
+    },
+    buildAuthUrl: (config, redirectUri, state, codeChallenge) => {
+      // Mirror CLIProxyAPI BuildAuthorizeURL: includes nonce, plan, referrer
+      const nonce = crypto.randomBytes(16).toString("hex");
+      const params = {
+        response_type: "code",
+        client_id: config.clientId,
+        redirect_uri: redirectUri,
+        scope: config.scope,
+        code_challenge: codeChallenge,
+        code_challenge_method: config.codeChallengeMethod,
+        state,
+        nonce,
+        plan: "generic",
+        referrer: "cli-proxy-api",
+      };
+      const qs = Object.entries(params)
+        .map(([k, v]) => `${k}=${encodeURIComponent(v)}`)
+        .join("&");
+      return `${config.authorizeUrl}?${qs}`;
+    },
+    exchangeToken: async (config, code, redirectUri, codeVerifier) => {
+      const response = await fetch(config.tokenUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          Accept: "application/json",
+        },
+        body: new URLSearchParams({
+          grant_type: "authorization_code",
+          client_id: config.clientId,
+          code,
+          redirect_uri: redirectUri,
+          code_verifier: codeVerifier,
+        }),
+      });
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`xAI token exchange failed: ${error}`);
+      }
+      return await response.json();
+    },
+    mapTokens: (tokens) => {
+      const mapped = {
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token,
+        expiresIn: tokens.expires_in,
+        scope: tokens.scope,
+      };
+      const email = decodeXaiIdTokenEmail(tokens.id_token);
+      if (email) mapped.email = email;
+      if (tokens.id_token) {
+        mapped.providerSpecificData = { idToken: tokens.id_token };
+      }
+      return mapped;
+    },
+  },
+
  "gemini-cli": {
    config: GEMINI_CONFIG,
    flowType: "authorization_code",
@@ -1183,18 +1260,21 @@ export function getProviderNames() {
 * Generate auth data for a provider
 * @param {object} [meta] - Provider-specific metadata (e.g. gitlab clientId/baseUrl)
 */
-export function generateAuthData(providerName, redirectUri, meta) {
+export async function generateAuthData(providerName, redirectUri, meta) {
  const provider = getProvider(providerName);
-  const { codeVerifier, codeChallenge, state } = generatePKCE();
+  const config = provider.prepareConfig
+    ? await provider.prepareConfig(provider.config, meta || {})
+    : provider.config;
+  const { codeVerifier, codeChallenge, state } = generatePKCE(provider.pkceVerifierBytes);

  let authUrl;
  if (provider.flowType === "device_code") {
    // Device code flow doesn't have auth URL upfront
    authUrl = null;
  } else if (provider.flowType === "authorization_code_pkce") {
-    authUrl = provider.buildAuthUrl(provider.config, redirectUri, state, codeChallenge, meta || {});
+    authUrl = provider.buildAuthUrl(config, redirectUri, state, codeChallenge, meta || {});
  } else {
-    authUrl = provider.buildAuthUrl(provider.config, redirectUri, state, undefined, meta || {});
+    authUrl = provider.buildAuthUrl(config, redirectUri, state, undefined, meta || {});
  }

  return {
@@ -1215,8 +1295,11 @@ export function generateAuthData(providerName, redirectUri, meta) {
 */
 export async function exchangeTokens(providerName, code, redirectUri, codeVerifier, state, meta) {
  const provider = getProvider(providerName);
+  const config = provider.prepareConfig
+    ? await provider.prepareConfig(provider.config, meta || {})
+    : provider.config;

-  const tokens = await provider.exchangeToken(provider.config, code, redirectUri, codeVerifier, state, meta || {});
+  const tokens = await provider.exchangeToken(config, code, redirectUri, codeVerifier, state, meta || {});

  let extra = null;
  if (provider.postExchange) {
--- a/src/lib/oauth/services/xai.js
+++ b/src/lib/oauth/services/xai.js
@@ -0,0 +1,238 @@
+import open from "open";
+import { OAuthService } from "./oauth.js";
+import crypto from "crypto";
+import { XAI_CONFIG, XAI_PKCE_VERIFIER_BYTES } from "../constants/xai.js";
+import { startLocalServer } from "../utils/server.js";
+import { generateCodeVerifier, generateCodeChallenge, generateState } from "../utils/pkce.js";
+import { spinner as createSpinner } from "../utils/ui.js";
+
+/**
+ * xAI (Grok) OAuth Service
+ *
+ * Source of truth: router-for-me/CLIProxyAPI internal/auth/xai/xai.go
+ *
+ * Flow:
+ *  1. Discover endpoints from `${XAI_ISSUER}/.well-known/openid-configuration`
+ *  2. Bind loopback server on 127.0.0.1:56121, path /callback
+ *  3. PKCE S256 with 96-byte verifier
+ *  4. Exchange code with form-urlencoded body
+ *  5. id_token email decode (no signature verify, mirrors Go)
+ */
+
+const BASE64_BLOCK_SIZE = 4;
+
+let cachedDiscovery = null;
+
+export function validateOAuthEndpoint(rawUrl, field) {
+  const value = String(rawUrl || "").trim();
+  if (!value) throw new Error(`xai discovery ${field} is empty`);
+
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch (err) {
+    throw new Error(`xai discovery ${field} is invalid: ${err.message}`);
+  }
+
+  if (parsed.protocol !== "https:") {
+    throw new Error(`xai discovery ${field} must use https: ${value}`);
+  }
+
+  const host = parsed.hostname.toLowerCase().trim();
+  if (host !== "x.ai" && !host.endsWith(".x.ai")) {
+    throw new Error(`xai discovery ${field} host ${host} is not on x.ai`);
+  }
+
+  return value;
+}
+
+/**
+ * Discover authorization + token endpoints. Cached process-wide.
+ */
+export async function discoverEndpoints() {
+  if (cachedDiscovery) return cachedDiscovery;
+
+  try {
+    const res = await fetch(XAI_CONFIG.discoveryUrl, {
+      headers: { Accept: "application/json" },
+    });
+    if (res.ok) {
+      const data = await res.json();
+      cachedDiscovery = {
+        authorizeUrl: validateOAuthEndpoint(data.authorization_endpoint, "authorization_endpoint"),
+        tokenUrl: validateOAuthEndpoint(data.token_endpoint, "token_endpoint"),
+      };
+      return cachedDiscovery;
+    }
+  } catch {
+    // fall through to static fallback
+  }
+
+  cachedDiscovery = {
+    authorizeUrl: XAI_CONFIG.authorizeUrl,
+    tokenUrl: XAI_CONFIG.tokenUrl,
+  };
+  return cachedDiscovery;
+}
+
+/**
+ * Decode the `email` claim from an id_token JWT. No signature verification —
+ * mirrors CLIProxyAPI Go behavior. Returns undefined if not parseable.
+ */
+export function decodeIdTokenEmail(idToken) {
+  if (!idToken || typeof idToken !== "string") return undefined;
+  const parts = idToken.split(".");
+  if (parts.length !== 3) return undefined;
+  try {
+    const base64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const padding = (BASE64_BLOCK_SIZE - (base64.length % BASE64_BLOCK_SIZE)) % BASE64_BLOCK_SIZE;
+    const json = Buffer.from(base64 + "=".repeat(padding), "base64").toString("utf8");
+    const payload = JSON.parse(json);
+    return payload.email || payload.preferred_username || payload.sub || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export class XaiService extends OAuthService {
+  constructor() {
+    super(XAI_CONFIG);
+  }
+
+  /**
+   * Build xAI authorization URL. Spaces in scope are encoded as %20.
+   */
+  buildXaiAuthUrl(redirectUri, state, codeChallenge, authorizeUrl) {
+    const nonce = crypto.randomBytes(16).toString("hex");
+    const params = {
+      response_type: "code",
+      client_id: XAI_CONFIG.clientId,
+      redirect_uri: redirectUri,
+      scope: XAI_CONFIG.scope,
+      code_challenge: codeChallenge,
+      code_challenge_method: XAI_CONFIG.codeChallengeMethod,
+      state,
+      nonce,
+      plan: "generic",
+      referrer: "cli-proxy-api",
+    };
+    const qs = Object.entries(params)
+      .map(([k, v]) => `${k}=${encodeURIComponent(v)}`)
+      .join("&");
+    return `${authorizeUrl}?${qs}`;
+  }
+
+  /**
+   * Exchange authorization code for tokens.
+   * xAI is a public PKCE client — no client_secret.
+   */
+  async exchangeXaiCode({ tokenUrl, code, redirectUri, codeVerifier }) {
+    const res = await fetch(tokenUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json",
+      },
+      body: new URLSearchParams({
+        grant_type: "authorization_code",
+        client_id: XAI_CONFIG.clientId,
+        code,
+        redirect_uri: redirectUri,
+        code_verifier: codeVerifier,
+      }),
+    });
+
+    if (!res.ok) {
+      const err = await res.text();
+      throw new Error(`xAI token exchange failed: ${err}`);
+    }
+    return await res.json();
+  }
+
+  /**
+   * Refresh an access token using a refresh_token.
+   */
+  async refreshAccessToken(refreshToken) {
+    const { tokenUrl } = await discoverEndpoints();
+    const res = await fetch(tokenUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json",
+      },
+      body: new URLSearchParams({
+        grant_type: "refresh_token",
+        client_id: XAI_CONFIG.clientId,
+        refresh_token: refreshToken,
+      }),
+    });
+    if (!res.ok) {
+      const err = await res.text();
+      throw new Error(`xAI token refresh failed: ${err}`);
+    }
+    return await res.json();
+  }
+
+  /**
+   * Complete xAI OAuth flow end-to-end (CLI entrypoint).
+   * Returns the raw token response plus extracted email.
+   */
+  async connect() {
+    const spinner = createSpinner("Starting xAI OAuth...").start();
+    try {
+      spinner.text = "Discovering xAI endpoints...";
+      const { authorizeUrl, tokenUrl } = await discoverEndpoints();
+
+      spinner.text = `Starting local server on port ${XAI_CONFIG.loopbackPort}...`;
+      let callbackParams = null;
+      const { port, close } = await startLocalServer((params) => {
+        callbackParams = params;
+      }, XAI_CONFIG.loopbackPort);
+      const redirectUri = `http://127.0.0.1:${port}${XAI_CONFIG.callbackPath}`;
+      spinner.succeed(`Local server started on port ${port}`);
+
+      const codeVerifier = generateCodeVerifier(XAI_PKCE_VERIFIER_BYTES);
+      const codeChallenge = generateCodeChallenge(codeVerifier);
+      const state = generateState();
+      const authUrl = this.buildXaiAuthUrl(redirectUri, state, codeChallenge, authorizeUrl);
+
+      console.log("\nOpening browser for xAI authentication...");
+      console.log(`If browser doesn't open, visit:\n${authUrl}\n`);
+      await open(authUrl);
+
+      spinner.start("Waiting for xAI authorization...");
+      await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => reject(new Error("Authentication timeout (5 minutes)")), 300000);
+        const iv = setInterval(() => {
+          if (callbackParams) {
+            clearInterval(iv);
+            clearTimeout(timeout);
+            resolve();
+          }
+        }, 100);
+      });
+      close();
+
+      if (callbackParams.error) {
+        throw new Error(callbackParams.error_description || callbackParams.error);
+      }
+      if (!callbackParams.code) throw new Error("No authorization code received");
+      if (callbackParams.state !== state) throw new Error("Invalid state parameter");
+
+      spinner.start("Exchanging code for tokens...");
+      const tokens = await this.exchangeXaiCode({
+        tokenUrl,
+        code: callbackParams.code,
+        redirectUri,
+        codeVerifier,
+      });
+
+      const email = decodeIdTokenEmail(tokens.id_token);
+      spinner.succeed("xAI connected successfully!");
+      return { tokens, email };
+    } catch (error) {
+      spinner.fail(`Failed: ${error.message}`);
+      throw error;
+    }
+  }
+}
--- a/src/lib/oauth/utils/pkce.js
+++ b/src/lib/oauth/utils/pkce.js
@@ -2,9 +2,11 @@ import crypto from "crypto";

 /**
 * Generate PKCE code verifier (43-128 characters)
+ *
+ * @param {number} [bytes=32] number of random bytes (xAI uses 96)
 */
-export function generateCodeVerifier() {
-  return crypto.randomBytes(32).toString("base64url");
+export function generateCodeVerifier(bytes = 32) {
+  return crypto.randomBytes(bytes).toString("base64url");
 }

 /**
@@ -24,8 +26,8 @@ export function generateState() {
 /**
 * Generate complete PKCE pair
 */
-export function generatePKCE() {
-  const codeVerifier = generateCodeVerifier();
+export function generatePKCE(bytes = 32) {
+  const codeVerifier = generateCodeVerifier(bytes);
  const codeChallenge = generateCodeChallenge(codeVerifier);
  const state = generateState();

@@ -35,4 +37,3 @@ export function generatePKCE() {
    state,
  };
 }
-
--- a/src/lib/oauth/utils/server.js
+++ b/src/lib/oauth/utils/server.js
@@ -274,3 +274,142 @@ export function stopCodexProxy() {
  }
 }

+// ───────────────────────────────────────────────────────────────────────────
+// xAI fixed-port proxy on 127.0.0.1:56121
+// Same shape as the Codex proxy. Kept as a parallel implementation rather than
+// generalizing the Codex one to keep the codex hot-path byte-equivalent.
+// ───────────────────────────────────────────────────────────────────────────
+
+let xaiProxyServer = null;
+let xaiProxyTimeout = null;
+const XAI_PROXY_TIMEOUT_MS = 300000; // 5 minutes
+const XAI_PROXY_PORT = 56121;
+const xaiPendingExchanges = new Map();
+
+export function registerXaiSession({ state, codeVerifier, redirectUri }) {
+  if (!state || !codeVerifier || !redirectUri) return false;
+  xaiPendingExchanges.set(state, {
+    codeVerifier,
+    redirectUri,
+    status: "pending",
+    createdAt: Date.now(),
+  });
+  return true;
+}
+
+export function getXaiSessionStatus(state) {
+  return xaiPendingExchanges.get(state) || null;
+}
+
+export function clearXaiSession(state) {
+  xaiPendingExchanges.delete(state);
+}
+
+function renderXaiResultPage(success, message) {
+  return renderCodexResultPage(success, message);
+}
+
+/**
+ * Start xAI proxy on fixed port 56121.
+ * Mode A (server-side): if any session was registered, proxy auto-exchanges + saves DB.
+ * Mode B (channel fallback): if no session, proxy 302 redirects to app port.
+ */
+export function startXaiProxy(appPort) {
+  return new Promise((resolve) => {
+    if (xaiProxyServer) {
+      resolve({ success: true });
+      return;
+    }
+
+    const server = http.createServer(async (req, res) => {
+      const url = new URL(req.url, "http://localhost");
+      if (url.pathname !== "/callback" && url.pathname !== "/auth/callback") {
+        res.writeHead(404);
+        res.end("Not found");
+        return;
+      }
+
+      const code = url.searchParams.get("code");
+      const state = url.searchParams.get("state");
+      const errorParam = url.searchParams.get("error");
+      const session = state ? xaiPendingExchanges.get(state) : null;
+
+      // Mode A: server-side exchange
+      if (session) {
+        try {
+          if (errorParam) {
+            throw new Error(url.searchParams.get("error_description") || errorParam);
+          }
+          if (!code) throw new Error("No authorization code received");
+
+          const { exchangeTokens } = await import("../providers.js");
+          const { createProviderConnection } = await import("@/models");
+
+          const tokenData = await exchangeTokens(
+            "xai",
+            code,
+            session.redirectUri,
+            session.codeVerifier,
+            state
+          );
+          const connection = await createProviderConnection({
+            provider: "xai",
+            authType: "oauth",
+            ...tokenData,
+            expiresAt: tokenData.expiresIn
+              ? new Date(Date.now() + tokenData.expiresIn * 1000).toISOString()
+              : null,
+            testStatus: "active",
+          });
+
+          session.status = "done";
+          session.connectionId = connection.id;
+          session.email = connection.email;
+
+          res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+          res.end(renderXaiResultPage(true, "You can close this window."));
+        } catch (err) {
+          session.status = "error";
+          session.error = err.message;
+          res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+          res.end(renderXaiResultPage(false, err.message));
+        } finally {
+          stopXaiProxy();
+        }
+        return;
+      }
+
+      // Mode B: legacy fallback redirect
+      const redirectUrl = `http://localhost:${appPort}/callback${url.search}`;
+      res.writeHead(302, { Location: redirectUrl });
+      res.end();
+      stopXaiProxy();
+    });
+
+    server.listen(XAI_PROXY_PORT, "127.0.0.1", () => {
+      xaiProxyServer = server;
+      xaiProxyTimeout = setTimeout(() => stopXaiProxy(), XAI_PROXY_TIMEOUT_MS);
+      resolve({ success: true });
+    });
+
+    server.on("error", (err) => {
+      if (err.code === "EADDRINUSE") {
+        resolve({ success: false, reason: "port_busy" });
+      } else {
+        resolve({ success: false, reason: err.message });
+      }
+    });
+  });
+}
+
+export function stopXaiProxy() {
+  if (xaiProxyTimeout) {
+    clearTimeout(xaiProxyTimeout);
+    xaiProxyTimeout = null;
+  }
+  if (xaiProxyServer) {
+    xaiProxyServer.close();
+    xaiProxyServer = null;
+  }
+}
+
--- a/src/lib/providerNormalization.js
+++ b/src/lib/providerNormalization.js
@@ -1,5 +1,14 @@
 import { AI_PROVIDERS } from "../shared/constants/providers.js";

+/**
+ * Detect xAI Grok models by id pattern (grok-*, Grok_*, etc).
+ * @param {string} modelId
+ * @returns {boolean}
+ */
+export function isXaiModel(modelId) {
+  return typeof modelId === "string" && /^grok[-_]/i.test(modelId.trim());
+}
+
 export function normalizeProviderId(provider) {
  if (typeof provider !== "string") return provider;