barebrowse 0.10.1 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,105 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.12.0] - 2026-05-29
+
+### Added
+- **Shipped TypeScript types, generated from JSDoc.** The package now ships
+  `.d.ts` declarations so adopters get autocomplete and type errors out of the
+  box — no `@types/barebrowse`. The `.js` we author is still the `.js` that
+  ships; there is **no build step for runtime code**. Types are generated by
+  `tsc` (`checkJs` + `strictNullChecks`), emitted to a git-ignored `types/`, and
+  built into the tarball at publish via `prepublishOnly`. Because they are
+  generated-and-never-committed, the JSDoc, the `.d.ts`, and CI cannot drift.
+  `exports` now carries a `types` condition on every subpath.
+- **`ci.yml` (push/PR gate):** `npm ci → typecheck → build:types → test`. A
+  JSDoc/code mismatch is now a type error that blocks merge. No lint step — `tsc`
+  covers the bug class that matters for a vanilla-ESM lib.
+- Dev-only tooling: `typescript` + `@types/node` (devDependencies; never
+  shipped), `tsconfig.json`, and `typecheck` / `build:types` / `prepublishOnly`
+  scripts.
+
+### Changed
+- **`publish.yml` is now manual-only (`workflow_dispatch`) — npm OIDC trusted publishing with provenance, idempotent, and verifies the registry end-state.**
+- **Packaging now uses a `files` allowlist** (`src/`, generated `types/`,
+  `cli.js`, `mcp-server.js`, and the doc set) instead of the old `.npmignore`
+  denylist, which was removed. Repo-only files (`test/`, `docs/`, `CLAUDE.md`)
+  are excluded from the tarball.
+
+### Fixed
+- **`auth.js`: cookie databases are now opened with `readOnly: true`.** The
+  previous `readonly` (lowercase) key is silently ignored by `node:sqlite`;
+  surfaced by the new `tsc` typecheck. Read-only was already enforced via the
+  `?immutable=1` connection URI, so observable behavior is unchanged — this
+  honors the intended option. Added minimal, behavior-preserving null/type
+  guards in a few spots (`server.address()`, SQLite row values) flagged by
+  `strictNullChecks`.
+
+## 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

@@ -35,6 +35,8 @@ npm install barebrowse
 
 Requires Node.js >= 22 and any installed Chromium-based browser.
 
+Ships with TypeScript types (generated from JSDoc) — autocomplete and type-checking work out of the box, no `@types/barebrowse` needed. The library is vanilla JS with no build step.
+
 ## Three ways to use it
 
 ### 1. CLI session -- for coding agents and quick testing
@@ -134,6 +136,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.12.0 | Node.js >= 22 | 0 required deps | Apache-2.0
 
 ## What this is
 
