Docs/auth refresh strategy clean

[sheyman546]

Closes #220

---

Closes #232

---

Summary
This PR implements a comprehensive refresh token strategy for the Callora Backend, addressing issue #232. The implementation enhances security by supporting long-lived refresh tokens with short-lived access tokens, enabling secure token rotation and immediate revocation capabilities.

Changes Made
🔐 Core Implementation
RefreshTokenService: Secure token generation, validation, and management
RefreshTokenRepository: Database operations for token storage and retrieval
AuthController: REST endpoints for token refresh, revocation, and management
Auth Routes: Express routes with proper validation and middleware
🗄️ Database Schema
Added refresh_tokens table with proper indexing and constraints
Includes fields for token hashing, expiration tracking, and revocation status
Optimized for performance with composite indexes
📝 Documentation
Comprehensive documentation in docs/auth-refresh-strategy.md
Security considerations and best practices
Migration strategy and configuration guidelines
🧪 Testing
Unit tests for RefreshTokenService covering all scenarios
Integration tests for API endpoints with mock repository
Security tests for edge cases and attack vectors
Security Features
🔒 Token Security
SHA-256 Hashing: Refresh tokens stored as secure hashes
Token Validation: Multiple layers of verification (signature, type, claims)
Hash Verification: Prevents token substitution attacks
Timing-Safe Comparison: Prevents timing attacks
🛡️ Protection Mechanisms
Token Expiration: Configurable expiry times (15m access, 7d refresh)
Revocation Support: Individual and bulk token revocation
Rate Limiting: Token usage tracking and cleanup
Maximum Tokens: Limit of 5 active refresh tokens per user
API Endpoints
POST /auth/refresh - Refresh access tokens
POST /auth/revoke - Revoke specific tokens
POST /auth/revoke-all - Revoke all user tokens
GET /auth/tokens - Get token information
Configuration
bash
JWT_SECRET=your-super-secret-key
ACCESS_TOKEN_EXPIRY=15m
REFRESH_TOKEN_EXPIRY=7d
MAX_REFRESH_TOKENS_PER_USER=5
Testing Results
✅ Unit Tests - Token creation, validation, security checks ✅ Integration Tests - API endpoints, database operations
✅ Security Tests - Attack vectors, edge cases, revocation

Backward Compatibility
Existing 24-hour JWT tokens continue to work
Gradual migration path available
No breaking changes to current API
Security & Data Integrity Notes
🔐 Security Assumptions
JWT secret is properly secured and rotated
Database access is properly restricted
Client-side token storage follows security best practices
Network communication uses HTTPS
🛡️ Data Integrity
All tokens are cryptographically signed
Token hashes prevent tampering
Database constraints ensure data consistency
Audit trail for token operations
Files Changed
src/types/auth.ts - Added refresh token interfaces
src/services/refreshTokenService.ts - Core token service
src/repositories/refreshTokenRepository.ts - Database operations
src/controllers/authController.ts - API endpoints
src/routes/authRoutes.ts - Express routes
src/services/refreshTokenService.test.ts - Unit tests
tests/integration/refreshToken.test.ts - Integration tests
docs/auth-refresh-strategy.md - Documentation
migrations/add_refresh_tokens.sql - Database schema

closes#232

[drips-wave]

@sheyman546 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits