feat(security): Phase 7c Step 2 — key generation + bcrypt verify + LRU cache

- Add generate_api_key(): generates lh_<256-bit-urlsafe> key with bcrypt hash
  (work factor 12) and 12-char prefix for UI display
- Add verify_api_key(): bcrypt.checkpw with TTLCache(maxsize=512, ttl=300s)
  to avoid re-running ~200ms bcrypt on every request after initial verify
- Add invalidate_cache(): explicit cache eviction on key revocation
- 16 new unit tests covering generation entropy, prefix format, bcrypt
  verification, cache hit/miss, and cache invalidation

Refs #22

Author: strausmann

backend/app/auth/__init__.py

@@ -0,0 +1,36 @@
+"""API key generation for Phase 7c — generates bcrypt-hashed keys with prefix.
+
+Key format: ``lh_<43-char-urlsafe-base64>``
+  - ``lh_`` — Label Hub prefix, distinguishes from other token formats
+  - 43-char body — secrets.token_urlsafe(32) produces ~43 URL-safe chars
+    from 256 bits of entropy (no padding)
+
+The plaintext is returned only at generation time and must be shown to the
+user ONCE. Only the bcrypt hash and the 12-char prefix are persisted.
+"""
+
+from __future__ import annotations
+
+import secrets
+
+import bcrypt
+
+# bcrypt work factor: 12 rounds is the 2024-2026 industry default (~100-200ms on
+# modern hardware). Deliberately slow to resist offline brute-force attacks.
+_BCRYPT_ROUNDS = 12
+
+
+def generate_api_key() -> tuple[str, str, str]:
+    """Generate a new API key.
+
+    Returns:
+        (plaintext, prefix, bcrypt_hash) where:
+        - plaintext — the full key, shown to the user ONCE, never persisted
+        - prefix    — first 12 chars (e.g. "lh_ab12cd34X"), stored for UI display
+        - bcrypt_hash — stored in the DB, used for verify_api_key()
+    """
+    body = secrets.token_urlsafe(32)  # 256 bits of entropy, URL-safe charset
+    plaintext = f"lh_{body}"
+    prefix = plaintext[:12]
+    hashed = bcrypt.hashpw(plaintext.encode(), bcrypt.gensalt(rounds=_BCRYPT_ROUNDS)).decode()
+    return plaintext, prefix, hashed

backend/app/auth/key_generator.py

@@ -0,0 +1,64 @@
+"""bcrypt verifier with LRU cache to avoid slow re-verification on every request.
+
+bcrypt.checkpw takes ~100-200ms per call (by design — work factor 12).  For a
+HomeLab with a handful of keys and hundreds of requests per day this is fine,
+but for interactive use (frontend page loads doing multiple API calls) it would
+be noticeable.
+
+The LRU cache keyed on (plaintext, hash) avoids repeated bcrypt rounds for the
+same key within the TTL window.  The cache is invalidated explicitly when a key
+is revoked or updated.
+
+Cache design:
+  - Key:   (plaintext, hashed) — using both avoids cache-poisoning if two keys
+           happen to share a prefix
+  - Value: bool (True=valid, False=invalid)
+  - Size:  maxsize=512 (sufficient for HomeLab, tiny memory footprint)
+  - TTL:   300 seconds (5 minutes) — after expiry the next call re-verifies
+
+Thread-safety: cachetools.TTLCache is NOT thread-safe, so we use an explicit
+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).
+"""
+
+from __future__ import annotations
+
+import bcrypt
+from cachetools import TTLCache
+
+# _cache is module-level so test code can inspect/clear it
+_cache: TTLCache[tuple[str, str], bool] = TTLCache(maxsize=512, ttl=300)
+
+
+def verify_api_key(plaintext: str, hashed: str) -> bool:
+    """Return True if ``plaintext`` matches the bcrypt ``hashed`` value.
+
+    Results are cached for ``ttl`` seconds (default 300s / 5 minutes) to avoid
+    repeated expensive bcrypt verifications.
+
+    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 = 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).
+
+    Called when a key is revoked or the hash changes so that subsequent
+    requests re-verify against the DB rather than getting a stale cache hit.
+    """
+    keys_to_remove = [k for k in list(_cache.keys()) if k[1] == hashed]
+    for k in keys_to_remove:
+        _cache.pop(k, None)

backend/app/auth/verifier.py

