barebrowse 0.13.0 → 0.15.0

package/src/index.js

@@ -9,7 +9,10 @@
  */
 
 import { launch, attach, cleanupBrowser } from './chromium.js';
+import { launchFirefox, cleanupFirefox } from './firefox.js';
 import { createCDP } from './cdp.js';
+import { createBiDi } from './bidi.js';
+import { createFirefoxPage } from './firefox-page.js';
 import { formatTree } from './aria.js';
 import { authenticate } from './auth.js';
 import { prune as pruneTree } from './prune.js';
@@ -31,6 +34,8 @@ import { chmodSync } from 'node:fs';
  * @param {object} [opts]
  * @param {'headless'|'headed'|'hybrid'} [opts.mode='headless'] - Browser mode
  * @param {boolean} [opts.cookies=true] - Inject user's cookies (Phase 2)
+ * @param {boolean} [opts.incognito=false] - Clean, unauthenticated session:
+ *   skip cookie/auth injection entirely (equivalent to cookies:false here).
  * @param {boolean} [opts.prune=true] - Apply ARIA pruning (Phase 2)
  * @param {number} [opts.timeout=30000] - Navigation timeout in ms
  * @param {boolean} [opts.blockAds=true] - Block ~120 common ad/tracker
@@ -54,6 +59,8 @@ import { chmodSync } from 'node:fs';
 export async function browse(url, opts = {}) {
   const mode = opts.mode || 'headless';
   const timeout = opts.timeout || 30000;
+  // Skip all auth injection when incognito (or the legacy cookies:false).
+  const noAuth = !!opts.incognito || opts.cookies === false;
 
   // Reject local-resource schemes (and optionally private hosts) before we
   // spend a browser launch on a URL we won't navigate to.
@@ -84,7 +91,7 @@ export async function browse(url, opts = {}) {
     await suppressPermissions(cdp);
 
     // Step 3: Cookie injection — extract from user's browser, inject via CDP
-    if (opts.cookies !== false) {
+    if (!noAuth) {
       try {
         await authenticate(page.session, url, { browser: opts.browser });
       } catch {
@@ -114,7 +121,7 @@ export async function browse(url, opts = {}) {
         cdp = await createCDP(browser.wsUrl);
         page = await createPage(cdp, false, pageOpts);
         await suppressPermissions(cdp);
-        if (opts.cookies !== false) {
+        if (!noAuth) {
           try { await authenticate(page.session, url, { browser: opts.browser }); } catch {}
         }
         await navigate(page, url, timeout);
@@ -188,12 +195,32 @@ export async function browse(url, opts = {}) {
  * @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 {boolean} [opts.incognito=false] - Clean, unauthenticated session:
+ *   skip storageState loading and make injectCookies() a no-op, so no auth
+ *   ever enters the session even if a caller injects unconditionally.
  * @param {'act'|'browse'|'navigate'|'full'|'read'} [opts.pruneMode='act'] - Pruning mode.
+ * @param {'chromium'|'firefox'} [opts.engine='chromium'] - Browser engine.
+ *   'firefox' drives over WebDriver BiDi (a separate transport / page object);
+ *   'chromium' (default) uses CDP.
  * @returns {Promise<object>} Page handle with goto, snapshot, close
  */
 export async function connect(opts = {}) {
+  // Firefox is driven over WebDriver BiDi (CDP is deprecated there) — a
+  // separate transport with its own page object. It reuses prune.js/aria.js/
+  // readable.js but none of the CDP page machinery below, so branch early.
+  if (opts.engine === 'firefox') {
+    return connectFirefox(opts);
+  }
+
   const mode = opts.mode || 'headless';
   const attachMode = !!opts.port;
+  // Incognito: run a clean, unauthenticated session. Skips storageState loading
+  // and neuters injectCookies() so no auth ever enters the session — even when
+  // a caller (MCP goto, daemon) calls injectCookies() unconditionally. The
+  // temp profile is already throwaway; this gates the OTHER auth source: the
+  // user's real browser cookies. Not Chrome's --incognito flag (redundant with
+  // the temp profile and would break the cookie-injection path when off).
+  const incognito = !!opts.incognito;
   let browser = null;
   let cdp;
   // Forward caller-supplied launch knobs into every launch() below,
@@ -243,8 +270,9 @@ export async function connect(opts = {}) {
     await suppressPermissions(cdp);
   }
 
-  // Load storage state (cookies + localStorage) from file
-  if (opts.storageState) {
+  // Load storage state (cookies + localStorage) from file.
+  // Skipped under incognito — storageState is an auth source too.
+  if (opts.storageState && !incognito) {
     try {
       const { readFileSync } = await import('node:fs');
       const state = JSON.parse(readFileSync(opts.storageState, 'utf8'));
@@ -439,7 +467,10 @@ export async function connect(opts = {}) {
     },
 
     async injectCookies(url, cookieOpts) {
-      await authenticate(page.session, url, { browser: cookieOpts?.browser });
+      // No-op under incognito: callers (MCP goto, daemon) inject unconditionally,
+      // so the gate has to live here, not just at the call site.
+      if (incognito) return 0;
+      return authenticate(page.session, url, { browser: cookieOpts?.browser });
     },
 
     async snapshot(pruneOpts) {
@@ -655,7 +686,8 @@ export async function connect(opts = {}) {
         },
         get botBlocked() { return tabBotBlocked; },
         async injectCookies(url, cookieOpts) {
-          await authenticate(tab.session, url, { browser: cookieOpts?.browser });
+          if (incognito) return 0;
+          return authenticate(tab.session, url, { browser: cookieOpts?.browser });
         },
         waitForNetworkIdle(idleOpts = {}) {
           return waitForNetworkIdle(tab.session, idleOpts);
@@ -708,6 +740,43 @@ async function suppressPermissions(cdp) {
   }
 }
 
+/**
+ * Firefox path for connect(): launch Firefox, open a BiDi session, and return
+ * a BiDi-backed page object. Separate from the CDP path because the transport,
+ * ref model, and AX-tree source all differ (see firefox-page.js). close() is
+ * wrapped to also reap the Firefox process + temp profile.
+ *
+ * Chromium-only options NOT applied on this path: `consent` (auto-dismiss),
+ * `blockAds`/`blockUrls`, stealth patches, and `hybrid` mode. `saveState`,
+ * `waitForNavigation`, `waitForNetworkIdle`, and download/dialog capture are
+ * CDP-only too (the page object stubs them — see firefox-page.js). The
+ * navigation guard (`allowLocalUrls`/`blockPrivateNetwork`), `uploadDir`
+ * sandbox, `incognito`, `proxy`, `viewport`, and `pruneMode` DO apply.
+ * @param {object} opts - connect() options ({ mode, proxy, binary, viewport, pruneMode, urlGuard, uploadDir, incognito })
+ * @returns {Promise<object>} Firefox page object
+ */
+async function connectFirefox(opts) {
+  const browser = await launchFirefox({
+    headed: opts.mode === 'headed',
+    proxy: opts.proxy,
+    binary: opts.binary,
+    viewport: opts.viewport,
+  });
+  const bidi = await createBiDi(browser.wsUrl);
+  const page = await createFirefoxPage(bidi, {
+    pruneMode: opts.pruneMode,
+    urlGuard: { allowLocalUrls: opts.allowLocalUrls, blockPrivateNetwork: opts.blockPrivateNetwork },
+    uploadDir: opts.uploadDir || null,
+    incognito: !!opts.incognito,
+  });
+  const closePage = page.close.bind(page);
+  page.close = async () => {
+    await closePage();
+    await cleanupFirefox(browser);
+  };
+  return page;
+}
+
 /**
  * Create a new page target and return a session-scoped handle.
  * @param {object} cdp - CDP client

package/src/readable.js

@@ -72,21 +72,21 @@ export function formatReadable(r) {
 }
 
 /**
- * Extract the main article from the current page.
- * @param {object} session - CDP session-scoped handle (.send()).
- * @returns {Promise<object>} One of:
- *   { ok: false, hint }                              — no article content found
- *   { ok: true, title, byline, text, length,
- *     confidence: 'high'|'low', readerable, hint? }  — extracted article
+ * The in-page extraction expression (Readability injected + run). Exported so
+ * non-CDP transports (BiDi/Firefox) can evaluate the same source and feed the
+ * raw result through finalizeReadable() — keeping every engine's output
+ * identical.
  */
-export async function readable(session) {
-  const { result } = await session.send('Runtime.evaluate', {
-    expression: EXTRACT_EXPRESSION,
-    returnByValue: true,
-    awaitPromise: true,
-  });
-  const r = result.value || {};
+export { EXTRACT_EXPRESSION };
 
+/**
+ * Turn the raw in-page extraction result into the public readable() shape,
+ * applying the advisory confidence rule. Transport-agnostic.
+ * @param {object} r - raw result from EXTRACT_EXPRESSION
+ * @returns {object} public readable() result
+ */
+export function finalizeReadable(r) {
+  r = r || {};
   if (!r.ok) {
     return {
       ok: false,
@@ -95,22 +95,34 @@ export async function readable(session) {
         : 'no article content found on this page; use snapshot() instead',
     };
   }
-
   // Advisory confidence: high only when the reader-view heuristic agrees AND
   // there is a substantial amount of text. Low is not an error — the text is
   // still returned; it just means "verify, or prefer snapshot()".
   const confidence = r.readerable && r.length >= MIN_ARTICLE_CHARS ? 'high' : 'low';
   const out = {
     ok: true,
-    title: r.title,
-    byline: r.byline,
-    text: r.text,
-    length: r.length,
-    readerable: r.readerable,
-    confidence,
+    title: r.title, byline: r.byline, text: r.text, length: r.length,
+    readerable: r.readerable, confidence,
   };
   if (confidence === 'low') {
     out.hint = 'low article confidence — this may not be an article; consider snapshot()';
   }
   return out;
 }
+
+/**
+ * Extract the main article from the current page.
+ * @param {object} session - CDP session-scoped handle (.send()).
+ * @returns {Promise<object>} One of:
+ *   { ok: false, hint }                              — no article content found
+ *   { ok: true, title, byline, text, length,
+ *     confidence: 'high'|'low', readerable, hint? }  — extracted article
+ */
+export async function readable(session) {
+  const { result } = await session.send('Runtime.evaluate', {
+    expression: EXTRACT_EXPRESSION,
+    returnByValue: true,
+    awaitPromise: true,
+  });
+  return finalizeReadable(result.value || {});
+}

package/types/auth.d.ts

@@ -25,9 +25,26 @@ export function injectCookies(session: object, cookies: Array<object>): Promise<
  * @returns {boolean}
  */
 export function cookieDomainMatch(host: string, cookieDomain: string): boolean;
+/**
+ * Select the user's cookies that are in-scope for `url`. Shared by BOTH engines
+ * (CDP `authenticate` and Firefox/BiDi `injectCookies`) so they can't drift on
+ * scoping — a divergence here re-opens loading the entire cookie jar into an
+ * agent session. Returns the filtered cookie array; never injects.
+ *
+ * Coarse SQL pre-filter strips 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 is what actually decides which
+ * cookies pass. Without it, browsing apple.com would match apple.com.evil.org
+ * and every *.co.uk site (verified).
+ * @param {string} url - URL whose host the cookies must match
+ * @param {object} [opts] - passed to extractCookies (e.g. { browser })
+ * @returns {Array<object>} cookies whose domain matches the URL host
+ */
+export function scopedCookiesForUrl(url: string, opts?: object): Array<object>;
 /**
  * Extract cookies for a URL and inject them into a CDP session.
- * Convenience function combining extractCookies + injectCookies.
+ * Convenience function combining scopedCookiesForUrl + injectCookies.
  * @param {object} session - CDP session handle
  * @param {string} url - URL to extract cookies for
  * @param {object} [opts] - Options passed to extractCookies

package/types/ax-snapshot.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Build the script.evaluate expression that reconstructs the AX tree in a
+ * context, assigning refs from `base`.
+ * @param {number} base - Starting ref offset (exclusive; first ref is base+1)
+ * @returns {string} JS expression returning JSON { tree, count }
+ */
+export function axSnapshotExpression(base: number): string;
+/**
+ * ax-snapshot.js — Reconstruct a CDP-shaped accessibility tree in-page.
+ *
+ * CDP hands you Accessibility.getFullAXTree; BiDi has no equivalent, so on
+ * Firefox we rebuild an equivalent tree inside the page via script.evaluate.
+ * The output tree uses the SAME node shape and role vocabulary as
+ * buildTree()'s CDP output, so prune.js and aria.js consume it unchanged:
+ *
+ *   { nodeId, role, name, properties, children, ignored }
+ *
+ * where `role` is CDP/ARIA vocabulary ('RootWebArea', 'StaticText', 'heading',
+ * 'link', 'button', 'img', 'paragraph', 'list', 'navigation', …), NOT tag
+ * names. The three things getFullAXTree gave us for free and we reimplement:
+ *   1. implicit ARIA role mapping (HTML element → role)
+ *   2. accessible-name computation (aria-labelledby → aria-label → native
+ *      label/alt/legend/title → text content) — the POC proved textContent
+ *      alone is NOT enough (img alt, <label>, aria-labelledby all missed).
+ *   3. hidden-subtree filtering (aria-hidden, display:none, visibility:hidden,
+ *      the hidden attribute).
+ *
+ * Each kept element is tagged with a data-bb-ref attribute carrying its ref,
+ * so firefox-page.js (resolveRef) can resolve a ref back to its element via
+ * querySelector.
+ * Refs are assigned from a caller-supplied `base` so they stay globally unique
+ * across browsing contexts (iframes), matching CDP's flat integer refs.
+ */
+/** Attribute used to tag elements for ref → element resolution. */
+export const REF_ATTR: "data-bb-ref";

package/types/bidi.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Create a BiDi client connected to the given /session WebSocket URL and open
+ * a session. Firefox prints its BiDi endpoint to stderr as
+ * "WebDriver BiDi listening on ws://HOST:PORT"; the direct-connection socket
+ * (no WebDriver-classic handshake) lives at that URL + "/session".
+ *
+ * @param {string} wsUrl - BiDi session WebSocket URL (ws://HOST:PORT/session)
+ * @returns {Promise<object>} BiDi client ({ send, evaluate, on, once, subscribe, sessionId, close })
+ */
+export function createBiDi(wsUrl: string): Promise<object>;

package/types/daemon.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Build the argv for the detached daemon child. Pure + exported so the
+ * flag-forwarding contract is unit-testable: a forward that's silently
+ * dropped here (as `--incognito` was in v0.15.0, turning `open --incognito`
+ * into a fully-authenticated session) becomes a failing test, not a leak.
+ * @param {object} opts - the session options parsed in cli.js cmdOpen
+ * @param {string} absDir - resolved output directory
+ * @param {string|undefined} initialUrl - URL to navigate on start (may be undefined)
+ * @param {string} cliPath - path to cli.js for the child to run
+ * @returns {string[]}
+ */
+export function buildDaemonArgs(opts: object, absDir: string, initialUrl: string | undefined, cliPath: string): string[];
 /**
  * Spawn a detached child process that runs the daemon.
  * Parent polls for session.json, then exits.

package/types/firefox-page.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Build a Firefox/BiDi-backed page object.
+ * @param {object} bidi - BiDi client from createBiDi()
+ * @param {object} [opts]
+ * @param {'act'|'browse'|'navigate'|'full'|'read'} [opts.pruneMode='act'] - Default prune mode.
+ * @param {{allowLocalUrls?: boolean, blockPrivateNetwork?: boolean}} [opts.urlGuard] - Navigation safety policy, applied on every goto().
+ * @param {string} [opts.uploadDir] - When set, upload() rejects files outside this dir.
+ * @param {boolean} [opts.incognito=false] - Clean session: injectCookies() is a no-op.
+ * @returns {Promise<object>} page object
+ */
+export function createFirefoxPage(bidi: object, opts?: {
+    pruneMode?: "act" | "browse" | "navigate" | "full" | "read" | undefined;
+    urlGuard?: {
+        allowLocalUrls?: boolean;
+        blockPrivateNetwork?: boolean;
+    } | undefined;
+    uploadDir?: string | undefined;
+    incognito?: boolean | undefined;
+}): Promise<object>;

package/types/firefox.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Find the first available Firefox binary on the system.
+ * @returns {string} Path to the binary
+ * @throws {Error} If no Firefox is found
+ */
+export function findFirefox(): string;
+/**
+ * Launch Firefox with WebDriver BiDi enabled and return its session WS URL.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.binary] - Firefox binary (auto-detected if omitted)
+ * @param {number} [opts.port=0] - Remote-agent port (0 = OS-assigned)
+ * @param {boolean} [opts.headed=false] - Launch with a visible window
+ * @param {string} [opts.proxy] - Proxy 'host:port' or 'scheme://host:port'
+ *   (http/https → HTTP+SSL proxy; socks/socks5/socks4 → SOCKS), via prefs
+ * @param {{width:number,height:number}} [opts.viewport] - Initial window size
+ * @returns {Promise<{wsUrl: string, process: import('node:child_process').ChildProcess, port: number, ownedProfileDir: string}>}
+ */
+export function launchFirefox(opts?: {
+    binary?: string | undefined;
+    port?: number | undefined;
+    headed?: boolean | undefined;
+    proxy?: string | undefined;
+    viewport?: {
+        width: number;
+        height: number;
+    } | undefined;
+}): Promise<{
+    wsUrl: string;
+    process: import("node:child_process").ChildProcess;
+    port: number;
+    ownedProfileDir: string;
+}>;
+/**
+ * Kill a launched Firefox and remove its temp profile dir.
+ * @param {{process: import('node:child_process').ChildProcess, ownedProfileDir?: string}} browser
+ */
+export function cleanupFirefox(browser: {
+    process: import("node:child_process").ChildProcess;
+    ownedProfileDir?: string;
+}): Promise<void>;

package/types/index.d.ts

@@ -6,6 +6,8 @@
  * @param {object} [opts]
  * @param {'headless'|'headed'|'hybrid'} [opts.mode='headless'] - Browser mode
  * @param {boolean} [opts.cookies=true] - Inject user's cookies (Phase 2)
+ * @param {boolean} [opts.incognito=false] - Clean, unauthenticated session:
+ *   skip cookie/auth injection entirely (equivalent to cookies:false here).
  * @param {boolean} [opts.prune=true] - Apply ARIA pruning (Phase 2)
  * @param {number} [opts.timeout=30000] - Navigation timeout in ms
  * @param {boolean} [opts.blockAds=true] - Block ~120 common ad/tracker
@@ -27,8 +29,9 @@
  * @returns {Promise<string>} ARIA snapshot text
  */
 export function browse(url: string, opts?: {
-    mode?: "headless" | "headed" | "hybrid" | undefined;
+    mode?: "headed" | "headless" | "hybrid" | undefined;
     cookies?: boolean | undefined;
+    incognito?: boolean | undefined;
     prune?: boolean | undefined;
     timeout?: number | undefined;
     blockAds?: boolean | undefined;
@@ -83,11 +86,17 @@ export function browse(url: string, opts?: {
  * @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 {boolean} [opts.incognito=false] - Clean, unauthenticated session:
+ *   skip storageState loading and make injectCookies() a no-op, so no auth
+ *   ever enters the session even if a caller injects unconditionally.
  * @param {'act'|'browse'|'navigate'|'full'|'read'} [opts.pruneMode='act'] - Pruning mode.
+ * @param {'chromium'|'firefox'} [opts.engine='chromium'] - Browser engine.
+ *   'firefox' drives over WebDriver BiDi (a separate transport / page object);
+ *   'chromium' (default) uses CDP.
  * @returns {Promise<object>} Page handle with goto, snapshot, close
  */
 export function connect(opts?: {
-    mode?: "headless" | "headed" | "hybrid" | undefined;
+    mode?: "headed" | "headless" | "hybrid" | undefined;
     port?: number | undefined;
     downloadPath?: string | undefined;
     blockAds?: boolean | undefined;
@@ -104,7 +113,9 @@ export function connect(opts?: {
     } | undefined;
     consent?: boolean | undefined;
     storageState?: string | undefined;
+    incognito?: boolean | undefined;
     pruneMode?: "act" | "browse" | "navigate" | "full" | "read" | undefined;
+    engine?: "chromium" | "firefox" | undefined;
 }): Promise<object>;
 /**
  * Apply Network.setBlockedURLs for ad/tracker blocking on a session.

package/types/readable.d.ts

@@ -7,6 +7,13 @@
  * @returns {string}
  */
 export function formatReadable(r: object): string;
+/**
+ * Turn the raw in-page extraction result into the public readable() shape,
+ * applying the advisory confidence rule. Transport-agnostic.
+ * @param {object} r - raw result from EXTRACT_EXPRESSION
+ * @returns {object} public readable() result
+ */
+export function finalizeReadable(r: object): object;
 /**
  * Extract the main article from the current page.
  * @param {object} session - CDP session-scoped handle (.send()).
@@ -16,3 +23,4 @@ export function formatReadable(r: object): string;
  *     confidence: 'high'|'low', readerable, hint? }  — extracted article
  */
 export function readable(session: object): Promise<object>;
+export const EXTRACT_EXPRESSION: string;