Variantes de base64: alfabetos padrão e URL-safe, regras de padding e rigor dos decodificadores

O que é

Variante	Caracteres do alfabeto 62/63	Padding	Quebra de linha
Base64 padrão (RFC 4648 §4)	+ /	obrigatório, a menos que a especificação que a referencia diga o contrário — "MUST include appropriate pad characters"	proibida, a menos que a especificação que a referencia a exija
URL-safe / base64url (RFC 4648 §5)	- _	mesma regra do padrão, salvo exceção; a RFC observa que o padding pode ser omitido quando o comprimento é conhecido	proibida, a menos que a especificação que a referencia a exija
JWT / JWS BASE64URL (RFC 7515)	- _	explicitamente omitido — "with all trailing '=' characters omitted"	não permitida — "without the inclusion of any line breaks"
MIME (RFC 2045)	+ /	obrigatório	obrigatória — no máximo 76 caracteres por linha; os decodificadores devem ignorar caracteres fora do alfabeto

Por que importa

A RFC 4648 define dois alfabetos que diferem em exatamente dois caracteres e afirma que o padding é obrigatório "unless the specification referring to this document explicitly states otherwise." Os JWTs são justamente uma dessas exceções: a RFC 7515 omite por completo os caracteres = finais e proíbe quebras de linha. Assim, um segmento de JWT com padding = ou quebrado em várias linhas é uma entrada inválida para um decodificador estrito. O MIME exige o oposto: linhas de no máximo 76 caracteres. O comando base64 do GNU quebra a saída nessa largura por padrão, então é preciso passar -w0 para obter uma única linha contínua (-w é uma opção do GNU coreutils; o base64 do macOS não quebra linhas por padrão e usa -b para pedir quebras). Os decodificadores também divergem quanto ao nível de tolerância. O base64.b64decode do Python descarta os caracteres fora do alfabeto antes de verificar o padding, a menos que se passe validate=True. Por isso, uma string base64url entregue a ele perde os - e _ e acaba decodificando para bytes errados ou falhando por causa do padding, sem nunca indicar quais são os caracteres inválidos. Além disso, ele lança Incorrect padding diante de entrada sem padding, que é exatamente o que acontece com base64.urlsafe_b64decode ao receber um segmento de JWT. Já o atob() do navegador lança InvalidCharacterError para -, _ ou qualquer outro caractere fora do alfabeto padrão, mas aceita a falta de padding e ignora espaços em branco ASCII. O encoding/base64 do Go mantém StdEncoding e URLEncoding como codecs separados e não intercambiáveis, com RawStdEncoding/RawURLEncoding como as formas explícitas sem padding.

Como aplicar

• Escolha o alfabeto conforme o contexto: URLs, nomes de arquivo e JWTs exigem -/_; todo o resto usa +// por padrão.
• Remova ou adicione o padding de forma deliberada: JWTs não podem ter padding; a maioria dos outros consumidores o espera, salvo documentação em contrário.
• Use base64 -w0 sempre que a saída gerada por script precisar ser uma única linha.
• Não conte com a tolerância padrão do base64.b64decode; passe validate=True quando entradas malformadas devam ser rejeitadas de imediato.
• Antes de decodificar um valor base64url sem padding em Python, acrescente '=' * (-len(s) % 4); em Go, use RawURLEncoding.

Armadilhas

• Passar uma string com padding e alfabeto +// a um decodificador que espera base64url.
• Supor que todo decodificador descarta caracteres estranhos como o Python faz por padrão — o atob() lança erro.
• Supor que -w0 é portátil: é uma opção do GNU coreutils, e o base64 do macOS usa -b.
• Esquecer que -w0 é necessário para evitar quebras de linha na saída de base64 gerada por script.