ipam_control/docs/changes/037-totp-2fa/PLAN.md

Двухфакторная аутентификация TOTP, по выбору пользователя (изменение 037)

Context

Стенд опубликован в интернет (изменение 034), и вход защищён только паролем и лимитами перебора. Нужен второй фактор, который пользователь включает сам.

Решения пользователя:

• Метод — TOTP: Google Authenticator, Aegis, 1Password, Bitwarden; настройка по QR-коду.
• Восстановление: 10 одноразовых кодов, выдаются при включении; superadmin может сбросить 2FA другому пользователю.
• Хранение: секрет в БД шифруется отдельным ключом TOTP_ENC_KEY (Fernet).

Обязательность 2FA не вводится: у кого 2FA выключена, вход прежний.

Модель и миграция 0015_user_totp.py

• Таблица users, новые колонки (nullable):
  • totp_secret_enc (Text) — зашифрованный подтверждённый секрет;
  • totp_pending_enc (Text) — секрет на время настройки, до подтверждения кодом;
  • totp_enabled_at (timestamptz) — признак включения;
  • totp_last_step (BigInteger) — защита от повторного использования кода: шаг TOTP должен быть строго больше последнего принятого.
• Новая таблица recovery_codes: id, user_id (FK → users.id, ON DELETE CASCADE, индекс), code_hash (sha256 hex), used_at (timestamptz null). sha256, а не argon2: коды высокоэнтропийные (10 символов base32), медленный хэш не нужен.
• UserOut: totp_enabled: bool (вычисляемое, totp_enabled_at is not None).

Конфигурация и зависимости

• app/config.py: totp_enc_key: str = "". validate_secrets(): если задан — проверить, что это корректный ключ Fernet (fail-fast). Если не задан — приложение стартует, 2FA недоступна:
  • setup → 503 «2FA не настроена на сервере (TOTP_ENC_KEY)»;
  • вход пользователя с включённой 2FA → 503 (не пропускать без второго фактора).
• docker-compose.yml: TOTP_ENC_KEY: ${TOTP_ENC_KEY:-} в окружении app.
• scripts/gen_env.py: генерировать TOTP_ENC_KEY (Fernet.generate_key() или base64.urlsafe_b64encode(os.urandom(32))).
• .env.example: строка с пояснением — потеря ключа означает сброс 2FA всем.
• requirements.txt: pyotp, segno (QR в SVG на сервере, чистый Python), cryptography. Обновить requirements.lock: venv/bin/pip-compile --strip-extras -o requirements.lock requirements.txt, команда из README.
• Новый модуль app/totp.py:
  • encrypt/decrypt (Fernet);
  • new_secret();
  • provisioning_uri(username) с issuer IPAM Manager;
  • qr_svg_data_uri(uri) через segno: data:image/svg+xml;base64,…, CSP уже разрешает img-src data:;
  • verify(user, code) — pyotp.TOTP.verify с окном ±1 шаг и проверкой totp_last_step, возвращает принятый шаг;
  • new_recovery_codes() — 10 кодов вида XXXXX-XXXXX и их хэши;
  • use_recovery_code(db, user, code) — нормализация (без дефиса, верхний регистр) и однократное погашение.

Вход — app/api/v1/auth.py

• POST /auth/login: после успешной проверки пароля, если user.totp_enabled_at:
  • вместо токена вернуть {"mfa_required": true, "mfa_token": …};
  • mfa_token — JWT с typ="mfa", sub, pv, сроком 5 минут;
  • session.login в журнал пока не пишется, last_login_* не обновляются, попытки входа не сбрасываются. TokenOut расширить: access_token: str | None, mfa_required: bool = False, mfa_token: str | None.
• POST /auth/login/2fa {mfa_token, code}:
  • токен разбирается и проверяется: typ == "mfa", пользователь активен, pv совпадает;
  • те же advisory-lock и лимиты, что у пароля (_retry_after, LoginAttempt); неверный код считается неудачной попыткой;
  • code — 6 цифр TOTP либо код восстановления;
  • успех: общая с паролем завершающая часть — вынести её из login() в хелпер _complete_login (очистка попыток, _remember_login, last_login_*, session.login, create_token). При входе кодом восстановления в diff — {"recovery_code": true} и остаток кодов;
  • неудача: session.2fa_failed в журнал (только первая в окне — как session.failed), 401 «Неверный код».
• app/security.py::current_user: отклонять токены с typ (401) — mfa_token не должен работать как токен доступа.

Управление 2FA — app/api/v1/users.py

Свои действия — любой роли, в стиле POST /users/me/password:

