@rightkit/release 0.2.151 → 0.2.154

package/qa-build-features.mjs

@@ -0,0 +1,216 @@
+// Source-level layer of "no test-automation surface ships": a release or update build must not enable the cargo
+// features that compile one in. The binary layer (`qa-control-scan.mjs`) cannot see every surface (a stripped
+// binary, compressed installers), so right-release also refuses, before it builds anything:
+//   - a build command (prePackage, package, native package hook, finalizer) that enables one of the forbidden
+//     features, directly (`--features`, `-F`, `-f`, `--features=`, `--all-features`) or through a package.json
+//     script it runs (`pnpm run <script>`, followed up to three levels);
+//   - an app Cargo.toml whose DEFAULT feature closure reaches one of them, or that lists `devtools` on `tauri`,
+//     (`devtools` and rightkit-tauri-shell's `content-devtools` are accepted only for an allow-listed app, see devtools-policy.mjs)
+//     `qa-control` on `rightkit-qa-driver`, `dev-inspect` on `rightkit-tauri-shell`, or `tauri-plugin-wdio-webdriver` as a non-optional dependency.
+// Dev builds are unaffected: `development.mjs` never calls this.
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+export const FORBIDDEN_FEATURES = Object.freeze(["devtools", "content-devtools", "qa-native", "qa-control", "dev-native", "dev-inspect",
+  // Per-app test-automation features (M20 owner gap): HeardRight `qa-shot`/`qa-tools`, ViewRight `dev-control`/`bench-native`.
+  "qa-shot", "qa-tools", "dev-control", "bench-native",
+  // D4 (M21/M23): rightkit-daemon `test-mode` compiles the override selectors; never in a release build.
+  "test-mode"]);
+// The only forbidden features an allow-listed app may enable: rightkit-tauri-shell's `content-devtools` (and the Tauri
+// `devtools` it switches on). See devtools-policy.mjs; every other app is refused them.
+const DEVTOOLS_FEATURES = Object.freeze(["devtools", "content-devtools"]);
+const FORBIDDEN_DEPENDENCY = "tauri-plugin-wdio-webdriver";
+const MANAGERS = new Set(["pnpm", "npm", "yarn", "bun", "npx"]);
+
+// "dep:foo" -> "foo"; "tauri/devtools" and "tauri?/devtools" -> "devtools".
+function featureName(item) {
+  const bare = String(item).trim().replace(/^dep:/, "");
+  return bare.includes("/") ? bare.slice(bare.lastIndexOf("/") + 1) : bare;
+}
+export function isForbiddenFeature(item, { allowDevtools = false } = {}) {
+  const text = String(item).trim();
+  const name = featureName(text);
+  if (allowDevtools && DEVTOOLS_FEATURES.includes(name)) return false;
+  return text === `dep:${FORBIDDEN_DEPENDENCY}` || FORBIDDEN_FEATURES.includes(name);
+}
+
+export function tokenize(text) {
+  return (String(text).match(/"[^"]*"|'[^']*'|[^\s"']+/g) ?? []).map((t) => t.replace(/^["']|["']$/g, ""));
+}
+
+// Feature names a token list enables, plus whether it asks for every feature.
+export function featuresInTokens(tokens) {
+  const enabled = []; let allFeatures = false;
+  const take = (value) => { for (const part of String(value).split(/[,\s]+/)) if (part) enabled.push(part); };
+  for (let i = 0; i < tokens.length; i += 1) {
+    const t = tokens[i];
+    if (t === "--all-features") allFeatures = true;
+    else if (t === "--features" || t === "-F" || t === "-f" || t === "--feature") { if (i + 1 < tokens.length) take(tokens[i + 1]); }
+    else if (t.startsWith("--features=")) take(t.slice("--features=".length));
+    else if (/^-F.+/.test(t)) take(t.slice(2));
+  }
+  return { enabled, allFeatures };
+}
+
+export function scriptTarget(tokens) {
+  const first = tokens.findIndex((t) => MANAGERS.has(path.basename(t).replace(/\.(cmd|exe)$/i, "")));
+  if (first < 0) return null;
+  let i = first + 1;
+  while (i < tokens.length && tokens[i].startsWith("-")) i += 1;
+  if (["run", "run-script"].includes(tokens[i])) { i += 1; while (i < tokens.length && tokens[i].startsWith("-")) i += 1; }
+  return tokens[i] ?? null;
+}
+
+// Issues (strings) for one command object { cmd, args, env? } or a shell string.
+export function commandFeatureIssues(command, { label = "command", scripts = {}, depth = 0, seen = new Set(), allowDevtools = false } = {}) {
+  const parts = typeof command === "string" ? [command] : [command?.cmd, ...(command?.args ?? [])].filter((v) => v !== undefined).map(String);
+  // Two views: every argument whole (`--features` followed by "a b qa-native"), and every argument re-tokenised as
+  // shell text (`sh -c "cargo build --features qa-native"`).
+  const views = [parts, parts.flatMap((p) => tokenize(p))];
+  const issues = new Set();
+  for (const tokens of views) {
+    const { enabled, allFeatures } = featuresInTokens(tokens);
+    if (allFeatures) issues.add(`${label}: --all-features enables every feature including ${FORBIDDEN_FEATURES.join(", ")}`);
+    for (const feature of enabled) if (isForbiddenFeature(feature, { allowDevtools })) issues.add(`${label}: enables feature \`${feature}\``);
+  }
+  if (command && typeof command === "object") {
+    for (const [key, value] of Object.entries(command.env ?? {})) {
+      if (/FEATURES$/i.test(key)) for (const feature of String(value).split(/[,\s]+/)) if (feature && isForbiddenFeature(feature, { allowDevtools })) issues.add(`${label}: env ${key} enables feature \`${feature}\``);
+    }
+  }
+  const script = views.map(scriptTarget).find(Boolean);
+  if (script && depth < 3 && Object.hasOwn(scripts, script) && !seen.has(script)) {
+    for (const issue of commandFeatureIssues(String(scripts[script]), { label: `${label} -> package script \`${script}\``, scripts, depth: depth + 1, seen: new Set([...seen, script]), allowDevtools })) issues.add(issue);
+  }
+  return [...issues];
+}
+
+// ---- Cargo.toml ---------------------------------------------------------------------------------------------
+function stripComments(text) {
+  let out = ""; let quote = null;
+  for (let i = 0; i < text.length; i += 1) {
+    const c = text[i];
+    if (quote) { out += c; if (c === quote && text[i - 1] !== "\\") quote = null; continue; }
+    if (c === '"' || c === "'") { quote = c; out += c; continue; }
+    if (c === "#") { while (i < text.length && text[i] !== "\n") i += 1; out += "\n"; continue; }
+    out += c;
+  }
+  return out;
+}
+
+function sectionsOf(text) {
+  const sections = []; let current = { name: "", body: "" };
+  for (const line of text.split(/\r?\n/)) {
+    const header = line.match(/^\s*\[\s*([^\[\]]+?)\s*\]\s*$/);
+    if (header) { sections.push(current); current = { name: header[1].replace(/\s+/g, ""), body: "" }; }
+    else current.body += `${line}\n`;
+  }
+  sections.push(current);
+  return sections;
+}
+
+function balanced(text, from, open, close) {
+  let depth = 0; let quote = null;
+  for (let i = from; i < text.length; i += 1) {
+    const c = text[i];
+    if (quote) { if (c === quote && text[i - 1] !== "\\") quote = null; continue; }
+    if (c === '"' || c === "'") quote = c;
+    else if (c === open) depth += 1;
+    else if (c === close) { depth -= 1; if (depth === 0) return text.slice(from, i + 1); }
+  }
+  return text.slice(from);
+}
+
+const strings = (text) => [...String(text).matchAll(/"([^"]*)"|'([^']*)'/g)].map((m) => m[1] ?? m[2]);
+const unquote = (key) => key.replace(/^["']|["']$/g, "");
+
+export function parseCargoFeaturesAndDependencies(manifestText) {
+  const sections = sectionsOf(stripComments(manifestText));
+  const features = new Map(); const dependencies = new Map();
+  for (const { name, body } of sections) {
+    if (name === "features") {
+      for (const m of body.matchAll(/^\s*([A-Za-z0-9_\-"']+)\s*=\s*\[/gm)) {
+        features.set(unquote(m[1]), strings(balanced(body, m.index + m[0].length - 1, "[", "]")));
+      }
+    } else if (/^(?:target\.[^\n]+\.)?dependencies$/.test(name)) {
+      for (const m of body.matchAll(/^\s*([A-Za-z0-9_\-"']+)\s*=\s*(\{)?/gm)) {
+        const depName = unquote(m[1]);
+        const spec = m[2] ? balanced(body, m.index + m[0].length - 1, "{", "}") : "";
+        dependencies.set(depName, dependencyInfo(spec));
+      }
+    } else {
+      const table = name.match(/^(?:target\.[^\n]+\.)?dependencies\.([A-Za-z0-9_\-]+)$/);
+      if (table) dependencies.set(table[1], dependencyInfo(body));
+    }
+  }
+  return { features, dependencies };
+}
+function dependencyInfo(spec) {
+  const list = spec.match(/features\s*=\s*(\[)/);
+  return {
+    optional: /optional\s*=\s*true/.test(spec),
+    features: list ? strings(balanced(spec, list.index + list[0].length - 1, "[", "]")) : [],
+  };
+}
+
+export function cargoManifestIssues(manifestText, label = "Cargo.toml", { allowDevtools = false } = {}) {
+  const { features, dependencies } = parseCargoFeaturesAndDependencies(manifestText);
+  const issues = [];
+  const tauri = dependencies.get("tauri");
+  if (!allowDevtools && tauri?.features.includes("devtools")) issues.push(`${label}: dependency \`tauri\` lists feature \`devtools\` unconditionally (inspector ships in release builds)`);
+  // The crate was renamed from rightkit-control; apps still on the old published name must stay covered.
+  for (const name of ["rightkit-qa-driver", "rightkit-control"]) {
+    const control = dependencies.get(name);
+    if (control && !control.optional && control.features.includes("qa-control")) issues.push(`${label}: dependency \`${name}\` lists \`qa-control\` unconditionally`);
+  }
+  // The crate was renamed from rightkit-shell; apps still on the old published name must stay covered.
+  for (const name of ["rightkit-tauri-shell", "rightkit-shell"]) {
+    const shell = dependencies.get(name);
+    if (shell && !shell.optional && shell.features.includes("dev-inspect")) issues.push(`${label}: dependency \`${name}\` lists \`dev-inspect\` unconditionally (developer inspection ships in release builds)`);
+  }
+  const service = dependencies.get("rightkit-daemon");
+  if (service && !service.optional && service.features.includes("test-mode")) issues.push(`${label}: dependency \`rightkit-daemon\` lists \`test-mode\` unconditionally (test-mode capability ships in release builds)`);
+  const wdio = dependencies.get(FORBIDDEN_DEPENDENCY);
+  if (wdio && !wdio.optional) issues.push(`${label}: dependency \`${FORBIDDEN_DEPENDENCY}\` is not optional`);
+  const reached = new Set(); const stack = [...(features.get("default") ?? [])];
+  while (stack.length) {
+    const item = stack.pop();
+    if (reached.has(item)) continue;
+    reached.add(item);
+    if (isForbiddenFeature(item, { allowDevtools })) issues.push(`${label}: default feature set reaches \`${item}\``);
+    if (features.has(item)) stack.push(...features.get(item));
+  }
+  return issues;
+}
+
+// commands: [{ label, command }]. Reads package.json scripts and the app Cargo manifests under `root`.
+// `devtools`: the allowance resolved by devtools-policy.mjs (mode "content-only") for an allow-listed app, else undefined.
+// Single manifest resolver shared by the closure gate (release-switch-scan.mjs) and the default-feature check below:
+// targets.<os>.cargoManifest -> releaseSwitches.manifest -> src-tauri/Cargo.toml -> Cargo.toml. `rel` is the first
+// candidate that exists (undefined when none does); `declared` are the configured paths.
+export function resolveCargoManifestPath({ root, cargoManifest, manifest } = {}) {
+  const declared = [cargoManifest, manifest].filter(Boolean);
+  const candidates = [...declared, path.join("src-tauri", "Cargo.toml"), "Cargo.toml"];
+  return { rel: candidates.find((c) => existsSync(path.join(root, c))), declared, candidates };
+}
+
+export function buildFeatureIssues({ root, commands, devtools, cargoManifest, manifest }) {
+  const allowDevtools = devtools?.mode === "content-only";
+  let scripts = {};
+  try { scripts = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8")).scripts ?? {}; } catch { /* no package.json */ }
+  const issues = [];
+  for (const { label, command } of commands) if (command) issues.push(...commandFeatureIssues(command, { label, scripts, allowDevtools }));
+  const { rel } = resolveCargoManifestPath({ root, cargoManifest, manifest });
+  if (rel) issues.push(...cargoManifestIssues(readFileSync(path.join(root, rel), "utf8"), rel, { allowDevtools }));
+  return issues;
+}
+
+export function assertNoForbiddenBuildFeatures({ root, commands, tier = "release", devtools, cargoManifest, manifest }) {
+  const issues = buildFeatureIssues({ root, commands, devtools, cargoManifest, manifest });
+  if (issues.length === 0) return;
+  throw new Error(
+    `${tier} build refused: it enables a test-automation or debugging feature (${FORBIDDEN_FEATURES.join(", ")}); none may ship:\n- ${issues.join("\n- ")}\n`
+    + "Remove the feature from the release build command, the app's default features and its tauri dependency; dev builds (`right-release dev`) may keep it. "
+    + "No app may ship devtools unless it is on the allow-list in devtools-policy.json and declares `devtools: \"content-only\"` (rightkit-tauri-shell DevToolsPolicy::ContentOnly).",
+  );
+}

package/qa-control-scan.mjs

@@ -0,0 +1,435 @@
+// Release-blocking scan: a shipped binary must not contain any test-automation or debugging surface.
+//
+// Owner requirement: NO test-automation surface of any kind ships; dev builds may contain them. This module is
+// the binary layer of that rule. It scans Mach-O, PE and ELF files (and the native files inside ZIP-based
+// containers such as MSIX/APPX) for four independent rules, and is called for release and update builds
+// (signing set, staged payloads, hardening targets, sealed files). The development lane (`development.mjs`)
+// never calls it: dev builds are the QA builds. The source-level layer is `qa-build-features.mjs`.
+//
+//   qa-control-server  `rightkit-qa-driver` feature `qa-control`: every binary with the embedded server carries
+//                      QA_CONTROL_MARKER (a `#[used]` static in `embedded/mod.rs`, also read by `Control::build`).
+//   wdio-webdriver     `tauri-plugin-wdio-webdriver` (HeardRight/MailRight/ViewRight `qa-native`): needs 2 of 3
+//                      independent signatures. WEAKER than the marker: the plugin source was not on disk when
+//                      the signatures were chosen, they come from Rust path/module/permission naming rules.
+//   shell-dev-inspect  `rightkit-tauri-shell` feature `dev-inspect` (developer inspection of an app's own webviews): every
+//                      binary built with it carries DEV_INSPECT_MARKER. Refused in every tier this module scans.
+//   remote-debugging   `--remote-debugging-port` / `WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS` baked into a binary.
+//   tauri-devtools     Tauri's `devtools` feature (or a debug build): the toggle-devtools init script. Accepted only for an
+//                      allow-listed app (devtools-policy.json) whose binary carries CONTENT_ONLY_MARKER.
+import { closeSync, lstatSync, openSync, readFileSync, readSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { inflateRawSync } from "node:zlib";
+
+// Keep identical to `QA_CONTROL_MARKER` in crates/rightkit-qa-driver/src/embedded/mod.rs.
+export const QA_CONTROL_MARKER = "RIGHTKIT-QA-CONTROL-SERVER-PRESENT";
+// Keep identical to `DEV_INSPECT_MARKER` in crates/rightkit-tauri-shell/src/devtools.rs (a `#[used]` static compiled only
+// with rightkit-tauri-shell's `dev-inspect` feature and read by the process guard). No allow-list lifts this rule.
+export const DEV_INSPECT_MARKER = "RIGHTKIT-SHELL-DEV-INSPECT-COMPILED";
+const MARKER = Buffer.from(QA_CONTROL_MARKER, "latin1");
+const CHUNK = 4 * 1024 * 1024;
+
+// Each signature is matched as Latin-1/UTF-8 bytes and as UTF-16LE (Windows wide strings). `min` signatures of a
+// rule must be present for it to fire; a signature counts once however often or in whichever encoding it occurs.
+export const QA_RULES = Object.freeze([
+  { id: "qa-control-server", min: 1, label: "RightKit QA control server (rightkit-qa-driver qa-control)",
+    signatures: [{ id: "marker", text: QA_CONTROL_MARKER }] },
+  { id: "shell-dev-inspect", min: 1, marker: DEV_INSPECT_MARKER, label: "rightkit-tauri-shell developer inspection (rightkit-tauri-shell dev-inspect)",
+    signatures: [{ id: "marker", text: DEV_INSPECT_MARKER }] },
+  { id: "wdio-webdriver", min: 2, label: "tauri-plugin-wdio-webdriver test driver (app qa-native/dev-native)",
+    signatures: [
+      { id: "crate-path", text: "tauri-plugin-wdio-webdriver" },
+      { id: "module-path", text: "tauri_plugin_wdio_webdriver" },
+      { id: "permission", text: "wdio-webdriver:default" },
+    ] },
+  { id: "remote-debugging", min: 1, label: "remote-debugging enablement baked into the binary",
+    signatures: [
+      { id: "chromium-flag", text: "--remote-debugging-port" },
+      { id: "webview2-env", text: "WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS" },
+    ] },
+  { id: "tauri-devtools", min: 1, label: "Tauri devtools (feature `devtools` or a debug build)",
+    signatures: [
+      { id: "invoke", text: "plugin:webview|internal_toggle_devtools" },
+      { id: "hotkey-script", text: "toggleDevtoolsHotkey" },
+    ] },
+]);
+
+// Keep identical to `CONTENT_ONLY_MARKER` in crates/rightkit-tauri-shell/src/devtools.rs. A binary carries it when it was
+// built with rightkit-tauri-shell's `content-devtools` feature. It is not a finding; it is the evidence that lets an
+// allow-listed app (devtools-policy.json) ship Tauri's devtools code for ViewRight-style content inspection.
+export const CONTENT_ONLY_MARKER = "RIGHTKIT-SHELL-DEVTOOLS-CONTENT-ONLY-COMPILED";
+const CONTENT_ONLY_KEY = "content-only-marker/marker";
+
+const NEEDLES = [...QA_RULES.flatMap((rule) => rule.signatures.map((signature) => ({
+  rule: rule.id, signature: signature.id,
+  buffers: [Buffer.from(signature.text, "latin1"), Buffer.from(signature.text, "utf16le")],
+}))), {
+  rule: "content-only-marker", signature: "marker",
+  buffers: [Buffer.from(CONTENT_ONLY_MARKER, "latin1"), Buffer.from(CONTENT_ONLY_MARKER, "utf16le")],
+}];
+const MAX_NEEDLE = Math.max(...NEEDLES.flatMap((n) => n.buffers.map((b) => b.length)));
+
+// Incremental matcher: feed chunks in order; keeps an overlap so a signature split across chunks is found.
+export class RuleScanner {
+  constructor() { this.tail = Buffer.alloc(0); this.hits = new Map(); }
+  push(chunk) {
+    const window = this.tail.length ? Buffer.concat([this.tail, chunk]) : chunk;
+    for (const needle of NEEDLES) {
+      const key = `${needle.rule}/${needle.signature}`;
+      if (this.hits.has(key)) continue;
+      if (needle.buffers.some((b) => window.includes(b))) this.hits.set(key, needle);
+    }
+    this.tail = Buffer.from(window.subarray(Math.max(0, window.length - (MAX_NEEDLE - 1))));
+  }
+  // `allowContentOnlyDevtools`: the app is allow-listed for rightkit-tauri-shell's ContentOnly DevTools policy. Then Tauri's
+  // devtools signatures are accepted only in a binary that also carries CONTENT_ONLY_MARKER; one without it is still
+  // a finding (devtools compiled in by some other route).
+  findings({ allowContentOnlyDevtools = false } = {}) {
+    const out = [];
+    for (const rule of QA_RULES) {
+      if (rule.id === "tauri-devtools" && allowContentOnlyDevtools && this.hits.has(CONTENT_ONLY_KEY)) continue;
+      const matched = rule.signatures.filter((s) => this.hits.has(`${rule.id}/${s.id}`));
+      if (matched.length < rule.min) continue;
+      out.push({ rule: rule.id, reason: rule.id === "qa-control-server" || rule.marker
+        ? `contains ${rule.marker ?? QA_CONTROL_MARKER}`
+        : `${rule.label}: ${matched.length} of ${rule.signatures.length} signatures (${matched.map((s) => s.text).join(", ")})` });
+    }
+    return out;
+  }
+}
+
+// Mach-O thin (both endians, 32/64-bit), fat/universal (0xCAFEBABE, 0xCAFEBABF), PE ("MZ"), ELF.
+const MAGICS = [
+  [0xfe, 0xed, 0xfa, 0xce], [0xfe, 0xed, 0xfa, 0xcf], [0xce, 0xfa, 0xed, 0xfe], [0xcf, 0xfa, 0xed, 0xfe],
+  [0xca, 0xfe, 0xba, 0xbe], [0xca, 0xfe, 0xba, 0xbf], [0x7f, 0x45, 0x4c, 0x46],
+].map((bytes) => Buffer.from(bytes));
+const MZ = Buffer.from([0x4d, 0x5a]);
+
+export function isNativeBinaryHeader(head) {
+  if (!Buffer.isBuffer(head)) return false;
+  if (head.length >= 2 && head.subarray(0, 2).equals(MZ)) return true;
+  return MAGICS.some((magic) => head.length >= 4 && head.subarray(0, 4).equals(magic));
+}
+
+export function isZipHeader(head) {
+  return Buffer.isBuffer(head) && head.length >= 4 && head[0] === 0x50 && head[1] === 0x4b
+    && ((head[2] === 0x03 && head[3] === 0x04) || (head[2] === 0x05 && head[3] === 0x06));
+}
+
+export function bufferHasQaControlMarker(buffer) {
+  return Buffer.from(buffer).includes(MARKER);
+}
+
+// All rules over one in-memory buffer (a sealed file). Looks inside ZIP containers too.
+export function bufferQaFindings(buffer, options = {}) {
+  const bytes = Buffer.from(buffer);
+  if (isZipHeader(bytes.subarray(0, 4))) {
+    const findings = []; const stats = newStats();
+    scanZip(bufferSource(bytes), "<buffer>", { findings, stats, allowContentOnlyDevtools: options.allowContentOnlyDevtools === true, limits: limitsOf(options), budget: { left: limitsOf(options).totalInflated } }, 0);
+    return findings;
+  }
+  const scanner = new RuleScanner();
+  for (let at = 0; at < bytes.length; at += CHUNK) scanner.push(bytes.subarray(at, Math.min(bytes.length, at + CHUNK)));
+  return scanner.findings({ allowContentOnlyDevtools: options.allowContentOnlyDevtools === true });
+}
+
+// Streams the file in chunks with an overlap, so a marker split across chunks is found. Marker rule only.
+export function fileHasQaControlMarker(file) {
+  const fd = openSync(file, "r");
+  try {
+    const buffer = Buffer.alloc(CHUNK);
+    let tail = Buffer.alloc(0);
+    for (;;) {
+      const read = readSync(fd, buffer, 0, CHUNK, null);
+      if (read === 0) return false;
+      const window = Buffer.concat([tail, buffer.subarray(0, read)]);
+      if (window.includes(MARKER)) return true;
+      tail = Buffer.from(window.subarray(Math.max(0, window.length - (MARKER.length - 1))));
+    }
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function readHead(file) {
+  const fd = openSync(file, "r");
+  try {
+    const head = Buffer.alloc(4);
+    const read = readSync(fd, head, 0, 4, 0);
+    return head.subarray(0, read);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+// ---- byte sources and the ZIP reader ------------------------------------------------------------------------
+const DEFAULT_LIMITS = Object.freeze({
+  maxEntries: 100_000,
+  maxCentralDirectory: 256 * 1024 * 1024,
+  maxEntryBytes: 1024 * 1024 * 1024, // largest single entry we will inflate in memory
+  totalInflated: 8 * 1024 * 1024 * 1024, // zip-bomb budget per scanned container
+  maxDepth: 3,
+});
+const limitsOf = (options) => ({ ...DEFAULT_LIMITS, ...(options.limits ?? {}) });
+const newStats = () => ({ binaries: 0, containers: 0, entries: 0, opaque: [] });
+
+function bufferSource(buffer) {
+  return { size: buffer.length, read: (position, length) => buffer.subarray(position, position + length) };
+}
+function fdSource(fd, size) {
+  return { size, read: (position, length) => {
+    const out = Buffer.alloc(length); let got = 0;
+    while (got < length) {
+      const n = readSync(fd, out, got, length - got, position + got);
+      if (n === 0) break;
+      got += n;
+    }
+    return out.subarray(0, got);
+  } };
+}
+const sliceSource = (source, start, length) => ({ size: length, read: (position, n) => source.read(start + position, Math.min(n, length - position)) });
+
+function u64(buffer, offset) {
+  const value = buffer.readBigUInt64LE(offset);
+  if (value > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error("zip64 value out of range");
+  return Number(value);
+}
+
+function readEndOfCentralDirectory(source) {
+  const tailLength = Math.min(source.size, 22 + 65535);
+  const tail = source.read(source.size - tailLength, tailLength);
+  for (let i = tail.length - 22; i >= 0; i -= 1) {
+    if (tail.readUInt32LE(i) !== 0x06054b50) continue;
+    if (i + 22 + tail.readUInt16LE(i + 20) > tail.length) continue;
+    let entries = tail.readUInt16LE(i + 10); let size = tail.readUInt32LE(i + 12); let offset = tail.readUInt32LE(i + 16);
+    if (entries === 0xffff || size === 0xffffffff || offset === 0xffffffff) {
+      const eocdPosition = source.size - tailLength + i;
+      if (eocdPosition < 20) throw new Error("zip64 locator missing");
+      const locator = source.read(eocdPosition - 20, 20);
+      if (locator.length < 20 || locator.readUInt32LE(0) !== 0x07064b50) throw new Error("zip64 locator missing");
+      const record = source.read(u64(locator, 8), 56);
+      if (record.length < 56 || record.readUInt32LE(0) !== 0x06064b50) throw new Error("zip64 end record missing");
+      entries = u64(record, 32); size = u64(record, 40); offset = u64(record, 48);
+    }
+    return { entries, size, offset };
+  }
+  throw new Error("end of central directory not found");
+}
+
+function* zipEntries(source, limits) {
+  const eocd = readEndOfCentralDirectory(source);
+  if (eocd.entries > limits.maxEntries) throw new Error(`more than ${limits.maxEntries} entries`);
+  if (eocd.size > limits.maxCentralDirectory || eocd.offset + eocd.size > source.size) throw new Error("central directory out of bounds");
+  const directory = source.read(eocd.offset, eocd.size);
+  if (directory.length !== eocd.size) throw new Error("central directory truncated");
+  let at = 0;
+  for (let n = 0; n < eocd.entries; n += 1) {
+    if (at + 46 > directory.length || directory.readUInt32LE(at) !== 0x02014b50) throw new Error("bad central directory entry");
+    const flags = directory.readUInt16LE(at + 8); const method = directory.readUInt16LE(at + 10);
+    let compressed = directory.readUInt32LE(at + 20); let uncompressed = directory.readUInt32LE(at + 24);
+    const nameLength = directory.readUInt16LE(at + 28); const extraLength = directory.readUInt16LE(at + 30);
+    const commentLength = directory.readUInt16LE(at + 32); let localOffset = directory.readUInt32LE(at + 42);
+    const end = at + 46 + nameLength + extraLength + commentLength;
+    if (end > directory.length) throw new Error("central directory entry out of bounds");
+    const name = directory.subarray(at + 46, at + 46 + nameLength).toString("utf8");
+    const extra = directory.subarray(at + 46 + nameLength, at + 46 + nameLength + extraLength);
+    for (let e = 0; e + 4 <= extra.length;) {
+      const id = extra.readUInt16LE(e); const size = extra.readUInt16LE(e + 2);
+      if (id === 0x0001) {
+        let p = e + 4;
+        if (uncompressed === 0xffffffff) { uncompressed = u64(extra, p); p += 8; }
+        if (compressed === 0xffffffff) { compressed = u64(extra, p); p += 8; }
+        if (localOffset === 0xffffffff) { localOffset = u64(extra, p); }
+      }
+      e += 4 + size;
+    }
+    yield { name, flags, method, compressed, uncompressed, localOffset };
+    at = end;
+  }
+}
+
+function entryDataStart(source, entry) {
+  const local = source.read(entry.localOffset, 30);
+  if (local.length < 30 || local.readUInt32LE(0) !== 0x04034b50) throw new Error("bad local header");
+  const start = entry.localOffset + 30 + local.readUInt16LE(26) + local.readUInt16LE(28);
+  if (start + entry.compressed > source.size) throw new Error("entry data out of bounds");
+  return start;
+}
+
+function pushBuffer(scanner, buffer) {
+  for (let at = 0; at < buffer.length; at += CHUNK) scanner.push(buffer.subarray(at, Math.min(buffer.length, at + CHUNK)));
+}
+
+function scanZip(source, label, ctx, depth) {
+  const { findings, stats, limits } = ctx;
+  const bad = (file, why) => findings.push({ file, rule: "unscannable", reason: `could not scan: ${why}` });
+  if (depth > limits.maxDepth) { bad(label, `containers nested deeper than ${limits.maxDepth}`); return; }
+  stats.containers += 1;
+  try {
+    for (const entry of zipEntries(source, limits)) {
+      if (entry.name.endsWith("/")) continue;
+      stats.entries += 1;
+      const file = `${label}!/${entry.name}`;
+      try {
+        if (entry.flags & 1) { bad(file, "encrypted entry"); continue; }
+        const start = entryDataStart(source, entry);
+        let body; // a byte source for the entry's content
+        if (entry.method === 0) {
+          body = sliceSource(source, start, entry.compressed);
+        } else if (entry.method === 8) {
+          if (entry.uncompressed > limits.maxEntryBytes || entry.compressed > limits.maxEntryBytes) { bad(file, `entry larger than ${limits.maxEntryBytes} bytes`); continue; }
+          if ((ctx.budget.left -= entry.uncompressed) < 0) { bad(file, "container exceeds its inflate budget"); continue; }
+          const inflated = inflateRawSync(source.read(start, entry.compressed), { maxOutputLength: Math.max(1, Math.min(limits.maxEntryBytes, entry.uncompressed + 1)) });
+          body = bufferSource(inflated);
+        } else {
+          bad(file, `unsupported compression method ${entry.method}`); continue;
+        }
+        scanBody(body, file, ctx, depth);
+      } catch (error) { bad(file, error.message); }
+    }
+  } catch (error) { bad(label, `invalid ZIP container (${error.message})`); }
+}
+
+// A byte source holding one file's content: ZIP -> recurse; native binary -> run the rules; anything else ignored.
+function scanBody(body, file, ctx, depth) {
+  const head = body.read(0, 4);
+  if (isZipHeader(head)) { scanZip(body, file, ctx, depth + 1); return; }
+  if (!isNativeBinaryHeader(head)) return;
+  ctx.stats.binaries += 1;
+  const scanner = new RuleScanner();
+  for (let at = 0; at < body.size; at += CHUNK) scanner.push(body.read(at, Math.min(CHUNK, body.size - at)));
+  for (const finding of scanner.findings({ allowContentOnlyDevtools: ctx.allowContentOnlyDevtools === true })) ctx.findings.push({ file, ...finding });
+}
+
+// ---- directory / file / container entry point ---------------------------------------------------------------
+// Returns { findings, stats }. Fails closed: a path that cannot be read is a finding, not a pass. Directories (a
+// `.app`, a staging dir) are walked. Symlinks are not followed (they would escape the bundle). A file with a ZIP
+// header (MSIX, APPX, zip) is read through its central directory and each entry is scanned (stored or deflate).
+export function scanWithStats(paths, options = {}) {
+  const limits = limitsOf(options);
+  const findings = [];
+  const stats = newStats();
+  const visit = (target) => {
+    let stat;
+    try { stat = lstatSync(target); } catch (error) { findings.push({ file: target, rule: "unscannable", reason: `could not scan: ${error.code ?? error.message}` }); return; }
+    if (stat.isSymbolicLink()) return;
+    if (stat.isDirectory()) {
+      let names;
+      try { names = readdirSync(target); } catch (error) { findings.push({ file: target, rule: "unscannable", reason: `could not list: ${error.code ?? error.message}` }); return; }
+      for (const name of names.sort()) visit(path.join(target, name));
+      return;
+    }
+    if (!stat.isFile()) return;
+    let fd;
+    try {
+      const head = readHead(target);
+      const isZip = isZipHeader(head);
+      if (!isZip && !isNativeBinaryHeader(head)) {
+        if (/\.dmg$/i.test(target)) stats.opaque.push({ file: target, kind: "dmg" });
+        return;
+      }
+      fd = openSync(target, "r");
+      const source = fdSource(fd, stat.size);
+      if (isZip) { scanZip(source, target, { findings, stats, allowContentOnlyDevtools: options.allowContentOnlyDevtools === true, limits, budget: { left: limits.totalInflated } }, 0); return; }
+      stats.binaries += 1;
+      const scanner = new RuleScanner();
+      for (let at = 0; at < stat.size; at += CHUNK) scanner.push(source.read(at, Math.min(CHUNK, stat.size - at)));
+      if (looksLikeNsis(source, stat.size)) stats.opaque.push({ file: target, kind: "nsis" });
+      for (const finding of scanner.findings({ allowContentOnlyDevtools: options.allowContentOnlyDevtools === true })) findings.push({ file: target, ...finding });
+    } catch (error) {
+      findings.push({ file: target, rule: "unscannable", reason: `could not scan: ${error.code ?? error.message}` });
+    } finally {
+      if (fd !== undefined) closeSync(fd);
+    }
+  };
+  for (const target of paths) visit(path.resolve(target));
+  return { findings, stats };
+}
+
+// NSIS installers carry the "NullsoftInst" signature in their first-stage header; the payload behind it is
+// LZMA/zlib compressed, so the rules cannot see inside it.
+const NSIS_SIGNATURE = Buffer.from("NullsoftInst", "latin1");
+function looksLikeNsis(source, size) {
+  const window = Math.min(size, 4 * 1024 * 1024);
+  return source.read(0, window).includes(NSIS_SIGNATURE);
+}
+
+export function scanForQaControl(paths, options = {}) {
+  return scanWithStats(paths, options).findings;
+}
+
+// `requireBinary`: fail when the scanned inputs contain no native binary at all (a missing or empty staging
+// directory must not read as "clean"). Returns the scan stats so a caller can report what stayed unscannable.
+export function assertNoQaControl(paths, label = "release", { requireBinary = false, limits, allowContentOnlyDevtools = false } = {}) {
+  const { findings, stats } = scanWithStats(paths, { limits, allowContentOnlyDevtools });
+  if (requireBinary && stats.binaries === 0 && findings.length === 0) {
+    findings.push({ file: paths.join(", ") || "<none>", rule: "unscannable", reason: "no Mach-O, PE or ELF file found to scan (missing or empty staging input); cannot verify" });
+  }
+  if (findings.length === 0) return stats;
+  throw new Error(
+    `${label}: the QA control server and every other test-automation or debugging surface must never ship (wdio WebDriver plugin, remote debugging, Tauri devtools); `
+    + `${findings.length} finding(s):\n${findings.map((f) => `- ${f.file}: ${f.reason}`).join("\n")}\n`
+    + "Build release and update tiers without the app's qa-native, dev-native, qa-control and devtools features.",
+  );
+}
+
+// ---- web-bundle mock scan (M20 owner gap) ----------------------------------------------------------------------
+// The binary scan above is blind to the frontend bundle (a Vite `dist/`, a Tauri `frontendDist`, an installer
+// payload folder). An app's in-page QA mock (HeardRight tauriQaMock, GenRight browser-mock-api, ScrapeRight and
+// MailRight qaMock, PostRight MockDataSource) must never be reachable from a release bundle. Each marker is a
+// string that survives minification (an identifier that is also a string literal, a file/chunk name, a protocol or
+// a build-flag name). Source maps are scanned too: a map that names qaMock.ts proves the module was bundled.
+export const WEB_MOCK_MARKERS = Object.freeze([
+  { id: "browser-qa-fake", pattern: /browser-qa-fake/ },
+  { id: "browser-mock-api", pattern: /browser-mock-api/ },
+  { id: "browser-qa-mock-scheme", pattern: /browser-qa-mock:/ },
+  { id: "qaMock", pattern: /qaMock/ },
+  { id: "tauriQaMock", pattern: /tauriQaMock/ },
+  { id: "isBrowserQaMode", pattern: /isBrowserQaMode/ },
+  { id: "MockDataSource", pattern: /MockDataSource/ },
+  { id: "qa-build-flag", pattern: /\bVITE_[A-Z0-9_]*_QA\b/ },
+]);
+const WEB_EXTENSIONS = /\.(?:m?js|cjs|html?|css|map)$/i;
+
+export function webBundleMockFindings(text) {
+  const out = [];
+  for (const marker of WEB_MOCK_MARKERS) {
+    const match = marker.pattern.exec(text);
+    if (match) out.push({ rule: "web-bundle-mock", marker: marker.id, reason: `web bundle carries browser-QA mock marker \`${match[0]}\`` });
+  }
+  return out;
+}
+
+// Walks files and directories (symlinks not followed, as in the binary scan). Fails closed on an unreadable path
+// and, with `requireFiles`, on an input that holds no scannable web file at all.
+export function scanWebBundle(paths, { requireFiles = false } = {}) {
+  const findings = []; let files = 0;
+  const visit = (target) => {
+    let stat;
+    try { stat = lstatSync(target); } catch (error) { findings.push({ file: target, rule: "unscannable", reason: `could not scan: ${error.code ?? error.message}` }); return; }
+    if (stat.isSymbolicLink()) return;
+    if (stat.isDirectory()) {
+      let names;
+      try { names = readdirSync(target); } catch (error) { findings.push({ file: target, rule: "unscannable", reason: `could not list: ${error.code ?? error.message}` }); return; }
+      for (const name of names.sort()) visit(path.join(target, name));
+      return;
+    }
+    if (!stat.isFile() || !WEB_EXTENSIONS.test(target)) return;
+    files += 1;
+    try {
+      for (const finding of webBundleMockFindings(readFileSync(target, "utf8"))) findings.push({ file: target, ...finding });
+    } catch (error) { findings.push({ file: target, rule: "unscannable", reason: `could not scan: ${error.code ?? error.message}` }); }
+  };
+  for (const target of paths) visit(path.resolve(target));
+  if (requireFiles && files === 0 && findings.length === 0) findings.push({ file: paths.join(", ") || "<none>", rule: "unscannable", reason: "no web bundle file (.js, .html, .css) found to scan; cannot verify" });
+  return { findings, files };
+}
+
+export function assertNoWebBundleMocks(paths, label = "release", { requireFiles = false } = {}) {
+  const { findings, files } = scanWebBundle(paths, { requireFiles });
+  if (findings.length === 0) return { files };
+  throw new Error(
+    `${label}: a release web bundle must not contain browser-QA mocks or test-mode markers; ${findings.length} finding(s):\n`
+    + `${findings.map((f) => `- ${f.file}: ${f.reason}`).join("\n")}\n`
+    + "Exclude the mock from the production build (dynamic import behind a build-time constant that tree-shakes, or a separate entry).",
+  );
+}