Skip to content

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

Retire stale CAPTCHA documents and validate fallback User-Agent

Emre Sokullu1f1822412ce8
diff --git a/src/chrome/src/agent/agent.js b/src/chrome/src/agent/agent.js
index 385c75f78..663897f89 100644
--- a/src/chrome/src/agent/agent.js
+++ b/src/chrome/src/agent/agent.js
@@ -85,7 +85,7 @@ import { normalizeRuntimeTraceConfig } from '../trace/runtime-config.js';
import { tracesToMarkdown } from './trace-export.js';
import { hcaptchaParamError } from './captcha-hcaptcha-providers.js';
import { getCaptchaCapabilities, prepareNativeCaptchaTasks, solveNativeCaptchaTasks } from './captcha-native-providers.js';
-import { applyNativeCaptchaSolution, captureCaptchaDocuments } from './captcha-solution-application.js';
+import { applyNativeCaptchaSolution, captureCaptchaDocuments, captchaAnswerDocumentCurrent } from './captcha-solution-application.js';
import { solveCaptchaWithProviders, detectCaptcha, injectToken, captchaParamError, captchaTypesMatch, captchaWebsiteUrl } from './captcha-solver.js';
import { CAPTCHA_SETTINGS_KEYS, getCaptchaProviders, captchaProviderSupportsType } from './captcha-provider-config.js';
import { captchaChallengeKey, captchaChallengeMatcherOptions, detectChallengeDialog, detectChallengeDialogInPage } from './captcha-gate.js';
@@ -35746,9 +35746,17 @@ If the user has already named or confirmed this exact recipient, do NOT ask agai
const record = this._nativeCaptchaSolutions?.get(tabId);
const applicationRetryable = async () => {
if (record?.solution === undefined || record.applied || Date.now() - record.createdAt > 180_000) return false;
- // A transient tab read cannot consume the answer; the next apply
- // rechecks the URL and document before any page mutation.
- try { return (await chrome.tabs.get(tabId))?.url === record.pageUrl; } catch { return true; }
+ // A same-URL reload also invalidates the answer. Only a confirmed
+ // document change retires it; transient inspection failures do not.
+ try {
+ const current = await captchaAnswerDocumentCurrent(tabId, record, chrome);
+ if (current === false) {
+ delete record.solution;
+ this._captchaGateStates.delete(tabId);
+ return false;
+ }
+ return true;
+ } catch { return true; }
};
try {
const result = await applyNativeCaptchaSolution(tabId, record, args, chrome);
diff --git a/src/chrome/src/agent/captcha-native-providers.js b/src/chrome/src/agent/captcha-native-providers.js
index 2a2a874e4..a2dc5e9e1 100644
--- a/src/chrome/src/agent/captcha-native-providers.js
+++ b/src/chrome/src/agent/captcha-native-providers.js
@@ -165,6 +165,7 @@ function validateFallbackIdentifiers(built) {
const groups = [
{ aliases: ['websiteURL', 'pageurl', 'url'], requireAll: false },
{ aliases: ['websiteKey', 'sitekey', 'googlekey', 'websitePublicKey', 'publickey'], requireAll: false },
+ { aliases: ['userAgent', 'useragent', 'user_agent'], requireAll: true },
...(FAMILY_IDENTIFIERS[family] || []).map(aliases => ({ aliases, requireAll: true })),
];
if (family === 'geetest') {
diff --git a/src/chrome/src/agent/captcha-solution-application.js b/src/chrome/src/agent/captcha-solution-application.js
index a207eb5cb..2afcbb7a9 100644
--- a/src/chrome/src/agent/captcha-solution-application.js
+++ b/src/chrome/src/agent/captcha-solution-application.js
@@ -77,6 +77,20 @@ export async function captureCaptchaDocuments(tabId, frames, api = globalThis.br
return identities.filter(Boolean);
}
+// A same-URL reload is a different document and cannot reuse its paid answer.
+// Null means the current document could not be read, so a transient API error
+// does not discard an answer that may still be valid.
+export async function captchaAnswerDocumentCurrent(tabId, record, api = globalThis.browser || globalThis.chrome) {
+ const tab = await api.tabs.get(tabId);
+ if (tab?.url !== record.pageUrl) return false;
+ const expected = record.documents?.find(d => d.frameId === 0 && d.url === record.pageUrl);
+ if (!expected) return null;
+ const documents = await captureCaptchaDocuments(tabId, [{ frameId: 0, url: record.pageUrl }], api);
+ const current = documents.find(d => d.frameId === 0);
+ if (!current) return null;
+ return current.url === expected.url && current.timeOrigin === expected.timeOrigin;
+}
+
// Self-contained for MAIN-world execution in one explicitly selected frame.
export function applyCaptchaValuesInPage(expectedUrl, fields, callback, clicks = [], expectedTimeOrigin, validateOnly = false) {
if (location.href !== expectedUrl || performance.timeOrigin !== expectedTimeOrigin) return { success: false, error: 'CAPTCHA frame navigated before application.' };
diff --git a/src/firefox/src/agent/agent.js b/src/firefox/src/agent/agent.js
index 5d69707f6..45503e5ae 100644
--- a/src/firefox/src/agent/agent.js
+++ b/src/firefox/src/agent/agent.js
@@ -80,7 +80,7 @@ import { normalizeRuntimeTraceConfig } from '../trace/runtime-config.js';
import { tracesToMarkdown } from './trace-export.js';
import { hcaptchaParamError } from './captcha-hcaptcha-providers.js';
import { getCaptchaCapabilities, prepareNativeCaptchaTasks, solveNativeCaptchaTasks } from './captcha-native-providers.js';
-import { applyNativeCaptchaSolution, captureCaptchaDocuments } from './captcha-solution-application.js';
+import { applyNativeCaptchaSolution, captureCaptchaDocuments, captchaAnswerDocumentCurrent } from './captcha-solution-application.js';
import { solveCaptchaWithProviders, detectCaptcha, injectToken, captchaParamError, captchaTypesMatch, captchaWebsiteUrl } from './captcha-solver.js';
import { CAPTCHA_SETTINGS_KEYS, getCaptchaProviders, captchaProviderSupportsType } from './captcha-provider-config.js';
import { captchaChallengeKey, captchaChallengeMatcherOptions, detectChallengeDialog, detectChallengeDialogInPage } from './captcha-gate.js';
@@ -32732,9 +32732,17 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
const record = this._nativeCaptchaSolutions?.get(tabId);
const applicationRetryable = async () => {
if (record?.solution === undefined || record.applied || Date.now() - record.createdAt > 180_000) return false;
- // A transient tab read cannot consume the answer; the next apply
- // rechecks the URL and document before any page mutation.
- try { return (await browser.tabs.get(tabId))?.url === record.pageUrl; } catch { return true; }
+ // A same-URL reload also invalidates the answer. Only a confirmed
+ // document change retires it; transient inspection failures do not.
+ try {
+ const current = await captchaAnswerDocumentCurrent(tabId, record, browser);
+ if (current === false) {
+ delete record.solution;
+ this._captchaGateStates.delete(tabId);
+ return false;
+ }
+ return true;
+ } catch { return true; }
};
try {
const result = await applyNativeCaptchaSolution(tabId, record, args, browser);
diff --git a/src/firefox/src/agent/captcha-native-providers.js b/src/firefox/src/agent/captcha-native-providers.js
index 2a2a874e4..a2dc5e9e1 100644
--- a/src/firefox/src/agent/captcha-native-providers.js
+++ b/src/firefox/src/agent/captcha-native-providers.js
@@ -165,6 +165,7 @@ function validateFallbackIdentifiers(built) {
const groups = [
{ aliases: ['websiteURL', 'pageurl', 'url'], requireAll: false },
{ aliases: ['websiteKey', 'sitekey', 'googlekey', 'websitePublicKey', 'publickey'], requireAll: false },
+ { aliases: ['userAgent', 'useragent', 'user_agent'], requireAll: true },
...(FAMILY_IDENTIFIERS[family] || []).map(aliases => ({ aliases, requireAll: true })),
];
if (family === 'geetest') {
diff --git a/src/firefox/src/agent/captcha-solution-application.js b/src/firefox/src/agent/captcha-solution-application.js
index a207eb5cb..2afcbb7a9 100644
--- a/src/firefox/src/agent/captcha-solution-application.js
+++ b/src/firefox/src/agent/captcha-solution-application.js
@@ -77,6 +77,20 @@ export async function captureCaptchaDocuments(tabId, frames, api = globalThis.br
return identities.filter(Boolean);
}
+// A same-URL reload is a different document and cannot reuse its paid answer.
+// Null means the current document could not be read, so a transient API error
+// does not discard an answer that may still be valid.
+export async function captchaAnswerDocumentCurrent(tabId, record, api = globalThis.browser || globalThis.chrome) {
+ const tab = await api.tabs.get(tabId);
+ if (tab?.url !== record.pageUrl) return false;
+ const expected = record.documents?.find(d => d.frameId === 0 && d.url === record.pageUrl);
+ if (!expected) return null;
+ const documents = await captureCaptchaDocuments(tabId, [{ frameId: 0, url: record.pageUrl }], api);
+ const current = documents.find(d => d.frameId === 0);
+ if (!current) return null;
+ return current.url === expected.url && current.timeOrigin === expected.timeOrigin;
+}
+
// Self-contained for MAIN-world execution in one explicitly selected frame.
export function applyCaptchaValuesInPage(expectedUrl, fields, callback, clicks = [], expectedTimeOrigin, validateOnly = false) {
if (location.href !== expectedUrl || performance.timeOrigin !== expectedTimeOrigin) return { success: false, error: 'CAPTCHA frame navigated before application.' };
diff --git a/test/captcha-native-providers.mjs b/test/captcha-native-providers.mjs
index e3fc1c897..e17d42840 100644
--- a/test/captcha-native-providers.mjs
+++ b/test/captcha-native-providers.mjs
@@ -243,6 +243,7 @@ for (const browser of ['chrome', 'firefox']) {
assert.equal(calls.length, 0);
});
const actionBoundPairs = [
+ ['DataDome User-Agent', ['2captcha', 'DataDomeSliderTask', { websiteURL: url, captchaUrl: 'https://example.test/captcha', userAgent: 'browser-UA', proxyType: 'http', proxyAddress: 'proxy.test', proxyPort: 8080 }], ['solvecaptcha', 'datadome', { pageurl: url, captcha_url: 'https://example.test/captcha', userAgent: 'browser-UA', proxy: 'proxy.test:8080', proxytype: 'http' }], 'userAgent'],
['reCAPTCHA v2 data-s', ['2captcha', 'RecaptchaV2TaskProxyless', { websiteURL: url, websiteKey: 'site', recaptchaDataSValue: 'observed' }], ['solvecaptcha', 'recaptcha_v2', { pageurl: url, googlekey: 'site', 'data-s': 'observed' }], 'data-s'],
['reCAPTCHA v2 enterprise data-s', ['2captcha', 'RecaptchaV2EnterpriseTaskProxyless', { websiteURL: url, websiteKey: 'site', enterprisePayload: { s: 'observed' } }], ['solvecaptcha', 'recaptcha_v2_enterprise', { pageurl: url, googlekey: 'site', 'data-s': 'observed' }], 'data-s'],
['reCAPTCHA v2 nested data-s', ['2captcha', 'RecaptchaV2TaskProxyless', { websiteURL: url, websiteKey: 'site', recaptchaDataSValue: 'observed' }], ['nopecha', 'token/recaptcha2', { url, sitekey: 'site', data: { s: 'observed' } }], 'data.s'],
@@ -266,6 +267,10 @@ for (const browser of ['chrome', 'firefox']) {
assert.equal(calls.length, 0);
});
for (const [label, entries] of [
+ ['reCAPTCHA v2 omitted User-Agent', [
+ { provider: '2captcha', method: 'RecaptchaV2TaskProxyless', parameters: { websiteURL: url, websiteKey: 'site', userAgent: 'browser-UA' } },
+ { provider: 'solvecaptcha', method: 'recaptcha_v2', parameters: { pageurl: url, googlekey: 'site' } },
+ ]],
['reCAPTCHA v2 omitted data-s', [
{ provider: '2captcha', method: 'RecaptchaV2TaskProxyless', parameters: { websiteURL: url, websiteKey: 'site', recaptchaDataSValue: 'observed' } },
{ provider: 'solvecaptcha', method: 'recaptcha_v2', parameters: { pageurl: url, googlekey: 'site' } },
diff --git a/test/captcha-runtime-policy.mjs b/test/captcha-runtime-policy.mjs
index 7b50d6e8b..c017d82e5 100644
--- a/test/captcha-runtime-policy.mjs
+++ b/test/captcha-runtime-policy.mjs
@@ -128,4 +128,35 @@ for (const build of ['chrome', 'firefox']) {
assert.equal(agent._hasUnappliedNativeCaptchaSolution(1), false);
assert.equal(record.dispatchedTimeOrigins.has(1000), true);
});
+ 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';
+ const record = { pageUrl, createdAt: Date.now(), applied: false, solution: { token: 'answer' },
+ documents: [{ frameId: 0, url: pageUrl, timeOrigin: 1000 }], dispatchedTimeOrigins: new Set([1000]) };
+ agent._nativeCaptchaSolutions = new Map([[1, record]]);
+ agent._captchaGateStates.set(1, { status: 'verification_pending', publicGate: { status: 'verification_pending' } });
+ const api = {
+ tabs: {
+ get: async () => ({ url: pageUrl }),
+ executeScript: async (_tabId, options) => [options.code.includes('performance.timeOrigin') && !options.code.includes('applyCaptchaValuesInPage')
+ ? { url: pageUrl, timeOrigin: 2000 } : { success: false, error: 'CAPTCHA frame navigated before application.' }],
+ },
+ scripting: build === 'chrome' ? { executeScript: async options => [{ frameId: 0, result: options.func.name === 'read'
+ ? { url: pageUrl, timeOrigin: 2000 } : { success: false, error: 'CAPTCHA frame navigated before application.' } }] } : undefined,
+ webNavigation: { getAllFrames: async () => [{ frameId: 0, url: pageUrl }] },
+ };
+ const key = build === 'chrome' ? 'chrome' : 'browser';
+ const previous = globalThis[key];
+ globalThis[key] = api;
+ try {
+ const result = await agent._executeToolImpl(1, 'apply_captcha_solution', { frameId: 0, frameUrl: pageUrl,
+ fields: [{ selector: '#response', path: 'token' }] });
+ assert.equal(result.applicationRetryable, false);
+ assert.equal(record.solution, undefined);
+ assert.equal(record.dispatchedTimeOrigins.has(1000), true);
+ assert.equal(agent._captchaGateStates.has(1), false);
+ } finally {
+ if (previous === undefined) delete globalThis[key]; else globalThis[key] = previous;
+ }
+ });
}