Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

11.9 KB
Raw Blame
import "server-only";
import { promises as fs } from "node:fs";
import os from "node:os";
import path from "node:path";
import { BACKUP_SKIPPED_DIRS, backupsRoot, createBackup, isManagedAppBackupId, readBackupManifest, stateDirFor } from "./backups";
import { getManagedAppDefinition } from "./catalog";
import { getManagedApp, assertManagedAppStopped } from "./manager";
import type { ManagedAppDefinition, ManagedAppId } from "./types";
import type { ManagedAppRestoreResult } from "./update-types";

// The only code in the subsystem that writes into an app's own directory, and
// the reason every other file refuses to. Six gates, in this order, before a
// single byte moves:
//
//   1. the app must not be RUNNING,
//   2. the backup id must match the minted stamp pattern (it is a path segment),
//   3. its manifest must name THIS application,
//   4. the manifest's recorded source must be exactly this app's state dir now,
//   5. the state dir must be a real directory, not a symlink, and not $HOME or
//      an ancestor of it,
//   6. no file in the snapshot may land on a symlink in the state dir — checked
//      by walking both trees BEFORE the first byte moves, because a refusal
//      raised mid-copy leaves the directory half-rolled-back.
//
// It OVERWRITES; it never deletes. A snapshot has no node_modules/.venv/.git
// (backups.ts prunes them), so a rename-aside-and-replace restore would strip a
// Hermes checkout of its own git metadata and dependencies and leave a broken
// install. Files created since the snapshot are therefore left in place, and
// the result says so — "rolled back" here means "these files are back as they
// were", not "the directory is as it was".

/** Refusing beats stopping it. A live app holds SQLite WALs and lock files
 *  (`state.db-wal`, `gateway.lock`, `kanban.db`) and would flush its in-memory
 *  state back over whatever we restored; and an MSO that stopped the app itself
 *  would then own the question of restarting it, including when the restore
 *  fails halfway. The operator has a Stop button — this is one click, not a
 *  wizard. */
const RESTORE_BLOCKING_STATES = new Set(["running", "starting", "unhealthy"]);

/** What both installs already use: `stat -c %a ~/.hermes ~/.openclaw` → 700. A
 *  re-created state dir must not be the one thing in the tree that is world
 *  readable. */
const STATE_DIR_MODE = 0o700;

const message = (error: unknown): string => (error instanceof Error ? error.message : String(error));

async function assertStopped(id: ManagedAppId): Promise<void> {
  const view = await getManagedApp(id);
  // This gate decides whether it is safe to overwrite the app's state directory,
  // so it must fail CLOSED. "not-installed" is not in the blocking set below —
  // correctly, because restoring into an absent app is the case this feature
  // exists for — but that answer is only safe when it is a FACT. When MSO cannot
  // reach the user bus it cannot see user services at all, and an app that is
  // running right now reads exactly like one that was never installed. Restoring
  // then would copy a snapshot over the live state of a running application.
  if (view.diagnostic) throw new Error(`cannot confirm ${view.name} is stopped — refusing to restore. ${view.diagnostic}`);
  if (RESTORE_BLOCKING_STATES.has(view.state)) throw new Error(`${view.name} is ${view.state}; stop it before restoring a backup`);
  await assertManagedAppStopped(id);
}

/** The state dir is GONE — the normal case for the restore that matters most:
 *  `openclaw uninstall --service --state` removes ~/.openclaw outright, and the
 *  pre-uninstall snapshot MSO forces before it is the operator's only way back.
 *  Refusing here made that snapshot unrestorable exactly when it was needed.
 *
 *  Creating it is safe because of GATE 4, not because of anything here: the path
 *  is `stateDirFor(definition)` — catalog plus env, never anything from the
 *  request — and gate 4 has already required the manifest's recorded source to
 *  be that same path. The only directory this can bring into existence is the
 *  app's own.
 *
 *  Deliberately not `mkdir -p`: a missing PARENT is not "the app was
 *  uninstalled", it is a mis-set HERMES_HOME or a volume that did not mount,
 *  and materialising a tree there would drop the restore somewhere the app will
 *  never look while reporting success. */
async function createStateDir(target: string): Promise<void> {
  const parent = path.dirname(target);
  // stat, not lstat: a symlinked $HOME is a legitimate setup, and the realpath
  // + home containment checks below still run on whatever this resolves to.
  if (!(await fs.stat(parent).catch(() => null))?.isDirectory()) {
    throw new Error(`the application state directory is missing and so is its parent (${parent}); nothing was restored`);
  }
  await fs.mkdir(target, { mode: STATE_DIR_MODE });
}

/** Gate 5. The manifest already proved WHICH directory this snapshot belongs
 *  to; this proves the directory is still a plain directory of this app's and
 *  not a link pointed somewhere else since. */
async function resolveTarget(definition: ManagedAppDefinition, recordedSource: string): Promise<string> {
  const target = stateDirFor(definition);
  if (!path.isAbsolute(target)) throw new Error("the application state directory is not an absolute path");
  if (!recordedSource || path.resolve(recordedSource) !== path.resolve(target)) {
    throw new Error("this backup was taken from a different directory than the application uses now");
  }
  const link = await fs.lstat(target).catch(() => null);
  if (!link) await createStateDir(target); // uninstalled: see createStateDir
  // A symlinked state dir would make every write below land wherever it points.
  else if (link.isSymbolicLink()) throw new Error("the application state directory is a symlink; refusing to restore through it");
  else if (!link.isDirectory()) throw new Error("the application state directory is not a directory");
  const real = await fs.realpath(target);
  const home = await fs.realpath(os.homedir()).catch(() => os.homedir());
  // Never write to $HOME itself or anything containing it: a mis-set
  // HERMES_HOME must not turn a restore into a home-directory overwrite.
  if (real === path.parse(real).root || real === home || `${home}${path.sep}`.startsWith(`${real}${path.sep}`)) {
    throw new Error("refusing to restore over the home directory");
  }
  return real;
}

