Skip to content

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

fix: honor observer opt-outs when storage is unavailable

Emre Sokullud3e7766cf135
diff --git a/docs/adding-a-tool.md b/docs/adding-a-tool.md
index 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.md
index 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] preamble
3. If site adapters enabled β†’ getActiveAdapter(url) β†’ inject adapter notes
4. 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 a
3-second window, the loop warning includes a `fetch_url({url, method})`
suggestion. For replayable XHR/fetch mutations, the observer also keeps bounded
request 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 transmitted
diff --git a/docs/privacy-and-data-flow.md b/docs/privacy-and-data-flow.md
index 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.js
index 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.md
index 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 equivalent
to Chrome's global `mime_types_handler`/`chrome.mimeHandler` route in this
extension. Firefox therefore keeps its native PDF viewer as the default and
uses 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 to
Firefox; the explicit Firefox entry remains available independently.
The explicit Firefox route is URL/GET based. It cannot replay an arbitrary
diff --git a/src/firefox/src/background.js b/src/firefox/src/background.js
index 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.mjs
index 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.js
index 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'],