leapfrog-mcp 0.6.2 → 0.6.3

package/dist/stealth.d.ts

@@ -0,0 +1,195 @@
+import type { Page } from "playwright-core";
+import type { Fingerprint } from "./humanize-fingerprint.js";
+export type StealthModeType = 'off' | 'passive' | 'active';
+export declare class StealthMode {
+    /**
+     * Strip sourceURL comments from init script text.
+     * Playwright injects `//# sourceURL=__playwright_evaluation_script__` into
+     * eval'd scripts which bot detectors look for. This strips any sourceURL
+     * or sourceMappingURL directives from our init scripts before injection.
+     */
+    private sanitizeSourceURL;
+    /**
+     * Chromium launch args that reduce automation fingerprinting.
+     *
+     * In passive mode, only automation-hiding args are included.
+     * In active mode, GPU-related args for WebGL faking are also added.
+     */
+    getLaunchArgs(): string[];
+    /**
+     * Realistic Chrome user agent string for macOS.
+     */
+    getDefaultUserAgent(): string;
+    /**
+     * Infer the correct navigator.platform value from a user-agent string.
+     * Prevents P2 #9: platform mismatch when custom UA says Windows but
+     * platform says MacIntel.
+     */
+    inferPlatformFromUA(ua: string): string;
+    /**
+     * Returns a random delay in ms (200-500) for dialog auto-dismiss.
+     * P1 #6: Instant dismiss (< 30ms) is a headless signal.
+     * Call this from dialog handlers in session-manager and tab-manager.
+     */
+    getDialogDelay(): number;
+    /**
+     * Derive the correct navigator.platform string from process.platform.
+     * Used as the fallback when no UA string is available to infer from.
+     */
+    getPlatformFromProcess(): string;
+    /**
+     * Extract the Chrome major version number from a UA string.
+     * Falls back to 136 (current default UA) if not found.
+     */
+    extractChromeMajorVersion(ua: string): number;
+    /**
+     * Generate a numeric seed from a string (simple djb2 hash).
+     * Used to seed per-session PRNG for canvas/audio noise determinism.
+     */
+    private hashSeed;
+    /**
+     * Category A: Passive init script — removes automation signals only.
+     * These patches make an automated browser look like a non-automated browser
+     * WITHOUT faking its identity. Safe against advanced fingerprinters like CreepJS
+     * because they don't introduce detectable inconsistencies ("lies").
+     *
+     * Patches included:
+     * - Playwright globals cleanup (__pwInitScripts, __playwright, etc.)
+     * - navigator.webdriver deletion (P0 #2)
+     * - ChromeDriver property removal
+     * - sourceURL stripping (#14)
+     */
+    private getPassiveInitScript;
+    /**
+     * Category B: Active init script — identity faking patches.
+     * These create a fake browser identity (plugins, WebGL, platform, etc.).
+     * Advanced fingerprinters like CreepJS can detect these as "lies" because
+     * they create inconsistencies between reported and actual values.
+     *
+     * Only applied when LEAP_STEALTH=true (active mode, the default).
+     *
+     * Patches included:
+     * - Session-seeded PRNG (mulberry32)
+     * - Client Hints brands override (P0 #1)
+     * - chrome.app/runtime/loadTimes/csi emulation (#10)
+     * - Permissions.prototype.query override (P2 #16)
+     * - navigator.plugins spoofing (5 fake plugins)
+     * - MimeTypeArray spoof (P2 #8)
+     * - navigator.languages override
+     * - navigator.platform override (P2 #9)
+     * - hardwareConcurrency/deviceMemory spoofing
+     * - Notification.permission override
+     * - WebGL vendor/renderer override (P1 #4)
+     * - Connection RTT override (P1 #5)
+     * - outerHeight/outerWidth fake (P2 #7)
+     * - document.hasFocus() override (#13)
+     * - Media codecs spoofing (#12)
+     * - Canvas fingerprint noise (Phase 2.2)
+     * - AudioContext fingerprint noise (P3 #17)
+     * - WebRTC IP filtering (P3 #18)
+     * - Font enumeration spoofing (P3 #19)
+     * - iframe contentWindow protection (#11)
+     * - Worker/SharedWorker UA leak prevention
+     */
+    private getActiveInitScript;
+    /**
+     * JavaScript to inject via page.addInitScript() that patches
+     * common bot-detection vectors in the page's execution context.
+     *
+     * This script runs BEFORE page JavaScript on every navigation,
+     * including in iframes (Playwright propagates addInitScript to all frames).
+     *
+     * In passive mode, only Category A (automation signal removal) patches are applied.
+     * In active mode, both Category A and Category B (identity faking) patches are applied.
+     */
+    getInitScript(platform?: string, ua?: string, fingerprint?: Fingerprint, sessionSeed?: number, modeOverride?: StealthModeType): string;
+    /**
+     * Remove Playwright-specific global variables that bot detection scripts
+     * trivially check for. These are injected by Playwright's init script
+     * mechanism and are dead giveaways of automation.
+     */
+    getPlaywrightGlobalsCleanupScript(): string;
+    /**
+     * P1: Runtime.enable CDP detection bypass init script.
+     * Default ON — disable with LEAP_CDP_STEALTH=false.
+     *
+     * When Playwright sends Runtime.enable via CDP, bot detection scripts
+     * can observe Playwright/DevTools stack frames in Error.prepareStackTrace.
+     * This patch intercepts prepareStackTrace and filters out any frames
+     * originating from __playwright, pptr:, or devtools:// — making the
+     * stack trace indistinguishable from a real browser.
+     *
+     * This is separate from the #14 sourceURL stripping patch because it
+     * performs a deeper filter (also strips devtools:// frames) and is
+     * opt-in due to potential debugging interference.
+     *
+     * Defends against: Patchright/rebrowser CDP detection, DataDome Runtime.enable check
+     */
+    getCdpStealthScript(): string;
+    /**
+     * Whether CDP stealth mode is enabled.
+     * Default ON — disable with LEAP_CDP_STEALTH=false.
+     * The Error.prepareStackTrace filter hides Playwright/DevTools stack frames
+     * from bot detection scripts. Safe for production; only disable if you need
+     * raw stack traces for debugging.
+     */
+    isCdpStealthEnabled(): boolean;
+    /**
+     * Apply the stealth init script to a Playwright page.
+     * Call this immediately after page creation, before navigating.
+     *
+     * Respects the current stealth mode:
+     * - passive: applies only Category A patches (automation signal removal)
+     * - active:  applies Category A + Category B (identity faking)
+     *
+     * Also applies:
+     * - Playwright globals cleanup (__pwInitScripts, __playwright__binding__, __playwright)
+     * - CDP stealth script (default ON, disable via LEAP_CDP_STEALTH=false)
+     */
+    applyToPage(page: Page, userAgent?: string, fingerprint?: Fingerprint, modeOverride?: StealthModeType): Promise<void>;
+    /**
+     * Get the current stealth mode.
+     *   'active'  — full stealth (automation removal + identity faking). Default.
+     *   'passive' — remove automation signals only, no identity faking.
+     *   'off'     — stealth completely disabled.
+     */
+    getMode(): StealthModeType;
+    /**
+     * Whether the stealth mode is bandit-driven (LEAP_STEALTH=auto).
+     * When true, the EXP3 bandit selects the stealth mode per-domain
+     * per-navigation instead of using a fixed mode.
+     *
+     * When LEAP_STEALTH is unset or explicitly set to true/passive/false,
+     * the user's choice takes precedence and the bandit is advisory only
+     * (it still records outcomes for learning, but doesn't override the mode).
+     */
+    isBanditMode(): boolean;
+    /**
+     * Whether stealth mode is enabled (passive or active).
+     * Returns true unless LEAP_STEALTH=false/off is set.
+     * Backwards compatible — callers that only need to know "is stealth on at all?"
+     * can keep using this method.
+     */
+    isEnabled(): boolean;
+    /**
+     * Build Sec-CH-UA header value from a Chrome version and platform.
+     * Phase 2.4: These HTTP headers are sent BEFORE JS runs, so they must
+     * be set via extraHTTPHeaders to stay in sync with the JS-side override.
+     */
+    buildSecChUaHeaders(chromeVersion: number, platform: string): Record<string, string>;
+    /**
+     * BrowserContext options to merge into context creation.
+     * Returns stealth-appropriate defaults (user agent, locale, timezone, headers).
+     *
+     * In passive mode, returns minimal options (locale/timezone for consistency)
+     * but does NOT set a faked userAgent or Sec-CH-UA headers.
+     *
+     * In active mode, returns the full set including faked UA and headers.
+     *
+     * BUG-005 / P0 #3 FIX: When a custom user agent is provided, we still return
+     * locale/timezone/extraHTTPHeaders — only the userAgent field is omitted.
+     */
+    getContextOptions(customUserAgent?: string, fingerprint?: Fingerprint): Record<string, unknown>;
+}
+export declare const stealth: StealthMode;
+export default stealth;