Como usar Cross-Origin-Embedder-Policy em uma landing page criada por IA

Uma landing page criada por IA pode carregar fontes, imagens, vídeos, scripts, workers e iframes de várias origens. Ativar uma política de isolamento sem mapear esses recursos costuma produzir uma página parcialmente quebrada: a estrutura abre, mas uma fonte some, um worker falha ou o checkout deixa de carregar.

Cross-Origin-Embedder-Policy, ou COEP, permite que o documento exija permissão explícita para determinados recursos cross-origin ou carregue alguns deles sem credenciais. Em conjunto com COOP, a política participa do isolamento necessário para APIs sensíveis.

Este guia mostra como inventariar dependências, escolher entre require-corp e credentialless, separar COEP de CORS e CORP e verificar a versão publicada.

Comece pelo motivo, não pelo header

O valor padrão é unsafe-none. Recursos cross-origin continuam sujeitos às regras normais do navegador, mas o documento não exige o opt-in adicional imposto por COEP.

Considere uma política compatível com isolamento quando houver uma necessidade demonstrada, como:

• uso de SharedArrayBuffer;
• worker ou biblioteca que depende de memória compartilhada;
• temporização de maior precisão para uma aplicação técnica;
• requisito de isolamento documentado por uma dependência;
• modelo de ameaça que justifica separar o documento de recursos sem opt-in.

Não ative COEP apenas para aumentar uma pontuação de auditoria. A política muda quais respostas podem entrar no contexto e exige coordenação com servidores que você talvez não controle.

O HTML Living Standard define unsafe-none, require-corp e credentialless, além da forma como headers inválidos falham para o comportamento padrão.

Inventarie cada recurso e seu modo de requisição

Procure dependências estáticas e dinâmicas:

rg -n \
  '<script|<link|<img|<video|<audio|<iframe|new Worker|new SharedWorker|fetch\(|import\(' \
  src public

Use Network no build final e percorra estados que carregam recursos sob demanda: consentimento, envio de formulário, abertura de vídeo, login, checkout e suporte.

Para cada resposta, registre:

URL e origem:
tipo de recurso:
proprietário do servidor:
modo no-cors ou cors:
credenciais enviadas:
redirects:
header Access-Control-Allow-Origin:
header Cross-Origin-Resource-Policy:
necessidade de cookies ou autenticação:
alternativa same-origin:

Inclua recursos criados por gerenciadores de tags e SDKs. Uma biblioteca pode buscar módulos, WASM, workers ou imagens que não aparecem no HTML inicial.

Compare os três valores

Com require-corp, um recurso cross-origin solicitado em modo no-cors precisa responder com uma Cross-Origin-Resource-Policy que permita o carregamento. Recursos solicitados em modo CORS precisam passar pelo contrato CORS correspondente.

Com credentialless, requisições cross-origin no-cors podem seguir sem CORP, mas cookies e outras credenciais são omitidos. Isso ajuda com recursos públicos que você não controla, mas pode mudar personalização, medição, cache e respostas dependentes de sessão.

Outros modos continuam sujeitos às suas regras. credentialless não é uma autorização geral para ler respostas nem um substituto para CORS.

Diferencie COEP, CORP e CORS

As siglas participam do mesmo fluxo com papéis diferentes:

Um servidor de imagens pode declarar:

Cross-Origin-Resource-Policy: cross-origin

Os valores definidos pelo Fetch Standard para CORP incluem same-origin, same-site e cross-origin. Escolha pelo público real. same-site inclui origens diferentes dentro do mesmo site registrável e não deve ser tratado como sinônimo de mesma origem.

Quando o recurso já suporta CORS, solicite-o no modo adequado. Em HTML, isso pode exigir crossorigin:

<img src="https://cdn.exemplo/imagem.webp" alt="Demonstração do produto" crossorigin />

O servidor ainda precisa devolver Access-Control-Allow-Origin compatível. O guia de validação de CORS mostra como testar origem, preflight, headers e credenciais.

Trate recursos externos por proprietário

Classifique as dependências:

Recursos controlados pela equipe

Prefira servir assets estáticos na mesma origem quando isso simplifica o contrato. Para um servidor separado, configure CORP ou CORS explicitamente e teste cache e redirects.

CDN ou fornecedor com suporte documentado

Siga o modo indicado pelo fornecedor e confirme os headers na resposta real. Não suponha que todos os endpoints do mesmo domínio possuem a mesma configuração.

Serviço sem suporte a CORS ou CORP

Avalie se o recurso é público e funciona sem credenciais com credentialless. Se cookies, sessão ou personalização são necessários, essa alternativa pode alterar o produto. Considere remover a dependência, hospedar um asset autorizado na origem ou negociar suporte com o fornecedor.

Iframes e documentos aninhados

Frames possuem regras adicionais. A política do documento pai, os headers do documento incorporado, CSP, X-Frame-Options, sandbox, credenciais e origens precisam ser analisados em conjunto. Não transforme um iframe autenticado em credentialless sem revisar armazenamento, login e pop-ups.

