qa360 2.2.20 → 2.3.1

package/dist/core/auth/webauthn-handler.js

@@ -0,0 +1,310 @@
+/**
+ * WebAuthn / Passkeys Handler
+ *
+ * P1 - Modern passwordless authentication
+ *
+ * Supports:
+ * - WebAuthn registration (credential creation)
+ * - WebAuthn authentication (assertion)
+ * - Passkeys (platform and cross-device)
+ * - Credential ID storage and lookup
+ *
+ * @see https://w3c.github.io/webauthn/
+ */
+/**
+ * WebAuthn Handler class
+ */
+export class WebAuthnHandler {
+    config;
+    credentials = new Map();
+    constructor(config) {
+        this.config = {
+            rpId: config.rpId,
+            rpName: config.rpName,
+            origin: config.origin || `https://${config.rpId}`,
+            userVerification: config.userVerification || 'preferred',
+            attestation: config.attestation || 'none',
+            requireResidentKey: config.requireResidentKey || false,
+        };
+    }
+    /**
+     * Generate a random challenge for WebAuthn
+     */
+    generateChallenge() {
+        const challenge = new Uint8Array(32);
+        crypto.getRandomValues(challenge);
+        return this.bufferToBase64(challenge);
+    }
+    /**
+     * Create registration options for WebAuthn navigator.credentials.create()
+     */
+    createRegistrationOptions(user, excludeCredentials) {
+        const challenge = this.generateChallenge();
+        const userId = this.bufferToBase64(user.id);
+        const options = {
+            challenge,
+            rp: {
+                id: this.config.rpId,
+                name: this.config.rpName,
+            },
+            user: {
+                id: userId,
+                name: user.name,
+                displayName: user.displayName,
+                icon: user.icon,
+            },
+            pubKeyCredParams: [
+                { type: 'public-key', alg: -7 }, // ES256
+                { type: 'public-key', alg: -257 }, // RS256
+                { type: 'public-key', alg: -37 }, // ES512
+            ],
+            authenticatorSelection: {
+                requireResidentKey: this.config.requireResidentKey,
+                userVerification: this.config.userVerification,
+            },
+            attestation: this.config.attestation,
+            timeout: 60000,
+        };
+        // Exclude existing credentials
+        if (excludeCredentials && excludeCredentials.length > 0) {
+            options.excludeCredentials = excludeCredentials.map(id => ({
+                id: this.base64ToBuffer(id).toString(),
+                type: 'public-key',
+            }));
+        }
+        return options;
+    }
+    /**
+     * Parse registration response from navigator.credentials.create()
+     */
+    async parseRegistration(response) {
+        try {
+            // Convert response to parseable format
+            const credential = response;
+            if (!credential || !credential.response) {
+                return { success: false, error: 'Invalid credential response' };
+            }
+            const attestationResponse = credential.response;
+            // Decode client data JSON
+            const clientDataJSON = this.decoder.decode(attestationResponse.clientDataJSON);
+            const clientData = JSON.parse(clientDataJSON);
+            // Verify challenge matches (in production, you'd verify against stored challenge)
+            // Verify origin matches
+            if (clientData.origin !== this.config.origin) {
+                return { success: false, error: `Origin mismatch: expected ${this.config.origin}, got ${clientData.origin}` };
+            }
+            // Verify type
+            if (clientData.type !== 'webauthn.create') {
+                return { success: false, error: `Type mismatch: expected webauthn.create, got ${clientData.type}` };
+            }
+            // Extract credential ID and public key
+            const credentialIdBytes = new Uint8Array(credential.rawId || new ArrayBuffer(0));
+            const credentialId = this.bufferToBase64(credentialIdBytes);
+            // Parse attestation object to get public key
+            let publicKeyObject;
+            try {
+                const attestationObject = this.decoder.decode(attestationResponse.attestationObject);
+                // Simple CBOR parsing would go here - for now we extract what we can
+                publicKeyObject = this.extractPublicKeyFromAttestation(attestationObject);
+            }
+            catch {
+                // Fallback: try to get public key directly
+                if (attestationResponse.getPublicKey) {
+                    publicKeyObject = this.bufferToBase64(new Uint8Array(attestationResponse.getPublicKey()));
+                }
+            }
+            const webAuthnCredential = {
+                id: credentialId,
+                publicKey: publicKeyObject || '',
+                counter: 0,
+                type: 'public-key',
+            };
+            // Store credential
+            this.credentials.set(credentialId, webAuthnCredential);
+            return {
+                success: true,
+                credential: webAuthnCredential,
+            };
+        }
+        catch (e) {
+            return {
+                success: false,
+                error: e instanceof Error ? e.message : 'Unknown error',
+            };
+        }
+    }
+    /**
+     * Create authentication options for WebAuthn navigator.credentials.get()
+     */
+    createAuthenticationOptions(allowedCredentials) {
+        const challenge = this.generateChallenge();
+        const options = {
+            challenge,
+            rpId: this.config.rpId,
+            userVerification: this.config.userVerification,
+            timeout: 60000,
+        };
+        // Add allowed credentials if provided
+        if (allowedCredentials && allowedCredentials.length > 0) {
+            options.allowCredentials = allowedCredentials.map(id => ({
+                id: this.base64ToBuffer(id).toString(),
+                type: 'public-key',
+            }));
+        }
+        return options;
+    }
+    /**
+     * Parse authentication response from navigator.credentials.get()
+     */
+    async parseAuthentication(response) {
+        try {
+            const credential = response;
+            if (!credential || !credential.response) {
+                return { success: false, error: 'Invalid credential response' };
+            }
+            const assertionResponse = credential.response;
+            // Decode client data JSON
+            const clientDataJSON = this.decoder.decode(assertionResponse.clientDataJSON);
+            const clientData = JSON.parse(clientDataJSON);
+            // Verify origin
+            if (clientData.origin !== this.config.origin) {
+                return { success: false, error: `Origin mismatch: expected ${this.config.origin}, got ${clientData.origin}` };
+            }
+            // Verify type
+            if (clientData.type !== 'webauthn.get') {
+                return { success: false, error: `Type mismatch: expected webauthn.get, got ${clientData.type}` };
+            }
+            const credentialId = this.bufferToBase64(new Uint8Array(credential.rawId));
+            // Verify credential exists
+            if (!this.credentials.has(credentialId)) {
+                return { success: false, error: 'Unknown credential' };
+            }
+            // Extract user handle
+            let userHandle;
+            if (assertionResponse.userHandle) {
+                userHandle = this.decoder.decode(assertionResponse.userHandle);
+            }
+            return {
+                success: true,
+                credentialId,
+                userHandle,
+            };
+        }
+        catch (e) {
+            return {
+                success: false,
+                error: e instanceof Error ? e.message : 'Unknown error',
+            };
+        }
+    }
+    /**
+     * Get stored credential by ID
+     */
+    getCredential(credentialId) {
+        return this.credentials.get(credentialId);
+    }
+    /**
+     * Get all stored credentials for a user
+     */
+    getCredentials() {
+        return Array.from(this.credentials.values());
+    }
+    /**
+     * Check if WebAuthn is supported in current browser
+     */
+    isSupported() {
+        return typeof window !== 'undefined' &&
+            typeof window.PublicKeyCredential !== 'undefined';
+    }
+    /**
+     * Check if platform authenticator is available
+     */
+    async isPlatformAvailable() {
+        if (!this.isSupported())
+            return false;
+        try {
+            const available = await window.PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable?.();
+            return available === true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Check if conditional mediation (autofill) is supported
+     */
+    isConditionalMediationSupported() {
+        if (!this.isSupported())
+            return false;
+        // Check for Conditional UI (WebAuthn Conditional UI)
+        return window.PublicKeyCredential.isConditionalMediationAvailable?.() === true;
+    }
+    /**
+     * Store credential externally
+     */
+    storeCredential(credential) {
+        this.credentials.set(credential.id, credential);
+    }
+    /**
+     * Remove credential
+     */
+    removeCredential(credentialId) {
+        return this.credentials.delete(credentialId);
+    }
+    /**
+     * Clear all credentials
+     */
+    clearCredentials() {
+        this.credentials.clear();
+    }
+    /**
+     * Helper: Convert ArrayBuffer to Base64
+     */
+    bufferToBase64(buffer) {
+        const bytes = new Uint8Array(buffer);
+        let binary = '';
+        for (let i = 0; i < bytes.byteLength; i++) {
+            binary += String.fromCharCode(bytes[i]);
+        }
+        return btoa(binary)
+            .replace(/\+/g, '-')
+            .replace(/\//g, '_')
+            .replace(/=/g, '');
+    }
+    /**
+     * Helper: Convert Base64 to Uint8Array
+     */
+    base64ToBuffer(base64) {
+        // Add padding if needed
+        const padded = base64 + '='.repeat((4 - base64.length % 4) % 4);
+        // Replace URL-safe chars
+        const standard = padded.replace(/-/g, '+').replace(/_/g, '/');
+        const binary = atob(standard);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++) {
+            bytes[i] = binary.charCodeAt(i);
+        }
+        return bytes;
+    }
+    /**
+     * Helper to extract public key from attestation object
+     * This is a simplified version - full CBOR parsing would be more complex
+     */
+    extractPublicKeyFromAttestation(attestationObject) {
+        // In a real implementation, you'd parse CBOR properly
+        // For now, return a placeholder that can be overridden
+        if (typeof attestationObject === 'string') {
+            return attestationObject;
+        }
+        const bytes = new Uint8Array(attestationObject);
+        return this.bufferToBase64(bytes.slice(0, Math.min(65, bytes.length)));
+    }
+    decoder = new TextDecoder();
+}
+/**
+ * Factory function to create WebAuthn handler
+ */
+export function createWebAuthnHandler(config) {
+    return new WebAuthnHandler(config);
+}
+export default WebAuthnHandler;

package/dist/core/crawler/advanced-interactions.d.ts

@@ -0,0 +1,342 @@
+/**
+ * QA360 Advanced Interactions Handler
+ *
+ * P0 Features for Enterprise-Grade Testing:
+ * - Shadow DOM support (auto-piercing)
+ * - Iframe handling (same-origin + cross-origin)
+ * - File upload/download
+ *
+ * @since 2.3.0
+ */
+import type { Page, Locator, Frame } from '@playwright/test';
+/**
+ * Configuration for advanced interactions
+ */
+export interface AdvancedInteractionsOptions {
+    /** Maximum shadow DOM depth to pierce (default: 5) */
+    maxShadowDepth?: number;
+    /** Whether to automatically pierce shadow DOM (default: true) */
+    autoShadowPiercing?: boolean;
+    /** Whether to handle iframes (default: true) */
+    handleIframes?: boolean;
+    /** Timeout for frame operations (default: 5000ms) */
+    frameTimeout?: number;
+}
+/**
+ * Element location result with context
+ */
+export interface ElementLocation {
+    /** The element locator */
+    locator: Locator;
+    /** Whether element is in shadow DOM */
+    isInShadowDom: boolean;
+    /** Shadow DOM depth (0 = not in shadow DOM) */
+    shadowDepth: number;
+    /** Nested shadow DOM depth (tracks shadow roots within shadow roots) */
+    nestedShadowDepth?: number;
+    /** Whether element is in iframe */
+    isInIframe: boolean;
+    /** Whether iframe is cross-origin (only meaningful if isInIframe is true) */
+    isCrossOrigin?: boolean;
+    /** Frame selector if in iframe */
+    frameSelector?: string;
+    /** The path taken to find the element */
+    path: string[];
+}
+/**
+ * File upload result
+ */
+export interface FileUploadResult {
+    /** Whether upload succeeded */
+    success: boolean;
+    /** Number of files uploaded */
+    count: number;
+    /** File names uploaded */
+    fileNames: string[];
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * File download result
+ */
+export interface FileDownloadResult {
+    /** Whether download was intercepted */
+    success: boolean;
+    /** Downloaded file path */
+    path?: string;
+    /** File name */
+    fileName?: string;
+    /** File size in bytes */
+    size?: number;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Advanced Interactions Handler
+ *
+ * Handles complex DOM interactions that go beyond simple element selection.
+ */
+export declare class AdvancedInteractionsHandler {
+    private page;
+    private options;
+    private shadowRootCache;
+    private frameCache;
+    constructor(page: Page, options?: AdvancedInteractionsOptions);
+    /**
+     * ═══════════════════════════════════════════════════════════════════════════════
+     * SHADOW DOM SUPPORT
+     * ═══════════════════════════════════════════════════════════════════════════════
+     */
+    /**
+     * Find an element with automatic shadow DOM piercing
+     *
+     * Attempts to find an element in the main DOM first,
+     * then recursively searches through shadow DOM trees.
+     *
+     * @param selector - CSS selector to search for
+     * @param options - Search options
+     * @returns Element location with context
+     */
+    findWithShadowPiercing(selector: string, options?: {
+        timeout?: number;
+        maxDepth?: number;
+    }): Promise<ElementLocation | null>;
+    /**
+     * Recursively search for element in shadow DOM
+     * Supports nested shadow DOM (shadow roots within shadow roots)
+     */
+    private searchInShadowDom;
+    /**
+     * Build a Playwright-compatible selector for shadow DOM elements
+     *
+     * Playwright supports shadow DOM piercing with >> >>
+     */
+    private buildShadowDomSelector;
+    /**
+     * Click an element with shadow DOM support
+     */
+    clickWithShadowPiercing(selector: string): Promise<boolean>;
+    /**
+     * Fill an input with shadow DOM support
+     */
+    fillWithShadowPiercing(selector: string, value: string): Promise<boolean>;
+    /**
+     * ═══════════════════════════════════════════════════════════════════════════════
+     * IFRAME HANDLING
+     * ═══════════════════════════════════════════════════════════════════════════════
+     */
+    /**
+     * Find an element within iframes
+     *
+     * Searches through same-origin iframes recursively.
+     *
+     * @param selector - CSS selector to search for
+     * @param options - Search options
+     * @returns Element location with iframe context
+     */
+    findInIframes(selector: string, options?: {
+        timeout?: number;
+        maxDepth?: number;
+        allowCrossOrigin?: boolean;
+    }): Promise<ElementLocation | null>;
+    /**
+     * Find element in same-origin iframes (faster, direct frame access)
+     */
+    private findInSameOriginIframes;
+    /**
+     * Find element in cross-origin iframes using frameLocator
+     *
+     * For cross-origin iframes, we cannot use frame.waitForSelector() due to SOP.
+     * Instead, we use Playwright's frameLocator which handles cross-origin transparently.
+     */
+    private findInCrossOriginIframes;
+    /**
+     * Recursively search nested iframes
+     */
+    private findInNestedFrames;
+    /**
+     * Get the selector for a frame
+     */
+    private getFrameSelector;
+    /**
+     * Get the selector for an iframe element
+     * Used for cross-origin iframe handling where we have an ElementHandle
+     */
+    private getFrameSelectorForElement;
+    /**
+     * Check if two URLs are same-origin
+     */
+    private isSameOrigin;
+    /**
+     * Interact with element in iframe
+     *
+     * @param iframeSelector - Selector for the iframe
+     * @param elementSelector - Selector for element within iframe
+     * @param action - Action to perform
+     * @returns Action result
+     */
+    interactInIframe(iframeSelector: string, elementSelector: string, action: (frame: Frame) => Promise<any>): Promise<any>;
+    /**
+     * ═══════════════════════════════════════════════════════════════════════════════
+     * FILE OPERATIONS
+     * ═══════════════════════════════════════════════════════════════════════════════
+     */
+    /**
+     * Upload files to an input element
+     *
+     * @param selector - File input selector
+     * @param filePaths - Paths to files to upload
+     * @returns Upload result
+     */
+    uploadFiles(selector: string, filePaths: string | string[]): Promise<FileUploadResult>;
+    /**
+     * Upload files to an input in shadow DOM
+     */
+    private uploadFilesInShadowDom;
+    /**
+     * Handle file download with interception
+     *
+     * @param triggerSelector - Selector for element that triggers download
+     * @param options - Download options
+     * @returns Download result
+     */
+    handleDownload(triggerSelector: string, options?: {
+        action?: 'click' | 'submit';
+        timeout?: number;
+        savePath?: string;
+    }): Promise<FileDownloadResult>;
+    /**
+     * ═══════════════════════════════════════════════════════════════════════════════
+     * COMBINED SEARCH (Shadow DOM + Iframes)
+     * ═══════════════════════════════════════════════════════════════════════════════
+     */
+    /**
+     * Find element anywhere (normal DOM, shadow DOM, or iframes)
+     *
+     * This is the main entry point for finding elements that may be
+     * hidden in shadow DOM or inside iframes.
+     *
+     * @param selector - CSS selector
+     * @param options - Search options
+     * @returns Element location or null
+     */
+    findElementAnywhere(selector: string, options?: {
+        timeout?: number;
+    }): Promise<ElementLocation | null>;
+    /**
+     * P0: Handle print dialog (window.print())
+     *
+     * Uses CDP to automatically dismiss or capture print dialogs.
+     *
+     * @param options - Print handling options
+     * @returns Promise that resolves when print dialog is handled
+     */
+    handlePrintDialog(options?: {
+        /** Action to take: 'dismiss' to cancel, 'capture' to generate PDF */
+        action?: 'dismiss' | 'capture';
+        /** Output path for PDF (when action is 'capture') */
+        path?: string;
+    }): Promise<{
+        handled: boolean;
+        pdfPath?: string;
+    }>;
+    /**
+     * P0: Hover over an element
+     *
+     * Triggers hover state and waits for any visual changes.
+     * Supports elements in shadow DOM and iframes.
+     *
+     * @param selector - CSS selector for the element
+     * @param options - Hover options
+     * @returns Hover result
+     */
+    hover(options: {
+        /** CSS selector for the element */
+        selector: string;
+        /** Whether to wait for animations after hover (default: true) */
+        waitForAnimation?: boolean;
+        /** Animation wait time in ms (default: 100) */
+        animationWait?: number;
+        /** Force hover even if element is not visible */
+        force?: boolean;
+    }): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * P0: Drag and drop operation
+     *
+     * Drags an element and drops it onto a target element.
+     * Supports elements in shadow DOM and iframes.
+     *
+     * @param options - Drag and drop options
+     * @returns Drag result
+     */
+    dragAndDrop(options: {
+        /** CSS selector for the source element to drag */
+        from: string;
+        /** CSS selector for the target element to drop on */
+        to: string;
+        /** Drop position relative to target (default: 'center') */
+        position?: 'top' | 'right' | 'bottom' | 'left' | 'center';
+        /** Whether to verify the drop was successful */
+        verifyDrop?: boolean;
+    }): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * P0: Drag element to specific coordinates
+     *
+     * Drags an element from its current position to specific x, y coordinates.
+     *
+     * @param options - Drag to coordinates options
+     * @returns Drag result
+     */
+    dragToCoordinates(options: {
+        /** CSS selector for the element to drag */
+        selector: string;
+        /** Target X coordinate */
+        x: number;
+        /** Target Y coordinate */
+        y: number;
+        /** Starting X coordinate (default: element center) */
+        fromX?: number;
+        /** Starting Y coordinate (default: element center) */
+        fromY?: number;
+        /** Number of steps for smooth drag (default: 10) */
+        steps?: number;
+    }): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * P0: Multi-select drag (select multiple elements)
+     *
+     * Performs Ctrl+Click on multiple elements to select them.
+     *
+     * @param selectors - Array of CSS selectors to select
+     * @returns Selection result
+     */
+    multiSelect(selectors: string[]): Promise<{
+        success: boolean;
+        selected: number;
+        errors: string[];
+    }>;
+    /**
+     * Get position offset for drop position
+     */
+    private getPositionForDrop;
+    /**
+     * Sleep utility for waiting
+     */
+    private sleep;
+    /**
+     * Clear caches
+     */
+    clearCache(): void;
+}
+/**
+ * Factory function to create handler
+ */
+export declare function createAdvancedInteractionsHandler(page: Page, options?: AdvancedInteractionsOptions): AdvancedInteractionsHandler;