@jwilleke/ngdpbase-types 5.18.0 → 5.20.0

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

@@ -17,6 +17,11 @@ 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
@@ -280,6 +285,8 @@ declare class AddonsManager extends BaseManager {
     private dashboardCards;
     /** Name of the first domain addon loaded — only one is permitted */
     private domainAddonName;
+    /** #1883: the enabled add-ons that did not load this start, with why — each reported once. */
+    private readonly loadFailures;
     constructor(engine: WikiEngine);
     /**
      * Initialize the AddonsManager
@@ -351,6 +358,30 @@ declare class AddonsManager extends BaseManager {
      * bundled/drop-in addon wins.
      */
     private registerAddonFromDir;
+    /**
+     * Register an add-on that will not be loaded, so Admin → Add-ons shows it
+     * with the reason, and report it when it is enabled (#1883). The first
+     * add-on of a slug wins, as for a loadable one.
+     */
+    private refuseAddon;
+    /**
+     * #1883 (operator, 2026-10-18): the one rule for an enabled add-on that does
+     * 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
+     * add-on per start. Nothing is opened in its place.
+     */
+    private recordLoadFailure;
+    /**
+     * #1883: an enabled add-on that discovery never found — its install failed
+     * (#1830), or only a stray folder answers it — did not load either.
+     */
+    private reportUndiscoveredAddons;
+    /** A notification to administrators; best-effort, like recordSeedFailure. */
+    private notifyAdmins;
     /**
      * Why an addon cannot run on this core (#1757): its manifest's `minVersion`
      * is newer than this release. Null when it can, or when it states none.

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

@@ -1052,6 +1052,15 @@ declare class AuthManager extends BaseManager {
     unlockVaults(username: string, password: string): Promise<string | undefined>;
     private vaultUnlocker;
     private warnedNoUnlocker;
+    /**
+     * The stored spelling of a username a sign-in brought (#1882), or null when
+     * no account has it. Lookups compare normalized (#1436), so "ADMIN" finds
+     * admin's record; the session, the audit record, the roles and the vault
+     * paths must carry the stored name, never the typed variant, which is a
+     * roleless twin. The one rule, asked by every door a sign-in passes:
+     * `authenticate`, `beginTwoStep` and `completeSignIn`.
+     */
+    private storedUsername;
     /** A fresh session for a sign-in (#1043); the one already on it ends first (#1626, #1670). */
     private regenerate;
     /**
@@ -1109,7 +1118,7 @@ declare class AuthManager extends BaseManager {
         ip?: string;
         userAgent?: string;
         privateStoreHandle?: string;
-    }): string;
+    }): Promise<string>;
     /** The pending sign-in, for the browser that started it; null when gone, expired, or another browser. */
     pendingSignIn(handle: string | undefined, binding: string | undefined): PendingSignIn | null;
     /**

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

@@ -18,6 +18,7 @@ import { type PathPreflightResult, type PathPreflightOptions } from '../utils/Pa
 import type { WikiEngine } from '../types/WikiEngine.js';
 import type { ManagerFetchOptions } from '../utils/managerUtils.js';
 import type { FormOption } from '../utils/pluginFormatters.js';
+import type { ActorContext } from '../context/ActorContext.js';
 /**
  * Backup data structure returned by backup() method
  */
@@ -34,9 +35,44 @@ export interface BackupData {
     providerBackup?: unknown;
     /** Optional note about the backup */
     note?: string;
+    /**
+     * Parts of this manager's backup that failed while the rest was written
+     * (#1723) — a database that could not be copied, say. BackupManager tells the
+     * admins about each one: a backup is never silently partial.
+     */
+    warnings?: string[];
     /** Allow additional properties */
     [key: string]: unknown;
 }
+/**
+ * What BackupManager hands each manager's `backup()` (#1723): who asked, and
+ * where the backup document is being written. A manager whose data is too
+ * large for the JSON document (the databases) writes its own files into
+ * `directory`, each named `<stem>.<something>`, and references them from its
+ * entry; BackupManager prunes them with the document.
+ */
+export interface ManagerBackupOptions {
+    ctx: ActorContext;
+    /** The backup directory the document is written to. */
+    directory: string;
+    /** The document's filename without `.json.gz` / `.json`. */
+    stem: string;
+}
+/** What BackupManager hands each manager's `restore()` (#1723): who asked, and the directory the backup document was read from. */
+export interface ManagerRestoreOptions {
+    ctx: ActorContext;
+    directory: string;
+    /** The backup document's filename. */
+    source?: string;
+    /**
+     * Replace what an earlier restore staged and the restart has not applied
+     * yet (#1723, D5). Without it a manager that stages refuses, so a staged
+     * restore is never replaced silently.
+     */
+    replaceStaged?: boolean;
+    /** The backup of the live data BackupManager took just before this restore (#1723, D6), by filename. */
+    safetyBackup?: string;
+}
 /**
  * Base class for all managers
  *
@@ -279,7 +315,7 @@ declare abstract class BaseManager {
      *   };
      * }
      */
-    backup(): Promise<BackupData>;
+    backup(_options?: ManagerBackupOptions): Promise<BackupData>;
     /**
      * Restore manager data from backup
      *
@@ -298,7 +334,7 @@ declare abstract class BaseManager {
      *   this.settings = backupData.data.settings;
      * }
      */
-    restore(backupData: BackupData): Promise<void>;
+    restore(backupData: BackupData, _options?: ManagerRestoreOptions): Promise<void>;
     /**
      * Return a plain-text string suitable for use as MarqueePlugin banner text.
      *

package/lib/src/managers/BaseManager.js

@@ -265,7 +265,7 @@ class BaseManager {
      *   };
      * }
      */
-    async backup() {
+    async backup(_options) {
         // Default implementation returns empty object
         // Managers with data MUST override this method
         return {
@@ -292,7 +292,7 @@ class BaseManager {
      *   this.settings = backupData.data.settings;
      * }
      */
-    async restore(backupData) {
+    async restore(backupData, _options) {
         // Default implementation does nothing
         // Managers with data MUST override this method
         if (!backupData) {

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

@@ -60,10 +60,12 @@ declare class ConfigurationManager extends BaseManager {
     private addonLayers;
     /** #1559: add-on system-categories refused, and operator values an owner's declaration overrode; #1860: database declarations refused or overridden. */
     private systemCategoryProblems;
-    /** #1559: add-ons that must not load because an entry they declare was refused, by slug, with why; #1860: or their database declaration. */
+    /** #1559: add-ons that must not load because an entry they declare was refused, by slug, with why; #1860: or their database declaration; #1883: or a site-critical value that is not a boolean. */
     private refusedAddons;
     /** #1860: every installed add-on's sound database declaration, on or off. */
     private addonDatabases;
+    /** #1883: which add-ons put the site in maintenance mode when they fail to load, by slug. */
+    private siteCriticalAddons;
     private environment;
     private defaultConfigPath;
     private customConfigPath;
@@ -282,6 +284,14 @@ declare class ConfigurationManager extends BaseManager {
      * ({@link getAddonRefusal}). DatabaseManager is the reader.
      */
     getAddonDatabaseDeclarations(): readonly AddonDatabaseDeclaration[];
+    /**
+     * #1883: whether this add-on's failure to load puts the whole site in
+     * maintenance mode — `ngdpbase.addons.<slug>.site-critical`, from the
+     * operator's file or else the add-on's own, read even when the add-on was
+     * refused. A value that is not exactly true or false counts as true (and
+     * refuses the add-on, {@link getAddonRefusal}).
+     */
+    isAddonSiteCritical(slug: string): boolean;
     /**
      * #1813: what one enabled addon's own `config/default-config.json` declares,
      * exactly as it was folded into the merge — not the merged view, so the

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

@@ -1,9 +1,52 @@
 import BaseManager from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.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";
+/** 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>`. */
+    name: string;
+    kind: 'application' | 'addon';
+    owner?: string;
+    /** The encrypted file beside the backup document: `<stem>.<name>.db`. */
+    file: string;
+    sizeBytes: number;
+    tables: number;
+}
+/** DatabaseManager's `data` in a backup document. */
+export interface DatabaseBackupData {
+    format: 1;
+    /** `backupKeyFingerprint()` of the key the files are encrypted under. */
+    keyFingerprint?: string;
+    databases: DatabaseBackupEntry[];
+    /** Declared databases with no file yet (an add-on that never opened it). */
+    absent: string[];
+    /** Databases that could not be copied; the backup carries the others. */
+    failed: Array<{
+        name: string;
+        error: string;
+    }>;
+}
 /** What an add-on hands over to have its database opened and migrated. */
 export interface AddonDatabaseOptions {
     /** Dated migrations, strictly ascending by id — the same rules as core's ledger. */
@@ -37,6 +80,10 @@ declare class DatabaseManager extends BaseManager {
     private databaseFile;
     private busyTimeoutMs;
     private readonly addonDatabases;
+    /** What the start did with a staged restore (#1723), reported once the notifications exist. */
+    private restoreAtStart;
+    /** Why this manager is degraded, one entry per cause, so one cause clearing leaves the others. */
+    private readonly faults;
     constructor(engine: WikiEngine);
     initialize(config?: Record<string, unknown>): Promise<void>;
     /** Whether an application database is open. */
@@ -81,6 +128,58 @@ declare class DatabaseManager extends BaseManager {
     private declarations;
     /** The one rule: a database declared `encrypt: "required"` is never opened without the key. */
     private static keyRefusal;
+    /**
+     * Copy every database into the backup BackupManager is writing: the
+     * application database and every declared add-on database, on or off, at
+     * one point in time, on a worker thread. Each goes into its own file,
+     * `<stem>.<name>.db`, beside the document, encrypted under
+     * `NGDPBASE_BACKUP_KEY`; the document references them. A database that
+     * fails is named in `warnings`, and the others are still written.
+     *
+     * Throws when there is no backup key: nothing is ever written unencrypted.
+     */
+    backup(options?: ManagerBackupOptions): Promise<BackupData>;
+    /**
+     * Stage a restore of the databases in a backup, for the next start. Each
+     * backed-up database is opened under the backup key, integrity-checked, and
+     * copied into `<live>.staged` under this site's database key. All or
+     * nothing: if any fails, none is staged. A database the backup does not
+     * contain is left as it is. Live files are never touched here.
+     *
+     * BackupManager takes a fresh backup of the live data before calling this.
+     * A backed-up add-on database that no add-on on this site declares is not
+     * staged, and admins are told.
+     */
+    restore(backupData: BackupData, options?: ManagerRestoreOptions): Promise<void>;
+    /** The restore staged and waiting for the next start, or null. */
+    getStagedRestore(): StagedRestoreManifest | null;
+    /**
+     * Throw away a staged restore before the restart applies it (#1723, D5):
+     * the staged files and the manifest are removed, the live databases are
+     * untouched. Recorded first (`backup-restore-cancel`, refuse): a cancel that
+     * cannot be recorded does not happen.
+     */
+    cancelStagedRestore(ctx: ActorContext): Promise<StagedRestoreManifest>;
+    /**
+     * Tell admins what the start found (#1723): what it did with a staged
+     * restore, and a backup key that is missing or the database key. Called by
+     * the engine once every manager exists: DatabaseManager starts before the
+     * notifications do.
+     */
+    reportAtBoot(): Promise<void>;
+    /** The application database and every declared add-on database (one per owner), on or off. */
+    private backupSources;
+    /** Put a staged restore in place, before any database opens; loud when it cannot. */
+    private applyRestoreAtStart;
+    private backupKey;
+    /** What is wrong with the backup key: missing, or the database key itself (D3). Null when sound. */
+    private backupKeyProblem;
+    /** `ngdpbase.database.backup.worker-timeout-ms`, read at use. */
+    private workerTimeoutMs;
+    /** Degrade for one cause; the dashboard shows every cause still standing. */
+    private fault;
+    private clearFault;
+    private notify;
     /** Whether every open database passes SQLite's quick check; true when none is configured. */
     integrityOk(): boolean;
     /** Closes the add-on databases, then the application database. */