Skip to content

A modern, self-hosted backup solution for secure, encrypted backups across local and cloud storage.

16.0 KB
Raw Blame
/**
 * `pluton --restore-pluton <blob>`: restore Pluton's config and history from a self-backup
 * blob, against a stopped server. A short-lived CLI process, not a flow inside the server.
 *
 * Steps 1-5 are read-only. A wrong key, corrupt blob, foreign edition, newer version, or a
 * running server all fail before the data dir is touched.
 */

import fs from 'fs';
import fsp from 'fs/promises';
import os from 'os';
import path from 'path';
import type { Database as SqliteDatabase } from 'better-sqlite3';
import { appPaths } from './AppPaths';
import { prompt } from './cliPrompt';
import { openBlob, BlobDecryptError } from './selfBackup/blobFormat';
import { unpackPayload, PayloadManifest, PlutonEdition } from './selfBackup/payload';
import { getDrizzleJournalTag } from './migrations';
import {
	writeEncryptionKeyToEnvFile,
	isLinuxInstalledRuntime,
	getEncEnvFilePath,
} from './envFileHelpers';
import { isDockerMode } from './installHelpers';
import { configService } from '../services/ConfigService';

export interface RestoreArgs {
	blobPath: string | null;
	force: boolean;
}

export interface RestoreDeps {
	/** The live handle this process opened, injected so we close the right one (see below). */
	sqlite: SqliteDatabase;
	dbFilePath: string;
	edition: PlutonEdition;
}

export function parseRestoreArgs(argv: string[]): RestoreArgs {
	const flagIndex = argv.indexOf('--restore-pluton');
	const next = flagIndex === -1 ? undefined : argv[flagIndex + 1];
	const blobPath = next && !next.startsWith('--') ? next : null;
	return { blobPath, force: argv.includes('--force') };
}

/** Any response on /api/health means a live Pluton. A negative is namespace-scoped (see guard). */
export async function isServerRunning(port: number): Promise<boolean> {
	try {
		await fetch(`http://127.0.0.1:${port}/api/health`, {
			signal: AbortSignal.timeout(2000),
		});
		return true;
	} catch {
		return false;
	}
}

export type GuardVerdict = { allowed: true; warning?: string } | { allowed: false; reason: string };

/**
 * A probe response is authoritative; silence is not. Under Docker the restore container has its
 * own network namespace, so the probe stays silent even when the server is live on the same
 * volume -- undetectable, so refuse unless --force.
 */
export function evaluateInstanceGuard(opts: {
	serverResponding: boolean;
	isDocker: boolean;
	force: boolean;
	port: number;
}): GuardVerdict {
	if (opts.serverResponding) {
		if (!opts.force) {
			return {
				allowed: false,
				reason:
					`Pluton is still running on port ${opts.port}. Stop the Pluton service before restoring, ` +
					'then run this command again.\n' +
					'   (If the port is held by something else, re-run with --force.)',
			};
		}
		return {
			allowed: true,
			warning: `A server is responding on port ${opts.port}, but --force was given. Continuing.`,
		};
	}

	if (opts.isDocker) {
		if (!opts.force) {
			return {
				allowed: false,
				reason:
					'Running inside a container, Pluton cannot tell whether your Pluton container is still up:\n' +
					'   this restore container has its own network namespace, so the health check here proves nothing.\n' +
					'   Restoring while Pluton is running will corrupt the database.\n\n' +
					'   Stop it first:\n' +
					'     docker compose down\n\n' +
					'   Then re-run this command with --force to confirm it is stopped.',
			};
		}
		return {
			allowed: true,
			warning:
				'Could not verify that Pluton is stopped (running inside a container). ' +
				'Proceeding because --force was given.',
		};
	}

	return { allowed: true };
}

export interface SkewCheckResult {
	ok: boolean;
	reason?: string;
}

