The Aroma Store SPA lives at https://aromastore.example. The API lives at https://api.aromastore.example. The first time somebody writes a fetch from the SPA to the API, the browser console shows the most famous message in web development:

And then the worst thing happens: somebody searches the internet, finds app.use(cors()) with no arguments, pastes it, it works, and they have just opened their API to every web page in the world. This lesson exists so that does not happen. We are going to understand why the browser blocks, what exactly it protects, why curl and Aroma Mobile see none of these problems, and how to configure a policy that lets the SPA and the back office through without opening the door to anybody else. By the end, src/config/cors.js will exist and the cors middleware will occupy position 4 in the src/app.js chain — the position matters, and we will see why.

Warning. CORS is a browser mechanism and it is not a server access control. A well-made CORS configuration does not replace authentication or authorisation. Any real deployment must be reviewed by a security professional. All the domains and data in this lesson are fictional.

1. The same-origin policy
2. What exactly an origin is
3. What the same-origin policy really protects
4. Why curl and Aroma Mobile are unaffected
5. Simple requests and preflighted requests
6. The complete OPTIONS exchange
7. All the CORS headers
8. Access-Control-Expose-Headers: the one that is always missing
9. Aroma Store's real configuration
10. Why * and Allow-Credentials are incompatible
11. The position in the src/app.js chain
12. Typical errors and how to read them in the console
13. Cross-origin cookies: SameSite, Secure, HttpOnly
14. CSRF: what it is and why Bearer is immune
15. Other browser policies
16. CORS authorises nothing
17. Testing CORS with curl and with the DevTools

The same-origin policy (SOP) is the fundamental security rule of browsers: a page's JavaScript can only read responses from its own origin.

It is what prevents this:

Without the SOP, any page you visited could, in the background, read your email, your bank and your intranet by exploiting the sessions you already have open. The web would be unusable.

And now the uncomfortable part: the SOP also blocks your own SPA calling your own API, because the browser has no way of knowing that aromastore.example and api.aromastore.example are the same organisation.

CORS (Cross-Origin Resource Sharing) is the standardised mechanism by which the server tells the browser: "this specific origin may read my responses". In other words:

CORS is not a defence. It is a controlled relaxation of a defence that already exists.

Internalising that sentence avoids 90% of the conceptual mistakes about CORS.

An origin is the triple scheme + host + port. All three have to match, exactly, with no exceptions.

Taking https://aromastore.example as the reference:

Two practical consequences:

A subdomain is another origin. This is the number-one source of surprise: many people assume api.aromastore.example is "the same" as aromastore.example. To the browser it is not, and that is why Aroma Store needs CORS.

The last row matters for security. When validating origins, origin.startsWith('https://aromastore.example') accepts https://aromastore.example.evil.example, a domain anybody can register. The comparison has to be exact equality against an allowlist.

There is a subtlety here that almost everyone gets wrong at first, and it changes completely how you reason about CORS.

The request is sent. When your page does a fetch to another origin without preflight, the browser sends the request to the server and the server processes it. What the SOP blocks is the page's JavaScript reading the response.

Consequences that need to be very clear:

• If the endpoint has side effects, they happen anyway. A GET that deleted something would delete it, even though the attacker never saw the response. It is one more argument for the safety of GET from 02-03.
• CORS protects your server from nothing. It protects the user's data by stopping another page reading it with that user's credentials.
• The attacker does not see the error. The JavaScript receives a generic TypeError: Failed to fetch, with no status code and no body. That is deliberate: if it could see the 401 or the 404, it would already have information.

Preflighted requests (section 5) are stopped before they are sent, and there there really is server-side protection: that is why Content-Type: application/json and Authorization trigger preflight.

curl does not apply CORS. Neither does Postman, nor a Node script, nor CataBox's backend, nor the Aroma Mobile app (which makes native requests, not requests from a browser context). CORS is implemented by the browser, and only by the browser, because it is the only thing that runs third-party code with the user's credentials.

From which follows the most important conclusion of the lesson, which is worth repeating until it feels obvious:

A restrictive CORS policy stops nobody calling your API. It only stops a web page from another origin reading the response inside a user's browser. The real protection for your data is, always, the server's authentication and authorisation.

The browser distinguishes two categories, and the difference is visible in performance and in the errors.

They are sent directly, with no prior enquiry. They must meet all of these conditions:

