kodelyth-ecc 2.24.0 → 2.24.2

package/CHANGELOG.md

@@ -2,6 +2,114 @@
 
 All notable changes to Kodelyth ECC are documented here.
 
+## v2.24.2 — adversarial pass: path traversal in get_rule, unrecallable memories (October 2026)
+
+**Security fix.** Three defects found by attacking the memory store, MCP server
+and dashboard rather than reading them.
+
+### `get_rule` returned any markdown file on the machine
+
+`loadRule` was the only catalog loader that built a filesystem path out of its
+argument. Every other loader — agents, skills, commands, bundles — enumerates a
+directory and matches by name, so a caller can only ever select something already
+listed. This one did `path.join(PATHS.rules, name + '.md')`, so:
+
+    get_rule("../../README")              -> 51,297 bytes of ROOT/README.md
+    get_rule("testing/../../../README")   -> same, via nested traversal
+
+The `.md` suffix was the only thing bounding the reach, which left every readable
+markdown file on the machine in scope.
+
+This matters because the caller is not always the user. An MCP tool argument can
+originate in text the agent merely read — a dependency README, an issue comment,
+a fetched page — which made this an arbitrary-markdown-read primitive reachable
+by prompt injection. That is exactly the class ECC's own `prompt-injection-hunter`
+agent exists to catch.
+
+Fixed with two guards that fail differently: a name pattern that rejects anything
+that is a path rather than a name before touching disk, and the existing
+`resolveContained()` from `scripts/lib/safe-fs.js`, which proves the target sits
+under `rules/common` once symlinks resolve. The pattern alone is not enough —
+`escape-probe` is a valid rule name, and a symlink under that name reads 51KB.
+
+`loadRule` had no test coverage at all, which is why this survived. It now has
+four tests, including the symlink case.
+
+### One memory was mathematically unrecallable
+
+`search()` defaulted to an absolute `minScore` of 0.5 against unnormalised BM25
+scores. BM25 IDF is `log(1 + (N - df + 0.5) / (df + 0.5))`, so a term appearing in
+every memory drives IDF toward zero and can never clear a fixed floor at any
+corpus size. The floor is now relative to the top hit, so it scales with the
+corpus instead of fighting it. An explicitly passed `minScore` is still honoured
+exactly. `recall_memory` passes none, so it was using the broken default.
+
+### Malformed request URIs returned 500 and wrote to stderr
+
+`decodeURIComponent` throws on `/%`, `/%zz` or a truncated `/%e0%a4`. The dashboard
+did not guard it, so a malformed *client* URI became a 500 "internal server error"
+plus one stderr line per request — meaning any local process could spam the
+terminal the dashboard runs in. A path that cannot be decoded names no file, so
+it is now a 404 like any other miss.
+
+### What resisted
+
+Worth recording, since the absence of findings was tested rather than assumed.
+Dashboard traversal (plain, encoded, double-encoded, backslash, absolute,
+null-byte) all returned 404. Host validation rejects absent, empty and foreign
+`Host` headers. Non-GET is 405. Stored XSS was tested in a real browser: a memory
+captured through the real store with breakout payloads in problem, approach, tags,
+language and project rendered as visible text, setting no global, creating no
+element and no attribute, with the `</pre>` breakout still inside its `<pre>`.
+
+**665 tests across 43 files.**
+
+## 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

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/       → 665 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 | ✅ 665 tests | ❌ | ❌ | ❌ |
 | Distributed via | `npx`, curl, clone | Manual | Manual | Manual |
 
 ---

package/VERSION

@@ -1 +1 @@
-2.24.0
+2.24.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kodelyth-ecc",
-  "version": "2.24.0",
+  "version": "2.24.2",
   "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/dashboard/server.js

