amicus 4.9.5 → 4.9.6

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

package/src/sidecar/electron-trust.js

@@ -1,5 +1,7 @@
 /**
- * Electron artifact TRUST core — the digest anchor, the gate, and the env scrub.
+ * Electron artifact TRUST core — the digest anchor and the gate. (The third
+ * member of the cluster, the installer-spawn env scrub, lives in
+ * ./electron-env-scrub and is re-exported here; see below.)
  *
  * A hostile REPOSITORY (a clone the user opens, an unpacked sample) controls the
  * `.npmrc` and `package.json` of the directory amicus's own docs tell people to
@@ -18,11 +20,21 @@
  * electron's own published sha256. Blocking the URL itself is defence in depth on
  * top of a control that already works, and is deliberately NOT built here.
  *
- * LEAF MODULE: `crypto` + `path` + `fs` and nothing from this repo. The arrow is
- * electron-install -> electron-provision -> electron-trust and must never point
+ * NEAR-LEAF MODULE: `crypto` + `path` + `fs`, plus `./electron-env-scrub`, which
+ * is itself a true leaf (no requires at all). The arrow is electron-install ->
+ * electron-provision -> electron-trust -> electron-env-scrub and must never point
  * back; src/utils/path-fence.js:11-17 records what a cycle does to a destructured
  * import in exactly this cluster.
  *
+ * THE ENV SCRUB LIVES NEXT DOOR (v4.9.6 F2). `isRepoPlantedName` and
+ * `REPO_ENV_PREFIXES` moved to `./electron-env-scrub` when this file hit the
+ * 300-line gate with the F2 repair still to land, and are RE-EXPORTED here so
+ * existing import paths stay valid — the same shape as engine-log-parse.js
+ * re-exporting utils/text-sanitize.js. There is ONE implementation; these are
+ * the same function objects, not a second copy. (`scrubbedChildEnv` and
+ * `ELECTRON_INSTALL_TARGET_ENV` were deleted with the install.js spawn they
+ * served; see electron-provision.js for why that spawn is gone.)
+ *
  * @module sidecar/electron-trust
  */
 
@@ -32,53 +44,7 @@ const crypto = require('crypto');
 const fsDefault = require('fs');
 const path = require('path');
 
