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.
TypeScript agentic-browseragentic-browsingagy-cliaiai-agentai-browser-extensionai-toolsbrave-extensionbrowser-agentbrowser-automationbrowser-extensionbrowser-usebrowserskillchrome-extensionclaude-codecodexfirefox-addonmcp-servernanobrowserweb-automation
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.mdindex 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).## Contributingdiff --git a/docs/guide/approvals.md b/docs/guide/approvals.mdindex 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 askdiff --git a/docs/guide/features/README.md b/docs/guide/features/README.mdindex 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 pagediff --git a/docs/guide/features/blocked-sites.md b/docs/guide/features/blocked-sites.mdnew file mode 100644index 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.mdindex 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 **PreferencesThe 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 vibrowser 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.mdindex 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 ownfor the `leaves-pinned-tab` rule. A bare `page.switchTab` with no arguments only *lists* tabs, so itis not a move.diff --git a/docs/internals/state.md b/docs/internals/state.mdindex 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 thisbrowser 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 apage paints before any socket is up. `browsentic/theme.unsynced` marks a pick the daemon has not heardyet, handed over at the next connect. So do **diagnostics buffers** (`browsentic/diagnostics`), monitors anddiff --git a/docs/reference/errors.md b/docs/reference/errors.mdindex 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) |