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(guardrails): the release rules, the settings tab and the config it writes

Shahriar7f44e2206ac7
diff --git a/README.md b/README.md
index 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 Start
diff --git a/docs/guide/approvals.md b/docs/guide/approvals.md
index 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 cover
The policy governs what an agent may do **to a page**. What the spawned CLI may do **to your
diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md
index 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).
## Paths
diff --git a/docs/internals/extension.md b/docs/internals/extension.md
index 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 scoping
A panel conversation is **bound to the tab it started in**.
diff --git a/docs/internals/guardrails.md b/docs/internals/guardrails.md
index 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 t
allowlists the browsentic tools to stop being asked — so a caller with nobody watching does not get
the 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 containment
Everything above governs what the model may do **to a page**. This governs what it may do **to the
diff --git a/docs/internals/transport.md b/docs/internals/transport.md
index 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 socket
with an explicit reason instead of letting two incompatible frame vocabularies talk past each other.
---