@@ -13,6 +13,11 @@ No Playwright. No bundled browser. No build step. Vanilla JS, ES modules.
 npm install barebrowse
 ```
 
+**TypeScript:** ships with `.d.ts` types generated from the source JSDoc, so
+autocomplete and type-checking work out of the box — no `@types/barebrowse`
+needed. The library itself is vanilla JS with no build step; the types are a
+publish-time artifact.
+
 Three integration paths:
 1. **Library:** `import { browse, connect } from 'barebrowse'` -- one-shot or interactive session
 2. **MCP server:** `barebrowse mcp` -- JSON-RPC over stdio for Claude Desktop, Cursor, etc.
@@ -95,6 +100,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 +234,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 +363,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/package.json

@@ -1,21 +1,49 @@
 {
   "name": "barebrowse",
-  "version": "0.10.1",
+  "version": "0.12.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",
+  "types": "./types/index.d.ts",
   "exports": {
-    ".": "./src/index.js",
-    "./bareagent": "./src/bareagent.js"
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./bareagent": {
+      "types": "./types/bareagent.d.ts",
+      "default": "./src/bareagent.js"
+    }
   },
   "bin": {
     "barebrowse": "./cli.js"
   },
+  "files": [
+    "src/",
+    "types/",
+    "cli.js",
+    "mcp-server.js",
+    "barebrowse.context.md",
+    "README.md",
+    "CHANGELOG.md",
+    "NOTICE"
+  ],
   "engines": {
     "node": ">=22"
   },
   "scripts": {
-    "test": "node --test test/unit/*.test.js test/integration/*.test.js"
+    "test": "node --test test/unit/*.test.js test/integration/*.test.js",
+    "test:unit": "node --test test/unit/*.test.js",
+    "test:integration": "node --test test/integration/*.test.js",
+    "typecheck": "tsc --noEmit",
+    "build:types": "tsc",
+    "prepublishOnly": "npm run build:types"
   },
   "keywords": [
     "browser",
@@ -29,7 +57,11 @@
     "headless"
   ],
   "optionalDependencies": {
-    "wearehere": "^1.0.0"
+    "wearehere": "1.0.0"
   },
-  "license": "Apache-2.0"
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3"
+  }
 }

package/src/auth.js

@@ -126,7 +126,7 @@ function extractChromiumCookies(dbPath, domain) {
   const aesKey = deriveKey(password);
 
   // immutable=1 bypasses WAL lock on live databases
-  const db = new DatabaseSync(`file://${dbPath}?immutable=1`, { readonly: true });
+  const db = new DatabaseSync(`file://${dbPath}?immutable=1`, { readOnly: true });
 
   let sql = `SELECT host_key, name, value, encrypted_value, path,
     CAST(expires_utc AS TEXT) AS expires_utc, is_secure, is_httponly, samesite
@@ -144,7 +144,8 @@ function extractChromiumCookies(dbPath, domain) {
   const SAMESITE = { 0: 'None', 1: 'Lax', 2: 'Strict' };
 
   return rows.map((row) => {
-    const enc = Buffer.from(row.encrypted_value);
+    const rawEnc = row.encrypted_value;
+    const enc = rawEnc instanceof Uint8Array ? Buffer.from(rawEnc) : Buffer.alloc(0);
     let value;
     try {
       value = enc.length > 0 ? decryptCookie(enc, aesKey) : row.value;
@@ -154,7 +155,9 @@ function extractChromiumCookies(dbPath, domain) {
 
     // Chrome timestamp: microseconds since 1601-01-01
     const CHROME_EPOCH = 11644473600000000n;
-    const expiresUtc = row.expires_utc ? BigInt(row.expires_utc) : 0n;
+    const expiresUtc = typeof row.expires_utc === 'string' || typeof row.expires_utc === 'number'
+      ? BigInt(row.expires_utc)
+      : 0n;
     const expires = expiresUtc > 0n
       ? Number((expiresUtc - CHROME_EPOCH) / 1000000n)
       : -1;
@@ -179,7 +182,7 @@ function extractChromiumCookies(dbPath, domain) {
  * @returns {Array<object>} Cookies in CDP Network.setCookie format
  */
 function extractFirefoxCookies(dbPath, domain) {
-  const db = new DatabaseSync(`file://${dbPath}?immutable=1`, { readonly: true });
+  const db = new DatabaseSync(`file://${dbPath}?immutable=1`, { readOnly: true });
 
   let sql = `SELECT host, name, value, path, expiry, isSecure, isHttpOnly, sameSite
     FROM moz_cookies`;
@@ -268,6 +271,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 +295,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/bareagent.js

@@ -11,6 +11,8 @@
  * 300ms settle delay after actions for DOM updates.
  */
 
+/// <reference path="./wearehere.d.ts" />
+
 import { browse, connect } from './index.js';
 
 // Optional: privacy assessment via wearehere
