Skip to content

Build your personal knowledge base with Trilium Notes

30.7 KB
Raw Blame
import { readBackupContainer } from "@triliumnext/backup-container";
import type { OptionNames, SetupBackupSettings } from "@triliumnext/commons";
import { getLog, getSql, ws } from "@triliumnext/core";
import fs from "fs";
import os from "os";
import path from "path";
import { Readable, Writable } from "stream";
import { afterAll, afterEach, beforeEach, describe, expect, it, type MockInstance, vi } from "vitest";

import ServerBackupService, { type ServerBackupConfig } from "./backup_provider.js";
import dataDir from "./services/data_dir.js";

const DEFAULT_DIR = path.resolve(dataDir.BACKUP_DIR);
const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "trilium-backup-spec-"));
const CUSTOM_DIR = path.join(tempRoot, "custom");

/** Stands in for the real online backup: writes a small file at the destination. */
let copyDatabase: MockInstance<(target: string) => Promise<void>>;

async function writeStubDatabase(target: string) {
    fs.writeFileSync(target, "db-bytes");
}

/** A desktop service (custom directory honoured) reading the given option value. */
function desktopService(
    customDbBackupDir: string | null,
    extraOptions: OptionOverrides = {},
    config: Partial<ServerBackupConfig> = {}
) {
    return new ServerBackupService(
        optionsWith(customDbBackupDir, extraOptions),
        { allowCustomDirectory: true, ...config }
    );
}

/** A server service, which ignores the option entirely. */
function serverService(customDbBackupDir: string | null) {
    return new ServerBackupService(optionsWith(customDbBackupDir));
}

type OptionOverrides = Partial<Record<OptionNames, string>>;

function optionsWith(customDbBackupDir: string | null, extraOptions: OptionOverrides = {}) {
    const values: Partial<Record<OptionNames, string | null>> = {
        customDbBackupDir,
        ...extraOptions
    };

    return {
        getOption: (name: OptionNames) => values[name] ?? "",
        getOptionOrNull: (name: OptionNames) => values[name] ?? null,
        getOptionBool: () => false,
        setOption: () => {}
    };
}

function backupNamesIn(directory: string) {
    return fs.existsSync(directory) ? fs.readdirSync(directory).sort() : [];
}

/** Unwraps a container back to the bytes the stub database was made of. */
async function unwrapContainer(filePath: string, passphrase?: string) {
    const chunks: Buffer[] = [];
    const sink = new Writable({
        write(chunk: Buffer, _encoding, callback) {
            chunks.push(Buffer.from(chunk));
            callback();
        }
    });

    await readBackupContainer(Readable.from([ fs.readFileSync(filePath) ]), sink, {
        passphrase,
        // The stub standing in for the online backup is not a real database.
        requireSqliteHeader: false
    });

    return Buffer.concat(chunks).toString();
}

beforeEach(() => {
    copyDatabase = vi.spyOn(getSql(), "copyDatabase").mockImplementation(writeStubDatabase);
    vi.spyOn(ws, "sendMessageToAllClients").mockImplementation(() => {});

    fs.rmSync(tempRoot, { recursive: true, force: true });
    fs.mkdirSync(tempRoot, { recursive: true });
    fs.rmSync(DEFAULT_DIR, { recursive: true, force: true });
});

afterEach(() => vi.restoreAllMocks());

afterAll(() => {
    fs.rmSync(tempRoot, { recursive: true, force: true });
    fs.rmSync(DEFAULT_DIR, { recursive: true, force: true });
});

