@blamejs/exceptd-skills 0.12.20 → 0.12.22

package/lib/prefetch.js

@@ -18,7 +18,7 @@
  *   rfc/<doc-name>.json                               — IETF Datatracker doc record
  *   pins/<owner>__<repo>__releases.json               — MITRE GitHub releases listing
  *
- * audit M P2-K: the registered source names in SOURCES below are `rfc` and
+ * K: the registered source names in SOURCES below are `rfc` and
  * `pins`. Earlier comments + --help text said `ietf` and `github`; an
  * operator running `--source ietf` or `--source github` would hit "unknown
  * source" because no such key exists. The names below are the canonical
@@ -322,7 +322,7 @@ function isFresh(idx, source, id, maxAgeMs) {
 
 function authHeadersForSource(source) {
   if (source === "nvd" && process.env.NVD_API_KEY) return { apiKey: process.env.NVD_API_KEY };
-  // audit M P2-J: the registered source name for MITRE GitHub releases is
+  // J: the registered source name for MITRE GitHub releases is
   // `pins` (see SOURCES above). The prior check looked for `github`, so
   // GITHUB_TOKEN never reached the per-request Authorization header and
   // anonymous-rate-limited fetches were always used even when an operator
@@ -520,7 +520,7 @@ function readCached(cacheDir, source, id, opts = {}) {
   const idx = loadIndex(cacheDir);
   const meta = idx.entries[entryKey(source, id)];
   if (!meta) return null;
-  // audit M P2-L: when `fetched_at` is missing / non-string / unparseable,
+  // L: when `fetched_at` is missing / non-string / unparseable,
   // `new Date(undefined).getTime()` is NaN and `NaN > maxAgeMs` is false —
   // so the cached entry would have been returned as if fresh. Treat any
   // non-finite age as "no provenance, refuse" unless the caller explicitly

package/lib/refresh-external.js

@@ -94,6 +94,12 @@ function parseArgs(argv) {
     else if (a.startsWith("--from-fixture=")) out.fromFixture = a.slice("--from-fixture=".length);
     else if (a === "--report-out") out.reportOut = argv[++i];
     else if (a.startsWith("--report-out=")) out.reportOut = a.slice("--report-out=".length);
+    // FF P1-3: previously only EXCEPTD_AIR_GAP=1 reached the GHSA/OSV source
+    // modules — the CLI flag was undocumented in parseArgs, so a downstream
+    // operator following the documented `--air-gap` path silently allowed
+    // network calls. Now the flag is honoured; env var still works as a
+    // fallback so existing automation isn't broken.
+    else if (a === "--air-gap") out.airGap = true;
   }
   return out;
 }
@@ -549,7 +555,7 @@ const GHSA_SOURCE = {
     return ghsa.buildDiff(ctx);
   },
   async applyDiff(ctx, diffs) {
-    // v0.12.14 (audit B-F1): the prior shape mutated ctx.cveCatalog in
+    // v0.12.14: the prior shape mutated ctx.cveCatalog in
     // memory but NEVER persisted to disk. Bulk `--source ghsa --apply`
     // reported "applied: N updates" while the catalog file gained zero
     // entries. Worse under `--swarm`: KEV's withCatalogLock would re-read
@@ -602,7 +608,7 @@ const OSV_SOURCE = {
     return osv.buildDiff(ctx);
   },
   async applyDiff(ctx, diffs) {
-    // v0.12.14 (audit B-F1): same fix as GHSA — route the read-modify-write
+    // v0.12.14: same fix as GHSA — route the read-modify-write
     // through withCatalogLock so writes actually land on disk and so
     // concurrent --source osv --apply doesn't lose updates.
     const catalogPath = ctx.cvePath || ABS("data/cve-catalog.json");
@@ -846,6 +852,11 @@ function loadCtx(opts) {
     d3fendCatalog: JSON.parse(fs.readFileSync(ABS("data/d3fend-catalog.json"), "utf8")),
     fixtures: null,
     cacheDir: null,
+    // FF P1-3: thread --air-gap (or EXCEPTD_AIR_GAP=1) through to ctx.airGap
+    // so the GHSA + OSV source modules (lib/source-ghsa.js, lib/source-osv.js)
+    // can branch on ctx.airGap and refuse network egress. Pre-fix the GHSA/OSV
+    // sources only saw `ctx?.airGap` as undefined when the CLI flag was used.
+    airGap: !!(opts && opts.airGap) || process.env.EXCEPTD_AIR_GAP === "1",
   };
   if (opts.fromFixture) {
     ctx.fixtures = { dir: path.resolve(opts.fromFixture), kev: true, epss: true, nvd: true, rfc: true, pins: true, ghsa: true, osv: true };

package/lib/refresh-network.js

@@ -112,7 +112,7 @@ function getBuffer(url, timeoutMs) {
       }
       const chunks = [];
       let total = 0;
-      // v0.12.14 (audit F5): enforce streaming size cap so a hostile
+      // v0.12.14: enforce streaming size cap so a hostile
       // registry CDN can't stream gigabytes into RAM.
       res.on("data", (c) => {
         total += c.length;
@@ -191,7 +191,7 @@ function verifyDetached(publicKeyObj, payload, sigB64) {
   } catch { return false; }
 }
 
-// v0.12.14 (audit F1, F7): CRLF/BOM normalization mirrors lib/verify.js's
+// v0.12.14: CRLF/BOM normalization mirrors lib/verify.js's
 // normalize(). Duplicated here to keep refresh-network free of cross-module
 // runtime deps. ANY change here MUST be mirrored in lib/verify.js +
 // lib/sign.js + scripts/verify-shipped-tarball.js — the four normalize()
@@ -203,7 +203,7 @@ function normalizeSkillBytes(buf) {
   return Buffer.from(s.replace(/\r\n/g, "\n"), "utf8");
 }
 
-// Audit O P1-B + Q P1: in-line manifest-signature verifier. Kept here
+// B + Q P1: in-line manifest-signature verifier. Kept here
 // rather than imported from lib/verify.js so refresh-network.js retains
 // its no-cross-module-dep posture (mirrors the per-skill verify path).
 // ANY change to canonical-bytes computation here MUST stay in lockstep
@@ -260,7 +260,7 @@ function validateManifestSkillPath(skillPath) {
   return skillPath;
 }
 
-// v0.12.14 (audit F5): tarball download size cap. A hostile registry CDN
+// v0.12.14: tarball download size cap. A hostile registry CDN
 // could stream gigabytes; Node buffers chunks in RAM until OOM. Current
 // tarball is ~2 MB; 200 MB is generous defense-in-depth. Tunable via
 // EXCEPTD_TARBALL_SIZE_CAP_BYTES for future growth.
@@ -335,14 +335,14 @@ async function main() {
     process.exitCode = 2; return;
   }
 
-  // v0.12.14 (audit F5): defense-in-depth tarball size cap.
+  // v0.12.14: defense-in-depth tarball size cap.
   const sizeCap = tarballSizeCap();
   if (tgzBuf.length > sizeCap) {
     emit({ ok: false, error: `tarball exceeds size cap: ${tgzBuf.length} bytes > ${sizeCap} (EXCEPTD_TARBALL_SIZE_CAP_BYTES)` }, opts.json);
     process.exitCode = 4; return;
   }
 
-  // v0.12.14 (audit F6, F3): verify SHA-512 SRI first (collision-resistant
+  // v0.12.14: verify SHA-512 SRI first (collision-resistant
   // beyond SHA-1 reach), then SHA-1 shasum for compatibility, then dist.
   // signatures[] (npm registry's Ed25519 signing key). Each layer is
   // defense-in-depth — registry compromise that produces a SHA-1 collision
@@ -406,7 +406,7 @@ async function main() {
     process.exitCode = 5; return;
   }
 
-  // v0.12.16 (audit I P1-5): cross-check the local public key against
+  // v0.12.16: cross-check the local public key against
   // keys/EXPECTED_FINGERPRINT (the CI-pinned signing key). The prior
   // refresh-network code only compared LOCAL ↔ TARBALL fingerprints, so a
   // coordinated attacker who swapped both `keys/public.pem` on the operator's
@@ -420,8 +420,13 @@ async function main() {
   const expectedFingerprintPath = path.join(ROOT, "keys", "EXPECTED_FINGERPRINT");
   if (fs.existsSync(expectedFingerprintPath) && !process.env.KEYS_ROTATED) {
     try {
-      const expectedFp = fs.readFileSync(expectedFingerprintPath, "utf8")
-        .split(/\r?\n/).map(l => l.trim()).find(l => l.length > 0);
+      // KK P1-5: route through the shared lib/verify loader so a BOM-prefixed
+      // pin file (Notepad with files.encoding=utf8bom) is tolerated identically
+      // across every verify site. Pre-fix the inline split-trim-find returned
+      // the BOM as part of the first line, which would never match a live
+      // fingerprint and would block every legitimate refresh-network run.
+      const { loadExpectedFingerprintFirstLine } = require("./verify.js");
+      const expectedFp = loadExpectedFingerprintFirstLine(expectedFingerprintPath);
       // v0.12.16 (codex P1 PR #11): `expectedFp` is read verbatim from
       // keys/EXPECTED_FINGERPRINT (formatted as `SHA256:<base64>`), but
       // `fingerprintPublicKey()` returns the raw base64 without the
@@ -451,7 +456,7 @@ async function main() {
   try { tarballManifest = JSON.parse(tarballManifestEntry.body.toString("utf8")); }
   catch (e) { emit({ ok: false, error: `tarball manifest.json parse: ${e.message}` }, opts.json); process.exitCode = 4; return; }
 
-  // Audit O P1-B + Q P1: verify the top-level manifest_signature against
+  // B + Q P1: verify the top-level manifest_signature against
   // the LOCAL public key before honoring any entry in the tarball manifest.
   // The previous flow iterated `manifest.skills[].signature` per-skill but
   // never authenticated the manifest envelope itself — a coordinated
@@ -478,7 +483,7 @@ async function main() {
     process.exitCode = 5; return;
   }
 
-  // v0.12.14 (audit F1): the prior loop iterated `sk.id` + a fixed payload
+  // v0.12.14: the prior loop iterated `sk.id` + a fixed payload
   // path `skills/<id>/SKILL.md`. Manifest entries actually expose `name` +
   // `path` (a forward-slash relative path like `skills/<name>/skill.md`,
   // lowercase). Result: the loop matched zero entries; `failures.length === 0`
@@ -534,7 +539,7 @@ async function main() {
     process.exitCode = 5; return;
   }
 
-  // v0.12.14 (audit F2): the swap loop replaces `data/` + `manifest.json` +
+  // v0.12.14: the swap loop replaces `data/` + `manifest.json` +
   // `manifest-snapshot.json` in addition to `skills/`. None of those files
   // are covered by the per-skill Ed25519 signature (which signs only the
   // skill body bytes). The only integrity check between the registry and
@@ -575,7 +580,7 @@ async function main() {
     return;
   }
 
-  // v0.12.14 (audit F4): the prior swap loop renamed targets one-by-one,
+  // v0.12.14: the prior swap loop renamed targets one-by-one,
   // and a mid-loop failure left the install half-applied with no automatic
   // rollback. New shape: rename all old targets into a single backup dir
   // first (so the install is empty-of-old before any new content is moved
@@ -599,7 +604,7 @@ async function main() {
       written++;
     }
 
-    // v0.12.14 (audit F10): use PID + random suffix in the backup dir name
+    // v0.12.14: use PID + random suffix in the backup dir name
     // so concurrent refresh-network invocations don't collide on the
     // millisecond clock.
     const backupSuffix = `${process.pid}-${crypto.randomBytes(4).toString("hex")}`;
@@ -640,7 +645,7 @@ async function main() {
       message: `refreshed catalog from v${localVersion} → v${latestVersion} (${verifiedCount}/${skills.length} signatures verified). Backup at ${path.relative(ROOT, backupDir)} — safe to remove after verifying the new run.`,
     }, opts.json);
   } catch (e) {
-    // v0.12.14 (audit F4): walk completedSteps in reverse to undo partial work.
+    // v0.12.14: walk completedSteps in reverse to undo partial work.
     const rollbackErrors = [];
     for (const step of [...completedSteps].reverse()) {
       try {
@@ -682,12 +687,12 @@ if (require.main === module) {
 module.exports = {
   parseTar,
   fingerprintPublicKey,
-  // Audit P P1-A: exported for tests/normalize-contract.test.js so the
+  // A: exported for tests/normalize-contract.test.js so the
   // byte-stability contract can be asserted across all four normalize()
   // implementations (lib/sign.js, lib/verify.js, lib/refresh-network.js,
   // scripts/verify-shipped-tarball.js).
   normalizeSkillBytes,
-  // Audit O P1-B + Q P1: exported for in-process tests of the refresh
+  // B + Q P1: exported for in-process tests of the refresh
   // path's manifest envelope check.
   verifyTarballManifestSignature,
   canonicalManifestBytesForRefresh,

package/lib/scoring.js

@@ -5,7 +5,7 @@
  * Supplements CVSS with exploit availability, active exploitation, and operational constraints.
  *
  * ----------------------------------------------------------------------------
- * `rwep_factors` dual-semantics (audit J F2)
+ * `rwep_factors` dual-semantics
  * ----------------------------------------------------------------------------
  * Catalog entries (data/cve-catalog.json) store `rwep_factors` as an object
  * whose values are POST-WEIGHT CONTRIBUTIONS for boolean / ladder factors
@@ -62,7 +62,7 @@ const RWEP_WEIGHTS = {
   reboot_required:       5
 };
 
-// audit J F4: active_exploitation ladder. Aligned with playbook-runner's
+// active_exploitation ladder. Aligned with playbook-runner's
 // _activeExploitationLadder so the catalog scorer and the runtime evaluator
 // produce identical results for the same string value. 'unknown' contributes
 // a quarter of the confirmed weight (5 points) — operationally "we have not
@@ -76,7 +76,7 @@ const ACTIVE_EXPLOITATION_LADDER = {
 };
 
 // The canonical set of factor keys scoreCustom recognises. Used by
-// validateFactors to flag unknown keys (audit J F8).
+// validateFactors to flag unknown keys.
 const RECOGNISED_FACTOR_KEYS = new Set([
   'cisa_kev', 'poc_available', 'ai_assisted_weapon', 'ai_discovered',
   'active_exploitation', 'blast_radius', 'patch_available',
@@ -125,7 +125,7 @@ function validateFactors(factors) {
   } else if (!aeAllowed.includes(factors.active_exploitation)) {
     warnings.push(`active_exploitation: expected one of ${aeAllowed.join(', ')}, got ${JSON.stringify(factors.active_exploitation)}`);
   }
-  // audit J F6: NaN diagnostics. The prior message read "expected number,
+  // NaN diagnostics. The prior message read "expected number,
   // got number (null)" because `JSON.stringify(NaN) === 'null'` and `typeof
   // NaN === 'number'`. Number.isFinite catches NaN + Infinity + -Infinity
   // and emits a useful message.
@@ -140,7 +140,7 @@ function validateFactors(factors) {
   } else if (factors.blast_radius < 0 || factors.blast_radius > 30) {
     warnings.push(`blast_radius: ${factors.blast_radius} out of expected range [0, 30] (clamped to weight ceiling, but the value usually indicates a unit-of-measure mistake)`);
   }
-  // audit J F8: surface unknown factor keys so a typo'd answer file
+  // surface unknown factor keys so a typo'd answer file
   // (`patch_avilable`, `cisa-kev`, etc.) doesn't silently default to false
   // with no diagnostic.
   for (const k of Object.keys(factors)) {
@@ -173,7 +173,7 @@ function scoreCustom(factors, opts) {
     patch_available = false,
     live_patch_available = false,
     reboot_required = false,
-    // v0.12.15 (audit J F9): the CVE catalog field is `patch_required_reboot`
+    // v0.12.15: the CVE catalog field is `patch_required_reboot`
     // but scoreCustom historically expected `reboot_required`. validate()
     // already aliases at the call site; accept either spelling here so a
     // direct caller passing the catalog entry doesn't silently lose the
@@ -186,7 +186,7 @@ function scoreCustom(factors, opts) {
   score += cisa_kev ? RWEP_WEIGHTS.cisa_kev : 0;
   score += poc_available ? RWEP_WEIGHTS.poc_available : 0;
   score += (ai_assisted_weapon || ai_discovered) ? RWEP_WEIGHTS.ai_factor : 0;
-  // audit J F4 + F16: active_exploitation goes through the ladder rather
+  // active_exploitation goes through the ladder rather
   // than two hand-written branches with `Math.floor(weight/2)`. The floor
   // was a no-op for even weights (20/2 = 10) but would have silently
   // truncated to asymmetric results if a future operator bumped the
@@ -195,7 +195,7 @@ function scoreCustom(factors, opts) {
   // aligns the catalog scorer with playbook-runner._activeExploitationLadder.
   const aeMultiplier = ACTIVE_EXPLOITATION_LADDER[active_exploitation] ?? 0;
   score += RWEP_WEIGHTS.active_exploitation * aeMultiplier;
-  // v0.12.15 (audit J F1, F5): blast_radius numeric coercion must reject
+  // v0.12.15: blast_radius numeric coercion must reject
   // NaN, Infinity, and strings explicitly. The prior `typeof === 'number'`
   // check passed NaN (which is `typeof === 'number'`) into `Math.min/max`
   // which propagates NaN through the final clamp, defeating the [0,100]
@@ -208,12 +208,12 @@ function scoreCustom(factors, opts) {
   score += live_patch_available ? RWEP_WEIGHTS.live_patch_available : 0;
   score += rebootFactor ? RWEP_WEIGHTS.reboot_required : 0;
 
-  // audit J F10: keep the pre-clamp value so collectWarnings consumers can
+  // keep the pre-clamp value so collectWarnings consumers can
   // see deduction magnitude (e.g. a -25 raw score collapsed to 0 hides the
   // fact that the entry had three mitigating factors).
   const rawUnclamped = score;
 
-  // v0.12.15 (audit J F1): defense-in-depth clamp against any unforeseen
+  // v0.12.15: defense-in-depth clamp against any unforeseen
   // NaN production above (negative weight + Infinity + math edge case).
   const clamped = Number.isFinite(score) ? Math.min(100, Math.max(0, score)) : 0;
   if (opts && opts.collectWarnings) {
@@ -227,7 +227,7 @@ function scoreCustom(factors, opts) {
 }
 
 /**
- * audit J F3 + audit M P1-C bridge: derive an RWEP score from a
+ * Derive an RWEP score from a
  * `rwep_factors` object regardless of which shape it uses.
  *
  *   - SHAPE A (boolean / string-ladder): values are booleans + an
@@ -275,7 +275,7 @@ function compare(cveId, catalog, opts) {
   const entry = catalog[cveId];
   if (!entry) throw new Error(`CVE not in catalog: ${cveId}`);
 
-  // audit J F11: `--recompute` ignores the stored rwep_score and forces a
+  // `--recompute` ignores the stored rwep_score and forces a
   // fresh computation from rwep_factors. Useful for catching catalog drift
   // (stored score grew stale relative to current weights) and for auditing
   // the divergence between stored vs. formula-derived scores.
@@ -294,7 +294,7 @@ function compare(cveId, catalog, opts) {
   const cvssEquivalent = cvss * 10;
   const delta = rwep - cvssEquivalent;
 
-  // audit J F15: narrow the "broadly aligned" band from ±20 to ±10. The old
+  // narrow the "broadly aligned" band from ±20 to ±10. The old
   // ±20 band swallowed the Copy Fail RWEP-vs-CVSS divergence (delta = 12)
   // where the operator-facing point is precisely that the CVSS-calibrated
   // SLA is insufficient. ±10 is the tightest classifier that still treats
@@ -342,6 +342,15 @@ function validate(catalog) {
   const errors = [];
   for (const [cveId, entry] of Object.entries(catalog)) {
     if (cveId.startsWith('_')) continue;
+    // FF P1-1: skip auto-imported drafts. KEV/GHSA/OSV-discovered drafts
+    // store a conservative-default rwep_score (poc=true, reboot=true, etc.)
+    // alongside `poc_available: null` and other null-until-curated factor
+    // fields, so the recomputed-vs-stored divergence check ALWAYS fires
+    // against them — flooding the predeploy gate. Drafts are reviewed
+    // separately via the `_auto_imported_meta.curation_needed` list and the
+    // strict catalog validator's draft-warning tier. Once curation promotes
+    // an entry, `_auto_imported` is cleared and full validation resumes.
+    if (entry && entry._auto_imported === true) continue;
     for (const field of CVE_SCHEMA_REQUIRED) {
       if (!(field in entry)) {
         errors.push(`${cveId}: missing required field '${field}'`);

package/lib/sign.js

@@ -112,7 +112,7 @@ function generateKeypair({ rotate = false } = {}) {
   fs.writeFileSync(PRIVATE_KEY_PATH, privateKey, { encoding: 'utf8', mode: 0o600 });
   fs.writeFileSync(PUBLIC_KEY_PATH, publicKey, { encoding: 'utf8', mode: 0o644 });
 
-  // Audit I P1-3: on win32, fs.writeFileSync `mode` does not produce
+  // on win32, fs.writeFileSync `mode` does not produce
   // a POSIX-style restrictive ACL. Tighten via icacls so other desktop
   // users on the same workstation / CI runner can't read the key.
   restrictWindowsAcl(PRIVATE_KEY_PATH);
@@ -166,7 +166,7 @@ function signAll() {
     signed++;
   }
 
-  // Audit I P1-4: sign the manifest itself. Removes any existing
+  // sign the manifest itself. Removes any existing
   // manifest_signature field so the canonical bytes are deterministic
   // across re-runs, signs with the private key, then writes the result.
   // A coordinated attacker who rewrites the manifest (and snapshot, and
@@ -298,7 +298,7 @@ function loadManifest() {
 }
 
 /**
- * Audit I P1-4 — canonical byte form of the manifest, used for both
+ * canonical byte form of the manifest, used for both
  * signing (lib/sign.js) and verification (lib/verify.js).
  *
  * Contract: the same logical manifest content must produce the same bytes
@@ -343,7 +343,7 @@ function canonicalManifestBytes(manifest) {
  * Returns the manifest_signature object literal to splice into the
  * manifest top level.
  *
- * Audit O P1-A: the previous shape included a `signed_at` ISO timestamp.
+ * A: the previous shape included a `signed_at` ISO timestamp.
  * That field was stripped from the canonical bytes before signing (via
  * `delete clone.manifest_signature`), so it was NOT covered by the
  * signature — an attacker who replayed a known-valid signature could
@@ -369,7 +369,7 @@ function signCanonicalManifest(manifest, privateKey) {
 }
 
 /**
- * Audit I P1-3 — tighten Windows ACL on the private key.
+ * tighten Windows ACL on the private key.
  *
  * fs.writeFileSync({mode: 0o600}) on win32 only affects read-only
  * attributes; the file inherits its ACL from the parent. icacls strips

package/lib/validate-catalog-meta.js

@@ -163,7 +163,7 @@ function validateMeta(catalogPath, opts) {
       }
     }
 
-    /* Audit G F3 — freshness enforcement. When both meta.last_updated and
+    /* freshness enforcement. When both meta.last_updated and
      * freshness_policy.stale_after_days are present, surface a warning if
      * (now - last_updated) > stale_after_days. Patch-class release emits at
      * WARN level (does not fail validation); v0.13.0 will flip to an error.

package/lib/validate-cve-catalog.js

@@ -244,8 +244,8 @@ function additionalChecks(key, entry, ctx) {
   }
 
   // V2 — Cross-catalog reference resolution. Unresolved refs are warnings
-  // for v0.12.x; v0.13.0 will flip to hard failures. Audit D's V2 expansion
-  // (Audit G) extends the walk from cwe_refs only to attack_refs, atlas_refs,
+  // for v0.12.x; v0.13.0 will flip to hard failures. V2 expansion
+  // extends the walk from cwe_refs only to attack_refs, atlas_refs,
   // d3fend_refs, AND framework_control_gaps.
   const REF_FIELDS = [
     { field: 'atlas_refs', set: ctx.atlasKeys, file: 'data/atlas-ttps.json' },

package/lib/validate-indexes.js

@@ -47,7 +47,7 @@ function main() {
   const meta = JSON.parse(fs.readFileSync(META, "utf8"));
   const recorded = meta.source_hashes || {};
 
-  // Audit G F1 — reject an empty source_hashes table outright. The previous
+  // reject an empty source_hashes table outright. The previous
   // gate would silently pass when source_hashes was {} (or missing entirely)
   // because the for-loop body never executed; the resulting "0 sources" pass
   // banner falsely advertised the indexes as current. An empty source-hash
@@ -67,7 +67,7 @@ function main() {
   const manifest = JSON.parse(fs.readFileSync(ABS("manifest.json"), "utf8"));
   const liveSources = new Set();
   liveSources.add("manifest.json");
-  // Audit G F16 — use lstat to detect symlinks. A symlinked .json under data/
+  // use lstat to detect symlinks. A symlinked .json under data/
   // would be hashed via the followed target, allowing a malicious checkout
   // (or a misconfigured filesystem) to swap data origin without tripping the
   // gate. Reject symlinks outright.

package/lib/verify.js

@@ -69,7 +69,7 @@ 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
+// 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()
@@ -164,7 +164,7 @@ function signAll() {
   const manifestSig = crypto.sign(null, canonical, {
     key: privateKey, dsaEncoding: 'ieee-p1363',
   });
-  // Audit O P1-A: `signed_at` is intentionally OMITTED. The previous shape
+  // A: `signed_at` is intentionally OMITTED. The previous shape
   // emitted a `signed_at` timestamp alongside the Ed25519 signature, but
   // `signed_at` was stripped from the canonical bytes before signing — so
   // an attacker could replay a known-valid signature against the same
@@ -294,7 +294,7 @@ function loadManifest() {
 }
 
 /**
- * Audit I P1-4 — canonical byte form of the manifest.
+ * 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.
@@ -347,7 +347,7 @@ function verifyManifestSignature(manifest) {
   if (typeof sig.signature_base64 !== 'string') {
     return { status: 'invalid', reason: 'manifest_signature.signature_base64 missing or not a string' };
   }
-  // Audit O P1-E: require the algorithm field to be present and exactly
+  // E: require the algorithm field to be present and exactly
   // 'Ed25519'. The previous form accepted a missing algorithm field
   // (`if (sig.algorithm && sig.algorithm !== 'Ed25519')`) which let a
   // future downgrade attacker drop the field to bait a weaker default.
@@ -362,6 +362,25 @@ function verifyManifestSignature(manifest) {
   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; missing
+  // pin file remains warn-and-continue (legacy compat).
+  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,
+    };
+  }
   let signatureBytes;
   try {
     signatureBytes = Buffer.from(sig.signature_base64, 'base64');
@@ -389,7 +408,7 @@ function verifyManifestSignature(manifest) {
  * is a fatal-class bug — surface it loudly rather than verify-against-
  * a-corrupt-manifest.
  *
- * Audit I P1-4: also verifies the top-level manifest_signature. On
+ * 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
@@ -414,7 +433,7 @@ function loadManifestValidated() {
   for (const skill of manifest.skills) {
     validateSkillPath(skill.path);
   }
-  // Audit I P1-4 — manifest signature gate. Runs after schema + path
+  // manifest signature gate. Runs after schema + path
   // validation so a malformed manifest reports the structural failure
   // before the cryptographic one.
   const sigResult = verifyManifestSignature(manifest);
@@ -422,7 +441,7 @@ function loadManifestValidated() {
     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') {
-    // Audit O P1-D: dedupe the legacy-tarball warning. Many CLI verbs
+    // D: dedupe the legacy-tarball warning. Many CLI verbs
     // call loadManifestValidated() more than once per invocation; the
     // previous console.warn spammed stderr per call. Node's emitWarning()
     // with a stable `code` collapses repeated emissions automatically.
@@ -562,7 +581,7 @@ function validateAgainstSchema(value, schema, here, root) {
  * @returns {{sha256: string, sha3_512: string}|{error: string}}
  */
 /**
- * Audit G F4 — compare the live public-key fingerprint against the optional
+ * 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.
@@ -574,16 +593,46 @@ function validateAgainstSchema(value, schema, here, root) {
  * @param {{sha256:string}|null} liveFp  publicKeyFingerprint() output
  * @param {string} [pinPath]             optional override (testability)
  */
+/**
+ * KK P1-5: 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 four 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)
+ * tests/normalize-contract.test.js asserts byte-identical output across all
+ * four sites under a BOM + CRLF fuzz corpus.
+ */
+function loadExpectedFingerprintFirstLine(pinPath) {
+  let raw;
+  try { raw = fs.readFileSync(pinPath, 'utf8'); }
+  catch { return null; }
+  if (raw.length > 0 && raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1);
+  const lines = raw
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0 && !l.startsWith('#'));
+  return lines[0] || null;
+}
+
 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) || '';
+  // KK P1-5: 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
+  // first-line of "SHA256:..." (with leading BOM) that would never equal
+  // a live fingerprint.
+  const firstLine = loadExpectedFingerprintFirstLine(p) || '';
   if (firstLine === liveFp.sha256) return { status: 'match' };
   return {
     status: 'mismatch',
@@ -675,7 +724,7 @@ if (require.main === module) {
   console.log(`[verify] ${fp.sha256}`);
   console.log(`[verify] ${fp.sha3_512}`);
 
-  // Audit G F4 — pin check. When keys/EXPECTED_FINGERPRINT exists, the
+  // 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
@@ -721,6 +770,7 @@ module.exports = {
   validateAgainstSchema,
   publicKeyFingerprint,
   checkExpectedFingerprint,
+  loadExpectedFingerprintFirstLine,
   canonicalManifestBytes,
   verifyManifestSignature,
   EXPECTED_FINGERPRINT_PATH,