zevairouter 1.0.154 → 1.0.156

package/src/lib/oauth/services/bulkImportBrowserEngine.js

@@ -1,756 +0,0 @@
-import { createHash } from "node:crypto";
-import { createRequire } from "node:module";
-import net from "node:net";
-import { ProxyAgent, fetch as undiciFetch } from "undici";
-
-const requireFromHere = createRequire(import.meta.url);
-
-/**
- * Automation browser engine: CloakBrowser only.
- * Stock Playwright Chromium is retired for bulk import — CloakBrowser is a
- * patched Chromium that passes Turnstile / bot checks (CF, Google, etc.).
- * playwright-core remains a peer of cloakbrowser (drive API only; no stock browser).
- */
-export const DEFAULT_BULK_IMPORT_ENGINE = "cloakbrowser";
-
-const SUPPORTED_ENGINES = new Set(["cloakbrowser"]);
-const CLOAK_PROXY_PROFILES = new WeakMap();
-const CLOAK_BROWSER_PROCESSES = new WeakMap();
-const CLOAK_BROWSER_HEADLESS = new WeakMap();
-
-export const DEFAULT_BROWSER_LAUNCH_TIMEOUT_MS = 90_000;
-export const DEFAULT_CONTEXT_CREATE_TIMEOUT_MS = 30_000;
-export const DEFAULT_CONTEXT_CLOSE_TIMEOUT_MS = 5_000;
-
-export const PROXY_EGRESS_ECHO_URLS = Object.freeze([
-  "https://myip.ipip.net",
-  "https://ip.3322.net",
-  "https://cip.cc",
-]);
-
-const PROXY_GEO_PROFILES = Object.freeze({
-  CN: { timezone: "Asia/Shanghai", locale: "zh-CN" },
-  HK: { timezone: "Asia/Hong_Kong", locale: "zh-HK" },
-  MO: { timezone: "Asia/Macau", locale: "zh-MO" },
-  TW: { timezone: "Asia/Taipei", locale: "zh-TW" },
-  SG: { timezone: "Asia/Singapore", locale: "en-SG" },
-  JP: { timezone: "Asia/Tokyo", locale: "ja-JP" },
-  KR: { timezone: "Asia/Seoul", locale: "ko-KR" },
-  US: { locale: "en-US" },
-  GB: { locale: "en-GB" },
-});
-
-const DEFAULT_PROXY_PROBE_TIMEOUT_MS = 8_000;
-const DEFAULT_PROXY_GEO_TIMEOUT_MS = 5_000;
-
-export function normalizeBulkImportEngine(value) {
-  if (typeof value !== "string" || !value.trim()) return DEFAULT_BULK_IMPORT_ENGINE;
-  const lower = value.trim().toLowerCase();
-  // Legacy aliases: everything maps to cloakbrowser (chromium/camoufox retired).
-  if (
-    lower === "cloak" ||
-    lower === "cloackbrowser" ||
-    lower === "cloack" ||
-    lower === "cloak-browser" ||
-    lower === "chromium" ||
-    lower === "chrome" ||
-    lower === "camoufox" ||
-    lower === "playwright"
-  ) {
-    return "cloakbrowser";
-  }
-  return SUPPORTED_ENGINES.has(lower) ? lower : DEFAULT_BULK_IMPORT_ENGINE;
-}
-
-function loadRuntimeHelper(name) {
-  try {
-    return requireFromHere(`../../../../cli/hooks/${name}`);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Seeded fingerprint so each account/session looks like a different real desktop
- * instead of the same 900x700 + identical navigator.* cluster (Tencent risk signal).
- * Do NOT spoof WebGL (CloakBrowser already patches at binary level).
- *
- * @param {string|number} [seed]
- */
-export function buildAccountFingerprint(seed) {
-  let buf = createHash("sha256").update(String(seed ?? `${Date.now()}-${Math.random()}`)).digest();
-  let i = 0;
-  const nextByte = () => {
-    if (i >= buf.length) {
-      buf = createHash("sha256").update(buf).digest();
-      i = 0;
-    }
-    return buf[i++];
-  };
-  const next = () => nextByte() / 256;
-  const pick = (arr) => arr[Math.floor(next() * arr.length) % arr.length];
-
-  const base = pick([
-    { width: 1366, height: 768 },
-    { width: 1440, height: 900 },
-    { width: 1536, height: 864 },
-    { width: 1920, height: 1080 },
-    { width: 1280, height: 800 },
-    { width: 1600, height: 900 },
-    { width: 1280, height: 720 },
-    { width: 1680, height: 1050 },
-    { width: 2560, height: 1440 },
-  ]);
-  const width = base.width - (nextByte() % 17);
-  const height = base.height - (nextByte() % 13);
-  const taskbar = pick([0, 30, 40, 48]);
-  const colorDepth = pick([24, 30, 32]);
-
-  return {
-    seed: String(seed ?? ""),
-    viewport: { width, height },
-    deviceScaleFactor: pick([1, 1, 1.25, 1.5, 2]),
-    hardwareConcurrency: pick([4, 6, 8, 8, 12, 16]),
-    deviceMemory: pick([4, 8, 8, 16]),
-    maxTouchPoints: 0,
-    screen: {
-      width,
-      height,
-      availWidth: width,
-      availHeight: Math.max(height - taskbar, Math.floor(height * 0.92)),
-      colorDepth,
-      pixelDepth: colorDepth,
-    },
-  };
-}
-
-/**
- * Keep stealth dimensions internally consistent while bounding renderer cost on
- * memory-constrained VPS hosts. Large DPR + 1440p fingerprints can consume most
- * of a 2GB server before the login SPA finishes booting.
- */
-export function compactAccountFingerprint(
-  fingerprint,
-  { maxWidth = 1280, maxHeight = 800, maxDeviceScaleFactor = 1.25 } = {},
-) {
-  if (!fingerprint || typeof fingerprint !== "object") return fingerprint;
-
-  const viewport = fingerprint.viewport || {};
-  const screen = fingerprint.screen || {};
-  const width = Math.min(Number(viewport.width) || maxWidth, maxWidth);
-  const height = Math.min(Number(viewport.height) || maxHeight, maxHeight);
-  const originalScreenHeight = Number(screen.height) || height;
-  const originalAvailHeight = Number(screen.availHeight) || originalScreenHeight;
-  const taskbarHeight = Math.max(0, originalScreenHeight - originalAvailHeight);
-
-  return {
-    ...fingerprint,
-    viewport: { width, height },
-    deviceScaleFactor: Math.min(
-      Number(fingerprint.deviceScaleFactor) || 1,
-      maxDeviceScaleFactor,
-    ),
-    screen: {
-      ...screen,
-      width,
-      height,
-      availWidth: width,
-      availHeight: Math.max(0, height - Math.min(taskbarHeight, 48)),
-    },
-  };
-}
-
-/**
- * Light init script for per-account HW/screen noise.
- * Avoids webdriver/WebGL patches that conflict with CloakBrowser binary stealth.
- */
-export function buildFingerprintInitScript({ languages, fingerprint } = {}) {
-  return `
-  (() => {
-    const profile = ${JSON.stringify({
-      languages: Array.isArray(languages) ? languages : null,
-      hardwareConcurrency: fingerprint?.hardwareConcurrency ?? null,
-      deviceMemory: fingerprint?.deviceMemory ?? null,
-      maxTouchPoints: fingerprint?.maxTouchPoints ?? null,
-      screen: fingerprint?.screen ?? null,
-    })};
-    try {
-      if (Array.isArray(profile.languages) && profile.languages.length) {
-        Object.defineProperty(navigator, 'languages', { get: () => profile.languages.slice() });
-      }
-    } catch {}
-    try {
-      if (typeof profile.hardwareConcurrency === 'number') {
-        Object.defineProperty(navigator, 'hardwareConcurrency', { get: () => profile.hardwareConcurrency });
-      }
-    } catch {}
-    try {
-      if (typeof profile.deviceMemory === 'number') {
-        Object.defineProperty(navigator, 'deviceMemory', { get: () => profile.deviceMemory });
-      }
-    } catch {}
-    try {
-      if (typeof profile.maxTouchPoints === 'number') {
-        Object.defineProperty(navigator, 'maxTouchPoints', { get: () => profile.maxTouchPoints });
-      }
-    } catch {}
-    try {
-      if (profile.screen && typeof profile.screen === 'object') {
-        const s = profile.screen;
-        for (const key of ['width', 'height', 'availWidth', 'availHeight', 'colorDepth', 'pixelDepth']) {
-          if (typeof s[key] === 'number') {
-            try { Object.defineProperty(screen, key, { get: () => s[key] }); } catch {}
-          }
-        }
-      }
-    } catch {}
-  })();
-`;
-}
-
-/**
- * Strip non-Playwright keys from newContext options and attach fingerprint init.
- * CloakBrowser is Playwright-compatible — `languages` / `fingerprint` are ours only.
- *
- * @param {import('playwright-core').Browser} browser
- * @param {object} options
- */
-export async function newStealthContext(browser, options = {}) {
-  const {
-    languages,
-    fingerprint,
-    ...pwOptions
-  } = options || {};
-  const context = await browser.newContext(pwOptions);
-  if (
-    (Array.isArray(languages) && languages.length) ||
-    (fingerprint && typeof fingerprint === "object")
-  ) {
-    try {
-      await context.addInitScript(
-        buildFingerprintInitScript({ languages, fingerprint }),
-      );
-    } catch {
-      // older drivers may not support addInitScript
-    }
-  }
-  return context;
-}
-
-export async function withAutomationTimeout(
-  task,
-  {
-    timeoutMs,
-    message = `Automation operation timed out after ${timeoutMs}ms`,
-    code = "AUTOMATION_TIMEOUT",
-    onTimeout,
-    onLateResolve,
-  } = {},
-) {
-  const operation = Promise.resolve(task);
-  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return operation;
-
-  let timer = null;
-  let timedOut = false;
-  const timeout = new Promise((_, reject) => {
-    timer = setTimeout(() => {
-      timedOut = true;
-      try {
-        onTimeout?.();
-      } catch {
-        // Preserve the timeout as the primary failure.
-      }
-      reject(Object.assign(new Error(message), { code }));
-    }, timeoutMs);
-    timer.unref?.();
-  });
-
-  try {
-    return await Promise.race([operation, timeout]);
-  } finally {
-    if (timer) clearTimeout(timer);
-    if (timedOut && typeof onLateResolve === "function") {
-      void operation.then(onLateResolve).catch(() => null);
-    }
-  }
-}
-
-export function parseProxyEgressIp(value) {
-  const raw = String(value || "").trim();
-  if (!raw) return null;
-  if (net.isIP(raw)) return raw;
-
-  try {
-    const parsed = JSON.parse(raw);
-    for (const key of ["ip", "query", "address", "origin"]) {
-      const candidate = String(parsed?.[key] || "").trim();
-      if (net.isIP(candidate)) return candidate;
-    }
-  } catch {
-    // Plain-text echo services are expected here.
-  }
-
-  for (const match of raw.matchAll(/(?:\d{1,3}\.){3}\d{1,3}/g)) {
-    if (net.isIP(match[0])) return match[0];
-  }
-
-  const tokens = raw.split(/[\s,;()[\]{}<>"'=\uFF1A]+/);
-  for (const token of tokens) {
-    const candidate = token.replace(/^[^0-9a-f:]+|[^0-9a-f:]+$/gi, "");
-    if (candidate.includes(":") && net.isIP(candidate)) return candidate;
-  }
-  return null;
-}
-
-function inferProxyRegionalProfile(proxyUrl) {
-  try {
-    const parsed = new URL(String(proxyUrl || "").trim());
-    const username = decodeURIComponent(parsed.username || "");
-    const matches = [...username.matchAll(/(?:^|__)cr\.([a-z]{2})(?=__|$)/gi)];
-    const countryCode = matches.at(-1)?.[1]?.toUpperCase() || null;
-    const regional = countryCode ? PROXY_GEO_PROFILES[countryCode] : null;
-    return regional?.timezone && regional?.locale
-      ? { countryCode, ...regional, source: "proxy-country" }
-      : null;
-  } catch {
-    return null;
-  }
-}
-
-async function closeProxyAgent(agent) {
-  if (!agent) return;
-  if (typeof agent.close === "function") {
-    await Promise.resolve(agent.close()).catch(() => null);
-    return;
-  }
-  if (typeof agent.destroy === "function") {
-    await Promise.resolve(agent.destroy()).catch(() => null);
-  }
-}
-
-/**
- * Pin a fresh sticky proxy with one request at a time. Parallel first-use
- * requests can race session assignment on providers such as DataImpulse.
- */
-export async function probeProxyEgressBeforeLaunch(
-  proxyUrl,
-  {
-    timeoutMs = DEFAULT_PROXY_PROBE_TIMEOUT_MS,
-    urls = PROXY_EGRESS_ECHO_URLS,
-    fetchImpl = undiciFetch,
-    createProxyAgent = (url) => new ProxyAgent(url),
-  } = {},
-) {
-  let agent = null;
-  const attemptedUrls = [];
-  let lastError = null;
-
-  try {
-    try {
-      agent = createProxyAgent(proxyUrl);
-    } catch {
-      return {
-        ok: false,
-        ip: null,
-        url: null,
-        attempts: 0,
-        attemptedUrls,
-        error: "proxy agent setup failed",
-      };
-    }
-
-    for (const url of urls) {
-      attemptedUrls.push(url);
-      try {
-        const response = await fetchImpl(url, {
-          dispatcher: agent,
-          redirect: "follow",
-          signal: AbortSignal.timeout(timeoutMs),
-          headers: {
-            Accept: "text/plain, application/json;q=0.9, */*;q=0.1",
-            "Cache-Control": "no-cache",
-          },
-        });
-        if (!response?.ok) {
-          lastError = `HTTP ${response?.status || 0}`;
-          continue;
-        }
-        const ip = parseProxyEgressIp(await response.text());
-        if (!ip) {
-          lastError = "exit-IP response was not recognized";
-          continue;
-        }
-        return {
-          ok: true,
-          ip,
-          url,
-          attempts: attemptedUrls.length,
-          attemptedUrls,
-          error: null,
-        };
-      } catch (error) {
-        lastError = error?.name === "TimeoutError"
-          ? `timed out after ${timeoutMs}ms`
-          : "request failed";
-      }
-    }
-
-    return {
-      ok: false,
-      ip: null,
-      url: null,
-      attempts: attemptedUrls.length,
-      attemptedUrls,
-      error: lastError || "all exit-IP services failed",
-    };
-  } finally {
-    await closeProxyAgent(agent);
-  }
-}
-
-async function lookupProxyGeoProfile(
-  egressIp,
-  { timeoutMs = DEFAULT_PROXY_GEO_TIMEOUT_MS, fetchImpl = undiciFetch } = {},
-) {
-  try {
-    const response = await fetchImpl(`https://ipwho.is/${encodeURIComponent(egressIp)}`, {
-      redirect: "follow",
-      signal: AbortSignal.timeout(timeoutMs),
-      headers: { Accept: "application/json" },
-    });
-    if (!response?.ok) return null;
-    const data = await response.json();
-    if (data?.success === false) return null;
-    const countryCode = String(data?.country_code || "").trim().toUpperCase();
-    const timezone = String(data?.timezone?.id || "").trim();
-    const locale = PROXY_GEO_PROFILES[countryCode]?.locale
-      || (countryCode ? `en-${countryCode}` : "");
-    return timezone && locale
-      ? { countryCode: countryCode || null, timezone, locale, source: "ip-geo" }
-      : null;
-  } catch {
-    return null;
-  }
-}
-
-export async function resolveProxyLaunchProfile(proxyUrl, options = {}) {
-  const probe = await probeProxyEgressBeforeLaunch(proxyUrl, options);
-  if (!probe.ok || !probe.ip) {
-    const error = new Error(
-      `Manual proxy exit IP could not be verified before browser launch (${probe.error || "no response"}); no phone number was purchased`,
-    );
-    error.code = "CLOAKBROWSER_PROXY_EGRESS_UNAVAILABLE";
-    throw error;
-  }
-
-  const regional = inferProxyRegionalProfile(proxyUrl)
-    || await lookupProxyGeoProfile(probe.ip, options);
-  if (!regional?.timezone || !regional?.locale) {
-    const error = new Error(
-      "Manual proxy region could not be aligned with CloakBrowser; no phone number was purchased",
-    );
-    error.code = "CLOAKBROWSER_PROXY_GEOIP_UNAVAILABLE";
-    throw error;
-  }
-
-  return Object.freeze({
-    egressIp: probe.ip,
-    timezone: regional.timezone,
-    locale: regional.locale,
-    countryCode: regional.countryCode || null,
-    source: regional.source,
-    probeUrl: probe.url,
-    probeAttempts: probe.attempts,
-  });
-}
-
-export function buildVerifiedProxyLaunchOptions(launchOpts, proxyProfile) {
-  const managedPrefixes = [
-    "--fingerprint-webrtc-ip=",
-    "--fingerprint-timezone=",
-    "--fingerprint-locale=",
-    "--lang=",
-  ];
-  const args = (launchOpts?.args || []).filter(
-    (arg) => !managedPrefixes.some((prefix) => String(arg).startsWith(prefix)),
-  );
-  args.push(
-    `--fingerprint-webrtc-ip=${proxyProfile.egressIp}`,
-    `--fingerprint-timezone=${proxyProfile.timezone}`,
-    `--lang=${proxyProfile.locale}`,
-    `--fingerprint-locale=${proxyProfile.locale}`,
-  );
-  return {
-    ...launchOpts,
-    args,
-    timezone: proxyProfile.timezone,
-    locale: proxyProfile.locale,
-    geoip: false,
-  };
-}
-
-/**
- * CloakBrowser — sole bulk-import engine (patched stealth Chromium).
- * Prefer headed (headless=false); Turnstile / Google bot checks often fail headless.
- * Auto-installs into ~/.zevai/runtime via cloakbrowserRuntime.
- */
-export function extractCloakProxyProfile(args = []) {
-  const readFlag = (name) => {
-    const prefix = `${name}=`;
-    const value = (args || []).find((arg) => String(arg).startsWith(prefix));
-    return value ? String(value).slice(prefix.length) : null;
-  };
-  return {
-    egressIp: readFlag("--fingerprint-webrtc-ip"),
-    timezone: readFlag("--fingerprint-timezone"),
-    locale: readFlag("--fingerprint-locale") || readFlag("--lang"),
-  };
-}
-
-export function getCloakProxyProfile(browser) {
-  return browser && typeof browser === "object"
-    ? CLOAK_PROXY_PROFILES.get(browser) || null
-    : null;
-}
-
-export function getBulkImportBrowserHeadless(browser) {
-  return browser && typeof browser === "object" && CLOAK_BROWSER_HEADLESS.has(browser)
-    ? CLOAK_BROWSER_HEADLESS.get(browser)
-    : null;
-}
-
-function resolveBrowserProcess(browser) {
-  if (!browser || typeof browser !== "object") return null;
-
-  const tracked = CLOAK_BROWSER_PROCESSES.get(browser);
-  if (tracked) return tracked;
-
-  // Puppeteer exposes process(); Playwright does not. CloakBrowser returns a
-  // local Playwright Browser, so resolve its server-side BrowserProcess once
-  // while the connection is still alive and keep that owned handle in a WeakMap.
-  try {
-    const documented = typeof browser.process === "function" ? browser.process() : null;
-    if (documented?.pid) return documented;
-  } catch {
-    // Fall through to the local Playwright implementation.
-  }
-  try {
-    const impl = browser?._connection?.toImpl?.(browser);
-    const processHandle = impl?.options?.browserProcess?.process || null;
-    if (processHandle?.pid) return processHandle;
-  } catch {
-    // Remote Playwright connections intentionally do not expose a process.
-  }
-  return null;
-}
-
-function trackBrowserProcess(browser) {
-  const processHandle = resolveBrowserProcess(browser);
-  if (browser && processHandle) CLOAK_BROWSER_PROCESSES.set(browser, processHandle);
-  return processHandle;
-}
-
-export function getBrowserProcessId(browser) {
-  const pid = Number(resolveBrowserProcess(browser)?.pid);
-  return Number.isFinite(pid) && pid > 1 ? pid : null;
-}
-
-async function launchCloakbrowser({
-  proxyUrl,
-  headless = false,
-  windowSize = null,
-  requireProxyGeoip = false,
-} = {}) {
-  const { ensureDisplayForHeadedBrowser } = await import("./displayEnv.js");
-
-  const runtime = loadRuntimeHelper("cloakbrowserRuntime");
-  let cloak = null;
-  if (runtime?.ensureCloakbrowserRuntime) {
-    const ready = runtime.ensureCloakbrowserRuntime({ silent: false });
-    if (!ready.ok && ready.error) throw ready.error;
-    cloak = ready.module || runtime.loadCloakbrowserModule?.();
-  }
-  if (!cloak?.launch) {
-    try {
-      const mod = await import("cloakbrowser");
-      cloak = mod?.default || mod;
-    } catch (err) {
-      const friendly = new Error(
-        `cloakbrowser is not installed. Bulk import will auto-install on next run, or run: cd ~/.zevai/runtime && npm install cloakbrowser mmdb-lib playwright-core`,
-      );
-      friendly.code = "CLOAKBROWSER_PACKAGE_MISSING";
-      friendly.cause = err;
-      throw friendly;
-    }
-  }
-  if (!cloak?.launch) {
-    const err = new Error("cloakbrowser loaded but launch() is missing");
-    err.code = "CLOAKBROWSER_API_MISMATCH";
-    throw err;
-  }
-
-  let useHeadless = headless === true;
-  if (!useHeadless) {
-    const display = ensureDisplayForHeadedBrowser();
-    if (!display.ok) {
-      throw display.error;
-    }
-  }
-
-  const launchOpts = {
-    headless: useHeadless,
-    humanize: true,
-  };
-  if (proxyUrl) {
-    // geoip aligns timezone/locale to proxy IP (Turnstile / abusive-pattern checks).
-    launchOpts.proxy = proxyUrl;
-    launchOpts.geoip = true;
-  }
-  if (windowSize?.width && windowSize?.height) {
-    // Keep headed contexts at viewport:null so dimensions follow the real Xvfb
-    // window. A Playwright viewport here overrides CloakBrowser's coherent window.
-    launchOpts.args = [`--window-size=${windowSize.width},${windowSize.height}`];
-  }
-
-  let effectiveLaunchOpts = launchOpts;
-  let proxyProfile = null;
-  if (proxyUrl && requireProxyGeoip) {
-    // Resolve the exit ourselves through CN-accessible endpoints. CloakBrowser's
-    // foreign echo fallbacks can time out and mistake the gateway IP for the exit.
-    proxyProfile = await resolveProxyLaunchProfile(proxyUrl);
-    effectiveLaunchOpts = buildVerifiedProxyLaunchOptions(launchOpts, proxyProfile);
-  }
-
-  try {
-    // Do not wrap with stock stealth scripts — CloakBrowser patches at binary level.
-    const browser = await cloak.launch(effectiveLaunchOpts);
-    trackBrowserProcess(browser);
-    CLOAK_BROWSER_HEADLESS.set(browser, useHeadless);
-    if (proxyProfile) {
-      CLOAK_PROXY_PROFILES.set(browser, Object.freeze({ ...proxyProfile }));
-    }
-    return browser;
-  } catch (error) {
-    const msg = String(error?.message || error || "");
-    if (!useHeadless && /XServer|DISPLAY|Missing X server|headed browser|no DISPLAY/i.test(msg)) {
-      const display = ensureDisplayForHeadedBrowser();
-      if (display.ok) {
-        const browser = await cloak.launch(effectiveLaunchOpts);
-        trackBrowserProcess(browser);
-        CLOAK_BROWSER_HEADLESS.set(browser, useHeadless);
-        if (proxyProfile) {
-          CLOAK_PROXY_PROFILES.set(browser, Object.freeze({ ...proxyProfile }));
-        }
-        return browser;
-      }
-      const friendly = new Error(
-        `${msg}\n\nVPS has no display. Install a virtual screen then retry:\n` +
-          `  sudo apt-get update && sudo apt-get install -y xvfb\n` +
-          `  sudo systemctl restart zevairouter\n` +
-          `ZevaiRouter auto-starts Xvfb when installed.`,
-      );
-      friendly.code = "NO_DISPLAY";
-      friendly.cause = error;
-      throw friendly;
-    }
-    throw error;
-  }
-}
-
-/**
- * Launch the automation browser (CloakBrowser only).
- * @param {object} [opts]
- * @param {string} [opts.engine] ignored (always cloakbrowser; kept for API compat)
- * @param {string|null} [opts.proxyUrl]
- * @param {boolean} [opts.headless] default false (headed — Turnstile/Google)
- * @param {{width:number,height:number}|null} [opts.windowSize]
- */
-export async function launchBulkImportBrowser({
-  engine = DEFAULT_BULK_IMPORT_ENGINE,
-  proxyUrl,
-  headless = false,
-  windowSize = null,
-  requireProxyGeoip = false,
-  timeoutMs = DEFAULT_BROWSER_LAUNCH_TIMEOUT_MS,
-} = {}) {
-  // engine arg kept for API compatibility; always cloakbrowser.
-  void normalizeBulkImportEngine(engine);
-  const launchTask = launchCloakbrowser({
-    proxyUrl,
-    headless: headless === true,
-    windowSize,
-    requireProxyGeoip,
-  });
-  return withAutomationTimeout(launchTask, {
-    timeoutMs,
-    message: `CloakBrowser launch timed out after ${Math.round(timeoutMs / 1000)}s`,
-    code: "BROWSER_LAUNCH_TIMEOUT",
-    onLateResolve: (browser) => forceCloseBrowser(browser),
-  });
-}
-
-export function makeBrowserLauncher({ engine, proxyUrl, headless = false, windowSize = null } = {}) {
-  return () => launchBulkImportBrowser({ engine, proxyUrl, headless, windowSize });
-}
-
-/**
- * Force-close browser. Graceful close can hang on blackholed proxy / spinning renderer.
- */
-export async function forceCloseBrowser(browser, { timeoutMs = 4_000 } = {}) {
-  if (!browser) return;
-
-  const ownedProcess = resolveBrowserProcess(browser);
-  const pid = Number(ownedProcess?.pid);
-  const validPid = Number.isFinite(pid) && pid > 1 ? pid : null;
-
-  try {
-    await withAutomationTimeout(
-      Promise.resolve().then(() => browser.close()),
-      {
-        timeoutMs,
-        message: `Browser close timed out after ${timeoutMs}ms`,
-        code: "BROWSER_CLOSE_TIMEOUT",
-      },
-    );
-  } catch {
-    // Escalate to the process owned by this browser below.
-  }
-
-  const isAlive = () => {
-    if (!ownedProcess) return false;
-    if (ownedProcess.exitCode != null || ownedProcess.signalCode != null) return false;
-    if (!validPid) return true;
-    try {
-      process.kill(validPid, 0);
-      return true;
-    } catch {
-      return false;
-    }
-  };
-
-  if (ownedProcess && isAlive()) {
-    const signalOwnedProcess = (signal) => {
-      // Playwright launches Chromium detached on Unix. Signal the process group
-      // first so renderer children cannot outlive the browser parent.
-      if (validPid && process.platform !== "win32") {
-        try {
-          process.kill(-validPid, signal);
-        } catch {
-          // A non-detached process has no group keyed by its pid.
-        }
-      }
-      try {
-        if (typeof ownedProcess.kill === "function") ownedProcess.kill(signal);
-        else if (validPid) process.kill(validPid, signal);
-      } catch {
-        // Process may have exited between the liveness check and signal.
-      }
-    };
-
-    signalOwnedProcess("SIGTERM");
-    await new Promise((resolve) => setTimeout(resolve, 400));
-    if (isAlive()) {
-      signalOwnedProcess("SIGKILL");
-    }
-  }
-}