@blamejs/exceptd-skills 0.12.22 → 0.12.24

package/lib/prefetch.js

@@ -18,11 +18,10 @@
  *   rfc/<doc-name>.json                               — IETF Datatracker doc record
  *   pins/<owner>__<repo>__releases.json               — MITRE GitHub releases listing
  *
- * K: the registered source names in SOURCES below are `rfc` and
- * `pins`. Earlier comments + --help text said `ietf` and `github`; an
- * operator running `--source ietf` or `--source github` would hit "unknown
- * source" because no such key exists. The names below are the canonical
- * ones consumed by --source filtering.
+ * The registered source names in SOURCES below are `rfc` and `pins`.
+ * `--source ietf` or `--source github` would hit "unknown source"
+ * because no such key exists. The names below are the canonical ones
+ * consumed by --source filtering.
  *
  * Usage:
  *   node lib/prefetch.js                  # fetch everything not fresh
@@ -237,7 +236,7 @@ async function withIndexLock(cacheDir, mutator) {
       // raised when the other process is mid-unlink). Treat both as
       // "lock held, back off" rather than a fatal error.
       if (e.code !== "EEXIST" && e.code !== "EPERM") throw e;
-      // T P1-1: PID-liveness check. Same pattern as withCatalogLock in
+      // PID-liveness check. Same pattern as withCatalogLock in
       // lib/refresh-external.js — read the lockfile's PID, probe with
       // process.kill(pid, 0); ESRCH → holder dead, reclaim immediately;
       // EPERM → holder alive (different user), keep waiting. The mtime
@@ -303,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}`;
 }
@@ -322,11 +407,12 @@ function isFresh(idx, source, id, maxAgeMs) {
 
 function authHeadersForSource(source) {
   if (source === "nvd" && process.env.NVD_API_KEY) return { apiKey: process.env.NVD_API_KEY };
-  // J: the registered source name for MITRE GitHub releases is
-  // `pins` (see SOURCES above). The prior check looked for `github`, so
-  // GITHUB_TOKEN never reached the per-request Authorization header and
-  // anonymous-rate-limited fetches were always used even when an operator
-  // had supplied a token. Accept both spellings so this is forgiving of
+  // The registered source name for MITRE GitHub releases is `pins`
+  // (see SOURCES above). Accept both `pins` and `github` so GITHUB_TOKEN
+  // reaches the per-request Authorization header regardless of which
+  // spelling the operator's automation uses; without this, anonymous
+  // rate-limited fetches happen even when a token is configured. Be
+  // forgiving of
   // the historical naming and the registered name.
   if ((source === "pins" || source === "github") && process.env.GITHUB_TOKEN) {
     return { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` };
@@ -415,14 +501,14 @@ async function prefetch(options = {}) {
         const dir = path.dirname(targetPath);
         if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
         const body = JSON.stringify(res.json, null, 2) + "\n";
-        // T P1-3: stage the payload to a same-volume tmp file BEFORE
-        // attempting to acquire the index lock. If withIndexLock fails
-        // (timeout after MAX_RETRIES), we want the partially-completed
-        // download discarded — not left on disk as an orphan payload
-        // with no index entry. Air-gap operators feed off `readCached`,
-        // which consults the index; an unindexed payload silently becomes
-        // junk taking cache space. Pattern: stage → lock → rename+index
-        // → release. The rename is atomic same-volume; if it fails inside
+        // Stage the payload to a same-volume tmp file BEFORE attempting
+        // to acquire the index lock. If withIndexLock fails (timeout
+        // after MAX_RETRIES), the partially-completed download must be
+        // discarded — not left on disk as an orphan payload with no
+        // index entry. Air-gap operators feed off `readCached`, which
+        // consults the index; an unindexed payload silently becomes junk
+        // taking cache space. Pattern: stage → lock → rename+index →
+        // release. The rename is atomic same-volume; if it fails inside
         // the lock we clean up the tmp file. If we never reach the rename
         // (lock acquisition throws), the tmp file is unlinked in the
         // catch block below.
@@ -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
@@ -520,12 +619,19 @@ function readCached(cacheDir, source, id, opts = {}) {
   const idx = loadIndex(cacheDir);
   const meta = idx.entries[entryKey(source, id)];
   if (!meta) return null;
-  // L: when `fetched_at` is missing / non-string / unparseable,
-  // `new Date(undefined).getTime()` is NaN and `NaN > maxAgeMs` is false —
+  // When `fetched_at` is missing / non-string / unparseable,
+  // `new Date(undefined).getTime()` is NaN and `NaN > maxAgeMs` is false,
   // so the cached entry would have been returned as if fresh. Treat any
   // 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

@@ -94,13 +94,17 @@ function parseArgs(argv) {
     else if (a.startsWith("--from-fixture=")) out.fromFixture = a.slice("--from-fixture=".length);
     else if (a === "--report-out") out.reportOut = argv[++i];
     else if (a.startsWith("--report-out=")) out.reportOut = a.slice("--report-out=".length);
-    // FF P1-3: previously only EXCEPTD_AIR_GAP=1 reached the GHSA/OSV source
-    // modules — the CLI flag was undocumented in parseArgs, so a downstream
-    // operator following the documented `--air-gap` path silently allowed
-    // network calls. Now the flag is honoured; env var still works as a
-    // fallback so existing automation isn't broken.
+    // Honour `--air-gap` here so it reaches the GHSA/OSV source modules.
+    // 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;
 }
 
@@ -656,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" };
   }
@@ -698,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;
@@ -726,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;
@@ -761,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;
@@ -795,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; }
@@ -852,13 +935,30 @@ function loadCtx(opts) {
     d3fendCatalog: JSON.parse(fs.readFileSync(ABS("data/d3fend-catalog.json"), "utf8")),
     fixtures: null,
     cacheDir: null,
-    // FF P1-3: thread --air-gap (or EXCEPTD_AIR_GAP=1) through to ctx.airGap
-    // so the GHSA + OSV source modules (lib/source-ghsa.js, lib/source-osv.js)
-    // can branch on ctx.airGap and refuse network egress. Pre-fix the GHSA/OSV
-    // sources only saw `ctx?.airGap` as undefined when the CLI flag was used.
+    // Thread --air-gap (or EXCEPTD_AIR_GAP=1) through to ctx.airGap so the
+    // 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);
@@ -878,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;
 }
