2026-08-27 · 8 min read
- base64
- binary
- encoding
Base64 maps arbitrary bytes to a restricted text alphabet. Problems begin when code treats the original bytes as Unicode text before encoding or treats decoded bytes as text afterward. UTF-8 decoders may replace invalid sequences, normalize data, or reject input, permanently changing a file.
A successful Base64 decode proves only that the transport text was valid enough for that decoder. It does not prove that the resulting bytes match the source or represent a valid file.
Choose the input model before encoding
Text and binary data need different contracts. Text starts as characters, uses a named character encoding such as UTF-8 to become bytes, and can then be Base64-encoded. A file or protocol frame already consists of bytes and should skip character decoding entirely.
- Read browser files as ArrayBuffer or Blob, not as text.
- Use byte arrays, buffers, or streams in server runtimes.
- Specify UTF-8 only for fields whose source is actually text.
- Avoid APIs that round-trip binary through a database text column.
Validate the transport and decoded content
Document standard Base64 versus Base64url, padding policy, whitespace policy, and maximum decoded size. Estimate or check decoded size before allocating a large buffer to reduce denial-of-service risk.
After decoding, verify expected length, file signature, checksum, or parser result. Magic bytes such as a PNG signature can quickly reveal text conversion or truncation, while a cryptographic hash provides a precise round-trip check.
Avoid string-oriented browser traps
Legacy browser functions often expose binary-looking strings whose code units must stay in the 0–255 range. Applying them directly to arbitrary Unicode text fails, and spreading very large arrays into function arguments can exceed runtime limits.
- Use chunked or streaming conversions for large data.
- Do not apply TextDecoder and TextEncoder to arbitrary file bytes.
- Revoke object URLs after previews are no longer needed.
- Keep decoded data local unless an upload is explicitly intended.
Build round-trip fixtures
Test empty input, zero bytes, all byte values, invalid UTF-8 sequences, large payloads, standard and URL-safe alphabets, and accepted padding variants. Compare the final byte sequence with the original rather than comparing only encoded strings.
Use Flashman's Base64 tool for safe fixtures, hash tool for byte integrity, hex/text converter for leading-byte inspection, diff tool for transport changes, and JSON formatter when Base64 is embedded in an API body. Never mistake encoding for encryption when handling sensitive files.