• The method is GET, HEAD or POST.
• Headers limited to the "CORS-safelisted" ones: Accept, Accept-Language, Content-Language, Content-Type (with restrictions) and a few more.
• Content-Type may only be application/x-www-form-urlencoded, multipart/form-data or text/plain.
• No upload event handlers on the XMLHttpRequest.

The historical reason for this list: these are exactly the requests an HTML form could make before CORS existed. Since they were already possible, requiring prior permission would have added no security and would certainly have broken the web.

Anything outside that list triggers a preliminary OPTIONS request. In Aroma Store, that means almost everything:

Since our API uses Authorization: Bearer and application/json everywhere, practically all the SPA's traffic is preflighted. That is why Access-Control-Max-Age (section 7) has a real performance impact: without a preflight cache, every request becomes two.

Let us look, in the raw, at what happens when the SPA creates an order.

Step 1: the preflight. The browser generates it on its own; your code never writes it:

Notice three things: it carries no body, it does not carry the real Authorization (it only announces that it is going to send one) and the announced headers are lowercase and sorted.

Step 2: the response to the preflight.

Step 3: the real request. Only if step 2 allowed it:

Step 4: the real response. And here is the point that always gets forgotten: the real response also needs Access-Control-Allow-Origin. The preflight having gone well is not enough.

Without Expose-Headers, the SPA would receive the 201 and the body, but response.headers.get('Location') would return null.

The fact that Origin cannot be forged from JavaScript is what makes the mechanism work: the browser writes it and does not let the script touch it. That said, a client that is not a browser can write whatever it likes (curl -H "Origin: ..."), and that is why Origin is not usable as an access control.

Two details that cause bugs:

Allow-Origin accepts a single value. There is no such thing as Access-Control-Allow-Origin: https://a.example, https://b.example. For several origins, the server reflects the origin it received if it is on its allowlist. That is what the cors package does with an origin function.

Max-Age has browser caps. Even if you ask for 86,400 seconds, browsers impose their own maximum (of the order of two hours in Chromium, less in others). A value of 600 is a good balance: it cuts down preflights a lot and does not leave a policy change frozen for too long.

If the server reflects the origin, the response depends on the Origin header. Without Vary: Origin, any intermediate cache — a CDN, a corporate proxy, the browser's cache — can store the response for https://aromastore.example and serve it to a request from https://panel.aromastore.example, which will then receive the wrong Allow-Origin and fail intermittently and inexplicably.

It is the same Vary mechanic we saw in 02-05 with Accept-Language, and we will return to it in 04-06 when we talk about caching. All three cases are the same principle: if the response depends on a request header, say so in Vary.

By default, JavaScript from another origin can read only seven response headers, the "CORS-safelisted" ones:

Cache-Control, Content-Language, Content-Length, Content-Type, Expires, Last-Modified, Pragma.

All the rest are invisible, even though they are there. And that wipes out a good part of what we have built in this course:

This is the link that joined the three previous lessons together. Aroma Store exposes exactly this:

And a design criterion: you expose what is needed, not everything. There is a * wildcard for Expose-Headers, but it does not work when credentials are involved and, above all, exposing infrastructure headers leaks unnecessary information.

And the start-up validation, consistent with 03-01: if there are no origins configured in production, the process must not start, because the silent alternative is worse.

Access-Control-Allow-Origin: * means "any web page in the world may read this response". There is one case where that is perfectly reasonable:

The prohibition is explicit in the specification: if Access-Control-Allow-Credentials: true, then Access-Control-Allow-Origin cannot be *. It has to be a specific origin.

The reason is clear once you think about the attack it prevents: if it were allowed, any web page could make requests carrying the user's session cookies to any API and read the result. It would be the complete elimination of the same-origin policy. The wildcard can only apply to data that does not depend on who is asking, and the moment credentials are involved, it does.

One nuance that confuses people: credentials: 'include' in the fetch affects cookies and HTTP authentication headers managed by the browser, not an Authorization: Bearer you set by hand. Even so, with Bearer you still need an allowlist, because the token identifies the user and the response depends on them.

Aroma Store's decision: an allowlist across the whole API. An exception with * could be made for GET /v1/coffees, which is public and cacheable, but keeping a single policy is simpler, less brittle and consistent with the consistency principle from 04-01.

Why position 4 and no other. It is the most important decision in this lesson:

• Before the rate limiting (6): otherwise a 429 goes out with no CORS headers and the browser turns it into an opaque network error. The SPA developer sees "Failed to fetch" and has no idea they have exceeded a limit.
• Before the JSON parser (7): the OPTIONS preflight carries no body, but a POST with malformed JSON would produce a 400 with no CORS headers, and once again the SPA would see a useless error.
• Before the routes (9) and therefore before all authentication: this is the key to the classic error in section 12. The OPTIONS preflight carries no Authorization — the browser never sends it — so if the authentication middleware ran first, it would answer 401 to the preflight and the real request would never be sent.
• After helmet (3): so that the preflight response also carries the security headers and so that, if helmet and CORS conflict (the Cross-Origin-Resource-Policy case we saw in 04-02), CORS has the last word over its own headers.
• After the trace (2): so that a failed preflight can be correlated in the logs.

And a design consequence worth noting: the cors package answers the OPTIONS and ends the chain (preflightContinue: false). The preflight never reaches the routes, so each route's router.all(...) with methodNotAllowed(...) does not interfere with it.

Translation: the OPTIONS returned 401. And it returned 401 because the authentication middleware ran before the CORS one, and the preflight carries no Authorization: the browser never includes it, by design, because the preflight is a question about policy, not a request for data.

The confusion here is twofold, which is why the bug eats whole afternoons: the message talks about CORS, but the cause is the middleware ordering; and the request that fails (OPTIONS) is not the one you wrote (POST). The diagnostic rule: when CORS fails, open the browser's network tab and look for the OPTIONS request. If it is not there, the problem is something else. If it is there and does not return 2xx, that is your failure, and its status code tells you exactly which middleware intercepted it.

If Aroma Store used session cookies instead of Authorization: Bearer, the necessary configuration would be:

The problem is obvious: SameSite=None is exactly what you have to set for things to work between aromastore.example and api.aromastore.example, and it is exactly what reopens the door to CSRF. In exchange you have to add anti-CSRF tokens, and on top of that SameSite=None requires Secure and is subject to the third-party cookie restrictions browsers have been tightening for years.

That is why Aroma Store uses Authorization: Bearer:

Neither option is perfect: Bearer eliminates CSRF but shifts the risk onto how the token is stored on the client (04-03). For an API consumed by a SPA, a mobile app and third parties, Bearer is the coherent choice, and that is why credentials: false in our CORS configuration.

CSRF (Cross-Site Request Forgery) is an attack that exploits the fact that the browser attaches cookies automatically. The victim, with an open session at Aroma Store, visits a malicious page:

The browser sends the request with the victim's session cookies. The attacker cannot read the response (the SOP prevents it), but they do not need to: the order has already been created. CSRF is a blind write attack.

Why Aroma Store is immune:

1. It uses Authorization: Bearer, and the browser does not attach that header automatically. A form on another site cannot add it.
2. It requires Content-Type: application/json, which an HTML form cannot produce (the enctype="text/plain" trick in the example is precisely an attempt to get round that, and our express.json({type: [...]}) rejects that type).
3. Every write triggers a preflight, and the preflight would fail because malicious-site.example is not on the allowlist.

All three are consequences of decisions that were already taken. If one day it migrated to cookies, explicit defences would be needed:

And the section's final warning: CSRF and CORS are different things and are often confused. CORS controls who may read responses; CSRF exploits the fact that requests are sent with credentials. Configuring CORS strictly does not eliminate CSRF if you use cookies, because simple requests get sent anyway.

CORS is not the only policy governing the relationship between the SPA and the API.

Referrer-Policy, which we already enabled with helmet in 04-02 with the value no-referrer. It controls how much of the originating URL is sent when navigating or loading resources. It matters because our URIs contain identifiers (/v1/orders/ord_5001) and we do not want them appearing in third parties' logs.

Permissions-Policy (formerly Feature-Policy) declares which browser capabilities a document may use: camera, microphone, geolocation. It is a header for HTML documents, so it is set by the SPA, not by the API:

Content-Security-Policy in the SPA, and specifically the connect-src directive, which is the symmetrical complement to CORS: while CORS says which origins may read us, connect-src says which origins the SPA may call.

Its defensive value is concrete: if an attacker manages to inject JavaScript into the SPA (an XSS), connect-src stops them exfiltrating the data to their own server, because the browser will block the fetch to an undeclared domain. That is why CSP is a valuable defence in depth even when you already sanitise your inputs.

The API, which serves no HTML, keeps its default-src 'none' from 04-02: nothing to load, nothing to execute.

