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: browsers pair with Browsentic Bridge by themselves; pairing modes, revoke that sticks, the code as the fallback, grants and refusal codes, where hosts are registered, and what each connection message means
Shahriar92b852d70c2d
diff --git a/README.md b/README.mdindex 1b414ff..94b7d0d 100644--- a/README.md+++ b/README.md@@ -157,7 +157,7 @@ The desktop apps for [macOS](docs/guide/mac-app.md) and [Windows](docs/guide/win## Privacy and Security-Nothing connects until you pair, and both ends prove who they are. The agent asks before any consequential action, 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: the browser enforces that list, where no agent can reach it. The full model is in [SECURITY.md](SECURITY.md), and what it does not cover is in [Limits](docs/guide/limits.md).+Nothing connects except Browsentic's own extension, paired by itself through the browser or with a code, and both ends prove who they are. The agent asks before any consequential action, 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: the browser enforces that list, where no agent can reach it. 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/SECURITY.md b/SECURITY.mdindex 54b9ede..8194d64 100644--- a/SECURITY.md+++ b/SECURITY.md@@ -31,7 +31,9 @@ The full write-up lives in the docs and is the authority:Three of those boundaries matter enough to repeat here. **Pairing controls which browser, notwhich local process**: anything running as your user can drive an already-paired browser, so-your user account is the trust boundary. **Prompt injection is mitigated, not solved**: an+your user account is the trust boundary. Automatic pairing keeps to it: the grant comes through+the browser's native messaging host, which only Browsentic's own extension IDs can launch, and+`browsentic pairing ask` shows you every new browser first. **Prompt injection is mitigated, not solved**: anagent reading a hostile page can be influenced by it, and the design goal is to leave asuccessful injection nowhere to act or send data, not to make injection impossible. And**secret detection is a filter, not a proof**: the sanitizer is deterministic and errs towarddiff --git a/docs/guide/configuration.md b/docs/guide/configuration.mdindex 3c07d96..8c639be 100644--- a/docs/guide/configuration.md+++ b/docs/guide/configuration.md@@ -102,6 +102,12 @@ settings page shows but will not change.| `skillsDir` | `~/browsentic/skills` | Where panel uploads and generated site maps live || `extensionDir` | `~/browsentic/extension/chrome-mv3` | Where `browsentic setup --unpacked` writes the unpacked extension. `--dir` writes it for you, and `update` reads it back so it refreshes the copy the browser actually loaded. If you change it by hand, load the new folder in the browser again, because the extension ID follows the path |+## Pairing++| Key | Default | What it does |+| --- | --- | --- |+| `pairing.mode` | `auto` | How a browser pairs through the native host: `auto` by itself, `ask` once you allow it in the app or with `browsentic approve`, `code` only with a typed code. A value that is none of these pairs only by code. `browsentic pairing` and the apps' Settings write it; the extension shows it but cannot change it. See [Pairing](pair.md#2-choose-how-browsers-pair) |+## Android| Key | Default | Notes |diff --git a/docs/guide/install.md b/docs/guide/install.mdindex b794b7e..2477b47 100644--- a/docs/guide/install.md+++ b/docs/guide/install.md@@ -1,13 +1,13 @@# InstallOne line installs Browsentic Bridge on your computer, then walks you through adding the extension-from your browser's store and pairing the two. Browsentic is your browser's superpower, free and-open source, with no API key, no account and no cloud service of its own.+from your browser's store. The two connect by themselves. Browsentic is your browser's superpower,+free and open source, with no API key, no account and no cloud service of its own.The Mac app, the Windows app or `npx browsentic@latest setup` installs Browsentic Bridge (the partthat runs on your computer), asks which browser you use and opens the extension's store page in it.-Press **Add**, then enter the code it shows. The side panel runs on an agent CLI you are signed in-to, such as Claude Code or Codex.+Press **Add**, and the extension connects to the Bridge by itself. The side panel runs on an agent+CLI you are signed in to, such as Claude Code or Codex.The extension is on the[Chrome Web Store](https://chromewebstore.google.com/detail/browsentic/npmocgldfflonjjmdadmdefpnfagnjmp)@@ -107,15 +107,21 @@ Setup, or the app's button for that browser, opens Browsentic's store page in itPin Browsentic to the toolbar from the puzzle-piece menu, so the side panel is one click away. Itupdates itself from its store from then on.-If you added it from the store before running setup, pick the same browser in setup and enter the-code it shows.+If you added it from the store before installing the Bridge, the two connect as soon as the Bridge+is in place: the extension's welcome page shows it happen.## 3. Pair them, once-Click Browsentic in the toolbar to open the side panel, press **Set up the link**, enter the code the-app or `setup` shows, and press **Connect**. The code works once and lives for ten minutes;-`browsentic pair`, or **Get a pairing code** in the app, issues another. The browser keeps the-pairing, so you do this once. [Pairing](pair.md) has the detail.+There is usually nothing to do: the extension pairs with the Bridge by itself, and the browser+keeps the pairing. If you set pairing to ask you first, allow the browser in the app or with+`browsentic approve`.++If the extension asks for a code (an extension from before automatic pairing, a browser the Bridge+cannot register with, or pairing set to `code`), click Browsentic in the toolbar to open the side+panel, press **Set up the link**, then **Pair with a code instead**, enter the code the app or+`setup` shows, and press **Connect**. The code works once and lives for ten minutes;+`browsentic pair`, or **Get a pairing code** in the app, issues another. [Pairing](pair.md) has the+detail.---diff --git a/docs/guide/limits.md b/docs/guide/limits.mdindex 04eb8bb..506e045 100644--- a/docs/guide/limits.md+++ b/docs/guide/limits.md@@ -36,6 +36,12 @@ Pairing binds a browser. It does not authenticate local programs: anything runniread `~/.browsentic/daemon.json` and drive an already-paired browser through the control port.**Browsentic assumes your user account is the trust boundary.**+Automatic pairing keeps to the same boundary. Its grant comes through the browser's native messaging+host, which only Browsentic's own extension IDs can launch, in a browser running as you. Someone at+your keyboard who loads a copy of the extension claiming that ID (Developer mode in Chromium, a+temporary add-on in Firefox) is paired by itself in `auto` mode; `browsentic pairing ask` shows you+each new browser first, and `browsentic pairing code` turns automatic pairing off.+## Prompt injection is a real riskAn agent reading a hostile page can follow instructions embedded in that page. No prompt makes adiff --git a/docs/guide/pair.md b/docs/guide/pair.mdindex 4914349..123a423 100644--- a/docs/guide/pair.md+++ b/docs/guide/pair.md@@ -1,16 +1,55 @@# Pair your browser-Pairing connects the extension in one browser to Browsentic Bridge with a single-use code, once per-browser. This page covers getting another code, checking the connection, what pairing protects and-managing several paired browsers.+Pairing connects the extension in one browser to Browsentic Bridge, once per browser. With the+Bridge on your computer, the extension pairs by itself: no code to copy. This page covers how that+works, how to make it ask you first or turn it off, how to pair with a code, what pairing protects+and managing several paired browsers.-It assumes you have [added the extension and installed the Bridge](install.md). `browsentic setup`-and the apps already show a code during install; use this page when you need another one, or to-pair a second browser.+It assumes you have [added the extension and installed the Bridge](install.md).----## 1. Redeem a pairing code+## 1. It connects by itself++Install the extension and Browsentic Bridge, in either order. The extension finds the Bridge through+the browser's native messaging host, which `setup` and the apps register, and the two connect. The+extension tries when it is installed, when the browser starts, when you open the side panel, and+every minute or so while it is not paired, more slowly when there is nothing to find.++The Bridge then issues a long-lived session key that survives browser and Bridge restarts and lasts+until you revoke it. Updating either side does not need a new pairing.++An extension from before automatic pairing, or a Bridge from before it, still pairs with a code+(section 3).++## 2. Choose how browsers pair++```sh+browsentic pairing # show how browsers pair now+browsentic pairing auto # by themselves (the default)+browsentic pairing ask # once you allow each one+browsentic pairing code # only with a code+```++The apps' Settings tab has the same three choices. The extension shows the setting but cannot+change it, because the browser is what the setting guards.++**Ask** shows each new browser to you before it connects:++- **With the Mac or Windows app,** a notification and a sheet in the app say which browser asks:+ its name, where its extension came from and its version. Press **Allow**, and give it a name if+ you like ("Work Chrome"). If the app is closed, the Bridge starts it in the background.+- **Without an app,** run `browsentic approve` (or `browsentic approve --watch` to be asked about+ each one as it comes), or answer the prompt `browsentic setup` shows while it waits.+- `browsentic requests` lists the browsers waiting, and `browsentic deny <id>` turns one down.++An allowed browser pairs by itself from then on. A denied one stays out until someone presses+**Reconnect** in that browser and you allow it.++**Code** pairs nothing by itself, and is also the switch to reach for if you ever want automatic+pairing off at once.++## 3. Pair with a code```shbrowsentic pair@@ -32,38 +71,41 @@ This starts the Bridge if it is not already running and prints a code:```Click Browsentic in the toolbar to open the side panel, then the status pill (or **Set up the link**-in the empty chat), enter the code and press **Connect**. In the apps, **Get a pairing code** on the-Overview tab does the same. Up to three codes are live at once, so a code the app shows keeps-working while a terminal mints another.+in the empty chat), press **Pair with a code instead**, enter the code and press **Connect**. In the+apps, **Get a pairing code** does the same. Up to three codes are live at once, so a code the app+shows keeps working while a terminal mints another.-The Bridge then issues a long-lived session key that survives browser and Bridge restarts and lasts-until you revoke it. Updating either side does not need a new pairing.+A code always works, whatever `pairing` is set to: use it for a browser the Bridge cannot register+with (section 6), a managed browser whose policy blocks native messaging, or an extension from+before automatic pairing.-## 2. Verify+## 4. Verify```shbrowsentic status``````-bridge: running on 127.0.0.1:8765 (pid 41207, v0.8.0)+bridge: running on 127.0.0.1:8765 (pid 41207, v0.9.0)wake-up: Chrome, Brave can start the Bridgeagent: Claude Code — 2.1.0 (Claude Code)browsers:- ● Google Chrome v0.8.0 Chrome Web Store connected- ○ Brave v0.8.0 unpacked not connected+ ● Google Chrome v0.9.0 Chrome Web Store connected+ ○ Brave v0.9.0 Chrome Web Store not connectedtools: in sync+pairing: automatic: a browser with Browsentic connects by itself```-What each line means:-| Line | What it means || --- | --- || `bridge` | The local process is up, on one of ports 8765–8767 |-| `wake-up` | Which browsers can start the Bridge when it is down |+| `wake-up` | Which browsers can start the Bridge, and pair, when it is down || `agent` | The CLI the side panel runs on, and whether it is ready || `browsers` | One row per paired browser: its extension version, where the extension came from, and whether it is connected right now. An unpacked copy a build behind the folder on disk says to press ↻; a store copy updates itself. Two copies answering in one browser are flagged || `tools` | `in sync` means both halves were built from the same action registry. When the extension is a version ahead or behind, the tools come from the extension, which is fine |+| `pairing` | How a new browser pairs (section 2) |++`browsentic sessions` also says how each browser paired: by itself, allowed, or with a code.---@@ -71,14 +113,21 @@ What each line means:Any web page can open a WebSocket to loopback, so the Bridge classifies every connection by itshandshake `Origin`, which browsers set themselves and page JavaScript cannot forge. A web page is-refused outright. An extension origin must then prove it holds a pairing code or a session key,-and the Bridge proves itself back, so another local process cannot squat the port and pose as your-Bridge. Neither secret ever crosses the wire.--The browser can also start the Bridge when it is down, through a native messaging host that setup-registers with each browser. Only Browsentic's own extensions may launch it: the Chrome Web Store-and Edge Add-ons copies by their IDs, the unpacked folder, and the signed Firefox add-on. It starts-the Bridge and nothing more; it pairs nothing.+refused outright. An extension origin must then prove it holds a pairing code, a one-time grant or a+session key, and the Bridge proves itself back, so another local process cannot squat the port and+pose as your Bridge. No secret ever crosses the socket.++Automatic pairing asks for its grant through the browser's native messaging host, which the browser+launches only for Browsentic's own extensions: the Chrome Web Store and Edge Add-ons copies by their+IDs, the unpacked folder, and the signed Firefox add-on, in a browser running as you. Web pages+cannot reach it. A grant works once, for two minutes, for that one browser profile and the extension+origin the browser vouched for, and a grant handed out is taken back the moment the setting changes+to code or the browser is revoked.++What that leaves: someone at your keyboard who loads a copy of the extension that claims+Browsentic's ID (Developer mode in Chromium, a temporary add-on in Firefox) is paired by itself in+`auto` mode. In `ask` mode you see it and can deny it. A program running as you could always read+the Bridge's control token anyway.What pairing does **not** do is authenticate local programs. Anything running as your user can read`~/.browsentic/daemon.json` and drive an already-paired browser. Browsentic treats your user account@@ -90,15 +139,22 @@ for the mechanism, [internals/transport.md](../internals/transport.md).## Managing pairings```sh-browsentic sessions # which browsers are paired-browsentic revoke # unpair every browser-browsentic revoke <id> # unpair one, by the id "sessions" prints+browsentic sessions # which browsers are paired, and which are kept out+browsentic rename <id> "Work Chrome" # name one+browsentic revoke # unpair every browser+browsentic revoke <id> # unpair one, by the id "sessions" prints+browsentic approve <id> # let a revoked or denied browser back in```+Revoking a browser also keeps it from pairing again by itself, so it does not come back a minute+later. It returns when you press **Reconnect** in that browser (in `auto` mode), allow it in the app+or with `browsentic approve <id>`, or pair it with a code. **Disconnect** in the extension does the+same from the browser's side: it stays unpaired until you press **Connect** there.+Several browsers can be paired **and connected at once**: Chrome beside Brave, or two Chrome-profiles. Each pairs with its own code and keeps its own key, and the side panel in each runs on its-own. Every browser that installs from the same store, or loads the same folder, presents the same-extension origin, so a browser is known by an install id it mints on first run, never by its origin.+profiles. Each keeps its own key, and the side panel in each runs on its own. Every browser that+installs from the same store, or loads the same folder, presents the same extension origin, so a+browser is known by an install id it mints on first run, never by its origin.A newer connection supersedes an older one only when both come from the same browser profile.@@ -108,6 +164,34 @@ them, and follows you again once it has been quiet for two minutes. `browsentic_---+## 5. When it does not connect by itself++The side panel's **Connection** sheet and the welcome page say why. The usual reasons:++| It says | What to do |+| --- | --- |+| Browsentic Bridge isn't on this computer yet | Install it (the Mac or Windows app, or `npx browsentic@latest setup`). Already installed? Open the app or run `browsentic setup`, which registers this browser |+| Browsentic Bridge needs an update | `npx browsentic@latest update`, or **Update now** in the app |+| Allow this browser in the Browsentic app | `pairing` is `ask`: press **Allow** in the app, or run `browsentic approve` |+| This computer disconnected this browser | It was revoked. Press **Reconnect** |+| Automatic pairing is off on this computer | `pairing` is `code`: pair with a code, or run `browsentic pairing auto` |+| Your organization's browser policy keeps Browsentic Bridge from starting | Pair with a code |+| Browsentic Bridge is turned off | `browsentic start`, or turn it on in the app |++## 6. Browsers it registers with++`setup`, the apps and every Bridge start register the native host where each installed browser+reads it, plus Chrome's and Mozilla's locations always, since Brave, Opera and other forks read+Chrome's. On macOS, a Chromium fork no list names is found from its app's `Info.plist`.++Registered: Chrome and its Beta, Dev and Canary channels, Edge and its channels, Brave, Vivaldi,+Arc, Opera, Opera GX, Comet, Thorium, Chromium, Firefox and its channels, Zen, LibreWolf, Waterfox+and Floorp. Tor Browser is left out on purpose. A browser installed after setup is registered the+next time the Bridge starts, or within the hour while it runs. Orion's native messaging does not+work, and a Snap or Flatpak browser on Linux cannot run the host: pair those with a code.++---+## Next**[First run →](first-run.md)**: a tour of the side panel and a first instruction to try.diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.mdindex 29e3242..cf8a1a6 100644--- a/docs/guide/troubleshooting.md+++ b/docs/guide/troubleshooting.md@@ -27,7 +27,15 @@ Those three answer most questions. The Bridge's log is at `~/.browsentic/daemon.| The store copy is a version behind the Bridge | The store has not published that version yet, or the browser checked before it did. A browser allows the extension one early check every few hours | Nothing breaks meanwhile, because the two work across versions. Once the browser has the update, the side panel says so above the prompt: press **Update**. To check now, turn on Developer mode at `chrome://extensions` and press **Update** there || `browsentic status` says two copies of Browsentic answer in one browser | An unpacked copy and a store copy are both installed, and both inject into every page | Remove the unpacked copy on the browser's extensions page || Edge will not install from the Chrome Web Store | Edge blocks other stores until you allow them | Press **Allow extensions from other stores** in the bar at the top of the store page, confirm, then press **Add to Chrome**. Or install from [Edge Add-ons](https://microsoftedge.microsoft.com/addons/detail/browsentic/cbkjhkgjcpihokphhdkbahilpcjojpdc) instead |-| `browsentic setup` keeps waiting for the browser | The extension is installed but not paired yet | Click Browsentic in the toolbar and enter the code `setup` printed. Ctrl-C stops the wait without undoing anything |+| `browsentic setup` keeps waiting for the browser | The extension is installed but not paired yet: it predates automatic pairing, pairing is set to `code`, or it is waiting for you to allow it | Open the side panel: it says which. Enter the code `setup` printed, or allow the browser when `setup` asks. Ctrl-C stops the wait without undoing anything |+| The panel says **Browsentic Bridge isn't on this computer yet**, but it is | This browser has no native messaging host registered: it was installed after the Bridge ran, or it is a browser the Bridge does not know | Open the app or run `browsentic setup`, which registers it; a running Bridge also does so within the hour. Or pair with a code |+| The panel says **Allow this browser in the Browsentic app** | `pairing` is `ask` and nobody has allowed it yet | Press **Allow** in the app's sheet or notification, or run `browsentic approve`. `browsentic requests` lists who is waiting |+| The panel says **This computer disconnected this browser** | It was revoked, from the app or with `browsentic revoke`, and does not pair again by itself | Press **Reconnect**, or `browsentic approve <id>` |+| The panel says **Automatic pairing is off on this computer** | `pairing` is `code` | Pair with a code, or `browsentic pairing auto` |+| The panel says **Your organization's browser policy keeps Browsentic Bridge from starting** | A managed browser blocks Browsentic's native messaging host | Pair with a code. A policy that turns off per-user hosts altogether shows as "isn't on this computer yet" instead, so on a work computer try a code first |+| The panel says **Browsentic Bridge needs an update** | The Bridge on this computer is older than automatic pairing, or older than 0.8 and does not let store copies in | `npx browsentic@latest update`, or **Update now** in the app |+| The panel says **Browsentic Bridge was updated but the old one is still running** | Pairing is set to ask and the Bridge still running is the one from before the update | `browsentic restart`, or **Restart** in the app |+| Firefox on Windows wakes the Bridge, then it is gone again | Firefox ends everything a native host starts when the host exits | Setup registers a scheduled task (Task Scheduler, `Browsentic\Bridge`) that starts the Bridge outside Firefox; run `browsentic setup` once if it was installed before that. Starting the Bridge from the app or `browsentic start` also works || The side panel's **Connection** sheet shows `Expected {op:…}` | Stale service worker after a rebuild | At `chrome://extensions`, press ↻ on Browsentic || "That pairing code is wrong or expired" | Codes are single-use and last 10 minutes | Run `browsentic pair` for a new code. A failed attempt does not use up the outstanding code || "No Browsentic daemon is running" | Browsentic Bridge is not installed, or not running on 8765–8767 | [Install it](install.md#1-install-browsentic), open the app, or run `browsentic start`. Then check `browsentic status` and `browsentic logs` |diff --git a/docs/internals/extension.md b/docs/internals/extension.mdindex cb874fd..37df62a 100644--- a/docs/internals/extension.md+++ b/docs/internals/extension.md@@ -583,6 +583,38 @@ loaded. If that is newer, it is held the same way, and **Update** reloads the exfolder. `browsentic update` and the apps restart the Bridge before they rewrite the folder, so thewelcome often comes too early; the panel reads the manifest again whenever it opens or gets focus.+## Pairing by itself++`auto-pair.ts` pairs the extension with Browsentic Bridge through the native host, with no code.+`native-pair.ts` sends the host a `pair` op and reads the answer; the grant it hands back is redeemed+by `redeemGrant()` in `socket.ts`, through the same handshake a typed code uses, on the grant's own+port first. [Transport](transport.md#pairing-by-itself-grants) has the Bridge's half.++**When it tries.** Only while there is no usable session key: on `onInstalled` (install and update),+`onStartup`, the worker's start and the one-minute alarm, whenever a page that shows the link opens+(`useAutoPair()` sends the `autoPair` bridge op), and on **Connect** or **Reconnect**. One attempt+runs at a time, and each launches a process, so `isDue()` spaces them by what the last one found:+every minute for the first ten minutes with no Bridge, then every fifteen; hourly for a Bridge too+old or blocked by policy; ten minutes while it is held; 1, 2, 4… up to 30 minutes after failures;+never unasked once this browser was revoked or denied, or after **Disconnect**. A click always tries.+While ask mode waits on a person and a page is open, the page holds the ask open 25 s at a time,+so it connects the moment someone allows it.++**What it shows.** `DaemonState.bridge` says whether the host was found and in what shape (`ready`,+`old`, `missing`, `forbidden`, `policy`, `stopped`, `failed`, `off`), read from the browsers' own+error strings; anything else is `failed`, never a confident wrong cause. `DaemonState.pairing`+carries the mode, a wait and its approver, a block, or **Disconnect**. `PairingStatus` renders each+with its own message, and the code form one click away (leading when nothing automatic can work).++**The welcome page.** `entrypoints/welcome/` opens once, on install: the three pieces (the extension,+the Bridge, an agent), a download for this OS while the Bridge is missing, and once connected the+agent picker and **Open the side panel**. The window id is read ahead of the click, because opening+the panel needs the gesture and an `await` spends it.++**Keys.** A session key is replaced only by a new one the Bridge proved it issued. When the Bridge+says it holds no session for the key (`unauthorized.code`), the key is marked stale: `unknown` pairs+again at once, `revoked` waits for **Reconnect**.+---## Nextdiff --git a/docs/internals/state.md b/docs/internals/state.mdindex d67d5f7..d7548e6 100644--- a/docs/internals/state.md+++ b/docs/internals/state.md@@ -8,14 +8,15 @@ the browser's own storage for what never reaches disk. Nothing is kept in the re```~/.browsentic/ (mode 0700, override with BROWSENTIC_HOME)├── daemon.json 0600 lockfile: pid, port, control token, protocol + daemon version-├── auth.json 0600 outstanding pairing code, session keys per browser+├── auth.json 0600 outstanding pairing codes, session keys per browser, allowed and blocked browsers├── config.json optional, hand-written├── profile.json 0600 the settings page's Profile: your details and standing instructions├── approvals.json 0600 "always on this site" grants, one action + host per entry├── models.json 0600 each agent CLI's own model list, as last read├── schedules.json 0600 scheduled tasks and the last twenty runs of each-├── native-host/ the helper a browser launches to start the daemon+├── native-host/ the helper a browser launches to start the daemon and pair├── stopped only after `browsentic stop`: the helper leaves the daemon down+├── daemon.start.lock only while a daemon is being started: the one starter others wait for├── daemon.log run starts, routed skills, every tool call and its outcome├── skills/ hand-written skill overrides├── cli/ desktop apps only: the command, the daemon, bundled skills, the extension payload@@ -33,13 +34,13 @@ the browser's own storage for what never reaches disk. Nothing is kept in the re| File | Written by | Notes || --- | --- | --- || `daemon.json` | Each daemon at startup | The control token dies with the daemon that minted it. Read it with `browsentic token` |-| `auth.json` | Pairing | Session keys are per browser profile, keyed by its install id, and survive restarts. Cleared by `browsentic revoke` |+| `auth.json` | Pairing | Session keys are per browser profile, keyed by its install id, and survive restarts, each with how it paired (`pairedBy`) and any name given to it. `approved` lists the browsers allowed in ask mode; `blocked` the ones revoked or denied, which do not pair again by themselves (the newest 200 kept). Grants are never written here: they live in the daemon's memory for two minutes. `browsentic revoke` deletes a session and blocks it || `config.json` | You, the agent picker, and the settings page and desktop app for `theme` and `guardrails` | Re-read before every run (no restart needed) and watched, so a hand edit reaches every open settings screen. [Reference](../guide/configuration.md) || `profile.json` | The settings page's **Profile** section | Only exists while something is filled in: clearing every field deletes it. Re-read before every run and watched like `config.json`; kept apart from it so the config never holds personal details. [Reference](../guide/configuration.md#profile) || `approvals.json` | **Always on ‹host›** | One action + host per entry. Only short-circuits a `confirm` || `models.json` | The daemon, reading each agent CLI's model list | A cache: deleting it only means the lists are read again. A failed read keeps the last list that read cleanly || `schedules.json` | The Schedules tab, `browsentic tasks` | At most 25 tasks. The daemon re-reads it every minute, so an edit from the CLI lands without a restart. Transcripts stay in the extension: the last three runs of each task |-| `native-host/` | `browsentic setup` | A launcher that runs this CLI with the `PATH` setup saw. Each browser gets a manifest in its own `NativeMessagingHosts` folder (a registry key on Windows) naming the extension origins allowed to use it: both store listings always, the unpacked folder, and each paired browser. Pairing adds the new one, and the Bridge rewrites them every time it starts. `browsentic uninstall` removes both |+| `native-host/` | `browsentic setup` | A launcher that runs this CLI with the `PATH` setup saw and Node's warnings off, since a host must write nothing to stderr. Each browser gets a manifest where it reads one (a registry key on Windows) naming the extension origins allowed to use it: both store listings always, the unpacked folder, and each paired browser. Chrome's and Mozilla's locations are written whether or not those browsers are installed, because Brave, Opera and other forks read Chrome's. The Bridge rewrites them on every start and every hour, only where something changed and never half-written, and repins a launcher whose Node or CLI has gone. A Bridge whose state lives outside the home folder registers nothing. On Windows, setup also registers the `Browsentic\Bridge` scheduled task Firefox's host starts the Bridge through. `browsentic uninstall`, and the Windows app's uninstaller, remove all of it || `stopped` | `browsentic stop` and `restart` | While it exists the helper starts no daemon, so a paired browser cannot undo a stop. The next daemon to start removes it || `cli/`, `bin/`, `runtime/` | The [macOS](../guide/mac-app.md) or [Windows](../guide/windows-app.md) app | Replaced whole on every app update. `cli/.browsentic-app.json` is what makes `installKind()` answer `app`, which turns the npm self-update off || `daemon.log` | The daemon | `browsentic logs`. Local [instant commands](../guide/features/instant-commands.md) never appear here, by design |@@ -88,6 +89,12 @@ closes. Nothing about the phone reaches the Bridge's disk beyond `daemon.log` liserial, its Chrome version and each DevTools method sent, never its parameters; screencast framesare never logged or stored. See [Android phones](android.md).+**Pairing by itself** keeps three values: `browsentic/pairManual` in `storage.local` while the user+has pressed Disconnect (only Connect clears it), `browsentic/pairLast` in `storage.local` with what the+last attempt found and when, which spaces the next one, and `browsentic/staleKey` in+`storage.session` once the Bridge has said it holds no session for the stored key. The key itself+stays until a new one replaces it.+**Blocked sites** are `browsentic/blockedSites` in `storage.local`: a list of up to 500 patterns thatthe daemon never receives. Removing the extension removes it; each browser keeps its own.diff --git a/docs/internals/stores.md b/docs/internals/stores.mdindex 5ba0b6d..8caa328 100644--- a/docs/internals/stores.md+++ b/docs/internals/stores.md@@ -125,7 +125,7 @@ and reuses the same screenshots. The images (five 1280×800 screenshots, a 440×| `scripting` | Reads and acts on the pages the user asks about: finding elements, filling in fields, clicking and extracting text. || `notifications` | Tells the user when a scheduled task or a timer they set has finished, or when a task needs their approval. || `downloads` | Saves a file the user asked the agent to download, and lists what it downloaded so it can hand the file back in the conversation. |-| `nativeMessaging` | Starts Browsentic Bridge, Browsentic's own companion on the user's computer, when it is not running. It talks only to Browsentic's native host. |+| `nativeMessaging` | Starts and connects to Browsentic Bridge, Browsentic's own companion on the user's computer: it starts the Bridge when it is not running and pairs with it without a code. It talks only to Browsentic's native host, which only Browsentic's own extension IDs can launch. || `sidePanel` | The side panel is Browsentic's main interface: the user types or speaks a task there and watches each step as it happens. || `debugger` | Used where a page's own scripts would otherwise block an action: trusted clicks and key presses, working inside cross-origin frames, and pages whose Content Security Policy blocks injected scripts. It attaches only to the tab a task is working on, and Chrome shows its standard banner while attached. || `offscreen` | Hands-free mode listens for the user's voice through an offscreen document, so it keeps working after the side panel is closed. |diff --git a/docs/internals/transport.md b/docs/internals/transport.mdindex 27e5c18..a9c3370 100644--- a/docs/internals/transport.md+++ b/docs/internals/transport.md@@ -61,7 +61,8 @@ Read it with `browsentic token`.## Pairing and sessions-The extension connects to nothing until you pair it.+The extension connects to nothing until it is paired, by a code someone types or by a grant the+native host hands over (next section). Both go through the same handshake.1. `browsentic pair` asks the daemon for a code: 8 characters from an alphabet with theambiguous glyphs removed, valid **10 minutes**, single use.@@ -90,6 +91,65 @@ The extension connects to nothing until you pair it.keystream derived from the same secret, so the long-lived credential never crosses the wire inthe clear. It survives browser and daemon restarts and dies only when you `browsentic revoke`.+### Pairing by itself: grants++`answerNativeMessage()` in `native-messaging.ts` answers three ops, one message per launch:++| Op | Answer |+| --- | --- |+| `ensure` | Starts the Bridge. Byte for byte what 0.8.x answered, because shipped extensions read it |+| `hello` | The host version, its ops, `pairing.mode`, whether the Bridge is held, whether a desktop app is installed. Read from disk; never starts the Bridge |+| `pair` | A grant, a `wait`, a refusal (`off`, `revoked`, `denied`, `stopped`, `origin`, `restart`) or an error |++Anything else gets `Expected {"op":"ensure"}.`, which is how a new extension recognises a host that+predates pairing.++1. The browser launches the host only for the extension IDs its registration lists, and passes the+ caller: `chrome-extension://<id>/` from Chromium (with `--parent-window` on Windows), the add-on+ ID from Firefox. `callerOf()` reads it from anywhere in argv; a caller it cannot name gets+ `origin` and nothing else.+2. The host asks the Bridge over `/control` (`grant`). `pairing-desk.ts` answers by+ `pairing.mode`: `code` refuses, a blocked install id is refused unless the request was a click+ (`gesture`), `ask` holds a request until an approver allows it, and otherwise it mints a+ **grant**: 26 characters from the code alphabet, valid **120 s**, single use, bound to the+ install id and the caller (the exact origin for Chromium; the `moz-extension://` scheme for+ Firefox, whose socket origin is a random UUID per install). Grants live in memory only. A second+ ask hands back the same grant while more than 30 s of it remains, and never takes a slot from+ the three typed codes.+3. The extension redeems the grant with the same `pair` hello and PBKDF2 proof a typed code uses,+ dialling the grant's port first. `greet()` tries the grant held for that install id from that+ origin before the typed codes, and checks it again then: a mode switched to `code`, a revoke or a+ withdrawn approval since it was handed out takes it back.+4. The session records `pairedBy`: `auto`, `approved` or `code`.++**Ask mode.** A request is one per install id, kept in memory for 10 minutes after its last ask,+with a nonce the app checks before a `browsentic://` link may act on it. Control clients that send+`pairRequests {watch:true}` are approvers and hear `pair-requests-changed`. If no app is watching but+the app marker names one, the Bridge starts it in the background, once per request. `decide` allows+(which also lifts a block and is remembered in `auth.json`'s `approved`) or denies (a `denied`+block). A host may hold a `pair` open for up to 25 s (`waitMs`) so an open page hears the decision+at once: a pending `sendNativeMessage` keeps a Chromium service worker alive and blocks a Firefox+background page's suspension.++**Blocks.** `revoke` deletes the session and blocks the install id (`auth.json`'s `blocked`, the newest+200 kept), so the extension's next automatic attempt is refused rather than re-pairing it. A click+in that browser (in `auto` mode), `decide`, or a typed code lifts it. Agent-run connections+(`speaksForRun`) are refused `grant`, `decide`, `pairing` changes and `label`.++**A Bridge older than grants** never answers an op it does not know, so the host reads `status`+first: one without `pairing` gets a plain code from `pair` in `auto` mode, and `restart` in `ask`+mode, where nobody could be asked.++### Refusal codes++An `unauthorized` frame carries `code` beside the `reason` text, which stays as shipped:++| Code | Meaning | What the extension does |+| --- | --- | --- |+| `bad-code` | A code or grant that matched nothing | Reports it |+| `unknown` | A session key the Bridge holds no session for, and the install is not blocked: a wiped or reinstalled Bridge | Marks the key stale and pairs again through the host, keeping the old key until a new one is stored |+| `revoked` | A key for a browser this computer revoked | Marks the key stale and waits for **Reconnect** |+### Why the daemon proves itself tooThe three ports are well known and any local process can bind one first, so an extension thatdiff --git a/docs/reference/cli.md b/docs/reference/cli.mdindex 4c26506..6572ad1 100644--- a/docs/reference/cli.md+++ b/docs/reference/cli.md@@ -75,9 +75,14 @@ See [guide/install.md](../guide/install.md) and [guide/maintenance.md](../guide/| Command | Does || --- | --- |-| `browsentic pair` | Issue a one-time code to paste into the side panel (status pill → **Connection**). 8 characters, valid 10 minutes, single use |-| `browsentic sessions` | List paired browsers |-| `browsentic revoke [id]` | Unpair one browser by the id `sessions` prints, or all of them. An origin still works, and unpairs every browser presenting it |+| `browsentic pair` | Issue a one-time code to paste into the side panel (status pill → **Connection** → **Pair with a code instead**). 8 characters, valid 10 minutes, single use |+| `browsentic pairing [auto\|ask\|code]` | Show or set how a browser pairs through the native host: by itself (`auto`, the default), once you allow it (`ask`), or only with a code (`code`) |+| `browsentic requests` | The browsers waiting for you to allow them, in `ask` mode. `--json` for scripts |+| `browsentic approve [id]` | Allow a waiting browser (the only one, when there is one), or let a revoked or denied one back in by its id. `--name <name>` names it; `--watch` asks about each browser as it asks, until Ctrl-C |+| `browsentic deny <id>` | Turn a waiting browser down. It stays out until someone presses **Reconnect** in it and you allow it |+| `browsentic sessions` | List paired browsers, how each paired, and the ones kept out |+| `browsentic rename <id> <name>` | Name a paired browser, as the app's list shows it. An empty name clears it |+| `browsentic revoke [id]` | Unpair one browser by the id `sessions` prints, or all of them, and keep them from pairing again by themselves. An origin still works, and unpairs every browser presenting it |See [guide/pair.md](../guide/pair.md).