@blamejs/exceptd-skills 0.12.16 → 0.12.20

package/lib/refresh-network.js

@@ -194,14 +194,63 @@ function verifyDetached(publicKeyObj, payload, sigB64) {
 // v0.12.14 (audit F1, F7): 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 — the three normalize() implementations form a byte-stability
-// contract.
+// lib/sign.js + scripts/verify-shipped-tarball.js — the four normalize()
+// implementations form a byte-stability contract enforced by
+// tests/normalize-contract.test.js.
 function normalizeSkillBytes(buf) {
   let s = Buffer.isBuffer(buf) ? buf.toString("utf8") : String(buf);
   if (s.length > 0 && s.charCodeAt(0) === 0xFEFF) s = s.slice(1);
   return Buffer.from(s.replace(/\r\n/g, "\n"), "utf8");
 }
 
+// Audit O P1-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
+// with lib/sign.js canonicalManifestBytes() / lib/verify.js
+// canonicalManifestBytes() — tests/normalize-contract.test.js enforces.
+function canonicalizeForRefresh(value) {
+  if (Array.isArray(value)) return value.map(canonicalizeForRefresh);
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      out[key] = canonicalizeForRefresh(value[key]);
+    }
+    return out;
+  }
+  return value;
+}
+function canonicalManifestBytesForRefresh(manifest) {
+  const clone = Object.assign({}, manifest);
+  delete clone.manifest_signature;
+  const json = JSON.stringify(canonicalizeForRefresh(clone), null, 2);
+  return normalizeSkillBytes(Buffer.from(json, "utf8"));
+}
+function verifyTarballManifestSignature(manifest, publicKeyPem) {
+  const sig = manifest && manifest.manifest_signature;
+  if (!sig || typeof sig !== "object") return { status: "missing" };
+  if (typeof sig.signature_base64 !== "string") {
+    return { status: "invalid", reason: "manifest_signature.signature_base64 missing or not a string" };
+  }
+  if (sig.algorithm !== "Ed25519") {
+    return { status: "invalid", reason: `manifest_signature.algorithm must be 'Ed25519' (got ${JSON.stringify(sig.algorithm)})` };
+  }
+  let signatureBytes;
+  try { signatureBytes = Buffer.from(sig.signature_base64, "base64"); }
+  catch (e) { return { status: "invalid", reason: `malformed base64: ${e.message}` }; }
+  const bytes = canonicalManifestBytesForRefresh(manifest);
+  let ok = false;
+  try {
+    ok = crypto.verify(null, bytes, {
+      key: publicKeyPem,
+      dsaEncoding: "ieee-p1363",
+    }, signatureBytes);
+  } catch (e) {
+    return { status: "invalid", reason: `crypto.verify threw: ${e.message}` };
+  }
+  return ok ? { status: "valid" } : { status: "invalid", reason: "Ed25519 manifest signature did not verify against local public.pem" };
+}
+
 // Manifest path validation. Mirrors lib/verify.js validateSkillPath().
 function validateManifestSkillPath(skillPath) {
   if (typeof skillPath !== "string") throw new Error(`manifest skill.path must be a string, got ${typeof skillPath}`);
@@ -402,6 +451,33 @@ 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
+  // 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
+  // attacker who flipped paths/names/atlas_refs on entries already covered
+  // by per-skill signatures (which sign only the skill body bytes, not the
+  // metadata around them) could re-shape catalog routing without breaking
+  // any per-skill signature. The manifest signature closes that gap.
+  //
+  // Unlike post-install verify (which warns-and-continues on missing
+  // signature for legacy-tarball compat), refresh-network REQUIRES the
+  // signature: this code path is publishing fresh content into the local
+  // tree, and the tarball must already be ≥ v0.12.17 to have reached the
+  // registry through the sign-all gate.
+  const manifestSigResult = verifyTarballManifestSignature(tarballManifest, localPubKeyText);
+  if (manifestSigResult.status !== "valid") {
+    emit({
+      ok: false,
+      error: `tarball manifest_signature ${manifestSigResult.status} — refusing to swap`,
+      reason: manifestSigResult.reason || null,
+      hint: manifestSigResult.status === "missing"
+        ? "Tarball predates v0.12.17 manifest signing. Run `npm update -g @blamejs/exceptd-skills` instead so the full provenance-verified install path runs."
+        : "Tarball manifest envelope failed Ed25519 verification against the LOCAL public key. Run `npm update -g @blamejs/exceptd-skills` for the full provenance-verified path, or report this tarball at https://github.com/blamejs/exceptd-skills/issues.",
+    }, opts.json);
+    process.exitCode = 5; return;
+  }
+
   // v0.12.14 (audit F1): 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`,
@@ -603,4 +679,16 @@ if (require.main === module) {
   });
 }
 
