AeThex-Engine-Core/services/auth-service/README.md

# AeThex Authentication Service

Cloud authentication service for AeThex Engine.

## Features

- ✅ Email/Password authentication
- ✅ JWT token-based sessions
- ✅ Refresh token rotation
- ✅ OAuth (Google, GitHub)
- ✅ Password reset flow
- ✅ Rate limiting
- ✅ Security headers (Helmet)
- ✅ Input validation

## Quick Start

### Prerequisites

- Node.js 18+
- Docker & Docker Compose
- PostgreSQL 16 (or use Docker)

### Setup

```bash
cd services/auth-service

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env

# Edit .env with your configuration
nano .env

# Start database
docker-compose up -d postgres

# Run migrations
npm run migrate

# Start development server
npm run dev
```

The service will be available at `http://localhost:3000`

### Using Docker Compose (Recommended)

```bash
# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down
```

## API Endpoints

### Authentication

#### Register User
```http
POST /api/v1/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "username": "johndoe",
  "password": "SecurePass123"
}
```

**Response:**
```json
{
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "username": "johndoe"
  },
  "accessToken": "jwt_token",
  "refreshToken": "refresh_token"
}
```

#### Login
```http
POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePass123"
}
```

#### Get Current User
```http
GET /api/v1/auth/me
Authorization: Bearer {access_token}
```

#### Refresh Token
```http
POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refreshToken": "your_refresh_token"
}
```

#### Logout
```http
POST /api/v1/auth/logout
Authorization: Bearer {access_token}
```

### OAuth

#### Google OAuth
```http
GET /api/v1/auth/google
```
Redirects to Google OAuth consent screen.

#### GitHub OAuth
```http
GET /api/v1/auth/github
```
Redirects to GitHub OAuth consent screen.

### Password Reset

#### Request Password Reset
```http
POST /api/v1/auth/forgot-password
Content-Type: application/json

{
  "email": "user@example.com"
}
```

#### Reset Password
```http
POST /api/v1/auth/reset-password
Content-Type: application/json

{
  "token": "reset_token_from_email",
  "password": "NewSecurePass123"
}
```

## Engine Integration

### GDScript Example

```gdscript
extends Node

func _ready():
    # Initialize cloud service
    AeThexCloud.auth.set_api_url("http://localhost:3000")
    
    # Register new user
    var result = await AeThexCloud.auth.register_async(
        "user@example.com",
        "username",
        "SecurePass123"
    )
    
    if result.success:
        print("Registered! Token: ", result.access_token)
    else:
        print("Error: ", result.error)
    
    # Login
    result = await AeThexCloud.auth.login_async(
        "user@example.com",
        "SecurePass123"
    )
    
    if result.success:
        print("Logged in as: ", result.user.username)
        # Token is automatically stored
    
    # Check if logged in
    if AeThexCloud.auth.is_logged_in():
        var user = AeThexCloud.auth.get_current_user()
        print("Welcome back, ", user.username)
```

## Development

### Project Structure

```
src/
├── index.ts              # Application entry point
├── routes/
│   ├── auth.ts          # Auth endpoints
│   └── user.ts          # User management
├── controllers/
│   ├── authController.ts
│   └── userController.ts
├── middleware/
│   ├── authenticateToken.ts
│   ├── validateRequest.ts
│   └── errorHandler.ts
├── models/
│   └── User.ts          # User model (Prisma)
├── services/
│   ├── tokenService.ts  # JWT handling
│   └── emailService.ts  # Email sending
└── utils/
    ├── logger.ts
    └── validators.ts
```

### Running Tests

```bash
npm test
```

### Database Migrations

```bash
# Create new migration
npx prisma migrate dev --name add_user_table

# Apply migrations
npm run migrate

# Reset database
npx prisma migrate reset
```

## Security Considerations

1. **JWT Secrets**: Change `JWT_SECRET` and `REFRESH_TOKEN_SECRET` in production
2. **Database Password**: Use strong password for PostgreSQL
3. **HTTPS**: Always use HTTPS in production
4. **Rate Limiting**: Configured for 100 requests per 15 minutes
5. **OAuth Secrets**: Keep OAuth client secrets secure
6. **Password Policy**: Enforces 8+ chars with uppercase, lowercase, and numbers

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `PORT` | Server port | 3000 |
| `DATABASE_URL` | PostgreSQL connection string | - |
| `JWT_SECRET` | Secret for access tokens | - |
| `JWT_EXPIRES_IN` | Token expiration | 7d |
| `REFRESH_TOKEN_SECRET` | Secret for refresh tokens | - |
| `GOOGLE_CLIENT_ID` | Google OAuth client ID | - |
| `GOOGLE_CLIENT_SECRET` | Google OAuth secret | - |
| `GITHUB_CLIENT_ID` | GitHub OAuth client ID | - |
| `GITHUB_CLIENT_SECRET` | GitHub OAuth secret | - |
| `FRONTEND_URL` | Frontend URL for CORS | http://localhost:9002 |

## Production Deployment

### Docker

```bash
# Build image
docker build -t aethex-auth-service .

# Run container
docker run -d \
  -p 3000:3000 \
  -e DATABASE_URL=postgresql://... \
  -e JWT_SECRET=your-secret \
  aethex-auth-service
```

### Kubernetes

```bash
kubectl apply -f k8s/deployment.yml
kubectl apply -f k8s/service.yml
```

## Monitoring

Health check endpoint:
```http
GET /health
```

Response:
```json
{
  "status": "healthy",
  "service": "aethex-auth-service",
  "timestamp": "2026-02-24T10:30:00.000Z"
}
```

## License

MIT License - See LICENSE file for details

## Support

- Documentation: https://docs.aethex.dev
- Issues: https://github.com/AeThex-LABS/AeThex-Engine-Core/issues
- Discord: https://discord.gg/aethex