/**
 * Universal credential resolution cascade.
 *
 * Given a principal and provider, resolves the best available credential:
 * 1. Principal's own stored OAuth token / API key
 * 2. System-level environment variable fallback
 */
import type { ToolPrincipal } from '../../types/tool-context';
/**
 * Thrown when credential resolution finds no credential for a provider.
 * Caught by route handlers to return structured 422 responses.
 */
export declare class MissingCredentialError extends Error {
    provider: string;
    constructor(provider: string);
}
export interface ResolvedCredential {
    value: string;
    source: 'user' | 'bot' | 'system';
    type: 'oauth_token' | 'api_key';
}
export interface ResolveCredentialOptions {
    /** Fallback principal for dual-identity workflows (e.g., human invoker when bot executes). */
    fallbackPrincipal?: ToolPrincipal;
}
/**
 * Resolve the best credential for a principal + provider.
 *
 * Four-tier cascade:
 * 1. Primary principal's stored OAuth token / API key
 * 2. Fallback principal's stored credential (when provided — e.g., the human
 *    invoker in a bot-executed workflow)
 * 3. System env var (e.g., ANTHROPIC_API_KEY)
 * 4. null (caller typically throws MissingCredentialError)
 *
 * @param principal - The authenticated principal (user or bot)
 * @param provider - OAuth provider name (e.g., 'anthropic', 'openai')
 * @param label - Optional credential label for multi-credential accounts
 * @param options - Optional fallback principal for dual-identity resolution
 * @returns Resolved credential or null if none available
 */
export declare function resolveCredential(principal: ToolPrincipal, provider: string, label?: string, options?: ResolveCredentialOptions): Promise<ResolvedCredential | null>;