🔧 Express Middleware Package

A comprehensive Express middleware utility package for Node.js web applications with monitoring and protection features.

✨ Features

• 🔒 HTTP Headers - Enhanced headers with Helmet.js
• 🌐 CORS Management - Cross-origin resource sharing configuration
• 🛡️ Input Validation - Request sanitization and validation
• 📁 Request Processing - Advanced request handling utilities
• 🔍 IP Management - Client IP detection and validation
• 🤖 Traffic Analysis - Request pattern monitoring
• 🚨 Activity Monitoring - Real-time request tracking
• 📱 Notifications - Slack integration for alerts
• 📊 Response Optimization - Compression and performance enhancements

🚀 Installation

npm install athar-express-middleware

📋 Dependencies

• helmet - HTTP headers management
• cors - Cross-origin resource sharing
• express-mongo-sanitize - NoSQL query sanitization
• compression - Response compression
• validator - Input validation utilities

🔧 Quick Start

Basic Usage

const express = require('express');
const createMiddleware = require('athar-express-middleware');

const app = express();

// Initialize with default settings
const middleware = createMiddleware();

// Apply all middlewares
middleware.initializeAll(app);

// Your routes
app.get('/', (req, res) => {
  res.json({ 
    message: 'Protected by Express Middleware!',
    requestId: req.id,
    clientIP: req.clientIP
  });
});

app.listen(3000, () => {
  console.log('🚀 Server running on port 3000');
});

Advanced Configuration

const middleware = createMiddleware({
  security: {
    cors: {
      allowedOrigins: [
        'https://yourdomain.com',
        'https://app.yourdomain.com'
      ],
      credentials: true
    },
    bodyLimit: '5mb',
    compression: {
      level: 6,
      threshold: 1024
    },
    csp: {
      defaultSrc: ["'self'"],
      styleSrc: ["'self'", "'unsafe-inline'", "https://fonts.googleapis.com"],
      scriptSrc: ["'self'", "https://cdn.jsdelivr.net"]
    }
  },
  monitoring: {
    thresholds: {
      requestsPerHour: 1000,    // Monitor IP request volume
      uniqueEndpoints: 50,      // Track endpoint access patterns
      authAttempts: 10,         // Monitor authentication attempts
      userAgents: 5            // Track user agent variations
    },
    blockDuration: 3600000,     // Block duration for flagged IPs
    enablePatternDetection: true,
    enableInputValidation: true,
    enableTraversalDetection: true,
    enableAttemptMonitoring: true
  },
  notifications: {
    enabled: true,
    applicationName: 'My API Server',
    slack: {
      enabled: true,
      webhookUrl: process.env.SLACK_WEBHOOK_URL,
      mentionUsers: ['U1234567890'],  // Slack user IDs to mention
      mentionChannels: ['here']       // @here, @channel for critical alerts
    }
  }
});

middleware.initializeAll(app);

🔐 Monitoring Features

1. Traffic Pattern Analysis

The monitoring system detects unusual patterns without affecting legitimate users:

// ✅ Normal user behavior - NO blocking
// User A: 500 requests to /api/users over 1 hour = ALLOWED
// User B: 800 requests to /api/products over 1 hour = ALLOWED

// 🚨 Unusual behavior - DETECTED & FLAGGED
// Bot: 1200 requests scanning multiple endpoints = FLAGGED
// Scanner: 50 failed login attempts = FLAGGED
// Crawler: Accessing 100+ different endpoints = FLAGGED

2. IP Validation & Management

// Automatic IP detection and validation
app.use((req, res, next) => {
  console.log('Validated IP:', req.clientIP); // Always a valid IP
  console.log('Request ID:', req.id);         // Unique request identifier
});

// Manual IP validation
const isValidIP = middleware.validateIP('192.168.1.1'); // true
const cleanIP = middleware.getSanitizedIP(req);         // Clean IP from request

3. Authentication Attempt Tracking

app.post('/login', async (req, res) => {
  const { username, password } = req.body;
  
  const isValid = await authenticateUser(username, password);
  
  if (!isValid) {
    // Track failed attempt - triggers alerts after threshold
    middleware.trackFailedAttempt(
      req.clientIP,
      req.path,
      'Invalid credentials',
      req.id
    );
    
    return res.status(401).json({ error: 'Invalid credentials' });
  }
  
  res.json({ message: 'Login successful' });
});

📊 Monitoring & Management

Get Activity Statistics

app.get('/admin/stats', (req, res) => {
  const stats = middleware.getStatistics();
  res.json(stats);
  
  // Returns:
  // {
  //   activeIPs: 245,
  //   flaggedIPs: 12,
  //   failedAttempts: 38,
  //   timestamp: "2024-01-15T10:30:00.000Z"
  // }
});

Manual IP Management

// Block an IP manually
app.post('/admin/block-ip', (req, res) => {
  const { ip, duration = 3600000 } = req.body; // 1 hour default
  
  if (!middleware.validateIP(ip)) {
    return res.status(400).json({ error: 'Invalid IP format' });
  }
  
  middleware.blockIP(ip, duration);
  res.json({ message: `IP ${ip} blocked for ${duration / 1000} seconds` });
});

// Unblock an IP
app.post('/admin/unblock-ip', (req, res) => {
  const { ip } = req.body;
  const unblocked = middleware.unblockIP(ip);
  
  res.json({ 
    message: unblocked ? `IP ${ip} unblocked` : `IP ${ip} was not blocked` 
  });
});

🔔 Slack Notifications

Setup Slack Webhook

1. Go to your Slack workspace
2. Create a new app or use existing one
3. Add "Incoming Webhooks" feature
4. Copy the webhook URL
5. Set environment variable: SLACK_WEBHOOK_URL=your_webhook_url

Notification Examples

