Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

13.3 KB
Raw Blame
import * as fs from 'fs';
import * as path from 'path';
import { Injectable, OnModuleInit } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { IWhatsAppEngine } from './interfaces/whatsapp-engine.interface';
import { PluginLoaderService, PluginType, IEnginePlugin, PluginManifest } from '../core/plugins';
import { WhatsAppWebJsPlugin } from './builtin/whatsapp-web-js';
import { BaileysPlugin } from './builtin/baileys';
import { createLogger } from '../common/services/logger.service';
import { BaileysMessageStoreService } from './adapters/baileys-message-store.service';
import { LidMappingStoreService } from './identity/lid-mapping-store.service';
import { ChatStateStoreService } from './adapters/baileys-chat-state-store.service';
import { isSafeSessionName } from '../common/utils/path-safety';
import { ensurePrivateDir } from '../common/utils/private-dir.util';
import { baileysAuthDir, readAuthDirEntries, wwjsAuthDir } from './auth-dir-paths';

export interface EngineCreateOptions {
  /**
   * Session UUID (Session.id): the on-disk auth-directory key (matches the dirs purgeSessionData
   * removes), and what the adapters stamp on their per-session rows and logs. Carries the same value
   * as `dbSessionId`; both stay in the per-call config because an out-of-tree engine plugin reads
   * them by name.
   */
  sessionId: string;
  /** Session UUID (Session.id) — the DB-row key for FK-bound stores (e.g. baileys_stored_messages). */
  dbSessionId: string;
  proxyUrl?: string;
  proxyType?: 'http' | 'https' | 'socks4' | 'socks5';
}

@Injectable()
export class EngineFactory implements OnModuleInit {
  private readonly logger = createLogger('EngineFactory');
  private readonly engineType: string;

  constructor(
    private readonly configService: ConfigService,
    private readonly pluginLoader: PluginLoaderService,
    private readonly baileysMessageStore: BaileysMessageStoreService,
    private readonly lidMappingStore: LidMappingStoreService,
    private readonly chatStateStore: ChatStateStoreService,
  ) {
    this.engineType = this.configService.get<string>('engine.type') ?? 'whatsapp-web.js';
  }

  async onModuleInit(): Promise<void> {
    // Register built-in engine plugins
    await this.registerBuiltInEngines();
  }

  private async registerBuiltInEngines(): Promise<void> {
    // The engine config sub-tree (engine.* from configuration.ts) as an opaque blob. Supplied BOTH
    // to registerBuiltInPlugin (becomes context.config when onLoad runs) AND to each plugin's
    // constructor (A fallback so createEngine still has operator config if enablePlugin fails
    // before onLoad — otherwise sessionDataPath/executablePath/authDir would silently drop to defaults).
    const engineConfig = this.configService.get<Record<string, unknown>>('engine') ?? {};

    // Register WhatsApp-web.js as built-in plugin
    const wwjsManifest: PluginManifest = {
      id: 'whatsapp-web.js',
      name: 'WhatsApp Web.js Engine',
      version: '1.0.0',
      type: PluginType.ENGINE,
      description: 'Official WhatsApp-web.js engine adapter',
      main: 'index.ts',
      provides: ['whatsapp-engine'],
    };

    const wwjsPlugin = new WhatsAppWebJsPlugin(engineConfig, this.lidMappingStore);
    this.pluginLoader.registerBuiltInPlugin(wwjsManifest, wwjsPlugin, engineConfig);

    // Register Baileys as a second built-in engine plugin. Same opaque engine blob; the plugin
    // reads only its own namespace (baileys.authDir) from context.config.
    const baileysManifest: PluginManifest = {
      id: 'baileys',
      name: 'Baileys Engine',
      version: '1.0.0',
      type: PluginType.ENGINE,
      description: 'Baileys (WebSocket, no-browser) engine adapter',
      main: 'index.ts',
      provides: ['whatsapp-engine'],
    };
    this.pluginLoader.registerBuiltInPlugin(
      baileysManifest,
      new BaileysPlugin(this.baileysMessageStore, engineConfig, this.lidMappingStore, this.chatStateStore),
      engineConfig,
    );

    // Auto-enable the configured engine
    try {
      await this.pluginLoader.enablePlugin(this.engineType);
      this.logger.log(`Engine plugin enabled: ${this.engineType}`, {
        action: 'engine_enabled',
        engineType: this.engineType,
      });
    } catch (error) {
      this.logger.error(
        `Failed to enable engine plugin: ${this.engineType}`,
        error instanceof Error ? error.message : String(error),
        { action: 'engine_enable_failed' },
      );
    }
  }

