barebrowse 0.10.1 → 0.11.0

package/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to npm
+
+# Trusted publishing via OIDC — no NPM_TOKEN needed.
+# Configure the trusted publisher at npmjs.com first (see repo notes).
+on:
+  workflow_dispatch:        # manual "Run workflow" button
+  release:
+    types: [published]      # also publishes when you cut a GitHub release
+
+permissions:
+  contents: read
+  id-token: write           # required: lets npm mint OIDC credentials
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: 'https://registry.npmjs.org'
+      - name: Upgrade npm (trusted publishing needs >= 11.5.1)
+        run: npm install -g npm@latest
+      - name: Publish
+        run: npm publish

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## 0.11.0
+
+### Security hardening — audit findings fixed, safe-by-default
+
+A full security audit of the library + CLI daemon + MCP server. Eight
+findings were reproduced with live PoCs, fixed, and locked in with 14 new
+regression tests (143 → 157 passing). Two new opt-in controls; two new
+defaults that change behavior (see **Breaking** below).
+
+- **Daemon authentication (was: unauthenticated `eval` over loopback).**
+  The CLI daemon's HTTP server bound to `127.0.0.1` but had no auth — and
+  loopback is shared across local users, so any local process could POST
+  `/command` (including `eval` = arbitrary JS in the authenticated browser).
+  Now every daemon mints a 32-byte random token at startup, written into
+  `session.json` (mode `0600`) and required on `/command` via the
+  `x-barebrowse-token` header (constant-time compare). `session-client.js`
+  reads and sends it transparently — no caller change. `GET /status` stays
+  open as a liveness ping returning only `{ ok, pid }`.
+- **Artifact permissions.** The session dir is now created `0700` and all
+  daemon artifacts (`session.json`, snapshots, screenshots, PDFs, console /
+  network / dialog logs) plus `page.saveState()` output are written `0600`.
+  `saveState` holds cookies + localStorage (session tokens), so this stops a
+  multi-user host from reading another user's credentials off disk.
+- **Navigation scheme guard (new module `src/url-guard.js`).** `goto()` /
+  `browse()` now reject local-resource and browser-internal schemes
+  (`file:`, `view-source:`, `chrome:`, `chrome-extension:`, `filesystem:`,
+  `devtools:`, …) by default — closing a confirmed local-file-read /
+  directory-listing vector for a prompt-injected agent. `http`/`https`/
+  `data`/`blob`/`about` stay allowed (`data:` is opaque-origin and the
+  test-fixture mechanism — not a read/SSRF vector). Override with
+  `{ allowLocalUrls: true }`.
+- **SSRF guard (opt-in `blockPrivateNetwork`).** When set, `goto()`/
+  `browse()` refuse loopback / RFC-1918 / link-local / cloud-metadata
+  (`169.254.169.254`) / `*.internal` hosts. Off by default so localhost
+  dev-server browsing keeps working. Exposed as `--block-private-network`.
+- **Upload sandbox (opt-in `uploadDir`).** `upload()` confirmed it would
+  attach any absolute path to a file input (exfil vector under prompt
+  injection). When `uploadDir` is set, every path must resolve (symlinks
+  included, via `realpath`) inside it. Default unrestricted — nothing breaks
+  unless you opt in. Exposed as `--upload-dir=DIR`. Both new opts pass
+  through `connect()` → MCP / bareagent / CLI daemon uniformly.
+- **Cookie injection scoped precisely (was: over-broad substring match).**
+  `authenticate()` matched `host_key LIKE '%domain%'`, so browsing
+  `apple.com` injected cookies for `apple.com.evil.org` / `notapple.com`,
+  and `mybank.co.uk` (→ `co.uk`) pulled every `*.co.uk` cookie. The LIKE
+  query is now only a coarse pre-filter; a precise RFC-6265
+  `cookieDomainMatch()` decides what actually gets injected (parent-domain
+  cookies like `.google.com` still apply to `mail.google.com`).
+- **Hardening:** browser discovery uses `execFileSync('which', [name])`
+  (no shell) instead of an interpolated `execSync` string; the cleanup
+  busy-wait drops a `sleep` subprocess for `Atomics.wait`. Added
+  `.gitignore` (was missing — `.barebrowse/` state/snapshots could be
+  accidentally committed). Pinned `wearehere` to exact `1.0.0`.
+- **Tests:** 157 total (14 new) — `test/unit/url-guard.test.js` (19
+  assertions over scheme/private-host policy), `cookieDomainMatch` cases in
+  `test/unit/auth.test.js`, daemon token + `0600` perms in
+  `test/integration/cli.test.js`.
+
+**Breaking:** (1) `file:`/`chrome:`/etc. navigation now throws by default —
+pass `allowLocalUrls: true` to restore. (2) The CLI daemon now requires the
+token; this is transparent via the bundled `session-client`, but any
+third-party client hitting the daemon's HTTP API directly must send
+`x-barebrowse-token` from `session.json`.
+
 ## 0.10.1
 
 ### Blocklist long-tail additions + legacy-Chrome warn + switchTab attach-mode test

