Open-source AI browser agent for Chrome and Firefox (monorepo) ðŸ§
JavaScript ai-agentai-agentsai-toolsbrowser-aibrowser-automationbrowser-extensionchrome-aichrome-devtoolschrome-extensionchrome-extensionsfirefox-addonfirefox-addonsfirefox-extensionfirefox-extensionsgemmagemma4minimaxoffline-aioffline-llmqwen
Reject undocumented nested CAPTCHA parameters
Emre Sokullubf483e8dc7ac
diff --git a/docs/captcha-provider-coverage.md b/docs/captcha-provider-coverage.mdindex 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 tasProvider-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 answersdiff --git a/src/chrome/src/agent/captcha-native-providers.js b/src/chrome/src/agent/captcha-native-providers.jsindex 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.jsindex 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.mjsindex 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'}}];