browser-commander 0.16.1 → 0.17.0

package/src/fingerprint/presets.js

@@ -0,0 +1,244 @@
+/**
+ * Ready-made fingerprint profiles for the desktop and mobile platforms Chrome
+ * ships on.
+ *
+ * A profile is only useful if it is internally consistent: the user agent
+ * string, the User-Agent Client Hints, `navigator.platform`, the WebGL
+ * renderer and the screen size all have to describe the same machine, because
+ * every serious fingerprinting script cross-checks them. Each preset below is
+ * therefore written as one machine rather than as a bag of independent fields.
+ *
+ * The Chrome version is a parameter instead of a constant. A profile claiming
+ * Chrome 131 while the binary is Chrome 149 is trivially detectable from
+ * feature sniffing, so the caller should pass the version of the browser they
+ * actually launch.
+ */
+import { resolveFingerprintProfile } from './profile.js';
+
+const DEFAULT_CHROME_VERSION = '140.0.0.0';
+
+function majorVersion(version) {
+  return version.split('.')[0];
+}
+
+function brandsFor(version) {
+  const major = majorVersion(version);
+  return [
+    { brand: 'Google Chrome', version: major },
+    { brand: 'Chromium', version: major },
+    { brand: 'Not)A;Brand', version: '24' },
+  ];
+}
+
+function fullVersionListFor(version) {
+  return [
+    { brand: 'Google Chrome', version },
+    { brand: 'Chromium', version },
+    { brand: 'Not)A;Brand', version: '24.0.0.0' },
+  ];
+}
+
+function desktopUserAgent(platformToken, version) {
+  return `Mozilla/5.0 (${platformToken}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${majorVersion(version)}.0.0.0 Safari/537.36`;
+}
+
+const BUILDERS = {
+  'windows-chrome': (version) => ({
+    userAgent: desktopUserAgent('Windows NT 10.0; Win64; x64', version),
+    userAgentData: {
+      brands: brandsFor(version),
+      fullVersionList: fullVersionListFor(version),
+      platform: 'Windows',
+      platformVersion: '15.0.0',
+      architecture: 'x86',
+      bitness: '64',
+      model: '',
+      mobile: false,
+      wow64: false,
+      formFactors: ['Desktop'],
+    },
+    platform: 'Win32',
+    vendor: 'Google Inc.',
+    languages: ['en-US', 'en'],
+    locale: 'en-US',
+    timezoneId: 'America/New_York',
+    hardwareConcurrency: 8,
+    deviceMemory: 8,
+    maxTouchPoints: 0,
+    screen: {
+      width: 1920,
+      height: 1080,
+      availWidth: 1920,
+      availHeight: 1032,
+      colorDepth: 24,
+      pixelDepth: 24,
+    },
+    viewport: { width: 1920, height: 947, deviceScaleFactor: 1, mobile: false },
+    webgl: {
+      vendor: 'WebKit',
+      renderer: 'WebKit WebGL',
+      unmaskedVendor: 'Google Inc. (NVIDIA)',
+      unmaskedRenderer:
+        'ANGLE (NVIDIA, NVIDIA GeForce RTX 3060 (0x00002503) Direct3D11 vs_5_0 ps_5_0, D3D11)',
+    },
+  }),
+  'macos-chrome': (version) => ({
+    userAgent: desktopUserAgent('Macintosh; Intel Mac OS X 10_15_7', version),
+    userAgentData: {
+      brands: brandsFor(version),
+      fullVersionList: fullVersionListFor(version),
+      platform: 'macOS',
+      platformVersion: '15.6.0',
+      architecture: 'arm',
+      bitness: '64',
+      model: '',
+      mobile: false,
+      wow64: false,
+      formFactors: ['Desktop'],
+    },
+    platform: 'MacIntel',
+    vendor: 'Google Inc.',
+    languages: ['en-US', 'en'],
+    locale: 'en-US',
+    timezoneId: 'America/Los_Angeles',
+    hardwareConcurrency: 10,
+    deviceMemory: 8,
+    maxTouchPoints: 0,
+    screen: {
+      width: 1728,
+      height: 1117,
+      availWidth: 1728,
+      availHeight: 1085,
+      colorDepth: 30,
+      pixelDepth: 30,
+    },
+    viewport: {
+      width: 1728,
+      height: 1005,
+      deviceScaleFactor: 2,
+      mobile: false,
+    },
+    webgl: {
+      vendor: 'WebKit',
+      renderer: 'WebKit WebGL',
+      unmaskedVendor: 'Google Inc. (Apple)',
+      unmaskedRenderer:
+        'ANGLE (Apple, ANGLE Metal Renderer: Apple M3, Unspecified Version)',
+    },
+  }),
+  'linux-chrome': (version) => ({
+    userAgent: desktopUserAgent('X11; Linux x86_64', version),
+    userAgentData: {
+      brands: brandsFor(version),
+      fullVersionList: fullVersionListFor(version),
+      platform: 'Linux',
+      platformVersion: '',
+      architecture: 'x86',
+      bitness: '64',
+      model: '',
+      mobile: false,
+      wow64: false,
+      formFactors: ['Desktop'],
+    },
+    platform: 'Linux x86_64',
+    vendor: 'Google Inc.',
+    languages: ['en-US', 'en'],
+    locale: 'en-US',
+    timezoneId: 'UTC',
+    hardwareConcurrency: 8,
+    deviceMemory: 8,
+    maxTouchPoints: 0,
+    screen: {
+      width: 1920,
+      height: 1080,
+      availWidth: 1920,
+      availHeight: 1053,
+      colorDepth: 24,
+      pixelDepth: 24,
+    },
+    viewport: { width: 1920, height: 955, deviceScaleFactor: 1, mobile: false },
+    webgl: {
+      vendor: 'WebKit',
+      renderer: 'WebKit WebGL',
+      unmaskedVendor: 'Google Inc. (Intel)',
+      unmaskedRenderer:
+        'ANGLE (Intel, Mesa Intel(R) UHD Graphics 630 (CFL GT2), OpenGL 4.6)',
+    },
+  }),
+  'android-chrome': (version) => ({
+    userAgent: `Mozilla/5.0 (Linux; Android 15; Pixel 8) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${majorVersion(version)}.0.0.0 Mobile Safari/537.36`,
+    userAgentData: {
+      brands: brandsFor(version),
+      fullVersionList: fullVersionListFor(version),
+      platform: 'Android',
+      platformVersion: '15.0.0',
+      architecture: '',
+      bitness: '',
+      model: 'Pixel 8',
+      mobile: true,
+      wow64: false,
+      formFactors: ['Mobile'],
+    },
+    platform: 'Linux armv81',
+    vendor: 'Google Inc.',
+    languages: ['en-US', 'en'],
+    locale: 'en-US',
+    timezoneId: 'America/New_York',
+    hardwareConcurrency: 8,
+    deviceMemory: 8,
+    maxTouchPoints: 5,
+    screen: {
+      width: 412,
+      height: 915,
+      availWidth: 412,
+      availHeight: 915,
+      colorDepth: 24,
+      pixelDepth: 24,
+    },
+    viewport: {
+      width: 412,
+      height: 823,
+      deviceScaleFactor: 2.625,
+      mobile: true,
+    },
+    webgl: {
+      vendor: 'WebKit',
+      renderer: 'WebKit WebGL',
+      unmaskedVendor: 'Google Inc. (Qualcomm)',
+      unmaskedRenderer: 'ANGLE (Qualcomm, Adreno (TM) 750, OpenGL ES 3.2)',
+    },
+  }),
+};
+
+/** Names accepted by {@link createFingerprintPreset}. */
+export const FINGERPRINT_PRESET_NAMES = Object.freeze(
+  Object.keys(BUILDERS).sort()
+);
+
+/**
+ * Build a complete, internally consistent fingerprint profile.
+ *
+ * @param {string} name One of {@link FINGERPRINT_PRESET_NAMES}.
+ * @param {object} [options] Preset options.
+ * @param {string} [options.chromeVersion] Full Chrome version, e.g. `'140.0.7339.80'`.
+ * @param {object} [options.overrides] Profile fields merged over the preset.
+ * @returns {object} Normalized fingerprint profile.
+ */
+export function createFingerprintPreset(name, options = {}) {
+  const builder = BUILDERS[name];
+  if (!builder) {
+    throw new TypeError(
+      `unknown fingerprint preset "${name}"; known presets: ${FINGERPRINT_PRESET_NAMES.join(', ')}`
+    );
+  }
+  const { chromeVersion = DEFAULT_CHROME_VERSION, overrides = {} } = options;
+  if (
+    typeof chromeVersion !== 'string' ||
+    !/^\d+(\.\d+)*$/u.test(chromeVersion)
+  ) {
+    throw new TypeError(
+      'chromeVersion must be a dotted numeric version string'
+    );
+  }
+  return resolveFingerprintProfile({ ...builder(chromeVersion), ...overrides });
+}

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 }
     );
   }
 }