browser-commander 0.16.0 → 0.17.0

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

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

@@ -0,0 +1,282 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+
+import {
+  FINGERPRINT_FIELD_MECHANISMS,
+  resolveFingerprintProfile,
+} from '../../../src/fingerprint/profile.js';
+
+const CHROME_UA =
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ' +
+  '(KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36';
+
+describe('fingerprint profile', () => {
+  it('returns an empty frozen profile for an empty input', () => {
+    const profile = resolveFingerprintProfile();
+
+    assert.deepEqual(profile, {});
+    assert.ok(Object.isFrozen(profile));
+  });
+
+  it('drops fields that were not supplied instead of filling in defaults', () => {
+    const profile = resolveFingerprintProfile({ locale: 'de-DE' });
+
+    assert.deepEqual(Object.keys(profile), ['locale']);
+  });
+
+  it('rejects an unknown field rather than silently ignoring it', () => {
+    assert.throws(
+      () => resolveFingerprintProfile({ hardwareConcurency: 8 }),
+      /unknown fingerprint profile field "hardwareConcurency"/u
+    );
+  });
+
+  it('rejects a profile that is not a plain object', () => {
+    for (const input of [null, [], 'profile', 42]) {
+      assert.throws(
+        () => resolveFingerprintProfile(input),
+        /fingerprint profile must be an object/u
+      );
+    }
+  });
+
+  it('derives acceptLanguage from languages when only languages is given', () => {
+    const profile = resolveFingerprintProfile({
+      languages: ['de-DE', 'de', 'en'],
+    });
+
+    assert.equal(profile.acceptLanguage, 'de-DE,de,en');
+    assert.deepEqual(profile.languages, ['de-DE', 'de', 'en']);
+  });
+
+  it('keeps an explicit acceptLanguage over the derived one', () => {
+    const profile = resolveFingerprintProfile({
+      languages: ['de-DE', 'de'],
+      acceptLanguage: 'fr-FR,fr',
+    });
+
+    assert.equal(profile.acceptLanguage, 'fr-FR,fr');
+  });
+
+  // Chrome splits acceptLanguage on commas without stripping q-values, so a
+  // q-value ends up inside a language tag and doubled in the header.
+  it('rejects q-values in acceptLanguage, which Chrome would misparse', () => {
+    assert.throws(
+      () => resolveFingerprintProfile({ acceptLanguage: 'de-DE,de;q=0.9' }),
+      /must be a plain comma-separated language list without q-values/u
+    );
+  });
+
+  it('derives client hints from a Chrome user agent', () => {
+    const profile = resolveFingerprintProfile({ userAgent: CHROME_UA });
+
+    assert.equal(profile.userAgentData.platform, 'Windows');
+    assert.equal(profile.userAgentData.architecture, 'x86');
+    assert.equal(profile.userAgentData.bitness, '64');
+    assert.equal(profile.userAgentData.mobile, false);
+    assert.ok(
+      profile.userAgentData.brands.some(
+        (entry) => entry.brand === 'Google Chrome' && entry.version === '140'
+      )
+    );
+  });
+
+  it('fills uaFullVersion from the Chrome entry of fullVersionList', () => {
+    const profile = resolveFingerprintProfile({
+      userAgentData: {
+        fullVersionList: [
+          { brand: 'Not=A?Brand', version: '24.0.0.0' },
+          { brand: 'Google Chrome', version: '140.0.7000.1' },
+        ],
+      },
+    });
+
+    assert.equal(profile.userAgentData.fullVersion, '140.0.7000.1');
+  });
+
+  it('keeps an explicit fullVersion instead of deriving one', () => {
+    const profile = resolveFingerprintProfile({
+      userAgentData: {
+        fullVersion: '99.1.2.3',
+        fullVersionList: [{ brand: 'Google Chrome', version: '140.0.0.0' }],
+      },
+    });
+
+    assert.equal(profile.userAgentData.fullVersion, '99.1.2.3');
+  });
+
+  it('lets an explicit userAgentData win over the one derived from the user agent', () => {
+    const profile = resolveFingerprintProfile({
+      userAgent: CHROME_UA,
+      userAgentData: { platform: 'macOS' },
+    });
+
+    assert.equal(profile.userAgentData.platform, 'macOS');
+  });
+
+  it('accepts every configurable field at once', () => {
+    const profile = resolveFingerprintProfile({
+      userAgent: CHROME_UA,
+      languages: ['de-DE', 'de'],
+      locale: 'de-DE',
+      timezoneId: 'Europe/Berlin',
+      platform: 'Win32',
+      vendor: 'Google Inc.',
+      hardwareConcurrency: 24,
+      deviceMemory: 32,
+      maxTouchPoints: 5,
+      doNotTrack: '1',
+      screen: {
+        width: 3840,
+        height: 2160,
+        availWidth: 3840,
+        availHeight: 2100,
+        colorDepth: 30,
+        pixelDepth: 30,
+      },
+      viewport: {
+        width: 1600,
+        height: 900,
+        deviceScaleFactor: 2,
+        mobile: false,
+      },
+      webgl: { unmaskedVendor: 'NVIDIA', unmaskedRenderer: 'RTX 4090' },
+      geolocation: { latitude: 52.52, longitude: 13.405, accuracy: 12 },
+      colorScheme: 'dark',
+      reducedMotion: 'reduce',
+      forcedColors: 'active',
+    });
+
+    assert.equal(profile.hardwareConcurrency, 24);
+    assert.equal(profile.deviceMemory, 32);
+    assert.equal(profile.screen.colorDepth, 30);
+    assert.equal(profile.viewport.deviceScaleFactor, 2);
+    assert.equal(profile.webgl.unmaskedRenderer, 'RTX 4090');
+    assert.equal(profile.geolocation.accuracy, 12);
+    assert.equal(profile.forcedColors, 'active');
+  });
+
+  it('rejects a hardwareConcurrency that is not a positive integer', () => {
+    for (const value of [0, -4, 2.5, '8']) {
+      assert.throws(
+        () => resolveFingerprintProfile({ hardwareConcurrency: value }),
+        /hardwareConcurrency must be a positive integer/u
+      );
+    }
+  });
+
+  it('allows maxTouchPoints to be zero but not negative', () => {
+    assert.equal(
+      resolveFingerprintProfile({ maxTouchPoints: 0 }).maxTouchPoints,
+      0
+    );
+    assert.throws(
+      () => resolveFingerprintProfile({ maxTouchPoints: -1 }),
+      /maxTouchPoints must be a non-negative integer/u
+    );
+  });
+
+  it('requires screen width and height to be given together', () => {
+    assert.throws(
+      () => resolveFingerprintProfile({ screen: { width: 1920 } }),
+      /screen.width and screen.height must be provided together/u
+    );
+  });
+
+  it('requires viewport width and height to be given together', () => {
+    assert.throws(
+      () => resolveFingerprintProfile({ viewport: { height: 900 } }),
+      /viewport.width and viewport.height must be provided together/u
+    );
+  });
+
+  it('rejects out-of-range coordinates', () => {
+    assert.throws(
+      () =>
+        resolveFingerprintProfile({
+          geolocation: { latitude: 91, longitude: 0 },
+        }),
+      /latitude must be between -90 and 90/u
+    );
+    assert.throws(
+      () =>
+        resolveFingerprintProfile({
+          geolocation: { latitude: 0, longitude: -181 },
+        }),
+      /longitude must be between -180 and 180/u
+    );
+  });
+
+  it('rejects an unsupported enum value', () => {
+    assert.throws(
+      () => resolveFingerprintProfile({ colorScheme: 'sepia' }),
+      /colorScheme must be one of light, dark, no-preference/u
+    );
+  });
+
+  it('rejects an empty languages array', () => {
+    assert.throws(
+      () => resolveFingerprintProfile({ languages: [] }),
+      /languages must not be empty/u
+    );
+  });
+
+  it('rejects a brand entry with a non-string version', () => {
+    assert.throws(
+      () =>
+        resolveFingerprintProfile({
+          userAgentData: { brands: [{ brand: 'Chromium', version: 140 }] },
+        }),
+      /userAgentData.brands\[0\].version must be a string/u
+    );
+  });
+
+  it('treats null the same as an omitted field', () => {
+    const profile = resolveFingerprintProfile({
+      locale: null,
+      screen: null,
+      webgl: null,
+    });
+
+    assert.deepEqual(profile, {});
+  });
+
+  it('copies arrays so a later mutation of the input cannot reach the profile', () => {
+    const languages = ['de-DE', 'de'];
+    const profile = resolveFingerprintProfile({ languages });
+    languages.push('en');
+
+    assert.deepEqual(profile.languages, ['de-DE', 'de']);
+  });
+
+  it('records a mechanism for every field the profile accepts', () => {
+    const everyField = resolveFingerprintProfile({
+      userAgent: CHROME_UA,
+      acceptLanguage: 'en-US,en',
+      languages: ['en-US', 'en'],
+      locale: 'en-US',
+      timezoneId: 'UTC',
+      platform: 'Win32',
+      vendor: 'Google Inc.',
+      hardwareConcurrency: 8,
+      deviceMemory: 8,
+      maxTouchPoints: 0,
+      doNotTrack: '1',
+      screen: { width: 1920, height: 1080 },
+      viewport: { width: 1280, height: 720 },
+      webgl: { unmaskedVendor: 'Intel' },
+      geolocation: { latitude: 0, longitude: 0 },
+      colorScheme: 'dark',
+      reducedMotion: 'reduce',
+      forcedColors: 'active',
+    });
+
+    for (const field of Object.keys(everyField)) {
+      assert.ok(
+        FINGERPRINT_FIELD_MECHANISMS[field] === 'browser' ||
+          FINGERPRINT_FIELD_MECHANISMS[field] === 'script',
+        `no mechanism recorded for "${field}"`
+      );
+    }
+  });
+});