byterover-cli 2.2.0 → 2.3.0

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

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;