pipu-music/docs/auth-and-roles.md

# Аутентификация, роли, первый запуск

## Роли

| Роль | Назначение |
|---|---|
| `admin` | Владелец системы. Может быть несколько, но минимум один всегда (последнего админа нельзя понизить / удалить / заблокировать). |
| `moderator` | Заместитель администратора: управление обычными пользователями. |
| `user` | Слушатель. |

## Матрица прав

| Действие | user | moderator | admin |
|---|:-:|:-:|:-:|
| Слушать, поиск, коллекция, волна | ✅ | ✅ | ✅ |
| Сменить свой пароль, язык, сессии | ✅ | ✅ | ✅ |
| Открыть админку | — | ✅ | ✅ |
| Видеть список пользователей | — | ✅ | ✅ |
| Создать пользователя с ролью `user` | — | ✅ | ✅ |
| Сбросить пароль / рекомендации, заблокировать `user` | — | ✅ | ✅ |
| Создать `moderator` / `admin`, менять роли | — | — | ✅ |
| Менять логин любого пользователя, включая себя | — | — | ✅ |
| Сбросить пароль / рекомендации, заблокировать `moderator` | — | — | ✅ |
| Удалить пользователя | — | — | ✅ |
| Хранилища, сканирование, переиндексация | — | — | ✅ |
| Статус библиотеки (только просмотр) | — | ✅ | ✅ |
| Предлагать треки (загрузка в очередь), видеть свои предложения | — | ✅ | ✅ |
| Лимит очереди, целевое хранилище, шаблон раскладки | — | — | ✅ |
| Статус рекомендательной системы, аудит | — | — | ✅ |
| Выдать / забрать аудит загрузок | — | — | ✅ |

**Аудит загрузок** (рассматривать очередь, одобрять / отклонять, править метаданные) — не строка матрицы, а
отдельный флаг пользователя `reviews_uploads`, не зависящий от роли: его может иметь кто угодно, сразу несколько
человек, а у админа его может не быть. Проверка — `Principal.Allowed(PermReviewUploads)`.

Реализация: в Go — политики в `internal/auth/policy.go` вида `CanManageUser(actor, target, action) bool`,
проверяются в сервисном слое (не только в middleware), покрываются табличными тестами по этой матрице.
Все админские действия пишутся в `audit_log`.

## Первый запуск (bootstrap)

1. При старте `api` проверяет `app_settings['bootstrap.completed']`. Если нет и в `users` нет ни одного админа —
   создаёт пользователя:
   - `username = BOOTSTRAP_ADMIN_USERNAME` (по умолчанию `admin`);
   - пароль = `BOOTSTRAP_ADMIN_PASSWORD` из env, а если не задан — генерируется случайный (20 символов)
     и **печатается в лог один раз**;
   - `must_change_credentials = true`.
2. `GET /server-info` возвращает `bootstrap_required: true` — клиент может показать подсказку на экране входа.
3. После входа с `must_change_credentials = true` любые эндпоинты, кроме `/me`, `/me/bootstrap-credentials`,
   `/auth/logout`, отвечают `403 { code: "auth.credentials_change_required" }`. Клиент показывает
   экран «Смените логин и пароль администратора».
4. `POST /me/bootstrap-credentials` — новый логин (может остаться `admin`, но пароль обязан отличаться),
   новый пароль (≥ 12 символов для админа) → флаг снимается, `bootstrap.completed = true`,
   все прочие токены отзываются, выдаётся новая пара.

Аналогично для `must_change_password` (после сброса пароля админом / модератором): разрешён только
`POST /me/password` (без `current_password`, если вход был по временному паролю).

## Перенос пользователей через файл

Администратору на странице «Пользователи» доступны «Экспорт пользователей» и «Импорт пользователей».
JSON-файл версии 1 содержит логины, отображаемые имена, роли, дополнительные права аудита загрузок
и управления обновлениями, флаги блокировки и обязательной смены пароля, а также хэши Argon2id.
Действующие пароли сохраняются; открытые пароли в файле отсутствуют. Файл содержит секретные данные
и должен храниться в защищённом месте. Экспорт охватывает всех пользователей независимо от фильтров страницы.

