streamflow/docs/SESSION_MANAGEMENT_SECURITY.md

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)

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:

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

// 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

// 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

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

# 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

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)

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:

{
  "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

   # 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

   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

// 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:

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
• RFC 6265 - HTTP State Management Mechanism (Cookies)
• SameSite Cookie Attribute 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