Skip to content

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

Retire stale CAPTCHA gates and validate Cloudflare fallbacks

Emre Sokullu94ca77379297
diff --git a/src/chrome/src/agent/agent.js b/src/chrome/src/agent/agent.js
index 15621974b..feece0e5a 100644
--- a/src/chrome/src/agent/agent.js
+++ b/src/chrome/src/agent/agent.js
@@ -10851,7 +10851,9 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
// Keep dispatchedTimeOrigins to prevent a second paid solve if the old
// document is restored, but never apply its answer to the new page.
delete record.solution;
+ return true;
}
+ return false;
}
_captchaRoutingMessage(tabId, captchaGateDecision, captchaSolveOutcome, toolResult = {}, onUpdate = () => {}) {
@@ -10996,8 +10998,9 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
if (!Agent.NAV_TOOLS.has(toolName)) return null;
const beforeDocument = this._normalizeUrlPath(beforeUrl);
const afterDocument = this._normalizeUrlPath(afterUrl);
- if (!beforeDocument || !afterDocument || beforeDocument === afterDocument) return null;
- this._retireNativeCaptchaAnswerIfPageChanged(tabId, afterUrl);
+ if (!beforeDocument || !afterDocument) return null;
+ const nativeAnswerRetired = this._retireNativeCaptchaAnswerIfPageChanged(tabId, afterUrl);
+ if (beforeDocument === afterDocument && !nativeAnswerRetired) return null;
const gate = this._captchaGateStates.get(tabId);
if (!gate) return null;
const clearedGate = {
@@ -11192,7 +11195,7 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
return { gate, loopCheck: { kind: 'none' } };
}
- const activeGate = this._captchaGateForTools(tabId, this._captchaGateStates.get(tabId));
+ let activeGate = this._captchaGateForTools(tabId, this._captchaGateStates.get(tabId));
const treeFilter = String(toolArgs?.filter || 'all').toLowerCase();
let observedChallengeFrameId = Number.isInteger(toolResult.captchaChallengeFrameId)
? toolResult.captchaChallengeFrameId
@@ -11233,7 +11236,12 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
try { pageUrl = await this._currentUrl(tabId); } catch {}
}
if (pageUrl && this._nativeCaptchaSolutions?.get(tabId)?.pageUrl !== pageUrl) {
- try { this._retireNativeCaptchaAnswerIfPageChanged(tabId, await this._currentUrl(tabId)); } catch {}
+ try {
+ if (this._retireNativeCaptchaAnswerIfPageChanged(tabId, await this._currentUrl(tabId))) {
+ this._captchaGateStates.delete(tabId);
+ activeGate = null;
+ }
+ } catch {}
}
let detection = null;
let detectionFailed = false;
diff --git a/src/chrome/src/agent/captcha-native-providers.js b/src/chrome/src/agent/captcha-native-providers.js
index 01aec9ebe..9a6760c46 100644
--- a/src/chrome/src/agent/captcha-native-providers.js
+++ b/src/chrome/src/agent/captcha-native-providers.js
@@ -209,8 +209,33 @@ function funcaptchaServiceHost(value) {
return url.host.toLowerCase();
} catch { throw new Error('Fallback FunCaptcha tasks must use comparable service hosts.'); }
}
+function cloudflareChallengeSignature({ contract, task }) {
+ const mode = contract.provider === 'capsolver' && contract.method === 'AntiCloudflareTask'
+ ? 'cf_clearance' : task.cloudflareTaskType;
+ if (mode === 'cf_clearance') {
+ let html = task.html;
+ if (task.htmlPageBase64 !== undefined) {
+ try {
+ const bytes = Uint8Array.from(atob(task.htmlPageBase64), char => char.charCodeAt(0));
+ html = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+ } catch {
+ throw new Error('Fallback Cloudflare challenge requires a valid page snapshot.');
+ }
+ }
+ if (!usable(html)) throw new Error('Fallback Cloudflare challenge requires the same observed page snapshot.');
+ return JSON.stringify([mode, html]);
+ }
+ if (mode === 'token') {
+ return JSON.stringify([mode, task.pageAction, task.data, task.pageData, task.apiJsUrl ?? null]);
+ }
+ throw new Error('Fallback Cloudflare challenge requires a comparable task mode.');
+}
function validateFallbackIdentifiers(built) {
const family = built[0].contract.family;
+ if (family === 'cloudflare_challenge' && built.length > 1
+ && new Set(built.map(cloudflareChallengeSignature)).size > 1) {
+ throw new Error('Fallback Cloudflare tasks must use the same challenge mode and observed page snapshot.');
+ }
if (family === 'funcaptcha' && built.length > 1) {
const services = built.map(({ task }) => task.funcaptchaApiJSSubdomain || task.surl);
if (services.some(usable)) {
diff --git a/src/firefox/src/agent/agent.js b/src/firefox/src/agent/agent.js
index c5c658fe5..e3b151fdb 100644
--- a/src/firefox/src/agent/agent.js
+++ b/src/firefox/src/agent/agent.js
@@ -9465,7 +9465,9 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
// Keep dispatchedTimeOrigins to prevent a second paid solve if the old
// document is restored, but never apply its answer to the new page.
delete record.solution;
+ return true;
}
+ return false;
}
_captchaRoutingMessage(tabId, captchaGateDecision, captchaSolveOutcome, toolResult = {}, onUpdate = () => {}) {
@@ -9610,8 +9612,9 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
if (!Agent.NAV_TOOLS.has(toolName)) return null;
const beforeDocument = this._normalizeUrlPath(beforeUrl);
const afterDocument = this._normalizeUrlPath(afterUrl);
- if (!beforeDocument || !afterDocument || beforeDocument === afterDocument) return null;
- this._retireNativeCaptchaAnswerIfPageChanged(tabId, afterUrl);
+ if (!beforeDocument || !afterDocument) return null;
+ const nativeAnswerRetired = this._retireNativeCaptchaAnswerIfPageChanged(tabId, afterUrl);
+ if (beforeDocument === afterDocument && !nativeAnswerRetired) return null;
const gate = this._captchaGateStates.get(tabId);
if (!gate) return null;
const clearedGate = {
@@ -9797,7 +9800,7 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
return { gate, loopCheck: { kind: 'none' } };
}
- const activeGate = this._captchaGateForTools(tabId, this._captchaGateStates.get(tabId));
+ let activeGate = this._captchaGateForTools(tabId, this._captchaGateStates.get(tabId));
const treeFilter = String(toolArgs?.filter || 'all').toLowerCase();
let observedChallengeFrameId = Number.isInteger(toolResult.captchaChallengeFrameId)
? toolResult.captchaChallengeFrameId
@@ -9838,7 +9841,12 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
try { pageUrl = await this._currentUrl(tabId); } catch {}
}
if (pageUrl && this._nativeCaptchaSolutions?.get(tabId)?.pageUrl !== pageUrl) {
- try { this._retireNativeCaptchaAnswerIfPageChanged(tabId, await this._currentUrl(tabId)); } catch {}
+ try {
+ if (this._retireNativeCaptchaAnswerIfPageChanged(tabId, await this._currentUrl(tabId))) {
+ this._captchaGateStates.delete(tabId);
+ activeGate = null;
+ }
+ } catch {}
}
let detection = null;
let detectionFailed = false;
diff --git a/src/firefox/src/agent/captcha-native-providers.js b/src/firefox/src/agent/captcha-native-providers.js
index 01aec9ebe..9a6760c46 100644
--- a/src/firefox/src/agent/captcha-native-providers.js
+++ b/src/firefox/src/agent/captcha-native-providers.js
@@ -209,8 +209,33 @@ function funcaptchaServiceHost(value) {
return url.host.toLowerCase();
} catch { throw new Error('Fallback FunCaptcha tasks must use comparable service hosts.'); }
}
+function cloudflareChallengeSignature({ contract, task }) {
+ const mode = contract.provider === 'capsolver' && contract.method === 'AntiCloudflareTask'
+ ? 'cf_clearance' : task.cloudflareTaskType;
+ if (mode === 'cf_clearance') {
+ let html = task.html;
+ if (task.htmlPageBase64 !== undefined) {
+ try {
+ const bytes = Uint8Array.from(atob(task.htmlPageBase64), char => char.charCodeAt(0));
+ html = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+ } catch {
+ throw new Error('Fallback Cloudflare challenge requires a valid page snapshot.');
+ }
+ }
+ if (!usable(html)) throw new Error('Fallback Cloudflare challenge requires the same observed page snapshot.');
+ return JSON.stringify([mode, html]);
+ }
+ if (mode === 'token') {
+ return JSON.stringify([mode, task.pageAction, task.data, task.pageData, task.apiJsUrl ?? null]);
+ }
+ throw new Error('Fallback Cloudflare challenge requires a comparable task mode.');
+}
function validateFallbackIdentifiers(built) {
const family = built[0].contract.family;
+ if (family === 'cloudflare_challenge' && built.length > 1
+ && new Set(built.map(cloudflareChallengeSignature)).size > 1) {
+ throw new Error('Fallback Cloudflare tasks must use the same challenge mode and observed page snapshot.');
+ }
if (family === 'funcaptcha' && built.length > 1) {
const services = built.map(({ task }) => task.funcaptchaApiJSSubdomain || task.surl);
if (services.some(usable)) {
diff --git a/test/captcha-native-providers.mjs b/test/captcha-native-providers.mjs
index 3e352f0ca..432a86be5 100644
--- a/test/captcha-native-providers.mjs
+++ b/test/captcha-native-providers.mjs
@@ -76,6 +76,31 @@ for (const browser of ['chrome','firefox']) {
assert.throws(()=>native.buildNativeCaptchaTask({provider:'nopecha',method:'token/turnstile',parameters:{sitekey:'site',url}}),/proxy/);
assert.throws(()=>native.buildNativeCaptchaTask({provider:'capmonster',method:'ComplexImageTask:recaptcha',parameters:{metadata:{Grid:'3x3',Task:'cars'}}}),/imageUrls or imagesBase64/);
});
+ test(`${browser}: Cloudflare fallback requires the same mode and page snapshot before dispatch`, t => {
+ const calls = mockApi(t, () => { throw new Error('Must not dispatch'); });
+ const html = '<html><body>Fresh challenge ✓</body></html>';
+ const capsolver = { provider: 'capsolver', method: 'AntiCloudflareTask', parameters: {
+ websiteURL: url, proxy: 'http:proxy.test:8080', userAgent: 'browser-UA', html,
+ } };
+ const capmonster = { provider: 'capmonster', method: 'TurnstileTask:cf_clearance:2', parameters: {
+ websiteURL: url, websiteKey: 'site', htmlPageBase64: Buffer.from(html, 'utf8').toString('base64'),
+ userAgent: 'browser-UA', proxyType: 'http', proxyAddress: 'proxy.test', proxyPort: 8080,
+ } };
+ assert.equal(native.prepareNativeCaptchaTasks(providers, [capsolver, capmonster]).length, 2);
+ for (const changed of [
+ { ...capsolver, parameters: { ...capsolver.parameters, html: '<html>Previous challenge</html>' } },
+ { ...capsolver, parameters: { websiteURL: url, proxy: 'http:proxy.test:8080', userAgent: 'browser-UA' } },
+ ]) assert.throws(() => native.prepareNativeCaptchaTasks(providers, [changed, capmonster]), /same observed page snapshot|same challenge mode/);
+ assert.throws(() => native.prepareNativeCaptchaTasks(providers, [capsolver, {
+ ...capmonster, parameters: { ...capmonster.parameters, htmlPageBase64: 'not base64' },
+ }]), /valid page snapshot/);
+ const token = { provider: 'capmonster', method: 'TurnstileTask:token:1', parameters: {
+ websiteURL: url, websiteKey: 'site', pageAction: 'managed', data: 'data', pageData: 'page',
+ userAgent: 'browser-UA', proxyType: 'http', proxyAddress: 'proxy.test', proxyPort: 8080,
+ } };
+ assert.throws(() => native.prepareNativeCaptchaTasks(providers, [capsolver, token]), /same challenge mode/);
+ assert.equal(calls.length, 0);
+ });
test(`${browser}: enumerated nested task fields reject undocumented data before paid dispatch`, t => {
const calls = mockApi(t, () => { throw new Error('Must not dispatch'); });
const entry = { provider: 'capmonster', method: 'CustomTask:alibaba', parameters: {
diff --git a/test/captcha-runtime-policy.mjs b/test/captcha-runtime-policy.mjs
index f514b2d42..6dca17120 100644
--- a/test/captcha-runtime-policy.mjs
+++ b/test/captcha-runtime-policy.mjs
@@ -141,6 +141,40 @@ for (const build of ['chrome', 'firefox']) {
assert.equal(agent._hasUnappliedNativeCaptchaSolution(1), false);
assert.equal(record.dispatchedTimeOrigins.has(1000), true);
});
+ test(`${build}: query and fragment navigation retire an answer and release its gate`, () => {
+ for (const to of ['https://example.test/challenge?step=2', 'https://example.test/challenge?step=1#next']) {
+ const agent = agentFor('act', 'full');
+ const from = 'https://example.test/challenge?step=1';
+ const record = { pageUrl: from, solution: { token: 'answer' }, applied: false,
+ dispatchedTimeOrigins: new Set([1000]) };
+ agent._nativeCaptchaSolutions = new Map([[1, record]]);
+ agent._captchaGateStates.set(1, { status: 'verification_pending', publicGate: { status: 'verification_pending' } });
+ const result = {};
+ assert.equal(agent._clearCaptchaGateAfterNavigation(1, 'navigate', from, to, result)?.status, 'cleared');
+ assert.equal(result.captchaGate.clearedByNavigation, true);
+ assert.equal(record.solution, undefined);
+ assert.equal(record.dispatchedTimeOrigins.has(1000), true);
+ assert.equal(agent._captchaGateStates.has(1), false);
+ }
+ });
+ test(`${build}: a fresh page read retires a stale native answer and gate`, async () => {
+ const agent = agentFor('act', 'full');
+ const from = 'https://example.test/challenge?step=1';
+ const to = 'https://example.test/challenge?step=2';
+ const record = { pageUrl: from, solution: { token: 'answer' }, applied: false,
+ dispatchedTimeOrigins: new Set([1000]) };
+ agent._nativeCaptchaSolutions = new Map([[1, record]]);
+ agent._captchaGateStates.set(1, { status: 'verification_pending', publicGate: { status: 'verification_pending' } });
+ agent._currentUrl = async () => to;
+ agent._activeCloudflareManagedChallengeGate = () => null;
+ agent._checkVerificationChallengeLoop = () => ({ kind: 'none' });
+ await agent._observeCaptchaChallenge(1, 'get_accessibility_tree', {
+ pageUrl: to, pageContent: 'heading "Next step"', truncated: false,
+ });
+ assert.equal(record.solution, undefined);
+ assert.equal(record.dispatchedTimeOrigins.has(1000), true);
+ assert.equal(agent._captchaGateStates.has(1), false);
+ });
test(`${build}: a same-URL reload retires the answer and releases the previous gate`, async () => {
const agent = agentFor('act', 'full');
const pageUrl = 'https://example.test/challenge';