Skip to content

An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.

docs: blocked sites — writing a pattern, what it stops, why nothing on the daemon's side can override it, SITE_BLOCKED, and where the list lives

Shahriarea21bf64fec0
diff --git a/README.md b/README.md
index 562d03f..9ebdd62 100644
--- a/README.md
+++ b/README.md
@@ -129,7 +129,7 @@ The extension dials out to the daemon, because a Manifest V3 service worker cann
## Privacy and Security
-Nothing connects until you pair, both ends prove themselves, consequential actions ask first, and credentials on a page are sealed before the agent sees them. The full model is in [SECURITY.md](SECURITY.md), and what it does not cover is in [Limits](docs/guide/limits.md).
+Nothing connects until you pair, both ends prove themselves, consequential actions ask first, credentials on a page are sealed before the agent sees them, and the sites you [block](docs/guide/features/blocked-sites.md) are off-limits to every agent — enforced in the browser, where none of them can reach the list. The full model is in [SECURITY.md](SECURITY.md), and what it does not cover is in [Limits](docs/guide/limits.md).
## Contributing
diff --git a/docs/guide/approvals.md b/docs/guide/approvals.md
index 58702fe..7978302 100644
--- a/docs/guide/approvals.md
+++ b/docs/guide/approvals.md
@@ -110,6 +110,14 @@ block "search for X" on an empty tab.
`example.com` in scope covers `www.example.com` and `app.example.com`. `["*"]` in
`guardrails.hosts` disables host confinement entirely.
+### Sites that are never in scope
+
+Scope is a question the daemon answers per run, and config.json can widen it. For a site the agent
+must never touch at all, use [Blocked sites](features/blocked-sites.md) instead: the extension enforces
+that list itself, before any of these rules run, and nothing on the daemon's side can read or change
+it. A run started from a blocked tab does not send its address, so it begins unconfined, as from a
+blank tab — and every action on the blocked site is refused all the same.
+
---
## Callers with nobody to ask
diff --git a/docs/guide/features/README.md b/docs/guide/features/README.md
index afb05d1..c9cb171 100644
--- a/docs/guide/features/README.md
+++ b/docs/guide/features/README.md
@@ -14,6 +14,7 @@ first.
| [Instant commands](instant-commands.md) | "go back", "scroll to the top" — the things that run in milliseconds without waking an agent |
| [A-Eye](a-eye.md) | Point at an element instead of describing it, and let it point back when it needs to |
| [Profile](profile.md) | Your details and standing rules, saved once, so it fills a form with the real thing instead of guessing |
+| [Blocked sites](blocked-sites.md) | Sites it never reads or acts on, whoever is driving — enforced in the browser, out of the agent's reach |
| [Skills](skills.md) | How an instruction gets routed to the right playbook, and how to write your own |
## Acting on a page
diff --git a/docs/guide/features/blocked-sites.md b/docs/guide/features/blocked-sites.md
new file mode 100644
index 0000000..8218f5c
--- /dev/null
+++ b/docs/guide/features/blocked-sites.md
@@ -0,0 +1,73 @@
+# Blocked sites
+
+Sites Browsentic never reads or acts on — your bank, your mail, the company admin console. Whatever is
+driving the browser, it stops at the edge of a blocked page, and nothing on the other side of the
+socket can talk it out of that.
+
+Open settings from the sliders button at the top of the side panel or the popup, and pick
+**Blocked sites**. It works without pairing.
+
+---
+
+## Writing a pattern
+
+| Pattern | Blocks |
+| --- | --- |
+| `mybank.com` | The whole site — every subdomain, every page. `https://www.mybank.com/` is stored the same way |
+| `mail.example.com` | That subdomain and anything below it, not the rest of `example.com` |
+| `example.com/admin` | `/admin` and everything under it — `/admin/users`, `/admin?tab=2` — but not `/administrator` |
+| `github.com/*/settings` | `*` stands for any run of characters, slashes included |
+| `example.com/checkout*` | Every path that starts with `/checkout` |
+| `shop.*` | The same name on any domain ending — `shop.com`, `shop.co.uk`, `www.shop.de` |
+| `localhost:3000` | One port. Without a port, every port |
+
+Matching ignores case and the part after `#`. The address is tidied before it is compared, so `/%61dmin`
+is `/admin` and `//admin` is `/admin`. A path pattern with a query (`example.com/search?q=private`)
+matches that query in that order. Only web pages can be blocked; browser pages are out of reach anyway.
+
+**Check a page** at the bottom of the section tells you which pattern, if any, blocks an address you paste.
+
+## What it stops
+
+Everything Browsentic could do to a matching page, whoever asked:
+
+- **Reading it** — page info, text, screenshots, the console and the network log.
+- **Acting on it** — clicking, typing, filling, submitting, scrolling, code, downloads, captchas.
+- **Going there** — `page_navigate` and `page_openTab` to a blocked address are refused before the
+ browser loads it, and a redirect or a click that lands somewhere blocked is caught after the fact:
+ nothing read there comes back.
+- **Seeing it in passing** — a blocked tab is left out of the agent's tab list, never matched by name,
+ and cannot be switched to or closed. A run started from a blocked tab does not send its address.
+- **Your own tools** — [instant commands](instant-commands.md), saved tools, the ones set to run on
+ every visit, [A-Eye](a-eye.md), **Attach page** and [recording](recordings.md) all refuse it too.
+- **Things already running** — a [monitor](monitoring.md) or a [diagnostics](diagnostics.md) capture
+ ends when its tab moves onto a blocked site (the capture discards what it had collected), a recording
+ stops before the blocked page is written into it, and a [scheduled task](scheduling.md) that would
+ open one fails instead of starting.
+
+The agent gets `SITE_BLOCKED` and is told to stop rather than look for another way in. The side panel
+shows a banner while the active tab is blocked; the agent can still work in other tabs from there.
+
+## Why nothing can override it
+
+The list lives in this browser's extension storage and nowhere else. No message from the daemon can
+read or write it, and the extension checks it before every page action, inside the browser — so neither
+the agent, an MCP client, nor anything that edits `~/.browsentic/config.json` can loosen it. The
+content script in the page checks it a second time, and the agent cannot steer a tab onto the settings
+page to edit it: page actions refuse anything that is not an http(s) page.
+
+That makes it different from [approvals](../approvals.md), which the daemon applies and you can tune
+per run: a blocked site is not a question the agent can ask.
+
+## Edges
+
+- **Per browser.** Each paired browser keeps its own list, and the desktop apps do not show it.
+- **A different address is a different site.** A site's IP address, or another of its domains, needs
+ its own pattern.
+- **Code on an allowed page can still send the page somewhere blocked.** Every action stops once the
+ tab is there, but the extension cannot stop the page's own requests.
+- **A blocked frame inside an allowed page** cannot be entered or acted on, but it can still appear in
+ a screenshot of the page around it.
+- **Saved tools that run on every visit** skip a blocked path from inside the page, which the page's
+ own code could interfere with; a site blocked as a whole never gets the tool at all.
+- Up to 500 patterns of up to 200 characters each.
diff --git a/docs/internals/extension.md b/docs/internals/extension.md
index 6018934..e79d935 100644
--- a/docs/internals/extension.md
+++ b/docs/internals/extension.md
@@ -103,7 +103,7 @@ lists it as **Options** on the toolbar icon's menu, and Firefox as **Preferences
The panel's header, the popup's header and the connection sheet open it with
`runtime.openOptionsPage()`, which focuses a settings tab already open rather than adding another.
-The page is a sidebar of five sections — **Extension**, **Profile**, **Guardrails**, **Agent**, **Connection** —
+The page is a sidebar of six sections — **Extension**, **Profile**, **Guardrails**, **Blocked sites**, **Agent**, **Connection** —
with the open one in the URL hash, so a reload or a link lands on it; an unknown hash,
such as the old `#appearance`, lands on **Extension**. **Agent** and **Connection** are the same
`AgentPicker` and `DaemonLink` the popup and the connection sheet show; those keep theirs, so a
@@ -117,6 +117,32 @@ page lists them with `commands.getAll()`, re-read whenever it comes back into vi
browser owns the keys and only its own page changes them — `chrome://extensions/shortcuts`
(`edge://` on Edge), or `commands.openShortcutSettings()` on Firefox.
+**Blocked sites** is the one section the daemon never sees. Its list is `browsentic/blockedSites` in
+`storage.local`, written only by `useBlockedSites()` on this page, and no socket frame carries it in
+either direction — the point of it is to bind the agent, so it cannot live on the agent's side of the
+socket. It is enforced here, in three layers:
+
+- **The gate** at the top of `invokeForHarness` ([invoke.ts](../../src/lib/bridge/invoke.ts)) checks the
+ target tab's `url` and `pendingUrl`, every frame on the focused path, and where the action would send
+ the browser (`navigate`, `captureDownload`). It is written as a list of exemptions — actions that touch
+ no tab, and `openTab`/`switchTab`/`closeTab`, which check the tab they pick in
+ [tabs.ts](../../src/lib/bridge/tabs.ts) — so an action added later is gated without anyone remembering
+ to. It also refuses any tab that is not an http(s) page, which is what keeps the debugger-backed
+ actions off the extension's own pages. After the action, the tab is checked again, and a result from a
+ tab that landed somewhere blocked is replaced by the refusal.
+- **The content script** re-checks its own frame's `location.href` before dispatching
+ ([host.ts](../../src/lib/actions/host.ts)).
+- **Everything that does not pass through the gate** checks for itself through
+ [site-guard.ts](../../src/lib/bridge/site-guard.ts): the scheduled-task tab, saved tools and their user
+ scripts, A-Eye, the recorder, monitors and diagnostics (which also end when their tab moves onto a
+ blocked site, or the list changes under them), recordings offered to the agent, and the run start,
+ which drops the tab's URL and the picked element.
+
+The list is read from storage on every check — a woken worker's memory is not the truth — and a value
+that is not a list refuses every web page rather than none. The pattern grammar is in
+[blocked-sites.ts](../../src/lib/settings/blocked-sites.ts), one RegExp per pattern so that a user
+script can carry the ones for its own origin.
+
**The theme and Guardrails are shared with the Mac app**, and the daemon keeps both in
`~/.browsentic/config.json`:
diff --git a/docs/internals/guardrails.md b/docs/internals/guardrails.md
index 606e6fb..690c386 100644
--- a/docs/internals/guardrails.md
+++ b/docs/internals/guardrails.md
@@ -169,6 +169,12 @@ on an empty tab.
`normalizeHost` drops a trailing root dot and a leading `www.` or `*.`, so a scope of `example.com`
covers `www.example.com` and `app.example.com`.
+A site the user has **blocked** never reaches this policy. That list is enforced in the extension,
+before `invokeForHarness` dispatches anything, and the daemon never learns it — see
+[extension.md § The settings page](extension.md#the-settings-page). A run started on a blocked tab
+arrives without a `url`, so its scope is the blank-tab one; the extension still refuses the site with
+`SITE_BLOCKED`.
+
`tabId` pins a run to one tab; `ownedTabIds` are tabs the run opened itself, which count as its own
for the `leaves-pinned-tab` rule. A bare `page.switchTab` with no arguments only *lists* tabs, so it
is not a move.
diff --git a/docs/internals/state.md b/docs/internals/state.md
index c802ff2..06e58dd 100644
--- a/docs/internals/state.md
+++ b/docs/internals/state.md
@@ -78,6 +78,9 @@ Only where the orb was dragged to (`browsentic/orbPosition`), whether hold-to-ta
(`browsentic/speechService`) are kept in `storage.local`, along with which right-click items this
browser shows (`browsentic/contextMenu`, both on when absent).
+**Blocked sites** are `browsentic/blockedSites` in `storage.local` — a list of patterns, up to 500, that
+the daemon never receives. Removing the extension removes it; each browser keeps its own.
+
**The theme** is config.json's `theme`, mirrored into `storage.local` under `browsentic/theme` so a
page paints before any socket is up. `browsentic/theme.unsynced` marks a pick the daemon has not heard
yet, handed over at the next connect. So do **diagnostics buffers** (`browsentic/diagnostics`), monitors and
diff --git a/docs/reference/errors.md b/docs/reference/errors.md
index 9c9c808..65f7659 100644
--- a/docs/reference/errors.md
+++ b/docs/reference/errors.md
@@ -85,6 +85,7 @@ repeatedly: failures carry the *fix* in the message, and a failed tool call neve
| --- | --- | --- |
| `DECLINED` | Approval gate | The user said no. **Final** — do not seek another route to the same effect |
| `BLOCKED` | Policy | A `deny` rule matched, or a `confirm` with nobody to answer it. The message names why. [Guide](../guide/approvals.md) |
+| `SITE_BLOCKED` | Extension | The page — or where the action would take the browser, or where it ended up — is on the user's Blocked sites list. Also returned for every page action while that list cannot be read. **Final** — do not retry or reach it another way; tell the user. [Guide](../guide/features/blocked-sites.md) |
| `SECRET_NOT_RELEASABLE` | Extension | A sealed secret placeholder was passed somewhere it cannot be released. Only `page_fillInput`'s `value` and `page_typeText`'s `text` release one |
| `SECRET_EXPIRED` | Extension | That placeholder is no longer held — it aged out, or it was read in an earlier browser session. Read the value again |
| `MAPPING_READ_ONLY` | Mapping gate | A mapping run may only call the 14 read-only actions (plus `page_clickElement` when `allowClicks` is on) |