motovaultpro/backend/src/features/auth

Auth Feature

User signup and email verification workflow using Auth0.

Overview

This feature provides API endpoints for user registration and email verification management. It integrates with Auth0 for authentication and manages user profiles in the local database.

Architecture

• API Layer: Controllers and routes for HTTP request/response handling
• Domain Layer: Business logic in AuthService
• Integration: Auth0 Management API client and UserProfileRepository

API Endpoints

POST /api/auth/signup (Public)

Create a new user account. Auth0 automatically sends verification email upon account creation.

Request:

{
  "email": "user@example.com",
  "password": "Password123"
}

Validation:

• Email: Valid email format required
• Password: Minimum 8 characters, at least one uppercase letter and one number

Response (201 Created):

{
  "userId": "auth0|123456",
  "email": "user@example.com",
  "message": "Account created successfully. Please check your email to verify your account."
}

Error Responses:

• 400: Invalid email or weak password
• 409: Email already exists
• 500: Auth0 API error or database error

---

GET /api/auth/verify-status (Protected)

Check email verification status. Updates local database if status changed in Auth0.

Authentication: Requires JWT

Response (200 OK):

{
  "emailVerified": true,
  "email": "user@example.com"
}

Error Responses:

• 401: Unauthorized (no JWT or invalid JWT)
• 500: Auth0 API error

---

POST /api/auth/resend-verification (Protected)

Resend email verification. Skips if email is already verified.

Authentication: Requires JWT

Response (200 OK):

{
  "message": "Verification email sent. Please check your inbox."
}

or if already verified:

{
  "message": "Email is already verified"
}

Error Responses:

• 401: Unauthorized (no JWT or invalid JWT)
• 500: Auth0 API error

Business Logic

Signup Flow

1. Validate email and password format
2. Create user in Auth0 via Management API
3. Auth0 automatically sends verification email
4. Create local user profile with emailVerified=false
5. Return success with user ID

Verify Status Flow

1. Extract Auth0 user ID from JWT
2. Query Auth0 Management API for email_verified status
3. Update local database if status changed
4. Return current verification status

Resend Verification Flow

1. Extract Auth0 user ID from JWT
2. Check if already verified (skip if true)
3. Call Auth0 Management API to resend verification email
4. Return success message

Integration Points

• Auth0 Management API: User creation, verification status, resend email
• User Profile Repository: Local user profile management
• Core Logger: Structured logging for all operations

Error Handling

• Validation errors (400): Invalid email format, weak password
• Conflict errors (409): Email already exists in Auth0
• Unauthorized (401): Missing or invalid JWT for protected endpoints
• Server errors (500): Auth0 API failures, database errors

Testing

Unit Tests

Location: tests/unit/auth.service.test.ts

Tests business logic with mocked Auth0 client and repository:

• User creation success and failure scenarios
• Email verification status retrieval and updates
• Resend verification logic

Integration Tests

Location: tests/integration/auth.integration.test.ts

Tests complete API workflows with test database:

• Signup with valid and invalid inputs
• Verification status checks
• Resend verification email

Run tests:

npm test -- features/auth

Dependencies

• Auth0 Management API client (core/auth/auth0-management.client.ts)
• UserProfileRepository (features/user-profile/data/user-profile.repository.ts)
• Core logger (core/logging/logger.ts)
• Database pool (core/config/database.ts)

Configuration

Auth0 Management API credentials are configured via environment variables:

• AUTH0_DOMAIN
• AUTH0_MANAGEMENT_CLIENT_ID
• AUTH0_MANAGEMENT_CLIENT_SECRET

See core/config/config-loader.ts for configuration details.