barebrowse 0.24.0 → 0.24.1

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 CHANGED
@@ -1,5 +1,24 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.24.1] - 2026-10-25
4
+
5
+ ### Fixed
6
+
7
+ - **Browsers are no longer orphaned when the launching process is hard-killed.**
8
+ `kill -9`, a process-group SIGKILL or a crash used to leave Chromium or
9
+ Firefox running forever. Chromium is now tethered to its launcher through
10
+ `--remote-debugging-pipe` (all launches), so it exits when the launcher dies.
11
+ Firefox is tethered with `setpriv --pdeathsig` on Linux when `setpriv` is
12
+ installed. Where there is no `setpriv`, on non-Linux systems, or with Snap
13
+ Firefox (a setuid wrapper defeats the tether), a hard kill can still orphan
14
+ the browser.
15
+ - **Stale temporary directories of dead launchers are cleaned up.** At the next
16
+ launch, leftover `barebrowse-*` profile and download directories whose
17
+ launcher is gone are removed, in both `/tmp` and the system temp directory. A
18
+ directory whose browser lock is still live is kept. Profile and download
19
+ directory names now carry the launcher's pid to make this possible. A reused
20
+ pid or a changed hostname keeps a directory instead of removing it.
21
+
3
22
  ## [0.24.0] - 2026-10-23
4
23
 
5
24
  ### Added
package/README.md CHANGED
@@ -100,6 +100,8 @@ MCP tools: `browse`, `goto`, `snapshot`, `readable`, `click`, `type`, `press`, `
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
 
103
+ **Hard-kill safety (Linux).** If the process that launched a browser is `kill -9`'d or crashes, the browser dies with it: Chromium via a `--remote-debugging-pipe` tether, Firefox via `setpriv --pdeathsig` (needs `setpriv` from util-linux; without it, or off Linux, a hard kill still orphans Firefox, as does a Snap Firefox). The dead launcher's leftover `barebrowse-*` temp dirs are cleaned at the next launch. Known limits: a reused pid keeps its dir, and dirs created under a different hostname are never removed.
104
+
103
105
  `browse` and `snapshot` accept `pruneMode: 'act'|'read'`. `act` (default) keeps interactive elements — best for clicking/filling. `read` keeps paragraphs, headings, and long text — best for articles, docs, and content extraction. If act-mode collapses a content-heavy page near-totally, the snapshot includes a `hint: …` line suggesting `pruneMode='read'` so the agent doesn't bail to a separate HTTP fetch.
104
106
 
105
107
  `npx barebrowse doctor` reports the runtime environment first — default engine/mode, installed Chromium/Firefox binaries, cookie sources, and any live session's engine + capabilities — then scans every known MCP config location and flags scope conflicts. `npx barebrowse install --force` overwrites an existing entry pointing at a different endpoint.
@@ -105,7 +105,7 @@ const snapshot = await browse('https://example.com', {
105
105
  - `viewport: '1280x720'` — Set viewport dimensions
106
106
  - `storageState: 'file.json'` — Load cookies/localStorage from saved state
107
107
  - `incognito: true|false` — Default `false`. When `true`, run a clean, unauthenticated session: skips `storageState` loading AND makes `injectCookies()` a no-op, so no auth ever enters the session even though callers (MCP `goto`, daemon) inject unconditionally. The temp profile is already throwaway; this gates the *other* auth source — the user's real browser cookies. Not Chrome's `--incognito` flag. Surfaced everywhere: library, MCP (`browse` tool param + `BAREBROWSE_INCOGNITO=1` env for the session), CLI (`--incognito`), bareagent (via `connect` opts).
108
- - `downloadPath: '/abs/dir'` — Where downloads land. Default: per-session `mkdtemp` under `/tmp/barebrowse-dl-*` that gets removed on `close()`. Caller-supplied paths are not cleaned up — caller owns the lifecycle.
108
+ - `downloadPath: '/abs/dir'` — Where downloads land. Default: per-session `mkdtemp` under `os.tmpdir()` named `barebrowse-dl-<pid>-*` (Firefox: `barebrowse-ff-dl-<pid>-*`) that gets removed on `close()`, or by the next launch's stale-dir sweep if the process was hard-killed. Caller-supplied paths are not cleaned up — caller owns the lifecycle.
109
109
  - `blockAds: true|false` — CDP-level URL blocking of 128 common ad/tracker patterns (Google ads/analytics, FB/Amazon/MS/Adobe ad+analytics, Segment/Amplitude/Mixpanel/Heap/PostHog, Hotjar/FullStory/LogRocket, Criteo/Taboola/Outbrain, the consumer-pixel cluster, AppNexus/Rubicon/PubMatic supply, marketing automation; v0.10.1 added AppsFlyer/Branch/Adjust, Cloudflare Web Analytics, Matomo Cloud). Default `true` for launched browsers, `false` in attach mode (would affect any tab in the user's running browser). Explicit `true` in attach mode is honored and follows the session across `switchTab()` (regression-tested). Shrinks ARIA snapshots and speeds page loads. On legacy Chromium lacking `Network.setBlockedURLs` a one-time `console.warn` surfaces the fallback.
110
110
  - `blockUrls: ['*://foo.com/*', ...]` — Extra glob patterns (CDP `Network.setBlockedURLs` format) to block in addition to the default. Merged with the default unless `blockAds: false`.
111
111
  - `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.
