amicus 4.9.5 → 4.9.6

package/src/sidecar/zip-entry-write.js

@@ -0,0 +1,268 @@
+/**
+ * ONE ENTRY of an in-memory archive, and the classified failures every caller
+ * acts on.
+ *
+ * SPLIT OUT of zip-from-buffer.js in the v4.9.6 third round: that file reached
+ * the repo's 300-line gate when the symlink-target control and the stall bound
+ * grew, and the seam is real. This module answers "what does one archive entry
+ * become on disk, and whose fault is it when that fails"; zip-from-buffer.js
+ * answers "how is the archive driven, and when do we give up on it". Nothing
+ * here knows about yauzl's event loop and nothing there writes a byte.
+ *
+ * ── ERROR CODES ARE A CAUSAL CLAIM, AND THE CALLER DELETES ON ONE OF THEM ──
+ * `UNZIP_BUFFER_FAILED` = the ARCHIVE is bad; it is the ONLY code that lets
+ * `electron-repair-cache` evict a user's cached artifact. `UNZIP_DEST_FAILED` =
+ * the DESTINATION is bad (no space, a read-only dist/, a path too long, a
+ * machine that cannot represent a symlink). `UNZIP_BUFFER_UNAVAILABLE` =
+ * neither; yauzl would not load. Every throw in this module goes through one of
+ * the three constructors below, so no unclassified error can reach a caller
+ * that reads "unclassified" as "the archive is bad" — council finding D2, and
+ * the leak that reopened it (a raw stream error out of `collect`) is closed by
+ * `collect` tagging its own rejection.
+ *
+ * @module sidecar/zip-entry-write
+ */
+
+'use strict';
+
+const path = require('path');
+const zlib = require('zlib');
+const { pipeline } = require('stream/promises');
+const { Transform } = require('stream');
+
+const { collapseExcerpt } = require('../utils/text-sanitize');
+
+/** @returns {Error} tagged with `code`, sanitized: every throw here is classified. */
+function failure(code, message) {
+  return Object.assign(new Error(collapseExcerpt(message)), { code });
+}
+
+/** @returns {Error} an archive-is-bad failure: the caller MAY evict the artifact. */
+const badArchive = (message) => failure('UNZIP_BUFFER_FAILED', message);
+
+/** @returns {Error} a destination-is-bad failure: the caller must NOT evict anything. */
+const badDestination = (message) => failure('UNZIP_DEST_FAILED', message);
+
+/** @returns {Error} the TERMINAL path-traversal refusal, in extract-zip's own
+ *  `Out of bound path ` wording so unzip.js's UNSAFE_PATTERNS still classifies it. */
+const outOfBound = (where, fileName) => failure('UNZIP_UNSAFE_ARCHIVE', `Out of bound path "${where}" found while processing file ${fileName}`);
+
+/**
+ * @returns {Error} yauzl would not load. NOT an archive failure and NOT a
+ * destination failure: the artifact is fine and so is the disk. unzip.js
+ * records the v4.5.2 outage where an undeclared `extract-zip` threw
+ * MODULE_NOT_FOUND out of a bare `require` and took a whole function with it;
+ * `yauzl` is declared for that reason, and this guard is what stops a hoisting
+ * surprise from turning into a DELETED cache entry.
+ */
+const extractorUnavailable = (message) => failure('UNZIP_BUFFER_UNAVAILABLE', `the in-memory zip extractor is unavailable: ${message}`);
+
+/**
+ * Collect a readable fully into one Buffer (a symlink target is a few bytes).
+ *
+ * CLASSIFIED, like every other throw here. This was the ONE throw site that
+ * rejected with the RAW yauzl/stream error, which carries no `code` — and
+ * `electron-repair-cache` read an unclassified extract failure as "the archive
+ * is bad" and DELETED the user's cached artifact. A read error on a symlink
+ * target IS an archive-side failure, so it is named as one rather than left to
+ * be guessed at.
+ */
+function collect(stream, what) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    stream.on('data', (c) => chunks.push(c));
+    stream.on('error', (e) => reject(badArchive(`could not read ${what}: ${(e && e.message) || e}`)));
+    stream.on('end', () => resolve(Buffer.concat(chunks)));
+  });
+}
+
+/** One entry's payload stream, decompressed by yauzl exactly as extract-zip gets it. */
+function entryStream(zipfile, entry) {
+  return new Promise((resolve, reject) => {
+    zipfile.openReadStream(entry, (err, stream) => {
+      if (err) { reject(badArchive(`${entry.fileName}: ${(err && err.message) || err}`)); return; }
+      resolve(stream);
+    });
+  });
+}
+
+/**
+ * Write one entry, checking its CRC-32 against the archive's own declaration.
+ * An INTEGRITY check, not a security control (CRC-32 is linear and forgeable):
+ * it catches a broken zlib or bad RAM, and is meaningful only because the
+ * whole-buffer sha256 already ran on these exact bytes. yauzl checks no CRC at
+ * all; `validateEntrySizes: true` covers the length half.
+ *
+ * `onBytes` AND `signal` ARE THE STALL BOUND'S TWO HALVES (round 3, seat A1 +
+ * B2), and both live here because this is the only function that writes.
+ *
+ * `onBytes(n)` reports WRITE PROGRESS, which is what the bound is armed against
+ * — the caller re-arms on bytes, never on entries, so a single 225 MB
+ * `electron.exe` on slow storage cannot look idle. It fires from the CRC
+ * transform, the stage immediately upstream of the sink, so it reports bytes the
+ * DESTINATION has accepted rather than bytes read out of the buffer. MEASURED
+ * (Node 24.18.0) against a sink whose `_write` never calls back: the counter
+ * stops, overshooting the sink by exactly one 64 KiB readable-side highWaterMark
+ * and no more, whether the wedge happens after 64 KiB or after 640 KiB. A hung
+ * destination therefore still stops the counter, which is what makes a genuine
+ * stall catchable.
+ *
+ * `signal` is what makes the bound STOP the work rather than merely report it.
+ * `pipeline` destroys every stream on abort — MEASURED: source and sink both
+ * `destroyed`, not one further byte counted or accepted — so no write can land
+ * after the caller has given up and started cleaning the incoming tree. The
+ * rejection it produces is a plain `AbortError` (`pipeline` does not carry the
+ * abort reason), which is why the caller keeps its own classified failure and
+ * discards this one.
+ */
+async function writeEntry({ zipfile, entry, dest, mode, fs, onBytes, signal }) {
+  const source = await entryStream(zipfile, entry);
+  let crc = 0;
+  // Accumulated by a TRANSFORM in the pipeline, never by a `data` listener:
+  // attaching one starts the flow before `pipeline` has piped it, losing bytes.
+  const crcThrough = new Transform({
+    transform(chunk, _enc, cb) {
+      crc = zlib.crc32(chunk, crc);
+      if (onBytes) { onBytes(chunk.length); }
+      cb(null, chunk);
+    },
+  });
+  let sink;
+  try {
+    sink = fs.createWriteStream(dest, { mode });
+  } catch (e) {
+    throw badDestination(`could not write ${entry.fileName}: ${(e && e.message) || e}`);
+  }
+  // WHICH SIDE FAILED FIRST is the causal claim the caller acts on (D2): a bad
+  // archive may be evicted, a full disk must never be. `pipeline` destroys the
+  // other half after the first error, so both ends usually end up emitting —
+  // only the FIRST one recorded says what actually happened.
+  let first = null;
+  const note = (from) => (e) => { if (!first) { first = { from, e }; } };
+  source.on('error', note('archive'));
+  sink.on('error', note('dest'));
+  try {
+    await pipeline(source, crcThrough, sink, ...(signal ? [{ signal }] : []));
+  } catch (e) {
+    const cause = first ? first.e : e;
+    const detail = `${entry.fileName}: ${(cause && cause.message) || cause}`;
+    throw first && first.from === 'dest'
+      ? badDestination(`could not write ${detail}`)
+      : badArchive(`could not inflate ${detail}`);
+  }
+  if ((crc >>> 0) !== (entry.crc32 >>> 0)) {
+    throw badArchive(`crc32 mismatch for ${entry.fileName}`);
+  }
+}
+
+/**
+ * Create one symlink, refusing a target that resolves outside `root`.
+ *
+ * `canonical` is `realpathSync` of the directory the link is ACTUALLY created
+ * in — never `path.dirname(dest)`. That distinction is the whole control, and
+ * getting it wrong was MEASURED to defeat the check completely: three entries
+ * naming `L0`, `L0/L1`, `L0/L1/L2`, each a symlink to `.`, make the LEXICAL
+ * dirname `<root>/L0/L1/L2` three levels deeper than the real one (`<root>`),
+ * so a fourth entry `L0/L1/L2/x -> ../../../victim` resolved to `<root>/victim`
+ * — inside, accepted — while the link really landed at `<root>/../../../victim`.
+ * Escape depth tracked chain length 1:1. Every one of those names passes
+ * yauzl's `validateFileName`, so one ordinary-looking archive was arbitrary
+ * same-user file write outside the extraction root.
+ *
+ * WHAT THIS DOES AND DOES NOT PROMISE. It resolves the target from the real
+ * directory and refuses anything that leaves `root`; it does NOT follow
+ * symlinks inside the target's own intermediate components, so a link pointing
+ * at an in-root path that some LATER entry turns into a link elsewhere is not
+ * caught here — that shape is caught by the per-entry `realpath` bound check in
+ * `placeEntry`, which re-runs after every earlier entry has been written.
+ *
+ * `signal` is checked immediately before the `symlinkSync`. A link target is a
+ * handful of bytes read through `collect`, which is not a `pipeline` and so is
+ * not destroyed by the abort — without this check the stall bound could fire and
+ * a symlink still appear in the tree the caller is about to delete.
+ */
+async function writeSymlink({ zipfile, entry, canonical, root, fs, signal }) {
+  const target = (await collect(await entryStream(zipfile, entry), `the symlink target for ${entry.fileName}`)).toString('utf8');
+  const dest = path.join(canonical, path.basename(entry.fileName));
+  const resolved = path.resolve(canonical, target);
+  const rel = path.relative(root, resolved);
+  // SYMLINKESCAPE: `..` at the head, or an absolute answer (a different Windows
+  // drive), means the link points out of the tree amicus is allowed to write.
+  if (rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+    throw outOfBound(resolved, entry.fileName);
+  }
+  if (signal && signal.aborted) { return; }
+  try {
+    fs.symlinkSync(target, dest);
+  } catch (e) {
+    throw badDestination(`could not create the symlink ${entry.fileName}: ${(e && e.message) || e}`);
+  }
+}
+
+/** stat mode constants, as extract-zip decodes them from externalFileAttributes. */
+const IFMT = 61440;
+const IFDIR = 16384;
+const IFLNK = 40960;
+
+/** extract-zip's getExtractedMode, with its 0755/0644 defaults. */
+function extractedMode(entryMode, isDir) {
+  if (entryMode !== 0) { return entryMode; }
+  return isDir ? 0o755 : 0o644;
+}
+
+/**
+ * One entry, mirroring extract-zip's Extractor.extractEntry decision order.
+ *
+ * MOVED HERE from zip-from-buffer.js in the third council round, when the stall
+ * bound's repair pushed that file back over the 300-line gate. It is not a
+ * convenience move: this function answers "what does one archive entry become on
+ * disk, and whose fault is it when that fails", which is this module's whole
+ * subject, and it calls nothing but this module's own writers. What stays next
+ * door is the archive DRIVER — yauzl's event loop, the bound, and the decision
+ * to give up.
+ *
+ * `signal` is the stall bound's halt: an entry that arrives after the bound
+ * fired creates NOTHING — not the directory, not the file — because the caller
+ * is already deleting the incoming tree.
+ * @returns {Promise<boolean>} true if the entry was placed (false = skipped)
+ */
+async function placeEntry({ zipfile, entry, root, fs, signal, onBytes }) {
+  // Nothing is created for an entry that arrives after the bound fired.
+  if (signal && signal.aborted) { return false; }
+  if (entry.fileName.startsWith('__MACOSX/')) { return false; }
+  if (entry.isEncrypted()) { throw badArchive(`${entry.fileName} is encrypted`); }
+  const dest = path.join(root, entry.fileName);
+  const mode = (entry.externalFileAttributes >> 16) & 0xFFFF;
+  const symlink = (mode & IFMT) === IFLNK;
+  let isDir = (mode & IFMT) === IFDIR;
+  if (!isDir && entry.fileName.endsWith('/')) { isDir = true; }
+  if (!isDir) { isDir = ((entry.versionMadeBy >> 8) === 0 && entry.externalFileAttributes === 16); }
+  const procMode = extractedMode(mode, isDir) & 0o777;
+  const destDir = isDir ? dest : path.dirname(dest);
+  let canonical;
+  try {
+    fs.mkdirSync(destDir, isDir ? { recursive: true, mode: procMode } : { recursive: true });
+    canonical = fs.realpathSync(destDir);
+  } catch (e) {
+    throw badDestination(`could not create ${destDir}: ${(e && e.message) || e}`);
+  }
+  // extract-zip's check, VERBATIM — re-run per entry, AFTER earlier entries were
+  // written, so a symlink an earlier entry created cannot redirect a later one.
+  if (path.relative(root, canonical).split(path.sep).includes('..')) {
+    throw outOfBound(canonical, entry.fileName);
+  }
+  if (isDir) { return true; }
+  if (symlink) {
+    // `canonical`, NEVER `dest`: the link's target is resolved against the
+    // directory realpath says it is created in (see writeSymlink).
+    await writeSymlink({ zipfile, entry, canonical, root, fs, signal });
+  } else {
+    await writeEntry({ zipfile, entry, dest, mode: procMode, fs, onBytes, signal });
+  }
+  return true;
+}
+
+module.exports = {
+  failure, badArchive, badDestination, outOfBound, extractorUnavailable,
+  collect, entryStream, writeEntry, writeSymlink, placeEntry,
+};

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