awg-dash/docs/adr/008-api-ui-security.md

008. Безопасность API/UI: токен, CSRF, rate limit, маскировка секретов

• Статус: принято
• Контекст/issue: #15, #34

Контекст

Приложение управляет VPN-туннелем и принимает приватные ключи AmneziaWG. Оно доступно из LAN, а в перспективе может быть выставлено через reverse-proxy. В ТЗ этот слой не описан, но без него загрузка .conf через веб-интерфейс превращается в дыру.

Решение

• API — токен доступа в заголовке (Bearer), токен только в виде хеша в БД;
• UI — сессия + CSRF-токен на мутирующие запросы;
• приватные ключи (PrivateKey, PresharedKey) — writeOnly в OpenAPI, маска в UI и логах, файлы 0600 в отдельном каталоге;
• rate limit и lockout на /auth, ограничение допустимых источников, bind по умолчанию на LAN;
• audit log всех изменений конфигурации.

Альтернативы

• Без аутентификации, доступ только по LAN — не защищает от заражённого устройства в сети и от ошибочной публикации порта.
• OIDC-провайдер — не для локального однопользовательского приложения.

Последствия

• Начальный токен генерируется при первом старте и выводится в лог один раз — это шаг в runbook (#45).
• Маскировка секретов проверяется автотестами (#41) и security-прогоном (#44).
• UI обязан корректно вести себя при 401 (переход на форму входа) — часть AC #35.