@blamejs/exceptd-skills 0.19.33 → 0.19.34

package/data/_indexes/_meta.json

@@ -1,10 +1,10 @@
 {
   "schema_version": "1.1.0",
-  "generated_at": "2026-08-23T07:03:41.141Z",
+  "generated_at": "2026-08-23T11:56:28.977Z",
   "generator": "scripts/build-indexes.js",
   "source_count": 64,
   "source_hashes": {
-    "manifest.json": "ab7c042636d0c7d610957171d74bd4e0973d8f5718315c90488333a824444a77",
+    "manifest.json": "592a1040e06e609cfc5fa7b690343735f4ad2f52ed3607c526b9ec057f9373eb",
     "README.md": "bc575c178c21e3d07f1491710e24b26cad3a3cee012c43641b6ea7e83468e64e",
     "data/atlas-ttps.json": "a14089671efcb4f06dd0f82d688fe49276c1370e167e4483d76e9c0a40ef41eb",
     "data/attack-techniques.json": "2179122ff8347bc691f245d5fd2601ca81fd1d6f790feae44abca86d3c08f865",

package/lib/auto-discovery.js

@@ -1,30 +1,7 @@
 "use strict";
 /**
- * lib/auto-discovery.js
- *
- * Discovers NEW catalog entries upstream and builds draft entries for
- * `refresh-external.js` to include as `op:"add"` diffs in its auto-PR.
- *
- * Sources covered:
- *   - KEV: every CVE in the CISA KEV feed that's not in local
- *     data/cve-catalog.json. NVD + EPSS data is pulled from the same
- *     prefetch cache the drift-check uses; missing cache entries fall
- *     through to a draft with null mechanical fields.
- *   - RFC: every recent IETF RFC published in a working group the
- *     project's existing rfc-references.json already cites. Queried
- *     live against Datatracker (small N — typically 1-5 RFCs per
- *     month across all project-relevant WGs).
- *
- * Each draft entry carries an `_auto_imported` block with the source,
- * import date, and a `curation_needed` list of analytical fields a
- * human still needs to fill (framework_control_gaps, atlas_refs,
- * attack_refs, type classification, etc.). `validate-cve-catalog.js`
- * is tolerant of this annotation; the audit / stale-content index
- * surfaces uncurated entries so they don't sit indefinitely.
- *
- * Both discovery functions accept a `cap` (default 100) so a burst
- * upstream addition doesn't generate an unreviewable PR. Items past
- * the cap spill to the next run.
+ * Discovers new upstream catalog entries (CISA KEV, IETF RFCs) as `op:"add"`
+ * diffs for refresh-external.js's auto-PR; items past `cap` spill to the next run.
  */
 
 const fs = require("fs");
@@ -34,16 +11,8 @@ const { scoreCustom, postWeightFactors } = require("./scoring");
 const { selectNvdCvss } = require("./cvss");
 const { deriveMechanicalFields } = require("./cve-enrich");
 
-// Stored rwep_factors must reproduce the stored rwep_score.
-// `buildScoringInputs` is the single source of truth for both — it captures
-// the conservative defaults applied to a freshly-imported KEV draft (CISA
-// only lists vulnerabilities with documented exploitation, so we assume a
-// public PoC exists; reboot defaults to true because most KEV-listed CVEs
-// land in the kernel / hypervisor / vendor firmware where reboot is the
-// norm). The same input object is then handed to scoreCustom for the score
-// AND mapped into the `rwep_factors` shape stored on the draft. Calling
-// scoring.validate() on the post-import catalog will no longer flag every
-// auto-imported draft for divergence > 5.
+// Single source of truth for a fresh KEV draft's score and its stored
+// rwep_factors, which must reproduce each other. The defaults read KEV conservatively.
 function buildScoringInputs(kevEntry /*, nvdPayload */) {
   void kevEntry;
   return {
@@ -59,35 +28,13 @@ function buildScoringInputs(kevEntry /*, nvdPayload */) {
   };
 }
 
-// cve-catalog.schema.json's `rwep_factors` requires the post-weight
-// numeric shape (cisa_kev: 0|25, poc_available: 0|20, ai_factor: 0|15,
-// active_exploitation: 0|5|10|20, blast_radius: 0..30, patch_available: 0|-15,
-// live_patch_available: 0|-10, reboot_required: 0|5). Pre-fix the auto-discovery
-// builder stored the SHAPE-A (boolean + string-ladder) factor bag — semantically
-// fine because deriveRwepFromFactors handles either shape, but the strict
-// JSON-schema validator (and any downstream tooling that types-checks the
-// catalog field) rejected drafts as malformed. `scoring.postWeightFactors` (the
-// canonical home for this conversion, also consumed by lib/cve-enrich.js's
-// batch-curation path) now does the boolean -> schema-required post-weight
-// conversion, so the nightly draft builder and the batch tool can't drift on
-// the math.
+// cve-catalog.schema.json requires `rwep_factors` in the post-weight numeric
+// shape, not the boolean + string-ladder shape scoreCustom consumes;
+// `scoring.postWeightFactors` is the one converter.
 
 /**
- * O — diff severity nuance for KEV-discovered drafts.
- *
- * Pre-fix every KEV-derived diff carried `severity: "high"`. Operators
- * scanning the diff stream had no way to distinguish "patch in 21 days"
- * from "active ransomware campaign, patch yesterday." Now:
- *
- *   - ransomware_use === "Known"   → "critical" (campaigns observed in the wild)
- *   - dueDate within 7 days of now → "critical" (CISA escalation window)
- *   - otherwise                    → "high"     (still actively exploited per KEV listing)
- *
- * A KEV listing inherently means active exploitation; "low" / "medium"
- * never apply here. The split is between "act today" and "act this sprint."
- *
- * @param {object} kevEntry
- * @returns {"critical" | "high"}
+ * Severity of a KEV-discovered diff. A KEV listing itself means active
+ * exploitation, so "low" and "medium" never apply.
  */
 function deriveKevSeverity(kevEntry) {
   const ransomware = String(kevEntry?.knownRansomwareCampaignUse || "").toLowerCase() === "known";
@@ -97,7 +44,6 @@ function deriveKevSeverity(kevEntry) {
     const dueMs = Date.parse(due);
     if (Number.isFinite(dueMs)) {
       const deltaMs = dueMs - Date.now();
-      // Within the next 7 days OR already past due → critical.
       if (deltaMs <= 7 * 86_400_000) return "critical";
     }
   }
@@ -109,8 +55,7 @@ const TIMEOUT_MS = 10_000;
 const USER_AGENT = "exceptd-security/auto-discovery (+https://exceptd.com)";
 const DEFAULT_CAP = 100;
 
-// IETF Datatracker codes → human-readable status strings used in
-// data/rfc-references.json.
+// IETF Datatracker codes → the status strings data/rfc-references.json stores.
 const RFC_STATUS_MAP = {
   std: "Internet Standard",
   ps:  "Proposed Standard",
@@ -122,29 +67,11 @@ const RFC_STATUS_MAP = {
   unkn: "Unknown",
 };
 
-// Read a per-source cache payload and verify its integrity against the
-// signed _index.json before returning it. Values from these files flow into
-// auto-imported catalog drafts (CVSS / CWE / EPSS), so an unverified read
-// would let an attacker who dropped a forged payload between prefetch and
-// refresh inject false mechanical fields. Discovery cannot throw (it returns
-// drafts, not errors), so the fail-closed action is to return null — the
-// payload is treated as absent and the draft keeps its null mechanical
-// fields, the same fallback used when no cache file exists.
-//
-// Integrity policy, mirroring the hardened drift reader in
-// refresh-external.js but never throwing:
-//   - _index.json present, has a per-entry sha256, payload matches -> return.
-//   - _index.json present, has a per-entry sha256, payload MISMATCHES ->
-//     return null. This is the core defense: a freshly-DISCOVERED CVE's
-//     NVD/EPSS sidecar dropped into a cache that already carries a valid
-//     signed index has no matching entry, and a tampered legit entry no
-//     longer hashes — both refuse to populate.
-//   - _index.json present but no entry for this source/id -> return null
-//     (the inject-alongside-a-signed-cache vector).
-//   - _index.json absent entirely -> unverified read. The --from-cache
-//     signature gate (loadCtx) already refuses an unsigned cache before
-//     consume unless --force-stale, so an index-less cache only reaches here
-//     under that explicit operator override or a direct library caller.
+// Reads a per-source cache payload, verified against the signed _index.json.
+// Anything unverifiable returns null — the only fail-closed action available to
+// a function that returns drafts, not errors. A missing index ENTRY returns null
+// too (the inject-alongside-a-signed-cache vector); an absent _index.json is left
+// to loadCtx's --from-cache signature gate.
 function readCachedJson(cacheDir, source, id) {
   if (!cacheDir) return null;
   const safe = String(id).replace(/[^A-Za-z0-9._-]/g, "_");
@@ -159,27 +86,23 @@ function readCachedJson(cacheDir, source, id) {
   try { idx = JSON.parse(fs.readFileSync(indexPath, "utf8")); } catch { return null; }
   const meta = idx && idx.entries && idx.entries[`${source}/${id}`];
   if (!meta || typeof meta.sha256 !== "string") return null;
-  // The sha256 recorded at prefetch time is computed over JSON.stringify of
-  // the parsed payload (unindented), so round-trip + re-stringify to compute
-  // the comparable hash.
+  // The recorded sha256 is over JSON.stringify of the parsed payload
+  // (unindented), so re-stringify rather than hashing the file bytes.
   const actual = crypto.createHash("sha256").update(JSON.stringify(parsed)).digest("hex");
   if (actual !== meta.sha256) return null;
   return parsed;
 }
 
 function extractNvdMetrics(payload, id) {
-  // Resolve the NVD vuln by id, not by position. vulnerabilities[0] blindly
-  // took the first record, so a cache entry keyed under `id` that held another
-  // CVE's response would attribute that CVE's CVSS/CWE/description to this id.
-  // When no id is supplied (legacy callers), fall back to the first record.
+  // Resolve by id, not by position: a cache entry keyed under `id` that holds
+  // another CVE's response would otherwise attribute its CVSS and CWE here.
   const cves = (payload?.vulnerabilities || []).map((v) => v?.cve).filter(Boolean);
   const vuln = id
     ? cves.find((c) => c.id && String(c.id).toUpperCase() === String(id).toUpperCase())
     : cves[0];
   if (!vuln) return null;
-  // Prefer the newest CVSS version (Primary within it) and normalize a bare
-  // v2 vector to its canonical prefix so an auto-imported draft never carries
-  // an unprefixed vector that the strict catalog validator would reject.
+  // Newest CVSS version, Primary within it, with a bare v2 vector normalized
+  // to its canonical prefix — the strict catalog validator rejects unprefixed.
   const up = selectNvdCvss(vuln.metrics);
   return {
     cvss_score: up ? up.baseScore : null,
@@ -190,24 +113,16 @@ function extractNvdMetrics(payload, id) {
       .map((d) => d.value)
       .filter((v) => /^CWE-\d+$/.test(v))
     ),
-    // Carry NVD's reference list (url + tags) so buildKevDraftEntry can feed
-    // real "Vendor Advisory"-tagged links into cve-enrich and a nightly
-    // draft's vendor_advisories reflects genuine advisories (empty otherwise,
-    // correctly tripping the cisa_kev-but-no-advisory curation-gap detector).
+    // The tags are load-bearing: cve-enrich keeps only "Vendor Advisory" links,
+    // so an empty result correctly trips the no-advisory curation-gap detector.
     references: (vuln.references || []).map((r) => ({ url: r.url, tags: r.tags || [] })),
   };
 }
 
 function extractEpss(payload, id) {
   const data = Array.isArray(payload?.data) ? payload.data : [];
-  // Match the requested CVE id only. The prior `|| data[0]` fallback silently
-  // misattributed a DIFFERENT CVE's EPSS score into the draft whenever the
-  // requested id was absent from the payload — a single-row response for the
-  // wrong CVE (or a stale/mismatched sidecar) wrote that CVE's score under the
-  // discovered id. A non-matching payload now yields null (same
-  // null-mechanical-field behavior used when no cache exists). The only
-  // accepted fallback is a single-row, cve-less response shape (the requested
-  // id is implicit because the payload carries exactly one un-keyed row).
+  // Match the requested id only — a `|| data[0]` fallback writes another CVE's
+  // score here. The one exception is a single-row, cve-less payload.
   let row = data.find((r) => r?.cve === id);
   if (!row && data.length === 1 && data[0]?.cve == null) row = data[0];
   if (!row) return null;
@@ -218,43 +133,16 @@ function extractEpss(payload, id) {
   };
 }
 
-// --- KEV discovery -----------------------------------------------------
-
 /**
- * Build a draft CVE catalog entry from a KEV record + optional cached
- * NVD/EPSS payloads. Required-schema fields are populated where
- * mechanically derivable; analytical fields are nulled and listed in
- * `_auto_imported.curation_needed`.
- *
- * @param {object} kevEntry  Single vulnerability from CISA KEV feed
- * @param {object|null} nvdPayload  Cached NVD 2.0 response (or null)
- * @param {object|null} epssPayload  Cached EPSS response (or null)
+ * Draft catalog entry from one KEV record plus cached NVD 2.0 and EPSS payloads,
+ * either of which may be null. Analytical fields stay null.
  */
 function buildKevDraftEntry(kevEntry, nvdPayload, epssPayload) {
   const id = String(kevEntry.cveID);
   const nvd = nvdPayload ? extractNvdMetrics(nvdPayload, id) : null;
   const epss = epssPayload ? extractEpss(epssPayload, id) : null;
 
-  // Stored rwep_factors and computed rwep_score MUST agree.
-  // Previously rwep_factors held nulls (for unknown poc/ai/reboot) but
-  // rwep_score was computed from concrete defaults (poc=true, reboot=true).
-  // `scoring.validate()` then flagged every auto-imported draft for
-  // divergence > 5. Now: one canonical input object → both surfaces.
-  //
-  // the catalog's JSON-schema for `rwep_factors` requires the
-  // POST-WEIGHT numeric shape (ai_factor / numeric ladder contributions /
-  // numeric ±deductions) — not the SHAPE-A boolean + string-ladder shape
-  // that scoreCustom consumes. Pre-fix the boolean shape was stored
-  // verbatim, so curate-apply's strict-schema gate rejected KEV-discovered
-  // drafts as soon as anyone tried to promote them — they were
-  // permanently unpromotable. `scoring.postWeightFactors` (shared with the
-  // batch-curation path in lib/cve-enrich.js) does the conversion now.
-  //
-  // The curation flow rewrites these once an operator answers the editorial
-  // questions; until then, the post-weight numeric shape on rwep_factors
-  // reproduces the score exactly (sum of values === rwep_score, because
-  // blast_radius weight=30 matches the raw-cap convention documented in
-  // scoring.js header).
+  // One input object feeds both, so the stored factors sum exactly to rwep_score.
   const scoringInputs = buildScoringInputs(kevEntry, nvdPayload);
   const rwep_factors = postWeightFactors(scoringInputs);
   const rwep_score = scoreCustom(scoringInputs);
@@ -263,15 +151,8 @@ function buildKevDraftEntry(kevEntry, nvdPayload, epssPayload) {
     .filter(Boolean)
     .join(" ");
 
-  // Mechanical fields (name, cvss_score/vector, cwe_refs, cisa_kev +
-  // cisa_kev_date/due_date, known_ransomware_use, complexity, vector, epss_*,
-  // vendor_advisories, verification_sources, source_verified/last_updated)
-  // are derived through the SAME cve-enrich module the `--curate-batch`
-  // tool uses, so the nightly auto-PR path and the batch tool never drift on
-  // how a raw KEV/NVD/EPSS fact set becomes a mechanical field. See
-  // lib/cve-enrich.js:deriveMechanicalFields — this module maps the already-
-  // extracted `nvd`/`epss` payloads (see extractNvdMetrics/extractEpss above)
-  // and the raw `kevEntry` into that module's `facts` shape.
+  // deriveMechanicalFields is shared with `--curate-batch`, so the nightly path
+  // and the batch tool cannot drift. What follows is that module's `facts` shape.
   const facts = {
     id,
     nvd_desc: nvd && nvd.description,
@@ -301,11 +182,8 @@ function buildKevDraftEntry(kevEntry, nvdPayload, epssPayload) {
     ai_discovered: null,
     ai_discovery_notes: null,
     ai_assisted_weaponization: null,
-    // Conservative pre-curation default — overrides deriveMechanicalFields'
-    // 'confirmed' (mechanically derived from "this CVE has a KEV listing").
-    // A nightly draft must not claim CONFIRMED active exploitation before a
-    // human has reviewed it; 'suspected' is the honest starting posture even
-    // though KEV listing alone already implies exploitation is real.
+    // Overrides deriveMechanicalFields' 'confirmed': a draft must not claim
+    // confirmed exploitation before a human has reviewed it.
     active_exploitation: "suspected",
     affected: product || "See vendor advisory",
     affected_versions: [],
@@ -321,12 +199,8 @@ function buildKevDraftEntry(kevEntry, nvdPayload, epssPayload) {
     rwep_score,
     rwep_factors,
     last_verified: TODAY,
-    // v0.12.15 (D): `_auto_imported` must be the boolean `true`
-    // for lib/validate-cve-catalog.js's draft-recognition check (strict
-    // `=== true` comparison). The prior object-shape was non-recognizable
-    // and the strict validator treated KEV-discovered drafts as
-    // hard-error entries instead of warning-tier drafts. The provenance
-    // metadata that used to be inline now lives in `_auto_imported_meta`.
+    // Boolean `true`, not an object: lib/validate-cve-catalog.js recognizes a
+    // draft by strict `=== true`. Provenance goes in `_auto_imported_meta`.
     _auto_imported: true,
     _auto_imported_meta: {
       source: "KEV discovery",
@@ -348,10 +222,8 @@ function buildKevDraftEntry(kevEntry, nvdPayload, epssPayload) {
 }
 
 /**
- * Find KEV entries upstream that are not in local cve-catalog.json.
- * Returns an array of { id, op:"add", entry, severity } diffs capped
- * at `cap` items. Spill past the cap is logged on the diff object's
- * `_spilled` count so the PR body can mention it.
+ * KEV entries upstream that are absent from local cve-catalog.json, as
+ * { id, op:"add", entry, severity } diffs capped at `cap`; overflow is `spilled`.
  */
 function discoverNewKev(ctx, cap = DEFAULT_CAP) {
   const feed = readCachedJson(ctx.cacheDir, "kev", "known_exploited_vulnerabilities");
@@ -363,8 +235,7 @@ function discoverNewKev(ctx, cap = DEFAULT_CAP) {
     Object.keys(ctx.cveCatalog).filter((k) => /^CVE-\d{4}-\d{4,7}$/.test(k))
   );
 
-  // Sort by dateAdded descending so the most recent additions are kept
-  // when the cap clips the list.
+  // Newest dateAdded first, so the cap clips the oldest additions.
   const candidates = feed.vulnerabilities
     .filter((v) => v && v.cveID && !localCves.has(String(v.cveID)))
     .sort((a, b) => String(b.dateAdded || "").localeCompare(String(a.dateAdded || "")));
@@ -402,28 +273,14 @@ function discoverNewKev(ctx, cap = DEFAULT_CAP) {
   };
 }
 
-// --- RFC discovery -----------------------------------------------------
-
 async function fetchDatatracker(url, ctx) {
-  // Air-gap refusal — Datatracker is a live IETF service. When the operator
-  // (or the caller's ctx) declares air-gap, return a structured refusal so
-  // refresh-external can surface "discovery skipped" rather than logging a
-  // generic network error. Caller's signature already accepts a nullable
-  // return; the structured object is distinguishable from a successful
-  // payload by `ok:false`.
+  // A structured `ok:false` the caller tells apart from a payload, so an air-gap
+  // refusal reports as a skip rather than a fetch error.
   if ((ctx && ctx.airGap === true) || process.env.EXCEPTD_AIR_GAP === "1") {
     return { ok: false, error: "air-gap-blocked", source: "datatracker" };
   }
-  // Adopt the vendored blamejs retry primitive, matching source-osv /
-  // source-ghsa / source-advisories / refresh-network: a transient Datatracker
-  // failure (HTTP 429/5xx, ECONNRESET/ETIMEDOUT family) backs off with
-  // exponential jitter instead of being dropped on the first hiccup, which
-  // silently yielded no discovered working groups. A genuine 4xx (e.g. 404 on
-  // a renamed WG acronym) carries a non-retryable statusCode, so the classifier
-  // does not waste attempts on it. The caller contract is unchanged: discovery
-  // never throws — it returns drafts, not errors — so an exhausted retry budget
-  // (or any non-retryable failure) collapses to the same `null` the
-  // single-fetch path returned, which discoverNewRfcs treats as one WG skip.
+  // Transient failures (429/5xx, ECONNRESET/ETIMEDOUT) back off with jitter.
+  // Discovery never throws, so an exhausted budget collapses to null.
   const { withRetry } = require("../vendor/blamejs/retry.js");
   const once = async () => {
     const ac = new AbortController();
@@ -451,74 +308,8 @@ async function fetchDatatracker(url, ctx) {
 }
 
 /**
- * Derive the set of IETF working-group acronyms the project already
- * cares about. Reads each entry in data/rfc-references.json, looks up
- * its Datatracker doc in the prefetch cache, extracts the group
- * acronym, returns the union.
- *
- * Two layers in the result:
- *
- *   1. DYNAMICALLY DERIVED — every WG that appears on a project-cited
- *      RFC's Datatracker record. Grows organically as catalog grows.
- *
- *   2. SEEDED — a curated baseline of IETF WGs that publish RFCs
- *      directly relevant to the project's mid-2026 threat model and
- *      compliance frameworks, even when the catalog doesn't yet cite
- *      one of their RFCs. Without this, RFC discovery would be blind
- *      to e.g. SCITT (supply chain) until a SCITT RFC was already
- *      manually added — defeating the point of discovery.
- *
- * SEED groups by project area:
- *
- *   Transport / crypto / PKI:
- *     tls, uta, cfrg, lamps, ipsecme
- *   HTTP / web / QUIC / API:
- *     httpbis, quic, ohai, privacypass, httpapi, core
- *   Identity / auth / SSO / cert mgmt / workload identity / constrained-env auth:
- *     oauth, gnap, jose, cose, cbor, kitten, emu, secevent, scim,
- *     acme, wimse, ace
- *   DNS security + privacy + DNS-based auth:
- *     dnsop, dprive, add, dance
- *   Supply chain + attestation + transparency + firmware/TEE:
- *     scitt, rats, suit, teep, trans
- *   Threat intel + security automation + operational telemetry:
- *     mile, sacm, i2nsf, opsawg, opsec
- *   Messaging + E2E + media:
- *     mls, moq, sframe
- *   Network / IoT mgmt + audit-grade time sync:
- *     anima, drip, iotops, netconf, netmod, ntp
- *   Data / schema / policy serialization:
- *     jsonschema
- *
- * Database protocols themselves (Postgres wire, MongoDB wire, etc.)
- * aren't IETF-standardized, so there's no "database" WG. The security
- * infrastructure databases USE — TLS for connections (tls/uta/lamps),
- * SASL/Kerberos auth (kitten/emu), workload identity (wimse), field
- * encryption (cose/cfrg/cbor), audit-trail time (ntp), cert validation
- * (lamps/dance/trans), and access-control sync (scim/oauth) — is all
- * already covered by the WGs above. jsonschema covers the DB+API+policy
- * schema validation layer.
- *
- * Reasoning for additions over the v0.9.2 seed:
- *   - wimse (Workload Identity in Multi-System Environments): federal
- *     zero-trust mandates + cloud-native workload identity are core to
- *     identity-assurance + sector-federal-government skills.
- *   - gnap (Grant Negotiation): OAuth successor; identity-assurance
- *     skill will eventually cite this.
- *   - ace + core: auth + REST for constrained environments — OT/ICS
- *     and IoT supply chain.
- *   - cbor: foundation for COSE, attestation tokens, SCITT receipts.
- *     Touches MCP trust + supply-chain integrity + RATS attestation.
- *   - trans (Certificate Transparency): compliance evidence for cert
- *     issuance; cross-cuts identity + framework-gap analysis.
- *   - ntp: audit trails need monotonic time. Required for the audit
- *     skills + breach-notification clocks (DORA, NYDFS, NIS2).
- *   - opsawg + opsec: operational security guidance and telemetry.
- *     Touches incident-response + threat-model-currency.
- *   - dance: DANE Authentication for Named Entities Enhancements —
- *     adds DNS-anchored TLS trust (complements lamps PKI).
- *   - netmod: NETCONF YANG models, often security-relevant for OT/ICS
- *     and network-segmentation policy.
+ * Seed WGs, unioned with those on project-cited RFCs: without the seed,
+ * discovery stays blind to a WG until one of its RFCs is added by hand.
  */
 const SEED_RFC_GROUPS = [
   // Transport / crypto / PKI
@@ -538,8 +329,7 @@ const SEED_RFC_GROUPS = [
   "mls", "moq", "sframe",
   // Network / IoT mgmt + audit-grade time sync
   "anima", "drip", "iotops", "netconf", "netmod", "ntp",
-  // Data / schema / policy serialization (DB validation, API schemas,
-  // security-policy contract languages)
+  // Data / schema / policy serialization
   "jsonschema",
 ];
 
@@ -556,35 +346,25 @@ function getProjectRfcGroups(ctx) {
     const acronym = obj?.group?.acronym || (typeof obj?.group === "string" ? extractAcronymFromGroupUri(obj.group) : null);
     if (acronym) groups.add(String(acronym).toLowerCase());
   }
-  // Always union the seed list — dynamic derivation covers the WGs we
-  // already cite; the seed covers WGs we SHOULD watch for our skill
-  // coverage even if no RFC from that WG is in the catalog yet.
   for (const g of SEED_RFC_GROUPS) groups.add(g);
   return groups;
 }
 
 function extractAcronymFromGroupUri(uri) {
-  // Group URIs from Datatracker look like /api/v1/group/group/12345/.
-  // Group acronym is in the doc object's full record but not in the URI.
-  // Returning null means we have to live-fetch later.
+  // A Datatracker group URI (/api/v1/group/group/12345/) carries no acronym —
+  // it is only in the doc object's full record. Null means live-fetch later.
   void uri;
   return null;
 }
 
 /**
- * Find recent RFCs published in any project-relevant working group
- * that aren't already in data/rfc-references.json. Queries Datatracker
- * live (small N — runs once per refresh, ~9 WG queries).
- *
- * @param {object} ctx
- * @param {object} opts  { cap?: number, sinceDays?: number }
+ * Recent RFCs in project-relevant working groups that are not already in
+ * data/rfc-references.json. Queries Datatracker live, one call per WG.
+ * @param {object} opts  { cap = DEFAULT_CAP, sinceDays = 180 }
  */
 async function discoverNewRfcs(ctx, opts = {}) {
-  // Air-gap: new-RFC discovery queries IETF Datatracker live (~one call per
-  // project working group). Refuse the egress under --air-gap so a fully
-  // offline run makes no network calls — the other discovery paths guard the
-  // same way. --from-cache alone (network-available host, e.g. the scheduled
-  // refresh) still discovers live; add --air-gap for a truly offline run.
+  // --air-gap refuses the egress outright; --from-cache alone still queries
+  // live, since the scheduled refresh runs on a networked host.
   if ((ctx && ctx.airGap === true) || process.env.EXCEPTD_AIR_GAP === "1") {
     return { diffs: [], errors: 0, spilled: 0, summary: "RFC discovery: skipped under air-gap (no live Datatracker query)" };
   }
@@ -603,18 +383,13 @@ async function discoverNewRfcs(ctx, opts = {}) {
   let errors = 0;
 
   for (const wg of groups) {
-    // Datatracker filter: RFCs in this WG, time > cutoff. Ordered by time descending.
     const url =
       `https://datatracker.ietf.org/api/v1/doc/document/` +
       `?type=rfc&group__acronym=${encodeURIComponent(wg)}` +
       `&time__gt=${cutoff}&order_by=-time&limit=20&format=json`;
     const payload = await fetchDatatracker(url, ctx);
-    // Treat the air-gap structured refusal as a discovery skip — not an
-    // error. The existing `!payload || !Array.isArray(payload.objects)`
-    // path would have classed it as `errors++`, which misreports an
-    // operator-chosen offline posture as a fault. Short-circuit the whole
-    // WG loop on first air-gap refusal because every subsequent fetch will
-    // refuse identically.
+    // An air-gap refusal is a skip, not an `errors++` fault, and every later
+    // fetch refuses identically — leave the WG loop on the first one.
     if (payload && payload.ok === false && payload.error === "air-gap-blocked") {
       return {
         diffs: [],
@@ -639,8 +414,7 @@ async function discoverNewRfcs(ctx, opts = {}) {
     }
   }
 
-  // Dedupe across overlapping WG membership (an RFC can list multiple
-  // groups). Keep the first occurrence (alphabetically first WG match).
+  // An RFC can list several groups; keep the first WG match.
   const seen = new Set();
   candidates = candidates.filter((c) => {
     if (seen.has(c.localKey)) return false;
@@ -648,7 +422,7 @@ async function discoverNewRfcs(ctx, opts = {}) {
     return true;
   });
 
-  // Sort by published time descending so we keep the most recent under the cap.
+  // Newest published first, so the cap clips the oldest.
   candidates.sort((a, b) => String(b.obj.time || "").localeCompare(String(a.obj.time || "")));
 
   const total = candidates.length;
@@ -668,11 +442,7 @@ async function discoverNewRfcs(ctx, opts = {}) {
       skills_referencing: [],
       errata_count: null,
       last_verified: TODAY,
-      // v0.12.15 (D, P3-T): boolean `_auto_imported: true` for
-      // strict-validator recognition; provenance moved to sibling
-      // `_auto_imported_meta`. Errata-URL hint converted to a real template
-      // literal so the rfc number actually interpolates (the previous double-
-      // quoted string left `${number}` as literal text in operator output).
+      // Boolean `true` for strict-validator draft recognition.
       _auto_imported: true,
       _auto_imported_meta: {
         source: `RFC discovery (IETF ${wg} working group)`,

package/lib/canonical-eq.js

@@ -1,51 +1,20 @@
 "use strict";
 /**
- * lib/canonical-eq.js
+ * Canonical-form deep equality for catalog diff detection.
  *
- * Canonical-form deep equality for catalog diff detection. The diff-
- * coverage gate previously compared `JSON.stringify(before.iocs)` vs
- * `JSON.stringify(after.iocs)` which is non-canonical: key order,
- * trailing whitespace, and numeric format differences all register as
- * "different" when the operator made no semantic change.
- *
- * Pre-v0.13.20 history: the symptom was patched twice with skip rules
- * (v0.13.17 _auto_imported skip; v0.13.19 _iocs_stub skip). v0.13.20
- * fixes the root cause — canonical recursive equality with sorted-key
- * object comparison and array-position-sensitive element comparison.
- *
- * Contract:
- *   - Primitives (string / number / boolean / null / undefined) compare
- *     by strict equality (===).
- *   - Arrays compare element-by-element in order. [1,2] !== [2,1].
- *     This matches operator intent — array order in IoCs / attack_refs
- *     / cwe_refs is meaningful (most-relevant-first convention).
- *   - Objects compare by key-set equality + per-key recursive equality.
- *     Key order does NOT matter; { a:1, b:2 } === { b:2, a:1 }.
- *   - Cycle protection: WeakSet of visited pairs prevents infinite
- *     recursion on self-referential structures. Cycles compare unequal
- *     across mismatched topologies; equal across identical topologies.
- *   - NaN: NaN === NaN under this comparator (deviates from Object.is
- *     to make the comparator total — useful for catalog data which
- *     never legitimately contains NaN but might pick one up from a
- *     buggy upstream).
- *
- * Helpers:
- *   - canonicalEqual(a, b): full recursive equality.
- *   - canonicalStringify(v): sorted-key JSON for hashing / display.
- *     Produces stable output suitable for SHA-256 etc.
+ * Arrays compare element-by-element in order — [1,2] !== [2,1], since position
+ * in iocs / attack_refs / cwe_refs carries meaning. Objects compare by key set
+ * and per-key value, so key order is irrelevant. NaN equals NaN, which makes
+ * the comparator total. A pair already under comparison compares equal, so a
+ * cycle leaves the verdict to the non-cyclic structure around it.
  */
 
 function canonicalEqual(a, b, seen = new WeakMap()) {
   if (a === b) return true;
-  // NaN === NaN under this comparator.
   if (typeof a === "number" && typeof b === "number" && Number.isNaN(a) && Number.isNaN(b)) return true;
   if (a === null || b === null) return a === b;
   if (typeof a !== "object" || typeof b !== "object") return false;
 
-  // Cycle detection — if we've already compared this exact pair, treat
-  // as equal (assumes the rest of the structure decides). For sibling-
-  // cycle differences this means the comparator says "equal at the
-  // cycle point" and lets non-cyclic differences elsewhere decide.
   const aSeen = seen.get(a);
   if (aSeen && aSeen.has(b)) return true;
   if (!aSeen) seen.set(a, new WeakSet([b]));
@@ -63,7 +32,6 @@ function canonicalEqual(a, b, seen = new WeakMap()) {
     return true;
   }
 
-  // Plain objects — compare key sets + per-key recursive equality.
   const aKeys = Object.keys(a).sort();
   const bKeys = Object.keys(b).sort();
   if (aKeys.length !== bKeys.length) return false;
@@ -76,8 +44,7 @@ function canonicalEqual(a, b, seen = new WeakMap()) {
   return true;
 }
 
-// Sorted-key recursive JSON. Stable output for hash digests, diff
-// comparison, and human-readable display.
+// Sorted-key recursive JSON — stable bytes for hash digests and diffing.
 function canonicalStringify(v) {
   if (v === null || typeof v !== "object") return JSON.stringify(v);
   if (Array.isArray(v)) return "[" + v.map(canonicalStringify).join(",") + "]";