CORS no Express: resolver o erro de CORS (com e sem cors)

Um erro de CORS ("No 'Access-Control-Allow-Origin' header is present") significa que uma página web em uma origem, como http://localhost:5173, chamou sua API em outra origem, e o navegador não deixou a página ler a resposta porque a resposta não dizia que aquela origem era permitida. A correção é no servidor: envie Access-Control-Allow-Origin com a origem da página, e responda a requisição de preflight OPTIONS do navegador com os métodos e headers que você aceita. No Express isso são poucas linhas de middleware, ou app.use(cors()) do pacote 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);

A resposta é a lista de produtos, e a aba Headers mostra access-control-allow-origin: https://app.example.com: uma página nessa origem pode lê-la. Agora envie OPTIONS /api/products/1 com os headers Origin: https://app.example.com e Access-Control-Request-Method: PUT. Esse é o preflight que um navegador envia antes de um PUT, e a resposta é 204 com os métodos e headers permitidos e sem body.

O que o navegador confere

Páginas de mesma origem não precisam de nada. Para uma requisição entre origens, o navegador lê estes headers da resposta:

Um GET simples ou um POST no estilo de formulário vai direto para o servidor, e o navegador confere Access-Control-Allow-Origin na resposta. O servidor executa a requisição mesmo assim; o CORS só decide se a página vê o resultado. Uma requisição com body JSON, com header Authorization ou com um método como PUT ou DELETE é precedida por uma requisição de preflight OPTIONS, e a requisição real só é enviada se a resposta do preflight permitir. Por isso um middleware de CORS precisa responder o OPTIONS antes de qualquer rota ou verificação de autenticação rodar.

Liberar várias origens, com credentials

Access-Control-Allow-Origin guarda uma origem ou *, nunca uma lista. Para liberar várias, compare o header Origin da requisição com uma lista de permitidas e devolva o mesmo valor quando ele estiver nela:

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);

A primeira requisição não tem header Origin, como uma chamada do curl ou de uma página de mesma origem, então ela recebe {"origin":null} e nenhum header de CORS. Envie GET /api/me com o header Origin: http://localhost:5173 e a aba Headers mostra essa origem devolvida mais access-control-allow-credentials: true. Troque o header para Origin: https://evil.example e os dois headers de CORS somem: o servidor ainda responde, mas um navegador impediria a página de ler. Access-Control-Allow-Credentials: true deixa a página enviar cookies (com fetch(url, { credentials: 'include' })), e os navegadores o rejeitam junto com *, então credentials sempre exige a origem exata.

O pacote cors

O pacote cors faz o mesmo trabalho com opções. Instale com 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);

Chamado sem opções, cors() envia Access-Control-Allow-Origin: * e responde todo preflight. Use * só para dados públicos que não exigem login.

Erros comuns

Adicionar CORS depois das rotas ou depois de um middleware de autenticação. A requisição de preflight OPTIONS não leva header Authorization, então uma verificação de autenticação colocada antes responde com 401 e o navegador informa um erro de CORS. Registre o middleware de CORS primeiro.

Usar * com credentials. Os navegadores recusam a resposta. Devolva a origem específica.

Tentar resolver CORS no frontend. Opções de requisição como mode: 'no-cors' não removem a restrição; elas te dão uma resposta opaca que você não consegue ler. Só os headers do servidor resolvem.

Para entender como funcionam o app.use() e a ordem dos middlewares, veja middleware no Express.