byterover-cli 2.2.0 → 2.3.1

package/dist/server/infra/provider-oauth/token-refresh-manager.js

@@ -0,0 +1,96 @@
+import { getProviderById } from '../../core/domain/entities/provider-registry.js';
+import { TransportDaemonEventNames } from '../../core/domain/transport/schemas.js';
+import { processLog } from '../../utils/process-logger.js';
+import { isPermanentOAuthError } from './errors.js';
+import { exchangeRefreshToken as defaultExchangeRefreshToken } from './refresh-token-exchange.js';
+import { computeExpiresAt } from './types.js';
+/** Refresh tokens when they expire within this threshold */
+export const REFRESH_THRESHOLD_MS = 5 * 60 * 1000;
+/**
+ * Manages automatic OAuth token refresh for providers.
+ *
+ * Called by resolveProviderConfig() before returning config to agents.
+ * If a token is expiring within 5 minutes, exchanges the refresh token
+ * for a new access token. On failure, disconnects the provider.
+ */
+export class TokenRefreshManager {
+    deps;
+    exchangeRefreshToken;
+    /** Per-provider mutex to serialize concurrent refresh attempts */
+    pendingRefreshes = new Map();
+    constructor(deps) {
+        this.deps = deps;
+        this.exchangeRefreshToken = deps.exchangeRefreshToken ?? defaultExchangeRefreshToken;
+    }
+    async refreshIfNeeded(providerId) {
+        // Serialize concurrent refreshes for the same provider
+        const pending = this.pendingRefreshes.get(providerId);
+        if (pending) {
+            return pending;
+        }
+        const promise = this.doRefresh(providerId).finally(() => {
+            this.pendingRefreshes.delete(providerId);
+        });
+        this.pendingRefreshes.set(providerId, promise);
+        return promise;
+    }
+    async doRefresh(providerId) {
+        // 1. Check if provider is OAuth-connected
+        const config = await this.deps.providerConfigStore.read();
+        const providerConfig = config.providers[providerId];
+        if (providerConfig?.authMethod !== 'oauth') {
+            return true;
+        }
+        // 2. Get token record from encrypted store
+        const tokenRecord = await this.deps.providerOAuthTokenStore.get(providerId);
+        if (!tokenRecord) {
+            return false;
+        }
+        // 3. Check if refresh is needed
+        const expiresAt = new Date(tokenRecord.expiresAt).getTime();
+        const timeUntilExpiry = expiresAt - Date.now();
+        if (timeUntilExpiry > REFRESH_THRESHOLD_MS) {
+            return true;
+        }
+        // 4. Look up provider OAuth config
+        const providerDef = getProviderById(providerId);
+        if (!providerDef?.oauth) {
+            return false;
+        }
+        const oauthConfig = providerDef.oauth;
+        const contentType = oauthConfig.tokenContentType === 'form' ? 'application/x-www-form-urlencoded' : 'application/json';
+        // 5. Attempt refresh
+        try {
+            const tokens = await this.exchangeRefreshToken({
+                clientId: oauthConfig.clientId,
+                contentType,
+                refreshToken: tokenRecord.refreshToken,
+                tokenUrl: oauthConfig.tokenUrl,
+            });
+            // 6. Success: update keychain + encrypted store
+            await this.deps.providerKeychainStore.setApiKey(providerId, tokens.access_token);
+            const newExpiresAt = tokens.expires_in ? computeExpiresAt(tokens.expires_in) : tokenRecord.expiresAt;
+            await this.deps.providerOAuthTokenStore.set(providerId, {
+                expiresAt: newExpiresAt,
+                refreshToken: tokens.refresh_token ?? tokenRecord.refreshToken,
+            });
+            this.deps.transport.broadcast(TransportDaemonEventNames.PROVIDER_UPDATED, {});
+            return true;
+        }
+        catch (error) {
+            // 7. Permanent failure (token revoked, client invalid): disconnect provider, clean up
+            if (isPermanentOAuthError(error)) {
+                await this.deps.providerConfigStore.disconnectProvider(providerId).catch(() => { });
+                await this.deps.providerOAuthTokenStore.delete(providerId).catch(() => { });
+                await this.deps.providerKeychainStore.deleteApiKey(providerId).catch(() => { });
+                this.deps.transport.broadcast(TransportDaemonEventNames.PROVIDER_UPDATED, {});
+                return false;
+            }
+            // Transient errors (network timeout, 5xx): keep credentials intact.
+            // Return true so the caller uses the existing access token from the keychain,
+            // which may still be valid until it actually expires.
+            processLog(`[TokenRefreshManager] Transient refresh error for ${providerId}: ${error instanceof Error ? error.message : String(error)}`);
+            return true;
+        }
+    }
+}

