Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

62.6 KB
Raw Blame
import * as path from 'path';
import * as fs from 'fs';
import type { ClientRequest, IncomingMessage } from 'http';
import type { Agent } from 'https';
import type { Socket } from 'net';
import * as qrcode from 'qrcode';
import { HttpsProxyAgent } from 'https-proxy-agent';
import { SocksProxyAgent } from 'socks-proxy-agent';
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 { useAtomicMultiFileAuthState } from './baileys-auth-store';
import { createBaileysLogger } from './baileys-logger';
import { GroupMetadataCache, groupMetadataCacheTtlMs } from './baileys-group-metadata-cache';
import { BaileysVersionResolver } from './baileys-version-resolver';
import { unappliedPatches, unappliedPatchesMessage } from './engine-patch-status';
import {
  ACCOUNT_REJECTED_REASON,
  CONNECTION_REPLACED_REASON,
  LOGOUT_CLEANUP_FAILED_REASON,
} from '../terminal-engine-failure';
import { differentWaIds, type BaileysEvents } from './baileys-events';
import type { BaileysHistory } from './baileys-history';
import type { BaileysSessionStore } from './baileys-session-store';
import { chatKind, userPart } from '../identity/wa-id';

/** Linked-device identity shown in WhatsApp (Settings → Linked Devices). The OS platform is
 * operator-configurable via BAILEYS_BROWSER_NAME; defaults to 'Ubuntu' because some accounts reject a
 * non-standard name on phone-number (pairing-code) linking. Only new pairings carry the name. */
const BAILEYS_BROWSER: [string, string, string] = [
  process.env.BAILEYS_BROWSER_NAME?.trim() || 'Ubuntu',
  'Chrome',
  '120.0.0',
];

/**
 * How long logout() waits for WhatsApp to acknowledge the `remove-companion-device` IQ. Completion of
 * an engine-native unlink requires a tagged IQ result from the server (NOT a WebSocket write flush),
 * so this bound is the difference between a 502 (operation incomplete) and a 200 (unlink completed).
 * Set above the typical round-trip but well under the service's 10s teardown deadline so a wedged
 * transport surfaces as a retryable 502 instead of wedging the session.
 */
const BAILEYS_LOGOUT_ACK_TIMEOUT_MS = 8_000;

/**
 * Backstop for a socket whose WebSocket never leaves CONNECTING, which emits no open, error or close
 * and so never reaches the reconnect path. Above Baileys' connectTimeoutMs (20 s by default), which
 * ws already enforces on a handshake that gets no answer, and applied only while the WebSocket is
 * still connecting, so it never cuts into a login or a socket waiting for its QR to be scanned.
 */
const BAILEYS_WS_CONNECTING_DEADLINE_MS = 60_000;

/** Bound on an HTTP(S) proxy's CONNECT reply, matching Baileys' default connectTimeoutMs. */
const PROXY_CONNECT_TIMEOUT_MS = 20_000;

/**
 * HttpsProxyAgent whose proxy socket cannot outlive the request that asked for it. The library awaits
 * the CONNECT reply with no abort hook or timeout, so a proxy that accepts TCP and never answers kept
 * its socket open after ws abandoned the handshake: one more open connection per reconnect attempt.
 * The socket is destroyed when the request is aborted (what ws does) or when the reply is overdue (a
 * request destroyed before it has a socket emits nothing). The signal has to be in connectOpts while
 * super.connect() runs synchronously, which is where the socket is opened; it is restored right after
 * so concurrent requests on the agent keep their own.
 */
class AbortableHttpsProxyAgent extends HttpsProxyAgent<string> {
  constructor(
    proxyUrl: string,
    private readonly connectTimeoutMs: number,
  ) {
    super(proxyUrl);
  }

  override async connect(req: ClientRequest, opts: Parameters<HttpsProxyAgent<string>['connect']>[1]): Promise<Socket> {
    const controller = new AbortController();
    const abort = (): void => controller.abort();
    req.once('abort', abort);
    const timer = setTimeout(abort, this.connectTimeoutMs);
    timer.unref();
    const connectOpts = this.connectOpts;
    this.connectOpts = { ...connectOpts, signal: controller.signal };
    const pending = super.connect(req, opts);
    this.connectOpts = connectOpts;
    try {
      return await pending;
    } finally {
      clearTimeout(timer);
      req.off('abort', abort);
    }
  }
}

/**
 * Build the Node-layer agent for a session egress proxy (#859). The WhatsApp WebSocket (`agent`) and
 * media uploads (`fetchAgent`) ride it; downloads and the version lookup go through global fetch,
 * which needs {@link createProxyDispatcher} instead. Credentials stay in the URL and are
 * authenticated on the socket itself, so none of the Chromium CDP auth timing the wwjs engine is
 * exposed to applies here. The scheme set matches the create-session DTO validator; anything else
 * (a pre-validation DB row) throws, failing the session closed rather than silently going direct.
 */
