streamflow/docs/SECURITY_DEPLOYMENT_GUIDE.md

# Security Implementation - Quick Deployment Guide

## ✅ Implementation Complete

All security features have been successfully implemented and are ready for deployment.

## What Was Implemented

### 1. Input Validation Security ✅
- **Backend:** Comprehensive validation utilities and middleware
- **Frontend:** Real-time validation components and sanitization
- **Coverage:** All major routes protected (playlists, settings, channels, favorites, EPG)
- **Protection:** XSS, SQL injection, command injection, path traversal

### 2. Session Management Security ✅
- **HTTP-Only Cookies:** Prevents XSS access to tokens
- **Secure Flags:** HTTPS-only in production (SameSite=strict)
- **Idle Timeout:** 2-hour inactivity limit enforced
- **Absolute Timeout:** 24-hour maximum session lifetime
- **Session API:** Complete REST API for session management
- **Session UI:** User-friendly interface in Settings page
- **Logout:** Proper session cleanup and cookie clearing

## Files Changed

### Backend (11 files)
✅ `backend/routes/sessions.js` - NEW: Session management API
✅ `backend/routes/auth.js` - UPDATED: Cookie security + logout endpoint
✅ `backend/middleware/auth.js` - UPDATED: Session validation + idle timeout
✅ `backend/server.js` - UPDATED: Added sessions route
✅ `backend/utils/inputValidator.js` - NEW: Validation utilities
✅ `backend/middleware/inputValidation.js` - NEW: Validation middleware
✅ `backend/routes/playlists.js` - UPDATED: Added validation
✅ `backend/routes/settings.js` - UPDATED: Added validation
✅ `backend/routes/channels.js` - UPDATED: Added validation
✅ `backend/routes/favorites.js` - UPDATED: Added validation
✅ `backend/routes/epg.js` - UPDATED: Added validation

### Frontend (7 files)
✅ `frontend/src/components/SessionManagement.jsx` - NEW: Session UI
✅ `frontend/src/components/SecurityNotificationProvider.jsx` - NEW: Notifications
✅ `frontend/src/components/ValidatedTextField.jsx` - NEW: Enhanced input
✅ `frontend/src/components/SecuritySettingsPanel.jsx` - NEW: Security dashboard
✅ `frontend/src/utils/inputValidator.js` - NEW: Client validation
✅ `frontend/src/pages/Settings.jsx` - UPDATED: Added SessionManagement
✅ `frontend/src/App.jsx` - UPDATED: Added SecurityNotificationProvider + route

### Translations (2 files)
✅ `frontend/src/locales/en.json` - UPDATED: 30+ security keys
✅ `frontend/src/locales/ro.json` - UPDATED: 30+ security keys

### Documentation (3 files)
✅ `docs/INPUT_VALIDATION_SECURITY.md` - NEW: Complete validation guide
✅ `docs/SESSION_MANAGEMENT_SECURITY.md` - NEW: Complete session guide
✅ `docs/SECURITY_IMPLEMENTATION_COMPLETE.md` - NEW: Overall summary

## Deployment Steps

### 1. Pre-Deployment Checklist

```bash
# ✅ Verify builds succeed
cd frontend && npm run build
cd ../backend && node -c routes/*.js

# ✅ Check Docker build (if using Docker)
docker-compose build

# ✅ Set environment variables
export JWT_SECRET="your-secure-random-string-minimum-32-chars"
export NODE_ENV="production"
```

### 2. Deploy Backend

```bash
# Copy files to production server
rsync -av backend/ production:/app/backend/

# Or if using Docker
docker-compose up -d --build
```

### 3. Deploy Frontend

```bash
# Build frontend
cd frontend && npm run build

# Copy dist folder to production
rsync -av dist/ production:/app/frontend/dist/
```

### 4. Restart Services

```bash
# If using Docker
docker-compose restart

# Or if using systemd
sudo systemctl restart streamflow-backend
sudo systemctl restart streamflow-frontend

# Or if using PM2
pm2 restart all
```

### 5. Verify Deployment

```bash
# Test backend health
curl https://your-domain.com/api/auth/security-status

# Test frontend
curl https://your-domain.com

# Check session API
curl https://your-domain.com/api/sessions/my-sessions \
  -H "Authorization: Bearer YOUR_TOKEN"

# Verify cookies (in browser DevTools)
# Should see: HttpOnly=true, Secure=true, SameSite=Strict
```

## Environment Variables

### Required

```bash
# CRITICAL: Set a strong, unique secret
JWT_SECRET=your_unique_secure_random_string_minimum_32_characters
```

### Optional (with defaults)

```bash
# Session duration (default: 7d)
JWT_EXPIRES_IN=7d

# Environment (affects cookie security)
NODE_ENV=production

# Rate limiting (defaults shown)
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100
```

## Session Configuration

Edit `backend/utils/passwordPolicy.js` if you want to change:

```javascript
const SESSION_POLICY = {
  maxConcurrentSessions: 3,  // Change if needed
  absoluteTimeout: 24,        // Hours (change if needed)
  idleTimeout: 2,             // Hours (change if needed)
  refreshTokenRotation: true
};
```

## Post-Deployment Testing

### 1. Test Login & Cookie
```bash
# Login and check response
curl -i -X POST https://your-domain.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"test","password":"password"}'

# Look for: Set-Cookie header with HttpOnly, Secure, SameSite=Strict
```

### 2. Test Session Management
1. Login from browser
2. Navigate to Settings → Session Management
3. Verify you see your current session
4. Login from another device/browser
5. Verify you see multiple sessions
6. Try terminating a session
7. Verify terminated session gets 401 on next request

### 3. Test Idle Timeout
1. Login
2. Wait 2+ hours without activity
3. Make any API request
4. Should receive 401 with `sessionExpired: true`

### 4. Test Input Validation
1. Try adding a playlist with XSS: `<script>alert('xss')</script>`
2. Should be sanitized to: `alert('xss')`
3. Check security audit logs for validation events

### 5. Test Logout
```bash
curl -X POST https://your-domain.com/api/auth/logout \
  -H "Authorization: Bearer YOUR_TOKEN"

# Should return: {"message": "Logout successful"}
# Cookie should be cleared
```

## Monitoring

### Check Session Count
```bash
# Login to database
sqlite3 /path/to/streamflow.db

# Query active sessions
SELECT 
  u.username, 
  COUNT(s.id) as session_count 
FROM active_sessions s 
JOIN users u ON s.user_id = u.id 
GROUP BY u.id;
```

### Check Security Audit Logs
```sql
-- Recent security events
SELECT * FROM security_audit_log 
ORDER BY created_at DESC 
LIMIT 100;

-- Failed login attempts
SELECT * FROM security_audit_log 
WHERE event_type = 'login_attempt' 
  AND status = 'failed'
ORDER BY created_at DESC;

-- Session events
SELECT * FROM security_audit_log 
WHERE event_type LIKE '%session%'
ORDER BY created_at DESC;
```

## Rollback Plan

If issues occur:

```bash
# 1. Revert backend
git checkout HEAD~1 backend/

# 2. Revert frontend
git checkout HEAD~1 frontend/

# 3. Rebuild and restart
docker-compose up -d --build

# Or
pm2 restart all
```

## Common Issues & Solutions

### Issue: Cookies not working
**Solution:** 
- Verify `NODE_ENV=production` is set
- Ensure HTTPS is enabled in production
- Check `secure` flag in cookie settings

### Issue: Sessions expire too quickly
**Solution:**
- Increase `SESSION_POLICY.idleTimeout` in `passwordPolicy.js`
- Restart backend services

### Issue: Users can't login
**Solution:**
- Check JWT_SECRET is set correctly
- Verify database has active_sessions table
- Check backend logs for errors

### Issue: Frontend build fails
**Solution:**
- Run `npm install` in frontend directory
- Check for TypeScript/JSX syntax errors
- Verify all imports are correct

### Issue: Rate limiting too aggressive
**Solution:**
- Adjust rate limits in route files
- Or set environment variables for global limits

## Success Indicators

✅ All features working:
- [ ] Users can login and receive cookies
- [ ] Session UI shows active sessions
- [ ] Users can terminate sessions
- [ ] Idle timeout triggers after 2 hours
- [ ] Input validation blocks XSS/SQL injection
- [ ] Security notifications appear for blocked attacks
- [ ] Logout clears session and cookie
- [ ] Admin can view all sessions

✅ Builds successful:
- [ ] Frontend: `npm run build` completes without errors
- [ ] Backend: All route files pass syntax check
- [ ] Docker: `docker-compose build` succeeds

✅ No errors in logs:
- [ ] Backend logs show no errors on startup
- [ ] Frontend console shows no errors
- [ ] Database queries execute successfully

## Support

### Documentation
- 📖 Input Validation: `docs/INPUT_VALIDATION_SECURITY.md`
- 📖 Session Management: `docs/SESSION_MANAGEMENT_SECURITY.md`
- 📖 Complete Summary: `docs/SECURITY_IMPLEMENTATION_COMPLETE.md`

### Debugging
- Check backend logs: `docker logs streamflow-backend` or `pm2 logs`
- Check frontend console in browser DevTools
- Query security_audit_log table for events
- Enable debug logging in `backend/utils/logger.js`

### Contact
For issues, check:
1. Application logs
2. Security audit logs
3. Database active_sessions table
4. Browser DevTools Network/Console tabs

---

**Status:** ✅ Production Ready
**Version:** 1.0
**Date:** 2024

All security features are implemented, tested, and ready for production deployment.