CORS para TYPO3

Por que projetos headless TYPO3 falham imediatamente sem uma configuração CORS correta

Assim que um sistema TYPO3 deixa de apenas renderizar HTML e passa a entregar APIs JSON a clientes JavaScript em outros domínios, o navegador esbarra na Same-Origin Policy. Sem cabeçalhos Cross-Origin Resource Sharing (CORS) explícitos, ele bloqueia qualquer chamada fetch que venha de uma origem diferente da API. Para qualquer abordagem headless TYPO3, integração de microsserviços e setup em que um frontend em app.example.com.br conversa com um backend em cms.example.com.br, uma configuração CORS limpa é o requisito básico. Ela não cabe em uma única extensão, mas é um jogo de cena entre middleware TYPO3, configuração de webserver e setup de reverse proxy.

Cenários típicos de uso

Um varejista online brasileiro com 40.000 pedidos por mês opera um catálogo de produtos em TYPO3 e um storefront React em um domínio separado. O storefront consulta dados de produto, estoque e informações de preço via API JSON implementada como middleware TYPO3. Sem cabeçalhos CORS corretos, o navegador bloqueia toda chamada AJAX com a mensagem “has been blocked by CORS policy”, e o storefront fica vazio. A solução é uma middleware que define Access-Control-Allow-Origin precisamente para os domínios de frontend conhecidos e responde corretamente aos preflight OPTIONS requests.

Um segundo caso é uma empresa que opera TYPO3 como content hub para vários sites de marcas. Cada marca tem um domínio próprio, mas renderiza certos módulos como listagens de notícias ou imagens de produto no cliente a partir da instância central TYPO3. Aqui o CORS precisa ser configurado de forma que todos os domínios de marca sejam permitidos, mas domínios desconhecidos não. Uma verificação dinâmica de origem contra uma whitelist na site configuration do TYPO3 é a abordagem correta, em vez de um wildcard genérico.

O terceiro contexto são consórcios científicos brasileiros, como redes ligadas à FAPESP ou ao CNPq, que mantêm uma base de dados de pesquisa em TYPO3 e oferecem acesso mundial a instituições via API aberta. Aqui a política CORS é deliberadamente aberta, mas precisa ser combinada com uma camada de autenticação, de modo que toda origem possa chamar a API, mas só receba dados com um token válido.

Arquitetura técnica: middleware, PSR-15 e preflight

No TYPO3 v12 e v13, o lugar correto para cabeçalhos CORS é uma middleware PSR-15 inserida na request pipeline. Ela verifica o header Origin da requisição de entrada, compara com uma whitelist configurada e define os cabeçalhos Access-Control-Allow-Origin, Access-Control-Allow-Methods e Access-Control-Allow-Headers na resposta. Para requisições POST, PUT ou DELETE com headers customizados, o navegador envia primeiro um preflight OPTIONS, que a middleware precisa responder sem autenticação, caso contrário a requisição real falha.

A configuração pode ser mantida via site configuration como array YAML, alternativamente diretamente no ext_localconf.php da extensão própria. É importante saber que o tratamento de credentials (cookies, Authorization header) só funciona se Access-Control-Allow-Credentials estiver como true e Access-Control-Allow-Origin apontar para uma origem concreta, não para um wildcard. Essa combinação é padrão CORS e fonte de erro frequente em times que testam primeiro com wildcard e depois tentam ligar credentials.

Problemas frequentes e soluções

O primeiro problema é a duplicação de headers. Se o TYPO3 seta um header e o Apache ou Nginx seta adicionalmente o mesmo header na configuração do webserver, dois valores chegam ao navegador, que rejeita a requisição como malformada. A solução é definir o CORS em exatamente um lugar, seja na middleware TYPO3 ou no webserver, e manter o outro deliberadamente vazio. Em reverse proxies como Traefik ou Cloudflare, entra ainda uma terceira camada que também pode manipular headers.

O segundo problema são preflight OPTIONS requests. O navegador envia um OPTIONS request para verificar, antes da chamada real, se o método é permitido. Middlewares TYPO3 que primeiro autenticam e depois definem cabeçalhos CORS rejeitam o OPTIONS request porque ele não traz Authorization header. A solução é interceptar preflight requests cedo na cadeia de middleware e respondê-los sem autenticação.

O terceiro tema é a combinação de CORS com caching. Um reverse proxy como Varnish cacheia uma resposta com certos cabeçalhos CORS, e na próxima chamada de outra origem essa origem recebe os cabeçalhos antigos. A consequência é que usuários legítimos vêem erros CORS de repente, porque recebem uma resposta cacheada destinada a outra origem. Um Vary header em Origin resolve o problema, mas força o cache a várias variantes por recurso.

Migração e compatibilidade de versões

O TYPO3 v11 ainda não oferecia uma API de middleware limpa para todos os contextos, de modo que a configuração CORS era frequentemente resolvida via hooks ou diretamente no webserver. A partir da v12, a middleware PSR-15 é o caminho previsto, e o caminho de migração de instalações mais antigas consiste em mover as manipulações de header da configuração Apache ou Nginx para a middleware TYPO3.

Para setups headless em TYPO3 v13 em combinação com a EXT:headless da Macopedia, o CORS é um bloco elementar e é tratado explicitamente na documentação da extensão. A Gosign implementou vários projetos headless assim e acompanha, se necessário, a coordenação entre times que cuidam de frontend e backend separadamente, de forma que as regras CORS fiquem documentadas de forma inequívoca e sejam sincronizadas a cada mudança de deploy. Uma regra errada abre um vetor de ataque em que sites maliciosos podem executar ações em nome do usuário autenticado, motivo pelo qual uma whitelist limpa não é questão de conforto, mas exigência de segurança.

Também vale notar que o CORS não substitui autenticação. Muitos times configuram regras CORS generosas acreditando que isso torna a API segura, e esquecem que cada origem que o navegador permite tem o mesmo acesso que um cliente chamado diretamente. A autenticação precisa ser feita independentemente do CORS, via tokens, API keys ou cookies de sessão, e o CORS apenas garante que navegadores permitam chamadas legítimas a esses endpoints autenticados. Quem entende essa separação configura regras CORS muito mais restritivas e fecha muitas brechas não intencionais.