/**
 * OAuth2 Handler
 * Manages OAuth2 authentication flows and token exchange
 */
import { OAuth2Config, OAuth2Token, OAuth2Endpoints, AuthorizationOptions } from './oauth2-config.js';
import { OAuth2ProviderLoader } from './oauth2-provider-loader.js';
/**
 * OAuth2Handler - Provider-Agnostic OAuth2 Flow Manager
 *
 * Matimo's OAuth2 Scope:
 * ✅ Help complete OAuth2 authorization with any provider
 * ✅ Exchange authorization codes for tokens
 * ✅ Support automatic token refresh if needed
 * ✅ Work with Google, GitHub, Slack, or any OAuth2 provider
 * ❌ Store tokens (User's responsibility)
 * ❌ Manage token lifecycle (User's responsibility)
 *
 * Pattern: Config → Get Auth URL → Exchange Code → Return Token → User Stores It
 *
 * Usage:
 * ```typescript
 * // 1. Create handler (works for any OAuth2 provider)
 * const oauth2 = new OAuth2Handler({
 *   provider: 'google', // or 'github', 'slack', etc.
 *   clientId: process.env.CLIENT_ID,
 *   clientSecret: process.env.CLIENT_SECRET,
 *   redirectUri: 'http://localhost:3000/callback',
 * });
 *
 * // 2. Generate authorization URL
 * const authUrl = oauth2.getAuthorizationUrl({
 *   userId: 'user-123',
 *   scopes: ['https://www.googleapis.com/auth/gmail.readonly'],
 * });
 * // Send user to authUrl
 *
 * // 3. Exchange authorization code for token
 * const token = await oauth2.exchangeCodeForToken('user-123', authCode);
 * // Token: { accessToken, refreshToken, expiresAt, ... }
 *
 * // 4. User stores token (in DB, file, cache, or wherever they choose)
 * // Matimo does NOT store tokens - that's the user's responsibility
 * await myDatabase.saveToken('user-123', token);
 *
 * // 5. User retrieves token from their storage and passes to tools
 * const stored = await myDatabase.getToken('user-123');
 * await matimo.execute('gmail-send-email', {
 *   to: 'user@example.com',
 *   GMAIL_ACCESS_TOKEN: stored.accessToken, // ← User provides token
 * });
 * ```
 */
export declare class OAuth2Handler {
    private config;
    private tokenRefreshBuffer;
    private endpoints;
    private providerLoader;
    /**
     * Constructor
     * @param config - OAuth2 configuration (provider, clientId, clientSecret, redirectUri)
     * @param providerLoader - Optional provider loader (loads from YAML files)
     */
    constructor(config: OAuth2Config, providerLoader?: OAuth2ProviderLoader);
    /**
     * Resolve OAuth2 endpoints with layered configuration
     *
     * Priority (highest to lowest):
     * 1. config.endpoints - user provided at runtime
     * 2. Environment variables: OAUTH_{PROVIDER}_AUTH_URL, OAUTH_{PROVIDER}_TOKEN_URL, etc.
     * 3. YAML definition from provider loader (tools/[provider]/definition.yaml)
     *
     * This design allows:
     * - Runtime override via config
     * - Deployment-time override via env vars
     * - Default configuration from YAML files
     * - Support for infinite providers without code changes
     */
    private resolveEndpoints;
    /**
     * Get resolved endpoints (for testing or debugging)
     */
    getEndpoints(): OAuth2Endpoints;
    /**
     * Generate authorization URL for user to visit
     * @param options - Authorization options (scopes, userId, optional state)
     * @returns Authorization URL
     */
    getAuthorizationUrl(options: AuthorizationOptions): string;
    /**
     * Exchange authorization code for access token
     * @param code - Authorization code from provider
     * @param userId - User ID to associate token with
     * @returns OAuth2Token with access and optional refresh token
     */
    exchangeCodeForToken(code: string, userId: string): Promise<OAuth2Token>;
    /**
     * Refresh a token if it's expired or expiring soon
     * @param userId - User ID (for context only)
     * @param currentToken - Current OAuth2Token to refresh
     * @returns Refreshed OAuth2Token (same token if not expiring soon)
     */
    refreshTokenIfNeeded(userId: string, currentToken: OAuth2Token): Promise<OAuth2Token>;
    /**
     * Revoke a token (logout)
     * @param token - OAuth2Token to revoke
     */
    revokeToken(token: OAuth2Token): Promise<void>;
    /**
     * Check if a token is expired or expiring soon (within 5 minute buffer)
     */
    private isTokenExpiringSoon;
    /**
     * Parse token response from provider
     */
    private parseTokenResponse;
    /**
     * Generate random state token for CSRF protection
     */
    private generateRandomState;
    /**
     * Check if a token is valid (not expired)
     */
    isTokenValid(token: OAuth2Token): boolean;
    /**
     * Set custom token refresh buffer (milliseconds before expiration)
     */
    setTokenRefreshBuffer(milliseconds: number): void;
}
export default OAuth2Handler;
//# sourceMappingURL=oauth2-handler.d.ts.map