@blamejs/exceptd-skills 0.19.32 → 0.19.34

package/lib/validate-vendor.js

@@ -1,20 +1,8 @@
 "use strict";
 /**
- * lib/validate-vendor.js
- *
- * Predeploy gate. Confirms every file recorded in `vendor/blamejs/_PROVENANCE.json`
- * has the same SHA-256 on disk as the manifest claims. Silent hand-edits
- * to a vendored copy fail the build.
- *
- * Also confirms vendor/blamejs/LICENSE matches the recorded license hash so
- * a license-text change is detected as a separate event from a code change.
- *
- * Exit codes:
- *   0 — vendor tree in sync with provenance
- *   1 — at least one file drift / missing
- *
- * Re-vendor with: copy upstream, apply strip rules, refresh hashes in
- * _PROVENANCE.json, re-run this gate.
+ * Predeploy gate: every file recorded in `vendor/blamejs/_PROVENANCE.json` must
+ * carry the same SHA-256 on disk, and vendor/blamejs/LICENSE must match its
+ * recorded hash. Exits 0 when the tree is in sync, 1 on any drift.
  */
 
 const fs = require("fs");
@@ -37,11 +25,8 @@ function main() {
   const prov = JSON.parse(fs.readFileSync(PROV, "utf8"));
   const issues = [];
 
-  // License file. A recorded license_file with NO license_sha256 is an
-  // unverifiable integrity claim, not a skip: stripping the hash from the
-  // manifest must not silently disable the LICENSE-text check (the
-  // absent-field-fails-open class). Only a manifest that records no
-  // license_file at all is exempt.
+  // A recorded license_file with NO license_sha256 is an unverifiable integrity
+  // claim, not a skip: stripping the hash must not disable this check.
   if (prov.license_file) {
     if (!prov.license_sha256) {
       issues.push(`license_file recorded (${prov.license_file}) without license_sha256 — integrity unverifiable`);
@@ -58,17 +43,14 @@ function main() {
     }
   }
 
-  // Each vendored file.
   for (const [name, info] of Object.entries(prov.files || {})) {
     const p = path.join(ROOT, info.vendored_path);
     if (!fs.existsSync(p)) {
       issues.push(`missing vendored file: ${info.vendored_path}`);
       continue;
     }
-    // A files[] entry recorded without vendored_sha256 is an unverifiable
-    // integrity claim — surface it as a clean issue rather than crashing on
-    // `undefined.slice()` while formatting a drift message (the absent-field
-    // class, symmetric with the license path above).
+    // An entry recorded without vendored_sha256 is an unverifiable integrity
+    // claim — report it rather than crash on `undefined.slice()`.
     if (!info.vendored_sha256) {
       issues.push(`${info.vendored_path} recorded without vendored_sha256 — integrity unverifiable`);
       continue;
@@ -77,20 +59,11 @@ function main() {
     if (live !== info.vendored_sha256) {
       issues.push(`drift in ${info.vendored_path}: recorded ${info.vendored_sha256.slice(0, 12)}…, live ${live.slice(0, 12)}…`);
     }
-    // Offline upstream-pin cross-check. The vendored_sha256 compare above is
-    // self-attesting — it only proves the file matches its OWN recorded hash,
-    // never that the bytes match blamejs@<pin> upstream. The full upstream
-    // verification (scripts/validate-vendor-online.js) needs the network and
-    // is not a predeploy gate, so a hand-edited upstream_sha256_at_pin
-    // advertising a pin that never existed otherwise passes every
-    // automatically-run gate.
-    //
-    // For a file recorded with NO strip rules, the vendored bytes are
-    // byte-identical to upstream by definition, so upstream_sha256_at_pin MUST
-    // equal vendored_sha256. A divergence is a forged or internally
-    // inconsistent pin claim, and it is provable OFFLINE — no fetch required.
-    // This closes the upstream side of the integrity check for every
-    // unmodified vendored file (the common case) inside the existing gate.
+    // The vendored_sha256 compare above is self-attesting: it proves the file
+    // matches its OWN recorded hash, never that the bytes match blamejs@<pin>.
+    // With no strip rules the vendored bytes ARE the upstream bytes, so a
+    // divergence from upstream_sha256_at_pin is a forged pin claim, provable
+    // offline. The fetching check is scripts/validate-vendor-online.js.
     const stripped = Array.isArray(info.stripped) ? info.stripped : [];
     if (stripped.length === 0) {
       if (!info.upstream_sha256_at_pin) {
@@ -110,16 +83,10 @@ function main() {
     }
   }
 
-  // On-disk inventory cross-check (BJS-04): the loop above is one-directional
-  // (manifest → disk). A loadable JS module PRESENT in vendor/blamejs/ but
-  // ABSENT from _PROVENANCE.json would ship in the tarball and be require()'d
-  // by lib code while NOTHING verifies its integrity — an unregistered or
-  // smuggled-in vendored module. Node executes `.js`, `.cjs`, and `.mjs` as
-  // code, so a `.cjs`/`.mjs` smuggled module carries the same arbitrary-code
-  // risk as a `.js` one — checking only `.js` let a renamed extension slip the
-  // gate. `.json`/`.node` are deliberately NOT swept here: `_PROVENANCE.json`
-  // itself lives in this directory and is the manifest, not a registered
-  // vendored module, so sweeping `.json` would false-positive on the manifest.
+  // The loop above is one-directional (manifest → disk): a module on disk but
+  // absent from _PROVENANCE.json ships with nothing verifying its integrity.
+  // Node executes `.js`, `.cjs` and `.mjs` alike, so a renamed extension must not
+  // slip the sweep; `.json` stays out because `_PROVENANCE.json` IS the manifest.
   const LOADABLE_MODULE = /\.(c|m)?js$/;
   const registered = new Set(
     Object.values(prov.files || {}).map((info) => path.basename(info.vendored_path))

package/lib/verify.js

@@ -1,62 +1,7 @@
 'use strict';
 
 /**
- * Skill integrity verifier — Ed25519 cryptographic signatures.
- *
- * SHA-256 hashes alone protect against accidental corruption; anyone with repo
- * write access can update the hash after tampering. Ed25519 signatures prove a
- * 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.
- *
- * Manifest signature contract (must mirror lib/sign.js):
- *   The manifest carries a top-level `manifest_signature` field. Before
- *   iterating skills, loadManifestValidated() extracts the signature,
- *   recomputes the canonical bytes, and verifies against keys/public.pem.
- *   On failure, all skill verification is blocked with a structured
- *   error. When the field is absent (older v0.11.x / pre-v0.12.17
- *   tarballs in the wild), a warning is emitted but verification
- *   continues — this preserves backward compatibility for installs that
- *   predate manifest signing.
- *
- *   Canonical bytes are computed identically to lib/sign.js
- *   canonicalManifestBytes():
- *     1. Clone, delete manifest_signature.
- *     2. JSON.stringify with top-level keys sorted lexicographically.
- *     3. Apply normalize() — strip BOM, CRLF → LF.
- *   ANY change to the canonical form requires the matching change in
- *   lib/sign.js. Round-trip stability is a hard contract.
- *
- * Signing ceremony: see lib/sign.js
- * Public key: keys/public.pem (tracked in repo)
- * Private key: .keys/private.pem (gitignored, kept off-repo)
- *
- * Usage:
- *   node lib/verify.js           — verify all skills
- *   node lib/verify.js <name>    — verify one skill
- *   node lib/verify.js update    — re-sign all skills (requires private key)
- *   node lib/verify.js check-key — verify the public key is present and valid
+ * Skill integrity verifier — Ed25519 signatures over normalized skill content.
  */
 
 const fs = require('fs');
@@ -69,21 +14,10 @@ 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');
-// 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.
+// Key pin: one line "SHA256:<base64>", compared against live keys/public.pem.
 const EXPECTED_FINGERPRINT_PATH = path.join(ROOT, 'keys', 'EXPECTED_FINGERPRINT');
 
-// --- public API ---
-
-/**
- * Verify all skills in manifest.json against the Ed25519 public key.
- * @returns {{ valid: string[], invalid: string[], missing_sig: string[], missing_file: string[], no_key: boolean }}
- */
+// Returns per-status name lists; an absent public key returns no_key:true.
 function verifyAll() {
   const publicKey = loadPublicKey();
   if (!publicKey) {
@@ -105,11 +39,7 @@ function verifyAll() {
   return result;
 }
 
-/**
- * Verify one skill by name.
- * @param {string} skillName
- * @returns {{ status: string, reason?: string }}
- */
+// Throws where verifyAll() reports a status: no public key, or name not in manifest.
 function verifyOne(skillName) {
   const publicKey = loadPublicKey();
   if (!publicKey) throw new Error('No public key at keys/public.pem');
@@ -121,19 +51,13 @@ function verifyOne(skillName) {
   return verifySkill(skill, publicKey);
 }
 
-/**
- * Re-sign all skills using the private key and write signatures to manifest.json.
- * Requires .keys/private.pem — never checked in.
- * @returns {{ signed: string[], errors: string[] }}
- */
+// Rewrites manifest.json in place. Requires .keys/private.pem.
 function signAll() {
   const privateKey = loadPrivateKey();
   if (!privateKey) throw new Error('No private key at .keys/private.pem — run `exceptd doctor --fix` (or `node $(exceptd path)/lib/sign.js generate-keypair` from a contributor checkout)');
 
-  // P1-4: load the manifest without the signature gate. We're about to
-  // mutate the manifest (re-sign skills + re-sign the manifest itself),
-  // so a stale manifest_signature mismatch here is expected — not a
-  // tampering signal. Schema + path validation still apply.
+  // Loaded without the signature gate: this run rewrites the signatures, so a
+  // stale manifest_signature is expected here. Schema + path checks still run.
   const manifest = loadManifest();
   const schema = JSON.parse(fs.readFileSync(MANIFEST_SCHEMA_PATH, 'utf8'));
   const errors0 = validateAgainstSchema(manifest, schema, 'manifest');
@@ -158,20 +82,13 @@ function signAll() {
     result.signed.push(skill.name);
   }
 
-  // P1-4: re-sign the manifest after the per-skill signatures changed.
   delete manifest.manifest_signature;
   const canonical = canonicalManifestBytes(manifest);
   const manifestSig = crypto.sign(null, canonical, {
     key: privateKey, dsaEncoding: 'ieee-p1363',
   });
-  // `signed_at` is intentionally OMITTED. A `signed_at` timestamp
-  // alongside the Ed25519 signature would be unsigned metadata (stripped
-  // from the canonical bytes before signing), so an attacker could replay
-  // a known-valid signature against the same canonical content while
-  // rewriting `signed_at` to any value — lending false freshness
-  // authority to a stale signature. Operators who need a freshness
-  // signal should consult the git-log mtime of manifest.json (or the
-  // npm publish timestamp), which are external to the signed bytes.
+  // No `signed_at` here: unsigned metadata, so a replayed known-valid signature
+  // could carry any timestamp. Freshness comes from git log / npm publish time.
   manifest.manifest_signature = {
     algorithm: 'Ed25519',
     signature_base64: manifestSig.toString('base64'),
@@ -182,46 +99,22 @@ function signAll() {
   return result;
 }
 
-// --- 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}
- */
+// Strips a leading UTF-8 BOM, then CRLF → LF. lib/sign.js applies the identical
+// transform; diverging breaks the sign→verify round trip for every skill.
 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}
- */
+// Throws unless skillPath is a string under skills/ with no ".." and no
+// backslashes. Deliberately duplicated in lib/sign.js — change both together.
 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/".
+  // Before the prefix check: a Windows-style "skills\foo\skill.md" earns the
+  // "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)}`);
   }
@@ -293,22 +186,10 @@ function loadManifest() {
   return JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf8'));
 }
 
-/**
- * canonical byte form of the manifest.
- *
- * Mirrors lib/sign.js canonicalManifestBytes(). Any divergence here
- * breaks the verify-after-sign round trip; do not modify in isolation.
- *
- * v0.12.17 (codex P1 PR #12): use deep canonicalize() instead of the
- * top-level sortedKeys replacer-array. The replacer-array form acts as
- * a property allowlist applied to EVERY object level — nested fields
- * like skills[].path and skills[].signature got silently dropped from
- * the canonical bytes, letting an attacker swap them without breaking
- * the signature.
- *
- * @param {object} manifest
- * @returns {Buffer} canonical UTF-8 bytes
- */
+// Deep key sort, never a top-level JSON.stringify replacer array: a replacer
+// acts as a property allowlist at EVERY object level, dropping skills[].path and
+// skills[].signature out of the signed bytes. Mirrors lib/sign.js
+// canonicalManifestBytes(); diverging breaks the verify-after-sign round trip.
 function canonicalize(value) {
   if (Array.isArray(value)) return value.map(canonicalize);
   if (value && typeof value === 'object') {
@@ -329,31 +210,15 @@ function canonicalManifestBytes(manifest) {
 }
 
 /**
- * Verify the top-level manifest_signature against keys/public.pem.
- *
- * Returns one of:
- *   { status: 'missing' }  — field absent (legacy tarball; warn-but-proceed)
- *   { status: 'valid' }    — signature verifies
- *   { status: 'invalid',   — signature malformed, wrong key, or tampered
- *     reason: string }
- *   { status: 'no-key',    — keys/public.pem absent
- *     reason: string }
- *
- * @param {object} manifest
+ * Verify the top-level manifest_signature against keys/public.pem. Status is
+ * one of 'valid'; 'missing' (field absent — a caller may warn and proceed);
+ * 'invalid' or 'no-key', both carrying a `reason`.
  */
 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).
+  // The key pin is consulted FIRST, before the signature-present branch: an
+  // attacker who swaps keys/public.pem AND strips manifest_signature would
+  // otherwise take the early `missing` return. A missing pin file fails closed —
+  // the pin is committed and ships in the tarball. KEYS_ROTATED=1 overrides.
   const publicKey = loadPublicKey();
   if (publicKey) {
     const liveFp = publicKeyFingerprint(publicKey);
@@ -380,12 +245,8 @@ function verifyManifestSignature(manifest) {
   if (typeof sig.signature_base64 !== 'string') {
     return { status: 'invalid', reason: 'manifest_signature.signature_base64 missing or not a string' };
   }
-  // Require the algorithm field to be present and exactly 'Ed25519'.
-  // Accepting a missing algorithm field
-  // (`if (sig.algorithm && sig.algorithm !== 'Ed25519')`) would let a
-  // downgrade attacker drop the field to bait a weaker default.
-  // lib/sign.js always writes the field, so no legitimate consumer
-  // breaks.
+  // Exact match, never `sig.algorithm && sig.algorithm !== 'Ed25519'`: tolerating
+  // an absent field lets a downgrade attacker drop it. lib/sign.js always writes it.
   if (sig.algorithm !== 'Ed25519') {
     return {
       status: 'invalid',
@@ -395,8 +256,6 @@ function verifyManifestSignature(manifest) {
   if (!publicKey) {
     return { status: 'no-key', reason: 'public key missing at keys/public.pem' };
   }
-  // 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');
@@ -417,22 +276,9 @@ function verifyManifestSignature(manifest) {
 }
 
 /**
- * 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.
- *
- * also verifies the top-level manifest_signature. On
- * invalid signature, throws a structured error blocking all skill
- * verification (a coordinated attacker who rewrote manifest.json +
- * manifest-snapshot.json + manifest-snapshot.sha256 still cannot forge
- * the Ed25519 signature without the private key). When the signature
- * field is absent, emits a stderr warning but proceeds — preserves
- * backward compatibility for v0.12.16-and-earlier tarballs.
- *
- * @returns {object}
+ * Returns a manifest that passed schema validation, the path-traversal guard and
+ * the manifest_signature check, or throws — a verified manifest or nothing. An
+ * absent signature field is the sole tolerated case: it warns and proceeds.
  */
 function loadManifestValidated() {
   const manifest = loadManifest();
@@ -449,41 +295,29 @@ function loadManifestValidated() {
   for (const skill of manifest.skills) {
     validateSkillPath(skill.path);
   }
-  // manifest signature gate. Runs after schema + path
-  // validation so a malformed manifest reports the structural failure
-  // before the cryptographic one.
+  // After schema + path validation: structural failures report before crypto ones.
   const sigResult = verifyManifestSignature(manifest);
   if (sigResult.status === 'invalid') {
     throw new Error(`[verify] manifest_signature verification FAILED — ${sigResult.reason}. The manifest has been modified (or signed with a different key) since last sign-all. Refusing to verify any skill against this manifest.`);
   }
   if (sigResult.status === 'missing') {
-    // Dedupe the legacy-tarball warning. Many CLI verbs call
-    // loadManifestValidated() more than once per invocation, so a plain
-    // console.warn would spam stderr per call. Node's emitWarning() with
-    // a stable `code` collapses repeated emissions automatically.
+    // emitWarning with a stable `code` collapses repeats; CLI verbs call
+    // loadManifestValidated() several times per invocation.
     process.emitWarning(
       'manifest.json has no top-level manifest_signature field. This tarball predates v0.12.17 manifest signing; skills will still be verified but a coordinated rewrite of manifest.json could go undetected. Re-run `exceptd doctor --fix` (or `node $(exceptd path)/lib/sign.js sign-all` from a contributor checkout) to add the signature.',
       { code: 'EXCEPTD_MANIFEST_UNSIGNED' }
     );
   } else if (sigResult.status === 'no-key') {
-    // The documented contract is "return a VERIFIED manifest or throw" — never
-    // an unverified one. verifyAll()/verifyOne() short-circuit on a missing key
-    // BEFORE reaching here, so this fires only for a direct
-    // loadManifestValidated() caller, which must not silently receive an
-    // unauthenticated manifest: an attacker who deletes keys/public.pem could
-    // otherwise smuggle a rewritten manifest past a library consumer.
+    // verifyAll()/verifyOne() short-circuit on a missing key before reaching
+    // here, so this fires only for a direct library caller.
     throw new Error(`[verify] manifest_signature verification FAILED — ${sigResult.reason}. Cannot verify the manifest without keys/public.pem; refusing to return an unauthenticated manifest.`);
   }
   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.
+// JSON-schema subset, mirroring lib/validate-cve-catalog.js's inline validator:
+// type, required, properties, additionalProperties, items, pattern, minLength,
+// minItems, and root-relative $ref ("#/$defs/foo") only.
 
 function typeOf(value) {
   if (value === null) return 'null';
@@ -580,54 +414,10 @@ function validateAgainstSchema(value, schema, here, root) {
 }
 
 /**
- * Public key fingerprint(s) of the DER-encoded SPKI public key,
- * base64-encoded. Emits both:
- *
- *   - SHA-256: the universal convention. Matches `ssh-keygen -lf`
- *     output for the same key, matches GPG / npm provenance / CT log
- *     fingerprints. Operators cross-referencing the key against an
- *     external pin will use this line.
- *
- *   - SHA3-512: SHA-3 family (Keccak / sponge construction), different
- *     mathematical foundation than SHA-2. Hedges against future SHA-2
- *     weaknesses. 512-bit output (~88 b64 chars) so collision +
- *     second-preimage resistance both exceed the 256-bit Ed25519 key
- *     itself. SHA-3 is also the hash family ML-KEM / ML-DSA use
- *     internally, so this fingerprint travels well with the project's
- *     PQ posture.
- *
- * @param {string|null} pemKey  PEM-encoded public key (or null)
- * @returns {{sha256: string, sha3_512: string}|{error: string}}
- */
-/**
- * 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)
- */
-/**
- * Shared loader for keys/EXPECTED_FINGERPRINT. Reads the pin file, strips
- * a leading UTF-8 BOM (Notepad with files.encoding=utf8bom would otherwise
- * prepend U+FEFF and silently break every verify path on the host),
- * tolerates CRLF line endings, ignores comment lines (`#`) and blanks,
- * and returns the first non-comment / non-empty line. Returns null if
- * the file is unreadable / empty.
- *
- * Shared across five sites so every loader normalises identically:
- *   - lib/verify.js              (manifest signature gate)
- *   - lib/refresh-network.js     (refresh-network pre-swap gate)
- *   - scripts/verify-shipped-tarball.js (predeploy gate)
- *   - bin/exceptd.js             (attestation pin)
- *   - lib/prefetch.js            (cache-consume index signature pin)
- * tests/normalize-contract.test.js asserts byte-identical output across the
- * sites under a BOM + CRLF fuzz corpus.
+ * First non-comment, non-blank line of keys/EXPECTED_FINGERPRINT, or null when
+ * the file is unreadable or empty. Strips a BOM and tolerates CRLF. Every site
+ * that reads the pin normalises through here, so a pin that works in one works
+ * in all; tests/normalize-contract.test.js asserts that.
  */
 function loadExpectedFingerprintFirstLine(pinPath) {
   let buf;
@@ -636,17 +426,11 @@ function loadExpectedFingerprintFirstLine(pinPath) {
   if (buf.length >= 2) {
     const b0 = buf[0];
     const b1 = buf[1];
-    // UTF-16LE (FF FE) and UTF-16BE (FE FF) pin files would silently decode
-    // as UTF-8 mojibake — the first line never matches a live fingerprint
-    // and the operator sees no signal. Refuse them; re-save as UTF-8.
+    // A UTF-16 pin file decodes as UTF-8 mojibake, so the first line silently
+    // never matches a live fingerprint. Refuse it; the fix is re-saving as UTF-8.
     if ((b0 === 0xFF && b1 === 0xFE) || (b0 === 0xFE && b1 === 0xFF)) return null;
-    // UTF-16BE-without-BOM defense: a pin file saved as UTF-16BE on a host
-    // whose editor stripped the BOM (or never wrote one) decodes as
-    // 0x00 <printable ASCII> 0x00 <printable ASCII>... The leading NUL byte
-    // would survive into the utf8 string and the first-line compare would
-    // never match a SHA256:... fingerprint. Detect "00 XX" where XX is
-    // printable ASCII (0x20-0x7E) and refuse — same remediation: re-save
-    // the file as UTF-8.
+    // UTF-16BE whose BOM was stripped: "00 <printable ASCII>" repeating. The
+    // leading NUL survives into the string and defeats the compare the same way.
     if (b0 === 0x00 && b1 >= 0x20 && b1 <= 0x7E) return null;
   }
   let raw = buf.toString('utf8');
@@ -658,15 +442,17 @@ function loadExpectedFingerprintFirstLine(pinPath) {
   return lines[0] || null;
 }
 
+// Status is 'no-pin' (no pin file — the caller decides whether that is fatal),
+// 'match', or 'mismatch' with expected/actual and rotationOverride set from
+// KEYS_ROTATED=1. pinPath overrides the default location for tests.
 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 };
   }
-  // Route through the shared loader so a BOM-prefixed pin file
-  // (Notepad with files.encoding=utf8bom) is tolerated identically across
-  // every verify site. Pre-fix the verbatim split-trim-find produced a
+  // The shared loader tolerates a BOM-prefixed pin file identically across every
+  // verify site. A verbatim split-trim-find here would instead yield a
   // allow:bidi-codepoint-literal — illustrative BOM-prefixed first-line in the pin-loader doc comment
   // first-line of "SHA256:..." (with leading BOM) that would never equal
   // a live fingerprint.
@@ -695,8 +481,6 @@ function publicKeyFingerprint(pemKey) {
   }
 }
 
-// --- CLI ---
-
 if (require.main === module) {
   const arg = process.argv[2];
 
@@ -737,14 +521,8 @@ if (require.main === module) {
   if (result.no_key) process.exit(1);
 
   const total = Object.values(result).filter(Array.isArray).flat().length;
-  // 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.
+  // Verdict first, fingerprint banner after: a banner printed above a TAMPERED /
+  // UNSIGNED / MISSING verdict reads 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) {
@@ -755,18 +533,13 @@ if (require.main === module) {
     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(`[verify] Public key: keys/public.pem`);
   console.log(`[verify] ${fp.sha256}`);
   console.log(`[verify] ${fp.sha3_512}`);
 
-  // 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.
+  // On this path an absent pin warns and continues: a fresh clone has no pin yet.
   const pinResult = checkExpectedFingerprint(fp);
   if (pinResult.status === 'no-pin') {
     console.warn(
@@ -780,10 +553,7 @@ if (require.main === module) {
         `KEYS_ROTATED=1 accepted. Update keys/EXPECTED_FINGERPRINT to lock the new pin.`,
         { code: 'EXCEPTD_KEYS_ROTATED_OVERRIDE' }
       );
-      // Mirror to stderr unconditionally: NODE_NO_WARNINGS=1 silences
-      // process.emitWarning, but a key-rotation override is a
-      // security-relevant event that must surface in the operator's
-      // terminal even when warnings are muted.
+      // Mirrored to stderr: NODE_NO_WARNINGS=1 silences emitWarning.
       console.error(
         `[verify] KEYS_ROTATED=1 override accepted; live fingerprint ${pinResult.actual} ` +
         `differs from pin ${pinResult.expected}. Update keys/EXPECTED_FINGERPRINT to lock the new pin.`