feat: implement comprehensive rate limiting system

backend/.env.example

@@ -68,6 +68,28 @@ MIN_REBALANCE_INTERVAL=86400000
 # Maximum auto-rebalances per day per portfolio
 MAX_AUTO_REBALANCES_PER_DAY=3
 
+# ============================================
+# RATE LIMITING CONFIGURATION
+# ============================================
+
+# Global rate limiting (applies to all requests)
+RATE_LIMIT_WINDOW_MS=60000
+RATE_LIMIT_MAX=100
+
+# Write operations rate limiting (POST/PUT/DELETE)
+RATE_LIMIT_WRITE_MAX=10
+
+# Authentication endpoints rate limiting
+RATE_LIMIT_AUTH_MAX=5
+
+# Critical operations rate limiting (rebalancing, data deletion)
+RATE_LIMIT_CRITICAL_MAX=3
+
+# Burst protection (short window, prevents rapid-fire attacks)
+RATE_LIMIT_BURST_WINDOW_MS=10000
+RATE_LIMIT_BURST_MAX=20
+RATE_LIMIT_WRITE_BURST_MAX=3
+
 # ============================================
 # JOB QUEUE CONFIGURATION (BullMQ + Redis)
 # ============================================

backend/RATE_LIMITING_IMPLEMENTATION.md

@@ -0,0 +1,168 @@
+# Rate Limiting Implementation Summary
+
+## ✅ Implementation Complete
+
+This implementation provides comprehensive backend-level request throttling that addresses all the specified requirements:
+
+### 🛡️ Protection Against Abuse and Overload
+
+**Multi-Tier Rate Limiting:**
+- **Burst Protection**: 20 requests/10s (prevents rapid-fire attacks)
+- **Global Limits**: 100 requests/minute (general API usage)
+- **Write Operations**: 10 requests/minute (POST/PUT/DELETE)
+- **Critical Operations**: 3 requests/minute (rebalancing, data deletion)
+- **Authentication**: 5 requests/minute (login/refresh/logout)
+- **Admin Operations**: 5 requests/minute (admin endpoints)
+
+### 🔄 Shared State Across Instances
+
+**Redis Store Integration:**
+- Uses `rate-limit-redis` for distributed rate limiting
+- Shared state across multiple backend instances
+- Graceful fallback to memory store if Redis unavailable
+- Proper connection management and cleanup
+
+### 📊 Separate Policies for Different Endpoint Types
+
+**Intelligent Endpoint Classification:**
+- **Read-heavy endpoints**: Global rate limits only
+- **Write operations**: Enhanced protection with burst limits
+- **Critical operations**: Strictest limits (rebalancing, user data deletion)
+- **Authentication**: Specialized limits to prevent brute force
+- **Admin endpoints**: Protected with admin-specific limits
+- **Health checks**: Excluded from rate limiting
+
+### 🎯 IP + Wallet-Address Based Throttling
+
+**Smart Key Generation:**
+- Authenticated requests: `prefix:ip:wallet_address`
+- Unauthenticated requests: `prefix:ip`
+- Prevents circumvention by IP switching
+- Handles multiple users behind same NAT/proxy
+
+### 📋 Standard 429 Response with Retry Metadata
+
+**Comprehensive Error Responses:**
+```json
+{
+  "success": false,
+  "error": {
+    "code": "RATE_LIMITED",
+    "message": "Rate limit exceeded for write-operations. Please try again later.",
+    "details": {
+      "limitType": "write-operations",
+      "retryAfter": 60,
+      "endpoint": "POST /api/portfolio"
+    }
+  },
+  "meta": {
+    "retryAfter": 60,
+    "limitType": "write-operations",
+    "endpoint": "POST /api/portfolio"
+  }
+}
+```
+
+**Standard Headers:**
+- `Retry-After`: Seconds until retry allowed
+- `X-RateLimit-Limit-Type`: Type of limit exceeded
+- RFC draft-7 compliant rate limit headers
+
+## 🎯 Acceptance Criteria Met
+
+### ✅ Abusive Request Bursts Throttled Consistently
+
+- **Burst protection** prevents rapid-fire attacks (20 req/10s)
+- **Redis store** ensures consistency across instances
+- **Intelligent key generation** prevents easy circumvention
+- **Multi-tier approach** catches different attack patterns
+
+### ✅ Critical Write Endpoints Protected
+
+- **Rebalancing operations**: 3 requests/minute + burst protection
+- **Portfolio creation**: 10 requests/minute + burst protection  
+- **User data deletion**: 3 requests/minute + burst protection
+- **Consent recording**: 10 requests/minute + burst protection
+- **Authentication**: 5 requests/minute (never skipped)
+
+### ✅ Rate-Limit Behavior Observable
+
+**Comprehensive Monitoring:**
+- Detailed request/throttle metrics tracking
+- Real-time suspicious activity detection
+- Admin endpoint: `GET /api/admin/rate-limits/metrics`
+- Structured logging with request context
+- Daily metrics reports with top offenders
+
+**Alerting System:**
+- Medium alerts: 50+ throttles from IP, 25+ from user
+- Critical alerts: 100+ throttles (potential ban consideration)
+- Automatic pattern detection and logging
+
+## 🔧 Configuration
+
+**Environment Variables:**
+```bash
+# Global limits
+RATE_LIMIT_WINDOW_MS=60000
+RATE_LIMIT_MAX=100
+
+# Specialized limits
+RATE_LIMIT_WRITE_MAX=10
+RATE_LIMIT_AUTH_MAX=5
+RATE_LIMIT_CRITICAL_MAX=3
+
+# Burst protection
+RATE_LIMIT_BURST_WINDOW_MS=10000
+RATE_LIMIT_BURST_MAX=20
+RATE_LIMIT_WRITE_BURST_MAX=3
+
+# Redis for distributed limiting
+REDIS_URL=redis://localhost:6379
+```
+
+## 🧪 Testing
+
+**Automated Test Suite:**
+```bash
+npm run test:rate-limits
+```
+
+Tests all rate limiting scenarios:
+- Global rate limits
+- Burst protection
+- Write operation limits
+- Authentication limits
+- Health check exclusions
+
+## 📚 Documentation
+
+- **Comprehensive docs**: `backend/docs/rate-limiting.md`
+- **Implementation details**: Architecture, configuration, monitoring
+- **Operational procedures**: Monitoring, incident response, maintenance
+- **Security considerations**: Attack prevention, bypass protection
+
+## 🚀 Deployment Ready
+
+**Production Considerations:**
+- Redis connection required for multi-instance deployments
+- Graceful shutdown handling for proper cleanup
+- Monitoring endpoints for operational visibility
+- Configurable limits for different environments
+- Fail-open design (requests not blocked if rate limiting fails)
+
+## 📈 Monitoring Dashboard
+
+Access rate limiting metrics via:
+```
+GET /api/admin/rate-limits/metrics
+```
+
+Returns:
+- Current throttle rates and totals
+- Top offending IPs and users  
+- Most throttled endpoints
+- Detailed activity reports
+- Suspicious activity alerts
+
+The implementation is production-ready and provides robust protection against abuse while maintaining excellent observability for operations teams.