Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

18.6 KB
Raw Blame
/**
 * WhatsApp Web build resolution for the whatsapp-web.js engine — kept free of whatsapp-web.js
 * imports (env + fetch + the app logger only) so the infra status endpoint can import it without
 * 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');

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
// whatsapp-web.js's own auto-select, which can latch onto a bleeding-edge build that authenticates
// then never reaches "ready" and disconnect-loops (#488).
export const WA_VERSION_REGISTRY_URL =
  'https://raw.githubusercontent.com/wppconnect-team/wa-version/main/versions.json';

const DEFAULT_REMOTE_TEMPLATE = 'https://raw.githubusercontent.com/wppconnect-team/wa-version/main/html/{version}.html';

// Module-level cache: undefined = not yet resolved, string = the resolved current build (refreshed
// after CACHE_TTL_MS). A failed fetch is NOT cached permanently — but to avoid re-stalling every
// call (e.g. each /infra/status poll and every session start/reconnect) on a firewalled/offline
// host, a failure is rate-limited by `lastFailureAt`: subsequent calls skip the fetch for
// FAILURE_BACKOFF_MS and answer the previously resolved build (null if none), then retry.
// `inFlight` dedupes concurrent resolves into a single fetch.
const FAILURE_BACKOFF_MS = 60_000;
// Minimum age a WhatsApp Web build must reach before we'll auto-pin it. The registry's
// `currentVersion` tracks the latest build, which can be minutes old and unvalidated; a build
// published at least this long ago is far less likely to hang before reaching QR readiness on a
// fresh start (the #488 / #684 failure class). Exposed for tests.
export const WEB_VERSION_SETTLE_MS = 12 * 60 * 60 * 1000; // 12h
// How long a resolved build is reused before the registry is read again. The registry deletes a
// build's HTML about 60 days after release, so a pin held for the life of the process eventually 404s
// and the page silently loads the live build instead.
const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
let cachedCurrentVersion: string | undefined;
let cachedAt = 0;
let inFlight: Promise<string | null> | null = null;
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. The latest successful download is kept in memory (a build's HTML does not
// change, and a pin only moves forward, so older builds are dropped); 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;
  cachedAt = 0;
  inFlight = null;
  lastFailureAt = 0;
  warnedRemoteTrust = false;
  pinnedHtml.clear();
  pinnedHtmlInFlight.clear();
}

/**
 * Warn once per process when a remote-HTML pin takes effect. The pinned HTML is fetched over the
 * network and executed inside the authenticated web.whatsapp.com origin with no integrity check,
 * 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: RemoteWebVersionPin): void {
  if (warnedRemoteTrust) return;
  warnedRemoteTrust = true;
  logger.warn(
    'WhatsApp Web build pinned to remote HTML served into the web.whatsapp.com origin WITHOUT an integrity check',
    {
      action: 'web_version_remote_pin',
      webVersion: pin.webVersion,
      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',
    },
  );
}

/**
 * Report a failed registry resolve. Without this the degradation is invisible: the fetch is
 * swallowed, `resolveWebVersionPin` returns undefined, and the adapter logs only inside
 * `if (versionPin)` — so a host that cannot reach the registry silently falls back to
 * whatsapp-web.js's own version selection, which is the failure class the pin exists to prevent
 * (#488), with nothing in the log to grep for.
 *
 * Deliberately NOT once-per-process like `warnRemoteTrustOnce`. The state is ongoing rather than a
 * one-time decision, and an operator diagnosing a session days into a container's life reads a
 * bounded log window (`docker compose logs --tail=…`) — a warning emitted only at first failure
 * would have scrolled away exactly when it is needed. Repetition is already bounded: the
 * `lastFailureAt` backoff returns before the fetch, so at most one attempt (hence one warning) per
 * FAILURE_BACKOFF_MS.
 */
function warnResolveFailed(reason: string, previous: string | null): void {
  if (previous) {
    logger.warn('Could not refresh the WhatsApp Web build from the wa-version registry; keeping the previous pin', {
      action: 'web_version_refresh_failed',
      reason,
      webVersion: previous,
      registry: WA_VERSION_REGISTRY_URL,
    });
    return;
  }
  logger.warn('Could not resolve a WhatsApp Web build from the wa-version registry — continuing WITHOUT a pin', {
    action: 'web_version_resolve_failed',
    reason,
    registry: WA_VERSION_REGISTRY_URL,
    consequence:
      "whatsapp-web.js selects the build itself, which on some setups authenticates then never reaches 'ready'",
    remedy:
      'confirm the host can reach the registry URL, or set WWEBJS_WEB_VERSION to an exact build (or "off" to accept the first-party build)',
  });
}

function buildRemotePin(version: string): RemoteWebVersionPin {
  const template = process.env.WWEBJS_WEB_VERSION_REMOTE_PATH?.trim() || DEFAULT_REMOTE_TEMPLATE;
  return {
    webVersion: version,
    webVersionCache: { type: 'remote', remotePath: template.replace('{version}', version) },
  };
}

type WaVersionEntry = { version?: unknown; beta?: unknown; released?: unknown; expire?: unknown };

