@jwilleke/ngdpbase-types 5.25.0 → 5.27.0

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/frontmatterAccess.d.ts

@@ -2,8 +2,8 @@
  * frontmatterAccess — the single implementation of ACL Tier 1 (#1054).
  *
  * A page's frontmatter can restrict who may act on it, via `access[<action>]`
- * or, for viewing, `audience`. Two subsystems needed that answer and each had
- * its own version of it, which is how they came to disagree:
+ * or `audience`, which covers every action (#1964). Two subsystems needed
+ * that answer and each had its own version of it, which is how they came to disagree:
  *
  *   - `PolicyInformationPoint.checkFrontmatterAccess` decided a request, correctly.
  *   - `VersioningFileProvider.getRecentChanges` decided a listing, and only
@@ -22,7 +22,7 @@
 export interface AccessMetadataLike {
     /** `{ view: ['role'], edit: [...] }` — per-action principal lists. */
     access?: unknown;
-    /** Shorthand for `access.view`. */
+    /** Who may act on the page at all; administrators excepted (#1964). */
     audience?: unknown;
 }
 export interface FrontmatterDecision {
@@ -34,21 +34,64 @@ export interface FrontmatterDecision {
     matched?: string;
 }
 /**
- * Principals permitted to perform `action`, or null when the page states no
- * rule and the caller should fall through to global policy.
- *
- * `access[action]` wins; `audience` is the shorthand and applies to `view`
- * only. An empty list counts as no rule — a page saying `audience: []`
- * restricts nobody, which matters because a bare `access:` key parses that way.
+ * The page's `audience`, or null when it names none (#1964, operator
+ * 2026-10-23). An audience restricts EVERY action: someone outside it may
+ * neither read nor edit the page.
+ */
+export declare function audiencePrincipals(metadata: AccessMetadataLike | null | undefined): string[] | null;
+/**
+ * The page's `access[action]` list, or null when it states none. It applies
+ * to that action only, and to everyone — administrators included.
+ */
+export declare function accessPrincipals(metadata: AccessMetadataLike | null | undefined, action: string): string[] | null;
+/**
+ * The entry `addon:<slug>` (#1964): "people who turned on the per-person
+ * add-on <slug>". It is matched only against the viewer's enabled add-ons,
+ * never against a role or a username.
+ */
+export declare const ADDON_PRINCIPAL_PREFIX = "addon:";
+/**
+ * Whether deciding `action` on this page needs the viewer's enabled add-ons —
+ * so a caller asks for them only when the page names one (#1964).
  */
-export declare function resolveFrontmatterPrincipals(metadata: AccessMetadataLike | null | undefined, action: string): string[] | null;
+export declare function namesAddonPrincipal(metadata: AccessMetadataLike | null | undefined, action: string): boolean;
+/**
+ * Every add-on slug the page names in `audience` or in any `access` list, once
+ * each, in the order first named — for the warning about a slug that can match
+ * nobody (#1964).
+ */
+export declare function addonAudienceSlugs(metadata: AccessMetadataLike | null | undefined): string[];
+/**
+ * Whether the page's audience leaves this viewer out — true only when it
+ * names one and nothing in it matches. The caller then asks whether the
+ * viewer is an administrator, the one exception (#1964), and passes the
+ * answer to {@link decideFrontmatterAccess}; it asks only when this is true.
+ */
+export declare function audienceExcludes(metadata: AccessMetadataLike | null | undefined, viewerPrincipals: readonly string[], enabledAddons?: readonly string[]): boolean;
+/** The `matched` an administrator outside the audience is admitted by. */
+export declare const AUDIENCE_ADMIN_MATCH = "admin-system";
 /**
  * Decide Tier 1 for a viewer described as a flat principal list — their roles
  * plus their username. Callers holding a `UserContext` should pass
  * `[...roles, username]`; the provider layer already works in these terms.
  *
+ * Two rules, in order (#1964, operator 2026-10-23):
+ *
+ * - __`audience`__ applies to every action. Someone it leaves out may neither
+ *   read nor edit the page: every action is refused. The one exception is an
+ *   administrator — a viewer holding `admin-system`, which the caller decides
+ *   and passes as `isAdmin` (this module never reads a role for it). For
+ *   `view`, a viewer the audience admits is allowed; for any other action it
+ *   only lets them through to `access` and then policy.
+ * - __`access[action]`__ applies to that action, to everyone, administrators
+ *   included. When the page states it, it decides.
+ *
+ * An `addon:<slug>` entry matches only when `<slug>` is in `enabledAddons`,
+ * the viewer's enabled per-person add-ons (#1964); a caller that does not
+ * supply them matches no such entry, so it can under-list but never leak.
+ *
  * Denies when the page states a rule and nothing matches. That default is the
  * point: a listing that treats "no match" as "show it" is the bug this exists
  * to prevent.
  */
-export declare function decideFrontmatterAccess(metadata: AccessMetadataLike | null | undefined, viewerPrincipals: readonly string[], action: string): FrontmatterDecision;
+export declare function decideFrontmatterAccess(metadata: AccessMetadataLike | null | undefined, viewerPrincipals: readonly string[], action: string, enabledAddons?: readonly string[], isAdmin?: boolean): FrontmatterDecision;

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

@@ -0,0 +1,64 @@
+/**
+ * Per-run summary persistence for NCM / import conversion outcomes (#738).
+ *
+ * Writes one JSON file per import run under FAST_STORAGE (configurable via
+ * `ngdpbase.import.runs-dir`, default `./data/import-runs`). Each file's
+ * name is the ISO timestamp of `startedAt`, sanitised for filesystem use.
+ *
+ * The trend view (admin-import.ejs) reads the last N summaries via
+ * listRecentRuns() to surface dominant failure causes across runs.
+ *
+ * Append-only by design. Retention is operator-managed for now — the
+ * directory can grow indefinitely; a future cleanup job (or admin button)
+ * can prune. Listed as a follow-up in the #738 acceptance criteria.
+ */
+/** Compact per-run record persisted to disk. */
+export interface ImportRunSummary {
+    /** Stable id; same as the filename without `.json`. */
+    runId: string;
+    /** ISO-8601 timestamp of when the run started. */
+    startedAt: string;
+    /** ISO-8601 timestamp of when the run finished (may equal startedAt for trivial runs). */
+    finishedAt: string;
+    /** What kind of import surfaced this run (`paste`, `url`, `file`, `ingest:<sourceId>`). */
+    importType: string;
+    /**
+     * Who initiated the run — `ImportOptions.actorContext.username` (#1236): the
+     * request's subject for a manual import, the system principal for a job.
+     */
+    actor: string;
+    /**
+     * True when the run was a job with no person behind it (a JobContext whose
+     * origin is boot, schedule or operator) — lets the trend view distinguish
+     * "alice triggered an import" from "scheduled feed ingested overnight".
+     * False for a request, or a request-origin job.
+     */
+    isSystem?: boolean;
+    /** Where the run came from: `request`, `boot`, `schedule` or `operator` (#1236). Absent on records written before it. */
+    origin?: string;
+    /** Total items the run attempted. */
+    total: number;
+    /** Items successfully converted to pages. */
+    converted: number;
+    /** Items intentionally skipped (e.g. duplicates). */
+    skipped: number;
+    /** Items that failed to convert. */
+    failed: number;
+    /**
+     * Counts of ConversionWarning.kind values aggregated across all items in the run.
+     * Keys are flat (no colon-subkinds today) per the #738 design decision.
+     */
+    kindCounts: Record<string, number>;
+}
+/** Aggregate a flat list of ConversionWarning-like objects into kindCounts. */
+export declare function tallyWarnings(warnings: Array<{
+    kind: string;
+}> | undefined): Record<string, number>;
+/** Write a single per-run summary. Idempotent for same runId. Best-effort — errors logged, never thrown. */
+export declare function writeRunSummary(runsDir: string, summary: ImportRunSummary): Promise<void>;
+/**
+ * Return the most-recent N run summaries, newest first. Filenames are ISO
+ * timestamps so lexicographic sort is chronological. Missing/empty dir
+ * returns []. Malformed individual files are skipped, not fatal.
+ */
+export declare function listRecentRuns(runsDir: string, limit?: number): Promise<ImportRunSummary[]>;

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') : '' } };
+}