@blamejs/exceptd-skills 0.12.23 → 0.12.25

package/lib/prefetch.js

@@ -302,6 +302,92 @@ async function saveIndex(cacheDir, idx) {
   });
 }
 
+// Canonical bytes for _index.json signing. Mirrors the manifest-signing
+// contract (lib/sign.js + lib/verify.js canonicalManifestBytes): deep-sort
+// keys, JSON.stringify with no formatting overhead the verifier can drift
+// against. Any change here must be mirrored in verifyIndexSignature() below.
+// The signature covers the index AS PERSISTED — `index_signature` is
+// excluded from the canonical bytes (the signature cannot sign itself).
+function canonicalizeIndex(value) {
+  if (Array.isArray(value)) return value.map(canonicalizeIndex);
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      out[key] = canonicalizeIndex(value[key]);
+    }
+    return out;
+  }
+  return value;
+}
+function canonicalIndexBytes(idx) {
+  const clone = Object.assign({}, idx);
+  delete clone.index_signature;
+  return Buffer.from(JSON.stringify(canonicalizeIndex(clone)), "utf8");
+}
+
+// Sign _index.json with the Ed25519 private key (.keys/private.pem). The
+// signature is written as a sidecar `_index.json.sig` containing
+// { algorithm: "Ed25519", signature_base64, signed_at }. readCachedJson /
+// loadCtx --from-cache verify this against keys/public.pem.
+//
+// Behavior on missing private key: emit a warning and return; the cache is
+// left unsigned. Operators on connected hosts where prefetch runs without
+// the maintainer keypair will see this warning. The verify side treats a
+// missing sidecar as "unsigned cache" and refuses unless --force-stale.
+function signIndex(cacheDir) {
+  const privPath = path.join(ROOT, ".keys", "private.pem");
+  if (!fs.existsSync(privPath)) {
+    console.warn(
+      `[prefetch] WARN: .keys/private.pem absent — _index.json written unsigned. ` +
+      `Downstream consumers reading this cache via --from-cache will refuse it ` +
+      `unless they pass --force-stale.`
+    );
+    return { signed: false };
+  }
+  const indexPath = path.join(cacheDir, "_index.json");
+  if (!fs.existsSync(indexPath)) return { signed: false };
+  const idx = JSON.parse(fs.readFileSync(indexPath, "utf8"));
+  const bytes = canonicalIndexBytes(idx);
+  const privKey = crypto.createPrivateKey(fs.readFileSync(privPath, "utf8"));
+  const sig = crypto.sign(null, bytes, privKey);
+  const sidecar = {
+    algorithm: "Ed25519",
+    signature_base64: sig.toString("base64"),
+    signed_at: new Date().toISOString(),
+  };
+  writeFileAtomic(path.join(cacheDir, "_index.json.sig"), JSON.stringify(sidecar, null, 2) + "\n");
+  return { signed: true };
+}
+
+// Verify _index.json against its sidecar signature using keys/public.pem.
+// Returns { status: "valid" | "missing" | "invalid", reason? }. Callers
+// decide policy: typically refuse unless --force-stale on "missing" /
+// "invalid".
+function verifyIndexSignature(cacheDir) {
+  const indexPath = path.join(cacheDir, "_index.json");
+  const sigPath = path.join(cacheDir, "_index.json.sig");
+  if (!fs.existsSync(indexPath)) return { status: "missing", reason: "_index.json not present" };
+  if (!fs.existsSync(sigPath)) return { status: "missing", reason: "_index.json.sig not present (cache was prefetched without a signing key)" };
+  let sidecar;
+  try { sidecar = JSON.parse(fs.readFileSync(sigPath, "utf8")); }
+  catch (e) { return { status: "invalid", reason: `_index.json.sig parse: ${e.message}` }; }
+  if (!sidecar || sidecar.algorithm !== "Ed25519" || typeof sidecar.signature_base64 !== "string") {
+    return { status: "invalid", reason: "_index.json.sig missing algorithm or signature_base64" };
+  }
+  const pubPath = path.join(ROOT, "keys", "public.pem");
+  if (!fs.existsSync(pubPath)) return { status: "invalid", reason: "keys/public.pem absent — cannot verify cache signature" };
+  const idx = JSON.parse(fs.readFileSync(indexPath, "utf8"));
+  const bytes = canonicalIndexBytes(idx);
+  const pubKey = crypto.createPublicKey(fs.readFileSync(pubPath, "utf8"));
+  let sigBytes;
+  try { sigBytes = Buffer.from(sidecar.signature_base64, "base64"); }
+  catch (e) { return { status: "invalid", reason: `signature_base64 decode: ${e.message}` }; }
+  let ok = false;
+  try { ok = crypto.verify(null, bytes, pubKey, sigBytes); }
+  catch (e) { return { status: "invalid", reason: `crypto.verify threw: ${e.message}` }; }
+  return ok ? { status: "valid" } : { status: "invalid", reason: "Ed25519 signature did not verify against keys/public.pem" };
+}
+
 function entryKey(source, id) {
   return `${source}/${id}`;
 }
