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>

frontend/.env.example

@@ -2,3 +2,8 @@
 VITE_API_BASE_URL=/api/v1
 VITE_USE_MOCK=true
 VITE_APP_NAME=LegacyHUB
+
+# Optional. When the backend has API_KEY set, the SPA must echo it on every
+# request. For SSO/cookie deployments leave this empty and let the reverse
+# proxy inject the header server-side.
+VITE_API_KEY=

frontend/src/services/apiClient.ts

@@ -1,11 +1,15 @@
 import axios, { type AxiosInstance, type AxiosError } from "axios";
 
 const BASE_URL = import.meta.env.VITE_API_BASE_URL ?? "/api/v1";
+const API_KEY = import.meta.env.VITE_API_KEY ?? "";
+
+const defaultHeaders: Record<string, string> = { "Content-Type": "application/json" };
+if (API_KEY) defaultHeaders["X-API-Key"] = API_KEY;
 
 export const apiClient: AxiosInstance = axios.create({
   baseURL: BASE_URL,
   timeout: 60_000,
-  headers: { "Content-Type": "application/json" },
+  headers: defaultHeaders,
 });
 
 apiClient.interceptors.response.use(

frontend/src/vite-env.d.ts

@@ -4,6 +4,7 @@ interface ImportMetaEnv {
   readonly VITE_API_BASE_URL?: string;
   readonly VITE_USE_MOCK?: string;
   readonly VITE_APP_NAME?: string;
+  readonly VITE_API_KEY?: string;
 }
 
 interface ImportMeta {