@blamejs/exceptd-skills 0.19.32 → 0.19.34

package/lib/refresh-network.js

@@ -2,35 +2,10 @@
 "use strict";
 
 /**
- * lib/refresh-network.js
- *
- * `exceptd refresh --network` — fetch the latest signed catalog snapshot
- * from the maintainer's npm-published tarball, verify every skill
- * signature against the Ed25519 public key already shipped in the
- * operator's local install, and swap in the fresh `data/`, `manifest.json`,
- * and `manifest-snapshot.json`.
- *
- * Trust boundary:
- *   - Trust anchor = the `keys/public.pem` already present in the local
- *     install. Operators rotated the key by running `npm install -g` at
- *     some earlier point; nothing in --network changes that root.
- *   - Tarball authenticity = each shipped `skills/<name>/SKILL.md` (or
- *     equivalent payload) has an Ed25519 signature in manifest.json that
- *     resolves against the local public key. ANY signature mismatch aborts
- *     the swap; the local install is untouched.
- *
- * Why this exists:
- *   `npm update -g` already pulls the same signed artifact (npm provenance
- *   + OIDC). --network is for operators who want only the data slice
- *   without re-resolving CLI/lib code, OR who are on a constrained host
- *   where the global npm install requires sudo and they're running a
- *   user-local copy they can write to.
- *
- * Requires write access to the install directory. Fails fast with a
- * clear message + the `npm update` fallback when the install is not
- * writable (typical for system-global installs).
- *
- * Zero npm deps. Node 24 stdlib only.
+ * `exceptd refresh --network` — fetch the npm-published tarball, verify every
+ * skill signature against the local install's Ed25519 key, and swap in the
+ * fresh `data/`, `manifest.json` and `manifest-snapshot.json`. The local
+ * `keys/public.pem` is the trust anchor; --network never rotates it.
  */
 
 const fs = require("fs");
@@ -42,21 +17,12 @@ const os = require("os");
 
 const ROOT = path.resolve(__dirname, "..");
 const PKG_NAME = "@blamejs/exceptd-skills";
-// Unscoped basename for the npm tarball filename: @scope/name -> name.
 const PKG_UNSCOPED = PKG_NAME.includes("/") ? PKG_NAME.split("/").pop() : PKG_NAME;
-// Strict semver — the ONLY registry-metadata field embedded in the fetch URL.
-// A value that passes this guard cannot carry a path separator, URL scheme, or
-// host, so the canonical tarball URL built from it has no metadata-controlled
-// destination component.
+// Strict semver — the only registry-metadata value embedded in the fetch URL.
 const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
 
-// The canonical npm tarball URL for this package@version, built entirely from
-// string literals plus a semver-guarded version. The fetch destination is no
-// longer derived from the metadata-supplied dist.tarball, so a tampered or
-// fixture-injected /latest response cannot steer the download at an internal or
-// attacker-controlled address — strictly stronger than host-allowlisting the
-// metadata URL. Content trust still rests on the SHA-512/SRI + shasum + Ed25519
-// checks downstream.
+// Built from literals plus the guarded version, never from the metadata's
+// dist.tarball, so a tampered /latest response cannot steer the download.
 function canonicalTarballUrl(version) {
   return `https://registry.npmjs.org/${PKG_NAME}/-/${PKG_UNSCOPED}-${version}.tgz`;
 }
@@ -83,16 +49,11 @@ function emit(obj, json) {
 }
 
 function progress(line, json) {
-  // Progress messages always go to stderr so --json consumers see only the
-  // final JSON result on stdout. Plain mode also routes progress through
-  // stderr (so `exceptd refresh --network > catalog.log` doesn't mix logs
-  // with structured output).
+  // Progress goes to stderr even in plain mode, so stdout carries only the result.
   process.stderr.write(`[refresh-network] ${line}\n`);
 }
 
-// Cap the registry metadata read so a hostile/misconfigured endpoint can't
-// stream unbounded JSON into RAM (the /latest response is a few KB; 16 MB is
-// generous headroom). Symmetric with getBuffer's tarball streaming cap.
+// Caps the registry metadata read against an endpoint streaming unbounded JSON.
 const JSON_RESPONSE_CAP_BYTES = 16 * 1024 * 1024;
 
 function getJsonOnce(url, timeoutMs) {
@@ -129,34 +90,18 @@ function getJsonOnce(url, timeoutMs) {
   });
 }
 
