export class BinaryTransportCodec {
  private static readonly STANDARD_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
  private static readonly URL_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';

  static encodeToStandard(input: Uint8Array): string {
    const binaryString = Array.from(input, (byte) => String.fromCharCode(byte)).join('');
    return btoa(binaryString);
  }

  static encodeToUrlSafe(input: Uint8Array): string {
    const standard = this.encodeToStandard(input);
    return standard
      .replace(/\+/g, '-')
      .replace(/\//

g, '_') .replace(/=+$/, ''); }

static decodeFromUrlSafe(encoded: string): Uint8Array { let normalized = encoded.replace(/-/g, '+').replace(/_/g, '/'); const paddingLength = (4 - (normalized.length % 4)) % 4; normalized += '='.repeat(paddingLength);

const binaryString = atob(normalized);
return new Uint8Array([...binaryString].map(char => char.charCodeAt(0)));

}

static decodeFromStandard(encoded: string): Uint8Array { const binaryString = atob(encoded); return new Uint8Array([...binaryString].map(char => char.charCodeAt(0))); } }

### Step 4: Chain with Actual Encryption When Required
If the payload contains sensitive data, encrypt it before encoding. Base64 should only wrap the ciphertext, never the plaintext.

```typescript
import { BinaryTransportCodec } from './BinaryTransportCodec';

async function securePayloadTransport(plaintext: string, encryptionKey: CryptoKey): Promise<string> {
  const encoder = new TextEncoder();
  const iv = crypto.getRandomValues(new Uint8Array(12));
  
  const encrypted = await crypto.subtle.encrypt(
    { name: 'AES-GCM', iv },
    encryptionKey,
    encoder.encode(plaintext)
  );

  const ivAndCiphertext = new Uint8Array(iv.length + encrypted.byteLength);
  ivAndCiphertext.set(iv);
  ivAndCiphertext.set(new Uint8Array(encrypted), iv.length);

  return BinaryTransportCodec.encodeToUrlSafe(ivAndCiphertext);
}

Architecture Rationale

• Why wrap native APIs? Direct btoa/atob usage scatters encoding logic across the codebase. A centralized codec enforces consistent padding handling, variant selection, and error boundaries.
• Why encrypt before encoding? Encryption produces raw bytes. Text protocols reject them. Base64 makes the ciphertext transportable without altering its cryptographic properties.
• Why strip padding in URLs? Padding characters (=) are reserved in query strings and can break routing or parsing logic. Base64url eliminates this risk while preserving decodability.

Pitfall Guide

1. Storing Secrets in JWT Payloads

Explanation: JWTs consist of three Base64url-encoded segments. The header and payload are never encrypted by default. Anyone with the token can decode the claims and read the contents. Fix: Never place passwords, API keys, or PII in JWT claims. Use short-lived tokens, reference opaque session IDs, or implement JWE (JSON Web Encryption) if payload confidentiality is mandatory.

2. Using Base64 as a Password Hash

Explanation: Base64 is reversible and deterministic. It provides zero resistance against brute-force or rainbow table attacks. Fix: Use dedicated password hashing functions like Argon2id, bcrypt, or scrypt. These incorporate salting, memory hardness, and computational cost to resist offline cracking.

3. Ignoring Padding in URL Contexts

Explanation: Standard Base64 appends = characters to align output length to multiples of 4. When embedded in URLs or query parameters, these characters can be misinterpreted by routers or parsers. Fix: Always use Base64url for web-facing identifiers. If standard Base64 is unavoidable, URL-encode the padding (%3D) or strip it and reconstruct during decoding.

4. Assuming Base64 Compresses Data

Explanation: Base64 expands payloads by ~33%. Applying it to large files or high-frequency API responses increases bandwidth consumption and latency. Fix: Reserve Base64 for small binaries (icons, certificates, short tokens). For large payloads, use binary protocols, chunked transfers, or compression algorithms like Brotli or Zstd before encoding.

5. Mixing Standard and Base64url Variants

Explanation: Standard Base64 uses + and /. Base64url uses - and _. Decoding a Base64url string with a standard decoder fails or produces corrupted output. Fix: Enforce variant consistency at the API contract level. Document which encoding is used for each endpoint. Implement strict validation that rejects mixed alphabets.

6. Encoding Encrypted Data Without Authentication

Explanation: While Base64 itself doesn't cause this, wrapping unauthenticated ciphertext in Base64 creates a false sense of security. Attackers can modify the encoded string, decode it, tamper with the ciphertext, and re-encode it. Fix: Always use authenticated encryption (AES-GCM, ChaCha20-Poly1305). Verify the authentication tag before decoding or processing the payload.

7. Relying on Base64 for API Authentication Without TLS

Explanation: HTTP Basic Auth encodes username:password in Base64. The encoding provides zero protection. Without HTTPS, credentials are transmitted in plaintext-equivalent form. Fix: Never use Basic Auth over unencrypted connections. Prefer token-based authentication (OAuth 2.0, API keys) with strict scope limitations and TLS enforcement.

Production Bundle

Action Checklist

• Audit all JWT payloads for sensitive data; migrate secrets to short-lived references or JWE
• Replace any Base64 password hashing with Argon2id or bcrypt
• Enforce Base64url for all URL-embedded identifiers and query parameters
• Validate that large binary transfers use binary protocols or compression before encoding
• Standardize on a single Base64 variant per API contract; reject mixed alphabets
• Verify all encrypted payloads use authenticated encryption before Base64 wrapping
• Confirm HTTP Basic Auth endpoints enforce TLS 1.2+ and consider deprecation in favor of token auth
• Implement centralized encoding/decoding utilities to prevent scattered btoa/atob usage

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Small binary in JSON API	Base64url	Text-safe, widely supported, minimal parsing overhead	+33% payload size
Large file transfer (10MB+)	Binary protocol (gRPC/WebSocket)	Avoids 33% inflation, reduces CPU encoding/decoding	Lower bandwidth & latency
JWT with user claims	Base64url + short expiry	Claims are readable by design; limit exposure window	Negligible
JWT with sensitive data	JWE (AES-GCM) + Base64url	Encrypts payload before encoding; maintains JWT structure	Slight CPU overhead for encryption
Password storage	Argon2id / bcrypt	Resists offline cracking; non-reversible	Higher storage per hash
URL-safe identifier	Base64url (no padding)	Prevents routing/parser conflicts	None

Configuration Template

// encoding.config.ts
export const EncodingConfig = {
  variants: {
    standard: {
      alphabet: 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/',
      padding: true,
      useCases: ['email-attachments', 'internal-json-payloads', 'certificate-pem']
    },
    urlSafe: {
      alphabet: 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_',
      padding: false,
      useCases: ['jwt-tokens', 'url-identifiers', 'query-parameters']
    }
  },
  limits: {
    maxPayloadSizeBytes: 524288, // 512KB threshold for Base64 usage
    enforceAuthenticatedEncryption: true,
    rejectMixedVariants: true
  }
};

// Usage guard
export function validateEncodingContext(payloadSize: number, variant: 'standard' | 'urlSafe'): void {
  if (payloadSize > EncodingConfig.limits.maxPayloadSizeBytes) {
    throw new Error('Payload exceeds Base64 threshold. Use binary transport or compression.');
  }
  
  const config = EncodingConfig.variants[variant];
  if (!config) {
    throw new Error(`Unsupported Base64 variant: ${variant}`);
  }
}

Quick Start Guide

1. Install dependencies: Ensure your runtime supports crypto.subtle and TextEncoder (Node.js 18+, modern browsers). No external packages required.
2. Create the codec: Copy the BinaryTransportCodec class into your utilities directory. Export it as a singleton or inject it via dependency injection.
3. Define your variant: Choose standard for internal APIs and email systems. Choose urlSafe for web routes, JWTs, and query strings. Enforce this choice in your API documentation.
4. Apply at boundaries only: Encode immediately before sending to a text-constrained system. Decode immediately after receiving. Keep internal processing in raw binary.
5. Layer encryption first: If the payload contains secrets, encrypt with AES-GCM or ChaCha20-Poly1305, then pass the ciphertext to the codec. Never encode plaintext secrets.