jeopi-ai 16.2.13

package/src/registry/oauth/types.ts

@@ -0,0 +1,65 @@
+import type { FetchImpl } from "../../types";
+import type { OAuthProviderUnion } from "../registry";
+
+export type OAuthCredentials = {
+	refresh: string;
+	access: string;
+	expires: number;
+	enterpriseUrl?: string;
+	projectId?: string;
+	email?: string;
+	accountId?: string;
+	apiEndpoint?: string;
+};
+
+export type OAuthProvider = OAuthProviderUnion;
+
+export type OAuthProviderId = OAuthProvider | (string & {});
+
+export type OAuthPrompt = {
+	message: string;
+	placeholder?: string;
+	allowEmpty?: boolean;
+};
+
+export type OAuthAuthInfo = {
+	url: string;
+	instructions?: string;
+};
+
+export interface OAuthProviderInfo {
+	id: OAuthProviderId;
+	name: string;
+	available: boolean;
+	/**
+	 * Provider id the login stores credentials under, when it differs from `id`
+	 * (e.g. `openai-codex-device` ⇒ `openai-codex`). Lets callers map a login
+	 * entry back to the model provider it authenticates.
+	 */
+	storeCredentialsAs?: string;
+}
+
+export interface OAuthController {
+	onAuth?(info: OAuthAuthInfo): void;
+	onProgress?(message: string): void;
+	onManualCodeInput?(): Promise<string>;
+	onPrompt?(prompt: OAuthPrompt): Promise<string>;
+	signal?: AbortSignal;
+	fetch?: FetchImpl;
+}
+
+export interface OAuthLoginCallbacks extends OAuthController {
+	onAuth: (info: OAuthAuthInfo) => void;
+	onPrompt: (prompt: OAuthPrompt) => Promise<string>;
+}
+
+export interface OAuthProviderInterface {
+	readonly id: OAuthProviderId;
+	readonly name: string;
+	readonly sourceId?: string;
+	login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials | string>;
+	refreshToken?(credentials: OAuthCredentials): Promise<OAuthCredentials>;
+	getApiKey?(credentials: OAuthCredentials): string;
+	/** Store resulting OAuth credentials under a different provider id. */
+	readonly storeCredentialsAs?: string;
+}

package/src/registry/oauth/wafer.ts

@@ -0,0 +1,24 @@
+/**
+ * Wafer Serverless login flow.
+ *
+ * Wafer (https://wafer.ai) exposes a pay-as-you-go OpenAI-compatible SKU at
+ * `https://pass.wafer.ai/v1`. Keys use the `wfr_…` prefix and are validated
+ * against `/v1/models`, which is cheap (no token spend).
+ */
+import { createApiKeyLogin } from "../api-key-login";
+
+const WAFER_AUTH_URL = "https://wafer.ai/dashboard";
+const WAFER_MODELS_URL = "https://pass.wafer.ai/v1/models";
+
+export const loginWaferServerless = createApiKeyLogin({
+	providerLabel: "Wafer Serverless",
+	authUrl: WAFER_AUTH_URL,
+	instructions: "Create or copy your Wafer Serverless API key from the Wafer dashboard",
+	promptMessage: "Paste your Wafer Serverless API key",
+	placeholder: "wfr_...",
+	validation: {
+		kind: "models-endpoint",
+		provider: "Wafer Serverless",
+		modelsUrl: WAFER_MODELS_URL,
+	},
+});

package/src/registry/oauth/xai-oauth.ts

@@ -0,0 +1,394 @@
+// Ported from NousResearch/hermes-agent (MIT) — hermes_cli/auth.py xAI sections (L93-111, L2979-3160, L5286-5469).
+
+/**
+ * xAI Grok (SuperGrok Subscription) OAuth flow.
+ *
+ * Loopback PKCE flow on `127.0.0.1:56121/callback`. One token unlocks Grok-4.x
+ * chat, Grok Imagine image generation, and Grok Voice TTS via subsequent
+ * commits. Endpoint discovery is hardened against MITM via
+ * {@link validateXAIEndpoint}: any non-HTTPS or non-`x.ai`/`*.x.ai` host is
+ * rejected on every call site, not just the first.
+ */
+
+import * as AIError from "../../error";
+import type { FetchImpl } from "../../types";
+import { OAuthCallbackFlow, type OAuthCallbackFlowOptions } from "./callback-server";
+import { generatePKCE } from "./pkce";
+import type { OAuthController, OAuthCredentials } from "./types";
+
+// Hermes hermes_cli/auth.py L93-111
+const XAI_OAUTH_ISSUER = "https://auth.x.ai";
+const XAI_OAUTH_DISCOVERY_URL = `${XAI_OAUTH_ISSUER}/.well-known/openid-configuration`;
+const XAI_OAUTH_CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828";
+const XAI_OAUTH_SCOPE = "openid profile email offline_access grok-cli:access api:access";
+const XAI_OAUTH_REDIRECT_HOST = "127.0.0.1";
+const XAI_OAUTH_REDIRECT_PORT = 56121;
+const XAI_OAUTH_REDIRECT_PATH = "/callback";
+const XAI_OAUTH_DOCS_URL = "https://hermes-agent.nousresearch.com/docs/guides/xai-grok-oauth";
+
+// Mirrors the 5-min skew used by anthropic.ts:160 — keeps every provider on the
+// same conservative client-side expiry window.
+const ACCESS_TOKEN_CLIENT_SKEW_MS = 5 * 60 * 1000;
+
+const DISCOVERY_TIMEOUT_MS = 15_000;
+const TOKEN_REQUEST_TIMEOUT_MS = 20_000;
+
+interface XAIOAuthDiscovery {
+	authorization_endpoint: string;
+	token_endpoint: string;
+}
+
+/**
+ * Validate an xAI OIDC discovery endpoint against scheme + host.
+ *
+ * Hermes `_xai_validate_oauth_endpoint` L2997-3035. The discovery response is
+ * long-lived and cached in {@link OAuthCredentials}; a single MITM during
+ * initial login could substitute a malicious `token_endpoint` that would then
+ * receive every future refresh_token. Rejecting non-HTTPS or non-`x.ai` /
+ * `*.x.ai` hosts pins the cached endpoint to the xAI auth origin.
+ *
+ * @throws Error with message `Invalid xAI <field>: <url>` when the URL fails
+ *         either scheme or host validation.
+ */
+export function validateXAIEndpoint(url: string, field: string): string {
+	let parsed: URL;
+	try {
+		parsed = new URL(url);
+	} catch {
+		throw new AIError.OAuthError(`Invalid xAI ${field}: ${url}`, { kind: "validation", provider: "xai" });
+	}
+	if (parsed.protocol !== "https:") {
+		throw new AIError.OAuthError(`Invalid xAI ${field}: ${url}`, { kind: "validation", provider: "xai" });
+	}
+	const host = parsed.hostname.toLowerCase();
+	if (!host || (host !== "x.ai" && !host.endsWith(".x.ai"))) {
+		throw new AIError.OAuthError(`Invalid xAI ${field}: ${url}`, { kind: "validation", provider: "xai" });
+	}
+	return url;
+}
+
+/**
+ * Fetch xAI's OIDC discovery document and validate both endpoints.
+ *
+ * Hermes `_xai_oauth_discovery` L3038-3084.
+ */
+async function xaiOAuthDiscovery(
+	timeoutMs: number = DISCOVERY_TIMEOUT_MS,
+	fetchOverride?: FetchImpl,
+): Promise<XAIOAuthDiscovery> {
+	const fetchImpl = fetchOverride ?? fetch;
+	let response: Response;
+	try {
+		response = await fetchImpl(XAI_OAUTH_DISCOVERY_URL, {
+			method: "GET",
+			headers: { Accept: "application/json" },
+			signal: AbortSignal.timeout(timeoutMs),
+		});
+	} catch (error) {
+		throw new AIError.OAuthError(
+			`xAI OIDC discovery failed: ${error instanceof Error ? error.message : String(error)}`,
+			{
+				kind: "discovery",
+				provider: "xai",
+				cause: error,
+			},
+		);
+	}
+	if (response.status !== 200) {
+		throw new AIError.OAuthError(`xAI OIDC discovery returned status ${response.status}.`, {
+			kind: "discovery",
+			provider: "xai",
+			status: response.status,
+		});
+	}
+	let payload: unknown;
+	try {
+		payload = await response.json();
+	} catch (error) {
+		throw new AIError.OAuthError(
+			`xAI OIDC discovery returned invalid JSON: ${error instanceof Error ? error.message : String(error)}`,
+			{ kind: "validation", provider: "xai", cause: error },
+		);
+	}
+	if (!payload || typeof payload !== "object") {
+		throw new AIError.OAuthError("xAI OIDC discovery response was not a JSON object.", {
+			kind: "validation",
+			provider: "xai",
+		});
+	}
+	const obj = payload as Record<string, unknown>;
+	const authorizationEndpoint =
+		typeof obj.authorization_endpoint === "string" ? obj.authorization_endpoint.trim() : "";
+	const tokenEndpoint = typeof obj.token_endpoint === "string" ? obj.token_endpoint.trim() : "";
+	if (!authorizationEndpoint || !tokenEndpoint) {
+		throw new AIError.OAuthError("xAI OIDC discovery response was missing required endpoints.", {
+			kind: "validation",
+			provider: "xai",
+		});
+	}
+	validateXAIEndpoint(authorizationEndpoint, "authorization_endpoint");
+	validateXAIEndpoint(tokenEndpoint, "token_endpoint");
+	return {
+		authorization_endpoint: authorizationEndpoint,
+		token_endpoint: tokenEndpoint,
+	};
+}
+
+/**
+ * Check whether a JWT access token is at or past its `exp` claim (with an
+ * optional refresh-skew margin).
+ *
+ * Hermes `_xai_access_token_is_expiring` L2979-2994. Returns `false` for any
+ * malformed input — this is a refresh-trigger check, not a validation, so
+ * non-JWTs ("no token in cache") must NOT trigger a spurious refresh.
+ */
+export function isXAIAccessTokenExpiring(jwt: string, skewSeconds: number = 0): boolean {
+	try {
+		if (typeof jwt !== "string" || !jwt.includes(".")) return false;
+		const parts = jwt.split(".");
+		if (parts.length < 2) return false;
+		const payloadPart = parts[1];
+		if (!payloadPart) return false;
+		const decoded = Buffer.from(payloadPart, "base64url").toString("utf8");
+		const payload = JSON.parse(decoded) as { exp?: unknown };
+		const exp = payload.exp;
+		if (typeof exp !== "number" || !Number.isFinite(exp)) return false;
+		const now = Math.floor(Date.now() / 1000);
+		const skew = Math.max(0, Math.floor(skewSeconds));
+		return exp <= now + skew;
+	} catch {
+		return false;
+	}
+}
+
+interface BuildXAIAuthorizeUrlOptions {
+	authorizationEndpoint: string;
+	redirectUri: string;
+	codeChallenge: string;
+	state: string;
+	nonce: string;
+}
+
+/**
+ * Build the xAI authorization URL.
+ *
+ * Hermes `_xai_oauth_build_authorize_url` L5286-5312. `plan=generic` opts the
+ * consent screen into xAI's generic OAuth plan tier; without it,
+ * `accounts.x.ai` rejects loopback OAuth from non-allowlisted clients.
+ * `referrer=oh-my-pi` lets xAI attribute oh-my-pi-originated logins in their
+ * OAuth server logs (Hermes uses `referrer=hermes-agent`; oh-my-pi mirrors the
+ * pattern with its own attribution string).
+ */
+function buildXAIAuthorizeUrl(opts: BuildXAIAuthorizeUrlOptions): string {
+	const params = new URLSearchParams({
+		response_type: "code",
+		client_id: XAI_OAUTH_CLIENT_ID,
+		redirect_uri: opts.redirectUri,
+		scope: XAI_OAUTH_SCOPE,
+		code_challenge: opts.codeChallenge,
+		code_challenge_method: "S256",
+		state: opts.state,
+		nonce: opts.nonce,
+		plan: "generic",
+		referrer: "oh-my-pi",
+	});
+	return `${opts.authorizationEndpoint}?${params.toString()}`;
+}
+
+/**
+ * xAI Grok OAuth loopback flow (Hermes `_xai_oauth_loopback_login` L5315-5469).
+ *
+ * Uses a fixed redirect URI so the callback server fails fast instead of
+ * falling back to a random port that xAI's redirect_uri allowlist rejects.
+ */
+export class XAIOAuthFlow extends OAuthCallbackFlow {
+	#verifier: string = "";
+	#fetch: FetchImpl;
+
+	constructor(ctrl: OAuthController) {
+		super(ctrl, {
+			preferredPort: XAI_OAUTH_REDIRECT_PORT,
+			callbackPath: XAI_OAUTH_REDIRECT_PATH,
+			callbackHostname: XAI_OAUTH_REDIRECT_HOST,
+			redirectUri: `http://${XAI_OAUTH_REDIRECT_HOST}:${XAI_OAUTH_REDIRECT_PORT}${XAI_OAUTH_REDIRECT_PATH}`,
+		} satisfies OAuthCallbackFlowOptions);
+		this.#fetch = ctrl.fetch ?? fetch;
+	}
+
+	async generateAuthUrl(state: string, redirectUri: string): Promise<{ url: string; instructions?: string }> {
+		const pkce = await generatePKCE();
+		this.#verifier = pkce.verifier;
+		const nonce = crypto.randomUUID().replace(/-/g, "");
+
+		const discovery = await xaiOAuthDiscovery(DISCOVERY_TIMEOUT_MS, this.#fetch);
+		const url = buildXAIAuthorizeUrl({
+			authorizationEndpoint: discovery.authorization_endpoint,
+			redirectUri,
+			codeChallenge: pkce.challenge,
+			state,
+			nonce,
+		});
+
+		return {
+			url,
+			instructions: `Complete login in your browser for xAI Grok (SuperGrok). Docs: ${XAI_OAUTH_DOCS_URL}`,
+		};
+	}
+
+	async exchangeToken(code: string, _state: string, redirectUri: string): Promise<OAuthCredentials> {
+		const discovery = await xaiOAuthDiscovery(DISCOVERY_TIMEOUT_MS, this.#fetch);
+		const tokenEndpoint = validateXAIEndpoint(discovery.token_endpoint, "token_endpoint");
+
+		const body = new URLSearchParams({
+			grant_type: "authorization_code",
+			client_id: XAI_OAUTH_CLIENT_ID,
+			code,
+			redirect_uri: redirectUri,
+			code_verifier: this.#verifier,
+		});
+
+		const response = await this.#fetch(tokenEndpoint, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/x-www-form-urlencoded",
+				Accept: "application/json",
+			},
+			body,
+			signal: AbortSignal.timeout(TOKEN_REQUEST_TIMEOUT_MS),
+		});
+
+		if (!response.ok) {
+			let detail = "";
+			try {
+				detail = (await response.text()).trim();
+			} catch {
+				// Ignore body-read failures; the status code is the diagnostic.
+			}
+			throw new AIError.OAuthError(`xAI token exchange failed: ${response.status}${detail ? ` ${detail}` : ""}`, {
+				kind: "token-exchange",
+				provider: "xai",
+				status: response.status,
+			});
+		}
+
+		let tokenData: { access_token?: unknown; refresh_token?: unknown; expires_in?: unknown };
+		try {
+			tokenData = (await response.json()) as typeof tokenData;
+		} catch (error) {
+			throw new AIError.OAuthError(
+				`xAI token exchange returned invalid JSON: ${error instanceof Error ? error.message : String(error)}`,
+				{ kind: "validation", provider: "xai", cause: error },
+			);
+		}
+
+		if (typeof tokenData.access_token !== "string" || !tokenData.access_token) {
+			throw new AIError.OAuthError("xAI token exchange response missing access_token", {
+				kind: "validation",
+				provider: "xai",
+			});
+		}
+		if (typeof tokenData.refresh_token !== "string" || !tokenData.refresh_token) {
+			throw new AIError.OAuthError("xAI token exchange response missing refresh_token", {
+				kind: "validation",
+				provider: "xai",
+			});
+		}
+		if (typeof tokenData.expires_in !== "number" || !Number.isFinite(tokenData.expires_in)) {
+			throw new AIError.OAuthError("xAI token exchange response missing expires_in", {
+				kind: "validation",
+				provider: "xai",
+			});
+		}
+
+		return {
+			access: tokenData.access_token,
+			refresh: tokenData.refresh_token,
+			expires: Date.now() + tokenData.expires_in * 1000 - ACCESS_TOKEN_CLIENT_SKEW_MS,
+		};
+	}
+}
+
+/**
+ * Login with xAI Grok OAuth (SuperGrok Subscription).
+ */
+export async function loginXAIOAuth(ctrl: OAuthController): Promise<OAuthCredentials> {
+	return new XAIOAuthFlow(ctrl).login();
+}
+
+/**
+ * Refresh an xAI OAuth access token using a stored refresh_token.
+ *
+ * Hermes `refresh_xai_oauth_pure` L3087-3160. Re-runs OIDC discovery and
+ * re-validates the cached `token_endpoint` on the refresh hot path so a
+ * cached-but-poisoned endpoint cannot silently leak a refresh_token.
+ */
+export async function refreshXAIOAuthToken(refreshToken: string, fetchOverride?: FetchImpl): Promise<OAuthCredentials> {
+	const fetchImpl = fetchOverride ?? fetch;
+	if (typeof refreshToken !== "string" || !refreshToken.trim()) {
+		throw new AIError.OAuthError("missing refresh_token", { kind: "validation", provider: "xai" });
+	}
+
+	const discovery = await xaiOAuthDiscovery(DISCOVERY_TIMEOUT_MS, fetchImpl);
+	const tokenEndpoint = validateXAIEndpoint(discovery.token_endpoint, "token_endpoint");
+
+	const body = new URLSearchParams({
+		grant_type: "refresh_token",
+		client_id: XAI_OAUTH_CLIENT_ID,
+		refresh_token: refreshToken,
+	});
+
+	const response = await fetchImpl(tokenEndpoint, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/x-www-form-urlencoded",
+			Accept: "application/json",
+		},
+		body,
+		signal: AbortSignal.timeout(TOKEN_REQUEST_TIMEOUT_MS),
+	});
+
+	if (!response.ok) {
+		let detail = "";
+		try {
+			detail = (await response.text()).trim();
+		} catch {
+			// Ignore body-read failures; the status code is the diagnostic.
+		}
+		throw new AIError.OAuthError(`xAI token refresh failed: ${response.status}${detail ? ` ${detail}` : ""}`, {
+			kind: "token-refresh",
+			provider: "xai",
+			status: response.status,
+		});
+	}
+
+	let data: { access_token?: unknown; refresh_token?: unknown; expires_in?: unknown };
+	try {
+		data = (await response.json()) as typeof data;
+	} catch (error) {
+		throw new AIError.OAuthError(
+			`xAI token refresh returned invalid JSON: ${error instanceof Error ? error.message : String(error)}`,
+			{ kind: "validation", provider: "xai", cause: error },
+		);
+	}
+
+	if (typeof data.access_token !== "string" || !data.access_token) {
+		throw new AIError.OAuthError("xAI token refresh response missing access_token", {
+			kind: "validation",
+			provider: "xai",
+		});
+	}
+	if (typeof data.expires_in !== "number" || !Number.isFinite(data.expires_in)) {
+		throw new AIError.OAuthError("xAI token refresh response missing expires_in", {
+			kind: "validation",
+			provider: "xai",
+		});
+	}
+
+	const newRefresh = typeof data.refresh_token === "string" && data.refresh_token ? data.refresh_token : refreshToken;
+
+	return {
+		access: data.access_token,
+		refresh: newRefresh,
+		expires: Date.now() + data.expires_in * 1000 - ACCESS_TOKEN_CLIENT_SKEW_MS,
+	};
+}

