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
fix: honor observer opt-outs when storage is unavailable
Emre Sokullud3e7766cf135
diff --git a/docs/adding-a-tool.md b/docs/adding-a-tool.mdindex d539683df..6ac6a473e 100644--- a/docs/adding-a-tool.md+++ b/docs/adding-a-tool.md@@ -411,10 +411,10 @@ if (name === 'chrome_only_tool') {Every new tool should be classified for security:1. **Can it read or exfiltrate data from the page?** β Add credential-field sensitivity checks if it reads input values.-2. **Can it perform destructive mutations?** β Consider whether it should be gated behind `/allow-api`.+2. **Can it perform destructive mutations?** β Classify it under the normal permission gate. The persistent **Always allow API mutations** setting (on by default) or the conversation's `/allow-api` override waives prompts only for write-method network egress, not other mutating capabilities.3. **Can it be prompt-injected?** β If the tool accepts user-provided strings that end up in tool-call arguments, document the injection surface in the tool description.4. **Which mode/tier should expose it?** β Ask-only semantic read goes in `ASK_ONLY_TOOLS`; common action tools should join the smallest normal tier that can reliably use them; developer-only source/style/debug tools go in Dev-only; Full fallbacks that Mid should get only during debugging go in Dev-extended.-5. **Can it shortcut repeated UI actions to network calls?** β Keep the UI-first policy intact. The background API observer may surface exact XHR/fetch URL+method hints during click loops, plus an opaque `replayRequestId` when same-origin body/header replay material is available. Mutating `fetch_url` calls still need the conversation's `/allow-api` state, and hidden form tokens must stay behind the replay id rather than being exposed to the model. GET requests and non-network capabilities still use the normal permission gate.+5. **Can it shortcut repeated UI actions to network calls?** β Keep the UI-first policy intact. The background API observer may surface exact XHR/fetch URL+method hints during click loops, plus an opaque `replayRequestId` when same-origin body/header replay material is available. Write-method `fetch_url` / `research_url` calls are authorized by the persistent **Always allow API mutations** setting (on by default) or the conversation's `/allow-api` override. An unreadable persistent setting grants no authorization, and hidden form tokens must stay behind the replay id rather than being exposed to the model. GET requests and non-network capabilities still use the normal permission gate.See `docs/security-model.md` for the full threat model.diff --git a/docs/architecture.md b/docs/architecture.mdindex a19648442..049766d15 100644--- a/docs/architecture.md+++ b/docs/architecture.md@@ -163,7 +163,7 @@ background.js handleMessage('chat_start')_enrichUserMessageWithCurrentPage(tabId, messages, userMessage)1. Collect URL + title via chrome.tabs.get(tabId)- 2. If /allow-api set for this tab β inject [USER OVERRIDE] preamble+ 2. If persistent API permission or this tab's /allow-api is active β inject [API ALLOWED] preamble3. If site adapters enabled β getActiveAdapter(url) β inject adapter notes4. If provider supports vision (or dedicated vision model configured):a. Capture viewport screenshot via CDP@@ -868,15 +868,18 @@ Three independent detectors run after every tool call:When the API mutation observer is enabled and a repeated `click` /`click_ax` loop is detected, `_detectApiShortcut()` checks the per-tab-webRequest buffer populated by `background.js`. The observer is on by default.+webRequest buffer populated by `background.js`. The observer is on by default,+can be disabled in Settings, and stays disabled if its preference cannot be read.If each repeated click produced the same exact URL + HTTP method within a3-second window, the loop warning includes a `fetch_url({url, method})`suggestion. For replayable XHR/fetch mutations, the observer also keeps boundedrequest bodies and a small allowlist of replay-safe headers behind an opaque`replayRequestId`; hidden form tokens are reused internally by `fetch_url` only-for the same tab and origin, not printed into model context. Write methods still-require the conversation's `/allow-api` state; GET requests and non-network-capabilities still use the normal permission gate.+for the same tab and origin, not printed into model context. Write methods are+authorized by the persistent **Always allow API mutations** setting (on by+default) or the conversation's `/allow-api` override. An unreadable persistent+setting grants no authorization. GET requests and non-network capabilities still+use the normal permission gate.### Context Management (`agent.js`)@@ -974,7 +977,7 @@ Key points:- No additional auth: the agent IS the user's browser session- Ask is read-only; Act and Dev are action modes. Dev adds source/style/page-debugging tools and is blocked for Compact-tier providers.- Plan before Act can require human approval before any action-mode tool call-- `/allow-api` flag gates destructive HTTP methods via `fetch_url`+- The persistent **Always allow API mutations** setting (on by default) or the conversation's `/allow-api` override waives permission prompts for write-method `fetch_url` / `research_url` calls- Tool results capped at 8 KB to limit prompt-injection surface- `strictSecretMode` instructs the model not to quote credentials in summaries, redacts known credential values (including short numeric PIN/CVV values) out of everything a cloud run publishes, and fails closed to scalar redaction if its bounded secret registry fills- Trace data is local-only (IndexedDB), never transmitteddiff --git a/docs/privacy-and-data-flow.md b/docs/privacy-and-data-flow.mdindex e624c9e59..bdcb3cc73 100644--- a/docs/privacy-and-data-flow.md+++ b/docs/privacy-and-data-flow.md@@ -602,7 +602,7 @@ CDP capture β JPEG/PNG data URL| User memory auto-learn | Controls whether post-turn extractor calls run || Site adapters toggle | Controls whether site-specific guidance is prepended || Research escalation | Off by default; when enabled, permits per-prompt consent requests for the visible ChatGPT helper flow |-| `/allow-api` | Controls whether the agent can use API mutations |+| Always allow API mutations / `/allow-api` | The persistent setting (on by default) or a per-conversation override waives permission prompts for write-method network egress || CapSolver toggle | Controls whether CAPTCHA data is sent to a third-party solver |---diff --git a/src/chrome/src/background.js b/src/chrome/src/background.jsindex 224f335b6..c58e3ac22 100644--- a/src/chrome/src/background.js+++ b/src/chrome/src/background.js@@ -2584,7 +2584,8 @@ async function loadApiMutationObserverSetting() {const stored = await chrome.storage.local.get({ [API_MUTATION_OBSERVER_KEY]: API_MUTATION_OBSERVER_DEFAULT });setApiMutationObserverEnabled(stored[API_MUTATION_OBSERVER_KEY] !== false);} catch (e) {- setApiMutationObserverEnabled(API_MUTATION_OBSERVER_DEFAULT);+ // Do not capture requests when a stored opt-out cannot be read.+ setApiMutationObserverEnabled(false);}}diff --git a/src/firefox/ARCHITECTURE.md b/src/firefox/ARCHITECTURE.mdindex 5ba8488d0..5c95d7ab8 100644--- a/src/firefox/ARCHITECTURE.md+++ b/src/firefox/ARCHITECTURE.md@@ -18,7 +18,7 @@ PDF handling is an intentional platform exception: Firefox has no equivalentto Chrome's global `mime_types_handler`/`chrome.mimeHandler` route in thisextension. Firefox therefore keeps its native PDF viewer as the default anduses an explicit WebBrain PDF viewer context-menu entry when the user chooses-it. The Chrome-only automatic PDF viewer opt-in setting does not apply to+it. The Chrome-only automatic PDF viewer setting (on by default) does not apply toFirefox; the explicit Firefox entry remains available independently.The explicit Firefox route is URL/GET based. It cannot replay an arbitrarydiff --git a/src/firefox/src/background.js b/src/firefox/src/background.jsindex fa0b86650..dc1608b64 100644--- a/src/firefox/src/background.js+++ b/src/firefox/src/background.js@@ -1728,7 +1728,8 @@ async function loadApiMutationObserverSetting() {const stored = await browser.storage.local.get({ [API_MUTATION_OBSERVER_KEY]: API_MUTATION_OBSERVER_DEFAULT });setApiMutationObserverEnabled(stored[API_MUTATION_OBSERVER_KEY] !== false);} catch (e) {- setApiMutationObserverEnabled(API_MUTATION_OBSERVER_DEFAULT);+ // Do not capture requests when a stored opt-out cannot be read.+ setApiMutationObserverEnabled(false);}}diff --git a/test/pdf-selection.mjs b/test/pdf-selection.mjsindex bb19e61b7..f26d6eb66 100644--- a/test/pdf-selection.mjs+++ b/test/pdf-selection.mjs@@ -3,7 +3,7 @@import assert from 'node:assert/strict';import { readFile } from 'node:fs/promises';import path from 'node:path';-import { fileURLToPath } from 'node:url';+import { fileURLToPath, pathToFileURL } from 'node:url';import { chromium } from 'playwright';const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');@@ -105,7 +105,7 @@ async function testScannedPdfOcrContract() {}async function testOcrNormalizationKeepsOnlyBoundedNormalizedLines() {- const { normalizePdfOcrResult } = await import(ocrModulePath);+ const { normalizePdfOcrResult } = await import(pathToFileURL(ocrModulePath).href);const result = normalizePdfOcrResult({lines: [{ text: ' Keep this text ', x: 0.1, y: 0.2, width: 0.7, height: 0.04, confidence: 0.91 },@@ -152,7 +152,7 @@ async function testPdfResponseStreamingStopsAtTheByteLimit() {const firefoxModuleSource = await readFile(firefoxPdfStreamModulePath, 'utf8');assert.equal(firefoxModuleSource, chromeModuleSource, 'Chrome and Firefox must share the same streaming limit behavior');- const { readPdfResponseBytes } = await import(pdfStreamModulePath);+ const { readPdfResponseBytes } = await import(pathToFileURL(pdfStreamModulePath).href);let cancelled = false;const oversizedResponse = {headers: { get: () => '1' },diff --git a/test/run.js b/test/run.jsindex b8363f83c..bfe0958fa 100644--- a/test/run.js+++ b/test/run.js@@ -46648,6 +46648,56 @@ test('API mutation observer setting defaults on and controls the request observe}});+for (const label of ['chrome', 'firefox']) {+ for (const { name, stored, storageError, expected } of [+ { name: 'missing setting defaults on', stored: {}, expected: true },+ { name: 'explicit opt-in stays on', stored: { apiMutationObserverEnabled: true }, expected: true },+ { name: 'explicit opt-out stays off', stored: { apiMutationObserverEnabled: false }, expected: false },+ { name: 'storage read failure keeps capture off', storageError: true, expected: false },+ ]) {+ test(`${label} API mutation observer startup: ${name}`, async () => {+ const source = fs.readFileSync(path.join(ROOT, `src/${label}/src/background.js`), 'utf8');+ const start = source.indexOf('const API_REQUESTS_PER_TAB_LIMIT =');+ const end = source.indexOf('\nloadApiMutationObserverSetting();', start);+ assert.ok(start >= 0 && end > start, `${label}: observer startup block missing`);+ const requestListeners = new Set();+ const headerListeners = new Set();+ const event = (listeners) => ({+ addListener: (listener) => listeners.add(listener),+ removeListener: (listener) => listeners.delete(listener),+ });+ const api = {+ storage: {+ local: {+ get: async (defaults) => {+ if (storageError) throw new Error('Storage unavailable');+ return { ...defaults, ...stored };+ },+ },+ },+ webRequest: {+ onBeforeRequest: event(requestListeners),+ onBeforeSendHeaders: event(headerListeners),+ },+ };+ const context = { [label === 'chrome' ? 'chrome' : 'browser']: api };+ const ready = vm.runInNewContext(+ `${source.slice(start, end)}\nloadApiMutationObserverSetting();`,+ context,+ );+ assert.equal(requestListeners.size, 0, 'request capture must wait for storage hydration');+ assert.equal(headerListeners.size, 0, 'header capture must wait for storage hydration');+ await ready;+ assert.equal(requestListeners.size, expected ? 1 : 0);+ assert.equal(headerListeners.size, expected ? 1 : 0);+ if (!expected) {+ assert.equal(context.__webbrainApiRequests.size, 0);+ assert.equal(context.__webbrainApiRequestReplay.size, 0);+ }+ });+ }+}+test('persistent API mutation permission defaults on, is portable, and mirrored', () => {for (const [label, bgRel, settingsRel, htmlRel, panelRel, configRel] of [['chrome', 'src/chrome/src/background.js', 'src/chrome/src/ui/settings.js', 'src/chrome/src/ui/settings.html', 'src/chrome/src/ui/sidepanel.js', 'src/chrome/src/config-transfer.js'],