describe("ServerBackupService: backup location", () => {
    it("uses the default directory when no custom one is configured", async () => {
        const service = desktopService("");

        expect(service.getBackupFolderPath()).toBe(DEFAULT_DIR);
        expect(await service.backupNow("now")).toBe(path.join(DEFAULT_DIR, "backup-now.db"));
    });

    it("uses the custom directory on the desktop, creating it if needed", async () => {
        const service = desktopService(CUSTOM_DIR);

        expect(service.getBackupFolderPath()).toBe(CUSTOM_DIR);
        expect(await service.backupNow("daily")).toBe(path.join(CUSTOM_DIR, "backup-daily.db"));
        expect(backupNamesIn(CUSTOM_DIR)).toEqual([ "backup-daily.db" ]);
        expect(backupNamesIn(DEFAULT_DIR)).toEqual([]);
    });

    it("ignores the custom directory on the server, which is configured via TRILIUM_BACKUP_DIR", async () => {
        const service = serverService(CUSTOM_DIR);

        expect(service.getBackupFolderPath()).toBe(DEFAULT_DIR);
        expect(await service.backupNow("daily")).toBe(path.join(DEFAULT_DIR, "backup-daily.db"));
        expect(backupNamesIn(CUSTOM_DIR)).toEqual([]);
    });

    it("falls back to the default directory for a blank, whitespace-only or missing option", () => {
        expect(desktopService("").getBackupFolderPath()).toBe(DEFAULT_DIR);
        expect(desktopService("   ").getBackupFolderPath()).toBe(DEFAULT_DIR);
        // The option row does not exist yet, e.g. the pre-migration backup of an older database.
        expect(desktopService(null).getBackupFolderPath()).toBe(DEFAULT_DIR);
    });

    it("resolves a relative custom directory against the working directory", () => {
        expect(desktopService("./my-backups").getBackupFolderPath()).toBe(path.resolve("./my-backups"));
    });

    it("treats a custom directory equal to the default one as no custom directory", async () => {
        const service = desktopService(DEFAULT_DIR);

        expect(service.getBackupFolderPath()).toBe(DEFAULT_DIR);
        await service.backupNow("now");
        // Listed once, not once per configured directory.
        const listed = await service.getExistingBackups();
        expect(listed.map((b) => b.fileName)).toEqual([ "backup-now.db" ]);
    });
});

