CORS (Cross-Origin Resource Sharing)

1What Problem CORS Solves

The Same-Origin Policy (see the Browser Request Lifecycle topic) blocks JavaScript on origin A from reading responses from origin B by default. That's the right default, but it's too strict for the modern web — a legitimate app on https://app.example.com often needs to call https://api.example.com. CORS is the mechanism by which the server at origin B explicitly tells the browser "responses from me may be read by scripts running on origin A" — via response headers. CORS doesn't loosen anything on its own; it's an opt-in relaxation the server grants, enforced by the browser reading that server's headers.

2The Core Fact: CORS Is Enforced by the Browser, on the Response

This is the single most important — and most commonly misunderstood — fact about CORS:

The server is always reachable. The request is always sent (with the exceptions in §4) and always processed by the server. CORS never stops a request from arriving. CORS only controls whether the browser lets your JavaScript READ the response it already received.

There is no server-side concept of "the request was blocked by CORS." If you see a CORS error in the console, the request very likely succeeded on the server (check server logs — the row got inserted, the email got sent) — the browser is the one refusing to hand the response back to your script. This is why CORS is a browser security feature, not a network security feature: a non-browser client (curl, a mobile app, a server-to-server call, Postman) completely ignores CORS headers, because CORS is implemented in browsers' fetch/XHR machinery, not in HTTP itself.

3Simple Requests vs Preflighted Requests

Not every cross-origin request triggers a preflight. The browser sends a request as a "simple request" — no preflight — only when ALL of the following hold:

• Method is GET, HEAD, or POST
• Only these headers are manually set (beyond ones the browser adds automatically): Accept, Accept-Language, Content-Language, Content-Type (with a restricted value — see below)
• If Content-Type is set, its value is one of: application/x-www-form-urlencoded, multipart/form-data, or text/plain
• No ReadableStream used in the request body
• No listeners registered on the upload progress of an associated XMLHttpRequestUpload

Any request that fails even one of these criteria is not simple, and the browser performs a preflight: an automatic OPTIONS request sent before your actual request, asking the server for permission.

Simple request examples (no preflight):
  GET  https://api.example.com/users
  POST https://api.example.com/users  (Content-Type: application/x-www-form-urlencoded)

Preflighted request examples:
  PUT    https://api.example.com/users/1
  DELETE https://api.example.com/users/1
  POST   https://api.example.com/users  (Content-Type: application/json)   ← the common case!
  GET    https://api.example.com/users  (with a custom header like Authorization or X-Api-Key)

The practical consequence: almost every real JSON API call from JS triggers a preflight, because Content-Type: application/json alone disqualifies it from being "simple."

4The Preflight Handshake, Precisely

OPTIONS /users HTTP/1.1
Host: api.example.com
Origin: https://app.example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: content-type, authorization

The browser builds this OPTIONS request itself — your JS never sees or triggers it directly. It asks the server: "if I were to send a POST from https://app.example.com with these headers, would you allow it?"

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: content-type, authorization
Access-Control-Max-Age: 600

The browser inspects this response and checks it against what it's about to send:

• Is the requesting origin listed (or is * used — see §6)?
• Is the actual method in Access-Control-Allow-Methods?
• Are all the actual custom headers covered by Access-Control-Allow-Headers?

Only if all checks pass does the browser then send the real request (POST /users with the real body). If any check fails, the browser never sends the real request at all, and your fetch() call rejects — this is the one case where CORS does prevent a request from leaving the browser, because the preflight failed before the real request was ever built.

Access-Control-Max-Age lets the server tell the browser to cache this preflight's answer for N seconds, so identical preflights aren't repeated on every call.

5What Happens on a Simple Request (No Preflight)

