@jwilleke/ngdpbase-types 5.25.0 → 5.26.0

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;

package/lib/src/utils/directoryBackup.js

@@ -0,0 +1,291 @@
+/**
+ * BackupManager's folder and file parts (#1876, #1985). Imported by
+ * BackupManager alone (`scripts/check-backup-boundary.ts`): a manager
+ * declares where its data lives (`BaseManager.backupFolders()`), an add-on's
+ * `dataPath` counts for it, and BackupManager does the rest through here.
+ *
+ * - __Backup__: each declared folder is written as `<stem>.<part>.tar` beside
+ *   the backup document (`treeArchive.ts`), streamed, bytes as stored, and
+ *   the manager's entry records it. With `NGDPBASE_BACKUP_KEY` set it is
+ *   encrypted under it (#1561) and named `<stem>.<part>.tar.enc`. A declared
+ *   file is the same with the one file in the archive; one that requires the
+ *   key is left out without it (the credentials store).
+ * - __Restore__: each part's archive is extracted beside the live path, as
+ *   `<path>.staged`, and the swaps are recorded in the site restore
+ *   manifest. Nothing is written into the live data.
+ * - __At start__: the staged copy is put in place before the owner reads it,
+ *   when the whole site restore is there to apply (`siteRestore.ts`), and
+ *   only for the paths the owner declares.
+ *
+ * The archive names and the entry shapes are those every backup since
+ * v5.21 has (#1985 keeps them), so a backup made before the declarations
+ * restores, and one made after can be restored by v5.25.0.
+ */
+import { existsSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import logger from './logger.js';
+import { extractTreeArchive, vanishedNote, writeTreeArchive } from './treeArchive.js';
+import { applyPartAtStart, readSiteRestore, siteRestoreFile, stagedPathFor } from './siteRestore.js';
+import { BACKUP_KEY_ENV, backupKeyFingerprint, currentBackupKey, LEFT_OUT_FOR_NO_KEY } from './backupKey.js';
+import { ENCRYPTED_SUFFIX } from './backupCrypto.js';
+/** Whether `name` is a bare archive name in the backup directory, never a path. */
+export function isArchiveName(name) {
+    return typeof name === 'string' && (name.endsWith('.tar') || name.endsWith(`.tar${ENCRYPTED_SUFFIX}`)) && path.basename(name) === name && !name.startsWith('.');
+}
+/**
+ * The name and key for one archive of a backup: encrypted under the backup
+ * key when it is set (#1561), plain otherwise. BackupManager says, once per
+ * backup, that a backup without the key is not encrypted.
+ */
+export function archiveTarget(stem, part) {
+    const key = currentBackupKey();
+    if (!key)
+        return { archive: `${stem}.${part}.tar` };
+    return { archive: `${stem}.${part}.tar${ENCRYPTED_SUFFIX}`, backupKey: key, keyFingerprint: backupKeyFingerprint(key) };
+}
+/**
+ * The key to read an archive of a backup with, checked against the
+ * fingerprint the backup recorded: a backup made under another key is
+ * refused before anything is staged. None for a backup that was not
+ * encrypted, which is then read as the plain archive it says it is.
+ */
+export function archiveReadKey(manager, data) {
+    if (!data.keyFingerprint)
+        return undefined;
+    const key = currentBackupKey();
+    if (!key)
+        throw new Error(`${manager}'s files in this backup are encrypted under the backup key, and ${BACKUP_KEY_ENV} is not set; nothing was staged`);
+    const now = backupKeyFingerprint(key);
+    if (now !== data.keyFingerprint) {
+        throw new Error(`${manager}'s files in this backup were made with a different backup key (fingerprint ${data.keyFingerprint}; ${BACKUP_KEY_ENV} now has ${now}). Set ${BACKUP_KEY_ENV} to the key it was made with; nothing was staged`);
+    }
+    return key;
+}
+/** `ManagerBackupOptions.archive`: one more archive beside the document, for a manager whose files are not a declared part. */
+export function archiveWriter(directory, stem) {
+    return (part) => {
+        const target = archiveTarget(stem, part);
+        return { ...target, path: path.join(directory, target.archive) };
+    };
+}
+/** `ManagerRestoreOptions.readArchive`: an archive the backup names, checked, and the key to read it under. */
+export function archiveReader(directory) {
+    return (manager, archive, keyFingerprint) => {
+        if (!isArchiveName(archive)) {
+            throw new Error(`The backup names ${manager}'s archive '${String(archive)}', which is not a file in the backup directory; nothing was staged`);
+        }
+        return { path: path.join(directory, archive), backupKey: archiveReadKey(manager, { keyFingerprint }) };
+    };
+}
+function requireBackupManager(manager, options) {
+    if (!options?.directory || !options.stem) {
+        throw new Error(`${manager} writes its files beside the backup document, so it is backed up through BackupManager (#1876)`);
+    }
+}
+function isFilePart(part) {
+    return 'file' in part;
+}
+/** The live path a declared part names: its folder or its file. */
+export function livePathOf(part) {
+    return isFilePart(part) ? part.file : part.folder;
+}
+/**
+ * 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 async function backupDeclaredParts(manager, declared, options) {
+    requireBackupManager(manager, options);
+    const out = { records: {}, warnings: [], notes: [] };
+    for (const part of declared) {
+        if (isFilePart(part))
+            await backupFilePart(manager, part, options, out);
+        else
+            await backupFolderPart(manager, part, options, out);
+    }
+    return out;
+}
+async function backupFolderPart(manager, part, options, out) {
+    if (!part.folder) {
+        out.records[part.part] = null;
+        out.notes.push(`${manager} has no folder configured`);
+        return;
+    }
+    const target = archiveTarget(options.stem, part.part);
+    const outcome = await writeTreeArchive(path.join(options.directory, target.archive), part.folder, { backupKey: target.backupKey, exclude: part.exclude });
+    out.records[part.part] = { format: 1, archive: target.archive, files: outcome.files, bytes: outcome.bytes, ...(target.keyFingerprint ? { keyFingerprint: target.keyFingerprint } : {}) };
+    const warnings = outcome.skipped.map((s) => `${s} in ${part.folder} is not a file or a folder, so it was left out`);
+    for (const w of warnings)
+        logger.error(`[${manager}] ${w}`);
+    out.warnings.push(...warnings);
+    logger.info(`[${manager}] Backed up ${outcome.files} file(s), ${(outcome.bytes / 1024).toFixed(1)} KB, as ${target.archive} (#1876)${vanishedNote(outcome.vanished)}`);
+}
+/**
+ * One file, encrypted under the backup key, as `<stem>.<part>.tar.enc`. With
+ * `requireKey` and no key the file is left out: its record is null and a
+ * warning says why (#1876: the credentials store is never in a backup
+ * unencrypted).
+ */
+async function backupFilePart(manager, part, options, out) {
+    if (!part.file) {
+        out.records[part.part] = null;
+        out.notes.push(`${manager} has no ${part.what} configured`);
+        return;
+    }
+    const target = archiveTarget(options.stem, part.part);
+    if (part.requireKey && !target.backupKey) {
+        const warning = `${LEFT_OUT_FOR_NO_KEY}the ${part.what} was left out: it is only ever backed up encrypted under the backup key (#1876)`;
+        logger.error(`[${manager}] ${warning}`);
+        out.records[part.part] = null;
+        out.warnings.push(warning);
+        return;
+    }
+    const entries = existsSync(part.file) ? [path.basename(part.file)] : [];
+    const outcome = await writeTreeArchive(path.join(options.directory, target.archive), path.dirname(part.file), { backupKey: target.backupKey, entries });
+    logger.info(`[${manager}] Backed up the ${part.what} (${outcome.files} file, ${(outcome.bytes / 1024).toFixed(1)} KB) as ${target.archive} (#1876)${vanishedNote(outcome.vanished)}`);
+    out.records[part.part] = { format: 1, archive: target.archive, files: outcome.files, bytes: outcome.bytes, ...(target.keyFingerprint ? { keyFingerprint: target.keyFingerprint } : {}) };
+}
+/**
+ * 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 function placePartRecords(entry, declared, parts) {
+    const own = entry.data;
+    const data = declared.length === 1 && (own === null || own === undefined)
+        ? parts.records[declared[0].part] ?? null
+        : { ...(own && typeof own === 'object' ? own : {}), ...parts.records };
+    const warnings = [...(entry.warnings ?? []), ...parts.warnings];
+    const note = [entry.note, ...parts.notes].filter(Boolean).join('; ');
+    return { ...entry, data, ...(warnings.length > 0 ? { warnings } : {}), ...(note ? { note } : {}) };
+}
+/** A declared part's record in a manager's entry, read the way `placePartRecords` wrote it. */
+export function partRecordIn(entry, declared, part) {
+    const data = entry?.data;
+    if (declared.length === 1 && isPartRecord(data))
+        return data;
+    return data && typeof data === 'object' ? data[part] : undefined;
+}
+function isPartRecord(value) {
+    return Boolean(value) && typeof value === 'object' && value.format === 1 && 'archive' in value;
+}
+function requireSiteRestore(manager, options) {
+    if (!options?.siteRestore || !options.directory) {
+        throw new Error(`${manager}'s restore is staged with the rest of the site, so it is restored through BackupManager (#1876)`);
+    }
+}
+/** The archive a part's record names, checked: format, a bare name, and the key it needs. */
+function readablePart(manager, record) {
+    if (!isPartRecord(record)) {
+        throw new Error(`The backup holds no ${manager} files (it was taken before they were backed up, #1876); nothing was staged`);
+    }
+    if (!isArchiveName(record.archive)) {
+        throw new Error(`The backup names ${manager}'s archive '${String(record.archive)}', which is not a file in the backup directory; nothing was staged`);
+    }
+    return { data: record, backupKey: archiveReadKey(manager, record) };
+}
+/**
+ * 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 async function stageDeclaredParts(manager, declared, entry, options) {
+    requireSiteRestore(manager, options);
+    const swaps = [];
+    const leftOut = [];
+    try {
+        for (const part of declared) {
+            const record = partRecordIn(entry, declared, part.part);
+            const live = livePathOf(part);
+            if (!isPartRecord(record) && (part.optional || isFilePart(part))) {
+                logger.warn(`[${manager}] The backup holds no ${part.part} part (left out when it was taken); this site's is kept, and named as not restored (#1876)`);
+                leftOut.push(part.part);
+                continue;
+            }
+            if (!live)
+                throw new Error(`${manager} has no ${isFilePart(part) ? part.what : 'folder'} configured; nothing was staged`);
+            const { data, backupKey } = readablePart(manager, record);
+            const staged = stagedPathFor(live);
+            swaps.push({ live, staged });
+            if (isFilePart(part))
+                await stageOneFile(live, path.join(options.directory, data.archive), backupKey, part.whenAbsent);
+            else
+                await extractTreeArchive(path.join(options.directory, data.archive), staged, { backupKey });
+        }
+        if (swaps.length > 0)
+            options.siteRestore.record(swaps);
+    }
+    catch (err) {
+        for (const s of swaps)
+            rmSync(s.staged, { recursive: true, force: true });
+        throw err;
+    }
+    for (const s of swaps)
+        logger.warn(`[${manager}] ${path.basename(s.live)} staged as ${path.basename(s.staged)} — applied at the next start with the rest of the site restore (#1876)`);
+    return { leftOut };
+}
+/**
+ * One file from its archive as `<file>.staged`. 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.
+ */
+async function stageOneFile(file, archive, backupKey, whenAbsent) {
+    const staged = stagedPathFor(file);
+    const tmp = `${staged}.extract`;
+    try {
+        const name = path.basename(file);
+        const { files } = await extractTreeArchive(archive, tmp, { backupKey, select: (rel) => rel === name });
+        rmSync(staged, { force: true });
+        if (files === 1)
+            renameSync(path.join(tmp, name), staged);
+        else
+            writeFileSync(staged, whenAbsent, { mode: 0o600 });
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+}
+/**
+ * Stage one file from a backup for the next start and record the swap: the
+ * instance `.env`, BackupManager's own part.
+ */
+export async function stageFilePart(manager, file, data, options, { whenAbsent }) {
+    await stageDeclaredParts(manager, [{ part: 'file', file, what: path.basename(file), whenAbsent }], { managerName: manager, timestamp: '', data }, options);
+}
+/**
+ * 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 function applyDeclaredPartsAtStart(manager, declared, configManager) {
+    const lives = declared.map(livePathOf).filter((p) => Boolean(p)).map((p) => path.resolve(p));
+    if (lives.length === 0)
+        return null;
+    const file = siteRestoreFile(configManager);
+    let backupTakenAt;
+    try {
+        const manifest = readSiteRestore(file);
+        if (manifest?.state === 'staged' && manifest.parts.some((p) => p.manager === manager && !p.status))
+            backupTakenAt = manifest.backup;
+    }
+    catch { /* the gate below says so */ }
+    const outcome = applyPartAtStart(file, manager, {
+        allowed: (swap) => lives.includes(path.resolve(swap.live)),
+        strays: () => lives.map(stagedPathFor).filter((p) => existsSync(p))
+    });
+    if (!outcome)
+        return null;
+    if (outcome.refused)
+        logger.error(`[${manager}] A staged restore was NOT applied: ${outcome.refused} (#1876)`);
+    for (const a of outcome.applied)
+        logger.warn(`[${manager}] Restore applied: ${a.live} (previous kept as ${path.basename(a.kept)}) (#1876)`);
+    return { ...outcome, ...(backupTakenAt ? { backupTakenAt } : {}) };
+}

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

