npm package: @paons/auth-system
Description: Reusable authentication system for FastAPI and React
Author: Locali Team
Latest version: 1.0.2

# FastAPI-React Authentication Package

A robust, type-safe authentication system for FastAPI backend and React/TypeScript frontend applications.

## Features

- User registration with email verification
- JWT-based authentication
- OAuth2 password flow
- TypeScript types for all responses
- Error handling for all edge cases
- Email verification system
- Password reset functionality

## Backend Setup

1. Install dependencies:
```bash
pip install fastapi[all] sqlalchemy passlib[bcrypt] python-jose[cryptography] python-multipart
```

2. Copy the backend module:
```python
from auth_system import setup_auth

# In your FastAPI app
app = FastAPI()
auth_router = setup_auth(
    database_url="your_database_url",
    secret_key="your_secret_key",
    email_config={
        "smtp_host": "smtp.gmail.com",
        "smtp_port": 587,
        "smtp_user": "your_email",
        "smtp_password": "your_app_password"
    }
)
app.include_router(auth_router, prefix="/api/v1/auth")
```

## Frontend Setup

1. Install dependencies:
```bash
npm install axios @types/axios
```

2. Import and use the auth client:
```typescript
import { createAuthClient } from 'auth-system'

const auth = createAuthClient({
    baseUrl: 'http://localhost:8000/api/v1',
    onTokenChange: (token) => {
        // Handle token storage
        localStorage.setItem('token', token)
    }
})

// Use the auth client
await auth.register(email, password, fullName)
await auth.login(email, password)
await auth.verifyEmail(token, email)
```

## Security Features

- Password hashing with bcrypt
- JWT token with configurable expiration
- CSRF protection
- Rate limiting
- Email verification required before login
- Secure password reset flow

## Error Handling

All errors are properly typed and handled:
- Network errors
- Validation errors
- Authentication errors
- Server errors

## Configuration Options

### Backend
- Database configuration
- JWT settings
- Email settings
- Password requirements
- Rate limiting options

### Frontend
- Base URL
- Token storage
- Request timeouts
- Custom error handling

## Environment Variables

The authentication package requires certain environment variables to be set. Create a `.env` file in your project root with the following variables:

### Email Configuration
```env
# Email Configuration (Gmail SMTP)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_EMAIL=your-email@gmail.com
SMTP_PASSWORD=your-app-specific-password
SMTP_FROM_NAME=Your App Name Support
```

> **Note**: For Gmail, you'll need to use an App Password instead of your regular password. You can generate one in your Google Account settings under Security > 2-Step Verification > App passwords.

### Security Settings
```env
SECRET_KEY=your-super-secret-key-replace-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
```

### Frontend Configuration
```env
FRONTEND_URL=http://localhost:3000
```

## Best Practices

1. Always store sensitive information in environment variables
2. Use HTTPS in production
3. Implement rate limiting
4. Set appropriate token expiration times
5. Use secure password requirements
6. Implement proper logging

## Common Issues and Solutions

1. CORS issues:
   - Ensure CORS settings match your frontend URL
   - Add all necessary CORS headers

2. Email verification:
   - Test email configuration thoroughly
   - Handle email sending failures gracefully

3. Token handling:
   - Store tokens securely
   - Implement proper token refresh
   - Clear tokens on logout

4. Form data:
   - Use proper content types
   - Handle validation errors correctly

## Testing

Includes comprehensive tests for:
- User registration
- Login/logout
- Email verification
- Password reset
- Error cases
- Token handling