Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(proxy): send SOCKS4 and caller-supplied URL fetches through the session proxy

Yudhi Armyndharis58fb7c94640e
diff --git a/.env.example b/.env.example
index 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.md
index 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
### Security
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
index 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.yml
index 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.md
index 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 through
these 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.md
index 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.json
index 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.json
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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_CONN
throw 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.ts
index 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.ts
index 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.ts
deleted file mode 100644
index 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.ts
index 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.ts
index 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 forwards
diff --git a/src/engine/adapters/baileys-sticker-webp.spec.ts b/src/engine/adapters/baileys-sticker-webp.spec.ts
index 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: je
const 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.ts
index 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.ts
index 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.ts
index 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): BaileysGroup
function 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.ts
index 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-unsu
import { 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 who
diff --git a/src/engine/adapters/whatsapp-web-js.adapter.spec.ts b/src/engine/adapters/whatsapp-web-js.adapter.spec.ts
index 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 gone
expect(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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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}`);
+}