@jwilleke/ngdpbase-types 5.18.0 → 5.20.0

package/lib/src/providers/sqliteBackup.js

@@ -0,0 +1,365 @@
+/**
+ * Encrypted, consistent copies of SQLite databases, and the staged restore
+ * that puts them back (#1723). Ported from yourPHR (`sqlite-backup.ts`,
+ * yourphr#461, #602, #608, #787, #866, #914), with these changes:
+ *
+ * - __One encrypted file per database__, not one file holding every
+ *   database's tables. A restore needs no table-name split, and two databases
+ *   may hold tables of the same name.
+ * - __Every database's snapshot is taken before any copying starts.__ Each
+ *   source gets its own connection with its backup file attached; a read
+ *   transaction is opened on every one of them, back to back, and only then
+ *   are they copied. SQLite allows ten attached databases per connection, so
+ *   one connection for all of them would cap a site at five databases; this
+ *   has no cap. The live files are in WAL mode, so these readers never block
+ *   the site's writers, and a write committed after the snapshot is in none of
+ *   the copies.
+ * - `sqlite_sequence` (AUTOINCREMENT counters) and `user_version` are copied,
+ *   so a restored table never hands out an id it handed out before.
+ * - Staging writes `<live>.staged` beside each live file, the path applying
+ *   reads (yourphr#866: they were different directories), and is all or
+ *   nothing: on any failure every staged file is removed.
+ * - Applying moves the live file's `-wal` and `-shm` aside with it
+ *   (yourphr#866), so a leftover WAL can never replay onto the restored file.
+ *
+ * Every function here is synchronous SQLite and can take minutes on a large
+ * database: the managers call them through `runOffThread`, never on the thread
+ * that answers requests (yourphr#787, #914). Keys travel in `workerData`
+ * (memory), never argv or the environment.
+ */
+import { chmodSync, copyFileSync, existsSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { Worker } from 'node:worker_threads';
+/** The staged file for a live database: beside it, so staging and applying name the same path. */
+export const stagedPath = (live) => `${live}.staged`;
+/** SQLCipher key pragma escaping, as SqliteDatabaseProvider does it. */
+function quoteKey(key) {
+    return `'${key.replace(/'/g, "''")}'`;
+}
+/** Open a file the way SqliteDatabaseProvider does: SQLCipher, keyed when a key is given. */
+function openKeyed(Database, file, key) {
+    // Checked here, not with `fileMustExist`: SQLite opens an ATTACHed file with
+    // the main file's flags, and without CREATE the backup or staged file could
+    // not be made.
+    if (!existsSync(file))
+        throw new Error(`${file} does not exist`);
+    const db = new Database(file);
+    try {
+        db.pragma("cipher='sqlcipher'");
+        if (key)
+            db.pragma(`key=${quoteKey(key)}`);
+        // The first read: a wrong key fails here.
+        db.prepare('SELECT COUNT(*) AS n FROM sqlite_master').get();
+        return db;
+    }
+    catch (err) {
+        db.close();
+        throw err;
+    }
+}
+/**
+ * Copies every table (with its rows), index, trigger and view from one schema
+ * of the connection into another, inside the caller's transaction. This is
+ * sqlcipher_export(), spelled out: SQLite3MultipleCiphers does not ship it.
+ * Tables are created and filled before any index or trigger exists, so the
+ * copy fires no trigger.
+ */
+function copyObjects(db, from, to) {
+    const all = db
+        .prepare(`SELECT type, name, sql FROM ${from}.sqlite_master WHERE sql IS NOT NULL AND name NOT LIKE 'sqlite_%' ORDER BY CASE type WHEN 'table' THEN 0 WHEN 'index' THEN 1 WHEN 'trigger' THEN 2 ELSE 3 END`)
+        .all();
+    // A virtual table (FTS5) owns shadow tables, <table>_data, _idx, _content,
+    // _docsize, _config: recreating it recreates them, and creating them by hand
+    // is refused. Their rows come back through the INSERT into the virtual table.
+    const virtual = all.filter((o) => /^CREATE VIRTUAL TABLE/i.test(o.sql)).map((o) => o.name);
+    const shadow = (name) => virtual.some((v) => name.startsWith(`${v}_`));
+    let tables = 0;
+    for (const object of all) {
+        if (shadow(object.name))
+            continue;
+        // CREATE TABLE x -> CREATE TABLE to.x: the one rewrite sqlcipher_export
+        // makes. sqlite_master SQL never carries a schema prefix.
+        const ddl = object.sql.replace(/^(CREATE (?:TABLE|INDEX|UNIQUE INDEX|TRIGGER|VIEW|VIRTUAL TABLE))\s+(?:IF NOT EXISTS\s+)?("[^"]+"|\[[^\]]+\]|`[^`]+`|\S+)/i, (_m, head, name) => `${head} ${to}.${name}`);
+        db.exec(ddl);
+        if (object.type !== 'table')
+            continue;
+        tables++;
+        const quoted = `"${object.name.replace(/"/g, '""')}"`;
+        if (virtual.includes(object.name)) {
+            // A virtual table's rowids are carried explicitly: SELECT * leaves them
+            // out, and the copy would be renumbered.
+            const cols = db.prepare(`SELECT name FROM ${from}.pragma_table_info(?)`).all(object.name)
+                .map((c) => `"${c.name.replace(/"/g, '""')}"`).join(', ');
+            db.exec(`INSERT INTO ${to}.${quoted} (rowid, ${cols}) SELECT rowid, ${cols} FROM ${from}.${quoted}`);
+        }
+        else {
+            db.exec(`INSERT INTO ${to}.${quoted} SELECT * FROM ${from}.${quoted}`);
+        }
+    }
+    // AUTOINCREMENT counters: without them a restored table could hand out an
+    // id it had already used for a deleted row.
+    const hasSequence = db.prepare(`SELECT 1 FROM ${from}.sqlite_master WHERE name = 'sqlite_sequence'`).get();
+    if (hasSequence && db.prepare(`SELECT 1 FROM ${to}.sqlite_master WHERE name = 'sqlite_sequence'`).get()) {
+        db.exec(`DELETE FROM ${to}.sqlite_sequence`);
+        db.exec(`INSERT INTO ${to}.sqlite_sequence (name, seq) SELECT name, seq FROM ${from}.sqlite_sequence`);
+    }
+    const userVersion = db.pragma(`${from}.user_version`, { simple: true });
+    if (userVersion)
+        db.pragma(`${to}.user_version = ${Number(userVersion)}`);
+    return tables;
+}
+/** SQLite's full integrity check of an open database; throws naming what it found. */
+function requireIntegrity(db, what) {
+    const result = String(db.pragma('integrity_check')[0]?.integrity_check ?? 'no result');
+    if (result !== 'ok')
+        throw new Error(`${what} failed its integrity check: ${result}`);
+}
+/**
+ * Write an encrypted copy of each database under `backupKey`. A database that
+ * cannot be opened or copied is named in `failed`, its partial file removed;
+ * the others are still written. A target that already exists is never
+ * overwritten.
+ */
+export function exportDatabasesSync(Database, exports, backupKey) {
+    if (!backupKey.trim()) {
+        throw new Error('a backup key is required: database backups are always encrypted');
+    }
+    const outcome = { written: [], failed: [] };
+    const open = [];
+    const fail = (job, err, db) => {
+        try {
+            db?.close();
+        }
+        catch { /* already failing */ }
+        rmSync(job.target, { force: true });
+        outcome.failed.push({ name: job.name, error: err.message });
+    };
+    // 1. A connection per database, its backup file attached under the backup key.
+    for (const job of exports) {
+        if (existsSync(job.target)) {
+            outcome.failed.push({ name: job.name, error: `${path.basename(job.target)} already exists; a backup never overwrites one` });
+            continue;
+        }
+        let db;
+        try {
+            db = openKeyed(Database, job.source, job.sourceKey);
+            db.prepare(`ATTACH DATABASE ? AS backup KEY ${quoteKey(backupKey)}`).run(job.target);
+            open.push({ job, db });
+        }
+        catch (err) {
+            fail(job, err, db);
+        }
+    }
+    // 2. Every snapshot, back to back, before any copying: one point in time.
+    const reading = [];
+    for (const entry of open) {
+        try {
+            entry.db.exec('BEGIN');
+            entry.db.prepare('SELECT COUNT(*) AS n FROM main.sqlite_master').get();
+            reading.push(entry);
+        }
+        catch (err) {
+            fail(entry.job, err, entry.db);
+        }
+    }
+    // 3. Copy each, then close and prove the copy opens under the backup key.
+    for (const { job, db } of reading) {
+        try {
+            const tables = copyObjects(db, 'main', 'backup');
+            db.exec('COMMIT');
+            db.close();
+            const check = openKeyed(Database, job.target, backupKey);
+            try {
+                requireIntegrity(check, `the backup of ${job.name}`);
+            }
+            finally {
+                check.close();
+            }
+            chmodSync(job.target, 0o600);
+            outcome.written.push({ name: job.name, target: job.target, sizeBytes: statSync(job.target).size, tables });
+        }
+        catch (err) {
+            try {
+                if (db.inTransaction)
+                    db.exec('ROLLBACK');
+            }
+            catch { /* closing anyway */ }
+            fail(job, err, db.open ? db : undefined);
+        }
+    }
+    return outcome;
+}
+/**
+ * Stage a restore: each backup file is opened under the backup key,
+ * integrity-checked, and copied into `<live>.staged` under the target
+ * database's key, which is then opened and checked too. All or nothing: if
+ * any database fails, every staged file is removed and the error names it.
+ * Live files are never touched.
+ */
+export function stageDatabasesSync(Database, stages, backupKey) {
+    if (!backupKey.trim()) {
+        throw new Error('a backup key is required to read a database backup');
+    }
+    const outcome = { staged: [] };
+    try {
+        for (const stage of stages) {
+            const staged = stagedPath(stage.live);
+            rmSync(staged, { force: true });
+            let db;
+            try {
+                db = openKeyed(Database, stage.backupFile, backupKey);
+            }
+            catch (err) {
+                throw new Error(`the backup of ${stage.name} cannot be read — wrong backup key, or not a backup: ${err.message}`, { cause: err });
+            }
+            let tables;
+            try {
+                requireIntegrity(db, `the backup of ${stage.name}`);
+                db.prepare(`ATTACH DATABASE ? AS staged KEY ${quoteKey(stage.targetKey)}`).run(staged);
+                db.exec('BEGIN');
+                try {
+                    tables = copyObjects(db, 'main', 'staged');
+                    db.exec('COMMIT');
+                }
+                catch (err) {
+                    db.exec('ROLLBACK');
+                    throw err;
+                }
+            }
+            finally {
+                db.close();
+            }
+            const check = openKeyed(Database, staged, stage.targetKey);
+            try {
+                requireIntegrity(check, `the staged copy of ${stage.name}`);
+            }
+            finally {
+                check.close();
+            }
+            chmodSync(staged, 0o600);
+            outcome.staged.push({ name: stage.name, staged, live: stage.live, tables });
+        }
+        return outcome;
+    }
+    catch (err) {
+        for (const stage of stages)
+            rmSync(stagedPath(stage.live), { force: true });
+        throw err;
+    }
+}
+export function runOffThread(job, timeoutMs) {
+    // Compiled, the worker is the .js beside this file. From source (vitest,
+    // tsx) it is the .ts, which needs tsx's loader.
+    const fromSource = import.meta.url.endsWith('.ts');
+    const entry = new URL(fromSource ? './sqliteBackupWorker.ts' : './sqliteBackupWorker.js', import.meta.url);
+    return new Promise((resolve, reject) => {
+        const driver = createRequire(import.meta.url).resolve('better-sqlite3-multiple-ciphers');
+        const workerData = { ...job, driver };
+        const worker = new Worker(entry, { workerData, ...(fromSource ? { execArgv: ['--import', 'tsx'] } : {}) });
+        let settled = false;
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            fn();
+        };
+        const timer = setTimeout(() => {
+            settle(() => reject(new Error(`the database ${job.kind === 'export' ? 'backup' : 'restore'} did not finish within ${timeoutMs} ms (ngdpbase.database.backup.worker-timeout-ms) and was stopped`)));
+            void worker.terminate();
+        }, timeoutMs);
+        worker.once('message', (m) => {
+            settle(() => (m.ok ? resolve(m.result) : reject(new Error(m.error))));
+        });
+        worker.once('error', (err) => settle(() => reject(err)));
+        worker.once('exit', (code) => settle(() => reject(new Error(`the database backup worker exited (code ${code}) without a result`))));
+    });
+}
+/** Where the manifest of a staged restore lives: beside the application database. */
+export const manifestPath = (applicationFile) => `${applicationFile}.restore.json`;
+export function writeManifest(file, manifest) {
+    const tmp = `${file}.tmp`;
+    writeFileSync(tmp, JSON.stringify(manifest, null, 2) + '\n', { mode: 0o600 });
+    renameSync(tmp, file);
+}
+/**
+ * Apply a staged restore at start, before any database opens. Each live file,
+ * with its `-wal` and `-shm`, steps aside as `*.pre-restore` (`-wal`/`-shm`
+ * beside it, so the kept copy still opens as it was), and the staged file
+ * takes its name. A rename, never a write into a live database.
+ *
+ * All or nothing: if any database the manifest names is not staged, nothing
+ * is applied; what is staged is renamed `*.incomplete`, so it is neither
+ * applied nor retried. A staged file with no manifest (staging was
+ * interrupted) is set aside the same way. `allowed` says which live paths may
+ * be replaced, so a tampered manifest cannot rename an arbitrary file.
+ */
+export function applyStagedRestore(applicationFile, allowed) {
+    const manifestFile = manifestPath(applicationFile);
+    const dir = path.dirname(applicationFile);
+    const stray = () => (existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith('.db.staged')).map((f) => path.join(dir, f)) : []);
+    if (!existsSync(manifestFile)) {
+        const leftovers = stray();
+        if (leftovers.length === 0)
+            return null;
+        for (const f of leftovers)
+            move(f, `${f}.incomplete`);
+        return { applied: [], refused: `staged database files with no restore manifest (an interrupted staging): ${leftovers.map((f) => path.basename(f)).join(', ')} — set aside as *.incomplete` };
+    }
+    const setAside = (reason) => {
+        for (const f of stray())
+            move(f, `${f}.incomplete`);
+        move(manifestFile, `${manifestFile}.incomplete`);
+        return { applied: [], refused: reason };
+    };
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(manifestFile, 'utf8'));
+    }
+    catch (err) {
+        return setAside(`the restore manifest cannot be read: ${err.message}`);
+    }
+    const entries = Array.isArray(manifest?.databases) ? manifest.databases : [];
+    const bad = entries.find((e) => !allowed(e.live) || e.staged !== stagedPath(e.live));
+    if (entries.length === 0 || bad) {
+        return setAside(bad ? `the restore manifest names ${bad.live}, which is not a database of this site` : 'the restore manifest names no database');
+    }
+    const missing = entries.filter((e) => !existsSync(e.staged));
+    if (missing.length > 0) {
+        return setAside(`only ${entries.length - missing.length} of ${entries.length} databases were staged (missing: ${missing.map((e) => e.name).join(', ')}), and they belong together`);
+    }
+    const applied = [];
+    for (const entry of entries) {
+        const kept = `${entry.live}.pre-restore`;
+        // A previous restore's kept WAL must not pair with this restore's kept file.
+        for (const sibling of [`${kept}-wal`, `${kept}-shm`])
+            rmSync(sibling, { force: true });
+        if (existsSync(entry.live)) {
+            move(entry.live, kept);
+            for (const suffix of ['-wal', '-shm']) {
+                if (existsSync(`${entry.live}${suffix}`))
+                    move(`${entry.live}${suffix}`, `${kept}${suffix}`);
+            }
+        }
+        // Never a WAL beside the restored file that is not its own.
+        for (const suffix of ['-wal', '-shm'])
+            rmSync(`${entry.live}${suffix}`, { force: true });
+        move(entry.staged, entry.live);
+        applied.push({ name: entry.name, live: entry.live, kept });
+    }
+    unlinkSync(manifestFile);
+    return { applied };
+}
+/** A rename; a copy and unlink when the two paths are on different devices. */
+function move(from, to) {
+    try {
+        renameSync(from, to);
+    }
+    catch (err) {
+        if (err.code !== 'EXDEV')
+            throw err;
+        copyFileSync(from, to);
+        unlinkSync(from);
+    }
+}

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,12 @@
  * 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`.
  */
 import { type AddonDatabaseDeclaration } from './addonDatabaseRules.js';
 export declare const ADDONS_PATH_KEY = "ngdpbase.managers.addons-manager.addons-path";
@@ -78,6 +84,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 +100,25 @@ 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;
+/** 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 +135,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 +147,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 +158,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>;

package/lib/src/utils/addonConfigLayer.js

@@ -40,6 +40,12 @@
  * 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`.
  */
 import fs from 'fs';
 import path from 'path';
