Base64 Encode and Decode Without Leaking Tokens

Base64 maps arbitrary binary data onto 64 printable ASCII characters, so that bytes can travel through channels that only reliably carry text: email bodies, JSON string fields, HTTP headers, data URIs, and source files.

The mechanism is mechanical and worth knowing. The encoder takes the input three bytes at a time — 24 bits — and re-splits those 24 bits into four 6-bit groups. Each 6-bit group indexes the alphabet A–Z, a–z, 0–9, +, /. When the input length is not a multiple of three, the final group is padded with = so the output length stays a multiple of four.

Three consequences follow directly from that arithmetic:

1. Output is always about 33% larger than input — four characters for every three bytes, plus padding. A 3 MB file becomes roughly 4 MB of Base64.
2. Length is always a multiple of four once padding is applied. A string whose length mod 4 is 1 cannot be valid Base64.
3. It is completely reversible by anyone. There is no key.

That third point is the one that matters most, and it deserves stating without hedging: Base64 is an encoding, not encryption. A Base64 string in a log file, a config file or a screenshot is plaintext to anyone who pastes it into a decoder. Credentials stored "encoded for safety" are stored in the clear.

JavaScript's built-in btoa() fails on any string containing a character above U+00FF:

btoa('café');
// InvalidCharacterError: String contains an invalid character

The reason is historical. btoa was specified when JavaScript strings were treated as sequences of single bytes; it interprets each code unit as one byte and throws when a code unit exceeds 255. Emoji, accented Latin, Devanagari, Chinese and Cyrillic all break it.

The correct approach encodes text to UTF-8 bytes first, then Base64-encodes those bytes:

```js function encodeText(text) { const bytes = new TextEncoder().encode(text); // UTF-8 bytes let binary = ''; for (let i = 0; i < bytes.length; i += 0x8000) { binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000)); } return btoa(binary); }

function decodeText(encoded) { const bytes = Uint8Array.from(atob(encoded), (c) => c.charCodeAt(0)); return new TextDecoder('utf-8', { fatal: true }).decode(bytes); } ```

Two details in that code are not decoration.

The 0x8000 chunking exists because String.fromCharCode(...bytes) spreads every byte as a separate function argument. On a large input this exceeds the JavaScript engine's argument limit and throws RangeError: Maximum call stack size exceeded — typically somewhere above 100 KB, which means the bug survives every small test and appears the first time a real file is used.

The `{ fatal: true }` flag on TextDecoder makes invalid UTF-8 throw instead of silently substituting U+FFFD replacement characters. Without it, corrupted input decodes to plausible-looking text containing �, and the corruption is discovered much later.

Standard Base64 uses + and /, both of which have meaning in a URL, and =, which has meaning in a query string. Placing standard Base64 in a URL therefore requires percent-encoding and produces unreadable results.

Base64URL, defined in RFC 4648 §5, makes three substitutions:

• + becomes -
• / becomes _
• trailing = padding is removed

This is the encoding used by JSON Web Tokens, by OAuth state and PKCE parameters, and by most modern URL-safe identifier schemes. Converting between the two is mechanical:

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

const fromBase64Url = (value) => value.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (value.length % 4)) % 4); ```

The padding restoration in the second function is the part people omit, and atob will reject the unpadded string. The expression (4 - (length % 4)) % 4 yields 0, 3, 2 or 1 and handles the case where no padding is needed without adding four equals signs.

A JWT is three Base64URL segments joined by dots: header, payload, signature. The payload is readable by anyone holding the token — decoding it requires no key, because the signature authenticates the contents rather than concealing them. Never place anything confidential in a JWT payload.

A data URI embeds a Base64-encoded resource directly in markup or CSS:

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..." alt="">

This removes a network round trip, which is genuinely valuable for very small assets in the critical rendering path — an icon in above-the-fold CSS, for example.

The costs accumulate quickly and are frequently underestimated:

• 33% size penalty, applied to every byte, permanently.
• No independent caching. An inlined asset is re-downloaded with its containing document on every change to that document. A separate file is cached once and reused.
• Render blocking when inlined in CSS. A large data URI inside a stylesheet delays first paint, because the stylesheet must be fully parsed before rendering begins.
• No parallel download. The browser cannot fetch an inlined asset concurrently with anything else.

A defensible rule: inline below roughly 4 KB, and only for assets needed immediately. Above that, a separate cached request almost always wins. Inlining a 200 KB hero image as a data URI is a reliable way to make a page measurably slower while appearing to reduce request count.

SVG is the exception worth knowing: because SVG is text, it can be embedded with URL encoding instead of Base64, avoiding the 33% penalty entirely and often producing a smaller result than the original file.

The practical risk in Base64 work is not the algorithm. It is where the plaintext goes.

Developers encode and decode tokens constantly — inspecting a JWT payload, preparing an HTTP Basic credential, checking an API key embedded in a config. Doing that in a web tool that posts the value to a server means the credential has been transmitted to, and possibly logged by, a third party. Rotating that credential afterwards is the only safe remedy, and it is rarely done.

Three habits materially reduce exposure:

1. Decode locally. A Base64 codec is pure arithmetic over bytes and needs no server. The OpenTools Base64 encoder runs in the page, so the value is not transmitted anywhere.
2. Treat any credential pasted into any web page as compromised. Browser extensions, autofill managers and crash reporters all have access to page content. If the token protects something important, rotate it.
3. Never commit Base64 credentials. Encoding does not obscure anything from a secret scanner, from a code reviewer, or from anyone with repository read access — and git history preserves them after deletion.

If you need the value to actually be protected rather than merely reformatted, the tool you want is encryption, not encoding — AES-GCM through the Web Crypto API, with a key you manage separately.