It deserves a section of its own because it is the misunderstanding with the worst consequences.

CORS is an instruction to the browser. It is not an access control.

An API with Access-Control-Allow-Origin: https://aromastore.example and no authentication is a completely open API: anyone with curl gets everything. And an API with the most restrictive CORS policy in the world is still vulnerable to BOLA if it does not check resource ownership (04-02).

The golden rule:

Configure CORS thinking about protecting your users inside their browser. Configure authentication and authorisation thinking about protecting your data from everything else. Never substitute the second with the first.

curl does not apply CORS, but it is perfect for inspecting the headers the server emits, which is what we want to verify.

1. Network tab, "Fetch/XHR" filter, and turn on "Preserve log" so entries are not lost on navigation.
2. Look for the OPTIONS request. If it fails, that is the problem; its status code points at the culprit.
3. Under "Headers", compare Access-Control-Request-Headers (what the browser asks for) with Access-Control-Allow-Headers (what the server grants). The difference is your mistake.
4. Check on the real response that both Access-Control-Allow-Origin and Access-Control-Expose-Headers are there.
5. If the response arrives but a header is null in the code, it is Expose-Headers. The DevTools do show every header even when JavaScript cannot read them: that discrepancy between "I can see it in the DevTools but headers.get() returns null" is the unmistakable signature of the problem.

The third test is the most valuable of the four: it pins down the middleware ordering. If somebody moves cors after the authentication, this test fails with a 401 and the problem is caught in continuous integration instead of in the console of a SPA developer.

Using app.use(cors()) with no options. It is equivalent to Access-Control-Allow-Origin: * across the whole API. It works, and that is why it is so dangerous: the problem never manifests itself.

Validating the origin with startsWith or a loose regular expression. https://aromastore.example.evil.example would pass the filter. Exact equality against a Set.

Forgetting Vary: Origin. It produces intermittent failures that depend on what the CDN happens to have cached, and they are among the hardest bugs to reproduce.

Putting cors after the authentication. The preflight gets a 401 and nothing works, with a message pointing in another direction.

Forgetting exposedHeaders. The SPA cannot read Location, Link, ETag or Retry-After, and a good part of the work from modules 2, 3 and 4 is invisible to it.

Trying to fix CORS from the client. You cannot: the decision belongs to the server. The proxies and extensions that "disable CORS" only work on your machine and hide the real problem.

Believing that mode: 'no-cors' in the fetch fixes anything. It returns an opaque response: you can read neither the body nor the status. It is almost never what you want.

Adding an origin to the allowlist "temporarily" for debugging. Temporary *s stay for ever. Use a development environment with its own configuration.

Tip: the preflight response also needs the security headers. That is why helmet goes before CORS.

Tip: when CORS fails, look at the network tab before the console. The console message is a summary; the OPTIONS request is the evidence.

Tip: document the list of allowed origins. When the SPA changes domain, somebody will have to update it, and if it is not written down nobody will know where.

For each request from https://aromastore.example, say whether it triggers a preflight and why:

1. fetch('https://api.aromastore.example/v1/coffees')
2. fetch('https://api.aromastore.example/v1/coffees', { headers: { Authorization: 'Bearer x' } })
3. fetch('https://api.aromastore.example/v1/orders', { method: 'POST', body: 'hello', headers: { 'Content-Type': 'text/plain' } })
4. fetch('https://api.aromastore.example/v1/orders', { method: 'POST', body: '{}', headers: { 'Content-Type': 'application/json' } })
5. fetch('https://aromastore.example/api/coffees')
6. fetch('https://api.aromastore.example/v1/coffees/cof_001', { method: 'DELETE' })

Diagnose each situation and propose the concrete fix:

• (a) The SPA creates an order correctly (201), but response.headers.get('Location') returns null.
• (b) The internal back office works from a developer's machine and fails in production with No 'Access-Control-Allow-Origin' header.
• (c) After putting a CDN in front, the SPA fails one time in five with an Allow-Origin belonging to the back office.
• (d) POST /v1/orders fails from the SPA with "Response to preflight request doesn't pass access control check", but the same POST with curl works.

