@mochi.js/core 0.1.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";
@@ -91,6 +93,16 @@ export interface LaunchOptions {
   args?: string[];
   out?: { traceDir?: string };
   timeout?: number;
+  /**
+   * Opt out of mochi's "auto-add `--no-sandbox` when running as root on
+   * Linux" fallback. Default `false` (the fallback is on). When `true`,
+   * mochi will NOT inject `--no-sandbox` even under root + Linux — useful
+   * if you've configured a SUID `chrome-sandbox` helper and want to keep
+   * the user-namespace sandbox active. The launch will crash with EPIPE
+   * if the SUID setup is wrong, but you keep stealth posture intact
+   * (`--no-sandbox` is a fingerprint leak per PLAN.md §8.6).
+   */
+  allowRootWithSandbox?: boolean;
   /**
    * When `true`, the {@link Session} skips both `buildPayload` (no payload
    * is compiled) and `Page.addScriptToEvaluateOnNewDocument` on every new
@@ -107,6 +119,27 @@ export interface LaunchOptions {
    * Chromium); task 0040.
    */
   bypassInject?: boolean;
+  /**
+   * When `true`, re-applies the harness/CI-only Chromium flags
+   * (`--disable-component-update`, `--disable-default-apps`,
+   * `--disable-background-networking`, `--disable-sync`, plus a noise-
+   * reduction `--disable-features=` block) on top of the production
+   * default flag set. Used by `@mochi.js/harness`, CI runs, and
+   * `mochi capture` flows where update traffic, default-apps auto-install,
+   * sync, and feed prefetches would inject non-determinism into baseline
+   * collection or stealth conformance.
+   *
+   * Defaults to `false` — production users get a cleaner flag set without
+   * the passive command-line bot-tells that patchright explicitly removes
+   * from its Playwright fork (`chromiumSwitchesPatch.ts:20-34`) and that
+   * `puppeteer-real-browser` strips for the same reason
+   * (`lib/cjs/index.js:57-58`).
+   *
+   * Pairs with — but is independent of — {@link bypassInject}. Capture
+   * flows set both `true`; harness conformance runs set `hermetic: true`
+   * with full inject pipeline active. PLAN.md §8.6 + task 0256.
+   */
+  hermetic?: boolean;
   /**
    * Convenience layer toggles for common bot-defense widgets. When
    * `challenges.turnstile.autoClick` is `true`, every page returned by
@@ -120,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;
 }
 
 /**
@@ -129,26 +191,100 @@ export interface LaunchOptions {
 export async function launch(opts: LaunchOptions): Promise<Session> {
   const binary = await resolveBinary(opts.binary);
   const normalized = normalizeProxy(opts.proxy);
+
+  // Resolve the `MatrixV1` BEFORE spawning so matrix-derived values flow
+  // into both the `--lang` flag (task 0251) and `--window-size` flag
+  // (task 0252). The matrix is otherwise read post-spawn for inject;
+  // deriving early is cheap (~µs, pure function) and lets us close the
+  // I-5 leaks between Chromium's native network/OS-window state and the
+  // JS-layer spoof.
+  //
+  // Inline `ProfileV1` objects flow straight through; string profile ids
+  // are resolved against a placeholder profile until `@mochi.js/profiles`
+  // ships its first capture (phase 0.4). The matrix is bit-stable per
+  // `(profile, seed)` excluding the `derivedAt` timestamp.
+  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,
     headless: opts.headless ?? false,
+    // Opt-out for the auto-no-sandbox-as-root fallback (default: fallback
+    // is on so first-run on a Linux server box doesn't crash).
+    ...(opts.allowRootWithSandbox === true ? { allowRootWithSandbox: true } : {}),
     // Chromium rejects inline auth on `--proxy-server`; pass the
     // auth-stripped server URL.
     ...(normalized !== undefined ? { proxy: normalized.server } : {}),
+    // Primary BCP-47 locale → `--lang=<value>`. Locks the network-layer
+    // `Accept-Language` header to the JS spoof (PLAN.md I-5). The full
+    // multi-locale list still flows through `matrix.languages` to the
+    // inject layer's `navigator.languages` spoof; Chromium derives the
+    // q-weighted `Accept-Language` value from the single `--lang` primary
+    // automatically. Task 0251.
+    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.
+    //
+    // (`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`,
+    // `--disable-background-networking`, `--disable-sync`, hermetic
+    // `--disable-features=` extras). Default `false` keeps production users
+    // off the passive command-line bot-tell list. Task 0256, PLAN.md §8.6.
+    ...(opts.hermetic === true ? { hermetic: true } : {}),
   });
 
-  // Resolve the `MatrixV1` for this session via the consistency engine.
-  // Inline `ProfileV1` objects flow straight through; string profile ids
-  // are resolved against a placeholder profile until `@mochi.js/profiles`
-  // ships its first capture (phase 0.4). The matrix is bit-stable per
-  // `(profile, seed)` excluding the `derivedAt` timestamp.
-  const profile = resolveProfile(opts.profile);
-  const matrix = deriveMatrix(profile, opts.seed);
-
   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/element-handle.ts

@@ -0,0 +1,110 @@
+/**
+ * `ElementHandle` — lightweight wrapper around a CDP `RemoteObject` that lets
+ * callers operate on an element resolved via the closed-shadow piercing
+ * locator (`Page.querySelectorPiercing`).
+ *
+ * The handle is intentionally minimal — Phase 0.2 only needs enough surface
+ * for the Turnstile auto-clicker to ask "is this an iframe whose src matches
+ * cf-turnstile?" and then position a click. Wider parity with Playwright's
+ * `ElementHandle` (waitFor, fill, hover, screenshot…) is deferred — those
+ * compose on top of the same primitives once they're needed.
+ *
+ * Lifecycle: the underlying `objectId` is bound to a CDP `Runtime` execution
+ * context. Closing the page invalidates every handle the page produced; we
+ * don't try to release them via `Runtime.releaseObject` because there's no
+ * `Runtime.enable` in this session (PLAN.md §8.2). Stale handles surface as
+ * `Cannot find context with specified id` errors from the next CDP call,
+ * which is fine for a v0.2 surface.
+ *
+ * @see PLAN.md §8.2 / §8.3
+ * @see tasks/0253-closed-shadow-piercing-locator.md
+ */
+
+import type { MessageRouter } from "../cdp/router";
+import type { CdpSessionId, RemoteObject } from "../cdp/types";
+
+export interface ElementHandleInit {
+  router: MessageRouter;
+  sessionId: CdpSessionId;
+  objectId: string;
+  /** CDP `backendNodeId` — stable across DOM mutations. */
+  backendNodeId: number;
+}
+
+/**
+ * A handle to a single DOM element exposed to host-side automation. Issued
+ * by `Page.querySelectorPiercing` / `Page.querySelectorAllPiercing`.
+ */
+export class ElementHandle {
+  private readonly router: MessageRouter;
+  private readonly sessionId: CdpSessionId;
+  private readonly objectId: string;
+  private readonly _backendNodeId: number;
+
+  constructor(init: ElementHandleInit) {
+    this.router = init.router;
+    this.sessionId = init.sessionId;
+    this.objectId = init.objectId;
+    this._backendNodeId = init.backendNodeId;
+  }
+
+  /** The CDP `backendNodeId` for the element — stable across DOM mutations. */
+  get backendNodeId(): number {
+    return this._backendNodeId;
+  }
+
+  /**
+   * Read a single attribute via `Runtime.callFunctionOn`. Returns `null` when
+   * the attribute is absent (mirrors `Element.getAttribute`).
+   */
+  async getAttribute(name: string): Promise<string | null> {
+    const r = await this.router.send<{ result: RemoteObject }>(
+      "Runtime.callFunctionOn",
+      {
+        objectId: this.objectId,
+        functionDeclaration:
+          "function(n) { var v = this.getAttribute(n); return v === null ? null : String(v); }",
+        arguments: [{ value: name }],
+        returnByValue: true,
+      },
+      { sessionId: this.sessionId },
+    );
+    const v = r.result.value;
+    return v === null || v === undefined ? null : String(v);
+  }
+
+  /**
+   * Get the element's text content via `Runtime.callFunctionOn`.
+   */
+  async textContent(): Promise<string | null> {
+    const r = await this.router.send<{ result: RemoteObject }>(
+      "Runtime.callFunctionOn",
+      {
+        objectId: this.objectId,
+        functionDeclaration: "function() { return this.textContent; }",
+        returnByValue: true,
+      },
+      { sessionId: this.sessionId },
+    );
+    const v = r.result.value;
+    return v === null || v === undefined ? null : String(v);
+  }
+
+  /**
+   * Evaluate a function bound to this element (the handle is `this`). Result
+   * is JSON-serialised via `returnByValue: true`. Same contract as
+   * `Page.evaluate` — no closures, no arguments, no DOM-node returns.
+   */
+  async evaluate<T>(fn: (this: Element) => T): Promise<T> {
+    const r = await this.router.send<{ result: RemoteObject }>(
+      "Runtime.callFunctionOn",
+      {
+        objectId: this.objectId,
+        functionDeclaration: fn.toString(),
+        returnByValue: true,
+      },
+      { sessionId: this.sessionId },
+    );
+    return r.result.value as T;
+  }
+}

package/src/page/piercing.ts

@@ -0,0 +1,135 @@
+/**
+ * Closed-shadow piercing locator.
+ *
+ * Walks a tree returned by `DOM.getDocument({ depth: -1, pierce: true })` and
+ * yields `backendNodeId`s for every element that matches a parsed CSS
+ * selector — including elements inside **closed** shadow roots, which
+ * `DOM.querySelector(..., pierce: true)` does NOT traverse from the parent
+ * document. Patchright solves the same problem in `_customFindElementsByParsed`
+ * (`framesPatch.ts:868-1012`); this is mochi's port — we kept the recursive-walk
+ * shape but simplified the selector subset (CSS only — no XPath; see task
+ * 0253 brief for the rationale).
+ *
+ * The walker recurses through:
+ *  - `node.children[]` (regular DOM descendants)
+ *  - `node.shadowRoots[]` (BOTH `shadowRootType:"open"` and `"closed"` — the
+ *    pierce flag yields both; the matcher just doesn't care which kind it is)
+ *  - `node.contentDocument` (iframes — same-origin only; OOPIF subframes
+ *    surface as separate targets and are out of scope here)
+ *  - `node.templateContent` (template fragment, rare but cheap to walk)
+ *
+ * It deliberately does NOT recurse into:
+ *  - `pseudoElements` — `::before` / `::after` aren't real DOM nodes for
+ *    selector matching purposes; CDP yields them but they'd produce
+ *    spurious matches on `*` selectors.
+ *
+ * The walker keeps a *flat* ancestor chain across shadow boundaries so the
+ * descendant-combinator matcher can reason about "div .btn" correctly even
+ * when the `.btn` is inside a closed shadow rooted at `<div>`. This mirrors
+ * how DOM's regular ancestor walk behaves under `composedPath` semantics —
+ * patchright does the same.
+ *
+ * Performance: O(N) in DOM size per call. Acceptable for v0.2 (per task
+ * brief — a per-page cache layer is a v0.3+ concern).
+ *
+ * @see PLAN.md §8.2 — `DOM.getDocument` / `DOM.resolveNode` are not forbidden
+ * @see tasks/0253-closed-shadow-piercing-locator.md
+ */
+
+import type { PierceDomNode } from "../cdp/types";
+import { matchSelector, type ParsedSelector } from "./selector";
+
+export interface PierceMatch {
+  /** The CDP `backendNodeId` of the matched element — stable across DOM mutations. */
+  backendNodeId: number;
+  /** The CDP node id (per-DOMSession-instance; less stable than backend). */
+  nodeId: number;
+  /** The matched node itself (for diagnostics + tests). */
+  node: PierceDomNode;
+}
+
+/**
+ * Walk `root` and return every matching element. Ordering is depth-first,
+ * pre-order (parents before children) — matches the natural `querySelectorAll`
+ * traversal order users expect.
+ *
+ * If `limit` is set, the walk short-circuits as soon as that many matches
+ * accumulate. `Page.querySelectorPiercing` passes `1` for a single-element
+ * lookup; `querySelectorAllPiercing` leaves it undefined.
+ */
+export function findPiercingMatches(
+  root: PierceDomNode,
+  selector: ParsedSelector,
+  limit?: number,
+): PierceMatch[] {
+  const out: PierceMatch[] = [];
+  walk(root, selector, [], out, limit);
+  return out;
+}
+
+function walk(
+  node: PierceDomNode,
+  selector: ParsedSelector,
+  ancestors: PierceDomNode[],
+  out: PierceMatch[],
+  limit: number | undefined,
+): boolean {
+  if (limit !== undefined && out.length >= limit) return true;
+
+  // Match element nodes only — but document / fragment nodes still need to
+  // recurse into children.
+  if (node.nodeType === 1 && matchSelector(selector, node, ancestors)) {
+    out.push({ backendNodeId: node.backendNodeId, nodeId: node.nodeId, node });
+    if (limit !== undefined && out.length >= limit) return true;
+  }
+
+  // Push self into ancestor stack ONLY if it's an element (text / shadow-root
+  // / document nodes aren't ancestors for `div .btn`-style descendant matches).
+  const isElement = node.nodeType === 1;
+  if (isElement) ancestors.push(node);
+
+  // Children (regular DOM descendants).
+  const children = node.children;
+  if (children !== undefined) {
+    for (const child of children) {
+      if (walk(child, selector, ancestors, out, limit)) {
+        if (isElement) ancestors.pop();
+        return true;
+      }
+    }
+  }
+
+  // Shadow roots — both open AND closed. This is the whole point.
+  const shadowRoots = node.shadowRoots;
+  if (shadowRoots !== undefined) {
+    for (const root of shadowRoots) {
+      if (walk(root, selector, ancestors, out, limit)) {
+        if (isElement) ancestors.pop();
+        return true;
+      }
+    }
+  }
+
+  // iframe contentDocument (same-origin only — OOPIFs surface as separate
+  // CDP targets and aren't reachable here).
+  const contentDocument = node.contentDocument;
+  if (contentDocument !== undefined) {
+    if (walk(contentDocument, selector, ancestors, out, limit)) {
+      if (isElement) ancestors.pop();
+      return true;
+    }
+  }
+
+  // <template>.content — rare in real-world Cloudflare integrations but
+  // matches what patchright walks.
+  const templateContent = node.templateContent;
+  if (templateContent !== undefined) {
+    if (walk(templateContent, selector, ancestors, out, limit)) {
+      if (isElement) ancestors.pop();
+      return true;
+    }
+  }
+
+  if (isElement) ancestors.pop();
+  return false;
+}