/**
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License.
 */
import { TokenResponse } from '../../oauth';
import { TurnContext } from '../../turnContext';
import { TurnState } from '../turnState';
import { AuthorizationManager } from './authorizationManager';
import { AuthorizationHandlerTokenOptions } from './types';
export interface Authorization {
    getToken(context: TurnContext, authHandlerId: string): Promise<TokenResponse>;
    exchangeToken(context: TurnContext, scopes: string[], authHandlerId: string): Promise<TokenResponse>;
    exchangeToken(context: TurnContext, authHandlerId: string, options?: AuthorizationHandlerTokenOptions): Promise<TokenResponse>;
    signOut(context: TurnContext, state: TurnState, authHandlerId?: string): Promise<void>;
    onSignInSuccess(handler: (context: TurnContext, state: TurnState, authHandlerId?: string) => Promise<void>): void;
    onSignInFailure(handler: (context: TurnContext, state: TurnState, authHandlerId?: string, errorMessage?: string) => Promise<void>): void;
}
/**
 * Class responsible for managing authorization and OAuth flows.
 * Handles multiple OAuth providers and manages the complete authentication lifecycle.
 *
 * @remarks
 * The Authorization class provides a centralized way to handle OAuth authentication
 * flows within the agent application. It supports multiple authentication handlers,
 * token exchange, on-behalf-of flows, and provides event handlers for success/failure scenarios.
 *
 * Key features:
 * - Multiple OAuth provider support
 * - Token caching and exchange
 * - On-behalf-of (OBO) token flows
 * - Sign-in success/failure event handling
 * - Automatic configuration from environment variables
 *
 */
