Skip to content

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

docs: document Cloud Bridge browser approval and Firefox bridge

Mitchou102ac5cb1639cb
diff --git a/README.md b/README.md
index 66d430b71..75169ac1a 100644
--- a/README.md
+++ b/README.md
@@ -211,6 +211,7 @@ Chrome side panel shortcuts work when the WebBrain side panel has focus.
| [Providers and models](docs/providers-and-models.md) | All provider cards, local setup, tiers |
| [Skills](docs/skills.md) | Bundled skills, importing, skill tools |
| [Security model](docs/security-model.md) | Permissions, credentials, trust boundaries |
+| [Cloud Bridge approval](docs/cloud-bridge-browser-approval.md) | Opt-in browser registration and approval for backends |
| [Prompt-injection defense](docs/prompt-injection-defense.md) | Defense layers and known gaps |
| [Privacy and data flow](docs/privacy-and-data-flow.md) | What leaves the browser, and what doesn't |
| [Accessibility tree and refs](docs/accessibility-tree-and-refs.md) | How pages are read and targeted |
@@ -293,8 +294,12 @@ npx -y @webbrain/mcp-server
Once the server is running, open **WebBrain β†’ Settings β†’ General β†’ Advanced β†’
MCP**, set the URL to `ws://127.0.0.1:17374/extension`, and enable it.
-**Chromium only** β€” the control and bridge runtime use the extension's off-screen
-document, which the Firefox build does not have.
+On Chromium browsers the bridge runs from the extension's off-screen document.
+Firefox hosts it in the background page and is configured under **Settings β†’
+Cloud Bridge** instead (not yet verified against the MCP server on a real Firefox
+install). A backend that needs to approve each browser before it can send
+commands can use the opt-in token handshake described in
+[Cloud Bridge browser approval](docs/cloud-bridge-browser-approval.md).
If Settings reports **Connection error: WebSocket error**, nothing is normally
listening at the configured URL. Start the MCP server, confirm that the URL uses
diff --git a/docs/architecture.md b/docs/architecture.md
index 46e26d80e..7b9cb3e91 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -946,6 +946,7 @@ Firefox uses `browser.storage.session`.
| Screenshots | CDP `Page.captureScreenshot` with run-scoped focus emulation for background tabs | `browser.tabs.captureTab()` for direct inactive-tab capture |
| Conversation/UI persistence | `chrome.storage.session` | `browser.storage.session` |
| Offscreen document | Yes (fetch proxy + recorder + local WebGPU models) | Not available |
+| Cloud Bridge socket | Offscreen document (`offscreen/cloud-bridge.js`) | Background page (`cloud-bridge.js`) |
| Trace recorder | IndexedDB (opt-in) | IndexedDB (opt-in) β€” same `trace/recorder.js` |
| Duplicate-submit guard | Yes | Not available |
| `execute_js` | Dev mode through CDP `Runtime.evaluate` | Dev mode through the MV2 content-script evaluator |
diff --git a/docs/security-model.md b/docs/security-model.md
index 1ff43c1d0..3b156eddf 100644
--- a/docs/security-model.md
+++ b/docs/security-model.md
@@ -122,6 +122,19 @@ Users can store a short profile (name, email, throwaway password) in Settings
---
+### Cloud Bridge Browser Approval
+
+The Cloud Bridge lets a controller send `cloud_*` run commands to the browser. By default (no token) it behaves as before. When a Cloud Bridge token is configured the bridge adds an opt-in approval step:
+
+- Each socket sends a `hello` with the token, `browserId`, `installationId` and browser/extension/platform info, then is *pending*; the backend must answer `connection_approved` before any command runs. Earlier commands get `connection_not_approved` (403) and never reach the background.
+- Approval is **per socket**: a reconnect, URL change or identity change starts pending again. `connection_rejected` closes the socket and stops auto-reconnect, and cancels any pending reconnect timer.
+- The token is a Cloud Bridge credential, distinct from provider API keys. It is stored in `chrome.storage.local` and is never included in the bridge `status`.
+- The URL stays restricted to `ws://` on localhost, and the allowed actions stay limited to the `cloud_*` run operations. No cookies, tabs, history, provider keys or configuration cross the bridge.
+
+**Where it stops.** The permission prompts raised during a cloud run (navigate, click, …) are answered by the backend through `cloud_respond`, including "always". An approved backend is therefore effectively an operator of that browser. Approval is not persisted and can only be revoked by disabling the bridge or rotating the token. Details: [cloud-bridge-browser-approval.md](cloud-bridge-browser-approval.md).
+
+---
+
## Prompt Injection Defenses
The primary threat: a malicious page crafts content that, when read by the agent and fed to the LLM, causes the model to execute unintended actions.
diff --git a/mcp-server/README.md b/mcp-server/README.md
index 76d0b6a5d..30cd06903 100644
--- a/mcp-server/README.md
+++ b/mcp-server/README.md
@@ -22,7 +22,9 @@ cd mcp-server && npm install && npm run build
## Connect the browser
-> **Chromium only.** Chrome, Edge, Brave, Opera, Vivaldi. The bridge runs from the extension's **offscreen document**, and the Firefox build has none β€” `cloud-bridge.js` and `cloud-runs.js` live only under `src/chrome/`. See [`src/firefox/ARCHITECTURE.md`](../src/firefox/ARCHITECTURE.md).
+> **Chromium first.** Chrome, Edge, Brave, Opera, Vivaldi run the bridge from the extension's **offscreen document** (`src/chrome/src/offscreen/cloud-bridge.js`). Firefox has no offscreen document, so `src/firefox/src/cloud-bridge.js` runs it in the background page, configured under **Settings β†’ Cloud Bridge**; it has not yet been verified against this MCP server on a real Firefox install.
+>
+> This server does not use the optional browser-approval handshake (token, `connection_pending` / `connection_approved`). Without a token the extension behaves exactly as before. See [Cloud Bridge browser approval](../docs/cloud-bridge-browser-approval.md) for backends that want it.
The MCP server hosts the listener; the extension dials out to it. A Manifest V3 extension cannot listen on a socket, so the direction is fixed.
diff --git a/src/chrome/ARCHITECTURE.md b/src/chrome/ARCHITECTURE.md
index aa00266f4..325b58195 100644
--- a/src/chrome/ARCHITECTURE.md
+++ b/src/chrome/ARCHITECTURE.md
@@ -39,6 +39,7 @@ src/chrome/
β”œβ”€β”€ src/
β”‚ β”œβ”€β”€ background.js # Service worker β€” message router
β”‚ β”œβ”€β”€ run-ui-journal.js # Detached-run replay + streamed-text snapshots
+β”‚ β”œβ”€β”€ cloud-runs.js # cloud_* run controller + persistent bridge identity
β”‚ β”œβ”€β”€ agent/
β”‚ β”‚ β”œβ”€β”€ agent.js # Core agent loop + tool dispatch
β”‚ β”‚ β”œβ”€β”€ loop-detector.js # Browser-free loop detection, directly unit-tested
@@ -60,6 +61,7 @@ src/chrome/
β”‚ β”œβ”€β”€ offscreen/
β”‚ β”‚ β”œβ”€β”€ offscreen.html # Offscreen document host
β”‚ β”‚ β”œβ”€β”€ offscreen.js # HTTP fetch proxy (localhost/PNA fallback)
+β”‚ β”‚ β”œβ”€β”€ cloud-bridge.js # Outbound WebSocket bridge + browser-approval state
β”‚ β”‚ β”œβ”€β”€ vision-inference-host.js # Local WebGPU worker bridge
β”‚ β”‚ └── inference-worker.js # Transformers.js WebGPU inference worker
β”‚ β”œβ”€β”€ providers/
@@ -257,6 +259,19 @@ tabAudioSource.connect(audioContext.destination); // back to the user's speaker
Mic, by contrast, is only piped into the recording (NOT to the speaker β€”
that would feed back).
+### Cloud Bridge and browser approval
+
+`offscreen/cloud-bridge.js` dials out to a controller on localhost and accepts
+only the `cloud_*` run actions. `cloud-runs.js` reads the persistent identity
+(`webbrainCloudBridgeToken`, `…BrowserId`, `…InstallationId`) from
+`chrome.storage.local` and passes it with `cloud-bridge-start`, because the
+offscreen page has no storage access. With a token configured, each new socket
+sends an authenticated `hello` and stays *pending* until the backend answers
+`connection_approved`; commands before that get `connection_not_approved`.
+Approval is per socket and never carries over a reconnect. Without a token the
+legacy behaviour is unchanged. Protocol and limits:
+[docs/cloud-bridge-browser-approval.md](../../docs/cloud-bridge-browser-approval.md).
+
### Why a shared offscreen document
Chrome/Edge MV3 allows exactly one offscreen document per extension. The
diff --git a/src/firefox/ARCHITECTURE.md b/src/firefox/ARCHITECTURE.md
index 9e10ec66f..e6e1041c2 100644
--- a/src/firefox/ARCHITECTURE.md
+++ b/src/firefox/ARCHITECTURE.md
@@ -9,6 +9,7 @@ Firefox uses Manifest V2 (background page, not service worker) and has **no acce
- **Optional trusted events** β€” standard mode uses synthetic events. The experimental [BiDi companion](../../firefox-companion/README.md) adds trusted click, hover, text, supported keys, file-input attachment, and native JavaScript-dialog handling. It requires a local helper and Firefox remote automation; other tools retain their existing implementations. This is a Firefox-specific transport, not a Chrome CDP adapter.
- **No pixel-perfect / full-page screenshots** β€” uses `browser.tabs.captureTab()` instead of CDP `Page.captureScreenshot`; it can capture the run tab while that tab is inactive. Firefox has exposed `tabs.captureTab()` since Firefox 59, before WebBrain's current minimum, and the manifest declares the required `<all_urls>` permission.
- **No shadow DOM piercing** β€” content script can read open shadow roots via `element.shadowRoot`, but cannot pierce closed roots.
+- **Cloud Bridge lives in the background page** β€” with no offscreen document, `src/cloud-bridge.js` holds the outbound WebSocket and hands `cloud_*` commands straight to `handleMessage`; `src/cloud-runs.js` mirrors the Chrome controller and receives the bridge as an injected dependency. The protocol and optional browser approval are identical to Chrome ([docs/cloud-bridge-browser-approval.md](../../docs/cloud-bridge-browser-approval.md)).
- **No offscreen document** β€” no HTTP fetch proxy for localhost LLM servers with Private Network Access / CORS issues. User must ensure their local LLM server sends permissive CORS headers.
- **Some Chrome-only tools/features remain absent** β€” no CDP full-page screenshot, CDP upload automation, tab recording, offscreen fetch proxy, Chrome-only `shadow_dom_query`, or closed-shadow-root traversal.
@@ -103,7 +104,7 @@ src/firefox/
└── icons/
```
-Notable absences vs Chrome: no `cdp/`, no `offscreen/`, no `recorder/`, no `providers/fetch-with-fallback.js`.
+Notable absences vs Chrome: no `cdp/`, no `offscreen/`, no `recorder/`, no `providers/fetch-with-fallback.js`. The Cloud Bridge (`cloud-bridge.js`, `cloud-runs.js`) sits next to `background.js` instead of under `offscreen/`.
## Permissions