For a simple request, the browser sends the actual request immediately (with an Origin header attached) and lets it go to the server. The server processes it and responds normally. The CORS check happens after the response comes back: the browser looks for Access-Control-Allow-Origin in the response headers and compares it to the requesting origin. If it's missing or doesn't match, the browser discards the response from JS's point of view (the request still happened; the side effects still occurred if it was e.g. a POST).

6The Response Headers That Matter

The credentials + wildcard interaction (a frequent gotcha)

Access-Control-Allow-Origin: * cannot be combined with credentialed requests. If a request is sent with fetch(url, { credentials: "include" }), the browser requires the server to echo back the exact requesting origin (not *) in Access-Control-Allow-Origin, AND include Access-Control-Allow-Credentials: true — otherwise the browser blocks the read even though the header technically exists. This is a deliberate spec restriction: a wildcard origin combined with "yes, send my cookies" would let any site read any user's cookie-authenticated data, defeating the entire purpose.

7Common CORS Response Headers Set by a Server (Express-style Example)

app.use((req, res, next) => {
  const allowedOrigins = ["https://app.example.com", "https://admin.example.com"];
  const origin = req.headers.origin;
  if (allowedOrigins.includes(origin)) {
    res.setHeader("Access-Control-Allow-Origin", origin); // echo exact origin, never blindly "*"
    res.setHeader("Access-Control-Allow-Credentials", "true");
  }
  res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE");
  res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
  if (req.method === "OPTIONS") return res.sendStatus(204); // short-circuit the preflight
  next();
});

Note the pattern: never set Access-Control-Allow-Origin to the literal string * alongside credentials — validate the incoming Origin header against an allowlist and echo it back only if it matches.

⚠️ Common Pitfalls

1. Believing a CORS error means the server rejected the request. In almost all cases the server processed it fine; the browser is refusing to expose the response to your script. Check server-side logs/effects before assuming failure.
2. Setting Access-Control-Allow-Origin: * while also trying to send cookies/credentials. The browser will refuse to honor it — you must echo the specific origin and set Access-Control-Allow-Credentials: true.
3. Forgetting that adding Content-Type: application/json turns a "simple" POST into a preflighted one. A server that only handles the real method/path and never implements OPTIONS will silently break for JSON POST calls from browsers even though curl to the same endpoint works fine.
4. Assuming preflight caching (Access-Control-Max-Age) means the browser only preflights once ever. It's cached per method+headers combination and expires; different endpoints or header sets trigger fresh preflights.
5. Trying to "fix" CORS from the client side. CORS headers must come from the server; there is no client-side header or fetch option that bypasses a server's refusal to grant access (short of a server-side proxy that makes the request same-origin from the browser's perspective).
6. Confusing CORS with authentication/authorization. A wide-open Access-Control-Allow-Origin: * does not grant unauthenticated access to protected data — CORS only governs readability by browser JS; it says nothing about whether the request is authenticated or authorized (a separate concern, and one not solved by CORS — see the CSRF topic for how cross-origin state-changing requests are actually a distinct threat that CORS alone does not fully prevent).

📋 Quick Reference

Simple request (no preflight): GET/HEAD/POST + only safelisted headers +
                                 Content-Type in {form-urlencoded, multipart/form-data, text/plain}
Everything else (PUT/DELETE/PATCH, JSON body, custom headers, Authorization) → preflighted

Preflight:  OPTIONS + Access-Control-Request-Method / -Headers  →  browser-only, auto-sent
Response:   Access-Control-Allow-Origin / -Methods / -Headers / -Credentials / -Max-Age

CORS blocks READING the response in JS. It does NOT prevent the request from
reaching the server, and does NOT by itself authenticate or authorize anything.

Access-Control-Allow-Origin: *  +  credentials: "include"  →  browser refuses; must echo exact origin

🎤 Interview Q&A

🛠️ Practice exercises

Each exercise is a file in this topic folder. Code exercises are self-checking: run them and make the checks pass.

✅ Check yourself

Source: browsersec_cors_theory.md · generated by tools/build_lessons.py