amicus 4.9.4 → 4.9.6

package/scripts/postinstall.js

@@ -42,7 +42,18 @@ const PROVISION_TIMEOUT_MS = 15000;
  * there is no cache (or the repair defers/contends), we emit a clear notice that
  * the GUI provisions on first use and that headless runs + the council already
  * work, then point at `amicus doctor --fix` (#56) — NOT a reinstall, which can
- * loop. A short timeout keeps a slow disk from ever hanging the install.
+ * loop.
+ *
+ * WHAT IS ACTUALLY BOUNDED HERE, stated precisely because the old sentence
+ * ("a short timeout keeps a slow disk from ever hanging the install") named a
+ * bound that does not exist on the default path. `PROVISION_TIMEOUT_MS` reaches
+ * `repairElectron` as `timeoutMs`, and `timeoutMs` becomes the DOWNLOAD budget
+ * (`electron-provision.js`'s `downloadMs`) — which the cache-only default path
+ * never uses, because it never downloads. The extract is what could hang here,
+ * and it is bounded by the extractor's own idle and hard caps
+ * (`zip-from-buffer.js`: 30 s with no progress, 240 s total), whose live timer
+ * handle is also what stops Node exiting 0 in the middle of a stall. Both
+ * bounds are real; neither is the other.
  *
  * This MUST never throw out of postinstall — the whole body (sync setup, the
  * awaited repair, and a synchronous-throw resolver) is guarded so nothing here
@@ -58,6 +69,15 @@ const PROVISION_TIMEOUT_MS = 15000;
  * @param {object} deps - { repairElectron } override for testing.
  * @returns {Promise<void>}
  */
+function warnIfUnverified(result) {
+  if (!result || !result.unverified) { return; }
+  console.warn('[amicus] Note: the Electron GUI binary was installed UNVERIFIED — either no published sha256');
+  console.warn('[amicus]   covered this artifact, so its bytes were checked only against whatever the mirror');
+  console.warn('[amicus]   served, or its sha256 CONTRADICTED the published one and');
+  console.warn('[amicus]   AMICUS_ALLOW_UNVERIFIED_ELECTRON accepted it anyway.');
+  console.warn('[amicus]   See docs/troubleshooting.md (Electron artifact REFUSED).');
+}
+
 async function provisionElectron(deps = {}) {
   try {
     const _repair = deps.repairElectron || repairElectron;
@@ -65,9 +85,10 @@ async function provisionElectron(deps = {}) {
     // Opt-in aggressive prewarm (#60): full fetch if needed. Non-fatal.
     if (process.env.AMICUS_PREFETCH_ELECTRON === '1') {
       console.log('[amicus] AMICUS_PREFETCH_ELECTRON=1 — prewarming the Electron GUI binary (may download)...');
-      const forced = await _repair({ force: true });
+      const forced = await _repair();
       if (forced && forced.repaired) {
         console.log('[amicus] Electron GUI binary prewarmed.');
+        warnIfUnverified(forced);
         return;
       }
       if (forced && forced.quarantined) {
@@ -80,7 +101,7 @@ async function provisionElectron(deps = {}) {
     }
 
     const result = await _repair({ cacheOnly: true, timeoutMs: PROVISION_TIMEOUT_MS });
-    if (result && result.repaired) { return; }
+    if (result && result.repaired) { warnIfUnverified(result); return; }
     // AV quarantine (electron.exe deleted right after extract) needs ACTION, not
     // a generic "provisions on first use" notice — re-extracting can never win,
     // so print the allow-list instruction verbatim instead. (No retry loop.)
@@ -89,6 +110,10 @@ async function provisionElectron(deps = {}) {
       console.warn('[amicus] Headless runs and the council already work without the GUI.');
       return;
     }
+    // A trust REFUSAL is not the same as "no cache yet": the artifact was found,
+    // hashed, and rejected. One line, so the reason is not lost behind the generic
+    // notice below (docs/troubleshooting.md promises this line).
+    if (result && result.integrity) { console.warn(`[amicus] Note: ${result.reason}`); }
     // No cache hit (deferred), contended, or otherwise not provisioned now.
     console.warn('[amicus] Note: the Electron GUI binary is not provisioned yet — it will download on first use of the interactive GUI / setup-wizard.');
     console.warn(`[amicus] Headless runs and the council already work. To provision the GUI now: ${HINTS.doctorFix}`);

package/src/sidecar/electron-cache.js

@@ -10,6 +10,7 @@
 
 'use strict';
 
+const fsDefault = require('fs');
 const path = require('path');
 const os = require('os');
 
@@ -39,4 +40,43 @@ function resolveCacheRoots(env = process.env) {
   return [...new Set(roots.filter(Boolean))];
 }
 
-module.exports = { resolveCacheRoots, defaultCacheRoot };
+/**
+ * Locate a previously-downloaded electron zip in the env-configurable cache
+ * roots. Walks <root>/<sha>/electron-v<ver>-<platform>-<arch>.zip.
+ *
+ * MOVED here from electron-install.js (v4.9.6 F1): that file sits at the 300-line
+ * gate with no headroom, and the F1 staging wiring had to go somewhere. Cache
+ * LOOKUP belongs beside cache-root RESOLUTION anyway; electron-install.js
+ * re-exports it so `ei.cachedZip` stays a valid import.
+ *
+ * The `<sha>` directory names come from `readdirSync` on a directory an attacker
+ * may write, so the returned path is attacker-INFLUENCED. Callers must treat it
+ * as such: read it ONCE into memory and hash and extract THOSE bytes, never
+ * resolving the name a second time (sidecar/electron-custody.js), and never
+ * print it unsanitized (utils/text-sanitize.js).
+ * @returns {string|null} absolute zip path, or null when no cache hit.
+ */
+function cachedZip({ version, platform = process.platform, arch = process.arch, env = process.env, fs = fsDefault } = {}) {
+  const zipName = `electron-v${version}-${platform}-${arch}.zip`;
+  for (const root of resolveCacheRoots(env)) {
+    let shaDirs;
+    try {
+      shaDirs = fs.readdirSync(root);
+    } catch {
+      continue;
+    }
+    for (const sha of shaDirs) {
+      const candidate = path.join(root, sha, zipName);
+      try {
+        if (fs.existsSync(candidate)) {
+          return candidate;
+        }
+      } catch {
+        /* ignore unreadable subdir */
+      }
+    }
+  }
+  return null;
+}
+
+module.exports = { resolveCacheRoots, defaultCacheRoot, cachedZip };

package/src/sidecar/electron-custody.js

@@ -0,0 +1,180 @@
+/**
+ * CUSTODY of the Electron artifact: one open, one read, one Buffer.
+ *
+ * THE PROPERTY THIS MODULE EXISTS TO MAKE TRUE, and the only one it claims:
+ *
+ *   **Amicus never itself writes, or reports as verified, bytes it did not hash.**
+ *
+ * Deliberately NOT "the user launches genuine Electron". A live attacker
+ * running as the same uid can overwrite `<electronDir>/dist/electron.exe`
+ * directly, at any moment, with no artifact involved at all — so no
+ * acquisition-time design can promise that, and claiming it would be the
+ * overclaim this whole change exists to stop.
+ *
+ * WHY A BUFFER, AND NOT A FILE DESCRIPTOR. Two council designs independently
+ * probed the fd remedy and both refuted it: a descriptor names an INODE, not a
+ * version of an inode. A same-uid `writeFileSync` at the path truncates and
+ * rewrites that same inode, and a positional read through our retained fd then
+ * returns the attacker's bytes (MEASURED twice, on Windows 11 / NTFS / Node
+ * 24.18: `"CLEANCLEANCLEAN"` before, `"POISONPOISONPOI"` after, through the
+ * SAME fd). A Buffer is different in kind: once the bytes are in this process's
+ * heap, no filesystem write can reach them. That is the whole design.
+ *
+ * WHY NOT A PRIVATE COPY EITHER — the remedy this replaces. v4.9.6 copied the
+ * artifact into a fresh 0700 `mkdtempSync` directory and asserted the attacker
+ * had "no name for it and no handle on it". MEASURED false on both halves: a
+ * spinner found the fixed `amicus-electron-stage-` prefix on its FIRST readdir
+ * of `os.tmpdir()`, opened the copy `r+` as the same user, and overwrote it;
+ * and on Windows `mkdtempSync` yields mode 666 while the module skipped its own
+ * `chmod(0o700)` on win32, so the 0700 was never even attempted. 0700 excludes
+ * OTHER users; the attacker in this threat model is THIS user.
+ *
+ * WHAT THE THREAT MODEL IS. An attacker who can write the Electron download
+ * cache directory, running as the same user as amicus. Out of scope, and stated
+ * rather than implied: that same user can also read and write amicus's process
+ * memory (`WriteProcessMemory`, or `process_vm_writev` under
+ * `yama.ptrace_scope=0`), rewrite amicus's own `node_modules`, or edit its
+ * config. Against THAT capability nothing here matters — an attacker in our
+ * address space can simply flip the gate's own verdict. This module closes the
+ * attacker whose capability is WRITING FILES, which is the one the digest gate
+ * makes sense against: a less-trusted cache root — a shared build box, a
+ * restored CI cache volume, a container bind-mount — read by a process whose
+ * own tree is trusted.
+ *
+ * NEAR-LEAF MODULE: `fs` + `path`, plus the pure house sanitizer
+ * `utils/text-sanitize`. Requires nothing in this cluster, so it can be
+ * required from either side of the electron-install -> electron-provision arrow.
+ *
+ * @module sidecar/electron-custody
+ */
+
+'use strict';
+
+const fsDefault = require('fs');
+const path = require('path');
+
+/** Positional-read chunk. 8 MiB keeps the loop at ~18 reads for a 138 MiB artifact. */
+const READ_CHUNK = 8 * 1024 * 1024;
+
+/**
+ * An electron artifact larger than this is not an electron artifact. The real
+ * win32 x64 artifact measured 138 MiB (144,265,219 bytes); darwin and linux are
+ * the same order. The cap is checked against `fstat`'s size BEFORE anything is
+ * allocated, so a 4 GiB sparse file planted in the cache costs one `fstat`.
+ */
+const MAX_ARTIFACT_BYTES = 1024 * 1024 * 1024;
+
+/**
+ * The ONLY shape allowed to become a path component:
+ * `electron-v<version>-<platform>-<arch>.zip`, with each field restricted to
+ * characters an electron version / platform / arch can actually contain.
+ *
+ * An ALLOW-list on purpose. A deny-list of `..` and separators is the shape
+ * that keeps losing — it has to anticipate every dialect (`..`, `%2e%2e`, a
+ * bare `\` that only win32's `path` treats as a separator), and it fails open
+ * on the one it did not think of. This fails closed on everything it was not
+ * written for.
+ *
+ * MOVED HERE from the deleted `electron-stage.js`, unchanged. It is still
+ * load-bearing: `version` is read out of `<electronDir>/package.json` whenever
+ * the caller supplies none, and `doctor --fix` — the one production caller —
+ * supplies none, for a directory it located by SCANNING npx caches. MEASURED
+ * before the check, end to end, with a planted `"version": "43.1.1/../../victim"`:
+ * a path two levels outside the intended directory was written and a
+ * pre-existing file there was destroyed.
+ */
+const ARTIFACT_NAME = /^electron-v[0-9A-Za-z][0-9A-Za-z.+-]*-[0-9A-Za-z_]+-[0-9A-Za-z_]+\.zip$/;
+
+/**
+ * True when `fileName` is a plain filename amicus itself could have produced.
+ *
+ * Both halves are checked deliberately. The pattern is the real control; the
+ * `path.basename` equality states the property in the platform's OWN dialect,
+ * so the claim "this is a filename, not a path" is asserted by the module that
+ * defines what a path is rather than only by a regex that has to imitate it.
+ * @param {*} fileName
+ * @returns {boolean}
+ */
+function isSafeArtifactName(fileName) {
+  return typeof fileName === 'string'
+    && fileName === path.basename(fileName)
+    && ARTIFACT_NAME.test(fileName);
+}
+
+/**
+ * Read `zip` into memory EXACTLY ONCE, through ONE descriptor.
+ *
+ * THE PATH IS RESOLVED ONCE AND NEVER AGAIN. `fstatSync(fd)` — never
+ * `statSync(zip)` — so even the size we act on comes from the handle we opened;
+ * a symlink is already resolved, and a swap after this point cannot change the
+ * answer. Every read is POSITIONAL (`readSync(fd, buf, off, len, POSITION)`),
+ * so the shared file offset is never used and nothing else in this process can
+ * perturb it.
+ *
+ * THERE IS NO "COULD NOT ALLOCATE" BRANCH, and that is deliberate. Two council
+ * designs promised one; both were MEASURED wrong. `Buffer.allocUnsafe` does not
+ * throw when the machine is out of memory — the process dies, exactly as it
+ * does today when extract-zip inflates a 215 MiB entry. Writing a clean
+ * `{why:'no-memory'}` refusal and claiming it works would be a failure branch
+ * this change never executed. What DOES protect the allocation is `maxBytes`,
+ * checked against `fstat` before a byte is reserved.
+ *
+ * A TORN READ NEEDS NO SPECIAL HANDLING. If the attacker mutates the file while
+ * we are reading it, the buffer we assembled is what would have been extracted,
+ * its sha256 will not match the anchor, and the gate refuses. `grew` and
+ * `short-read` exist to name the shape, not to provide the security.
+ *
+ * @param {object} o
+ * @param {string} o.zip        attacker-influenced path (a cache entry, or what
+ *                              `downloadArtifact` handed back)
+ * @param {number} [o.maxBytes] default MAX_ARTIFACT_BYTES
+ * @param {object} [o.fs]
+ * @returns {{bytes: Buffer, size: number}
+ *         | {bytes: null, why: 'unreadable'|'not-a-file'|'empty'|'too-large'|'short-read'|'grew',
+ *            detail: string}}
+ */
+function readArtifactBytes({ zip, maxBytes = MAX_ARTIFACT_BYTES, fs = fsDefault }) {
+  let fd;
+  try {
+    fd = fs.openSync(zip, 'r');
+  } catch (e) {
+    return { bytes: null, why: 'unreadable', detail: (e && e.message) || String(e) };
+  }
+  try {
+    const st = fs.fstatSync(fd);
+    if (!st.isFile()) {
+      return { bytes: null, why: 'not-a-file', detail: 'it is not a regular file' };
+    }
+    if (st.size === 0) {
+      return { bytes: null, why: 'empty', detail: 'it is empty' };
+    }
+    if (st.size > maxBytes) {
+      return { bytes: null, why: 'too-large', detail: `${st.size} bytes exceeds the ${maxBytes}-byte ceiling` };
+    }
+    const bytes = Buffer.allocUnsafe(st.size);
+    let off = 0;
+    while (off < st.size) {
+      const n = fs.readSync(fd, bytes, off, Math.min(READ_CHUNK, st.size - off), off);
+      if (!(n > 0)) {
+        return { bytes: null, why: 'short-read', detail: `the file ended after ${off} of ${st.size} bytes` };
+      }
+      off += n;
+    }
+    // One positional read PAST the size we trusted. A file that grew under us is
+    // what an active swap looks like, and it means the bytes we hold are a prefix
+    // of something else — say that, rather than hashing a truncation.
+    const tail = Buffer.allocUnsafe(1);
+    if (fs.readSync(fd, tail, 0, 1, st.size) > 0) {
+      return { bytes: null, why: 'grew', detail: 'it changed size while amicus was reading it' };
+    }
+    return { bytes, size: st.size };
+  } catch (e) {
+    return { bytes: null, why: 'unreadable', detail: (e && e.message) || String(e) };
+  } finally {
+    try { fs.closeSync(fd); } catch { /* already closed */ }
+  }
+}
+
+module.exports = {
+  readArtifactBytes, isSafeArtifactName, MAX_ARTIFACT_BYTES, READ_CHUNK,
+};

package/src/sidecar/electron-ensure.js

@@ -45,7 +45,7 @@ function _resetEnsureElectron() {
  * @param {object} [opts.deps] injected
  *   { isElectronUsable, resolveElectronBinary, repairElectron, logProgress }.
  * @param {object} [opts.repairOptions] forwarded to repairElectron (electronDir, etc.).
- * @returns {Promise<{ok:boolean, path?:string, reason?:string}>}
+ * @returns {Promise<{ok:boolean, path?:string, reason?:string, unverified?:boolean}>}
  */
 function ensureElectron({ deps = {}, repairOptions = {} } = {}) {
   const usable = deps.isElectronUsable || defaultIsUsable;
@@ -71,11 +71,32 @@ function ensureElectron({ deps = {}, repairOptions = {} } = {}) {
       return { ok: false, reason: `Electron provisioning failed: ${err && err.message}` };
     }
     if (usable()) {
+      // A2/B3 (council, confirmed 4 of 4): `unverified` was WRITTEN on both
+      // provision routes and read by nothing in src/ or scripts/, while the docs
+      // said the outcome was "marked unverified". A flag no code and no human
+      // ever sees establishes no property at all. This is the launch-time
+      // reader; scripts/postinstall.js is the install-time one and
+      // doctor-electron-mcp-check.js reports it from `--fix`.
+      if (result && result.unverified) {
+        logProgress('[amicus] NOTE: this Electron binary is UNVERIFIED — either no published sha256 covered');
+        logProgress('[amicus]   the artifact it came from, so its bytes were vouched for only by the');
+        logProgress('[amicus]   mirror that served them, or its sha256 CONTRADICTED the published one and');
+        logProgress('[amicus]   AMICUS_ALLOW_UNVERIFIED_ELECTRON accepted it anyway.');
+      }
       logProgress('[amicus] Electron GUI ready.');
-      return { ok: true, path: resolve() };
+      return { ok: true, path: resolve(), ...(result && result.unverified ? { unverified: true } : {}) };
     }
-    const reason = (result && result.reason)
-      || `Electron could not be provisioned; the GUI is unavailable. ${HINTS.doctorFix} (or use --no-ui).`;
+    // THE POINTER IS NOT OPTIONAL. This used to be `result.reason || <the
+    // pointer>`, so the moment `repairElectron` started returning a reason for a
+    // failed controlled download (v4.9.6, when the last-resort installer was
+    // deleted and the failure became something to REPORT), the one line telling
+    // the user what to do next silently disappeared. A more detailed message is
+    // not a reason to stop giving advice.
+    const detail = (result && result.reason) || 'Electron could not be provisioned; the GUI is unavailable.';
+    // Matched on the COMMAND, not on the whole hint string: the AV-quarantine
+    // reason already ends with a bare `amicus doctor --fix` and must not be
+    // given a second, longer copy of the same advice.
+    const reason = detail.includes('doctor --fix') ? detail : `${detail} ${HINTS.doctorFix} (or use --no-ui).`;
     return { ok: false, reason };
   })().then((r) => {
     // Only memoize SUCCESS; a failure clears the guard so a later launch retries.

package/src/sidecar/electron-env-scrub.js

@@ -0,0 +1,233 @@
+/**
+ * The ENV SCRUB — which environment names a hostile REPOSITORY can plant.
+ *
+ * WHAT THIS MODULE LOST, AND WHY (v4.9.6 second round, council seat B1).
+ * It used to build a scrubbed environment for the last-resort `install.js`
+ * SPAWN. That spawn is gone — it bypassed the custody and digest gate entirely
+ * — so `scrubbedChildEnv` and the `ELECTRON_INSTALL_TARGET_*` artifact selectors
+ * went with it: there is no child process left to hand an environment to. The
+ * measured enumeration they encoded is kept below as the record it is.
+ * `isRepoPlantedName` survives and is now used by the IN-PROCESS download scrub
+ * (electron-provision.js), which is the surface seat D5 filed against.
+ *
+ * SPLIT OUT of electron-trust.js (v4.9.6 F2). That module owns three things —
+ * the digest anchor, the gate, and this scrub — and sat at 299 of the repo's
+ * 300-line limit, so the F2 repair had nowhere to go. electron-trust.js
+ * RE-EXPORTS every name below, so existing imports keep working and the split is
+ * invisible to callers. This module is a LEAF (no requires at all); the arrow is
+ * electron-install -> electron-provision -> electron-trust -> electron-env-scrub
+ * and must never point back.
+ *
+ * The trust boundary it encodes: 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 run `npx -y amicus@latest` in. MEASURED (npm
+ * 11.16.0): that reaches the child as exactly two name shapes —
+ * `npm_config_<key lowercased>` and `npm_package_config_<key case-preserved>` —
+ * and NOTHING else. Bare `ELECTRON_*` and `AMICUS_*` names are out of its reach,
+ * which is why the escape hatch is a plain environment variable and why a
+ * machine-level `ELECTRON_MIRROR` is still honoured.
+ *
+ * @module sidecar/electron-env-scrub
+ */
+
+'use strict';
+
+/**
+ * Env-name PREFIXES an untrusted REPOSITORY can plant for the mirror knobs.
+ *
+ * PREFIXES, not a hand-maintained name list. RE-ENUMERATED EXHAUSTIVELY for
+ * v4.9.6 F2 against `@electron/get` 5.0.0 (`dist/artifact-utils.js`, lines 20-35):
+ * `mirrorVar(name)` is called for exactly five names — `mirror`, `nightlyMirror`,
+ * `customDir`, `customFilename`, `customVersion` — and reads six spellings of
+ * each, thirty names in all:
+ *   1. `npm_config_electron_<name.toLowerCase()>`          .npmrc
+ *   2. `NPM_CONFIG_ELECTRON_<SNAKE_UPPER>`                 .npmrc, npm's own casing
+ *   3. `npm_config_electron_<snake_lower>`                 .npmrc
+ *   4. `npm_package_config_electron_<name>` (case KEPT)    package.json "config"
+ *   5. `npm_package_config_electron_<snake_lower>`         package.json "config"
+ *   6. `ELECTRON_<SNAKE_UPPER>`                            plain env
+ * Rows 1-5 — twenty-five names — all begin with one of the two prefixes below
+ * under a case fold, so the prefixes cover every repo-reachable mirror knob
+ * exactly. Row 6 (`ELECTRON_MIRROR`, `ELECTRON_NIGHTLY_MIRROR`,
+ * `ELECTRON_CUSTOM_DIR`, `ELECTRON_CUSTOM_FILENAME`, `ELECTRON_CUSTOM_VERSION`)
+ * is BARE and therefore the machine owner's, and is deliberately kept.
+ *
+ * The prefixes also cover electron's own
+ * `npm_config_electron_use_remote_checksums` (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` (row 5 above) 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_'];
+
+/**
+ * THE ARTIFACT SELECTORS ARE GONE WITH THE SPAWN, and this is the record of what
+ * they were, because it was measured and a later change may need it.
+ *
+ * `ELECTRON_INSTALL_TARGET_ENV` held `npm_config_platform` / `npm_config_arch`
+ * and their `npm_package_config_*` spellings (council B2 added the second pair).
+ * They mattered because they chose WHICH artifact `install.js` fetched. Nothing
+ * spawns install.js any more (seat B1), and amicus's own downloader is passed
+ * `platform` and `arch` as ARGUMENTS, so no environment name can choose them.
+ *
+ * RE-ENUMERATED EXHAUSTIVELY, before the deletion, against the installed
+ * `node_modules/electron` (43.1.1) `install.js`. Every `process.env` read there:
+ *   ELECTRON_INSTALL_PLATFORM (20, 99)  bare — amicus used to SET it
+ *   npm_config_platform       (20, 99)  REPO-PLANTABLE
+ *   ELECTRON_INSTALL_ARCH     (21)      bare — amicus used to SET it
+ *   npm_config_arch           (21, 27)  REPO-PLANTABLE
+ *   force_no_cache            (45)      bare
+ *   electron_config_cache     (46)      bare — the machine owner's cache root
+ *   electron_use_remote_checksums            (48)  bare — the owner's
+ *   npm_config_electron_use_remote_checksums (48)  covered by the prefixes above
+ *   ELECTRON_OVERRIDE_DIST_PATH (73, 80) bare
+ * install.js 43.1.1 did NOT itself read `npm_package_config_platform` / `-arch`.
+ *
+ * WHAT THE IN-PROCESS SCRUB NEEDS is only the prefixes: `@electron/get` 5.0.0
+ * reads `mirror`, `nightlyMirror`, `customDir`, `customFilename` and
+ * `customVersion` under `npm_config_electron_*` / `npm_package_config_electron_*`
+ * (dist/artifact-utils.js, lines 20-35) and takes platform and arch as call
+ * arguments. So `isRepoPlantedName` covers the download surface exactly.
+ */
+
+/** True for a name a hostile repository could have planted, in ANY case (see above). */
+function isRepoPlantedName(name) {
+  return REPO_ENV_PREFIXES.some((prefix) => String(name).toLowerCase().startsWith(prefix));
+}
+
+/**
+ * Run `fn` with every repo-plantable electron name DELETED from `env`, restoring
+ * each one before returning — whether `fn` returned a value, returned a promise,
+ * or threw (council seat D5).
+ *
+ * THE HOLE THIS CLOSES. The v4.9.6 mirror-knob scrub covered only the
+ * last-resort `install.js` SPAWN, and amicus's own controlled download runs
+ * `@electron/get` IN THIS PROCESS, reading `process.env` directly. So a hostile
+ * repository could still point amicus's own download at its mirror. It was filed
+ * as a nit because the digest pin refuses the redirected bytes anyway — this is
+ * a wasted download, not a compromise — but a stated threat model that is wider
+ * than the code is its own defect.
+ *
+ * ── WHAT IT COVERS, MEASURED RATHER THAN REASONED (round 3, seat B1) ───────
+ * The previous version of this docblock ARGUED, from a source read, that every
+ * repo-plantable name is read in `downloadArtifact`'s synchronous prefix. Seat
+ * B1 called that "an unverified invariant about @electron/get internals" and
+ * was right to: the argument had never been run, and the scrub pattern was
+ * copied from `utils/engine-output-flag.js :: withOutputTokenFlag`, where it is
+ * correct only because the thing it guards reads the env synchronously at spawn.
+ *
+ * So it was MEASURED, against the INSTALLED @electron/get 5.0.0 (Node 24.18.0,
+ * Windows 11), by replacing `process.env` with a recording Proxy and driving a
+ * real `downloadArtifact` with an injected offline downloader:
+ *
+ *   PINNED call (amicus's normal route — a `checksums` table goes out)
+ *     20 repo-plantable reads, ALL INSIDE the scrub window; 0 after the restore.
+ *     Four knobs on a stable version (`customVersion` from `getArtifactVersion`,
+ *     then `mirror`, `customDir`, `customFilename` from `getArtifactRemoteURL`)
+ *     x five repo-reachable spellings; `nightlyMirror` adds five on a nightly.
+ *     POSITIVE CONTROL, `npm_config_electron_mirror=https://ATTACKER.example/mirror/`:
+ *       scrubbed   -> https://github.com/electron/electron/releases/download/v43.1.1/…
+ *       unscrubbed -> https://ATTACKER.example/mirror/ATTACKERDIR/ATTACKER.zip
+ *     The scrub is therefore NOT a no-op: it is what puts that download back on
+ *     the official URL.
+ *
+ *   UNPINNED call (no anchor, or the hatch dropped the pin — no `checksums`)
+ *     The same 20 land inside the window and the ARTIFACT still comes from the
+ *     official URL. Then `validateArtifact` recursively `downloadArtifact`s
+ *     `SHASUMS256.txt` AFTER awaits, with the environment restored, and reads
+ *     the planted names back — 13, not 20, because `mirrorVar`'s `||` chain
+ *     short-circuits as soon as a planted name answers.
+ *
+ * THE RESIDUAL IS AVAILABILITY-ONLY, and that is why it is documented rather
+ * than closed. The zip's URL was already fixed inside the scrub, so a planted
+ * mirror cannot substitute the bytes — it can only serve a checksum file that
+ * disagrees with the official artifact, which FAILS the download.
+ *
+ * IT IS STATED IN BOTH PLACES A USER READS IT, which took two rounds. Round 3
+ * narrowed `docs/configuration.md` and left the SAME overclaim standing at
+ * `docs/troubleshooting.md`, on the very bullet that tells a user to set
+ * `AMICUS_ALLOW_UNVERIFIED_ELECTRON=1` — i.e. on the page a user in exactly the
+ * UNPINNED configuration is sent to. Round 4 corrected it there too. When a
+ * claim about this module is narrowed, grep the docs for the phrasing rather
+ * than the file that suggested it.
+ *
+ * ── NOTHING OUTSIDE CAN OBSERVE IT (seat B3, REFUTED BY MEASUREMENT) ───────
+ * B3 read this as mutating shared `process.env` "while the download is still in
+ * flight", so "concurrent repairs can interleave". They cannot: delete -> call
+ * -> restore contains no `await`, so it is ONE synchronous turn and no other
+ * task can be scheduled inside it. MEASURED: two concurrent scrubbed downloads
+ * with an outside observer sampling `process.env` from the microtask, immediate
+ * and timer queues — 11380 samples, 0 saw a scrubbed environment, and both
+ * resolved to the official URL. The await-free window IS the control, which is
+ * why `fn` is called synchronously and its promise is returned UNAWAITED.
+ * `tests/electron-env-scrub-get5-contract.test.js` re-measures every number
+ * above against the installed library on each run, so a @electron/get that moves
+ * a read past an await turns red there instead of in the field.
+ *
+ * ── THREE REMEDIES CONSIDERED AND REJECTED, each with its reason ───────────
+ * 1. Pass the values instead of scrubbing. IMPOSSIBLE: `mirrorVar` ranks
+ *    `process.env` ABOVE `options[name]` (dist/artifact-utils.js, lines 20-35),
+ *    so a planted name beats anything amicus puts in `mirrorOptions`.
+ * 2. `mirrorOptions.resolveAssetURL`, which does override the URL outright and
+ *    IS inherited by the recursive SHASUMS256 call. Rejected: it bypasses
+ *    `base` entirely, so a machine owner's bare `ELECTRON_MIRROR` — which this
+ *    module deliberately keeps — would silently stop being honoured, and amicus
+ *    would have to hand-build electron release URLs.
+ * 3. Hold the scrub for the whole call. Rejected by the finding itself: that is
+ *    the shared-mutation-across-an-await B3 filed, and it would hand a scrubbed
+ *    environment to every unrelated child a long-lived MCP process spawns in
+ *    that window.
+ *
+ * `delete` and restore, not `= undefined`: assigning undefined to a process.env
+ * key stores the STRING 'undefined', which `mirrorVar` would read as a truthy
+ * mirror URL and use.
+ * @template T
+ * @param {() => T} fn called synchronously, exactly once
+ * @param {NodeJS.ProcessEnv} [env] defaults to process.env
+ * @returns {T} whatever fn returned (a promise is returned, never awaited here)
+ */
+function withScrubbedRepoEnv(fn, env = process.env) {
+  const removed = [];
+  for (const name of Object.keys(env)) {
+    if (isRepoPlantedName(name)) {
+      removed.push([name, env[name]]);
+      delete env[name];
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    for (const [name, value] of removed) { env[name] = value; }
+  }
+}
+
+module.exports = { isRepoPlantedName, withScrubbedRepoEnv, REPO_ENV_PREFIXES };