@blamejs/exceptd-skills 0.18.6 → 0.18.8

package/scripts/check-version-tags.js

@@ -4,8 +4,17 @@
 /**
  * scripts/check-version-tags.js
  *
- * Refuses NEW version-stamped comments / filenames in the tracked
- * source tree. The authoritative version surfaces are:
+ * Refuses NEW version-stamped lines / filenames in the tracked source
+ * tree. "Line" is deliberate and broader than "comment": a 0.x version
+ * stamp is residue wherever a stranger reads it, which per the
+ * operator-facing-surface rules includes string literals that ship to
+ * operators — CLI `--help` text, error messages, and test descriptions —
+ * not just `//` comments. The scan therefore tests the WHOLE line, so a
+ * `version: '0.18.7'` data literal or a `--flag (v0.18.7)` help string
+ * counts the same as a `// v0.18.7` comment. Genuinely-load-bearing
+ * version references (real test fixtures, deprecation timelines) get the
+ * file added to COMMENT_EXEMPT below. The authoritative version surfaces
+ * are:
  *
  *   1. package.json / manifest.json `"version"` field
  *   2. CHANGELOG.md `## X.Y.Z` headings
@@ -22,7 +31,7 @@
  * compare against the baseline:
  *
  *   - Filename violations beyond baseline → fail.
- *   - Comment violations beyond baseline (in any file)        → fail.
+ *   - Line violations beyond baseline (in any file)           → fail.
  *   - Violations strictly within baseline                     → ok.
  *   - Violations below baseline (drift reduced)               → ok +
  *     suggestion to refresh the baseline.
@@ -106,7 +115,11 @@ function gitIgnoredSet(relPaths) {
 // Pattern: project version like `v0.13.22` or bare `0.13.22`. Matches
 // our pre-1.0 release range. External package versions like ATLAS
 // `v5.6.0` or CycloneDX `1.6` don't match because the major is 0.
-const VERSION_TAG_RE = /\bv?0\.\d+\.\d+\b/;
+// The dot/digit lookarounds keep an IPv4 octet run (e.g. `127.0.0.1`, whose
+// `0.0.1` tail would otherwise count as a version tag) and any longer
+// dotted-numeric sequence from registering — a release version is never
+// embedded inside a larger digit.digit run.
+const VERSION_TAG_RE = /(?<![\d.])v?0\.\d+\.\d+(?![\d.])/;
 
 // Phase residue patterns — broader than just version tags.
 const PHASE_RESIDUE_RES = [
@@ -135,7 +148,13 @@ function walk(dir, results = []) {
   return results;
 }
 
-function countCommentViolations(rel) {
+// Counts version-stamp lines in a file. Intentionally WHOLE-LINE, not
+// comment-only: a 0.x stamp inside a shipped string literal (CLI --help text,
+// an error message, a test description) is operator-readable residue just like
+// a `//` comment, so it counts the same. A file with a genuinely load-bearing
+// version literal (real test fixture, deprecation timeline) is exempted by path
+// in COMMENT_EXEMPT, not by narrowing the scan.
+function countLineViolations(rel) {
   if (COMMENT_EXEMPT.has(rel)) return 0;
   const ext = path.extname(rel);
   if (!SCAN_EXTS.has(ext)) return 0;
@@ -163,7 +182,7 @@ function scanCurrent() {
     // scanned — a new file about to be committed is what the gate guards.
     if (ignored.has(rel)) continue;
     if (FILENAME_VERSION_RE.test(rel)) filenameViolations.push(rel);
-    const n = countCommentViolations(rel);
+    const n = countLineViolations(rel);
     if (n > 0) byFile[rel] = n;
   }
   return { byFile, filenameViolations };
@@ -238,7 +257,7 @@ function main() {
         path: rel,
         baseline: prior,
         actual: n,
-        reason: `comment-level version-tag count grew from ${prior} to ${n} — describe the WHY of the current code, not the release that introduced it`,
+        reason: `version-tag line count grew from ${prior} to ${n} (counts stamps in comments, strings, and data) — describe the WHY of the current code, not the release that introduced it`,
       });
     }
   }
@@ -254,7 +273,7 @@ function main() {
         path: rel,
         baseline: 0,
         actual: n,
-        reason: `new file carries ${n} version-tag comment(s) — describe the WHY of the current code, not the release that introduced it`,
+        reason: `new file carries ${n} version-tag line(s) (counts stamps in comments, strings, and data) — describe the WHY of the current code, not the release that introduced it`,
       });
     }
   }

package/scripts/predeploy.js

@@ -422,7 +422,7 @@ function main() {
       ".\n"
   );
 
-  process.exit(failures.length > 0 ? 1 : 0);
+  process.exit(failures.length > 0 ? 1 : 0); // allow:process-exit-after-stdout-write — local-only gate runner; output is the human/CI summary written synchronously above, never a piped --json result channel
 }
 
 module.exports = { GATES };

package/scripts/refresh-manifest-snapshot.js

@@ -71,8 +71,18 @@ const commitOnly =
   argv.includes("--commit-only") ||
   process.env.EXCEPTD_SNAPSHOT_AUDIT_ACK === "1";
 
-if (fs.existsSync(SNAPSHOT_PATH) && !commitOnly) {
-  const current = fs.readFileSync(SNAPSHOT_PATH, "utf8");
+// Read the committed snapshot once and branch on the read RESULT rather than
+// an existsSync(SNAPSHOT_PATH)-then-readFileSync probe — the latter is a
+// check-then-use window (CodeQL js/file-system-race) where the existence the
+// guard decides on may not be the file it then reads. ENOENT IS the "no prior
+// snapshot, write a fresh one" signal.
+let current = null;
+try {
+  current = fs.readFileSync(SNAPSHOT_PATH, "utf8");
+} catch (e) {
+  if (e.code !== "ENOENT") throw e;
+}
+if (current !== null && !commitOnly) {
   // Normalise the _generated_at timestamp for comparison — that field
   // changes every run and shouldn't trigger the guard.
   const stripGenerated = (s) => s.replace(
@@ -80,7 +90,7 @@ if (fs.existsSync(SNAPSHOT_PATH) && !commitOnly) {
   );
   if (stripGenerated(current) === stripGenerated(newJson)) {
     console.log("[refresh-manifest-snapshot] snapshot unchanged — nothing to do.");
-    process.exit(0);
+    process.exit(0); // allow:process-exit-after-stdout-write — local snapshot-refresh tool; the status line above is human-read on a TTY, not a piped --json result channel
   }
   process.stderr.write(
     "[refresh-manifest-snapshot] REFUSING to overwrite manifest-snapshot.json — " +
@@ -90,7 +100,7 @@ if (fs.existsSync(SNAPSHOT_PATH) && !commitOnly) {
     "force a deliberate decision about removed skills / triggers / refs before " +
     "the baseline is rewritten.\n"
   );
-  process.exit(1);
+  process.exit(1); // allow:process-exit-after-stdout-write — local snapshot-refresh tool; the refusal note above goes to stderr on a TTY, not a piped --json result channel
 }
 
 fs.writeFileSync(SNAPSHOT_PATH, newJson, "utf8");

package/scripts/refresh-reverse-refs.js

@@ -222,7 +222,13 @@ function rebuildCatalog(cfg, manifest, cveCatalog) {
   }
 
   // Surface forward refs that point at catalog entries that don't exist.
-  // Not fatal here — that's a separate validation concern — but we report.
+  // Informational only — orphans never change the exit code (this script is
+  // unconditionally write-mode, exit 0 always; see the file header). The
+  // failing gates for the two signals this script can surface live
+  // elsewhere: orphan forward refs are hard-errored by lib/lint-skills.js
+  // ref-resolution ("<id> not present in data/<catalog>"), and reverse-field
+  // drift is hard-failed by tests/reverse-ref-drift.test.js. Do not wire
+  // this script itself as a "reverse refs clean?" check — it always passes.
   for (const id of index.keys()) {
     if (!seenIds.has(id)) orphans.push(id);
   }

package/scripts/refresh-sbom.js

@@ -338,7 +338,7 @@ function buildSbom() {
         version: pkg.version,
         description: pkg.description,
         licenses: [{ license: { id: 'Apache-2.0' } }],
-        purl: `pkg:npm/${pkg.name.replace('@', '%40')}@${pkg.version}`,
+        purl: `pkg:npm/${pkg.name.replace(/@/g, '%40')}@${pkg.version}`,
         // Bundle digest over every shipped file (see bundleDigest above
         // for the canonical-input rule). Operators can recompute this
         // from the per-file components[] list and compare without

package/scripts/release.js

@@ -413,7 +413,7 @@ function cmdWatch() {
     console.log("\nfailed checks (" + failed.length + "):");
     failed.forEach(function (c) { console.log("  ✗ " + c.name + "  " + (c.link || "")); });
     console.log("\nFix in code, push, then re-run: node scripts/release.js watch");
-    process.exit(3);
+    process.exit(3); // allow:process-exit-after-stdout-write — maintainer-run release orchestrator; the guidance line above is human-read on a TTY, not a piped result channel
   }
 
   // CodeQL SAST gate — a standing per-release step. An open, un-triaged CodeQL
@@ -432,7 +432,7 @@ function cmdWatch() {
     });
     console.log("\nFix real findings in code (push, let CodeQL re-scan) OR dismiss by-design FPs with a " +
       "written reason, then re-run: node scripts/release.js watch");
-    process.exit(3);
+    process.exit(3); // allow:process-exit-after-stdout-write — maintainer-run release orchestrator; the guidance line above is human-read on a TTY, not a piped result channel
   } else {
     _ok("zero open CodeQL alerts");
   }
@@ -445,7 +445,7 @@ function cmdWatch() {
       if (c) console.log("  - by " + c.author.login + ": " + c.body.split("\n")[0]);
     });
     console.log("\nFix in code, push, resolve the thread, then re-run: node scripts/release.js watch");
-    process.exit(3);
+    process.exit(3); // allow:process-exit-after-stdout-write — maintainer-run release orchestrator; the guidance line above is human-read on a TTY, not a piped result channel
   }
   _ok("zero unresolved review threads");
   console.log("\nnext: node scripts/release.js merge");

package/scripts/run-e2e-scenarios.js

@@ -252,16 +252,26 @@ function runScenario(scenarioPath) {
   }
 }
 
+// Select scenario directories under SCENARIO_DIR, optionally narrowed by a
+// filter. The filter is matched as a plain substring (String.includes), NOT
+// compiled with new RegExp: a regex built from a CLI argument is a regex-
+// injection / ReDoS vector, and scenario names are literal NN-name strings, so
+// substring selection is behavior-equivalent for every legitimate filter
+// (e.g. --filter=library-author). Returns sorted basenames.
+function selectScenarios(filterStr, dir = SCENARIO_DIR) {
+  return fs.readdirSync(dir)
+    .filter(d => /^\d+-/.test(d))
+    .filter(d => !filterStr || d.includes(filterStr))
+    .sort();
+}
+
 function main() {
   const filter = process.argv.find(a => a.startsWith("--filter="));
-  const filterRe = filter ? new RegExp(filter.slice("--filter=".length)) : null;
+  const filterStr = filter ? filter.slice("--filter=".length) : null;
   const json = process.argv.includes("--json");
 
-  const scenarios = fs.readdirSync(SCENARIO_DIR)
-    .filter(d => /^\d+-/.test(d))
-    .filter(d => !filterRe || filterRe.test(d))
-    .map(d => path.join(SCENARIO_DIR, d))
-    .sort();
+  const scenarios = selectScenarios(filterStr)
+    .map(d => path.join(SCENARIO_DIR, d));
 
   const results = [];
   for (const s of scenarios) {
@@ -293,9 +303,9 @@ function main() {
     process.stdout.write(`\n${passed.length}/${results.length} scenarios passed${failed.length ? `, ${failed.length} failed` : ""}${skipped.length ? `, ${skipped.length} skipped` : ""}.\n`);
   }
 
-  process.exit(failed.length === 0 ? 0 : 1);
+  process.exit(failed.length === 0 ? 0 : 1); // allow:process-exit-after-stdout-write — local e2e runner; the pass/fail summary above is human/CI-read on a TTY, not a piped --json result channel
 }
 
-module.exports = { evaluateScenario, diffExpect, tryParseJson, stderrBanFailures, runScenario, SCENARIO_DIR };
+module.exports = { evaluateScenario, diffExpect, tryParseJson, stderrBanFailures, runScenario, selectScenarios, SCENARIO_DIR };
 
 if (require.main === module) main();

package/scripts/validate-vendor-online.js

@@ -48,10 +48,10 @@ function parseArgs(argv) {
       process.stdout.write(
         "Usage: node scripts/validate-vendor-online.js [--timeout <ms>] [--json]\n"
       );
-      process.exit(0);
+      process.exit(0); // allow:process-exit-after-stdout-write — local vendor-check script; the usage line above is human-read on a TTY, not a piped --json result channel
     } else {
       process.stderr.write(`Unknown argument: ${a}\n`);
-      process.exit(2);
+      process.exit(2); // allow:process-exit-after-stdout-write — local vendor-check script; the error note goes to stderr on a TTY, not a piped --json result channel
     }
   }
   return out;
@@ -66,13 +66,39 @@ function rawUrlForPin(sourceRepo, commit, upstreamPath) {
   if (!m) return null;
   const [, owner, repo] = m;
   const cleanPath = String(upstreamPath || "").replace(/^\/+/, "");
+  // Validate every file-derived component before embedding it in the fetch URL,
+  // so a tampered _PROVENANCE.json cannot steer the request: owner/repo are
+  // GitHub-name-shaped, the commit is a hex git object id, and the path is a
+  // relative, traversal-free repo path. With the host a string literal, the
+  // fetch destination is fully constrained — not metadata-controlled.
+  if (!/^[A-Za-z0-9._-]+$/.test(owner) || !/^[A-Za-z0-9._-]+$/.test(repo)) return null;
+  if (!/^[0-9a-fA-F]{7,64}$/.test(String(commit || ""))) return null;
+  if (!/^[A-Za-z0-9._/-]+$/.test(cleanPath) || cleanPath.includes("..")) return null;
   return `https://raw.githubusercontent.com/${owner}/${repo}/${commit}/${cleanPath}`;
 }
 
 const MAX_REDIRECTS = 5;
 
+// Only GitHub-controlled hosts may be fetched. The initial URL is always a
+// raw.githubusercontent.com URL computed from the committed _PROVENANCE.json,
+// but redirects re-enter fetchBuffer with a server-supplied Location; pinning
+// the host to github.com / *.githubusercontent.com stops a redirect (or a
+// tampered provenance source_repo) from steering the fetch at an internal or
+// attacker-controlled address.
+const ALLOWED_FETCH_HOST = /(?:^|\.)githubusercontent\.com$|^github\.com$/;
+
+function assertAllowedHost(url) {
+  let host;
+  try { host = new URL(url).hostname.toLowerCase(); }
+  catch { throw new Error(`unparseable fetch URL: ${url}`); }
+  if (!ALLOWED_FETCH_HOST.test(host)) {
+    throw new Error(`refusing to fetch from non-allowlisted host: ${host}`);
+  }
+}
+
 function fetchBuffer(url, timeoutMs, redirectsLeft = MAX_REDIRECTS) {
   return new Promise((resolve, reject) => {
+    try { assertAllowedHost(url); } catch (e) { return reject(e); }
     const req = https.get(url, (res) => {
       // v0.12.14 (codex P2): cap redirect hops. A redirect loop (or a
       // hostile / mis-configured upstream that keeps returning 3xx with

package/scripts/verify-shipped-tarball.js

@@ -108,12 +108,48 @@ function verifyExtractedManifestSignature(manifest, publicKeyPem) {
   return ok ? { status: "valid" } : { status: "invalid", reason: "Ed25519 manifest signature did not verify against extracted public.pem" };
 }
 
+// Decide one skill entry's verification outcome. Pulled out as a pure
+// function so the missing-signature guard is unit-testable without
+// spawning `npm pack`. Mirrors lib/verify.js verifySkill()'s missing_sig
+// branch: a manifest skill entry MAY legally omit `signature` (it is not
+// in the schema's skillEntry.required set — a freshly-added skill, or one
+// skipped during a partial sign-all, leaves it absent while the manifest
+// envelope is still validly re-signed over that field-absent state). Such
+// an entry must be a STRUCTURED miss, not Buffer.from(undefined,'base64')
+// throwing a TypeError that the script body's catch re-throws as an
+// uncaught stack trace.
+//   { status: 'missing' }            — no Ed25519 signature in manifest
+//   { status: 'pass' }               — signature verified
+//   { status: 'fail' }               — signature did not verify
+//   { status: 'fail', reason: str }  — malformed base64 / verify threw
+function verifySkillSignatureOutcome(s, normalizedContent, pubKey) {
+  const cryptoMod = require("crypto");
+  if (typeof s.signature !== "string" || s.signature.length === 0) {
+    return { status: "missing" };
+  }
+  let sigBytes;
+  try {
+    sigBytes = Buffer.from(s.signature, "base64");
+  } catch (e) {
+    return { status: "fail", reason: `malformed base64 signature: ${e.message}` };
+  }
+  let ok = false;
+  try {
+    ok = cryptoMod.verify(null, normalizedContent, pubKey, sigBytes);
+  } catch (e) {
+    return { status: "fail", reason: `crypto.verify threw: ${e.message}` };
+  }
+  return ok ? { status: "pass" } : { status: "fail" };
+}
+
 // Exported so tests/normalize-contract.test.js can assert byte-identical
-// normalize() behavior across all four implementations.
+// normalize() behavior across all four implementations, and so the
+// missing-signature guard above is unit-testable.
 module.exports = {
   normalizeSkillBytes,
   verifyExtractedManifestSignature,
   canonicalManifestBytesForTarball,
+  verifySkillSignatureOutcome,
 };
 
 const ROOT = path.resolve(__dirname, "..");
@@ -156,8 +192,21 @@ try {
   }
   const tarballName = pack.stdout.trim().split(/\r?\n/).filter(Boolean).pop();
   const tarballPath = path.join(tmpRoot, tarballName);
-  if (!fs.existsSync(tarballPath)) fail(`expected tarball at ${tarballPath}, not found`, 2);
-  emit(`tarball: ${tarballPath} (${fs.statSync(tarballPath).size} bytes)`);
+  // Open the packed tarball once and fstat + read via the descriptor so the
+  // existence check, size report, and read all observe the same inode — no
+  // existsSync→statSync→readFileSync TOCTOU on the path.
+  let tgz;
+  try {
+    const fd = fs.openSync(tarballPath, "r");
+    try {
+      const st = fs.fstatSync(fd);
+      emit(`tarball: ${tarballPath} (${st.size} bytes)`);
+      tgz = Buffer.alloc(st.size);
+      fs.readSync(fd, tgz, 0, st.size, 0);
+    } finally { fs.closeSync(fd); }
+  } catch (e) {
+    fail(`expected tarball at ${tarballPath}: ${e.message}`, 2);
+  }
 
   // Extract via Node — bypasses GNU tar's "C:..." path quirk on Windows
   // where it interprets the colon as a remote-host separator.
@@ -165,7 +214,6 @@ try {
   fs.mkdirSync(extractDir, { recursive: true });
   const zlib = require("zlib");
   const { parseTar: parseTarSource } = require(path.join(ROOT, "lib", "refresh-network.js"));
-  const tgz = fs.readFileSync(tarballPath);
   const tarBuf = zlib.gunzipSync(tgz);
   const entries = parseTarSource(tarBuf);
   for (const e of entries) {
@@ -353,7 +401,17 @@ try {
     // pack. This is the recurring CRLF/line-ending-bypass class.
     const rawContent = fs.readFileSync(skillPath);
     const normalizedContent = normalizeSkillBytes(rawContent);
-    const ok = crypto.verify(null, normalizedContent, pubKey, Buffer.from(s.signature, "base64"));
+    const outcome = verifySkillSignatureOutcome(s, normalizedContent, pubKey);
+    // A skill entry that legally omits `signature` (not in the schema's
+    // required set) must be a STRUCTURED miss — not Buffer.from(undefined,
+    // 'base64') throwing a TypeError that the body's catch re-throws as an
+    // uncaught stack trace. Mirrors lib/verify.js verifySkill()'s missing_sig.
+    if (outcome.status === "missing") {
+      miss++;
+      failures.push(`${s.name}: no Ed25519 signature in manifest`);
+      continue;
+    }
+    const ok = outcome.status === "pass";
     if (ok) pass++;
     else {
       fail_count++;
@@ -372,7 +430,8 @@ try {
         srcSha = crypto.createHash("sha256").update(normalizeSkillBytes(srcContent)).digest("hex").slice(0, 16);
       }
       const equal = srcContent && rawContent.equals(srcContent) ? "equal" : "DIFFER";
-      failures.push(`${s.name}: signature did not verify (tarball size=${rawContent.length} sha-normalized=${tarSha}; source size=${srcSize} sha-normalized=${srcSha}; raw bytes ${equal})`);
+      const reasonSuffix = outcome.reason ? ` [${outcome.reason}]` : "";
+      failures.push(`${s.name}: signature did not verify${reasonSuffix} (tarball size=${rawContent.length} sha-normalized=${tarSha}; source size=${srcSize} sha-normalized=${srcSha}; raw bytes ${equal})`);
     }
   }
 

package/sources/validators/cve-validator.js

@@ -107,6 +107,11 @@ function extractNvdCvss(nvdJson) {
   return {
     score: up.baseScore,
     vector: up.vector,
+    // The DECLARED CVSS version (from cvssData.version / the metric bucket),
+    // independent of the vector string — NVD can carry a baseScore with a
+    // missing/empty vectorString, and the downgrade guard needs the version
+    // even then.
+    version: up.version,
     source: up.source,
   };
 }
@@ -170,6 +175,7 @@ async function validateCve(cveId, localEntry) {
   const fetched = {
     cvss_score: null,
     cvss_vector: null,
+    cvss_version: null,
     in_kev: null,
     kev_date: null,
     epss: null,
@@ -208,6 +214,7 @@ async function validateCve(cveId, localEntry) {
       if (cvss) {
         fetched.cvss_score = cvss.score;
         fetched.cvss_vector = cvss.vector;
+        fetched.cvss_version = cvss.version;
         fetched.sources.nvd = { reachable: true, found: true, source: cvss.source };
       } else {
         fetched.sources.nvd = { reachable: true, found: true, source: null, note: 'no cvss metrics in NVD response' };
@@ -276,7 +283,16 @@ async function validateCve(cveId, localEntry) {
   // suppression (lib/refresh-external.js nvdDiffFromCache) so the live and
   // cache refresh paths converge; a same-version re-score still flows through.
   const localCvssVersion = cvssVersionOf(local.cvss_vector);
-  const fetchedCvssVersion = cvssVersionOf(fetched.cvss_vector);
+  // Prefer the upstream metric's DECLARED version over deriving it from the
+  // vector string: NVD can return a baseScore with a missing/empty
+  // vectorString, and cvssVersionOf(null) is null — which would defeat the
+  // downgrade guard on the live path (a v2 score with no vector would surface
+  // as a drift over a curated v3.x) while the cache path, which uses the
+  // declared up.version, still suppressed it. Fall back to the vector only when
+  // the declared version is absent.
+  const fetchedCvssVersion = fetched.cvss_version != null
+    ? fetched.cvss_version
+    : cvssVersionOf(fetched.cvss_vector);
   const cvssIsDowngrade =
     fetchedCvssVersion != null && localCvssVersion != null && fetchedCvssVersion < localCvssVersion;
   if (cveFoundInNvd && !cvssIsDowngrade) {

package/vendor/blamejs/_PROVENANCE.json

@@ -57,8 +57,10 @@
       "vendored_path": "vendor/blamejs/codepoint-class.js",
       "vendored_sha256": "2be79cf25de87f46b608aec98ee790f4cf1035ffee48fe70ff082d3cf6f324ba",
       "upstream_path": "lib/codepoint-class.js",
-      "upstream_sha256_at_pin": "2be79cf25de87f46b608aec98ee790f4cf1035ffee48fe70ff082d3cf6f324ba",
-      "stripped": [],
+      "upstream_sha256_at_pin": "18bcf1e99d168845a41c34e351e2323951319d2054634ca5021b002093e0fc03",
+      "stripped": [
+        "`// allow:raw-byte-literal — …` lint-suppression markers on 12 inline comments (the raw-byte-literal codebase-pattern rule does not scan vendor/, so the marker prefix is dropped to `// …`; comment text otherwise preserved)"
+      ],
       "surface_preserved": [
         "BIDI_RE / C0_CTRL_RE / ZERO_WIDTH_RE / NULL_BYTE (classification regexes)",
         "BIDI_RE_G / C0_CTRL_RE_G / ZW_RE_G / NULL_RE_G (global strip regexes)",