Conteúdo do curso Lição 67 de 156 · Content Security Policy e enquadramento
Content Security Policy e enquadramento

Trusted Types

Por que isso importa A CSP bloqueia tags de script injetadas. Mas muitos bugs modernos moram dentro do seu próprio JavaScript: uma linha como box.innerHTML = comment transforma o texto de um visitante em HTML vivo. Essa é a injeção baseada em DOM do Módulo 10 (Lição 59), e ela acontece depois que a página carregou. O Trusted Types faz o navegador recusar essas linhas perigosas, a menos que o valor tenha passado por uma verificação escrita por você.

Imagine uma fábrica em que só peças com um carimbo de inspeção podem entrar na linha de montagem. Ninguém consegue parafusar uma peça qualquer achada no estacionamento, nem por acidente. O Trusted Types acrescenta esse carimbo às strings que seu código entrega a lugares perigosos.

DOM: abreviação de Document Object Model, a árvore viva de elementos que o navegador monta a partir de uma página, e que o JavaScript consegue ler e mudar.

Sink: um lugar no DOM em que uma string vira código ou marcação. Exemplos: element.innerHTML, outerHTML, insertAdjacentHTML, document.write, iframe.srcdoc, eval e argumentos de string para setTimeout, e script.src.

Trusted Types: um recurso do navegador, ligado pela CSP, com o qual esses sinks só aceitam objetos especiais (TrustedHTML, TrustedScript, TrustedScriptURL) feitos por uma política, uma pequena função que você escreve e nomeia. Uma string simples atribuída a um sink levanta um erro em vez de rodar.

Ligando o recurso

Content-Security-Policy: require-trusted-types-for 'script'; trusted-types comments
  • require-trusted-types-for 'script': aplica o recurso em todos os sinks ligados a script.
  • trusted-types comments: o único nome de política que seu código pode criar. Um script injetado não consegue registrar uma política própria com outro nome. trusted-types 'none' proíbe criar qualquer uma.

Usando no seu código

// The one, reviewed place that turns text into HTML.
const commentsPolicy = trustedTypes.createPolicy("comments", {
  createHTML: (text) => escapeHtml(text),   // or a well-tested sanitiser
});

box.innerHTML = comment;                              // throws TypeError: blocked
box.innerHTML = commentsPolicy.createHTML(comment);   // allowed, escaped
box.textContent = comment;                            // not a sink at all: always fine

O grande ganho é para quem revisa. Em vez de caçar todo innerHTML em uma base de código grande, você revisa as poucas funções de política. Se elas forem seguras, o navegador garante que todo o resto passe por elas.

Uma política chamada default é especial: o navegador a chama automaticamente sempre que uma string simples chega a um sink. Ela é útil durante a migração de código antigo, mas também é um lugar em que os erros se escondem, então mantenha-a rigorosa e registre o que passa por ela.

Suporte e implantação

O Trusted Types é aceito em todos os principais motores: navegadores baseados em Chromium, Safari 26 e Firefox 148 (verificado em outubro de 2026). Visitantes em navegadores mais antigos simplesmente não recebem a verificação extra, então mantenha o escape e mantenha sua CSP com nonces. O código pode testar o suporte com if (window.trustedTypes).

Implante como qualquer política: envie require-trusted-types-for 'script' primeiro em um cabeçalho Content-Security-Policy-Report-Only. Toda string que chega a um sink é informada, mostrando exatamente quais linhas precisam de uma política ou, melhor, de uma troca para textContent.

Um equívoco comum: "o Trusted Types limpa o HTML para mim". Ele não limpa nada. Ele obriga as strings a passarem pela sua política. Uma política que retorna a entrada sem mudança (createHTML: s => s) passa na verificação e não protege nada.

Resumo

  • A injeção no DOM acontece no seu próprio JavaScript, em sinks como innerHTML; regras só sobre tags de script não a pegam.
  • require-trusted-types-for 'script' faz os sinks recusarem strings simples; trusted-types NAME limita quais políticas podem existir.
  • Revise as poucas funções de política em vez de todo sink, e prefira textContent quando puder.
  • Aceito em todos os principais motores (verificado em outubro de 2026); implante primeiro em report-only.

Viu um problema nesta lição? Reporte-o · Pergunte sobre esta lição

Este exercício abre em breve

Termine a lição anterior para que esta seja desbloqueada. O curso inteiro é gratuito, não precisa de conta, e você pode ler esta lição agora mesmo.