Cross-Origin Resource Sharing (CORS)

Imagine trying to access your bank account from a legitimate banking website, but an attacker has created a malicious website that attempts to make requests to your bank's API on your behalf. Without proper security controls, this attacker could potentially access your financial data or perform unauthorized transactions. This is the fundamental security problem that Cross-Origin Resource Sharing (CORS) and the Same-Origin Policy solve—controlling which websites can make requests to which servers and under what conditions.

Cross-Origin Resource Sharing (CORS) is a web standard that defines how browsers and servers interact to safely allow cross-origin HTTP requests while maintaining security boundaries. CORS works alongside the Same-Origin Policy (SOP) to provide a controlled relaxation of the strict same-origin restrictions, enabling legitimate cross-domain communication while preventing unauthorized access.

In modern web applications where microservices, APIs, CDNs, and third-party integrations are commonplace, understanding and properly configuring CORS becomes critical for both functionality and security. Misconfigured CORS can either break legitimate functionality or create security vulnerabilities that expose sensitive data and APIs to unauthorized access.

In this comprehensive guide, we'll explore CORS mechanisms and implementation strategies, from understanding the Same-Origin Policy and preflight requests to building sophisticated CORS management systems that balance security with functionality in complex web architectures.

Understanding Cross-Origin Security Architecture

CORS operates as a negotiation mechanism between browsers and servers that determines whether cross-origin requests should be allowed, creating secure boundaries for web application communication.

The Theoretical Foundation of Cross-Origin Security

What is the Same-Origin Policy? The Same-Origin Policy is a critical web security concept that restricts how documents or scripts from one origin can interact with resources from another origin. Two URLs are considered to have the same origin if they have the same protocol, domain, and port.

Same-Origin Examples:

// Same origin as https://example.com:443/page
'https://example.com/api/data'     // ✓ Same origin
'https://example.com:443/api'      // ✓ Same origin (default HTTPS port)
'https://example.com/different'    // ✓ Same origin

// Different origins
'http://example.com/api'           // ✗ Different protocol
'https://api.example.com/data'     // ✗ Different subdomain
'https://example.com:8080/api'     // ✗ Different port
'https://another.com/api'          // ✗ Different domain

Why Same-Origin Policy Exists: Without SOP, any website could make requests to any other website on behalf of the user, leading to:

Cross-Site Request Forgery (CSRF): Malicious sites could perform actions on other sites
Data Theft: Malicious scripts could read sensitive data from other origins
Session Hijacking: Attackers could access user sessions on other websites

The CORS Solution: CORS provides a controlled way to relax SOP restrictions by:

Server Declaration: Servers explicitly declare which origins can access their resources
Browser Enforcement: Browsers enforce these declarations and block unauthorized requests
Preflight Negotiation: Complex requests require pre-approval through preflight requests
Credential Handling: Special rules for requests that include cookies or authentication

CORS Request Types and Flow

🌐 Cross-Origin Resource Sharing Flow

📡 Simple Requests (No Preflight)
   • GET, POST, HEAD methods only
   • Limited headers (Accept, Content-Type, etc.)
   • Content-Type: text/plain, multipart/form-data, application/x-www-form-urlencoded
   • Direct request with Origin header
   • Server responds with Access-Control-Allow-Origin

🔍 Preflight Requests (Complex Requests)
   • Custom HTTP methods (PUT, DELETE, PATCH)
   • Custom headers (Authorization, X-API-Key)
   • Content-Type: application/json, application/xml
   • Browser sends OPTIONS request first
   • Server responds with allowed methods/headers
   • If approved, browser sends actual request

🍪 Credentialed Requests
   • Requests with cookies, HTTP authentication
   • XMLHttpRequest.withCredentials = true
   • fetch(url, { credentials: 'include' })
   • Server must explicitly allow credentials
   • Access-Control-Allow-Credentials: true

🚫 CORS Error Scenarios
   • Missing Access-Control-Allow-Origin header
   • Origin not in allowed origins list
   • Preflight request denied
   • Credentials included but not allowed
   • Custom headers not permitted

Advanced CORS Implementation

Building robust CORS systems requires understanding request types, proper header configuration, security considerations, and dynamic policy management for complex web architectures.

Enterprise-Grade CORS Management Framework

/**
 * Advanced Cross-Origin Resource Sharing (CORS) Management System
 * Comprehensive framework for secure and flexible cross-origin request handling
 */

