/**
 * Step-Up Authorization Handler
 *
 * Handles step-up authorization flows for MCP 2025-11-25.
 * Step-up authorization allows clients to re-authorize with additional scopes
 * when they encounter insufficient_scope errors.
 *
 * @see MCP 2025-11-25 Specification Section 10.1
 */
import { AuthorizationRequestParams } from './oauth-flow.js';
/**
 * Insufficient scope error response
 */
export interface InsufficientScopeError {
    /** Error code (should be 'insufficient_scope') */
    error: string;
    /** Human-readable error description */
    error_description?: string;
    /** URI to error documentation */
    error_uri?: string;
    /** Required scope(s) */
    scope?: string;
    /** HTTP status code */
    status?: number;
    /** WWW-Authenticate header value */
    wwwAuthenticate?: string;
}
/**
 * Authorization result from step-up flow
 */
export interface AuthorizationResult {
    success: boolean;
    accessToken?: string;
    refreshToken?: string;
    scope?: string;
    error?: string;
}
/**
 * Step-Up Authorization Handler
 *
 * Manages the step-up authorization flow when clients need additional scopes.
 */
export declare class StepUpAuthHandler {
    private retryCount;
    private maxRetries;
    private attemptedScopes;
    constructor(maxRetries?: number);
    /**
     * Detect if error response indicates insufficient scope
     *
     * @param error - Error response from MCP server or resource server
     * @returns true if error indicates insufficient scope
     */
    detectInsufficientScope(error: any): boolean;
    /**
     * Parse required scopes from error response
     *
     * Attempts to extract scope information from:
     * 1. `scope` field in error response body
     * 2. `error_description` field (parsing text)
     * 3. WWW-Authenticate header
     *
     * @param error - Error response
     * @returns Array of required scopes
     */
    parseRequiredScopes(error: InsufficientScopeError | any): string[];
    /**
     * Initiate re-authorization with additional scopes
     *
     * @param currentScopes - Current scopes array
     * @param requiredScopes - Required scopes array
     * @param authParams - Original authorization parameters
     * @returns Updated authorization parameters with combined scopes
     */
    prepareReauthorization(currentScopes: string[], requiredScopes: string[], authParams: AuthorizationRequestParams): AuthorizationRequestParams;
    /**
     * Increment retry count and check if retry is allowed
     *
     * @returns Current retry count
     */
    incrementRetryCount(): number;
    /**
     * Check if retry is allowed
     *
     * @returns true if retry count is within limit
     */
    canRetry(): boolean;
    /**
     * Check if scope combination has already been attempted
     *
     * @param scopes - Array of scopes to check
     * @returns true if this scope combination was already tried
     */
    hasAttemptedScopes(scopes: string[]): boolean;
    /**
     * Reset retry state
     */
    reset(): void;
    /**
     * Get current retry count
     */
    getRetryCount(): number;
    /**
     * Get max retries allowed
     */
    getMaxRetries(): number;
    /**
     * Parse scope string into array
     *
     * @param scopeString - Space-separated scope string
     * @returns Array of individual scopes
     */
    private parseScopeString;
    /**
     * Extract scopes from error description text
     *
     * Looks for patterns like:
     * - "requires the 'admin' scope"
     * - "scope: admin"
     * - "scopes required: admin, user"
     *
     * @param description - Error description text
     * @returns Array of extracted scopes
     */
    private extractScopesFromDescription;
    /**
     * Parse scopes from WWW-Authenticate header
     *
     * Format: Bearer error="insufficient_scope", scope="admin user"
     *
     * @param wwwAuthHeader - WWW-Authenticate header value
     * @returns Array of scopes
     */
    private parseScopesFromWWWAuthenticate;
}
/**
 * Create an InsufficientScopeError from an HTTP error response
 *
 * @param status - HTTP status code
 * @param body - Response body
 * @param headers - Response headers
 * @returns InsufficientScopeError object
 */
export declare function createInsufficientScopeError(status: number, body: any, headers?: Record<string, string>): InsufficientScopeError;
//# sourceMappingURL=step-up-auth.d.ts.map