@achamm/veilbrowser 0.3.0

package/src/browser.ts

@@ -0,0 +1,43 @@
+/**
+ * Browser: the top-level handle. Launches Chrome, opens the CDP socket, and
+ * hands out Page objects attached via flat sessions.
+ */
+import { launchChrome, type LaunchOptions, type LaunchResult } from "./launcher.js";
+import { CDP } from "./cdp.js";
+import { Page } from "./page.js";
+
+export class Browser {
+  private constructor(
+    private cdp: CDP,
+    private launch: LaunchResult,
+    private blockPrivate: boolean,
+  ) {}
+
+  static async launch(opts: LaunchOptions = {}): Promise<Browser> {
+    const launch = await launchChrome(opts);
+    const cdp = await CDP.connect(launch.webSocketDebuggerUrl);
+    // Default ON: a stealth browser shouldn't let visited sites port-scan your
+    // localhost/LAN. Opt out with { blockPrivateNetwork: false }.
+    return new Browser(cdp, launch, opts.blockPrivateNetwork ?? true);
+  }
+
+  /** Open a fresh tab and return an initialised Page. */
+  async newPage(): Promise<Page> {
+    const { targetId } = await this.cdp.send("Target.createTarget", { url: "about:blank" });
+    const { sessionId } = await this.cdp.send("Target.attachToTarget", {
+      targetId,
+      flatten: true,
+    });
+    const page = new Page(this.cdp, sessionId, targetId);
+    await page.init({ maskWebgl: this.launch.maskWebgl, blockPrivateNetwork: this.blockPrivate });
+    return page;
+  }
+
+  async close() {
+    try {
+      await this.cdp.send("Browser.close");
+    } catch {}
+    this.cdp.close();
+    this.launch.kill();
+  }
+}

package/src/cdp.ts

@@ -0,0 +1,133 @@
+/**
+ * Raw Chrome DevTools Protocol client.
+ *
+ * No puppeteer, no playwright, no chrome-remote-interface. Just a WebSocket and
+ * the protocol. We use "flat" session mode (Target.attachToTarget {flatten:true})
+ * so every command/event is tagged with a sessionId and we can talk to the
+ * browser and any number of page targets over a single socket.
+ *
+ * Crucially: we never call `Runtime.enable`. That command is one of the loudest
+ * automation tells on the web (it creates a detectable execution-context binding
+ * and fires events sites listen for). `Runtime.evaluate` works fine without it.
+ */
+
+type Pending = { resolve: (v: any) => void; reject: (e: Error) => void; method: string };
+type EventHandler = (params: any) => void;
+
+export class CDP {
+  private ws!: WebSocket;
+  private nextId = 1;
+  private pending = new Map<number, Pending>();
+  // key: `${sessionId ?? ""}:${method}` -> set of handlers
+  private handlers = new Map<string, Set<EventHandler>>();
+  private closed = false;
+
+  private constructor(private url: string) {}
+
+  static async connect(webSocketDebuggerUrl: string): Promise<CDP> {
+    const cdp = new CDP(webSocketDebuggerUrl);
+    await cdp.open();
+    return cdp;
+  }
+
+  private open(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.ws = new WebSocket(this.url);
+      this.ws.addEventListener("open", () => resolve());
+      this.ws.addEventListener("error", (e: any) =>
+        reject(new Error(`CDP socket error: ${e?.message ?? "unknown"}`)),
+      );
+      this.ws.addEventListener("close", () => {
+        this.closed = true;
+        for (const { reject } of this.pending.values())
+          reject(new Error("CDP connection closed"));
+        this.pending.clear();
+      });
+      this.ws.addEventListener("message", (ev: any) => this.onMessage(String(ev.data)));
+    });
+  }
+
+  private onMessage(data: string) {
+    let msg: any;
+    try {
+      msg = JSON.parse(data);
+    } catch {
+      return;
+    }
+    if (typeof msg.id === "number") {
+      const p = this.pending.get(msg.id);
+      if (!p) return;
+      this.pending.delete(msg.id);
+      if (msg.error) p.reject(new Error(`${p.method}: ${msg.error.message} (${msg.error.code})`));
+      else p.resolve(msg.result);
+      return;
+    }
+    // Event. Dispatch to handlers keyed with and without sessionId.
+    if (msg.method) {
+      const sid = msg.sessionId ?? "";
+      for (const key of [`${sid}:${msg.method}`, `*:${msg.method}`]) {
+        const set = this.handlers.get(key);
+        if (set) for (const h of [...set]) h(msg.params ?? {});
+      }
+    }
+  }
+
+  /** Send a CDP command. Optionally scoped to a session (page target). */
+  send<T = any>(method: string, params: Record<string, any> = {}, sessionId?: string): Promise<T> {
+    if (this.closed) return Promise.reject(new Error("CDP connection closed"));
+    const id = this.nextId++;
+    const payload: any = { id, method, params };
+    if (sessionId) payload.sessionId = sessionId;
+    return new Promise<T>((resolve, reject) => {
+      this.pending.set(id, { resolve, reject, method });
+      this.ws.send(JSON.stringify(payload));
+    });
+  }
+
+  /** Subscribe to an event. Pass sessionId, or "*" to match any session. */
+  on(method: string, handler: EventHandler, sessionId = "*"): () => void {
+    const key = `${sessionId}:${method}`;
+    let set = this.handlers.get(key);
+    if (!set) this.handlers.set(key, (set = new Set()));
+    set.add(handler);
+    return () => set!.delete(handler);
+  }
+
+  /** Resolve once an event fires (with optional predicate / timeout). */
+  once(method: string, opts: { sessionId?: string; predicate?: (p: any) => boolean; timeout?: number } = {}): Promise<any> {
+    return new Promise((resolve, reject) => {
+      const off = this.on(
+        method,
+        (p) => {
+          if (opts.predicate && !opts.predicate(p)) return;
+          clearTimeout(timer);
+          off();
+          resolve(p);
+        },
+        opts.sessionId ?? "*",
+      );
+      const timer = setTimeout(() => {
+        off();
+        reject(new Error(`Timed out waiting for ${method}`));
+      }, opts.timeout ?? 30000);
+    });
+  }
+
+  /** Remove all handlers for a specific sessionId. Called on page close to prevent accumulation. */
+  clearHandlers(sessionId: string) {
+    // Remove all handlers keyed with this sessionId
+    const prefix = `${sessionId}:`;
+    for (const key of this.handlers.keys()) {
+      if (key.startsWith(prefix)) {
+        this.handlers.delete(key);
+      }
+    }
+  }
+
+  close() {
+    this.closed = true;
+    try {
+      this.ws.close();
+    } catch {}
+  }
+}

