amicus 4.9.4 → 4.9.6

package/src/sidecar/electron-trust.js

@@ -0,0 +1,226 @@
+/**
+ * Electron artifact TRUST core — the digest anchor and the gate. (The third
+ * member of the cluster, the installer-spawn env scrub, lives in
+ * ./electron-env-scrub and is re-exported here; see below.)
+ *
+ * A hostile REPOSITORY (a clone the user opens, an unpacked sample) controls the
+ * `.npmrc` and `package.json` of the directory amicus's own docs tell people to
+ * run `npx -y amicus@latest` in. MEASURED (npm 11.16.0): that reaches the child
+ * as exactly two name shapes — `npm_config_<key lowercased>` and
+ * `npm_package_config_<key case-preserved>` — and NOTHING else. Bare `ELECTRON_*`
+ * and `AMICUS_*` names are out of its reach. THAT is the trust boundary this
+ * module encodes: the escape hatch can be a plain environment variable, and a
+ * machine-level `ELECTRON_MIRROR` can still be honoured, precisely because a
+ * repository cannot write either one.
+ *
+ * The control is the DIGEST, not the URL. Supplying `checksums` to
+ * `downloadArtifact` makes `@electron/get` write a LOCAL `SHASUMS256.txt` and
+ * never fetch one from the mirror (@electron/get 5.0.0, dist/index.js, lines
+ * 28-40), so an attacker who redirects the download still has to produce bytes that match
+ * electron's own published sha256. Blocking the URL itself is defence in depth on
+ * top of a control that already works, and is deliberately NOT built here.
+ *
+ * NEAR-LEAF MODULE: `crypto` + `path` + `fs`, plus `./electron-env-scrub`, which
+ * is itself a true leaf (no requires at all). The arrow is electron-install ->
+ * electron-provision -> electron-trust -> electron-env-scrub and must never point
+ * back; src/utils/path-fence.js:11-17 records what a cycle does to a destructured
+ * import in exactly this cluster.
+ *
+ * THE ENV SCRUB LIVES NEXT DOOR (v4.9.6 F2). `isRepoPlantedName` and
+ * `REPO_ENV_PREFIXES` moved to `./electron-env-scrub` when this file hit the
+ * 300-line gate with the F2 repair still to land, and are RE-EXPORTED here so
+ * existing import paths stay valid — the same shape as engine-log-parse.js
+ * re-exporting utils/text-sanitize.js. There is ONE implementation; these are
+ * the same function objects, not a second copy. (`scrubbedChildEnv` and
+ * `ELECTRON_INSTALL_TARGET_ENV` were deleted with the install.js spawn they
+ * served; see electron-provision.js for why that spawn is gone.)
+ *
+ * @module sidecar/electron-trust
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+const fsDefault = require('fs');
+const path = require('path');
+
+const { isRepoPlantedName, REPO_ENV_PREFIXES } = require('./electron-env-scrub');
+
+/** A published sha256 is 64 LOWER-case hex characters. Anything else is not an anchor. */
+const HEX64 = /^[0-9a-f]{64}$/;
+
+/** Leading 'v' applied exactly once — matches @electron/get's normalizeVersion. */
+function normalizeV(version) {
+  const v = String(version || '');
+  return v.startsWith('v') ? v : `v${v}`;
+}
+
+/**
+ * The amicus-namespaced trust policy. THE ONLY place the escape hatch is read.
+ * Never reads npm_config_* / npm_package_config_* / NPM_CONFIG_* — those are the
+ * attacker's channel, and a rule that read its own writer's surface would be no
+ * rule at all.
+ *
+ * `allowUnverified` is true for the string '1' and NOTHING else — 'true', 'yes',
+ * ' 1' are all false. A hatch that fails open on a typo is not a hatch.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {{ allowUnverified: boolean }}
+ */
+function electronTrustPolicy(env = process.env) {
+  return { allowUnverified: env.AMICUS_ALLOW_UNVERIFIED_ELECTRON === '1' };
+}
+
+/** `electron-v43.1.1-win32-x64.zip`. Matches BOTH electron's checksums.json keys
+ *  and @electron/get's getArtifactFileName + normalizeVersion. */
+function artifactFileName({ version, platform, arch }) {
+  return `electron-${normalizeV(version)}-${platform}-${arch}.zip`;
+}
+
+/**
+ * The electron package THIS amicus resolves — resolveAnchor rung 1. Duplicated
+ * (not imported from electron-install.defaultElectronDir) so this module stays a
+ * leaf and the require arrow keeps pointing one way.
+ * @returns {string|null}
+ */
+function selfElectronPackageDir() {
+  try {
+    return path.dirname(require.resolve('electron/package.json'));
+  } catch {
+    return null;
+  }
+}
+
+/** Parse one checksums.json into a table of ONLY well-formed rows. Never throws. */
+function readChecksumTable(file, fs) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) { return null; }
+    const table = {};
+    for (const [name, digest] of Object.entries(parsed)) {
+      if (typeof digest === 'string' && HEX64.test(digest)) { table[name] = digest; }
+    }
+    return Object.keys(table).length > 0 ? table : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the digest ANCHOR, offline. Precedence, highest first:
+ *   1. <selfElectronDir>/checksums.json — the RUNNING amicus's own table.
+ *   2. <electronDir>/checksums.json — ONLY when rung 1 offers no usable table.
+ *
+ * RUNG 1 IS LOAD-BEARING, not a convenience. `doctor --fix`
+ * (src/utils/doctor-electron-mcp-check.js:122-137) hands `repairElectron` an
+ * electronDir found by a FILESYSTEM SCAN of npx caches, so rung 2 on its own
+ * would read the anchor out of the same untrusted directory the bytes came from
+ * — the pin would vouch for the attacker's own zip. Rung 1 is the same published
+ * data out of a tree npm installed for amicus itself, before any hostile
+ * directory was visited.
+ *
+ * WHY RUNG 1 NO LONGER TESTS THE VERSION. It used to apply only when the self
+ * package's version equalled the requested one — but the requested `version` is
+ * itself read out of `<electronDir>/package.json` whenever the caller supplies
+ * none (electron-install.js `if (!version)`), and the ONE production caller,
+ * doctor --fix, supplies none. MEASURED on this tree: a planted
+ * `{"version":"99.0.0"}` demoted rung 1 by DATA alone, the scanned tree's own
+ * checksums.json then vouched for its own bytes, and repairElectron returned
+ * `{repaired:true}` after extracting POISONED-BYTES. A rule that reads its own
+ * selector off the surface it exists to distrust is not a rule. No version check
+ * is needed to keep a genuine version disagreement honest, because the table is
+ * keyed by the FULL artifact filename: a self table for 43.1.1 simply holds no
+ * `electron-v99.0.0-…zip` row, `expectedDigest` returns null, and the gate's
+ * `no-digest` verdict extracts-and-MARKS exactly as the brief requires — never a
+ * refusal, never a re-download loop.
+ *
+ * Rung 2 therefore survives for exactly one case: amicus's own electron package
+ * ships no readable checksums.json (an old electron, or the optionalDependency
+ * never installed). There the target's table is all there is, and it is still
+ * better than nothing against a truncated download.
+ *
+ * Pass `selfElectronDir: null` to disable rung 1.
+ * NEVER THROWS. Rejects a table whose values are not 64 lower-case hex.
+ * @returns {{ table: Record<string,string>, source: string } | null}
+ */
+function resolveAnchor({ electronDir, fs = fsDefault, selfElectronDir } = {}) {
+  const self = selfElectronDir === undefined ? selfElectronPackageDir() : selfElectronDir;
+  for (const dir of [self, electronDir]) {
+    if (!dir) { continue; }
+    const source = path.join(dir, 'checksums.json');
+    const table = readChecksumTable(source, fs);
+    if (table) { return { table, source }; }
+  }
+  return null;
+}
+
+/** @returns {string|null} the 64-hex digest for one artifact, or null. */
+function expectedDigest(anchor, fileName) {
+  if (!anchor || !anchor.table) { return null; }
+  const digest = anchor.table[fileName];
+  return typeof digest === 'string' && HEX64.test(digest) ? digest : null;
+}
+
+/** sha256 of an artifact amicus already holds in its own heap. */
+function sha256Bytes(bytes) {
+  return crypto.createHash('sha256').update(bytes).digest('hex');
+}
+
+/**
+ * THE GATE, OVER BYTES. NEVER THROWS. `allowed` is the single decision bit.
+ *
+ * @returns {{verdict:'verified',   allowed:true,  actual:string}
+ *         | {verdict:'mismatch',   allowed:boolean, expected:string, actual:string}
+ *         | {verdict:'no-digest',  allowed:true}}
+ *
+ * IT TAKES A BUFFER, AND THE PATH FORM IS GONE. `verifyArtifact({zip, ...})` and
+ * `sha256File` were DELETED in the v4.9.6 second council round, not deprecated.
+ * Hashing a path and then handing that path to an extractor is the race three
+ * seats filed against v4.9.5, and hashing a private COPY of it is the race a
+ * fourth seat filed against the remedy — a same-uid attacker opens the copy too
+ * (MEASURED). Leaving a path-hashing gate exported and callable is an invitation
+ * to reintroduce it, and no caller is left that could legitimately want one. The
+ * bytes now arrive from `electron-custody.readArtifactBytes`, which reads them
+ * once through one descriptor, and the SAME Buffer is what `zip-from-buffer`
+ * extracts.
+ *
+ * `unreadable` disappeared with the path form. Unreadability is decided BEFORE
+ * any hashing now, by `readArtifactBytes`, and the caller refuses there — bytes
+ * that could not be read never reach this function, so there is no verdict for
+ * them to carry.
+ *
+ * `no-digest` is ALLOWED and merely marked. An electron package that predates
+ * `checksums.json` has no anchor through no fault of its own, and refusing it
+ * would push that machine into a permanent re-download loop for a file no
+ * download can improve. THE NOTE BELOW IS THE CACHE ROUTE'S stderr line, the one
+ * `docs/troubleshooting.md` promises; the download route prints its own.
+ */
+function verifyArtifactBytes({ bytes, anchor, fileName, policy = {}, log = () => {} }) {
+  const expected = expectedDigest(anchor, fileName);
+  if (!expected) {
+    log(`[amicus] NOTE: no published sha256 for ${fileName} (this electron package ships no`);
+    log('[amicus]   checksums.json entry for it), so its bytes could not be verified.');
+    return { verdict: 'no-digest', allowed: true };
+  }
+  const actual = sha256Bytes(bytes);
+  if (actual === expected) { return { verdict: 'verified', allowed: true, actual }; }
+  if (policy.allowUnverified) {
+    log(`[amicus] WARNING: AMICUS_ALLOW_UNVERIFIED_ELECTRON=1 — accepting ${fileName} even though`);
+    log(`[amicus]   its sha256 ${actual} does not match the published ${expected}.`);
+    log('[amicus]   Unset that variable to fail closed.');
+    return { verdict: 'mismatch', allowed: true, expected, actual };
+  }
+  return { verdict: 'mismatch', allowed: false, expected, actual };
+}
+
+module.exports = {
+  electronTrustPolicy,
+  resolveAnchor,
+  expectedDigest,
+  verifyArtifactBytes,
+  sha256Bytes,
+  artifactFileName,
+  normalizeV,
+  // RE-EXPORTED from ./electron-env-scrub — the same function objects, not copies.
+  isRepoPlantedName,
+  REPO_ENV_PREFIXES,
+};

