Build notes · WhatsApp Media Decryption & CAS Streaming Engine

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

Native HKDF-SHA256 Decryption, Content-Addressable Storage, and RFC 7233 Byte-Range Streaming

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

Status: Resolved. This postmortem is a historical log. The issue discussed below has been fully fixed.

The Klaros desktop app reads personal WhatsApp numbers through WhatsApp Web. Until this change, every photo, voice note and PDF in a live chat was pulled out of the browser page as a base64 string, one at a time, and kept in memory. Here is how we replaced that with direct HKDF decryption from WhatsApp’s media servers, a content-addressed disk cache, and HTTP byte-range streaming.

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

1. Native HKDF Cryptography: Eliminating Chrome Tab Freezes & Memory Bloat

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) & Reserved Image Space: Stopping Layout Jitter

Decrypted media is stored content-addressed: the file is named by the SHA-256 of its bytes (blobs/<sha256>.bin), so the same photo forwarded into ten chats is stored once. Each message gets a small record (keys/<sha256 of session and message id>.json) pointing at its blob and holding its MIME type, file name and dimensions. Both are written to a .tmp file and renamed into place, so a reader never sees half a file, and Windows refusing to replace a file that is being streamed is harmless because the content is identical.

The cache lives in the per-user data folder, capped at 5 GB. Reads refresh a blob’s timestamp and the least recently used blobs are evicted first, in a throttled background pass rather than on the request.

When WhatsApp’s message data includes an image’s width and height, the inbox sets the container’s aspect-ratio before the image loads, so the thread does not jump as photos arrive. When it does not, the container falls back to a default ratio.

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

3. RFC 7233 HTTP 206 Streaming: Eliminating Voice Note Freezes & 4-Second Audio Lag

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. When the Fast Path Fails: MAC Checks, Fallbacks and a Cache That Cannot Write

The direct path refuses rather than guesses. A file whose 10-byte HMAC does not verify is rejected outright: decrypting it anyway would put a corrupted or tampered file into a cache that serves it for days. The download is only attempted over HTTPS to whatsapp.net hosts, is capped in size while it streams, and follows no redirects.

Every failure on that path, a MAC mismatch, a timeout, an expired URL, falls back to WhatsApp Web’s own downloadMedia(), which is slower but authoritative. And if the disk cache cannot be written, the file is served from memory instead of failing the request: a cache is an optimisation, never a reason not to show the photo.

Cached media is keyed by session as well as message, because one desktop install can hold several WhatsApp profiles, and it is served with Cache-Control: private. It is private chat content.

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