Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

train 13 (#1816)

Yudhi Armyndharisee6b9d576a7a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f2f2cd9ac..c7e74023a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -23,10 +23,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Changed
+- Retire the whatsapp-web.js download-mimetype install patch; inbound media downloads now pass the mimetype themselves.
- CI and the weekly security scan run `npm audit` over the JavaScript SDK, and Dependabot watches its lockfile.
### Fixed
+- Drop whatsapp-web.js inbound media over `MEDIA_DOWNLOAD_MAX_BYTES` in the page when the sender understates its size.
- Probe the configured `PORT` in the Docker image healthcheck instead of a fixed 2785.
- Cap the total bytes one storage import writes at `STORAGE_IMPORT_MAX_TOTAL_BYTES`.
- Close the Baileys session proxy's fetch dispatcher when the session disconnects, logs out or is destroyed.
diff --git a/Dockerfile b/Dockerfile
index da4f2d81f..0f10d20df 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -191,7 +191,7 @@ COPY package*.json ./
# scripts/postinstall.js rides along so a bare local `npm ci` keeps working, but the
# --ignore-scripts install below skips the hook here: the explicit fatal run right
# after is the sole (and stricter) applier for the image.
-COPY scripts/postinstall.js scripts/patch-wwebjs-201832.js scripts/wwebjs-201832.patch scripts/patch-wwebjs-newsletter-preview.js scripts/patch-wwebjs-status.js scripts/patch-wwebjs-ready-sync.js scripts/patch-wwebjs-participant-arity.js scripts/patch-wwebjs-block.js scripts/patch-wwebjs-group-description.js scripts/patch-wwebjs-media-id.js scripts/patch-wwebjs-send-error.js scripts/patch-wwebjs-download-mimetype.js scripts/patch-baileys-appstate.js scripts/patch-baileys-newsletter-create.js scripts/patch-baileys-pairing.js ./scripts/
+COPY scripts/postinstall.js scripts/patch-wwebjs-201832.js scripts/wwebjs-201832.patch scripts/patch-wwebjs-newsletter-preview.js scripts/patch-wwebjs-status.js scripts/patch-wwebjs-ready-sync.js scripts/patch-wwebjs-participant-arity.js scripts/patch-wwebjs-block.js scripts/patch-wwebjs-group-description.js scripts/patch-wwebjs-media-id.js scripts/patch-wwebjs-send-error.js scripts/patch-baileys-appstate.js scripts/patch-baileys-newsletter-create.js scripts/patch-baileys-pairing.js ./scripts/
# Install production dependencies only, then apply the backports. The status patcher runs after
# the two patchers it depends on: its transforms were written against the tree they leave behind.
@@ -219,7 +219,6 @@ RUN npm ci --omit=dev --ignore-scripts \
&& node scripts/patch-wwebjs-group-description.js \
&& node scripts/patch-wwebjs-media-id.js \
&& node scripts/patch-wwebjs-send-error.js \
- && node scripts/patch-wwebjs-download-mimetype.js \
&& node scripts/patch-baileys-appstate.js \
&& node scripts/patch-baileys-newsletter-create.js \
&& node scripts/patch-baileys-pairing.js \
diff --git a/docs/29-engine-capability-matrix.md b/docs/29-engine-capability-matrix.md
index 4720bca15..91aa61e50 100644
--- a/docs/29-engine-capability-matrix.md
+++ b/docs/29-engine-capability-matrix.md
@@ -5,7 +5,7 @@ Three-way comparison of every capability: the **Baileys library** (`@whiskeysock
its adapter layer and REST API — including which "supported" cells only work because OpenWA patches
the installed library. Coverage is total: all 113 `IWhatsAppEngine` methods (29.4), **all 152
Baileys + 81 whatsapp-web.js library methods** (29.5), all 34 + 31 library events (29.5.4), and all
-13 install-time patches (29.3). If it exists upstream or in OpenWA, it has a row here.
+12 install-time patches (29.3). If it exists upstream or in OpenWA, it has a row here.
## 29.1 How to read this matrix
@@ -50,7 +50,7 @@ flowchart LR
IF --> BA["BaileysAdapter"]
SVC --> STORE["OpenWA-side stores"]
end
- WA --> WLIB["whatsapp-web.js 1.34.7<br/>+ 10 OpenWA patches"]
+ WA --> WLIB["whatsapp-web.js 1.34.7<br/>+ 9 OpenWA patches"]
BA --> BLIB["@whiskeysockets/baileys 7.0.0-rc14<br/>+ 3 OpenWA patches"]
WLIB --> WEB["WhatsApp Web<br/>headless Chromium"]
BLIB --> WAS["WhatsApp servers<br/>browser-free socket"]
@@ -128,7 +128,7 @@ wrong interface method. Those three remain reader-verified.
## 29.3 Install-time patches OpenWA applies to the libraries
-OpenWA ships thirteen exact, self-disabling source transforms over the installed engines. Each runs at
+OpenWA ships twelve exact, self-disabling source transforms over the installed engines. Each runs at
`npm install` (`scripts/postinstall.js`, `--best-effort`) and again in the Docker production stage
(**without** best-effort — dependency drift fails the image build). A recognized repaired source shape makes the
patcher no-op; an unrecognized source shape fails loudly rather than shipping a silently partial
@@ -141,7 +141,7 @@ it is missing as it starts (`src/engine/adapters/engine-patch-status.ts`; 🔧¹
check described below). The report is diagnostic, not preventive: startup continues, so a session
reaching READY is not evidence that every patch landed. See docs/12 for the operator procedure.
-### 29.3.1 The thirteen patches
+### 29.3.1 The twelve patches
| # | Patcher | Library target | What it repairs | Stand-down predicate |
| ------ | ---------------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -157,11 +157,10 @@ reaching READY is not evidence that every patch landed. See docs/12 for the oper
| 🔧⁹ | `scripts/patch-wwebjs-group-description.js` | whatsapp-web.js `GroupChat.js` | `GroupChat.setDescription()` calls the page's `WAWebGroupModifyInfoJob.setGroupDescription(chatWid, description, newId, descId)` positionally, but that job now takes a single options object `{desc, groupWid, newDescId, prevDescId}`. The first positional argument lands where the object is read, every field comes back undefined, and `widToGroupJid(undefined)` throws inside the page — reaching the caller as a bare `500` while the library still types the method `Promise<boolean>`. `setGroupSubject` in the same module is still positional, which is why subjects kept working and made the Wid look innocent. The patch sends the options object, takes `newDescId` from `WARandomHex.randomHex(8)` as the product does, and maps an empty description to `desc: null` so it selects the job's delete branch rather than sending an empty body element. The open upstream fix #201895 changes the same call, but keeps `WAWebMsgKey.newId()` and passes an empty description through verbatim, so this patcher will not stand down when it lands and the `desc: null` mapping has to be carried over rather than dropped with it. | exact-shape match; unknown shape fails the build. |
| 🔧¹⁰ | `scripts/patch-wwebjs-media-id.js` | whatsapp-web.js `Injected/Utils.js` | Every media send built by `processMediaData` failed on the WhatsApp Web builds rolled out on 2026-09-17 with `Data passed to getter must include an id property`, while text still sent. `window.WWebJS.sendMessage` builds the outgoing message with `id: newMsgKey` and then spreads the media model returned by `processMediaData` into it, and on those builds that model carries an enumerable private `__x_id` that clobbers the id when the `Msg` model initialises. The patch deletes `message.__x_id` right after the object is built, which is upstream's own fix (whatsapp-web.js PR #201923, unmerged, no release after 1.34.7). It stands down once the installed tree carries that line. | exact-shape match; unknown shape fails the build. |
| 🔧¹¹ | `scripts/patch-wwebjs-send-error.js` | whatsapp-web.js `Client.js` | A send the page refused reached OpenWA as the minified `t: t`, with nothing but Node frames: puppeteer rebuilds a page-side exception from its class name and description only, and WhatsApp Web's own error classes are minified to one letter and keep their detail in their own properties. The patch wraps the `window.WWebJS.sendMessage` call inside `Client.sendMessage`'s evaluate. A plain `Error`, which is what whatsapp-web.js's own send failures and WhatsApp Web's `No LID for user` already are, is rethrown as the same object, so its text and OpenWA's matching on it are unchanged. Anything else is rethrown as an `Error` reading `page threw {...}`, a capped JSON summary of the WhatsApp Web build actually running, the constructor name, `name`, `message`, `stack` and the value's own properties. Diagnostic only: a successful send returns what it returned before, and the dead-page classifier never reads a captured error as a transport death. | exact-shape match; unknown shape fails the build. |
-| 🔧¹² | `scripts/patch-wwebjs-download-mimetype.js` | whatsapp-web.js `Message.js` | Every download of inbound media the page had not decrypted before failed on current WhatsApp Web builds, so webhooks, the chat-media archive and `history?includeMedia=true` carried the `omitted` marker and the media route answered `404`. `Message#downloadMedia()` calls `downloadAndMaybeDecrypt()` without a `mimetype`; WhatsApp Web defaults the missing value to `application/octet-stream`, rejects it as the wrong type for the media, and the `InvalidMediaFileType` it throws reaches OpenWA as `t: t`. A file the page already decrypted comes from a cache keyed by file hash and skips that check, which is why some downloads kept working. The patch passes `msg.mimetype` to the call, the fix diagnosed in whatsapp-web.js issue #201908 (no release after 1.34.7). It stands down once the installed tree carries that line. | exact-shape match; unknown shape fails the build. |
### 29.3.2 Which matrix rows depend on which patch
-This is the patch visibility the matrix cells refer to. Every patch is engine-specific (10 on wwjs,
+This is the patch visibility the matrix cells refer to. Every patch is engine-specific (9 on wwjs,
3 on Baileys), and **no row carries a row-level patch mark on both engines**. The two column-wide
patches are a separate matter: 🔧¹ underwrites every wwjs cell and 🔧⁵ every baileys cell, so in
that sense every row does depend on a patch on each side. "Patch-dependent" below means a patch
@@ -181,7 +180,6 @@ class of rows (🔧⁸ and 🔧¹⁰), stated in the table instead.
| 🔧⁸ block/unblock | `blockContact`, `unblockContact` on **wwjs**. Without it both answer an opaque `500` on every id, so the capability is dead rather than degraded; the blocklist read still works, which makes the failure look one-sided. |
| 🔧¹⁰ media send repair | Every **wwjs** media send built by `processMediaData`: `sendImageMessage`, `sendVideoMessage`, `sendAudioMessage` (voice notes included, through `ptt`), `sendDocumentMessage` and the media status posts. A sticker is built by `processStickerData`, which returns a new object rather than the media model. On the WhatsApp Web builds from 2026-09-17 the library's own id is clobbered by the media model and every such send answers a bare `500`, while text sends keep working. Not row-marked: it covers a whole class of rows rather than one. |
| 🔧¹¹ send error capture | No row. Every **wwjs** send that fails in the page reports what the page threw instead of `t: t`, but no cell's outcome depends on it: a send that works without the patch works the same way with it. |
-| 🔧¹² download mimetype | No single row. Every **wwjs** media download goes through `Message#downloadMedia()`: inbound message media (webhook, chat-media archive, the media route), the own-send echo, `getChatHistory` with `includeMedia`, and received statuses. Without it, media the page has not decrypted before arrives as the `omitted` marker instead of its bytes; the messages themselves still arrive. |
Rows that are ✅ on **both** engines where one side is patch-dependent: `initialize` (🔧⁴ wwjs),
`sendTextMessage` (🔧³ wwjs), `postTextStatus` / `postImageStatus` / `postVideoStatus` /
@@ -1034,7 +1032,7 @@ adapter sources — re-derive the same way when anything changes:
cannot repopulate; and `rejectCall`, whose `Call.reject()` resolves while the caller's phone
keeps ringing (all in 29.6.2). Each answers 501 on wwjs. `.d.ts` presence is not capability, and
only a live call distinguishes the two.
-- **13** install-time patches (10 whatsapp-web.js + 3 Baileys), all exact and self-disabling.
+- **12** install-time patches (9 whatsapp-web.js + 3 Baileys), all exact and self-disabling.
- **0 phantom-support rows** — every `not-available` cell throws at the adapter boundary.
- Remaining adapter-gaps (fixable in this repo, ranked): **#1** `getChannelMessages` (Baileys —
fetch is one line, `BinaryNode`→`ChannelMessage` parser is the work); **#2** `subscribeToChannel`
diff --git a/package.json b/package.json
index 7f58d7e48..c749507b0 100644
--- a/package.json
+++ b/package.json
@@ -41,7 +41,7 @@
"lint": "eslint \"{src,apps,libs,test}/**/*.ts\"",
"lint:fix": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
"test": "jest",
- "test:scripts": "node --test scripts/proxy-addr.spec.js scripts/postinstall.spec.js scripts/patch-wwebjs-newsletter-preview.spec.js scripts/patch-wwebjs-status.spec.js scripts/patch-wwebjs-ready-sync.spec.js scripts/patch-wwebjs-participant-arity.spec.js scripts/patch-wwebjs-block.spec.js scripts/patch-wwebjs-group-description.spec.js scripts/patch-wwebjs-media-id.spec.js scripts/patch-wwebjs-send-error.spec.js scripts/patch-wwebjs-download-mimetype.spec.js scripts/patch-baileys-appstate.spec.js scripts/patch-baileys-newsletter-create.spec.js scripts/patch-baileys-pairing.spec.js scripts/baileys-pairing.integration.spec.mjs scripts/dockerfile-patchers.spec.js scripts/smoke-test-docker-proxy.spec.js scripts/check-upstream-surface.spec.mjs scripts/check-sdk-docs.spec.mjs scripts/check-audit.spec.mjs scripts/check-contract-shapes.spec.mjs scripts/check-sdk-coverage.spec.mjs scripts/cli-entrypoint-guard.spec.mjs",
+ "test:scripts": "node --test scripts/proxy-addr.spec.js scripts/postinstall.spec.js scripts/patch-wwebjs-newsletter-preview.spec.js scripts/patch-wwebjs-status.spec.js scripts/patch-wwebjs-ready-sync.spec.js scripts/patch-wwebjs-participant-arity.spec.js scripts/patch-wwebjs-block.spec.js scripts/patch-wwebjs-group-description.spec.js scripts/patch-wwebjs-media-id.spec.js scripts/patch-wwebjs-send-error.spec.js scripts/patch-baileys-appstate.spec.js scripts/patch-baileys-newsletter-create.spec.js scripts/patch-baileys-pairing.spec.js scripts/baileys-pairing.integration.spec.mjs scripts/dockerfile-patchers.spec.js scripts/smoke-test-docker-proxy.spec.js scripts/check-upstream-surface.spec.mjs scripts/check-sdk-docs.spec.mjs scripts/check-audit.spec.mjs scripts/check-contract-shapes.spec.mjs scripts/check-sdk-coverage.spec.mjs scripts/cli-entrypoint-guard.spec.mjs",
"test:docs": "jest src/common/changelog-sections.spec.ts src/common/ci-privilege-gate.spec.ts src/common/docs-ci-jobs.spec.ts src/common/docs-coverage-policy.spec.ts src/common/docs-metrics-list.spec.ts src/common/docs-next-version.spec.ts src/common/docs-sdk-rate-limit.spec.ts src/common/openapi/docs-06-contract.spec.ts src/common/test-lane-partition.spec.ts src/config/docs-env-example.spec.ts src/config/openapi-contract.spec.ts src/config/openapi-export-pins.spec.ts src/config/wa-web-version-example-pin.spec.ts src/engine/docs-29-counts.spec.ts src/engine/docs-27-backfill-engine.spec.ts src/engine/engine-inventory-parity.spec.ts src/engine/engine-parity.spec.ts src/engine/inventory-mapping-direction.spec.ts src/engine/adapters/baileys-voice-waveform.spec.ts src/engine/adapters/wwebjs-newsletter-preview.spec.ts src/modules/audit/audit-coverage.spec.ts src/modules/auth/global-route-fence-coverage.spec.ts src/modules/auth/query-session-scope-coverage.spec.ts src/modules/docker/compose-network.spec.ts src/modules/queue/bull-board-mount-coverage.spec.ts src/common/release-gate-parity.spec.ts src/database/migrations/__tests__/migration-drift.spec.ts src/common/docs-governance.spec.ts --testPathIgnorePatterns=/node_modules/",
"test:watch": "jest --watch",
"test:cov": "jest --coverage",
diff --git a/scripts/patch-wwebjs-download-mimetype.js b/scripts/patch-wwebjs-download-mimetype.js
deleted file mode 100644
index d6cd80dd0..000000000
--- a/scripts/patch-wwebjs-download-mimetype.js
+++ /dev/null
@@ -1,91 +0,0 @@
-/**
- * Pass the message's mimetype to the media download whatsapp-web.js runs in the page.
- *
- * `Message#downloadMedia()` decrypts through `WAWebDownloadManager.downloadAndMaybeDecrypt()`
- * without a `mimetype`. Current WhatsApp Web builds default the missing value to
- * `application/octet-stream` and check it against the media type, so every download of media the
- * page has not decrypted before fails with `InvalidMediaFileType`, which reaches Node as the
- * minified `t: t`. Media the page already decrypted comes from a cache keyed by file hash and skips
- * that check, which is why some downloads still succeed. Diagnosed upstream in whatsapp-web.js
- * issue #201908, with no release after 1.34.7; this adds the option that issue identifies.
- *
- * The source transform is deliberately exact and self-disabling. An unknown shape fails the
- * production image build instead of silently shipping without the fix, and the patch stands down
- * once the installed tree carries the line itself.
- */
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-
-const DEFAULT_WWJS = path.join(__dirname, '..', 'node_modules', 'whatsapp-web.js');
-const MESSAGE_PATH = path.join('src', 'structures', 'Message.js');
-// The two options of the downloadAndMaybeDecrypt call in downloadMedia the fix goes between,
-// unique in the file.
-const TYPE_LINE = ' type: msg.type,\n';
-const SIGNAL_LINE = ' signal: new AbortController().signal,\n';
-const ANCHOR = TYPE_LINE + SIGNAL_LINE;
-const FIX = TYPE_LINE + ' mimetype: msg.mimetype,\n' + SIGNAL_LINE;
-
-function occurrences(source, needle) {
- return source.split(needle).length - 1;
-}
-
-function applyBackport(wwjsDir = DEFAULT_WWJS) {
- const messageFile = path.join(wwjsDir, MESSAGE_PATH);
- if (!fs.existsSync(messageFile)) {
- throw new Error(`whatsapp-web.js Message.js not found at ${messageFile}`);
- }
-
- const source = fs.readFileSync(messageFile, 'utf8');
- const anchorCount = occurrences(source, ANCHOR);
- const fixCount = occurrences(source, FIX);
-
- if (anchorCount === 0 && fixCount === 1) {
- return {
- skipped: true,
- reason: 'installed whatsapp-web.js already passes the mimetype to the media download',
- };
- }
- if (anchorCount !== 1 || fixCount !== 0) {
- throw new Error(
- `unsupported Message.js shape (anchors: ${anchorCount}, fixes: ${fixCount}); ` +
- 're-evaluate the media download backport against the installed whatsapp-web.js',
- );
- }
-
- fs.writeFileSync(messageFile, source.replace(ANCHOR, FIX));
- return { skipped: false, note: 'mimetype passed to the media download' };
-}
-
-/**
- * The stand-down branch above as a predicate, for the startup guard (engine-patch-status.ts).
- * Unreadable reads as applied: a tree we cannot inspect is not evidence of a broken one.
- */
-function isApplied(wwjsDir = DEFAULT_WWJS) {
- try {
- const source = fs.readFileSync(path.join(wwjsDir, MESSAGE_PATH), 'utf8');
- return occurrences(source, ANCHOR) === 0 && occurrences(source, FIX) === 1;
- } catch {
- return true;
- }
-}
-
-function run() {
- const bestEffort = process.argv.includes('--best-effort');
- try {
- const result = applyBackport();
- console.log(`patch-wwebjs-download-mimetype: ${result.skipped ? `skipped: ${result.reason}` : result.note}`);
- } catch (error) {
- if (bestEffort) {
- console.warn(`patch-wwebjs-download-mimetype: skipped: ${error.message}`);
- return;
- }
- console.error(`patch-wwebjs-download-mimetype: ${error.message}`);
- process.exitCode = 1;
- }
-}
-
-if (require.main === module) run();
-
-module.exports = { applyBackport, isApplied, ANCHOR, FIX };
diff --git a/scripts/patch-wwebjs-download-mimetype.spec.js b/scripts/patch-wwebjs-download-mimetype.spec.js
deleted file mode 100644
index 38af30529..000000000
--- a/scripts/patch-wwebjs-download-mimetype.spec.js
+++ /dev/null
@@ -1,76 +0,0 @@
-'use strict';
-
-const test = require('node:test');
-const assert = require('node:assert/strict');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-
-const { applyBackport, isApplied, ANCHOR, FIX } = require('./patch-wwebjs-download-mimetype.js');
-
-// The real shape around the anchor: the options object of the downloadAndMaybeDecrypt call.
-const BEFORE = ` mediaKeyTimestamp: msg.mediaKeyTimestamp,\n${ANCHOR} downloadQpl: mockQpl,\n`;
-const AFTER = ` mediaKeyTimestamp: msg.mediaKeyTimestamp,\n${FIX} downloadQpl: mockQpl,\n`;
-
-function makeDependency(source) {
- const root = fs.mkdtempSync(path.join(os.tmpdir(), 'openwa-download-mimetype-'));
- const message = path.join(root, 'src', 'structures', 'Message.js');
- fs.mkdirSync(path.dirname(message), { recursive: true });
- fs.writeFileSync(message, source);
- return { root, message };
-}
-
-test('passes the mimetype to the media download', () => {
- const { root, message } = makeDependency(`head\n${BEFORE}tail\n`);
-
- const result = applyBackport(root);
-
- assert.deepEqual(result, { skipped: false, note: 'mimetype passed to the media download' });
- assert.equal(fs.readFileSync(message, 'utf8'), `head\n${AFTER}tail\n`);
-});
-
-test('is idempotent once the fix is present', () => {
- const { root, message } = makeDependency(`head\n${AFTER}tail\n`);
- const original = fs.readFileSync(message, 'utf8');
-
- assert.deepEqual(applyBackport(root), {
- skipped: true,
- reason: 'installed whatsapp-web.js already passes the mimetype to the media download',
- });
- assert.equal(fs.readFileSync(message, 'utf8'), original);
-});
-
-test('reports the patch as applied only once the transform has run', () => {
- const { root } = makeDependency(`head\n${BEFORE}tail\n`);
-
- assert.equal(isApplied(root), false);
- applyBackport(root);
- assert.equal(isApplied(root), true);
-});
-
-test('rejects an unknown dependency shape without changing it', () => {
- const { root, message } = makeDependency('class Message {}\n');
- const original = fs.readFileSync(message, 'utf8');
-
- assert.throws(() => applyBackport(root), /unsupported Message\.js shape/);
- assert.equal(fs.readFileSync(message, 'utf8'), original);
-});
-
-test('rejects an ambiguous dependency shape without changing it', () => {
- const { root, message } = makeDependency(`${BEFORE}${BEFORE}`);
- const original = fs.readFileSync(message, 'utf8');
-
- assert.throws(() => applyBackport(root), /unsupported Message\.js shape/);
- assert.equal(fs.readFileSync(message, 'utf8'), original);
-});
-
-// The patch stands down when the fix is already there, so a shape carrying both the fix and an
-// unpatched call is not one it understands either.
-test('rejects a fix present alongside an unpatched call', () => {
- const { root, message } = makeDependency(`${AFTER}${BEFORE}`);
- const original = fs.readFileSync(message, 'utf8');
-
- assert.throws(() => applyBackport(root), /unsupported Message\.js shape/);
- assert.equal(fs.readFileSync(message, 'utf8'), original);
- assert.equal(isApplied(root), false);
-});
diff --git a/scripts/postinstall.js b/scripts/postinstall.js
index d1bac1991..ca11e31f5 100644
--- a/scripts/postinstall.js
+++ b/scripts/postinstall.js
@@ -1,7 +1,7 @@
/**
* Post-install hook (npm `postinstall`).
*
- * Fourteen conditional steps, each skipped when its target is absent so the hook is a no-op where the
+ * Thirteen conditional steps, each skipped when its target is absent so the hook is a no-op where the
* piece is missing (the Docker builder stage copies package*.json long before any source):
*
* 1. `npm ci` inside dashboard/ when dashboard/ exists — the dashboard carries its own lockfile and
@@ -32,16 +32,13 @@
* 10. `node scripts/patch-wwebjs-send-error.js --best-effort` when present, making a failed send
* report what the page threw instead of `t: t`, gated the same way. It runs after the other
* two Client.js patchers (steps 2 and 5), so theirs still meet the tree they were written for.
- * 11. `node scripts/patch-wwebjs-download-mimetype.js --best-effort` when present, passing the
- * message's mimetype to the media download so inbound media downloads work again, gated the
- * same way.
- * 12. `node scripts/patch-baileys-appstate.js --best-effort` when present, the app-state resync
+ * 11. `node scripts/patch-baileys-appstate.js --best-effort` when present, the app-state resync
* bound, gated the same way.
- * 13. `node scripts/patch-baileys-newsletter-create.js --best-effort` when present, the
- * newsletter-create parse fix. Steps 12-14 are the Baileys patches. Every patcher runs whenever
+ * 12. `node scripts/patch-baileys-newsletter-create.js --best-effort` when present, the
+ * newsletter-create parse fix. Steps 11-13 are the Baileys patches. Every patcher runs whenever
* its script is present, whatever ENGINE_TYPE is set to.
*
- * 14. `node scripts/patch-baileys-pairing.js --best-effort` when present, preserving pre-login
+ * 13. `node scripts/patch-baileys-pairing.js --best-effort` when present, preserving pre-login
* notification ACKs and refreshing pairing credentials. A partial patch remains fatal.
*
* Structured like scripts/patch-wwebjs-201832.js: pure planning + injectable spawn, so the spec
@@ -169,15 +166,6 @@ function planSteps(root, env = process.env) {
options: { stdio: 'inherit', cwd: root, env: cleanEnv },
});
}
- const downloadMimetypePatcher = path.join(root, 'scripts', 'patch-wwebjs-download-mimetype.js');
- if (fs.existsSync(downloadMimetypePatcher)) {
- steps.push({
- name: 'whatsapp-web.js media download mimetype (scripts/patch-wwebjs-download-mimetype.js --best-effort)',
- command: process.execPath,
- args: [downloadMimetypePatcher, '--best-effort'],
- options: { stdio: 'inherit', cwd: root, env: cleanEnv },
- });
- }
const baileysAppStatePatcher = path.join(root, 'scripts', 'patch-baileys-appstate.js');
if (fs.existsSync(baileysAppStatePatcher)) {
steps.push({
diff --git a/scripts/postinstall.spec.js b/scripts/postinstall.spec.js
index 7957e0604..e9639006a 100644
--- a/scripts/postinstall.spec.js
+++ b/scripts/postinstall.spec.js
@@ -34,7 +34,6 @@ const EXPECTED_PATCHER_ORDER = [
'patch-wwebjs-group-description.js',
'patch-wwebjs-media-id.js',
'patch-wwebjs-send-error.js',
- 'patch-wwebjs-download-mimetype.js',
'patch-baileys-appstate.js',
'patch-baileys-newsletter-create.js',
'patch-baileys-pairing.js',
diff --git a/src/engine/adapters/inbound-media-cap.spec.ts b/src/engine/adapters/inbound-media-cap.spec.ts
index 2f604664c..ebd5fc932 100644
--- a/src/engine/adapters/inbound-media-cap.spec.ts
+++ b/src/engine/adapters/inbound-media-cap.spec.ts
@@ -19,6 +19,15 @@ import {
ingestMediaBudgetBytes,
} from './inbound-media-cap';
+/**
+ * Serve a message's media download from `download`: production reads it through the page
+ * (downloadCappedMedia), and the same mock stays reachable as `downloadMedia` for assertions.
+ */
+const onPage = <T extends jest.Mock>(download: T) => ({
+ downloadMedia: download,
+ client: { pupPage: { evaluate: download } },
+});
+
describe('inbound media cap', () => {
const ENV = 'MEDIA_DOWNLOAD_MAX_BYTES';
const CONC = 'INBOUND_MEDIA_CONCURRENCY';
@@ -343,13 +352,15 @@ describe('process-wide inbound media gate (INBOUND_MEDIA_GLOBAL_CONCURRENCY)', (
const makeMsg = (id: string): unknown => ({
id: { _serialized: id },
_data: { size: 100, mimetype: 'image/png' },
- downloadMedia: jest.fn(() => {
- inFlight++;
- maxInFlight = Math.max(maxInFlight, inFlight);
- const d = defer<{ mimetype: string; data: string }>();
- downloads.push(d);
- return d.promise.finally(() => inFlight--);
- }),
+ ...onPage(
+ jest.fn(() => {
+ inFlight++;
+ maxInFlight = Math.max(maxInFlight, inFlight);
+ const d = defer<{ mimetype: string; data: string }>();
+ downloads.push(d);
+ return d.promise.finally(() => inFlight--);
+ }),
+ ),
});
const a = newAdapter('gate-a');
const b = newAdapter('gate-b');
@@ -377,12 +388,12 @@ describe('process-wide inbound media gate (INBOUND_MEDIA_GLOBAL_CONCURRENCY)', (
const first = {
id: { _serialized: 'x1' },
_data: { size: 100, mimetype: 'image/png' },
- downloadMedia: jest.fn(() => held.promise),
+ ...onPage(jest.fn(() => held.promise)),
};
const second = {
id: { _serialized: 'y1' },
_data: { size: 100, mimetype: 'image/png' },
- downloadMedia: jest.fn(),
+ ...onPage(jest.fn()),
};
const r1 = cap(newAdapter('gate-x'), first);
diff --git a/src/engine/adapters/inbound-media-cap.ts b/src/engine/adapters/inbound-media-cap.ts
index 618535c23..c22da3c1a 100644
--- a/src/engine/adapters/inbound-media-cap.ts
+++ b/src/engine/adapters/inbound-media-cap.ts
@@ -83,10 +83,10 @@ export function inboundMediaTimeoutMs(): number {
* bound TIME: a remote sender can trickle bytes slowly (never tripping the cap) and hold a concurrency
* slot indefinitely — a slow-loris on the inbound pipeline. On timeout `onTimeout` runs — a best-effort
* hook to abort the source where it's abortable (e.g. destroy a Baileys stream) — and the result resolves
- * `null`, the "no usable media" sentinel. A non-abortable source (the wwjs `downloadMedia()`) can't be
- * stopped, so that caller must instead hold its concurrency slot until the real download settles. A late
- * rejection from the abandoned download is swallowed so it can't surface as an unhandled rejection after
- * the race has already settled.
+ * `null`, the "no usable media" sentinel. A non-abortable source (the wwjs page download,
+ * `downloadCappedMedia()`) can't be stopped, so that caller must instead hold its concurrency slot until the
+ * real download settles. A late rejection from the abandoned download is swallowed so it can't surface as an
+ * unhandled rejection after the race has already settled.
*/
export function withInboundDownloadTimeout<T>(
promise: Promise<T>,
diff --git a/src/engine/adapters/whatsapp-web-js.adapter.spec.ts b/src/engine/adapters/whatsapp-web-js.adapter.spec.ts
index 4b193df65..3d34554b0 100644
--- a/src/engine/adapters/whatsapp-web-js.adapter.spec.ts
+++ b/src/engine/adapters/whatsapp-web-js.adapter.spec.ts
@@ -18,10 +18,13 @@ import {
NAVIGATION_REINJECT_GRACE_MS,
NAVIGATION_EPISODE_CAP_MS,
} from './whatsapp-web-js.adapter';
+import { downloadMediaInPage } from './wwebjs-messaging';
+import { LoggerService } from '../../common/services/logger.service';
import { resolveOnboardingContinueLabels } from './wwebjs-onboarding';
import { getEffectiveWebVersionInfo, resolveWebVersionPin, __resetWebVersionCache } from '../wa-web-version';
import { resolveEngineInitTimeoutMs } from '../engine-init-timeout';
import * as fs from 'fs';
+import { createHash } from 'crypto';
import * as path from 'path';
import * as qrcode from 'qrcode';
import { InternalServerErrorException, UnprocessableEntityException, BadRequestException } from '@nestjs/common';
@@ -74,6 +77,15 @@ jest.mock('qrcode', () => ({
// jest.spyOn cannot redefine execFile on it. The adapter reads execFile live off this same object.
const childProcess = jest.requireActual<typeof import('child_process')>('child_process');
+/**
+ * Serve a message's media download from `download`: production reads it through the page
+ * (downloadCappedMedia), and the same mock stays reachable as `downloadMedia` for assertions.
+ */
+const onPage = <T extends jest.Mock>(download: T) => ({
+ downloadMedia: download,
+ client: { pupPage: { evaluate: download } },
+});
+
describe('wwebjsAckToDeliveryStatus (engine ack-int -> neutral DeliveryStatus boundary, #265)', () => {
// Regression-locks the integer boundary the decoupling moved behaviour into, incl. the
// PLAYED(4) -> 'read' collapse that the old ackToMessageStatus(4) -> READ test used to cover.
@@ -948,7 +960,7 @@ describe('WhatsAppWebJsAdapter.getChatHistory enrichment (parity with the live p
hasMedia: true,
hasQuotedMsg: false,
_data: { size: 12 * 1024 * 1024, mimetype: 'image/jpeg' },
- downloadMedia: jest.fn(),
+ ...onPage(jest.fn()),
};
const chat = { fetchMessages: jest.fn().mockResolvedValue([mediaMsg]) };
const client = { getChatById: jest.fn().mockResolvedValue(chat) };
@@ -978,7 +990,7 @@ describe('WhatsAppWebJsAdapter.getChatHistory enrichment (parity with the live p
hasMedia: true,
hasQuotedMsg: false,
_data: { size: data.length, mimetype: 'image/jpeg' },
- downloadMedia: jest.fn().mockResolvedValue({ data, mimetype: 'image/jpeg' }),
+ ...onPage(jest.fn().mockResolvedValue({ data, mimetype: 'image/jpeg' })),
});
const clientFor = (...msgs: unknown[]) => ({
getChatById: jest.fn().mockResolvedValue({ fetchMessages: jest.fn().mockResolvedValue(msgs) }),
@@ -3298,7 +3310,7 @@ describe('WhatsAppWebJsAdapter status methods', () => {
timestamp: 1700000030,
hasMedia: true,
_data: { mimetype: 'image/png', size: 3 },
- downloadMedia,
+ ...onPage(downloadMedia),
},
],
};
@@ -3623,7 +3635,7 @@ describe('WhatsAppWebJsAdapter inbound media (MEDIA_DOWNLOAD_ENABLED=false)', ()
fromMe: true,
hasMedia: true,
_data: { mimetype: 'image/png', size: 3 },
- downloadMedia: jest.fn().mockResolvedValue({ mimetype: 'image/png', data: 'QUJD', filename: 'a.png' }),
+ ...onPage(jest.fn().mockResolvedValue({ mimetype: 'image/png', data: 'QUJD', filename: 'a.png' })),
getContact: jest.fn().mockResolvedValue(null),
hasQuotedMsg: false,
};
@@ -3672,7 +3684,7 @@ describe('WhatsAppWebJsAdapter inbound media (MEDIA_DOWNLOAD_ENABLED=false)', ()
fromMe: true,
hasMedia: true,
_data: { mimetype: 'image/png', size: 3 },
- downloadMedia: jest.fn().mockResolvedValue({ mimetype: 'image/png', data: 'QUJD', filename: 'a.png' }),
+ ...onPage(jest.fn().mockResolvedValue({ mimetype: 'image/png', data: 'QUJD', filename: 'a.png' })),
hasQuotedMsg: false,
};
@@ -3716,7 +3728,7 @@ describe('WhatsAppWebJsAdapter inbound media (MEDIA_DOWNLOAD_ENABLED=false)', ()
fromMe: true,
hasMedia: true,
_data: { mimetype: 'image/png', size: 3 },
- downloadMedia: jest.fn().mockRejectedValue(new Error('media gone')),
+ ...onPage(jest.fn().mockRejectedValue(new Error('media gone'))),
getContact: jest.fn().mockResolvedValue(null),
hasQuotedMsg: false,
};
@@ -3765,7 +3777,7 @@ describe('WhatsAppWebJsAdapter inbound media (MEDIA_DOWNLOAD_ENABLED=false)', ()
hasMedia: true,
_data: { mimetype: 'image/jpeg', size: 2048 },
// The minified page-side throw a WhatsApp Web build surfaces through Puppeteer.
- downloadMedia: jest.fn().mockRejectedValue(new Error('t: t')),
+ ...onPage(jest.fn().mockRejectedValue(new Error('t: t'))),
getContact: jest.fn().mockResolvedValue(null),
hasQuotedMsg: false,
};
@@ -5508,15 +5520,17 @@ describe('WhatsAppWebJsAdapter inbound media concurrency (slot held until the re
const makeMsg = (id: string): unknown => ({
id: { _serialized: id },
_data: { size: 100, mimetype: 'image/png' },
- downloadMedia: jest.fn(() => {
- inFlight++;
- maxInFlight = Math.max(maxInFlight, inFlight);
- const d = defer<{ mimetype: string; data: string }>();
- downloads.push(d);
- return d.promise.finally(() => {
- inFlight--;
- });
- }),
+ ...onPage(
+ jest.fn(() => {
+ inFlight++;
+ maxInFlight = Math.max(maxInFlight, inFlight);
+ const d = defer<{ mimetype: string; data: string }>();
+ downloads.push(d);
+ return d.promise.finally(() => {
+ inFlight--;
+ });
+ }),
+ ),
});
const cap = (m: unknown): Promise<unknown> =>
(adapter as unknown as { capInboundMediaFor: (msg: unknown) => Promise<unknown> }).capInboundMediaFor(m);
@@ -5561,13 +5575,15 @@ describe('WhatsAppWebJsAdapter inbound media concurrency (slot held until the re
const makeMsg = (id: string): unknown => ({
id: { _serialized: id },
_data: { size: 100, mimetype: 'image/png' },
- downloadMedia: jest.fn(() => {
- started.push(id);
- // Every download takes 60 ms, inside the 100 ms deadline on its own.
- return new Promise(resolve =>
- setTimeout(() => resolve({ mimetype: 'image/png', data: Buffer.from(id).toString('base64') }), 60),
- );
- }),
+ ...onPage(
+ jest.fn(() => {
+ started.push(id);
+ // Every download takes 60 ms, inside the 100 ms deadline on its own.
+ return new Promise(resolve =>
+ setTimeout(() => resolve({ mimetype: 'image/png', data: Buffer.from(id).toString('base64') }), 60),
+ );
+ }),
+ ),
});
const cap = (m: unknown): Promise<{ data?: string; omitted?: boolean }> =>
(
@@ -5602,12 +5618,14 @@ describe('WhatsAppWebJsAdapter inbound media concurrency (slot held until the re
const makeMsg = (id: string, behavior: 'reject' | 'resolve'): unknown => ({
id: { _serialized: id },
_data: { size: 100, mimetype: 'image/png' },
- downloadMedia: jest.fn(() => {
- calls.push(id);
- return behavior === 'reject'
- ? Promise.reject(new Error('download blew up'))
- : Promise.resolve({ mimetype: 'image/png', data: Buffer.from('ok').toString('base64') });
- }),
+ ...onPage(
+ jest.fn(() => {
+ calls.push(id);
+ return behavior === 'reject'
+ ? Promise.reject(new Error('download blew up'))
+ : Promise.resolve({ mimetype: 'image/png', data: Buffer.from('ok').toString('base64') });
+ }),
+ ),
});
const cap = (m: unknown): Promise<unknown> =>
(adapter as unknown as { capInboundMediaFor: (msg: unknown) => Promise<unknown> }).capInboundMediaFor(m);
@@ -5630,7 +5648,7 @@ describe('WhatsAppWebJsAdapter inbound media concurrency (slot held until the re
const adapter = newAdapter();
const downloadMedia = jest.fn(() => Promise.resolve({ mimetype: 'video/mp4', data: 'x'.repeat(2000) }));
- const msg = { id: { _serialized: 'big' }, _data: { size: 1500, mimetype: 'video/mp4' }, downloadMedia };
+ const msg = { id: { _serialized: 'big' }, _data: { size: 1500, mimetype: 'video/mp4' }, ...onPage(downloadMedia) };
const cap = (m: unknown, override: number): Promise<unknown> =>
(adapter as unknown as { capInboundMediaFor: (msg: unknown, o: number) => Promise<unknown> }).capInboundMediaFor(
m,
@@ -5651,7 +5669,7 @@ describe('WhatsAppWebJsAdapter inbound media concurrency (slot held until the re
const adapter = newAdapter();
const data = Buffer.alloc(300).toString('base64');
const downloadMedia = jest.fn(() => Promise.resolve({ mimetype: 'image/jpeg', data }));
- const msg = { id: { _serialized: 'undeclared' }, _data: {}, downloadMedia };
+ const msg = { id: { _serialized: 'undeclared' }, _data: {}, ...onPage(downloadMedia) };
const cap = (m: unknown, override: number): Promise<unknown> =>
(adapter as unknown as { capInboundMediaFor: (msg: unknown, o: number) => Promise<unknown> }).capInboundMediaFor(
m,
@@ -5666,6 +5684,205 @@ describe('WhatsAppWebJsAdapter inbound media concurrency (slot held until the re
});
});
+/**
+ * The cap on what the page actually decrypted. The pre-gate only sees the size the sender declares,
+ * so a message that understates it passes; downloadMediaInPage runs here against a stand-in `window`
+ * whose download returns more than that.
+ */
+describe('WhatsAppWebJsAdapter inbound media measured in the page', () => {
+ const g = globalThis as unknown as { window?: unknown };
+ const ENV_KEYS = ['MEDIA_DOWNLOAD_MAX_BYTES', 'MEDIA_DOWNLOAD_ENABLED'];
+ let saved: Record<string, string | undefined> = {};
+ beforeEach(() => {
+ saved = {};
+ ENV_KEYS.forEach(k => (saved[k] = process.env[k]));
+ process.env.MEDIA_DOWNLOAD_MAX_BYTES = '1000';
+ process.env.MEDIA_DOWNLOAD_ENABLED = 'true';
+ runInPage.mockClear();
+ });
+ afterEach(() => {
+ ENV_KEYS.forEach(k => {
+ if (saved[k] === undefined) delete process.env[k];
+ else process.env[k] = saved[k];
+ });
+ delete g.window;
+ jest.restoreAllMocks();
+ });
+
+ /**
+ * A page holding message `M1`, whose decrypted media is `bytes` long; returns the encoder spy. `stage` is
+ * the media stage before the download, `resolvedStage` the one the page's own resolve step leaves.
+ */
+ function pageServing(
+ bytes: number,
+ page: { stage?: string; resolvedStage?: string; decrypt?: () => Promise<ArrayBuffer> } = {},
+ ): jest.Mock {
+ const toBase64 = jest.fn((buffer: ArrayBuffer) => Promise.resolve(Buffer.from(buffer).toString('base64')));
+ const pageMsg = {
+ mimetype: 'video/mp4',
+ filename: 'clip.mp4',
+ mediaData: { mediaStage: page.stage ?? 'RESOLVED' },
+ downloadMedia: () => {
+ pageMsg.mediaData.mediaStage = page.resolvedStage ?? 'RESOLVED';
+ return Promise.resolve();
+ },
+ };
+ const decrypt = page.decrypt ?? (() => Promise.resolve(new ArrayBuffer(bytes)));
+ g.window = {
+ require: (name: string) =>
+ name === 'WAWebCollections'
+ ? {
+ Msg: {
+ get: (id: string) => (id === 'M1' ? pageMsg : undefined),
+ getMessagesById: () => Promise.resolve({ messages: [] }),
+ },
+ }
+ : { downloadManager: { downloadAndMaybeDecrypt: decrypt } },
+ WWebJS: { arrayBufferToBase64Async: toBase64 },
+ };
+ return toBase64;
+ }
+
+ // The sender declares 10 bytes, well under the 1000-byte cap, so the pre-gate lets every case through.
+ const understated = (evaluate: jest.Mock) => ({
+ id: { _serialized: 'M1' },
+ _data: { size: 10, mimetype: 'video/mp4' },
+ ...onPage(evaluate),
+ });
+ const runInPage = jest.fn((fn: (arg: unknown) => Promise<unknown>, arg: unknown) => fn(arg));
+ const cap = (msg: unknown, override?: number): Promise<unknown> =>
+ (
+ new WhatsAppWebJsAdapter({
+ sessionId: 'media-2',
+ sessionDataPath: './data/sessions',
+ puppeteer: {},
+ }) as unknown as {
+ capInboundMediaFor: (m: unknown, o?: number) => Promise<unknown>;
+ }
+ ).capInboundMediaFor(msg, override);
+
+ it('drops a payload the page decrypted over the cap before encoding it, despite a small declared size', async () => {
+ const toBase64 = pageServing(5000);
+ const warn = jest.spyOn(LoggerService.prototype, 'warn').mockImplementation(() => undefined);
+
+ await expect(cap(understated(runInPage))).resolves.toEqual({
+ mimetype: 'video/mp4',
+ filename: 'clip.mp4',
+ omitted: true,
+ sizeBytes: 5000,
+ });
+ expect(toBase64).not.toHaveBeenCalled();
+ expect(runInPage).toHaveBeenCalledWith(downloadMediaInPage, { msgId: 'M1', maxBytes: 1000 });
+ expect(warn).toHaveBeenCalledTimes(1);
+ expect(warn).toHaveBeenCalledWith(
+ 'Inbound media exceeds MEDIA_DOWNLOAD_MAX_BYTES; dropped payload, kept envelope',
+ expect.objectContaining({ msgId: 'M1', sizeBytes: 5000 }),
+ );
+ });
+
+ it('checks the payload in the page against a per-call override below the global cap', async () => {
+ const toBase64 = pageServing(700);
+
+ await expect(cap(understated(runInPage), 500)).resolves.toEqual(
+ expect.objectContaining({ omitted: true, sizeBytes: 700 }),
+ );
+ expect(runInPage).toHaveBeenCalledWith(downloadMediaInPage, { msgId: 'M1', maxBytes: 500 });
+ expect(toBase64).not.toHaveBeenCalled();
+ });
+
+ it('still inlines a payload within the cap', async () => {
+ pageServing(3);
+
+ await expect(cap(understated(runInPage))).resolves.toEqual({
+ mimetype: 'video/mp4',
+ filename: 'clip.mp4',
+ data: Buffer.alloc(3).toString('base64'),
+ });
+ });
+
+ it('drops a payload over the cap by its received length even when the page reports it small', async () => {
+ const data = Buffer.alloc(2000).toString('base64');
+ const page = jest.fn().mockResolvedValue({ mimetype: 'video/mp4', data, sizeBytes: 10 });
+
+ await expect(cap(understated(page))).resolves.toEqual(expect.objectContaining({ omitted: true, sizeBytes: 2000 }));
+ });
+
+ // The rest of the page function is whatsapp-web.js's own download; these keep its outcomes intact.
+ type PageCase = { msgId?: string; stage?: string; resolvedStage?: string; decrypt?: () => Promise<ArrayBuffer> };
+ const notFound = () => Promise.reject(Object.assign(new Error('gone'), { status: 404 }));
+ it.each<[string, PageCase, null | undefined]>([
+ ['a message the page does not hold', { msgId: 'M2' }, null],
+ ['media the phone is re-uploading', { stage: 'REUPLOADING' }, null],
+ ['media whose resolve step fails', { stage: 'INIT', resolvedStage: 'ERROR_MISSING' }, undefined],
+ ['media still fetching after the resolve step', { stage: 'INIT', resolvedStage: 'FETCHING' }, undefined],
+ ['media the server no longer has', { decrypt: notFound }, undefined],
+ ])('returns %s as upstream does', async (_case, page, expected) => {
+ const toBase64 = pageServing(5, page);
+
+ await expect(downloadMediaInPage({ msgId: page.msgId ?? 'M1', maxBytes: 1000 })).resolves.toBe(expected);
+ expect(toBase64).not.toHaveBeenCalled();
+ });
+
+ it('resolves unresolved media in the page before downloading it', async () => {
+ pageServing(5, { stage: 'INIT' });
+
+ await expect(downloadMediaInPage({ msgId: 'M1', maxBytes: 1000 })).resolves.toEqual({
+ mimetype: 'video/mp4',
+ filename: 'clip.mp4',
+ sizeBytes: 5,
+ data: Buffer.alloc(5).toString('base64'),
+ });
+ });
+
+ it('rethrows any other download error', async () => {
+ const failure = Object.assign(new Error('boom'), { status: 500 });
+ pageServing(5, { decrypt: () => Promise.reject(failure) });
+
+ await expect(downloadMediaInPage({ msgId: 'M1', maxBytes: 1000 })).rejects.toBe(failure);
+ });
+
+ // downloadMediaInPage copies the page side of Message#downloadMedia. The fingerprint pins the whole
+ // upstream method, comments and formatting aside, so any whatsapp-web.js release that changes it fails
+ // here; the other checks hold the copy to upstream's modules, accessors, literals and call arguments.
+ // A tree an older OpenWA install patched carries the copy's `mimetype` option and is read without it.
+ it('matches the page download of the installed whatsapp-web.js', () => {
+ const squash = (src: string) =>
+ src
+ .replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, '')
+ .replace(/\s+/g, ' ')
+ .replace(/ ?([^\w$ ]) ?/g, '$1')
+ .replace(/,(?=[)}\]])/g, '');
+ const upstreamFile = fs.readFileSync(require.resolve('whatsapp-web.js/src/structures/Message.js'), 'utf8');
+ const start = upstreamFile.indexOf('async downloadMedia()');
+ const method = squash(upstreamFile.slice(start, upstreamFile.indexOf('\n /**', start))).replace(
+ 'type:msg.type,mimetype:msg.mimetype,signal:',
+ 'type:msg.type,signal:',
+ );
+ const upstream = method.slice(method.indexOf('async(msgId)=>'), method.indexOf('},this.id._serialized'));
+ const ours = fs.readFileSync(path.join(__dirname, 'wwebjs-messaging.ts'), 'utf8');
+ const fn = ours.slice(ours.indexOf('export async function downloadMediaInPage'));
+ const own = squash(fn.slice(0, fn.indexOf('\n}\n'))).split('const collection=')[1] ?? '';
+ const members = (src: string) => [...new Set([...src.matchAll(/(?<!\.)\.([A-Za-z_]\w*)/g)].map(m => m[1]))].sort();
+ const literals = (src: string) => [...new Set([...src.matchAll(/'(\w+)'/g)].map(m => m[1]))].sort();
+ const call = (src: string, name: string) =>
+ (new RegExp(`\\.${name}\\(\\{[^}]*\\}\\)`).exec(src)?.[0] ?? '').replace(/downloadQpl:\w+/, 'downloadQpl:qpl');
+
+ expect(start).toBeGreaterThan(-1);
+ expect(createHash('sha256').update(method).digest('hex')).toBe(
+ 'f70f7cd8393bc60149745b7901bb96eece28a2940eaee4725e71ce615cf9ec73',
+ );
+ expect(literals(own)).toEqual(literals(upstream));
+ // The copy measures the decrypted length instead of reporting the declared `size`.
+ expect(members(own)).toEqual(
+ [...members(upstream).filter(m => m !== 'size'), 'byteLength', 'maxBytes', 'msgId', 'sizeBytes'].sort(),
+ );
+ expect(call(own, 'downloadMedia')).toBe(call(upstream, 'downloadMedia'));
+ expect(call(own, 'downloadAndMaybeDecrypt')).toBe(
+ call(upstream, 'downloadAndMaybeDecrypt').replace('type:msg.type,', 'type:msg.type,mimetype:msg.mimetype,'),
+ );
+ });
+});
+
/**
* The send contract when whatsapp-web.js cannot hand back a usable message (#757).
*
diff --git a/src/engine/adapters/whatsapp-web-js.adapter.ts b/src/engine/adapters/whatsapp-web-js.adapter.ts
index 0dca89269..a8ca84699 100644
--- a/src/engine/adapters/whatsapp-web-js.adapter.ts
+++ b/src/engine/adapters/whatsapp-web-js.adapter.ts
@@ -1,5 +1,5 @@
import { EventEmitter } from 'events';
-import { MessageMedia, type Client, type Message } from 'whatsapp-web.js';
+import { type Client, type Message } from 'whatsapp-web.js';
import {
CallLinkType,
IWhatsAppEngine,
@@ -44,7 +44,7 @@ import { ChannelMediaNotSupportedError } from '../../common/errors/channel-media
import { WwebjsGroups } from './wwebjs-groups';
import { type WwebjsEngineHost } from './wwebjs-host';
import { registerWwebjsMessageEvents } from './wwebjs-message-events';
-import { WwebjsMessaging, declaredOnlyMedia } from './wwebjs-messaging';
+import { WwebjsMessaging, declaredOnlyMedia, downloadCappedMedia, type PageMediaDownload } from './wwebjs-messaging';
import { WwebjsContacts } from './wwebjs-contacts';
import { WwebjsProfile } from './wwebjs-profile';
import { WwebjsLabels } from './wwebjs-labels';
@@ -129,8 +129,9 @@ export { READY_RECONCILE_TIMEOUT_MS, READY_RECONCILE_BRIDGE_RELOAD_GRACE_MS } fr
export class WhatsAppWebJsAdapter extends EventEmitter implements IWhatsAppEngine {
private readonly logger = createLogger('WhatsAppWebJsAdapter');
- // Bound concurrent inbound media downloads: downloadMedia() materialises the full base64 blob, so an
- // unbounded burst could stack many multi-MB allocations.
+ // Bound concurrent inbound media downloads: each one holds the whole decrypted file in the browser
+ // page and, when within the cap, its base64 in Node, so an unbounded burst could stack many multi-MB
+ // allocations.
// The queue is UNBOUNDED. A cap equal to the active slots made admission a constant
// (active + queued) whatever the batch size, so a burst lost the media of everything past the
// eighth — the same defect repaired on the Baileys side. Parking costs one held Message per
@@ -279,10 +280,11 @@ export class WhatsAppWebJsAdapter extends EventEmitter implements IWhatsAppEngin
}
/**
- * Download inbound media safely. downloadMedia() can't be size-bounded at the source, so (1) pre-gate
- * on the sender-declared size and skip the download entirely when it exceeds the cap, and (2) run the
- * download through the concurrency limiter for backpressure. Resolves an envelope whenever it has one
- * to build: the payload, or the declared-only marker when no blob is available.
+ * Download inbound media safely. The page decrypts the whole file before anything can measure it, so
+ * (1) pre-gate on the sender-declared size and skip the download entirely when it exceeds the cap,
+ * (2) let the page drop a decrypted payload over the cap before encoding it (downloadMediaInPage),
+ * and (3) run the download through the concurrency limiter for backpressure. Resolves an envelope
+ * whenever it has one to build: the payload, or the declared-only marker when no blob is available.
*/
private async capInboundMediaFor(
msg: Message,
@@ -308,15 +310,16 @@ export class WhatsAppWebJsAdapter extends EventEmitter implements IWhatsAppEngin
});
return declaredOnlyMedia(msg);
}
- // msg.downloadMedia() can't be aborted, so freeing the slot the moment the wall-clock deadline fires
+ // The page download can't be aborted, so freeing the slot the moment the wall-clock deadline fires
// would admit a fresh download while the abandoned one is still materialising in heap — letting the
// number of in-flight downloads exceed inboundMediaConcurrency(). Instead, HOLD the slot until the real
// download settles; the caller still unblocks on the timeout race and emits the message without media.
// boundedReady adopts the timeout-bounded race (a Promise resolving a Promise flattens), so awaiting it
// unblocks the caller once the task is admitted AND the deadline-or-download settles — yielding the
// media or null on timeout.
- let resolveBounded: (value: MessageMedia | null | PromiseLike<MessageMedia | null>) => void = () => undefined;
- const boundedReady = new Promise<MessageMedia | null>(resolve => {
+ type Download = PageMediaDownload | null | undefined;
+ let resolveBounded: (value: Download | PromiseLike<Download>) => void = () => undefined;
+ const boundedReady = new Promise<Download>(resolve => {
resolveBounded = resolve;
});
// Set when the caller's wait below expires. A task still queued at that point has nobody left to
@@ -329,11 +332,11 @@ export class WhatsAppWebJsAdapter extends EventEmitter implements IWhatsAppEngin
resolveBounded(null);
return Promise.resolve();
}
- // downloadMedia() is async, so a page-side throw (a detached target, a WA Web field rename) arrives
+ // The page download is async, so a page-side throw (a detached target, a WA Web field rename) arrives
// as a rejection, which boundedReady adopts and rethrows past the only exit that builds the marker,
// leaving every call site to emit with no media field at all. It is the same "no usable media"
// outcome as the timeout below, so it takes the same null sentinel.
- const download = msg.downloadMedia().catch((error: unknown) => {
+ const download = downloadCappedMedia(msg, maxBytes).catch((error: unknown) => {
this.logger.warn('Inbound media download failed; emitting the omitted marker', {
msgId,
error: String(error),
@@ -389,10 +392,12 @@ export class WhatsAppWebJsAdapter extends EventEmitter implements IWhatsAppEngin
if (!media) {
return declaredOnlyMedia(msg);
}
+ // An over-cap payload arrives without data, carrying the size the page measured. Anything that did
+ // arrive is counted here as received, so a page that sends more than the cap is still caught.
const capped = capInboundMedia({
mimetype: media.mimetype,
filename: media.filename || undefined,
- sizeBytes: Buffer.byteLength(media.data, 'base64'),
+ sizeBytes: media.data ? Buffer.byteLength(media.data, 'base64') : media.sizeBytes,
toBase64: () => media.data,
maxBytes,
});
diff --git a/src/engine/adapters/wwebjs-messaging.ts b/src/engine/adapters/wwebjs-messaging.ts
index 0150aca12..ff1b5dfe9 100644
--- a/src/engine/adapters/wwebjs-messaging.ts
+++ b/src/engine/adapters/wwebjs-messaging.ts
@@ -12,7 +12,7 @@ import {
PollInput,
Quotable,
} from '../interfaces/whatsapp-engine.interface';
-import { MessageWithReactions, SerializedWid } from '../types/whatsapp-web-js.types';
+import { MessageWithReactions, SerializedWid, readWid } from '../types/whatsapp-web-js.types';
import { BadRequestException, NotImplementedException } from '@nestjs/common';
import { MessageNotFoundError } from '../../common/errors/message-not-found.error';
import { EngineRefusedError } from '../../common/errors/engine-refused.error';
@@ -72,6 +72,96 @@ export function declaredOnlyMedia(msg: Message): IncomingMessage['media'] {
};
}
+/** A media download as {@link downloadMediaInPage} returns it: `data` is empty when the payload was over the cap. */
+export interface PageMediaDownload {
+ mimetype: string;
+ filename?: string;
+ data: string;
+ /** Decrypted byte length, measured in the page. */
+ sizeBytes: number;
+}
+
+/**
+ * Page-side `Message#downloadMedia()` (whatsapp-web.js 1.34.7) with two changes. It passes `mimetype`
+ * to `downloadAndMaybeDecrypt()`, which current WhatsApp Web builds require (upstream issue #201908),
+ * and it checks the decrypted length against `maxBytes`. The size the sender declares is not the size
+ * WhatsApp serves, and upstream base64-encodes and ships whatever it decrypts, so an understated
+ * `fileLength` brought an arbitrarily large string over the protocol into Node. An over-cap payload
+ * comes back with its size and no data. `undefined` and `null` keep upstream's meaning: no usable
+ * media.
+ */
+export async function downloadMediaInPage(args: {
+ msgId: string;
+ maxBytes: number;
+}): Promise<PageMediaDownload | null | undefined> {
+ type PageMsg = Record<string, unknown> & {
+ mimetype: string;
+ filename?: string;
+ mediaData?: { mediaStage: string };
+ downloadMedia: (opts: object) => Promise<unknown>;
+ };
+ const w = window as unknown as {
+ require(m: 'WAWebCollections'): {
+ Msg: {
+ get: (id: string) => PageMsg | undefined;
+ getMessagesById: (ids: string[]) => Promise<{ messages?: PageMsg[] } | undefined>;
+ };
+ };
+ require(m: 'WAWebDownloadManager'): {
+ downloadManager: { downloadAndMaybeDecrypt: (opts: object) => Promise<ArrayBuffer> };
+ };
+ WWebJS: { arrayBufferToBase64Async: (buffer: ArrayBuffer) => Promise<string> };
+ };
+ const collection = w.require('WAWebCollections').Msg;
+ const msg = collection.get(args.msgId) || (await collection.getMessagesById([args.msgId]))?.messages?.[0];
+ // REUPLOADING: the media expired and the phone is re-uploading it; it cannot be downloaded now.
+ if (!msg || !msg.mediaData || msg.mediaData.mediaStage === 'REUPLOADING') return null;
+ if (msg.mediaData.mediaStage !== 'RESOLVED') {
+ await msg.downloadMedia({ downloadEvenIfExpensive: true, rmrReason: 1 });
+ }
+ if (msg.mediaData.mediaStage.includes('ERROR') || msg.mediaData.mediaStage === 'FETCHING') return undefined;
+ try {
+ const noopQpl = {
+ addAnnotations() {
+ return this;
+ },
+ addPoint() {
+ return this;
+ },
+ };
+ const decrypted = await w.require('WAWebDownloadManager').downloadManager.downloadAndMaybeDecrypt({
+ directPath: msg.directPath,
+ encFilehash: msg.encFilehash,
+ filehash: msg.filehash,
+ mediaKey: msg.mediaKey,
+ mediaKeyTimestamp: msg.mediaKeyTimestamp,
+ type: msg.type,
+ mimetype: msg.mimetype,
+ signal: new AbortController().signal,
+ downloadQpl: noopQpl,
+ });
+ const meta = { mimetype: msg.mimetype, filename: msg.filename, sizeBytes: decrypted.byteLength };
+ if (meta.sizeBytes > args.maxBytes) return { ...meta, data: '' };
+ return { ...meta, data: await w.WWebJS.arrayBufferToBase64Async(decrypted) };
+ } catch (e) {
+ if ((e as { status?: number } | null)?.status === 404) return undefined;
+ throw e;
+ }
+}
+
+/** Download a message's media through {@link downloadMediaInPage}, on the page that delivered it. */
+export async function downloadCappedMedia(
+ msg: Message,
+ maxBytes: number,
+): Promise<PageMediaDownload | null | undefined> {
+ const { pupPage } = (
+ msg as unknown as {
+ client: { pupPage: { evaluate: <T, A>(fn: (arg: A) => Promise<T>, arg: A) => Promise<T> } };
+ }
+ ).client;
+ return pupPage.evaluate(downloadMediaInPage, { msgId: readWid(msg.id) ?? '', maxBytes });
+}
+
/**
* Whether a MediaInput's string `data` is an http(s) URL (to be fetched through the SSRF-guarded
* loadRemoteMedia) rather than base64. Case-insensitive, matching the Baileys adapter — a mixed-case
diff --git a/src/engine/docs-29-counts.spec.ts b/src/engine/docs-29-counts.spec.ts
index f282c1aff..ef39d7716 100644
--- a/src/engine/docs-29-counts.spec.ts
+++ b/src/engine/docs-29-counts.spec.ts
@@ -163,6 +163,12 @@ describe('docs/29 counts match the capability matrix', () => {
else if (WORDS[spelled[1]] !== expected.total) {
wrongProse.push(`29.3 opening: says ${spelled[1]}, scripts/ has ${expected.total}`);
}
+ // docs/12's missing-patch entry restates the same total in words.
+ const faq = read('docs', '12-troubleshooting-faq.md').match(/OpenWA applies (\w+) exact source transforms/);
+ if (!faq) wrongProse.push('docs/12 missing-patch cause: phrasing no longer found in the document');
+ else if (WORDS[faq[1]] !== expected.total) {
+ wrongProse.push(`docs/12 missing-patch cause: says ${faq[1]}, scripts/ has ${expected.total}`);
+ }
const claims: { label: string; re: RegExp; want: number }[] = [
{ label: 'intro total', re: /(\d+) install-time patches \(29\.3\)/, want: expected.total },