# Codificador e Decodificador de URL / URI: Arquitetura Técnica e Guia Avançado

Identificadores Uniformes de Recursos (URIs) e URLs definem o endereçamento da Web. Normatizados pela blank" rel="noopener noreferrer" class="text-emerald-400 hover:text-emerald-300 underline underline-offset-4 decoration-emerald-500/40 hover:decoration-emerald-400 font-medium transition inline-flex items-center gap-0.5">RFC 3986 e pelo WHATWG URL Living Standard, os endereços impõem regras sintáticas estritas para garantir roteamento determinístico entre proxies, gateways e microsserviços.

Ao trafegar dados em query strings, rotas ou formulários HTTP, caracteres como pontuações, espaços, glifos Unicode e bytes binários são convertidos para US-ASCII via codificação percentual (percent-encoding). Falhas de escape causam rotas quebradas, vulnerabilidades como Redirecionamento Aberto (Open Redirect) e SSRF (Server-Side Request Forgery), além de exceções como URIError: URI malformed.

O Codificador e Decodificador de URL do ToolsAA combina url encoder online, url decoder bidirecional e suporte estrito a encodeURIComponent online. Com arquitetura 100% no cliente ("use client"), todo o processamento executa na memória do navegador. Zero dados ou telemetria deixam seu dispositivo, garantindo privacidade para tokens OAuth, chaves de API e URLs confidenciais.

# Visão Geral Abrangente e Casos de Uso no Mundo Real

A codificação de URL converte bytes em tripletos US-ASCII %XY, onde XY é o valor hexadecimal do byte em UTF-8. Isso preserva delimitadores estruturais da URI enquanto neutraliza caracteres literais na carga útil.

+---------------------------------------------------------------------------------------------------+
|                                      Anatomia de uma URI Moderna                                  |
|  https://api.dominio.com:443 /v2/busca/recurso ;matriz=val ?q=ferramentas+dev&lang=pt #resultado |
|  |___|   |________________| |__| |________________| |__________| |_______________________| |_________| |
| Esquema     Autoridade      Porta     Caminho         Matriz           Query String         Fragmento  |
+---------------------------------------------------------------------------------------------------+
                                                   |
                        +--------------------------+--------------------------+
                        |                                                     |
                        v                                                     v
           [ Codificação de Componentes ]                             [ Codificação de URI Completa ]
           - Preserva: ALPHA, DIGIT, - _ . ~                         - Preserva: Esquema, host, porta,
           - Codifica: : / ? # [ ] @ ! $ & ' ( ) * + , ; =             barras do caminho, separadores
           - Alvo: Chaves e valores de query string                  - Alvo: Endereços web integrais

# Casos de Uso Críticos em Engenharia de Software

• Fluxos OAuth 2.0 e OIDC: URIs de retorno (redirecturi) exigem codificação de componentes para isolar callbacks e proteger o codechallenge PKCE.
• APIs REST e GraphQL: Requisições GET com filtros ou cursores escapam objetos JSON (filtro={"status":"ativo"} vira filtro=%7B%22status%22%3A%22ativo%22%7D).
• Assinatura AWS SigV4: APIs em nuvem exigem query strings canônicas ordenadas lexicograficamente e codificadas via RFC 3986 estrita para validar assinaturas HMAC.
• Internacionalização (i18n): Acentos em português (ç, ã, é) e emojis viram tripletos hexadecimais (São Paulo vira S%C3%A3o%20Paulo).
• Webhooks e Formulários: Cargas em application/x-www-form-urlencoded convertem espaços em + e escapam delimitadores para trânsito em filas.

# Por Que o Processamento no Cliente É Inegociável para a Privacidade

Utilitários online que transmitem dados a servidores externos geram passivos graves de segurança. URLs de depuração frequentemente transportam códigos OAuth, cookies de sessão, tokens JWT e credenciais de API. Transmitir essas sequências pela rede viola normas como LGPD, GDPR, SOC 2 e HIPAA ao expor dados a logs e proxies.

O ToolsAA adota o Modelo Estrito de Zero Servidor: todas as operações ocorrem na sandbox local do navegador. Zero pacotes deixam seu dispositivo.

# Arquitetura Técnica e Funcionamento Interno

Compreender as normas que regem URLs evita truncamentos silenciosos de parâmetros e falhas em integrações.

# 1. O Contínuo de Padrões: RFC 3986 vs RFC 2396 vs WHATWG