describe("ServerBackupService: backup format", () => {
    const PASSPHRASE = "correct horse battery staple";
    const withPassphrase: Partial<ServerBackupConfig> = { getPassphrase: async () => PASSPHRASE };

    it("writes a plain database when neither compression nor encryption is on", async () => {
        const backupFile = await desktopService(CUSTOM_DIR).backupNow("now");

        expect(backupFile).toBe(path.join(CUSTOM_DIR, "backup-now.db"));
        expect(backupNamesIn(CUSTOM_DIR)).toEqual([ "backup-now.db" ]);
    });

    it("writes a compressed container, which unwraps to the database again", async () => {
        const service = desktopService(CUSTOM_DIR, { backupEnableCompression: "true" });

        const backupFile = await service.backupNow("now");

        expect(backupFile).toBe(path.join(CUSTOM_DIR, "backup-now.tnbackup"));
        expect(await unwrapContainer(backupFile)).toBe("db-bytes");
    });

    it("writes an encrypted container, which only the passphrase opens", async () => {
        const service = desktopService(
            CUSTOM_DIR,
            { backupEnableEncryption: "true" },
            withPassphrase
        );

        const backupFile = await service.backupNow("now");

        expect(backupFile).toBe(path.join(CUSTOM_DIR, "backup-now.tnbackup"));
        expect(await unwrapContainer(backupFile, PASSPHRASE)).toBe("db-bytes");
        await expect(unwrapContainer(backupFile, "wrong"))
            .rejects.toMatchObject({ reason: "wrong-passphrase-or-damaged-header" });
    });

    it("compresses and encrypts together when both are on", async () => {
        const service = desktopService(
            CUSTOM_DIR,
            { backupEnableCompression: "true", backupEnableEncryption: "true" },
            withPassphrase
        );

        const backupFile = await service.backupNow("now");

        expect(await unwrapContainer(backupFile, PASSPHRASE)).toBe("db-bytes");
    });

    it("keeps one file per backup name, whichever format it was last written in", async () => {
        await desktopService(CUSTOM_DIR).backupNow("daily");
        expect(backupNamesIn(CUSTOM_DIR)).toEqual([ "backup-daily.db" ]);

        await desktopService(CUSTOM_DIR, { backupEnableCompression: "true" }).backupNow("daily");
        expect(backupNamesIn(CUSTOM_DIR)).toEqual([ "backup-daily.tnbackup" ]);

        await desktopService(CUSTOM_DIR).backupNow("daily");
        expect(backupNamesIn(CUSTOM_DIR)).toEqual([ "backup-daily.db" ]);
    });

    it("leaves no snapshot behind in the data directory", async () => {
        await desktopService(CUSTOM_DIR, { backupEnableCompression: "true" }).backupNow("now");

        const left = fs.readdirSync(dataDir.TMP_DIR);
        const snapshots = left.filter((name) => name.includes("snapshot"));

        expect(snapshots).toEqual([]);
    });

    it("cleans up after a failure, leaving no snapshot and no partial container", async () => {
        copyDatabase.mockRejectedValue(new Error("EIO: i/o error"));

        const backup = desktopService("", { backupEnableCompression: "true" }).backupNow("now");

        await expect(backup).rejects.toThrow("EIO");

        const left = fs.readdirSync(dataDir.TMP_DIR);
        const snapshots = left.filter((name) => name.includes("snapshot"));

        expect(snapshots).toEqual([]);
        expect(backupNamesIn(DEFAULT_DIR)).toEqual([]);
    });

    it("lists containers alongside plain backups", async () => {
        await desktopService("", { backupEnableCompression: "true" }).backupNow("daily");
        await desktopService("").backupNow("weekly");

        const backups = await desktopService("").getExistingBackups();

        expect(backups.map((b) => b.fileName).sort()).toEqual(
            [ "backup-daily.tnbackup",
                "backup-weekly.db" ]
        );
    });

    it("reads what each container is from its own header, not from today's options", async () => {
        await desktopService("", { backupEnableCompression: "true" }).backupNow("compressed");
        const encrypting = desktopService("", { backupEnableEncryption: "true" }, withPassphrase);
        await encrypting.backupNow("encrypted");
        await desktopService("").backupNow("plain");

        // Listed by a service with both switched off: a backup keeps the shape it was written in.
        const listed = await desktopService("").getExistingBackups();
        const byName = new Map(listed.map((b) => [ b.fileName, b ]));

        expect(byName.get("backup-compressed.tnbackup")).toMatchObject(
            { compressed: true,
                encrypted: false,
                plaintextSize: "db-bytes".length }
        );
        expect(byName.get("backup-encrypted.tnbackup")).toMatchObject(
            { compressed: false,
                encrypted: true }
        );
        // A plain copy states nothing of the sort: its own size is the whole story.
        expect(byName.get("backup-plain.db")).not.toHaveProperty("compressed");
        expect(byName.get("backup-plain.db")).not.toHaveProperty("plaintextSize");
    });

    it("lists a container it cannot make sense of, saying so rather than dropping it", async () => {
        fs.mkdirSync(DEFAULT_DIR, { recursive: true });
        fs.writeFileSync(
            path.join(DEFAULT_DIR, "backup-damaged.tnbackup"),
            "not a container at all"
        );

        const backups = await desktopService("").getExistingBackups();

        // Listed, because a file sitting in the backup directory is one the user is relying on,
        // and saying it is no good is the whole point of listing it.
        expect(backups.map((b) => b.fileName)).toEqual([ "backup-damaged.tnbackup" ]);
        expect(backups[0]).toMatchObject({ unreadable: "invalid" });
        expect(backups[0]).not.toHaveProperty("compressed");
        expect(backups[0]).not.toHaveProperty("encrypted");
    });

    it("tells a backup from a newer Trilium apart from one that is not a backup", async () => {
        fs.mkdirSync(DEFAULT_DIR, { recursive: true });

        const compressing = desktopService("", { backupEnableCompression: "true" });
        const newer = fs.readFileSync(await compressing.backupNow("daily"));
        // The version byte, straight after the magic. Everything else about the file is intact,
        // which is exactly the case that must not read as damaged.
        newer.writeUInt8(2, 20);
        fs.writeFileSync(path.join(DEFAULT_DIR, "backup-newer.tnbackup"), newer);

        const byName = new Map(
            (await desktopService("").getExistingBackups()).map((b) => [ b.fileName, b ])
        );

        expect(byName.get("backup-newer.tnbackup")).toMatchObject({
            unreadable: "unsupported-version"
        });
        expect(byName.get("backup-daily.tnbackup")).not.toHaveProperty("unreadable");
    });
});