/** Refuse a newer blob into older Pluton (no down migrations). Caller MUST check edition first. */
export function checkVersionSkew(
	manifest: Pick<PayloadManifest, 'plutonVersion' | 'drizzleJournalTag'>,
	local: { plutonVersion: string; drizzleJournalTag: string | null }
): SkewCheckResult {
	const cmp = compareSemver(manifest.plutonVersion, local.plutonVersion);
	if (cmp > 0) {
		return {
			ok: false,
			reason:
				`This blob was written by Pluton ${manifest.plutonVersion}, but this install is ${local.plutonVersion}. ` +
				'Restoring a newer backup into an older Pluton is not supported (there are no down migrations). ' +
				'Upgrade Pluton to at least the blob version, then restore again.',
		};
	}

	if (
		manifest.drizzleJournalTag &&
		local.drizzleJournalTag &&
		compareJournalTag(manifest.drizzleJournalTag, local.drizzleJournalTag) > 0
	) {
		return {
			ok: false,
			reason:
				`This blob's database schema (${manifest.drizzleJournalTag}) is newer than this install's (${local.drizzleJournalTag}). ` +
				'Restoring it would leave the database ahead of the code. Upgrade Pluton, then restore again.',
		};
	}

	return { ok: true };
}

export function checkEdition(
	manifestEdition: string | undefined,
	localEdition: PlutonEdition
): SkewCheckResult {
	if (!manifestEdition) {
		return {
			ok: false,
			reason:
				'This blob does not record which Pluton edition produced it, so it cannot be safely restored.',
		};
	}
	if (manifestEdition !== localEdition) {
		return {
			ok: false,
			reason:
				`This blob is from the "${manifestEdition}" edition of Pluton, but this install is "${localEdition}". ` +
				'Cross-edition restore is not supported. Version and schema numbering differ between editions.',
		};
	}
	return { ok: true };
}

/** Numeric-segment compare; non-numeric suffixes are ignored. Returns -1 / 0 / 1. */
function compareSemver(a: string, b: string): number {
	const parse = (v: string) =>
		v
			.replace(/^v/, '')
			.split(/[.\-+]/)
			.map(part => parseInt(part, 10))
			.filter(n => !Number.isNaN(n));

	const left = parse(a);
	const right = parse(b);
	// An unparseable version ('unknown', a dev build) can't be ordered, so don't block on it.
	if (left.length === 0 || right.length === 0) return 0;

	for (let i = 0; i < Math.max(left.length, right.length); i++) {
		const l = left[i] ?? 0;
		const r = right[i] ?? 0;
		if (l !== r) return l > r ? 1 : -1;
	}
	return 0;
}

/** Drizzle tags are `NNNN_name`; the numeric prefix is the ordering. */
function compareJournalTag(a: string, b: string): number {
	const idx = (tag: string) => parseInt(tag.split('_')[0], 10);
	const left = idx(a);
	const right = idx(b);
	if (Number.isNaN(left) || Number.isNaN(right)) return 0;
	if (left === right) return 0;
	return left > right ? 1 : -1;
}

// Scratch holds the decrypted payload (keys.json included); process.exit() skips finally, so
// every exit path cleans up through here.
let scratchToClean: string | null = null;

function cleanScratch(): void {
	if (!scratchToClean) return;
	try {
		fs.rmSync(scratchToClean, { recursive: true, force: true });
	} catch {
		// best effort
	}
	scratchToClean = null;
}

/** Per-install next steps: env-injected key/password override what we restored, except on desktop. */
export function buildCompletionMessage(env: {
	isDocker: boolean;
	isLinuxInstalled: boolean;
}): string {
	const done = '\n✅ Restore complete.\n';

	if (env.isDocker) {
		return (
			done +
			'\n   REQUIRED: open the .env next to your docker-compose.yml and set\n' +
			'\n     ENCRYPTION_KEY=<the same key you just entered>\n' +
			'\n   The key is deliberately NOT stored in the data volume, so compose is the only\n' +
			'   place Pluton can get it. Without it the container will refuse to start.\n' +
			'   If it is set but does not match the backup, Pluton starts and every restored plan\n' +
			'   points at a repository it can no longer read, so check it now.\n' +
			'\n   While you are in that file, USER_NAME and USER_PASSWORD are your login: they\n' +
			'   override the restored account, so set them to what you want to log in with.\n' +
			'\n   Then: docker compose up -d\n' +
			'   Log in with the USER_NAME / USER_PASSWORD from that .env, not your old password.\n'
		);
	}

	if (env.isLinuxInstalled) {
		return (
			done +
			'\n   The encryption key from your backup was written to /etc/pluton/pluton.enc.env,\n' +
			'   which the service reads on start. Nothing more to do for the key.\n' +
			'\n   Then: sudo systemctl start pluton\n' +
			'   Log in with the PLUTON_USER_NAME / PLUTON_USER_PASSWORD in /etc/pluton/pluton.env.\n' +
			'   Those override the restored account, so they are your credentials now, not the old ones.\n'
		);
	}

	return done + '\n   Start the Pluton service and log in with your old password.\n';
}

