@sema-agent/connector-browser 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this package are documented here. Released sections are
 frozen: once a version is published its section is never edited again; new text
 goes into the next version's section.
 
+## 0.1.2 (2026-10-21)
+
+### Documentation
+
+- The connector's document ships inside the package as `README.md`, a byte copy of
+  the repository's `docs/CONNECTORS/<name>.md` made by the build (CN-056): a person
+  who installed the package reads its setup, what runs, the recommended policy and
+  the known limits without the repository.
+- The recommended policy names four tools to leave out (`browser_run_code_unsafe`,
+  `browser_evaluate`, `browser_network_request`, `browser_network_requests`) and
+  `browser_file_upload` as a fifth a deployment may add back; the example list holds
+  20 names, 21 with it.
+
 ## 0.1.1 (2026-10-16)
 
 ### Documentation

package/README.md

@@ -0,0 +1,229 @@
+# Browser connector
+
+`@sema-agent/connector-browser` (CN-027) gives the engine a web browser. It runs the
+[Playwright MCP server](https://github.com/microsoft/playwright-mcp) (`@playwright/mcp`) unmodified behind the
+`sema-connector` launcher, driving a pinned Chrome for Testing, at the versions and sha256 values its `binaries.lock.json`
+pins. The launcher's stages (scope, normalize, status, trace, the withholding of secret values) apply to it as to every
+connector; see [`ARCHITECTURE.md`](../ARCHITECTURE.md). Its bin is `sema-connector-browser`; its subcommands are the shared
+CLI kit's (CN-039) around the shared install of a pinned upstream program (CN-027) and this package's `auth`, and read the
+configuration directory from `CONFIG_LOCAL_DIR` like every connector's
+([`INTEGRATION-SERVER.md`](../INTEGRATION-SERVER.md)).
+
+The browser is headless and runs in a fresh, in-memory profile at every start; what it knows of a login is the login
+state `auth` stored (see "The login state"). Chrome for Testing is pinned for `darwin-arm64` and `linux-x64` only.
+
+## Setting it up
+
+```sh
+export CONFIG_LOCAL_DIR=/absolute/path/to/the/engine/configuration
+sema-connector-browser install
+echo '{}' | sema-connector-browser auth          # a clean profile
+sema-connector-browser mount
+sema-connector-browser status
+```
+
+On Linux the connector keeps Chromium's own sandbox on (`--sandbox`, never `--no-sandbox`), which needs user
+namespaces: in a container that does not allow them (Docker's default seccomp profile, for one) the first
+`browser_navigate` answers `Chromium sandboxing failed!` and nothing is browsed. Run the connector on a host or in a
+container that allows user namespaces (KL-18 in the repository's `docs/KNOWN-LIMITS.md`); the connector never turns
+the sandbox off.
+
+Then restart the engine. To start from a login instead of a clean profile, save a Playwright storage state (for example
+with Playwright's `context.storageState({ path })` after logging in) to a file only you can read, and give `auth` its path:
+`echo '{"storageStateFile": "/absolute/path/state.json"}' | sema-connector-browser auth`. Delete the file afterwards; the
+state is a secret (it holds the session cookies).
+
+## The pinned build
+
+`binaries.lock.json` is the one place that names the build, in the shape "Pinned upstream programs" in
+[`ARCHITECTURE.md`](../ARCHITECTURE.md) describes: the key `playwright-mcp`, version 0.0.83, and five archives.
+
+| Archive | Platform | Source | Unpacked as |
+|---|---|---|---|
+| `playwright-mcp-0.0.83.tgz` | `*` | `https://registry.npmjs.org/@playwright/mcp/-/mcp-{version}.tgz` | `node_modules/@playwright/mcp` |
+| `playwright-1.64.0-alpha-1790635538000.tgz` | `*` | `https://registry.npmjs.org/playwright/-/{file}` | `node_modules/playwright` |
+| `playwright-core-1.64.0-alpha-1790635538000.tgz` | `*` | `https://registry.npmjs.org/playwright-core/-/{file}` | `node_modules/playwright-core` |
+| `chrome-mac-arm64.zip` | `darwin-arm64` | `https://cdn.playwright.dev/builds/cft/155.0.8059.12/mac-arm64/{file}` | `chrome` |
+| `chrome-linux64.zip` | `linux-x64` | `https://cdn.playwright.dev/builds/cft/155.0.8059.12/linux64/{file}` | `chrome` |
+
+The three npm tarballs are the whole run-time closure of `@playwright/mcp` 0.0.83 (its lock file lists no other
+package), each pinned with the sha256 of the tarball whose `sha512` integrity the registry gives. Chrome for Testing
+155.0.8059.12 is the build that `playwright-core` 1.64.0-alpha-1790635538000 names (Playwright's `chromium` 1247), fetched
+from the host Playwright itself downloads it from. The program is the Node.js script
+`node_modules/@playwright/mcp/cli.js` (`{"node": ...}`): it runs on the Node.js that runs the connector, and Node.js
+finds `playwright` and `playwright-core` next to it. npm is never run.
+
+## install
+
+`install` is the shared install of a pinned upstream program (see "Pinned upstream programs" in
+[`ARCHITECTURE.md`](../ARCHITECTURE.md)): it fetches the four archives of this platform, compares each with its sha256
+and checks what it gives before anything is unpacked, then unpacks each below
+`<configuration directory>/connectors/browser/bin/` (0700) and keeps the archives there. About 580 MB on `darwin-arm64`.
+When that directory already holds the pinned build, `install` changes nothing. On a platform the lock does not pin it
+refuses (`binaries.lock.json pins no playwright-mcp build for <platform>`).
+
+## auth
+
+`auth` reads exactly one line from standard input (never from an argument), a JSON object with at most one string member:
+
+```json
+{}
+{"storageStateFile": "<absolute path>"}
+```
+
+- `{}` stores a clean profile, `{"cookies":[],"origins":[]}`. Empty input is refused rather than read as `{}`: a pipe
+  whose producer failed must not replace a stored login with an empty one.
+- `storageStateFile` names a Playwright storage state file by its absolute path: at most 4 MiB of UTF-8 JSON holding one
+  object with exactly the keys `cookies` and `origins`, each a list. Its text is stored as it is.
+- Any other key, a key given twice, a value that is not a string, or a file outside the rule is refused, and a refusal
+  never repeats what was read.
+
+The state is stored through the secrets backend as the handle `BROWSER_STORAGE_STATE`: a 0600 file in
+`<configuration directory>/connectors/browser/` (0700), a secret (no metadata). The write holds the lock of the
+connector's directory as for every connector (see "Secrets" in [`ARCHITECTURE.md`](../ARCHITECTURE.md)): a connector
+started while `auth` runs gets the old state or the new one, and an `auth` that fails leaves the old one.
+
+## mount and status
+
+`mount` writes the connector's standalone catalog entry through the shared `mount` function, and `status` prints the
+status the launcher serves, as for every connector. Before `auth` there is no handle, so the launcher does not start the
+connector and answers itself (see "Parked session" in [`ARCHITECTURE.md`](../ARCHITECTURE.md)): `status` prints
+`{"state":"unauthorized","tools":[]}`. After `auth` (a clean profile included) the status is `authorized` and lists the
+25 tools of playwright-mcp; reading them starts playwright-mcp but not the browser, which starts at the first tool that
+needs a page.
+
+## What runs
+
+With no arguments, `sema-connector-browser` is the connector process the launcher starts. It refuses to start (exit 1,
+with a line on stderr naming what to do) on the shared start check ("Pinned upstream programs": without `CONNECTOR_DIR`,
+without the `BROWSER_STORAGE_STATE` handle, when its per-launch copy is not a regular file in `CONNECTOR_DIR`, when `bin/`
+does not hold the pinned build), when the stored state breaks the rule of "auth", and when Chrome for Testing is not in
+`bin/chrome`. Otherwise it makes the launch's output directory (see "The output directory"), makes it the working
+directory, and starts `node_modules/@playwright/mcp/cli.js` on its own Node.js as its child on the same standard input,
+output and error, so every MCP message passes between the launcher and playwright-mcp untouched; it ends as playwright-mcp ends, with its exit code or by the signal that ended it, and passes its stop
+signals on. playwright-mcp closes the browser when its input ends or it gets `SIGTERM` (measured well under a second,
+inside the launcher's teardown steps); killed with `SIGKILL` before that, it leaves Chromium running (KL-22).
+
+playwright-mcp gets the arguments of "Security baseline" and the environment the launcher gave the connector without
+`CONNECTOR_DIR`, `BROWSER_STORAGE_STATE_FILE` and every `PLAYWRIGHT_MCP_*` variable (the variable twins of its options),
+so its options are those arguments whoever starts the connector.
+
+## Security baseline
+
+The arguments are one table in `src/upstream.ts`; none comes from the environment, standard input or a file.
+
+| Argument | Why |
+|---|---|
+| `--headless` | no window; the browser is driven only through the tools. |
+| `--isolated` | the profile lives in memory and is gone when the browser closes; nothing persists between starts but the stored login state. |
+| `--browser chromium` | Chrome for Testing, the pinned build. |
+| `--sandbox` | the Chromium sandbox on: playwright-mcp leaves it off on Linux for Chrome for Testing unless asked (KL-18). |
+| `--block-service-workers` | a page cannot install a service worker that outlives it or intercepts its requests. |
+| `--no-webmcp` | tools a page registers are not offered to the engine: a page cannot add tools. |
+| `--timeout-navigation 60000` | the navigation timeout, stated rather than defaulted. |
+| `--output-max-size 67108864` | the output directory holds at most 64 MiB; older files are evicted. |
+| `--executable-path <bin>/chrome/...` | the pinned Chrome for Testing in the bin directory; playwright-mcp never looks for or downloads a browser. |
+| `--output-dir <launch directory>/out` | screenshots, snapshots and other files land in the launch's own directory and go with it. |
+| `--storage-state <per-launch copy>` | the login state, read when the browser context is created. |
+
+Never given: `--no-sandbox`, `--caps` (none of the opt-in capabilities `vision`, `pdf`, `devtools`, `config`, `network`,
+`storage` is on), `--user-data-dir`, `--save-session`, `--secrets`, `--allow-unrestricted-file-access`, `--proxy-server`,
+`--port` and `--host` (MCP runs on standard input and output only), `--init-script`, `--init-page`, `--config`,
+`--extension`, `--cdp-endpoint`, `--allowed-origins` and `--blocked-origins` (playwright-mcp itself says they are not a
+security boundary and do not apply to redirects; the connector does not offer them as one).
+
+## The login state
+
+The state is a secret handle: the launcher reads it before the connector starts and hands the connector a per-launch copy
+(0600, inside the connector's directory, removed when the launcher ends), whose path the connector gives playwright-mcp
+with `--storage-state`. playwright-mcp loads its cookies and local storage into each new browser context. The launcher
+withholds the state's text as a whole from everything it forwards; a cookie value a page's script can read (one not
+marked `HttpOnly`) reaches the engine like any page content, through `browser_evaluate` and the other tools that read the
+page. A reply that carries the stored state's text as a whole, the clean profile's `{"cookies":[],"origins":[]}`
+included, is withheld like any secret value (answered with `connector.internal`).
+
+Logins made during a session are not written back: the profile is in memory (`--isolated`), so they end with the browser
+(KL-15). To keep a login, store a new state with `auth`.
+
+## The output directory
+
+Every launch has an output directory of its own: `out` (0700) in the launch's directory, the 0700 directory the launcher
+makes inside the connector's directory for the per-launch copy of the login state and removes when the launch ends. It
+holds what playwright-mcp writes (screenshots, page snapshots, console logs, downloads, at most 64 MiB) and goes with the
+launch, so nothing a session wrote outlives it, and two launches at once (two engine sessions, or `status` while a
+session runs) never touch each other's files. It is also playwright-mcp's working directory, and playwright-mcp confines
+the files its tools read and write (`browser_file_upload`, a screenshot's file name, `browser_run_code_unsafe`'s
+`filename`) to its output directory and its workspace, which is the working directory unless the MCP client names a root
+(then its first root). `file:` URLs are not opened.
+
+## Tools
+
+The connector offers every tool playwright-mcp lists; which of them a caller may use is the launcher's scope stage, and
+standalone grants `tool:*` unless the configuration directory carries a local per-tool policy (CN-054, `ARCHITECTURE.md`,
+"Stages on the launcher hop"). The 25 tools, with what each can reach:
+
+| Tool | Reach |
+|---|---|
+| `browser_run_code_unsafe` | **Runs arbitrary JavaScript in the playwright-mcp process** (playwright-mcp calls it RCE-equivalent): it can read and write every file the user can, the tokens of the other connectors in the configuration directory included, start processes and connect anywhere. |
+| `browser_evaluate` | Runs JavaScript in the page, with the page's access: its DOM, storage and script-readable cookies, requests as the page. |
+| `browser_network_requests`, `browser_network_request` | The page's requests and responses, headers and bodies included (session cookies and authorization headers of a logged-in site). |
+| `browser_file_upload`, `browser_drop` | Give files to a page: files in the output directory or the workspace (see "The output directory"). |
+| `browser_navigate`, `browser_navigate_back`, `browser_tabs` | Open any `http` or `https` URL, as the logged-in user where the state has a login. |
+| `browser_click`, `browser_type`, `browser_press_key`, `browser_fill_form`, `browser_select_option`, `browser_hover`, `browser_drag`, `browser_handle_dialog` | Act on the page as the user (submit forms, confirm dialogs, buy, post, delete). |
+| `browser_snapshot`, `browser_find`, `browser_take_screenshot`, `browser_console_messages` | Read the page (its text, its look, its console); snapshots and screenshots are also written to the output directory. |
+| `browser_resize`, `browser_emulate_media`, `browser_wait_for`, `browser_close` | Change the viewport or media features, wait, close the browser. |
+
+### A recommended policy
+
+Mounting this connector grants every tool above by default (`tool:*`): nothing in this package writes a policy for
+it. An operator who wants to keep the reach of `browser_run_code_unsafe`, `browser_evaluate`,
+`browser_network_request` and `browser_network_requests` off, while still using the browser for everything else, writes `connectors/browser/tools.json` in the configuration directory by hand
+(`ARCHITECTURE.md`, "Stages on the launcher hop"; no CLI subcommand writes this file):
+
+```json
+{
+  "allow": [
+    "browser_navigate", "browser_navigate_back", "browser_tabs",
+    "browser_click", "browser_type", "browser_press_key", "browser_fill_form", "browser_select_option",
+    "browser_hover", "browser_drag", "browser_handle_dialog",
+    "browser_snapshot", "browser_find", "browser_take_screenshot", "browser_console_messages",
+    "browser_resize", "browser_emulate_media", "browser_wait_for", "browser_close", "browser_drop"
+  ]
+}
+```
+
+The example leaves a fifth tool out as well, `browser_file_upload`: a deployment that needs it adds it back (it
+reaches only the output directory and the workspace, not arbitrary files), so the list above holds 20 names and a
+deployment that keeps `browser_file_upload` lists 21. A tool left out of `allow` fails
+`tools/call` with `connector.forbidden_scope` and is absent from `tools/list` and the status resource's `tools`;
+nothing about the connector itself changes.
+
+## Outbound connections
+
+The browser connects to whatever the engine asks it to open: that is what it is for. The standalone form has no egress
+proxy (M3), and the connector gives playwright-mcp none. The negative-control gate (`run-browser-negctl-test`) checks
+what else connects: playwright-mcp itself connects nowhere (every Node.js process runs under the gate's egress probe and,
+on macOS, a sandbox that refuses every connection but the gate's own loopback page). Chrome for Testing 155 does contact
+Google on its own when it starts, although Playwright passes switches meant to keep it quiet: the gate's proxied run
+names `accounts.google.com`, `update.googleapis.com`, `www.google.com` and `android.clients.google.com`, and Chromium
+also connects a UDP socket to `[2001:4860:4860::8888]:443` (KL-19); the gate fails on a host outside google.com and
+googleapis.com. The browser follows the system's proxy settings.
+
+playwright-mcp also publishes the running browser for other Playwright tools of the same user: a socket under
+`/tmp/pw-<hash>/browser/` and an entry in Playwright's registry directory (`~/Library/Caches/ms-playwright/b` on macOS,
+`~/.cache/ms-playwright/b` on Linux), removed when the browser closes. A process of the same user can attach to the
+browser there (KL-21).
+
+## Known limits
+
+- **Logins made in a session are not kept** (KL-15).
+- **No egress policy in the standalone form** (KL-17).
+- **The Chromium sandbox needs user namespaces on Linux** (KL-18): in a container without them Chromium does not start;
+  the connector never turns the sandbox off.
+- **Chrome for Testing contacts Google on its own** (KL-19).
+- **Two platforms**: `darwin-arm64` and `linux-x64` (KL-20).
+- **Other processes of the user can attach to the running browser** (KL-21).
+- **Chromium outlives a playwright-mcp killed with `SIGKILL`** before it closed the browser (KL-22).
+- **Check, then start:** as for every pinned upstream program (see "Pinned upstream programs" in
+  [`ARCHITECTURE.md`](../ARCHITECTURE.md)): at each start the trees are compared with their archives by their files'
+  names, kinds, sizes, modes and link targets, the program by its content.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/connector-browser",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Browser connector: runs the pinned Playwright MCP server and a pinned Chrome for Testing behind the sema-connector launcher, in an isolated, headless session whose login state is a secret handle.",
   "license": "Apache-2.0",
   "type": "module",
@@ -15,7 +15,8 @@
     "dist",
     "CHANGELOG.md",
     "binaries.lock.json",
-    "NOTICE"
+    "NOTICE",
+    "README.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json"