@jwilleke/ngdpbase-types 5.20.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

@@ -17,11 +17,6 @@ import type { WikiEngine } from '../types/WikiEngine.js';
 import type { User } from '../types/User.js';
 import { type StoreOwnerState } from '../utils/privateStoreDoor.js';
 import { type AddonHost } from '../utils/addonHost.js';
-/**
- * #1883: what visitors see while a site-critical add-on that did not load
- * holds the site in maintenance mode. Empty leaves only the page's heading.
- */
-export declare const SITE_CRITICAL_PUBLIC_MESSAGE_KEY = "ngdpbase.managers.addons-manager.site-critical.public-message";
 /**
  * Type passed to `AddonModule.profileSection()` (#534). Matches what
  * `UserManager.getUser()` returns at runtime — `User` minus the password
@@ -369,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.
@@ -202,10 +214,29 @@ declare class BackgroundJobManager extends BaseManager {
     /** Set once shutdown begins: no slot starts after it (#1717). */
     private stopping;
     private handedOff;
+    /**
+     * #1892: why no job runs — the application database is configured but could
+     * not be opened safely, and the site is in maintenance mode. Jobs still
+     * register; none starts, on a schedule or by hand, until a restart opens it.
+     */
+    private held;
     /** Each running job's abort, by run id. */
     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.
@@ -384,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

@@ -57,6 +57,12 @@ export interface ManagerBackupOptions {
     directory: string;
     /** The document's filename without `.json.gz` / `.json`. */
     stem: string;
+    /**
+     * The backup a restore takes of the live data first (#1892 D2). A database
+     * that can't be opened is left out and recorded in the manager's data, not
+     * failed: the restore keeps its file beside the restored one instead.
+     */
+    safetyBackup?: boolean;
 }
 /** What BackupManager hands each manager's `restore()` (#1723): who asked, and the directory the backup document was read from. */
 export interface ManagerRestoreOptions {
@@ -72,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
@@ -335,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/ConfigurationManager.d.ts

@@ -248,6 +248,14 @@ declare class ConfigurationManager extends BaseManager {
      * const appName = configManager.getProperty('ngdpbase.application-name', 'MyWiki');
      */
     getProperty(key: string, defaultValue?: unknown): unknown;
+    /**
+     * #1889: a value as configured, every `$NAME` reference in it unresolved,
+     * for the one kind of reader that must see that a secret IS a reference:
+     * AuthManager refuses an outside provider whose client secret is written
+     * into configuration rather than named in the environment. Never for
+     * display: a literal secret would come back as itself.
+     */
+    getUnresolvedProperty(key: string, defaultValue?: unknown): unknown;
     /**
      * #896: read a property from the SHIPPED defaults only, ignoring instance
      * custom-config overrides. Used by vocabulary providers whose seed must not
@@ -320,7 +328,10 @@ declare class ConfigurationManager extends BaseManager {
      * **`$$literal` escape** — for the rare config value that genuinely
      * starts with `$`. `"$$abc"` resolves to `"$abc"`.
      *
-     * Non-string values pass through unchanged. Resolution happens at lookup
+     * Inside a map or list (#1889), the bare `$VAR` form and the `$$` escape
+     * apply to every string, strictly, the error naming the full path
+     * (`key.map-key.field`); the brace form does not. Other non-string values
+     * pass through unchanged. Resolution happens at lookup
      * time (per-`getProperty()` call), not at config load — so tests that
      * mutate `process.env` mid-run see the new value on the next read.
      *
@@ -332,6 +343,10 @@ declare class ConfigurationManager extends BaseManager {
      * @throws  When the bare `$VAR` form references an unset env var.
      */
     private resolveEnvRef;
+    /** A string inside a map or list (#1889): `$$` escapes, a bare `$NAME` resolves strictly, anything else is itself. */
+    private resolveNestedRef;
+    /** The variable a bare `$NAME` reference names; throws, naming the key or path, when it is unset (#775). */
+    private readEnvRef;
     /** Audit counters for the boot-time env-ref summary log (#775). */
     private _envRefHitCount;
     private _envRefMissCount;

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>`. */
@@ -46,6 +35,15 @@ export interface DatabaseBackupData {
         name: string;
         error: string;
     }>;
+    /**
+     * #1892 D2: in a restore's safety backup taken while the application
+     * database can't be opened, the databases left out and why. The restore
+     * keeps their files beside the restored ones, as `*.pre-restore`.
+     */
+    leftOut?: {
+        databases: string[];
+        reason: string;
+    };
 }
 /** What an add-on hands over to have its database opened and migrated. */
 export interface AddonDatabaseOptions {
@@ -82,12 +80,37 @@ 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. */
+    private unavailable;
     constructor(engine: WikiEngine);
     initialize(config?: Record<string, unknown>): Promise<void>;
     /** Whether an application database is open. */
     isEnabled(): boolean;
+    /**
+     * Why the configured application database is not open (#1892): it could not
+     * be opened safely, and the site is in maintenance mode. Null when it is
+     * open, or when none is configured (`ngdpbase.database.provider` `none`).
+     * A manager that needs the database asks this and holds its work.
+     */
+    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 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.
+     */
+    private markUnavailable;
+    /** The reason for a database that did not open, with the fix that fits the key (#1892). */
+    private static openFailure;
+    /** The refusal for anything that needs the application database while it is unavailable (#1892). */
+    private unavailableRefusal;
     /**
      * The open connection, for a row-storing provider's constructor. Throws when
      * no database is configured, so a provider that needs one fails at boot with
@@ -151,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;
     /**
@@ -180,7 +217,7 @@ declare class DatabaseManager extends BaseManager {
     private fault;
     private clearFault;
     private notify;
-    /** Whether every open database passes SQLite's quick check; true when none is configured. */
+    /** Whether every open database passes SQLite's quick check; true when none is configured, false when the configured one could not be opened (#1892). */
     integrityOk(): boolean;
     /** Closes the add-on databases, then the application database. */
     shutdown(): Promise<void>;