qa360 2.3.0 → 2.3.2

package/dist/core/auth/recaptcha-handler.d.ts

@@ -0,0 +1,119 @@
+/**
+ * reCAPTCHA Handler
+ *
+ * Supports reCAPTCHA v2 (checkbox) and v3 (score-based, invisible)
+ *
+ * Test mode bypass uses Google's official test keys:
+ * - Site key: 6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-
+ * - Secret key: 6Le-wvkSAAAAAGGOV5XwRZ0nLfwPgJZsYNiWBvvC
+ *
+ * These always return a valid token with predictable score (v3) or success (v2)
+ *
+ * @see https://developers.google.com/recaptcha/docs/faq#id-like-to-run-automated-tests-with-recaptcha.-what-should-i-do
+ */
+export interface RecaptchaV2Config {
+    /** Site key for reCAPTCHA v2 */
+    siteKey?: string;
+    /** Use test mode (always returns valid token) */
+    testMode?: boolean;
+    /** CSS selector for the reCAPTCHA iframe */
+    selector?: string;
+    /** Timeout for solving (ms) */
+    timeout?: number;
+}
+export interface RecaptchaV3Config {
+    /** Site key for reCAPTCHA v3 */
+    siteKey?: string;
+    /** Action name for the request */
+    action?: string;
+    /** Use test mode (always returns score 0.9) */
+    testMode?: boolean;
+    /** Minimum acceptable score (0.0 - 1.0) */
+    minScore?: number;
+    /** Timeout for solving (ms) */
+    timeout?: number;
+}
+export interface RecaptchaTokenResponse {
+    success: boolean;
+    token: string;
+    score?: number;
+    action?: string;
+    challengeTs?: string;
+    hostname?: string;
+    errorCodes?: string[];
+}
+export declare const RECAPTCHA_V2_TEST_SITE_KEY = "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-";
+export declare const RECAPTCHA_V2_TEST_SECRET = "6Le-wvkSAAAAAGGOV5XwRZ0nLfwPgJZsYNiWBvvC";
+export declare const RECAPTCHA_V3_TEST_SITE_KEY = "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-";
+export declare const RECAPTCHA_V3_TEST_SECRET = "6Le-wvkSAAAAAGGOV5XwRZ0nLfwPgJZsYNiWBvvC";
+export declare class RecaptchaHandler {
+    private testMode;
+    private timeout;
+    constructor(options?: {
+        testMode?: boolean;
+        timeout?: number;
+    });
+    /**
+     * Detect if reCAPTCHA is present on the page
+     */
+    detectRecaptcha(page: any): Promise<{
+        present: boolean;
+        version?: 'v2' | 'v3';
+        siteKey?: string;
+    }>;
+    /**
+     * Solve reCAPTCHA v2 (checkbox)
+     *
+     * In test mode, injects a test token
+     * In production, waits for user interaction
+     */
+    solveV2(page: any, config?: RecaptchaV2Config): Promise<RecaptchaTokenResponse>;
+    /**
+     * Solve reCAPTCHA v2 in test mode
+     */
+    private solveV2TestMode;
+    /**
+     * Solve reCAPTCHA v2 in production mode (requires human interaction)
+     */
+    private solveV2Production;
+    /**
+     * Execute reCAPTCHA v3 (invisible, score-based)
+     */
+    executeV3(page: any, config?: RecaptchaV3Config): Promise<RecaptchaTokenResponse>;
+    /**
+     * Verify a reCAPTCHA token (server-side simulation)
+     *
+     * In real usage, this would call Google's siteverify API:
+     * POST https://www.google.com/recaptcha/api/siteverify
+     */
+    verifyToken(token: string, secret?: string): Promise<RecaptchaTokenResponse>;
+    /**
+     * Wait for reCAPTCHA to be ready
+     */
+    waitForReady(page: any, timeout?: number): Promise<boolean>;
+    /**
+     * Inject test site key into page
+     */
+    injectTestSiteKey(page: any, elementSelector: string): Promise<void>;
+    /**
+     * Generate a test token for mocking
+     */
+    private generateTestToken;
+    private sleep;
+    /**
+     * Reset all reCAPTCHA widgets on the page
+     */
+    reset(page: any): Promise<void>;
+    /**
+     * Get the current response token from reCAPTCHA
+     */
+    getResponse(page: any, widgetId?: string): Promise<string | null>;
+}
+/**
+ * Factory function to create a reCAPTCHA handler
+ */
+export declare function createRecaptchaHandler(options?: {
+    testMode?: boolean;
+    timeout?: number;
+}): RecaptchaHandler;
+export default RecaptchaHandler;

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

