Rustelo/info/env_config.md

# Environment Configuration

This document describes the environment variables needed for the authentication system.

## Required Environment Variables

### Database Configuration
```bash
DATABASE_URL=postgres://username:password@localhost:5432/database_name
```

### JWT Configuration
```bash
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
JWT_ISSUER=rustelo-auth
JWT_ACCESS_TOKEN_EXPIRES_IN=15  # minutes
JWT_REFRESH_TOKEN_EXPIRES_IN=7  # days
```

### Password Security
```bash
# Argon2 uses secure defaults, no configuration needed
```

### OAuth2 Configuration

#### Google OAuth
```bash
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
```

#### GitHub OAuth
```bash
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret
```

#### Discord OAuth
```bash
DISCORD_CLIENT_ID=your-discord-client-id
DISCORD_CLIENT_SECRET=your-discord-client-secret
```

#### Microsoft OAuth
```bash
MICROSOFT_CLIENT_ID=your-microsoft-client-id
MICROSOFT_CLIENT_SECRET=your-microsoft-client-secret
MICROSOFT_TENANT_ID=common  # or your specific tenant ID
```

### OAuth Redirect URLs
```bash
OAUTH_REDIRECT_BASE_URL=http://localhost:3030/api/auth/oauth/callback
```

## OAuth Provider Setup

### Google OAuth Setup
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select an existing one
3. Enable the Google+ API
4. Create OAuth 2.0 credentials
5. Add authorized redirect URIs:
   - `http://localhost:3030/api/auth/oauth/callback/google` (development)
   - `https://yourdomain.com/api/auth/oauth/callback/google` (production)

### GitHub OAuth Setup
1. Go to GitHub Settings > Developer settings > OAuth Apps
2. Create a new OAuth App
3. Set Authorization callback URL:
   - `http://localhost:3030/api/auth/oauth/callback/github` (development)
   - `https://yourdomain.com/api/auth/oauth/callback/github` (production)

### Discord OAuth Setup
1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
2. Create a new application
3. Go to OAuth2 settings
4. Add redirect URIs:
   - `http://localhost:3030/api/auth/oauth/callback/discord` (development)
   - `https://yourdomain.com/api/auth/oauth/callback/discord` (production)

### Microsoft OAuth Setup
1. Go to [Azure Portal](https://portal.azure.com/)
2. Register a new application in Azure AD
3. Configure authentication platform (Web)
4. Add redirect URIs:
   - `http://localhost:3030/api/auth/oauth/callback/microsoft` (development)
   - `https://yourdomain.com/api/auth/oauth/callback/microsoft` (production)

## Database Setup

### PostgreSQL Setup
1. Install PostgreSQL
2. Create a database for your application
3. Run the application - tables will be created automatically

### Example Database Creation
```sql
CREATE DATABASE rustelo_dev;
CREATE USER rustelo_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE rustelo_dev TO rustelo_user;
```

## Security Considerations

### Production Environment
- Use strong, unique JWT secrets
- Use HTTPS for all OAuth redirect URLs
- Set secure cookie flags
- Use environment-specific database credentials
- Enable rate limiting
- Use secure password hashing costs (12 or higher)

### Development Environment
- Use different credentials than production
- OAuth redirect URLs should point to localhost
- JWT secrets can be simpler for development
- Database can be local

## Sample .env File

```bash
# Database
DATABASE_URL=postgres://rustelo_user:password@localhost:5432/rustelo_dev

# JWT
JWT_SECRET=development-secret-change-in-production
JWT_ISSUER=rustelo-auth
JWT_ACCESS_TOKEN_EXPIRES_IN=15
JWT_REFRESH_TOKEN_EXPIRES_IN=7

# Password
# Argon2 uses secure defaults, no configuration needed

# OAuth Base URL
OAUTH_REDIRECT_BASE_URL=http://localhost:3030/api/auth/oauth/callback

# Google OAuth (optional)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# GitHub OAuth (optional)
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

# Discord OAuth (optional)
DISCORD_CLIENT_ID=your-discord-client-id
DISCORD_CLIENT_SECRET=your-discord-client-secret

# Microsoft OAuth (optional)
MICROSOFT_CLIENT_ID=your-microsoft-client-id
MICROSOFT_CLIENT_SECRET=your-microsoft-client-secret
MICROSOFT_TENANT_ID=common
```

## API Endpoints

### Authentication Endpoints
- `POST /api/auth/register` - Register new user
- `POST /api/auth/login` - Login with email/password
- `POST /api/auth/logout` - Logout current user
- `POST /api/auth/refresh` - Refresh access token
- `GET /api/auth/profile` - Get current user profile
- `PUT /api/auth/profile` - Update user profile
- `POST /api/auth/change-password` - Change password

### OAuth Endpoints
- `GET /api/auth/oauth/providers` - Get available OAuth providers
- `GET /api/auth/oauth/:provider/authorize` - Get OAuth authorization URL
- `GET /api/auth/oauth/:provider/callback` - Handle OAuth callback

### Password Reset Endpoints
- `POST /api/auth/password-reset/request` - Request password reset
- `POST /api/auth/password-reset/confirm` - Confirm password reset

### Admin Endpoints
- `GET /api/auth/admin/users/:id` - Get user by ID
- `POST /api/auth/admin/users/:id/verify-email` - Verify user email
- `POST /api/auth/admin/cleanup` - Clean up expired tokens/sessions

## Usage Examples

### Register User
```bash
curl -X POST http://localhost:3030/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "username": "newuser",
    "password": "SecurePass123!",
    "display_name": "New User"
  }'
```

### Login
```bash
curl -X POST http://localhost:3030/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!",
    "remember_me": true
  }'
```

### Get Profile (with JWT token)
```bash
curl -X GET http://localhost:3030/api/auth/profile \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

## Troubleshooting

### Common Issues
1. **Database connection failed**: Check DATABASE_URL and ensure PostgreSQL is running
2. **OAuth callback errors**: Verify redirect URLs match exactly in OAuth provider settings
3. **JWT token invalid**: Check JWT_SECRET and ensure it's the same across restarts
4. **Password validation fails**: Review password strength requirements

### Logging
The system logs authentication events. Check server logs for detailed error messages.