@bongos/core 1.18.19 → 1.19.3

package/modules/security/artifact-scan/floor.js

@@ -0,0 +1,319 @@
+// modules/security/artifact-scan/floor.js — the zero-LLM deterministic floor
+// (task 1002544, goal 1000055).
+//
+// The floor's whole purpose is that a successful prompt injection cannot erase
+// its own evidence: this report is computed by CODE and written to disk BEFORE
+// any model reads a byte of the artifact. A panel can add findings on top; the
+// reducer takes the MAXIMUM of this floor and everything downstream, so
+// nothing a model says can lower what the detectors already proved.
+//
+// The floor reads the PRISTINE copy, not the mirror. Code is immune to
+// persuasion, so the injection-safety argument for the mirror does not apply —
+// and the mirror is scrubbed, so codepoint evidence EXISTS only in pristine.
+// Reads follow the same confinement discipline as mirror.js: manifest-driven,
+// lexically checked before any fs call, realpath-verified inside the pen.
+//
+// Verdict arithmetic (monotone by construction):
+//   any critical finding  → 'dangerous'
+//   any finding at all    → 'caution'
+//   no findings           → 'clean'
+// A detector that crashes contributes a finding (never silence), so a broken
+// detector degrades the verdict toward caution rather than toward clean.
+
+'use strict';
+
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const { TextDecoder } = require('node:util');
+
+const { isInside } = require('./quarantine');
+const { MIRROR_CAPS } = require('./mirror');
+const { scrubUntrusted } = require('./fence-local');
+const { finding, isSensitivePath, SEVERITIES, excerpt } = require('./detectors/shared');
+
+const npmLifecycle = require('./detectors/npm-lifecycle');
+const hooks = require('./detectors/hooks');
+const mcp = require('./detectors/mcp');
+const permissions = require('./detectors/permissions');
+const credentials = require('./detectors/credentials');
+const network = require('./detectors/network');
+const injection = require('./detectors/injection');
+const dependencies = require('./detectors/dependencies');
+const configObfuscation = require('./detectors/config-obfuscation');
+const capabilities = require('./detectors/capabilities');
+
+const FLOOR_VERSION = '1.0.0';
+const REPORT_BASENAME = 'floor-report.json';
+
+// Bounds on the fetch-stage fold (see runFloor's extraFindings).
+const MAX_EXTRA_FINDINGS = 500;
+const CODE_MAX_CHARS = 64;
+
+// Shared with the reducer (task 1002545): the max() it takes is over this rank.
+const VERDICT_RANK = Object.freeze({ clean: 0, caution: 1, dangerous: 2 });
+
+const UTF8_STRICT = new TextDecoder('utf-8', { fatal: true });
+
+const DETECTORS = Object.freeze([
+  ['npm-lifecycle', npmLifecycle.detect],
+  ['claude-hooks', hooks.detect],
+  ['mcp-servers', mcp.detect],
+  ['permissions', permissions.detect],
+  ['credential-stores', credentials.detect],
+  ['network-sinks', network.detect],
+  ['injection-text', injection.detect],
+  ['dependencies', dependencies.detect],
+  ['config-obfuscation', configObfuscation.detect],
+]);
+
+// Per-chunk parallel-read width. Bounded so a huge artifact cannot exhaust
+// file descriptors; chunked (not a free-running pool) so files[]/skipped[]
+// keep deterministic manifest order.
+const READ_CONCURRENCY = 16;
+
+// Manifest-driven confined read of every renderable text file. Anything the
+// floor cannot honestly read (binary, oversize, escaping, unreadable) becomes
+// a skipped record — counted, never silently dropped — because "I did not read
+// it" must always be visible to the reducer's coverage cap.
+async function buildCorpus({ pristineDir, quarantineRoot, entries, caps = {}, realQuarantine: realQuarantineIn = null }) {
+  const maxFileBytes = caps.maxFileBytes ?? MIRROR_CAPS.maxFileBytes;
+  const realQuarantine = realQuarantineIn || await fsp.realpath(quarantineRoot);
+
+  // One entry → { file } | { skip }, so chunked parallel reads reassemble in
+  // manifest order below. The RAW rel is used for every filesystem operation;
+  // the STORED path is scrubbed at this chokepoint, because manifest paths are
+  // artifact-controlled and corpus records flow into the report (coverage,
+  // capability inventory) — the report must never become a carrier.
+  const readOne = async (entry) => {
+    const rel = entry.path;
+    const safeRel = scrubUntrusted(rel);
+    const skip = (reason, bytes) => ({ skip: { path: safeRel, reason, bytes: bytes || 0 } });
+    if (entry.kind !== 'file') return skip(entry.kind === 'symlink' ? 'symlink' : 'special', entry.size);
+    if (typeof rel !== 'string' || rel.length === 0 || path.isAbsolute(rel)
+      || !isInside(pristineDir, path.resolve(pristineDir, ...rel.split('/')))) {
+      return skip('path_escape', entry.size);
+    }
+    if (entry.size > maxFileBytes) return skip('oversize', entry.size);
+
+    const abs = path.resolve(pristineDir, ...rel.split('/'));
+    let buf;
+    try {
+      const real = await fsp.realpath(abs);
+      if (!isInside(realQuarantine, real)) return skip('path_escape', entry.size);
+      const st = await fsp.lstat(abs);
+      if (st.isSymbolicLink()) return skip('path_escape', entry.size);
+      // Read the verified resolved path — same TOCTOU close as mirror.js.
+      buf = await fsp.readFile(real);
+    } catch {
+      return skip('unreadable', entry.size);
+    }
+
+    try {
+      return { file: { path: safeRel, size: buf.length, text: UTF8_STRICT.decode(buf) } };
+    } catch {
+      return skip('non_utf8', buf.length);
+    }
+  };
+
+  const files = [];
+  const skipped = [];
+  for (let i = 0; i < entries.length; i += READ_CONCURRENCY) {
+    const chunk = await Promise.all(entries.slice(i, i + READ_CONCURRENCY).map(readOne));
+    for (const r of chunk) {
+      if (r.file) files.push(r.file);
+      else skipped.push(r.skip);
+    }
+  }
+  return { files, skipped };
+}
+
+function computeFloorVerdict(findings) {
+  if (findings.some((f) => f.severity === 'critical')) return 'dangerous';
+  return findings.length > 0 ? 'caution' : 'clean';
+}
+
+function countBySeverity(findings) {
+  const counts = { critical: 0, high: 0, medium: 0, low: 0 };
+  for (const f of findings) counts[f.severity] = (counts[f.severity] || 0) + 1;
+  return counts;
+}
+
+// The same-file join: a file that both names a credential store AND carries a
+// network sink. Labeled exactly "same-file co-occurrence" — the floor has no
+// dataflow analysis and must never imply one; co-location is opportunity, and
+// opportunity inside one file is the strongest static exfil signal we can
+// honestly claim.
+function coOccurrence(corpus) {
+  const creds = credentials.perFileHits(corpus);
+  const sinks = network.perFileHits(corpus);
+  const findings = [];
+  for (const [file, credHits] of creds) {
+    const sinkHits = sinks.get(file);
+    if (!sinkHits) continue;
+    // Only FILE-class credential hits (a concrete on-disk secret path) arm this
+    // critical. An env-var NAME next to a fetch() is the single most common
+    // shape in ordinary tooling, so it must not be the read half of a
+    // read-then-send accusation — it still stands as its own medium finding.
+    const fileCreds = credHits.filter((h) => h.klass === 'file');
+    if (fileCreds.length === 0) continue;
+    findings.push(finding('read_then_send_same_file', 'critical', file,
+      `Same-file co-occurrence: names ${fileCreds[0].label} (line ${fileCreds[0].line}) AND carries ${sinkHits[0].label} (line ${sinkHits[0].line}). Co-location, not proven dataflow.`,
+      {
+        credential_stores: fileCreds.map((h) => h.label),
+        network_sinks: sinkHits.map((h) => h.label),
+        claimed_as: 'same-file co-occurrence, not dataflow',
+      }));
+  }
+  return findings;
+}
+
+// Coverage findings: a skip is only honest if it cannot resolve to "clean". A
+// skipped SENSITIVE file (a config that changes what the harness/installer
+// does) becomes a finding; an artifact NONE of whose bytes were readable
+// becomes a finding. Both keep the floor's own verdict off 'clean' when
+// executable/config content went unreviewed — the header's promise that
+// unreviewed never reads as clean, enforced in the floor itself and not left to
+// the downstream reducer alone.
+function coverageFindings(corpus) {
+  const findings = [];
+  for (const s of corpus.skipped) {
+    if (isSensitivePath(s.path)) {
+      findings.push(finding('unreviewed_sensitive_file', 'high', s.path,
+        `A security-relevant file was skipped (${s.reason}) and never reviewed — the installer/harness can still read it.`,
+        { reason: s.reason, bytes: s.bytes || 0 }));
+    }
+  }
+  if (corpus.files.length === 0 && corpus.skipped.length > 0) {
+    findings.push(finding('nothing_readable', 'high', '(floor)',
+      `None of the artifact's ${corpus.skipped.length} file(s) were readable as text — the floor reviewed nothing.`,
+      { skipped: corpus.skipped.length }));
+  }
+  return findings;
+}
+
+// Run every detector crash-isolated: a detector that throws yields a finding,
+// never a hole in the report. `detectors` is injectable so the crash-isolation
+// contract is unit-testable with a deliberately-throwing detector.
+function runDetectors(corpus, detectors = DETECTORS) {
+  const findings = [];
+  const errors = [];
+  for (const [name, detect] of detectors) {
+    try {
+      findings.push(...detect(corpus));
+    } catch (err) {
+      errors.push({ detector: name, error: String(err && err.message ? err.message : err) });
+      findings.push(finding('detector_error', 'high', '(floor)',
+        `Detector "${name}" crashed — its surface is UNREVIEWED and counts against coverage, not toward clean.`,
+        { detector: name }));
+    }
+  }
+  return { findings, errors };
+}
+
+// Build + persist the floor report. Returns the report object; the file at
+// <quarantineRoot>/floor-report.json is on disk before this resolves — callers
+// (the skill) MUST await this before any model reads a byte.
+//
+// `extraFindings` carries code-computed evidence produced BEFORE the floor ran
+// — fetchArtifact's findings (unfetched submodules, surviving symlinks,
+// non-regular nodes). They belong in the persisted report for the same reason
+// every detector finding does: they are arithmetic, not opinion, and the
+// reducer takes its floor component from this report. Routing them only to a
+// chat summary let a repo whose submodule was never fetched reduce to CLEAN
+// (review finding) — an artifact with unreviewed code must never read as clean.
+async function runFloor({ pristineDir, quarantineRoot, entries, sha = null, contentHash = null, caps = {}, extraFindings = [] }) {
+  // Resolved once, shared by the corpus reads and the persist below. Allowed to
+  // throw: an unresolvable pen means no report can honestly land anywhere.
+  const realQuarantine = await fsp.realpath(quarantineRoot);
+  let corpus = { files: [], skipped: [] };
+  let corpusError = null;
+  try {
+    corpus = await buildCorpus({ pristineDir, quarantineRoot, entries, caps, realQuarantine });
+  } catch (err) {
+    corpusError = String(err && err.message ? err.message : err);
+  }
+
+  const { findings, errors } = runDetectors(corpus);
+  // Each post-detector step is crash-isolated too: the whole point of the floor
+  // is that a report ALWAYS lands, so a throw in co-occurrence, the coverage
+  // pass, or the capability inventory must degrade to a finding, never abort
+  // the persist. isolate() runs a step, appends its result, and on a throw
+  // records a detector_error (which contributes caution) instead of propagating.
+  const isolate = (name, fn) => {
+    try { return fn(); }
+    catch (err) {
+      errors.push({ detector: name, error: String(err && err.message ? err.message : err) });
+      findings.push(finding('detector_error', 'high', '(floor)',
+        `Step "${name}" crashed — its surface is UNREVIEWED and counts against coverage, not toward clean.`, { detector: name }));
+      return null;
+    }
+  };
+
+  findings.push(...(isolate('co-occurrence', () => coOccurrence(corpus)) || []));
+  findings.push(...(isolate('coverage', () => coverageFindings(corpus)) || []));
+  // Re-built through finding() so fetch-stage strings get the same scrub + cap
+  // every other finding gets — a caller's array is untrusted input here too.
+  // `code` does NOT pass through finding()'s chokepoint (it is a label, not a
+  // quoted string), so it is scrubbed + capped explicitly here; and the array
+  // is length-capped, because an unbounded fold would let one stage balloon
+  // the persisted report.
+  findings.push(...(isolate('fetch-stage', () => (Array.isArray(extraFindings) ? extraFindings : [])
+    .filter((f) => f && typeof f === 'object')
+    .slice(0, MAX_EXTRA_FINDINGS)
+    .map((f) => finding(
+      excerpt(String(f.code || 'fetch_finding'), CODE_MAX_CHARS),
+      SEVERITIES.includes(f.severity) ? f.severity : 'high',
+      String(f.file || '(fetch)'),
+      String(f.message || ''),
+      f.detail ?? null
+    ))) || []));
+  const capabilityInventory = isolate('capabilities', () => capabilities.inventory(corpus)) || [];
+  if (corpusError) {
+    findings.push(finding('corpus_error', 'high', '(floor)',
+      'The floor could not read the artifact tree at all — nothing here was reviewed.', { error: corpusError }));
+  }
+
+  const report = {
+    floor_version: FLOOR_VERSION,
+    detectors_run: DETECTORS.map(([name]) => name),
+    detector_errors: errors,
+    generated_at: new Date().toISOString(),
+    target: { sha, content_hash: contentHash },
+    findings,
+    counts: countBySeverity(findings),
+    floor_verdict: computeFloorVerdict(findings),
+    // Printed, never scored — the reader's power budget for the artifact.
+    capabilities: capabilityInventory,
+    coverage: {
+      files_read: corpus.files.length,
+      bytes_read: corpus.files.reduce((sum, f) => sum + f.size, 0),
+      files_skipped: corpus.skipped,
+      bytes_skipped: corpus.skipped.reduce((sum, s) => sum + (s.bytes || 0), 0),
+    },
+  };
+
+  // Atomic persist inside the pen: write-then-rename so a crash mid-write can
+  // never leave a half-valid report a later stage might trust. Persist is the
+  // one step that MUST be allowed to throw — a report we could not write to disk
+  // is not a report, and the caller needs to know the floor did not land.
+  const outPath = path.join(realQuarantine, REPORT_BASENAME);
+  const tmpPath = `${outPath}.tmp`;
+  await fsp.writeFile(tmpPath, JSON.stringify(report, null, 2), 'utf8');
+  await fsp.rename(tmpPath, outPath);
+
+  return { report, reportPath: outPath };
+}
+
+module.exports = {
+  FLOOR_VERSION,
+  REPORT_BASENAME,
+  VERDICT_RANK,
+  DETECTORS,
+  buildCorpus,
+  computeFloorVerdict,
+  countBySeverity,
+  coOccurrence,
+  coverageFindings,
+  runDetectors,
+  runFloor,
+};

