browser-commander 0.16.0 → 0.17.0

package/tests/unit/fingerprint/cdp-overrides.test.js

@@ -0,0 +1,227 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+
+import { buildCdpEmulationCommands } from '../../../src/fingerprint/cdp-overrides.js';
+import { resolveFingerprintProfile } from '../../../src/fingerprint/profile.js';
+
+function methodsOf(profile) {
+  return buildCdpEmulationCommands(resolveFingerprintProfile(profile)).map(
+    (command) => command.method
+  );
+}
+
+function paramsOf(profile, method) {
+  const command = buildCdpEmulationCommands(
+    resolveFingerprintProfile(profile)
+  ).find((entry) => entry.method === method);
+  return command?.params;
+}
+
+describe('CDP emulation commands', () => {
+  it('rejects anything that is not a profile object', () => {
+    assert.throws(
+      () => buildCdpEmulationCommands(null),
+      /must be a normalized fingerprint profile/u
+    );
+    assert.throws(
+      () => buildCdpEmulationCommands('windows'),
+      /must be a normalized fingerprint profile/u
+    );
+  });
+
+  it('emits nothing for an empty profile', () => {
+    assert.deepEqual(
+      buildCdpEmulationCommands(resolveFingerprintProfile({})),
+      []
+    );
+  });
+
+  it('sends only the commands the profile asks for', () => {
+    assert.deepEqual(methodsOf({ timezoneId: 'Europe/Berlin' }), [
+      'Emulation.setTimezoneOverride',
+    ]);
+    assert.deepEqual(methodsOf({ hardwareConcurrency: 4 }), [
+      'Emulation.setHardwareConcurrencyOverride',
+    ]);
+  });
+
+  it('keeps a stable command order for a full profile', () => {
+    assert.deepEqual(
+      methodsOf({
+        userAgent:
+          'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ' +
+          '(KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36',
+        timezoneId: 'Europe/Berlin',
+        locale: 'de-DE',
+        hardwareConcurrency: 12,
+        screen: { width: 2560, height: 1440 },
+        viewport: { width: 1280, height: 720 },
+        maxTouchPoints: 0,
+        colorScheme: 'dark',
+        geolocation: { latitude: 52.52, longitude: 13.405, accuracy: 20 },
+      }),
+      [
+        'Emulation.setUserAgentOverride',
+        'Emulation.setTimezoneOverride',
+        'Emulation.setLocaleOverride',
+        'Emulation.setHardwareConcurrencyOverride',
+        'Emulation.setDeviceMetricsOverride',
+        'Emulation.setTouchEmulationEnabled',
+        'Emulation.setEmulatedMedia',
+        'Emulation.setGeolocationOverride',
+      ]
+    );
+  });
+
+  it('supplies the required empty user agent when only the language changes', () => {
+    const params = paramsOf(
+      { languages: ['fr-FR', 'fr'] },
+      'Emulation.setUserAgentOverride'
+    );
+    // userAgent is a required protocol parameter; an empty string means
+    // "leave it alone" while acceptLanguage still takes effect.
+    assert.equal(params.userAgent, '');
+    assert.equal(params.acceptLanguage, 'fr-FR,fr');
+  });
+
+  it('carries the client hints, including the deprecated full version', () => {
+    const params = paramsOf(
+      {
+        userAgent:
+          'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ' +
+          '(KHTML, like Gecko) Chrome/140.0.7000.55 Safari/537.36',
+        platform: 'Win32',
+      },
+      'Emulation.setUserAgentOverride'
+    );
+
+    assert.equal(params.platform, 'Win32');
+    assert.equal(params.userAgentMetadata.platform, 'Windows');
+    // fullVersionList does not cover the uaFullVersion hint, so the deprecated
+    // fullVersion field has to travel with it.
+    assert.equal(params.userAgentMetadata.fullVersion, '140.0.7000.55');
+    assert.equal(params.userAgentMetadata.bitness, '64');
+    assert.equal(params.userAgentMetadata.wow64, false);
+    assert.deepEqual(params.userAgentMetadata.formFactors, ['Desktop']);
+  });
+
+  it('always fills the protocol-required metadata fields', () => {
+    const params = paramsOf(
+      {
+        userAgent: 'custom agent',
+        userAgentData: { brands: [{ brand: 'Custom', version: '1' }] },
+      },
+      'Emulation.setUserAgentOverride'
+    );
+
+    // Chrome rejects setUserAgentOverride when any of these is missing.
+    for (const field of [
+      'platform',
+      'platformVersion',
+      'architecture',
+      'model',
+      'mobile',
+    ]) {
+      assert.ok(field in params.userAgentMetadata, `${field} must be present`);
+    }
+    assert.equal(params.userAgentMetadata.mobile, false);
+    assert.ok(!('bitness' in params.userAgentMetadata));
+  });
+
+  it('copies the brand entries instead of sharing them with the profile', () => {
+    const profile = resolveFingerprintProfile({
+      userAgent:
+        'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ' +
+        '(KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36',
+    });
+    const [{ params }] = buildCdpEmulationCommands(profile);
+
+    assert.notEqual(
+      params.userAgentMetadata.brands,
+      profile.userAgentData.brands
+    );
+    assert.notEqual(
+      params.userAgentMetadata.brands[0],
+      profile.userAgentData.brands[0]
+    );
+  });
+
+  it('leaves the window size alone when only the screen is described', () => {
+    const params = paramsOf(
+      { screen: { width: 2560, height: 1440 } },
+      'Emulation.setDeviceMetricsOverride'
+    );
+
+    // Zeroes mean "no override" for the viewport, so a screen-only profile
+    // does not resize the window it was applied to.
+    assert.deepEqual(params, {
+      width: 0,
+      height: 0,
+      deviceScaleFactor: 0,
+      mobile: false,
+      screenWidth: 2560,
+      screenHeight: 1440,
+    });
+  });
+
+  it('sends the viewport without screen dimensions when no screen is set', () => {
+    assert.deepEqual(
+      paramsOf(
+        {
+          viewport: {
+            width: 1280,
+            height: 720,
+            deviceScaleFactor: 2,
+            mobile: true,
+          },
+        },
+        'Emulation.setDeviceMetricsOverride'
+      ),
+      { width: 1280, height: 720, deviceScaleFactor: 2, mobile: true }
+    );
+  });
+
+  it('disables touch emulation for a desktop profile that names zero touch points', () => {
+    // maxTouchPoints must stay at least 1 because the protocol rejects 0, so
+    // "no touch" is expressed through enabled instead.
+    assert.deepEqual(
+      paramsOf({ maxTouchPoints: 0 }, 'Emulation.setTouchEmulationEnabled'),
+      { enabled: false, maxTouchPoints: 1 }
+    );
+    assert.deepEqual(
+      paramsOf({ maxTouchPoints: 5 }, 'Emulation.setTouchEmulationEnabled'),
+      { enabled: true, maxTouchPoints: 5 }
+    );
+  });
+
+  it('collects every media preference into a single command', () => {
+    assert.deepEqual(
+      paramsOf(
+        {
+          colorScheme: 'dark',
+          reducedMotion: 'reduce',
+          forcedColors: 'active',
+        },
+        'Emulation.setEmulatedMedia'
+      ),
+      {
+        features: [
+          { name: 'prefers-reduced-motion', value: 'reduce' },
+          { name: 'forced-colors', value: 'active' },
+          { name: 'prefers-color-scheme', value: 'dark' },
+        ],
+      }
+    );
+  });
+
+  it('passes geolocation through as its own copy', () => {
+    const geolocation = { latitude: 48.85, longitude: 2.35, accuracy: 10 };
+    const params = paramsOf(
+      { geolocation },
+      'Emulation.setGeolocationOverride'
+    );
+
+    assert.deepEqual(params, geolocation);
+    assert.notEqual(params, geolocation);
+  });
+});