@@ -22,6 +24,14 @@ try {
 const SETTLE_MS = 300;
 const settle = () => new Promise((r) => setTimeout(r, SETTLE_MS));
 
+/**
+ * @typedef {object} BrowseTool
+ * @property {string} name
+ * @property {string} description
+ * @property {object} parameters - JSON-schema-shaped parameter spec
+ * @property {(args?: any) => Promise<any>} execute
+ */
+
 /**
  * Create bareagent-compatible browse tools.
  * @param {object} [opts] - Options passed to connect() for session tools
@@ -42,6 +52,7 @@ export function createBrowseTools(opts = {}) {
     return await page.snapshot();
   }
 
+  /** @type {BrowseTool[]} */
   const tools = [
     {
       name: 'browse',
@@ -77,7 +88,7 @@ export function createBrowseTools(opts = {}) {
           pruneMode: { type: 'string', enum: ['act', 'read'], description: '"act" (default) for interactive elements only; "read" for paragraphs and long text (articles/docs).' },
         },
       },
-      execute: async ({ pruneMode } = {}) => {
+      execute: async (/** @type {{ pruneMode?: string }} */ { pruneMode } = {}) => {
         const page = await getPage();
         return await page.snapshot(pruneMode ? { mode: pruneMode } : undefined);
       },
@@ -231,7 +242,7 @@ export function createBrowseTools(opts = {}) {
           landscape: { type: 'boolean', description: 'Landscape orientation (default: false)' },
         },
       },
-      execute: async ({ landscape } = {}) => {
+      execute: async (/** @type {{ landscape?: boolean }} */ { landscape } = {}) => {
         const page = await getPage();
         return await page.pdf({ landscape });
       },
@@ -245,7 +256,7 @@ export function createBrowseTools(opts = {}) {
           format: { type: 'string', enum: ['png', 'jpeg', 'webp'], description: 'Image format (default: png)' },
         },
       },
-      execute: async ({ format } = {}) => {
+      execute: async (/** @type {{ format?: string }} */ { format } = {}) => {
         const page = await getPage();
         return await page.screenshot({ format });
       },
@@ -259,7 +270,7 @@ export function createBrowseTools(opts = {}) {
           ignoreCache: { type: 'boolean', description: 'Bypass HTTP cache (hard reload). Default: false.' },
         },
       },
-      execute: async ({ ignoreCache } = {}) => actionAndSnapshot((page) => page.reload({ ignoreCache })),
+      execute: async (/** @type {{ ignoreCache?: boolean }} */ { ignoreCache } = {}) => actionAndSnapshot((page) => page.reload({ ignoreCache })),
     },
     {
       name: 'wait_for',
@@ -272,7 +283,7 @@ export function createBrowseTools(opts = {}) {
           timeout: { type: 'number', description: 'Timeout in ms (default: 30000)' },
         },
       },
-      execute: async ({ text, selector, timeout } = {}) => actionAndSnapshot((page) => page.waitFor({ text, selector, timeout })),
+      execute: async (/** @type {{ text?: string, selector?: string, timeout?: number }} */ { text, selector, timeout } = {}) => actionAndSnapshot((page) => page.waitFor({ text, selector, timeout })),
     },
     {
       name: 'downloads',

package/src/cdp.js

@@ -12,7 +12,7 @@
 /**
  * Create a CDP client connected to the given WebSocket URL.
  * @param {string} wsUrl - WebSocket URL (ws://127.0.0.1:PORT/devtools/...)
- * @returns {Promise<CDPClient>}
+ * @returns {Promise<object>} CDP client ({ send, on, once, session, close })
  */
 export async function createCDP(wsUrl) {
   const ws = new WebSocket(wsUrl);
@@ -20,7 +20,8 @@ export async function createCDP(wsUrl) {
   const pending = new Map();   // id → { resolve, reject }
   const listeners = new Map(); // "method" or "sessionId:method" → Set<callback>
 
-  await new Promise((resolve, reject) => {
+  /** @type {Promise<void>} */
+  const connected = new Promise((resolve, reject) => {
     const timeout = setTimeout(() => reject(new Error('CDP connection timeout (5s)')), 5000);
     ws.onopen = () => { clearTimeout(timeout); resolve(); };
     ws.onerror = (e) => {
@@ -28,6 +29,7 @@ export async function createCDP(wsUrl) {
       reject(new Error(`CDP WebSocket connection failed: ${e.message || 'unknown error'}`));
     };
   });
+  await connected;
 
   ws.onmessage = (event) => {
     const msg = JSON.parse(typeof event.data === 'string' ? event.data : event.data.toString());

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
@@ -104,7 +112,8 @@ export function findBrowser() {
  * @param {number} [opts.port=0] - CDP port (0 = random available port)
  * @param {string} [opts.userDataDir] - Browser profile directory
  * @param {boolean} [opts.headed=false] - Launch in headed mode (with visible window)
- * @returns {Promise<{wsUrl: string, process: ChildProcess, port: number}>}
+ * @param {string} [opts.proxy] - Proxy server (e.g. 'http://host:port')
+ * @returns {Promise<{wsUrl: string, process: import('node:child_process').ChildProcess, port: number}>}
  */
 export async function launch(opts = {}) {
   const binary = opts.binary || findBrowser();
@@ -227,6 +236,7 @@ export async function cleanupBrowser(browser) {
   if (!browser) return;
   activeBrowsers.delete(browser);
   if (browser.process && !browser.process.killed && browser.process.exitCode === null) {
+    /** @type {Promise<void>} */
     const exited = new Promise((resolve) => {
       const timer = setTimeout(resolve, 2000);
       browser.process.once('exit', () => { clearTimeout(timer); resolve(); });
@@ -274,7 +284,10 @@ export async function cleanupBrowser(browser) {
 export async function getDebugUrl(port) {
   const res = await fetch(`http://127.0.0.1:${port}/json/version`);
   if (!res.ok) throw new Error(`Cannot reach browser debug port at ${port}: ${res.status}`);
-  const data = await res.json();
+  const data = /** @type {{ webSocketDebuggerUrl?: string }} */ (await res.json());
+  if (!data.webSocketDebuggerUrl) {
+    throw new Error(`Browser debug port at ${port} returned no webSocketDebuggerUrl`);
+  }
   return data.webSocketDebuggerUrl;
 }