Build notes · WhatsApp Media Decryption & CAS Streaming Engine

The WhatsApp media pipeline that ran out of memory: Native HKDF Decryption, CAS Storage, and RFC 7233 Streaming

23 September 2026 · media performance & streaming · Founder, Klaros

When thousands of voice notes, high-resolution product photos, and PDF invoices flow through a team inbox, standard WhatsApp CRM architectures collapse. Here is how we replaced Chrome DevTools Protocol WebSocket Base64 bloat with native HKDF key derivation, Content-Addressable Storage, and RFC 7233 byte-range streaming.

Figure 1: Klaros Zero-Latency Media Decryption & CAS Streaming Architecture

1. The Cryptography of WhatsApp Media: Under the Hood

When a customer sends a voice note or image on WhatsApp, the media binary is not stored on signaling servers. Instead, it is uploaded to WhatsApp CDN nodes at mmg.whatsapp.net. The chat message payload contains only metadata: the encrypted URL, file SHA256 hashes, and a 32-byte mediaKey.

To decipher the payload natively without running headless browser scrapers, the 32-byte mediaKey must be expanded using HKDF-SHA256 (RFC 5869) using a 32-byte zero salt and type-specific UTF-8 info string labels:

• Image: "WhatsApp Image Keys"
• Video: "WhatsApp Video Keys"
• Audio / Voice Note (PTT): "WhatsApp Audio Keys"
• Document: "WhatsApp Document Keys"

The HKDF derivation produces 112 bytes of pseudo-random key material, sliced into four functional keys:

// src/local-modules/wa-media-decryptor.mjs
import crypto from 'node:crypto';

export function deriveMediaKeys(mediaKey, type = 'image') {
  const infoStr = INFO_MAP[type] || INFO_MAP.image;
  const salt = Buffer.alloc(32, 0);
  const hkdfOutput = crypto.hkdfSync('sha256', mediaKey, salt, Buffer.from(infoStr, 'utf8'), 112);

  return {
    iv: Buffer.from(hkdfOutput.slice(0, 16)),
    cipherKey: Buffer.from(hkdfOutput.slice(16, 48)),
    macKey: Buffer.from(hkdfOutput.slice(48, 80)),
    refKey: Buffer.from(hkdfOutput.slice(80, 112)),
  };
}

export function decryptMediaBuffer(encryptedBlob, mediaKey, type = 'image') {
  const ciphertext = encryptedBlob.subarray(0, encryptedBlob.length - 10);
  const macTrailer = encryptedBlob.subarray(encryptedBlob.length - 10);
  const { iv, cipherKey, macKey } = deriveMediaKeys(mediaKey, type);

  // Validate 10-byte truncated HMAC-SHA256 integrity
  const hmac = crypto.createHmac('sha256', macKey);
  hmac.update(iv);
  hmac.update(ciphertext);
  const computedMac = hmac.digest().subarray(0, 10);

  if (!crypto.timingSafeEqual(computedMac, macTrailer)) {
    throw new Error('HMAC verification failed: corrupted payload');
  }

  const decipher = crypto.createDecipheriv('aes-256-cbc', cipherKey, iv);
  return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
}

2. Content-Addressable Storage (CAS) & Zero-CLS Math

Decrypted media payloads are ingested into Content-Addressable Storage (CAS), indexed by content SHA256 hashes or message keys. Files are written using an atomic write pattern (writing to a .tmp file before executing an atomic fs.renameSync()) to prevent filesystem lock crashes on Windows environments.

Along with binary files, CAS generates persistent .meta.json sidecars storing parsed dimensions, aspect ratios, micro-blur Thumbhashes, and EXIF Tag 0x0112 orientation values. Photos taken vertically on smartphones are automatically orientation-corrected so portrait photos never render sideways.

Pre-calculated aspect ratios are injected directly into inline styles (aspect-ratio: 1.778), reserving exact screen dimensions before binary bytes finish loading over the network. This yields a 0.00 Cumulative Layout Shift (CLS) score across all team inbox viewports.

Figure 2: Universal Media Engine — Mode A (Lightbox Viewer Carousel) & Mode B (Composer Card Picker)

3. RFC 7233 Byte-Range HTTP 206 Partial Content Streaming

HTML5 <audio> and <video> players require HTTP 206 Partial Content range responses to seek, scrub, and stream audio without downloading full 50MB files into memory. Klaros implements full RFC 7233 Range parsing supporting bytes=100-499, open-ended bytes=500-, and trailing suffix range requests (bytes=-500 for MP4/MOOV atom seeking).

// src/routes/whatsapp-chats.mjs
const range = parseRangeHeader(req.headers.range, fileSize);

if (range) {
  res.status(206);
  res.setHeader('Content-Range', `bytes ${range.start}-${range.end}/${fileSize}`);
  res.setHeader('Content-Length', range.chunkSize);

  const fileStream = fs.createReadStream(filePath, { start: range.start, end: range.end });
  req.on('close', () => fileStream.destroy()); // Destroy stream if user cancels request mid-scroll
  fileStream.pipe(res);
}

4. Safari Private Browsing & Edge Web Crypto Fallback Engine

When running in web browsers or Edge Workers, local storage interfaces exhibit platform-specific constraints. In Safari Private Browsing mode, opening IndexedDB throws an uncatchable DOMException: UnknownError or QuotaExceededError. Klaros wraps IndexedDB storage calls with a try-catch block that automatically falls back to an in-memory MemoryBlobMap LRU cache in JavaScript heap space, guaranteeing zero client crashes or white screens.

Furthermore, in Cloudflare Workers V8 environments where Node native C++ modules are unavailable, key derivation uses the standard Web Crypto API (crypto.subtle.importKey and crypto.subtle.deriveBits), providing universal portability between Node.js desktop processes and edge worker isolates.

5. Architectural Comparison: Klaros vs. Legacy WhatsApp Platforms

6. Empirical Performance Scorecard: Scraper vs. Edge CAS Engine

Written 23 September 2026. Klaros — Built to Remember Your Story. Related: our philosophy, performance notes, all build notes.