package/dist/server/infra/provider-oauth/types.d.ts

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+export type ProviderCallbackResult = {
+    code: string;
+    state: string;
+};
+export type PkceParameters = {
+    codeChallenge: string;
+    codeVerifier: string;
+    state: string;
+};
+export type TokenRequestContentType = 'application/json' | 'application/x-www-form-urlencoded';
+/**
+ * Raw token response from an OAuth provider.
+ * Fields are snake_case per OAuth 2.0 spec (RFC 6749).
+ */
+export declare const ProviderTokenResponseSchema: z.ZodObject<{
+    access_token: z.ZodString;
+    expires_in: z.ZodOptional<z.ZodNumber>;
+    id_token: z.ZodOptional<z.ZodString>;
+    refresh_token: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodString>;
+    token_type: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    access_token: string;
+    scope?: string | undefined;
+    refresh_token?: string | undefined;
+    expires_in?: number | undefined;
+    id_token?: string | undefined;
+    token_type?: string | undefined;
+}, {
+    access_token: string;
+    scope?: string | undefined;
+    refresh_token?: string | undefined;
+    expires_in?: number | undefined;
+    id_token?: string | undefined;
+    token_type?: string | undefined;
+}>;
+export type ProviderTokenResponse = z.infer<typeof ProviderTokenResponseSchema>;
+export type RefreshTokenExchangeParams = {
+    clientId: string;
+    contentType: TokenRequestContentType;
+    refreshToken: string;
+    tokenUrl: string;
+};
+export type TokenExchangeParams = {
+    clientId: string;
+    clientSecret?: string;
+    code: string;
+    codeVerifier: string;
+    contentType: TokenRequestContentType;
+    redirectUri: string;
+    tokenUrl: string;
+};
+/** Compute an ISO 8601 expiry timestamp from an OAuth expires_in value (seconds). */
+export declare function computeExpiresAt(expiresInSeconds: number): string;

package/dist/server/infra/provider-oauth/types.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+/**
+ * Raw token response from an OAuth provider.
+ * Fields are snake_case per OAuth 2.0 spec (RFC 6749).
+ */
+export const ProviderTokenResponseSchema = z.object({
+    // eslint-disable-next-line camelcase
+    access_token: z.string().min(1),
+    // eslint-disable-next-line camelcase
+    expires_in: z.number().optional(),
+    // eslint-disable-next-line camelcase
+    id_token: z.string().optional(),
+    // eslint-disable-next-line camelcase
+    refresh_token: z.string().optional(),
+    scope: z.string().optional(),
+    // eslint-disable-next-line camelcase
+    token_type: z.string().optional(),
+});
+/** Compute an ISO 8601 expiry timestamp from an OAuth expires_in value (seconds). */
+export function computeExpiresAt(expiresInSeconds) {
+    return new Date(Date.now() + expiresInSeconds * 1000).toISOString();
+}

package/dist/server/infra/storage/file-provider-config-store.d.ts