describe("ServerBackupService.backupAs: the backup the setup screen asked for", () => {
    const PASSPHRASE = "correct horse battery staple";
    const withPassphrase: Partial<ServerBackupConfig> = { getPassphrase: async () => PASSPHRASE };

    /** What the screen sends, with the plainest backup there is as the starting point. */
    function asked(overrides: Partial<SetupBackupSettings> = {}): SetupBackupSettings {
        return {
            name: "Before the import",
            passphrase: "",
            useStoredPassphrase: false,
            compress: false,
            ...overrides
        };
    }

    it("writes it under the name the user gave it, spaces and all", async () => {
        const written = await desktopService(CUSTOM_DIR).backupAs(asked());

        // A plain database copy rather than a container, which is what nothing asked for looks like.
        expect(written.fileName).toBe("Before the import.db");
        expect(written.directoryPath).toBe(CUSTOM_DIR);
    });

    it("locks it with the password typed on the screen, over anything the instance is set up for", async () => {
        // Encryption is off in the options, and there is a stored passphrase that is not this one:
        // what the user typed while asking is what the backup is written with.
        const service = desktopService(CUSTOM_DIR, {}, withPassphrase);

        const written = await service.backupAs(asked({ passphrase: "typed-here" }));

        expect(written.fileName).toBe("Before the import.tnbackup");
        expect(await unwrapContainer(written.filePath, "typed-here")).toBe("db-bytes");
        await expect(unwrapContainer(written.filePath, PASSPHRASE))
            .rejects.toMatchObject({ reason: "wrong-passphrase-or-damaged-header" });
    });

    it("locks it with the stored passphrase where that is what was asked for", async () => {
        // The one the screen cannot show and so cannot have sent: asking for it is the only way.
        const service = desktopService(CUSTOM_DIR, {}, withPassphrase);

        const written = await service.backupAs(asked({ useStoredPassphrase: true, passphrase: "ignored" }));

        expect(written.fileName).toBe("Before the import.tnbackup");
        expect(await unwrapContainer(written.filePath, PASSPHRASE)).toBe("db-bytes");
    });

    it("leaves it unlocked where the user cleared the password, however the instance backs up", async () => {
        const service = desktopService(
            CUSTOM_DIR,
            { backupEnableEncryption: "true", backupEnableCompression: "true" },
            withPassphrase
        );

        const written = await service.backupAs(asked());

        // Neither locked nor wrapped, so not a container at all: a plain database copy.
        expect(written.fileName).toBe("Before the import.db");
    });

    it("compresses because the screen said so, not because the option says so", async () => {
        const compressed = await desktopService(CUSTOM_DIR).backupAs(asked({ compress: true }));
        expect(compressed.fileName).toBe("Before the import.tnbackup");
        expect(await unwrapContainer(compressed.filePath)).toBe("db-bytes");

        const plain = await desktopService(CUSTOM_DIR, { backupEnableCompression: "true" })
            .backupAs(asked({ name: "Plain" }));
        expect(plain.fileName).toBe("Plain.db");
    });

    it("falls back to an unencrypted local copy where the stored passphrase turns out to be unreadable", async () => {
        // Only reachable if the keyring fails between the screen being told there is a passphrase
        // and the backup asking for it. A backup is still worth more than no backup.
        const service = desktopService(CUSTOM_DIR, {}, { getPassphrase: async () => null });

        const written = await service.backupAs(asked({ useStoredPassphrase: true }));

        // Unlocked, and so kept out of the chosen directory: that one is typically a synced folder,
        // which is the very thing encryption was turned on to keep a readable database out of.
        expect(written.fileName).toBe("Before the import.db");
        expect(written.directoryPath).toBe(DEFAULT_DIR);
        expect(ws.sendMessageToAllClients).toHaveBeenCalledWith(
            expect.objectContaining({ type: "toast", message: expect.stringContaining("not encrypted") })
        );
    });

    it("says whether there is a stored passphrase, which is all the screen is allowed to learn", async () => {
        await expect(desktopService("", {}, withPassphrase).hasStoredPassphrase()).resolves.toBe(true);
        await expect(desktopService("", {}, { getPassphrase: async () => null }).hasStoredPassphrase())
            .resolves.toBe(false);
        // A build with no keyring behind it at all, which is every server deployment.
        await expect(desktopService("").hasStoredPassphrase()).resolves.toBe(false);
    });
});

