Codificar entidades HTML

Um parser de HTML se importa com pouquíssimos caracteres. O sinal de menor e o de maior abrem e fecham uma tag, o e comercial abre uma referência de caractere, e dentro do valor de um atributo as aspas duplas e as simples terminam esse valor. São cinco, e todo o resto é conteúdo comum.

Por isso o ajuste sóbrio escapa exatamente esses cinco e nada mais. Um codificador que transforme cada acento numa entidade não é mais seguro: ele só produz uma saída quatro ou cinco vezes mais longa e ilegível para pessoas, protegendo contra exatamente os mesmos ataques que a versão curta.

Quem substitui na mão precisa começar pelo `&`. Se ele ficar para depois, o codificador já gerou as próprias entidades e escapa de novo o `&` de cada uma: um `<` vira `&lt;` e isso vira `&amp;lt;`, e a página mostra o texto `&lt;` em vez de um sinal de menor.

É de longe o erro mais comum nas funções de escape caseiras, e um dos poucos que se reconhece a olho na saída: se aparece `&amp;` na frente de outros nomes de entidade, a ordem está errada. Esta ferramenta resolve a substituição numa passada só, então o problema não tem como acontecer.

Entre duas tags bastam três substituições: menor, maior e e comercial. Dentro do valor de um atributo entram também as aspas, porque ali uma aspa dupla termina o valor e o que vier depois é lido pelo parser como mais um atributo — a via clássica para enfiar um `onmouseover` numa tag alheia.

O caso pior são os valores de atributo sem aspas, que o HTML permite: ali basta um espaço para terminar o valor, e escapar já não alcança. A regra prática é sempre colocar aspas nos atributos e escapar os cinco caracteres, que é exatamente o que o ajuste desta página faz.

O segundo ajuste escreve também cada caractere fora do ASCII como referência numérica, de modo que um `ç` vira `&#231;`. Para segurança isso não acrescenta nada e para legibilidade é uma perda: só serve onde algum elo da esteira não suporta UTF-8.

Esses elos ainda existem: modelos de e-mail antigos, exportações para sistemas com Latin-1 no código, de vez em quando uma coluna com a collation errada. Se as cedilhas e os acentos viram interrogação ou pares de letras estranhos no caminho, a forma numérica é um desvio sólido. Onde a esteira fala UTF-8 direito, ela sobra.

Escapar protege num lugar: na hora de inserir em HTML. Não é validação de entrada nem substitui nenhuma. Quem escapa ao salvar em vez de ao mostrar acaba com dados no banco que aparecem como `&amp;` numa resposta JSON, numa exportação CSV ou num e-mail — lugares em que HTML nunca esteve envolvido.

A ordem que funciona é a inversa: guardar cru e escapar ao renderizar para o destino específico. Os mesmos dados então saem corretos em HTML, em JSON e num e-mail de texto puro, cada um com as suas regras, e ninguém precisa adivinhar em que estado está um campo.

O HTML aceita referências com nome como `&amp;`, decimais como `&#38;` e hexadecimais como `&#x26;`. As três designam o mesmo caractere e um parser aceita as três. Esta ferramenta gera as de nome para os cinco caracteres decisivos, porque elas se leem no código-fonte, e numéricas para todo o resto.

Ao ler saídas alheias você vai encontrar as três misturadas, muitas vezes no mesmo arquivo, porque foram produzidas por peças diferentes. Não é erro nem indica problema: só diz que naquele documento passou mais de uma ferramenta.

A aspa simples tem um nome, `&apos;`, mas ele vem do XML e não fez parte oficialmente do HTML até o HTML5. No HTML 4 ele não estava definido, então parsers muito antigos imprimem aquilo como texto em vez de resolver.

A forma numérica `&#39;` nunca teve esse problema e funciona em todo lugar, por isso continua sendo a opção padrão de quase toda biblioteca de escape. É um daqueles casos em que uma incompatibilidade de vinte anos atrás fixou a convenção mesmo depois de o motivo ter desaparecido.

Um valor escrito dentro de um bloco `<script>` já não está em contexto HTML e sim em contexto JavaScript, e ali valem outras regras. Uma aspa escapada como entidade não ajuda; e, ao contrário, uma string inofensiva em HTML pode fechar o script.

O mesmo vale para um valor dentro de um `href`, de um `style` ou de um `data-` que depois é avaliado. Cada um desses lugares tem o escape dele, e a pergunta certa nunca é «está escapado?» e sim «está escapado para o lugar em que vai parar?». Esta ferramenta responde ao caso HTML.

Escapar é tudo ou nada: depois dele nenhuma tag funciona, inclusive as que você queria deixar passar. Se o requisito é aceitar negrito e link de um editor de texto rico, escapar é a ferramenta errada, e escapar parcialmente na mão é a maneira mais rápida de abrir um buraco.

O que resolve isso é um sanitizador com lista de permissão: uma biblioteca que interpreta o HTML, joga fora tudo que não está na lista de tags e atributos aceitos e devolve o resto. É outro problema, com outras bibliotecas, e a única coisa que as duas abordagens têm em comum é que nenhuma das duas deve ser escrita à mão.

Quase todo motor de template moderno escapa por padrão. O Django, o Jinja, o Rails e o React fazem isso sem você pedir, e é por isso que a maioria dos aplicativos nunca precisa desta página no fluxo normal — o escape já está lá.

A falha, quando aparece, quase sempre está na porta de saída desse comportamento: um `|safe`, um `raw`, um `dangerouslySetInnerHTML`. Cada um deles existe por um motivo legítimo e cada um transfere a responsabilidade para quem escreveu a linha. Procurar essas três palavras no código é uma revisão de segurança de cinco minutos que vale a pena fazer.

O que se cola neste campo normalmente é texto de outra pessoa: um comentário de usuário, uma mensagem de suporte, uma descrição com nomes dentro. Como a substituição acontece na página, não há compartilhamento conosco nem operação de tratamento nossa sobre esse conteúdo.

Isso se confere no painel de rede do navegador: enquanto você usa, nenhuma requisição sai com a sua entrada. A página vem de uma CDN e o site tem publicidade, então existem requisições — elas sabem que você esteve aqui, não o que está no campo.