package/src/registry/oauth/xiaomi.ts

@@ -0,0 +1,211 @@
+/**
+ * Xiaomi MiMo login flow.
+ *
+ * Xiaomi MiMo provides OpenAI-compatible models via
+ * https://api.xiaomimimo.com/v1.
+ *
+ * Standard Xiaomi login opens the pay-as-you-go API key console. Token Plan
+ * login opens plan management so users copy the regional `tp-...` key.
+ */
+
+import * as AIError from "../../error";
+import type { FetchImpl } from "../../types";
+import type { OAuthController } from "./types";
+
+const PROVIDER_ID = "xiaomi";
+const PROVIDER_NAME = "Xiaomi MiMo";
+const STANDARD_AUTH_URL = "https://platform.xiaomimimo.com/#/console/api-keys";
+const TOKEN_PLAN_AUTH_URL = "https://platform.xiaomimimo.com/console/plan-manage";
+const STANDARD_API_BASE_URL = "https://api.xiaomimimo.com/v1";
+const TOKEN_PLAN_KEY_PREFIX = "tp-";
+const STANDARD_VALIDATION_MODEL = "mimo-v2.5";
+const TOKEN_PLAN_VALIDATION_MODEL = "mimo-v2.5";
+const TOKEN_PLAN_SGP_API_BASE_URL = "https://token-plan-sgp.xiaomimimo.com/v1";
+const TOKEN_PLAN_AMS_API_BASE_URL = "https://token-plan-ams.xiaomimimo.com/v1";
+const TOKEN_PLAN_CN_API_BASE_URL = "https://token-plan-cn.xiaomimimo.com/v1";
+
+/** Region codes accepted by the Xiaomi Token Plan login flow. */
+export type XiaomiTokenPlanRegion = "sgp" | "ams" | "cn";
+
+type XiaomiValidationEndpoint = {
+	baseUrl: string;
+	model: string;
+};
+
+const TOKEN_PLAN_VALIDATION_ENDPOINTS: Record<XiaomiTokenPlanRegion, XiaomiValidationEndpoint> = {
+	sgp: { baseUrl: TOKEN_PLAN_SGP_API_BASE_URL, model: TOKEN_PLAN_VALIDATION_MODEL },
+	ams: { baseUrl: TOKEN_PLAN_AMS_API_BASE_URL, model: TOKEN_PLAN_VALIDATION_MODEL },
+	cn: { baseUrl: TOKEN_PLAN_CN_API_BASE_URL, model: TOKEN_PLAN_VALIDATION_MODEL },
+};
+
+const TOKEN_PLAN_REGION_NAMES: Record<XiaomiTokenPlanRegion, string> = {
+	sgp: "Singapore",
+	ams: "Europe",
+	cn: "China",
+};
+
+function isTokenPlanKey(apiKey: string): boolean {
+	return apiKey.startsWith(TOKEN_PLAN_KEY_PREFIX);
+}
+
+const VALIDATION_TIMEOUT_MS = 15_000;
+
+async function validateXiaomiApiKey(
+	apiKey: string,
+	tokenPlanRegion: XiaomiTokenPlanRegion | undefined,
+	signal?: AbortSignal,
+	fetchOverride?: FetchImpl,
+): Promise<void> {
+	const fetchImpl = fetchOverride ?? fetch;
+	// Region-specific Token Plan logins must validate against the selected
+	// cluster. Generic Xiaomi login keeps the historical SGP → AMS → CN fallback.
+	const endpoints = tokenPlanRegion
+		? [TOKEN_PLAN_VALIDATION_ENDPOINTS[tokenPlanRegion]]
+		: isTokenPlanKey(apiKey)
+			? [
+					TOKEN_PLAN_VALIDATION_ENDPOINTS.sgp,
+					TOKEN_PLAN_VALIDATION_ENDPOINTS.ams,
+					TOKEN_PLAN_VALIDATION_ENDPOINTS.cn,
+				]
+			: [{ baseUrl: STANDARD_API_BASE_URL, model: STANDARD_VALIDATION_MODEL }];
+
+	let lastError: Error | null = null;
+
+	for (const ep of endpoints) {
+		// Fresh timeout per endpoint so SGP→AMS fallback works after a regional
+		// timeout: a shared AbortSignal.timeout would stay aborted and instantly
+		// abort the AMS fetch.
+		const timeoutSignal = AbortSignal.timeout(VALIDATION_TIMEOUT_MS);
+		const requestSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+		try {
+			const response = await fetchImpl(`${ep.baseUrl}/chat/completions`, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					Authorization: `Bearer ${apiKey}`,
+				},
+				body: JSON.stringify({
+					model: ep.model,
+					max_tokens: 1,
+					messages: [{ role: "user", content: "ping" }],
+				}),
+				signal: requestSignal,
+			});
+
+			if (response.ok) {
+				return;
+			}
+
+			// 401 means this endpoint didn't accept the key; try the next one
+			if (response.status === 401) {
+				let details = "";
+				try {
+					details = (await response.text()).trim();
+				} catch {
+					// ignore body parse errors, status is enough
+				}
+				lastError = new AIError.OAuthError(
+					details
+						? `${PROVIDER_NAME} API key validation failed (${response.status}): ${details}`
+						: `${PROVIDER_NAME} API key validation failed (${response.status})`,
+					{ kind: "validation", provider: PROVIDER_ID, status: response.status },
+				);
+				continue;
+			}
+
+			// Non-auth errors are real failures
+			let details = "";
+			try {
+				details = (await response.text()).trim();
+			} catch {
+				// ignore body parse errors, status is enough
+			}
+			const message = details
+				? `${PROVIDER_NAME} API key validation failed (${response.status}): ${details}`
+				: `${PROVIDER_NAME} API key validation failed (${response.status})`;
+			throw new AIError.OAuthError(message, {
+				kind: "validation",
+				provider: PROVIDER_ID,
+				status: response.status,
+			});
+		} catch (e) {
+			// Only re-throw AbortError when the caller explicitly cancelled.
+			// Timeout aborts (from AbortSignal.timeout) should fall through to
+			// the next endpoint so SGP→AMS fallback works during regional outages.
+			if (e instanceof DOMException && e.name === "AbortError" && signal?.aborted) {
+				throw e;
+			}
+			lastError = e instanceof Error ? e : new Error(String(e));
+		}
+	}
+	throw (
+		lastError ??
+		new AIError.OAuthError(`${PROVIDER_NAME} API key validation failed`, {
+			kind: "validation",
+			provider: PROVIDER_ID,
+		})
+	);
+}
+
+/**
+ * Login to Xiaomi MiMo.
+ *
+ * Opens browser to API keys page, prompts user to paste their API key.
+ * Returns the API key directly (not OAuthCredentials - this isn't OAuth).
+ */
+export async function loginXiaomi(options: OAuthController): Promise<string> {
+	const fetchImpl = options.fetch ?? fetch;
+	if (!options.onPrompt) {
+		throw new AIError.OnPromptRequiredError(PROVIDER_NAME);
+	}
+	options.onAuth?.({
+		url: STANDARD_AUTH_URL,
+		instructions: "Copy your API key from the Xiaomi MiMo console",
+	});
+	const apiKey = await options.onPrompt({
+		message: "Paste your Xiaomi API key (sk-... or token-plan tp-...)",
+		placeholder: "sk-... or tp-...",
+	});
+	if (options.signal?.aborted) {
+		throw new AIError.LoginCancelledError();
+	}
+	const trimmed = apiKey.trim();
+	if (!trimmed) {
+		throw new AIError.ApiKeyRequiredError();
+	}
+
+	options.onProgress?.(`Validating ${PROVIDER_ID} API key...`);
+	await validateXiaomiApiKey(trimmed, undefined, options.signal, fetchImpl);
+	return trimmed;
+}
+
+/**
+ * Login to a regional Xiaomi Token Plan endpoint.
+ *
+ * Prompts for a token-plan API key and validates it against the selected region.
+ */
+export async function loginXiaomiTokenPlan(options: OAuthController, region: XiaomiTokenPlanRegion): Promise<string> {
+	const fetchImpl = options.fetch ?? fetch;
+	if (!options.onPrompt) {
+		throw new AIError.OnPromptRequiredError(`Xiaomi Token Plan (${TOKEN_PLAN_REGION_NAMES[region]})`);
+	}
+	options.onAuth?.({
+		url: TOKEN_PLAN_AUTH_URL,
+		instructions: `Copy your token-plan API key for the ${TOKEN_PLAN_REGION_NAMES[region]} region`,
+	});
+	const apiKey = await options.onPrompt({
+		message: `Paste your Xiaomi Token Plan ${TOKEN_PLAN_REGION_NAMES[region]} API key (tp-...)`,
+		placeholder: "tp-...",
+	});
+	if (options.signal?.aborted) {
+		throw new AIError.LoginCancelledError();
+	}
+	const trimmed = apiKey.trim();
+	if (!trimmed) {
+		throw new AIError.ApiKeyRequiredError();
+	}
+
+	options.onProgress?.(`Validating Xiaomi Token Plan (${TOKEN_PLAN_REGION_NAMES[region]}) API key...`);
+	await validateXiaomiApiKey(trimmed, region, options.signal, fetchImpl);
+	return trimmed;
+}