amicus 4.9.4 → 4.9.6

package/src/sidecar/zip-from-buffer.js

@@ -0,0 +1,220 @@
+/**
+ * Extract an archive that is ALREADY IN MEMORY and ALREADY HASHED.
+ *
+ * There is no `zip` parameter because there is no file. The bytes arrive as a
+ * Buffer that `electron-custody.readArtifactBytes` read through a single
+ * descriptor and that `electron-trust.verifyArtifactBytes` hashed; nothing here
+ * resolves a path to the artifact, so there is no second read for a same-uid
+ * attacker to race. `electron-custody.js` carries the measured refutations of
+ * the two remedies this replaces. NO HAND-WRITTEN ZIP PARSING: a council judge
+ * killed a design that sliced local file headers by hand — "a terminal path with
+ * no rescue", since it would have had to re-derive ZIP64 local headers, data
+ * descriptors and the central-vs-local size disagreement `openReadStream`
+ * already handles. Every byte offset comes from `yauzl.openReadStream`, exactly
+ * as under extract-zip; only WHERE yauzl reads from changes.
+ *
+ * ── THE `autoClose` TRAP, MEASURED ────────────────────────────────────────
+ * `yauzl.fromBuffer` sets `options.autoClose = false` UNCONDITIONALLY
+ * (yauzl@2.10.0 index.js, line 67) — an explicit `{autoClose: true}` is silently
+ * discarded — and `extract-zip` resolves on the zipfile's `'close'` event
+ * (extract-zip@2.0.1 index.js, lines 32-37), so a naive port of extract-zip onto
+ * a buffer HANGS FOREVER. Both council judges hit it. MEASURED on the installed
+ * libraries (Windows 11, Node 24.18.0) it is worse than the brief recorded:
+ * `ZipFile.close()` only calls `reader.unref()`, and fd-slicer's BufferSlicer
+ * has no close and emits nothing on unref (fd-slicer index.js, lines 282-288)
+ * where FdSlicer closes the fd and emits `'close'` — so under `fromBuffer` that
+ * event is UNREACHABLE even if you call `close()` (500 ms after END fired, close
+ * had not). THE FIX, stated so nobody "tidies" it: this module resolves on
+ * `'end'`, which yauzl emits once the central directory is exhausted, and drives
+ * `readEntry()` only after the previous entry has been fully written, so `'end'`
+ * cannot arrive before the last write lands. `close()` is still called, for the
+ * reader refcount, but NOTHING waits on it. Pinned by YAUZLHANG.
+ *
+ * ── PARITY WITH extract-zip, AND THE ONE DELIBERATE DIFFERENCE ────────────
+ * The per-entry decisions all live in `./zip-entry-write :: placeEntry` now, and
+ * the `__MACOSX/` skip, the mode decode, both directory failsafes, the 0755/0644
+ * defaults and the per-entry `realpath(destDir)` out-of-bound check with its
+ * message VERBATIM are copied from extract-zip@2.0.1 index.js, lines 48-160, so
+ * `UNSAFE_PATTERNS` and `electron-refuse.isUnsafeArchive` classify exactly what
+ * they classified. The difference: a SYMLINK whose target resolves outside the
+ * extraction root is REFUSED here and is not by extract-zip, and it is resolved
+ * against the REALPATH of the directory the link lands in because the lexical
+ * `path.dirname` was measured to be defeated outright by a chain of
+ * directory-symlink entries earlier in the same archive. That is a behaviour
+ * change on a shape amicus cannot test on this machine (the darwin `.app` bundle
+ * is the only electron artifact with real symlinks), so it is refused in the
+ * same `Out of bound path` wording, exercised against synthetic archives, and
+ * named in the report as unverified on macOS.
+ *
+ * ── ERROR CODES ARE A CAUSAL CLAIM ───────────────────────────────────────
+ * `UNZIP_BUFFER_FAILED` = the ARCHIVE is bad. `UNZIP_DEST_FAILED` = the
+ * DESTINATION is (no space, a read-only dist, a path too long).
+ * `UNZIP_BUFFER_UNAVAILABLE` = neither, yauzl would not load.
+ * `UNZIP_BUFFER_STALLED` = no progress inside the bound; nobody learned anything
+ * about the archive OR the disk. The caller evicts on `UNZIP_BUFFER_FAILED`
+ * ONLY (finding D2). The constructors and the writers live in `./zip-entry-write`;
+ * `UNZIP_BUFFER_STALLED` and the windows that raise it live in `./zip-stall-bound`.
+ *
+ * @module sidecar/zip-from-buffer
+ */
+
+'use strict';
+
+const fsDefault = require('fs');
+const path = require('path');
+
+// The classified failures, and `placeEntry` — everything that decides what ONE
+// entry becomes on disk. THE ONE-WAY ARROW: zip-from-buffer -> zip-entry-write,
+// never back. `placeEntry` moved across that seam in the third council round,
+// when this file hit the 300-line gate again: it answers "what does one entry
+// become on disk", which is the neighbouring module's whole subject, while what
+// stays here is "how is the archive DRIVEN, and when do we give up on it".
+const {
+  failure, badArchive, badDestination, extractorUnavailable, placeEntry,
+} = require('./zip-entry-write');
+// THE GIVE-UP POLICY, and the whole record of how it has been wrong: the two
+// windows, the bounded wait for an aborted write to come apart, and the
+// classified failure. Read `./zip-stall-bound` before touching any of it.
+const {
+  IDLE_MS, MAX_MS, UNWIND_MS, stalled, awaitUnwind,
+} = require('./zip-stall-bound');
+
+/** yauzl's own validateFileName refusals — three of unzip.js's UNSAFE_PATTERNS. */
+const NAME_REFUSAL = /^(absolute path|invalid relative path|invalid characters in fileName): /;
+
+/** yauzl's callback API as a promise, with `fromBuffer`'s options pinned here. */
+function openBuffer(yauzl, bytes) {
+  return new Promise((resolve, reject) => {
+    yauzl.fromBuffer(bytes, { lazyEntries: true, validateEntrySizes: true }, (err, zipfile) => {
+      if (err) { reject(badArchive(`could not read the archive: ${(err && err.message) || err}`)); return; }
+      resolve(zipfile);
+    });
+  });
+}
+
+/**
+ * Extract `bytes` into `dir`. The caller has ALREADY hashed `bytes`.
+ *
+ * BOUNDED, AND EVERY WAIT IN IT IS BOUNDED. See `./zip-stall-bound`, which
+ * carries the whole record: an idle watchdog armed against BYTES WRITTEN (not entries completed),
+ * a hard cap, and a bounded wait for the aborted write to unwind — each one a
+ * live `setTimeout` handle, so a write that never completes becomes a catchable
+ * rejection instead of a promise that never settles, and SOME handle is alive
+ * for the whole of it, which is what stops Node exiting 0 mid-stall with a
+ * partial extract and no message. When a bound fires it ABORTS the in-flight
+ * write first, so no byte lands after the failure is decided; it then waits up
+ * to `unwindMs` for that write to come apart, and throws whether or not it did.
+ *
+ * @param {Buffer} bytes  the whole archive, in this process's heap
+ * @param {object} o
+ * @param {string} o.dir  absolute destination (created if absent)
+ * @param {number} [o.idleMs] no-progress window before the extract is stalled
+ * @param {number} [o.maxMs]  hard cap on the whole extraction
+ * @param {number} [o.unwindMs] how long an aborted write may take to come apart
+ * @param {object} [o.deps] { fs, yauzl, log, setTimeout, clearTimeout }
+ * @returns {Promise<{strategy:'buffer', entries:number}>}
+ * @throws {Error} code 'UNZIP_UNSAFE_ARCHIVE' — terminal; never retried
+ * @throws {Error} code 'UNZIP_BUFFER_FAILED'  — the archive is bad
+ * @throws {Error} code 'UNZIP_DEST_FAILED'    — the destination is bad
+ * @throws {Error} code 'UNZIP_BUFFER_UNAVAILABLE' — yauzl could not be loaded
+ * @throws {Error} code 'UNZIP_BUFFER_STALLED' — no progress; NOT an artifact verdict
+ */
+async function extractZipBuffer(bytes, {
+  dir, idleMs = IDLE_MS, maxMs = MAX_MS, unwindMs = UNWIND_MS, deps = {},
+} = {}) {
+  const fs = deps.fs || fsDefault;
+  const setTimer = deps.setTimeout || setTimeout;
+  const clearTimer = deps.clearTimeout || clearTimeout;
+  // GUARDED (the v4.5.2 lesson). `yauzl` IS declared in package.json; the guard
+  // keeps a broken install a refusal rather than a deleted cache entry.
+  let yauzl = deps.yauzl;
+  if (!yauzl) {
+    try { yauzl = require('yauzl'); } catch (e) { throw extractorUnavailable((e && e.message) || String(e)); }
+  }
+  if (!path.isAbsolute(dir)) { throw badDestination('Target directory is expected to be absolute'); }
+  let root;
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    root = fs.realpathSync(dir);
+  } catch (e) {
+    throw badDestination(`could not prepare ${dir}: ${(e && e.message) || e}`);
+  }
+
+  const zipfile = await openBuffer(yauzl, bytes);
+  let entries = 0;
+  let written = 0;                  // BYTES the destination accepted — the progress signal
+  let idleTimer = null;
+  let maxTimer = null;
+  let inFlight = null;              // the entry being written when the bound fires
+  const halt = new AbortController();
+  const cancelTimers = () => {
+    if (idleTimer !== null) { clearTimer(idleTimer); idleTimer = null; }
+    if (maxTimer !== null) { clearTimer(maxTimer); maxTimer = null; }
+  };
+  let thrown = null;
+  try {
+    await new Promise((resolve, reject) => {
+      let settled = false;
+      const finish = (fn, value) => {
+        if (settled) { return; }
+        settled = true;
+        cancelTimers();
+        fn(value);
+      };
+      // STOP THE WORK FIRST, THEN REPORT IT. A control that reports a failure
+      // while the work continues is not a control (round 3, seat A1): the abort
+      // destroys the in-flight pipeline, and `placeEntry`/`writeSymlink` refuse
+      // to start or finish anything once the signal is set.
+      const fail = (e) => {
+        if (!halt.signal.aborted) { halt.abort(e); }
+        finish(reject, e);
+      };
+      // The idle WATCHDOG re-arms itself from the marks it took, so a single
+      // huge entry that is writing steadily is progress and never a stall.
+      const armIdle = () => {
+        const atBytes = written;
+        const atEntries = entries;
+        idleTimer = setTimer(() => {
+          if (written !== atBytes || entries !== atEntries) { armIdle(); return; }
+          fail(stalled(`no extract progress for ${idleMs}ms`));
+        }, idleMs);
+      };
+      maxTimer = setTimer(() => fail(stalled(`extraction exceeded ${maxMs}ms`)), maxMs);
+      armIdle();
+      // yauzl's own validateFileName refusals ('absolute path: ', 'invalid
+      // relative path: ', 'invalid characters in fileName: ') arrive here.
+      zipfile.on('error', (e) => fail(failure(
+        NAME_REFUSAL.test((e && e.message) || '') ? 'UNZIP_UNSAFE_ARCHIVE' : 'UNZIP_BUFFER_FAILED',
+        (e && e.message) || 'the archive could not be read',
+      )));
+      // RESOLVE ON 'end', NEVER ON 'close' — see the docblock. `close` is
+      // unreachable under fromBuffer, so waiting for it hangs forever.
+      zipfile.on('end', () => finish(resolve));
+      zipfile.on('entry', (entry) => {
+        inFlight = placeEntry({
+          zipfile, entry, root, fs, signal: halt.signal, onBytes: (n) => { written += n; },
+        });
+        inFlight.then((placed) => {
+          if (settled) { return; }        // the bound already fired; stop driving
+          if (placed) { entries += 1; }
+          zipfile.readEntry();
+        }, fail);
+      });
+      zipfile.readEntry();
+    });
+  } catch (e) {
+    thrown = e;
+  } finally {
+    cancelTimers();
+    // The abort has been issued; give the destroyed pipeline a BOUNDED window to
+    // unwind, so the caller's cleanup (extractBytesToDist deletes the incoming
+    // tree in its own `finally`) does not usually race an open descriptor — and
+    // so a pipeline that can never unwind cannot hang this call. Round 4.
+    if (inFlight) { await awaitUnwind(inFlight, unwindMs, setTimer, clearTimer); }
+    try { zipfile.close(); } catch { /* the buffer reader holds no fd */ }
+  }
+  if (thrown) { throw thrown; }
+  return { strategy: 'buffer', entries };
+}
+
+module.exports = { extractZipBuffer };

package/src/sidecar/zip-name-scan.js

@@ -0,0 +1,141 @@
+/**
+ * WHAT NAMES DOES THIS ARCHIVE DECLARE? A read-only walk of the central
+ * directory, for the one caller that is about to hand an archive to a tool with
+ * no path-traversal check of its own.
+ *
+ * ── THE HOLE THIS CLOSES, MEASURED ────────────────────────────────────────
+ * `electron-native-rescue.js` refuses to rescue a `UNZIP_UNSAFE_ARCHIVE`, and
+ * that refusal is exactly right — but it keys on the REFUSAL yauzl happened to
+ * form, not on the hostile ENTRY. yauzl validates an entry's NAME in
+ * `_readEntry`, AFTER its size check (yauzl@2.10.0 index.js lines 407-426), so
+ * one bad entry earlier in the same archive ends the walk before any later name
+ * is ever looked at. MEASURED on the installed yauzl (Windows 11, Node 24), real
+ * `extractZipBuffer`, one archive per line:
+ *
+ *   [`../../../PWNED.txt`]                        -> UNZIP_UNSAFE_ARCHIVE
+ *                                                    ("invalid relative path: …")
+ *   [`first.bin` w/ the encrypted flag set,
+ *    `../../../PWNED.txt`, `electron.exe`]        -> UNZIP_BUFFER_FAILED
+ *                                                    ("compressed/uncompressed size
+ *                                                     mismatch for stored file: 4 != 4")
+ *
+ * The second archive is one flag bit different from the first and lands in the
+ * ONE class the rescue acts on, so the whole thing — traversal entry included —
+ * was handed to `tar` / `Expand-Archive`. What stopped the escape in that run was
+ * each tool's own check (`tar.exe`: `../../../PWNED.txt: Path contains '..'`,
+ * exit 1; `Expand-Archive`: `Can not process invalid archive entry '…'`, exit 0,
+ * nothing outside the destination in either case) — precisely the reliance
+ * `unzip.js` says amicus will not make: "a tool with no such check".
+ *
+ * ── WHAT THIS CAN AND CANNOT SEE, STATED BEFORE THE CODE ──────────────────
+ * The scan reads the CENTRAL DIRECTORY with size validation and string decoding
+ * both OFF, so the entry that breaks the extraction does not stop the walk.
+ * MEASURED on the archive above: all three names come back, the traversal entry
+ * included. It sees NOTHING when the central directory itself is unreadable —
+ * a truncated zip answers `end of central directory record signature not found`
+ * and yields no names at all — which is why the result carries `read` and the
+ * caller states that residual out loud rather than pretending to a guarantee.
+ * It also cannot see a SYMLINK whose TARGET escapes the root: that is bytes, not
+ * a name, and `zip-from-buffer.js` refuses it only because it reads the payload.
+ *
+ * ── AND IT IS ONLY EVER A NARROWING ───────────────────────────────────────
+ * Nothing here can make a rescue happen. A refusal it forms turns a
+ * `UNZIP_BUFFER_FAILED` into the TERMINAL `UNZIP_UNSAFE_ARCHIVE` its caller
+ * already excludes; silence changes nothing. So a bug in this file can cost the
+ * rescue, never widen it.
+ *
+ * @module sidecar/zip-name-scan
+ */
+
+'use strict';
+
+/** Hard bound: this is an in-memory walk, but nothing waits forever here. */
+const SCAN_MS = 10_000;
+
+/** No real electron artifact is near this; a hostile central directory can be. */
+const MAX_ENTRIES = 200_000;
+
+/**
+ * yauzl's own `validateFileName` (index.js lines 607-619), under the options
+ * amicus really extracts with — `decodeStrings` on and `strictFileNames` off,
+ * which rewrites backslashes to `/` BEFORE validating (lines 420-426). The
+ * wording is yauzl's verbatim so a refusal built from it is classified by
+ * `unzip.js :: UNSAFE_PATTERNS` as well as by its `code`.
+ *
+ * `invalid characters in fileName` is deliberately absent: with the backslash
+ * rewrite in force yauzl cannot produce it, and inventing a refusal yauzl would
+ * not make is how a scan starts costing the rescue legitimate archives.
+ * @returns {string|null} yauzl's refusal for this name, or null
+ */
+function nameRefusal(name) {
+  const n = name.replace(/\\/g, '/');
+  if (/^[a-zA-Z]:/.test(n) || n.startsWith('/')) { return `absolute path: ${name}`; }
+  if (n.split('/').includes('..')) { return `invalid relative path: ${name}`; }
+  return null;
+}
+
+/**
+ * Walk `bytes`' central directory and report the first entry name yauzl would
+ * refuse.
+ *
+ * DECODED AS LATIN-1, ON PURPOSE. `decodeStrings: false` hands back raw name
+ * Buffers, and latin-1 is the one decoding that maps bytes to characters 1:1 —
+ * no replacement characters, no multi-byte collapsing. Every byte the two rules
+ * look at (`.`, `/`, `\`, `:`) is ASCII, and no continuation byte of a UTF-8
+ * sequence can be ASCII, so this sees exactly what a correct decode would.
+ *
+ * NEVER THROWS, never rejects: a caller reaching this already has a failure in
+ * flight and must not acquire a second one from a diagnostic.
+ *
+ * @param {Buffer} bytes the archive, in this process's heap
+ * @param {object} [o]
+ * @param {object} [o.deps] { yauzl, setTimeout, clearTimeout }
+ * @returns {Promise<{read:boolean, refusal:string|null, why:string}>}
+ *   `read` = the whole central directory was enumerated, so `refusal: null`
+ *   really means "no such name in this archive". `read:false` means the scan
+ *   proved nothing.
+ */
+function scanEntryNames(bytes, { deps = {} } = {}) {
+  const setTimer = deps.setTimeout || setTimeout;
+  const clearTimer = deps.clearTimeout || clearTimeout;
+  let yauzl = deps.yauzl;
+  if (!yauzl) {
+    try {
+      // eslint-disable-next-line global-require
+      yauzl = require('yauzl');
+    } catch (e) { return Promise.resolve({ read: false, refusal: null, why: `yauzl unavailable: ${(e && e.message) || e}` }); }
+  }
+  return new Promise((resolve) => {
+    let settled = false;
+    let refusal = null;
+    let seen = 0;
+    let timer = null;
+    const done = (read, why) => {
+      if (settled) { return; }
+      settled = true;
+      if (timer !== null) { clearTimer(timer); }
+      resolve({ read, refusal, why });
+    };
+    timer = setTimer(() => done(false, `the name scan exceeded ${SCAN_MS}ms`), SCAN_MS);
+    try {
+      yauzl.fromBuffer(bytes, { lazyEntries: true, decodeStrings: false, validateEntrySizes: false }, (err, zipfile) => {
+        if (err || !zipfile) { done(false, `could not read the central directory: ${(err && err.message) || 'no zipfile'}`); return; }
+        zipfile.on('error', (e) => done(false, `could not read the central directory: ${(e && e.message) || e}`));
+        zipfile.on('end', () => done(true, ''));
+        zipfile.on('entry', (entry) => {
+          seen += 1;
+          const name = Buffer.isBuffer(entry.fileName) ? entry.fileName.toString('latin1') : String(entry.fileName);
+          refusal = nameRefusal(name);
+          if (refusal) { done(true, ''); return; }
+          if (seen >= MAX_ENTRIES) { done(false, `stopped after ${MAX_ENTRIES} entries`); return; }
+          zipfile.readEntry();
+        });
+        zipfile.readEntry();
+      });
+    } catch (e) {
+      done(false, `could not read the central directory: ${(e && e.message) || e}`);
+    }
+  });
+}
+
+module.exports = { scanEntryNames, nameRefusal, SCAN_MS, MAX_ENTRIES };

