Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
fix(wwebjs): bound the pinned WhatsApp Web HTML fetch
Yudhi Armyndharis7771733cb710
diff --git a/.env.example b/.env.exampleindex f2d78c12b..6c67d7126 100644--- a/.env.example+++ b/.env.example@@ -180,11 +180,12 @@ OPENWA_PIDS_LIMIT=2048# https://github.com/wppconnect-team/wa-version). WWEBJS_WEB_VERSION_REMOTE_PATH overrides the# HTML URL template (use {version} as the placeholder) to fetch from an operator-controlled copy# instead. The requested build + its source (pinned/auto/native) is shown on the dashboard's-# Infrastructure page. A pin is not guaranteed to hold: a pin whose HTML cannot be fetched is dropped-# for the live build, and WhatsApp Web's service worker can serve its own cached build instead of the-# pinned HTML. Each session logs the build it actually runs when it reaches ready (action-# web_version_running), and warns with both builds when that is not the pinned one (action-# web_version_pin_not_applied).+# Infrastructure page. A pin is not guaranteed to hold: a pin whose HTML cannot be fetched within+# 10 s is dropped for the live build (warning web_version_html_unavailable), and WhatsApp Web's+# service worker can serve its own cached build instead of the pinned HTML. A fetched build is kept+# under SESSION_DATA_PATH/.wa-web-cache/. Each session logs the build it actually runs when it+# reaches ready (action web_version_running), and warns with both builds when that is not the+# pinned one (action web_version_pin_not_applied).# WWEBJS_WEB_VERSION=<a build from that registry's html/ folder># WWEBJS_WEB_VERSION=offdiff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.mdindex 054a062da..0d3583350 100644--- a/docs/12-troubleshooting-faq.md+++ b/docs/12-troubleshooting-faq.md@@ -343,20 +343,24 @@ WWEBJS_WEB_VERSION=<a build from that registry's html/ folder>Restart the container after changing it. Pick the build from[wppconnect-team/wa-version](https://github.com/wppconnect-team/wa-version) (the `html/` folder) — a-build the registry no longer serves is fetched, missed, and ignored, leaving you on the default-behaviour rather than the pin you asked for (the `ready`-time warning below names both builds). With+build the registry no longer serves cannot be fetched, and the session starts on the live build rather+than the pin you asked for, with a warning at start (action `web_version_html_unavailable`, naming the+build, the URL and the reason). With`WWEBJS_WEB_VERSION` unset, `latest`, or `auto` (the default), OpenWA auto-resolves a settled buildfrom that registry and pins its HTML — note this HTML is fetched from a third-party repository andexecuted inside the `web.whatsapp.com` origin without an integrity check. Set`WWEBJS_WEB_VERSION=off` to disable pinning and use the first-party build served by WhatsApp. Anunpinned session (this setting, or an auto-resolve that could not reach the registry) caches nothing to-disk, so it also works on the image's read-only root filesystem.+disk, so it also works on the image's read-only root filesystem. A pinned build's HTML is downloaded+at start, with a 10 s bound, into `<SESSION_DATA_PATH>/.wa-web-cache/` on the writable data volume and+served from there; a build no session has started on for a week is removed.A pin is not guaranteed to hold. whatsapp-web.js applies it by answering the page's document requestwith the pinned HTML, and that can miss in two ways: a pin whose HTML could not be fetched is dropped-and the live build loads, and WhatsApp Web's service worker can serve its own cached build without the-request reaching whatsapp-web.js. Either way the page can run a different build than the one-requested, while the startup line `Pinning WhatsApp Web version …` still names the requested build.+at start (the `web_version_html_unavailable` warning above) and the live build loads, and WhatsApp+Web's service worker can serve its own cached build without the request reaching whatsapp-web.js. In+the second case the page runs a different build than the one requested, while the startup line+`Pinning WhatsApp Web version …` still names the requested build.When a session reaches `ready`, OpenWA reads the build the page reports and logs it (action`web_version_running`); when a pin was requested and the page runs a different build, it logs awarning naming both (action `web_version_pin_not_applied`). The comparison ignores the registry's@@ -364,9 +368,8 @@ suffix such as `-alpha`, so a pin and the same bare build count as a match.The warning changes nothing about the session. It reached `ready` on the build the warning names, sothe pin did not cover that page load, and a session that works on that build needs no action.-If the pin is one you set yourself, check that the registry still serves it. Whether the service worker-answers can differ from one page load to the next, so a later restart may load the pin. When you report-a problem with the session, include both builds.+Whether the service worker answers can differ from one page load to the next, so a later restart may+load the pin. When you report a problem with the session, include both builds.### Issue: QR generation times out on slow first boot (WSL2 / low-resource)diff --git a/src/engine/adapters/wwebjs-lifecycle.ts b/src/engine/adapters/wwebjs-lifecycle.tsindex 8fd0478b6..2ff36a190 100644--- a/src/engine/adapters/wwebjs-lifecycle.ts+++ b/src/engine/adapters/wwebjs-lifecycle.ts@@ -300,7 +300,12 @@ export class WwebjsLifecycle {// #251/#488). DEFAULT: auto-resolve a settled build from the wa-version registry and pin its// remote HTML (no integrity check — resolveWebVersionPin logs a loud warning); only// WWEBJS_WEB_VERSION=off leaves whatsapp-web.js to use the first-party build from WhatsApp.- const versionPin = await resolveWebVersionPin();+ // The pinned HTML is downloaded (bounded) onto the writable data volume and served from there,+ // so an unreachable mirror is named in the log instead of silently loading the live build.+ const versionPin = await resolveWebVersionPin(+ undefined,+ path.join(path.resolve(this.host.config.sessionDataPath), '.wa-web-cache'),+ );// Assigned on every init, including the unpinned case, so a pin from an earlier init is never// compared against the page this one loads.this.requestedWebVersion = versionPin?.webVersion;@@ -451,7 +456,9 @@ export class WwebjsLifecycle {// Unpinned, whatsapp-web.js defaults to a local HTML cache at the cwd-relative// './.wwebjs_cache/' and writes it after the link, before `ready`. The image's /app is not// writable (root-owned, read-only in compose and Helm), so that write throws and the session- // never reaches ready. 'none' caches nothing and serves WhatsApp's live build.+ // never reaches ready. 'none' caches nothing and serves WhatsApp's live build. A pin is a+ // strict local cache under SESSION_DATA_PATH (see resolveWebVersionPin), which the library+ // only reads: it persists nothing when the cache served the page....(versionPin ?? { webVersionCache: { type: 'none' as const } }),});this.client = client;diff --git a/src/engine/adapters/wwebjs-running-build.ts b/src/engine/adapters/wwebjs-running-build.tsindex 911711a04..515fbeac8 100644--- a/src/engine/adapters/wwebjs-running-build.ts+++ b/src/engine/adapters/wwebjs-running-build.ts@@ -26,10 +26,11 @@ function numericBuild(version: string): string | null {* whatsapp-web.js applies a pin by answering the page's document request from its request* interceptor, so the pin holds only for a page load that goes through it. WhatsApp Web's service* worker can answer the document from its own cache without the request ever reaching the- * interceptor, and a pin whose HTML could not be fetched installs no interceptor at all (the- * library's remote cache is non-strict and falls back to the live build). Either way the startup- * line `Pinning WhatsApp Web version …` still names the pin, and nothing read back the build that- * actually booted, so a session reported to be on one build could be running another.+ * interceptor. (A pin whose HTML could not be fetched is dropped before the Client is built: it+ * logs `web_version_html_unavailable`, no pin is requested, and the page loads the live build.) In+ * the service-worker case the startup line `Pinning WhatsApp Web version …` still names the pin,+ * and nothing read back the build that actually booted, so a session reported to be on one build+ * could be running another.** The comparison is on the numeric build only (see {@link numericBuild}). A pin that does not parse* as one cannot be compared, and gets the info line rather than a warning. A read that fails ordiff --git a/src/engine/adapters/wwebjs-web-version-cache.spec.ts b/src/engine/adapters/wwebjs-web-version-cache.spec.tsindex 2f54c3d8a..a9444bb27 100644--- a/src/engine/adapters/wwebjs-web-version-cache.spec.ts+++ b/src/engine/adapters/wwebjs-web-version-cache.spec.ts@@ -1,5 +1,9 @@+import * as fs from 'fs';+import * as os from 'os';+import * as path from 'path';import { Client } from 'whatsapp-web.js';import { WhatsAppWebJsAdapter } from './whatsapp-web-js.adapter';+import { __resetWebVersionCache } from '../wa-web-version';/*** The web version cache handed to the whatsapp-web.js Client. Unpinned, the library's default is a@@ -9,12 +13,13 @@ import { WhatsAppWebJsAdapter } from './whatsapp-web-js.adapter';describe('whatsapp-web.js web version cache', () => {let clientInitSpy: jest.SpyInstance;let savedWebVersion: string | undefined;+ let dataDir: string;const launchedCacheOption = async (webVersion: string): Promise<unknown> => {process.env.WWEBJS_WEB_VERSION = webVersion;const adapter = new WhatsAppWebJsAdapter({sessionId: 'sess-web-version-cache',- sessionDataPath: './data/sessions',+ sessionDataPath: dataDir,puppeteer: {},});await adapter.initialize({});@@ -22,6 +27,8 @@ describe('whatsapp-web.js web version cache', () => {};beforeEach(() => {+ __resetWebVersionCache();+ dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'wwebjs-web-version-'));savedWebVersion = process.env.WWEBJS_WEB_VERSION;// Build the real Client, whose options are merged over the library defaults, but launch no browser.clientInitSpy = jest@@ -30,6 +37,9 @@ describe('whatsapp-web.js web version cache', () => {});afterEach(() => {+ jest.restoreAllMocks();+ __resetWebVersionCache();+ fs.rmSync(dataDir, { recursive: true, force: true });clientInitSpy.mockRestore();if (savedWebVersion === undefined) {delete process.env.WWEBJS_WEB_VERSION;@@ -42,7 +52,33 @@ describe('whatsapp-web.js web version cache', () => {expect(await launchedCacheOption('off')).toEqual({ type: 'none' });});- it('keeps the remote cache for a pinned build', async () => {- expect(await launchedCacheOption('2.3000.1000000000')).toMatchObject({ type: 'remote' });+ // whatsapp-web.js's remote cache fetches with no timeout and loads the live build on failure, so a+ // pinned build's HTML is downloaded first and served as a strict file on the data volume.+ it('serves a pinned build from a strict local cache under the session data path', async () => {+ const html = `<html>${'x'.repeat(2048)}</html>`;+ jest+ .spyOn(globalThis, 'fetch')+ .mockResolvedValue({ ok: true, status: 200, text: () => Promise.resolve(html) } as unknown as Response);++ expect(await launchedCacheOption('2.3000.1000000000')).toEqual({+ type: 'local',+ path: path.join(path.resolve(dataDir), '.wa-web-cache'),+ strict: true,+ });+ expect(fs.readFileSync(path.join(dataDir, '.wa-web-cache', '2.3000.1000000000.html'), 'utf8')).toBe(html);++ // The library's own strict cache finds the file under the name it looks for.+ // eslint-disable-next-line @typescript-eslint/no-require-imports+ const LocalWebCache = require('whatsapp-web.js/src/webCache/LocalWebCache') as new (options: object) => {+ resolve: (version: string) => Promise<string | null>;+ };+ const cache = new LocalWebCache({ path: path.join(path.resolve(dataDir), '.wa-web-cache'), strict: true });+ await expect(cache.resolve('2.3000.1000000000')).resolves.toBe(html);+ });++ it('runs unpinned when the pinned build cannot be downloaded', async () => {+ jest.spyOn(globalThis, 'fetch').mockRejectedValue(new Error('getaddrinfo ENOTFOUND'));++ expect(await launchedCacheOption('2.3000.1000000000')).toEqual({ type: 'none' });});});diff --git a/src/engine/wa-web-version.spec.ts b/src/engine/wa-web-version.spec.tsindex dc8094947..72050e058 100644--- a/src/engine/wa-web-version.spec.ts+++ b/src/engine/wa-web-version.spec.ts@@ -3,8 +3,12 @@ jest.mock('../common/services/logger.service', () => ({createLogger: () => ({ warn: mockWarn, log: jest.fn(), error: jest.fn(), info: jest.fn(), debug: jest.fn() }),}));+import * as fs from 'fs';+import * as os from 'os';+import * as path from 'path';import {__resetWebVersionCache,+ PINNED_HTML_TIMEOUT_MS,pickSettledWebVersion,resolveCurrentWebVersion,resolveWebVersionPin,@@ -270,3 +274,145 @@ describe('resolveCurrentWebVersion failure warning', () => {expect(mockWarn).toHaveBeenCalledTimes(1);});});++// whatsapp-web.js fetches a remote pin's HTML with no timeout and, non-strict, loads the live build+// when that fails, silently. The HTML is now fetched here, bounded, and served as a strict local file.+describe('resolveWebVersionPin with a cache directory', () => {+ const ORIGINAL_ENV = process.env.WWEBJS_WEB_VERSION;+ const VERSION = '2.3000.1234';+ const HTML = `<!DOCTYPE html><html><head></head><body>${'x'.repeat(2048)}</body></html>`;+ let dir: string;++ const page = (body: string, status = 200) => ({ ok: status < 400, status, text: () => Promise.resolve(body) });+ const htmlWarning = (): Record<string, unknown> | undefined =>+ (mockWarn.mock.calls as [string, Record<string, unknown>][]).find(+ ([, meta]) => meta?.action === 'web_version_html_unavailable',+ )?.[1];++ beforeEach(() => {+ __resetWebVersionCache();+ mockWarn.mockClear();+ dir = fs.mkdtempSync(path.join(os.tmpdir(), 'wa-web-cache-'));+ process.env.WWEBJS_WEB_VERSION = VERSION;+ });+ afterEach(() => {+ jest.useRealTimers();+ __resetWebVersionCache();+ fs.rmSync(dir, { recursive: true, force: true });+ if (ORIGINAL_ENV === undefined) delete process.env.WWEBJS_WEB_VERSION;+ else process.env.WWEBJS_WEB_VERSION = ORIGINAL_ENV;+ });++ it('writes the HTML and answers a strict local cache for it', async () => {+ const fetcher = jest.fn(() => Promise.resolve(page(HTML)));++ await expect(resolveWebVersionPin(fetcher as never, dir)).resolves.toEqual({+ webVersion: VERSION,+ webVersionCache: { type: 'local', path: dir, strict: true },+ });+ expect(fs.readFileSync(path.join(dir, `${VERSION}.html`), 'utf8')).toBe(HTML);+ expect(fs.readdirSync(dir)).toEqual([`${VERSION}.html`]);+ expect(htmlWarning()).toBeUndefined();+ });++ it('sends URL credentials as a Basic header, since fetch refuses a URL that carries them', async () => {+ process.env.WWEBJS_WEB_VERSION_REMOTE_PATH = 'https://u:[email protected]/{version}.html';+ try {+ const fetcher = jest.fn(() => Promise.resolve(page(HTML)));++ await expect(resolveWebVersionPin(fetcher as never, dir)).resolves.toMatchObject({+ webVersionCache: { type: 'local' },+ });+ expect(fetcher).toHaveBeenCalledWith(+ `https://mirror.example/${VERSION}.html`,+ expect.objectContaining({ headers: { Authorization: 'Basic dTpw' } }),+ );++ fetcher.mockResolvedValue(page('', 503));+ __resetWebVersionCache();+ await resolveWebVersionPin(fetcher as never, dir);+ expect(htmlWarning()?.remotePath).toBe(`https://mirror.example/${VERSION}.html`);+ const logged = JSON.stringify(mockWarn.mock.calls);+ expect(logged).not.toContain('u:p@');+ } finally {+ delete process.env.WWEBJS_WEB_VERSION_REMOTE_PATH;+ }+ });++ it('removes a build no start has written for a week, and keeps a recent one', async () => {+ const stale = path.join(dir, '2.3000.1.html');+ const recent = path.join(dir, '2.3000.2.html');+ fs.writeFileSync(stale, HTML);+ fs.writeFileSync(recent, HTML);+ const eightDaysAgo = new Date(Date.now() - 8 * 24 * 60 * 60 * 1000);+ fs.utimesSync(stale, eightDaysAgo, eightDaysAgo);+ const fetcher = jest.fn(() => Promise.resolve(page(HTML)));++ await resolveWebVersionPin(fetcher as never, dir);++ expect(fs.readdirSync(dir).sort()).toEqual(['2.3000.1234.html', '2.3000.2.html']);+ });++ it('gives up at the bound and drops the pin with a named warning', async () => {+ jest.useFakeTimers();+ const fetcher = jest.fn(+ (_url: string, init: { signal: AbortSignal }) =>+ new Promise((_resolve, reject) => init.signal.addEventListener('abort', () => reject(new Error('aborted')))),+ );++ const pending = resolveWebVersionPin(fetcher as never, dir);+ await jest.advanceTimersByTimeAsync(PINNED_HTML_TIMEOUT_MS);++ await expect(pending).resolves.toBeUndefined();+ const warning = htmlWarning();+ expect(warning?.webVersion).toBe(VERSION);+ expect(warning?.reason).toContain(`${PINNED_HTML_TIMEOUT_MS} ms`);+ expect(warning?.remotePath).toContain(VERSION);+ });++ it.each([+ ['a non-ok status', page(HTML, 404), 'HTTP 404'],+ ['a body too short to be the page', page('<html></html>'), 'not a WhatsApp Web page'],+ ['a body that is not HTML', page('x'.repeat(4096)), 'not a WhatsApp Web page'],+ ])('drops the pin on %s and writes nothing', async (_label, response, reason) => {+ const fetcher = jest.fn(() => Promise.resolve(response));++ await expect(resolveWebVersionPin(fetcher as never, dir)).resolves.toBeUndefined();+ expect(htmlWarning()?.reason).toContain(reason);+ expect(fs.readdirSync(dir)).toEqual([]);+ });++ it('fetches a build once, shares a concurrent fetch, and retries after a failure', async () => {+ const fetcher = jest.fn().mockResolvedValueOnce(page('', 503)).mockResolvedValue(page(HTML));++ await expect(resolveWebVersionPin(fetcher as never, dir)).resolves.toBeUndefined();+ const [a, b] = await Promise.all([+ resolveWebVersionPin(fetcher as never, dir),+ resolveWebVersionPin(fetcher as never, dir),+ ]);+ await resolveWebVersionPin(fetcher as never, dir);++ expect(a?.webVersionCache.type).toBe('local');+ expect(b?.webVersionCache.type).toBe('local');+ expect(fetcher).toHaveBeenCalledTimes(2);+ });++ it('refuses a version that is not a build number, without fetching or writing', async () => {+ process.env.WWEBJS_WEB_VERSION = '../../etc/x';+ const fetcher = jest.fn(() => Promise.resolve(page(HTML)));++ await expect(resolveWebVersionPin(fetcher as never, dir)).resolves.toBeUndefined();+ expect(fetcher).not.toHaveBeenCalled();+ expect(fs.readdirSync(dir)).toEqual([]);+ expect(htmlWarning()).toBeDefined();+ });++ it('keeps the remote shape when no cache directory is given', async () => {+ const fetcher = jest.fn();++ await expect(resolveWebVersionPin(fetcher as never)).resolves.toMatchObject({+ webVersionCache: { type: 'remote' },+ });+ expect(fetcher).not.toHaveBeenCalled();+ });+});diff --git a/src/engine/wa-web-version.ts b/src/engine/wa-web-version.tsindex c85edb598..901ac1361 100644--- a/src/engine/wa-web-version.ts+++ b/src/engine/wa-web-version.ts@@ -4,11 +4,16 @@* pulling in the heavy whatsapp-web.js module and breaking engine lazy-loading.*/+import { randomUUID } from 'crypto';+import * as fs from 'fs';+import * as path from 'path';import { createLogger } from '../common/services/logger.service';const logger = createLogger('WebVersion');-export type WebVersionPin = { webVersion: string; webVersionCache: { type: 'remote'; remotePath: string } };+type RemoteWebVersionPin = { webVersion: string; webVersionCache: { type: 'remote'; remotePath: string } };+type LocalWebVersionPin = { webVersion: string; webVersionCache: { type: 'local'; path: string; strict: true } };+export type WebVersionPin = RemoteWebVersionPin | LocalWebVersionPin;// The wppconnect-team/wa-version registry tracks the current known-good WhatsApp Web build. Its// `currentVersion` is what we pin to when the operator hasn't chosen one — far more reliable than@@ -42,6 +47,18 @@ let lastFailureAt = 0;let warnedRemoteTrust = false;+// The pinned build's HTML. whatsapp-web.js's own remote cache fetches it with no timeout and, being+// non-strict, loads WhatsApp's live build when the fetch fails: the #488 class the pin exists to+// prevent. A non-OK answer falls back with nothing logged, a network error reaches only a bare+// console.error, and a hang never ends. It is fetched here instead, bounded, and handed to the library+// as a strict local cache. A successful download is kept per URL for the life of the process (a+// build's HTML does not change); a failure is not, so the next start retries.+export const PINNED_HTML_TIMEOUT_MS = 10_000;+const PINNED_HTML_MIN_LENGTH = 1024;+const PINNED_HTML_KEEP_MS = 7 * 24 * 60 * 60 * 1000;+const pinnedHtml = new Map<string, string>();+const pinnedHtmlInFlight = new Map<string, Promise<string>>();+/** Test-only: reset the resolved-version cache between cases. */export function __resetWebVersionCache(): void {cachedCurrentVersion = undefined;@@ -49,6 +66,8 @@ export function __resetWebVersionCache(): void {inFlight = null;lastFailureAt = 0;warnedRemoteTrust = false;+ pinnedHtml.clear();+ pinnedHtmlInFlight.clear();}/**@@ -57,7 +76,7 @@ export function __resetWebVersionCache(): void {* so pinning is a trust decision the operator must make knowingly — the log states the source and* the opt-outs. Once-only: resolveWebVersionPin runs on every session (re)start.*/-function warnRemoteTrustOnce(pin: WebVersionPin): void {+function warnRemoteTrustOnce(pin: RemoteWebVersionPin): void {if (warnedRemoteTrust) return;warnedRemoteTrust = true;logger.warn(@@ -65,7 +84,7 @@ function warnRemoteTrustOnce(pin: WebVersionPin): void {{action: 'web_version_remote_pin',webVersion: pin.webVersion,- remotePath: pin.webVersionCache.remotePath,+ remotePath: splitCredentials(pin.webVersionCache.remotePath).href,optOut:'set WWEBJS_WEB_VERSION=off for the first-party build served by WhatsApp, or point WWEBJS_WEB_VERSION_REMOTE_PATH at an operator-controlled copy',},@@ -107,7 +126,7 @@ function warnResolveFailed(reason: string, previous: string | null): void {});}-function buildRemotePin(version: string): WebVersionPin {+function buildRemotePin(version: string): RemoteWebVersionPin {const template = process.env.WWEBJS_WEB_VERSION_REMOTE_PATH?.trim() || DEFAULT_REMOTE_TEMPLATE;return {webVersion: version,@@ -198,23 +217,154 @@ export async function resolveCurrentWebVersion(fetcher: typeof fetch = fetch): P* from the wa-version registry and pin it; if that fetch fails, keep the previously resolved* build, or fall back to native auto-select when none was ever resolved.* `WWEBJS_WEB_VERSION_REMOTE_PATH` overrides the HTML URL template (`{version}` placeholder).+ * With `cacheDir`, the pinned HTML is downloaded there first and the pin becomes a strict local cache;+ * a download that fails (or takes over PINNED_HTML_TIMEOUT_MS) drops the pin with a named warning.* The auto-resolve replaces whatsapp-web.js's unreliable default that caused #488 (scan → stuck →* disconnect loop) on Docker setups where no version was pinned.*/-export async function resolveWebVersionPin(fetcher: typeof fetch = fetch): Promise<WebVersionPin | undefined> {+export function resolveWebVersionPin(fetcher?: typeof fetch): Promise<RemoteWebVersionPin | undefined>;+export function resolveWebVersionPin(+ fetcher: typeof fetch | undefined,+ cacheDir: string,+): Promise<WebVersionPin | undefined>;+export async function resolveWebVersionPin(+ fetcher: typeof fetch = fetch,+ cacheDir?: string,+): Promise<WebVersionPin | undefined> {const raw = process.env.WWEBJS_WEB_VERSION?.trim();const lc = raw?.toLowerCase();+ let pin: RemoteWebVersionPin;if (raw && lc !== 'off' && lc !== 'latest' && lc !== 'auto') {- const pin = buildRemotePin(raw); // operator-pinned exact version- warnRemoteTrustOnce(pin);- return pin;+ pin = buildRemotePin(raw); // operator-pinned exact version+ } else {+ if (lc === 'off') return undefined; // explicit escape hatch → native auto-select+ const current = await resolveCurrentWebVersion(fetcher);+ if (!current) return undefined;+ pin = buildRemotePin(current);}- if (lc === 'off') return undefined; // explicit escape hatch → native auto-select- const current = await resolveCurrentWebVersion(fetcher);- if (!current) return undefined;- const pin = buildRemotePin(current);warnRemoteTrustOnce(pin);- return pin;+ return cacheDir ? localisePin(pin, cacheDir, fetcher) : pin;+}++/**+ * Download the pinned HTML (bounded) into `<cacheDir>/<version>.html` and answer a strict local cache+ * for it. When it cannot be had, say so by name and answer no pin: the session then loads the live+ * build, as the docs promise, instead of hanging on an unbounded fetch that ends the same way.+ */+async function localisePin(+ pin: RemoteWebVersionPin,+ cacheDir: string,+ fetcher: typeof fetch,+): Promise<WebVersionPin | undefined> {+ const { webVersion } = pin;+ const { remotePath } = pin.webVersionCache;+ try {+ // The version becomes a file name, and an operator sets it: no separators, no leading dots.+ if (!/^\d[\w.-]*$/.test(webVersion)) throw new Error('the version is not a WhatsApp Web build number');+ const html = await fetchPinnedHtml(remotePath, fetcher);+ writePinnedHtml(cacheDir, webVersion, html);+ return { webVersion, webVersionCache: { type: 'local', path: cacheDir, strict: true } };+ } catch (error) {+ logger.warn('Could not load the pinned WhatsApp Web build; continuing WITHOUT a pin', {+ action: 'web_version_html_unavailable',+ reason: error instanceof Error ? error.message : String(error),+ webVersion,+ remotePath: splitCredentials(remotePath).href,+ consequence:+ "the live WhatsApp Web build loads instead, which on some setups authenticates then never reaches 'ready'",+ remedy:+ 'confirm the host can reach remotePath, pin a build the registry still serves in WWEBJS_WEB_VERSION, or point WWEBJS_WEB_VERSION_REMOTE_PATH at a reachable copy',+ });+ return undefined;+ }+}++function fetchPinnedHtml(remotePath: string, fetcher: typeof fetch): Promise<string> {+ const cached = pinnedHtml.get(remotePath);+ if (cached) return Promise.resolve(cached);+ let pending = pinnedHtmlInFlight.get(remotePath);+ if (!pending) {+ pending = downloadPinnedHtml(remotePath, fetcher).finally(() => pinnedHtmlInFlight.delete(remotePath));+ pinnedHtmlInFlight.set(remotePath, pending);+ }+ return pending;+}++async function downloadPinnedHtml(remotePath: string, fetcher: typeof fetch): Promise<string> {+ const controller = new AbortController();+ const timer = setTimeout(() => controller.abort(), PINNED_HTML_TIMEOUT_MS);+ try {+ const { href, authorization } = splitCredentials(remotePath);+ const headers: Record<string, string> = authorization ? { Authorization: authorization } : {};+ const res = await fetcher(href, { signal: controller.signal, headers });+ if (!res.ok) throw new Error(`HTTP ${res.status}`);+ const html = await res.text();+ if (html.length < PINNED_HTML_MIN_LENGTH || !/<html/i.test(html)) {+ throw new Error('the response is not a WhatsApp Web page');+ }+ pinnedHtml.set(remotePath, html);+ return html;+ } catch (error) {+ if (controller.signal.aborted) throw new Error(`no answer within ${PINNED_HTML_TIMEOUT_MS} ms`, { cause: error });+ throw error;+ } finally {+ clearTimeout(timer);+ }+}++/**+ * Move URL userinfo into a Basic Authorization header. Node's fetch refuses a URL that carries+ * credentials, while the library's own fetcher used to send them this way, so a mirror reached as+ * https://user:pass@host/... keeps working. The credential-free URL is also what gets logged.+ */+function splitCredentials(remotePath: string): { href: string; authorization?: string } {+ let url: URL;+ try {+ url = new URL(remotePath);+ } catch {+ return { href: remotePath };+ }+ if (!url.username && !url.password) return { href: remotePath };+ const decode = (part: string): string => {+ try {+ return decodeURIComponent(part);+ } catch {+ return part;+ }+ };+ const authorization = `Basic ${Buffer.from(`${decode(url.username)}:${decode(url.password)}`).toString('base64')}`;+ url.username = '';+ url.password = '';+ return { href: url.href, authorization };+}++/**+ * Write through a unique temp file and rename it into place: several sessions, or several nodes on+ * one data volume, can write the same build at once, and the strict cache must never read half a file.+ */+function writePinnedHtml(cacheDir: string, version: string, html: string): void {+ fs.mkdirSync(cacheDir, { recursive: true });+ const file = path.join(cacheDir, `${version}.html`);+ const tmp = `${file}.${randomUUID()}.tmp`;+ try {+ fs.writeFileSync(tmp, html);+ fs.renameSync(tmp, file);+ } catch (error) {+ fs.rmSync(tmp, { force: true });+ throw error;+ }+ // The directory sits on the backed-up data volume, and every build pinned over the months would+ // otherwise stay there. Each start rewrites its own file, so a build any session still starts on+ // is never a week old: only those that are not get removed.+ for (const name of fs.readdirSync(cacheDir)) {+ const other = path.join(cacheDir, name);+ if (other === file) continue;+ try {+ if (Date.now() - fs.statSync(other).mtimeMs > PINNED_HTML_KEEP_MS) fs.rmSync(other, { force: true });+ } catch {+ // Another writer renamed or removed it first; nothing left to prune.+ }+ }}/**