feat(js): add launchPersistentContext to Puppeteer wrapper (#261)

Expose userDataDir support via launchPersistentContext() for cloakbrowser/puppeteer, matching the existing Playwright API. Includes proxy auth, geoip, and humanize support.
2026-06-23 11:41:46 +02:00 · 2026-05-18 18:32:45 +02:00
parent 34bc095b65
commit 7a9a61d4de
2 changed files with 206 additions and 58 deletions
@@ -12,71 +12,55 @@ import { ensureBinary } from "./download.js";
 import { isSocksProxy, parseProxyUrl, resolveProxyConfig } from "./proxy.js";
 import { maybeResolveGeoip, resolveWebrtcArgs } from "./geoip.js";

-/**
- * Launch stealth Chromium browser via Puppeteer.
- *
- * @example
- * ```ts
- * import { launch } from 'cloakbrowser/puppeteer';
- * * // With humanize — human-like mouse, keyboard, scroll
- * const browser = await launch({ humanize: true });
- * const page = await browser.newPage();
- * await page.goto('[https://example.com](https://example.com)');
- * await page.click('#login');  // Bézier curve mouse movement
- * await page.type('#email', 'user@example.com');  // Per-character timing
- * ```
- */
-export async function launch(options: LaunchOptions = {}): Promise<Browser> {
-  const puppeteer = await import("puppeteer-core");
-
+/** Resolve binary path, geoip, webrtc, and build final Chrome args. */
+async function resolveArgs(options: LaunchOptions): Promise<{ binaryPath: string; args: string[] }> {
  const binaryPath = process.env.CLOAKBROWSER_BINARY_PATH || (await ensureBinary());
  const { exitIp, ...resolved } = (await maybeResolveGeoip(options)) ?? {};
  let resolvedArgs = (await resolveWebrtcArgs(options)) ?? options.args;
-  
+
  if (exitIp && !(resolvedArgs ?? []).some(a => a.startsWith("--fingerprint-webrtc-ip"))) {
    resolvedArgs = [...(resolvedArgs ?? []), `--fingerprint-webrtc-ip=${exitIp}`];
  }
-  const args = buildArgs({ ...options, ...resolved, args: resolvedArgs });
+  return { binaryPath, args: buildArgs({ ...options, ...resolved, args: resolvedArgs }) };
+}

-  // Puppeteer handles proxy via CLI args, not a separate option.
-  // SOCKS5: Chrome supports inline credentials natively (RFC 1929 auth).
-  // HTTP: Chrome does NOT support inline credentials — strip them and
-  // use page.authenticate() for Proxy-Authorization headers instead.
-  let proxyAuth: { username: string; password: string } | undefined;
-  if (options.proxy) {
-    if (isSocksProxy(options.proxy)) {
-      // SOCKS5: pass full URL with credentials to Chrome directly
-      const { proxyArgs } = resolveProxyConfig(options.proxy);
-      args.push(...proxyArgs);
-    } else if (typeof options.proxy === "string") {
-      const { server, username, password } = parseProxyUrl(options.proxy);
-      args.push(`--proxy-server=${server}`);
-      if (username) {
-        proxyAuth = { username, password: password ?? "" };
-      }
-    } else {
-      const parsed = parseProxyUrl(options.proxy.server);
-      args.push(`--proxy-server=${parsed.server}`);
-      if (options.proxy.bypass) {
-        args.push(`--proxy-bypass-list=${options.proxy.bypass}`);
-      }
-      const username = options.proxy.username ?? parsed.username;
-      const password = options.proxy.password ?? parsed.password;
-      if (username) {
-        proxyAuth = { username, password: password ?? "" };
-      }
-    }
+/**
+ * Resolve proxy into Chrome CLI args and optional HTTP auth credentials.
+ * SOCKS5: Chrome supports inline credentials natively (RFC 1929 auth).
+ * HTTP: Chrome does NOT support inline credentials — strip them and
+ * use page.authenticate() for Proxy-Authorization headers instead.
+ */
+function resolveProxy(options: LaunchOptions, args: string[]): { username: string; password: string } | undefined {
+  if (!options.proxy) return undefined;
+
+  if (isSocksProxy(options.proxy)) {
+    const { proxyArgs } = resolveProxyConfig(options.proxy);
+    args.push(...proxyArgs);
+    return undefined;
  }

-  const browser = await puppeteer.default.launch({
-    executablePath: binaryPath,
-    headless: options.headless ?? true,
-    args,
-    ignoreDefaultArgs: IGNORE_DEFAULT_ARGS,
-    ...options.launchOptions,
-  });
+  if (typeof options.proxy === "string") {
+    const { server, username, password } = parseProxyUrl(options.proxy);
+    args.push(`--proxy-server=${server}`);
+    return username ? { username, password: password ?? "" } : undefined;
+  }

-  // Monkey-patch newPage() to auto-authenticate proxy credentials
+  const parsed = parseProxyUrl(options.proxy.server);
+  args.push(`--proxy-server=${parsed.server}`);
+  if (options.proxy.bypass) {
+    args.push(`--proxy-bypass-list=${options.proxy.bypass}`);
+  }
+  const username = options.proxy.username ?? parsed.username;
+  const password = options.proxy.password ?? parsed.password;
+  return username ? { username, password: password ?? "" } : undefined;
+}
+
+/** Apply proxy auth monkey-patch and humanize behavioral patching. */
+async function applyPostLaunch(
+  browser: Browser,
+  options: LaunchOptions,
+  proxyAuth?: { username: string; password: string },
+): Promise<void> {
  if (proxyAuth) {
    const origNewPage = browser.newPage.bind(browser);
    const auth = proxyAuth;
@@ -87,9 +71,6 @@ export async function launch(options: LaunchOptions = {}): Promise<Browser> {
    };
  }

-  // Human-like behavioral patching — FULL coverage, same as Playwright.
-  // This enables Bézier mouse movements, organic typing rhythms, and 
-  // natural scrolling to bypass advanced anti-bot detection.
  if (options.humanize) {
    const { patchBrowser } = await import('./human-puppeteer/index.js');
    const { resolveConfig } = await import('./human/config.js');
@@ -99,6 +80,73 @@ export async function launch(options: LaunchOptions = {}): Promise<Browser> {
    );
    patchBrowser(browser, cfg);
  }
+}

+/**
+ * Launch stealth Chromium browser via Puppeteer.
+ *
+ * @example
+ * ```ts
+ * import { launch } from 'cloakbrowser/puppeteer';
+ * // With humanize — human-like mouse, keyboard, scroll
+ * const browser = await launch({ humanize: true });
+ * const page = await browser.newPage();
+ * await page.goto('https://example.com');
+ * await page.click('#login');  // Bézier curve mouse movement
+ * await page.type('#email', 'user@example.com');  // Per-character timing
+ * ```
+ */
+export async function launch(options: LaunchOptions = {}): Promise<Browser> {
+  const puppeteer = await import("puppeteer-core");
+  const { binaryPath, args } = await resolveArgs(options);
+  const proxyAuth = resolveProxy(options, args);
+
+  const browser = await puppeteer.default.launch({
+    ...options.launchOptions,
+    executablePath: binaryPath,
+    headless: options.headless ?? true,
+    args,
+    ignoreDefaultArgs: IGNORE_DEFAULT_ARGS,
+  });
+
+  await applyPostLaunch(browser, options, proxyAuth);
+  return browser;
+}
+
+/**
+ * Launch stealth Chromium with a persistent user profile via Puppeteer.
+ * Passes `userDataDir` to Puppeteer's launch options so cookies,
+ * localStorage, and session data persist across launches.
+ *
+ * @example
+ * ```ts
+ * import { launchPersistentContext } from 'cloakbrowser/puppeteer';
+ * const browser = await launchPersistentContext({
+ *   userDataDir: './chrome-profile',
+ *   headless: false,
+ *   proxy: 'http://user:pass@proxy:8080',
+ * });
+ * const page = await browser.newPage();
+ * await page.goto('https://example.com');
+ * await browser.close();
+ * ```
+ */
+export async function launchPersistentContext(
+  options: LaunchOptions & { userDataDir: string }
+): Promise<Browser> {
+  const puppeteer = await import("puppeteer-core");
+  const { binaryPath, args } = await resolveArgs(options);
+  const proxyAuth = resolveProxy(options, args);
+
+  const browser = await puppeteer.default.launch({
+    ...options.launchOptions,
+    executablePath: binaryPath,
+    headless: options.headless ?? true,
+    args,
+    ignoreDefaultArgs: IGNORE_DEFAULT_ARGS,
+    userDataDir: options.userDataDir,
+  });
+
+  await applyPostLaunch(browser, options, proxyAuth);
  return browser;
 }
@@ -126,6 +126,14 @@ describe("puppeteer launch", () => {
    expect(page.authenticate).not.toHaveBeenCalled();
  });

+  it("forwards launchOptions to puppeteer launch", async () => {
+    const { launch } = await import("../src/puppeteer.js");
+    await launch({ launchOptions: { slowMo: 50 } });
+
+    const callArgs = vi.mocked(puppeteerMock.default.launch).mock.calls[0][0];
+    expect(callArgs.slowMo).toBe(50);
+  });
+
  it("reconstructs SOCKS5 dict with auth into --proxy-server URL", async () => {
    const { launch } = await import("../src/puppeteer.js");
    const browser = await launch({
@@ -139,3 +147,95 @@ describe("puppeteer launch", () => {
    expect(page.authenticate).not.toHaveBeenCalled();
  });
 });
+
+describe("puppeteer launchPersistentContext", () => {
+  let puppeteerMock: any;
+  let mockBrowser: any;
+
+  beforeEach(async () => {
+    delete process.env.CLOAKBROWSER_BINARY_PATH;
+    puppeteerMock = await import("puppeteer-core");
+    mockBrowser = {
+      newPage: vi.fn().mockResolvedValue({
+        authenticate: vi.fn(),
+      }),
+      close: vi.fn(),
+    };
+    vi.mocked(puppeteerMock.default.launch).mockResolvedValue(mockBrowser);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("passes userDataDir to puppeteer launch", async () => {
+    process.env.CLOAKBROWSER_BINARY_PATH = "/fake/chrome";
+    const { launchPersistentContext } = await import("../src/puppeteer.js");
+    await launchPersistentContext({ userDataDir: "./my-profile" });
+
+    expect(puppeteerMock.default.launch).toHaveBeenCalledWith(
+      expect.objectContaining({
+        userDataDir: "./my-profile",
+        executablePath: "/fake/chrome",
+      })
+    );
+  });
+
+  it("includes stealth args", async () => {
+    const { launchPersistentContext } = await import("../src/puppeteer.js");
+    await launchPersistentContext({ userDataDir: "./my-profile" });
+
+    const callArgs = vi.mocked(puppeteerMock.default.launch).mock.calls[0][0];
+    expect(callArgs.args.some((a: string) => a.startsWith("--fingerprint="))).toBe(true);
+  });
+
+  it("handles proxy auth with persistent context", async () => {
+    const { launchPersistentContext } = await import("../src/puppeteer.js");
+    const browser = await launchPersistentContext({
+      userDataDir: "./my-profile",
+      proxy: "http://user:pass@proxy:8080",
+    });
+
+    const page = await browser.newPage();
+    expect(page.authenticate).toHaveBeenCalledWith({
+      username: "user",
+      password: "pass",
+    });
+  });
+
+  it("keeps SOCKS5 credentials in --proxy-server URL", async () => {
+    const { launchPersistentContext } = await import("../src/puppeteer.js");
+    const browser = await launchPersistentContext({
+      userDataDir: "./my-profile",
+      proxy: "socks5://user:pass@proxy:1080",
+    });
+
+    const callArgs = vi.mocked(puppeteerMock.default.launch).mock.calls[0][0];
+    expect(callArgs.args).toContain("--proxy-server=socks5://user:pass@proxy:1080");
+
+    const page = await browser.newPage();
+    expect(page.authenticate).not.toHaveBeenCalled();
+  });
+
+  it("forwards launchOptions to puppeteer launch", async () => {
+    const { launchPersistentContext } = await import("../src/puppeteer.js");
+    await launchPersistentContext({ userDataDir: "./my-profile", launchOptions: { slowMo: 50 } });
+
+    const callArgs = vi.mocked(puppeteerMock.default.launch).mock.calls[0][0];
+    expect(callArgs.slowMo).toBe(50);
+    expect(callArgs.userDataDir).toBe("./my-profile");
+  });
+
+  it("injects timezone and locale as binary flags", async () => {
+    const { launchPersistentContext } = await import("../src/puppeteer.js");
+    await launchPersistentContext({
+      userDataDir: "./my-profile",
+      timezone: "Asia/Tokyo",
+      locale: "ja-JP",
+    });
+
+    const callArgs = vi.mocked(puppeteerMock.default.launch).mock.calls[0][0];
+    expect(callArgs.args).toContain("--fingerprint-timezone=Asia/Tokyo");
+    expect(callArgs.args).toContain("--lang=ja-JP");
+  });
+});