@blamejs/exceptd-skills 0.12.22 → 0.12.24

package/lib/flag-suggest.js

@@ -0,0 +1,130 @@
+'use strict';
+
+/**
+ * Levenshtein-distance flag-typo suggestions.
+ *
+ * Operator typos `--evidnce` / `--csaf-stats` / `--bundle-epohc` were silently
+ * absorbed by the argv parser, falling through as boolean true flags with no
+ * value, then producing cryptic downstream errors. This helper compares an
+ * unknown flag to a verb-scoped allowlist and returns the closest match at
+ * distance ≤ 2 AND ≤ floor(flag.length / 2).
+ *
+ * Per-verb allowlists are the canonical CLI surface. Adding a new flag to a
+ * verb means appending to the allowlist here AND updating the printPlaybookVerbHelp
+ * block; a test asserts the two sets agree.
+ */
+
+function editDistance(a, b) {
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  const prev = new Array(b.length + 1);
+  const curr = new Array(b.length + 1);
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(
+        curr[j - 1] + 1,
+        prev[j] + 1,
+        prev[j - 1] + cost,
+      );
+    }
+    for (let j = 0; j <= b.length; j++) prev[j] = curr[j];
+  }
+  return prev[b.length];
+}
+
+/**
+ * Suggest the closest allowlisted flag to a given unknown flag.
+ *
+ * @param {string} flag - operator-supplied flag name without leading --
+ * @param {string[]} allowlist - known flag names for the active verb
+ * @returns {string|null} the suggested flag name or null when no close match
+ */
+function suggestFlag(flag, allowlist) {
+  if (typeof flag !== 'string' || flag.length === 0) return null;
+  if (!Array.isArray(allowlist) || allowlist.length === 0) return null;
+  const probe = flag.toLowerCase();
+  const cap = Math.min(2, Math.floor(flag.length / 2));
+  let bestDist = Infinity;
+  let best = null;
+  for (const candidate of allowlist) {
+    const d = editDistance(probe, candidate.toLowerCase());
+    if (d < bestDist && d <= cap) {
+      bestDist = d;
+      best = candidate;
+    }
+  }
+  return best;
+}
+
+/**
+ * Per-verb known-flag allowlist. Every operator-facing flag should appear
+ * exactly once per verb where it is consumed. Flags consumed by every verb
+ * (e.g. `pretty`, `json`, `help`) live under '_global'.
+ */
+const VERB_FLAG_ALLOWLIST = Object.freeze({
+  _global: ['help', 'pretty', 'json', 'verbose'],
+  run: [
+    'evidence', 'evidence-dir', 'session-id', 'force-overwrite', 'attestation-root',
+    'mode', 'air-gap', 'force-stale', 'operator', 'ack', 'csaf-status',
+    'publisher-namespace', 'vex', 'diff-from-latest', 'all', 'scope',
+    'strict-preconditions', 'ci', 'block-on-jurisdiction-clock', 'upstream-check',
+    'session-key', 'tlp', 'bundle-deterministic', 'bundle-epoch',
+  ],
+  ci: [
+    'evidence', 'evidence-dir', 'session-id', 'force-overwrite', 'attestation-root',
+    'mode', 'air-gap', 'force-stale', 'operator', 'ack', 'csaf-status',
+    'publisher-namespace', 'vex', 'all', 'scope', 'required', 'format',
+    'strict-preconditions', 'block-on-jurisdiction-clock', 'tlp',
+  ],
+  'run-all': [
+    'evidence', 'evidence-dir', 'session-id', 'force-overwrite', 'attestation-root',
+    'mode', 'air-gap', 'force-stale', 'operator', 'ack', 'csaf-status',
+    'publisher-namespace', 'vex', 'scope', 'strict-preconditions', 'tlp',
+  ],
+  'ai-run': [
+    'evidence', 'no-stream', 'session-id', 'force-overwrite', 'attestation-root',
+    'operator', 'ack', 'csaf-status', 'publisher-namespace', 'air-gap',
+    'mode', 'force-stale', 'tlp',
+  ],
+  ingest: [
+    'evidence', 'session-id', 'force-overwrite', 'attestation-root', 'operator',
+    'ack', 'csaf-status', 'publisher-namespace', 'air-gap', 'force-stale',
+    'strict-preconditions',
+  ],
+  brief: ['all', 'scope', 'directives', 'flat', 'phase'],
+  discover: ['scan-only', 'scope'],
+  ask: [],
+  attest: [
+    'against', 'playbook', 'since', 'latest', 'format', 'force', 'dry-run',
+    'all-older-than',
+  ],
+  reattest: [
+    'playbook', 'since', 'latest', 'force-replay', 'attestation-root',
+  ],
+  doctor: ['signatures', 'cves', 'rfcs', 'fix', 'registry-check', 'exit-codes'],
+  lint: ['evidence'],
+  refresh: [
+    'apply', 'dry-run', 'from-cache', 'from-fixture', 'network', 'source',
+    'advisory', 'force-stale', 'force-stale-acked', 'air-gap', 'swarm',
+  ],
+  prefetch: ['source', 'cache-dir', 'max-age', 'force', 'no-network', 'quiet'],
+});
+
+/**
+ * Return the allowlist for a verb (global flags always included).
+ */
+function flagsFor(verb) {
+  const verbFlags = VERB_FLAG_ALLOWLIST[verb] || [];
+  return [...VERB_FLAG_ALLOWLIST._global, ...verbFlags];
+}
+
+module.exports = {
+  editDistance,
+  suggestFlag,
+  flagsFor,
+  VERB_FLAG_ALLOWLIST,
+};

