feat: implement HMAC-SHA256 for API key hashing and add corresponding tests

Signed-off-by: Grant Ramsay <seapagan@gmail.com>

Author: seapagan

app/managers/api_key.py

@@ -1,13 +1,15 @@
 """Define the API Key Manager."""
 
 import hashlib
+import hmac
 import secrets
 from typing import Optional
 from uuid import UUID
 
 from fastapi import Depends, HTTPException, Request, status
 from sqlalchemy.ext.asyncio import AsyncSession
 
+from app.config.settings import get_settings
 from app.database.db import get_database
 from app.database.helpers import (
     add_new_api_key_,
@@ -36,8 +38,17 @@ class ApiKeyManager:
 
     @staticmethod
     def _hash_key(key: str) -> str:
-        """Hash an API key."""
-        return hashlib.sha256(key.encode()).hexdigest()
+        """Hash an API key using HMAC-SHA256.
+
+        This intentionally uses HMAC-SHA256 rather than a slow, memory-hard
+        password hash (e.g., bcrypt or argon2) because our API keys are
+        generated with `secrets.token_urlsafe(32)`, giving ~192 bits of
+        entropy. They are not human-chosen or guessable, so brute-forcing
+        them is computationally infeasible. HMAC also prevents
+        length-extension attacks possible with raw SHA256 hashing.
+        """
+        secret_key = get_settings().secret_key.encode()
+        return hmac.new(secret_key, key.encode(), hashlib.sha256).hexdigest()
 
     @classmethod
     def generate_key(cls) -> str:

pyproject.toml

@@ -180,6 +180,7 @@ convention = "google"
   "TD003",
   "FIX002",
   "RUF012",
+  "SLF001", # sometimes tests need to access private members
 ]
 "app/managers/auth.py" = ["ERA001"]
 "app/resources/auth.py" = ["ERA001"]

tests/unit/test_admin.py

@@ -1,6 +1,5 @@
 """Unit tests for the admin interface."""
 
-# ruff: noqa: SLF001
 import json
 from datetime import datetime, timedelta, timezone
 

tests/unit/test_api_key_manager.py

@@ -1,5 +1,7 @@
 """Test the API Key Manager functionality."""
 
+import hashlib
+import hmac
 from uuid import uuid4
 
 import pytest
@@ -318,3 +320,47 @@ async def test_api_key_auth_user_not_found_in_db_no_auto_error(
         auth = ApiKeyAuth(auto_error=False)
         result = await auth(request=mock_req, db=test_db)
         assert result is None
+
+    def test_hash_key_uses_hmac(self, mocker) -> None:
+        """Test that API key hashing uses HMAC-SHA256 with secret key."""
+        # Mock the settings
+        mock_settings = mocker.patch("app.managers.api_key.get_settings")
+        test_secret = "test_secret_key_12345"  # noqa: S105
+        mock_settings.return_value.secret_key = test_secret
+
+        test_key = "pk_test_key_123456789"
+        result = ApiKeyManager._hash_key(test_key)
+
+        # Calculate expected HMAC manually
+        expected = hmac.new(
+            test_secret.encode(), test_key.encode(), hashlib.sha256
+        ).hexdigest()
+
+        assert result == expected
+        assert len(result) == 64  # SHA256 hex digest length  # noqa: PLR2004
+
+    def test_hash_key_different_secrets_different_hashes(self, mocker) -> None:
+        """Test that different secret keys produce different hashes."""
+        test_key = "pk_same_key_123"
+
+        # First hash with secret 1
+        mock_settings = mocker.patch("app.managers.api_key.get_settings")
+        mock_settings.return_value.secret_key = "secret1"  # noqa: S105
+        hash1 = ApiKeyManager._hash_key(test_key)
+
+        # Second hash with secret 2
+        mock_settings.return_value.secret_key = "secret2"  # noqa: S105
+        hash2 = ApiKeyManager._hash_key(test_key)
+
+        assert hash1 != hash2
+
+    def test_hash_key_deterministic(self, mocker) -> None:
+        """Test that the same key produces the same hash consistently."""
+        mock_settings = mocker.patch("app.managers.api_key.get_settings")
+        mock_settings.return_value.secret_key = "consistent_secret"  # noqa: S105
+
+        test_key = "pk_deterministic_test"
+        hash1 = ApiKeyManager._hash_key(test_key)
+        hash2 = ApiKeyManager._hash_key(test_key)
+
+        assert hash1 == hash2