@@ -0,0 +1,79 @@
+"""Unit tests for API key generation — Phase 7c Step 2.
+
+RED phase: these tests must fail before key_generator.py exists.
+"""
+
+from __future__ import annotations
+
+import bcrypt
+import pytest
+
+
+def test_generate_api_key_importable():
+    """generate_api_key is importable from app.auth.key_generator."""
+    from app.auth.key_generator import generate_api_key  # noqa: F401
+    assert generate_api_key is not None
+
+
+def test_generate_api_key_returns_three_tuple():
+    from app.auth.key_generator import generate_api_key
+    result = generate_api_key()
+    assert len(result) == 3
+
+
+def test_plaintext_starts_with_lh_prefix():
+    from app.auth.key_generator import generate_api_key
+    plaintext, _, _ = generate_api_key()
+    assert plaintext.startswith("lh_"), f"Expected lh_ prefix, got: {plaintext[:5]}"
+
+
+def test_prefix_is_first_12_chars_of_plaintext():
+    from app.auth.key_generator import generate_api_key
+    plaintext, prefix, _ = generate_api_key()
+    assert prefix == plaintext[:12], f"prefix={prefix!r}, plaintext[:12]={plaintext[:12]!r}"
+
+
+def test_prefix_is_exactly_12_chars():
+    from app.auth.key_generator import generate_api_key
+    _, prefix, _ = generate_api_key()
+    assert len(prefix) == 12, f"Expected 12 chars, got {len(prefix)}"
+
+
+def test_bcrypt_hash_verifies_against_plaintext():
+    from app.auth.key_generator import generate_api_key
+    plaintext, _, hashed = generate_api_key()
+    assert bcrypt.checkpw(plaintext.encode(), hashed.encode()), (
+        "bcrypt.checkpw failed — hash does not match plaintext"
+    )
+
+
+def test_bcrypt_hash_rejects_wrong_plaintext():
+    from app.auth.key_generator import generate_api_key
+    _, _, hashed = generate_api_key()
+    assert not bcrypt.checkpw(b"wrong_key", hashed.encode())
+
+
+def test_generate_produces_unique_keys():
+    """10 consecutive calls produce unique plaintexts (collision probability negligible)."""
+    from app.auth.key_generator import generate_api_key
+    plaintexts = [generate_api_key()[0] for _ in range(10)]
+    assert len(set(plaintexts)) == 10, "Duplicate keys detected in 10 generations"
+
+
+def test_plaintext_body_is_urlsafe():
+    """Characters after lh_ prefix should be URL-safe (no +, /, =)."""
+    from app.auth.key_generator import generate_api_key
+    for _ in range(5):
+        plaintext, _, _ = generate_api_key()
+        body = plaintext[3:]  # strip "lh_"
+        assert "+" not in body and "/" not in body and "=" not in body, (
+            f"Non-URL-safe chars in plaintext body: {body}"
+        )
+
+
+def test_plaintext_has_sufficient_entropy():
+    """Plaintext body should be at least 43 chars (32 bytes base64url ≈ 43 chars)."""
+    from app.auth.key_generator import generate_api_key
+    plaintext, _, _ = generate_api_key()
+    body = plaintext[3:]
+    assert len(body) >= 43, f"Body too short for 256-bit entropy: {len(body)} chars"

backend/tests/unit/auth/__init__.py

@@ -0,0 +1,96 @@
+"""Unit tests for bcrypt verifier + LRU cache — Phase 7c Step 2."""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+
+import bcrypt
+import pytest
+
+
+def _make_hash(plaintext: str) -> str:
+    return bcrypt.hashpw(plaintext.encode(), bcrypt.gensalt(rounds=4)).decode()
+
+
+def test_verify_api_key_importable():
+    from app.auth.verifier import verify_api_key
+    assert verify_api_key is not None
+
+
+def test_verify_returns_true_for_correct_key():
+    from app.auth.verifier import verify_api_key
+    plaintext = "lh_testkey_correct_12345"
+    hashed = _make_hash(plaintext)
+    assert verify_api_key(plaintext, hashed) is True
+
+
+def test_verify_returns_false_for_wrong_key():
+    from app.auth.verifier import verify_api_key
+    hashed = _make_hash("lh_correct_key_abc123")
+    assert verify_api_key("lh_wrong_key_xyz999", hashed) is False
+
+
+def test_verify_caches_result_on_second_call():
+    """After the first verify, subsequent calls with same inputs skip bcrypt."""
+    from app.auth import verifier as verifier_module
+    verifier_module._cache.clear()
+
+    plaintext = "lh_cache_test_key_001"
+    hashed = _make_hash(plaintext)
+
+    bcrypt_call_count = [0]
+    original_checkpw = bcrypt.checkpw
+
+    def counting_checkpw(pw, hsh):
+        bcrypt_call_count[0] += 1
+        return original_checkpw(pw, hsh)
+
+    with patch.object(bcrypt, "checkpw", side_effect=counting_checkpw):
+        # First call — should invoke bcrypt
+        result1 = verifier_module.verify_api_key(plaintext, hashed)
+        # Second call — should use cache
+        result2 = verifier_module.verify_api_key(plaintext, hashed)
+
+    assert result1 is True
+    assert result2 is True
+    assert bcrypt_call_count[0] == 1, (
+        f"Expected 1 bcrypt call (cache hit on 2nd), got {bcrypt_call_count[0]}"
+    )
+
+
+def test_verify_different_keys_call_bcrypt_each():
+    """Different plaintext/hash pairs are each verified separately."""
+    from app.auth import verifier as verifier_module
+    verifier_module._cache.clear()
+
+    p1, h1 = "lh_key_alpha_001", _make_hash("lh_key_alpha_001")
+    p2, h2 = "lh_key_beta_002", _make_hash("lh_key_beta_002")
+
+    bcrypt_call_count = [0]
+    original_checkpw = bcrypt.checkpw
+
+    def counting_checkpw(pw, hsh):
+        bcrypt_call_count[0] += 1
+        return original_checkpw(pw, hsh)
+
+    with patch.object(bcrypt, "checkpw", side_effect=counting_checkpw):
+        verifier_module.verify_api_key(p1, h1)
+        verifier_module.verify_api_key(p2, h2)
+
+    assert bcrypt_call_count[0] == 2
+
+
+def test_invalidate_cache_removes_entry():
+    """invalidate_cache removes a cached entry by hash."""
+    from app.auth import verifier as verifier_module
+    verifier_module._cache.clear()
+
+    plaintext = "lh_invalidate_test_001"
+    hashed = _make_hash(plaintext)
+
+    # Prime cache
+    verifier_module.verify_api_key(plaintext, hashed)
+    assert (plaintext, hashed) in verifier_module._cache
+
+    verifier_module.invalidate_cache(hashed)
+    assert (plaintext, hashed) not in verifier_module._cache