CORS: what it protects and how it goes wrong

CORS lets a browser page read an API’s answer, and one careless string comparison lets every site do it. Of the ten ways the second program below tries to decide that an origin is yours, nine accept at least one origin that is not.

You will see what CORS relaxes and what it never did, follow a simple and a preflighted request header by header, learn why lookalike origins pass most matchers, and configure an exact allowlist, or choose a design that needs no CORS at all.

CORS lets a page read a response; it never decided who may send

The same-origin policysame-origin policy: The browser rule that a page's script may read responses and documents only from its own origin, unless the other origin allows it with CORS. It limits reading; requests to other origins are still sent. More in “HTTP, origins and the browser security model” stops a page’s script from reading what another origin sends back. Cross-origin resource sharingcross-origin resource sharing (CORS): Response headers by which a server tells browsers which other origins may read its answers. It relaxes the same-origin policy's block on reading. It does not stop requests from being sent and does not identify the caller. is how a server relaxes that rule for the origins it names: headers on its answer tell the browser that a given page may read it. Four facts follow, and each is easy to forget.

• It is a rule the browser applies for its own page. curl, another server and a mobile app ignore it, so it protects nobody from them.
• It decides who may read an answer, not who may send a request. A simple request reaches your server whatever your headers say, as the last lesson showed. MDN’s reasoning is that forms could always send such requests, so servers already guard against them.
• Every origin you allow is a party you trust. When the request carries the user’s cookie, a page on an allowed origin can call your API as that user and read the answers.
• It is not access control. OWASP’s HTML5 cheat sheet says not to rely only on the Origin header for access control checks, and the session and permission checks stay where they were.

The program is a model of the CORS rules in the Fetch standard for the cases it shows, and it sends nothing over a network. A page on https://app.example calls an API on https://api.example. For each answer the API could give, it prints whether the browser sent the request and whether the script may read the response. Read the first group now; the other two return later in the lesson:

// What a browser lets a page's script do with an API's CORS answers. The page is https://app.example and the API is
// https://api.example. This is a model of the CORS rules in the Fetch standard for the cases shown: it is not a
// browser, and the standard has more cases than these.
const PAGE = 'https://app.example';
const FORM_TYPES = ['application/x-www-form-urlencoded', 'multipart/form-data', 'text/plain'];
const SAFE_HEADERS = ['accept', 'accept-language', 'content-language'];

// A request needs a preflight unless its method is GET, HEAD or POST and its headers are all safelisted.
function needsPreflight(req) {
  if (!['GET', 'HEAD', 'POST'].includes(req.method)) return true;
  return Object.entries(req.headers).some(([name, value]) => (name === 'content-type' ? !FORM_TYPES.includes(value) : !SAFE_HEADERS.includes(name)));
}

// The check on Access-Control-Allow-Origin and -Credentials: why the script may not read the answer, or null.
function readCheck(h, credentials) {
  const origin = h['access-control-allow-origin'];
  if (origin === undefined) return 'no Allow-Origin header';
  if (origin === '*') return credentials ? 'a wildcard cannot go with credentials' : null;
  if (origin !== PAGE) return `Allow-Origin is ${origin}`;
  if (credentials && h['access-control-allow-credentials'] !== 'true') return 'Allow-Credentials is not exactly true';
  return null;
}

// The preflight answer must pass the same check, and list the method (compared exactly) and every non-safelisted
// header (compared without regard to case). A * counts as a wildcard only when the request sends no credentials.
function preflightCheck(req, h) {
  const why = readCheck(h, req.credentials);
  if (why) return `preflight: ${why}`;
  const items = (name, lower) => (h[name] ?? '').split(',').map((s) => (lower ? s.trim().toLowerCase() : s.trim()));
  const methods = items('access-control-allow-methods', false);
  const headers = items('access-control-allow-headers', true);
  const wildcardOk = !req.credentials;
  if (!(methods.includes(req.method) || (wildcardOk && methods.includes('*')))) return `preflight: Allow-Methods lacks ${req.method}`;
  for (const name of Object.keys(req.headers)) {
    if (SAFE_HEADERS.includes(name)) continue;
    if (!(headers.includes(name) || (wildcardOk && headers.includes('*')))) return `preflight: Allow-Headers lacks ${name}`;
  }
  return null;
}