@@ -206,8 +206,8 @@ barebrowse can inject cookies from the user's real browser sessions, bypassing l
206
206
  | Stealth (headless tells) | v0.9.0 (H4): `Network.setUserAgentOverride` strips "HeadlessChrome" from UA in HTTP headers AND `navigator.userAgent`; JS patches for webdriver, plugins, languages, full `chrome.runtime` enum shape, `Notification` constructor + `permission: 'default'`, `hardwareConcurrency: 8`, `deviceMemory: 8`, WebGL `UNMASKED_VENDOR_WEBGL`/`UNMASKED_RENDERER_WEBGL` spoofed to Intel. v0.10.0: canvas fingerprint noise — `toDataURL`/`getImageData` XOR a per-session `crypto.getRandomValues`-seeded mask into ~1 byte per 64-byte stride (stable within a session, different across sessions; bitmap is restored after encoding so legitimate canvas use is unaffected). | Headless |
207
207
  | Ad / tracker URL blocking | v0.10.0: CDP `Network.setBlockedURLs` with 128 curated patterns (Google/FB/Amazon/MS/Adobe ad+analytics, the major SaaS analytics + session-replay stacks, content-rec, supply-side ad networks, marketing automation). v0.10.1 added long-tail: AppsFlyer/Branch/Adjust, Cloudflare Web Analytics, Matomo Cloud, broader Outbrain (`amplify`/`log`) and PostHog (`/static/array.js`). Default on for launched browsers, off in attach mode. `opts.blockUrls` extends; `opts.blockAds: false` disables. Shrinks ARIA snapshots and speeds loads. v0.10.1: regression-tested across `switchTab()` in attach mode; one-time `console.warn` if Chromium lacks the CDP method. | Launched |
208
208
  | iframe / OOPIF content (Stripe, reCAPTCHA, embedded forms) | v0.9.0 (H2): `Target.setAutoAttach({flatten:true})` registers a CDP session per iframe; `ariaTree()` walks `Page.getFrameTree`, fetches each frame's AX tree on the right session, splices children under iframe placeholders via `DOM.getFrameOwner`. Refs route via `{session, backendNodeId}` so clicks dispatch in the iframe's Input domain. `--site-per-process` launch flag forces every iframe — including same-origin — into OOPIF so coords work. | Both |
209
- | Downloads | v0.9.0 (H7): `Browser.setDownloadBehavior({behavior:'allowAndName', downloadPath, eventsEnabled:true})` + listeners populate `page.downloads`. Files land at `savedPath` (under `--download-path` if supplied, else per-session `/tmp/barebrowse-dl-*`). | Headless + Headed (skipped in attach mode) |
210
- | Profile locking | Unique temp dir per headless instance. A launch that fails (start timeout, early exit, bad endpoint — both engines) SIGKILLs the browser's whole process group and removes that temp dir before rejecting | Headless |
209
+ | Downloads | v0.9.0 (H7): `Browser.setDownloadBehavior({behavior:'allowAndName', downloadPath, eventsEnabled:true})` + listeners populate `page.downloads`. Files land at `savedPath` (under `--download-path` if supplied, else per-session `barebrowse-dl-<pid>-*` under `os.tmpdir()`). | Headless + Headed (skipped in attach mode) |
210
+ | Profile locking | Unique temp dir per headless instance. A launch that fails (start timeout, early exit, bad endpoint — both engines) SIGKILLs the browser's whole process group and removes that temp dir before rejecting. **Hard-kill safety (Linux):** if the launcher itself is `kill -9`'d or crashes (no exit handler can run), the browser still dies with it: Chromium is spawned with `--remote-debugging-pipe` and stdio fds 3/4 as a parent-death tether (the kernel closes the pipe, Chromium exits with its helpers); Firefox is spawned through `setpriv --pdeathsig SIGKILL` when `setpriv` exists (Linux only; without it, or off Linux, a hard kill still orphans Firefox). The dead launcher's leftover `barebrowse-*` temp dirs (Chromium profile, Firefox profile, download dirs, all named with the owner pid) are removed by the next launch's sweep, which keeps any dir whose owner pid or browser lock is still live. Known limits: a reused pid keeps its dir; a dir whose Chromium lock names a different hostname (renamed machine, container sharing `/tmp`) is kept forever; a Snap Firefox (its setuid wrapper clears pdeathsig) can still be orphaned, though its profile is kept while it runs | Headless |
211
211
  | Shared memory crash (Linux) | `--disable-dev-shm-usage` flag prevents `/dev/shm` exhaustion | Headless |