package/README.md

@@ -134,6 +134,17 @@ No clone profile, no fresh cookies — the agent sees what you see.
 
 Cookie consent walls (29 languages, with real mouse click fallback for stubborn CMPs), login walls (cookie extraction from your browsers), bot detection (ARIA node count heuristic + stealth patches + automatic headed fallback — snapshot shows `[BOT CHALLENGE DETECTED]` warning when blocked), permission prompts, SPA navigation, JS dialogs, off-screen elements, pre-filled inputs, ARIA noise, and profile locking. The agent doesn't think about any of it.
 
+## Safe by default (v0.11.0)
+
+barebrowse hands an autonomous — and therefore prompt-injectable — agent an *authenticated* browser, so the defaults are calibrated for that threat:
+
+- **Local-resource schemes blocked.** `file:`, `view-source:`, `chrome:`, etc. are rejected by default (a confirmed local-file-read vector); `http`/`https`/`data` stay allowed. Override with `allowLocalUrls: true`.
+- **Cookie injection scoped** to a precise RFC-6265 domain match — browsing one site can't pull look-alike or unrelated cookies into the session.
+- **CLI daemon authenticated** with a per-session token (loopback alone isn't an authorization boundary); snapshots and saved state are written owner-only (`0600`).
+- **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`).
+
+See `barebrowse.context.md` and the PRD's "Security Model & Safe Defaults" for the full rationale.
+
 ## What the agent sees
 
 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

@@ -1,7 +1,7 @@
 # barebrowse -- Integration Guide
 
 > For AI assistants and developers wiring barebrowse into a project.
-> v0.9.1 | Node.js >= 22 | 0 required deps | Apache-2.0
+> v0.11.0 | Node.js >= 22 | 0 required deps | Apache-2.0
 
 ## What this is
 
@@ -95,6 +95,9 @@ const snapshot = await browse('https://example.com', {
 - `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.
 - `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.
 - `blockUrls: ['*://foo.com/*', ...]` — Extra glob patterns (CDP `Network.setBlockedURLs` format) to block in addition to the default. Merged with the default unless `blockAds: false`.
+- `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.
+- `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.
+- `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.
 
 ## Snapshot format
 
@@ -226,7 +229,7 @@ barebrowse save-state                  # → .barebrowse/state-<timestamp>.json
 barebrowse close                       # Kill daemon + browser
 ```
 
-**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`
+**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)
 
 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.
 
@@ -355,6 +358,10 @@ Useful for agent threshold decisions: "skip sites above score 40", "warn if term
 
 14. **`eval` MCP tool is opt-in.** Set `BAREBROWSE_MCP_EVAL=1` to register it. Default off because `Runtime.evaluate` in an authenticated session can read cookies/localStorage, post on the user's behalf, hit any same-origin endpoint. CLI/connect()/daemon all keep `eval` because the developer is the caller; MCP gates it because the agent acts with less judgment.
 
