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(guardrails): the release rules, the settings tab and the config it writes
Shahriar7f44e2206ac7
diff --git a/README.md b/README.mdindex 10e7957..c3502c9 100644--- a/README.md+++ b/README.md@@ -12,7 +12,7 @@ Hand your real, logged-in browser to the AI agent you already run. Browsentic is- **Voice, Text, or Demonstration**: Dictate in the side panel, type anywhere, or record yourself doing a job once and later say "do it like last time"- **Teach It a Site Once**: Point it at a site and it explores and writes reusable notes, so every later session already knows its way around- **Instant Commands**: "Go back", "scroll to the top", "open github.com" run in the browser in milliseconds instead of becoming an agent round trip-- **Guardrails, Not Vibes**: A declarative policy gates consequential actions, confines each run to the sites it is about, and marks every byte of page text as untrusted data+- **Guardrails, Not Vibes**: A declarative policy gates consequential actions, confines each run to the sites it is about, and marks every byte of page text as untrusted data — tunable per rule from a Settings tab, with nothing overridden until you say so- **Off By Default**: A fresh install contacts nothing until you redeem a one-time pairing code## Quick Startdiff --git a/docs/guide/approvals.md b/docs/guide/approvals.mdindex 6ac1b2a..9206d5e 100644--- a/docs/guide/approvals.md+++ b/docs/guide/approvals.md@@ -50,6 +50,9 @@ depend on declaration order.| `file-upload` | `page_attachFile` — putting one of your files into a page | confirm || `leaves-pinned-tab` | Moving to a tab the run was not pointed at | confirm || `captcha-solve` | `page_solveCaptcha` — ticking a site's "I am a human" box | confirm |+| `secret-in-url` | A saved secret placed in a navigation URL | **deny** |+| `secret-release` | A saved secret about to be typed into the page | confirm |+| `secret-off-scope` | …and it was read on a site outside this run's scope | confirm || `config-require-approval` | The action is named in your `requireApproval` list | confirm |Two of these are less obvious than they look:@@ -123,6 +126,51 @@ gate stops being information.---+## The Settings tab++Everything below is editable from **Settings** in the side panel, without opening a file.++The screen is a list of **overrides**, not a list of switches that turn protection on. Every row+starts off, meaning "use the default Browsentic ships" — so a fresh install has an empty settings+tab and the posture you get is the posture described here, whether or not you ever open it.++Turning a row on reveals **Allow / Ask / Block** and writes that one line to+`~/.browsentic/config.json`. Turning it back off removes the line rather than writing a value equal+to the default, so your config file only ever names decisions you actually made — and a change to a+shipped default still reaches you.++A run takes its policy when it starts. A change applies to the next run, not one already going.++Three rows are shown but **locked**: `reserved-action`, `non-http-navigation` and `secret-in-url`.+Allowing a `javascript:` URL, letting a page call an internal verb, or letting a credential travel+in a query string are not preferences, and none of them has a use worth a switch you can hit by+accident. Hand-editing config.json still works if you genuinely mean it.++Credential sealing appears in the list with no switch at all, because there is nothing to turn off:+it is what keeps a plaintext password off the socket in the first place.++---++## Secrets are sealed before you are asked++Before any of this runs, a deterministic sanitizer takes credentials out of what the browser hands+back. A password, key, token, cookie or card number found in a page is replaced by a placeholder+that names what it was and where it came from:++```+Your new password is ⟦password:[email protected]⟧+```++The agent never sees the value. It stays in the browser and becomes plaintext again at exactly one+moment: when the agent types it into a page field, which is when `secret-release` asks you first.+That is why the flow works at all — the agent can carry a reset password from the mail page to the+login form without ever being able to read it, repeat it, or put it in a URL.++If you see `⟦…⟧` in the panel, nothing has gone wrong. That is a credential being handled.+[How it works](../internals/guardrails.md#sealed-secrets).++---+## What this does not coverThe policy governs what an agent may do **to a page**. What the spawned CLI may do **to yourdiff --git a/docs/guide/configuration.md b/docs/guide/configuration.mdindex b22a460..b5990a2 100644--- a/docs/guide/configuration.md+++ b/docs/guide/configuration.md@@ -65,6 +65,11 @@ Eight tab sessions may be *open* at once regardless; that ceiling is compiled in## Approvals and guardrails+Most of this section has a UI: the side panel's **Settings** tab writes these same keys, one row at+a time. Rows start off — meaning "use the default" — so an install that never opens the tab has no+`guardrails` key at all. Turning a row back off deletes its line rather than writing the default,+which is why a hand-edited file and a panel-edited file look the same.+| Key | Default | Notes || --- | --- | --- || `requireApproval` | `["page.submitForm"]` | Actions an agent run must ask about first. Listing `page.submitForm` also catches `pressEnter: true` and pressing Enter, because those submit forms too |@@ -74,7 +79,7 @@ Eight tab sessions may be *open* at once regardless; that ceiling is compiled in| `guardrails.hosts` | — | Standing host allowlist added to every run's scope. `["*"]` disables host confinement entirely || `guardrails.fence` | `true` | Whether page-derived text is wrapped and marked as untrusted data |-Every rule id and what it does: [Approvals](approvals.md).+Every rule id and what it does, plus the three that the panel shows but will not change: [Approvals](approvals.md).## Pathsdiff --git a/docs/internals/extension.md b/docs/internals/extension.mdindex c1802af..c0a98b4 100644--- a/docs/internals/extension.md+++ b/docs/internals/extension.md@@ -35,6 +35,17 @@ it is the documented escape hatch.---+## The panel's tabs++`PanelNav` owns the tab strip: **Chat**, **History**, **Skills**, **Recordings**, **Settings**.+Adding one is a variant in `PanelTab`, an entry in `TABS`, and a branch in the side panel's body —+there is no router.++**Settings** is the only tab whose state lives on the daemon rather than in extension storage. It+reads and writes `~/.browsentic/config.json` through two bridge ops, `guardrails` and+`setGuardrail`, which forward to the socket frames of the same name. The extension holds no copy:+every write returns the daemon's fresh view, which is what the panel then renders.+## Tab scopingA panel conversation is **bound to the tab it started in**.diff --git a/docs/internals/guardrails.md b/docs/internals/guardrails.mdindex 1554b97..c53d2c4 100644--- a/docs/internals/guardrails.md+++ b/docs/internals/guardrails.md@@ -46,6 +46,9 @@ The condition vocabulary is closed on purpose: a rule cannot express anything th| `file-upload` | `uploadsFile` | confirm | `page.attachFile` || `leaves-pinned-tab` | `leavesPinnedTab` | confirm | A tab move away from the pinned tab, to a tab the run does not own || `captcha-solve` | `answersCaptcha` | confirm | `page.solveCaptcha` |+| `secret-in-url` | `carriesSecretInUrl` | **deny** | A sealed secret placeholder appears in a navigation URL |+| `secret-release` | `releasesSecret` | confirm | A sealed secret is about to be typed into the page |+| `secret-off-scope` | `releasesSecretOffScope` | confirm | …and it was read on a site outside the run's scope || `config-require-approval` | `listedInConfig` | confirm | The action is named in `requireApproval` |Two are worth the annotation they carry in source:@@ -90,6 +93,25 @@ The default is `deny`. Leaning on the client's host to prompt stops being true tallowlists the browsentic tools to stop being asked — so a caller with nobody watching does not getthe consequential actions. `unattended: 'allow'` goes back to waiving them.+### The settings screen++`guardrailSettings()` in [settings.ts](../../mcp/src/guardrails/settings.ts) describes the policy to+the side panel's Settings tab. Everything it returns is derived from `DEFAULT_RULES` and the live+config, so a rule added to the policy appears in the screen with no second edit, and a rule whose+title or reason changes says the new thing in both places.++Two things it gets right that are easy to get wrong:++**`fallback` is not the shipped constant.** `form-submission` takes its default from the legacy+`requireApproval` key, so the row is computed by re-running `policyFrom` with the rule overrides+stripped. Otherwise the screen would claim a default the policy does not use.++**An empty override is not the same as an override equal to the default.** Clearing a row deletes+the key, so config.json only names real decisions and a changed default still reaches that install.++`settingWritable()` is the gate: unknown ids, locked rules and wrong-shaped values are refused at+the daemon, not just hidden in the UI.+### Overriding```json@@ -165,6 +187,108 @@ it removes the easy win, where page text is indistinguishable from the transcrip---+## Sealed secrets++Fencing tells the model that page text is data. Sealing goes further for one class of it: a+credential is removed from the text entirely and replaced by a placeholder that says what it was.++```+Your new password is ⟦password:[email protected]⟧+Your API key: sk-ant-…⟦api-key:[email protected]⟧+Card ending ⟦card:[email protected]⟧…4242+```++The value itself stays in the browser. It is not in the tool result, not in the transcript, not in+the model's context, and it never crosses the socket.++### The detector is deterministic++No model, no scoring, no dependence on what was asked — the same text always yields the same+findings. That is not a stylistic preference: the client seals and the daemon seals again, and the+second pass can only leave the first one's work alone if both agree about what a secret is.++Three passes, in `lib/secrets/`:++| Pass | Finds | Example |+| --- | --- | --- |+| **Shapes** | Credentials that announce their own format | `sk-ant-…`, `ghp_…`, `AKIA…`, a JWT, a PEM block, a card that passes Luhn |+| **Labels** | A value next to a word that names it, inline or as an object key | `password: …`, `{"apiKey": …}`, `Cookie: …`, `newPassword`, `access_token` |+| **Entropy** | A bare token that announces nothing | 32+ characters, mixed classes, ≥ 4.3 bits/char **and** ≥ 0.5 case flips per letter |++The label vocabulary is written once, as word parts, and both readers are generated from it — the+inline regex joins the parts with an optional separator, the key matcher joins them bare. They+cannot drift, and `yarn check:security` asserts every word is readable both ways.++The entropy gate carries two signals because one is not enough. `ContinueReadingTheFullArticleHere`+reaches 3.96 bits per character; a random 32-character token reaches 4.5–5.0, and flips case about+half the time where an identifier flips once per word. Measured over both populations the ranges do+not overlap. Hex strings, UUIDs, anything inside a URL path and anything inside a `data:` URL are+excluded outright — those are digests, ids and asset hashes, not credentials.++Placeholders are left alone, so `password: ********` still reads as a page that says nothing. A+`selector` is never scanned, because the agent has to hand it back verbatim.++### What may be revealed++Truncating from the middle is only useful if what survives says something, and the only characters+that say something without giving anything away are the ones a vendor puts there as a format+marker. `sk-ant-` and `ghp_` are public by construction; four characters of a password are four+characters of a password. So `reveal` is declared per shape and defaults to nothing.++Cards are the one exception: the last four are conventional, and are what lets a person recognise+their own card.++### Releasing one++The vault lives in the extension, in `storage.session`, and nowhere else — so the daemon, which+spawns an agent CLI and serves MCP clients over a local socket, holds no credential it could leak.+The daemon's half of the sanitizer **only seals**. It has no way to turn a handle back.++A handle becomes plaintext at exactly one place: one hop before the content script, in+`invokeForHarness`, and only in a field that types into a page.++```+page.fillInput → value+page.typeText → text+```++A handle anywhere else — a URL, a selector, a search box — is refused with `SECRET_NOT_RELEASABLE`+rather than passed through, because a form filled with `⟦…⟧` fails in a way nobody can read. A+handle the vault no longer holds comes back as `SECRET_EXPIRED`.++That is the flow the vault exists for: a reset password read off one page and submitted on another,+without the value ever being something the model saw, stored, or could repeat.++### A page cannot forge one++The tag at the end of a handle is minted once per browser session and is never rendered into page+text, a tool result or a transcript. A page can author the brackets; it cannot author the tag.++Two consequences. A page-planted handle **resolves to nothing**, because release checks the tag.+And sealing in the extension is strict: any bracket that is not one of our own handles is rewritten,+so a forgery does not even survive the trip out of the page. The daemon's pass is deliberately+lenient in the other direction — it did not mint those handles and leaves them alone, which is what+makes sealing idempotent across both sides.++Entries expire after two hours, cap at 64, and are gone when the browser closes.++What this does **not** stop is the agent itself. A handle is in the model's context, and an+injected agent can choose to put one in a field on a page it is already on. That is why release+is a gated action rather than a silent one: `secret-release` asks, and `secret-off-scope` says so+when the credential was read somewhere else. The seal removes the value from the model's reach;+the policy is what decides where the model may spend it.++### Where it runs++| Side | Where | What it does |+| --- | --- | --- |+| Extension | `invokeForHarness` | Seals every action result before it crosses the socket; releases into the two fields |+| Daemon | `render()` and the resource reader | Seals every tool result and resource body on its way to any MCP client |+| Daemon | `summarize()` / `invokeExternal` | Seals the one-line summaries the side panel renders |+| Daemon | the run's stream sink | Seals what the agent writes back to the user, holding the tail of the stream so a credential split across two deltas is still caught |++---+## Spawn containmentEverything above governs what the model may do **to a page**. This governs what it may do **to thediff --git a/docs/internals/transport.md b/docs/internals/transport.mdindex d68c8d7..3081128 100644--- a/docs/internals/transport.md+++ b/docs/internals/transport.md@@ -94,7 +94,7 @@ dialling — but it never deletes the stored key. Only pairing again or `disconn## Protocol version-Both sides compile in `SOCKET_PROTOCOL_VERSION` (currently **11**). A mismatch closes the socket+Both sides compile in `SOCKET_PROTOCOL_VERSION` (currently **12**). A mismatch closes the socketwith an explicit reason instead of letting two incompatible frame vocabularies talk past each other.---