@blamejs/exceptd-skills 0.18.9 → 0.18.12

package/lib/validate-catalog-meta.js

@@ -85,6 +85,29 @@ function containsPlaceholder(s) {
   return PLACEHOLDER_TOKENS.some((re) => re.test(s));
 }
 
+// Round-trip ISO calendar-date check. Returns a Date for a real YYYY-MM-DD
+// calendar date, or null for anything malformed. Unlike a shape-only regex,
+// this rejects impossible dates (2026-13-99, 2026-04-31, 2026-02-29 in a
+// non-leap year): `new Date('2026-02-30T00:00:00Z')` does NOT throw — it rolls
+// over to March 2 with a valid getTime() — so the parsed Y-M-D must round-trip
+// back to the input components. Deliberately carries NO year-floor business
+// rule (a valid-but-old 1900-01-01 stays a valid date so the staleness branch,
+// not the validity branch, reports it).
+function parseIsoDateStrict(v) {
+  if (typeof v !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(v)) return null;
+  const d = new Date(v + 'T00:00:00Z');
+  if (Number.isNaN(d.getTime())) return null;
+  const [y, m, day] = v.split('-').map(Number);
+  if (
+    d.getUTCFullYear() !== y ||
+    d.getUTCMonth() + 1 !== m ||
+    d.getUTCDate() !== day
+  ) {
+    return null;
+  }
+  return d;
+}
+
 function validateMeta(catalogPath, opts) {
   const errors = [];
   const warnings = [];
@@ -92,7 +115,16 @@ function validateMeta(catalogPath, opts) {
   const meta = data._meta;
 
   if (!meta || typeof meta !== 'object') {
-    return ['missing _meta block'];
+    // Honor both return contracts. The rest of the body dereferences
+    // `meta.tlp` / `meta.source_confidence` / `meta.freshness_policy`, so it
+    // must NOT run when `meta` is absent or non-object. Return early in the
+    // SAME shape the caller asked for: includeWarnings callers (main()) get
+    // `{errors, warnings}` so `result.errors` is a real array and the loop
+    // reports a clean FAIL + continues; no-opts callers still get a non-empty
+    // `string[]`. This still FAILS — it only removes the uncaught TypeError.
+    errors.push('missing _meta block');
+    if (opts && opts.includeWarnings) return { errors, warnings };
+    return errors;
   }
 
   /* tlp */
@@ -176,14 +208,26 @@ function validateMeta(catalogPath, opts) {
      * the warning posture.
      */
     if (
-      typeof meta.last_updated === 'string' &&
+      meta.last_updated !== undefined &&
       typeof fp.stale_after_days === 'number' &&
       fp.stale_after_days > 0
     ) {
-      const lu = new Date(meta.last_updated + (
-        /^\d{4}-\d{2}-\d{2}$/.test(meta.last_updated) ? 'T00:00:00Z' : ''
-      ));
-      if (!Number.isNaN(lu.getTime())) {
+      const lu = parseIsoDateStrict(meta.last_updated);
+      if (lu === null) {
+        // Fail-closed on a malformed date instead of silently skipping the
+        // freshness gate. A NaN/impossible/wrong-shape last_updated is
+        // "invalid input" (error under --strict, warning by default), NOT
+        // "no opinion" — otherwise the staleness check fails open.
+        const msg =
+          `_meta.last_updated ${JSON.stringify(meta.last_updated)} is not a valid ISO date ` +
+          `(YYYY-MM-DD calendar date) — cannot evaluate freshness. ` +
+          `Promoted to an error under --strict.`;
+        if (opts && (opts.strict || opts.errorOnStale)) {
+          errors.push(msg);
+        } else {
+          warnings.push(msg);
+        }
+      } else {
         const ageDays = Math.floor((Date.now() - lu.getTime()) / 86400000);
         if (ageDays > fp.stale_after_days) {
           const msg =
@@ -255,4 +299,4 @@ if (require.main === module) {
   main();
 }
 
-module.exports = { validateMeta };
+module.exports = { validateMeta, parseIsoDateStrict };

package/lib/validate-cve-catalog.js

@@ -244,6 +244,16 @@ function isUsableDate(value) {
 function additionalChecks(key, entry, ctx) {
   const warnings = [];
 
+  // A non-object entry has no checkable sub-fields, and validate() already
+  // emits the top-level type error for it (lines 127-133). Guarding here turns
+  // the uncaught `entry.poc_available` TypeError on a null/array entry into a
+  // clean no-op so main() still prints that FAIL and continues to later
+  // entries instead of aborting the whole gate. The FAIL is preserved — it
+  // originates in validate(), not here.
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    return [];
+  }
+
   // V1 — Hard Rule #14 conditional: poc + public-exploit URL → iocs required.
   if (entry.poc_available === true) {
     const sources = Array.isArray(entry.verification_sources)

package/lib/validate-playbooks.js

@@ -322,6 +322,16 @@ function obligationKey(o) {
 
 function checkCrossRefs(playbook, ctx, playbookIds) {
   const findings = [];
+  // A null/array/primitive playbook has no cross-refs to check, and validate()
+  // already emits the top-level `expected type "object", got null` error for
+  // it (main() line ~755). Guarding here turns the uncaught `playbook._meta`
+  // TypeError on a literal-null playbook file into a clean no-op so main()
+  // still reports the FAIL and continues to the remaining playbooks instead of
+  // aborting the whole gate. The FAIL is preserved — it originates in
+  // validate(), not here.
+  if (!playbook || typeof playbook !== 'object' || Array.isArray(playbook)) {
+    return findings;
+  }
   const meta = playbook._meta || {};
   const phases = playbook.phases || {};
   const domain = playbook.domain || {};
@@ -533,7 +543,15 @@ function checkCrossRefs(playbook, ctx, playbookIds) {
     // Case-insensitive + word-bounded so `HTTPS://`, `Curl`, and `fetch(` (no
     // trailing space) still flag a network source — otherwise an artifact could
     // ship under air_gap_mode with no offline alternative and run incomplete.
-    const netSourceRe = /(https?:\/\/|\bgh (?:api|release)\b|\bcurl\b|\bwget\b|\bfetch\b)/i;
+    // Network-source detection includes API-verb-phrased sources ("GET
+    // /directoryRoles via Graph", "Entra ID", "Okta", "Microsoft Graph") so a
+    // REST/Graph endpoint described in prose still flags under air_gap_mode and
+    // is not silently collected offline-incomplete. `api/v\d` is deliberately
+    // NOT a token — it false-positives on local code-scan artifacts that merely
+    // reference an API path. NOTE: lib/schemas/playbook.schema.json carries the
+    // same narrow `source` pattern and must be broadened in lockstep with this
+    // regex (main-thread item — that file is not edited here).
+    const netSourceRe = /(https?:\/\/|\bgh (?:api|release)\b|\bcurl\b|\bwget\b|\bfetch\b|\b(?:GET|POST|PUT|PATCH|DELETE)\s+\/|\bGraph\b|\b(?:Okta|Entra ID|Microsoft Graph)\b)/i;
     for (const [i, art] of (look.artifacts || []).entries()) {
       if (!art || typeof art !== 'object') continue;
       if (typeof art.source === 'string' && netSourceRe.test(art.source)) {

package/lib/verify.js

@@ -342,6 +342,39 @@ function canonicalManifestBytes(manifest) {
  * @param {object} manifest
  */
 function verifyManifestSignature(manifest) {
+  // The key-pin fingerprint check runs FIRST — independent of whether a
+  // manifest_signature is present — so library callers (refresh-network gate,
+  // verify-shipped-tarball gate, tests, downstream `require("lib/verify")`
+  // consumers) cannot bypass the pin. Previously the pin only fired AFTER the
+  // signature-present check, so a key-substitution attacker who swapped
+  // keys/public.pem AND stripped manifest_signature got the early `missing`
+  // return and never tripped the pin — authenticating against the attacker key
+  // through the library API. Consulting the pin up front closes that on the
+  // legacy/missing path too. Honors KEYS_ROTATED=1 for legitimate rotations; a
+  // MISSING pin file fails closed (keys/EXPECTED_FINGERPRINT ships in the
+  // tarball and is committed, so its absence is the signature of a tamper that
+  // stripped the pin to hide a swapped key).
+  const publicKey = loadPublicKey();
+  if (publicKey) {
+    const liveFp = publicKeyFingerprint(publicKey);
+    const pinResult = checkExpectedFingerprint(liveFp);
+    if (pinResult.status === 'mismatch' && !pinResult.rotationOverride) {
+      return {
+        status: 'invalid',
+        reason: `fingerprint-mismatch: live=${pinResult.actual} pin=${pinResult.expected} — keys/public.pem does not match keys/EXPECTED_FINGERPRINT. If this is an intentional rotation, set KEYS_ROTATED=1 and update the pin.`,
+        fingerprint_mismatch: true,
+        expected: pinResult.expected,
+        actual: pinResult.actual,
+      };
+    }
+    if (pinResult.status === 'no-pin') {
+      return {
+        status: 'invalid',
+        reason: `key-pin absent: keys/EXPECTED_FINGERPRINT is missing, so a swapped keys/public.pem cannot be detected. The pin ships in the tarball and is committed — restore it from the package or version control.`,
+        pin_absent: true,
+      };
+    }
+  }
   const sig = manifest && manifest.manifest_signature;
   if (!sig || typeof sig !== 'object') return { status: 'missing' };
   if (typeof sig.signature_base64 !== 'string') {
@@ -359,43 +392,11 @@ function verifyManifestSignature(manifest) {
       reason: `manifest_signature.algorithm must be exactly 'Ed25519' (got ${JSON.stringify(sig.algorithm)})`,
     };
   }
-  const publicKey = loadPublicKey();
   if (!publicKey) {
     return { status: 'no-key', reason: 'public key missing at keys/public.pem' };
   }
-  // consult keys/EXPECTED_FINGERPRINT BEFORE crypto.verify so
-  // library callers (refresh-network gate, verify-shipped-tarball gate, tests,
-  // downstream consumers via `require("lib/verify")`) cannot bypass the pin.
-  // Previously the pin only fired at the CLI tail of `node lib/verify.js`,
-  // letting a coordinated attacker who swapped keys/public.pem authenticate
-  // against the attacker key without any divergence surfaced through the
-  // library API. Honors KEYS_ROTATED=1 for legitimate rotations. A MISSING pin
-  // file is now rejected too: keys/EXPECTED_FINGERPRINT ships in the tarball and
-  // is committed to the repo, so its absence is not a legacy state — it is the
-  // signature a key-substitution attack leaves when it strips the pin to hide a
-  // swapped keys/public.pem.
-  const liveFp = publicKeyFingerprint(publicKey);
-  const pinResult = checkExpectedFingerprint(liveFp);
-  if (pinResult.status === 'mismatch' && !pinResult.rotationOverride) {
-    return {
-      status: 'invalid',
-      reason: `fingerprint-mismatch: live=${pinResult.actual} pin=${pinResult.expected} — keys/public.pem does not match keys/EXPECTED_FINGERPRINT. If this is an intentional rotation, set KEYS_ROTATED=1 and update the pin.`,
-      fingerprint_mismatch: true,
-      expected: pinResult.expected,
-      actual: pinResult.actual,
-    };
-  }
-  if (pinResult.status === 'no-pin') {
-    // A missing pin fails closed unconditionally — there is nothing to override.
-    // KEYS_ROTATED only applies to a fingerprint MISMATCH (a new key + a new
-    // pin); a legitimate rotation updates the pin in place, it never removes it,
-    // so an absent pin is treated as tampering and restoring it is the only fix.
-    return {
-      status: 'invalid',
-      reason: `key-pin absent: keys/EXPECTED_FINGERPRINT is missing, so a swapped keys/public.pem cannot be detected. The pin ships in the tarball and is committed — restore it from the package or version control.`,
-      pin_absent: true,
-    };
-  }
+  // The key-pin (mismatch / no-pin) was already verified up front, before any
+  // signature branching — so reaching here means the live key matches the pin.
   let signatureBytes;
   try {
     signatureBytes = Buffer.from(sig.signature_base64, 'base64');

package/lib/xml-tokenizer.js

@@ -110,6 +110,82 @@ function parseAttrs(rawAttrs) {
   return out;
 }
 
+/**
+ * Emit the character-data of a raw-text leaf element span `[start, end)`.
+ *
+ * CDATA sections inside the span are emitted verbatim (onCData if present,
+ * else onText) exactly like the main loop's CDATA fast-path; all other bytes
+ * — including a stray unescaped '<' or inline HTML — are entity-decoded and
+ * emitted via onText. Keeping the CDATA contract here means a `<![CDATA[...]]>`
+ * title still surfaces only its inner text, not the literal markers.
+ */
+function emitRawText(xml, start, end, H) {
+  let p = start;
+  while (p < end) {
+    const c = xml.indexOf("<![CDATA[", p);
+    if (c === -1 || c >= end) {
+      const chunk = xml.slice(p, end);
+      if (chunk.length && H.onText) H.onText(decodeEntities(chunk));
+      return;
+    }
+    if (c > p) {
+      const chunk = xml.slice(p, c);
+      if (chunk.length && H.onText) H.onText(decodeEntities(chunk));
+    }
+    const cend = xml.indexOf("]]>", c + 9);
+    // findRawTextEnd already guaranteed a terminated CDATA before the close
+    // tag, so cend is within range; guard anyway.
+    const inner = cend === -1 || cend > end ? xml.slice(c + 9, end) : xml.slice(c + 9, cend);
+    if (H.onCData) H.onCData(inner);
+    else if (H.onText) H.onText(inner);
+    p = cend === -1 || cend > end ? end : cend + 3;
+  }
+}
+
+/**
+ * Locate the matching close tag of a raw-text leaf element.
+ *
+ * Scans `xml` from `start` (the byte after the leaf open tag's `>`) for the
+ * first close tag `</...name>` whose local-name (namespace prefix stripped)
+ * equals `name`. CDATA sections are skipped verbatim so a `</title>` that
+ * legitimately appears inside `<![CDATA[ ... ]]>` is treated as literal text,
+ * not as the element's terminator.
+ *
+ * Returns { contentEnd, next } on success — `contentEnd` is the index of the
+ * close tag's leading `<`, `next` is the index just past its `>`. Returns null
+ * when no matching close tag exists before EOF (genuinely truncated input).
+ */
+function findRawTextEnd(xml, start, name) {
+  const len = xml.length;
+  let j = start;
+  while (j < len) {
+    const lt = xml.indexOf("<", j);
+    if (lt === -1) return null;
+    // Step over a CDATA section so its contents (which may contain "</name>"
+    // literally) cannot satisfy the close-tag match.
+    if (xml.startsWith("<![CDATA[", lt)) {
+      const cend = xml.indexOf("]]>", lt + 9);
+      if (cend === -1) return null; // unterminated CDATA → truncated
+      j = cend + 3;
+      continue;
+    }
+    if (xml[lt + 1] === "/") {
+      const gt = xml.indexOf(">", lt + 2);
+      if (gt === -1) return null;
+      const closeName = localName(xml.slice(lt + 2, gt).trim());
+      if (closeName === name) {
+        return { contentEnd: lt, next: gt + 1 };
+      }
+      j = gt + 1;
+      continue;
+    }
+    // Any other '<' (stray literal '<', or an inner open tag like <b>) is part
+    // of the leaf's character data — advance past it without classifying.
+    j = lt + 1;
+  }
+  return null;
+}
+
 /**
  * Streaming tokenizer. Calls handlers in document order. Returns no
  * value — accumulation is the caller's responsibility.
@@ -122,6 +198,17 @@ function parseAttrs(rawAttrs) {
  *   onComment(text)
  *   onPI(name, content)  processing instructions (<?xml-stylesheet?>)
  *   onError(message, position)
+ *
+ * Options (second-position fields on the handlers object):
+ *   rawTextElements   Set<string> of leaf-element local-names whose content
+ *                     is #PCDATA — once such an element opens, every byte up
+ *                     to the matching `</name>` close tag is treated as
+ *                     character data (entities decoded, then onText), exactly
+ *                     like the CDATA fast-path. This makes leaf fields tolerant
+ *                     of stray unescaped '<' (e.g. "affects versions < 5.0"),
+ *                     which real RSS/Atom routinely emits, instead of letting a
+ *                     recoverable lexical glitch silently drop the whole field.
+ *                     Structural parsing stays strict for container elements.
  */
 function tokenize(xml, handlers) {
   const H = handlers || {};
@@ -129,6 +216,7 @@ function tokenize(xml, handlers) {
     if (H.onError) H.onError("input must be a string", 0);
     return;
   }
+  const rawTextElements = H.rawTextElements instanceof Set ? H.rawTextElements : null;
   const len = xml.length;
   let i = 0;
   // Open-tag stack — surfaces EOF-with-unclosed-elements as an error
@@ -229,9 +317,33 @@ function tokenize(xml, handlers) {
       if (H.onTagClose) H.onTagClose(name);
     } else {
       const attrs = parseAttrs(rawAttrs);
-      if (!selfClose) openStack.push(name);
       if (H.onTagOpen) H.onTagOpen(name, attrs, selfClose);
-      if (selfClose && H.onTagClose) H.onTagClose(name);
+      if (selfClose) {
+        if (H.onTagClose) H.onTagClose(name);
+      } else if (rawTextElements && rawTextElements.has(name)) {
+        // Raw-text leaf element (title/summary/description/...). Its content
+        // is #PCDATA: scan to the matching `</name>` and treat the whole span
+        // as character data — only the matching close tag terminates it. Any
+        // inner '<...>' (a stray unescaped '<', or inline HTML like <b>) is
+        // preserved as text and normalized later by stripHtml(), instead of
+        // being misclassified as markup and silently dropping the field.
+        const span = findRawTextEnd(xml, close + 1, name);
+        if (span === null) {
+          // Genuinely truncated: the leaf never closes before EOF. Surface
+          // the loud-error contract just like the structural path would, then
+          // flush the residual as text and stop.
+          if (H.onError) H.onError("unterminated element at EOF: " + name, len);
+          const tail = xml.slice(close + 1);
+          if (tail.length && H.onText) H.onText(decodeEntities(tail));
+          return;
+        }
+        emitRawText(xml, close + 1, span.contentEnd, H);
+        if (H.onTagClose) H.onTagClose(name);
+        i = span.next;
+        continue;
+      } else {
+        openStack.push(name);
+      }
     }
     i = close + 1;
   }
@@ -240,15 +352,36 @@ function tokenize(xml, handlers) {
   }
 }
 
+// Leaf-element local-names whose content is character-data (#PCDATA). When
+// one of these opens, the tokenizer runs in raw-text mode until the matching
+// close tag, so a stray unescaped '<' inside the field (e.g. "affects
+// versions < 5.0") is preserved as text instead of being misclassified as
+// markup and silently dropping the whole field.
+const LEAF_FIELDS = new Set([
+  "title", "link", "pubDate", "published", "updated",
+  "description", "content", "summary",
+]);
+
+// rel-rank for Atom <link> sibling selection. RFC 4287: a <link> with no rel
+// defaults to rel="alternate", the canonical article URL. A non-alternate rel
+// (self / replies / edit / enclosure) should never clobber an alternate.
+function relRank(rel) {
+  if (rel == null || rel === "" || String(rel).toLowerCase() === "alternate") return 2;
+  return 1;
+}
+
 /**
- * Parse an RSS / Atom feed into a flat array of items. Returns:
- *   [{ title, link, published, body, raw_attrs: {...} }, ...]
+ * Parse an RSS / Atom feed, always collecting parse errors.
+ *
+ * Returns { items, errors } where errors is an array of
+ * { message, position } records. This is the channel a caller cannot forget
+ * to opt into — parseFeed() below is a thin back-compat wrapper.
  *
- * Empty array on parse failure. `errors` (out-of-band) captured via
- * the optional `errors` array — callers wanting observability pass it.
+ *   items: [{ title, link, published, body }, ...]
  */
-function parseFeed(xml, errors = null) {
+function parseFeedDetailed(xml) {
   const items = [];
+  const errors = [];
   // Stack of "in-progress item" contexts. RSS uses <item>; Atom uses
   // <entry>; both nest title / link / pubDate / published / updated /
   // description / content / summary.
@@ -266,25 +399,34 @@ function parseFeed(xml, errors = null) {
   let current = null;       // active item context
   let activeField = null;   // active field local-name
   let buffer = "";          // accumulator for current field text
-  let linkHref = null;      // captured from <link href="..."/> attribute
+  let linkRank = 0;         // rel-rank of the best <link> captured so far
 
   tokenize(xml, {
+    rawTextElements: LEAF_FIELDS,
     onTagOpen(name, attrs, selfClosing) {
       if (ITEM_LOCALS.has(name)) {
         current = { title: "", link: "", published: "", body: "" };
+        linkRank = 0;
         return;
       }
       if (!current) return;
       if (FIELD_MAP[name]) {
         activeField = FIELD_MAP[name];
         buffer = "";
-        // Atom <link href="..."/> — capture the href attribute as the
-        // link value. RSS <link>...</link> uses element text instead.
-        if (name === "link" && attrs && attrs.href) linkHref = attrs.href;
-        if (selfClosing && name === "link" && linkHref) {
-          current.link = linkHref;
-          linkHref = null;
-          activeField = null;
+        // Atom <link href="..."/> — rel-aware selection. Only let an
+        // alternate / rel-absent link upgrade the captured value, and never
+        // let a non-alternate rel (self/replies/edit) clobber an alternate
+        // already in hand. First-alternate-wins, independent of document
+        // order.
+        if (name === "link" && attrs && attrs.href) {
+          const r = relRank(attrs.rel);
+          if (r > linkRank) {
+            current.link = attrs.href;
+            linkRank = r;
+          }
+          // The link value has been resolved from the attribute — there is
+          // no element-text close to wait for.
+          if (selfClosing) activeField = null;
         }
       }
     },
@@ -294,28 +436,31 @@ function parseFeed(xml, errors = null) {
         current = null;
         activeField = null;
         buffer = "";
+        linkRank = 0;
         return;
       }
       if (!current) return;
       if (FIELD_MAP[name] && activeField === FIELD_MAP[name]) {
         const value = buffer.trim();
-        // Element-text link overrides the attribute capture when
-        // both are present.
-        if (name === "link" && value) {
-          current.link = value;
-        } else if (name === "link" && !value && linkHref) {
-          current.link = linkHref;
+        // RSS <link>...</link> — element text is authoritative (rank 2),
+        // unconditional. An empty element-text link falls back to whatever
+        // attribute capture onTagOpen already recorded.
+        if (name === "link") {
+          if (value) {
+            current.link = value;
+            linkRank = 2;
+          }
         } else if (activeField === "body" || activeField === "title") {
           // Strip HTML tags from title + description / content / summary.
           // Many feeds embed inline HTML (<b>, <em>, <a>) in titles for
           // emphasis; the operational consumer wants plain text. CDATA
           // content reaches here verbatim, so this also strips HTML
-          // that was wrapped in CDATA to dodge entity-encoding.
+          // that was wrapped in CDATA to dodge entity-encoding. A stray
+          // unescaped '<' that survived raw-text mode collapses here too.
           current[activeField] = stripHtml(value);
         } else {
           current[activeField] = value;
         }
-        linkHref = null;
         activeField = null;
         buffer = "";
       }
@@ -327,10 +472,27 @@ function parseFeed(xml, errors = null) {
       if (activeField) buffer += text;
     },
     onError(msg, pos) {
-      if (errors) errors.push({ message: msg, position: pos });
+      errors.push({ message: msg, position: pos });
     }
   });
 
+  return { items, errors };
+}
+
+/**
+ * Parse an RSS / Atom feed into a flat array of items. Returns:
+ *   [{ title, link, published, body }, ...]
+ *
+ * Empty array on parse failure. Errors are ALWAYS collected internally; the
+ * optional `errors` array is filled for callers that pass one (back-compat).
+ * Prefer parseFeedDetailed(xml) for new callers — it returns the errors
+ * channel unconditionally so it cannot be silently dropped.
+ */
+function parseFeed(xml, errors = null) {
+  const { items, errors: collected } = parseFeedDetailed(xml);
+  if (Array.isArray(errors)) {
+    for (const e of collected) errors.push(e);
+  }
   return items;
 }
 
@@ -341,4 +503,4 @@ function stripHtml(s) {
   return s.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
 }
 
-module.exports = { tokenize, parseFeed, decodeEntities, localName, parseAttrs, stripHtml };
+module.exports = { tokenize, parseFeed, parseFeedDetailed, decodeEntities, localName, parseAttrs, stripHtml };