Erros de URL encoding parecem pequenos: um espaço, um sinal de mais, uma barra ou um ampersand. Mesmo assim, eles podem mudar o significado de toda a requisição. Um filtro vira dois parâmetros, um ID vira dois segmentos, uma assinatura falha ou um redirect aponta para outro domínio. A causa é a mesma: URLs usam caracteres tanto como dados quanto como sintaxe.

Path e query seguem regras diferentes

Em paths, / separa segmentos. Em query strings, & separa parâmetros e = separa chave e valor. Em formulários, + pode significar espaço. Uma única função de escape não serve para todos esses contextos.

Use funções específicas para path segment e query parameter. A separação existe porque a gramática é diferente.

Encoding duplo cria strings inesperadas

%20 codificado outra vez vira %2520. Um decoder recupera o texto literal %20; dois decoders recuperam espaço. Essa diferença quebra routes, caches e assinaturas e pode criar problemas de segurança.

Mantenha valores brutos internamente e codifique apenas ao construir a URL final. Não salve estados parcialmente encoded.

Concatenar query strings falha com dados reais

Um valor como “P&D” contém um separador. Nomes com espaço, acento ou sinal de igual expõem outras falhas. A demo com abc funciona, mas o primeiro usuário real quebra a construção.

Uma API de parâmetros resolve encoding, repetição de chaves e arrays, além de deixar o código mais legível.

Assinaturas exigem canonicalização exata

APIs assinadas podem calcular HMAC sobre método, path, query e body. Ordem de parâmetros, caixa do percent-encoding e tratamento de espaços precisam ser idênticos. Conteúdo semanticamente igual pode produzir bytes diferentes.

O protocolo deve fornecer vectors de teste. Produtor e consumidor precisam seguir a mesma regra, não o comportamento default de bibliotecas distintas.

Decoding em camadas pode alterar autorização

Proxy, servidor e framework podem decodificar em momentos diferentes. Uma barra encoded pode ser dado em uma camada e separador em outra. Se permissão é verificada numa forma e a rota executada em outra, surge um bypass.

Defina quais encodings ambíguos são rejeitados e qual forma normalizada participa da decisão.

Unicode requer encoding consistente

Caracteres não ASCII viram bytes, geralmente UTF-8, antes do percent-encoding. Se as partes discordam, o texto recuperado muda. Domínios internacionalizados seguem regras de IDNA e punycode.

Validação visual não é suficiente para hosts. Use bibliotecas mantidas e compare a representação normalizada.

Redirects exigem política além de escaping

Um parâmetro next pode estar perfeitamente encoded e apontar para um domínio malicioso. O sistema precisa permitir apenas paths internos ou hosts conhecidos. Encoding protege sintaxe; allowlist protege destino.

Encoding duplo também pode esconder a URL externa até uma segunda etapa. Normalize e valide uma vez, com regra explícita.

Logs podem mostrar outra representação

Algumas ferramentas exibem a URL decodificada; outras preservam a forma bruta. Comparar logs sem conhecer essa escolha confunde investigações. Registre, quando seguro, request target bruto, componentes parseados e resultado normalizado.

Limites de comprimento e quantidade de parâmetros também evitam que URLs gigantes sobrecarreguem proxies e logs.

A prevenção acontece na construção

Trabalhe com objetos URL, segmentos e parâmetros, não com strings concatenadas. Teste espaços, acentos, ampersands, barras, sinais de mais, valores já encoded e destinos proibidos.

Frameworks e proxies precisam concordar

Se o proxy normaliza uma barra encoded de modo diferente do framework, a camada de segurança pode analisar outra rota. Testes de integração devem atravessar a infraestrutura real, não apenas chamar diretamente o router da aplicação.

Regras de trailing slash, case sensitivity e decoding devem ser alinhadas para evitar redirects inesperados e bypasses de autorização.

Falhas devem preservar evidência

Ao rejeitar uma URL, logs internos podem registrar componente e regra violada, com redaction de dados sensíveis. Uma mensagem externa simples evita expor detalhes, enquanto o request ID permite investigação.

Parâmetros repetidos precisam de regra

Uma query pode conter role=user&role=admin. Frameworks divergem: alguns escolhem o primeiro valor, outros o último, outros criam array. Se validação e lógica de negócio usam interpretações diferentes, o atacante explora a discrepância.

Defina quais parâmetros podem repetir, como arrays são representados e o que acontece com duplicatas inesperadas. A regra deve ser igual no gateway e na aplicação.

Encoding deve ocorrer exatamente uma vez

O componente que constrói a URL final deve ser dono do percent-encoding. Se camadas anteriores entregam valores parcialmente encoded, ninguém sabe se deve preservar ou escapar novamente. Tipos e helpers específicos podem tornar essa responsabilidade visível.

Testes de integração devem conferir o request target recebido pelo servidor, não apenas a string antes do cliente HTTP. A biblioteca pode normalizar ou reencodar durante o envio.

Ao armazenar uma URL recebida, guarde também a versão normalizada usada pela política. Isso ajuda a comparar, deduplicar e investigar corretamente sem perder a evidência original quando ela é necessária.

Uma URL correta não é aquela que parece normal. É aquela em que cada caractere reservado mantém o papel definido pelo componente.