@@ -0,0 +1,46 @@
+/** The part's name in the site restore manifest: BackupManager owns the `.env` part. */
+export declare const INSTANCE_ENV_PART = "BackupManager";
+/** The lines a restore keeps from the live file, never from the backup. */
+export declare const KEPT_ON_RESTORE: readonly string[];
+/** The instance `.env`: the one file ngdpbase writes generated secrets into (#1194). */
+export declare function instanceEnvPath(instanceDataDir: string): string;
+/**
+ * The names the instance `.env` sets, sorted, read the way the boot loads it
+ * (`dotenv.parse`, `bootstrap-env.ts`): never a value (#1976).
+ */
+export declare function envKeyNames(content: string): string[];
+/** A short fingerprint of a set of `.env` names (#1976): the first 16 hex digits of a SHA-256 of the sorted names, one per line. */
+export declare function envKeyNamesFingerprint(names: readonly string[]): string;
+/** The file without any line assigning one of `names`. */
+export declare function withoutAssignments(content: string, names: readonly string[]): string;
+/** What goes into a backup: the file without the backup key's line. */
+export declare function envForBackup(content: string): string;
+/**
+ * The file a restore puts in place: the backup's, without the kept names,
+ * then the live file's lines for them (a name the live file does not set
+ * stays unset).
+ */
+export declare function mergeRestoredEnv(restored: string, live: string): string;
+/**
+ * The site restore manifest's path, read before the configuration exists:
+ * `ngdpbase.backup.restore-manifest` from the custom file, else the shipped
+ * default, with `${FAST_STORAGE}` (and `./data`) resolved to the instance data
+ * folder and `${SLOW_STORAGE}` to its variable — as `getResolvedDataPath`
+ * resolves it once the configuration is loaded.
+ */
+export declare function siteRestoreFileAtBoot(instanceDataDir: string, env?: Record<string, string | undefined>, cwd?: string): string;
+export interface EnvRestoreOutcome {
+    /** The file before and after, when the restore was applied: the boot reloads the environment from them. */
+    applied?: {
+        before: string;
+        after: string;
+    };
+    refused?: string;
+}
+/**
+ * Put a staged `.env` in place at the start of the process, when the whole
+ * site restore is there to apply (`siteRestore.ts`). The live file is kept as
+ * `.env.pre-restore`; the kept lines are carried over first. Null when there
+ * is nothing to do.
+ */
+export declare function applyInstanceEnvAtStart(instanceDataDir: string, siteFile: string): EnvRestoreOutcome | null;

