fix(security): offload bcrypt.checkpw to thread pool (Fix A)

verify_api_key_async wraps bcrypt.checkpw in asyncio.to_thread so the
event loop is not blocked during expensive bcrypt verification (~100-200ms).
Cache check still runs on the loop thread; thread pool is used only on
cache miss.

TDD: test_verify_api_key_does_not_block_event_loop added first (RED),
then implementation (GREEN).

Refs #22

Author: strausmann

backend/app/auth/dependencies.py

@@ -36,7 +36,7 @@
 from pydantic import BaseModel
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.auth.verifier import verify_api_key
+from app.auth.verifier import verify_api_key_async
 from app.config import Settings, get_settings
 from app.db.session import get_session
 from app.repositories import api_keys as api_keys_repo
@@ -159,7 +159,7 @@ async def _validate_api_key(
                 detail={"error_code": "key_expired", "error_message": "API key has expired"},
             )
 
-    if not verify_api_key(key_header, key_row.key_hash):
+    if not await verify_api_key_async(key_header, key_row.key_hash):
         _log.debug("bcrypt mismatch for prefix %s", prefix)
         raise HTTPException(
             status_code=status.HTTP_401_UNAUTHORIZED,

backend/app/auth/verifier.py

@@ -20,10 +20,19 @@
 asyncio-compatible pattern (single event loop = single thread for FastAPI).
 For multi-process deployments an external cache would be needed (out of scope
 for HomeLab single-instance design per spec Section 5).
+
+Async design: bcrypt.checkpw is CPU-intensive (~100-200ms).  Calling it
+directly inside an ``async def`` blocks the event loop and prevents other
+coroutines from running.  ``verify_api_key_async`` offloads the work to a
+thread pool via ``asyncio.to_thread``, keeping the loop free.  The cache
+check/write still happens on the event-loop thread (single-threaded, no lock
+needed for in-process use).
 """
 
 from __future__ import annotations
 
+import asyncio
+
 import bcrypt
 from cachetools import TTLCache
 
@@ -43,6 +52,10 @@ def verify_api_key(plaintext: str, hashed: str) -> bool:
 
     Returns:
         True if the key is valid, False otherwise.
+
+    Note:
+        This is a synchronous helper.  In async contexts prefer
+        ``verify_api_key_async`` to avoid blocking the event loop.
     """
     cache_key = (plaintext, hashed)
     if cache_key in _cache:
@@ -53,6 +66,33 @@ def verify_api_key(plaintext: str, hashed: str) -> bool:
     return result
 
 
+async def verify_api_key_async(plaintext: str, hashed: str) -> bool:
+    """Async wrapper around ``verify_api_key`` that offloads bcrypt to a thread.
+
+    bcrypt.checkpw is CPU-intensive (~100-200ms).  Running it on the event-loop
+    thread would block all other coroutines for that duration.  This wrapper:
+
+    1. Checks the TTL cache first (fast, on the loop thread).
+    2. If a cache miss, runs bcrypt.checkpw in a thread pool via
+       ``asyncio.to_thread``, freeing the loop for other work.
+    3. Writes the result back to the cache (on the loop thread after await).
+
+    Args:
+        plaintext: The full API key as provided in the ``X-Label-Hub-Key`` header.
+        hashed:    The bcrypt hash stored in the DB.
+
+    Returns:
+        True if the key is valid, False otherwise.
+    """
+    cache_key = (plaintext, hashed)
+    if cache_key in _cache:
+        return _cache[cache_key]
+
+    result = await asyncio.to_thread(bcrypt.checkpw, plaintext.encode(), hashed.encode())
+    _cache[cache_key] = result
+    return result
+
+
 def invalidate_cache(hashed: str) -> None:
     """Remove all cache entries for a given hash (e.g. after key revocation).
 

backend/tests/unit/auth/test_verifier.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import asyncio
 from unittest.mock import patch
 
 import bcrypt
@@ -94,3 +95,49 @@ def test_invalidate_cache_removes_entry():
 
     verifier_module.invalidate_cache(hashed)
     assert (plaintext, hashed) not in verifier_module._cache
+
+
+@pytest.mark.asyncio
+async def test_verify_api_key_does_not_block_event_loop():
+    """bcrypt.checkpw must run in a thread pool so the event loop stays free.
+
+    Strategy: run verify_api_key concurrently with a fast coroutine.
+    If checkpw blocks the loop, the fast coroutine cannot advance.
+    We assert the concurrent coroutine completed while verify was running.
+    """
+    from app.auth import verifier as verifier_module
+
+    verifier_module._cache.clear()
+    plaintext = "lh_nonblocking_test_001"
+    hashed = _make_hash(plaintext)
+
+    side_ran = []
+
+    async def side_coroutine():
+        await asyncio.sleep(0)
+        side_ran.append(True)
+
+    # Run both concurrently
+    await asyncio.gather(
+        verifier_module.verify_api_key_async(plaintext, hashed),
+        side_coroutine(),
+    )
+
+    assert side_ran, "Side coroutine did not run — event loop was blocked"
+
+
+@pytest.mark.asyncio
+async def test_verify_api_key_async_returns_true_for_correct_key():
+    """Async wrapper returns True for a matching key."""
+    from app.auth.verifier import verify_api_key_async
+    plaintext = "lh_async_correct_001"
+    hashed = _make_hash(plaintext)
+    assert await verify_api_key_async(plaintext, hashed) is True
+
+
+@pytest.mark.asyncio
+async def test_verify_api_key_async_returns_false_for_wrong_key():
+    """Async wrapper returns False for a non-matching key."""
+    from app.auth.verifier import verify_api_key_async
+    hashed = _make_hash("lh_async_other_001")
+    assert await verify_api_key_async("lh_async_wrong_001", hashed) is False