Base64 Encoder & Decoder

How Base64 works, and why output is 33% larger

Base64 variants

Several alphabets exist. Mixing them up is the most common decode failure.

A JWT segment pasted into a strict standard-Base64 decoder typically fails on the missing padding or on a - / _ character. That is a variant mismatch, not corruption.

The UTF-8 trap in JavaScript

btoa() and atob() predate widespread Unicode and operate on Latin-1. Passing them non-ASCII text throws or corrupts silently.

btoa('café');
// InvalidCharacterError: String contains characters
// outside of the Latin1 range

btoa('日本語');   // same failure

// Encode: text -> UTF-8 bytes -> Base64
function encode(text) {
  const bytes = new TextEncoder().encode(text);
  return btoa(String.fromCharCode(...bytes));
}

// Decode: Base64 -> UTF-8 bytes -> text
function decode(b64) {
  const binary = atob(b64);
  const bytes = Uint8Array.from(binary, c => c.charCodeAt(0));
  return new TextDecoder().decode(bytes);
}

encode('café');   // 'Y2Fmw6k='  — correct

const toUrl = b64 =>
  b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');

const fromUrl = s => {
  const b64 = s.replace(/-/g, '+').replace(/_/g, '/');
  return b64.padEnd(Math.ceil(b64.length / 4) * 4, '=');
};

# Encode / decode
echo -n 'hello' | base64
echo 'aGVsbG8=' | base64 -d

# -n matters: without it the trailing newline is encoded too,
# which is why a shell-produced value often fails to match
# one produced by an application.

# Files
base64 -i image.png -o image.txt

When Base64 is and is not appropriate

• Small inline images (data URIs) —Reasonable for icons under about 2 KB, where saving a round trip beats the 33% size penalty. Above that, a separate cacheable file wins — a data URI cannot be cached independently of the document that contains it.
• Binary in JSON —The standard approach, because JSON has no binary type. Accept the 33% overhead or use a binary protocol.
• HTTP Basic auth —Required by the spec, and worth restating: Basic auth Base64 is not protection. The credentials are recoverable instantly. It is only safe over TLS.
• Large file uploads —A poor fit. Use multipart/form-data or a direct binary body — Base64 wastes a third of the bandwidth and forces the whole payload into memory on both ends.
• Hiding data —Never. Base64 is trivially reversible and recognisable on sight. Anything encoded "for security" is not secured.