# Аутентификация ## Ключ доступа Все запросы, кроме открытых путей, требуют заголовок: ``` X-API-Key: <ключ> ``` Ключ сверяется со свойством сервера `wordpdf.api-key` (env `WORDPDF_API_KEY`). Сравнение — `MessageDigest.isEqual` (защита от timing-атак). **Пустое свойство = аутентификация выключена** — так работают `java -jar` и dev-стенд (:9011). Без ключа или с неверным: ``` HTTP 401 {"error":"Ключ доступа не передан или неверен (заголовок X-API-Key)"} ``` ## Открытые пути Без ключа всегда доступны (матч по **префиксу со слэшем**, без учёта forwarded-contextPath): |Префикс|Что| |---|---| |`/actuator/`|health-checks Spring Boot| |`/swagger-ui`|Swagger UI| |`/v3/api-docs`|OpenAPI-спек| !!! warning "Точечные сегменты обходят открытие" Пути с точечными сегментами (`..` или их URL-код `%2e`) **никогда** не считаются открытыми: запрос вида `/actuator/../api/v1/convert` потребует ключ даже на открытом префиксе. Это защита от обхода фильтра через нормализацию пути. ## Где задаётся ключ |Среда|Как| |---|---| |`java -jar`|`wordpdf.api-key=` пусто — auth выключен; включить: `--wordpdf.api-key=…` или env `WORDPDF_API_KEY`| |prod-like стенд (:9010)|обязателен `.env` с `WORDPDF_API_KEY` (fail-closed: без него стек не поднимется), шаблон — `.env.example`| |прод|env-переменная контейнера из Gitea Secret (в репозитории и на диске ключа нет)| Сгенерировать ключ: `openssl rand -hex 32`. ## Как фронтенд узнаёт про ключ SPA при старте опрашивает сервис (`probeApiKey()`, `GET /api/v1/convert`): 401 — сервер требует ключ, показывается экран ввода; иначе — интерфейс открывается сразу. Введённый ключ хранится в `localStorage` браузера и стирается при ответе 401.