barebrowse 0.26.0 → 0.27.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +20 -0
- package/README.md +11 -1
- package/barebrowse.context.md +4 -3
- package/cli.js +20 -2
- package/commands/barebrowse/SKILL.md +1 -0
- package/commands/barebrowse.md +1 -0
- package/mcp-server.js +71 -5
- package/package.json +1 -1
- package/src/blocklist-firefox.js +12 -4
- package/src/daemon.js +2 -0
- package/src/firefox-page.js +10 -2
- package/src/index.js +47 -11
- package/src/navigation.js +12 -0
- package/src/site-lock.js +184 -0
- package/types/blocklist-firefox.d.ts +2 -1
- package/types/firefox-page.d.ts +12 -0
- package/types/index.d.ts +4 -0
- package/types/navigation.d.ts +12 -0
- package/types/site-lock.d.ts +70 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,25 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [0.27.0] - 2026-10-30
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- **Site lock (`allowHosts`).** `connect({ allowHosts: ['a.com', '*.b.org'] })`
|
|
8
|
+
and `browse(url, { allowHosts })` confine top-level navigation to a host list
|
|
9
|
+
on both engines: `goto()`, redirect hops, clicked links, JS jumps, popups and
|
|
10
|
+
new tabs. A blocked `goto()` rejects with `err.code === 'NAV_BLOCKED'` and
|
|
11
|
+
`err.host`; the page stays where it was. A blocked in-page jump shows as
|
|
12
|
+
`[blocked navigation to <host>]` on the next `snapshot()`. Not locked:
|
|
13
|
+
subresources, iframes, WebSocket. Attach mode (`port`) throws. CLI:
|
|
14
|
+
`--allow-hosts=a.com,*.b.org` on `open` and `browse`.
|
|
15
|
+
- **MCP tool annotations and access tiers.** Every tool has `readOnlyHint`,
|
|
16
|
+
`destructiveHint`, `openWorldHint` (and `idempotentHint` where it applies).
|
|
17
|
+
`BAREBROWSE_TIER=r|rw|rwx` (default `rwx`) hides tools above the tier, and a
|
|
18
|
+
hidden tool answers `Unknown tool`. `BAREBROWSE_ALLOW=a.com,*.b.org` sets the
|
|
19
|
+
site lock. An invalid value of either stops the server at start. The
|
|
20
|
+
`capabilities` tool and the server instructions report `tier` and
|
|
21
|
+
`allowHosts`.
|
|
22
|
+
|
|
3
23
|
## [0.26.0] - 2026-10-27
|
|
4
24
|
|
|
5
25
|
### Added
|
package/README.md
CHANGED
|
@@ -96,7 +96,7 @@ Or manually add to your config (`claude_desktop_config.json`, `.cursor/mcp.json`
|
|
|
96
96
|
}
|
|
97
97
|
```
|
|
98
98
|
|
|
99
|
-
MCP tools: `browse`, `goto`, `snapshot`, `readable`, `click`, `type`, `press`, `scroll`, `hover`, `select`, `back`, `forward`, `reload`, `drag`, `upload`, `pdf`, `screenshot`, `wait_for`, `tabs`, `capabilities` (reports the active engine — chromium or firefox — and what the session can do, plus a `cookies` field naming the cookies injected on the last goto — names only, never values; no side effects), `switch_engine` (swap chromium/firefox without restarting; page, tabs and refs reset, so call `goto` after). Plus `assess` (privacy scan) if [wearehere](https://github.com/hamr0/wearehere) is installed. Plus opt-in `eval` (`BAREBROWSE_MCP_EVAL=1`) — runs JS in the authenticated session, off by default because it can read cookies/localStorage. Session runs in hybrid mode with automatic cookie injection. Per-tool timeouts (goto/reload/wait_for 60s, back/forward 30s, interactive ops 15s, pdf/screenshot/upload 45s) with auto-retry on transient failures (idempotent only — mutating tools fail loudly to avoid double-submits).
|
|
99
|
+
MCP tools: `browse`, `goto`, `snapshot`, `readable`, `click`, `type`, `press`, `scroll`, `hover`, `select`, `back`, `forward`, `reload`, `drag`, `upload`, `pdf`, `screenshot`, `wait_for`, `tabs`, `capabilities` (reports the active engine — chromium or firefox — and what the session can do, plus a `cookies` field naming the cookies injected on the last goto — names only, never values; no side effects), `switch_engine` (swap chromium/firefox without restarting; page, tabs and refs reset, so call `goto` after). Plus `assess` (privacy scan) if [wearehere](https://github.com/hamr0/wearehere) is installed. Plus opt-in `eval` (`BAREBROWSE_MCP_EVAL=1`) — runs JS in the authenticated session, off by default because it can read cookies/localStorage. `BAREBROWSE_TIER` and `BAREBROWSE_ALLOW` restrict the tool set and the reachable hosts (see Site lock and MCP access tiers below). Session runs in hybrid mode with automatic cookie injection. Per-tool timeouts (goto/reload/wait_for 60s, back/forward 30s, interactive ops 15s, pdf/screenshot/upload 45s) with auto-retry on transient failures (idempotent only — mutating tools fail loudly to avoid double-submits).
|
|
100
100
|
|
|
101
101
|
**Idle release.** An MCP server can outlive its conversation, so it closes its browser after `BAREBROWSE_IDLE_MINUTES` (default `15`, `0` = never, blank/invalid = default, fractional allowed, capped at ~24.8 days) with no tool call in flight. The next call opens a fresh browser (a new job, not a resume — a page left open, e.g. a solved captcha in the headed window, is gone). A transient browser error also closes the broken browser rather than orphaning it; an ordinary `wait_for` timeout does not reset the page.
|
|
102
102
|
|
|
@@ -211,8 +211,18 @@ barebrowse hands an autonomous — and therefore prompt-injectable — agent an
|
|
|
211
211
|
- **CLI daemon authenticated** with a per-session token (loopback alone isn't an authorization boundary); snapshots and saved state are written owner-only (`0600`).
|
|
212
212
|
- **Opt-in hardening** for stricter deployments: `blockPrivateNetwork` (SSRF guard for loopback/RFC-1918/cloud-metadata) and `uploadDir` (confine `upload()` to one directory). Both available on the library, MCP, bareagent, and CLI (`--block-private-network`, `--upload-dir`).
|
|
213
213
|
|
|
214
|
+
- **Site lock** (`allowHosts`): confine top-level navigation to a list of hosts. See below.
|
|
215
|
+
|
|
214
216
|
See `barebrowse.context.md` and the PRD's "Security Model & Safe Defaults" for the full rationale.
|
|
215
217
|
|
|
218
|
+
### Site lock and MCP access tiers
|
|
219
|
+
|
|
220
|
+
`allowHosts: ['example.com', '*.docs.example.org']` on `connect()` and `browse()` (CLI `--allow-hosts=a.com,*.b.org` on `open` and `browse`; MCP `BAREBROWSE_ALLOW=a.com,*.b.org`) locks the top frame to those hosts, on both engines. An entry is `host` (exactly that host) or `*.host` (its subdomains, not `host` itself); a scheme, port or path in an entry is an error. A `goto()` to another host, or one that redirects there, rejects with `err.code === 'NAV_BLOCKED'` (`err.host`) and the page stays where it was. A clicked link, a JS jump or a `window.open` popup to another host never loads; the next `snapshot()` carries `[blocked navigation to <host>]`. New tabs are locked too. `connect({ port, allowHosts })` (attach mode) throws: the lock is browser-wide and would reach your own tabs.
|
|
221
|
+
|
|
222
|
+
Not locked, by design: subresources (images, scripts, CSS, XHR/fetch), iframes and WebSocket. The lock stops an agent being steered to another site, not a page from loading its own assets. The MCP `eval` tool (tier `rwx`) can still `fetch()` anywhere.
|
|
223
|
+
|
|
224
|
+
MCP only: `BAREBROWSE_TIER=r|rw|rwx` (default `rwx`) hides tools above the tier. `r` reads (`browse`, `goto`, `back`, `forward`, `reload`, `scroll`, `snapshot`, `readable`, `screenshot`, `pdf`, `wait_for`, `tabs`, `capabilities`, `assess`); `rw` adds `click`, `type`, `press`, `select`, `drag`, `hover`, `switch_engine`; `rwx` adds `upload` and `eval`. A hidden tool answers `Unknown tool`. Every tool also carries MCP `annotations` (`readOnlyHint`, `destructiveHint`, `openWorldHint`, `idempotentHint`). An invalid `BAREBROWSE_TIER` or `BAREBROWSE_ALLOW` stops the server at start; it never falls back to `rwx` or to no lock. `capabilities` and the server instructions report the tier and the allowed hosts.
|
|
225
|
+
|
|
216
226
|
## What the agent sees
|
|
217
227
|
|
|
218
228
|
Raw ARIA output from a page is noisy -- decorative wrappers, hidden elements, structural junk. The pruning pipeline (ported from [mcprune](https://github.com/hamr0/mcprune)) strips it down to what matters.
|
package/barebrowse.context.md
CHANGED
|
@@ -66,7 +66,7 @@ const snapshot = await browse('https://example.com', {
|
|
|
66
66
|
|
|
67
67
|
| Method | Args | Returns | Notes |
|
|
68
68
|
|---|---|---|---|
|
|
69
|
-
| `goto(url, timeout?)` | url: string, timeout: number (default 30000) | `{ url, status }` | Navigate + wait for load + dismiss consent. Resolves to the final URL (after redirects) and the main document's HTTP status (`0` = no HTTP response observed, e.g. an aborted navigation). Non-2xx still resolves; `snapshot()` then carries `[HTTP 404 — the page may be an error page]`. Network failure (DNS, refused, TLS) rejects with `err.code === 'NAV_FAILED'` and `err.reason` (raw browser string, e.g. `net::ERR_NAME_NOT_RESOLVED` / `NS_ERROR_UNKNOWN_HOST`). A download or 204 (`ERR_ABORTED` / `NS_BINDING_ABORTED`) is not a failure and returns without waiting for a load event. `browse()` still returns a string (warning line prepended when non-2xx) and rejects with the same `NAV_FAILED`. |
|
|
69
|
+
| `goto(url, timeout?)` | url: string, timeout: number (default 30000) | `{ url, status }` | Navigate + wait for load + dismiss consent. Resolves to the final URL (after redirects) and the main document's HTTP status (`0` = no HTTP response observed, e.g. an aborted navigation). Non-2xx still resolves; `snapshot()` then carries `[HTTP 404 — the page may be an error page]`. Network failure (DNS, refused, TLS) rejects with `err.code === 'NAV_FAILED'` and `err.reason` (raw browser string, e.g. `net::ERR_NAME_NOT_RESOLVED` / `NS_ERROR_UNKNOWN_HOST`). A download or 204 (`ERR_ABORTED` / `NS_BINDING_ABORTED`) is not a failure and returns without waiting for a load event. `browse()` still returns a string (warning line prepended when non-2xx) and rejects with the same `NAV_FAILED`. With `allowHosts`, an off-list URL or redirect hop rejects with `err.code === 'NAV_BLOCKED'` (`err.host`) and the page stays put. |
|
|
70
70
|
| `lastNavigation` | -- | `{ url, status }` or null | Outcome of the latest `goto()`; null before any goto and while a goto is failing. Reset to null by `reload`/`goBack`/`goForward`/`switchTab` (status is reported for `goto()` only) |
|
|
71
71
|
| `goBack()` | -- | void | Navigate back in browser history |
|
|
72
72
|
| `goForward()` | -- | void | Navigate forward in browser history |
|
|
@@ -112,6 +112,7 @@ const snapshot = await browse('https://example.com', {
|
|
|
112
112
|
- `blockUrls: ['*://foo.com/*', ...]` — Extra glob patterns (CDP `Network.setBlockedURLs` format) to block in addition to the default. Merged with the default unless `blockAds: false`.
|
|
113
113
|
- `allowLocalUrls: true|false` — (v0.11.0) Default `false`: navigation to local-resource / browser-internal schemes (`file:`, `view-source:`, `chrome:`, `filesystem:`, `devtools:`, …) is **blocked** to stop a prompt-injected agent reading local files. `http`/`https`/`data`/`blob`/`about` are always allowed. Set `true` to permit local schemes.
|
|
114
114
|
- `blockPrivateNetwork: true|false` — (v0.11.0) Default `false`. When `true`, `goto()`/`browse()` refuse loopback / RFC-1918 / link-local / cloud-metadata (`169.254.169.254`) / `*.internal` hosts (SSRF guard). Off by default so localhost dev-server browsing works. Hostname-based — does not catch DNS names that resolve to private IPs.
|
|
115
|
+
- `allowHosts: ['example.com', '*.docs.example.org']` — Site lock (both engines, `connect()` and `browse()`; CLI `--allow-hosts=a,b` on `open`/`browse`; MCP `BAREBROWSE_ALLOW=a,b`). Top-level navigations (goto, redirect hops, clicked links, JS jumps, `window.open` popups, new tabs) to a host outside the list are failed in the browser and the page stays put. Entry = `host` (exact) or `*.host` (strict subdomains, not the apex); scheme/port/path/bare `*` throw. `goto()` rejects with `err.code === 'NAV_BLOCKED'` + `err.host`; in-page blocks add `[blocked navigation to <host>]` to the next `snapshot()`. Attach mode (`port`) throws. NOT locked: subresources, iframes, WebSocket (and MCP `eval`, which can `fetch()` anywhere).
|
|
115
116
|
- `uploadDir: '/abs/dir'` — (v0.11.0) Default unset (no restriction). When set, `upload()` rejects any file that does not resolve (symlinks included, via `realpath`) inside this directory — sandboxes the agent's file-upload capability.
|
|
116
117
|
|
|
117
118
|
## Snapshot format
|
|
@@ -268,7 +269,7 @@ barebrowse switch-engine firefox # Swap chromium/firefox in place (page/ta
|
|
|
268
269
|
barebrowse close # Kill daemon + browser
|
|
269
270
|
```
|
|
270
271
|
|
|
271
|
-
**Open flags:** `--mode=headless|headed|hybrid`, `--port=N` (attach to running browser), `--proxy=URL`, `--viewport=WxH`, `--storage-state=FILE`, `--download-path=DIR` (v0.9.0), `--no-cookies`, `--browser=firefox|chromium`, `--timeout=N`, `--block-private-network` (SSRF guard, v0.11.0), `--upload-dir=DIR` (upload sandbox, v0.11.0)
|
|
272
|
+
**Open flags:** `--mode=headless|headed|hybrid`, `--port=N` (attach to running browser), `--proxy=URL`, `--viewport=WxH`, `--storage-state=FILE`, `--download-path=DIR` (v0.9.0), `--no-cookies`, `--browser=firefox|chromium`, `--timeout=N`, `--block-private-network` (SSRF guard, v0.11.0), `--upload-dir=DIR` (upload sandbox, v0.11.0), `--allow-hosts=a.com,*.b.org` (site lock; also on `browse`)
|
|
272
273
|
|
|
273
274
|
Session lifecycle: `open` spawns a background daemon holding a `connect()` session. Subsequent commands POST to the daemon over HTTP (localhost). `close` shuts everything down. JS dialogs (alert/confirm/prompt) are auto-dismissed and logged.
|
|
274
275
|
|
|
@@ -296,7 +297,7 @@ barebrowse ships an MCP server for direct use with Claude Desktop, Cursor, or an
|
|
|
296
297
|
}
|
|
297
298
|
```
|
|
298
299
|
|
|
299
|
-
21 core tools: `browse` (one-shot), `goto`, `snapshot`, `readable`, `click`, `type`, `press`, `scroll`, `hover`, `select`, `back`, `forward`, `reload`, `drag`, `upload`, `pdf`, `screenshot`, `wait_for`, `tabs`, `capabilities` (engine + feature report, plus a `cookies` field naming the last goto's injected cookies — names only, never values), `switch_engine` (swap chromium/firefox without restarting; page, tabs and refs reset, so `goto` after). Plus `assess` (privacy scan) if `wearehere` is installed (`npm install wearehere`). Plus the **opt-in `eval` tool** gated by `BAREBROWSE_MCP_EVAL=1` (default OFF) — `Runtime.evaluate` in the user's authenticated session can read cookies/localStorage and hit any same-origin endpoint, so opt-in only.
|
|
300
|
+
21 core tools: `browse` (one-shot), `goto`, `snapshot`, `readable`, `click`, `type`, `press`, `scroll`, `hover`, `select`, `back`, `forward`, `reload`, `drag`, `upload`, `pdf`, `screenshot`, `wait_for`, `tabs`, `capabilities` (engine + feature report, plus a `cookies` field naming the last goto's injected cookies — names only, never values), `switch_engine` (swap chromium/firefox without restarting; page, tabs and refs reset, so `goto` after). Plus `assess` (privacy scan) if `wearehere` is installed (`npm install wearehere`). Every tool carries MCP `annotations` (`readOnlyHint`/`destructiveHint`/`openWorldHint`/`idempotentHint`). `BAREBROWSE_TIER=r|rw|rwx` (default `rwx`) hides tools above the tier (`r` = read the web, `rw` = + click/type/press/select/drag/hover/switch_engine, `rwx` = + upload/eval); `BAREBROWSE_ALLOW=a.com,*.b.org` sets the site lock. Bad values refuse to start. `capabilities` reports `tier` and `allowHosts`. Plus the **opt-in `eval` tool** gated by `BAREBROWSE_MCP_EVAL=1` (default OFF) — `Runtime.evaluate` in the user's authenticated session can read cookies/localStorage and hit any same-origin endpoint, so opt-in only.
|
|
300
301
|
|
|
301
302
|
**Idle release:** the MCP server closes its browser after `BAREBROWSE_IDLE_MINUTES` of no tool calls (default `15`; `0` = off; blank/invalid = default; capped at ~24.8 days; calls in flight postpone it). The next call opens a fresh browser — page state (open tabs, a solved captcha) is not resumed. Transient browser errors close the broken browser instead of orphaning it; a `wait_for` that merely times out keeps the page (its outer deadline is `max(60s, timeout+5s)`).
|
|
302
303
|
|
package/cli.js
CHANGED
|
@@ -9,6 +9,7 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from
|
|
|
9
9
|
import { join, resolve } from 'node:path';
|
|
10
10
|
import { homedir, platform } from 'node:os';
|
|
11
11
|
import { fileURLToPath } from 'node:url';
|
|
12
|
+
import { parseAllowHosts } from './src/site-lock.js';
|
|
12
13
|
|
|
13
14
|
const args = process.argv.slice(2);
|
|
14
15
|
const cmd = args[0];
|
|
@@ -127,6 +128,7 @@ async function cmdOpen() {
|
|
|
127
128
|
blockUrls: parseFlagAll('--block-urls'),
|
|
128
129
|
blockPrivateNetwork: hasFlag('--block-private-network') || undefined,
|
|
129
130
|
uploadDir: parseFlag('--upload-dir') ? resolve(parseFlag('--upload-dir')) : undefined,
|
|
131
|
+
allowHosts: parseAllowHostsFlag(),
|
|
130
132
|
};
|
|
131
133
|
|
|
132
134
|
try {
|
|
@@ -205,7 +207,7 @@ async function oneShot() {
|
|
|
205
207
|
const url = args[1];
|
|
206
208
|
const mode = args[2] && !args[2].startsWith('--') ? args[2] : 'headless';
|
|
207
209
|
try {
|
|
208
|
-
const snapshot = await browse(url, { mode, incognito: hasFlag('--incognito') || undefined, links: hasFlag('--links') || undefined });
|
|
210
|
+
const snapshot = await browse(url, { mode, incognito: hasFlag('--incognito') || undefined, links: hasFlag('--links') || undefined, allowHosts: parseAllowHostsFlag() });
|
|
209
211
|
process.stdout.write(snapshot + '\n');
|
|
210
212
|
process.exit(0);
|
|
211
213
|
} catch (err) {
|
|
@@ -234,6 +236,7 @@ async function runDaemonInternal() {
|
|
|
234
236
|
blockUrls: parseFlagAll('--block-urls'),
|
|
235
237
|
blockPrivateNetwork: hasFlag('--block-private-network') || undefined,
|
|
236
238
|
uploadDir: parseFlag('--upload-dir'),
|
|
239
|
+
allowHosts: parseAllowHostsFlag(),
|
|
237
240
|
};
|
|
238
241
|
const outputDir = parseFlag('--output-dir') || resolve('.barebrowse');
|
|
239
242
|
const url = parseFlag('--url');
|
|
@@ -252,6 +255,18 @@ function parseFlag(name) {
|
|
|
252
255
|
return undefined;
|
|
253
256
|
}
|
|
254
257
|
|
|
258
|
+
// --allow-hosts=a.com,*.b.org → validated array (site lock), or undefined when
|
|
259
|
+
// absent. A bad entry exits here, before any browser or daemon is started.
|
|
260
|
+
function parseAllowHostsFlag() {
|
|
261
|
+
const raw = parseFlag('--allow-hosts');
|
|
262
|
+
if (raw === undefined) return undefined;
|
|
263
|
+
try { return parseAllowHosts(raw.split(',')); }
|
|
264
|
+
catch (err) {
|
|
265
|
+
process.stderr.write(`Error: --allow-hosts: ${err.message}\n`);
|
|
266
|
+
process.exit(1);
|
|
267
|
+
}
|
|
268
|
+
}
|
|
269
|
+
|
|
255
270
|
function hasFlag(name) {
|
|
256
271
|
return args.includes(name);
|
|
257
272
|
}
|
|
@@ -579,6 +594,9 @@ Session:
|
|
|
579
594
|
cloud-metadata hosts. Off by default so localhost browsing works.
|
|
580
595
|
--upload-dir=DIR Sandbox uploads: reject files outside DIR (symlinks resolved).
|
|
581
596
|
Default: no restriction. (file:/chrome: schemes are always blocked.)
|
|
597
|
+
--allow-hosts=a.com,*.b.org Site lock: top-level navigation (goto, redirects, links, popups) only to these
|
|
598
|
+
hosts; others fail with NAV_BLOCKED. *.host = subdomains only. Subresources and
|
|
599
|
+
iframes are not locked. Also accepted by browse. Not allowed with --port.
|
|
582
600
|
|
|
583
601
|
Navigation:
|
|
584
602
|
barebrowse goto <url> Navigate to URL
|
|
@@ -620,7 +638,7 @@ Debugging:
|
|
|
620
638
|
barebrowse switch-engine <chromium|firefox> Swap the browser in place (page, tabs, refs are lost)
|
|
621
639
|
|
|
622
640
|
One-shot:
|
|
623
|
-
barebrowse browse <url> [mode] [--links] Browse + print snapshot to stdout
|
|
641
|
+
barebrowse browse <url> [mode] [--links] [--allow-hosts=...] Browse + print snapshot to stdout
|
|
624
642
|
|
|
625
643
|
MCP:
|
|
626
644
|
barebrowse mcp Start MCP server (JSON-RPC over stdio)
|
|
@@ -41,6 +41,7 @@ All output files go to `.barebrowse/` in the current directory. Read them with t
|
|
|
41
41
|
- `--storage-state=FILE` — Load cookies/localStorage from JSON file
|
|
42
42
|
- `--block-private-network` — SSRF guard: refuse loopback / RFC-1918 / link-local / cloud-metadata hosts (v0.11.0)
|
|
43
43
|
- `--upload-dir=DIR` — Sandbox uploads to DIR; reject files outside it (v0.11.0)
|
|
44
|
+
- `--allow-hosts=a.com,*.b.org` — Site lock: top-level navigation only to these hosts (`*.host` = subdomains); others fail with `NAV_BLOCKED`. Subresources and iframes are not locked. Also on `browse`.
|
|
44
45
|
|
|
45
46
|
> Security (v0.11.0): `file:`/`chrome:`/etc. navigation is blocked by default, and the daemon requires a per-session token (handled transparently by the CLI). Snapshots and saved state are written owner-only (`0600`).
|
|
46
47
|
|
package/commands/barebrowse.md
CHANGED
|
@@ -40,6 +40,7 @@ All output files go to `.barebrowse/` in the current directory. Read them with t
|
|
|
40
40
|
- `--storage-state=FILE` — Load cookies/localStorage from JSON file
|
|
41
41
|
- `--block-private-network` — SSRF guard: refuse loopback / RFC-1918 / link-local / cloud-metadata hosts (v0.11.0)
|
|
42
42
|
- `--upload-dir=DIR` — Sandbox uploads to DIR; reject files outside it (v0.11.0)
|
|
43
|
+
- `--allow-hosts=a.com,*.b.org` — Site lock: top-level navigation only to these hosts (`*.host` = subdomains); others fail with `NAV_BLOCKED`. Subresources and iframes are not locked. Also on `browse`.
|
|
43
44
|
|
|
44
45
|
> Security (v0.11.0): `file:`/`chrome:`/etc. navigation is blocked by default, and the daemon requires a per-session token (handled transparently by the CLI). Snapshots and saved state are written owner-only (`0600`).
|
|
45
46
|
|
package/mcp-server.js
CHANGED
|
@@ -15,6 +15,7 @@ import { formatReadable } from './src/readable.js';
|
|
|
15
15
|
import { cleanOld } from './src/output-clean.js';
|
|
16
16
|
import { scopedCookiesForUrl } from './src/auth.js';
|
|
17
17
|
import { isHttpError } from './src/navigation.js';
|
|
18
|
+
import { parseAllowHosts } from './src/site-lock.js';
|
|
18
19
|
import { mkdirSync, writeFileSync, readFileSync } from 'node:fs';
|
|
19
20
|
import { join, dirname } from 'node:path';
|
|
20
21
|
import { pathToFileURL, fileURLToPath } from 'node:url';
|
|
@@ -217,6 +218,53 @@ function engineInfo() {
|
|
|
217
218
|
};
|
|
218
219
|
}
|
|
219
220
|
|
|
221
|
+
// --- Access tier + site lock (env, fixed at server start) ---
|
|
222
|
+
//
|
|
223
|
+
// BAREBROWSE_TIER = r | rw | rwx (default rwx = everything). r: read the web
|
|
224
|
+
// (navigate, observe); rw: + interact (click/type/...); rwx: + upload and eval.
|
|
225
|
+
// Every tool has an explicit tier; a tool missing from the map is rwx, so a
|
|
226
|
+
// new tool is hidden from restricted tiers until someone classifies it.
|
|
227
|
+
const TIER_RANK = { r: 0, rw: 1, rwx: 2 };
|
|
228
|
+
export const TOOL_TIER = {
|
|
229
|
+
browse: 'r', goto: 'r', back: 'r', forward: 'r', reload: 'r', scroll: 'r',
|
|
230
|
+
snapshot: 'r', readable: 'r', screenshot: 'r', pdf: 'r', wait_for: 'r', tabs: 'r',
|
|
231
|
+
capabilities: 'r', assess: 'r',
|
|
232
|
+
click: 'rw', type: 'rw', press: 'rw', select: 'rw', drag: 'rw', hover: 'rw', switch_engine: 'rw',
|
|
233
|
+
upload: 'rwx', eval: 'rwx',
|
|
234
|
+
};
|
|
235
|
+
|
|
236
|
+
/** @param {string} name */
|
|
237
|
+
export function toolTier(name) { return TOOL_TIER[name] ?? 'rwx'; }
|
|
238
|
+
|
|
239
|
+
/** Parse BAREBROWSE_TIER. Unset/empty = rwx; anything else must be exact, or it throws (never widen on a typo). */
|
|
240
|
+
export function parseTier(v) {
|
|
241
|
+
if (v === undefined || v === '') return 'rwx';
|
|
242
|
+
if (!Object.hasOwn(TIER_RANK, v)) throw new Error(`BAREBROWSE_TIER must be r, rw or rwx (got ${JSON.stringify(v)})`);
|
|
243
|
+
return v;
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
/** Parse BAREBROWSE_ALLOW (comma list of hosts). Unset/blank = no lock (null); a bad entry throws. */
|
|
247
|
+
export function parseAllowEnv(v) {
|
|
248
|
+
if (v === undefined || !v.trim()) return null;
|
|
249
|
+
try { return parseAllowHosts(v.split(',')); }
|
|
250
|
+
catch (e) { throw new Error(`BAREBROWSE_ALLOW: ${e.message}`); }
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
/** Read + validate the tier/site-lock env. Throws on bad config. */
|
|
254
|
+
function readAccess() {
|
|
255
|
+
return { tier: parseTier(process.env.BAREBROWSE_TIER), allowHosts: parseAllowEnv(process.env.BAREBROWSE_ALLOW) };
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
/** MCP tool hints derived from the tier: r = read-only; rw/rwx change state (hover and switch_engine non-destructively). */
|
|
259
|
+
function annotationsFor(name) {
|
|
260
|
+
if (toolTier(name) === 'r') {
|
|
261
|
+
const a = { readOnlyHint: true, openWorldHint: name !== 'capabilities' };
|
|
262
|
+
if (['snapshot', 'readable', 'screenshot', 'pdf', 'tabs', 'capabilities', 'wait_for'].includes(name)) a.idempotentHint = true;
|
|
263
|
+
return a;
|
|
264
|
+
}
|
|
265
|
+
return { readOnlyHint: false, destructiveHint: !['hover', 'switch_engine'].includes(name), openWorldHint: true };
|
|
266
|
+
}
|
|
267
|
+
|
|
220
268
|
async function getPage() {
|
|
221
269
|
if (_page) return _page;
|
|
222
270
|
if (_pageConnecting) return _pageConnecting;
|
|
@@ -230,9 +278,10 @@ async function getPage() {
|
|
|
230
278
|
// across tool calls, so it's an env var (BAREBROWSE_INCOGNITO=1), not a
|
|
231
279
|
// per-request flag. Skips all auth injection for a clean, logged-out session.
|
|
232
280
|
const incognito = process.env.BAREBROWSE_INCOGNITO === '1';
|
|
281
|
+
const { allowHosts } = readAccess();
|
|
233
282
|
const connectOpts = _engine === 'firefox'
|
|
234
|
-
? { engine: 'firefox', mode: process.env.BAREBROWSE_MODE || 'hybrid', incognito }
|
|
235
|
-
: { mode: process.env.BAREBROWSE_MODE || 'hybrid', incognito };
|
|
283
|
+
? { engine: 'firefox', mode: process.env.BAREBROWSE_MODE || 'hybrid', incognito, allowHosts }
|
|
284
|
+
: { mode: process.env.BAREBROWSE_MODE || 'hybrid', incognito, allowHosts };
|
|
236
285
|
_pageConnecting = connect(connectOpts);
|
|
237
286
|
try {
|
|
238
287
|
_page = await _pageConnecting;
|
|
@@ -517,12 +566,17 @@ if (assessFn) {
|
|
|
517
566
|
});
|
|
518
567
|
}
|
|
519
568
|
|
|
569
|
+
for (const t of TOOLS) t.annotations = annotationsFor(t.name);
|
|
570
|
+
|
|
520
571
|
async function handleToolCall(name, args) {
|
|
521
572
|
switch (name) {
|
|
522
573
|
case 'capabilities': {
|
|
523
574
|
// Introspection only — must NOT launch a browser. Report the configured
|
|
524
575
|
// engine from env; if a page is already connected, attach its live flags.
|
|
525
576
|
const info = engineInfo();
|
|
577
|
+
const access = readAccess();
|
|
578
|
+
info.tier = access.tier;
|
|
579
|
+
info.allowHosts = access.allowHosts;
|
|
526
580
|
if (_page) {
|
|
527
581
|
info.connected = true;
|
|
528
582
|
info.capabilities = _page.capabilities;
|
|
@@ -547,7 +601,7 @@ async function handleToolCall(name, args) {
|
|
|
547
601
|
case 'browse': {
|
|
548
602
|
let timer;
|
|
549
603
|
const text = await Promise.race([
|
|
550
|
-
browse(args.url, { mode: args.mode, pruneMode: args.pruneMode, incognito: args.incognito, links: args.links }),
|
|
604
|
+
browse(args.url, { mode: args.mode, pruneMode: args.pruneMode, incognito: args.incognito, links: args.links, allowHosts: readAccess().allowHosts ?? undefined }),
|
|
551
605
|
new Promise((_, rej) => { timer = setTimeout(() => rej(new Error('browse timed out after 60s')), 60000); }),
|
|
552
606
|
]);
|
|
553
607
|
clearTimeout(timer);
|
|
@@ -771,6 +825,10 @@ async function handleMessage(msg) {
|
|
|
771
825
|
|
|
772
826
|
if (method === 'initialize') {
|
|
773
827
|
const e = engineInfo();
|
|
828
|
+
const { tier, allowHosts } = readAccess();
|
|
829
|
+
const access = (tier === 'r' ? ' Access tier: read-only (no clicking, typing or uploading).'
|
|
830
|
+
: tier === 'rw' ? ' Access tier: read/write (no upload or eval).' : '')
|
|
831
|
+
+ (allowHosts ? ` Navigation is restricted to: ${allowHosts.join(', ')}.` : '');
|
|
774
832
|
return jsonrpcResponse(id, {
|
|
775
833
|
protocolVersion: '2024-11-05',
|
|
776
834
|
capabilities: { tools: {} },
|
|
@@ -780,7 +838,7 @@ async function handleMessage(msg) {
|
|
|
780
838
|
instructions:
|
|
781
839
|
`barebrowse drives a real browser. Active engine: ${e.activeEngine} (mode: ${e.mode}). `
|
|
782
840
|
+ `Both chromium and firefox are supported; ${e.switchEngine} `
|
|
783
|
-
+ `Call the "capabilities" tool for the live engine + feature set
|
|
841
|
+
+ `Call the "capabilities" tool for the live engine + feature set.${access}`,
|
|
784
842
|
});
|
|
785
843
|
}
|
|
786
844
|
|
|
@@ -793,7 +851,8 @@ async function handleMessage(msg) {
|
|
|
793
851
|
// active engine (and that both are supported) is visible without a call.
|
|
794
852
|
const e = engineInfo();
|
|
795
853
|
const note = ` [Active engine: ${e.activeEngine}; chromium + firefox both supported — ${e.switchEngine}]`;
|
|
796
|
-
const
|
|
854
|
+
const { tier } = readAccess();
|
|
855
|
+
const tools = TOOLS.filter((t) => TIER_RANK[toolTier(t.name)] <= TIER_RANK[tier]).map((t) =>
|
|
797
856
|
t.name === 'browse' ? { ...t, description: t.description + note } : t);
|
|
798
857
|
return jsonrpcResponse(id, { tools });
|
|
799
858
|
}
|
|
@@ -803,6 +862,8 @@ async function handleMessage(msg) {
|
|
|
803
862
|
_inflight++;
|
|
804
863
|
clearTimeout(_idleTimer);
|
|
805
864
|
try {
|
|
865
|
+
// A tool above the tier answers exactly like one that doesn't exist.
|
|
866
|
+
if (TIER_RANK[toolTier(name)] > TIER_RANK[readAccess().tier]) throw new Error(`Unknown tool: ${name}`);
|
|
806
867
|
const result = await handleToolCall(name, args || {});
|
|
807
868
|
return jsonrpcResponse(id, {
|
|
808
869
|
content: [{ type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result) }],
|
|
@@ -833,6 +894,11 @@ async function handleMessage(msg) {
|
|
|
833
894
|
// runStdio() explicitly. Tests import TIMEOUTS/TOOLS without calling it.
|
|
834
895
|
|
|
835
896
|
export function runStdio() {
|
|
897
|
+
// Fail closed: a bad tier or allow list must stop the server, never fall back to rwx / no lock.
|
|
898
|
+
try { readAccess(); } catch (e) {
|
|
899
|
+
process.stderr.write(`barebrowse mcp: ${e.message}\n`);
|
|
900
|
+
process.exit(1);
|
|
901
|
+
}
|
|
836
902
|
cleanOld(OUTPUT_DIR);
|
|
837
903
|
// One-line startup banner to stderr (stderr because stdout is the JSON-RPC
|
|
838
904
|
// channel — must not contain non-JSON-RPC bytes). Captured by Claude Code's
|
package/package.json
CHANGED
package/src/blocklist-firefox.js
CHANGED
|
@@ -13,9 +13,15 @@
|
|
|
13
13
|
* request pauses for one continue/fail round-trip to Node. On a typical page
|
|
14
14
|
* (tens–low-hundreds of requests over a local socket) that's negligible, and
|
|
15
15
|
* it's the only route that preserves glob parity without a second list.
|
|
16
|
+
*
|
|
17
|
+
* The site lock (`allowHosts`, site-lock.js) plugs into this same handler: a
|
|
18
|
+
* second catch-all handler would race this one on the same paused request, so
|
|
19
|
+
* there is exactly one continue/fail decision per request, and the intercept
|
|
20
|
+
* exists whenever either the blocklist or the lock is active.
|
|
16
21
|
*/
|
|
17
22
|
|
|
18
23
|
import { resolveBlocklistPatterns, makeBlockMatcher } from './blocklist.js';
|
|
24
|
+
import { createFirefoxLockCheck } from './site-lock.js';
|
|
19
25
|
|
|
20
26
|
/**
|
|
21
27
|
* Install ad/tracker blocking on a BiDi session. Idempotent per session is the
|
|
@@ -26,13 +32,15 @@ import { resolveBlocklistPatterns, makeBlockMatcher } from './blocklist.js';
|
|
|
26
32
|
* @param {boolean} [pageOpts.blockAds] - false disables the default list.
|
|
27
33
|
* @param {string[]} [pageOpts.blockUrls] - extra CDP-format globs; extend the
|
|
28
34
|
* default unless blockAds is false, in which case they're the whole list.
|
|
35
|
+
* @param {import('./site-lock.js').SiteLock|null} [lock] - Site lock to enforce in the same handler.
|
|
29
36
|
* @returns {Promise<void>}
|
|
30
37
|
*/
|
|
31
|
-
export async function applyFirefoxBlocklist(bidi, pageOpts = {}) {
|
|
38
|
+
export async function applyFirefoxBlocklist(bidi, pageOpts = {}, lock = null) {
|
|
32
39
|
const patterns = resolveBlocklistPatterns(pageOpts);
|
|
33
|
-
if (!patterns.length) return;
|
|
40
|
+
if (!patterns.length && !lock) return;
|
|
34
41
|
|
|
35
|
-
const isBlocked = makeBlockMatcher(patterns);
|
|
42
|
+
const isBlocked = patterns.length ? makeBlockMatcher(patterns) : () => false;
|
|
43
|
+
const lockBlocks = lock ? await createFirefoxLockCheck(bidi, lock) : null;
|
|
36
44
|
|
|
37
45
|
await bidi.send('network.addIntercept', {
|
|
38
46
|
phases: ['beforeRequestSent'],
|
|
@@ -47,7 +55,7 @@ export async function applyFirefoxBlocklist(bidi, pageOpts = {}) {
|
|
|
47
55
|
const id = e.request?.request;
|
|
48
56
|
if (!id) return;
|
|
49
57
|
try {
|
|
50
|
-
if (isBlocked(e.request.url)) {
|
|
58
|
+
if (isBlocked(e.request.url) || (lockBlocks && await lockBlocks(e))) {
|
|
51
59
|
await bidi.send('network.failRequest', { request: id });
|
|
52
60
|
} else {
|
|
53
61
|
await bidi.send('network.continueRequest', { request: id });
|
package/src/daemon.js
CHANGED
|
@@ -66,6 +66,7 @@ export function buildDaemonArgs(opts, absDir, initialUrl, cliPath) {
|
|
|
66
66
|
}
|
|
67
67
|
if (opts.blockPrivateNetwork) args.push('--block-private-network');
|
|
68
68
|
if (opts.uploadDir) args.push('--upload-dir', opts.uploadDir);
|
|
69
|
+
if (opts.allowHosts) args.push('--allow-hosts', opts.allowHosts.join(','));
|
|
69
70
|
return args;
|
|
70
71
|
}
|
|
71
72
|
|
|
@@ -235,6 +236,7 @@ export async function runDaemon(opts, outputDir, initialUrl) {
|
|
|
235
236
|
blockUrls: opts.blockUrls,
|
|
236
237
|
blockPrivateNetwork: opts.blockPrivateNetwork,
|
|
237
238
|
uploadDir: opts.uploadDir,
|
|
239
|
+
allowHosts: opts.allowHosts,
|
|
238
240
|
// incognito neuters injectCookies() session-wide; cookies:false (below)
|
|
239
241
|
// is the legacy per-open equivalent. Either yields a logged-out session.
|
|
240
242
|
incognito: opts.incognito || opts.cookies === false,
|
package/src/firefox-page.js
CHANGED
|
@@ -28,7 +28,7 @@ import { waitForNetworkIdleBiDi } from './network-idle.js';
|
|
|
28
28
|
import { decideDialog, dialogLogEntry } from './dialog.js';
|
|
29
29
|
import { isChallengePage, countNodes } from './challenge.js';
|
|
30
30
|
import { withTimeout } from './with-timeout.js';
|
|
31
|
-
import { navFailed, httpWarning } from './navigation.js';
|
|
31
|
+
import { navFailed, navBlocked, httpWarning } from './navigation.js';
|
|
32
32
|
|
|
33
33
|
/** BiDi/WebDriver normalized key values for named keys (U+E000 block). */
|
|
34
34
|
const BIDI_KEYS = {
|
|
@@ -46,6 +46,7 @@ const BIDI_KEYS = {
|
|
|
46
46
|
* @param {boolean} [opts.links=false] - Default for snapshot({ links }): show link URLs.
|
|
47
47
|
* @param {{allowLocalUrls?: boolean, blockPrivateNetwork?: boolean}} [opts.urlGuard] - Navigation safety policy, applied on every goto().
|
|
48
48
|
* @param {string} [opts.uploadDir] - When set, upload() rejects files outside this dir.
|
|
49
|
+
* @param {?import('./site-lock.js').SiteLock} [opts.siteLock] - Site lock (allowHosts) state; the request-level enforcement is installed by applyFirefoxBlocklist, this side maps it to NAV_BLOCKED and snapshot notes.
|
|
49
50
|
* @param {boolean} [opts.incognito=false] - Clean session: injectCookies() is a no-op.
|
|
50
51
|
* @param {boolean} [opts.consent=true] - Auto-dismiss cookie consent dialogs after goto().
|
|
51
52
|
* @param {boolean} [opts.hybrid=false] - Relaunch headed on a bot-challenge page and retry.
|
|
@@ -56,6 +57,7 @@ export async function createFirefoxPage(bidi, opts = {}) {
|
|
|
56
57
|
const defaultPruneMode = opts.pruneMode || 'act';
|
|
57
58
|
const urlGuard = opts.urlGuard || {};
|
|
58
59
|
const uploadDir = opts.uploadDir || null;
|
|
60
|
+
const lock = opts.siteLock || null;
|
|
59
61
|
const incognito = !!opts.incognito;
|
|
60
62
|
const consent = opts.consent !== false;
|
|
61
63
|
// True when the consent pass after the latest goto() found nothing: the first
|
|
@@ -282,6 +284,7 @@ export async function createFirefoxPage(bidi, opts = {}) {
|
|
|
282
284
|
const offStarted = bidi.on('network.responseStarted', (e) => {
|
|
283
285
|
if (e.navigation && e.context === topContext) started.push(e);
|
|
284
286
|
});
|
|
287
|
+
lock?.startGoto(topContext);
|
|
285
288
|
try {
|
|
286
289
|
const res = await withTimeout(
|
|
287
290
|
bidi.send('browsingContext.navigate', { context: topContext, url, wait: 'complete' }),
|
|
@@ -289,6 +292,10 @@ export async function createFirefoxPage(bidi, opts = {}) {
|
|
|
289
292
|
const last = events.filter((e) => e.navigation === res.navigation).pop();
|
|
290
293
|
return { url: last ? last.response.url : url, status: last ? last.response.status : 0 };
|
|
291
294
|
} catch (err) {
|
|
295
|
+
// A lock-refused document (the URL or a redirect hop) surfaces as
|
|
296
|
+
// NS_ERROR_ABORT; report it as NAV_BLOCKED, not NAV_FAILED.
|
|
297
|
+
const blocked = lock?.takeGotoBlock(topContext);
|
|
298
|
+
if (blocked) throw navBlocked(blocked.url, blocked.host);
|
|
292
299
|
const m = /^BiDi error: unknown error — (?:Error: )?(.+)$/.exec(err.message);
|
|
293
300
|
if (!m) throw err;
|
|
294
301
|
if (m[1] === 'NS_BINDING_ABORTED') {
|
|
@@ -359,6 +366,7 @@ export async function createFirefoxPage(bidi, opts = {}) {
|
|
|
359
366
|
// Same navigation guard the CDP path enforces — block file:/chrome:/
|
|
360
367
|
// view-source: and (optionally) private-network hosts before navigating.
|
|
361
368
|
assertNavigable(url, urlGuard);
|
|
369
|
+
lock?.assertAllowed(url);
|
|
362
370
|
refContexts = new Map(); // refs from the previous page are now stale
|
|
363
371
|
consentRecheck = null; // a throwing navigate() must not leave the old page's flag
|
|
364
372
|
lastNavigation = null;
|
|
@@ -408,7 +416,7 @@ export async function createFirefoxPage(bidi, opts = {}) {
|
|
|
408
416
|
|
|
409
417
|
const pageUrl = await bidi.evaluate(topContext, 'location.href', false).catch(() => '');
|
|
410
418
|
const raw = formatTree(root);
|
|
411
|
-
const warn = httpWarning(lastNavigation?.status);
|
|
419
|
+
const warn = httpWarning(lastNavigation?.status) + (lock?.takeNotes(topContext) ?? '');
|
|
412
420
|
const links = !!((pruneOpts || undefined)?.links ?? opts.links);
|
|
413
421
|
const tree = links ? annotateLinks(root, pageUrl) : root;
|
|
414
422
|
if (pruneOpts === false) return `url: ${pageUrl}\n` + warn + (links ? formatTree(tree) : raw);
|
package/src/index.js
CHANGED
|
@@ -29,7 +29,8 @@ import { decideDialog, dialogLogEntry } from './dialog.js';
|
|
|
29
29
|
import { isChallengePage } from './challenge.js';
|
|
30
30
|
import { withTimeout } from './with-timeout.js';
|
|
31
31
|
import { readable as extractReadable } from './readable.js';
|
|
32
|
-
import { navFailed, httpWarning } from './navigation.js';
|
|
32
|
+
import { navFailed, navBlocked, httpWarning } from './navigation.js';
|
|
33
|
+
import { createSiteLock, applySiteLockCDP } from './site-lock.js';
|
|
33
34
|
import { assertNavigable, assertUploadAllowed } from './url-guard.js';
|
|
34
35
|
import { join as pathJoin } from 'node:path';
|
|
35
36
|
import { chmodSync } from 'node:fs';
|
|
@@ -63,6 +64,9 @@ import { chmodSync } from 'node:fs';
|
|
|
63
64
|
* @param {boolean} [opts.consent=true] - Auto-dismiss cookie consent dialogs.
|
|
64
65
|
* @param {'act'|'browse'|'navigate'|'full'|'read'|'data'} [opts.pruneMode='act'] - Pruning mode.
|
|
65
66
|
* @param {boolean} [opts.links=false] - Show link URLs: `link "name" <url> [ref=N]`.
|
|
67
|
+
* @param {string[]} [opts.allowHosts] - Site lock: top-level navigations (the URL, its
|
|
68
|
+
* redirects) to hosts outside this list reject with NAV_BLOCKED. Entries are `host`
|
|
69
|
+
* or `*.host` (strict subdomains). Subresources and iframes are not locked.
|
|
66
70
|
* @returns {Promise<string>} ARIA snapshot text
|
|
67
71
|
*/
|
|
68
72
|
export async function browse(url, opts = {}) {
|
|
@@ -74,6 +78,8 @@ export async function browse(url, opts = {}) {
|
|
|
74
78
|
// Reject local-resource schemes (and optionally private hosts) before we
|
|
75
79
|
// spend a browser launch on a URL we won't navigate to.
|
|
76
80
|
assertNavigable(url, { allowLocalUrls: opts.allowLocalUrls, blockPrivateNetwork: opts.blockPrivateNetwork });
|
|
81
|
+
const lock = opts.allowHosts ? createSiteLock(opts.allowHosts) : null;
|
|
82
|
+
lock?.assertAllowed(url);
|
|
77
83
|
|
|
78
84
|
let browser = null;
|
|
79
85
|
let cdp = null;
|
|
@@ -91,6 +97,7 @@ export async function browse(url, opts = {}) {
|
|
|
91
97
|
browser = await launch(launchOpts);
|
|
92
98
|
cdp = await createCDP(browser.wsUrl);
|
|
93
99
|
}
|
|
100
|
+
if (lock) await applySiteLockCDP(cdp, lock);
|
|
94
101
|
|
|
95
102
|
// Step 2: Create a new page target and attach
|
|
96
103
|
const pageOpts = { viewport: opts.viewport, blockAds: opts.blockAds, blockUrls: opts.blockUrls };
|
|
@@ -109,7 +116,7 @@ export async function browse(url, opts = {}) {
|
|
|
109
116
|
}
|
|
110
117
|
|
|
111
118
|
// Step 4: Navigate and wait for load
|
|
112
|
-
let outcome = await navigate(page, url, timeout);
|
|
119
|
+
let outcome = await navigate(page, url, timeout, lock);
|
|
113
120
|
|
|
114
121
|
// Step 4.5: Auto-dismiss cookie consent dialogs
|
|
115
122
|
if (opts.consent !== false) {
|
|
@@ -128,12 +135,13 @@ export async function browse(url, opts = {}) {
|
|
|
128
135
|
try {
|
|
129
136
|
browser = await launch({ ...launchOpts, headed: true });
|
|
130
137
|
cdp = await createCDP(browser.wsUrl);
|
|
138
|
+
if (lock) await applySiteLockCDP(cdp, lock);
|
|
131
139
|
page = await createPage(cdp, false, pageOpts);
|
|
132
140
|
await suppressPermissions(cdp);
|
|
133
141
|
if (!noAuth) {
|
|
134
142
|
try { await authenticate(page.session, url, { browser: opts.browser }); } catch {}
|
|
135
143
|
}
|
|
136
|
-
outcome = await navigate(page, url, timeout);
|
|
144
|
+
outcome = await navigate(page, url, timeout, lock);
|
|
137
145
|
if (opts.consent !== false) await dismissConsent(page.session);
|
|
138
146
|
({ tree } = await ariaTree(page));
|
|
139
147
|
} catch {
|
|
@@ -281,6 +289,11 @@ export async function browse(url, opts = {}) {
|
|
|
281
289
|
* ever enters the session even if a caller injects unconditionally.
|
|
282
290
|
* @param {'act'|'browse'|'navigate'|'full'|'read'|'data'} [opts.pruneMode='act'] - Pruning mode.
|
|
283
291
|
* @param {boolean} [opts.links=false] - Default for `snapshot({ links })`: show link URLs.
|
|
292
|
+
* @param {string[]} [opts.allowHosts] - Site lock: top-level navigations (goto, redirects,
|
|
293
|
+
* clicked links, JS jumps, popups) to hosts outside this list are refused and the page
|
|
294
|
+
* stays put. Entries are `host` or `*.host` (strict subdomains). goto() rejects with
|
|
295
|
+
* NAV_BLOCKED; in-page blocks add a `[blocked navigation to <host>]` line to the next
|
|
296
|
+
* snapshot. Subresources, iframes and WebSocket are not locked. Not allowed with `port`.
|
|
284
297
|
* @param {'chromium'|'firefox'} [opts.engine='chromium'] - Browser engine.
|
|
285
298
|
* 'firefox' drives over WebDriver BiDi (a separate transport / page object);
|
|
286
299
|
* 'chromium' (default) uses CDP.
|
|
@@ -339,6 +352,12 @@ export async function connect(opts = {}) {
|
|
|
339
352
|
|
|
340
353
|
const mode = opts.mode || 'headless';
|
|
341
354
|
const attachMode = !!opts.port;
|
|
355
|
+
// Validate before launching anything. Attach mode is refused: the lock is a
|
|
356
|
+
// browser-level intercept that would reach the user's own tabs.
|
|
357
|
+
if (opts.allowHosts && attachMode) {
|
|
358
|
+
throw new Error('allowHosts is not supported in attach mode (port): the site lock is browser-wide and would affect your own tabs');
|
|
359
|
+
}
|
|
360
|
+
const lock = opts.allowHosts ? createSiteLock(opts.allowHosts) : null;
|
|
342
361
|
// Incognito: run a clean, unauthenticated session. Skips storageState loading
|
|
343
362
|
// and neuters injectCookies() so no auth ever enters the session — even when
|
|
344
363
|
// a caller (MCP goto, daemon) calls injectCookies() unconditionally. The
|
|
@@ -370,6 +389,7 @@ export async function connect(opts = {}) {
|
|
|
370
389
|
browser = await launch(launchOpts);
|
|
371
390
|
cdp = await createCDP(browser.wsUrl);
|
|
372
391
|
}
|
|
392
|
+
if (lock) await applySiteLockCDP(cdp, lock);
|
|
373
393
|
|
|
374
394
|
// In attach mode we don't know (and shouldn't assume) the user's headed/
|
|
375
395
|
// headless state — treat it as headed so stealth patches are skipped
|
|
@@ -506,6 +526,7 @@ export async function connect(opts = {}) {
|
|
|
506
526
|
return {
|
|
507
527
|
async goto(url, timeout = 30000) {
|
|
508
528
|
assertNavigable(url, urlGuard);
|
|
529
|
+
lock?.assertAllowed(url);
|
|
509
530
|
// Refs from the previous page are about to become invalid — clear
|
|
510
531
|
// before navigating so a stale click(ref) errors clearly instead of
|
|
511
532
|
// silently resolving to whatever backendNodeId happens to still be in
|
|
@@ -523,13 +544,14 @@ export async function connect(opts = {}) {
|
|
|
523
544
|
|
|
524
545
|
browser = await launch(launchOpts);
|
|
525
546
|
cdp = await createCDP(browser.wsUrl);
|
|
547
|
+
if (lock) await applySiteLockCDP(cdp, lock);
|
|
526
548
|
page = await createPage(cdp, true, pageOpts);
|
|
527
549
|
setupDialogHandler(page.session);
|
|
528
550
|
await suppressPermissions(cdp);
|
|
529
551
|
currentlyHeaded = false;
|
|
530
552
|
}
|
|
531
553
|
|
|
532
|
-
lastNavigation = await navigate(page, url, timeout);
|
|
554
|
+
lastNavigation = await navigate(page, url, timeout, lock);
|
|
533
555
|
if (opts.consent !== false) {
|
|
534
556
|
const dismissed = await dismissConsent(page.session);
|
|
535
557
|
if (!dismissed) consentRecheck = await navKey();
|
|
@@ -550,10 +572,11 @@ export async function connect(opts = {}) {
|
|
|
550
572
|
try {
|
|
551
573
|
browser = await launch({ ...launchOpts, headed: true });
|
|
552
574
|
cdp = await createCDP(browser.wsUrl);
|
|
575
|
+
if (lock) await applySiteLockCDP(cdp, lock);
|
|
553
576
|
page = await createPage(cdp, false, pageOpts);
|
|
554
577
|
setupDialogHandler(page.session);
|
|
555
578
|
await suppressPermissions(cdp);
|
|
556
|
-
lastNavigation = await navigate(page, url, timeout);
|
|
579
|
+
lastNavigation = await navigate(page, url, timeout, lock);
|
|
557
580
|
consentRecheck = null;
|
|
558
581
|
if (opts.consent !== false && !(await dismissConsent(page.session))) {
|
|
559
582
|
consentRecheck = await navKey();
|
|
@@ -628,7 +651,7 @@ export async function connect(opts = {}) {
|
|
|
628
651
|
const { currentIndex, entries } = await page.session.send('Page.getNavigationHistory');
|
|
629
652
|
const pageUrl = entries[currentIndex]?.url || '';
|
|
630
653
|
const warn = (botBlocked ? '[BOT CHALLENGE DETECTED — page content may be incomplete or blocked]\n' : '')
|
|
631
|
-
+ httpWarning(lastNavigation?.status);
|
|
654
|
+
+ httpWarning(lastNavigation?.status) + (lock?.takeNotes(page.targetId) ?? '');
|
|
632
655
|
const links = !!((pruneOpts || undefined)?.links ?? opts.links);
|
|
633
656
|
const tree = links ? annotateLinks(result.tree, pageUrl) : result.tree;
|
|
634
657
|
if (pruneOpts === false) return `url: ${pageUrl}\n` + warn + (links ? formatTree(tree) : raw);
|
|
@@ -854,7 +877,8 @@ export async function connect(opts = {}) {
|
|
|
854
877
|
return {
|
|
855
878
|
async goto(url, timeout = 30000) {
|
|
856
879
|
assertNavigable(url, urlGuard);
|
|
857
|
-
|
|
880
|
+
lock?.assertAllowed(url);
|
|
881
|
+
const outcome = await navigate(tab, url, timeout, lock);
|
|
858
882
|
if (opts.consent !== false) {
|
|
859
883
|
await dismissConsent(tab.session);
|
|
860
884
|
}
|
|
@@ -940,10 +964,11 @@ async function suppressPermissions(cdp) {
|
|
|
940
964
|
* v0.16.0. Still Firefox-limited: `reload({ignoreCache})` (upstream BiDi gap).
|
|
941
965
|
* The navigation guard (`allowLocalUrls`/`blockPrivateNetwork`), `uploadDir`
|
|
942
966
|
* sandbox, `incognito`, `proxy`, `viewport`, and `pruneMode` all apply.
|
|
943
|
-
* @param {object} opts - connect() options ({ mode, proxy, binary, viewport, pruneMode, urlGuard, uploadDir, incognito, downloadPath, blockAds, blockUrls })
|
|
967
|
+
* @param {object} opts - connect() options ({ mode, proxy, binary, viewport, pruneMode, urlGuard, uploadDir, incognito, downloadPath, blockAds, blockUrls, allowHosts })
|
|
944
968
|
*/
|
|
945
969
|
async function connectFirefox(opts) {
|
|
946
970
|
const hybrid = opts.mode === 'hybrid';
|
|
971
|
+
const lock = opts.allowHosts ? createSiteLock(opts.allowHosts) : null; // validates before any launch
|
|
947
972
|
const blockOpts = {
|
|
948
973
|
blockAds: opts.blockAds !== undefined ? opts.blockAds : true,
|
|
949
974
|
blockUrls: opts.blockUrls,
|
|
@@ -972,7 +997,7 @@ async function connectFirefox(opts) {
|
|
|
972
997
|
});
|
|
973
998
|
const bidi = await createBiDi(browser.wsUrl);
|
|
974
999
|
if (!headed) await applyFirefoxStealth(bidi);
|
|
975
|
-
await applyFirefoxBlocklist(bidi, blockOpts);
|
|
1000
|
+
await applyFirefoxBlocklist(bidi, blockOpts, lock);
|
|
976
1001
|
const { contexts } = await bidi.send('browsingContext.getTree', {});
|
|
977
1002
|
return { browser, bidi, topContext: contexts[0].context };
|
|
978
1003
|
}
|
|
@@ -997,6 +1022,7 @@ async function connectFirefox(opts) {
|
|
|
997
1022
|
links: opts.links,
|
|
998
1023
|
urlGuard: { allowLocalUrls: opts.allowLocalUrls, blockPrivateNetwork: opts.blockPrivateNetwork },
|
|
999
1024
|
uploadDir: opts.uploadDir || null,
|
|
1025
|
+
siteLock: lock,
|
|
1000
1026
|
incognito: !!opts.incognito,
|
|
1001
1027
|
consent: opts.consent,
|
|
1002
1028
|
hybrid,
|
|
@@ -1164,10 +1190,15 @@ export function _resetBlocklistWarning() {
|
|
|
1164
1190
|
/**
|
|
1165
1191
|
* Navigate to a URL and wait for the page to load. Resolves to the outcome of
|
|
1166
1192
|
* the main-document navigation (final URL after redirects, HTTP status);
|
|
1167
|
-
* rejects with a NAV_FAILED error when the browser could not reach a document
|
|
1193
|
+
* rejects with a NAV_FAILED error when the browser could not reach a document,
|
|
1194
|
+
* or NAV_BLOCKED when the site lock refused the URL or a redirect hop.
|
|
1195
|
+
* @param {*} page
|
|
1196
|
+
* @param {string} url
|
|
1197
|
+
* @param {number} [timeout]
|
|
1198
|
+
* @param {import('./site-lock.js').SiteLock|null} [lock]
|
|
1168
1199
|
* @returns {Promise<NavigationOutcome>}
|
|
1169
1200
|
*/
|
|
1170
|
-
async function navigate(page, url, timeout = 30000) {
|
|
1201
|
+
async function navigate(page, url, timeout = 30000, lock = null) {
|
|
1171
1202
|
const { session } = page;
|
|
1172
1203
|
// Main-document responses (every redirect hop fires one; the last wins).
|
|
1173
1204
|
const docs = [];
|
|
@@ -1182,7 +1213,12 @@ async function navigate(page, url, timeout = 30000) {
|
|
|
1182
1213
|
}));
|
|
1183
1214
|
loaded.catch(() => {}); // rejection is only read if we await it below
|
|
1184
1215
|
try {
|
|
1216
|
+
lock?.startGoto(page.targetId);
|
|
1185
1217
|
const nav = await session.send('Page.navigate', { url });
|
|
1218
|
+
// A lock-refused document (the URL or a redirect hop) also surfaces as
|
|
1219
|
+
// ERR_ABORTED, so this must come before the aborted branch below.
|
|
1220
|
+
const blocked = lock?.takeGotoBlock(page.targetId);
|
|
1221
|
+
if (blocked) throw navBlocked(blocked.url, blocked.host);
|
|
1186
1222
|
// ERR_ABORTED is not a failure: a download (isDownload) or a 204 replaces
|
|
1187
1223
|
// no document and fires no load event, so don't wait for one.
|
|
1188
1224
|
const aborted = nav.errorText === 'net::ERR_ABORTED';
|
package/src/navigation.js
CHANGED
|
@@ -23,6 +23,18 @@ export function navFailed(url, reason) {
|
|
|
23
23
|
return Object.assign(new Error(`Navigation to ${url} failed: ${reason}`), { code: /** @type {const} */ ('NAV_FAILED'), reason });
|
|
24
24
|
}
|
|
25
25
|
|
|
26
|
+
/**
|
|
27
|
+
* Typed error for a top-level navigation the site lock (`allowHosts`) refused:
|
|
28
|
+
* the target, or a redirect hop of it, is off the allowed list. `code` is
|
|
29
|
+
* 'NAV_BLOCKED'; `host` is the refused hostname. The page stays where it was.
|
|
30
|
+
* @param {string} url - The refused URL (the redirect target, if it was a hop).
|
|
31
|
+
* @param {string} host
|
|
32
|
+
* @returns {Error & {code: 'NAV_BLOCKED', host: string}}
|
|
33
|
+
*/
|
|
34
|
+
export function navBlocked(url, host) {
|
|
35
|
+
return Object.assign(new Error(`Navigation to ${url} blocked: ${host} is not in allowHosts`), { code: /** @type {const} */ ('NAV_BLOCKED'), host });
|
|
36
|
+
}
|
|
37
|
+
|
|
26
38
|
/**
|
|
27
39
|
* True for a final HTTP status that is not 2xx (0 = unknown is not an error).
|
|
28
40
|
* @param {number|undefined} status
|
package/src/site-lock.js
ADDED
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* site-lock.js — Optional top-frame site lock (`allowHosts`).
|
|
3
|
+
*
|
|
4
|
+
* Top-level navigations (goto, redirect hops, clicked links, JS jumps, popups)
|
|
5
|
+
* to a host outside the allow list are failed in the browser before any request
|
|
6
|
+
* leaves, so the page stays put. Deliberately NOT locked: subresources
|
|
7
|
+
* (img/script/css/XHR/fetch), iframes, WebSocket — the lock stops an agent
|
|
8
|
+
* being steered to another site, not the page from loading its own assets.
|
|
9
|
+
* The engine wiring lives next to each transport (applySiteLockCDP here,
|
|
10
|
+
* blocklist-firefox.js for BiDi); this file is the shared policy + state.
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
import { navBlocked } from './navigation.js';
|
|
14
|
+
|
|
15
|
+
const HOST_RE = /^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$/;
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Validate and normalize an allow list. Entry = `host` or `*.host`; anything
|
|
19
|
+
* else (scheme, port, path, spaces, empty, bare `*`) throws — a typo must never
|
|
20
|
+
* silently widen or drop the lock.
|
|
21
|
+
* @param {string[]} list
|
|
22
|
+
* @returns {string[]} lowercase entries
|
|
23
|
+
*/
|
|
24
|
+
export function parseAllowHosts(list) {
|
|
25
|
+
if (!Array.isArray(list) || !list.length) throw new Error('allowHosts must be a non-empty array of hostnames');
|
|
26
|
+
return list.map((raw) => {
|
|
27
|
+
const e = typeof raw === 'string' ? raw.trim().toLowerCase() : raw;
|
|
28
|
+
const host = typeof e === 'string' && e.startsWith('*.') ? e.slice(2) : e;
|
|
29
|
+
if (typeof host !== 'string' || !HOST_RE.test(host) || host.includes('..')) {
|
|
30
|
+
throw new Error(`allowHosts: invalid entry ${JSON.stringify(raw)} (expected "host" or "*.host", no scheme/port/path)`);
|
|
31
|
+
}
|
|
32
|
+
return e;
|
|
33
|
+
});
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* Build a URL matcher from an allow list. Non-http(s) URLs (about:, data:,
|
|
38
|
+
* blob:) are allowed; `host` matches that host exactly, `*.host` matches its
|
|
39
|
+
* strict subdomains only (not `host` itself). An unparseable URL is refused.
|
|
40
|
+
* @param {string[]} list
|
|
41
|
+
* @returns {(url: string) => boolean}
|
|
42
|
+
*/
|
|
43
|
+
export function makeHostMatcher(list) {
|
|
44
|
+
const entries = parseAllowHosts(list);
|
|
45
|
+
const exact = new Set(entries.filter((e) => !e.startsWith('*.')));
|
|
46
|
+
const suffixes = entries.filter((e) => e.startsWith('*.')).map((e) => e.slice(1)); // ".host"
|
|
47
|
+
return (url) => {
|
|
48
|
+
let u;
|
|
49
|
+
try { u = new URL(url); } catch { return false; }
|
|
50
|
+
if (u.protocol !== 'http:' && u.protocol !== 'https:') return true;
|
|
51
|
+
const host = u.hostname.replace(/\.$/, '');
|
|
52
|
+
return exact.has(host) || suffixes.some((s) => host.endsWith(s));
|
|
53
|
+
};
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* The lock's shared state, one per connect()/browse() call, surviving
|
|
58
|
+
* relaunches and new tabs (each transport just keeps calling record()).
|
|
59
|
+
* @param {string[]} list
|
|
60
|
+
*/
|
|
61
|
+
export function createSiteLock(list) {
|
|
62
|
+
const allowed = makeHostMatcher(list);
|
|
63
|
+
const hostOf = (url) => { try { return new URL(url).hostname; } catch { return url; } };
|
|
64
|
+
/** @type {{url: string, host: string, ctx: string}[]} */
|
|
65
|
+
let gotoBlocks = [];
|
|
66
|
+
// Snapshot notes belong to the tab/context where the block happened, so one
|
|
67
|
+
// tab's (or a popup's, shown if the agent switches to it) never leak into another's.
|
|
68
|
+
/** @type {Map<string, Set<string>>} */
|
|
69
|
+
const noted = new Map();
|
|
70
|
+
return {
|
|
71
|
+
allowed,
|
|
72
|
+
/** @param {string} url @throws NAV_BLOCKED when url is off the list */
|
|
73
|
+
assertAllowed(url) {
|
|
74
|
+
if (!allowed(url)) throw navBlocked(url, hostOf(url));
|
|
75
|
+
},
|
|
76
|
+
/** A top-level document request was refused. ctx = tab/context it belongs to. */
|
|
77
|
+
record(url, ctx) {
|
|
78
|
+
const host = hostOf(url);
|
|
79
|
+
gotoBlocks.push({ url, host, ctx });
|
|
80
|
+
const hosts = noted.get(ctx) ?? new Set();
|
|
81
|
+
noted.set(ctx, hosts.add(host));
|
|
82
|
+
},
|
|
83
|
+
/** Call right before a goto navigates; drops that tab's pending notes too. */
|
|
84
|
+
startGoto(ctx) { gotoBlocks = []; noted.delete(ctx); },
|
|
85
|
+
/**
|
|
86
|
+
* The block that hit this goto's own tab (a popup's block is not the
|
|
87
|
+
* goto's), consumed; it is reported as NAV_BLOCKED, so no snapshot note.
|
|
88
|
+
*/
|
|
89
|
+
takeGotoBlock(ctx) {
|
|
90
|
+
const b = gotoBlocks.find((x) => x.ctx === ctx);
|
|
91
|
+
if (!b) return null;
|
|
92
|
+
gotoBlocks = gotoBlocks.filter((x) => x !== b);
|
|
93
|
+
noted.get(ctx)?.delete(b.host);
|
|
94
|
+
return { url: b.url, host: b.host };
|
|
95
|
+
},
|
|
96
|
+
/** Snapshot lines for this tab's in-page blocked jumps since the last call. */
|
|
97
|
+
takeNotes(ctx) {
|
|
98
|
+
const out = [...(noted.get(ctx) ?? [])].map((h) => `[blocked navigation to ${h}]\n`).join('');
|
|
99
|
+
noted.delete(ctx);
|
|
100
|
+
return out;
|
|
101
|
+
},
|
|
102
|
+
};
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/** @typedef {ReturnType<typeof createSiteLock>} SiteLock */
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* Chromium: lock every page target of this browser. A BROWSER-level
|
|
109
|
+
* Fetch.enable (root client, no sessionId) pauses document requests of every
|
|
110
|
+
* target, popups included, so one handler covers tabs we create later and
|
|
111
|
+
* windows the page opens itself. A request is top-level when its frameId is a
|
|
112
|
+
* page target id (OOPIF iframes are 'iframe' targets, subframes share their
|
|
113
|
+
* parent's id space). 'Aborted' (not BlockedByClient) fails the request but
|
|
114
|
+
* keeps the old page instead of swapping in a chrome-error:// page.
|
|
115
|
+
* Call once per CDP connection, before the first navigation.
|
|
116
|
+
* @param {object} cdp - root CDP client
|
|
117
|
+
* @param {SiteLock} lock
|
|
118
|
+
*/
|
|
119
|
+
export async function applySiteLockCDP(cdp, lock) {
|
|
120
|
+
const pageTargets = new Set();
|
|
121
|
+
const subframes = new Set(); // ids a refresh proved are not page targets
|
|
122
|
+
cdp.on('Target.targetCreated', ({ targetInfo }) => {
|
|
123
|
+
if (targetInfo.type === 'page') pageTargets.add(targetInfo.targetId);
|
|
124
|
+
});
|
|
125
|
+
cdp.on('Target.targetDestroyed', ({ targetId }) => pageTargets.delete(targetId));
|
|
126
|
+
await cdp.send('Target.setDiscoverTargets', { discover: true });
|
|
127
|
+
|
|
128
|
+
cdp.on('Fetch.requestPaused', async (p, sessionId) => {
|
|
129
|
+
// A popup's create event can lag its first request: ask the browser
|
|
130
|
+
// before treating an unknown frame as a subframe (and if that fails,
|
|
131
|
+
// fail closed: treat it as top-level).
|
|
132
|
+
if (!pageTargets.has(p.frameId) && !subframes.has(p.frameId)) {
|
|
133
|
+
try {
|
|
134
|
+
const { targetInfos } = await cdp.send('Target.getTargets');
|
|
135
|
+
for (const t of targetInfos) if (t.type === 'page') pageTargets.add(t.targetId);
|
|
136
|
+
if (!pageTargets.has(p.frameId)) subframes.add(p.frameId);
|
|
137
|
+
} catch { pageTargets.add(p.frameId); }
|
|
138
|
+
}
|
|
139
|
+
const ok = !pageTargets.has(p.frameId) || lock.allowed(p.request.url);
|
|
140
|
+
if (!ok) lock.record(p.request.url, p.frameId);
|
|
141
|
+
try {
|
|
142
|
+
if (ok) await cdp.send('Fetch.continueRequest', { requestId: p.requestId }, sessionId);
|
|
143
|
+
else await cdp.send('Fetch.failRequest', { requestId: p.requestId, errorReason: 'Aborted' }, sessionId);
|
|
144
|
+
} catch { /* target closed between the pause and our reply */ }
|
|
145
|
+
});
|
|
146
|
+
await cdp.send('Fetch.enable', { patterns: [{ resourceType: 'Document', requestStage: 'Request' }] });
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
/**
|
|
150
|
+
* Firefox/BiDi: build the "is this paused request a locked top-level load?"
|
|
151
|
+
* check that blocklist-firefox.js's single intercept handler calls (two
|
|
152
|
+
* catch-all handlers on one paused request would race — one continues before
|
|
153
|
+
* the other fails). A request is a top-level document load when it carries a
|
|
154
|
+
* navigation id and its context has no parent. Context ids are tracked from
|
|
155
|
+
* contextCreated and refreshed from getTree when an unknown one shows up, so a
|
|
156
|
+
* popup whose create event lags its first request can't slip through; one that
|
|
157
|
+
* is still unknown after the refresh is treated as top-level (fail closed).
|
|
158
|
+
* Redirect hops arrive as their own beforeRequestSent, so each is checked.
|
|
159
|
+
* @param {object} bidi - BiDi client
|
|
160
|
+
* @param {SiteLock} lock
|
|
161
|
+
* @returns {Promise<(e: object) => Promise<boolean>>} true = fail this request
|
|
162
|
+
*/
|
|
163
|
+
export async function createFirefoxLockCheck(bidi, lock) {
|
|
164
|
+
const tops = new Set();
|
|
165
|
+
const known = new Set();
|
|
166
|
+
async function refresh() {
|
|
167
|
+
const { contexts } = await bidi.send('browsingContext.getTree', {});
|
|
168
|
+
(function walk(nodes, top) {
|
|
169
|
+
for (const n of nodes) { known.add(n.context); if (top) tops.add(n.context); walk(n.children || [], false); }
|
|
170
|
+
})(contexts, true);
|
|
171
|
+
}
|
|
172
|
+
bidi.on('browsingContext.contextCreated', (c) => { known.add(c.context); if (!c.parent) tops.add(c.context); });
|
|
173
|
+
bidi.on('browsingContext.contextDestroyed', (c) => { known.delete(c.context); tops.delete(c.context); });
|
|
174
|
+
await bidi.subscribe(['browsingContext.contextCreated', 'browsingContext.contextDestroyed']);
|
|
175
|
+
await refresh();
|
|
176
|
+
return async (e) => {
|
|
177
|
+
if (e.navigation == null) return false; // subresource
|
|
178
|
+
if (!known.has(e.context)) { try { await refresh(); } catch { tops.add(e.context); } }
|
|
179
|
+
if (known.has(e.context) && !tops.has(e.context)) return false; // iframe
|
|
180
|
+
if (lock.allowed(e.request.url)) return false;
|
|
181
|
+
lock.record(e.request.url, e.context);
|
|
182
|
+
return true;
|
|
183
|
+
};
|
|
184
|
+
}
|
|
@@ -7,9 +7,10 @@
|
|
|
7
7
|
* @param {boolean} [pageOpts.blockAds] - false disables the default list.
|
|
8
8
|
* @param {string[]} [pageOpts.blockUrls] - extra CDP-format globs; extend the
|
|
9
9
|
* default unless blockAds is false, in which case they're the whole list.
|
|
10
|
+
* @param {import('./site-lock.js').SiteLock|null} [lock] - Site lock to enforce in the same handler.
|
|
10
11
|
* @returns {Promise<void>}
|
|
11
12
|
*/
|
|
12
13
|
export function applyFirefoxBlocklist(bidi: object, pageOpts?: {
|
|
13
14
|
blockAds?: boolean | undefined;
|
|
14
15
|
blockUrls?: string[] | undefined;
|
|
15
|
-
}): Promise<void>;
|
|
16
|
+
}, lock?: import("./site-lock.js").SiteLock | null): Promise<void>;
|
package/types/firefox-page.d.ts
CHANGED
|
@@ -6,6 +6,7 @@
|
|
|
6
6
|
* @param {boolean} [opts.links=false] - Default for snapshot({ links }): show link URLs.
|
|
7
7
|
* @param {{allowLocalUrls?: boolean, blockPrivateNetwork?: boolean}} [opts.urlGuard] - Navigation safety policy, applied on every goto().
|
|
8
8
|
* @param {string} [opts.uploadDir] - When set, upload() rejects files outside this dir.
|
|
9
|
+
* @param {?import('./site-lock.js').SiteLock} [opts.siteLock] - Site lock (allowHosts) state; the request-level enforcement is installed by applyFirefoxBlocklist, this side maps it to NAV_BLOCKED and snapshot notes.
|
|
9
10
|
* @param {boolean} [opts.incognito=false] - Clean session: injectCookies() is a no-op.
|
|
10
11
|
* @param {boolean} [opts.consent=true] - Auto-dismiss cookie consent dialogs after goto().
|
|
11
12
|
* @param {boolean} [opts.hybrid=false] - Relaunch headed on a bot-challenge page and retry.
|
|
@@ -20,6 +21,17 @@ export function createFirefoxPage(bidi: object, opts?: {
|
|
|
20
21
|
blockPrivateNetwork?: boolean;
|
|
21
22
|
} | undefined;
|
|
22
23
|
uploadDir?: string | undefined;
|
|
24
|
+
siteLock?: {
|
|
25
|
+
allowed: (url: string) => boolean;
|
|
26
|
+
assertAllowed(url: string): void;
|
|
27
|
+
record(url: any, ctx: any): void;
|
|
28
|
+
startGoto(ctx: any): void;
|
|
29
|
+
takeGotoBlock(ctx: any): {
|
|
30
|
+
url: string;
|
|
31
|
+
host: string;
|
|
32
|
+
} | null;
|
|
33
|
+
takeNotes(ctx: any): string;
|
|
34
|
+
} | null | undefined;
|
|
23
35
|
incognito?: boolean | undefined;
|
|
24
36
|
consent?: boolean | undefined;
|
|
25
37
|
hybrid?: boolean | undefined;
|
package/types/index.d.ts
CHANGED
|
@@ -27,6 +27,9 @@
|
|
|
27
27
|
* @param {boolean} [opts.consent=true] - Auto-dismiss cookie consent dialogs.
|
|
28
28
|
* @param {'act'|'browse'|'navigate'|'full'|'read'|'data'} [opts.pruneMode='act'] - Pruning mode.
|
|
29
29
|
* @param {boolean} [opts.links=false] - Show link URLs: `link "name" <url> [ref=N]`.
|
|
30
|
+
* @param {string[]} [opts.allowHosts] - Site lock: top-level navigations (the URL, its
|
|
31
|
+
* redirects) to hosts outside this list reject with NAV_BLOCKED. Entries are `host`
|
|
32
|
+
* or `*.host` (strict subdomains). Subresources and iframes are not locked.
|
|
30
33
|
* @returns {Promise<string>} ARIA snapshot text
|
|
31
34
|
*/
|
|
32
35
|
export function browse(url: string, opts?: {
|
|
@@ -50,6 +53,7 @@ export function browse(url: string, opts?: {
|
|
|
50
53
|
consent?: boolean | undefined;
|
|
51
54
|
pruneMode?: "data" | "act" | "browse" | "navigate" | "full" | "read" | undefined;
|
|
52
55
|
links?: boolean | undefined;
|
|
56
|
+
allowHosts?: string[] | undefined;
|
|
53
57
|
}): Promise<string>;
|
|
54
58
|
/**
|
|
55
59
|
* Decide which engine connect() should use. Pure — the caller passes lazy
|
package/types/navigation.d.ts
CHANGED
|
@@ -21,6 +21,18 @@ export function navFailed(url: string, reason: string): Error & {
|
|
|
21
21
|
code: "NAV_FAILED";
|
|
22
22
|
reason: string;
|
|
23
23
|
};
|
|
24
|
+
/**
|
|
25
|
+
* Typed error for a top-level navigation the site lock (`allowHosts`) refused:
|
|
26
|
+
* the target, or a redirect hop of it, is off the allowed list. `code` is
|
|
27
|
+
* 'NAV_BLOCKED'; `host` is the refused hostname. The page stays where it was.
|
|
28
|
+
* @param {string} url - The refused URL (the redirect target, if it was a hop).
|
|
29
|
+
* @param {string} host
|
|
30
|
+
* @returns {Error & {code: 'NAV_BLOCKED', host: string}}
|
|
31
|
+
*/
|
|
32
|
+
export function navBlocked(url: string, host: string): Error & {
|
|
33
|
+
code: "NAV_BLOCKED";
|
|
34
|
+
host: string;
|
|
35
|
+
};
|
|
24
36
|
/**
|
|
25
37
|
* True for a final HTTP status that is not 2xx (0 = unknown is not an error).
|
|
26
38
|
* @param {number|undefined} status
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Validate and normalize an allow list. Entry = `host` or `*.host`; anything
|
|
3
|
+
* else (scheme, port, path, spaces, empty, bare `*`) throws — a typo must never
|
|
4
|
+
* silently widen or drop the lock.
|
|
5
|
+
* @param {string[]} list
|
|
6
|
+
* @returns {string[]} lowercase entries
|
|
7
|
+
*/
|
|
8
|
+
export function parseAllowHosts(list: string[]): string[];
|
|
9
|
+
/**
|
|
10
|
+
* Build a URL matcher from an allow list. Non-http(s) URLs (about:, data:,
|
|
11
|
+
* blob:) are allowed; `host` matches that host exactly, `*.host` matches its
|
|
12
|
+
* strict subdomains only (not `host` itself). An unparseable URL is refused.
|
|
13
|
+
* @param {string[]} list
|
|
14
|
+
* @returns {(url: string) => boolean}
|
|
15
|
+
*/
|
|
16
|
+
export function makeHostMatcher(list: string[]): (url: string) => boolean;
|
|
17
|
+
/**
|
|
18
|
+
* The lock's shared state, one per connect()/browse() call, surviving
|
|
19
|
+
* relaunches and new tabs (each transport just keeps calling record()).
|
|
20
|
+
* @param {string[]} list
|
|
21
|
+
*/
|
|
22
|
+
export function createSiteLock(list: string[]): {
|
|
23
|
+
allowed: (url: string) => boolean;
|
|
24
|
+
/** @param {string} url @throws NAV_BLOCKED when url is off the list */
|
|
25
|
+
assertAllowed(url: string): void;
|
|
26
|
+
/** A top-level document request was refused. ctx = tab/context it belongs to. */
|
|
27
|
+
record(url: any, ctx: any): void;
|
|
28
|
+
/** Call right before a goto navigates; drops that tab's pending notes too. */
|
|
29
|
+
startGoto(ctx: any): void;
|
|
30
|
+
/**
|
|
31
|
+
* The block that hit this goto's own tab (a popup's block is not the
|
|
32
|
+
* goto's), consumed; it is reported as NAV_BLOCKED, so no snapshot note.
|
|
33
|
+
*/
|
|
34
|
+
takeGotoBlock(ctx: any): {
|
|
35
|
+
url: string;
|
|
36
|
+
host: string;
|
|
37
|
+
} | null;
|
|
38
|
+
/** Snapshot lines for this tab's in-page blocked jumps since the last call. */
|
|
39
|
+
takeNotes(ctx: any): string;
|
|
40
|
+
};
|
|
41
|
+
/** @typedef {ReturnType<typeof createSiteLock>} SiteLock */
|
|
42
|
+
/**
|
|
43
|
+
* Chromium: lock every page target of this browser. A BROWSER-level
|
|
44
|
+
* Fetch.enable (root client, no sessionId) pauses document requests of every
|
|
45
|
+
* target, popups included, so one handler covers tabs we create later and
|
|
46
|
+
* windows the page opens itself. A request is top-level when its frameId is a
|
|
47
|
+
* page target id (OOPIF iframes are 'iframe' targets, subframes share their
|
|
48
|
+
* parent's id space). 'Aborted' (not BlockedByClient) fails the request but
|
|
49
|
+
* keeps the old page instead of swapping in a chrome-error:// page.
|
|
50
|
+
* Call once per CDP connection, before the first navigation.
|
|
51
|
+
* @param {object} cdp - root CDP client
|
|
52
|
+
* @param {SiteLock} lock
|
|
53
|
+
*/
|
|
54
|
+
export function applySiteLockCDP(cdp: object, lock: SiteLock): Promise<void>;
|
|
55
|
+
/**
|
|
56
|
+
* Firefox/BiDi: build the "is this paused request a locked top-level load?"
|
|
57
|
+
* check that blocklist-firefox.js's single intercept handler calls (two
|
|
58
|
+
* catch-all handlers on one paused request would race — one continues before
|
|
59
|
+
* the other fails). A request is a top-level document load when it carries a
|
|
60
|
+
* navigation id and its context has no parent. Context ids are tracked from
|
|
61
|
+
* contextCreated and refreshed from getTree when an unknown one shows up, so a
|
|
62
|
+
* popup whose create event lags its first request can't slip through; one that
|
|
63
|
+
* is still unknown after the refresh is treated as top-level (fail closed).
|
|
64
|
+
* Redirect hops arrive as their own beforeRequestSent, so each is checked.
|
|
65
|
+
* @param {object} bidi - BiDi client
|
|
66
|
+
* @param {SiteLock} lock
|
|
67
|
+
* @returns {Promise<(e: object) => Promise<boolean>>} true = fail this request
|
|
68
|
+
*/
|
|
69
|
+
export function createFirefoxLockCheck(bidi: object, lock: SiteLock): Promise<(e: object) => Promise<boolean>>;
|
|
70
|
+
export type SiteLock = ReturnType<typeof createSiteLock>;
|