@whisper-security/whisper-mcp 0.242.0 → 0.250.0

package/README.md

@@ -47,11 +47,14 @@ investigation procedures).
 
 ## What this package does
 
-It resolves the `whisper` binary for your platform from the GitHub release tagged for
-this exact package version, checks it against the `.sha256` published beside it, caches it,
-and runs `whisper mcp`. The verified digest is recorded beside the binary and re-checked on
-every run, so a given version of this package always resolves to the same bytes and a cached
-copy that no longer matches the digest we recorded is never executed.
+It resolves the `whisper` binary for your platform from the GitHub release this package
+pins, checks it against the sha256 digest written into this package when it was published,
+caches it, and runs `whisper mcp`. An npm version cannot change, so a given version of this
+package always resolves to the same bytes: an asset replaced under the release tag later does
+not match the pin and is refused, never run. The verified digest is recorded beside the binary
+and re-checked on every run, so a cached copy that no longer matches it is never executed.
+
+`npx @whisper-security/whisper-mcp --version` prints this package's version and the CLI's.
 
 Already have the CLI (`brew install whisper-sec/tap/whisper`, `apt install whisper`,
 `scoop install whisper`)? Then `whisper mcp` is the same server and you do not need this

package/bin/whisper-mcp.js

@@ -12,10 +12,13 @@
  * which presents as "the server does not work" with nothing in any log. Every diagnostic
  * here goes to stderr, deliberately and without exception.
  *
- * TRUST. The binary is fetched from the GitHub release tagged for THIS package version and
- * checked against the `.sha256` published beside it, so a given version of this package
- * always resolves to the same bytes. The verified digest is recorded next to the binary and
- * re-checked on EVERY run, so a cached copy that no longer matches that digest is never run.
+ * TRUST. The binary is fetched from the GitHub release this package pins and checked against
+ * the sha256 digest written into this package's own package.json (`whisperCliDigests`) when
+ * it was published. An npm version is immutable, so a given version of this package always
+ * resolves to the same bytes, even if somebody later replaces an asset under the release tag:
+ * the replaced file does not match the pin and is refused. The `.sha256` published beside the
+ * asset is read only to explain a mismatch. The verified digest is recorded next to the binary
+ * and re-checked on EVERY run, so a cached copy that no longer matches it is never run.
  */
 
 const fs = require('fs');
@@ -33,6 +36,13 @@ const PKG = require('../package.json');
  */
 const CLI_VERSION = PKG.whisperCliVersion || PKG.version;
 const VERSION = CLI_VERSION;
+/*
+ * The per-asset digests of that release, pinned at publish time from its checksums.txt by
+ * pin-digests.js. A package without them (a local checkout, never a published one: the pack
+ * refuses it) falls back to the `.sha256` beside the asset, which proves the download arrived
+ * intact but not that the asset is the one that was released.
+ */
+const PINS = PKG.whisperCliDigests || null;
 const REPO = 'whisper-sec/whisper-cli';
 const BASE = `https://github.com/${REPO}/releases/download/v${CLI_VERSION}`;
 
@@ -67,6 +77,58 @@ const TARGETS = {
   'win32-arm64': 'whisper-windows-arm64.exe',
 };
 