• POST /users/me/2fa/setup {password} — только если 2FA выключена. Новый секрет кладётся в totp_pending_enc, ответ: {secret, otpauth_uri, qr} (qr — data URI SVG).
• POST /users/me/2fa/enable {code} — проверка кода по pending-секрету; перенос в totp_secret_enc, totp_enabled_at = now(), totp_last_step; выпуск 10 кодов. Ответ: {recovery_codes: [...]} — показываются один раз. Журнал user.2fa_enabled.
• POST /users/me/2fa/disable {password, code} — code может быть TOTP или кодом восстановления. Очистить поля и удалить коды. Журнал user.2fa_disabled.
• POST /users/{id}/2fa/reset — только superadmin, не для своей записи (409 — свою отключают через /me/2fa/disable). Очистить поля и коды. Журнал user.2fa_reset.
• Журнал: все события без organization_id (системные, видит superadmin), тексты — явным message.
• Схемы в app/schemas.py: MfaLoginIn, TotpSetupIn, TotpSetupOut, TotpCodeIn, TotpDisableIn, RecoveryCodesOut.
• Ошибки: неверный пароль → 403, как в /users/me/password; неверный код → 422; 2FA уже включена или выключена → 409.

UI — web/app.js

• Вход. Если ответ mfa_required, показать второй шаг: поле «Код из приложения или код восстановления» (autocomplete="one-time-code", inputmode не ограничивать — у кода восстановления есть буквы). mfa_token хранить в памяти. «Назад» возвращает к паролю. Ошибка истёкшего токена → возврат к паролю с сообщением.
• Меню логина (изменение 036): пункт «Двухфакторная аутентификация» между «Сменить пароль» и «Выйти» → диалог.
  • 2FA выключена: «Включить» → пароль → QR, секрет текстом для ручного ввода и поле кода → «Подтвердить» → экран с 10 кодами восстановления, моноширинно, кнопка «Скопировать» и предупреждение «сохраните — больше не покажем».
  • 2FA включена: статус «включена с <дата>» и «Отключить» (пароль + код).
  • Диалоги — через существующие openDialog/formBody/fInput/dlgFoot, по образцу passwordDialog.
• Раздел «Пользователи»: бейдж 2FA в колонке статуса у пользователей с включённой 2FA. В меню строки у superadmin — «Сбросить 2FA» (с подтверждением) для чужих записей с включённой 2FA.
• auth/me отдаёт totp_enabled — диалог знает текущее состояние.

Тесты (минимально)

Один сквозной тест tests/test_users.py::test_totp_flow, pyotp вычисляет коды:

• создать пользователя и войти;
• setup → enable (получить 10 кодов);
• вход паролем → mfa_required; mfa_token на /auth/me → 401;
• /auth/login/2fa с кодом → токен; повтор того же кода → 401 (повторное использование);
• вход кодом восстановления → успех, повтор того же кода → 401;
• reset суперадминистратором → вход снова только паролем;
• в finally удалить пользователя.

pyotp добавить в requirements-dev.txt, если он не подтягивает requirements.txt.

Документация

• docs/changes/037-totp-2fa/PLAN.md — этот план; по завершении — SUMMARY.md.
• README.md:
  • «Безопасность → Вход»: 2FA по желанию, коды восстановления, сброс суперадминистратором;
  • конфигурация: TOTP_ENC_KEY;
  • API: /auth/login/2fa, /users/me/2fa/*, /users/{id}/2fa/reset;
  • миграции 0001–0015;
  • строка 037 в истории.

Исполнение

По принятой схеме: код, миграцию, UI, зависимости и тест пишет агент на Sonnet (без запуска тестов и стенда). Моя часть:

• ревью;
• TOTP_ENC_KEY в .env стенда;
• пересборка с --force-recreate;
• проверки и SUMMARY.

Проверка

• Пересборка: docker compose -p ipam_control_006 up -d --build --force-recreate app. alembic current = 0015, alembic check чисто, откат до 0014 и повторный upgrade — без ошибок; стенд отдаёт новый app.js.
• Старт без TOTP_ENC_KEY → приложение работает, setup → 503. С некорректным ключом → отказ старта.
• pytest -q — все зелёные, включая test_totp_flow.
• API вручную:
  • mfa_token не работает как токен доступа;
  • лимит перебора кода срабатывает (429 после порогов);
  • в БД totp_secret_enc не содержит base32-секрет открытым текстом;
  • события user.2fa_* и session.2fa_failed есть в журнале.
• Ручная проверка в браузере (пользователь): включение по QR в приложении-аутентификаторе, вход с кодом, вход кодом восстановления, отключение, сброс суперадминистратором.