ADR-0001: Email-First Authentication with Supabase¶

Статус¶

Accepted (Updated 2025-11-14)

Контекст¶

Проект Saga - это Integration-Only финансовая платформа для персональных пенсионных криптофондов. Необходимо обеспечить: - Простую и доступную аутентификацию для широкой аудитории - Безопасность через проверенные enterprise-решения - Совместимость с традиционными и Web3 пользователями - Минимальный барьер входа для новых пользователей

Архитектурные ограничения: - Integration-Only архитектура: никаких собственных wallet операций - Никаких приватных ключей или HD Wallet на платформе - Все криптовалютные операции через Crypto2B API и Fordefi - Аутентификация отделена от управления активами

Решение¶

Использовать Email-first аутентификацию через Supabase Auth с опциональным Web3 подключением.

Архитектура аутентификации:

Основные методы аутентификации:
Google OAuth (приоритетный)
Email/Password
Magic Links
Multi-Factor Authentication (MFA)
Поток аутентификации:
Пользователь регистрируется через Google/Email
Supabase Auth обрабатывает аутентификацию
Backend валидирует JWT токены от Supabase
Создается пользовательская сессия
Опциональная Web3 интеграция:
Привязка wallet адреса к существующему аккаунту
Только для identity, НЕ для управления активами
Использование для будущих DeFi интеграций

Ключевые компоненты:

frontend/user-app/src/hooks/useSupabaseAuth.ts - Supabase auth context
frontend/user-app/src/components/auth/ - Компоненты аутентификации
backend/shared/services/auth_service.go - Валидация Supabase JWT
backend/shared/models/auth.go - Модели аутентификации

Альтернативы¶

Исключительно Web3 wallet аутентификация¶

Отклонена - создает высокий барьер входа для пользователей, не знакомых с Web3. Противоречит Integration-Only архитектуре и принципам массового adoption для пенсионных сбережений.

Собственная система аутентификации¶

Отклонена - требует значительные ресурсы на разработку, тестирование и поддержку. Увеличивает attack surface и не обеспечивает преимуществ над enterprise-решениями.

Auth0 или аналоги¶

Рассматривались - хорошие решения, но Supabase обеспечивает лучшую интеграцию с PostgreSQL и более простую настройку для MVP.

Последствия¶

Положительные¶

Низкий барьер входа для традиционных пользователей
Проверенная enterprise-безопасность через Supabase
Знакомый UX для большинства пользователей
Быстрая разработка и простота поддержки
Масштабируемость и надежность Supabase инфраструктуры
Поддержка MFA и modern security practices

Отрицательные¶

Зависимость от внешнего провайдера (Supabase)
Менее "native" для Web3 сообщества
Требует дополнительный слой для Web3 интеграции
Возможные ограничения free tier Supabase при росте

Нейтральные¶

Необходимость обучения команды Supabase API
Стандартный UX, не выделяющийся в crypto пространстве

Связанные решения¶

Связано с: ADR-0007 (Database Schema Design) - для хранения пользовательских данных
Связано с: Integration-Only Architecture - аутентификация отделена от управления активами

Примечания¶

Supabase предоставляет готовые JWT токены с подписью
Поддержка multiple auth провайдеров: Google, Email, потенциально Apple/Facebook
Админская аутентификация использует тот же Supabase с role-based проверками
JWT токены содержат user_id, email и metadata для быстрого доступа
Опциональная привязка wallet адресов храниться в таблице user_wallets для future DeFi features
MFA опционально включается через Supabase Auth настройки