Skip to content

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

Bind native CAPTCHA fallback and replay to observed challenges

Emre Sokullu2693132b0a66
diff --git a/src/chrome/src/agent/agent.js b/src/chrome/src/agent/agent.js
index 8e0c4be01..6caa4d0a3 100644
--- a/src/chrome/src/agent/agent.js
+++ b/src/chrome/src/agent/agent.js
@@ -35770,12 +35770,16 @@ If the user has already named or confirmed this exact recipient, do NOT ask agai
}
}
this._nativeCaptchaSolutions ||= new Map();
- const previous = this._nativeCaptchaSolutions.get(tabId);
- if (previous?.pageUrl === websiteURL && Date.now() - previous.createdAt < 180_000) return noDispatchFailure('A native solve was already dispatched for this page. Use its result or ask for manual completion; do not spend again.');
// Record dispatch before sending. Even timeout/failure cannot trigger
- // a second call for this challenge; fallback stays inside one call.
+ // a second call for this document; fallback stays inside one call.
const documents = await captureCaptchaDocuments(tabId, frames, chrome);
- if (!documents.some(d => d.frameId === 0 && d.url === websiteURL)) return noDispatchFailure('Could not bind this page document before the native CAPTCHA request.');
+ const rootDocument = documents.find(d => d.frameId === 0 && d.url === websiteURL);
+ if (!rootDocument) return noDispatchFailure('Could not bind this page document before the native CAPTCHA request.');
+ const previous = this._nativeCaptchaSolutions.get(tabId);
+ const previousRoot = previous?.documents?.find(d => d.frameId === 0);
+ if (previousRoot?.url === rootDocument.url && previousRoot.timeOrigin === rootDocument.timeOrigin) {
+ return noDispatchFailure('A native solve was already dispatched for this page document. Use its result or ask for manual completion; do not spend again.');
+ }
const record = { pageUrl: websiteURL, createdAt: Date.now(), applied: false, documents };
this._nativeCaptchaSolutions.set(tabId, record);
dispatched = true;
diff --git a/src/chrome/src/agent/captcha-native-providers.js b/src/chrome/src/agent/captcha-native-providers.js
index dc663b7c7..337e112df 100644
--- a/src/chrome/src/agent/captcha-native-providers.js
+++ b/src/chrome/src/agent/captcha-native-providers.js
@@ -120,6 +120,13 @@ const FAMILY_IDENTIFIERS = {
yidun: [['challenge'], ['hcg'], ['hct']],
hcaptcha: [['rqdata', 'data.rqdata']],
funcaptcha: [['data']],
+ recaptcha_v3: [['pageAction', 'action', 'data.action']],
+ recaptcha_v3_enterprise: [['pageAction', 'action', 'data.action']],
+ turnstile: [
+ ['action', 'pageAction', 'metadata.action', 'data.action'],
+ ['data', 'cData', 'metadata.cdata', 'data.cdata', 'data.cData'],
+ ['pagedata', 'pageData', 'chlPageData', 'data.pagedata', 'data.pageData', 'data.chlPageData'],
+ ],
};
function validateFallbackIdentifiers(built) {
const family = built[0].contract.family;
@@ -136,7 +143,8 @@ function validateFallbackIdentifiers(built) {
if (versions[0] === 3) groups.push(['challenge']);
}
for (const aliases of groups) {
- const values = built.flatMap(({task}) => aliases.map(path => at(task, path))).filter(usable);
+ const values = built.flatMap(({task}) => aliases.map(path => at(task, path)))
+ .filter(value => usable(value) && !(family === 'turnstile' && aliases.includes('data') && object(value)));
if (new Set(values.map(value => typeof value === 'object' ? JSON.stringify(value) : String(value))).size > 1) {
throw new Error(`Fallback tasks must reference the same observed challenge (${aliases.join('/')}).`);
}
diff --git a/src/firefox/src/agent/agent.js b/src/firefox/src/agent/agent.js
index e972848cc..7e5b40a78 100644
--- a/src/firefox/src/agent/agent.js
+++ b/src/firefox/src/agent/agent.js
@@ -32753,12 +32753,16 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
}
}
this._nativeCaptchaSolutions ||= new Map();
- const previous = this._nativeCaptchaSolutions.get(tabId);
- if (previous?.pageUrl === websiteURL && Date.now() - previous.createdAt < 180_000) return noDispatchFailure('A native solve was already dispatched for this page. Use its result or ask for manual completion; do not spend again.');
// Record dispatch before sending. Even timeout/failure cannot trigger
- // a second call for this challenge; fallback stays inside one call.
+ // a second call for this document; fallback stays inside one call.
const documents = await captureCaptchaDocuments(tabId, frames, browser);
- if (!documents.some(d => d.frameId === 0 && d.url === websiteURL)) return noDispatchFailure('Could not bind this page document before the native CAPTCHA request.');
+ const rootDocument = documents.find(d => d.frameId === 0 && d.url === websiteURL);
+ if (!rootDocument) return noDispatchFailure('Could not bind this page document before the native CAPTCHA request.');
+ const previous = this._nativeCaptchaSolutions.get(tabId);
+ const previousRoot = previous?.documents?.find(d => d.frameId === 0);
+ if (previousRoot?.url === rootDocument.url && previousRoot.timeOrigin === rootDocument.timeOrigin) {
+ return noDispatchFailure('A native solve was already dispatched for this page document. Use its result or ask for manual completion; do not spend again.');
+ }
const record = { pageUrl: websiteURL, createdAt: Date.now(), applied: false, documents };
this._nativeCaptchaSolutions.set(tabId, record);
dispatched = true;
diff --git a/src/firefox/src/agent/captcha-native-providers.js b/src/firefox/src/agent/captcha-native-providers.js
index dc663b7c7..337e112df 100644
--- a/src/firefox/src/agent/captcha-native-providers.js
+++ b/src/firefox/src/agent/captcha-native-providers.js
@@ -120,6 +120,13 @@ const FAMILY_IDENTIFIERS = {
yidun: [['challenge'], ['hcg'], ['hct']],
hcaptcha: [['rqdata', 'data.rqdata']],
funcaptcha: [['data']],
+ recaptcha_v3: [['pageAction', 'action', 'data.action']],
+ recaptcha_v3_enterprise: [['pageAction', 'action', 'data.action']],
+ turnstile: [
+ ['action', 'pageAction', 'metadata.action', 'data.action'],
+ ['data', 'cData', 'metadata.cdata', 'data.cdata', 'data.cData'],
+ ['pagedata', 'pageData', 'chlPageData', 'data.pagedata', 'data.pageData', 'data.chlPageData'],
+ ],
};
function validateFallbackIdentifiers(built) {
const family = built[0].contract.family;
@@ -136,7 +143,8 @@ function validateFallbackIdentifiers(built) {
if (versions[0] === 3) groups.push(['challenge']);
}
for (const aliases of groups) {
- const values = built.flatMap(({task}) => aliases.map(path => at(task, path))).filter(usable);
+ const values = built.flatMap(({task}) => aliases.map(path => at(task, path)))
+ .filter(value => usable(value) && !(family === 'turnstile' && aliases.includes('data') && object(value)));
if (new Set(values.map(value => typeof value === 'object' ? JSON.stringify(value) : String(value))).size > 1) {
throw new Error(`Fallback tasks must reference the same observed challenge (${aliases.join('/')}).`);
}
diff --git a/test/captcha-native-providers.mjs b/test/captcha-native-providers.mjs
index 67e3c9d8f..38887220d 100644
--- a/test/captcha-native-providers.mjs
+++ b/test/captcha-native-providers.mjs
@@ -150,4 +150,24 @@ for (const browser of ['chrome', 'firefox']) {
await assert.rejects(async () => native.solveNativeCaptchaTasks(native.prepareNativeCaptchaTasks(providers, entries)), /same observed challenge/);
assert.equal(calls.length, 0);
});
+ const actionBoundPairs = [
+ ['reCAPTCHA v3 action', ['2captcha', 'RecaptchaV3TaskProxyless', { websiteURL: url, websiteKey: 'site', minScore: 0.3, pageAction: 'login' }], ['solvecaptcha', 'recaptcha_v3', { pageurl: url, googlekey: 'site', action: 'login' }], 'action'],
+ ['reCAPTCHA v3 enterprise action', ['capsolver', 'ReCaptchaV3EnterpriseTaskProxyLess', { websiteURL: url, websiteKey: 'site', pageAction: 'login' }], ['nopecha', 'token/recaptcha3:enterprise', { url, sitekey: 'site', data: { action: 'login' } }], 'data.action'],
+ ['Turnstile action', ['capsolver', 'AntiTurnstileTaskProxyLess', { websiteURL: url, websiteKey: 'site', metadata: { action: 'login', cdata: 'widget' } }], ['anti-captcha', 'TurnstileTaskProxyless', { websiteURL: url, websiteKey: 'site', action: 'login', cData: 'widget' }], 'action'],
+ ['Turnstile cData', ['2captcha', 'TurnstileTaskProxyless', { websiteURL: url, websiteKey: 'site', action: 'login', data: 'widget' }], ['anti-captcha', 'TurnstileTaskProxyless', { websiteURL: url, websiteKey: 'site', action: 'login', cData: 'widget' }], 'cData'],
+ ['Turnstile page data', ['2captcha', 'TurnstileTaskProxyless', { websiteURL: url, websiteKey: 'site', pagedata: 'page' }], ['solvecaptcha', 'turnstile', { pageurl: url, sitekey: 'site', pagedata: 'page' }], 'pagedata'],
+ ['Turnstile nested metadata', ['capmonster', 'TurnstileTask', { websiteURL: url, websiteKey: 'site', pageAction: 'login', data: 'widget' }], ['nopecha', 'token/turnstile', { url, sitekey: 'site', proxy: { scheme: 'http', host: 'proxy.test', port: 8080 }, data: { action: 'login', cdata: 'widget' } }], 'data.cdata'],
+ ];
+ for (const [label, a, b, changed] of actionBoundPairs) test(`${browser}: ${label} mismatch cannot spend`, async t => {
+ const calls = mockApi(t, () => { throw new Error('Must not dispatch'); });
+ const entries = [a, b].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);
+ const path = changed.split('.');
+ let target = entries[1].parameters;
+ for (const part of path.slice(0, -1)) target = target[part];
+ target[path.at(-1)] = 'different';
+ assert.throws(() => native.prepareNativeCaptchaTasks(enabled, entries), /same observed challenge/);
+ assert.equal(calls.length, 0);
+ });
}
diff --git a/test/run.js b/test/run.js
index ef63bc24e..2fcccf9c7 100644
--- a/test/run.js
+++ b/test/run.js
@@ -122022,6 +122022,19 @@ test('CAPTCHA native methods dispatch through the real agent, preserve structure
const cleared = await agent._observeCaptchaChallenge(1, 'get_accessibility_tree', { pageUrl: 'https://example.test/form', pageContent: 'heading "Verification complete"' });
assert.equal(cleared.gate.status, 'cleared', build);
assert.equal(agent._captchaGateBlockResult(1, 'click', {}), null, build);
+ // A paid task may time out after the solution's short application TTL.
+ // Its dispatch lock must still hold for the original document.
+ const prior = agent._nativeCaptchaSolutions.get(1);
+ prior.createdAt = Date.now() - 200_000;
+ delete prior.solution;
+ const aged = await agent._executeToolImpl(1, 'solve_captcha', args);
+ assert.equal(aged.dispatched, false, build);
+ assert.equal(calls.length, 1, build);
+ if (build === 'chrome') api.scripting.executeScript = async () => [{ frameId: 0, result: { url: 'https://example.test/form', timeOrigin: 2000 } }];
+ else api.tabs.executeScript = async () => [{ url: 'https://example.test/form', timeOrigin: 2000 }];
+ const reloaded = await agent._executeToolImpl(1, 'solve_captcha', args);
+ assert.equal(reloaded.success, true, `${build}: new document at the same URL should be eligible: ${reloaded.error}`);
+ assert.equal(calls.length, 2, build);
} finally { globalThis.fetch = previousFetch; }
});
}