package/tests/unit/fingerprint/derive.test.js

@@ -0,0 +1,105 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+
+import { deriveUserAgentData } from '../../../src/fingerprint/derive.js';
+
+describe('client hints derived from a user agent', () => {
+  it('returns null when the string names no Chrome version', () => {
+    assert.equal(
+      deriveUserAgentData(
+        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ' +
+          'AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Safari/605.1.15'
+      ),
+      null
+    );
+  });
+
+  it('rejects a non-string user agent', () => {
+    assert.throws(() => deriveUserAgentData(undefined), /must be a string/u);
+  });
+
+  it('maps a Windows user agent onto the Windows platform hints', () => {
+    const data = deriveUserAgentData(
+      'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ' +
+        '(KHTML, like Gecko) Chrome/140.0.7000.55 Safari/537.36'
+    );
+
+    assert.equal(data.platform, 'Windows');
+    assert.equal(data.architecture, 'x86');
+    assert.equal(data.bitness, '64');
+    assert.equal(data.mobile, false);
+    assert.deepEqual(data.formFactors, ['Desktop']);
+    // Chrome froze the user agent at "Windows NT 10.0" and reports the real
+    // version only through platformVersion, where 13 and up mean Windows 11.
+    assert.equal(data.platformVersion, '15.0.0');
+    assert.equal(data.fullVersion, '140.0.7000.55');
+  });
+
+  it('pads a major-only Chrome version into a four part full version', () => {
+    const data = deriveUserAgentData(
+      'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ' +
+        '(KHTML, like Gecko) Chrome/141 Safari/537.36'
+    );
+
+    assert.equal(data.fullVersion, '141.0.0.0');
+    assert.deepEqual(
+      data.brands.map((entry) => entry.version),
+      ['141', '141', '24']
+    );
+  });
+
+  it('parses the macOS version out of the user agent', () => {
+    const data = deriveUserAgentData(
+      'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ' +
+        '(KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36'
+    );
+
+    assert.equal(data.platform, 'macOS');
+    assert.equal(data.platformVersion, '10.15.7');
+  });
+
+  it('reports an Android phone as mobile and recovers the model', () => {
+    const data = deriveUserAgentData(
+      'Mozilla/5.0 (Linux; Android 14; Pixel 8 Build/UQ1A.240105.004) ' +
+        'AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Mobile Safari/537.36'
+    );
+
+    assert.equal(data.platform, 'Android');
+    assert.equal(data.platformVersion, '14');
+    assert.equal(data.mobile, true);
+    assert.equal(data.model, 'Pixel 8');
+    assert.deepEqual(data.formFactors, ['Mobile']);
+  });
+
+  it('recognises Linux and Chrome OS', () => {
+    assert.equal(
+      deriveUserAgentData(
+        'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 ' +
+          '(KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36'
+      ).platform,
+      'Linux'
+    );
+    assert.equal(
+      deriveUserAgentData(
+        'Mozilla/5.0 (X11; CrOS x86_64 14541.0.0) AppleWebKit/537.36 ' +
+          '(KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36'
+      ).platform,
+      'Chrome OS'
+    );
+  });
+
+  it('includes the GREASE brand so the brand list has a real browser shape', () => {
+    const data = deriveUserAgentData(
+      'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ' +
+        '(KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36'
+    );
+
+    assert.equal(data.brands.length, 3);
+    assert.ok(data.brands.some((entry) => entry.brand === 'Not=A?Brand'));
+    assert.ok(
+      data.fullVersionList.every(
+        (entry) => entry.version.split('.').length === 4
+      )
+    );
+  });
+});

