@mochi.js/core 0.1.0 → 0.2.2

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,27 @@ 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[] = [];
+  /**
+   * Cache of resolved execution-context ids for worker-style targets,
+   * keyed by the worker session id. Populated by
+   * {@link extractWorkerExecutionContextId} on first attach and reused by
+   * any later worker CDP op that needs an `executionContextId`. Patchright
+   * keeps this on a per-target `CRExecutionContext`; mochi keeps the
+   * Session-local map until we grow a real worker-target abstraction.
+   *
+   * @see crServiceWorkerPatch.ts:32-43, crPagePatch.ts:404-417
+   * @internal
+   */
+  private readonly workerExecutionContextIds = new Map<string, number>();
 
   constructor(init: SessionInit) {
     this.proc = init.proc;
@@ -161,6 +204,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);
@@ -222,6 +266,30 @@ export class Session {
     // (only Runtime.enable is forbidden). We enable here so subsequent
     // addScriptToEvaluateOnNewDocument is honoured by the page domain.
     await this.router.send("Page.enable", undefined, { sessionId: attached.sessionId });
+    // Task 0255: defensive UA override at the network layer.
+    //
+    // The inject payload (Page.addScriptToEvaluateOnNewDocument) spoofs
+    // `navigator.userAgent` in the JS surface, but `Network.requestWillBeSent`
+    // events (and the request line itself) carry the BARE browser UA — which
+    // under `--headless=new` still contains the substring "HeadlessChrome".
+    // The inject can never reach those bytes because they're emitted before
+    // any document script runs.
+    //
+    // `Network.setUserAgentOverride` is a per-target setter that does NOT
+    // require `Network.enable` (it only stores override state); §8.2's ban
+    // on `Network.enable` is therefore unaffected. Sent immediately after
+    // attach and before any navigation so the very first request the page
+    // issues already carries the matrix UA.
+    //
+    // Skipped under `bypassInject:true` (PLAN.md §12.1) — capture flows must
+    // record the bare browser fingerprint, including its raw UA.
+    if (!this.bypassInject) {
+      await this.router.send(
+        "Network.setUserAgentOverride",
+        { userAgent: this.profile.userAgent },
+        { sessionId: attached.sessionId },
+      );
+    }
     // PLAN.md §12.1 / task 0040 — capture flow short-circuits inject so the
     // browser reports its bare fingerprint. Otherwise install the payload
     // main-world via §8.4. worldName MUST be the empty string.
@@ -259,6 +327,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 +471,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.
@@ -500,18 +593,35 @@ export class Session {
 
   /**
    * Inject the payload into a freshly-attached target if it's a worker-
-   * style target (dedicated worker, shared worker, service worker, audio
-   * worklet, etc.), then resume it.
+   * style target (dedicated worker, shared worker, audio worklet — service
+   * workers go through the same path; see notes below), then resume it.
    *
    * Worker targets do NOT support `Page.addScriptToEvaluateOnNewDocument`
-   * (no Page domain). PLAN.md §8.4 calls out that we use `Runtime.evaluate`
-   * against the paused worker session before issuing
-   * `Runtime.runIfWaitingForDebugger`. The §8.2 forbidden-method assertion
-   * does NOT trip because we never send `Runtime.enable` — only
-   * `Runtime.evaluate` against an already-paused worker target.
+   * (no Page domain). PLAN.md §8.4 calls out that the worker target accepts
+   * `Runtime.evaluate` even though `Runtime.enable` is forbidden by §8.2.
+   *
+   * The Patchright-cited bootstrap (task 0254 — `crServiceWorkerPatch.ts:32-43`,
+   * `crPagePatch.ts:404-417`) tightens the inject race window:
+   *   1. `Runtime.evaluate("globalThis", { serialization: "idOnly" })` —
+   *      returns a `RemoteObject` whose `objectId` carries the worker's
+   *      execution-context id. `serialization: "idOnly"` skips the value
+   *      preview round-trip we don't need.
+   *   2. Parse `objectId.split(".")[1]` for the contextId. The wire format
+   *      is `"<runtimeAgentId>.<contextId>.<remoteObjectId>"`; we validate
+   *      the split and fail loudly if Chromium has moved the goalposts.
+   *   3. Inject the payload via `Runtime.callFunctionOn({ functionDeclaration,
+   *      executionContextId, returnByValue: true })`. This binds the call
+   *      to the worker's own context rather than relying on
+   *      `Runtime.evaluate`'s implicit context resolution, which is the
+   *      coarser pattern v0.1.x used.
+   *   4. `Runtime.runIfWaitingForDebugger` to resume the target.
    *
-   * Caveat: worker injection has a smaller stealth ceiling than main-
-   * world Page injection. Documented in `docs/limits.md`.
+   * We never send `Runtime.enable` — that's the whole point of extracting
+   * the contextId via the idOnly trick instead of waiting for an
+   * `Runtime.executionContextCreated` event.
+   *
+   * Caveat: worker injection has a smaller stealth ceiling than main-world
+   * Page injection. Documented in `docs/limits.md`.
    */
   private async handleAttachedTarget(
     ev: AttachedToTargetEvent,
@@ -527,12 +637,20 @@ export class Session {
     // PLAN.md §12.1 / task 0040 — capture flow skips worker injection too.
     if (isWorkerLike && !this.bypassInject && this._payload !== null) {
       try {
+        const executionContextId = await this.extractWorkerExecutionContextId(childSessionId);
+        this.workerExecutionContextIds.set(childSessionId, executionContextId);
+        // `Runtime.callFunctionOn` requires either an `objectId` OR an
+        // `executionContextId`. We use the latter — patchright's pattern —
+        // so the call binds to the worker's own context, not whatever
+        // `Runtime.evaluate` happens to resolve. The payload IIFE is wrapped
+        // as a function declaration so `callFunctionOn` accepts it.
         await this.router.send(
-          "Runtime.evaluate",
+          "Runtime.callFunctionOn",
           {
-            expression: this._payload.code,
+            functionDeclaration: `function() { ${this._payload.code} }`,
+            executionContextId,
+            returnByValue: true,
             awaitPromise: false,
-            returnByValue: false,
             // includeCommandLineAPI must remain false (§8.2).
           },
           { sessionId: childSessionId },
@@ -560,6 +678,73 @@ export class Session {
     }
   }
 
+  /**
+   * Resolve the worker target's execution-context id WITHOUT
+   * `Runtime.enable` — patchright's trick.
+   *
+   * Sends `Runtime.evaluate("globalThis", { serialization: "idOnly" })`
+   * against the paused worker session. The returned `RemoteObject.objectId`
+   * has the on-the-wire shape `"<runtimeAgentId>.<contextId>.<localId>"`
+   * (Chromium >= v131; verified against patchright's parser). We extract
+   * `split(".")[1]` and assert it's a positive integer.
+   *
+   * Throws with a precise diagnostic if Chromium changes the format —
+   * silent fallback would mask a real wire-protocol shift, which we want
+   * to catch in CI rather than ship as a degraded inject path.
+   *
+   * @see crServiceWorkerPatch.ts:32-43
+   */
+  private async extractWorkerExecutionContextId(childSessionId: string): Promise<number> {
+    const evalRes = await this.router.send<{ result: { objectId?: string; type?: string } }>(
+      "Runtime.evaluate",
+      {
+        expression: "globalThis",
+        // idOnly skips full value serialisation — we want the objectId
+        // alone. Supported on Chromium >= v124 (chrome-for-testing v131+
+        // in the mochi profile floor).
+        serialization: "idOnly",
+        // includeCommandLineAPI must remain false (§8.2).
+      },
+      { sessionId: childSessionId },
+    );
+    const objectId = evalRes.result.objectId;
+    if (typeof objectId !== "string" || objectId.length === 0) {
+      throw new Error(
+        `[mochi] worker idOnly bootstrap: Runtime.evaluate("globalThis") returned no objectId (got ${JSON.stringify(evalRes.result)})`,
+      );
+    }
+    const parts = objectId.split(".");
+    // Format: "<runtimeAgentId>.<contextId>.<localId>" — patchright also
+    // pulls index [1]. Refuse to guess if the segment count shifts.
+    if (parts.length < 2) {
+      throw new Error(
+        `[mochi] worker idOnly bootstrap: unexpected objectId shape "${objectId}" (expected dotted segments)`,
+      );
+    }
+    const ctxRaw = parts[1];
+    if (ctxRaw === undefined || ctxRaw.length === 0) {
+      throw new Error(
+        `[mochi] worker idOnly bootstrap: objectId "${objectId}" has empty contextId segment`,
+      );
+    }
+    const contextId = Number.parseInt(ctxRaw, 10);
+    if (!Number.isInteger(contextId) || contextId <= 0 || String(contextId) !== ctxRaw) {
+      throw new Error(
+        `[mochi] worker idOnly bootstrap: contextId segment "${ctxRaw}" of objectId "${objectId}" is not a positive integer`,
+      );
+    }
+    return contextId;
+  }
+
+  /**
+   * Snapshot of the worker → executionContextId cache. Test-only.
+   *
+   * @internal
+   */
+  _internalWorkerExecutionContextIds(): ReadonlyMap<string, number> {
+    return new Map(this.workerExecutionContextIds);
+  }
+
   private installCrashGuard(): void {
     // If Chromium dies unexpectedly, we want to mark the session closed so
     // pending and future calls reject cleanly.