fix(security): replace bcrypt pepper concatenation with HMAC-SHA256 pre-hashing

Bcrypt silently truncates input at 72 bytes. Concatenating key_secret (64
chars) with a pepper could push the combined string past that limit, causing
the tail characters to be ignored — two distinct secrets could produce the
same hash.

Fix: _apply_pepper() now computes HMAC-SHA256(pepper, secret), producing a
fixed 32-byte digest that is always well within bcrypt's input limit. The
pepper remains cryptographically bound to the secret as the HMAC key.

This is a breaking change: hashes stored under the old concatenation scheme
will not verify with the new implementation; affected keys must be re-issued.

Also updates README, docs/index.md, and docs/schema.mermaid to document the
NIST SP 800-132 compliance entry, the OWASP API2:2023 bullet (missing from
docs/index.md), the STATE_CHECK node (missing from the docs/index.md diagram),
and the NOTE_ARGON annotation to cover both Argon2 and Bcrypt strategies.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Author: Athroniaeth

README.md

@@ -37,6 +37,13 @@ This library try to follow best practices and relevant RFCs for API key manageme
 - **[OWASP API2:2023](https://owasp.org/API-Security/editions/2023/en/0xa2-broken-authentication/)**: Hash
   verification is performed before status/scope checks to prevent key-state enumeration — a caller with
   a wrong secret always receives `401 Invalid`, regardless of whether the key is inactive or expired.
+- **[NIST SP 800-132](https://csrc.nist.gov/publications/detail/sp/800-132/final)**: The Bcrypt hasher
+  pre-hashes the secret via `HMAC-SHA256(pepper, secret)` before passing it to bcrypt, producing a fixed
+  32-byte digest that eliminates bcrypt's silent 72-byte input truncation.
+- **Input validation (defense-in-depth)**: Scope strings are validated against a strict allowlist
+  pattern (`^[a-z][a-z0-9:_\-]*$`) at the schema level. Note: [RFC 6749 §3.3](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3)
+  permits a broader character set; this restriction is a deliberate keyshield design choice to
+  prevent injection of arbitrary characters (HTML, SQL fragments, etc.) in scope values.
 
 ## Installation
 
@@ -257,9 +264,10 @@ flowchart LR
     • invalid if api key updated or deleted
     • invalid after 3600s`"]:::noteStyle
 
-    NOTE_ARGON["`**ArgonApiKeyHasher**
-    • line salt apikey
-    • global pepper api key`"]:::noteStyle
+    NOTE_ARGON["`**Hashing strategy**
+    Argon2: concat(secret, pepper)
+    Bcrypt: HMAC-SHA256(pepper, secret)
+    → fixed 32 bytes, no 72-byte truncation`"]:::noteStyle
 
     NOTE_SLEEP["`**sleep random (0.1s – 0.5s)**
     makes brute force less effective;

docs/index.md

@@ -34,6 +34,12 @@ This library try to follow best practices and relevant RFCs for API key manageme
   valid but inactive/expired keys
 - **[RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750)**: Supports `Authorization: Bearer <api_key>` header for
   key transmission (also supports deprecated `X-API-Key` header and `api_key` query param)
+- **[OWASP API2:2023](https://owasp.org/API-Security/editions/2023/en/0xa2-broken-authentication/)**: Hash
+  verification is performed before status/scope checks to prevent key-state enumeration — a caller with
+  a wrong secret always receives `401 Invalid`, regardless of whether the key is inactive or expired.
+- **[NIST SP 800-132](https://csrc.nist.gov/publications/detail/sp/800-132/final)**: The Bcrypt hasher
+  pre-hashes the secret via `HMAC-SHA256(pepper, secret)` before passing it to bcrypt, producing a fixed
+  32-byte digest that eliminates bcrypt's silent 72-byte input truncation.
 
 ## How API Keys Work
 
@@ -103,6 +109,10 @@ flowchart LR
     COMPARE{"`**Compare db api key hash
     to received api key hash**`"}:::processNode
 
+    STATE_CHECK{"`**Check state & scopes**
+    _(active? not expired?
+    required scopes?)_`"}:::processNode
+
     %% ── Outcomes ────────────────────────────────────────────
     REJECT(["`🔴 **Reject API Key**`"]):::rejectNode
     ACCEPT(["`🟢 **Accept API Key**`"]):::acceptNode
@@ -119,7 +129,8 @@ flowchart LR
 
     %% ── Accept path ─────────────────────────────────────────
     CACHED -- "yes" --> ACCEPT
-    COMPARE -- "equals" --> ACCEPT
+    COMPARE -- "equals" --> STATE_CHECK
+    STATE_CHECK -- "valid" --> ACCEPT
     ACCEPT -- "`**APIKey.touch()**
     _(update last_used_at)_`" --> CACHE_STORE
 
@@ -130,6 +141,7 @@ flowchart LR
     PREFIX_CHECK -- "no" --> REJECT
     QUERY_DB -- "not found" --> REJECT
     COMPARE -- "not equals" --> REJECT
+    STATE_CHECK -- "invalid (403)" --> REJECT
 
     %% ── Notes (annotations) ─────────────────────────────────
     NOTE_FORMAT["`**Format API Key**
@@ -147,9 +159,10 @@ flowchart LR
     • invalid if api key updated or deleted
     • invalid after 3600s`"]:::noteStyle
 
-    NOTE_ARGON["`**ArgonApiKeyHasher**
-    • line salt apikey
-    • global pepper api key`"]:::noteStyle
+    NOTE_ARGON["`**Hashing strategy**
+    Argon2: concat(secret, pepper)
+    Bcrypt: HMAC-SHA256(pepper, secret)
+    → fixed 32 bytes, no 72-byte truncation`"]:::noteStyle
 
     NOTE_SLEEP["`**sleep random (0.1s – 0.5s)**
     makes brute force less effective;

docs/schema.mermaid

@@ -87,9 +87,10 @@ flowchart LR
     • invalid if api key updated or deleted
     • invalid after 3600s`"]:::noteStyle
 
-    NOTE_ARGON["`**ArgonApiKeyHasher**
-    • line salt apikey
-    • global pepper api key`"]:::noteStyle
+    NOTE_ARGON["`**Hashing strategy**
+    Argon2: concat(secret, pepper)
+    Bcrypt: HMAC-SHA256(pepper, secret)
+    → fixed 32 bytes, no 72-byte truncation`"]:::noteStyle
 
     NOTE_SLEEP["`**sleep random (0.1s – 0.5s)**
     makes brute force less effective;

src/keyshield/_schemas.py

@@ -14,12 +14,16 @@
     ) from e
 
 from datetime import datetime, timedelta
-from typing import List, Optional
+from typing import Annotated, List, Optional
 
 from keyshield.domain.entities import ApiKey
 from keyshield.repositories.base import ApiKeyFilter, SortableColumn
 from keyshield.utils import datetime_factory
 
+# Scope strings must follow the format: lowercase letter, then lowercase
+# alphanumerics, colons, underscores, or hyphens (e.g. "read", "api:write").
+_ScopeStr = Annotated[str, Field(pattern=r"^[a-z][a-z0-9:_\-]*$")]
+
 
 class ApiKeyCreateIn(BaseModel):
     """Payload to create a new API key.
@@ -35,7 +39,7 @@ class ApiKeyCreateIn(BaseModel):
     name: str = Field(..., min_length=1, max_length=128)
     description: Optional[str] = Field(None, max_length=1024)
     is_active: bool = Field(default=True)
-    scopes: List[str] = Field(default_factory=list)
+    scopes: List[_ScopeStr] = Field(default_factory=list)
     expires_at: Optional[datetime] = Field(
         default=None,
         examples=[(datetime_factory() + timedelta(days=30)).isoformat()],
@@ -58,7 +62,7 @@ class ApiKeyUpdateIn(BaseModel):
     name: Optional[str] = Field(None, min_length=1, max_length=128)
     description: Optional[str] = Field(None, max_length=1024)
     is_active: Optional[bool] = None
-    scopes: Optional[List[str]] = None
+    scopes: Optional[List[_ScopeStr]] = None
     expires_at: Optional[datetime] = Field(None, description="New expiration datetime (ISO 8601)")
     clear_expires: bool = Field(False, description="Remove expiration date")
 
@@ -120,8 +124,8 @@ class ApiKeySearchIn(BaseModel):
     last_used_before: Optional[datetime] = Field(None, description="Keys last used before this date")
     last_used_after: Optional[datetime] = Field(None, description="Keys last used after this date")
     never_used: Optional[bool] = Field(None, description="True = never used keys, False = used keys")
-    scopes_contain_all: Optional[List[str]] = Field(None, description="Keys must have ALL these scopes")
-    scopes_contain_any: Optional[List[str]] = Field(None, description="Keys must have at least ONE of these scopes")
+    scopes_contain_all: Optional[List[_ScopeStr]] = Field(None, description="Keys must have ALL these scopes")
+    scopes_contain_any: Optional[List[_ScopeStr]] = Field(None, description="Keys must have at least ONE of these scopes")
     name_contains: Optional[str] = Field(None, description="Name contains this substring (case-insensitive)")
     name_exact: Optional[str] = Field(None, description="Exact name match")
     order_by: SortableColumn = Field(SortableColumn.CREATED_AT, description="Field to sort by")

src/keyshield/hasher/bcrypt.py

@@ -1,3 +1,5 @@
+import hashlib
+import hmac
 from typing import Optional
 
 try:
@@ -25,16 +27,15 @@ def __init__(
         super().__init__(pepper=pepper)
         self._rounds = rounds
 
-    def _apply_pepper(self, api_key: str) -> str:
-        return f"{api_key}{self._pepper}"
+    def _apply_pepper(self, api_key: str) -> bytes:
+        # HMAC-SHA256 with the pepper as key produces a fixed 32-byte digest,
+        # well within bcrypt's 72-byte input limit. This avoids the silent
+        # truncation that occurs when key_secret + pepper exceeds 72 bytes.
+        return hmac.digest(self._pepper.encode("utf-8"), api_key.encode("utf-8"), hashlib.sha256)
 
     def hash(self, key_secret: str) -> str:
-        salted_key = self._apply_pepper(key_secret).encode("utf-8")
-        # Avoid exception : ValueError: password cannot be longer than 72 bytes, truncate manually if necessary (e.g. my_password[:72])
-        hashed = bcrypt.hashpw(salted_key[:72], bcrypt.gensalt(self._rounds))
+        hashed = bcrypt.hashpw(self._apply_pepper(key_secret), bcrypt.gensalt(self._rounds))
         return hashed.decode("utf-8")
 
     def verify(self, key_hash: str, key_secret: str) -> bool:
-        # Ensure that verify truncates the supplied key to 72 bytes like hash()
-        salted_key = self._apply_pepper(key_secret).encode("utf-8")[:72]
-        return bcrypt.checkpw(salted_key, key_hash.encode("utf-8"))
+        return bcrypt.checkpw(self._apply_pepper(key_secret), key_hash.encode("utf-8"))

tests/unit/test_hasher.py

@@ -145,57 +145,62 @@ class TestBcryptHasher:
 
     @patch("keyshield.hasher.bcrypt.bcrypt")
     def test_hash_applies_pepper(self, mock_bcrypt):
-        """hash() passes peppered key to bcrypt.hashpw."""
+        """hash() passes HMAC-SHA256(pepper, key) digest to bcrypt.hashpw."""
+        import hashlib
+        import hmac
+
         mock_bcrypt.gensalt.return_value = b"$2b$04$salt"
         mock_bcrypt.hashpw.return_value = b"hashed-value"
 
         hasher = BcryptApiKeyHasher(pepper="my-pepper", rounds=4)
         result = hasher.hash("api-key")
 
-        # Check pepper was applied
+        expected_digest = hmac.digest(b"my-pepper", b"api-key", hashlib.sha256)
         call_args = mock_bcrypt.hashpw.call_args[0]
-        assert call_args[0] == b"api-keymy-pepper"
+        assert call_args[0] == expected_digest
         assert result == "hashed-value"
 
     @patch("keyshield.hasher.bcrypt.bcrypt")
-    def test_hash_truncates_long_keys(self, mock_bcrypt):
-        """hash() truncates keys longer than 72 bytes."""
+    def test_hash_digest_fixed_size(self, mock_bcrypt):
+        """hash() always passes a fixed 32-byte digest to bcrypt regardless of key length."""
         mock_bcrypt.gensalt.return_value = b"$2b$04$salt"
         mock_bcrypt.hashpw.return_value = b"hashed"
 
         hasher = BcryptApiKeyHasher(pepper="pepper", rounds=4)
-        long_key = "a" * 100
 
-        hasher.hash(long_key)
+        hasher.hash("a" * 100)
 
         call_args = mock_bcrypt.hashpw.call_args[0]
-        assert len(call_args[0]) == 72
+        assert len(call_args[0]) == 32
 
     @patch("keyshield.hasher.bcrypt.bcrypt")
     def test_verify_applies_pepper(self, mock_bcrypt):
-        """verify() passes peppered key to bcrypt.checkpw."""
+        """verify() passes HMAC-SHA256(pepper, key) digest to bcrypt.checkpw."""
+        import hashlib
+        import hmac
+
         mock_bcrypt.checkpw.return_value = True
 
         hasher = BcryptApiKeyHasher(pepper="my-pepper", rounds=4)
         result = hasher.verify("stored-hash", "api-key")
 
+        expected_digest = hmac.digest(b"my-pepper", b"api-key", hashlib.sha256)
         call_args = mock_bcrypt.checkpw.call_args[0]
-        assert call_args[0] == b"api-keymy-pepper"
+        assert call_args[0] == expected_digest
         assert call_args[1] == b"stored-hash"
         assert result is True
 
     @patch("keyshield.hasher.bcrypt.bcrypt")
-    def test_verify_truncates_long_keys(self, mock_bcrypt):
-        """verify() truncates keys longer than 72 bytes."""
+    def test_verify_digest_fixed_size(self, mock_bcrypt):
+        """verify() always passes a fixed 32-byte digest to bcrypt regardless of key length."""
         mock_bcrypt.checkpw.return_value = True
 
         hasher = BcryptApiKeyHasher(pepper="pepper", rounds=4)
-        long_key = "a" * 100
 
-        hasher.verify("hash", long_key)
+        hasher.verify("hash", "a" * 100)
 
         call_args = mock_bcrypt.checkpw.call_args[0]
-        assert len(call_args[0]) == 72
+        assert len(call_args[0]) == 32
 
     def test_rounds_too_low_raises(self):
         """Rounds below 4 raises ValueError."""