iterate-skill-installer 3.5.1 → 3.5.3

package/README.md

@@ -39,8 +39,15 @@ npx iterate-skill-installer --version
 
 1. Checks for Python 3 on your system.
 2. Fetches the latest iterate-skill release from GitHub.
-3. Downloads the release tarball and `SHA256SUMS.txt`.
-4. Verifies the tarball checksum.
+3. Downloads the release tarball, `SHA256SUMS.txt` and its detached GPG
+   signature (`iterate-skill.tar.gz.asc`).
+4. Verifies BOTH the tarball checksum (integrity) and the signature against the
+   pinned iterate signing key (authenticity). **Signing is mandatory**: a
+   release without a valid signature is refused, because `SHA256SUMS.txt`
+   travels in the same release as the tarball and therefore cannot be the only
+   anchor. Install GnuPG (`gpg`) if you do not have it; hosts that cannot run
+   gpg may opt out explicitly with `ITERATE_ALLOW_UNSIGNED=1` (a bad signature
+   is never bypassed).
 5. Extracts the release into a temporary directory.
 6. Runs the bundled Python install script (`scripts/install.py`) which:
    - Detects installed AI coding assistants on your machine.

package/README.zh-CN.md

@@ -39,8 +39,13 @@ npx iterate-skill-installer --version
 
 1. 检查你系统上的 Python 3。
 2. 从 GitHub 获取最新的 iterate-skill 发布版本。
-3. 下载发布 tarball 与 `SHA256SUMS.txt`。
-4. 校验 tarball 的校验和。
+3. 下载发布 tarball、`SHA256SUMS.txt` 及其分离式 GPG 签名
+   （`iterate-skill.tar.gz.asc`）。
+4. 同时校验 tarball 校验和（完整性）与签名（真实性，对照内嵌的 iterate 签名公钥）。
+   **签名为强制**：没有有效签名的发布会直接拒绝安装——因为 `SHA256SUMS.txt` 与
+   tarball 出自同一个 release，不能作为唯一信任锚点。没有 `gpg` 请先安装 GnuPG；
+   确实无法运行 gpg 的环境可显式设置 `ITERATE_ALLOW_UNSIGNED=1` 放行（但**坏签名
+   永不放行**）。
 5. 解压发布内容到临时目录。
 6. 运行自带的 Python 安装脚本（`scripts/install.py`），它会：
    - 检测你机器上已安装的 AI 编程助手。

package/bin/cli.js

@@ -42,28 +42,48 @@ Examples:
 }
 
 async function run() {
-  const options = parseArgs(process.argv.slice(2));
+  let options;
+  try {
+    options = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    // Hard argument errors are THROWN by parseArgs (library code never calls
+    // process.exit); report them cleanly at this boundary.
+    console.error(`Error: ${err.message}`);
+    return 1;
+  }
 
   if (options.mode === 'help') {
     printHelp();
-    process.exit(0);
+    return 0;
   }
 
   if (options.mode === 'version') {
     console.log(`iterate-skill-installer ${VERSION}`);
-    process.exit(0);
+    return 0;
   }
 
   try {
     const code = await main(options);
     // Normalize: a null/non-numeric code (main should never produce one, but a
     // signal-killed child upstream does) must surface as a failure, never as
-    // the success exit 0 that `process.exit(null)` would yield.
-    process.exit(typeof code === 'number' ? code : 1);
+    // the success exit 0 that a null exit code would yield.
+    return typeof code === 'number' ? code : 1;
   } catch (err) {
     console.error(`\nUnexpected error: ${err.message}`);
-    process.exit(1);
+    return 1;
   }
 }
 
-run();
+// CLI boundary: set process.exitCode rather than calling process.exit(), so
+// buffered stdout/stderr still flush and no caller cleanup is skipped. The
+// trailing catch is the top-level net: an unexpected rejection (e.g. a throw
+// before run()'s inner try) becomes a clean message + non-zero code, never an
+// unhandled-rejection stack trace.
+run()
+  .then((code) => {
+    process.exitCode = typeof code === 'number' ? code : 1;
+  })
+  .catch((err) => {
+    console.error(`\nUnexpected error: ${err && err.message ? err.message : err}`);
+    process.exitCode = 1;
+  });

package/lib/installer.js

