amicus 4.9.4 → 4.9.6

package/src/sidecar/electron-native-rescue.js

@@ -0,0 +1,231 @@
+/**
+ * THE NATIVE-EXTRACTOR RESCUE — the one way an archive amicus's own extractor
+ * cannot parse still becomes an install, what it costs, and why it is reachable
+ * from exactly one place.
+ *
+ * ── THE FINDING (council run 34182994208, major, deepseek seat) ───────────
+ * "Deleting the native-unzip fallback and the last-resort install.js spawn
+ * weakens the air-gapped recovery path to a permanent no-rescue failure for
+ * archives yauzl cannot parse." True as filed. `zip-stall-bound.js` had already
+ * written the loss down honestly — "an archive yauzl cannot parse but a native
+ * extractor could is a failed repair plus a re-download" — and on a machine with
+ * no network to re-download from, that is the end of the road.
+ *
+ * ── WHY IT CANNOT SIMPLY BE PUT BACK, WHICH IS THE WHOLE JUSTIFICATION ────
+ * Every native extractor — `tar`, `Expand-Archive`, `ditto`, `unzip` — takes a
+ * PATH. Using one therefore means writing bytes down and letting a child process
+ * open them: the SECOND PATH RESOLUTION the custody design exists to eliminate
+ * (`electron-custody.js` carries the three refuted remedies and the measurements
+ * that killed them). The custody property — **amicus never itself writes, or
+ * reports as verified, bytes it did not hash** — and a path-taking extractor
+ * cannot both hold on the same run. There is no clever version of this: the two
+ * properties are in direct contradiction.
+ *
+ * That trade is acceptable ONLY under a flag whose existing documented meaning is
+ * already "I accept Electron bytes amicus cannot vouch for", and it must not be
+ * reachable any other way. `AMICUS_ALLOW_UNVERIFIED_ELECTRON=1` is that flag, and
+ * it is read in exactly one place (`electron-trust.js :: electronTrustPolicy`),
+ * from a bare environment name a repository's `.npmrc` cannot plant. Custody
+ * stays absolute by default. `runInstaller` is NOT coming back — it did its own
+ * download with its own anchor, which is a different and much worse thing (see
+ * `electron-provision.js`).
+ *
+ * ── THE TRIGGER BOUNDARY, WHICH MATTERS MORE THAN THE MECHANISM ───────────
+ * "Fall back when extraction fails" would re-arm the laundering bug this cluster
+ * already fixed once (C4): a security refusal handed to a tool with no such
+ * check. So the trigger is ONE extractor verdict, `UNZIP_BUFFER_FAILED` — the
+ * code whose defined meaning is "the ARCHIVE is bad", and already the only
+ * failure that licences an eviction (`electron-repair-cache.js ::
+ * EVICTS_THE_ARTIFACT`). The rescue and the eviction now share one trigger.
+ *
+ *   YES  the extractor positively identified the ARCHIVE as unreadable.
+ *   NO   `UNZIP_UNSAFE_ARCHIVE` — a path-traversal REFUSAL. Terminal by design;
+ *        C4 exists precisely to stop a refusal being retried through a tool
+ *        amicus does not control, and the hatch is not even MENTIONED on that
+ *        exit — advertising it there would be the same laundering with a human
+ *        in the loop.
+ *   NO   `UNZIP_BUFFER_STALLED` — the bound exists to STOP work, not to hand it
+ *        to someone else, and a stall is a verdict about nothing.
+ *   NO   a digest MISMATCH. The bytes are known wrong; there is nothing to
+ *        rescue. This is the exclusion that is easy to get wrong, because the
+ *        same flag that opens the rescue ALSO downgrades a mismatch refusal to a
+ *        warning (`electron-trust.js :: verifyArtifactBytes`) — so with the hatch
+ *        set, contradicted bytes really do reach the extractor. `gate.verdict`
+ *        is checked here for that one reason.
+ *   NO   `UNZIP_DEST_FAILED` — not the archive's fault, and a native extractor
+ *        writing to the same full or unwritable destination fails identically.
+ *   NO   `UNZIP_BUFFER_UNAVAILABLE`, and NO an error carrying no `code` at all.
+ *        Neither is a parse failure, and a rule that fails OPEN on the shapes
+ *        nobody enumerated is the shape D2 was filed against. Fail closed.
+ *
+ * AND A VERDICT IS NOT THE WHOLE QUESTION. Every line above keys on the refusal
+ * yauzl FORMED, and yauzl checks an entry's size before its name — so an archive
+ * whose first entry breaks the extraction arrives as `UNZIP_BUFFER_FAILED` with
+ * its traversal entry never looked at. One flag bit, MEASURED, moves the same
+ * archive from the terminal class into the rescuable one. So the boundary also
+ * asks what names the archive DECLARES (`hostileName`), and a name yauzl would
+ * have refused is treated as the refusal it would have raised. What that scan
+ * cannot see is written down there rather than papered over.
+ *
+ * ── AND `no-digest` IS ALLOWED, DELIBERATELY ──────────────────────────────
+ * Only `mismatch` is excluded. `no-digest` means nobody ever published a digest
+ * for this artifact — an Electron package predating `checksums.json` — which is
+ * exactly the old, air-gapped machine the finding is about. Nothing contradicts
+ * those bytes; refusing them would delete the rescue for its main case.
+ *
+ * ── WHAT A RESCUE CAN NEVER DO: REPORT CLEAN ──────────────────────────────
+ * `rescue.used` is set when the rescue runs, and both routes fold it into their
+ * `unverified` mark, so a rescued install is never reported as verified even
+ * when the artifact's own sha256 matched. It has to be: the bytes in `dist/` were
+ * placed there by a child process reading a path, not by amicus writing what it
+ * hashed. Reporting that as verified is the exact overclaim the custody property
+ * forbids.
+ *
+ * ── OFFERED-BUT-UNARMED: THE OFFER IS A PROMISE ──────────────────────────
+ * With the hatch OFF, a parse failure prints an offer naming the flag and telling
+ * an air-gapped user to set it and provision again. The FIRST cut of C2 printed
+ * that and then let the same `UNZIP_BUFFER_FAILED` reach the cache route's
+ * eviction, which DELETED the artifact on the way out — MEASURED end to end: the
+ * ten-line offer on stderr, `reason: "… was corrupt and removed"`, the zip gone,
+ * and the re-run the message asks for ending in `No cached electron zip found`.
+ * On the machine the whole finding is about, the offer named a rescue that its
+ * own run had just made impossible.
+ *
+ * So `rescue.offered` is set HERE, where the promise is made, and
+ * `electron-repair-cache.js` keeps the artifact when it is set. The cost is the
+ * availability cost that module already accepts wherever its delete fence says
+ * no: an unreadable zip survives and is re-downloaded once per provision. That
+ * is the right way round — a copy nobody can read costs one download; a copy
+ * that is gone costs the only rescue there was.
+ *
+ * @module sidecar/electron-native-rescue
+ */
+
+'use strict';
+
+const { spawnSync } = require('child_process');
+
+// The cap comes from `unzip.js`, which is byte-for-byte unchanged: this is a
+// re-wiring of a caller, not a change to that module.
+const { MAX_MS } = require('./unzip');
+// The mechanism this file decides about: writing the buffer down, walking the
+// platform's plan, sweeping up. `RESCUE_ZIP` and `INCOMING_PREFIX` are re-exported
+// below because they name what a rescue leaves on disk, which is this module's
+// subject even though the code that writes them is next door.
+const { nativeRescue, RESCUE_ZIP, INCOMING_PREFIX } = require('./electron-native-plan');
+// The offer a parse failure gets when the hatch is off. Every other user-facing
+// sentence in this subsystem is written in the same two files.
+const { offerNativeRescue } = require('./electron-rescue-notice');
+// The read-only name walk the boundary consults before it trusts a verdict.
+const { scanEntryNames } = require('./zip-name-scan');
+const { collapseExcerpt } = require('../utils/text-sanitize');
+
+/** The ONE extractor verdict a rescue may act on. See the docblock's boundary. */
+const RESCUE_TRIGGER = 'UNZIP_BUFFER_FAILED';
+
+/** True for the ONE failure class the owner authorised a rescue for. */
+function isRescuableFailure(err) {
+  return !!err && err.code === RESCUE_TRIGGER;
+}
+
+/**
+ * A parse failure's archive, asked what ENTRY NAMES it declares.
+ *
+ * THE EXCLUSION ABOVE KEYS ON A REFUSAL, AND A REFUSAL HAS TO BE FORMED. yauzl
+ * checks an entry's size before its name, so an archive whose FIRST entry breaks
+ * the extraction never reaches the traversal entry behind it and arrives here as
+ * `UNZIP_BUFFER_FAILED` — the one class a rescue acts on. MEASURED: one flag bit
+ * moves the same archive from `UNZIP_UNSAFE_ARCHIVE` into the rescue, traversal
+ * entry and all (`zip-name-scan.js` carries both measurements and the two
+ * Windows tools' own refusals, which are what stopped the escape that run).
+ *
+ * So the boundary asks about the ENTRIES, not only the verdict, and a name yauzl
+ * would have refused becomes the refusal yauzl would have raised: terminal,
+ * unadvertised, left in place, exactly as if the archive had had nothing wrong
+ * with it but that entry.
+ *
+ * THE RESIDUAL, STATED RATHER THAN ENGINEERED AWAY. The scan reads the central
+ * directory; an archive whose central directory is unreadable — a truncated zip,
+ * the commonest thing this rescue exists for — declares no names it can see, and
+ * that archive still reaches the native extractor. Nothing here covers a SYMLINK
+ * whose target escapes either: that is a payload, not a name. In both cases the
+ * only remaining check is the extractor's own, which `tar` and `Expand-Archive`
+ * were MEASURED to have (`ditto` and Info-ZIP `unzip` are unmeasured), and
+ * `cleanDir` sweeps only inside `dir` — anything a native tool wrote outside it
+ * would survive a failed strategy. `docs/configuration.md` says the same thing to
+ * the user who has to decide whether to set the flag.
+ * @returns {Error|null} a terminal UNZIP_UNSAFE_ARCHIVE, or null
+ */
+async function hostileName(bytes, log) {
+  const seen = await scanEntryNames(bytes);
+  if (!seen.refusal) { return null; }
+  log('[amicus] REFUSING to rescue this archive: amicus could not read it, and while asking what');
+  log('[amicus] it contains it found an entry that tries to write OUTSIDE the destination:');
+  log(`[amicus]   ${collapseExcerpt(seen.refusal)}`);
+  log('[amicus] A native extractor may have no such check, so it is not offered this archive.');
+  return Object.assign(
+    new Error(`refusing to extract this archive: ${collapseExcerpt(seen.refusal)}`),
+    { code: 'UNZIP_UNSAFE_ARCHIVE' },
+  );
+}
+
+/**
+ * Wrap a buffer extractor so a PARSE FAILURE — and nothing else — may be rescued
+ * by the native plan when the hatch is set.
+ *
+ * ONE WRAPPER, WIRED AT BOTH CALL SITES. `gate` and `policy` are only known after
+ * the digest gate has run, which is why this is composed inside each route rather
+ * than once in `repairElectron`; F3 is the standing reminder of what happens when
+ * a rule lands on one provision route and not the other, so a test asserts both.
+ *
+ * @param {object} o
+ * @param {function} o.extract  the buffer extractor being wrapped
+ * @param {object}   o.gate     verifyArtifactBytes's result (its `verdict` is read)
+ * @param {object}   o.policy   electronTrustPolicy's result (the hatch)
+ * @param {object}   o.rescue   OUT: `{used, strategy}` when a rescue ran, and
+ *   `{offered:true}` when one was named but not armed — the caller must not then
+ *   discard the artifact the offer points at
+ * @returns {function} an extractor with the same (bytes, {dir}) signature
+ */
+function withNativeRescue({
+  extract, gate = {}, policy = {}, rescue = {}, platform = process.platform,
+  fs, spawn = spawnSync, maxMs = MAX_MS, log = () => {},
+}) {
+  return async (bytes, o) => {
+    try {
+      return await extract(bytes, o);
+    } catch (err) {
+      // Every class but one leaves through here untouched and unadvertised.
+      if (!isRescuableFailure(err)) { throw err; }
+      // ...and the one class that IS rescuable is asked what names it declares
+      // first, because the exclusion above keys on the refusal yauzl FORMED and
+      // an earlier bad entry stops it forming one. See `hostileName`.
+      const hostile = await hostileName(bytes, log);
+      if (hostile) { throw hostile; }
+      if (!policy.allowUnverified) {
+        // `offered` IS THE OFFER'S RECEIPT, and the cache route is required to
+        // honour it: see the docblock's OFFERED-BUT-UNARMED section.
+        rescue.offered = true;
+        offerNativeRescue({ reason: (err && err.message) || '', log });
+        throw err;
+      }
+      if (gate.verdict === 'mismatch') {
+        log('[amicus] the native-extractor rescue was NOT attempted: these bytes contradict the published sha256, so there is nothing to rescue.');
+        throw err;
+      }
+      const strategy = nativeRescue({
+        bytes, dir: o.dir, reason: (err && err.message) || '', platform, fs, spawn, maxMs, log,
+      });
+      // A rescue that failed leaves the ORIGINAL classified error in flight, so
+      // a genuinely bad archive is still evicted exactly as it was before.
+      if (!strategy) { throw err; }
+      rescue.used = true;
+      rescue.strategy = strategy;
+      return { strategy, rescued: true };
+    }
+  };
+}
+
+module.exports = {
+  withNativeRescue, isRescuableFailure, RESCUE_TRIGGER, RESCUE_ZIP, INCOMING_PREFIX,
+};

