jumpy-lion 1.0.0-beta.5 → 1.0.0-beta.7

package/dist/launch-stealth-browser.js

@@ -0,0 +1,133 @@
+/**
+ * `launchStealthBrowser()` - launch the anti-detect browser with the same stealth
+ * setup the crawler uses internally, without going through the crawler.
+ *
+ * WHY THIS EXISTS. Everything needed to launch a properly-spoofed session was
+ * already in the package and none of it was reachable from outside it. The
+ * `exports` map allows only `.` and `./package.json`, so a consumer cannot deep
+ * import `browser-process/*`, and `index.ts` exported the crawler, the router,
+ * `CdpPage` and the session-bundle helpers - no launcher. A consumer who wanted a
+ * browser rather than a crawl had to re-implement the composition, and the parts
+ * are not obvious: miss one and the launch still succeeds while advertising a
+ * contradiction.
+ *
+ * That gap had a measurable cost. The Google-only integrity header module shipped
+ * with no reachable caller, so `sec-ch-ua-full-version` could not be aligned with
+ * the digest's build from outside the package at all.
+ *
+ * WHAT THE ORDER BUYS YOU. These steps are sequenced, not a bag of options:
+ *
+ *   1. `prepareForLaunch` picks an OS-matching, uncontaminated profile and
+ *      generates the C++ `FingerprintConfigJson` from it. Selection must happen
+ *      before the config is written - once the browser starts with a wrong-OS
+ *      profile baked in, nothing afterwards can undo it.
+ *   2. The same call aligns UA and UA-CH with the real binary version, so the
+ *      profile's own Chrome vintage never contradicts the binary.
+ *   3. `launchBrowserWithNewProfile` applies the integrity headers - which also
+ *      re-aligns the advertised full version onto the seed's build - then writes
+ *      the config and composes the command line.
+ *
+ * Per ADR 0004 the identity a session claims is the reference, never the host. On
+ * Linux with a macOS profile every surface has to present the macOS shape, so the
+ * profile's OS is what drives the config, and `fingerprintGeneratorOptions.
+ * operatingSystems` is how you choose it.
+ */
+import { log } from 'crawlee';
+import { isAntiDetectBrowserSync } from './browser-process/anti-detect-browser.js';
+import { launchBrowserWithNewProfile } from './browser-process/browser.js';
+import { prepareForLaunch } from './browser-process/fingerprint-config.js';
+import { resolveAntiDetectBrowserPath, getAntiDetectBrowserPath } from './browser-process/get-chrome-executable.js';
+/**
+ * Launch a fully-spoofed browser and return the process plus the config it used.
+ *
+ * ```ts
+ * import { launchStealthBrowser } from 'jumpy-lion';
+ *
+ * const { browserProcess, fingerprintConfig } = await launchStealthBrowser({
+ *     debuggingPort: 9222,
+ *     sessionId: 'session-1',
+ *     fingerprintGeneratorOptions: { operatingSystems: ['macos'] },
+ * });
+ *
+ * const wsUrl = await browserProcess.wsEndpoint();
+ * // … drive it over CDP …
+ * await browserProcess.kill();
+ * ```
+ *
+ * On proxies: `proxyUrl` is passed to Chromium directly. Prefer SOCKS5 over an
+ * HTTP proxy that terminates TLS - a MITM proxy replaces Chromium's own TLS
+ * ClientHello with its runtime's, which changes the JA4 fingerprint and undoes
+ * work no JS or C++ override can reach.
+ */
+export async function launchStealthBrowser(options = {}) {
+    const executablePath = options.executablePath
+        // resolveAntiDetectBrowserPath throws a diagnostic naming the paths it
+        // checked, which is better than launching something unspoofed.
+        ?? resolveAntiDetectBrowserPath();
+    const usingNativeStealth = isAntiDetectBrowserSync(executablePath);
+    if (!usingNativeStealth) {
+        log.warning('[AntiDetect] launchStealthBrowser: the resolved binary is not the anti-detect build, '
+            + 'so every C++-level override is inactive and only the JS layer applies. '
+            + `Path: ${executablePath}`);
+    }
+    // The shape prepareForLaunch reads and writes. It stamps the generated config
+    // onto launchOptions, which is the same object passed to the launcher below,
+    // so the config reaches the browser without being threaded by hand.
+    const launchOptions = {
+        executablePath,
+        debuggingPort: options.debuggingPort,
+        anonymizedProxyUrl: options.proxyUrl,
+        windowWidth: options.windowWidth ?? 1920,
+        windowHeight: options.windowHeight ?? 1080,
+        userDataDir: options.userDataDir,
+        keepUserDataDir: options.keepUserDataDir,
+        useNativeStealth: usingNativeStealth,
+        enableStealthMode: true,
+        extraArgs: options.extraArgs,
+        fingerprintGeneratorOptions: options.fingerprintGeneratorOptions,
+        fingerprintOptions: {
+            // Real captured Chrome device profiles rather than generated ones.
+            // Defaulted ON: a generated profile is internally consistent but its
+            // combination of values need not correspond to any machine that
+            // exists, and the population of generated profiles is itself a
+            // distribution a detector can learn. Overridable, not forced.
+            useNonApifyFingerprints: options.useNonApifyFingerprints ?? true,
+            // The seed key IS the identity. resolveSeedKey falls back to the
+            // proxy URL when this is absent, so without it two launches on one
+            // proxy silently share a fingerprint.
+            ...(options.sessionId && { seedKey: options.sessionId }),
+            ...(options.locale && { locale: options.locale }),
+        },
+        // A caller-supplied config wins: prepareForLaunch leaves an already
+        // stamped config alone, which is what makes session replay exact.
+        ...(options.fingerprintConfig && { fingerprintConfig: options.fingerprintConfig }),
+    };
+    if (!options.fingerprintConfig) {
+        // launchOptions is passed BY REFERENCE, not spread. prepareForLaunch
+        // communicates by mutating it - it stamps the generated config onto
+        // `launchOptions.fingerprintConfig` and resizes the window to the claimed
+        // screen. Handing it a copy would leave both changes on an object nobody
+        // reads, and the launch would still succeed, using an unaligned config.
+        await prepareForLaunch({
+            proxyUrl: options.proxyUrl,
+            useNativeStealth: usingNativeStealth,
+            launchOptions: launchOptions,
+        });
+    }
+    const browserProcess = await launchBrowserWithNewProfile(executablePath, launchOptions);
+    return {
+        browserProcess,
+        fingerprintConfig: launchOptions.fingerprintConfig,
+        usingNativeStealth,
+    };
+}
+/**
+ * Where the anti-detect binary was found, or `null` if it is not installed.
+ *
+ * Exported so a consumer can check for the native build before launching rather
+ * than discovering from a warning that it ran unspoofed.
+ */
+export function getStealthBrowserPath() {
+    return getAntiDetectBrowserPath();
+}
+//# sourceMappingURL=launch-stealth-browser.js.map