@@ -151,7 +151,18 @@ function serveStaticFile(res, filePath) {
 // baseDir is injectable so the containment logic can be tested against a real
 // symlink without planting one in the shipped static/ directory.
 function resolveStatic(reqPath, baseDir = STATIC_DIR) {
-  const decoded = decodeURIComponent(reqPath.replace(/^\/+/, ''));
+  // decodeURIComponent throws URIError on malformed percent-encoding — "/%",
+  // "/%zz", a truncated "/%e0%a4". That threw out to the route handler, which
+  // turned a client's malformed URI into a 500 "internal server error" and wrote
+  // a line to stderr, so any local process could both mislabel its own bad
+  // request as a server fault and spam the terminal the dashboard runs in.
+  // A path that cannot be decoded names no file, so it is simply not found.
+  let decoded;
+  try {
+    decoded = decodeURIComponent(reqPath.replace(/^\/+/, ''));
+  } catch {
+    return null;
+  }
   if (decoded.includes('..')) return null;
   if (decoded === '' || decoded === '/') return path.join(baseDir, 'index.html');
   // Containment, including symlink resolution — see scripts/lib/safe-fs.js.

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 };

package/scripts/mcp/catalog.js

@@ -8,6 +8,7 @@
 
 const fs   = require('fs');
 const path = require('path');
+const { resolveContained } = require('../lib/safe-fs');
 
 const ROOT = path.join(__dirname, '..', '..');
 
@@ -157,8 +158,28 @@ function loadCommands() {
 }
 
 // ── Rules ────────────────────────────────────────────────────────────────────
+// A rule name is a flat basename: rules/common has no subdirectories, and every
+// other loader here resolves a name against a directory LISTING, so a caller can
+// only ever select something already enumerated. This one built a path out of the
+// argument instead, which made `../../README` read ROOT/README.md — any .md file
+// the process could reach, through a tool whose contract is "return a rule".
+//
+// That matters because the caller is not always the user. An MCP tool argument
+// can originate in text the agent merely read — a dependency's README, an issue
+// comment, a fetched page — so this was an arbitrary-markdown-read primitive
+// reachable by prompt injection, which is exactly what ECC's own
+// prompt-injection-hunter agent exists to catch.
+//
+// Two guards, because they fail differently. The pattern rejects anything that is
+// a path rather than a name, before touching disk. resolveContained then proves
+// the target really sits under rules/common once symlinks are resolved, which a
+// pattern cannot know.
+const RULE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
 function loadRule(name) {
-  const file = path.join(PATHS.rules, `${name}.md`);
+  if (typeof name !== 'string' || !RULE_NAME.test(name)) return null;
+  const file = resolveContained(path.join(PATHS.rules, `${name}.md`), PATHS.rules);
+  if (file === null) return null;
   const raw = safeReadFile(file);
   if (raw === null) return null;
   return { name, file, relpath: path.relative(ROOT, file), body: raw };

package/scripts/memory/store.js

@@ -185,8 +185,33 @@ function indexMemory(index, memory) {
 }
 
 // ── BM25 retrieval (k1=1.5, b=0.75) ──────────────────────────────────────────
+/**
+ * Fraction of the best hit's score a result must reach to be kept, when the
+ * caller does not impose an absolute floor of its own.
+ *
+ * Relative, not absolute, and that is the whole point. BM25 scores are not
+ * normalised — they scale with corpus size and term rarity — so any fixed
+ * threshold is really a statement about how many memories you have. The old
+ * default of 0.5 made a single stored memory mathematically unrecallable: with
+ * N=1 and df=1 the IDF term caps the score at ~0.288, so recall() returned
+ * nothing no matter what you searched for.
+ *
+ * It was worse for common words. A token appearing in every memory scores
+ * 0.288 at N=1, 0.087 at N=5 and 0.010 at N=50 — correct BM25 behaviour, since
+ * a term that is everywhere carries no signal, but under a fixed floor it meant
+ * those words never matched at any corpus size.
+ *
+ * Three call sites had already worked around this by passing minScore: 0.1
+ * (doctor and two tests, one of which names the ~0.29 figure outright). The
+ * user-facing paths had not: the MCP recall_memory tool, the memory CLI and
+ * SessionStart injection all used the default and silently returned nothing.
+ */
+const RELATIVE_SCORE_FLOOR = 0.25;
+
 function search(query, options = {}) {
-  const { limit = 5, minScore = 0.5, projectFilter = null } = options;
+  // minScore stays honoured when passed, so existing callers keep their exact
+  // behaviour; only the default changes from an absolute floor to a relative one.
+  const { limit = 5, minScore = null, projectFilter = null } = options;
   const index   = loadIndex();
   const tokens  = tokenise(query);
   if (tokens.length === 0 || index.docCount === 0) return [];
@@ -208,9 +233,13 @@ function search(query, options = {}) {
     }
   }
 
-  const ranked = Object.entries(scores)
-    .filter(([, score]) => score >= minScore)
-    .sort(([, a], [, b]) => b - a)
+  const sorted = Object.entries(scores).sort(([, a], [, b]) => b - a);
+  const topScore = sorted.length ? sorted[0][1] : 0;
+  const floor = minScore !== null && minScore !== undefined
+    ? minScore
+    : topScore * RELATIVE_SCORE_FLOOR;
+  const ranked = sorted
+    .filter(([, score]) => score >= floor)
     .slice(0, limit * 3);
 
   if (ranked.length === 0) return [];