Note: This document is superseded by User Authentication Workflow (Detailed).

User Authentication

User accounts are intended for agency owners and managers. These accounts are global and are not scoped to a specific agency.

Registration Flow (Email + Password)

User registration is a two-step process to ensure email ownership.

1. Request Registration: The RegisterUserCommand is executed. A new User is created (marked isActive: false) and a verification code is generated.
2. Verify Email: The VerifyEmailUserCommand is executed with the received code. If valid, the User is activated and an initial Token Pair is returned.

sequenceDiagram
    participant Client as Frontend (Panel)
    participant API as UserAuthController
    participant Bus as CommandBus
    participant Handler as RegisterUserHandler
    participant DB as Identity Database
    participant Pub as IdentityPublisher

    Client->>API: POST /auth/user/register {email, password, ...}
    API->>Bus: Execute RegisterUserCommand
    Bus->>Handler: execute()
    Handler->>DB: Check if email exists
    Handler->>DB: Save User (isActive: false)
    Handler->>DB: Save Verification Token
    Handler->>Pub: publishUserRegistered()
    Pub-->>Client: Email with code (via EventBus)
    Handler-->>API: Result.ok
    API-->>Client: 200 OK (Verification code sent)

---

Login Flow (Email + Password)

Login is handled by NestJS Passport and the LocalUserStrategy.

sequenceDiagram
    participant Client as Frontend (Panel)
    participant Guard as LocalUserAuthGuard
    participant Strat as LocalUserStrategy
    participant API as UserAuthController
    participant Bus as CommandBus
    participant Handler as LoginUserHandler

    Client->>Guard: POST /auth/user/login {email, password}
    Guard->>Strat: validate(email, password)
    Strat->>Strat: Check password (HashingService)
    Strat-->>Guard: return User entity
    Guard->>API: req.user = User
    API->>Bus: Execute LoginUserCommand(User)
    Bus->>Handler: execute()
    Handler-->>API: TokenPair {accessToken, refreshToken}
    API-->>Client: 200 OK (Tokens)

---

Google OAuth Flow

Users can register or log in using Google. We use a standardized OAuth 2.0 flow.

1. Redirect: User is sent to Google's consent screen via UserAuthController.googleRedirect.
2. Callback: Google redirects back to UserAuthController.googleCallback with a profile.
3. Command Execution: GoogleLoginUserCommand handles account linking or new account creation.

sequenceDiagram
    participant User as User Browser
    participant API as UserAuthController
    participant Guard as GoogleUserAuthGuard
    participant Strat as GoogleUserStrategy
    participant Bus as CommandBus
    participant Handler as GoogleLoginUserHandler

    User->>API: GET /auth/user/google
    API->>Guard: canActivate()
    Guard->>User: Redirect to Google
    User->>User: Consent & Authenticate
    User->>API: GET /auth/user/google/callback?code=...
    API->>Guard: canActivate()
    Guard->>Strat: validate(...)
    Strat-->>Guard: return GoogleProfile
    Guard->>API: req.user = GoogleProfile
    API->>Bus: Execute GoogleLoginUserCommand(profile)
    Bus->>Handler: execute()
    Handler-->>API: TokenPair
    API-->>User: 200 OK (Tokens)