function run(req, preflight, response) {
  const pre = needsPreflight(req) ? preflightCheck(req, preflight ?? {}) : null;
  if (pre) return { sent: 'no', reads: 'no', why: pre };
  const why = readCheck(response, req.credentials);
  return { sent: 'yes', reads: why ? 'no' : 'yes', why: why ?? '' };
}

const getMe = { method: 'GET', headers: {}, credentials: true };
const getCatalogue = { method: 'GET', headers: {}, credentials: false };
const putMe = { method: 'PUT', headers: { 'content-type': 'application/json' }, credentials: true };
const exact = { 'access-control-allow-origin': PAGE, 'access-control-allow-credentials': 'true' };

const rows = [
  ['GET /me with the cookie', null],
  ['  no CORS headers', run(getMe, null, {})],
  ['  Allow-Origin: *', run(getMe, null, { 'access-control-allow-origin': '*' })],
  ['  Allow-Origin: the page, nothing else', run(getMe, null, { 'access-control-allow-origin': PAGE })],
  ['  Allow-Origin: the page, Credentials: true', run(getMe, null, exact)],
  ['  ... with Credentials: True', run(getMe, null, { ...exact, 'access-control-allow-credentials': 'True' })],
  ['  Allow-Origin: the page with a slash', run(getMe, null, { ...exact, 'access-control-allow-origin': `${PAGE}/` })],
  ['  Allow-Origin: the page, then another', run(getMe, null, { ...exact, 'access-control-allow-origin': `${PAGE}, https://admin.example` })],
  ['  Allow-Origin: null', run(getMe, null, { ...exact, 'access-control-allow-origin': 'null' })],
  ['GET /catalogue, no cookie', null],
  ['  Allow-Origin: *', run(getCatalogue, null, { 'access-control-allow-origin': '*' })],
  ['PUT /me with JSON and the cookie', null],
  ['  no answer to the preflight', run(putMe, {}, exact)],
  ['  preflight lists POST only', run(putMe, { ...exact, 'access-control-allow-methods': 'POST' }, exact)],
  ['  preflight lists PUT, not Content-Type', run(putMe, { ...exact, 'access-control-allow-methods': 'PUT' }, exact)],
  ['  preflight lists PUT and Content-Type', run(putMe, { ...exact, 'access-control-allow-methods': 'PUT', 'access-control-allow-headers': 'content-type' }, exact)],
  ['  Allow-Methods: * with the cookie', run(putMe, { ...exact, 'access-control-allow-methods': '*', 'access-control-allow-headers': 'content-type' }, exact)],
];

console.log(`${'the API answers'.padEnd(46)}${'sent'.padEnd(6)}${'script reads'.padEnd(14)}why not`);
for (const [label, r] of rows) {
  console.log(r ? `${label.padEnd(46)}${r.sent.padEnd(6)}${r.reads.padEnd(14)}${r.why}`.trimEnd() : label);
}

the API answers                               sent  script reads  why not
GET /me with the cookie
  no CORS headers                             yes   no            no Allow-Origin header
  Allow-Origin: *                             yes   no            a wildcard cannot go with credentials
  Allow-Origin: the page, nothing else        yes   no            Allow-Credentials is not exactly true
  Allow-Origin: the page, Credentials: true   yes   yes
  ... with Credentials: True                  yes   no            Allow-Credentials is not exactly true
  Allow-Origin: the page with a slash         yes   no            Allow-Origin is https://app.example/
  Allow-Origin: the page, then another        yes   no            Allow-Origin is https://app.example, https://admin.example
  Allow-Origin: null                          yes   no            Allow-Origin is null
