npm - @mochi.js/core - Versions diffs - 0.1.2 → 0.3.0 - Mend

@mochi.js/core 0.1.2 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

package/package.json +5 -5
package/src/__tests__/geo-consistency.test.ts +277 -0
package/src/__tests__/geo-probe.test.ts +415 -0
package/src/__tests__/inject.test.ts +4 -0
package/src/__tests__/integration.e2e.test.ts +24 -0
package/src/__tests__/piercing.test.ts +164 -0
package/src/__tests__/proc.test.ts +383 -0
package/src/__tests__/selector.test.ts +188 -0
package/src/__tests__/window-size.e2e.test.ts +130 -0
package/src/cdp/types.ts +47 -0
package/src/geo-consistency.ts +343 -0
package/src/geo-probe.ts +603 -0
package/src/index.ts +11 -0
package/src/launch.ts +145 -9
package/src/page/element-handle.ts +110 -0
package/src/page/piercing.ts +135 -0
package/src/page/selector.ts +423 -0
package/src/page.ts +152 -1
package/src/proc.ts +386 -41
package/src/session.ts +358 -12

package/src/__tests__/window-size.e2e.test.ts ADDED Viewed

@@ -0,0 +1,130 @@
+/**
+ * Task 0252 conformance E2E — verify the OS-level outer-window pin
+ * (`--window-size=<W>,<H>`, derived from `matrix.display.{width,height}`)
+ * is honored under `--headless=new` such that
+ * `window.outerWidth === matrix.display.width`.
+ *
+ * UDC issue #2242 documents that `--window-size` is honored at the OS
+ * level under headless, but the JS API surface (`window.outerWidth/Height`)
+ * historically did not reflect it without a CDP `Browser.setWindowBounds`
+ * follow-up. This test is the canonical check that the leak is closed
+ * end-to-end on the Chromium versions we care about. If `outerWidth`
+ * comes back as 800 (the legacy headless default) the test fails loudly
+ * and the orchestrator knows to layer in the CDP fix.
+ *
+ * Mochi's inject layer also defines `window.outerWidth/outerHeight` from
+ * `matrix.uaCh["window-viewport"]` (R-029). On macOS the R-029 outerWidth
+ * equals `display.width` exactly (OS_CHROME_WIDTH = 0), so the assertion
+ * holds regardless of whether the OS-level honoring works as promised.
+ * The OS-level fix is what hardens the surface against:
+ *   - inject-bypassed flows (`bypassInject: true`, `mochi capture`)
+ *   - cross-realm reads where the spoof hasn't installed yet
+ *
+ * Gated by `MOCHI_E2E=1`. Set `MOCHI_CHROMIUM_PATH` to a real binary.
+ *
+ * @see tasks/0252-window-size-flag-from-matrix.md
+ * @see UDC `__init__.py:410-411`, UDC issue #2242
+ */
+import { describe, expect, it } from "bun:test";
+import { mochi } from "../index";
+const E2E_ENABLED = process.env.MOCHI_E2E === "1";
+const TEST_TIMEOUT_MS = 15_000;
+const describeOrSkip = E2E_ENABLED ? describe : describe.skip;
+const PROBE_HTML = `<!doctype html><html><body><pre id="p"></pre><script>
+document.getElementById("p").textContent = JSON.stringify({
+  outerWidth: window.outerWidth,
+  outerHeight: window.outerHeight,
+  screenWidth: screen.width,
+  screenHeight: screen.height,
+});
+</script></body></html>`;
+const PROBE_DATA_URL = `data:text/html;charset=utf-8,${encodeURIComponent(PROBE_HTML)}`;
+interface ProbeShape {
+  outerWidth: number;
+  outerHeight: number;
+  screenWidth: number;
+  screenHeight: number;
+}
+describeOrSkip("@mochi.js/core --window-size E2E (MOCHI_E2E=1) — task 0252", () => {
+  it(
+    "window.outerWidth matches matrix.display.width under --headless=new",
+    async () => {
+      const session = await mochi.launch({
+        seed: "task-0252-window-size",
+        headless: true,
+        profile: {
+          id: "window-size-e2e-fixture",
+          version: "0.0.0-e2e",
+          engine: "chromium",
+          browser: { name: "chrome", channel: "stable", minVersion: "131", maxVersion: "133" },
+          os: { name: "macos", version: "14", arch: "arm64" },
+          device: {
+            vendor: "Apple",
+            model: "Mac14,2",
+            cpuFamily: "apple-silicon-m2",
+            cores: 8,
+            memoryGB: 16,
+          },
+          // Distinctive non-default dimensions so an 800×600 leak is glaring.
+          display: { width: 1728, height: 1117, dpr: 2, colorDepth: 30, pixelDepth: 30 },
+          gpu: {
+            vendor: "Apple Inc.",
+            renderer: "Apple M2",
+            webglUnmaskedVendor: "Google Inc. (Apple)",
+            webglUnmaskedRenderer:
+              "ANGLE (Apple, ANGLE Metal Renderer: Apple M2, Unspecified Version)",
+            webglMaxTextureSize: 16384,
+            webglMaxColorAttachments: 8,
+            webglExtensions: [],
+          },
+          audio: {
+            contextSampleRate: 48000,
+            audioWorkletLatency: 0.005,
+            destinationMaxChannelCount: 2,
+          },
+          fonts: { family: "macos-baseline", list: ["Helvetica"] },
+          timezone: "America/Los_Angeles",
+          locale: "en-US",
+          languages: ["en-US", "en"],
+          behavior: { hand: "right", tremor: 0.18, wpm: 60, scrollStyle: "smooth" },
+          wreqPreset: "chrome_131_macos",
+          userAgent:
+            "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.6778.86 Safari/537.36",
+          uaCh: {},
+          entropyBudget: { fixed: [], perSeed: [] },
+        },
+      });
+      try {
+        const matrix = session.profile;
+        const page = await session.newPage();
+        await page.goto(PROBE_DATA_URL);
+        const txt = await page.text("#p");
+        if (txt === null) throw new Error("[mochi e2e] probe element produced no textContent");
+        const probe = JSON.parse(txt) as ProbeShape;
+        // Task 0252 success criterion #4: probe-time conformance.
+        // The 800×600 leak under --headless=new manifests as outerWidth=800.
+        // Failing here means the OS-level pin is NOT honored AND the inject
+        // spoof did not install — orchestrator should layer in CDP
+        // `Browser.setWindowBounds` per UDC issue #2242 follow-up.
+        expect(probe.outerWidth).toBe(matrix.display.width);
+        expect(probe.outerWidth).not.toBe(800);
+        // screen.width must match too (separate path: inject layer R-010).
+        expect(probe.screenWidth).toBe(matrix.display.width);
+        expect(probe.screenHeight).toBe(matrix.display.height);
+      } finally {
+        await session.close();
+      }
+    },
+    TEST_TIMEOUT_MS,
+  );
+});

package/src/cdp/types.ts CHANGED Viewed

@@ -68,6 +68,53 @@ export interface DomNode {
   nodeName: string;
 }
+/**
+ * Wider subset of `DOM.Node` used by the closed-shadow piercing locator
+ * (`Page.querySelectorPiercing`).
+ *
+ * Returned by `DOM.getDocument({ depth: -1, pierce: true })` — `pierce: true`
+ * yields shadow descendants under `shadowRoots[]` for *both* open and closed
+ * roots, and iframe descendants under `contentDocument`. Element-node fields
+ * (`localName`, `attributes`) drive selector matching in JS without round-
+ * tripping each candidate through `DOM.querySelector` (which would not pierce
+ * closed shadows even when called against the parent's document node).
+ *
+ * Reference: <https://chromedevtools.github.io/devtools-protocol/tot/DOM/#type-Node>
+ *
+ * @see PLAN.md §8.2 — `DOM.getDocument` and `DOM.resolveNode` are not on the
+ * forbidden list; both are fine to use.
+ * @see tasks/0253-closed-shadow-piercing-locator.md
+ */
+export interface PierceDomNode {
+  nodeId: number;
+  backendNodeId: number;
+  /** 1 = ELEMENT, 3 = TEXT, 9 = DOCUMENT, 11 = DOCUMENT_FRAGMENT, etc. */
+  nodeType: number;
+  /** Upper-case tag for element nodes (e.g. `"DIV"`); `"#document"` for the document. */
+  nodeName: string;
+  /** Lower-case tag (`"div"`) — only present on element nodes. */
+  localName?: string;
+  /** Flat `[name, value, name, value, ...]` array — only on element nodes. */
+  attributes?: string[];
+  /** Element / document children. */
+  children?: PierceDomNode[];
+  /**
+   * Shadow-root subtrees attached to this element. CDP yields BOTH open and
+   * closed shadows here when `pierce: true` is set; `shadowRootType` is
+   * `"open" | "closed" | "user-agent"`. The piercing walker traverses all of
+   * them — that's the whole point of this type vs. `DomNode`.
+   */
+  shadowRoots?: PierceDomNode[];
+  /** `"open" | "closed" | "user-agent"` — present on shadow-root nodes. */
+  shadowRootType?: "open" | "closed" | "user-agent";
+  /** iframe descendant tree. CDP yields it as a single-element array. */
+  contentDocument?: PierceDomNode;
+  /** Pseudo-element children (::before, ::after) — element nodes only. */
+  pseudoElements?: PierceDomNode[];
+  /** Template content fragment — present on `<template>` elements. */
+  templateContent?: PierceDomNode;
+}
 /** Subset of `Page.Frame`. */
 export interface PageFrame {
   id: string;

package/src/geo-consistency.ts ADDED Viewed

@@ -0,0 +1,343 @@
+/**
+ * Geo-consistency reconciler — cross-references the matrix's declared
+ * `(timezone, locale)` against the probed exit-IP geolocation and
+ * applies a `LaunchOptions.geoConsistency` policy on mismatch.
+ *
+ * The default policy is `"privacy-fallback"`: on mismatch (or probe
+ * failure), override the matrix to `UTC` + `en-US`. The session then
+ * fingerprints as a privacy-conscious user (Tor / Brave / hardened-FF
+ * style), which is benign in most threat models — across thousands of
+ * real users, mismatched-tz-vs-IP is the canonical bot signature; UTC
+ * + en-US looks like every Tor user.
+ *
+ * @see PLAN.md §9 — relational consistency, IP/TZ/Locale axis
+ * @see tasks/0262-ip-tz-locale-exit-consistency.md
+ */
+import type { MatrixV1 } from "@mochi.js/consistency";
+import type { ExitGeo } from "./geo-probe";
+/**
+ * Reconciliation modes for `(matrix.timezone, matrix.locale)` vs exit IP.
+ *
+ * - `"privacy-fallback"` *(default)* — on mismatch (or probe failure),
+ *   override to `UTC` + `en-US`. Fingerprints as a Tor-class user. UTC
+ *   + en-US is the failure-mode-of-least-tampering: it identifies the
+ *   user as privacy-aware, not as automated.
+ * - `"auto-correct"` — on mismatch, override the matrix's timezone with
+ *   the IP's timezone and the locale's region with the IP's country.
+ *   Most "stealth" but trusts mochi's IP-derived defaults over the
+ *   user's declared profile.
+ * - `"strict"` — throw on mismatch. The user must change profile or
+ *   change proxy.
+ * - `"off"` — skip the probe entirely. Used by tests and by users with
+ *   rate-limit problems.
+ */
+export type GeoConsistencyMode = "privacy-fallback" | "auto-correct" | "strict" | "off";
+/**
+ * Outcome of a reconciliation pass — exposed for diagnostics + the
+ * planned `_internalReconcile` test seam. `kind === "ok"` means the
+ * matrix passes through unchanged; `"override"` means we adjusted the
+ * matrix per the policy; `"strict-throw"` is the strict-mode error path
+ * (caller throws).
+ */
+export interface GeoReconcileResult {
+  /** Possibly-adjusted matrix (always a fresh object when adjusted). */
+  readonly matrix: MatrixV1;
+  /** What happened. `"ok"` is the no-mismatch fast path. */
+  readonly action: "ok" | "no-probe" | "off" | "privacy-fallback" | "auto-correct";
+  /** The geo result that drove this decision (null for `"no-probe"` / `"off"`). */
+  readonly geo: ExitGeo | null;
+  /** Human-readable mismatch summary, when applicable. */
+  readonly reason?: string;
+}
+/**
+ * Thrown by {@link reconcileGeoConsistency} when `mode === "strict"` and
+ * the probe revealed a mismatch. Signals the user MUST adjust either the
+ * profile or the proxy.
+ */
+export class GeoMismatchError extends Error {
+  readonly matrix: { timezone: string; locale: string };
+  readonly geo: ExitGeo;
+  readonly reason: string;
+  constructor(matrix: { timezone: string; locale: string }, geo: ExitGeo, reason: string) {
+    super(
+      `[mochi] geoConsistency: strict — exit-IP geo (${geo.country}/${geo.timezone}, ` +
+        `via ${geo.source}) does not match matrix (${matrix.locale}/${matrix.timezone}): ` +
+        `${reason}. Change the profile to match the proxy egress, change the proxy, ` +
+        `or pass geoConsistency: "privacy-fallback" | "auto-correct" | "off".`,
+    );
+    this.name = "GeoMismatchError";
+    this.matrix = matrix;
+    this.geo = geo;
+    this.reason = reason;
+  }
+}
+/**
+ * Compute the **integer minutes offset** of an IANA timezone for a given
+ * reference date. Uses `Intl.DateTimeFormat(...).formatToParts(...)` to
+ * extract the "longOffset" part — the most stable cross-runtime path that
+ * works for both fixed-offset zones (`UTC`, `Etc/GMT+8`) and DST-aware
+ * zones (`America/New_York`).
+ *
+ * The brief calls this out: `America/New_York` and `America/Detroit`
+ * share the same offset and are equivalent for fingerprinting; we MUST
+ * compare offsets, not zone names.
+ *
+ * Returns `null` if the zone string isn't recognised (caller treats this
+ * as "incomparable" and bails out to the per-mode policy).
+ */
+export function tzOffsetMinutes(zone: string, ref: Date = new Date()): number | null {
+  try {
+    const parts = new Intl.DateTimeFormat("en-US", {
+      timeZone: zone,
+      timeZoneName: "longOffset",
+    }).formatToParts(ref);
+    const tzPart = parts.find((p) => p.type === "timeZoneName")?.value;
+    if (tzPart === undefined) return null;
+    // longOffset shape: "GMT+05:30", "GMT-08:00", "GMT" (== 0).
+    if (tzPart === "GMT" || tzPart === "UTC") return 0;
+    const m = /^(?:GMT|UTC)([+-])(\d{1,2})(?::?(\d{2}))?$/.exec(tzPart);
+    if (m === null) return null;
+    const sign = m[1] === "-" ? -1 : 1;
+    const hours = Number.parseInt(m[2] ?? "0", 10);
+    const mins = Number.parseInt(m[3] ?? "0", 10);
+    if (!Number.isFinite(hours) || !Number.isFinite(mins)) return null;
+    return sign * (hours * 60 + mins);
+  } catch {
+    return null;
+  }
+}
+/**
+ * Extract the alpha-2 region code from a BCP-47 locale via `Intl.Locale`.
+ * `"en-US"` → `"US"`, `"de-DE"` → `"DE"`, `"en"` → `null` (no region).
+ */
+export function localeRegion(locale: string): string | null {
+  try {
+    const region = new Intl.Locale(locale).region;
+    if (region === undefined || region.length === 0) return null;
+    return region.toUpperCase();
+  } catch {
+    return null;
+  }
+}
+/**
+ * Tiny country-code → primary-locale lookup for `auto-correct` mode.
+ * Covers the major proxy-egress countries; falls back to `en-<CC>` for
+ * unknown codes (which is wrong for, say, Korea, but is at most a
+ * lower-stealth-ceiling fallback rather than a hard fail).
+ *
+ * Order chosen for the most common residential-proxy egress destinations.
+ */
+const PRIMARY_LOCALE_BY_COUNTRY: Readonly<Record<string, string>> = {
+  US: "en-US",
+  GB: "en-GB",
+  CA: "en-CA",
+  AU: "en-AU",
+  IE: "en-IE",
+  NZ: "en-NZ",
+  DE: "de-DE",
+  AT: "de-AT",
+  CH: "de-CH",
+  FR: "fr-FR",
+  BE: "fr-BE",
+  IT: "it-IT",
+  ES: "es-ES",
+  MX: "es-MX",
+  AR: "es-AR",
+  BR: "pt-BR",
+  PT: "pt-PT",
+  NL: "nl-NL",
+  PL: "pl-PL",
+  RU: "ru-RU",
+  UA: "uk-UA",
+  CN: "zh-CN",
+  HK: "zh-HK",
+  TW: "zh-TW",
+  JP: "ja-JP",
+  KR: "ko-KR",
+  IN: "hi-IN",
+  ID: "id-ID",
+  TH: "th-TH",
+  VN: "vi-VN",
+  TR: "tr-TR",
+  IL: "he-IL",
+  SA: "ar-SA",
+  AE: "ar-AE",
+  EG: "ar-EG",
+  ZA: "en-ZA",
+  SG: "en-SG",
+  MY: "ms-MY",
+  PH: "en-PH",
+  SE: "sv-SE",
+  NO: "nb-NO",
+  DK: "da-DK",
+  FI: "fi-FI",
+  CZ: "cs-CZ",
+  HU: "hu-HU",
+  RO: "ro-RO",
+  GR: "el-GR",
+};
+/** Best-effort primary locale for an ISO-3166-1 alpha-2 country code. */
+function primaryLocaleFor(country: string): string {
+  return PRIMARY_LOCALE_BY_COUNTRY[country.toUpperCase()] ?? `en-${country.toUpperCase()}`;
+}
+/**
+ * Return a fresh matrix with `timezone`/`locale`/`languages` overridden.
+ * Other fields (display, GPU, audio, etc.) are preserved so the rest of
+ * the relational lock stays intact. The brief's I-5 invariant: `MatrixV1`
+ * is the single source of truth, so we hand back the same shape with
+ * just the geo-axis fields swapped.
+ *
+ * Note: `wreqPreset` and `userAgent` are NOT touched — those carry
+ * OS/browser semantics, not geo. The reconciler is purely a geo-axis
+ * adjustment.
+ */
+function withGeoOverride(
+  matrix: MatrixV1,
+  overrides: { timezone: string; locale: string; languages: readonly [string, ...string[]] },
+): MatrixV1 {
+  const [head, ...tail] = overrides.languages;
+  return {
+    ...matrix,
+    timezone: overrides.timezone,
+    locale: overrides.locale,
+    languages: [head, ...tail],
+  };
+}
+/**
+ * Reconcile the matrix against the probed exit-IP geo per the supplied
+ * `mode`. Pure: never mutates the input matrix; returns a fresh object on
+ * any override path.
+ *
+ * **Mismatch criteria**:
+ *   - **Timezone**: matrix offset minutes ≠ IP offset minutes (computed
+ *     via `Intl.DateTimeFormat(timeZoneName: "longOffset")`). Zone-name
+ *     equivalence (e.g. `America/New_York` vs `America/Detroit`) is
+ *     intentional — they share an offset and fingerprint identically.
+ *   - **Locale**: `Intl.Locale(matrix.locale).region` ≠ IP country code.
+ *     A locale with no region (`"en"`) is treated as matching any
+ *     country (we can't disprove it).
+ *
+ * **Per-mode behaviour** (matrix passes through unchanged unless
+ * mismatch is detected):
+ *
+ * | Mode | probe = null | tz mismatch | locale mismatch | both match |
+ * |---|---|---|---|---|
+ * | `privacy-fallback` | UTC+en-US | UTC+en-US | UTC+en-US | passthrough |
+ * | `auto-correct` | passthrough (best effort) | IP tz | IP locale | passthrough |
+ * | `strict` | passthrough (no probe → no mismatch) | THROW | THROW | passthrough |
+ * | `off` | passthrough | n/a (no probe) | n/a | passthrough |
+ *
+ * The `strict` × `probe = null` case intentionally passes the matrix
+ * through. A null probe means "we couldn't talk to any geo endpoint" —
+ * which is most often a network blip, not a mismatch. Strict-mode users
+ * who want to fail closed on probe failure should pair this with
+ * external monitoring.
+ *
+ * @throws {GeoMismatchError} when `mode === "strict"` and a real
+ *   mismatch was detected.
+ */
+export function reconcileGeoConsistency(
+  matrix: MatrixV1,
+  geo: ExitGeo | null,
+  mode: GeoConsistencyMode,
+): GeoReconcileResult {
+  if (mode === "off") {
+    return { matrix, action: "off", geo: null };
+  }
+  if (geo === null) {
+    if (mode === "privacy-fallback") {
+      return {
+        matrix: withGeoOverride(matrix, {
+          timezone: "UTC",
+          locale: "en-US",
+          languages: ["en-US", "en"],
+        }),
+        action: "privacy-fallback",
+        geo: null,
+        reason: "probe returned null (all endpoints failed); falling back to UTC+en-US",
+      };
+    }
+    // auto-correct + strict: nothing to act on. Pass through.
+    return { matrix, action: "no-probe", geo: null };
+  }
+  // We have a probe result. Compute offset-based mismatch.
+  const matrixOffset = tzOffsetMinutes(matrix.timezone);
+  const ipOffset = tzOffsetMinutes(geo.timezone);
+  const tzMismatch =
+    matrixOffset !== null && ipOffset !== null && matrixOffset !== ipOffset
+      ? `tz offset ${matrixOffset}min (matrix ${matrix.timezone}) ≠ ${ipOffset}min (IP ${geo.timezone})`
+      : null;
+  const matrixRegion = localeRegion(matrix.locale);
+  // matrixRegion === null => locale has no region (e.g. "en"); treat as
+  // permissive match to avoid spurious mismatches.
+  const localeMismatch =
+    matrixRegion !== null && matrixRegion !== geo.country
+      ? `locale region ${matrixRegion} (matrix ${matrix.locale}) ≠ IP country ${geo.country}`
+      : null;
+  if (tzMismatch === null && localeMismatch === null) {
+    return { matrix, action: "ok", geo };
+  }
+  const reason = [tzMismatch, localeMismatch].filter((x): x is string => x !== null).join("; ");
+  if (mode === "strict") {
+    throw new GeoMismatchError({ timezone: matrix.timezone, locale: matrix.locale }, geo, reason);
+  }
+  if (mode === "auto-correct") {
+    const newLocale = primaryLocaleFor(geo.country);
+    return {
+      matrix: withGeoOverride(matrix, {
+        timezone: geo.timezone,
+        locale: newLocale,
+        // languages list: primary locale + its language root (e.g. "de-DE",
+        // "de"). Keeps the language root present which sites read for
+        // fallback negotiation.
+        languages: deriveLanguagesFor(newLocale),
+      }),
+      action: "auto-correct",
+      geo,
+      reason,
+    };
+  }
+  // privacy-fallback
+  return {
+    matrix: withGeoOverride(matrix, {
+      timezone: "UTC",
+      locale: "en-US",
+      languages: ["en-US", "en"],
+    }),
+    action: "privacy-fallback",
+    geo,
+    reason,
+  };
+}
+/**
+ * Derive the `navigator.languages` list for an `auto-correct` override.
+ * Convention: `[primary, primary-language-only, "en"]`, deduped. The "en"
+ * tail mirrors what real Chrome instances ship for non-English locales —
+ * most users have English as a secondary because Chrome itself defaults
+ * the menu language to English on first install in many regions.
+ */
+function deriveLanguagesFor(locale: string): readonly [string, ...string[]] {
+  const out: [string, ...string[]] = [locale];
+  const dash = locale.indexOf("-");
+  if (dash > 0) {
+    const root = locale.slice(0, dash);
+    if (!out.includes(root)) out.push(root);
+  }
+  if (!out.includes("en")) out.push("en");
+  return out;
+}