CORS Deep Dive: Configuring Cross-Origin Resource Sharing

// ❌ Common misconception: CORS blocks the request
// Reality: The request IS sent. The browser blocks the RESPONSE.
// Your server processes the request either way!
 
// This means CORS alone doesn't prevent server-side effects.
// A POST that creates a database record still executes.
// The browser just hides the response from JavaScript.

// The browser's CORS decision flow:
interface CORSCheck {
  step1: "Is request origin different from resource origin?";
  step2: "If same-origin → allow, no CORS headers needed";
  step3: "If cross-origin → check Access-Control-Allow-Origin header";
  step4: "If header matches origin → allow JavaScript to read response";
  step5: "If header missing or mismatched → block response from JS";
}
 
// For non-simple requests, add a preflight step BEFORE step 1:
interface PreflightCheck {
  trigger: "Custom headers, non-GET/POST methods, or non-simple content types";
  action: "Send OPTIONS request with Access-Control-Request-* headers";
  serverResponds: "With Access-Control-Allow-* headers declaring policy";
  browserDecides: "Whether to send the actual request based on the policy";
}

// ❌ Not understanding why a preflight is triggered
// "My GET request shouldn't need a preflight!"
// It does if you added custom headers:
fetch("https://api.example.com/data", {
  headers: {
    Authorization: "Bearer token123",  // Custom header → preflight
    "X-Request-Id": "abc",            // Custom header → preflight
  },
});

// Express middleware: properly handling preflight
import express, { Request, Response, NextFunction } from "express";
 
const ALLOWED_ORIGINS = new Set([
  "https://app.example.com",
  "https://staging.example.com",
]);
 
function corsMiddleware(
  req: Request,
  res: Response,
  next: NextFunction
): void {
  const origin = req.headers.origin;
 
  // Only set CORS headers for allowed origins
  if (origin && ALLOWED_ORIGINS.has(origin)) {
    res.setHeader("Access-Control-Allow-Origin", origin);
    res.setHeader("Vary", "Origin"); // Critical for caching
 
    // Handle preflight
    if (req.method === "OPTIONS") {
      res.setHeader(
        "Access-Control-Allow-Methods",
        "GET, POST, PUT, DELETE, PATCH"
      );
      res.setHeader(
        "Access-Control-Allow-Headers",
        "Content-Type, Authorization, X-Request-Id"
      );
      res.setHeader(
        "Access-Control-Max-Age",
        "86400" // Cache preflight for 24 hours
      );
      res.status(204).end();
      return;
    }
  }
 
  next();
}
 
const app = express();
app.use(corsMiddleware);

// ❌ Reflecting any origin back (equivalent to wildcard)
function unsafeCors(req: Request, res: Response, next: NextFunction) {
  res.setHeader(
    "Access-Control-Allow-Origin",
    req.headers.origin ?? "*" // Reflects attacker's origin!
  );
  next();
}

// ✅ Validating origins against a pattern
function isAllowedOrigin(origin: string): boolean {
  const allowedPatterns = [
    /^https:\/\/app\.example\.com$/,
    /^https:\/\/[a-z0-9-]+\.preview\.example\.com$/,
    /^https:\/\/staging\.example\.com$/,
  ];
 
  // In development, also allow localhost
  if (process.env.NODE_ENV === "development") {
    allowedPatterns.push(/^http:\/\/localhost:\d+$/);
  }
 
  return allowedPatterns.some(pattern => pattern.test(origin));
}
 
function secureCorsMiddleware(
  req: Request,
  res: Response,
  next: NextFunction
): void {
  const origin = req.headers.origin;
 
  if (origin && isAllowedOrigin(origin)) {
    res.setHeader("Access-Control-Allow-Origin", origin);
    res.setHeader("Vary", "Origin");
 
    if (req.method === "OPTIONS") {
      res.setHeader(
        "Access-Control-Allow-Methods",
        "GET, POST, PUT, DELETE"
      );
      res.setHeader(
        "Access-Control-Allow-Headers",
        "Content-Type, Authorization"
      );
      res.setHeader("Access-Control-Max-Age", "86400");
      res.status(204).end();
      return;
    }
  }
 
  next();
}