+15. **The CLI daemon requires a per-session token (v0.11.0).** `open` mints a 32-byte random token, writes it into `.barebrowse/session.json` (mode `0600`) and requires it on `POST /command` via the `x-barebrowse-token` header (loopback is shared across local users, so binding to `127.0.0.1` alone isn't an authorization boundary). The bundled `session-client` sends it automatically — no change for CLI users. A third-party client hitting the daemon HTTP API directly must read the token from `session.json` and send it. `GET /status` stays open (liveness only). The session dir is `0700`; snapshots, `saveState`, and logs are written `0600`.
+
+16. **Navigation is scheme-guarded by default (v0.11.0).** `file:`/`chrome:`/etc. throw unless `allowLocalUrls: true`; `blockPrivateNetwork` and `uploadDir` add opt-in SSRF and upload-sandbox controls. All four are exposed identically on the library, MCP/bareagent (via `connect` opts), and the CLI (`--block-private-network`, `--upload-dir=DIR`; the scheme guard and token are always on).
+
 ## Constraints
 
 - **Node >= 22** -- built-in WebSocket, built-in SQLite

package/cli.js

@@ -119,6 +119,8 @@ async function cmdOpen() {
     downloadPath: parseFlag('--download-path'),
     blockAds: hasFlag('--no-block-ads') ? false : undefined,
     blockUrls: parseFlagAll('--block-urls'),
+    blockPrivateNetwork: hasFlag('--block-private-network') || undefined,
+    uploadDir: parseFlag('--upload-dir') ? resolve(parseFlag('--upload-dir')) : undefined,
   };
 
   try {
@@ -222,6 +224,8 @@ async function runDaemonInternal() {
     downloadPath: parseFlag('--download-path'),
     blockAds: hasFlag('--no-block-ads') ? false : undefined,
     blockUrls: parseFlagAll('--block-urls'),
+    blockPrivateNetwork: hasFlag('--block-private-network') || undefined,
+    uploadDir: parseFlag('--upload-dir'),
   };
   const outputDir = parseFlag('--output-dir') || resolve('.barebrowse');
   const url = parseFlag('--url');
@@ -489,6 +493,10 @@ Session:
                                     Default: enabled in owned-browser modes, disabled in attach mode.
     --block-urls=PATTERN            Extra URL glob to block (repeatable, e.g. --block-urls='*://*.foo.com/*').
                                     Use the =VALUE form when the pattern could be mistaken for a flag.
+    --block-private-network         SSRF guard: refuse to navigate to loopback / RFC-1918 / link-local /
+                                    cloud-metadata hosts. Off by default so localhost browsing works.
+    --upload-dir=DIR                Sandbox uploads: reject files outside DIR (symlinks resolved).
+                                    Default: no restriction. (file:/chrome: schemes are always blocked.)
 
 Navigation:
   barebrowse goto <url>             Navigate to URL

package/commands/barebrowse/SKILL.md

@@ -39,6 +39,10 @@ All output files go to `.barebrowse/` in the current directory. Read them with t
 - `--proxy=URL` — HTTP/SOCKS proxy server
 - `--viewport=WxH` — Viewport size (e.g. 1280x720)
 - `--storage-state=FILE` — Load cookies/localStorage from JSON file
+- `--block-private-network` — SSRF guard: refuse loopback / RFC-1918 / link-local / cloud-metadata hosts (v0.11.0)
+- `--upload-dir=DIR` — Sandbox uploads to DIR; reject files outside it (v0.11.0)
+
+> 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`).
 
 ### Navigation
 

package/commands/barebrowse.md

@@ -38,6 +38,10 @@ All output files go to `.barebrowse/` in the current directory. Read them with t
 - `--proxy=URL` — HTTP/SOCKS proxy server
 - `--viewport=WxH` — Viewport size (e.g. 1280x720)
 - `--storage-state=FILE` — Load cookies/localStorage from JSON file
+- `--block-private-network` — SSRF guard: refuse loopback / RFC-1918 / link-local / cloud-metadata hosts (v0.11.0)
+- `--upload-dir=DIR` — Sandbox uploads to DIR; reject files outside it (v0.11.0)
+
+> 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`).
 
 ### Navigation
 

package/package.json

@@ -1,7 +1,13 @@
 {
   "name": "barebrowse",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Authenticated web browsing for autonomous agents via CDP. URL in, pruned ARIA snapshot out.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hamr0/barebrowse.git"
+  },
+  "homepage": "https://github.com/hamr0/barebrowse#readme",
+  "bugs": "https://github.com/hamr0/barebrowse/issues",
   "type": "module",
   "main": "src/index.js",
   "exports": {
@@ -29,7 +35,7 @@
     "headless"
   ],
   "optionalDependencies": {
-    "wearehere": "^1.0.0"
+    "wearehere": "1.0.0"
   },
   "license": "Apache-2.0"
 }

package/src/auth.js

@@ -268,6 +268,22 @@ export async function injectCookies(session, cookies) {
   }
 }
 
