@prometheus-ai/ai 0.5.4 → 0.5.8

package/src/{utils → registry}/oauth/github-copilot.ts

@@ -2,19 +2,32 @@
  * GitHub Copilot OAuth flow (opencode OAuth app)
  */
 import { scheduler } from "node:timers/promises";
-import { getBundledModels } from "../../models";
+import { getBundledModels } from "@prometheus-ai/catalog/models";
+import {
+	COPILOT_API_HEADERS,
+	getGitHubCopilotBaseUrl,
+	isPublicGitHubHost,
+	normalizeDomain,
+	normalizeGitHubCopilotEnterpriseDomain,
+	OPENCODE_HEADERS,
+} from "@prometheus-ai/catalog/wire/github-copilot";
+import type { FetchImpl } from "../../types";
 import type { OAuthCredentials } from "./types";
 
 const CLIENT_ID = "Ov23li8tweQw6odWQebz";
 
-export const COPILOT_USER_AGENT = "opencode/1.3.15" as const;
-
-export const OPENCODE_HEADERS = {
-	"User-Agent": COPILOT_USER_AGENT,
-} as const;
-
 const INITIAL_POLL_INTERVAL_MULTIPLIER = 1.2;
 const SLOW_DOWN_POLL_INTERVAL_MULTIPLIER = 1.4;
+
+type GitHubCopilotLoginOptions = {
+	onAuth: (url: string, instructions?: string) => void;
+	onPrompt: (prompt: { message: string; placeholder?: string; allowEmpty?: boolean }) => Promise<string>;
+	onProgress?: (message: string) => void;
+	signal?: AbortSignal;
+	pollIntervalFloorMs?: number;
+	pollIntervalScaleMs?: number;
+	fetch?: FetchImpl;
+};
 type DeviceCodeResponse = {
 	device_code: string;
 	user_code: string;
@@ -35,58 +48,6 @@ type DeviceTokenErrorResponse = {
 	interval?: number;
 };
 
-type GitHubCopilotApiKeyPayload = {
-	token?: unknown;
-	enterpriseUrl?: unknown;
-};
-
-export type ParsedGitHubCopilotApiKey = {
-	accessToken: string;
-	enterpriseUrl?: string;
-};
-
-const PUBLIC_GITHUB_HOSTS = new Set(["api.github.com", "github.com", "www.github.com"]);
-
-function isPublicGitHubHost(host: string): boolean {
-	return PUBLIC_GITHUB_HOSTS.has(host.trim().toLowerCase());
-}
-
-export function normalizeGitHubCopilotEnterpriseDomain(input: string | undefined): string | undefined {
-	const trimmed = input?.trim();
-	if (!trimmed) return undefined;
-	const normalized = normalizeDomain(trimmed) ?? trimmed.toLowerCase();
-	if (!normalized || isPublicGitHubHost(normalized)) return undefined;
-	return normalized;
-}
-
-export function parseGitHubCopilotApiKey(apiKeyRaw: string): ParsedGitHubCopilotApiKey {
-	try {
-		const parsed = JSON.parse(apiKeyRaw) as GitHubCopilotApiKeyPayload;
-		if (typeof parsed.token === "string") {
-			return {
-				accessToken: parsed.token,
-				enterpriseUrl:
-					typeof parsed.enterpriseUrl === "string"
-						? normalizeGitHubCopilotEnterpriseDomain(parsed.enterpriseUrl)
-						: undefined,
-			};
-		}
-	} catch {}
-
-	return { accessToken: apiKeyRaw };
-}
-
-export function normalizeDomain(input: string): string | null {
-	const trimmed = input.trim();
-	if (!trimmed) return null;
-	try {
-		const url = trimmed.includes("://") ? new URL(trimmed) : new URL(`https://${trimmed}`);
-		return url.hostname;
-	} catch {
-		return null;
-	}
-}
-
 function getUrls(domain: string): {
 	deviceCodeUrl: string;
 	accessTokenUrl: string;
@@ -97,17 +58,8 @@ function getUrls(domain: string): {
 	};
 }
 
-export function getGitHubCopilotBaseUrl(enterpriseDomain?: string): string {
-	const normalizedEnterpriseDomain = normalizeGitHubCopilotEnterpriseDomain(enterpriseDomain);
-	if (!normalizedEnterpriseDomain) return "https://api.githubcopilot.com";
-	const host = normalizedEnterpriseDomain.startsWith("copilot-api.")
-		? normalizedEnterpriseDomain
-		: `copilot-api.${normalizedEnterpriseDomain}`;
-	return `https://${host}`;
-}
-
-async function fetchJson(url: string, init: RequestInit): Promise<unknown> {
-	const response = await fetch(url, init);
+async function fetchJson(url: string, init: RequestInit, fetchImpl: FetchImpl): Promise<unknown> {
+	const response = await fetchImpl(url, init);
 	if (!response.ok) {
 		const text = await response.text();
 		throw new Error(`${response.status} ${response.statusText}: ${text}`);
@@ -115,20 +67,24 @@ async function fetchJson(url: string, init: RequestInit): Promise<unknown> {
 	return response.json();
 }
 
-async function startDeviceFlow(domain: string): Promise<DeviceCodeResponse> {
+async function startDeviceFlow(domain: string, fetchImpl: FetchImpl): Promise<DeviceCodeResponse> {
 	const urls = getUrls(domain);
-	const data = await fetchJson(urls.deviceCodeUrl, {
-		method: "POST",
-		headers: {
-			Accept: "application/json",
-			"Content-Type": "application/json",
-			...OPENCODE_HEADERS,
+	const data = await fetchJson(
+		urls.deviceCodeUrl,
+		{
+			method: "POST",
+			headers: {
+				Accept: "application/json",
+				"Content-Type": "application/json",
+				...OPENCODE_HEADERS,
+			},
+			body: JSON.stringify({
+				client_id: CLIENT_ID,
+				scope: "read:user",
+			}),
 		},
-		body: JSON.stringify({
-			client_id: CLIENT_ID,
-			scope: "read:user",
-		}),
-	});
+		fetchImpl,
+	);
 
 	if (!data || typeof data !== "object") {
 		throw new Error("Invalid device code response");
@@ -164,7 +120,8 @@ async function pollForGitHubAccessToken(
 	deviceCode: string,
 	intervalSeconds: number,
 	expiresIn: number,
-	signal?: AbortSignal,
+	signal: AbortSignal | undefined,
+	fetchImpl: FetchImpl,
 	pollIntervalFloorMs = 1000,
 	pollIntervalScaleMs = 1000,
 ) {
@@ -187,19 +144,23 @@ async function pollForGitHubAccessToken(
 			throw new Error("Login cancelled");
 		}
 
-		const raw = await fetchJson(urls.accessTokenUrl, {
-			method: "POST",
-			headers: {
-				Accept: "application/json",
-				"Content-Type": "application/json",
-				...OPENCODE_HEADERS,
+		const raw = await fetchJson(
+			urls.accessTokenUrl,
+			{
+				method: "POST",
+				headers: {
+					Accept: "application/json",
+					"Content-Type": "application/json",
+					...OPENCODE_HEADERS,
+				},
+				body: JSON.stringify({
+					client_id: CLIENT_ID,
+					device_code: deviceCode,
+					grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+				}),
 			},
-			body: JSON.stringify({
-				client_id: CLIENT_ID,
-				device_code: deviceCode,
-				grant_type: "urn:ietf:params:oauth:grant-type:device_code",
-			}),
-		});
+			fetchImpl,
+		);
 
 		if (raw && typeof raw === "object" && typeof (raw as DeviceTokenSuccessResponse).access_token === "string") {
 			return (raw as DeviceTokenSuccessResponse).access_token;
@@ -255,17 +216,22 @@ export function refreshGitHubCopilotToken(refreshToken: string, enterpriseDomain
  * Enable a model for the user's GitHub Copilot account.
  * This is required for some models (like Claude, Grok) before they can be used.
  */
-async function enableGitHubCopilotModel(token: string, modelId: string, enterpriseDomain?: string): Promise<boolean> {
+async function enableGitHubCopilotModel(
+	token: string,
+	modelId: string,
+	fetchImpl: FetchImpl,
+	enterpriseDomain?: string,
+): Promise<boolean> {
 	const baseUrl = getGitHubCopilotBaseUrl(enterpriseDomain);
 	const url = `${baseUrl}/models/${modelId}/policy`;
 
 	try {
-		const response = await fetch(url, {
+		const response = await fetchImpl(url, {
 			method: "POST",
 			headers: {
 				"Content-Type": "application/json",
 				Authorization: `Bearer ${token}`,
-				...OPENCODE_HEADERS,
+				...COPILOT_API_HEADERS,
 				"openai-intent": "chat-policy",
 				"x-interaction-type": "chat-policy",
 			},
@@ -283,17 +249,20 @@ async function enableGitHubCopilotModel(token: string, modelId: string, enterpri
  */
 async function enableAllGitHubCopilotModels(
 	token: string,
-	enterpriseDomain?: string,
+	enterpriseDomain: string | undefined,
+	fetchImpl: FetchImpl,
 	onProgress?: (model: string, success: boolean) => void,
 ): Promise<void> {
-	const models = getBundledModels("github-copilot");
+	// Synthesized catalog variants (Copilot long-context `-1m` entries) share
+	// the upstream model id; enable each wire id exactly once.
+	const wireModelIds = [...new Set(getBundledModels("github-copilot").map(model => model.requestModelId ?? model.id))];
 	const BATCH_SIZE = 5;
-	for (let i = 0; i < models.length; i += BATCH_SIZE) {
-		const batch = models.slice(i, i + BATCH_SIZE);
+	for (let i = 0; i < wireModelIds.length; i += BATCH_SIZE) {
+		const batch = wireModelIds.slice(i, i + BATCH_SIZE);
 		await Promise.all(
-			batch.map(async model => {
-				const success = await enableGitHubCopilotModel(token, model.id, enterpriseDomain);
-				onProgress?.(model.id, success);
+			batch.map(async modelId => {
+				const success = await enableGitHubCopilotModel(token, modelId, fetchImpl, enterpriseDomain);
+				onProgress?.(modelId, success);
 			}),
 		);
 	}
@@ -307,14 +276,8 @@ async function enableAllGitHubCopilotModels(
  * @param options.onProgress - Optional progress callback
  * @param options.signal - Optional AbortSignal for cancellation
  */
-export async function loginGitHubCopilot(options: {
-	onAuth: (url: string, instructions?: string) => void;
-	onPrompt: (prompt: { message: string; placeholder?: string; allowEmpty?: boolean }) => Promise<string>;
-	onProgress?: (message: string) => void;
-	signal?: AbortSignal;
-	pollIntervalFloorMs?: number;
-	pollIntervalScaleMs?: number;
-}): Promise<OAuthCredentials> {
+export async function loginGitHubCopilot(options: GitHubCopilotLoginOptions): Promise<OAuthCredentials> {
+	const fetchImpl = options.fetch ?? fetch;
 	const input = await options.onPrompt({
 		message: "GitHub Enterprise URL/domain (blank for github.com)",
 		placeholder: "company.ghe.com",
@@ -334,7 +297,7 @@ export async function loginGitHubCopilot(options: {
 	const domain =
 		normalizedDomain && isPublicGitHubHost(normalizedDomain) ? "github.com" : (normalizedDomain ?? "github.com");
 
-	const device = await startDeviceFlow(domain);
+	const device = await startDeviceFlow(domain, fetchImpl);
 	options.onAuth(device.verification_uri, `Enter code: ${device.user_code}`);
 
 	const githubAccessToken = await pollForGitHubAccessToken(
@@ -343,6 +306,7 @@ export async function loginGitHubCopilot(options: {
 		device.interval,
 		device.expires_in,
 		options.signal,
+		fetchImpl,
 		options.pollIntervalFloorMs,
 		options.pollIntervalScaleMs,
 	);
@@ -357,6 +321,6 @@ export async function loginGitHubCopilot(options: {
 
 	// Enable all models after successful login
 	options.onProgress?.("Enabling models...");
-	await enableAllGitHubCopilotModels(githubAccessToken, enterpriseDomain ?? undefined);
+	await enableAllGitHubCopilotModels(githubAccessToken, enterpriseDomain ?? undefined, fetchImpl);
 	return credentials;
 }

package/src/registry/oauth/gitlab-duo.ts

@@ -0,0 +1,198 @@
+import { clearGitLabDuoDirectAccessCache } from "../../providers/gitlab-duo";
+import type { FetchImpl } from "../../types";
+import { OAuthCallbackFlow, type OAuthCallbackFlowOptions } from "./callback-server";
+import { generatePKCE } from "./pkce";
+import type { OAuthCredentials, OAuthLoginCallbacks } from "./types";
+
+const GITLAB_COM_URL = "https://gitlab.com";
+/**
+ * Default OAuth client id baked into the bundled GitLab Duo login flow. GitLab
+ * authorize requests are rejected outright (`The redirect URI included is not
+ * valid`) whenever this client id's registered redirect URI list drifts from
+ * `http://localhost:8080/callback`. Users hitting that case can either:
+ *
+ * - register their own GitLab OAuth application and override the bundled
+ *   credentials with `GITLAB_CLIENT_ID` + `GITLAB_REDIRECT_URI`, or
+ * - skip OAuth entirely and supply a Personal Access Token via `GITLAB_TOKEN`.
+ *
+ * @see https://github.com/uttamtrivedi/prometheus/issues/2424
+ */
+const DEFAULT_CLIENT_ID = "da4edff2e6ebd2bc3208611e2768bc1c1dd7be791dc5ff26ca34ca9ee44f7d4b";
+const OAUTH_SCOPES = ["api"];
+const DEFAULT_CALLBACK_PORT = 8080;
+const DEFAULT_CALLBACK_PATH = "/callback";
+const DEFAULT_CALLBACK_HOSTNAME = "localhost";
+
+interface PKCEPair {
+	verifier: string;
+	challenge: string;
+}
+
+/**
+ * Resolve the OAuth client id, preferring `GITLAB_CLIENT_ID` when set so users
+ * with their own GitLab OAuth application can bypass the bundled credentials.
+ */
+function resolveClientId(): string {
+	const env = process.env.GITLAB_CLIENT_ID?.trim();
+	return env && env.length > 0 ? env : DEFAULT_CLIENT_ID;
+}
+
+/**
+ * Resolve callback-server options from `GITLAB_REDIRECT_URI`. When set, the
+ * exact string is advertised to GitLab (strict matching), random-port fallback
+ * is disabled, and HTTP loopback URIs bind the listener to the URI's host/port
+ * so the browser callback lands on us. HTTPS loopback URIs are rejected because
+ * the local callback server is plaintext HTTP. Non-loopback URIs bind a random
+ * local port — only the paste-code path can complete in that case.
+ */
+function resolveCallbackOptions(): OAuthCallbackFlowOptions {
+	const raw = process.env.GITLAB_REDIRECT_URI?.trim();
+	if (!raw) {
+		return {
+			preferredPort: DEFAULT_CALLBACK_PORT,
+			callbackPath: DEFAULT_CALLBACK_PATH,
+			callbackHostname: DEFAULT_CALLBACK_HOSTNAME,
+		};
+	}
+
+	let parsed: URL;
+	try {
+		parsed = new URL(raw);
+	} catch {
+		throw new Error(`Invalid GITLAB_REDIRECT_URI: ${raw}`);
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+		throw new Error(`GITLAB_REDIRECT_URI must use http:// or https://, got: ${raw}`);
+	}
+
+	const isLoopback = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1" || parsed.hostname === "[::1]";
+	if (isLoopback && parsed.protocol !== "http:") {
+		throw new Error(`GITLAB_REDIRECT_URI loopback callbacks must use http://, got: ${raw}`);
+	}
+
+	const port = parsed.port ? Number.parseInt(parsed.port, 10) : parsed.protocol === "https:" ? 443 : 80;
+
+	return {
+		preferredPort: isLoopback ? port : 0,
+		callbackPath: parsed.pathname || DEFAULT_CALLBACK_PATH,
+		callbackHostname: isLoopback ? parsed.hostname : DEFAULT_CALLBACK_HOSTNAME,
+		redirectUri: raw,
+	};
+}
+
+function mapTokenResponse(payload: {
+	access_token?: string;
+	refresh_token?: string;
+	expires_in?: number;
+	created_at?: number;
+}): OAuthCredentials {
+	if (!payload.access_token || !payload.refresh_token || typeof payload.expires_in !== "number") {
+		throw new Error("GitLab OAuth token response missing required fields");
+	}
+
+	const createdAtMs =
+		typeof payload.created_at === "number" && Number.isFinite(payload.created_at)
+			? payload.created_at * 1000
+			: Date.now();
+
+	return {
+		access: payload.access_token,
+		refresh: payload.refresh_token,
+		expires: createdAtMs + payload.expires_in * 1000 - 5 * 60 * 1000,
+	};
+}
+
+class GitLabDuoOAuthFlow extends OAuthCallbackFlow {
+	#pkce: PKCEPair;
+	#clientId: string;
+	#fetch: FetchImpl;
+
+	constructor(ctrl: OAuthLoginCallbacks, pkce: PKCEPair, clientId: string, options: OAuthCallbackFlowOptions) {
+		super(ctrl, options);
+		this.#pkce = pkce;
+		this.#clientId = clientId;
+		this.#fetch = ctrl.fetch ?? fetch;
+	}
+
+	override async generateAuthUrl(state: string, redirectUri: string): Promise<{ url: string; instructions?: string }> {
+		const authParams = new URLSearchParams({
+			client_id: this.#clientId,
+			redirect_uri: redirectUri,
+			response_type: "code",
+			scope: OAUTH_SCOPES.join(" "),
+			code_challenge: this.#pkce.challenge,
+			code_challenge_method: "S256",
+			state,
+		});
+
+		return {
+			url: `${GITLAB_COM_URL}/oauth/authorize?${authParams.toString()}`,
+			instructions:
+				'Complete GitLab login in browser. If GitLab responds with "The redirect URI included is not valid", ' +
+				"register your own GitLab OAuth application and set GITLAB_CLIENT_ID + GITLAB_REDIRECT_URI, or use a " +
+				"Personal Access Token via GITLAB_TOKEN.",
+		};
+	}
+
+	override async exchangeToken(code: string, _state: string, redirectUri: string): Promise<OAuthCredentials> {
+		const response = await this.#fetch(`${GITLAB_COM_URL}/oauth/token`, {
+			method: "POST",
+			headers: { "Content-Type": "application/x-www-form-urlencoded" },
+			body: new URLSearchParams({
+				client_id: this.#clientId,
+				grant_type: "authorization_code",
+				code,
+				code_verifier: this.#pkce.verifier,
+				redirect_uri: redirectUri,
+			}).toString(),
+		});
+
+		if (!response.ok) {
+			throw new Error(`GitLab OAuth token exchange failed: ${response.status} ${await response.text()}`);
+		}
+
+		clearGitLabDuoDirectAccessCache();
+		return mapTokenResponse(
+			(await response.json()) as {
+				access_token?: string;
+				refresh_token?: string;
+				expires_in?: number;
+				created_at?: number;
+			},
+		);
+	}
+}
+
+export async function loginGitLabDuo(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials> {
+	const pkce = await generatePKCE();
+	const clientId = resolveClientId();
+	const options = resolveCallbackOptions();
+	const flow = new GitLabDuoOAuthFlow(callbacks, pkce, clientId, options);
+	return flow.login();
+}
+
+export async function refreshGitLabDuoToken(credentials: OAuthCredentials): Promise<OAuthCredentials> {
+	const response = await fetch(`${GITLAB_COM_URL}/oauth/token`, {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body: new URLSearchParams({
+			client_id: resolveClientId(),
+			grant_type: "refresh_token",
+			refresh_token: credentials.refresh,
+		}).toString(),
+	});
+
+	if (!response.ok) {
+		throw new Error(`GitLab OAuth refresh failed: ${response.status} ${await response.text()}`);
+	}
+
+	clearGitLabDuoDirectAccessCache();
+	return mapTokenResponse(
+		(await response.json()) as {
+			access_token?: string;
+			refresh_token?: string;
+			expires_in?: number;
+			created_at?: number;
+		},
+	);
+}

package/src/{utils → registry}/oauth/google-antigravity.ts

@@ -2,14 +2,11 @@
  * Antigravity OAuth flow (Gemini 3, Claude, GPT-OSS via Google Cloud)
  * Uses different OAuth credentials than google-gemini-cli for access to additional models.
  */
-import { getAntigravityUserAgent } from "../../providers/google-gemini-headers";
+import { getAntigravityUserAgent } from "@prometheus-ai/catalog/wire/gemini-headers";
 import { runGoogleOAuthLogin } from "./google-oauth-shared";
 import type { OAuthController, OAuthCredentials } from "./types";
 
 const decode = (s: string) => atob(s);
-// Native-app OAuth credentials identify the public Google/Antigravity client.
-// They are not user OAuth tokens, and installed apps cannot keep client
-// credentials confidential. See docs/secrets.md for the release hygiene note.
 const CLIENT_ID = decode(
 	"MTA3MTAwNjA2MDU5MS10bWhzc2luMmgyMWxjcmUyMzV2dG9sb2poNGc0MDNlcC5hcHBzLmdvb2dsZXVzZXJjb250ZW50LmNvbQ==",
 );

package/src/{utils → registry}/oauth/google-gemini-cli.ts

@@ -3,15 +3,12 @@
  * Standard Gemini models only (gemini-2.0-flash, gemini-2.5-*)
  */
 
+import { getGeminiCliHeaders } from "@prometheus-ai/catalog/wire/gemini-headers";
 import { $env } from "@prometheus-ai/utils";
-import { getGeminiCliHeaders } from "../../providers/google-gemini-headers";
 import { runGoogleOAuthLogin } from "./google-oauth-shared";
 import type { OAuthController, OAuthCredentials } from "./types";
 
 const decode = (s: string) => atob(s);
-// Native-app OAuth credentials identify the public Google/Gemini CLI client.
-// They are not user OAuth tokens, and installed apps cannot keep client
-// credentials confidential. See docs/secrets.md for the release hygiene note.
 const CLIENT_ID = decode(
 	"NjgxMjU1ODA5Mzk1LW9vOGZ0Mm9wcmRybnA5ZTNhcWY2YXYzaG1kaWIxMzVqLmFwcHMuZ29vZ2xldXNlcmNvbnRlbnQuY29t",
 );

package/src/registry/oauth/index.ts

@@ -0,0 +1,164 @@
+// ============================================================================
+// High-level API
+// ============================================================================
+
+import { getProviderDefinition, PROVIDER_REGISTRY } from "../registry";
+import type {
+	OAuthCredentials,
+	OAuthProvider,
+	OAuthProviderId,
+	OAuthProviderInfo,
+	OAuthProviderInterface,
+} from "./types";
+
+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,
+}));
+
+const customOAuthProviders = new Map<string, OAuthProviderInterface>();
+
+/**
+ * Register a custom OAuth provider.
+ */
+export function registerOAuthProvider(provider: OAuthProviderInterface): void {
+	customOAuthProviders.set(provider.id, provider);
+}
+
+/**
+ * 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 Error(`No OAuth credentials found for ${provider}`);
+	}
+	const def = getProviderDefinition(provider);
+	if (!def?.login) {
+		throw new Error(`Unknown OAuth provider: ${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 Error(
+			`OAuth credential for ${provider} is expired and must be refreshed via AuthStorage before getOAuthApiKey is called`,
+		);
+	}
+	// For providers that need request-time credential metadata, return JSON.
+	const needsStructuredApiKey =
+		provider === "github-copilot" || provider === "google-gemini-cli" || provider === "google-antigravity";
+	const apiKey = needsStructuredApiKey
+		? JSON.stringify({
+				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,
+	}));
+	return [...builtInOAuthProviders, ...customProviders];
+}