@jwilleke/ngdpbase-types 5.25.0 → 5.27.0

package/lib/src/utils/backupCrypto.js

@@ -0,0 +1,275 @@
+/**
+ * Encrypted backup files (#1561, #1876): the backup document, every file
+ * archive beside it, and the credentials store, under `NGDPBASE_BACKUP_KEY`.
+ * The database files are encrypted by SQLCipher itself (`sqliteBackup.ts`);
+ * everything else a backup writes goes through here.
+ *
+ * Format, version 1:
+ *
+ * - `NGDPBK01` (8 bytes), then a big-endian u32 length and that many bytes of
+ *   JSON header: the cipher, the key derivation (scrypt, its cost and a fresh
+ *   random salt), the backup key's fingerprint (`backupKeyFingerprint`, never
+ *   the key), an 8-byte random nonce prefix and the chunk size.
+ * - Then records: u32 plaintext length, one byte (1 on the last record, else
+ *   0), the ciphertext, and its 16-byte AES-256-GCM tag. Each record's nonce
+ *   is the prefix and its u32 index; its additional data is the SHA-256 of
+ *   the header, the index and the last-record byte. So a record moved,
+ *   dropped, swapped from another file or cut off at the end fails, and so
+ *   does any change to the header.
+ *
+ * Streamed both ways, a chunk at a time: a file's size never becomes memory.
+ * Decrypting checks the fingerprint first, so a backup made under another key
+ * is refused by name ({@link BackupKeyMismatchError}) before any work is done.
+ */
+import { createCipheriv, createDecipheriv, createHash, randomBytes, scrypt } from 'node:crypto';
+import { Readable, Transform, Writable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { backupKeyFingerprint, BACKUP_KEY_ENV } from './backupKey.js';
+import { open } from 'node:fs/promises';
+/** The first bytes of every encrypted backup file. */
+export const BACKUP_FILE_MAGIC = Buffer.from('NGDPBK01', 'ascii');
+/** What an encrypted backup file's name ends with. */
+export const ENCRYPTED_SUFFIX = '.enc';
+/** The key derivation's cost, written into each file's header so a reader uses the file's own. A format constant, not a tunable: changing it changes no file already written. */
+const KDF = { N: 16384, r: 8, p: 1 };
+const CHUNK_BYTES = 64 * 1024;
+const SALT_BYTES = 16;
+const NONCE_PREFIX_BYTES = 8;
+const TAG_BYTES = 16;
+const RECORD_HEAD = 5;
+/** The largest header a reader accepts: a header is a few hundred bytes. */
+const MAX_HEADER = 4096;
+/** A backup file made under a different backup key than the one set now. */
+export class BackupKeyMismatchError extends Error {
+    fileFingerprint;
+    keyFingerprint;
+    constructor(fileFingerprint, keyFingerprint) {
+        super(`it was made with a different backup key (fingerprint ${fileFingerprint}; ${BACKUP_KEY_ENV} now has ${keyFingerprint}). Set ${BACKUP_KEY_ENV} to the key it was made with`);
+        this.fileFingerprint = fileFingerprint;
+        this.keyFingerprint = keyFingerprint;
+        this.name = 'BackupKeyMismatchError';
+    }
+}
+function deriveKey(backupKey, salt, kdf) {
+    const options = { N: kdf.N, r: kdf.r, p: kdf.p, maxmem: 256 * kdf.N * kdf.r };
+    return new Promise((resolve, reject) => scrypt(backupKey, salt, 32, options, (err, key) => (err ? reject(err) : resolve(key))));
+}
+function nonceFor(prefix, index) {
+    const nonce = Buffer.alloc(12);
+    prefix.copy(nonce, 0, 0, 8);
+    nonce.writeUInt32BE(index, 8);
+    return nonce;
+}
+function aadFor(headerHash, index, last) {
+    const tail = Buffer.alloc(5);
+    tail.writeUInt32BE(index, 0);
+    tail.writeUInt8(last ? 1 : 0, 4);
+    return Buffer.concat([headerHash, tail]);
+}
+function requireKey(backupKey) {
+    if (!backupKey.trim())
+        throw new Error(`a backup key is required: ${BACKUP_KEY_ENV} is not set`);
+}
+/** Whether these bytes (a file's first) are an encrypted backup file. */
+export function isEncryptedBackup(head) {
+    return head.length >= BACKUP_FILE_MAGIC.length && head.subarray(0, BACKUP_FILE_MAGIC.length).equals(BACKUP_FILE_MAGIC);
+}
+/** Whether the file on disk is an encrypted backup file, read from its first bytes only. */
+export async function fileIsEncrypted(file) {
+    const handle = await open(file, 'r');
+    try {
+        const head = Buffer.alloc(BACKUP_FILE_MAGIC.length);
+        const { bytesRead } = await handle.read(head, 0, head.length, 0);
+        return isEncryptedBackup(head.subarray(0, bytesRead));
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** A stream that encrypts what is written to it under `backupKey`. */
+export function encryptStream(backupKey) {
+    requireKey(backupKey);
+    let key = null;
+    let headerHash;
+    let prefix;
+    let index = 0;
+    let pending = Buffer.alloc(0);
+    const record = (plain, last) => {
+        const cipher = createCipheriv('aes-256-gcm', key, nonceFor(prefix, index));
+        cipher.setAAD(aadFor(headerHash, index, last));
+        const ct = Buffer.concat([cipher.update(plain), cipher.final()]);
+        const head = Buffer.alloc(RECORD_HEAD);
+        head.writeUInt32BE(plain.length, 0);
+        head.writeUInt8(last ? 1 : 0, 4);
+        index++;
+        return Buffer.concat([head, ct, cipher.getAuthTag()]);
+    };
+    const start = async (stream) => {
+        if (key)
+            return;
+        const salt = randomBytes(SALT_BYTES);
+        prefix = randomBytes(NONCE_PREFIX_BYTES);
+        const header = {
+            format: 1,
+            cipher: 'aes-256-gcm',
+            kdf: { alg: 'scrypt', ...KDF, salt: salt.toString('base64') },
+            keyFingerprint: backupKeyFingerprint(backupKey),
+            noncePrefix: prefix.toString('base64'),
+            chunkBytes: CHUNK_BYTES
+        };
+        const json = Buffer.from(JSON.stringify(header), 'utf8');
+        const len = Buffer.alloc(4);
+        len.writeUInt32BE(json.length, 0);
+        const headerBytes = Buffer.concat([BACKUP_FILE_MAGIC, len, json]);
+        headerHash = createHash('sha256').update(headerBytes).digest();
+        key = await deriveKey(backupKey, salt, KDF);
+        stream.push(headerBytes);
+    };
+    return new Transform({
+        transform(chunk, _enc, done) {
+            start(this).then(() => {
+                pending = pending.length === 0 ? chunk : Buffer.concat([pending, chunk]);
+                // The last record is written at the end, so a full chunk is held back
+                // until more follows: the last-record byte is then always right.
+                while (pending.length > CHUNK_BYTES) {
+                    this.push(record(pending.subarray(0, CHUNK_BYTES), false));
+                    pending = pending.subarray(CHUNK_BYTES);
+                }
+                done();
+            }, done);
+        },
+        flush(done) {
+            start(this).then(() => {
+                this.push(record(pending, true));
+                done();
+            }, done);
+        }
+    });
+}
+/**
+ * A stream that decrypts an encrypted backup file written to it. Fails —
+ * naming why — on a file that is not one, a different backup key
+ * ({@link BackupKeyMismatchError}), any record that does not verify, and a
+ * file cut short or with bytes after its last record.
+ */
+export function decryptStream(backupKey) {
+    requireKey(backupKey);
+    let buffer = Buffer.alloc(0);
+    let header = null;
+    let headerHash;
+    let prefix;
+    let key;
+    let index = 0;
+    let ended = false;
+    const parseHeader = async () => {
+        if (buffer.length < BACKUP_FILE_MAGIC.length + 4)
+            return false;
+        if (!isEncryptedBackup(buffer))
+            throw new Error('not an encrypted backup file');
+        const len = buffer.readUInt32BE(BACKUP_FILE_MAGIC.length);
+        if (len === 0 || len > MAX_HEADER)
+            throw new Error('the encrypted backup file has a damaged header');
+        const total = BACKUP_FILE_MAGIC.length + 4 + len;
+        if (buffer.length < total)
+            return false;
+        const headerBytes = buffer.subarray(0, total);
+        let parsed;
+        try {
+            parsed = JSON.parse(headerBytes.subarray(BACKUP_FILE_MAGIC.length + 4).toString('utf8'));
+        }
+        catch {
+            throw new Error('the encrypted backup file has a damaged header');
+        }
+        // The header is not authenticated until the first record verifies, so
+        // nothing in it may set the cost of the work before that: format 1 has
+        // one key derivation cost, and a header asking for another is refused
+        // (a crafted file must not make the server run a huge scrypt).
+        const salt = typeof parsed.kdf?.salt === 'string' ? Buffer.from(parsed.kdf.salt, 'base64') : Buffer.alloc(0);
+        const noncePrefix = typeof parsed.noncePrefix === 'string' ? Buffer.from(parsed.noncePrefix, 'base64') : Buffer.alloc(0);
+        if (parsed.format !== 1 || parsed.cipher !== 'aes-256-gcm' || parsed.kdf?.alg !== 'scrypt'
+            || parsed.kdf.N !== KDF.N || parsed.kdf.r !== KDF.r || parsed.kdf.p !== KDF.p
+            || salt.length !== SALT_BYTES || noncePrefix.length !== NONCE_PREFIX_BYTES
+            || !(parsed.chunkBytes > 0 && parsed.chunkBytes <= 16 * CHUNK_BYTES)) {
+            throw new Error('the encrypted backup file is in a format this build does not read');
+        }
+        const fingerprint = backupKeyFingerprint(backupKey);
+        if (parsed.keyFingerprint !== fingerprint)
+            throw new BackupKeyMismatchError(String(parsed.keyFingerprint), fingerprint);
+        headerHash = createHash('sha256').update(headerBytes).digest();
+        prefix = noncePrefix;
+        key = await deriveKey(backupKey, salt, KDF);
+        header = parsed;
+        buffer = buffer.subarray(total);
+        return true;
+    };
+    const drain = (stream) => {
+        while (buffer.length >= RECORD_HEAD) {
+            if (ended)
+                throw new Error('the encrypted backup file has bytes after its last record');
+            const len = buffer.readUInt32BE(0);
+            const last = buffer.readUInt8(4);
+            if (len > header.chunkBytes || last > 1)
+                throw new Error('the encrypted backup file is damaged');
+            const size = RECORD_HEAD + len + TAG_BYTES;
+            if (buffer.length < size)
+                return;
+            const decipher = createDecipheriv('aes-256-gcm', key, nonceFor(prefix, index));
+            decipher.setAAD(aadFor(headerHash, index, last === 1));
+            decipher.setAuthTag(buffer.subarray(RECORD_HEAD + len, size));
+            let plain;
+            try {
+                plain = Buffer.concat([decipher.update(buffer.subarray(RECORD_HEAD, RECORD_HEAD + len)), decipher.final()]);
+            }
+            catch {
+                throw new Error('the encrypted backup file does not verify: it is damaged or was changed');
+            }
+            index++;
+            buffer = buffer.subarray(size);
+            if (last === 1)
+                ended = true;
+            if (plain.length > 0)
+                stream.push(plain);
+        }
+    };
+    return new Transform({
+        transform(chunk, _enc, done) {
+            buffer = buffer.length === 0 ? chunk : Buffer.concat([buffer, chunk]);
+            (header ? Promise.resolve(true) : parseHeader()).then((ready) => {
+                if (ready)
+                    drain(this);
+                done();
+            }).catch(done);
+        },
+        flush(done) {
+            try {
+                if (!header)
+                    throw new Error(buffer.length === 0 ? 'the encrypted backup file is empty' : 'the encrypted backup file has a damaged header');
+                drain(this);
+                if (!ended || buffer.length > 0)
+                    throw new Error('the encrypted backup file is cut short');
+                done();
+            }
+            catch (err) {
+                done(err);
+            }
+        }
+    });
+}
+async function collect(source, transform) {
+    const out = [];
+    await pipeline(Readable.from([source]), transform, new Writable({
+        write(chunk, _enc, done) {
+            out.push(chunk);
+            done();
+        }
+    }));
+    return Buffer.concat(out);
+}
+/** Encrypt a whole buffer (the backup document, already in memory). */
+export function encryptBuffer(data, backupKey) {
+    return collect(data, encryptStream(backupKey));
+}
+/** Decrypt a whole buffer. */
+export function decryptBuffer(data, backupKey) {
+    return collect(data, decryptStream(backupKey));
+}

package/lib/src/utils/backupDocument.d.ts

@@ -0,0 +1,36 @@
+/** A backup document's shape: what every backup holds at its top level. */
+export interface BackupDocument {
+    version: string;
+    timestamp: string;
+    application: string;
+    managers: Record<string, unknown>;
+}
+/** Throws, naming what is missing, when `doc` is not a backup document. */
+export declare function validateBackupDocument(doc: BackupDocument): void;
+/**
+ * The document in `bytes`, read as a restore reads it: an encrypted one only
+ * under `backupKey`, gzip by its first bytes whatever the name says.
+ *
+ * @param name - the file's name, for the messages
+ * @param options.validate - check the shape (default true)
+ */
+export declare function readBackupDocument(bytes: Buffer, backupKey: string, name: string, options?: {
+    validate?: boolean;
+}): Promise<BackupDocument>;
+/** What a read-back found: the document's timestamp and how many manager parts it holds. */
+export interface VerifiedBackup {
+    timestamp: string;
+    managers: number;
+}
+/** The worker's job: the document's bytes, the key and the name. */
+export interface VerifyJob {
+    bytes: Uint8Array;
+    backupKey: string;
+    name: string;
+}
+/**
+ * Read a backup document back on a worker thread (#1563): rejects, naming
+ * why, when it does not decrypt (a wrong key, a changed byte, a bad tag), does
+ * not decompress, does not parse, or is not a backup document.
+ */
+export declare function verifyBackupOffThread(bytes: Buffer, backupKey: string, name: string, timeoutMs: number): Promise<VerifiedBackup>;

package/lib/src/utils/backupDocument.js

@@ -0,0 +1,99 @@
+/**
+ * Reading a backup document back (#1563): decrypt it under the backup key
+ * (the GCM tag of every record is checked), decompress it, parse it, and
+ * check its shape. The one place a document is read: a restore reads it this
+ * way, and every backup is read back this way before it counts as one.
+ *
+ * `verifyBackupOffThread` does it on a worker thread, so a large document is
+ * never decrypted, unzipped and parsed on the thread that serves requests.
+ */
+import { promisify } from 'node:util';
+import zlib from 'node:zlib';
+import { Worker } from 'node:worker_threads';
+import { decryptBuffer, isEncryptedBackup } from './backupCrypto.js';
+import { BACKUP_KEY_ENV } from './backupKey.js';
+const gunzip = promisify(zlib.gunzip);
+/** Throws, naming what is missing, when `doc` is not a backup document. */
+export function validateBackupDocument(doc) {
+    if (!doc || typeof doc !== 'object')
+        throw new Error('Invalid backup: not a backup document');
+    if (!doc.version)
+        throw new Error('Invalid backup: missing version');
+    if (!doc.timestamp)
+        throw new Error('Invalid backup: missing timestamp');
+    if (!doc.managers || typeof doc.managers !== 'object')
+        throw new Error('Invalid backup: missing or invalid managers data');
+}
+/**
+ * The document in `bytes`, read as a restore reads it: an encrypted one only
+ * under `backupKey`, gzip by its first bytes whatever the name says.
+ *
+ * @param name - the file's name, for the messages
+ * @param options.validate - check the shape (default true)
+ */
+export async function readBackupDocument(bytes, backupKey, name, options = {}) {
+    let plain = bytes;
+    if (isEncryptedBackup(bytes)) {
+        if (!backupKey)
+            throw new Error(`The backup ${name} is encrypted under the backup key, and ${BACKUP_KEY_ENV} is not set`);
+        try {
+            plain = await decryptBuffer(bytes, backupKey);
+        }
+        catch (err) {
+            throw new Error(`The backup ${name} could not be read: ${err.message}`, { cause: err });
+        }
+    }
+    let json;
+    if (plain[0] === 0x1f && plain[1] === 0x8b) {
+        try {
+            json = (await gunzip(plain)).toString('utf8');
+        }
+        catch (err) {
+            throw new Error(`The backup ${name} does not decompress: ${err.message}`, { cause: err });
+        }
+    }
+    else {
+        json = plain.toString('utf8');
+    }
+    let doc;
+    try {
+        doc = JSON.parse(json);
+    }
+    catch (err) {
+        throw new Error(`The backup ${name} is not a readable document: ${err.message}`, { cause: err });
+    }
+    if (options.validate !== false)
+        validateBackupDocument(doc);
+    return doc;
+}
+/**
+ * Read a backup document back on a worker thread (#1563): rejects, naming
+ * why, when it does not decrypt (a wrong key, a changed byte, a bad tag), does
+ * not decompress, does not parse, or is not a backup document.
+ */
+export function verifyBackupOffThread(bytes, backupKey, name, timeoutMs) {
+    // Compiled, the worker is the .js beside this file. From source (vitest, tsx) it is the .ts, which needs tsx's loader.
+    const fromSource = import.meta.url.endsWith('.ts');
+    const entry = new URL(fromSource ? './backupVerifyWorker.ts' : './backupVerifyWorker.js', import.meta.url);
+    return new Promise((resolve, reject) => {
+        const workerData = { bytes, backupKey, name };
+        const worker = new Worker(entry, { workerData, ...(fromSource ? { execArgv: ['--import', 'tsx'] } : {}) });
+        let settled = false;
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            fn();
+        };
+        const timer = setTimeout(() => {
+            settle(() => reject(new Error(`reading the backup ${name} back did not finish within ${timeoutMs} ms (ngdpbase.backup.verify-timeout-ms)`)));
+            void worker.terminate();
+        }, timeoutMs);
+        worker.once('message', (m) => {
+            settle(() => (m.ok ? resolve(m.result) : reject(new Error(m.error))));
+        });
+        worker.once('error', (err) => settle(() => reject(err)));
+        worker.once('exit', (code) => settle(() => reject(new Error(`the backup read-back worker exited (code ${code}) without a result`))));
+    });
+}

package/lib/src/utils/browserDescription.d.ts

@@ -0,0 +1,11 @@
+/**
+ * #1532 — a browser and the kind of device it runs on, in words a person
+ * recognises ("Chrome on Windows"), from a User-Agent header. Used where a
+ * person is asked to judge a request someone made: the sign-in approval
+ * message and page. The rules are the ones `suggestedName()` in
+ * `public/js/passkey.js` applies in the browser, so a passkey's suggested name
+ * and an approval request describe the same device the same way.
+ *
+ * Null when the header names neither a browser nor a device we know.
+ */
+export declare function describeBrowser(userAgent: string | undefined): string | null;

package/lib/src/utils/directoryBackup.d.ts

@@ -1,15 +1,7 @@
-import type { BackupData, ManagerBackupOptions, ManagerRestoreOptions } from '../managers/BaseManager.js';
-import { siteRestoreFile, type PartOutcome } from './siteRestore.js';
-/** A folder part's `data` in the backup document. */
-export interface DirectoryBackupData {
-    format: 1;
-    /** The archive beside the document: `<stem>.<part>.tar`, or `.tar.enc` when encrypted. */
-    archive: string;
-    files: number;
-    bytes: number;
-    /** `backupKeyFingerprint()` of the key the archive is encrypted under; absent when it is not encrypted. */
-    keyFingerprint?: string;
-}
+import type { BackupArchiveTarget, BackupData, BackupFolder, BackupPartRecord, ManagerBackupOptions, ManagerRestoreOptions, StagedRestoreAtStart } from '../managers/BaseManager.js';
+import { siteRestoreFile } from './siteRestore.js';
+/** A folder or file part's record in the backup document (the name every backup since v5.21 used). */
+export type DirectoryBackupData = BackupPartRecord;
 /** Whether `name` is a bare archive name in the backup directory, never a path. */
 export declare function isArchiveName(name: unknown): name is string;
 /**
@@ -31,50 +23,58 @@ export declare function archiveTarget(stem: string, part: string): {
 export declare function archiveReadKey(manager: string, data: {
     keyFingerprint?: string;
 }): string | undefined;
+/** `ManagerBackupOptions.archive`: one more archive beside the document, for a manager whose files are not a declared part. */
+export declare function archiveWriter(directory: string, stem: string): (part: string) => BackupArchiveTarget;
+/** `ManagerRestoreOptions.readArchive`: an archive the backup names, checked, and the key to read it under. */
+export declare function archiveReader(directory: string): NonNullable<ManagerRestoreOptions['readArchive']>;
+/** The live path a declared part names: its folder or its file. */
+export declare function livePathOf(part: BackupFolder): string | null;
+/** What backing up a manager's declared parts wrote: each part's record (null when left out), and what to tell admins. */
+export interface DeclaredPartsBackup {
+    records: Record<string, BackupPartRecord | null>;
+    warnings: string[];
+    notes: string[];
+}
 /**
- * Back the folder up beside the document BackupManager is writing. Throws
- * outside BackupManager: the files go beside a document, never into it.
- * `exclude` leaves out a path relative to the folder (posix form).
- */
-export declare function backupDirectoryPart(manager: string, part: string, folder: string | null, options?: ManagerBackupOptions, extra?: {
-    exclude?: (relative: string) => boolean;
-}): Promise<BackupData>;
-/** The log's note of entries deleted while they were backed up (#1563): skipped, not a failure. */
-export declare function vanishedNote(vanished: string[]): string;
-/**
- * Stage the folder from a backup for the next start: the archive is
- * extracted to `<folder>.staged`, and the swap recorded in the site restore.
- * Throws — staging nothing — outside a site restore, for a backup without
- * this part, or for an archive that is missing, unsafe, or under another key.
+ * Back up a manager's declared parts beside the document BackupManager is
+ * writing. Throws outside BackupManager: the files go beside a document,
+ * never into it. A part that fails throws, and the manager's entry is then
+ * an error, as when its own `backup()` throws.
  */
-export declare function stageDirectoryPart(manager: string, folder: string | null, backupData: BackupData, options?: ManagerRestoreOptions): Promise<void>;
+export declare function backupDeclaredParts(manager: string, declared: BackupFolder[], options: ManagerBackupOptions | undefined): Promise<DeclaredPartsBackup>;
 /**
- * Put a staged restore of the folder in place, at start, before the manager
- * reads it. Loud when something was staged but not applied.
+ * Put the declared parts' records into a manager's entry, in the shape
+ * every backup has had: the entry's `data` is the record when the manager
+ * has no data of its own and declares one part (roles, persons, …, an
+ * add-on's folder); otherwise each record is `data[<part>]` beside the
+ * manager's own data (the credentials store beside the provider list).
  */
-export declare function applyDirectoryPartAtStart(manager: string, folder: string, configManager: Parameters<typeof siteRestoreFile>[0]): PartOutcome | null;
+export declare function placePartRecords(entry: BackupData, declared: BackupFolder[], parts: DeclaredPartsBackup): BackupData;
+/** A declared part's record in a manager's entry, read the way `placePartRecords` wrote it. */
+export declare function partRecordIn(entry: BackupData | undefined, declared: BackupFolder[], part: string): unknown;
 /**
- * Back one file up beside the document, encrypted under the backup key, as
- * `<stem>.<part>.tar.enc`. With `requireKey` and no key the file is left out:
- * `data` is null and a warning says why, so BackupManager reports the backup
- * incomplete (#1876: the credentials store is never in a backup unencrypted).
+ * Stage a manager's declared parts from its entry in a backup, for the next
+ * start: each archive is extracted to `<path>.staged`, and the swaps are
+ * recorded in the site restore together. Throws — staging nothing, and
+ * removing what it extracted — outside a site restore, for a backup without
+ * a part that is not optional, or for an archive that is missing, unsafe,
+ * or under another key. Returns the parts the backup left out.
  */
-export declare function backupFilePart(manager: string, part: string, file: string | null, options: ManagerBackupOptions | undefined, { requireKey, what }: {
-    requireKey: boolean;
-    what: string;
-}): Promise<{
-    data: DirectoryBackupData | null;
-    warnings: string[];
-    note?: string;
+export declare function stageDeclaredParts(manager: string, declared: BackupFolder[], entry: BackupData | undefined, options: ManagerRestoreOptions | undefined): Promise<{
+    leftOut: string[];
 }>;
 /**
- * Stage one file from a backup as `<file>.staged`, and record the swap. When
- * the file was absent at backup time the archive holds nothing, and
- * `whenAbsent` is staged in its place (an empty store), so the restore still
- * puts the site back as it was.
+ * Stage one file from a backup for the next start and record the swap: the
+ * instance `.env`, BackupManager's own part.
  */
-export declare function stageFilePart(manager: string, file: string, data: DirectoryBackupData, options: ManagerRestoreOptions | undefined, { whenAbsent }: {
+export declare function stageFilePart(manager: string, file: string, data: BackupPartRecord, options: ManagerRestoreOptions | undefined, { whenAbsent }: {
     whenAbsent: string;
 }): Promise<void>;
-/** Put a staged restore of one file in place, at start, before the manager reads it. */
-export declare function applyFilePartAtStart(manager: string, file: string, configManager: Parameters<typeof siteRestoreFile>[0]): PartOutcome | null;
+/**
+ * Put a staged restore of a manager's declared parts in place, at start,
+ * before the manager reads them. Only the paths it declares may be
+ * replaced, whatever the manifest says; a staged copy no committed restore
+ * names (an interrupted staging) is set aside. Loud when something was
+ * staged but not applied. Null when there was nothing to do.
+ */
+export declare function applyDeclaredPartsAtStart(manager: string, declared: BackupFolder[], configManager: Parameters<typeof siteRestoreFile>[0]): StagedRestoreAtStart | null;