browser-commander 0.19.0 → 0.21.0

package/src/browser/browser-cookies.js

@@ -92,7 +92,8 @@ function readChromiumRows(database, domainFilter) {
   );
 }
 
-function mapFirefoxRows(rows) {
+/** Map `moz_cookies` rows to cookies; profile migration reuses this too. */
+export function mapFirefoxCookieRows(rows) {
   return rows.map((row) => ({
     name: row.name,
     value: row.value,
@@ -306,7 +307,9 @@ export async function readBrowserCookiesWithDependencies(
   let cookies;
   try {
     if (browser === 'firefox') {
-      cookies = mapFirefoxRows(readFirefoxRows(database, options.domainFilter));
+      cookies = mapFirefoxCookieRows(
+        readFirefoxRows(database, options.domainFilter)
+      );
     } else {
       const databaseVersion = readDatabaseVersion(database);
       const rows = readChromiumRows(database, options.domainFilter);

package/src/browser/cdp-session.js

@@ -0,0 +1,94 @@
+/**
+ * Raw Chrome DevTools Protocol sessions with one surface for both engines
+ * (issue #104).
+ *
+ * Rust has chromiumoxide and raw CDP; this module gives JavaScript the same
+ * `cdpSession` API: `send(method, params)`, `on(event, fn)`, `off(event, fn)`
+ * and `detach()`, whether the page belongs to Playwright or Puppeteer.
+ */
+import { detectEngine } from '../core/engine-detection.js';
+import { createCdpSession as openEngineCdpSession } from '../fingerprint/apply.js';
+
+/**
+ * Wrap an engine CDP session in the uniform surface.
+ *
+ * @param {Object} session - Playwright or Puppeteer `CDPSession`
+ * @param {'playwright'|'puppeteer'} engine
+ * @returns {CdpSession}
+ */
+export function wrapCdpSession(session, engine) {
+  let detached;
+  const wrapper = {
+    engine,
+    /** The engine's own `CDPSession`, for anything not covered here. */
+    session,
+    /** Send a CDP command and resolve with its result. */
+    send: (method, params = {}) => session.send(method, params),
+    /** Listen to a CDP event, such as `Network.requestWillBeSent`. */
+    on(event, listener) {
+      session.on(event, listener);
+      return wrapper;
+    },
+    /** Listen to one occurrence of a CDP event. */
+    once(event, listener) {
+      session.once(event, listener);
+      return wrapper;
+    },
+    /** Stop listening to a CDP event. */
+    off(event, listener) {
+      session.off(event, listener);
+      return wrapper;
+    },
+    /** Detach the session; calling it again is a no-op. */
+    detach() {
+      detached ??= Promise.resolve(session.detach());
+      return detached;
+    },
+  };
+  return wrapper;
+}
+
+function isLegacyOptions(value) {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    'page' in value &&
+    typeof value.goto !== 'function'
+  );
+}
+
+/**
+ * Open a raw CDP session for a page.
+ *
+ * Playwright opens it with `page.context().newCDPSession(page)`, Puppeteer
+ * with `page.createCDPSession()`. Both are returned with the same methods.
+ * The older `createCdpSession({browser, page, engine})` form is accepted too.
+ *
+ * @param {Object} page - Playwright or Puppeteer page
+ * @param {Object} [options]
+ * @param {'playwright'|'puppeteer'} [options.engine] - Detected from the page when omitted
+ * @param {Object} [options.browser] - Playwright context to open the session on
+ * @returns {Promise<CdpSession>}
+ *
+ * @typedef {Object} CdpSession
+ * @property {string} engine
+ * @property {Object} session
+ * @property {function(string, Object=): Promise<Object>} send
+ * @property {function(string, Function): CdpSession} on
+ * @property {function(string, Function): CdpSession} once
+ * @property {function(string, Function): CdpSession} off
+ * @property {function(): Promise<void>} detach
+ */
+export async function createCdpSession(page, options = {}) {
+  const request = isLegacyOptions(page) ? page : { ...options, page };
+  if (!request.page) {
+    throw new Error('createCdpSession requires a page');
+  }
+  const engine = request.engine ?? detectEngine(request.page);
+  const session = await openEngineCdpSession({
+    browser: request.browser,
+    page: request.page,
+    engine,
+  });
+  return wrapCdpSession(session, engine);
+}

package/src/browser/connector.js

@@ -5,12 +5,21 @@ import {
   restorePuppeteerStorageState,
 } from './storage-state.js';
 
-function validateConnectionOptions({ engine, cdpEndpoint, wsEndpoint }) {
+/**
+ * Throw unless `engine` is one Browser Commander drives.
+ *
+ * @param {string} engine
+ */
+export function assertSupportedEngine(engine) {
   if (!['playwright', 'puppeteer'].includes(engine)) {
     throw new Error(
       `Invalid engine: ${engine}. Expected 'playwright' or 'puppeteer'`
     );
   }
+}
+
+function validateConnectionOptions({ engine, cdpEndpoint, wsEndpoint }) {
+  assertSupportedEngine(engine);
 
   if (Boolean(cdpEndpoint) === Boolean(wsEndpoint)) {
     throw new Error(
@@ -66,6 +75,33 @@ async function prepareStorageState({ storageState, seedCookies }) {
   };
 }
 
+/**
+ * Pick the tab that is on screen.
+ *
+ * A browser attached after it started can already have several tabs - a fresh
+ * Chrome profile opens "What's new" next to the New Tab page - and neither
+ * engine lists them in a stable order. Driving a background tab would make
+ * `document.hidden` true where a person's first navigation would see a visible
+ * page, so the visible tab wins and the first tab is the fallback.
+ *
+ * @param {Object[]} pages - Engine page handles
+ * @returns {Promise<Object|undefined>}
+ */
+export async function pickForegroundPage(pages) {
+  for (const page of pages) {
+    if (typeof page?.evaluate !== 'function') {
+      continue;
+    }
+    const state = await page
+      .evaluate(() => document.visibilityState)
+      .catch(() => null);
+    if (state === 'visible') {
+      return page;
+    }
+  }
+  return pages[0];
+}
+
 async function connectPlaywright({ options, loadPlaywright, storageState }) {
   const { chromium } = await loadPlaywright();
   const endpoint = options.cdpEndpoint ?? options.wsEndpoint;
@@ -77,7 +113,8 @@ async function connectPlaywright({ options, loadPlaywright, storageState }) {
   if (!context) {
     throw new Error('Connected Playwright browser has no default context');
   }
-  const page = context.pages()[0] ?? (await context.newPage());
+  const page =
+    (await pickForegroundPage(context.pages())) ?? (await context.newPage());
 
   await restorePlaywrightStorageState({ context, storageState });
   return { browser, page };
@@ -89,8 +126,9 @@ async function connectPuppeteer({ options, loadPuppeteer, storageState }) {
   const browser = await puppeteer.connect(
     buildPuppeteerConnectOptions(options)
   );
-  const pages = await browser.pages();
-  const page = pages[0] ?? (await browser.newPage());
+  const page =
+    (await pickForegroundPage(await browser.pages())) ??
+    (await browser.newPage());
 
   await restorePuppeteerStorageState({ page, storageState });
   return { browser, page };

package/src/browser/debugging-port.js

@@ -0,0 +1,155 @@
+import net from 'node:net';
+
+/**
+ * A fixed, non-zero `--remote-debugging-port` is the only CDP transport that
+ * leaves `navigator.webdriver` false without the unsupported
+ * `--disable-blink-features=AutomationControlled` switch: Chromium's
+ * `content/child/runtime_features.cc` treats `--remote-debugging-pipe` and
+ * `--remote-debugging-port=0` as automation, but a specific port as a human
+ * attaching a debugger (issue #101).
+ *
+ * The port is reserved by binding `127.0.0.1:0`, reading the port the kernel
+ * picked and closing the socket. Another process can take the port between
+ * that close and Chrome's bind, so the launcher confirms ownership and retries.
+ *
+ * Chrome only writes `DevToolsActivePort` into the profile for port 0 (see
+ * `chrome/browser/devtools/remote_debugging_server.cc`), so for a fixed port
+ * ownership is confirmed from the line Chromium prints to stderr when its
+ * DevTools server starts:
+ *
+ *     DevTools listening on ws://127.0.0.1:<port>/devtools/browser/<id>
+ *
+ * When the loopback port is taken Chromium logs `bind() failed: Address
+ * already in use` and falls back to `[::1]:<port>` (measured with Chrome 153,
+ * experiments/issue-105/port-race.mjs); when both fail it logs `Cannot start
+ * http server for devtools`. Either outcome is reported as a race.
+ */
+
+export const LOOPBACK_HOST = '127.0.0.1';
+
+/** Thrown when the reserved port was taken before the browser could bind it. */
+export class PortRaceError extends Error {
+  constructor(port, detail) {
+    super(
+      `Remote debugging port ${port} was taken by another process before the browser bound it${detail ? ` (${detail})` : ''}`
+    );
+    this.name = 'PortRaceError';
+    this.port = port;
+  }
+}
+
+/**
+ * Reserve a free loopback TCP port for `--remote-debugging-port`.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.host='127.0.0.1'] - Interface to bind while reserving
+ * @returns {Promise<number>} A port that was free a moment ago
+ */
+export async function reserveLoopbackPort({ host = LOOPBACK_HOST } = {}) {
+  return await new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.unref();
+    server.once('error', reject);
+    server.listen({ port: 0, host, exclusive: true }, () => {
+      const { port } = server.address();
+      server.close((error) => (error ? reject(error) : resolve(port)));
+    });
+  });
+}
+
+/** Validate a caller-supplied debugging port; zero is refused on purpose. */
+export function assertFixedDebuggingPort(port) {
+  if (port === 0) {
+    throw new RangeError(
+      'remoteDebuggingPort 0 makes Chrome enable AutomationControlled (navigator.webdriver === true); omit it so a free fixed port is reserved'
+    );
+  }
+  if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+    throw new RangeError(
+      'remoteDebuggingPort must be an integer from 1 to 65535'
+    );
+  }
+  return port;
+}
+
+const LISTENING_PATTERN =
+  /DevTools listening on (ws:\/\/(\[[^\]]+\]|[^:/\s]+):(\d+)\/devtools\/browser\/[^\s]+)/;
+// A bare `bind() failed` can come from unrelated sockets (media router, mDNS),
+// so only DevTools' own give-up message counts as a failure on its own.
+const BIND_FAILURE_PATTERN = /Cannot start http server for devtools/i;
+
+/**
+ * Parse Chromium's DevTools startup output.
+ *
+ * @param {string} text - Browser stderr collected so far
+ * @returns {{listening: {url: string, host: string, port: number}|null, bindFailed: boolean}}
+ */
+export function parseDevToolsOutput(text) {
+  const match = LISTENING_PATTERN.exec(text);
+  return {
+    listening: match
+      ? {
+          url: match[1],
+          host: match[2].replace(/^\[|\]$/g, ''),
+          port: Number(match[3]),
+        }
+      : null,
+    bindFailed: BIND_FAILURE_PATTERN.test(text),
+  };
+}
+
+/**
+ * Collect a browser's stderr so the launcher can confirm which process owns
+ * the debugging port. The stream keeps being drained after startup so a
+ * chatty browser never blocks on a full pipe.
+ *
+ * @param {Object|null|undefined} stream - Browser stderr
+ * @param {Object} [options]
+ * @param {boolean} [options.forward=false] - Also copy the output to process.stderr
+ * @returns {{available: boolean, state: function(): Object}}
+ */
+export function watchDevToolsOutput(stream, { forward = false } = {}) {
+  if (!stream || typeof stream.on !== 'function') {
+    return {
+      available: false,
+      state: () => ({ listening: null, bindFailed: false }),
+    };
+  }
+  let text = '';
+  let settled = null;
+  stream.on('data', (chunk) => {
+    if (forward) {
+      process.stderr.write(chunk);
+    }
+    if (settled) {
+      return;
+    }
+    // Only the startup lines matter; cap the buffer so it cannot grow forever.
+    text = `${text}${chunk}`.slice(-65_536);
+    const parsed = parseDevToolsOutput(text);
+    if (parsed.listening) {
+      settled = parsed;
+    }
+  });
+  return {
+    available: true,
+    state: () => settled ?? parseDevToolsOutput(text),
+  };
+}
+
+/**
+ * Decide whether the DevTools output proves that `port` belongs to our
+ * browser, proves a race, or is not conclusive yet.
+ *
+ * @returns {'owned'|'race'|'pending'}
+ */
+export function classifyDevToolsOwnership(output, port) {
+  const { listening, bindFailed } = output;
+  if (listening) {
+    if (listening.port === port && listening.host === LOOPBACK_HOST) {
+      return 'owned';
+    }
+    return 'race';
+  }
+  return bindFailed ? 'race' : 'pending';
+}

package/src/browser/launch-options.js

@@ -1,24 +1,34 @@
-import { CHROME_ARGS } from '../core/constants.js';
+import {
+  assertStringArray,
+  mergeFeatureSwitches,
+  resolveRestrictions,
+} from './restrictions.js';
 import {
   applyAutomationParityArgs,
   parityIgnoredDefaultArgs,
 } from '../fingerprint/automation-parity.js';
 
-function stringArray(value, name) {
-  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
-    throw new TypeError(`${name} must be an array of strings`);
-  }
-  return value;
-}
-
-/** Resolve Browser Commander defaults, compatibility args, and extra args. */
+/**
+ * Resolve the switches an engine-launched browser gets on top of the engine's
+ * own: opt-in restrictions, then custom args (issue #103). Browser Commander
+ * adds nothing by default; `CHROME_ARGS` is kept only as the
+ * `legacy-defaults` restriction preset.
+ *
+ * @param {Object} [options]
+ * @param {string[]} [options.args]
+ * @param {string[]} [options.extraArgs]
+ * @param {boolean|string[]} [options.ignoreDefaultArgs] - Engine defaults to omit
+ * @param {string[]} [options.restrictions] - Names from launch-restrictions.json
+ * @returns {{args: string[], ignoreDefaultArgs: boolean|string[]}}
+ */
 export function resolveChromeArgs({
   args = [],
   extraArgs = [],
   ignoreDefaultArgs = [],
+  restrictions = [],
 } = {}) {
-  stringArray(args, 'args');
-  stringArray(extraArgs, 'extraArgs');
+  assertStringArray(args, 'args');
+  assertStringArray(extraArgs, 'extraArgs');
   if (
     typeof ignoreDefaultArgs !== 'boolean' &&
     !Array.isArray(ignoreDefaultArgs)
@@ -26,23 +36,16 @@ export function resolveChromeArgs({
     throw new TypeError('ignoreDefaultArgs must be a boolean or string array');
   }
   if (Array.isArray(ignoreDefaultArgs)) {
-    stringArray(ignoreDefaultArgs, 'ignoreDefaultArgs');
+    assertStringArray(ignoreDefaultArgs, 'ignoreDefaultArgs');
   }
 
-  const normalizedIgnoreDefaultArgs =
-    ignoreDefaultArgs === false ? [] : ignoreDefaultArgs;
-  const ignored = new Set(
-    normalizedIgnoreDefaultArgs === true
-      ? CHROME_ARGS
-      : normalizedIgnoreDefaultArgs
-  );
   return {
-    args: [
-      ...CHROME_ARGS.filter((argument) => !ignored.has(argument)),
+    args: mergeFeatureSwitches([
+      ...resolveRestrictions(restrictions).args,
       ...args,
       ...extraArgs,
-    ],
-    ignoreDefaultArgs: normalizedIgnoreDefaultArgs,
+    ]),
+    ignoreDefaultArgs: ignoreDefaultArgs === false ? [] : ignoreDefaultArgs,
   };
 }
 
@@ -56,6 +59,31 @@ function setBrowserSelectionOptions(options, { channel, executablePath }) {
   return options;
 }
 
+/**
+ * The engine default switches to drop: the caller's list plus, with
+ * automation parity, the ones that turn AutomationControlled on.
+ *
+ * @param {'playwright'|'puppeteer'} engine
+ * @returns {true|string[]}
+ */
+function resolveEngineIgnoreDefaultArgs(
+  engine,
+  { headless, ignoreDefaultArgs, automationParity, always = [] }
+) {
+  if (ignoreDefaultArgs === true) {
+    return true;
+  }
+  return [
+    ...new Set([
+      ...always,
+      ...(automationParity
+        ? parityIgnoredDefaultArgs(engine, { headless })
+        : []),
+      ...(ignoreDefaultArgs === false ? [] : ignoreDefaultArgs),
+    ]),
+  ];
+}
+
 export function buildPlaywrightLaunchOptions({
   headless,
   slowMo,
@@ -66,20 +94,12 @@ export function buildPlaywrightLaunchOptions({
   ignoreDefaultArgs = [],
   automationParity = true,
 }) {
-  const normalizedIgnoreDefaultArgs =
-    ignoreDefaultArgs === false ? [] : ignoreDefaultArgs;
-  const engineIgnoreDefaultArgs =
-    normalizedIgnoreDefaultArgs === true
-      ? true
-      : [
-          ...new Set([
-            '--enable-automation',
-            ...(automationParity
-              ? parityIgnoredDefaultArgs('playwright', { headless })
-              : []),
-            ...normalizedIgnoreDefaultArgs,
-          ]),
-        ];
+  const engineIgnoreDefaultArgs = resolveEngineIgnoreDefaultArgs('playwright', {
+    headless,
+    ignoreDefaultArgs,
+    automationParity,
+    always: ['--enable-automation'],
+  });
   const options = {
     headless,
     slowMo,
@@ -105,24 +125,15 @@ export function buildPuppeteerLaunchOptions({
   ignoreDefaultArgs = [],
   automationParity = true,
 }) {
-  const normalizedIgnoreDefaultArgs =
-    ignoreDefaultArgs === false ? [] : ignoreDefaultArgs;
-  const baseArgs = ['--start-maximized', ...chromeArgs];
-  const engineIgnoreDefaultArgs =
-    normalizedIgnoreDefaultArgs === true
-      ? true
-      : [
-          ...new Set([
-            ...(automationParity
-              ? parityIgnoredDefaultArgs('puppeteer', { headless })
-              : []),
-            ...normalizedIgnoreDefaultArgs,
-          ]),
-        ];
+  const engineIgnoreDefaultArgs = resolveEngineIgnoreDefaultArgs('puppeteer', {
+    headless,
+    ignoreDefaultArgs,
+    automationParity,
+  });
   const options = {
     headless,
     defaultViewport: null,
-    args: automationParity ? applyAutomationParityArgs(baseArgs) : baseArgs,
+    args: automationParity ? applyAutomationParityArgs(chromeArgs) : chromeArgs,
     userDataDir,
   };
   if (engineIgnoreDefaultArgs === true || engineIgnoreDefaultArgs.length > 0) {

package/src/browser/launch-restrictions.json

@@ -0,0 +1,147 @@
+{
+  "restrictions": [
+    {
+      "id": "no-first-run",
+      "description": "Skip first-run UI with the switch instead of the First Run sentinel file Browser Commander already writes.",
+      "args": ["--no-first-run"]
+    },
+    {
+      "id": "no-default-browser-check",
+      "description": "Hide the \"Chrome isn't your default browser\" infobar that a hand-started Chrome shows.",
+      "args": ["--no-default-browser-check"]
+    },
+    {
+      "id": "no-crash-restore",
+      "description": "Hide the restore-pages bubble after an unclean exit.",
+      "args": [
+        "--disable-session-crashed-bubble",
+        "--hide-crash-restore-bubble",
+        "--disable-crash-restore"
+      ]
+    },
+    {
+      "id": "no-infobars",
+      "description": "Legacy switch; current Chrome ignores it and still shows the unsupported-flag infobar.",
+      "args": ["--disable-infobars"]
+    },
+    {
+      "id": "basic-password-store",
+      "description": "Store passwords and cookie keys unencrypted instead of in libsecret/KWallet. Real-profile data cannot be decrypted or migrated.",
+      "args": ["--password-store=basic"]
+    },
+    {
+      "id": "mock-keychain",
+      "description": "Use a mock macOS Keychain. Real-profile data cannot be decrypted or migrated.",
+      "args": ["--use-mock-keychain"]
+    },
+    {
+      "id": "no-extensions",
+      "description": "Disable extensions, component extensions with background pages and default apps.",
+      "args": [
+        "--disable-extensions",
+        "--disable-component-extensions-with-background-pages",
+        "--disable-default-apps"
+      ]
+    },
+    {
+      "id": "no-sync",
+      "description": "Disable Chrome sync.",
+      "args": ["--disable-sync"]
+    },
+    {
+      "id": "no-google-services",
+      "description": "Override the built-in Google API keys for the browser process only; disables Chrome sign-in, sync, Safe Browsing and other Google services. The host process environment is never changed.",
+      "env": {
+        "GOOGLE_API_KEY": "no",
+        "GOOGLE_DEFAULT_CLIENT_ID": "no",
+        "GOOGLE_DEFAULT_CLIENT_SECRET": "no"
+      }
+    },
+    {
+      "id": "no-translate",
+      "description": "Disable the Translate feature and its bubble.",
+      "disableFeatures": ["Translate"]
+    },
+    {
+      "id": "no-component-update",
+      "description": "Disable component updates (Widevine, CRLSets, Safe Browsing lists).",
+      "args": ["--disable-component-update"]
+    },
+    {
+      "id": "no-background-networking",
+      "description": "Disable background networking such as variations and update checks.",
+      "args": ["--disable-background-networking"]
+    },
+    {
+      "id": "no-popup-blocking",
+      "description": "Never block popups; pages can observe this.",
+      "args": ["--disable-popup-blocking"]
+    },
+    {
+      "id": "no-phishing-detection",
+      "description": "Disable client-side phishing detection.",
+      "args": ["--disable-client-side-phishing-detection"]
+    },
+    {
+      "id": "no-https-upgrades",
+      "description": "Disable automatic HTTPS upgrades.",
+      "disableFeatures": ["HttpsUpgrades"]
+    },
+    {
+      "id": "no-media-router",
+      "description": "Disable Cast/Media Router and global media controls.",
+      "disableFeatures": [
+        "MediaRouter",
+        "DialMediaRouteProvider",
+        "GlobalMediaControls"
+      ]
+    },
+    {
+      "id": "no-lens",
+      "description": "Disable the Lens overlay.",
+      "disableFeatures": ["LensOverlay"]
+    },
+    {
+      "id": "no-background-throttling",
+      "description": "Keep hidden tabs at full speed; pages can observe this.",
+      "args": [
+        "--disable-background-timer-throttling",
+        "--disable-renderer-backgrounding",
+        "--disable-backgrounding-occluded-windows"
+      ]
+    },
+    {
+      "id": "no-back-forward-cache",
+      "description": "Disable the back/forward cache; pageshow.persisted is always false.",
+      "args": ["--disable-back-forward-cache"]
+    },
+    {
+      "id": "srgb-color-profile",
+      "description": "Force the sRGB colour profile; changes rendered colours.",
+      "args": ["--force-color-profile=srgb"]
+    },
+    {
+      "id": "start-maximized",
+      "description": "Start with a maximized window.",
+      "args": ["--start-maximized"]
+    }
+  ],
+  "presets": {
+    "legacy-defaults": [
+      "no-crash-restore",
+      "no-infobars",
+      "basic-password-store",
+      "no-first-run",
+      "no-default-browser-check"
+    ],
+    "legacy-launch-browser": [
+      "no-crash-restore",
+      "no-infobars",
+      "basic-password-store",
+      "no-first-run",
+      "no-default-browser-check",
+      "no-google-services",
+      "no-translate"
+    ]
+  }
+}