O guia de iframe sandbox cobre capacidades do frame; COEP trata outra fronteira.

Use report-only para localizar bloqueios

Antes de aplicar enforcement, quando a infraestrutura oferece Reporting API, teste:

Cross-Origin-Embedder-Policy-Report-Only: require-corp; report-to="coep"
Reporting-Endpoints: coep="https://relatorios.exemplo/coep"

Percorra todas as rotas e interações. Correlacione relatórios com Network e Console para identificar a requisição, seu modo e a resposta.

Report-only é observação, não proteção ativa. Ele também não substitui testes funcionais. Recursos carregados apenas em contas, regiões ou condições específicas podem não aparecer na sessão analisada.

Mantenha uma matriz:

Combine com COOP e teste o resultado

COEP compatível sozinha não torna o documento cross-origin isolated. A combinação típica é:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

Depois, verifique no contexto seguro:

if (crossOriginIsolated) {
  iniciarRecursoComMemoriaCompartilhada();
} else {
  iniciarFallbackCompativel();
}

Trate o fallback como parte do produto. Mesmo com os headers corretos, uma Permissions Policy, um browser não suportado, uma resposta intermediária ou uma rota servida de forma diferente pode impedir o resultado esperado.

O guia de Cross-Origin-Opener-Policy cobre pop-ups, grupos de navegação e compatibilidade de login e checkout.

Entregue os headers no documento publicado

COEP e seu modo report-only são headers HTTP. Não existe meta tag equivalente que ative a política:

Cross-Origin-Embedder-Policy: require-corp

O contrato atual de Publicação envia os arquivos do site, mas não converte um _headers do pacote em headers da resposta. A equipe precisa de uma camada autorizada que controle a resposta HTML ou de suporte explícito da plataforma.

O mesmo vale para CORP em recursos próprios. Um arquivo de configuração local não prova que o CDN ou servidor entregou o header. Confirme cada resposta pela URL pública.

Não anuncie isolamento completo enquanto a infraestrutura necessária não existir. Registre a política proposta, os fornecedores incompatíveis e o responsável pela entrega dos headers.

Verifique documento, recursos e domínios

Confira o HTML principal:

curl -sS -D - -o /dev/null https://exemplo.sitenoar.app \
  | rg -i '^cross-origin-(opener|embedder)-policy:'

Confira um recurso controlado:

curl -sS -D - -o /dev/null https://cdn.exemplo/worker.js \
  | rg -i '^(access-control-allow-origin|cross-origin-resource-policy):'

No navegador, valide crossOriginIsolated, Network, Console e o comportamento do recurso que motivou a política. Não pare no booleano: login, checkout, Analytics, mídia, fontes, workers e frames precisam continuar operando de forma intencional.

Repita na URL padrão e em cada domínio próprio ativo. CORS, cookies e same-origin mudam com esquema, host e porta. Se corrigir assets ou headers, republique o mesmo Site e refaça a matriz na versão final.

Prompt copiável para o agente

Revise a adoção de Cross-Origin-Embedder-Policy nesta landing page.

Pasta publicável: [caminho]
URL de teste: [URL]
Domínios finais: [lista]
Recurso que exige isolamento: [descrição]

- Inventarie imagens, fontes, scripts, mídia, workers, WASM, APIs e iframes.
- Registre origem, modo de request, credenciais, redirects, CORS e CORP.
- Compare unsafe-none, require-corp e credentialless.
- Não use credentialless em recursos autenticados sem testar o impacto.
- Comece com report-only quando a infraestrutura oferecer Reporting API.
- Coordene headers com cada servidor ou fornecedor responsável.
- Teste COOP: same-origin junto com a COEP escolhida.
- Implemente fallback quando crossOriginIsolated for falso.
- Confirme headers na resposta HTTP publicada, não apenas no repositório.
- Verifique URL padrão, domínios próprios e todos os estados dinâmicos.
- Entregue política, recursos incompatíveis, responsáveis e evidências.

Checklist final

• o requisito de isolamento está documentado;
• recursos estáticos e dinâmicos foram inventariados;
• modo, credenciais, CORS, CORP e redirects foram registrados;
• require-corp e credentialless foram comparados pelo comportamento real;
• recursos autenticados não perderam cookies sem decisão explícita;
• report-only e testes funcionais cobriram rotas e interações;
• COOP e Permissions Policy foram revisadas em conjunto;
• existe fallback quando crossOriginIsolated é falso;
• headers aparecem no documento e nos recursos publicados;
• URL padrão e domínios próprios foram verificados;
• a versão publicada corresponde à matriz aprovada.

COEP funciona quando cada recurso externo tem origem, proprietário, modo e permissão conhecidos. O objetivo não é bloquear até o console silenciar, mas tornar explícito quais respostas podem entrar em um contexto isolado e por quê.