Security hardening (v0.1.1)

- Header- and API-key-derived identities are SHA-256 hashed before use as Redis keys, so tokens are not observable in the keyspace (CWE-312)
- Fail-open path logs explicitly that the request was allowed despite the Redis error

Author: Berik Ashimov

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.1.1 — 2026-06-10
+
+Security hardening.
+
+- Header- and API-key-derived rate-limit identities (`header_key()`, `api_key()`) are now SHA-256 hashed before use as Redis keys, so bearer tokens and API keys are no longer observable in the keyspace (CWE-312). Note: this changes the key format produced by these identity functions.
+- The fail-open path (`RedisLimiter` Redis error with `fail_closed=False`) now logs explicitly that the request was allowed despite the error; security-sensitive routes (admin / payment) should set `fail_closed=True` to deny instead.
+
 ## 0.1.0 — 2026-05-17
 
 Initial release.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hawkapi-ratelimit"
-version = "0.1.0"
+version = "0.1.1"
 description = "Rate limiting for HawkAPI — token bucket + sliding window, Redis + in-memory backends"
 readme = "README.md"
 license = { file = "LICENSE" }

src/hawkapi_ratelimit/_identity.py

@@ -2,11 +2,21 @@
 
 from __future__ import annotations
 
+import hashlib
 import ipaddress
 from collections.abc import Callable
 from typing import Any
 
 
+def _hash_value(value: str) -> str:
+    """Hash a user-controlled identity value before it lands in the keyspace.
+
+    Defense-in-depth: bearer tokens / API keys must not be observable verbatim
+    in Redis keys. Truncated SHA-256 is collision-resistant for keyspace sizing.
+    """
+    return hashlib.sha256(value.encode()).hexdigest()[:32]
+
+
 def _parse_xff(raw: str) -> str:
     """Return the left-most ``X-Forwarded-For`` token, IP-only."""
     first = raw.split(",", 1)[0].strip()
@@ -99,7 +109,7 @@ def _fn(request: Any) -> str:
                 value = headers.get(h, "") or ""
             except Exception:
                 value = ""
-        return f"{prefix}:{value}"
+        return f"{prefix}:{_hash_value(value)}"
 
     return _fn
 
@@ -117,7 +127,7 @@ def _fn(request: Any) -> str:
                 value = ""
         if value.lower().startswith("bearer "):
             value = value[7:].strip()
-        return f"apikey:{value}"
+        return f"apikey:{_hash_value(value)}"
 
     return _fn
 

src/hawkapi_ratelimit/_redis.py

@@ -170,7 +170,10 @@ async def hit(self, key: str, limit: RateLimit, *, now: float | None = None) ->
             import logging
 
             logging.getLogger("hawkapi_ratelimit").warning(
-                "redis limiter failed (fail-open allowing): %s", exc
+                "redis limiter error — request ALLOWED despite Redis failure "
+                "(fail_closed=False; set fail_closed=True on admin/payment routes "
+                "to deny instead): %s",
+                exc,
             )
             # Fail open — count the request as allowed but report 0 remaining.
             return LimitResult(allowed=True, remaining=0, reset_at=now + limit.per)

tests/test_identity.py

@@ -6,6 +6,7 @@
 from typing import Any
 
 from hawkapi_ratelimit import api_key, composite_key, header_key, ip_key, user_key
+from hawkapi_ratelimit._identity import _hash_value
 
 
 @dataclass
@@ -84,19 +85,22 @@ class _U:
 def test_header_key_reads_header() -> None:
     fn = header_key("x-api-key", prefix="api")
     req = _Request(headers={"x-api-key": "abc123"})
-    assert fn(req) == "api:abc123"
+    # Value is hashed (defense-in-depth) — raw header must not leak into keyspace.
+    assert fn(req) == f"api:{_hash_value('abc123')}"
+    assert "abc123" not in fn(req)
 
 
 def test_api_key_strips_bearer_prefix() -> None:
     fn = api_key()
     req = _Request(headers={"authorization": "Bearer my-token"})
-    assert fn(req) == "apikey:my-token"
+    assert fn(req) == f"apikey:{_hash_value('my-token')}"
+    assert "my-token" not in fn(req)
 
 
 def test_api_key_passes_through_non_bearer() -> None:
     fn = api_key()
     req = _Request(headers={"authorization": "Basic dXNlcjpwYXNz"})
-    assert fn(req) == "apikey:Basic dXNlcjpwYXNz"
+    assert fn(req) == f"apikey:{_hash_value('Basic dXNlcjpwYXNz')}"
 
 
 def test_composite_key_combines() -> None: