dsh-coding-subscription-oauth 0.5.7 → 0.6.0

package/src/oauth-providers.ts

@@ -1,152 +1,152 @@
-/**
- * Native pi-ai OAuth providers and their stable Harness route aliases.
- * @module dsh-coding-subscription-oauth/oauth-providers
- */
-
-import type { Api, ApiKeyAuth, Provider } from "@earendil-works/pi-ai";
-import { anthropicProvider } from "@earendil-works/pi-ai/providers/anthropic";
-import { kimiCodingProvider } from "@earendil-works/pi-ai/providers/kimi-coding";
-import { openaiCodexProvider } from "@earendil-works/pi-ai/providers/openai-codex";
-import {
-	CLAUDE_CODE_OAUTH_AUTH_FILENAME,
-	CLAUDE_CODE_OAUTH_MODELS_CACHE_FILENAME,
-	CLAUDE_CODE_OAUTH_ROUTE,
-	CLAUDE_PI_PROVIDER,
-	CODEX_OAUTH_AUTH_FILENAME,
-	CODEX_OAUTH_MODELS_CACHE_FILENAME,
-	CODEX_OAUTH_ROUTE,
-	CODEX_PI_PROVIDER,
-	type CodingOAuthProviderSlug,
-	KIMI_CODE_OAUTH_AUTH_FILENAME,
-	KIMI_CODE_OAUTH_MODELS_CACHE_FILENAME,
-	KIMI_CODE_OAUTH_ROUTE,
-	KIMI_PI_PROVIDER,
-} from "./ids.ts";
-
-export type SubscriptionProviderSlug = Exclude<CodingOAuthProviderSlug, "grok">;
-export type SubscriptionLoginMethod = "browser" | "device";
-
-export interface OAuthProviderDefinition {
-	slug: SubscriptionProviderSlug;
-	route: string;
-	nativeProviderId: string;
-	displayName: string;
-	authFilename: string;
-	modelsCacheFilename: string;
-	loginMethods: readonly SubscriptionLoginMethod[];
-	recommendedLoginMethod: SubscriptionLoginMethod;
-	providerFactory(): Provider<Api>;
-	requestProvider(selectedIds?: readonly string[]): Provider<Api>;
-}
-
-function requestTokenAuth(name: string, bearerHeader: boolean): ApiKeyAuth {
-	return {
-		name,
-		resolve: async ({ credential }) => {
-			const token = credential?.key?.trim();
-			if (token === undefined || token.length === 0) return undefined;
-			return bearerHeader
-				? { auth: { headers: { Authorization: `Bearer ${token}` } }, source: "OAuth bridge" }
-				: { auth: { apiKey: token }, source: "OAuth bridge" };
-		},
-	};
-}
-
-function selectedProvider(
-	base: Provider<Api>,
-	selectedIds: readonly string[] | undefined,
-	apiKey: ApiKeyAuth | undefined,
-): Provider<Api> {
-	const selected = selectedIds === undefined || selectedIds.length === 0 ? undefined : new Set(selectedIds);
-	return {
-		...base,
-		auth: apiKey === undefined ? base.auth : { ...base.auth, apiKey },
-		getModels: () => {
-			const models = base.getModels();
-			return selected === undefined ? models : models.filter((model) => selected.has(model.id));
-		},
-	};
-}
-
-/** Remove the transport-only `apiKey` carrier without reintroducing it as an explicit undefined. */
-function withoutApiKey<T extends { apiKey?: unknown }>(options: T): T {
-	const { apiKey: _dropped, ...rest } = options;
-	return rest as T;
-}
-
-/**
- * PiAiAdapter's api-key resolver seam necessarily populates `options.apiKey`.
- * Kimi OAuth is header-owned Bearer auth, so remove that transport-only carrier
- * after Models has derived Authorization and before the Anthropic client sees
- * it (otherwise the SDK also emits an invalid x-api-key header).
- */
-function stripApiKeyBeforeStream(provider: Provider<Api>): Provider<Api> {
-	return {
-		...provider,
-		stream: (model, context, options) =>
-			provider.stream(model, context, options === undefined ? undefined : withoutApiKey(options)),
-		streamSimple: (model, context, options) =>
-			provider.streamSimple(model, context, options === undefined ? undefined : withoutApiKey(options)),
-	};
-}
-
-function asProvider(factory: () => Provider): () => Provider<Api> {
-	return factory as () => Provider<Api>;
-}
-
-const createCodexProvider = asProvider(openaiCodexProvider);
-const createKimiProvider = asProvider(kimiCodingProvider);
-const createClaudeProvider = asProvider(anthropicProvider);
-
-export const CODEX_OAUTH_PROVIDER: OAuthProviderDefinition = {
-	slug: "codex",
-	route: CODEX_OAUTH_ROUTE,
-	nativeProviderId: CODEX_PI_PROVIDER,
-	displayName: "OpenAI Codex (ChatGPT Plus/Pro)",
-	authFilename: CODEX_OAUTH_AUTH_FILENAME,
-	modelsCacheFilename: CODEX_OAUTH_MODELS_CACHE_FILENAME,
-	loginMethods: ["device", "browser"],
-	recommendedLoginMethod: "device",
-	providerFactory: createCodexProvider,
-	requestProvider: (selectedIds) =>
-		selectedProvider(createCodexProvider(), selectedIds, requestTokenAuth("OpenAI Codex OAuth token", false)),
-};
-
-export const KIMI_CODE_OAUTH_PROVIDER: OAuthProviderDefinition = {
-	slug: "kimi",
-	route: KIMI_CODE_OAUTH_ROUTE,
-	nativeProviderId: KIMI_PI_PROVIDER,
-	displayName: "Kimi Code (subscription)",
-	authFilename: KIMI_CODE_OAUTH_AUTH_FILENAME,
-	modelsCacheFilename: KIMI_CODE_OAUTH_MODELS_CACHE_FILENAME,
-	loginMethods: ["device"],
-	recommendedLoginMethod: "device",
-	providerFactory: createKimiProvider,
-	requestProvider: (selectedIds) =>
-		stripApiKeyBeforeStream(
-			selectedProvider(createKimiProvider(), selectedIds, requestTokenAuth("Kimi Code OAuth token", true)),
-		),
-};
-
-export const CLAUDE_CODE_OAUTH_PROVIDER: OAuthProviderDefinition = {
-	slug: "claude",
-	route: CLAUDE_CODE_OAUTH_ROUTE,
-	nativeProviderId: CLAUDE_PI_PROVIDER,
-	displayName: "Claude Code (Pro/Max)",
-	authFilename: CLAUDE_CODE_OAUTH_AUTH_FILENAME,
-	modelsCacheFilename: CLAUDE_CODE_OAUTH_MODELS_CACHE_FILENAME,
-	loginMethods: ["browser"],
-	recommendedLoginMethod: "browser",
-	providerFactory: createClaudeProvider,
-	requestProvider: (selectedIds) => selectedProvider(createClaudeProvider(), selectedIds, undefined),
-};
-
-export const OAUTH_PROVIDER_DEFINITIONS = [
-	CODEX_OAUTH_PROVIDER,
-	KIMI_CODE_OAUTH_PROVIDER,
-	CLAUDE_CODE_OAUTH_PROVIDER,
-] as const;
-
-export function oauthProviderDefinition(slug: string): OAuthProviderDefinition | undefined {
-	return OAUTH_PROVIDER_DEFINITIONS.find((provider) => provider.slug === slug);
-}
+/**
+ * Native pi-ai OAuth providers and their stable Harness route aliases.
+ * @module dsh-coding-subscription-oauth/oauth-providers
+ */
+
+import type { Api, ApiKeyAuth, Provider } from "@earendil-works/pi-ai";
+import { anthropicProvider } from "@earendil-works/pi-ai/providers/anthropic";
+import { kimiCodingProvider } from "@earendil-works/pi-ai/providers/kimi-coding";
+import { openaiCodexProvider } from "@earendil-works/pi-ai/providers/openai-codex";
+import {
+	CLAUDE_CODE_OAUTH_AUTH_FILENAME,
+	CLAUDE_CODE_OAUTH_MODELS_CACHE_FILENAME,
+	CLAUDE_CODE_OAUTH_ROUTE,
+	CLAUDE_PI_PROVIDER,
+	CODEX_OAUTH_AUTH_FILENAME,
+	CODEX_OAUTH_MODELS_CACHE_FILENAME,
+	CODEX_OAUTH_ROUTE,
+	CODEX_PI_PROVIDER,
+	type CodingOAuthProviderSlug,
+	KIMI_CODE_OAUTH_AUTH_FILENAME,
+	KIMI_CODE_OAUTH_MODELS_CACHE_FILENAME,
+	KIMI_CODE_OAUTH_ROUTE,
+	KIMI_PI_PROVIDER,
+} from "./ids.ts";
+
+export type SubscriptionProviderSlug = Exclude<CodingOAuthProviderSlug, "grok">;
+export type SubscriptionLoginMethod = "browser" | "device";
+
+export interface OAuthProviderDefinition {
+	slug: SubscriptionProviderSlug;
+	route: string;
+	nativeProviderId: string;
+	displayName: string;
+	authFilename: string;
+	modelsCacheFilename: string;
+	loginMethods: readonly SubscriptionLoginMethod[];
+	recommendedLoginMethod: SubscriptionLoginMethod;
+	providerFactory(): Provider<Api>;
+	requestProvider(selectedIds?: readonly string[]): Provider<Api>;
+}
+
+function requestTokenAuth(name: string, bearerHeader: boolean): ApiKeyAuth {
+	return {
+		name,
+		resolve: async ({ credential }) => {
+			const token = credential?.key?.trim();
+			if (token === undefined || token.length === 0) return undefined;
+			return bearerHeader
+				? { auth: { headers: { Authorization: `Bearer ${token}` } }, source: "OAuth bridge" }
+				: { auth: { apiKey: token }, source: "OAuth bridge" };
+		},
+	};
+}
+
+function selectedProvider(
+	base: Provider<Api>,
+	selectedIds: readonly string[] | undefined,
+	apiKey: ApiKeyAuth | undefined,
+): Provider<Api> {
+	const selected = selectedIds === undefined || selectedIds.length === 0 ? undefined : new Set(selectedIds);
+	return {
+		...base,
+		auth: apiKey === undefined ? base.auth : { ...base.auth, apiKey },
+		getModels: () => {
+			const models = base.getModels();
+			return selected === undefined ? models : models.filter((model) => selected.has(model.id));
+		},
+	};
+}
+
+/** Remove the transport-only `apiKey` carrier without reintroducing it as an explicit undefined. */
+function withoutApiKey<T extends { apiKey?: unknown }>(options: T): T {
+	const { apiKey: _dropped, ...rest } = options;
+	return rest as T;
+}
+
+/**
+ * PiAiAdapter's api-key resolver seam necessarily populates `options.apiKey`.
+ * Kimi OAuth is header-owned Bearer auth, so remove that transport-only carrier
+ * after Models has derived Authorization and before the Anthropic client sees
+ * it (otherwise the SDK also emits an invalid x-api-key header).
+ */
+function stripApiKeyBeforeStream(provider: Provider<Api>): Provider<Api> {
+	return {
+		...provider,
+		stream: (model, context, options) =>
+			provider.stream(model, context, options === undefined ? undefined : withoutApiKey(options)),
+		streamSimple: (model, context, options) =>
+			provider.streamSimple(model, context, options === undefined ? undefined : withoutApiKey(options)),
+	};
+}
+
+function asProvider(factory: () => Provider): () => Provider<Api> {
+	return factory as () => Provider<Api>;
+}
+
+const createCodexProvider = asProvider(openaiCodexProvider);
+const createKimiProvider = asProvider(kimiCodingProvider);
+const createClaudeProvider = asProvider(anthropicProvider);
+
+export const CODEX_OAUTH_PROVIDER: OAuthProviderDefinition = {
+	slug: "codex",
+	route: CODEX_OAUTH_ROUTE,
+	nativeProviderId: CODEX_PI_PROVIDER,
+	displayName: "OpenAI Codex (ChatGPT Plus/Pro)",
+	authFilename: CODEX_OAUTH_AUTH_FILENAME,
+	modelsCacheFilename: CODEX_OAUTH_MODELS_CACHE_FILENAME,
+	loginMethods: ["device", "browser"],
+	recommendedLoginMethod: "device",
+	providerFactory: createCodexProvider,
+	requestProvider: (selectedIds) =>
+		selectedProvider(createCodexProvider(), selectedIds, requestTokenAuth("OpenAI Codex OAuth token", false)),
+};
+
+export const KIMI_CODE_OAUTH_PROVIDER: OAuthProviderDefinition = {
+	slug: "kimi",
+	route: KIMI_CODE_OAUTH_ROUTE,
+	nativeProviderId: KIMI_PI_PROVIDER,
+	displayName: "Kimi Code (subscription)",
+	authFilename: KIMI_CODE_OAUTH_AUTH_FILENAME,
+	modelsCacheFilename: KIMI_CODE_OAUTH_MODELS_CACHE_FILENAME,
+	loginMethods: ["device"],
+	recommendedLoginMethod: "device",
+	providerFactory: createKimiProvider,
+	requestProvider: (selectedIds) =>
+		stripApiKeyBeforeStream(
+			selectedProvider(createKimiProvider(), selectedIds, requestTokenAuth("Kimi Code OAuth token", true)),
+		),
+};
+
+export const CLAUDE_CODE_OAUTH_PROVIDER: OAuthProviderDefinition = {
+	slug: "claude",
+	route: CLAUDE_CODE_OAUTH_ROUTE,
+	nativeProviderId: CLAUDE_PI_PROVIDER,
+	displayName: "Claude Code (Pro/Max)",
+	authFilename: CLAUDE_CODE_OAUTH_AUTH_FILENAME,
+	modelsCacheFilename: CLAUDE_CODE_OAUTH_MODELS_CACHE_FILENAME,
+	loginMethods: ["browser"],
+	recommendedLoginMethod: "browser",
+	providerFactory: createClaudeProvider,
+	requestProvider: (selectedIds) => selectedProvider(createClaudeProvider(), selectedIds, undefined),
+};
+
+export const OAUTH_PROVIDER_DEFINITIONS = [
+	CODEX_OAUTH_PROVIDER,
+	KIMI_CODE_OAUTH_PROVIDER,
+	CLAUDE_CODE_OAUTH_PROVIDER,
+] as const;
+
+export function oauthProviderDefinition(slug: string): OAuthProviderDefinition | undefined {
+	return OAUTH_PROVIDER_DEFINITIONS.find((provider) => provider.slug === slug);
+}

