/**
 * Guided Authentication Workflow (INT-010)
 *
 * Provides interactive, step-by-step authentication guidance for government portals
 * and other authenticated sites. Features:
 *
 * 1. User callback for interactive login (MFA, email verification)
 * 2. Step-by-step auth guidance with screenshots
 * 3. Session capture after successful auth
 * 4. Extensible to any authenticated portal
 *
 * Works with AuthFlowDetector to detect auth challenges and AuthWorkflow
 * to store credentials once authentication is complete.
 */
import type { Page } from 'playwright-core';
import type { SessionManager } from './session-manager.js';
import type { AuthFlowDetector } from './auth-flow-detector.js';
/**
 * Authentication step types
 */
export type AuthStepType = 'navigate' | 'enter_username' | 'enter_password' | 'click_submit' | 'mfa_code' | 'email_verify' | 'sms_code' | 'captcha' | 'select_option' | 'accept_terms' | 'security_question' | 'wait' | 'custom';
/**
 * Status of an authentication step
 */
export type AuthStepStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'skipped';
/**
 * Single step in the guided auth workflow
 */
export interface GuidedAuthStep {
    /** Unique step ID */
    id: string;
    /** Step type */
    type: AuthStepType;
    /** Step sequence number */
    sequence: number;
    /** Human-readable instruction */
    instruction: string;
    /** Detailed description/hint */
    description?: string;
    /** Current status */
    status: AuthStepStatus;
    /** CSS selector for the target element (if applicable) */
    selector?: string;
    /** Expected value pattern (for validation) */
    expectedPattern?: RegExp | string;
    /** Screenshot of the current step (base64) */
    screenshot?: string;
    /** Screenshot file path */
    screenshotPath?: string;
    /** When the step was started */
    startedAt?: number;
    /** When the step was completed */
    completedAt?: number;
    /** Error message if step failed */
    error?: string;
    /** User input for this step (masked for passwords) */
    userInput?: string;
    /** Whether this step requires user action */
    requiresUserAction: boolean;
    /** Auto-detect selector hints */
    selectorHints?: string[];
}
/**
 * Authentication session progress
 */
export interface AuthSessionProgress {
    /** Unique session ID */
    sessionId: string;
    /** Domain being authenticated */
    domain: string;
    /** Target URL that triggered auth */
    targetUrl: string;
    /** Current step index */
    currentStepIndex: number;
    /** All steps */
    steps: GuidedAuthStep[];
    /** Overall status */
    status: 'not_started' | 'in_progress' | 'completed' | 'failed' | 'cancelled';
    /** When auth session started */
    startedAt: number;
    /** When auth session completed */
    completedAt?: number;
    /** Error message if failed */
    error?: string;
    /** Whether session was successfully captured */
    sessionCaptured: boolean;
    /** Final screenshot after auth */
    finalScreenshot?: string;
}
/**
 * User action callback for interactive auth
 */
export interface UserAuthActionCallback {
    /** Called when a step requires user input */
    onStepAction: (step: GuidedAuthStep, progress: AuthSessionProgress) => Promise<{
        /** The value/action to perform */
        value?: string;
        /** Whether to skip this step */
        skip?: boolean;
        /** Whether to cancel the entire workflow */
        cancel?: boolean;
    }>;
    /** Called when a screenshot is taken (for UI display) */
    onScreenshot?: (screenshot: string, step: GuidedAuthStep, progress: AuthSessionProgress) => Promise<void>;
    /** Called when step status changes */
    onStepStatusChange?: (step: GuidedAuthStep, progress: AuthSessionProgress) => Promise<void>;
    /** Called when auth completes (success or failure) */
    onComplete?: (success: boolean, progress: AuthSessionProgress, error?: string) => Promise<void>;
}
/**
 * Options for starting a guided auth session
 */
export interface GuidedAuthOptions {
    /** User callback for interactive actions */
    userCallback: UserAuthActionCallback;
    /** Whether to capture screenshots at each step */
    captureScreenshots?: boolean;
    /** Directory to save screenshots */
    screenshotDir?: string;
    /** Session profile name */
    sessionProfile?: string;
    /** Maximum time to wait for auth (ms) */
    maxAuthTimeMs?: number;
    /** Whether to auto-detect login form elements */
    autoDetectForm?: boolean;
    /** Predefined steps (for known sites) */
    predefinedSteps?: Array<Partial<GuidedAuthStep>>;
    /** Cookies to preserve through auth */
    preserveCookies?: boolean;
}
/**
 * Result of a guided auth session
 */
export interface GuidedAuthResult {
    /** Whether authentication was successful */
    success: boolean;
    /** The progress object with all step details */
    progress: AuthSessionProgress;
    /** Session ID for future use */
    sessionId?: string;
    /** Captured cookies (if preserveCookies is true) */
    cookies?: Array<{
        name: string;
        value: string;
        domain: string;
        path: string;
        expires: number;
        httpOnly: boolean;
        secure: boolean;
    }>;
    /** Error message if failed */
    error?: string;
}
export declare class GuidedAuthWorkflow {
    private sessionManager;
    private authFlowDetector;
    private activeSessions;
    constructor();
    /**
     * Configure dependencies
     */
    configure(deps: {
        sessionManager?: SessionManager;
        authFlowDetector?: AuthFlowDetector;
    }): void;
    /**
     * Start a guided authentication workflow
     */
    startAuth(page: Page, loginUrl: string, options: GuidedAuthOptions): Promise<GuidedAuthResult>;
    /**
     * Resume a paused auth session (e.g., after email verification)
     */
    resumeAuth(page: Page, sessionId: string, options: GuidedAuthOptions): Promise<GuidedAuthResult>;
    /**
     * Get active auth session progress
     */
    getSessionProgress(sessionId: string): AuthSessionProgress | undefined;
    /**
     * Cancel an active auth session
     */
    cancelSession(sessionId: string): boolean;
    /**
     * Execute a single auth step
     */
    private executeStep;
    private executeNavigateStep;
    private executeInputStep;
    private executeClickStep;
    private executeWaitStep;
    private executeEmailVerifyStep;
    private executeCaptchaStep;
    private executeSelectStep;
    private executeCustomStep;
    /**
     * Auto-detect login form and create steps
     */
    private autoDetectAndCreateSteps;
    /**
     * Capture session after successful auth
     */
    private captureSession;
    /**
     * Verify authentication was successful
     */
    private verifyAuthSuccess;
    /**
     * Checks if a cookie belongs to the given domain (handles subdomain matching)
     */
    private isCookieForDomain;
    /**
     * Filters cookies that belong to the given domain
     */
    private filterDomainCookies;
    private createStep;
    private stepRequiresUserAction;
    private getSelectorsForStepType;
    private generateSessionId;
    private takeScreenshot;
}
/** Default guided auth workflow instance */
export declare const guidedAuthWorkflow: GuidedAuthWorkflow;
//# sourceMappingURL=guided-auth-workflow.d.ts.map