package/src/human.ts

@@ -0,0 +1,82 @@
+/**
+ * Human-like input timing.
+ *
+ * Robotic automation moves the mouse in straight teleports and types at a
+ * perfectly fixed cadence. Behavioural-fingerprinting scripts (Akamai, PerimeterX,
+ * Datadome) watch for exactly that. We move along a curved path with eased,
+ * jittered timing and vary keystroke intervals around human norms.
+ *
+ * Determinism note: we draw randomness from a seedable PRNG so runs can be made
+ * reproducible for tests, while still being non-uniform on the wire.
+ */
+export class Rng {
+  private s: number;
+  constructor(seed = (Date.now() ^ (process.pid << 16)) >>> 0) {
+    this.s = seed >>> 0 || 1;
+  }
+  next(): number {
+    // xorshift32
+    let x = this.s;
+    x ^= x << 13;
+    x ^= x >>> 17;
+    x ^= x << 5;
+    this.s = x >>> 0;
+    return this.s / 0xffffffff;
+  }
+  range(min: number, max: number): number {
+    return min + this.next() * (max - min);
+  }
+  int(min: number, max: number): number {
+    return Math.floor(this.range(min, max + 1));
+  }
+}
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+/**
+ * Sample a curved path from `from` to `to` using a quadratic Bézier whose control
+ * point is offset perpendicular to the travel direction — the gentle arc a real
+ * hand makes. Returns ~steps points with eased spacing (slow-fast-slow).
+ */
+export function mousePath(from: Point, to: Point, rng: Rng): Point[] {
+  const dx = to.x - from.x;
+  const dy = to.y - from.y;
+  const dist = Math.hypot(dx, dy);
+  const steps = Math.max(8, Math.min(40, Math.round(dist / 12)));
+
+  // Perpendicular control-point offset, scaled to distance, signed randomly.
+  const mag = Math.min(dist * 0.18, 60) * (rng.next() < 0.5 ? -1 : 1) * rng.range(0.4, 1);
+  const mx = (from.x + to.x) / 2 + (-dy / (dist || 1)) * mag;
+  const my = (from.y + to.y) / 2 + (dx / (dist || 1)) * mag;
+
+  const pts: Point[] = [];
+  for (let i = 1; i <= steps; i++) {
+    let t = i / steps;
+    // ease-in-out so the cursor accelerates then settles
+    t = t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2;
+    const u = 1 - t;
+    const x = u * u * from.x + 2 * u * t * mx + t * t * to.x;
+    const y = u * u * from.y + 2 * u * t * my + t * t * to.y;
+    // sub-pixel jitter
+    pts.push({ x: x + rng.range(-0.6, 0.6), y: y + rng.range(-0.6, 0.6) });
+  }
+  pts[pts.length - 1] = { x: to.x, y: to.y }; // land exactly on target
+  return pts;
+}
+
+/** Per-step delay (ms) for mouse moves — short, slightly jittered. */
+export function moveDelay(rng: Rng): number {
+  return rng.range(4, 12);
+}
+
+/** Per-character delay (ms) for typing — human burst-and-pause cadence. */
+export function keyDelay(rng: Rng, char: string): number {
+  if (char === " ") return rng.range(60, 140);
+  if (/[.,!?]/.test(char)) return rng.range(120, 260); // micro-pause at punctuation
+  return rng.range(45, 130);
+}
+
+export const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

