amicus 4.9.4 → 4.9.6

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

package/src/sidecar/electron-repair-cache.js

@@ -0,0 +1,212 @@
+/**
+ * ATTEMPT 1 of the electron self-heal: turn a CACHED artifact into a `dist/`,
+ * fully offline, in custody.
+ *
+ * SPLIT OUT of electron-install.js in the v4.9.6 second council round. That file
+ * sits at the repo's 300-line gate and this route grew a step (read into memory)
+ * while keeping every branch it already had. The seam is real: everything here
+ * answers "can this cache entry become an install", and nothing here decides
+ * where the cache is, what the anchor is, or what happens next — those arrive as
+ * arguments.
+ *
+ * THE SHAPE OF THE ROUTE, and what each step now promises:
+ *   1. READ the artifact ONCE into a Buffer (`electron-custody`). The path is
+ *      resolved exactly once, ever. Anything that goes wrong here is a REFUSAL
+ *      with a named `why`, never a silent fall-through.
+ *   2. HASH THAT BUFFER against the anchor (`electron-trust.verifyArtifactBytes`).
+ *   3. EXTRACT THAT BUFFER (`electron-layout.extractBytesToDist`), into an
+ *      incoming directory that is promoted by rename.
+ * There is no step in which a name is resolved a second time, which is what
+ * makes the claim "the bytes that were hashed are the bytes that were written"
+ * true rather than a race the attacker usually loses.
+ *
+ * WHAT AN EXTRACT FAILURE NOW MEANS (council finding D2). The old code deleted
+ * the cached artifact on ANY extract error, including a failure to write
+ * `dist/`. A full disk therefore destroyed a pristine cache entry — worst case
+ * on an air-gapped run with no network to re-fetch from. `zip-from-buffer`
+ * distinguishes the two: `UNZIP_BUFFER_FAILED` says the ARCHIVE is bad and is
+ * the only failure that CAN evict anything; `UNZIP_DEST_FAILED` says the
+ * DESTINATION is bad and never evicts. Since C2 even that one holds its fire on
+ * a run that OFFERED the native-extractor rescue: an offer whose own run
+ * destroys the artifact it points at is not an offer.
+ *
+ * NEAR-LEAF: requires the custody, trust, refusal, layout and provision-fence
+ * modules, and is required only by electron-install.js. The arrow is
+ * electron-install -> electron-repair-cache -> {electron-custody, electron-trust,
+ * electron-refuse, electron-layout, electron-provision} and never points back.
+ *
+ * @module sidecar/electron-repair-cache
+ */
+
+'use strict';
+
+const { readArtifactBytes } = require('./electron-custody');
+const { extractBytesToDist } = require('./electron-layout');
+const { withNativeRescue } = require('./electron-native-rescue');
+const { mayDeleteRejectedZip } = require('./electron-provision');
+const { avHint } = require('./electron-quarantine');
+const {
+  isUnsafeArchive, refuseUnsafeArchive, refuseUnreadableArtifact, rejectCachedZip,
+} = require('./electron-refuse');
+const { verifyArtifactBytes } = require('./electron-trust');
+const { collapseExcerpt } = require('../utils/text-sanitize');
+
+/**
+ * The ONE extract failure that is evidence the CACHED ARTIFACT is worthless,
+ * and therefore the only one that may delete it.
+ *
+ * IT IS A ONE-ENTRY ALLOW-LIST BECAUSE THE RULE HAS TO FAIL CLOSED. The first
+ * answer to D2 was a two-entry list of codes that KEEP the artifact, with
+ * everything else evicting — which failed OPEN toward deletion on every failure
+ * shape nobody had enumerated. MEASURED: an extractor throwing a plain `Error`
+ * with no `code` (an internal bug) and one throwing a raw Node `ENOSPC` BOTH
+ * deleted the artifact and told the user it "was corrupt and removed", which is
+ * D2's own shape one classification gap to the left — and D2's stated worst case
+ * is an air-gapped run with no network to re-fetch from.
+ *
+ * So the test is inverted: an extract failure removes the artifact only when the
+ * extractor positively identified the ARCHIVE as bad. Everything else — a full
+ * disk, an unwritable dist/, a promote that could not rename, an extractor that
+ * would not load, a stall, and any error a future extractor forgets to classify
+ * — keeps it. `zip-entry-write.js` is the other half of the contract: every
+ * throw there goes through one of its three constructors.
+ */
+const EVICTS_THE_ARTIFACT = 'UNZIP_BUFFER_FAILED';
+
+/**
+ * Try to provision from `zip`.
+ *
+ * @param {object} o
+ * @param {string}  o.zip        the cached artifact's path (attacker-influenced)
+ * @param {string}  o.fileName   the artifact name AMICUS resolved and validated
+ * @param {object}  o.anchor     resolveAnchor's result
+ * @param {object}  o.policy     electronTrustPolicy's result
+ * @param {boolean} o.cacheOnly  true = never fall through to a download
+ * @param {function} o.extract   the buffer extractor
+ * @param {function} o.verifyOutcome  the bound AV-quarantine check
+ * @returns {Promise<{done:true, result:object} | {done:false, refusal:object|null}>}
+ *   `done:false` means "fall through to the controlled download", carrying a
+ *   refusal the caller must still surface if the download also fails.
+ */
+async function repairFromCache({
+  zip, fileName, anchor, policy, electronDir, platform, arch, version,
+  cacheOnly, extract, verifyOutcome, fs, spawn, env = process.env, log = () => {},
+}) {
+  const held = readArtifactBytes({ zip, fs });
+  if (!held.bytes) {
+    const refusal = refuseUnreadableArtifact({ fileName, zip, why: held.why, detail: held.detail, log });
+    return cacheOnly ? { done: true, result: refusal } : { done: false, refusal };
+  }
+
+  // C2: extraction must be unreachable for an artifact the anchor contradicts.
+  // A missing anchor is NOT a refusal (see verifyArtifactBytes).
+  const gate = verifyArtifactBytes({ bytes: held.bytes, anchor, fileName, policy, log });
+  if (!gate.allowed) {
+    const mayDelete = mayDeleteRejectedZip({ zip, fileName, env });
+    const refusal = rejectCachedZip({ gate, zip, mayDelete, fileName, fs, log });
+    return cacheOnly ? { done: true, result: refusal } : { done: false, refusal };
+  }
+
+  // C2: a PARSE FAILURE — and nothing else — may be answered by the native
+  // extractor, and only when the hatch this route's own gate already honours is
+  // set. `./electron-native-rescue` owns that boundary and the custody it spends;
+  // `rescue.used` is what stops a rescued install ever reporting a clean repair,
+  // because the bytes in dist/ were then placed by a child process from a path.
+  const rescue = {};
+  const extractOrRescue = withNativeRescue({ extract, gate, policy, rescue, platform, fs, spawn, log });
+  try {
+    await extractBytesToDist({ bytes: held.bytes, electronDir, platform, extract: extractOrRescue, fs });
+    // A non-throwing extract with no exe is the AV-quarantine signature.
+    const outcome = verifyOutcome();
+    // A2/B3, and the gap the third round found in the first answer to them: the
+    // mark is `verdict !== 'verified'`, NOT `verdict === 'no-digest'`. The
+    // strictly more alarming case is the hatch-accepted MISMATCH — amicus
+    // hashed the bytes and they CONTRADICT the published sha256 — and under the
+    // narrow test that was the one case that reported a clean repair, with
+    // postinstall's warning, ensureElectron's launch NOTE and `doctor --fix`'s
+    // UNVERIFIED count all silent. MEASURED: same bytes, same contradicting
+    // anchor, AMICUS_ALLOW_UNVERIFIED_ELECTRON=1 — the DOWNLOAD route marked it
+    // (it drops the pin and requires `verified`) and this one did not. The two
+    // routes now agree: `verified` is the only verdict that reports clean.
+    //
+    // C2 ADDS A SECOND WAY TO LOSE `verified`, for the same reason the first
+    // exists: a NATIVE RESCUE extracted a path through a child process, so
+    // whatever landed in dist/ is not what amicus hashed, whatever the artifact's
+    // own digest said.
+    return { done: true, result: gate.verdict === 'verified' && !rescue.used ? outcome : { ...outcome, unverified: true } };
+  } catch (err) {
+    // C4 IS A CALL-SITE INVARIANT. A path-traversal refusal must not be
+    // deleted-and-retried, nor reported as "corrupt" — it stops here, and the
+    // archive is LEFT IN PLACE, because a refused archive is evidence.
+    if (isUnsafeArchive(err)) { return { done: true, result: refuseUnsafeArchive({ err, fileName, log }) }; }
+    // D2: only a bad ARCHIVE is evidence that the cached artifact is worthless.
+    // A full disk, an unwritable dist/, a promote that could not rename, an
+    // extractor that would not load and an error nobody classified all say
+    // nothing about the artifact, so it keeps its bytes. (The v4.5.2 outage is
+    // why an unloadable extractor is in here: an undeclared zip library must not
+    // be able to delete a user's only artifact on its way out.)
+    if (!err || err.code !== EVICTS_THE_ARTIFACT) {
+      const refusal = {
+        repaired: false,
+        integrity: 'extract-failed',
+        // F5: the extractor's message can quote the ARCHIVE'S OWN entry name and
+        // an fs error string built from an attacker-influenced path.
+        reason: `Cached electron artifact ${fileName} was NOT extracted (${collapseExcerpt((err && err.message) || '')});`
+          + ' it was LEFT IN PLACE: only an archive amicus positively identified as bad is removed.',
+      };
+      log(`[amicus] ${refusal.reason}`);
+      return cacheOnly ? { done: true, result: refusal } : { done: false, refusal };
+    }
+    // C2 (round 4): AN OFFER IS A PROMISE, AND THIS IS WHERE IT IS KEPT. With the
+    // hatch off, the wrapper above has just printed a ten-line offer telling an
+    // air-gapped user to set AMICUS_ALLOW_UNVERIFIED_ELECTRON=1 and provision
+    // again — and the eviction below hangs on the IDENTICAL code, so the first
+    // cut deleted the artifact on the way out and the promised re-run found
+    // nothing to rescue (MEASURED: the full offer on stderr, `was corrupt and
+    // removed`, `existsSync(zip) === false`, then `No cached electron zip found`).
+    // The cost of keeping it is the availability cost the fence below already
+    // accepts on a wrong `false`: it survives and is re-downloaded once per
+    // provision. A rescue that was named must still exist to be taken.
+    if (rescue.offered) {
+      const kept = `Cached electron zip for v${version} (${platform}-${arch}) could not be read and was `
+        + 'LEFT IN PLACE: the native-extractor rescue was offered on this run and needs this copy; '
+        + `${cacheOnly ? 'deferring re-download' : 'trying a fresh download'}.` + avHint(platform);
+      log(`[amicus] ${kept}`);
+      return cacheOnly
+        ? { done: true, result: { repaired: false, reason: kept } }
+        : { done: false, refusal: { repaired: false, integrity: 'corrupt-artifact', reason: kept } };
+    }
+    // The archive really is bad: evict it — THROUGH THE SAME FENCE the mismatch
+    // eviction uses — and claim only what happened.
+    //
+    // C2 (round 3): this was a bare `fs.rmSync(zip, { force: true })`. Two
+    // deletes of the same attacker-influenced path lived in this one module, one
+    // fenced and one not, and `mayDeleteRejectedZip`'s own docblock had already
+    // written the reason down — it called itself "STRICTLY NARROWER than the
+    // unconditional `fs.rmSync` on the corrupt-extract path" and left that path
+    // unconditional. `zip` comes out of a `readdirSync` of a directory anyone can
+    // write, so the fence realpaths it, requires the basename to be exactly the
+    // artifact amicus asked for, and requires it to resolve inside a resolved
+    // cache root; `containsOnDisk` returns false on any error, so an
+    // unresolvable path is refused rather than trusted.
+    //
+    // COST OF A WRONG `false`: a corrupt zip survives and is re-downloaded once
+    // per provision, and the reason below says "left in place" — the same
+    // availability cost the mismatch fence already accepts, never a safety one.
+    let removed = false;
+    if (mayDeleteRejectedZip({ zip, fileName, env })) {
+      try { fs.rmSync(zip, { force: true }); removed = true; } catch { /* an unwritable cache is not a repair failure */ }
+    }
+    const reason = `Cached electron zip for v${version} (${platform}-${arch}) was corrupt and `
+      + `${removed ? 'removed' : 'left in place'}; ${cacheOnly ? 'deferring re-download' : 'trying a fresh download'}.`
+      + avHint(platform);
+    // A1: this used to leave `refusal` null on the non-cacheOnly branch, so a
+    // failed re-download afterwards returned a bare {repaired:false} with no
+    // reason at all — after deleting the user's only artifact.
+    return cacheOnly
+      ? { done: true, result: { repaired: false, reason } }
+      : { done: false, refusal: { repaired: false, integrity: 'corrupt-artifact', reason } };
+  }
+}
+
+module.exports = { repairFromCache };

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