GET /catalogue, no cookie
  Allow-Origin: *                             yes   yes
PUT /me with JSON and the cookie
  no answer to the preflight                  no    no            preflight: no Allow-Origin header
  preflight lists POST only                   no    no            preflight: Allow-Methods lacks PUT
  preflight lists PUT, not Content-Type       no    no            preflight: Allow-Headers lacks content-type
  preflight lists PUT and Content-Type        yes   yes
  Allow-Methods: * with the cookie            no    no            preflight: Allow-Methods lacks PUT

In every row of the first group the request was sent, and in seven of the eight the script may not read the answer. The API ran its code each time. Only one answer opens the response to the page, the exact origin together with Access-Control-Allow-Credentials: true. Remove the credentials header, or change one character of the origin, and the script gets an error while whatever the request did on the server stays done.

A simple request goes out at once; a preflight asks first

The last lesson defined the simple requestsimple request: A cross-origin request that a browser sends without asking first: GET, HEAD or POST with only safelisted headers and, for a POST, a form content type. The page cannot read the answer, but the server has already acted. More in “CSRF: tokens, SameSite and Fetch Metadata”: a GET, HEAD or POST with only safelisted headers and, for a POST, a form content type. A browser sends that at once. Anything else, such as a PUT, a JSON body or a custom header, starts with a preflightpreflight: The OPTIONS request a browser sends before a cross-origin request that is not simple. It asks which methods and headers the server allows, and if the answer gives no permission the real request is never sent. More in “CSRF: tokens, SameSite and Fetch Metadata”, an OPTIONS request that the browser sends without cookies. The real request follows only if the answer to the preflight gives the permission it asked for. These are the headers each side must send:

Step through one PUT with a JSON body and the user’s cookie, and see where each check can stop it:

The last group of rows in the program traces the same checks. With no answer to the preflight, with an answer that lists POST only, and with one that lists PUT but not content-type, the request is never sent: the first column says no. Only the answer that lists both lets it out. The final row shows a trap. Access-Control-Allow-Methods: * reads as a wildcard only for requests without credentials, so with a cookie the browser looks for a method called * and finds no PUT. A browser also caps how long it keeps a preflight answer, 2 hours in Chromium and 24 hours in Firefox, according to MDN.

An allowlist is exact, or it is a door

Most servers that answer more than one origin read the request’s Origin, decide whether it is theirs and, if so, send it back in Access-Control-Allow-Origin. The decision is where the weakness lives. A browser sets Origin from the page’s real origin, and anyone can register a host name that looks like yours, so the origin of a lookalike page arrives as a perfectly honest header. The second program tries ten ways to decide that an origin is yours on eight origins, one real and seven that are not, or not meant. All the names end in .example or .test, which are reserved for examples:

# Ten ways to decide that an Origin header is "ours", tried on eight origins. The only origin we mean is
# https://shop.example. Every host name here ends in .example or .test, which are reserved for examples.
import re
from urllib.parse import urlsplit

REAL = "https://shop.example"

origins = [
    ("https://shop.example", "the real origin"),
    ("https://shop.example.other.test", "starts with the real origin"),
    ("https://eshop.example", "ends with shop.example"),
    ("http://shop.example", "the same host over http"),
    ("https://shop.example:8443", "the same host on another port"),
    ("https://shop-example", "a hyphen where the dot is"),
    ("https://blog.shop.example", "a subdomain"),
    ("null", "a sandboxed frame or a file page"),
]


def host(origin):
    return urlsplit(origin).hostname or ""


matchers = [
    ("reflect any Origin", lambda o: True),
    ("exact string, and null too", lambda o: o in (REAL, "null")),
    ("o.endswith('shop.example')", lambda o: o.endswith("shop.example")),
    ("o.startswith(REAL)", lambda o: o.startswith(REAL)),
    ("'shop.example' in o", lambda o: "shop.example" in o),
    ("regex, dot not escaped", lambda o: re.fullmatch(r"https://shop.example", o) is not None),
    ("regex, no end anchor", lambda o: re.match(r"https://shop\.example", o) is not None),
    ("the host or any subdomain", lambda o: host(o) == "shop.example" or host(o).endswith(".shop.example")),
    ("the host only, scheme ignored", lambda o: host(o) == "shop.example"),
    ("exact string in a set", lambda o: o in {REAL}),
]