@@ -127,6 +133,10 @@ export function discoverAddonDefaults(base, cwd = process.cwd(), dataFolder = in
     }
     return out;
 }
+/** How a problem line names an addon; AddonsManager matches it to fold a refusal into its load-failure notice (#1883). */
+export function addonProblemSubject(slug, enabled) {
+    return `add-on '${slug}'${enabled ? '' : ' (turned off)'}`;
+}
 function vaultIdOf(entry) {
     return parsePrivatestore(entry?.storageLocation?.privatestore)?.vaultId;
 }
@@ -154,7 +164,7 @@ function addonCategoryLayer(shipped, custom, addons) {
         const declared = addon.defaults[SYSTEM_CATEGORY_KEY];
         if (declared === undefined)
             continue;
-        const who = `add-on '${addon.slug}'${addon.enabled ? '' : ' (turned off)'}`;
+        const who = addonProblemSubject(addon.slug, addon.enabled);
         if (!isPlainObject(declared)) {
             const reason = `${SYSTEM_CATEGORY_KEY} must be a map of entries`;
             layer.problems.push(`${who}: ${reason}; it is refused and the add-on is not loaded`);
@@ -246,7 +256,7 @@ export function addonDatabaseLayer(addons, custom) {
             }
         }
         if (reasons.length > 0) {
-            const who = `add-on '${addon.slug}'${addon.enabled ? '' : ' (turned off)'}`;
+            const who = addonProblemSubject(addon.slug, addon.enabled);
             layer.problems.push(`${who}: its database declaration is refused (${reasons.join('; ')}); the add-on is not loaded`);
             layer.refused.set(addon.slug, `its database declaration was refused: ${reasons.join('; ')}`);
             continue;
@@ -262,6 +272,45 @@ export function addonDatabaseLayer(addons, custom) {
     }
     return layer;
 }
+/** The configuration key that makes an addon site-critical (#1883). */
+export function addonSiteCriticalKey(slug) {
+    return `ngdpbase.addons.${slug}.site-critical`;
+}
+/**
+ * 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 function addonSiteCriticalLayer(addons, custom) {
+    const layer = { siteCritical: new Map(), refused: new Map(), problems: [] };
+    const take = (slug, enabled, own) => {
+        const key = addonSiteCriticalKey(slug);
+        const fromSite = custom[key] !== undefined;
+        const value = fromSite ? custom[key] : own;
+        if (value === undefined)
+            return;
+        if (typeof value === 'boolean') {
+            layer.siteCritical.set(slug, value);
+            return;
+        }
+        const reason = `${key} must be true or false, got ${JSON.stringify(value)} in ${fromSite ? 'app-custom-config.json' : 'its config/default-config.json'}; it is treated as true`;
+        layer.siteCritical.set(slug, true);
+        layer.refused.set(slug, reason);
+        layer.problems.push(`${addonProblemSubject(slug, enabled)}: ${reason}; the add-on is not loaded`);
+    };
+    for (const addon of addons)
+        take(addon.slug, addon.enabled, addon.defaults[addonSiteCriticalKey(addon.slug)]);
+    for (const key of Object.keys(custom)) {
+        const slug = /^ngdpbase\.addons\.([^.]+)\.site-critical$/.exec(key)?.[1];
+        if (slug && !layer.siteCritical.has(slug))
+            take(slug, custom[`ngdpbase.addons.${slug}.enabled`] === true, undefined);
+    }
+    return layer;
+}
 /**
  * The owner's declaration stands (operator, 2026-09-29): for each entry an
  * addon declared, the fields in OWNER_DECIDED_FIELDS are the addon's, never
@@ -310,8 +359,10 @@ export function mergeWithAddonLayer(shipped, addons, custom) {
     const customCategories = custom[SYSTEM_CATEGORY_KEY];
     const layer = addonCategoryLayer(shipped[SYSTEM_CATEGORY_KEY], customCategories, addons);
     const databaseLayer = addonDatabaseLayer(addons, custom);
+    const criticalLayer = addonSiteCriticalLayer(addons, custom);
+    const siteCritical = criticalLayer.siteCritical;
     const refused = new Map(layer.refused);
-    for (const [slug, reason] of databaseLayer.refused)
+    for (const [slug, reason] of [...databaseLayer.refused, ...criticalLayer.refused])
         refused.set(slug, refused.has(slug) ? `${refused.get(slug)}; ${reason}` : reason);
     const databases = databaseLayer.declarations.map((d) => ({ ...d, enabled: d.enabled && !refused.has(d.declaredBy) }));
     const withAddons = addons
@@ -325,14 +376,14 @@ export function mergeWithAddonLayer(shipped, addons, custom) {
         return deepMergeObjects(acc, rest);
     }, shipped);
     if (Object.keys(layer.entries).length === 0) {
-        return { merged: deepMergeConfigs(withAddons, custom), problems: [...layer.problems, ...databaseLayer.problems], refused, databases };
+        return { merged: deepMergeConfigs(withAddons, custom), problems: [...layer.problems, ...databaseLayer.problems, ...criticalLayer.problems], refused, databases, siteCritical };
     }
     const shippedCategories = isPlainObject(withAddons[SYSTEM_CATEGORY_KEY]) ? withAddons[SYSTEM_CATEGORY_KEY] : {};
     const layered = { ...withAddons, [SYSTEM_CATEGORY_KEY]: deepMergeObjects(shippedCategories, layer.entries) };
     const merged = deepMergeObjects(layered, custom);
     const stood = ownerDeclarationsStand(merged[SYSTEM_CATEGORY_KEY], layer, customCategories);
     merged[SYSTEM_CATEGORY_KEY] = stood.categories;
-    return { merged: merged, problems: [...layer.problems, ...stood.problems, ...databaseLayer.problems], refused, databases };
+    return { merged: merged, problems: [...layer.problems, ...stood.problems, ...databaseLayer.problems, ...criticalLayer.problems], refused, databases, siteCritical };
 }
 /**
  * The full merge for a caller with the two files already read (the manager,
@@ -344,12 +395,14 @@ export function mergeWithAddonLayer(shipped, addons, custom) {
  * 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 function mergeConfigWithAddons(shipped, custom, cwd = process.cwd(), dataFolder = instanceDataFolder()) {
     const base = deepMergeConfigs(shipped, custom);
     const all = discoverAddonDefaults(base, cwd, dataFolder);
-    const { merged, problems, refused, databases } = mergeWithAddonLayer(shipped, all, custom);
+    const { merged, problems, refused, databases, siteCritical } = mergeWithAddonLayer(shipped, all, custom);
     const unreadable = all
         .filter((a) => !a.enabled && a.error)
         .map((a) => `add-on '${a.slug}' (turned off): config/default-config.json could not be read (${a.error}); its system-categories and database are not known`);
@@ -359,7 +412,8 @@ export function mergeConfigWithAddons(shipped, custom, cwd = process.cwd(), data
         addons: all.filter((a) => a.enabled && !refused.has(a.slug)),
         problems: [...unreadable, ...problems],
         refused,
-        databases
+        databases,
+        siteCritical
     };
 }
 /**

package/lib/src/utils/auditEventNames.generated.d.ts

@@ -34,6 +34,12 @@ export declare const AUDIT_EVENT: {
     readonly AUTHORIZATION_DENY: "authorization-deny";
     /** A full backup written; where it went and who asked */
     readonly BACKUP_CREATE: "backup-create";
+    /** A restore of a backup's databases started from Admin → Backup: which backup and who asked; recorded before the fresh backup and the staging, which cannot proceed without it (#1723) */
+    readonly BACKUP_RESTORE: "backup-restore";
+    /** A staged database restore cancelled before the restart applied it: which backup, who staged it and who cancelled; recorded first, which cannot proceed without it (#1723) */
+    readonly BACKUP_RESTORE_CANCEL: "backup-restore-cancel";
+    /** A staged database restore replaced by another before the restart applied it: which backup replaced which, and who asked; recorded first, which cannot proceed without it (#1723) */
+    readonly BACKUP_RESTORE_REPLACE: "backup-restore-replace";
     /** Comment added to a page — user content written on someone's behalf, the page-edit class (#1232) */
     readonly COMMENT_CREATE: "comment-create";
     /** Comment marked deleted; who removed it and whose it was (#1232) */

package/lib/src/utils/auditEventNames.generated.js

@@ -41,6 +41,12 @@ export const AUDIT_EVENT = {
     AUTHORIZATION_DENY: 'authorization-deny',
     /** A full backup written; where it went and who asked */
     BACKUP_CREATE: 'backup-create',
+    /** A restore of a backup's databases started from Admin → Backup: which backup and who asked; recorded before the fresh backup and the staging, which cannot proceed without it (#1723) */
+    BACKUP_RESTORE: 'backup-restore',
+    /** A staged database restore cancelled before the restart applied it: which backup, who staged it and who cancelled; recorded first, which cannot proceed without it (#1723) */
+    BACKUP_RESTORE_CANCEL: 'backup-restore-cancel',
+    /** A staged database restore replaced by another before the restart applied it: which backup replaced which, and who asked; recorded first, which cannot proceed without it (#1723) */
+    BACKUP_RESTORE_REPLACE: 'backup-restore-replace',
     /** Comment added to a page — user content written on someone's behalf, the page-edit class (#1232) */
     COMMENT_CREATE: 'comment-create',
     /** Comment marked deleted; who removed it and whose it was (#1232) */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.18.0",
+  "version": "5.20.0",
   "description": "TypeScript types for ngdpbase add-ons, and a test kit of core's own values. A dev dependency, versioned with ngdpbase.",
   "license": "Apache-2.0",
   "author": "Jim Willeke",