streamflow/docs/ERROR_HANDLING_SECURITY.md

# Error Handling and Logging Security Implementation

## Overview

This document describes the comprehensive error handling and logging security implementation that addresses **CWE-209: Information Exposure Through Error Messages**. The system ensures that sensitive information such as file paths, stack traces, database details, and system internals are never exposed to end users.

## Security Objectives

1. **Prevent Information Disclosure**: Sanitize all error messages before sending to clients
2. **Secure Logging**: Log full error details internally while exposing safe messages externally
3. **User-Friendly Messages**: Provide meaningful feedback without technical details
4. **Audit Trail**: Maintain comprehensive logs for security monitoring and debugging

## Implementation Components

### Backend Security

#### 0. **Process-Level Error Handlers** (`backend/server.js`)

**CWE-391 Compliance:**
- ✅ Catches all uncaught exceptions
- ✅ Handles unhandled promise rejections
- ✅ Graceful shutdown on SIGTERM/SIGINT
- ✅ Server error handling
- ✅ Logs all errors before exit

**Handlers Implemented:**
```javascript
process.on('uncaughtException', handler)   // Catches sync exceptions
process.on('unhandledRejection', handler)  // Catches async rejections
process.on('SIGTERM', handler)             // Graceful shutdown
process.on('SIGINT', handler)              // Ctrl+C handling
server.on('error', handler)                // Server startup errors
```

### Backend Security

#### 1. Error Handler Utility (`backend/utils/errorHandler.js`)

**Features:**
- Sanitizes error messages before client responses
- Removes file paths, stack traces, and system information
- Maps technical errors to user-friendly messages
- Detects and filters sensitive patterns
- Provides structured error responses

**Error Types Handled:**
- Authentication & Authorization errors
- Database constraint violations
- File system errors (ENOENT, EACCES, ENOSPC)
- Network errors (ECONNREFUSED, ETIMEDOUT, ENOTFOUND)
- Validation errors
- Rate limiting

**Key Functions:**
```javascript
sanitizeError(error, defaultMessage)  // Sanitizes error for client
logError(error, context)              // Logs full error internally
errorMiddleware(err, req, res, next)  // Express middleware
asyncHandler(fn)                      // Wraps async routes
ErrorResponses.*                      // Standard error creators
```

#### 2. Enhanced Logger (`backend/utils/logger.js`)

**Security Features:**
- Automatically redacts passwords, tokens, secrets, and API keys
- Separates error logs from combined logs
- Supports production and development formats
- File rotation (5MB files, keep 5 backups)
- Structured JSON logging for analysis

**Sensitive Data Redaction:**
```javascript
// Automatically redacts:
- "password": "[REDACTED]"
- "token": "[REDACTED]"
- "secret": "[REDACTED]"
- "apiKey": "[REDACTED]"
- "authorization": "Bearer [REDACTED]"
- "privateKey": "[REDACTED]"
```

**Additional Helpers:**
```javascript
logger.security(action, details)           // Security event logging
logger.performance(operation, duration)    // Performance monitoring
```

#### 3. Global Error Middleware (`backend/server.js`)

Integrated into Express application as the last middleware:
- Catches all unhandled errors
- Logs full details internally with context
- Returns sanitized responses to clients
- Includes timestamp and error code

### Frontend Security

#### 0. **Window-Level Error Handlers** (`frontend/src/main.jsx`)

**CWE-391 Compliance:**
- ✅ Catches all window errors
- ✅ Handles unhandled promise rejections
- ✅ Service worker error handling
- ✅ Prevents default browser error display

**Handlers Implemented:**
```javascript
window.addEventListener('error', handler)              // Global errors
window.addEventListener('unhandledrejection', handler) // Promise rejections
```

**Service Worker Protection:** (`frontend/public/service-worker.js`)
```javascript
self.addEventListener('error', handler)                // SW errors
self.addEventListener('unhandledrejection', handler)   // SW rejections
```

#### 1. Error Handler Utility (`frontend/src/utils/errorHandler.js`)

**Features:**
- Extracts user-friendly messages from API responses
- Classifies errors by type (auth, permission, validation, network, server)
- Determines error severity
- Provides retry logic for transient failures
- Never exposes technical details to UI