+/**
+ * RFC 6265 domain-match: does `host` belong to a cookie declared for
+ * `cookieDomain`? Leading dot on the cookie domain is ignored (host-only
+ * vs domain cookies are matched the same here, intentionally — we want
+ * parent-domain cookies like .google.com to apply to mail.google.com).
+ * @param {string} host - target hostname (e.g. 'mail.google.com')
+ * @param {string} cookieDomain - cookie's host_key (e.g. '.google.com')
+ * @returns {boolean}
+ */
+export function cookieDomainMatch(host, cookieDomain) {
+  const h = String(host).toLowerCase();
+  const d = String(cookieDomain).toLowerCase().replace(/^\./, '');
+  if (!d) return false;
+  return h === d || h.endsWith('.' + d);
+}
+
 /**
  * Extract cookies for a URL and inject them into a CDP session.
  * Convenience function combining extractCookies + injectCookies.
@@ -276,12 +292,18 @@ export async function injectCookies(session, cookies) {
  * @param {object} [opts] - Options passed to extractCookies
  */
 export async function authenticate(session, url, opts = {}) {
-  // Strip to registrable domain so mail.google.com → google.com
-  // This ensures parent-domain cookies (.google.com) are included
-  const hostname = new URL(url).hostname.replace(/^www\./, '');
-  const parts = hostname.split('.');
-  const domain = parts.length > 2 ? parts.slice(-2).join('.') : hostname;
-  const cookies = extractCookies({ ...opts, domain });
+  const fullHost = new URL(url).hostname.toLowerCase();
+  // Coarse SQL pre-filter: strip to a registrable-ish domain so the LIKE query
+  // returns a superset (incl. parent-domain cookies). slice(-2) is a cheap
+  // heuristic — it over-selects for multi-part eTLDs (co.uk) and as a substring
+  // match, so the precise RFC-6265 domain-match below is what actually decides
+  // which cookies get injected. Without it, browsing apple.com would inject
+  // cookies for apple.com.evil.org and every *.co.uk site (verified).
+  const noWww = fullHost.replace(/^www\./, '');
+  const parts = noWww.split('.');
+  const coarseDomain = parts.length > 2 ? parts.slice(-2).join('.') : noWww;
+  const candidates = extractCookies({ ...opts, domain: coarseDomain });
+  const cookies = candidates.filter((c) => cookieDomainMatch(fullHost, c.domain));
   if (cookies.length > 0) {
     await injectCookies(session, cookies);
   }

package/src/chromium.js

@@ -5,9 +5,14 @@
  * Modes: headless (launch new, no UI), headed (launch new, visible window).
  */
 
-import { execSync, spawn } from 'node:child_process';
+import { execFileSync, spawn } from 'node:child_process';
 import { existsSync, rmSync } from 'node:fs';
 
+/** Block the current thread for `ms` without spawning a process. */
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
 // Track launched browsers so we can clean them up if the parent crashes.
 // Registered exit handlers (one-time) iterate this set on shutdown.
 const activeBrowsers = new Set();
@@ -29,7 +34,7 @@ function reapAllSync() {
   for (const b of toReap) {
     for (let i = 0; i < 20; i++) {
       try { process.kill(b.process.pid, 0); } catch { break; }
-      try { execSync('sleep 0.05'); } catch {}
+      sleepSync(50);
     }
     if (b.ownedProfileDir) {
       try { rmSync(b.ownedProfileDir, { recursive: true, force: true }); } catch {}
@@ -84,8 +89,11 @@ export function findBrowser() {
         if (existsSync(candidate)) return candidate;
         continue;
       }
-      // Relative name — check via which
-      const path = execSync(`which ${candidate} 2>/dev/null`, { encoding: 'utf8' }).trim();
+      // Relative name — resolve via `which` (execFile: no shell, no injection)
+      const path = execFileSync('which', [candidate], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }).trim();
       if (path) return path;
     } catch {
       // Not found, try next

package/src/daemon.js

@@ -8,9 +8,25 @@
 import { createServer } from 'node:http';
 import { spawn } from 'node:child_process';
 import { writeFileSync, mkdirSync, existsSync, readFileSync, unlinkSync } from 'node:fs';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
 import { join, resolve } from 'node:path';
 import { connect } from './index.js';
 
+/** Owner-only file write helper — daemon artifacts can hold authenticated content. */
+function writeFilePrivate(path, data) {
+  writeFileSync(path, data, { mode: 0o600 });
+}
+
+/** Constant-time token compare; false on any length/format mismatch. */
+function tokenMatches(expected, got) {
+  if (typeof got !== 'string' || got.length !== expected.length) return false;
+  try {
+    return timingSafeEqual(Buffer.from(got), Buffer.from(expected));
+  } catch {
+    return false;
+  }
+}
+
 const SESSION_FILE = 'session.json';
 
 /**
@@ -19,7 +35,7 @@ const SESSION_FILE = 'session.json';
  */
 export async function startDaemon(opts, outputDir, initialUrl) {
   const absDir = resolve(outputDir);
-  mkdirSync(absDir, { recursive: true });
+  mkdirSync(absDir, { recursive: true, mode: 0o700 });
 
   // Clean stale session
   const sessionPath = join(absDir, SESSION_FILE);
@@ -44,6 +60,8 @@ export async function startDaemon(opts, outputDir, initialUrl) {
   if (Array.isArray(opts.blockUrls)) {
     for (const p of opts.blockUrls) args.push('--block-urls', p);
   }
+  if (opts.blockPrivateNetwork) args.push('--block-private-network');
+  if (opts.uploadDir) args.push('--upload-dir', opts.uploadDir);
 
   const child = spawn(process.execPath, args, {
     detached: true,
@@ -75,7 +93,13 @@ export async function startDaemon(opts, outputDir, initialUrl) {
  */
 export async function runDaemon(opts, outputDir, initialUrl) {
   const absDir = resolve(outputDir);
-  mkdirSync(absDir, { recursive: true });
+  mkdirSync(absDir, { recursive: true, mode: 0o700 });
+
+  // Per-session auth token. The daemon binds to loopback, but loopback is
+  // shared across local users — without a token any local user/process could
+  // POST /command and drive the authenticated browser (incl. `eval`). The
+  // token is written into session.json (mode 0600) so only the owner reads it.
+  const authToken = randomBytes(32).toString('hex');
 
   // Connect to browser
   const page = await connect({
@@ -88,6 +112,8 @@ export async function runDaemon(opts, outputDir, initialUrl) {
     downloadPath: opts.downloadPath,
     blockAds: opts.blockAds,
     blockUrls: opts.blockUrls,
+    blockPrivateNetwork: opts.blockPrivateNetwork,
+    uploadDir: opts.uploadDir,
   });
 
   // Console log capture
@@ -161,7 +187,7 @@ export async function runDaemon(opts, outputDir, initialUrl) {
       const text = await page.snapshot({ mode: pruneMode });
       const ts = new Date().toISOString().replace(/[:.]/g, '-');
       const file = join(absDir, `page-${ts}.yml`);
-      writeFileSync(file, text);
+      writeFilePrivate(file, text);
       return { ok: true, file };
     },
 
@@ -170,7 +196,7 @@ export async function runDaemon(opts, outputDir, initialUrl) {
       const ts = new Date().toISOString().replace(/[:.]/g, '-');
       const ext = format || 'png';
       const file = join(absDir, `screenshot-${ts}.${ext}`);
-      writeFileSync(file, Buffer.from(data, 'base64'));
+      writeFilePrivate(file, Buffer.from(data, 'base64'));
       return { ok: true, file };
     },
 
@@ -244,7 +270,7 @@ export async function runDaemon(opts, outputDir, initialUrl) {
       const data = await page.pdf({ landscape });
       const ts = new Date().toISOString().replace(/[:.]/g, '-');
       const file = join(absDir, `page-${ts}.pdf`);
-      writeFileSync(file, Buffer.from(data, 'base64'));
+      writeFilePrivate(file, Buffer.from(data, 'base64'));
       return { ok: true, file };
     },
 
@@ -273,7 +299,7 @@ export async function runDaemon(opts, outputDir, initialUrl) {
     async 'dialog-log'() {
       const ts = new Date().toISOString().replace(/[:.]/g, '-');
       const file = join(absDir, `dialogs-${ts}.json`);
-      writeFileSync(file, JSON.stringify(page.dialogLog, null, 2));
+      writeFilePrivate(file, JSON.stringify(page.dialogLog, null, 2));
       return { ok: true, file, count: page.dialogLog.length };
     },
 
@@ -304,7 +330,7 @@ export async function runDaemon(opts, outputDir, initialUrl) {
       if (level) logs = logs.filter((l) => l.type === level);
       const ts = new Date().toISOString().replace(/[:.]/g, '-');
       const file = join(absDir, `console-${ts}.json`);
-      writeFileSync(file, JSON.stringify(logs, null, 2));
+      writeFilePrivate(file, JSON.stringify(logs, null, 2));
       if (clear) consoleLogs.length = 0;
       return { ok: true, file, count: logs.length };
     },
@@ -314,7 +340,7 @@ export async function runDaemon(opts, outputDir, initialUrl) {
       if (failed) logs = logs.filter((l) => l.status === 0 || l.status >= 400);
       const ts = new Date().toISOString().replace(/[:.]/g, '-');
       const file = join(absDir, `network-${ts}.json`);
-      writeFileSync(file, JSON.stringify(logs, null, 2));
+      writeFilePrivate(file, JSON.stringify(logs, null, 2));
       return { ok: true, file, count: logs.length };
     },
 
@@ -346,6 +372,14 @@ export async function runDaemon(opts, outputDir, initialUrl) {
       return;
     }
 
+    // Require the per-session token. Rejects any local process that hasn't
+    // read session.json (which is owner-only). Constant-time compare.
+    if (!tokenMatches(authToken, req.headers['x-barebrowse-token'])) {
+      res.writeHead(401, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: false, error: 'Unauthorized: missing or invalid token' }));
+      return;
+    }
+
     let body = '';
     for await (const chunk of req) body += chunk;
 
@@ -388,11 +422,13 @@ export async function runDaemon(opts, outputDir, initialUrl) {
 
   const port = server.address().port;
 
-  // Write session.json so parent/clients can find us
+  // Write session.json so parent/clients can find us. Owner-only: it carries
+  // the auth token that gates /command.
   const sessionPath = join(absDir, SESSION_FILE);
-  writeFileSync(sessionPath, JSON.stringify({
+  writeFilePrivate(sessionPath, JSON.stringify({
     port,
     pid: process.pid,
+    token: authToken,
     startedAt: new Date().toISOString(),
   }));
 

package/src/index.js

@@ -18,7 +18,9 @@ import { dismissConsent } from './consent.js';
 import { applyStealth } from './stealth.js';
 import { DEFAULT_BLOCKLIST } from './blocklist.js';
 import { waitForNetworkIdle } from './network-idle.js';
+import { assertNavigable, assertUploadAllowed } from './url-guard.js';
 import { join as pathJoin } from 'node:path';
+import { chmodSync } from 'node:fs';
 
 /**
  * Browse a URL and return an ARIA snapshot.
@@ -41,6 +43,10 @@ export async function browse(url, opts = {}) {
   const mode = opts.mode || 'headless';
   const timeout = opts.timeout || 30000;
 
+  // Reject local-resource schemes (and optionally private hosts) before we
+  // spend a browser launch on a URL we won't navigate to.
+  assertNavigable(url, { allowLocalUrls: opts.allowLocalUrls, blockPrivateNetwork: opts.blockPrivateNetwork });
+
   let browser = null;
   let cdp = null;
   // Forward caller-supplied launch knobs (binary, userDataDir, proxy) into
@@ -154,6 +160,15 @@ export async function browse(url, opts = {}) {
  *   attached to and follows the session across switchTab() until close.
  * @param {string[]} [opts.blockUrls] - Extra URL glob patterns to block,
  *   merged with the default unless blockAds is false.
+ * @param {boolean} [opts.allowLocalUrls=false] - Permit navigation to local-
+ *   resource schemes (file:, view-source:, chrome:, …). Blocked by default
+ *   because a prompt-injected agent could use them to read local files.
+ * @param {boolean} [opts.blockPrivateNetwork=false] - Reject navigation to
+ *   loopback / RFC-1918 / link-local / cloud-metadata hosts (SSRF guard).
+ *   Off by default so localhost dev-server browsing keeps working.
+ * @param {string} [opts.uploadDir] - When set, upload() rejects any file that
+ *   does not resolve (symlinks included) inside this directory. Sandboxes the
+ *   agent's file-upload capability. Default: no restriction.
  * @returns {Promise<object>} Page handle with goto, snapshot, close
  */
 export async function connect(opts = {}) {
@@ -164,6 +179,11 @@ export async function connect(opts = {}) {
   // Forward caller-supplied launch knobs into every launch() below,
   // including hybrid-fallback re-launches inside goto().
   const launchOpts = { proxy: opts.proxy, binary: opts.binary, userDataDir: opts.userDataDir };
+  // Navigation safety policy, applied on every goto()/createTab().goto().
+  const urlGuard = { allowLocalUrls: opts.allowLocalUrls, blockPrivateNetwork: opts.blockPrivateNetwork };
+  // Optional upload sandbox: when set, upload() rejects files outside this dir.
+  // assertUploadAllowed resolves it (realpath) at check time.
+  const uploadDir = opts.uploadDir || null;
 
   if (attachMode) {
     // Reuse the user's running browser — do not launch, do not own the
@@ -312,6 +332,7 @@ export async function connect(opts = {}) {
 
   return {
     async goto(url, timeout = 30000) {
+      assertNavigable(url, urlGuard);
       // Refs from the previous page are about to become invalid — clear
       // before navigating so a stale click(ref) errors clearly instead of
       // silently resolving to whatever backendNodeId happens to still be in
@@ -467,6 +488,10 @@ export async function connect(opts = {}) {
     async upload(ref, files) {
       const entry = refMap.get(ref);
       if (!entry) throw new Error(`No element found for ref "${ref}"`);
+      // Upload sandbox: when uploadDir is set, every path must resolve
+      // (symlinks included, via realpath) inside it. Stops a prompt-injected
+      // agent from attaching ~/.ssh/id_rsa or other arbitrary local files.
+      assertUploadAllowed(files, uploadDir);
       await cdpUpload(entry.session, entry.backendNodeId, files);
     },
 
@@ -535,7 +560,10 @@ export async function connect(opts = {}) {
       });
       const state = { cookies, localStorage: JSON.parse(result.value || '{}') };
       const { writeFileSync } = await import('node:fs');
-      writeFileSync(filePath, JSON.stringify(state, null, 2));
+      // State holds cookies + localStorage (session tokens) — write owner-only
+      // so a multi-user host can't read another user's credentials off disk.
+      writeFileSync(filePath, JSON.stringify(state, null, 2), { mode: 0o600 });
+      try { chmodSync(filePath, 0o600); } catch { /* best effort if pre-existing */ }
     },
 
     get botBlocked() { return botBlocked; },
@@ -590,6 +618,7 @@ export async function connect(opts = {}) {
       let tabBotBlocked = false;
       return {
         async goto(url, timeout = 30000) {
+          assertNavigable(url, urlGuard);
           await navigate(tab, url, timeout);
           if (opts.consent !== false) {
             await dismissConsent(tab.session);

package/src/session-client.js

@@ -53,7 +53,11 @@ export async function sendCommand(command, args, outputDir) {
   try {
     res = await fetch(`http://127.0.0.1:${session.port}/command`, {
       method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
+      headers: {
+        'Content-Type': 'application/json',
+        // Authenticate to the daemon with the per-session token from session.json.
+        ...(session.token ? { 'x-barebrowse-token': session.token } : {}),
+      },
       body: JSON.stringify({ command, args }),
       signal: AbortSignal.timeout(60000),
     });

package/src/url-guard.js

@@ -0,0 +1,138 @@
+/**
+ * url-guard.js — Navigation safety checks for goto()/browse().
+ *
+ * Closes two confirmed vectors for an autonomous (and therefore
+ * prompt-injectable) agent:
+ *   1. Local-resource schemes (file:, view-source:, chrome:, …) that let a
+ *      page-sourced instruction read local files or browser internals.
+ *   2. Optional private-network blocking (loopback, RFC-1918, link-local,
+ *      cloud-metadata) to stop SSRF to internal services.
+ *
+ * Scheme blocking is on by default; private-network blocking is opt-in
+ * (blockPrivateNetwork) so localhost dev-server browsing keeps working.
+ *
+ * Limitation: private-network checks match the URL hostname only. A public
+ * DNS name that resolves to a private IP (DNS rebinding) is NOT caught here —
+ * that needs connection-time IP inspection. Documented, not silently assumed.
+ */
+
+import { realpathSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+
+// Schemes safe to navigate to. Everything else is treated as a local-resource
+// or browser-internal scheme and blocked unless allowLocalUrls is set.
+// data:/blob:/about: stay allowed: opaque origins, no file:// or cross-origin
+// read, and data: is the library's test-fixture mechanism.
+const ALLOWED_SCHEMES = new Set(['http:', 'https:', 'data:', 'blob:', 'about:']);
+
+/**
+ * @param {string} host - hostname (no brackets for IPv6)
+ * @returns {boolean} true if it names a private/loopback/link-local/internal host
+ */
+function isPrivateHost(host) {
+  const h = host.toLowerCase().replace(/^\[|\]$/g, ''); // strip IPv6 brackets
+
+  // Internal hostnames
+  if (h === 'localhost' || h.endsWith('.localhost')) return true;
+  if (h.endsWith('.local') || h.endsWith('.internal')) return true;
+  if (h === 'metadata.google.internal') return true;
+
+  // IPv4 (incl. ranges)
+  const v4 = h.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  if (v4) {
+    const [a, b] = [Number(v4[1]), Number(v4[2])];
+    if (a === 127) return true;                 // loopback 127.0.0.0/8
+    if (a === 10) return true;                   // 10.0.0.0/8
+    if (a === 0) return true;                    // 0.0.0.0/8
+    if (a === 169 && b === 254) return true;     // link-local / cloud metadata
+    if (a === 172 && b >= 16 && b <= 31) return true; // 172.16.0.0/12
+    if (a === 192 && b === 168) return true;     // 192.168.0.0/16
+    return false;
+  }
+
+  // IPv6 — gated on the host actually being an IPv6 literal (contains a
+  // colon). Without this gate, ordinary hostnames like "fcbarcelona.com" or
+  // "fdic.gov" would match the fc00::/7 ULA prefix check and be wrongly blocked.
+  if (h.includes(':')) {
+    if (h === '::1' || h === '::') return true;        // loopback / unspecified
+    if (h.startsWith('fe80:')) return true;            // link-local fe80::/10
+    if (h.startsWith('fc') || h.startsWith('fd')) return true; // fc00::/7 ULA
+    // IPv4-mapped IPv6 (e.g. ::ffff:127.0.0.1)
+    const mapped = h.match(/::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+    if (mapped) return isPrivateHost(mapped[1]);
+    return false;
+  }
+
+  return false;
+}
+
+/**
+ * Throw if `url` is unsafe to navigate to under the given policy.
+ * @param {string} url
+ * @param {object} [opts]
+ * @param {boolean} [opts.allowLocalUrls=false] - permit file:/chrome:/etc.
+ * @param {boolean} [opts.blockPrivateNetwork=false] - reject loopback/RFC-1918/metadata.
+ */
+export function assertNavigable(url, opts = {}) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`Refusing to navigate: not a valid URL (${String(url).slice(0, 80)})`);
+  }
+
+  if (!opts.allowLocalUrls && !ALLOWED_SCHEMES.has(parsed.protocol)) {
+    throw new Error(
+      `Refusing to navigate to "${parsed.protocol}" URL — local-resource and ` +
+      `browser-internal schemes are blocked (reads local files / browser state). ` +
+      `Pass { allowLocalUrls: true } to override.`
+    );
+  }
+
+  if (
+    opts.blockPrivateNetwork &&
+    (parsed.protocol === 'http:' || parsed.protocol === 'https:') &&
+    parsed.hostname &&
+    isPrivateHost(parsed.hostname)
+  ) {
+    throw new Error(
+      `Refusing to navigate to private/internal host "${parsed.hostname}" — ` +
+      `blockPrivateNetwork is enabled (SSRF guard). ` +
+      `Unset it to allow localhost / internal browsing.`
+    );
+  }
+}
+
+/**
+ * Throw if any file in `files` resolves outside `uploadDir`. Both the base
+ * dir and each file are resolved through realpath, so symlinks (in either the
+ * base path — e.g. macOS /tmp → /private/tmp — or the file) can't be used to
+ * escape the sandbox or to false-reject a legitimate file.
+ * No-op when `uploadDir` is falsy (no restriction configured).
+ * @param {string|string[]} files
+ * @param {string|null} uploadDir
+ */
+export function assertUploadAllowed(files, uploadDir) {
+  if (!uploadDir) return;
+  let baseReal;
+  try {
+    baseReal = realpathSync(resolve(uploadDir));
+  } catch {
+    throw new Error(`upload: uploadDir does not exist or is unreadable (${uploadDir})`);
+  }
+  const list = Array.isArray(files) ? files : [files];
+  for (const f of list) {
+    let real;
+    try {
+      real = realpathSync(resolve(String(f)));
+    } catch {
+      throw new Error(`upload: cannot resolve "${f}" (must exist inside uploadDir)`);
+    }
+    if (real !== baseReal && !real.startsWith(baseReal + sep)) {
+      throw new Error(`upload: "${f}" is outside the allowed uploadDir (${uploadDir})`);
+    }
+  }
+}
+
+// Exported for unit tests.
+export { isPrivateHost };