  create(options: EngineCreateOptions): IWhatsAppEngine {
    // The sessionId becomes the engine's on-disk auth-directory key (path.join(authDir, sessionId) /
    // session-${sessionId}), so a value containing '.', '/' or '\\' could traverse outside it. It is a
    // Session.id (a UUID) on every in-tree path, but a restored/imported row carries whatever its
    // archive held — assert here so the traversal can never materialize regardless of source.
    if (!isSafeSessionName(options.sessionId)) {
      throw new Error(`Refusing to create an engine for an unsafe session key: ${JSON.stringify(options.sessionId)}`);
    }

    // Both engine shapes' credential dirs are made owner-only up front, whichever engine this
    // session runs: a whatsapp-web.js profile and a baileys creds.json each hold everything needed
    // to take over the linked account, so read access to the data volume must not be enough.
    // Mirrors purgeSessionData, which removes BOTH shapes for the same engine-switch-residue reason.
    ensurePrivateDir(this.wwjsAuthDir(options.sessionId));
    ensurePrivateDir(this.baileysAuthDir(options.sessionId));

    // Try to get engine from plugin system
    const enginePlugin = this.pluginLoader.getPlugin(this.engineType);

    if (enginePlugin?.instance && this.isEnginePlugin(enginePlugin.instance)) {
      // Engine-neutral per-call config, plus the two auth-dir bases. Engine-specific config (e.g.
      // Puppeteer for whatsapp-web.js) is supplied to the plugin as an opaque blob via context.config
      // at registration, so the factory never assembles browser-shaped fields. The bases are the
      // exception: this factory hardens and purges the credential dirs under them, and the boot
      // migration renames into them, so the engine must write there too. context.config can carry a
      // persisted plugin-config override that none of those would follow.
      return enginePlugin.instance.createEngine({
        sessionId: options.sessionId,
        dbSessionId: options.dbSessionId,
        proxyUrl: options.proxyUrl,
        proxyType: options.proxyType,
        sessionDataPath: this.sessionDataPath(),
        authDir: this.baileysAuthBase(),
      }) as IWhatsAppEngine;
    }

    // Both built-ins are registered with an instance in onModuleInit and ENGINE_TYPE is whitelisted at
    // boot, so this is reached only by a broken host. Never build some other engine in its place.
    throw new Error(`Engine '${this.engineType}' is not registered; cannot start the session.`);
  }

