@blamejs/exceptd-skills 0.18.6 → 0.18.7

package/lib/refresh-network.js

@@ -72,7 +72,12 @@ function progress(line, json) {
   process.stderr.write(`[refresh-network] ${line}\n`);
 }
 
-function getJson(url, timeoutMs) {
+// Cap the registry metadata read so a hostile/misconfigured endpoint can't
+// stream unbounded JSON into RAM (the /latest response is a few KB; 16 MB is
+// generous headroom). Symmetric with getBuffer's tarball streaming cap.
+const JSON_RESPONSE_CAP_BYTES = 16 * 1024 * 1024;
+
+function getJsonOnce(url, timeoutMs) {
   return new Promise((resolve, reject) => {
     const u = new URL(url);
     const req = https.get({
@@ -82,23 +87,64 @@ function getJson(url, timeoutMs) {
     }, (res) => {
       if (res.statusCode !== 200) {
         res.resume();
-        return reject(new Error(`HTTP ${res.statusCode} from ${url}`));
+        const e = new Error(`HTTP ${res.statusCode} from ${url}`);
+        e.statusCode = res.statusCode; // let withRetry's classifier retry 429/5xx
+        return reject(e);
       }
       const chunks = [];
-      res.on("data", (c) => chunks.push(c));
+      let total = 0;
+      res.on("data", (c) => {
+        total += c.length;
+        if (total > JSON_RESPONSE_CAP_BYTES) {
+          req.destroy(new Error(`registry response exceeds ${JSON_RESPONSE_CAP_BYTES}-byte cap`));
+          return;
+        }
+        chunks.push(c);
+      });
       res.on("end", () => {
         try { resolve(JSON.parse(Buffer.concat(chunks).toString("utf8"))); }
         catch (e) { reject(new Error(`parse: ${e.message}`)); }
       });
     });
-    req.on("timeout", () => req.destroy(new Error("timeout")));
+    req.on("timeout", () => { const te = new Error("timeout"); te.code = "ETIMEDOUT"; req.destroy(te); });
     req.on("error", reject);
   });
 }
 
-function getBuffer(url, timeoutMs) {
+// Adopt the vendored blamejs retry primitive: a transient registry failure
+// (HTTP 429/5xx, ECONNRESET/ETIMEDOUT family) is retried with exponential
+// backoff + jitter instead of aborting the whole --network refresh on the
+// first network hiccup. Permanent conditions (parse error, size-cap) carry no
+// statusCode/code, so the classifier does not retry them.
+function getJson(url, timeoutMs) {
+  // Lazy require: a parseTar-only consumer (scripts/verify-shipped-tarball.js)
+  // loads this module in a context where vendor/ may not be present, and it
+  // never calls getJson — so retry must not be a load-time dependency.
+  const { withRetry } = require("../vendor/blamejs/retry.js");
+  return withRetry(() => getJsonOnce(url, timeoutMs), { maxAttempts: 3, baseDelayMs: 100, maxDelayMs: 2000, jitterFactor: 0.5 });
+}
+
+// The tarball URL is taken from the registry metadata (or, under
+// EXCEPTD_REGISTRY_FIXTURE, a local fixture file), so it is not a hardcoded
+// constant the way the /latest metadata URL is. Pin its host to the npm
+// registry the metadata was queried from, so a tampered metadata response or
+// fixture cannot steer the fetch at an internal or attacker-controlled address.
+// Content trust still rests on the SHA-512/SRI + shasum + Ed25519 checks below;
+// this is fetch-destination defense-in-depth.
+const ALLOWED_TARBALL_HOST = /(?:^|\.)npmjs\.org$|(?:^|\.)npmjs\.com$/;
+
+// Exported for in-process tests of the fetch-destination guard.
+function isAllowedTarballHost(url) {
+  try { return ALLOWED_TARBALL_HOST.test(new URL(url).hostname.toLowerCase()); }
+  catch { return false; }
+}
+
+function getBufferOnce(url, timeoutMs) {
   return new Promise((resolve, reject) => {
     const u = new URL(url);
+    if (!isAllowedTarballHost(url)) {
+      return reject(new Error(`refusing to fetch tarball from non-allowlisted host: ${u.hostname}`));
+    }
     const cap = (() => {
       const env = parseInt(process.env.EXCEPTD_TARBALL_SIZE_CAP_BYTES, 10);
       return Number.isFinite(env) && env > 0 ? env : 200 * 1024 * 1024;
@@ -110,7 +156,9 @@ function getBuffer(url, timeoutMs) {
     }, (res) => {
       if (res.statusCode !== 200) {
         res.resume();
-        return reject(new Error(`HTTP ${res.statusCode} from ${url}`));
+        const e = new Error(`HTTP ${res.statusCode} from ${url}`);
+        e.statusCode = res.statusCode; // retryable 429/5xx via withRetry
+        return reject(e);
       }
       const chunks = [];
       let total = 0;
@@ -126,11 +174,19 @@ function getBuffer(url, timeoutMs) {
       });
       res.on("end", () => resolve(Buffer.concat(chunks)));
     });
-    req.on("timeout", () => req.destroy(new Error("timeout")));
+    req.on("timeout", () => { const te = new Error("timeout"); te.code = "ETIMEDOUT"; req.destroy(te); });
     req.on("error", reject);
   });
 }
 
+// Wrap the tarball fetch in the same vendored retry primitive (BJS-01). The
+// host-allowlist rejection + size-cap carry no statusCode/code, so a permanent
+// refusal is not retried; a transient 5xx / reset / timeout is.
+function getBuffer(url, timeoutMs) {
+  const { withRetry } = require("../vendor/blamejs/retry.js"); // lazy — see getJson
+  return withRetry(() => getBufferOnce(url, timeoutMs), { maxAttempts: 3, baseDelayMs: 100, maxDelayMs: 2000, jitterFactor: 0.5 });
+}
+
 /**
  * Parse a tar buffer (uncompressed) and return [{ name, body }] entries.
  * Tiny implementation — supports the GNU ustar variant npm produces.
@@ -193,6 +249,56 @@ function verifyDetached(publicKeyObj, payload, sigB64) {
   } catch { return false; }
 }
 
+// Pinned npm registry signing keys (https://registry.npmjs.org/-/npm/v1/keys).
+// The registry signs `<pkg>@<version>:<integrity>` with an ECDSA P-256
+// (secp256r1 / ecdsa-sha2-nistp256) key; `dist.signatures[]` carries the
+// keyid + base64 signature. These keys are pinned in-tree on purpose: fetching
+// them over the network would mean authenticating the metadata response with a
+// key obtained from the same untrusted channel, which is circular. They also
+// rotate rarely and out-of-band. Values are SPKI DER, base64-encoded.
+const NPM_REGISTRY_KEYS = Object.freeze({
+  "SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA":
+    "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE1Olb3zMAFFxXKHiIkQO5cJ3Yhl5i6UPp+IhuteBJbuHcA5UogKo0EWtlWwW6KSaKoTNEYL7JlCQiVnkhBktUgg==",
+  "SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U":
+    "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEY6Ya7W++7aUPzvMTrezH6Ycx3c+HOKYCcNGybJZSCJq/fd7Qa8uuAKtdIkUQtQiEKERhAmE5lMMJhP8OkDOa2g==",
+});
+
+// Verify the npm registry's signature over `<pkg>@<version>:<integrity>`.
+// Returns:
+//   { status: "valid", keyid }            — a pinned key verified the signature
+//   { status: "absent" }                  — no dist.signatures entries supplied
+//   { status: "unverifiable", reason }     — integrity missing (nothing to sign over)
+//   { status: "unknown-keyid", keyid }     — signature keyid is not a pinned npm key
+//   { status: "invalid", reason }          — a present, pinned-keyid signature did NOT verify
+//
+// The caller treats `valid` as an authenticity anchor over the WHOLE tarball
+// (including the unsigned data/ tree), `invalid`/`unknown-keyid` as a hard
+// refusal, and `absent`/`unverifiable` as warn-and-continue (so private or
+// pre-signing registries still work — the SHA-512/SHA-1 gates still apply).
+function verifyNpmRegistrySignature(pkg, version, integrity, signatures) {
+  if (!Array.isArray(signatures) || signatures.length === 0) return { status: "absent" };
+  if (typeof integrity !== "string" || integrity.length === 0) {
+    return { status: "unverifiable", reason: "dist.integrity missing — no canonical message to verify the registry signature over" };
+  }
+  const message = Buffer.from(`${pkg}@${version}:${integrity}`, "utf8");
+  for (const entry of signatures) {
+    if (!entry || typeof entry.keyid !== "string" || typeof entry.sig !== "string") continue;
+    const spkiB64 = NPM_REGISTRY_KEYS[entry.keyid];
+    if (!spkiB64) return { status: "unknown-keyid", keyid: entry.keyid };
+    let keyObj;
+    try {
+      keyObj = crypto.createPublicKey({ key: Buffer.from(spkiB64, "base64"), format: "der", type: "spki" });
+    } catch (e) {
+      return { status: "invalid", reason: `pinned npm key ${entry.keyid} failed to load: ${e.message}` };
+    }
+    let ok = false;
+    try { ok = crypto.verify("sha256", message, keyObj, Buffer.from(entry.sig, "base64")); }
+    catch (e) { return { status: "invalid", reason: `crypto.verify threw for keyid ${entry.keyid}: ${e.message}` }; }
+    if (ok) return { status: "valid", keyid: entry.keyid };
+  }
+  return { status: "invalid", reason: "no dist.signatures[] entry verified against the pinned npm registry key" };
+}
+
 // v0.12.14: 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 +
@@ -302,7 +408,7 @@ async function main() {
       // + dist.shasum, or just version to exercise the early-return path).
       meta = JSON.parse(fs.readFileSync(process.env.EXCEPTD_REGISTRY_FIXTURE, "utf8"));
     } else {
-      meta = await getJson(`https://registry.npmjs.org/${encodeURIComponent(PKG_NAME).replace("%40", "@").replace("%2F", "/")}/latest`, opts.timeoutMs);
+      meta = await getJson(`https://registry.npmjs.org/${encodeURIComponent(PKG_NAME).replace(/%40/g, "@").replace(/%2F/g, "/")}/latest`, opts.timeoutMs);
     }
   } catch (e) {
     emit({ ok: false, error: `registry unreachable: ${e.message}`, hint: "Network required. Air-gap workflow: run `exceptd refresh --prefetch` on a connected host, then `exceptd refresh --from-cache --apply` offline. Or set EXCEPTD_REGISTRY_FIXTURE for offline testing." }, opts.json);
@@ -357,12 +463,26 @@ async function main() {
     process.exitCode = 4; return;
   }
 
-  // v0.12.14: 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.
+  // Verify SHA-512 SRI first (collision-resistant beyond SHA-1 reach), then
+  // SHA-1 shasum for compatibility. Both are transport hashes drawn from the
+  // registry metadata response, so they only prove the downloaded tarball
+  // matches the hashes THAT RESPONSE declared — an attacker who can forge the
+  // metadata serves a tampered tarball plus matching SHA-512/SHA-1 and both
+  // pass. The npm registry's signature over `<pkg>@<version>:<integrity>`
+  // (verified further below, after the both-absent refusal) is the only layer
+  // an attacker forging the metadata cannot also forge, because it is made
+  // with npm's registry private key, which they do not hold.
+  //
+  // `integrityVerified` records whether at least one transport hash actually
+  // matched the downloaded bytes. The per-skill + manifest Ed25519 signatures
+  // below authenticate skills/ + manifest.json, but the swap loop ALSO
+  // replaces data/ and manifest-snapshot.json, which carry no per-content
+  // signature — a transport hash is their only integrity anchor. When the
+  // registry metadata supplies NEITHER dist.integrity (sha512 SRI) NOR a
+  // dist.shasum, both branches are skipped and those bytes would otherwise be
+  // swapped in with zero verification, so the both-absent case is refused
+  // below rather than falling through to an unauthenticated swap.
+  let integrityVerified = false;
   if (tarballIntegrity && /^sha512-/.test(tarballIntegrity)) {
     const expected = tarballIntegrity.slice("sha512-".length);
     const actual = crypto.createHash("sha512").update(tgzBuf).digest("base64");
@@ -370,9 +490,11 @@ async function main() {
       emit({ ok: false, error: `tarball SHA-512 integrity mismatch: dist.integrity=${tarballIntegrity}, actual=sha512-${actual}` }, opts.json);
       process.exitCode = 4; return;
     }
+    integrityVerified = true;
   } else if (tarballIntegrity) {
     // Non-sha512 SRI (e.g. sha384) — emit a warning but accept; SHA-1 path
-    // below still gates.
+    // below still gates. A non-sha512 SRI is not actually checked here, so it
+    // does not count toward integrityVerified.
     progress(`note: dist.integrity present but not sha512: ${tarballIntegrity.slice(0, 40)}`, opts.json);
   }
 
@@ -383,6 +505,51 @@ async function main() {
       emit({ ok: false, error: `tarball shasum mismatch: expected ${tarballShasum}, got ${actual}` }, opts.json);
       process.exitCode = 4; return;
     }
+    integrityVerified = true;
+  }
+
+  // Refuse the swap when no transport hash was verifiable. data/ and
+  // manifest-snapshot.json have no per-content signature, so absent both
+  // dist.integrity and dist.shasum there is no integrity anchor on those bytes
+  // and a tampered registry response (or a hostile EXCEPTD_REGISTRY_FIXTURE)
+  // could inject arbitrary catalog/playbook/index content. `npm update -g`
+  // runs the full provenance-verified path (sha512 SRI + npm Ed25519 registry
+  // signatures + sigstore attestations), so it is the correct fallback.
+  if (!integrityVerified) {
+    emit({
+      ok: false,
+      error: "registry metadata carries no verifiable transport integrity (dist.integrity sha512 SRI and dist.shasum both absent) — refusing to swap unsigned data/ + manifest-snapshot.json",
+      hint: "data/ and manifest-snapshot.json are not covered by the per-skill or manifest Ed25519 signature; a transport hash is their only integrity anchor. Run `npm update -g @blamejs/exceptd-skills` for the full provenance-verified path.",
+    }, opts.json);
+    process.exitCode = 4; return;
+  }
+
+  // Verify the npm registry's signature over `<pkg>@<version>:<integrity>`.
+  // This is the authenticity anchor the transport hashes above cannot be: the
+  // hashes come from the same (possibly forged) metadata response as the
+  // tarball URL, but this signature is made with npm's registry private key.
+  // It transitively authenticates the WHOLE tarball — including the data/ and
+  // manifest-snapshot.json bytes that carry no per-content Ed25519 signature.
+  //   - valid           → strongest anchor present; proceed.
+  //   - invalid / unknown-keyid → a present signature did not verify against a
+  //                       pinned npm key (or steers us to an unpinned key);
+  //                       this is the forged-metadata signal — refuse.
+  //   - absent / unverifiable   → registry supplied no signature (private or
+  //                       pre-signing registry); the SHA-512/SHA-1 gates above
+  //                       still applied, so warn-and-continue.
+  const regSig = verifyNpmRegistrySignature(PKG_NAME, latestVersion, tarballIntegrity, registrySignatures);
+  if (regSig.status === "invalid" || regSig.status === "unknown-keyid") {
+    emit({
+      ok: false,
+      error: `npm registry signature ${regSig.status} for ${PKG_NAME}@${latestVersion} — refusing to swap`,
+      reason: regSig.reason || null,
+      keyid: regSig.keyid || null,
+      hint: "dist.signatures is present but did not verify against the pinned npm registry key. A forged metadata response cannot reproduce this signature, so treat it as tampering. Run `npm update -g @blamejs/exceptd-skills` for the full provenance-verified path, or report at https://github.com/blamejs/exceptd-skills/issues.",
+    }, opts.json);
+    process.exitCode = 5; return;
+  }
+  if (regSig.status === "absent" || regSig.status === "unverifiable") {
+    progress(`note: npm registry signature ${regSig.status} (${regSig.reason || "no dist.signatures"}) — relying on transport-hash integrity only`, opts.json);
   }
 
   // Extract.
@@ -602,14 +769,16 @@ async function main() {
     process.exitCode = 5; return;
   }
 
-  // v0.12.14: 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).
+  // 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). Their integrity
+  // anchors are: the SHA-512 SRI + SHA-1 shasum transport hashes (checked
+  // above; both-absent is refused), AND — when the registry supplies it — the
+  // npm registry ECDSA-P256 signature over `<pkg>@<version>:<integrity>`
+  // (verifyNpmRegistrySignature above), which authenticates the whole tarball
+  // against npm's pinned signing key and cannot be reproduced by a forged
+  // metadata response. `npm update -g` additionally honors dist.attestations
+  // (sigstore SLSA provenance), which this data-only path does not consume.
   //
   // Defense-in-depth: refuse the swap if the manifest skills list doesn't
   // exactly match the skill payload entries present in the tarball. A
@@ -705,7 +874,9 @@ async function main() {
       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.`,
+      registry_signature_status: regSig.status,
+      registry_signature_keyid: regSig.keyid || null,
+      message: `refreshed catalog from v${localVersion} → v${latestVersion} (${verifiedCount}/${skills.length} skill signatures verified, npm registry signature: ${regSig.status}). Backup at ${path.relative(ROOT, backupDir)} — safe to remove after verifying the new run.`,
     }, opts.json);
   } catch (e) {
     // v0.12.14: walk completedSteps in reverse to undo partial work.
@@ -759,4 +930,10 @@ module.exports = {
   // check.
   verifyTarballManifestSignature,
   canonicalManifestBytesForRefresh,
+  // Exported for in-process tests of the tarball fetch-destination allowlist.
+  isAllowedTarballHost,
+  // Exported for in-process tests of the npm registry signature verification
+  // over `<pkg>@<version>:<integrity>`.
+  verifyNpmRegistrySignature,
+  NPM_REGISTRY_KEYS,
 };

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

@@ -41,6 +41,11 @@
       "minLength": 1,
       "description": "Vulnerability class (LPE, RCE-via-prompt-injection, RCE-supply-chain, etc.)."
     },
+    "attack_class": {
+      "type": "string",
+      "enum": ["kernel-lpe", "mcp-supply-chain", "ai-c2", "prompt-injection", "container-escape"],
+      "description": "Optional coarse chainable taxonomy the sbom -> deep-dive feeds_into rules quantify over (any matched_cve.attack_class == 'kernel-lpe'). Distinct from the free-form `type`: a small fixed set of deep-dive playbook attack classes a matched CVE routes to. Absent when a CVE does not map cleanly to one, so the chain correctly does not fire rather than misrouting."
+    },
     "cvss_score": {
       "type": "number",
       "minimum": 0.0,

package/lib/scoring.js

@@ -81,13 +81,73 @@ const ACTIVE_EXPLOITATION_LADDER = {
   none:        0,
 };
 
+/**
+ * Resolve the active_exploitation ladder multiplier for a factor value.
+ *
+ * The bare `ACTIVE_EXPLOITATION_LADDER[v] ?? 0` lookup silently mapped any
+ * out-of-vocabulary string ('exploited', 'in-the-wild', a future vocabulary
+ * value) AND any case/whitespace variant ('Confirmed', ' CONFIRMED ') to 0 —
+ * dropping up to the full active_exploitation weight (20 pts) from the RWEP
+ * with no diagnostic, while validateFactors() flagged the same string. This
+ * is the recurring "out-of-vocab token -> silent zero" class: the no-match
+ * path must surface an error, not a silent default (same remedy as the
+ * playbook-runner condition-evaluator hyphen fix).
+ *
+ * - Case-normalises the lookup so 'Confirmed' / ' CONFIRMED ' resolve to the
+ *   canonical ladder entry instead of zeroing.
+ * - null / undefined are the documented "treated as 'none'" default (mult 0,
+ *   recognised) — these are not typos.
+ * - A non-empty string NOT in the ladder, or a non-string non-nullish value,
+ *   is UNRECOGNISED: returns multiplier 0 AND emits a process warning so the
+ *   zeroed factor is observable in the bare-number call path. The structured
+ *   diagnostic for the collectWarnings path is produced by validateFactors().
+ *
+ * Returns { multiplier, recognised, normalised }.
+ */
+function resolveActiveExploitation(active_exploitation) {
+  if (active_exploitation === undefined || active_exploitation === null) {
+    // documented default: absent active_exploitation is scored as 'none'.
+    return { multiplier: ACTIVE_EXPLOITATION_LADDER.none, recognised: true, normalised: 'none' };
+  }
+  if (typeof active_exploitation === 'string') {
+    const norm = active_exploitation.trim().toLowerCase();
+    if (Object.prototype.hasOwnProperty.call(ACTIVE_EXPLOITATION_LADDER, norm)) {
+      return { multiplier: ACTIVE_EXPLOITATION_LADDER[norm], recognised: true, normalised: norm };
+    }
+    return { multiplier: 0, recognised: false, normalised: norm };
+  }
+  return { multiplier: 0, recognised: false, normalised: null };
+}
+
+function activeExploitationMultiplier(active_exploitation) {
+  const r = resolveActiveExploitation(active_exploitation);
+  if (!r.recognised) {
+    // Observable diagnostic for the bare-number call path (scoreCustom without
+    // collectWarnings, which the production write-paths use). Routed through
+    // process.emitWarning so it lands on the standard Node diagnostic channel
+    // without changing the function's number return contract; deduped per
+    // distinct offending value so a batch curation run doesn't flood stderr.
+    const detail = active_exploitation === undefined || active_exploitation === null
+      ? String(active_exploitation)
+      : (typeof active_exploitation === 'string' ? JSON.stringify(active_exploitation) : `${typeof active_exploitation} ${JSON.stringify(active_exploitation)}`);
+    process.emitWarning(
+      `active_exploitation ${detail} is not in the recognised ladder (${Object.keys(ACTIVE_EXPLOITATION_LADDER).join(', ')}); contributing 0 active-exploitation weight`,
+      { type: 'RwepActiveExploitationUnrecognised', code: 'RWEP_AE_UNRECOGNISED' },
+    );
+  }
+  return r.multiplier;
+}
+
 // The canonical set of factor keys scoreCustom recognises. Used by
 // validateFactors to flag unknown keys.
 const RECOGNISED_FACTOR_KEYS = new Set([
   'cisa_kev', 'poc_available', 'ai_assisted_weapon', 'ai_discovered',
   'active_exploitation', 'blast_radius', 'patch_available',
   'live_patch_available', 'reboot_required',
-  // accepted alias for the catalog field name
+  // accepted aliases for the catalog field names: a factor bag built straight
+  // from a catalog entry carries `ai_assisted_weaponization` (the field the
+  // catalog declares) and `patch_required_reboot`, not the legacy short forms.
+  'ai_assisted_weaponization',
   'patch_required_reboot',
 ]);
 
@@ -119,10 +179,14 @@ function validateFactors(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) {
+    // The catalog field `ai_assisted_weaponization` satisfies `ai_assisted_weapon`.
+    const present = (f === 'ai_assisted_weapon')
+      ? (factors.ai_assisted_weapon ?? factors.ai_assisted_weaponization)
+      : factors[f];
+    if (present === undefined || present === 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])})`);
+    } else if (typeof present !== 'boolean') {
+      warnings.push(`${f}: expected boolean, got ${typeof present} (${JSON.stringify(present)})`);
     }
   }
   const aeAllowed = ['none', 'unknown', 'suspected', 'theoretical', 'confirmed'];
@@ -180,6 +244,10 @@ function scoreCustom(factors, opts) {
     cisa_kev = false,
     poc_available = false,
     ai_assisted_weapon = false,
+    // The catalog field is `ai_assisted_weaponization`; accept it as an alias
+    // so a factor bag built directly from a catalog entry still counts the AI
+    // factor instead of silently dropping the +15 weight.
+    ai_assisted_weaponization = false,
     ai_discovered = false,
     active_exploitation = 'none',
     blast_radius = 0,
@@ -198,7 +266,7 @@ function scoreCustom(factors, opts) {
   let score = 0;
   score += cisa_kev ? RWEP_WEIGHTS.cisa_kev : 0;
   score += poc_available ? RWEP_WEIGHTS.poc_available : 0;
-  score += (ai_assisted_weapon || ai_discovered) ? RWEP_WEIGHTS.ai_factor : 0;
+  score += (ai_assisted_weapon || ai_assisted_weaponization || ai_discovered) ? RWEP_WEIGHTS.ai_factor : 0;
   // active_exploitation goes through the ladder rather
   // than two hand-written branches with `Math.floor(weight/2)`. The floor
   // was a no-op for even weights (20/2 = 10) but would have silently
@@ -206,7 +274,7 @@ function scoreCustom(factors, opts) {
   // weight to 21. The ladder + multiplication preserves the contribution
   // exactly, including the new `unknown → 0.25 × weight = 5` mapping that
   // aligns the catalog scorer with playbook-runner._activeExploitationLadder.
-  const aeMultiplier = ACTIVE_EXPLOITATION_LADDER[active_exploitation] ?? 0;
+  const aeMultiplier = activeExploitationMultiplier(active_exploitation);
   score += RWEP_WEIGHTS.active_exploitation * aeMultiplier;
   // v0.12.15: blast_radius numeric coercion must reject
   // NaN, Infinity, and strings explicitly. The prior `typeof === 'number'`
@@ -284,9 +352,26 @@ function deriveRwepFromFactors(factors) {
     return scoreCustom(factors);
   }
   // Shape B: catalog post-weight. Sum + clamp.
+  //
+  // blast_radius is the one Shape B field with a per-factor ceiling: it is a
+  // RAW 0..30 magnitude, not a post-weight contribution (see the dual-semantics
+  // note at the top of this file). Clamp it to [0, RWEP_WEIGHTS.blast_radius]
+  // before summing — exactly as scoreCustom does — so an out-of-range stored
+  // value (a unit error such as 300, or a negative) cannot silently inflate or
+  // zero the result by being absorbed only by the final aggregate clamp. Both
+  // paths now produce the same score for the same factors, so the validate()
+  // recompute-vs-stored divergence gate stays meaningful instead of flagging a
+  // self-inconsistency the two scorers introduced. Every other Shape B value is
+  // already a bounded post-weight contribution, so only blast_radius needs the
+  // per-factor clamp.
   let sum = 0;
-  for (const v of values) {
-    if (typeof v === 'number' && Number.isFinite(v)) sum += v;
+  for (const [k, v] of Object.entries(factors)) {
+    if (typeof v !== 'number' || !Number.isFinite(v)) continue;
+    if (k === 'blast_radius') {
+      sum += Math.max(0, Math.min(RWEP_WEIGHTS.blast_radius, v));
+    } else {
+      sum += v;
+    }
   }
   return Math.max(0, Math.min(100, sum));
 }
@@ -333,7 +418,11 @@ function compare(cveId, catalog, opts) {
   // delta is null (not NaN) when there is no CVSS to compare against, so the
   // emitted result serializes cleanly and never claims a numeric divergence
   // that does not exist.
-  const delta = cvssAbsent ? null : rwep - cvssEquivalent;
+  // Guard the RWEP side exactly like CVSS above: an absent or non-finite
+  // rwep_score must not flow into `rwep - cvssEquivalent` — NaN poisons the
+  // delta, fails every band, and falls through to a false "broadly aligned".
+  const rwepValid = (typeof rwep === 'number' && Number.isFinite(rwep));
+  const delta = (cvssAbsent || !rwepValid) ? null : rwep - cvssEquivalent;
 
   // narrow the "broadly aligned" band from ±20 to ±10. The old
   // ±20 band swallowed the Copy Fail RWEP-vs-CVSS divergence (delta = 12)
@@ -347,7 +436,9 @@ function compare(cveId, catalog, opts) {
   // aligned" — coincidence-passing per the field-present-not-populated
   // pitfall. Now the operator sees a specific signal pointing at the
   // catalog gap rather than a false sense of alignment.
-  if ((rwep == null || rwep === 0) && (cvss == null || cvss === 0)) {
+  if (!rwepValid) {
+    explanation = 'RWEP score absent or non-numeric for this CVE — no usable RWEP signal to compare. Backfill rwep_score / rwep_factors in the catalog.';
+  } else if ((rwep == null || rwep === 0) && (cvss == null || cvss === 0)) {
     explanation = 'No scoring signal — both RWEP and CVSS are zero/null. Investigate the catalog entry; this CVE has no usable risk score.';
   } else if (cvssAbsent) {
     // RWEP carries a real signal but there is no CVSS to compare it against.
@@ -379,9 +470,9 @@ function compare(cveId, catalog, opts) {
   const out = {
     cve_id: cveId,
     cvss: cvss,
-    rwep: rwep,
+    rwep: rwepValid ? rwep : null,
     cvss_framework_sla: timeline(cvssEquivalent),
-    rwep_actual_sla: timeline(rwep),
+    rwep_actual_sla: rwepValid ? timeline(rwep) : { hours: null, label: 'RWEP score unavailable' },
     delta,
     explanation,
   };
@@ -485,7 +576,7 @@ function validate(catalog) {
     // one judgment-set factor with no deriving source field.
     if (shape === 'B') {
       const f = entry.rwep_factors;
-      const aeMultiplier = ACTIVE_EXPLOITATION_LADDER[entry.active_exploitation] ?? 0;
+      const aeMultiplier = resolveActiveExploitation(entry.active_exploitation).multiplier;
       const implied = {
         cisa_kev: entry.cisa_kev === true ? RWEP_WEIGHTS.cisa_kev : 0,
         poc_available: entry.poc_available === true ? RWEP_WEIGHTS.poc_available : 0,
@@ -612,6 +703,8 @@ module.exports = {
   validateFactors,
   deriveRwepFromFactors,
   parseCvss31Vector,
+  resolveActiveExploitation,
+  activeExploitationMultiplier,
   RWEP_WEIGHTS,
   ACTIVE_EXPLOITATION_LADDER,
   RECOGNISED_FACTOR_KEYS,