-module.exports = { parseTar, fingerprintPublicKey };
+module.exports = {
+  parseTar,
+  fingerprintPublicKey,
+  // Audit P P1-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
+  // path's manifest envelope check.
+  verifyTarballManifestSignature,
+  canonicalManifestBytesForRefresh,
+};

package/lib/schemas/playbook.schema.json

@@ -323,7 +323,13 @@
                   "confidence": { "type": "string", "enum": ["low", "medium", "high", "deterministic"] },
                   "deterministic": { "type": "boolean", "description": "True if presence is definitive proof, not probabilistic." },
                   "atlas_ref": { "type": "string" },
-                  "attack_ref": { "type": "string" }
+                  "attack_ref": { "type": "string" },
+                  "cve_ref": { "type": "string", "description": "Optional CVE / MAL-* / SNYK-* identifier this indicator binds to. When the indicator fires, the named entry is pulled into analyze.matched_cves[] (v0.12.14 F3)." },
+                  "false_positive_checks_required": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "description": "v0.12.12+ contract: each entry is a check an AI assistant or operator must satisfy before this indicator's `hit` verdict can drive classification:detected. The runner downgrades a hit to inconclusive when this array is non-empty and no fp_checks attestation is supplied via signal_overrides[`<id>__fp_checks`]."
+                  }
                 }
               }
             },

package/lib/sign.js

@@ -24,6 +24,38 @@
  * validateSkillPath() below). Without this a tampered manifest could
  * sign or verify arbitrary files outside the skills/ tree.
  *
+ * Manifest signing contract (must mirror lib/verify.js):
+ *   After all individual skill signatures are written, sign-all signs
+ *   the manifest itself. The canonical bytes are computed as:
+ *     1. Read the manifest object after all skill signatures land.
+ *     2. Delete the top-level `manifest_signature` field if present
+ *        (idempotency — re-signing after rotation must produce the same
+ *        canonical bytes whether or not a stale signature is there).
+ *     3. Serialize via JSON.stringify(obj, sortedTopLevelKeys, 2). The
+ *        top-level keys are stringified in lexicographic order so a
+ *        re-ordered manifest signs to the same bytes. Nested objects
+ *        keep their natural key order (skills[] entries already follow
+ *        a stable convention).
+ *     4. Apply normalize() (CRLF→LF, BOM strip) — same transform skills
+ *        use, so the manifest signature survives any line-ending churn.
+ *   ANY change to canonicalManifestBytes() or this contract requires
+ *   the matching change in lib/verify.js. A coordinated attacker who
+ *   rewrites manifest.json + manifest-snapshot.json + manifest-snapshot.sha256
+ *   without the private key produces a manifest_signature mismatch that
+ *   lib/verify.js refuses to load.
+ *
+ * Windows ACL contract:
+ *   On win32, `fs.writeFileSync(..., { mode: 0o600 })` only affects
+ *   read-only attributes — it does NOT establish a POSIX-style restrictive
+ *   ACL. Any process running under the same desktop user can read the key
+ *   by default ACL inheritance from the parent. After writing
+ *   .keys/private.pem on Windows, restrictWindowsAcl() shells to icacls
+ *   to strip inherited entries and grant Full Control only to the current
+ *   user. If icacls is unavailable (Server Core, exotic shells), the call
+ *   warns to stderr but does not fail keypair generation — generating the
+ *   key was the load-bearing step; ACL tightening is best-effort hardening
+ *   on top.
+ *
  * Signing ceremony:
  *   1. node lib/sign.js generate-keypair    — generate keypair (one time, per deployment)
  *   2. node lib/sign.js sign-all            — sign all skills (after any content change)
