browser-commander 0.16.0 → 0.17.0

package/src/fingerprint/profile.js

@@ -0,0 +1,428 @@
+/**
+ * A fingerprint profile is the complete description of the environment a page
+ * is allowed to see: who the browser claims to be, where it claims to run, and
+ * what hardware it claims to have.
+ *
+ * Every field here is applied through a documented mechanism - a Chrome
+ * switch, a CDP `Emulation` command, or a page init script - and the mechanism
+ * is recorded in `FINGERPRINT_FIELD_MECHANISMS` so callers can tell an
+ * override the browser enforces from an override that is only a JavaScript
+ * patch. See `limitations.js` for the surfaces that have no mechanism at all.
+ */
+
+import { deriveUserAgentData } from './derive.js';
+
+const BRAND_KEYS = ['brand', 'version'];
+
+function fail(message) {
+  throw new TypeError(message);
+}
+
+function optionalString(value, name) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  if (typeof value !== 'string') {
+    fail(`${name} must be a string`);
+  }
+  return value;
+}
+
+function optionalBoolean(value, name) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  if (typeof value !== 'boolean') {
+    fail(`${name} must be a boolean`);
+  }
+  return value;
+}
+
+function optionalPositiveInteger(value, name) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  if (!Number.isInteger(value) || value <= 0) {
+    fail(`${name} must be a positive integer`);
+  }
+  return value;
+}
+
+function optionalNonNegativeInteger(value, name) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  if (!Number.isInteger(value) || value < 0) {
+    fail(`${name} must be a non-negative integer`);
+  }
+  return value;
+}
+
+function optionalPositiveNumber(value, name) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+    fail(`${name} must be a positive number`);
+  }
+  return value;
+}
+
+function optionalStringArray(value, name) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+    fail(`${name} must be an array of strings`);
+  }
+  if (value.length === 0) {
+    fail(`${name} must not be empty`);
+  }
+  return [...value];
+}
+
+function optionalBrands(value, name) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  if (!Array.isArray(value)) {
+    fail(`${name} must be an array of { brand, version } entries`);
+  }
+  return value.map((entry, index) => {
+    if (!entry || typeof entry !== 'object') {
+      fail(`${name}[${index}] must be an object`);
+    }
+    for (const key of BRAND_KEYS) {
+      if (typeof entry[key] !== 'string') {
+        fail(`${name}[${index}].${key} must be a string`);
+      }
+    }
+    return { brand: entry.brand, version: entry.version };
+  });
+}
+
+function optionalEnum(value, name, allowed) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  if (!allowed.includes(value)) {
+    fail(`${name} must be one of ${allowed.join(', ')}`);
+  }
+  return value;
+}
+
+function compact(object) {
+  const result = {};
+  for (const [key, value] of Object.entries(object)) {
+    if (value !== undefined) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+function resolveScreen(screen) {
+  if (screen === undefined || screen === null) {
+    return undefined;
+  }
+  if (typeof screen !== 'object') {
+    fail('screen must be an object');
+  }
+  const resolved = compact({
+    width: optionalPositiveInteger(screen.width, 'screen.width'),
+    height: optionalPositiveInteger(screen.height, 'screen.height'),
+    availWidth: optionalPositiveInteger(screen.availWidth, 'screen.availWidth'),
+    availHeight: optionalPositiveInteger(
+      screen.availHeight,
+      'screen.availHeight'
+    ),
+    colorDepth: optionalPositiveInteger(screen.colorDepth, 'screen.colorDepth'),
+    pixelDepth: optionalPositiveInteger(screen.pixelDepth, 'screen.pixelDepth'),
+  });
+  if ((resolved.width === undefined) !== (resolved.height === undefined)) {
+    fail('screen.width and screen.height must be provided together');
+  }
+  return Object.keys(resolved).length > 0 ? resolved : undefined;
+}
+
+function resolveViewport(viewport) {
+  if (viewport === undefined || viewport === null) {
+    return undefined;
+  }
+  if (typeof viewport !== 'object') {
+    fail('viewport must be an object');
+  }
+  const resolved = compact({
+    width: optionalPositiveInteger(viewport.width, 'viewport.width'),
+    height: optionalPositiveInteger(viewport.height, 'viewport.height'),
+    deviceScaleFactor: optionalPositiveNumber(
+      viewport.deviceScaleFactor,
+      'viewport.deviceScaleFactor'
+    ),
+    mobile: optionalBoolean(viewport.mobile, 'viewport.mobile'),
+  });
+  if ((resolved.width === undefined) !== (resolved.height === undefined)) {
+    fail('viewport.width and viewport.height must be provided together');
+  }
+  return Object.keys(resolved).length > 0 ? resolved : undefined;
+}
+
+function resolveGeolocation(geolocation) {
+  if (geolocation === undefined || geolocation === null) {
+    return undefined;
+  }
+  if (typeof geolocation !== 'object') {
+    fail('geolocation must be an object');
+  }
+  const { latitude, longitude, accuracy } = geolocation;
+  for (const [value, name] of [
+    [latitude, 'geolocation.latitude'],
+    [longitude, 'geolocation.longitude'],
+  ]) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+      fail(`${name} must be a finite number`);
+    }
+  }
+  if (latitude < -90 || latitude > 90) {
+    fail('geolocation.latitude must be between -90 and 90');
+  }
+  if (longitude < -180 || longitude > 180) {
+    fail('geolocation.longitude must be between -180 and 180');
+  }
+  return compact({
+    latitude,
+    longitude,
+    accuracy: optionalPositiveNumber(accuracy, 'geolocation.accuracy'),
+  });
+}
+
+function resolveWebgl(webgl) {
+  if (webgl === undefined || webgl === null) {
+    return undefined;
+  }
+  if (typeof webgl !== 'object') {
+    fail('webgl must be an object');
+  }
+  const resolved = compact({
+    vendor: optionalString(webgl.vendor, 'webgl.vendor'),
+    renderer: optionalString(webgl.renderer, 'webgl.renderer'),
+    unmaskedVendor: optionalString(
+      webgl.unmaskedVendor,
+      'webgl.unmaskedVendor'
+    ),
+    unmaskedRenderer: optionalString(
+      webgl.unmaskedRenderer,
+      'webgl.unmaskedRenderer'
+    ),
+  });
+  return Object.keys(resolved).length > 0 ? resolved : undefined;
+}
+
+/**
+ * Chrome derives both the Accept-Language header and `navigator.languages`
+ * from this one string, and it splits on commas without stripping q-values.
+ * Passing `de-DE,de;q=0.9` therefore yields the language tag `"de;q=0.9"` and
+ * the header `de-DE,de;q=0.9;q=0.9`; passing the plain list `de-DE,de,en`
+ * yields correct tags and the header `de-DE,de;q=0.9,en;q=0.8` that a real
+ * browser sends. Measured in
+ * `docs/case-studies/issue-79/analysis-artifacts/ua-hints-detail.json`.
+ */
+function resolveAcceptLanguage(acceptLanguage) {
+  if (acceptLanguage === undefined) {
+    return undefined;
+  }
+  if (acceptLanguage.includes(';')) {
+    fail(
+      'acceptLanguage must be a plain comma-separated language list without ' +
+        'q-values; Chrome generates the quality values itself'
+    );
+  }
+  return acceptLanguage;
+}
+
+/** Keep `uaFullVersion` consistent with `fullVersionList`. */
+function withFullVersion(userAgentData) {
+  if (!userAgentData || userAgentData.fullVersion !== undefined) {
+    return userAgentData;
+  }
+  const primary = userAgentData.fullVersionList?.find(
+    (entry) => entry.brand === 'Google Chrome' || entry.brand === 'Chromium'
+  );
+  return primary
+    ? { ...userAgentData, fullVersion: primary.version }
+    : userAgentData;
+}
+
+function resolveUserAgentData(userAgentData) {
+  if (userAgentData === undefined || userAgentData === null) {
+    return undefined;
+  }
+  if (typeof userAgentData !== 'object') {
+    fail('userAgentData must be an object');
+  }
+  const resolved = compact({
+    brands: optionalBrands(userAgentData.brands, 'userAgentData.brands'),
+    fullVersionList: optionalBrands(
+      userAgentData.fullVersionList,
+      'userAgentData.fullVersionList'
+    ),
+    platform: optionalString(userAgentData.platform, 'userAgentData.platform'),
+    platformVersion: optionalString(
+      userAgentData.platformVersion,
+      'userAgentData.platformVersion'
+    ),
+    architecture: optionalString(
+      userAgentData.architecture,
+      'userAgentData.architecture'
+    ),
+    bitness: optionalString(userAgentData.bitness, 'userAgentData.bitness'),
+    // Deprecated in the protocol but still the only way to control the
+    // `uaFullVersion` high-entropy hint: with `fullVersionList` alone the page
+    // still reads the real Chrome build number.
+    fullVersion: optionalString(
+      userAgentData.fullVersion,
+      'userAgentData.fullVersion'
+    ),
+    model: optionalString(userAgentData.model, 'userAgentData.model'),
+    mobile: optionalBoolean(userAgentData.mobile, 'userAgentData.mobile'),
+    wow64: optionalBoolean(userAgentData.wow64, 'userAgentData.wow64'),
+    formFactors: optionalStringArray(
+      userAgentData.formFactors,
+      'userAgentData.formFactors'
+    ),
+  });
+  return Object.keys(resolved).length > 0 ? resolved : undefined;
+}
+
+/**
+ * Normalize and validate a fingerprint profile.
+ *
+ * Unknown keys are rejected rather than ignored: a typo in `hardwareConcurency`
+ * would otherwise silently leave the real core count exposed, which is exactly
+ * the failure this module exists to prevent.
+ *
+ * @param {object} [input] Raw profile.
+ * @returns {object} Frozen, normalized profile.
+ */
+export function resolveFingerprintProfile(input = {}) {
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    fail('fingerprint profile must be an object');
+  }
+
+  const known = new Set([
+    'userAgent',
+    'userAgentData',
+    'acceptLanguage',
+    'languages',
+    'locale',
+    'timezoneId',
+    'platform',
+    'vendor',
+    'hardwareConcurrency',
+    'deviceMemory',
+    'maxTouchPoints',
+    'doNotTrack',
+    'screen',
+    'viewport',
+    'webgl',
+    'geolocation',
+    'colorScheme',
+    'reducedMotion',
+    'forcedColors',
+  ]);
+  for (const key of Object.keys(input)) {
+    if (!known.has(key)) {
+      fail(
+        `unknown fingerprint profile field "${key}"; known fields: ${[...known].sort().join(', ')}`
+      );
+    }
+  }
+
+  const languages = optionalStringArray(input.languages, 'languages');
+  const acceptLanguage = resolveAcceptLanguage(
+    optionalString(input.acceptLanguage, 'acceptLanguage') ??
+      (languages ? languages.join(',') : undefined)
+  );
+  const userAgent = optionalString(input.userAgent, 'userAgent');
+  const userAgentData =
+    resolveUserAgentData(input.userAgentData) ??
+    (userAgent === undefined ? undefined : deriveUserAgentData(userAgent));
+
+  return Object.freeze(
+    compact({
+      userAgent,
+      userAgentData: withFullVersion(userAgentData),
+      acceptLanguage,
+      languages,
+      locale: optionalString(input.locale, 'locale'),
+      timezoneId: optionalString(input.timezoneId, 'timezoneId'),
+      platform: optionalString(input.platform, 'platform'),
+      vendor: optionalString(input.vendor, 'vendor'),
+      hardwareConcurrency: optionalPositiveInteger(
+        input.hardwareConcurrency,
+        'hardwareConcurrency'
+      ),
+      deviceMemory: optionalPositiveNumber(input.deviceMemory, 'deviceMemory'),
+      maxTouchPoints: optionalNonNegativeInteger(
+        input.maxTouchPoints,
+        'maxTouchPoints'
+      ),
+      doNotTrack: optionalString(input.doNotTrack, 'doNotTrack'),
+      screen: resolveScreen(input.screen),
+      viewport: resolveViewport(input.viewport),
+      webgl: resolveWebgl(input.webgl),
+      geolocation: resolveGeolocation(input.geolocation),
+      colorScheme: optionalEnum(input.colorScheme, 'colorScheme', [
+        'light',
+        'dark',
+        'no-preference',
+      ]),
+      reducedMotion: optionalEnum(input.reducedMotion, 'reducedMotion', [
+        'reduce',
+        'no-preference',
+      ]),
+      forcedColors: optionalEnum(input.forcedColors, 'forcedColors', [
+        'active',
+        'none',
+      ]),
+    })
+  );
+}
+
+/**
+ * How each profile field reaches the page.
+ *
+ * `browser` means Chrome itself produces the value, so it holds for the
+ * document, for HTTP headers and for any code that reads it, and a page cannot
+ * detect the override by comparing two ways of asking. `script` means the value
+ * is a JavaScript property patch installed before page scripts run, which is
+ * weaker: it holds for the main world but is not what the network stack or a
+ * fresh renderer would say.
+ *
+ * Neither kind reaches a worker in full. Measured in a dedicated worker,
+ * `userAgent`, `timezoneId` and `locale` follow the profile while `platform`,
+ * `languages` and `hardwareConcurrency` revert to the host values; see the
+ * `init-script-does-not-reach-workers` entry in `limitations.js` and
+ * `docs/case-studies/issue-79/analysis-artifacts/worker-visibility.json`.
+ */
+export const FINGERPRINT_FIELD_MECHANISMS = Object.freeze({
+  userAgent: 'browser',
+  userAgentData: 'browser',
+  acceptLanguage: 'browser',
+  languages: 'browser',
+  locale: 'browser',
+  timezoneId: 'browser',
+  hardwareConcurrency: 'browser',
+  screen: 'browser',
+  viewport: 'browser',
+  maxTouchPoints: 'browser',
+  geolocation: 'browser',
+  colorScheme: 'browser',
+  reducedMotion: 'browser',
+  forcedColors: 'browser',
+  platform: 'browser',
+  vendor: 'script',
+  deviceMemory: 'script',
+  doNotTrack: 'script',
+  webgl: 'script',
+});

