Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(proxy): send SOCKS4 and caller-supplied URL fetches through the session proxy
Yudhi Armyndharis58fb7c94640e
diff --git a/.env.example b/.env.exampleindex 1e22f7d18..a7ffc6e2e 100644--- a/.env.example+++ b/.env.example@@ -476,6 +476,12 @@ WEBHOOK_SSRF_PROTECT=true# download holds memory up to MEDIA_DOWNLOAD_MAX_BYTES; this bounds N. Unset takes the default; a# value that is not a positive integer fails the boot.# INBOUND_MEDIA_CONCURRENCY=4 # default 4+# Fetch a caller-supplied URL (a media URL passed to a send or to POST /media/convert, and the link+# preview of a text send) through the egress proxy of the session the request names. ON by default,+# so the destination sees the same address as the rest of that session's traffic. Set to false when+# the proxy is a WhatsApp-only route that cannot reach arbitrary media hosts: those fetches then+# leave from the gateway's own address again. Sessions without a proxy are unaffected either way.+# SESSION_PROXY_URL_FETCH=true# ---------------------------------------------------------------------------# Server-side media conversion (opt-in)diff --git a/CHANGELOG.md b/CHANGELOG.mdindex e84f4aec4..2fa43afb3 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Security++- Baileys sessions with a SOCKS4 proxy fetch through it instead of connecting direct: inbound media, the WhatsApp Web version lookup, the initial-sync payloads and a product card's image URL, which 0.23.5 routed through HTTP, HTTPS and SOCKS5 proxies only ([#1626](https://github.com/rmyndharis/OpenWA/issues/1626)).+- A media URL passed to a send route or to `POST /api/sessions/{sessionId}/media/convert`, and the link preview of a text send, are fetched through the named session's egress proxy on both engines, instead of leaving from the gateway's own address ([#1626](https://github.com/rmyndharis/OpenWA/issues/1626)).++### Changed++- Credentials on a `socks4://` session proxy are reported at session start as unauthenticatable: SOCKS4 sends the user name as the connect request's user id and drops the password.++### Upgrade notes (behavior changes)++- A caller-supplied URL leaves through the session proxy from this release. Set `SESSION_PROXY_URL_FETCH=false` when a session proxy is a WhatsApp-only route that cannot reach arbitrary media hosts.+## [0.23.5] - 2026-09-15### Securitydiff --git a/docker-compose.dev.yml b/docker-compose.dev.ymlindex b5857e463..facfe843f 100644--- a/docker-compose.dev.yml+++ b/docker-compose.dev.yml@@ -137,6 +137,7 @@ services:- MEDIA_DOWNLOAD_MAX_BYTES=${MEDIA_DOWNLOAD_MAX_BYTES:-}- MEDIA_DOWNLOAD_TIMEOUT_MS=${MEDIA_DOWNLOAD_TIMEOUT_MS:-}- INBOUND_MEDIA_CONCURRENCY=${INBOUND_MEDIA_CONCURRENCY:-}+ - SESSION_PROXY_URL_FETCH=${SESSION_PROXY_URL_FETCH:-}- MEDIA_CONVERSION_ENABLED=${MEDIA_CONVERSION_ENABLED:-}- FFMPEG_PATH=${FFMPEG_PATH:-}- MEDIA_CONVERSION_TIMEOUT_MS=${MEDIA_CONVERSION_TIMEOUT_MS:-}diff --git a/docker-compose.yml b/docker-compose.ymlindex ed008a12e..31a9eb1c6 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -211,6 +211,7 @@ services:- MEDIA_DOWNLOAD_MAX_BYTES=${MEDIA_DOWNLOAD_MAX_BYTES:-}- MEDIA_DOWNLOAD_TIMEOUT_MS=${MEDIA_DOWNLOAD_TIMEOUT_MS:-}- INBOUND_MEDIA_CONCURRENCY=${INBOUND_MEDIA_CONCURRENCY:-}+ - SESSION_PROXY_URL_FETCH=${SESSION_PROXY_URL_FETCH:-}# Server-side media conversion (opt-in). The image ships ffmpeg, but without these forwards# the feature could not be switched on from .env at all.- MEDIA_CONVERSION_ENABLED=${MEDIA_CONVERSION_ENABLED:-}diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex 042e57eca..da442584d 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -552,13 +552,22 @@ network cannot reach WhatsApp directly. Set `proxyUrl`/`proxyType` on the same r> WebSocket never connects, **no QR code is ever delivered**, and `POST /api/sessions/:sessionId/start`> returns `504 Gateway Timeout` after ~30s. Leave `proxyUrl` unset unless you genuinely need a proxy.-On the Baileys engine, with `socks5`, `http` or `https`, the proxy also carries everything the engine fetches-over HTTP: inbound media, the WhatsApp Web version lookup, the history-sync and app-state payloads of the-initial sync, and a product card's `imageUrl`. A `socks4` proxy carries the WebSocket and media uploads only,-because the HTTP client has no SOCKS4 transport: inbound media is not downloaded (it arrives as the omitted-marker) and the WhatsApp Web version is not looked up remotely, while the initial-sync payloads and a product-card's `imageUrl` are still fetched directly. On every proxy scheme, a media URL you pass to a send or to-`POST /api/media/convert` is fetched by the gateway itself, directly, not through the session proxy.+On the Baileys engine the proxy carries everything the engine fetches over HTTP, on all four schemes: inbound+media, the WhatsApp Web version lookup, the history-sync and app-state payloads of the initial sync, and a+product card's `imageUrl`. SOCKS4 has no authentication step, so credentials in a `socks4://` URL are not a+login: the user name travels as the connect request's user id and the password is dropped, which a warning+says at session start. Use `socks5`, `http` or `https` for a proxy that needs a password.++A URL **you** supply is fetched through the session proxy too, on both engines: the media URL of a send, the+`url` of `POST /api/sessions/:sessionId/media/convert/voice|video`, and the link preview of a text send. The+session named in the request decides which proxy that is: the one its running engine started with, or, when+the session is not running, the one stored on its row. Set `SESSION_PROXY_URL_FETCH=false` to fetch those URLs+from the gateway's own address instead, for a proxy that only routes to WhatsApp. The SSRF guard applies+either way: the scheme and the destination are checked before any socket is opened, and the checked addresses+are what a SOCKS proxy is asked to connect to, in resolver order, so a proxy that routes only one address+family still reaches a dual-stack host (a `socks4` proxy is always given an IPv4 one, the only family that+protocol carries). Behind an HTTP or HTTPS proxy the destination is named in the `CONNECT` line and resolved+by the proxy, so the connection there cannot be pinned to the address that was vetted.**Response** `201`@@ -6365,6 +6374,11 @@ endpoints run — on a source install it must be present, or they answer `503`.Nothing is converted implicitly: sends behave exactly as before unless a caller runs media throughthese endpoints first and posts the result.+A `url` is fetched by the gateway through the egress proxy of the session in the path, exactly as a+send by URL is (see "Per-session egress proxy" under `POST /api/sessions`); `SESSION_PROXY_URL_FETCH=false`+sends it direct instead. ffmpeg never sees the URL either way: it is handed bytes this gateway already+fetched and checked.+> **Why voice conversion matters.** WhatsApp renders a playable voice-note bubble only for Ogg/Opus.> Posting MP3 bytes to `send-audio` with `ptt: true` sends those bytes as they are, so the recipient> gets a mic bubble that will not play. Converting first is what produces a real voice note.diff --git a/docs/14-migration-guide.md b/docs/14-migration-guide.mdindex e1d9f0380..3125d4695 100644--- a/docs/14-migration-guide.md+++ b/docs/14-migration-guide.md@@ -746,6 +746,7 @@ docker compose run --rm openwa-api npm run migration:run:prod| Release | Change | Action || -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `0.23.6` | A media URL passed to a send route or to `POST /media/convert`, and the link preview of a text send, are fetched through the egress proxy of the session named in the request instead of leaving from the gateway's own address | Set `SESSION_PROXY_URL_FETCH=false` if a session proxy is a WhatsApp-only route that cannot reach arbitrary media hosts || `0.23.0` | Typed SDK clients: `markRead` and `subscribePresence` each take their own request type instead of the shared `MarkChatRequest`, which now serves `markUnread` alone | Go and Java: swap the type at both call sites. Typed Python: only at `markRead`, its `subscribePresence` body being structurally identical. JavaScript and PHP need no change; the wire body is unchanged || `0.22.0` | Baileys refuses a reply whose quoted id, or a forward whose `fromChatId`, does not name the addressed chat, with the `404` whatsapp-web.js already answered; leaving a group, unsubscribing from a channel and labelling a channel surface WhatsApp's refusal; membership requests for an id that is not a group are refused | Handle a refusal on those six calls, which previously answered `200` whatever happened || `0.22.0` | Typed SDK clients narrow their request bodies: 19 Python request types mark the fields the server requires, and Go and Java type the proxy scheme, call kind, membership method, chat state, pin window and status font as enums | Pass the named constants instead of bare strings or numbers and supply every required field; untyped callers are unaffected |diff --git a/package-lock.json b/package-lock.jsonindex d787cac11..8e0ed25bb 100644--- a/package-lock.json+++ b/package-lock.json@@ -46,6 +46,7 @@"rxjs": "^7.8.1","sharp": "^0.35.4","socket.io": "^4.8.3",+ "socks": "^2.8.7","socks-proxy-agent": "^10.1.0","tar-stream": "3.2.0","typeorm": "^1.1.1",@@ -4081,6 +4082,7 @@"version": "0.11.0","resolved": "https://registry.npmjs.org/@pkgjs/parseargs/-/parseargs-0.11.0.tgz","integrity": "sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==",+ "dev": true,"license": "MIT","optional": true,"engines": {diff --git a/package.json b/package.jsonindex 8931da433..703ddf3c4 100644--- a/package.json+++ b/package.json@@ -103,6 +103,7 @@"rxjs": "^7.8.1","sharp": "^0.35.4","socket.io": "^4.8.3",+ "socks": "^2.8.7","socks-proxy-agent": "^10.1.0","tar-stream": "3.2.0","typeorm": "^1.1.1",diff --git a/src/common/media/load-remote-media.spec.ts b/src/common/media/load-remote-media.spec.tsindex f4439d219..6bec2dbc9 100644--- a/src/common/media/load-remote-media.spec.ts+++ b/src/common/media/load-remote-media.spec.ts@@ -36,14 +36,14 @@ describe('loadRemoteMediaBuffer', () => {it('blocks an internal URL via the SSRF guard before any fetch', async () => {const fetchMock = undiciFetch as jest.Mock;- await expect(loadRemoteMediaBuffer('http://127.0.0.1/x.png')).rejects.toBeInstanceOf(SsrfBlockedError);+ await expect(loadRemoteMediaBuffer('http://127.0.0.1/x.png', undefined)).rejects.toBeInstanceOf(SsrfBlockedError);expect(fetchMock).not.toHaveBeenCalled();});it('fetches a public URL and returns the bytes + content-type', async () => {const fetchMock = undiciFetch as jest.Mock;fetchMock.mockResolvedValue(fakeResponse([1, 2, 3], { 'content-type': 'image/png', 'content-length': '3' }));- const res = await loadRemoteMediaBuffer('http://8.8.8.8/x.png');+ const res = await loadRemoteMediaBuffer('http://8.8.8.8/x.png', undefined);expect(res.mimetype).toBe('image/png');expect(Array.from(res.data)).toEqual([1, 2, 3]);// Never follow redirects (a 3xx could reach an internal host the guard never validated).@@ -53,6 +53,6 @@ describe('loadRemoteMediaBuffer', () => {it('rejects a body that exceeds the byte cap', async () => {process.env.MEDIA_DOWNLOAD_MAX_BYTES = '2';(undiciFetch as jest.Mock).mockResolvedValue(fakeResponse([1, 2, 3], { 'content-type': 'image/png' }));- await expect(loadRemoteMediaBuffer('http://8.8.8.8/x.png')).rejects.toThrow(/exceeds/i);+ await expect(loadRemoteMediaBuffer('http://8.8.8.8/x.png', undefined)).rejects.toThrow(/exceeds/i);});});diff --git a/src/common/media/load-remote-media.ts b/src/common/media/load-remote-media.tsindex 6288bffd4..2fdac30fa 100644--- a/src/common/media/load-remote-media.ts+++ b/src/common/media/load-remote-media.ts@@ -1,4 +1,5 @@import { withSafeFetch } from '../security/ssrf-guard';+import { urlFetchProxy } from '../security/proxy-dispatcher';/** Default cap on a server-side media download: 50 MiB (overridable via MEDIA_DOWNLOAD_MAX_BYTES). */const DEFAULT_MEDIA_MAX_BYTES = 50 * 1024 * 1024;@@ -24,45 +25,58 @@ function positiveIntFromEnv(name: string, fallback: number): number {* or wrong) to bound memory use.** Engine-neutral: returns raw bytes + the response content-type, so any engine adapter can use it.+ *+ * `sessionProxyUrl` is the egress proxy of the session the fetch is attributed to, or undefined for+ * a direct one. It is required rather than optional so a new call site cannot leave a proxied+ * session's fetch going direct by omission; `urlFetchProxy` applies the operator's opt-out.*/-export async function loadRemoteMediaBuffer(url: string): Promise<{ data: Buffer; mimetype: string }> {+export async function loadRemoteMediaBuffer(+ url: string,+ sessionProxyUrl: string | undefined,+): Promise<{ data: Buffer; mimetype: string }> {const maxBytes = positiveIntFromEnv('MEDIA_DOWNLOAD_MAX_BYTES', DEFAULT_MEDIA_MAX_BYTES);const timeoutMs = positiveIntFromEnv('MEDIA_DOWNLOAD_TIMEOUT_MS', DEFAULT_MEDIA_TIMEOUT_MS);// Always guarded (media SSRF is independent of the webhook opt-out); withSafeFetch validates the// host, pins the connection to the vetted IP, and refuses redirects. The streaming cap runs inside// the callback so the connection stays open for the body read and is torn down right after.- return withSafeFetch(url, { signal: AbortSignal.timeout(timeoutMs) }, async response => {- if (!response.ok) {- throw new Error(`Media fetch failed with status ${response.status}`);- }-- const declaredLength = Number(response.headers.get('content-length') ?? '');- if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {- throw new Error(`Media exceeds the ${maxBytes}-byte limit`);- }+ const proxyUrl = urlFetchProxy(sessionProxyUrl);+ return withSafeFetch(+ url,+ { signal: AbortSignal.timeout(timeoutMs) },+ async response => {+ if (!response.ok) {+ throw new Error(`Media fetch failed with status ${response.status}`);+ }- const reader = response.body?.getReader();- if (!reader) {- throw new Error('Media response has no body');- }+ const declaredLength = Number(response.headers.get('content-length') ?? '');+ if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {+ throw new Error(`Media exceeds the ${maxBytes}-byte limit`);+ }- const chunks: Buffer[] = [];- let total = 0;- for (;;) {- const { done, value } = (await reader.read()) as { done: boolean; value: Uint8Array };- if (done) {- break;+ const reader = response.body?.getReader();+ if (!reader) {+ throw new Error('Media response has no body');}- total += value.byteLength;- if (total > maxBytes) {- await reader.cancel();- throw new Error(`Media exceeds the ${maxBytes}-byte limit`);++ const chunks: Buffer[] = [];+ let total = 0;+ for (;;) {+ const { done, value } = (await reader.read()) as { done: boolean; value: Uint8Array };+ if (done) {+ break;+ }+ total += value.byteLength;+ if (total > maxBytes) {+ await reader.cancel();+ throw new Error(`Media exceeds the ${maxBytes}-byte limit`);+ }+ chunks.push(Buffer.from(value));}- chunks.push(Buffer.from(value));- }- const mimetype = (response.headers.get('content-type') ?? '').split(';')[0].trim();- return { data: Buffer.concat(chunks), mimetype };- });+ const mimetype = (response.headers.get('content-type') ?? '').split(';')[0].trim();+ return { data: Buffer.concat(chunks), mimetype };+ },+ { proxyUrl },+ );}diff --git a/src/common/security/proxy-dispatcher.spec.ts b/src/common/security/proxy-dispatcher.spec.tsnew file mode 100644index 000000000..bc660a566--- /dev/null+++ b/src/common/security/proxy-dispatcher.spec.ts@@ -0,0 +1,214 @@+import * as http from 'http';+import * as net from 'net';+import type { AddressInfo } from 'net';+import { Dispatcher1Wrapper, fetch as undiciFetch } from 'undici';+import { createProxyDispatcher, hasUnauthenticatableSocks4Credentials, urlFetchProxy } from './proxy-dispatcher';+import { startSocks4Proxy, startSocks5Proxy, type SocksProxyServer } from '../../../test/helpers/socks-proxy-servers';++/**+ * The session proxy carries every fetch the gateway makes for a session: Baileys' media downloads+ * and version lookup through global fetch, and a caller-supplied URL through undici's own. Both are+ * exercised here against REAL proxies, so a dispatcher that merely looks right fails.+ *+ * An https destination is judged by what reaches the tunnelled socket rather than by a completed+ * handshake: the repository ships no certificate to serve, and the claim that matters is that the+ * TLS ClientHello travels through the proxy rather than around it.+ */++const listen = async <T extends net.Server>(server: T): Promise<T> => {+ await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve));+ return server;+};+const portOf = (server: net.Server): number => (server.address() as AddressInfo).port;+const close = (server: net.Server): Promise<void> => new Promise(resolve => server.close(() => resolve()));++describe('createProxyDispatcher', () => {+ it('returns a dispatcher for every scheme the session proxy validator accepts', () => {+ for (const url of [+ 'http://u:[email protected]:8080',+ 'https://proxy.example:443',+ 'socks4://proxy.example:1080',+ 'socks5://proxy.example:1080',+ ]) {+ expect(createProxyDispatcher(url)).toBeInstanceOf(Dispatcher1Wrapper);+ }+ });++ it('throws on an unsupported scheme instead of answering "go direct"', () => {+ expect(() => createProxyDispatcher('ftp://proxy.example:21')).toThrow(/unsupported proxy/i);+ });++ it('routes a global fetch through an http proxy', async () => {+ const seen: string[] = [];+ const proxy = await listen(+ http.createServer((req, res) => {+ seen.push(`${req.method} ${req.url}`);+ res.end('via proxy');+ }),+ );+ const dispatcher = createProxyDispatcher(`http://127.0.0.1:${portOf(proxy)}`);+ try {+ const response = await fetch('http://media.example.invalid/file', { dispatcher } as RequestInit);+ expect(await response.text()).toBe('via proxy');+ expect(seen).toEqual(['GET http://media.example.invalid/file']);+ } finally {+ await dispatcher.destroy();+ proxy.closeAllConnections();+ await close(proxy);+ }+ });+});++describe('createProxyDispatcher over real SOCKS proxies', () => {+ let origin: http.Server;+ let proxy: SocksProxyServer | undefined;++ beforeAll(async () => {+ origin = await listen(http.createServer((req, res) => res.end(`origin saw ${req.url}`)));+ });+ afterAll(async () => {+ origin.closeAllConnections();+ await close(origin);+ });+ afterEach(async () => {+ await proxy?.close();+ proxy = undefined;+ });++ // The proxies relay to the local origin whatever destination is asked for, so a request that went+ // around the proxy would reach nothing and fail rather than pass quietly.+ const originAnswers = async (+ proxyUrl: string,+ destination: string,+ ...pinnedAddresses: string[]+ ): Promise<string> => {+ const dispatcher = createProxyDispatcher(proxyUrl, { pinnedAddresses });+ try {+ return await (await undiciFetch(destination, { dispatcher })).text();+ } finally {+ await dispatcher.destroy();+ }+ };++ it.each(['socks4', 'socks5'] as const)('fetches an http destination through a %s proxy', async scheme => {+ const start = scheme === 'socks4' ? startSocks4Proxy : startSocks5Proxy;+ proxy = await start({ relayTo: portOf(origin) });++ expect(await originAnswers(proxy.url, 'http://203.0.113.7/file')).toBe('origin saw /file');+ expect(proxy.destinations).toHaveLength(1);+ });++ it.each(['socks4', 'socks5'] as const)('tunnels an https destination through a %s proxy', async scheme => {+ const start = scheme === 'socks4' ? startSocks4Proxy : startSocks5Proxy;+ // Relayed to a listener that speaks no TLS and hangs up on the ClientHello: completing a+ // handshake is not the claim, and the repository ships no certificate to serve one with.+ const tcpOnly = await listen(net.createServer(socket => socket.once('data', () => socket.destroy())));+ proxy = await start({ relayTo: portOf(tcpOnly) });+ try {+ await expect(originAnswers(proxy.url, 'https://203.0.113.7/file', '203.0.113.7')).rejects.toThrow();+ expect(proxy.destinations).toEqual(['203.0.113.7:443']);+ expect(proxy.firstBytes).toEqual(['160301']); // TLS 1.x ClientHello record header+ } finally {+ tcpOnly.close();+ }+ });++ // SOCKS4 has no hostname form, so the destination is resolved here before the request goes out;+ // SOCKS5 keeps the name, letting the proxy's own resolver decide.+ it('resolves the destination locally for socks4 and keeps the hostname for socks5', async () => {+ proxy = await startSocks4Proxy({ relayTo: portOf(origin) });+ await originAnswers(proxy.url, `http://localhost:${portOf(origin)}/four`);+ // The resolved address itself, not merely its shape: the SOCKS4a form a strict proxy rejects+ // also puts four IP octets on the wire (0.0.0.x, with the name trailing), so asserting "is an+ // IPv4 address" would hold even if the hostname had been handed over.+ expect(proxy.destinations).toEqual([`127.0.0.1:${portOf(origin)}`]);+ await proxy.close();++ proxy = await startSocks5Proxy({ relayTo: portOf(origin) });+ await originAnswers(proxy.url, `http://localhost:${portOf(origin)}/five`);+ expect(proxy.destinations).toEqual([`localhost:${portOf(origin)}`]);+ });++ it('refuses an IPv6 destination on socks4, which cannot carry one', async () => {+ proxy = await startSocks4Proxy({ relayTo: portOf(origin) });+ await expect(originAnswers(proxy.url, `http://[::1]:${portOf(origin)}/x`)).rejects.toThrow();+ expect(proxy.destinations).toEqual([]);+ });++ // The SSRF guard resolves and vets the destination itself; passing that address on keeps the+ // connection tied to what was checked instead of letting a second resolution choose.+ it.each(['socks4', 'socks5'] as const)('sends the vetted address as the %s destination', async scheme => {+ const start = scheme === 'socks4' ? startSocks4Proxy : startSocks5Proxy;+ proxy = await start({ relayTo: portOf(origin) });++ // The URL names one address and the guard vetted another, so only the vetted one may be dialled.+ await originAnswers(proxy.url, 'http://203.0.113.8/file', '203.0.113.7');++ expect(proxy.destinations).toEqual(['203.0.113.7:80']);+ });++ // A vetted list is family-mixed in resolver order, and a dual-stack host commonly resolves AAAA+ // first. Taking only its head left socks4 unable to reach any such host at all.+ it('dials the IPv4 entry of a vetted dual-stack list on socks4', async () => {+ proxy = await startSocks4Proxy({ relayTo: portOf(origin) });++ expect(+ await originAnswers(proxy.url, 'http://cdn.example/file', '2606:2800:220:1:248:1893:25c8:1946', '127.0.0.1'),+ ).toBe('origin saw /file');+ expect(proxy.destinations).toEqual(['127.0.0.1:80']);+ });++ // Same list, and a SOCKS5 proxy that has no IPv6 route of its own: the next vetted address is+ // tried, which is the failover the direct path gets from happy-eyeballs.+ it('falls back to the next vetted address when the proxy cannot reach the first', async () => {+ proxy = await startSocks5Proxy({ relayTo: portOf(origin), ipv4Only: true });++ expect(+ await originAnswers(proxy.url, 'http://cdn.example/file', '2606:2800:220:1:248:1893:25c8:1946', '127.0.0.1'),+ ).toBe('origin saw /file');+ expect(proxy.destinations).toEqual(['2606:2800:220:1:248:1893:25c8:1946:80', '127.0.0.1:80']);+ });++ it('authenticates a socks5 proxy with the decoded credentials', async () => {+ // URL credentials stay percent-encoded until they are decoded for the handshake.+ proxy = await startSocks5Proxy({ relayTo: portOf(origin), credentials: { username: 'us@er', password: 'p@ss:1' } });++ expect(await originAnswers(proxy.url, 'http://203.0.113.7/file')).toBe('origin saw /file');+ expect(proxy.credentials).toEqual(['us@er:p@ss:1']);+ });++ // SOCKS4 authenticates nobody: the user name travels as the connect request's user id and the+ // password is dropped, so the caller is warned rather than left with an opaque refusal.+ it('sends socks4 credentials as the user id, and reports them as unauthenticatable', async () => {+ proxy = await startSocks4Proxy({ relayTo: portOf(origin) });+ const credentialed = proxy.url.replace('socks4://', 'socks4://us%40er:p%40ss@');++ await originAnswers(credentialed, 'http://203.0.113.7/file');++ expect(proxy.credentials).toEqual(['us@er']);+ expect(hasUnauthenticatableSocks4Credentials(credentialed)).toBe(true);+ expect(hasUnauthenticatableSocks4Credentials(proxy.url)).toBe(false);+ expect(hasUnauthenticatableSocks4Credentials('socks5://us:[email protected]:1080')).toBe(false);+ });+});++describe('urlFetchProxy', () => {+ afterEach(() => delete process.env.SESSION_PROXY_URL_FETCH);++ it('routes a caller-supplied URL through the session proxy by default', () => {+ expect(urlFetchProxy('socks5://proxy.example:1080')).toBe('socks5://proxy.example:1080');+ process.env.SESSION_PROXY_URL_FETCH = 'true';+ expect(urlFetchProxy('socks5://proxy.example:1080')).toBe('socks5://proxy.example:1080');+ });++ it('fetches direct when the operator switches it off', () => {+ process.env.SESSION_PROXY_URL_FETCH = 'false';+ expect(urlFetchProxy('socks5://proxy.example:1080')).toBeUndefined();+ });++ it('leaves an unproxied session alone either way', () => {+ expect(urlFetchProxy(undefined)).toBeUndefined();+ process.env.SESSION_PROXY_URL_FETCH = 'false';+ expect(urlFetchProxy(undefined)).toBeUndefined();+ });+});diff --git a/src/common/security/proxy-dispatcher.ts b/src/common/security/proxy-dispatcher.tsnew file mode 100644index 000000000..229a4722e--- /dev/null+++ b/src/common/security/proxy-dispatcher.ts@@ -0,0 +1,166 @@+import { isIP, type Socket } from 'net';+import { lookup } from 'dns/promises';+import { SocksClient, type SocksProxy } from 'socks';+import { Agent, Dispatcher1Wrapper, ProxyAgent, buildConnector, type Dispatcher } from 'undici';++/** Ports assumed when the destination URL names none, per scheme. */+const DEFAULT_DESTINATION_PORTS: Record<string, number> = { 'https:': 443, 'http:': 80 };++/** Conventional SOCKS port (RFC 1928 section 3), used when the proxy URL names none. */+const DEFAULT_SOCKS_PORT = 1080;++export interface ProxyDispatcherOptions {+ /**+ * The destination addresses the SSRF guard already resolved and vetted, in resolver order.+ * Honoured by the SOCKS schemes, which carry the destination themselves, so the address that was+ * checked is the one connected to and a DNS rebind cannot swap it. The whole list is kept, and+ * dialled in order, because it is family-mixed: a dual-stack host commonly resolves AAAA first,+ * and neither a SOCKS4 proxy (which has no IPv6 form) nor an IPv4-only SOCKS5 proxy can reach+ * that first entry, while the direct path just falls through to the next address. An HTTP/HTTPS+ * proxy is asked for the destination by NAME in the CONNECT line and resolves it itself, so there+ * the value is ignored: pinning through such a proxy is not expressible in the protocol.+ */+ pinnedAddresses?: string[];+}++/**+ * The destination addresses to put on the wire for a SOCKS request, in the order they are tried.+ *+ * SOCKS5 keeps the HOSTNAME when nothing was vetted: the proxy resolves it, which is usually the+ * point of routing through one (the destination is resolved, and reachable, from the proxy's network+ * rather than ours). SOCKS4 has no hostname form at all (the SOCKS4a extension invented one, and a+ * strict SOCKS4 proxy rejects it), so a name is resolved here, to IPv4, the only family the protocol+ * can carry, and a vetted list is narrowed to its IPv4 entries. Note this differs from+ * `socks-proxy-agent`, which the session's WebSocket agent uses: it resolves locally for `socks5://`+ * too, keeping the name only for `socks5h://`, a spelling this gateway's proxy validator does not+ * accept.+ */+async function socksDestinations(type: 4 | 5, hostname: string, pinnedAddresses?: string[]): Promise<string[]> {+ const hosts = pinnedAddresses?.length ? pinnedAddresses : [hostname.replace(/^\[|\]$/g, '')]; // strip IPv6 brackets+ if (type === 5) {+ return hosts;+ }+ const ipv4 = hosts.filter(host => isIP(host) === 4);+ if (ipv4.length > 0) {+ return ipv4;+ }+ // Every vetted entry is an IP literal, so no IPv4 among them means they are all IPv6.+ if (isIP(hosts[0]) === 6) {+ throw new Error(`A SOCKS4 proxy cannot reach the IPv6 destination ${hosts.join(', ')}`);+ }+ return [(await lookup(hosts[0], { family: 4 })).address];+}++/**+ * Open a tunnel to the first destination the proxy can reach.+ *+ * The vetted addresses are family-mixed in resolver order, so a proxy with no route to the first+ * family would otherwise sink a request the direct path completes by trying the next address.+ */+async function connectThroughSocks(proxy: SocksProxy, hosts: string[], port: number): Promise<Socket> {+ let lastError = new Error('No destination address to reach through the SOCKS proxy');+ for (const host of hosts) {+ try {+ const { socket } = await SocksClient.createConnection({ proxy, command: 'connect', destination: { host, port } });+ return socket;+ } catch (error) {+ lastError = error as Error;+ }+ }+ throw lastError;+}++/**+ * undici connector that opens each connection through a SOCKS4 or SOCKS5 proxy.+ *+ * undici has no SOCKS4 transport and ships SOCKS5 as an experimental agent that hands the proxy the+ * URL's still-percent-encoded credentials; one connector over the `socks` package covers both+ * schemes and authenticates SOCKS5 with the decoded pair. For an https destination the tunnelled+ * socket is handed to undici's own connector for the TLS upgrade: the request options pass through+ * untouched, so SNI and certificate validation still use the destination hostname, not the proxy's.+ */+function socksConnector(proxyUrl: URL, pinnedAddresses?: string[]): buildConnector.connector {+ const type = proxyUrl.protocol === 'socks4:' ? 4 : 5;+ // SOCKS4 has no authentication: `socks` sends the user id in the connect request and drops the+ // password. Credentials are decoded here because URL keeps them percent-encoded.+ const proxy: SocksProxy = {+ host: proxyUrl.hostname,+ port: Number(proxyUrl.port) || DEFAULT_SOCKS_PORT,+ type,+ userId: decodeURIComponent(proxyUrl.username) || undefined,+ password: decodeURIComponent(proxyUrl.password) || undefined,+ };+ const upgradeTls = buildConnector({});++ return (options, callback) => {+ // undici's connect callback is a plain callback, not a promise resolver, and it is answered from+ // inside open(): a throw raised after that (by the callback itself, or by the TLS upgrade) would+ // otherwise answer it a second time, with an error, on an already-connected client.+ let answered = false;+ const answer: typeof callback = (...args: Parameters<typeof callback>) => {+ if (answered) return;+ answered = true;+ callback(...args);+ };+ const open = async (): Promise<void> => {+ const socket = await connectThroughSocks(+ proxy,+ await socksDestinations(type, options.hostname, pinnedAddresses),+ Number(options.port) || DEFAULT_DESTINATION_PORTS[options.protocol] || 80,+ );+ if (options.protocol === 'https:') {+ upgradeTls({ ...options, httpSocket: socket }, answer);+ return;+ }+ answer(null, socket.setNoDelay());+ };+ open().catch((error: Error) => answer(error, null));+ };+}++/**+ * Build a fetch dispatcher that sends every request through a session's egress proxy.+ *+ * Covers all four schemes the session proxy validator accepts. The returned dispatcher is usable by+ * both undici's own `fetch` and the global one: `Dispatcher1Wrapper` adapts the installed undici to+ * the handler API of the older undici bundled in Node, and passes a modern handler straight through.+ *+ * Throws on any other scheme rather than returning a value a caller could read as "go direct": a+ * proxied session must fail loudly instead of leaving the gateway's own address on the wire.+ */+export function createProxyDispatcher(proxyUrl: string, options: ProxyDispatcherOptions = {}): Dispatcher {+ const url = new URL(proxyUrl);+ if (url.protocol === 'http:' || url.protocol === 'https:') {+ return new Dispatcher1Wrapper(new ProxyAgent(proxyUrl));+ }+ if (url.protocol === 'socks4:' || url.protocol === 'socks5:') {+ return new Dispatcher1Wrapper(new Agent({ connect: socksConnector(url, options.pinnedAddresses) }));+ }+ throw new Error(`Unsupported proxy protocol: ${url.protocol}`);+}++/**+ * The proxy a server-side fetch of a CALLER-SUPPLIED URL must leave through, given the proxy of the+ * session the request names.+ *+ * Such a fetch belongs to the request rather than to the session, so it used to leave from the+ * gateway's own address even for a proxied session (#1626): the destination saw a different IP than+ * every other byte that session sends. Routing it through the session proxy is the default.+ * `SESSION_PROXY_URL_FETCH=false` restores the direct fetch, for a deployment whose proxy is a+ * WhatsApp-only route that cannot reach arbitrary media hosts.+ */+export function urlFetchProxy(sessionProxyUrl: string | undefined): string | undefined {+ return process.env.SESSION_PROXY_URL_FETCH === 'false' ? undefined : sessionProxyUrl;+}++/**+ * Whether a proxy URL carries credentials its scheme cannot authenticate: SOCKS4 has no+ * authentication step, so `socks4://user:pass@host` sends the user name as the connect request's+ * user id and drops the password entirely. Surfaced by the caller as a warning, the way the+ * whatsapp-web.js engine already reports SOCKS credentials Chromium cannot use (#628), so a proxy+ * that answers "request rejected" is not diagnosed as an unreachable host.+ */+export function hasUnauthenticatableSocks4Credentials(proxyUrl: string): boolean {+ const url = new URL(proxyUrl);+ return url.protocol === 'socks4:' && (url.username !== '' || url.password !== '');+}diff --git a/src/common/security/ssrf-guard-session-proxy.spec.ts b/src/common/security/ssrf-guard-session-proxy.spec.tsnew file mode 100644index 000000000..a10ac0969--- /dev/null+++ b/src/common/security/ssrf-guard-session-proxy.spec.ts@@ -0,0 +1,141 @@+import * as http from 'http';+import * as net from 'net';+import type { AddressInfo } from 'net';+import { withSafeFetch } from './ssrf-guard';+import { loadRemoteMediaBuffer } from '../media/load-remote-media';+import { startSocks4Proxy, startSocks5Proxy, type SocksProxyServer } from '../../../test/helpers/socks-proxy-servers';++/**+ * A guarded fetch made for a proxied session must leave through that session's proxy on EVERY+ * branch, or the gateway's own address reaches the destination for some URLs and not others. The+ * branches are: a hostname with vetted addresses to pin, an IP literal with nothing to pin, a+ * redirect chain, and the guard switched off entirely.+ *+ * Real servers throughout: a real SOCKS5 proxy that relays every tunnel to a local origin whatever+ * destination is named, and requests aimed at TEST-NET-3 addresses, which are unroutable. A request+ * that went direct therefore fails instead of passing quietly, and one that went through the proxy+ * is answered by the origin.+ */+describe('withSafeFetch through a session proxy', () => {+ let origin: http.Server;+ let originPort: number;+ let requests: string[];+ let proxy: SocksProxyServer;+ const savedAllowedHosts = process.env.SSRF_ALLOWED_HOSTS;++ const body = (response: { text(): Promise<string> }): Promise<string> => response.text();++ beforeAll(async () => {+ origin = http.createServer((req, res) => {+ requests.push(req.url ?? '');+ if (req.url === '/moved') {+ res.writeHead(302, { location: 'http://203.0.113.9/final' });+ res.end();+ return;+ }+ res.end(`origin saw ${req.url}`);+ });+ await new Promise<void>(resolve => origin.listen(0, '127.0.0.1', resolve));+ originPort = (origin.address() as AddressInfo).port;+ });++ afterAll(async () => {+ origin.closeAllConnections();+ await new Promise<void>(resolve => origin.close(() => resolve()));+ });++ beforeEach(async () => {+ requests = [];+ proxy = await startSocks5Proxy({ relayTo: originPort });+ });++ afterEach(async () => {+ await proxy.close();+ if (savedAllowedHosts === undefined) delete process.env.SSRF_ALLOWED_HOSTS;+ else process.env.SSRF_ALLOWED_HOSTS = savedAllowedHosts;+ delete process.env.WEBHOOK_SSRF_REDIRECTS;+ });++ it('sends a vetted hostname to the proxy as the address the guard checked', async () => {+ // Allowlisted so the loopback origin passes the guard; an allowlisted host is still resolved,+ // so there IS a vetted address to pin, which is the branch under test.+ process.env.SSRF_ALLOWED_HOSTS = 'localhost';++ const text = await withSafeFetch(`http://localhost:${originPort}/named`, {}, body, { proxyUrl: proxy.url });++ expect(text).toBe('origin saw /named');+ expect(proxy.destinations).toHaveLength(1);+ expect(net.isIP(proxy.destinations[0].split(':').slice(0, -1).join(':'))).toBeGreaterThan(0);+ });++ // The guard hands over the vetted list in resolver order, which is family-mixed: a dual-stack host+ // resolves AAAA first on any gateway with IPv6 connectivity, and SOCKS4 has no IPv6 form at all.+ // Handing over only the head of that list left such a session unable to fetch any dual-stack URL.+ it('sends a socks4 proxy an IPv4 entry of a dual-stack vetted host', async () => {+ process.env.SSRF_ALLOWED_HOSTS = 'localhost';+ const socks4 = await startSocks4Proxy({ relayTo: originPort });++ try {+ const text = await withSafeFetch(`http://localhost:${originPort}/dual`, {}, body, { proxyUrl: socks4.url });++ expect(text).toBe('origin saw /dual');+ expect(socks4.destinations).toEqual([`127.0.0.1:${originPort}`]);+ } finally {+ await socks4.close();+ }+ });++ // An IP literal leaves the guard with nothing to pin, which used to mean "no dispatcher": exactly+ // the branch where a proxied session's fetch would have gone direct.+ it('proxies an IP-literal URL, which has no resolved target to pin', async () => {+ const text = await withSafeFetch('http://203.0.113.7/literal', {}, body, { proxyUrl: proxy.url });++ expect(text).toBe('origin saw /literal');+ expect(proxy.destinations).toEqual(['203.0.113.7:80']);+ });++ // Turning the SSRF guard off says nothing about which address the request may leave from.+ it('proxies an unguarded fetch', async () => {+ const text = await withSafeFetch('http://203.0.113.7/unguarded', {}, body, {+ proxyUrl: proxy.url,+ guard: false,+ });++ expect(text).toBe('origin saw /unguarded');+ expect(proxy.destinations).toEqual(['203.0.113.7:80']);+ });++ it('proxies every hop of a followed redirect chain', async () => {+ const text = await withSafeFetch('http://203.0.113.7/moved', {}, body, {+ proxyUrl: proxy.url,+ followRedirects: true,+ });++ expect(text).toBe('origin saw /final');+ expect(proxy.destinations).toEqual(['203.0.113.7:80', '203.0.113.9:80']);+ });++ // The media loader is the path a send-by-URL and POST /media/convert both take.+ it('fetches caller-supplied media through the proxy', async () => {+ const media = await loadRemoteMediaBuffer('http://203.0.113.7/photo.png', proxy.url);++ expect(media.data.toString()).toBe('origin saw /photo.png');+ expect(proxy.destinations).toEqual(['203.0.113.7:80']);+ });++ it('fails the fetch rather than going direct when the proxy value is unusable', async () => {+ await expect(+ withSafeFetch('http://203.0.113.7/literal', {}, body, { proxyUrl: 'ftp://proxy.example:21' }),+ ).rejects.toThrow(/unsupported proxy/i);+ expect(requests).toEqual([]);+ });++ it('leaves an unproxied fetch exactly as it was: direct, and never near the proxy', async () => {+ process.env.SSRF_ALLOWED_HOSTS = 'localhost';++ const text = await withSafeFetch(`http://localhost:${originPort}/direct`, {}, body);++ expect(text).toBe('origin saw /direct');+ expect(proxy.destinations).toEqual([]);+ });+});diff --git a/src/common/security/ssrf-guard.ts b/src/common/security/ssrf-guard.tsindex 5e0e25593..24ae6cd5e 100644--- a/src/common/security/ssrf-guard.ts+++ b/src/common/security/ssrf-guard.ts@@ -1,7 +1,8 @@import { BlockList, isIPv4, isIPv6, type LookupFunction } from 'net';import { lookup } from 'dns/promises';import { type LookupAddress, type LookupOptions } from 'dns';-import { Agent, fetch as undiciFetch, Headers, type RequestInit, type Response } from 'undici';+import { Agent, fetch as undiciFetch, Headers, type Dispatcher, type RequestInit, type Response } from 'undici';+import { createProxyDispatcher } from './proxy-dispatcher';/** Thrown when an outbound URL is blocked by the SSRF guard. */export class SsrfBlockedError extends Error {@@ -449,13 +450,43 @@ function nextRedirectHopInit(init: RequestInit, status: number, nextUrl: string,return next;}+/**+ * The dispatcher one guarded request rides, destroyed by the caller once the request settles.+ *+ * With a session proxy the request leaves through it, whatever the guard decided: the proxy is the+ * session's egress and a fetch that quietly went direct would put the gateway's own address on the+ * wire (#1626). What the guard can still enforce there is narrower than on the direct path, and+ * worth stating exactly:+ *+ * - The scheme check and the blocked-address check on the URL itself run unchanged, so `file:`,+ * `http://169.254.169.254/` and a name resolving into a reserved range are refused before any+ * socket is opened, proxy or not.+ * - Destination PINNING survives only through SOCKS, which carries the destination address in the+ * request. The whole vetted list goes over, to be dialled in order, so the address-family failover+ * the direct path gets from happy-eyeballs is not lost to a proxy that can route only one of them.+ * An HTTP/HTTPS proxy is handed the destination by name in the CONNECT line and resolves it with+ * its own resolver, so the vetted address cannot be expressed and a DNS rebind between check and+ * connect is not structurally preventable.+ *+ * Without a proxy the behaviour is byte-identical to before: the pinned `Agent` for a vetted+ * hostname, and no dispatcher at all for an IP literal or an unguarded fetch.+ */+function requestDispatcher(proxyUrl: string | undefined, target: LookupAddress[] | null): Dispatcher | undefined {+ if (proxyUrl) {+ return createProxyDispatcher(proxyUrl, { pinnedAddresses: target?.map(({ address }) => address) });+ }+ return target ? new Agent({ connect: { lookup: pinnedLookup(target) } }) : undefined;+}+/*** Perform an SSRF-safe fetch and hand the response to `use`, then tear down the per-request* connection. The host is validated and resolved ONCE; the connection is pinned to the vetted IP(s)* via an undici dispatcher so it cannot be re-resolved to an internal address between check and* connect (DNS-rebinding TOCTOU). The original hostname is preserved for TLS SNI and the Host header,* so virtual hosting and certificate validation are unaffected, and ALL vetted addresses are offered- * so A-record failover still works. Redirects are refused (the guard only validated the original host).+ * so A-record failover still works (behind a SOCKS proxy the same list is dialled in order, and+ * behind an HTTP/HTTPS proxy the CONNECT line carries the name for the proxy to resolve). Redirects+ * are refused (the guard only validated the original host).** `use` must read everything it needs from the response before returning — the dispatcher (and its* sockets) is destroyed once `use` settles, so a still-streaming body would be cut off. Unread@@ -464,20 +495,33 @@ function nextRedirectHopInit(init: RequestInit, status: number, nextUrl: string,** @param opts.guard - when false (the WEBHOOK_SSRF_PROTECT opt-out), skips validation/pinning and* performs a plain redirect-following fetch. Defaults to true (always guard).+ * @param opts.proxyUrl - the egress proxy every request of this fetch must leave through; see+ * {@link requestDispatcher} for what the guard can still enforce behind one.*/export async function withSafeFetch<T>(rawUrl: string,init: RequestInit,use: (response: Response) => Promise<T> | T,- opts: { guard?: boolean; followRedirects?: boolean } = {},+ opts: { guard?: boolean; followRedirects?: boolean; proxyUrl?: string } = {},): Promise<T> {const guard = opts.guard ?? true;if (!guard) {// Redirect-following is a separate decision from SSRF protection: an operator who disabled the// guard (closed network) did not opt into chasing 3xx chains to arbitrary hosts. Fail loudly// unless WEBHOOK_SSRF_REDIRECTS=true says otherwise.+ //+ // The proxy still applies: turning the guard off says nothing about which address the request+ // may leave from, so an unguarded fetch for a proxied session is proxied too.const follow = process.env.WEBHOOK_SSRF_REDIRECTS === 'true';- return useAndSettleBody(await undiciFetch(rawUrl, { ...init, redirect: follow ? 'follow' : 'error' }), use);+ const dispatcher = requestDispatcher(opts.proxyUrl, null);+ try {+ return await useAndSettleBody(+ await undiciFetch(rawUrl, { ...init, redirect: follow ? 'follow' : 'error', dispatcher }),+ use,+ );+ } finally {+ if (dispatcher) await dispatcher.destroy().catch(() => undefined);+ }}if (opts.followRedirects) {@@ -503,7 +547,7 @@ export async function withSafeFetch<T>(throw new Error(`Refusing redirect that downgrades from https to http: ${currentUrl}`);}if (current.protocol === 'https:') sawSecureHop = true;- const dispatcher = target ? new Agent({ connect: { lookup: pinnedLookup(target) } }) : undefined;+ const dispatcher = requestDispatcher(opts.proxyUrl, target);try {const response = await undiciFetch(currentUrl, { ...hopInit, redirect: 'manual', dispatcher });if (!REDIRECT_STATUSES.has(response.status)) {@@ -529,7 +573,7 @@ export async function withSafeFetch<T>(}const target = await resolveSafeFetchTarget(rawUrl, init.signal);- const dispatcher = target ? new Agent({ connect: { lookup: pinnedLookup(target) } }) : undefined;+ const dispatcher = requestDispatcher(opts.proxyUrl, target);try {const response = await undiciFetch(rawUrl, { ...init, redirect: 'manual', dispatcher });try {diff --git a/src/config/env-precedence.ts b/src/config/env-precedence.tsindex 702c6d4e9..3a89a6be7 100644--- a/src/config/env-precedence.ts+++ b/src/config/env-precedence.ts@@ -31,6 +31,8 @@ export const BLANK_SHADOWED_ENV_KEYS: string[] = ['MEDIA_DOWNLOAD_MAX_BYTES','MEDIA_DOWNLOAD_TIMEOUT_MS','INBOUND_MEDIA_CONCURRENCY',+ // Whether a caller-supplied URL is fetched through the named session's egress proxy.+ 'SESSION_PROXY_URL_FETCH',// Database selection + connection details (#488)'DATABASE_TYPE','DATABASE_HOST',diff --git a/src/config/env.validation.ts b/src/config/env.validation.tsindex 31d0cab4d..55e533694 100644--- a/src/config/env.validation.ts+++ b/src/config/env.validation.ts@@ -421,6 +421,10 @@ export function validateEnv(config: EnvConfig): EnvConfig {// the webhook payload an integrator receives is not the one the operator configured.'WEBHOOK_SSRF_PROTECT','WEBHOOK_CONTACT_DETAILS',+ // `!== 'false'`: a typo keeps caller-supplied URL fetches on the session proxy, the safe value,+ // but an operator whose proxy cannot reach arbitrary media hosts asked for the opposite and+ // would see every send-by-URL on a proxied session fail instead.+ 'SESSION_PROXY_URL_FETCH',// Engine behaviour flags: a typo leaves full-history sync off, or leaves the account marked// online on connect (#871 — it suppresses notifications on the operator's own phone).'BAILEYS_SYNC_FULL_HISTORY',diff --git a/src/engine/adapters/baileys-contacts.ts b/src/engine/adapters/baileys-contacts.tsindex f18e886f5..3f5ca807b 100644--- a/src/engine/adapters/baileys-contacts.ts+++ b/src/engine/adapters/baileys-contacts.ts@@ -12,6 +12,8 @@ import { RecipientUnreachableError } from '../../common/errors/recipient-unreach* delegate never touches lifecycle state directly.*/export interface BaileysContactsHost {+ /** This session's egress proxy URL (snapshotted at session start), or undefined when direct. */+ sessionProxyUrl(): string | undefined;ensureReady(): void;/** Post-ensureReady socket handle — call host.ensureReady() first. */getSocket(): WASocket;@@ -180,7 +182,7 @@ export class BaileysContacts {}// updateProfilePicture takes a WAMediaUpload; resolveMediaBuffer covers Buffer | base64 | URL,// the same conversion the media sends use.- const { data } = await resolveMediaBuffer(media);+ const { data } = await resolveMediaBuffer(media, this.host.sessionProxyUrl());await this.confirmed(this.sock().updateProfilePicture(selfJid, data), 'the profile picture change');}diff --git a/src/engine/adapters/baileys-events.ts b/src/engine/adapters/baileys-events.tsindex a427f2fa6..c2e3d3f29 100644--- a/src/engine/adapters/baileys-events.ts+++ b/src/engine/adapters/baileys-events.ts@@ -99,8 +99,8 @@ export interface BaileysEventsHost {normalizedSelfJid(): string;/** Lazily loaded @whiskeysockets/baileys module (ESM-only; loaded on first connect, not at boot). */loadLib(): Promise<typeof BaileysLib>;- /** Session proxy dispatcher for the media download: undefined = direct, null = proxy fetch cannot use. */- getFetchDispatcher(): Dispatcher | null | undefined;+ /** Session proxy dispatcher for the media download; undefined = direct. */+ getFetchDispatcher(): Dispatcher | undefined;/** Unix-seconds timestamp of the last 'open' connection.update — the live-vs-history discriminator. */readonly connectedAt: number;/** The adapter's inbound media download gate (shared so the bound holds across all inbound paths). */@@ -756,12 +756,8 @@ export class BaileysEvents {maxBytes: number,): Promise<Buffer | { overflowBytes: number } | null> {// A proxied session must not fetch media around its proxy (#859). Baileys reads the dispatcher- // from the nested `options` (a top-level one is ignored); a proxy scheme fetch cannot use fails- // the download, which the caller turns into the omitted marker.+ // from the nested `options`; a top-level one is ignored.const dispatcher = this.host.getFetchDispatcher();- if (dispatcher === null) {- throw new Error('Media download is not supported through this proxy scheme');- }// Hold the stream handle in the outer scope so the timeout can destroy it. A genuine// download/read error still rejects (propagating to the caller's catch as before).let stream: (AsyncIterable<Buffer> & { destroy?: () => void }) | undefined;diff --git a/src/engine/adapters/baileys-groups.ts b/src/engine/adapters/baileys-groups.tsindex 49bf8a4d4..4fcab66db 100644--- a/src/engine/adapters/baileys-groups.ts+++ b/src/engine/adapters/baileys-groups.ts@@ -25,6 +25,8 @@ import { toParticipantWid } from '../identity/wa-id';* delegate never touches lifecycle state directly.*/export interface BaileysGroupsHost {+ /** This session's egress proxy URL (snapshotted at session start), or undefined when direct. */+ sessionProxyUrl(): string | undefined;ensureReady(): void;/** Post-ensureReady socket handle — call host.ensureReady() first. */getSocket(): WASocket;@@ -423,7 +425,7 @@ export class BaileysGroups {async setGroupPicture(groupId: string, media: MediaInput): Promise<void> {this.host.ensureReady();// Same socket call as the own-account picture, addressed at the group JID.- const { data } = await resolveMediaBuffer(media);+ const { data } = await resolveMediaBuffer(media, this.host.sessionProxyUrl());await mapServerRefusal('Setting the group picture', () =>this.confirmed(this.sock().updateProfilePicture(groupId, data), 'the group picture change'),);diff --git a/src/engine/adapters/baileys-lifecycle.ts b/src/engine/adapters/baileys-lifecycle.tsindex 4a66a6b86..06ec3f2a2 100644--- a/src/engine/adapters/baileys-lifecycle.ts+++ b/src/engine/adapters/baileys-lifecycle.ts@@ -6,12 +6,13 @@ import type { Socket } from 'net';import * as qrcode from 'qrcode';import { HttpsProxyAgent } from 'https-proxy-agent';import { SocksProxyAgent } from 'socks-proxy-agent';-import { Dispatcher1Wrapper, ProxyAgent, type Dispatcher } from 'undici';+import { type Dispatcher } from 'undici';import type * as BaileysLib from '@whiskeysockets/baileys';import type { WASocket } from '@whiskeysockets/baileys';import type { ILogger } from '@whiskeysockets/baileys/lib/Utils/logger.js';import { EngineEventCallbacks, EngineStatus } from '../interfaces/whatsapp-engine.interface';import { EngineNotReadyError } from '../../common/errors/engine-not-ready.error';+import { createProxyDispatcher, hasUnauthenticatableSocks4Credentials } from '../../common/security/proxy-dispatcher';import { type createLogger } from '../../common/services/logger.service';import { BaileysAdapterConfig } from '../types/baileys.types';import { createBaileysLogger } from './baileys-logger';@@ -109,35 +110,6 @@ export function createProxyAgent(proxyUrl: string, connectTimeoutMs = PROXY_CONNthrow new Error(`Unsupported proxy protocol for the baileys engine: ${protocol}`);}-/**- * Build the global-fetch dispatcher for a session egress proxy, used by Baileys' media download, the- * version lookup and the socket's own `options` fetch init. Global fetch accepts only an undici- * dispatcher, never a Node http Agent, and Node's bundled undici predates the handler API of the- * installed one, so the agent is wrapped to speak the older interface. undici has no SOCKS4 transport:- * null tells the caller to skip the request rather than send it direct.- */-export function createProxyDispatcher(proxyUrl: string): Dispatcher | null {- const { protocol, username, password } = new URL(proxyUrl);- if (protocol === 'http:' || protocol === 'https:') {- return new Dispatcher1Wrapper(new ProxyAgent(proxyUrl));- }- if (protocol === 'socks5:') {- // undici hands SOCKS5 the URL credentials still percent-encoded (it decodes them only for the HTTP- // Proxy-Authorization header), so a password written as `p%40ss` would fail auth. Pass them decoded;- // the options object is not a literal because undici's typings omit these two runtime options.- const options = {- uri: proxyUrl,- username: decodeURIComponent(username) || undefined,- password: decodeURIComponent(password) || undefined,- };- return new Dispatcher1Wrapper(new ProxyAgent(options));- }- if (protocol === 'socks4:') {- return null;- }- throw new Error(`Unsupported proxy protocol for the baileys engine: ${protocol}`);-}-/*** Connection lifecycle extracted from BaileysAdapter: connect/reconnect with capped backoff, QR* rendering, logout with the remove-companion-device ACK, terminal-close handling, and the state@@ -221,7 +193,7 @@ export class BaileysLifecycle {/** Lazily loaded @whiskeysockets/baileys module (ESM-only; loaded on first connect, not at boot). */private lib?: typeof BaileysLib;/** The session proxy's fetch dispatcher, built once: the proxy URL is fixed for the adapter's life. */- private dispatcher?: Dispatcher | null;+ private dispatcher?: Dispatcher;constructor(private readonly host: BaileysLifecycleHost) {this.versionResolver = new BaileysVersionResolver({@@ -236,19 +208,13 @@ export class BaileysLifecycle {return (this.lib ??= await import('@whiskeysockets/baileys'));}- /**- * Dispatcher for Baileys' global-fetch calls: undefined without a proxy (direct), null when the- * proxy scheme has no fetch transport, so the caller must skip the request instead of going direct.- */- fetchDispatcher(): Dispatcher | null | undefined {+ /** Dispatcher for Baileys' global-fetch calls: undefined without a proxy (direct). */+ fetchDispatcher(): Dispatcher | undefined {const { proxyUrl } = this.host.config;if (!proxyUrl) {return undefined;}- if (this.dispatcher === undefined) {- this.dispatcher = createProxyDispatcher(proxyUrl);- }- return this.dispatcher;+ return (this.dispatcher ??= createProxyDispatcher(proxyUrl));}async initialize(): Promise<void> {@@ -302,6 +268,13 @@ export class BaileysLifecycle {const { protocol, host } = new URL(this.host.config.proxyUrl);// Credential-stripped, matching the wwjs adapter's log line (#628).this.host.logger.log(`Using proxy: ${protocol}//${host}`, { sessionId: this.host.config.sessionId });+ if (hasUnauthenticatableSocks4Credentials(this.host.config.proxyUrl)) {+ this.host.logger.warn(+ `Proxy for session ${this.host.config.sessionId} has credentials on a SOCKS4 proxy, which has no ` ++ `authentication step: the user name is sent as the connect request's user id and the password is ` ++ `dropped. Use a socks5, http or https proxy, or an IP-authorized one.`,+ );+ }}const b = await this.loadLib();const { state, saveCreds } = await b.useMultiFileAuthState(this.host.authPath);@@ -371,8 +344,7 @@ export class BaileysLifecycle {// The same dispatcher for the fetches Baileys runs off this config itself: the history-sync// payload, the app-state external blobs, and a URL handed to a send (a product card image).// Without it they leave direct from the host IP even on a proxied session. `{}` is Baileys' own- // default for the key, and is what an unproxied session gets, as does a SOCKS4 one: it has no- // fetch transport at all, so these keep going direct there as they always have.+ // default for the key, and is what an unproxied session gets.options: (fetchDispatcher ? { dispatcher: fetchDispatcher } : {}) as RequestInit,// Enable the initial sync. Baileys defaults `shouldSyncHistoryMessage` to `() => !!syncFullHistory`,// so leaving both unset disables ALL history + app-state sync - no contacts, chats, recent history,diff --git a/src/engine/adapters/baileys-media-abort.spec.ts b/src/engine/adapters/baileys-media-abort.spec.tsindex c7d41f48c..46d438fa3 100644--- a/src/engine/adapters/baileys-media-abort.spec.ts+++ b/src/engine/adapters/baileys-media-abort.spec.ts@@ -24,7 +24,7 @@ function imageMessage(id: string, fileLength: number): WAMessage {};}-function build(dispatcher?: object | null): { events: BaileysEvents; warns: string[] } {+function build(dispatcher?: object): { events: BaileysEvents; warns: string[] } {const warns: string[] = [];const events = new BaileysEvents({getSocket: () => ({ updateMediaMessage: jest.fn() }) as unknown as WASocket,@@ -179,13 +179,19 @@ describe('BaileysEvents media download through a session proxy', () => {);});- it('never downloads direct when the proxy scheme has no fetch dispatcher', async () => {- const { events, warns } = build(null);+ // An unproxied session passes no dispatcher at all, which is Baileys' own default, and the+ // download must not start carrying an empty options object instead.+ it('passes no fetch options for an unproxied session', async () => {+ downloadMediaMessage.mockResolvedValue({+ // eslint-disable-next-line @typescript-eslint/require-await+ async *[Symbol.asyncIterator]() {+ yield Buffer.from('IMG');+ },+ });+ const { events } = build(undefined);- const incoming = await events.mapMessage(imageMessage('SOCKS4', 3), 'imageMessage');+ await events.mapMessage(imageMessage('DIRECT', 3), 'imageMessage');- expect(downloadMediaMessage).not.toHaveBeenCalled();- expect(incoming.media).toEqual({ mimetype: 'image/png', filename: undefined, omitted: true, sizeBytes: 3 });- expect(warns).toEqual([expect.stringContaining('download failed')]);+ expect(downloadMediaMessage).toHaveBeenCalledWith(expect.anything(), 'stream', {}, expect.anything());});});diff --git a/src/engine/adapters/baileys-messaging.ts b/src/engine/adapters/baileys-messaging.tsindex 570f9ff5d..f352f2357 100644--- a/src/engine/adapters/baileys-messaging.ts+++ b/src/engine/adapters/baileys-messaging.ts@@ -31,6 +31,8 @@ import { BAILEYS_QUERY_BUDGET_MS, withQueryDeadline } from './baileys-query-dead* delegate never touches lifecycle state directly.*/export interface BaileysMessagingHost {+ /** This session's egress proxy URL (snapshotted at session start), or undefined when direct. */+ sessionProxyUrl(): string | undefined;ensureReady(): void;/** Post-ensureReady socket handle — call host.ensureReady() first. */getSocket(): WASocket;@@ -132,13 +134,21 @@ async function toWebpSticker(data: Buffer, mimetype: string): Promise<Buffer> {}}-/** Resolve a MediaInput's data (Buffer | base64 string | http(s) URL) to bytes + mimetype. */-export async function resolveMediaBuffer(media: MediaInput): Promise<{ data: Buffer; mimetype: string }> {+/**+ * Resolve a MediaInput's data (Buffer | base64 string | http(s) URL) to bytes + mimetype.+ *+ * `sessionProxyUrl` is this session's egress proxy, which the URL fetch leaves through (#1626). It+ * is required, not optional, so a new call site cannot fetch direct on a proxied session by omission.+ */+export async function resolveMediaBuffer(+ media: MediaInput,+ sessionProxyUrl: string | undefined,+): Promise<{ data: Buffer; mimetype: string }> {if (Buffer.isBuffer(media.data)) {return { data: media.data, mimetype: media.mimetype };}if (/^https?:\/\//i.test(media.data)) {- const fetched = await loadRemoteMediaBuffer(media.data);+ const fetched = await loadRemoteMediaBuffer(media.data, sessionProxyUrl);// A generic placeholder mimetype (buildMediaInput's 'application/octet-stream' default when the// caller supplied none) carries no real signal — defer to the fetched response content-type,// which was sniffed from the actual bytes. This fixes URL-based sends where the caller has no@@ -179,7 +189,7 @@ export class BaileysMessaging {// not only when a preview was asked for.const options = {...(this.withEphemeral(jid) ?? {}),- getUrlInfo: (text: string) => generateSafeLinkPreview(text),+ getUrlInfo: (text: string) => generateSafeLinkPreview(text, { sessionProxyUrl: this.host.sessionProxyUrl() }),// Merged rather than assigned: getUrlInfo above must survive, or the library's own vulnerable// preview generator becomes reachable again on quoted sends only....((await this.quoteOption(sendOptions?.quotedMessageId)) ?? {}),@@ -314,7 +324,7 @@ export class BaileysMessaging {async sendImageMessage(chatId: string, media: MediaInput): Promise<MessageResult> {this.host.ensureReady();- const { data, mimetype } = await resolveMediaBuffer(media);+ const { data, mimetype } = await resolveMediaBuffer(media, this.host.sessionProxyUrl());return this.sendContent(chatId,{@@ -329,7 +339,7 @@ export class BaileysMessaging {async sendVideoMessage(chatId: string, media: MediaInput): Promise<MessageResult> {this.host.ensureReady();- const { data, mimetype } = await resolveMediaBuffer(media);+ const { data, mimetype } = await resolveMediaBuffer(media, this.host.sessionProxyUrl());return this.sendContent(chatId,{@@ -344,7 +354,7 @@ export class BaileysMessaging {async sendAudioMessage(chatId: string, media: MediaInput): Promise<MessageResult> {this.host.ensureReady();- const { data, mimetype } = await resolveMediaBuffer(media);+ const { data, mimetype } = await resolveMediaBuffer(media, this.host.sessionProxyUrl());return this.sendContent(chatId,// Audio carries no caption, so a mention here tags the recipient through contextInfo without@@ -358,7 +368,7 @@ export class BaileysMessaging {async sendDocumentMessage(chatId: string, media: MediaInput): Promise<MessageResult> {this.host.ensureReady();- const { data, mimetype } = await resolveMediaBuffer(media);+ const { data, mimetype } = await resolveMediaBuffer(media, this.host.sessionProxyUrl());return this.sendContent(chatId,{@@ -396,7 +406,7 @@ export class BaileysMessaging {async sendStickerMessage(chatId: string, media: MediaInput): Promise<MessageResult> {this.host.ensureReady();- const { data, mimetype } = await resolveMediaBuffer(media);+ const { data, mimetype } = await resolveMediaBuffer(media, this.host.sessionProxyUrl());// A sticker has neither text nor caption, but stickerMessage carries a contextInfo like every// other content type, so a mention still tags the participant. The route accepts the field// (send-sticker shares SendMediaMessageDto) and docs/06 lists it among the media sends that@@ -617,7 +627,10 @@ export class BaileysMessaging {*/private previewSafeOptions(content: AnyMessageContent, options?: MiscMessageGenerationOptions) {if (!('text' in content)) return options;- return { ...(options ?? {}), getUrlInfo: (text: string) => generateSafeLinkPreview(text) };+ return {+ ...(options ?? {}),+ getUrlInfo: (text: string) => generateSafeLinkPreview(text, { sessionProxyUrl: this.host.sessionProxyUrl() }),+ };}private async sendContent(diff --git a/src/engine/adapters/baileys-proxy.spec.ts b/src/engine/adapters/baileys-proxy.spec.tsdeleted file mode 100644index becb7ad07..000000000--- a/src/engine/adapters/baileys-proxy.spec.ts+++ /dev/null@@ -1,87 +0,0 @@-import * as http from 'http';-import * as net from 'net';-import type { AddressInfo } from 'net';-import { Dispatcher1Wrapper } from 'undici';-import { createProxyDispatcher } from './baileys-lifecycle';--/**- * Baileys fetches media and the WhatsApp Web version with global fetch, which takes only an undici- * dispatcher that speaks the handler API of the undici bundled in Node, never a Node http Agent. The- * last case runs a real fetch through a local proxy, so an incompatible dispatcher fails here.- */--const listen = async <T extends net.Server>(server: T): Promise<T> => {- await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve));- return server;-};-const portOf = (server: net.Server): number => (server.address() as AddressInfo).port;-const close = (server: net.Server): Promise<void> => new Promise(resolve => server.close(() => resolve()));--describe('createProxyDispatcher', () => {- it('wraps a dispatcher for http, https and socks5 proxies', () => {- for (const url of ['http://u:[email protected]:8080', 'https://proxy.example:443', 'socks5://proxy.example:1080']) {- expect(createProxyDispatcher(url)).toBeInstanceOf(Dispatcher1Wrapper);- }- });-- it('returns null for socks4, which fetch cannot use', () => {- expect(createProxyDispatcher('socks4://proxy.example:1080')).toBeNull();- });-- it('throws on an unsupported scheme', () => {- expect(() => createProxyDispatcher('ftp://proxy.example:21')).toThrow(/unsupported proxy/i);- });-- it('routes a global fetch through the proxy', async () => {- const seen: string[] = [];- const proxy = await listen(- http.createServer((req, res) => {- seen.push(`${req.method} ${req.url}`);- res.end('via proxy');- }),- );- try {- const response = await fetch('http://media.example.invalid/file', {- dispatcher: createProxyDispatcher(`http://127.0.0.1:${portOf(proxy)}`),- } as RequestInit);- expect(await response.text()).toBe('via proxy');- expect(seen).toEqual(['GET http://media.example.invalid/file']);- } finally {- proxy.closeAllConnections();- await close(proxy);- }- });-- it('sends percent-encoded socks5 credentials decoded', async () => {- // Minimal SOCKS5 server: ask for username/password auth (RFC 1929), record it, then refuse.- const seen: string[] = [];- const sockets = new Set<net.Socket>();- const proxy = await listen(- net.createServer(socket => {- sockets.add(socket);- socket.once('data', () => {- socket.write(Buffer.from([0x05, 0x02]));- socket.once('data', auth => {- const userLen = auth[1];- const user = auth.subarray(2, 2 + userLen).toString();- const passLen = auth[2 + userLen];- const pass = auth.subarray(3 + userLen, 3 + userLen + passLen).toString();- seen.push(`${user}:${pass}`);- socket.end(Buffer.from([0x01, 0x01]));- });- });- }),- );- try {- await expect(- fetch('http://media.example.invalid/file', {- dispatcher: createProxyDispatcher(`socks5://us%40er:p%40ss%[email protected]:${portOf(proxy)}`),- } as RequestInit),- ).rejects.toThrow();- expect(seen).toEqual(['us@er:p@ss:1']);- } finally {- sockets.forEach(socket => socket.destroy());- await close(proxy);- }- });-});diff --git a/src/engine/adapters/baileys-quoted-send.spec.ts b/src/engine/adapters/baileys-quoted-send.spec.tsindex e9de2f825..2695383d6 100644--- a/src/engine/adapters/baileys-quoted-send.spec.ts+++ b/src/engine/adapters/baileys-quoted-send.spec.ts@@ -37,6 +37,7 @@ function makeMessaging(stored: unknown = STORED): {const getStoredMessage = jest.fn().mockResolvedValue(stored);const host = {ensureReady: jest.fn(),+ sessionProxyUrl: () => undefined,getSocket: () => sock as unknown as WASocket,logger,toNeutralJid: (j: string) => j,diff --git a/src/engine/adapters/baileys-status.ts b/src/engine/adapters/baileys-status.tsindex 178bd3f86..ecaf64df6 100644--- a/src/engine/adapters/baileys-status.ts+++ b/src/engine/adapters/baileys-status.ts@@ -9,6 +9,8 @@ import { resolveMediaBuffer } from './baileys-messaging';* delegate never touches lifecycle state directly.*/export interface BaileysStatusHost {+ /** This session's egress proxy URL (snapshotted at session start), or undefined when direct. */+ sessionProxyUrl(): string | undefined;ensureReady(): void;/** Post-ensureReady socket handle — call host.ensureReady() first. */getSocket(): WASocket;@@ -48,7 +50,7 @@ export class BaileysStatus {options: StatusPostOptions,): Promise<StatusResult> {this.host.ensureReady();- const { data, mimetype } = await resolveMediaBuffer(media);+ const { data, mimetype } = await resolveMediaBuffer(media, this.host.sessionProxyUrl());// A voice status carries no caption: WhatsApp has nowhere to render one on a status voice note,// and `ptt` is what makes it a voice note rather than an audio file. Baileys reads that same flag// to decide a status may take a background colour, so the colour `postStatus` already forwardsdiff --git a/src/engine/adapters/baileys-sticker-webp.spec.ts b/src/engine/adapters/baileys-sticker-webp.spec.tsindex c532b573b..c77cb4166 100644--- a/src/engine/adapters/baileys-sticker-webp.spec.ts+++ b/src/engine/adapters/baileys-sticker-webp.spec.ts@@ -48,6 +48,7 @@ function makeMessaging(): { messaging: BaileysMessaging; sock: { sendMessage: jeconst sock = { sendMessage: jest.fn().mockResolvedValue({ key: { id: 'M1' }, messageTimestamp: 1 }) };const host = {ensureReady: jest.fn(),+ sessionProxyUrl: () => undefined,getSocket: () => sock as unknown as WASocket,logger,toNeutralJid: (j: string) => j,diff --git a/src/engine/adapters/baileys-version-resolver.spec.ts b/src/engine/adapters/baileys-version-resolver.spec.tsindex 8088bc422..2df78c3eb 100644--- a/src/engine/adapters/baileys-version-resolver.spec.ts+++ b/src/engine/adapters/baileys-version-resolver.spec.ts@@ -38,20 +38,21 @@ describe('BaileysVersionResolver', () => {const asBaileysLib = (mock: unknown): typeof BaileysLib => mock as typeof BaileysLib;- describe('Proxy scheme without a fetch dispatcher', () => {- it('when the dispatcher is null, skips both remote tiers instead of fetching direct', async () => {- fs.writeFileSync(path.join(tmpDir, 'last_known_wa_version.json'), JSON.stringify([2, 3000, 1043857760]));+ describe('Session proxy', () => {+ // Every supported proxy scheme now has a fetch transport, so the lookup rides the proxy instead+ // of being skipped for want of one.+ it('hands the dispatcher to the remote tier rather than skipping it', async () => {+ const dispatcher = { marker: 'session-proxy' };const resolver = createResolver();const mockLib = {- fetchLatestWaWebVersion: jest.fn(),+ fetchLatestWaWebVersion: jest.fn().mockResolvedValue({ isLatest: true, version: [2, 3000, 1043857760] }),fetchLatestBaileysVersion: jest.fn(),};- const version = await resolver.resolve(asBaileysLib(mockLib), { dispatcher: null });+ const version = await resolver.resolve(asBaileysLib(mockLib), { dispatcher });expect(version).toEqual([2, 3000, 1043857760]);- expect(mockLib.fetchLatestWaWebVersion).not.toHaveBeenCalled();- expect(mockLib.fetchLatestBaileysVersion).not.toHaveBeenCalled();+ expect(mockLib.fetchLatestWaWebVersion).toHaveBeenCalledWith(expect.objectContaining({ dispatcher }));});});diff --git a/src/engine/adapters/baileys-version-resolver.ts b/src/engine/adapters/baileys-version-resolver.tsindex 1710c7df1..3d2dc0c4a 100644--- a/src/engine/adapters/baileys-version-resolver.ts+++ b/src/engine/adapters/baileys-version-resolver.ts@@ -23,8 +23,7 @@ export interface BaileysVersionResolverOptions {}export interface ResolveOptions {- /** Global-fetch dispatcher for the session proxy. null means the session is proxied through a scheme- * fetch cannot use, so both remote tiers are skipped rather than fetched direct around the proxy. */+ /** Global-fetch dispatcher for the session proxy; undefined on an unproxied session (direct). */dispatcher?: unknown;}@@ -53,20 +52,14 @@ export class BaileysVersionResolver {return envVersion;}- if (resolveOptions.dispatcher === null) {- this.options.logger.log('Remote WhatsApp Web version lookup is not supported through this proxy scheme', {- sessionId: this.options.sessionId,- });- } else {- const waWebVersion = await this.resolveFromWaWeb(b, resolveOptions);- if (waWebVersion) {- return waWebVersion;- }+ const waWebVersion = await this.resolveFromWaWeb(b, resolveOptions);+ if (waWebVersion) {+ return waWebVersion;+ }- const baileysVersion = await this.resolveFromBaileys(b, resolveOptions);- if (baileysVersion) {- return baileysVersion;- }+ const baileysVersion = await this.resolveFromBaileys(b, resolveOptions);+ if (baileysVersion) {+ return baileysVersion;}const cachedVersion = this.resolveFromDiskCache();diff --git a/src/engine/adapters/baileys-write-deadline.spec.ts b/src/engine/adapters/baileys-write-deadline.spec.tsindex 444a6ee50..1fbb69dd2 100644--- a/src/engine/adapters/baileys-write-deadline.spec.ts+++ b/src/engine/adapters/baileys-write-deadline.spec.ts@@ -18,6 +18,7 @@ const stub = () => jest.fn(never);function groups(sock: Record<string, jest.Mock>, budgetMs: number): BaileysGroups {const host = {ensureReady: () => undefined,+ sessionProxyUrl: () => undefined,getSocket: () => sock as unknown as WASocket,logger: { warn: jest.fn(), debug: jest.fn(), info: jest.fn(), error: jest.fn() },toNeutralJid: (j: string) => j,@@ -30,6 +31,7 @@ function groups(sock: Record<string, jest.Mock>, budgetMs: number): BaileysGroupfunction contacts(sock: Record<string, jest.Mock>, budgetMs: number): BaileysContacts {const host = {ensureReady: () => undefined,+ sessionProxyUrl: () => undefined,getSocket: () => sock as unknown as WASocket,logger: { warn: jest.fn(), debug: jest.fn(), info: jest.fn(), error: jest.fn() },normalizedSelfJid: () => '[email protected]',diff --git a/src/engine/adapters/baileys.adapter.spec.ts b/src/engine/adapters/baileys.adapter.spec.tsindex 768d7be33..56791a28c 100644--- a/src/engine/adapters/baileys.adapter.spec.ts+++ b/src/engine/adapters/baileys.adapter.spec.ts@@ -159,6 +159,7 @@ import { ChatLabelsUnsupportedError } from '../../common/errors/chat-labels-unsuimport { Boom } from '@hapi/boom';import { EngineTransportError } from '../../common/errors/engine-transport.error';import { loadRemoteMediaBuffer } from '../../common/media/load-remote-media';+import * as safeLinkPreview from './safe-link-preview';const fakeStore = {put: jest.fn().mockResolvedValue(undefined),@@ -1670,6 +1671,59 @@ describe('BaileysAdapter messaging', () => {expect(res).toEqual({ id: 'OUT1', timestamp: 1700000001 });});+ /** An adapter for a session started behind a proxy, which every fetch it makes must leave through. */+ const proxiedAdapter = async (): Promise<BaileysAdapter> => {+ const adapter = new BaileysAdapter({+ sessionId: 'sess-1',+ dbSessionId: 'db-uuid-1',+ authDir: './data/baileys',+ messageStore: fakeStore,+ proxyUrl: 'socks5://proxy.invalid:1080',+ });+ await adapter.initialize({});+ fakeSock.fire('connection.update', { connection: 'open' });+ return adapter;+ };++ /** Run the preview generator the last send handed Baileys, the way the library itself would. */+ const runPreviewGenerator = async (): Promise<void> => {+ const calls = fakeSock.sendMessage.mock.calls as Array<[unknown, unknown, { getUrlInfo: (t: string) => unknown }]>;+ await calls[calls.length - 1][2].getUrlInfo('https://example.com');+ };++ // The preview generator fetches a URL out of the message text, which is caller-supplied egress+ // like a media URL: on a proxied session it must leave through the session proxy (#1626).+ it('generates the link preview of a text send through the session proxy', async () => {+ const preview = jest.spyOn(safeLinkPreview, 'generateSafeLinkPreview').mockResolvedValue(undefined);+ fakeSock.sendMessage.mockResolvedValue({ key: { id: 'OUT1' }, messageTimestamp: 1700000001 });+ const adapter = await proxiedAdapter();++ await adapter.sendTextMessage('[email protected]', 'see https://example.com');+ await runPreviewGenerator();++ expect(preview).toHaveBeenCalledWith('https://example.com', { sessionProxyUrl: 'socks5://proxy.invalid:1080' });+ preview.mockRestore();+ });++ // Every OTHER text-bearing send (an edit, a reply) shares one options builder, so it carries the+ // same responsibility as a plain text send and reaches more routes.+ it('generates the link preview of an edit through the session proxy', async () => {+ const preview = jest.spyOn(safeLinkPreview, 'generateSafeLinkPreview').mockResolvedValue(undefined);+ const own = {+ key: { id: 'TARGET', remoteJid: '[email protected]', fromMe: true },+ message: { conversation: 'hi' },+ };+ fakeStore.getMessage.mockResolvedValue(own);+ fakeSock.sendMessage.mockResolvedValue({ key: { ...own.key }, messageTimestamp: 1700000010 });+ const adapter = await proxiedAdapter();++ await adapter.editMessage('[email protected]', 'TARGET', 'see https://example.com');+ await runPreviewGenerator();++ expect(preview).toHaveBeenCalledWith('https://example.com', { sessionProxyUrl: 'socks5://proxy.invalid:1080' });+ preview.mockRestore();+ });+it('emits onMessageCreate for the own send so message.sent fires (parity with the wwjs engine)', async () => {const onMessageCreate = jest.fn();// A realistic own-send return: fromMe + remoteJid + content, which the API-send echo path maps.@@ -3152,7 +3206,7 @@ describe('BaileysAdapter media sends', () => {(loadRemoteMediaBuffer as jest.Mock).mockResolvedValue({ data: Buffer.from([9]), mimetype: 'video/mp4' });const adapter = await ready();await adapter.sendVideoMessage('[email protected]', { mimetype: '', data: 'https://cdn.example/v.mp4' });- expect(loadRemoteMediaBuffer).toHaveBeenCalledWith('https://cdn.example/v.mp4');+ expect(loadRemoteMediaBuffer).toHaveBeenCalledWith('https://cdn.example/v.mp4', undefined);expect(fakeSock.sendMessage).toHaveBeenCalledWith('[email protected]', {video: Buffer.from([9]),caption: undefined,@@ -3237,6 +3291,25 @@ describe('BaileysAdapter media sends', () => {});});+ // A URL send is made by the gateway, not by the socket, so nothing else makes it follow the+ // session's egress proxy: the adapter has to hand its own proxy to the fetch (#1626).+ it('fetches a URL data string through the session proxy on a proxied session', async () => {+ (loadRemoteMediaBuffer as jest.Mock).mockResolvedValue({ data: Buffer.from([9]), mimetype: 'video/mp4' });+ const adapter = new BaileysAdapter({+ sessionId: 'sess-1',+ dbSessionId: 'db-uuid-1',+ authDir: './data/baileys',+ messageStore: fakeStore,+ proxyUrl: 'socks5://proxy.invalid:1080',+ });+ await adapter.initialize({});+ fakeSock.fire('connection.update', { connection: 'open' });++ await adapter.sendVideoMessage('[email protected]', { mimetype: '', data: 'https://cdn.example/v.mp4' });++ expect(loadRemoteMediaBuffer).toHaveBeenCalledWith('https://cdn.example/v.mp4', 'socks5://proxy.invalid:1080');+ });+it('uses the caller-declared mimetype over the fetched content-type for a URL', async () => {(loadRemoteMediaBuffer as jest.Mock).mockResolvedValue({data: Buffer.from([1]),@@ -5182,6 +5255,32 @@ describe('BaileysAdapter proxy support', () => {expect(lastSocketConfig().agent).toBeInstanceOf(SocksProxyAgent);});+ // SOCKS4 has no authentication step, so a credentialed socks4 URL is not the login the operator+ // thinks it is: the proxy answers "request rejected", which reads like an unreachable host.+ it('warns that a credentialed socks4 proxy cannot authenticate', async () => {+ const adapter = proxied('socks4://user:[email protected]:1080');+ const logger = (adapter as unknown as { logger: { warn: (m: string) => void } }).logger;+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => undefined);++ await adapter.initialize(noopCallbacks());++ expect(warn).toHaveBeenCalledWith(expect.stringMatching(/SOCKS4 proxy, which has no authentication/));+ warn.mockRestore();+ });++ it('does not warn for a credential-less socks4 proxy, or for credentials on socks5', async () => {+ for (const url of ['socks4://proxy.example:1080', 'socks5://user:[email protected]:1080']) {+ const adapter = proxied(url);+ const logger = (adapter as unknown as { logger: { warn: (m: string) => void } }).logger;+ const warn = jest.spyOn(logger, 'warn').mockImplementation(() => undefined);++ await adapter.initialize(noopCallbacks());++ expect(warn).not.toHaveBeenCalledWith(expect.stringMatching(/SOCKS4/));+ warn.mockRestore();+ }+ });+it('hands the version lookup a fetch dispatcher, not the socket agent', async () => {await proxied('http://user:[email protected]:8080').initialize(noopCallbacks());// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access@@ -5190,10 +5289,12 @@ describe('BaileysAdapter proxy support', () => {expect(options.dispatcher).toBeInstanceOf(Dispatcher1Wrapper);});- it('skips the remote version lookup rather than going direct for a socks4 proxy', async () => {+ it('hands the version lookup a dispatcher for a socks4 proxy too, instead of skipping it', async () => {await proxied('socks4://proxy.example:1080').initialize(noopCallbacks());// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access- expect(jest.requireMock('@whiskeysockets/baileys').fetchLatestBaileysVersion).not.toHaveBeenCalled();+ const lookup = jest.requireMock('@whiskeysockets/baileys').fetchLatestBaileysVersion as jest.Mock;+ const [[options]] = lookup.mock.calls as Array<[{ dispatcher?: unknown }]>;+ expect(options.dispatcher).toBeInstanceOf(Dispatcher1Wrapper);});it('hands the socket config a fetch dispatcher, for the downloads Baileys runs itself', async () => {@@ -5202,11 +5303,12 @@ describe('BaileysAdapter proxy support', () => {expect(options.dispatcher).toBeInstanceOf(Dispatcher1Wrapper);});- it('leaves the socket fetch options at the library default for a socks4 proxy', async () => {- // Global fetch has no SOCKS4 transport, so there is nothing to hand it; these downloads keep the- // direct behaviour they have always had rather than being broken outright.+ it('hands the socket config a fetch dispatcher for a socks4 proxy too', async () => {+ // The SOCKS connector covers socks4, so the fetches Baileys runs off this config (history sync,+ // app-state blobs, a product card image) no longer leave direct on a socks4 session.await proxied('socks4://proxy.example:1080').initialize(noopCallbacks());- expect(lastSocketConfig().options).toEqual({});+ const options = lastSocketConfig().options as { dispatcher?: unknown };+ expect(options.dispatcher).toBeInstanceOf(Dispatcher1Wrapper);});it('leaves agent/fetchAgent unset and the fetch options at the library default without a proxyUrl', async () => {diff --git a/src/engine/adapters/baileys.adapter.ts b/src/engine/adapters/baileys.adapter.tsindex 67f5173aa..84268c1f9 100644--- a/src/engine/adapters/baileys.adapter.ts+++ b/src/engine/adapters/baileys.adapter.ts@@ -134,6 +134,7 @@ export class BaileysAdapter implements IWhatsAppEngine {normalizedSelfJid: () => this.normalizedSelfJid(),loadLib: () => this.loadLib(),getFetchDispatcher: () => this.lifecycle.fetchDispatcher(),+ sessionProxyUrl: () => this.config.proxyUrl,toUnixSeconds,inboundLimiter: this.inboundLimiter,recordKeyLidMappings: key => this.sessionStore.recordKeyLidMappings(key),diff --git a/src/engine/adapters/membership-requests.spec.ts b/src/engine/adapters/membership-requests.spec.tsindex 421b35eab..994e638eb 100644--- a/src/engine/adapters/membership-requests.spec.ts+++ b/src/engine/adapters/membership-requests.spec.ts@@ -225,6 +225,7 @@ function makeBaileysGroups(): { groups: BaileysGroups; sock: BaileysSockStub } {};const host: BaileysGroupsHost = {ensureReady: jest.fn(),+ sessionProxyUrl: () => undefined,getSocket: () => sock as unknown as WASocket,logger,toNeutralJid: jid => jid.replace('@s.whatsapp.net', '@c.us'),diff --git a/src/engine/adapters/safe-link-preview.spec.ts b/src/engine/adapters/safe-link-preview.spec.tsindex 66e3b7e43..75232d33b 100644--- a/src/engine/adapters/safe-link-preview.spec.ts+++ b/src/engine/adapters/safe-link-preview.spec.ts@@ -37,6 +37,36 @@ describe('generateSafeLinkPreview', () => {expect((withSafeFetch.mock.calls[0] as unknown[])[0]).toBe('https://example.com/a');});+ // A URL in a message is caller-supplied, so fetching it is session egress like a media URL: it+ // has to leave through the session's proxy rather than from the gateway's own address (#1626).+ it('hands the guard the session proxy for a proxied session', async () => {+ respondWith('<title>Example</title>');++ await generateSafeLinkPreview('https://example.com/a', { sessionProxyUrl: 'socks5://proxy.invalid:1080' });++ expect((withSafeFetch.mock.calls[0] as unknown[])[3]).toEqual({ proxyUrl: 'socks5://proxy.invalid:1080' });+ });++ it('leaves an unproxied session fetching direct', async () => {+ respondWith('<title>Example</title>');++ await generateSafeLinkPreview('https://example.com/a');++ expect((withSafeFetch.mock.calls[0] as unknown[])[3]).toEqual({ proxyUrl: undefined });+ });++ it('fetches direct when the operator switches the session-proxy URL fetch off', async () => {+ process.env.SESSION_PROXY_URL_FETCH = 'false';+ respondWith('<title>Example</title>');+ try {+ await generateSafeLinkPreview('https://example.com/a', { sessionProxyUrl: 'socks5://proxy.invalid:1080' });+ } finally {+ delete process.env.SESSION_PROXY_URL_FETCH;+ }++ expect((withSafeFetch.mock.calls[0] as unknown[])[3]).toEqual({ proxyUrl: undefined });+ });+// The guard rejects a blocked destination by throwing. That must surface as "no preview", never// as a failed send — and never as a leaked internal address in an error message.it('returns nothing when the guard refuses the destination', async () => {diff --git a/src/engine/adapters/safe-link-preview.ts b/src/engine/adapters/safe-link-preview.tsindex 48505799f..dddf01941 100644--- a/src/engine/adapters/safe-link-preview.ts+++ b/src/engine/adapters/safe-link-preview.ts@@ -1,5 +1,6 @@import type { Response } from 'undici';import { withSafeFetch } from '../../common/security/ssrf-guard';+import { urlFetchProxy } from '../../common/security/proxy-dispatcher';/*** The link-preview payload WhatsApp accepts, in Baileys' own field names.@@ -32,11 +33,12 @@ export interface SafeUrlInfo {* so an operator who intentionally allows an internal host keeps that behaviour here too.** Returns undefined rather than throwing on any failure: a preview is decoration, and a site that is- * slow, unreachable, or refused must never turn into a failed message send.+ * slow, unreachable, or refused must never turn into a failed message send. That includes an+ * unusable session proxy: no preview is attached, and the fetch never falls back to a direct one.*/export async function generateSafeLinkPreview(matchedText: string,- opts: { timeoutMs?: number; maxBytes?: number } = {},+ opts: { timeoutMs?: number; maxBytes?: number; sessionProxyUrl?: string } = {},): Promise<SafeUrlInfo | undefined> {const timeoutMs = opts.timeoutMs ?? 3000;const maxBytes = opts.maxBytes ?? 512 * 1024;@@ -87,6 +89,9 @@ export async function generateSafeLinkPreview(...(description ? { description: decodeEntities(description) } : {}),};},+ // The fetched URL comes from the message text, so it is caller-supplied the same way a media+ // URL is: on a proxied session it leaves through the session proxy (#1626).+ { proxyUrl: urlFetchProxy(opts.sessionProxyUrl) },);} catch {// Blocked destination, DNS failure, timeout, malformed response — all the same to a caller whodiff --git a/src/engine/adapters/whatsapp-web-js.adapter.spec.ts b/src/engine/adapters/whatsapp-web-js.adapter.spec.tsindex a6fa32dcb..374462f60 100644--- a/src/engine/adapters/whatsapp-web-js.adapter.spec.ts+++ b/src/engine/adapters/whatsapp-web-js.adapter.spec.ts@@ -37,6 +37,7 @@ import { InvalidInviteCodeError } from '../../common/errors/invalid-invite-code.import { GroupNotFoundError } from '../../common/errors/group-not-found.error';import { LabelNotFoundError } from '../../common/errors/label-not-found.error';import { SsrfBlockedError } from '../../common/security/ssrf-guard';+import * as loadRemoteMediaModule from '../../common/media/load-remote-media';import { fetch as undiciFetch } from 'undici';// Allowlisted hosts are PINNED to their DNS answer (ssrf-guard pins allowlisted hosts to their DNS answers), so the specs that exercise@@ -510,7 +511,7 @@ describe('loadRemoteMedia — routes through the SSRF-pinned media fetch', () =>it('builds MessageMedia from the pinned fetch bytes, never via MessageMedia.fromUrl', async () => {(undiciFetch as jest.Mock).mockResolvedValue(fakeResponse([104, 105], { 'content-type': 'image/png' }));- const media = await loadRemoteMedia('https://8.8.8.8/x.png');+ const media = await loadRemoteMedia('https://8.8.8.8/x.png', undefined);expect(fromUrlSpy).not.toHaveBeenCalled(); // the unpinned node-fetch path is goneexpect(media.mimetype).toBe('image/png');@@ -522,13 +523,13 @@ describe('loadRemoteMedia — routes through the SSRF-pinned media fetch', () =>});it('blocks an internal/loopback URL BEFORE any fetch (no outbound socket)', async () => {- await expect(loadRemoteMedia('http://127.0.0.1/x.png')).rejects.toBeInstanceOf(SsrfBlockedError);+ await expect(loadRemoteMedia('http://127.0.0.1/x.png', undefined)).rejects.toBeInstanceOf(SsrfBlockedError);expect(undiciFetch).not.toHaveBeenCalled();expect(fromUrlSpy).not.toHaveBeenCalled();});it('blocks the cloud-metadata IP before fetching', async () => {- await expect(loadRemoteMedia('http://169.254.169.254/latest/meta-data/x.png')).rejects.toBeInstanceOf(+ await expect(loadRemoteMedia('http://169.254.169.254/latest/meta-data/x.png', undefined)).rejects.toBeInstanceOf(SsrfBlockedError,);expect(undiciFetch).not.toHaveBeenCalled();@@ -538,7 +539,7 @@ describe('loadRemoteMedia — routes through the SSRF-pinned media fetch', () =>process.env.SSRF_ALLOWED_HOSTS = 'minio';(undiciFetch as jest.Mock).mockResolvedValue(fakeResponse([1], { 'content-type': 'image/png' }));- const media = await loadRemoteMedia('http://minio:9000/bucket/x.png');+ const media = await loadRemoteMedia('http://minio:9000/bucket/x.png', undefined);expect(media.mimetype).toBe('image/png');expect(fromUrlSpy).not.toHaveBeenCalled();@@ -4164,6 +4165,30 @@ describe('outbound document mode (#989)', () => {);});+ // The browser's own requests ride Chromium's --proxy-server; this fetch is made by the gateway,+ // so the adapter has to hand it the session proxy or it leaves from the gateway's address (#1626).+ it('fetches a media URL through the session proxy on a proxied session', async () => {+ const load = jest+ .spyOn(loadRemoteMediaModule, 'loadRemoteMediaBuffer')+ .mockResolvedValue({ data: Buffer.from([1]), mimetype: 'image/png' });+ const adapter = new WhatsAppWebJsAdapter({+ sessionId: 's',+ sessionDataPath: './data/sessions',+ puppeteer: {},+ proxy: { url: 'socks5://proxy.invalid:1080', type: 'socks5' },+ });+ (adapter as unknown as { status: EngineStatus }).status = EngineStatus.READY;+ (adapter as unknown as { client: unknown }).client = { sendMessage: jest.fn().mockResolvedValue(sentMessage) };++ await adapter.sendImageMessage('[email protected]', {+ mimetype: 'image/png',+ data: 'https://files.example.com/photo.jpg',+ });++ expect(load).toHaveBeenCalledWith('https://files.example.com/photo.jpg', 'socks5://proxy.invalid:1080');+ load.mockRestore();+ });+// The DTO fills this in when the client said nothing, so it is a placeholder rather than a claim// about the bytes — the response has to win, or every URL send would go out as a generic blob.it('lets the response win when the declared mimetype is the octet-stream placeholder', async () => {diff --git a/src/engine/adapters/wwebjs-groups.ts b/src/engine/adapters/wwebjs-groups.tsindex d2c9a8f8b..b0f391755 100644--- a/src/engine/adapters/wwebjs-groups.ts+++ b/src/engine/adapters/wwebjs-groups.ts@@ -470,7 +470,7 @@ export class WwebjsGroups {async setGroupPicture(groupId: string, media: MediaInput): Promise<void> {const groupChat = await this.requireGroupChat(groupId);// GroupChat.setPicture, NOT Client.setProfilePicture — the latter targets the own account.- const ok = await groupChat.setPicture(await toMessageMedia(media));+ const ok = await groupChat.setPicture(await toMessageMedia(media, this.host.config.proxy?.url));if (!ok) {throw new EngineRefusedError(`Failed to set the picture for group ${groupId} — admin rights required`);}diff --git a/src/engine/adapters/wwebjs-messaging.ts b/src/engine/adapters/wwebjs-messaging.tsindex 50b807fa5..2cc971b63 100644--- a/src/engine/adapters/wwebjs-messaging.ts+++ b/src/engine/adapters/wwebjs-messaging.ts@@ -81,12 +81,14 @@ export function isHttpUrl(value: string): boolean {* bound memory use and hang time. `unsafeMime` is left at its default (false) to preserve the* existing MIME-detection behavior.*/-export async function loadRemoteMedia(url: string): Promise<MessageMedia> {+export async function loadRemoteMedia(url: string, sessionProxyUrl: string | undefined): Promise<MessageMedia> {// Fetch through the SSRF-pinned path: it validates the host, pins the connection to the vetted IP// (so a DNS rebind can't redirect it to an internal target between check and connect), caps bytes,// and refuses redirects. We then build the MessageMedia from the returned bytes — NOT via// MessageMedia.fromUrl, whose bundled node-fetch performs its own unpinned DNS re-resolution.- const { data, mimetype } = await loadRemoteMediaBuffer(url);+ // `sessionProxyUrl` routes the fetch through this session's egress proxy (#1626); the browser's+ // own requests already ride Chromium's --proxy-server, this one is made by the gateway itself.+ const { data, mimetype } = await loadRemoteMediaBuffer(url, sessionProxyUrl);const filename = new URL(url).pathname.split('/').pop() || undefined;return new MessageMedia(mimetype || 'application/octet-stream', data.toString('base64'), filename);}@@ -121,9 +123,13 @@ export function isQuoteUnresolvedError(err: unknown): boolean {* that one decision it is the better source. The declared filename still wins either way — that is* a label, and nothing branches on it.*/-export async function toMessageMedia(media: MediaInput, opts?: { trustDeclaredType?: boolean }): Promise<MessageMedia> {+export async function toMessageMedia(+ media: MediaInput,+ sessionProxyUrl: string | undefined,+ opts?: { trustDeclaredType?: boolean },+): Promise<MessageMedia> {if (typeof media.data === 'string' && isHttpUrl(media.data)) {- const fetched = await loadRemoteMedia(media.data);+ const fetched = await loadRemoteMedia(media.data, sessionProxyUrl);// `loadRemoteMedia` derives both fields from the response (content-type, URL basename) because// that is all it has. The caller usually knows better, so let an explicit `mimetype`/`filename`// win — matching `resolveMediaBuffer` on the Baileys adapter, which already prefers the caller's.@@ -419,7 +425,7 @@ export class WwebjsMessaging {this.host.ensureNotChannelRecipient(chatId);// Build the media once (a remote URL is fetched here); sendResolved may retry the send itself.- const messageMedia = await toMessageMedia(media);+ const messageMedia = await toMessageMedia(media, this.host.config.proxy?.url);// A nameless document reaches WA Web as `new File([blob], undefined)` and is labelled literally// "undefined". Only documents render a filename, so default just this path — as Baileys does.if (extraOptions?.sendMediaAsDocument && !messageMedia.filename) {@@ -486,7 +492,7 @@ export class WwebjsMessaging {this.host.ensureNotChannelRecipient(chatId);// Keep the fetched content-type for a remote URL: here the mimetype selects the conversion, and// whatsapp-web.js returns the media unconverted once it reads as webp (Util.formatImageToWebpSticker).- const messageMedia = await toMessageMedia(media, { trustDeclaredType: false });+ const messageMedia = await toMessageMedia(media, this.host.config.proxy?.url, { trustDeclaredType: false });const msg = await this.sendResolved(chatId,diff --git a/src/engine/adapters/wwebjs-profile.ts b/src/engine/adapters/wwebjs-profile.tsindex 45e69242a..dd4fc606a 100644--- a/src/engine/adapters/wwebjs-profile.ts+++ b/src/engine/adapters/wwebjs-profile.ts@@ -73,7 +73,7 @@ export class WwebjsProfile {async setProfilePicture(media: MediaInput): Promise<void> {this.host.ensureReady();- const messageMedia = await toMessageMedia(media);+ const messageMedia = await toMessageMedia(media, this.host.config.proxy?.url);// setProfilePicture resolves false (rather than throwing) when the upload is refused.const ok = await this.withPage('setProfilePicture', () => this.client().setProfilePicture(messageMedia));if (!ok) {diff --git a/src/engine/adapters/wwebjs-status.ts b/src/engine/adapters/wwebjs-status.tsindex 87ef5f272..da79f7137 100644--- a/src/engine/adapters/wwebjs-status.ts+++ b/src/engine/adapters/wwebjs-status.ts@@ -180,7 +180,7 @@ export class WwebjsStatus {): Promise<StatusResult> {this.host.ensureReady();this.warnStatusRecipientsOnce(options);- const messageMedia = await toMessageMedia(media);+ const messageMedia = await toMessageMedia(media, this.host.config.proxy?.url);// Non-idempotent: a replayed post would publish the status twice. See reportPageDeath.const msg = await reportPageDeath(this.host, 'postMediaStatus', () =>this.client().sendMessage('status@broadcast', messageMedia, {diff --git a/src/engine/engine-registry.service.spec.ts b/src/engine/engine-registry.service.spec.tsindex 34473153b..2aab48ef3 100644--- a/src/engine/engine-registry.service.spec.ts+++ b/src/engine/engine-registry.service.spec.ts@@ -46,6 +46,50 @@ describe('EngineRegistry', () => {expect(registry.entries()).toEqual([]);});+ /**+ * The proxy travels with the engine because it is fixed for that engine's life: `PATCH /proxy`+ * edits the row without restarting, so a fetch made for a running session has to use what the+ * engine was started with rather than what the row now says (#1626).+ */+ describe('the egress proxy of the live engine', () => {+ it('remembers the proxy the engine was registered with', () => {+ registry.set('s1', engineStub('a'), 'socks5://proxy.invalid:1080');++ expect(registry.proxyUrl('s1')).toBe('socks5://proxy.invalid:1080');+ });++ it('reports no proxy for a direct session and for one that was never started', () => {+ registry.set('s1', engineStub('a'));++ expect(registry.proxyUrl('s1')).toBeUndefined();+ expect(registry.proxyUrl('never-started')).toBeUndefined();+ });++ it('takes the new proxy when a reconnect replaces the engine', () => {+ registry.set('s1', engineStub('first'), 'http://old.invalid:8080');+ registry.set('s1', engineStub('second'), 'socks5://new.invalid:1080');++ expect(registry.proxyUrl('s1')).toBe('socks5://new.invalid:1080');+ });++ it('forgets it on delete, deleteIfLive and clear, so a stopped session keeps no egress', () => {+ const live = engineStub('live');+ registry.set('s1', engineStub('a'), 'http://a.invalid:8080');+ registry.delete('s1');+ expect(registry.proxyUrl('s1')).toBeUndefined();++ registry.set('s2', live, 'http://b.invalid:8080');+ registry.deleteIfLive('s2', engineStub('superseded'));+ expect(registry.proxyUrl('s2')).toBe('http://b.invalid:8080'); // not the live engine: kept+ registry.deleteIfLive('s2', live);+ expect(registry.proxyUrl('s2')).toBeUndefined();++ registry.set('s3', engineStub('c'), 'http://c.invalid:8080');+ registry.clear();+ expect(registry.proxyUrl('s3')).toBeUndefined();+ });+ });+it('entries() snapshots the map so callers can tear down while it mutates', () => {const a = engineStub('a');registry.set('s1', a);diff --git a/src/engine/engine-registry.service.ts b/src/engine/engine-registry.service.tsindex 5a1cfca91..30f1d82e7 100644--- a/src/engine/engine-registry.service.ts+++ b/src/engine/engine-registry.service.ts@@ -21,6 +21,17 @@ export class EngineRegistry {/** Live engines by session (DB) id. Presence here means "started"; identity means "not superseded". */private readonly engines = new Map<string, IWhatsAppEngine>();+ /**+ * The egress proxy each live engine was created with, by session (DB) id.+ *+ * A session's proxy is fixed for the life of its engine: the WebSocket, the browser and the fetch+ * dispatcher are all built from it at start, and `PATCH /proxy` deliberately does not restart the+ * engine, so the stored row can already name a different one. Anything that fetches ON BEHALF of a+ * running session (a caller-supplied media URL) has to leave through THIS value, not the row, or+ * the destination would see an address the rest of the session never uses.+ */+ private readonly proxies = new Map<string, string | undefined>();+/*** Sessions whose engine is being constructed but is not in `engines` yet. Held so concurrency* accounting and the infra import pre-flight can see a session that is starting but not yet@@ -38,8 +49,15 @@ export class EngineRegistry {return this.engines.get(id);}- set(id: string, engine: IWhatsAppEngine): void {+ /**+ * Register the live engine for a session together with the proxy it was started with. A new+ * production call site must pass that proxy: `proxyUrl(id)` is what keeps a fetch made for a+ * proxied session off the gateway's own address (#1626), and an omitted argument records "direct".+ * It stays optional only because the specs that register a bare engine stub do not care.+ */+ set(id: string, engine: IWhatsAppEngine, proxyUrl?: string): void {this.engines.set(id, engine);+ this.proxies.set(id, proxyUrl);}has(id: string): boolean {@@ -47,11 +65,13 @@ export class EngineRegistry {}delete(id: string): boolean {+ this.proxies.delete(id);return this.engines.delete(id);}clear(): void {this.engines.clear();+ this.proxies.clear();}get size(): number {@@ -94,7 +114,16 @@ export class EngineRegistry {if (!this.isLive(id, engine)) {return false;}- return this.engines.delete(id);+ return this.delete(id);+ }++ /**+ * The egress proxy the live engine for `id` was started with, or undefined when that session is+ * direct OR has no live engine. A caller that must not fetch direct for a proxied session pairs+ * this with the stored row; see `MediaConversionService.sessionProxy`.+ */+ proxyUrl(id: string): string | undefined {+ return this.proxies.get(id);}// ── Consumer-facing accessor ──────────────────────────────────────────diff --git a/src/modules/media/media-conversion.service.spec.ts b/src/modules/media/media-conversion.service.spec.tsindex 08f23205d..12f01a845 100644--- a/src/modules/media/media-conversion.service.spec.ts+++ b/src/modules/media/media-conversion.service.spec.ts@@ -1,6 +1,14 @@-import { BadRequestException, PayloadTooLargeException, ServiceUnavailableException } from '@nestjs/common';+import {+ BadRequestException,+ HttpException,+ PayloadTooLargeException,+ ServiceUnavailableException,+} from '@nestjs/common';import { ConfigService } from '@nestjs/config';+import { Repository } from 'typeorm';import { MediaConversionService } from './media-conversion.service';+import { EngineRegistry } from '../../engine/engine-registry.service';+import { Session } from '../session/entities/session.entity';import * as ffmpeg from './ffmpeg';import * as loadRemoteMedia from '../../common/media/load-remote-media';@@ -22,6 +30,33 @@ describe('MediaConversionService', () => {return { get: (key: string, fallback?: unknown) => values[key] ?? fallback } as unknown as ConfigService;};+ /** Route param of every call below: conversion is session-scoped even though it needs no engine. */+ const SESSION = '11111111-1111-4111-8111-111111111111';++ /** The session-row read, so a case can assert whether the row was consulted at all. */+ const findOne = jest.fn();++ /**+ * The service with a real (empty) engine registry and no session row, which is what every case+ * except the egress-proxy ones needs.+ */+ const makeService = (+ configService: ConfigService = config(),+ opts: { registry?: EngineRegistry; row?: Pick<Session, 'proxyUrl'> | null } = {},+ ): MediaConversionService => {+ findOne.mockResolvedValue(opts.row ?? null);+ return new MediaConversionService(configService, opts.registry ?? new EngineRegistry(), {+ findOne,+ } as unknown as Repository<Session>);+ };++ /** A registry holding a live engine for SESSION, started with the given proxy. */+ const registryWith = (proxyUrl?: string): EngineRegistry => {+ const registry = new EngineRegistry();+ registry.set(SESSION, {} as never, proxyUrl);+ return registry;+ };+/** runFfmpeg(input, inputExtension, outputExtension, ...) — the third argument fixes the format. */const outputExtensionOf = (spy: jest.SpyInstance): unknown => (spy.mock.calls[0] as unknown[])[2];@@ -29,6 +64,7 @@ describe('MediaConversionService', () => {let probeFfmpeg: jest.SpyInstance;beforeEach(() => {+ findOne.mockReset();runFfmpeg = jest.spyOn(ffmpeg, 'runFfmpeg').mockResolvedValue(Buffer.from('converted-bytes'));probeFfmpeg = jest.spyOn(ffmpeg, 'probeFfmpeg').mockResolvedValue(true);});@@ -36,9 +72,11 @@ describe('MediaConversionService', () => {describe('availability', () => {it('refuses with 503 when conversion is switched off, without probing for the binary', async () => {- const service = new MediaConversionService(config({ 'mediaConversion.enabled': false }));+ const service = makeService(config({ 'mediaConversion.enabled': false }));- await expect(service.convertToVoice({ base64: 'AAAA' })).rejects.toBeInstanceOf(ServiceUnavailableException);+ await expect(service.convertToVoice(SESSION, { base64: 'AAAA' })).rejects.toBeInstanceOf(+ ServiceUnavailableException,+ );expect(probeFfmpeg).not.toHaveBeenCalled();expect(runFfmpeg).not.toHaveBeenCalled();});@@ -46,24 +84,28 @@ describe('MediaConversionService', () => {// Enabling the flag on a host with no ffmpeg must be a clear answer, not a spawn error.it('refuses with 503 when the binary cannot be run', async () => {probeFfmpeg.mockResolvedValue(false);- const service = new MediaConversionService(config());+ const service = makeService(config());- await expect(service.convertToVoice({ base64: 'AAAA' })).rejects.toThrow(/ffmpeg binary could not be run/);+ await expect(service.convertToVoice(SESSION, { base64: 'AAAA' })).rejects.toThrow(+ /ffmpeg binary could not be run/,+ );expect(runFfmpeg).not.toHaveBeenCalled();});it('reports availability without converting anything', async () => {- await expect(new MediaConversionService(config()).isAvailable()).resolves.toBe(true);- await expect(- new MediaConversionService(config({ 'mediaConversion.enabled': false })).isAvailable(),- ).resolves.toBe(false);+ await expect(makeService(config()).isAvailable()).resolves.toBe(true);+ await expect(makeService(config({ 'mediaConversion.enabled': false })).isAvailable()).resolves.toBe(false);});// Concurrent first requests must not each spawn their own probe.it('probes the binary once per process, even under concurrent first calls', async () => {- const service = new MediaConversionService(config());+ const service = makeService(config());- await Promise.all([service.isAvailable(), service.isAvailable(), service.convertToVoice({ base64: 'AAAA' })]);+ await Promise.all([+ service.isAvailable(),+ service.isAvailable(),+ service.convertToVoice(SESSION, { base64: 'AAAA' }),+ ]);expect(probeFfmpeg).toHaveBeenCalledTimes(1);});@@ -76,51 +118,128 @@ describe('MediaConversionService', () => {const load = jest.spyOn(loadRemoteMedia, 'loadRemoteMediaBuffer').mockResolvedValue({ data: Buffer.from('remote-audio'), mimetype: 'audio/mpeg' });- const service = new MediaConversionService(config());+ const service = makeService(config());- await service.convertToVoice({ url: 'https://example.com/note.m4a' });+ await service.convertToVoice(SESSION, { url: 'https://example.com/note.m4a' });- expect(load).toHaveBeenCalledWith('https://example.com/note.m4a');+ expect(load).toHaveBeenCalledWith('https://example.com/note.m4a', undefined);const [input] = runFfmpeg.mock.calls[0] as [Buffer];expect(input).toEqual(Buffer.from('remote-audio'));// Nothing resembling the URL may appear anywhere in the ffmpeg call.expect(JSON.stringify(runFfmpeg.mock.calls[0])).not.toContain('example.com');});+ /**+ * A conversion is a fetch the gateway makes on a session's behalf, so it has to leave from that+ * session's address rather than the gateway's own (#1626). The live engine's proxy is the+ * authority: PATCH /proxy does not restart the engine, so the row can already say something the+ * running session does not use.+ */+ describe('the egress proxy of the named session', () => {+ const loadSpy = (): jest.SpyInstance =>+ jest+ .spyOn(loadRemoteMedia, 'loadRemoteMediaBuffer')+ .mockResolvedValue({ data: Buffer.from('remote-audio'), mimetype: 'audio/mpeg' });++ it('uses the proxy the running engine was started with, not the stored row', async () => {+ const load = loadSpy();+ const service = makeService(config(), {+ registry: registryWith('socks5://live.invalid:1080'),+ row: { proxyUrl: 'http://edited-since.invalid:8080' },+ });++ await service.convertToVoice(SESSION, { url: 'https://example.com/note.m4a' });++ expect(load).toHaveBeenCalledWith('https://example.com/note.m4a', 'socks5://live.invalid:1080');+ });++ it('fetches direct for a running session that has no proxy, whatever the row says', async () => {+ const load = loadSpy();+ const service = makeService(config(), {+ registry: registryWith(undefined),+ row: { proxyUrl: 'http://not-in-use.invalid:8080' },+ });++ await service.convertToVoice(SESSION, { url: 'https://example.com/note.m4a' });++ expect(load).toHaveBeenCalledWith('https://example.com/note.m4a', undefined);+ });++ it('falls back to the stored proxy when the session has no live engine', async () => {+ const load = loadSpy();+ const service = makeService(config(), { row: { proxyUrl: 'socks4://stored.invalid:1080' } });++ await service.convertToVoice(SESSION, { url: 'https://example.com/note.m4a' });++ expect(load).toHaveBeenCalledWith('https://example.com/note.m4a', 'socks4://stored.invalid:1080');+ });++ // Ids are generated uuids; anything else matches no row, and asking Postgres would raise on+ // the cast rather than answer.+ it('does not query the row for a session id that cannot be one', async () => {+ const load = loadSpy();+ const service = makeService();++ await service.convertToVoice('not-a-uuid', { url: 'https://example.com/note.m4a' });++ expect(findOne).not.toHaveBeenCalled();+ expect(load).toHaveBeenCalledWith('https://example.com/note.m4a', undefined);+ });++ // The row read is server-side I/O, not part of the caller's input. Mapped as a bad URL it+ // would answer 400 with the driver's own message, telling a client to stop retrying a+ // failover or a locked SQLite file.+ it('does not report a failed row read as a bad URL', async () => {+ const load = loadSpy();+ const service = makeService();+ findOne.mockRejectedValue(new Error('SQLITE_BUSY: database is locked'));++ const failure: unknown = await service+ .convertToVoice(SESSION, { url: 'https://example.com/note.m4a' })+ .catch((error: unknown) => error);++ expect(failure).not.toBeInstanceOf(HttpException);+ expect(failure).toMatchObject({ message: 'SQLITE_BUSY: database is locked' });+ expect(load).not.toHaveBeenCalled();+ });+ });+it('decodes base64, stripping a data: prefix', async () => {- const service = new MediaConversionService(config());+ const service = makeService(config());- await service.convertToVoice({ base64: `data:audio/mpeg;base64,${Buffer.from('inline').toString('base64')}` });+ await service.convertToVoice(SESSION, {+ base64: `data:audio/mpeg;base64,${Buffer.from('inline').toString('base64')}`,+ });expect((runFfmpeg.mock.calls[0] as [Buffer])[0]).toEqual(Buffer.from('inline'));});it('rejects base64 above the media cap with 413, before any conversion', async () => {- const service = new MediaConversionService(config());+ const service = makeService(config());const oversized = Buffer.alloc(51 * 1024 * 1024).toString('base64');- await expect(service.convertToVoice({ base64: oversized })).rejects.toBeInstanceOf(PayloadTooLargeException);+ await expect(service.convertToVoice(SESSION, { base64: oversized })).rejects.toBeInstanceOf(+ PayloadTooLargeException,+ );expect(runFfmpeg).not.toHaveBeenCalled();});it('rejects a request carrying neither url nor base64', async () => {- await expect(new MediaConversionService(config()).convertToVoice({})).rejects.toThrow(+ await expect(makeService(config()).convertToVoice(SESSION, {})).rejects.toThrow(/Either url or base64 must be provided/,);});it('rejects base64 that decodes to nothing', async () => {- await expect(new MediaConversionService(config()).convertToVoice({ base64: '!!!' })).rejects.toThrow(- /did not decode/,- );+ await expect(makeService(config()).convertToVoice(SESSION, { base64: '!!!' })).rejects.toThrow(/did not decode/);});});describe('conversion', () => {it('returns Ogg/Opus for voice, which is what makes a playable mic bubble', async () => {- const service = new MediaConversionService(config());+ const service = makeService(config());- const result = await service.convertToVoice({ base64: 'AAAA' });+ const result = await service.convertToVoice(SESSION, { base64: 'AAAA' });expect(result).toEqual({base64: Buffer.from('converted-bytes').toString('base64'),@@ -131,9 +250,9 @@ describe('MediaConversionService', () => {});it('returns MP4 for video', async () => {- const service = new MediaConversionService(config());+ const service = makeService(config());- const result = await service.convertToVideo({ base64: 'AAAA' });+ const result = await service.convertToVideo(SESSION, { base64: 'AAAA' });expect(result.mimetype).toBe('video/mp4');expect(outputExtensionOf(runFfmpeg)).toBe('mp4');@@ -142,18 +261,18 @@ describe('MediaConversionService', () => {// ffmpeg's complaint is about the caller's own bytes, so surfacing it is what makes a 400 useful.it('turns an ffmpeg refusal into a 400 carrying its reason', async () => {runFfmpeg.mockRejectedValue(new ffmpeg.FfmpegConversionError('ffmpeg exited with code 1', 'Invalid data found'));- const service = new MediaConversionService(config());+ const service = makeService(config());- await expect(service.convertToVoice({ base64: 'AAAA' })).rejects.toBeInstanceOf(BadRequestException);- await expect(service.convertToVoice({ base64: 'AAAA' })).rejects.toThrow(/Invalid data found/);+ await expect(service.convertToVoice(SESSION, { base64: 'AAAA' })).rejects.toBeInstanceOf(BadRequestException);+ await expect(service.convertToVoice(SESSION, { base64: 'AAAA' })).rejects.toThrow(/Invalid data found/);});// A programming error must not be relabelled as the caller's fault.it('lets an unexpected error through rather than reporting it as a bad request', async () => {runFfmpeg.mockRejectedValue(new TypeError('boom'));- const service = new MediaConversionService(config());+ const service = makeService(config());- await expect(service.convertToVoice({ base64: 'AAAA' })).rejects.toBeInstanceOf(TypeError);+ await expect(service.convertToVoice(SESSION, { base64: 'AAAA' })).rejects.toBeInstanceOf(TypeError);});});@@ -162,7 +281,7 @@ describe('MediaConversionService', () => {// up while each runs toward its timeout — that bound lives here.it('bounds concurrent ffmpeg runs and answers 503 past the queue instead of stacking processes', async () => {// concurrency 1 → queue depth 4: five simultaneous requests fill the gate, the sixth is refused.- const service = new MediaConversionService(config({ 'mediaConversion.concurrency': 1 }));+ const service = makeService(config({ 'mediaConversion.concurrency': 1 }));let release!: () => void;runFfmpeg.mockImplementation(() =>@@ -171,11 +290,13 @@ describe('MediaConversionService', () => {}),);- const inflight = Array.from({ length: 5 }, () => service.convertToVoice({ base64: 'AAAA' }));+ const inflight = Array.from({ length: 5 }, () => service.convertToVoice(SESSION, { base64: 'AAAA' }));await new Promise(resolve => setImmediate(resolve));expect(runFfmpeg).toHaveBeenCalledTimes(1);- await expect(service.convertToVoice({ base64: 'AAAA' })).rejects.toBeInstanceOf(ServiceUnavailableException);+ await expect(service.convertToVoice(SESSION, { base64: 'AAAA' })).rejects.toBeInstanceOf(+ ServiceUnavailableException,+ );// Drain: release each run in turn so every parked task completes and nothing leaks.for (let i = 0; i < 5; i++) {diff --git a/src/modules/media/media-conversion.service.ts b/src/modules/media/media-conversion.service.tsindex c2d42009e..973f47ec9 100644--- a/src/modules/media/media-conversion.service.ts+++ b/src/modules/media/media-conversion.service.ts@@ -1,6 +1,11 @@import { BadRequestException, HttpException, Injectable, ServiceUnavailableException } from '@nestjs/common';import { ConfigService } from '@nestjs/config';+import { InjectRepository } from '@nestjs/typeorm';+import { isUUID } from 'class-validator';+import { Repository } from 'typeorm';import { createLogger } from '../../common/services/logger.service';+import { EngineRegistry } from '../../engine/engine-registry.service';+import { Session } from '../session/entities/session.entity';import { loadRemoteMediaBuffer } from '../../common/media/load-remote-media';import { SsrfBlockedError, SSRF_BLOCKED_CLIENT_MESSAGE } from '../../common/security/ssrf-guard';import { ConcurrencyLimiter } from '../../common/utils/concurrency-limiter';@@ -31,7 +36,12 @@ export class MediaConversionService {*/private readonly ffmpegGate: ConcurrencyLimiter;- constructor(private readonly configService: ConfigService) {+ constructor(+ private readonly configService: ConfigService,+ private readonly engines: EngineRegistry,+ @InjectRepository(Session, 'data')+ private readonly sessionRepository: Repository<Session>,+ ) {const concurrency = this.configService.get<number>('mediaConversion.concurrency', 2);this.ffmpegGate = new ConcurrencyLimiter(concurrency, concurrency * 4);}@@ -44,13 +54,13 @@ export class MediaConversionService {* applied when no mimetype is given — the declared type and the actual bytes disagree, and the* recipient sees a voice note that will not play.*/- async convertToVoice(dto: ConvertMediaDto): Promise<ConvertedMedia> {- return this.convert(dto, 'ogg', voiceEncodeArgs(), 'audio/ogg; codecs=opus');+ async convertToVoice(sessionId: string, dto: ConvertMediaDto): Promise<ConvertedMedia> {+ return this.convert(sessionId, dto, 'ogg', voiceEncodeArgs(), 'audio/ogg; codecs=opus');}/** Convert to an MP4 WhatsApp will accept and preview on every client. */- async convertToVideo(dto: ConvertMediaDto): Promise<ConvertedMedia> {- return this.convert(dto, 'mp4', videoEncodeArgs(), 'video/mp4');+ async convertToVideo(sessionId: string, dto: ConvertMediaDto): Promise<ConvertedMedia> {+ return this.convert(sessionId, dto, 'mp4', videoEncodeArgs(), 'video/mp4');}/** Whether conversion is both switched on and actually runnable on this host. */@@ -60,13 +70,14 @@ export class MediaConversionService {}private async convert(+ sessionId: string,dto: ConvertMediaDto,outputExtension: string,encodeArgs: string[],outputMimetype: string,): Promise<ConvertedMedia> {await this.assertAvailable();- const input = await this.resolveInput(dto);+ const input = await this.resolveInput(sessionId, dto);try {const output = await this.ffmpegGate.run(() =>@@ -93,8 +104,29 @@ export class MediaConversionService {}}+ /**+ * The egress proxy a URL fetch made for this session must leave through.+ *+ * A running engine's proxy wins, including when it is none: it is the address every other byte of+ * that session leaves from, and `PATCH /proxy` can have changed the row since without restarting+ * the engine. With no engine running there is no such egress, so the stored row is used instead,+ * which keeps the fetch off the gateway's own address for a session an operator has proxied.+ */+ private async sessionProxy(sessionId: string): Promise<string | undefined> {+ if (this.engines.has(sessionId)) {+ return this.engines.proxyUrl(sessionId);+ }+ // Ids are generated uuids, so anything else matches no row; asking Postgres would raise on the+ // cast instead of answering "no session".+ if (!isUUID(sessionId)) {+ return undefined;+ }+ const session = await this.sessionRepository.findOne({ where: { id: sessionId }, select: { proxyUrl: true } });+ return session?.proxyUrl ?? undefined;+ }+/** Read the caller's media into memory, honouring the same caps and SSRF guard as a send. */- private async resolveInput(dto: ConvertMediaDto): Promise<Buffer> {+ private async resolveInput(sessionId: string, dto: ConvertMediaDto): Promise<Buffer> {if (dto.base64) {// Checked before decoding, so an oversized payload is refused without allocating it.assertBase64WithinMediaCap(dto.base64);@@ -105,9 +137,14 @@ export class MediaConversionService {if (dto.url) {// Through the SSRF guard, exactly as a send does: it validates the host and pins the// connection to the vetted address. ffmpeg itself never sees a URL — it is restricted to the- // file protocol and handed bytes this process already fetched and checked.+ // file protocol and handed bytes this process already fetched and checked. It also leaves+ // through the named session's proxy, exactly as a send by URL does (#1626).+ // Resolved BEFORE the try, which exists to map a bad URL to a 400: a session-row read that+ // fails is a server fault, and reporting it as a bad URL (with the driver's own message+ // attached) would tell a client not to retry something transient.+ const proxyUrl = await this.sessionProxy(sessionId);try {- const { data } = await loadRemoteMediaBuffer(dto.url);+ const { data } = await loadRemoteMediaBuffer(dto.url, proxyUrl);return data;} catch (error) {// The fetch layer throws plain Errors (bad status, over the byte cap) and SsrfBlockedError,diff --git a/src/modules/media/media.controller.spec.ts b/src/modules/media/media.controller.spec.tsindex 6f06b5096..983ebd473 100644--- a/src/modules/media/media.controller.spec.ts+++ b/src/modules/media/media.controller.spec.ts@@ -68,18 +68,22 @@ describe('MediaController', () => {});describe('delegation', () => {- it('passes the body straight to the voice conversion', async () => {+ it('passes the body and the session id straight to the voice conversion', async () => {const dto = { base64: 'AAAA' };- await expect(controller.convertVoice(dto)).resolves.toMatchObject({ mimetype: 'audio/ogg; codecs=opus' });- expect(convertToVoice).toHaveBeenCalledWith(dto);+ await expect(controller.convertVoice('session-1', dto)).resolves.toMatchObject({+ mimetype: 'audio/ogg; codecs=opus',+ });+ expect(convertToVoice).toHaveBeenCalledWith('session-1', dto);});- it('passes the body straight to the video conversion', async () => {+ // The session id is what a URL conversion resolves its egress proxy from, so it must reach the+ // service rather than being consumed by the guard alone.+ it('passes the body and the session id straight to the video conversion', async () => {const dto = { url: 'https://example.com/clip.mov' };- await expect(controller.convertVideo(dto)).resolves.toMatchObject({ mimetype: 'video/mp4' });- expect(convertToVideo).toHaveBeenCalledWith(dto);+ await expect(controller.convertVideo('session-1', dto)).resolves.toMatchObject({ mimetype: 'video/mp4' });+ expect(convertToVideo).toHaveBeenCalledWith('session-1', dto);});it('reports availability as a plain flag', async () => {diff --git a/src/modules/media/media.controller.ts b/src/modules/media/media.controller.tsindex 78797df82..719900ea7 100644--- a/src/modules/media/media.controller.ts+++ b/src/modules/media/media.controller.ts@@ -1,4 +1,4 @@-import { Body, Controller, Get, HttpCode, HttpStatus, Post } from '@nestjs/common';+import { Body, Controller, Get, HttpCode, HttpStatus, Param, Post } from '@nestjs/common';import { ApiOperation, ApiParam, ApiResponse, ApiTags } from '@nestjs/swagger';import { ConversionStatusResponseDto, ConvertedMediaResponseDto } from './dto/media-response.dto';import { MediaConversionService } from './media-conversion.service';@@ -9,15 +9,17 @@ import { ApiKeyRole } from '../auth/entities/api-key.entity';/*** Server-side transcoding, scoped to a session.*- * Conversion itself needs no session — it never touches WhatsApp. The session dimension is kept- * because this project's API keys can be restricted to specific sessions, and the guard resolves- * that restriction from route parameters: a deployment-global route would have to be marked+ * Conversion never touches WhatsApp, so it needs no running engine. The session dimension is kept+ * for two reasons. This project's API keys can be restricted to specific sessions, and the guard+ * resolves that restriction from route parameters: a deployment-global route would have to be marked* unscoped, which would shut session-restricted keys out of a feature they need in order to send.+ * And the named session decides which egress proxy a `url` conversion leaves through (#1626), so a+ * proxied session's fetch does not go out from the gateway's own address.*/@ApiTags('media')-// Declared on the class because no handler binds the parameter — conversion needs no session id, only-// the guard does (see above). Without this the published paths carry a `{sessionId}` template with no-// parameter to fill it, which OpenAPI 3.0 does not allow and a generated client cannot satisfy.+// Declared on the class because the handlers take the id without an `@ApiParam` of their own. Without+// this the published paths carry a `{sessionId}` template with no parameter to fill it, which OpenAPI+// 3.0 does not allow and a generated client cannot satisfy.@ApiParam({ name: 'sessionId', type: String, description: 'Session ID the API key must be authorized for' })@Controller('sessions/:sessionId/media')export class MediaController {@@ -55,8 +57,8 @@ export class MediaController {description:'Conversion is disabled, the ffmpeg binary is not runnable, or the conversion queue is saturated — retry shortly.',})- async convertVoice(@Body() dto: ConvertMediaDto) {- return this.mediaConversion.convertToVoice(dto);+ async convertVoice(@Param('sessionId') sessionId: string, @Body() dto: ConvertMediaDto) {+ return this.mediaConversion.convertToVoice(sessionId, dto);}@Post('convert/video')@@ -77,7 +79,7 @@ export class MediaController {description:'Conversion is disabled, the ffmpeg binary is not runnable, or the conversion queue is saturated — retry shortly.',})- async convertVideo(@Body() dto: ConvertMediaDto) {- return this.mediaConversion.convertToVideo(dto);+ async convertVideo(@Param('sessionId') sessionId: string, @Body() dto: ConvertMediaDto) {+ return this.mediaConversion.convertToVideo(sessionId, dto);}}diff --git a/src/modules/media/media.module.ts b/src/modules/media/media.module.tsindex b3bcdf14d..d89ad9761 100644--- a/src/modules/media/media.module.ts+++ b/src/modules/media/media.module.ts@@ -1,8 +1,13 @@import { Module } from '@nestjs/common';+import { TypeOrmModule } from '@nestjs/typeorm';import { MediaController } from './media.controller';import { MediaConversionService } from './media-conversion.service';+import { Session } from '../session/entities/session.entity';@Module({+ // The session row is read for one field: the egress proxy a URL conversion must leave through+ // when the named session has no live engine to take it from.+ imports: [TypeOrmModule.forFeature([Session], 'data')],controllers: [MediaController],providers: [MediaConversionService],exports: [MediaConversionService],diff --git a/src/modules/session/session-engine-lifecycle.service.ts b/src/modules/session/session-engine-lifecycle.service.tsindex d57332ec4..3d7bf8722 100644--- a/src/modules/session/session-engine-lifecycle.service.ts+++ b/src/modules/session/session-engine-lifecycle.service.ts@@ -577,7 +577,9 @@ export class SessionEngineLifecycle {proxyUrl: session.proxyUrl || undefined,proxyType: session.proxyType || undefined,});- this.engines.set(id, engine);+ // The proxy is registered with the engine, not re-read from the row later: it is the egress this+ // engine will use until it is replaced, and a fetch made on the session's behalf must match it.+ this.engines.set(id, engine, session.proxyUrl || undefined);// Presence subscriptions live on the socket, so a fresh engine has none — whatever the previous// connection last reported is now unverifiable and would be served as if it were current.this.presence.clear(id);diff --git a/src/modules/session/session.service.spec.ts b/src/modules/session/session.service.spec.tsindex d0f17ffae..41b17aac7 100644--- a/src/modules/session/session.service.spec.ts+++ b/src/modules/session/session.service.spec.ts@@ -95,6 +95,8 @@ describe('SessionService', () => {// The engine-lifecycle verbs/state moved out of SessionService (god-object split); the white-box// pokes below target the lifecycle owner directly, the public-API tests stay on `service`.let lifecycle: SessionEngineLifecycle;+ /** The real registry the service writes to, read directly for the live-engine proxy snapshot. */+ let registry: EngineRegistry;let repository: jest.Mocked<Partial<Repository<Session>>>;let messageRepository: jest.Mocked<Partial<Repository<Message>>>;let dataSource: jest.Mocked<Partial<DataSource>>;@@ -264,6 +266,7 @@ describe('SessionService', () => {service = module.get<SessionService>(SessionService);lifecycle = module.get<SessionEngineLifecycle>(SessionEngineLifecycle);+ registry = module.get<EngineRegistry>(EngineRegistry);});// ── shutdown ──────────────────────────────────────────────────────@@ -1153,6 +1156,18 @@ describe('SessionService', () => {});});+ // Anything the gateway fetches on a running session's behalf has to leave through the proxy that+ // session actually started with, which the row alone cannot answer: PATCH /proxy edits the row+ // without restarting the engine (#1626).+ it('records the proxy the engine was created with alongside the engine', async () => {+ (repository.findOne as jest.Mock).mockResolvedValue(createMockSession({ proxyUrl: 'socks5://p.invalid:1080' }));+ (repository.update as jest.Mock).mockResolvedValue({ affected: 1 });++ await service.start('sess-uuid-1');++ expect(registry.proxyUrl('sess-uuid-1')).toBe('socks5://p.invalid:1080');+ });+it('should throw BadRequestException if session already started', async () => {const session = createMockSession();(repository.findOne as jest.Mock).mockResolvedValue(session);diff --git a/test/helpers/socks-proxy-servers.ts b/test/helpers/socks-proxy-servers.tsnew file mode 100644index 000000000..3f55776e5--- /dev/null+++ b/test/helpers/socks-proxy-servers.ts@@ -0,0 +1,199 @@+import * as net from 'net';+import type { AddressInfo } from 'net';++/**+ * Minimal, real SOCKS4 and SOCKS5 servers for the specs that exercise the session-proxy fetch path.+ *+ * They speak enough of RFC 1928 / RFC 1929 (and the SOCKS4 connect request) for a client to complete+ * a real handshake, record what the client asked for, and then relay the tunnel to ONE fixed local+ * port whatever destination was named. That last part is what makes a proxied fetch observable: a+ * spec can aim a request at a public-looking address and still have a local origin answer it, so a+ * request that leaked around the proxy fails instead of quietly reaching nothing.+ */+export interface SocksProxyServer {+ /** Proxy URL to hand to the code under test, credentials included when asked for. */+ url: string;+ /** `host:port` of every connect request received, in order. */+ destinations: string[];+ /** `user:pass` of every SOCKS5 username/password authentication, in order. */+ credentials: string[];+ /** First bytes each tunnelled connection carried, hex-encoded (a TLS ClientHello starts 160301). */+ firstBytes: string[];+ close(): Promise<void>;+}++/** What a running proxy recorded, shared by reference with the object the spec holds. */+type Recorded = Pick<SocksProxyServer, 'destinations' | 'credentials' | 'firstBytes'>;++interface Options {+ /** Local port every tunnel is relayed to, whatever destination the client named. */+ relayTo?: number;+ /** SOCKS5 only: demand username/password authentication (RFC 1929). */+ credentials?: { username: string; password: string };+ /**+ * SOCKS5 only: answer "host unreachable" for an IPv6 destination, the way a proxy with no IPv6+ * route of its own does. The destination is still recorded, so a spec can see what was attempted.+ */+ ipv4Only?: boolean;+}++const listen = async (server: net.Server): Promise<number> => {+ await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve));+ return (server.address() as AddressInfo).port;+};++/**+ * Read exactly `size` bytes. Pull-based (`readable` + `read(size)`) rather than a 'data' listener:+ * a handshake field can arrive in the same packet as the next one, and the stream's own buffer keeps+ * the remainder for the next call. Flowing mode would hand over whole packets and lose the tail.+ */+function read(socket: net.Socket, size: number): Promise<Buffer> {+ return new Promise((resolve, reject) => {+ const settle = (finish: () => void): void => {+ socket.off('readable', attempt);+ socket.off('error', onError);+ socket.off('end', onEnd);+ finish();+ };+ const attempt = (): void => {+ const chunk = socket.read(size) as Buffer | null;+ if (chunk) settle(() => resolve(chunk));+ };+ const onError = (error: Error): void => settle(() => reject(error));+ const onEnd = (): void => settle(() => reject(new Error('socks client closed mid-handshake')));+ socket.on('readable', attempt);+ socket.once('error', onError);+ socket.once('end', onEnd);+ attempt();+ });+}++/** Read a length-prefixed byte string (one length octet, then that many bytes). */+async function readLengthPrefixed(socket: net.Socket): Promise<string> {+ const [length] = await read(socket, 1);+ return length === 0 ? '' : (await read(socket, length)).toString();+}++/** Read a NUL-terminated string one byte at a time (the SOCKS4 user id). */+async function readNulTerminated(socket: net.Socket): Promise<string> {+ const bytes: number[] = [];+ for (;;) {+ const [byte] = await read(socket, 1);+ if (byte === 0) return Buffer.from(bytes).toString();+ bytes.push(byte);+ }+}++function relay(socket: net.Socket, state: Recorded, relayTo?: number): void {+ if (relayTo === undefined) {+ socket.end();+ return;+ }+ const upstream = net.connect(relayTo, '127.0.0.1', () => {+ let first = true;+ socket.on('data', chunk => {+ if (!first) return;+ first = false;+ state.firstBytes.push(chunk.subarray(0, 3).toString('hex'));+ });+ socket.pipe(upstream);+ upstream.pipe(socket);+ });+ upstream.on('error', () => socket.destroy());+}++function serve(handshake: (socket: net.Socket, state: Recorded) => Promise<void>): {+ server: net.Server;+ state: Recorded;+} {+ const state: Recorded = { destinations: [], credentials: [], firstBytes: [] };+ const sockets = new Set<net.Socket>();+ const server = net.createServer(socket => {+ sockets.add(socket);+ socket.on('error', () => undefined);+ socket.on('close', () => sockets.delete(socket));+ void handshake(socket, state).catch(() => socket.destroy());+ });+ // Destroy live tunnels on close so a spec cannot hang on a half-open relay.+ const close = server.close.bind(server);+ server.close = (cb?: (err?: Error) => void) => {+ sockets.forEach(socket => socket.destroy());+ return close(cb);+ };+ return { server, state };+}++const finish = async (+ server: net.Server,+ state: Recorded,+ url: (port: number) => string,+): Promise<SocksProxyServer> => {+ const port = await listen(server);+ return {+ url: url(port),+ ...state,+ close: () => new Promise<void>(resolve => server.close(() => resolve())),+ };+};++/** A SOCKS5 proxy, optionally demanding username/password authentication. */+export async function startSocks5Proxy(options: Options = {}): Promise<SocksProxyServer> {+ const { server, state } = serve(async (socket, recorded) => {+ const [, methodCount] = await read(socket, 2);+ await read(socket, methodCount);+ if (options.credentials) {+ socket.write(Buffer.from([0x05, 0x02])); // username/password+ await read(socket, 1); // auth version+ const username = await readLengthPrefixed(socket);+ const password = await readLengthPrefixed(socket);+ recorded.credentials.push(`${username}:${password}`);+ const ok = username === options.credentials.username && password === options.credentials.password;+ socket.write(Buffer.from([0x01, ok ? 0x00 : 0x01]));+ if (!ok) {+ socket.end();+ return;+ }+ } else {+ socket.write(Buffer.from([0x05, 0x00])); // no authentication required+ }++ const request = await read(socket, 4); // ver, cmd, rsv, atyp+ const atyp = request[3];+ let host: string;+ if (atyp === 0x01) {+ host = [...(await read(socket, 4))].join('.');+ } else if (atyp === 0x03) {+ host = await readLengthPrefixed(socket);+ } else {+ const raw = await read(socket, 16);+ host = Array.from({ length: 8 }, (_, i) => raw.readUInt16BE(i * 2).toString(16)).join(':');+ }+ const port = (await read(socket, 2)).readUInt16BE(0);+ recorded.destinations.push(`${host}:${port}`);+ if (options.ipv4Only && atyp === 0x04) {+ socket.end(Buffer.from([0x05, 0x04, 0x00, 0x01, 0, 0, 0, 0, 0, 0])); // host unreachable+ return;+ }+ socket.write(Buffer.from([0x05, 0x00, 0x00, 0x01, 0, 0, 0, 0, 0, 0]));+ relay(socket, recorded, options.relayTo);+ });++ const scheme = options.credentials+ ? `socks5://${encodeURIComponent(options.credentials.username)}:${encodeURIComponent(options.credentials.password)}@127.0.0.1:`+ : 'socks5://127.0.0.1:';+ return finish(server, state, port => `${scheme}${port}`);+}++/** A strict SOCKS4 proxy: an IPv4 destination only, and no authentication step at all. */+export async function startSocks4Proxy(options: Options = {}): Promise<SocksProxyServer> {+ const { server, state } = serve(async (socket, recorded) => {+ const request = await read(socket, 8); // ver, cmd, port(2), ip(4)+ const port = request.readUInt16BE(2);+ const host = [...request.subarray(4, 8)].join('.');+ recorded.credentials.push(await readNulTerminated(socket)); // user id, the only identity SOCKS4 has+ recorded.destinations.push(`${host}:${port}`);+ socket.write(Buffer.from([0x00, 0x5a, 0, 0, 0, 0, 0, 0])); // request granted+ relay(socket, recorded, options.relayTo);+ });+ return finish(server, state, port => `socks4://127.0.0.1:${port}`);+}