for number, (origin, note) in enumerate(origins, 1):
    print(f"{number}  {origin:<33}{note}")
print()
print(f"{'accepted by':<31}" + " ".join(str(n) for n in range(1, len(origins) + 1)))
for name, accepts in matchers:
    print(f"{name:<31}" + " ".join("Y" if accepts(origin) else "." for origin, _ in origins))

1  https://shop.example             the real origin
2  https://shop.example.other.test  starts with the real origin
3  https://eshop.example            ends with shop.example
4  http://shop.example              the same host over http
5  https://shop.example:8443        the same host on another port
6  https://shop-example             a hyphen where the dot is
7  https://blog.shop.example        a subdomain
8  null                             a sandboxed frame or a file page

accepted by                    1 2 3 4 5 6 7 8
reflect any Origin             Y Y Y Y Y Y Y Y
exact string, and null too     Y . . . . . . Y
o.endswith('shop.example')     Y . Y Y . . Y .
o.startswith(REAL)             Y Y . . Y . . .
'shop.example' in o            Y Y Y Y Y . Y .
regex, dot not escaped         Y . . . . Y . .
regex, no end anchor           Y Y . . Y . . .
the host or any subdomain      Y . . Y Y . Y .
the host only, scheme ignored  Y . . Y Y . . .
exact string in a set          Y . . . . . . .

Read down column 1 and then across a row. The real origin passes every matcher. Reflecting any Origin accepts all eight, and ASVS 5.0.0 requirement 3.4.2 says an echoed origin must be validated against an allowlist of trusted origins. The second row is an exact list that also lists null, which the next section explains. The rows after it fail in different ways: endswith takes https://eshop.example and plain http, startswith takes a longer host and another port, in takes six of the eight, and a regular expression with an unescaped dot takes https://shop-example because the dot stands for any character. Without an end anchor, a regular expression accepts the longer host and the other port.

Two rows are choices as much as mistakes. Allowing the host and every subdomain is exactly as safe as the weakest subdomain you own, and a subdomain can be forgotten, handed to a hosting service or taken over. Comparing only the host ignores the scheme and the port, which are part of an origin. Only the last matcher, an exact string in a set of whole origins, accepts the real origin and nothing else.

Credentials, null and caches change what a header means

A request that carries the user’s cookie, credentials: 'include' in fetch(), is a credentialed requestcredentialed request: A cross-origin request that carries the user's cookies or other credentials, such as fetch() with credentials set to include. The server must name one exact origin and send Allow-Credentials true, because browsers refuse a wildcard answer., and the rules tighten. Access-Control-Allow-Origin: * no longer works, and neither does * in Access-Control-Allow-Methods, Access-Control-Allow-Headers or Access-Control-Expose-Headers. The answer must name one origin, and Access-Control-Allow-Credentials must be exactly true, which is why the wildcard row and the row with a capital T in the first group of the first program both fail. That requirement is also why reflecting Origin is tempting: it makes the error go away. It does so by trusting every site.

Whether the cookie goes at all is a separate question. MDN notes that the browser’s third-party cookie policy applies whatever the server and the page configure, and SameSite still decides which requests carry the cookie, as the CSRF lesson showed. When the page and the API are the same site, a Lax cookie goes along; when they are not, the cookie needs SameSite=None.

