barebrowse 0.10.1 → 0.12.0

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;
 
@@ -382,17 +416,25 @@ export async function runDaemon(opts, outputDir, initialUrl) {
     }
   });
 
-  await new Promise((resolve) => {
+  /** @type {Promise<void>} */
+  const listening = new Promise((resolve) => {
     server.listen(0, '127.0.0.1', () => resolve());
   });
+  await listening;
 
-  const port = server.address().port;
+  const address = server.address();
+  if (!address || typeof address === 'string') {
+    throw new Error('Daemon server failed to bind to a TCP port');
+  }
+  const port = 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.
@@ -35,12 +37,27 @@ import { join as pathJoin } from 'node:path';
  *   See src/blocklist.js for the default set. Set false to disable.
  * @param {string[]} [opts.blockUrls] - Extra URL glob patterns to block,
  *   merged with the default unless blockAds:false.
+ * @param {boolean} [opts.allowLocalUrls=false] - Permit navigation to local-
+ *   resource schemes (file:, view-source:, chrome:, …). Blocked by default.
+ * @param {boolean} [opts.blockPrivateNetwork=false] - Reject navigation to
+ *   loopback / RFC-1918 / link-local / cloud-metadata hosts (SSRF guard).
+ * @param {string} [opts.proxy] - Proxy server (e.g. 'http://host:port').
+ * @param {string} [opts.binary] - Path to browser binary (auto-detected if omitted).
+ * @param {string} [opts.userDataDir] - Browser profile directory.
+ * @param {{width: number, height: number}} [opts.viewport] - Viewport dimensions.
+ * @param {string} [opts.browser] - Source browser for cookie extraction.
+ * @param {boolean} [opts.consent=true] - Auto-dismiss cookie consent dialogs.
+ * @param {'act'|'browse'|'navigate'|'full'|'read'} [opts.pruneMode='act'] - Pruning mode.
  * @returns {Promise<string>} ARIA snapshot text
  */
 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 +171,23 @@ 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.
+ * @param {string} [opts.proxy] - Proxy server (e.g. 'http://host:port').
+ * @param {string} [opts.binary] - Path to browser binary (auto-detected if omitted).
+ * @param {string} [opts.userDataDir] - Browser profile directory.
+ * @param {{width: number, height: number}} [opts.viewport] - Viewport dimensions.
+ * @param {boolean} [opts.consent=true] - Auto-dismiss cookie consent dialogs.
+ * @param {string} [opts.storageState] - Path to a storage-state JSON file
+ *   (cookies + localStorage) to load before navigation.
+ * @param {'act'|'browse'|'navigate'|'full'|'read'} [opts.pruneMode='act'] - Pruning mode.
  * @returns {Promise<object>} Page handle with goto, snapshot, close
  */
 export async function connect(opts = {}) {
@@ -164,12 +198,17 @@ 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
     // profile. cleanupBrowser() is a no-op on this shape (process: null,
     // ownedProfileDir: null), which is the whole point.
-    browser = await attach({ port: opts.port });
+    browser = await attach({ port: opts.port ?? 0 });
     cdp = await createCDP(browser.wsUrl);
   } else if (mode === 'headed') {
     browser = await launch({ ...launchOpts, headed: true });
@@ -312,6 +351,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 +507,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 +579,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 +637,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/network-idle.js

@@ -12,12 +12,14 @@
  * @param {object} [opts]
  * @param {number} [opts.timeout=30000] - Max wait time before reject
  * @param {number} [opts.idle=500] - Required idle duration before resolve
+ * @returns {Promise<void>}
  */
 export function waitForNetworkIdle(session, opts = {}) {
   const timeout = opts.timeout || 30000;
   const idle = opts.idle || 500;
 
-  return new Promise((resolve, reject) => {
+  /** @type {Promise<void>} */
+  const settled = new Promise((resolve, reject) => {
     const pending = new Set();
     let timer = null;
     const unsubs = [];
@@ -59,4 +61,5 @@ export function waitForNetworkIdle(session, opts = {}) {
     // Start check immediately (might already be idle)
     check();
   });
+  return settled;
 }

package/src/prune.js

@@ -60,7 +60,7 @@ const SKIP_ROLES = new Set([
  *
  * @param {object} tree - Root node from buildTree() (CDP format)
  * @param {object} [options]
- * @param {'act'|'browse'|'navigate'|'full'} [options.mode='act'] - Pruning mode
+ * @param {'act'|'browse'|'navigate'|'full'|'read'} [options.mode='act'] - Pruning mode ('read' is an alias for 'browse')
  * @param {string} [options.context=''] - Search context for relevance filtering
  * @returns {object|null} Pruned tree
  */

package/src/session-client.js

@@ -13,7 +13,7 @@ const SESSION_FILE = 'session.json';
 
 /**
  * Read session.json from the output directory.
- * @returns {{ port: number, pid: number, startedAt: string } | null}
+ * @returns {{ port: number, pid: number, token?: string, startedAt: string } | null}
  */
 export function readSession(outputDir) {
   const sessionPath = join(resolve(outputDir), SESSION_FILE);
@@ -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 };

package/src/wearehere.d.ts

@@ -0,0 +1,6 @@
+// Ambient shim for the optional 'wearehere' dependency.
+// It is dynamically imported and may not be installed; this declaration
+// satisfies the typechecker without pulling in a hard dependency.
+declare module 'wearehere' {
+  export function assess(...args: any[]): Promise<any>;
+}

package/types/aria.d.ts

@@ -0,0 +1,17 @@
+/**
+ * aria.js — Format ARIA accessibility tree nodes for agent consumption.
+ *
+ * Takes a nested tree (built from CDP's Accessibility.getFullAXTree)
+ * and formats it as readable YAML-like text, similar to Playwright's ariaSnapshot.
+ */
+/**
+ * Format a nested ARIA tree as readable text output.
+ *
+ * Output format (one node per line, indented):
+ *   - role "name" [props] [ref=nodeId]
+ *
+ * @param {object} node - Tree node { role, name, properties, children, ignored, nodeId }
+ * @param {number} [depth=0] - Current indentation depth
+ * @returns {string} Formatted ARIA tree text
+ */
+export function formatTree(node: object, depth?: number): string;

package/types/auth.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Extract cookies from the user's browser, auto-detecting which browser to use.
+ * @param {object} [opts]
+ * @param {string} [opts.browser] - 'chromium', 'chrome', 'brave', 'edge', 'firefox', or 'auto'
+ * @param {string} [opts.domain] - Filter by domain
+ * @returns {Array<object>} Cookies in CDP-compatible format
+ */
+export function extractCookies(opts?: {
+    browser?: string | undefined;
+    domain?: string | undefined;
+}): Array<object>;
+/**
+ * Inject cookies into a CDP session via Network.setCookie.
+ * @param {object} session - CDP session handle (from cdp.session())
+ * @param {Array<object>} cookies - Cookies from extractCookies()
+ */
+export function injectCookies(session: object, cookies: Array<object>): Promise<void>;
+/**
+ * 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: string, cookieDomain: string): boolean;
+/**
+ * Extract cookies for a URL and inject them into a CDP session.
+ * Convenience function combining extractCookies + injectCookies.
+ * @param {object} session - CDP session handle
+ * @param {string} url - URL to extract cookies for
+ * @param {object} [opts] - Options passed to extractCookies
+ */
+export function authenticate(session: object, url: string, opts?: object): Promise<number>;

package/types/bareagent.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @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
+ * @returns {{ tools: Array, close: () => Promise<void> }}
+ */
+export function createBrowseTools(opts?: object): {
+    tools: any[];
+    close: () => Promise<void>;
+};
+export type BrowseTool = {
+    name: string;
+    description: string;
+    /**
+     * - JSON-schema-shaped parameter spec
+     */
+    parameters: object;
+    execute: (args?: any) => Promise<any>;
+};

package/types/blocklist.d.ts

@@ -0,0 +1,21 @@
+/**
+ * blocklist.js — Ad/tracker URL patterns for CDP Network.setBlockedURLs.
+ *
+ * Curated by real-world frequency, not pulled wholesale from Peter Lowe /
+ * EasyList. CDP does linear pattern matching per request, so 3,000-entry
+ * lists add ~150ms cumulative cost on a typical page for ~5% extra coverage
+ * (long-tail regional networks the agent rarely encounters). The set below
+ * is ~120 patterns covering the trackers that actually show up in agent
+ * traffic: Google/FB/Amazon/MS/Adobe ad+analytics, the major SaaS analytics
+ * stacks (Segment/Amplitude/Mixpanel/HubSpot/Hotjar/FullStory/Heap/Mouseflow),
+ * session-replay (LogRocket/Crazy Egg/Optimizely/VWO), content-recommendation
+ * (Taboola/Outbrain/Criteo), and the consumer-pixel cluster (LinkedIn/Twitter/
+ * TikTok/Snap/Pinterest/Reddit).
+ *
+ * Patterns are CDP-format globs: '*' matches any character run.
+ *
+ * To extend at runtime, pass connect({ blockUrls: [...] }) — your patterns
+ * are merged with this default. To turn the default off entirely, pass
+ * { blockAds: false }.
+ */
+export const DEFAULT_BLOCKLIST: string[];

package/types/cdp.d.ts

@@ -0,0 +1,16 @@
+/**
+ * cdp.js — Minimal Chrome DevTools Protocol client over WebSocket.
+ *
+ * Sends JSON-RPC commands, receives responses and events.
+ * Uses Node 22's built-in WebSocket (no external deps).
+ *
+ * Supports flattened sessions: when a sessionId is provided,
+ * it's sent at the top level of the message (not inside params).
+ * Events from sessions are also dispatched by sessionId.
+ */
+/**
+ * Create a CDP client connected to the given WebSocket URL.
+ * @param {string} wsUrl - WebSocket URL (ws://127.0.0.1:PORT/devtools/...)
+ * @returns {Promise<object>} CDP client ({ send, on, once, session, close })
+ */
+export function createCDP(wsUrl: string): Promise<object>;

package/types/chromium.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Find the first available Chromium binary on the system.
+ * @returns {string} Path to the binary
+ * @throws {Error} If no Chromium browser is found
+ */
+export function findBrowser(): string;
+/**
+ * Launch a Chromium instance with CDP enabled.
+ * @param {object} [opts]
+ * @param {string} [opts.binary] - Path to browser binary (auto-detected if omitted)
+ * @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)
+ * @param {string} [opts.proxy] - Proxy server (e.g. 'http://host:port')
+ * @returns {Promise<{wsUrl: string, process: import('node:child_process').ChildProcess, port: number}>}
+ */
+export function launch(opts?: {
+    binary?: string | undefined;
+    port?: number | undefined;
+    userDataDir?: string | undefined;
+    headed?: boolean | undefined;
+    proxy?: string | undefined;
+}): Promise<{
+    wsUrl: string;
+    process: import("node:child_process").ChildProcess;
+    port: number;
+}>;
+/**
+ * Kill a launched browser and remove its temp profile dir (if we created one).
+ * Waits up to 2s for the process to actually exit before unlinking the dir —
+ * Chromium can still hold files briefly after SIGTERM, which races rmSync.
+ * Safe to call on partially-failed launches or already-dead processes.
+ * @returns {Promise<void>}
+ */
+export function cleanupBrowser(browser: any): Promise<void>;
+/**
+ * Get the CDP WebSocket URL for a browser already running with --remote-debugging-port.
+ * @param {number} port - The debug port
+ * @returns {Promise<string>} WebSocket URL
+ */
+export function getDebugUrl(port: number): Promise<string>;
+/**
+ * Attach to a Chromium already running with --remote-debugging-port=<port>.
+ * Returns the same shape as launch() but with process: null and
+ * ownedProfileDir: null — cleanupBrowser() becomes a no-op so we never
+ * kill a browser we did not start or remove a profile we do not own.
+ * @param {object} opts
+ * @param {number} opts.port - The debug port the running browser is listening on
+ * @returns {Promise<{wsUrl: string, process: null, port: number, ownedProfileDir: null}>}
+ */
+export function attach({ port }: {
+    port: number;
+}): Promise<{
+    wsUrl: string;
+    process: null;
+    port: number;
+    ownedProfileDir: null;
+}>;