class CORSManager {
  constructor(config = {}) {
    this.config = {
      // Default CORS policy
      defaultPolicy: {
        allowOrigins: config.allowOrigins || [],
        allowMethods: config.allowMethods || ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
        allowHeaders: config.allowHeaders || ['Content-Type', 'Authorization', 'X-Requested-With'],
        exposeHeaders: config.exposeHeaders || [],
        allowCredentials: config.allowCredentials || false,
        maxAge: config.maxAge || 86400, // 24 hours
      },
      
      // Security settings
      strictMode: config.strictMode !== false,
      enableWildcardOrigins: config.enableWildcardOrigins || false,
      enableDynamicOrigins: config.enableDynamicOrigins || false,
      originValidationRules: config.originValidationRules || [],
      
      // Policy management
      enablePolicyRouting: config.enablePolicyRouting || false,
      routePolicies: config.routePolicies || {},
      enableOriginWhitelisting: config.enableOriginWhitelisting !== false,
      
      // Monitoring and logging
      enableRequestLogging: config.enableRequestLogging || false,
      enableViolationReporting: config.enableViolationReporting || false,
      reportingEndpoint: config.reportingEndpoint || '/api/cors-violations',
      
      // Performance optimizations
      enableCaching: config.enableCaching !== false,
      cacheTimeout: config.cacheTimeout || 300000, // 5 minutes
      
      // Development features
      developmentMode: config.developmentMode || false,
      enableCORSDebugging: config.enableCORSDebugging || false,
      
      ...config
    };

    // Internal state
    this.originCache = new Map();
    this.policyCache = new Map();
    this.corsViolations = [];
    this.requestStats = new Map();
    
    // Trusted origin patterns
    this.trustedOriginPatterns = new Set();
    this.blockedOriginPatterns = new Set();
    
    // Statistics
    this.stats = {
      requestsProcessed: 0,
      preflightRequests: 0,
      requestsAllowed: 0,
      requestsBlocked: 0,
      violationsReported: 0
    };

    this.initialize();
  }

  // Initialize CORS manager
  initialize() {
    // Set up trusted origin patterns
    this.setupOriginPatterns();
    
    // Initialize policy cache
    this.initializePolicyCache();
    
    // Set up violation monitoring
    if (this.config.enableViolationReporting) {
      this.setupViolationMonitoring();
    }
  }

  // Main CORS processing method
  async processCORSRequest(request, response, options = {}) {
    this.stats.requestsProcessed++;
    
    const origin = request.headers.origin;
    const method = request.method;
    const requestHeaders = request.headers;
    
    // Get applicable CORS policy
    const policy = await this.getCORSPolicy(request, options);
    
    // Process different request types
    if (method === 'OPTIONS') {
      return this.handlePreflightRequest(request, response, policy);
    } else {
      return this.handleSimpleRequest(request, response, policy);
    }
  }

  // Handle preflight OPTIONS requests
  async handlePreflightRequest(request, response, policy) {
    this.stats.preflightRequests++;
    
    const origin = request.headers.origin;
    const requestedMethod = request.headers['access-control-request-method'];
    const requestedHeaders = request.headers['access-control-request-headers'];
    
    // Validate origin
    const originAllowed = this.isOriginAllowed(origin, policy);
    if (!originAllowed) {
      this.recordViolation({
        type: 'origin-not-allowed',
        origin,
        method: requestedMethod,
        timestamp: Date.now()
      });
      return this.denyPreflightRequest(response, 'Origin not allowed');
    }
    
    // Validate requested method
    const methodAllowed = policy.allowMethods.includes(requestedMethod) ||
                         policy.allowMethods.includes('*');
    if (!methodAllowed) {
      this.recordViolation({
        type: 'method-not-allowed',
        origin,
        method: requestedMethod,
        timestamp: Date.now()
      });
      return this.denyPreflightRequest(response, 'Method not allowed');
    }
    
    // Validate requested headers
    if (requestedHeaders) {
      const headersArray = requestedHeaders.split(',').map(h => h.trim().toLowerCase());
      const invalidHeaders = headersArray.filter(header => 
        !this.isHeaderAllowed(header, policy)
      );
      
      if (invalidHeaders.length > 0) {
        this.recordViolation({
          type: 'headers-not-allowed',
          origin,
          method: requestedMethod,
          headers: invalidHeaders,
          timestamp: Date.now()
        });
        return this.denyPreflightRequest(response, `Headers not allowed: ${invalidHeaders.join(', ')}`);
      }
    }
    
    // Approve preflight request
    this.stats.requestsAllowed++;
    return this.approvePreflightRequest(response, policy, {
      requestedMethod,
      requestedHeaders
    });
  }