// ❌ This doesn't work: wildcard + credentials
res.setHeader("Access-Control-Allow-Origin", "*");
res.setHeader("Access-Control-Allow-Credentials", "true");
// Browser error: Cannot use wildcard with credentials
 
// ❌ Reflecting origin without validation + credentials
res.setHeader("Access-Control-Allow-Origin", req.headers.origin);
res.setHeader("Access-Control-Allow-Credentials", "true");
// Security hole: any site can make authenticated requests

// ✅ Explicit origin with credentials
function credentialedCorsMiddleware(
  req: Request,
  res: Response,
  next: NextFunction
): void {
  const origin = req.headers.origin;
 
  if (origin && isAllowedOrigin(origin)) {
    res.setHeader("Access-Control-Allow-Origin", origin);
    res.setHeader("Access-Control-Allow-Credentials", "true");
    res.setHeader("Vary", "Origin");
 
    // Expose specific response headers to JavaScript
    res.setHeader(
      "Access-Control-Expose-Headers",
      "X-Total-Count, X-Request-Id"
    );
 
    if (req.method === "OPTIONS") {
      res.setHeader(
        "Access-Control-Allow-Methods",
        "GET, POST, PUT, DELETE"
      );
      res.setHeader(
        "Access-Control-Allow-Headers",
        "Content-Type, Authorization"
      );
      res.setHeader("Access-Control-Max-Age", "3600");
      res.status(204).end();
      return;
    }
  }
 
  next();
}

// Client-side: must explicitly opt into credentials
const response = await fetch("https://api.example.com/user", {
  credentials: "include", // Send cookies cross-origin
  headers: {
    "Content-Type": "application/json",
  },
});

// Next.js API route
import type { NextApiRequest, NextApiResponse } from "next";
 
const allowedOrigins = ["https://app.example.com"];
 
export default function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const origin = req.headers.origin;
 
  if (origin && allowedOrigins.includes(origin)) {
    res.setHeader("Access-Control-Allow-Origin", origin);
    res.setHeader("Vary", "Origin");
  }
 
  if (req.method === "OPTIONS") {
    res.setHeader("Access-Control-Allow-Methods", "GET, POST");
    res.setHeader("Access-Control-Allow-Headers", "Content-Type");
    res.setHeader("Access-Control-Max-Age", "86400");
    return res.status(204).end();
  }
 
  res.json({ data: "response" });
}

# FastAPI with strict CORS
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
 
app = FastAPI()
 
app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "https://app.example.com",
        "https://staging.example.com",
    ],
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE"],
    allow_headers=["Content-Type", "Authorization"],
    expose_headers=["X-Total-Count"],
    max_age=86400,
)

// Go with chi router
package main
 
import (
    "net/http"
    "github.com/go-chi/cors"
)
 
func main() {
    r := chi.NewRouter()
 
    r.Use(cors.Handler(cors.Options{
        AllowedOrigins:   []string{"https://app.example.com"},
        AllowedMethods:   []string{"GET", "POST", "PUT", "DELETE"},
        AllowedHeaders:   []string{"Content-Type", "Authorization"},
        ExposedHeaders:   []string{"X-Total-Count"},
        AllowCredentials: true,
        MaxAge:           86400,
    }))
}

interface CORSDebugChecklist {
  step: string;
  check: string;
  fix: string;
}
 
const debugChecklist: CORSDebugChecklist[] = [
  {
    step: "1. Check the actual error message",
    check: "Browser console shows which header is missing or wrong",
    fix: "Add the specific header mentioned in the error",
  },
  {
    step: "2. Inspect the preflight",
    check: "Network tab → filter by OPTIONS → check response headers",
    fix: "Ensure OPTIONS returns 204 with correct CORS headers",
  },
  {
    step: "3. Verify Vary header",
    check: "Response includes 'Vary: Origin'",
    fix: "Add Vary header to prevent CDN caching issues",
  },
  {
    step: "4. Check credentials mode",
    check: "If using credentials, origin cannot be wildcard",
    fix: "Set explicit origin and credentials: true",
  },
  {
    step: "5. Check exposed headers",
    check: "Custom response headers readable in JS?",
    fix: "Add Access-Control-Expose-Headers for custom headers",
  },
  {
    step: "6. Check Max-Age",
    check: "Browser might cache a failed preflight",
    fix: "Clear browser cache or use incognito to test",
  },
];