package/dist/launch-stealth-browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"launch-stealth-browser.js","sourceRoot":"","sources":["../src/launch-stealth-browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,SAAS,CAAC;AAE9B,OAAO,EAAE,uBAAuB,EAAE,MAAM,0CAA0C,CAAC;AAEnF,OAAO,EAAE,2BAA2B,EAAE,MAAM,8BAA8B,CAAC;AAC3E,OAAO,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAC3E,OAAO,EAAE,4BAA4B,EAAE,wBAAwB,EAAE,MAAM,4CAA4C,CAAC;AAyFpH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACtC,UAAuC,EAAE;IAEzC,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc;QACzC,uEAAuE;QACvE,+DAA+D;WAC5D,4BAA4B,EAAE,CAAC;IAEtC,MAAM,kBAAkB,GAAG,uBAAuB,CAAC,cAAc,CAAC,CAAC;IACnE,IAAI,CAAC,kBAAkB,EAAE,CAAC;QACtB,GAAG,CAAC,OAAO,CACP,uFAAuF;cACrF,yEAAyE;cACzE,SAAS,cAAc,EAAE,CAC9B,CAAC;IACN,CAAC;IAED,8EAA8E;IAC9E,6EAA6E;IAC7E,oEAAoE;IACpE,MAAM,aAAa,GAA4B;QAC3C,cAAc;QACd,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,kBAAkB,EAAE,OAAO,CAAC,QAAQ;QACpC,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI;QACxC,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,IAAI;QAC1C,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,eAAe,EAAE,OAAO,CAAC,eAAe;QACxC,gBAAgB,EAAE,kBAAkB;QACpC,iBAAiB,EAAE,IAAI;QACvB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,2BAA2B,EAAE,OAAO,CAAC,2BAA2B;QAChE,kBAAkB,EAAE;YAChB,mEAAmE;YACnE,qEAAqE;YACrE,gEAAgE;YAChE,+DAA+D;YAC/D,8DAA8D;YAC9D,uBAAuB,EAAE,OAAO,CAAC,uBAAuB,IAAI,IAAI;YAChE,iEAAiE;YACjE,mEAAmE;YACnE,sCAAsC;YACtC,GAAG,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC;YACxD,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;SACpD;QACD,oEAAoE;QACpE,kEAAkE;QAClE,GAAG,CAAC,OAAO,CAAC,iBAAiB,IAAI,EAAE,iBAAiB,EAAE,OAAO,CAAC,iBAAiB,EAAE,CAAC;KACrF,CAAC;IAEF,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,CAAC;QAC7B,qEAAqE;QACrE,oEAAoE;QACpE,0EAA0E;QAC1E,yEAAyE;QACzE,wEAAwE;QACxE,MAAM,gBAAgB,CAAC;YACnB,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,gBAAgB,EAAE,kBAAkB;YACpC,aAAa,EAAE,aAAsB;SAC/B,CAAC,CAAC;IAChB,CAAC;IAED,MAAM,cAAc,GAAG,MAAM,2BAA2B,CACpD,cAAc,EACd,aAAsB,CACzB,CAAC;IAEF,OAAO;QACH,cAAc;QACd,iBAAiB,EAAE,aAAa,CAAC,iBAAsD;QACvF,kBAAkB;KACrB,CAAC;AACN,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB;IACjC,OAAO,wBAAwB,EAAE,CAAC;AACtC,CAAC"}