package/lib/src/utils/instanceEnvBackup.js

@@ -0,0 +1,120 @@
+/**
+ * The instance `.env` in a backup, and its staged restore (#1876, operator
+ * plan "one thing to save", 2026-10-20).
+ *
+ * `<FAST_STORAGE>/.env` holds the keys the site made for itself and the ones
+ * the operator put there: the database key, the credentials key, the session
+ * secret, the OpenID Connect keys, mail and add-on secrets. A backup carries
+ * it, encrypted under the backup key, __without the backup key's own line__:
+ * that one key is what the operator saves off the server, and a backup that
+ * held it would hold the key to itself.
+ *
+ * A restore stages it as `<FAST_STORAGE>/.env.staged` with the rest of the
+ * site restore. It is applied at the very start of the process
+ * (`bootstrap-env.ts`), before the file is loaded, because every key in it is
+ * read from the environment from then on. Two lines are always kept from the
+ * live file, never taken from the backup:
+ *
+ * - `NGDPBASE_BACKUP_KEY` — the key this site's backups are made under;
+ * - `NGDPBASE_DATABASE_KEY` — the restored databases are staged under the
+ *   site's own database key (`DatabaseManager.restore`), so the key they open
+ *   with is the live one.
+ *
+ * Everything here is synchronous and depends on nothing but the filesystem:
+ * it runs before the logger, the configuration or any manager exists.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import dotenv from 'dotenv';
+import { BACKUP_KEY_ENV } from './backupKey.js';
+import { DATABASE_KEY_ENV } from './databaseKey.js';
+import { configFilePaths, readConfigFilesSync } from './configFiles.js';
+import { applyPartAtStart, gatePart, SITE_RESTORE_MANIFEST_KEY, stagedPathFor } from './siteRestore.js';
+/** The part's name in the site restore manifest: BackupManager owns the `.env` part. */
+export const INSTANCE_ENV_PART = 'BackupManager';
+/** The lines a restore keeps from the live file, never from the backup. */
+export const KEPT_ON_RESTORE = [BACKUP_KEY_ENV, DATABASE_KEY_ENV];
+/** The instance `.env`: the one file ngdpbase writes generated secrets into (#1194). */
+export function instanceEnvPath(instanceDataDir) {
+    return path.join(instanceDataDir, '.env');
+}
+/**
+ * The names the instance `.env` sets, sorted, read the way the boot loads it
+ * (`dotenv.parse`, `bootstrap-env.ts`): never a value (#1976).
+ */
+export function envKeyNames(content) {
+    return Object.keys(dotenv.parse(content)).sort();
+}
+/** A short fingerprint of a set of `.env` names (#1976): the first 16 hex digits of a SHA-256 of the sorted names, one per line. */
+export function envKeyNamesFingerprint(names) {
+    return createHash('sha256').update([...names].sort().join('\n')).digest('hex').slice(0, 16);
+}
+function assigns(line, names) {
+    const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line);
+    return m !== null && names.includes(m[1]);
+}
+/** The file without any line assigning one of `names`. */
+export function withoutAssignments(content, names) {
+    return content.split('\n').filter((line) => !assigns(line, names)).join('\n');
+}
+/** What goes into a backup: the file without the backup key's line. */
+export function envForBackup(content) {
+    return withoutAssignments(content, [BACKUP_KEY_ENV]);
+}
+/**
+ * The file a restore puts in place: the backup's, without the kept names,
+ * then the live file's lines for them (a name the live file does not set
+ * stays unset).
+ */
+export function mergeRestoredEnv(restored, live) {
+    const kept = live.split('\n').filter((line) => assigns(line, KEPT_ON_RESTORE));
+    const body = withoutAssignments(restored, KEPT_ON_RESTORE).replace(/\n*$/, '\n');
+    return kept.length === 0 ? body : `${body}# Kept from this site when a backup was restored (#1876): the backup key, and the database key the restored databases were staged under.\n${kept.join('\n')}\n`;
+}
+/**
+ * The site restore manifest's path, read before the configuration exists:
+ * `ngdpbase.backup.restore-manifest` from the custom file, else the shipped
+ * default, with `${FAST_STORAGE}` (and `./data`) resolved to the instance data
+ * folder and `${SLOW_STORAGE}` to its variable — as `getResolvedDataPath`
+ * resolves it once the configuration is loaded.
+ */
+export function siteRestoreFileAtBoot(instanceDataDir, env = process.env, cwd = process.cwd()) {
+    let value = '${FAST_STORAGE}/site-restore.json';
+    try {
+        const files = readConfigFilesSync(configFilePaths({ ...env, FAST_STORAGE: instanceDataDir }, cwd));
+        const configured = files.customConfig[SITE_RESTORE_MANIFEST_KEY] ?? files.defaultConfig?.[SITE_RESTORE_MANIFEST_KEY];
+        if (typeof configured === 'string' && configured.trim())
+            value = configured.trim();
+    }
+    catch { /* a configuration that can't be read: the default, as the boot will find out itself */ }
+    const resolved = value
+        .replace(/^\$\{(FAST_STORAGE|INSTANCE_DATA_FOLDER)\}/, instanceDataDir)
+        .replace(/^\$\{SLOW_STORAGE\}/, env.SLOW_STORAGE ?? instanceDataDir)
+        .replace(/^\.\/data(?=\/|$)/, instanceDataDir);
+    return resolved.includes('${') ? path.join(instanceDataDir, path.basename(resolved)) : resolved;
+}
+/**
+ * Put a staged `.env` in place at the start of the process, when the whole
+ * site restore is there to apply (`siteRestore.ts`). The live file is kept as
+ * `.env.pre-restore`; the kept lines are carried over first. Null when there
+ * is nothing to do.
+ */
+export function applyInstanceEnvAtStart(instanceDataDir, siteFile) {
+    const live = instanceEnvPath(instanceDataDir);
+    const staged = stagedPathFor(live);
+    const gate = gatePart(siteFile, INSTANCE_ENV_PART);
+    const before = existsSync(live) ? readFileSync(live, 'utf8') : '';
+    if (gate.decision === 'apply' && gate.part.swaps.length === 1 && path.resolve(gate.part.swaps[0].live) === path.resolve(live) && existsSync(staged)) {
+        writeFileSync(staged, mergeRestoredEnv(readFileSync(staged, 'utf8'), before), { mode: 0o600 });
+    }
+    const outcome = applyPartAtStart(siteFile, INSTANCE_ENV_PART, {
+        allowed: (swap) => path.resolve(swap.live) === path.resolve(live),
+        strays: () => (existsSync(staged) ? [staged] : [])
+    });
+    if (!outcome)
+        return null;
+    if (outcome.refused)
+        return { refused: outcome.refused };
+    return { applied: { before, after: existsSync(live) ? readFileSync(live, 'utf8') : '' } };
+}