@@ -0,0 +1,301 @@
+/**
+ * reCAPTCHA Handler
+ *
+ * Supports reCAPTCHA v2 (checkbox) and v3 (score-based, invisible)
+ *
+ * Test mode bypass uses Google's official test keys:
+ * - Site key: 6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-
+ * - Secret key: 6Le-wvkSAAAAAGGOV5XwRZ0nLfwPgJZsYNiWBvvC
+ *
+ * These always return a valid token with predictable score (v3) or success (v2)
+ *
+ * @see https://developers.google.com/recaptcha/docs/faq#id-like-to-run-automated-tests-with-recaptcha.-what-should-i-do
+ */
+// Test keys from Google (always return valid responses)
+export const RECAPTCHA_V2_TEST_SITE_KEY = '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-';
+export const RECAPTCHA_V2_TEST_SECRET = '6Le-wvkSAAAAAGGOV5XwRZ0nLfwPgJZsYNiWBvvC';
+export const RECAPTCHA_V3_TEST_SITE_KEY = '6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-';
+export const RECAPTCHA_V3_TEST_SECRET = '6Le-wvkSAAAAAGGOV5XwRZ0nLfwPgJZsYNiWBvvC';
+// Common reCAPTCHA iframe selectors
+const RECAPTCHA_SELECTORS = [
+    'iframe[src*="recaptcha"]',
+    'iframe[src*="google.com/recaptcha"]',
+    'div.g-recaptcha',
+    'div[data-recaptcha]',
+    'div[data-sitekey]',
+];
+// DOM injection script for bypass
+const BYPASS_SCRIPT = (siteKey, testMode) => `
+  (function() {
+    if (typeof window.grecaptcha !== 'undefined') {
+      // reCAPTCHA already loaded
+      window.__qa360_recaptcha_ready = true;
+      return;
+    }
+
+    // Mock grecaptcha object for test mode
+    if (${testMode}) {
+      window.grecaptcha = {
+        ready: function(cb) { cb(); },
+        execute: function(siteKey, options) {
+          return Promise.resolve('${RECAPTCHA_V2_TEST_SITE_KEY}');
+        },
+        render: function(container, options) {
+          return '${RECAPTCHA_V2_TEST_SITE_KEY}';
+        },
+        reset: function() {},
+        getResponse: function(widgetId) {
+          return 'TEST_TOKEN_SUCCESS';
+        }
+      };
+      window.__qa360_recaptcha_ready = true;
+    }
+  })();
+`;
+export class RecaptchaHandler {
+    testMode;
+    timeout;
+    constructor(options = {}) {
+        this.testMode = options.testMode ?? true;
+        this.timeout = options.timeout ?? 10000;
+    }
+    /**
+     * Detect if reCAPTCHA is present on the page
+     */
+    async detectRecaptcha(page) {
+        const result = await page.evaluate(() => {
+            // Check for v2 checkbox
+            const v2Checkbox = document.querySelector('div.g-recaptcha');
+            const v2DataAttr = document.querySelector('[data-sitekey]');
+            const v2Iframe = document.querySelector('iframe[src*="recaptcha/api2"]');
+            // Check for v3
+            const v3Script = Array.from(document.scripts).some(s => s.src.includes('recaptcha/api3') || s.src.includes('recaptcha/v3'));
+            const hasGrecaptchaV3 = window.grecaptcha?.execute;
+            let version;
+            if (v2Checkbox || v2DataAttr || v2Iframe) {
+                version = 'v2';
+            }
+            else if (v3Script || hasGrecaptchaV3) {
+                version = 'v3';
+            }
+            // Try to extract site key
+            let siteKey;
+            const siteKeyEl = document.querySelector('[data-sitekey]');
+            if (siteKeyEl) {
+                siteKey = siteKeyEl.getAttribute('data-sitekey') || undefined;
+            }
+            return { version, siteKey };
+        });
+        return {
+            present: !!result.version,
+            version: result.version,
+            siteKey: result.siteKey,
+        };
+    }
+    /**
+     * Solve reCAPTCHA v2 (checkbox)
+     *
+     * In test mode, injects a test token
+     * In production, waits for user interaction
+     */
+    async solveV2(page, config = {}) {
+        const { testMode = this.testMode, selector } = config;
+        const detection = await this.detectRecaptcha(page);
+        if (!detection.present || detection.version !== 'v2') {
+            return {
+                success: false,
+                token: '',
+                errorCodes: ['NO_RECAPTCHA_V2_FOUND'],
+            };
+        }
+        if (testMode) {
+            return await this.solveV2TestMode(page, config);
+        }
+        // Production mode: Wait for user to solve
+        return await this.solveV2Production(page, selector);
+    }
+    /**
+     * Solve reCAPTCHA v2 in test mode
+     */
+    async solveV2TestMode(page, config) {
+        const siteKey = config.siteKey || RECAPTCHA_V2_TEST_SITE_KEY;
+        // Inject bypass script
+        await page.evaluate(BYPASS_SCRIPT(siteKey, true));
+        // Set callback token
+        await page.evaluate((testToken) => {
+            const callbackName = '___grecaptcha_cfg';
+            if (window[callbackName]?.fns) {
+                window[callbackName].fns.forEach((cb) => cb(testToken));
+            }
+        }, this.generateTestToken('v2'));
+        return {
+            success: true,
+            token: this.generateTestToken('v2'),
+            challengeTs: new Date().toISOString(),
+            hostname: 'test.google.com',
+        };
+    }
+    /**
+     * Solve reCAPTCHA v2 in production mode (requires human interaction)
+     */
+    async solveV2Production(page, selector) {
+        // Wait for the checkbox to be clicked by user
+        const startTime = Date.now();
+        while (Date.now() - startTime < this.timeout) {
+            const result = await page.evaluate(() => {
+                if (typeof window.grecaptcha === 'undefined') {
+                    return { ready: false, token: null };
+                }
+                const response = window.grecaptcha.getResponse();
+                if (response) {
+                    return { ready: true, token: response };
+                }
+                return { ready: false, token: null };
+            });
+            if (result.ready && result.token) {
+                return {
+                    success: true,
+                    token: result.token,
+                    challengeTs: new Date().toISOString(),
+                };
+            }
+            await this.sleep(500);
+        }
+        return {
+            success: false,
+            token: '',
+            errorCodes: ['TIMEOUT'],
+        };
+    }
+    /**
+     * Execute reCAPTCHA v3 (invisible, score-based)
+     */
+    async executeV3(page, config = {}) {
+        const { testMode = this.testMode, action = 'verify', minScore = 0.5 } = config;
+        if (testMode) {
+            return {
+                success: true,
+                token: this.generateTestToken('v3'),
+                score: 0.9, // Test mode always returns high score
+                action,
+                challengeTs: new Date().toISOString(),
+                hostname: 'test.google.com',
+            };
+        }
+        // Production mode: Call grecaptcha.execute
+        const result = await page.evaluate((act) => {
+            if (typeof window.grecaptcha === 'undefined') {
+                return { success: false, token: null, error: 'GRECAPTCHA_NOT_LOADED' };
+            }
+            return window.grecaptcha.execute(act).then((token) => ({
+                success: true,
+                token,
+            })).catch((err) => ({
+                success: false,
+                token: null,
+                error: err.message,
+            }));
+        }, action);
+        if (!result.success) {
+            return {
+                success: false,
+                token: '',
+                errorCodes: [result.error || 'EXECUTION_FAILED'],
+            };
+        }
+        // In production, we can't verify the score without server-side validation
+        // The token would need to be sent to the backend for verification
+        return {
+            success: true,
+            token: result.token,
+            action,
+        };
+    }
+    /**
+     * Verify a reCAPTCHA token (server-side simulation)
+     *
+     * In real usage, this would call Google's siteverify API:
+     * POST https://www.google.com/recaptcha/api/siteverify
+     */
+    async verifyToken(token, secret) {
+        if (this.testMode) {
+            // In test mode, always return success
+            return {
+                success: true,
+                token,
+                score: 0.9,
+                challengeTs: new Date().toISOString(),
+                hostname: 'test.google.com',
+            };
+        }
+        // Production: Would call siteverify endpoint
+        // For now, return a mock response
+        return {
+            success: false,
+            token,
+            errorCodes: ['SITEVERIFY_NOT_IMPLEMENTED'],
+        };
+    }
+    /**
+     * Wait for reCAPTCHA to be ready
+     */
+    async waitForReady(page, timeout = 10000) {
+        const startTime = Date.now();
+        while (Date.now() - startTime < timeout) {
+            const ready = await page.evaluate(() => typeof window.grecaptcha !== 'undefined');
+            if (ready)
+                return true;
+            await this.sleep(100);
+        }
+        return false;
+    }
+    /**
+     * Inject test site key into page
+     */
+    async injectTestSiteKey(page, elementSelector) {
+        await page.evaluate((sel, testKey) => {
+            const el = document.querySelector(sel);
+            if (el) {
+                el.setAttribute('data-sitekey', testKey);
+            }
+        }, elementSelector, RECAPTCHA_V2_TEST_SITE_KEY);
+    }
+    /**
+     * Generate a test token for mocking
+     */
+    generateTestToken(version) {
+        const timestamp = Date.now();
+        return `TEST_${version}_TOKEN_${timestamp}`;
+    }
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /**
+     * Reset all reCAPTCHA widgets on the page
+     */
+    async reset(page) {
+        await page.evaluate(() => {
+            if (typeof window.grecaptcha !== 'undefined') {
+                window.grecaptcha.reset();
+            }
+        });
+    }
+    /**
+     * Get the current response token from reCAPTCHA
+     */
+    async getResponse(page, widgetId) {
+        return await page.evaluate((id) => {
+            if (typeof window.grecaptcha === 'undefined') {
+                return null;
+            }
+            return window.grecaptcha.getResponse(id);
+        }, widgetId);
+    }
+}
+/**
+ * Factory function to create a reCAPTCHA handler
+ */
+export function createRecaptchaHandler(options) {
+    return new RecaptchaHandler(options);
+}
+export default RecaptchaHandler;

