CORS in Express: risolvere l'errore CORS, con e senza cors

Un errore CORS ("No 'Access-Control-Allow-Origin' header is present") significa che una pagina web su un'origine, come http://localhost:5173, ha chiamato la tua API su un'altra origine e il browser non ha lasciato leggere la risposta alla pagina, perché la risposta non diceva che quell'origine era autorizzata. La soluzione sta sul server: invia Access-Control-Allow-Origin con l'origine della pagina e rispondi alla richiesta preflight OPTIONS del browser con i metodi e gli header che accetti. In Express sono poche righe di middleware, oppure app.use(cors()) dal pacchetto cors.

const express = require('express');
const app = express();

const ALLOWED_ORIGIN = 'https://app.example.com';

function cors(req, res, next) {
    res.set('Access-Control-Allow-Origin', ALLOWED_ORIGIN);
    res.set('Vary', 'Origin');
    if (req.method === 'OPTIONS') {
        res.set('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE');
        res.set('Access-Control-Allow-Headers', 'Content-Type, Authorization');
        res.set('Access-Control-Max-Age', '600');
        return res.sendStatus(204);
    }
    next();
}

app.use(cors);

app.get('/api/products', (req, res) => {
    res.json([{ id: 1, name: 'Lamp' }]);
});

app.put('/api/products/:id', (req, res) => {
    res.json({ updated: req.params.id });
});

// GET /api/products
app.listen(3000);

La risposta è la lista dei prodotti, e la sua scheda Headers mostra access-control-allow-origin: https://app.example.com: una pagina su quell'origine può leggerla. Ora invia OPTIONS /api/products/1 con gli header Origin: https://app.example.com e Access-Control-Request-Method: PUT. È il preflight che un browser invia prima di un PUT, e la risposta è 204 con i metodi e gli header consentiti e nessun body.

Cosa controlla il browser

Le pagine della stessa origine non hanno bisogno di niente. Per una richiesta cross-origin il browser legge questi header della risposta:

Una semplice GET o una POST in stile form arriva direttamente al server, e il browser controlla Access-Control-Allow-Origin nella risposta. Il server esegue comunque la richiesta; CORS decide solo se la pagina vede il risultato. Una richiesta con un body JSON, un header Authorization o un metodo come PUT o DELETE è preceduta da una richiesta preflight OPTIONS, e quella vera parte solo se la risposta al preflight lo consente. Per questo un middleware CORS deve rispondere a OPTIONS prima di qualsiasi route o controllo di autenticazione.

Consentire più origini, con le credentials

Access-Control-Allow-Origin contiene una sola origine o *, mai una lista. Per consentirne più di una, confronta l'header Origin della richiesta con una lista di origini ammesse e rimandalo indietro quando corrisponde:

const express = require('express');
const app = express();

const allowed = new Set(['https://app.example.com', 'http://localhost:5173']);

app.use((req, res, next) => {
    const origin = req.get('origin');
    if (origin && allowed.has(origin)) {
        res.set('Access-Control-Allow-Origin', origin);
        res.set('Access-Control-Allow-Credentials', 'true');
    }
    res.set('Vary', 'Origin');
    if (req.method === 'OPTIONS') {
        res.set('Access-Control-Allow-Methods', 'GET, POST');
        res.set('Access-Control-Allow-Headers', 'Content-Type');
        return res.sendStatus(204);
    }
    next();
});

app.get('/api/me', (req, res) => {
    res.json({ origin: req.get('origin') ?? null });
});

app.listen(3000);

La prima richiesta non ha l'header Origin, come una chiamata da curl o da una pagina della stessa origine, quindi riceve {"origin":null} e nessun header CORS. Invia GET /api/me con l'header Origin: http://localhost:5173 e la scheda Headers mostra quell'origine rimandata indietro più access-control-allow-credentials: true. Cambia l'header in Origin: https://evil.example e i due header CORS spariscono: il server risponde comunque, ma un browser impedirebbe alla pagina di leggere la risposta. Access-Control-Allow-Credentials: true permette alla pagina di inviare cookie (con fetch(url, { credentials: 'include' })), e i browser lo rifiutano insieme a *, quindi le credentials richiedono sempre l'origine esatta.

Il pacchetto cors

Il pacchetto cors fa lo stesso lavoro tramite opzioni. Installalo con npm install cors:

const cors = require('cors');

// Any origin, no cookies: fine for a public read-only API.
app.use(cors());

// Only your frontend, with cookies.
app.use(cors({
    origin: ['https://app.example.com', 'http://localhost:5173'],
    credentials: true,
    methods: ['GET', 'POST', 'PUT', 'DELETE'],
}));

// One route only.
app.get('/api/public', cors(), handler);

Chiamato senza opzioni, cors() invia Access-Control-Allow-Origin: * e risponde a ogni preflight. Usa * solo per dati pubblici che non richiedono login.

Errori comuni

Aggiungere CORS dopo le route o dopo un middleware di autenticazione. La richiesta preflight OPTIONS non ha l'header Authorization, quindi un controllo di autenticazione messo prima risponde 401 e il browser segnala un errore CORS. Registra per primo il middleware CORS.

Usare * con le credentials. I browser rifiutano la risposta. Rimanda invece l'origine specifica.

Provare a risolvere CORS nel frontend. Opzioni della richiesta come mode: 'no-cors' non tolgono la restrizione; ti danno una risposta opaca che non puoi leggere. Solo gli header del server risolvono il problema.

Per come funzionano app.use() e l'ordine dei middleware, vedi i middleware di Express.