CORS End-to-End

1The one mental model to anchor everything

CORS stands for Cross-Origin Resource Sharing. It is a browser-enforced policy, not a server firewall. The browser blocks the JS from reading a cross-origin response unless the server explicitly grants permission via CORS headers. The server still receives (and processes) most requests — the browser just withholds the response from your code.

Origin = protocol + host + port. All three must match for requests to be "same-origin." https://example.com and https://api.example.com are different origins (different host). http://example.com and https://example.com differ on protocol. https://example.com:8080 differs on port.

2Simple vs preflight: the split

The browser applies different rules depending on how "safe" the request looks. A simple request goes straight through; a preflighted request is preceded by an automatic OPTIONS handshake.

The preflight exchange

-- STEP 1: browser auto-sends OPTIONS --
OPTIONS /api/hotels HTTP/1.1
Origin:                          https://example.com
Access-Control-Request-Method:   POST
Access-Control-Request-Headers:  Content-Type, Authorization

-- STEP 2: server responds (must include these) --
HTTP/1.1 204 No Content
Access-Control-Allow-Origin:    https://example.com
Access-Control-Allow-Methods:   POST, GET, OPTIONS
Access-Control-Allow-Headers:   Content-Type, Authorization
Access-Control-Max-Age:         86400

-- STEP 3: if preflight passes, actual POST fires --

Access-Control-Max-Age caches the preflight result in the browser for that many seconds (Chrome caps at 7200s = 2 hrs). Without it every request in a session fires a new OPTIONS round trip.

3The CORS header reference

4Credentials: the wildcard trap

Credentialed requests (cookies, Authorization headers, TLS certs) need two things to align — client opt-in AND explicit server permission. The * wildcard is banned when credentials are involved.

-- Client opt-in (credentials mode: include) --
fetch('https://api.example.com/profile', {
  credentials: 'include'   // sends cookies cross-origin
});

-- Server must respond with BOTH of these (wildcard * is forbidden) --
Access-Control-Allow-Origin:      https://example.com   // explicit, not *
Access-Control-Allow-Credentials: true

5Debugging CORS cold in DevTools

A systematic approach when you hit a CORS error:

1. Read the exact browser error message. Chrome spells out exactly which header is wrong or missing.
2. Open Network tab, filter by the blocked request URL. Check: did the request reach the server (status code visible)? Or was it blocked before sending?
3. Look for the OPTIONS preflight. If present, inspect its response headers. If absent but expected, the server may not handle OPTIONS at all (common nginx/express oversight).
4. Check the actual response headers on the blocked request: is Access-Control-Allow-Origin present? Does it match the page's origin exactly (scheme + host + port)?
5. Check credentials scenario. Is credentials: 'include' set? Then origin must not be * and Access-Control-Allow-Credentials: true must be present.
6. Check error responses. The server must include CORS headers on 4xx and 5xx responses too — many servers only add them on success paths, so an auth error returns a bare 401 and the browser shows a CORS error instead of the actual status.

Common misconfigurations at a glance

6What CORS does NOT protect

Because CORS is browser-enforced only, it provides zero server-side security:

• curl / Postman / server-to-server calls bypass it entirely — your API is reachable regardless.
• CORS doesn't prevent CSRF. A malicious page can trigger a simple cross-origin POST (e.g. form submit) without CORS; CSRF tokens or SameSite cookies are the real defense.
• CORS is not authentication. Allowing an origin doesn't mean the user is authenticated. Auth is separate (tokens, sessions).

7platform-specific angle

The platform runs a global, multi-subdomain architecture — www.example.com, partner APIs, mobile web, affiliate widgets. In this context:

• Dynamic origin allowlist: maintain a server-side set of approved origins; reflect the request Origin back only if it matches. More flexible than a hardcoded header.
• Preflight caching: set Access-Control-Max-Age: 86400 on stable APIs. On mobile connections (the core audience in Southeast Asia), each saved OPTIONS round-trip is ~50–150ms.
• SSR proxy pattern: many platform pages are SSR — the Node server calls internal APIs. Those calls are server-to-server and CORS doesn't apply. If you move an API call from SSR to the client, CORS suddenly matters. Track this at architectural review.
• CDN and CORS: the platform's APIs serve many origins — partner portals, subdomains, affiliate widgets. Dynamic origin reflection without Vary: Origin is a latent production bomb; see §8.

8Vary: Origin + CDN interaction

This is the subtlest CORS failure mode in production — it works in staging (no CDN) and silently misfires after the CDN warms up.

