feat: implement complete JWT authentication system with enhanced security

Implement a production-ready JWT authentication system with comprehensive
security features, rate limiting, and enhanced password validation.

## Core Authentication Features
- User registration and login with JWT tokens
- Access tokens (15-minute expiration) and refresh tokens (7-day expiration)
- Secure token refresh mechanism without re-authentication
- User profile endpoint with authentication middleware

## Security Enhancements
- Enhanced password validation requiring uppercase, lowercase, digits, and special characters
- Secure bcrypt password hashing with proper salt rounds
- JWT token validation with issuer and audience verification
- Rate limiting on authentication endpoints (5 reg/hour, 10 login/hour, 100 refresh/hour)
- Proper error handling without information leakage

## Technical Implementation
- JWT service with token generation, validation, and refresh logic
- Authentication service with business logic separation
- Authentication middleware for route protection
- Rate limiting middleware with in-memory store
- Structured error responses and logging

## Configuration & Documentation
- JWT configuration externalized to environment variables
- Updated .env.example with JWT settings and production warnings
- Comprehensive API documentation for all auth endpoints
- Complete test coverage for JWT and authentication services

## API Endpoints Added
- POST /api/v1/auth/register - User registration
- POST /api/v1/auth/login - User authentication
- POST /api/v1/auth/refresh - Token refresh
- POST /api/v1/auth/logout - User logout
- GET /api/v1/auth/me - Get current user (protected)

## Dependencies Added
- github.com/golang-jwt/jwt/v5 for JWT token handling
- Enhanced golang.org/x/crypto usage for secure password hashing

Resolves #4

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: starbops

.env.example

@@ -18,4 +18,12 @@ LOG_FORMAT=json
 # CORS Configuration
 CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173
 CORS_ALLOWED_METHODS=GET,POST,PUT,DELETE,OPTIONS
-CORS_ALLOWED_HEADERS=Content-Type,Authorization,X-Request-ID
+CORS_ALLOWED_HEADERS=Content-Type,Authorization,X-Request-ID
+
+# JWT Configuration
+# IMPORTANT: Change these values in production!
+JWT_SECRET_KEY=your-secret-key-change-in-production-256-bits-minimum
+JWT_ACCESS_TOKEN_DURATION=15m
+JWT_REFRESH_TOKEN_DURATION=168h
+JWT_ISSUER=voidrunner
+JWT_AUDIENCE=voidrunner-api

api