package/src/sidecar/unzip.js

@@ -17,6 +17,8 @@
  *      the exact electron zip the field box choked on.
  *   3. Only report success when files actually landed on disk. The electron
  *      exe-stat verify stays upstream (electron-quarantine.verifyExtractOutcome).
+ * Layer 2 has ONE exception: a path-traversal REFUSAL is terminal and is never
+ * retried natively (UNSAFE_PATTERNS below).
  *
  * Everything network/spawn/timer-facing is dependency-INJECTABLE so tests never
  * hit the real clock, spawn a real process, or extract a real binary.
@@ -28,6 +30,41 @@ const path = require('path');
 const fsDefault = require('fs');
 const { spawnSync } = require('child_process');
 
+// F5: refusals quote the ARCHIVE'S OWN entry name, so every message built from
+// one is sanitized before it reaches stderr or an Error a caller prints.
+const { collapseExcerpt } = require('../utils/text-sanitize');
+
+/**
+ * A SECURITY REFUSAL IS A REFUSAL, NOT A RETRY (M9).
+ *
+ * Strategy 1 used to collapse a stall, a plain throw, and extract-zip's / yauzl's
+ * own path-traversal refusals into ONE branch that cleans the directory and re-runs
+ * the IDENTICAL archive through OS extractors amicus does not control — laundering
+ * a "this archive tried to escape its directory" into an unsupervised retry.
+ *
+ * These four strings are verified against the installed versions:
+ *   extract-zip@2.0.1 raises `Out of bound path "<dir>" found while processing file <n>`
+ *   yauzl@2.10.0 validateFileName returns the other three, raised as new Error(msg).
+ * NOTE: with strictFileNames unset (extract-zip's default) yauzl rewrites
+ * backslashes before validating, so `invalid characters in fileName: ` is not
+ * reachable through extract-zip today. Classified anyway — it costs one line and
+ * yauzl's defaults can change.
+ *
+ * DELIBERATELY NARROW. A stall must still fall back, or the Node-24 workaround
+ * this whole module exists for is destroyed.
+ *
+ * AND THE VERIFICATION NO LONGER DECAYS (v4.9.6 F4). "Verified against the
+ * installed versions" had nothing keeping it true; tests/sidecar/unzip-refusal-strings.js
+ * now drives the INSTALLED libraries into producing all four for real, and fails
+ * both on a reworded refusal and on a pattern no real message produces.
+ */
+const UNSAFE_PATTERNS = [
+  /^Out of bound path /,
+  /^absolute path: /,
+  /^invalid relative path: /,
+  /^invalid characters in fileName: /,
+];
+
 // No-progress window: if extract-zip reports no new entry for this long AND has
 // not settled, treat it as the silent stall. Reset on every onEntry so a slow-
 // but-progressing extract is never falsely aborted.
