byterover-cli 2.1.5 → 2.3.0

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

@@ -0,0 +1,76 @@
+export class ProviderOAuthError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ProviderOAuthError';
+    }
+}
+export class ProviderCallbackTimeoutError extends ProviderOAuthError {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`OAuth callback timed out after ${timeoutMs}ms`);
+        this.name = 'ProviderCallbackTimeoutError';
+        this.timeoutMs = timeoutMs;
+    }
+}
+export class ProviderCallbackStateError extends ProviderOAuthError {
+    constructor() {
+        super('OAuth callback state mismatch — possible CSRF attack');
+        this.name = 'ProviderCallbackStateError';
+    }
+}
+export class ProviderCallbackOAuthError extends ProviderOAuthError {
+    errorCode;
+    constructor(errorCode, errorDescription) {
+        super(errorDescription ?? `OAuth provider returned error: ${errorCode}`);
+        this.name = 'ProviderCallbackOAuthError';
+        this.errorCode = errorCode;
+    }
+}
+export class ProviderTokenExchangeError extends ProviderOAuthError {
+    errorCode;
+    statusCode;
+    constructor(params) {
+        super(params.message);
+        this.name = 'ProviderTokenExchangeError';
+        this.errorCode = params.errorCode;
+        this.statusCode = params.statusCode;
+    }
+}
+/**
+ * Extracts OAuth error fields from an unknown error response body.
+ * Shared by token-exchange and refresh-token-exchange.
+ */
+export function extractOAuthErrorFields(data) {
+    if (typeof data !== 'object' || data === null) {
+        return {};
+    }
+    return {
+        error: 'error' in data && typeof data.error === 'string' ? data.error : undefined,
+        // eslint-disable-next-line camelcase
+        error_description: 'error_description' in data && typeof data.error_description === 'string' ? data.error_description : undefined,
+    };
+}
+/**
+ * Checks whether an OAuth token refresh error is permanent (token revoked, client invalid)
+ * vs. transient (network timeout, server error).
+ *
+ * Permanent errors require disconnecting the provider and re-authenticating.
+ * Transient errors should preserve credentials so the existing access token can still be used.
+ */
+export function isPermanentOAuthError(error) {
+    if (!(error instanceof ProviderTokenExchangeError)) {
+        return false;
+    }
+    // 401/403 are unconditionally permanent (credentials rejected)
+    if (error.statusCode && [401, 403].includes(error.statusCode)) {
+        return true;
+    }
+    // 400 is only permanent when the OAuth error code explicitly indicates it.
+    // A 400 with an unknown or transient error code (e.g. temporarily_unavailable)
+    // should preserve credentials so the existing access token can still be used.
+    const permanentErrorCodes = new Set(['invalid_client', 'invalid_grant', 'unauthorized_client']);
+    if (error.errorCode && permanentErrorCodes.has(error.errorCode)) {
+        return true;
+    }
+    return false;
+}

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

@@ -0,0 +1,9 @@
+export * from './callback-server.js';
+export * from './errors.js';
+export * from './jwt-utils.js';
+export * from './pkce-service.js';
+export * from './provider-oauth-token-store.js';
+export * from './refresh-token-exchange.js';
+export * from './token-exchange.js';
+export * from './token-refresh-manager.js';
+export * from './types.js';

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

@@ -0,0 +1,9 @@
+export * from './callback-server.js';
+export * from './errors.js';
+export * from './jwt-utils.js';
+export * from './pkce-service.js';
+export * from './provider-oauth-token-store.js';
+export * from './refresh-token-exchange.js';
+export * from './token-exchange.js';
+export * from './token-refresh-manager.js';
+export * from './types.js';

package/dist/server/infra/provider-oauth/jwt-utils.d.ts