package/modules/security/artifact-scan/limits.js

@@ -0,0 +1,66 @@
+// modules/security/artifact-scan/limits.js — the honest-limits text
+// (task 1002545, goal 1000055).
+//
+// This file OWNS the caveat language. The reducer computes the verdict and the
+// assembler renders the report, but the sentences that admit what the scan
+// could not see live here, as fixed templates with slots filled from real
+// counts — so a steered panel can bias findings but can never soften the
+// caveats, because no model-authored text is ever spliced into them.
+
+'use strict';
+
+const { excerpt } = require('./detectors/shared');
+
+// THE PASSING WORDING — the most important string in the feature. Emitted
+// verbatim (slots filled) whenever a scan's computed verdict is 'clean'.
+// Do not reword: the sentence is the product of an owner decision that a
+// "clean" scan must still say exactly what it cannot promise.
+const PASSING_WORDING =
+  'No findings at the {tier} tier for commit {sha} — that is the absence of ' +
+  'evidence, not proof this is harmless. I read the code but never ran it, so ' +
+  'anything that only happens at runtime was invisible to me; {N} of {M} files ' +
+  'could not be read at all and are listed in the report; the dependencies it ' +
+  'declares and any server its config points at were never fetched or checked; ' +
+  'and this covers only these exact bytes — one new commit voids it. If you go ' +
+  'ahead, install this exact commit, from the copy I already read.';
+
+// Fill the passing wording. tier and sha are artifact-adjacent strings, so
+// they are scrubbed + capped HERE — the paragraph that carries the honesty
+// promise must not depend on every caller remembering to sanitize. One GLOBAL
+// pass with a replacer FUNCTION: a `$`-pattern in a value can never expand
+// into the template, and a slot token inside a filled value is never
+// re-scanned — so fill order cannot matter and a value containing "{sha}"
+// stays literal (task 1002545 grader nit, fixed under task 1002548).
+function passingWording({ tier, sha, filesUnread, filesTotal }) {
+  const slots = {
+    tier: () => excerpt(String(tier), 16),
+    sha: () => excerpt(String(sha), 64),
+    N: () => String(Number(filesUnread) || 0),
+    M: () => String(Number(filesTotal) || 0),
+  };
+  return PASSING_WORDING.replace(/\{(tier|sha|N|M)\}/g, (_, name) => slots[name]());
+}
+
+// The honest-limits lines for EVERY verdict (clean gets PASSING_WORDING on
+// top). Same principle: fixed sentences, slots from counts.
+function limitLines({ filesRead, filesUnread, declaredDeps, unscannable, lensProblems }) {
+  const lines = [
+    'This was a static read of the exact bytes at one commit. Nothing was executed, installed, or fetched.',
+  ];
+  if (filesUnread > 0) {
+    lines.push(`${filesUnread} file(s) could not be read (binary, oversize, or unreadable) — their contents are UNREVIEWED.`);
+  }
+  if (declaredDeps > 0) {
+    lines.push(`${declaredDeps} declared dependencies were never fetched — installing would pull code nobody here read.`);
+  }
+  if (unscannable > 0) {
+    lines.push(`${unscannable} finding(s) point at code that lives outside these bytes (MCP commands, remote servers) and could not be scanned.`);
+  }
+  if (lensProblems > 0) {
+    lines.push(`${lensProblems} review lens(es) failed to complete — their surface counts as unreviewed, not as clean.`);
+  }
+  lines.push(`${filesRead} file(s) were actually read; the verdict covers those bytes only, and a new commit voids it.`);
+  return lines;
+}
+
+module.exports = { PASSING_WORDING, passingWording, limitLines };

