@legionworks/facet 1.9.0

package/src/validation/tier1/isolated-probe.ts

@@ -0,0 +1,94 @@
+/**
+ * Isolated-world probe — evaluate counts inside the pre-created
+ * execution context (`Page.createIsolatedWorld`). The isolated world
+ * is OUTSIDE the page's JavaScript scope: a hostile artifact that
+ * monkey-patched `document.querySelectorAll` (Test A) cannot reach
+ * it. Counts taken here are the third authority channel after
+ * `DOMSnapshot` and `DOM.getDocument`.
+ *
+ * Failure to evaluate returns null — the verifier falls back to
+ * `shim_only` instead of `tampered` because a missing isolated
+ * world is a probe-level failure, not a page-world divergence.
+ *
+ * `graphCount` matches the protocol probe: one count per
+ * renderer-owned `<svg>`. `mermaidNodeCount` sums the `g.node`
+ * descendants. Those renderer counts are marker-scoped; opaque regions
+ * deliberately census every owning `<canvas>` in the frame document so
+ * smuggled canvases cannot hide outside a marked root. The probe never
+ * calls getContext(), which would create an observation.
+ */
+
+import type { ProtocolObservation } from "../../shared/contracts/validation";
+import { HTML_STRUCTURAL_GROUPS } from "../../shared/html/policy";
+
+import type { VerifierCdpSession } from "./browser-process";
+
+export async function probeIsolatedCounts(
+  session: VerifierCdpSession,
+  executionContextId: number,
+): Promise<ProtocolObservation | null> {
+  try {
+    const selectors = Object.fromEntries(
+      Object.entries(HTML_STRUCTURAL_GROUPS).map(([group, names]) => [group, names.join(",")]),
+    );
+    const result = (await session.send("Runtime.evaluate", {
+      contextId: executionContextId,
+      returnByValue: true,
+      expression: [
+        "(function(){",
+        "  var candidates = Array.prototype.slice.call(document.querySelectorAll('[data-facet-renderer-root=\"true\"]'));",
+        "  var candidateSet = new Set(candidates);",
+        "  var roots = candidates.filter(function(root){",
+        "    for (var parent = root.parentElement; parent; parent = parent.parentElement) {",
+        "      if (candidateSet.has(parent)) return false;",
+        "    }",
+        "    return true;",
+        "  });",
+        "  var svgRoots = roots.filter(function(root){ return String(root.nodeName).toLowerCase() === 'svg'; });",
+        "  var graphRoots = svgRoots.filter(function(root){ return root.getAttribute('data-facet-renderer-graph') === 'true'; });",
+        "  var htmlRoots = roots.filter(function(root){ return String(root.nodeName).toLowerCase() !== 'svg'; });",
+        `  var selectors = ${JSON.stringify(selectors)};`,
+        "  var html = htmlRoots.length === 0 ? null : {rendererRootCount:htmlRoots.length,headingCount:0,tableCount:0,listCount:0,imageCount:0,canvasCount:0,externalImageCount:0};",
+        "  var externalImageCount = 0;",
+        "  for (var h = 0; h < htmlRoots.length; h++) {",
+        "    var htmlRoot = htmlRoots[h];",
+        "    html.headingCount += htmlRoot.querySelectorAll(selectors.headings).length;",
+        "    html.tableCount += htmlRoot.querySelectorAll(selectors.tables).length;",
+        "    html.listCount += htmlRoot.querySelectorAll(selectors.lists).length;",
+        "    var images = Array.prototype.slice.call(htmlRoot.querySelectorAll(selectors.images));",
+        "    html.imageCount += images.length;",
+        "    var rootExternal = images.filter(function(image){ try { return new URL(image.getAttribute('src') || '').protocol === 'https:'; } catch (_) { return false; } }).length;",
+        "    html.externalImageCount += rootExternal;",
+        "    externalImageCount += rootExternal;",
+        "    html.canvasCount += htmlRoot.querySelectorAll(selectors.canvases).length;",
+        "  }",
+        "  var nodeCount = 0;",
+        "  var visibleSvgCount = 0;",
+        "  for (var i = 0; i < svgRoots.length; i++) {",
+        "    var vb = svgRoots[i].getAttribute('viewBox') || '';",
+        "    var parts = vb.trim().split(/[\\s,]+/).map(Number.parseFloat);",
+        "    if (parts.length === 4 && Number.isFinite(parts[2]) && Number.isFinite(parts[3]) && parts[2] > 0 && parts[3] > 0) visibleSvgCount += 1;",
+        "  }",
+        "  for (var j = 0; j < graphRoots.length; j++) nodeCount += graphRoots[j].querySelectorAll('g.node').length;",
+        "  var errorCount = document.querySelectorAll('[data-facet-error]').length;",
+        "  var opaqueRegionCount = Array.prototype.slice.call(document.querySelectorAll('*')).filter(function(el){ return String(el.nodeName).toLowerCase() === 'canvas'; }).length;",
+        "  return {",
+        "    rendererRootSvgCount: svgRoots.length,",
+        "    graphCount: graphRoots.length,",
+        "    mermaidNodeCount: nodeCount,",
+        "    visibleSvgCount: visibleSvgCount,",
+        "    viewBoxes: [],",
+        "    errorCount: errorCount,",
+        "    opaqueRegionCount: opaqueRegionCount,",
+        "    externalImageCount: externalImageCount,",
+        "    discriminativeErrors: [],",
+        "    ...(html === null ? {} : {html: html})",
+        "  };",
+        "})()",
+      ].join("\n"),
+    })) as { result: { value?: ProtocolObservation } };
+    return result.result.value ?? null;
+  } catch {
+    return null;
+  }
+}

