@mochi.js/core 0.0.1 → 0.1.2

package/src/proc.ts

@@ -0,0 +1,213 @@
+/**
+ * Chromium process lifecycle.
+ *
+ * Owns spawn (Bun.spawn with pipe-mode FDs 3+4), stdio bookkeeping, graceful
+ * shutdown (SIGTERM → 2s grace → SIGKILL), and ephemeral user-data-dir cleanup.
+ *
+ * @see PLAN.md §8.5 / §8.6
+ */
+
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { PipeReader, PipeWriter } from "./cdp/transport";
+
+/**
+ * The chromium flags PLAN.md §8.6 mandates we always pass. Order does not
+ * matter; Chromium accepts late-arriving overrides for most flags but we
+ * never override these.
+ */
+export const DEFAULT_CHROMIUM_FLAGS: readonly string[] = [
+  "--remote-debugging-pipe",
+  "--no-default-browser-check",
+  "--no-first-run",
+  "--no-service-autorun",
+  "--password-store=basic",
+  "--use-mock-keychain",
+  "--disable-default-apps",
+  "--disable-component-update",
+  // Single comma-joined --disable-features flag (Chromium accepts comma list).
+  "--disable-features=Translate,OptimizationHints,MediaRouter,AcceptCHFrame,InterestFeedContentSuggestions,CalculateNativeWinOcclusion,IsolateOrigins,site-per-process",
+  "--enable-features=NetworkService,NetworkServiceInProcess",
+  "--disable-background-networking",
+  "--disable-sync",
+];
+
+const SIGTERM_GRACE_MS = 2000;
+
+/**
+ * Public knobs surfaced through `LaunchOptions`. Held here so `launch.ts` can
+ * pass a small immutable record into `spawnChromium` without leaking the full
+ * options shape.
+ */
+export interface SpawnConfig {
+  binary: string;
+  /** User-supplied extra flags appended after the defaults. Null to skip. */
+  extraArgs?: readonly string[];
+  /** Run headless via Chromium's modern `--headless=new` flag. */
+  headless: boolean;
+  /** Optional proxy server, e.g. "http://host:port" or "socks5://host:port". */
+  proxy?: string;
+}
+
+/**
+ * The handle returned by {@link spawnChromium}. Owns the user-data-dir, the
+ * subprocess, and the BunFile FD wrappers used by the CDP transport.
+ */
+export interface ChromiumProcess {
+  /** Absolute path to the ephemeral user-data-dir. Removed on close(). */
+  readonly userDataDir: string;
+  /** OS process id for diagnostics. */
+  readonly pid: number;
+  /** Resolves to the exit code once the child terminates (normal or signaled). */
+  readonly exited: Promise<number>;
+  /** Pipe reader for the CDP transport (browser → us; FD 4). */
+  readonly reader: PipeReader;
+  /** Pipe writer for the CDP transport (us → browser; FD 3). */
+  readonly writer: PipeWriter;
+  /**
+   * Graceful shutdown: SIGTERM, 2s grace, SIGKILL, then `rm -rf` the
+   * user-data-dir. Idempotent; safe to call multiple times.
+   */
+  close(): Promise<void>;
+}
+
+/**
+ * Spawn Chromium with `--remote-debugging-pipe` and the standard flag set.
+ *
+ * Pipe FD convention (Chromium CDP pipe spec, matches Puppeteer / Playwright):
+ *   - FD 3 in the *child* is the read end. The parent writes commands to it.
+ *   - FD 4 in the *child* is the write end. The parent reads responses from it.
+ *
+ * Note: task brief 0011 has the FD direction labels reversed; we follow
+ * Chromium's actual convention here so the protocol works. Either way Bun's
+ * `stdio: ["pipe", "pipe", "pipe", "pipe", "pipe"]` allocates two extra pipes
+ * and gives us back numeric FDs at `proc.stdio[3]` and `proc.stdio[4]`.
+ */
+export async function spawnChromium(cfg: SpawnConfig): Promise<ChromiumProcess> {
+  const userDataDir = await mkdtemp(join(tmpdir(), "mochi-"));
+
+  const args: string[] = [`--user-data-dir=${userDataDir}`, ...DEFAULT_CHROMIUM_FLAGS];
+  if (cfg.headless) {
+    // Modern headless mode (matches stable Chrome behavior more closely than
+    // legacy --headless). The `=new` is critical — old `--headless` is
+    // detectable.
+    args.push("--headless=new");
+  }
+  if (cfg.proxy !== undefined && cfg.proxy.length > 0) {
+    args.push(`--proxy-server=${cfg.proxy}`);
+  }
+  if (cfg.extraArgs !== undefined && cfg.extraArgs.length > 0) {
+    args.push(...cfg.extraArgs);
+  }
+  // Whitespace-separated extra args from the environment. Same effect as
+  // `LaunchOptions.args` but settable from outside the calling code — load-
+  // bearing for CI environments that need `--no-sandbox` (Linux user-namespace
+  // sandbox doesn't work in unprivileged containers / GH Actions runners) and
+  // for ad-hoc local debugging without touching test fixtures. Production code
+  // SHOULD NOT set this — `--no-sandbox` is a fingerprint leak in real-user
+  // contexts. PLAN.md §8.6 explicitly omits it from DEFAULT_CHROMIUM_FLAGS.
+  const envExtra = process.env.MOCHI_EXTRA_ARGS;
+  if (typeof envExtra === "string" && envExtra.trim().length > 0) {
+    args.push(...envExtra.trim().split(/\s+/));
+  }
+
+  const proc = Bun.spawn([cfg.binary, ...args], {
+    // stdin, stdout, stderr, then two extra pipes for CDP framing.
+    stdio: ["pipe", "pipe", "pipe", "pipe", "pipe"],
+    // Chromium needs a real CWD for crash dumps etc; user-data-dir is fine.
+    cwd: userDataDir,
+  });
+
+  const writeFd = proc.stdio[3];
+  const readFd = proc.stdio[4];
+  if (typeof writeFd !== "number" || typeof readFd !== "number") {
+    proc.kill();
+    await rm(userDataDir, { recursive: true, force: true }).catch(() => {});
+    throw new Error(
+      "[mochi] Bun.spawn did not return numeric FDs at stdio[3]/stdio[4]; cannot establish CDP pipe.",
+    );
+  }
+
+  // Drain stderr so Chromium doesn't block writing diagnostics. We don't read
+  // it (yet); piping to /dev/null keeps the buffer empty.
+  void drainToVoid(proc.stderr);
+  void drainToVoid(proc.stdout);
+
+  // Build PipeReader/PipeWriter wrappers around the raw FDs.
+  const writer: PipeWriter = (() => {
+    const sink = Bun.file(writeFd).writer();
+    return {
+      write: (chunk) => sink.write(chunk),
+      flush: () => sink.flush(),
+      end: () => sink.end(),
+    };
+  })();
+
+  const reader: PipeReader = {
+    getReader: () => Bun.file(readFd).stream().getReader(),
+  };
+
+  let closing = false;
+  const close = async (): Promise<void> => {
+    if (closing) {
+      // Wait until the in-flight close finishes.
+      await proc.exited.catch(() => 0);
+      return;
+    }
+    closing = true;
+    // Try to flush+end the writer first so Chromium's read side sees EOF.
+    try {
+      await writer.end?.();
+    } catch {
+      // ignore
+    }
+    // SIGTERM, then 2s grace, then SIGKILL.
+    try {
+      proc.kill("SIGTERM");
+    } catch {
+      // process may have already exited
+    }
+    const timer = setTimeout(() => {
+      try {
+        proc.kill("SIGKILL");
+      } catch {
+        // ignore
+      }
+    }, SIGTERM_GRACE_MS);
+    try {
+      await proc.exited;
+    } finally {
+      clearTimeout(timer);
+    }
+    // Best-effort user-data-dir cleanup. Failures are non-fatal but logged.
+    await rm(userDataDir, { recursive: true, force: true }).catch((err: unknown) => {
+      console.warn(`[mochi] failed to remove user-data-dir ${userDataDir}:`, err);
+    });
+  };
+
+  return {
+    userDataDir,
+    pid: proc.pid,
+    exited: proc.exited,
+    reader,
+    writer,
+    close,
+  };
+}
+
+/** Read-and-discard a ReadableStream so Chromium's pipe buffers don't fill. */
+async function drainToVoid(stream: ReadableStream<Uint8Array> | null): Promise<void> {
+  if (stream === null) return;
+  const reader = stream.getReader();
+  try {
+    while (true) {
+      const { done } = await reader.read();
+      if (done) return;
+    }
+  } catch {
+    // ignore — stream errored or was cancelled
+  } finally {
+    reader.releaseLock();
+  }
+}

