Yaltopia-Ticket-Admin/dev-docs/AUTHENTICATION.md

# Authentication Setup

## Overview
The admin dashboard now requires authentication before accessing any admin routes and follows industry-standard security practices.

## Security Status

### ✅ Frontend Security (Implemented)
- Protected routes with authentication check
- Role-based access control (ADMIN only)
- httpOnly cookie support (`withCredentials: true`)
- Automatic token refresh on expiration
- Centralized logout with backend call
- localStorage fallback for compatibility
- Secure error handling
- CSRF protection ready (via SameSite cookies)

### ⚠️ Backend Security (Required)
The backend MUST implement these critical security measures:
1. **httpOnly Cookies**: Store tokens in httpOnly cookies (not response body)
2. **Password Hashing**: Use bcrypt with salt rounds >= 12
3. **Rate Limiting**: Limit login attempts (5 per 15 minutes)
4. **HTTPS**: Enable HTTPS in production
5. **Token Refresh**: Implement refresh token endpoint
6. **Input Validation**: Sanitize and validate all inputs
7. **CORS**: Configure with specific origin and credentials
8. **Security Headers**: Use helmet.js for security headers
9. **Audit Logging**: Log all admin actions
10. **SQL Injection Prevention**: Use parameterized queries

See `SECURITY_CHECKLIST.md` for complete requirements.

## How It Works

### 1. Protected Routes
All admin routes are wrapped with `ProtectedRoute` component that checks for a valid access token.

### 2. Login Flow
- User visits any admin route without authentication → Redirected to `/login`
- User enters credentials → API validates and returns user data
- Backend sets httpOnly cookies (recommended) OR returns token (fallback)
- Token/cookies stored, user redirected to originally requested page

### 3. Token Management
- **Recommended**: Tokens stored in httpOnly cookies (XSS protection)
- **Fallback**: Access token in localStorage, automatically added to requests
- Token automatically sent with all API requests
- On 401 response, automatically attempts token refresh
- If refresh fails, user is logged out and redirected to login

### 4. Logout
- Calls backend `/auth/logout` to clear httpOnly cookies
- Clears localStorage (access_token, user)
- Redirects to `/login` page

## API Endpoints Required

### POST /auth/login
**Request:**
```json
{
  "email": "admin@example.com",
  "password": "password123"
}
```

**Response (Cookie-based - Recommended):**
```http
HTTP/1.1 200 OK
Set-Cookie: access_token=<jwt>; HttpOnly; Secure; SameSite=Strict; Path=/; Max-Age=900
Set-Cookie: refresh_token=<jwt>; HttpOnly; Secure; SameSite=Strict; Path=/auth/refresh; Max-Age=604800

{
  "user": {
    "id": "user-id",
    "email": "admin@example.com",
    "firstName": "Admin",
    "lastName": "User",
    "role": "ADMIN"
  }
}
```

**Response (localStorage fallback):**
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "user-id",
    "email": "admin@example.com",
    "role": "ADMIN"
  }
}
```

### POST /auth/logout
Clears httpOnly cookies and invalidates tokens.

### POST /auth/refresh
Refreshes expired access token using refresh token from cookie.

### GET /auth/me (Optional)
Returns current authenticated user for session validation.

## Files Modified/Created

### Created:
- `src/pages/login/index.tsx` - Login page with show/hide password
- `src/components/ProtectedRoute.tsx` - Route protection wrapper
- `dev-docs/AUTHENTICATION.md` - This documentation
- `dev-docs/API_STANDARDS.md` - Detailed API standards
- `dev-docs/SECURITY_CHECKLIST.md` - Complete security checklist

### Modified:
- `src/App.tsx` - Added login route and protected admin routes
- `src/layouts/app-shell.tsx` - User state management and logout
- `src/lib/api-client.ts` - Cookie support, token refresh, centralized auth

## Testing

1. Start the application
2. Navigate to any admin route (e.g., `/admin/dashboard`)
3. Should be redirected to `/login`
4. Enter valid admin credentials
5. Should be redirected back to the dashboard
6. Check browser DevTools > Application > Cookies (if backend uses cookies)
7. Click logout to clear session

## Security Comparison

| Feature | Current (Frontend) | With Backend Implementation |
|---------|-------------------|----------------------------|
| XSS Protection | ⚠️ Partial (localStorage) | ✅ Full (httpOnly cookies) |
| CSRF Protection | ✅ Ready | ✅ Full (SameSite cookies) |
| Token Refresh | ✅ Automatic | ✅ Automatic |
| Rate Limiting | ❌ None | ✅ Required |
| Password Hashing | ❌ Backend only | ✅ Required |
| Audit Logging | ❌ Backend only | ✅ Required |
| HTTPS | ⚠️ Production | ✅ Required |

## Production Deployment Checklist

### Frontend
- ✅ Build with production environment variables
- ✅ Enable HTTPS
- ✅ Configure CSP headers
- ✅ Set secure cookie flags

### Backend
- ⚠️ Implement httpOnly cookies
- ⚠️ Enable HTTPS with valid SSL certificate
- ⚠️ Configure CORS with specific origin
- ⚠️ Add rate limiting
- ⚠️ Implement password hashing
- ⚠️ Add security headers (helmet.js)
- ⚠️ Set up audit logging
- ⚠️ Configure environment variables
- ⚠️ Enable database encryption
- ⚠️ Set up monitoring and alerting

## Security Notes

### Current Implementation
- Frontend follows industry standards
- Supports both cookie-based and localStorage authentication
- Automatic token refresh prevents session interruption
- Centralized error handling and logout

### Backend Requirements
- **Critical**: Backend must implement security measures in `SECURITY_CHECKLIST.md`
- **Recommended**: Use httpOnly cookies instead of localStorage
- **Required**: Implement rate limiting, password hashing, HTTPS
- **Important**: Regular security audits and updates

## Support

For detailed security requirements, see:
- `dev-docs/SECURITY_CHECKLIST.md` - Complete security checklist
- `dev-docs/API_STANDARDS.md` - API implementation guide
- `dev-docs/DEPLOYMENT.md` - Deployment instructions