package/src/index.ts

@@ -0,0 +1,6 @@
+export { Browser } from "./browser.js";
+export { Page, isPrivateHost, type Snapshot, type Element, type FedCmAccount, type FedCmDialog } from "./page.js";
+export { launchChrome, findChrome, type LaunchOptions } from "./launcher.js";
+export { CDP } from "./cdp.js";
+export { STEALTH_SOURCE } from "./stealth.js";
+export { Rng, mousePath } from "./human.js";

package/src/launcher.ts

@@ -0,0 +1,325 @@
+/**
+ * Launches a REAL, unmodified Chrome. To a website, this process IS Chrome —
+ * identical TLS, identical JS engine, identical canvas/WebGL/font fingerprint —
+ * because it literally is the same binary a human runs.
+ *
+ * The whole stealth game at launch time is: don't add the switches that
+ * Puppeteer/Playwright add. Those tools flip on `--enable-automation` and a
+ * batch of `--disable-*` flags that change behaviour in fingerprintable ways.
+ * We launch with the flags a normal Chrome uses, minus the noise.
+ */
+import { spawn, type ChildProcess } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, readlinkSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+const CANDIDATES = [
+  process.env.VEIL_CHROME,
+  "/opt/google/chrome/chrome",
+  "/usr/bin/google-chrome",
+  "/usr/bin/google-chrome-stable",
+  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+  "/usr/bin/chromium",
+  "/usr/bin/chromium-browser",
+  "/snap/bin/chromium",
+].filter(Boolean) as string[];
+
+export function findChrome(): string {
+  for (const c of CANDIDATES) if (existsSync(c)) return c;
+  throw new Error("No Chrome/Chromium found. Set VEIL_CHROME=/path/to/chrome");
+}
+
+export interface LaunchOptions {
+  headless?: boolean;       // default false (headful is far less detectable)
+  userDataDir?: string;     // persist cookies/history -> looks like a used profile
+  chromePath?: string;
+  windowSize?: { width: number; height: number };
+  /**
+   * Virtual-display (Xvfb) resolution — the `screen.*` a page sees. Defaults to a
+   * realistic desktop 1920x1080 so the Chrome window sits INSIDE the screen. A
+   * virtual display sized to the window (screen === window, window taller than
+   * screen) is a classic headless tell; a real monitor is bigger than the window.
+   * Only applies to veil's own auto-Xvfb, not an external DISPLAY.
+   */
+  screenSize?: { width: number; height: number };
+  proxy?: string;           // e.g. "http://user:pass@host:port"
+  /**
+   * Block visited sites from reaching loopback / private-network hosts (default
+   * true). Detectors port-scan 127.0.0.1 from JS to fingerprint the machine's
+   * other software; it also leaks your LAN to every page. The agent's own
+   * top-level navigation to a private host still works. Set false to allow a
+   * page to reach localhost (e.g. driving your own local app via subresources).
+   */
+  blockPrivateNetwork?: boolean;
+  /**
+   * WebGL backend:
+   *  - "hardware": use the real GPU via ANGLE/EGL → genuine, consistent vendor.
+   *    Works headless AND headful (no Xvfb needed). Best stealth — nothing spoofed.
+   *  - "software": SwiftShader + a spoofed Intel vendor. For GPU-less hosts only.
+   *  - "off": no GL flags.
+   *  - "auto" (default): "hardware" if a DRI render node is accessible, else "software".
+   */
+  gpu?: "hardware" | "software" | "off" | "auto";
+  /**
+   * Run headful on a virtual X display via Xvfb — "headful on a server". Headful
+   * Chrome scores far better against deep fingerprinters than headless (no
+   * headless render quirks, real screen size). Default "auto": on when headful is
+   * requested (headless:false) and there's no real DISPLAY. Requires Xvfb on PATH.
+   */
+  xvfb?: boolean;
+  extraArgs?: string[];
+}
+
+const RENDER_NODE = "/dev/dri/renderD128";
+
+const wait = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+// --- Orphan-Chrome reaper --------------------------------------------------
+// Chrome runs as a TREE (main + renderers + gpu + zygote). SIGKILL to just the
+// main pid leaves the rest to reparent to init and run forever; and if the
+// owner dies without calling kill() (Ctrl-C, an uncaught throw), nothing reaps
+// them at all. Fix: every Chrome is spawned `detached` so it leads its own
+// process group, we kill the whole GROUP, and a process-level reaper sweeps any
+// survivors on exit/signal. (Puppeteer/Playwright do the same.)
+interface LiveBrowser {
+  child: ChildProcess;
+  xvfb: ChildProcess | null;
+  userDataDir: string;
+  ephemeral: boolean;
+}
+const LIVE = new Set<LiveBrowser>();
+let reaperInstalled = false;
+
+function killGroup(proc: ChildProcess | null): void {
+  const pid = proc?.pid;
+  if (!pid) return;
+  try {
+    process.kill(-pid, "SIGKILL"); // negative pid = the whole process group
+  } catch {
+    try {
+      proc!.kill("SIGKILL"); // group already gone → fall back to the single pid
+    } catch {}
+  }
+}
+
+function reapAll(): void {
+  for (const b of LIVE) {
+    killGroup(b.child);
+    killGroup(b.xvfb);
+  }
+}
+
+const SIGNAL_EXIT: Record<string, number> = { SIGINT: 130, SIGTERM: 143, SIGHUP: 129 };
+
+function installReaper(): void {
+  if (reaperInstalled) return;
+  reaperInstalled = true;
+  // 'exit' fires on a normal return AND during an uncaught-exception exit — sync
+  // context, exactly right for a group-kill.
+  process.on("exit", reapAll);
+  // Signals don't run 'exit' handlers on their own, so catch them, reap, and then
+  // leave with the conventional 128+signum code.
+  for (const sig of Object.keys(SIGNAL_EXIT)) {
+    process.on(sig as NodeJS.Signals, () => {
+      reapAll();
+      process.exit(SIGNAL_EXIT[sig]);
+    });
+  }
+}
+
+/** Start an Xvfb virtual display; resolves once it's ready, or null if unavailable. */
+async function startXvfb(width: number, height: number): Promise<{ display: string; proc: ChildProcess } | null> {
+  let n = 99;
+  for (; n < 160; n++) if (!existsSync(`/tmp/.X${n}-lock`)) break;
+  const display = `:${n}`;
+  let proc: ChildProcess;
+  try {
+    proc = spawn("Xvfb", [display, "-screen", "0", `${width}x${height}x24`, "-nolisten", "tcp"], {
+      stdio: "ignore",
+    });
+  } catch {
+    return null;
+  }
+  let exited = false;
+  proc.on("exit", () => (exited = true));
+  const start = Date.now();
+  while (!existsSync(`/tmp/.X${n}-lock`) && !exited && Date.now() - start < 5000) await wait(50);
+  if (exited) return null;
+  return { display, proc };
+}
+
+/** Resolve "auto" → real GPU if we can reach the render node, else SwiftShader. */
+function resolveGpu(mode: LaunchOptions["gpu"]): "hardware" | "software" | "off" {
+  if (mode && mode !== "auto") return mode;
+  try {
+    // accessSync would import fs; existsSync is already imported and the ACL
+    // grants read here. Presence of the node is a good-enough hardware signal.
+    return existsSync(RENDER_NODE) ? "hardware" : "software";
+  } catch {
+    return "software";
+  }
+}
+
+export interface LaunchResult {
+  webSocketDebuggerUrl: string;
+  process: ChildProcess;
+  userDataDir: string;
+  /** True only for SwiftShader (software) — the page layer should then mask the vendor. */
+  maskWebgl: boolean;
+  kill: () => void;
+}
+
+export async function launchChrome(opts: LaunchOptions = {}): Promise<LaunchResult> {
+  const chromePath = opts.chromePath ?? findChrome();
+  const ephemeral = !opts.userDataDir;
+  const userDataDir = opts.userDataDir ?? join(tmpdir(), `veil-${process.pid}-${Date.now()}`);
+  mkdirSync(userDataDir, { recursive: true });
+  // Reused profiles leave a stale DevToolsActivePort from the previous Chrome;
+  // waitForPort would read the OLD port and connect to a dead endpoint. Clear it
+  // so we wait for THIS launch's fresh port.
+  rmSync(join(userDataDir, "DevToolsActivePort"), { force: true });
+  // SingletonLock records who owns this profile — Chrome writes it as a symlink
+  // "<host>-<pid>". Only clear a STALE lock (its pid is dead). If a LIVE Chrome
+  // still owns the profile, REFUSE: two Chromes on one userDataDir silently
+  // corrupt it (this was the real cause of an "Initializing…" hang). Blindly
+  // removing the lock, as before, let that corruption happen.
+  const lockPath = join(userDataDir, "SingletonLock");
+  let ownerPid = -1; // -1 = no lock present
+  try { ownerPid = parseInt(readlinkSync(lockPath).split("-").pop() || "", 10); } catch {}
+  if (ownerPid > 0) {
+    let alive = false;
+    try { process.kill(ownerPid, 0); alive = true; } catch (e: any) { alive = e?.code === "EPERM"; }
+    if (alive) {
+      throw new Error(
+        `Profile "${userDataDir}" is already in use by Chrome (pid ${ownerPid}). ` +
+          `Close it, or launch with a different userDataDir.`,
+      );
+    }
+  }
+  rmSync(lockPath, { force: true }); // absent or stale → safe to clear
+  rmSync(join(userDataDir, "SingletonCookie"), { force: true });
+  rmSync(join(userDataDir, "SingletonSocket"), { force: true });
+  // The screen (virtual display) is a realistic desktop; the window sits INSIDE it
+  // and is never larger than it, positioned like a real user's window so that
+  // screen.* > window.outer.*, availHeight leaves room for a taskbar, and
+  // screenX/screenY are non-zero — none of the "display sized to the window" tells.
+  const screen = opts.screenSize ?? { width: 1920, height: 1080 };
+  const win = opts.windowSize ?? { width: 1280, height: 800 };
+  const width = Math.min(win.width, screen.width);
+  const height = Math.min(win.height, screen.height);
+  const posX = Math.max(0, (screen.width - width) >> 1);
+  const posY = Math.max(0, (screen.height - height) >> 1);
+
+  // Port 0 => Chrome picks a free port and writes it to DevToolsActivePort.
+  const args = [
+    `--remote-debugging-port=0`,
+    `--user-data-dir=${userDataDir}`,
+    `--window-size=${width},${height}`,
+    `--window-position=${posX},${posY}`,
+    // Stealth: navigator.webdriver is gated behind this blink feature. Disabling
+    // the "AutomationControlled" feature makes navigator.webdriver === false,
+    // matching a normal browser. (Playwright historically left it true.)
+    `--disable-blink-features=AutomationControlled`,
+    // Quiet, non-suspicious startup — these match a fresh real profile, they are
+    // NOT the automation-only switches that change fingerprintable behaviour.
+    `--no-first-run`,
+    `--no-default-browser-check`,
+    `--disable-features=Translate,OptimizationHints`,
+    `--password-store=basic`,
+    `--homepage=about:blank`,
+    `about:blank`,
+  ];
+  if (opts.headless) {
+    // headless=new is the modern engine; still more detectable than headful,
+    // so it's opt-in. Default product mode is headful on a real display/Xvfb.
+    args.unshift("--headless=new");
+  }
+  // WebGL backend. Hardware (real GPU via ANGLE/EGL) is preferred — it gives an
+  // authentic, self-consistent fingerprint and works headless without Xvfb. We
+  // only fall back to SwiftShader (and then mask its vendor) when there's no GPU.
+  const gpu = resolveGpu(opts.gpu);
+  let maskWebgl = false;
+  if (gpu === "hardware") {
+    args.push("--use-gl=angle", "--use-angle=gl-egl");
+  } else if (gpu === "software") {
+    args.push("--use-gl=angle", "--use-angle=swiftshader", "--enable-unsafe-swiftshader");
+    maskWebgl = true; // SwiftShader's vendor is a server tell — hide it.
+  }
+  if (opts.proxy) args.push(`--proxy-server=${opts.proxy}`);
+  if (opts.extraArgs) args.push(...opts.extraArgs);
+
+  // Headful on a server: bring up our own Xvfb display if there isn't a real one.
+  const childEnv = { ...process.env };
+  let xvfbProc: ChildProcess | null = null;
+  const wantXvfb = opts.xvfb ?? (!opts.headless && !process.env.DISPLAY);
+  if (wantXvfb) {
+    const xvfb = await startXvfb(screen.width, screen.height);
+    if (xvfb) {
+      xvfbProc = xvfb.proc;
+      childEnv.DISPLAY = xvfb.display;
+    } else if (!process.env.DISPLAY) {
+      // No virtual display available — degrade gracefully to headless rather than
+      // failing the whole launch. Still uses the real GPU; just a higher headless
+      // heuristic score. Better a working browser than none.
+      args.unshift("--headless=new");
+    }
+  }
+
+  // detached => Chrome leads its own process group, so killGroup() can take down
+  // the whole renderer/gpu/zygote tree in one shot instead of orphaning it.
+  const child = spawn(chromePath, args, { stdio: ["ignore", "ignore", "pipe"], env: childEnv, detached: true });
+
+  const live: LiveBrowser = { child, xvfb: xvfbProc, userDataDir, ephemeral };
+  LIVE.add(live);
+  installReaper();
+  // If Chrome dies on its own (crash, external kill), drop it from the reaper set,
+  // tear down its Xvfb, and clean an ephemeral profile — no leak, no stale dir.
+  child.on("exit", () => {
+    LIVE.delete(live);
+    killGroup(xvfbProc);
+    if (ephemeral) { try { rmSync(userDataDir, { recursive: true, force: true }); } catch {} }
+  });
+
+  const portFile = join(userDataDir, "DevToolsActivePort");
+  const wsPath = await waitForPort(portFile, child);
+  const port = wsPath.port;
+
+  // Fetch the browser-level WebSocket endpoint from Chrome's HTTP side.
+  const res = await fetch(`http://127.0.0.1:${port}/json/version`);
+  const info = (await res.json()) as { webSocketDebuggerUrl: string };
+
+  const kill = () => {
+    LIVE.delete(live);
+    killGroup(child); // whole process group, not just the main pid
+    killGroup(xvfbProc);
+    if (ephemeral) {
+      try {
+        rmSync(userDataDir, { recursive: true, force: true });
+      } catch {}
+    }
+  };
+
+  return { webSocketDebuggerUrl: info.webSocketDebuggerUrl, process: child, userDataDir, maskWebgl, kill };
+}
+
+function waitForPort(portFile: string, child: ChildProcess): Promise<{ port: number }> {
+  return new Promise((resolve, reject) => {
+    let stderr = "";
+    child.stderr?.on("data", (d) => (stderr += d.toString()));
+    child.on("exit", (code) =>
+      reject(new Error(`Chrome exited early (code ${code}).\n${stderr.slice(-600)}`)),
+    );
+    const start = Date.now();
+    const tick = () => {
+      if (existsSync(portFile)) {
+        try {
+          const port = parseInt(readFileSync(portFile, "utf8").split("\n")[0]!.trim(), 10);
+          if (port > 0) return resolve({ port });
+        } catch {}
+      }
+      if (Date.now() - start > 15000) return reject(new Error("Chrome never opened a debug port"));
+      setTimeout(tick, 50);
+    };
+    tick();
+  });
+}