@jwilleke/ngdpbase-types 5.18.0 → 5.20.0

package/lib/src/managers/DatabaseManager.js

@@ -25,15 +25,49 @@
  * Only a declared database is opened (#1860): the add-on names it in its own
  * config/default-config.json (`ngdpbase.addons.<slug>.database`), and one
  * declared `encrypt: "required"` is never opened without the key.
+ *
+ * Backup and restore (#1723): `backup()` and `restore()` are the ones
+ * BackupManager calls on every manager, so add-ons write no backup code. A
+ * backup copies the application database and every declared add-on database,
+ * on or off, at one point in time, on a worker thread, each into its own file
+ * beside BackupManager's document, encrypted under `NGDPBASE_BACKUP_KEY`. A
+ * restore stages `<file>.staged` beside each database, all or nothing, and the
+ * next start puts them in place before any database opens.
  */
 import path from 'node:path';
 import BaseManager from './BaseManager.js';
 import SqliteDatabaseProvider, { DEFAULT_BUSY_TIMEOUT_MS } from '../providers/SqliteDatabaseProvider.js';
 import DATABASE_MIGRATIONS from '../providers/databaseMigrations.js';
+import { createHmac } from 'node:crypto';
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { actorOf } from '../context/ActorContext.js';
+import { recordAuditEvent } from '../utils/auditEvents.js';
+import { AUDIT_EVENT } from '../utils/auditEventNames.js';
 import logger from '../utils/logger.js';
 import { ADDON_SLUG, ledgerPrefix } from '../utils/addonDatabaseRules.js';
+import { applyStagedRestore, manifestPath, runOffThread, stagedPath, writeManifest } from '../providers/sqliteBackup.js';
 /** The environment variable holding the SQLCipher key. Never a config key: config is readable from the admin screens. */
 export const DATABASE_KEY_ENV = 'NGDPBASE_DATABASE_KEY';
+/**
+ * The environment variable holding the key every database backup is encrypted
+ * under (#1723). Its own secret, not the database key: the copy that travels
+ * and the copy that stays should not fall to the same compromise. Never a
+ * config key. Unset, no database is backed up, and admins are told.
+ */
+export const BACKUP_KEY_ENV = 'NGDPBASE_BACKUP_KEY';
+/** How long a database backup or restore staging may run on its worker before it is stopped, when not configured. */
+export const DEFAULT_BACKUP_WORKER_TIMEOUT_MS = 3_600_000;
+/**
+ * A short fingerprint of a backup key (#1723, D3): the first 16 hex digits of
+ * an HMAC of a fixed label under the key. Recorded in each backup so a restore
+ * under another key says so plainly; it never reveals the key.
+ */
+export function backupKeyFingerprint(key) {
+    return createHmac('sha256', key).update('ngdpbase backup key fingerprint v1').digest('hex').slice(0, 16);
+}
+/** The backup's name for the application database; an add-on's is `addon-<owner>`. */
+const APPLICATION = 'application';
+const addonName = (owner) => `addon-${owner}`;
 /**
  * The request rules (addonDatabaseRules): the owner is a canonical slug, and
  * the ledger table starts with its prefix. `openAddonDatabase` applies them,
@@ -73,6 +107,10 @@ class DatabaseManager extends BaseManager {
     databaseFile = null;
     busyTimeoutMs = DEFAULT_BUSY_TIMEOUT_MS;
     addonDatabases = new Map();
+    /** What the start did with a staged restore (#1723), reported once the notifications exist. */
+    restoreAtStart = null;
+    /** Why this manager is degraded, one entry per cause, so one cause clearing leaves the others. */
+    faults = new Map();
     constructor(engine) {
         super(engine);
     }
@@ -95,6 +133,8 @@ class DatabaseManager extends BaseManager {
         this.busyTimeoutMs = busy;
         const file = configManager.getResolvedDataPath('ngdpbase.database.file', './data/ngdpbase.db');
         const key = process.env[DATABASE_KEY_ENV] ?? '';
+        // #1723: a staged restore goes in now, before any database opens.
+        this.applyRestoreAtStart(file);
         const provider = new SqliteDatabaseProvider(file, key, DATABASE_MIGRATIONS, 'schema_migrations', { busyTimeoutMs: this.busyTimeoutMs });
         if (!provider.integrityOk()) {
             provider.close();
@@ -107,6 +147,11 @@ class DatabaseManager extends BaseManager {
         if (!key) {
             logger.warn(`[DatabaseManager] ${DATABASE_KEY_ENV} is not set, so the application database is stored unencrypted (#1536)`);
         }
+        const keyProblem = this.backupKeyProblem();
+        if (keyProblem) {
+            logger.error(`[DatabaseManager] ${keyProblem}`);
+            this.fault('backup-key', keyProblem);
+        }
     }
     /** Whether an application database is open. */
     isEnabled() {
@@ -210,7 +255,316 @@ class DatabaseManager extends BaseManager {
     static keyRefusal(declaration, key) {
         if (declaration.encrypt !== 'required' || key)
             return null;
-        return `Add-on '${declaration.declaredBy}' declares database '${declaration.owner}' with encrypt "required", but ${DATABASE_KEY_ENV} is not set — it is never opened unencrypted (#1860)`;
+        return `Add-on '${declaration.declaredBy}' declares database '${declaration.owner}' with encrypt "required", but ${DATABASE_KEY_ENV} is not set — it is never opened unencrypted. Set ${DATABASE_KEY_ENV} in the environment or the instance .env (<FAST_STORAGE>/.env) and restart (#1860, #1883)`;
+    }
+    // ---- Backup and restore (#1723) ------------------------------------------
+    /**
+     * Copy every database into the backup BackupManager is writing: the
+     * application database and every declared add-on database, on or off, at
+     * one point in time, on a worker thread. Each goes into its own file,
+     * `<stem>.<name>.db`, beside the document, encrypted under
+     * `NGDPBASE_BACKUP_KEY`; the document references them. A database that
+     * fails is named in `warnings`, and the others are still written.
+     *
+     * Throws when there is no backup key: nothing is ever written unencrypted.
+     */
+    async backup(options) {
+        const base = { managerName: 'DatabaseManager', timestamp: new Date().toISOString() };
+        if (!this.provider || !this.databaseFile) {
+            return { ...base, data: null, note: 'No application database (ngdpbase.database.provider is none)' };
+        }
+        if (!options?.directory || !options.stem) {
+            throw new Error('DatabaseManager writes its databases beside the backup document, so it is backed up through BackupManager (#1723)');
+        }
+        const backupKey = this.backupKey();
+        if (!backupKey) {
+            const reason = `${BACKUP_KEY_ENV} is not set, so no database was backed up. Database backups are always encrypted and are never written without it (#1723)`;
+            this.fault('backup-key', reason);
+            throw new Error(reason);
+        }
+        const key = process.env[DATABASE_KEY_ENV] ?? '';
+        const keyProblem = this.backupKeyProblem();
+        if (keyProblem) {
+            // D3: still backed up, but as loudly as a missing key.
+            logger.error(`[DatabaseManager] ${keyProblem}`);
+            this.fault('backup-key', keyProblem);
+            await this.notify('error', 'The backup key is the database key', `${keyProblem}. This backup was still taken.`);
+        }
+        else {
+            this.clearFault('backup-key');
+        }
+        const sources = this.backupSources(this.databaseFile);
+        const absent = sources.filter((s) => !existsSync(s.file)).map((s) => s.name);
+        const exports = sources
+            .filter((s) => existsSync(s.file))
+            .map((s) => ({ name: s.name, source: s.file, sourceKey: key, target: path.join(options.directory, `${options.stem}.${s.name}.db`) }));
+        let outcome;
+        try {
+            outcome = await runOffThread({ kind: 'export', exports, backupKey }, this.workerTimeoutMs());
+        }
+        catch (err) {
+            for (const e of exports)
+                rmSync(e.target, { force: true });
+            throw err;
+        }
+        const byName = new Map(sources.map((s) => [s.name, s]));
+        const data = {
+            format: 1,
+            keyFingerprint: backupKeyFingerprint(backupKey),
+            databases: outcome.written.map((w) => {
+                const s = byName.get(w.name);
+                return { name: w.name, kind: s.kind, ...(s.owner ? { owner: s.owner } : {}), file: path.basename(w.target), sizeBytes: w.sizeBytes, tables: w.tables };
+            }),
+            absent,
+            failed: outcome.failed
+        };
+        logger.info(`[DatabaseManager] Backed up ${data.databases.length} database(s): ${data.databases.map((d) => d.name).join(', ')}${absent.length ? `; not created yet: ${absent.join(', ')}` : ''} (#1723)`);
+        const warnings = outcome.failed.map((f) => `database ${f.name} was not backed up: ${f.error}`);
+        for (const w of warnings)
+            logger.error(`[DatabaseManager] ${w}`);
+        return { ...base, data, ...(warnings.length > 0 ? { warnings } : {}) };
+    }
+    /**
+     * Stage a restore of the databases in a backup, for the next start. Each
+     * backed-up database is opened under the backup key, integrity-checked, and
+     * copied into `<live>.staged` under this site's database key. All or
+     * nothing: if any fails, none is staged. A database the backup does not
+     * contain is left as it is. Live files are never touched here.
+     *
+     * BackupManager takes a fresh backup of the live data before calling this.
+     * A backed-up add-on database that no add-on on this site declares is not
+     * staged, and admins are told.
+     */
+    async restore(backupData, options) {
+        await super.restore(backupData);
+        const data = backupData.data;
+        if (!data || !Array.isArray(data.databases) || data.databases.length === 0) {
+            logger.info('[DatabaseManager] The backup holds no database; every database is left as it is (#1723)');
+            return;
+        }
+        if (!this.provider || !this.databaseFile) {
+            throw new Error("The backup holds databases, but this site has none open — set ngdpbase.database.provider to 'sqlite' first (#1723)");
+        }
+        if (!options?.directory) {
+            throw new Error('DatabaseManager reads its databases from beside the backup document, so it is restored through BackupManager (#1723)');
+        }
+        const backupKey = this.backupKey();
+        if (!backupKey) {
+            throw new Error(`${BACKUP_KEY_ENV} is not set, so the databases in this backup cannot be read; nothing was staged (#1723)`);
+        }
+        if (data.keyFingerprint && data.keyFingerprint !== backupKeyFingerprint(backupKey)) {
+            throw new Error(`This backup was made with a different backup key (fingerprint ${data.keyFingerprint}; ${BACKUP_KEY_ENV} now has ${backupKeyFingerprint(backupKey)}). Set ${BACKUP_KEY_ENV} to the key it was made with; nothing was staged (#1723)`);
+        }
+        const staged = this.getStagedRestore();
+        if (staged && !options.replaceStaged) {
+            throw new Error(`A restore from ${staged.source || staged.backup} is already staged (by ${staged.stagedBy || 'unknown'}, ${staged.stagedAt}). Cancel it, or replace it; nothing was changed (#1723)`);
+        }
+        const targetKey = process.env[DATABASE_KEY_ENV] ?? '';
+        const dir = path.dirname(this.databaseFile);
+        const declarations = this.declarations();
+        const stages = [];
+        const skipped = [];
+        for (const entry of data.databases) {
+            if (typeof entry?.file !== 'string' || path.basename(entry.file) !== entry.file || entry.file.startsWith('.')) {
+                throw new Error(`The backup names a database file '${String(entry?.file)}' outside its directory; nothing was staged (#1723)`);
+            }
+            let live;
+            if (entry.name === APPLICATION) {
+                live = this.databaseFile;
+            }
+            else {
+                const owner = entry.name.startsWith('addon-') ? entry.name.slice('addon-'.length) : '';
+                if (!ADDON_SLUG.test(owner)) {
+                    throw new Error(`The backup holds a database '${entry.name}' this build does not know; nothing was staged (#1723)`);
+                }
+                const declared = declarations.filter((d) => d.owner === owner);
+                if (declared.length === 0) {
+                    skipped.push(entry.name);
+                    continue;
+                }
+                if (!targetKey && declared.some((d) => d.encrypt === 'required')) {
+                    throw new Error(`Database '${owner}' is declared encrypt "required", but ${DATABASE_KEY_ENV} is not set — it is never restored unencrypted; nothing was staged (#1723)`);
+                }
+                live = path.join(dir, `${owner}.db`);
+            }
+            const backupFile = path.join(options.directory, entry.file);
+            if (!existsSync(backupFile)) {
+                throw new Error(`The backup's database file ${entry.file} is missing from ${options.directory}; nothing was staged (#1723)`);
+            }
+            stages.push({ name: entry.name, backupFile, live, targetKey });
+        }
+        if (stages.length === 0) {
+            throw new Error(`None of the databases in this backup belongs to this site (${skipped.join(', ')}); nothing was staged (#1723)`);
+        }
+        // A restore staged earlier and not yet applied is replaced by this one.
+        const manifestFile = manifestPath(this.databaseFile);
+        for (const previous of this.getStagedRestore()?.databases ?? [])
+            rmSync(stagedPath(previous.live), { force: true });
+        rmSync(manifestFile, { force: true });
+        try {
+            await runOffThread({ kind: 'stage', stages, backupKey }, this.workerTimeoutMs());
+        }
+        catch (err) {
+            for (const s of stages)
+                rmSync(stagedPath(s.live), { force: true });
+            throw new Error(`The databases were not staged, and nothing was changed: ${err.message}`, { cause: err });
+        }
+        const manifest = {
+            version: 1,
+            stagedAt: new Date().toISOString(),
+            backup: String(backupData.timestamp ?? ''),
+            source: options.source ?? '',
+            stagedBy: actorOf(options.ctx).user,
+            ...(options.safetyBackup ? { safetyBackup: options.safetyBackup } : {}),
+            databases: stages.map((s) => ({ name: s.name, live: s.live, staged: stagedPath(s.live) }))
+        };
+        writeManifest(manifestFile, manifest);
+        const names = stages.map((s) => s.name).join(', ');
+        logger.warn(`[DatabaseManager] Restore staged for ${names} — restart to apply it (#1723)`);
+        await this.notify('warning', 'A database restore is staged', `The databases ${names} from the backup taken ${manifest.backup} are staged. Restart the site to put them in place; the current files are kept as *.pre-restore.${manifest.safetyBackup ? ` The current data was backed up first, as ${manifest.safetyBackup}.` : ''}`);
+        if (skipped.length > 0) {
+            const message = `The backup also holds ${skipped.join(', ')}, which no add-on on this site declares, so they were not restored. Install the add-on and restore again to bring them back.`;
+            logger.error(`[DatabaseManager] ${message}`);
+            await this.notify('error', 'Some databases in the backup were not restored', message);
+        }
+    }
+    /** The restore staged and waiting for the next start, or null. */
+    getStagedRestore() {
+        if (!this.databaseFile)
+            return null;
+        const file = manifestPath(this.databaseFile);
+        if (!existsSync(file))
+            return null;
+        try {
+            return JSON.parse(readFileSync(file, 'utf8'));
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Throw away a staged restore before the restart applies it (#1723, D5):
+     * the staged files and the manifest are removed, the live databases are
+     * untouched. Recorded first (`backup-restore-cancel`, refuse): a cancel that
+     * cannot be recorded does not happen.
+     */
+    async cancelStagedRestore(ctx) {
+        const staged = this.getStagedRestore();
+        if (!staged || !this.databaseFile)
+            throw new Error('No database restore is staged');
+        const who = actorOf(ctx);
+        await recordAuditEvent(this.engine.getManager('AuditManager'), {
+            eventType: AUDIT_EVENT.BACKUP_RESTORE_CANCEL,
+            ...who,
+            action: 'backup-restore-cancel',
+            result: 'success',
+            severity: 'high',
+            resource: staged.source || staged.backup,
+            resourceType: 'backup',
+            metadata: { ...who.metadata, stagedAt: staged.stagedAt, stagedBy: staged.stagedBy, databases: staged.databases.map((d) => d.name) }
+        });
+        for (const d of staged.databases)
+            rmSync(stagedPath(d.live), { force: true });
+        rmSync(manifestPath(this.databaseFile), { force: true });
+        logger.warn(`[DatabaseManager] Staged restore from ${staged.source || staged.backup} cancelled by ${who.user} (#1723)`);
+        return staged;
+    }
+    /**
+     * Tell admins what the start found (#1723): what it did with a staged
+     * restore, and a backup key that is missing or the database key. Called by
+     * the engine once every manager exists: DatabaseManager starts before the
+     * notifications do.
+     */
+    async reportAtBoot() {
+        const keyProblem = this.provider ? this.backupKeyProblem() : null;
+        if (keyProblem)
+            await this.notify('error', 'Databases are not safely backed up', keyProblem);
+        const outcome = this.restoreAtStart;
+        this.restoreAtStart = null;
+        if (!outcome)
+            return;
+        if (outcome.refused) {
+            await this.notify('error', 'A database restore was not applied', `${outcome.refused}. The site started on its current databases.`);
+            return;
+        }
+        await this.notify('success', 'A database restore was applied', `Restored at start: ${outcome.applied.map((a) => a.name).join(', ')}. The previous files are kept as *.pre-restore.`);
+    }
+    /** The application database and every declared add-on database (one per owner), on or off. */
+    backupSources(applicationFile) {
+        const sources = [{ name: APPLICATION, kind: 'application', file: applicationFile }];
+        for (const owner of new Set(this.declarations().map((d) => d.owner))) {
+            sources.push({ name: addonName(owner), kind: 'addon', owner, file: path.join(path.dirname(applicationFile), `${owner}.db`) });
+        }
+        return sources;
+    }
+    /** Put a staged restore in place, before any database opens; loud when it cannot. */
+    applyRestoreAtStart(file) {
+        const dir = path.resolve(path.dirname(file));
+        const allowed = (live) => {
+            const resolved = path.resolve(live);
+            if (resolved === path.resolve(file))
+                return true;
+            const name = path.basename(resolved);
+            return path.dirname(resolved) === dir && name.endsWith('.db') && ADDON_SLUG.test(name.slice(0, -3));
+        };
+        const outcome = applyStagedRestore(file, allowed);
+        if (!outcome)
+            return;
+        this.restoreAtStart = outcome;
+        if (outcome.refused) {
+            const reason = `A staged database restore was NOT applied: ${outcome.refused}. The site started on its current databases (#1723)`;
+            logger.error(`[DatabaseManager] ${reason}`);
+            this.fault('restore', reason);
+            return;
+        }
+        for (const a of outcome.applied) {
+            logger.warn(`[DatabaseManager] Restore applied: ${a.name} -> ${a.live} (previous kept as ${path.basename(a.kept)}) (#1723)`);
+        }
+    }
+    backupKey() {
+        return (process.env[BACKUP_KEY_ENV] ?? '').trim();
+    }
+    /** What is wrong with the backup key: missing, or the database key itself (D3). Null when sound. */
+    backupKeyProblem() {
+        const backupKey = this.backupKey();
+        if (!backupKey)
+            return `${BACKUP_KEY_ENV} is not set, so no database is backed up — set it in the environment or the instance .env (#1723)`;
+        const key = process.env[DATABASE_KEY_ENV] ?? '';
+        if (key && key.trim() === backupKey) {
+            return `${BACKUP_KEY_ENV} is the same as ${DATABASE_KEY_ENV}: a stolen backup and a stolen data disk then fall to one secret — give the backups a key of their own (#1723)`;
+        }
+        return null;
+    }
+    /** `ngdpbase.database.backup.worker-timeout-ms`, read at use. */
+    workerTimeoutMs() {
+        const configured = this.engine.getManager('ConfigurationManager')
+            ?.getProperty('ngdpbase.database.backup.worker-timeout-ms', DEFAULT_BACKUP_WORKER_TIMEOUT_MS) ?? DEFAULT_BACKUP_WORKER_TIMEOUT_MS;
+        if (typeof configured !== 'number' || !Number.isInteger(configured) || configured <= 0) {
+            throw new Error(`ngdpbase.database.backup.worker-timeout-ms must be a whole number of milliseconds, more than 0 — got ${JSON.stringify(configured)} (#1723)`);
+        }
+        return configured;
+    }
+    /** Degrade for one cause; the dashboard shows every cause still standing. */
+    fault(cause, reason) {
+        this.faults.set(cause, reason);
+        this.markDegraded([...this.faults.values()].join('; '));
+    }
+    clearFault(cause) {
+        if (!this.faults.delete(cause))
+            return;
+        if (this.faults.size === 0)
+            this.markReady();
+        else
+            this.markDegraded([...this.faults.values()].join('; '));
+    }
+    async notify(level, title, message) {
+        try {
+            await this.engine.getManager('NotificationManager')
+                ?.addNotification({ type: 'system', level, title, message });
+        }
+        catch (err) {
+            logger.error(`[DatabaseManager] The notification '${title}' could not be sent (#1723):`, err);
+        }
     }
     /** Whether every open database passes SQLite's quick check; true when none is configured. */
     integrityOk() {

package/lib/src/providers/sqliteBackup.d.ts

@@ -0,0 +1,128 @@
+import type DatabaseConstructor from 'better-sqlite3-multiple-ciphers';
+/**
+ * The SQLite driver, handed in rather than imported: the worker loads it from
+ * the file the site's own thread resolved (`job.driver`), so both threads use
+ * the same native module, and a worker run from source (tsx) is not sent to
+ * the type declarations tsconfig's `paths` maps the package name to.
+ */
+export type Driver = typeof DatabaseConstructor;
+/** One database to copy into a backup: where it is, the key it opens under ('' = plaintext), and the backup file to write. */
+export interface DatabaseExport {
+    name: string;
+    source: string;
+    sourceKey: string;
+    target: string;
+}
+export interface ExportOutcome {
+    written: Array<{
+        name: string;
+        target: string;
+        sizeBytes: number;
+        tables: number;
+    }>;
+    /** Databases that could not be copied; the others still are. Each is named, never dropped silently. */
+    failed: Array<{
+        name: string;
+        error: string;
+    }>;
+}
+/** One database to stage from a backup: the backup's file, and the live file it will replace at the next start. */
+export interface DatabaseStage {
+    name: string;
+    backupFile: string;
+    live: string;
+    targetKey: string;
+}
+export interface StageOutcome {
+    staged: Array<{
+        name: string;
+        staged: string;
+        live: string;
+        tables: number;
+    }>;
+}
+export type SqliteBackupJob = {
+    kind: 'export';
+    exports: DatabaseExport[];
+    backupKey: string;
+} | {
+    kind: 'stage';
+    stages: DatabaseStage[];
+    backupKey: string;
+};
+/** A job as the worker receives it: with the driver's resolved file. */
+export type WorkerJob = SqliteBackupJob & {
+    driver: string;
+};
+/** The staged file for a live database: beside it, so staging and applying name the same path. */
+export declare const stagedPath: (live: string) => string;
+/**
+ * Write an encrypted copy of each database under `backupKey`. A database that
+ * cannot be opened or copied is named in `failed`, its partial file removed;
+ * the others are still written. A target that already exists is never
+ * overwritten.
+ */
+export declare function exportDatabasesSync(Database: Driver, exports: DatabaseExport[], backupKey: string): ExportOutcome;
+/**
+ * Stage a restore: each backup file is opened under the backup key,
+ * integrity-checked, and copied into `<live>.staged` under the target
+ * database's key, which is then opened and checked too. All or nothing: if
+ * any database fails, every staged file is removed and the error names it.
+ * Live files are never touched.
+ */
+export declare function stageDatabasesSync(Database: Driver, stages: DatabaseStage[], backupKey: string): StageOutcome;
+/** Run a job of this module on a worker thread, so a large database never stalls requests or the liveness probe. */
+export declare function runOffThread(job: {
+    kind: 'export';
+    exports: DatabaseExport[];
+    backupKey: string;
+}, timeoutMs: number): Promise<ExportOutcome>;
+export declare function runOffThread(job: {
+    kind: 'stage';
+    stages: DatabaseStage[];
+    backupKey: string;
+}, timeoutMs: number): Promise<StageOutcome>;
+/** What a staged restore is: written last, once every database is staged; its presence is what the next start applies. */
+export interface StagedRestoreManifest {
+    version: 1;
+    stagedAt: string;
+    /** When the backup it came from was taken. */
+    backup: string;
+    /** The backup document's filename. */
+    source: string;
+    /** Who staged it: the account named by the request's context. */
+    stagedBy: string;
+    /** The backup of the live data taken just before staging (D6): what to restore to undo this one. */
+    safetyBackup?: string;
+    databases: Array<{
+        name: string;
+        live: string;
+        staged: string;
+    }>;
+}
+/** Where the manifest of a staged restore lives: beside the application database. */
+export declare const manifestPath: (applicationFile: string) => string;
+export declare function writeManifest(file: string, manifest: StagedRestoreManifest): void;
+export interface ApplyOutcome {
+    /** Databases now on the restored copy, each with where its previous file was kept. */
+    applied: Array<{
+        name: string;
+        live: string;
+        kept: string;
+    }>;
+    /** Why nothing was applied; the staged files were set aside as `*.incomplete`. */
+    refused?: string;
+}
+/**
+ * Apply a staged restore at start, before any database opens. Each live file,
+ * with its `-wal` and `-shm`, steps aside as `*.pre-restore` (`-wal`/`-shm`
+ * beside it, so the kept copy still opens as it was), and the staged file
+ * takes its name. A rename, never a write into a live database.
+ *
+ * All or nothing: if any database the manifest names is not staged, nothing
+ * is applied; what is staged is renamed `*.incomplete`, so it is neither
+ * applied nor retried. A staged file with no manifest (staging was
+ * interrupted) is set aside the same way. `allowed` says which live paths may
+ * be replaced, so a tampered manifest cannot rename an arbitrary file.
+ */
+export declare function applyStagedRestore(applicationFile: string, allowed: (live: string) => boolean): ApplyOutcome | null;