Gerador de Cabeçalho CORS Customizado

CORS a fundo: origens, preflight, credentials e os headers que importam

CORS (Cross-Origin Resource Sharing) é o mecanismo que permite a uma página na origem A fazer requisições HTTP para uma API na origem B. Faz parte do padrão Fetch do WHATWG, descende da recomendação W3C CORS, e é integralmente aplicado pelo browser — o servidor apenas sugere o que permite, o browser decide se expõe a resposta para o JavaScript.

Uma origem é a tupla scheme + host + port — https://exemplo.com:443 é uma origem, http://exemplo.com é outra, e https://api.exemplo.com é uma terceira. Por padrão a same-origin policy impede scripts de ler respostas entre origens; CORS é o opt-in controlado em que o servidor diz "sim, aquela origem pode ler isto".

Requisições simples vs preflight

Uma requisição simples usa GET, HEAD ou POST, apenas headers padrão e Content-Type entre application/x-www-form-urlencoded, multipart/form-data ou text/plain. O browser apenas envia a requisição com um header Origin: https://app.com e o servidor responde com Access-Control-Allow-Origin: https://app.com (ou * para APIs públicas).

Qualquer outra coisa — PUT, DELETE, PATCH, headers customizados como Authorization ou X-API-Key, ou Content-Type JSON — dispara um preflight. O browser envia uma requisição OPTIONS antes e o servidor precisa responder com o conjunto completo de allow headers:

Access-Control-Allow-Origin: https://app.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 86400

Max-Age diz ao browser por quanto tempo cachear o preflight (em segundos) — sem ele, toda requisição que muda estado faz dois round-trips. Chrome trava em 7200, Firefox em 86400.

Credentials: cookies e Authorization

Quando o cliente envia cookies, auth HTTP ou um fetch(..., { credentials: 'include' }), o servidor precisa responder com Access-Control-Allow-Credentials: true. Crucial: o header Origin na resposta NUNCA pode ser * quando credentials estão habilitadas — precisa ser a origem literal que chamou. A maioria dos frameworks implementa isso como "reflete o Origin da requisição se estiver na allow-list".

Para deixar seu JS ler headers de resposta não-padrão (paginação, contadores de rate-limit), exponha-os: Access-Control-Expose-Headers: X-Total-Count, X-Pagination, X-RateLimit-Remaining. Sem esse header o browser esconde mesmo que cheguem na camada de rede.

Configurando CORS em servidores reais

• Express: app.use(cors({ origin: ['https://app.com'], credentials: true, maxAge: 86400 })) — o pacote cors do npm cuida do OPTIONS automaticamente.
• nginx: add_header Access-Control-Allow-Origin "$http_origin" always; mais um bloco location dedicado que retorna 204 para OPTIONS.
• AWS CloudFront: anexe uma Response Headers Policy ao behaviour; o CloudFront só repassa Origin se você incluir na chave de cache.
• AWS API Gateway: habilite CORS por recurso — ele gera uma integração mock para OPTIONS.
• S3 static hosting: configure o CORSConfiguration XML em nível de bucket (separado da bucket policy).

Pegadinhas comuns

• Allow-Origin: * combinado com Allow-Credentials: true — o browser silenciosamente bloqueia a resposta. Reflita a origem específica.
• A spec CORS não permite múltiplos valores em Allow-Origin — você precisa ecoar uma única origem da sua allow-list (padrão reflect-origin).
• CDN cacheando sem Vary: Origin pode servir a resposta CORS errada para outra origem — sempre adicione o Vary.
• Falhas de preflight passam despercebidas — o OPTIONS retorna 200 mas o browser ainda bloqueia a requisição real porque o Allow-Methods estava incompleto.
• Redirects não preservam o header Origin no preflight em browsers antigos — evite 301/302 em rotas de API.

FAQ

Por que vejo "CORS error" no console? O servidor não retornou um header Access-Control-Allow-Origin casando com a origem da página, ou não respondeu 2xx no preflight. Inspecione a aba Network — o OPTIONS vai mostrar exatamente qual header está faltando.

Dá pra bypassar CORS do lado cliente? Não. CORS é aplicado pelo browser; só o servidor pode autorizar a leitura. Workarounds (CORS proxies, flags do browser) só funcionam em dev. Em produção, conserte o servidor ou mova a chamada para o backend.

Preflight acontece em toda requisição? Só em requisições não-simples, e só se o cache estiver frio. Coloque Access-Control-Max-Age em algumas horas e o browser reutiliza o resultado para aquela combinação origem/método/header.

CORS é uma feature de segurança? É uma feature de relaxamento, não de proteção. Permite leituras cross-origin que a same-origin policy bloquearia. Não protege o servidor de CSRF, XSS ou chamadas diretas via curl/Postman — essas não passam pelo browser.

Como suportar múltiplas origens? Mantenha uma allow-list, confira o Origin recebido contra ela e reflita aquele valor exato de volta. Sempre adicione Vary: Origin para os caches segmentarem as respostas corretamente.