export function createProxyAgent(proxyUrl: string, connectTimeoutMs = PROXY_CONNECT_TIMEOUT_MS): Agent {
  const { protocol } = new URL(proxyUrl);
  if (protocol === 'http:' || protocol === 'https:') {
    return new AbortableHttpsProxyAgent(proxyUrl, connectTimeoutMs);
  }
  if (protocol === 'socks4:' || protocol === 'socks5:') {
    const agent = new SocksProxyAgent(proxyUrl);
    // The library passes URL.hostname through, so an IPv6 literal keeps its brackets and fails as a
    // DNS lookup of "[::1]". Mutated in place: userId and password are non-enumerable on this object.
    agent.proxy.host = agent.proxy.host?.replace(/^\[|\]$/g, '');
    return agent;
  }
  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
 * behind them (sock, status, reconnect counters, the lazily-loaded library). The adapter keeps the
 * public IWhatsAppEngine members as thin forwarders and injects this narrow host surface via
 * closures, so the delegate never touches adapter state directly; the two state fields the rest of
 * the adapter reads live (`sock`) are public here and aliased by adapter accessors.
 */
export interface BaileysLifecycleHost {
  readonly logger: ReturnType<typeof createLogger>;
  /** This session's multi-file auth dir (authDir/sessionId) — wiped by clearAuthState on terminal logout. */
  readonly authPath: string;
  /** Adapter config, passed through: proxyUrl/sessionId in connectInner, messageStore/dbSessionId in
   *  the retry-getMessage path and logout's session cleanup. */
  readonly config: BaileysAdapterConfig;
  /** Live-call cache handle — the map is owned by the events delegate (call events + rejectCall);
   *  lifecycle teardown clears it so a late rejectCall() reports not-found on a dead socket. */
  readonly liveCalls: Map<string, { callFrom: string; expiresAt: number }>;
  /** `628999:[email protected]` / `[email protected]` -> `628999`. */
  extractPhone(id: string | undefined): string | null;
  toNeutralJid(jid: string): string;
  /** Persist contact records pushed by the socket (contacts.upsert/update, messaging-history.set). */
  upsertContacts: BaileysSessionStore['upsertContacts'];
  /** Persist chat records pushed by the socket (chats.upsert/update, messaging-history.set). */
  upsertChats: BaileysSessionStore['upsertChats'];
  /** Drop chats the socket reports deleted (chats.delete). */
  removeChats: BaileysSessionStore['removeChats'];
  /** Learn lid<->phone mappings pushed by the socket (messaging-history.set, lid-mapping.update). */
  addLidMappings: BaileysSessionStore['addLidMappings'];
  handleMessagesUpsert: BaileysEvents['handleMessagesUpsert'];
  handleMessagesUpdate: BaileysEvents['handleMessagesUpdate'];
  handleMessageReceiptUpdate: BaileysEvents['handleMessageReceiptUpdate'];
  logContactEvent: BaileysEvents['logContactEvent'];
  handleGroupParticipantsUpdate: BaileysEvents['handleGroupParticipantsUpdate'];
  handleGroupsUpdate: BaileysEvents['handleGroupsUpdate'];
  handleGroupsUpsert: BaileysEvents['handleGroupsUpsert'];
  handleGroupJoinRequest: BaileysEvents['handleGroupJoinRequest'];
  handleCallEvents: BaileysEvents['handleCallEvents'];
  handlePresenceUpdate: BaileysEvents['handlePresenceUpdate'];
  /** Drop the store writes of messages still being processed; called before an unlink wipes the store. */
  fenceStoredWrites: BaileysEvents['fenceStoredWrites'];
  captureHistoryMessages: BaileysHistory['captureHistoryMessages'];
  /** Backfill names the initial sync skipped (runs on connection 'open'). */
  hydrateNames: BaileysHistory['hydrateNames'];
  /** Pull the saved address book from a snapshot (a first link's pull, once its history sync is quiet). */
  restoreAddressbookSnapshot: BaileysHistory['restoreAddressbookSnapshot'];
  /** The currently-registered onQRCode callback, if any (assigned at initialize()). */
  getOnQRCode(): EngineEventCallbacks['onQRCode'];
  /** The currently-registered onReady callback, if any (assigned at initialize()). */
  getOnReady(): EngineEventCallbacks['onReady'];
  /** The currently-registered onDisconnected callback, if any (assigned at initialize()). */
  getOnDisconnected(): EngineEventCallbacks['onDisconnected'];
  /** The currently-registered onReconnecting callback, if any (assigned at initialize()). */
  getOnReconnecting(): EngineEventCallbacks['onReconnecting'];
  /** The currently-registered onError callback, if any (assigned at initialize()). */
  getOnError(): EngineEventCallbacks['onError'];
  /** The currently-registered onStateChanged callback, if any (assigned at initialize()). */
  getOnStateChanged(): EngineEventCallbacks['onStateChanged'];
  /** The currently-registered onCredentialTeardownStarted callback, if any (assigned at initialize()). */
  getOnCredentialTeardownStarted(): EngineEventCallbacks['onCredentialTeardownStarted'];
  /** The currently-registered onAccountRestriction callback, if any (assigned at initialize()). */
  getOnAccountRestriction(): EngineEventCallbacks['onAccountRestriction'];
}

export class BaileysLifecycle {
  /** A close more than this long after the previous close restarts the backoff counter from scratch
   *  instead of inheriting an old incident's attempts. The backoff wait counts toward the gap. */
  private static readonly RECONNECT_STABILITY_RESET_MS = 5 * 60_000;
  /** How long a first link's history sync must stay silent before the address-book pull runs. */
  private static readonly ADDRESSBOOK_QUIET_MS = 20_000;

  /** Live Baileys socket, null when disconnected. Public so the adapter's `sock` accessor can alias
   *  it (an unmodified spec pokes `adapter.sock` through a cast; delegate hosts read it live). */
  sock: WASocket | null = null;
  private status: EngineStatus = EngineStatus.DISCONNECTED;
  private qrCode: string | null = null;
  private qrRenderSequence = 0;
  private phoneNumber: string | null = null;
  private pushName: string | null = null;
  /** Aborted by disconnect()/logout()/destroy(); the adapter is single-use from then on. */
  private readonly teardown = new AbortController();
  private get intentionalClose(): boolean {
    return this.teardown.signal.aborted;
  }
  private readonly versionResolver: BaileysVersionResolver;
  private connecting = false;
  private reconnectAttempts = 0;
  private reconnectTimer?: ReturnType<typeof setTimeout>;
  /** The current socket's BAILEYS_WS_CONNECTING_DEADLINE_MS backstop. */
  private connectingTimer?: ReturnType<typeof setTimeout>;
  /** A first link's pending address-book pull (see scheduleAddressbookRestore). */
  private addressbookTimer?: ReturnType<typeof setTimeout>;
  /** Date.now() of the last close that scheduled a reconnect — input to the stability reset. */
  private lastConnectionCloseAt = 0;
  /** 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 on first use and closed at teardown. */
  private dispatcher?: Dispatcher;
  /**
   * The participant lists Baileys reuses for group sends instead of querying one per message. Kept up to
   * date by the group events registered below, dropped with every socket (see dropConnectionState).
   * Public so the groups delegate can forget a group right after it changes its membership.
   */
  readonly groupMetadata = new GroupMetadataCache(groupMetadataCacheTtlMs());

  constructor(private readonly host: BaileysLifecycleHost) {
    this.versionResolver = new BaileysVersionResolver({
      authDir: this.host.config.authDir || path.dirname(this.host.authPath),
      sessionId: this.host.config.sessionId,
      logger: this.host.logger,
    });
  }

  /** The module once {@link loadLib} has loaded it, which happens before any socket exists. */
  get loadedLib(): typeof BaileysLib | undefined {
    return this.lib;
  }

  /** Lazily loaded @whiskeysockets/baileys module (ESM-only; loaded on first connect, not at boot). */
  async loadLib(): Promise<typeof BaileysLib> {
    return (this.lib ??= await import('@whiskeysockets/baileys'));
  }

  /** Dispatcher for Baileys' global-fetch calls: undefined without a proxy (direct). */
  fetchDispatcher(): Dispatcher | undefined {
    const { proxyUrl } = this.host.config;
    if (!proxyUrl) {
      return undefined;
    }
    return (this.dispatcher ??= createProxyDispatcher(proxyUrl));
  }

  /**
   * Drop the proxy's pooled tunnels at teardown instead of leaving them to idle out. close(), not
   * destroy(): a request already in progress finishes. A later fetch builds a fresh dispatcher.
   */
  private closeFetchDispatcher(): void {
    const dispatcher = this.dispatcher;
    this.dispatcher = undefined;
    void dispatcher?.close().catch(() => undefined);
  }

  async initialize(): Promise<void> {
    // Single-use after teardown: disconnect()/destroy()/forceDestroy()/logout() set this latch, and
    // it must NOT be re-armed here. A retired adapter (e.g. one whose session was stopped/deleted
    // during the service's pre-initialize window) would otherwise open a fresh socket no caller is
    // tracking. A new adapter starts with the latch false, so the first initialize() proceeds; a
    // later teardown leaves it true for the adapter's lifetime. connectInner() re-checks the latch
    // after its auth/version awaits as a fence against teardown during those I/O steps.
    if (this.intentionalClose) {
      return;
    }
    const chatStateStore = this.host.config.chatStateStore;
    if (chatStateStore) {
      await chatStateStore.refreshSession(this.host.config.sessionId).catch(() => undefined);
      // A teardown during that read must still keep this adapter from opening a socket.
      if (this.intentionalClose) {
        return;
      }
    }

    // An install that skipped a Baileys patch fails later with errors that name no cause: an
    // app-state resync that never terminates, a newsletter create that cannot parse its reply.
    // Say so here instead, while the operator is still looking at the startup logs.
    const unapplied = unappliedPatches('baileys');
    if (unapplied.length) {
      this.host.logger.error(unappliedPatchesMessage('baileys', unapplied));
    }

    try {
      await this.connect();
    } catch (err) {
      this.setStatus(EngineStatus.FAILED);
      this.host.getOnError()?.(err instanceof Error ? err.message : String(err));
      throw err;
    }
  }

  private async connect(): Promise<void> {
    // I4: in-flight guard — skip if a connect() is already in progress.
    if (this.connecting) {
      return;
    }
    this.connecting = true;
    try {
      await this.connectInner();
    } finally {
      this.connecting = false;
    }
  }

  private async connectInner(): Promise<void> {
    this.setStatus(EngineStatus.INITIALIZING);
    // Build the egress proxy agent BEFORE any auth-state I/O so an unusable proxy value fails the
    // session (engine_error) instead of silently connecting direct (#859).
    let proxyAgent: Agent | undefined;
    if (this.host.config.proxyUrl) {
      proxyAgent = createProxyAgent(this.host.config.proxyUrl);
      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();
    // The first load of the library takes a while; a stop meanwhile must not have the auth dir created for it.
    if (this.intentionalClose) {
      return;
    }
    const { state, saveCreds } = await useAtomicMultiFileAuthState(this.host.authPath, b, this.host.logger);
    // A teardown during those loads already closed the dispatcher: the lookup would build a new one
    // that nothing closes and send the stopped session's requests through its proxy. One during the
    // lookup aborts it, and the latch check below bails.
    if (this.intentionalClose) {
      return;
    }
    const version = await this.versionResolver.resolve(b, {
      dispatcher: this.fetchDispatcher(),
      signal: this.teardown.signal,
    });
    // BaileysLogger matches ILogger exactly; cast needed because the module resolves the type
    // through a deep import path that TypeScript does not auto-unify here. Shared by the key
    // store wrapper below and the socket itself, rather than constructing two instances.
    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
    const baileysLogger = createBaileysLogger() as unknown as ILogger;

    // Wrap the raw file-backed signal key store with Baileys' own official caching layer.
    // Without it, every session read/write hits disk directly with no protection against a
    // write-then-immediate-read race — observed here as a freshly-established Signal session
    // appearing "missing" moments later, forcing Baileys to discard it and start a brand new
    // PreKey handshake on the very next send (visible as repeated "Closing session" log spam and
    // the recipient stuck on "waiting for this message" until a slow WhatsApp-side retry rescues
    // it). makeCacheableSignalKeyStore keeps the just-written state visible in memory immediately,
    // regardless of disk I/O timing.
    state.keys = b.makeCacheableSignalKeyStore(state.keys, baileysLogger);

    // C2: resurrect-after-stop guard — if disconnect/logout/destroy ran during the awaits above,
    // bail now so we don't create a live socket for a session that was intentionally stopped.
    if (this.intentionalClose) {
      return;
    }

    // An internal reconnect (transient drop) overwrites this.sock WITHOUT going through
    // disconnect/logout/destroy, so the previous socket's WebSocket and the 18 ev listeners we
    // register below would leak on every reconnect. Tear the prior socket down first. Detach OUR
    // connection.update listener BEFORE end(): Baileys' own end() synchronously emits a synthetic
    // connection.update {connection:'close'}, which — if still wired — would re-enter
    // handleConnectionUpdate and schedule a spurious second reconnect.
    const previous = this.sock;
    if (previous) {
      try {
        previous.ev.removeAllListeners('connection.update');
        previous.ev.removeAllListeners('creds.update');
        previous.ev.removeAllListeners('messages.upsert');
        previous.ev.removeAllListeners('messages.update');
        previous.ev.removeAllListeners('message-receipt.update');
        previous.ev.removeAllListeners('contacts.upsert');
        previous.ev.removeAllListeners('contacts.update');
        previous.ev.removeAllListeners('chats.upsert');
        previous.ev.removeAllListeners('chats.update');
        previous.ev.removeAllListeners('chats.delete');
        previous.ev.removeAllListeners('messaging-history.set');
        previous.ev.removeAllListeners('lid-mapping.update');
        previous.ev.removeAllListeners('group-participants.update');
        previous.ev.removeAllListeners('groups.update');
        previous.ev.removeAllListeners('groups.upsert');
        previous.ev.removeAllListeners('group.join-request');
        previous.ev.removeAllListeners('call');
        previous.ev.removeAllListeners('presence.update');
        void previous.end(undefined);
      } catch {
        // end() may already have run from Baileys' own close handler — a safe no-op.
      }
    }

    // Group changes made while the previous socket was down never reached it, so nothing it cached is
    // trusted by the next one.
    this.groupMetadata.clear();

    const fetchDispatcher = this.fetchDispatcher();
    const sock: WASocket = b.default({
      auth: state,
      version,
      browser: BAILEYS_BROWSER,
      printQRInTerminal: false,
      // Session egress proxy (#859): the WS and media uploads share one agent; undefined = direct.
      // Media downloads use fetchDispatcher() instead, since Baileys fetches them with global fetch.
      agent: proxyAgent,
      fetchAgent: proxyAgent,
      // 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.
      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,
      // or lid->phone mappings ever arrive (the address-book app-state sync only runs once history sync is
      // enabled; see WhiskeySockets/Baileys Socket/index.js + Socket/chats.js). Returning true enables it
      // while keeping the full-archive download opt-in: with syncFullHistory false WhatsApp sends the
      // RECENT window + the full contact/app-state snapshot, not the entire message history.
      shouldSyncHistoryMessage: () => true,
      syncFullHistory: process.env.BAILEYS_SYNC_FULL_HISTORY === 'true',
      // Baileys defaults markOnlineOnConnect to true: every (re)connect broadcasts `available`,
      // and WhatsApp suppresses the paired phone's push notifications while any linked device is
      // online — a 24/7 gateway then permanently silences the phone (#871). Set
      // BAILEYS_MARK_ONLINE_ON_CONNECT=false to stay invisible; the default preserves prior
      // behavior. Note this only gates the on-connect presence: the typing / chat-state API still
      // sends per-chat presence for that call regardless.
      markOnlineOnConnect: process.env.BAILEYS_MARK_ONLINE_ON_CONNECT !== 'false',
      // Baileys defaults this to `async () => undefined` (Defaults/index.js). Without a real
      // implementation, WhatsApp's message-retry protocol — triggered whenever a recipient's client
      // fails to decrypt on the first attempt — has nothing to resend, so the recipient is stuck on
      // "waiting for this message" indefinitely instead of the retry resolving it within seconds.
      // Backed by the same messageStore used for reply/forward/react/delete-by-id. Baileys relays the
      // answer to key.remoteJid, and a retry receipt names its message by id alone, so a stored message
      // from a provably different chat is refused: a forged receipt must not pull it into this one.
      getMessage: async key => {
        if (!key.id) {
          return undefined;
        }
        const stored = await this.host.config.messageStore?.getMessage(this.host.config.dbSessionId, key.id);
        if (!stored) {
          return undefined;
        }
        // An RSVP to an event this account posted in a 1:1 chat names the event by its key as the guest
        // sees it, so its remoteJid is this account. Baileys rewrites reaction and poll keys to our side
        // but not event keys, so our own 1:1 message asked for under our own jid is that same chat.
        const bare = (jid: string): string => `${userPart(jid)}@${jid.split('@')[1]}`;
        const asked = key.remoteJid ? bare(key.remoteJid) : undefined;
        const me = this.sock?.user;
        const askedByGuest =
          !!asked &&
          stored.key.fromMe === true &&
          chatKind(stored.key.remoteJid ?? '') === 'individual' &&
          [me?.id, me?.lid].some(own => !!own && bare(own) === asked);
        if (askedByGuest) {
          return stored.message ?? undefined;
        }
        const neutral = (jid: string): string => this.host.toNeutralJid(jid);
        const chat = [stored.key.remoteJid, stored.key.remoteJidAlt];
        if (differentWaIds(chat, [key.remoteJid], neutral)) {
          return undefined;
        }
        // A lid the session cannot map cannot be compared with a phone-number chat, so ask Baileys'
        // own mapping (a local store read) for its phone number too. When neither knows it, the retry
        // is still answered: refusing then would leave a real recipient waiting for good.
        const lid = key.remoteJid;
        if (lid?.endsWith('@lid') && neutral(lid).endsWith('@lid')) {
          const pn = await this.sock?.signalRepository?.lidMapping?.getPNForLID(lid).catch(() => null);
          if (pn && differentWaIds(chat, [pn], neutral)) {
            return undefined;
          }
        }
        return stored.message ?? undefined;
      },
      // Every group send needs the group's participant list, and without this Baileys queries it for each
      // message. Read through the cache, on a miss with the same query Baileys would have made; a failure
      // surfaces as the send's own, exactly as before. 0 in BAILEYS_GROUP_METADATA_CACHE_TTL_MS switches it
      // off, and Baileys then queries on its own.
      cachedGroupMetadata: jid => this.groupMetadata.read(jid, () => sock.groupMetadata(jid)),
      logger: baileysLogger,
    });
    this.sock = sock;

    // Baileys re-emits ws's 'unexpected-response', and any listener there stops ws from aborting the
    // handshake itself: an upgrade answered with anything but 101 (a 503 from WhatsApp's edge or from a
    // session proxy) leaves the socket CONNECTING for good, and the session at INITIALIZING with no
    // retry (#1546). Ending it emits the close that handleConnectionUpdate logs, backs off and retries.
    // A plain Error on purpose: a Boom carrying the HTTP status would turn a 401, 403 or 440 upgrade
    // response into the terminal close of the same code.
    sock.ws.on('unexpected-response', (_req: ClientRequest, res: IncomingMessage) => {
      void sock.end(new Error(`WebSocket upgrade refused (HTTP ${res.statusCode})`));
    });
    this.connectingTimer = setTimeout(() => {
      if (this.sock === sock && sock.ws.isConnecting) {
        void sock.end(new Error(`WebSocket still connecting after ${BAILEYS_WS_CONNECTING_DEADLINE_MS} ms`));
      }
    }, BAILEYS_WS_CONNECTING_DEADLINE_MS);
    this.connectingTimer.unref();

    // Baileys raises the counter above 0 once, when a first link's initial sync ends (or times out).
    // Whole-creds emits carry the field too, so only that transition on a first link arms the pull.
    let awaitingFirstSync = !((state.creds.accountSyncCounter ?? 0) > 0);
    sock.ev.on('creds.update', update => {
      void saveCreds().catch(err => {
        this.host.logger.warn('Baileys creds.update save failed', {
          sessionId: this.host.config.sessionId,
          error: err instanceof Error ? err.message : String(err),
        });
      });
      if (awaitingFirstSync && (update.accountSyncCounter ?? 0) > 0) {
        awaitingFirstSync = false;
        this.scheduleAddressbookRestore(sock);
      }
    });
    sock.ev.on('connection.update', update => this.handleConnectionUpdate(update));
    sock.ev.on('messages.upsert', event => this.host.handleMessagesUpsert(event));
    sock.ev.on('messages.update', updates => this.host.handleMessagesUpdate(updates));
    sock.ev.on('message-receipt.update', updates => this.host.handleMessageReceiptUpdate(updates));
    sock.ev.on('contacts.upsert', contacts => {
      this.host.logContactEvent('contacts.upsert', contacts);
      this.host.upsertContacts(contacts);
    });
    sock.ev.on('contacts.update', updates => {
      this.host.logContactEvent('contacts.update', updates);
      this.host.upsertContacts(updates);
    });
    sock.ev.on('chats.upsert', chats => {
      this.host.logger.debug('Baileys chats event', {
        action: 'baileys_chats',
        event: 'upsert',
        count: chats?.length ?? 0,
      });
      this.host.upsertChats(chats);
    });
    sock.ev.on('chats.update', updates => {
      this.host.logger.debug('Baileys chats event', {
        action: 'baileys_chats',
        event: 'update',
        count: updates?.length ?? 0,
      });
      // A disappearing-messages timer changed on the phone (or turned off, which reads null) reaches us as a
      // chat update only, and the cached list's timer is what a group send stamps on its stanza. The same
      // own key makes upsertChats take the new timer.
      for (const update of updates ?? []) {
        if (Object.hasOwn(update, 'ephemeralExpiration')) this.groupMetadata.invalidate(update.id);
      }
      this.host.upsertChats(updates);
    });
    sock.ev.on('chats.delete', ids => {
      this.host.logger.debug('Baileys chats event', {
        action: 'baileys_chats',
        event: 'delete',
        count: ids?.length ?? 0,
      });
      this.host.removeChats(ids);
    });
    // The same events keep the group metadata cache honest: a membership change, a (re)join, a settings
    // change or a whole-metadata snapshot drops that group, so the next send reads it again.
    sock.ev.on('group-participants.update', event => {
      this.groupMetadata.invalidate(event.id);
      this.host.handleGroupParticipantsUpdate(event);
    });
    sock.ev.on('groups.update', updates => {
      this.groupMetadata.applyUpdates(updates);
      this.host.handleGroupsUpdate(updates);
    });
    sock.ev.on('groups.upsert', groups => {
      for (const group of groups) this.groupMetadata.invalidate(group.id);
      this.host.handleGroupsUpsert(groups);
    });
    sock.ev.on('group.join-request', event => this.host.handleGroupJoinRequest(event));
    sock.ev.on('messaging-history.set', history => {
      // A chunk still arriving means the pull could be absorbed into the next one: wait again.
      if (this.addressbookTimer) {
        this.scheduleAddressbookRestore(sock);
      }
      // History sync copies conversation.displayName into `name`, which is a chat title, not the
      // address-book saved name (that arrives via contacts.upsert from app-state contactAction).
      // Fold the title into notify so chat-name fallback still works, and leave `name` unset so
      // GET /contacts stays the agenda rather than every 1:1 the account has ever opened.
      this.host.upsertContacts(
        (history.contacts ?? []).map(c => ({
          ...c,
          notify: c.notify ?? c.name,
          name: undefined,
        })),
      );
      this.host.upsertChats(history.chats);
      this.host.addLidMappings(history.lidPnMappings ?? []);
      void this.host
        .captureHistoryMessages(history.messages ?? [])
        .catch(error => this.host.logger.warn('Failed to capture history messages', { error: String(error) }));
      this.host.logger.debug('History sync received', {
        action: 'baileys_history_set',
        sessionId: this.host.config.sessionId,
        syncType: history.syncType,
        isLatest: history.isLatest,
        progress: history.progress,
        chats: history.chats?.length ?? 0,
        messages: history.messages?.length ?? 0,
        contacts: history.contacts?.length ?? 0,
        namedContacts: history.contacts?.filter(c => c.name || c.notify).length ?? 0,
        lidContacts: history.contacts?.filter(c => c.lid).length ?? 0,
        lidPnMappings: history.lidPnMappings?.length ?? 0,
      });
    });
    // WhatsApp pushes this when a lid<->phone mapping is learned (renamed from the pre-v7
    // 'chats.phoneNumberShare' event, whose { lid, jid } payload this shape directly replaces).
    sock.ev.on('lid-mapping.update', ({ lid, pn }) => this.host.addLidMappings([{ lid, pn }]));
    sock.ev.on('call', calls => this.host.handleCallEvents(calls));
    sock.ev.on('presence.update', update => this.host.handlePresenceUpdate(update));
  }

  /**
   * Pull the address book once a first link's history sync has gone quiet. During the initial sync
   * Baileys folds saved names into the history batch, where they are stripped as chat titles (see
   * BaileysHistory.hydrateNames), and that run opens with accountSyncCounter 0, so the pull on
   * 'open' skips it. Pulling straight away would share the event buffer with the next history chunk
   * and be absorbed the same way, so every chunk pushes the pull back by the quiet window.
   */
  private scheduleAddressbookRestore(sock: WASocket): void {
    this.cancelAddressbookRestore();
    this.addressbookTimer = setTimeout(() => {
      this.addressbookTimer = undefined;
      if (this.sock !== sock) {
        return;
      }
      this.host.restoreAddressbookSnapshot().catch(err => {
        this.host.logger.warn('Address-book restore after the initial sync failed', {
          sessionId: this.host.config.sessionId,
          error: err instanceof Error ? err.message : String(err),
        });
      });
    }, BaileysLifecycle.ADDRESSBOOK_QUIET_MS);
    this.addressbookTimer.unref();
  }

  private cancelAddressbookRestore(): void {
    clearTimeout(this.addressbookTimer);
    this.addressbookTimer = undefined;
  }

  private handleConnectionUpdate(update: {
    connection?: string;
    qr?: string;
    isNewLogin?: boolean;
    lastDisconnect?: { error?: unknown };
    reachoutTimeLock?: { isActive?: boolean; timeEnforcementEnds?: Date; enforcementType?: string };
  }): void {
    const { connection, qr, isNewLogin, lastDisconnect, reachoutTimeLock } = update;

    // Arrives on its own update (no `connection` key) both when WhatsApp pushes a change and when
    // probeAccountRestriction() pulls the current state — Baileys routes its own query result back
    // through this same event, so one handler covers both channels.
    if (reachoutTimeLock) {
      this.reportReachoutTimelock(reachoutTimeLock);
    }

    // Baileys keeps rotating the QR (every 20-60 s) until the socket ends, including after the link
    // was accepted; a refresh in that window must not put the session back at QR_READY.
    if (qr && this.status !== EngineStatus.AUTHENTICATING) {
      // Baileys hands us the raw QR ref string; render it to a PNG data URL so the stored
      // value matches the whatsapp-web.js engine's contract (the dashboard does <img src={qrCode}>).
      void this.handleQrCode(qr);
    }

    if (isNewLogin) {
      // WhatsApp accepted the QR scan or pairing code. It asks for a restart next (a 515 close, which
      // the branch below turns into INITIALIZING) and the reconnect opens READY. Left at QR_READY, a
      // repeat pairing request in that window would pass the guard and overwrite the just-linked
      // creds.me. AUTHENTICATING is what whatsapp-web.js reports at the same point. The link worked, so
      // that restart is attempt 1 whatever failed before the scan.
      this.qrCode = null;
      this.reconnectAttempts = 0;
      this.setStatus(EngineStatus.AUTHENTICATING);
    }

    if (connection === 'connecting') {
      this.setStatus(EngineStatus.INITIALIZING);
    }

    if (connection === 'open') {
      clearTimeout(this.connectingTimer);
      this.qrCode = null;
      this.phoneNumber = this.host.extractPhone(this.sock?.user?.id);
      this.pushName = this.sock?.user?.name ?? null;
      // The account's own lid<->phone pair. Baileys stores it in its own mapping without emitting
      // lid-mapping.update, and an account whose only traffic is API sends never sees it on a message
      // key either, so a lid-addressed group's `<lid>@lid` row for the account stayed unresolved and
      // every self-admin check read it as somebody else.
      const me = this.sock?.user;
      if (me?.id && me.lid) {
        this.host.addLidMappings([{ lid: `${userPart(me.lid)}@lid`, pn: `${userPart(me.id)}@s.whatsapp.net` }]);
      }
      // The reconnect counter is not reset here: a connection that drops seconds after the handshake
      // would otherwise redial at attempt 1 forever. The close branch resets it once more than the
      // stability window passes between drops.
      this.setStatus(EngineStatus.READY);
      this.host.getOnReady()?.(this.phoneNumber ?? '', this.pushName ?? '');
      // WhatsApp only PUSHES a timelock when it changes, so a gateway that starts (or reconnects)
      // while the account is already restricted would never hear about it. Ask once per connection.
      void this.probeAccountRestriction();
      // Backfill names the initial sync skipped (see BaileysHistory.hydrateNames).
      void this.host.hydrateNames();
    }

    if (connection === 'close') {
      clearTimeout(this.connectingTimer);
      this.cancelAddressbookRestore();
      const statusCode = (lastDisconnect?.error as { output?: { statusCode?: number } } | undefined)?.output
        ?.statusCode;

      if (this.intentionalClose) {
        this.setStatus(EngineStatus.DISCONNECTED);
        return;
      }

      if (statusCode === this.lib?.DisconnectReason.loggedOut) {
        // Credentials invalidated — terminal. Re-linking requires a fresh QR/pairing, so the now-dead
        // multi-file auth dir MUST be wiped: otherwise the next connect() reloads the stale creds and
        // Baileys silently retries them instead of emitting a new QR, leaving the session stuck (no QR).
        void this.handleRemoteLoggedOut();
        return;
      }

      if (statusCode === (this.lib?.DisconnectReason.connectionReplaced ?? 440)) {
        // Another live instance took over this account. Reconnecting
        // would fight it — two instances endlessly replacing each other — so this is terminal:
        // the operator stops the other instance, then starts this session again (onError = terminal
        // + evict in the session service). Auth state is NOT cleared: the link itself is still valid.
        this.setStatus(EngineStatus.FAILED);
        this.dropConnectionState(); // terminal close: dead call handles, like the loggedOut branch above
        this.host.getOnError()?.(
          `${CONNECTION_REPLACED_REASON} — stop the other instance, then start this session again`,
        );
        return;
      }

      if (statusCode === (this.lib?.DisconnectReason.forbidden ?? 403)) {
        // The account itself was rejected by WhatsApp (banned/blocked — an authorization-level
        // refusal that must not be retried). Retrying forever is pointless and risks worsening
        // the account's standing, so this is terminal like 440. Auth state is NOT cleared (unlike
        // 401): this is an account-level refusal, not dead credentials — the operator keeps the auth
        // files for inspection and can retry manually once the account issue is resolved.
        this.setStatus(EngineStatus.FAILED);
        this.dropConnectionState(); // terminal close: dead call handles, like the loggedOut branch above
        this.host.getOnError()?.(
          `${ACCOUNT_REJECTED_REASON} — the number is likely banned or blocked; reconnecting will not help`,
        );
        return;
      }

      // Every other close (408/411/428/500/503/515/undefined) is transient: reconnect with capped
      // backoff and NO attempt ceiling — a long network outage must
      // not kill the session. The counter resets on a scan, when a QR window runs out, and via the
      // stability window below.
      // Do NOT fire onDisconnected here; this is a transient drop, not a terminal disconnect.
      this.host.logger.log('Baileys connection dropped; reconnecting', {
        sessionId: this.host.config.sessionId,
        statusCode,
        reason: (lastDisconnect?.error as Error | undefined)?.message,
        action: 'baileys_connection_dropped',
      });

      // Baileys ends an unscanned socket with a 408 once its QR refs run out, the same code as a lost
      // connection, so only its message tells them apart. Every other close while a QR waits (503, 500,
      // 428, a lost connection) is a failure like any other. Should Baileys reword the message, the
      // expiry counts too, which backs off rather than loops.
      const qrWindowEnded = (lastDisconnect?.error as Error | undefined)?.message === 'QR refs attempts ended';

      // The socket is dead NOW, but the reconnect attempt only runs after the backoff delay below
      // (up to 60 s + jitter; connectInner's own setStatus(INITIALIZING) fires just before the new
      // socket is created). Staying READY across that window makes probeLiveness() report a live
      // session and lets sends fail against the dead socket, so drop to INITIALIZING here — the
      // 'open' branch restores READY. setStatus no-ops on an unchanged status, so the duplicate
      // closes Baileys can emit per drop do not flap onStateChanged.
      this.setStatus(EngineStatus.INITIALIZING);

      // Duplicate close while a reconnect timer is already pending — ignore it WITHOUT burning an
      // attempt (Baileys can emit more than one close per drop; the increment must come after this).
      if (this.reconnectTimer) {
        return;
      }

      // Stability reset: a close more than 5 minutes after the previous one starts the backoff fresh
      // instead of inheriting the old counter. The gap runs close to close, so the backoff wait counts
      // toward it. A drop sooner than that keeps climbing it, so a link that fails right after each
      // handshake backs off instead of redialing every second or two.
      // A QR window that ran out resets it too: WhatsApp answered, and a QR left unscanned for hours
      // must not add up to a reconnect loop.
      const now = Date.now();
      if (qrWindowEnded || now - this.lastConnectionCloseAt > BaileysLifecycle.RECONNECT_STABILITY_RESET_MS) {
        this.reconnectAttempts = 0;
      }
      this.lastConnectionCloseAt = now;
      this.scheduleReconnect(!qrWindowEnded);
    }
  }

  /**
   * Translate Baileys' reachout-timelock state into the neutral restriction signal. Baileys reports
   * this first-class — it is not inferred from failures — and it reports the lift as well as the
   * onset, so `isActive: false` is a positive "no restriction" and is forwarded as `null`.
   *
   * A timelock does NOT close the connection: the account stays linked and existing chats keep
   * working, only starting new conversations is blocked. Nothing here touches status or reconnects.
   */
  private reportReachoutTimelock(state: {
    isActive?: boolean;
    timeEnforcementEnds?: Date;
    enforcementType?: string;
  }): void {
    const report = this.host.getOnAccountRestriction();
    if (!report) return;

    if (!state.isActive) {
      report(null);
      return;
    }

    // `time_enforcement_ends` is a server-supplied string Baileys parses with parseInt, so a
    // malformed value yields an Invalid Date whose getTime() is NaN — which would serialize to null
    // and read as "no expiry known". Same outcome, but reached deliberately rather than by accident.
    const endsAt = state.timeEnforcementEnds?.getTime();
    report({
      kind: 'reachout_timelock',
      // DEFAULT is Baileys' own "no specific enforcement type" value, not a placeholder of ours.
      code: state.enforcementType ?? 'DEFAULT',
      expiresAt: typeof endsAt === 'number' && Number.isFinite(endsAt) ? endsAt : undefined,
    });
  }

  /**
   * Ask WhatsApp for the account's current restriction standing. The answer is not used here:
   * Baileys emits its own `connection.update { reachoutTimeLock }` with the result, so it arrives
   * through the same path as a pushed change.
   *
   * Best-effort by design — an account or server that does not answer this query must not turn a
   * healthy connection into a logged failure, so it stays at debug level.
   */
  private async probeAccountRestriction(): Promise<void> {
    try {
      await this.sock?.fetchAccountReachoutTimelock();
    } catch (error) {
      this.host.logger.debug('Could not read the account restriction state', {
        action: 'baileys_restriction_probe_failed',
        sessionId: this.host.config.sessionId,
        error: String(error),
      });
    }
  }

  /**
   * Schedule the next reconnect attempt with capped exponential backoff (1 s doubling up to a 60 s
   * cap, plus up to 1 s jitter). Deliberately NO attempt ceiling: transient drops retry forever —
   * only loggedOut (401), forbidden (403), and connectionReplaced (440) are terminal. A connect()
   * failure inside the attempt is just a failed attempt: warn and schedule the next one.
   *
   * `countAttempt` false is only the close that ends an unscanned QR window: the connection worked,
   * so the reconnect is neither an attempt nor reported, and after the reset it waits the first step.
   */
  private scheduleReconnect(countAttempt = true): void {
    if (this.intentionalClose || this.reconnectTimer) {
      return;
    }
    if (countAttempt) {
      this.reconnectAttempts += 1;
    }
    const step = Math.max(this.reconnectAttempts - 1, 0);
    const delay = Math.min(60_000, 1_000 * 2 ** step) + Math.floor(Math.random() * 1000);
    // The consumer is never told about this drop through onDisconnected (deliberately: the session is
    // still linked), and the status it does see is INITIALIZING for the whole episode. So this is the
    // only signal that a retry loop is running. Fired here rather than in the close handler because
    // this is the one place every scheduled attempt passes through, including the reschedule from the
    // failed-attempt catch below, and it is already past the duplicate-close guard above.
    if (countAttempt) {
      this.host.getOnReconnecting()?.(this.reconnectAttempts, delay);
    }
    this.reconnectTimer = setTimeout(() => {
      this.reconnectTimer = undefined;
      if (this.intentionalClose) {
        return; // stopped while waiting — abort
      }
      void this.connect().catch(err => {
        // A failed attempt is NOT terminal: the outage may outlast any fixed attempt budget, so
        // schedule the following attempt.
        this.host.logger.warn('Baileys reconnect attempt failed; will retry', {
          attempt: this.reconnectAttempts,
          error: err instanceof Error ? err.message : String(err),
        });
        this.scheduleReconnect();
      });
    }, delay);
  }

  /** Render the raw Baileys QR ref to a PNG data URL, then publish it (mirrors the whatsapp-web.js engine). */
  private async handleQrCode(qr: string): Promise<void> {
    const sock = this.sock;
    const sequence = ++this.qrRenderSequence;
    // A registration refresh retires the previous secret before PNG rendering finishes.
    this.qrCode = null;
    try {
      const rendered = await qrcode.toDataURL(qr);
      // The socket can drop, or the link be accepted, while the QR renders. The handler has already
      // moved the status on, and publishing now would stamp QR_READY on a dead socket until the
      // backoff reconnect, or reopen the pairing guard on a socket that is committed to a restart.
      if (
        sequence !== this.qrRenderSequence ||
        this.sock !== sock ||
        !sock?.ws.isOpen ||
        this.status === EngineStatus.AUTHENTICATING ||
        this.status === EngineStatus.READY ||
        sock.user?.id
      ) {
        return;
      }
      this.qrCode = rendered;
      this.setStatus(EngineStatus.QR_READY);
      this.host.getOnQRCode()?.(this.qrCode);
    } catch (error) {
      this.host.logger.error('Error generating QR code', String(error));
    }
  }

  /**
   * What lives and dies with a connection: the cached call handles, which a later rejectCall() must
   * report as not-found rather than act on a dead socket, and the group metadata, whose changes the
   * socket stops reporting once it is gone.
   */
  private dropConnectionState(): void {
    this.host.liveCalls.clear();
    this.groupMetadata.clear();
  }

  disconnect(): Promise<void> {
    this.teardown.abort();
    if (this.reconnectTimer) {
      clearTimeout(this.reconnectTimer);
      this.reconnectTimer = undefined;
    }
    clearTimeout(this.connectingTimer);
    this.cancelAddressbookRestore();
    void this.sock?.end(undefined);
    this.sock = null;
    this.closeFetchDispatcher();
    // Cached call handles die with the socket — drop them so a later rejectCall() reports
    // not-found instead of acting on a closed connection.
    this.dropConnectionState();
    this.setStatus(EngineStatus.DISCONNECTED);
    return Promise.resolve();
  }

  async logout(): Promise<void> {
    this.teardown.abort();
    if (this.reconnectTimer) {
      clearTimeout(this.reconnectTimer);
      this.reconnectTimer = undefined;
    }
    // Capture the exact live socket. Without one the unlink cannot be sent, and an optional-chained
    // send would resolve as though it had been — reporting a confirmed unlink, writing the audit row,
    // and then wiping the on-disk credentials, leaving the device linked server-side with nothing
    // left to retry with. Reachable: a WhatsApp-side logout nulls the socket while the engine stays
    // registered for the whole reconnect backoff.
    const sourceSock = this.sock;
    if (!sourceSock) {
      throw new Error('No live WhatsApp socket — the unlink was not sent');
    }

    try {
      // Completion of an engine-native unlink requires a tagged IQ result from WhatsApp — Baileys'
      // own sock.logout() resolves on a WebSocket write flush (NOT an IQ ack) and transmits nothing
      // at all when creds.me is unset, so a resolved promise proves nothing about the unlink. Use
      // the public query() surface against the pinned `remove-companion-device` node instead.
      const b = await this.loadLib();
      const jid = sourceSock.user?.id;
      if (!jid) {
        // The companion identity is required to address the unlink; without it nothing is sent.
        throw new Error('No linked companion identity — the unlink was not sent');
      }
      const response: unknown = await sourceSock.query(
        {
          tag: 'iq',
          attrs: { to: b.S_WHATSAPP_NET, type: 'set', id: sourceSock.generateMessageTag(), xmlns: 'md' },
          content: [{ tag: 'remove-companion-device', attrs: { jid, reason: 'user_initiated' } }],
        },
        BAILEYS_LOGOUT_ACK_TIMEOUT_MS,
      );
      if (!response) {
        // query() resolved without a result — WhatsApp did not acknowledge the unlink request.
        throw new Error('WhatsApp did not acknowledge the unlink request');
      }

      // Acknowledged. End/null the captured socket, clear live call handles, and drop to
      // DISCONNECTED before the awaited cleanup so no send/path observes a half-torn-down socket.
      this.localSocketShutdown(sourceSock);
      this.host.fenceStoredWrites();
      await this.clearStoredAccountState();
      // Wipe the multi-file auth dir so a fresh link starts clean — stale creds would otherwise be
      // reloaded on the next connect() and block re-linking (Baileys retries them, no QR emitted).
      // A removal failure propagates: completion requires cleanup, so the operation is incomplete.
      await this.clearAuthState();
    } catch (err) {
      // EVERY failure exit (missing identity, query rejection/timeout, empty response, OR a later
      // auth removal failure) still stops sourceSock locally so no engine/socket orphan is left in
      // the service map after it evicts the engine on 502. Failure before acknowledgement must NOT
      // remove auth state — the link may still be valid server-side, and the creds are needed to
      // retry. localSocketShutdown is identity-safe: it only nulls this.sock if it still points at
      // sourceSock (a concurrent reconnect may have already swapped in a fresh socket).
      this.localSocketShutdown(sourceSock);
      throw err;
    }
  }

  /**
   * Identity-safe local shutdown of a captured socket: clears the reconnect timer, ends the socket,
   * clears cached live call handles, drops to DISCONNECTED, and nulls `this.sock` ONLY if it still
   * points at the same object (a concurrent reconnect could have swapped in a fresh one). Called at
   * every logout exit so the service's 502 genuinely means "stopped locally, operation incomplete".
   */
  private localSocketShutdown(sourceSock: WASocket): void {
    if (this.reconnectTimer) {
      clearTimeout(this.reconnectTimer);
      this.reconnectTimer = undefined;
    }
    clearTimeout(this.connectingTimer);
    this.cancelAddressbookRestore();
    try {
      void sourceSock.end(undefined);
    } catch {
      // end() may already have run from Baileys' own close handler — a safe no-op.
    }
    this.closeFetchDispatcher();
    // Cached call handles die with the connection — drop them so a later rejectCall() reports
    // not-found (404) instead of acting on a dead socket (mirrors disconnect/destroy).
    this.dropConnectionState();
    if (this.sock === sourceSock) {
      this.sock = null;
    }
    this.setStatus(EngineStatus.DISCONNECTED);
  }

  /**
   * Handle a WhatsApp-originated `loggedOut` (401) close: the credentials were invalidated server-side
   * and re-linking requires a fresh QR/pairing, so the now-dead multi-file auth dir MUST be wiped —
   * otherwise the next connect() reloads the stale creds and Baileys silently retries them instead of
   * emitting a QR, leaving the session stuck (no QR).
   *
   * The status/socket/live-call teardown happens SYNCHRONOUSLY before any await so the session
   * watchdog never processes a READY socket that is already dead. The strict auth removal is then
   * awaited as a tracked cleanup (onCredentialTeardownStarted registers it under the session NAME). On success the engine reports DISCONNECTED + onDisconnected('logged out'); on failure it
   * reports FAILED + onError (terminal — a reconnect with known-invalid auth would loop forever).
   */
  private async handleRemoteLoggedOut(): Promise<void> {
    // Synchronous teardown BEFORE any await.
    this.setStatus(EngineStatus.DISCONNECTED);
    const dead = this.sock;
    this.sock = null;
    // Cached call handles die with the connection — drop them so a later rejectCall() reports
    // not-found (404) instead of acting on a dead socket (mirrors disconnect/logout/destroy).
    this.dropConnectionState();
    // A message still being processed must not recreate a row of the unlinked account after the wipe below.
    this.host.fenceStoredWrites();
    void dead?.end(undefined);
    this.closeFetchDispatcher();

    const cleanup = (async (): Promise<void> => {
      try {
        // The unlinked account's messages and chat states go with it, as they do on an API logout: the
        // next account to link this session must not reply to, forward or retry them, nor inherit its
        // muted, archived and pinned chats.
        await this.clearStoredAccountState();
        await this.clearAuthState();
      } catch (err) {
        // A failed credential removal is terminal: report FAILED + onError instead of looking like a
        // clean disconnect (the credentials did not actually get wiped).
        this.setStatus(EngineStatus.FAILED);
        this.host.getOnError()?.(
          `${LOGOUT_CLEANUP_FAILED_REASON}: ${err instanceof Error ? err.message : String(err)}`,
        );
        return;
      }
      this.host.getOnDisconnected()?.('logged out');
    })();
    // Register the destructive promise the instant it begins (NOT guarded on this engine still being
    // live): the rm targets the session NAME's auth dir and would race a (re)created session under
    // that same name. tracked under the captured name, settled regardless of the outcome.
    this.host.getOnCredentialTeardownStarted()?.(cleanup);
    await cleanup;
  }

  /**
   * Drop the stored messages and chat states of the account being unlinked. A failure does not fail the
   * unlink, whose completion is the credential removal that follows, but it is logged: the rows that
   * survive resurface under the next account to link this session (its chat list picks up the old
   * account's pin, mute and archive flags), and nothing else says why.
   */
  private async clearStoredAccountState(): Promise<void> {
    const { messageStore, chatStateStore, dbSessionId, sessionId } = this.host.config;
    const warn =
      (what: string) =>
      (err: unknown): void =>
        this.host.logger.warn(`Failed to clear the stored ${what} of an unlinked account`, {
          sessionId,
          error: err instanceof Error ? err.message : String(err),
        });
    await messageStore?.clearSession(dbSessionId).catch(warn('messages'));
    await chatStateStore?.clearSession(sessionId).catch(warn('chat states'));
  }

  /**
   * Delete this session's on-disk multi-file auth state (`authDir/sessionId`). Required after a terminal
   * logout: Baileys would otherwise reload the now-invalid creds on the next connect() and retry them
   * instead of emitting a fresh QR, leaving re-linking stuck. `force` makes a missing dir a no-op.
   * Logs the outcome and RETHROWS on failure: completion of an engine-native unlink (logout 200) AND
   * the loggedOut close path both require cleanup, so a removal failure must propagate (the operation
   * is incomplete), not be swallowed.
   */
  private async clearAuthState(): Promise<void> {
    try {
      await fs.promises.rm(this.host.authPath, { recursive: true, force: true });
      this.host.logger.log('Cleared Baileys auth state', { authPath: this.host.authPath });
    } catch (err) {
      this.host.logger.warn('Failed to clear Baileys auth state', {
        error: err instanceof Error ? err.message : String(err),
      });
      throw err;
    }
  }

  destroy(): Promise<void> {
    this.teardown.abort();
    if (this.reconnectTimer) {
      clearTimeout(this.reconnectTimer);
      this.reconnectTimer = undefined;
    }
    clearTimeout(this.connectingTimer);
    this.cancelAddressbookRestore();
    void this.sock?.end(undefined);
    this.sock = null;
    this.closeFetchDispatcher();
    this.dropConnectionState();
    this.setStatus(EngineStatus.DISCONNECTED);
    return Promise.resolve();
  }

  // Baileys has no separate Chromium process to SIGKILL (destroy() already ends the socket
  // synchronously), so a force-destroy is just a destroy.
  forceDestroy(): Promise<void> {
    return this.destroy();
  }

  getStatus(): EngineStatus {
    return this.status;
  }

  /**
   * Cheap local liveness check for the session watchdog. Genuine dead-connection detection is owned
   * by Baileys' built-in keepalive, which surfaces a close event (408) within ~35 s of a silent
   * drop — and the close handler above then drops the status to INITIALIZING for the whole reconnect
   * backoff, so READY + a live socket is sufficient here. Note the status trails the dead transport:
   * Baileys emits that close only after `await ws.close()` resolves, which on a black-holed socket
   * waits out ws's 30 s close timeout, so this reports live for that window too. Acceptable for the
   * watchdog, whose next interval catches it; NOT sufficient for a request guard, which is why
   * requestPairingCode below also tests `ws.isOpen`.
   */
  // eslint-disable-next-line @typescript-eslint/require-await
  async probeLiveness(): Promise<boolean> {
    return this.status === EngineStatus.READY && this.sock != null;
  }

  getQRCode(): string | null {
    return this.qrCode;
  }

  /**
   * Gated on QR_READY AND a live WebSocket, not on the socket merely existing: `this.sock` is assigned the
   * moment makeWASocket returns, before the WebSocket is open, and Baileys' sendNode throws a raw Boom 428
   * until it is. QR_READY is set from the post-handshake `connection.update { qr }` event, so it opens the
   * window; it does not close it promptly, which is why the status alone is not enough. Baileys emits its
   * `connection.update { connection: 'close' }` only after `await ws.close()` resolves, and `ws` leaves a
   * black-holed socket in CLOSING for its 30 s close timeout, so the status keeps reading QR_READY for up to
   * half a minute after the connection stopped carrying anything. `ws.isOpen` is the same predicate Baileys'
   * own sendRawMessage tests and the same liveness check handleQrCode makes before publishing. It matters
   * beyond the status code here: requestPairingCode writes `creds.me` and emits `creds.update`, which we
   * persist, BEFORE it sends, so a request in that window leaves the next connect trying to log in as a
   * device that was never registered. The whatsapp-web.js engine needs no equivalent operand: its page and
   * browser death listeners fire handlePuppeteerDeath, which drops the status in the same tick, so there
   * the status is not the stale value it is here.
   */
  async requestPairingCode(phoneNumber: string): Promise<string> {
    if (!this.sock?.ws.isOpen || this.status !== EngineStatus.QR_READY) {
      throw new EngineNotReadyError('Session is not waiting to be linked. Start it and wait for the QR stage.');
    }
    return this.sock.requestPairingCode(phoneNumber);
  }

  getPhoneNumber(): string | null {
    return this.phoneNumber;
  }

  getPushName(): string | null {
    return this.pushName;
  }

  ensureReady(): void {
    if (this.status !== EngineStatus.READY || !this.sock) {
      throw new EngineNotReadyError();
    }
  }

  private setStatus(status: EngineStatus): void {
    if (this.status === status) {
      return;
    }
    // The cached QR belongs to the socket that produced it, so it dies with the QR_READY window.
    // Enforced in the funnel rather than at each exit: every close sub-branch (intentional, 401, 440,
    // 403, transient), the accepted link and every teardown route through here, and the exits that
    // did not clear it by hand kept serving a dead QR over GET /qr for the whole reconnect backoff.
    // Safe after the no-op guard above: a non-null qrCode implies QR_READY, so an unchanged status
    // that is not QR_READY already has a null cache.
    if (status !== EngineStatus.QR_READY) {
      this.qrCode = null;
    }
    this.status = status;
    this.host.getOnStateChanged()?.(status);
  }
}