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>

RUNBOOK.md

@@ -95,6 +95,36 @@ docker compose exec postgres psql -U legacyhub -d legacyhub -c \
 | Indexing stuck       | OpenSearch + Qdrant health                          | `scripts/init_opensearch.py`, `scripts/init_qdrant.py` |
 | Reranker disabled    | API logs → `reranker.disabled`                      | Ensure `RERANKER_ENABLED=true`; HF cache mounted |
 
+## API authentication
+
+Two mechanisms layered together:
+
+1. **Reverse proxy / SSO** (preferred). Front the API with nginx, Traefik, or
+   an OAuth gateway. The reverse proxy terminates TLS and authenticates the
+   caller; LegacyHUB never sees a raw user identity.
+2. **Shared-secret API key** (defence in depth). Set `API_KEY` to a long
+   random value (`openssl rand -hex 32`). Every request to `APP_API_PREFIX`
+   except `/health` must then carry either:
+
+   ```http
+   X-API-Key: <key>
+   ```
+   or:
+   ```http
+   Authorization: Bearer <key>
+   ```
+
+   `/health` is intentionally exempt so external probes do not need the
+   secret.
+
+   In production this is required (`docker-compose.prod.yml` fails the
+   stack if `API_KEY` is empty). In development the key is optional and
+   the default empty value disables the middleware entirely.
+
+   The frontend reads `VITE_API_KEY` and injects the header on every Axios
+   request. For SSO deployments leave `VITE_API_KEY` empty and let the
+   reverse proxy inject the header server-side.
+
 ## Verification gates (per change)
 
 1. `python -m pytest tests/ -q` — full unit suite (19+ tests).