@jwilleke/ngdpbase-types 5.21.0 → 5.22.0

package/lib/packages/ngdpbase-types/index.d.ts

@@ -30,3 +30,8 @@ export type { Migration } from '../../src/providers/sqliteMigrations.js';
 export type { AddonDatabaseDeclaration, DatabaseEncrypt } from '../../src/utils/addonDatabaseRules.js';
 export type { default as ExportManager } from '../../src/managers/ExportManager.js';
 export type { default as PolicyDecisionPoint } from '../../src/security/PolicyDecisionPoint.js';
+export type { default as PersonManager, LinkOfferOutcome } from '../../src/managers/PersonManager.js';
+export type { default as OrganizationManager } from '../../src/managers/OrganizationManager.js';
+export type { Person, PersonAffiliation, PersonInput, PersonUpdate } from '../../src/types/Person.js';
+export type { Organization, OrganizationInput, OrganizationUpdate } from '../../src/types/Organization.js';
+export type { ContactRefusedError } from '../../src/utils/contactAccess.js';

package/lib/src/mail/MailProvider.d.ts

@@ -30,6 +30,8 @@ export interface MailProvider {
 /**
  * Development transport — writes the email to the server log instead of
  * sending it. Useful for local installs where no SMTP server is available.
+ * Like every log line, it names the recipient's domain only, and any address
+ * in the body is cut to its domain (#1916).
  */
 export declare class ConsoleMailProvider implements MailProvider {
     send(message: MailMessage): Promise<void>;

package/lib/src/managers/AddonsManager.d.ts

@@ -364,9 +364,9 @@ declare class AddonsManager extends BaseManager {
      * not load, whatever the reason. Admins get a notification at the most
      * severe level naming it and the reason, which says how to fix it where the
      * reason does. A site-critical add-on (`ngdpbase.addons.<slug>.site-critical`)
-     * also holds the whole site in maintenance mode through core's survivable
-     * path (#1152): visitors see only the configured public message, with no
-     * details, and administrators can still sign in and reach /admin. Once per
+     * also holds the whole site in maintenance mode through the one door
+     * (`engine.maintenance`, #1906): visitors see only the site's maintenance
+     * message, with no details, and administrators can still sign in and reach /admin. Once per
      * add-on per start. Nothing is opened in its place.
      */
     private recordLoadFailure;

package/lib/src/managers/AttachmentManager.d.ts

@@ -1,4 +1,6 @@
-import BaseManager, { BackupData, type ManagerStats } from './BaseManager.js';
+import BaseManager, { BackupData, type ManagerBackupOptions, type ManagerRestoreOptions, type ManagerStats } from './BaseManager.js';
+import type { AttachmentFilesBackupData, AttachmentFilesBackupOutcome } from '../providers/attachmentFilesBackup.js';
+import type { PartOutcome } from '../utils/siteRestore.js';
 import { type ActorContext } from '../context/ActorContext.js';
 /**
  * Marks an error as "the audit record could not be written", not "the action
@@ -7,13 +9,16 @@ import { type ActorContext } from '../context/ActorContext.js';
 export declare const AUDIT_WRITE_FAILED = "EAUDITWRITE";
 import type { WikiEngine } from '../types/WikiEngine.js';
 import type { CatalogSource, CatalogQuery, CatalogPage, CreativeWork, SchemaType, RebuildOpts } from '../types/Schema.js';
-import type { AssetQuery, AssetRecord } from '../types/Asset.js';
+import type { User } from '../providers/BaseAttachmentProvider.js';
+import { type AssetQuery, type AssetRecord } from '../types/Asset.js';
 import type { StoreFileEntry, StoreFileLocation } from '../types/Provider.js';
 /**
  * Base attachment provider interface
  */
 interface BaseAttachmentProvider {
-    initialize(): Promise<void>;
+    initialize(options?: {
+        readOnly?: boolean;
+    }): Promise<void>;
     storeAttachment(fileBuffer: Buffer, fileInfo: FileInfo, metadata: AttachmentMetadataInput, user: User | null): Promise<AttachmentMetadata>;
     getAttachment(attachmentId: string): Promise<{
         buffer: Buffer;
@@ -30,6 +35,12 @@ interface BaseAttachmentProvider {
     getThumbnail?(id: string, size: string): Promise<Buffer | null>;
     backup(): Promise<unknown>;
     restore(backupData: unknown): Promise<void>;
+    /** #1876: the files themselves beside the backup document, and their staged restore. */
+    backupFiles?(directory: string, stem: string): Promise<AttachmentFilesBackupOutcome>;
+    stageFilesRestore?(providerBackup: Record<string, unknown>, files: AttachmentFilesBackupData, directory: string, siteRestore: string): Promise<{
+        skippedVaults: string[];
+    }>;
+    takeRestoreAtStart?(): PartOutcome | null;
     shutdown(): Promise<void>;
     getProviderInfo(): {
         features: string[];
@@ -95,13 +106,6 @@ export interface UploadOptions {
     /** Store id when private with no private page; default from ConfigurationManager defaultstoreid */
     store?: string;
 }
-/**
- * User object interface
- */
-export interface User {
-    name: string;
-    email?: string;
-}
 /**
  * Mention object (WebPage reference)
  */
@@ -148,6 +152,8 @@ export interface AttachmentMetadataInput {
 export interface AttachmentBackupData extends BackupData {
     providerClass: string | null;
     providerBackup?: unknown;
+    /** The files themselves, as archives beside the document (#1876). */
+    files?: AttachmentFilesBackupData;
     data?: null;
 }
 declare class AttachmentManager extends BaseManager implements CatalogSource {
@@ -302,6 +308,16 @@ declare class AttachmentManager extends BaseManager implements CatalogSource {
      * @returns {Promise<AttachmentMetadata>} Attachment metadata
      */
     uploadAttachment(fileBuffer: Buffer, fileInfo: FileInfo, ctx: ActorContext, options?: UploadOptions): Promise<AttachmentMetadata>;
+    /**
+     * The username an upload is recorded under (#1926): the person the context
+     * names. Asked after policy has allowed the upload and before anything is
+     * written; it decides nothing about authority, only whether there is
+     * someone to record. No one uploads anonymously (operator, 2026-10-20, on
+     * #1852), so the anonymous subject — a share visitor included — and a job
+     * with no person behind it are refused. A refusal reads 'Permission denied'
+     * so the route answers it as one (401 for an anonymous caller).
+     */
+    private static uploaderOf;
     /** A file is added to a private page only by someone who may edit it: the page's own decision (#1398). */
     private assertMayEditPage;
     /**
@@ -446,6 +462,40 @@ declare class AttachmentManager extends BaseManager implements CatalogSource {
      * is findable exactly as a public one is.
      */
     searchPrivateStoreAttachments(query: AssetQuery, ctx: ActorContext): Promise<AssetRecord[]>;
+    /**
+     * {@link searchPrivateStoreAttachments}, kept apart by vault (#1852): the
+     * files layer needs to say which vault each file is in. The same stores,
+     * the same container rule, the same matching.
+     */
+    readableVaultAssetRecords(ctx: ActorContext, query?: AssetQuery): Promise<Array<{
+        owner: string;
+        vault: string;
+        files: AssetRecord[];
+    }>>;
+    /**
+     * The shared pool as asset records (#1852), every one of them: the
+     * provider's own mapping, so the files layer and asset search show a
+     * public file the same way. Whether the requester may read the pool is the
+     * caller's question (`asset-read`).
+     */
+    sharedPoolAssetRecords(): Promise<AssetRecord[]>;
+    /**
+     * Every vault's files, for an operator inventory with no viewer (#1852,
+     * the files migration dry run), the way {@link findVaultPagesUsingPoolFiles}
+     * walks them: an unsealed vault's index entries; for any other vault
+     * (sealed, or not yet opened) only the files on disk and their size, since
+     * its index can't be read without its owner's key. Reads only. The entries
+     * are for the files layer to count; they are never shown.
+     */
+    vaultFileInventory(): Promise<Array<{
+        owner: string;
+        vault: string;
+        /** Whether its index could be read: an unsealed vault. */
+        readable: boolean;
+        entries: StoreFileEntry[] | null;
+        filesOnDisk: number;
+        bytesOnDisk: number;
+    }>>;
     /**
      * Move every unencrypted private file record out of the global
      * `attachment-metadata.json` and into its store's own index, at start-up.
@@ -1000,7 +1050,7 @@ declare class AttachmentManager extends BaseManager implements CatalogSource {
      *
      * @returns {Promise<AttachmentBackupData>}
      */
-    backup(): Promise<AttachmentBackupData>;
+    backup(options?: ManagerBackupOptions): Promise<AttachmentBackupData>;
     /**
      * Restore manager data from backup
      * Delegates to provider's restore method
@@ -1008,7 +1058,9 @@ declare class AttachmentManager extends BaseManager implements CatalogSource {
      * @param {AttachmentBackupData} backupData - Backup data from backup() method
      * @returns {Promise<void>}
      */
-    restore(backupData: AttachmentBackupData): Promise<void>;
+    restore(backupData: AttachmentBackupData, options?: ManagerRestoreOptions): Promise<void>;
+    /** Its restore is staged for the next start with the rest of a site restore (#1876). */
+    restoreIsStaged(): boolean;
     /**
      * Shutdown the manager
      * @returns {Promise<void>}

package/lib/src/managers/AuthManager.d.ts

@@ -30,7 +30,7 @@
  * @see {@link https://github.com/jwilleke/ngdpbase/issues/396}
  */
 import BaseManager from './BaseManager.js';
-import type { BackupData } from './BaseManager.js';
+import type { BackupData, ManagerBackupOptions, ManagerRestoreOptions } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import type { PermissionSubject } from './UserManager.js';
 import type { JobContext } from '../context/JobContext.js';
@@ -396,6 +396,8 @@ declare class AuthManager extends BaseManager {
     private factorCache;
     /** The credentials store (#1524); null when it could not be opened. */
     private credentials;
+    /** `ngdpbase.auth.credentials.file`, resolved at start: what a backup copies (#1876). */
+    private credentialsFile;
     constructor(engine: WikiEngine);
     initialize(config?: Record<string, unknown>): Promise<void>;
     /**
@@ -1126,7 +1128,7 @@ declare class AuthManager extends BaseManager {
      * The link only opens the approval page; the button there approves, so a
      * mail scanner opening links approves nothing. Limited to one per minute.
      */
-    sendEmailApproval(handle: string, binding: string): Promise<'sent' | 'too-soon' | 'unavailable'>;
+    sendEmailApproval(handle: string, binding: string): Promise<'sent' | 'too-soon' | 'unavailable' | 'failed'>;
     /** What the approval page shows about the waiting sign-in; null for an unknown or used link. */
     approvalDetails(token: string): {
         username: string;
@@ -1260,7 +1262,25 @@ declare class AuthManager extends BaseManager {
     isEnabled(providerId: string): boolean;
     /** Returns all registered providers (for admin UI). */
     getProviders(): AuthProvider[];
-    backup(): Promise<BackupData>;
-    restore(_backupData: BackupData): Promise<void>;
+    /**
+     * The provider list, and the credentials store (#1876): passkeys, TOTP,
+     * verified email and phone, devices, linked identities and proxy grants,
+     * as its own file beside the document, __always encrypted under
+     * `NGDPBASE_BACKUP_KEY`__ (`<stem>.credentials.tar.enc`). Without the key the
+     * store is left out and the backup is reported incomplete; it is never in a
+     * backup unencrypted. The rows stay signed with `NGDPBASE_CREDENTIALS_KEY`,
+     * which is not in the backup: a site restored under another credentials key
+     * holds them in quarantine (#1633).
+     */
+    backup(options?: ManagerBackupOptions): Promise<BackupData>;
+    /**
+     * Stage the credentials store from a backup for the next start, with the
+     * rest of a site restore (#1876). A backup that left it out (no backup key
+     * when it was taken) stages nothing: the store on the site stays, and the
+     * restore's notification names it as not restored.
+     */
+    restore(backupData: BackupData, options?: ManagerRestoreOptions): Promise<void>;
+    /** Staged for the next start with the rest of a site restore (#1876). */
+    restoreIsStaged(): boolean;
 }
 export default AuthManager;

package/lib/src/managers/BackgroundJobManager.d.ts

@@ -1,9 +1,21 @@
-import BaseManager from './BaseManager.js';
+import BaseManager, { type BackupData, type ManagerBackupOptions, type ManagerRestoreOptions } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import { type JobContext } from '../context/JobContext.js';
 import { type ScheduleInput } from '../utils/schedule.js';
 import { type CatchUp, type Overlap } from '../utils/jobSlots.js';
 import { type JobRunRecord, type JobStateProvider } from '../providers/jobState.js';
+/** Who holds a slot lock: this host, this process, this start. */
+/**
+ * One run between a backup and the restore of it (#1876): what admins are
+ * told was done on the site and is no longer in the restored job state.
+ */
+export interface JobRunSince {
+    jobId: string;
+    startedAt: string;
+    completedAt?: string;
+    status: JobRunRecord['status'];
+    error?: string;
+}
 /**
  * Callback supplied to job run functions so they can push live progress
  * messages that the client can display while polling.
@@ -212,6 +224,19 @@ declare class BackgroundJobManager extends BaseManager {
     private controllers;
     /** For each running scheduled run: write it as interrupted and let go of its slot. */
     private handoffs;
+    /** `ngdpbase.jobs.state.dir`, when job state is files: what a backup copies (#1876). */
+    private stateDir;
+    /**
+     * The job state was put back from a backup at this start (#1876): every
+     * job then starts from now — no slot since the backup is caught up, and a
+     * run unfinished in the backup is closed, never resumed or retried. Jobs
+     * are never re-run because of a restore.
+     */
+    private restoredAtStart;
+    /** Jobs whose restored state has been settled, since this start. */
+    private settledAfterRestore;
+    /** The runs found in the live file state before a restore replaced it (#1876). */
+    private runsReplacedAtStart;
     /**
      * @param options - for tests: a state provider in place of the configured
      *   one, and the clock.
@@ -390,6 +415,45 @@ declare class BackgroundJobManager extends BaseManager {
     /** Whether the person who started a run still holds the job's permission — by policy, as at the time it is asked (P2). */
     private stillHolds;
     /** A run a restart cut off and that is not run again: recorded as failed, audited, and told to the admins. Never silent. */
+    /**
+     * A scheduled job's first look after its state was restored (#1876): a run
+     * the backup caught unfinished is closed as failed, never resumed or
+     * retried, and the next slot is the next one from now, so no slot between
+     * the backup and the restore is caught up. The restore's notification
+     * lists the runs that had happened since the backup.
+     */
+    private settleAfterRestore;
+    /**
+     * Job state in a backup (#1876). Files (`ngdpbase.jobs.state.dir`): the
+     * state, run history and checkpoints as `<stem>.jobs.tar` beside the
+     * document, without the slot locks, which belong to the server that holds
+     * them. In the database: nothing here — it is in the database backup.
+     */
+    backup(options?: ManagerBackupOptions): Promise<BackupData>;
+    /** File job state is staged for the next start with the rest of a site restore (#1876). Database job state comes back with the database. */
+    restore(backupData: BackupData, options?: ManagerRestoreOptions): Promise<void>;
+    restoreIsStaged(): boolean;
+    /**
+     * Put staged file job state in place, at start, before it is opened
+     * (#1876). The runs in the live state since the backup was taken are read
+     * first, before it is replaced, for the restore's notification.
+     */
+    private applyRestoreAtStart;
+    /**
+     * The job runs the live application database held, since the backup, when
+     * this start's restore replaced it (#1876): read from the copy DatabaseManager
+     * kept, which is the database as it was at the moment of the swap — so runs
+     * between staging and the restart are named too.
+     */
+    private readReplacedDatabaseRuns;
+    /** The runs in the file job state at `stateDir` started after `since`, read from disk. */
+    private readLiveRunsSince;
+    /** The runs of every registered job started after `since`, from the live state (#1876): read before a restore replaces it. */
+    runsSince(since: string): Promise<JobRunSince[]>;
+    /** The runs the live file state held before a restore replaced it at this start (#1876). */
+    getRunsReplacedAtStart(): JobRunSince[];
+    /** A job's display name, or its id when no job of that id is registered. */
+    displayNameOf(jobId: string): string;
     private reportCutOff;
     /**
      * Get the current state of a run by runId.

package/lib/src/managers/BaseManager.d.ts

@@ -78,6 +78,13 @@ export interface ManagerRestoreOptions {
     replaceStaged?: boolean;
     /** The backup of the live data BackupManager took just before this restore (#1723, D6), by filename. */
     safetyBackup?: string;
+    /**
+     * The site restore manifest this restore is staged under (#1876). A
+     * manager whose restore is staged (`restoreIsStaged()`) stages its files
+     * beside its live ones and records its part there; the next start applies
+     * every part or none (`src/utils/siteRestore.ts`).
+     */
+    siteRestore?: string;
 }
 /**
  * Base class for all managers
@@ -341,6 +348,13 @@ declare abstract class BaseManager {
      * }
      */
     restore(backupData: BackupData, _options?: ManagerRestoreOptions): Promise<void>;
+    /**
+     * Whether this manager's `restore()` stages for the next start instead of
+     * writing into the running site (#1723, #1876). BackupManager stages every
+     * such manager in a site restore together, all or nothing, after a backup
+     * of the live data. The default is false: the restore writes live.
+     */
+    restoreIsStaged(): boolean;
     /**
      * Return a plain-text string suitable for use as MarqueePlugin banner text.
      *

package/lib/src/managers/BaseManager.js

@@ -299,6 +299,15 @@ class BaseManager {
             throw new Error(`${this.constructor.name}: No backup data provided for restore`);
         }
     }
+    /**
+     * Whether this manager's `restore()` stages for the next start instead of
+     * writing into the running site (#1723, #1876). BackupManager stages every
+     * such manager in a site restore together, all or nothing, after a backup
+     * of the live data. The default is false: the restore writes live.
+     */
+    restoreIsStaged() {
+        return false;
+    }
     /**
      * Return a plain-text string suitable for use as MarqueePlugin banner text.
      *

package/lib/src/managers/CommentManager.d.ts

@@ -1,4 +1,4 @@
-import BaseManager from './BaseManager.js';
+import BaseManager, { type BackupData, type ManagerBackupOptions, type ManagerRestoreOptions } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import type { PageComment } from '../types/Comment.js';
 import { type ActorContext } from '../context/ActorContext.js';
@@ -10,6 +10,15 @@ export default class CommentManager extends BaseManager {
     private readonly outsideCheck;
     constructor(engine: WikiEngine);
     initialize(): Promise<void>;
+    /**
+     * The public folder is in the backup (#1876), as `<stem>.comments.tar` beside
+     * the document: the public pages' comments. A vault page's are in its vault, which
+     * PageManager backs up with the vault, sealed as stored.
+     */
+    backup(options?: ManagerBackupOptions): Promise<BackupData>;
+    /** Staged for the next start with the rest of a site restore (#1876); the live folder is untouched. */
+    restore(backupData: BackupData, options?: ManagerRestoreOptions): Promise<void>;
+    restoreIsStaged(): boolean;
     isEnabled(): boolean;
     /** The public folder and the vaults, as configured now (#1839). */
     private roots;

package/lib/src/managers/DatabaseManager.d.ts

@@ -1,27 +1,16 @@
 import BaseManager from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
+import { type SqliteHandle } from '../providers/SqliteDatabaseProvider.js';
 import type { Migration } from '../providers/sqliteMigrations.js';
 import { type ActorContext } from '../context/ActorContext.js';
 import type { BackupData, ManagerBackupOptions, ManagerRestoreOptions } from './BaseManager.js';
 import { type AddonDatabaseDeclaration } from '../utils/addonDatabaseRules.js';
 import { type StagedRestoreManifest } from '../providers/sqliteBackup.js';
-/** The environment variable holding the SQLCipher key. Never a config key: config is readable from the admin screens. */
-export declare const DATABASE_KEY_ENV = "NGDPBASE_DATABASE_KEY";
-/**
- * The environment variable holding the key every database backup is encrypted
- * under (#1723). Its own secret, not the database key: the copy that travels
- * and the copy that stays should not fall to the same compromise. Never a
- * config key. Unset, no database is backed up, and admins are told.
- */
-export declare const BACKUP_KEY_ENV = "NGDPBASE_BACKUP_KEY";
+import { DATABASE_KEY_ENV } from '../utils/databaseKey.js';
+export { DATABASE_KEY_ENV };
+export { BACKUP_KEY_ENV, backupKeyFingerprint } from '../utils/backupKey.js';
 /** How long a database backup or restore staging may run on its worker before it is stopped, when not configured. */
 export declare const DEFAULT_BACKUP_WORKER_TIMEOUT_MS = 3600000;
-/**
- * A short fingerprint of a backup key (#1723, D3): the first 16 hex digits of
- * an HMAC of a fixed label under the key. Recorded in each backup so a restore
- * under another key says so plainly; it never reveals the key.
- */
-export declare function backupKeyFingerprint(key: string): string;
 /** One database in a backup, as DatabaseManager's entry in the backup document lists it. */
 export interface DatabaseBackupEntry {
     /** `application`, or `addon-<owner>`. */
@@ -91,6 +80,10 @@ declare class DatabaseManager extends BaseManager {
     private readonly addonDatabases;
     /** What the start did with a staged restore (#1723), reported once the notifications exist. */
     private restoreAtStart;
+    /** The databases a staged restore put back at this start (#1876): kept after the report, for the managers whose data is in them. */
+    private restoredNow;
+    /** When the restored backup was taken, and where the replaced application database is kept, when a restore was applied at this start (#1876). */
+    private replaced;
     /** Why this manager is degraded, one entry per cause, so one cause clearing leaves the others. */
     private readonly faults;
     /** Why the configured application database could not be opened safely (#1892); null otherwise. */
@@ -108,8 +101,8 @@ declare class DatabaseManager extends BaseManager {
     getUnavailableReason(): string | null;
     /**
      * #1892 (operator D3 rule, 2026-10-18): the application database can't be
-     * opened safely. The process stays up in maintenance mode through core's
-     * survivable path (#1152): visitors see only the public message (#1883),
+     * opened safely. The process stays up in maintenance mode through the one
+     * door (`engine.maintenance`, #1906): visitors see only the site's maintenance message,
      * administrators can sign in and reach /admin, and `reportAtBoot()` sends
      * them the reason as a critical notification once notifications exist.
      */
@@ -181,6 +174,20 @@ declare class DatabaseManager extends BaseManager {
      * staged, and admins are told.
      */
     restore(backupData: BackupData, options?: ManagerRestoreOptions): Promise<void>;
+    /** Whether a staged restore put the databases back at this start (#1876): the job state in them is then the backup's. */
+    restoredAtStart(): boolean;
+    /**
+     * Read the application database as it was just before this start's restore
+     * replaced it (#1876): the kept `*.pre-restore` file, read-only, under the
+     * site's database key, which it was encrypted under. For the owner of data
+     * in it (BackgroundJobManager's job runs since the backup) to say what the
+     * restore took away. Null when no restore replaced it at this start.
+     */
+    readReplacedApplicationDatabase<T>(read: (db: SqliteHandle, backupTakenAt: string) => T): T | null;
+    /** The databases a staged restore put back at this start, by name (#1876). */
+    getRestoredAtStart(): string[];
+    /** Its restore is staged for the next start (#1723), and joins a site restore (#1876). */
+    restoreIsStaged(): boolean;
     /** The restore staged and waiting for the next start, or null. */
     getStagedRestore(): StagedRestoreManifest | null;
     /**

package/lib/src/managers/DatabaseManager.js

@@ -40,34 +40,22 @@ import path from 'node:path';
 import BaseManager from './BaseManager.js';
 import SqliteDatabaseProvider, { DEFAULT_BUSY_TIMEOUT_MS } from '../providers/SqliteDatabaseProvider.js';
 import DATABASE_MIGRATIONS from '../providers/databaseMigrations.js';
-import { createHmac } from 'node:crypto';
 import { existsSync, readFileSync, rmSync } from 'node:fs';
 import { actorOf } from '../context/ActorContext.js';
 import { recordAuditEvent } from '../utils/auditEvents.js';
 import { AUDIT_EVENT } from '../utils/auditEventNames.js';
 import logger from '../utils/logger.js';
 import { ADDON_SLUG, ledgerPrefix } from '../utils/addonDatabaseRules.js';
-import { sitePublicMessage } from '../utils/startupState.js';
-import { applyStagedRestore, manifestPath, runOffThread, stagedPath, writeManifest } from '../providers/sqliteBackup.js';
-/** The environment variable holding the SQLCipher key. Never a config key: config is readable from the admin screens. */
-export const DATABASE_KEY_ENV = 'NGDPBASE_DATABASE_KEY';
-/**
- * The environment variable holding the key every database backup is encrypted
- * under (#1723). Its own secret, not the database key: the copy that travels
- * and the copy that stays should not fall to the same compromise. Never a
- * config key. Unset, no database is backed up, and admins are told.
- */
-export const BACKUP_KEY_ENV = 'NGDPBASE_BACKUP_KEY';
+import { applyStagedRestore, manifestPath, runOffThread, setAsideStagedRestore, stagedPath, writeManifest } from '../providers/sqliteBackup.js';
+import { gatePart, markPart, recordStagedPart, siteRestoreFile } from '../utils/siteRestore.js';
+import { BACKUP_KEY_ENV, backupKeyFingerprint, currentBackupKey, LEFT_OUT_FOR_NO_KEY } from '../utils/backupKey.js';
+// The environment variable holding the SQLCipher key: one declaration, `src/utils/databaseKey.ts`.
+import { DATABASE_KEY_ENV } from '../utils/databaseKey.js';
+export { DATABASE_KEY_ENV };
+// #1723, #1876: the backup key has one declaration (`src/utils/backupKey.ts`); re-exported for the callers that import it from here.
+export { BACKUP_KEY_ENV, backupKeyFingerprint } from '../utils/backupKey.js';
 /** How long a database backup or restore staging may run on its worker before it is stopped, when not configured. */
 export const DEFAULT_BACKUP_WORKER_TIMEOUT_MS = 3_600_000;
-/**
- * A short fingerprint of a backup key (#1723, D3): the first 16 hex digits of
- * an HMAC of a fixed label under the key. Recorded in each backup so a restore
- * under another key says so plainly; it never reveals the key.
- */
-export function backupKeyFingerprint(key) {
-    return createHmac('sha256', key).update('ngdpbase backup key fingerprint v1').digest('hex').slice(0, 16);
-}
 /** The backup's name for the application database; an add-on's is `addon-<owner>`. */
 const APPLICATION = 'application';
 const addonName = (owner) => `addon-${owner}`;
@@ -112,6 +100,10 @@ class DatabaseManager extends BaseManager {
     addonDatabases = new Map();
     /** What the start did with a staged restore (#1723), reported once the notifications exist. */
     restoreAtStart = null;
+    /** The databases a staged restore put back at this start (#1876): kept after the report, for the managers whose data is in them. */
+    restoredNow = [];
+    /** When the restored backup was taken, and where the replaced application database is kept, when a restore was applied at this start (#1876). */
+    replaced = null;
     /** Why this manager is degraded, one entry per cause, so one cause clearing leaves the others. */
     faults = new Map();
     /** Why the configured application database could not be opened safely (#1892); null otherwise. */
@@ -190,8 +182,8 @@ class DatabaseManager extends BaseManager {
     }
     /**
      * #1892 (operator D3 rule, 2026-10-18): the application database can't be
-     * opened safely. The process stays up in maintenance mode through core's
-     * survivable path (#1152): visitors see only the public message (#1883),
+     * opened safely. The process stays up in maintenance mode through the one
+     * door (`engine.maintenance`, #1906): visitors see only the site's maintenance message,
      * administrators can sign in and reach /admin, and `reportAtBoot()` sends
      * them the reason as a critical notification once notifications exist.
      */
@@ -200,10 +192,8 @@ class DatabaseManager extends BaseManager {
         this.provider = null;
         logger.error(`[DatabaseManager] ${reason}`);
         this.markFailed(reason, 'ngdpbase.database.file');
-        const configManager = this.engine.getManager('ConfigurationManager');
-        this.engine.blockConfiguration(reason, {
-            publicMessage: sitePublicMessage(configManager ? (k, d) => configManager.getProperty(k, d) : undefined)
-        });
+        // #1906: no message of its own, so visitors see the site's maintenance message.
+        this.engine.maintenance.enter(reason);
     }
     /** The reason for a database that did not open, with the fix that fits the key (#1892). */
     static openFailure(file, cause, key) {
@@ -355,7 +345,7 @@ class DatabaseManager extends BaseManager {
         }
         const backupKey = this.backupKey();
         if (!backupKey) {
-            const reason = `${BACKUP_KEY_ENV} is not set, so no database was backed up. Database backups are always encrypted and are never written without it (#1723)`;
+            const reason = `${LEFT_OUT_FOR_NO_KEY}no database was backed up. Database backups are always encrypted and are never written without it (#1723)`;
             this.fault('backup-key', reason);
             throw new Error(reason);
         }
@@ -502,6 +492,14 @@ class DatabaseManager extends BaseManager {
             databases: stages.map((s) => ({ name: s.name, live: s.live, staged: stagedPath(s.live) }))
         };
         writeManifest(manifestFile, manifest);
+        // #1876: part of a site restore — the databases go in with the other parts, or not at all.
+        if (options.siteRestore) {
+            recordStagedPart(options.siteRestore, {
+                manager: 'DatabaseManager',
+                swaps: manifest.databases.map((d) => ({ live: d.live, staged: d.staged })),
+                discard: [manifestFile]
+            });
+        }
         const names = stages.map((s) => s.name).join(', ');
         logger.warn(`[DatabaseManager] Restore staged for ${names} — restart to apply it (#1723)`);
         const unopened = this.unavailable
@@ -514,6 +512,31 @@ class DatabaseManager extends BaseManager {
             await this.notify('error', 'Some databases in the backup were not restored', message);
         }
     }
+    /** Whether a staged restore put the databases back at this start (#1876): the job state in them is then the backup's. */
+    restoredAtStart() {
+        return this.restoredNow.length > 0;
+    }
+    /**
+     * Read the application database as it was just before this start's restore
+     * replaced it (#1876): the kept `*.pre-restore` file, read-only, under the
+     * site's database key, which it was encrypted under. For the owner of data
+     * in it (BackgroundJobManager's job runs since the backup) to say what the
+     * restore took away. Null when no restore replaced it at this start.
+     */
+    readReplacedApplicationDatabase(read) {
+        const kept = this.replaced?.applicationKept;
+        if (!kept || !existsSync(kept))
+            return null;
+        return SqliteDatabaseProvider.readOnce(kept, process.env[DATABASE_KEY_ENV] ?? '', (db) => read(db, this.replaced.backup));
+    }
+    /** The databases a staged restore put back at this start, by name (#1876). */
+    getRestoredAtStart() {
+        return [...this.restoredNow];
+    }
+    /** Its restore is staged for the next start (#1723), and joins a site restore (#1876). */
+    restoreIsStaged() {
+        return true;
+    }
     /** The restore staged and waiting for the next start, or null. */
     getStagedRestore() {
         if (!this.databaseFile)
@@ -596,7 +619,23 @@ class DatabaseManager extends BaseManager {
             const name = path.basename(resolved);
             return path.dirname(resolved) === dir && name.endsWith('.db') && ADDON_SLUG.test(name.slice(0, -3));
         };
-        const outcome = applyStagedRestore(file, allowed);
+        // #1876: a database restore staged as part of a site restore goes in only
+        // when the whole site restore does; otherwise it is set aside with it.
+        const siteFile = siteRestoreFile(this.engine.getManager('ConfigurationManager'));
+        const stagedBackupAt = this.getStagedRestore()?.backup ?? '';
+        const gate = gatePart(siteFile, 'DatabaseManager');
+        let outcome;
+        if (gate.decision === 'set-aside') {
+            outcome = setAsideStagedRestore(file, `the site restore it belongs to was not applied: ${gate.reason}`);
+            if (gate.part)
+                markPart(siteFile, 'DatabaseManager', 'set-aside', gate.reason);
+        }
+        else {
+            outcome = applyStagedRestore(file, allowed);
+            if (gate.decision === 'apply') {
+                markPart(siteFile, 'DatabaseManager', outcome && !outcome.refused ? 'applied' : 'set-aside', outcome?.refused ?? (outcome ? undefined : 'no staged database restore was found'));
+            }
+        }
         if (!outcome)
             return;
         this.restoreAtStart = outcome;
@@ -606,12 +645,16 @@ class DatabaseManager extends BaseManager {
             this.fault('restore', reason);
             return;
         }
+        this.restoredNow = outcome.applied.map((a) => a.name);
+        if (outcome.applied.length > 0) {
+            this.replaced = { backup: stagedBackupAt, applicationKept: outcome.applied.find((a) => path.resolve(a.live) === path.resolve(file))?.kept ?? null };
+        }
         for (const a of outcome.applied) {
             logger.warn(`[DatabaseManager] Restore applied: ${a.name} -> ${a.live} (previous kept as ${path.basename(a.kept)}) (#1723)`);
         }
     }
     backupKey() {
-        return (process.env[BACKUP_KEY_ENV] ?? '').trim();
+        return currentBackupKey();
     }
     /** What is wrong with the backup key: missing, or the database key itself (D3). Null when sound. */
     backupKeyProblem() {