@jwilleke/ngdpbase-types 5.20.0 → 5.21.0

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

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

@@ -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

@@ -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;
@@ -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/utils/addonConfigLayer.d.ts

@@ -46,6 +46,11 @@
  * 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";
@@ -100,6 +105,20 @@ 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 {

package/lib/src/utils/addonConfigLayer.js

@@ -46,6 +46,11 @@
  * 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 fs from 'fs';
 import path from 'path';
@@ -53,6 +58,7 @@ import { isDeepStrictEqual } from 'util';
 import { configFilePaths, deepMergeConfigs, deepMergeObjects, instanceDataFolder, isPlainObject, readConfigFilesSync } from './configFiles.js';
 import { configuredInstallSlugs, findNodeModulesDir, installedAddonsDir, matchNpmPackageDirs, resolveAddonSlug, splitAddonsPath } from './addonsPathResolver.js';
 import { lockedAddonDirsSync } from './addonLock.js';
+import { LEGACY_SECRET_KEYS_KEY, SENSITIVE_VALUES_KEY } from './sensitiveValues.js';
 import { parsePrivatestore } from './privateStorePath.js';
 import { OWNER_DECIDED_FIELDS, SYSTEM_CATEGORY_KEY, systemCategoryValueProblems } from './systemCategoryRules.js';
 import { addonDatabaseKey, addonDatabaseKeySlug, addonDatabaseProblems } from './addonDatabaseRules.js';
@@ -272,6 +278,41 @@ export function addonDatabaseLayer(addons, custom) {
     }
     return layer;
 }
+/** Every entry an addon's file names in a sensitive-values map or the legacy list, whatever its level. */
+function sensitiveEntriesOf(defaults) {
+    const names = [];
+    for (const listKey of [SENSITIVE_VALUES_KEY, LEGACY_SECRET_KEYS_KEY]) {
+        const declared = defaults[listKey];
+        if (Array.isArray(declared))
+            names.push(...declared.filter((v) => typeof v === 'string'));
+        else if (isPlainObject(declared))
+            names.push(...Object.keys(declared));
+    }
+    return names;
+}
+/**
+ * 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 function addonSensitiveValuesLayer(addons) {
+    const layer = { refused: new Map(), problems: [] };
+    for (const addon of addons) {
+        if (!addon.enabled)
+            continue;
+        const own = `ngdpbase.addons.${addon.slug}`;
+        const foreign = sensitiveEntriesOf(addon.defaults).filter((entry) => entry.trim() !== own && !entry.trim().startsWith(`${own}.`));
+        if (foreign.length === 0)
+            continue;
+        const reason = `its sensitive-values entries ${foreign.map((e) => `'${e}'`).join(', ')} are not its own; an add-on classifies only ${own} and what is under it`;
+        layer.refused.set(addon.slug, reason);
+        layer.problems.push(`${addonProblemSubject(addon.slug, addon.enabled)}: ${reason}; the add-on is not loaded`);
+    }
+    return layer;
+}
 /** The configuration key that makes an addon site-critical (#1883). */
 export function addonSiteCriticalKey(slug) {
     return `ngdpbase.addons.${slug}.site-critical`;
@@ -360,9 +401,10 @@ export function mergeWithAddonLayer(shipped, addons, custom) {
     const layer = addonCategoryLayer(shipped[SYSTEM_CATEGORY_KEY], customCategories, addons);
     const databaseLayer = addonDatabaseLayer(addons, custom);
     const criticalLayer = addonSiteCriticalLayer(addons, custom);
+    const sensitiveLayer = addonSensitiveValuesLayer(addons);
     const siteCritical = criticalLayer.siteCritical;
     const refused = new Map(layer.refused);
-    for (const [slug, reason] of [...databaseLayer.refused, ...criticalLayer.refused])
+    for (const [slug, reason] of [...databaseLayer.refused, ...criticalLayer.refused, ...sensitiveLayer.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
@@ -376,14 +418,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, ...criticalLayer.problems], refused, databases, siteCritical };
+        return { merged: deepMergeConfigs(withAddons, custom), problems: [...layer.problems, ...databaseLayer.problems, ...criticalLayer.problems, ...sensitiveLayer.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, ...criticalLayer.problems], refused, databases, siteCritical };
+    return { merged: merged, problems: [...layer.problems, ...stood.problems, ...databaseLayer.problems, ...criticalLayer.problems, ...sensitiveLayer.problems], refused, databases, siteCritical };
 }
 /**
  * The full merge for a caller with the two files already read (the manager,

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

@@ -0,0 +1,55 @@
+/**
+ * Paths inside a configuration value (#1889).
+ *
+ * A configuration key names a value; when the value is a map or a list, each
+ * thing inside it has a path below the key: its map keys and list indices, in
+ * order. `ngdpbase.addons.accounting.accounts` → `checking` → `account-number`
+ * is written `ngdpbase.addons.accounting.accounts.checking.account-number`.
+ *
+ * Two readers walk these paths, and they walk them here, the same way:
+ *
+ *   - `ConfigurationManager` resolves a bare `$NAME` environment reference
+ *     wherever it sits in a value, naming the full path when the variable is
+ *     unset;
+ *   - `sensitiveValues` hides what `ngdpbase.config.sensitive-values` names by
+ *     a path, where `*` stands for any one map key (or list index).
+ *
+ * @module utils/configPaths
+ */
+/** A bare, whole-string environment reference: `$NAME`, upper case, digits and `_`. */
+export declare const ENV_REF_PATTERN: RegExp;
+/** The variable a bare `$NAME` reference names, or null when the value is not one. */
+export declare function envRefName(value: unknown): string | null;
+/** One path segment that stands for any map key or list index. */
+export declare const WILDCARD = "*";
+/** A key and the path below it, written as configuration keys are: dot-joined. */
+export declare function pathString(key: string, below: readonly string[]): string;
+/**
+ * Visit a value and everything inside it, top first. `visit` returns a
+ * replacement for the node, or `undefined` to keep it and go inside. Copy on
+ * write: a map or list nothing inside changed is returned as itself, so a read
+ * of a value with nothing to replace allocates nothing.
+ */
+export declare function mapConfigValue(value: unknown, visit: (node: unknown, below: readonly string[]) => unknown, below?: string[]): unknown;
+/**
+ * The segments of a path entry, or null when it is not a well-formed one: no
+ * empty segment, and `*` only as a whole segment with at least two written-out
+ * segments before the first one (`ngdpbase.<category>`), since a key is never
+ * a wildcard.
+ */
+export declare function parsePathEntry(entry: string): string[] | null;
+/**
+ * Whether `entry` names something inside `key`'s value, and the path pattern
+ * below the key if so. The key is matched literally: a `*` stands only for a
+ * segment below it.
+ */
+export declare function patternBelow(entry: string, key: string): string[] | null;
+/** Whether a path below a key matches a pattern below it: same length, `*` any one segment. */
+export declare function pathMatches(pattern: readonly string[], below: readonly string[]): boolean;
+/** What sits at a path below a value, or undefined. */
+export declare function valueAt(value: unknown, below: readonly string[]): unknown;
+/**
+ * The configuration key a path entry lies inside: the longest prefix, ending
+ * before the first `*`, for which `has` is true. Null when none is set.
+ */
+export declare function keyOfEntry(entry: string, has: (key: string) => boolean): string | null;