-/**
- * Env-name PREFIXES an untrusted REPOSITORY can plant. MEASURED, npm 11: a repo
- * .npmrc key `k` reaches an `npm run` / `npm exec` child as
- * `npm_config_<k lowercased>`; a repo package.json "config" key `k` reaches it as
- * `npm_package_config_<k>` with case preserved. Nothing else.
- *
- * PREFIXES, not a hand-maintained name list. Two prefixes cover every
- * `@electron/get` mirror knob in each repo-reachable spelling, plus electron's
- * own `npm_config_electron_use_remote_checksums` (electron's install.js, lines
- * 47-50 — that name turns electron's bundled pin OFF), plus any knob a future
- * @electron/get adds in the same namespace. Contrast ENGINE_CREDENTIAL_ENV
- * (scripts/run-integration-keyless.js:101), whose own docblock warns that nothing
- * makes a name list follow an upstream bump.
- *
- * The BARE `electron_use_remote_checksums` is deliberately NOT removed: a bare
- * lower-case name is not repo-injectable, so it carries the machine owner's
- * intent, exactly like a bare `ELECTRON_MIRROR`.
- *
- * MATCHED CASE-INSENSITIVELY. This used to fold no case, on the claim that
- * because the Windows environment block is case-insensitive, deleting the
- * lower-case name also removed the `NPM_CONFIG_ELECTRON_*` view @electron/get
- * reads second. That is true of `process.env` and FALSE of the `{...env}` PLAIN
- * OBJECT this module actually deletes from — a plain object is case-sensitive on
- * every platform, so the upper-case key survived and was handed to the child.
- * RE-MEASURED (npm 11.16.0, Windows 11) — two ways a repository reaches an
- * upper-case slot:
- *   1. `.npmrc` `electron_mirror=…` while `NPM_CONFIG_ELECTRON_MIRROR` already
- *      exists in the environment: npm overwrites that slot's VALUE and never
- *      renames it, so the child sees the ATTACKER's URL under the upper-case name.
- *   2. `package.json` `"config": {"ELECTRON_MIRROR": …}`: npm PRESERVES the key's
- *      case, planting `npm_package_config_ELECTRON_MIRROR` with nothing
- *      pre-existing at all — and @electron/get's own lookup for
- *      `npm_package_config_electron_mirror` (dist/artifact-utils.js, line 28) finds it,
- *      because the Windows lookup is case-insensitive too.
- * The old docblock's POSIX half (`NPM_CONFIG_ELECTRON_*` is a distinct variable
- * npm never writes there, so it is the machine owner's) is NOT measurable from
- * this machine, and it is load-bearing in the fail-OPEN direction: wrong, it
- * hands the child an attacker's mirror. Wrong the other way it costs one
- * alternate spelling inside a last-resort spawn, while bare `ELECTRON_MIRROR`
- * — which @electron/get ranks FIRST — still carries owner intent. So the fold is
- * unconditional rather than resting on an unverified platform claim.
- */
-const REPO_ENV_PREFIXES = ['npm_config_electron_', 'npm_package_config_electron_'];
-
-/** electron's install.js, lines 20-21 and 99 — these choose WHICH artifact it
- *  fetches, and `.npmrc` `platform=`/`arch=` plants both. Same case fold. */
-const ELECTRON_INSTALL_TARGET_ENV = ['npm_config_platform', 'npm_config_arch'];
+const { isRepoPlantedName, REPO_ENV_PREFIXES } = require('./electron-env-scrub');
 
 /** A published sha256 is 64 LOWER-case hex characters. Anything else is not an anchor. */
 const HEX64 = /^[0-9a-f]{64}$/;
@@ -89,13 +55,6 @@ function normalizeV(version) {
   return v.startsWith('v') ? v : `v${v}`;
 }
 
