Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix(crusher): switch compression_store cache key from MD5 to SHA-256 (CodeQL #395)

chopratejasaf9e6282f89f
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 2b88649d8..1e91d756c 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -5,14 +5,14 @@
},
"metadata": {
"description": "Headroom marketplace for Claude Code and GitHub Copilot CLI plugins.",
- "version": "0.20.16"
+ "version": "0.20.28"
},
"plugins": [
{
"name": "headroom",
"source": "./plugins/headroom-agent-hooks",
"description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.",
- "version": "0.20.16",
+ "version": "0.20.28",
"author": {
"name": "Headroom Contributors",
"url": "https://github.com/chopratejas/headroom"
diff --git a/.github/plugin/marketplace.json b/.github/plugin/marketplace.json
index 2b88649d8..1e91d756c 100644
--- a/.github/plugin/marketplace.json
+++ b/.github/plugin/marketplace.json
@@ -5,14 +5,14 @@
},
"metadata": {
"description": "Headroom marketplace for Claude Code and GitHub Copilot CLI plugins.",
- "version": "0.20.16"
+ "version": "0.20.28"
},
"plugins": [
{
"name": "headroom",
"source": "./plugins/headroom-agent-hooks",
"description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.",
- "version": "0.20.16",
+ "version": "0.20.28",
"author": {
"name": "Headroom Contributors",
"url": "https://github.com/chopratejas/headroom"
diff --git a/headroom/cache/compression_store.py b/headroom/cache/compression_store.py
index 4ab29ea70..810d1a07c 100644
--- a/headroom/cache/compression_store.py
+++ b/headroom/cache/compression_store.py
@@ -199,7 +199,7 @@ class CompressionStore:
compression_strategy: Strategy used for compression.
ttl: Custom TTL in seconds (uses default if not specified).
explicit_hash: Use this exact hex hash as the storage key
- instead of computing MD5(original)[:24]. Required when
+ instead of computing SHA-256(original)[:24]. Required when
the marker that points at this entry was emitted by a
producer with its own hash function (e.g. SmartCrusher's
Rust row-drop path uses SHA-256[:12]). If not a hex
@@ -210,28 +210,35 @@ class CompressionStore:
Returns:
Hash key for retrieving this content.
"""
- # Generate hash from original content. Default: MD5[:24] of the
+ # Generate hash from original content. Default: SHA-256[:24] of the
# original. When the caller provides `explicit_hash`, use it
# verbatim — required when the hash that ends up in the prompt
# marker is produced by another component (e.g. the Rust
# SmartCrusher row-drop path emits SHA-256[:12], which the
# Python store has to mirror so /v1/retrieve resolves it).
- # CRITICAL FIX #5: Use 24 chars (96 bits) instead of 16 (64 bits) for better
- # collision resistance. Birthday paradox: 50% collision at sqrt(2^n) entries.
- # - 64 bits: ~4 billion entries for 50% collision
- # - 96 bits: ~280 trillion entries for 50% collision
+ # 24 chars (96 bits) was chosen for collision resistance under the
+ # birthday bound: 50% collision probability at ~280 trillion entries
+ # (2^48), versus ~4 billion (2^32) for the previous 16-char default.
if explicit_hash is not None:
# Validate as hex. Bail loudly per `feedback_no_silent_fallbacks`
- # — silently falling back to MD5 when the caller asked for a
- # specific key would defeat the marker/store consistency we're
- # trying to preserve.
+ # — silently falling back to the default hash when the caller
+ # asked for a specific key would defeat the marker/store
+ # consistency we're trying to preserve.
if not explicit_hash or not all(c in "0123456789abcdefABCDEF" for c in explicit_hash):
raise ValueError(
f"explicit_hash must be a non-empty hex string, got {explicit_hash!r}"
)
hash_key = explicit_hash.lower()
else:
- hash_key = hashlib.md5(original.encode()).hexdigest()[:24] # nosec B324
+ # SHA-256 truncated to 24 hex chars (96 bits) — same collision
+ # space as the MD5[:24] this replaced. Switched from MD5 in
+ # PR #395 to silence CodeQL's `py/weak-sensitive-data-hashing`
+ # rule (the `usedforsecurity=False` parameter and the `lgtm`
+ # comment marker both failed to suppress it). The cache is
+ # in-memory, so changing the hash function on upgrade has no
+ # persistence-side effect — the same content always hashes
+ # deterministically under whichever function is in use.
+ hash_key = hashlib.sha256(original.encode()).hexdigest()[:24]
entry = CompressionEntry(
hash=hash_key,
diff --git a/plugins/headroom-agent-hooks/.claude-plugin/plugin.json b/plugins/headroom-agent-hooks/.claude-plugin/plugin.json
index 4d8e4f107..d5f65b6ab 100644
--- a/plugins/headroom-agent-hooks/.claude-plugin/plugin.json
+++ b/plugins/headroom-agent-hooks/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "headroom",
- "version": "0.20.16",
+ "version": "0.20.28",
"description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.",
"author": {
"name": "Headroom Contributors",
diff --git a/plugins/headroom-agent-hooks/.github/plugin/plugin.json b/plugins/headroom-agent-hooks/.github/plugin/plugin.json
index f91358182..2a5588a0b 100644
--- a/plugins/headroom-agent-hooks/.github/plugin/plugin.json
+++ b/plugins/headroom-agent-hooks/.github/plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "headroom",
- "version": "0.20.16",
+ "version": "0.20.28",
"description": "Headroom startup hooks for Claude Code and GitHub Copilot CLI.",
"author": {
"name": "Headroom Contributors",