@@ -0,0 +1,17 @@
+/**
+ * JWT Utilities for Provider OAuth
+ *
+ * Parses provider-specific claims from OAuth id_tokens.
+ * Uses manual base64url decoding — no external JWT library needed.
+ */
+/**
+ * Extracts the ChatGPT Account ID from an OpenAI id_token.
+ *
+ * Checks claims in priority order:
+ * 1. `chatgpt_account_id` (top-level claim)
+ * 2. `["https://api.openai.com/auth"].chatgpt_account_id` (nested claim)
+ * 3. `organizations[0].id` (fallback)
+ *
+ * @returns The account ID string, or undefined if not found or token is malformed
+ */
+export declare function parseAccountIdFromIdToken(idToken: string): string | undefined;

package/dist/server/infra/provider-oauth/jwt-utils.js

@@ -0,0 +1,51 @@
+/**
+ * JWT Utilities for Provider OAuth
+ *
+ * Parses provider-specific claims from OAuth id_tokens.
+ * Uses manual base64url decoding — no external JWT library needed.
+ */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Extracts the ChatGPT Account ID from an OpenAI id_token.
+ *
+ * Checks claims in priority order:
+ * 1. `chatgpt_account_id` (top-level claim)
+ * 2. `["https://api.openai.com/auth"].chatgpt_account_id` (nested claim)
+ * 3. `organizations[0].id` (fallback)
+ *
+ * @returns The account ID string, or undefined if not found or token is malformed
+ */
+export function parseAccountIdFromIdToken(idToken) {
+    try {
+        const parts = idToken.split('.');
+        if (parts.length < 2 || !parts[1])
+            return undefined;
+        const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+        if (!isRecord(payload))
+            return undefined;
+        // 1. Top-level claim
+        if (typeof payload.chatgpt_account_id === 'string' && payload.chatgpt_account_id) {
+            return payload.chatgpt_account_id;
+        }
+        // 2. Nested claim under OpenAI auth namespace
+        const authNamespace = payload['https://api.openai.com/auth'];
+        if (isRecord(authNamespace) &&
+            typeof authNamespace.chatgpt_account_id === 'string' &&
+            authNamespace.chatgpt_account_id) {
+            return authNamespace.chatgpt_account_id;
+        }
+        // 3. Organizations fallback
+        if (Array.isArray(payload.organizations) && payload.organizations.length > 0) {
+            const org = payload.organizations[0];
+            if (isRecord(org) && typeof org.id === 'string' && org.id) {
+                return org.id;
+            }
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/server/infra/provider-oauth/pkce-service.d.ts

@@ -0,0 +1,22 @@
+import type { PkceParameters } from './types.js';
+/**
+ * Generates a cryptographically secure PKCE code verifier.
+ * Output is 43 characters (base64url encoding of 32 random bytes).
+ * Meets the OAuth 2.0 PKCE spec requirement of 43-128 characters.
+ */
+export declare function generateCodeVerifier(): string;
+/**
+ * Generates S256 code challenge from a code verifier.
+ * SHA-256 hash of the verifier, base64url-encoded.
+ */
+export declare function generateCodeChallenge(codeVerifier: string): string;
+/**
+ * Generates a cryptographically secure state parameter for CSRF protection.
+ * Output is 22 characters (base64url encoding of 16 random bytes).
+ */
+export declare function generateState(): string;
+/**
+ * Generates a complete set of PKCE parameters for an authorization request.
+ * Convenience function combining verifier, challenge, and state generation.
+ */
+export declare function generatePkce(): PkceParameters;

package/dist/server/infra/provider-oauth/pkce-service.js

@@ -0,0 +1,33 @@
+import crypto from 'node:crypto';
+/**
+ * Generates a cryptographically secure PKCE code verifier.
+ * Output is 43 characters (base64url encoding of 32 random bytes).
+ * Meets the OAuth 2.0 PKCE spec requirement of 43-128 characters.
+ */
+export function generateCodeVerifier() {
+    return crypto.randomBytes(32).toString('base64url');
+}
+/**
+ * Generates S256 code challenge from a code verifier.
+ * SHA-256 hash of the verifier, base64url-encoded.
+ */
+export function generateCodeChallenge(codeVerifier) {
+    return crypto.createHash('sha256').update(codeVerifier).digest('base64url');
+}
+/**
+ * Generates a cryptographically secure state parameter for CSRF protection.
+ * Output is 22 characters (base64url encoding of 16 random bytes).
+ */
+export function generateState() {
+    return crypto.randomBytes(16).toString('base64url');
+}
+/**
+ * Generates a complete set of PKCE parameters for an authorization request.
+ * Convenience function combining verifier, challenge, and state generation.
+ */
+export function generatePkce() {
+    const codeVerifier = generateCodeVerifier();
+    const codeChallenge = generateCodeChallenge(codeVerifier);
+    const state = generateState();
+    return { codeChallenge, codeVerifier, state };
+}

package/dist/server/infra/provider-oauth/provider-oauth-token-store.d.ts

@@ -0,0 +1,48 @@
+import type { IProviderOAuthTokenStore, OAuthTokenRecord } from '../../core/interfaces/i-provider-oauth-token-store.js';
+/**
+ * Dependencies for FileProviderOAuthTokenStore.
+ * Allows injection for testing (paths + filesystem operations).
+ */
+export interface FileProviderOAuthTokenStoreDeps {
+    readonly ensureDir?: (path: string) => Promise<void>;
+    readonly getCredentialsPath: () => string;
+    readonly getDataDir: () => string;
+    readonly getKeyPath: () => string;
+    readonly readBuffer?: (path: string) => Promise<Buffer>;
+    readonly readString?: (path: string) => Promise<string>;
+    readonly renameFile?: (oldPath: string, newPath: string) => Promise<void>;
+    readonly writeData?: (path: string, data: Buffer | string, options: {
+        encoding?: 'utf8';
+        mode: number;
+    }) => Promise<void>;
+}
+/**
+ * File-based encrypted OAuth token store.
+ *
+ * Security:
+ * - Random 32-byte key stored in <global-data-dir>/.provider-oauth-keys (rotated on each save)
+ * - AES-256-GCM authenticated encryption for OAuth refresh tokens + expiry
+ * - Both files have 0600 permissions (owner read/write only)
+ * - All tokens stored as encrypted JSON map: { [providerId]: OAuthTokenRecord }
+ */
+export declare class FileProviderOAuthTokenStore implements IProviderOAuthTokenStore {
+    private readonly deps;
+    private readonly ensureDir;
+    private readonly readBuffer;
+    private readonly readString;
+    private readonly renameFile;
+    private readonly writeData;
+    /** Serializes concurrent read-modify-write cycles to prevent data loss */
+    private writeLock;
+    constructor(deps?: FileProviderOAuthTokenStoreDeps);
+    delete(providerId: string): Promise<void>;
+    get(providerId: string): Promise<OAuthTokenRecord | undefined>;
+    has(providerId: string): Promise<boolean>;
+    set(providerId: string, data: OAuthTokenRecord): Promise<void>;
+    private decrypt;
+    private encrypt;
+    private loadAll;
+    private saveAll;
+    private serialize;
+}
+export declare function createProviderOAuthTokenStore(): IProviderOAuthTokenStore;

package/dist/server/infra/provider-oauth/provider-oauth-token-store.js

@@ -0,0 +1,155 @@
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { z } from 'zod';
+import { getGlobalDataDir } from '../../utils/global-data-path.js';
+const OAuthTokenRecordSchema = z.object({
+    expiresAt: z.string(),
+    refreshToken: z.string(),
+});
+const TokenRecordMapSchema = z.record(OAuthTokenRecordSchema);
+const KEY_FILE = '.provider-oauth-keys';
+const CREDENTIALS_FILE = 'provider-oauth-tokens';
+const ALGORITHM = 'aes-256-gcm';
+const KEY_LENGTH = 32;
+const IV_LENGTH = 16;
+const defaultDeps = {
+    getCredentialsPath: () => `${getGlobalDataDir()}/${CREDENTIALS_FILE}`,
+    getDataDir: getGlobalDataDir,
+    getKeyPath: () => `${getGlobalDataDir()}/${KEY_FILE}`,
+};
+/**
+ * File-based encrypted OAuth token store.
+ *
+ * Security:
+ * - Random 32-byte key stored in <global-data-dir>/.provider-oauth-keys (rotated on each save)
+ * - AES-256-GCM authenticated encryption for OAuth refresh tokens + expiry
+ * - Both files have 0600 permissions (owner read/write only)
+ * - All tokens stored as encrypted JSON map: { [providerId]: OAuthTokenRecord }
+ */
+export class FileProviderOAuthTokenStore {
+    deps;
+    ensureDir;
+    readBuffer;
+    readString;
+    renameFile;
+    writeData;
+    /** Serializes concurrent read-modify-write cycles to prevent data loss */
+    writeLock = Promise.resolve();
+    constructor(deps = defaultDeps) {
+        this.deps = deps;
+        this.ensureDir = deps.ensureDir ?? ((p) => mkdir(p, { recursive: true }).then(() => { }));
+        this.readBuffer = deps.readBuffer ?? ((p) => readFile(p));
+        this.readString = deps.readString ?? ((p) => readFile(p, 'utf8'));
+        this.renameFile = deps.renameFile ?? rename;
+        this.writeData = deps.writeData ?? ((p, d, o) => writeFile(p, d, o));
+    }
+    async delete(providerId) {
+        return this.serialize(async () => {
+            let records;
+            try {
+                records = await this.loadAll();
+            }
+            catch {
+                return; // No file to delete from
+            }
+            const updated = Object.fromEntries(Object.entries(records).filter(([key]) => key !== providerId));
+            await this.saveAll(updated);
+        });
+    }
+    async get(providerId) {
+        return this.serialize(async () => {
+            try {
+                const records = await this.loadAll();
+                return records[providerId] ?? undefined;
+            }
+            catch { }
+        });
+    }
+    async has(providerId) {
+        const record = await this.get(providerId);
+        return record !== undefined;
+    }
+    async set(providerId, data) {
+        return this.serialize(async () => {
+            let records;
+            try {
+                records = await this.loadAll();
+            }
+            catch {
+                // Credentials file is corrupt or unreadable — start fresh.
+                // Existing records are unrecoverable; overwriting is the only path forward.
+                records = {};
+            }
+            records[providerId] = data;
+            await this.saveAll(records);
+        });
+    }
+    decrypt(ciphertext, key) {
+        const parts = ciphertext.split(':');
+        if (parts.length !== 3) {
+            throw new Error('Invalid format');
+        }
+        const iv = Buffer.from(parts[0], 'base64');
+        const authTag = Buffer.from(parts[1], 'base64');
+        const encrypted = Buffer.from(parts[2], 'base64');
+        const decipher = createDecipheriv(ALGORITHM, key, iv);
+        decipher.setAuthTag(authTag);
+        return Buffer.concat([decipher.update(encrypted), decipher.final()]).toString('utf8');
+    }
+    encrypt(plaintext, key) {
+        const iv = randomBytes(IV_LENGTH);
+        const cipher = createCipheriv(ALGORITHM, key, iv);
+        const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+        const authTag = cipher.getAuthTag();
+        /** Format: iv:authTag:data (all base64) */
+        return `${iv.toString('base64')}:${authTag.toString('base64')}:${encrypted.toString('base64')}`;
+    }
+    async loadAll() {
+        const keyPath = this.deps.getKeyPath();
+        const credentialsPath = this.deps.getCredentialsPath();
+        try {
+            const key = await this.readBuffer(keyPath);
+            const encrypted = await this.readString(credentialsPath);
+            const decrypted = this.decrypt(encrypted.trim(), key);
+            const parsed = JSON.parse(decrypted);
+            return TokenRecordMapSchema.parse(parsed);
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+                return {};
+            throw error;
+        }
+    }
+    async saveAll(records) {
+        const dataDir = this.deps.getDataDir();
+        const keyPath = this.deps.getKeyPath();
+        const credentialsPath = this.deps.getCredentialsPath();
+        const tmpKeyPath = `${keyPath}.tmp`;
+        const tmpCredentialsPath = `${credentialsPath}.tmp`;
+        await this.ensureDir(dataDir);
+        // Always generate new key for rotation (security best practice).
+        // Write to temp files first, then atomically rename both — a crash at any
+        // point leaves either the old consistent pair or the new one, never a
+        // mismatched key/ciphertext that would destroy all stored tokens.
+        const key = randomBytes(KEY_LENGTH);
+        const plaintext = JSON.stringify(records);
+        const encrypted = this.encrypt(plaintext, key);
+        await this.writeData(tmpKeyPath, key, { mode: 0o600 });
+        await this.writeData(tmpCredentialsPath, encrypted, { encoding: 'utf8', mode: 0o600 });
+        // Rename key first, then credentials. If a crash occurs between the two
+        // renames, loadAll() will read the new key + old ciphertext and fail to
+        // decrypt — but set() recovers by overwriting with fresh data. The key
+        // improvement is that writes target temp files, so a crash during the
+        // write phase never corrupts the live key/ciphertext pair.
+        await this.renameFile(tmpKeyPath, keyPath);
+        await this.renameFile(tmpCredentialsPath, credentialsPath);
+    }
+    serialize(fn) {
+        const result = this.writeLock.then(fn, fn);
+        this.writeLock = result.then(() => { }, () => { });
+        return result;
+    }
+}
+export function createProviderOAuthTokenStore() {
+    return new FileProviderOAuthTokenStore();
+}

package/dist/server/infra/provider-oauth/refresh-token-exchange.d.ts

@@ -0,0 +1,8 @@
+import type { ProviderTokenResponse, RefreshTokenExchangeParams } from './types.js';
+/**
+ * Exchanges a refresh token for a new access token at the provider's token endpoint.
+ * Supports configurable content type to accommodate different providers:
+ * - OpenAI uses application/x-www-form-urlencoded
+ * - Anthropic uses application/json
+ */
+export declare function exchangeRefreshToken(params: RefreshTokenExchangeParams): Promise<ProviderTokenResponse>;

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

@@ -0,0 +1,39 @@
+/* eslint-disable camelcase */
+import axios, { isAxiosError } from 'axios';
+import { extractOAuthErrorFields, ProviderTokenExchangeError } from './errors.js';
+import { ProviderTokenResponseSchema } from './types.js';
+/**
+ * Exchanges a refresh token for a new access token at the provider's token endpoint.
+ * Supports configurable content type to accommodate different providers:
+ * - OpenAI uses application/x-www-form-urlencoded
+ * - Anthropic uses application/json
+ */
+export async function exchangeRefreshToken(params) {
+    const body = {
+        client_id: params.clientId,
+        grant_type: 'refresh_token',
+        refresh_token: params.refreshToken,
+    };
+    let response;
+    try {
+        response = await axios.post(params.tokenUrl, params.contentType === 'application/x-www-form-urlencoded' ? new URLSearchParams(body).toString() : body, {
+            headers: {
+                'Content-Type': params.contentType,
+            },
+            timeout: 30_000,
+        });
+    }
+    catch (error) {
+        if (isAxiosError(error)) {
+            const data = error.response?.data;
+            const errorFields = extractOAuthErrorFields(data);
+            throw new ProviderTokenExchangeError({
+                errorCode: errorFields.error ?? error.code,
+                message: errorFields.error_description ?? `Token refresh failed: ${error.message}`,
+                statusCode: error.response?.status,
+            });
+        }
+        throw error;
+    }
+    return ProviderTokenResponseSchema.parse(response.data);
+}

package/dist/server/infra/provider-oauth/token-exchange.d.ts

@@ -0,0 +1,8 @@
+import type { ProviderTokenResponse, TokenExchangeParams } from './types.js';
+/**
+ * Exchanges an authorization code for tokens at the provider's token endpoint.
+ * Supports configurable content type to accommodate different providers:
+ * - OpenAI uses application/x-www-form-urlencoded
+ * - Anthropic uses application/json
+ */
+export declare function exchangeCodeForTokens(params: TokenExchangeParams): Promise<ProviderTokenResponse>;

package/dist/server/infra/provider-oauth/token-exchange.js

@@ -0,0 +1,44 @@
+/* eslint-disable camelcase */
+import axios, { isAxiosError } from 'axios';
+import { extractOAuthErrorFields, ProviderTokenExchangeError } from './errors.js';
+import { ProviderTokenResponseSchema } from './types.js';
+/**
+ * Exchanges an authorization code for tokens at the provider's token endpoint.
+ * Supports configurable content type to accommodate different providers:
+ * - OpenAI uses application/x-www-form-urlencoded
+ * - Anthropic uses application/json
+ */
+export async function exchangeCodeForTokens(params) {
+    const body = {
+        client_id: params.clientId,
+        code: params.code,
+        code_verifier: params.codeVerifier,
+        grant_type: 'authorization_code',
+        redirect_uri: params.redirectUri,
+    };
+    if (params.clientSecret !== undefined) {
+        body.client_secret = params.clientSecret;
+    }
+    let response;
+    try {
+        response = await axios.post(params.tokenUrl, params.contentType === 'application/x-www-form-urlencoded' ? new URLSearchParams(body).toString() : body, {
+            headers: {
+                'Content-Type': params.contentType,
+            },
+            timeout: 30_000,
+        });
+    }
+    catch (error) {
+        if (isAxiosError(error)) {
+            const data = error.response?.data;
+            const errorFields = extractOAuthErrorFields(data);
+            throw new ProviderTokenExchangeError({
+                errorCode: errorFields.error ?? error.code,
+                message: errorFields.error_description ?? `Token exchange failed: ${error.message}`,
+                statusCode: error.response?.status,
+            });
+        }
+        throw error;
+    }
+    return ProviderTokenResponseSchema.parse(response.data);
+}

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

@@ -0,0 +1,32 @@
+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 { ITokenRefreshManager } from '../../core/interfaces/i-token-refresh-manager.js';
+import type { ITransportServer } from '../../core/interfaces/transport/i-transport-server.js';
+import type { ProviderTokenResponse, RefreshTokenExchangeParams } from './types.js';
+export { type ITokenRefreshManager } from '../../core/interfaces/i-token-refresh-manager.js';
+/** Refresh tokens when they expire within this threshold */
+export declare const REFRESH_THRESHOLD_MS: number;
+export interface TokenRefreshManagerDeps {
+    exchangeRefreshToken?: (params: RefreshTokenExchangeParams) => Promise<ProviderTokenResponse>;
+    providerConfigStore: IProviderConfigStore;
+    providerKeychainStore: IProviderKeychainStore;
+    providerOAuthTokenStore: IProviderOAuthTokenStore;
+    transport: ITransportServer;
+}
+/**
+ * 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 declare class TokenRefreshManager implements ITokenRefreshManager {
+    private readonly deps;
+    private readonly exchangeRefreshToken;
+    /** Per-provider mutex to serialize concurrent refresh attempts */
+    private readonly pendingRefreshes;
+    constructor(deps: TokenRefreshManagerDeps);
+    refreshIfNeeded(providerId: string): Promise<boolean>;
+    private doRefresh;
+}

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;
+        }
+    }
+}