amicus 4.9.5 → 4.9.7

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,231 @@
+/**
+ * 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. It is refused in the
+ * same `Out of bound path` wording and exercised against synthetic archives
+ * here; the darwin `.app` bundle is the only electron artifact with real
+ * symlinks, and since v4.9.7 `.github/workflows/darwin-bundle.yml` runs this
+ * path over the REAL artifact on a real Mac. The v4.9.6 worry that the check
+ * might REJECT a working layout is refuted by measurement: the real
+ * `electron-v43.1.1-darwin-arm64.zip` declares 585 records and 14 symlinks,
+ * every target relative, none carrying a `..` component, none absolute, and 0
+ * of the 585 entry names traversing a symlinked component. The linux artifacts
+ * hold ZERO symlink entries, so `writeSymlink` is unreachable there at all.
+ *
+ * `root = fs.realpathSync(dir)` below is load-bearing for that answer and no
+ * Windows probe would ever show it: on macOS the extraction root usually sits
+ * under `/var`, which is itself a symlink to `/private/var`, so comparing a
+ * resolved target against an UNRESOLVED root would read every link in a real
+ * `.app` as an escape.
+ *
+ * ── 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 };