  // Handle simple CORS requests
  async handleSimpleRequest(request, response, policy) {
    const origin = request.headers.origin;
    
    if (!origin) {
      // Same-origin request, no CORS headers needed
      return { allowed: true, corsHeaders: {} };
    }
    
    // Validate origin for simple request
    const originAllowed = this.isOriginAllowed(origin, policy);
    if (!originAllowed) {
      this.recordViolation({
        type: 'simple-request-blocked',
        origin,
        method: request.method,
        timestamp: Date.now()
      });
      this.stats.requestsBlocked++;
      return { allowed: false, reason: 'Origin not allowed' };
    }
    
    this.stats.requestsAllowed++;
    
    // Generate CORS response headers
    const corsHeaders = this.generateCORSHeaders(origin, policy);
    
    return {
      allowed: true,
      corsHeaders
    };
  }

  // Get CORS policy for request
  async getCORSPolicy(request, options = {}) {
    // Check for route-specific policy
    if (this.config.enablePolicyRouting) {
      const routePolicy = this.getRoutePolicyPolicy(request.url);
      if (routePolicy) {
        return routePolicy;
      }
    }
    
    // Check for custom policy in options
    if (options.policy) {
      return this.mergePolicies(this.config.defaultPolicy, options.policy);
    }
    
    // Return default policy
    return this.config.defaultPolicy;
  }

  // Origin validation
  isOriginAllowed(origin, policy) {
    if (!origin) return false;
    
    // Check wildcard
    if (policy.allowOrigins.includes('*')) {
      if (this.config.enableWildcardOrigins) {
        return !this.isOriginBlocked(origin);
      } else if (this.config.strictMode) {
        return false; // Wildcard not allowed in strict mode
      }
    }
    
    // Check exact matches
    if (policy.allowOrigins.includes(origin)) {
      return !this.isOriginBlocked(origin);
    }
    
    // Check pattern matches
    if (this.config.enableDynamicOrigins) {
      return this.matchesOriginPattern(origin, policy);
    }
    
    return false;
  }

  // Check if origin matches allowed patterns
  matchesOriginPattern(origin, policy) {
    // Check trusted patterns
    for (const pattern of this.trustedOriginPatterns) {
      if (this.testOriginPattern(origin, pattern)) {
        return true;
      }
    }
    
    // Check policy-specific patterns
    if (policy.originPatterns) {
      for (const pattern of policy.originPatterns) {
        if (this.testOriginPattern(origin, pattern)) {
          return true;
        }
      }
    }
    
    return false;
  }

  // Test origin against pattern
  testOriginPattern(origin, pattern) {
    if (typeof pattern === 'string') {
      // Simple string pattern with wildcards
      const regex = new RegExp(
        '^' + pattern.replace(/\*/g, '.*').replace(/\./g, '\\.') + '$'
      );
      return regex.test(origin);
    } else if (pattern instanceof RegExp) {
      return pattern.test(origin);
    }
    
    return false;
  }

  // Check if origin is explicitly blocked
  isOriginBlocked(origin) {
    for (const pattern of this.blockedOriginPatterns) {
      if (this.testOriginPattern(origin, pattern)) {
        return true;
      }
    }
    
    return false;
  }

  // Header validation
  isHeaderAllowed(header, policy) {
    const lowerHeader = header.toLowerCase();
    
    // Always allowed headers (simple headers)
    const simpleHeaders = [
      'accept',
      'accept-language',
      'content-language',
      'content-type'
    ];
    
    if (simpleHeaders.includes(lowerHeader)) {
      return true;
    }
    
    // Check policy allowed headers
    const allowedHeaders = policy.allowHeaders.map(h => h.toLowerCase());
    return allowedHeaders.includes(lowerHeader) || allowedHeaders.includes('*');
  }

  // Approve preflight request
  approvePreflightRequest(response, policy, requestDetails) {
    const corsHeaders = {
      'Access-Control-Allow-Origin': this.getOriginHeader(response.origin, policy),
      'Access-Control-Allow-Methods': policy.allowMethods.join(', '),
      'Access-Control-Max-Age': policy.maxAge.toString()
    };
    
    // Add allowed headers
    if (policy.allowHeaders.length > 0) {
      corsHeaders['Access-Control-Allow-Headers'] = policy.allowHeaders.join(', ');
    }
    
    // Add credentials header if needed
    if (policy.allowCredentials) {
      corsHeaders['Access-Control-Allow-Credentials'] = 'true';
    }
    
    // Add Vary header for security
    corsHeaders['Vary'] = 'Origin, Access-Control-Request-Method, Access-Control-Request-Headers';
    
    return {
      allowed: true,
      corsHeaders,
      status: 204 // No Content for preflight
    };
  }

