@linxiraos/pi-ai 1.0.0

package/src/registry/oauth/google-gemini-cli.ts

@@ -0,0 +1,297 @@
+/**
+ * Gemini CLI OAuth flow (Google Cloud Code Assist)
+ * Standard Gemini models only (gemini-2.0-flash, gemini-2.5-*)
+ */
+
+import { getGeminiCliHeaders } from "@linxiraos/pi-catalog/wire/gemini-headers";
+import { $env } from "@linxiraos/pi-utils";
+import * as AIError from "../../error";
+import { oauthFetch, runGoogleOAuthLogin, throwIfLoginCancelled } from "./google-oauth-shared";
+import type { OAuthController, OAuthCredentials } from "./types";
+
+const decode = (s: string) => atob(s);
+const CLIENT_ID = decode(
+	"NjgxMjU1ODA5Mzk1LW9vOGZ0Mm9wcmRybnA5ZTNhcWY2YXYzaG1kaWIxMzVqLmFwcHMuZ29vZ2xldXNlcmNvbnRlbnQuY29t",
+);
+const CLIENT_SECRET = decode("R09DU1BYLTR1SGdNUG0tMW83U2stZ2VWNkN1NWNsWEZzeGw=");
+const CALLBACK_PORT = 8085;
+const CALLBACK_PATH = "/oauth2callback";
+const SCOPES = [
+	"https://www.googleapis.com/auth/cloud-platform",
+	"https://www.googleapis.com/auth/userinfo.email",
+	"https://www.googleapis.com/auth/userinfo.profile",
+];
+const AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
+const TOKEN_URL = "https://oauth2.googleapis.com/token";
+const CODE_ASSIST_ENDPOINT = "https://cloudcode-pa.googleapis.com";
+
+interface LoadCodeAssistPayload {
+	cloudaicompanionProject?: string;
+	currentTier?: { id?: string };
+	allowedTiers?: Array<{ id?: string; isDefault?: boolean }>;
+}
+
+interface LongRunningOperationResponse {
+	name?: string;
+	done?: boolean;
+	response?: {
+		cloudaicompanionProject?: { id?: string };
+	};
+}
+
+const TIER_FREE = "free-tier";
+const TIER_LEGACY = "legacy-tier";
+const TIER_STANDARD = "standard-tier";
+
+interface GoogleRpcErrorResponse {
+	error?: {
+		details?: Array<{ reason?: string }>;
+	};
+}
+
+function getDefaultTier(allowedTiers?: Array<{ id?: string; isDefault?: boolean }>): { id?: string } {
+	if (!allowedTiers || allowedTiers.length === 0) return { id: TIER_LEGACY };
+	const defaultTier = allowedTiers.find(t => t.isDefault);
+	return defaultTier ?? { id: TIER_LEGACY };
+}
+
+function isVpcScAffectedUser(payload: unknown): boolean {
+	if (!payload || typeof payload !== "object") return false;
+	if (!("error" in payload)) return false;
+	const error = (payload as GoogleRpcErrorResponse).error;
+	if (!error?.details || !Array.isArray(error.details)) return false;
+	return error.details.some(detail => detail.reason === "SECURITY_POLICY_VIOLATED");
+}
+
+/**
+ * LRO poll cadence and bound. Cloud Code Assist project provisioning normally
+ * completes within a handful of polls; the attempt cap converts a stuck
+ * `done: false` operation (or a service incident) into a bounded login error
+ * instead of the previous unbounded loop.
+ */
+const POLL_INTERVAL_MS = 5000;
+export const POLL_MAX_ATTEMPTS = 24;
+
+export async function pollOperation(
+	operationName: string,
+	headers: Record<string, string>,
+	signal: AbortSignal | undefined,
+	onProgress?: (message: string) => void,
+): Promise<LongRunningOperationResponse> {
+	for (let attempt = 0; attempt < POLL_MAX_ATTEMPTS; attempt += 1) {
+		if (attempt > 0) {
+			onProgress?.(`Waiting for project provisioning (attempt ${attempt + 1}/${POLL_MAX_ATTEMPTS})...`);
+			throwIfLoginCancelled(signal);
+			await Bun.sleep(POLL_INTERVAL_MS);
+		}
+
+		throwIfLoginCancelled(signal);
+		const response = await oauthFetch(
+			`${CODE_ASSIST_ENDPOINT}/v1internal/${operationName}`,
+			{ method: "GET", headers },
+			{ provider: "google-gemini-cli", signal },
+		);
+
+		if (!response.ok) {
+			throw new AIError.OAuthError(`Failed to poll operation: ${response.status} ${response.statusText}`, {
+				kind: "polling",
+				provider: "google-gemini-cli",
+				status: response.status,
+			});
+		}
+
+		const data = (await response.json()) as LongRunningOperationResponse;
+		if (data.done) {
+			return data;
+		}
+	}
+
+	throw new AIError.OAuthError(`Project provisioning did not complete after ${POLL_MAX_ATTEMPTS} attempts`, {
+		kind: "timeout",
+		provider: "google-gemini-cli",
+	});
+}
+
+async function discoverProject(
+	accessToken: string,
+	onProgress?: (message: string) => void,
+	signal?: AbortSignal,
+): Promise<string> {
+	const envProjectId = $env.GOOGLE_CLOUD_PROJECT || $env.GOOGLE_CLOUD_PROJECT_ID;
+
+	const headers = {
+		Authorization: `Bearer ${accessToken}`,
+		"Content-Type": "application/json",
+		...getGeminiCliHeaders(),
+	};
+
+	onProgress?.("Checking for existing Cloud Code Assist project...");
+	const loadResponse = await oauthFetch(
+		`${CODE_ASSIST_ENDPOINT}/v1internal:loadCodeAssist`,
+		{
+			method: "POST",
+			headers,
+			body: JSON.stringify({
+				cloudaicompanionProject: envProjectId,
+				metadata: {
+					ideType: "IDE_UNSPECIFIED",
+					platform: "PLATFORM_UNSPECIFIED",
+					pluginType: "GEMINI",
+					duetProject: envProjectId,
+				},
+			}),
+		},
+		{ provider: "google-gemini-cli", signal },
+	);
+
+	let data: LoadCodeAssistPayload;
+
+	if (!loadResponse.ok) {
+		let errorPayload: unknown;
+		try {
+			errorPayload = await loadResponse.clone().json();
+		} catch {
+			errorPayload = undefined;
+		}
+
+		if (isVpcScAffectedUser(errorPayload)) {
+			data = { currentTier: { id: TIER_STANDARD } };
+		} else {
+			const errorText = await loadResponse.text();
+			throw new AIError.OAuthError(
+				`loadCodeAssist failed: ${loadResponse.status} ${loadResponse.statusText}: ${errorText}`,
+				{ kind: "discovery", provider: "google-gemini-cli", status: loadResponse.status },
+			);
+		}
+	} else {
+		data = (await loadResponse.json()) as LoadCodeAssistPayload;
+	}
+
+	if (data.currentTier) {
+		if (data.cloudaicompanionProject) {
+			return data.cloudaicompanionProject;
+		}
+		if (envProjectId) {
+			return envProjectId;
+		}
+		throw new AIError.OAuthError(
+			"This account requires setting the GOOGLE_CLOUD_PROJECT or GOOGLE_CLOUD_PROJECT_ID environment variable. " +
+				"See https://goo.gle/gemini-cli-auth-docs#workspace-gca",
+			{ kind: "configuration", provider: "google-gemini-cli" },
+		);
+	}
+
+	const tier = getDefaultTier(data.allowedTiers);
+	const tierId = tier?.id ?? TIER_FREE;
+
+	if (tierId !== TIER_FREE && !envProjectId) {
+		throw new AIError.OAuthError(
+			"This account requires setting the GOOGLE_CLOUD_PROJECT or GOOGLE_CLOUD_PROJECT_ID environment variable. " +
+				"See https://goo.gle/gemini-cli-auth-docs#workspace-gca",
+			{ kind: "configuration", provider: "google-gemini-cli" },
+		);
+	}
+
+	onProgress?.("Provisioning Cloud Code Assist project (this may take a moment)...");
+
+	const onboardBody: Record<string, unknown> = {
+		tierId,
+		metadata: {
+			ideType: "IDE_UNSPECIFIED",
+			platform: "PLATFORM_UNSPECIFIED",
+			pluginType: "GEMINI",
+		},
+	};
+
+	if (tierId !== TIER_FREE && envProjectId) {
+		onboardBody.cloudaicompanionProject = envProjectId;
+		(onboardBody.metadata as Record<string, unknown>).duetProject = envProjectId;
+	}
+
+	const onboardResponse = await oauthFetch(
+		`${CODE_ASSIST_ENDPOINT}/v1internal:onboardUser`,
+		{ method: "POST", headers, body: JSON.stringify(onboardBody) },
+		{ provider: "google-gemini-cli", signal },
+	);
+
+	if (!onboardResponse.ok) {
+		const errorText = await onboardResponse.text();
+		throw new AIError.OAuthError(
+			`onboardUser failed: ${onboardResponse.status} ${onboardResponse.statusText}: ${errorText}`,
+			{ kind: "provisioning", provider: "google-gemini-cli", status: onboardResponse.status },
+		);
+	}
+
+	let lroData = (await onboardResponse.json()) as LongRunningOperationResponse;
+
+	if (!lroData.done && lroData.name) {
+		lroData = await pollOperation(lroData.name, headers, signal, onProgress);
+	}
+
+	const projectId = lroData.response?.cloudaicompanionProject?.id;
+	if (projectId) {
+		return projectId;
+	}
+
+	if (envProjectId) {
+		return envProjectId;
+	}
+
+	throw new AIError.OAuthError(
+		"Could not discover or provision a Google Cloud project. " +
+			"Try setting the GOOGLE_CLOUD_PROJECT or GOOGLE_CLOUD_PROJECT_ID environment variable. " +
+			"See https://goo.gle/gemini-cli-auth-docs#workspace-gca",
+		{ kind: "validation", provider: "google-gemini-cli" },
+	);
+}
+
+export async function loginGeminiCli(ctrl: OAuthController): Promise<OAuthCredentials> {
+	return runGoogleOAuthLogin(ctrl, {
+		provider: "google-gemini-cli",
+		clientId: CLIENT_ID,
+		clientSecret: CLIENT_SECRET,
+		authUrl: AUTH_URL,
+		tokenUrl: TOKEN_URL,
+		scopes: SCOPES,
+		callbackPort: CALLBACK_PORT,
+		callbackPath: CALLBACK_PATH,
+		discoverProject,
+	});
+}
+
+/**
+ * Refresh Google Cloud Code Assist token
+ */
+export async function refreshGoogleCloudToken(refreshToken: string, projectId: string): Promise<OAuthCredentials> {
+	const response = await fetch(TOKEN_URL, {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body: new URLSearchParams({
+			client_id: CLIENT_ID,
+			client_secret: CLIENT_SECRET,
+			refresh_token: refreshToken,
+			grant_type: "refresh_token",
+		}),
+	});
+
+	if (!response.ok) {
+		const error = await response.text();
+		throw new AIError.OAuthError(`Google Cloud token refresh failed: ${error}`, {
+			kind: "token-refresh",
+			provider: "google-gemini-cli",
+		});
+	}
+
+	const data = (await response.json()) as {
+		access_token: string;
+		expires_in: number;
+		refresh_token?: string;
+	};
+
+	return {
+		refresh: data.refresh_token || refreshToken,
+		access: data.access_token,
+		expires: Date.now() + data.expires_in * 1000 - 5 * 60 * 1000,
+		projectId,
+	};
+}

package/src/registry/oauth/google-oauth-shared.ts

@@ -0,0 +1,211 @@
+/**
+ * Shared OAuth flow for Google-style providers (Gemini CLI, Antigravity).
+ *
+ * Both providers use the same authorization-code flow shape; only the client
+ * credentials, scopes, endpoint constants, and project-discovery logic differ.
+ */
+import * as AIError from "../../error";
+import { extractGoogleValidationUrl, formatGoogleValidationRequiredMessage } from "../../utils/google-validation";
+import { OAuthCallbackFlow } from "./callback-server";
+import type { OAuthController, OAuthCredentials } from "./types";
+
+/**
+ * Per-request timeout for the post-callback provisioning phase (token exchange,
+ * user-info, project discovery/onboarding, LRO polling). These Cloud Code
+ * Assist calls normally settle in well under this window; a longer stall means
+ * a hung endpoint that must surface a login error instead of hanging forever.
+ * The callback server's own 300s deadline covers only the browser-callback wait
+ * ({@link OAuthCallbackFlow}) and does not gate this phase.
+ */
+export const OAUTH_REQUEST_TIMEOUT_MS = 30_000;
+
+/** Options for {@link oauthFetch}. */
+export interface OAuthFetchOptions {
+	/** Provider id recorded on any {@link AIError.OAuthError} raised. */
+	provider: string;
+	/** Controller signal; when it aborts, the in-flight request is cancelled. */
+	signal?: AbortSignal;
+	/** Override the per-request timeout (defaults to {@link OAUTH_REQUEST_TIMEOUT_MS}). */
+	timeoutMs?: number;
+}
+
+/**
+ * Throw {@link AIError.LoginCancelledError} when the controller signal has
+ * already aborted. Gates each provisioning round-trip, which the callback-wait
+ * cancellation checks in {@link OAuthCallbackFlow} do not reach.
+ */
+export function throwIfLoginCancelled(signal: AbortSignal | undefined): void {
+	if (signal?.aborted) {
+		throw new AIError.LoginCancelledError(`OAuth login cancelled: ${String(signal.reason)}`);
+	}
+}
+
+/**
+ * `fetch` for the provisioning phase: composes the controller signal with a
+ * per-request timeout so a stalled endpoint aborts instead of hanging login,
+ * and user cancellation aborts the in-flight request. Cancellation surfaces as
+ * {@link AIError.LoginCancelledError}; a timeout surfaces as an
+ * {@link AIError.OAuthError} with `kind: "timeout"`.
+ */
+export async function oauthFetch(
+	url: string,
+	init: RequestInit,
+	{ provider, signal, timeoutMs = OAUTH_REQUEST_TIMEOUT_MS }: OAuthFetchOptions,
+): Promise<Response> {
+	const timeoutSignal = AbortSignal.timeout(timeoutMs);
+	const requestSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+	try {
+		return await fetch(url, { ...init, signal: requestSignal });
+	} catch (err) {
+		if (signal?.aborted) {
+			throw new AIError.LoginCancelledError(`OAuth login cancelled: ${String(signal.reason)}`);
+		}
+		if (timeoutSignal.aborted) {
+			throw new AIError.OAuthError(`Timed out after ${timeoutMs}ms waiting for ${url}`, {
+				kind: "timeout",
+				provider,
+			});
+		}
+		throw err;
+	}
+}
+
+export interface GoogleOAuthFlowConfig {
+	/** Provider id used in progress/error reporting and per-request fetches. */
+	provider: string;
+	clientId: string;
+	clientSecret: string;
+	authUrl: string;
+	tokenUrl: string;
+	scopes: string[];
+	callbackPort: number;
+	callbackPath: string;
+	discoverProject: (
+		accessToken: string,
+		onProgress?: (message: string) => void,
+		signal?: AbortSignal,
+	) => Promise<string>;
+}
+
+async function getUserEmail(
+	accessToken: string,
+	provider: string,
+	signal: AbortSignal | undefined,
+): Promise<string | undefined> {
+	try {
+		const response = await oauthFetch(
+			"https://www.googleapis.com/oauth2/v1/userinfo?alt=json",
+			{ headers: { Authorization: `Bearer ${accessToken}` } },
+			{ provider, signal },
+		);
+
+		if (response.ok) {
+			const data = (await response.json()) as { email?: string };
+			return data.email;
+		}
+	} catch {
+		// Ignore errors, email is optional; the caller re-checks cancellation.
+	}
+	return undefined;
+}
+
+export class GoogleOAuthFlow extends OAuthCallbackFlow {
+	private readonly config: GoogleOAuthFlowConfig;
+
+	constructor(ctrl: OAuthController, config: GoogleOAuthFlowConfig) {
+		super(ctrl, {
+			preferredPort: config.callbackPort,
+			callbackPath: config.callbackPath,
+			callbackHostname: "127.0.0.1",
+		});
+		this.config = config;
+	}
+
+	async generateAuthUrl(state: string, redirectUri: string): Promise<{ url: string; instructions?: string }> {
+		const authParams = new URLSearchParams({
+			client_id: this.config.clientId,
+			response_type: "code",
+			redirect_uri: redirectUri,
+			scope: this.config.scopes.join(" "),
+			state,
+			access_type: "offline",
+			prompt: "consent",
+		});
+
+		const url = `${this.config.authUrl}?${authParams.toString()}`;
+		return { url, instructions: "Complete the sign-in in your browser." };
+	}
+
+	async exchangeToken(code: string, _state: string, redirectUri: string): Promise<OAuthCredentials> {
+		const { provider } = this.config;
+		const signal = this.ctrl.signal;
+		throwIfLoginCancelled(signal);
+		this.ctrl.onProgress?.("Exchanging authorization code for tokens...");
+
+		const tokenResponse = await oauthFetch(
+			this.config.tokenUrl,
+			{
+				method: "POST",
+				headers: { "Content-Type": "application/x-www-form-urlencoded" },
+				body: new URLSearchParams({
+					client_id: this.config.clientId,
+					client_secret: this.config.clientSecret,
+					code,
+					grant_type: "authorization_code",
+					redirect_uri: redirectUri,
+				}),
+			},
+			{ provider, signal },
+		);
+
+		if (!tokenResponse.ok) {
+			const error = await tokenResponse.text();
+			throw new AIError.OAuthError(`Token exchange failed: ${error}`, { kind: "token-exchange", provider });
+		}
+
+		const tokenData = (await tokenResponse.json()) as {
+			access_token: string;
+			refresh_token: string;
+			expires_in: number;
+		};
+
+		if (!tokenData.refresh_token) {
+			throw new AIError.OAuthError("No refresh token received. Please try again.", {
+				kind: "validation",
+				provider,
+			});
+		}
+
+		throwIfLoginCancelled(signal);
+		this.ctrl.onProgress?.("Getting user info...");
+		const email = await getUserEmail(tokenData.access_token, provider, signal);
+		throwIfLoginCancelled(signal);
+		let projectId: string;
+		try {
+			projectId = await this.config.discoverProject(tokenData.access_token, this.ctrl.onProgress, signal);
+		} catch (err) {
+			const validationUrl = extractGoogleValidationUrl(err instanceof Error ? err.message : String(err));
+			if (!validationUrl) throw err;
+			throw new AIError.OAuthError(formatGoogleValidationRequiredMessage(validationUrl, "sign in again", email), {
+				kind: "validation",
+				provider,
+			});
+		}
+
+		return {
+			refresh: tokenData.refresh_token,
+			access: tokenData.access_token,
+			expires: Date.now() + tokenData.expires_in * 1000 - 5 * 60 * 1000,
+			projectId,
+			email,
+		};
+	}
+}
+
+export async function runGoogleOAuthLogin(
+	ctrl: OAuthController,
+	config: GoogleOAuthFlowConfig,
+): Promise<OAuthCredentials> {
+	const flow = new GoogleOAuthFlow(ctrl, config);
+	return flow.login();
+}

package/src/registry/oauth/index.ts

@@ -0,0 +1,187 @@
+// ============================================================================
+// High-level API
+// ============================================================================
+
+import * as AIError from "../../error";
+import { getProviderDefinition, PROVIDER_REGISTRY } from "../registry";
+import type {
+	OAuthCredentials,
+	OAuthProvider,
+	OAuthProviderId,
+	OAuthProviderInfo,
+	OAuthProviderInterface,
+} from "./types";
+
+export * from "./anthropic";
+export * from "./device-code";
+export type * from "./types";
+
+const builtInOAuthProviders: OAuthProviderInfo[] = PROVIDER_REGISTRY.filter(
+	provider => provider.login && provider.showInLoginList !== false,
+).map(provider => ({
+	id: provider.id,
+	name: provider.name,
+	available: provider.available ?? true,
+	storeCredentialsAs: provider.storeCredentialsAs,
+}));
+
+const customOAuthProviders = new Map<string, OAuthProviderInterface>();
+
+/**
+ * Register a custom OAuth provider.
+ */
+export function registerOAuthProvider(provider: OAuthProviderInterface): void {
+	customOAuthProviders.set(provider.id, provider);
+}
+
+/**
+ * Remove a custom OAuth provider by ID.
+ */
+export function unregisterOAuthProvider(id: string): void {
+	customOAuthProviders.delete(id);
+}
+
+/**
+ * Get a custom OAuth provider by ID.
+ */
+export function getOAuthProvider(id: OAuthProviderId): OAuthProviderInterface | undefined {
+	return customOAuthProviders.get(id);
+}
+
+/**
+ * Remove all custom OAuth providers registered by a source.
+ */
+export function unregisterOAuthProviders(sourceId: string): void {
+	for (const [id, provider] of customOAuthProviders.entries()) {
+		if (provider.sourceId === sourceId) {
+			customOAuthProviders.delete(id);
+		}
+	}
+}
+
+/**
+ * Refresh token for any OAuth provider.
+ * Saves the new credentials and returns the new access token.
+ */
+export async function refreshOAuthToken(
+	provider: OAuthProvider,
+	credentials: OAuthCredentials,
+): Promise<OAuthCredentials> {
+	if (!credentials) {
+		throw new AIError.OAuthError(`No OAuth credentials found for ${provider}`, {
+			kind: "validation",
+			provider,
+		});
+	}
+	const def = getProviderDefinition(provider);
+	if (!def?.login) {
+		throw new AIError.OAuthError(`Unknown OAuth provider: ${provider}`, {
+			kind: "validation",
+			provider,
+		});
+	}
+	// Providers without a real refresher (static bearer tokens / API keys that
+	// don't expire) return the credentials unchanged.
+	return def.refreshToken ? def.refreshToken(credentials) : credentials;
+}
+function getPerplexityJwtExpiryMs(token: string): number | undefined {
+	const parts = token.split(".");
+	if (parts.length !== 3) return undefined;
+	const payload = parts[1];
+	if (!payload) return undefined;
+	try {
+		const decoded = JSON.parse(Buffer.from(payload, "base64url").toString("utf8")) as { exp?: unknown };
+		if (typeof decoded.exp !== "number" || !Number.isFinite(decoded.exp)) return undefined;
+		return decoded.exp * 1000 - 5 * 60_000;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Build API-key bytes for a provider from an already-fresh OAuth credential.
+ *
+ * Refresh is owned by AuthStorage. This helper deliberately refuses expired
+ * credentials so it cannot POST broker redaction sentinels to upstream token
+ * endpoints as a side channel.
+ *
+ * For providers that need credential metadata at request time, returns
+ * JSON-encoded credentials plus expiry metadata for diagnostics/edge guards.
+ * @returns API key string, or null if no credentials
+ * @throws Error if the credential is expired and must be refreshed upstream
+ */
+export async function getOAuthApiKey(
+	provider: OAuthProvider,
+	credentials: Record<string, OAuthCredentials>,
+): Promise<{ newCredentials: OAuthCredentials; apiKey: string } | null> {
+	let creds = credentials[provider];
+	if (!creds) {
+		return null;
+	}
+
+	if (provider === "perplexity") {
+		// Perplexity JWTs usually omit `exp` (server-side sessions). Trust the JWT
+		// claim when present; otherwise treat the credential as non-expiring rather
+		// than honoring a stale stored `expires` (older logins wrote loginTime+1h).
+		const NEVER_EXPIRES = 8.64e15;
+		const normalizedExpires =
+			creds.expires > 0 && creds.expires < 10_000_000_000 ? creds.expires * 1000 : creds.expires;
+		const jwtExpiry = getPerplexityJwtExpiryMs(creds.access);
+		const expires = jwtExpiry ?? Math.max(normalizedExpires, NEVER_EXPIRES);
+		if (expires !== creds.expires) {
+			creds = { ...creds, expires };
+		}
+	}
+	// Refresh is the sole responsibility of `AuthStorage` (which calls
+	// `refreshOAuthToken` directly with broker-aware single-flighting). If we
+	// reach here with an expired credential, the outer pipeline failed to
+	// refresh before this call OR the refresh slot is the broker sentinel —
+	// either way, posting the credential to a provider endpoint would only
+	// trigger a `__remote__`-against-real-provider failure that gets classified
+	// as `invalid_grant` and disables the row. Refuse loudly instead.
+	if (Date.now() >= creds.expires) {
+		if (provider === "perplexity") {
+			const jwtExpiry = getPerplexityJwtExpiryMs(creds.access);
+			if (jwtExpiry && Date.now() < jwtExpiry) {
+				const fallbackCredentials = { ...creds, expires: jwtExpiry };
+				return { newCredentials: fallbackCredentials, apiKey: fallbackCredentials.access };
+			}
+		}
+		throw new AIError.OAuthError(
+			`OAuth credential for ${provider} is expired and must be refreshed via AuthStorage before getOAuthApiKey is called`,
+			{ kind: "validation", provider },
+		);
+	}
+	// For providers that need request-time credential metadata, return JSON.
+	const needsStructuredApiKey =
+		provider === "github-copilot" ||
+		provider === "google-gemini-cli" ||
+		provider === "google-antigravity" ||
+		provider === "alibaba-coding-plan";
+	const apiKey = needsStructuredApiKey
+		? JSON.stringify({
+				apiEndpoint: creds.apiEndpoint,
+				token: creds.access,
+				enterpriseUrl: creds.enterpriseUrl,
+				projectId: creds.projectId,
+				refreshToken: creds.refresh,
+				expiresAt: creds.expires,
+				email: creds.email,
+				accountId: creds.accountId,
+			})
+		: creds.access;
+	return { newCredentials: creds, apiKey };
+}
+
+/**
+ * Get list of OAuth providers.
+ */
+export function getOAuthProviders(): OAuthProviderInfo[] {
+	const customProviders = Array.from(customOAuthProviders.values(), provider => ({
+		id: provider.id,
+		name: provider.name,
+		available: true,
+		storeCredentialsAs: provider.storeCredentialsAs,
+	}));
+	return [...builtInOAuthProviders, ...customProviders];
+}