Skip to content

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

Route managed Cloud captcha solving through broker

Emre Sokullu1d2c29d80d00
diff --git a/package.json b/package.json
index 59bcbd99f..81118e46b 100644
--- a/package.json
+++ b/package.json
@@ -5,7 +5,7 @@
"private": true,
"type": "module",
"scripts": {
- "test": "npm run test:markdown && npm run test:systemone && npm run test:systemone:fast && node --test test/browser-dialogs.mjs && npm run test:firefox-bidi && npm run test:runtime-lifecycle && npm run test:provider-limits && npm run test:accessibility-tree-benchmark && npm run test:toolbar-guard && npm run test:pdf-read && npm run test:pdf-selection && npm run test:social-contract && npm run test:safesocial && npm run test:build-unpacked && npm run test:attachment-drop && node --test test/profile-sync-stats.mjs && node test/run.js && node test/selection-scope-restoration.mjs && node scripts/benchmark-offline-relevance.mjs && npm run test:security",
+ "test": "npm run test:markdown && npm run test:systemone && npm run test:systemone:fast && node --test test/browser-dialogs.mjs test/capsolver-cloud-broker.mjs && npm run test:firefox-bidi && npm run test:runtime-lifecycle && npm run test:provider-limits && npm run test:accessibility-tree-benchmark && npm run test:toolbar-guard && npm run test:pdf-read && npm run test:pdf-selection && npm run test:social-contract && npm run test:safesocial && npm run test:build-unpacked && npm run test:attachment-drop && node --test test/profile-sync-stats.mjs && node test/run.js && node test/selection-scope-restoration.mjs && node scripts/benchmark-offline-relevance.mjs && npm run test:security",
"test:provider-limits": "node test/provider-model-limits.mjs",
"test:markdown": "node --test test/markdown-render.mjs",
"test:accessibility-tree-benchmark": "node --test test/llm/lib/accessibility-tree-formats.test.mjs && node test/llm/accessibility-tree-benchmark.mjs --no-exact-tokenizer --check",
diff --git a/src/chrome/src/agent/agent.js b/src/chrome/src/agent/agent.js
index 2cf091836..c7c47b33a 100644
--- a/src/chrome/src/agent/agent.js
+++ b/src/chrome/src/agent/agent.js
@@ -35623,8 +35623,8 @@ If the user has already named or confirmed this exact recipient, do NOT ask agai
}
// ─── CAPTCHA solver ──────────────────────────────────────────────
- // A valid saved key is the enable control. Re-check it on every call so
- // rotating or clearing the key takes effect without a restart.
+ // Re-check consent and the active solver route on every call so changes
+ // take effect without a restart. Cloud browsers route through the broker.
if (name === 'solve_captcha') {
let dispatched = false;
const noDispatchFailure = (error) => ({
@@ -35634,9 +35634,17 @@ If the user has already named or confirmed this exact recipient, do NOT ask agai
error,
});
try {
- const stored = await chrome.storage.local.get(['capsolverApiKey', 'captchaSolverEnabled']);
+ const stored = await chrome.storage.local.get([
+ 'capsolverApiKey', 'captchaSolverEnabled',
+ 'webbrainCloudManaged', 'webbrainCloudCapsolverBrokerEnabled',
+ ]);
const apiKey = normalizeCapsolverApiKey(stored.capsolverApiKey);
- if (!isCapsolverEnabled(apiKey, stored.captchaSolverEnabled)) {
+ const useCloudBroker = stored.webbrainCloudManaged === true
+ && stored.webbrainCloudCapsolverBrokerEnabled === true;
+ if (stored.captchaSolverEnabled !== true
+ || (stored.webbrainCloudManaged === true
+ ? !useCloudBroker
+ : !isCapsolverEnabled(apiKey, true))) {
return noDispatchFailure('CapSolver is not enabled with a valid API key. Ask the user to save their key in Settings β†’ General β†’ Advanced, or fall back to asking them to solve the captcha manually.');
}
@@ -35792,7 +35800,7 @@ If the user has already named or confirmed this exact recipient, do NOT ask agai
}
dispatched = true;
- const result = await solveCaptcha(apiKey, params);
+ const result = await solveCaptcha(apiKey, params, { useCloudBroker });
// For non-image types, push the token into the page response field
// unless the caller explicitly opted out.
diff --git a/src/chrome/src/agent/captcha-solver.js b/src/chrome/src/agent/captcha-solver.js
index 5f1b05158..03ea69e8e 100644
--- a/src/chrome/src/agent/captcha-solver.js
+++ b/src/chrome/src/agent/captcha-solver.js
@@ -30,6 +30,7 @@ const API_BASE = 'https://api.capsolver.com';
const POLL_INTERVAL_MS = 2500;
const POLL_TIMEOUT_MS = 120_000;
const DEFAULT_APP_ID = 'B7E57F27-0AD3-434D-A5B7-CF9EE7D093EE'; // CapSolver public affiliate id; used only to identify the integration.
+const CLOUD_BROKER_URL = 'http://127.0.0.1:17373/capsolver/solve';
// ─── REST ──────────────────────────────────────────────────────────────
@@ -233,13 +234,31 @@ function solutionFor(type, solution) {
// ─── solveCaptcha β€” the public entry point ────────────────────────────
-export async function solveCaptcha(apiKey, params) {
- if (!apiKey) throw new Error('No CapSolver API key configured.');
+async function solveWithCloudBroker(task) {
+ const response = await fetch(CLOUD_BROKER_URL, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json', 'X-WebBrain-CapSolver-Broker': '1' },
+ body: JSON.stringify({ task }),
+ });
+ const result = await response.json().catch(() => ({}));
+ if (!response.ok) throw new Error(result.error || 'Cloud CapSolver broker failed.');
+ if (!result.taskId || !result.solution || typeof result.solution !== 'object') {
+ throw new Error('Cloud CapSolver broker returned an invalid result.');
+ }
+ return result;
+}
+
+export async function solveCaptcha(apiKey, params, { useCloudBroker = false } = {}) {
+ if (!apiKey && !useCloudBroker) throw new Error('No CapSolver API key configured.');
const paramError = captchaParamError(params);
if (paramError) throw new Error(paramError);
const task = buildTask(params);
- const taskId = await createTask(apiKey, task);
- const solution = await pollTaskResult(apiKey, taskId);
+ const { taskId, solution } = useCloudBroker
+ ? await solveWithCloudBroker(task)
+ : await (async () => {
+ const taskId = await createTask(apiKey, task);
+ return { taskId, solution: await pollTaskResult(apiKey, taskId) };
+ })();
const meta = solutionFor(params.type, solution);
return { taskId, solution, ...meta };
}
diff --git a/src/chrome/src/background.js b/src/chrome/src/background.js
index 6ea8d2c59..70a9e2d04 100644
--- a/src/chrome/src/background.js
+++ b/src/chrome/src/background.js
@@ -1080,15 +1080,16 @@ async function loadCustomSkills() {
}
const customSkillsReady = loadCustomSkills();
-// A valid key plus explicit consent enables CapSolver. Requiring the existing
-// boolean preserves legacy profiles that saved a key while the old switch was
-// off; pressing Save Key in the new UI sets consent to true.
+// Local browsers require a valid key and explicit consent. Managed Cloud
+// browsers use the broker flag and never use a CapSolver key from storage.
async function loadCaptchaSolver() {
- const stored = await chrome.storage.local.get(['capsolverApiKey', 'captchaSolverEnabled']);
- agent.captchaSolverEnabled = isCapsolverEnabled(
- stored.capsolverApiKey,
- stored.captchaSolverEnabled,
- );
+ const stored = await chrome.storage.local.get([
+ 'capsolverApiKey', 'captchaSolverEnabled',
+ 'webbrainCloudManaged', 'webbrainCloudCapsolverBrokerEnabled',
+ ]);
+ agent.captchaSolverEnabled = stored.webbrainCloudManaged === true
+ ? stored.captchaSolverEnabled === true && stored.webbrainCloudCapsolverBrokerEnabled === true
+ : isCapsolverEnabled(stored.capsolverApiKey, stored.captchaSolverEnabled);
}
loadCaptchaSolver();
@@ -1308,7 +1309,8 @@ chrome.storage.onChanged.addListener((changes, areaName) => {
}
refreshPrompts = true;
}
- if (changes.capsolverApiKey || changes.captchaSolverEnabled) {
+ if (changes.capsolverApiKey || changes.captchaSolverEnabled
+ || changes.webbrainCloudManaged || changes.webbrainCloudCapsolverBrokerEnabled) {
loadCaptchaSolver()
.then(() => agent._refreshSystemPrompts())
.catch((error) => console.warn('[WebBrain] CapSolver setting could not be refreshed', error));
diff --git a/src/chrome/src/ui/settings.js b/src/chrome/src/ui/settings.js
index 304a34928..c1d81d93c 100644
--- a/src/chrome/src/ui/settings.js
+++ b/src/chrome/src/ui/settings.js
@@ -935,8 +935,11 @@ async function init() {
await loadUserMemorySettings();
// A valid saved key is the CapSolver enable control.
- const captchaStored = await chrome.storage.local.get('capsolverApiKey');
- if (captchaApiKeyInput) captchaApiKeyInput.value = captchaStored.capsolverApiKey || '';
+ const captchaStored = await chrome.storage.local.get(['capsolverApiKey', 'webbrainCloudManaged']);
+ const cloudCaptchaCard = document.getElementById('captcha-card');
+ if (cloudCaptchaCard) cloudCaptchaCard.style.display = captchaStored.webbrainCloudManaged === true ? 'none' : '';
+ if (captchaApiKeyInput) captchaApiKeyInput.value = captchaStored.webbrainCloudManaged === true
+ ? '' : (captchaStored.capsolverApiKey || '');
await loadCustomSkills();
diff --git a/src/firefox/src/agent/agent.js b/src/firefox/src/agent/agent.js
index 1da212720..44ae73313 100644
--- a/src/firefox/src/agent/agent.js
+++ b/src/firefox/src/agent/agent.js
@@ -32620,9 +32620,17 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
error,
});
try {
- const stored = await browser.storage.local.get(['capsolverApiKey', 'captchaSolverEnabled']);
+ const stored = await browser.storage.local.get([
+ 'capsolverApiKey', 'captchaSolverEnabled',
+ 'webbrainCloudManaged', 'webbrainCloudCapsolverBrokerEnabled',
+ ]);
const apiKey = normalizeCapsolverApiKey(stored.capsolverApiKey);
- if (!isCapsolverEnabled(apiKey, stored.captchaSolverEnabled)) {
+ const useCloudBroker = stored.webbrainCloudManaged === true
+ && stored.webbrainCloudCapsolverBrokerEnabled === true;
+ if (stored.captchaSolverEnabled !== true
+ || (stored.webbrainCloudManaged === true
+ ? !useCloudBroker
+ : !isCapsolverEnabled(apiKey, true))) {
return noDispatchFailure('CapSolver is not enabled with a valid API key. Ask the user to save their key in Settings β†’ General β†’ Advanced, or fall back to asking them to solve the captcha manually.');
}
@@ -32775,7 +32783,7 @@ Rules: no prose intro, no conclusion, no "this screenshot shows...", no layout d
}
dispatched = true;
- const result = await solveCaptcha(apiKey, params);
+ const result = await solveCaptcha(apiKey, params, { useCloudBroker });
let injection = null;
if (wantInject && result.fieldName && result.token) {
diff --git a/src/firefox/src/agent/captcha-solver.js b/src/firefox/src/agent/captcha-solver.js
index b95f38663..ee219e2d2 100644
--- a/src/firefox/src/agent/captcha-solver.js
+++ b/src/firefox/src/agent/captcha-solver.js
@@ -27,6 +27,7 @@ const API_BASE = 'https://api.capsolver.com';
const POLL_INTERVAL_MS = 2500;
const POLL_TIMEOUT_MS = 120_000;
const DEFAULT_APP_ID = 'B7E57F27-0AD3-434D-A5B7-CF9EE7D093EE';
+const CLOUD_BROKER_URL = 'http://127.0.0.1:17373/capsolver/solve';
async function postJson(path, body) {
const res = await fetch(`${API_BASE}${path}`, {
@@ -199,13 +200,31 @@ function solutionFor(type, solution) {
return { token: null, fieldName: null };
}
-export async function solveCaptcha(apiKey, params) {
- if (!apiKey) throw new Error('No CapSolver API key configured.');
+async function solveWithCloudBroker(task) {
+ const response = await fetch(CLOUD_BROKER_URL, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json', 'X-WebBrain-CapSolver-Broker': '1' },
+ body: JSON.stringify({ task }),
+ });
+ const result = await response.json().catch(() => ({}));
+ if (!response.ok) throw new Error(result.error || 'Cloud CapSolver broker failed.');
+ if (!result.taskId || !result.solution || typeof result.solution !== 'object') {
+ throw new Error('Cloud CapSolver broker returned an invalid result.');
+ }
+ return result;
+}
+
+export async function solveCaptcha(apiKey, params, { useCloudBroker = false } = {}) {
+ if (!apiKey && !useCloudBroker) throw new Error('No CapSolver API key configured.');
const paramError = captchaParamError(params);
if (paramError) throw new Error(paramError);
const task = buildTask(params);
- const taskId = await createTask(apiKey, task);
- const solution = await pollTaskResult(apiKey, taskId);
+ const { taskId, solution } = useCloudBroker
+ ? await solveWithCloudBroker(task)
+ : await (async () => {
+ const taskId = await createTask(apiKey, task);
+ return { taskId, solution: await pollTaskResult(apiKey, taskId) };
+ })();
const meta = solutionFor(params.type, solution);
return { taskId, solution, ...meta };
}
diff --git a/src/firefox/src/background.js b/src/firefox/src/background.js
index fd4d09dfc..cc33461a2 100644
--- a/src/firefox/src/background.js
+++ b/src/firefox/src/background.js
@@ -956,15 +956,16 @@ async function loadCustomSkills() {
}
const customSkillsReady = loadCustomSkills();
-// A valid key plus explicit consent enables CapSolver. Requiring the existing
-// boolean preserves legacy profiles that saved a key while the old switch was
-// off; pressing Save Key in the new UI sets consent to true.
+// Local browsers require a valid key and explicit consent. Managed Cloud
+// browsers use the broker flag and never use a CapSolver key from storage.
async function loadCaptchaSolver() {
- const stored = await browser.storage.local.get(['capsolverApiKey', 'captchaSolverEnabled']);
- agent.captchaSolverEnabled = isCapsolverEnabled(
- stored.capsolverApiKey,
- stored.captchaSolverEnabled,
- );
+ const stored = await browser.storage.local.get([
+ 'capsolverApiKey', 'captchaSolverEnabled',
+ 'webbrainCloudManaged', 'webbrainCloudCapsolverBrokerEnabled',
+ ]);
+ agent.captchaSolverEnabled = stored.webbrainCloudManaged === true
+ ? stored.captchaSolverEnabled === true && stored.webbrainCloudCapsolverBrokerEnabled === true
+ : isCapsolverEnabled(stored.capsolverApiKey, stored.captchaSolverEnabled);
}
loadCaptchaSolver();
@@ -1153,7 +1154,8 @@ browser.storage.onChanged.addListener((changes) => {
}
refreshPrompts = true;
}
- if (changes.capsolverApiKey || changes.captchaSolverEnabled) {
+ if (changes.capsolverApiKey || changes.captchaSolverEnabled
+ || changes.webbrainCloudManaged || changes.webbrainCloudCapsolverBrokerEnabled) {
loadCaptchaSolver()
.then(() => agent._refreshSystemPrompts())
.catch((error) => console.warn('[WebBrain] CapSolver setting could not be refreshed', error));
diff --git a/src/firefox/src/ui/settings.js b/src/firefox/src/ui/settings.js
index c52733555..98904fbf5 100644
--- a/src/firefox/src/ui/settings.js
+++ b/src/firefox/src/ui/settings.js
@@ -697,8 +697,11 @@ async function init() {
await loadUserMemorySettings();
// A valid saved key is the CapSolver enable control.
- const captchaStored = await browser.storage.local.get('capsolverApiKey');
- if (captchaApiKeyInput) captchaApiKeyInput.value = captchaStored.capsolverApiKey || '';
+ const captchaStored = await browser.storage.local.get(['capsolverApiKey', 'webbrainCloudManaged']);
+ const cloudCaptchaCard = document.getElementById('captcha-card');
+ if (cloudCaptchaCard) cloudCaptchaCard.style.display = captchaStored.webbrainCloudManaged === true ? 'none' : '';
+ if (captchaApiKeyInput) captchaApiKeyInput.value = captchaStored.webbrainCloudManaged === true
+ ? '' : (captchaStored.capsolverApiKey || '');
await loadCustomSkills();
diff --git a/test/capsolver-cloud-broker.mjs b/test/capsolver-cloud-broker.mjs
new file mode 100644
index 000000000..601f13984
--- /dev/null
+++ b/test/capsolver-cloud-broker.mjs
@@ -0,0 +1,37 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { solveCaptcha as solveChrome } from '../src/chrome/src/agent/captcha-solver.js';
+import { solveCaptcha as solveFirefox } from '../src/firefox/src/agent/captcha-solver.js';
+
+for (const [browser, solveCaptcha] of [['Chrome', solveChrome], ['Firefox', solveFirefox]]) {
+ test(`${browser} sends brokered challenges without a CapSolver key`, async () => {
+ const originalFetch = globalThis.fetch;
+ const calls = [];
+ globalThis.fetch = async (url, options) => {
+ calls.push({ url, options });
+ return Response.json({ taskId: 'broker-task', solution: { token: 'challenge-token' } });
+ };
+ try {
+ const result = await solveCaptcha('', {
+ type: 'turnstile',
+ websiteURL: 'https://example.com/signup',
+ websiteKey: 'public-site-key',
+ }, { useCloudBroker: true });
+ assert.equal(result.taskId, 'broker-task');
+ assert.equal(result.token, 'challenge-token');
+ assert.equal(calls.length, 1);
+ assert.equal(calls[0].url, 'http://127.0.0.1:17373/capsolver/solve');
+ assert.equal(calls[0].options.headers['X-WebBrain-CapSolver-Broker'], '1');
+ assert.deepEqual(JSON.parse(calls[0].options.body), {
+ task: {
+ type: 'AntiTurnstileTaskProxyLess',
+ websiteURL: 'https://example.com/signup',
+ websiteKey: 'public-site-key',
+ },
+ });
+ assert.equal(calls[0].options.body.includes('clientKey'), false);
+ } finally {
+ globalThis.fetch = originalFetch;
+ }
+ });
+}
diff --git a/test/run.js b/test/run.js
index fcb65b64c..a7c1ee1cb 100644
--- a/test/run.js
+++ b/test/run.js
@@ -45720,20 +45720,24 @@ test('saving a valid CapSolver key opts in without overriding legacy opt-outs',
`${label}: saving a valid CapSolver key should record explicit consent`,
);
- assert.match(
- background,
- new RegExp(`const stored = await ${api}\\.storage\\.local\\.get\\(\\['capsolverApiKey', 'captchaSolverEnabled'\\]\\);[\\s\\S]*?agent\\.captchaSolverEnabled = isCapsolverEnabled\\([\\s\\S]*?stored\\.capsolverApiKey,[\\s\\S]*?stored\\.captchaSolverEnabled,[\\s\\S]*?\\);`),
- `${label}: background startup should require both a valid key and prior consent`,
+ assert.ok(
+ background.includes(`const stored = await ${api}.storage.local.get([`)
+ && background.includes('isCapsolverEnabled(stored.capsolverApiKey, stored.captchaSolverEnabled)')
+ && background.includes('stored.webbrainCloudManaged === true')
+ && background.includes('stored.webbrainCloudCapsolverBrokerEnabled === true'),
+ `${label}: background startup should require consent and a valid key or managed Cloud broker`,
);
assert.match(
background,
- /if \(changes\.capsolverApiKey \|\| changes\.captchaSolverEnabled\) \{[\s\S]*?loadCaptchaSolver\(\)[\s\S]*?agent\._refreshSystemPrompts\(\)/,
- `${label}: key or consent changes should refresh CapSolver availability immediately`,
+ /if \(changes\.capsolverApiKey \|\| changes\.captchaSolverEnabled[\s\S]*?changes\.webbrainCloudCapsolverBrokerEnabled\) \{[\s\S]*?loadCaptchaSolver\(\)[\s\S]*?agent\._refreshSystemPrompts\(\)/,
+ `${label}: key, consent, or broker changes should refresh CapSolver availability immediately`,
);
- assert.match(
- agent,
- new RegExp(`const stored = await ${api}\\.storage\\.local\\.get\\(\\['capsolverApiKey', 'captchaSolverEnabled'\\]\\);[\\s\\S]*?const apiKey = normalizeCapsolverApiKey\\(stored\\.capsolverApiKey\\);[\\s\\S]*?if \\(!isCapsolverEnabled\\(apiKey, stored\\.captchaSolverEnabled\\)\\)`),
- `${label}: solve_captcha should revalidate the saved key and consent at dispatch time`,
+ assert.ok(
+ agent.includes(`const stored = await ${api}.storage.local.get([`)
+ && agent.includes('stored.captchaSolverEnabled !== true')
+ && agent.includes('!isCapsolverEnabled(apiKey, true)')
+ && agent.includes('const result = await solveCaptcha(apiKey, params, { useCloudBroker });'),
+ `${label}: solve_captcha should revalidate consent and the direct key when the Cloud broker is absent`,
);
assert.equal(capsolverConfig.normalizeCapsolverApiKey(' CAP-0123456789abcdefghij '), 'CAP-0123456789abcdefghij');