Codifica percentuale

La codifica percentuale (chiamata anche codifica URL) è il meccanismo che gli URL usano per rappresentare caratteri non legali nella grammatica URL o che hanno significati riservati. Definita in RFC 3986 §2.

Lo schema: ogni byte da sottoporre a escape è scritto come % seguito da due cifre esadecimali che rappresentano il valore del byte. Lo spazio diventa %20. Il punto interrogativo diventa %3F. La barra obliqua diventa %2F. Il cancelletto diventa %23.

Per i caratteri non-ASCII (umlaut, accenti, CJK, emoji), il carattere viene prima codificato UTF-8 in una sequenza di byte, poi ogni byte viene codificato in percentuale. Il singolo carattere “é” (U+00E9) diventa i byte 0xC3 0xA9 in UTF-8, codificati in percentuale come %C3%A9.

Tre classi di caratteri da conoscere:

• Non riservati — A-Z, a-z, 0-9 e -_.~. Non vengono mai sottoposti a escape.
• Riservati — caratteri con significato sintattico (:/?#[]@!$'()*+,;=). Vengono sottoposti a escape quando appaiono in dati che non devono essere analizzati come sintassi URL.
• Altri — tutto il resto (spazi, non-ASCII, caratteri di controllo). Vengono sempre sottoposti a escape.

Codifica o decodifica qualsiasi stringa nel nostro codificatore URL, che gestisce correttamente UTF-8 (alcune implementazioni legacy trattano le stringhe come ISO-8859-1 e producono output diversi per lo stesso input).

La nota sullo spazio come segno più: nel percorso e nel frammento di un URL, uno spazio si codifica come %20. Ma nella stringa di query di un corpo application/x-www-form-urlencoded, gli spazi si codificano come + — una convenzione specifica delle form precedente alla moderna specifica URL. encodeURIComponent() di JavaScript emette sempre %20; il vecchio escape() (deprecato) emetteva +. Per le form di invio e la maggior parte delle librerie URL, entrambe le rappresentazioni si decodificano correttamente come spazio, ma mischiarle in un URL costruito manualmente rompe i controlli di uguaglianza delle stringhe. Il consiglio moderno: usa le API URL standard (WHATWG URLSearchParams nei browser, url.URL in Node) e lascia che l’implementazione scelga la codifica corretta per il contesto.

La doppia codifica — il bug di produzione piú comune: se un valore passa attraverso due codificatori senza un decodificatore nel mezzo, il % originale del primo passaggio diventa %25, e l’utente vede roba incomprensibile come %2520 invece di %20. La causa principale è quasi sempre uno strato del sistema che presuppone che il suo input sia testo normale quando è già codificato in URL. La soluzione è tracciare un confine chiaro: l’input è testo normale fino al costruttore di URL, codificato in percentuale solo in forma URL, decodificato di nuovo a testo normale nel momento in cui lascia il contesto URL. Correlati: UTF-8, ASCII. Riferimento: RFC 3986 §2.1 — Codifica percentuale.

Esempio pratico

Codifica la query di ricerca café & thé in una stringa di query URL. Passo uno — UTF-8 di ogni carattere: c a f é <spazio> & <spazio> t h é diventa i byte 63 61 66 C3 A9 20 26 20 74 68 C3 A9. Passo due — applica le regole di codifica percentuale: i caratteri non riservati (c a f t h) rimangono; le sequenze UTF-8 multibyte e i caratteri riservati (&) vengono sottoposti a escape. Risultato: caf%C3%A9%20%26%20th%C3%A9. URL completo: https://example.com/search?q=caf%C3%A9%20%26%20th%C3%A9. Sul lato ricevente, il server decodifica invertendo entrambi i passaggi: sostituisce ogni %XX con il suo valore byte per ottenere i byte UTF-8, poi decodifica UTF-8 per recuperare café & thé. Se il server tratta i byte come Latin-1 invece di UTF-8, “café” risulta come “café” — il classico mojibake.

Quando e perché è importante

Ogni URL costruito per concatenazione di stringhe è un potenziale bug di iniezione o routing. Un nome di file fornito dall’utente come ../../../etc/passwd incorporato grezzo in un URL diventa un tentativo di path-traversal; codificato in percentuale come ..%2F..%2F..%2Fetc%2Fpasswd è sicuro come singolo segmento ma potrebbe decodificarsi allo strato sbagliato e reintrodurre il traversal. Le query di ricerca con & o # si troncano silenziosamente se non codificate. I moderni framework HTTP (Express, FastAPI, ASP.NET) gestiscono questo automaticamente quando usi i loro costruttori di parametri di query; i bug si concentrano in URL di reindirizzamento costruiti a mano, ID di correlazione dei log e generatori di URL firmati dove gli sviluppatori concatenano stringhe. L’abitudine difensiva: non usare mai + per la concatenazione di stringhe quando si costruisce un URL — passa sempre per URLSearchParams o l’equivalente del tuo framework. Riferimento: WHATWG URL Standard — Byte codificati in percentuale.