/**
 * OAuth Runtime Context for SERV
 *
 * Provides OAuth token access within photon execution context.
 * Enables photons to request OAuth tokens via yield-based elicitation.
 */
import type { Session } from '../types/index.js';
import type { TokenVault } from '../vault/token-vault.js';
import type { OAuthFlowHandler } from '../auth/oauth.js';
/**
 * OAuth token request yield
 * When a photon needs an OAuth token, it yields this
 */
export interface OAuthAsk {
    ask: 'oauth';
    /** OAuth provider ID (e.g., 'google', 'github') */
    provider: string;
    /** Required OAuth scopes */
    scopes: string[];
    /** Human-readable message explaining why auth is needed */
    message?: string;
}
/**
 * OAuth ask response - either a token or an elicitation request
 */
export interface OAuthResponse {
    /** Whether the token is available */
    success: boolean;
    /** The access token (if available) */
    token?: string;
    /** Elicitation required - redirect user to this URL */
    elicitationUrl?: string;
    /** Elicitation ID for tracking */
    elicitationId?: string;
    /** Error message if something went wrong */
    error?: string;
}
/**
 * MCP Elicitation Error
 *
 * When a photon needs user authorization, this error is returned
 * following the MCP elicitation protocol.
 */
export declare class OAuthElicitationRequired extends Error {
    readonly code = "OAUTH_ELICITATION_REQUIRED";
    readonly elicitationUrl: string;
    readonly elicitationId: string;
    readonly provider: string;
    readonly scopes: string[];
    constructor(options: {
        elicitationUrl: string;
        elicitationId: string;
        provider: string;
        scopes: string[];
        message?: string;
    });
    /**
     * Convert to MCP error response format
     */
    toMCPError(): {
        error: {
            code: string;
            message: string;
            data: {
                elicitation: {
                    type: 'oauth';
                    url: string;
                    id: string;
                    provider: string;
                    scopes: string[];
                };
            };
        };
    };
}
export interface OAuthContextConfig {
    session: Session;
    photonId: string;
    tenantId: string;
    oauthFlow: OAuthFlowHandler;
    tokenVault: TokenVault;
}
/**
 * OAuth context for photon execution
 *
 * Provides a way for photons to request OAuth tokens during execution.
 * Integrates with SERV's OAuth flow handler to manage grants and elicitations.
 */
export declare class OAuthContext {
    private session;
    private photonId;
    private tenantId;
    private oauthFlow;
    constructor(config: OAuthContextConfig);
    /**
     * Request an OAuth token
     *
     * @param provider - OAuth provider ID
     * @param scopes - Required scopes
     * @returns Token if available, or throws OAuthElicitationRequired
     */
    requestToken(provider: string, scopes: string[]): Promise<string>;
    /**
     * Handle an OAuth ask yield
     *
     * @param ask - The OAuth ask yield from the photon
     * @returns OAuth response
     */
    handleOAuthAsk(ask: OAuthAsk): Promise<OAuthResponse>;
}
export type OAuthInputProvider = (ask: OAuthAsk | Record<string, unknown>) => Promise<unknown>;
/**
 * Create an input provider that handles OAuth asks
 *
 * Wraps the standard input provider to add OAuth token handling.
 * When an 'oauth' ask is received, it checks for existing grants
 * or initiates an elicitation flow.
 */
export declare function createOAuthInputProvider(oauthContext: OAuthContext, fallbackProvider?: (ask: Record<string, unknown>) => Promise<unknown>): OAuthInputProvider;
//# sourceMappingURL=oauth-context.d.ts.map