/**
 * Desktop/Server: write pluton.enc.env so the key takes effect. Docker: write nothing and delete
 * any copy -- compose owns the key, and a leftover OLDER key would silently boot against the
 * wrong key instead of failing loudly. Safe to delete: the caller just decrypted with it.
 */
export async function applyEncryptionKey(opts: {
	dataDir: string;
	key: string;
	isDocker: boolean;
}): Promise<void> {
	if (opts.isDocker) {
		await fsp.rm(getEncEnvFilePath(opts.dataDir), { force: true });
		return;
	}
	writeEncryptionKeyToEnvFile(opts.dataDir, opts.key);
}

function fail(message: string): never {
	cleanScratch();
	console.error(`❌ ${message}`);
	process.exit(1);
}

function succeed(message: string): never {
	cleanScratch();
	console.log(message);
	process.exit(0);
}

async function copyTree(srcDir: string, destDir: string): Promise<void> {
	await fsp.cp(srcDir, destDir, { recursive: true, force: true });
}

/** Transient errno codes Windows raises for a momentarily-held file (AV, indexer, memory-map). */
const TRANSIENT_FS_CODES = new Set(['EBUSY', 'EPERM', 'EACCES', 'ENOTEMPTY', 'EMFILE', 'ENFILE']);

/**
 * Close the DB handle and clear pluton.db + its WAL sidecars. On Windows a naive close()-unlink
 * races the -shm teardown and AV/indexer scans and hits EBUSY, so: switch out of WAL before
 * closing (deletes -wal/-shm with the handle still held), retry the unlink, then rename aside
 * for a clean slot. Throws only if all three fail; the caller aborts before copying.
 */
export async function releaseDatabaseFiles(
	sqlite: SqliteDatabase,
	dbFilePath: string
): Promise<void> {
	// A downstream edition injects its own handle, but core's db/index.ts also loads here, leaving
	// a SECOND open handle that would make the unlink fail. Close it too. Lazy import keeps the
	// pure pieces off the db graph; the guard avoids double-closing when it already IS the injected one.
	try {
		const coreDb = await import('../db');
		if (coreDb.sqlite !== sqlite && coreDb.sqlite.open) {
			coreDb.sqlite.close();
		}
	} catch {
		// core's db may not be loaded here, or already closed
	}

	try {
		sqlite.pragma('journal_mode = DELETE'); // deletes -wal/-shm before we drop the handle
	} catch {
		// switch failed; still close and lean on the retry/rename below
	}
	sqlite.close();

	const rmOpts = { force: true, maxRetries: 10, retryDelay: 200 } as const;

	for (const suffix of ['-wal', '-shm']) {
		await fsp.rm(`${dbFilePath}${suffix}`, rmOpts);
	}

	try {
		await fsp.rm(dbFilePath, rmOpts);
		return;
	} catch (error: any) {
		if (!TRANSIENT_FS_CODES.has(error?.code)) throw error;
	}

	// Still locked: rename aside. An inert DB with no sidecars is ignored by SQLite.
	const aside = `${dbFilePath}.restore-old-${process.pid}`;
	await fsp.rename(dbFilePath, aside);
	fsp.rm(aside, rmOpts).catch(() => {});
}

