Skip to content

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

Keep native CAPTCHA dispatch across chat clears and validate array payloads

Emre Sokullud082f2e6c57e
diff --git a/src/chrome/src/agent/agent.js b/src/chrome/src/agent/agent.js
index da324cb6d..9c5ff5a0c 100644
--- a/src/chrome/src/agent/agent.js
+++ b/src/chrome/src/agent/agent.js
@@ -26145,7 +26145,9 @@ If the user has already named or confirmed this exact recipient, do NOT ask agai
this.completionInvariants.delete(tabId);
this.readCompletenessStates.delete(tabId);
this._captchaGateStates.delete(tabId);
- this._nativeCaptchaSolutions?.delete(tabId);
+ // Native paid answers and dispatch locks belong to the page document,
+ // not the conversation. A new chat on the same document must reuse them.
+ if (!preserveRunGuard) this._nativeCaptchaSolutions?.delete(tabId);
if (preserveRunGuard) {
this._activeCloudflareManagedChallengeGate(tabId);
} else {
diff --git a/src/chrome/src/agent/captcha-native-providers.js b/src/chrome/src/agent/captcha-native-providers.js
index 1a40fea7a..c1b8f752f 100644
--- a/src/chrome/src/agent/captcha-native-providers.js
+++ b/src/chrome/src/agent/captcha-native-providers.js
@@ -64,6 +64,39 @@ function validateDocumentedPaths(task, contract) {
};
visit(task);
}
+function validateDocumentedArrays(task, contract) {
+ const stringItem = value => typeof value === 'string' && !!value.trim();
+ const exactObject = (value, required, optional = {}) => object(value)
+ && Object.entries(required).every(([key, valid]) => valid(value[key]))
+ && Object.entries(value).every(([key, item]) => (required[key] || optional[key])?.(item) === true);
+ const cookiePair = value => exactObject(value, { name: stringItem, value: v => typeof v === 'string' });
+ const nopechaCookie = value => exactObject(value, {
+ name: stringItem, value: v => typeof v === 'string', domain: stringItem, path: stringItem,
+ hostOnly: v => typeof v === 'boolean', httpOnly: v => typeof v === 'boolean',
+ secure: v => typeof v === 'boolean', session: v => typeof v === 'boolean',
+ }, { expirationDate: v => Number.isInteger(v) && v >= 1 });
+ const coordinates = value => Array.isArray(value) && value.length === 2
+ && value.every(v => typeof v === 'number' && Number.isFinite(v));
+ const entity = value => exactObject(value, {
+ entity_id: stringItem, entity_uri: stringItem, coords: coordinates, size: coordinates,
+ });
+ const hcaptchaTask = value => exactObject(value, {
+ task_key: stringItem, datapoint_uri: stringItem,
+ }, { entities: value => Array.isArray(value) && value.length > 0 && value.every(entity) });
+ for (const [path, field] of Object.entries(contract.fields)) {
+ if (!field.type.split('|').includes('array')) continue;
+ const values = at(task, path);
+ if (!Array.isArray(values)) continue;
+ const validItem = path === 'cookie' ? nopechaCookie
+ : path === 'cookies' ? cookiePair
+ : path === 'data.tasklist' ? hcaptchaTask
+ : path === 'steps' ? value => Number.isInteger(value) && value >= 0
+ : stringItem;
+ if (values.some(value => !validItem(value))) {
+ throw new Error(`${contract.method}: ${path} contains an undocumented or invalid array element.`);
+ }
+ }
+}
// No keys, credentials, or account balances are exposed by discovery.
export function getCaptchaCapabilities(providers, { provider, family, method } = {}) {
@@ -90,6 +123,7 @@ export function buildNativeCaptchaTask(entry) {
put(task, path, value);
}
validateDocumentedPaths(task, contract);
+ validateDocumentedArrays(task, contract);
for (const [path, field] of Object.entries(contract.fields)) {
const value = at(task, path);
if (value === undefined) { if (field.required) throw new Error(`${entry.method}: ${path} is required.`); continue; }
diff --git a/src/firefox/src/agent/agent.js b/src/firefox/src/agent/agent.js
index 82d00b3a4..8d00d412f 100644
--- a/src/firefox/src/agent/agent.js
+++ b/src/firefox/src/agent/agent.js
@@ -24665,7 +24665,9 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
this.completionInvariants.delete(tabId);
this.readCompletenessStates.delete(tabId);
this._captchaGateStates.delete(tabId);
- this._nativeCaptchaSolutions?.delete(tabId);
+ // Native paid answers and dispatch locks belong to the page document,
+ // not the conversation. A new chat on the same document must reuse them.
+ if (!preserveRunGuard) this._nativeCaptchaSolutions?.delete(tabId);
if (preserveRunGuard) {
this._activeCloudflareManagedChallengeGate(tabId);
} else {
diff --git a/src/firefox/src/agent/captcha-native-providers.js b/src/firefox/src/agent/captcha-native-providers.js
index 1a40fea7a..c1b8f752f 100644
--- a/src/firefox/src/agent/captcha-native-providers.js
+++ b/src/firefox/src/agent/captcha-native-providers.js
@@ -64,6 +64,39 @@ function validateDocumentedPaths(task, contract) {
};
visit(task);
}
+function validateDocumentedArrays(task, contract) {
+ const stringItem = value => typeof value === 'string' && !!value.trim();
+ const exactObject = (value, required, optional = {}) => object(value)
+ && Object.entries(required).every(([key, valid]) => valid(value[key]))
+ && Object.entries(value).every(([key, item]) => (required[key] || optional[key])?.(item) === true);
+ const cookiePair = value => exactObject(value, { name: stringItem, value: v => typeof v === 'string' });
+ const nopechaCookie = value => exactObject(value, {
+ name: stringItem, value: v => typeof v === 'string', domain: stringItem, path: stringItem,
+ hostOnly: v => typeof v === 'boolean', httpOnly: v => typeof v === 'boolean',
+ secure: v => typeof v === 'boolean', session: v => typeof v === 'boolean',
+ }, { expirationDate: v => Number.isInteger(v) && v >= 1 });
+ const coordinates = value => Array.isArray(value) && value.length === 2
+ && value.every(v => typeof v === 'number' && Number.isFinite(v));
+ const entity = value => exactObject(value, {
+ entity_id: stringItem, entity_uri: stringItem, coords: coordinates, size: coordinates,
+ });
+ const hcaptchaTask = value => exactObject(value, {
+ task_key: stringItem, datapoint_uri: stringItem,
+ }, { entities: value => Array.isArray(value) && value.length > 0 && value.every(entity) });
+ for (const [path, field] of Object.entries(contract.fields)) {
+ if (!field.type.split('|').includes('array')) continue;
+ const values = at(task, path);
+ if (!Array.isArray(values)) continue;
+ const validItem = path === 'cookie' ? nopechaCookie
+ : path === 'cookies' ? cookiePair
+ : path === 'data.tasklist' ? hcaptchaTask
+ : path === 'steps' ? value => Number.isInteger(value) && value >= 0
+ : stringItem;
+ if (values.some(value => !validItem(value))) {
+ throw new Error(`${contract.method}: ${path} contains an undocumented or invalid array element.`);
+ }
+ }
+}
// No keys, credentials, or account balances are exposed by discovery.
export function getCaptchaCapabilities(providers, { provider, family, method } = {}) {
@@ -90,6 +123,7 @@ export function buildNativeCaptchaTask(entry) {
put(task, path, value);
}
validateDocumentedPaths(task, contract);
+ validateDocumentedArrays(task, contract);
for (const [path, field] of Object.entries(contract.fields)) {
const value = at(task, path);
if (value === undefined) { if (field.required) throw new Error(`${entry.method}: ${path} is required.`); continue; }
diff --git a/test/captcha-native-providers.mjs b/test/captcha-native-providers.mjs
index 61f864b95..3340dfeb9 100644
--- a/test/captcha-native-providers.mjs
+++ b/test/captcha-native-providers.mjs
@@ -134,7 +134,8 @@ for (const browser of ['chrome','firefox']) {
const calls = mockApi(t, () => { throw new Error('Must not dispatch'); });
const nopecha = { provider: 'nopecha', method: 'token/hcaptcha', parameters: {
sitekey: 'site', url,
- cookie: [{ name: 'SID', value: 'session', domain: 'example.test', path: '/' }],
+ cookie: [{ name: 'SID', value: 'session', domain: 'example.test', path: '/',
+ hostOnly: true, httpOnly: false, secure: true, session: true }],
} };
const nonecap = { provider: 'nonecap', method: 'hcaptcha', parameters: { sitekey: 'site', url } };
assert.equal(native.prepareNativeCaptchaTasks(providers, [
@@ -198,6 +199,35 @@ for (const browser of ['chrome','firefox']) {
// Provider-documented option objects remain open where their schemas say so.
assert.equal(native.buildNativeCaptchaTask({ provider: 'nopecha', method: 'token/recaptcha2:enterprise',
parameters: { url, sitekey: 'site', data: { s: 'observed' } } }).task.data.s, 'observed');
+ const cookie = { name: 'SID', value: 'x', domain: 'example.test', path: '/',
+ hostOnly: true, httpOnly: false, secure: true, session: true };
+ const token = { provider: 'nopecha', method: 'token/recaptcha2', parameters: {
+ url, sitekey: 'site', cookie: [cookie],
+ } };
+ assert.equal(native.prepareNativeCaptchaTasks(providers, [token]).length, 1);
+ for (const item of [{ ...cookie, undocumentedSecret: 'page data' }, { name: 'SID', value: 'x' }]) {
+ assert.throws(() => native.prepareNativeCaptchaTasks(providers, [{ ...token,
+ parameters: { ...token.parameters, cookie: [item] },
+ }]), /invalid array element/);
+ }
+ assert.throws(() => native.prepareNativeCaptchaTasks(providers, [{
+ provider: 'nopecha', method: 'recognition/textcaptcha', parameters: { image_data: [{ secret: 'page data' }] },
+ }]), /invalid array element/);
+ const hcaptcha = { provider: 'nopecha', method: 'recognition/hcaptcha', parameters: { data: {
+ request_type: 'image_drag_drop', requester_question: { en: 'Match the objects' },
+ tasklist: [{ task_key: 'task', datapoint_uri: 'data:image/jpeg;base64,a', entities: [{
+ entity_id: 'entity', entity_uri: 'data:image/png;base64,b', coords: [10, 20], size: [30, 40],
+ }] }],
+ } } };
+ assert.equal(native.prepareNativeCaptchaTasks(providers, [hcaptcha]).length, 1);
+ assert.throws(() => native.prepareNativeCaptchaTasks(providers, [{ ...hcaptcha,
+ parameters: { data: { ...hcaptcha.parameters.data, tasklist: [{
+ ...hcaptcha.parameters.data.tasklist[0], entities: [{
+ ...hcaptcha.parameters.data.tasklist[0].entities[0], secret: 'page data',
+ }],
+ }] } },
+ }]), /invalid array element/);
+ assert.equal(calls.length, 0);
});
test(`${browser}: weighted JSON fallback preserves structured answers and synchronous results`,async t=>{
const calls=mockApi(t,c=>c.url.hostname==='api.capsolver.com'?{errorId:1,errorDescription:'failed'}:{status:'ready',solution:{captcha_id:'id',lot_number:'lot',pass_token:'pass',gen_time:'time',captcha_output:'out'}});
diff --git a/test/captcha-runtime-policy.mjs b/test/captcha-runtime-policy.mjs
index eaba5c0ba..2011a3ee3 100644
--- a/test/captcha-runtime-policy.mjs
+++ b/test/captcha-runtime-policy.mjs
@@ -141,6 +141,23 @@ for (const build of ['chrome', 'firefox']) {
assert.equal(agent._hasUnappliedNativeCaptchaSolution(1), false);
assert.equal(record.dispatchedTimeOrigins.has(1000), true);
});
+ test(`${build}: clearing a chat preserves the page-scoped paid answer and dispatch lock`, () => {
+ const agent = agentFor('act', 'full');
+ const record = { pageUrl: 'https://example.test/challenge', createdAt: Date.now(),
+ solution: { token: 'paid-answer' }, applied: false,
+ documents: [{ frameId: 0, url: 'https://example.test/challenge', timeOrigin: 1000 }],
+ dispatchedTimeOrigins: new Set([1000]) };
+ agent._nativeCaptchaSolutions = new Map([[1, record]]);
+ agent.clearConversation(1);
+ assert.equal(agent._nativeCaptchaSolutions.get(1), record);
+ assert.equal(agent._hasUnappliedNativeCaptchaSolution(1), true);
+ assert.equal(agent._nativeCaptchaSolutions.get(1).dispatchedTimeOrigins.has(1000), true);
+ // A still-running solve can fill the same record after the chat is cleared.
+ record.solution = { token: 'late-answer' };
+ assert.equal(agent._nativeCaptchaSolutions.get(1).solution.token, 'late-answer');
+ agent._cleanupTab(1);
+ assert.equal(agent._nativeCaptchaSolutions.has(1), false);
+ });
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');