@blamejs/exceptd-skills 0.12.11 → 0.12.15

package/lib/verify.js

@@ -8,6 +8,28 @@
  * specific keypair signed each skill. Even if the manifest is updated, a valid
  * signature requires the private key, which never enters this repository.
  *
+ * Byte-stability contract (must mirror lib/sign.js):
+ *   Skill content is normalized BEFORE the signature is verified:
+ *     1. Strip a UTF-8 BOM (U+FEFF) if present.
+ *     2. Convert CRLF line endings to LF.
+ *   The same normalization runs in lib/sign.js. A skill file checked
+ *   out with core.autocrlf=true on Windows therefore verifies against
+ *   a signature produced on Linux CI (LF). ANY change to normalize()
+ *   requires the matching change in lib/sign.js — round-trip stability
+ *   is a hard contract. The v0.11.x signature regression (operators
+ *   ran `exceptd doctor --signatures` and saw 0/38) was a single
+ *   instance of this contract drifting; do not relax it.
+ *
+ * Manifest entries are validated through validateSkillPath() before
+ * any file is read. A tampered manifest with `path: "../../../etc/passwd"`
+ * cannot escape the skills/ tree. The whole manifest is rejected on
+ * the first traversal attempt.
+ *
+ * The manifest object itself is validated against
+ * lib/schemas/manifest.schema.json before any skill is touched.
+ * additionalProperties=false at the skill level catches typos and
+ * unknown fields that would otherwise silently be dropped.
+ *
  * Signing ceremony: see lib/sign.js
  * Public key: keys/public.pem (tracked in repo)
  * Private key: .keys/private.pem (gitignored, kept off-repo)
@@ -28,6 +50,15 @@ const MANIFEST_PATH = path.join(ROOT, 'manifest.json');
 const SKILLS_DIR = path.join(ROOT, 'skills');
 const PUBLIC_KEY_PATH = path.join(ROOT, 'keys', 'public.pem');
 const PRIVATE_KEY_PATH = path.join(ROOT, '.keys', 'private.pem');
+const MANIFEST_SCHEMA_PATH = path.join(__dirname, 'schemas', 'manifest.schema.json');
+// Audit G F4 — key-pin file. When present, lib/verify.js compares the live
+// public-key fingerprint against the pinned one and fails the verify run
+// if they differ (unless the operator sets KEYS_ROTATED=1). The file format
+// is a single line "SHA256:<base64>" matching the publicKeyFingerprint()
+// shape. The file is OPTIONAL: when missing, the gate warns-and-continues
+// rather than failing — this preserves bootstrap compatibility on fresh
+// clones / new key ceremonies. Patch-class semantics.
+const EXPECTED_FINGERPRINT_PATH = path.join(ROOT, 'keys', 'EXPECTED_FINGERPRINT');
 
 // --- public API ---
 
@@ -42,7 +73,7 @@ function verifyAll() {
     return { valid: [], invalid: [], missing_sig: [], missing_file: [], no_key: true };
   }
 