package/src/oauth-session.ts

@@ -1,183 +1,183 @@
-/**
- * Persistent OAuth session and static model selection for one subscription provider.
- * @module dsh-coding-subscription-oauth/oauth-session
- */
-
-import { mkdir, readFile, rm } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
-import { writeFileAtomic } from "@deepseek-ai/dsh-atomic-write";
-import { resolveDshHome } from "@deepseek-ai/dsh-home-paths";
-import type {
-	Api,
-	AuthInteraction,
-	Credential,
-	Model,
-	MutableModels,
-	OAuthCredential,
-	Provider,
-} from "@earendil-works/pi-ai";
-import { createModels } from "@earendil-works/pi-ai";
-import type { OAuthProviderDefinition } from "./oauth-providers.ts";
-import { OAuthCredentialFileStore, oauthCredentialPath } from "./store.ts";
-
-const MODELS_CACHE_VERSION = 1;
-
-interface ModelsCacheDocument {
-	version: typeof MODELS_CACHE_VERSION;
-	selected: string[];
-}
-
-function isENOENT(error: unknown): boolean {
-	return (error as NodeJS.ErrnoException | null)?.code === "ENOENT";
-}
-
-function parseIdList(value: unknown): string[] {
-	if (!Array.isArray(value)) return [];
-	return [...new Set(value.filter((id): id is string => typeof id === "string" && id.length > 0))];
-}
-
-function parseCache(text: string): string[] | undefined {
-	let value: unknown;
-	try {
-		value = JSON.parse(text);
-	} catch {
-		return undefined;
-	}
-	if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
-	const document = value as Record<string, unknown>;
-	if (document["version"] !== MODELS_CACHE_VERSION) return undefined;
-	const selected = parseIdList(document["selected"]);
-	return selected.length === 0 ? undefined : selected;
-}
-
-export function oauthModelsCachePath(basename: string, dshHome?: string): string {
-	return resolve(join(resolveDshHome(dshHome), basename));
-}
-
-export interface OAuthProviderStatus {
-	authenticated: boolean;
-	expiresAt?: number;
-}
-
-export class OAuthProviderSession {
-	readonly store: OAuthCredentialFileStore;
-	readonly models: MutableModels;
-	private readonly catalog: readonly Model<Api>[];
-	private readonly cacheFile: string;
-	private selectedIds: string[] | undefined;
-
-	constructor(
-		readonly definition: OAuthProviderDefinition,
-		onCatalogChange?: () => void,
-		store: OAuthCredentialFileStore = new OAuthCredentialFileStore(
-			definition.nativeProviderId,
-			oauthCredentialPath(definition.authFilename),
-			definition.route,
-		),
-		cacheFile: string = oauthModelsCachePath(definition.modelsCacheFilename),
-	) {
-		this.store = store;
-		this.cacheFile = resolve(cacheFile);
-		const provider = definition.providerFactory();
-		this.catalog = [...provider.getModels()];
-		this.models = createModels({ credentials: store });
-		this.models.setProvider(provider);
-		this.onCatalogChange = onCatalogChange;
-	}
-
-	private onCatalogChange: (() => void) | undefined;
-
-	availableModels(): Model<Api>[] {
-		return [...this.catalog];
-	}
-
-	selectedModelIds(): string[] | undefined {
-		return this.selectedIds === undefined ? undefined : [...this.selectedIds];
-	}
-
-	visibleModels(): Model<Api>[] {
-		if (this.selectedIds === undefined || this.selectedIds.length === 0) return this.availableModels();
-		const byId = new Map(this.catalog.map((model) => [model.id, model]));
-		return this.selectedIds.flatMap((id) => {
-			const model = byId.get(id);
-			return model === undefined ? [] : [model];
-		});
-	}
-
-	provider(): Provider {
-		return this.definition.requestProvider(this.visibleModels().map((model) => model.id));
-	}
-
-	async loadCachedModels(): Promise<void> {
-		try {
-			this.selectedIds = parseCache(await readFile(this.cacheFile, "utf8"));
-		} catch (error) {
-			if (!isENOENT(error)) throw error;
-		}
-	}
-
-	async setSelectedModels(ids: readonly string[]): Promise<void> {
-		const available = new Set(this.catalog.map((model) => model.id));
-		const selected = [...new Set(ids.filter((id) => available.has(id)))];
-		this.selectedIds = selected.length === 0 ? undefined : selected;
-		await this.writeCache();
-		this.onCatalogChange?.();
-	}
-
-	async status(): Promise<OAuthProviderStatus> {
-		const credential = await this.store.read(this.definition.nativeProviderId);
-		if (credential?.type !== "oauth") return { authenticated: false };
-		return { authenticated: true, expiresAt: credential.expires };
-	}
-
-	async login(interaction: AuthInteraction): Promise<Credential> {
-		const credential = await this.models.login(this.definition.nativeProviderId, "oauth", interaction);
-		this.onCatalogChange?.();
-		return credential;
-	}
-
-	async resolveAccessToken(): Promise<string | undefined> {
-		const resolved = await this.models.getAuth(this.definition.nativeProviderId);
-		if (resolved === undefined) return undefined;
-		const credential = await this.store.read(this.definition.nativeProviderId);
-		return credential?.type === "oauth" ? credential.access : undefined;
-	}
-
-	/**
-	 * Backdate the stored token's expiry so the next `getAuth()` refreshes.
-	 * Called after an upstream 401 rejected a locally-valid token.
-	 */
-	async invalidateAccessToken(): Promise<void> {
-		await this.store.invalidate(this.definition.nativeProviderId);
-	}
-
-	async storedCredential(): Promise<OAuthCredential | undefined> {
-		const credential = await this.store.read(this.definition.nativeProviderId);
-		return credential?.type === "oauth" ? credential : undefined;
-	}
-
-	async logout(): Promise<void> {
-		try {
-			await this.models.logout(this.definition.nativeProviderId);
-			this.selectedIds = undefined;
-			await mkdir(dirname(this.cacheFile), { recursive: true, mode: 0o700 });
-			await rm(this.cacheFile, { force: true });
-		} finally {
-			// Credential deletion may succeed before cache cleanup fails. Always
-			// refresh discovery so an open selector cannot retain stale models.
-			this.onCatalogChange?.();
-		}
-	}
-
-	private async writeCache(): Promise<void> {
-		const document: ModelsCacheDocument = {
-			version: MODELS_CACHE_VERSION,
-			selected: this.selectedIds === undefined ? [] : [...this.selectedIds],
-		};
-		await mkdir(dirname(this.cacheFile), { recursive: true, mode: 0o700 });
-		await writeFileAtomic(this.cacheFile, `${JSON.stringify(document)}\n`, {
-			mode: 0o600,
-			dirMode: 0o700,
-		});
-	}
-}
+/**
+ * Persistent OAuth session and static model selection for one subscription provider.
+ * @module dsh-coding-subscription-oauth/oauth-session
+ */
+
+import { mkdir, readFile, rm } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { writeFileAtomic } from "@deepseek-ai/dsh-atomic-write";
+import { resolveDshHome } from "@deepseek-ai/dsh-home-paths";
+import type {
+	Api,
+	AuthInteraction,
+	Credential,
+	Model,
+	MutableModels,
+	OAuthCredential,
+	Provider,
+} from "@earendil-works/pi-ai";
+import { createModels } from "@earendil-works/pi-ai";
+import type { OAuthProviderDefinition } from "./oauth-providers.ts";
+import { OAuthCredentialFileStore, oauthCredentialPath } from "./store.ts";
+
+const MODELS_CACHE_VERSION = 1;
+
+interface ModelsCacheDocument {
+	version: typeof MODELS_CACHE_VERSION;
+	selected: string[];
+}
+
+function isENOENT(error: unknown): boolean {
+	return (error as NodeJS.ErrnoException | null)?.code === "ENOENT";
+}
+
+function parseIdList(value: unknown): string[] {
+	if (!Array.isArray(value)) return [];
+	return [...new Set(value.filter((id): id is string => typeof id === "string" && id.length > 0))];
+}
+
+function parseCache(text: string): string[] | undefined {
+	let value: unknown;
+	try {
+		value = JSON.parse(text);
+	} catch {
+		return undefined;
+	}
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+	const document = value as Record<string, unknown>;
+	if (document["version"] !== MODELS_CACHE_VERSION) return undefined;
+	const selected = parseIdList(document["selected"]);
+	return selected.length === 0 ? undefined : selected;
+}
+
+export function oauthModelsCachePath(basename: string, dshHome?: string): string {
+	return resolve(join(resolveDshHome(dshHome), basename));
+}
+
+export interface OAuthProviderStatus {
+	authenticated: boolean;
+	expiresAt?: number;
+}
+
+export class OAuthProviderSession {
+	readonly store: OAuthCredentialFileStore;
+	readonly models: MutableModels;
+	private readonly catalog: readonly Model<Api>[];
+	private readonly cacheFile: string;
+	private selectedIds: string[] | undefined;
+
+	constructor(
+		readonly definition: OAuthProviderDefinition,
+		onCatalogChange?: () => void,
+		store: OAuthCredentialFileStore = new OAuthCredentialFileStore(
+			definition.nativeProviderId,
+			oauthCredentialPath(definition.authFilename),
+			definition.route,
+		),
+		cacheFile: string = oauthModelsCachePath(definition.modelsCacheFilename),
+	) {
+		this.store = store;
+		this.cacheFile = resolve(cacheFile);
+		const provider = definition.providerFactory();
+		this.catalog = [...provider.getModels()];
+		this.models = createModels({ credentials: store });
+		this.models.setProvider(provider);
+		this.onCatalogChange = onCatalogChange;
+	}
+
+	private onCatalogChange: (() => void) | undefined;
+
+	availableModels(): Model<Api>[] {
+		return [...this.catalog];
+	}
+
+	selectedModelIds(): string[] | undefined {
+		return this.selectedIds === undefined ? undefined : [...this.selectedIds];
+	}
+
+	visibleModels(): Model<Api>[] {
+		if (this.selectedIds === undefined || this.selectedIds.length === 0) return this.availableModels();
+		const byId = new Map(this.catalog.map((model) => [model.id, model]));
+		return this.selectedIds.flatMap((id) => {
+			const model = byId.get(id);
+			return model === undefined ? [] : [model];
+		});
+	}
+
+	provider(): Provider {
+		return this.definition.requestProvider(this.visibleModels().map((model) => model.id));
+	}
+
+	async loadCachedModels(): Promise<void> {
+		try {
+			this.selectedIds = parseCache(await readFile(this.cacheFile, "utf8"));
+		} catch (error) {
+			if (!isENOENT(error)) throw error;
+		}
+	}
+
+	async setSelectedModels(ids: readonly string[]): Promise<void> {
+		const available = new Set(this.catalog.map((model) => model.id));
+		const selected = [...new Set(ids.filter((id) => available.has(id)))];
+		this.selectedIds = selected.length === 0 ? undefined : selected;
+		await this.writeCache();
+		this.onCatalogChange?.();
+	}
+
+	async status(): Promise<OAuthProviderStatus> {
+		const credential = await this.store.read(this.definition.nativeProviderId);
+		if (credential?.type !== "oauth") return { authenticated: false };
+		return { authenticated: true, expiresAt: credential.expires };
+	}
+
+	async login(interaction: AuthInteraction): Promise<Credential> {
+		const credential = await this.models.login(this.definition.nativeProviderId, "oauth", interaction);
+		this.onCatalogChange?.();
+		return credential;
+	}
+
+	async resolveAccessToken(): Promise<string | undefined> {
+		const resolved = await this.models.getAuth(this.definition.nativeProviderId);
+		if (resolved === undefined) return undefined;
+		const credential = await this.store.read(this.definition.nativeProviderId);
+		return credential?.type === "oauth" ? credential.access : undefined;
+	}
+
+	/**
+	 * Backdate the stored token's expiry so the next `getAuth()` refreshes.
+	 * Called after an upstream 401 rejected a locally-valid token.
+	 */
+	async invalidateAccessToken(): Promise<void> {
+		await this.store.invalidate(this.definition.nativeProviderId);
+	}
+
+	async storedCredential(): Promise<OAuthCredential | undefined> {
+		const credential = await this.store.read(this.definition.nativeProviderId);
+		return credential?.type === "oauth" ? credential : undefined;
+	}
+
+	async logout(): Promise<void> {
+		try {
+			await this.models.logout(this.definition.nativeProviderId);
+			this.selectedIds = undefined;
+			await mkdir(dirname(this.cacheFile), { recursive: true, mode: 0o700 });
+			await rm(this.cacheFile, { force: true });
+		} finally {
+			// Credential deletion may succeed before cache cleanup fails. Always
+			// refresh discovery so an open selector cannot retain stale models.
+			this.onCatalogChange?.();
+		}
+	}
+
+	private async writeCache(): Promise<void> {
+		const document: ModelsCacheDocument = {
+			version: MODELS_CACHE_VERSION,
+			selected: this.selectedIds === undefined ? [] : [...this.selectedIds],
+		};
+		await mkdir(dirname(this.cacheFile), { recursive: true, mode: 0o700 });
+		await writeFileAtomic(this.cacheFile, `${JSON.stringify(document)}\n`, {
+			mode: 0o600,
+			dirMode: 0o700,
+		});
+	}
+}