A modern, self-hosted backup solution for secure, encrypted backups across local and cloud storage.
import fs from 'fs';
import os from 'os';
import path from 'path';
// cliSelfRestore imports payload -> AppPaths (an import-time singleton that mkdirSync's
// ~12 dirs) and ConfigService. Both are mocked so the pure pieces can be tested in isolation.
const mockDataDir = path.join(__dirname, '__unused__');
// writeEncryptionKeyToEnvFile applies a Windows ACL via icacls; keep it out of tests.
jest.mock('child_process', () => ({ execSync: jest.fn() }));
jest.mock('../../src/utils/AppPaths', () => ({
appPaths: {
getDataDir: () => mockDataDir,
getConfigDir: () => path.join(mockDataDir, 'config'),
getDbDir: () => path.join(mockDataDir, 'db'),
getProgressDir: () => path.join(mockDataDir, 'progress'),
getSyncDir: () => path.join(mockDataDir, 'sync'),
getSchedulesPath: () => path.join(mockDataDir, 'schedules.json'),
getTempDir: () => path.join(mockDataDir, 'temp'),
},
}));
jest.mock('../../src/services/ConfigService', () => ({
configService: { config: { SERVER_PORT: 5173 } },
}));
import Database from 'better-sqlite3';
import {
parseRestoreArgs,
checkVersionSkew,
checkEdition,
isServerRunning,
evaluateInstanceGuard,
buildCompletionMessage,
applyEncryptionKey,
releaseDatabaseFiles,
} from '../../src/utils/cliSelfRestore';
const local = { plutonVersion: '1.4.0', drizzleJournalTag: '0042_stable_tag' };
describe('parseRestoreArgs', () => {
it('reads the blob path that follows the flag', () => {
expect(parseRestoreArgs(['node', 'pluton', '--restore-pluton', './b.pluton'])).toEqual({
blobPath: './b.pluton',
force: false,
});
});
it('picks up --force in any position', () => {
expect(parseRestoreArgs(['node', 'pluton', '--force', '--restore-pluton', './b.pluton'])).toEqual(
{ blobPath: './b.pluton', force: true }
);
});
it('returns a null path when the flag has no argument', () => {
expect(parseRestoreArgs(['node', 'pluton', '--restore-pluton'])).toEqual({
blobPath: null,
force: false,
});
});
it('does not swallow a following flag as the blob path', () => {
expect(parseRestoreArgs(['node', 'pluton', '--restore-pluton', '--force'])).toEqual({
blobPath: null,
force: true,
});
});
it('returns a null path when the flag is absent', () => {
expect(parseRestoreArgs(['node', 'pluton']).blobPath).toBeNull();
});
});
describe('evaluateInstanceGuard', () => {
const base = { serverResponding: false, isDocker: false, force: false, port: 5173 };
it('refuses when the server answers the probe', () => {
const v = evaluateInstanceGuard({ ...base, serverResponding: true });
expect(v.allowed).toBe(false);
expect((v as any).reason).toMatch(/still running on port 5173/);
});
it('allows a responding server through --force, but warns', () => {
const v = evaluateInstanceGuard({ ...base, serverResponding: true, force: true });
expect(v.allowed).toBe(true);
expect((v as any).warning).toMatch(/--force/);
});
it('allows a silent probe on a non-docker install, where loopback is trustworthy', () => {
expect(evaluateInstanceGuard(base)).toEqual({ allowed: true });
});
it('refuses a silent probe under docker, where the restore container has its own loopback', () => {
// The motivating bug: without this the guard fails OPEN in exactly the install type
// where it cannot see the server, and the user silently corrupts a live database.
const v = evaluateInstanceGuard({ ...base, isDocker: true });
expect(v.allowed).toBe(false);
expect((v as any).reason).toMatch(/docker compose down/);
});
it('tells the docker user what to do rather than just refusing', () => {
const reason = (evaluateInstanceGuard({ ...base, isDocker: true }) as any).reason;
expect(reason).toMatch(/cannot tell whether/i);
expect(reason).toMatch(/--force/);
});
it('lets a docker user proceed with --force, warning that it could not verify', () => {
const v = evaluateInstanceGuard({ ...base, isDocker: true, force: true });
expect(v.allowed).toBe(true);
expect((v as any).warning).toMatch(/[Cc]ould not verify/);
});
it('prefers the concrete "still running" message when docker DOES answer the probe', () => {
// docker exec / --network=host land in the server's namespace, so the probe works
// and the user deserves the specific message, not the generic docker one.
const v = evaluateInstanceGuard({ ...base, isDocker: true, serverResponding: true });
expect(v.allowed).toBe(false);
expect((v as any).reason).toMatch(/still running on port/);
expect((v as any).reason).not.toMatch(/docker compose down/);
});
});
describe('applyEncryptionKey', () => {
let dataDir: string;
let encEnvPath: string;
const KEY = 'the-key-from-the-blob';
beforeEach(() => {
dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'applykey-'));
encEnvPath = path.join(dataDir, 'pluton.enc.env');
});
afterEach(() => {
fs.rmSync(dataDir, { recursive: true, force: true });
});
it('writes the key on desktop/server, where nothing else supplies it', async () => {
await applyEncryptionKey({ dataDir, key: KEY, isDocker: false });
expect(fs.existsSync(encEnvPath)).toBe(true);
expect(fs.readFileSync(encEnvPath, 'utf-8')).toContain(`ENCRYPTION_KEY=${KEY}`);
});
it('writes NOTHING into the data dir on docker', async () => {
// ENCRYPTION_KEY is RESTIC_PASSWORD for every repo. Compose is the only source of
// truth on docker, so a copy here would just be a plaintext master key at rest.
await applyEncryptionKey({ dataDir, key: KEY, isDocker: true });
expect(fs.existsSync(encEnvPath)).toBe(false);
});
it('removes a pre-existing key file on docker, rather than leaving it', async () => {
fs.writeFileSync(encEnvPath, 'ENCRYPTION_KEY=a-stale-key-from-an-older-restore\n');
await applyEncryptionKey({ dataDir, key: KEY, isDocker: true });
// Left in place, ConfigService would silently prefer it whenever compose passes an
// empty ENCRYPTION_KEY, booting Pluton against the WRONG key. Loud failure is better.
expect(fs.existsSync(encEnvPath)).toBe(false);
});
it('never leaves the key on disk in docker, whatever was there before', async () => {
fs.writeFileSync(encEnvPath, `ENCRYPTION_KEY=${KEY}\n`);
await applyEncryptionKey({ dataDir, key: KEY, isDocker: true });
const leaked = fs
.readdirSync(dataDir)
.filter(f => fs.readFileSync(path.join(dataDir, f), 'utf-8').includes(KEY));
expect(leaked).toEqual([]);
});
it('is a no-op on docker when there is no key file to begin with', async () => {
await expect(applyEncryptionKey({ dataDir, key: KEY, isDocker: true })).resolves.toBeUndefined();
expect(fs.readdirSync(dataDir)).toEqual([]);
});
it('overwrites a stale key file on desktop/server instead of removing it', async () => {
fs.writeFileSync(encEnvPath, 'ENCRYPTION_KEY=an-old-key\n');
await applyEncryptionKey({ dataDir, key: KEY, isDocker: false });
const content = fs.readFileSync(encEnvPath, 'utf-8');
expect(content).toContain(`ENCRYPTION_KEY=${KEY}`);
expect(content).not.toContain('an-old-key');
});
});
describe('buildCompletionMessage', () => {
// Measured: ConfigService only reads pluton.enc.env when ENCRYPTION_KEY is absent from the
// env, and hashPasswordIfNeeded re-hashes USER_PASSWORD over the restored PASSWORD_HASH.
// So the restored key/password only apply where nothing injects env vars.
const docker = { isDocker: true, isLinuxInstalled: false };
const server = { isDocker: false, isLinuxInstalled: true };
const desktop = { isDocker: false, isLinuxInstalled: false };
it('tells docker users to set ENCRYPTION_KEY in their compose .env', () => {
const msg = buildCompletionMessage(docker);
expect(msg).toMatch(/ENCRYPTION_KEY/);
expect(msg).toMatch(/docker-compose\.yml/);
expect(msg).toMatch(/same key you just entered/i);
});
it('presents the docker .env key as required, not advisory', () => {
// There is no longer a key file in the volume to fall back on, so omitting it is
// not a "you probably should" but a "the container will not start".
const msg = buildCompletionMessage(docker);
expect(msg).toMatch(/REQUIRED/);
expect(msg).toMatch(/refuse to start/);
});
it('tells docker users the key is deliberately not in the volume', () => {
expect(buildCompletionMessage(docker)).toMatch(/NOT stored in the data volume/);
});
it('warns docker users what a mismatched key costs them', () => {
expect(buildCompletionMessage(docker)).toMatch(/no longer read/);
});
it('does NOT tell docker users to use their old password', () => {
// It would be wrong: compose's USER_PASSWORD overwrites the restored hash on boot.
const msg = buildCompletionMessage(docker);
expect(msg).toMatch(/not your old password/);
expect(msg).toMatch(/USER_PASSWORD/);
});
it('tells server users the key is already handled, since systemd reads the file we wrote', () => {
const msg = buildCompletionMessage(server);
expect(msg).toMatch(/etc\/pluton\/pluton\.enc\.env/);
expect(msg).toMatch(/Nothing more to do for the key/);
});
it('points server users at pluton.env for credentials, not the old password', () => {
const msg = buildCompletionMessage(server);
expect(msg).toMatch(/etc\/pluton\/pluton\.env/);
expect(msg).toMatch(/not the old ones/);
});
it('gives each install type its own start command', () => {
expect(buildCompletionMessage(docker)).toMatch(/docker compose up -d/);
expect(buildCompletionMessage(server)).toMatch(/systemctl start pluton/);
});
it('only promises the old password on desktop, where no env vars override it', () => {
const msg = buildCompletionMessage(desktop);
expect(msg).toMatch(/log in with your old password/i);
expect(msg).not.toMatch(/docker compose/);
expect(msg).not.toMatch(/systemctl/);
});
it('says restore is complete in every case', () => {
for (const env of [docker, server, desktop]) {
expect(buildCompletionMessage(env)).toMatch(/Restore complete/);
}
});
});
describe('checkEdition', () => {
it('accepts a matching edition', () => {
expect(checkEdition('core', 'core').ok).toBe(true);
});
it('refuses a foreign edition, in both directions', () => {
const fromPro = checkEdition('pro', 'core');
expect(fromPro.ok).toBe(false);
expect(fromPro.reason).toMatch(/different|edition/i);
expect(checkEdition('core', 'pro').ok).toBe(false);
});
it('refuses a blob that does not record its edition', () => {
expect(checkEdition(undefined, 'core').ok).toBe(false);
});
it('says "edition", not "version", since a misleading message sends the user down the wrong path', () => {
const result = checkEdition('pro', 'core');
expect(result.reason).toContain('edition');
expect(result.reason).not.toMatch(/upgrade pluton/i);
});
});
describe('checkVersionSkew', () => {
it('accepts an older blob, because migrations run forward. This is the normal path', () => {
expect(
checkVersionSkew({ plutonVersion: '1.2.0', drizzleJournalTag: '0031_older' }, local).ok
).toBe(true);
});
it('accepts an equal version', () => {
expect(
checkVersionSkew({ plutonVersion: '1.4.0', drizzleJournalTag: '0042_stable_tag' }, local).ok
).toBe(true);
});
it('refuses a newer blob version, because there are no down migrations', () => {
const result = checkVersionSkew({ plutonVersion: '1.5.0', drizzleJournalTag: null }, local);
expect(result.ok).toBe(false);
expect(result.reason).toMatch(/newer/);
});
it('refuses a blob whose schema is ahead even when the version is not', () => {
const result = checkVersionSkew(
{ plutonVersion: '1.4.0', drizzleJournalTag: '0043_newer' },
local
);
expect(result.ok).toBe(false);
expect(result.reason).toMatch(/schema/);
});
it('compares version segments numerically, not lexically', () => {
// '1.10.0' < '1.9.0' as strings; it must not be treated as older.
expect(
checkVersionSkew({ plutonVersion: '1.10.0', drizzleJournalTag: null }, local).ok
).toBe(false);
expect(
checkVersionSkew(
{ plutonVersion: '1.9.0', drizzleJournalTag: null },
{ plutonVersion: '1.10.0', drizzleJournalTag: null }
).ok
).toBe(true);
});
it('does not block on an unparseable version (dev builds report "unknown")', () => {
expect(checkVersionSkew({ plutonVersion: 'unknown', drizzleJournalTag: null }, local).ok).toBe(
true
);
expect(
checkVersionSkew(
{ plutonVersion: '9.9.9', drizzleJournalTag: null },
{ plutonVersion: 'unknown', drizzleJournalTag: null }
).ok
).toBe(true);
});
it('does not compare journal tags when either side is missing one', () => {
expect(
checkVersionSkew({ plutonVersion: '1.0.0', drizzleJournalTag: '0099_x' }, {
plutonVersion: '1.4.0',
drizzleJournalTag: null,
}).ok
).toBe(true);
});
});
describe('isServerRunning', () => {
const realFetch = global.fetch;
afterEach(() => {
global.fetch = realFetch;
});
it('reports running on any HTTP response, since deleting the DB under a live server is corruption', async () => {
global.fetch = jest.fn().mockResolvedValue({ ok: true, status: 200 }) as any;
expect(await isServerRunning(5173)).toBe(true);
});
it('reports running even on a non-200, since something is still holding the port', async () => {
global.fetch = jest.fn().mockResolvedValue({ ok: false, status: 503 }) as any;
expect(await isServerRunning(5173)).toBe(true);
});
it('reports not running on ECONNREFUSED', async () => {
global.fetch = jest.fn().mockRejectedValue(new Error('ECONNREFUSED')) as any;
expect(await isServerRunning(5173)).toBe(false);
});
it('probes the unauthenticated health endpoint on loopback', async () => {
const fetchMock = jest.fn().mockResolvedValue({ ok: true, status: 200 });
global.fetch = fetchMock as any;
await isServerRunning(9999);
expect(fetchMock).toHaveBeenCalledWith(
'http://127.0.0.1:9999/api/health',
expect.objectContaining({ signal: expect.anything() })
);
});
});
// The automated form of the design doc's "sqlite.close() on Windows" spike (§9): open a REAL
// WAL database with a real handle, then assert releaseDatabaseFiles closes it and clears the
// file plus both sidecars, rather than racing close() against unlink.
describe('releaseDatabaseFiles', () => {
let tmp: string;
let dbPath: string;
beforeEach(() => {
tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'pluton-dbrelease-'));
dbPath = path.join(tmp, 'pluton.db');
});
afterEach(() => {
fs.rmSync(tmp, { recursive: true, force: true });
});
// Open a WAL db and force a -wal (and -shm) into existence with an uncheckpointed write.
const openWalDbWithSidecars = () => {
const sqlite = new Database(dbPath);
sqlite.pragma('journal_mode = WAL');
sqlite.pragma('wal_autocheckpoint = 0'); // keep the write in -wal so the sidecar survives
sqlite.exec('CREATE TABLE t (id INTEGER); INSERT INTO t (id) VALUES (1);');
return sqlite;
};
it('closes the handle and clears pluton.db, -wal and -shm', async () => {
const sqlite = openWalDbWithSidecars();
expect(fs.existsSync(`${dbPath}-wal`)).toBe(true);
await releaseDatabaseFiles(sqlite, dbPath);
expect(sqlite.open).toBe(false);
expect(fs.existsSync(dbPath)).toBe(false);
expect(fs.existsSync(`${dbPath}-wal`)).toBe(false);
expect(fs.existsSync(`${dbPath}-shm`)).toBe(false);
});
it('is a no-op on the sidecars when the DB was never in WAL mode', async () => {
const sqlite = new Database(dbPath);
sqlite.exec('CREATE TABLE t (id INTEGER);');
await expect(releaseDatabaseFiles(sqlite, dbPath)).resolves.toBeUndefined();
expect(fs.existsSync(dbPath)).toBe(false);
});
it('leaves nothing that could replay a stale WAL onto the restored DB', async () => {
// The whole point of clearing the sidecars: a leftover -wal beside a fresh pluton.db
// would replay onto it at next open. Assert the db dir holds no db artifacts afterward.
const sqlite = openWalDbWithSidecars();
await releaseDatabaseFiles(sqlite, dbPath);
const leftovers = fs.readdirSync(tmp).filter(f => f.startsWith('pluton.db'));
expect(leftovers).toEqual([]);
});
});