Browsers send the origin null for some pages, among them sandboxed frames and files opened from disk, and a site’s own form post can carry it under Referrer-Policy: no-referrer. The null originnull origin: The value null in an Origin header. Browsers send it for sandboxed frames, local files and some redirects, and a site's own form post can carry it under Referrer-Policy no-referrer. It names no site, so it is never a match. identifies no site, and MDN warns that any site can make a document with a null origin, so an Access-Control-Allow-Origin: null lets every site in. The third program puts a weak middleware, the kind that grows out of fixing errors one at a time, beside a fixed one. Pages on six origins ask for GET /me with their cookie, a page on the real origin sends a PUT with a header nobody planned for, and then a shared cache sits in front of the API:

// The same API behind a weak CORS middleware and a fixed one. Pages on six origins ask for GET /me with their cookie,
// and a page on the real origin sends a PUT that needs a preflight. The program prints what each server answers and
// whether the page could read it. At the end a shared cache sits in front of the API and two pages ask in turn.
const REAL = 'https://shop.example';

function weakCors(req) {
  const origin = req.headers.origin;
  const h = {};
  if (origin && (origin.endsWith('shop.example') || origin === 'null')) {
    h['access-control-allow-origin'] = origin; // echoes whatever matched
    h['access-control-allow-credentials'] = 'true';
  }
  if (req.method === 'OPTIONS') {
    h['access-control-allow-methods'] = 'GET, POST, PUT, PATCH, DELETE';
    h['access-control-allow-headers'] = req.headers['access-control-request-headers'] ?? ''; // echoes what was asked
  }
  return h;
}

const ALLOWED = new Set([REAL, 'https://admin.shop.example']);
function fixedCors(req) {
  const origin = req.headers.origin;
  const h = { vary: 'Origin' };
  if (origin !== undefined && ALLOWED.has(origin)) {
    h['access-control-allow-origin'] = origin;
    h['access-control-allow-credentials'] = 'true';
    if (req.method === 'OPTIONS') {
      h['access-control-allow-methods'] = 'GET, POST';
      h['access-control-allow-headers'] = 'content-type';
      h['access-control-max-age'] = '600';
    }
  }
  return h;
}

const readable = (page, h) => h['access-control-allow-origin'] === page && h['access-control-allow-credentials'] === 'true';
const show = (h) => h['access-control-allow-origin'] ?? '(none)';

const pages = [REAL, 'https://admin.shop.example', 'https://eshop.example', 'http://shop.example', 'null', 'https://other.example'];
console.log(`${'GET /me with the cookie, from'.padEnd(32)}${'weak: Allow-Origin sent, page reads?'.padEnd(46)}fixed`);
for (const page of pages) {
  const req = { method: 'GET', headers: { origin: page } };
  const w = weakCors(req);
  const f = fixedCors(req);
  console.log(`${page.padEnd(32)}${`${show(w)}, ${readable(page, w) ? 'yes' : 'no'}`.padEnd(46)}${show(f)}, ${readable(page, f) ? 'yes' : 'no'}`);
}

// A PUT with a custom header from the real origin: the preflight lists what the browser may then send.
const ask = { method: 'OPTIONS', headers: { origin: REAL, 'access-control-request-method': 'PUT', 'access-control-request-headers': 'content-type, x-debug-admin' } };
const lists = (h) => `methods: ${h['access-control-allow-methods'] ?? '(none)'}; headers: ${h['access-control-allow-headers'] ?? '(none)'}`;
console.log(`\npreflight for PUT with x-debug-admin, from ${REAL}`);
console.log(`  weak   ${lists(weakCors(ask))}`);
console.log(`  fixed  ${lists(fixedCors(ask))}`);

// A shared cache keyed by URL, plus the headers that the stored response lists in Vary.
function cachedAnswers(server) {
  const store = new Map();
  return ['https://shop.example', 'https://admin.shop.example'].map((page) => {
    const req = { method: 'GET', headers: { origin: page } };
    const h = server(req);
    const vary = (h.vary ?? '').toLowerCase().split(',').map((s) => s.trim());
    const key = `/me${vary.includes('origin') ? ` ${page}` : ''}`;
    if (!store.has(key)) store.set(key, h);
    return { page, got: store.get(key) };
  });
}
console.log('\nshared cache in front of the API, two pages ask for /me in turn');
for (const [name, server] of [['weak', weakCors], ['fixed', fixedCors]]) {
  const [, second] = cachedAnswers(server);
  console.log(`  ${name.padEnd(6)}second page reads the cached answer? ${readable(second.page, second.got) ? 'yes' : `no, it got Allow-Origin ${show(second.got)}`}`);
}