package/lib/src/utils/instanceEnvSecret.js

@@ -0,0 +1,79 @@
+/**
+ * A secret that must be defined in the instance `.env`, generated once when
+ * nothing supplies it (#1194, generalised for #1524).
+ *
+ * The session secret was the first; the credentials-store key is the second.
+ * Both follow one rule, so it is written once:
+ *
+ * 1. Set in the environment — use it, write nothing.
+ * 2. Blank in the environment, but the instance `.env` has a usable line — use
+ *    that (a launcher passing `NAME=` empty would otherwise regenerate on every
+ *    boot).
+ * 3. Otherwise generate, append one commented line to `<instanceDataDir>/.env`
+ *    (created `0600` when new), and use it.
+ *
+ * The repo-root `.env` is never written: it is shared by every instance that
+ * launches from the checkout.
+ */
+import fs from 'fs';
+import path from 'path';
+import { randomBytes } from 'crypto';
+export function ensureInstanceEnvSecret(spec, env, instanceDataDir, fs) {
+    const accept = spec.accept ?? ((v) => v);
+    const ambient = (env[spec.name] ?? '').trim();
+    if (ambient !== '')
+        return { secret: accept(ambient), origin: { kind: 'env' } };
+    const envPath = `${instanceDataDir.replace(/\/+$/, '')}/.env`;
+    const existing = fs.readFile(envPath);
+    if (existing !== null) {
+        const fromFile = readEnvLine(existing, spec.name);
+        if (fromFile !== null)
+            return { secret: accept(fromFile), origin: { kind: 'instance-env-file', path: envPath } };
+    }
+    const secret = fs.randomSecret();
+    const needsLeadingNewline = existing !== null && existing !== '' && !existing.endsWith('\n');
+    const line = (needsLeadingNewline ? '\n' : '') + `# ${spec.comment}\n${spec.name}=${secret}\n`;
+    try {
+        fs.appendFile(envPath, line, 0o600);
+    }
+    catch (err) {
+        throw spec.refusal(envPath, err);
+    }
+    return { secret, origin: { kind: 'generated', path: envPath } };
+}
+/** The last `NAME=` line in a dotenv file, unquoted; null when absent or blank. */
+export function readEnvLine(content, name) {
+    const pattern = new RegExp(`^\\s*(?:export\\s+)?${name}\\s*=\\s*(.*)$`);
+    let found = null;
+    for (const raw of content.split('\n')) {
+        const m = raw.match(pattern);
+        if (!m)
+            continue;
+        let value = m[1].trim();
+        const quoted = value.match(/^(['"])(.*)\1$/);
+        if (quoted)
+            value = quoted[2];
+        else
+            value = value.replace(/\s+#.*$/, '').trim();
+        found = value;
+    }
+    return found === '' ? null : found;
+}
+/** The real filesystem behind every generated `.env` secret. */
+export const nodeInstanceEnvFs = {
+    readFile: (p) => {
+        try {
+            return fs.readFileSync(p, 'utf8');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return null;
+            throw err;
+        }
+    },
+    appendFile: (p, line, mode) => {
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.appendFileSync(p, line, { mode });
+    },
+    randomSecret: () => randomBytes(32).toString('base64')
+};