@dotsetlabs/bellwether 0.10.0

package/dist/auth/credentials.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Credential resolution - unified API key retrieval from multiple sources.
+ *
+ * Resolution order (highest to lowest priority):
+ * 1. Direct config (apiKey in config)
+ * 2. Custom environment variable (apiKeyEnvVar in config)
+ * 3. Standard environment variable (OPENAI_API_KEY, ANTHROPIC_API_KEY)
+ * 4. Project .env file (./env in current working directory)
+ * 5. Global .env file (~/.bellwether/.env)
+ * 6. System keychain (via bellwether auth)
+ */
+import type { LLMProviderId, LLMConfig } from '../llm/client.js';
+/**
+ * Default environment variable names for each provider.
+ */
+export declare const DEFAULT_ENV_VARS: Record<LLMProviderId, string>;
+/**
+ * Result of credential resolution.
+ */
+export interface CredentialResult {
+    apiKey: string | undefined;
+    source: 'config' | 'env' | 'project-env' | 'global-env' | 'keychain' | 'none';
+    envVar?: string;
+    envFile?: string;
+}
+/**
+ * Resolve API key from all available sources.
+ *
+ * Resolution order (highest to lowest priority):
+ * 1. Direct config (apiKey in config)
+ * 2. Custom environment variable (apiKeyEnvVar in config)
+ * 3. Standard environment variable (OPENAI_API_KEY, ANTHROPIC_API_KEY)
+ * 4. Project .env file (./env in current working directory)
+ * 5. Global .env file (~/.bellwether/.env)
+ * 6. System keychain (via bellwether auth)
+ *
+ * @param config - LLM configuration
+ * @returns The resolved API key and its source
+ */
+export declare function resolveCredentials(config: Pick<LLMConfig, 'provider' | 'apiKey' | 'apiKeyEnvVar'>): Promise<CredentialResult>;
+/**
+ * Synchronous API key resolution (for backward compatibility).
+ * Does NOT check keychain - use resolveCredentials for full resolution.
+ */
+export declare function resolveApiKeySync(config: Pick<LLMConfig, 'provider' | 'apiKey' | 'apiKeyEnvVar'>): string | undefined;
+/**
+ * Check if credentials are available for a provider.
+ */
+export declare function hasCredentials(provider: LLMProviderId): Promise<boolean>;
+/**
+ * Get a description of where credentials are configured.
+ */
+export declare function describeCredentialSource(provider: LLMProviderId): Promise<string>;
+/**
+ * Get authentication status for all providers.
+ */
+export interface AuthStatus {
+    provider: LLMProviderId;
+    configured: boolean;
+    source: CredentialResult['source'];
+    envVar?: string;
+}
+export declare function getAuthStatus(): Promise<AuthStatus[]>;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/auth/credentials.js