GET /me with the cookie, from   weak: Allow-Origin sent, page reads?          fixed
https://shop.example            https://shop.example, yes                     https://shop.example, yes
https://admin.shop.example      https://admin.shop.example, yes               https://admin.shop.example, yes
https://eshop.example           https://eshop.example, yes                    (none), no
http://shop.example             http://shop.example, yes                      (none), no
null                            null, yes                                     (none), no
https://other.example           (none), no                                    (none), no

preflight for PUT with x-debug-admin, from https://shop.example
  weak   methods: GET, POST, PUT, PATCH, DELETE; headers: content-type, x-debug-admin
  fixed  methods: GET, POST; headers: content-type

shared cache in front of the API, two pages ask for /me in turn
  weak  second page reads the cached answer? no, it got Allow-Origin https://shop.example
  fixed second page reads the cached answer? yes

The weak middleware lets in https://eshop.example, plain http and null, three origins that are not the real one. The fixed one answers only the two listed origins, and it sends Vary: Origin on every response. In the preflight, the weak middleware echoes whatever the browser asked for, x-debug-admin included, and allows five methods, where the fixed one lists the two methods and the one header its front end really uses. Echoing makes the permission follow the request, so it checks nothing.

The cache shows what Vary is for. A response that names one origin depends on the request’s Origin, and a shared cache that does not know this keeps one copy and hands it to the next origin. The weak middleware sent no Vary, so the second page received an answer that named the first, and its script could not read it. The fixed middleware’s Vary: Origin made the cache keep one copy per origin. The lesson on safe caching in the next module treats Vary in full.

Allow one exact origin, or put the API on the origin of the page

The safest CORS setting is the one you do not need. Four designs avoid a cross-origin read, or make it harmless:

• One origin for the page and the API. Put the API under a path of the page’s own origin, with a reverse proxy, so that the browser sees one origin. No cross-origin read exists to misconfigure.
• A backend for the front end. The page calls a server of yours, and that server calls the API with its own credentials. The browser never holds the API token.
• A wildcard for public data. Access-Control-Allow-Origin: * on a route that holds nothing private and needs no cookie. ASVS 3.4.2 allows a wildcard only when the response holds no sensitive data.
• postMessage between two windows, which is safe only when every handler discards a message from an origin it does not trust, as ASVS 3.5.5 requires.

Where a page of another origin must call your API with a cookie, configure the exact list. Use your framework’s maintained CORS middleware, give it whole origins, and do not use any setting that reflects the request’s Origin. Send Vary: Origin, list only the methods and headers the front end uses, and keep Access-Control-Max-Age modest. A model like this lesson’s is not a browser, so run a check against a real browser engine in your tests as well; the standards have more cases than any model. Four questions about who calls your API choose between these designs:

In short: if your own front end is the only caller, avoid cross-origin reads altogether; if partner sites call it, keep an exact list that someone reviews; and keep the wildcard for public data without a cookie.

Practise: a CORS middleware that allows only what it lists

The starter is close to the weak middleware of the third program, with a wildcard for other origins added, and it breaks several of the rules above at once. Rewrite it so that a listed origin gets exactly its own origin and credentials, every other origin gets nothing, and a preflight answer carries fixed lists. The sample tests include the lookalikes of this lesson:

export const ALLOWED_ORIGINS = ['https://shop.example', 'https://admin.shop.example'];
export const ALLOWED_METHODS = ['GET', 'POST'];
export const ALLOWED_HEADERS = ['content-type', 'x-csrf-token'];