-  const manifest = loadManifest();
+  const manifest = loadManifestValidated();
   const result = { valid: [], invalid: [], missing_sig: [], missing_file: [], no_key: false };
 
   for (const skill of manifest.skills) {
@@ -65,7 +96,7 @@ function verifyOne(skillName) {
   const publicKey = loadPublicKey();
   if (!publicKey) throw new Error('No public key at keys/public.pem');
 
-  const manifest = loadManifest();
+  const manifest = loadManifestValidated();
   const skill = manifest.skills.find(s => s.name === skillName);
   if (!skill) throw new Error(`Skill not in manifest: ${skillName}`);
 
@@ -81,7 +112,7 @@ function signAll() {
   const privateKey = loadPrivateKey();
   if (!privateKey) throw new Error('No private key at .keys/private.pem — run: node lib/sign.js generate-keypair');
 
-  const manifest = loadManifest();
+  const manifest = loadManifestValidated();
   const result = { signed: [], errors: [] };
 
   for (const skill of manifest.skills) {
@@ -104,6 +135,56 @@ function signAll() {
 
 // --- private helpers ---
 
+/**
+ * Normalize skill content for byte-stable verification.
+ *
+ * Strips a leading UTF-8 BOM (U+FEFF) if present, then converts CRLF
+ * line endings to LF. lib/sign.js applies the exact same transform —
+ * see the byte-stability contract in the file header.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+function normalize(content) {
+  let s = content;
+  if (s.length > 0 && s.charCodeAt(0) === 0xFEFF) s = s.slice(1);
+  return s.replace(/\r\n/g, '\n');
+}
+
+/**
+ * Validate a manifest skill.path entry to prevent path traversal.
+ *
+ *   skill.path MUST be a string.
+ *   skill.path MUST start with "skills/".
+ *   skill.path MUST NOT contain "..".
+ *   skill.path MUST NOT contain backslashes.
+ *
+ * Same shape as lib/sign.js validateSkillPath(); the two functions
+ * are intentionally duplicated rather than cross-imported so the
+ * verify path has no runtime dependency on the sign path.
+ *
+ * @param {string} skillPath
+ * @returns {string}
+ */
+function validateSkillPath(skillPath) {
+  if (typeof skillPath !== 'string') {
+    throw new Error(`[verify] manifest skill.path must be a string, got ${typeof skillPath}`);
+  }
+  // Backslash check runs BEFORE the prefix check so a Windows-style
+  // path ("skills\foo\skill.md") returns the clearer "use forward
+  // slashes" diagnostic, not the misleading "must start with skills/".
+  if (skillPath.includes('\\')) {
+    throw new Error(`[verify] manifest skill.path must use forward slashes, not backslashes: ${JSON.stringify(skillPath)}`);
+  }
+  if (!skillPath.startsWith('skills/')) {
+    throw new Error(`[verify] manifest skill.path must start with 'skills/': ${JSON.stringify(skillPath)}`);
+  }
+  if (skillPath.includes('..')) {
+    throw new Error(`[verify] manifest skill.path must not contain '..': ${JSON.stringify(skillPath)}`);
+  }
+  return skillPath;
+}
+
 function verifySkill(skill, publicKey) {
   if (!skill.signature) {
     return { status: 'missing_sig', reason: 'No Ed25519 signature in manifest — run: node lib/sign.js sign-all' };
@@ -128,7 +209,8 @@ function verifySkill(skill, publicKey) {
 }
 
 function sign(content, privateKey) {
-  const signature = crypto.sign(null, Buffer.from(content, 'utf8'), {
+  const normalized = normalize(content);
+  const signature = crypto.sign(null, Buffer.from(normalized, 'utf8'), {
     key: privateKey,
     dsaEncoding: 'ieee-p1363'
   });
@@ -138,7 +220,8 @@ function sign(content, privateKey) {
 function verify(content, signatureBase64, publicKey) {
   try {
     const signature = Buffer.from(signatureBase64, 'base64');
-    return crypto.verify(null, Buffer.from(content, 'utf8'), {
+    const normalized = normalize(content);
+    return crypto.verify(null, Buffer.from(normalized, 'utf8'), {
       key: publicKey,
       dsaEncoding: 'ieee-p1363'
     }, signature);
@@ -161,6 +244,136 @@ function loadManifest() {
   return JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf8'));
 }
 
+/**
+ * Load the manifest and validate it against
+ * lib/schemas/manifest.schema.json + the path-traversal guard.
+ *
+ * Throws on schema violation OR traversal-pattern paths. Either case
+ * is a fatal-class bug — surface it loudly rather than verify-against-
+ * a-corrupt-manifest.
+ *
+ * @returns {object}
+ */
+function loadManifestValidated() {
+  const manifest = loadManifest();
+  const schema = JSON.parse(fs.readFileSync(MANIFEST_SCHEMA_PATH, 'utf8'));
+  const errors = validateAgainstSchema(manifest, schema, 'manifest');
+  if (errors.length > 0) {
+    const detail = errors.slice(0, 10).map(e => '  - ' + e).join('\n');
+    const more = errors.length > 10 ? `\n  ...and ${errors.length - 10} more` : '';
+    throw new Error(`[verify] manifest.json failed schema validation:\n${detail}${more}`);
+  }
+  if (!Array.isArray(manifest.skills)) {
+    throw new Error('[verify] manifest.json: skills must be an array');
+  }
+  for (const skill of manifest.skills) {
+    validateSkillPath(skill.path);
+  }
+  return manifest;
+}
+
+// --- JSON schema validator (subset) ---
+//
+// Mirrors lib/validate-cve-catalog.js's inline validator. Supports the
+// schema features manifest.schema.json actually uses: type, required,
+// properties, additionalProperties, items, pattern, minLength,
+// minItems, $defs / $ref (root-relative only — "#/$defs/foo"). Zero
+// external deps.
+
+function typeOf(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  return typeof value;
+}
+
+function typeMatches(value, expected) {
+  if (Array.isArray(expected)) return expected.some(t => typeMatches(value, t));
+  const actual = typeOf(value);
+  if (expected === 'integer') return actual === 'number' && Number.isInteger(value);
+  return actual === expected;
+}
+
+function resolveRef(ref, root) {
+  if (!ref.startsWith('#/')) {
+    throw new Error(`[verify] unsupported $ref form (must be root-relative): ${ref}`);
+  }
+  const parts = ref.slice(2).split('/');
+  let cur = root;
+  for (const p of parts) {
+    if (cur === undefined || cur === null) {
+      throw new Error(`[verify] cannot resolve $ref ${ref}`);
+    }
+    cur = cur[p];
+  }
+  if (cur === undefined) {
+    throw new Error(`[verify] $ref ${ref} did not resolve`);
+  }
+  return cur;
+}
+
+function validateAgainstSchema(value, schema, here, root) {
+  const rootSchema = root || schema;
+  const errors = [];
+  let effectiveSchema = schema;
+  if (schema && schema.$ref) {
+    effectiveSchema = resolveRef(schema.$ref, rootSchema);
+  }
+
+  if (effectiveSchema.type !== undefined) {
+    if (!typeMatches(value, effectiveSchema.type)) {
+      errors.push(`${here}: expected type ${JSON.stringify(effectiveSchema.type)}, got ${typeOf(value)}`);
+      return errors;
+    }
+  }
+
+  const t = typeOf(value);
+
+  if (t === 'string') {
+    if (effectiveSchema.minLength !== undefined && value.length < effectiveSchema.minLength) {
+      errors.push(`${here}: string shorter than minLength ${effectiveSchema.minLength}`);
+    }
+    if (effectiveSchema.pattern !== undefined) {
+      const re = new RegExp(effectiveSchema.pattern);
+      if (!re.test(value)) {
+        errors.push(`${here}: string ${JSON.stringify(value)} does not match pattern /${effectiveSchema.pattern}/`);
+      }
+    }
+    if (effectiveSchema.format === 'uri') {
+      try { new URL(value); } catch { errors.push(`${here}: not a valid URI`); }
+    }
+  }
+
+  if (t === 'array') {
+    if (effectiveSchema.minItems !== undefined && value.length < effectiveSchema.minItems) {
+      errors.push(`${here}: array shorter than minItems ${effectiveSchema.minItems}`);
+    }
+    if (effectiveSchema.items !== undefined) {
+      value.forEach((item, idx) => {
+        errors.push(...validateAgainstSchema(item, effectiveSchema.items, `${here}[${idx}]`, rootSchema));
+      });
+    }
+  }
+
+  if (t === 'object') {
+    if (effectiveSchema.required) {
+      for (const req of effectiveSchema.required) {
+        if (!(req in value)) errors.push(`${here}: missing required field "${req}"`);
+      }
+    }
+    const props = effectiveSchema.properties || {};
+    const allowAdditional = effectiveSchema.additionalProperties !== false;
+    for (const [k, v] of Object.entries(value)) {
+      if (k in props) {
+        errors.push(...validateAgainstSchema(v, props[k], `${here}.${k}`, rootSchema));
+      } else if (!allowAdditional) {
+        errors.push(`${here}: unexpected property "${k}"`);
+      }
+    }
+  }
+
+  return errors;
+}
+
 /**
  * Public key fingerprint(s) of the DER-encoded SPKI public key,
  * base64-encoded. Emits both:
@@ -181,6 +394,38 @@ function loadManifest() {
  * @param {string|null} pemKey  PEM-encoded public key (or null)
  * @returns {{sha256: string, sha3_512: string}|{error: string}}
  */
+/**
+ * Audit G F4 — compare the live public-key fingerprint against the optional
+ * pinned fingerprint in keys/EXPECTED_FINGERPRINT. Returns one of:
+ *   { status: 'no-pin' }      — keys/EXPECTED_FINGERPRINT not present.
+ *                               Callers should warn and continue.
+ *   { status: 'match' }       — live fingerprint matches the pin.
+ *   { status: 'mismatch',     — divergence; caller should fail unless
+ *     expected, actual,         KEYS_ROTATED=1 is set in the environment.
+ *     rotationOverride }
+ *
+ * @param {{sha256:string}|null} liveFp  publicKeyFingerprint() output
+ * @param {string} [pinPath]             optional override (testability)
+ */
+function checkExpectedFingerprint(liveFp, pinPath) {
+  const p = pinPath || EXPECTED_FINGERPRINT_PATH;
+  if (!fs.existsSync(p)) return { status: 'no-pin' };
+  if (!liveFp || typeof liveFp.sha256 !== 'string') {
+    return { status: 'mismatch', expected: 'unknown', actual: '(invalid)', rotationOverride: false };
+  }
+  const expected = fs.readFileSync(p, 'utf8').trim();
+  // Tolerate trailing comment / whitespace on the same line; the file's
+  // first non-empty line is the canonical fingerprint.
+  const firstLine = expected.split(/\r?\n/).map((l) => l.trim()).find((l) => l.length > 0) || '';
+  if (firstLine === liveFp.sha256) return { status: 'match' };
+  return {
+    status: 'mismatch',
+    expected: firstLine,
+    actual: liveFp.sha256,
+    rotationOverride: process.env.KEYS_ROTATED === '1',
+  };
+}
+
 function publicKeyFingerprint(pemKey) {
   if (!pemKey) return { sha256: '(no key)', sha3_512: '(no key)' };
   try {
@@ -238,24 +483,76 @@ if (require.main === module) {
   if (result.no_key) process.exit(1);
 
   const total = Object.values(result).filter(Array.isArray).flat().length;
-  // Compute + print the public key fingerprints so operators can pin
-  // the key out-of-band. Without this, a swapped keys/public.pem
-  // would still produce a "verified" message — undetectable from the
-  // exit code alone. Dual fingerprint (SHA-256 + SHA3-512) gives
-  // ssh-keygen compatibility AND a SHA-3 family diversity hedge.
+  // S5 ordering: verdict line first, fingerprint banner after.
+  // An operator scanning `gh run watch` output should never see a
+  // fingerprint banner without first seeing whether the verdict
+  // was pass or fail. The previous order printed the success
+  // summary then the fingerprint; if verification was actually
+  // failing (TAMPERED / UNSIGNED / MISSING) the success line was
+  // never reached but the fingerprint had already been printed,
+  // which can read as "success" at a glance.
+  if (result.invalid.length > 0) {
+    console.error(`\n[verify] ${result.invalid.length}/${total} FAILED — TAMPERED: ${result.invalid.join(', ')}`);
+  } else if (result.missing_sig.length > 0) {
+    console.warn(`\n[verify] ${result.missing_sig.length}/${total} UNSIGNED: ${result.missing_sig.join(', ')}`);
+  } else if (result.missing_file.length > 0) {
+    console.error(`\n[verify] ${result.missing_file.length}/${total} MISSING: ${result.missing_file.join(', ')}`);
+  } else {
+    console.log(`\n[verify] All skills verified. ${result.valid.length}/${total} skills passed Ed25519 verification.`);
+  }
+
+  // Fingerprint banner comes AFTER the verdict.
   const pubKey = loadPublicKey();
   const fp = publicKeyFingerprint(pubKey);
-  console.log(`\n[verify] ${result.valid.length}/${total} skills passed Ed25519 verification.`);
   console.log(`[verify] Public key: keys/public.pem`);
   console.log(`[verify] ${fp.sha256}`);
   console.log(`[verify] ${fp.sha3_512}`);
 
-  if (result.invalid.length > 0) { console.error('[verify] TAMPERED:', result.invalid.join(', ')); process.exit(1); }
-  if (result.missing_sig.length > 0) { console.warn('[verify] UNSIGNED:', result.missing_sig.join(', ')); process.exit(1); }
-  if (result.missing_file.length > 0) { console.error('[verify] MISSING:', result.missing_file.join(', ')); process.exit(1); }
+  // Audit G F4 — pin check. When keys/EXPECTED_FINGERPRINT exists, the
+  // live fingerprint MUST match it (or KEYS_ROTATED=1 must be set to
+  // intentionally override). When the file is absent, emit a single-line
+  // warning but continue — fresh clones / bootstrap workflows should not
+  // fail the gate before the operator has committed a fingerprint.
+  const pinResult = checkExpectedFingerprint(fp);
+  if (pinResult.status === 'no-pin') {
+    console.warn(
+      `[verify] WARN: keys/EXPECTED_FINGERPRINT not present — key-pin check skipped. ` +
+      `Create it with the current ${fp.sha256} line to enable pinning.`
+    );
+  } else if (pinResult.status === 'mismatch') {
+    if (pinResult.rotationOverride) {
+      console.warn(
+        `[verify] WARN: live key fingerprint ${pinResult.actual} differs from pin ` +
+        `${pinResult.expected}. KEYS_ROTATED=1 set — accepting rotation. ` +
+        `Update keys/EXPECTED_FINGERPRINT to lock the new pin.`
+      );
+    } else {
+      console.error(
+        `[verify] FAIL: live key fingerprint ${pinResult.actual} does not match ` +
+        `keys/EXPECTED_FINGERPRINT ${pinResult.expected}. ` +
+        `If this is an intentional rotation, re-run with KEYS_ROTATED=1 and ` +
+        `then commit the new fingerprint to keys/EXPECTED_FINGERPRINT.`
+      );
+      process.exit(1);
+    }
+  }
+
+  if (result.invalid.length > 0) process.exit(1);
+  if (result.missing_sig.length > 0) process.exit(1);
+  if (result.missing_file.length > 0) process.exit(1);
 
-  console.log('[verify] All skills verified.');
   process.exit(0);
 }
 
-module.exports = { verifyAll, verifyOne, signAll };
+module.exports = {
+  verifyAll,
+  verifyOne,
+  signAll,
+  normalize,
+  validateSkillPath,
+  loadManifestValidated,
+  validateAgainstSchema,
+  publicKeyFingerprint,
+  checkExpectedFingerprint,
+  EXPECTED_FINGERPRINT_PATH,
+};

package/manifest-snapshot.json

@@ -1,6 +1,6 @@
 {
   "_comment": "Auto-generated by scripts/refresh-manifest-snapshot.js — do not hand-edit. Public skill surface used by check-manifest-snapshot.js to detect breaking removals.",
-  "_generated_at": "2026-05-13T21:19:34.827Z",
+  "_generated_at": "2026-05-14T15:55:39.383Z",
   "atlas_version": "5.1.0",
   "skill_count": 38,
   "skills": [

package/manifest-snapshot.sha256

@@ -0,0 +1 @@
+ca9d31e533c9d494e1ac5875e0a45176101438c3d75d44387187e367ccae21ad  manifest-snapshot.json