/** Gate 2 + 3 + the containment check on the snapshot itself. */
async function resolveSource(id: ManagedAppId, backupId: string): Promise<{ dir: string; source: string }> {
  if (!isManagedAppBackupId(backupId)) throw new Error("unknown backup");
  const manifest = await readBackupManifest(id, backupId);
  if (!manifest) throw new Error("this backup has no manifest and cannot be verified");
  if (manifest.applicationId !== id) throw new Error(`this backup belongs to ${manifest.applicationId}, not ${id}`);
  const root = await fs.realpath(backupsRoot(id));
  const dir = await fs.realpath(path.join(root, backupId));
  // realpath both sides: a snapshot dir replaced by a link to somewhere else
  // must not become the thing we copy from.
  if (path.dirname(dir) !== root) throw new Error("backup is outside the application backup directory");
  if (!(await fs.lstat(dir)).isDirectory()) throw new Error("backup is not a directory");
  return { dir, source: manifest.source };
}

/** Gate 6: walk the snapshot against the state dir and refuse BEFORE anything
 *  is written if any entry would land on a symlink. The `fs.cp` filter below
 *  catches the same collision, but by then `fs.cp` has already copied
 *  everything it walked past — the refusal that was meant to protect the state
 *  dir left it half snapshot and half its old self, and said nothing about it.
 *  Both checks stay: this one makes the common case atomic, the filter is the
 *  last-ditch guard for a link that appears during the copy.
 *
 *  Affordable: ~14k entries on the larger of the two installs (~0.3 s of
 *  lstats) against a `createBackup` that copies 366 MB of it a moment later. */
async function assertNoSymlinkCollisions(dir: string, target: string): Promise<void> {
  const pending = [""];
  while (pending.length) {
    const rel = pending.pop() as string;
    const entries = await fs.readdir(path.join(dir, rel), { withFileTypes: true }).catch(() => []);
    for (const entry of entries) {
      // Skipped by the copy for the same reasons, so neither can collide.
      if (entry.isSymbolicLink()) continue;
      if (!rel && entry.name === "manifest.json") continue;
      const next = path.join(rel, entry.name);
      const existing = await fs.lstat(path.join(target, next)).catch(() => null);
      if (existing?.isSymbolicLink()) throw new Error(`refusing to write through a symlink: ${next} (nothing was written)`);
      if (entry.isDirectory()) pending.push(next);
    }
  }
}

export async function restoreManagedAppBackup(id: ManagedAppId, backupId: string, append: (text: string) => void): Promise<ManagedAppRestoreResult> {
  const definition = getManagedAppDefinition(id);
  await assertStopped(id);
  const { dir, source } = await resolveSource(id, backupId);
  const target = await resolveTarget(definition, source);
  await assertNoSymlinkCollisions(dir, target);
  append(`[mso] restoring ${backupId} into ${target}\n`);

  // The undo. Taken AFTER the gates so a refused restore does not litter, and
  // before the first write so the current state is always recoverable.
  const safety = await createBackup(definition, "pre-restore", () => assertStopped(id));
  append(`[mso] current state saved as ${safety.id} (${safety.files ?? "?"} files) before overwriting\n`);
  await assertStopped(id);

  const manifestFile = path.join(dir, "manifest.json");
  let filesRestored = 0;
  let bytesRestored = 0;
  let checkedAt = 0;
  try {
    await fs.cp(dir, target, {
      recursive: true,
      force: true,
      preserveTimestamps: true,
      filter: async (from, to) => {
        if (Date.now() - checkedAt >= 1000) { await assertStopped(id); checkedAt = Date.now(); }
        if (from === manifestFile) return false; // ours, not the app's
        const entry = await fs.lstat(from);
        // A snapshot contains no symlinks by construction; one that appeared
        // since is not something to copy or follow.
        if (entry.isSymbolicLink()) return false;
        const existing = await fs.lstat(to).catch(() => null);
        // `fs.copyFile` opens the destination with O_CREAT|O_TRUNC, which
        // FOLLOWS a symlink — that is how a restore ends up writing outside the
        // state dir. Gate 6 already refused this before anything moved, so
        // reaching here means the link appeared DURING the copy; refuse the
        // rest of the run rather than write through it.
        if (existing?.isSymbolicLink()) throw new Error(`refusing to write through a symlink: ${path.relative(target, to) || to}`);
        if (entry.isFile()) {
          filesRestored += 1;
          bytesRestored += entry.size;
        }
        return true;
      },
    });
  } catch (error) {
    // `fs.cp` stops where it is, so the state dir now holds part of the
    // snapshot and part of what was there before. The undo id has to be in the
    // MESSAGE, not only in the transcript: a failed job shows one status line,
    // and "refusing to write through a symlink" on its own reads like nothing
    // happened.
    throw new Error(`${message(error)} - the state directory is PARTIALLY restored; undo with backup ${safety.id}`);
  }

  const notRestored = [...BACKUP_SKIPPED_DIRS];
  append(`[mso] restored ${filesRestored} files (${(bytesRestored / 1024 / 1024).toFixed(1)} MB)\n`);
  append(`[mso] NOT restored (never in a snapshot): ${notRestored.join(", ")}\n`);
  append("[mso] files created since the snapshot were left in place - a restore overwrites, it does not delete\n");
  append(`[mso] undo this with backup ${safety.id}\n`);
  return { applicationId: id, backupId, target, filesRestored, bytesRestored, safetyBackupId: safety.id, notRestored, overwriteOnly: true };
}