@mochi.js/core 0.2.2 → 0.3.0

package/src/launch.ts

@@ -12,6 +12,8 @@
 
 import { deriveMatrix, type ProfileV1 } from "@mochi.js/consistency";
 import { resolveBinary } from "./binary";
+import { type GeoConsistencyMode, reconcileGeoConsistency } from "./geo-consistency";
+import { probeExitGeo } from "./geo-probe";
 import { spawnChromium } from "./proc";
 import { parseProxyUrl } from "./proxy-auth";
 import { Session } from "./session";
@@ -151,6 +153,35 @@ export interface LaunchOptions {
    * solving is v0.3+).
    */
   challenges?: ChallengeLaunchOptions;
+  /**
+   * Reconcile `(matrix.timezone, matrix.locale)` against the proxy's
+   * exit-IP geolocation. Closes the cross-layer leak where a US profile
+   * over an EU proxy would have `Date.getTimezoneOffset()` reporting PT
+   * while the IP geolocates to UTC+1 — the canonical bot signature.
+   *
+   * - `"privacy-fallback"` *(default)* — on mismatch (or probe failure),
+   *   override the matrix to UTC + `en-US`. The session fingerprints as
+   *   a privacy-conscious user (Tor / Brave / hardened-FF style), which
+   *   is benign in most threat models.
+   * - `"auto-correct"` — on mismatch, override the matrix's timezone
+   *   with the IP's timezone and the locale with a primary-locale
+   *   guess for the IP's country. Most "stealth" but trusts mochi's
+   *   IP-derived defaults over the user's declared profile.
+   * - `"strict"` — throw `GeoMismatchError` on mismatch. The user must
+   *   change profile or change proxy. Probe failure (null) does NOT
+   *   throw under strict — that's a network blip, not a mismatch.
+   * - `"off"` — skip the probe entirely. Use in offline tests / when
+   *   the probe service is rate-limited.
+   *
+   * The probe is a single GET through wreq (using the matrix's
+   * `wreqPreset`, so the geo service sees the same JA4/headers as user
+   * traffic). 4-attempt cap, 2s per endpoint. Probe results are NOT
+   * cached across sessions — proxy IPs rotate.
+   *
+   * @see PLAN.md §9 (relational consistency, IP/TZ/Locale axis)
+   * @see tasks/0262-ip-tz-locale-exit-consistency.md
+   */
+  geoConsistency?: GeoConsistencyMode;
 }
 
 /**
@@ -175,6 +206,37 @@ export async function launch(opts: LaunchOptions): Promise<Session> {
   const profile = resolveProfile(opts.profile);
   const matrix = deriveMatrix(profile, opts.seed);
 
+  // Task 0262 — exit-IP / TZ / locale reconciliation.
+  //
+  // Probe the apparent exit IP through the configured proxy (using wreq
+  // with the matrix's `wreqPreset` so the geo service sees the same JA4
+  // / headers as user traffic). Then cross-reference against
+  // `(matrix.timezone, matrix.locale)` and apply `geoConsistency`. The
+  // adjusted matrix flows into BOTH `spawnChromium` (so `--lang` reflects
+  // any override) AND `Session` (so inject + the CDP `Emulation.set
+  // TimezoneOverride` send pick it up). PLAN.md §9.
+  //
+  // `"off"` short-circuits the probe — the probe call itself respects
+  // the mode so we don't pay the network round-trip in offline tests.
+  const geoMode: GeoConsistencyMode = opts.geoConsistency ?? "privacy-fallback";
+  let adjustedMatrix = matrix;
+  if (geoMode !== "off") {
+    const geo = await probeExitGeo({
+      ...(normalized?.netProxy !== undefined ? { proxy: normalized.netProxy } : {}),
+      matrix,
+    });
+    // Strict mode throws GeoMismatchError on real mismatch; let it
+    // propagate up so callers can recover (the orchestrator surfaced
+    // it as the canonical failure mode for "wrong proxy for profile").
+    const result = reconcileGeoConsistency(matrix, geo, geoMode);
+    adjustedMatrix = result.matrix;
+    if (result.action === "privacy-fallback" || result.action === "auto-correct") {
+      console.warn(
+        `[mochi] geoConsistency=${geoMode}: ${result.action} applied — ${result.reason ?? "(no reason)"}`,
+      );
+    }
+  }
+
   const proc = await spawnChromium({
     binary,
     extraArgs: opts.args,
@@ -191,17 +253,26 @@ export async function launch(opts: LaunchOptions): Promise<Session> {
     // inject layer's `navigator.languages` spoof; Chromium derives the
     // q-weighted `Accept-Language` value from the single `--lang` primary
     // automatically. Task 0251.
-    locale: matrix.locale,
+    locale: adjustedMatrix.locale,
     // Pin OS-level outer window from the matrix's display geometry so
     // `window.outerWidth/outerHeight` (which reads from the OS window,
     // NOT the JS-spoofed `screen.*`) matches the spoof. Closes the
     // `fingerprint-scan.com` 800×600 leak under `--headless=new`.
     // UDC fixes the same issue at `__init__.py:410-411`. Task 0252.
-    ...(Number.isInteger(matrix.display.width) &&
-    Number.isInteger(matrix.display.height) &&
-    matrix.display.width > 0 &&
-    matrix.display.height > 0
-      ? { windowSize: { width: matrix.display.width, height: matrix.display.height } }
+    //
+    // (`adjustedMatrix.display` === `matrix.display` since geo reconcile
+    // only touches timezone/locale/languages — but we use the adjusted
+    // ref for forward-compat.)
+    ...(Number.isInteger(adjustedMatrix.display.width) &&
+    Number.isInteger(adjustedMatrix.display.height) &&
+    adjustedMatrix.display.width > 0 &&
+    adjustedMatrix.display.height > 0
+      ? {
+          windowSize: {
+            width: adjustedMatrix.display.width,
+            height: adjustedMatrix.display.height,
+          },
+        }
       : {}),
     // Hermetic harness/CI escape hatch — re-applies the patchright-trim
     // flags (`--disable-component-update`, `--disable-default-apps`,
@@ -213,7 +284,7 @@ export async function launch(opts: LaunchOptions): Promise<Session> {
 
   const session = new Session({
     proc,
-    matrix,
+    matrix: adjustedMatrix,
     seed: opts.seed,
     ...(opts.timeout !== undefined ? { defaultTimeoutMs: opts.timeout } : {}),
     ...(opts.bypassInject === true ? { bypassInject: true } : {}),

package/src/page.ts

@@ -311,6 +311,14 @@ export class Page {
    * document (so `this` === document). Result is JSON-serialized via
    * `returnByValue: true`.
    *
+   * The function may return a value or a `Promise`. Promise-returning
+   * functions are awaited page-side via `awaitPromise: true` (CDP's canonical
+   * mechanism for async eval) — without that flag, an `async () => ...`
+   * function round-trips its returned Promise as `undefined` because CDP
+   * serializes the Promise object itself, not its resolution. `awaitPromise`
+   * is NOT on PLAN.md §8.2's forbidden list — only `Runtime.enable` and
+   * `Page.createIsolatedWorld` are. Available since Chromium 67.
+   *
    * Limitations (documented in docs/limits.md):
    *   - Non-JSON return values (functions, DOM nodes, undefined) are
    *     coerced/dropped per CDP semantics.
@@ -319,13 +327,14 @@ export class Page {
    *     standard for any cross-process evaluator).
    *   - Arguments cannot be passed in v0.1; the function takes no args.
    */
-  async evaluate<T>(fn: () => T): Promise<T> {
+  async evaluate<T>(fn: () => T | Promise<T>): Promise<T> {
     this.assertOpen();
     const docId = await this.documentObjectId();
     const result = await this.send<{ result: RemoteObject }>("Runtime.callFunctionOn", {
       objectId: docId,
       functionDeclaration: fn.toString(),
       returnByValue: true,
+      awaitPromise: true,
     });
     return result.result.value as T;
   }

package/src/session.ts

@@ -266,27 +266,70 @@ 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` 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.
+    // `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. Sent immediately after
-    // attach and before any navigation so the very first request the page
-    // issues already carries the matrix UA.
+    // 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.
+    // 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 },
+        {
+          userAgent: this.profile.userAgent,
+          userAgentMetadata: buildUserAgentMetadata(this.profile),
+        },
         { sessionId: attached.sessionId },
       );
     }
@@ -764,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,
+  };
+}