+const HEX64 = /^[0-9a-f]{64}$/;
+
+/**
+ * The digest this package pins for an asset, or null when the package pins none. A package that
+ * pins digests but not THIS one, or pins something that is not a sha256, was packed wrong, and
+ * running an unpinned binary from it would be the exact hole the pins close, so that is fatal.
+ */
+function pinnedDigest(pins, asset) {
+  if (!pins) return null;
+  const d = typeof pins[asset] === 'string' ? pins[asset].toLowerCase() : '';
+  if (!HEX64.test(d)) {
+    die(
+      `this package pins no valid sha256 for ${asset}, so the download cannot be verified.`,
+      `  Nothing was executed. Please report this at https://github.com/${REPO}/issues`
+    );
+  }
+  return d;
+}
+
+/**
+ * Judge downloaded bytes against the pin. Returns null when they match, or the message and the
+ * hint to die with. `published` is the `.sha256` beside the asset, fetched only now, to say
+ * WHICH way it went wrong: a published checksum that names the bytes we got means the asset was
+ * replaced under the tag after this package was published; one that names the pin means the
+ * bytes were damaged or substituted on the way here.
+ */
+function judgePinned(got, pinned, published) {
+  if (got === pinned) return null;
+  let why;
+  if (published === got) {
+    why =
+      `  The release now publishes a checksum for these new bytes, so the asset was REPLACED\n` +
+      `  after this package version was published. This package will only run the bytes it pins.`;
+  } else if (published === pinned) {
+    why = `  The release still publishes the pinned digest, so the download was damaged or substituted on the way.`;
+  } else {
+    why = `  The checksum published beside the asset matches neither.`;
+  }
+  return [
+    'CHECKSUM MISMATCH - refusing to run the downloaded binary.',
+    `  pinned by this package  ${pinned}\n  downloaded             ${got}\n` +
+      (published ? `  published beside it    ${published}\n` : '') +
+      `${why}\n  Nothing was executed. Please report this at https://github.com/${REPO}/issues`,
+  ];
+}
+
+/** The first field of a "<hex>  <name>" checksum file, lowercased; '' when it is not a digest. */
+function parseSum(txt) {
+  const d = String(txt).trim().split(/\s+/)[0].toLowerCase();
+  return HEX64.test(d) ? d : '';
+}
+
 function assetName() {
   const key = `${process.platform}-${process.arch}`;
   const asset = TARGETS[key];
@@ -131,9 +193,11 @@ async function ensureBinary() {
   // execution inside a process holding WHISPER_API_KEY in its environment. On a laptop that
   // path is private; under a shared XDG_CACHE_HOME or on CI it is not, and the check costs
   // about a tenth of a second.
+  const pinned = pinnedDigest(PINS, asset);
   if (fs.existsSync(exe) && fs.existsSync(stamp)) {
     const recorded = fs.readFileSync(stamp, 'utf8').trim().slice(0, 64);
-    if (/^[0-9a-f]{64}$/.test(recorded) && sha256(fs.readFileSync(exe)) === recorded) {
+    // With a pin, the cached copy must be the pinned bytes, not merely the bytes recorded.
+    if (HEX64.test(recorded) && (!pinned || recorded === pinned) && sha256(fs.readFileSync(exe)) === recorded) {
       return exe;
     }
     note('the cached binary no longer matches its recorded digest; fetching a clean copy');
@@ -149,23 +213,32 @@ async function ensureBinary() {
   }
 
   note(`fetching the Whisper CLI ${VERSION} for ${process.platform}-${process.arch} (first run only)`);
-  const [bin, sumTxt] = await Promise.all([
-    fetchOrDie(`${BASE}/${asset}`, 'the binary'),
-    fetchOrDie(`${BASE}/${asset}.sha256`, 'its checksum'),
-  ]);
-
-  // "<hex>  <name>" - take the first field and nothing else.
-  const want = String(sumTxt).trim().split(/\s+/)[0].toLowerCase();
+  const bin = await fetchOrDie(`${BASE}/${asset}`, 'the binary');
   const got = sha256(bin);
-  if (!/^[0-9a-f]{64}$/.test(want)) {
-    die('the published checksum is not a sha256 digest, so the download cannot be verified.');
-  }
-  if (got !== want) {
-    die(
-      'CHECKSUM MISMATCH - refusing to run the downloaded binary.',
-      `  expected ${want}\n  got      ${got}\n` +
-        `  Nothing was executed. Please report this at https://github.com/${REPO}/issues`
-    );
+  if (pinned) {
+    if (got !== pinned) {
+      // Best effort: the explanation must never mask the refusal, so a failed fetch is ''.
+      let published = '';
+      try {
+        const res = await fetch(`${BASE}/${asset}.sha256`, { redirect: 'follow', signal: AbortSignal.timeout(20_000) });
+        if (res.ok) published = parseSum(await res.text());
+      } catch (_) {
+        published = '';
+      }
+      die(...judgePinned(got, pinned, published));
+    }
+  } else {
+    const want = parseSum(await fetchOrDie(`${BASE}/${asset}.sha256`, 'its checksum'));
+    if (!want) {
+      die('the published checksum is not a sha256 digest, so the download cannot be verified.');
+    }
+    if (got !== want) {
+      die(
+        'CHECKSUM MISMATCH - refusing to run the downloaded binary.',
+        `  expected ${want}\n  got      ${got}\n` +
+          `  Nothing was executed. Please report this at https://github.com/${REPO}/issues`
+      );
+    }
   }
 
   // 0o700 on the directory too, not just the file: a group-writable cache directory hands the
@@ -181,11 +254,26 @@ async function ensureBinary() {
   return exe;
 }
 
+/**
+ * The CLI arguments for what the caller typed. The server is the default, so everything is
+ * passed to `whisper mcp`, with one exception: `--version` asks which CLI this package runs,
+ * and `whisper mcp --version` is an unknown flag (#1624). That one goes straight to the CLI.
+ * `--help` keeps the prefix on purpose: `whisper mcp --help` is the help for the server, which
+ * is what someone running whisper-mcp is asking for.
+ */
+function cliArgs(argv) {
+  if (argv.length === 1 && argv[0] === '--version') return ['--version'];
+  return ['mcp', ...argv];
+}
+
 async function main() {
+  const argv = process.argv.slice(2);
+  const args = cliArgs(argv);
+  if (args[0] === '--version') {
+    // Not the MCP stream, so stdout is right here: this is what a person or a script reads.
+    process.stdout.write(`whisper-mcp ${PKG.version} (runs the Whisper CLI ${CLI_VERSION})\n`);
+  }
   const exe = await ensureBinary();
-  // Default to the MCP server; anything the caller passes is appended, so
-  // `npx @whisper-security/whisper-mcp --help` and the bare form both do the right thing.
-  const args = ['mcp', ...process.argv.slice(2)];
 
   const child = spawn(exe, args, { stdio: 'inherit', env: process.env });
 
@@ -211,4 +299,9 @@ async function main() {
   });
 }
 
-main().catch((e) => die(e && e.stack ? e.stack : String(e)));
+// Required as a module (by pin-digests.js and the tests) it only exports; run, it runs.
+if (require.main === module) {
+  main().catch((e) => die(e && e.stack ? e.stack : String(e)));
+} else {
+  module.exports = { TARGETS, HEX64, cliArgs, judgePinned, parseSum, pinnedDigest };
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@whisper-security/whisper-mcp",
-  "version": "0.242.0",
+  "version": "0.250.0",
   "mcpName": "io.github.whisper-sec/whisper",
-  "whisperCliVersion": "0.242.0",
+  "whisperCliVersion": "0.250.0",
   "description": "Give an AI agent a real, routable IPv6 identity, verifiable egress and DNS policy. Keyless: verify any agent's identity and query the infrastructure graph. With a key: register, govern and route agents.",
   "keywords": [
     "mcp",
@@ -31,6 +31,10 @@
   "bin": {
     "whisper-mcp": "bin/whisper-mcp.js"
   },
+  "scripts": {
+    "prepack": "node pin-digests.js --check",
+    "test": "node --test test/wrapper.test.js"
+  },
   "files": [
     "bin/whisper-mcp.js",
     "README.md",
@@ -41,5 +45,18 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "whisperCliDigests": {
+    "whisper-darwin-amd64": "29a5464ca9ffe17be34daf21434a8b39200ed3401af77acb85c3d5c08eb21daf",
+    "whisper-darwin-arm64": "8d4f47d562b7cfb0ce42609f91da423e9f9444ce5153c65ecb48067aaae20801",
+    "whisper-linux-386": "f260dd1ff1faee7829da9e390309909ede0345c1daea113dbff5a54d7ba55a30",
+    "whisper-linux-amd64": "48e408205f5001eeb852b66cea57401a829839fcd079d0df6545891b626f72d4",
+    "whisper-linux-arm": "452dd96e0812d1e9daacaf5abe361d51694253d91a3bc4d968246b6a2d38c4ca",
+    "whisper-linux-arm64": "b6e211c490a918885787e5a49e0439c2aea3fb941d38974568fe6af356851d04",
+    "whisper-linux-mips": "bca68da0f87f81ad966076b86754409ee8b9c1991e0ec73ffee83affb3412877",
+    "whisper-linux-mipsle": "9d84c297d783e506dcc56db5f6f3cf7e291d331cf1dd195a53c466c418c69cc8",
+    "whisper-linux-riscv64": "8dd1194b6536f17d4fa8e1252d0082996a491dffbd060f6a8b984afbfddc3133",
+    "whisper-windows-amd64.exe": "a94dbd418ce90ac643f64288ba0b384d3780bdc718c1c9592d13dd6ae70bf130",
+    "whisper-windows-arm64.exe": "450ae61200d9cfe78b7dddd45424373bb3a4317a7fe830d6c8e74f777c154da0"
   }
 }