real-browser-plus 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 real-browser-plus contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# real-browser-plus
+
+A modernized, more capable successor to `puppeteer-real-browser` (which stopped receiving updates in Feb 2026). Built on current Puppeteer + `puppeteer-extra-plugin-stealth`, with a richer evasion and humanization toolkit.
+
+## Features
+
+- **Self-consistent fingerprint randomization** — UA, platform, WebGL vendor/renderer, hardware concurrency, timezone, locale, and screen/viewport resolution are generated together so nothing mismatches (a common tell for detection scripts).
+- **Client Hints spoofing** — `Sec-CH-UA` / `Sec-CH-UA-Platform` / `Sec-CH-UA-Full-Version-List` headers and `navigator.userAgentData` are overridden at the CDP network layer to match the spoofed Chrome version, not just the JS-visible User-Agent string.
+- **Screen & viewport consistency** — `screen.width/height`, `availWidth/availHeight`, `window.outerWidth/outerHeight`, and `devicePixelRatio` are all patched together so window geometry checks can't catch a mismatch.
+- **Canvas, AudioContext, WebGL & WebGL2 noise/spoof** — defeats canvas/audio hashing and GPU vendor fingerprinting on both WebGL contexts without breaking rendering.
+- **Deep stealth evasions** — `navigator.webdriver`, CDP artifacts, `window.chrome`, plugins array, permissions.query, iframe.contentWindow leaks, Battery API, Network Information API, and `Function.prototype.toString` proxy detection.
+- **Ghost cursor** — bezier-curve mouse movement with easing, variable speed, and randomized landing points inside target elements.
+- **Human typing** — variable per-key delay, occasional realistic typos with correction, mid-sentence pauses.
+- **Human scrolling** — incremental wheel events with reading pauses instead of one jump.
+- **Automatic Cloudflare Turnstile handling** — detects the challenge iframe and clicks the checkbox like a real visitor, on load and on every navigation.
+- **WebRTC IP leak protection** — strips ICE servers so the real local/public IP can't be extracted through WebRTC.
+- **Session persistence** — save and restore cookies, localStorage, and sessionStorage across runs.
+- **Proxy support with rotation** — pass one proxy or an array to rotate across launches, with auth handled automatically.
+- **Retry helper** — exponential backoff with jitter for flaky network/page actions.
+- **Plugin system** — hook into browser/page lifecycle events.
+- **TypeScript-native**, ships both CJS and ESM builds.
+
+## Install
+
+```bash
+npm install real-browser-plus
+```
+
+On Linux, install `xvfb` if you plan to run with `headless: false` on a machine without a display:
+
+```bash
+sudo apt-get install xvfb
+```
+
+## Quick start
+
+```ts
+import { connect } from "real-browser-plus";
+
+const { browser, page, humanClick, humanType } = await connect({
+  headless: false,
+  turnstile: true,
+});
+
+await page.goto("https://example.com/login");
+await humanType(page, "#username", "myUsername");
+await humanType(page, "#password", "myPassword123");
+await humanClick(page, "#submit");
+
+await browser.close();
+```
+
+## Using a proxy (with rotation)
+
+```ts
+const { page } = await connect({
+  proxy: [
+    { server: "1.2.3.4:8080", username: "user1", password: "pass1" },
+    { server: "5.6.7.8:8080", username: "user2", password: "pass2" },
+  ],
+});
+```
+
+A proxy is chosen at random from the array on each `connect()` call.
+
+## Forcing a specific fingerprint
+
+```ts
+const { page } = await connect({
+  fingerprint: {
+    platform: "MacIntel",
+    timezone: "Asia/Jakarta",
+    locale: "id-ID",
+  },
+});
+```
+
+Any field you don't specify is still randomized (consistently) around the rest.
+
+## API
+
+### `connect(options?: ConnectOptions): Promise<ConnectResult>`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `headless` | `boolean` | `false` | Run without a visible window |
+| `args` | `string[]` | `[]` | Extra Chromium flags |
+| `executablePath` | `string` | — | Use a specific Chrome/Chromium binary |
+| `proxy` | `ProxyConfig \| ProxyConfig[]` | — | Proxy or pool to rotate |
+| `turnstile` | `boolean` | `true` | Auto-solve Cloudflare Turnstile checkboxes |
+| `fingerprint` | `Partial<FingerprintProfile>` | — | Pin specific fingerprint fields |
+| `disableFingerprinting` | `boolean` | `false` | Skip fingerprint randomization |
+| `ghostCursor` | `boolean` | `true` | Use human-like mouse movement for `humanClick` |
+| `connectToExisting` | `{ browserWSEndpoint }` \| `{ browserURL }` | — | Attach to an already-running Chrome |
+| `customConfig` | `LaunchOptions` | `{}` | Passed straight through to `puppeteer.launch` |
+| `ignoreAllFlags` | `boolean` | `false` | Disable every evasion patch (debugging only) |
+
+### `ConnectResult`
+
+- `browser`, `page` — standard Puppeteer objects
+- `fingerprint` — the resolved `FingerprintProfile` actually applied
+- `humanClick(page, selector)`
+- `humanType(page, selector, text)`
+- `humanScroll(page, distance)`
+- `solveTurnstile(page)` — manually trigger a solve attempt
+
+## Scope & limitations
+
+This handles the same class of problem as `puppeteer-real-browser`: making an automated browser look and act like a real one for checkbox-style challenges (Turnstile) and general bot-detection scripts. It does **not** solve interactive image/audio CAPTCHAs (reCAPTCHA v2 puzzles, hCaptcha image grids) — those require a separate solving service.
+
+Be aware this can never be a 100% guarantee against every detection technique — some vectors sit below what any JS/CDP-level patch can fully hide, such as TLS/JA3 handshake fingerprinting, font-enumeration fingerprinting, or CDP protocol timing signatures. Sophisticated anti-bot services combine dozens of signals, so treat this as raising the bar significantly, not as an absolute guarantee. Always check the target site's Terms of Service and applicable law before automating access to it.
+
+## Build from source
+
+```bash
+npm install
+npm run typecheck
+npm run build
+npm test
+```
+
+## Publishing to npm
+
+1. Check the name is still free: `npm view real-browser-plus` (should return a 404 / "not found").
+2. Update `"author"`, `"repository"`, `"bugs"`, and `"homepage"` in `package.json` with your own GitHub username.
+3. Log in: `npm login`
+4. Bump the version if needed: `npm version patch` (or `minor`/`major`)
+5. Publish: `npm publish`
+
+`prepublishOnly` already runs `typecheck` → `build` → `test` automatically, so a broken package can't be published by accident.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,123 @@
+import { LaunchOptions, Browser, Page } from 'puppeteer';
+
+interface ProxyConfig {
+    server: string;
+    username?: string;
+    password?: string;
+}
+interface FingerprintProfile {
+    userAgent: string;
+    chromeVersion: string;
+    chromeMajorVersion: string;
+    platform: string;
+    viewport: {
+        width: number;
+        height: number;
+        deviceScaleFactor: number;
+    };
+    screen: {
+        width: number;
+        height: number;
+    };
+    hardwareConcurrency: number;
+    deviceMemory: number;
+    timezone: string;
+    locale: string;
+    webglVendor: string;
+    webglRenderer: string;
+    languages: string[];
+}
+interface SessionData {
+    cookies: unknown[];
+    localStorage: Record<string, string>;
+    sessionStorage: Record<string, string>;
+    origin: string;
+}
+type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
+interface RetryOptions {
+    retries?: number;
+    minDelayMs?: number;
+    maxDelayMs?: number;
+    onRetry?: (attempt: number, error: unknown) => void;
+}
+interface RealBrowserPlugin {
+    name: string;
+    onBrowserLaunched?: (browser: Browser) => void | Promise<void>;
+    onPageCreated?: (page: Page) => void | Promise<void>;
+    onBeforeClose?: (browser: Browser) => void | Promise<void>;
+}
+interface ConnectOptions {
+    headless?: boolean;
+    args?: string[];
+    executablePath?: string;
+    proxy?: ProxyConfig | ProxyConfig[];
+    turnstile?: boolean;
+    fingerprint?: Partial<FingerprintProfile>;
+    disableFingerprinting?: boolean;
+    ghostCursor?: boolean;
+    blockWebRTCLeak?: boolean;
+    connectToExisting?: {
+        browserWSEndpoint: string;
+    } | {
+        browserURL: string;
+    };
+    customConfig?: LaunchOptions;
+    ignoreAllFlags?: boolean;
+    plugins?: RealBrowserPlugin[];
+    logLevel?: LogLevel;
+    session?: SessionData;
+}
+interface ConnectResult {
+    browser: Browser;
+    page: Page;
+    fingerprint: FingerprintProfile;
+    humanClick: (page: Page, selector: string) => Promise<void>;
+    humanType: (page: Page, selector: string, text: string) => Promise<void>;
+    humanScroll: (page: Page, distance: number) => Promise<void>;
+    solveTurnstile: (page: Page) => Promise<boolean>;
+    saveSession: (page: Page) => Promise<SessionData>;
+    restoreSession: (page: Page, session: SessionData) => Promise<void>;
+    withRetry: <T>(fn: () => Promise<T>, options?: RetryOptions) => Promise<T>;
+    use: (plugin: RealBrowserPlugin) => Promise<void>;
+}
+
+declare function generateFingerprint(overrides?: Partial<FingerprintProfile>): FingerprintProfile;
+
+interface Point {
+    x: number;
+    y: number;
+}
+declare function moveMouseHuman(page: Page, target: Point): Promise<void>;
+declare function ghostClick(page: Page, selector: string): Promise<void>;
+
+declare function humanType(page: Page, selector: string, text: string): Promise<void>;
+
+declare function humanScroll(page: Page, distance: number): Promise<void>;
+
+declare function solveTurnstile(page: Page): Promise<boolean>;
+
+declare function saveSession(page: Page): Promise<SessionData>;
+declare function restoreSession(page: Page, session: SessionData): Promise<void>;
+
+declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+
+declare class Logger {
+    private level;
+    constructor(level?: LogLevel);
+    setLevel(level: LogLevel): void;
+    private shouldLog;
+    error(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+}
+declare const logger: Logger;
+
+declare function blockWebRTCLeak(page: Page): Promise<void>;
+
+declare function connect(options?: ConnectOptions): Promise<ConnectResult>;
+declare const _default: {
+    connect: typeof connect;
+};
+
+export { type ConnectOptions, type ConnectResult, type FingerprintProfile, type LogLevel, Logger, type ProxyConfig, type RealBrowserPlugin, type RetryOptions, type SessionData, blockWebRTCLeak, connect, _default as default, generateFingerprint, ghostClick, humanScroll, humanType, logger, moveMouseHuman, restoreSession, saveSession, solveTurnstile, withRetry };

package/dist/index.d.ts

@@ -0,0 +1,123 @@
+import { LaunchOptions, Browser, Page } from 'puppeteer';
+
+interface ProxyConfig {
+    server: string;
+    username?: string;
+    password?: string;
+}
+interface FingerprintProfile {
+    userAgent: string;
+    chromeVersion: string;
+    chromeMajorVersion: string;
+    platform: string;
+    viewport: {
+        width: number;
+        height: number;
+        deviceScaleFactor: number;
+    };
+    screen: {
+        width: number;
+        height: number;
+    };
+    hardwareConcurrency: number;
+    deviceMemory: number;
+    timezone: string;
+    locale: string;
+    webglVendor: string;
+    webglRenderer: string;
+    languages: string[];
+}
+interface SessionData {
+    cookies: unknown[];
+    localStorage: Record<string, string>;
+    sessionStorage: Record<string, string>;
+    origin: string;
+}
+type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
+interface RetryOptions {
+    retries?: number;
+    minDelayMs?: number;
+    maxDelayMs?: number;
+    onRetry?: (attempt: number, error: unknown) => void;
+}
+interface RealBrowserPlugin {
+    name: string;
+    onBrowserLaunched?: (browser: Browser) => void | Promise<void>;
+    onPageCreated?: (page: Page) => void | Promise<void>;
+    onBeforeClose?: (browser: Browser) => void | Promise<void>;
+}
+interface ConnectOptions {
+    headless?: boolean;
+    args?: string[];
+    executablePath?: string;
+    proxy?: ProxyConfig | ProxyConfig[];
+    turnstile?: boolean;
+    fingerprint?: Partial<FingerprintProfile>;
+    disableFingerprinting?: boolean;
+    ghostCursor?: boolean;
+    blockWebRTCLeak?: boolean;
+    connectToExisting?: {
+        browserWSEndpoint: string;
+    } | {
+        browserURL: string;
+    };
+    customConfig?: LaunchOptions;
+    ignoreAllFlags?: boolean;
+    plugins?: RealBrowserPlugin[];
+    logLevel?: LogLevel;
+    session?: SessionData;
+}
+interface ConnectResult {
+    browser: Browser;
+    page: Page;
+    fingerprint: FingerprintProfile;
+    humanClick: (page: Page, selector: string) => Promise<void>;
+    humanType: (page: Page, selector: string, text: string) => Promise<void>;
+    humanScroll: (page: Page, distance: number) => Promise<void>;
+    solveTurnstile: (page: Page) => Promise<boolean>;
+    saveSession: (page: Page) => Promise<SessionData>;
+    restoreSession: (page: Page, session: SessionData) => Promise<void>;
+    withRetry: <T>(fn: () => Promise<T>, options?: RetryOptions) => Promise<T>;
+    use: (plugin: RealBrowserPlugin) => Promise<void>;
+}
+
+declare function generateFingerprint(overrides?: Partial<FingerprintProfile>): FingerprintProfile;
+
+interface Point {
+    x: number;
+    y: number;
+}
+declare function moveMouseHuman(page: Page, target: Point): Promise<void>;
+declare function ghostClick(page: Page, selector: string): Promise<void>;
+
+declare function humanType(page: Page, selector: string, text: string): Promise<void>;
+
+declare function humanScroll(page: Page, distance: number): Promise<void>;
+
+declare function solveTurnstile(page: Page): Promise<boolean>;
+
+declare function saveSession(page: Page): Promise<SessionData>;
+declare function restoreSession(page: Page, session: SessionData): Promise<void>;
+
+declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+
+declare class Logger {
+    private level;
+    constructor(level?: LogLevel);
+    setLevel(level: LogLevel): void;
+    private shouldLog;
+    error(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+}
+declare const logger: Logger;
+
+declare function blockWebRTCLeak(page: Page): Promise<void>;
+
+declare function connect(options?: ConnectOptions): Promise<ConnectResult>;
+declare const _default: {
+    connect: typeof connect;
+};
+
+export { type ConnectOptions, type ConnectResult, type FingerprintProfile, type LogLevel, Logger, type ProxyConfig, type RealBrowserPlugin, type RetryOptions, type SessionData, blockWebRTCLeak, connect, _default as default, generateFingerprint, ghostClick, humanScroll, humanType, logger, moveMouseHuman, restoreSession, saveSession, solveTurnstile, withRetry };