Aroma Store is going to let CataBox (https://catabox.example) call the API from its own SPA in the browser, using OAuth with Authorization: Bearer and only the orders.read scope. Write the necessary CORS configuration and answer: is adding the origin to the allowlist enough for CataBox to read the orders? What else is needed, and what does CORS not contribute here?

Solution 1

An observation about case 3: even though it does not trigger a preflight, our API would reject it anyway with a 400, because express.json is configured with type: ['application/json', 'application/merge-patch+json'] and does not parse text/plain. That rejection is precisely what makes the CSRF form trick from section 14 fail.

Solution 2

(a) Location is missing from exposedHeaders. The response arrives complete and the header is there — you can see it in the DevTools — but the browser does not let JavaScript read it because it is not one of the seven safelisted ones. Fix: add Location to exposedHeaders in src/config/cors.js.

(b) The production ALLOWED_ORIGINS variable does not include the back office's domain. In development it worked because allowedOrigins() adds localhost when NODE_ENV is development. Fix: add https://panel.aromastore.example to the production environment's configuration and redeploy. Verification: curl -sI -H 'Origin: https://panel.aromastore.example' ....

(c) Vary: Origin is missing. The CDN caches the response — including its Access-Control-Allow-Origin header — without knowing that it depends on Origin, and serves it indiscriminately to both origins. The failure is intermittent because it depends on which response happens to be cached. Fix: emit Vary: Origin (the cors package does so when an origin function is used, but you have to verify that the CDN respects it and does not strip it).

(d) The preflight is not being answered correctly. curl works because it does no preflight. The two likely causes, in order: the authentication middleware runs before cors and answers 401 to the OPTIONS; or Idempotency-Key is missing from allowedHeaders, so the browser rejects the preflight even though it returns 204. Diagnosis: look at the OPTIONS request in the network tab. If it returns 401, it is the first; if it returns 204 but the Access-Control-Allow-Headers does not include idempotency-key, it is the second.

Solution 3

Nothing else is needed in the configuration: CataBox uses Authorization: Bearer, which is already in allowedHeaders, and credentials stays false because there are no cookies.

Is that enough for CataBox to read the orders? No. Adding the origin only allows the browser to hand the response to CataBox's JavaScript. For the API to return data, three more things are needed, all on the server side:

1. A valid token issued by the authorisation server, with aud equal to our API (04-03).
2. The orders.read scope in that token, checked by requireScope.
3. The ownership check: the token gives access only to the orders belonging to its sub, not to anyone's (04-02).

What CORS does not contribute here: absolutely no authorisation. If tomorrow CataBox's backend calls the API from its server, there will be no Origin and no CORS involved, and the access will carry on working or failing in exactly the same way, according to the token. And a practical note: since CataBox's SPA is a public client, it must use Authorization Code + PKCE and cannot store a client_secret (04-03).

CORS stops being a mystery as soon as you understand that it is not a defence, but a controlled relaxation of a defence that already exists: the same-origin policy, which stops a page's JavaScript reading responses from another origin. You know what an origin is exactly — scheme, host and port, with a subdomain counting as different — that the request is sent even when the response is blocked, and why curl, Aroma Mobile and CataBox's backend see none of this. You can tell simple requests from preflighted ones, and you have seen the complete raw OPTIONS exchange, with the key observation that the real response also needs its CORS headers. You know the protocol's seven headers, the importance of Vary: Origin when caches are involved, and above all Access-Control-Expose-Headers, which was the missing link letting the SPA read Location, Link, ETag, Retry-After and the Aroma-RateLimit-* headers we have spent three lessons building. In the project you have src/config/cors.js with a per-environment allowlist validated at start-up, and the middleware at position 4 of src/app.js: after helmet, before the rate limiting, the parser and all authentication — which is precisely what avoids the classic preflight 401. And you are clear on why Aroma Store uses Authorization: Bearer rather than cookies, which makes it immune to CSRF with no need for synchroniser tokens.

With the API secured, bounded and reachable from the right origins, what remains is making it fast. In 04-06, HTTP Caching and Performance, we will pick up the "cacheable" constraint from 01-04 and turn it into implementation: the levels of caching from the browser down to the database; Cache-Control in depth, with max-age, s-maxage, private, that no-cache which does not mean "do not cache", stale-while-revalidate and immutable; conditional validation with ETag and Last-Modified producing a 304 with no body; and the reunion we have been promising since 03-05, when If-Match and the 412 close the optimistic concurrency circle and explain why a header is a better place than the body for the version field. We will add src/middleware/cache.js, look at invalidation — the hard problem — server-side caching with Redis and its cache-aside pattern, compression, the N+1, the 202 for long operations, and why you have to measure p50, p95 and p99 before optimising anything.