@@ -0,0 +1,218 @@
+/**
+ * Credential resolution - unified API key retrieval from multiple sources.
+ *
+ * Resolution order (highest to lowest priority):
+ * 1. Direct config (apiKey in config)
+ * 2. Custom environment variable (apiKeyEnvVar in config)
+ * 3. Standard environment variable (OPENAI_API_KEY, ANTHROPIC_API_KEY)
+ * 4. Project .env file (./env in current working directory)
+ * 5. Global .env file (~/.bellwether/.env)
+ * 6. System keychain (via bellwether auth)
+ */
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { getKeychainService } from './keychain.js';
+/**
+ * Default environment variable names for each provider.
+ */
+export const DEFAULT_ENV_VARS = {
+    openai: 'OPENAI_API_KEY',
+    anthropic: 'ANTHROPIC_API_KEY',
+    ollama: '', // Ollama doesn't need an API key
+};
+/**
+ * Read a specific environment variable from a .env file.
+ * Returns undefined if the file doesn't exist or the variable isn't found.
+ */
+function readEnvFile(filePath, envVar) {
+    try {
+        if (!existsSync(filePath)) {
+            return undefined;
+        }
+        const content = readFileSync(filePath, 'utf-8');
+        const lines = content.split('\n');
+        for (const line of lines) {
+            const trimmed = line.trim();
+            // Skip empty lines and comments
+            if (!trimmed || trimmed.startsWith('#')) {
+                continue;
+            }
+            // Parse KEY=VALUE format
+            const eqIndex = trimmed.indexOf('=');
+            if (eqIndex === -1) {
+                continue;
+            }
+            const key = trimmed.substring(0, eqIndex).trim();
+            if (key !== envVar) {
+                continue;
+            }
+            let value = trimmed.substring(eqIndex + 1).trim();
+            // Remove surrounding quotes if present
+            if ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'"))) {
+                value = value.slice(1, -1);
+            }
+            if (value) {
+                return value;
+            }
+        }
+        return undefined;
+    }
+    catch {
+        // File read error - return undefined
+        return undefined;
+    }
+}
+/**
+ * Get the path to the global Bellwether .env file.
+ */
+function getGlobalEnvPath() {
+    return join(homedir(), '.bellwether', '.env');
+}
+/**
+ * Get the path to the project .env file.
+ */
+function getProjectEnvPath() {
+    return join(process.cwd(), '.env');
+}
+/**
+ * Resolve API key from all available sources.
+ *
+ * Resolution order (highest to lowest priority):
+ * 1. Direct config (apiKey in config)
+ * 2. Custom environment variable (apiKeyEnvVar in config)
+ * 3. Standard environment variable (OPENAI_API_KEY, ANTHROPIC_API_KEY)
+ * 4. Project .env file (./env in current working directory)
+ * 5. Global .env file (~/.bellwether/.env)
+ * 6. System keychain (via bellwether auth)
+ *
+ * @param config - LLM configuration
+ * @returns The resolved API key and its source
+ */
+export async function resolveCredentials(config) {
+    // 1. Direct config
+    if (config.apiKey) {
+        return { apiKey: config.apiKey, source: 'config' };
+    }
+    // 2. Custom environment variable
+    if (config.apiKeyEnvVar) {
+        const key = process.env[config.apiKeyEnvVar];
+        if (key) {
+            return { apiKey: key, source: 'env', envVar: config.apiKeyEnvVar };
+        }
+    }
+    // 3. Standard environment variable (already in process.env)
+    const defaultEnvVar = DEFAULT_ENV_VARS[config.provider];
+    if (defaultEnvVar) {
+        const key = process.env[defaultEnvVar];
+        if (key) {
+            return { apiKey: key, source: 'env', envVar: defaultEnvVar };
+        }
+    }
+    // 4. Project .env file
+    if (defaultEnvVar) {
+        const projectEnvPath = getProjectEnvPath();
+        const key = readEnvFile(projectEnvPath, defaultEnvVar);
+        if (key) {
+            return { apiKey: key, source: 'project-env', envVar: defaultEnvVar, envFile: projectEnvPath };
+        }
+    }
+    // 5. Global .env file (~/.bellwether/.env)
+    if (defaultEnvVar) {
+        const globalEnvPath = getGlobalEnvPath();
+        const key = readEnvFile(globalEnvPath, defaultEnvVar);
+        if (key) {
+            return { apiKey: key, source: 'global-env', envVar: defaultEnvVar, envFile: globalEnvPath };
+        }
+    }
+    // 6. System keychain
+    if (config.provider !== 'ollama') {
+        try {
+            const keychain = getKeychainService();
+            const key = await keychain.getApiKey(config.provider);
+            if (key) {
+                return { apiKey: key, source: 'keychain' };
+            }
+        }
+        catch {
+            // Keychain not available
+        }
+    }
+    return { apiKey: undefined, source: 'none' };
+}
+/**
+ * Synchronous API key resolution (for backward compatibility).
+ * Does NOT check keychain - use resolveCredentials for full resolution.
+ */
+export function resolveApiKeySync(config) {
+    if (config.apiKey) {
+        return config.apiKey;
+    }
+    if (config.apiKeyEnvVar) {
+        const key = process.env[config.apiKeyEnvVar];
+        if (key)
+            return key;
+    }
+    const defaultEnvVar = DEFAULT_ENV_VARS[config.provider];
+    if (defaultEnvVar) {
+        return process.env[defaultEnvVar];
+    }
+    return undefined;
+}
+/**
+ * Check if credentials are available for a provider.
+ */
+export async function hasCredentials(provider) {
+    if (provider === 'ollama') {
+        return true; // Ollama doesn't need credentials
+    }
+    const result = await resolveCredentials({ provider });
+    return result.source !== 'none';
+}
+/**
+ * Get a description of where credentials are configured.
+ */
+export async function describeCredentialSource(provider) {
+    if (provider === 'ollama') {
+        return 'Ollama (no API key required)';
+    }
+    const result = await resolveCredentials({ provider });
+    switch (result.source) {
+        case 'config':
+            return 'Provided in configuration';
+        case 'env':
+            return `Environment variable: ${result.envVar}`;
+        case 'project-env':
+            return `Project .env file: ${result.envFile}`;
+        case 'global-env':
+            return `Global .env file: ${result.envFile}`;
+        case 'keychain':
+            return 'System keychain';
+        case 'none':
+            return 'Not configured';
+    }
+}
+export async function getAuthStatus() {
+    const providers = ['openai', 'anthropic', 'ollama'];
+    const results = [];
+    for (const provider of providers) {
+        if (provider === 'ollama') {
+            results.push({
+                provider,
+                configured: true,
+                source: 'none', // Ollama doesn't use credentials
+            });
+            continue;
+        }
+        const creds = await resolveCredentials({ provider });
+        results.push({
+            provider,
+            configured: creds.source !== 'none',
+            source: creds.source,
+            envVar: creds.envVar,
+        });
+    }
+    return results;
+}
+//# sourceMappingURL=credentials.js.map

