kodelyth-ecc 2.23.2 → 2.24.1

package/CHANGELOG.md

@@ -2,6 +2,107 @@
 
 All notable changes to Kodelyth ECC are documented here.
 
+## v2.24.1 — verify Windows downloads before running them (October 2026)
+
+**Security fix.** The Windows installer added in 2.23.0 downloaded a release zip
+over HTTPS and extracted it straight into the user's PATH directory **with no
+integrity check at all**.
+
+This repository ships a `supply-chain-auditor` agent whose entire job is catching
+"downloads and executes a binary without verifying it". The code doing it was
+ours. Both upstream projects publish a `checksums.txt` in the same release, in
+standard `sha256sum` format, and nothing was reading it.
+
+### What it does now
+
+Fetches `checksums.txt` from the release, finds the line for the asset it just
+downloaded, hashes the file with Node's `crypto`, and compares.
+
+- **Mismatch is fatal.** It refuses to install and reports both hashes.
+- **Missing or unlisted warns and proceeds.** The fetch is HTTPS from
+  github.com so transport tampering is already hard, and a release that stops
+  publishing checksums should not make ECC look broken. The case this control
+  exists for is a mismatch, and that stays fatal.
+
+Hashing uses Node's `crypto` rather than shelling out, because `certutil`,
+`sha256sum` and `shasum` differ in availability and output format across the
+machines this has to run on.
+
+### Proven, not asserted
+
+Checked against the real artifact before a single test was written: the genuine
+RTK Windows asset hashes to its published sha256, and flipping one byte produces
+a mismatch.
+
+Nine tests cover a matching checksum, a single changed byte, an unlisted asset,
+a malformed entry, picking the right line out of a full file, uppercase hex, and
+that a filename merely *ending* with the asset name does not satisfy the lookup
+(`evil-asset.zip` must not pass as `asset.zip`).
+
+The Windows CI job asserts the gate is exercised on every push — a security
+control nobody runs is decoration. From a real `windows-latest` runner:
+
+```
+[win] checksum verified (sha256 1623e9b45d28…)
+```
+
+**656 tests across 43 files.**
+
+## v2.24.0 — the update notice now tells you why (October 2026)
+
+The CLI has always polled npm for new versions and cached the answer for 24
+hours. That monthly touchpoint was spent on almost nothing: the result surfaced
+only in the interactive menu, as a version number and an install command.
+
+```
+Update to v2.23.2
+npm i -g kodelyth-ecc  (installs new version)
+```
+
+A version number is a nag. It states a fact and gives no reason to act on it.
+
+### It now links what changed
+
+```
+Update to v2.24.0
+what changed: github.com/sifxprime/kodelyth-ecc/releases/tag/v2.24.0
+```
+
+`check()` returns a `releaseNotes` URL alongside the version, so every consumer
+gets it without doing its own string building.
+
+### doctor surfaces it too
+
+A second natural touchpoint — `doctor` is run deliberately, usually when
+somebody is already paying attention:
+
+```
+! version — v2.23.2 installed, v2.24.0 available
+    → npm i -g kodelyth-ecc    what changed: .../releases/tag/v2.24.0
+```
+
+### Cache-only, on purpose
+
+The new `cachedCheck()` reads the 24-hour cache and never touches the network.
+`doctor` is the command people reach for when something is **already** wrong, so
+it must not wait on the registry — and an unreachable npm is not a fact about
+the health of your install. A cold or stale cache yields nothing and the row is
+simply absent, rather than reported as a warning. A check that fires on "I could
+not reach the network" teaches people to ignore the output.
+
+`run()` stays synchronous and takes the result as a parameter, so it remains
+testable and `doctor` adds no latency.
+
+Verified across every state: a newer version warns with the link, being current
+passes, a stale cache is ignored, a corrupt cache leaves `doctor` working on its
+11 checks, and a cold cache omits the row.
+
+### What this does not do
+
+No nagging on every command. Nothing auto-updates. Nothing blocks.
+
+**647 tests passing.**
+
 ## v2.23.2 — the README leads with the product, not the badges (October 2026)
 
 No change to the toolkit. The README **is** the npm landing page, and npm only

package/CLAUDE.md

