# 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:**
```json
{
  "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):**
```json
{
  "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):**
```json
{
  "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):**
```json
{
  "message": "Verification email sent. Please check your inbox."
}
```

or if already verified:

```json
{
  "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:
```bash
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.
