@mochi.js/core 0.1.2 → 0.3.0

package/src/session.ts

@@ -184,6 +184,18 @@ export class Session {
    */
   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;
@@ -254,6 +266,73 @@ 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 0262: timezone spoof via CDP `Emulation.setTimezoneOverride`.
+    //
+    // Drives BOTH `Intl.DateTimeFormat().resolvedOptions().timeZone` AND
+    // `Date.getTimezoneOffset()` because Chromium's V8 reads from the same
+    // internal timezone source. We do NOT manually rewrite
+    // `Date.prototype.getTimezoneOffset` in inject — that's detectable via
+    // prototype-shape checks. The CDP override is the canonical
+    // mechanism.
+    //
+    // Per the CDP docs (`tot/Emulation/#method-setTimezoneOverride`),
+    // this method does NOT require `Emulation.enable` (it stores override
+    // state directly on the target's `EmulationAgent`). §8.2's bans are
+    // unaffected. Sent per-target before any navigation so the very first
+    // document JS already sees the spoofed zone.
+    //
+    // The empty-string sentinel in the protocol means "clear override";
+    // we never send empty here because that would defeat the purpose.
+    //
+    // Skipped under `bypassInject:true` (PLAN.md §12.1) — capture flows
+    // record the bare browser timezone.
+    if (!this.bypassInject) {
+      await this.router.send(
+        "Emulation.setTimezoneOverride",
+        { timezoneId: this.profile.timezone },
+        { sessionId: attached.sessionId },
+      );
+    }
+    // Task 0255: defensive UA override at the network layer.
+    //
+    // The inject payload (Page.addScriptToEvaluateOnNewDocument) spoofs
+    // `navigator.userAgent` and `navigator.userAgentData` 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" — AND the bare
+    // `Sec-CH-UA*` request-header set. The inject can never reach those
+    // bytes because they're emitted before any document script runs.
+    //
+    // 0255 plumbed `userAgent`. 0261 closes the cross-layer leak that left
+    // open: without `userAgentMetadata`, the request `Sec-CH-UA*` headers
+    // carry CfT defaults instead of the matrix, so a fingerprinter doing
+    // `getHighEntropyValues()` and comparing against the request headers
+    // sees a mismatch (direct PLAN.md I-5 violation). The metadata struct
+    // is the CDP-canonical UA-CH descriptor; Chromium derives every
+    // `Sec-CH-UA*` header from it. Both surfaces (this network call and
+    // the inject's `client-hints.ts` getHighEntropyValues) read the SAME
+    // matrix fields, so they cannot drift.
+    //
+    // `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, with or without the
+    // metadata payload. Sent immediately after attach and before any
+    // navigation so the very first request the page issues already carries
+    // the matrix UA + UA-CH headers.
+    //
+    // Skipped under `bypassInject:true` (PLAN.md §12.1) — capture flows must
+    // record the bare browser fingerprint, including its raw UA AND raw
+    // `Sec-CH-UA*` headers.
+    if (!this.bypassInject) {
+      await this.router.send(
+        "Network.setUserAgentOverride",
+        {
+          userAgent: this.profile.userAgent,
+          userAgentMetadata: buildUserAgentMetadata(this.profile),
+        },
+        { 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.
@@ -557,18 +636,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,
@@ -584,12 +680,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 },
@@ -617,6 +721,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.
@@ -636,3 +807,178 @@ export class Session {
     }
   }
 }
+
+// ---- UA-CH metadata helpers (task 0261) -------------------------------------
+
+/**
+ * Single brand entry as accepted by `Network.setUserAgentOverride`'s
+ * `userAgentMetadata.brands` / `fullVersionList`.
+ *
+ * @internal
+ */
+interface UaMetadataBrand {
+  brand: string;
+  version: string;
+}
+
+/**
+ * Strip surrounding ASCII double-quotes (the on-the-wire form for several
+ * `Sec-CH-UA*` headers — `'"macOS"'`, `'"14.0.0"'`, `'"arm"'`, `'"64"'`).
+ * The CDP `userAgentMetadata` enums consume the unquoted form.
+ */
+function unquoteUaCh(s: string): string {
+  if (s.length >= 2 && s.startsWith('"') && s.endsWith('"')) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+/**
+ * Parse a Sec-CH-UA-style header value
+ * (`'"Brand A";v="123", "Not.A/Brand";v="8", "Brand B";v="456"'`) into the
+ * `[{brand, version}, ...]` shape `userAgentMetadata.brands` expects.
+ *
+ * Hand-written state machine — Sec-CH-UA is RFC 8941 Structured Headers
+ * with quoted strings, so a regex split on `,` would break on
+ * `"Brand,with,commas"`. Mirrors `parseSecChUa` in
+ * `@mochi.js/inject/src/modules/client-hints.ts` byte-for-byte: same
+ * source field (`matrix.uaCh["sec-ch-ua"]`), same output shape, so the
+ * network surface and the JS surface cannot drift.
+ *
+ * @internal
+ */
+function parseSecChUaBrandList(s: string): UaMetadataBrand[] {
+  const out: UaMetadataBrand[] = [];
+  // Split on `,` outside quoted segments. `depth` toggles inside `"…"`.
+  const parts: string[] = [];
+  let depth = 0;
+  let cur = "";
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i] as string;
+    if (c === '"') {
+      depth = depth === 0 ? 1 : 0;
+      cur += c;
+    } else if (c === "," && depth === 0) {
+      parts.push(cur);
+      cur = "";
+    } else {
+      cur += c;
+    }
+  }
+  if (cur.length > 0) parts.push(cur);
+  for (const raw of parts) {
+    const piece = raw.trim();
+    if (piece.length === 0) continue;
+    const semi = piece.indexOf(";");
+    if (semi === -1) {
+      out.push({ brand: unquoteUaCh(piece), version: "" });
+      continue;
+    }
+    const brandPart = piece.slice(0, semi).trim();
+    const rest = piece.slice(semi + 1).trim();
+    let version = "";
+    if (rest.startsWith("v=")) {
+      version = unquoteUaCh(rest.slice(2).trim());
+    }
+    out.push({ brand: unquoteUaCh(brandPart), version });
+  }
+  return out;
+}
+
+/**
+ * Parse the JSON-encoded `uaCh.ua-full-version-list` (R-031) into the
+ * `[{brand, version}]` shape. Falls through to the brand-list parser if
+ * the matrix doesn't carry the field — every shipped profile does, so
+ * the fallback is purely defensive.
+ *
+ * @internal
+ */
+function parseFullVersionList(matrix: MatrixV1): UaMetadataBrand[] {
+  const raw = matrix.uaCh["ua-full-version-list"];
+  if (typeof raw === "string" && raw.length > 0) {
+    try {
+      const parsed = JSON.parse(raw) as unknown;
+      if (Array.isArray(parsed)) {
+        return parsed
+          .filter(
+            (e): e is UaMetadataBrand =>
+              typeof e === "object" &&
+              e !== null &&
+              typeof (e as { brand?: unknown }).brand === "string" &&
+              typeof (e as { version?: unknown }).version === "string",
+          )
+          .map((e) => ({ brand: e.brand, version: e.version }));
+      }
+    } catch {
+      // Fall through.
+    }
+  }
+  // Fallback: reuse the brand-list majors. Matches the inject side's same
+  // fallback in client-hints.ts.
+  const secChUa = matrix.uaCh["sec-ch-ua"] ?? "";
+  return parseSecChUaBrandList(secChUa);
+}
+
+/**
+ * Build the `userAgentMetadata` parameter for `Network.setUserAgentOverride`
+ * from a derived MatrixV1. Single source of truth = the matrix; the inject
+ * `client-hints.ts` module reads the same fields, so the JS-API surface
+ * (`navigator.userAgentData.getHighEntropyValues`) and the request-header
+ * surface (`Sec-CH-UA*`) cannot drift.
+ *
+ * Field shape per CDP spec:
+ *   - `brands`             — `[{brand, version}]`, brand-list majors.
+ *   - `fullVersionList`    — `[{brand, version}]`, tip-locked full versions.
+ *   - `fullVersion`        — string, branded entry's version (R-046).
+ *   - `platform`           — unquoted Sec-CH-UA-Platform value.
+ *   - `platformVersion`    — unquoted Sec-CH-UA-Platform-Version.
+ *   - `architecture`       — `"arm" | "x86" | ""` (R-042 unquoted).
+ *   - `model`              — free-form string, empty for desktop (R-045).
+ *   - `mobile`             — boolean (R-044 → `?1` mapped to true).
+ *   - `bitness`            — STRING `"64" | "32" | ""` (R-043 unquoted),
+ *                            never numeric.
+ *   - `wow64`              — boolean; matrix doesn't model nested-WOW64,
+ *                            we always emit false (task 0261 out-of-scope).
+ *
+ * @internal
+ */
+export function buildUserAgentMetadata(matrix: MatrixV1): {
+  brands: UaMetadataBrand[];
+  fullVersionList: UaMetadataBrand[];
+  fullVersion: string;
+  platform: string;
+  platformVersion: string;
+  architecture: string;
+  model: string;
+  mobile: boolean;
+  bitness: string;
+  wow64: boolean;
+} {
+  const ua = matrix.uaCh;
+  const brandsRaw = ua["sec-ch-ua"] ?? "";
+  const brands = parseSecChUaBrandList(brandsRaw);
+  const fullVersionList = parseFullVersionList(matrix);
+  const fullVersion =
+    typeof ua["ua-full-version"] === "string" && ua["ua-full-version"].length > 0
+      ? ua["ua-full-version"]
+      : (fullVersionList[0]?.version ?? "");
+  const platform = unquoteUaCh(ua["sec-ch-ua-platform"] ?? "");
+  const platformVersion = unquoteUaCh(ua["sec-ch-ua-platform-version"] ?? "");
+  const architecture = unquoteUaCh(ua["sec-ch-ua-arch"] ?? "");
+  const bitness = unquoteUaCh(ua["sec-ch-ua-bitness"] ?? "");
+  const model = unquoteUaCh(ua["sec-ch-ua-model"] ?? "");
+  // Sec-CH-UA-Mobile wire form is "?0" / "?1" (Structured-Headers boolean).
+  const mobile = ua["sec-ch-ua-mobile"] === "?1";
+  return {
+    brands,
+    fullVersionList,
+    fullVersion,
+    platform,
+    platformVersion,
+    architecture,
+    model,
+    mobile,
+    bitness,
+    wow64: false,
+  };
+}