package/dist/auth/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Authentication module - secure credential management.
+ */
+export { KeychainService, getKeychainService, type KeychainBackend, } from './keychain.js';
+export { resolveCredentials, resolveApiKeySync, hasCredentials, describeCredentialSource, getAuthStatus, DEFAULT_ENV_VARS, type CredentialResult, type AuthStatus, } from './credentials.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.js

@@ -0,0 +1,6 @@
+/**
+ * Authentication module - secure credential management.
+ */
+export { KeychainService, getKeychainService, } from './keychain.js';
+export { resolveCredentials, resolveApiKeySync, hasCredentials, describeCredentialSource, getAuthStatus, DEFAULT_ENV_VARS, } from './credentials.js';
+//# sourceMappingURL=index.js.map

package/dist/auth/keychain.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Cross-platform keychain service for secure credential storage.
+ *
+ * Uses the system keychain:
+ * - macOS: Keychain
+ * - Windows: Credential Manager
+ * - Linux: Secret Service (libsecret)
+ *
+ * Gracefully degrades if keychain is unavailable (e.g., CI environments).
+ */
+import type { LLMProviderId } from '../llm/client.js';
+/**
+ * Keychain interface - can be implemented by different backends.
+ */
+export interface KeychainBackend {
+    getPassword(service: string, account: string): Promise<string | null>;
+    setPassword(service: string, account: string, password: string): Promise<void>;
+    deletePassword(service: string, account: string): Promise<boolean>;
+}
+/**
+ * Keychain service - manages API key storage.
+ */
+export declare class KeychainService {
+    private backend;
+    private useFileBackend;
+    constructor();
+    /**
+     * Check if secure keychain (keytar) is available.
+     */
+    isSecureKeychainAvailable(): Promise<boolean>;
+    /**
+     * Get the backend being used.
+     */
+    getBackendType(): Promise<'keychain' | 'file'>;
+    /**
+     * Enable file-based fallback explicitly.
+     */
+    enableFileBackend(): void;
+    /**
+     * Get API key for a provider from keychain.
+     */
+    getApiKey(provider: LLMProviderId): Promise<string | null>;
+    /**
+     * Store API key for a provider in keychain.
+     */
+    setApiKey(provider: LLMProviderId, apiKey: string): Promise<void>;
+    /**
+     * Delete API key for a provider from keychain.
+     */
+    deleteApiKey(provider: LLMProviderId): Promise<boolean>;
+    /**
+     * Get all stored credentials (without values, just which providers have keys).
+     */
+    getStoredProviders(): Promise<LLMProviderId[]>;
+    /**
+     * Clear all stored credentials.
+     */
+    clearAll(): Promise<void>;
+}
+/**
+ * Get the keychain service instance.
+ */
+export declare function getKeychainService(): KeychainService;
+//# sourceMappingURL=keychain.d.ts.map

