feat(auth): Implement comprehensive JWT authentication system with token rotation
This commit introduces a complete authentication system using JWT-based access and refresh
tokens, secure session management, and refresh token rotation to enhance overall security.
Core Authentication Features:
- Dual-token system: Short-lived access tokens (15 min) + long-lived refresh tokens (7 days)
- Hybrid security model: JWT signatures + SHA-256 hashed refresh tokens in database
- Session tracking: Device info, IP address, and user agent for security auditing
- Token rotation: Automatically rotates refresh tokens on each use to reduce theft exposure
- Multi-tenant support: TenantID embedded in access tokens for data isolation
Security Implementations:
- bcrypt password hashing for user credentials
- SHA-256 hashing for refresh token persistence and fast lookup
- HttpOnly + Secure + SameSite cookies for XSS/CSRF protection
- Token type validation to prevent misuse of refresh tokens as access tokens
- Robust input validation (email structure, password strength, uniqueness)
- Generic authentication errors to prevent email enumeration attacks
Authentication Middleware:
- Required authentication: Rejects unauthorized requests with 401
- Optional authentication: Allows public/private hybrid endpoints
- Dual token source support: Cookies (web) + Authorization header (mobile/API)
- Injects user claims into request context for downstream handlers
Rate Limiting:
- Sliding window algorithm to prevent brute force and DoS attacks
- Configurable per-IP limits with automatic counter cleanup
- Thread-safe design using mutex locks
- Returns 429 Too Many Requests on rate limit violations
Password & Email Validation:
- Password rules: Minimum length, mixed character types, no personal info
- Email validation: RFC-compliant parsing + normalization (lowercase/trim)
- Case-insensitive uniqueness checks during registration
Session Management:
- Database-backed sessions for immediate revocation and device tracking
- View active sessions per user (with metadata)
- Revoke single or all sessions
- Automatic cleanup of expired/revoked sessions
API Endpoints Added:
- POST /api/v1/auth/login – Authenticate user and issue tokens
- POST /api/v1/auth/refresh – Rotate refresh token and issue new access token
- POST /api/v1/auth/logout – Revoke session and clear cookies
- GET /api/v1/health – Protected health check route
Service Layer Enhancements:
- AuthService: Token generation/validation, session lifecycle management
- UserService: Registration, authentication, and password updates
CORS Configuration:
- Localhost origins for development (5173, 3000)
- Configurable allowed methods/headers/credentials
- 1-hour preflight caching
- Production-ready whitelist via environment config
Files Added:
- pkg/auth/claims.go
- internal/services/auth_service.go
- internal/services/user_service.go
- internal/repositories/session_repository.go
- internal/repositories/user_repository.go
- internal/handlers/auth_handler.go
- internal/middleware/auth_middleware.go
- internal/middleware/cors.go
- internal/middleware/rate_limiter.go
- internal/models/session.go
- internal/models/user.go
- internal/config/config.go
- internal/routes/routes.go
Technical Stack:
- Echo v4, golang-jwt/jwt v5, sqlx, bcrypt, PostgreSQL
Testing Considerations:
- Dependency injection for easy mocking
- Service-layer testing independent of HTTP stack
- Repository abstraction supporting mock DBs
- Time-based logic testable via injected clock
Future Enhancements:
- Redis-powered rate limiting for scaling
- Password history enforcement
- Have I Been Pwned integration
- Email verification workflow
- Two-factor authentication (2FA)
- OAuth/social login support
- Monitoring/metrics (Prometheus)
- Structured logging with request IDs
Story: E2-001-2 – JWT Authentication System Implementation
Rezon Philip
060cf8c78b