@bongos/core 1.18.19 → 1.19.2

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 };

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

@@ -0,0 +1,158 @@
+// modules/security/artifact-scan/mirror.js — the reading-room copy of a
+// quarantined artifact (task 1002543, goal 1000055).
+//
+// Two copies of a fetched artifact exist in the quarantine: the PRISTINE copy
+// no model is ever allowed to read, and this mirror — where every readable
+// file has already been scrubbed of control/zero-width/bidi characters and
+// wrapped in an on-disk fence before any agent can open it. The defense is
+// structural: even a raw Read call against mirror/ returns data-never-
+// instructions, with no dependence on any agent's discipline.
+//
+// What does NOT get mirrored becomes a STUB RECORD instead: symlinks (never
+// followed), non-UTF8/binary files, oversize files, special files, and any
+// path that escapes the pen lexically or physically. Stub bytes are counted as
+// UNREVIEWED — downstream the reducer caps the verdict at caution over them,
+// because static analysis cannot clear what it never read.
+//
+// The walk is driven by the MANIFEST entries, not a fresh readdir: the mirror
+// renders exactly the inventory that was hashed, so "what we read" and "what
+// we fingerprinted" can never drift apart.
+//
+// Confinement is checked twice per file, fail-closed:
+//   1. lexically — a manifest path that is absolute or resolves above the
+//      pristine root is refused before any fs call touches it;
+//   2. physically — the file's realpath must live under the quarantine root,
+//      so a real on-disk symlink smuggled past kind detection still cannot
+//      pull outside bytes into the mirror.
+//
+// Fully async (fs.promises) for the same reason as manifest.js: a sync walk at
+// cap limits blocks the event loop for seconds.
+
+'use strict';
+
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const { TextDecoder } = require('node:util');
+
+// Intra-module siblings (a module may require its own files, never another
+// module or a core internal).
+const { isInside } = require('./quarantine');
+const { newFenceDelim, fenceFile } = require('./fence-local');
+
+// Per-file readability budget. A "text" file past this size is recorded as a
+// stub rather than rendered readable — a 40 MB minified blob is unreviewable
+// text in practice, and unreviewable must always surface as unreviewed.
+const MIRROR_CAPS = Object.freeze({
+  maxFileBytes: 1024 * 1024, // 1 MiB per mirrored file
+});
+
+const INDEX_BASENAME = 'mirror-index.json';
+
+// Lexical containment for a manifest-relative path: must be relative, and must
+// stay under root after resolution. Directional — anything else is an escape.
+function relEscapes(rootDir, rel) {
+  if (typeof rel !== 'string' || rel.length === 0) return true;
+  if (path.isAbsolute(rel)) return true;
+  return !isInside(rootDir, path.resolve(rootDir, ...rel.split('/')));
+}
+
+// Decode strictly as UTF-8. A single invalid sequence means "not text we can
+// honestly render" — the file becomes a stub, never a lossily-decoded mirror.
+// One shared decoder: non-streaming decode() keeps no state between calls.
+const UTF8_STRICT = new TextDecoder('utf-8', { fatal: true });
+function strictUtf8(buf) {
+  try {
+    return UTF8_STRICT.decode(buf);
+  } catch {
+    return null;
+  }
+}
+
+// Build the reading-room mirror for one scan.
+//   pristineDir    — the pristine snapshot (never modified here)
+//   mirrorDir      — where scrubbed+fenced copies are written
+//   quarantineRoot — the pen; every realpath must resolve under it
+//   entries        — manifest entries ({ path, kind, size, ... }) from buildManifest
+//   caps           — { maxFileBytes } override (tests); defaults MIRROR_CAPS
+//
+// Returns { mirrored, stubs, unreviewedBytes, fenceDelim, indexPath }. A stub
+// is { path, reason: symlink|special|oversize|non_utf8|path_escape|unreadable,
+// bytes }. Never throws on a per-file problem — a file the mirror cannot
+// honestly render is a recorded stub, not a crashed scan.
+async function buildMirror({ pristineDir, mirrorDir, quarantineRoot, entries, caps = {} }) {
+  if (!pristineDir || !mirrorDir || !quarantineRoot || !Array.isArray(entries)) {
+    throw new Error('buildMirror requires pristineDir, mirrorDir, quarantineRoot and manifest entries[].');
+  }
+  const maxFileBytes = caps.maxFileBytes ?? MIRROR_CAPS.maxFileBytes;
+  const realQuarantine = await fsp.realpath(quarantineRoot);
+  const fenceDelim = newFenceDelim();
+
+  const mirrored = [];
+  const stubs = [];
+  const madeDirs = new Set();
+  const stub = (rel, reason, bytes) => stubs.push({ path: rel, reason, bytes });
+
+  for (const entry of entries) {
+    const rel = entry.path;
+
+    if (entry.kind === 'symlink') { stub(rel, 'symlink', entry.size || 0); continue; }
+    if (entry.kind !== 'file') { stub(rel, 'special', entry.size || 0); continue; }
+
+    // 1. Lexical confinement — before any fs call touches the path.
+    if (relEscapes(pristineDir, rel)) { stub(rel, 'path_escape', entry.size || 0); continue; }
+    const abs = path.resolve(pristineDir, ...rel.split('/'));
+
+    if (entry.size > maxFileBytes) { stub(rel, 'oversize', entry.size); continue; }
+
+    // 2. Physical confinement — the realpath must stay inside the pen, so a
+    // real symlink mislabeled "file" cannot pull outside bytes into the mirror.
+    let buf;
+    try {
+      const real = await fsp.realpath(abs);
+      if (!isInside(realQuarantine, real)) { stub(rel, 'path_escape', entry.size || 0); continue; }
+      const st = await fsp.lstat(abs);
+      if (st.isSymbolicLink()) { stub(rel, 'path_escape', entry.size || 0); continue; }
+      // Read the VERIFIED resolved path, not the original — reading `abs` would
+      // reopen the race the realpath check just closed (TOCTOU: a swap between
+      // lstat and read would be followed silently).
+      buf = await fsp.readFile(real);
+    } catch {
+      // Missing/unreadable on disk though present in the manifest — that
+      // disagreement is itself worth surfacing, as unreviewed.
+      stub(rel, 'unreadable', entry.size || 0);
+      continue;
+    }
+
+    const text = strictUtf8(buf);
+    if (text === null) { stub(rel, 'non_utf8', buf.length); continue; }
+
+    const dest = path.resolve(mirrorDir, ...rel.split('/'));
+    if (!isInside(mirrorDir, dest)) { stub(rel, 'path_escape', buf.length); continue; }
+    const destDir = path.dirname(dest);
+    if (!madeDirs.has(destDir)) {
+      await fsp.mkdir(destDir, { recursive: true });
+      madeDirs.add(destDir);
+    }
+    await fsp.writeFile(dest, fenceFile(fenceDelim, rel, text), 'utf8');
+    mirrored.push({ path: rel, bytes: buf.length });
+  }
+
+  const unreviewedBytes = stubs.reduce((sum, s) => sum + (s.bytes || 0), 0);
+
+  // The index is the trusted record downstream stages (floor, reducer) read:
+  // which files are renderable, which bytes were never reviewed, and the fence
+  // delimiter the panel should expect. Written inside the pen, nowhere else.
+  const indexPath = path.join(realQuarantine, INDEX_BASENAME);
+  const index = {
+    fenceDelim,
+    mirrored,
+    stubs,
+    unreviewedBytes,
+    counts: { mirrored: mirrored.length, stubs: stubs.length },
+  };
+  await fsp.writeFile(indexPath, JSON.stringify(index, null, 2), 'utf8');
+
+  return { mirrored, stubs, unreviewedBytes, fenceDelim, indexPath };
+}
+
+module.exports = { buildMirror, MIRROR_CAPS, INDEX_BASENAME };

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