The cache-key problem

A CDN's default cache key is the URL + Host. The Origin request header is not included. When your server does dynamic origin reflection — checking the request Origin against an allowlist and echoing it back — the response varies per caller origin. But the CDN doesn't know that.

-- Request 1: from https://example.com --
GET /api/hotels  Origin: https://example.com
→ CDN miss → origin server reflects back:
   Access-Control-Allow-Origin: https://example.com
→ CDN stores this response under key: /api/hotels

-- Request 2: from https://partner.example.com --
GET /api/hotels  Origin: https://partner.example.com
→ CDN HIT (same URL!) → returns CACHED response:
   Access-Control-Allow-Origin: https://example.com  ← wrong origin
→ Browser: "partner.example.com ≠ example.com" → CORS ERROR

The fix: Vary: Origin

Vary: Origin is an instruction to the CDN: "include the Origin request header in the cache key." Now each distinct origin gets its own cache entry.

-- Correct response from origin server --
Access-Control-Allow-Origin:  https://example.com
Access-Control-Allow-Credentials: true
Vary:                         Origin

-- CDN now caches separately: --
  /api/hotels + Origin: https://example.com       → entry A
  /api/hotels + Origin: https://partner.example.com → entry B

The cold-start trap

There is a subtler variant. A server-to-server call (a health check, a bot, an SSR Node server) hits the CDN first — with no Origin header at all. The origin server returns a response with no Access-Control-Allow-Origin (nothing to reflect). The CDN caches it. The first browser request is a CDN hit — and gets a response with no ACAO → CORS error.

Vary: Origin fixes this too: requests with no Origin and requests with an Origin are now different cache keys, so they never collide.

When you don't need Vary: Origin

If you return Access-Control-Allow-Origin: *, the response is identical for all origins — there's nothing to vary. No Vary: Origin needed. But remember: wildcard is incompatible with credentials (§4), so for any credentialed endpoint you'll always need dynamic reflection and therefore always need Vary: Origin.

9WebSocket and CORS

WebSockets use a completely different security model from fetch/XHR. The browser's CORS enforcement does not apply. This is the most dangerous misconception about CORS: developers assume the browser protects them; for WebSockets, it doesn't.

What actually happens during a WebSocket connection

A WebSocket starts as an HTTP upgrade request. The browser does send Origin automatically — but it never checks Access-Control-Allow-Origin in the server's response. There is no preflight. There is no CORS validation.

-- Browser sends the HTTP upgrade --
GET /ws HTTP/1.1
Host:                    api.example.com
Upgrade:                 websocket
Connection:              Upgrade
Origin:                  https://example.com   ← browser sends this…
Sec-WebSocket-Key:       dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version:  13

-- Server responds with 101 (no ACAO header needed or checked) --
HTTP/1.1 101 Switching Protocols
Upgrade:                 websocket
Connection:             Upgrade
Sec-WebSocket-Accept:   s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
← no Access-Control-Allow-Origin required or enforced

Cookies + WebSocket = automatic CSRF vector

Unlike fetch, the WebSocket API has no credentials option. The browser always sends same-site cookies on the upgrade request — you can't opt out. This means: a malicious page can open a WebSocket to your server, the victim's session cookie rides along, and if the server doesn't validate Origin, the attacker has an authenticated socket.

-- Malicious page on evil.com --
const ws = new WebSocket('wss://api.example.com/realtime');
// Browser sends: Origin: https://evil.com
// Browser ALSO sends: Cookie: session=<victim's token>  ← automatic
// If server doesn't reject: connection succeeds, attacker reads real-time data

-- Correct server-side defence (Node/ws library) --
const wss = new WebServer({ server });
wss.on('connection', (socket, req) => {
  const origin = req.headers.origin;
  if (!ALLOWED_ORIGINS.has(origin)) {
    socket.close(1008, 'Origin not allowed');   // 1008 = policy violation
    return;
  }
});

Socket.IO: HTTP polling + WebSocket

Socket.IO starts with HTTP long-polling before upgrading to WebSocket. The polling requests do go through CORS (they're regular HTTP). So Socket.IO has its own CORS config that covers the polling phase — but the underlying WebSocket upgrade still relies on the same server-side Origin check:

const io = new Server(server, {
  cors: {
    origin: 'https://example.com',   // covers HTTP polling phase
    credentials: true
  }
});
// Socket.IO's built-in CORS handles the upgrade path too via its own handshake

10Check yourself — scenario quiz