feat(pir): captcha providers

Author: madblex

injected/integration-test/test-pages/broker-protection/actions/get-captcha.json

@@ -2,6 +2,7 @@
   "state": {
     "action": {
       "actionType": "getCaptchaInfo",
+      "captchaType": "recaptcha2",
       "selector": ".g-recaptcha",
       "id": "8324"
     }

injected/integration-test/test-pages/broker-protection/actions/solve-captcha.json

@@ -2,6 +2,7 @@
   "state": {
     "action": {
       "actionType": "solveCaptcha",
+      "captchaType": "recaptcha2",
       "id": "83241"
     },
     "data": {

injected/src/features/broker-protection/actions/captcha.js renamed to injected/src/features/broker-protection/actions/captcha-deprecated.js

@@ -1,16 +1,20 @@
 import { captchaCallback } from './captcha-callback.js';
-import { getElement } from '../utils.js';
+import { getElement } from '../utils';
 import { ErrorResponse, SuccessResponse } from '../types.js';
 
 /**
  * Gets the captcha information to send to the backend
  *
- * @param action
+ * @param {import('../types.js').PirAction} action
  * @param {Document | HTMLElement} root
  * @return {import('../types.js').ActionResponse}
  */
 export function getCaptchaInfo(action, root = document) {
     const pageUrl = window.location.href;
+    if (!action.selector) {
+        return new ErrorResponse({ actionID: action.id, message: 'missing selector' });
+    }
+
     const captchaDiv = getElement(root, action.selector);
 
     // if 'captchaDiv' was missing, cannot continue

injected/src/features/broker-protection/actions/click.js

@@ -1,4 +1,4 @@
-import { getElements } from '../utils.js';
+import { getElements } from '../utils';
 import { ErrorResponse, SuccessResponse } from '../types.js';
 import { extractProfiles } from './extract.js';
 import { processTemplateStringWithUserData } from './build-url-transforms.js';

injected/src/features/broker-protection/actions/expectation.js

@@ -1,4 +1,4 @@
-import { getElement } from '../utils.js';
+import { getElement } from '../utils';
 import { ErrorResponse, SuccessResponse } from '../types.js';
 
 /**

injected/src/features/broker-protection/actions/extract.js

@@ -1,4 +1,4 @@
-import { cleanArray, getElement, getElementMatches, getElements, sortAddressesByStateAndCity } from '../utils.js'; // Assuming you have imported the address comparison function
+import { cleanArray, getElement, getElementMatches, getElements, sortAddressesByStateAndCity } from '../utils'; // Assuming you have imported the address comparison function
 import { ErrorResponse, ProfileResult, SuccessResponse } from '../types.js';
 import { isSameAge } from '../comparisons/is-same-age.js';
 import { isSameName } from '../comparisons/is-same-name.js';

injected/src/features/broker-protection/actions/fill-form.js

@@ -1,4 +1,4 @@
-import { getElement, generateRandomInt } from '../utils.js';
+import { getElement, generateRandomInt } from '../utils';
 import { ErrorResponse, SuccessResponse } from '../types.js';
 import { generatePhoneNumber, generateZipCode, generateStreetAddress } from './generators.js';
 

injected/src/features/broker-protection/actions/generators.js

@@ -1,4 +1,4 @@
-import { generateRandomInt } from '../utils.js';
+import { generateRandomInt } from '../utils';
 
 export function generatePhoneNumber() {
     /**

injected/src/features/broker-protection/actions/index.js

@@ -0,0 +1,31 @@
+import { extract } from './extract.js';
+import { fillForm } from './fill-form.js';
+import { click } from './click.js';
+import { expectation } from './expectation.js';
+import { navigate } from './navigate';
+import { buildUrl } from './build-url';
+import * as captchaHandlers from '../captcha-services';
+import * as deprecatedCaptchaHandlers from './captcha-deprecated';
+
+/**
+ * Returns the captcha handlers based on the useNewActionHandlers flag
+ * @param {Object} params
+ * @param {boolean} params.useNewActionHandlers
+ */
+export const resolveActionHandlers = ({ useNewActionHandlers }) => {
+    return {
+        extract,
+        fillForm,
+        click,
+        expectation,
+        ...(useNewActionHandlers
+            ? {
+                  navigate,
+                  ...captchaHandlers,
+              }
+            : {
+                  navigate: buildUrl,
+                  ...deprecatedCaptchaHandlers,
+              }),
+    };
+};

injected/src/features/broker-protection/actions/navigate.js

@@ -0,0 +1,31 @@
+import { getSupportingCodeToInject } from '../captcha-services';
+import { ErrorResponse, SuccessResponse } from '../types';
+import { buildUrl } from './build-url';
+
+/**
+ * This builds the proper URL given the URL template and userData.
+ * Also, if the action requires a captcha handler, it will inject the necessary code.
+ *
+ * @param {import('../types.js').PirAction} action
+ * @param {Record<string, any>} userData
+ * @return {import('../types.js').ActionResponse}
+ */
+export const navigate = (action, userData) => {
+    const { id: actionID, actionType, injectCaptchaHandler } = action;
+    try {
+        const urlResult = buildUrl(action, userData);
+        if (urlResult instanceof ErrorResponse) {
+            return urlResult;
+        }
+
+        const codeToInject = injectCaptchaHandler ? getSupportingCodeToInject(injectCaptchaHandler) : null;
+        const response = {
+            ...urlResult.success.response,
+            ...(codeToInject && { code: codeToInject }),
+        };
+
+        return new SuccessResponse({ actionID, actionType, response });
+    } catch (e) {
+        return new ErrorResponse({ actionID, message: `[navigate] ${e.message}` });
+    }
+};

injected/src/features/broker-protection/captcha-services/captcha.service.js

@@ -0,0 +1,87 @@
+import { getElement, removeUrlQueryParams } from '../utils';
+import { ErrorResponse, SuccessResponse } from '../types';
+import { getCaptchaProvider, getCaptchaSolveProvider } from './get-captcha-provider';
+import { captchaFactory } from './providers';
+
+/**
+ * Returns the supporting code to inject for the given captcha type
+ *
+ * @param {import('../types.js').PirAction['captchaType']} captchaType
+ * @return string
+ * @throws {Error}
+ */
+export const getSupportingCodeToInject = (captchaType) => {
+    const captchaProvider = captchaFactory.getProviderByType(captchaType);
+    if (!captchaProvider) {
+        throw new Error(`[injectCaptchaHandler] could not find captchaProvider with type ${captchaType}`);
+    }
+
+    return captchaProvider.getSupportingCodeToInject();
+};
+
+/**
+ * Gets the captcha information to send to the backend
+ *
+ * @param {import('../types.js').PirAction} action
+ * @param {Document | HTMLElement} root
+ * @return {import('../types.js').ActionResponse}
+ */
+export const getCaptchaInfo = (action, root = document) => {
+    const { id: actionID, selector, actionType, captchaType } = action;
+    try {
+        if (!selector) {
+            throw new Error('missing selector');
+        }
+
+        const captchaContainer = getElement(root, selector);
+        if (!captchaContainer) {
+            throw new Error(`could not find captchaContainer with selector ${selector}`);
+        }
+
+        const captchaProvider = getCaptchaProvider(captchaContainer, captchaType);
+        const captchaIdentifier = captchaProvider.getCaptchaIdentifier(captchaContainer);
+        if (!captchaIdentifier) {
+            throw new Error(`could not extract captcha identifier from ${captchaType} captcha`);
+        }
+
+        const response = {
+            url: removeUrlQueryParams(window.location.href), // query params (which may include PII)
+            siteKey: captchaIdentifier,
+            type: captchaProvider.getType(),
+        };
+        return new SuccessResponse({ actionID, actionType, response });
+    } catch (e) {
+        return new ErrorResponse({ actionID, message: `[getCaptchaInfo] ${e.message}` });
+    }
+};
+
+/**
+ * Takes the solved captcha token and injects it into the page to solve the captcha
+ *
+ * @param {import('../types.js').PirAction} action
+ * @param {string} token
+ * @param {Document} root
+ * @return {import('../types.js').ActionResponse}
+ */
+export const solveCaptcha = (action, token, root = document) => {
+    const { id: actionID, actionType, captchaType } = action;
+    try {
+        if (!captchaType) {
+            throw new Error('missing captchaType');
+        }
+
+        const captchaSolveProvider = getCaptchaSolveProvider(root, captchaType);
+        if (!captchaSolveProvider.canSolve(root)) {
+            throw new Error(`[solveCaptcha] cannot solve captcha with type ${captchaType}`);
+        }
+
+        captchaSolveProvider.injectToken(root, token);
+        return new SuccessResponse({
+            actionID,
+            actionType,
+            response: { callback: { eval: captchaSolveProvider.getSolveCallback(token) } },
+        });
+    } catch (e) {
+        return new ErrorResponse({ actionID, message: `[solveCaptcha] ${e.message}` });
+    }
+};

injected/src/features/broker-protection/captcha-services/factory.js

@@ -0,0 +1,48 @@
+/**
+ * Factory for captcha providers
+ */
+export class CaptchaFactory {
+    constructor() {
+        this.providers = new Map();
+    }
+
+    /**
+     * Register a captcha provider
+     * @param {typeof import('./providers/provider.interface').CaptchaProvider} ProviderClass
+     */
+    registerProvider(ProviderClass) {
+        const provider = new ProviderClass();
+        this.providers.set(provider.getType(), provider);
+    }
+
+    /**
+     * Get a provider by type
+     * @param {string} type - The provider type
+     * @returns {import('./providers/provider.interface').CaptchaProvider|null}
+     */
+    getProviderByType(type) {
+        return this.providers.get(type) || null;
+    }
+
+    /**
+     * Detect the captcha provider based on the element
+     * @param {HTMLElement} element - The element to check
+     * @returns {import('./providers/provider.interface').CaptchaProvider|null}
+     */
+    detectProvider(element) {
+        return this._getAllProviders().find((provider) => provider.isSupportedForElement(element)) || null;
+    }
+
+    detectSolveProvider(root) {
+        return this._getAllProviders().find((provider) => provider.canSolve(root)) || null;
+    }
+
+    /**
+     * Get all registered providers
+     * @private
+     * @returns {Array<import('./providers/provider.interface').CaptchaProvider>}
+     */
+    _getAllProviders() {
+        return Array.from(this.providers.values());
+    }
+}

injected/src/features/broker-protection/captcha-services/get-captcha-provider.js

@@ -0,0 +1,62 @@
+import { captchaFactory } from './providers';
+
+/**
+ * Gets the captcha provider for the getCaptchaInfo action
+ *
+ * @param {HTMLElement} captchaDiv
+ * @param {string} captchaType
+ * @return {import('./providers/provider.interface.js').CaptchaProvider}
+ * @throws {Error}
+ */
+export const getCaptchaProvider = (captchaDiv, captchaType) => {
+    const captchaProvider = captchaFactory.getProviderByType(captchaType);
+    if (!captchaProvider) {
+        throw new Error(`[getCaptchaProvider] could not find captchaProvider with type ${captchaType}`);
+    }
+
+    if (captchaProvider.isSupportedForElement(captchaDiv)) {
+        return captchaProvider;
+    }
+
+    // TODO fire a pixel
+    // if the captcha provider type is different from the expected type, log a warning
+    console.warn(
+        `[getCaptchaProvider] mismatch between expected captha type ${captchaType} and detected type ${captchaProvider.getType()}`,
+    );
+    const detectedProvider = captchaFactory.detectProvider(captchaDiv);
+    if (!detectedProvider) {
+        throw new Error(`[getCaptchaProvider] could not detect captcha provider for ${captchaType} captcha and element ${captchaDiv}`);
+    }
+
+    return detectedProvider;
+};
+
+/**
+ * Gets the captcha provider for the solveCaptcha action
+ * @param {Document} root
+ * @param {string} captchaType
+ * @return {import('./providers/provider.interface.js').CaptchaProvider}
+ * @throws {Error}
+ */
+export const getCaptchaSolveProvider = (root, captchaType) => {
+    const captchaProvider = captchaFactory.getProviderByType(captchaType);
+    if (!captchaProvider) {
+        throw new Error(`[getCaptchaSolveProvider] could not find captchaProvider with type ${captchaType}`);
+    }
+
+    if (captchaProvider.canSolve(root)) {
+        return captchaProvider;
+    }
+
+    // TODO fire a pixel
+    // if the captcha provider type is different from the expected type, log a warning
+    console.warn(
+        `[getCaptchaSolveProvider] mismatch between expected captha type ${captchaType} and detected type ${captchaProvider.getType()}`,
+    );
+    const detectedProvider = captchaFactory.detectSolveProvider(root);
+    if (!detectedProvider) {
+        throw new Error(`[getCaptchaSolveProvider] could not detect captcha provider for ${captchaType} captcha and element ${root}`);
+    }
+
+    return detectedProvider;
+};

injected/src/features/broker-protection/captcha-services/index.js

@@ -0,0 +1 @@
+export { getSupportingCodeToInject, getCaptchaInfo, solveCaptcha } from './captcha.service';

injected/src/features/broker-protection/captcha-services/providers/cloudflare-turnstile.js

@@ -0,0 +1,52 @@
+import { CaptchaProvider } from './provider.interface';
+
+export class CloudFlareTurnstileProvider extends CaptchaProvider {
+    getType() {
+        return 'cloudflareTurnstile';
+    }
+
+    /**
+     * @param {HTMLElement} captchaContainerElement
+     */
+    isSupportedForElement(captchaContainerElement) {
+        // TODO: Implement
+        return false;
+    }
+
+    /**
+     * @param {HTMLElement} captchaContainerElement - The element containing the captcha
+     */
+    getCaptchaIdentifier(captchaContainerElement) {
+        // TODO: Implement
+        return null;
+    }
+
+    getSupportingCodeToInject() {
+        // TODO: Implement
+        return null;
+    }
+
+    /**
+     * @param {Document} root - The document root to search for captchas
+     */
+    canSolve(root) {
+        // TODO: Implement
+        return false;
+    }
+
+    /**
+     * @param {Document} root - The document root containing the captcha
+     * @param {string} token - The solved captcha token
+     */
+    injectToken(root, token) {
+        // TODO: Implement
+        return false;
+    }
+
+    /**
+     * @param {string} token - The solved captcha token
+     */
+    getSolveCallback(token) {
+        return null;
+    }
+}