Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

6.4 KB
Raw Blame
import * as fs from 'fs';
import * as path from 'path';
import { createLogger } from '../../common/services/logger.service';
import { PluginInstance } from './plugin.interfaces';
import { PluginStorageService } from './plugin-storage.service';

/**
 * The uninstall half of the plugin loader: fully remove an installed user plugin — disable + unload
 * from the runtime, delete its directories from disk, then drop its persisted registry entry. Install,
 * download and unpack live feature-side (modules/plugins); this is the runtime-owned removal they and
 * the REST surface call through PluginLoaderService.
 *
 * Split out of PluginLoaderService so the loader reads as the public facade while the removal
 * contract — package-dir provenance, the traversal guard, split-dir storage cleanup — is reviewed on
 * its own. A plain class, not a Nest provider: the loader constructs it in its constructor (the same
 * pattern as PluginSandboxBridge / PluginCapabilityContext), so the loader's public constructor
 * signature — which specs build directly — is unchanged.
 */
export class PluginUninstaller {
  constructor(
    // The LOADER's logger, deliberately — uninstall lines carry the PluginLoaderService tag, and
    // that context is operator-visible. Creating a second logger here would silently retag every
    // uninstall log line the moment this moved.
    private readonly logger: ReturnType<typeof createLogger>,
    // The LOADER's plugin registry, passed BY REFERENCE (see the class doc): reads here see the same
    // map the loader, the scanner and the bridge share.
    private readonly plugins: Map<string, PluginInstance>,
    private readonly pluginStorage: PluginStorageService,
    private readonly pluginsDir: string,
    /** The lifecycle's unload — passed as a callback so this file never imports the lifecycle back. */
    private readonly unload: (pluginId: string) => Promise<void>,
    /** The legacy plugin tree the boot scan also loads from, or null when PLUGINS_DIR is set. */
    private readonly legacyPluginsDir: string | null = null,
    /** Hands the chats the plugin took over back to the bot; the conversation store is not this file's. */
    private readonly releaseTakeovers?: (pluginId: string) => Promise<void>,
  ) {}

  /**
   * Package folders of plugins whose uninstall stopped after the unload dropped their runtime record,
   * until a repeat completes: without it the repeat only has the id to go by, and a package whose folder
   * is not its manifest id would be left on disk to load again on the next boot.
   */
  private readonly unloadedDirs = new Map<string, string>();

  /** <root>/<id> for an id with no loaded package, or null if the id escapes that root. */
  private resolveUninstallDir(root: string, pluginId: string): string | null {
    const base = path.resolve(root);
    const dir = path.resolve(base, pluginId);
    return dir !== base && dir.startsWith(base + path.sep) ? dir : null;
  }

  /**
   * Fully remove an installed user plugin: disable + unload from the runtime, delete its directory from
   * disk, then drop its persisted registry entry (last, so a failed removal can be repeated). Built-ins (engines, bundled extensions) are
   * registered programmatically with no on-disk dir and must never be removable.
   */
  async uninstallPlugin(pluginId: string): Promise<void> {
    if (this.pluginStorage.getPluginEntry(pluginId)?.builtIn) {
      throw new Error(`Cannot uninstall built-in plugin ${pluginId}`);
    }

    // Read the package location BEFORE unloading: unloadPlugin drops the runtime record that holds
    // it, and for a plugin loaded from the legacy directory the configured root is the wrong tree —
    // deleting there removes the ctx.storage directory and leaves the code, so the plugin comes
    // back on the next boot having reported a successful uninstall.
    const recordedDir = this.plugins.get(pluginId)?.packageDir ?? this.unloadedDirs.get(pluginId) ?? null;
    if (recordedDir) this.unloadedDirs.set(pluginId, recordedDir);

    if (this.plugins.has(pluginId)) {
      await this.unload(pluginId);
    }

    // A takeover the plugin held keeps every other plugin silent on that chat, and nothing is left to
    // hand it back once the plugin is gone. Done after the unload, because until its worker ends the
    // plugin can still take a chat over again, and before the registry entry goes: a store that cannot
    // take the release fails the uninstall, and a repeat finds no runtime and goes straight to it.
    await this.releaseTakeovers?.(pluginId);

    // A recorded directory came from the boot scan and is already contained. Without one the id is
    // the only input, so it stays behind the traversal guard against the configured root.
    const dir = recordedDir ?? this.resolveUninstallDir(this.pluginsDir, pluginId);
    if (dir && fs.existsSync(dir)) {
      fs.rmSync(dir, { recursive: true, force: true });
    }
    // The legacy tree can still hold a copy the scan would load again on the next boot (as a new
    // plugin, config lost): the package of a plugin that failed to load (its registry entry survives
    // the boot scan but no runtime record does), or a copy the scan skipped as a duplicate because
    // the same id loaded from the configured tree. When the recorded dir was the legacy copy it is
    // already gone above, and this is a no-op.
    if (this.legacyPluginsDir) {
      const legacyDir = this.resolveUninstallDir(this.legacyPluginsDir, pluginId);
      if (legacyDir && fs.existsSync(path.join(legacyDir, 'manifest.json'))) {
        fs.rmSync(legacyDir, { recursive: true, force: true });
      }
    }

    // Drop the plugin's ctx.storage data dir. Under shipped defaults it lives INSIDE the package
    // dir (already gone above), but a split-dir deployment (PLUGINS_DIR outside the data dir) would
    // otherwise leak <dataDir>/plugins/<id> — persisted secrets included — on every uninstall.
    // Strictly that one plugin's directory.
    this.pluginStorage.deletePluginData(pluginId);

    // Last, so a removal that failed above leaves the entry in place: the service answers a repeat only
    // for an id it still knows, and without the entry a half-removed package would load again on the
    // next boot as a new plugin with no way left to uninstall it.
    this.pluginStorage.deletePluginEntry(pluginId);

    this.unloadedDirs.delete(pluginId);
    this.logger.log(`Plugin uninstalled: ${pluginId}`, { pluginId, action: 'plugin_uninstalled' });
  }
}