fix(security): verify hash before status checks to prevent key-state enumeration

OWASP API2:2023: move hash verification before ensure_valid() so a caller
with a wrong secret always receives 401 InvalidKey, regardless of whether
the key is inactive or expired. Adds regression test and updates mermaid
flow diagrams to reflect the STATE_CHECK step after COMPARE.

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

Author: Athroniaeth

README.md

@@ -34,6 +34,9 @@ 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.
 
 ## Installation
 
@@ -204,6 +207,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
@@ -220,7 +227,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
 
@@ -231,6 +239,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**

docs/schema.mermaid

@@ -37,6 +37,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
@@ -53,7 +57,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
 
@@ -64,6 +69,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**

src/keyshield/services/base.py

@@ -472,19 +472,19 @@ async def _verify_entity(self, entity: ApiKey, key_secret: str, required_scopes:
             The entity with updated last_used_at.
 
         Raises:
+            InvalidKey: If the hash does not match.
             KeyInactive: If the key is disabled.
             KeyExpired: If the key is expired.
-            InvalidKey: If the hash does not match.
             InvalidScopes: If scopes are insufficient.
         """
         # Todo: IDK if this line ise usefully
         # assert entity.key_hash is not None, "key_hash must be set for existing API keys"  # nosec B101
 
-        entity.ensure_valid(scopes=required_scopes)
-
         if not self._hasher.verify(entity.key_hash, key_secret):
             raise InvalidKey("API key is invalid (hash mismatch)")
 
+        entity.ensure_valid(scopes=required_scopes)
+
         return await self.touch(entity)
 
     def _get_parts(self, api_key: str) -> ParsedApiKey:

tests/unit/test_service.py

@@ -260,6 +260,19 @@ async def test_verify_inactive_raises(self, service: ApiKeyService):
         with pytest.raises(KeyInactive):
             await service.verify_key(full_key)
 
+    @pytest.mark.asyncio
+    async def test_verify_inactive_with_wrong_secret_raises_invalid_key(self, service: ApiKeyService):
+        """verify_key() raises InvalidKey (not KeyInactive) for wrong secret on inactive key.
+
+        Regression test for OWASP API2:2023: the caller must not be able to enumerate
+        key state (active/inactive) without knowing the correct secret.
+        """
+        entity, _ = await service.create(name="inactive", is_active=False)
+        bad_key = _full_key(entity.key_id, key_secret_factory())
+
+        with pytest.raises(InvalidKey):
+            await service.verify_key(bad_key)
+
     @pytest.mark.asyncio
     async def test_verify_expired_raises(self, service: ApiKeyService):
         """verify_key() raises KeyExpired for expired key."""