open-grok-build 0.1.0

package/src/auth/oauth.ts

@@ -0,0 +1,529 @@
+/**
+ * xAI Grok OAuth 2.0 + PKCE implementation.
+ *
+ * Uses Web Crypto API (crypto.subtle) for PKCE so the extension is
+ * portable across Node versions and potential non-Node runtimes.
+ *
+ * xAI issuer (auth.x.ai) with Grok Build client_id; API traffic uses
+ * cli-chat-proxy.grok.com instead of api.x.ai.
+ */
+
+import { createServer } from 'node:http';
+import { XaiErrorCode, XaiOAuthError } from '../shared/errors.js';
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const DEFAULT_BASE_URL = 'https://cli-chat-proxy.grok.com/v1';
+const ISSUER = 'https://auth.x.ai';
+const DISCOVERY_URL = `${ISSUER}/.well-known/openid-configuration`;
+const CLIENT_ID = process.env.GROK_BUILD_OAUTH_CLIENT_ID || 'b1a00492-073a-47ea-816f-4c329264a828';
+const SCOPE =
+  process.env.GROK_BUILD_OAUTH_SCOPE ||
+  'openid profile email offline_access grok-cli:access api:access';
+const CALLBACK_HOST = process.env.GROK_BUILD_CALLBACK_HOST || '127.0.0.1';
+const CALLBACK_PORT = Number.parseInt(process.env.GROK_BUILD_CALLBACK_PORT || '56122', 10);
+const CALLBACK_PATH = '/callback';
+/** Refresh 120s before actual expiry. */
+const REFRESH_SKEW_MS = 120_000;
+const TOKEN_REQUEST_TIMEOUT_MS = Number.parseInt(
+  process.env.GROK_BUILD_TOKEN_TIMEOUT_MS || '30000',
+  10,
+);
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+interface XaiDiscovery {
+  authorization_endpoint: string;
+  token_endpoint: string;
+}
+
+export interface XaiOAuthCredentials {
+  [key: string]: unknown;
+  refresh: string;
+  access: string;
+  expires: number;
+  tokenEndpoint?: string;
+  discovery?: XaiDiscovery;
+  idToken?: string;
+  tokenType?: string;
+  baseUrl?: string;
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+export function getBaseUrl(): string {
+  return (process.env.GROK_BUILD_BASE_URL || DEFAULT_BASE_URL).replace(/\/+$/, '');
+}
+
+function base64Url(buffer: ArrayBuffer | Uint8Array): string {
+  const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
+  let binary = '';
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+// ─── PKCE ─────────────────────────────────────────────────────────────────────
+
+async function generatePKCE(): Promise<{
+  verifier: string;
+  challenge: string;
+}> {
+  const verifier = base64Url(crypto.getRandomValues(new Uint8Array(32)));
+  const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
+  return { verifier, challenge: base64Url(hash) };
+}
+
+// ─── Endpoint validation ──────────────────────────────────────────────────────
+
+function validateEndpoint(value: string, field: string): string {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new XaiOAuthError(
+      `xAI OAuth discovery returned invalid ${field}: ${value}`,
+      XaiErrorCode.DISCOVERY_INVALID_ORIGIN,
+    );
+  }
+  if (url.protocol !== 'https:') {
+    throw new XaiOAuthError(
+      `xAI OAuth ${field} must use HTTPS: ${value}`,
+      XaiErrorCode.DISCOVERY_INVALID_ORIGIN,
+    );
+  }
+  const host = url.hostname.toLowerCase();
+  if (
+    host !== 'x.ai' &&
+    host !== 'auth.x.ai' &&
+    host !== 'accounts.x.ai' &&
+    !host.endsWith('.x.ai')
+  ) {
+    throw new XaiOAuthError(
+      `Refusing non-xAI OAuth ${field}: ${value}`,
+      XaiErrorCode.DISCOVERY_INVALID_ORIGIN,
+    );
+  }
+  return url.toString();
+}
+
+// ─── OIDC Discovery ──────────────────────────────────────────────────────────
+
+async function discover(): Promise<XaiDiscovery> {
+  let response: Response;
+  try {
+    response = await fetch(DISCOVERY_URL, {
+      headers: { Accept: 'application/json' },
+      signal: AbortSignal.timeout(15_000),
+    });
+  } catch (cause) {
+    throw new XaiOAuthError(
+      `xAI OIDC discovery failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+      XaiErrorCode.DISCOVERY_FAILED,
+    );
+  }
+  if (!response.ok) {
+    throw new XaiOAuthError(
+      `xAI OIDC discovery returned ${response.status}`,
+      XaiErrorCode.DISCOVERY_FAILED,
+    );
+  }
+  let payload: Record<string, unknown>;
+  try {
+    payload = (await response.json()) as Record<string, unknown>;
+  } catch (cause) {
+    throw new XaiOAuthError(
+      `xAI OIDC discovery returned invalid JSON: ${cause instanceof Error ? cause.message : String(cause)}`,
+      XaiErrorCode.DISCOVERY_FAILED,
+    );
+  }
+  const authorizationEndpoint = validateEndpoint(
+    String(payload.authorization_endpoint ?? ''),
+    'authorization_endpoint',
+  );
+  const tokenEndpoint = validateEndpoint(String(payload.token_endpoint ?? ''), 'token_endpoint');
+  return {
+    authorization_endpoint: authorizationEndpoint,
+    token_endpoint: tokenEndpoint,
+  };
+}
+
+// ─── Loopback callback server ────────────────────────────────────────────────
+
+interface CallbackResult {
+  code?: string;
+  state?: string;
+  error?: string;
+  errorDescription?: string;
+}
+
+function startCallbackServer(): Promise<{
+  server: import('node:http').Server;
+  redirectUri: string;
+  waitForCallback: (timeoutMs: number) => Promise<CallbackResult>;
+}> {
+  let settle: ((value: CallbackResult) => void) | undefined;
+  const callbackPromise = new Promise<CallbackResult>((resolve) => {
+    settle = resolve;
+  });
+
+  const server = createServer((req, res) => {
+    try {
+      const origin = req.headers.origin;
+      if (origin === 'https://accounts.x.ai' || origin === 'https://auth.x.ai') {
+        res.setHeader('Access-Control-Allow-Origin', origin);
+        res.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+        res.setHeader('Access-Control-Allow-Private-Network', 'true');
+        res.setHeader('Vary', 'Origin');
+      }
+      if (req.method === 'OPTIONS') {
+        res.statusCode = 204;
+        res.end();
+        return;
+      }
+
+      const url = new URL(req.url ?? '/', `http://${CALLBACK_HOST}`);
+      if (url.pathname !== CALLBACK_PATH) {
+        res.statusCode = 404;
+        res.end('Not found');
+        return;
+      }
+
+      const result: CallbackResult = {
+        code: url.searchParams.get('code') ?? undefined,
+        state: url.searchParams.get('state') ?? undefined,
+        error: url.searchParams.get('error') ?? undefined,
+        errorDescription: url.searchParams.get('error_description') ?? undefined,
+      };
+
+      res.statusCode = result.error ? 400 : 200;
+      res.setHeader('Content-Type', 'text/html; charset=utf-8');
+      const html = result.error
+        ? '<html><body><h1>xAI authorization failed.</h1>You can close this tab.</body></html>'
+        : '<html><body><h1>xAI authorization received.</h1>You can close this tab.</body></html>';
+      res.end(html);
+      settle?.(result);
+    } catch {
+      res.statusCode = 500;
+      res.end('Internal error');
+    }
+  });
+
+  const listen = (port: number) =>
+    new Promise<number>((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(port, CALLBACK_HOST, () => {
+        server.removeListener('error', reject);
+        const addr = server.address();
+        resolve(typeof addr === 'object' && addr ? addr.port : port);
+      });
+    });
+
+  return (async () => {
+    let actualPort: number;
+    try {
+      actualPort = await listen(CALLBACK_PORT);
+    } catch (firstError) {
+      try {
+        actualPort = await listen(0);
+      } catch (secondError) {
+        const errorDescription = `Could not bind xAI OAuth callback server on ${CALLBACK_HOST}:${CALLBACK_PORT} or an ephemeral port: ${secondError instanceof Error ? secondError.message : String(secondError)} (initial error: ${firstError instanceof Error ? firstError.message : String(firstError)})`;
+        return {
+          server,
+          redirectUri: `http://${CALLBACK_HOST}:${CALLBACK_PORT}${CALLBACK_PATH}`,
+          waitForCallback: async () => ({
+            error: XaiErrorCode.CALLBACK_BIND_FAILED,
+            errorDescription,
+          }),
+        };
+      }
+    }
+    const redirectUri = `http://${CALLBACK_HOST}:${actualPort}${CALLBACK_PATH}`;
+    return {
+      server,
+      redirectUri,
+      waitForCallback: (timeoutMs: number) =>
+        Promise.race([
+          callbackPromise,
+          new Promise<CallbackResult>((resolve) =>
+            setTimeout(
+              () =>
+                resolve({
+                  error: XaiErrorCode.CALLBACK_TIMEOUT,
+                  errorDescription: 'Timed out waiting for xAI OAuth callback.',
+                }),
+              timeoutMs,
+            ),
+          ),
+        ]),
+    };
+  })();
+}
+
+// ─── Token exchange ───────────────────────────────────────────────────────────
+
+async function fetchTokenResponse(
+  tokenEndpoint: string,
+  body: URLSearchParams,
+  errorCode: string,
+  label: string,
+): Promise<Response> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), TOKEN_REQUEST_TIMEOUT_MS);
+  try {
+    return await fetch(tokenEndpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Accept: 'application/json',
+      },
+      body,
+      signal: controller.signal,
+    });
+  } catch (cause) {
+    throw new XaiOAuthError(
+      `xAI ${label} failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+      errorCode,
+    );
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function tokenResponseText(response: Response) {
+  try {
+    return await response.text();
+  } catch (cause) {
+    return `unable to read response body: ${cause instanceof Error ? cause.message : String(cause)}`;
+  }
+}
+
+async function tokenResponseJson(
+  response: Response,
+  errorCode: string,
+  label: string,
+): Promise<Record<string, unknown>> {
+  try {
+    return (await response.json()) as Record<string, unknown>;
+  } catch (cause) {
+    throw new XaiOAuthError(
+      `xAI ${label} returned invalid JSON: ${cause instanceof Error ? cause.message : String(cause)}`,
+      errorCode,
+    );
+  }
+}
+
+async function exchangeCode(
+  tokenEndpoint: string,
+  code: string,
+  redirectUri: string,
+  verifier: string,
+): Promise<XaiOAuthCredentials> {
+  const response = await fetchTokenResponse(
+    tokenEndpoint,
+    new URLSearchParams({
+      grant_type: 'authorization_code',
+      client_id: CLIENT_ID,
+      code,
+      redirect_uri: redirectUri,
+      code_verifier: verifier,
+    }),
+    XaiErrorCode.TOKEN_EXCHANGE_FAILED,
+    'token exchange',
+  );
+  if (!response.ok) {
+    throw new XaiOAuthError(
+      `xAI token exchange failed: ${response.status} ${await tokenResponseText(response)}`,
+      XaiErrorCode.TOKEN_EXCHANGE_FAILED,
+    );
+  }
+  const payload = await tokenResponseJson(
+    response,
+    XaiErrorCode.TOKEN_EXCHANGE_FAILED,
+    'token exchange',
+  );
+  const access = String(payload.access_token ?? '');
+  const refresh = String(payload.refresh_token ?? '');
+  if (!access) {
+    throw new XaiOAuthError(
+      'xAI token exchange did not return access_token.',
+      XaiErrorCode.TOKEN_EXCHANGE_INVALID,
+    );
+  }
+  if (!refresh) {
+    throw new XaiOAuthError(
+      'xAI token exchange did not return refresh_token.',
+      XaiErrorCode.TOKEN_EXCHANGE_INVALID,
+    );
+  }
+  const expiresIn =
+    typeof payload.expires_in === 'number'
+      ? payload.expires_in
+      : Number(payload.expires_in ?? 3600);
+  return {
+    access,
+    refresh,
+    expires: Date.now() + expiresIn * 1000 - REFRESH_SKEW_MS,
+    tokenEndpoint,
+    discovery: { authorization_endpoint: '', token_endpoint: tokenEndpoint },
+    idToken: String(payload.id_token ?? ''),
+    tokenType: String(payload.token_type ?? 'Bearer'),
+    baseUrl: getBaseUrl(),
+  };
+}
+
+export type OAuthCredentials = {
+  access: string;
+  refresh: string;
+  expires: number;
+  [key: string]: unknown;
+};
+
+export type OAuthLoginCallbacks = {
+  onAuth: (payload: { url: string; instructions: string }) => void;
+  onError?: (error: unknown) => void;
+  onSuccess?: () => void;
+};
+
+export type GrokBuildOAuthSession = {
+  url: string;
+  instructions: string;
+  finish: () => Promise<OAuthCredentials>;
+};
+
+/** Start loopback OAuth; call `finish` after the user completes the browser step. */
+export async function beginGrokBuildOAuth(
+  referrer = 'open-grok-build',
+): Promise<GrokBuildOAuthSession> {
+  const discovery = await discover();
+  const { verifier, challenge } = await generatePKCE();
+  const state = base64Url(crypto.getRandomValues(new Uint8Array(16)));
+  const nonce = base64Url(crypto.getRandomValues(new Uint8Array(16)));
+  const callback = await startCallbackServer();
+
+  const authUrl = new URL(discovery.authorization_endpoint);
+  authUrl.searchParams.set('response_type', 'code');
+  authUrl.searchParams.set('client_id', CLIENT_ID);
+  authUrl.searchParams.set('redirect_uri', callback.redirectUri);
+  authUrl.searchParams.set('scope', SCOPE);
+  authUrl.searchParams.set('code_challenge', challenge);
+  authUrl.searchParams.set('code_challenge_method', 'S256');
+  authUrl.searchParams.set('state', state);
+  authUrl.searchParams.set('nonce', nonce);
+  authUrl.searchParams.set('plan', 'generic');
+  authUrl.searchParams.set('referrer', referrer);
+
+  return {
+    url: authUrl.toString(),
+    instructions: `Authorize xAI for Grok Build, then return to OpenCode. Callback: ${callback.redirectUri}`,
+    finish: async () => {
+      try {
+        const result = await callback.waitForCallback(180_000);
+
+        if (result.error) {
+          const code =
+            result.error === XaiErrorCode.CALLBACK_BIND_FAILED ||
+            result.error === XaiErrorCode.CALLBACK_TIMEOUT
+              ? result.error
+              : XaiErrorCode.AUTHORIZATION_FAILED;
+          throw new XaiOAuthError(result.errorDescription ?? result.error, code);
+        }
+        if (result.state !== state) {
+          throw new XaiOAuthError(
+            'xAI OAuth state mismatch — possible CSRF.',
+            XaiErrorCode.STATE_MISMATCH,
+          );
+        }
+        if (!result.code) {
+          throw new XaiOAuthError(
+            'xAI OAuth callback did not include an authorization code.',
+            XaiErrorCode.CODE_MISSING,
+          );
+        }
+
+        const credentials = await exchangeCode(
+          discovery.token_endpoint,
+          result.code,
+          callback.redirectUri,
+          verifier,
+        );
+        credentials.discovery = discovery;
+        return credentials;
+      } finally {
+        callback.server.close();
+      }
+    },
+  };
+}
+
+// ─── Programmatic login (browser OAuth) ─────────────────────────────────────
+
+export async function login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials> {
+  const session = await beginGrokBuildOAuth('open-grok-build');
+  callbacks.onAuth({ url: session.url, instructions: session.instructions });
+  return session.finish();
+}
+
+// ─── Token refresh ────────────────────────────────────────────────────────────
+
+export async function refresh(credentials: OAuthCredentials): Promise<OAuthCredentials> {
+  const xai = credentials as XaiOAuthCredentials;
+  const tokenEndpoint =
+    xai.tokenEndpoint || xai.discovery?.token_endpoint || (await discover()).token_endpoint;
+  validateEndpoint(tokenEndpoint, 'token_endpoint');
+
+  if (!credentials.refresh) {
+    throw new XaiOAuthError(
+      'Missing refresh_token. Re-login required.',
+      XaiErrorCode.REFRESH_MISSING,
+      true,
+    );
+  }
+
+  const response = await fetchTokenResponse(
+    tokenEndpoint,
+    new URLSearchParams({
+      grant_type: 'refresh_token',
+      client_id: CLIENT_ID,
+      refresh_token: credentials.refresh,
+    }),
+    XaiErrorCode.REFRESH_FAILED,
+    'token refresh',
+  );
+
+  if (!response.ok) {
+    const isFatal = response.status === 400 || response.status === 401 || response.status === 403;
+    throw new XaiOAuthError(
+      `xAI token refresh failed: ${response.status} ${await tokenResponseText(response)}`,
+      XaiErrorCode.REFRESH_FAILED,
+      isFatal,
+    );
+  }
+
+  const payload = await tokenResponseJson(response, XaiErrorCode.REFRESH_FAILED, 'token refresh');
+  const access = String(payload.access_token ?? '');
+  if (!access) {
+    throw new XaiOAuthError(
+      'xAI token refresh did not return access_token.',
+      XaiErrorCode.REFRESH_FAILED,
+      true,
+    );
+  }
+
+  const refresh_new = String(payload.refresh_token ?? credentials.refresh);
+  const expiresIn =
+    typeof payload.expires_in === 'number'
+      ? payload.expires_in
+      : Number(payload.expires_in ?? 3600);
+
+  return {
+    ...xai,
+    access,
+    refresh: refresh_new,
+    expires: Date.now() + expiresIn * 1000 - REFRESH_SKEW_MS,
+    tokenEndpoint,
+    idToken: String(payload.id_token ?? xai.idToken ?? ''),
+    tokenType: String(payload.token_type ?? xai.tokenType ?? 'Bearer'),
+    baseUrl: getBaseUrl(),
+  };
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+/**
+ * open-grok-build — Grok Build OpenCode plugin.
+ */
+
+export { OpenGrokBuildPlugin, OpenGrokBuildPlugin as default } from './opencode/plugin.js';

package/src/models/catalog.ts

@@ -0,0 +1,149 @@
+/**
+ * Model definitions for Grok Build's API.
+ */
+
+// ─── Cost constants ($/M tokens) ──────────────────────────────────────────────
+
+const COST_BUILD = { input: 1, output: 2, cacheRead: 0.2, cacheWrite: 0.2 };
+const COST_COMPOSER_FAST = { input: 3, output: 15, cacheRead: 0.5, cacheWrite: 0 };
+const COST_43 = { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 };
+const COST_420 = { input: 2, output: 6, cacheRead: 0.2, cacheWrite: 0 };
+
+// ─── Model type ───────────────────────────────────────────────────────────────
+
+export interface GrokBuildModelConfig {
+  id: string;
+  name: string;
+  reasoning: boolean;
+  input: ('text' | 'image')[];
+  cost: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+  };
+  contextWindow: number;
+  maxTokens: number;
+  /** Models that don't support reasoning.effort get a thinkingLevelMap. */
+  thinkingLevelMap?: Record<string, string | null>;
+}
+
+// ─── Hardcoded fallback catalog ───────────────────────────────────────────────
+//
+// These are the models observed via the Grok Build /v1/models endpoint and
+// the actual traffic captured through cli-chat-proxy.grok.com.
+
+const FALLBACK_MODELS: GrokBuildModelConfig[] = [
+  {
+    id: 'grok-composer-2.5-fast',
+    name: 'Composer 2.5 Fast (Grok Build)',
+    reasoning: false,
+    input: ['text', 'image'],
+    cost: COST_COMPOSER_FAST,
+    contextWindow: 200_000,
+    maxTokens: 30_000,
+    thinkingLevelMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: null,
+      xhigh: null,
+    },
+  },
+  {
+    id: 'grok-build',
+    name: 'Grok Build',
+    reasoning: true,
+    input: ['text', 'image'],
+    cost: COST_BUILD,
+    contextWindow: 512_000,
+    maxTokens: 30_000,
+  },
+  {
+    id: 'grok-4.3',
+    name: 'Grok 4.3',
+    reasoning: true,
+    input: ['text', 'image'],
+    cost: COST_43,
+    contextWindow: 1_000_000,
+    maxTokens: 30_000,
+  },
+  {
+    id: 'grok-4.20-0309-reasoning',
+    name: 'Grok 4.20 Reasoning',
+    reasoning: true,
+    input: ['text', 'image'],
+    cost: COST_420,
+    contextWindow: 2_000_000,
+    maxTokens: 30_000,
+  },
+  {
+    id: 'grok-4.20-0309-non-reasoning',
+    name: 'Grok 4.20 Non-Reasoning',
+    reasoning: false,
+    input: ['text', 'image'],
+    cost: COST_420,
+    contextWindow: 2_000_000,
+    maxTokens: 30_000,
+    thinkingLevelMap: {
+      off: 'none',
+      minimal: null,
+      low: null,
+      medium: null,
+      high: null,
+      xhigh: null,
+    },
+  },
+  {
+    id: 'grok-4.20-multi-agent-0309',
+    name: 'Grok 4.20 Multi-Agent',
+    reasoning: true,
+    input: ['text', 'image'],
+    cost: COST_420,
+    contextWindow: 2_000_000,
+    maxTokens: 30_000,
+  },
+];
+
+const EFFORT_CAPABLE_PREFIXES = ['grok-3-mini', 'grok-4.20-multi-agent', 'grok-4.3'];
+
+export function supportsReasoningEffort(modelId: string): boolean {
+  const parts = modelId.split('/');
+  const name = parts.at(-1) ?? modelId;
+  const model = resolveModels().find((entry) => entry.id.toLowerCase() === name.toLowerCase());
+  if (!EFFORT_CAPABLE_PREFIXES.some((prefix) => name.toLowerCase().startsWith(prefix))) {
+    return false;
+  }
+  if (!model?.reasoning) return false;
+  if (!model.thinkingLevelMap) return true;
+  return Object.values(model.thinkingLevelMap).some((level) => level !== null && level !== 'none');
+}
+
+// ─── GROK_BUILD_MODELS env override ───────────────────────────────────────────
+
+/**
+ * Resolve the active model list.  If `GROK_BUILD_MODELS` is set,
+ * it filters/reorders the fallback list; unknown IDs get sensible defaults.
+ */
+export function resolveModels(): GrokBuildModelConfig[] {
+  const env = (process.env.GROK_BUILD_MODELS || '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+  if (env.length === 0) return FALLBACK_MODELS;
+
+  const byId = new Map(FALLBACK_MODELS.map((m) => [m.id, m]));
+  return env.map(
+    (id) =>
+      byId.get(id) ?? {
+        id,
+        name: id,
+        reasoning: true,
+        input: ['text'] as ('text' | 'image')[],
+        cost: COST_BUILD,
+        contextWindow: 1_000_000,
+        maxTokens: 30_000,
+      },
+  );
+}