@@ -44,6 +76,7 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
+const { execFileSync } = require('child_process');
 
 const ROOT = path.join(__dirname, '..');
 const MANIFEST_PATH = path.join(ROOT, 'manifest.json');
@@ -79,6 +112,11 @@ 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
+  // 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);
+
   if (rotate) {
     console.log('[sign] Keypair rotated. All existing signatures are now invalid — run: node lib/sign.js sign-all');
   } else {
@@ -128,6 +166,16 @@ function signAll() {
     signed++;
   }
 
+  // Audit I P1-4: 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
+  // snapshot SHA) without the private key produces an invalid manifest
+  // signature; lib/verify.js refuses to load the manifest.
+  delete manifest.manifest_signature;
+  const manifestSig = signCanonicalManifest(manifest, privateKey);
+  manifest.manifest_signature = manifestSig;
+
   fs.writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
 
   // S5: verdict line FIRST, fingerprint banner after. An operator
@@ -136,7 +184,7 @@ function signAll() {
   if (errors > 0) {
     console.error(`\n[sign] FAILED — ${signed} signed, ${errors} errors.`);
   } else {
-    console.log(`\n[sign] ${signed} skills signed.`);
+    console.log(`\n[sign] ${signed} skills signed. Manifest signed.`);
   }
   printFingerprintBanner();
 
@@ -160,6 +208,11 @@ function signOne(skillName) {
   skill.signed_at = new Date().toISOString();
   delete skill.sha256;
 
+  // P1-4: re-sign the manifest after the per-skill signature changes.
+  // Without this a single-skill sign leaves manifest_signature stale.
+  delete manifest.manifest_signature;
+  manifest.manifest_signature = signCanonicalManifest(manifest, privateKey);
+
   fs.writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
   console.log(`[sign] Signed: ${skillName}`);
   printFingerprintBanner();
@@ -244,6 +297,113 @@ function loadManifest() {
   return JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf8'));
 }
 
+/**
+ * Audit I P1-4 — 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
+ * regardless of (a) whether a stale manifest_signature is present, (b)
+ * key order at any depth, (c) line endings or BOM.
+ *
+ *   1. Clone, delete manifest_signature.
+ *   2. Recursively sort object keys at every depth (NOT the top-level
+ *      whitelist trap — see codex P1 PR #12: passing
+ *      `Object.keys(manifest).sort()` as the JSON.stringify replacer-array
+ *      treats it 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. Now we deep-canonicalize
+ *      every object).
+ *   3. Apply normalize() — strip leading BOM, convert CRLF → LF.
+ *
+ * @param {object} manifest
+ * @returns {Buffer} canonical UTF-8 bytes
+ */
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      out[key] = canonicalize(value[key]);
+    }
+    return out;
+  }
+  return value;
+}
+
+function canonicalManifestBytes(manifest) {
+  const clone = { ...manifest };
+  delete clone.manifest_signature;
+  const json = JSON.stringify(canonicalize(clone), null, 2);
+  return Buffer.from(normalize(json), 'utf8');
+}
+
+/**
+ * Sign the canonical manifest bytes with the Ed25519 private key.
+ * 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.
+ * 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
+ * rewrite `signed_at` to any value, lending false freshness authority to
+ * a stale signature. The field is now omitted entirely. Freshness signal
+ * lives outside the signed bytes (git-log mtime of manifest.json, npm
+ * publish timestamp).
+ *
+ * @param {object} manifest
+ * @param {string} privateKey PEM-encoded Ed25519 private key
+ * @returns {{algorithm:'Ed25519', signature_base64:string}}
+ */
+function signCanonicalManifest(manifest, privateKey) {
+  const bytes = canonicalManifestBytes(manifest);
+  const sig = crypto.sign(null, bytes, {
+    key: privateKey,
+    dsaEncoding: 'ieee-p1363',
+  });
+  return {
+    algorithm: 'Ed25519',
+    signature_base64: sig.toString('base64'),
+  };
+}
+
+/**
+ * Audit I P1-3 — 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
+ * inheritance and grants Full Control only to the current user. Any
+ * failure (icacls missing, exotic shell, environment without USERNAME)
+ * is warned to stderr — generating the key was the load-bearing step,
+ * ACL tightening is best-effort hardening.
+ *
+ * @param {string} targetPath absolute path of the private key file
+ */
+function restrictWindowsAcl(targetPath) {
+  if (process.platform !== 'win32') return;
+  const user = process.env.USERNAME;
+  if (!user) {
+    console.warn('[sign] WARN: USERNAME env var not set — skipping Windows ACL hardening on ' + targetPath);
+    return;
+  }
+  try {
+    execFileSync('icacls', [
+      targetPath,
+      '/inheritance:r',
+      '/grant:r',
+      `${user}:F`,
+    ], { stdio: ['ignore', 'ignore', 'pipe'] });
+  } catch (err) {
+    console.warn(
+      '[sign] WARN: icacls hardening failed on ' + targetPath + ': ' +
+      ((err && err.message) || String(err)) +
+      ' — the key was written but ACL inheritance was not stripped. ' +
+      'Other desktop users on this machine may be able to read it.'
+    );
+  }
+}
+
 function printFingerprintBanner() {
   if (!fs.existsSync(PUBLIC_KEY_PATH)) return;
   try {
@@ -303,4 +463,13 @@ Signing ceremony (first time):
   }
 }
 