-// Adopt the vendored blamejs retry primitive: a transient registry failure
-// (HTTP 429/5xx, ECONNRESET/ETIMEDOUT family) is retried with exponential
-// backoff + jitter instead of aborting the whole --network refresh on the
-// first network hiccup. Permanent conditions (parse error, size-cap) carry no
-// statusCode/code, so the classifier does not retry them.
+// Transient failures (429/5xx, ECONNRESET/ETIMEDOUT) retry; permanent ones
+// (parse error, size cap) carry no statusCode/code, so the classifier skips them.
 function getJson(url, timeoutMs) {
-  // Lazy require: a parseTar-only consumer (scripts/verify-shipped-tarball.js)
-  // loads this module in a context where vendor/ may not be present, and it
-  // never calls getJson — so retry must not be a load-time dependency.
+  // Lazy: verify-shipped-tarball.js loads this module for parseTar where vendor/ may be absent.
   const { withRetry } = require("../vendor/blamejs/retry.js");
   return withRetry(() => getJsonOnce(url, timeoutMs), { maxAttempts: 3, baseDelayMs: 100, maxDelayMs: 2000, jitterFactor: 0.5 });
 }
 
-// The tarball URL is taken from the registry metadata (or, under
-// EXCEPTD_REGISTRY_FIXTURE, a local fixture file), so it is not a hardcoded
-// constant the way the /latest metadata URL is. Pin its host to the npm
-// registry the metadata was queried from, so a tampered metadata response or
-// fixture cannot steer the fetch at an internal or attacker-controlled address.
-// Content trust still rests on the SHA-512/SRI + shasum + Ed25519 checks below;
-// this is fetch-destination defense-in-depth.
 const ALLOWED_TARBALL_HOST = /(?:^|\.)npmjs\.org$|(?:^|\.)npmjs\.com$/;
 
-// Exported for in-process tests of the fetch-destination guard.
-// The guard parses the URL once and rejects any non-default port BEFORE the
-// hostname test, so validation and the subsequent https.get({host,path})
-// connect (which reuses u.host — port-inclusive) agree on the same value.
-// Without the port check a `registry.npmjs.org:9999` URL would pass the
-// hostname-only allowlist yet connect to the attacker-chosen port.
+// Rejects a non-default port before the hostname test: `registry.npmjs.org:9999`
+// passes a hostname-only allowlist yet connects to the attacker's port.
 function isAllowedTarballHost(url) {
   try {
     const u = new URL(url);
@@ -188,8 +133,6 @@ function getBufferOnce(url, timeoutMs) {
       }
       const chunks = [];
       let total = 0;
-      // 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;
         if (total > cap) {
@@ -205,39 +148,29 @@ function getBufferOnce(url, timeoutMs) {
   });
 }
 
-// Wrap the tarball fetch in the same vendored retry primitive (BJS-01). The
-// host-allowlist rejection + size-cap carry no statusCode/code, so a permanent
-// refusal is not retried; a transient 5xx / reset / timeout is.
+// Same classifier as getJson: the host refusal and the size cap are permanent.
 function getBuffer(url, timeoutMs) {
   const { withRetry } = require("../vendor/blamejs/retry.js"); // lazy — see getJson
   return withRetry(() => getBufferOnce(url, timeoutMs), { maxAttempts: 3, baseDelayMs: 100, maxDelayMs: 2000, jitterFactor: 0.5 });
 }
 
 /**
- * Parse a tar buffer (uncompressed) and return [{ name, body }] entries.
- * Tiny implementation — supports the GNU ustar variant npm produces.
- * Skips PaxHeader entries; treats long-link entries (type L) by stitching
- * the next entry's name from the long-link body.
+ * Parse an uncompressed tar buffer into [{ name, body }] — the GNU ustar
+ * variant npm produces; a type-L entry supplies the following entry's name.
  */
 function parseTar(buf) {
   const entries = [];
   let offset = 0;
   let pendingLongName = null;
-  // v0.12.12: tarballs from a compromised registry CDN could ship entries
-  // with `..`-bearing names targeting paths outside the install root. The
-  // immediate callers (verify-shipped-tarball.js + the network update path)
-  // do hash + signature checks before honoring entries, so this is
-  // defense-in-depth — drop the entry rather than handing a path-traversal
-  // string downstream.
+  // An entry whose name escapes the extraction root is dropped.
   const isSafeName = (n) => {
     if (typeof n !== "string" || n.length === 0) return false;
-    // Reject absolute paths AND any segment that is exactly ".."
     if (/^[\\/]/.test(n) || /^[A-Za-z]:[\\/]/.test(n)) return false;
     return !n.split(/[\\/]/).some((seg) => seg === "..");
   };
   while (offset + 512 <= buf.length) {
     const block = buf.subarray(offset, offset + 512);
-    // empty block = end-of-archive marker
+    // An all-zero block is the end-of-archive marker.
     if (block.every((b) => b === 0)) break;
     let name = block.subarray(0, 100).toString("utf8").replace(/\0.*$/, "");
     const sizeStr = block.subarray(124, 136).toString("utf8").replace(/\0.*$|\s+$/g, "").trim();
@@ -255,7 +188,6 @@ function parseTar(buf) {
         entries.push({ name, body: buf.subarray(dataStart, dataEnd) });
       }
     }
-    // round up to 512
     offset = dataStart + Math.ceil(size / 512) * 512;
   }
   return entries;
@@ -275,13 +207,9 @@ function verifyDetached(publicKeyObj, payload, sigB64) {
   } catch { return false; }
 }
 
