feat(pir): captcha providers

[madblex]

Asana Task/Github Issue: https://app.asana.com/0/0/1209555302496203

• tech design: https://app.asana.com/0/0/1209498481524623

Description

This PR:

• refactors the captcha action handlers to enable extensibility (see associated tech design)
• adds support for existing captcha providers: recaptcha, recaptcha enterprise, captcha (partially)
• adds scaffolding for cloudflare turnstile
• adds support for the new navigate action, already augmented with the new injectCaptchaHandler property (see associated tech design)
• adds resolveActionHandlers resolver for the action handlers that uses a remote config to determine which version is used

TODO:

• polish up the code, I am still deciding upon some patterns I used, names, etc
• create remote config and wire up the value in resolveActionHandlers
• manual testing
• automated testing
• reference asana tasks next to TODOs

Testing Steps

• cd injected
• npm run playwright should pass

Checklist

Please tick all that apply:

• I have tested this change locally
• I have tested this change locally in all supported browsers
• This change will be visible to users
• I have added automated tests that cover this change
• I have ensured the change is gated by config
• This change was covered by a ship review
• This change was covered by a tech design
• Any dependent config has been merged

[netlify]

✅ Deploy Preview for content-scope-scripts ready!

Name	Link
🔨 Latest commit	12b2e90
🔍 Latest deploy log	https://app.netlify.com/sites/content-scope-scripts/deploys/67daee0b324c410008c1ab73
😎 Deploy Preview	https://deploy-preview-1550--content-scope-scripts.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[github-actions]

Temporary Branch Update

The temporary branch has been updated with the latest changes. Below are the details:

• Branch Name: pr-releases/pr-1550
• Commit Hash: c570642d0786874aea32c00d76ac5804ab712c40
• Install Command: npm i github:duckduckgo/content-scope-scripts#c570642d0786874aea32c00d76ac5804ab712c40

Please use the above install command to update to the latest version.

[github-actions]

[Beta] Generated file diff

Time updated: Wed, 19 Mar 2025 16:17:54 GMT

Android

    - android/brokerProtection.js

File has changed

Integration

    - integration/contentScope.js

File has changed

Windows

    - windows/contentScope.js

File has changed

Apple

    - dist/contentScopeIsolated.js

File has changed

[shakyShane]

Thanks @madblex for your first contribution!

I like the pattern you're thinking of here, I just noted some small things related to matching the existing codebase's patterns around type-safety etc. Here's a small summary:

• 1. try to design richer return types to avoid needing to use exceptions as control flow
• 2. favour implements over extends to avoid class inheritance (this is awkward in JSDoc, but I gave an example in the comments)
• 3. remove 'index' files if they only serve to enable re-exports. In this codebase it's preferred to be explicit about import/exports.
• 4. prefer function foo() { over const foo = () => { in module-level functions

In terms of number 2, I made this change on a branch just to verify the types would still work correctly, you can take a look here bf391d2

[brianhall]

@madblex This looks great to me. I left some comments and did some testing (see below) but nothing blocking from me.

I tested this PR directly in XCode in the following scenarios:

1. Using existing Spokeo JSON file (e.g. no captchaType in getCaptchaInfo) - ✅ Succeeded as expected
2. Using an invalid captchaType in Spokeo's JSON (captchaType: 'bleh') - ❌ Failed as expected
3. Using an explicit captchaType in Spokeo's JSON (captchaType: 'recaptcha2') - ✅ Succeded as expected
4. Using a real but mismatched captchaType in Spokeo's JSON (captchaType: 'cloudflareTurnstile') - ✅ Fell back to recaptcha2 and succeeded.

Very excited to see us in a better place captcha-wise. Great job.

[madblex]

@madblex This looks great to me. I left some comments and did some testing (see below) but nothing blocking from me.

I tested this PR directly in XCode in the following scenarios:

1. Using existing Spokeo JSON file (e.g. no captchaType in getCaptchaInfo) - ✅ Succeeded as expected
2. Using an invalid captchaType in Spokeo's JSON (captchaType: 'bleh') - ❌ Failed as expected
3. Using an explicit captchaType in Spokeo's JSON (captchaType: 'recaptcha2') - ✅ Succeded as expected
4. Using a real but mismatched captchaType in Spokeo's JSON (captchaType: 'cloudflareTurnstile') - ✅ Fell back to recaptcha2 and succeeded.

Very excited to see us in a better place captcha-wise. Great job.

Thanks Brian, and thanks for testing as well! Did a very similar test matrix and it all worked well with the new changes. Ready for another round of reviews.

[brianhall]

These updated changes look great to me.