-module.exports = { generateKeypair, signAll, signOne, normalize, validateSkillPath };
+module.exports = {
+  generateKeypair,
+  signAll,
+  signOne,
+  normalize,
+  validateSkillPath,
+  canonicalManifestBytes,
+  signCanonicalManifest,
+  restrictWindowsAcl,
+};

package/lib/verify.js

@@ -30,6 +30,24 @@
  * 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)
@@ -112,7 +130,19 @@ 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 = loadManifestValidated();
+  // 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.
+  const manifest = loadManifest();
+  const schema = JSON.parse(fs.readFileSync(MANIFEST_SCHEMA_PATH, 'utf8'));
+  const errors0 = validateAgainstSchema(manifest, schema, 'manifest');
+  if (errors0.length > 0) {
+    const detail = errors0.slice(0, 10).map(e => '  - ' + e).join('\n');
+    throw new Error(`[verify] manifest.json failed schema validation before re-sign:\n${detail}`);
+  }
+  for (const skill of (manifest.skills || [])) validateSkillPath(skill.path);
+
   const result = { signed: [], errors: [] };
 
   for (const skill of manifest.skills) {
@@ -128,8 +158,27 @@ 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',
+  });
+  // Audit O P1-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
+  // canonical content while rewriting `signed_at` to any value, lending
+  // false freshness authority to a stale signature. Operators who need
+  // freshness signal should consult the git-log mtime of manifest.json
+  // (or the npm publish timestamp), which are external to the signed bytes.
+  manifest.manifest_signature = {
+    algorithm: 'Ed25519',
+    signature_base64: manifestSig.toString('base64'),
+  };
+
   fs.writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
-  console.log(`[verify] Signed ${result.signed.length} skills with Ed25519 private key.`);
+  console.log(`[verify] Signed ${result.signed.length} skills with Ed25519 private key. Manifest signed.`);
   return result;
 }
 
@@ -244,6 +293,94 @@ function loadManifest() {
   return JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf8'));
 }
 