@@ -26,7 +26,7 @@ scripts/     → Node.js utilities: MCP server, dashboard, swarm, replay, router
 bundles/     → 3 power bundles (indie-hacker, red-team, enterprise)
 actions/     → GitHub Action (CI/CD integration for PR review)
 docs/        → Feature docs (arena.md, mcp.md, dashboard.md, swarm.md, replay.md, evolve.md, supply-chain.md)
-tests/       → 647 passing tests across 42 test files
+tests/       → 656 passing tests across 43 test files
 ```
 
 ## Running Tests

package/README.md

@@ -44,7 +44,7 @@ Google Antigravity, OpenCode, Cline, Roo Code, Aider, Kimi and Gemini CLI.
 [![npm downloads](https://img.shields.io/npm/dm/kodelyth-ecc.svg)](https://www.npmjs.com/package/kodelyth-ecc)
 [![GitHub Stars](https://img.shields.io/github/stars/sifxprime/kodelyth-ecc?style=social)](https://github.com/sifxprime/kodelyth-ecc/stargazers)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-![Tests](https://img.shields.io/badge/tests-647%20passing-brightgreen)
+![Tests](https://img.shields.io/badge/tests-656%20passing-brightgreen)
 ![Claude Code](https://img.shields.io/badge/Claude%20Code-Ready-8A2BE2)
 ![Windsurf](https://img.shields.io/badge/Windsurf-Ready-06b6d4)
 ![Antigravity](https://img.shields.io/badge/Antigravity-Ready-00ADD8)
@@ -118,7 +118,7 @@ Most "AI agent kits" are folders of markdown files you have to remember the name
 | Quality hooks | ✅ 44 | Some | ❌ | ❌ |
 | IDE platforms | **11** (Claude Code, Windsurf, Cursor, Codex, Antigravity, OpenCode, Cline, Roo Code, Aider, Kimi, Gemini CLI) | 1-2 | 1 | Varies |
 | Telemetry | ❌ none | Varies | ❌ | Varies |
-| Test coverage | ✅ 647 tests | ❌ | ❌ | ❌ |
+| Test coverage | ✅ 656 tests | ❌ | ❌ | ❌ |
 | Distributed via | `npx`, curl, clone | Manual | Manual | Manual |
 
 ---

package/VERSION

@@ -1 +1 @@
-2.23.2
+2.24.1

package/bin/kodelyth-ecc.js

@@ -707,7 +707,23 @@ if (args[0] === 'god' || args[0] === 'evil' || args[0] === 'arena') {
 
 if (args[0] === 'doctor') {
   const { run, PASS, WARN, FAIL } = require(path.join(ROOT, 'scripts', 'doctor-health.js'));
-  const report = run();
+
+  // Cache-only, deliberately. doctor is what people run when something is
+  // already wrong, so it must not wait on the registry — and an unreachable npm
+  // is not a fact about the health of their install. The cache is warmed by the
+  // interactive menu; a cold one yields null and the version row is simply
+  // absent.
+  let update;
+  try {
+    const { cachedCheck } = require(path.join(ROOT, 'scripts', 'cli', 'update-check.js'));
+    const vf = path.join(ROOT, 'VERSION');
+    const current = fs.existsSync(vf)
+      ? fs.readFileSync(vf, 'utf8').trim()
+      : require(path.join(ROOT, 'package.json')).version;
+    update = cachedCheck(current) || undefined;
+  } catch { /* never let a version hint break the health check */ }
+
+  const report = run({ update });
   if (args.includes('--json')) {
     process.stdout.write(JSON.stringify(report, null, 2) + '\n');
     process.exit(report.summary.fail > 0 ? 1 : 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kodelyth-ecc",
-  "version": "2.23.2",
+  "version": "2.24.1",
   "description": "Production-grade AI coding toolkit — 70 agents (incl. devil-mode adversarial crew), 196 skills, 103 commands, parallel multi-agent commands, semantic intent routing, self-learning memory, and a built-in MCP server (16 tools / 6 prompts / 377 resources) that bridges to Claude Desktop, LangGraph, AutoGen, CrewAI, and OpenAI Agents SDK. Works on macOS, Linux and Windows with Claude Code, Windsurf, Cursor, Codex, Antigravity, OpenCode, Cline, RooCode, Aider, Kimi, and Gemini CLI.",
   "author": "Kodelyth <github.com/sifxprime>",
   "license": "MIT",

package/scripts/cli/menu.js

@@ -47,7 +47,9 @@ async function buildOptions({ ROOT }) {
   if (update.updateAvailable) {
     opts.push({
       label: `Update to v${update.latest}`,
-      hint:  'npm i -g kodelyth-ecc  (installs new version)',
+      // Say what it is AND where to read what changed. A version number alone
+      // is a nag; a reason is an invitation.
+      hint:  `what changed: ${update.releaseNotes || 'github.com/sifxprime/kodelyth-ecc/releases'}`,
       run:   () => runUpdate(),
       badge: 'NEW',
     });

package/scripts/cli/update-check.js

@@ -54,7 +54,19 @@ function cmpVersion(a, b) {
   return 0;
 }
 
-// Public: returns { current, latest, updateAvailable, cached } or nulls on failure.
+/**
+ * Where to read what actually changed in a given version.
+ *
+ * "update available: v2.23.2" is a nag — it tells you a number and no reason.
+ * A link to the release notes turns the same notice into something worth acting
+ * on, which is the whole point of owning a monthly touchpoint.
+ */
+function releaseNotesUrl(version) {
+  if (!version) return null;
+  return `https://github.com/sifxprime/kodelyth-ecc/releases/tag/v${version}`;
+}
+
+// Public: returns { current, latest, updateAvailable, cached, releaseNotes } or nulls on failure.
 async function check({ current, force = false } = {}) {
   if (!force) {
     const c = readCache();
@@ -63,6 +75,7 @@ async function check({ current, force = false } = {}) {
         current, latest: c.latest,
         updateAvailable: c.latest && cmpVersion(c.latest, current) > 0,
         cached: true,
+        releaseNotes: releaseNotesUrl(c.latest),
       };
     }
   }
