fix(#4120): replace shellcheck npm dep with dependency-free downloader (#4121)

* fix(#4120): replace shellcheck npm dep with dependency-free downloader

The `shellcheck` devDependency (added in #4109) pulled in decompress@4.2.1
for archive extraction, which carries an unpatched CRITICAL zip-slip
vulnerability (GHSA-mp2f-45pm-3cg9, CVSS 9.1) plus two moderate findings.
decompress's latest published version IS the vulnerable one -- no patched
release exists upstream, so npm audit fix cannot resolve this by upgrading.

Removes the shellcheck package entirely and replaces its role with
scripts/lib/shellcheck-fetch.cjs: a small downloader using only Node's
built-in https/zlib plus a hand-written tar-entry reader, fetching a pinned
koalaman/shellcheck release directly from GitHub releases. The reader never
uses an archive-supplied name as a filesystem path (the exact defect class
decompress had) -- it only returns the matched entry's bytes; the caller
writes those bytes to a path it constructs itself. Bounds the download with
a 30s-per-hop timeout, consistent with the ShellCheck subprocess's own
timeout. Covers linux/darwin on x86_64/aarch64, matching this repo's actual
CI (lint-tests runs only on ubuntu-latest) and local dev needs; Windows
fails with a clear, honest error rather than silently misbehaving.

Adds tests/lint-workflow-shellcheck-fetch.test.cjs covering the tar-parser
(unit cases plus a fast-check property test per CLAUDE.md's parser-testing
requirement), a security behavioral pin confirming traversal-style entry
names are treated as opaque strings never filesystem paths, and boundary
coverage for the redirect-following logic's MAX_REDIRECTS limit
(limit-1/limit/limit+1, via an injectable transport, no real network I/O).

npm audit: 0 vulnerabilities (was 1 critical + 5 moderate). The lint script
reproduces the identical result against the current tree:
"212 pre-existing finding(s) from baseline, 0 new" -- no behavior
regression, no baseline changes needed.

* fix(#4120): register shellcheck-fetch.cjs with the installer

scripts/lib/shellcheck-fetch.cjs shipped without being added to
GSD_SCRIPTS_LIB_FILES in bin/install.js, which would have left it orphaned
on uninstall and broken the golden install-tree fixtures for every runtime.
Adds the entry and regenerates the 19 affected fixtures via
npm run gen:install-tree.

* docs(#4120): add changeset for the decompress CVE fix

---------

Co-authored-by: sim <sim@local>

scripts/lib/shellcheck-fetch.cjs

@@ -0,0 +1,247 @@
+'use strict';
+
+/**
+ * shellcheck-fetch.cjs
+ *
+ * Dependency-free replacement for the `shellcheck` npm package (removed in
+ * #4120 — its extraction step pulled in `decompress@4.2.1`, which carries an
+ * unpatched CRITICAL zip-slip vulnerability, GHSA-mp2f-45pm-3cg9, CVSS 9.1,
+ * plus two moderate findings, with no patched version available upstream).
+ *
+ * This module fetches a PINNED koalaman/shellcheck release directly from
+ * GitHub releases (never "latest" — see SHELLCHECK_VERSION below), extracts
+ * the single `shellcheck` binary from the release's `.tar.gz` asset using
+ * only Node's built-in `https`/`zlib` modules plus a small hand-written tar
+ * reader (no third-party archive library), and caches the extracted binary
+ * for reuse across runs.
+ *
+ * Zip-slip defense: unlike `decompress`, which wrote extracted files using
+ * PATHS TAKEN FROM THE ARCHIVE (the exact defect class in GHSA-mp2f-45pm-
+ * 3cg9 — a malicious archive entry named e.g. `../../etc/passwd` gets
+ * written there verbatim), this reader NEVER uses an archive-supplied name
+ * as a filesystem path. `extractFileFromTar` only ever returns the matched
+ * entry's raw byte content; the caller (`resolveShellcheckBin`) writes those
+ * bytes to a path it constructs itself (`<cacheDir>/shellcheck`), and the
+ * archive's own name field is used only for a string-equality/suffix CHECK
+ * (`name === targetName || name.endsWith('/' + targetName)`), never
+ * interpolated into a path passed to `fs.writeFileSync`/`fs.mkdirSync`/etc.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const zlib = require('node:zlib');
+const https = require('node:https');
+const { ExitError } = require('./cli-exit.cjs');
+
+// Pinned explicitly — verified against `koalaman/shellcheck`'s GitHub
+// releases API as the current latest tag at the time this was written
+// (2026-08-31). Never resolved dynamically ("latest") — a moving target
+// would make this lint's exact ShellCheck version, and therefore its exact
+// finding set against scripts/lint-workflow-shellcheck-baseline.json,
+// non-reproducible across runs/machines/CI.
+const SHELLCHECK_VERSION = 'v0.11.0';
+
+const ROOT = path.join(__dirname, '..', '..');
+const CACHE_DIR = path.join(ROOT, 'node_modules', '.cache', 'shellcheck', SHELLCHECK_VERSION);
+const CACHED_BIN_PATH = path.join(CACHE_DIR, 'shellcheck');
+
+// process.arch -> the arch token ShellCheck's release asset names use.
+// Only the two architectures that actually matter for this repo (per
+// .github/workflows/test.yml: the lint-tests job that runs this script only
+// runs on ubuntu-latest, which is x86_64; and Apple Silicon dev machines are
+// aarch64) are supported — anything else fails with a clear error rather
+// than guessing.
+const ARCH_MAP = { x64: 'x86_64', arm64: 'aarch64' };
+
+const MAX_REDIRECTS = 5;
+
+// Bounds each individual HTTP hop (the initial request AND every redirect
+// hop get their own fresh 30s budget, rather than one shared budget across
+// the whole redirect chain) — a stalled connection on any single hop is
+// caught in a bounded time, mirroring lint-workflow-shellcheck.cjs's own
+// SHELLCHECK_TIMEOUT_MS bound on the ShellCheck subprocess. A bare `timeout`
+// option on the request does NOT abort it by itself — Node only emits a
+// 'timeout' event, which must be handled by destroying the request (see the
+// `req.on('timeout', ...)` below).
+const DOWNLOAD_TIMEOUT_MS = 30_000;
+
+/**
+ * Issue one real HTTPS request. Exists as its own function purely so tests
+ * can inject a fake in its place (see `httpsGetFollowingRedirects`'s
+ * `requestFn` parameter) — production callers never pass an override, so
+ * the real download path always uses this exact implementation.
+ */
+function defaultRequestFn(url, options, callback) {
+  return https.get(url, options, callback);
+}
+
+/**
+ * GET `url` following HTTP redirects manually — `https.get` does NOT follow
+ * redirects automatically, and GitHub release asset URLs redirect through
+ * `objects.githubusercontent.com`. Resolves with the full response body as a
+ * Buffer once a 200 response is received.
+ *
+ * `requestFn` defaults to a real `https.get`-based transport
+ * (`defaultRequestFn`) and is only ever overridden in tests, so calling this
+ * with zero/one arg from `resolveShellcheckBin` is unchanged behavior.
+ */
+function httpsGetFollowingRedirects(url, redirectsLeft = MAX_REDIRECTS, requestFn = defaultRequestFn) {
+  return new Promise((resolve, reject) => {
+    const req = requestFn(
+      url,
+      { headers: { 'User-Agent': 'gsd-core-shellcheck-fetch' }, timeout: DOWNLOAD_TIMEOUT_MS },
+      (res) => {
+        const status = res.statusCode || 0;
+        if (status >= 300 && status < 400 && res.headers.location) {
+          res.resume(); // drain so the socket can be reused/closed
+          if (redirectsLeft <= 0) {
+            reject(new Error(`too many redirects fetching ${url}`));
+            return;
+          }
+          const next = new URL(res.headers.location, url).toString();
+          httpsGetFollowingRedirects(next, redirectsLeft - 1, requestFn).then(resolve, reject);
+          return;
+        }
+        if (status !== 200) {
+          res.resume();
+          reject(new Error(`unexpected HTTP ${status} fetching ${url}`));
+          return;
+        }
+        const chunks = [];
+        res.on('data', (chunk) => chunks.push(chunk));
+        res.on('end', () => resolve(Buffer.concat(chunks)));
+        res.on('error', reject);
+      },
+    );
+    req.on('error', reject);
+    // `timeout` in the options above only ARMS a timer — Node emits a
+    // 'timeout' event on the request but does not abort it. Without this
+    // handler the request (and this Promise) would hang indefinitely past
+    // the configured bound on a stalled connection.
+    req.on('timeout', () => {
+      req.destroy(new Error(`timed out after ${DOWNLOAD_TIMEOUT_MS}ms fetching ${url}`));
+    });
+  });
+}
+
+/**
+ * Find the entry named (or path-ending-in) `targetName` inside a raw
+ * (already gunzipped) POSIX tar byte stream and return its content as a
+ * Buffer, or `null` if not found.
+ *
+ * Tar format: a sequence of 512-byte headers — name at offset 0/length 100,
+ * size at offset 124/length 12 (octal ASCII), typeflag at offset 156 — each
+ * followed by that many content bytes, padded up to the next 512-byte
+ * boundary, terminated by an all-zero 512-byte block. This deliberately
+ * implements only enough to locate ONE known entry name (no general
+ * multi-file extraction, no symlink handling, no GNU long-name `@LongLink`
+ * entries — ShellCheck's own release tarballs never need them) — see this
+ * module's header comment for why the entry's NAME is never used as a
+ * filesystem path.
+ */
+function extractFileFromTar(buffer, targetName) {
+  let offset = 0;
+  while (offset + 512 <= buffer.length) {
+    const header = buffer.subarray(offset, offset + 512);
+    if (header.every((b) => b === 0)) break; // end-of-archive marker
+    const name = header.subarray(0, 100).toString('utf8').replace(/\0.*$/, '');
+    const sizeRaw = header.subarray(124, 136).toString('utf8').replace(/\0.*$/, '').trim();
+    const size = sizeRaw === '' ? 0 : parseInt(sizeRaw, 8);
+    const typeflag = String.fromCharCode(header[156]);
+    const dataStart = offset + 512;
+    const isRegularFile = typeflag === '0' || typeflag === '\0';
+    if (isRegularFile && (name === targetName || name.endsWith(`/${targetName}`))) {
+      return buffer.subarray(dataStart, dataStart + size);
+    }
+    const contentBlocks = Math.ceil(size / 512);
+    offset = dataStart + contentBlocks * 512;
+  }
+  return null;
+}
+
+/**
+ * Resolve the local path to a working, executable `shellcheck` binary,
+ * downloading and caching the pinned release on first use. Subsequent calls
+ * (same version) reuse the cached binary with no network activity — mirrors
+ * the `fs.accessSync(bin, F_OK | X_OK)` cache-check pattern already used by
+ * this script's own `runShellcheck`.
+ */
+async function resolveShellcheckBin() {
+  try {
+    fs.accessSync(CACHED_BIN_PATH, fs.constants.F_OK | fs.constants.X_OK);
+    return CACHED_BIN_PATH;
+  } catch {
+    // not cached yet — fall through to download
+  }
+
+  if (process.platform === 'win32') {
+    throw new ExitError(
+      1,
+      'lint-workflow-shellcheck: automatic ShellCheck download is not supported on Windows yet ' +
+        '(this lint only ever runs in the ubuntu-latest lint-tests CI job — see .github/workflows/test.yml — ' +
+        'so this is an honest platform gap, not expected to be hit in CI).',
+    );
+  }
+  const platform = process.platform === 'darwin' || process.platform === 'linux' ? process.platform : null;
+  if (!platform) {
+    throw new ExitError(
+      1,
+      `lint-workflow-shellcheck: unsupported platform '${process.platform}' for ShellCheck auto-download ` +
+        `(supported: linux, darwin).`,
+    );
+  }
+  const arch = ARCH_MAP[process.arch];
+  if (!arch) {
+    throw new ExitError(
+      1,
+      `lint-workflow-shellcheck: unsupported architecture '${process.arch}' for ShellCheck auto-download ` +
+        `(supported: x86_64 [node arch 'x64'], aarch64 [node arch 'arm64']).`,
+    );
+  }
+
+  const assetName = `shellcheck-${SHELLCHECK_VERSION}.${platform}.${arch}.tar.gz`;
+  const url = `https://github.com/koalaman/shellcheck/releases/download/${SHELLCHECK_VERSION}/${assetName}`;
+
+  let gz;
+  try {
+    gz = await httpsGetFollowingRedirects(url);
+  } catch (e) {
+    throw new ExitError(1, `lint-workflow-shellcheck: failed to download ShellCheck (${url}): ${e.message}`);
+  }
+
+  let tarBuf;
+  try {
+    tarBuf = zlib.gunzipSync(gz);
+  } catch (e) {
+    throw new ExitError(1, `lint-workflow-shellcheck: failed to gunzip downloaded ShellCheck archive: ${e.message}`);
+  }
+
+  const entry = extractFileFromTar(tarBuf, 'shellcheck');
+  if (!entry) {
+    throw new ExitError(
+      1,
+      `lint-workflow-shellcheck: could not find a 'shellcheck' entry inside downloaded archive ${assetName}`,
+    );
+  }
+
+  fs.mkdirSync(CACHE_DIR, { recursive: true });
+  // Write to a per-process temp path and rename into place — avoids any
+  // other concurrent invocation observing (and trying to execute) a
+  // partially-written binary at the real cache path.
+  const tmpPath = path.join(CACHE_DIR, `.shellcheck.tmp-${process.pid}`);
+  fs.writeFileSync(tmpPath, entry);
+  fs.chmodSync(tmpPath, 0o755);
+  fs.renameSync(tmpPath, CACHED_BIN_PATH);
+
+  return CACHED_BIN_PATH;
+}
+
+module.exports = {
+  SHELLCHECK_VERSION,
+  CACHED_BIN_PATH,
+  MAX_REDIRECTS,
+  DOWNLOAD_TIMEOUT_MS,
+  extractFileFromTar,
+  httpsGetFollowingRedirects,
+  resolveShellcheckBin,
+};

scripts/lint-workflow-shellcheck.cjs

@@ -13,14 +13,15 @@
  * bash) from landing undetected a second time (it already landed 4 times in
  * this repo's workflow templates before #4109's fix).
  *
- * ShellCheck source: the `shellcheck` npm package (gunar/shellcheck), a thin
- * wrapper that downloads the official koalaman/shellcheck binary on first
- * use and caches it under node_modules/shellcheck/bin/. Chosen over the
- * alternatives surveyed (node-shellcheck: ~5 weekly downloads, last
- * published 2022; shellcheck-binaries: ~280 weekly downloads, last
- * published 2022) because it has ~80k weekly downloads and is the
- * only actively-maintained wrapper — it downloads the CURRENT upstream
- * ShellCheck release rather than vendoring a stale binary snapshot.
+ * ShellCheck source: scripts/lib/shellcheck-fetch.cjs, a small dependency-
+ * free downloader that fetches a PINNED koalaman/shellcheck release directly
+ * from GitHub releases and caches the extracted binary under
+ * node_modules/.cache/shellcheck/<version>/. This replaces the `shellcheck`
+ * npm package (gunar/shellcheck) originally used here (#4109) — removed in
+ * #4120 because its extraction dependency, `decompress@4.2.1`, carries an
+ * unpatched CRITICAL zip-slip vulnerability (GHSA-mp2f-45pm-3cg9, CVSS 9.1)
+ * with no patched version available upstream. See shellcheck-fetch.cjs's own
+ * header comment for the extraction implementation and its zip-slip defense.
  *
  * Extraction: reuses scanFencedBlocks from markdown-sectionizer.cts (the
  * canonical fence-scanning engine — see tests/review-plan-coverage-manifest
@@ -112,23 +113,17 @@ const os = require('node:os');
 const path = require('node:path');
 const childProcess = require('node:child_process');
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+const { resolveShellcheckBin } = require('./lib/shellcheck-fetch.cjs');
 
 // Hard bound on the ShellCheck binary's run time, matching this repo's
 // npm-subprocess timeout convention (5-30s git, 60s npm — same "external
-// process that could hang" hazard class). See runShellcheck's comment for
-// why this cannot be applied via the `shellcheck` npm package's own API.
+// process that could hang" hazard class). Applied directly to runShellcheck's
+// own spawnSync call below.
 const SHELLCHECK_TIMEOUT_MS = 60_000;
 
 const ROOT = path.join(__dirname, '..');
 const WORKFLOWS_DIR = path.join(ROOT, 'gsd-core', 'workflows');
 const SECTIONIZER_PATH = path.join(ROOT, 'gsd-core', 'bin', 'lib', 'markdown-sectionizer.cjs');
-const SHELLCHECK_BIN_MODULE = path.join(ROOT, 'node_modules', 'shellcheck', 'build', 'index.js');
-// The top-level SHELLCHECK_BIN_MODULE barrel (build/index.js) does NOT
-// re-export `configs/index.js` (verified: `export *`-ing helpers/logger/
-// utils/shellcheck.js only — no configs), so `config` (which carries the
-// resolved binary path used by runShellcheck's own spawnSync call, see
-// below) has to be imported from its own submodule directly.
-const SHELLCHECK_CONFIG_MODULE = path.join(ROOT, 'node_modules', 'shellcheck', 'build', 'configs', 'index.js');
 const BASELINE_PATH = path.join(__dirname, 'lint-workflow-shellcheck-baseline.json');
 
 // Codes excluded for structural reasons documented in the module header above.
@@ -443,58 +438,25 @@ function loadSectionizer() {
   }
 }
 
-/** Load the `shellcheck` npm package's programmatic API — its own `shellcheck()`
- * function transparently downloads the real binary to node_modules/shellcheck/
- * bin/shellcheck (caching it there) on first use if it is not already present. */
-async function loadShellcheckModule() {
-  try {
-    const mod = await import(SHELLCHECK_BIN_MODULE);
-    // See SHELLCHECK_CONFIG_MODULE's comment above — `config` is not part of
-    // the top-level barrel's exports, so it is imported separately and
-    // attached here for runShellcheck's direct spawnSync call to consume.
-    const { config } = await import(SHELLCHECK_CONFIG_MODULE);
-    return { ...mod, config };
-  } catch (e) {
-    throw new ExitError(
-      1,
-      `lint-workflow-shellcheck: cannot load the 'shellcheck' npm package at ` +
-        `${path.relative(ROOT, SHELLCHECK_BIN_MODULE)} — run 'npm install' first (${e.message})`,
-    );
-  }
-}
-
 /**
  * Run ShellCheck (json1 output) over every staged temp file in one invocation,
  * bounded by SHELLCHECK_TIMEOUT_MS.
  *
- * The `shellcheck` npm package's own `shellcheck()` function does NOT accept a
- * `timeout` — its `ShellCheckArgs` type is `{bin, args, stdio, token}` only
- * (verified against node_modules/shellcheck/build/shellcheck.d.ts and .js),
- * and internally it hardcodes `child_process.spawnSync(opts.bin, opts.args, {
- * stdio: opts.stdio })` with no pass-through for extra spawnSync options.
- * Wrapping the call in `Promise.race` against a timer would not help either:
- * spawnSync is synchronous and blocks the event loop for its whole duration,
- * so a timer callback racing it can never fire before it returns (or hangs).
- * Instead, this reimplements the same binary-resolve-and-download step the
- * wrapper performs (via the package's own exported `config`/`download`), then
- * invokes `child_process.spawnSync` directly with a native `timeout` so a
- * hung ShellCheck binary is killed (Node sets `result.error.code ===
- * 'ETIMEDOUT'` and `result.signal` on expiry) rather than hanging this lint —
- * and, transitively, CI — indefinitely.
+ * `bin` is resolved by the caller via scripts/lib/shellcheck-fetch.cjs's
+ * `resolveShellcheckBin()` (downloading and caching the pinned release on
+ * first use, per that module's own header comment). This invokes
+ * `child_process.spawnSync` directly with a native `timeout` so a hung
+ * ShellCheck binary is killed (Node sets `result.error.code === 'ETIMEDOUT'`
+ * and `result.signal` on expiry) rather than hanging this lint — and,
+ * transitively, CI — indefinitely.
  */
-async function runShellcheck(mod, filePaths) {
+function runShellcheck(bin, filePaths) {
   const args = [
     '--shell=bash',
     '--format=json1',
     `--exclude=${EXCLUDED_CODES.join(',')}`,
     ...filePaths,
   ];
-  const bin = mod.config.bin;
-  try {
-    fs.accessSync(bin, fs.constants.F_OK | fs.constants.X_OK);
-  } catch {
-    await mod.download({ destination: bin, token: process.env.GITHUB_TOKEN });
-  }
   const result = childProcess.spawnSync(bin, args, { stdio: 'pipe', timeout: SHELLCHECK_TIMEOUT_MS });
   if (result.error) {
     const timedOut = result.error.code === 'ETIMEDOUT';
@@ -560,7 +522,7 @@ async function main() {
   }
   const structuralFailed = structuralFindings.length > 0;
 
-  const shellcheckModule = await loadShellcheckModule();
+  const shellcheckBin = await resolveShellcheckBin();
 
   const stageDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-workflow-shellcheck-'));
   try {
@@ -573,7 +535,7 @@ async function main() {
       byPath.set(scriptPath, block);
     });
 
-    const findings = await runShellcheck(shellcheckModule, stagedPaths);
+    const findings = runShellcheck(shellcheckBin, stagedPaths);
 
     if (findings.length === 0) {
       process.stdout.write(