  // Deny preflight request
  denyPreflightRequest(response, reason) {
    this.stats.requestsBlocked++;
    
    return {
      allowed: false,
      reason,
      corsHeaders: {},
      status: 403 // Forbidden
    };
  }

  // Generate CORS response headers for simple requests
  generateCORSHeaders(origin, policy) {
    const corsHeaders = {
      'Access-Control-Allow-Origin': this.getOriginHeader(origin, policy)
    };
    
    // Add exposed headers
    if (policy.exposeHeaders && policy.exposeHeaders.length > 0) {
      corsHeaders['Access-Control-Expose-Headers'] = policy.exposeHeaders.join(', ');
    }
    
    // Add credentials header if needed
    if (policy.allowCredentials) {
      corsHeaders['Access-Control-Allow-Credentials'] = 'true';
    }
    
    // Add Vary header for caching
    corsHeaders['Vary'] = 'Origin';
    
    return corsHeaders;
  }

  // Get appropriate origin header value
  getOriginHeader(origin, policy) {
    if (policy.allowOrigins.includes('*') && !policy.allowCredentials) {
      return '*';
    }
    
    return origin;
  }

  // Route-specific policy management
  getRoutePolicyPolicy(url) {
    for (const [pattern, policy] of Object.entries(this.config.routePolicies)) {
      if (this.matchesRoutePattern(url, pattern)) {
        return this.mergePolicies(this.config.defaultPolicy, policy);
      }
    }
    
    return null;
  }