/** The CORS response headers for one request: `req` is { method, headers } with lower-case header names. */
export function corsHeaders(req) {
  const origin = req.headers.origin;
  const h = {};
  if (origin && (origin.endsWith('shop.example') || origin === 'null')) {
    h['access-control-allow-origin'] = origin;
    h['access-control-allow-credentials'] = 'true';
  } else if (origin) {
    h['access-control-allow-origin'] = '*';
  }
  if (req.method === 'OPTIONS') {
    h['access-control-allow-methods'] = 'GET, POST, PUT, PATCH, DELETE';
    h['access-control-allow-headers'] = req.headers['access-control-request-headers'] ?? '';
    h['access-control-max-age'] = '86400';
  }
  return h;
}

import { test, assert } from 'mysmartcopilot:test';
import { ALLOWED_ORIGINS, corsHeaders } from './cors.mjs';

const get = (origin) => ({ method: 'GET', headers: origin === undefined ? {} : { origin } });
const preflight = (origin) => ({
  method: 'OPTIONS',
  headers: { ...(origin === undefined ? {} : { origin }), 'access-control-request-method': 'PUT', 'access-control-request-headers': 'content-type, x-debug-admin' },
});
const onlyVary = { vary: 'Origin' };

test('a listed origin gets exactly its own origin and credentials', () => {
  for (const origin of ALLOWED_ORIGINS) {
    assert.deepEqual(corsHeaders(get(origin)), { vary: 'Origin', 'access-control-allow-origin': origin, 'access-control-allow-credentials': 'true' });
  }
});

test('an origin that is not listed gets nothing but Vary', () => {
  assert.deepEqual(corsHeaders(get('https://other.example')), onlyVary);
  assert.deepEqual(corsHeaders(get(undefined)), onlyVary, 'no Origin header at all');
});

test('lookalikes of a listed origin are refused', () => {
  for (const origin of ['https://eshop.example', 'https://shop.example.other.test', 'http://shop.example', 'https://shop.example:8443', 'https://blog.shop.example']) {
    assert.deepEqual(corsHeaders(get(origin)), onlyVary, origin);
  }
});

test('null and the wildcard are never allowed', () => {
  assert.deepEqual(corsHeaders(get('null')), onlyVary);
  assert.deepEqual(corsHeaders(get('*')), onlyVary);
});

test('a preflight from a listed origin carries fixed lists, not what was asked for', () => {
  assert.deepEqual(corsHeaders(preflight('https://shop.example')), {
    vary: 'Origin',
    'access-control-allow-origin': 'https://shop.example',
    'access-control-allow-credentials': 'true',
    'access-control-allow-methods': 'GET, POST',
    'access-control-allow-headers': 'content-type, x-csrf-token',
    'access-control-max-age': '600',
  });
});

test('a preflight from any other origin gets nothing but Vary', () => {
  assert.deepEqual(corsHeaders(preflight('https://eshop.example')), onlyVary);
  assert.deepEqual(corsHeaders(preflight(undefined)), onlyVary);
});

test('a GET carries no preflight headers', () => {
  const h = corsHeaders(get('https://admin.shop.example'));
  for (const name of ['access-control-allow-methods', 'access-control-allow-headers', 'access-control-max-age']) {
    assert.equal(h[name], undefined, name);
  }
});

ALLOWED_ORIGINS = ["https://shop.example", "https://admin.shop.example"]
ALLOWED_METHODS = ["GET", "POST"]
ALLOWED_HEADERS = ["content-type", "x-csrf-token"]


def cors_headers(req):
    """The CORS response headers for one request: req has "method" and "headers" (lower-case names)."""
    origin = req["headers"].get("origin")
    h = {}
    if origin and (origin.endswith("shop.example") or origin == "null"):
        h["access-control-allow-origin"] = origin
        h["access-control-allow-credentials"] = "true"
    elif origin:
        h["access-control-allow-origin"] = "*"
    if req["method"] == "OPTIONS":
        h["access-control-allow-methods"] = "GET, POST, PUT, PATCH, DELETE"
        h["access-control-allow-headers"] = req["headers"].get("access-control-request-headers", "")
        h["access-control-max-age"] = "86400"
    return h