@@ -12,6 +12,7 @@ import (
 
 	"github.com/gin-gonic/gin"
 	"github.com/voidrunnerhq/voidrunner/internal/api/routes"
+	"github.com/voidrunnerhq/voidrunner/internal/auth"
 	"github.com/voidrunnerhq/voidrunner/internal/config"
 	"github.com/voidrunnerhq/voidrunner/internal/database"
 	"github.com/voidrunnerhq/voidrunner/pkg/logger"
@@ -60,12 +61,18 @@ func main() {
 
 	log.Info("database initialized successfully")
 
+	// Initialize JWT service
+	jwtService := auth.NewJWTService(&cfg.JWT)
+
+	// Initialize authentication service
+	authService := auth.NewService(repos.Users, jwtService, log.Logger, cfg)
+
 	if cfg.IsProduction() {
 		gin.SetMode(gin.ReleaseMode)
 	}
 
 	router := gin.New()
-	routes.Setup(router, cfg, log, repos)
+	routes.Setup(router, cfg, log, repos, authService)
 
 	srv := &http.Server{
 		Addr:    fmt.Sprintf("%s:%s", cfg.Server.Host, cfg.Server.Port),

cmd/api/main.go

@@ -0,0 +1,256 @@
+# Authentication API Documentation
+
+This document describes the authentication endpoints available in the VoidRunner API.
+
+## Overview
+
+The VoidRunner API uses JWT (JSON Web Tokens) for authentication. The authentication system supports:
+
+- User registration with email and password
+- User login with email and password  
+- JWT access token (15-minute expiration)
+- JWT refresh token (7-day expiration)
+- Token refresh without re-authentication
+- Rate limiting on auth endpoints
+
+## Base URL
+
+```
+http://localhost:8080/api/v1
+```
+
+## Authentication Endpoints
+
+### 1. User Registration
+
+**Endpoint:** `POST /auth/register`
+
+**Rate Limit:** 5 requests per hour per IP
+
+**Request Body:**
+```json
+{
+  "email": "user@example.com",
+  "password": "StrongPassword123!"
+}
+```
+
+**Password Requirements:**
+- Minimum 8 characters
+- Maximum 128 characters
+- At least one uppercase letter
+- At least one lowercase letter
+- At least one digit
+- At least one special character
+
+**Success Response (201):**
+```json
+{
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "token_type": "Bearer",
+  "expires_in": 900,
+  "user": {
+    "id": "123e4567-e89b-12d3-a456-426614174000",
+    "email": "user@example.com",
+    "created_at": "2023-07-04T12:00:00Z",
+    "updated_at": "2023-07-04T12:00:00Z"
+  }
+}
+```
+
+**Error Responses:**
+- `400 Bad Request`: Invalid input format or validation errors
+- `409 Conflict`: User with email already exists
+- `429 Too Many Requests`: Rate limit exceeded
+
+### 2. User Login
+
+**Endpoint:** `POST /auth/login`
+
+**Rate Limit:** 10 requests per hour per IP
+
+**Request Body:**
+```json
+{
+  "email": "user@example.com",
+  "password": "StrongPassword123!"
+}
+```
+
+**Success Response (200):**
+```json
+{
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "token_type": "Bearer",
+  "expires_in": 900,
+  "user": {
+    "id": "123e4567-e89b-12d3-a456-426614174000",
+    "email": "user@example.com",
+    "created_at": "2023-07-04T12:00:00Z",
+    "updated_at": "2023-07-04T12:00:00Z"
+  }
+}
+```
+
+**Error Responses:**
+- `400 Bad Request`: Invalid input format
+- `401 Unauthorized`: Invalid email or password
+- `429 Too Many Requests`: Rate limit exceeded
+
+### 3. Token Refresh
+
+**Endpoint:** `POST /auth/refresh`
+
+**Rate Limit:** 100 requests per hour per IP
+
+**Request Body:**
+```json
+{
+  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+}
+```
+
+**Success Response (200):**
+```json
+{
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "token_type": "Bearer",
+  "expires_in": 900,
+  "user": {
+    "id": "123e4567-e89b-12d3-a456-426614174000",
+    "email": "user@example.com",
+    "created_at": "2023-07-04T12:00:00Z",
+    "updated_at": "2023-07-04T12:00:00Z"
+  }
+}
+```
+
+**Error Responses:**
+- `400 Bad Request`: Invalid request format
+- `401 Unauthorized`: Invalid or expired refresh token
+- `429 Too Many Requests`: Rate limit exceeded
+
+### 4. User Logout
+
+**Endpoint:** `POST /auth/logout`
+
+**Description:** In a JWT system, logout is typically handled client-side by removing tokens from storage. This endpoint returns a success message.
+
+**Success Response (200):**
+```json
+{
+  "message": "Successfully logged out"
+}
+```
+
+### 5. Get Current User
+
+**Endpoint:** `GET /auth/me`
+
+**Authentication:** Required (Bearer token)
+
+**Headers:**
+```
+Authorization: Bearer <access_token>
+```
+
+**Success Response (200):**
+```json
+{
+  "user": {
+    "id": "123e4567-e89b-12d3-a456-426614174000",
+    "email": "user@example.com",
+    "created_at": "2023-07-04T12:00:00Z",
+    "updated_at": "2023-07-04T12:00:00Z"
+  }
+}
+```
+
+**Error Responses:**
+- `401 Unauthorized`: Missing, invalid, or expired token
+
+## Authentication Flow
+
+### Initial Authentication
+1. User registers with `POST /auth/register` or logs in with `POST /auth/login`
+2. Server returns access token (15-minute expiration) and refresh token (7-day expiration)
+3. Client stores both tokens securely
+
+### Making Authenticated Requests
+1. Include access token in Authorization header: `Authorization: Bearer <access_token>`
+2. If access token is expired, use refresh token to get new tokens
+3. Update stored tokens with new values
+
+### Token Refresh
+1. When access token expires, call `POST /auth/refresh` with refresh token
+2. Server returns new access token and refresh token
+3. Client updates stored tokens
+
+### Logout
+1. Call `POST /auth/logout` (optional, for logging purposes)
+2. Remove tokens from client storage
+
+## Error Handling
+
+All endpoints return errors in the following format:
+
+```json
+{
+  "error": "Error message description",
+  "details": "Additional error details (optional)"
+}
+```
+
+Common HTTP status codes:
+- `400 Bad Request`: Invalid input or request format
+- `401 Unauthorized`: Authentication required or failed
+- `403 Forbidden`: Access denied
+- `409 Conflict`: Resource already exists
+- `429 Too Many Requests`: Rate limit exceeded
+- `500 Internal Server Error`: Server error
+
+## Rate Limiting
+
+The authentication endpoints have the following rate limits:
+
+| Endpoint | Limit | Window |
+|----------|-------|--------|
+| `/auth/register` | 5 requests | 1 hour |
+| `/auth/login` | 10 requests | 1 hour |
+| `/auth/refresh` | 100 requests | 1 hour |
+
+Rate limits are applied per IP address. When the limit is exceeded, the server returns:
+
+```json
+{
+  "error": "Rate limit exceeded",
+  "retry_after": 3600
+}
+```
+
+## Security Considerations
+
+1. **HTTPS Only**: Use HTTPS in production to protect tokens in transit
+2. **Token Storage**: Store tokens securely (secure cookies, encrypted storage)
+3. **Token Expiration**: Access tokens expire in 15 minutes, refresh tokens in 7 days
+4. **Secret Key**: Use a strong, random secret key (minimum 256 bits)
+5. **Rate Limiting**: Authentication endpoints are rate-limited to prevent abuse
+6. **Password Policy**: Strong password requirements enforced
+
+## Environment Configuration
+
+Required environment variables:
+
+```bash
+# JWT Configuration
+JWT_SECRET_KEY=your-secret-key-change-in-production-256-bits-minimum
+JWT_ACCESS_TOKEN_DURATION=15m
+JWT_REFRESH_TOKEN_DURATION=168h
+JWT_ISSUER=voidrunner
+JWT_AUDIENCE=voidrunner-api
+```
+
+For a complete list of configuration options, see `.env.example`.

docs/auth-api.md

@@ -5,7 +5,9 @@ go 1.24.4
 require (
 	github.com/gin-contrib/cors v1.7.6
 	github.com/gin-gonic/gin v1.10.1
+	github.com/golang-migrate/migrate/v4 v4.18.3
 	github.com/google/uuid v1.6.0
+	github.com/jackc/pgx/v5 v5.7.5
 	github.com/joho/godotenv v1.5.1
 	github.com/stretchr/testify v1.10.0
 )
@@ -21,12 +23,11 @@ require (
 	github.com/go-playground/universal-translator v0.18.1 // indirect
 	github.com/go-playground/validator/v10 v10.26.0 // indirect
 	github.com/goccy/go-json v0.10.5 // indirect
-	github.com/golang-migrate/migrate/v4 v4.18.3 // indirect
+	github.com/golang-jwt/jwt/v5 v5.2.2 // indirect
 	github.com/hashicorp/errwrap v1.1.0 // indirect
 	github.com/hashicorp/go-multierror v1.1.1 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
-	github.com/jackc/pgx/v5 v5.7.5 // indirect
 	github.com/jackc/puddle/v2 v2.2.2 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/klauspost/cpuid/v2 v2.2.10 // indirect
@@ -37,6 +38,7 @@ require (
 	github.com/modern-go/reflect2 v1.0.2 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/stretchr/objx v0.5.2 // indirect
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
 	github.com/ugorji/go/codec v1.3.0 // indirect
 	go.uber.org/atomic v1.7.0 // indirect