@@ -0,0 +1,78 @@
+/**
+ * THE TWO NOTICES the native-extractor rescue speaks — the offer a parse failure
+ * gets when the hatch is OFF, and the window disclosure printed when it is ON.
+ *
+ * SPLIT OUT of `./electron-refuse` (v4.9.6, C2 round 4): that file sits at the
+ * repo's 300-line gate and these two functions pushed it two lines over. The
+ * seam is the one it already had — everything in both files composes a message
+ * a user reads and decides nothing. `./electron-native-rescue` owns which
+ * failures reach either of these, and it is the only caller.
+ *
+ * WHY THE WORDS ARE THIS BLUNT. The rescue writes bytes amicus hashed to a path
+ * and hands that path to a child process, which is the one thing the rest of the
+ * provisioning exists to avoid. Neither notice may describe that as safe; both
+ * say what the window is while it is open. F5's sanitizer runs on everything
+ * here that quotes an extractor message or a path.
+ *
+ * NEAR-LEAF: `./electron-refuse` (for `PATH_EXCERPT_CHARS`) and
+ * `../utils/text-sanitize`. Nothing requires it back.
+ *
+ * @module sidecar/electron-rescue-notice
+ */
+
+'use strict';
+
+const { PATH_EXCERPT_CHARS } = require('./electron-refuse');
+const { collapseExcerpt } = require('../utils/text-sanitize');
+
+/**
+ * THE OFFER a parse failure gets when the native-extractor rescue is NOT armed.
+ *
+ * It NAMES `AMICUS_ALLOW_UNVERIFIED_ELECTRON` and says what setting it would do,
+ * so an air-gapped user whose archive amicus cannot read can find the escape
+ * hatch without reading the source — the whole point of the C2 finding. It is
+ * printed for a PARSE FAILURE and nothing else: a security refusal must never be
+ * answered with an offer to retry, which is C4 with a human in the loop.
+ * `electron-native-rescue.js` owns which failures reach here.
+ *
+ * AND IT PROMISES THE ARCHIVE IS STILL THERE, which is a claim its callers now
+ * keep: printing this offer sets `rescue.offered`, and the cache route reads that
+ * and does NOT evict (`electron-repair-cache.js`). The first cut said all of the
+ * above and then deleted the artifact on the way out, so the re-run it asks for
+ * had nothing to rescue — the last sentence exists to be falsifiable.
+ */
+function offerNativeRescue({ reason, log = () => {} }) {
+  log(`[amicus] amicus could not read this Electron archive: ${collapseExcerpt(reason)}`);
+  log('[amicus] There is ONE rescue for that, and it is OFF. With');
+  log('[amicus] AMICUS_ALLOW_UNVERIFIED_ELECTRON=1 set BEFORE provisioning, amicus writes the bytes');
+  log('[amicus] it hashed into a private directory inside the electron package and hands that PATH');
+  log('[amicus] to a native extractor (tar / Expand-Archive / ditto / unzip) — the only way an');
+  log('[amicus] archive amicus cannot parse becomes an install on a machine with no network to');
+  log('[amicus] re-download from. It COSTS custody: between amicus writing that file and the child');
+  log('[amicus] process opening it, anything running as your user can substitute it, and what the');
+  log('[amicus] child extracts is promoted into dist/ without ever being hashed again. That is not');
+  log('[amicus] safe — it is the trade the flag buys. Prefer a different copy of the artifact.');
+  log('[amicus] This run has NOT discarded the archive it could not read: the copy you have is still');
+  log('[amicus] there, so setting the variable and running again has something to act on.');
+}
+
+/**
+ * THE NOTICE a user sees when the rescue actually runs. Printed BEFORE the child
+ * is spawned, because the window opens at the write, and it DESCRIBES that window
+ * instead of reassuring anyone about it — the rescue is not safe, and the words a
+ * user reads while it happens have to say so.
+ */
+function announceNativeRescue({ zip, reason, log = () => {} }) {
+  log('[amicus] AMICUS_ALLOW_UNVERIFIED_ELECTRON=1 — running the NATIVE-EXTRACTOR RESCUE.');
+  log(`[amicus]   amicus could not read the archive itself: ${collapseExcerpt(reason)}`);
+  log('[amicus] THE WINDOW THIS OPENS, stated plainly. amicus has written the bytes it hashed to');
+  log(`[amicus]   ${collapseExcerpt(zip, PATH_EXCERPT_CHARS)}`);
+  log('[amicus] and is about to hand that PATH to a native extractor it does not control. Between');
+  log('[amicus] the write and the child opening the file, anything running as your user can');
+  log('[amicus] replace it, and whatever the child extracts is promoted into dist/ WITHOUT being');
+  log('[amicus] hashed again. So this run is not covered by the property the rest of the');
+  log('[amicus] provisioning holds to — that amicus only ever writes bytes it hashed. It is NOT');
+  log('[amicus] safe; it is what the flag buys, and the result is reported as unverified.');
+}
+
+module.exports = { offerNativeRescue, announceNativeRescue };