Перейти к содержанию

0013 — Auth PoC и Gmail для DEV

  • Дата: 2026-08-21.
  • Статус: Принято для PoC и DEV; Gmail SMTP сохранён как fallback, основной DEV transport уточнён решением 0025.
  • Ответственный: владелец проекта.

Контекст

После подтверждения product gate владелец разрешил начать Auth PoC и установку Better Auth. Для этапа разработки выбран существующий почтовый ящик Gmail; production-провайдер не выбирался.

Решение

  • Для Auth PoC установлена и зафиксирована версия better-auth@1.7.1.
  • Auth API размещается внутри модульного монолита по пути /api/v1/auth/*; внутренний путь Fastify после DEV proxy — /v1/auth/*.
  • Identity, password hash, verification token и сессии хранятся в PostgreSQL-таблицах auth_*; организации и memberships остаются продуктовой моделью SKUARO.
  • Email должен быть подтверждён до входа. Автоматический вход после регистрации и подтверждения отключён.
  • Сброс пароля отзывает прежние сессии. Пользователь со статусом inactive не получает новую сессию.
  • Принятая парольная политика проверяется общей функцией на frontend и серверной границе перед Better Auth.
  • Rate limit включён явно и действует для регистрации, входа, повторного письма, запроса и завершения сброса пароля. Распределённый rate limit и CAPTCHA пока не выбраны.
  • Для DEV выбран Gmail. Адрес ящика, пароль приложения и другие credentials не записываются в Git или документацию.
  • DEV-транспорт: smtp.gmail.com, STARTTLS, порт 587, отдельный Google App Password после включения двухэтапной аутентификации. Установлен nodemailer@9.0.5 с типами @types/nodemailer@8.0.1.
  • Gmail не считается production-провайдером: лимиты, репутация отправителя, bounce/complaint handling и эксплуатационные гарантии будут оцениваться отдельно.

Реализованная граница

  • Созданы Drizzle-схема и первая SQL-миграция auth-таблиц с UUID, timestamptz, внешними ключами и enum статуса/платформенной роли.
  • Реализованы конфигурация Better Auth, email-контракт и шаблоны писем, Fastify adapter, нейтральный ответ при неготовом Auth и frontend-клиент.
  • UI регистрации, входа, восстановления и нового пароля вызывает Auth API; демонстрационная успешная авторизация удалена.
  • В тестах используется только memory sender и домен .test; токены и реальные email не логируются.
  • Реализован Gmail sender, fail-closed runtime-конфигурация Auth и явная проверка SMTP без отправки письма.
  • Локальный запуск может прочитать [LOCAL_SECRET_STORE]/config_skuaro_Email.env; локальные имена email/pass преобразуются в канонические переменные только в памяти процесса.

Синтетический PostgreSQL-сценарий sign-up → verify → login → recovery → revoke прошёл. Фактическая Gmail-аутентификация пока не подтверждена: TCP к портам 587/465 устанавливается, но текущая сеть не передаёт SMTP/TLS greeting, поэтому проверка останавливается до команды AUTH. Реальное письмо не отправлялось.

Последствия

  • Better Auth остаётся кандидатом до успешного интеграционного сценария с PostgreSQL и выбранным live email transport; решение 0025 заменило основной DEV-путь Gmail SMTP на Resend HTTPS API.
  • Auth runtime включается только при одновременном наличии PostgreSQL, полной auth-конфигурации и полной конфигурации выбранного email provider; иначе route отвечает 503 AUTH_NOT_CONFIGURED или запуск останавливается на неполной конфигурации.
  • Создание Organization и Membership(owner) после подтверждения email относится к следующему доменному срезу и не подменяется auth-библиотекой.
  • Пароль длиной от 5 символов остаётся слабее рекомендуемого уровня; rate limit не заменяет будущую проверку распространённых/скомпрометированных паролей и более сильную anti-abuse защиту.

Проверка и источники

Откат или замена

Если интеграционный PoC не пройдёт, Better Auth удаляется вместе с его adapter-слоем после выбора резервной реализации и плана миграции. Замена DEV или production email-провайдера не должна менять auth-домен и email-контракт.