jumpy-lion 0.1.6-beta.9 → 1.0.0-beta.4

package/dist/fingerprinting/os-consistency.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Describe a contradiction between the two OS-related config knobs, if any.
+ *
+ * The crawler historically exposed two ways to express "I want fingerprints
+ * from OS X":
+ *
+ *   1. `browserPoolOptions.fingerprintOptions.fingerprintGeneratorOptions.operatingSystems`
+ *      - Crawlee's standard knob, an array of `'macos' | 'linux' | 'windows'`.
+ *      This is the **single source of truth** for OS selection (issue #80).
+ *
+ *   2. `launchContext.launchOptions.fingerprintOptions.platform` - the legacy
+ *      anti-detect knob, a single `'MacIntel' | 'Win32' | 'Linux x86_64'`. It is
+ *      deprecated and, when it disagrees with `operatingSystems`, loses: the
+ *      resolved OS is derived from the fingerprint the generator produced.
+ *
+ * This used to `throw` on disagreement, aborting the launch (and, at the
+ * per-page selection site, a whole crawl). Under the #80 single-source model
+ * the contradiction is no longer fatal - `operatingSystems` simply wins and the
+ * caller gets a warning. This function returns that human-readable warning (or
+ * `null` when the pair is consistent / not both caller-supplied), leaving the
+ * decision to `log.warning` to the caller.
+ *
+ * Only reports when BOTH values are present - host-OS auto-fill for
+ * `operatingSystems` is internal policy, not a user statement of intent, so it
+ * never conflicts with an explicit `platform` pin.
+ */
+export declare function describeOsConflict(callerOpSys: string | undefined, platform: string | undefined): string | null;
+//# sourceMappingURL=os-consistency.d.ts.map

package/dist/fingerprinting/os-consistency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"os-consistency.d.ts","sourceRoot":"","sources":["../../src/fingerprinting/os-consistency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,kBAAkB,CAC9B,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC7B,MAAM,GAAG,IAAI,CAgBf"}

package/dist/fingerprinting/os-consistency.js

@@ -0,0 +1,45 @@
+/**
+ * Describe a contradiction between the two OS-related config knobs, if any.
+ *
+ * The crawler historically exposed two ways to express "I want fingerprints
+ * from OS X":
+ *
+ *   1. `browserPoolOptions.fingerprintOptions.fingerprintGeneratorOptions.operatingSystems`
+ *      - Crawlee's standard knob, an array of `'macos' | 'linux' | 'windows'`.
+ *      This is the **single source of truth** for OS selection (issue #80).
+ *
+ *   2. `launchContext.launchOptions.fingerprintOptions.platform` - the legacy
+ *      anti-detect knob, a single `'MacIntel' | 'Win32' | 'Linux x86_64'`. It is
+ *      deprecated and, when it disagrees with `operatingSystems`, loses: the
+ *      resolved OS is derived from the fingerprint the generator produced.
+ *
+ * This used to `throw` on disagreement, aborting the launch (and, at the
+ * per-page selection site, a whole crawl). Under the #80 single-source model
+ * the contradiction is no longer fatal - `operatingSystems` simply wins and the
+ * caller gets a warning. This function returns that human-readable warning (or
+ * `null` when the pair is consistent / not both caller-supplied), leaving the
+ * decision to `log.warning` to the caller.
+ *
+ * Only reports when BOTH values are present - host-OS auto-fill for
+ * `operatingSystems` is internal policy, not a user statement of intent, so it
+ * never conflicts with an explicit `platform` pin.
+ */
+export function describeOsConflict(callerOpSys, platform) {
+    if (!callerOpSys || !platform)
+        return null;
+    const PLATFORM_TO_OS = {
+        'MacIntel': 'macos',
+        'Win32': 'windows',
+        'Linux x86_64': 'linux',
+    };
+    const platformOs = PLATFORM_TO_OS[platform];
+    if (!platformOs)
+        return null; // unknown platform string - nothing to compare
+    if (platformOs === callerOpSys.toLowerCase())
+        return null;
+    return (`[AntiDetect] OS configuration conflict (issue #80): `
+        + `browserPoolOptions.fingerprintOptions.fingerprintGeneratorOptions.operatingSystems=['${callerOpSys}'] `
+        + `contradicts the deprecated launchOptions.fingerprintOptions.platform='${platform}'. `
+        + `operatingSystems is the single source of truth and wins; drop fingerprintOptions.platform to silence this.`);
+}
+//# sourceMappingURL=os-consistency.js.map

package/dist/fingerprinting/os-consistency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"os-consistency.js","sourceRoot":"","sources":["../../src/fingerprinting/os-consistency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,kBAAkB,CAC9B,WAA+B,EAC/B,QAA4B;IAE5B,IAAI,CAAC,WAAW,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3C,MAAM,cAAc,GAA2B;QAC3C,UAAU,EAAE,OAAO;QACnB,OAAO,EAAE,SAAS;QAClB,cAAc,EAAE,OAAO;KAC1B,CAAC;IACF,MAAM,UAAU,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IAC5C,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC,CAAC,+CAA+C;IAC7E,IAAI,UAAU,KAAK,WAAW,CAAC,WAAW,EAAE;QAAE,OAAO,IAAI,CAAC;IAC1D,OAAO,CACH,sDAAsD;UACpD,wFAAwF,WAAW,KAAK;UACxG,yEAAyE,QAAQ,KAAK;UACtF,4GAA4G,CACjH,CAAC;AACN,CAAC"}

package/dist/fingerprinting/profile-quality.d.ts

@@ -0,0 +1,25 @@
+import type { NavigatorPlatform } from '../session-profile.js';
+/**
+ * Pool-contamination gate for fingerprint profiles.
+ *
+ * The upstream fingerprint-generator dataset contains a small but recurring
+ * fraction (~30-40%) of profiles that come from Lark/Feishu (ByteDance)
+ * modified Chrome installs and similar third-party browser modifications.
+ * Telltales:
+ *   - a non-Chrome UA (Firefox / Safari) returned despite browsers:['chrome']
+ *   - userAgent suffix " LarkUrl" or mid-UA " newsai/X.Y.Z" injection
+ *   - navigator.platform = "Linux x86_64" while UA claims Macintosh
+ *   - hardwareConcurrency > 32 (server CPU; consumer Macs are 4-16)
+ *   - "10_15_6" frozen UA stamp instead of canonical Chrome 147 "10_15_7"
+ * A contaminated profile flows verbatim into FingerprintConfig and the
+ * C++ patches dutifully spoof to it - every CreepJS/DataDome/Naver run
+ * sees a bot.
+ *
+ * @param fp a BrowserFingerprintWithHeaders-shaped profile
+ * @param expectedPlatform when set, profiles of any other OS are rejected
+ *        outright - even a "clean" profile of the wrong OS is a non-starter
+ *        when targeting a specific host.
+ * @returns a human-readable rejection reason, or null when the profile is clean
+ */
+export declare function rejectContaminatedProfile(fp: any, expectedPlatform: NavigatorPlatform | null): string | null;
+//# sourceMappingURL=profile-quality.d.ts.map

package/dist/fingerprinting/profile-quality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-quality.d.ts","sourceRoot":"","sources":["../../src/fingerprinting/profile-quality.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAG/D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,yBAAyB,CACrC,EAAE,EAAE,GAAG,EACP,gBAAgB,EAAE,iBAAiB,GAAG,IAAI,GAC3C,MAAM,GAAG,IAAI,CA6Sf"}

package/dist/fingerprinting/profile-quality.js

@@ -0,0 +1,310 @@
+import { describeGreaseIncoherence, isGreaseBrand } from './ua-ch-brands.js';
+/**
+ * Pool-contamination gate for fingerprint profiles.
+ *
+ * The upstream fingerprint-generator dataset contains a small but recurring
+ * fraction (~30-40%) of profiles that come from Lark/Feishu (ByteDance)
+ * modified Chrome installs and similar third-party browser modifications.
+ * Telltales:
+ *   - a non-Chrome UA (Firefox / Safari) returned despite browsers:['chrome']
+ *   - userAgent suffix " LarkUrl" or mid-UA " newsai/X.Y.Z" injection
+ *   - navigator.platform = "Linux x86_64" while UA claims Macintosh
+ *   - hardwareConcurrency > 32 (server CPU; consumer Macs are 4-16)
+ *   - "10_15_6" frozen UA stamp instead of canonical Chrome 147 "10_15_7"
+ * A contaminated profile flows verbatim into FingerprintConfig and the
+ * C++ patches dutifully spoof to it - every CreepJS/DataDome/Naver run
+ * sees a bot.
+ *
+ * @param fp a BrowserFingerprintWithHeaders-shaped profile
+ * @param expectedPlatform when set, profiles of any other OS are rejected
+ *        outright - even a "clean" profile of the wrong OS is a non-starter
+ *        when targeting a specific host.
+ * @returns a human-readable rejection reason, or null when the profile is clean
+ */
+export function rejectContaminatedProfile(fp, expectedPlatform) {
+    const nav = fp?.fingerprint?.navigator ?? {};
+    const ua = nav.userAgent ?? '';
+    const platform = nav.platform ?? '';
+    const hwc = nav.hardwareConcurrency ?? 0;
+    const uaData = nav.userAgentData ?? {};
+    const arch = uaData.architecture ?? '';
+    const platformVersion = uaData.platformVersion ?? '';
+    const brands = uaData.brands ?? [];
+    const fullVersionList = uaData.fullVersionList ?? [];
+    const videoCard = fp?.fingerprint?.videoCard ?? {};
+    const gpuRenderer = videoCard.renderer ?? '';
+    // Reject host-OS mismatches first - even a "clean" profile of the
+    // wrong OS is a non-starter when we're targeting a specific host.
+    if (expectedPlatform && platform && platform !== expectedPlatform) {
+        return `platform=${platform} != expected ${expectedPlatform} (host-OS pin)`;
+    }
+    // Reject non-Chrome browsers outright. The upstream pool occasionally
+    // returns a Firefox / Safari profile even when `browsers: ['chrome']` was
+    // requested (observed: "…Windows NT 10.0…Gecko/20100101 Firefox/147.0").
+    // Shipping one is fatal: setUserAgentWithMetadata cannot derive a Chrome
+    // version from it and THROWS, which aborts the ENTIRE fingerprint injection
+    // and leaks the browser's real identity. This crawler only launches Chrome,
+    // so a Firefox (real "Gecko/<8-digit build>" + "Firefox/N") or a Safari UA
+    // ("Safari/" without any "Chrome/") is contamination - reject it here so the
+    // selector re-rolls to a Chrome profile. (Chrome's own UA carries the
+    // "like Gecko" token with no slash and always includes "Chrome/N", so this
+    // never false-positives on real Chrome.)
+    const looksFirefox = /\bGecko\/\d{6,}|\bFirefox\/\d/i.test(ua);
+    const looksSafariNotChrome = /\bSafari\//i.test(ua) && !/\bChrome\/\d/.test(ua);
+    if (ua && (looksFirefox || looksSafariNotChrome)) {
+        return `UA is not Chrome (only Chrome profiles are supported): …${ua.slice(0, 60)}`;
+    }
+    if (/\b(LarkUrl|Lark\/|Feishu|newsai\/|toutiao|bytedance)\b/i.test(ua)) {
+        return `UA contains modified-Chrome marker: …${ua.slice(-60)}`;
+    }
+    if (hwc > 32) {
+        return `hardwareConcurrency=${hwc} exceeds consumer cap (server-class CPU)`;
+    }
+    // Pool occasionally returns ancient Chrome majors (108 from 2022,
+    // 128, 136…). For 2026 traffic this is implausibly old: real Chrome
+    // auto-updates and the share of >2-year-old majors is <1% in the
+    // wild. The launcher already re-stamps UA + UA-CH to the running
+    // binary version, but several profile-derived fields (Chromium
+    // version-gated feature exposure in fingerprint metadata) still
+    // reflect the source profile's vintage. Reject anything pre-140
+    // (Chrome 140 shipped 2025-08, conservative floor for "current"
+    // traffic in May 2026).
+    const chromeMajorMatch = ua.match(/Chrome\/(\d+)/);
+    const chromeMajor = chromeMajorMatch ? Number(chromeMajorMatch[1]) : 0;
+    if (chromeMajor > 0 && chromeMajor < 140) {
+        return `Chrome major ${chromeMajor} is stale (pre-140); current cutoff is 140+ for 2026 traffic`;
+    }
+    const claimsMac = /Macintosh|Mac OS X/i.test(ua);
+    // ─── UA OS token ↔ navigator.platform coherence (all platforms) ──
+    // Chrome freezes navigator.platform per-OS: Windows→"Win32",
+    // macOS→"MacIntel", Linux→"Linux <arch>". This is UA-CH-independent, so a
+    // UA OS token that disagrees with navigator.platform is a 100%-certain
+    // contradiction on EVERY OS - it catches the Windows/Linux mismatches the
+    // old Mac-only check missed (and subsumes it: a Mac UA with a non-MacIntel
+    // platform still fails here).
+    let uaOs = null;
+    if (claimsMac)
+        uaOs = 'macos';
+    else if (/Windows NT/i.test(ua))
+        uaOs = 'windows';
+    else if (/X11; Linux|Linux x86_64/i.test(ua) && !/Android|CrOS/i.test(ua))
+        uaOs = 'linux';
+    if (uaOs && platform) {
+        let platformOk;
+        if (uaOs === 'macos')
+            platformOk = platform === 'MacIntel';
+        else if (uaOs === 'windows')
+            platformOk = platform === 'Win32';
+        else
+            platformOk = /^Linux/i.test(platform);
+        if (!platformOk) {
+            return `UA claims ${uaOs} but navigator.platform=${platform} (Chrome freezes platform per-OS)`;
+        }
+    }
+    if (claimsMac && hwc > 0 && hwc < 8) {
+        // Real Apple Silicon Mac cores: M1=8, M1 Pro=8/10, M1 Max=10,
+        // M2=8, M2 Pro=10/12, M3+=8/10/12/14/16. Anything <8 is either
+        // a pre-2020 MacBook Air dual-core (Chrome dropped support long
+        // ago) or a VM/sandbox-capped profile - neither is plausible
+        // for 2026 Mac traffic claiming an Apple Silicon GPU.
+        return `hardwareConcurrency=${hwc} too low for Apple Silicon Mac (real range 8-16)`;
+    }
+    if (claimsMac && /Mac OS X 10_15_[0-6](?:[^0-9]|$)/i.test(ua)) {
+        // Canonical frozen Chrome 147+ macOS UA carries "10_15_7"; any other
+        // _N value is the Lark cluster's stale stamp.
+        return `Mac UA carries non-canonical 10_15_<6 stamp (Lark cluster signature)`;
+    }
+    // UA tail: after "Safari/537.36" real Chrome is bare. Any trailing
+    // token is a third-party UA-modifier brand (LarkUrl / Edg / OPR / etc).
+    const tailMatch = ua.match(/Safari\/537\.36(.*)$/);
+    if (tailMatch && tailMatch[1].trim().length > 0) {
+        return `UA has unexpected tail after Safari/537.36: "${tailMatch[1].trim()}"`;
+    }
+    // ─── Hardware / architecture / OS-version consistency ──────────
+    // CreepJS and modern anti-bot vendors cross-check
+    //   navigator.userAgentData.architecture  (x86 | arm)
+    //   navigator.userAgentData.platformVersion  (e.g. "15.7.1")
+    //   WEBGL_RENDERER  ("ANGLE (Apple, Apple Mn…)" vs "ANGLE (Intel,…)")
+    // against each other. Apify pool routinely ships profiles that
+    // violate every one of these - Intel iGPU + ARM arch, Apple M4 +
+    // x86 arch, Intel Mac claiming Sequoia (15.x, Apple-Silicon-only),
+    // etc. Each is an instant detection signal.
+    const rendererIsApple = /\bAngle \(Apple|Apple M\d|Apple GPU/i.test(gpuRenderer);
+    // Match any non-Apple desktop-Mac GPU vendor string. Includes:
+    //   - Modern ANGLE form:  "ANGLE (Intel, …)"  /  "ANGLE (AMD, …)"
+    //   - Parenthesised form: "Intel(R) Iris"  /  "Intel(R) UHD"
+    //   - Bare AMD form:      "AMD Radeon Pro 560"
+    //   - Bare NVIDIA form:   "NVIDIA GeForce GT 750M"  (old Mac Pro)
+    //   - Old OpenGL form:    "Intel Iris OpenGL Engine"  /
+    //                          "Intel HD Graphics OpenGL Engine"
+    //                          (pre-ANGLE Mac drivers; common in older
+    //                          pool profiles, was the regex hole that
+    //                          let arm-arch + Intel-GPU through)
+    const rendererIsNonAppleDesktopGpu = (/\bAngle \((Intel|AMD|NVIDIA)\b/i.test(gpuRenderer)
+        || /\bIntel\(R\)/i.test(gpuRenderer)
+        || /\bAMD Radeon\b/i.test(gpuRenderer)
+        || /\bNVIDIA\b/i.test(gpuRenderer)
+        || /\bIntel (Iris|HD|UHD|OpenGL)\b/i.test(gpuRenderer));
+    // ─── Architecture ↔ GPU renderer (physics, OS-independent) ──────
+    // Apple GPUs ship ONLY on Apple Silicon (arm); no arm consumer device ships
+    // an Intel/AMD/NVIDIA desktop GPU (arm Macs use Apple GPUs, arm Windows uses
+    // Qualcomm Adreno). These contradictions hold on any OS, so they run
+    // unconditionally - previously they were Mac-only, which let a Windows/Linux
+    // profile carrying the same arch↔GPU contradiction through.
+    if (arch === 'arm' && rendererIsNonAppleDesktopGpu) {
+        return `arch=arm contradicts non-Apple desktop GPU renderer "${gpuRenderer.slice(0, 60)}"`;
+    }
+    if (arch === 'x86' && rendererIsApple) {
+        return `arch=x86 contradicts Apple Silicon GPU renderer "${gpuRenderer.slice(0, 60)}"`;
+    }
+    // ─── macOS version ↔ architecture (Mac-specific) ───────────────
+    if (claimsMac) {
+        // platformVersion major sanity vs architecture:
+        //   26.x (Tahoe) is Apple-Silicon-only - Apple dropped Intel AFTER
+        //     Sequoia, so 15.x is the LAST Intel-capable macOS (2018-2020 Intel
+        //     Macs run it). The old `>= 15` cutoff false-rejected every real
+        //     Intel Sequoia Mac; the true Intel cutoff is 26 (Tahoe).
+        //   <11.x (pre-Big-Sur) is Intel-only - Apple Silicon launched on 11.0.
+        const pvMajor = parseInt(platformVersion.split('.')[0] ?? '0', 10);
+        if (pvMajor >= 26 && arch === 'x86') {
+            return `platformVersion=${platformVersion} (Tahoe+) requires Apple Silicon but arch=x86`;
+        }
+        if (pvMajor >= 1 && pvMajor < 11 && arch === 'arm') {
+            return `platformVersion=${platformVersion} (pre-Big-Sur) is Intel-only but arch=arm`;
+        }
+        // Same check via GPU class (defense-in-depth when arch is missing):
+        if (pvMajor >= 26 && rendererIsNonAppleDesktopGpu) {
+            return `platformVersion=${platformVersion} (Tahoe+) requires Apple Silicon but GPU is non-Apple desktop`;
+        }
+    }
+    // ─── Linux platform / GPU-renderer coherence ───────────────────
+    // The sampled `linux` pool in non-apify-profiles.json is contaminated:
+    // ~6% of "Linux x86_64" profiles carry a macOS WebGL renderer
+    // ("Intel Iris OpenGL Engine", "ANGLE (Apple, …)") and others a Windows
+    // D3D11 string. navigator.platform=Linux paired with a Mac/Windows GPU is
+    // an instant cross-platform contradiction (CreepJS/Akamai/DataDome read
+    // UNMASKED_RENDERER_WEBGL against the platform). The Mac block above only
+    // fires when the UA claims Macintosh, so a Linux-UA profile with a Mac GPU
+    // slips through - reject it here so the selector re-rolls to a clean Linux
+    // profile. Valid Linux renderers: "ANGLE (Intel, Mesa …)",
+    // "ANGLE (NVIDIA Corporation, … /PCIe/SSE2 …)", "ANGLE (AMD, … radeonsi …)",
+    // The GPU-less "ANGLE (Google, Vulkan … SwiftShader …)" software fallback
+    // is NOT valid for our purposes - it is a datacenter tell and is rejected
+    // unconditionally by the SwiftShader gate further below.
+    const claimsLinux = /X11; Linux|Linux x86_64/i.test(ua) || platform === 'Linux x86_64';
+    if (claimsLinux && gpuRenderer) {
+        if (/ANGLE \(Apple|Apple M\d|Apple GPU|Metal Renderer|Iris OpenGL Engine|HD Graphics OpenGL Engine/i.test(gpuRenderer)) {
+            return `platform=Linux but GPU renderer is macOS "${gpuRenderer.slice(0, 60)}"`;
+        }
+        if (/Direct3D|D3D11|vs_5_0|ps_5_0/i.test(gpuRenderer)) {
+            return `platform=Linux but GPU renderer is Windows D3D "${gpuRenderer.slice(0, 60)}"`;
+        }
+        // ARM SoC / single-board-computer GPUs (Raspberry Pi Broadcom V3D,
+        // ARM Mali, Qualcomm Adreno, Imagination PowerVR, Vivante) physically
+        // cannot appear on an x86_64 desktop. The pool is platform-strict
+        // Linux x86_64, so any of these is a cross-arch contradiction
+        // (vendor "ARM"/"Broadcom" + Linux x86_64) - an instant tell.
+        if (/\b(Mali|Adreno|PowerVR|Vivante|VideoCore)\b|Broadcom|\bV3D\b/i.test(gpuRenderer)) {
+            return `platform=Linux x86_64 but GPU renderer is ARM/embedded "${gpuRenderer.slice(0, 60)}"`;
+        }
+    }
+    // ─── Windows platform / GPU-renderer coherence ─────────────────
+    // Symmetric to the Linux block above. Real Windows Chrome reports a D3D11
+    // ANGLE renderer ("ANGLE (NVIDIA, … Direct3D11 …)"). A Windows platform
+    // paired with a macOS Metal/Apple GPU or a Linux Mesa renderer is a
+    // cross-platform contradiction read straight off UNMASKED_RENDERER_WEBGL.
+    // The Mac/Linux blocks only fire on their own UA, so a Windows profile
+    // carrying a foreign GPU slipped through before. (Linux markers are
+    // Mesa/llvmpipe/radeonsi + the Linux ANGLE tails "NVIDIA Corporation" /
+    // "/PCIe/" / "/SSE2"; Windows ANGLE strings carry none of these.)
+    const claimsWindows = /Windows NT/i.test(ua) || platform === 'Win32';
+    if (claimsWindows && gpuRenderer) {
+        if (/ANGLE \(Apple|Apple M\d|Apple GPU|Metal Renderer|Iris OpenGL Engine|HD Graphics OpenGL Engine/i.test(gpuRenderer)) {
+            return `platform=Windows but GPU renderer is macOS "${gpuRenderer.slice(0, 60)}"`;
+        }
+        if (/\bMesa\b|llvmpipe|radeonsi|NVIDIA Corporation|\/PCIe\/|\/SSE2\b/i.test(gpuRenderer)) {
+            return `platform=Windows but GPU renderer is Linux "${gpuRenderer.slice(0, 60)}"`;
+        }
+    }
+    // ─── Brand cohort consistency ──────────────────────────────────
+    // userAgentData.brands should carry only Chrome / Chromium / GREASE
+    // when we are launching a Chrome binary. Apify pool mixes in Brave/
+    // Edge/Opera/Yandex profiles whose brand entries advertise those
+    // browsers directly - CreepJS reads them via getHighEntropyValues
+    // and a Chrome UA paired with a Brave brand entry is an instant
+    // contradiction.
+    const ALLOWED_BRANDS = /^(Google Chrome|Chromium)$/;
+    const offending = brands.find(b => b?.brand && !isGreaseBrand(b.brand) && !ALLOWED_BRANDS.test(b.brand));
+    if (offending) {
+        return `userAgentData.brands includes non-Chrome derivative "${offending.brand}"`;
+    }
+    // …and the same check on the profile's `sec-ch-ua` HEADER, which is a
+    // SEPARATE field the JS-side check above never saw. 44 of the 200 bundled
+    // non-Apify rows advertise "Brave" in the header while their
+    // userAgentData.brands says Google Chrome - a page announcing Brave on the
+    // wire and Chrome in JS is a harder contradiction than the GREASE mismatch
+    // that started issue #131.
+    const secChUaHeader = Object.entries(fp?.headers ?? {})
+        .find(([k]) => k.toLowerCase() === 'sec-ch-ua')?.[1];
+    if (secChUaHeader) {
+        const headerBrands = [...secChUaHeader.matchAll(/"([^"]+)";\s*v="([^"]+)"/g)]
+            .map(m => ({ brand: m[1], version: m[2] }));
+        const offendingHeader = headerBrands.find(b => !isGreaseBrand(b.brand) && !ALLOWED_BRANDS.test(b.brand));
+        if (offendingHeader) {
+            return `sec-ch-ua header advertises non-Chrome derivative "${offendingHeader.brand}"`;
+        }
+    }
+    // GREASE ↔ major coherence. Chromium derives the GREASE token from the
+    // major (`ua-ch-brands.ts`), so a real Chrome profile always agrees with the
+    // derivation - a disagreement means the brand list was synthesized, or
+    // re-stamped by something that did not know the rule (older versions of
+    // this crawler did exactly that, which is issue #131: a 134-era GREASE on a
+    // 147 UA, refused by Naver with a challenge-free 418). Measured cost: 0 of
+    // 224 upstream-pool profiles with brands fail this, and 5 of 197 bundled
+    // non-Apify rows do - i.e. it rejects only fabricated lists, so the
+    // re-roll budget is unaffected.
+    const greaseIncoherence = describeGreaseIncoherence(brands);
+    if (greaseIncoherence) {
+        return greaseIncoherence;
+    }
+    // UA-CH full-version list must carry a REAL build number for the real
+    // brands. UA Reduction (Chrome 107+) freezes MAJOR.0.0.0 in the User-Agent
+    // STRING only; `sec-ch-ua-full-version-list` keeps the build
+    // ("147.0.7727.15"), so a profile whose list says "147.0.0.0" is unusable on
+    // any origin that requests high-entropy hints - measured on Naver: reduced
+    // shape 418, real build 200 (issue #131). Real pool profiles never do this
+    // (0 of 208 Chrome-cohort draws), so this only catches fabricated lists.
+    const reducedFullVersion = fullVersionList.find(b => b?.brand && !isGreaseBrand(b.brand) && /^\d+\.0\.0\.0$/.test(b.version ?? ''));
+    if (reducedFullVersion) {
+        return `userAgentData.fullVersionList carries the UA-reduced shape "${reducedFullVersion.brand}";v="${reducedFullVersion.version}"`
+            + ` (UA-CH must report the real build, e.g. 147.0.7727.15)`;
+    }
+    // Prefer profiles whose brands include "Google Chrome" - pool also
+    // returns Chromium-only profiles (no Google Chrome entry) which a
+    // CreepJS / FingerprintJS check via getHighEntropyValues against the
+    // canonical Chrome brand list would flag as "Chromium-based but not
+    // Chrome". Real Chrome's brand list always contains "Google Chrome".
+    const hasGoogleChrome = brands.some(b => b?.brand === 'Google Chrome');
+    if (brands.length > 0 && !hasGoogleChrome) {
+        return `userAgentData.brands lacks "Google Chrome" entry (Chromium-branded profile)`;
+    }
+    // ─── GPU renderer must be the detailed-ANGLE form, not SwiftShader ──
+    // ~29% of upstream Mac and ~51% of upstream Linux profiles carry the
+    // SwiftShader software-renderer signature:
+    //   "ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device (Subzero) …))"
+    // No real consumer machine running real Chrome reports this - SwiftShader
+    // is Chrome's last-resort software fallback used only when no GPU is
+    // available, e.g. inside Docker containers with no /dev/dri or on headless
+    // test runners. Shipping a SwiftShader renderer with ANY desktop UA is an
+    // instant "this is a sandboxed/datacenter browser" signal that Akamai /
+    // CreepJS / DataDome read straight off UNMASKED_RENDERER_WEBGL - and the
+    // C++ WebGL emulation faithfully spoofs *to* it, so forceEmulateWebgl does
+    // not save us. Reject on EVERY platform: the previous Mac-only gate let
+    // half of the Linux pool ship a software renderer (see the Akamai/Lowes
+    // intermittent-block investigation).
+    if (/SwiftShader|llvmpipe|Mesa Offscreen/i.test(gpuRenderer)) {
+        return `videoCard.renderer is SwiftShader/software (datacenter tell on any OS)`;
+    }
+    return null;
+}
+//# sourceMappingURL=profile-quality.js.map

package/dist/fingerprinting/profile-quality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-quality.js","sourceRoot":"","sources":["../../src/fingerprinting/profile-quality.ts"],"names":[],"mappings":"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"}

package/dist/fingerprinting/profile-selector.d.ts

@@ -0,0 +1,102 @@
+import { type NavigatorPlatform, type OsHint } from '../session-profile.js';
+/**
+ * FingerprintProfileSelector - the single home for "pick a clean fingerprint
+ * profile for the expected OS".
+ *
+ * Both launch paths consume it:
+ *   - browser-plugin._prepareNativeFingerprintConfig (native pre-launch, before
+ *     the C++ fingerprint config is written)
+ *   - browser-controller._maybeOverrideFingerprint (post-launch, system-Chrome
+ *     fallback where the pre-launch C++ config write was skipped)
+ *
+ * Selection happens exactly once per launch: the caller stamps the returned
+ * {@link SelectedProfile} onto the launch context under
+ * {@link PROFILE_SELECTION_KEY}, and the post-launch path reuses it instead of
+ * re-drawing. Without the marker, the controller's deterministic seeded
+ * re-draw used to resurrect the exact contaminated profile the plugin's
+ * re-roll loop had just escaped.
+ */
+/** Structural shape of `BrowserFingerprintWithHeaders` - kept loose on purpose. */
+export interface FingerprintLike {
+    headers?: Record<string, string>;
+    fingerprint?: Record<string, unknown>;
+}
+/**
+ * The narrow seam the selector draws profiles through. Production adapter:
+ * {@link defaultProfilePoolPort} (wraps `generateNonApifyFingerprint` and
+ * `FingerprintGenerator`). Tests script contaminated→clean sequences.
+ */
+export interface ProfilePoolPort {
+    /** One draw from the non-Apify real-device pool. Deterministic per seed. */
+    drawNonApify(opts: {
+        platform: NavigatorPlatform | undefined;
+        os: OsHint;
+        proxySeedKey: string | null;
+    }): Promise<FingerprintLike>;
+    /** A re-roll generator over the Apify synthetic pool, honouring genOpts constraints. */
+    createApifyReroller(genOpts: Record<string, unknown>): {
+        getFingerprint: () => unknown | Promise<unknown>;
+    };
+}
+export declare const defaultProfilePoolPort: ProfilePoolPort;
+export interface ProfileSelectionInput {
+    /** The fingerprint Crawlee already generated (`launchContext.fingerprint`), if any. */
+    currentFingerprint?: FingerprintLike;
+    /** `launchOptions.fingerprintOptions` - consulted for `useNonApifyFingerprints`, `platform`, `seedKey`. */
+    fingerprintOptions?: Record<string, unknown>;
+    /** `launchOptions.fingerprintGeneratorOptions` - consulted for `operatingSystems` + re-roll constraints. */
+    fingerprintGeneratorOptions?: {
+        operatingSystems?: string[];
+    } & Record<string, unknown>;
+    proxyUrl?: string | null;
+    /**
+     * A caller-threaded fingerprint generator (preserves caller-side generator
+     * options); preferred over `port.createApifyReroller` when present.
+     */
+    externalGenerator?: {
+        getFingerprint: () => unknown | Promise<unknown>;
+    } | null;
+    /**
+     * Host platform for the final OS-hint fallback. Threaded through to
+     * `resolveOsHint` so selection is deterministic in tests instead of
+     * depending on the runner's `process.platform`. Defaults to
+     * `process.platform` inside `resolveOsHint` when omitted.
+     */
+    hostPlatform?: NodeJS.Platform;
+}
+export interface SelectedProfile {
+    fingerprint: FingerprintLike | undefined;
+    seedKey: string | null;
+    expectedOs: OsHint | null;
+    expectedPlatform: NavigatorPlatform | null;
+    /** Number of pool re-draws performed to escape contamination. */
+    rerolls: number;
+    /** Non-null = still contaminated after the attempt cap; the last draw is shipped anyway. */
+    rejection: string | null;
+    /** True when `fingerprint` differs from `currentFingerprint` - caller must write it back. */
+    replaced: boolean;
+    /** True when the non-Apify real-device pool was used. */
+    usedNonApifyPool: boolean;
+}
+/** Key under which callers stamp the selection result onto the launch context. */
+export declare const PROFILE_SELECTION_KEY = "profileSelection";
+/**
+ * Pick a clean fingerprint profile for the expected OS.
+ *
+ * Owns the whole selection protocol: seed-key resolution, OS-pin validation,
+ * os-hint expectation, pool choice (Apify synthetic vs non-Apify real-device),
+ * and the contamination re-roll loop gated by `rejectContaminatedProfile`.
+ *
+ * The pool-contamination background: the upstream fingerprint-generator
+ * dataset contains a recurring fraction of profiles from Lark/Feishu
+ * (ByteDance) modified Chrome installs - see `profile-quality.ts` for the
+ * telltales. A contaminated profile flows verbatim into FingerprintConfig and
+ * the C++ source-tree overrides dutifully spoof to it, so every
+ * CreepJS/DataDome/Naver run sees a bot. We re-roll until clean, capped.
+ *
+ * When `operatingSystems[0]` and the deprecated `fingerprintOptions.platform`
+ * contradict each other, `operatingSystems` wins and a warning is logged (see
+ * `describeOsConflict`) - the conflict is no longer fatal (issue #80).
+ */
+export declare function selectFingerprintProfile(input: ProfileSelectionInput, port?: ProfilePoolPort): Promise<SelectedProfile>;
+//# sourceMappingURL=profile-selector.d.ts.map

package/dist/fingerprinting/profile-selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-selector.d.ts","sourceRoot":"","sources":["../../src/fingerprinting/profile-selector.ts"],"names":[],"mappings":"AAMA,OAAO,EAIH,KAAK,iBAAiB,EACtB,KAAK,MAAM,EACd,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;;;;;;GAgBG;AAEH,mFAAmF;AACnF,MAAM,WAAW,eAAe;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC5B,4EAA4E;IAC5E,YAAY,CAAC,IAAI,EAAE;QACf,QAAQ,EAAE,iBAAiB,GAAG,SAAS,CAAC;QACxC,EAAE,EAAE,MAAM,CAAC;QACX,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;KAC/B,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC7B,wFAAwF;IACxF,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;QACnD,cAAc,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;KACpD,CAAC;CACL;AAED,eAAO,MAAM,sBAAsB,EAAE,eAGpC,CAAC;AAEF,MAAM,WAAW,qBAAqB;IAClC,uFAAuF;IACvF,kBAAkB,CAAC,EAAE,eAAe,CAAC;IACrC,2GAA2G;IAC3G,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,4GAA4G;IAC5G,2BAA2B,CAAC,EAAE;QAAE,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxF,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;OAGG;IACH,iBAAiB,CAAC,EAAE;QAAE,cAAc,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;IAChF;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC5B,WAAW,EAAE,eAAe,GAAG,SAAS,CAAC;IACzC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,gBAAgB,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC3C,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,4FAA4F;IAC5F,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,6FAA6F;IAC7F,QAAQ,EAAE,OAAO,CAAC;IAClB,yDAAyD;IACzD,gBAAgB,EAAE,OAAO,CAAC;CAC7B;AAED,kFAAkF;AAClF,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AAQxD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,wBAAwB,CAC1C,KAAK,EAAE,qBAAqB,EAC5B,IAAI,GAAE,eAAwC,GAC/C,OAAO,CAAC,eAAe,CAAC,CAuI1B"}