@@ -162,6 +199,8 @@ function runExtractZipBounded({ zip, dir, onEntry, extractZip, idleMs, maxMs, se
  * @param {object}   [opts.deps] injected { fs, extractZip, spawn, setTimeout, clearTimeout, log }
  * @returns {Promise<{strategy:string, fallback?:boolean, extractZipReason?:string}>}
  * @throws {Error} code 'UNZIP_ALL_FAILED' when no strategy produced files.
+ * @throws {Error} code 'UNZIP_UNSAFE_ARCHIVE' when the archive was REFUSED for a
+ *   path-traversal attempt — terminal, with no native retry (see UNSAFE_PATTERNS).
  */
 async function robustExtract(zip, opts = {}) {
   const {
@@ -202,8 +241,18 @@ async function robustExtract(zip, opts = {}) {
     return { strategy: 'extract-zip' };
   }
 
+  // TERMINAL: the archive was REFUSED for trying to write outside `dir`. Never
+  // cleanDir (the partial output is evidence), never fall back — handing the same
+  // archive to tar/Expand-Archive would ask a tool with no such check to do what
+  // extract-zip just declined to.
+  if (!z.ok && UNSAFE_PATTERNS.some((p) => p.test(z.reason || ''))) {
+    const err = new Error(`refusing to extract ${zip}: ${collapseExcerpt(z.reason)}`);
+    err.code = 'UNZIP_UNSAFE_ARCHIVE';
+    throw err;
+  }
+
   // extract-zip stalled / threw / produced nothing → clean partial output, go native.
-  const zipReason = z.ok ? 'extract-zip produced no files' : z.reason;
+  const zipReason = z.ok ? 'extract-zip produced no files' : collapseExcerpt(z.reason);
   cleanDir(fs, dir);
   log(`[amicus] extract-zip did not complete (${zipReason}); falling back to native unzip.`);
 
@@ -243,4 +292,5 @@ async function robustExtract(zip, opts = {}) {
   throw err;
 }
 
-module.exports = { robustExtract, nativeUnzipPlan, IDLE_MS, MAX_MS };
+// UNSAFE_PATTERNS is exported for the F4 upstream-drift probe (see its docblock).
+module.exports = { robustExtract, nativeUnzipPlan, IDLE_MS, MAX_MS, UNSAFE_PATTERNS };

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