package/lib/id-validation.js

@@ -0,0 +1,95 @@
+'use strict';
+
+/**
+ * Shared validation for path-component-shaped operator inputs.
+ *
+ * Six sites in `bin/exceptd.js` previously hand-rolled regexes of the form
+ * /^[A-Za-z0-9._-]{1,64}$/ for `--session-id`, `--playbook`, attestation
+ * filenames, and `--evidence-dir` filenames. Each regex was slightly
+ * different in character class ordering; each grew its own follow-on checks
+ * (all-dots refusal, length cap, leading-dot refusal) at different rates.
+ *
+ * This module is the single source of truth. Adding a new path-component
+ * input means calling `validateIdComponent(value, role)` and propagating
+ * the returned {ok, reason} pair to the caller's emit-error path.
+ *
+ * Three role types, three character classes:
+ *   - 'session'  — sessions live under `.exceptd/attestations/<sid>/`. Allow
+ *                  lower+upper alpha, digit, dot, underscore, hyphen, 1-64
+ *                  chars. Refuse all-dots.
+ *   - 'playbook' — playbook ids index `data/playbooks/<id>.json`. Stricter:
+ *                  lowercase-only, must start with a letter, no dots (all
+ *                  catalogued playbook ids match `/^[a-z][a-z0-9-]{0,63}$/`).
+ *   - 'filename' — attestation filename inside a session directory. Same
+ *                  charset as 'session' but length cap reflects filename
+ *                  policy (no path separators ever).
+ *
+ * The function never reads the filesystem; combine with realpathSync at
+ * the caller for full path-traversal defense.
+ */
+
+const SESSION_RE = /^[A-Za-z0-9._-]{1,64}$/;
+const PLAYBOOK_RE = /^[a-z][a-z0-9-]{0,63}$/;
+const FILENAME_RE = /^[A-Za-z0-9._-]{1,80}$/;
+const ALL_DOTS_RE = /^\.+$/;
+
+function validateIdComponent(value, role) {
+  if (typeof value !== 'string') {
+    return { ok: false, reason: `expected string, got ${typeof value}` };
+  }
+  if (value.length === 0) {
+    return { ok: false, reason: 'must not be empty' };
+  }
+  let re;
+  let constraint;
+  switch (role) {
+    case 'session':
+      re = SESSION_RE;
+      constraint = '^[A-Za-z0-9._-]{1,64}$';
+      break;
+    case 'playbook':
+      re = PLAYBOOK_RE;
+      constraint = '^[a-z][a-z0-9-]{0,63}$ (lowercase, starts with letter, no dots)';
+      break;
+    case 'filename':
+      re = FILENAME_RE;
+      constraint = '^[A-Za-z0-9._-]{1,80}$';
+      break;
+    default:
+      return { ok: false, reason: `unknown role: ${role}` };
+  }
+  if (!re.test(value)) {
+    return { ok: false, reason: `must match ${constraint}` };
+  }
+  // All-dots refusal applies after the character-class regex because the
+  // session/filename classes admit any string of dots (`.`, `..`, `...`),
+  // each of which path-resolves into or above the intended directory.
+  if (ALL_DOTS_RE.test(value)) {
+    return { ok: false, reason: 'must not consist entirely of dots' };
+  }
+  return { ok: true };
+}
+
+/**
+ * Cheap typed-throw wrapper for callers that prefer exceptions over result
+ * objects (lib/playbook-runner.js uses this shape for loadPlaybook).
+ */
+function assertIdComponent(value, role) {
+  const r = validateIdComponent(value, role);
+  if (!r.ok) {
+    const err = new Error(`invalid ${role} id (${r.reason}): ${typeof value === 'string' ? value.slice(0, 80) : typeof value}`);
+    err.code = 'EXCEPTD_INVALID_ID';
+    err.role = role;
+    err.reason = r.reason;
+    throw err;
+  }
+  return value;
+}
+
+module.exports = {
+  validateIdComponent,
+  assertIdComponent,
+  SESSION_RE,
+  PLAYBOOK_RE,
+  FILENAME_RE,
+};