// Critical Alert Example:
🛡️ Activity Alert: Input Pattern Detected
📊 Severity: 🚨 CRITICAL
🕒 Time: 2024-01-15T10:30:00.000Z
📋 Details:
  - Client IP: 192.168.1.100
  - Endpoint: /api/users
  - Method: POST
  - User Agent: automated-tool/1.6.12
  - Request ID: a1b2c3d4e5f6

// High Alert Example:
🛡️ Activity Alert: High Request Volume
📊 Severity: 🔴 HIGH
🕒 Time: 2024-01-15T10:30:00.000Z
📋 Details:
  - Requests per Hour: 1500
  - Client IP: 10.0.0.50
  - Current Endpoint: /api/scan
  - Threshold: 1000

⚙️ Configuration Options

Main Configuration

{
  security: {
    // Content Policy
    csp: {
      defaultSrc: ["'self'"],
      styleSrc: ["'self'", "'unsafe-inline'"],
      scriptSrc: ["'self'"],
      imgSrc: ["'self'", "data:", "https:"]
    },
    
    // CORS settings
    cors: {
      allowedOrigins: ['https://yourdomain.com'],
      credentials: true,
      methods: ['GET', 'POST', 'PUT', 'DELETE'],
      allowedHeaders: ['Content-Type', 'Authorization']
    },
    
    // Transport settings
    hsts: {
      maxAge: 31536000,      // 1 year
      includeSubDomains: true,
      preload: true
    },
    
    // Body parsing limits
    bodyLimit: '10mb',
    parameterLimit: 1000,
    
    // Compression settings
    compression: {
      level: 6,              // 1-9, higher = better compression
      threshold: 1024        // Only compress responses > 1KB
    }
  }
}

Monitoring Configuration

{
  monitoring: {
    // Detection thresholds
    thresholds: {
      requestsPerHour: 1000,     // Monitor request volume
      uniqueEndpoints: 50,       // Track endpoint access
      userAgents: 5,             // Monitor user agent patterns
      authAttempts: 20,          // Track authentication attempts
      failedAttemptThreshold: 5  // Failed attempt threshold
    },
    
    // Response settings
    blockDuration: 3600000,      // 1 hour in milliseconds
    
    // Feature toggles
    enablePatternDetection: true,
    enableInputValidation: true,
    enableTraversalDetection: true,
    enableAttemptMonitoring: true,
    
    // Cleanup settings
    cleanupInterval: 3600000,    // Clean old data every hour
    dataRetentionPeriod: 86400000 // Keep data for 24 hours
  }
}

🌍 Environment-Based Configuration

// Automatically adjusts settings based on NODE_ENV
const middleware = createMiddleware.createFromEnvironment({
  // Your custom overrides here
  notifications: {
    slack: {
      enabled: true,
      webhookUrl: process.env.SLACK_WEBHOOK_URL
    }
  }
});

// Development: More lenient thresholds, no Slack alerts
// Production: Strict monitoring, Slack alerts enabled
// Test: Notifications disabled, high thresholds

🚨 Detection Patterns

The system automatically detects these activity patterns:

1. High Request Volume

• Trigger: IP exceeds hourly request threshold
• Action: Flag IP, send alert

2. Endpoint Scanning

• Trigger: IP accesses many unique endpoints rapidly
• Action: Flag IP, send alert

3. Multiple User Agents

• Trigger: Same IP uses multiple user agent strings
• Action: Flag as suspicious, send alert

4. Unusual User Agents

• Trigger: User agent contains automation tool names
• Action: Flag request, send alert

5. Input Pattern Detection

• Trigger: Request contains unusual input patterns
• Action: Block request, send critical alert

6. Script Pattern Detection

• Trigger: Request contains script-like patterns
• Action: Block request, send alert

7. Path Pattern Detection

• Trigger: Request contains directory access patterns
• Action: Block request, send alert

8. Repeated Attempts

• Trigger: Multiple failed auth attempts from same IP
• Action: Block IP after threshold, send alert

🛠️ API Reference

Main Functions

const middleware = createMiddleware(options);

// Initialize all middlewares
middleware.initializeAll(app);

// Individual middleware access
middleware.securityMiddleware(app);
app.use(middleware.activityMiddleware);

// Utility functions
middleware.validateIP(ip);
middleware.getSanitizedIP(req);
middleware.trackFailedAttempt(ip, endpoint, reason, requestId);

// Management functions
middleware.getStatistics();
middleware.blockIP(ip, duration);
middleware.unblockIP(ip);

Request Object Enhancements

After applying the middleware, request objects include:

app.use((req, res, next) => {
  console.log({
    id: req.id,                    // Unique request ID
    clientIP: req.clientIP,        // Validated client IP
    activityScore: req.activityScore,     // 0-10 activity score
    activityPatterns: req.activityPatterns, // Detected patterns
    clientTracker: req.clientTracker      // IP tracking data
  });
  next();
});

🔧 Troubleshooting

Common Issues

1. CORS Errors

// Solution: Add your frontend domain to allowedOrigins
cors: {
  allowedOrigins: ['https://yourfrontend.com', 'http://localhost:3000']
}

2. Slack Notifications Not Working

# Check webhook URL
echo $SLACK_WEBHOOK_URL

# Verify webhook format
https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

3. Legitimate Traffic Being Flagged

// Increase thresholds for your use case
thresholds: {
  requestsPerHour: 2000,  // Increase if you have high-traffic APIs
  uniqueEndpoints: 100    // Increase for SPA applications
}

📈 Performance Impact

• Memory Usage: ~10-50MB depending on traffic (includes cleanup)
• CPU Overhead: <1% for typical applications
• Response Time: +1-3ms per request
• Storage: In-memory only, automatic cleanup

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues

Made with ❤️ for Express.js applications