@@ -949,15 +1124,15 @@ async function withCatalogLock(catalogPath, mutator) {
       // Windows the same race surfaces as EPERM (sharing-violation raised
       // when the holder is mid-unlink). Treat both as "lock held, back off."
       if (e.code !== "EEXIST" && e.code !== "EPERM") throw e;
-      // T P1-1: PID-liveness check before falling back to mtime. The
-      // lockfile already contains String(process.pid) of the holder; parse
-      // it and probe with `process.kill(pid, 0)`. ESRCH means the holder is
-      // dead — reclaim immediately rather than waiting STALE_LOCK_MS for
-      // the mtime gate to expire. EPERM (holder alive, different user) is
-      // treated as "alive, keep waiting." The mtime gate remains as a
-      // belt-and-suspenders for the case where the lockfile content is
-      // missing / malformed / belongs to a recycled PID. Matches the PID
-      // pattern in orchestrator/index.js _acquireWatchLock and
+      // PID-liveness check before falling back to mtime. The lockfile
+      // contains String(process.pid) of the holder; parse it and probe with
+      // `process.kill(pid, 0)`. ESRCH means the holder is dead — reclaim
+      // immediately rather than waiting STALE_LOCK_MS for the mtime gate
+      // to expire. EPERM (holder alive, different user) is treated as
+      // "alive, keep waiting." The mtime gate remains as a belt-and-
+      // suspenders for cases where the lockfile content is missing /
+      // malformed / belongs to a recycled PID. Matches the PID pattern in
+      // orchestrator/index.js _acquireWatchLock and
       // lib/playbook-runner.js pidAlive().
       let reclaimedByPid = false;
       try {
@@ -1291,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

@@ -418,27 +418,75 @@ async function main() {
   // re-bootstrap. Missing EXPECTED_FINGERPRINT file → warn-and-continue
   // (don't break existing installs whose tree predates the pin file).
   const expectedFingerprintPath = path.join(ROOT, "keys", "EXPECTED_FINGERPRINT");
+  if (fs.existsSync(expectedFingerprintPath) && process.env.KEYS_ROTATED === "1") {
+    process.emitWarning(
+      `EXPECTED_FINGERPRINT pin check skipped via KEYS_ROTATED=1 during refresh-network. ` +
+      `Update keys/EXPECTED_FINGERPRINT to lock the new pin once rotation completes.`,
+      { code: 'EXCEPTD_KEYS_ROTATED_OVERRIDE' }
+    );
+  }
   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 {
-      // KK P1-5: 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. Pre-fix the inline split-trim-find returned
-      // 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);
-      // v0.12.16 (codex P1 PR #11): `expectedFp` is read verbatim from
-      // keys/EXPECTED_FINGERPRINT (formatted as `SHA256:<base64>`), but
+      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 || 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)`,
+          pin_path: expectedFingerprintPath,
+          hint: "Re-save the pin file as UTF-8 (the loader accepts UTF-8-with-BOM). Refusing to swap on --network with an unparseable pin.",
+        }, opts.json);
+        process.exitCode = 5; return;
+      }
+      // The pin file is canonically formatted as `SHA256:<base64>`, but
       // `fingerprintPublicKey()` returns the raw base64 without the
       // `SHA256:` prefix. Comparing the two raw strings would refuse every
       // legitimate run unless KEYS_ROTATED=1 was set. Normalize by stripping
       // the prefix from the pin file before compare. lib/verify.js's
       // checkExpectedFingerprint() does the symmetric thing (adds the
       // prefix to localFp); either side works as long as one is canonical.
-      const expectedFpBase64 = expectedFp && expectedFp.startsWith("SHA256:")
+      const expectedFpBase64 = expectedFp.startsWith("SHA256:")
         ? expectedFp.slice("SHA256:".length)
         : expectedFp;
-      if (expectedFpBase64 && expectedFpBase64 !== localFp) {
+      if (expectedFpBase64 !== localFp) {
         emit({
           ok: false,
           error: `local keys/public.pem fingerprint diverges from keys/EXPECTED_FINGERPRINT pin`,
@@ -448,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.
@@ -687,13 +735,13 @@ if (require.main === module) {
 module.exports = {
   parseTar,
   fingerprintPublicKey,
-  // A: exported for tests/normalize-contract.test.js so the
-  // byte-stability contract can be asserted across all four normalize()
-  // implementations (lib/sign.js, lib/verify.js, lib/refresh-network.js,
+  // Exported for tests/normalize-contract.test.js so the byte-stability
+  // contract can be asserted across all four normalize() implementations
+  // (lib/sign.js, lib/verify.js, lib/refresh-network.js,
   // scripts/verify-shipped-tarball.js).
   normalizeSkillBytes,
-  // B + Q P1: exported for in-process tests of the refresh
-  // path's manifest envelope check.
+  // Exported for in-process tests of the refresh path's manifest envelope
+  // check.
   verifyTarballManifestSignature,
   canonicalManifestBytesForRefresh,
 };

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

@@ -88,7 +88,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": {