  matchesRoutePattern(url, pattern) {
    if (typeof pattern === 'string') {
      const regex = new RegExp(
        '^' + pattern.replace(/\*/g, '.*').replace(/\//g, '\\/') + '$'
      );
      return regex.test(url);
    } else if (pattern instanceof RegExp) {
      return pattern.test(url);
    }
    
    return false;
  }

  // Policy merging
  mergePolicies(basePolicy, overridePolicy) {
    return {
      allowOrigins: overridePolicy.allowOrigins || basePolicy.allowOrigins,
      allowMethods: overridePolicy.allowMethods || basePolicy.allowMethods,
      allowHeaders: overridePolicy.allowHeaders || basePolicy.allowHeaders,
      exposeHeaders: overridePolicy.exposeHeaders || basePolicy.exposeHeaders,
      allowCredentials: overridePolicy.allowCredentials !== undefined ? 
        overridePolicy.allowCredentials : 
        basePolicy.allowCredentials,
      maxAge: overridePolicy.maxAge || basePolicy.maxAge,
      originPatterns: overridePolicy.originPatterns || basePolicy.originPatterns
    };
  }

  // Violation recording and reporting
  recordViolation(violation) {
    this.corsViolations.push(violation);
    this.stats.violationsReported++;
    
    if (this.config.enableRequestLogging) {
      console.warn('CORS Violation:', violation);
    }
    
    if (this.config.enableViolationReporting) {
      this.reportViolation(violation);
    }
  }

  async reportViolation(violation) {
    if (!this.config.reportingEndpoint) return;
    
    try {
      await fetch(this.config.reportingEndpoint, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          type: 'cors-violation',
          violation,
          timestamp: Date.now(),
          userAgent: typeof navigator !== 'undefined' ? navigator.userAgent : 'server'
        })
      });
    } catch (error) {
      console.error('Failed to report CORS violation:', error);
    }
  }

  // Origin pattern management
  setupOriginPatterns() {
    // Common trusted patterns for development
    if (this.config.developmentMode) {
      this.trustedOriginPatterns.add('http://localhost:*');
      this.trustedOriginPatterns.add('http://127.0.0.1:*');
      this.trustedOriginPatterns.add('https://*.local');
    }
    
    // Add custom patterns from config
    if (this.config.trustedOrigins) {
      this.config.trustedOrigins.forEach(pattern => {
        this.trustedOriginPatterns.add(pattern);
      });
    }
    
    if (this.config.blockedOrigins) {
      this.config.blockedOrigins.forEach(pattern => {
        this.blockedOriginPatterns.add(pattern);
      });
    }
  }

  // Cache management
  initializePolicyCache() {
    // Pre-cache common origin checks
    if (this.config.defaultPolicy.allowOrigins) {
      this.config.defaultPolicy.allowOrigins.forEach(origin => {
        if (origin !== '*') {
          this.originCache.set(origin, {
            allowed: true,
            timestamp: Date.now(),
            expiresAt: Date.now() + this.config.cacheTimeout
          });
        }
      });
    }
  }

  getCachedOriginResult(origin) {
    if (!this.config.enableCaching) return null;
    
    const cached = this.originCache.get(origin);
    if (!cached || Date.now() > cached.expiresAt) {
      this.originCache.delete(origin);
      return null;
    }
    
    return cached;
  }

  setCachedOriginResult(origin, allowed) {
    if (!this.config.enableCaching) return;
    
    this.originCache.set(origin, {
      allowed,
      timestamp: Date.now(),
      expiresAt: Date.now() + this.config.cacheTimeout
    });
  }

  // Monitoring and analytics
  setupViolationMonitoring() {
    // Monitor for common attack patterns
    setInterval(() => {
      this.analyzeViolationPatterns();
    }, 60000); // Every minute
  }

  analyzeViolationPatterns() {
    const recentViolations = this.corsViolations.filter(v => 
      Date.now() - v.timestamp < 300000 // Last 5 minutes
    );
    
    if (recentViolations.length > 10) {
      console.warn(`High CORS violation rate: ${recentViolations.length} violations in 5 minutes`);
      
      // Analyze violation types
      const violationTypes = {};
      recentViolations.forEach(v => {
        violationTypes[v.type] = (violationTypes[v.type] || 0) + 1;
      });
      
      console.warn('Violation breakdown:', violationTypes);
    }
  }

  // Express.js middleware factory
  createMiddleware(options = {}) {
    return async (req, res, next) => {
      try {
        const corsResult = await this.processCORSRequest(req, res, options);
        
        if (corsResult.corsHeaders) {
          // Apply CORS headers
          Object.entries(corsResult.corsHeaders).forEach(([key, value]) => {
            res.setHeader(key, value);
          });
        }
        
        if (req.method === 'OPTIONS') {
          // Handle preflight request
          res.status(corsResult.status || 200).end();
        } else if (!corsResult.allowed) {
          // Block request
          res.status(403).json({
            error: 'CORS policy violation',
            reason: corsResult.reason
          });
        } else {
          // Allow request to continue
          next();
        }
      } catch (error) {
        console.error('CORS middleware error:', error);
        res.status(500).json({ error: 'Internal server error' });
      }
    };
  }

  // Dynamic policy updates
  updatePolicy(policyUpdates) {
    this.config.defaultPolicy = this.mergePolicies(
      this.config.defaultPolicy,
      policyUpdates
    );
    
    // Clear caches
    this.originCache.clear();
    this.policyCache.clear();
    
    // Reinitialize
    this.initialize();
  }

  addAllowedOrigin(origin) {
    if (!this.config.defaultPolicy.allowOrigins.includes(origin)) {
      this.config.defaultPolicy.allowOrigins.push(origin);
      this.setCachedOriginResult(origin, true);
    }
  }

  removeAllowedOrigin(origin) {
    const index = this.config.defaultPolicy.allowOrigins.indexOf(origin);
    if (index > -1) {
      this.config.defaultPolicy.allowOrigins.splice(index, 1);
      this.originCache.delete(origin);
    }
  }

  // Security analysis
  analyzeSecurityPosture() {
    const analysis = {
      riskLevel: 'low',
      risks: [],
      recommendations: [],
      configuration: {
        wildcardOrigins: this.config.defaultPolicy.allowOrigins.includes('*'),
        credentialsAllowed: this.config.defaultPolicy.allowCredentials,
        strictMode: this.config.strictMode
      }
    };
    
    // Check for high-risk configurations
    if (analysis.configuration.wildcardOrigins && analysis.configuration.credentialsAllowed) {
      analysis.riskLevel = 'critical';
      analysis.risks.push('Wildcard origins with credentials allowed');
      analysis.recommendations.push('Never use wildcard origins with credentials');
    }
    
    if (analysis.configuration.wildcardOrigins && !this.config.strictMode) {
      analysis.riskLevel = 'high';
      analysis.risks.push('Wildcard origins in permissive mode');
      analysis.recommendations.push('Enable strict mode or specify exact origins');
    }
    
    // Check violation patterns
    const recentViolations = this.corsViolations.filter(v => 
      Date.now() - v.timestamp < 3600000 // Last hour
    );
    
    if (recentViolations.length > 50) {
      analysis.riskLevel = 'high';
      analysis.risks.push('High CORS violation rate detected');
      analysis.recommendations.push('Investigate potential attack or misconfiguration');
    }
    
    return analysis;
  }

  // Public API methods
  getStats() {
    return {
      ...this.stats,
      cacheInfo: {
        originCacheSize: this.originCache.size,
        policyCacheSize: this.policyCache.size
      },
      recentViolations: this.corsViolations.slice(-10)
    };
  }

  getSecurityReport() {
    return {
      timestamp: Date.now(),
      stats: this.getStats(),
      securityAnalysis: this.analyzeSecurityPosture(),
      policyConfiguration: this.config.defaultPolicy,
      trustedPatterns: Array.from(this.trustedOriginPatterns),
      blockedPatterns: Array.from(this.blockedOriginPatterns)
    };
  }

  // Cleanup
  destroy() {
    this.originCache.clear();
    this.policyCache.clear();
    this.corsViolations = [];
  }
}

