Authentication Flow (Integration-Only Architecture)¶

Email-first аутентификация через Supabase Auth в Integration-Only архитектуре.

Дата обновления: 2025-11-14 Архитектура: Email-First Authentication (Integration-Only)

Email-First Supabase Authentication Flow¶

sequenceDiagram
    participant User as 👤 User
    participant Frontend as 🖥️ Frontend App
    participant Supabase as 🔐 Supabase Auth
    participant API as 🌐 Backend API
    participant AuthService as 🔑 Auth Service
    participant Database as 🗄️ PostgreSQL

    Note over User,Database: Google OAuth Authentication (Primary)

    User->>Frontend: Clicks "Sign in with Google"
    Frontend->>Supabase: signInWithOAuth({provider: 'google'})
    Supabase->>User: Redirect to Google OAuth
    User->>Supabase: Complete Google authentication
    Supabase->>Frontend: Return Supabase JWT + user metadata

    Note over User,Database: Backend JWT Generation

    Frontend->>API: POST /api/auth/supabase/login<br/>{supabase_token}
    API->>AuthService: ValidateSupabaseJWT(token)
    AuthService->>Supabase: Validate JWT via JWKS

    alt Supabase JWT Valid
        AuthService->>Database: Query user by email
        Database->>AuthService: User data or null

        alt User Exists
            AuthService->>AuthService: Generate backend JWT (email-based)
            AuthService->>API: Return backend JWT + user data
            API->>Frontend: HTTP 200 + backend JWT
        else User Not Exists
            AuthService->>Database: Create new user from email
            Database->>AuthService: New user created
            AuthService->>AuthService: Generate backend JWT (email-based)
            AuthService->>API: Return backend JWT + user data
            API->>Frontend: HTTP 201 + backend JWT
        end

        Frontend->>Frontend: Store backend JWT in localStorage
        Frontend->>User: Redirect to dashboard

    else Supabase JWT Invalid
        AuthService->>API: Return authentication error
        API->>Frontend: HTTP 401 Unauthorized
        Frontend->>User: Show error message
    end

    Note over User,Database: Alternative Authentication Methods

    alt Email/Password Authentication
        User->>Frontend: Enter email/password
        Frontend->>Supabase: signInWithPassword({email, password})
        Supabase->>Frontend: Return Supabase JWT
    else Magic Link Authentication
        User->>Frontend: Enter email for magic link
        Frontend->>Supabase: signInWithOtp({email})
        Supabase->>User: Send magic link email
        User->>Supabase: Click magic link
        Supabase->>Frontend: Return Supabase JWT
    end

    Note over User,Database: Logout Process

    User->>Frontend: Clicks "Logout"
    Frontend->>Supabase: signOut()
    Frontend->>API: POST /api/auth/logout (optional blacklisting)
    Frontend->>Frontend: Clear localStorage
    Frontend->>User: Redirect to login

JWT Token Structure (Email-First Integration-Only)¶

graph TB
    subgraph "Backend JWT Token (Integration-Only)"
        H[Header<br/>Algorithm: HS256]
        P[Payload<br/>user_id<br/>email<br/>full_name<br/>iat<br/>exp<br/>❌ NO wallet_address]
        S[Signature<br/>HMAC SHA256]
    end

    subgraph "Supabase JWT (Initial)"
        SH[Supabase Header<br/>Algorithm: RS256]
        SP[Supabase Payload<br/>sub (user_id)<br/>email<br/>email_verified<br/>user_metadata]
        SS[Supabase Signature<br/>RSA SHA256]
    end

    subgraph "Token Validation Process"
        API[🌐 API Request]
        MW[🔐 Auth Middleware]
        JWT_CHECK[✅ Backend JWT Validation]
        USER_LOOKUP[👤 User Lookup by Email]
        PROCEED[✅ Proceed to Handler]
    end

    API --> MW
    MW --> JWT_CHECK
    JWT_CHECK --> USER_LOOKUP
    USER_LOOKUP --> PROCEED

    classDef jwt fill:#FFE066,stroke:#D4AC0D,color:#000
    classDef supabase fill:#3ECF8E,stroke:#2ECC71,color:#000
    classDef process fill:#85C1E9,stroke:#3498DB,color:#000

    class H,P,S jwt
    class SH,SP,SS supabase
    class API,MW,JWT_CHECK,USER_LOOKUP,PROCEED process

Database Schema (Email-First Integration-Only)¶

