Skip to content

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

fix: preserve API mutation opt-outs on storage errors

Emre Sokullu233011b28422
diff --git a/docs/security-model.md b/docs/security-model.md
index 0a3eecf11..e8316333f 100644
--- a/docs/security-model.md
+++ b/docs/security-model.md
@@ -138,7 +138,7 @@ The primary threat: a malicious page crafts content that, when read by the agent
| **Plan before Act** | When enabled, action-mode runs first produce a structured plan and wait for side-panel approval before any browser tool executes. In Try mode, planner JSON that remains invalid after repair degrades that turn to Ask/read-only; Strict stops. Scheduled runs can auto-approve the plan only through scheduler policy. |
| **Skill import boundary** | Skills can expose read-only HTTP tools and download-job tools through a `webbrain-tools` manifest. Importing or keeping the skill enabled is the trust decision for the declared HTTPS endpoint; declared skill tools use `credentials: "omit"` and should mark third-party results `resultPolicy: "untrusted"`. Download-job skill tools still require an action mode and the normal Downloads permission gate before saving files. |
| **WebMCP boundary** | Experimental WebMCP is off by default, so its tools and prompt guidance do not enter ordinary model requests unless the user opts in under Settings β†’ General β†’ Advanced. When enabled, Chrome page-registered names, descriptions, schemas, frame URLs, annotations, outputs, and errors are page-controlled and always use the untrusted-content wrapper. Calls use opaque IDs. Ask may list tools but cannot invoke them. Because a callback can run arbitrary page logic, every invocation requires Act/Dev, fresh per-call confirmation, and a permission grant for the actual registration-frame origin; a page-authored `readOnly` hint never bypasses those gates. Missing/opaque frame identity fails closed, and the frame plus effective HTTP(S) security origin are revalidated immediately before dispatch to prevent navigation races from borrowing an old grant. |
-| **API mutation override** | A per-conversation `/allow-api` flag, or the default-off persistent setting under General β†’ Advanced, *waives* the permission prompt for write-method network egress (`fetch_url`/`research_url` with POST/PUT/PATCH/DELETE). Neither option waives GET egress or any other capability. Conversation reset clears only the slash-command override. |
+| **API mutation override** | A per-conversation `/allow-api` flag, or the default-on persistent setting under General β†’ Advanced, *waives* the permission prompt for write-method network egress (`fetch_url`/`research_url` with POST/PUT/PATCH/DELETE). Neither option waives GET egress or any other capability. Conversation reset clears only the slash-command override. |
| **`done()` blocking** | Before accepting completion, the agent probes for open dialogs/forms. If the summary claims "created"/"saved" but a modal is still open, the agent is forced to continue. |
| **Duplicate-submit guard** | Clicks on submit-like text (create/save/submit/add/post/publish/send/confirm/sign up/log in/pay/checkout/order, etc.) are blocked within a 45-second window per tab+URL (Chrome). |
| **CLICK occlusion test** | Before clicking, the resolver calls `elementFromPoint()`. If another element is visually on top, the click is refused. |
@@ -161,8 +161,9 @@ The primary threat: a malicious page crafts content that, when read by the agent
Set per-conversation via the `/allow-api` slash command in the side panel, or
persistently with **Always allow API mutations** under **Settings β†’ General β†’
-Advanced**. The persistent setting is on by default. When either option is
-active, it waives the permission prompt for **write-method network egress only**:
+Advanced**. The persistent setting is on by default. If it cannot be read from
+storage, it grants no authorization. When either option is active, it waives
+the permission prompt for **write-method network egress only**:
- `fetch_url` / `research_url` with `method: POST/PUT/PATCH/DELETE`
diff --git a/src/chrome/ARCHITECTURE.md b/src/chrome/ARCHITECTURE.md
index d020a120d..3624b1d2d 100644
--- a/src/chrome/ARCHITECTURE.md
+++ b/src/chrome/ARCHITECTURE.md
@@ -103,7 +103,7 @@ src/chrome/
| Permission | Why |
|---|---|
| `debugger` | CDP access β€” trusted mouse/keyboard, pixel-perfect screenshots, shadow-DOM piercing. The single most important differentiator in the Chrome/Edge build vs Firefox. |
-| `webRequest` | Opt-in, in-memory same-tab XHR/fetch observer for repeated-click API shortcut hints and opaque same-origin replay. Off by default. |
+| `webRequest` | In-memory same-tab XHR/fetch observer for repeated-click API shortcut hints and opaque same-origin replay. On by default; can be disabled in Settings. |
| `alarms` | Scheduled tasks and scheduled resumes across browser sessions. |
| `unlimitedStorage` | Optional trace recorder persists agent runs (LLM I/O + screenshots) into IndexedDB. A multi-step run can be 1–10 MB; the default ~10 MB origin cap fills after a few runs. |
| `offscreen` | Hosts the localhost/PNA fetch proxy, tab recorder, and optional on-device WebGPU model worker. Chrome MV3 service workers cannot provide those document APIs directly. |
@@ -132,8 +132,8 @@ same cost allowance and abort checks as the main loop.
Planner prompts keep optional policy text mechanically gated. The base planner
prompt includes general repeated-task pacing, but API replay guidance is appended
-only when the tab conversation already has `/allow-api`; unavailable paths should
-not bloat every planner request.
+only when API mutations are authorized by the persistent setting or the tab's
+`/allow-api` override; unavailable paths should not bloat every planner request.
---
@@ -443,11 +443,13 @@ Before any submit-like text `click`, the agent checks a per-tab+URL 45-second wi
When the API mutation observer setting is enabled, `background.js` records the
last 40 same-tab XHR/fetch requests using `chrome.webRequest.onBeforeRequest`.
-The setting is off by default. When loop detection sees the same `click` /
-`click_ax` repeat, `_detectApiShortcut()` checks whether each click produced the
-same exact URL + method within 3 seconds. If so, the warning suggests
+The setting is on by default and can be disabled in Settings. When loop detection
+sees the same `click` / `click_ax` repeat, `_detectApiShortcut()` checks whether
+each click produced the same exact URL + method within 3 seconds. If so, the warning suggests
`fetch_url({url, method})` instead of another click. This is advisory only:
-POST/PUT/PATCH/DELETE still depend on the conversation's `/allow-api` state, and
+POST/PUT/PATCH/DELETE still depend on the persistent **Always allow API mutations**
+setting (on by default) or the conversation's `/allow-api` override. If the
+persistent setting cannot be read from storage, it grants no authorization.
GET/non-network capabilities still follow the normal permission gate.
### Ambiguous-click CDP enrichment (v3.6.4+)
@@ -834,7 +836,7 @@ Adapters may also opt into narrow runtime enforcement. On Douyin `/chat`, an `ac
- `debugger` β†’ trusted events on any tab.
- Cross-origin iframes reachable via content-script injection (extension privilege).
- Plan before Act can require user approval before any action-mode tool executes.
-- `/allow-api` flag required for API mutations (POST/PUT/PATCH/DELETE via `fetch_url`).
+- The persistent **Always allow API mutations** setting (on by default) or the conversation's `/allow-api` override waives permission prompts for API mutations (POST/PUT/PATCH/DELETE via `fetch_url` / `research_url`).
- Finance adapters layer extra confirmation guidance.
- Tool results capped at 8 KB to limit prompt-injection surface.
- Offscreen proxy only forwards requests the user's own code initiated (provider SDK traffic).
diff --git a/src/chrome/src/background.js b/src/chrome/src/background.js
index 2a22a6491..224f335b6 100644
--- a/src/chrome/src/background.js
+++ b/src/chrome/src/background.js
@@ -199,7 +199,8 @@ const alwaysAllowApiMutationsReady = chrome.storage.local
agent.setAlwaysAllowApiMutations(stored[ALWAYS_ALLOW_API_MUTATIONS_KEY] !== false);
})
.catch(() => {
- agent.setAlwaysAllowApiMutations(true);
+ // An unreadable setting must not bypass a stored opt-out.
+ agent.setAlwaysAllowApiMutations(false);
});
agent.setConversationScopeChangeListener((tabId, state) => {
chrome.runtime.sendMessage({
diff --git a/src/firefox/ARCHITECTURE.md b/src/firefox/ARCHITECTURE.md
index 2d0670196..5ba8488d0 100644
--- a/src/firefox/ARCHITECTURE.md
+++ b/src/firefox/ARCHITECTURE.md
@@ -132,7 +132,7 @@ Notably **missing** vs Chrome: `debugger`, `sidePanel`, `scripting`, `offscreen`
- No `debugger` β†’ no CDP, no trusted events
- No `offscreen` β†’ no HTTP fetch proxy; direct fetch from background page only
- No `privateNetworkAccess` β†’ localhost LLM servers must send CORS headers themselves
-- `webRequest` is used for the same opt-in in-memory API shortcut observer as Chrome. The setting is off by default.
+- `webRequest` is used for the same in-memory API shortcut observer as Chrome. The setting is on by default and can be disabled in Settings.
- Uses `sidebar_action` (MV2) instead of `side_panel` (MV3)
- Uses `browser.tabs.executeScript()` / `browser.tabs.sendMessage()` instead of `chrome.scripting.executeScript()`
@@ -573,9 +573,10 @@ Same end-to-end shape as Chrome, minus the CDP-trusted-event path and the offscr
Planner prompts follow Chrome's token-minimal gating: the base planner prompt
includes general repeated-task pacing, while API replay guidance is appended only
-when the tab conversation already has `/allow-api`. Both compact and full
-planner schemas carry a language-neutral messaging target only when the trusted
-request authorizes an external message.
+when API mutations are authorized by the persistent setting or the tab's
+`/allow-api` override. Both compact and full planner schemas carry a
+language-neutral messaging target only when the trusted request authorizes an
+external message.
---
@@ -603,8 +604,8 @@ Same as Chrome, minus CDP:
- Cross-origin iframes accessible via extension privilege
- Ask is read-only; Act and Dev are action modes. Dev adds source/style/page-inspection tools and is blocked for Compact-tier providers.
- Plan before Act can require user approval before any action-mode tool executes
-- API shortcut observer is off by default; when enabled, it records bounded same-tab XHR/fetch replay metadata in memory only
-- `/allow-api` flag required for API mutations (POST/PUT/PATCH/DELETE via `fetch_url`)
+- API shortcut observer is on by default and can be disabled in Settings; when enabled, it records bounded same-tab XHR/fetch replay metadata in memory only
+- The persistent **Always allow API mutations** setting (on by default) or the conversation's `/allow-api` override waives permission prompts for API mutations (POST/PUT/PATCH/DELETE via `fetch_url` / `research_url`). If the persistent setting cannot be read from storage, it grants no authorization.
- Finance adapters get extra safety warnings
- Tool results capped at 8KB
- No remote code execution: all providers called via `fetch()` with user-supplied keys; no eval of LLM responses
diff --git a/src/firefox/src/background.js b/src/firefox/src/background.js
index 0342c139e..fa0b86650 100644
--- a/src/firefox/src/background.js
+++ b/src/firefox/src/background.js
@@ -147,7 +147,8 @@ const alwaysAllowApiMutationsReady = browser.storage.local
agent.setAlwaysAllowApiMutations(stored[ALWAYS_ALLOW_API_MUTATIONS_KEY] !== false);
})
.catch(() => {
- agent.setAlwaysAllowApiMutations(true);
+ // An unreadable setting must not bypass a stored opt-out.
+ agent.setAlwaysAllowApiMutations(false);
});
agent.setConversationScopeChangeListener((tabId, state) => {
browser.runtime.sendMessage({
diff --git a/test/run.js b/test/run.js
index 7ae934910..b8363f83c 100644
--- a/test/run.js
+++ b/test/run.js
@@ -73890,6 +73890,41 @@ test('agent clearConversation drops /allow-api override in both builds', () => {
}
});
+for (const [label, AgentClass] of [['chrome', AgentCh], ['firefox', AgentFx]]) {
+ for (const { name, stored, storageError, expected } of [
+ { name: 'missing setting defaults on', stored: {}, expected: true },
+ { name: 'explicit opt-in stays on', stored: { alwaysAllowApiMutations: true }, expected: true },
+ { name: 'explicit opt-out stays off', stored: { alwaysAllowApiMutations: false }, expected: false },
+ { name: 'storage read failure keeps authorization off', storageError: true, expected: false },
+ ]) {
+ test(`${label} persistent API mutation startup: ${name}`, async () => {
+ const source = fs.readFileSync(path.join(ROOT, `src/${label}/src/background.js`), 'utf8');
+ const start = source.indexOf('const ALWAYS_ALLOW_API_MUTATIONS_KEY =');
+ const end = source.indexOf('agent.setConversationScopeChangeListener(', start);
+ assert.ok(start >= 0 && end > start, `${label}: persistent permission startup block missing`);
+ const agent = new AgentClass({});
+ const api = {
+ storage: {
+ local: {
+ get: async (defaults) => {
+ if (storageError) throw new Error('Storage unavailable');
+ return { ...defaults, ...stored };
+ },
+ },
+ },
+ };
+ const ready = vm.runInNewContext(
+ `${source.slice(start, end)}\nalwaysAllowApiMutationsReady;`,
+ { agent, [label === 'chrome' ? 'chrome' : 'browser']: api },
+ );
+ const tabId = 4897;
+ assert.equal(agent.isApiMutationsAllowed(tabId), false, 'permission must wait for storage hydration');
+ await ready;
+ assert.equal(agent.isApiMutationsAllowed(tabId), expected);
+ });
+ }
+}
+
test('persistent API mutation permission is global and independent of /allow-api lifecycle', () => {
for (const AgentClass of [AgentCh, AgentFx]) {
const agent = new AgentClass({});