+/**
+ * Audit I P1-4 — 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
+ */
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      out[key] = canonicalize(value[key]);
+    }
+    return out;
+  }
+  return value;
+}
+
+function canonicalManifestBytes(manifest) {
+  const clone = { ...manifest };
+  delete clone.manifest_signature;
+  const json = JSON.stringify(canonicalize(clone), null, 2);
+  return Buffer.from(normalize(json), 'utf8');
+}
+
+/**
+ * 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
+ */
+function verifyManifestSignature(manifest) {
+  const sig = manifest && manifest.manifest_signature;
+  if (!sig || typeof sig !== 'object') return { status: 'missing' };
+  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
+  // '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.
+  // lib/sign.js always writes the field, so no legitimate consumer breaks.
+  if (sig.algorithm !== 'Ed25519') {
+    return {
+      status: 'invalid',
+      reason: `manifest_signature.algorithm must be exactly 'Ed25519' (got ${JSON.stringify(sig.algorithm)})`,
+    };
+  }
+  const publicKey = loadPublicKey();
+  if (!publicKey) {
+    return { status: 'no-key', reason: 'public key missing at keys/public.pem' };
+  }
+  let signatureBytes;
+  try {
+    signatureBytes = Buffer.from(sig.signature_base64, 'base64');
+  } catch (e) {
+    return { status: 'invalid', reason: `malformed base64 in manifest_signature: ${e.message}` };
+  }
+  const bytes = canonicalManifestBytes(manifest);
+  let ok = false;
+  try {
+    ok = crypto.verify(null, bytes, {
+      key: publicKey,
+      dsaEncoding: 'ieee-p1363',
+    }, signatureBytes);
+  } catch (e) {
+    return { status: 'invalid', reason: `crypto.verify threw: ${e.message}` };
+  }
+  return ok ? { status: 'valid' } : { status: 'invalid', reason: 'Ed25519 manifest signature did not verify against keys/public.pem — manifest.json has been tampered or signed with a different key' };
+}
+
 /**
  * Load the manifest and validate it against
  * lib/schemas/manifest.schema.json + the path-traversal guard.
@@ -252,6 +389,14 @@ function loadManifest() {
  * 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
+ * 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}
  */
 function loadManifestValidated() {
@@ -269,6 +414,28 @@ function loadManifestValidated() {
   for (const skill of manifest.skills) {
     validateSkillPath(skill.path);
   }
+  // Audit I P1-4 — manifest signature gate. Runs after schema + path
+  // validation so a malformed manifest reports the structural failure
+  // before the cryptographic one.
+  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') {
+    // Audit O P1-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.
+    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 `node lib/sign.js sign-all` to add the signature.',
+      { code: 'EXCEPTD_MANIFEST_UNSIGNED' }
+    );
+  } else if (sigResult.status === 'no-key') {
+    // Surfaced separately so the warning matches the missing-key path
+    // that verifyAll() already handles — don't fail here, the verifyAll
+    // entry point will emit a no_key result of its own.
+    console.warn(`[verify] WARN: cannot verify manifest_signature — ${sigResult.reason}.`);
+  }
   return manifest;
 }
 
@@ -554,5 +721,7 @@ module.exports = {
   validateAgainstSchema,
   publicKeyFingerprint,
   checkExpectedFingerprint,
+  canonicalManifestBytes,
+  verifyManifestSignature,
   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-14T15:55:39.383Z",
+  "_generated_at": "2026-05-14T18:49:21.239Z",
   "atlas_version": "5.1.0",
   "skill_count": 38,
   "skills": [

package/manifest-snapshot.sha256

@@ -1 +1 @@
-ca9d31e533c9d494e1ac5875e0a45176101438c3d75d44387187e367ccae21ad  manifest-snapshot.json
+7e10f4b0b1c6cfa096e35ca28cdd8a95c19e51537cdd3e22628aecb87c72db1b  manifest-snapshot.json