Codificação de Entidades HTML vs Codificação de URL: Principais Diferenças

O que é Codificação de Entidades HTML?

A codificação de entidades HTML (também chamada de escape HTML) converte caracteres que têm significado especial em HTML em referências de entidade que os navegadores exibem como o caractere literal, em vez de interpretá-los como marcação. Os caracteres mais importantes a codificar são <, >, &, " e '.

Sem a codificação HTML, uma string como <script>alert('XSS')</script> seria executada como JavaScript pelo navegador. Com a codificação, ela se torna <script>alert('XSS')</script> e é exibida como texto inofensivo.

As entidades HTML podem ser escritas de duas formas: entidades nomeadas como &, < e ", ou entidades numéricas como &, < e ". As entidades numéricas usam o code point Unicode do caractere e podem representar qualquer caractere Unicode.

<!-- Antes da codificação HTML -->
<p>The formula is: x < y & y > z</p>
<!-- O navegador interpreta < como o início de uma tag! -->

<!-- Depois da codificação HTML -->
<p>The formula is: x &lt; y &amp; y &gt; z</p>
<!-- O navegador exibe: x < y & y > z -->

<!-- Entidades HTML comuns -->
&amp;   → &   (E comercial)
&lt;    → <   (menor que)
&gt;    → >   (maior que)
&quot;  → "   (aspas duplas)
&#39;   → '   (aspas simples / apóstrofo)
&nbsp;  →     (espaço não separável)

O que é Codificação de URL?

A codificação de URL (percent-encoding) converte caracteres que não são seguros em URLs em um sinal de porcentagem seguido por dois dígitos hexadecimais que representam o valor do byte. Ela é definida pela RFC 3986 e garante que as URLs contenham apenas caracteres ASCII válidos que possam ser transmitidos com segurança pela internet.

A codificação de URL é necessária porque as URLs têm uma sintaxe rígida em que certos caracteres funcionam como delimitadores (/, ?, &, #, =). Quando esses caracteres aparecem em dados (como valores de parâmetros de consulta), eles precisam ser codificados para evitar que sejam interpretados como elementos estruturais.

// Exemplos de codificação de URL
space     → %20
&         → %26
=         → %3D
?         → %3F
#         → %23
/         → %2F
+         → %2B

// URL completa com parâmetro de consulta codificado
https://example.com/search?q=salt%20%26%20pepper
// O valor de q é "salt & pepper"

Tabela Comparativa

Característica	Codificação de Entidades HTML	Codificação de URL
Finalidade	Exibição segura em páginas HTML	Transmissão segura em URLs
Padrão	Especificação HTML/WHATWG	RFC 3986
Formato	&name; ou &#number;	%XX (valor do byte em hex)
Espaço vira	  (não separável) ou mantido como está	%20 ou +
& vira	&	%26
< vira	&lt;	%3C
Previne	Ataques XSS, HTML quebrado	URLs quebradas, ataques de injeção
Contexto	Corpo e atributos de documentos HTML	Caminhos de URL, query strings, fragmentos
Função JS	Nenhuma nativa (use uma biblioteca ou as APIs do DOM)	encodeURIComponent()

Quando Você Precisa das Duas?

Existem situações comuns em que você precisa tanto da codificação HTML quanto da codificação de URL. O caso mais frequente é quando você coloca uma URL dentro de um atributo HTML, como um atributo href ou src. A URL deve primeiro ser corretamente codificada como URL e, em seguida, quaisquer caracteres HTML especiais no resultado devem ser codificados como HTML.

<!-- Passo 1: Codificar como URL o valor do parâmetro de consulta -->
<!-- Valor: "Tom & Jerry" → codificado como URL: "Tom%20%26%20Jerry" -->

<!-- Passo 2: Montar a URL -->
<!-- URL: https://example.com/search?q=Tom%20%26%20Jerry -->

<!-- Passo 3: Codificar como HTML a URL para uso em um atributo href -->
<a href="https://example.com/search?q=Tom%20%26%20Jerry">
  Search for Tom &amp; Jerry
</a>

<!-- Neste caso, as sequências % não precisam de codificação HTML -->
<!-- porque % não é um caractere HTML especial -->

<!-- Mas se a URL contiver & como delimitador, ele DEVE ser codificado como HTML: -->
<a href="https://example.com/search?q=cats&amp;sort=name">
  Search cats sorted by name
</a>
<!-- Sem &amp;, o navegador pode interpretar &sort como uma entidade HTML -->

Em frameworks modernos como React, Vue e Angular, a codificação HTML é tratada automaticamente quando você usa expressões de template ou JSX. No entanto, a codificação de URL ainda precisa ser feita explicitamente ao construir URLs a partir de dados dinâmicos.

// React - a codificação HTML é automática, a de URL não é
function SearchLink({ query }) {
  // A codificação de URL deve ser explícita
  const url = '/search?q=' + encodeURIComponent(query);

  // A codificação HTML é automática no JSX
  return <a href={url}>Search for {query}</a>;
  // O React codifica automaticamente como HTML tanto o href quanto o conteúdo de texto
}

Prevenção de XSS: Qual Codificação Usar e Onde

A prevenção de Cross-Site Scripting (XSS) exige a aplicação da codificação correta com base no contexto onde a entrada do usuário é inserida. Usar o tipo errado de codificação em um determinado contexto não oferece nenhuma proteção.

• Contexto do corpo HTML: Use codificação de entidades HTML. Isso impede que tags injetadas como <script> sejam interpretadas como marcação.
• Contexto de atributo HTML: Use codificação de entidades HTML e sempre coloque os valores de atributo entre aspas. Atributos sem aspas podem ser escapados mesmo com a codificação HTML.
• Contexto de URL (href, src): Use codificação de URL para as partes dinâmicas e, em seguida, codifique como HTML a URL inteira ao inseri-la em HTML. Valide que a URL começa com um esquema seguro (https:) para evitar URLs javascript:.
• Contexto JavaScript: Use escape de strings JavaScript (JSON.stringify ou uma biblioteca dedicada). Nem a codificação HTML nem a codificação de URL são suficientes em um contexto JavaScript.
• Contexto CSS: Use escape de CSS. As codificações HTML e de URL não protegem contra injeção de CSS.

O princípio fundamental é: codifique para o contexto de saída, não para a fonte de entrada. Uma mesma entrada de usuário pode precisar de codificações diferentes dependendo de onde ela aparece na resposta. Nunca dependa apenas da validação de entrada para a prevenção de XSS; sempre aplique a codificação de saída.