/** `deps.sqlite` is injected, not imported, so releaseDatabaseFiles closes the right handle. */
export async function handleSelfRestore(deps: RestoreDeps): Promise<never> {
	console.log('\n🛟  Pluton Restore\n');

	// Show the target while still read-only. A service sets PLUTON_DATA_DIR but the operator's
	// shell often doesn't inherit it, and then the path falls back to the default.
	const dataDir = appPaths.getDataDir();
	console.log(`Restoring into data directory: ${dataDir}`);
	const isRealInstall = Boolean((process as any).pkg) || process.env.NODE_ENV === 'production';
	if (isRealInstall && !isDockerMode() && !process.env.PLUTON_DATA_DIR) {
		console.warn(
			'⚠️  PLUTON_DATA_DIR is not set in this shell, so the path above is the default location.\n' +
				'   If this Pluton runs as a service with a custom data directory, stop the service and set\n' +
				'   PLUTON_DATA_DIR to match it before restoring, or you will restore into the wrong place.\n'
		);
	}

	// ---- 1. Parse
	const { blobPath, force } = parseRestoreArgs(process.argv);
	if (!blobPath) {
		fail('Usage: pluton --restore-pluton <path-to-blob> [--force]');
	}
	if (!fs.existsSync(blobPath)) {
		fail(`No such file: ${blobPath}`);
	}

	// ---- 2. Running-instance guard
	const port = configService.config.SERVER_PORT || 5173;
	const verdict = evaluateInstanceGuard({
		serverResponding: await isServerRunning(port),
		isDocker: isDockerMode(),
		force,
		port,
	});
	if (!verdict.allowed) {
		fail(verdict.reason);
	}
	if (verdict.warning) {
		console.warn(`⚠️  ${verdict.warning}`);
	}

	// ---- 3. Key
	const key = await obtainEncryptionKey();

	// ---- 4. Decrypt (wrong key fails here, before anything is touched)
	console.log('Decrypting blob...');
	let tar: Buffer;
	try {
		tar = openBlob(await fsp.readFile(blobPath), key);
	} catch (error: any) {
		if (error instanceof BlobDecryptError) {
			fail(`${error.message}\n   Nothing has been modified.`);
		}
		throw error;
	}

	// ---- 5. Unpack to scratch, then guard edition before version
	const scratchDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'pluton-restore-'));
	scratchToClean = scratchDir;
	try {
		const manifest = await unpackPayload(tar, scratchDir);

		const editionCheck = checkEdition(manifest.edition, deps.edition);
		if (!editionCheck.ok) {
			fail(`${editionCheck.reason}\n   Nothing has been modified.`);
		}

		const skewCheck = checkVersionSkew(manifest, {
			plutonVersion: process.env.APP_VERSION || 'unknown',
			drizzleJournalTag: getDrizzleJournalTag(),
		});
		if (!skewCheck.ok) {
			fail(`${skewCheck.reason}\n   Nothing has been modified.`);
		}

		console.log(
			`Blob looks good. Written ${manifest.createdAt} on host "${manifest.hostname}" ` +
				`by Pluton ${manifest.plutonVersion} (${manifest.edition}).`
		);

		// ================= past this line we mutate =================

		// ---- 6/7. Close the DB and clear pluton.db + its WAL sidecars (Windows-safe; see helper)
		console.log('Applying restore...');
		try {
			await releaseDatabaseFiles(deps.sqlite, deps.dbFilePath);
		} catch (error: any) {
			// Nothing copied yet, so the data dir is intact -- safe to abort.
			fail(
				`Could not replace the database file (${error?.code || error?.message || error}).\n` +
					`   Something still holds ${deps.dbFilePath} open. On Windows this is almost always\n` +
					'   antivirus or the Search indexer scanning it, or a Pluton process that did not fully\n' +
					'   stop. Confirm no "pluton" process is running (Task Manager, or `Get-Process pluton`),\n' +
					'   then run this command again. Your existing data has not been modified.'
			);
		}

		// ---- 8. Unpack over the data dir
		await copyTree(scratchDir, appPaths.getDataDir());
		await fsp.rm(path.join(appPaths.getDataDir(), 'manifest.json'), { force: true });

		// ---- 9. Get the key where this install reads it from (nowhere, on Docker)
		await applyEncryptionKey({
			dataDir: appPaths.getDataDir(),
			key,
			isDocker: isDockerMode(),
		});

		// ---- 10. Mark setup complete so the wizard doesn't reappear
		await fsp.writeFile(path.join(appPaths.getDataDir(), '.setup_complete'), '');

		succeed(
			buildCompletionMessage({
				isDocker: isDockerMode(),
				isLinuxInstalled: isLinuxInstalledRuntime(),
			})
		);
	} catch (error) {
		// An unexpected throw (not a fail()) still must not leave the decrypted payload behind.
		cleanScratch();
		throw error;
	}
}

/** No --encryption-key flag (argv leaks to ps/history); use PLUTON_ENCRYPTION_KEY or the prompt. */
async function obtainEncryptionKey(): Promise<string> {
	const fromEnv = process.env.PLUTON_ENCRYPTION_KEY || process.env.ENCRYPTION_KEY;
	if (fromEnv) {
		console.log('Using encryption key from the environment.');
		return fromEnv;
	}

	if (!process.stdin.isTTY) {
		fail(
			'An encryption key is required. Run this in an interactive terminal, ' +
				'or set PLUTON_ENCRYPTION_KEY.'
		);
	}

	const key = await prompt('Enter your Pluton encryption key: ', true);
	if (!key) {
		fail('Encryption key cannot be empty.');
	}
	return key;
}