212
212
  | ARIA noise | 9-step pruning: wrapper collapse, noise removal, landmark promotion | Both |
213
213
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "barebrowse",
3
- "version": "0.24.0",
3
+ "version": "0.24.1",
4
4
  "description": "Authenticated web browsing for autonomous agents via CDP. URL in, pruned ARIA snapshot out.",
5
5
  "repository": {
6
6
  "type": "git",
package/src/chromium.js CHANGED
@@ -6,7 +6,8 @@
6
6
  */
7
7
 
8
8
  import { execFileSync, spawn } from 'node:child_process';
9
- import { existsSync, rmSync } from 'node:fs';
9
+ import { existsSync, rmSync, readdirSync, readlinkSync } from 'node:fs';
10
+ import { tmpdir, hostname } from 'node:os';
10
11
 
11
12
  /** Block the current thread for `ms` without spawning a process. */
12
13
  function sleepSync(ms) {
@@ -121,6 +122,7 @@ export async function launch(opts = {}) {
121
122
 
122
123
  const args = [
123
124
  `--remote-debugging-port=${port}`,
125
+ '--remote-debugging-pipe',
124
126
  '--no-first-run',
125
127
  '--no-default-browser-check',
126
128
  '--disable-background-networking',
@@ -156,6 +158,7 @@ export async function launch(opts = {}) {
156
158
  if (opts.userDataDir) {
157
159
  args.push(`--user-data-dir=${opts.userDataDir}`);
158
160
  } else {
161
+ sweepStaleProfiles();
159
162
  ownedProfileDir = `/tmp/barebrowse-${process.pid}-${Date.now()}`;
160
163
  args.push(`--user-data-dir=${ownedProfileDir}`);
161
164
  }
@@ -176,10 +179,19 @@ export async function launch(opts = {}) {
176
179
  // directly. The SIGINT handler in registerExitHandlers() that calls
177
180
  // reapAllSync() is what actually kills Chromium under Ctrl-C now. Do not
178
181
  // remove that handler without restoring some other path to reap children.
182
+ //
183
+ // Parent-death tether: --remote-debugging-pipe makes Chromium read CDP from
184
+ // fd 3 and write to fd 4. We never use them (CDP still goes over the ws
185
+ // port) — they exist so that when this Node process dies by SIGKILL/crash,
186
+ // where no exit handler can run, the kernel closes our end, Chromium reads
187
+ // EOF and exits itself, helpers included. Without it the browser is
188
+ // orphaned to init with its profile dir. Nothing may write to these fds.
179
189
  const child = spawn(binary, args, {
180
- stdio: ['ignore', 'pipe', 'pipe'],
190
+ stdio: ['ignore', 'pipe', 'pipe', 'pipe', 'pipe'],
181
191
  detached: true,
182
192
  });
193
+ // Drop our ends once Chromium is gone so they can't hold the event loop.
194
+ child.once('exit', () => { child.stdio[3]?.destroy(); child.stdio[4]?.destroy(); });
183
195
 
184
196
  // Not in activeBrowsers yet, so nothing else would reap it: any failure
185
197
  // before registration (start timeout, spawn error, early exit, bad URL)
@@ -194,7 +206,7 @@ export async function launch(opts = {}) {
194
206
  reject(new Error(`Browser failed to start within 10s. stderr: ${stderr}`));
195
207
  }, 10000);
196
208
 
197
- child.stderr.on('data', (chunk) => {
209
+ child.stderr?.on('data', (chunk) => {
198
210
  stderr += chunk.toString();
199
211
  const match = stderr.match(/ws:\/\/[^\s]+/);
200
212
  if (match) {
@@ -234,6 +246,53 @@ export async function launch(opts = {}) {
234
246
  return browser;
235
247
  }
236
248
 
249
+ /**
250
+ * True when a profile dir's browser lock says a browser may still be using it: the
251
+ * lock's pid is alive, or (Chromium) it names another host (shared dir, can't judge).
252
+ * Chromium: SingletonLock -> '<hostname>-<pid>'; Firefox: lock -> '<ip>:+<pid>'.
253
+ * Download dirs have no lock.
254
+ */
255
+ function browserStillUsing(path, host) {
256
+ for (const f of ['SingletonLock', 'lock']) {
257
+ let t;
258
+ try { t = readlinkSync(`${path}/${f}`); } catch { continue; }
259
+ const m = f === 'lock' ? /:\+?(\d+)$/.exec(t) : /^(.*)-(\d+)$/.exec(t);
260
+ if (!m) continue;
261
+ if (f !== 'lock' && m[1] !== host) return true;
262
+ try { process.kill(Number(m.at(-1)), 0); return true; } catch (err) { if (err.code !== 'ESRCH') return true; }
263
+ }
264
+ return false;
265
+ }
266
+
267
+ /**
268
+ * Remove profile dirs left by launchers that were hard-killed (the pipe tether
269
+ * kills their Chromium but cannot delete the dir). Matches exactly
270
+ * barebrowse-<pid>-<ms> (Chromium) or barebrowse-ff-<pid>-<6 random chars>
271
+ * (Firefox), or the dl-/ff-dl- download-dir forms of those, and removes it only when that pid is dead (EPERM means alive), and only if no browser lock in it names a live pid or a foreign host.
272
+ * Dirs only, never processes; old pid-less dirs are never matched. Known limit: a reused pid keeps its dir.
273
+ * Foreign-host rule: if the hostname changed (renamed machine, container with a random hostname sharing /tmp), a dead launcher's dir is kept forever, a deliberate leak-over-delete tradeoff.
274
+ * With no argument sweeps both '/tmp' (Chromium profiles) and tmpdir() (download
275
+ * dirs, Firefox profiles); they differ when TMPDIR is set.
276
+ * @param {string} [dir]
277
+ * @param {string} [host] hostname a Chromium lock must name to be judged by its pid (default: this machine's; injectable for tests)
278
+ */
279
+ export function sweepStaleProfiles(dir, host = hostname()) {
280
+ if (dir === undefined) {
281
+ for (const d of new Set(['/tmp', tmpdir()])) sweepStaleProfiles(d, host);
282
+ return;
283
+ }
284
+ let names = [];
285
+ try { names = readdirSync(dir); } catch {}
286
+ for (const name of names) {
287
+ const m = /^barebrowse-(?:(\d+)-\d+|(?:ff-|dl-|ff-dl-)(\d+)-[A-Za-z0-9]{6})$/.exec(name);
288
+ const pid = Number(m?.[1] ?? m?.[2]);
289
+ if (!m || pid === process.pid) continue;
290
+ try { process.kill(pid, 0); continue; } catch (err) { if (err.code !== 'ESRCH') continue; }
291
+ if (browserStillUsing(`${dir}/${name}`, host)) continue;
292
+ try { rmSync(`${dir}/${name}`, { recursive: true, force: true }); } catch {}
293
+ }
294
+ }
295
+
237
296
  /**
238
297
  * Kill a launched browser and remove its temp profile dir (if we created one).
239
298
  * Waits up to 2s for the process to actually exit before unlinking the dir —
package/src/firefox.js CHANGED
@@ -15,9 +15,10 @@
15
15
  */
16
16
 
17
17
  import { execFileSync, spawn } from 'node:child_process';
18
- import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
18
+ import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
19
19
  import { tmpdir } from 'node:os';
20
20
  import { join } from 'node:path';
21
+ import { sweepStaleProfiles } from './chromium.js';
21
22
 
22
23
  /** Block the current thread for `ms` (sync, for the 'exit' reaper). */
23
24
  function sleepSync(ms) {
@@ -55,6 +56,8 @@ function registerExitHandlers() {
55
56
  }
56
57
  }
57
58
 
59
+ const SETPRIV = ['/usr/bin/setpriv', '/bin/setpriv'];
60
+
58
61
  const CANDIDATES = [
59
62
  'firefox',
60
63
  'firefox-esr',
@@ -103,7 +106,9 @@ export function findFirefox() {
103
106
  export async function launchFirefox(opts = {}) {
104
107
  const binary = opts.binary || findFirefox();
105
108
  const port = opts.port || 0;
106
- const profileDir = mkdtempSync(join(tmpdir(), 'barebrowse-ff-'));
109
+ // Always our own profile: sweep dirs of hard-killed launchers, then pid-tag ours.
110
+ sweepStaleProfiles();
111
+ const profileDir = mkdtempSync(join(tmpdir(), `barebrowse-ff-${process.pid}-`));
107
112
 
108
113
  // Proxy + prompt-suppressing prefs go in user.js (read at profile load).
109
114
  const prefs = [
@@ -167,7 +172,21 @@ export async function launchFirefox(opts = {}) {
167
172
  args.push('about:blank');
168
173
 
169
174
  // detached:true → own process group, so cleanup can signal the whole tree.
170
- const child = spawn(binary, args, { stdio: ['ignore', 'pipe', 'pipe'], detached: true });
175
+ //
176
+ // Parent-death tether: Firefox has no --remote-debugging-pipe, so a SIGKILLed
177
+ // or crashed Node parent (no exit handler runs) would orphan it. On Linux we
178
+ // exec it through util-linux `setpriv --pdeathsig SIGKILL`: setpriv execs
179
+ // Firefox (child.pid stays Firefox's pid) and the kernel SIGKILLs it when this
180
+ // process dies; its children follow. Without setpriv (or off Linux) we spawn
181
+ // exactly as before and a hard kill still orphans it.
182
+ // A setuid wrapper (e.g. Snap's snap-confine) clears pdeathsig on exec, so a Snap
183
+ // Firefox can still be orphaned even with setpriv; the stale-profile sweep keeps
184
+ // its profile dir while it runs (it checks the browser lock).
185
+ const setpriv = process.platform === 'linux' && SETPRIV.find(existsSync);
186
+ const child = spawn(setpriv || binary, setpriv ? ['--pdeathsig', 'SIGKILL', binary, ...args] : args, {
187
+ stdio: ['ignore', 'pipe', 'pipe'],
188
+ detached: true,
189
+ });
171
190
 
172
191
  // Not in activeBrowsers yet, so nothing else would reap it: any failure
173
192
  // before registration must kill the process group and remove the profile.
package/src/index.js CHANGED
@@ -397,7 +397,7 @@ export async function connect(opts = {}) {
397
397
  if (!downloadPath) {
398
398
  const { mkdtempSync } = await import('node:fs');
399
399
  const { tmpdir } = await import('node:os');
400
- ownedDownloadDir = mkdtempSync(pathJoin(tmpdir(), 'barebrowse-dl-'));
400
+ ownedDownloadDir = mkdtempSync(pathJoin(tmpdir(), `barebrowse-dl-${process.pid}-`));
401
401
  downloadPath = ownedDownloadDir;
402
402
  }
403
403
  // Register listeners BEFORE sending setDownloadBehavior so no
@@ -888,7 +888,7 @@ async function connectFirefox(opts) {
888
888
  if (!downloadDir) {
889
889
  const { mkdtempSync } = await import('node:fs');
890
890
  const { tmpdir } = await import('node:os');
891
- ownedDownloadDir = mkdtempSync(pathJoin(tmpdir(), 'barebrowse-ff-dl-'));
891
+ ownedDownloadDir = mkdtempSync(pathJoin(tmpdir(), `barebrowse-ff-dl-${process.pid}-`));
892
892
  downloadDir = ownedDownloadDir;
893
893
  }
894
894
 
@@ -25,6 +25,19 @@ export function launch(opts?: {
25
25
  process: import("node:child_process").ChildProcess;
26
26
  port: number;
27
27
  }>;
28
+ /**
29
+ * Remove profile dirs left by launchers that were hard-killed (the pipe tether
30
+ * kills their Chromium but cannot delete the dir). Matches exactly
31
+ * barebrowse-<pid>-<ms> (Chromium) or barebrowse-ff-<pid>-<6 random chars>
32
+ * (Firefox), or the dl-/ff-dl- download-dir forms of those, and removes it only when that pid is dead (EPERM means alive), and only if no browser lock in it names a live pid or a foreign host.
33
+ * Dirs only, never processes; old pid-less dirs are never matched. Known limit: a reused pid keeps its dir.
34
+ * Foreign-host rule: if the hostname changed (renamed machine, container with a random hostname sharing /tmp), a dead launcher's dir is kept forever, a deliberate leak-over-delete tradeoff.
35
+ * With no argument sweeps both '/tmp' (Chromium profiles) and tmpdir() (download
36
+ * dirs, Firefox profiles); they differ when TMPDIR is set.
37
+ * @param {string} [dir]
38
+ * @param {string} [host] hostname a Chromium lock must name to be judged by its pid (default: this machine's; injectable for tests)
39
+ */
40
+ export function sweepStaleProfiles(dir?: string, host?: string): void;
28
41
  /**
29
42
  * Kill a launched browser and remove its temp profile dir (if we created one).
30
43
  * Waits up to 2s for the process to actually exit before unlinking the dir —