package/src/sidecar/zip-stall-bound.js

@@ -0,0 +1,144 @@
+/**
+ * WHEN AMICUS GIVES UP ON AN IN-MEMORY EXTRACTION, and how it stops the work.
+ *
+ * SPLIT OUT of zip-from-buffer.js in the v4.9.6 FOURTH council round, when the
+ * repair below pushed that file back over the repo's 300-line gate. The seam is
+ * the one the last three rounds have all been about: this module owns the
+ * give-up POLICY — the two windows, the bounded wait for an aborted write, and
+ * the classified failure that is raised — while zip-from-buffer.js owns the
+ * yauzl event loop that the policy is applied to. Nothing here knows what a zip
+ * entry is; nothing there decides how long to wait.
+ *
+ * @module sidecar/zip-stall-bound
+ */
+
+'use strict';
+
+const { failure } = require('./zip-entry-write');
+
+/**
+ * THE STALL BOUND, and what did and did not come back with it.
+ *
+ * unzip.js exists for a field bug that was never root-caused: "on some Node 24
+ * boxes extract-zip@2.0.1 STALLS mid-extract — its promise never resolves AND
+ * never rejects", so the awaiting self-heal let the event loop drain and Node
+ * exited 0 with a partial extract and no message. It answered that with three
+ * layers: (1) an idle timer + a hard cap, whose LIVE handle is what stops the
+ * process exiting mid-stall, (2) a native OS unzip fallback, (3) a
+ * files-actually-landed check. All three went with unzip.js when the electron
+ * artifact moved onto `extractZipBuffer` and nothing replaced them: it
+ * had no timer of any kind, so a stalled write (a network volume, a hung AV
+ * filter, an `openReadStream` callback that never arrives) hung `ensureElectron`
+ * forever — and in `scripts/postinstall.js` the loop drained and Node exited 0.
+ *
+ * LAYER 1 IS BACK, with unzip.js's own numbers (30 s idle, 240 s hard) and
+ * unzip.js itself untouched: `IDLE_MS`/`MAX_MS` below.
+ *
+ * ── THE FIRST CUT WAS WRONG IN BOTH DIRECTIONS (round 3) ──────────────────
+ * Seat A1: "the advertised idle timeout fires during legitimate active writes
+ * and does not actually stop extraction." Seat B2: "can false-fire on a single
+ * slow entry write, failing a valid repair on slow storage." Two seats, opposite
+ * directions, both true of code that re-armed on ENTRY COMPLETION and settled
+ * its promise without stopping anything.
+ *
+ *   ARMED AGAINST BYTES, NOT ENTRIES. The real artifact contains a 225 MB
+ *   `electron.exe`, which is ONE entry: on storage slower than 7.5 MB/s that
+ *   entry alone exceeds a 30 s window while writing perfectly well. Progress is
+ *   now `written` — reported by `zip-entry-write.writeEntry`'s CRC transform,
+ *   the stage immediately upstream of the sink, so it counts bytes the
+ *   DESTINATION accepted. The entry count is kept only as a SECOND progress
+ *   term, because an archive of empty files legitimately writes zero bytes.
+ *
+ *   AND IT STOPS THE WORK. `fail()` aborts an `AbortController` BEFORE it
+ *   rejects; `writeEntry` hands that signal to `pipeline`, which destroys the
+ *   source and the sink. MEASURED (Node 24.18.0): after the abort not one
+ *   further byte is accepted by the sink. `placeEntry` refuses to start a new
+ *   entry once the signal is aborted, and `writeSymlink` re-checks it before
+ *   `symlinkSync` (a link target is read through `collect`, not a pipeline).
+ *
+ *   A WATCHDOG, NOT A RE-ARM PER CHUNK. The idle timer re-arms ITSELF: when it
+ *   fires it compares bytes and entries against the mark it took and fails only
+ *   when neither moved. One timer per window instead of one per 64 KiB chunk,
+ *   at the cost of detecting a stall between one and two idle windows after it
+ *   starts — irrelevant at 30 s, and stated rather than left to be discovered.
+ *
+ * ── AND THAT REMEDY REINTRODUCED THE HANG IT REMOVED (round 4) ────────────
+ * The round-3 repair also made the `finally` `await inFlight` — so the caller's
+ * cleanup could not race a live descriptor — AFTER `cancelTimers()` had cleared
+ * both handles. On the one shape the bound exists for, that await CANNOT settle:
+ * `pipeline` waits for every stream to close, and yauzl@2.10.0 replaces its
+ * endpoint stream's `destroy` with a no-arg function that emits neither 'error'
+ * nor 'close' (node_modules/yauzl/index.js, lines 566-573 and 698-713).
+ * MEASURED on the shipped code, Node 24.18.0, real yauzl and a real `pipeline`:
+ * one 1 MiB entry into a sink whose `_write` never calls back, `idleMs: 300` —
+ * the bound fired, the sink accepted nothing further, and the promise was STILL
+ * PENDING at 6 s; in a bare process with no other handle the loop drained and
+ * Node exited 0 having printed nothing. The original field bug, verbatim, from
+ * the commit whose message claimed to prevent it.
+ *
+ *   SO THE UNWIND IS ITSELF BOUNDED. `awaitUnwind` races the in-flight write
+ *   against `UNWIND_MS` on a LIVE timer: the wait keeps the loop alive, and
+ *   then it ENDS. A write that comes apart normally is still awaited in full,
+ *   which is all the round-3 repair actually wanted; one that never does costs
+ *   `unwindMs` and the classified failure is thrown regardless. What that
+ *   trades away is the descriptor race — whose cost is LITTER, not damage:
+ *   `electron-layout.extractBytesToDist` removes the incoming tree best-effort
+ *   (`try { rmSync } catch {}`) and `sweepPromoteLitter` takes what an EPERM
+ *   leaves. A bound that cannot end is not a bound.
+ *
+ * LAYER 2 IS NOT THE DEFAULT AND NEVER CAN BE. Every native strategy (`tar`,
+ * `Expand-Archive`, `ditto`, `unzip`) takes a PATH, and a path is what the
+ * custody finding is about: handing one an artifact would extract bytes amicus
+ * did not hash, and writing our hashed Buffer to a temp file for it would
+ * rebuild the staged copy the council deleted. The two properties cannot both
+ * hold on one run.
+ *
+ * WHAT THAT COST, AND WHAT C2 BOUGHT BACK. This paragraph used to end "an archive
+ * yauzl cannot parse but a native extractor could is a failed repair plus a
+ * re-download" — which on an air-gapped machine is a permanent no-rescue failure,
+ * and a council seat filed it as such. Layer 2 is now reachable again as a
+ * RESCUE, for that ONE failure class (`UNZIP_BUFFER_FAILED`) and only when
+ * `AMICUS_ALLOW_UNVERIFIED_ELECTRON=1` was already set. `electron-native-rescue.js`
+ * owns the whole boundary and the custody it spends; nothing here changed, and a
+ * stall in particular is still NOT a rescue trigger — `UNZIP_BUFFER_STALLED` is
+ * a verdict about nothing, this bound exists to STOP work rather than hand it to
+ * someone else, and it is still never an eviction (see `electron-repair-cache.js`).
+ * LAYER 3 lives upstream and always did:
+ * `electron-quarantine.verifyExtractOutcome` stats the exe after a non-throwing
+ * extract.
+ */
+/** No-progress window, then the hard cap. unzip.js's IDLE_MS / MAX_MS, to the ms. */
+const IDLE_MS = 30_000;
+const MAX_MS = 240_000;
+/** How long an ABORTED write is given to come apart before it is abandoned. */
+const UNWIND_MS = 5_000;
+
+/**
+ * @returns {Error} the extraction made no progress. NOT an archive verdict and
+ * NOT a destination verdict — nobody learned anything about either — so it must
+ * never be the code that evicts a user's cached artifact.
+ */
+const stalled = (message) => failure('UNZIP_BUFFER_STALLED', `the in-memory extraction stalled: ${message}`);
+
+/**
+ * Wait for an ABORTED entry to come apart — bounded, because it may never.
+ *
+ * yauzl's endpoint stream has a `destroy` that emits nothing, so `pipeline`'s
+ * promise can stay pending forever after the abort (see the module docblock's
+ * round-4 section above, where an unbounded wait was measured to hang the whole
+ * extractor). The timer is a LIVE handle for the length of the wait, which is
+ * what stops the process draining mid-stall, and it ends the wait when it fires.
+ *
+ * @returns {Promise<boolean>} true if the write unwound, false if it was abandoned
+ */
+function awaitUnwind(inFlight, ms, setTimer, clearTimer) {
+  return new Promise((resolve) => {
+    const t = setTimer(() => resolve(false), ms);
+    // The rejection is already handled by the driver; this only observes settling.
+    inFlight.then(() => {}, () => {}).then(() => { clearTimer(t); resolve(true); });
+  });
+}
+
+module.exports = {
+  IDLE_MS, MAX_MS, UNWIND_MS, stalled, awaitUnwind,
+};

