browser-commander 0.16.1 → 0.17.0

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

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

@@ -0,0 +1,184 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { readFileSync } from 'node:fs';
+
+import {
+  FINGERPRINT_LIMITATIONS,
+  findFingerprintLimitation,
+  relevantFingerprintLimitations,
+} from '../../../src/fingerprint/limitations.js';
+
+const ids = (limitations) => limitations.map((limitation) => limitation.id);
+
+describe('the documented limitations', () => {
+  it('gives every entry a unique id and the fields a reader needs', () => {
+    const seen = new Set();
+    for (const limitation of FINGERPRINT_LIMITATIONS) {
+      assert.ok(!seen.has(limitation.id), `duplicate id ${limitation.id}`);
+      seen.add(limitation.id);
+      assert.ok(limitation.surface.length > 0, limitation.id);
+      assert.ok(limitation.detail.length > 0, limitation.id);
+      assert.ok(
+        ['high', 'medium', 'low'].includes(limitation.severity),
+        limitation.id
+      );
+      assert.ok(
+        ['measured', 'documented'].includes(limitation.evidence),
+        limitation.id
+      );
+    }
+  });
+
+  it('points every measured entry at the artifact that proves it', () => {
+    for (const limitation of FINGERPRINT_LIMITATIONS) {
+      if (limitation.evidence === 'measured') {
+        assert.ok(limitation.reference, `${limitation.id} needs a reference`);
+      }
+    }
+  });
+
+  it('cannot be edited by a caller', () => {
+    assert.ok(Object.isFrozen(FINGERPRINT_LIMITATIONS));
+    assert.ok(FINGERPRINT_LIMITATIONS.every((entry) => Object.isFrozen(entry)));
+  });
+
+  it('is the shared JSON asset Python and Rust also publish', () => {
+    // The catalogue is data, not code, so the three packages ship one file
+    // rather than three translations of the same eleven paragraphs.
+    const asset = JSON.parse(
+      readFileSync(
+        new URL('../../../src/fingerprint/limitations.json', import.meta.url),
+        'utf8'
+      )
+    );
+
+    assert.deepEqual(asset, FINGERPRINT_LIMITATIONS);
+  });
+
+  it('looks an entry up by id', () => {
+    assert.equal(
+      findFingerprintLimitation('webgl-strings-only').surface,
+      'WebGL renderer strings and driver limits'
+    );
+    assert.equal(findFingerprintLimitation('no-such-limitation'), undefined);
+  });
+});
+
+describe('limitations relevant to a profile', () => {
+  it('always reports the two nothing can be done about', () => {
+    assert.deepEqual(ids(relevantFingerprintLimitations()), [
+      'canvas-audio-font-follow-the-host',
+      'network-layer-not-covered',
+    ]);
+  });
+
+  it("mentions the launch-only switch only when attaching to someone else's browser", () => {
+    assert.ok(
+      !ids(relevantFingerprintLimitations({}, {})).includes(
+        'automation-controlled-is-launch-only'
+      )
+    );
+    assert.ok(
+      ids(relevantFingerprintLimitations({}, { attached: true })).includes(
+        'automation-controlled-is-launch-only'
+      )
+    );
+  });
+
+  it('mentions headless only for a headless browser', () => {
+    assert.ok(
+      ids(relevantFingerprintLimitations({}, { headless: true })).includes(
+        'headless-is-distinguishable'
+      )
+    );
+  });
+
+  it('mentions the JavaScript-only fields when the profile sets them', () => {
+    assert.ok(
+      ids(relevantFingerprintLimitations({ deviceMemory: 8 })).includes(
+        'no-cdp-device-memory-override'
+      )
+    );
+    assert.ok(
+      ids(relevantFingerprintLimitations({ doNotTrack: '1' })).includes(
+        'no-cdp-vendor-or-dnt-override'
+      )
+    );
+    assert.ok(
+      ids(
+        relevantFingerprintLimitations({ webgl: { vendor: 'WebKit' } })
+      ).includes('webgl-strings-only')
+    );
+  });
+
+  it('mentions the screen entry only for the fields CDP does not emulate', () => {
+    assert.ok(
+      !ids(
+        relevantFingerprintLimitations({
+          screen: { width: 1920, height: 1080 },
+        })
+      ).includes('screen-depth-and-avail-not-emulated')
+    );
+    assert.ok(
+      ids(
+        relevantFingerprintLimitations({
+          screen: { width: 1920, height: 1080, availHeight: 1032 },
+        })
+      ).includes('screen-depth-and-avail-not-emulated')
+    );
+  });
+
+  it('mentions the pointer side effect only when touch is actually enabled', () => {
+    assert.ok(
+      !ids(relevantFingerprintLimitations({ maxTouchPoints: 0 })).includes(
+        'touch-emulation-changes-pointer-media'
+      )
+    );
+    assert.ok(
+      ids(relevantFingerprintLimitations({ maxTouchPoints: 5 })).includes(
+        'touch-emulation-changes-pointer-media'
+      )
+    );
+  });
+
+  it('mentions workers for every field a worker reads differently', () => {
+    // Measured in worker-visibility.json: platform, languages and
+    // hardwareConcurrency revert to the host values inside a worker even
+    // though the page session overrides them.
+    for (const profile of [
+      { platform: 'Win32' },
+      { languages: ['de-DE'] },
+      { hardwareConcurrency: 8 },
+      { deviceMemory: 8 },
+    ]) {
+      assert.ok(
+        ids(relevantFingerprintLimitations(profile)).includes(
+          'init-script-does-not-reach-workers'
+        ),
+        JSON.stringify(profile)
+      );
+    }
+    assert.ok(
+      !ids(relevantFingerprintLimitations({ timezoneId: 'UTC' })).includes(
+        'init-script-does-not-reach-workers'
+      )
+    );
+  });
+
+  it('keeps the declaration order and returns a frozen list', () => {
+    const relevant = relevantFingerprintLimitations(
+      { deviceMemory: 8, webgl: { vendor: 'WebKit' } },
+      { headless: true, attached: true }
+    );
+
+    assert.ok(Object.isFrozen(relevant));
+    assert.deepEqual(
+      ids(relevant),
+      ids(
+        FINGERPRINT_LIMITATIONS.filter((entry) =>
+          ids(relevant).includes(entry.id)
+        )
+      )
+    );
+  });
+});

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

@@ -0,0 +1,135 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+
+import {
+  createFingerprintPreset,
+  FINGERPRINT_PRESET_NAMES,
+} from '../../../src/fingerprint/presets.js';
+import { buildCdpEmulationCommands } from '../../../src/fingerprint/cdp-overrides.js';
+
+describe('fingerprint presets', () => {
+  it('names the platforms Chrome ships on', () => {
+    assert.deepEqual(
+      [...FINGERPRINT_PRESET_NAMES],
+      ['android-chrome', 'linux-chrome', 'macos-chrome', 'windows-chrome']
+    );
+  });
+
+  it('rejects an unknown preset and lists the known ones', () => {
+    assert.throws(
+      () => createFingerprintPreset('windows-edge'),
+      /unknown fingerprint preset "windows-edge".*windows-chrome/su
+    );
+  });
+
+  it('rejects a Chrome version that is not a dotted number', () => {
+    for (const chromeVersion of ['latest', '', 140, '140.x']) {
+      assert.throws(
+        () => createFingerprintPreset('linux-chrome', { chromeVersion }),
+        /dotted numeric version string/u
+      );
+    }
+  });
+
+  it('describes one machine consistently', () => {
+    // Every serious fingerprinting script cross-checks these against each
+    // other, so a preset is only useful when they agree.
+    const expectations = {
+      'windows-chrome': {
+        platform: 'Win32',
+        uaToken: 'Windows NT 10.0',
+        hint: 'Windows',
+        mobile: false,
+      },
+      'macos-chrome': {
+        platform: 'MacIntel',
+        uaToken: 'Mac OS X',
+        hint: 'macOS',
+        mobile: false,
+      },
+      'linux-chrome': {
+        platform: 'Linux x86_64',
+        uaToken: 'X11; Linux x86_64',
+        hint: 'Linux',
+        mobile: false,
+      },
+      'android-chrome': {
+        platform: 'Linux armv81',
+        uaToken: 'Android 15',
+        hint: 'Android',
+        mobile: true,
+      },
+    };
+
+    for (const [name, expected] of Object.entries(expectations)) {
+      const profile = createFingerprintPreset(name);
+      assert.equal(profile.platform, expected.platform, name);
+      assert.ok(profile.userAgent.includes(expected.uaToken), name);
+      assert.equal(profile.userAgentData.platform, expected.hint, name);
+      assert.equal(profile.userAgentData.mobile, expected.mobile, name);
+      assert.equal(profile.viewport.mobile, expected.mobile, name);
+      assert.equal(
+        profile.userAgent.includes('Mobile Safari'),
+        expected.mobile,
+        name
+      );
+      assert.deepEqual(
+        profile.userAgentData.formFactors,
+        [expected.mobile ? 'Mobile' : 'Desktop'],
+        name
+      );
+    }
+  });
+
+  it('keeps the viewport inside the screen it claims', () => {
+    for (const name of FINGERPRINT_PRESET_NAMES) {
+      const { screen, viewport } = createFingerprintPreset(name);
+      assert.ok(viewport.width <= screen.width, name);
+      assert.ok(viewport.height <= screen.availHeight, name);
+      assert.ok(screen.availWidth <= screen.width, name);
+      assert.ok(screen.availHeight <= screen.height, name);
+    }
+  });
+
+  it('gives touch points only to the mobile preset', () => {
+    assert.equal(createFingerprintPreset('android-chrome').maxTouchPoints, 5);
+    for (const name of ['windows-chrome', 'macos-chrome', 'linux-chrome']) {
+      assert.equal(createFingerprintPreset(name).maxTouchPoints, 0, name);
+    }
+  });
+
+  it('puts the requested Chrome version everywhere it appears', () => {
+    const profile = createFingerprintPreset('windows-chrome', {
+      chromeVersion: '141.0.7390.55',
+    });
+
+    // The user agent carries only the major version, as Chrome freezes it.
+    assert.ok(profile.userAgent.includes('Chrome/141.0.0.0'));
+    for (const entry of profile.userAgentData.brands) {
+      assert.ok(['141', '24'].includes(entry.version), entry.brand);
+    }
+    assert.ok(
+      profile.userAgentData.fullVersionList.some(
+        (entry) => entry.version === '141.0.7390.55'
+      )
+    );
+  });
+
+  it('merges caller overrides over the preset', () => {
+    const profile = createFingerprintPreset('linux-chrome', {
+      overrides: { timezoneId: 'Europe/Lisbon', hardwareConcurrency: 32 },
+    });
+
+    assert.equal(profile.timezoneId, 'Europe/Lisbon');
+    assert.equal(profile.hardwareConcurrency, 32);
+    assert.equal(profile.platform, 'Linux x86_64');
+  });
+
+  it('returns a normalized, frozen profile every preset can be applied from', () => {
+    for (const name of FINGERPRINT_PRESET_NAMES) {
+      const profile = createFingerprintPreset(name);
+      assert.ok(Object.isFrozen(profile), name);
+      assert.ok(buildCdpEmulationCommands(profile).length > 0, name);
+    }
+  });
+});