Initial commit: StreamFlow IPTV platform

2025-12-17 00:42:43 +00:00 · 2025-12-17 00:42:43 +00:00 · 73a8ae9ffd
commit 73a8ae9ffd
1240 changed files with 278451 additions and 0 deletions
--- a/docs/SESSION_MANAGEMENT_SECURITY.md
+++ b/docs/SESSION_MANAGEMENT_SECURITY.md
@ -0,0 +1,415 @@
+# Session Management Security Implementation
+
+## Overview
+
+This document details the comprehensive session management security implementation for StreamFlow, addressing session fixation, session hijacking, and other session-based attacks through proper session handling, cookie security, and timeout enforcement.
+
+## Session Security Features
+
+### 1. Secure Session Creation
+
+**Implementation:** `backend/middleware/securityEnhancements.js`
+
+- **Cryptographically Strong Session IDs**: Sessions use JWT tokens signed with `JWT_SECRET`
+- **Random Session Tokens**: Each session gets a unique, unpredictable token
+- **Session Metadata**: Tracks user_id, IP address, user agent, timestamps
+- **Absolute Timeout**: 24-hour maximum session lifetime (configurable)
+- **Idle Timeout**: 2-hour inactivity limit (configurable)
+
+```javascript
+const SESSION_POLICY = {
+  maxConcurrentSessions: 3,
+  absoluteTimeout: 24,      // hours
+  idleTimeout: 2,           // hours
+  refreshTokenRotation: true
+};
+```
+
+### 2. HTTP-Only Cookie Configuration
+
+**Implementation:** `backend/routes/auth.js`
+
+All authentication endpoints now set secure HTTP-only cookies:
+
+```javascript
+res.cookie('auth_token', token, {
+  httpOnly: true,                    // Prevents XSS access
+  secure: process.env.NODE_ENV === 'production',  // HTTPS only in production
+  sameSite: 'strict',                // CSRF protection
+  maxAge: 7 * 24 * 60 * 60 * 1000   // 7 days
+});
+```
+
+**Protected Endpoints:**
+- `POST /api/auth/register` - Registration
+- `POST /api/auth/login` - Standard login
+- `POST /api/auth/verify-2fa` - Two-factor authentication (both TOTP and backup codes)
+
+**Cookie Security Attributes:**
+- **httpOnly**: JavaScript cannot access the cookie (prevents XSS)
+- **secure**: Cookie only sent over HTTPS (prevents man-in-the-middle)
+- **sameSite: strict**: Cookie not sent with cross-site requests (prevents CSRF)
+- **maxAge**: Cookie expires after 7 days
+
+### 3. Session Validation & Idle Timeout Enforcement
+
+**Implementation:** `backend/middleware/auth.js`
+
+The authentication middleware now performs comprehensive session validation:
+
+1. **Token Verification**: Validates JWT signature and expiration
+2. **Session Lookup**: Verifies session exists in database
+3. **Absolute Timeout Check**: Ensures session hasn't exceeded 24-hour lifetime
+4. **Idle Timeout Check**: Validates last activity within 2-hour window
+5. **Activity Update**: Updates `last_activity` timestamp on each request
+
+```javascript
+// Idle timeout check
+const idleTimeMs = now - lastActivity;
+const idleTimeoutMs = SESSION_POLICY.idleTimeout * 60 * 60 * 1000;
+
+if (idleTimeMs > idleTimeoutMs) {
+  db.run('DELETE FROM active_sessions WHERE id = ?', [session.id]);
+  return res.status(401).json({ 
+    error: 'Session expired due to inactivity', 
+    sessionExpired: true 
+  });
+}
+```
+
+### 4. Session Management API
+
+**Implementation:** `backend/routes/sessions.js`
+
+New RESTful API for session management:
+
+#### User Endpoints
+
+**GET /api/sessions/my-sessions**
+- View all active sessions for the current user
+- Returns device info, IP address, last activity
+- Identifies current session
+
+**DELETE /api/sessions/:sessionId**
+- Terminate a specific session
+- Cannot terminate current session (prevents accidental logout)
+- Logs security audit event
+
+**POST /api/sessions/terminate-all-others**
+- Terminate all sessions except the current one
+- Useful after password change or security concern
+- Returns count of terminated sessions
+
+#### Admin Endpoints
+
+**GET /api/sessions/all**
+- View all active sessions across all users
+- Requires admin role
+- Includes user information
+
+**POST /api/sessions/force-logout/:userId**
+- Admin can force logout a specific user
+- Terminates all sessions for that user
+- Logs security audit event
+
+**GET /api/sessions/stats**
+- Session statistics (total active, per-user counts)
+- Requires admin role
+
+### 5. Session Management UI
+
+**Implementation:** `frontend/src/components/SessionManagement.jsx`
+
+User-facing interface for managing active sessions:
+
+**Features:**
+- View all active sessions with device/browser detection
+- Shows IP address, last activity, creation time
+- Highlights current session
+- Terminate individual sessions
+- Bulk terminate all other sessions
+- Real-time session refresh
+- Internationalized (EN/RO)
+
+**Device Detection:**
+- Identifies browsers (Chrome, Firefox, Safari, Edge)
+- Detects device types (Desktop, Mobile, Tablet)
+- Shows user agent details
+
+**UI Integration:**
+- Embedded in Settings page (`/settings`)
+- Uses Material-UI components
+- Security notifications via `SecurityNotificationProvider`
+
+### 6. Logout with Session Cleanup
+
+**Implementation:** `backend/routes/auth.js`
+
+New logout endpoint with proper cleanup:
+
+**POST /api/auth/logout**
+- Requires authentication
+- Removes session from database
+- Clears HTTP-only cookie
+- Logs security audit event
+- Returns success confirmation
+
+```javascript
+// Clear the HTTP-only cookie
+res.clearCookie('auth_token', {
+  httpOnly: true,
+  secure: process.env.NODE_ENV === 'production',
+  sameSite: 'strict'
+});
+```
+
+## Attack Prevention
+
+### Session Fixation Protection
+
+1. **New Session on Login**: Fresh session created after successful authentication
+2. **Token Regeneration**: JWT token signed with unique session data
+3. **Old Session Cleanup**: Previous sessions can be terminated
+4. **Session Binding**: Session tied to user_id, IP, and user agent
+
+### Session Hijacking Prevention
+
+1. **HTTP-Only Cookies**: JavaScript cannot access auth tokens
+2. **HTTPS Enforcement**: `secure` flag in production prevents interception
+3. **SameSite Strict**: Prevents CSRF by blocking cross-site cookies
+4. **IP & User Agent Tracking**: Session metadata helps detect suspicious activity
+5. **Idle Timeout**: Limits exposure window of stolen sessions
+6. **Absolute Timeout**: Maximum 24-hour session lifetime
+
+### Concurrent Session Control
+
+1. **Max 3 Sessions**: `SESSION_POLICY.maxConcurrentSessions` enforced
+2. **User Visibility**: Users can see all active sessions
+3. **Selective Termination**: Users can kill suspicious sessions
+4. **Bulk Termination**: "Terminate all others" for security incidents
+
+## Database Schema
+
+### active_sessions Table
+
+```sql
+CREATE TABLE IF NOT EXISTS active_sessions (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_id INTEGER NOT NULL,
+  session_token TEXT NOT NULL,
+  ip_address TEXT,
+  user_agent TEXT,
+  last_activity TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  expires_at TIMESTAMP NOT NULL,
+  FOREIGN KEY (user_id) REFERENCES users (id)
+);
+```
+
+**Indexes:**
+- `user_id` - Fast lookup of user sessions
+- `session_token` - Fast session validation
+- `expires_at` - Efficient cleanup of expired sessions
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# JWT Secret (CRITICAL - must be unique and secure)
+JWT_SECRET=your_secure_random_string_here
+
+# Session duration (optional, defaults below apply)
+JWT_EXPIRES_IN=7d
+
+# Environment (affects cookie security)
+NODE_ENV=production
+```
+
+### Session Policy Configuration
+
+**File:** `backend/utils/passwordPolicy.js`
+
+```javascript
+const SESSION_POLICY = {
+  maxConcurrentSessions: 3,  // Maximum sessions per user
+  absoluteTimeout: 24,        // Hours until forced logout
+  idleTimeout: 2,             // Hours of inactivity before logout
+  refreshTokenRotation: true  // Future: implement refresh token rotation
+};
+```
+
+## Automated Cleanup
+
+**Implementation:** `backend/jobs/epgSync.js` (runs hourly)
+
+```javascript
+setInterval(() => {
+  const { cleanupExpiredSessions } = require('../middleware/securityEnhancements');
+  cleanupExpiredSessions();
+}, 60 * 60 * 1000); // Every hour
+```
+
+**Cleanup Process:**
+1. Deletes sessions where `expires_at < NOW()`
+2. Runs automatically every hour
+3. Prevents database bloat
+4. Logs cleanup count
+
+## Internationalization
+
+### Translation Keys (EN/RO)
+
+Added to `frontend/src/locales/en.json` and `ro.json`:
+
+```json
+{
+  "security": {
+    "activeSessions": "Active Sessions",
+    "terminateSession": "Terminate Session",
+    "terminateAllSessions": "Terminate All Other Sessions",
+    "multipleDevices": "You are currently logged in on {{count}} devices",
+    "noRecentActivity": "No recent activity found",
+    "ipAddress": "IP Address",
+    "status": "Status"
+  },
+  "device": "Device",
+  "location": "Location",
+  "lastActive": "Last Active",
+  "created": "Created",
+  "current": "Current",
+  "active": "Active",
+  "actions": "Actions",
+  "refresh": "Refresh"
+}
+```
+
+## Testing Recommendations
+
+### Manual Testing
+
+1. **Session Creation**
+   ```bash
+   # Login and verify cookie is set
+   curl -c cookies.txt -X POST http://localhost:3000/api/auth/login \
+     -H "Content-Type: application/json" \
+     -d '{"username":"test","password":"password"}'
+   ```
+
+2. **View Active Sessions**
+   ```bash
+   curl -b cookies.txt http://localhost:3000/api/sessions/my-sessions
+   ```
+
+3. **Idle Timeout**
+   - Login
+   - Wait 2+ hours without making requests
+   - Next request should return 401 with `sessionExpired: true`
+
+4. **Absolute Timeout**
+   - Login
+   - Keep session active (make requests every hour)
+   - After 24 hours, session should expire
+
+5. **Session Termination**
+   - Login from multiple devices
+   - Terminate one session
+   - Verify terminated session gets 401
+
+6. **Cookie Security**
+   - Verify cookies in browser DevTools have `HttpOnly`, `Secure` (production), `SameSite=Strict`
+
+### Automated Testing
+
+```javascript
+// Example test for idle timeout
+describe('Session Idle Timeout', () => {
+  it('should expire session after 2 hours of inactivity', async () => {
+    const token = await loginUser('test', 'password');
+    
+    // Fast-forward time 2+ hours
+    await setSystemTime(Date.now() + (2.5 * 60 * 60 * 1000));
+    
+    const response = await fetch('/api/playlists', {
+      headers: { Authorization: `Bearer ${token}` }
+    });
+    
+    expect(response.status).toBe(401);
+    expect(response.body.sessionExpired).toBe(true);
+  });
+});
+```
+
+## Security Audit Logging
+
+All session events are logged via `SecurityAuditLogger`:
+
+- **login** - Successful authentication
+- **logout** - User-initiated logout
+- **session_terminated** - Session killed by user
+- **session_force_logout** - Admin force logout
+- **session_expired_idle** - Idle timeout triggered
+- **session_expired_absolute** - Absolute timeout triggered
+
+**Audit Log Query:**
+```sql
+SELECT * FROM security_audit_log 
+WHERE event_type LIKE '%session%' 
+ORDER BY created_at DESC 
+LIMIT 100;
+```
+
+## Deployment Checklist
+
+- [ ] Set strong `JWT_SECRET` in production
+- [ ] Enable `NODE_ENV=production` for secure cookies
+- [ ] Configure HTTPS/TLS for production
+- [ ] Verify session cleanup job is running
+- [ ] Test idle timeout in production environment
+- [ ] Monitor session count per user
+- [ ] Review security audit logs regularly
+- [ ] Set up alerts for suspicious session activity
+
+## Future Enhancements
+
+### Planned Features
+
+1. **Refresh Token Rotation**
+   - Implement short-lived access tokens
+   - Long-lived refresh tokens
+   - Automatic token rotation
+
+2. **Session Fingerprinting**
+   - Enhanced device fingerprinting
+   - Detect session hijacking via fingerprint changes
+   - Challenge suspicious sessions
+
+3. **Geographic Session Restrictions**
+   - IP geolocation tracking
+   - Alert on login from new locations
+   - Option to restrict sessions by country
+
+4. **Session Analytics**
+   - Dashboard showing session trends
+   - Average session duration
+   - Peak usage times
+   - Device distribution
+
+5. **Trusted Device Management**
+   - Remember trusted devices
+   - Extended timeouts for trusted devices
+   - Device verification via email
+
+## References
+
+- [OWASP Session Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html)
+- [RFC 6265 - HTTP State Management Mechanism (Cookies)](https://tools.ietf.org/html/rfc6265)
+- [SameSite Cookie Attribute Explained](https://web.dev/samesite-cookies-explained/)
+
+## Support
+
+For questions or issues related to session management:
+- Review this documentation
+- Check security audit logs
+- Examine `active_sessions` table
+- Enable debug logging in `backend/utils/logger.js`