package/dist/auth/keychain.js

@@ -0,0 +1,268 @@
+/**
+ * Cross-platform keychain service for secure credential storage.
+ *
+ * Uses the system keychain:
+ * - macOS: Keychain
+ * - Windows: Credential Manager
+ * - Linux: Secret Service (libsecret)
+ *
+ * Gracefully degrades if keychain is unavailable (e.g., CI environments).
+ */
+import { homedir } from 'os';
+import { join } from 'path';
+import { createRequire } from 'module';
+// Create require function for loading CommonJS optional dependencies in ESM
+const require = createRequire(import.meta.url);
+// Service name for keychain entries
+const SERVICE_NAME = 'bellwether';
+// Account names for each provider
+const PROVIDER_ACCOUNTS = {
+    openai: 'openai-api-key',
+    anthropic: 'anthropic-api-key',
+    ollama: 'ollama', // Ollama doesn't use API keys, but included for completeness
+};
+/**
+ * Keytar-based keychain backend (requires keytar package).
+ */
+class KeytarBackend {
+    keytar = null;
+    initPromise = null;
+    async init() {
+        if (this.initPromise) {
+            return this.initPromise;
+        }
+        this.initPromise = (async () => {
+            try {
+                // Dynamic import to avoid requiring keytar if not installed
+                // Using require() for optional dependency
+                this.keytar = require('keytar');
+            }
+            catch {
+                // keytar not available - will use fallback
+                this.keytar = null;
+            }
+        })();
+        return this.initPromise;
+    }
+    async getPassword(service, account) {
+        await this.init();
+        if (!this.keytar)
+            return null;
+        return this.keytar.getPassword(service, account);
+    }
+    async setPassword(service, account, password) {
+        await this.init();
+        if (!this.keytar) {
+            throw new Error('Keychain not available. Install keytar: npm install keytar\n' +
+                'Or use environment variables instead.');
+        }
+        await this.keytar.setPassword(service, account, password);
+    }
+    async deletePassword(service, account) {
+        await this.init();
+        if (!this.keytar)
+            return false;
+        return this.keytar.deletePassword(service, account);
+    }
+}
+/**
+ * File-based fallback for environments without keychain access.
+ * Stores credentials in ~/.bellwether/credentials (with restrictive permissions).
+ *
+ * NOTE: This is less secure than system keychain but better than nothing.
+ * Credentials are stored in plain text but with 0600 permissions.
+ */
+class FileBackend {
+    credentialsPath;
+    credentials = null;
+    constructor() {
+        this.credentialsPath = join(homedir(), '.bellwether', 'credentials.json');
+    }
+    async load() {
+        if (this.credentials)
+            return this.credentials;
+        const fs = await import('fs');
+        try {
+            if (fs.existsSync(this.credentialsPath)) {
+                const content = fs.readFileSync(this.credentialsPath, 'utf-8');
+                this.credentials = JSON.parse(content);
+            }
+            else {
+                this.credentials = {};
+            }
+        }
+        catch {
+            this.credentials = {};
+        }
+        return this.credentials;
+    }
+    async save() {
+        const fs = await import('fs');
+        const path = await import('path');
+        const os = await import('os');
+        const dir = path.join(os.homedir(), '.bellwether');
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        }
+        fs.writeFileSync(this.credentialsPath, JSON.stringify(this.credentials, null, 2), { mode: 0o600 });
+    }
+    async getPassword(service, account) {
+        const creds = await this.load();
+        return creds[service]?.[account] ?? null;
+    }
+    async setPassword(service, account, password) {
+        const creds = await this.load();
+        if (!creds[service]) {
+            creds[service] = {};
+        }
+        creds[service][account] = password;
+        await this.save();
+    }
+    async deletePassword(service, account) {
+        const creds = await this.load();
+        if (creds[service]?.[account]) {
+            delete creds[service][account];
+            if (Object.keys(creds[service]).length === 0) {
+                delete creds[service];
+            }
+            await this.save();
+            return true;
+        }
+        return false;
+    }
+}
+/**
+ * Keychain service - manages API key storage.
+ */
+export class KeychainService {
+    backend;
+    useFileBackend = false;
+    constructor() {
+        // Try keytar first, fall back to file-based storage
+        this.backend = new KeytarBackend();
+    }
+    /**
+     * Check if secure keychain (keytar) is available.
+     */
+    async isSecureKeychainAvailable() {
+        try {
+            // Try to access keytar using require
+            require('keytar');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get the backend being used.
+     */
+    async getBackendType() {
+        if (await this.isSecureKeychainAvailable()) {
+            return 'keychain';
+        }
+        return 'file';
+    }
+    /**
+     * Enable file-based fallback explicitly.
+     */
+    enableFileBackend() {
+        this.backend = new FileBackend();
+        this.useFileBackend = true;
+    }
+    /**
+     * Get API key for a provider from keychain.
+     */
+    async getApiKey(provider) {
+        const account = PROVIDER_ACCOUNTS[provider];
+        if (!account || provider === 'ollama') {
+            return null;
+        }
+        try {
+            return await this.backend.getPassword(SERVICE_NAME, account);
+        }
+        catch {
+            // If keytar fails, try file backend
+            if (!this.useFileBackend) {
+                this.enableFileBackend();
+                return await this.backend.getPassword(SERVICE_NAME, account);
+            }
+            return null;
+        }
+    }
+    /**
+     * Store API key for a provider in keychain.
+     */
+    async setApiKey(provider, apiKey) {
+        const account = PROVIDER_ACCOUNTS[provider];
+        if (!account || provider === 'ollama') {
+            throw new Error(`Provider ${provider} does not use API keys`);
+        }
+        try {
+            await this.backend.setPassword(SERVICE_NAME, account, apiKey);
+        }
+        catch (error) {
+            // If keytar fails, try file backend
+            if (!this.useFileBackend) {
+                this.enableFileBackend();
+                await this.backend.setPassword(SERVICE_NAME, account, apiKey);
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    /**
+     * Delete API key for a provider from keychain.
+     */
+    async deleteApiKey(provider) {
+        const account = PROVIDER_ACCOUNTS[provider];
+        if (!account || provider === 'ollama') {
+            return false;
+        }
+        try {
+            return await this.backend.deletePassword(SERVICE_NAME, account);
+        }
+        catch {
+            // If keytar fails, try file backend
+            if (!this.useFileBackend) {
+                this.enableFileBackend();
+                return await this.backend.deletePassword(SERVICE_NAME, account);
+            }
+            return false;
+        }
+    }
+    /**
+     * Get all stored credentials (without values, just which providers have keys).
+     */
+    async getStoredProviders() {
+        const providers = [];
+        for (const provider of ['openai', 'anthropic']) {
+            const key = await this.getApiKey(provider);
+            if (key) {
+                providers.push(provider);
+            }
+        }
+        return providers;
+    }
+    /**
+     * Clear all stored credentials.
+     */
+    async clearAll() {
+        for (const provider of ['openai', 'anthropic']) {
+            await this.deleteApiKey(provider);
+        }
+    }
+}
+// Singleton instance
+let keychainService = null;
+/**
+ * Get the keychain service instance.
+ */
+export function getKeychainService() {
+    if (!keychainService) {
+        keychainService = new KeychainService();
+    }
+    return keychainService;
+}
+//# sourceMappingURL=keychain.js.map