describe("ServerBackupService: when the backup passphrase cannot be read", () => {
    const noPassphrase: Partial<ServerBackupConfig> = { getPassphrase: async () => null };

    it("keeps the unencrypted backup out of the chosen directory and says so", async () => {
        const service = desktopService(
            CUSTOM_DIR,
            { backupEnableEncryption: "true" },
            noPassphrase
        );

        const backupFile = await service.backupNow("daily");

        // The chosen directory is typically a synced folder, which is what encryption was avoiding.
        // With nothing left to wrap, the backup is a plain database again rather than an empty
        // container.
        expect(backupFile).toBe(path.join(DEFAULT_DIR, "backup-daily.db"));
        expect(backupNamesIn(CUSTOM_DIR)).toEqual([]);
        expect(ws.sendMessageToAllClients).toHaveBeenCalledWith(
            expect.objectContaining(
                { type: "toast",
                    message: expect.stringContaining("not encrypted") }
            )
        );
    });

    it("still honours compression, so only what could not be done is missing", async () => {
        const service = desktopService(
            CUSTOM_DIR,
            { backupEnableCompression: "true", backupEnableEncryption: "true" },
            noPassphrase
        );

        const backupFile = await service.backupNow("daily");

        expect(backupFile).toBe(path.join(DEFAULT_DIR, "backup-daily.tnbackup"));
    });

    it("says nothing and encrypts nothing when encryption was never asked for", async () => {
        await desktopService(CUSTOM_DIR, {}, noPassphrase).backupNow("daily");

        expect(backupNamesIn(CUSTOM_DIR)).toEqual([ "backup-daily.db" ]);
        expect(ws.sendMessageToAllClients).not.toHaveBeenCalled();
    });

    it("treats a service with no passphrase provider at all the same way", async () => {
        const service = desktopService(CUSTOM_DIR, { backupEnableEncryption: "true" });

        expect(await service.backupNow("daily")).toBe(path.join(DEFAULT_DIR, "backup-daily.db"));
    });
});

describe("ServerBackupService: fallback when the custom directory cannot be written to", () => {
    it("backs up to the default directory and notifies the user", async () => {
        copyDatabase.mockRejectedValueOnce(new Error("ENOSPC: no space left on device"));

        expect(await desktopService(CUSTOM_DIR).backupNow("daily")).toBe(path.join(DEFAULT_DIR, "backup-daily.db"));
        expect(backupNamesIn(DEFAULT_DIR)).toEqual([ "backup-daily.db" ]);

        expect(ws.sendMessageToAllClients).toHaveBeenCalledWith(
            expect.objectContaining({
                type: "toast",
                message: `Database backup failed: unable to write to ${CUSTOM_DIR}. Backing up to the default location instead.`
            })
        );
    });

    it("falls back when the custom directory itself cannot be created", async () => {
        // A file where the directory should be: mkdir fails on every platform.
        const blocked = path.join(tempRoot, "blocked");
        fs.writeFileSync(blocked, "not-a-directory");

        const service = desktopService(path.join(blocked, "backups"));

        expect(await service.backupNow("now")).toBe(path.join(DEFAULT_DIR, "backup-now.db"));
        expect(ws.sendMessageToAllClients).toHaveBeenCalledOnce();
    });

    it("leaves no half-written file behind in the custom directory", async () => {
        copyDatabase.mockImplementationOnce(async (target: string) => {
            fs.writeFileSync(target, "partial");
            throw new Error("EIO: i/o error");
        });

        await desktopService(CUSTOM_DIR).backupNow("daily");

        expect(backupNamesIn(CUSTOM_DIR)).toEqual([]);
        expect(backupNamesIn(DEFAULT_DIR)).toEqual([ "backup-daily.db" ]);
    });

    it("propagates the failure when the default directory fails too", async () => {
        copyDatabase.mockRejectedValue(new Error("EACCES: permission denied"));

        await expect(desktopService(CUSTOM_DIR).backupNow("now")).rejects.toThrow("EACCES");
    });

    it("does not notify when there is no custom directory to fall back from", async () => {
        copyDatabase.mockRejectedValue(new Error("EACCES: permission denied"));

        await expect(desktopService("").backupNow("now")).rejects.toThrow("EACCES");
        expect(ws.sendMessageToAllClients).not.toHaveBeenCalled();
    });
});

