@jwilleke/ngdpbase-types 5.19.0 → 5.21.0

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

@@ -280,6 +280,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 +353,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/BackgroundJobManager.d.ts

@@ -202,6 +202,12 @@ 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. */

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 {

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;
@@ -246,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
@@ -282,6 +292,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
@@ -310,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.
      *
@@ -322,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

@@ -46,6 +46,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 {
@@ -84,10 +93,31 @@ declare class DatabaseManager extends BaseManager {
     private restoreAtStart;
     /** 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 core's
+     * survivable path (#1152): visitors see only the public message (#1883),
+     * 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
@@ -180,7 +210,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>;

package/lib/src/managers/DatabaseManager.js

@@ -14,9 +14,11 @@
  *     when `NGDPBASE_DATABASE_KEY` is set (in the environment or the instance
  *     `.env`), never from config. Without a key it opens unencrypted and says so.
  *
- * Boot refuses, naming the cause, when the file would sit on a network
- * filesystem, when the schema is from a newer build, when a migration fails,
- * or when the integrity check does not pass.
+ * The database is refused, naming the cause, when the file would sit on a
+ * network filesystem, when the schema is from a newer build, when a migration
+ * fails, when the key is missing or wrong, or when the integrity check does
+ * not pass. The process stays up (#1892): the site starts in maintenance mode
+ * and administrators are told the fix (`getUnavailableReason`).
  *
  * An add-on that keeps rows gets a database of its own the same way
  * (`openAddonDatabase`, ngdp-accounting-addons#13): its own file beside the
@@ -45,6 +47,7 @@ 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';
@@ -111,6 +114,8 @@ class DatabaseManager extends BaseManager {
     restoreAtStart = 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. */
+    unavailable = null;
     constructor(engine) {
         super(engine);
     }
@@ -133,15 +138,32 @@ class DatabaseManager extends BaseManager {
         this.busyTimeoutMs = busy;
         const file = configManager.getResolvedDataPath('ngdpbase.database.file', './data/ngdpbase.db');
         const key = process.env[DATABASE_KEY_ENV] ?? '';
+        // Known even when it does not open (#1892): a staged restore stays visible and cancellable.
+        this.databaseFile = file;
         // #1723: a staged restore goes in now, before any database opens.
-        this.applyRestoreAtStart(file);
-        const provider = new SqliteDatabaseProvider(file, key, DATABASE_MIGRATIONS, 'schema_migrations', { busyTimeoutMs: this.busyTimeoutMs });
-        if (!provider.integrityOk()) {
-            provider.close();
-            throw new Error(`The application database ${file} failed its integrity check — refusing to start (#1536)`);
+        try {
+            this.applyRestoreAtStart(file);
+        }
+        catch (err) {
+            this.markUnavailable(`A staged database restore could not be put in place: ${err.message}. ` +
+                'No database was opened. Some databases may already be restored: each one moved is kept beside it as *.pre-restore, and the rest are still *.staged beside ' +
+                `${path.basename(manifestPath(file))}. Stop the server, put the files back as they should be, and restart (#1892)`);
+            return;
+        }
+        // #1892: a database that cannot be opened safely (no key or the wrong key
+        // on an encrypted file, a damaged file, a failed migration, a newer
+        // schema) does not stop the process: the site starts in maintenance mode.
+        // The provider checks integrity before it writes anything, and a failed
+        // migration is rolled back.
+        let provider;
+        try {
+            provider = new SqliteDatabaseProvider(file, key, DATABASE_MIGRATIONS, 'schema_migrations', { busyTimeoutMs: this.busyTimeoutMs });
+        }
+        catch (err) {
+            this.markUnavailable(DatabaseManager.openFailure(file, err.message, key));
+            return;
         }
         this.provider = provider;
-        this.databaseFile = file;
         const { applied, skipped } = provider.migrations;
         logger.info(`[DatabaseManager] Opened ${file} (${key ? 'encrypted' : 'NOT encrypted'}, lock wait ${this.busyTimeoutMs} ms) — migrations applied ${applied.length}, already present ${skipped}`);
         if (!key) {
@@ -157,6 +179,47 @@ class DatabaseManager extends BaseManager {
     isEnabled() {
         return this.provider !== null;
     }
+    /**
+     * 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() {
+        return this.unavailable;
+    }
+    /**
+     * #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),
+     * administrators can sign in and reach /admin, and `reportAtBoot()` sends
+     * them the reason as a critical notification once notifications exist.
+     */
+    markUnavailable(reason) {
+        this.unavailable = reason;
+        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)
+        });
+    }
+    /** The reason for a database that did not open, with the fix that fits the key (#1892). */
+    static openFailure(file, cause, key) {
+        const keyFix = key
+            ? `If ${DATABASE_KEY_ENV} is not the key this database was made with, correct ${DATABASE_KEY_ENV} in <FAST_STORAGE>/.env (or the environment) and restart.`
+            : `${DATABASE_KEY_ENV} is not set: if the database is encrypted, set ${DATABASE_KEY_ENV} in <FAST_STORAGE>/.env (or the environment) and restart.`;
+        return `The application database ${file} could not be opened safely: ${cause.replace(/\.$/, '')}. ` +
+            'It was not opened unencrypted, and nothing further was migrated or written. ' +
+            `${keyFix} If the file itself is damaged or a migration failed, restore the databases from a backup on Admin → Backup ` +
+            '(applied at the next restart; the current file is kept beside it as *.pre-restore), or stop the server, put back a good copy ' +
+            'of the database file, and restart (#1892)';
+    }
+    /** The refusal for anything that needs the application database while it is unavailable (#1892). */
+    unavailableRefusal(what) {
+        return `The application database is not available, so ${what} — the critical notification about it says why and how to fix it (#1892)`;
+    }
     /**
      * 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
@@ -185,6 +248,8 @@ class DatabaseManager extends BaseManager {
      * set; nothing is opened in the clear.
      */
     openAddonDatabase(owner, options) {
+        if (this.unavailable)
+            throw new Error(this.unavailableRefusal(`add-on database '${owner}' is not opened`));
         if (!this.provider || !this.databaseFile) {
             throw new Error(`Add-on '${owner}' needs a database, but none is open — set ngdpbase.database.provider to 'sqlite' (ngdp-accounting-addons#13)`);
         }
@@ -208,11 +273,8 @@ class DatabaseManager extends BaseManager {
         if (path.resolve(file) === path.resolve(this.databaseFile)) {
             throw new Error(`Add-on '${owner}' would open the application database itself (${file}) (ngdp-accounting-addons#13)`);
         }
+        // Integrity is checked by the provider before anything is written (#1892).
         const provider = new SqliteDatabaseProvider(file, key, options.migrations, options.ledgerTable, { busyTimeoutMs: this.busyTimeoutMs });
-        if (!provider.integrityOk()) {
-            provider.close();
-            throw new Error(`Add-on database ${file} failed its integrity check (ngdp-accounting-addons#13)`);
-        }
         this.addonDatabases.set(owner, { provider, ledgers: new Set([options.ledgerTable]) });
         const { applied, skipped } = provider.migrations;
         logger.info(`[DatabaseManager] Opened ${file} for ${owner} (${key ? 'encrypted' : 'NOT encrypted'}) — ledger ${options.ledgerTable}, migrations applied ${applied.length}, already present ${skipped}`);
@@ -242,6 +304,9 @@ class DatabaseManager extends BaseManager {
         for (const declaration of this.declarations()) {
             if (declaration.declaredBy !== slug || !declaration.enabled)
                 continue;
+            // #1892: its database sits beside the application database, under the same key.
+            if (this.unavailable)
+                return this.unavailableRefusal(`add-on '${slug}', which declares database '${declaration.owner}', is not loaded`);
             const refusal = DatabaseManager.keyRefusal(declaration, key);
             if (refusal)
                 return refusal;
@@ -255,7 +320,7 @@ class DatabaseManager extends BaseManager {
     static keyRefusal(declaration, key) {
         if (declaration.encrypt !== 'required' || key)
             return null;
-        return `Add-on '${declaration.declaredBy}' declares database '${declaration.owner}' with encrypt "required", but ${DATABASE_KEY_ENV} is not set — it is never opened unencrypted (#1860)`;
+        return `Add-on '${declaration.declaredBy}' declares database '${declaration.owner}' with encrypt "required", but ${DATABASE_KEY_ENV} is not set — it is never opened unencrypted. Set ${DATABASE_KEY_ENV} in the environment or the instance .env (<FAST_STORAGE>/.env) and restart (#1860, #1883)`;
     }
     // ---- Backup and restore (#1723) ------------------------------------------
     /**
@@ -270,6 +335,18 @@ class DatabaseManager extends BaseManager {
      */
     async backup(options) {
         const base = { managerName: 'DatabaseManager', timestamp: new Date().toISOString() };
+        // #1892: never a backup that silently leaves the databases out. A
+        // restore's safety backup (D2) leaves them out and says so: they can't be
+        // read, and the restore keeps their files as *.pre-restore.
+        if (this.unavailable && this.databaseFile) {
+            if (!options?.safetyBackup)
+                throw new Error(this.unavailableRefusal('no database was backed up'));
+            const leftOut = this.backupSources(this.databaseFile).map((s) => s.name);
+            const note = `The databases (${leftOut.join(', ')}) are left out of this safety backup: the application database could not be opened. A restore keeps their files beside the restored ones as *.pre-restore (#1892)`;
+            logger.warn(`[DatabaseManager] ${note}`);
+            const data = { format: 1, databases: [], absent: [], failed: [], leftOut: { databases: leftOut, reason: this.unavailable } };
+            return { ...base, data, note };
+        }
         if (!this.provider || !this.databaseFile) {
             return { ...base, data: null, note: 'No application database (ngdpbase.database.provider is none)' };
         }
@@ -342,7 +419,13 @@ class DatabaseManager extends BaseManager {
             logger.info('[DatabaseManager] The backup holds no database; every database is left as it is (#1723)');
             return;
         }
-        if (!this.provider || !this.databaseFile) {
+        // #1892 D2: a restore is how a damaged database is put right, so it is
+        // allowed while the application database can't be opened, but never
+        // without the key: what it stages would then be unencrypted.
+        if (this.unavailable && !(process.env[DATABASE_KEY_ENV] ?? '')) {
+            throw new Error(`The application database is not available and ${DATABASE_KEY_ENV} is not set, so nothing was staged: a restore now would put the databases back unencrypted. Set ${DATABASE_KEY_ENV} in <FAST_STORAGE>/.env (or the environment) and restart first; if that opens the database, no restore is needed (#1892)`);
+        }
+        if (!this.databaseFile || (!this.provider && !this.unavailable)) {
             throw new Error("The backup holds databases, but this site has none open — set ngdpbase.database.provider to 'sqlite' first (#1723)");
         }
         if (!options?.directory) {
@@ -421,7 +504,10 @@ class DatabaseManager extends BaseManager {
         writeManifest(manifestFile, manifest);
         const names = stages.map((s) => s.name).join(', ');
         logger.warn(`[DatabaseManager] Restore staged for ${names} — restart to apply it (#1723)`);
-        await this.notify('warning', 'A database restore is staged', `The databases ${names} from the backup taken ${manifest.backup} are staged. Restart the site to put them in place; the current files are kept as *.pre-restore.${manifest.safetyBackup ? ` The current data was backed up first, as ${manifest.safetyBackup}.` : ''}`);
+        const unopened = this.unavailable
+            ? ' The application database could not be opened, so that safety backup leaves the databases out; the current database files are kept as *.pre-restore instead.'
+            : '';
+        await this.notify('warning', 'A database restore is staged', `The databases ${names} from the backup taken ${manifest.backup} are staged. Restart the site to put them in place; the current files are kept as *.pre-restore.${manifest.safetyBackup ? ` The current data was backed up first, as ${manifest.safetyBackup}.` : ''}${unopened}`);
         if (skipped.length > 0) {
             const message = `The backup also holds ${skipped.join(', ')}, which no add-on on this site declares, so they were not restored. Install the add-on and restore again to bring them back.`;
             logger.error(`[DatabaseManager] ${message}`);
@@ -476,6 +562,9 @@ class DatabaseManager extends BaseManager {
      * notifications do.
      */
     async reportAtBoot() {
+        if (this.unavailable) {
+            await this.notify('error', 'Critical: the application database is not available', `${this.unavailable}. Until then the site is in maintenance mode: visitors see a short notice with no details, and administrators can still sign in and use /admin.`);
+        }
         const keyProblem = this.provider ? this.backupKeyProblem() : null;
         if (keyProblem)
             await this.notify('error', 'Databases are not safely backed up', keyProblem);
@@ -566,8 +655,10 @@ class DatabaseManager extends BaseManager {
             logger.error(`[DatabaseManager] The notification '${title}' could not be sent (#1723):`, err);
         }
     }
-    /** 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() {
+        if (this.unavailable)
+            return false;
         if (this.provider && !this.provider.integrityOk())
             return false;
         for (const { provider } of this.addonDatabases.values()) {

package/lib/src/providers/SqliteDatabaseProvider.d.ts

@@ -35,6 +35,9 @@ declare class SqliteDatabaseProvider extends BaseDatabaseProvider<SqliteHandle>
     constructor(file: string, key: string, ledger: Migration[], ledgerTable?: string, options?: {
         busyTimeoutMs?: number;
     });
+    private static unlock;
+    /** Read an existing file read-only: the key opens it and it passes the quick check, or this throws. */
+    private static probe;
     /**
      * Run a further migration ledger on this connection, recorded in its own
      * table: an add-on that depends on the add-on owning this database brings
@@ -49,6 +52,8 @@ declare class SqliteDatabaseProvider extends BaseDatabaseProvider<SqliteHandle>
         encrypted: boolean;
     };
     integrityOk(): boolean;
+    /** SQLite's quick check; throws what the driver throws (a wrong key: "file is not a database"). */
+    private quickCheckOk;
     getDurability(): ProviderDurability;
     close(): void;
 }

package/lib/src/providers/SqliteDatabaseProvider.js

@@ -36,14 +36,17 @@ class SqliteDatabaseProvider extends BaseDatabaseProvider {
         super();
         this.file = file;
         refuseNetworkFilesystem(file);
+        // #1892: an existing file is first read through a read-only connection.
+        // A wrong or missing key, or a damaged file, fails there, and nothing is
+        // written: a read-write connection that fails to read still checkpoints
+        // the WAL into the file on close, or deletes a WAL it can't parse. Only
+        // the -shm index, which SQLite rebuilds from the WAL, may be rewritten.
+        if (existsSync(file))
+            SqliteDatabaseProvider.probe(file, key);
         this.db = new Database(file, { timeout: options.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS });
         this.encrypted = key !== '';
         try {
-            if (this.encrypted) {
-                this.db.pragma("cipher='sqlcipher'");
-                this.db.pragma(`key='${key.replace(/'/g, "''")}'`);
-            }
-            // The first read: a wrong key fails here, before anything is written.
+            SqliteDatabaseProvider.unlock(this.db, key);
             this.db.pragma('journal_mode = WAL');
             this.db.pragma('synchronous = FULL');
             this.migrations = runMigrations(this.db, ledger, ledgerTable);
@@ -53,6 +56,26 @@ class SqliteDatabaseProvider extends BaseDatabaseProvider {
             throw err;
         }
     }
+    static unlock(db, key) {
+        if (!key)
+            return;
+        db.pragma("cipher='sqlcipher'");
+        db.pragma(`key='${key.replace(/'/g, "''")}'`);
+    }
+    /** Read an existing file read-only: the key opens it and it passes the quick check, or this throws. */
+    static probe(file, key) {
+        const db = new Database(file, { readonly: true, fileMustExist: true });
+        try {
+            SqliteDatabaseProvider.unlock(db, key);
+            const rows = db.pragma('quick_check');
+            if (String(rows[0]?.quick_check ?? '').toLowerCase() !== 'ok') {
+                throw new Error(`The database ${file} failed its integrity check — nothing was migrated or written`);
+            }
+        }
+        finally {
+            db.close();
+        }
+    }
     /**
      * Run a further migration ledger on this connection, recorded in its own
      * table: an add-on that depends on the add-on owning this database brings
@@ -70,13 +93,17 @@ class SqliteDatabaseProvider extends BaseDatabaseProvider {
     }
     integrityOk() {
         try {
-            const rows = this.db.pragma('quick_check');
-            return String(rows[0]?.quick_check ?? '').toLowerCase() === 'ok';
+            return this.quickCheckOk();
         }
         catch {
             return false;
         }
     }
+    /** SQLite's quick check; throws what the driver throws (a wrong key: "file is not a database"). */
+    quickCheckOk() {
+        const rows = this.db.pragma('quick_check');
+        return String(rows[0]?.quick_check ?? '').toLowerCase() === 'ok';
+    }
     getDurability() {
         return { bufferedForMs: 0, bufferedRecords: 0, fsync: true };
     }

package/lib/src/types/WikiEngine.d.ts

@@ -102,10 +102,21 @@ export interface WikiEngine {
      * the repair, instead of exiting and leaving the filesystem as the only way
      * back. Only for values an administrator can fix through the admin UI; a
      * failure of the machinery needed to serve that UI is fatal and still throws.
+     * Also a site-critical add-on that did not load (#1883, operator
+     * 2026-10-18): its fix may lie outside the UI (a key in the instance .env),
+     * and the admin notification says so.
      */
-    blockConfiguration(reason: string): void;
+    blockConfiguration(reason: string, options?: {
+        publicMessage?: string;
+    }): void;
     /** Configuration values that could not be used, in the order found (#1152). */
     getBlockingConditions(): readonly string[];
+    /**
+     * What visitors see in place of the reasons, when a reason was recorded with
+     * a `publicMessage` (#1883: a site-critical add-on that did not load); null
+     * when every reason may be shown.
+     */
+    getPublicBlockingMessage(): string | null;
     /**
      * Get all registered manager names
      * @returns Array of manager names

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

@@ -40,6 +40,17 @@
  * never merged into the configuration: DatabaseManager reads the declarations
  * from here, so the operator's file cannot change one. An invalid declaration
  * stops its addon loading, as a refused system-category does.
+ *
+ * A third, `ngdpbase.addons.<slug>.site-critical` (#1883): whether a failure of
+ * the addon to load puts the whole site in maintenance mode. Read from the
+ * addon's own file and from the operator's, which wins either way, and kept
+ * apart from the merge so a refused addon's value is still known. A value that
+ * is not exactly `true` or `false` refuses the addon and counts as `true`.
+ *
+ * A fourth, `ngdpbase.config.sensitive-values` (#1889): an enabled addon may
+ * classify only its own keys, `ngdpbase.addons.<slug>` and what is under it
+ * (paths inside its values included). An entry for any other key refuses the
+ * addon, since it could unhide core's or another addon's secret.
  */
 import { type AddonDatabaseDeclaration } from './addonDatabaseRules.js';
 export declare const ADDONS_PATH_KEY = "ngdpbase.managers.addons-manager.addons-path";
@@ -78,6 +89,8 @@ export declare function discoverAddonDirs(base: Record<string, unknown>, cwd?: s
  * rather than silently skip it.
  */
 export declare function discoverAddonDefaults(base: Record<string, unknown>, cwd?: string, dataFolder?: string): AddonDefaults[];
+/** How a problem line names an addon; AddonsManager matches it to fold a refusal into its load-failure notice (#1883). */
+export declare function addonProblemSubject(slug: string, enabled: boolean): string;
 export interface AddonDatabaseLayer {
     /** Every sound declaration, of every installed addon, `enabled` as its addon is. */
     declarations: AddonDatabaseDeclaration[];
@@ -92,6 +105,39 @@ export interface AddonDatabaseLayer {
  * file: a value there for a declaration's key is ignored, and said so.
  */
 export declare function addonDatabaseLayer(addons: readonly AddonDefaults[], custom: Record<string, unknown>): AddonDatabaseLayer;
+export interface AddonSensitiveValuesLayer {
+    /** Addons with an entry for a key that is not their own, by slug, with why: never loaded. */
+    refused: Map<string, string>;
+    problems: string[];
+}
+/**
+ * Which values an addon may classify (#1889): its own, `ngdpbase.addons.<slug>`
+ * and anything under it, top-level keys and paths alike. An entry for core's
+ * keys or another addon's could unhide them (`false`, or `sensitive` for a
+ * `secret`), so it refuses the addon, as a database declaration under another
+ * slug does (#1860): it is not loaded and none of its keys apply. Only an
+ * enabled addon's entries reach the merge, so only an enabled addon is checked.
+ */
+export declare function addonSensitiveValuesLayer(addons: readonly AddonDefaults[]): AddonSensitiveValuesLayer;
+/** The configuration key that makes an addon site-critical (#1883). */
+export declare function addonSiteCriticalKey(slug: string): string;
+export interface AddonSiteCriticalLayer {
+    /** Each addon with a value, by slug: true when its failure to load puts the site in maintenance mode. */
+    siteCritical: Map<string, boolean>;
+    /** Addons whose value is not exactly `true` or `false`, by slug, with why: never loaded. */
+    refused: Map<string, string>;
+    problems: string[];
+}
+/**
+ * Which addons are site-critical (#1883): the operator's value if the
+ * operator's file sets one, else the addon's own (only under its own slug),
+ * else not. The operator's file wins in both directions, as for every addon
+ * key. The value is exactly `true` or `false`; anything else (the string
+ * `"true"` included) refuses the addon and counts as site-critical, so a
+ * mistyped value fails closed. `custom` keys for an addon with no file, or
+ * one that is not installed, count too.
+ */
+export declare function addonSiteCriticalLayer(addons: readonly AddonDefaults[], custom: Record<string, unknown>): AddonSiteCriticalLayer;
 /**
  * shipped ⊕ addons ⊕ custom, in that order of precedence (custom wins), with
  * the problems found in the addons' system-categories (#1559).
@@ -108,6 +154,7 @@ export declare function mergeWithAddonLayer<T extends Record<string, unknown>>(s
     problems: string[];
     refused: Map<string, string>;
     databases: AddonDatabaseDeclaration[];
+    siteCritical: Map<string, boolean>;
 };
 /**
  * The full merge for a caller with the two files already read (the manager,
@@ -119,7 +166,9 @@ export declare function mergeWithAddonLayer<T extends Record<string, unknown>>(s
  * could not be read; `refused` names, by slug, each addon that must not load
  * because an entry it declares was refused, and why (#1559), or because its
  * database declaration was (#1860); `databases` is every sound database
- * declaration of every installed addon, on or off (#1860).
+ * declaration of every installed addon, on or off (#1860); `siteCritical`
+ * says, by slug, which addons put the site in maintenance mode when they fail
+ * to load (#1883).
  */
 export declare function mergeConfigWithAddons<T extends Record<string, unknown>>(shipped: T, custom: Partial<T>, cwd?: string, dataFolder?: string): {
     merged: T;
@@ -128,6 +177,7 @@ export declare function mergeConfigWithAddons<T extends Record<string, unknown>>
     problems: string[];
     refused: Map<string, string>;
     databases: AddonDatabaseDeclaration[];
+    siteCritical: Map<string, boolean>;
 };
 export interface MergedConfigFiles {
     merged: Record<string, unknown>;