package/tests/unit/fingerprint/init-script.test.js

@@ -0,0 +1,357 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import vm from 'node:vm';
+
+import {
+  buildFingerprintInitScript,
+  buildInitScriptConfig,
+  FINGERPRINT_PAYLOAD_SOURCE,
+} from '../../../src/fingerprint/init-script.js';
+import { resolveFingerprintProfile } from '../../../src/fingerprint/profile.js';
+
+/**
+ * Run a generated init script in a throwaway realm that looks enough like a
+ * page to exercise every patch: the payload only ever touches prototypes it
+ * finds on the global object, so a handful of stand-in constructors is all it
+ * needs. Running it for real is what proves the descriptor shapes, the
+ * `[native code]` masking and the double-application guard, none of which a
+ * string comparison would catch.
+ */
+function runInFakeRealm(script, { hostValues = {} } = {}) {
+  const context = vm.createContext({});
+  vm.runInContext(
+    `
+    function Navigator() {}
+    function WorkerNavigator() {}
+    function Screen() {}
+    function WebGLRenderingContext() {}
+    function WebGL2RenderingContext() {}
+    const host = ${JSON.stringify({
+      deviceMemory: 64,
+      vendor: 'Host Vendor',
+      platform: 'HostPlatform',
+      language: 'xx-XX',
+      languages: ['xx-XX'],
+      doNotTrack: '1',
+      hardwareConcurrency: 128,
+      maxTouchPoints: 0,
+      ...hostValues,
+    })};
+    for (const property of Object.keys(host)) {
+      const value = host[property];
+      Object.defineProperty(Navigator.prototype, property, {
+        get() { return value; },
+        enumerable: true,
+        configurable: true,
+      });
+      Object.defineProperty(WorkerNavigator.prototype, property, {
+        get() { return value; },
+        enumerable: true,
+        configurable: true,
+      });
+    }
+    for (const property of ['width', 'height', 'availWidth', 'availHeight', 'colorDepth', 'pixelDepth']) {
+      Object.defineProperty(Screen.prototype, property, {
+        get() { return 1; },
+        enumerable: true,
+        configurable: true,
+      });
+    }
+    for (const name of ['WebGLRenderingContext', 'WebGL2RenderingContext']) {
+      this[name].prototype.getParameter = function getParameter(parameter) {
+        return 'real-' + parameter;
+      };
+    }
+    globalThis.navigator = new Navigator();
+    globalThis.screen = new Screen();
+    globalThis.gl = new WebGLRenderingContext();
+    `,
+    context
+  );
+  vm.runInContext(script, context);
+  return context;
+}
+
+describe('init script config', () => {
+  it('rejects anything that is not a profile object', () => {
+    assert.throws(
+      () => buildFingerprintInitScript(undefined),
+      /must be a normalized fingerprint profile/u
+    );
+  });
+
+  it('returns null when the browser-side overrides already cover everything', () => {
+    const profile = resolveFingerprintProfile({
+      userAgent: 'Mozilla/5.0 (X11; Linux x86_64) Chrome/140.0.0.0',
+      timezoneId: 'UTC',
+      hardwareConcurrency: 8,
+      maxTouchPoints: 0,
+    });
+
+    assert.equal(buildInitScriptConfig(profile), null);
+    assert.equal(buildFingerprintInitScript(profile), null);
+  });
+
+  it('patches only the fields the Emulation domain has no command for', () => {
+    const profile = resolveFingerprintProfile({
+      deviceMemory: 8,
+      vendor: 'Google Inc.',
+      doNotTrack: '1',
+      hardwareConcurrency: 8,
+      timezoneId: 'UTC',
+    });
+
+    // hardwareConcurrency and timezoneId are browser-enforced, so they must
+    // not appear in the weaker JavaScript patch.
+    assert.deepEqual(Object.keys(buildInitScriptConfig(profile)).sort(), [
+      'deviceMemory',
+      'doNotTrack',
+      'vendor',
+    ]);
+  });
+
+  it('adds webdriver only when the caller asks for it', () => {
+    const profile = resolveFingerprintProfile({ vendor: 'Google Inc.' });
+
+    assert.equal(buildInitScriptConfig(profile).webdriver, undefined);
+    assert.equal(
+      buildInitScriptConfig(profile, { patchWebdriver: true }).webdriver,
+      false
+    );
+  });
+
+  it('patches webdriver even for an otherwise empty profile', () => {
+    const script = buildFingerprintInitScript(resolveFingerprintProfile({}), {
+      patchWebdriver: true,
+    });
+
+    assert.ok(script);
+    const context = runInFakeRealm(script);
+    assert.equal(vm.runInContext('navigator.webdriver', context), false);
+  });
+
+  it('leaves languages to the browser unless explicitly asked', () => {
+    const profile = resolveFingerprintProfile({ languages: ['fr-FR', 'fr'] });
+
+    assert.equal(buildInitScriptConfig(profile), null);
+    assert.deepEqual(
+      buildInitScriptConfig(profile, { patchLanguages: true }).languages,
+      ['fr-FR', 'fr']
+    );
+  });
+
+  it('drops the screen dimensions setDeviceMetricsOverride already enforces', () => {
+    const config = buildInitScriptConfig(
+      resolveFingerprintProfile({
+        screen: {
+          width: 1920,
+          height: 1080,
+          availWidth: 1920,
+          availHeight: 1032,
+          colorDepth: 24,
+          pixelDepth: 24,
+        },
+      })
+    );
+
+    assert.deepEqual(Object.keys(config.screen).sort(), [
+      'availHeight',
+      'availWidth',
+      'colorDepth',
+      'pixelDepth',
+    ]);
+  });
+
+  it('skips the screen patch when only width and height are given', () => {
+    assert.equal(
+      buildInitScriptConfig(
+        resolveFingerprintProfile({ screen: { width: 1920, height: 1080 } })
+      ),
+      null
+    );
+  });
+});
+
+describe('init script behaviour in a page-like realm', () => {
+  const profile = resolveFingerprintProfile({
+    deviceMemory: 8,
+    vendor: 'Google Inc.',
+    doNotTrack: null,
+    platform: 'Win32',
+    languages: ['de-DE', 'de'],
+    screen: {
+      width: 1920,
+      height: 1080,
+      availWidth: 1920,
+      availHeight: 1032,
+      colorDepth: 24,
+      pixelDepth: 24,
+    },
+    webgl: {
+      vendor: 'WebKit',
+      renderer: 'WebKit WebGL',
+      unmaskedVendor: 'Google Inc. (NVIDIA)',
+      unmaskedRenderer: 'ANGLE (NVIDIA, NVIDIA GeForce RTX 3060, D3D11)',
+    },
+  });
+  const script = buildFingerprintInitScript(profile, {
+    patchWebdriver: true,
+    patchLanguages: true,
+  });
+
+  it('replaces the values a page reads from navigator', () => {
+    const context = runInFakeRealm(script);
+
+    assert.equal(vm.runInContext('navigator.deviceMemory', context), 8);
+    assert.equal(vm.runInContext('navigator.vendor', context), 'Google Inc.');
+    assert.equal(vm.runInContext('navigator.webdriver', context), false);
+    assert.equal(vm.runInContext('navigator.language', context), 'de-DE');
+    assert.deepEqual(
+      vm.runInContext('Array.from(navigator.languages)', context),
+      ['de-DE', 'de']
+    );
+  });
+
+  it('hands out a frozen copy of languages so page code cannot mutate ours', () => {
+    const context = runInFakeRealm(script);
+
+    assert.equal(
+      vm.runInContext('Object.isFrozen(navigator.languages)', context),
+      true
+    );
+    assert.equal(
+      vm.runInContext('navigator.languages !== navigator.languages', context),
+      true
+    );
+  });
+
+  it('patches only the screen fields the profile named', () => {
+    const context = runInFakeRealm(script);
+
+    assert.equal(vm.runInContext('screen.availHeight', context), 1032);
+    assert.equal(vm.runInContext('screen.colorDepth', context), 24);
+    // width and height stay with the browser-side override.
+    assert.equal(vm.runInContext('screen.width', context), 1);
+  });
+
+  it('answers the WebGL renderer queries and forwards everything else', () => {
+    const context = runInFakeRealm(script);
+
+    // 0x9245/0x9246 are UNMASKED_VENDOR_WEBGL/UNMASKED_RENDERER_WEBGL.
+    assert.equal(
+      vm.runInContext('gl.getParameter(0x9245)', context),
+      'Google Inc. (NVIDIA)'
+    );
+    assert.equal(vm.runInContext('gl.getParameter(0x1f00)', context), 'WebKit');
+    assert.equal(
+      vm.runInContext('gl.getParameter(0x1234)', context),
+      'real-4660'
+    );
+  });
+
+  it('keeps the descriptor shape of a real accessor', () => {
+    const context = runInFakeRealm(script);
+    const descriptor = vm.runInContext(
+      `(() => {
+        const d = Object.getOwnPropertyDescriptor(Navigator.prototype, 'deviceMemory');
+        return {
+          enumerable: d.enumerable,
+          configurable: d.configurable,
+          hasGetter: typeof d.get === 'function',
+          setter: d.set,
+          name: d.get.name,
+        };
+      })()`,
+      context
+    );
+
+    assert.deepEqual(descriptor, {
+      enumerable: true,
+      configurable: true,
+      hasGetter: true,
+      setter: undefined,
+      name: 'get deviceMemory',
+    });
+  });
+
+  it('makes the replacements report native source', () => {
+    const context = runInFakeRealm(script);
+
+    assert.equal(
+      vm.runInContext(
+        "Object.getOwnPropertyDescriptor(Navigator.prototype, 'deviceMemory').get.toString()",
+        context
+      ),
+      'function get deviceMemory() { [native code] }'
+    );
+    assert.equal(
+      vm.runInContext(
+        'WebGLRenderingContext.prototype.getParameter.toString()',
+        context
+      ),
+      'function getParameter() { [native code] }'
+    );
+    // The masking of toString itself has to be masked too, or the patch is
+    // detectable by asking the one function that does the lying.
+    assert.equal(
+      vm.runInContext('Function.prototype.toString.toString()', context),
+      'function toString() { [native code] }'
+    );
+    // Untouched functions still report their real source.
+    assert.match(
+      vm.runInContext('(function example() { return 1; }).toString()', context),
+      /return 1/u
+    );
+  });
+
+  it('does not stack getters when the script runs twice', () => {
+    const context = runInFakeRealm(script);
+    vm.runInContext(script, context);
+
+    assert.equal(vm.runInContext('navigator.deviceMemory', context), 8);
+    assert.equal(
+      vm.runInContext(
+        'WebGLRenderingContext.prototype.getParameter.toString()',
+        context
+      ),
+      'function getParameter() { [native code] }'
+    );
+    assert.equal(
+      vm.runInContext('gl.getParameter(0x1234)', context),
+      'real-4660'
+    );
+  });
+
+  it('carries the shared payload asset and nothing else', () => {
+    // The payload is one file that Python and Rust send byte for byte, so the
+    // script has to be that file rather than a copy generated from a function
+    // in this package. scripts/check-shared-fingerprint-assets.sh guards the copies.
+    assert.ok(script.includes(FINGERPRINT_PAYLOAD_SOURCE));
+    assert.match(
+      FINGERPRINT_PAYLOAD_SOURCE,
+      /^function fingerprintPayload\(/mu
+    );
+    assert.doesNotMatch(FINGERPRINT_PAYLOAD_SOURCE, /^(import|export)\s/mu);
+  });
+
+  it('leaves no helper of its own on the page global', () => {
+    const context = runInFakeRealm(script);
+
+    assert.equal(
+      vm.runInContext('typeof fingerprintPayload', context),
+      'undefined'
+    );
+  });
+
+  it('hides its own marker from enumeration', () => {
+    const context = runInFakeRealm(script);
+
+    assert.equal(
+      vm.runInContext(
+        "Object.keys(globalThis).includes('__browserCommanderFingerprint')",
+        context
+      ),
+      false
+    );
+  });
+});