describe("ServerBackupService: what reaches the backend log", () => {
    /** The log is meant to be postable for diagnostics as-is, so no backup path may appear in it. */
    function loggedBy(method: "info" | "error") {
        return vi.spyOn(getLog(), method).mockImplementation(() => {});
    }

    function linesFrom(spy: ReturnType<typeof loggedBy>) {
        return spy.mock.calls.flat().join("\n");
    }

    it("names the backup relative to its directory, never the directory itself", async () => {
        const info = loggedBy("info");

        await desktopService("").backupNow("daily");

        expect(linesFrom(info)).toContain(`Created backup .${path.sep}backup-daily.db`);
        expect(linesFrom(info)).not.toContain(DEFAULT_DIR);
    });

    it("says a backup went to the custom location without saying where that is", async () => {
        const info = loggedBy("info");

        await desktopService(CUSTOM_DIR).backupNow("daily");

        expect(linesFrom(info)).toContain(`Created backup .${path.sep}backup-daily.db in the custom backup location.`);
        expect(linesFrom(info)).not.toContain(CUSTOM_DIR);
    });

    it("keeps the reason for a fallback but strips the location the error quotes back", async () => {
        const error = loggedBy("error");
        copyDatabase.mockRejectedValueOnce(new Error(`EACCES: permission denied, open '${CUSTOM_DIR}\\backup-daily.db'`));

        await desktopService(CUSTOM_DIR).backupNow("daily");

        expect(linesFrom(error)).toContain("EACCES: permission denied");
        expect(linesFrom(error)).not.toContain(CUSTOM_DIR);
    });

    it("strips the location from the failure it propagates when there is nowhere left to fall back to", async () => {
        copyDatabase.mockRejectedValue(new Error(`ENOSPC: no space left on device, open '${DEFAULT_DIR}\\backup-now.db'`));

        const failure = await desktopService("").backupNow("now").catch((e: Error) => e.message);

        expect(failure).toContain("ENOSPC: no space left on device");
        expect(failure).not.toContain(DEFAULT_DIR);
    });
});

describe("ServerBackupService.backupNow: naming", () => {
    it("rejects a name with no usable characters", async () => {
        await expect(desktopService("").backupNow("../..")).rejects.toThrow("Invalid backup name");
    });

    it("strips path traversal from the name", async () => {
        expect(await desktopService(CUSTOM_DIR).backupNow("../../evil")).toBe(path.join(CUSTOM_DIR, "backup-evil.db"));
    });
});

describe("ServerBackupService.getExistingBackups", () => {
    it("lists .db backups with their size, excluding intermediate SQLite files", async () => {
        fs.mkdirSync(DEFAULT_DIR, { recursive: true });
        fs.writeFileSync(path.join(DEFAULT_DIR, "backup-spec-list.db"), "backup-bytes");
        fs.writeFileSync(path.join(DEFAULT_DIR, "backup-spec-list.db-journal"), "journal-bytes");

        const backups = await desktopService("").getExistingBackups();

        expect(backups.map((b) => b.fileName)).toEqual([ "backup-spec-list.db" ]);
        expect(backups[0].fileSize).toBe("backup-bytes".length);
        expect(backups[0].filePath).toBe(path.join(DEFAULT_DIR, "backup-spec-list.db"));
        expect(backups[0].mtime).toBeInstanceOf(Date);
    });

    it("merges the custom and the default directory, so redirected backups stay reachable", async () => {
        fs.mkdirSync(CUSTOM_DIR, { recursive: true });
        fs.mkdirSync(DEFAULT_DIR, { recursive: true });
        fs.writeFileSync(path.join(CUSTOM_DIR, "backup-daily.db"), "a");
        fs.writeFileSync(path.join(DEFAULT_DIR, "backup-weekly.db"), "b");

        const backups = await desktopService(CUSTOM_DIR).getExistingBackups();

        expect(backups.map((b) => b.filePath).sort()).toEqual(
            [
                path.join(CUSTOM_DIR, "backup-daily.db"),
                path.join(DEFAULT_DIR, "backup-weekly.db")
            ].sort()
        );
    });

    it("tolerates a custom directory that does not exist", async () => {
        await expect(desktopService(path.join(tempRoot, "gone")).getExistingBackups()).resolves.toEqual([]);
    });
});