@@ -482,6 +568,19 @@ async function prefetch(options = {}) {
   // run's writes would be silently overwritten here at the end of our run.
   await saveIndex(opts.cacheDir, idx);
 
+  // Sign the freshly-written _index.json with the Ed25519 private key
+  // (.keys/private.pem). The signature is a sidecar `_index.json.sig`;
+  // consumers reading via --from-cache verify it against keys/public.pem
+  // before trusting any entry. If the private key is absent (typical on
+  // operator-side prefetch runs where the maintainer keypair isn't
+  // present), signIndex() warns-and-returns and the cache is left
+  // unsigned — downstream verify will then refuse it without --force-stale.
+  try {
+    signIndex(opts.cacheDir);
+  } catch (err) {
+    console.warn(`[prefetch] WARN: _index.json signing failed: ${err && err.message}; cache left unsigned.`);
+  }
+
   // Final summary is unconditional — --quiet suppresses per-entry chatter
   // (the noisy part) but the operator still needs one line confirming success.
   // Without this, --quiet + --no-network was zero output even on dry-run
@@ -526,6 +625,13 @@ function readCached(cacheDir, source, id, opts = {}) {
   // non-finite age as "no provenance, refuse" unless the caller explicitly
   // opted into allowStale.
   const ageMs = meta.fetched_at ? Date.now() - new Date(meta.fetched_at).getTime() : NaN;
+  // Future-dated `fetched_at` (ageMs < 0) is a poisoning signal: either the
+  // host clock jumped backwards mid-fetch, or an attacker rewrote the index
+  // to inflate apparent freshness past the maxAge gate. Either way the
+  // entry's provenance is no longer trustworthy. Treat as missing — refuse
+  // even when allowStale is set, because allowStale loosens the upper bound,
+  // not the lower one.
+  if (Number.isFinite(ageMs) && ageMs < 0) return null;
   if (!opts.allowStale) {
     if (!meta.fetched_at || !Number.isFinite(ageMs)) return null;
     if (ageMs > maxAgeMs) return null;
@@ -575,6 +681,13 @@ module.exports = {
   parseArgs,
   SOURCES,
   DEFAULT_CACHE,
+  // Ed25519 _index.json signing + verification. Exported so
+  // lib/refresh-external.js (which consumes --from-cache) can verify the
+  // sidecar before trusting any cached entry, and so test harnesses can
+  // exercise the signing path without running the full prefetch pipeline.
+  signIndex,
+  verifyIndexSignature,
+  canonicalIndexBytes,
   // v0.12.12 C2: exported for the concurrent-writer regression test.
   // Not part of the operator-facing API — internal contract for tests
   // that need to exercise the lockfile path without spawning the full

package/lib/refresh-external.js

@@ -98,7 +98,13 @@ function parseArgs(argv) {
     // EXCEPTD_AIR_GAP=1 still works as an env-var fallback so existing
     // automation isn't broken.
     else if (a === "--air-gap") out.airGap = true;
+    // `--force-stale` bypasses cache-freshness + cache-signature refusals.
+    // Required when the operator intentionally wants to consume a cache
+    // older than 7d or one that was prefetched without a signing keypair.
+    // EXCEPTD_FORCE_STALE=1 mirrors for non-interactive automation.
+    else if (a === "--force-stale") out.forceStale = true;
   }
+  if (process.env.EXCEPTD_FORCE_STALE === "1") out.forceStale = true;
   return out;
 }
 
@@ -654,16 +660,95 @@ const ALL_SOURCES = {
 // readCachedJson returns null on miss; callers report it as "unreachable"
 // for that entry rather than failing the whole source.
 
-function readCachedJson(cacheDir, source, id) {
+// sha256 of on-disk cache entries is recorded in _index.json at fetch time
+// but was never verified on consume. A coordinated tamper that rewrote
+// e.g. `.cache/upstream/kev/known_exploited_vulnerabilities.json` between
+// prefetch and refresh would silently feed false intelligence into the
+// applied catalog. We now recompute the sha256 inside readCachedJson and
+// refuse on mismatch.
+//
+// The sha256 stored at prefetch time is computed over JSON.stringify(payload)
+// — unindented. The on-disk bytes use JSON.stringify(payload, null, 2)+"\n",
+// so we round-trip parse and re-canonicalize to compute the comparable hash.
+function readCachedJson(cacheDir, source, id, opts) {
+  const forceStale = !!(opts && opts.forceStale);
   const safe = id.replace(/[^A-Za-z0-9._-]/g, "_");
   const p = path.join(cacheDir, source, `${safe}.json`);
   if (!fs.existsSync(p)) return null;
-  try { return JSON.parse(fs.readFileSync(p, "utf8")); }
+  let parsed;
+  try { parsed = JSON.parse(fs.readFileSync(p, "utf8")); }
   catch { return null; }
+  // Look up the index entry. If the index is absent or doesn't have an
+  // entry for this source/id, we cannot verify integrity — refuse rather
+  // than fail-open. The cache invariant is: every payload on disk has a
+  // signed entry in _index.json. `--force-stale` is the operator escape
+  // hatch for pre-v0.12.24 caches that lack the per-entry sha256 records;
+  // we proceed without integrity checking but emit a warning so the gap
+  // is visible in logs.
+  const indexPath = path.join(cacheDir, "_index.json");
+  if (!fs.existsSync(indexPath)) {
+    if (forceStale) {
+      process.emitWarning(
+        `cache-integrity: _index.json missing under ${cacheDir}; proceeding unverified (--force-stale)`,
+        { code: "EXCEPTD_CACHE_UNVERIFIED" },
+      );
+      return parsed;
+    }
+    const err = new Error(`cache-integrity: _index.json missing under ${cacheDir}; refusing to consume unindexed payload for ${source}/${id}`);
+    err._exceptd_cache_integrity = true;
+    err._exceptd_hint = true;
+    err._exceptd_exit_code = 4;
+    throw err;
+  }
+  let idx;
+  try { idx = JSON.parse(fs.readFileSync(indexPath, "utf8")); }
+  catch (e) {
+    if (forceStale) {
+      process.emitWarning(
+        `cache-integrity: _index.json parse failed (${e.message}); proceeding unverified (--force-stale)`,
+        { code: "EXCEPTD_CACHE_UNVERIFIED" },
+      );
+      return parsed;
+    }
+    const err = new Error(`cache-integrity: _index.json parse failed: ${e.message}`);
+    err._exceptd_cache_integrity = true;
+    err._exceptd_hint = true;
+    err._exceptd_exit_code = 4;
+    throw err;
+  }
+  const meta = idx && idx.entries && idx.entries[`${source}/${id}`];
+  if (!meta || typeof meta.sha256 !== "string") {
+    if (forceStale) {
+      process.emitWarning(
+        `cache-integrity: _index.json has no sha256 entry for ${source}/${id}; proceeding unverified (--force-stale)`,
+        { code: "EXCEPTD_CACHE_UNVERIFIED" },
+      );
+      return parsed;
+    }
+    const err = new Error(`cache-integrity: _index.json has no sha256 entry for ${source}/${id}; cache may have been tampered or partially populated`);
+    err._exceptd_cache_integrity = true;
+    err._exceptd_hint = true;
+    err._exceptd_exit_code = 4;
+    throw err;
+  }
+  const expected = meta.sha256;
+  const cryptoMod = require("crypto");
+  const actual = cryptoMod.createHash("sha256").update(JSON.stringify(parsed)).digest("hex");
+  if (expected !== actual) {
+    // sha256 mismatch is a hard tamper signal — `--force-stale` does NOT
+    // bypass it. An operator who knows the cache is stale can re-prefetch;
+    // an operator whose cache has been tampered should not proceed.
+    const err = new Error(`cache-integrity: sha256 mismatch for ${source}/${id} (expected ${expected.slice(0, 16)}..., got ${actual.slice(0, 16)}...)`);
+    err._exceptd_cache_integrity = true;
+    err._exceptd_hint = true;
+    err._exceptd_exit_code = 4;
+    throw err;
+  }
+  return parsed;
 }
 
 function kevDiffFromCache(ctx) {
-  const feed = readCachedJson(ctx.cacheDir, "kev", "known_exploited_vulnerabilities");
+  const feed = readCachedJson(ctx.cacheDir, "kev", "known_exploited_vulnerabilities", { forceStale: ctx.forceStale });
   if (!feed) {
     return { status: "unreachable", diffs: [], errors: 1, summary: "KEV: no cached feed" };
   }
@@ -696,7 +781,7 @@ function epssDiffFromCache(ctx) {
   let errors = 0;
   const drift = 0.05;
   for (const id of cves) {
-    const payload = readCachedJson(ctx.cacheDir, "epss", id);
+    const payload = readCachedJson(ctx.cacheDir, "epss", id, { forceStale: ctx.forceStale });
     if (!payload) { errors++; continue; }
     const row = (payload.data || []).find((r) => r?.cve === id) || (payload.data || [])[0];
     if (!row) continue;
@@ -724,7 +809,7 @@ function nvdDiffFromCache(ctx) {
   const diffs = [];
   let errors = 0;
   for (const id of cves) {
-    const payload = readCachedJson(ctx.cacheDir, "nvd", id);
+    const payload = readCachedJson(ctx.cacheDir, "nvd", id, { forceStale: ctx.forceStale });
     if (!payload) { errors++; continue; }
     const vuln = payload.vulnerabilities?.[0]?.cve;
     if (!vuln) continue;
@@ -759,7 +844,7 @@ function rfcDiffFromCache(ctx) {
     if (id.startsWith("RFC-")) docName = `rfc${id.slice(4)}`;
     else if (id.startsWith("DRAFT-")) docName = `draft-${id.slice(6).toLowerCase()}`;
     if (!docName) continue;
-    const payload = readCachedJson(ctx.cacheDir, "rfc", docName);
+    const payload = readCachedJson(ctx.cacheDir, "rfc", docName, { forceStale: ctx.forceStale });
     if (!payload) { errors++; continue; }
     const obj = payload.objects?.[0];
     if (!obj) continue;
@@ -793,7 +878,7 @@ function pinsDiffFromCache(ctx) {
   const diffs = [];
   let errors = 0;
   for (const [pinName, file] of Object.entries(PIN_REPOS)) {
-    const payload = readCachedJson(ctx.cacheDir, "pins", file);
+    const payload = readCachedJson(ctx.cacheDir, "pins", file, { forceStale: ctx.forceStale });
     if (!payload || !Array.isArray(payload)) { errors++; continue; }
     const stable = payload.find((r) => !r.draft && !r.prerelease);
     if (!stable) { errors++; continue; }
@@ -854,8 +939,26 @@ function loadCtx(opts) {
     // GHSA + OSV source modules (lib/source-ghsa.js, lib/source-osv.js)
     // branch on it and refuse network egress.
     airGap: !!(opts && opts.airGap) || process.env.EXCEPTD_AIR_GAP === "1",
+    // Thread --force-stale through so readCachedJson can downgrade cache-
+    // integrity refusals to warnings when an operator explicitly opts out.
+    forceStale: !!(opts && opts.forceStale),
   };
   if (opts.fromFixture) {
+    // `--from-fixture` injects frozen test payloads as if they were live
+    // upstream responses. Allowing this on an operator's host would let any
+    // caller forge KEV / NVD / EPSS / pin diffs into the applied catalog.
+    // Gate the flag behind EXCEPTD_TEST_HARNESS=1 so it only activates in
+    // explicit test contexts.
+    if (process.env.EXCEPTD_TEST_HARNESS !== "1") {
+      const err = new Error(
+        `refresh: --from-fixture is disabled outside the test harness.\n` +
+        `Hint: Set EXCEPTD_TEST_HARNESS=1 to use --from-fixture; this flag is intended for test harnesses only and would otherwise allow forged upstream payloads.`
+      );
+      err._exceptd_hint = true;
+      err._exceptd_exit_code = 4;
+      err._exceptd_error_code = "from-fixture-disabled";
+      throw err;
+    }
     ctx.fixtures = { dir: path.resolve(opts.fromFixture), kev: true, epss: true, nvd: true, rfc: true, pins: true, ghsa: true, osv: true };
   } else if (opts.fromCache) {
     const abs = path.resolve(opts.fromCache);
@@ -875,6 +978,81 @@ function loadCtx(opts) {
       err._exceptd_hint = true;
       throw err;
     }
+    // _index.json signature verification. The cache was signed at
+    // prefetch time with the Ed25519 private key. Refuse to consume any
+    // cache whose sidecar signature does not verify against keys/public.pem,
+    // unless the operator explicitly accepts the risk via --force-stale.
+    // A missing sidecar (cache prefetched on a host without the signing
+    // keypair) is treated identically: same refusal, same override.
+    try {
+      const { verifyIndexSignature } = require("./prefetch.js");
+      const sigResult = verifyIndexSignature(abs);
+      if (sigResult.status !== "valid" && !opts.forceStale) {
+        const err = new Error(
+          `refresh: --from-cache signature verification failed (${sigResult.status}): ${sigResult.reason || "(no reason)"}.\n` +
+          `Hint: The cache at ${abs} was prefetched without a signing key, or its _index.json / _index.json.sig was tampered. ` +
+          `Re-run \`exceptd prefetch\` on a host with .keys/private.pem, or pass --force-stale to consume the cache anyway.`
+        );
+        err._exceptd_hint = true;
+        err._exceptd_exit_code = 4;
+        err._exceptd_error_code = "cache-signature";
+        throw err;
+      }
+    } catch (e) {
+      if (e && e._exceptd_hint) throw e;
+      // Loader error (prefetch.js missing exports, etc.) — treat as a hard
+      // refusal rather than fail-open. Operators on --force-stale still
+      // pass through.
+      if (!opts.forceStale) {
+        const err = new Error(
+          `refresh: --from-cache signature verifier unavailable: ${e && e.message}.\n` +
+          `Hint: Pass --force-stale to consume the cache without signature verification, or reinstall the package.`
+        );
+        err._exceptd_hint = true;
+        err._exceptd_exit_code = 4;
+        err._exceptd_error_code = "cache-signature";
+        throw err;
+      }
+    }
+    // Max-age check. Cache entries whose freshest fetched_at is older
+    // than 7 days are refused outright; intel that stale is more likely
+    // to be misleading than helpful (KEV gains entries weekly; EPSS shifts
+    // daily). --force-stale overrides for genuine air-gap workflows.
+    try {
+      const idxPath = path.join(abs, "_index.json");
+      if (fs.existsSync(idxPath)) {
+        const idx = JSON.parse(fs.readFileSync(idxPath, "utf8"));
+        const entries = (idx && idx.entries) || {};
+        let maxFetchedMs = 0;
+        for (const k of Object.keys(entries)) {
+          const t = entries[k] && entries[k].fetched_at ? new Date(entries[k].fetched_at).getTime() : NaN;
+          if (Number.isFinite(t) && t > maxFetchedMs) maxFetchedMs = t;
+        }
+        if (maxFetchedMs > 0) {
+          const ageMs = Date.now() - maxFetchedMs;
+          const ageDays = ageMs / (24 * 3600 * 1000);
+          if (ageDays > 7 && !opts.forceStale) {
+            const err = new Error(
+              `refresh: --from-cache freshest entry is ${ageDays.toFixed(1)} days old (>7d cutoff).\n` +
+              `Hint: Re-run \`exceptd prefetch\` to refresh the cache, or pass --force-stale to consume it anyway.`
+            );
+            err._exceptd_hint = true;
+            err._exceptd_exit_code = 4;
+            err._exceptd_error_code = "cache-stale";
+            err._exceptd_max_age_days = Number(ageDays.toFixed(2));
+            err._exceptd_refresh_command = "exceptd prefetch";
+            throw err;
+          }
+        }
+      }
+    } catch (e) {
+      if (e && e._exceptd_hint) throw e;
+      // Index parse error — bubble up as a hint
+      const err = new Error(`refresh: --from-cache _index.json unreadable: ${e && e.message}`);
+      err._exceptd_hint = true;
+      err._exceptd_exit_code = 4;
+      throw err;
+    }
   }
   return ctx;
 }
@@ -1288,7 +1466,11 @@ if (require.main === module) {
     // v0.12.12 C3: exitCode + return rather than process.exit(2) — the
     // event loop has no further work after main()'s rejection, so this
     // ends the process with code 2 but lets stderr drain first.
-    process.exitCode = 2;
+    // Cache-integrity / cache-stale / from-fixture-disabled refusals carry
+    // an explicit exit code (4) via _exceptd_exit_code; honor that so
+    // downstream automation can distinguish "blocked by precondition"
+    // (exit 4) from "fatal/unhandled" (exit 2).
+    process.exitCode = (err && Number.isInteger(err._exceptd_exit_code)) ? err._exceptd_exit_code : 2;
   });
 }
 

package/lib/refresh-network.js

@@ -426,21 +426,48 @@ async function main() {
     );
   }
   if (fs.existsSync(expectedFingerprintPath) && !process.env.KEYS_ROTATED) {
+    // Route through the shared lib/verify loader so a BOM-prefixed pin
+    // file (Notepad with files.encoding=utf8bom) is tolerated identically
+    // across every verify site. An inline split-trim-find would retain
+    // the BOM as part of the first line, which would never match a live
+    // fingerprint and would block every legitimate refresh-network run.
+    //
+    // Narrowed try/catch: only swallow ENOENT / EACCES from the loader
+    // call (the pin file may have been deleted between existsSync and
+    // read, or be unreadable by the current uid — both are "warn and
+    // continue" cases). Any OTHER error (loader bug, unexpected throw)
+    // must NOT silently fall through to an unpinned refresh — the prior
+    // catch-all flow was a fail-open vector. The emit({ok:false,...}) +
+    // exitCode + return block is now OUTSIDE the catch so a parsing
+    // failure cannot be silently swallowed.
+    let expectedFp;
+    let loaderFailedSoftly = false;
     try {
-      // Route through the shared lib/verify loader so a BOM-prefixed pin
-      // file (Notepad with files.encoding=utf8bom) is tolerated identically
-      // across every verify site. An inline split-trim-find would retain
-      // the BOM as part of the first line, which would never match a live
-      // fingerprint and would block every legitimate refresh-network run.
       const { loadExpectedFingerprintFirstLine } = require("./verify.js");
-      const expectedFp = loadExpectedFingerprintFirstLine(expectedFingerprintPath);
+      expectedFp = loadExpectedFingerprintFirstLine(expectedFingerprintPath);
+    } catch (err) {
+      if (err && (err.code === "ENOENT" || err.code === "EACCES")) {
+        // Pin file unreadable (race with deletion / permission denied) —
+        // warn-and-continue is the original behavior for this class.
+        loaderFailedSoftly = true;
+      } else {
+        emit({
+          ok: false,
+          error: `keys/EXPECTED_FINGERPRINT loader threw unexpectedly: ${err && err.message}`,
+          pin_path: expectedFingerprintPath,
+          hint: "The pin file exists but the loader hit a non-IO error. Refusing to swap on --network; investigate the loader failure before retrying.",
+        }, opts.json);
+        process.exitCode = 5; return;
+      }
+    }
+    if (!loaderFailedSoftly) {
       // Pin file present but the loader returned null. The loader refuses
       // UTF-16LE / UTF-16BE pin files and any other shape that cannot be
       // safely decoded. Treat this as a hard fail: the operator placed a
       // pin file but the bytes are not consumable, so we must not fall
       // through to an unpinned refresh. Re-save the pin as UTF-8 (with or
       // without BOM) and retry.
-      if (expectedFp === null) {
+      if (expectedFp === null || expectedFp === undefined) {
         emit({
           ok: false,
           error: `keys/EXPECTED_FINGERPRINT exists but its bytes could not be parsed (likely UTF-16 BOM or non-UTF-8 encoding)`,
@@ -469,7 +496,7 @@ async function main() {
         }, opts.json);
         process.exitCode = 5; return;
       }
-    } catch { /* unreadable pin file = warn-and-continue */ }
+    }
   }
 
   // Verify every signed entry in the tarball manifest using the local key.

package/lib/schemas/cve-catalog.schema.json

@@ -13,6 +13,7 @@
     "cisa_kev",
     "poc_available",
     "ai_discovered",
+    "ai_assisted_weaponization",
     "active_exploitation",
     "affected",
     "affected_versions",
@@ -60,11 +61,31 @@
     "poc_available": { "type": "boolean" },
     "poc_description": { "type": "string" },
     "ai_discovered": {
-      "description": "Whether the vulnerability was discovered with AI assistance.",
-      "type": ["boolean", "string"]
+      "description": "Whether the vulnerability was discovered with AI assistance. Boolean-only — strings can mask tagging bugs in RWEP's truthy branching.",
+      "type": "boolean"
+    },
+    "ai_discovery_source": {
+      "description": "Provenance category for the AI-assisted discovery (or absence thereof). Paired with ai_discovered: a true value should be backed by one of vendor_research / bug_bounty_ai_augmented / academic_ai_fuzzing / threat_actor_ai_built; false values may use human_researcher or unknown.",
+      "type": "string",
+      "enum": [
+        "vendor_research",
+        "bug_bounty_ai_augmented",
+        "academic_ai_fuzzing",
+        "threat_actor_ai_built",
+        "human_researcher",
+        "unknown"
+      ]
+    },
+    "ai_discovery_date": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
+      "description": "ISO date of the AI-discovery event (typically disclosure date if discovery date is not separately published)."
     },
     "ai_discovery_notes": { "type": "string" },
-    "ai_assisted_weaponization": { "type": "boolean" },
+    "ai_assisted_weaponization": {
+      "type": "boolean",
+      "description": "Distinct from ai_discovered. ai_discovered=AI found the bug; ai_assisted_weaponization=AI was used in exploit development. The two fields are independent and BOTH are required so operators cannot conflate them."
+    },
     "ai_assisted_notes": { "type": "string" },
     "active_exploitation": {
       "type": "string",
@@ -88,7 +109,13 @@
     "live_patch_available": { "type": "boolean" },
     "live_patch_tools": {
       "type": "array",
-      "items": { "type": "string" }
+      "items": { "type": "string" },
+      "description": "Tools/mechanisms that apply a runtime live-patch WITHOUT restart (e.g. kpatch, ksplice, kgraft). Distinct from vendor_update_paths — a non-empty list here is what feeds the RWEP live_patch_available factor in lib/scoring.js."
+    },
+    "vendor_update_paths": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Vendor-supplied update mechanisms that require service restart / reboot (e.g. apt upgrade, dnf update, package-manager pins). Separate from live_patch_tools so the RWEP live_patch_available factor only fires when a true zero-downtime live-patch path exists."
     },
     "live_patch_notes": { "type": "string" },
     "framework_control_gaps": {

package/lib/schemas/playbook.schema.json

@@ -6,6 +6,57 @@
   "type": "object",
   "required": ["_meta", "domain", "phases", "directives"],
   "additionalProperties": false,
+  "allOf": [
+    {
+      "if": {
+        "type": "object",
+        "properties": {
+          "_meta": {
+            "type": "object",
+            "properties": { "air_gap_mode": { "const": true } },
+            "required": ["air_gap_mode"]
+          }
+        },
+        "required": ["_meta"]
+      },
+      "then": {
+        "description": "When _meta.air_gap_mode is true, every artifact whose source contains a network-call substring (https://, http://, gh api, gh release, curl, wget, fetch) MUST carry an air_gap_alternative. The runner refuses to use the network when --air-gap is set, so an artifact with no offline fallback cannot be collected and the run is incomplete.",
+        "type": "object",
+        "properties": {
+          "phases": {
+            "type": "object",
+            "properties": {
+              "look": {
+                "type": "object",
+                "properties": {
+                  "artifacts": {
+                    "type": "array",
+                    "items": {
+                      "anyOf": [
+                        {
+                          "not": {
+                            "type": "object",
+                            "properties": {
+                              "source": {
+                                "type": "string",
+                                "pattern": "(https://|http://|gh api|gh release|curl |wget |fetch )"
+                              }
+                            },
+                            "required": ["source"]
+                          }
+                        },
+                        { "required": ["air_gap_alternative"] }
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  ],
   "properties": {
 
     "_meta": {

package/lib/scoring.js

@@ -381,6 +381,46 @@ function validate(catalog) {
   return errors;
 }
 
+/**
+ * Strict CVSS 3.1 vector parse. Returns `{ ok, version, reason? }`.
+ *
+ * The CSAF 2.0 cvss_v3 score block requires a canonical CVSS 3.1 vector
+ * string. Strict validators (BSI CSAF Validator, ENISA dashboard) reject
+ * documents that emit a cvss_v3 block keyed off a malformed vector — the
+ * pre-fix permissive `^CVSS:(\d+\.\d+)/` regex let through 3.0 vectors,
+ * truncated metric sets, and unknown environmental-metric values, which
+ * downstream tooling then rejected wholesale.
+ *
+ * Required metric set (in order): AV / AC / PR / UI / S / C / I / A.
+ * Optional temporal metrics: E / RL / RC.
+ * Optional environmental metrics: CR / IR / AR / MAV / MAC / MPR / MUI /
+ *                                 MS / MC / MI / MA.
+ */
+// CVSS 3.0 and 3.1 share an identical vector grammar (metric set, value enums,
+// and metric order are the same; only the `CVSS:X.Y/` prefix differs). CSAF
+// 2.0 §3.2.4.3 accepts both versions in the cvss_v3 block. The strict regex
+// matches either prefix; the parser records which version the vector declared
+// so the emitter can stamp the right `version` field.
+const CVSS_3X_RE = /^CVSS:3\.[01]\/AV:[NALP]\/AC:[LH]\/PR:[NLH]\/UI:[NR]\/S:[UC]\/C:[NLH]\/I:[NLH]\/A:[NLH](\/E:[XUPFH])?(\/RL:[XOTWU])?(\/RC:[XURC])?(\/CR:[XLMH])?(\/IR:[XLMH])?(\/AR:[XLMH])?(\/MAV:[XNALP])?(\/MAC:[XLH])?(\/MPR:[XNLH])?(\/MUI:[XNR])?(\/MS:[XUC])?(\/MC:[XNLH])?(\/MI:[XNLH])?(\/MA:[XNLH])?$/;
+
+function parseCvss31Vector(v) {
+  if (typeof v !== 'string' || v.length === 0) {
+    return { ok: false, version: null, reason: 'cvss_vector is not a non-empty string' };
+  }
+  const versionMatch = v.match(/^CVSS:(\d+\.\d+)\//);
+  if (!versionMatch) {
+    return { ok: false, version: null, reason: 'cvss_vector does not start with a CVSS:X.Y/ version prefix' };
+  }
+  const version = versionMatch[1];
+  if (version !== '3.0' && version !== '3.1') {
+    return { ok: false, version, reason: `cvss_vector declares version ${version}; CSAF 2.0 cvss_v3 accepts 3.0 and 3.1 only. Backfill a CVSS 3.x vector against this CVE in the catalog, or wait for CSAF 2.1 (cvss_v4 support).` };
+  }
+  if (!CVSS_3X_RE.test(v)) {
+    return { ok: false, version, reason: 'cvss_vector does not match the strict CVSS 3.x grammar (missing/invalid mandatory metric, unknown metric value, or out-of-order metric)' };
+  }
+  return { ok: true, version };
+}
+
 module.exports = {
   score,
   scoreCustom,
@@ -389,6 +429,7 @@ module.exports = {
   validate,
   validateFactors,
   deriveRwepFromFactors,
+  parseCvss31Vector,
   RWEP_WEIGHTS,
   ACTIVE_EXPLOITATION_LADDER,
   RECOGNISED_FACTOR_KEYS,