-// Pinned npm registry signing keys (https://registry.npmjs.org/-/npm/v1/keys).
-// The registry signs `<pkg>@<version>:<integrity>` with an ECDSA P-256
-// (secp256r1 / ecdsa-sha2-nistp256) key; `dist.signatures[]` carries the
-// keyid + base64 signature. These keys are pinned in-tree on purpose: fetching
-// them over the network would mean authenticating the metadata response with a
-// key obtained from the same untrusted channel, which is circular. They also
-// rotate rarely and out-of-band. Values are SPKI DER, base64-encoded.
+// Pinned npm registry signing keys (https://registry.npmjs.org/-/npm/v1/keys),
+// as base64 SPKI DER. Pinned in-tree because fetching them over the channel
+// they authenticate would be circular.
 const NPM_REGISTRY_KEYS = Object.freeze({
   "SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA":
     "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE1Olb3zMAFFxXKHiIkQO5cJ3Yhl5i6UPp+IhuteBJbuHcA5UogKo0EWtlWwW6KSaKoTNEYL7JlCQiVnkhBktUgg==",
@@ -289,18 +217,8 @@ const NPM_REGISTRY_KEYS = Object.freeze({
     "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEY6Ya7W++7aUPzvMTrezH6Ycx3c+HOKYCcNGybJZSCJq/fd7Qa8uuAKtdIkUQtQiEKERhAmE5lMMJhP8OkDOa2g==",
 });
 
-// Verify the npm registry's signature over `<pkg>@<version>:<integrity>`.
-// Returns:
-//   { status: "valid", keyid }            — a pinned key verified the signature
-//   { status: "absent" }                  — no dist.signatures entries supplied
-//   { status: "unverifiable", reason }     — integrity missing (nothing to sign over)
-//   { status: "unknown-keyid", keyid }     — signature keyid is not a pinned npm key
-//   { status: "invalid", reason }          — a present, pinned-keyid signature did NOT verify
-//
-// The caller treats `valid` as an authenticity anchor over the WHOLE tarball
-// (including the unsigned data/ tree), `invalid`/`unknown-keyid` as a hard
-// refusal, and `absent`/`unverifiable` as warn-and-continue (so private or
-// pre-signing registries still work — the SHA-512/SHA-1 gates still apply).
+// Returns { status }: valid | absent | unverifiable | unknown-keyid | invalid.
+// Callers refuse on invalid and unknown-keyid, and warn-and-continue otherwise.
 function verifyNpmRegistrySignature(pkg, version, integrity, signatures) {
   if (!Array.isArray(signatures) || signatures.length === 0) return { status: "absent" };
   if (typeof integrity !== "string" || integrity.length === 0) {
@@ -325,24 +243,17 @@ function verifyNpmRegistrySignature(pkg, version, integrity, signatures) {
   return { status: "invalid", reason: "no dist.signatures[] entry verified against the pinned npm registry key" };
 }
 
-// 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()
-// implementations form a byte-stability contract enforced by
-// tests/normalize-contract.test.js.
+// CRLF/BOM normalization, duplicated to keep this module dependency-free. Any
+// change must be mirrored in lib/verify.js, lib/sign.js and
+// scripts/verify-shipped-tarball.js; tests/normalize-contract.test.js enforces it.
 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");
 }
 
-// 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.
+// Canonical-bytes computation must stay in lockstep with
+// canonicalManifestBytes() in lib/sign.js and lib/verify.js.
 function canonicalizeForRefresh(value) {
   if (Array.isArray(value)) return value.map(canonicalizeForRefresh);
   if (value && typeof value === "object") {
@@ -385,7 +296,7 @@ function verifyTarballManifestSignature(manifest, publicKeyPem) {
   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().
+// 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}`);
   if (skillPath.includes("\\")) throw new Error(`manifest skill.path must use forward slashes: ${JSON.stringify(skillPath)}`);
@@ -394,10 +305,7 @@ function validateManifestSkillPath(skillPath) {
   return skillPath;
 }
 
-// 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.
+// Buffered-tarball cap; EXCEPTD_TARBALL_SIZE_CAP_BYTES overrides it.
 const TARBALL_SIZE_CAP_BYTES_DEFAULT = 200 * 1024 * 1024;
 function tarballSizeCap() {
   const env = parseInt(process.env.EXCEPTD_TARBALL_SIZE_CAP_BYTES, 10);
@@ -409,15 +317,9 @@ async function main() {
   const localPkg = JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf8"));
   const localVersion = localPkg.version;
 
-  // Air-gap refusal. --network needs egress to registry.npmjs.org for the
-  // /latest metadata + tarball pull. Under air-gap there is no offline
-  // substitute, so refuse before any network attempt and point at the
-  // offline workflow. The refusal is UNCONDITIONAL w.r.t.
-  // EXCEPTD_REGISTRY_FIXTURE: a present metadata fixture only stubs the
-  // /latest read, not the subsequent tarball fetch (getBuffer still hits
-  // canonicalUrl), so honoring the fixture under air-gap would let egress
-  // happen anyway while silently disabling an operator-facing control.
-  // Offline tests exercise the metadata+tarball path WITHOUT --air-gap.
+  // Refused before any network attempt, and unconditional with respect to
+  // EXCEPTD_REGISTRY_FIXTURE — the fixture stubs only the /latest read, so
+  // honoring it here would let the tarball fetch reach the network anyway.
   if (opts.airGap) {
     emit({
       ok: false,
@@ -432,11 +334,8 @@ async function main() {
   let meta;
   try {
     if (process.env.EXCEPTD_REGISTRY_FIXTURE) {
-      // Honor the same fixture mechanism as upstream-check so test runners
-      // can exercise the offline / reachable / unreachable branches without
-      // touching the network. Fixture shape: a JSON file matching the
-      // /<pkg>/latest registry response (must include version + dist.tarball
-      // + dist.shasum, or just version to exercise the early-return path).
+      // Fixture shape mirrors upstream-check's /<pkg>/latest response: version +
+      // dist.tarball + dist.shasum, or version alone for the already-at-latest path.
       meta = JSON.parse(fs.readFileSync(process.env.EXCEPTD_REGISTRY_FIXTURE, "utf8"));
     } else {
       meta = await getJson(`https://registry.npmjs.org/${encodeURIComponent(PKG_NAME).replace(/%40/g, "@").replace(/%2F/g, "/")}/latest`, opts.timeoutMs);
@@ -461,9 +360,7 @@ async function main() {
     return;
   }
 
-  // Writable-install check. Global installs typically live in a
-  // root-owned dir; refusing to fail-then-leave-partial is the safer
-  // contract.
+  // Probe writability before anything is fetched — failing here beats failing mid-swap.
   const writeProbe = path.join(ROOT, `.write-probe-${process.pid}`);
   try {
     fs.writeFileSync(writeProbe, "");
@@ -477,13 +374,9 @@ async function main() {
     process.exitCode = 3; return;
   }
 
-  // Build the fetch destination from constants + a semver-validated version
-  // rather than from the metadata-supplied dist.tarball, so the registry
-  // response cannot steer the download's host or path. The metadata URL is
-  // still cross-checked for visibility; a divergence is noted, not fatal,
-  // because the authenticity anchor is the SHA-512/shasum/Ed25519 chain below.
-  // Guard the SAME binding that the URL is built from (`safeVersion`), so the
-  // semver check is the only path by which a metadata value reaches the fetch.
+  // Guard the same binding the URL is built from, so the semver check is the only
+  // path a metadata value reaches the fetch. A dist.tarball divergence is noted,
+  // not fatal — authenticity rests on the hash and signature chain below.
   const safeVersion = typeof latestVersion === "string" ? latestVersion : "";
   if (!SEMVER_RE.test(safeVersion)) {
     emit({ ok: false, error: `registry metadata version is not valid semver: ${safeVersion.slice(0, 64)}` }, opts.json);
@@ -504,32 +397,15 @@ async function main() {
     process.exitCode = 2; return;
   }
 
-  // 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;
   }
 
-  // Verify SHA-512 SRI first (collision-resistant beyond SHA-1 reach), then
-  // SHA-1 shasum for compatibility. Both are transport hashes drawn from the
-  // registry metadata response, so they only prove the downloaded tarball
-  // matches the hashes THAT RESPONSE declared — an attacker who can forge the
-  // metadata serves a tampered tarball plus matching SHA-512/SHA-1 and both
-  // pass. The npm registry's signature over `<pkg>@<version>:<integrity>`
-  // (verified further below, after the both-absent refusal) is the only layer
-  // an attacker forging the metadata cannot also forge, because it is made
-  // with npm's registry private key, which they do not hold.
-  //
-  // `integrityVerified` records whether at least one transport hash actually
-  // matched the downloaded bytes. The per-skill + manifest Ed25519 signatures
-  // below authenticate skills/ + manifest.json, but the swap loop ALSO
-  // replaces data/ and manifest-snapshot.json, which carry no per-content
-  // signature — a transport hash is their only integrity anchor. When the
-  // registry metadata supplies NEITHER dist.integrity (sha512 SRI) NOR a
-  // dist.shasum, both branches are skipped and those bytes would otherwise be
-  // swapped in with zero verification, so the both-absent case is refused
-  // below rather than falling through to an unauthenticated swap.
+  // Both hashes come from the same metadata response as the tarball URL, so they
+  // prove only that the download matches what that response declared.
+  // `integrityVerified` gates the unsigned data/ + manifest-snapshot.json swap.
   let integrityVerified = false;
   if (tarballIntegrity && /^sha512-/.test(tarballIntegrity)) {
     const expected = tarballIntegrity.slice("sha512-".length);
@@ -540,13 +416,10 @@ async function main() {
     }
     integrityVerified = true;
   } else if (tarballIntegrity) {
-    // Non-sha512 SRI (e.g. sha384) — emit a warning but accept; SHA-1 path
-    // below still gates. A non-sha512 SRI is not actually checked here, so it
-    // does not count toward integrityVerified.
+    // A non-sha512 SRI is not checked, so it does not count toward integrityVerified.
     progress(`note: dist.integrity present but not sha512: ${tarballIntegrity.slice(0, 40)}`, opts.json);
   }
 
-  // Verify shasum (registry-provided integrity).
   if (tarballShasum) {
     const actual = crypto.createHash("sha1").update(tgzBuf).digest("hex");
     if (actual !== tarballShasum) {
@@ -556,13 +429,8 @@ async function main() {
     integrityVerified = true;
   }
 
-  // Refuse the swap when no transport hash was verifiable. data/ and
-  // manifest-snapshot.json have no per-content signature, so absent both
-  // dist.integrity and dist.shasum there is no integrity anchor on those bytes
-  // and a tampered registry response (or a hostile EXCEPTD_REGISTRY_FIXTURE)
-  // could inject arbitrary catalog/playbook/index content. `npm update -g`
-  // runs the full provenance-verified path (sha512 SRI + npm Ed25519 registry
-  // signatures + sigstore attestations), so it is the correct fallback.
+  // Without a verified transport hash, a tampered registry response — or a hostile
+  // EXCEPTD_REGISTRY_FIXTURE — injects arbitrary catalog content.
   if (!integrityVerified) {
     emit({
       ok: false,
@@ -572,19 +440,8 @@ async function main() {
     process.exitCode = 4; return;
   }
 
-  // Verify the npm registry's signature over `<pkg>@<version>:<integrity>`.
-  // This is the authenticity anchor the transport hashes above cannot be: the
-  // hashes come from the same (possibly forged) metadata response as the
-  // tarball URL, but this signature is made with npm's registry private key.
-  // It transitively authenticates the WHOLE tarball — including the data/ and
-  // manifest-snapshot.json bytes that carry no per-content Ed25519 signature.
-  //   - valid           → strongest anchor present; proceed.
-  //   - invalid / unknown-keyid → a present signature did not verify against a
-  //                       pinned npm key (or steers us to an unpinned key);
-  //                       this is the forged-metadata signal — refuse.
-  //   - absent / unverifiable   → registry supplied no signature (private or
-  //                       pre-signing registry); the SHA-512/SHA-1 gates above
-  //                       still applied, so warn-and-continue.
+  // Made with npm's registry private key, so it survives a forged metadata
+  // response; absent/unverifiable falls back to the hash gates above.
   const regSig = verifyNpmRegistrySignature(PKG_NAME, latestVersion, tarballIntegrity, registrySignatures);
   if (regSig.status === "invalid" || regSig.status === "unknown-keyid") {
     emit({
@@ -600,7 +457,6 @@ async function main() {
     progress(`note: npm registry signature ${regSig.status} (${regSig.reason || "no dist.signatures"}) — relying on transport-hash integrity only`, opts.json);
   }
 
-  // Extract.
   let tarBuf;
   try { tarBuf = zlib.gunzipSync(tgzBuf); }
   catch (e) { emit({ ok: false, error: `gunzip: ${e.message}` }, opts.json); process.exitCode = 4; return; }
@@ -616,9 +472,8 @@ async function main() {
     process.exitCode = 4; return;
   }
 
-  // Trust anchor = LOCAL public.pem. Compare it to the tarball's public.pem
-  // by fingerprint; if they differ, refuse the swap (key rotation requires
-  // a full `npm update -g` so the operator has explicit visibility).
+  // The trust anchor is the LOCAL public.pem; a differing tarball fingerprint is
+  // a rotation, which requires a full `npm update -g`.
   const localPubKeyPath = path.join(ROOT, "keys", "public.pem");
   let localPubKeyText, tarballPubKeyText;
   try { localPubKeyText = fs.readFileSync(localPubKeyPath, "utf8"); }
@@ -636,17 +491,8 @@ async function main() {
     process.exitCode = 5; return;
   }
 
-  // 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
-  // host AND the registry tarball passed every check — fingerprints match
-  // each other but match the attacker's key. The pin in EXPECTED_FINGERPRINT
-  // is the external trust anchor that closes this gap.
-  //
-  // Honors `KEYS_ROTATED=1` env to allow legitimate key rotation without
-  // re-bootstrap. Missing EXPECTED_FINGERPRINT file → warn-and-continue
-  // (don't break existing installs whose tree predates the pin file).
+  // local ↔ tarball agreement still passes for an attacker who swapped both, so
+  // keys/EXPECTED_FINGERPRINT is the external anchor. KEYS_ROTATED=1 bypasses it.
   const expectedFingerprintPath = path.join(ROOT, "keys", "EXPECTED_FINGERPRINT");
   if (fs.existsSync(expectedFingerprintPath) && process.env.KEYS_ROTATED === "1") {
     process.emitWarning(
@@ -656,20 +502,9 @@ async function main() {
     );
   }
   if (fs.existsSync(expectedFingerprintPath) && !process.env.KEYS_ROTATED) {
-    // 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. An inline split-trim-find would retain
-    // the BOM as part of the first line, which would never match a live
-    // fingerprint and would block every legitimate refresh-network run.
-    //
-    // Narrowed try/catch: only swallow ENOENT / EACCES from the loader
-    // call (the pin file may have been deleted between existsSync and
-    // read, or be unreadable by the current uid — both are "warn and
-    // continue" cases). Any OTHER error (loader bug, unexpected throw)
-    // must NOT silently fall through to an unpinned refresh — the prior
-    // catch-all flow was a fail-open vector. The emit({ok:false,...}) +
-    // exitCode + return block is now OUTSIDE the catch so a parsing
-    // failure cannot be silently swallowed.
+    // The shared loader tolerates a BOM-prefixed pin file; an inline split-trim
+    // keeps the BOM on the first line and blocks every legitimate run. Only
+    // ENOENT/EACCES is swallowed — any other error must refuse.
     let expectedFp;
     let loaderFailedSoftly = false;
     try {
@@ -677,8 +512,7 @@ async function main() {
       expectedFp = loadExpectedFingerprintFirstLine(expectedFingerprintPath);
     } catch (err) {
       if (err && (err.code === "ENOENT" || err.code === "EACCES")) {
-        // Pin file unreadable (race with deletion / permission denied) —
-        // warn-and-continue is the original behavior for this class.
+        // Pin file deleted under us, or not readable by this uid.
         loaderFailedSoftly = true;
       } else {
         emit({
@@ -691,12 +525,8 @@ async function main() {
       }
     }
     if (!loaderFailedSoftly) {
-      // Pin file present but the loader returned null. The loader refuses
-      // UTF-16LE / UTF-16BE pin files and any other shape that cannot be
-      // safely decoded. Treat this as a hard fail: the operator placed a
-      // pin file but the bytes are not consumable, so we must not fall
-      // through to an unpinned refresh. Re-save the pin as UTF-8 (with or
-      // without BOM) and retry.
+      // The loader returns null for a pin file it cannot decode; the operator
+      // placed a pin, so an unreadable one is a hard fail, not an unpinned refresh.
       if (expectedFp === null || expectedFp === undefined) {
         emit({
           ok: false,
@@ -706,13 +536,8 @@ async function main() {
         }, opts.json);
         process.exitCode = 5; return;
       }
-      // The pin file is canonically formatted as `SHA256:<base64>`, but
-      // `fingerprintPublicKey()` returns the raw base64 without the
-      // `SHA256:` prefix. Comparing the two raw strings would refuse every
-      // legitimate run unless KEYS_ROTATED=1 was set. Normalize by stripping
-      // the prefix from the pin file before compare. lib/verify.js's
-      // checkExpectedFingerprint() does the symmetric thing (adds the
-      // prefix to localFp); either side works as long as one is canonical.
+      // The pin file is canonically `SHA256:<base64>` while fingerprintPublicKey()
+      // returns bare base64, so the prefix comes off before the compare.
       const expectedFpBase64 = expectedFp.startsWith("SHA256:")
         ? expectedFp.slice("SHA256:".length)
         : expectedFp;
@@ -729,25 +554,14 @@ async function main() {
     }
   }
 
-  // Verify every signed entry in the tarball manifest using the local key.
   let tarballManifest;
   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; }
 
-  // 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.
+  // Authenticate the manifest envelope against the LOCAL public key before
+  // honoring any entry in it: per-skill signatures cover only skill body bytes,
+  // so paths and names around them could be re-shaped without breaking one. A
+  // missing signature refuses here rather than warning.
   const manifestSigResult = verifyTarballManifestSignature(tarballManifest, localPubKeyText);
   if (manifestSigResult.status !== "valid") {
     emit({
@@ -761,20 +575,9 @@ async function main() {
     process.exitCode = 5; return;
   }
 
-  // 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`
-  // and `verifiedCount === 0` and the swap proceeded with `ok: true`. Every
-  // operator running `exceptd refresh --network` installed unverified bytes.
-  //
-  // Fixed shape mirrors lib/verify.js: iterate `manifest.skills[]` by
-  // `name` + `path` + `signature`. Apply the same CRLF/BOM normalization
-  // before verify (lib/verify.js normalize() — duplicated here to keep
-  // this path free of cross-module runtime deps). validateSkillPath()
-  // is also mirrored to defend against path traversal in a tampered
-  // tarball manifest before we resolve the path against the extracted
-  // tree.
+  // `path` is the payload's forward-slash location in the tarball, never a name
+  // synthesized from the entry's id, and is validated before it resolves against
+  // the extracted tree, so a tampered manifest cannot traverse out of it.
   const localKeyObj = crypto.createPublicKey(localPubKeyText);
   const skills = Array.isArray(tarballManifest.skills) ? tarballManifest.skills : [];
   const failures = [];
@@ -817,21 +620,8 @@ async function main() {
     process.exitCode = 5; return;
   }
 
-  // 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). Their integrity
-  // anchors are: the SHA-512 SRI + SHA-1 shasum transport hashes (checked
-  // above; both-absent is refused), AND — when the registry supplies it — the
-  // npm registry ECDSA-P256 signature over `<pkg>@<version>:<integrity>`
-  // (verifyNpmRegistrySignature above), which authenticates the whole tarball
-  // against npm's pinned signing key and cannot be reproduced by a forged
-  // metadata response. `npm update -g` additionally honors dist.attestations
-  // (sigstore SLSA provenance), which this data-only path does not consume.
-  //
-  // Defense-in-depth: refuse the swap if the manifest skills list doesn't
-  // exactly match the skill payload entries present in the tarball. A
-  // malicious tarball that drops/adds a skill outside the manifest no
-  // longer slips through.
+  // A skill payload the manifest does not declare refuses the swap, so a
+  // tarball that adds one outside the manifest cannot slip past the loop above.
   const manifestSkillPaths = new Set(skills.map(s => validateManifestSkillPath(s.path)));
   const tarballSkillPayloads = entries
     .map(e => stripPkg(e.name))
@@ -860,12 +650,8 @@ async function main() {
     return;
   }
 
-  // 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
-  // in); then rename all new targets in; on failure, walk the backup dir
-  // in reverse and restore.
+  // Every old target moves into one backup dir before any new target moves in;
+  // a failure walks completedSteps in reverse to restore.
   const stageDir = fs.mkdtempSync(path.join(ROOT, ".refresh-network-"));
   let written = 0;
   let backupDir = null;
@@ -873,9 +659,7 @@ async function main() {
   try {
     for (const entry of entries) {
       const rel = stripPkg(entry.name);
-      // Scope: only data/, skills/, manifest.json, manifest-snapshot.json.
-      // Everything else (bin/, lib/, package.json, etc.) is left alone —
-      // --network is a DATA refresh, not a code refresh.
+      // A data refresh: bin/, lib/ and package.json are left alone.
       if (!(rel === "manifest.json" || rel === "manifest-snapshot.json" ||
             rel.startsWith("data/") || rel.startsWith("skills/"))) continue;
       const dst = path.join(stageDir, rel);
@@ -884,16 +668,13 @@ async function main() {
       written++;
     }
 
-    // v0.12.14: use PID + random suffix in the backup dir name
-    // so concurrent refresh-network invocations don't collide on the
-    // millisecond clock.
+    // PID plus random suffix: concurrent invocations collide on the ms clock alone.
     const backupSuffix = `${process.pid}-${crypto.randomBytes(4).toString("hex")}`;
     backupDir = path.join(ROOT, `.refresh-network-backup-${Date.now()}-${backupSuffix}`);
     fs.mkdirSync(backupDir);
     const replaceList = ["data", "skills", "manifest.json", "manifest-snapshot.json"];
 
-    // Phase A: move all existing targets to backupDir. After this loop
-    // completes, the install root has none of the replaced targets.
+    // Phase A: the install root holds none of the replaced targets after this.
     for (const target of replaceList) {
       const dst = path.join(ROOT, target);
       if (fs.existsSync(dst)) {
@@ -911,8 +692,7 @@ async function main() {
     }
 
     fs.rmSync(stageDir, { recursive: true, force: true });
-    // Best-effort cleanup of backup dir — keep on disk for one cycle so
-    // operators can manually roll back if something feels off.
+    // The backup dir stays on disk so an operator can roll back by hand.
     emit({
       ok: true,
       local_version: localVersion,
@@ -927,15 +707,12 @@ async function main() {
       message: `refreshed catalog from v${localVersion} → v${latestVersion} (${verifiedCount}/${skills.length} skill signatures verified, npm registry signature: ${regSig.status}). Backup at ${path.relative(ROOT, backupDir)} — safe to remove after verifying the new run.`,
     }, opts.json);
   } catch (e) {
-    // v0.12.14: walk completedSteps in reverse to undo partial work.
     const rollbackErrors = [];
     for (const step of [...completedSteps].reverse()) {
       try {
         if (step.kind === "install") {
-          // Remove the newly-installed copy.
           fs.rmSync(path.join(ROOT, step.target), { recursive: true, force: true });
         } else if (step.kind === "backup" && backupDir) {
-          // Restore from backup.
           const src = path.join(backupDir, step.target);
           const dst = path.join(ROOT, step.target);
           if (fs.existsSync(src)) fs.renameSync(src, dst);
@@ -969,19 +746,10 @@ if (require.main === module) {
 module.exports = {
   parseTar,
   fingerprintPublicKey,
-  // 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,
-  // Exported for in-process tests of the refresh path's manifest envelope
-  // check.
   verifyTarballManifestSignature,
   canonicalManifestBytesForRefresh,
-  // Exported for in-process tests of the tarball fetch-destination allowlist.
   isAllowedTarballHost,
-  // Exported for in-process tests of the npm registry signature verification
-  // over `<pkg>@<version>:<integrity>`.
   verifyNpmRegistrySignature,
   NPM_REGISTRY_KEYS,
 };