2FA / TOTP

[NovakPAai]

Проработать 2FA / TOTP на базе Avanpost

---

Отправитель: novak.pavel@flowtask.dev (novak.pavel@flowtask.dev)
Окружение: production

Устройство

Устройство: desktop | ОС: macOS | Браузер: Safari
Экран: 1470×956 / вьюпорт: 1470×833
Язык: ru
URL: https://staging\-flowtask\.ru/my\-tasks
UA: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.3 Safari/605.1.15

[NovakPAai]

BDD + SDD: 2FA / TOTP на базе Avanpost

---

BDD — Behaviour-Driven Design

Feature: Двухфакторная аутентификация
Actor: Пользователь / Администратор воркспейса

Feature: Двухфакторная аутентификация (2FA / TOTP)

  # ────── Режим 1: делегирование Avanpost (рекомендуемый) ──────

  Scenario: пользователь проходит 2FA через Avanpost OIDC
    Given интеграция Avanpost настроена (PR #121)
    And в Avanpost включён обязательный TOTP для группы FloTask-users
    When пользователь нажимает "Войти через Avanpost"
    Then редирект на Avanpost login page
    And Avanpost запрашивает TOTP-код
    When пользователь вводит верный TOTP-код
    Then Avanpost возвращает id_token с claim `amr: ["totp"]`
    And FlowTask создаёт сессию и пускает в приложение

  Scenario: токен без MFA-claim при включённом требовании 2FA
    Given воркспейс требует обязательную 2FA (`require_mfa: true`)
    When Avanpost возвращает токен без `amr: ["totp"]`
    Then FlowTask отклоняет сессию
    And показывает сообщение "Для входа требуется двухфакторная аутентификация"

  # ────── Режим 2: native TOTP (если не Avanpost) ──────

  Scenario: пользователь включает TOTP-аутентификацию
    Given я авторизован
    And я нахожусь на /settings/security
    When я нажимаю "Подключить 2FA"
    Then отображается QR-код для TOTP-приложения (Google Authenticator / Яндекс.Ключ)
    And показывается текстовый секрет для ручного ввода
    When я ввожу корректный 6-значный TOTP-код
    Then 2FA активируется
    And мне показывают 10 резервных кодов (единожды, с предупреждением сохранить)

  Scenario: вход с включённой 2FA
    Given у пользователя включена native 2FA
    When пользователь вводит правильный логин и пароль
    Then появляется экран ввода TOTP-кода
    When пользователь вводит верный код
    Then доступ предоставлен
    When пользователь вводит неверный код 5 раз подряд
    Then аккаунт временно блокируется на 15 минут

  Scenario: вход с резервным кодом
    Given пользователь потерял TOTP-устройство
    When на экране 2FA он нажимает "Использовать резервный код"
    And вводит один из 10 одноразовых кодов
    Then доступ предоставлен
    And использованный код аннулируется

  Scenario: отключение 2FA
    Given у пользователя включена 2FA
    When он нажимает "Отключить 2FA" в /settings/security
    And вводит текущий TOTP-код для подтверждения
    Then 2FA отключается

  Scenario: принудительная 2FA для всего воркспейса
    Given я admin воркспейса
    When я включаю "Обязательная 2FA" в настройках воркспейса
    Then при следующем входе пользователя без 2FA ему предлагается настроить её
    And без настройки 2FA доступ к воркспейсу недоступен (grace period: 7 дней)

---

SDD — System Design

Рекомендуемый подход: Режим 1 — делегирование Avanpost

Поскольку Avanpost уже интегрирован через OIDC/PKCE (PR #121), минимальные изменения в FlowTask:

Backend (Express)

// При создании/валидации сессии проверять AMR claim
function validateMfaRequirement(idToken: DecodedJWT, workspace: Workspace) {
  if (!workspace.requireMfa) return; // 2FA не обязательна
  const amr: string[] = idToken.amr ?? [];
  const mfaSatisfied = amr.some(m => ['totp', 'otp', 'mfa'].includes(m));
  if (!mfaSatisfied) throw new ForbiddenError('MFA_REQUIRED');
}

Schema (Prisma)

model Workspace {
  // ... существующие поля
  requireMfa Boolean @default(false)
}

API

PATCH /api/workspaces/:slug/settings
  body: { requireMfa: boolean }
  auth: ADMIN/OWNER only

---

Режим 2 — Native TOTP (если нужен независимо от Avanpost)

Schema

model UserTwoFactor {
  id          String   @id @default(cuid())
  userId      String   @unique
  secret      String   // AES-256-GCM зашифрован
  enabled     Boolean  @default(false)
  backupCodes String[] // bcrypt-hashed, 10 штук
  failCount   Int      @default(0)
  lockedUntil DateTime?
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
  user        User     @relation(fields: [userId], references: [id], onDelete: Cascade)
}

API Endpoints

Method	URL	Auth	Описание
POST	/api/auth/2fa/setup	Bearer	Генерация QR + secret
POST	/api/auth/2fa/confirm-setup	Bearer + TOTP	Активация после верного кода
POST	/api/auth/2fa/challenge	session_token	Проверка TOTP при логине
POST	/api/auth/2fa/challenge-backup	session_token	Использовать резервный код
DELETE	/api/auth/2fa	Bearer + TOTP	Отключение 2FA
GET	/api/auth/2fa/backup-codes	Bearer + TOTP	Просмотр/регенерация кодов

Библиотеки (npm)

• speakeasy — генерация TOTP secret, валидация кодов (RFC 6238)
• qrcode — генерация QR SVG/PNG для TOTP-приложений
• Шифрование secret: crypto.createCipheriv('aes-256-gcm', ...), ключ из TOTP_ENCRYPTION_KEY env

Frontend Components

• <TwoFactorSetupWizard /> — 3 шага: QR-код → ввод кода → резервные коды
• <TwoFactorChallengeModal /> — модалка ввода кода при логине (6-digit input + резервный код)
• <SecuritySettingsSection /> в /settings/security — статус 2FA, кнопки включить/отключить

Риски

Риск	Митигация
Режим 1: настройка TOTP в Avanpost Admin Console вне нашего контроля	Документировать в README; добавить amr claim в список требований к Avanpost
Режим 2: хранение TOTP secret → обязательное шифрование	Env var TOTP_ENCRYPTION_KEY, ротация ключа требует реэнкрипт
Принудительная 2FA ломает уже залогиненных пользователей	Grace period 7 дней + уведомление за 3 дня до дедлайна
Потеря TOTP-устройства без резервных кодов	Admin-flow для сброса 2FA конкретному пользователю

Acceptance Criteria

• Режим 1: requireMfa настраивается на уровне воркспейса, AMR claim проверяется при каждом входе
• Режим 2 (если выбран): setup wizard работает, TOTP-код валидируется при логине
• Резервные коды генерируются, используются однократно
• Rate limiting: 5 неверных попыток → блокировка на 15 мин
• Принудительная 2FA: grace period 7 дней, блокировка доступа после дедлайна
• E2E: successful 2FA login + blocked login without MFA

[NovakPAai]

Spec готова: specs/gaps/gap-13-2fa-totp.md

Два режима:

• Mode A (рекомендуется) — делегирование Avanpost: извлечь amr claim из OIDC id_token, добавить requireMfa на Workspace, guard-middleware на workspace routes. Минимум изменений в FlowTask, максимум — в Avanpost Admin Console.
• Mode B — native TOTP для local auth: новая UserTwoFactor Prisma-модель, setup wizard, challenge при логине, резервные коды, rate limiting.

Spec содержит полные BDD сценарии (A1–C2), TypeScript контракты, Prisma schema, список API-эндпоинтов и constraints (включая amr claim зависимость от версии Avanpost).