- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
2.5 KiB
Аутентификация
Ключ доступа
Все запросы, кроме открытых путей, требуют заголовок:
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.