export declare class UserAuthorization implements Authorization {
    private manager;
    /**
     * Creates a new instance of Authorization.
     * @param manager The AuthorizationManager instance to manage handlers.
     */
    constructor(manager: AuthorizationManager);
    /**
     * Gets the token for a specific auth handler.
     *
     * @param context - The context object for the current turn.
     * @param authHandlerId - ID of the auth handler to use.
     * @returns A promise that resolves to the token response from the OAuth provider.
     * @throws {Error} If the auth handler is not configured.
     *
     * @remarks
     * This method retrieves an existing token for the specified auth handler.
     * The token may be cached and will be retrieved from the OAuth provider if needed.
     *
     * @example
     * ```typescript
     * const tokenResponse = await auth.getToken(context, 'microsoft');
     * if (tokenResponse.token) {
     *   console.log('User is authenticated');
     * }
     * ```
     *
     * @public
     */
    getToken(context: TurnContext, authHandlerId: string): Promise<TokenResponse>;
    /**
     * @deprecated
     * Exchanges a token for a new token with different scopes.
     *
     * @param context - The context object for the current turn.
     * @param scopes - Array of scopes to request for the new token.
     * @param authHandlerId - ID of the auth handler to use.
     * @returns A promise that resolves to the exchanged token response.
     * @throws {Error} If the auth handler is not configured.
     *
     * @remarks
     * This method handles token exchange scenarios, particularly for on-behalf-of (OBO) flows.
     * It checks if the current token is exchangeable (e.g., has audience starting with 'api://')
     * and performs the appropriate token exchange using MSAL.
     *
     * @example
     * ```typescript
     * const exchangedToken = await auth.exchangeToken(
     *   context,
     *   ['https://graph.microsoft.com/.default'],
     *   'microsoft'
     * );
     * ```
     *
     * @public
     */
    exchangeToken(context: TurnContext, scopes: string[], authHandlerId: string): Promise<TokenResponse>;
    /**
     * Exchanges a token for a new token with different scopes.
     *
     * @param context - The context object for the current turn.
     * @param authHandlerId - ID of the auth handler to use.
     * @param options - Optional token options. If `connection` and `scopes` are NOT provided, the auth handler's configured options are used
     * (`AgentApplication.authorization.obo.connection` and `AgentApplication.authorization.obo.scopes`), and the token exchange operation will happen automatically,
     * meaning that this method should not be called, otherwise it will perform the token exchange operation twice.
     * Provide `options` only when you need to override the `AgentApplication.authorization.obo` configuration for a specific call.
     * @returns A promise that resolves to the exchanged token response.
     * @throws {Error} If the auth handler is not configured.
     *
     * @remarks
     * This method handles token exchange scenarios, particularly for on-behalf-of (OBO) flows.
     * It checks if the current token is exchangeable (e.g., has audience starting with 'api://')
     * and performs the appropriate token exchange using MSAL.
     *
     * @example
     * ```typescript
     * const exchangedToken = await auth.exchangeToken(
     *   context,
     *   'microsoft',
     *   { connection: 'oboConnection', scopes: ['https://graph.microsoft.com/.default'] }
     * });
     * ```
     *
     * @public
     */
    exchangeToken(context: TurnContext, authHandlerId: string, options?: AuthorizationHandlerTokenOptions): Promise<TokenResponse>;
    /**
     * Signs out the current user.
     *
     * @param context - The context object for the current turn.
     * @param state - The state object for the current turn.
     * @param authHandlerId - Optional ID of the auth handler to use for sign out. If not provided, signs out from all handlers.
     * @returns A promise that resolves when sign out is complete.
     * @throws {Error} If the specified auth handler is not configured.
     *
     * @remarks
     * This method clears the user's token and resets the authentication state.
     * If no specific authHandlerId is provided, it signs out from all configured handlers.
     * This ensures complete cleanup of authentication state across all providers.
     *
     * @example
     * ```typescript
     * // Sign out from specific handler
     * await auth.signOut(context, state, 'microsoft');
     *
     * // Sign out from all handlers
     * await auth.signOut(context, state);
     * ```
     *
     * @public
     */
    signOut(context: TurnContext, state: TurnState, authHandlerId?: string): Promise<void>;
    /**
     * Sets a handler to be called when sign-in is successfully completed.
     *
     * @param handler - The handler function to call on successful sign-in.
     *
     * @remarks
     * This method allows you to register a callback that will be invoked whenever
     * a user successfully completes the authentication process. The handler receives
     * the turn context, state, and the ID of the auth handler that was used.
     *
     * @example
     * ```typescript
     * auth.onSignInSuccess(async (context, state, authHandlerId) => {
     *   await context.sendActivity(`Welcome! You signed in using ${authHandlerId}.`);
     *   // Perform any post-authentication setup
     * });
     * ```
     *
     * @public
     */
    onSignInSuccess(handler: (context: TurnContext, state: TurnState, authHandlerId?: string) => Promise<void>): void;
    /**
     * Sets a handler to be called when sign-in fails.
     *
     * @param handler - The handler function to call on sign-in failure.
     *
     * @remarks
     * This method allows you to register a callback that will be invoked whenever
     * a user's authentication attempt fails. The handler receives the turn context,
     * state, auth handler ID, and an optional error message describing the failure.
     *
     * Common failure scenarios include:
     * - User cancels the authentication process
     * - Invalid credentials or expired tokens
     * - Network connectivity issues
     * - OAuth provider errors
     *
     * @example
     * ```typescript
     * auth.onSignInFailure(async (context, state, authHandlerId, errorMessage) => {
     *   await context.sendActivity(`Sign-in failed: ${errorMessage || 'Unknown error'}`);
     *   await context.sendActivity('Please try signing in again.');
     * });
     * ```
     *
     * @public
     */
    onSignInFailure(handler: (context: TurnContext, state: TurnState, authHandlerId?: string, errorMessage?: string) => Promise<void>): void;
    /**
     * Gets the auth handler by ID or throws an error if not found.
     *
     * @param id - ID of the auth handler to retrieve.
     * @returns The auth handler instance.
     * @throws {Error} If the auth handler with the specified ID is not configured.
     * @private
     */
    private getHandler;
}