@open-wa/decrypt 5.0.0 → 5.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-wa/decrypt",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "Lightweight WhatsApp media decryption — zero external dependencies",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -14,17 +14,18 @@
     }
   },
   "files": [
+    "src",
     "dist"
   ],
   "dependencies": {},
   "devDependencies": {
-    "@open-wa/schema": "5.0.0",
+    "@open-wa/schema": "5.1.0",
     "@types/node": "^26.6.3",
     "typescript": "^7.0.2",
     "vitest": "5.0.2"
   },
   "peerDependencies": {
-    "@open-wa/schema": "5.0.0"
+    "@open-wa/schema": "5.1.0"
   },
   "peerDependenciesMeta": {
     "@open-wa/schema": {

package/src/__tests__/decrypt.test.ts

@@ -0,0 +1,142 @@
+import { describe, it, expect } from 'vitest';
+import { createCipheriv, randomBytes, hkdfSync } from 'node:crypto';
+
+import {
+  decryptMedia,
+  bleachMessage,
+  mediaTypes,
+  MissingCriticalDataError,
+} from '../index';
+import type { DecryptableMessage } from '../types';
+import { decryptBuffer } from '../crypto';
+
+/**
+ * Build a synthetic encrypted payload matching WhatsApp's scheme:
+ * HKDF → AES-256-CBC → ciphertext that decryptBuffer can reverse.
+ */
+function encryptTestPayload(
+  plaintext: Buffer,
+  mediaKeyBase64: string,
+  type: string,
+): Buffer {
+  const mediaKeyBytes = Buffer.from(mediaKeyBase64, 'base64');
+  const info = `WhatsApp ${mediaTypes[type.toUpperCase()]} Keys`;
+
+  const expanded = Buffer.from(
+    hkdfSync('sha256', mediaKeyBytes, Buffer.alloc(32), info, 112),
+  );
+  const iv = expanded.subarray(0, 16);
+  const cipherKey = expanded.subarray(16, 48);
+
+  const cipher = createCipheriv('aes-256-cbc', cipherKey, iv);
+  cipher.setAutoPadding(false);
+
+  // Manually apply PKCS#7 padding
+  const padding = 16 - (plaintext.length % 16);
+  const padded = Buffer.concat([
+    plaintext,
+    Buffer.alloc(padding, padding),
+  ]);
+
+  return Buffer.concat([cipher.update(padded), cipher.final()]);
+}
+
+describe('decryptBuffer', () => {
+  it('decrypts a synthetic payload correctly', () => {
+    const mediaKey = randomBytes(32).toString('base64');
+    const plaintext = Buffer.from('hello open-wa decrypt');
+
+    const encrypted = encryptTestPayload(plaintext, mediaKey, 'IMAGE');
+
+    const result = decryptBuffer(
+      encrypted,
+      mediaKey,
+      'IMAGE',
+      plaintext.length,
+      'image/jpeg',
+    );
+
+    expect(result.toString()).toBe('hello open-wa decrypt');
+  });
+
+  it('handles different media types', () => {
+    for (const type of ['VIDEO', 'AUDIO', 'DOCUMENT', 'STICKER']) {
+      const mediaKey = randomBytes(32).toString('base64');
+      const plaintext = Buffer.from(`test-${type}`);
+      const encrypted = encryptTestPayload(plaintext, mediaKey, type);
+
+      const result = decryptBuffer(
+        encrypted,
+        mediaKey,
+        type,
+        plaintext.length,
+        'application/octet-stream',
+      );
+
+      expect(result.toString()).toBe(`test-${type}`);
+    }
+  });
+});
+
+describe('bleachMessage', () => {
+  it('keeps only decryption-relevant fields', () => {
+    const msg = {
+      type: 'image',
+      mediaKey: 'abc',
+      mimetype: 'image/jpeg',
+      size: 1000,
+      filehash: 'xyz',
+      deprecatedMms3Url: 'https://example.com',
+      // These should be stripped:
+      sender: 'user@c.us',
+      body: 'some text',
+      chat: { id: 'chat@g.us' },
+    };
+
+    const result = bleachMessage(msg);
+
+    expect(result).toHaveProperty('type');
+    expect(result).toHaveProperty('mediaKey');
+    expect(result).toHaveProperty('mimetype');
+    expect(result).toHaveProperty('size');
+    expect(result).toHaveProperty('filehash');
+    expect(result).toHaveProperty('deprecatedMms3Url');
+    expect(result).not.toHaveProperty('sender');
+    expect(result).not.toHaveProperty('body');
+    expect(result).not.toHaveProperty('chat');
+  });
+});
+
+describe('decryptMedia validation', () => {
+  it('throws MissingCriticalDataError when mediaKey is missing', async () => {
+    const bad = {
+      filehash: 'x',
+      mimetype: 'image/jpeg',
+      type: 'image',
+      size: 100,
+      deprecatedMms3Url: 'https://example.com',
+    } as unknown as DecryptableMessage;
+
+    await expect(decryptMedia(bad)).rejects.toThrow(MissingCriticalDataError);
+  });
+
+  it('throws MissingCriticalDataError when multiple fields are missing', async () => {
+    const bad = {
+      type: 'image',
+      deprecatedMms3Url: 'https://example.com',
+    } as unknown as DecryptableMessage;
+
+    await expect(decryptMedia(bad)).rejects.toThrow(MissingCriticalDataError);
+  });
+});
+
+describe('mediaTypes', () => {
+  it('maps all expected types', () => {
+    expect(mediaTypes['IMAGE']).toBe('Image');
+    expect(mediaTypes['VIDEO']).toBe('Video');
+    expect(mediaTypes['AUDIO']).toBe('Audio');
+    expect(mediaTypes['PTT']).toBe('Audio');
+    expect(mediaTypes['DOCUMENT']).toBe('Document');
+    expect(mediaTypes['STICKER']).toBe('Image');
+  });
+});

package/src/bleach.ts

@@ -0,0 +1,32 @@
+/**
+ * Strip a message down to the minimum fields needed for decryption.
+ *
+ * Useful for minimizing sensitive data in transit — removes sender info,
+ * chat context, etc.
+ */
+
+const BLEACH_KEEP = new Set([
+  'type',
+  'clientUrl',
+  'mimetype',
+  'mediaKey',
+  'size',
+  'filehash',
+  'uploadhash',
+  'deprecatedMms3Url',
+]);
+
+/**
+ * Return a copy of the message containing only the fields required for decryption.
+ */
+export function bleachMessage<T extends Record<string, unknown>>(
+  message: T,
+): Partial<T> {
+  const result: Record<string, unknown> = {};
+  for (const key of Object.keys(message)) {
+    if (BLEACH_KEEP.has(key)) {
+      result[key] = message[key];
+    }
+  }
+  return result as Partial<T>;
+}

package/src/constants.ts

@@ -0,0 +1,25 @@
+/** Mapping from message type to WhatsApp's internal media-type key name. */
+export const mediaTypes: Record<string, string> = {
+  IMAGE: 'Image',
+  VIDEO: 'Video',
+  AUDIO: 'Audio',
+  PTT: 'Audio',
+  DOCUMENT: 'Document',
+  STICKER: 'Image',
+} as const;
+
+/** Message types where a missing `size` field is tolerable. */
+export const NON_SIZE_TYPES = ['sticker'] as const;
+
+/** The default user-agent used for fetching encrypted media blobs. */
+export const DEFAULT_USER_AGENT =
+  'WhatsApp/2.16.352 Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/81.0.4044.92 Safari/537.36';
+
+/** Thrown when a message is missing fields required for decryption. */
+export class MissingCriticalDataError extends Error {
+  override readonly name = 'MissingCriticalDataError';
+
+  constructor(message: string) {
+    super(message);
+  }
+}

package/src/crypto.ts

@@ -0,0 +1,71 @@
+/**
+ * Core crypto routines for WhatsApp media decryption.
+ *
+ * Uses only `node:crypto` builtins — no external HKDF library needed.
+ * `crypto.hkdfSync` landed in Node 15 and is available in Bun.
+ */
+import { createDecipheriv, hkdfSync } from 'node:crypto';
+
+import { mediaTypes } from './constants';
+
+/**
+ * Derive the AES-256-CBC key and IV from the media key using HKDF-SHA256,
+ * then decrypt the ciphertext.
+ */
+export function decryptBuffer(
+  encryptedData: Uint8Array,
+  mediaKeyBase64: string,
+  mediaType: string,
+  expectedSize?: number,
+  mimetype?: string,
+): Buffer {
+  const mediaKeyBytes = Buffer.from(mediaKeyBase64, 'base64');
+
+  // Resolve the info string: "WhatsApp <Type> Keys"
+  const typeKey =
+    mediaTypes[mediaType.toUpperCase()] ??
+    mediaTypes[
+      Object.keys(mediaTypes).find((t) =>
+        mimetype?.includes(t.toLowerCase()),
+      ) ?? ''
+    ];
+
+  const info = `WhatsApp ${typeKey} Keys`;
+
+  // HKDF expand to 112 bytes (iv=16 + cipherKey=32 + macKey=32 + refKey=32)
+  const expanded = Buffer.from(
+    hkdfSync('sha256', mediaKeyBytes, Buffer.alloc(32), info, 112),
+  );
+
+  const iv = expanded.subarray(0, 16);
+  const cipherKey = expanded.subarray(16, 48);
+
+  const decipher = createDecipheriv('aes-256-cbc', cipherKey, iv);
+  // WhatsApp handles padding manually — disable OpenSSL auto-padding
+  decipher.setAutoPadding(false);
+  const decrypted = Buffer.concat([
+    decipher.update(encryptedData),
+    decipher.final(),
+  ]);
+
+  return expectedSize ? fixPadding(decrypted, expectedSize) : decrypted;
+}
+
+/**
+ * Correct PKCS#7-style padding that WhatsApp applies inconsistently.
+ */
+function fixPadding(data: Buffer, expectedSize: number): Buffer {
+  const padding = (16 - (expectedSize % 16)) & 0xf;
+  if (padding > 0) {
+    if (expectedSize + padding === data.length) {
+      // Trim trailing padding bytes
+      return data.subarray(0, data.length - padding);
+    }
+    if (data.length + padding === expectedSize) {
+      // Append missing padding
+      const pad = Buffer.alloc(padding, padding);
+      return Buffer.concat([data, pad]);
+    }
+  }
+  return data;
+}

package/src/decrypt.ts

@@ -0,0 +1,73 @@
+/**
+ * Main decryptMedia entry point.
+ *
+ * Downloads the encrypted blob → decrypts with AES-256-CBC via HKDF-derived keys.
+ */
+import { MissingCriticalDataError, NON_SIZE_TYPES } from './constants';
+import { decryptBuffer } from './crypto';
+import { downloadEncryptedMedia } from './download';
+import type { DecryptableMessage, DecryptOptions } from './types';
+
+/**
+ * Download and decrypt a WhatsApp media message.
+ *
+ * @param message — A message object with at least the required decryption fields.
+ * @param optionsOrUa — Either a {@link DecryptOptions} object or a legacy user-agent string.
+ * @returns The decrypted media as a Buffer.
+ *
+ * @example
+ * ```ts
+ * import { decryptMedia } from '@open-wa/decrypt';
+ *
+ * const buffer = await decryptMedia(message);
+ * ```
+ */
+export async function decryptMedia(
+  message: DecryptableMessage,
+  optionsOrUa?: DecryptOptions | string,
+): Promise<Buffer> {
+  // Normalise options — accept legacy string signature for backward compat
+  const opts: DecryptOptions =
+    typeof optionsOrUa === 'string'
+      ? { useragent: optionsOrUa }
+      : optionsOrUa ?? {};
+
+  validateMessage(message);
+
+  const url = (message.deprecatedMms3Url ?? message.clientUrl)!.trim();
+  const encrypted = await downloadEncryptedMedia(url, opts);
+
+  return decryptBuffer(
+    encrypted,
+    message.mediaKey,
+    message.type,
+    message.size,
+    message.mimetype,
+  );
+}
+
+function validateMessage(message: DecryptableMessage): void {
+  const missing: string[] = [];
+
+  if (!message.mediaKey) missing.push('mediaKey');
+  if (!message.filehash) missing.push('filehash');
+  if (!message.mimetype) missing.push('mimetype');
+  if (!message.type) missing.push('type');
+  if (!message.size) missing.push('size');
+
+  if (missing.length === 0) return;
+
+  // Size-only omission is a warning for non-sticker types, not an error
+  if (missing.length === 1 && missing[0] === 'size') {
+    if (!NON_SIZE_TYPES.includes(message.type as (typeof NON_SIZE_TYPES)[number])) {
+      console.warn(
+        '@open-wa/decrypt: size property is missing. File will fail an integrity check.',
+      );
+    }
+    return;
+  }
+
+  throw new MissingCriticalDataError(
+    `Message is missing critical data: ${missing.join(', ')}`,
+  );
+}

package/src/download.ts

@@ -0,0 +1,55 @@
+/**
+ * Download encrypted media from WhatsApp CDN using native fetch.
+ *
+ * Replaces the legacy axios-based downloader.
+ */
+import {
+  DEFAULT_USER_AGENT,
+} from './constants';
+
+function buildUserAgent(override?: string): string {
+  let ua = override ?? DEFAULT_USER_AGENT;
+  if (!ua.includes('WhatsApp')) ua = `WhatsApp/2.16.352 ${ua}`;
+  return ua;
+}
+
+/**
+ * Download an encrypted media blob from the given URL.
+ * Uses the global `fetch` API (Bun native / Node 18+).
+ */
+export async function downloadEncryptedMedia(
+  url: string,
+  options?: { useragent?: string; maxRetries?: number; retryDelay?: number },
+): Promise<Uint8Array> {
+  const { useragent, maxRetries = 3, retryDelay = 2_000 } = options ?? {};
+
+  const headers: Record<string, string> = {
+    'User-Agent': buildUserAgent(useragent),
+    DNT: '1',
+    'Upgrade-Insecure-Requests': '1',
+    Origin: 'https://web.whatsapp.com/',
+    Referer: 'https://web.whatsapp.com/',
+  };
+
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    const res = await fetch(url, { headers });
+
+    if (res.ok) {
+      return new Uint8Array(await res.arrayBuffer());
+    }
+
+    if (res.status === 404) {
+      throw new Error(
+        'This media does not exist or is no longer available on the server. ' +
+          'See: https://openwa.dev/pages/How%20to/decrypt-media.html#40439d',
+      );
+    }
+
+    // Retry on transient errors
+    if (attempt < maxRetries - 1) {
+      await new Promise((r) => setTimeout(r, retryDelay));
+    }
+  }
+
+  throw new Error(`Failed to download media after ${maxRetries} attempts`);
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @open-wa/decrypt — WhatsApp media decryption with zero external dependencies.
+ *
+ * All crypto uses node:crypto builtins (hkdfSync, createDecipheriv).
+ * HTTP fetching uses the global fetch API (Bun/Node 18+).
+ */
+
+export { decryptMedia } from './decrypt';
+export { bleachMessage } from './bleach';
+export type {
+  DecryptableMessage,
+  RequiredDecryptionMessage,
+  DecryptOptions,
+} from './types';
+export { mediaTypes, MissingCriticalDataError } from './constants';

package/src/types.ts

@@ -0,0 +1,49 @@
+/**
+ * Type definitions for decryptable WhatsApp media messages.
+ *
+ * Self-contained — no external type deps like type-fest or wa-automate-types-only.
+ */
+
+/**
+ * Utility type: at least one of the specified keys must be present.
+ * Replaces the `type-fest` RequireAtLeastOne import.
+ */
+type RequireAtLeastOne<T, Keys extends keyof T = keyof T> = Pick<
+  T,
+  Exclude<keyof T, Keys>
+> &
+  {
+    [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>>;
+  }[Keys];
+
+/** The absolute minimum fields needed for decryption. */
+export interface RequiredDecryptionMessage {
+  mediaKey: string;
+  filehash: string;
+  mimetype: string;
+  type: string;
+  size: number;
+}
+
+/**
+ * A message with enough data to download + decrypt the media attachment.
+ * At least one of `clientUrl` or `deprecatedMms3Url` must be present.
+ */
+export type DecryptableMessage = RequireAtLeastOne<
+  {
+    clientUrl?: string;
+    deprecatedMms3Url?: string;
+  },
+  'clientUrl' | 'deprecatedMms3Url'
+> &
+  RequiredDecryptionMessage;
+
+/** Options for the decryptMedia function. */
+export interface DecryptOptions {
+  /** Custom User-Agent header for the download request. */
+  useragent?: string;
+  /** Maximum number of retry attempts for the download (default: 3). */
+  maxRetries?: number;
+  /** Delay in ms between retries (default: 2000). */
+  retryDelay?: number;
+}