  /**
   * Remove a session's persistent on-disk auth/store directories so deleting a session fully purges
   * its footprint. The dir is keyed by session ID — the same key {@link create} uses
   * (`path.join(authDir, id)` for baileys, `session-${id}` under sessionDataPath for
   * whatsapp-web.js) — and survives independently of any engine instance. On delete the engine is
   * frequently not even loaded (a stopped session has none), so the paths are derived from config
   * here rather than from a live adapter; otherwise the residue would sit on the volume forever.
   *
   * BOTH engine shapes are purged, not just the active engine's: ENGINE_TYPE is a deploy-level
   * switch, so a session that ever ran under both engines leaves a live auth dir for each, and
   * removing only the active engine's would strand the other's WhatsApp credentials on disk after
   * "delete" — able to silently re-link if the engine is ever switched back (and carried into
   * backups). Each rm is isolated best-effort: an unsafe key is refused up front, and one engine's
   * rm failure is logged per-engine — it neither fails the delete nor skips the other engine's purge.
   *
   * Note: session START deliberately does NOT purge the inactive engine's residue. An operator
   * trialling the other engine keeps the previous engine's link so switching back doesn't force a
   * re-pair; the residue is removed only when the session itself is deleted.
   *
   * `legacyName` is the row's name, passed by delete. SessionAuthDirMigration leaves the legacy
   * name-keyed directory in place whenever it could not rename it (an open profile on Windows, or an
   * id-keyed directory already there), so purging only the id-keyed dirs would strand a complete
   * WhatsApp login on the volume and in every backup taken after the delete. It is removed only when
   * the base directory really holds an entry with that exact name; see readAuthDirEntries.
   *
   * The session's lid mappings are kept (the table is shared) but handed to no session, so a phone
   * this session stored can still be cleared by the session that replaces it (see LidMappingStoreService).
   */
  async purgeSessionData(sessionId: string, legacyName?: string): Promise<void> {
    if (!isSafeSessionName(sessionId)) {
      // Same guard as create(): never let a key with '.', '/' or '\\' reach an rm -rf sink.
      this.logger.warn('Refusing to purge session data for an unsafe session key', {
        action: 'engine_purge_unsafe',
        key: JSON.stringify(sessionId),
      });
      return;
    }
    await this.lidMappingStore.releaseSession(sessionId);
    const dirs: Array<{ engine: string; dir: string }> = [
      { engine: 'whatsapp-web.js', dir: this.wwjsAuthDir(sessionId) },
      { engine: 'baileys', dir: this.baileysAuthDir(sessionId) },
    ];
    // The caller withholds a name that is another session's id: the dirs it points at are then that
    // session's live id-keyed credentials, and only the caller can see the table.
    if (legacyName !== undefined && isSafeSessionName(legacyName)) {
      const legacyDirs = [
        { engine: 'whatsapp-web.js', dir: this.wwjsAuthDir(legacyName) },
        { engine: 'baileys', dir: this.baileysAuthDir(legacyName) },
      ];
      dirs.push(...legacyDirs.filter(({ dir }) => this.authDirExists(dir)));
    }
    for (const { engine, dir } of dirs) {
      try {
        await fs.promises.rm(dir, { recursive: true, force: true });
        this.logger.log('Purged session auth directory', { action: 'engine_purge', engine, sessionId, dir });
      } catch (error) {
        this.logger.warn('Failed to purge session auth directory', {
          action: 'engine_purge_failed',
          engine,
          sessionId,
          dir,
          error: error instanceof Error ? error.message : String(error),
        });
      }
    }
  }

  /** The whatsapp-web.js sessionDataPath from config. */
  private sessionDataPath(): string {
    return this.configService.get<string>('engine.sessionDataPath') ?? './data/sessions';
  }

  /** The baileys authDir from config. */
  private baileysAuthBase(): string {
    return this.configService.get<string>('engine.baileys.authDir') ?? './data/baileys';
  }

  /** The whatsapp-web.js LocalAuth profile dir for `sessionId`, with sessionDataPath from config. */
  private wwjsAuthDir(sessionId: string): string {
    return wwjsAuthDir(this.sessionDataPath(), sessionId);
  }

  /** The baileys multi-file auth dir for `sessionId`, with authDir from config. */
  private baileysAuthDir(sessionId: string): string {
    return baileysAuthDir(this.baileysAuthBase(), sessionId);
  }

  /** True when `dir`'s base directory holds an entry with exactly that name (see readAuthDirEntries). */
  private authDirExists(dir: string): boolean {
    try {
      return readAuthDirEntries(path.dirname(dir)).has(path.basename(dir));
    } catch {
      return false; // base directory missing or unreadable: nothing of this shape to purge
    }
  }

  private isEnginePlugin(instance: unknown): instance is IEnginePlugin {
    return (
      typeof instance === 'object' &&
      instance !== null &&
      'type' in instance &&
      instance.type === PluginType.ENGINE &&
      'createEngine' in instance &&
      typeof (instance as { createEngine: unknown }).createEngine === 'function'
    );
  }

  // ============================================================================
  // Query Methods for API/Dashboard
  // ============================================================================

  getAvailableEngines(): Array<{
    id: string;
    name: string;
    enabled: boolean;
    features: string[];
    library?: { name: string; version: string };
  }> {
    const enginePlugins = this.pluginLoader.getPluginsByType(PluginType.ENGINE);

    return enginePlugins.map(plugin => {
      const inst = plugin.instance;
      const features = inst && this.isEnginePlugin(inst) ? inst.getFeatures() : [];
      // The real underlying library version (e.g. whatsapp-web.js 1.34.7), distinct from the
      // plugin's manifest version — so the dashboard can show which engine is actually running.
      const library = inst && this.isEnginePlugin(inst) ? inst.getEngineLibrary?.() : undefined;

      return {
        id: plugin.manifest.id,
        name: plugin.manifest.name,
        enabled: this.pluginLoader.isPluginEnabled(plugin.manifest.id),
        features,
        library,
      };
    });
  }

  getCurrentEngine(): string {
    return this.engineType;
  }
}