// Custom error class
class CORSError extends Error {
  constructor(message, details) {
    super(message);
    this.name = 'CORSError';
    this.details = details;
  }
}

// Usage Examples
const corsManager = new CORSManager({
  defaultPolicy: {
    allowOrigins: ['https://app.example.com', 'https://admin.example.com'],
    allowMethods: ['GET', 'POST', 'PUT', 'DELETE'],
    allowHeaders: ['Content-Type', 'Authorization', 'X-API-Key'],
    exposeHeaders: ['X-Total-Count', 'X-Rate-Limit-Remaining'],
    allowCredentials: true,
    maxAge: 86400
  },
  strictMode: true,
  enableViolationReporting: true,
  reportingEndpoint: '/api/cors-violations'
});

// Example 1: Express.js middleware
const express = require('express');
const app = express();

// Use CORS middleware
app.use(corsManager.createMiddleware());

// Route-specific CORS policy
app.use('/api/public', corsManager.createMiddleware({
  policy: {
    allowOrigins: ['*'],
    allowCredentials: false
  }
}));

// Example 2: Manual CORS handling
app.use(async (req, res, next) => {
  const corsResult = await corsManager.processCORSRequest(req, res);
  
  if (corsResult.corsHeaders) {
    Object.entries(corsResult.corsHeaders).forEach(([key, value]) => {
      res.setHeader(key, value);
    });
  }
  
  if (req.method === 'OPTIONS') {
    res.status(corsResult.status || 200).end();
  } else if (!corsResult.allowed) {
    res.status(403).json({ error: corsResult.reason });
  } else {
    next();
  }
});

// Example 3: Dynamic origin management
corsManager.addAllowedOrigin('https://new-client.example.com');
corsManager.removeAllowedOrigin('https://old-client.example.com');

// Example 4: Security monitoring
setInterval(() => {
  const report = corsManager.getSecurityReport();
  if (report.securityAnalysis.riskLevel === 'critical') {
    console.error('Critical CORS security risk detected:', report);
    // Send alert to security team
  }
}, 300000); // Every 5 minutes

// Example 5: Route-specific policies
const corsWithRoutePolicies = new CORSManager({
  enablePolicyRouting: true,
  routePolicies: {
    '/api/auth/*': {
      allowOrigins: ['https://login.example.com'],
      allowCredentials: true,
      allowHeaders: ['Content-Type', 'Authorization']
    },
    '/api/public/*': {
      allowOrigins: ['*'],
      allowCredentials: false,
      allowHeaders: ['Content-Type']
    },
    '/api/admin/*': {
      allowOrigins: ['https://admin.example.com'],
      allowCredentials: true,
      allowHeaders: ['Content-Type', 'Authorization', 'X-Admin-Token']
    }
  }
});

export { CORSManager, CORSError };

Understanding the CORS Management Framework Code

Let's explore how this comprehensive CORS system works and why each component is essential for secure cross-origin communication.

1. Framework Architecture and Request Processing

The Core CORS Philosophy: The CORSManager implements a policy-based approach that evaluates each cross-origin request against configured security rules and determines whether to allow or block the request.

Request Flow Processing:

async processCORSRequest(request, response, options = {}) {
  const origin = request.headers.origin;
  const method = request.method;
  
  // Get applicable CORS policy
  const policy = await this.getCORSPolicy(request, options);
  
  // Process different request types
  if (method === 'OPTIONS') {
    return this.handlePreflightRequest(request, response, policy);
  } else {
    return this.handleSimpleRequest(request, response, policy);
  }
}

Why This Flow Works:

Request Type Detection: Different handling for preflight vs simple requests
Policy Selection: Dynamic policy based on route, origin, or custom rules
Origin Validation: Comprehensive origin checking against multiple criteria
Header Generation: Proper CORS headers based on policy and request type

2. Preflight Request Handling

Preflight Validation Process:

async handlePreflightRequest(request, response, policy) {
  const origin = request.headers.origin;
  const requestedMethod = request.headers['access-control-request-method'];
  const requestedHeaders = request.headers['access-control-request-headers'];
  
  // Validate origin
  const originAllowed = this.isOriginAllowed(origin, policy);
  if (!originAllowed) {
    return this.denyPreflightRequest(response, 'Origin not allowed');
  }
  
  // Validate requested method
  const methodAllowed = policy.allowMethods.includes(requestedMethod);
  if (!methodAllowed) {
    return this.denyPreflightRequest(response, 'Method not allowed');
  }
  
  // Validate requested headers
  if (requestedHeaders) {
    const headersArray = requestedHeaders.split(',').map(h => h.trim().toLowerCase());
    const invalidHeaders = headersArray.filter(header => 
      !this.isHeaderAllowed(header, policy)
    );
    
    if (invalidHeaders.length > 0) {
      return this.denyPreflightRequest(response, `Headers not allowed: ${invalidHeaders.join(', ')}`);
    }
  }
  
  return this.approvePreflightRequest(response, policy);
}

Preflight Security Checks:

Origin Validation: Ensure requesting origin is allowed
Method Validation: Verify HTTP method is permitted
Header Validation: Check all requested headers are allowed
Policy Compliance: All checks must pass for approval

3. Origin Validation System

Comprehensive Origin Checking:

isOriginAllowed(origin, policy) {
  if (!origin) return false;
  
  // Check wildcard
  if (policy.allowOrigins.includes('*')) {
    if (this.config.enableWildcardOrigins) {
      return !this.isOriginBlocked(origin);
    } else if (this.config.strictMode) {
      return false; // Wildcard not allowed in strict mode
    }
  }
  
  // Check exact matches
  if (policy.allowOrigins.includes(origin)) {
    return !this.isOriginBlocked(origin);
  }
  
  // Check pattern matches
  if (this.config.enableDynamicOrigins) {
    return this.matchesOriginPattern(origin, policy);
  }
  
  return false;
}

Origin Matching Strategies:

Exact Match: Direct string comparison for specific origins
Wildcard Support: Controlled wildcard usage with security checks
Pattern Matching: Regex patterns for dynamic subdomain support
Blocklist: Explicit blocking of dangerous origins

Pattern Matching Examples:

// Pattern: "https://*.example.com"
// Matches: "https://app.example.com", "https://api.example.com"
// Doesn't match: "https://evil.com", "https://fake-example.com"

testOriginPattern(origin, pattern) {
  if (typeof pattern === 'string') {
    const regex = new RegExp(
      '^' + pattern.replace(/\*/g, '.*').replace(/\./g, '\\.') + '$'
    );
    return regex.test(origin);
  } else if (pattern instanceof RegExp) {
    return pattern.test(origin);
  }
  
  return false;
}

4. Route-Based Policy Management

Dynamic Policy Selection:

getRoutePolicyPolicy(url) {
  for (const [pattern, policy] of Object.entries(this.config.routePolicies)) {
    if (this.matchesRoutePattern(url, pattern)) {
      return this.mergePolicies(this.config.defaultPolicy, policy);
    }
  }
  
  return null;
}

Route-Specific Security:

// Configuration example
routePolicies: {
  '/api/auth/*': {
    allowOrigins: ['https://login.example.com'],
    allowCredentials: true,
    allowHeaders: ['Content-Type', 'Authorization']
  },
  '/api/public/*': {
    allowOrigins: ['*'],
    allowCredentials: false,
    allowHeaders: ['Content-Type']
  }
}

Benefits of Route-Based Policies:

Granular Control: Different security levels for different endpoints
Least Privilege: Minimal permissions for each route
Context-Aware: Policy based on the resource being accessed
Maintenance: Centralized policy management

5. Security Violation Monitoring

Violation Detection and Reporting:

recordViolation(violation) {
  this.corsViolations.push(violation);
  this.stats.violationsReported++;
  
  if (this.config.enableRequestLogging) {
    console.warn('CORS Violation:', violation);
  }
  
  if (this.config.enableViolationReporting) {
    this.reportViolation(violation);
  }
}

Violation Types Tracked:

origin-not-allowed: Blocked origin attempting access
method-not-allowed: Unsupported HTTP method requested
headers-not-allowed: Restricted headers in request
simple-request-blocked: Simple request from blocked origin

6. Performance Optimization

Caching Strategy:

getCachedOriginResult(origin) {
  if (!this.config.enableCaching) return null;
  
  const cached = this.originCache.get(origin);
  if (!cached || Date.now() > cached.expiresAt) {
    this.originCache.delete(origin);
    return null;
  }
  
  return cached;
}

Cache Benefits:

Performance: Avoid repeated origin validation
Scalability: Handle high request volumes efficiently
Consistency: Same origin decisions during cache period
Memory Management: Automatic cleanup of expired entries

7. Express.js Middleware Integration

Middleware Factory:

createMiddleware(options = {}) {
  return async (req, res, next) => {
    try {
      const corsResult = await this.processCORSRequest(req, res, options);
      
      if (corsResult.corsHeaders) {
        Object.entries(corsResult.corsHeaders).forEach(([key, value]) => {
          res.setHeader(key, value);
        });
      }
      
      if (req.method === 'OPTIONS') {
        res.status(corsResult.status || 200).end();
      } else if (!corsResult.allowed) {
        res.status(403).json({
          error: 'CORS policy violation',
          reason: corsResult.reason
        });
      } else {
        next();
      }
    } catch (error) {
      console.error('CORS middleware error:', error);
      res.status(500).json({ error: 'Internal server error' });
    }
  };
}

Integration Examples:

// Global CORS
app.use(corsManager.createMiddleware());

// Route-specific CORS
app.use('/api/public', corsManager.createMiddleware({
  policy: { allowOrigins: ['*'], allowCredentials: false }
}));

// Method-specific CORS
app.options('/api/sensitive', corsManager.createMiddleware({
  policy: { allowOrigins: ['https://trusted.com'] }
}));

8. Security Analysis and Monitoring

Security Posture Analysis:

analyzeSecurityPosture() {
  const analysis = {
    riskLevel: 'low',
    risks: [],
    recommendations: []
  };
  
  // Check for high-risk configurations
  if (wildcardOrigins && credentialsAllowed) {
    analysis.riskLevel = 'critical';
    analysis.risks.push('Wildcard origins with credentials allowed');
    analysis.recommendations.push('Never use wildcard origins with credentials');
  }
  
  return analysis;
}

Critical Security Checks:

Wildcard + Credentials: Never allow both together
Overly Permissive: Too many allowed origins
Missing Validation: Insufficient origin checking
High Violation Rate: Potential attacks or misconfigurations

This comprehensive CORS management framework provides enterprise-grade cross-origin security through intelligent request processing, dynamic policy management, comprehensive violation monitoring, and seamless integration with modern web application architectures.

Summary

Cross-Origin Resource Sharing (CORS) represents a fundamental web security mechanism that enables controlled relaxation of the Same-Origin Policy while maintaining protection against cross-origin attacks. By implementing comprehensive CORS management through intelligent policy configuration, dynamic origin validation, and sophisticated monitoring systems, applications can safely enable cross-domain communication while preventing unauthorized access and maintaining security boundaries.

CORS Security Excellence Benefits:

Controlled Access: Precise control over which origins can access your resources and under what conditions
Attack Prevention: Protection against cross-origin attacks while enabling legitimate cross-domain functionality
Policy Flexibility: Route-based and context-aware policies for granular security control
Violation Monitoring: Real-time detection and analysis of CORS policy violations for security intelligence

Advanced CORS Management Capabilities:

Dynamic Policy Management: Runtime policy updates and origin management for changing requirements
Pattern-Based Validation: Sophisticated origin matching including wildcard and regex support
Performance Optimization: Intelligent caching and request processing for high-performance applications
Security Analysis: Automated risk assessment and security posture evaluation

CORS Architecture Patterns:

Defense in Depth: CORS as part of comprehensive web application security strategy
Least Privilege Access: Minimal necessary permissions for each resource and origin
Monitoring and Alerting: Continuous security monitoring with violation detection and reporting
Policy-Based Security: Declarative security policies that adapt to application requirements

CORS transforms web applications from isolated silos into secure, interconnected systems that can safely communicate across origins while maintaining strict security boundaries and preventing unauthorized access through sophisticated policy enforcement and monitoring.

Effective CORS implementation doesn't just enable cross-origin requests—it creates a security framework where applications can safely interact across domains while maintaining complete control over access permissions and detecting potential security threats.