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: preserve API mutation opt-outs on storage errors
Emre Sokullu233011b28422
diff --git a/docs/security-model.md b/docs/security-model.mdindex 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 agentSet per-conversation via the `/allow-api` slash command in the side panel, orpersistently 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.mdindex 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 plannerprompt 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 wiWhen the API mutation observer setting is enabled, `background.js` records thelast 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.jsindex 2a22a6491..224f335b6 100644--- a/src/chrome/src/background.js+++ b/src/chrome/src/background.js@@ -199,7 +199,8 @@ const alwaysAllowApiMutationsReady = chrome.storage.localagent.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.mdindex 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 offscrPlanner prompts follow Chrome's token-minimal gating: the base planner promptincludes 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 responsesdiff --git a/src/firefox/src/background.js b/src/firefox/src/background.jsindex 0342c139e..fa0b86650 100644--- a/src/firefox/src/background.js+++ b/src/firefox/src/background.js@@ -147,7 +147,8 @@ const alwaysAllowApiMutationsReady = browser.storage.localagent.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.jsindex 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({});