erDiagram
    USERS {
        uuid id PK
        string email
        string full_name
        string status
        timestamp created_at
        timestamp updated_at
    }

    SUPABASE_USERS {
        uuid id PK
        string email
        string provider
        string provider_id
        jsonb user_metadata
        timestamp created_at
    }

    USER_SESSIONS {
        uuid id PK
        uuid user_id FK
        string session_token
        timestamp expires_at
        timestamp created_at
    }

    USERS ||--o{ USER_SESSIONS : has

    %% Note: Wallet addresses managed by Crypto2B/Fordefi APIs
    %% Note: No direct wallet_address storage in Integration-Only

Security Implementation (Integration-Only)¶

Security Measures (Email-First)¶

Supabase Auth Validation - Enterprise-grade JWT verification via JWKS
Multi-Factor Authentication - Optional MFA through Supabase
OAuth2 Security - Google OAuth with proper scopes and validation
Rate Limiting - IP-based brute force protection
Session Management - HttpOnly cookies with secure flags
HTTPS Enforcement - TLS 1.3 for all authentication flows

Integration-Only Security Benefits¶

No Private Key Management - All custody through Fordefi enterprise
Reduced Attack Surface - No wallet signatures or blockchain operations
Enterprise Compliance - Supabase provides SOC 2 Type II compliance
Simplified Authentication - Email-first reduces user friction
Centralized Security - Single auth provider for better monitoring

API Endpoints (Integration-Only)¶

Authentication Endpoints:

POST /api/auth/supabase/login - Supabase JWT validation and backend JWT generation
POST /api/auth/supabase/register - New user registration through Supabase
POST /api/auth/logout - Logout and session cleanup
GET /api/auth/me - Get current user information

Admin Endpoints:

POST /api/admin/auth/login - Admin email authentication through Supabase
GET /api/admin/auth/verify - Verify admin permissions

Integration Endpoints:

POST /api/webhooks/crypto2b - Deposit notifications from Crypto2B
POST /api/webhooks/fordefi - Withdrawal notifications from Fordefi

Implementation Details (Integration-Only)¶

Supabase JWT Validation¶

// From: backend/auth/service/supabase_auth.go
func ValidateSupabaseJWT(token string) (*SupabaseUserInfo, error) {
    // Get Supabase JWKS
    jwks, err := getSupabaseJWKS()
    if err != nil {
        return nil, err
    }

    // Validate JWT signature
    claims, err := jwt.ParseWithClaims(token, &SupabaseClaims{}, func(token *jwt.Token) (interface{}, error) {
        return jwks.GetKey(token.Header["kid"].(string))
    })

    if err != nil {
        return nil, err
    }

    return &SupabaseUserInfo{
        Email: claims.Email,
        FullName: claims.UserMetadata.FullName,
    }, nil
}

Backend JWT Generation (Email-First)¶

// From: backend/auth/service/jwt_service.go
func GenerateJWTForUser(userData UserData, cfg config.ConfigInterface) (string, error) {
    claims := jwt.MapClaims{
        "user_id":   userData.UserID,
        "email":     userData.Email,
        "full_name": userData.FullName,
        "iat":       time.Now().Unix(),
        "exp":       time.Now().Add(time.Duration(cfg.GetJWTExpirationHours()) * time.Hour).Unix(),
        // ❌ NO wallet_address - Integration-Only architecture
    }

    token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
    return token.SignedString([]byte(cfg.GetJWTSecret()))
}

Session Management¶

// Session cleanup for logout
func (s *AuthService) CreateSession(userID uuid.UUID, token string) error {
    session := &models.UserSession{
        UserID:       userID,
        SessionToken: token,
        ExpiresAt:    time.Now().Add(24 * time.Hour),
    }
    return s.sessionRepo.Create(session)
}

Security Assessment (Integration-Only)¶

Strengths¶

Enterprise Authentication: Supabase Auth with SOC 2 Type II compliance
Multi-Factor Security: Optional MFA through enterprise provider
OAuth2 Standards: Google OAuth with proper scope validation
Reduced Attack Surface: No private key management or wallet operations
Centralized Monitoring: Single auth provider for better security oversight
Email-First UX: Familiar authentication flow for mass adoption

Integration-Only Benefits¶

No Private Key Risk: All custody through Fordefi enterprise security
Simplified Security Model: Email-first reduces complexity without sacrificing security
Enterprise Compliance: Built-in regulatory compliance through providers
Scalable Architecture: Proven enterprise infrastructure
Reduced Development Risk: Focus on business logic, not security infrastructure

Trade-offs Accepted¶

Provider Dependency: Reliance on Supabase Auth service availability
Limited Customization: Bound by Supabase Auth features and limitations
API Integration Complexity: Multiple provider coordination for complete flows

Integration Roadmap¶

Phase 1: Enhanced User Experience¶

Implement SSO (Single Sign-On) with corporate providers
Add biometric authentication support
Improve onboarding flow for non-tech users

Phase 2: Advanced Security Features¶

Implement device fingerprinting
Add suspicious activity monitoring
Enhance session management with device tracking

Phase 3: Enterprise Features¶

SAML integration for enterprise customers
Advanced audit logging and compliance reporting
White-label authentication for partners

Conclusion¶

Current Integration-Only authentication system is enterprise-ready and secure for pension fund management. The implementation follows Integration-Only principles that prioritize:

Security First - Enterprise-grade authentication without private key risks
User Experience - Email-first approach for mass market adoption
Regulatory Compliance - Built-in compliance through enterprise providers
Operational Efficiency - No private key or wallet management overhead
Scalability - Proven enterprise infrastructure for growth

The system eliminates wallet-related security risks while maintaining enterprise-grade authentication standards.

Status: ✅ Integration-Only Architecture Compliant