describe("ServerBackupService.getBackupContent", () => {
    it("reads a backup from the default directory", async () => {
        fs.mkdirSync(DEFAULT_DIR, { recursive: true });
        const file = path.join(DEFAULT_DIR, "backup-now.db");
        fs.writeFileSync(file, "db-bytes");

        expect(await desktopService("").getBackupContent(file)).toEqual(Buffer.from("db-bytes"));
    });

    it("reads a backup from the custom directory", async () => {
        fs.mkdirSync(CUSTOM_DIR, { recursive: true });
        const file = path.join(CUSTOM_DIR, "backup-now.db");
        fs.writeFileSync(file, "db-bytes");

        expect(await desktopService(CUSTOM_DIR).getBackupContent(file)).toEqual(Buffer.from("db-bytes"));
    });

    it("refuses a path outside the backup directories", async () => {
        const outside = path.join(tempRoot, "secret.db");
        fs.writeFileSync(outside, "secret");

        expect(await desktopService(CUSTOM_DIR).getBackupContent(outside)).toBeNull();
        expect(await desktopService(CUSTOM_DIR).getBackupContent(path.join(DEFAULT_DIR, "..", "document.db"))).toBeNull();
        // The directory itself is not a backup.
        expect(await desktopService(CUSTOM_DIR).getBackupContent(CUSTOM_DIR)).toBeNull();
        // The custom directory is only allowed while it is the configured one.
        expect(await desktopService("").getBackupContent(path.join(CUSTOM_DIR, "backup-now.db"))).toBeNull();
    });

    it("accepts a custom directory given with a trailing separator", async () => {
        fs.mkdirSync(CUSTOM_DIR, { recursive: true });
        const file = path.join(CUSTOM_DIR, "backup-now.db");
        fs.writeFileSync(file, "db-bytes");

        expect(await desktopService(CUSTOM_DIR + path.sep).getBackupContent(file)).toEqual(Buffer.from("db-bytes"));
    });

    it("returns null for a missing file inside the backup directory", async () => {
        expect(await desktopService("").getBackupContent(path.join(DEFAULT_DIR, "backup-absent.db"))).toBeNull();
    });
});

describe("ServerBackupService: sending a backup for download", () => {
    /** Collects what was written to it, and records the moment the headers were committed. */
    function fakeResponse() {
        const headers: Record<string, string> = {};
        const chunks: Buffer[] = [];
        let flushedAfter: number | null = null;

        const res = new Writable({
            write(chunk: Buffer, _encoding, callback) {
                chunks.push(Buffer.from(chunk));
                callback();
            }
        }) as Writable & {
            setHeader(name: string, value: string): void;
            flushHeaders(): void;
        };
        res.setHeader = (name, value) => { headers[name] = value; };
        res.flushHeaders = () => { flushedAfter = chunks.length; };

        return { res, headers, chunks, flushed: () => flushedAfter };
    }

    async function written(res: Writable): Promise<void> {
        await new Promise((resolve) => res.on("finish", resolve));
    }

    it("streams it with its headers committed first, so nothing downstream buffers it whole", async () => {
        const filePath = path.join(CUSTOM_DIR, "Backup 2026-08-07 10-32-21.tnbackup");
        fs.mkdirSync(CUSTOM_DIR, { recursive: true });
        fs.writeFileSync(filePath, "backup-bytes");
        const { res, headers, chunks, flushed } = fakeResponse();

        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the express Response surface this uses.
        expect(desktopService(CUSTOM_DIR).sendBackup?.(filePath, res as any)).toBe(true);
        await written(res);

        expect(Buffer.concat(chunks).toString()).toBe("backup-bytes");
        expect(headers["Content-Disposition"])
            .toBe('attachment; filename="Backup 2026-08-07 10-32-21.tnbackup"');
        expect(headers["Content-Length"]).toBe("12");
        // Before any of the body: the desktop's protocol bridge streams only once headers are
        // flushed, and buffers a multi-gigabyte backup whole otherwise.
        expect(flushed()).toBe(0);
    });

    it("refuses anything that is not an existing backup, rather than sending a file", () => {
        const { res } = fakeResponse();

        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- as above.
        expect(desktopService(CUSTOM_DIR).sendBackup?.("/etc/passwd", res as any)).toBe(false);
    });
});

describe("ServerBackupService.adoptPassphrase", () => {
    it("hands the password to wherever this platform keeps one, and clears it on null", async () => {
        const stored: (string | null)[] = [];
        const service = desktopService("", {}, { setPassphrase: async (p) => void stored.push(p) });

        await service.adoptPassphrase("the restored database's password");
        await service.adoptPassphrase(null);

        expect(stored).toEqual([ "the restored database's password", null ]);
    });

    it("does nothing where there is nowhere to keep one, rather than failing the restore", async () => {
        // The server has no keyring, so it has no stored passphrase for a restore to bring up to
        // date; the restore calls this the same way regardless of the platform it is running on.
        await expect(serverService(null).adoptPassphrase("a password")).resolves.toBeUndefined();
    });
});