Импорт добавляет отсутствующие логины с новыми ID. Существующие логины пропускаются без изменений
пароля, роли и данных пользователя; список пропущенных логинов показывается в результате.
Весь файл проверяется до записи, добавление выполняется атомарно. Ограничения: 10000 пользователей,
16 MiB; параметры импортированных хэшей ограничены для безопасной проверки пароля при следующем входе.
Рекомендации, история, лайки, плейлисты, сессии и настройки интерфейса не экспортируются и не импортируются.
Язык новых записей берётся из настроек сервера. Импорт и экспорт пишутся в журнал без хэшей паролей.
API: `GET /admin/users/export`, `POST /admin/users/import` (оба только для admin).

## Пароли

- argon2id: `m=64 MiB, t=3, p=2`, соль 16 байт; параметры в хэше (PHC), при изменении — rehash при входе.
- Политика: ≥ 8 символов для `user`, ≥ 12 для `moderator`/`admin`; не совпадает с логином; проверка по
  встроенному списку частых паролей (`internal/auth/common_passwords.txt`; пока ~150 записей, цель — 10k).
- Временный пароль при создании пользователя и при сбросе генерирует сервер: 12 символов, показывается **один раз**;
  у пользователя ставится `must_change_password = true`.
- Защита от перебора: после 5 неудачных попыток — `locked_until = now() + 5 мин` (растёт экспоненциально до 1 ч),
  плюс rate limit по IP в Redis. Ответ всегда одинаковый (`auth.invalid_credentials`) — не раскрываем,
  существует ли логин. Время ответа выравнивается (хэш с фиктивным паролем для несуществующих).

## Токены

| | Access | Refresh |
|---|---|---|
| Формат | JWT, EdDSA (Ed25519) | 32 случайных байта, base64url; в БД — SHA-256 |
| Срок | 15 мин | 30 дней скользящий (каждая ротация продлевает), абсолютный максимум 180 дней |
| Claims | `sub`, `role`, `sid` (family_id), `ver` (token_version пользователя), `exp`, `iat` | — |
| Веб | в памяти (JS) | cookie `pipu_rt`: `HttpOnly; Secure; SameSite=Strict; Path=/api/v1/auth` |
| Android | в памяти | `expo-secure-store` |

- **Ротация**: каждый `/auth/refresh` помечает старый токен `used_at` и выдаёт новый в той же `family_id`.
  Повторное предъявление уже использованного токена ⇒ компрометация ⇒ отзыв всей семьи
  (`401 auth.refresh_reused`). Исключение — первые 10 с после ротации: так бывает, когда две вкладки
  обновляют токен одновременно; ответ `401 auth.refresh_race` без отзыва, клиент повторяет запрос
  с уже новой cookie.
- **Мгновенный отзыв** (блокировка, смена роли, смена пароля): у пользователя инкрементируется `token_version`
  (в Redis-кэше), middleware сравнивает с `ver` в access-токене.
- Ключи подписи: `JWT_PRIVATE_KEY` (base64 seed Ed25519) из env; `kid` = первые 8 байт SHA-256 публичного ключа,
  прежние ключи для проверки — `JWT_PREVIOUS_KEYS`.
- Смена пароля и учётных данных отзывает все сессии и сразу выдаёт новую пару текущему устройству —
  пользователь остаётся в системе, остальные устройства разлогиниваются.
- CSRF: refresh-cookie `SameSite=Strict` и путь только `/api/v1/auth`; остальные запросы — Bearer-заголовок,
  поэтому CSRF к ним неприменим.

## Клиентская логика

- Один общий модуль в `packages/core/auth`: хранит access в памяти, при `401 auth.token_expired`
  делает **единственный** параллельный refresh (single-flight) и повторяет запросы.
- Роутинг-гарды: `must_change_credentials` → `/setup/admin`; `must_change_password` → `/setup/password`;
  админские разделы — по `role`.


Управление обновлениями сервера — право `manages_updates`: у admin всегда, другим его выдаёт и отзывает только admin. Оно даёт доступ к `/admin/updates`, управлению источниками и запуску обновления, но не к конфигурации сервера. `/admin/config` доступен только admin. Подробности: [server-management.md](server-management.md).