@mochi.js/core 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mochi.js/core",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Bun-native browser automation framework — relational fingerprint locking, zero-jitter injection, behavioral playback. The primary entry point.",
   "license": "MIT",
   "type": "module",
@@ -49,10 +49,11 @@
     "build": "echo 'no build step yet — Bun consumes src/ directly'"
   },
   "dependencies": {
-    "@mochi.js/behavioral": "workspace:*",
-    "@mochi.js/consistency": "workspace:*",
-    "@mochi.js/inject": "workspace:*",
-    "@mochi.js/net": "workspace:*"
+    "@mochi.js/behavioral": "^0.1.1",
+    "@mochi.js/challenges": "^0.2.0",
+    "@mochi.js/consistency": "^0.1.0",
+    "@mochi.js/inject": "^0.1.1",
+    "@mochi.js/net": "^0.1.1"
   },
   "publishConfig": {
     "access": "public"

package/src/__tests__/proxy-auth.test.ts

@@ -6,7 +6,7 @@
  * creds, empty password).
  *
  * `installProxyAuth`: drives a fake CDP router. Verifies:
- *   - `Fetch.enable` is sent with `handleAuthRequests: true, patterns: []`.
+ *   - `Fetch.enable` is sent with `handleAuthRequests: true, patterns: [{ urlPattern: "*" }]`.
  *   - `Fetch.authRequired` events trigger `Fetch.continueWithAuth` carrying
  *     the configured creds.
  *   - The defensive `Fetch.requestPaused` handler issues `Fetch.continueRequest`.
@@ -193,7 +193,7 @@ describe("installProxyAuth", () => {
     const handle = await installProxyAuth(f.router, { username: "u", password: "p" });
     const enable = f.written.find((c) => c.method === "Fetch.enable");
     expect(enable).toBeDefined();
-    expect(enable?.params).toEqual({ handleAuthRequests: true, patterns: [] });
+    expect(enable?.params).toEqual({ handleAuthRequests: true, patterns: [{ urlPattern: "*" }] });
     await handle.dispose();
     await f.router.close();
   });

package/src/index.ts