package/src/proxy-auth.ts

@@ -0,0 +1,252 @@
+/**
+ * Proxy authentication via CDP `Fetch.authRequired`.
+ *
+ * Background
+ * ----------
+ * Chromium's `--proxy-server=` flag accepts the address but rejects inline
+ * credentials in the URL — `--proxy-server=http://user:pass@host:8080` is
+ * silently stripped. The historical "proxy-auth-extension" workaround ships
+ * a tiny chrome-extension that subscribes to `chrome.webRequest.onAuthRequired`,
+ * but `--load-extension` is itself a fingerprint leak (chrome.runtime
+ * weirdness, observable extension ids) and so is forbidden by mochi's
+ * stealth invariants.
+ *
+ * The CDP path is invariant-clean: enable `Fetch` with `handleAuthRequests`
+ * AND a wildcard pattern. Chromium rejects `patterns: []` when
+ * `handleAuthRequests: true` (`-32602 Can't specify empty patterns with
+ * handleAuth set`, verified on CfT linux ~2026-05) — the original 0160
+ * design assumed empty patterns would only fire `Fetch.authRequired`
+ * events, but modern Chromium requires at least one URL pattern when auth
+ * handling is on. We use `[{ urlPattern: "*" }]` and forward every paused
+ * request immediately via `Fetch.continueRequest`. The auth challenges
+ * separately fire `Fetch.authRequired`; we answer those with
+ * `Fetch.continueWithAuth` carrying the parsed credentials.
+ *
+ * PLAN.md §8.2 invariant check
+ * ----------------------------
+ * `Fetch.enable` is NOT on the forbidden list. Only `Runtime.enable`
+ * (leaks execution-context-created events to page-observable side
+ * channels) and `Page.createIsolatedWorld` (creates a fingerprintable
+ * isolated world) are forbidden. `Fetch.enable` operates at the network
+ * layer below page script — it does not produce execution-context-creation
+ * events, does not surface a `chrome.devtools` global, and is not
+ * detectable from page JavaScript. With `patterns: [{urlPattern: "*"}]`
+ * every request pauses for one CDP round-trip before continuing — that's
+ * a measurable but bounded overhead (sub-ms per request on modern
+ * hardware) and only active on sessions with proxy auth credentials
+ * (the function early-returns when `auth` is undefined).
+ *
+ * Protocols
+ * ---------
+ * Chromium surfaces both HTTP and SOCKS5 auth challenges through the same
+ * `Fetch.authRequired` event. SOCKS5 user/pass auth happens at the SOCKS
+ * handshake (before any HTTP request) but Chromium wraps it as an
+ * `authRequired` for the first request through the proxy, so the same
+ * handler covers both.
+ *
+ * @see PLAN.md §8.2 / §10
+ * @see tasks/0160-proxy-auth-and-ci-fix.md
+ */
+
+import type { MessageRouter, Unsubscribe } from "./cdp/router";
+
+/** Parsed proxy URL — what `parseProxyUrl` returns. */
+export interface ParsedProxy {
+  /**
+   * The auth-stripped server URL safe to pass to Chromium's
+   * `--proxy-server=` flag. Format: `<protocol>//<host>:<port>`.
+   */
+  server: string;
+  /**
+   * Decoded credentials, present only when the input URL carried a
+   * `user[:pass]@` segment. `password` is `""` (empty string) when the
+   * URL had a username but no password (`http://user@host:8080`).
+   */
+  auth?: { username: string; password: string };
+  /** Lowercased protocol (`http`, `https`, `socks5`, `socks4`). */
+  protocol: "http" | "https" | "socks5" | "socks4";
+}
+
+/** Default ports used when the input URL omits one. */
+const DEFAULT_PORTS: Record<string, string> = {
+  http: "80",
+  https: "443",
+  socks5: "1080",
+  socks4: "1080",
+};
+
+/**
+ * Parse a proxy URL string into `{ server, auth?, protocol }`.
+ *
+ * Handles:
+ *   - `http://user:pass@host:port`      → auth + server
+ *   - `socks5://user@host:1080`         → auth.password = ""
+ *   - `http://host:8080`                → no auth
+ *   - `http://user%40d:p%40ss@host:80`  → percent-decoded credentials
+ *   - `http://user:pass@[::1]:8080`     → IPv6 hosts (URL parser handles)
+ *   - `http://host`                     → port defaults per protocol
+ *
+ * Implementation uses `new URL()` so percent-decoding and IPv6 host
+ * bracketing are handled natively.
+ */
+export function parseProxyUrl(input: string): ParsedProxy {
+  let url: URL;
+  try {
+    url = new URL(input);
+  } catch (err) {
+    throw new Error(
+      `[mochi] invalid proxy URL ${JSON.stringify(input)}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  const rawProto = url.protocol.replace(/:$/, "").toLowerCase();
+  if (
+    rawProto !== "http" &&
+    rawProto !== "https" &&
+    rawProto !== "socks5" &&
+    rawProto !== "socks4"
+  ) {
+    throw new Error(
+      `[mochi] unsupported proxy protocol ${JSON.stringify(rawProto)} — supported: http, https, socks5, socks4`,
+    );
+  }
+  const protocol = rawProto;
+  // `URL.hostname` may keep or strip IPv6 brackets depending on the
+  // runtime — normalize to a single `[…]`-bracketed form so we can format
+  // the server URL deterministically.
+  const rawHost = url.hostname;
+  const stripped =
+    rawHost.startsWith("[") && rawHost.endsWith("]") ? rawHost.slice(1, -1) : rawHost;
+  const isIpv6 = stripped.includes(":");
+  const host = isIpv6 ? `[${stripped}]` : stripped;
+  const port = url.port.length > 0 ? url.port : DEFAULT_PORTS[protocol];
+  if (host.length === 0) {
+    throw new Error(`[mochi] proxy URL ${JSON.stringify(input)} is missing a host`);
+  }
+  const server = `${protocol}://${host}:${port}`;
+
+  // `URL.username`/`URL.password` are already percent-decoded.
+  if (url.username.length > 0) {
+    return {
+      server,
+      auth: {
+        username: decodeURIComponent(url.username),
+        password: url.password.length > 0 ? decodeURIComponent(url.password) : "",
+      },
+      protocol,
+    };
+  }
+  return { server, protocol };
+}
+
+/**
+ * Result of {@link installProxyAuth}: an unsubscriber that removes the
+ * router listeners and disables the Fetch domain. Idempotent.
+ */
+export interface ProxyAuthHandle {
+  /** Tear down the listeners + send `Fetch.disable`. Idempotent. */
+  dispose(): Promise<void>;
+}
+
+/**
+ * Wire proxy-auth handling into a {@link MessageRouter}. No-op when
+ * `auth` is undefined — saves the `Fetch.enable` round-trip and avoids
+ * any protocol surface for sessions that don't need it.
+ *
+ * Behavior:
+ *   - Sends `Fetch.enable { handleAuthRequests: true, patterns: [{
+ *     urlPattern: "*" }] }` once.
+ *   - On `Fetch.authRequired`, replies with `Fetch.continueWithAuth` and
+ *     the parsed creds.
+ *   - On `Fetch.requestPaused`, forwards `Fetch.continueRequest`
+ *     immediately so the network model stays unchanged (every request
+ *     still flows; we just take one CDP round-trip to wave it through).
+ *
+ * Why wildcard patterns instead of empty: modern Chromium (CfT linux
+ * ~2026-05) rejects `patterns: []` when `handleAuthRequests: true` is set
+ * with `-32602 Can't specify empty patterns with handleAuth set`. The
+ * wildcard plus an immediate-continue handler is the equivalent of
+ * "auth-only interception" with one extra round-trip per request — only
+ * active on proxy-authed sessions.
+ */
+export async function installProxyAuth(
+  router: MessageRouter,
+  auth: { username: string; password: string },
+): Promise<ProxyAuthHandle> {
+  // Subscribe FIRST so we don't miss the very first authRequired event the
+  // browser fires after Fetch.enable.
+  const offAuth: Unsubscribe = router.on("Fetch.authRequired", (params) => {
+    const requestId = (params as { requestId?: string } | null)?.requestId;
+    if (typeof requestId !== "string") return;
+    // Fire-and-forget — failures here are non-fatal (the request will
+    // simply 407 and the page-level fetch will see it). We log on
+    // unexpected errors so users can diagnose creds issues.
+    router
+      .send("Fetch.continueWithAuth", {
+        requestId,
+        authChallengeResponse: {
+          response: "ProvideCredentials",
+          username: auth.username,
+          password: auth.password,
+        },
+      })
+      .catch((err: unknown) => {
+        if (!isClosedError(err)) {
+          console.warn("[mochi] Fetch.continueWithAuth failed:", err);
+        }
+      });
+  });
+
+  // Pattern is REQUIRED with handleAuthRequests: true. Modern Chromium
+  // rejects an empty `patterns` array with `-32602 Can't specify empty
+  // patterns with handleAuth set` (verified on CfT linux ~2026-05). Use
+  // a wildcard pattern so every request paus es, then immediately
+  // forward in the requestPaused handler below — that gets us auth
+  // challenge interception without altering the user-visible network
+  // model. The per-request CDP round-trip is real overhead but only
+  // active when the session has proxy auth credentials (this whole
+  // function early-returns when `auth` is undefined), so non-proxied
+  // sessions pay zero cost.
+  const offPaused: Unsubscribe = router.on("Fetch.requestPaused", (params) => {
+    const requestId = (params as { requestId?: string } | null)?.requestId;
+    if (typeof requestId !== "string") return;
+    router.send("Fetch.continueRequest", { requestId }).catch((err: unknown) => {
+      if (!isClosedError(err)) {
+        console.warn("[mochi] Fetch.continueRequest failed:", err);
+      }
+    });
+  });
+
+  await router.send("Fetch.enable", {
+    handleAuthRequests: true,
+    patterns: [{ urlPattern: "*" }],
+  });
+
+  let disposed = false;
+  return {
+    async dispose(): Promise<void> {
+      if (disposed) return;
+      disposed = true;
+      offAuth();
+      offPaused();
+      try {
+        await router.send("Fetch.disable");
+      } catch (err) {
+        // Closed-pipe failures are expected during session teardown.
+        if (!isClosedError(err)) {
+          console.warn("[mochi] Fetch.disable failed:", err);
+        }
+      }
+    },
+  };
+}
+
+/** True when an error reflects the transport already being closed. */
+function isClosedError(err: unknown): boolean {
+  if (err instanceof Error) {
+    return (
+      err.name === "BrowserCrashedError" ||
+      /transport already closed|pipe closed|browser process exited/i.test(err.message)
+    );
+  }
+  return false;
+}