Skip to content

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

Reject undocumented nested CAPTCHA parameters

Emre Sokullubf483e8dc7ac
diff --git a/docs/captcha-provider-coverage.md b/docs/captcha-provider-coverage.md
index 653db25e1..30c9419e3 100644
--- a/docs/captcha-provider-coverage.md
+++ b/docs/captcha-provider-coverage.md
@@ -139,6 +139,8 @@ Saved weights determine execution order, regardless of array order. Supply a tas
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; TSPD fallbacks must use the same captured page. reCAPTCHA v2 fallbacks must agree on `data-s` and visible/invisible mode, and reCAPTCHA v3 fallbacks on action and minimum score, when supplied.
+The native adapter rejects undeclared nested fields in schemas with enumerated children, such as CapMonster `metadata`. Provider-documented free-form option objects, including NopeCHA Enterprise `data`, remain available.
+
`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.
## Applying answers
diff --git a/src/chrome/src/agent/captcha-native-providers.js b/src/chrome/src/agent/captcha-native-providers.js
index e67bcc39a..c08320363 100644
--- a/src/chrome/src/agent/captcha-native-providers.js
+++ b/src/chrome/src/agent/captcha-native-providers.js
@@ -45,6 +45,26 @@ function matches(value, type) {
: typeof value === t);
}
+function validateDocumentedPaths(task, contract) {
+ const paths = [...Object.keys(contract.fields), ...Object.keys(contract.fixed)];
+ // NopeCHA Enterprise passes grecaptcha.render options in data; its API
+ // explicitly permits additional widget options besides the fixed flag.
+ const openData = contract.provider === 'nopecha'
+ && ['token/recaptcha2:enterprise', 'token/recaptcha3:enterprise'].includes(contract.method);
+ const visit = (value, path = '') => {
+ if (!object(value) || (openData && path === 'data')) return;
+ if (path && !paths.some(candidate => candidate.startsWith(`${path}.`))) return;
+ for (const [key, child] of Object.entries(value)) {
+ const childPath = path ? `${path}.${key}` : key;
+ if (!paths.includes(childPath) && !paths.some(candidate => candidate.startsWith(`${childPath}.`))) {
+ throw new Error(`${contract.method}: undocumented field ${childPath}.`);
+ }
+ visit(child, childPath);
+ }
+ };
+ visit(task);
+}
+
// No keys, credentials, or account balances are exposed by discovery.
export function getCaptchaCapabilities(providers, { provider, family, method } = {}) {
const enabled = new Map(providers.map(p => [p.id, p]));
@@ -65,12 +85,11 @@ export function buildNativeCaptchaTask(entry) {
validateJson(entry.parameters);
if (JSON.stringify(entry.parameters).length > 12_000_000) throw new Error('CAPTCHA input exceeds 12 MB.');
const task = JSON.parse(JSON.stringify(entry.parameters));
- const roots = new Set([...Object.keys(contract.fields), ...Object.keys(contract.fixed)].map(k => k.split('.')[0]));
- for (const key of Object.keys(task)) if (!roots.has(key)) throw new Error(`${entry.provider}/${entry.method}: undocumented field ${key}.`);
for (const [path, value] of Object.entries(contract.fixed)) {
if (at(task, path) !== undefined && at(task, path) !== value) throw new Error(`${entry.method}: ${path} is fixed by this method.`);
put(task, path, value);
}
+ validateDocumentedPaths(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/captcha-native-providers.js b/src/firefox/src/agent/captcha-native-providers.js
index e67bcc39a..c08320363 100644
--- a/src/firefox/src/agent/captcha-native-providers.js
+++ b/src/firefox/src/agent/captcha-native-providers.js
@@ -45,6 +45,26 @@ function matches(value, type) {
: typeof value === t);
}
+function validateDocumentedPaths(task, contract) {
+ const paths = [...Object.keys(contract.fields), ...Object.keys(contract.fixed)];
+ // NopeCHA Enterprise passes grecaptcha.render options in data; its API
+ // explicitly permits additional widget options besides the fixed flag.
+ const openData = contract.provider === 'nopecha'
+ && ['token/recaptcha2:enterprise', 'token/recaptcha3:enterprise'].includes(contract.method);
+ const visit = (value, path = '') => {
+ if (!object(value) || (openData && path === 'data')) return;
+ if (path && !paths.some(candidate => candidate.startsWith(`${path}.`))) return;
+ for (const [key, child] of Object.entries(value)) {
+ const childPath = path ? `${path}.${key}` : key;
+ if (!paths.includes(childPath) && !paths.some(candidate => candidate.startsWith(`${childPath}.`))) {
+ throw new Error(`${contract.method}: undocumented field ${childPath}.`);
+ }
+ visit(child, childPath);
+ }
+ };
+ visit(task);
+}
+
// No keys, credentials, or account balances are exposed by discovery.
export function getCaptchaCapabilities(providers, { provider, family, method } = {}) {
const enabled = new Map(providers.map(p => [p.id, p]));
@@ -65,12 +85,11 @@ export function buildNativeCaptchaTask(entry) {
validateJson(entry.parameters);
if (JSON.stringify(entry.parameters).length > 12_000_000) throw new Error('CAPTCHA input exceeds 12 MB.');
const task = JSON.parse(JSON.stringify(entry.parameters));
- const roots = new Set([...Object.keys(contract.fields), ...Object.keys(contract.fixed)].map(k => k.split('.')[0]));
- for (const key of Object.keys(task)) if (!roots.has(key)) throw new Error(`${entry.provider}/${entry.method}: undocumented field ${key}.`);
for (const [path, value] of Object.entries(contract.fixed)) {
if (at(task, path) !== undefined && at(task, path) !== value) throw new Error(`${entry.method}: ${path} is fixed by this method.`);
put(task, path, value);
}
+ validateDocumentedPaths(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 fa1255db4..13cb6fcf1 100644
--- a/test/captcha-native-providers.mjs
+++ b/test/captcha-native-providers.mjs
@@ -76,6 +76,20 @@ 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}: 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: {
+ websiteURL: url, metadata: { sceneId: 'scene', prefix: 'prefix', secret: 'page-provided-secret' },
+ } };
+ assert.throws(() => native.prepareNativeCaptchaTasks(providers, [entry]), /undocumented field metadata.secret/);
+ assert.equal(calls.length, 0);
+ const allowed = { ...entry, parameters: { ...entry.parameters,
+ metadata: { sceneId: 'scene', prefix: 'prefix' } } };
+ assert.equal(native.prepareNativeCaptchaTasks(providers, [allowed]).length, 1);
+ // 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');
+ });
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'}});
const entries=[{provider:'2captcha',method:'GeeTestTaskProxyless',parameters:{websiteURL:url,version:4,initParameters:{captcha_id:'id'}}},{provider:'capsolver',method:'GeeTestTaskProxyLess',parameters:{websiteURL:url,captchaId:'id'}}];