@@ -23,6 +23,7 @@ export {
 export { NotImplementedError } from "./errors";
 // Public surface — exported here so users only need `@mochi.js/core`.
 export {
+  type ChallengeLaunchOptions,
   type LaunchOptions,
   launch,
   type Mochi,

package/src/launch.ts

@@ -27,6 +27,38 @@ export interface ProxyConfig {
   password?: string;
 }
 
+/**
+ * Per-challenge convenience options surfaced via `LaunchOptions.challenges`.
+ *
+ * v0.2 implements `turnstile.autoClick` only. Other entries (hCaptcha,
+ * reCAPTCHA, etc.) are reserved for v0.3+ — see `@mochi.js/challenges`
+ * README.
+ *
+ * When `turnstile.autoClick: true`, the `Session` calls
+ * `installTurnstileAutoClick(page)` on every page returned by `newPage`.
+ * The handle is disposed automatically on page close.
+ *
+ * The full `TurnstileOptions` (timeout / humanize / onSolved / onEscalation)
+ * are passed through unchanged. See
+ * `@mochi.js/challenges#TurnstileOptions`.
+ */
+export interface ChallengeLaunchOptions {
+  turnstile?: {
+    /** When `true`, auto-install Turnstile detection + click on every newPage. */
+    autoClick?: boolean;
+    /** Override the per-widget post-click timeout (ms). Default 30_000. */
+    timeout?: number;
+    /** When `false`, use a fast non-humanized click path. Default `true`. */
+    humanize?: boolean;
+    /** Fired when a widget reports a token. */
+    onSolved?: (token: string) => void;
+    /** Fired on image-challenge / managed-variant / timeout. */
+    onEscalation?: (reason: "image-challenge" | "managed" | "timeout") => void;
+    /** Override the DOM-poll cadence (ms). Default 500. */
+    pollIntervalMs?: number;
+  };
+}
+
 /**
  * Options accepted by `mochi.launch`.
  *
@@ -75,6 +107,19 @@ export interface LaunchOptions {
    * Chromium); task 0040.
    */
   bypassInject?: boolean;
+  /**
+   * Convenience layer toggles for common bot-defense widgets. When
+   * `challenges.turnstile.autoClick` is `true`, every page returned by
+   * `Session.newPage` has `installTurnstileAutoClick(page, opts)` wired
+   * automatically — the Bezier+Fitts behavioral synth handles the click,
+   * an optional `onSolved` callback fires when the response token appears,
+   * and `onEscalation` fires on image-challenge / managed-variant / timeout.
+   *
+   * See `@mochi.js/challenges` for the full surface and the limits page
+   * for the v0.2 scope (visible-checkbox variants only — image/audio
+   * solving is v0.3+).
+   */
+  challenges?: ChallengeLaunchOptions;
 }
 
 /**
@@ -112,6 +157,7 @@ export async function launch(opts: LaunchOptions): Promise<Session> {
     // `@mochi.js/net` (wreq) accepts the full `user:pass@host` URL form.
     ...(normalized !== undefined ? { netProxy: normalized.netProxy } : {}),
     ...(normalized?.auth !== undefined ? { proxyAuth: normalized.auth } : {}),
+    ...(opts.challenges !== undefined ? { challenges: opts.challenges } : {}),
   });
   return session;
 }

package/src/page.ts

@@ -352,6 +352,55 @@ export class Page {
     return result.cookies;
   }
 
+  /**
+   * Install an additional main-world script that runs on every new document
+   * via `Page.addScriptToEvaluateOnNewDocument({ runImmediately: true,
+   * worldName: "" })`. Returns the CDP identifier so callers can later
+   * remove it via {@link removeInitScript}.
+   *
+   * `worldName: ""` is critical — any non-empty string creates an isolated
+   * world (PLAN.md §8.4) which is detectable. `runImmediately: true` ensures
+   * the script also runs against the current document if one already exists,
+   * not just on the next navigation.
+   *
+   * Use cases:
+   *   - The `@mochi.js/challenges` Turnstile detector (mounts a
+   *     `MutationObserver` + Symbol-keyed reader on `document` in the page's
+   *     main world, before any page script runs).
+   *   - Any future per-page convenience layer that needs main-world
+   *     mutation observation.
+   *
+   * The session-level inject payload is installed separately on every
+   * `newPage()` and is NOT routed through this method — convenience-layer
+   * scripts compose on top of it.
+   */
+  async addInitScript(source: string): Promise<string> {
+    this.assertOpen();
+    const result = await this.send<{ identifier: string }>(
+      "Page.addScriptToEvaluateOnNewDocument",
+      {
+        source,
+        runImmediately: true,
+        worldName: "",
+      },
+    );
+    return result.identifier;
+  }
+
+  /**
+   * Remove a previously-installed init script by its identifier (returned
+   * from {@link addInitScript}). Best-effort — silently ignores failures
+   * (e.g. the target was already closed).
+   */
+  async removeInitScript(identifier: string): Promise<void> {
+    if (this.closed) return;
+    try {
+      await this.send("Page.removeScriptToEvaluateOnNewDocument", { identifier });
+    } catch {
+      // Ignore — target might already be gone.
+    }
+  }
+
   /** Tear down the page. Does not close the session's other pages. */
   async close(): Promise<void> {
     if (this.closed) return;

package/src/proxy-auth.ts

@@ -12,9 +12,14 @@
  * stealth invariants.
  *
  * The CDP path is invariant-clean: enable `Fetch` with `handleAuthRequests`
- * and *empty* request patterns. Chromium fires `Fetch.authRequired` ONLY for
- * proxy auth challenges; regular request flow is unaffected (no
- * `Fetch.requestPaused` events when patterns is `[]`). We answer with
+ * 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
@@ -25,9 +30,11 @@
  * 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. The defensive `Fetch.requestPaused`
- * handler below is unreachable when `patterns: []` is set, but registered
- * as belt-and-braces in case a Chromium quirk triggers a pause.
+ * 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
  * ---------
@@ -146,17 +153,20 @@ export interface ProxyAuthHandle {
  * any protocol surface for sessions that don't need it.
  *
  * Behavior:
- *   - Sends `Fetch.enable { handleAuthRequests: true, patterns: [] }` once.
+ *   - Sends `Fetch.enable { handleAuthRequests: true, patterns: [{
+ *     urlPattern: "*" }] }` once.
  *   - On `Fetch.authRequired`, replies with `Fetch.continueWithAuth` and
  *     the parsed creds.
- *   - On `Fetch.requestPaused` (defensive — should never fire with empty
- *     patterns), forwards `Fetch.continueRequest` so we don't hang.
+ *   - 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).
  *
- * The empty `patterns` array is critical: any non-empty patterns turn
- * Chromium into an interception proxy for matching requests, which tanks
- * page perf and changes the network model. Empty patterns +
- * `handleAuthRequests: true` is the documented contract for "auth-only
- * interception".
+ * 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,
@@ -186,22 +196,29 @@ export async function installProxyAuth(
       });
   });
 