@@ -339,9 +339,14 @@ function validateTokenShape(token) {
  * loudly instead of leaking the PAT to a foreign host.
  */
 function buildAuthFlags(url, token) {
-  if (!token) return [];
+  // Re-normalize here as well as at the CLI boundary: this is the exact point
+  // the token is interpolated into a header, so a raw CR/LF (e.g. a token read
+  // from a Windows-created file) must never reach curl — an embedded newline
+  // would split the header (CRLF/header injection) or silently break auth.
+  const clean = normalizeToken(token);
+  if (!clean) return [];
   if (!isGithubApiUrl(url)) return [];
-  return ['-H', `Authorization: Bearer ${token}`, '--max-redirs', '0'];
+  return ['-H', `Authorization: Bearer ${clean}`, '--max-redirs', '0'];
 }
 
 async function fetchJson(url, token) {
@@ -349,7 +354,10 @@ async function fetchJson(url, token) {
   // and avoids Node-specific certificate issues in some environments.
   const failFlag = (await supportsCurlFailWithBody()) ? '--fail-with-body' : '--fail';
   const args = ['-sSL', failFlag, '--max-time', CURL_MAX_TIME_SECONDS, '--max-filesize', String(JSON_MAX_BYTES), '-H', 'Accept: application/vnd.github+json', '-H', 'X-GitHub-Api-Version: 2022-11-28', '-H', 'User-Agent: iterate-skill-installer', ...buildAuthFlags(url, token)];
-  args.push(url);
+  // `--` ends curl's option parsing so a URL that begins with `-` (e.g. a
+  // hostile/odd `browser_download_url` served by the API) is treated as a URL,
+  // never smuggled in as a curl flag.
+  args.push('--', url);
   // stdoutMustBeComplete with an explicit cap: the default 1 MiB TailBuffer
   // would truncate a large /releases payload and JSON.parse then failed with a
   // baffling "Unexpected end of JSON input". The cap now matches the
@@ -381,7 +389,9 @@ async function downloadFile(url, destPath, token, { progress = false, maxBytes =
   const failFlag = (await supportsCurlFailWithBody()) ? '--fail-with-body' : '--fail';
   const args = ['-sSL', failFlag, '--max-time', CURL_MAX_TIME_SECONDS, '--max-filesize', String(maxBytes), '-o', destPath, '-H', 'User-Agent: iterate-skill-installer', ...buildAuthFlags(url, token)];
   if (progress) args.push('--progress-bar');
-  args.push(url);
+  // `--` ends curl's option parsing so a `-`-leading URL can never be read as
+  // a curl flag (option injection); it is always the final positional URL.
+  args.push('--', url);
   if (progress) {
     // Let curl write its progress bar directly to the terminal.
     await runCommand('curl', args, { stdio: ['ignore', 'ignore', 'inherit'] });
@@ -424,6 +434,79 @@ function enforceDownloadedSize(destPath, maxBytes) {
   }
 }
 
+// True when the operator explicitly opted out of signature enforcement. Kept
+// as an ENVIRONMENT variable (not a flag) so it cannot be enabled from a
+// project config and shows up in the invoking environment for audit.
+const ALLOW_UNSIGNED_ENV = 'ITERATE_ALLOW_UNSIGNED';
+
+// Only these (case-insensitive) values enable the override. A bare "any
+// non-empty string" check meant `ITERATE_ALLOW_UNSIGNED=0` (or "false", or a
+// stray "no") ENABLED unsigned installs — the exact opposite of what the
+// operator intended, and a silent downgrade of the authenticity gate.
+const ALLOW_UNSIGNED_TRUTHY = new Set(['1', 'true', 'yes']);
+
+function allowUnsigned() {
+  const raw = process.env[ALLOW_UNSIGNED_ENV];
+  if (raw == null) return false;
+  return ALLOW_UNSIGNED_TRUTHY.has(String(raw).trim().toLowerCase());
+}
+
+/**
+ * Apply the MANDATORY release-signature policy (mirrors
+ * ``iterate_cli/signing.py`` and ``scripts/install.py``).
+ *
+ * Returns an error MESSAGE when the install must abort, or null when it may
+ * proceed. The ``ITERATE_ALLOW_UNSIGNED`` override downgrades "cannot check"
+ * (no ``.asc`` asset / no ``gpg`` binary) to a warning, but it NEVER bypasses a
+ * BAD signature — that is exactly the tampering/key-substitution case.
+ *
+ * @param {object} state
+ * @param {boolean} state.hasSignatureAsset  release published an ``.asc``
+ * @param {string}  [state.status]           'verified' | 'invalid' | 'unavailable'
+ * @param {string}  [state.detail]           verifier detail for messages
+ * @param {string}  [state.downloadError]    failure to FETCH the ``.asc``
+ * @param {boolean} [state.allowUnsigned]    override (defaults to the env var)
+ */
+function signaturePolicyError({
+  hasSignatureAsset,
+  status = null,
+  detail = '',
+  downloadError = null,
+  allowUnsigned: override = allowUnsigned(),
+} = {}) {
+  if (downloadError) {
+    // The release DID publish a signature but we could not fetch it: a
+    // transport problem, not a licence to skip authenticity.
+    return (
+      `Could not download the release signature (${downloadError}). Refusing to install ` +
+      `without authenticity verification; retry once the network recovers. Set ` +
+      `${ALLOW_UNSIGNED_ENV}=1 only if you accept an unauthenticated install.`
+    );
+  }
+  if (!hasSignatureAsset) {
+    if (override) return null;
+    return (
+      'Release is UNSIGNED: it publishes no .asc signature, so authenticity cannot be ' +
+      `verified (SHA256SUMS travels in the same release and is not an independent ` +
+      `anchor). Set ${ALLOW_UNSIGNED_ENV}=1 only if you accept an unauthenticated install.`
+    );
+  }
+  if (status === 'verified') return null;
+  if (status === 'invalid') {
+    return (
+      `GPG signature verification FAILED (${detail}). Refusing to install: the tarball ` +
+      `is not signed by the pinned iterate signing key. This is either tampering or a ` +
+      `key rotation this installer version does not know about; ${ALLOW_UNSIGNED_ENV} ` +
+      'does NOT bypass a bad signature.'
+    );
+  }
+  if (override) return null;
+  return (
+    `Cannot verify the release signature (${detail || 'gpg unavailable'}). Install GnuPG ` +
+    `(gpg) and retry, or set ${ALLOW_UNSIGNED_ENV}=1 to accept an unauthenticated install.`
+  );
+}
+
 function sha256File(filePath) {
   return new Promise((resolve, reject) => {
     const hash = crypto.createHash('sha256');
@@ -434,6 +517,31 @@ function sha256File(filePath) {
   });
 }
 
+/**
+ * Constant-time, case-insensitive comparison of two SHA256 hex digests.
+ *
+ * Casing must never decide the outcome: `sha256sum`/other tools may emit
+ * upper-case hex, and a case-sensitive `===` would reject a perfectly good
+ * release. Both sides are lower-cased and compared with `timingSafeEqual` —
+ * the expected hash travels over the network beside the tarball, so an
+ * early-exit string inequality would leak prefix information usable to forge a
+ * checksum. The length guard keeps `timingSafeEqual` from throwing on
+ * mismatched lengths (an empty/short value is refused outright).
+ *
+ * Exported so the comparison itself is unit-testable (the inline version it
+ * replaces could only be exercised by a full network install).
+ */
+function constantTimeHashEqual(actualHash, expectedHash) {
+  if (typeof actualHash !== 'string' || typeof expectedHash !== 'string') return false;
+  const actualBuf = Buffer.from(actualHash.trim().toLowerCase(), 'utf8');
+  const expectedBuf = Buffer.from(expectedHash.trim().toLowerCase(), 'utf8');
+  return (
+    actualBuf.length === expectedBuf.length &&
+    actualBuf.length > 0 &&
+    crypto.timingSafeEqual(actualBuf, expectedBuf)
+  );
+}
+
 // Best-effort GPG authenticity verification of a downloaded artifact against
 // the embedded signing key. Returns one of:
 //   'verified'    — `gpg` present and the detached signature is valid.
@@ -447,7 +555,11 @@ function sha256File(filePath) {
 // Runs inside an isolated temporary GNUPGHOME so the end user's own keyring and
 // gpg-agent are never touched or modified.
 function verifyGpgDetachedSignature(artifactPath, signaturePath, publicKeyArmor, tmpDir) {
-  const gpgHome = path.join(tmpDir, 'gnupg');
+  // NOTE: gpg derives its agent socket from the homedir
+  // (<homedir>/S.gpg-agent) and unix sockets cap out around 104 characters, so
+  // keep this path SHORT — a deep tmpdir made gpg fail with "File name too
+  // long: can't connect to the gpg-agent".
+  const gpgHome = path.join(tmpDir, 'g');
   fs.mkdirSync(gpgHome, { recursive: true, mode: 0o700 });
   const keyPath = path.join(tmpDir, 'iterate-skill-pubkey.asc');
   fs.writeFileSync(keyPath, publicKeyArmor, 'utf8');
@@ -678,77 +790,118 @@ function runCommand(bin, args, options = {}) {
 
 async function rejectLinkEntries(tarballPath, { listingCap = MAX_LISTING_CHARS } = {}) {
   // Inspect the verbose listing and reject any symbolic ("l") or hard ("h")
-  // link entry. We deliberately reject *all* links rather than validating
-  // their targets: the release tarball contains none, so any link is a sign
-  // of a tampered archive and refusing it outright is the safest response to
-  // a symlink-escape attempt (see extractTarball above).
+  // link entry — and any device ("b" block / "c" character), FIFO ("p") or
+  // socket special node. We deliberately reject *all* links rather than
+  // validating their targets: the release tarball contains none, so any link is
+  // a sign of a tampered archive and refusing it outright is the safest
+  // response to a symlink-escape attempt (see extractTarball above). Special
+  // nodes are rejected for the same reason: neither the release nor its
+  // installer ever ships one, and a FIFO/device could wedge or bypass a later
+  // read of the extracted tree.
   //
   // stdoutMustBeComplete: this listing is a SECURITY input. The old 1 MiB
   // tail buffer silently dropped the OLDEST entries, so an archive with enough
   // filler members to push its listing past the cap hid a symlink/hardlink
   // entry from this scan entirely (while `tar -xzf` still extracted it).
   // A listing over the cap now fails closed instead.
+  //
+  // Returns the COMPLETE verbose listing so callers (extractTarball) can reuse
+  // it for the pre-extraction declared-size check without a second tar run.
   const verbose = await runCommand('tar', ['-tvzf', tarballPath], {
     stdoutCap: listingCap,
     stdoutMustBeComplete: true,
   });
+  const TYPE_LABELS = {
+    l: 'symbolic link',
+    h: 'hard link',
+    b: 'block device node',
+    c: 'character device node',
+    p: 'FIFO',
+    s: 'socket',
+  };
   for (const line of verbose.split(/\r?\n/)) {
     if (!line) {
       continue;
     }
     const type = line[0];
-    if (type === 'l') {
-      throw new InstallerError(
-        'Refusing to extract tarball: archive contains a symbolic link, which the release never ships.',
-      );
-    }
-    if (type === 'h') {
+    const label = TYPE_LABELS[type];
+    if (label) {
       throw new InstallerError(
-        'Refusing to extract tarball: archive contains a hard link, which the release never ships.',
+        `Refusing to extract tarball: archive contains a ${label}, which the release never ships.`,
       );
     }
   }
+  return verbose;
 }
 
-async function extractTarball(tarballPath, destDir, { listingCap = MAX_LISTING_CHARS } = {}) {
-  // Use the system tar command (available on macOS, Linux, and Windows 10+),
-  // but defend against path-traversal tarballs: before extracting we list the
-  // archive contents and refuse to extract any entry whose resolved path
-  // escapes destDir (e.g. a "../" prefix). This keeps the installer
-  // dependency-free while closing the theoretical escape vector.
-  //
-  // Extraction uses --strip-components=1, which relies on the archive having
-  // exactly one top-level directory (see README "Release tarball structure").
-  // Archives that violate that contract — multiple top-level directories, or
-  // entries with no path left after stripping — are rejected outright.
-  //
-  // A name-based `../` check alone is not enough: a tarball can smuggle a
-  // symlink whose in-archive name looks safe but whose target points outside
-  // destDir, then place files "through" that symlink (e.g. `link/passwd` where
-  // `link -> /etc`). Because extraction happens with a system `tar`, the write
-  // would follow the link before we could validate — so any symbolic or hard
-  // link is rejected *before* extraction. The release tarball never uses links.
-  const absoluteDest = path.resolve(destDir);
-  fs.mkdirSync(absoluteDest, { recursive: true });
+// A month abbreviation ("Jan".."Dec") appears in the timestamp column of the
+// bsdtar verbose listing; GNU tar prints an ISO date ("2023-01-01"). Both mark
+// the end of the size/user fields, so the numeric token immediately before the
+// first such token is the entry's declared uncompressed size in EITHER format.
+const MONTH_ABBR_RE = /^(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)$/;
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 
-  // 1. List archive entries (no extraction yet). Must be complete — see
-  //    rejectLinkEntries: every guard below reads THIS listing, and a tail
-  //    buffer would let a big archive hide entries from all of them.
-  const listing = await runCommand('tar', ['-tzf', tarballPath], {
-    stdoutCap: listingCap,
-    stdoutMustBeComplete: true,
-  });
-  const entries = listing.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
-  if (entries.length === 0) {
-    throw new InstallerError('Refusing to extract tarball: archive contains no entries.');
+/**
+ * Parse one `tar -tvzf` line's declared uncompressed size, or null when the
+ * line cannot be parsed. `size` is the numeric field immediately preceding the
+ * timestamp column (see MONTH_ABBR_RE / ISO_DATE_RE).
+ */
+function declaredEntrySize(line) {
+  const tokens = line.trim().split(/\s+/);
+  for (let i = 1; i < tokens.length; i += 1) {
+    if (ISO_DATE_RE.test(tokens[i]) || MONTH_ABBR_RE.test(tokens[i])) {
+      const candidate = tokens[i - 1];
+      return /^\d+$/.test(candidate) ? Number(candidate) : null;
+    }
   }
+  return null;
+}
 
-  // 1a. Reject absolute-path entries outright before any other accounting.
-  // A member named ``/etc/cron.d/x`` or ``C:\\...`` would resolve through the
-  // top-level-strip logic into destDir, but accepting its name as a "safe"
-  // component invites ambiguity between tar implementations about what the
-  // first component really is — never claim a release archive can contain
-  // absolute paths, so fail closed instead.
+/**
+ * Sum the declared uncompressed sizes in a `tar -tvzf` listing.
+ *
+ * This is the PRE-extraction half of the decompression-bomb guard: `tar -xzf`
+ * has no size bound and the download cap only limits the COMPRESSED size, so a
+ * small highly-compressible archive can declare (and would expand to) many GiB.
+ * Reading the declared sizes out of the listing lets us refuse BEFORE writing
+ * anything to disk. Returns the total plus how many entries were parsed so a
+ * caller can distinguish "empty" from "unparseable format".
+ */
+function sumDeclaredSizes(verboseListing) {
+  let total = 0;
+  let parsed = 0;
+  let entries = 0;
+  for (const line of verboseListing.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    entries += 1;
+    const size = declaredEntrySize(line);
+    if (size !== null) {
+      total += size;
+      parsed += 1;
+    }
+  }
+  return { total, parsed, entries };
+}
+
+/**
+ * Validate every archive member NAME before extraction.
+ *
+ * Rejects, in order:
+ *   - absolute paths (`/etc/...`, `C:\...`), which invite ambiguity between
+ *     tar implementations about what the "first component" is;
+ *   - any `..` path component (path traversal), which — even when the
+ *     top-level-strip logic happens to keep it inside destDir — violates the
+ *     release's "single top-level directory" contract and must never appear;
+ *   - archives without exactly one top-level directory (required by
+ *     --strip-components=1);
+ *   - entries that still escape destDir after the top-level component is
+ *     stripped.
+ *
+ * Pure and exported so the guards are unit-testable without crafting hostile
+ * tarballs. Returns the resolved top-level directory name.
+ */
+function validateEntryNames(entries, absoluteDest) {
+  // Reject absolute-path entries outright before any other accounting.
   for (const entry of entries) {
     if (entry.startsWith('/') || /^[A-Za-z]:[\\/]/.test(entry)) {
       throw new InstallerError(
@@ -757,15 +910,20 @@ async function extractTarball(tarballPath, destDir, { listingCap = MAX_LISTING_C
     }
   }
 
-  // 1b. Reject any symbolic or hard link entry before touching the tree.
-  // The verbose listing's first character is the entry type for both GNU tar
-  // and bsdtar (macOS): '-' regular, 'd' directory, 'l' symbolic link, 'h'
-  // hard link. We only need to detect links, so a cheap first-char scan is
-  // sufficient and avoids relying on the rest of the format.
-  await rejectLinkEntries(tarballPath, { listingCap });
+  // Reject any ``..`` component. A name-based resolve() check below already
+  // catches escapes, but an explicit rejection is unambiguous and also refuses
+  // the "stripped away" cases (e.g. a lone `..` top-level) that resolve back
+  // inside destDir while still violating the archive contract.
+  for (const entry of entries) {
+    if (entry.split('/').includes('..')) {
+      throw new InstallerError(
+        `Refusing to extract tarball: entry "${entry}" contains a ".." path component.`,
+      );
+    }
+  }
 
-  // 2. Enforce the single-top-level-directory contract required by
-  //    --strip-components=1.
+  // Enforce the single-top-level-directory contract required by
+  // --strip-components=1.
   const topLevelComponents = new Set(entries.map((entry) => entry.split('/')[0]));
   if (topLevelComponents.size !== 1) {
     const tops = [...topLevelComponents].join(', ');
@@ -775,8 +933,8 @@ async function extractTarball(tarballPath, destDir, { listingCap = MAX_LISTING_C
   }
   const topLevel = entries[0].split('/')[0];
 
-  // 3. Validate every entry stays inside destDir after stripping the single
-  //    top-level directory component (--strip-components=1).
+  // Validate every entry stays inside destDir after stripping the single
+  // top-level directory component (--strip-components=1).
   for (const entry of entries) {
     const stripped = entry.split('/').slice(1).join('/');
     if (stripped === '') {
@@ -798,7 +956,73 @@ async function extractTarball(tarballPath, destDir, { listingCap = MAX_LISTING_C
     }
   }
 
+  return topLevel;
+}
+
+async function extractTarball(
+  tarballPath,
+  destDir,
+  { listingCap = MAX_LISTING_CHARS, declaredSizeCap = MAX_EXTRACTED_BYTES } = {},
+) {
+  // Use the system tar command (available on macOS, Linux, and Windows 10+),
+  // but defend against path-traversal tarballs: before extracting we list the
+  // archive contents and refuse to extract any entry whose resolved path
+  // escapes destDir (e.g. a "../" prefix). This keeps the installer
+  // dependency-free while closing the theoretical escape vector.
+  //
+  // Extraction uses --strip-components=1, which relies on the archive having
+  // exactly one top-level directory (see README "Release tarball structure").
+  // Archives that violate that contract — multiple top-level directories, or
+  // entries with no path left after stripping — are rejected outright.
+  //
+  // A name-based `../` check alone is not enough: a tarball can smuggle a
+  // symlink whose in-archive name looks safe but whose target points outside
+  // destDir, then place files "through" that symlink (e.g. `link/passwd` where
+  // `link -> /etc`). Because extraction happens with a system `tar`, the write
+  // would follow the link before we could validate — so any symbolic or hard
+  // link is rejected *before* extraction. The release tarball never uses links.
+  // Note: dest is created AFTER every guard below (not before), so a refused
+  // archive never leaves a directory behind. `tar -xzf` requires the target to
+  // exist, so mkdir stays inside this function rather than with the caller.
+  const absoluteDest = path.resolve(destDir);
+
+  // 1. List archive entries (no extraction yet). Must be complete — see
+  //    rejectLinkEntries: every guard below reads THIS listing, and a tail
+  //    buffer would let a big archive hide entries from all of them.
+  const listing = await runCommand('tar', ['-tzf', tarballPath], {
+    stdoutCap: listingCap,
+    stdoutMustBeComplete: true,
+  });
+  const entries = listing.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+  if (entries.length === 0) {
+    throw new InstallerError('Refusing to extract tarball: archive contains no entries.');
+  }
+
+  // 1a/2/3. Reject absolute paths and `..` components, enforce the single
+  //         top-level directory, and prove every entry stays inside destDir.
+  validateEntryNames(entries, absoluteDest);
+
+  // 1b. Reject any symbolic/hard link — and any device/FIFO/socket node —
+  // before touching the tree. The verbose listing's first character is the
+  // entry type for both GNU tar and bsdtar (macOS): '-' regular, 'd' directory,
+  // 'l' symbolic link, 'h' hard link, 'b'/'c' device, 'p' FIFO. The COMPLETE
+  // listing is returned so the declared-size check below can reuse it.
+  const verbose = await rejectLinkEntries(tarballPath, { listingCap });
+
+  // 1c. PRE-extraction decompression-bomb check: refuse an archive whose
+  //     declared uncompressed total exceeds the budget, using the sizes from
+  //     the listing we already parsed. This fails before a single byte is
+  //     written, complementing the post-extraction re-measure in step 5.
+  const declared = sumDeclaredSizes(verbose);
+  if (declared.total > declaredSizeCap) {
+    throw new InstallerError(
+      `Refusing to extract tarball: declared uncompressed size ${declared.total} bytes ` +
+        `exceeds the safety budget (${declaredSizeCap} bytes).`,
+    );
+  }
+
   // 4. Now extract safely — the content has been validated above.
+  fs.mkdirSync(absoluteDest, { recursive: true });
   await runCommand('tar', ['-xzf', tarballPath, '-C', absoluteDest, '--strip-components=1']);
 
   // 5. Decompression-bomb guard (mirrors scripts/install.py). ``tar`` itself
@@ -1095,8 +1319,10 @@ function buildPythonInstallArgs(options) {
  *
  * Kept as a pure function (exported) so the flag surface — including the
  * skill-only ``--no-cli`` switch — can be unit-tested without spawning the
- * full download-and-install pipeline. ``process.exit`` is only reached for
- * hard argument errors (e.g. a value-consuming flag missing its value).
+ * full download-and-install pipeline. Hard argument errors (a value-consuming
+ * flag missing its value, an unknown option) THROW an ``InstallerError`` for
+ * the CLI boundary to report; library code must never call ``process.exit``
+ * (which would skip the caller's cleanup/flush and is untestable in-process).
  */
 function parseArgs(argv) {
   const options = {
@@ -1134,16 +1360,14 @@ function parseArgs(argv) {
     switch (arg) {
       case '--ai':
         if (!next || next.startsWith('-')) {
-          console.error('Error: --ai requires a value (a flag was found instead)');
-          process.exit(1);
+          throw new InstallerError('--ai requires a value (a flag was found instead)');
         }
         options.ai = next;
         i++;
         break;
       case '--target':
         if (!next || next.startsWith('-')) {
-          console.error('Error: --target requires a value (a flag was found instead)');
-          process.exit(1);
+          throw new InstallerError('--target requires a value (a flag was found instead)');
         }
         if (options.globalExplicit) {
           warning('--target overrides --global: installing into the project directory instead.');
@@ -1171,16 +1395,14 @@ function parseArgs(argv) {
         break;
       case '--token':
         if (!next || next.startsWith('-')) {
-          console.error('Error: --token requires a value (a flag was found instead)');
-          process.exit(1);
+          throw new InstallerError('--token requires a value (a flag was found instead)');
         }
         options.token = normalizeToken(next);
         i++;
         break;
       default:
         if (arg.startsWith('-')) {
-          console.error(`Error: unknown option ${arg}`);
-          process.exit(1);
+          throw new InstallerError(`unknown option ${arg}`);
         }
         // A bare positional argument is not a valid installer flag; warn so a
         // typo like "npx iterate-skill-installer trae" is not silently ignored.
@@ -1252,20 +1474,27 @@ async function main(options = {}) {
     hint('Retry, or set GITHUB_TOKEN if this is a rate-limit artefact.');
     return 1;
   }
-  // Announce releases that carry the tarball but not the checksum pair: they
-  // are skipped, which silently installs an OLDER release when the newest one
-  // is mid-upload. Saying so out loud keeps "installed an old version" visible.
+  // Announce releases that carry the tarball but not the checksum/signature
+  // pair: they are skipped, which silently installs an OLDER release when the
+  // newest one is mid-upload. Saying so out loud keeps "installed an old
+  // version" visible.
   for (const candidate of releases) {
     if (!candidate || candidate.draft || candidate.prerelease) continue;
     const assets = Array.isArray(candidate.assets) ? candidate.assets : [];
     const hasTarball = assets.some((a) => a && a.name === TARBALL_ASSET_NAME);
-    const hasChecksums = assets.some((a) => a && a.name === CHECKSUMS_ASSET_NAME);
-    if (hasTarball && !hasChecksums) {
+    const missing = [];
+    if (!assets.some((a) => a && a.name === CHECKSUMS_ASSET_NAME)) missing.push(CHECKSUMS_ASSET_NAME);
+    if (!assets.some((a) => a && a.name === TARBALL_SIGNATURE_ASSET_NAME)) missing.push(TARBALL_SIGNATURE_ASSET_NAME);
+    if (hasTarball && missing.length > 0) {
       warning(
-        `Skipping release ${candidate.tag_name}: has ${TARBALL_ASSET_NAME} but no ${CHECKSUMS_ASSET_NAME}.`,
+        `Skipping release ${candidate.tag_name}: has ${TARBALL_ASSET_NAME} but no ${missing.join(' / ')}.`,
       );
     }
   }
+  // A usable release must carry the tarball, its checksums AND its detached
+  // signature: the signature is mandatory at install time (see
+  // signaturePolicyError), so selecting a release without one would only turn
+  // "found the latest" into "failed to install".
   const release = releases.find(
     (r) =>
       r &&
@@ -1273,12 +1502,14 @@ async function main(options = {}) {
       !r.prerelease &&
       Array.isArray(r.assets) &&
       r.assets.some((a) => a && a.name === TARBALL_ASSET_NAME) &&
-      r.assets.some((a) => a && a.name === CHECKSUMS_ASSET_NAME),
+      r.assets.some((a) => a && a.name === CHECKSUMS_ASSET_NAME) &&
+      r.assets.some((a) => a && a.name === TARBALL_SIGNATURE_ASSET_NAME),
   );
 
   if (!release) {
     error(
-      `No published release in the last 100 carries a ${TARBALL_ASSET_NAME} + ${CHECKSUMS_ASSET_NAME} asset pair.`
+      `No published release in the last 100 carries a ${TARBALL_ASSET_NAME} + ` +
+        `${CHECKSUMS_ASSET_NAME} + ${TARBALL_SIGNATURE_ASSET_NAME} asset triple.`
     );
     hint('This is usually a GitHub API rate limit; retry with GITHUB_TOKEN set.');
     return 1;
@@ -1306,7 +1537,7 @@ async function main(options = {}) {
     return 1;
   }
 
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'iterate-skill-install-'));
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ig-install-'));
   const tarballPath = path.join(tmpDir, TARBALL_ASSET_NAME);
   const checksumPath = path.join(tmpDir, CHECKSUMS_ASSET_NAME);
 
@@ -1338,16 +1569,8 @@ async function main(options = {}) {
       return 1;
     }
     const actualHash = await sha256File(tarballPath);
-    // Constant-time compare (timingSafeEqual): the expected hash travels
-    // over the network with the tarball, so an early-exit string inequality
-    // would leak prefix information usable to forge a checksum. The length
-    // guard keeps timingSafeEqual from throwing on mismatched lengths.
-    const actualBuf = Buffer.from(actualHash.toLowerCase(), 'utf8');
-    const expectedBuf = Buffer.from(expectedHash.toLowerCase(), 'utf8');
-    const hashMatches =
-      actualBuf.length === expectedBuf.length &&
-      actualBuf.length > 0 &&
-      crypto.timingSafeEqual(actualBuf, expectedBuf);
+    // Constant-time, case-insensitive compare (see constantTimeHashEqual).
+    const hashMatches = constantTimeHashEqual(actualHash, expectedHash);
     if (!hashMatches) {
       error('Checksum mismatch — refusing to install.');
       return 1;
@@ -1358,19 +1581,17 @@ async function main(options = {}) {
       `\x1b[32m✓\x1b[0m SHA256 checksum verified`,
     ]);
 
-    // GPG authenticity check (defense-in-depth, fail-closed when it runs). The
-    // release also publishes a detached ASCII-armored signature over the
-    // tarball. When a `gpg` binary is present we verify it against the embedded
-    // signing key: a *valid* signature upgrades the release from
-    // "integrity-guaranteed" to "authenticity-guaranteed". If gpg is
-    // unavailable we degrade to a warning (SHA256 already guards integrity —
-    // that check still stands on its own).
+    // GPG authenticity check — MANDATORY (see signaturePolicyError).
     //
-    // If gpg IS present and the signature is present but does NOT verify, the
-    // install now FAILS. SHA256SUMS travels in the same release as the tarball,
-    // so an attacker who can replace one can replace both; the pinned public
-    // key is the single anchor they cannot forge. Reporting "signature
-    // invalid" and installing anyway made that anchor decorative.
+    // SHA256SUMS.txt travels in the SAME release as the tarball, so an attacker
+    // who can replace one can replace both; the pinned public key below is the
+    // only anchor they cannot forge. A missing `.asc`, a host without `gpg`, an
+    // unfetchable signature, or a signature that does not verify all ABORT the
+    // install. The single documented escape hatch is ``ITERATE_ALLOW_UNSIGNED``
+    // (hosts without GnuPG) and it never bypasses a BAD signature.
+    let signatureStatus = null;
+    let signatureDetail = '';
+    let signatureDownloadError = null;
     if (signatureAsset) {
       const signaturePath = path.join(tmpDir, TARBALL_SIGNATURE_ASSET_NAME);
       try {
@@ -1378,30 +1599,28 @@ async function main(options = {}) {
           maxBytes: CHECKSUMS_MAX_BYTES,
         });
         const sig = verifyGpgDetachedSignature(tarballPath, signaturePath, ITERATE_SIGNING_PUBLIC_KEY, tmpDir);
-        if (sig.status === 'verified') {
-          success('GPG signature verified.');
-        } else if (sig.status === 'invalid') {
-          error(
-            `GPG signature verification FAILED (${sig.detail}) — refusing to install.\n` +
-              '  The tarball was signed with a key that does not match the pinned ' +
-              'iterate-skill signing key: this is either tampering or a key rotation ' +
-              'that this installer version does not know about. Report it before retrying.',
-          );
-          return 1;
-        } else {
-          warning(
-            `gpg not available (${sig.detail}); skipping signature check — SHA256 integrity still enforced.`
-          );
-        }
+        signatureStatus = sig.status;
+        signatureDetail = sig.detail;
       } catch (err) {
-        warning(`Could not download/verify the GPG signature (${err.message}); SHA256 integrity still enforced.`);
+        signatureDownloadError = err.message;
       }
-    } else {
-      // Say it out loud: a silent skip meant an operator could believe the
-      // signature layer ran on every install. SHA256 still guards integrity,
-      // but authenticity was NOT verified for this release.
+    }
+    const signatureError = signaturePolicyError({
+      hasSignatureAsset: Boolean(signatureAsset),
+      status: signatureStatus,
+      detail: signatureDetail,
+      downloadError: signatureDownloadError,
+    });
+    if (signatureError) {
+      error(signatureError);
+      return 1;
+    }
+    if (signatureStatus === 'verified') {
+      success('GPG signature verified.');
+    } else if (allowUnsigned()) {
       warning(
-        'Release publishes no GPG signature asset; authenticity check skipped (SHA256 integrity still enforced).',
+        `Signature NOT verified (${signatureDetail || 'no signature'}) but accepted because ` +
+          `${ALLOW_UNSIGNED_ENV} is set — SHA256 integrity only.`,
       );
     }
 
@@ -1484,12 +1703,19 @@ module.exports = {
   resolveInstallMode,
   askYesNo,
   parseChecksums,
+  constantTimeHashEqual,
   enforceDownloadedSize,
   extractTarball,
   rejectLinkEntries,
+  sumDeclaredSizes,
+  declaredEntrySize,
+  validateEntryNames,
   isGithubApiUrl,
   normalizeToken,
   validateTokenShape,
+  allowUnsigned,
+  signaturePolicyError,
+  ALLOW_UNSIGNED_ENV,
   buildAuthFlags,
   supportsCurlFailWithBody,
   // Executed under test for the timeout/null-exit-code hardening; retaining

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-skill-installer",
-  "version": "3.5.1",
+  "version": "3.5.3",
   "description": "One-command installer for iterate-skill across AI coding assistants",
   "main": "lib/installer.js",
   "files": [