package/src/utils/doctor-electron-mcp-check.js

@@ -138,11 +138,18 @@ async function evaluateElectronMcp(d) {
   const after = evaluateElectronInstalls(d); // fresh scan reflects the repairs
   if (after.status === 'ok') {
     const n = results.length;
+    // A2/B3: `unverified` used to be written by repairElectron and read by
+    // NOTHING. A repair that no published digest could vouch for is exactly the
+    // thing a `doctor --fix` report exists to say out loud.
+    const unverified = results.filter((r) => r.repaired && r.unverified).length;
+    const mark = unverified > 0
+      ? `, ${unverified} UNVERIFIED (no published sha256 covered the artifact, or its sha256`
+        + ' contradicted the published one and the hatch accepted it)' : '';
     return {
       ...after,
-      message: `${after.message} (self-healed ${n} npx-cache ${plural(n, 'copy', 'copies')})`,
+      message: `${after.message} (self-healed ${n} npx-cache ${plural(n, 'copy', 'copies')}${mark})`,
       fixed: true,
-      fixDetail: `self-healed ${n} npx-cache ${plural(n, 'copy', 'copies')}`,
+      fixDetail: `self-healed ${n} npx-cache ${plural(n, 'copy', 'copies')}${mark}`,
     };
   }
   const failed = results.filter((r) => !r.repaired)