**Key Functions:**
```javascript
getErrorMessage(error, defaultMessage)    // Extract safe message
isAuthError(error)                        // Check if auth error
isPermissionError(error)                  // Check if permission error
isValidationError(error)                  // Check if validation error
isNetworkError(error)                     // Check if network error
getErrorType(error)                       // Classify error type
formatError(error, options)               // Format for display
createErrorNotification(error, options)   // Create notification
retryRequest(fn, options)                 // Retry with backoff
```

#### 2. Error Boundary Component (`frontend/src/components/ErrorBoundary.jsx`)

**Purpose:**
- Catches JavaScript errors in React component tree
- Prevents application crashes
- Displays user-friendly fallback UI
- Provides recovery options (reset, reload)
- **Does NOT expose stack traces to users**

**Features:**
- Automatic error counting
- Reset functionality
- Full page reload option
- Localized messages

#### 3. Error Notification Provider (`frontend/src/components/ErrorNotificationProvider.jsx`)

**Global Notification System:**
- Context-based notification management
- Automatic error type detection
- Localized error titles and messages
- Severity-based styling (error, warning, info, success)
- Auto-dismiss with configurable duration

**Usage:**
```javascript
const { showError, showSuccess, showWarning, showInfo } = useErrorNotification();

// Show error from API response
showError(error, { defaultMessage: 'Custom message' });

// Show success message
showSuccess('Operation completed successfully');
```

#### 4. Enhanced API Client (`frontend/src/utils/api.js`)

**Security Improvements:**
- Automatic error handling with sanitization
- Timeout configuration (30 seconds)
- Automatic retry for transient failures
- Auth error detection and redirect
- Silent token parsing errors
- Development-only error logging

### Internationalization

#### Error Message Translations

**English (`frontend/src/locales/en.json`):**
```json
"errors": {
  "general": { "unexpected", "tryAgain", "contactSupport" },
  "network": { "title", "message", "timeout", "offline" },
  "auth": { "title", "required", "invalid", "failed", "sessionExpired" },
  "permission": { "title", "message", "adminRequired", "contactAdmin" },
  "validation": { "title", "invalidInput", "requiredField", "invalidFormat" },
  "server": { "title", "message", "unavailable", "maintenance", "overloaded" },
  "notFound": { "title", "message", "page", "resource" },
  "conflict": { "title", "message", "duplicate", "outdated" },
  "rateLimit": { "title", "message", "slowDown" }
}
```

**Romanian (`frontend/src/locales/ro.json`):**
Full translations provided for all error categories.

## Security Benefits

### 1. CWE-209 Mitigation

**Before:**
```javascript
// Exposed internal details
res.status(500).json({ error: error.message });
// User sees: "ENOENT: no such file or directory, open '/app/data/db/users.db'"
```

**After:**
```javascript
// Sanitized message
const sanitized = sanitizeError(error);
res.status(500).json({ error: sanitized.message });
// User sees: "An internal error occurred"
```

### 2. Stack Trace Protection

**Before:**
```
Error: Database error
    at /app/backend/routes/users.js:45:12
    at processTicksAndRejections (internal/process/task_queues.js:93:5)
```

**After:**
```json
{
  "error": "Database operation failed",
  "code": "DATABASE_ERROR",
  "timestamp": "2025-12-15T10:30:00.000Z"
}
```

### 3. Sensitive Data Redaction

**Logs automatically redact:**
- Passwords
- Authentication tokens
- API keys
- Secrets
- Private keys
- Authorization headers

### 4. Contextual Logging

**Internal logs include:**
- Full error stack trace
- Request method and path
- User ID (if authenticated)
- IP address
- Timestamp
- Additional context

**Client responses include:**
- Safe error message
- Error code
- Timestamp
- HTTP status code

## Usage Examples

### Backend Route with Error Handling

```javascript
const { asyncHandler, ErrorResponses } = require('../utils/errorHandler');

router.get('/users/:id', asyncHandler(async (req, res) => {
  const user = await findUser(req.params.id);
  
  if (!user) {
    throw ErrorResponses.notFound('User not found');
  }
  
  res.json(user);
}));
```

### Frontend Component with Error Handling

