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

package/dist/fingerprinting/locale-resolver.d.ts

@@ -15,6 +15,12 @@ export interface ResolveLocaleInput {
     timezone?: string;
     /** Explicit Accept-Language header value (e.g. 'ko-KR,ko;q=0.9'). Overrides derived list. */
     languages?: string;
+    /**
+     * The caller's requested fingerprint-generator locales (e.g. ['it-IT', 'it']).
+     * This is explicit caller intent, unlike the generator's host-biased Accept-Language
+     * output, so the first valid tag ranks above the proxy country lookup.
+     */
+    generatorLocales?: string[];
     /** ISO 3166-1 alpha-2 country code from proxy IP lookup (e.g. 'KR'). */
     proxyCountry?: string;
     /** Fingerprint-generator language, used as a fallback when nothing else is available. */
@@ -32,6 +38,21 @@ export interface ResolvedLocale {
 }
 /** Resolve every locale surface from whatever signals are available. */
 export declare function resolveLocale(input?: ResolveLocaleInput): ResolvedLocale;
+/**
+ * Turn an Accept-Language style list ('it-IT,it;q=0.9,en;q=0.8') into the q-less
+ * comma list that Chromium's --lang switch and the config's navigator.languages expect.
+ */
+export declare function toLangList(languages: string | undefined): string;
+/**
+ * The value for Chromium's --lang switch, which sets ICU's default locale and so drives
+ * Intl.*().resolvedOptions().locale. Reads the one resolved locale; when none exists it
+ * derives the list from the fingerprint config's navigator languages (so --lang can never
+ * disagree with navigator.languages) and only then uses the historical en-US default.
+ */
+export declare function resolveLangSwitch(resolvedLocale: Pick<ResolvedLocale, 'locale' | 'languages'> | undefined, configNavigator?: {
+    language?: string;
+    languages?: string;
+}): string;
 /**
  * Look up the proxy IP's country (ISO 3166-1 alpha-2) via ipinfo.io.
  * Best-effort: returns undefined on any failure so callers can fall through

package/dist/fingerprinting/locale-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"locale-resolver.d.ts","sourceRoot":"","sources":["../../src/fingerprinting/locale-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,kBAAkB;IAC/B,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6FAA6F;IAC7F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yFAAyF;IACzF,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,cAAc;IAC3B,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;CACjB;AA0DD,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,KAAK,GAAE,kBAAuB,GAAG,cAAc,CAO5E;AA6ED;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAetF"}
+{"version":3,"file":"locale-resolver.d.ts","sourceRoot":"","sources":["../../src/fingerprinting/locale-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,kBAAkB;IAC/B,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6FAA6F;IAC7F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yFAAyF;IACzF,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,cAAc;IAC3B,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;CACjB;AA0DD,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,KAAK,GAAE,kBAAuB,GAAG,cAAc,CAO5E;AAoED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAMhE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC7B,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,WAAW,CAAC,GAAG,SAAS,EACxE,eAAe,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5D,MAAM,CAQR;AAmBD;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAetF"}

package/dist/fingerprinting/locale-resolver.js

@@ -70,9 +70,15 @@ export function resolveLocale(input = {}) {
     const posix = toPosix(locale);
     return { locale, languages, timezone, posix };
 }
-function pickLocale({ locale, proxyCountry, fingerprintLanguage }) {
+function pickLocale({ locale, generatorLocales, proxyCountry, fingerprintLanguage }) {
     if (locale && isValidBcp47(locale))
         return locale;
+    // A lookup over the network can fail (a residential proxy often times out against
+    // ipinfo.io), and a failed lookup used to silently demote an Italian run to en-US while
+    // the fingerprint config still claimed it-IT. The caller's own locales never fail.
+    const fromGenerator = generatorLocales?.find(isValidBcp47);
+    if (fromGenerator)
+        return fromGenerator;
     if (proxyCountry) {
         const fromCountry = COUNTRY_TO_LOCALE[proxyCountry.toUpperCase()];
         if (fromCountry)
@@ -96,19 +102,22 @@ function pickLocale({ locale, proxyCountry, fingerprintLanguage }) {
     }
     return DEFAULT_LOCALE;
 }
+// Timezone priority: explicit tz > proxy country (the exit IP's own zone) > locale region > UTC.
+// The proxy outranks the locale region because a page can compare the timezone with the IP geo,
+// while a locale such as en-US legitimately appears on a German exit.
 function pickTimezone({ timezone, proxyCountry }, region) {
     if (timezone)
         return timezone;
-    if (region) {
-        const fromRegion = REGION_TO_TIMEZONE[region];
-        if (fromRegion)
-            return fromRegion;
-    }
     if (proxyCountry) {
         const fromProxy = REGION_TO_TIMEZONE[proxyCountry.toUpperCase()];
         if (fromProxy)
             return fromProxy;
     }
+    if (region) {
+        const fromRegion = REGION_TO_TIMEZONE[region];
+        if (fromRegion)
+            return fromRegion;
+    }
     return DEFAULT_TIMEZONE;
 }
 /**
@@ -131,6 +140,34 @@ function buildLanguages(locale) {
     }
     return parts.join(',');
 }
+/**
+ * Turn an Accept-Language style list ('it-IT,it;q=0.9,en;q=0.8') into the q-less
+ * comma list that Chromium's --lang switch and the config's navigator.languages expect.
+ */
+export function toLangList(languages) {
+    return (languages ?? '')
+        .split(',')
+        .map(l => l.split(';')[0].trim())
+        .filter(Boolean)
+        .join(',');
+}
+/**
+ * The value for Chromium's --lang switch, which sets ICU's default locale and so drives
+ * Intl.*().resolvedOptions().locale. Reads the one resolved locale; when none exists it
+ * derives the list from the fingerprint config's navigator languages (so --lang can never
+ * disagree with navigator.languages) and only then uses the historical en-US default.
+ */
+export function resolveLangSwitch(resolvedLocale, configNavigator) {
+    if (resolvedLocale?.locale) {
+        return toLangList(resolvedLocale.languages) || resolvedLocale.locale;
+    }
+    const fromConfig = toLangList(configNavigator?.languages);
+    if (fromConfig)
+        return fromConfig;
+    if (configNavigator?.language)
+        return configNavigator.language;
+    return `${DEFAULT_LOCALE},en`;
+}
 /** Extract the region subtag (uppercase) from a BCP-47 tag. 'ko-KR' → 'KR'. */
 function extractRegion(locale) {
     const [, region] = locale.split('-');

package/dist/fingerprinting/locale-resolver.js.map

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

package/dist/index.d.ts

@@ -10,4 +10,9 @@ export { restoreSession, installSessionInjectionHook, buildStorageInjectionScrip
 export { assertValidBundle, SCHEMA_VERSION } from "./session/types.js";
 export type { SessionBundle, SessionBundleBrowserProfile, SessionBundleFingerprintInput, SessionBundleProxyMeta, SessionBundleUserDataDir, SerializedCookie, StorageMap, LaunchSnapshot, } from "./session/types.js";
 export type { SaveSessionOptions } from "./session/save.js";
+export { launchStealthBrowser, getStealthBrowserPath } from "./launch-stealth-browser.js";
+export type { LaunchStealthBrowserOptions, StealthBrowserLaunch } from "./launch-stealth-browser.js";
+export type { FingerprintConfigJson } from "./browser-process/anti-detect-config.js";
+export { applyIntegrityToConfig, buildIntegrityHeaderArgs, VERIFIED_INTEGRITY_PROFILES, INTEGRITY_CLAIMED_VERSION, CHROME_API_KEYS, } from "./browser-process/integrity-headers.js";
+export type { IntegrityProfile, ClaimedIntegrityPlatform } from "./browser-process/integrity-headers.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,cAAc,CAAC;AACtC,OAAO,OAAO,MAAM,WAAW,CAAC;AAEhC,eAAe,UAAU,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EAAE,SAAS,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC1H,YAAY,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAClE,OAAO,EAAE,OAAO,EAAE,CAAC;AAKnB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,2BAA2B,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AACpH,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACvE,YAAY,EACR,aAAa,EACb,2BAA2B,EAC3B,6BAA6B,EAC7B,sBAAsB,EACtB,wBAAwB,EACxB,gBAAgB,EAChB,UAAU,EACV,cAAc,GACjB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,cAAc,CAAC;AACtC,OAAO,OAAO,MAAM,WAAW,CAAC;AAEhC,eAAe,UAAU,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EAAE,SAAS,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC1H,YAAY,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAClE,OAAO,EAAE,OAAO,EAAE,CAAC;AAKnB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,2BAA2B,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AACpH,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACvE,YAAY,EACR,aAAa,EACb,2BAA2B,EAC3B,6BAA6B,EAC7B,sBAAsB,EACtB,wBAAwB,EACxB,gBAAgB,EAChB,UAAU,EACV,cAAc,GACjB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAO5D,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAC1F,YAAY,EAAE,2BAA2B,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACrG,YAAY,EAAE,qBAAqB,EAAE,MAAM,yCAAyC,CAAC;AAWrF,OAAO,EACH,sBAAsB,EACtB,wBAAwB,EACxB,2BAA2B,EAC3B,yBAAyB,EACzB,eAAe,GAClB,MAAM,wCAAwC,CAAC;AAChD,YAAY,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAC"}

package/dist/index.js

@@ -9,4 +9,20 @@ export { CdpPage };
 export { saveSession } from "./session/save.js";
 export { restoreSession, installSessionInjectionHook, buildStorageInjectionScript } from "./session/inject-hook.js";
 export { assertValidBundle, SCHEMA_VERSION } from "./session/types.js";
+// Standalone launcher - the crawler's own stealth setup, without the crawler.
+// Composes profile selection, C++ fingerprint config generation, binary-version
+// alignment and the Google integrity headers in the order that matters, then
+// launches the anti-detect binary. See launch-stealth-browser.ts for why the
+// order is load-bearing.
+export { launchStealthBrowser, getStealthBrowserPath } from "./launch-stealth-browser.js";
+// Google-only request-header integrity. Exported so a consumer can see which
+// Chrome builds we hold a VERIFIED seed for, and align the claimed version with
+// it. Previously this module had no reachable caller at all: it was neither
+// re-exported here nor deep-importable through the `exports` map, so the version
+// the digest is computed for could not be chosen from outside the package.
+//
+// Only verified seeds are usable. A missing header set leaves us
+// indistinguishable from every other Chromium build; a header carrying a wrong
+// digest is impossible-valued and therefore unique.
+export { applyIntegrityToConfig, buildIntegrityHeaderArgs, VERIFIED_INTEGRITY_PROFILES, INTEGRITY_CLAIMED_VERSION, CHROME_API_KEYS, } from "./browser-process/integrity-headers.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,cAAc,CAAC;AACtC,OAAO,OAAO,MAAM,WAAW,CAAC;AAEhC,eAAe,UAAU,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG/C,OAAO,EAAE,OAAO,EAAE,CAAC;AAEnB,6EAA6E;AAC7E,6EAA6E;AAC7E,yEAAyE;AACzE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,2BAA2B,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AACpH,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,cAAc,CAAC;AACtC,OAAO,OAAO,MAAM,WAAW,CAAC;AAEhC,eAAe,UAAU,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG/C,OAAO,EAAE,OAAO,EAAE,CAAC;AAEnB,6EAA6E;AAC7E,6EAA6E;AAC7E,yEAAyE;AACzE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,2BAA2B,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AACpH,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAavE,8EAA8E;AAC9E,gFAAgF;AAChF,6EAA6E;AAC7E,6EAA6E;AAC7E,yBAAyB;AACzB,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAI1F,6EAA6E;AAC7E,gFAAgF;AAChF,4EAA4E;AAC5E,iFAAiF;AACjF,2EAA2E;AAC3E,EAAE;AACF,iEAAiE;AACjE,+EAA+E;AAC/E,oDAAoD;AACpD,OAAO,EACH,sBAAsB,EACtB,wBAAwB,EACxB,2BAA2B,EAC3B,yBAAyB,EACzB,eAAe,GAClB,MAAM,wCAAwC,CAAC"}

package/dist/launch-stealth-browser.d.ts

@@ -0,0 +1,143 @@
+/**
+ * `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 type { FingerprintConfigJson } from './browser-process/anti-detect-config.js';
+import type { BrowserProcess } from './browser-process/process.js';
+export interface LaunchStealthBrowserOptions {
+    /**
+     * Path to the browser binary. Defaults to the installed anti-detect build.
+     *
+     * Point this at stock Chrome only deliberately: the C++ overrides are what
+     * most of the stealth surface is, and a stock binary silently ignores the
+     * config file, leaving the host's own fingerprint on every surface the JS
+     * layer does not cover.
+     */
+    executablePath?: string;
+    /**
+     * Remote-debugging port. Omit for no CDP endpoint at all.
+     *
+     * A FIXED port is safe; `0` is not. Chromium sets `navigator.webdriver` when
+     * it is started with `--remote-debugging-port=0` (as it does for
+     * `--enable-automation`, `--headless` and `--remote-debugging-pipe`), so
+     * asking for an ephemeral port advertises automation on a surface every
+     * detector reads. Pass a real port number or nothing.
+     */
+    debuggingPort?: number;
+    /** Upstream proxy URL. Prefer SOCKS5 - see the note on TLS below. */
+    proxyUrl?: string;
+    /**
+     * Stable identity key. Two launches with the same value get the same
+     * fingerprint, because seeds are derived from it rather than from
+     * `Date.now()` / `Math.random()`.
+     *
+     * Omitting it falls back to seeding from the proxy URL, so distinct sessions
+     * sharing one proxy would claim the same machine. Pass it whenever you want
+     * one identity per session.
+     */
+    sessionId?: string;
+    /**
+     * Use real captured Chrome device profiles instead of generated ones.
+     * Defaults to `true`.
+     */
+    useNonApifyFingerprints?: boolean;
+    /**
+     * Which OS the session should CLAIM, e.g. `{ operatingSystems: ['macos'] }`.
+     * This is the claimed identity, not the host's.
+     */
+    fingerprintGeneratorOptions?: {
+        operatingSystems?: string[];
+    } & Record<string, unknown>;
+    /** BCP-47 locale driving navigator, Intl, Accept-Language and timezone together. */
+    locale?: string;
+    /** Window size. Defaults to a desktop-typical 1920x1080. */
+    windowWidth?: number;
+    windowHeight?: number;
+    /** Reuse an existing profile directory instead of a fresh temp one. */
+    userDataDir?: string;
+    /** Keep the profile directory on exit. Defaults to true only when you supplied one. */
+    keepUserDataDir?: boolean;
+    /**
+     * A captured `FingerprintConfigJson` to use verbatim, skipping generation.
+     * This is how session continuity works: feed back the config a previous
+     * launch used and the second browser is byte-for-byte the first one.
+     */
+    fingerprintConfig?: FingerprintConfigJson;
+    /** Extra command-line switches, appended last. */
+    extraArgs?: string[];
+}
+export interface StealthBrowserLaunch {
+    /** The live process. `await wsEndpoint()` for the CDP URL, `kill()` to stop it. */
+    browserProcess: BrowserProcess;
+    /**
+     * The config this launch actually used - after profile selection, binary
+     * alignment and integrity-version alignment.
+     *
+     * Keep it to reproduce the session later via `fingerprintConfig`, and read it
+     * to know what the session is claiming rather than inferring it.
+     */
+    fingerprintConfig?: FingerprintConfigJson;
+    /** Whether the resolved binary is the anti-detect build (native C++ stealth). */
+    usingNativeStealth: boolean;
+}
+/**
+ * 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 declare function launchStealthBrowser(options?: LaunchStealthBrowserOptions): Promise<StealthBrowserLaunch>;
+/**
+ * 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 declare function getStealthBrowserPath(): string | null;
+//# sourceMappingURL=launch-stealth-browser.d.ts.map

package/dist/launch-stealth-browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"launch-stealth-browser.d.ts","sourceRoot":"","sources":["../src/launch-stealth-browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAKH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yCAAyC,CAAC;AAIrF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAEnE,MAAM,WAAW,2BAA2B;IACxC;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAElC;;;OAGG;IACH,2BAA2B,CAAC,EAAE;QAAE,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAExF,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uFAAuF;IACvF,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,qBAAqB,CAAC;IAE1C,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACjC,mFAAmF;IACnF,cAAc,EAAE,cAAc,CAAC;IAC/B;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,qBAAqB,CAAC;IAC1C,iFAAiF;IACjF,kBAAkB,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,oBAAoB,CACtC,OAAO,GAAE,2BAAgC,GAC1C,OAAO,CAAC,oBAAoB,CAAC,CAuE/B;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,GAAG,IAAI,CAErD"}

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"}