@blamejs/exceptd-skills 0.12.11 → 0.12.15

package/lib/refresh-network.js

@@ -97,6 +97,10 @@ function getJson(url, timeoutMs) {
 function getBuffer(url, timeoutMs) {
   return new Promise((resolve, reject) => {
     const u = new URL(url);
+    const cap = (() => {
+      const env = parseInt(process.env.EXCEPTD_TARBALL_SIZE_CAP_BYTES, 10);
+      return Number.isFinite(env) && env > 0 ? env : 200 * 1024 * 1024;
+    })();
     const req = https.get({
       host: u.host, path: u.pathname + u.search,
       headers: { "User-Agent": "exceptd/refresh-network" },
@@ -107,7 +111,17 @@ function getBuffer(url, timeoutMs) {
         return reject(new Error(`HTTP ${res.statusCode} from ${url}`));
       }
       const chunks = [];
-      res.on("data", (c) => chunks.push(c));
+      let total = 0;
+      // v0.12.14 (audit F5): enforce streaming size cap so a hostile
+      // registry CDN can't stream gigabytes into RAM.
+      res.on("data", (c) => {
+        total += c.length;
+        if (total > cap) {
+          req.destroy(new Error(`tarball exceeds ${cap}-byte cap during streaming download`));
+          return;
+        }
+        chunks.push(c);
+      });
       res.on("end", () => resolve(Buffer.concat(chunks)));
     });
     req.on("timeout", () => req.destroy(new Error("timeout")));
@@ -125,6 +139,18 @@ function parseTar(buf) {
   const entries = [];
   let offset = 0;
   let pendingLongName = null;
+  // v0.12.12: tarballs from a compromised registry CDN could ship entries
+  // with `..`-bearing names targeting paths outside the install root. The
+  // immediate callers (verify-shipped-tarball.js + the network update path)
+  // do hash + signature checks before honoring entries, so this is
+  // defense-in-depth — drop the entry rather than handing a path-traversal
+  // string downstream.
+  const isSafeName = (n) => {
+    if (typeof n !== "string" || n.length === 0) return false;
+    // Reject absolute paths AND any segment that is exactly ".."
+    if (/^[\\/]/.test(n) || /^[A-Za-z]:[\\/]/.test(n)) return false;
+    return !n.split(/[\\/]/).some((seg) => seg === "..");
+  };
   while (offset + 512 <= buf.length) {
     const block = buf.subarray(offset, offset + 512);
     // empty block = end-of-archive marker
@@ -141,7 +167,9 @@ function parseTar(buf) {
     if (type === "L") {
       pendingLongName = buf.subarray(dataStart, dataEnd).toString("utf8").replace(/\0.*$/, "");
     } else if (type === "0" || type === "" || type === "\0") {
-      entries.push({ name, body: buf.subarray(dataStart, dataEnd) });
+      if (isSafeName(name)) {
+        entries.push({ name, body: buf.subarray(dataStart, dataEnd) });
+      }
     }
     // round up to 512
     offset = dataStart + Math.ceil(size / 512) * 512;
@@ -163,6 +191,36 @@ function verifyDetached(publicKeyObj, payload, sigB64) {
   } catch { return false; }
 }
 
+// v0.12.14 (audit F1, F7): CRLF/BOM normalization mirrors lib/verify.js's
+// normalize(). Duplicated here to keep refresh-network free of cross-module
+// runtime deps. ANY change here MUST be mirrored in lib/verify.js +
+// lib/sign.js — the three normalize() implementations form a byte-stability
+// contract.
+function normalizeSkillBytes(buf) {
+  let s = Buffer.isBuffer(buf) ? buf.toString("utf8") : String(buf);
+  if (s.length > 0 && s.charCodeAt(0) === 0xFEFF) s = s.slice(1);
+  return Buffer.from(s.replace(/\r\n/g, "\n"), "utf8");
+}
+
+// Manifest path validation. Mirrors lib/verify.js validateSkillPath().
+function validateManifestSkillPath(skillPath) {
+  if (typeof skillPath !== "string") throw new Error(`manifest skill.path must be a string, got ${typeof skillPath}`);
+  if (skillPath.includes("\\")) throw new Error(`manifest skill.path must use forward slashes: ${JSON.stringify(skillPath)}`);
+  if (!skillPath.startsWith("skills/")) throw new Error(`manifest skill.path must start with 'skills/': ${JSON.stringify(skillPath)}`);
+  if (skillPath.includes("..")) throw new Error(`manifest skill.path must not contain '..': ${JSON.stringify(skillPath)}`);
+  return skillPath;
+}
+
+// v0.12.14 (audit F5): tarball download size cap. A hostile registry CDN
+// could stream gigabytes; Node buffers chunks in RAM until OOM. Current
+// tarball is ~2 MB; 200 MB is generous defense-in-depth. Tunable via
+// EXCEPTD_TARBALL_SIZE_CAP_BYTES for future growth.
+const TARBALL_SIZE_CAP_BYTES_DEFAULT = 200 * 1024 * 1024;
+function tarballSizeCap() {
+  const env = parseInt(process.env.EXCEPTD_TARBALL_SIZE_CAP_BYTES, 10);
+  return Number.isFinite(env) && env > 0 ? env : TARBALL_SIZE_CAP_BYTES_DEFAULT;
+}
+
 async function main() {
   const opts = parseArgs(process.argv);
   const localPkg = JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf8"));
@@ -190,6 +248,8 @@ async function main() {
   const latestVersion = meta.version;
   const tarballUrl = meta.dist && meta.dist.tarball;
   const tarballShasum = meta.dist && meta.dist.shasum;
+  const tarballIntegrity = meta.dist && meta.dist.integrity; // SHA-512 SRI
+  const registrySignatures = Array.isArray(meta.dist && meta.dist.signatures) ? meta.dist.signatures : [];
   if (!tarballUrl) {
     emit({ ok: false, error: "registry metadata missing dist.tarball" }, opts.json);
     process.exitCode = 2; return;
@@ -226,6 +286,32 @@ async function main() {
     process.exitCode = 2; return;
   }
 
+  // v0.12.14 (audit F5): defense-in-depth tarball size cap.
+  const sizeCap = tarballSizeCap();
+  if (tgzBuf.length > sizeCap) {
+    emit({ ok: false, error: `tarball exceeds size cap: ${tgzBuf.length} bytes > ${sizeCap} (EXCEPTD_TARBALL_SIZE_CAP_BYTES)` }, opts.json);
+    process.exitCode = 4; return;
+  }
+
+  // v0.12.14 (audit F6, F3): verify SHA-512 SRI first (collision-resistant
+  // beyond SHA-1 reach), then SHA-1 shasum for compatibility, then dist.
+  // signatures[] (npm registry's Ed25519 signing key). Each layer is
+  // defense-in-depth — registry compromise that produces a SHA-1 collision
+  // doesn't trivially produce a SHA-512 collision; an attacker who breaks
+  // both still has to forge the npm-signing-key signature on the tarball.
+  if (tarballIntegrity && /^sha512-/.test(tarballIntegrity)) {
+    const expected = tarballIntegrity.slice("sha512-".length);
+    const actual = crypto.createHash("sha512").update(tgzBuf).digest("base64");
+    if (actual !== expected) {
+      emit({ ok: false, error: `tarball SHA-512 integrity mismatch: dist.integrity=${tarballIntegrity}, actual=sha512-${actual}` }, opts.json);
+      process.exitCode = 4; return;
+    }
+  } else if (tarballIntegrity) {
+    // Non-sha512 SRI (e.g. sha384) — emit a warning but accept; SHA-1 path
+    // below still gates.
+    progress(`note: dist.integrity present but not sha512: ${tarballIntegrity.slice(0, 40)}`, opts.json);
+  }
+
   // Verify shasum (registry-provided integrity).
   if (tarballShasum) {
     const actual = crypto.createHash("sha1").update(tgzBuf).digest("hex");
@@ -276,22 +362,51 @@ async function main() {
   try { tarballManifest = JSON.parse(tarballManifestEntry.body.toString("utf8")); }
   catch (e) { emit({ ok: false, error: `tarball manifest.json parse: ${e.message}` }, opts.json); process.exitCode = 4; return; }
 
+  // v0.12.14 (audit F1): the prior loop iterated `sk.id` + a fixed payload
+  // path `skills/<id>/SKILL.md`. Manifest entries actually expose `name` +
+  // `path` (a forward-slash relative path like `skills/<name>/skill.md`,
+  // lowercase). Result: the loop matched zero entries; `failures.length === 0`
+  // and `verifiedCount === 0` and the swap proceeded with `ok: true`. Every
+  // operator running `exceptd refresh --network` installed unverified bytes.
+  //
+  // Fixed shape mirrors lib/verify.js: iterate `manifest.skills[]` by
+  // `name` + `path` + `signature`. Apply the same CRLF/BOM normalization
+  // before verify (lib/verify.js normalize() — duplicated here to keep
+  // this path free of cross-module runtime deps). validateSkillPath()
+  // is also mirrored to defend against path traversal in a tampered
+  // tarball manifest before we resolve the path against the extracted
+  // tree.
   const localKeyObj = crypto.createPublicKey(localPubKeyText);
   const skills = Array.isArray(tarballManifest.skills) ? tarballManifest.skills : [];
   const failures = [];
   let verifiedCount = 0;
   for (const sk of skills) {
-    if (!sk || !sk.id || !sk.signature) continue;
-    // Find the skill payload entry. manifest convention: skills/<id>/SKILL.md
-    const payloadName = `skills/${sk.id}/SKILL.md`;
-    const payloadEntry = entries.find((e) => stripPkg(e.name) === payloadName);
-    if (!payloadEntry) { failures.push({ id: sk.id, reason: "payload not in tarball" }); continue; }
-    const ok = verifyDetached(localKeyObj, payloadEntry.body, sk.signature);
+    if (!sk || typeof sk.name !== "string" || typeof sk.signature !== "string") {
+      failures.push({ name: sk?.name || "(missing name)", reason: "manifest entry missing name or signature" });
+      continue;
+    }
+    let normalizedPath;
+    try { normalizedPath = validateManifestSkillPath(sk.path); }
+    catch (e) { failures.push({ name: sk.name, reason: `manifest path rejected: ${e.message}` }); continue; }
+    const payloadEntry = entries.find((e) => stripPkg(e.name) === normalizedPath);
+    if (!payloadEntry) { failures.push({ name: sk.name, reason: `payload missing from tarball: ${normalizedPath}` }); continue; }
+    const normalized = normalizeSkillBytes(payloadEntry.body);
+    const ok = verifyDetached(localKeyObj, normalized, sk.signature);
     if (ok) verifiedCount++;
-    else failures.push({ id: sk.id, reason: "signature did not verify against local public key" });
+    else failures.push({ name: sk.name, reason: "Ed25519 signature did not verify against local public key" });
   }
 
-  if (failures.length > 0) {
+  if (skills.length === 0) {
+    emit({
+      ok: false,
+      error: "tarball manifest.json declares zero skills — refusing to swap",
+      verified: 0,
+      total: 0,
+      hint: "A legitimate tarball must declare at least one skill. Treat this as a tarball-integrity failure.",
+    }, opts.json);
+    process.exitCode = 5; return;
+  }
+  if (verifiedCount !== skills.length || failures.length > 0) {
     emit({
       ok: false,
       error: `${failures.length}/${skills.length} skill signature(s) failed verification — refusing to swap`,
@@ -303,6 +418,34 @@ async function main() {
     process.exitCode = 5; return;
   }
 
+  // v0.12.14 (audit F2): the swap loop replaces `data/` + `manifest.json` +
+  // `manifest-snapshot.json` in addition to `skills/`. None of those files
+  // are covered by the per-skill Ed25519 signature (which signs only the
+  // skill body bytes). The only integrity check between the registry and
+  // those bytes is SHA-1 dist.shasum — collision-broken since 2017 and
+  // weaker than `npm install` itself which honors dist.integrity (SHA-512
+  // SRI) + dist.signatures (npm Ed25519 registry key) + dist.attestations
+  // (sigstore SLSA provenance).
+  //
+  // Defense-in-depth: refuse the swap if the manifest skills list doesn't
+  // exactly match the skill payload entries present in the tarball. A
+  // malicious tarball that drops/adds a skill outside the manifest no
+  // longer slips through.
+  const manifestSkillPaths = new Set(skills.map(s => validateManifestSkillPath(s.path)));
+  const tarballSkillPayloads = entries
+    .map(e => stripPkg(e.name))
+    .filter(name => /^skills\/[^/]+\/skill\.md$/.test(name));
+  for (const tp of tarballSkillPayloads) {
+    if (!manifestSkillPaths.has(tp)) {
+      emit({
+        ok: false,
+        error: `tarball ships skill payload not declared in manifest: ${tp} — refusing to swap`,
+        hint: "Tarball+manifest divergence. Report at https://github.com/blamejs/exceptd-skills/issues.",
+      }, opts.json);
+      process.exitCode = 5; return;
+    }
+  }
+
   if (opts.dryRun) {
     emit({
       ok: true,
@@ -316,9 +459,16 @@ async function main() {
     return;
   }
 
-  // Atomic swap: stage to a tmp dir under the install, then rename.
+  // v0.12.14 (audit F4): the prior swap loop renamed targets one-by-one,
+  // and a mid-loop failure left the install half-applied with no automatic
+  // rollback. New shape: rename all old targets into a single backup dir
+  // first (so the install is empty-of-old before any new content is moved
+  // in); then rename all new targets in; on failure, walk the backup dir
+  // in reverse and restore.
   const stageDir = fs.mkdtempSync(path.join(ROOT, ".refresh-network-"));
   let written = 0;
+  let backupDir = null;
+  const completedSteps = []; // [{kind: 'backup' | 'install', target}]
   try {
     for (const entry of entries) {
       const rel = stripPkg(entry.name);
@@ -333,19 +483,32 @@ async function main() {
       written++;
     }
 
-    // Replace targets.
-    const replaceList = ["data", "skills", "manifest.json", "manifest-snapshot.json"];
-    const backupDir = path.join(ROOT, `.refresh-network-backup-${Date.now()}`);
+    // v0.12.14 (audit F10): use PID + random suffix in the backup dir name
+    // so concurrent refresh-network invocations don't collide on the
+    // millisecond clock.
+    const backupSuffix = `${process.pid}-${crypto.randomBytes(4).toString("hex")}`;
+    backupDir = path.join(ROOT, `.refresh-network-backup-${Date.now()}-${backupSuffix}`);
     fs.mkdirSync(backupDir);
+    const replaceList = ["data", "skills", "manifest.json", "manifest-snapshot.json"];
+
+    // Phase A: move all existing targets to backupDir. After this loop
+    // completes, the install root has none of the replaced targets.
     for (const target of replaceList) {
-      const src = path.join(stageDir, target);
-      if (!fs.existsSync(src)) continue;
       const dst = path.join(ROOT, target);
       if (fs.existsSync(dst)) {
         fs.renameSync(dst, path.join(backupDir, target));
+        completedSteps.push({ kind: "backup", target });
       }
-      fs.renameSync(src, dst);
     }
+
+    // Phase B: move all new targets in from stage.
+    for (const target of replaceList) {
+      const src = path.join(stageDir, target);
+      if (!fs.existsSync(src)) continue;
+      fs.renameSync(src, path.join(ROOT, target));
+      completedSteps.push({ kind: "install", target });
+    }
+
     fs.rmSync(stageDir, { recursive: true, force: true });
     // Best-effort cleanup of backup dir — keep on disk for one cycle so
     // operators can manually roll back if something feels off.
@@ -357,11 +520,38 @@ async function main() {
       total_skills: skills.length,
       files_written: written,
       backup_dir: path.relative(ROOT, backupDir),
+      registry_signatures_present: registrySignatures.length,
       message: `refreshed catalog from v${localVersion} → v${latestVersion} (${verifiedCount}/${skills.length} signatures verified). Backup at ${path.relative(ROOT, backupDir)} — safe to remove after verifying the new run.`,
     }, opts.json);
   } catch (e) {
+    // v0.12.14 (audit F4): walk completedSteps in reverse to undo partial work.
+    const rollbackErrors = [];
+    for (const step of [...completedSteps].reverse()) {
+      try {
+        if (step.kind === "install") {
+          // Remove the newly-installed copy.
+          fs.rmSync(path.join(ROOT, step.target), { recursive: true, force: true });
+        } else if (step.kind === "backup" && backupDir) {
+          // Restore from backup.
+          const src = path.join(backupDir, step.target);
+          const dst = path.join(ROOT, step.target);
+          if (fs.existsSync(src)) fs.renameSync(src, dst);
+        }
+      } catch (re) {
+        rollbackErrors.push({ target: step.target, kind: step.kind, error: re.message });
+      }
+    }
     fs.rmSync(stageDir, { recursive: true, force: true });
-    emit({ ok: false, error: `swap failed mid-rename: ${e.message}`, hint: "If files are missing, restore from the backup dir at the install root, or reinstall with `npm install -g @blamejs/exceptd-skills`." }, opts.json);
+    emit({
+      ok: false,
+      error: `swap failed mid-rename: ${e.message}`,
+      rolled_back: rollbackErrors.length === 0,
+      rollback_errors: rollbackErrors,
+      backup_dir: backupDir ? path.relative(ROOT, backupDir) : null,
+      hint: rollbackErrors.length === 0
+        ? "Auto-rollback completed. Install state matches pre-refresh. Re-run `exceptd refresh --network` or `npm install -g @blamejs/exceptd-skills` to retry."
+        : "Auto-rollback partially failed. Restore manually from the backup dir at the install root, or reinstall with `npm install -g @blamejs/exceptd-skills`.",
+    }, opts.json);
     process.exitCode = 4;
   }
 }

package/lib/schemas/manifest.schema.json

@@ -82,6 +82,22 @@
           "type": "array",
           "items": { "type": "string", "minLength": 1 }
         },
+        "rfc_refs": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "cwe_refs": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "d3fend_refs": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "dlp_refs": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
         "last_threat_review": {
           "type": "string",
           "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"

package/lib/scoring.js

@@ -34,7 +34,62 @@ function score(cveId, catalog) {
   return entry.rwep_score;
 }
 
-function scoreCustom(factors) {
+/**
+ * E10: Validate an RWEP factor bag. Returns an array of warning strings
+ * for missing-but-defaultable fields and out-of-range values. Does NOT
+ * throw — operators wanting hard enforcement should treat a non-empty
+ * return as a failure themselves.
+ *
+ * Range expectations:
+ *   - cisa_kev, poc_available, ai_assisted_weapon, ai_discovered,
+ *     patch_available, live_patch_available, reboot_required: boolean
+ *     (or null, treated as false with a missing-field warning).
+ *   - active_exploitation: 'none' | 'unknown' | 'suspected' | 'confirmed'.
+ *   - blast_radius: integer in [0, 30] (clamped at the weight ceiling but
+ *     flagged when out-of-range — out-of-range usually means a unit error).
+ */
+function validateFactors(factors) {
+  const warnings = [];
+  if (!factors || typeof factors !== 'object') {
+    return ['factors: expected object, got ' + (factors === null ? 'null' : typeof factors)];
+  }
+  const boolFields = ['cisa_kev', 'poc_available', 'ai_assisted_weapon', 'ai_discovered',
+                      'patch_available', 'live_patch_available', 'reboot_required'];
+  for (const f of boolFields) {
+    if (factors[f] === undefined || factors[f] === null) {
+      warnings.push(`${f}: missing (treated as false; explicit value recommended)`);
+    } else if (typeof factors[f] !== 'boolean') {
+      warnings.push(`${f}: expected boolean, got ${typeof factors[f]} (${JSON.stringify(factors[f])})`);
+    }
+  }
+  const aeAllowed = ['none', 'unknown', 'suspected', 'confirmed'];
+  if (factors.active_exploitation === undefined || factors.active_exploitation === null) {
+    warnings.push("active_exploitation: missing (treated as 'none')");
+  } else if (!aeAllowed.includes(factors.active_exploitation)) {
+    warnings.push(`active_exploitation: expected one of ${aeAllowed.join(', ')}, got ${JSON.stringify(factors.active_exploitation)}`);
+  }
+  if (factors.blast_radius === undefined || factors.blast_radius === null) {
+    warnings.push('blast_radius: missing (treated as 0)');
+  } else if (typeof factors.blast_radius !== 'number' || Number.isNaN(factors.blast_radius)) {
+    warnings.push(`blast_radius: expected number, got ${typeof factors.blast_radius} (${JSON.stringify(factors.blast_radius)})`);
+  } else if (factors.blast_radius < 0 || factors.blast_radius > 30) {
+    warnings.push(`blast_radius: ${factors.blast_radius} out of expected range [0, 30] (clamped to weight ceiling, but the value usually indicates a unit-of-measure mistake)`);
+  }
+  return warnings;
+}
+
+/**
+ * scoreCustom — compute the RWEP for a factor bag. Returns a number
+ * (clamped to [0, 100]).
+ *
+ * Backward-compat note: this function has always returned a number;
+ * callers in lib/auto-discovery.js etc. rely on that. E10 surfaces
+ * warnings via the optional `opts.collectWarnings` flag — when true,
+ * scoreCustom returns `{ score, _scoring_warnings }` instead of a bare
+ * number. Operators wanting validation without the score can call
+ * `validateFactors(factors)` directly.
+ */
+function scoreCustom(factors, opts) {
   const {
     cisa_kev = false,
     poc_available = false,
@@ -44,8 +99,15 @@ function scoreCustom(factors) {
     blast_radius = 0,
     patch_available = false,
     live_patch_available = false,
-    reboot_required = false
-  } = factors;
+    reboot_required = false,
+    // v0.12.15 (audit J F9): the CVE catalog field is `patch_required_reboot`
+    // but scoreCustom historically expected `reboot_required`. validate()
+    // already aliases at the call site; accept either spelling here so a
+    // direct caller passing the catalog entry doesn't silently lose the
+    // reboot factor.
+    patch_required_reboot,
+  } = factors || {};
+  const rebootFactor = (reboot_required === true) || (patch_required_reboot === true);
 
   let score = 0;
   score += cisa_kev ? RWEP_WEIGHTS.cisa_kev : 0;
@@ -53,12 +115,26 @@ function scoreCustom(factors) {
   score += (ai_assisted_weapon || ai_discovered) ? RWEP_WEIGHTS.ai_factor : 0;
   score += active_exploitation === 'confirmed' ? RWEP_WEIGHTS.active_exploitation : 0;
   score += active_exploitation === 'suspected' ? Math.floor(RWEP_WEIGHTS.active_exploitation / 2) : 0;
-  score += Math.min(RWEP_WEIGHTS.blast_radius, blast_radius);
+  // v0.12.15 (audit J F1, F5): blast_radius numeric coercion must reject
+  // NaN, Infinity, and strings explicitly. The prior `typeof === 'number'`
+  // check passed NaN (which is `typeof === 'number'`) into `Math.min/max`
+  // which propagates NaN through the final clamp, defeating the [0,100]
+  // contract. Number.isFinite + Number() coercion catches all four classes:
+  // NaN, Infinity, undefined, stringified-number.
+  const brRaw = Number.isFinite(Number(blast_radius)) ? Number(blast_radius) : 0;
+  const brClamped = Math.max(0, Math.min(RWEP_WEIGHTS.blast_radius, brRaw));
+  score += brClamped;
   score += patch_available ? RWEP_WEIGHTS.patch_available : 0;
   score += live_patch_available ? RWEP_WEIGHTS.live_patch_available : 0;
-  score += reboot_required ? RWEP_WEIGHTS.reboot_required : 0;
+  score += rebootFactor ? RWEP_WEIGHTS.reboot_required : 0;
 
-  return Math.min(100, Math.max(0, score));
+  // v0.12.15 (audit J F1): defense-in-depth clamp against any unforeseen
+  // NaN production above (negative weight + Infinity + math edge case).
+  const clamped = Number.isFinite(score) ? Math.min(100, Math.max(0, score)) : 0;
+  if (opts && opts.collectWarnings) {
+    return { score: clamped, _scoring_warnings: validateFactors(factors) };
+  }
+  return clamped;
 }
 
 function timeline(rwepScore) {
@@ -146,4 +222,4 @@ function validate(catalog) {
   return errors;
 }
 
-module.exports = { score, scoreCustom, timeline, compare, validate, RWEP_WEIGHTS };
+module.exports = { score, scoreCustom, timeline, compare, validate, validateFactors, RWEP_WEIGHTS };

package/lib/sign.js

@@ -8,6 +8,22 @@
  * which is gitignored. The public key at keys/public.pem is tracked and used
  * by lib/verify.js for signature verification.
  *
+ * Byte-stability contract (must mirror lib/verify.js):
+ *   Skill content is normalized BEFORE the bytes are signed:
+ *     1. Strip a UTF-8 BOM (U+FEFF) if present.
+ *     2. Convert CRLF line endings to LF.
+ *   The same normalization runs in lib/verify.js. A skill file checked
+ *   out with core.autocrlf=true on Windows therefore signs to the SAME
+ *   signature as the LF copy on Linux CI — closing the regression class
+ *   that broke v0.11.x signatures across the Windows/CI line-ending
+ *   boundary. ANY change to normalize() requires the matching change in
+ *   lib/verify.js; round-trip stability is a hard contract.
+ *
+ * Manifest entries are also validated before iteration: skill.path must
+ * begin with "skills/" and must not contain ".." or backslashes (see
+ * validateSkillPath() below). Without this a tampered manifest could
+ * sign or verify arbitrary files outside the skills/ tree.
+ *
  * Signing ceremony:
  *   1. node lib/sign.js generate-keypair    — generate keypair (one time, per deployment)
  *   2. node lib/sign.js sign-all            — sign all skills (after any content change)
@@ -80,10 +96,20 @@ function generateKeypair({ rotate = false } = {}) {
 /**
  * Sign all skills in manifest.json using the private key.
  * Updates manifest.json with Ed25519 signatures.
+ *
+ * Each manifest entry's `path` is validated through validateSkillPath()
+ * BEFORE the file is read — a tampered manifest with an out-of-tree
+ * path will reject the whole run.
  */
 function signAll() {
   const privateKey = loadPrivateKey();
   const manifest = loadManifest();
+  // Validate every entry's path before doing any I/O. Reject the whole
+  // manifest on the first traversal attempt — we never want to sign
+  // half a manifest then exit non-zero with a partial mutation.
+  for (const skill of manifest.skills) {
+    validateSkillPath(skill.path);
+  }
   let signed = 0;
   let errors = 0;
 
@@ -103,7 +129,16 @@ function signAll() {
   }
 
   fs.writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
-  console.log(`\n[sign] ${signed} skills signed. ${errors} errors.`);
+
+  // S5: verdict line FIRST, fingerprint banner after. An operator
+  // scrolling output should not be able to see "fingerprint: SHA256..."
+  // and assume success when errors > 0.
+  if (errors > 0) {
+    console.error(`\n[sign] FAILED — ${signed} signed, ${errors} errors.`);
+  } else {
+    console.log(`\n[sign] ${signed} skills signed.`);
+  }
+  printFingerprintBanner();
 
   if (errors > 0) process.exit(1);
 }
@@ -118,6 +153,7 @@ function signOne(skillName) {
   const skill = manifest.skills.find(s => s.name === skillName);
   if (!skill) { console.error(`Skill not found: ${skillName}`); process.exit(1); }
 
+  validateSkillPath(skill.path);
   const skillPath = path.join(ROOT, skill.path);
   const content = fs.readFileSync(skillPath, 'utf8');
   skill.signature = signContent(content, privateKey);
@@ -126,12 +162,69 @@ function signOne(skillName) {
 
   fs.writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
   console.log(`[sign] Signed: ${skillName}`);
+  printFingerprintBanner();
 }
 
 // --- helpers ---
 
+/**
+ * Normalize skill content for byte-stable signing.
+ *
+ * Strips a leading UTF-8 BOM (U+FEFF) if present, then converts CRLF
+ * line endings to LF. lib/verify.js applies the exact same transform.
+ *
+ * Without this, a Windows checkout with core.autocrlf=true reads a
+ * skill with \r\n while CI reads the same skill with \n — same bytes
+ * on disk in git, different bytes in the working tree, different
+ * signature. v0.11.x shipped 0/38 verifies for exactly this reason.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+function normalize(content) {
+  let s = content;
+  if (s.length > 0 && s.charCodeAt(0) === 0xFEFF) s = s.slice(1);
+  return s.replace(/\r\n/g, '\n');
+}
+
+/**
+ * Validate a manifest skill.path entry to prevent path traversal.
+ *
+ *   skill.path MUST be a string.
+ *   skill.path MUST start with "skills/".
+ *   skill.path MUST NOT contain "..".
+ *   skill.path MUST NOT contain backslashes (POSIX-style forward slashes
+ *     only — manifest paths are not platform-specific).
+ *
+ * A tampered manifest with "../../../etc/passwd" or
+ * "skills/foo/../../.keys/private.pem" is refused; the whole run
+ * aborts before any file I/O.
+ *
+ * @param {string} skillPath
+ * @returns {string}
+ */
+function validateSkillPath(skillPath) {
+  if (typeof skillPath !== 'string') {
+    throw new Error(`[sign] manifest skill.path must be a string, got ${typeof skillPath}`);
+  }
+  // Backslash check runs BEFORE the prefix check so a Windows-style
+  // path ("skills\foo\skill.md") returns the clearer "use forward
+  // slashes" diagnostic, not the misleading "must start with skills/".
+  if (skillPath.includes('\\')) {
+    throw new Error(`[sign] manifest skill.path must use forward slashes, not backslashes: ${JSON.stringify(skillPath)}`);
+  }
+  if (!skillPath.startsWith('skills/')) {
+    throw new Error(`[sign] manifest skill.path must start with 'skills/': ${JSON.stringify(skillPath)}`);
+  }
+  if (skillPath.includes('..')) {
+    throw new Error(`[sign] manifest skill.path must not contain '..': ${JSON.stringify(skillPath)}`);
+  }
+  return skillPath;
+}
+
 function signContent(content, privateKey) {
-  const signature = crypto.sign(null, Buffer.from(content, 'utf8'), {
+  const normalized = normalize(content);
+  const signature = crypto.sign(null, Buffer.from(normalized, 'utf8'), {
     key: privateKey,
     dsaEncoding: 'ieee-p1363'
   });
@@ -151,6 +244,22 @@ function loadManifest() {
   return JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf8'));
 }
 
+function printFingerprintBanner() {
+  if (!fs.existsSync(PUBLIC_KEY_PATH)) return;
+  try {
+    const pem = fs.readFileSync(PUBLIC_KEY_PATH, 'utf8');
+    const keyObj = crypto.createPublicKey(pem);
+    const der = keyObj.export({ type: 'spki', format: 'der' });
+    const sha256 = 'SHA256:' + crypto.createHash('sha256').update(der).digest('base64');
+    const sha3_512 = 'SHA3-512:' + crypto.createHash('sha3-512').update(der).digest('base64');
+    console.log(`[sign] Public key: keys/public.pem`);
+    console.log(`[sign] ${sha256}`);
+    console.log(`[sign] ${sha3_512}`);
+  } catch (_) {
+    // Best-effort banner — never let a fingerprint failure poison the run.
+  }
+}
+
 // --- CLI ---
 
 if (require.main === module) {
@@ -194,4 +303,4 @@ Signing ceremony (first time):
   }
 }
 
-module.exports = { generateKeypair, signAll, signOne };
+module.exports = { generateKeypair, signAll, signOne, normalize, validateSkillPath };