package/lib/lint-skills.js

@@ -162,11 +162,11 @@ function readJson(p) {
 function parseFrontmatter(text) {
   const lines = text.split(/\r?\n/);
   const result = {};
-  // S4: track every top-level key we've already assigned. YAML's
-  // last-wins semantics would let a tampered skill set name twice
-  // ("name: real-skill\nname: evil-skill") and silently take the
-  // second value — a skill-identity spoofing primitive. Refuse
-  // duplicates outright; an honest skill never has them.
+  // Track every top-level key we've already assigned. YAML's last-wins
+  // semantics would let a tampered skill set name twice
+  // ("name: real-skill\nname: evil-skill") and silently take the second
+  // value — a skill-identity spoofing primitive. Refuse duplicates
+  // outright; an honest skill never has them.
   const seenKeys = new Set();
   let i = 0;
   while (i < lines.length) {
@@ -655,6 +655,59 @@ function findOrphanSkillFiles(manifestSkills) {
   return orphans;
 }
 
+// Substrings that indicate an artifact `source` makes a network call. Used
+// by lintPlaybookAirGap() to flag artifacts that lack an air_gap_alternative.
+// Conservative-by-design — false positives are surfaced as `warn` (not
+// `error`) and a playbook author who has reviewed the source can suppress
+// by adding an air_gap_alternative even when the source itself is offline.
+const PLAYBOOK_NET_PATTERNS = [
+  'https://', 'http://', 'gh api', 'gh release', 'curl ', 'wget ', 'fetch ',
+];
+
+const PLAYBOOK_DIR = path.join(DATA_DIR, 'playbooks');
+
+/**
+ * Air-gap completeness lint for shipped playbooks. Walks every
+ * data/playbooks/*.json file, examines phases.look.artifacts[], and warns
+ * when an artifact's `source` contains a network-call substring without a
+ * sibling `air_gap_alternative`. The playbook schema's hard `if/then`
+ * conditional (added v0.12.24) catches this for playbooks marked
+ * `_meta.air_gap_mode: true`; this lint surfaces the gap for every
+ * playbook, on the principle that a non-air-gap playbook may still be
+ * invoked under `exceptd --air-gap` and operators deserve the warning.
+ *
+ * Returns an array of `{ playbook, artifact_id, source }` warning records.
+ */
+function lintPlaybookAirGap() {
+  const warnings = [];
+  if (!fs.existsSync(PLAYBOOK_DIR)) return warnings;
+  const files = fs.readdirSync(PLAYBOOK_DIR).filter(f => f.endsWith('.json') && !f.startsWith('_'));
+  for (const f of files) {
+    let playbook;
+    try {
+      playbook = readJson(path.join(PLAYBOOK_DIR, f));
+    } catch {
+      continue; // schema validator catches parse errors separately
+    }
+    const arts = playbook && playbook.phases && playbook.phases.look && playbook.phases.look.artifacts;
+    if (!Array.isArray(arts)) continue;
+    for (const a of arts) {
+      if (!a || typeof a !== 'object') continue;
+      const src = a.source;
+      if (typeof src !== 'string') continue;
+      const isNet = PLAYBOOK_NET_PATTERNS.some(p => src.includes(p));
+      if (isNet && !a.air_gap_alternative) {
+        warnings.push({
+          playbook: playbook._meta && playbook._meta.id ? playbook._meta.id : f.replace(/\.json$/, ''),
+          artifact_id: a.id || '<unknown>',
+          source: src,
+        });
+      }
+    }
+  }
+  return warnings;
+}
+
 function main() {
   const opts = parseArgs(process.argv);
   const manifest = readJson(MANIFEST_PATH);
@@ -700,6 +753,7 @@ function main() {
   // A targeted single-skill lint is for diagnosing one entry; running
   // the orphan walk there would surface unrelated findings.
   let orphans = [];
+  let airGapWarnings = [];
   if (!opts.skill) {
     orphans = findOrphanSkillFiles(manifest.skills);
     for (const o of orphans) {
@@ -707,14 +761,25 @@ function main() {
       console.log(`        - skill.md exists on disk but not in manifest: ${o}`);
       console.log(`          fix: re-run \`node lib/sign.js sign-all\` after adding it to manifest.json, OR delete the orphan directory`);
     }
+    // P4 — air-gap completeness lint over data/playbooks/*.json.
+    airGapWarnings = lintPlaybookAirGap();
+    for (const w of airGapWarnings) {
+      console.log(`WARN  playbook:${w.playbook}`);
+      console.log(`        - [warn] artifact "${w.artifact_id}" source contains a network call but has no air_gap_alternative`);
+      console.log(`                 source: ${w.source}`);
+      console.log(`                 fix: add an air_gap_alternative source (offline file path / packaged dataset / pre-staged artifact)`);
+    }
   }
 
   const total = results.length;
   const passed = total - failed - warned;
   const orphanSummary = orphans.length ? `, ${orphans.length} orphan skill.md file(s)` : '';
   const warnSummary = warned ? `, ${warned} with warnings` : '';
+  const airGapSummary = airGapWarnings && airGapWarnings.length
+    ? `, ${airGapWarnings.length} playbook artifact(s) missing air_gap_alternative`
+    : '';
   console.log(
-    `\n${passed}/${total} skills passed${warnSummary}${failed ? `, ${failed} failed` : ''}${orphanSummary}.`,
+    `\n${passed}/${total} skills passed${warnSummary}${failed ? `, ${failed} failed` : ''}${orphanSummary}${airGapSummary}.`,
   );
   process.exit(failed === 0 && orphans.length === 0 ? 0 : 1);
 }
@@ -727,6 +792,8 @@ module.exports = {
   unquote,
   findOrphanSkillFiles,
   findMissingSections,
+  lintPlaybookAirGap,
+  PLAYBOOK_NET_PATTERNS,
   REQUIRED_SECTIONS,
   COUNTERMEASURE_SECTION,
   COUNTERMEASURE_CUTOFF,