package/src/validation/tier1/launcher.ts

@@ -0,0 +1,177 @@
+/**
+ * Resolves the PINNED chrome-headless-shell binary and the production
+ * netns wrapper. Both paths live behind narrow helpers so the runner
+ * never inlines a path string and so the egress penetration harness
+ * can share the same lookup logic.
+ *
+ * The wrapper script (`scripts/launch-netns.sh`) is the egress boundary
+ * — `unshare --map-current-user --net --` removes every reachable
+ * interface, route, and DNS context from the browser process. A future
+ * regression that swaps the wrapper for a plain chromium exec would
+ * silently re-enable off-loopback traffic; the harness's CI test would
+ * catch that, but the path resolution here is the only place that
+ * names the wrapper script.
+ *
+ * The shell binary is pinned per ADR 0001 D3. The cache layout matches
+ * what `puppeteer` writes under `~/.cache/puppeteer/chrome-headless-shell/`.
+ */
+
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { InsecureLevelSchema, type InsecureLevel } from "../../shared/contracts/validation";
+import { TIER1_PINNED_VERSION } from "./limits";
+
+const ENV_PINNED_VERSION = "FACET_TIER1_PINNED_VERSION";
+const ENV_CACHE_DIR = "FACET_TIER1_BROWSER_CACHE";
+// Test-only seam: production callers resolve the repository wrapper path.
+const ENV_NETNS_WRAPPER = "FACET_TIER1_NETNS_WRAPPER";
+
+/**
+ * A pair of resolved paths the runner hands to puppeteer-core. The
+ * wrapper (`executablePath`) is what puppeteer-core actually `exec`s;
+ * `binaryPath` records the absolute path to the shell inside the
+ * wrapper's argv so a failure diagnostic can cite it.
+ */
+export interface ResolvedLauncher {
+  readonly executablePath: string;
+  readonly binaryPath: string;
+  readonly pinnedVersion: string;
+}
+
+type LauncherOverrides = {
+  readonly version?: string;
+  readonly cacheRoot?: string;
+  readonly wrapperPath?: string;
+};
+
+/**
+ * Default lookup locations for the cached shell. The cache directory
+ * layout matches what `puppeteer browsers install chrome-headless-shell`
+ * writes — pinning that layout here means the project does not need
+ * its own installer.
+ */
+function defaultCacheRoot(): string {
+  return join(homedir(), ".cache", "puppeteer", "chrome-headless-shell");
+}
+
+/** Read an env var or return undefined. */
+function readEnv(name: string): string | undefined {
+  const value = process.env[name];
+  return value !== undefined && value.length > 0 ? value : undefined;
+}
+
+/**
+ * Probe the cache layout for the pinned shell. Returns null when no
+ * candidate file exists; the caller turns that into a typed
+ * `tier1_launcher_missing` error.
+ */
+export function resolveShellBinary(
+  overrides: { readonly version?: string; readonly cacheRoot?: string } = {},
+): string | null {
+  const version = overrides.version ?? readEnv(ENV_PINNED_VERSION) ?? TIER1_PINNED_VERSION;
+  const cacheRoot = overrides.cacheRoot ?? readEnv(ENV_CACHE_DIR) ?? defaultCacheRoot();
+  const candidates = [
+    join(cacheRoot, version, "chrome-headless-shell-linux64", "chrome-headless-shell"),
+    join(cacheRoot, `linux-${version}`, "chrome-headless-shell-linux64", "chrome-headless-shell"),
+    join(cacheRoot, version, "chrome-headless-shell"),
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Resolve the production netns wrapper script. The wrapper is the
+ * only egress boundary — when it is missing, callers surface a typed
+ * `tier1_unavailable` instead of falling back to a plain exec.
+ */
+export function resolveNetnsWrapper(overrides: { readonly wrapperPath?: string } = {}): string {
+  const override = overrides.wrapperPath ?? readEnv(ENV_NETNS_WRAPPER);
+  if (override !== undefined) return override;
+  const fromRepo = join(process.cwd(), "scripts", "launch-netns.sh");
+  if (existsSync(fromRepo)) return fromRepo;
+  const fromSibling = join(import.meta.dir, "..", "..", "..", "scripts", "launch-netns.sh");
+  return fromSibling;
+}
+
+/**
+ * The Puppeteer-compatible browser args. Every flag here is required:
+ *
+ *   - `--headless=new` selects the modern headless mode that owns the
+ *     same renderer as full Chrome.
+ *   - `--no-sandbox` is OMITTED — we keep Chromium's browser sandbox
+ *     (the netns wrapper passes `--map-current-user` so the user is
+ *     not mapped to root, and the renderer retains its sandbox).
+ *   - `--no-first-run`, `--disable-background-networking`,
+ *     `--disable-component-update`, `--disable-default-apps`,
+ *     `--disable-sync` keep first-launch noise and network from
+ *     contaminating an isolated run.
+ *   - `--user-data-dir=$tmp/...` plus the verifier's profile-mode
+ *     (0o700) keeps the on-disk footprint ephemeral.
+ *
+ * `--single-process --no-zygote` are NOT used. The Phase-0 fidelity
+ * spike relied on them to bound the process tree, but the pinned
+ * The pinned build aborts the CDP target during `newPage()` when
+ * those flags are present (verified empirically against the wrapper).
+ * The multi-process model is fine inside an isolated verifier run
+ * because every renderer lives under the same netns pid and exits
+ * when the wrapper does.
+ *
+ * CDP transport (`--remote-debugging-pipe`) is added by puppeteer-core
+ * itself when `pipe: true` is set on the launch options; the netns
+ * wrapper inherits the pipe through `exec`.
+ */
+export function buildBrowserArgs(userDataDir: string): readonly string[] {
+  return [
+    "--headless=new",
+    "--no-first-run",
+    "--disable-background-networking",
+    "--disable-component-update",
+    "--disable-default-apps",
+    "--disable-sync",
+    "--disable-features=AutofillServerCommunication,OptimizationHints",
+    `--user-data-dir=${userDataDir}`,
+  ];
+}
+
+/**
+ * Resolve every launcher path needed for a single run. Throws a
+ * plain `Error` (not `FacetError`) because the verifier is the only
+ * caller and maps the error into a typed `tier1_launcher_missing` or
+ * `tier1_unavailable` upstream.
+ */
+export function resolveLauncher(
+  level: InsecureLevel,
+  overrides?: LauncherOverrides,
+): ResolvedLauncher;
+export function resolveLauncher(overrides?: LauncherOverrides): ResolvedLauncher;
+export function resolveLauncher(
+  levelOrOverrides: InsecureLevel | LauncherOverrides = 0,
+  passedOverrides: LauncherOverrides = {},
+): ResolvedLauncher {
+  const level = typeof levelOrOverrides === "number" ? levelOrOverrides : 0;
+  const overrides = typeof levelOrOverrides === "number" ? passedOverrides : levelOrOverrides;
+  InsecureLevelSchema.parse(level);
+  const binaryPath = resolveShellBinary({
+    ...(overrides.version !== undefined ? { version: overrides.version } : {}),
+    ...(overrides.cacheRoot !== undefined ? { cacheRoot: overrides.cacheRoot } : {}),
+  });
+  if (binaryPath === null) {
+    throw new Error(
+      `pinned chrome-headless-shell ${overrides.version ?? TIER1_PINNED_VERSION} not found in cache`,
+    );
+  }
+  return {
+    executablePath:
+      level === 0
+        ? resolveNetnsWrapper(
+            overrides.wrapperPath !== undefined ? { wrapperPath: overrides.wrapperPath } : {},
+          )
+        : binaryPath,
+    binaryPath,
+    pinnedVersion: overrides.version ?? TIER1_PINNED_VERSION,
+  };
+}

package/src/validation/tier1/limits.ts

@@ -0,0 +1,80 @@
+/**
+ * Resource caps for the Tier 1 verifier.
+ *
+ * Each cap is named and exposed so the runner, the harness builder,
+ * and the penetration test agree on a single value. A failing cap
+ * produces a typed `FacetError` with the matching `tier1_*` code.
+ */
+
+/**
+ * Wall-clock budget for one Tier 1 verifier invocation. The harness
+ * bundles the REAL renderers (mermaid + marked + vega, ~8 MB inline);
+ * parse + first render of a 40-node fixture needs real headroom.
+ */
+export const TIER1_TIMEOUT_MS = 60_000;
+
+/**
+ * Path to the pinned `chrome-headless-shell` distribution. The release
+ * manifest pins a specific revision; the default resolves the first
+ * match under `~/.cache/puppeteer/chrome-headless-shell/`. Tests inject
+ * a custom resolver so the path does not become load-bearing on a
+ * specific dev workstation.
+ */
+export { TIER1_PINNED_VERSION } from "../../shared/config/limits";
+
+/** Network namespace label recorded with each Tier 1 run. */
+export const TIER1_NETWORK_NAMESPACE = "facet-tier1-egress-isolated";
+
+/** Lifetime of the ephemeral browser user-data directory (mode 0700). */
+export const TIER1_USER_DATA_DIR_MODE = 0o700;
+
+/**
+ * Per-render timeout the verifier waits for the trusted
+ * `render-complete` barrier before classifying the run as `timeout`.
+ * Sized for the real mermaid runtime: first-render initialization of
+ * the bundled runtime plus a 40-node layout must fit inside.
+ */
+export const TIER1_RENDER_BARRIER_MS = 30_000;
+
+/**
+ * Time between the first interactive TSX observation and its bounded
+ * stability re-check. It stays below the headroom after the render barrier so
+ * a typed `partial:unstable` verdict remains observable before Tier 1 times out.
+ */
+export const TSX_STABILITY_WINDOW_MS = 1_000;
+
+/**
+ * Ceiling for any single CDP call. Every protocol round-trip in a
+ * healthy session completes in well under a second; a call that
+ * outlives this budget means the pipe transport silently wedged
+ * (observed: a browser spawned immediately after another browser's
+ * teardown can have its devtools pipe torn down while the process
+ * stays alive — every subsequent call pends forever). The runner
+ * treats the typed rejection as retryable and relaunches once.
+ */
+export const TIER1_CDP_CALL_WATCHDOG_MS = 10_000;
+
+/** Screenshot evidence has a tighter deadline than the verifier transport watchdog. */
+export const TIER1_SCREENSHOT_CAPTURE_TIMEOUT_MS = 2_000;
+export const TIER1_SCREENSHOT_CAPTURE_ATTEMPTS = 2;
+
+/** Deterministic viewport used for Tier 1 layout and screenshot evidence. */
+export const TIER1_VIEWPORT_WIDTH = 1280;
+export const TIER1_VIEWPORT_HEIGHT = 800;
+
+/** Maximum CSS axis length for a whole-artifact evidence image. */
+export const TIER1_SCREENSHOT_MAX_AXIS_PX = 4096;
+
+/** Maximum decoded pixel count for a whole-artifact evidence image. */
+export const TIER1_SCREENSHOT_MAX_PIXELS = 8_388_608;
+
+/** Static evidence uses WebP at this quality. */
+export const TIER1_SCREENSHOT_WEBP_QUALITY = 82;
+
+/** Animated evidence samples four frames at fixed browser-time intervals. */
+export const TIER1_ANIMATION_FRAME_COUNT = 4;
+export const TIER1_ANIMATION_FRAME_INTERVAL_MS = 150;
+export const TIER1_ANIMATION_WEBP_QUALITIES = [TIER1_SCREENSHOT_WEBP_QUALITY, 70, 55] as const;
+
+/** Whole-artifact evidence above this cap after scaling and quality fallback is screenshot_unavailable. */
+export const TIER1_SCREENSHOT_CAP_BYTES = 8 * 1024 * 1024;

package/src/validation/tier1/nonce.ts

@@ -0,0 +1,17 @@
+/**
+ * Per-frame nonce for the Tier 1 verification harness.
+ *
+ * Cryptographically random; the harness pins it into the CSP meta and
+ * the <script nonce> for the same srcdoc so only that inlined bundle
+ * executes. A regression that reuses a nonce across builds would let a
+ * stale bundle survive a CSP bypass attempt.
+ *
+ * Kept separate from gallery-web so the gallery frame bundle cannot
+ * accidentally pull in any Tier 1 import.
+ */
+
+export function freshHarnessNonce(): string {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}