package/src/sidecar/electron-provision.js

@@ -0,0 +1,232 @@
+/**
+ * Electron CONTROLLED provision — the pinned download, and the fence that says
+ * whether a refused cache artifact may be deleted.
+ *
+ * Split out of electron-install.js because that file sits at the repo's 300-line
+ * gate and cannot grow; the refusal MESSAGES were split out of this file, into
+ * ./electron-refuse, for the same reason. The require arrow is
+ * electron-install -> electron-provision -> {electron-custody, electron-layout,
+ * electron-refuse, electron-trust} and must never point back. Those four are
+ * near-leaves required by both this module and electron-install.js — and by
+ * ./electron-repair-cache, which requires THIS module for `mayDeleteRejectedZip`
+ * and is required only by electron-install.js, so the arrow stays acyclic.
+ *
+ * @module sidecar/electron-provision
+ */
+
+'use strict';
+
+const path = require('path');
+
+const { resolveCacheRoots } = require('./electron-cache');
+const { readArtifactBytes } = require('./electron-custody');
+const { extractBytesToDist } = require('./electron-layout');
+const { withNativeRescue } = require('./electron-native-rescue');
+const { refuseUnreadableArtifact, rejectDownloadedZip } = require('./electron-refuse');
+const { withScrubbedRepoEnv } = require('./electron-env-scrub');
+const { artifactFileName, expectedDigest, verifyArtifactBytes } = require('./electron-trust');
+const { containsOnDisk } = require('../utils/path-fence');
+
+/** Best-effort cache root for downloadArtifact (first resolved root). */
+function cacheRootFor(env = process.env) {
+  return resolveCacheRoots(env)[0];
+}
+
+/**
+ * CONTROLLED provision: fetch the zip ourselves with the SAME @electron/get
+ * api install.js uses, READ IT ONCE into memory, hash THOSE BYTES ourselves,
+ * extract THOSE BYTES offline, and let the caller verify isElectronUsable().
+ * No blind install.js spawn, and no path resolved a second time.
+ *
+ * C1 — THE PIN. `checksums` is what breaks the attack chain. Supplied, it makes
+ * @electron/get write a LOCAL SHASUMS256.txt from this table and never fetch one
+ * from the mirror, so a redirected download still has to produce bytes matching
+ * electron's own published sha256. Passed as the ONE entry for this artifact:
+ * an empty table is a hard throw upstream, and a table missing the requested
+ * name fails the download outright — which is why no anchor means no `checksums`
+ * key at all rather than an empty one. With no anchor, @electron/get falls back
+ * to its own remote SHASUMS256.txt fetch: weaker, but never a re-download loop.
+ *
+ * THE HATCH REACHES THIS ROUTE TOO. `AMICUS_ALLOW_UNVERIFIED_ELECTRON=1` used to
+ * be handed only to the cached-artifact gate, so the one case both docs describe
+ * — a machine whose electron bytes legitimately differ (a local rebuild, an
+ * internally-signed build on a corporate mirror) — still had its download pinned
+ * to the official digest and failed. MEASURED before this change: with the hatch
+ * set and nothing in any cache root, `checksums` was still sent and the call
+ * returned `{repaired:false}` with no reason at all. When the hatch is set the
+ * pin is dropped here and @electron/get falls back to the mirror's own
+ * SHASUMS256.txt, which is what a rebuild publishes. That is a real downgrade,
+ * so it is stated out loud on stderr every time rather than happening quietly —
+ * and it is reachable ONLY through a bare env name a repository cannot plant.
+ *
+ * F#2 — AMICUS HASHES WHAT IT DOWNLOADED, ITSELF. Sending `checksums` records
+ * that a table went out; it does not record that the bytes reaching the
+ * extractor matched it. @electron/get validates in its own temp dir and then
+ * RENAMES the artifact into the cache root, handing back THAT path — a path the
+ * same cache-dir writer the digest gate exists to stop can swap before amicus
+ * opens it. MEASURED before this change: with the swap fired inside amicus's own
+ * post-download window, `BYTES EXTRACTED: "POISONED-BYTES"` and
+ * `{"repaired":true}`.
+ *
+ * THE SECOND ROUND MOVED WHERE THAT HASH HAPPENS, because the first answer was
+ * not enough. It staged a private COPY and hashed the copy — and seat D1 showed
+ * that copy is discoverable and openable by the same uid, so the race simply
+ * moved onto the staged path. There is no copy now: the downloaded path is read
+ * ONCE into a Buffer, that Buffer is hashed, and that Buffer is extracted. The
+ * identical three steps run on the cache route (./electron-repair-cache), which
+ * is what makes `pinned` mean what its name says.
+ *
+ * F#6/F#8 — AND IT FAILS CLOSED. When the bytes could not be read at all, this
+ * route used to extract the unread path anyway while the only line on screen
+ * said they would not be extracted. It refuses, in the cache route's own words.
+ *
+ * F3 — AND AN UNPINNED SUCCESS IS MARKED, NOT ONLY LOGGED (seats C1 + B3). Both
+ * `CHANGELOG.md` and `docs/troubleshooting.md` promise that an artifact no
+ * published digest covers is "extracted and marked `unverified`". v4.9.5 kept
+ * that promise on the CACHE route only. `repairElectron` folds `unverified:true`
+ * into its result whenever `pinned` is false.
+ * @returns {Promise<{pinned:boolean, refused?:object}>} pinned:false = these bytes
+ *   were vouched for only by the mirror that served them; `refused` = a result
+ *   shape the caller must return as-is, nothing was extracted.
+ */
+async function controlledProvision({
+  electronDir, platform, arch, version, anchor, downloadArtifact, extract,
+  fs, spawn, env = process.env, downloadMs = 480000, policy = {}, log = () => {},
+}) {
+  const fileName = artifactFileName({ version, platform, arch });
+  let digest = expectedDigest(anchor, fileName);
+  if (digest && policy.allowUnverified) {
+    log('[amicus] WARNING: AMICUS_ALLOW_UNVERIFIED_ELECTRON=1 — downloading without the published');
+    log(`[amicus]   sha256 pin for ${fileName}; its digest comes from the mirror you are using.`);
+    digest = null;
+  } else if (!digest) {
+    log(`[amicus] NOTE: no published sha256 for ${fileName} (this electron package ships no`);
+    log('[amicus]   checksums.json entry for it), so the download could not be pinned: its bytes');
+    log('[amicus]   are checked against the SHASUMS256.txt the mirror itself serves. The result');
+    log('[amicus]   is reported as unverified.');
+  }
+  // D5: @electron/get runs IN THIS PROCESS and reads the same repo-plantable
+  // npm_config_electron_* / npm_package_config_electron_* names install.js does.
+  // The scrub is held across the synchronous prefix ONLY, and the promise is
+  // returned unawaited so no unrelated caller ever sees a scrubbed environment.
+  //
+  // WHAT THAT DOES AND DOES NOT COVER, MEASURED against the installed 5.0.0 and
+  // re-measured by tests/electron-env-scrub-get5-contract.test.js on every run
+  // (round 3, seat B1 — the previous claim here was reasoned, never run):
+  // every read that decides the ARTIFACT's URL lands inside the window on BOTH
+  // routes (20 of 20, 0 after the restore), so a planted mirror cannot move this
+  // download. When `digest` is null there is no `checksums` table, and
+  // @electron/get then recursively downloads SHASUMS256.txt AFTER awaits with
+  // the environment restored — 13 planted reads, measured. That is
+  // availability-only: the zip's URL is already fixed, so the planted mirror can
+  // only serve a checksum file that disagrees with official bytes and FAIL the
+  // download. See electron-env-scrub.js for the three closures rejected and why.
+  //
+  // IT SCRUBS `process.env`, NOT THIS FUNCTION'S `env` ARGUMENT, and that is the
+  // point. `env` is an injectable input to cache-root RESOLUTION; the env
+  // @electron/get actually reads is `process.env`, and the library offers no way
+  // to change that. Threading `env` here would make the control silently do
+  // nothing for any caller that passed a synthetic one — a guard aimed at a
+  // surface its target never reads.
+  const zip = await withScrubbedRepoEnv(() => downloadArtifact({
+    version,
+    artifactName: 'electron',
+    // MEASURED, and stated because the surrounding prose used to claim
+    // otherwise: `force` is DEAD in @electron/get 5.0.0 — `effectiveCacheMode`
+    // never reads it — so this call can return a CACHE PATH with no network
+    // fetch at all. It is left in place because removing it changes nothing
+    // today and a later version may honour it again. What makes this route
+    // sound is not freshness: it is that amicus reads and hashes whatever path
+    // comes back, in its own memory.
+    force: true,
+    cacheRoot: cacheRootFor(env),
+    platform,
+    arch,
+    ...(digest ? { checksums: { [fileName]: digest } } : {}),
+    downloadOptions: { signal: AbortSignal.timeout(downloadMs) }, // 5.x native fetch: bound stalled downloads, free the lock
+  }));
+  // READ THE BYTES ONCE, and never resolve that path again. Everything after
+  // this line acts on a Buffer in amicus's own heap.
+  const held = readArtifactBytes({ zip, fs });
+  if (!held.bytes) {
+    return { pinned: false, refused: refuseUnreadableArtifact({ fileName, zip, why: held.why, detail: held.detail, log }) };
+  }
+  const gate = verifyArtifactBytes({ bytes: held.bytes, anchor, fileName, policy, log });
+  if (!gate.allowed) { return { pinned: false, refused: rejectDownloadedZip({ gate, fileName, log }) }; }
+  // C2, on BOTH routes — F3 is the standing reminder of what a rule wired to one
+  // provision route and not the other costs. See ./electron-native-rescue for the
+  // trigger boundary; `rescue.used` is folded into `pinned` below.
+  const rescue = {};
+  const extractOrRescue = withNativeRescue({ extract, gate, policy, rescue, platform, fs, spawn, log });
+  await extractBytesToDist({ bytes: held.bytes, electronDir, platform, extract: extractOrRescue, fs });
+  // BOTH halves, deliberately. `digest` says a `checksums` table went out, so a
+  // hatch-dropped pin still reports unverified even when the anchor happens to
+  // agree; `verdict === 'verified'` says amicus itself hashed these exact bytes
+  // and they matched. Either half alone has been wrong: F3's first cut reported
+  // the table, and the table alone is what seat F#2 showed does not describe the
+  // bytes that reach the extractor.
+  //
+  // `!rescue.used` IS IMPLIED TODAY, AND IS STATED ANYWAY — said out loud so it
+  // is not mistaken for a measured control. A rescue requires the hatch, and the
+  // hatch has already set `digest` to null above, so `pinned` is false on every
+  // hatch-on provision whether or not a rescue ran: on THIS route the term
+  // changes no observable result. It is here because the property it encodes —
+  // a tree a child process extracted from a path was never pinned — must not
+  // depend on that coupling holding. On the CACHE route the same term is
+  // load-bearing and observable (electron-repair-cache.js :: repairFromCache).
+  return { pinned: !!digest && gate.verdict === 'verified' && !rescue.used };
+}
+
+/**
+ * May this refused artifact be deleted? STRICTLY NARROWER than the unconditional
+ * `fs.rmSync` on the corrupt-extract path: the basename must be exactly the
+ * artifact we asked for, AND the file must resolve inside a resolved cache root.
+ * `containsOnDisk` realpaths both sides and returns false on any error, so an
+ * unresolvable path is refused rather than trusted — deleting at an
+ * attacker-influenceable path is the one thing a poisoned cache could otherwise
+ * turn into a weapon.
+ *
+ * Cost if it returns a wrong false: the mismatched zip stays and is re-downloaded
+ * once per provision. An availability cost, never a safety one — the gate above
+ * still refuses to extract it.
+ */
+function mayDeleteRejectedZip({ zip, fileName, env = process.env }) {
+  if (path.basename(zip) !== fileName) { return false; }
+  return resolveCacheRoots(env).some((root) => containsOnDisk(root, zip));
+}
+
+/**
+ * THERE IS NO LAST-RESORT INSTALLER ANY MORE (council seat B1, BLOCKER,
+ * confirmed 4 of 4). `runInstaller` spawned `<electronDir>/install.js`, which
+ * did its OWN download and its OWN extraction, outside every control on this
+ * page — and it was reached from `catch (provisionErr)` for ANY throw, so
+ * inducing one failure was enough to route around the whole gate.
+ *
+ * It was worse than "a bypass". install.js pins with
+ * `require('./checksums.json')` — the checksums of `<electronDir>`, the very
+ * directory `doctor --fix` located by SCANNING npx caches. That is the
+ * ANCHORFROMTARGET hole `resolveAnchor`'s rung 1 exists to close, and
+ * electron-trust.js records it as MEASURED-exploitable. It also extracted
+ * unbounded, with no stall protection and no path-traversal classification, and
+ * its success came back as a plain `{repaired: isElectronUsable()}` — bytes
+ * amicus never saw, labelled exactly like bytes it hashed.
+ *
+ * ITS ONE CLAIMED JUSTIFICATION WAS MEASURED FALSE. The case for keeping it was
+ * "amicus's own tree cannot resolve @electron/get but electron's can". On this
+ * machine, both resolve the SAME hoisted copy:
+ *   amicus   require.resolve('@electron/get')                 -> node_modules/@electron/get/dist/index.js
+ *   electron createRequire(electron/package.json).resolve(...) -> node_modules/@electron/get/dist/index.js
+ * Every other trigger — a network failure, a mirror checksum failure, an abort
+ * timeout, an extract failure — makes install.js do the same download the same
+ * way with weaker checks. That is not a fallback; it is a bypass with a retry's
+ * reputation. A failed provision is now reported honestly instead:
+ * `ensureElectron` already turns that into "the GUI is unavailable, headless
+ * runs and the council work", clears its single-flight guard so the next launch
+ * retries, and points at `doctor --fix`.
+ *
+ * `scrubbedChildEnv` died with it (there is no child to build an env for). The
+ * enumeration it encoded survives as `isRepoPlantedName` in electron-env-scrub,
+ * which is what the IN-PROCESS download scrub uses.
+ */
+
+module.exports = { cacheRootFor, controlledProvision, mayDeleteRejectedZip };