@gajae-code/ai 0.2.4 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-06-03
+
+### Added
+
+- Added xAI to the `/login` provider catalog as a Grok OAuth login with PKCE, refresh-token storage, and mocked login/refresh coverage.
+
 ## [0.2.4] - 2026-06-02
 
 ### Added

package/README.md

@@ -1014,6 +1014,7 @@ Several providers support OAuth authentication (some also support static API key
 - **Google Gemini CLI** (Gemini 2.0/2.5 via Google Cloud Code Assist; free tier or paid subscription)
 - **Antigravity** (Free Gemini 3, Anthropic model, GPT-OSS via Google Cloud)
 - **Qwen Portal** (Qwen OAuth token or API key)
+- **xAI** (Grok OAuth login via xAI account)
 
 For paid Cloud Code Assist subscriptions, set `GOOGLE_CLOUD_PROJECT` or `GOOGLE_CLOUD_PROJECT_ID` to your project ID.
 
@@ -1063,12 +1064,13 @@ The quickest way to authenticate:
 bunx @gajae-code/ai login              # interactive provider selection
 bunx @gajae-code/ai login anthropic    # login to specific provider
 bunx @gajae-code/ai login vllm         # store vLLM API key (or placeholder for local no-auth)
+bunx @gajae-code/ai login xai          # sign in with xAI/Grok OAuth
 bunx @gajae-code/ai list               # list available providers
 ```
 
-Credentials are saved to `agent.db` in the agent directory. `/login qianfan` opens the Qianfan console and stores the pasted API key.
+Credentials are saved to `agent.db` in the agent directory. `/login qianfan` opens the Qianfan console and stores the pasted API key; `/login xai` opens xAI/Grok OAuth login and stores refreshable OAuth credentials.
 
-`login` supports OAuth providers (Anthropic, OpenAI code provider, GitHub Copilot, Gemini CLI, Antigravity) and API-key onboarding flows.
+`login` supports OAuth providers (Anthropic, OpenAI code provider, GitHub Copilot, Gemini CLI, Antigravity, xAI) and API-key onboarding flows.
 
 For the current API-key onboarding flows, the library covers Together, Moonshot, Qianfan, NVIDIA, NanoGPT, Hugging Face, Venice, Xiaomi, vLLM, LiteLLM, Cloudflare AI Gateway, Qwen Portal, and Ollama Cloud. Ollama remains the local runtime integration; set `OLLAMA_API_KEY` only when your local or self-hosted deployment enforces bearer auth.
 

package/dist/types/utils/oauth/callback-server.d.ts

@@ -7,6 +7,8 @@ export interface OAuthCallbackFlowOptions {
     preferredPort: number;
     callbackPath?: string;
     callbackHostname?: string;
+    /** Local listener hostname; defaults to callbackHostname when omitted. */
+    callbackBindHostname?: string;
     /** Exact redirect URI advertised to the provider; disables port fallback. */
     redirectUri?: string;
 }
@@ -19,6 +21,7 @@ export declare abstract class OAuthCallbackFlow {
     preferredPort: number;
     callbackPath: string;
     callbackHostname: string;
+    callbackBindHostname: string;
     redirectUri?: string;
     constructor(ctrl: OAuthController, preferredPortOrOptions: number | OAuthCallbackFlowOptions, callbackPath?: string);
     /**

package/dist/types/utils/oauth/types.d.ts

@@ -7,7 +7,7 @@ export type OAuthCredentials = {
     email?: string;
     accountId?: string;
 };
-export type OAuthProvider = "alibaba-coding-plan" | "anthropic" | "cerebras" | "cloudflare-ai-gateway" | "cursor" | "deepseek" | "fireworks" | "firepass" | "github-copilot" | "google-gemini-cli" | "google-antigravity" | "gitlab-duo" | "huggingface" | "kimi-code" | "kilo" | "kagi" | "litellm" | "lm-studio" | "minimax-code" | "minimax-code-cn" | "moonshot" | "nvidia" | "nanogpt" | "ollama" | "ollama-cloud" | "openai-codex" | "openai-codex-device" | "opencode-go" | "opencode-zen" | "parallel" | "perplexity" | "qianfan" | "qwen-portal" | "synthetic" | "tavily" | "together" | "venice" | "vercel-ai-gateway" | "vllm" | "xiaomi" | "zenmux" | "zai";
+export type OAuthProvider = "alibaba-coding-plan" | "anthropic" | "cerebras" | "cloudflare-ai-gateway" | "cursor" | "deepseek" | "fireworks" | "firepass" | "github-copilot" | "google-gemini-cli" | "google-antigravity" | "gitlab-duo" | "huggingface" | "kimi-code" | "kilo" | "kagi" | "litellm" | "lm-studio" | "minimax-code" | "minimax-code-cn" | "moonshot" | "nvidia" | "nanogpt" | "ollama" | "ollama-cloud" | "openai-codex" | "openai-codex-device" | "opencode-go" | "opencode-zen" | "parallel" | "perplexity" | "qianfan" | "qwen-portal" | "synthetic" | "tavily" | "together" | "venice" | "vercel-ai-gateway" | "vllm" | "xai" | "xiaomi" | "zenmux" | "zai";
 export type OAuthProviderId = OAuthProvider | (string & {});
 export type OAuthPrompt = {
     message: string;

package/dist/types/utils/oauth/xai.d.ts

@@ -0,0 +1,23 @@
+/** xAI OAuth flow (Grok account login). */
+import { OAuthCallbackFlow } from "./callback-server";
+import type { OAuthController, OAuthCredentials } from "./types";
+export declare const XAI_OAUTH_DISCOVERY_URL = "https://auth.x.ai/.well-known/openid-configuration";
+export declare const XAI_OAUTH_CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828";
+export declare const XAI_OAUTH_SCOPE = "openid profile email offline_access grok-cli:access api:access";
+interface XaiDiscovery {
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+}
+export declare function discoverXaiOAuthEndpoints(signal?: AbortSignal): Promise<XaiDiscovery>;
+export declare class XaiOAuthFlow extends OAuthCallbackFlow {
+    #private;
+    constructor(ctrl: OAuthController);
+    generateAuthUrl(state: string, redirectUri: string): Promise<{
+        url: string;
+        instructions?: string;
+    }>;
+    exchangeToken(code: string, _state: string, redirectUri: string): Promise<OAuthCredentials>;
+}
+export declare function loginXai(ctrl: OAuthController): Promise<OAuthCredentials>;
+export declare function refreshXaiToken(refreshToken: string, signal?: AbortSignal): Promise<OAuthCredentials>;
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/ai",
-	"version": "0.2.4",
+	"version": "0.3.0",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://gaebal-gajae.dev",
 	"author": "Yeachan-Heo",
@@ -43,7 +43,7 @@
 	"dependencies": {
 		"@anthropic-ai/sdk": "^0.94.0",
 		"@bufbuild/protobuf": "^2.12.0",
-		"@gajae-code/utils": "0.2.4",
+		"@gajae-code/utils": "0.3.0",
 		"openai": "^6.36.0",
 		"partial-json": "^0.1.7",
 		"zod": "4.4.3"

package/src/auth-broker/remote-store.ts

@@ -281,7 +281,7 @@ export class RemoteAuthCredentialStore implements AuthCredentialStore {
 
 	async prepareForRequest(credentialId: number, opts: { signal?: AbortSignal } = {}): Promise<boolean> {
 		const entry = this.#snapshot.credentials.find(candidate => candidate.id === credentialId);
-		if (!entry || entry.credential.type !== "oauth" || entry.rotatesInMs === null) return false;
+		if (entry?.credential.type !== "oauth" || entry.rotatesInMs === null) return false;
 		const remainingMs = this.#snapshotReceivedAt + entry.rotatesInMs - Date.now();
 		if (remainingMs > WAIT_THRESHOLD_MS) return false;
 		return this.waitForFreshSnapshot(MAX_WAIT_MS, opts);

package/src/auth-storage.ts

@@ -1484,6 +1484,14 @@ export class AuthStorage {
 				await saveApiKeyCredential(apiKey);
 				return;
 			}
+			case "xai": {
+				const { loginXai } = await import("./utils/oauth/xai");
+				credentials = await loginXai({
+					...ctrl,
+					onManualCodeInput: ctrl.onManualCodeInput ?? manualCodeInput,
+				});
+				break;
+			}
 			case "fireworks": {
 				const { loginFireworks } = await import("./utils/oauth/fireworks");
 				const apiKey = await loginFireworks(ctrl);
@@ -1637,6 +1645,13 @@ export class AuthStorage {
 			}
 		}
 		const newCredential: OAuthCredential = { type: "oauth", ...credentials };
+		if (provider === "xai") {
+			const existingOAuthCredentials = this.#getCredentialsForProvider(provider).filter(
+				(credential): credential is OAuthCredential => credential.type === "oauth",
+			);
+			await this.set(provider, [...existingOAuthCredentials, newCredential]);
+			return;
+		}
 		await this.#upsertOAuthCredential(provider, newCredential);
 	}
 
@@ -2733,7 +2748,7 @@ export class AuthStorage {
 		if (!prepare) return true;
 		const stored = this.#getStoredCredentials(provider);
 		const selected = stored[selection.index];
-		if (!selected || selected.credential.type !== "oauth") return false;
+		if (selected?.credential.type !== "oauth") return false;
 
 		const prepared = await prepare(selected.id, { signal: options?.signal });
 		if (!prepared) return true;
@@ -2745,7 +2760,7 @@ export class AuthStorage {
 		const latestIndex = latestRows.findIndex(row => row.id === selected.id);
 		if (latestIndex === -1) return false;
 		const latest = latestRows[latestIndex];
-		if (!latest || latest.credential.type !== "oauth") return false;
+		if (latest?.credential.type !== "oauth") return false;
 		selection.index = latestIndex;
 		selection.credential = latest.credential;
 		return true;

package/src/cli.ts

@@ -110,6 +110,7 @@ Providers:
   tavily            Tavily
   zai               Z.AI (GLM Coding Plan)
   deepseek          DeepSeek
+  xai               xAI
   nanogpt           NanoGPT
   minimax-code      MiniMax Coding Plan (International)
   minimax-code-cn   MiniMax Coding Plan (China)

package/src/providers/anthropic.ts

@@ -1684,7 +1684,7 @@ function disableThinkingIfToolChoiceForced(params: MessageCreateParamsStreaming)
 
 function ensureMaxTokensForThinking(params: MessageCreateParamsStreaming, model: Model<"anthropic-messages">): void {
 	const thinking = params.thinking;
-	if (!thinking || thinking.type !== "enabled") return;
+	if (thinking?.type !== "enabled") return;
 
 	const budgetTokens = thinking.budget_tokens ?? 0;
 	if (budgetTokens <= 0) return;

package/src/providers/openai-completions.ts

@@ -554,7 +554,7 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 				eventStream: AssistantMessageEventStream,
 				text: string,
 			): void => {
-				if (!currentBlock || currentBlock.type !== "text") {
+				if (currentBlock?.type !== "text") {
 					finishCurrentBlock(currentBlock);
 					currentBlock = { type: "text", text: "" };
 					message.content.push(currentBlock);
@@ -575,8 +575,7 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 				signature?: string,
 			): void => {
 				if (
-					!currentBlock ||
-					currentBlock.type !== "thinking" ||
+					currentBlock?.type !== "thinking" ||
 					(signature !== undefined && currentBlock.thinkingSignature !== signature)
 				) {
 					finishCurrentBlock(currentBlock);
@@ -786,11 +785,7 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 
 					if (choice?.delta?.tool_calls && choice.delta.tool_calls.length > 0) {
 						for (const toolCall of choice.delta.tool_calls) {
-							if (
-								!currentBlock ||
-								currentBlock.type !== "toolCall" ||
-								(toolCall.id && currentBlock.id !== toolCall.id)
-							) {
+							if (currentBlock?.type !== "toolCall" || (toolCall.id && currentBlock.id !== toolCall.id)) {
 								finishCurrentBlock(currentBlock);
 								currentBlock = {
 									type: "toolCall",

package/src/providers/openai-responses-server.ts

@@ -954,7 +954,7 @@ export function encodeStream(
 							break;
 						}
 						case "text_delta": {
-							if (!state.open || state.open.kind !== "message") break;
+							if (state.open?.kind !== "message") break;
 							const cur: OpenMessage = state.open;
 							cur.currentPartText += ev.delta;
 							emit("response.output_text.delta", {
@@ -970,7 +970,7 @@ export function encodeStream(
 							break;
 						}
 						case "text_end": {
-							if (!state.open || state.open.kind !== "message") break;
+							if (state.open?.kind !== "message") break;
 							const cur: OpenMessage = state.open;
 							const text = ev.content ?? cur.currentPartText;
 							emit("response.output_text.done", {
@@ -997,7 +997,7 @@ export function encodeStream(
 							break;
 						}
 						case "thinking_delta": {
-							if (!state.open || state.open.kind !== "reasoning") break;
+							if (state.open?.kind !== "reasoning") break;
 							const cur: OpenReasoning = state.open;
 							cur.reasoningText += ev.delta;
 							emit("response.reasoning_summary_text.delta", {
@@ -1009,7 +1009,7 @@ export function encodeStream(
 							break;
 						}
 						case "thinking_end": {
-							if (!state.open || state.open.kind !== "reasoning") break;
+							if (state.open?.kind !== "reasoning") break;
 							const cur: OpenReasoning = state.open;
 							const text = ev.content ?? cur.reasoningText;
 							cur.reasoningText = text;
@@ -1034,7 +1034,7 @@ export function encodeStream(
 							break;
 						}
 						case "toolcall_delta": {
-							if (!state.open || state.open.kind !== "function_call") break;
+							if (state.open?.kind !== "function_call") break;
 							const cur: OpenFunctionCall = state.open;
 							cur.argsText += ev.delta;
 							if (cur.customWireName) {
@@ -1053,7 +1053,7 @@ export function encodeStream(
 							break;
 						}
 						case "toolcall_end": {
-							if (!state.open || state.open.kind !== "function_call") break;
+							if (state.open?.kind !== "function_call") break;
 							const cur: OpenFunctionCall = state.open;
 							// Promote possibly-late info from the canonical ToolCall.
 							const tc = ev.toolCall;

package/src/utils/oauth/callback-server.ts

@@ -23,6 +23,8 @@ export interface OAuthCallbackFlowOptions {
 	preferredPort: number;
 	callbackPath?: string;
 	callbackHostname?: string;
+	/** Local listener hostname; defaults to callbackHostname when omitted. */
+	callbackBindHostname?: string;
 	/** Exact redirect URI advertised to the provider; disables port fallback. */
 	redirectUri?: string;
 }
@@ -35,6 +37,7 @@ export abstract class OAuthCallbackFlow {
 	preferredPort: number;
 	callbackPath: string;
 	callbackHostname: string;
+	callbackBindHostname: string;
 	redirectUri?: string;
 	#callbackResolve?: (result: CallbackResult) => void;
 	#callbackReject?: (error: string) => void;
@@ -49,12 +52,14 @@ export abstract class OAuthCallbackFlow {
 			this.preferredPort = preferredPortOrOptions;
 			this.callbackPath = callbackPath;
 			this.callbackHostname = DEFAULT_HOSTNAME;
+			this.callbackBindHostname = DEFAULT_HOSTNAME;
 			return;
 		}
 
 		this.preferredPort = preferredPortOrOptions.preferredPort;
 		this.callbackPath = preferredPortOrOptions.callbackPath ?? CALLBACK_PATH;
 		this.callbackHostname = preferredPortOrOptions.callbackHostname ?? DEFAULT_HOSTNAME;
+		this.callbackBindHostname = preferredPortOrOptions.callbackBindHostname ?? this.callbackHostname;
 		this.redirectUri = preferredPortOrOptions.redirectUri;
 	}
 
@@ -144,7 +149,7 @@ export abstract class OAuthCallbackFlow {
 	 */
 	#createServer(port: number, expectedState: string): Bun.Server<unknown> {
 		return Bun.serve({
-			hostname: this.callbackHostname,
+			hostname: this.callbackBindHostname,
 			port,
 			reusePort: false,
 			fetch: req => this.#handleCallback(req, expectedState),

package/src/utils/oauth/index.ts

@@ -60,6 +60,11 @@ const builtInOAuthProviders: OAuthProviderInfo[] = [
 		name: "DeepSeek",
 		available: true,
 	},
+	{
+		id: "xai",
+		name: "xAI",
+		available: true,
+	},
 	{
 		id: "fireworks",
 		name: "Fireworks",
@@ -310,6 +315,11 @@ export async function refreshOAuthToken(
 			newCredentials = await refreshCursorToken(credentials.refresh);
 			break;
 		}
+		case "xai": {
+			const { refreshXaiToken } = await import("./xai");
+			newCredentials = await refreshXaiToken(credentials.refresh);
+			break;
+		}
 		case "kilo":
 		case "perplexity":
 		case "huggingface":

package/src/utils/oauth/types.ts

@@ -48,6 +48,7 @@ export type OAuthProvider =
 	| "venice"
 	| "vercel-ai-gateway"
 	| "vllm"
+	| "xai"
 	| "xiaomi"
 	| "zenmux"
 	| "zai";

package/src/utils/oauth/xai.ts

@@ -0,0 +1,210 @@
+/** xAI OAuth flow (Grok account login). */
+import { OAuthCallbackFlow, type OAuthCallbackFlowOptions } from "./callback-server";
+import { generatePKCE } from "./pkce";
+import type { 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): Promise<OAuthCredentials> {
+	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);
+}