from cors import ALLOWED_ORIGINS, cors_headers

ONLY_VARY = {"vary": "Origin"}


def get(origin):
    return {"method": "GET", "headers": {} if origin is None else {"origin": origin}}


def preflight(origin):
    headers = {"access-control-request-method": "PUT", "access-control-request-headers": "content-type, x-debug-admin"}
    if origin is not None:
        headers["origin"] = origin
    return {"method": "OPTIONS", "headers": headers}


def test_a_listed_origin_gets_exactly_its_own_origin_and_credentials():
    for origin in ALLOWED_ORIGINS:
        assert cors_headers(get(origin)) == {
            "vary": "Origin",
            "access-control-allow-origin": origin,
            "access-control-allow-credentials": "true",
        }


def test_an_origin_that_is_not_listed_gets_nothing_but_vary():
    assert cors_headers(get("https://other.example")) == ONLY_VARY
    assert cors_headers(get(None)) == ONLY_VARY, "no Origin header at all"


def test_lookalikes_of_a_listed_origin_are_refused():
    for origin in [
        "https://eshop.example",
        "https://shop.example.other.test",
        "http://shop.example",
        "https://shop.example:8443",
        "https://blog.shop.example",
    ]:
        assert cors_headers(get(origin)) == ONLY_VARY, origin


def test_null_and_the_wildcard_are_never_allowed():
    assert cors_headers(get("null")) == ONLY_VARY
    assert cors_headers(get("*")) == ONLY_VARY


def test_a_preflight_from_a_listed_origin_carries_fixed_lists():
    assert cors_headers(preflight("https://shop.example")) == {
        "vary": "Origin",
        "access-control-allow-origin": "https://shop.example",
        "access-control-allow-credentials": "true",
        "access-control-allow-methods": "GET, POST",
        "access-control-allow-headers": "content-type, x-csrf-token",
        "access-control-max-age": "600",
    }


def test_a_preflight_from_any_other_origin_gets_nothing_but_vary():
    assert cors_headers(preflight("https://eshop.example")) == ONLY_VARY
    assert cors_headers(preflight(None)) == ONLY_VARY


def test_a_get_carries_no_preflight_headers():
    h = cors_headers(get("https://admin.shop.example"))
    for name in ("access-control-allow-methods", "access-control-allow-headers", "access-control-max-age"):
        assert name not in h, name

Finish with the self-check. It asks about one idea at a time, starting with the one you know least, and each answer comes with its reason:

Interview questions

Warm-up: what does CORS protect, and what does it not?

CORS lets a server say which other origins may read its responses, by relaxing the browser’s same-origin policy for those origins. It protects nothing by itself: without it the browser withholds a cross-origin answer from the script, and with it the browser releases the answer to the origins listed. It does not stop a request from being sent, so a simple request such as a form post reaches the server whatever its CORS headers say, and it does not identify the caller, since only browsers apply it. Use it sparingly: name whole origins from a list, never reflect the request’s Origin, never allow null, send Vary: Origin, and keep session checks and CSRF defences in place whatever the headers say.

Key takeaways

• CORS relaxes the block on reading another origin’s response; it never decided who may send a request, and curl and other non-browser clients ignore it.
• A simple request goes out at once and a preflight asks first, with Access-Control-Request-Method and Access-Control-Request-Headers answered by the matching Allow headers.
• Compare the whole Origin string with a list of whole origins: prefixes, suffixes, substrings, loose patterns, host names alone and a reflected Origin each accept an origin you did not mean, and null is never ours.
• With a cookie the answer must name one origin and send Access-Control-Allow-Credentials: true, a wildcard does not work, and a response that depends on Origin needs Vary: Origin.
• Prefer a design with no cross-origin read, one origin or a backend for the front end, and keep CORS, an exact list that someone reviews, for the pages that really need it.