-/** True for a name a hostile repository could have planted, in ANY case (see above). */
-function isRepoPlantedName(name) {
-  const lower = String(name).toLowerCase();
-  return REPO_ENV_PREFIXES.some((prefix) => lower.startsWith(prefix))
-    || ELECTRON_INSTALL_TARGET_ENV.includes(lower);
-}
-
 /**
  * The amicus-namespaced trust policy. THE ONLY place the escape hatch is read.
  * Never reads npm_config_* / npm_package_config_* / NPM_CONFIG_* — those are the
@@ -201,53 +160,48 @@ function expectedDigest(anchor, fileName) {
   return typeof digest === 'string' && HEX64.test(digest) ? digest : null;
 }
 
-/** Chunked sha256 (1 MiB buffer, openSync/readSync). SYNC so it composes with
- *  repairElectron's injected `fs`; chunked so a ~170 MB zip is never buffered whole. */
-function sha256File(file, fs = fsDefault) {
-  const hash = crypto.createHash('sha256');
-  const buffer = Buffer.alloc(1024 * 1024);
-  const fd = fs.openSync(file, 'r');
-  try {
-    let read = fs.readSync(fd, buffer, 0, buffer.length, null);
-    while (read > 0) {
-      hash.update(buffer.subarray(0, read));
-      read = fs.readSync(fd, buffer, 0, buffer.length, null);
-    }
-  } finally {
-    try { fs.closeSync(fd); } catch { /* already closed */ }
-  }
-  return hash.digest('hex');
+/** sha256 of an artifact amicus already holds in its own heap. */
+function sha256Bytes(bytes) {
+  return crypto.createHash('sha256').update(bytes).digest('hex');
 }
 
 /**
- * THE GATE. NEVER THROWS. `allowed` is the single decision bit callers act on.
+ * THE GATE, OVER BYTES. NEVER THROWS. `allowed` is the single decision bit.
  *
  * @returns {{verdict:'verified',   allowed:true,  actual:string}
  *         | {verdict:'mismatch',   allowed:boolean, expected:string, actual:string}
- *         | {verdict:'no-digest',  allowed:true}
- *         | {verdict:'unreadable', allowed:false, reason:string}}
+ *         | {verdict:'no-digest',  allowed:true}}
+ *
+ * IT TAKES A BUFFER, AND THE PATH FORM IS GONE. `verifyArtifact({zip, ...})` and
+ * `sha256File` were DELETED in the v4.9.6 second council round, not deprecated.
+ * Hashing a path and then handing that path to an extractor is the race three
+ * seats filed against v4.9.5, and hashing a private COPY of it is the race a
+ * fourth seat filed against the remedy — a same-uid attacker opens the copy too
+ * (MEASURED). Leaving a path-hashing gate exported and callable is an invitation
+ * to reintroduce it, and no caller is left that could legitimately want one. The
+ * bytes now arrive from `electron-custody.readArtifactBytes`, which reads them
+ * once through one descriptor, and the SAME Buffer is what `zip-from-buffer`
+ * extracts.
+ *
+ * `unreadable` disappeared with the path form. Unreadability is decided BEFORE
+ * any hashing now, by `readArtifactBytes`, and the caller refuses there — bytes
+ * that could not be read never reach this function, so there is no verdict for
+ * them to carry.
  *
  * `no-digest` is ALLOWED and merely marked. An electron package that predates
  * `checksums.json` has no anchor through no fault of its own, and refusing it
  * would push that machine into a permanent re-download loop for a file no
- * download can improve.
- *
- * `unreadable` is refused whatever the policy says: bytes that cannot be hashed
- * cannot be extracted either, so there is nothing to fail open to.
+ * download can improve. THE NOTE BELOW IS THE CACHE ROUTE'S stderr line, the one
+ * `docs/troubleshooting.md` promises; the download route prints its own.
  */
-function verifyArtifact({ zip, anchor, fileName, policy = {}, fs = fsDefault, log = () => {} }) {
+function verifyArtifactBytes({ bytes, anchor, fileName, policy = {}, log = () => {} }) {
   const expected = expectedDigest(anchor, fileName);
   if (!expected) {
     log(`[amicus] NOTE: no published sha256 for ${fileName} (this electron package ships no`);
     log('[amicus]   checksums.json entry for it), so its bytes could not be verified.');
     return { verdict: 'no-digest', allowed: true };
   }
-  let actual;
-  try {
-    actual = sha256File(zip, fs);
-  } catch (e) {
-    return { verdict: 'unreadable', allowed: false, reason: `could not hash ${fileName}: ${(e && e.message) || e}` };
-  }
+  const actual = sha256Bytes(bytes);
   if (actual === expected) { return { verdict: 'verified', allowed: true, actual }; }
   if (policy.allowUnverified) {
     log(`[amicus] WARNING: AMICUS_ALLOW_UNVERIFIED_ELECTRON=1 — accepting ${fileName} even though`);
@@ -258,42 +212,15 @@ function verifyArtifact({ zip, anchor, fileName, policy = {}, fs = fsDefault, lo
   return { verdict: 'mismatch', allowed: false, expected, actual };
 }
 
-/**
- * A COPY of env for the runInstaller SPAWN. Never mutates the argument.
- *
- * electron's own install.js honours `npm_config_electron_mirror` (through
- * @electron/get) AND `npm_config_electron_use_remote_checksums` (its lines 47-50,
- * which turns its bundled pin off), so spawning it with an unfiltered
- * `{...process.env}` would funnel a blocked attacker straight into an unpinned
- * downloader. `npm_config_platform` / `npm_config_arch` (its lines 20-21 and 99)
- * choose WHICH artifact it fetches, so they are removed too and amicus's own
- * resolution is pinned through `ELECTRON_INSTALL_PLATFORM`/`_ARCH`, which
- * install.js ranks above them.
- *
- * LEAVES ALONE, deliberately — every one of these is a BARE name a repository
- * cannot plant, so it is the machine owner's: `ELECTRON_MIRROR`,
- * `ELECTRON_CUSTOM_*`, `electron_config_cache`, `ELECTRON_CACHE`,
- * `electron_use_remote_checksums`, `HTTP_PROXY`/`HTTPS_PROXY`/`ELECTRON_GET_USE_PROXY`.
- */
-function scrubbedChildEnv({ env = process.env, platform, arch } = {}) {
-  const out = { ...env };
-  for (const name of Object.keys(out)) {
-    if (isRepoPlantedName(name)) { delete out[name]; }
-  }
-  if (platform) { out.ELECTRON_INSTALL_PLATFORM = platform; }
-  if (arch) { out.ELECTRON_INSTALL_ARCH = arch; }
-  return out;
-}
-
 module.exports = {
   electronTrustPolicy,
   resolveAnchor,
   expectedDigest,
-  verifyArtifact,
-  sha256File,
+  verifyArtifactBytes,
+  sha256Bytes,
   artifactFileName,
-  scrubbedChildEnv,
   normalizeV,
+  // RE-EXPORTED from ./electron-env-scrub — the same function objects, not copies.
+  isRepoPlantedName,
   REPO_ENV_PREFIXES,
-  ELECTRON_INSTALL_TARGET_ENV,
 };

package/src/sidecar/unzip.js

@@ -30,6 +30,10 @@ const path = require('path');
 const fsDefault = require('fs');
 const { spawnSync } = require('child_process');
 
+// F5: refusals quote the ARCHIVE'S OWN entry name, so every message built from
+// one is sanitized before it reaches stderr or an Error a caller prints.
+const { collapseExcerpt } = require('../utils/text-sanitize');
+
 /**
  * A SECURITY REFUSAL IS A REFUSAL, NOT A RETRY (M9).
  *
@@ -48,6 +52,11 @@ const { spawnSync } = require('child_process');
  *
  * DELIBERATELY NARROW. A stall must still fall back, or the Node-24 workaround
  * this whole module exists for is destroyed.
+ *
+ * AND THE VERIFICATION NO LONGER DECAYS (v4.9.6 F4). "Verified against the
+ * installed versions" had nothing keeping it true; tests/sidecar/unzip-refusal-strings.js
+ * now drives the INSTALLED libraries into producing all four for real, and fails
+ * both on a reworded refusal and on a pattern no real message produces.
  */
 const UNSAFE_PATTERNS = [
   /^Out of bound path /,
@@ -237,13 +246,13 @@ async function robustExtract(zip, opts = {}) {
   // archive to tar/Expand-Archive would ask a tool with no such check to do what
   // extract-zip just declined to.
   if (!z.ok && UNSAFE_PATTERNS.some((p) => p.test(z.reason || ''))) {
-    const err = new Error(`refusing to extract ${zip}: ${z.reason}`);
+    const err = new Error(`refusing to extract ${zip}: ${collapseExcerpt(z.reason)}`);
     err.code = 'UNZIP_UNSAFE_ARCHIVE';
     throw err;
   }
 
   // extract-zip stalled / threw / produced nothing → clean partial output, go native.
-  const zipReason = z.ok ? 'extract-zip produced no files' : z.reason;
+  const zipReason = z.ok ? 'extract-zip produced no files' : collapseExcerpt(z.reason);
   cleanDir(fs, dir);
   log(`[amicus] extract-zip did not complete (${zipReason}); falling back to native unzip.`);
 
@@ -283,4 +292,5 @@ async function robustExtract(zip, opts = {}) {
   throw err;
 }
 
-module.exports = { robustExtract, nativeUnzipPlan, IDLE_MS, MAX_MS };
+// UNSAFE_PATTERNS is exported for the F4 upstream-drift probe (see its docblock).
+module.exports = { robustExtract, nativeUnzipPlan, IDLE_MS, MAX_MS, UNSAFE_PATTERNS };