Files
java-word-pdf/docs/api/authentication.md
T
Pjandro b3511f8b74 docs: сайт документации на MkDocs Material
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура,
  разработчику, эксплуатация; навигация обязательна (strict-сборка).
- docs/agent/ и docs/standards/ из сайта исключены (exclude_docs),
  ссылки на них — внешние, на Gitea.
- Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
2026-11-22 21:39:08 +03:00

53 lines
2.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Аутентификация
## Ключ доступа
Все запросы, кроме открытых путей, требуют заголовок:
```
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.