@@ -31,7 +31,9 @@ export declare class FileProviderConfigStore implements IProviderConfigStore {
      */
     connectProvider(providerId: string, options?: {
         activeModel?: string;
+        authMethod?: 'api-key' | 'oauth';
         baseUrl?: string;
+        oauthAccountId?: string;
     }): Promise<void>;
     /**
      * Removes a provider connection.

package/dist/server/infra/storage/file-provider-config-store.js

@@ -38,9 +38,7 @@ export class FileProviderConfigStore {
      */
     async connectProvider(providerId, options) {
         const config = await this.read();
-        const newConfig = config
-            .withProviderConnected(providerId, options)
-            .withActiveProvider(providerId);
+        const newConfig = config.withProviderConnected(providerId, options).withActiveProvider(providerId);
         await this.write(newConfig);
     }
     /**

package/dist/server/infra/transport/handlers/model-handler.d.ts

@@ -1,7 +1,9 @@
 import type { IProviderConfigStore } from '../../../core/interfaces/i-provider-config-store.js';
 import type { IProviderKeychainStore } from '../../../core/interfaces/i-provider-keychain-store.js';
+import type { IProviderModelFetcher } from '../../../core/interfaces/i-provider-model-fetcher.js';
 import type { ITransportServer } from '../../../core/interfaces/transport/i-transport-server.js';
 export interface ModelHandlerDeps {
+    getModelFetcher?: (providerId: string) => Promise<IProviderModelFetcher | undefined>;
     providerConfigStore: IProviderConfigStore;
     providerKeychainStore: IProviderKeychainStore;
     transport: ITransportServer;
@@ -11,6 +13,7 @@ export interface ModelHandlerDeps {
  * Business logic for model listing and selection — no terminal/UI calls.
  */
 export declare class ModelHandler {
+    private readonly getModelFetcher;
     private readonly providerConfigStore;
     private readonly providerKeychainStore;
     private readonly transport;

package/dist/server/infra/transport/handlers/model-handler.js

@@ -1,15 +1,17 @@
 import { ModelEvents, } from '../../../../shared/transport/events/model-events.js';
 import { TransportDaemonEventNames } from '../../../core/domain/transport/schemas.js';
-import { getModelFetcher } from '../../http/provider-model-fetcher-registry.js';
+import { getModelFetcher as getModelFetcherDefault } from '../../http/provider-model-fetcher-registry.js';
 /**
  * Handles model:* events.
  * Business logic for model listing and selection — no terminal/UI calls.
  */
 export class ModelHandler {
+    getModelFetcher;
     providerConfigStore;
     providerKeychainStore;
     transport;
     constructor(deps) {
+        this.getModelFetcher = deps.getModelFetcher ?? getModelFetcherDefault;
         this.providerConfigStore = deps.providerConfigStore;
         this.providerKeychainStore = deps.providerKeychainStore;
         this.transport = deps.transport;
@@ -22,18 +24,21 @@ export class ModelHandler {
     setupList() {
         this.transport.onRequest(ModelEvents.LIST, async (data) => {
             const { providerId } = data;
-            const fetcher = await getModelFetcher(providerId);
+            const fetcher = await this.getModelFetcher(providerId);
             if (!fetcher) {
                 return { favorites: [], models: [], recent: [] };
             }
             // Fetch models from provider API using the correct per-provider fetcher
             let fetchedModels;
             try {
+                const config = await this.providerConfigStore.read();
+                const authMethod = config.providers[providerId]?.authMethod;
                 const apiKey = await this.providerKeychainStore.getApiKey(providerId);
-                fetchedModels = await fetcher.fetchModels(apiKey ?? '');
+                fetchedModels = await fetcher.fetchModels(apiKey ?? '', { authMethod });
             }
-            catch {
-                return { favorites: [], models: [], recent: [] };
+            catch (error) {
+                const message = error instanceof Error ? error.message : 'Failed to load models';
+                return { error: message, favorites: [], models: [], recent: [] };
             }
             const models = fetchedModels.map((m) => ({
                 contextLength: m.contextLength,
@@ -61,12 +66,14 @@ export class ModelHandler {
     setupListByProviders() {
         this.transport.onRequest(ModelEvents.LIST_BY_PROVIDERS, async (data) => {
             const { providerIds } = data;
+            const config = await this.providerConfigStore.read();
             const results = await Promise.allSettled(providerIds.map(async (providerId) => {
-                const fetcher = await getModelFetcher(providerId);
+                const fetcher = await this.getModelFetcher(providerId);
                 if (!fetcher)
                     return [];
+                const authMethod = config.providers[providerId]?.authMethod;
                 const apiKey = await this.providerKeychainStore.getApiKey(providerId);
-                const fetchedModels = await fetcher.fetchModels(apiKey ?? '');
+                const fetchedModels = await fetcher.fetchModels(apiKey ?? '', { authMethod });
                 return fetchedModels.map((model) => ({
                     contextLength: model.contextLength,
                     description: model.description,
@@ -98,10 +105,45 @@ export class ModelHandler {
     }
     setupSetActive() {
         this.transport.onRequest(ModelEvents.SET_ACTIVE, async (data) => {
-            await this.providerConfigStore.setActiveProvider(data.providerId);
-            await this.providerConfigStore.setActiveModel(data.providerId, data.modelId, data.contextLength);
-            this.transport.broadcast(TransportDaemonEventNames.PROVIDER_UPDATED, {});
-            return { success: true };
+            try {
+                const config = await this.providerConfigStore.read();
+                const providerConfig = config.providers[data.providerId];
+                if (!providerConfig) {
+                    return {
+                        error: `Provider "${data.providerId}" is not connected`,
+                        success: false,
+                    };
+                }
+                let matchedModel;
+                // Validate model against allowed list for OAuth providers
+                if (providerConfig.authMethod === 'oauth') {
+                    const fetcher = await this.getModelFetcher(data.providerId);
+                    if (!fetcher) {
+                        return {
+                            error: `Cannot validate model for OAuth-connected ${data.providerId}: model fetcher unavailable`,
+                            success: false,
+                        };
+                    }
+                    const allowedModels = await fetcher.fetchModels('', { authMethod: 'oauth' });
+                    matchedModel = allowedModels.find((m) => m.id === data.modelId);
+                    if (!matchedModel) {
+                        const allowedIds = allowedModels.map((m) => m.id).join(', ');
+                        return {
+                            error: `Model "${data.modelId}" is not available for OAuth-connected ${data.providerId}. Allowed models: ${allowedIds}`,
+                            success: false,
+                        };
+                    }
+                }
+                const contextLength = data.contextLength ?? matchedModel?.contextLength;
+                await this.providerConfigStore.setActiveProvider(data.providerId);
+                await this.providerConfigStore.setActiveModel(data.providerId, data.modelId, contextLength);
+                this.transport.broadcast(TransportDaemonEventNames.PROVIDER_UPDATED, {});
+                return { success: true };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : 'Failed to set active model';
+                return { error: message, success: false };
+            }
         });
     }
 }

package/dist/server/infra/transport/handlers/provider-handler.d.ts

@@ -1,9 +1,24 @@
 import type { IProviderConfigStore } from '../../../core/interfaces/i-provider-config-store.js';
 import type { IProviderKeychainStore } from '../../../core/interfaces/i-provider-keychain-store.js';
+import type { IProviderOAuthTokenStore } from '../../../core/interfaces/i-provider-oauth-token-store.js';
+import type { IBrowserLauncher } from '../../../core/interfaces/services/i-browser-launcher.js';
 import type { ITransportServer } from '../../../core/interfaces/transport/i-transport-server.js';
+import type { PkceParameters, ProviderTokenResponse, TokenExchangeParams } from '../../provider-oauth/index.js';
+import { ProviderCallbackServer } from '../../provider-oauth/index.js';
 export interface ProviderHandlerDeps {
+    browserLauncher: IBrowserLauncher;
+    /** Factory for creating callback servers (injectable for testing) */
+    createCallbackServer?: (options: {
+        callbackPath?: string;
+        port: number;
+    }) => ProviderCallbackServer;
+    /** Token exchange function (injectable for testing) */
+    exchangeCodeForTokens?: (params: TokenExchangeParams) => Promise<ProviderTokenResponse>;
+    /** PKCE generator function (injectable for testing) */
+    generatePkce?: () => PkceParameters;
     providerConfigStore: IProviderConfigStore;
     providerKeychainStore: IProviderKeychainStore;
+    providerOAuthTokenStore: IProviderOAuthTokenStore;
     transport: ITransportServer;
 }
 /**
@@ -11,15 +26,26 @@ export interface ProviderHandlerDeps {
  * Business logic for provider management — no terminal/UI calls.
  */
 export declare class ProviderHandler {
+    private readonly browserLauncher;
+    private readonly createCallbackServer;
+    private readonly exchangeCodeForTokens;
+    private readonly generatePkce;
+    private readonly oauthFlows;
     private readonly providerConfigStore;
     private readonly providerKeychainStore;
+    private readonly providerOAuthTokenStore;
     private readonly transport;
     constructor(deps: ProviderHandlerDeps);
     setup(): void;
+    private cleanupFlowsForClient;
+    private setupAwaitOAuthCallback;
+    private setupCancelOAuth;
     private setupConnect;
     private setupDisconnect;
     private setupGetActive;
     private setupList;
     private setupSetActive;
+    private setupStartOAuth;
+    private setupSubmitOAuthCode;
     private setupValidateApiKey;
 }

package/dist/server/infra/transport/handlers/provider-handler.js

@@ -4,17 +4,29 @@ import { TransportDaemonEventNames } from '../../../core/domain/transport/schema
 import { getErrorMessage } from '../../../utils/error-helpers.js';
 import { processLog } from '../../../utils/process-logger.js';
 import { validateApiKey as validateApiKeyViaFetcher } from '../../http/provider-model-fetcher-registry.js';
+import { computeExpiresAt, exchangeCodeForTokens as defaultExchangeCodeForTokens, generatePkce as defaultGeneratePkce, parseAccountIdFromIdToken, ProviderCallbackServer, ProviderCallbackTimeoutError, } from '../../provider-oauth/index.js';
 /**
  * Handles provider:* events.
  * Business logic for provider management — no terminal/UI calls.
  */
 export class ProviderHandler {
+    browserLauncher;
+    createCallbackServer;
+    exchangeCodeForTokens;
+    generatePkce;
+    oauthFlows = new Map();
     providerConfigStore;
     providerKeychainStore;
+    providerOAuthTokenStore;
     transport;
     constructor(deps) {
+        this.browserLauncher = deps.browserLauncher;
+        this.createCallbackServer = deps.createCallbackServer ?? ((options) => new ProviderCallbackServer(options));
+        this.exchangeCodeForTokens = deps.exchangeCodeForTokens ?? defaultExchangeCodeForTokens;
+        this.generatePkce = deps.generatePkce ?? defaultGeneratePkce;
         this.providerConfigStore = deps.providerConfigStore;
         this.providerKeychainStore = deps.providerKeychainStore;
+        this.providerOAuthTokenStore = deps.providerOAuthTokenStore;
         this.transport = deps.transport;
     }
     setup() {
@@ -24,6 +36,99 @@ export class ProviderHandler {
         this.setupList();
         this.setupSetActive();
         this.setupValidateApiKey();
+        this.setupStartOAuth();
+        this.setupAwaitOAuthCallback();
+        this.setupCancelOAuth();
+        this.setupSubmitOAuthCode();
+        // Clean up OAuth flows when a client disconnects (prevents callback server port leaks)
+        this.transport.onDisconnection((clientId) => {
+            this.cleanupFlowsForClient(clientId);
+        });
+    }
+    cleanupFlowsForClient(clientId) {
+        for (const [providerId, flow] of this.oauthFlows.entries()) {
+            if (flow.clientId === clientId) {
+                flow.callbackServer?.stop().catch(() => { });
+                this.oauthFlows.delete(providerId);
+            }
+        }
+    }
+    setupAwaitOAuthCallback() {
+        this.transport.onRequest(ProviderEvents.AWAIT_OAUTH_CALLBACK, async (data) => {
+            const flow = this.oauthFlows.get(data.providerId);
+            if (!flow?.callbackServer) {
+                return { error: 'No active OAuth flow for this provider', success: false };
+            }
+            if (flow.awaitInProgress) {
+                return { error: 'OAuth callback is already being awaited for this provider', success: false };
+            }
+            flow.awaitInProgress = true;
+            try {
+                // Block until callback or timeout (5 min default in ProviderCallbackServer)
+                const callbackResult = await flow.callbackServer.waitForCallback(flow.state);
+                // Exchange code for tokens
+                const providerDef = getProviderById(data.providerId);
+                if (!providerDef?.oauth) {
+                    return { error: 'Provider does not support OAuth', success: false };
+                }
+                const oauthConfig = providerDef.oauth;
+                const contentType = oauthConfig.tokenContentType === 'form' ? 'application/x-www-form-urlencoded' : 'application/json';
+                const tokens = await this.exchangeCodeForTokens({
+                    clientId: oauthConfig.clientId,
+                    code: callbackResult.code,
+                    codeVerifier: flow.codeVerifier,
+                    contentType,
+                    redirectUri: oauthConfig.redirectUri,
+                    tokenUrl: oauthConfig.tokenUrl,
+                });
+                // Parse JWT id_token for account ID
+                const oauthAccountId = tokens.id_token ? parseAccountIdFromIdToken(tokens.id_token) : undefined;
+                // Store access token as the "API key" in keychain
+                await this.providerKeychainStore.setApiKey(data.providerId, tokens.access_token);
+                // Store refresh token + expiry in encrypted OAuth token store
+                if (tokens.refresh_token) {
+                    const expiresAt = tokens.expires_in ? computeExpiresAt(tokens.expires_in) : computeExpiresAt(3600); // 1-hour default when provider omits expires_in
+                    await this.providerOAuthTokenStore.set(data.providerId, {
+                        expiresAt,
+                        refreshToken: tokens.refresh_token,
+                    });
+                }
+                // Connect provider — secrets stored in keychain + encrypted token store, not config
+                // OAuth providers may define their own default model (e.g., Codex for OpenAI OAuth)
+                const defaultModel = oauthConfig.defaultModel ?? providerDef.defaultModel;
+                await this.providerConfigStore.connectProvider(data.providerId, {
+                    activeModel: defaultModel,
+                    authMethod: 'oauth',
+                    oauthAccountId,
+                });
+                // Broadcast update
+                this.transport.broadcast(TransportDaemonEventNames.PROVIDER_UPDATED, {});
+                return { success: true };
+            }
+            catch (error) {
+                if (error instanceof ProviderCallbackTimeoutError) {
+                    return { error: 'Authentication timed out. Please try again.', success: false };
+                }
+                return { error: getErrorMessage(error), success: false };
+            }
+            finally {
+                // Only clean up if this is still the same flow (guard against concurrent START_OAUTH)
+                if (this.oauthFlows.get(data.providerId) === flow) {
+                    await flow.callbackServer?.stop().catch(() => { });
+                    this.oauthFlows.delete(data.providerId);
+                }
+            }
+        });
+    }
+    setupCancelOAuth() {
+        this.transport.onRequest(ProviderEvents.CANCEL_OAUTH, async (data) => {
+            const flow = this.oauthFlows.get(data.providerId);
+            if (flow?.callbackServer) {
+                await flow.callbackServer.stop().catch(() => { });
+            }
+            this.oauthFlows.delete(data.providerId);
+            return { success: true };
+        });
     }
     setupConnect() {
         this.transport.onRequest(ProviderEvents.CONNECT, async (data) => {
@@ -35,6 +140,7 @@ export class ProviderHandler {
             const provider = getProviderById(providerId);
             await this.providerConfigStore.connectProvider(providerId, {
                 activeModel: provider?.defaultModel,
+                authMethod: apiKey ? 'api-key' : undefined,
                 baseUrl,
             });
             this.transport.broadcast(TransportDaemonEventNames.PROVIDER_UPDATED, {});
@@ -46,6 +152,7 @@ export class ProviderHandler {
             const { providerId } = data;
             await this.providerConfigStore.disconnectProvider(providerId);
             await this.providerKeychainStore.deleteApiKey(providerId);
+            await this.providerOAuthTokenStore.delete(providerId);
             this.transport.broadcast(TransportDaemonEventNames.PROVIDER_UPDATED, {});
             return { success: true };
         });
@@ -64,19 +171,28 @@ export class ProviderHandler {
                 processLog(`[ProviderHandler] getActiveProvider failed: ${error instanceof Error ? error.message : String(error)}`);
                 return '';
             });
-            const providers = await Promise.all(definitions.map(async (def) => ({
-                apiKeyUrl: def.apiKeyUrl,
-                category: def.category,
-                description: def.description,
-                id: def.id,
-                isConnected: await this.providerConfigStore.isProviderConnected(def.id).catch((error) => {
-                    processLog(`[ProviderHandler] isProviderConnected failed for ${def.id}: ${error instanceof Error ? error.message : String(error)}`);
-                    return false;
-                }),
-                isCurrent: def.id === activeProviderId,
-                name: def.name,
-                requiresApiKey: providerRequiresApiKey(def.id),
-            })));
+            const config = await this.providerConfigStore.read().catch(() => null);
+            const providers = await Promise.all(definitions.map(async (def) => {
+                const providerConfig = config?.providers[def.id];
+                const authMethod = providerConfig?.authMethod;
+                return {
+                    apiKeyUrl: def.apiKeyUrl,
+                    authMethod,
+                    category: def.category,
+                    description: def.description,
+                    id: def.id,
+                    isConnected: await this.providerConfigStore.isProviderConnected(def.id).catch((error) => {
+                        processLog(`[ProviderHandler] isProviderConnected failed for ${def.id}: ${error instanceof Error ? error.message : String(error)}`);
+                        return false;
+                    }),
+                    isCurrent: def.id === activeProviderId,
+                    name: def.name,
+                    oauthCallbackMode: def.oauth?.callbackMode,
+                    oauthLabel: def.oauth?.modes[0]?.label,
+                    requiresApiKey: providerRequiresApiKey(def.id, authMethod),
+                    supportsOAuth: Boolean(def.oauth),
+                };
+            }));
             return { providers };
         });
     }
@@ -87,6 +203,92 @@ export class ProviderHandler {
             return { success: true };
         });
     }
+    /* eslint-disable camelcase -- OAuth query params follow RFC 6749 naming */
+    setupStartOAuth() {
+        this.transport.onRequest(ProviderEvents.START_OAUTH, async (data, clientId) => {
+            const providerDef = getProviderById(data.providerId);
+            if (!providerDef?.oauth) {
+                const errorResponse = {
+                    authUrl: '',
+                    callbackMode: 'auto',
+                    error: 'Provider does not support OAuth',
+                    success: false,
+                };
+                return errorResponse;
+            }
+            try {
+                const oauthConfig = providerDef.oauth;
+                // Clean up any existing flow for this provider (race condition guard)
+                const existingFlow = this.oauthFlows.get(data.providerId);
+                if (existingFlow?.callbackServer) {
+                    await existingFlow.callbackServer.stop().catch(() => { });
+                }
+                this.oauthFlows.delete(data.providerId);
+                // Generate PKCE parameters
+                const pkce = this.generatePkce();
+                // Build auth URL
+                const mode = oauthConfig.modes.find((m) => m.id === (data.mode ?? 'default')) ?? oauthConfig.modes[0];
+                const params = new URLSearchParams({
+                    client_id: oauthConfig.clientId,
+                    code_challenge: pkce.codeChallenge,
+                    code_challenge_method: 'S256',
+                    redirect_uri: oauthConfig.redirectUri,
+                    response_type: 'code',
+                    scope: oauthConfig.scopes,
+                    state: pkce.state,
+                });
+                // Provider-specific extra params (e.g. OpenAI's codex_cli_simplified_flow)
+                if (oauthConfig.extraParams) {
+                    for (const [key, value] of Object.entries(oauthConfig.extraParams)) {
+                        params.set(key, value);
+                    }
+                }
+                const authUrl = `${mode.authUrl}?${params.toString()}`;
+                // Start callback server for auto mode
+                let callbackServer;
+                if (oauthConfig.callbackMode === 'auto' && oauthConfig.callbackPort) {
+                    callbackServer = this.createCallbackServer({ port: oauthConfig.callbackPort });
+                    await callbackServer.start();
+                }
+                // Store flow state
+                this.oauthFlows.set(data.providerId, {
+                    callbackServer,
+                    clientId,
+                    codeVerifier: pkce.codeVerifier,
+                    state: pkce.state,
+                });
+                // Open browser (non-fatal on failure)
+                try {
+                    await this.browserLauncher.open(authUrl);
+                }
+                catch {
+                    processLog(`[ProviderHandler] Browser launch failed for OAuth — user can copy the URL`);
+                }
+                return { authUrl, callbackMode: oauthConfig.callbackMode, success: true };
+            }
+            catch (error) {
+                // Clean up callback server if it was started but flow setup failed
+                const partialFlow = this.oauthFlows.get(data.providerId);
+                if (partialFlow?.callbackServer) {
+                    await partialFlow.callbackServer.stop().catch(() => { });
+                }
+                this.oauthFlows.delete(data.providerId);
+                const errorResponse = {
+                    authUrl: '',
+                    callbackMode: 'auto',
+                    error: getErrorMessage(error),
+                    success: false,
+                };
+                return errorResponse;
+            }
+        });
+    }
+    /* eslint-enable camelcase */
+    setupSubmitOAuthCode() {
+        this.transport.onRequest(ProviderEvents.SUBMIT_OAUTH_CODE, 
+        // Stub for M2 (Anthropic code-paste flow)
+        async () => ({ error: 'Code submission is not yet supported for this provider', success: false }));
+    }
     setupValidateApiKey() {
         this.transport.onRequest(ProviderEvents.VALIDATE_API_KEY, async (data) => {
             try {