Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

20.7 KB
Raw Blame
/**
 * Installing, updating, rolling back and uninstalling plugins on disk.
 *
 * Every install is atomic: the package is downloaded and unpacked in
 * `.staging/`, checked (checksum, archive safety, manifest, compatibility,
 * native file checksums), and only then moved into place with a rename.
 * Anything that fails leaves the previous state untouched and the staging
 * folder removed. The previous version is kept for rollback.
 */
import { createHash, randomBytes } from 'node:crypto';
import { execFile } from 'node:child_process';
import { chmodSync, cpSync, createReadStream, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
import { homedir } from 'node:os';
import { basename, dirname, join, relative, resolve, sep } from 'node:path';
import { promisify } from 'node:util';
import { guardedFetch } from '../utils/ssrf.js';
import { logger } from '../utils/logger.js';
import {
  incompatibility, pluginDir, pluginVersionDir, readState, stagingRoot, withLock, writeState, currentPlatform,
} from './store.js';
import { manifestSchema, PLUGIN_ID_RE, type CatalogEntry, type PluginManifest, type PluginStateEntry } from './types.js';

const execFileAsync = promisify(execFile);

/** Hard limits that keep a hostile or broken package from filling the disk. */
export const LIMITS = {
  downloadBytes: 200 * 1024 * 1024,
  unpackedBytes: 400 * 1024 * 1024,
  files: 5000,
  downloadTimeoutMs: 5 * 60 * 1000,
};

export interface InstallOptions {
  /** Catalog entry when installing by id (gives the pinned checksum). */
  catalogEntry?: CatalogEntry;
  /** Expected SHA-256 of the archive for URL installs. */
  sha256?: string;
  /** Allow a different plugin id than expected (never for catalog installs). */
  expectId?: string;
  /** Reinstall even if this exact version is already installed. */
  force?: boolean;
  onProgress?: (message: string) => void;
}

export interface InstallResult {
  id: string;
  version: string;
  previousVersion?: string;
  verified: boolean;
  manifest: PluginManifest;
  /** True when it was already installed at this version and nothing changed. */
  unchanged: boolean;
}

export type InstallSource =
  | { type: 'catalog'; entry: CatalogEntry }
  | { type: 'path'; path: string }
  | { type: 'url'; url: string }
  | { type: 'github'; repo: string; tag?: string };

/** Turn what the owner typed into a source. Catalog ids are resolved by the caller. */
export function parseSource(input: string): { kind: 'id'; id: string } | InstallSource {
  const s = input.trim();
  if (/^https:\/\//i.test(s)) return { type: 'url', url: s };
  if (/^http:\/\//i.test(s)) throw new Error('Plugin downloads must use HTTPS.');
  const gh = /^(?:github:|https?:\/\/github\.com\/)?([A-Za-z0-9-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?(?:@([\w.-]+))?$/.exec(s);
  if (s.startsWith('github:') && gh) return { type: 'github', repo: gh[1], tag: gh[2] };
  const looksLikePath = s.startsWith('.') || s.startsWith('/') || s.startsWith('~') || /^[a-zA-Z]:[\\/]/.test(s) || s.includes(sep) || /\.(tgz|tar\.gz)$/i.test(s);
  if (looksLikePath) return { type: 'path', path: expandHome(s) };
  if (PLUGIN_ID_RE.test(s)) return { kind: 'id', id: s };
  if (gh) return { type: 'github', repo: gh[1], tag: gh[2] };
  throw new Error(`Don't know how to install "${input}". Use a plugin id, a folder or .tgz path, an https:// URL, or github:owner/repo.`);
}

function expandHome(p: string): string {
  return p === '~' || p.startsWith('~/') ? join(homedir(), p.slice(1)) : resolve(p);
}

// ── download ──────────────────────────────────────────────────────────────

async function download(url: string, dest: string, onProgress?: (m: string) => void): Promise<string> {
  const ac = new AbortController();
  const timer = setTimeout(() => ac.abort(), LIMITS.downloadTimeoutMs);
  try {
    const res = await guardedFetch(url, ac.signal, { 'user-agent': 'mercury-plugin-installer', accept: 'application/octet-stream,*/*' });
    if (!res.ok || !res.body) throw new Error(`Download failed: HTTP ${res.status} from ${new URL(url).host}`);
    const declared = Number(res.headers.get('content-length') ?? 0);
    if (declared > LIMITS.downloadBytes) throw new Error(`Package is too large (${Math.round(declared / 1048576)} MB, limit ${LIMITS.downloadBytes / 1048576} MB).`);
    const hash = createHash('sha256');
    const chunks: Buffer[] = [];
    let total = 0;
    let lastReport = 0;
    const reader = res.body.getReader();
    for (;;) {
      const { done, value } = await reader.read();
      if (done) break;
      total += value.byteLength;
      if (total > LIMITS.downloadBytes) {
        ac.abort();
        throw new Error(`Package is too large (over ${LIMITS.downloadBytes / 1048576} MB).`);
      }
      hash.update(value);
      chunks.push(Buffer.from(value));
      if (onProgress && total - lastReport > 2 * 1048576) {
        lastReport = total;
        onProgress(`Downloaded ${(total / 1048576).toFixed(1)} MB`);
      }
    }
    writeFileSync(dest, Buffer.concat(chunks));
    return hash.digest('hex');
  } finally {
    clearTimeout(timer);
  }
}

export async function sha256File(path: string): Promise<string> {
  const hash = createHash('sha256');
  await new Promise<void>((res, rej) => {
    createReadStream(path).on('data', (c) => hash.update(c)).on('end', () => res()).on('error', rej);
  });
  return hash.digest('hex');
}

async function githubReleaseAsset(repo: string, tag?: string): Promise<string> {
  const api = `https://api.github.com/repos/${repo}/releases/${tag ? `tags/${encodeURIComponent(tag)}` : 'latest'}`;
  const ac = new AbortController();
  const timer = setTimeout(() => ac.abort(), 20_000);
  try {
    const res = await guardedFetch(api, ac.signal, { accept: 'application/vnd.github+json', 'user-agent': 'mercury-plugin-installer' });
    if (!res.ok) throw new Error(`GitHub release not found for ${repo}${tag ? `@${tag}` : ''} (HTTP ${res.status}).`);
    const rel = (await res.json()) as { assets?: { name: string; browser_download_url: string }[] };
    const assets = rel.assets ?? [];
    const platform = currentPlatform();
    const pick = assets.find((a) => a.name === `mercury-plugin-${platform}.tgz`) ?? assets.find((a) => a.name === 'mercury-plugin.tgz');
    if (!pick) throw new Error(`The ${repo} release has no "mercury-plugin.tgz" or "mercury-plugin-${platform}.tgz" asset.`);
    return pick.browser_download_url;
  } finally {
    clearTimeout(timer);
  }
}

// ── unpack and check ────────────────────────────────────────────────────

async function extractTgz(archive: string, into: string): Promise<void> {
  mkdirSync(into, { recursive: true });
  // System tar (bsdtar on macOS/Windows, GNU tar on Linux): both refuse
  // absolute paths and ".." members by default. We re-check every entry below.
  try {
    // Run from the archive's folder and pass only its name: GNU tar (e.g. Git
    // for Windows' tar on PATH) reads "C:\\…" as a remote host "C".
    await execFileAsync('tar', ['-xzf', basename(archive), '-C', into], { cwd: dirname(archive), timeout: 120_000, windowsHide: true, maxBuffer: 1024 * 1024 });
  } catch (err) {
    throw new Error(`Couldn't unpack the plugin archive: ${(err as Error).message.split('\n')[0]}`);
  }
}

/**
 * Walk the unpacked tree and reject anything unsafe: symlinks, hard-linked
 * or special files, paths escaping the folder, and size/file-count bombs.
 */
export function checkTree(root: string): { files: number; bytes: number } {
  const realRoot = realpathSync(root);
  let files = 0;
  let bytes = 0;
  const walk = (dir: string) => {
    for (const name of readdirSync(dir)) {
      const full = join(dir, name);
      const st = lstatSync(full);
      if (st.isSymbolicLink()) throw new Error(`Plugin package contains a symbolic link (${relative(root, full)}); refusing to install.`);
      if (!st.isDirectory() && !st.isFile()) throw new Error(`Plugin package contains a special file (${relative(root, full)}).`);
      const real = realpathSync(full);
      if (real !== realRoot && !real.startsWith(realRoot + sep)) throw new Error(`Plugin package path escapes its folder (${relative(root, full)}).`);
      if (st.isDirectory()) {
        walk(full);
        continue;
      }
      if (st.nlink > 1) throw new Error(`Plugin package contains a hard link (${relative(root, full)}).`);
      files += 1;
      bytes += st.size;
      if (files > LIMITS.files) throw new Error(`Plugin package has too many files (limit ${LIMITS.files}).`);
      if (bytes > LIMITS.unpackedBytes) throw new Error(`Plugin package is too large unpacked (limit ${LIMITS.unpackedBytes / 1048576} MB).`);
    }
  };
  walk(root);
  return { files, bytes };
}

/** npm-pack style archives put everything under one folder; find the manifest. */
function findPackageRoot(unpacked: string): string {
  if (existsSync(join(unpacked, 'mercury-plugin.json'))) return unpacked;
  const entries = readdirSync(unpacked).filter((n) => !n.startsWith('.'));
  if (entries.length === 1 && lstatSync(join(unpacked, entries[0])).isDirectory() && existsSync(join(unpacked, entries[0], 'mercury-plugin.json'))) {
    return join(unpacked, entries[0]);
  }
  throw new Error('No mercury-plugin.json found at the top of the plugin package.');
}

/** Parse and validate a manifest, with readable errors. */
export function loadManifest(dir: string): PluginManifest {
  const path = join(dir, 'mercury-plugin.json');
  let raw: unknown;
  try {
    raw = JSON.parse(readFileSync(path, 'utf8'));
  } catch (err) {
    throw new Error(`mercury-plugin.json is not valid JSON: ${(err as Error).message}`);
  }
  const parsed = manifestSchema.safeParse(raw);
  if (!parsed.success) {
    const first = parsed.error.issues.slice(0, 4).map((i) => `${i.path.join('.') || 'manifest'}: ${i.message}`).join('; ');
    throw new Error(`Invalid mercury-plugin.json: ${first}`);
  }
  return parsed.data;
}

/** Everything that must hold before a package can be installed or started. */
export async function verifyPackage(dir: string, manifest: PluginManifest): Promise<void> {
  const why = incompatibility(manifest);
  if (why) throw new Error(`${manifest.name} ${manifest.version} can't run here: ${why}.`);
  const inside = (p: string) => {
    const full = resolve(dir, p);
    if (full !== dir && !full.startsWith(dir + sep)) throw new Error(`Manifest path escapes the plugin folder: ${p}`);
    return full;
  };
  if (manifest.kind === 'in-process') {
    const entry = inside(manifest.entry!);
    if (!existsSync(entry) || !statSync(entry).isFile()) throw new Error(`Entry module "${manifest.entry}" is missing from the package.`);
    if (!/\.(m?js)$/.test(entry)) throw new Error('The entry module must be a bundled .js or .mjs file.');
  } else {
    const spec = manifest.server!.platforms?.[currentPlatform()] ?? manifest.server!;
    if (spec.command !== 'node') {
      const cmd = inside(spec.command);
      if (!existsSync(cmd)) throw new Error(`Server program "${spec.command}" is missing for ${currentPlatform()}.`);
      if (process.platform !== 'win32') chmodSync(cmd, 0o755);
    } else if (spec.args[0]) {
      const script = inside(spec.args[0]);
      if (!existsSync(script)) throw new Error(`Server script "${spec.args[0]}" is missing from the package.`);
    }
  }
  for (const [rel, expected] of Object.entries(manifest.checksums ?? {})) {
    const file = inside(rel);
    if (!existsSync(file)) throw new Error(`File "${rel}" listed in checksums is missing.`);
    const actual = await sha256File(file);
    if (actual !== expected) throw new Error(`Checksum mismatch for ${rel}: the file was modified or corrupted.`);
  }
}

// ── install ────────────────────────────────────────────────────────────

function newStaging(): string {
  const dir = join(stagingRoot(), `${Date.now()}-${randomBytes(4).toString('hex')}`);
  mkdirSync(dir, { recursive: true });
  return dir;
}

/** Remove leftovers from interrupted installs. Safe to call any time. */
export function cleanStaging(): void {
  try { rmSync(stagingRoot(), { recursive: true, force: true }); } catch { /* best effort */ }
}

export async function installPackage(source: InstallSource, opts: InstallOptions = {}): Promise<InstallResult> {
  return withLock(async () => {
    const progress = opts.onProgress ?? (() => {});
    const staging = newStaging();
    try {
      let unpacked: string;
      let verified = false;
      let sourceRef: PluginStateEntry['source'];

      if (source.type === 'path') {
        if (!existsSync(source.path)) throw new Error(`No such file or folder: ${source.path}`);
        sourceRef = { type: 'path', ref: source.path };
        if (statSync(source.path).isDirectory()) {
          progress('Copying plugin folder');
          unpacked = join(staging, 'pkg');
          cpSync(source.path, unpacked, {
            recursive: true,
            verbatimSymlinks: true,
            // Skip VCS metadata; keep node_modules (out-of-process plugins may ship dependencies).
            filter: (src) => {
              const rel = relative(source.path, src);
              return rel === '' || !/(^|[\\/])\.git([\\/]|$)/.test(rel);
            },
          });
        } else {
          progress('Unpacking archive');
          unpacked = join(staging, 'pkg');
          await extractTgz(source.path, unpacked);
        }
      } else {
        let url: string;
        let expected: string | undefined;
        if (source.type === 'catalog') {
          const art = source.entry.artifacts?.[currentPlatform()] ?? source.entry.artifact;
          if (!art) throw new Error(`${source.entry.name} has no build for ${currentPlatform()}.`);
          url = art.url;
          expected = art.sha256;
          sourceRef = { type: 'catalog', ref: source.entry.id };
        } else if (source.type === 'github') {
          progress(`Looking up the ${source.repo} release`);
          url = await githubReleaseAsset(source.repo, source.tag);
          expected = opts.sha256;
          sourceRef = { type: 'github', ref: `${source.repo}${source.tag ? `@${source.tag}` : ''}` };
        } else {
          url = source.url;
          expected = opts.sha256;
          sourceRef = { type: 'url', ref: source.url };
        }
        progress(`Downloading from ${new URL(url).host}`);
        const archive = join(staging, 'package.tgz');
        const actual = await download(url, archive, progress);
        if (expected) {
          if (actual !== expected.toLowerCase()) throw new Error('Checksum mismatch: the download does not match the published SHA-256. Nothing was installed.');
          verified = source.type === 'catalog';
        }
        progress('Unpacking');
        unpacked = join(staging, 'pkg');
        await extractTgz(archive, unpacked);
      }

      progress('Checking the package');
      checkTree(unpacked);
      const root = findPackageRoot(unpacked);
      const manifest = loadManifest(root);
      if (source.type === 'catalog') {
        if (manifest.id !== source.entry.id) throw new Error(`Package id "${manifest.id}" doesn't match the catalog entry "${source.entry.id}".`);
        if (manifest.version !== source.entry.version) throw new Error(`Package version ${manifest.version} doesn't match the catalog (${source.entry.version}).`);
      }
      if (opts.expectId && manifest.id !== opts.expectId) throw new Error(`This package is "${manifest.id}", not "${opts.expectId}".`);
      await verifyPackage(root, manifest);

      const state = readState();
      const existing = state.plugins[manifest.id];
      if (existing && existing.version === manifest.version && !opts.force && existsSync(pluginVersionDir(manifest.id, manifest.version))) {
        return { id: manifest.id, version: manifest.version, verified: existing.verified, manifest, unchanged: true };
      }

      progress('Installing');
      const versionsDir = join(pluginDir(manifest.id), 'versions');
      mkdirSync(versionsDir, { recursive: true });
      mkdirSync(join(pluginDir(manifest.id), 'data'), { recursive: true });
      const target = pluginVersionDir(manifest.id, manifest.version);
      let trash: string | null = null;
      if (existsSync(target)) {
        trash = join(staging, 'replaced');
        renameSync(target, trash);
      }
      try {
        renameSync(root, target);
      } catch (err) {
        if (trash) renameSync(trash, target);
        throw err;
      }

      const now = new Date().toISOString();
      const previousVersion = existing && existing.version !== manifest.version ? existing.version : existing?.previousVersion;
      state.plugins[manifest.id] = {
        version: manifest.version,
        previousVersion,
        // A fresh install starts disabled; updates keep the owner's choice.
        enabled: existing?.enabled ?? false,
        kind: manifest.kind,
        source: sourceRef,
        verified,
        installedAt: existing?.installedAt ?? now,
        updatedAt: now,
        // Any disable reason from the old version doesn't carry over, except the owner's.
        disabled: existing?.disabled?.code === 'user' ? existing.disabled : undefined,
      };
      if (state.plugins[manifest.id].enabled) state.boot.lastChange = { id: manifest.id, at: now };
      writeState(state);
      pruneVersions(manifest.id, [manifest.version, previousVersion].filter(Boolean) as string[]);
      logger.info({ plugin: manifest.id, version: manifest.version, previousVersion, verified, source: sourceRef.type }, 'Plugin installed');
      return { id: manifest.id, version: manifest.version, previousVersion, verified, manifest, unchanged: false };
    } finally {
      try { rmSync(staging, { recursive: true, force: true }); } catch { /* best effort */ }
    }
  });
}

/** Keep only the listed versions on disk (current and one previous). */
function pruneVersions(id: string, keep: string[]): void {
  const dir = join(pluginDir(id), 'versions');
  if (!existsSync(dir)) return;
  for (const v of readdirSync(dir)) {
    if (!keep.includes(v)) {
      try { rmSync(join(dir, v), { recursive: true, force: true }); } catch (err) { logger.warn({ err, plugin: id, version: v }, 'Could not prune old plugin version'); }
    }
  }
}

/** Switch back to the previous version, if it's still on disk. */
export async function rollbackPackage(id: string): Promise<{ from: string; to: string }> {
  return withLock(async () => {
    const state = readState();
    const entry = state.plugins[id];
    if (!entry) throw new Error(`Plugin "${id}" is not installed.`);
    const prev = entry.previousVersion;
    if (!prev || !existsSync(pluginVersionDir(id, prev))) throw new Error(`No previous version of "${id}" to roll back to.`);
    const manifest = loadManifest(pluginVersionDir(id, prev));
    await verifyPackage(pluginVersionDir(id, prev), manifest);
    const from = entry.version;
    entry.version = prev;
    entry.previousVersion = from;
    entry.kind = manifest.kind;
    entry.updatedAt = new Date().toISOString();
    if (entry.disabled && entry.disabled.code !== 'user') entry.disabled = undefined;
    if (entry.enabled) state.boot.lastChange = { id, at: entry.updatedAt };
    writeState(state);
    return { from, to: prev };
  });
}

/** Remove a plugin. Its data and settings are kept unless `purge` is set. */
export async function uninstallPackage(id: string, purge = false): Promise<{ removedData: boolean }> {
  return withLock(async () => {
    const state = readState();
    const had = !!state.plugins[id];
    delete state.plugins[id];
    if (state.boot.lastChange?.id === id) state.boot.lastChange = undefined;
    writeState(state);
    const dir = pluginDir(id);
    if (purge) {
      if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
    } else if (existsSync(join(dir, 'versions'))) {
      rmSync(join(dir, 'versions'), { recursive: true, force: true });
    }
    if (!had && !existsSync(dir)) throw new Error(`Plugin "${id}" is not installed.`);
    logger.info({ plugin: id, purge }, 'Plugin uninstalled');
    return { removedData: purge };
  });
}

/** The manifest of the installed (current) version, or null if missing or broken. */
export function installedManifest(id: string, version: string): PluginManifest | null {
  try {
    return loadManifest(pluginVersionDir(id, version));
  } catch {
    return null;
  }
}

export function packageSize(id: string, version: string): number {
  let bytes = 0;
  const walk = (d: string) => {
    for (const n of readdirSync(d)) {
      const f = join(d, n);
      const st = lstatSync(f);
      if (st.isDirectory()) walk(f);
      else bytes += st.size;
    }
  };
  try { walk(pluginVersionDir(id, version)); } catch { /* missing */ }
  return bytes;
}