@@ -0,0 +1,149 @@
+// modules/security/artifact-scan/quarantine.js — the holding pen an untrusted
+// artifact is fetched into.
+//
+// The scan engine's first rule is that a suspect artifact never gets a chance to
+// act. Everything downstream (the mirror, the detectors, the panel) assumes the
+// bytes it reads live somewhere that satisfies three location properties:
+//
+//   1. OUTSIDE THE REPO — so a scanned artifact can never be mistaken for our
+//      own source, land in a diff, or be picked up by a fitness/lint sweep.
+//   2. OUTSIDE ONEDRIVE (or any sync root) — a synced folder uploads whatever
+//      lands in it. Fetching malware into a synced directory copies it to the
+//      builder's cloud storage and every other machine on that account.
+//   3. OUTSIDE EVERY WORKSPACE ROOT — this is the subtle one. A Claude session
+//      auto-loads CLAUDE.md and .claude/ from directories inside its workspace.
+//      An artifact carrying its own CLAUDE.md, dropped inside a workspace root,
+//      is prompt injection delivered through the harness itself rather than
+//      through any file an agent chose to read. Callers pass their workspace
+//      roots in `forbiddenRoots`; we refuse to build a quarantine under one.
+//
+// The pen also holds the three neutralizing fixtures the hardened clone needs:
+// an EMPTY REAL hooks directory (git's core.hooksPath must be a real directory
+// — /dev/null works on macOS and is not a directory on Windows), and an empty
+// gitconfig used for both GIT_CONFIG_GLOBAL and GIT_CONFIG_SYSTEM so the
+// builder's own git config (insteadOf URL rewrites, a global hooksPath, a
+// credential helper) cannot influence the fetch.
+//
+// Pure-ish: filesystem only. No DB, no network, no doorway — so it is unit
+// testable and safe to require from a CLI.
+
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+// modules/security/artifact-scan/ -> modules/security/ -> modules/ -> repo root
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+
+// Fail-closed budget. Exceeding any of these aborts the scan and records a
+// finding — it never silently truncates, because a scan that quietly stopped
+// reading at 80% of a repo and still says "no findings" is a lie.
+const CAPS = Object.freeze({
+  maxFiles: 5000,
+  maxBytes: 64 * 1024 * 1024, // 64 MiB across the whole artifact
+  cloneTimeoutMs: 120_000,
+});
+
+// A directory is "sync-backed" if any segment names a known consumer-sync root.
+// Deliberately a name test rather than a path test: OneDrive/Dropbox relocate,
+// and the property we care about ("anything written here is uploaded") travels
+// with the folder, not with one machine's absolute path.
+const SYNC_SEGMENTS = ['onedrive', 'dropbox', 'google drive', 'icloud drive'];
+
+function isSyncBacked(p) {
+  return path
+    .resolve(p)
+    .split(/[\\/]/)
+    .some((seg) => SYNC_SEGMENTS.includes(seg.toLowerCase()));
+}
+
+// Lexical containment: is `candidate` equal to, or under, `root`? Directional on
+// purpose — path.relative escaping upward ('..') or returning an absolute path
+// both mean "outside". Used to reject a quarantine site, and by callers to keep
+// derived paths inside the pen.
+function isInside(root, candidate) {
+  const rel = path.relative(path.resolve(root), path.resolve(candidate));
+  if (rel === '') return true;
+  return !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+// Why a chosen site is unusable, or null when it is fine. Split out from
+// createQuarantine so the rule set is directly testable without touching disk.
+function siteRefusal(site, forbiddenRoots) {
+  if (isInside(REPO_ROOT, site)) return `inside the repository (${REPO_ROOT})`;
+  if (isSyncBacked(site)) return 'inside a cloud-sync folder (it would upload the artifact)';
+  for (const root of forbiddenRoots) {
+    if (!root) continue;
+    if (isInside(root, site)) return `inside a workspace root (${root}) where its CLAUDE.md could auto-load`;
+  }
+  return null;
+}
+
+// Build a fresh, uniquely-named pen.
+//
+// `forbiddenRoots` is REQUIRED, not optional-with-an-empty-default. Workspace
+// isolation is the primary defense against an artifact's own CLAUDE.md being
+// auto-loaded as instructions, and a defense that silently does nothing when a
+// caller forgets a parameter is not a defense. Callers with genuinely no
+// workspace roots must say so by passing [] explicitly. The repo root and sync
+// folders are refused unconditionally regardless.
+//
+// Returns { root, pristineDir, mirrorDir, hooksDir, gitConfigFile, cleanup() }.
+// pristineDir holds the bytes no model is ever allowed to read; mirrorDir is
+// where the scrubbed reading-room copy is written (task 1002543).
+function createQuarantine({ tmpRoot = os.tmpdir(), forbiddenRoots } = {}) {
+  if (!Array.isArray(forbiddenRoots)) {
+    throw new Error(
+      'createQuarantine requires forbiddenRoots: string[] — the workspace roots a quarantine must never live under. ' +
+        'Pass [] explicitly if this caller genuinely has none.'
+    );
+  }
+  const refusal = siteRefusal(tmpRoot, forbiddenRoots);
+  if (refusal) {
+    throw new Error(
+      `Refusing to create a quarantine under ${tmpRoot} — it is ${refusal}. ` +
+        'Pass a different tmpRoot outside the repo, outside any sync folder, and outside every workspace root.'
+    );
+  }
+
+  const root = fs.mkdtempSync(path.join(tmpRoot, 'bongos-scan-'));
+  // mkdtemp resolves through whatever tmpRoot really is (on macOS /tmp is a
+  // symlink to /private/tmp), so re-check the REAL location before we trust it.
+  const realRoot = fs.realpathSync(root);
+  const realRefusal = siteRefusal(realRoot, forbiddenRoots);
+  if (realRefusal) {
+    fs.rmSync(root, { recursive: true, force: true });
+    throw new Error(`Refusing to use quarantine ${realRoot} — it resolves ${realRefusal}.`);
+  }
+
+  const pristineDir = path.join(realRoot, 'pristine');
+  const mirrorDir = path.join(realRoot, 'mirror');
+  const hooksDir = path.join(realRoot, 'empty-hooks');
+  const gitConfigFile = path.join(realRoot, 'empty-gitconfig');
+
+  fs.mkdirSync(mirrorDir);
+  fs.mkdirSync(hooksDir); // must exist and be EMPTY: git's core.hooksPath target
+  fs.writeFileSync(gitConfigFile, '', 'utf8');
+  // pristineDir is deliberately NOT created — `git clone` wants to create it.
+
+  return {
+    root: realRoot,
+    pristineDir,
+    mirrorDir,
+    hooksDir,
+    gitConfigFile,
+    cleanup() {
+      fs.rmSync(realRoot, { recursive: true, force: true });
+    },
+  };
+}
+
+module.exports = {
+  CAPS,
+  REPO_ROOT,
+  createQuarantine,
+  siteRefusal,
+  isSyncBacked,
+  isInside,
+};