```javascript
import { useErrorNotification } from '../components/ErrorNotificationProvider';
import { getErrorMessage } from '../utils/errorHandler';

function MyComponent() {
  const { showError, showSuccess } = useErrorNotification();
  
  const handleSubmit = async () => {
    try {
      await api.post('/users', data);
      showSuccess('User created successfully');
    } catch (error) {
      showError(error);
    }
  };
}
```

### Custom Error Messages

```javascript
// Backend
throw ErrorResponses.badRequest('Email address is already in use');

// Frontend automatically displays localized message
// No technical details exposed
```

## Testing

### Test Cases

1. **Database Errors**
   - UNIQUE constraint → "Duplicate entry exists"
   - NOT NULL constraint → "Required field is missing"
   - Foreign key constraint → "Resource conflict"

2. **File System Errors**
   - ENOENT → "File not found"
   - EACCES → "Access forbidden"
   - ENOSPC → "Service temporarily unavailable"

3. **Network Errors**
   - ECONNREFUSED → "External service unavailable"
   - ETIMEDOUT → "Request timeout"
   - ENOTFOUND → "Network request failed"

4. **Authentication Errors**
   - Invalid token → "Invalid or expired authentication token"
   - Missing auth → "Authentication required"
   - Expired session → "Your session has expired"

### Manual Testing

```bash
# Test error sanitization
curl http://localhost:12345/api/nonexistent
# Should return: {"error": "Resource not found", ...}
# Should NOT expose file paths or stack traces

# Test authentication error
curl http://localhost:12345/api/users
# Should return: {"error": "Authentication required", ...}

# Test rate limiting
# Make 100+ rapid requests
# Should return: {"error": "Too many requests. Please try again later", ...}
```

## Monitoring and Maintenance

### Log Files

**Location:** `/app/logs/`

- `error.log` - Error-level events only
- `combined.log` - All application logs

**Rotation:** 5MB per file, keep 5 files

### Security Events

Monitor for:
- Unusual error patterns
- Repeated authentication failures
- Rate limit violations
- Permission denied attempts
- Database constraint violations

### Performance Monitoring

```javascript
const start = Date.now();
await performOperation();
logger.performance('operation_name', Date.now() - start);
```

## Docker Integration

All changes are automatically included in Docker builds:

```dockerfile
# Logs directory created with correct permissions
# Error handling utilities bundled
# Frontend error components included
# Translations packaged
```

## PWA & Desktop App Compatibility

- Error boundary works in all environments
- Service worker error handling included
- Electron app error logging configured
- APK builds include error handling

## Best Practices

### DO:
✅ Use `ErrorResponses` for standard errors
✅ Use `asyncHandler` for async routes
✅ Log errors with context using `logError()`
✅ Use `useErrorNotification()` in React components
✅ Provide user-friendly error messages
✅ Include error codes for debugging

### DON'T:
❌ Never send `error.stack` to clients
❌ Never expose file paths in error messages
❌ Never include database query details in responses
❌ Never log passwords or tokens
❌ Never use `console.error()` for sensitive data
❌ Never expose internal implementation details

## Compliance

This implementation addresses:
- **CWE-209**: Information Exposure Through Error Messages ✅
- **CWE-391**: Unchecked Error Condition ✅
- **OWASP A01:2021**: Broken Access Control
- **OWASP A07:2021**: Identification and Authentication Failures
- **OWASP A09:2021**: Security Logging and Monitoring Failures

## Summary

The error handling and logging security implementation provides:

1. ✅ **Complete CWE-209 mitigation** - No information leakage
2. ✅ **Complete CWE-391 compliance** - No unhandled exceptions
3. ✅ **Secure logging** - Full internal logs, safe external messages
4. ✅ **User-friendly errors** - Clear, actionable messages
5. ✅ **Multi-language support** - English and Romanian translations
6. ✅ **Global error handling** - Process, window, and component level
7. ✅ **Structured logging** - JSON format for analysis
8. ✅ **Automatic sanitization** - Passwords, tokens, secrets redacted
9. ✅ **Docker integration** - All changes bundled
10. ✅ **PWA/Desktop compatible** - Works in all environments
11. ✅ **Service worker protection** - Error handling in SW context
12. ✅ **Production-ready** - Tested and documented

All existing features remain functional. No breaking changes introduced.