package/modules/security/artifact-scan/manifest.js

@@ -0,0 +1,203 @@
+// modules/security/artifact-scan/manifest.js — the deterministic inventory of
+// what was fetched.
+//
+// The manifest is the scan's anchor. Three downstream promises rest on it being
+// exact and reproducible:
+//   * "install this exact commit, from the copy I already read" — the install
+//     offer re-hashes and compares before printing a command;
+//   * "{N} of {M} files could not be read" — the honest-limits sentence quotes
+//     real counts, so unreadable entries are recorded, never skipped;
+//   * "we already scanned these exact bytes" — content_hash is the GDS key.
+//
+// Cross-platform determinism is therefore a correctness requirement: paths are
+// normalized to forward slashes, entries sort by UTF-8 BYTES (localeCompare
+// would drift by machine locale), and the hashed form is JSON-per-line so a
+// path containing a quote, newline, or tab cannot forge a field boundary.
+//
+// Symlinks are never followed — lstat throughout. The hardened clone sets
+// core.symlinks=false so a symlink arrives as inert text, but where that does
+// not bite, a real symlink would otherwise let the walk read a file outside the
+// quarantine. It is recorded by its link text and its target is never opened.
+//
+// Fully async: every filesystem call goes through fs.promises. A sync walk at
+// CAPS limits (5,000 files / 64 MiB) blocks for seconds, and being called from
+// an async function would only hide that behind an await.
+
+'use strict';
+
+const crypto = require('node:crypto');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+
+// Sibling within this module (intra-module requires are fine; a module may not
+// require another MODULE or a core internal). CAPS lives with the quarantine
+// because the budget is a property of the holding pen, not of the hasher.
+const { CAPS } = require('./quarantine');
+
+const KIND = Object.freeze({
+  FILE: 'file',
+  SYMLINK: 'symlink',
+  OTHER: 'other', // fifo, socket, block/char device — never opened
+});
+
+const HASH_CHUNK_BYTES = 1024 * 1024;
+
+function toPosix(rel) {
+  return rel.split(path.sep).join('/');
+}
+
+// Pre-keyed so the comparator allocates nothing — encoding inside a comparator
+// would allocate O(n log n) throwaway Buffers.
+function sortByBytes(items, keyOf) {
+  return items
+    .map((item) => ({ item, key: Buffer.from(keyOf(item), 'utf8') }))
+    .sort((a, b) => Buffer.compare(a.key, b.key))
+    .map((w) => w.item);
+}
+
+// Hash in fixed chunks so peak memory stays flat regardless of file size. The
+// buffer is owned by one buildManifest call and threaded down, not module-level:
+// two concurrent manifests would otherwise share it and corrupt each other's
+// digests, which async made possible.
+async function sha256File(abs, buf) {
+  const h = crypto.createHash('sha256');
+  const fh = await fsp.open(abs, 'r');
+  try {
+    for (;;) {
+      const { bytesRead } = await fh.read(buf, 0, buf.length, null);
+      if (bytesRead <= 0) break;
+      h.update(buf.subarray(0, bytesRead));
+    }
+  } finally {
+    await fh.close();
+  }
+  return h.digest('hex');
+}
+
+// Thrown when a cap trips. Carries the finding the caller records — the abort is
+// fail-closed and always surfaces, never a silent truncation.
+class CapExceeded extends Error {
+  constructor(code, message, detail) {
+    super(message);
+    this.name = 'CapExceeded';
+    this.code = code;
+    this.detail = detail ?? null;
+  }
+}
+
+async function walk(rootDir, { maxFiles, maxBytes, skipNames, buf }) {
+  const entries = [];
+  let totalBytes = 0;
+
+  // Every recorded node counts against maxFiles, not just regular files: a tree
+  // of 10,000 symlinks is as much of a resource problem as 10,000 files, and a
+  // cap counting only the latter would let a crafted artifact walk past it.
+  const push = (entry) => {
+    if (entries.length + 1 > maxFiles) {
+      throw new CapExceeded('cap_max_files', `Artifact exceeds the ${maxFiles}-entry cap.`, { maxFiles });
+    }
+    entries.push(entry);
+  };
+
+  const visit = async (absDir) => {
+    const names = sortByBytes(await fsp.readdir(absDir), (n) => n);
+    for (const name of names) {
+      const abs = path.join(absDir, name);
+      const rel = toPosix(path.relative(rootDir, abs));
+      if (skipNames.has(name) && path.dirname(rel) === '.') continue;
+
+      const st = await fsp.lstat(abs); // lstat: never resolves a symlink
+      if (st.isSymbolicLink()) {
+        push({
+          path: rel,
+          kind: KIND.SYMLINK,
+          size: 0,
+          sha256: null,
+          // The link text, recorded as inert data. We do NOT open the target.
+          linkTarget: await fsp.readlink(abs),
+        });
+        continue;
+      }
+      if (st.isDirectory()) {
+        await visit(abs);
+        continue;
+      }
+      if (!st.isFile()) {
+        push({ path: rel, kind: KIND.OTHER, size: 0, sha256: null });
+        continue;
+      }
+
+      totalBytes += st.size;
+      if (totalBytes > maxBytes) {
+        throw new CapExceeded('cap_max_bytes', `Artifact exceeds the ${maxBytes}-byte cap.`, { maxBytes, totalBytes });
+      }
+      push({ path: rel, kind: KIND.FILE, size: st.size, sha256: await sha256File(abs, buf) });
+    }
+  };
+
+  await visit(rootDir);
+  return { entries: sortByBytes(entries, (e) => e.path), totalBytes };
+}
+
+// The exact bytes content_hash is taken over. One JSON array per entry, newline
+// separated: unambiguous under any path content, stable across platforms.
+function serialize(entries) {
+  return entries
+    .map((e) => JSON.stringify([e.path, e.kind, e.size, e.sha256, e.linkTarget ?? null]))
+    .join('\n');
+}
+
+// Build the manifest for a fetched tree.
+//   rootDir   — the pristine directory (its .git should already be removed)
+//   skipNames — top-level names to ignore (default: .git, if still present)
+//
+// Returns { entries, fileCount, symlinkCount, otherCount, totalBytes, contentHash }.
+// Throws CapExceeded when a budget trips.
+async function buildManifest(rootDir, { maxFiles, maxBytes, skipNames = ['.git'] } = {}) {
+  if (!Number.isFinite(maxFiles) || !Number.isFinite(maxBytes)) {
+    throw new Error('buildManifest requires numeric maxFiles and maxBytes (fail-closed: no implicit unlimited).');
+  }
+  const buf = Buffer.allocUnsafe(HASH_CHUNK_BYTES);
+  const { entries, totalBytes } = await walk(rootDir, { maxFiles, maxBytes, skipNames: new Set(skipNames), buf });
+
+  let fileCount = 0;
+  let symlinkCount = 0;
+  let otherCount = 0;
+  for (const e of entries) {
+    if (e.kind === KIND.FILE) fileCount++;
+    else if (e.kind === KIND.SYMLINK) symlinkCount++;
+    else otherCount++;
+  }
+  return {
+    entries,
+    fileCount,
+    symlinkCount,
+    otherCount,
+    totalBytes,
+    contentHash: crypto.createHash('sha256').update(serialize(entries), 'utf8').digest('hex'),
+  };
+}
+
+// Re-hash a tree and compare it to a stored manifest. This is what stands
+// between "the scan passed" and "here is the install command" — if the bytes
+// moved underneath us, the offer must be withdrawn rather than honoured.
+//
+// A cap trip here means the tree GREW past the budget it was scanned under,
+// which is itself proof it changed — so it resolves to ok:false rather than
+// propagating. Answering "is this still what I read?" must never throw on the
+// very tampering it exists to detect.
+async function verifyUnchanged(rootDir, manifest, opts = {}) {
+  const maxFiles = opts.maxFiles ?? CAPS.maxFiles;
+  const maxBytes = opts.maxBytes ?? CAPS.maxBytes;
+  let fresh;
+  try {
+    fresh = await buildManifest(rootDir, { maxFiles, maxBytes });
+  } catch (err) {
+    if (err instanceof CapExceeded) return { ok: false, contentHash: null, reason: err.code };
+    throw err;
+  }
+  const ok = fresh.contentHash === manifest.contentHash;
+  return { ok, contentHash: fresh.contentHash, reason: ok ? null : 'content_hash_mismatch' };
+}
+
+module.exports = { KIND, CapExceeded, buildManifest, verifyUnchanged };