@@ -72,7 +85,30 @@ async function check({ current, force = false } = {}) {
     current, latest,
     updateAvailable: !!(latest && cmpVersion(latest, current) > 0),
     cached: false,
+    releaseNotes: releaseNotesUrl(latest),
+  };
+}
+
+/**
+ * Cache-only read. No network, no promise, no timeout — safe to call from a
+ * synchronous command.
+ *
+ * doctor uses this rather than check(): it is the command people run when
+ * something is already wrong, so it must never wait on the registry. The cache
+ * is warmed by the interactive menu, which does hit the network. A cold cache
+ * simply yields null and the version row does not appear, which is correct —
+ * "I could not reach npm" is not a fact about the health of your install.
+ */
+function cachedCheck(current) {
+  const c = readCache();
+  if (!c || !c.latest) return null;
+  return {
+    current,
+    latest: c.latest,
+    updateAvailable: cmpVersion(c.latest, current) > 0,
+    cached: true,
+    releaseNotes: releaseNotesUrl(c.latest),
   };
 }
 
-module.exports = { check, cmpVersion };
+module.exports = { check, cachedCheck, cmpVersion, releaseNotesUrl };

package/scripts/doctor-health.js

@@ -155,7 +155,29 @@ function checkCodebaseGraph() {
 
 // ── Runner ───────────────────────────────────────────────────────────────────
 
-function run() {
+/**
+ * Whether the installed version is current.
+ *
+ * Takes a pre-fetched result rather than doing its own network call, so run()
+ * stays synchronous and testable, and doctor never blocks on the registry. When
+ * nothing was fetched — offline, timed out, caller did not bother — this is
+ * silently absent rather than a warning. "Could not reach npm" is not a health
+ * problem with the user's install, and reporting it as one trains people to
+ * ignore the output.
+ */
+function checkVersion(update) {
+  if (!update || !update.latest) return null;
+  if (!update.updateAvailable) {
+    return { status: PASS, detail: `v${update.current} is the latest` };
+  }
+  return {
+    status: WARN,
+    detail: `v${update.current} installed, v${update.latest} available`,
+    fix: `npm i -g kodelyth-ecc    what changed: ${update.releaseNotes || 'github.com/sifxprime/kodelyth-ecc/releases'}`,
+  };
+}
+
+function run({ update } = {}) {
   const checks = [
     check('binaries',            checkBinaries),
     check('install-target',      checkInstallTarget),
@@ -169,6 +191,11 @@ function run() {
     check('terse',               checkTerse),
     check('codebase-graph',      checkCodebaseGraph),
   ];
+
+  // Appended rather than inlined: it is the only check that depends on the
+  // network, and it drops out entirely when no result was supplied.
+  const version = checkVersion(update);
+  if (version) checks.push({ id: 'version', ...version });
   const summary = {
     total: checks.length,
     pass: checks.filter(c => c.status === PASS).length,
@@ -178,4 +205,4 @@ function run() {
   return { checks, summary };
 }
 
-module.exports = { run, PASS, WARN, FAIL };
+module.exports = { run, checkVersion, PASS, WARN, FAIL };

package/scripts/lib/win-install.js

@@ -26,6 +26,7 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const crypto = require('crypto');
 const { execFileSync, spawnSync } = require('child_process');
 
 /** Where ECC puts binaries it installs on Windows. User-writable, no admin. */
@@ -81,6 +82,29 @@ function installFromRelease({ repo, asset, binName, log = () => {} }) {
       return { installed: false, reason: `downloaded file is empty — ${url}` };
     }
 
+    // Verify the download before extracting, let alone running it.
+    //
+    // ECC ships a supply-chain-auditor agent whose whole job is catching
+    // "downloads and executes a binary with no integrity check" — and the first
+    // version of this file did exactly that. Both projects publish a
+    // checksums.txt in the same release, so there is no excuse.
+    const verdict = verifyChecksum({ repo, asset, file: zip, log });
+    if (verdict.status === 'mismatch') {
+      return {
+        installed: false,
+        reason: `checksum mismatch for ${asset} — expected ${verdict.expected}, got ${verdict.actual}. Refusing to install.`,
+      };
+    }
+    if (verdict.status === 'unavailable') {
+      // Warn rather than fail. The fetch is HTTPS from github.com, so transport
+      // tampering is already hard, and a release that simply stops publishing
+      // checksums should not make ECC look broken. A MISMATCH is still fatal —
+      // that is the case this check exists for.
+      log(`[win] WARNING: no checksum available for ${asset} (${verdict.reason}) — proceeding on HTTPS alone`);
+    } else {
+      log(`[win] checksum verified (sha256 ${verdict.expected.slice(0, 12)}…)`);
+    }
+
     log('[win] extracting…');
     const ex = spawnSync('tar', ['-xf', zip, '-C', dir], { stdio: 'inherit' });
     if (ex.status !== 0) {
@@ -154,4 +178,42 @@ function setxHint(dir) {
   return `setx PATH "%PATH%;${dir}"`;
 }
 
-module.exports = { installFromRelease, installDir, isOnUserPath, setxHint, findBinary };
+
+/**
+ * Check a downloaded asset against the release's checksums.txt.
+ *
+ * Both upstreams publish the standard sha256sum format:
+ *   <64 hex>  <filename>
+ *
+ * Returns { status: 'ok' | 'mismatch' | 'unavailable' }. Hashing is done with
+ * Node's crypto rather than shelling out, because certutil, sha256sum and
+ * shasum all differ in availability and output format across the machines this
+ * has to run on.
+ */
+function verifyChecksum({ repo, asset, file, log = () => {}, checksumText }) {
+  // checksumText is injectable so the parsing and comparison can be tested
+  // without reaching the network. Production callers never pass it.
+  let text = checksumText;
+  if (text === undefined) {
+    const url = `https://github.com/${repo}/releases/latest/download/checksums.txt`;
+    try {
+      text = execFileSync('curl', ['-fsSL', url], { encoding: 'utf8', timeout: 20000 });
+    } catch {
+      return { status: 'unavailable', reason: 'checksums.txt could not be fetched' };
+    }
+  }
+
+  const line = text.split('\n').find((l) => l.trim().endsWith(` ${asset}`) || l.trim().endsWith(`  ${asset}`));
+  if (!line) return { status: 'unavailable', reason: `${asset} not listed in checksums.txt` };
+
+  const expected = (line.trim().split(/\s+/)[0] || '').toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(expected)) {
+    return { status: 'unavailable', reason: 'malformed checksum entry' };
+  }
+
+  const actual = crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+  if (actual !== expected) return { status: 'mismatch', expected, actual };
+  return { status: 'ok', expected };
+}
+
+module.exports = { installFromRelease, installDir, isOnUserPath, setxHint, findBinary, verifyChecksum };