feat(api): optional API-key auth middleware

Adds defence-in-depth shared-secret auth that activates when API_KEY
is set. Behaviour:

- empty API_KEY (dev default): every request allowed, middleware is
  not even installed;
- non-empty API_KEY: every request under APP_API_PREFIX except
  /health must carry X-API-Key: <value> or
  Authorization: Bearer <value>. /, /docs, /redoc, /openapi.json and
  CORS preflight stay open. hmac.compare_digest is used for the
  constant-time comparison.

The middleware resolves settings lazily so test fixtures can reload
app.config and have the new API_KEY take effect on the next install.

Tests (tests/test_api_security.py, 5 cases):
- /health remains open;
- protected route rejects missing key (401);
- protected route accepts X-API-Key header;
- protected route accepts Authorization: Bearer header;
- protected route rejects a wrong key.

Frontend:
- VITE_API_KEY env reads the key and Axios injects it on every
  request, falling back to no header when empty so SSO/reverse-proxy
  deployments stay unchanged.
- vite-env.d.ts adds the new env entry.

Docs/ops:
- .env.example documents the dev-default empty key;
- .env.prod.example marks API_KEY as a required rotation point;
- docker-compose.yml forwards API_KEY (defaults to empty);
- docker-compose.prod.yml fails the stack with ?:required when API_KEY
  is missing;
- RUNBOOK gains an API authentication section with header examples
  and the reverse-proxy + key layering recommendation.

pytest -q: 33 passed (5 new security + 28 prior).
npx tsc --noEmit: clean.

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

tests/test_api_security.py

@@ -0,0 +1,167 @@
+"""Tests for the optional API-key auth middleware."""
+
+from __future__ import annotations
+
+import importlib
+
+import pytest
+
+from fastapi.testclient import TestClient
+
+
+KEY = "test-secret-key-DO-NOT-USE-IN-PROD"
+
+
+@pytest.fixture
+def secured_app(monkeypatch):
+    """Reload the FastAPI application with API_KEY set so the middleware
+    installs itself before the lifespan starts. Returns a TestClient bound to
+    that fresh app instance.
+    """
+    monkeypatch.setenv("API_KEY", KEY)
+
+    # Drop cached Settings and main so the new env vars are picked up.
+    import app.config as cfg
+    import app.main as main_module
+
+    cfg.get_settings.cache_clear()
+    importlib.reload(cfg)
+    importlib.reload(main_module)
+    return main_module.app
+
+
+def _patch_health(monkeypatch, module):
+    from app.api.schemas import ComponentHealth
+
+    def _ok(name):
+        return ComponentHealth(name=name, status="ok", detail={})
+
+    for name in (
+        "_check_postgres",
+        "_check_minio",
+        "_check_opensearch",
+        "_check_qdrant",
+        "_check_redis",
+    ):
+        monkeypatch.setattr(module, name, lambda n=name: _ok(n.removeprefix("_check_")))
+
+
+def test_health_remains_open_when_key_required(secured_app, monkeypatch):
+    from app.api import routes_health
+    from app.config import settings
+
+    _patch_health(monkeypatch, routes_health)
+    client = TestClient(secured_app)
+    res = client.get(f"{settings.app_api_prefix}/health")
+    assert res.status_code == 200
+
+
+def test_protected_route_rejects_missing_key(secured_app, monkeypatch):
+    from app.config import settings
+    from app.indexing import hybrid_search
+
+    monkeypatch.setattr(hybrid_search, "run_search", lambda req: pytest.fail("must not run"))
+
+    client = TestClient(secured_app)
+    res = client.post(
+        f"{settings.app_api_prefix}/search",
+        json={
+            "query": "anything",
+            "limit": 1,
+            "filters": {
+                "document_id": None,
+                "source_path": None,
+                "block_type": None,
+                "min_ocr_confidence": None,
+            },
+            "search_mode": "hybrid",
+        },
+    )
+    assert res.status_code == 401
+    assert res.json()["detail"].startswith("invalid")
+
+
+def test_protected_route_accepts_x_api_key_header(secured_app, monkeypatch):
+    from app.config import settings
+    from app.indexing import hybrid_search
+    from app.api.schemas import SearchResponse
+
+    monkeypatch.setattr(
+        hybrid_search,
+        "run_search",
+        lambda req: SearchResponse(
+            query=req.query, mode=req.search_mode, total_candidates=0, reranked=False, results=[]
+        ),
+    )
+
+    client = TestClient(secured_app)
+    res = client.post(
+        f"{settings.app_api_prefix}/search",
+        headers={"X-API-Key": KEY},
+        json={
+            "query": "x",
+            "limit": 1,
+            "filters": {
+                "document_id": None,
+                "source_path": None,
+                "block_type": None,
+                "min_ocr_confidence": None,
+            },
+            "search_mode": "hybrid",
+        },
+    )
+    assert res.status_code == 200
+
+
+def test_protected_route_accepts_bearer_token(secured_app, monkeypatch):
+    from app.config import settings
+    from app.indexing import hybrid_search
+    from app.api.schemas import SearchResponse
+
+    monkeypatch.setattr(
+        hybrid_search,
+        "run_search",
+        lambda req: SearchResponse(
+            query=req.query, mode=req.search_mode, total_candidates=0, reranked=False, results=[]
+        ),
+    )
+
+    client = TestClient(secured_app)
+    res = client.post(
+        f"{settings.app_api_prefix}/search",
+        headers={"Authorization": f"Bearer {KEY}"},
+        json={
+            "query": "x",
+            "limit": 1,
+            "filters": {
+                "document_id": None,
+                "source_path": None,
+                "block_type": None,
+                "min_ocr_confidence": None,
+            },
+            "search_mode": "hybrid",
+        },
+    )
+    assert res.status_code == 200
+
+
+def test_protected_route_rejects_wrong_key(secured_app):
+    from app.config import settings
+
+    client = TestClient(secured_app)
+    res = client.post(
+        f"{settings.app_api_prefix}/search",
+        headers={"X-API-Key": "wrong"},
+        json={
+            "query": "x",
+            "limit": 1,
+            "filters": {
+                "document_id": None,
+                "source_path": None,
+                "block_type": None,
+                "min_ocr_confidence": None,
+            },
+            "search_mode": "hybrid",
+        },
+    )
+    assert res.status_code == 401