netrunner-backend/src/modules/auth/README.md

modules/auth — авторизация

Четыре способа попасть в систему сходятся в одной точке — AuthService::issue_session, которая выдаёт пару токенов, а не один JWT:

• access — JWT (Claims { sub, tg_id, exp }, 15 минут), кладётся в cookie nrxp_token (Path=/).
• refresh — непрозрачный случайный токен (30 дней), в БД хранится только его SHA-256-хеш (refresh_sessions); кладётся в cookie nrxp_refresh, строго ограниченную Path=/api/v1/auth/refresh, чтобы не улетать на остальные ручки.

Обе cookie — HttpOnly; Secure; SameSite=Lax, в проде дополнительно Domain из COOKIE_DOMAIN (.netrunner-vpn.com) — одна сессия работает и на лендинге, и на ЛК на сабдомене. Никакой JS-читаемый токен нигде не хранится (ни cookie без HttpOnly, ни localStorage).

POST /auth/refresh ротирует refresh-токен при каждом использовании: старая запись помечается revoked_at, выдаётся новая пара. Предъявление уже отозванного токена (признак кражи/повторного использования после ротации) отзывает все сессии юзера. POST /auth/logout отзывает текущую сессию и чистит cookie.

Способы входа:

1. Telegram Login Widget (POST /auth/telegram, controller::auth_telegram_api). Фронтенд получает от виджета подписанный payload, бэкенд проверяет HMAC-SHA256 подпись ключом sha256(bot_token) в постоянное время (mac.verify_slice, не строковое !=) — это защита от timing-атаки на подбор подписи (см. service::verify_tg_widget_auth).
2. Telegram-бот (/start [ref_code], обрабатывается в bot.rs, не здесь) — вызывает тот же AuthService::process_login. Кнопки «Личный Кабинет»/«Тарифы»/ «Синдикат» открывают WebApp с короткоживущим (60с) bootstrap-JWT в URL-фрагменте; фронт меняет его на полноценную сессию через POST /auth/exchange.
3. Ghost Protocol (POST /auth/seed/generate, POST /auth/seed/login) — анонимный вход без привязки к Telegram. Сервер генерирует случайный 16-символьный seed, хеширует его Argon2 с фиксированной солью из ARGON_SALT (детерминированно — иначе логин никогда не совпадёт с хешем, сохранённым при регистрации) и хранит только хеш. Seed невосстановим: его теряет — теряет аккаунт.
4. Bootstrap-обмен (POST /auth/exchange) — принимает короткоживущий JWT из WebApp-ссылки бота, проверяет подпись/exp и выдаёт обычную сессию через issue_session. Это единственный способ входа, не создающий пользователя заново — он уже существует (создан через Telegram/Ghost).

Гварды (guard.rs)

• auth_guard — достаёт JWT из Authorization: Bearer или из cookie nrxp_token, валидирует подпись, подтягивает юзера из БД и кладёт его в req.extensions() для контроллеров. Для мутирующих запросов (POST/PUT/PATCH/DELETE), пришедших через cookie, дополнительно проверяет Origin/Referer против CSRF_ALLOWED_ORIGINS — это CSRF-защита. Bearer-запросы её не проходят и не должны: подделать Authorization-заголовок с чужого origin браузер не даст, поэтому CSRF для них неактуален.
• owner_guard / staff_guard / node_manage_guard / partner_guard — ролевые гварды админки (Owner/Moderator/Partner), должны идти после auth_guard в цепочке слоёв (читают роль юзера из extensions, второй запрос к БД не нужен). Без завязки на Telegram — роль назначается через staff-модуль (создание Owner — CLI --create-owner, дальше Owner/Moderator создают друг друга через API). node_manage_guard — Owner всегда, либо Moderator с выданным правом can_manage_nodes.

Sybil-защита

Триал (billing::activate_trial) намеренно недоступен Ghost-аккаунтам — иначе генерация нового seed была бы бесплатным и безлимитным способом штамповать VPN-доступ. Подробности инцидента и фикса — в SECURITY_AUDIT.md.