package/src/tests/index.js

@@ -223,7 +223,8 @@ export function loadTimingData(options = {}) {
       return createEmptyTimingData();
     }
     throw new Error(
-      `Could not read browser test timing data: ${error.message}`
+      `Could not read browser test timing data: ${error.message}`,
+      { cause: error }
     );
   }
 }

package/tests/e2e/fingerprint-parity.e2e.test.js

@@ -0,0 +1,212 @@
+/**
+ * E2E parity tests: a page must not be able to tell that Browser Commander is
+ * driving the browser.
+ *
+ * The reference capture never speaks CDP. Chrome is started as a plain child
+ * process pointed at a local page; the page runs the environment probe and
+ * POSTs the report back over HTTP. Every automated capture is delivered the
+ * same way, so a difference in the diff is a difference in the browser rather
+ * than a difference in how the probe was invoked.
+ *
+ * Parity is asserted twice, because "the same as a real browser" means a
+ * different thing in each mode: a headful capture is compared against a
+ * hand-started headful Chrome, and a headless capture against a hand-started
+ * headless Chrome. The two references genuinely differ -- see the
+ * `headless-is-distinguishable` entry in `src/fingerprint/limitations.js` --
+ * so neither comparison can stand in for the other.
+ *
+ * Prerequisites:
+ *   RUN_E2E=true, a Chrome binary, and, for the headful half, a display:
+ *
+ *     RUN_E2E=true xvfb-run -a --server-args="-screen 0 1920x1080x24" \
+ *       npm run test:e2e:parity
+ */
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert';
+import { existsSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+import {
+  captureReferenceReport,
+  diffReports,
+  readProbeSource,
+  startProbeServer,
+} from '../../../experiments/fingerprint-parity/harness.mjs';
+import { launchBrowser } from '../../src/index.js';
+import { createFingerprintPreset } from '../../src/fingerprint/presets.js';
+
+const CHROME = process.env.CHROME_PATH || '/usr/bin/google-chrome';
+const TEST_TIMEOUT = 180000;
+
+/** Why the suite cannot run here, or `false` when it can. */
+function skipReason({ headless }) {
+  if (!process.env.RUN_E2E) {
+    return 'set RUN_E2E=true to run the parity tests';
+  }
+  if (!existsSync(CHROME)) {
+    return `no Chrome binary at ${CHROME}; set CHROME_PATH`;
+  }
+  if (!headless && process.platform === 'linux' && !process.env.DISPLAY) {
+    return 'headful parity needs a display; run under xvfb-run';
+  }
+  return false;
+}
+
+function defineParitySuite({ headless }) {
+  const mode = headless ? 'headless' : 'headful';
+
+  describe(
+    `E2E Tests - Fingerprint Parity (${mode})`,
+    { skip: skipReason({ headless }) },
+    () => {
+      let server;
+      let reference;
+      const userDataDirs = [];
+
+      const nextUserDataDir = async () => {
+        const directory = await mkdtemp(path.join(tmpdir(), 'bc-parity-e2e-'));
+        userDataDirs.push(directory);
+        return directory;
+      };
+
+      /** Drive one capture through the shipped launcher. */
+      const captureWithLibrary = async (options) => {
+        const token = randomUUID();
+        const { browser, page } = await launchBrowser({
+          headless,
+          slowMo: 0,
+          executablePath: CHROME,
+          userDataDir: await nextUserDataDir(),
+          ...options,
+        });
+        try {
+          await page.goto(server.url(token), { waitUntil: 'load' });
+          return { report: await server.waitForReport(token), token };
+        } finally {
+          await browser.close();
+        }
+      };
+
+      before(async () => {
+        server = await startProbeServer(await readProbeSource());
+        reference = await captureReferenceReport({
+          executablePath: CHROME,
+          server,
+          token: randomUUID(),
+          headless,
+        });
+        assert.ok(
+          reference && !reference.fatal,
+          `reference capture failed: ${reference && reference.fatal}`
+        );
+      });
+
+      after(async () => {
+        if (server) {
+          await server.close();
+        }
+        await Promise.all(
+          userDataDirs.map((directory) =>
+            rm(directory, { recursive: true, force: true, maxRetries: 10 })
+          )
+        );
+      });
+
+      for (const engine of ['playwright', 'puppeteer']) {
+        it(
+          `${engine} is indistinguishable from a hand-started Chrome`,
+          { timeout: TEST_TIMEOUT },
+          async () => {
+            const { report } = await captureWithLibrary({ engine });
+            const differences = diffReports(reference, report);
+
+            assert.deepEqual(
+              differences,
+              [],
+              `${engine} differs from a real ${mode} browser in: ${differences
+                .map((entry) => entry.path)
+                .join(', ')}`
+            );
+          }
+        );
+
+        it(
+          `${engine} leaks navigator.webdriver once parity is turned off`,
+          { timeout: TEST_TIMEOUT },
+          async () => {
+            // Negative control: without this the parity assertion above could
+            // pass for the wrong reason, for example because the probe stopped
+            // reporting the field.
+            const { report } = await captureWithLibrary({
+              engine,
+              automationParity: false,
+            });
+            const paths = diffReports(reference, report).map(
+              (entry) => entry.path
+            );
+
+            assert.ok(
+              paths.includes('navigator.webdriver'),
+              `expected navigator.webdriver to leak, saw: ${paths.join(', ')}`
+            );
+          }
+        );
+
+        it(
+          `${engine} presents the fingerprint profile it was launched with`,
+          { timeout: TEST_TIMEOUT },
+          async () => {
+            const profile = createFingerprintPreset('macos-chrome', {
+              overrides: {
+                timezoneId: 'Australia/Sydney',
+                languages: ['pt-BR', 'pt', 'en'],
+                hardwareConcurrency: 6,
+              },
+            });
+            const { report, token } = await captureWithLibrary({
+              engine,
+              fingerprint: profile,
+            });
+
+            assert.equal(report.navigator.userAgent, profile.userAgent);
+            assert.equal(report.navigator.platform, profile.platform);
+            assert.equal(report.navigator.hardwareConcurrency, 6);
+            assert.equal(report.navigator.deviceMemory, profile.deviceMemory);
+            assert.deepEqual(report.navigator.languages, ['pt-BR', 'pt', 'en']);
+            assert.equal(report.intl.dateTimeTimeZone, 'Australia/Sydney');
+            assert.equal(report.screen.width, profile.screen.width);
+            assert.equal(report.screen.availHeight, profile.screen.availHeight);
+            assert.equal(report.screen.colorDepth, profile.screen.colorDepth);
+            // A machine with no GPU stack reports no WebGL context at all, and
+            // there is then nothing for the renderer patch to replace.
+            if (report.webgl.webgl1) {
+              assert.equal(
+                report.webgl.webgl1.unmaskedVendor,
+                profile.webgl.unmaskedVendor
+              );
+              assert.equal(report.webgl.webgl1.vendor, profile.webgl.vendor);
+            }
+            // The overrides Chrome enforces itself reach the network stack
+            // too, which a JavaScript property patch never would. Chrome
+            // builds the quality ladder from the plain list, exactly as it
+            // does for a real browser configured with these languages.
+            assert.equal(
+              server.headersFor(token)['accept-language'],
+              'pt-BR,pt;q=0.9,en;q=0.8'
+            );
+            assert.equal(
+              server.headersFor(token)['user-agent'],
+              profile.userAgent
+            );
+          }
+        );
+      }
+    }
+  );
+}
+
+defineParitySuite({ headless: false });
+defineParitySuite({ headless: true });

package/tests/helpers/mocks.js

@@ -530,7 +530,8 @@ export const assert = {
     } catch (error) {
       if (expectedError && !error.message.includes(expectedError)) {
         throw new Error(
-          `${message}: Expected error message to include "${expectedError}", got "${error.message}"`
+          `${message}: Expected error message to include "${expectedError}", got "${error.message}"`,
+          { cause: error }
         );
       }
     }
@@ -540,7 +541,8 @@ export const assert = {
       await fn();
     } catch (error) {
       throw new Error(
-        `${message}: Expected function not to throw, but got: ${error.message}`
+        `${message}: Expected function not to throw, but got: ${error.message}`,
+        { cause: error }
       );
     }
   },