/**
 * Pick the WhatsApp Web build to auto-pin from the registry's `versions[]`: the newest non-beta,
 * unexpired build published at least `WEB_VERSION_SETTLE_MS` ago — i.e. one the ecosystem has had
 * time to validate — rather than the registry's `currentVersion`, which can be minutes old. Falls
 * back to `currentVersion` when no build qualifies (a freshly-reset registry, or every build still
 * too new), so this hardens pinning without ever defeating it. Pure: pass `now` explicitly.
 */
export function pickSettledWebVersion(versions: unknown, now: number, currentVersion: string | null): string | null {
  if (!Array.isArray(versions)) return currentVersion;
  const settledCutoff = now - WEB_VERSION_SETTLE_MS;
  let best: { version: string; released: number } | null = null;
  for (const raw of versions) {
    if (!raw || typeof raw !== 'object') continue;
    const e = raw as WaVersionEntry;
    if (typeof e.version !== 'string' || !/^\d/.test(e.version)) continue;
    if (e.beta === true) continue;
    const released = typeof e.released === 'string' ? Date.parse(e.released) : NaN;
    if (!Number.isFinite(released) || released > settledCutoff) continue; // too fresh
    const expire = typeof e.expire === 'string' ? Date.parse(e.expire) : NaN;
    if (Number.isFinite(expire) && expire <= now) continue; // already expired
    if (!best || best.released < released) best = { version: e.version, released };
  }
  return best?.version ?? currentVersion;
}

/**
 * Fetch the current known-good WhatsApp Web build from the wa-version registry. A SUCCESSFUL resolve
 * is cached for CACHE_TTL_MS, then refreshed; a failure is NOT cached, so a later call retries (a
 * single transient outage must not permanently defeat the #488 fix). A failed refresh keeps the
 * previous build, and only a process that never resolved one gets null. Concurrent callers share one
 * in-flight fetch. Prefers a build that has settled (see `pickSettledWebVersion`) over the registry's
 * possibly-minute-old `currentVersion`.
 */
export async function resolveCurrentWebVersion(fetcher: typeof fetch = fetch): Promise<string | null> {
  const previous = cachedCurrentVersion ?? null;
  if (previous && Date.now() - cachedAt < CACHE_TTL_MS) return previous;
  if (inFlight) return inFlight;
  // Within the backoff window after a recent failure, answer instantly without a network call so a
  // firewalled/offline host doesn't re-stall on every status poll / session start.
  if (lastFailureAt && Date.now() - lastFailureAt < FAILURE_BACKOFF_MS) return previous;
  inFlight = (async (): Promise<string | null> => {
    try {
      const controller = new AbortController();
      const timer = setTimeout(() => controller.abort(), 5000);
      try {
        const res = await fetcher(WA_VERSION_REGISTRY_URL, { signal: controller.signal });
        if (!res.ok) throw new Error(`HTTP ${res.status}`);
        const json = (await res.json()) as { currentVersion?: unknown; versions?: unknown };
        const rawCurrent =
          typeof json.currentVersion === 'string' && /^\d/.test(json.currentVersion) ? json.currentVersion : null;
        const picked = pickSettledWebVersion(json.versions, Date.now(), rawCurrent);
        if (picked) {
          cachedCurrentVersion = picked; // cache only on success
          cachedAt = Date.now();
          return picked;
        }
        lastFailureAt = Date.now(); // nothing usable — back off, then retry
        warnResolveFailed('the registry carried no usable build', previous);
        return previous;
      } finally {
        clearTimeout(timer);
      }
    } catch (error) {
      lastFailureAt = Date.now(); // fetch failed — back off, then retry
      warnResolveFailed(error instanceof Error ? error.message : String(error), previous);
      return previous;
    } finally {
      inFlight = null;
    }
  })();
  return inFlight;
}

/**
 * Resolve the WhatsApp Web version pin for the whatsapp-web.js client.
 * - Explicit `WWEBJS_WEB_VERSION` (a version string)  → pin it exactly (no network call).
 * - `off`                                             → no pin; whatsapp-web.js native auto-select.
 * - unset / `auto` / `latest`                         → auto-resolve the current known-good build
 *   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 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') {
    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);
  }
  warnRemoteTrustOnce(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.clear();
    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.
    }
  }
}

/**
 * The WhatsApp Web build sessions request as their pin, for the dashboard to display (#488). This is
 * what was asked for, not a read-back: a page can still run another build, which each session logs at
 * READY (./adapters/wwebjs-running-build). It is distinct from the whatsapp-web.js library version.
 * `source`: `pinned` = operator-set exact version; `auto` = resolved from the wa-version registry;
 * `native` = whatsapp-web.js auto-select.
 */
export function getEffectiveWebVersionInfo(): { version: string | null; source: 'pinned' | 'auto' | 'native' } {
  const raw = process.env.WWEBJS_WEB_VERSION?.trim();
  const lc = raw?.toLowerCase();
  if (raw && lc !== 'off' && lc !== 'latest' && lc !== 'auto') return { version: raw, source: 'pinned' };
  if (lc === 'off') return { version: null, source: 'native' };
  return { version: cachedCurrentVersion ?? null, source: 'auto' };
}