Skip to content

Open-source AI browser agent for Chrome and Firefox (monorepo) 🧠

Match CAPTCHA fallback instructions and visibility

Emre Sokullu7e7187529c80
diff --git a/docs/captcha-provider-coverage.md b/docs/captcha-provider-coverage.md
index 58d03b134..f1c86185d 100644
--- a/docs/captcha-provider-coverage.md
+++ b/docs/captcha-provider-coverage.md
@@ -137,7 +137,7 @@ Use observed page parameters to prepare fallback tasks. Method IDs are WebBrain
Saved weights determine execution order, regardless of array order. Supply a task for each enabled provider that can solve that family and for which the required inputs are available. The tool does not invent another provider's parameters. Page URLs must belong to the active tab or an observed frame. Native methods do not automatically scrape every site's internal configuration.
-Provider-specific identifiers (for example `appId`/`app_id` and `miseryKey`/`misery_key`) must agree across fallback entries before any paid request.
+Provider-specific identifiers (for example `appId`/`app_id` and `miseryKey`/`misery_key`) must agree across fallback entries before any paid request. Recognition fallbacks must use the same image/audio and selection instruction. reCAPTCHA v2 fallbacks must also agree on `data-s` and visible/invisible mode when supplied.
`solution` remains structured: tokens, cookie values, GeeTest objects, coordinates, arrays of booleans, text, and provider-specific response fields are not coerced into a single token string. A synchronous ready response is consumed without a redundant polling request.
diff --git a/src/chrome/src/agent/captcha-native-providers.js b/src/chrome/src/agent/captcha-native-providers.js
index 6736dcb03..f4f6c7d52 100644
--- a/src/chrome/src/agent/captcha-native-providers.js
+++ b/src/chrome/src/agent/captcha-native-providers.js
@@ -205,9 +205,22 @@ function validateFallbackIdentifiers(built) {
const parts = family === 'temu_recognition'
? task.parts || [task.part1, task.part2, task.part3]
: null;
- return JSON.stringify([media[0], parts]);
+ const instructions = ['comment', 'task', 'question', 'metadata.Task', 'metadata.TaskDefinition', 'metadata.TaskArgument']
+ .map(path => at(task, path)).filter(usable);
+ if (new Set(instructions.map(String)).size > 1) throw new Error('Fallback recognition tasks must use the same observed challenge instructions.');
+ return JSON.stringify([media[0], parts, instructions[0] ?? null]);
});
- if (new Set(signatures).size > 1) throw new Error('Fallback recognition tasks must use the same observed challenge media.');
+ if (new Set(signatures).size > 1) throw new Error('Fallback recognition tasks must use the same observed challenge media and instructions.');
+ }
+ if (['recaptcha_v2', 'recaptcha_v2_enterprise'].includes(family)) {
+ const modes = built.map(({ task }) => task.isInvisible ?? task.invisible);
+ if (modes.some(mode => mode !== undefined)) {
+ if (modes.some(mode => ![true, false, 0, 1].includes(mode))
+ || new Set(modes.map(mode => mode === true || mode === 1 ? 'invisible'
+ : mode === false || mode === 0 ? 'visible' : 'missing')).size > 1) {
+ throw new Error('Fallback tasks must use the same observed reCAPTCHA visibility mode.');
+ }
+ }
}
const groups = [
{ aliases: ['websiteURL', 'pageurl', 'url'], requireAll: false },
diff --git a/src/firefox/src/agent/captcha-native-providers.js b/src/firefox/src/agent/captcha-native-providers.js
index 6736dcb03..f4f6c7d52 100644
--- a/src/firefox/src/agent/captcha-native-providers.js
+++ b/src/firefox/src/agent/captcha-native-providers.js
@@ -205,9 +205,22 @@ function validateFallbackIdentifiers(built) {
const parts = family === 'temu_recognition'
? task.parts || [task.part1, task.part2, task.part3]
: null;
- return JSON.stringify([media[0], parts]);
+ const instructions = ['comment', 'task', 'question', 'metadata.Task', 'metadata.TaskDefinition', 'metadata.TaskArgument']
+ .map(path => at(task, path)).filter(usable);
+ if (new Set(instructions.map(String)).size > 1) throw new Error('Fallback recognition tasks must use the same observed challenge instructions.');
+ return JSON.stringify([media[0], parts, instructions[0] ?? null]);
});
- if (new Set(signatures).size > 1) throw new Error('Fallback recognition tasks must use the same observed challenge media.');
+ if (new Set(signatures).size > 1) throw new Error('Fallback recognition tasks must use the same observed challenge media and instructions.');
+ }
+ if (['recaptcha_v2', 'recaptcha_v2_enterprise'].includes(family)) {
+ const modes = built.map(({ task }) => task.isInvisible ?? task.invisible);
+ if (modes.some(mode => mode !== undefined)) {
+ if (modes.some(mode => ![true, false, 0, 1].includes(mode))
+ || new Set(modes.map(mode => mode === true || mode === 1 ? 'invisible'
+ : mode === false || mode === 0 ? 'visible' : 'missing')).size > 1) {
+ throw new Error('Fallback tasks must use the same observed reCAPTCHA visibility mode.');
+ }
+ }
}
const groups = [
{ aliases: ['websiteURL', 'pageurl', 'url'], requireAll: false },
diff --git a/test/captcha-native-providers.mjs b/test/captcha-native-providers.mjs
index dd3b50952..7468ed36f 100644
--- a/test/captcha-native-providers.mjs
+++ b/test/captcha-native-providers.mjs
@@ -297,10 +297,26 @@ for (const browser of ['chrome', 'firefox']) {
assert.throws(() => native.prepareNativeCaptchaTasks(entries.map(entry => ({ id: entry.provider, apiKey: 'key' })), entries), /same observed challenge|same proxy identity/);
assert.equal(calls.length, 0);
});
+ for (const [family, first, second] of [
+ ['v2', ['2captcha', 'RecaptchaV2TaskProxyless', { websiteURL: url, websiteKey: 'site', isInvisible: true }], ['solvecaptcha', 'recaptcha_v2', { pageurl: url, googlekey: 'site', invisible: 1 }]],
+ ['v2 enterprise', ['2captcha', 'RecaptchaV2EnterpriseTaskProxyless', { websiteURL: url, websiteKey: 'site', isInvisible: true }], ['solvecaptcha', 'recaptcha_v2_enterprise', { pageurl: url, googlekey: 'site', invisible: 1 }]],
+ ]) test(`${browser}: reCAPTCHA ${family} visibility agrees before fallback`, t => {
+ const calls = mockApi(t, () => { throw new Error('Must not dispatch'); });
+ const entries = [first, second].map(([provider, method, parameters]) => ({ provider, method, parameters: structuredClone(parameters) }));
+ const enabled = entries.map(entry => ({ id: entry.provider, apiKey: 'key' }));
+ assert.equal(native.prepareNativeCaptchaTasks(enabled, entries).length, 2);
+ entries[1].parameters.invisible = 0;
+ assert.throws(() => native.prepareNativeCaptchaTasks(enabled, entries), /same observed reCAPTCHA visibility mode/);
+ delete entries[1].parameters.invisible;
+ assert.throws(() => native.prepareNativeCaptchaTasks(enabled, entries), /same observed reCAPTCHA visibility mode/);
+ assert.equal(calls.length, 0);
+ });
const recognitionPairs = [
['coordinates body', ['2captcha', 'CoordinatesTask', { body: 'image-A' }], ['solvecaptcha', 'coordinates', { body: 'image-A' }], task => { task.body = 'image-B'; }],
['image-to-text array alias', ['2captcha', 'ImageToTextTask', { body: 'image-A' }], ['nopecha', 'recognition/textcaptcha', { image_data: ['image-A'] }], task => { task.image_data = ['image-B']; }],
['Temu parts', ['2captcha', 'TemuImageTask', { image: 'background', parts: ['one', 'two', 'three'] }], ['solvecaptcha', 'temuimage', { body: 'background', part1: 'one', part2: 'two', part3: 'three' }], task => { task.part2 = 'different'; }],
+ ['FunCaptcha instruction', ['2captcha', 'GridTask:funcaptcha_recognition', { body: 'image-A', comment: 'cars' }], ['nopecha', 'recognition/funcaptcha', { image_data: ['image-A'], task: 'cars' }], task => { task.task = 'bicycles'; }],
+ ['reCAPTCHA recognition instruction', ['capsolver', 'ReCaptchaV2Classification', { image: 'image-A', question: 'cars' }], ['nopecha', 'recognition/recaptcha', { image_data: ['image-A'], grid: '3x3', task: 'cars' }], task => { task.task = 'bicycles'; }],
];
for (const [label, a, b, change] of recognitionPairs) test(`${browser}: ${label} must match before paid fallback`, t => {
const calls = mockApi(t, () => { throw new Error('Must not dispatch'); });