@blamejs/exceptd-skills 0.12.28 → 0.12.30

package/scripts/check-test-coverage.js

@@ -184,15 +184,29 @@ function readMaybe(p) {
 
 // --- Categorization ---------------------------------------------------------
 
+// Mechanical / contributor-only docs the gate auto-allows: their content
+// has no operator-facing semantic surface (CONTRIBUTING is for PRs;
+// LICENSE / NOTICE / CODE_OF_CONDUCT are boilerplate; .gitignore / .npmrc
+// / .editorconfig are tooling). Edits here never need a regression test.
 const DOCS_ALWAYS_GREEN = new Set([
-  "CHANGELOG.md", "README.md", "CONTRIBUTING.md", "SECURITY.md",
-  "LICENSE", "NOTICE", "CODE_OF_CONDUCT.md", "AGENTS.md", "CLAUDE.md",
-  "SUPPORT.md", "MIGRATING.md", ".gitignore", ".npmrc", ".editorconfig",
+  "CONTRIBUTING.md", "LICENSE", "NOTICE", "CODE_OF_CONDUCT.md",
+  "CLAUDE.md", "SUPPORT.md", ".gitignore", ".npmrc", ".editorconfig",
+]);
+
+// Cycle 9 finding: operator-facing docs (release notes, install instructions,
+// security disclosure policy, migration guides, AI-assistant ground truth)
+// previously auto-greened. A PR could land deceptive copy here without any
+// reviewer signal. Downgrade to manual-review so the diff surfaces in the
+// gate output — a human (or the maintainer reviewing the bot summary) at
+// least sees the change exists.
+const DOCS_MANUAL_REVIEW = new Set([
+  "CHANGELOG.md", "README.md", "SECURITY.md", "MIGRATING.md", "AGENTS.md",
 ]);
 
 function categorize(file) {
   const norm = file.replace(/\\/g, "/");
   if (DOCS_ALWAYS_GREEN.has(norm)) return "docs";
+  if (DOCS_MANUAL_REVIEW.has(norm)) return "manual-review";
   if (norm.startsWith("tests/")) return "test"; // no recursion
   if (norm.startsWith("docs/")) return "docs";
   if (norm.endsWith(".md") && !norm.startsWith("data/")) return "docs";
@@ -662,5 +676,5 @@ module.exports = {
   extractCliSurface, extractLibExports, extractPlaybookIds, extractCveIocChanges,
   coversCliVerb, coversCliFlag, coversLibExport, coversPlaybookId, coversCveIoc,
   scanForCoincidenceAsserts,
-  DOCS_ALWAYS_GREEN,
+  DOCS_ALWAYS_GREEN, DOCS_MANUAL_REVIEW,
 };

package/scripts/refresh-reverse-refs.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+/*
+ * scripts/refresh-reverse-refs.js — rebuild reverse references in
+ * data/{atlas-ttps,cwe-catalog,d3fend-catalog,rfc-references}.json from
+ * the manifest.json forward direction.
+ *
+ * Background. Each skill in manifest.json declares forward references via
+ * atlas_refs / cwe_refs / d3fend_refs / rfc_refs. The four catalogs above
+ * carry a denormalised reverse field per entry (`exceptd_skills` for
+ * atlas-ttps, `skills_referencing` for the other three) listing every
+ * skill that points at that entry. The reverse field drifts whenever a
+ * skill adds or removes a forward ref without the catalog being updated
+ * in lockstep — Cycle 9 audit found this drift in production.
+ *
+ * Behaviour. For each catalog file:
+ *   1. Walk every skill's relevant forward-ref array in manifest.json.
+ *   2. For every catalog entry, list every skill that references it.
+ *   3. Sort the resulting skill list and write it back into the per-entry
+ *      reverse field. All other fields are preserved untouched.
+ *
+ * The script is idempotent: a second run produces no further changes.
+ *
+ * The script does NOT touch playbooks_referencing — that field carries
+ * playbook ids (data/playbooks/*.json), not skill names; it has its own
+ * source of truth and is out of scope for this audit fix.
+ *
+ * Run:   node scripts/refresh-reverse-refs.js
+ *        npm run refresh-reverse-refs
+ *
+ * Exit code: 0 always (script is unconditionally write-mode). Use
+ * tests/reverse-ref-drift.test.js as the read-only drift detector.
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const MANIFEST_PATH = path.join(REPO_ROOT, 'manifest.json');
+const DATA_DIR = path.join(REPO_ROOT, 'data');
+
+/* Per-catalog config:
+ *   file              relative path under data/
+ *   forwardField      manifest.skills[].* array name
+ *   reverseField      per-entry reverse field name in the catalog
+ */
+const CATALOGS = [
+  {
+    file: 'atlas-ttps.json',
+    forwardField: 'atlas_refs',
+    reverseField: 'exceptd_skills',
+  },
+  {
+    file: 'cwe-catalog.json',
+    forwardField: 'cwe_refs',
+    reverseField: 'skills_referencing',
+  },
+  {
+    file: 'd3fend-catalog.json',
+    forwardField: 'd3fend_refs',
+    reverseField: 'skills_referencing',
+  },
+  {
+    file: 'rfc-references.json',
+    forwardField: 'rfc_refs',
+    reverseField: 'skills_referencing',
+  },
+];
+
+function readJson(p) {
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+function buildReverseIndex(skills, forwardField) {
+  // entryId -> Set<skillName>
+  const index = new Map();
+  for (const skill of skills) {
+    const refs = Array.isArray(skill[forwardField]) ? skill[forwardField] : [];
+    for (const id of refs) {
+      if (!index.has(id)) index.set(id, new Set());
+      index.get(id).add(skill.name);
+    }
+  }
+  return index;
+}
+
+function rebuildCatalog(cfg, manifest) {
+  const filePath = path.join(DATA_DIR, cfg.file);
+  const catalog = readJson(filePath);
+  const index = buildReverseIndex(manifest.skills, cfg.forwardField);
+  let changed = 0;
+  let added = 0;
+  let removed = 0;
+  let unchanged = 0;
+  const orphans = []; // forward refs that don't resolve to a catalog entry
+  const seenIds = new Set();
+
+  for (const [id, entry] of Object.entries(catalog)) {
+    if (id === '_meta') continue;
+    if (typeof entry !== 'object' || entry === null) continue;
+    seenIds.add(id);
+    const before = Array.isArray(entry[cfg.reverseField])
+      ? [...entry[cfg.reverseField]]
+      : [];
+    const computed = index.has(id)
+      ? Array.from(index.get(id)).sort()
+      : [];
+    const beforeSet = new Set(before);
+    const computedSet = new Set(computed);
+    const sameLen = before.length === computed.length;
+    const sameContent =
+      sameLen && before.every((s, i) => s === computed[i]);
+    if (!sameContent) {
+      entry[cfg.reverseField] = computed;
+      changed += 1;
+      for (const s of computed) if (!beforeSet.has(s)) added += 1;
+      for (const s of before) if (!computedSet.has(s)) removed += 1;
+    } else {
+      unchanged += 1;
+    }
+  }
+
+  // Surface forward refs that point at catalog entries that don't exist.
+  // Not fatal here — that's a separate validation concern — but we report.
+  for (const id of index.keys()) {
+    if (!seenIds.has(id)) orphans.push(id);
+  }
+
+  if (changed > 0) {
+    fs.writeFileSync(filePath, JSON.stringify(catalog, null, 2) + '\n', 'utf8');
+  }
+
+  return {
+    file: cfg.file,
+    changed,
+    added,
+    removed,
+    unchanged,
+    orphans,
+  };
+}
+
+function main() {
+  const manifest = readJson(MANIFEST_PATH);
+  const results = [];
+  for (const cfg of CATALOGS) {
+    results.push(rebuildCatalog(cfg, manifest));
+  }
+  for (const r of results) {
+    process.stdout.write(
+      `${r.file}: ${r.changed} entries changed ` +
+        `(+${r.added} / -${r.removed} skill refs), ` +
+        `${r.unchanged} unchanged` +
+        (r.orphans.length
+          ? `, ${r.orphans.length} orphan forward ref(s) [${r.orphans.join(', ')}]`
+          : '') +
+        '\n',
+    );
+  }
+}
+
+module.exports = {
+  CATALOGS,
+  buildReverseIndex,
+  rebuildCatalog,
+};
+
+if (require.main === module) {
+  main();
+}

package/scripts/refresh-sbom.js

@@ -15,12 +15,25 @@
  *                                    timestamp) so reruns produce a new
  *                                    UUID per refresh.
  *   - metadata.timestamp             ISO 8601 of generation
- *   - metadata.tools                 hand-written generator
- *   - metadata.component             application entry for exceptd-skills
+ *   - metadata.tools                 this script itself, version pulled
+ *                                    from package.json at refresh time
+ *   - metadata.component             application entry for exceptd-skills,
+ *                                    including a hashes[] bundle digest
+ *                                    that operators can recompute from
+ *                                    the per-file component list (see
+ *                                    `bundleDigest` below for the exact
+ *                                    canonical-input rule)
  *   - metadata.properties            catalog count, skill count, dataflow
  *                                    inputs, and the per-skill Ed25519
  *                                    integrity claim (lib/sign.js)
- *   - components                     [] — zero npm runtime deps
+ *   - components                     vendored libraries + a `type: file`
+ *                                    component per shipped file in the
+ *                                    package.json `files` allowlist, each
+ *                                    carrying its SHA-256 hash. Lets
+ *                                    CycloneDX-aware vuln scanners verify
+ *                                    individual files against the bundle
+ *                                    without re-deriving the canonical
+ *                                    list themselves.
  *   - dependencies                   [] — nothing to depend on
  *
  * Run:   node scripts/refresh-sbom.js
@@ -85,6 +98,128 @@ function loadVendorProvenance() {
   }
 }
 
+/* Recursively expand a `package.json.files` allowlist entry into the
+ * concrete file list that npm pack would ship. The allowlist accepts
+ * either a file path or a directory path (with trailing slash convention
+ * inside this repo); directories expand to every regular file beneath
+ * them. Returned paths are POSIX-style relative to REPO_ROOT so the
+ * SHA-256 input is stable across operating systems.
+ *
+ * Mirrors npm's pack-time inclusion rules at the level of fidelity this
+ * SBOM needs (a deeper match — .npmignore, package-lock fields, npm-CLI
+ * defaults — is intentionally out of scope: any divergence here surfaces
+ * as a SHA mismatch on the predeploy verify-shipped-tarball gate, which
+ * is the authoritative consumer-side check).
+ */
+function walkFiles(absDir) {
+  const out = [];
+  const entries = fs.readdirSync(absDir, { withFileTypes: true });
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    const abs = path.join(absDir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...walkFiles(abs));
+    } else if (entry.isFile()) {
+      out.push(abs);
+    }
+  }
+  return out;
+}
+
+/* Files that cannot have a stable SHA inside the SBOM they belong to.
+ * `sbom.cdx.json` is the obvious self-reference: hashing it would always
+ * be stale the moment the SBOM gets written back. The bundle digest in
+ * metadata.component.hashes[] covers everything ELSE that ships and is
+ * the operator's verification anchor for the bundle as a whole. */
+const SELF_EXCLUDED = new Set(['sbom.cdx.json']);
+
+/* Path prefixes whose contents are derivable / cache-class artifacts.
+ * `data/_indexes/` is the pre-computed index cache that ships in the
+ * tarball but is regenerated by `npm run build-indexes`. The test suite
+ * deliberately mutates these files (build-incremental.test.js,
+ * indexes-v070.test.js), so per-file SHA verification would race against
+ * any test run that touches the cache between refresh-sbom and the
+ * verification gate. The bundle digest at metadata.component.hashes[] is
+ * computed from a SBOM-generation-time snapshot of all OTHER files; the
+ * cache is excluded from the per-file inventory entirely. Predeploy's
+ * `Pre-computed indexes freshness` gate is the authoritative consumer-
+ * side check for the cache. */
+const DERIVABLE_PREFIXES = ['data/_indexes/'];
+
+function isDerivable(rel) {
+  return DERIVABLE_PREFIXES.some((p) => rel === p.replace(/\/$/, '') || rel.startsWith(p));
+}
+
+function expandAllowlist(allowlist) {
+  const abs = [];
+  for (const entry of allowlist) {
+    const full = path.join(REPO_ROOT, entry);
+    if (!fs.existsSync(full)) continue; // tolerate a stale entry; predeploy gate flags
+    const stat = fs.statSync(full);
+    if (stat.isDirectory()) {
+      abs.push(...walkFiles(full));
+    } else if (stat.isFile()) {
+      abs.push(full);
+    }
+  }
+  // dedupe + sort by relative POSIX path for deterministic output;
+  // strip self-referential entries (see SELF_EXCLUDED) and derivable cache
+  // entries (see DERIVABLE_PREFIXES).
+  const rel = Array.from(new Set(abs.map((a) => toPosixRel(a))))
+    .filter((r) => !SELF_EXCLUDED.has(r))
+    .filter((r) => !isDerivable(r))
+    .sort();
+  return rel;
+}
+
+function toPosixRel(absPath) {
+  return path
+    .relative(REPO_ROOT, absPath)
+    .split(path.sep)
+    .join('/');
+}
+
+function sha256File(absPath) {
+  return crypto
+    .createHash('sha256')
+    .update(fs.readFileSync(absPath))
+    .digest('hex');
+}
+
+function fileComponents(allowlist) {
+  const rels = expandAllowlist(allowlist);
+  const out = [];
+  for (const rel of rels) {
+    const abs = path.join(REPO_ROOT, rel);
+    out.push({
+      'bom-ref': `file:${rel}`,
+      type: 'file',
+      name: rel,
+      hashes: [{ alg: 'SHA-256', content: sha256File(abs) }],
+    });
+  }
+  return out;
+}
+
+/* Bundle digest = SHA-256 over a deterministic newline-delimited
+ * "<sha256>\t<relpath>\n" stream of every shipped file, sorted by
+ * relpath. The same input shape an operator would assemble from the
+ * components[] list (`type: file` entries) lets them recompute and
+ * compare without trusting the SBOM's stored value blindly.
+ */
+function bundleDigest(fileComps) {
+  const sorted = [...fileComps].sort((a, b) =>
+    a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
+  );
+  const hash = crypto.createHash('sha256');
+  for (const c of sorted) {
+    hash.update(c.hashes[0].content);
+    hash.update('\t');
+    hash.update(c.name);
+    hash.update('\n');
+  }
+  return hash.digest('hex');
+}
+
 function vendorComponents(prov) {
   if (!prov || !prov.files) return [];
   const out = [];
@@ -119,6 +254,14 @@ function buildSbom() {
   const catalogCount = catalogs.length;
   const vendorProv = loadVendorProvenance();
   const vendoredComponents = vendorComponents(vendorProv);
+  const fileComps = fileComponents(Array.isArray(pkg.files) ? pkg.files : []);
+  const bundleSha = bundleDigest(fileComps);
+
+  // Sort the union of vendor + file components by bom-ref for
+  // deterministic regeneration.
+  const allComponents = [...vendoredComponents, ...fileComps].sort((a, b) =>
+    a['bom-ref'] < b['bom-ref'] ? -1 : a['bom-ref'] > b['bom-ref'] ? 1 : 0,
+  );
 
   const serialNumber =
     'urn:uuid:' +
@@ -137,10 +280,9 @@ function buildSbom() {
       timestamp: timestamp,
       tools: [
         {
-          name: 'hand-written',
-          version: '0.1.0',
-          description:
-            'SBOM generated from package.json + manual review (scripts/refresh-sbom.js).',
+          vendor: 'blamejs',
+          name: 'scripts/refresh-sbom.js',
+          version: pkg.version,
         },
       ],
       component: {
@@ -154,6 +296,11 @@ function buildSbom() {
         description: pkg.description,
         licenses: [{ license: { id: 'Apache-2.0' } }],
         purl: `pkg:npm/${pkg.name.replace('@', '%40')}@${pkg.version}`,
+        // Bundle digest over every shipped file (see bundleDigest above
+        // for the canonical-input rule). Operators can recompute this
+        // from the per-file components[] list and compare without
+        // re-deriving package.json.files themselves.
+        hashes: [{ alg: 'SHA-256', content: bundleSha }],
         externalReferences: [
           { type: 'distribution', url: `https://www.npmjs.com/package/${pkg.name}/v/${pkg.version}` },
           { type: 'vcs', url: (pkg.repository && pkg.repository.url) || 'https://github.com/blamejs/exceptd-skills' },
@@ -196,7 +343,7 @@ function buildSbom() {
         },
       ],
     },
-    components: vendoredComponents,
+    components: allComponents,
     dependencies: [],
   };