enviodeckauthenticationapi-s2f19c/README.md

# Enviodeck Authentication API

A FastAPI backend API for the Enviodeck mobile app with comprehensive user authentication features including phone number OTP, email/password, and third-party OAuth (Google/Apple) authentication.

## Features

- **Phone Number Authentication**: OTP-based login via SMS
- **Email/Password Authentication**: Traditional signup and login
- **Third-Party Authentication**: Google and Apple OAuth integration
- **JWT Token-based Authentication**: Secure session management
- **Rate Limiting**: Protection against OTP abuse
- **SQLite Database**: Lightweight, embedded database
- **API Documentation**: Auto-generated Swagger/OpenAPI docs

## Tech Stack

- **Framework**: FastAPI
- **Database**: SQLite with SQLAlchemy ORM
- **Authentication**: JWT tokens with python-jose
- **Password Hashing**: bcrypt via passlib
- **Rate Limiting**: slowapi
- **Migrations**: Alembic
- **Code Quality**: Ruff for linting

## API Endpoints

### Authentication
- `POST /auth/request-otp` - Request OTP for phone number
- `POST /auth/verify-otp` - Verify OTP and get access token
- `POST /auth/signup-email` - Sign up with email/password
- `POST /auth/login-email` - Login with email/password
- `POST /auth/login-google` - Login with Google OAuth
- `POST /auth/login-apple` - Login with Apple OAuth

### User Management
- `GET /user/me` - Get current user information

### System
- `GET /` - API information
- `GET /health` - Health check endpoint
- `GET /docs` - Swagger UI documentation
- `GET /redoc` - ReDoc documentation

## Installation & Setup

1. **Install Dependencies**
   ```bash
   pip install -r requirements.txt
   ```

2. **Environment Configuration**
   ```bash
   cp .env.example .env
   # Edit .env with your configuration values
   ```

3. **Database Setup**
   ```bash
   # Run migrations to create database tables
   alembic upgrade head
   ```

4. **Start the Server**
   ```bash
   uvicorn main:app --reload --host 0.0.0.0 --port 8000
   ```

## Environment Variables

The following environment variables need to be configured:

### Required
- `JWT_SECRET_KEY`: Secret key for JWT token generation (change in production!)

### Optional (for full functionality)
- `REDIS_URL`: Redis connection URL for OTP storage (defaults to mock implementation)
- `GOOGLE_CLIENT_ID`: Google OAuth client ID
- `GOOGLE_CLIENT_SECRET`: Google OAuth client secret
- `APPLE_CLIENT_ID`: Apple OAuth client ID
- `APPLE_CLIENT_SECRET`: Apple OAuth client secret
- `TWILIO_ACCOUNT_SID`: Twilio account SID for SMS
- `TWILIO_AUTH_TOKEN`: Twilio auth token
- `TWILIO_PHONE_NUMBER`: Twilio phone number for sending SMS

## Database Schema

### User Model
- `id`: Primary key
- `phone_number`: Unique phone number (nullable)
- `email`: Unique email address (nullable)
- `name`: User's name (optional)
- `password_hash`: Hashed password for email auth
- `auth_provider`: Enum (PHONE, EMAIL, GOOGLE, APPLE)
- `is_active`: User account status
- `is_verified`: Phone/email verification status
- `created_at`: Account creation timestamp
- `updated_at`: Last update timestamp

## API Usage Examples

### Phone Authentication Flow
```bash
# 1. Request OTP
curl -X POST "http://localhost:8000/auth/request-otp" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+1234567890"}'

# 2. Verify OTP
curl -X POST "http://localhost:8000/auth/verify-otp" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+1234567890", "otp": "123456"}'
```

### Email Authentication
```bash
# Sign up
curl -X POST "http://localhost:8000/auth/signup-email" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password123", "name": "John Doe"}'

# Login
curl -X POST "http://localhost:8000/auth/login-email" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password123"}'
```

### Accessing Protected Endpoints
```bash
# Get current user info
curl -X GET "http://localhost:8000/user/me" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

## Security Features

- **Password Hashing**: Secure bcrypt hashing for email authentication
- **JWT Tokens**: Stateless authentication with configurable expiration
- **Rate Limiting**: OTP requests limited to 5 per minute per IP
- **OTP Security**: 6-digit codes with 5-minute expiration and attempt limits
- **CORS**: Configured for cross-origin requests

## Development

### Code Quality
```bash
# Run linting and auto-fix
ruff check . --fix
ruff format .
```

### Database Migrations
```bash
# Create new migration
alembic revision --autogenerate -m "description"

# Apply migrations
alembic upgrade head

# Rollback migration
alembic downgrade -1
```

## Production Deployment

1. **Security**: Change the `JWT_SECRET_KEY` to a strong, random value
2. **Database**: Consider migrating to PostgreSQL for production
3. **Redis**: Set up Redis instance for OTP storage
4. **SMS Service**: Configure Twilio or alternative SMS provider
5. **OAuth**: Set up Google and Apple OAuth applications
6. **HTTPS**: Enable SSL/TLS encryption
7. **Rate Limiting**: Consider more sophisticated rate limiting strategies

## Testing

Access the interactive API documentation at:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

## License

This project is licensed under the MIT License.