amicus 4.9.5 → 4.9.7

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

@@ -0,0 +1,238 @@
+/**
+ * THE OTHER TABLE AN ARCHIVE DECLARES ITS NAMES IN — the local file headers.
+ *
+ * SPLIT OUT of zip-name-scan.js (v4.9.7, council #239 round 2): that file reached
+ * the repo's 300-line gate, and this walk answers a different question from the
+ * central-directory scan beside it. `nameRefusal` is imported rather than
+ * reimplemented, so there is exactly ONE rule about what yauzl would refuse and
+ * the two tables cannot drift apart.
+ *
+ * WHY A SECOND WALK EXISTS. `scanEntryNames` reads the CENTRAL directory, and an
+ * archive can make that unreadable while leaving every local header whole — a
+ * truncation does it by accident, four one-field edits to a COMPLETE
+ * end-of-central-directory record do it on purpose. MEASURED before this shipped:
+ * seven such archives carrying `../../../PWNED-BY-NATIVE.txt` reached a real
+ * spawn, two of them running to completion. And the tables can DISAGREE, which is
+ * why both are read: on an archive declaring one name locally and another
+ * centrally, `tar.exe` wrote the LOCAL name and `Expand-Archive` the CENTRAL one.
+ *
+ * ONLY EVER A NARROWING. Nothing here can make a rescue HAPPEN: the sole output
+ * that changes control flow is a REFUSAL, and `complete`/`names` exist for the
+ * notice printed before a spawn and decide nothing.
+ *
+ * @module sidecar/zip-local-name-scan
+ */
+
+'use strict';
+
+const { nameRefusal, MAX_ENTRIES } = require('./zip-name-scan');
+
+/** The three signatures the local-header chain walks between. */
+const LOCAL_SIG = 0x04034b50;
+const CENTRAL_SIG = 0x02014b50;
+const EOCD_SIG = 0x06054b50;
+/** Bit 3: the sizes are BEHIND the payload, in a data descriptor. */
+const FLAG_SIZES_DEFERRED = 0x08;
+/** The same local signature as bytes, for scanning a span the walk would jump. */
+const LOCAL_SIG_BYTES = Buffer.from([0x50, 0x4b, 0x03, 0x04]);
+
+/**
+ * Where this archive's END-OF-CENTRAL-DIRECTORY record says its directory begins,
+ * or -1 when no such record can be found.
+ *
+ * THE TERMINUS HAS TO BE ANCHORED TO SOMETHING THE ARCHIVE DECLARES. A walk that
+ * stops the moment it lands on `PK\x01\x02` believes four bytes it has not
+ * earned: MEASURED, planting that signature where an honest advance lands ends
+ * the chain with every local header in the archive untouched and no field lying,
+ * so neither the deferred-size demotion nor the span check fires -- and the walk
+ * reports it saw everything while `tar.exe` went on to reach a `../../../` entry
+ * sitting behind it.
+ */
+function declaredCentralOffset(bytes) {
+  if (bytes.length < 22) { return -1; }
+  const floor = Math.max(0, bytes.length - 22 - 0xFFFF);
+  for (let i = bytes.length - 22; i >= floor; i -= 1) {
+    if (bytes.readUInt32LE(i) === EOCD_SIG) { return bytes.readUInt32LE(i + 16); }
+  }
+  return -1;
+}
+
+/**
+ * THE BYTES THE CHAIN COULD NOT REACH, ASKED THE SAME QUESTION ANYWAY.
+ *
+ * Every way the walk can stop early -- a size deferred to a data descriptor, the
+ * zip64 sentinel, a chain that runs off the end or lands on a non-signature --
+ * leaves the region AHEAD of it unexamined, and an entry the walk never reached
+ * is an entry it cannot refuse. That is the council #239 round-2 BLOCKER, and it
+ * needed no exotic archive: bit 3 with a zero size is a STANDARD encoding, so an
+ * attacker puts one entry in front of `../../../PWNED.txt`, blinds the central
+ * directory, and the walk stops before it ever sees the hostile name.
+ *
+ * WHY NOT SIMPLY REFUSE WHEN THE WALK CANNOT FINISH. Because that is the blanket
+ * fail-closed this cluster already rejected on MEASURED availability grounds: a
+ * truncated zip is the case the whole rescue exists for, and its walk cannot
+ * finish either. Refusing there kills the feature to close the hole.
+ *
+ * So the region is SWEPT rather than trusted or refused: every local-header
+ * signature in it is located and its declared name put through the SAME
+ * `nameRefusal`. It cannot follow the chain (that is what broke), so it does not
+ * pretend to -- `complete` stays false and the notice still says the names could
+ * not be confirmed. It can only ADD refusals, so the narrowing invariant holds
+ * and no archive that is rescued today stops being rescued unless it declares a
+ * hostile name.
+ *
+ * THE RESIDUAL: a `PK\x03\x04` occurring by chance inside a payload is read as a
+ * header, so a refusal can name something that is not an entry. MEASURED: zero
+ * spurious signatures across 777 MB of six real Electron artifacts, and a false
+ * hit must ALSO be followed by bytes that parse as a traversal or absolute name.
+ * It fails toward REFUSING, which costs a rescue and never grants one.
+ *
+ * Bounded: one pass, and at most MAX_ENTRIES candidates.
+ */
+function sweepUnreached(bytes, from) {
+  let seen = 0;
+  let at = from;
+  while (at >= 0 && at + 30 <= bytes.length && seen < MAX_ENTRIES) {
+    const hit = bytes.indexOf(LOCAL_SIG_BYTES, at);
+    if (hit === -1 || hit + 30 > bytes.length) { return null; }
+    seen += 1;
+    const nameLen = bytes.readUInt16LE(hit + 26);
+    const stop = Math.min(hit + 30 + nameLen, bytes.length);
+    const refusal = nameRefusal(bytes.subarray(hit + 30, stop).toString('latin1'));
+    if (refusal) { return refusal; }
+    at = hit + 4;
+  }
+  return null;
+}
+
+/**
+ * THE SAME QUESTION, ASKED OF THE LOCAL FILE HEADERS.
+ *
+ * WHY A SECOND WALK EXISTS. `scanEntryNames` reads the CENTRAL directory, and an
+ * archive can make that unreadable while leaving every local header whole.
+ * MEASURED: four ONE-FIELD edits to a COMPLETE end-of-central-directory record —
+ * entry count `0xFFFF`, cd offset `0xFFFFFFFF`, a lying comment length, a
+ * multi-disk marker — each blind yauzl on an archive whose `../../../` entry
+ * `tar` and `Expand-Archive` then read perfectly. On the comment-length one the
+ * rescue RAN TO COMPLETION and promoted the result. Cutting the tail off the file
+ * does the same thing by accident.
+ *
+ * AND IT IS THE TABLE ONE OF THE STRATEGIES ACTUALLY USES. MEASURED on an archive
+ * declaring one name locally and another centrally: `tar.exe` (bsdtar 3.8.4) wrote
+ * the LOCAL name; `Expand-Archive` wrote the CENTRAL one. Neither table is the
+ * right one to read. Both are. That is the whole ruling — the earlier candidates
+ * argued about which BLINDNESS to tolerate while looking in one table.
+ *
+ * ONE NAME RULE, NOT TWO. It calls `nameRefusal` above, deliberately: a second
+ * lexical rule free to drift from yauzl's would start costing the rescue archives
+ * yauzl accepts, which is the failure this module was written to avoid.
+ *
+ * ONLY `refusal` MAY CHANGE CONTROL FLOW. `complete` and `names` exist for the
+ * notice printed before a spawn and decide nothing, so the module's NARROWING
+ * invariant above holds verbatim: nothing here can make a rescue HAPPEN.
+ *
+ * NEVER THROWS, and synchronous: it reads headers and SKIPS payloads, so it never
+ * decompresses. MEASURED on six real electron artifacts (v28.0.0-v43.6.0,
+ * 107-151 MB): 73-75 names in 0-1 ms, no data descriptors, and the local names
+ * equal the central names entry for entry. Truncated, the central walk goes blind
+ * and this one still enumerates all 73-75.
+ *
+ * WHAT `complete` MEANS, AND WHY IT IS A VARIABLE. It is the claim "I saw every
+ * local header", it starts true, and it may only ever be turned OFF. Three things
+ * turn it off: an entry declaring bit 3 (its stated size is not authoritative),
+ * a declared size whose span HIDES another local signature, and a chain that ends
+ * anywhere but the offset this archive's own EOCD names. All three DEMOTE and
+ * keep walking. That distinction is the whole design: a name the walk can still
+ * read is a name it can still REFUSE, and MEASURED, turning any of these into an
+ * early `return` forfeits the refusal for every entry behind it — an archive
+ * with bit 3, an honest size and `../../../PWNED.txt` at entry 2 went from a
+ * terminal refusal to a completed rescue on 5.7% of forged shapes.
+ *
+ * THE RESIDUAL: the walk still trusts a local size to FIND the next header, so a
+ * desynchronised walk can read a "name" out of payload bytes and refuse a name
+ * that is not an entry. MEASURED constructible; MEASURED to need deliberate
+ * construction — zero spurious `PK\x03\x04` signatures across 777 MB of six real
+ * Electron artifacts. It fails toward REFUSING, which costs a rescue and never
+ * grants one.
+ *
+ * @param {Buffer} bytes the archive, in this process's heap
+ * @returns {{refusal:string|null, complete:boolean, names:number, why:string}}
+ *   `complete` = the chain reached the directory, so EVERY local header was seen.
+ *   A refusal stops the walk early, so it reports `complete:false` too: it did not
+ *   see them all, and a field must not claim otherwise on any of its return sites.
+ */
+function scanLocalNames(bytes) {
+  let at = 0;
+  let names = 0;
+  // `complete` MAY ONLY EVER BE TURNED OFF, and the walk is never SHORTENED by
+  // anything but a refusal or a genuinely unknowable next offset. Turning a
+  // doubt into an early `return` was MEASURED to destroy the refusal for every
+  // entry behind it -- an archive with bit 3, an HONEST size and
+  // `../../../PWNED.txt` at entry 2 went from a terminal UNZIP_UNSAFE_ARCHIVE to
+  // a completed rescue. Deleting the one control-flow-changing power this module
+  // has IS the control-flow change; demoting a claim is not.
+  let complete = true;
+  let why = '';
+  const demote = (m) => { if (complete) { complete = false; why = m; } };
+  const cdOffset = declaredCentralOffset(bytes);
+  // EVERY EARLY EXIT SWEEPS WHAT IT NEVER REACHED. A stop is not a clean bill,
+  // and it is not a refusal either -- but the bytes ahead of it may declare a
+  // name that IS one. See `sweepUnreached`.
+  const stopped = (from, m) => ({ refusal: sweepUnreached(bytes, from), complete: false, names, why: why || m });
+  try {
+    for (;;) {
+      if (at + 4 > bytes.length) { return stopped(at, `the local-header chain ran off the end at ${at}`); }
+      const sig = bytes.readUInt32LE(at);
+      if (sig === CENTRAL_SIG || sig === EOCD_SIG) {
+        // ANCHORED: the chain may claim it reached the directory only where this
+        // archive says its directory begins. See `declaredCentralOffset`.
+        if (at !== cdOffset) { demote(`the chain ended at ${at}, not where this archive declares its directory begins (${cdOffset})`); }
+        return { refusal: null, complete, names, why };
+      }
+      if (sig !== LOCAL_SIG || at + 30 > bytes.length) { return stopped(at, `no local file header at ${at}`); }
+      const flags = bytes.readUInt16LE(at + 6);
+      const compressed = bytes.readUInt32LE(at + 18);
+      const nameLen = bytes.readUInt16LE(at + 26);
+      const extraLen = bytes.readUInt16LE(at + 28);
+      if (at + 30 + nameLen > bytes.length) { return stopped(at, `a local file name was cut off at ${at}`); }
+      names += 1;
+      // Latin-1 for the reason the central walk gives: bytes to characters 1:1.
+      const refusal = nameRefusal(bytes.subarray(at + 30, at + 30 + nameLen).toString('latin1'));
+      if (refusal) { return { refusal, complete: false, names, why: '' }; }
+      // NO NEXT OFFSET AT ALL. These two are the only genuine stops: a zero size
+      // under bit 3 would advance by nothing and resynchronise on payload, and
+      // the zip64 sentinel names a size that is not here.
+      if (((flags & FLAG_SIZES_DEFERRED) && compressed === 0) || compressed === 0xFFFFFFFF) {
+        return stopped(at, `entry ${names} does not declare its size here`);
+      }
+      // BIT 3 SAYS THIS SIZE IS NOT AUTHORITATIVE. APPNOTE 4.4.4 has the writer
+      // set it to ZERO, so a nonzero value beside the flag is malformed by
+      // construction and `complete` may not rest on it -- but it is still the
+      // only lead to the next header, and a name the walk can still read is a
+      // name it can still REFUSE. Follow it; just stop claiming to have proved
+      // anything (the filed blocker: a lying nonzero size jumped a hostile entry
+      // and the walk reported it had seen them all).
+      if (flags & FLAG_SIZES_DEFERRED) { demote(`entry ${names} declares bit 3, so the size it states here is not authoritative`); }
+      const next = at + 30 + nameLen + extraLen + compressed;
+      // THE SPAN THE WALK NEVER LOOKS AT -- name, extra field and payload, every
+      // length the archive's to choose. A span holding a local signature may be
+      // hiding an entry, so the claim is demoted; the walk still follows the
+      // offset, because stopping here would forfeit the refusals behind it.
+      if (next <= bytes.length && next > at + 30) {
+        // BOUNDED TO THE SPAN. Searching to the end of the archive and only then
+        // comparing against `next` is the same answer for O(archive) work PER
+        // ENTRY -- quadratic on attacker-chosen input, synchronous, and on the
+        // rescue path before the hatch policy is even read (council #239 r2).
+        // `subarray` is a view, not a copy, so the total is one pass.
+        const hidden = bytes.subarray(at + 30, next).indexOf(LOCAL_SIG_BYTES);
+        if (hidden !== -1) { demote(`entry ${names}'s declared size jumps over a local file header at ${at + 30 + hidden}`); }
+      }
+      if (names >= MAX_ENTRIES) { return stopped(at, `stopped after ${MAX_ENTRIES} entries`); }
+      at = next;
+    }
+  } catch (e) {
+    return { refusal: null, complete: false, names, why: `the local-header chain could not be walked: ${(e && e.message) || e}` };
+  }
+}
+
+module.exports = { scanLocalNames, declaredCentralOffset };

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

@@ -0,0 +1,146 @@
+/**
+ * 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.
+ *
+ * THE BLINDNESS IN THE FIRST PARAGRAPH IS WHY `scanLocalNames` EXISTS (v4.9.7,
+ * B3). An archive carries its names TWICE, and an unreadable central directory
+ * says nothing about the local file headers — which is the table `tar` was
+ * MEASURED to act on. The caller asks both.
+ *
+ * ── 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)