barebrowse 0.14.0 → 0.17.0

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/consent-firefox.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Try to dismiss a cookie consent dialog in a reconstructed Firefox AX tree.
+ *
+ * @param {object} root - Spliced AX tree root (from firefox-page's buildTree).
+ * @param {(ref: string) => Promise<void>} click - Clicks the element for a ref
+ *   (firefox-page injects one that routes to pointerClick / performActions).
+ * @returns {Promise<boolean>} true if an accept button was found and clicked.
+ */
+export function dismissConsentFirefox(root: object, click: (ref: string) => Promise<void>): Promise<boolean>;

package/types/consent-patterns.d.ts

@@ -0,0 +1,12 @@
+/**
+ * consent-patterns.js — Shared cookie-consent detection data.
+ *
+ * The engine-agnostic half of consent handling: the multilingual regex sets
+ * and dialog roles used to recognise a consent dialog and its "accept" button.
+ * Both the CDP walker (consent.js) and the BiDi walker (consent-firefox.js)
+ * import these so the language coverage is single-sourced — a new language or
+ * pattern is added once and both engines get it.
+ */
+export const ACCEPT_PATTERNS: RegExp[];
+export const DIALOG_ROLES: Set<string>;
+export const CONSENT_DIALOG_HINTS: RegExp[];

package/types/daemon.d.ts

@@ -1,3 +1,37 @@
+/**
+ * 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[];
+/**
+ * Wire Firefox/BiDi console + network capture onto the daemon's log arrays.
+ * The BiDi analogue of the CDP `Runtime.consoleAPICalled` / `Network.*`
+ * capture — measured event shapes: `log.entryAdded` carries {method, level,
+ * args:[{type,value}], text}; the network events key in-flight requests by
+ * `request.request` and expose `response.{status,statusText,mimeType}` /
+ * top-level `errorText`. Pure + exported so the shape mapping (warn→warning
+ * normalization, arg extraction, orphan-safe response/error pairing) is
+ * unit-testable against a fake bidi without launching Firefox.
+ *
+ * @param {object} bidi - BiDi client (async .subscribe(), .on(method, cb))
+ * @param {object} sinks
+ * @param {Array} sinks.consoleLogs - push-target for console entries
+ * @param {Array} sinks.networkLogs - push-target for completed/failed requests
+ * @param {Map} sinks.pendingRequests - in-flight request bookkeeping
+ * @returns {Promise<void>}
+ */
+export function attachBiDiCapture(bidi: object, { consoleLogs, networkLogs, pendingRequests }: {
+    consoleLogs: any[];
+    networkLogs: any[];
+    pendingRequests: Map<any, any>;
+}): Promise<void>;
 /**
  * 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,21 @@
+/**
+ * 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.
+ * @param {boolean} [opts.consent=true] - Auto-dismiss cookie consent dialogs after goto().
+ * @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;
+    consent?: 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/network-idle.d.ts

@@ -1,12 +1,5 @@
 /**
- * network-idle.js — wait until the page's network has been idle for N ms.
- *
- * Tracks in-flight requests by requestId in a Set, so an orphan
- * loadingFinished/Failed (event for a request whose requestWillBeSent
- * arrived before our listener attached) is a harmless no-op instead of
- * driving a counter negative and resolving prematurely.
- */
-/**
+ * CDP: wait for network idle over `Network.*` events.
  * @param {object} session - CDP session-scoped handle with .on() returning unsub
  * @param {object} [opts]
  * @param {number} [opts.timeout=30000] - Max wait time before reject
@@ -17,3 +10,18 @@ export function waitForNetworkIdle(session: object, opts?: {
     timeout?: number | undefined;
     idle?: number | undefined;
 }): Promise<void>;
+/**
+ * Firefox/BiDi: wait for network idle over `network.*` events. Subscribes the
+ * events first (idempotent — safe even if the daemon already subscribed for
+ * log capture), then runs the same orphan-resilient idle loop. The in-flight
+ * key is `params.request.request` (the BiDi request id).
+ * @param {object} bidi - BiDi client with async .subscribe() and .on() returning unsub
+ * @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 waitForNetworkIdleBiDi(bidi: object, opts?: {
+    timeout?: number | undefined;
+    idle?: number | undefined;
+}): Promise<void>;

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;

package/types/stealth-firefox.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Register the Firefox stealth patches so they run before any page script.
+ * Must be called before the first navigation. addPreloadScript is global
+ * (applies to every browsing context / navigation), so a single registration
+ * covers the whole session.
+ *
+ * @param {object} bidi - BiDi client from createBiDi()
+ */
+export function applyFirefoxStealth(bidi: object): Promise<void>;

package/types/stealth.d.ts

@@ -12,3 +12,34 @@
  * @param {object} session - Session-scoped CDP handle
  */
 export function applyStealth(session: object): Promise<void>;
+/**
+ * stealth.js — Anti-detection patches for headless Chromium.
+ *
+ * Uses Page.addScriptToEvaluateOnNewDocument so patches run before
+ * any page scripts (unlike Runtime.evaluate which runs after).
+ */
+/**
+ * navigator.webdriver hiding — the one automation tell shared by every engine
+ * (Chromium headless AND Firefox-under-BiDi both report `true`). Split out so
+ * the Firefox stealth path (stealth-firefox.js) reuses the exact same patch
+ * instead of duplicating it. Measured baseline on both engines: `true`.
+ *
+ * A naive `Object.defineProperty(navigator, 'webdriver', …)` hides the *value*
+ * but leaves an advanced tell: it creates an OWN property on the instance, so
+ * `navigator.hasOwnProperty('webdriver')` becomes `true` where a real browser
+ * (property lives on Navigator.prototype) reports `false` — sophisticated
+ * anti-bot checks (e.g. sannysoft's "WebDriver New") catch that inconsistency.
+ * So we DELETE the getter off the prototype instead: then `navigator.webdriver`
+ * is `undefined` AND `'webdriver' in navigator` AND `hasOwnProperty` are both
+ * `false`, matching a stock browser. POC-verified on Chromium and Firefox
+ * (own/in both false, prototype descriptor gone). The defineProperty fallback
+ * only fires if the descriptor is somehow non-configurable (delete a no-op).
+ */
+export const WEBDRIVER_PATCH: "\n  try {\n    const proto = Object.getPrototypeOf(navigator);\n    const desc = proto && Object.getOwnPropertyDescriptor(proto, 'webdriver');\n    if (desc && desc.configurable) delete proto.webdriver;\n    if (navigator.webdriver) {\n      Object.defineProperty(navigator, 'webdriver', { get: () => undefined, configurable: true });\n    }\n  } catch {}\n";
+/**
+ * Canvas-fingerprint noise — browser-agnostic (standard Canvas2D API), so both
+ * the Chromium and Firefox stealth scripts compose it. This block carries the
+ * subtle double-XOR-cancellation fixes (see git history / project memory); keep
+ * it SINGLE-SOURCED here so a fix never has to be made in two places.
+ */
+export const CANVAS_NOISE_PATCH: "\n  // Canvas fingerprinting \u2014 sites render standard text/shapes, then read\n  // pixels via toDataURL or getImageData. The output is stable per machine\n  // (GPU, font rasterizer, anti-aliasing) but unique across machines, which\n  // makes it the second-most-common fingerprint after WebGL. Defense: nudge\n  // a few RGB channels by \u00B11 per session so the hash changes each visit\n  // while the canvas still looks identical to the human eye. The per-tab\n  // seed keeps reads stable within a session so legitimate canvas use\n  // (image processing, games) doesn't flicker.\n  // crypto.getRandomValues is guaranteed unique per browsing context; using\n  // Math.random alone can collide when two fresh V8 contexts start within\n  // microseconds of each other (real-world: parallel tests, real-world hit:\n  // we observed it). performance.now adds a wall-clock anchor as a belt-and-\n  // braces guard against contexts where crypto is somehow stubbed.\n  const _seedBuf = new Uint32Array(1);\n  crypto.getRandomValues(_seedBuf);\n  const CANVAS_SEED = (_seedBuf[0] ^ ((performance.now() * 1e6) | 0)) >>> 0;\n  function shiftPixels(data) {\n    // Touch ~1 byte per 64-byte stride. The bit we XOR with is taken from a\n    // position-dependent SLICE of a seed-mixed hash, not its low bit \u2014 a\n    // naive 'mix & 1' collapses to only two possible outputs per seed\n    // parity because every stride index is even (the position multiplier\n    // is odd, so the low bit only depends on seed parity). Indexing the\n    // hash by (i/64) mod 32 makes every stride position sample a different\n    // bit, so two distinct seeds produce different mask patterns.\n    for (let i = 0; i < data.length; i += 64) {\n      const h = ((CANVAS_SEED * 2654435761) ^ (i * 1597334677)) >>> 0;\n      const bit = (h >>> ((i >>> 6) & 31)) & 1;\n      data[i] = (data[i] ^ bit) & 0xff;\n    }\n    return data;\n  }\n  // Capture originals BEFORE replacing \u2014 toDataURL must read pixels via the\n  // native getImageData (not the patched one), otherwise the patch double-\n  // applies and the second XOR cancels the first, leaving output unchanged.\n  const origGetImageData = CanvasRenderingContext2D.prototype.getImageData;\n  const origToDataURL = HTMLCanvasElement.prototype.toDataURL;\n  HTMLCanvasElement.prototype.toDataURL = function() {\n    const ctx = this.getContext('2d');\n    if (ctx && this.width > 0 && this.height > 0) {\n      try {\n        const img = origGetImageData.call(ctx, 0, 0, this.width, this.height);\n        // Snapshot the original bytes so we can restore them after encoding.\n        // Without this, repeated toDataURL() alternates noisy/clean: call 1\n        // XORs the canvas in place, call 2 reads the noisy canvas and XORs\n        // again (self-inverse), call 3 again, etc. Same XOR-cancellation\n        // class as the earlier double-apply bug, just through canvas state\n        // rather than method composition. The restore also keeps the\n        // bitmap idempotent for any downstream legitimate canvas reads.\n        const original = new Uint8ClampedArray(img.data);\n        shiftPixels(img.data);\n        ctx.putImageData(img, 0, 0);\n        const result = origToDataURL.apply(this, arguments);\n        img.data.set(original);\n        ctx.putImageData(img, 0, 0);\n        return result;\n      } catch {\n        // Tainted canvas (cross-origin image) \u2014 can't read; skip the nudge\n        // and fall through to the original call so the page sees the\n        // expected SecurityError instead of silent corruption.\n      }\n    }\n    return origToDataURL.apply(this, arguments);\n  };\n  CanvasRenderingContext2D.prototype.getImageData = function() {\n    const img = origGetImageData.apply(this, arguments);\n    shiftPixels(img.data);\n    return img;\n  };\n";