amicus 4.9.5 → 4.9.7

package/src/sidecar/electron-provision.js

@@ -1,11 +1,15 @@
 /**
- * Electron CONTROLLED provision — the pinned download, and what happens to a
- * cached artifact the digest gate refuses.
+ * 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 require arrow is
- * electron-install -> electron-provision -> electron-trust and must never point
- * back, so `extractFromCache` arrives as an argument rather than an import.
+ * 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
  */
@@ -15,7 +19,12 @@
 const path = require('path');
 
 const { resolveCacheRoots } = require('./electron-cache');
-const { artifactFileName, expectedDigest } = require('./electron-trust');
+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). */
@@ -25,8 +34,9 @@ function cacheRootFor(env = process.env) {
 
 /**
  * CONTROLLED provision: fetch the zip ourselves with the SAME @electron/get
- * api install.js uses (downloadArtifact, force:true), extract offline, and let
- * the caller verify isElectronUsable(). No blind install.js spawn.
+ * 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
@@ -48,11 +58,40 @@ function cacheRootFor(env = process.env) {
  * 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.
- * @returns {Promise<void>}
+ *
+ * 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, extractFromCache,
-  fs, env = process.env, downloadMs = 480000, policy = {}, log = () => {},
+  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);
@@ -60,18 +99,82 @@ async function controlledProvision({
     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.');
   }
-  const zip = await downloadArtifact({
+  // 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
-  });
-  await extractFromCache({ zip, electronDir, platform, extract, fs });
+  }));
+  // 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 };
 }
 
 /**
@@ -93,87 +196,37 @@ function mayDeleteRejectedZip({ zip, fileName, env = process.env }) {
 }
 
 /**
- * Act on a REFUSED cached artifact: remove the poison when it is safe to, say
- * plainly what happened, and hand back the result shape a cacheOnly caller
- * returns. Deletion happens ONLY on `mismatch` — a `no-digest` artifact is not
- * evidence of anything, and an `unreadable` one is a file we could not even hash.
- * @returns {{repaired:false, integrity:string, reason:string}}
- */
-function rejectCachedZip({ gate, zip, fileName, env = process.env, fs, log = () => {} }) {
-  let removed = false;
-  if (gate.verdict === 'mismatch' && mayDeleteRejectedZip({ zip, fileName, env })) {
-    try {
-      fs.rmSync(zip, { force: true });
-      removed = true;
-    } catch { /* a cache we cannot write is not a reason to fail the repair */ }
-  }
-  const what = gate.verdict === 'mismatch'
-    ? `sha256 ${gate.actual} does not match the published ${gate.expected}`
-    : gate.reason;
-  log(`[amicus] Electron artifact REFUSED: ${fileName}`);
-  log(`[amicus]   ${zip}`);
-  log(`[amicus]   ${what}`);
-  log('[amicus] This is what a swapped mirror or a planted cache file looks like. It is ALSO');
-  log('[amicus] what a truncated download, a failing disk, or a mirror serving a REBUILT');
-  log('[amicus] electron looks like — amicus cannot tell them apart.');
-  // ORDER MATTERS. The advice comes BEFORE the removal notice, and says what to
-  // do about a file that is already gone: a hand-seeded air-gapped cache is the
-  // one place the refused artifact was also the ONLY copy, and being told about
-  // the hatch after "The file has been removed." is being told too late to use
-  // it. The delete itself is required (a poisoned zip must not survive to be
-  // re-offered); the words around it are what make it recoverable.
-  log('[amicus] If you deliberately run a REBUILT electron, set');
-  log('[amicus] AMICUS_ALLOW_UNVERIFIED_ELECTRON=1 BEFORE provisioning again — it accepts these');
-  log('[amicus] bytes on the cache path and drops the digest pin on the download path.');
-  log(`[amicus]   ${removed
-    ? 'The file has been removed: re-copy it from the machine that downloaded it (or let'
-      + '\n[amicus]   amicus download it again) once that variable is set.'
-    : 'The file was left in place.'}`);
-  log('[amicus] Headless runs and the council work without the GUI.');
-  return {
-    repaired: false,
-    integrity: gate.verdict,
-    reason: `Cached electron artifact ${fileName} was REFUSED: ${what}.`
-      + `${removed ? ' It has been removed.' : ' It was left in place.'}`,
-  };
-}
-
-/** The terminal path-traversal refusal `robustExtract` throws (unzip.js C4). */
-function isUnsafeArchive(err) {
-  return !!err && err.code === 'UNZIP_UNSAFE_ARCHIVE';
-}
-
-/**
- * C4 AT THE CALL SITE. unzip.js classifies extract-zip's path-traversal refusals
- * as terminal so the same archive is never handed to an OS extractor that has no
- * such check. That invariant held only INSIDE unzip.js: both of repairElectron's
- * catch blocks used to swallow the refusal without reading `err.code` and launder
- * it back into exactly the retry the control forbids — the network path spawned
- * `node <electronDir>/install.js`, which re-downloads and re-extracts through
- * @electron-internal/extract-zip with no amicus supervision (the forbidden move,
- * one stack frame up), and the cache path deleted the zip through the UNFENCED
- * `fs.rmSync` and told the user it "was corrupt and removed" — a security refusal
- * reported as corruption. MEASURED both, before this change.
+ * 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.
  *
- * So the refusal ends here: no retry, no fallback extractor, and no delete. The
- * archive is left where it is, because a refused archive is evidence, and
- * `err.message` already carries the path and extract-zip's own reason.
- * @returns {{repaired:false, integrity:'unsafe-archive', reason:string}}
+ * 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.
  */
-function refuseUnsafeArchive({ err, fileName, log = () => {} }) {
-  const detail = (err && err.message) || 'the archive tried to write outside its destination';
-  log(`[amicus] Electron artifact REFUSED (unsafe archive): ${fileName}`);
-  log(`[amicus]   ${detail}`);
-  log('[amicus] Entries in that zip tried to write OUTSIDE the destination directory. amicus');
-  log('[amicus] will not retry it with another extractor, and has left the file in place.');
-  log('[amicus] Headless runs and the council work without the GUI.');
-  return {
-    repaired: false,
-    integrity: 'unsafe-archive',
-    reason: `Electron artifact ${fileName} was REFUSED: ${detail}. It was NOT retried and NOT removed.`,
-  };
-}
 
-module.exports = {
-  cacheRootFor, controlledProvision, mayDeleteRejectedZip, rejectCachedZip, isUnsafeArchive, refuseUnsafeArchive,
-};
+module.exports = { cacheRootFor, controlledProvision, mayDeleteRejectedZip };

package/src/sidecar/electron-refuse.js

@@ -0,0 +1,253 @@
+/**
+ * Electron artifact REFUSALS — the ways amicus declines to turn bytes into an
+ * Electron install, and the exact words it uses each time. The two NOTICES the
+ * native-extractor rescue speaks are the same kind of thing and were briefly
+ * here; they live in `./electron-rescue-notice` because this file sits at the
+ * repo's 300-line gate and they pushed it over. Same seam either side of the
+ * split: the words live in these two files, the policy does not.
+ *
+ * SPLIT OUT of electron-provision.js (v4.9.6, second council round) because that
+ * file sits under the repo's 300-line gate and the round added two more
+ * refusals: a DOWNLOADED artifact that fails amicus's own hash (F#2), and an
+ * artifact that could not be taken private at all (F#6/F#8). The split is along
+ * a real seam — everything here composes a message and returns a result shape,
+ * and nothing here decides policy. The one `rmSync` in the file is fenced by an
+ * answer its caller computed (`mayDelete`), never by anything derived here.
+ *
+ * F5 (council seat B5). Everything below that reaches stderr or a returned
+ * `reason` goes through the house sanitizer first, because two of its inputs are
+ * written by the attacker: an unsafe archive's refusal text carries the ARCHIVE'S
+ * OWN entry name, and a cached artifact's path carries a `<sha>` directory name
+ * read out of a cache root anyone can write. Unsanitized, either could embed ANSI
+ * escapes, a newline plus a forged `[amicus] …` line, or a right-to-left override
+ * that renders the rest of the sentence backwards — in the one message a user
+ * reads when amicus is telling them something is wrong.
+ *
+ * NEAR-LEAF MODULE: `utils/text-sanitize` only. electron-install.js and
+ * electron-provision.js both require it, which adds no cycle.
+ *
+ * @module sidecar/electron-refuse
+ */
+
+'use strict';
+
+const { collapseExcerpt } = require('../utils/text-sanitize');
+
+/**
+ * A path gets a longer cap than an error excerpt: 200 characters truncates a real
+ * npx-cache path, and a path the user cannot copy is not much use in a refusal.
+ */
+const PATH_EXCERPT_CHARS = 320;
+
+/**
+ * What each of `readArtifactBytes`'s refusals MEANS, in one clause the user can
+ * act on. Kept here rather than in the custody module so every user-facing
+ * sentence in this subsystem is written in one file.
+ */
+const UNREADABLE_REASON = {
+  unreadable: 'could not be opened or read at all',
+  'not-a-file': 'is not a regular file',
+  empty: 'is empty',
+  'too-large': 'is far larger than any electron artifact',
+  'short-read': 'ended early while amicus was reading it',
+  grew: 'changed size while amicus was reading it',
+};
+
+/** The terminal path-traversal refusal `robustExtract` throws (unzip.js C4). */
+function isUnsafeArchive(err) {
+  return !!err && err.code === 'UNZIP_UNSAFE_ARCHIVE';
+}
+
+/**
+ * C4 AT THE CALL SITE. unzip.js classifies extract-zip's path-traversal refusals
+ * as terminal so the same archive is never handed to an OS extractor that has no
+ * such check. That invariant held only INSIDE unzip.js: both of repairElectron's
+ * catch blocks used to swallow the refusal without reading `err.code` and launder
+ * it back into exactly the retry the control forbids — the network path spawned
+ * `node <electronDir>/install.js`, which re-downloads and re-extracts through
+ * @electron-internal/extract-zip with no amicus supervision (the forbidden move,
+ * one stack frame up), and the cache path deleted the zip through the UNFENCED
+ * `fs.rmSync` and told the user it "was corrupt and removed" — a security refusal
+ * reported as corruption. MEASURED both, before this change.
+ *
+ * So the refusal ends here: no retry, no fallback extractor, and no delete. The
+ * archive is left where it is, because a refused archive is evidence, and
+ * `err.message` already carries the path and extract-zip's own reason.
+ * @returns {{repaired:false, integrity:'unsafe-archive', reason:string}}
+ */
+function refuseUnsafeArchive({ err, fileName, log = () => {} }) {
+  // F5: this message quotes the ARCHIVE'S OWN entry name back at the user. The
+  // house sanitizer runs before it reaches stderr or the returned reason.
+  const detail = collapseExcerpt((err && err.message) || 'the archive tried to write outside its destination');
+  log(`[amicus] Electron artifact REFUSED (unsafe archive): ${fileName}`);
+  log(`[amicus]   ${detail}`);
+  log('[amicus] Entries in that zip tried to write OUTSIDE the destination directory. amicus');
+  log('[amicus] will not retry it with another extractor, and has left the file in place.');
+  log('[amicus] Headless runs and the council work without the GUI.');
+  return {
+    repaired: false,
+    integrity: 'unsafe-archive',
+    reason: `Electron artifact ${fileName} was REFUSED: ${detail}. It was NOT retried and NOT removed.`,
+  };
+}
+
+/**
+ * Act on a REFUSED cached artifact: remove the poison when it is safe to, say
+ * plainly what happened, and hand back the result shape a cacheOnly caller
+ * returns. Deletion happens ONLY on `mismatch` — a `no-digest` artifact is not
+ * evidence of anything, and an `unreadable` one is a file we could not even hash.
+ *
+ * `zip` is the ORIGINAL cache path, which is also the ONLY copy of these bytes
+ * anyone can reach: staging COPIES, so the artifact never left the cache and
+ * this `rmSync` is the whole delete, exactly as it was in v4.9.5. (The first cut
+ * of the F1 work made it conditional on a `moved` flag the stage object carried;
+ * seats F#4/F#5 caught the sibling branch where that silently removed nothing.)
+ *
+ * `mayDelete` IS THE FENCE'S ANSWER, PASSED IN, not re-derived here — the fence
+ * realpaths the artifact, so it has to be asked while the file is still where the
+ * caller found it.
+ * @returns {{repaired:false, integrity:string, reason:string}}
+ */
+function rejectCachedZip({ gate, zip, fileName, mayDelete = false, fs, log = () => {} }) {
+  let removed = false;
+  if (gate.verdict === 'mismatch' && mayDelete) {
+    try {
+      fs.rmSync(zip, { force: true });
+      removed = true;
+    } catch { /* a cache we cannot write is not a reason to fail the repair */ }
+  }
+  // F5: `gate.reason` is an fs error string (an `unreadable` verdict) and `zip` is
+  // an attacker-influenced cache path; the digests are 64-hex by construction.
+  const what = gate.verdict === 'mismatch'
+    ? `sha256 ${gate.actual} does not match the published ${gate.expected}`
+    : collapseExcerpt(gate.reason);
+  log(`[amicus] Electron artifact REFUSED: ${fileName}`);
+  log(`[amicus]   ${collapseExcerpt(zip, PATH_EXCERPT_CHARS)}`);
+  log(`[amicus]   ${what}`);
+  log('[amicus] This is what a swapped mirror or a planted cache file looks like. It is ALSO');
+  log('[amicus] what a truncated download, a failing disk, or a mirror serving a REBUILT');
+  log('[amicus] electron looks like — amicus cannot tell them apart.');
+  // ORDER MATTERS. The advice comes BEFORE the removal notice, and says what to
+  // do about a file that is already gone: a hand-seeded air-gapped cache is the
+  // one place the refused artifact was also the ONLY copy, and being told about
+  // the hatch after "The file has been removed." is being told too late to use
+  // it. The delete itself is required (a poisoned zip must not survive to be
+  // re-offered); the words around it are what make it recoverable.
+  log('[amicus] If you deliberately run a REBUILT electron, set');
+  log('[amicus] AMICUS_ALLOW_UNVERIFIED_ELECTRON=1 BEFORE provisioning again — it accepts these');
+  log('[amicus] bytes on the cache path and drops the digest pin on the download path.');
+  log(`[amicus]   ${removed
+    ? 'The file has been removed: re-copy it from the machine that downloaded it (or let'
+      + '\n[amicus]   amicus download it again) once that variable is set.'
+    : 'The file was left in place.'}`);
+  log('[amicus] Headless runs and the council work without the GUI.');
+  return {
+    repaired: false,
+    integrity: gate.verdict,
+    reason: `Cached electron artifact ${fileName} was REFUSED: ${what}.`
+      + `${removed ? ' It has been removed.' : ' It was left in place.'}`,
+  };
+}
+
+/**
+ * F#2 — a DOWNLOADED artifact that amicus hashed for itself and refused.
+ *
+ * WHY THERE IS A SECOND GATE AT ALL, when `checksums` already went out.
+ * @electron/get validates in its own temp dir and then RENAMES the artifact into
+ * the cache root, returning THAT path (5.0.0, dist/index.js lines 148-160 and
+ * Cache.js lines 60-76) — so the last bytes it vouched for live at a path the
+ * same cache-dir writer controls. On a cache HIT it is looser still: `force` is
+ * dead in 5.0.0 (the only read guard is `shouldTryReadCache(effectiveCacheMode(...))`,
+ * and amicus sends no `cacheMode`), so it validates a file AT ITS CACHE PATH and
+ * hands that back. Either way the vouching happened somewhere amicus does not
+ * control, which is the whole reason the bytes are read into memory and
+ * re-hashed here. (They are not COPIED anywhere: the private staging directory
+ * that used to hold them was deleted in this change, its privacy claim having
+ * been measured false.)
+ *
+ * NOTHING IS DELETED. The refused artifact stays where @electron/get put it, and
+ * the CACHE route removes it on the next run through the fence that was written
+ * for exactly that (`mayDeleteRejectedZip` + `rejectCachedZip`). Deleting from
+ * here would add a second, differently-fenced unlink for no gain: the number of
+ * downloads is the same either way.
+ * @returns {{repaired:false, integrity:string, reason:string}}
+ */
+function rejectDownloadedZip({ gate, fileName, log = () => {} }) {
+  const what = gate.verdict === 'mismatch'
+    ? `sha256 ${gate.actual} does not match the published ${gate.expected}`
+    : collapseExcerpt(gate.reason);
+  log(`[amicus] DOWNLOADED electron artifact REFUSED: ${fileName}`);
+  log(`[amicus]   ${what}`);
+  // WHAT THIS LINE MAY CLAIM. It used to promise the download was hashed inside
+  // a PRIVATE staging directory — a containment property that was DELETED in
+  // this same change, because the council measured it false (mkdtempSync yields
+  // mode 666 on Windows and the chmod(0o700) was skipped on win32, and a spinner
+  // found the fixed `amicus-electron-stage-` prefix on its FIRST readdir). The
+  // docs describing that copy were fixed and this string was missed; nothing
+  // pinned it, so nothing caught it. It now states the property that is
+  // actually true, and it is pinned by a test.
+  log('[amicus] amicus read these bytes ONCE, into its own memory, and hashed THAT buffer — the');
+  log('[amicus] same buffer it would have extracted. There is no copy on disk and no path in play');
+  log('[amicus] after the read. These bytes were NOT extracted and no Electron was installed from');
+  log('[amicus] them. Check what ELECTRON_MIRROR points at.');
+  log('[amicus] Headless runs and the council work without the GUI.');
+  return {
+    repaired: false,
+    integrity: gate.verdict,
+    reason: `Downloaded electron artifact ${fileName} was REFUSED: ${what}. It was NOT extracted.`,
+  };
+}
+
+/**
+ * Bytes amicus could not take into custody are never extracted.
+ *
+ * REPLACES `refuseUnstagedArtifact`, and the replacement is not cosmetic. The
+ * old refusal existed because staging COPIED the artifact into `os.tmpdir()`,
+ * so its whole vocabulary was about temp: "could not be copied into a private
+ * directory", "free up space in the temp directory". Council finding A3 caught
+ * the consequence — a cache entry deleted by a concurrent repair mid-copy was
+ * reported as "no space, or an unwritable temp directory", advice that could
+ * not possibly help. There is no copy and no temp directory any more; the only
+ * way to fail here is that the ARTIFACT ITSELF could not be read, and `why`
+ * says which way.
+ *
+ * The first cut of the staging work FAILED OPEN in this position: when the
+ * artifact could not be taken private the download route quietly extracted the
+ * unstaged cache path anyway, while the one line on screen said the bytes would
+ * not be extracted (seats F#6/F#8, MEASURED both shapes). Both routes refuse
+ * here now, and `integrity` is set so `scripts/postinstall.js` prints the reason
+ * instead of its generic "provisions on first use" notice.
+ *
+ * F5: `zip` is an attacker-influenced cache path (its `<sha>` directory name
+ * came out of a `readdirSync` of a directory anyone can write) and `detail` is
+ * an fs error string, so both are sanitized before reaching stderr or the
+ * returned reason.
+ * @param {object} o
+ * @param {string} o.fileName
+ * @param {string} o.zip
+ * @param {string} o.why    one of readArtifactBytes's named refusals
+ * @param {string} [o.detail]
+ * @returns {{repaired:false, integrity:'unreadable', reason:string}}
+ */
+function refuseUnreadableArtifact({ fileName, zip, why, detail = '', log = () => {} }) {
+  const where = collapseExcerpt(zip, PATH_EXCERPT_CHARS);
+  const what = UNREADABLE_REASON[why] || 'could not be read';
+  log(`[amicus] Electron artifact NOT extracted: ${fileName}`);
+  log(`[amicus]   ${where}`);
+  log(`[amicus]   ${what}${detail ? ` (${collapseExcerpt(detail)})` : ''}`);
+  log('[amicus] amicus reads an artifact ONCE, into memory, and hashes and extracts THOSE');
+  log('[amicus] bytes. It could not read these, so it has nothing it could vouch for and');
+  log('[amicus] has extracted nothing. The file was left exactly where it is.');
+  log('[amicus] Headless runs and the council work without the GUI.');
+  return {
+    repaired: false,
+    integrity: 'unreadable',
+    reason: `Electron artifact ${fileName} ${what}, so it was NOT extracted: ${where}.`
+      + ' It was left in place.',
+  };
+}
+
+module.exports = {
+  isUnsafeArchive, refuseUnsafeArchive, rejectCachedZip, rejectDownloadedZip, refuseUnreadableArtifact,
+  PATH_EXCERPT_CHARS,
+};