A RFC 2396 (1998) tratava pontuações (!, ', (, ), *) como marcas não reservadas, preservadas pelo encodeURIComponent() do JavaScript por retrocompatibilidade. A RFC 3986 (2005) reclassificou-as como subdelimitadores reservados, exigindo escape em contextos estritos. Apenas A-Z, a-z, 0-9, -, _, ., ~ são não reservados. O WHATWG URL Living Standard padronizou a análise moderna e o formato application/x-www-form-urlencoded.

# 2. Mecânica em Nível de Bytes da Codificação Percentual UTF-8

Antes do escape percentual, os caracteres são serializados em UTF-8:

• 1 Byte (U+0000 a U+007F): US-ASCII. Espaço (U+0020) vira %20.
• 2 Bytes (U+0080 a U+07FF): Acentos latinos. é (U+00E9) vira 0xC3 0xA9 (%C3%A9); ç vira %C3%A7.
• 3 Bytes (U+0800 a U+FFFF): Ideogramas CJK. 東 (U+6771) vira 0xE6 0x9D 0xB1 (%E6%9D%B1).
• 4 Bytes (U+10000 a U+10FFFF): Emojis. 🚀 (U+1F680) vira 0xF0 0x9F 0x9A 0x80 (%F0%9F%9A%80).

No JavaScript, caracteres acima de U+FFFF utilizam pares substitutos UTF-16 (surrogate pairs). Substitutos órfãos disparam URIError: URI malformed.

# 3. O Trio de APIs Nativas da Web no Navegador

• encodeURIComponent(): Codifica caracteres reservados, exceto A-Z, a-z, 0-9, -, _, ., !, ~, *, ', (, ). Foco: parâmetros individuais.
• encodeURI(): Codifica caracteres ilegais preservando delimitadores sintáticos (:, /, ?, #, [, ], @, !, $, &, ', (, ), *, +, ,, ;, =). Foco: URLs completas.
• URLSearchParams: Implementa application/x-www-form-urlencoded, formatando espaços como + e interpretando tanto + quanto %20 como espaços.

# 4. APIs Web do Navegador, Web Crypto e Execução Client-Side

• React 18 Concorrente: O hook useDeferredValue() dissocia digitação da computação, mantendo 60 FPS estáveis na UI.
• Web Workers e Streams: Entradas acima de 500 KB são processadas em background com TextEncoder e TextDecoder.
• Web Crypto API: Gera resumos SHA-256 no navegador (crypto.subtle.digest) para validar PKCE e assinaturas HMAC.
• Canvas HTML5: Renderiza mapas de distribuição de bytes em canvas offscreen sem causar reflows no DOM.

# Guia Prático Passo a Passo

# Passo 1: Ingestão de Dados e Presets

Cole a query string, URL ou token no editor, ou selecione presets como OAuth 2.0 PKCE ou Payload JSON Aninhado. Arquivos locais podem ser carregados via FileReader sem envio ao servidor.

# Passo 2: Seleção do Algoritmo de Codificação

• encodeURIComponent: Para valores de query string e parâmetros isolados.
• RFC 3986 Estrito: Para assinaturas em nuvem (AWS SigV4, OAuth 1.0a), convertendo !, ', (, ) e * para hexadecimal.
• encodeURI: Para sanitizar URLs completas preservando barras e delimitadores.
• application/x-www-form-urlencoded: Para codificar espaços como + em formulários HTML.

# Passo 3: Análise Interativa de Parâmetros

O ToolsAA decompõe a URL em uma tabela dinâmica de chave-valor. Habilite ou desabilite parâmetros via checkboxes, altere valores inline e adicione tags UTM com sincronização imediata.

# Passo 4: Decodificação Segura e Recursiva

• Detecção de Dupla Codificação: Identifica sequências como %2520 ou %253A com alertas imediatos.
• Descompactação Recursiva (Auto-Unpack): Desfaz camadas sucessivas de percent-encoding aninhadas.
• Decodificação Resiliente: Isola sequências corrompidas com marcadores visuais sem abortar o processo.

# Passo 5: Métricas de Bytes e Exportação

Monitore contagem de caracteres, bytes UTF-8 e taxa de expansão em tempo real. Copie o resultado com um clique ou baixe o texto processado.

# Implementações de Código para Produção

# 1. Implementação em TypeScript / JavaScript Moderno

Biblioteca de alto desempenho e sem dependências com suporte a RFC 3986, tolerância a falhas e manipulação de query strings:

export type EncodingMode = "rfc3986" | "component" | "fullUri" | "formUrlEncoded";

export class UrlCodec {
  public static encodeStrictRFC3986(input: string): string {
    return encodeURIComponent(input).replace(
      /[!'()*]/g,
      (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`
    );
  }

  public static encode(input: string, mode: EncodingMode = "component"): string {
    if (!input) return "";
    switch (mode) {
      case "rfc3986": return this.encodeStrictRFC3986(input);
      case "component": return encodeURIComponent(input);
      case "fullUri": return encodeURI(input);
      case "formUrlEncoded":
        return encodeURIComponent(input)
          .replace(/%20/g, "+")
          .replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
      default: throw new Error(`Modo não suportado: ${mode}`);
    }
  }

  public static safeDecode(input: string, isForm = false): { text: string; error: boolean } {
    if (!input) return { text: "", error: false };
    const normalized = isForm ? input.replace(/\+/g, " ") : input;
    try {
      return { text: decodeURIComponent(normalized), error: false };
    } catch {
      let output = "", hasError = false;
      for (const token of normalized.split(/(%[0-9a-fA-F]{2})/g)) {
        if (token.startsWith("%") && token.length === 3) {
          try { output += decodeURIComponent(token); }
          catch { output += token; hasError = true; }
        } else { output += token; }
      }
      return { text: output, error: hasError };
    }
  }

  public static parseQuery(urlOrQuery: string): Record<string, string[]> {
    const raw = urlOrQuery.includes("?") ? urlOrQuery.split("?")[1].split("#")[0] : urlOrQuery;
    const params: Record<string, string[]> = {};
    new URLSearchParams(raw).forEach((val, key) => {
      params[key] = params[key] ? [...params[key], val] : [val];
    });
    return params;
  }
}

# 2. Implementação em Python 3.11+

Implementação tipada em Python para codificação RFC 3986 e geração de query strings canônicas para APIs:

from typing import Dict, List, Tuple, Union
import urllib.parse

class UrlCodec:
    @staticmethod
    def encode_rfc3986(value: str) -> str:
        return urllib.parse.quote(value or "", safe="-_.~")

    @staticmethod
    def encode_form(value: str) -> str:
        return urllib.parse.quote_plus(value or "")

    @staticmethod
    def safe_decode(encoded_str: str, is_form: bool = False) -> str:
        if not encoded_str:
            return ""
        decoder = urllib.parse.unquote_plus if is_form else urllib.parse.unquote
        return decoder(encoded_str, errors="replace")

    @classmethod
    def build_canonical_query(cls, params: Dict[str, Union[str, List[str]]]) -> str:
        pairs: List[Tuple[str, str]] = []
        for key, val in params.items():
            k = cls.encode_rfc3986(str(key))
            items = val if isinstance(val, list) else [val]
            for item in items:
                pairs.append((k, cls.encode_rfc3986(str(item))))
        pairs.sort(key=lambda x: (x[0], x[1]))
        return "&".join(f"{k}={v}" for k, v in pairs)

# Armadilhas Comuns, Casos Limite e Solução de Problemas

# 1. O Problema da Dupla Codificação (%2520)

A dupla codificação converte % em %25, transformando %20 em %2520.

• Solução: Verifique a idempotência antes de recodificar: se decodeURIComponent(str) !== str, a string já contém dados codificados.

# 2. A Dualidade de Espaços: + versus %20

Na RFC 3986, espaço deve ser %20, enquanto em application/x-www-form-urlencoded espaços tornam-se +.

• Solução: Codifique o mais literal como %2B. Utilize %20 em APIs REST e reserve + para corpos de formulários.

# 3. Substitutos Isolados UTF-16 e URIError

Strings em JavaScript usam UTF-16. Truncar um emoji no meio do par substituto deixa um substituto órfão (\uD83D), gerando erro em encodeURIComponent().

• Solução: Sanitize os dados com String.prototype.toWellFormed() antes de codificar:

```javascript const urlSegura = encodeURIComponent(entrada.toWellFormed()); ```

# 4. Divisão Manual de Query Strings em Delimitadores Literais

Dividir URLs com .split("&") corrompe parâmetros contendo delimitadores legitimamente codificados como %26 ou %3D.

• Solução: Use exclusivamente as APIs padrão URL e URLSearchParams.

# 5. Barras Codificadas (%2F) em Proxies Reversos

Ao enviar %2F no caminho da URL, o Apache rejeita com 404 por padrão, enquanto o Nginx decodifica %2F para / antes de encaminhar ao backend.

• Solução: Transporte dados com barras em parâmetros de consulta (?rota=pasta%2Farquivo).

# 6. Domínios Internacionalizados (IDN) vs Codificação de Caminho

Executar encodeURI("https://münchen.de") produz https://m%C3%BCnchen.de, rejeitado por servidores DNS.

• Solução: Nomes de host exigem Punycode (xn--mnchen-3ya.de via RFC 5891). A codificação percentual aplica-se apenas a caminhos e queries.

# Perguntas Frequentes (FAQ)

# Q1: Qual é a diferença exata entre encodeURI() e encodeURIComponent()?

Resposta: encodeURI() normaliza URLs completas preservando delimitadores estruturais (:, /, ?, #, &, =) e codificando caracteres ilegais. Já encodeURIComponent() escapa valores individuais, convertendo inclusive delimitadores para isolar os parâmetros.

# Q2: Por que encodeURIComponent() preserva !, ', (, ) e *?

Resposta: O JavaScript adotou a RFC 2396 legada, que tratava esses símbolos como marcas não reservadas. A RFC 3986 reclassificou-os como reservados. APIs rígidas (AWS SigV4, OAuth 1.0a) exigem escape manual: str.replace(/[!'()*]/g, c => "%" + c.charCodeAt(0).toString(16).toUpperCase()).

# Q3: Quando o espaço deve ser representado como + e quando deve ser %20?

Resposta: O caractere + representa espaço apenas em payloads application/x-www-form-urlencoded (formulários HTML). Em requisições REST, APIs JSON e conformidade com a RFC 3986, espaços devem ser codificados como %20. Em caminhos de rota, + indica um sinal de mais literal.

# Q4: Como evitar exceções URIError: URI malformed ao decodificar strings externas?

Resposta: O decodeURIComponent() nativo falha diante de percentuais incompletos ou substitutos UTF-16 isolados. Trate a operação em blocos try...catch com tokenização tolerante, ou higienize a entrada previamente com str.toWellFormed() para neutralizar substitutos órfãos.

# Q5: Como funciona a codificação percentual UTF-8 para emojis e caracteres não latinos?

Resposta: Caracteres não ASCII são convertidos em bytes binários UTF-8, e cada byte vira um tripleto hexadecimal %XX. A letra á demanda 2 bytes (%C3%A1). Ideogramas como 東 ocupam 3 bytes (%E6%9D%B1). Emojis como 🚀 exigem 4 bytes (%F0%9F%9A%80).

# Q6: Como detectar programaticamente se uma string já foi codificada em URL?

Resposta: Verifique a presença de tripletos com a regex /%[0-9A-Fa-f]{2}/.test(str) e aplique o teste de idempotência: se decodeURIComponent(str) !== str, a cadeia já contém valores codificados que não devem ser recodificados.

# Q7: Minhas chaves de API ou URLs confidenciais são enviadas a servidores no ToolsAA?

Resposta: Não. O ToolsAA opera 100% no cliente ("use client"). Todo o processamento ocorre na memória local do navegador sem requisições externas, garantindo conformidade irrestrita com a LGPD e o GDPR.

# Q8: Por que proxies reversos retornam erro 400 ou 404 em URLs com %2F no caminho?

Resposta: Apache e Nginx tratam barras codificadas em caminhos como risco de travessia de diretório (directory traversal). O Apache rejeita %2F com erro 404 por padrão, enquanto o Nginx o normaliza para /. Transmita barras sempre em parâmetros de consulta.

# Matriz de Comparação Técnica: Especificações de Codificação de URL

# Conclusão

A aplicação rigorosa da codificação de URL é indispensável para construir arquiteturas web seguras e resilientes. Seja na proteção de fluxos OAuth 2.0 e OIDC, na assinatura canônica de requisições de nuvem ou na internacionalização de rotas, dominar a manipulação de caracteres elimina bugs silenciosos e riscos de segurança.

Compreendendo as diferenças entre a RFC 3986, encodeURIComponent() e formulários HTML, engenheiros evitam dupla codificação e bloqueios em proxies reversos. O Codificador e Decodificador de URL do ToolsAA garante precisão técnica e privacidade irrestrita, executando 100% no cliente sem telemetria ou envio de dados a servidores.