package/dist/core/auth/remember-me-handler.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Remember Me Handler
+ *
+ * P1 - Persistent session management
+ *
+ * Supports:
+ * - Generating secure remember me tokens
+ * - Validating persistent tokens
+ * - Token rotation for security
+ * - Configurable token expiration
+ *
+ * @see https://cheatsheetseries.owasp.org/cheatsheets/Remember_Me_Cheat_Sheet.html
+ */
+export interface RememberMeConfig {
+    /** Token expiration time in days (default: 30) */
+    expiresInDays?: number;
+    /** Token length in bytes (default: 32) */
+    tokenLength?: number;
+    /** Secret key for signing tokens */
+    secret: string;
+    /** Cookie name */
+    cookieName?: string;
+    /** Cookie path */
+    cookiePath?: string;
+    /** Cookie domain */
+    cookieDomain?: string;
+    /** Secure flag for cookies */
+    secure?: boolean;
+    /** HttpOnly flag for cookies */
+    httpOnly?: boolean;
+    /** SameSite attribute */
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+export interface RememberMeToken {
+    /** Token value (selector) */
+    selector: string;
+    /** Validator (hashed token) */
+    validator: string;
+    /** User ID associated with token */
+    userId: string;
+    /** Token expiration timestamp */
+    expiresAt: Date;
+}
+export interface RememberMeResult {
+    success: boolean;
+    token?: RememberMeToken;
+    userId?: string;
+    error?: string;
+}
+/**
+ * Remember Me Handler class
+ */
+export declare class RememberMeHandler {
+    private config;
+    private tokens;
+    /** Store raw validators for testing purposes (in production, only send to client via cookie) */
+    private rawValidators;
+    constructor(config: RememberMeConfig);
+    /**
+     * Generate a new remember me token
+     * Creates a secure random token pair (selector + validator)
+     */
+    generateToken(userId: string): RememberMeToken;
+    /**
+     * Validate a remember me token
+     * Checks selector and validator against stored tokens
+     */
+    validateToken(selector: string, rawValidator: string): RememberMeResult;
+    /**
+     * Rotate a remember me token
+     * Generates a new token while invalidating the old one
+     */
+    rotateToken(selector: string, rawValidator: string): RememberMeResult;
+    /**
+     * Revoke (invalidate) a remember me token
+     */
+    revokeToken(selector: string): boolean;
+    /**
+     * Revoke all tokens for a user
+     */
+    revokeAllUserTokens(userId: string): number;
+    /**
+     * Clean up expired tokens
+     */
+    cleanupExpiredTokens(): number;
+    /**
+     * Get cookie configuration for setting remember me cookie
+     */
+    getCookieConfig(token: RememberMeToken): {
+        name: string;
+        value: string;
+        options: {
+            expires: Date;
+            path: string;
+            domain?: string;
+            secure: boolean;
+            httpOnly: boolean;
+            sameSite: 'Strict' | 'Lax' | 'None';
+        };
+    };
+    /**
+     * Parse cookie value to extract selector and validator
+     */
+    parseCookieValue(cookieValue: string): {
+        selector: string;
+        validator: string;
+    } | null;
+    /**
+     * Check if a token is expired
+     */
+    isTokenExpired(token: RememberMeToken): boolean;
+    /**
+     * Get token by selector
+     */
+    getToken(selector: string): RememberMeToken | undefined;
+    /**
+     * Get all tokens
+     */
+    getAllTokens(): RememberMeToken[];
+    /**
+     * Clear all tokens
+     */
+    clearAllTokens(): void;
+    /**
+     * Set custom secret (for testing)
+     */
+    setSecret(secret: string): void;
+    /**
+     * Get raw validator for a selector (testing only)
+     * In production, the raw validator is only sent to the client via cookie
+     */
+    getRawValidator(selector: string): string | undefined;
+    /**
+     * Get number of active tokens
+     */
+    get tokenCount(): number;
+}
+/**
+ * Factory function to create Remember Me handler
+ */
+export declare function createRememberMeHandler(config: RememberMeConfig): RememberMeHandler;
+export default RememberMeHandler;