Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

6.7 KB
Raw Blame
import * as fs from 'fs';
import { type Client } from 'whatsapp-web.js';
import { type EngineEventCallbacks, EngineStatus } from '../interfaces/whatsapp-engine.interface';
import { type createLogger } from '../../common/services/logger.service';
import { type WhatsAppWebJsConfig } from './whatsapp-web-js.adapter';
import { wwjsAuthDir } from '../auth-dir-paths';

/**
 * Stuck-auth detection and recovery extracted from WhatsAppWebJsAdapter: what to do when a session
 * authenticated but never reached runtime readiness, and the LocalAuth-profile removal both that
 * recovery and a WhatsApp-initiated unlink go through. The adapter keeps the methods as thin
 * forwarders and injects the host surface via closures, so the delegate never touches lifecycle
 * state directly.
 */
export interface WwebjsStuckAuthHost {
  readonly logger: ReturnType<typeof createLogger>;
  readonly config: WhatsAppWebJsConfig;
  getClient(): Client | null;
  setClient(client: Client | null): void;
  setStatus(status: EngineStatus): void;
  /** Live callbacks bag — read per event, since initialize() installs it after delegates are built. */
  getCallbacks(): EngineEventCallbacks;
}

/** The Puppeteer Browser whatsapp-web.js keeps on the client; `process()` is null once Chromium is gone. */
type BrowserHandle = { pupBrowser?: { process?: () => { kill?: (sig: string) => void } | null } };

export class WwebjsStuckAuth {
  // Guards the stuck-auth self-heal so it runs at most once per engine: a re-paired session that still
  // can't reach readiness fails terminally instead of looping QR -> timeout -> clear forever.
  private recoveryAttempted = false;

  constructor(private readonly host: WwebjsStuckAuthHost) {}

  /**
   * Recover a session that authenticated but never reached runtime readiness (stale/incompatible auth
   * or a wedged page). Clear the broken LocalAuth and disconnect so the session lifecycle re-pairs (a
   * fresh QR) instead of hanging at "authenticating". Runs at most ONCE per reconnect episode: the
   * one-shot budget lives on the session (via the synchronous `claimStuckAuthRecovery` callback), so
   * an automatic reconnect that builds a fresh adapter cannot reset it and wipe LocalAuth every
   * generation. A re-paired session that still can't reach readiness fails terminally rather than looping.
   *
   * When the callback is ABSENT (standalone adapter use/test, no session lifecycle) the adapter falls
   * back to its own instance-local boolean so standalone behavior stays one-shot.
   */
  async recoverFromStuckAuth(): Promise<void> {
    // The one-shot budget is decided SYNCHRONOUSLY before any destructive I/O. The session-owned
    // callback is authoritative when present; the instance-local boolean is the standalone fallback.
    // Fail-closed: a callback that throws (or already-spent budget) makes this terminal WITHOUT
    // touching the auth dir, so a wedged claim path can never wipe the only copy of the credentials.
    const claim = this.host.getCallbacks().claimStuckAuthRecovery;
    let granted: boolean;
    if (claim) {
      try {
        granted = claim();
      } catch {
        granted = false;
      }
    } else {
      granted = !this.recoveryAttempted;
      this.recoveryAttempted = true;
    }
    if (!granted) {
      this.host.setStatus(EngineStatus.FAILED);
      this.host
        .getCallbacks()
        .onError?.(
          'WhatsApp Web could not reach readiness after re-pairing. Pin WWEBJS_WEB_VERSION to a known-good build and try again.',
        );
      return;
    }

    const client = this.host.getClient();
    this.host.setClient(null);
    // Kill the wedged Chromium before removing its profile: a live browser keeps writing into the
    // directory being removed, which can exhaust the rm retries and leave half a profile behind.
    try {
      const browser = (client as unknown as BrowserHandle | null)?.pupBrowser;
      browser?.process?.()?.kill?.('SIGKILL');
    } catch (err) {
      this.host.logger.warn('Could not kill the browser before clearing the saved session', {
        sessionId: this.host.config.sessionId,
        error: String(err),
      });
    }
    // Clear auth + disconnect (the recovery path), then finish the client teardown in the background
    // so a hung destroy can't block (or skip) the recovery. The removal is registered with the
    // credential-teardown fence before it is awaited, as the logout path does: a stop and start
    // arriving meanwhile would otherwise launch a new Chromium into the directory being deleted.
    const removal = this.clearLocalAuth();
    this.host.getCallbacks().onCredentialTeardownStarted?.(removal);
    await removal;
    this.host.setStatus(EngineStatus.DISCONNECTED);
    // onDisconnected drives the lifecycle's reconnect, which re-creates the engine with no saved auth
    // → a fresh QR. (A no-op once the engine is superseded/torn down.)
    this.host.getCallbacks().onDisconnected?.('Saved session could not be restored; cleared for re-pairing');
    if (typeof client?.destroy === 'function') void client.destroy().catch(() => undefined);
  }

  /** Remove this session's LocalAuth directory so the next start re-pairs from a clean slate. */
  async clearLocalAuth(): Promise<void> {
    const dir = wwjsAuthDir(this.host.config.sessionDataPath, this.host.config.sessionId);
    await fs.promises
      // maxRetries mirrors LocalAuth's own default: on a WhatsApp-initiated unlink the library never
      // closes the browser, so Chromium is still rotating IndexedDB files while this walks the tree and
      // a bare rm reports ENOTEMPTY (#1072). Node's default is 0 retries, which is why the failure
      // surfaced here and never on the library's removal of the same directory.
      .rm(dir, { recursive: true, force: true, maxRetries: 4 })
      .then(() => {
        // #981: this is the only copy of the session's WhatsApp credentials, and removing it is not
        // recoverable — every later start finds an empty profile and can do nothing but show a QR. Say
        // so at the moment it happens: otherwise the sole trace is a session that silently stops
        // reconnecting, indistinguishable from a WhatsApp-side logout or an untouched profile.
        this.host.logger.warn(
          `Deleted this session's stored WhatsApp credentials at ${dir}. That was the only copy, so the ` +
            'next start cannot restore the link and comes back with a fresh QR to scan.',
          { sessionId: this.host.config.sessionId, dir, action: 'auth_cleared' },
        );
      })
      .catch((error: unknown) => {
        this.host.logger.warn(`Could not clear stale auth at ${dir}`, {
          sessionId: this.host.config.sessionId,
          dir,
          error: String(error),
        });
      });
  }
}