-  // Defensive — `patterns: []` means this event should never fire, but
-  // some Chromium builds may pause requests adjacent to auth challenges.
-  // If it ever fires, immediately continue so we don't hang the request.
+  // 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 (defensive) failed:", err);
+        console.warn("[mochi] Fetch.continueRequest failed:", err);
       }
     });
   });
 
   await router.send("Fetch.enable", {
     handleAuthRequests: true,
-    patterns: [],
+    patterns: [{ urlPattern: "*" }],
   });
 
   let disposed = false;

package/src/session.ts

@@ -12,6 +12,11 @@
  * @see PLAN.md §7
  */
 
+import {
+  type Disposable as ChallengeHandle,
+  installTurnstileAutoClick,
+  type TurnstileEscalationReason,
+} from "@mochi.js/challenges";
 import type { MatrixV1 } from "@mochi.js/consistency";
 import { buildPayload, type PayloadResult } from "@mochi.js/inject";
 import {
@@ -82,6 +87,23 @@ export interface SessionInit {
    * @internal
    */
   netAdapter?: NetAdapter;
+  /**
+   * Convenience layer toggles surfaced via
+   * `LaunchOptions.challenges`. When `challenges.turnstile.autoClick` is
+   * `true`, every page returned by `Session.newPage` has
+   * `installTurnstileAutoClick(page, opts)` wired automatically.
+   * See `@mochi.js/challenges`.
+   */
+  challenges?: {
+    turnstile?: {
+      autoClick?: boolean;
+      timeout?: number;
+      humanize?: boolean;
+      onSolved?: (token: string) => void;
+      onEscalation?: (reason: TurnstileEscalationReason) => void;
+      pollIntervalMs?: number;
+    };
+  };
 }
 
 /** Public Cookie shape (re-exported from page.ts). */
@@ -153,6 +175,15 @@ export class Session {
    * `Session.close`. Undefined when the session has no proxy auth.
    */
   private proxyAuthHandle: ProxyAuthHandle | undefined;
+  /**
+   * Snapshot of the `challenges` launch option, retained so
+   * {@link newPage} can install the per-page auto-click handler. Undefined
+   * when no challenge convenience layer is enabled. Each page gets its
+   * own {@link ChallengeHandle} tracked here for disposal on
+   * {@link close}.
+   */
+  private readonly challengesOpts: SessionInit["challenges"] | undefined;
+  private readonly challengeHandles: ChallengeHandle[] = [];
 
   constructor(init: SessionInit) {
     this.proc = init.proc;
@@ -161,6 +192,7 @@ export class Session {
     this.bypassInject = init.bypassInject === true;
     this.netProxy = init.netProxy;
     this.netAdapter = init.netAdapter ?? defaultNetAdapter;
+    this.challengesOpts = init.challenges;
     // Skip payload compilation entirely when bypassed — capture flows must
     // not pay the build cost AND must not see the matrix-derived bytes.
     this._payload = this.bypassInject ? null : buildPayload(init.matrix);
@@ -259,6 +291,21 @@ export class Session {
       },
     });
     this._pages.push(page);
+    // Wire the Turnstile auto-click convenience layer if the session was
+    // launched with `challenges.turnstile.autoClick: true`. The handle is
+    // tracked on the Session so it disposes on close (and the page-close
+    // path also cleans up via the disposable's idempotent dispose).
+    const ts = this.challengesOpts?.turnstile;
+    if (ts !== undefined && ts.autoClick === true) {
+      const tsOpts: Parameters<typeof installTurnstileAutoClick>[1] = {};
+      if (ts.timeout !== undefined) tsOpts.timeout = ts.timeout;
+      if (ts.humanize !== undefined) tsOpts.humanize = ts.humanize;
+      if (ts.onSolved !== undefined) tsOpts.onSolved = ts.onSolved;
+      if (ts.onEscalation !== undefined) tsOpts.onEscalation = ts.onEscalation;
+      if (ts.pollIntervalMs !== undefined) tsOpts.pollIntervalMs = ts.pollIntervalMs;
+      const handle = installTurnstileAutoClick(page, tsOpts);
+      this.challengeHandles.push(handle);
+    }
     return page;
   }
 
@@ -388,6 +435,16 @@ export class Session {
   async close(): Promise<void> {
     if (this.closed) return;
     this.closed = true;
+    // Dispose any challenge convenience-layer handles first so background
+    // pollers stop before pages tear down their CDP sessions.
+    for (const h of this.challengeHandles) {
+      try {
+        h.dispose();
+      } catch {
+        // ignore — best-effort
+      }
+    }
+    this.challengeHandles.length = 0;
     // Mark all pages as closed (they'll error on further use).
     for (const p of this._pages) {
       // close() is idempotent on Page.