@jwilleke/ngdpbase-types 5.42.0 → 5.44.0

package/lib/src/managers/AuthManager.js

@@ -33,6 +33,7 @@
  */
 import { CONSENT_PATH, REMEMBER_BROWSER_CONSENT_SCOPE } from '../types/Consent.js';
 import BaseManager from './BaseManager.js';
+import { IN_SERVER_SETTINGS } from '../utils/plainAttention.js';
 import { PasswordAuthProvider } from '../providers/PasswordAuthProvider.js';
 import { MagicLinkAuthProvider, EMAIL_FACTOR } from '../providers/MagicLinkAuthProvider.js';
 import { dropKeyCopiesOfGrant, dropKeyCopy, hasUnlockedKey, hasUserKeys, heldKeyCopy, lockPrivateStores, openKeyCopy, personKeyOf, sealKekCopyFor } from '../utils/privateStoreUnlock.js';
@@ -104,6 +105,15 @@ const CORE_PROVIDER_IDS = [
 function isReservedProviderId(id) {
     return CORE_PROVIDER_IDS.includes(id) || id.startsWith('oidc:');
 }
+/**
+ * The host passkeys are tied to, or null when the site's address cannot support
+ * them: base-url must be set explicitly, and be https (or localhost).
+ */
+function passkeyRelyingPartyOf(configManager) {
+    if (!configManager.isBaseUrlExplicit())
+        return null;
+    return relyingPartyFrom(configManager.getBaseURL(), String(configManager.getProperty('ngdpbase.application-name', 'ngdpbase')));
+}
 /** A factor as offered: its entry lowered to what the provider's code gives. */
 /**
  * Providers that count toward a sign-in level only once the account has
@@ -1155,7 +1165,8 @@ class AuthManager extends BaseManager {
             return;
         this.credentialsFile = file;
         if (!key) {
-            this.markDegraded(`${CREDENTIALS_KEY_ENV} is not set, so the credentials store is closed`, CREDENTIALS_KEY_ENV);
+            logger.error(`[AuthManager] ${CREDENTIALS_KEY_ENV} is not set, so the credentials store is closed`);
+            this.markDegraded("Nobody can sign in with a password, because the key that protects the saved passwords is not set. This is set in the server's settings, outside this page.", CREDENTIALS_KEY_ENV);
             return;
         }
         const store = new FileCredentialsProvider(file, key);
@@ -1163,7 +1174,8 @@ class AuthManager extends BaseManager {
             await store.initialize((rejected) => this.raiseRejectedCredentials(store.location(), rejected));
         }
         catch (err) {
-            this.markDegraded(`The credentials store ${file} could not be read: ${err.message}`, 'ngdpbase.auth.credentials.file');
+            logger.error(`[AuthManager] The credentials store ${file} could not be read: ${err.message}`);
+            this.markDegraded('Nobody can sign in with a password, because the saved passwords could not be read. Ask whoever runs the server to check them; this is outside this page.', 'ngdpbase.auth.credentials.file');
             return;
         }
         this.credentials = store;
@@ -1181,13 +1193,14 @@ class AuthManager extends BaseManager {
             logger.warn('[AuthManager] Passkeys NOT registered: the credentials store is not available (#448)');
             return;
         }
-        if (!configManager.isBaseUrlExplicit()) {
-            logger.info('[AuthManager] Passkeys off: ngdpbase.application.base-url is not set explicitly, and a passkey is tied to that host (#448)');
-            return;
-        }
-        const rp = relyingPartyFrom(configManager.getBaseURL(), String(configManager.getProperty('ngdpbase.application-name', 'ngdpbase')));
+        const rp = passkeyRelyingPartyOf(configManager);
         if (!rp) {
-            logger.warn(`[AuthManager] Passkeys off: base-url ${configManager.getBaseURL()} is not https (or localhost), where browsers allow WebAuthn (#448)`);
+            if (!configManager.isBaseUrlExplicit()) {
+                logger.info('[AuthManager] Passkeys off: ngdpbase.application.base-url is not set explicitly, and a passkey is tied to that host (#448)');
+            }
+            else {
+                logger.warn(`[AuthManager] Passkeys off: base-url ${configManager.getBaseURL()} is not https (or localhost), where browsers allow WebAuthn (#448)`);
+            }
             return;
         }
         const store = this.credentials;
@@ -1197,6 +1210,18 @@ class AuthManager extends BaseManager {
         }));
         logger.info(`[AuthManager] passkeys tied to ${rp.rpID}`);
     }
+    /**
+     * #2317: the setting says passkeys are on, but the site's address cannot
+     * support them (base-url not set explicitly, or neither https nor localhost),
+     * so none are offered. The same rule registerPasskeys applies. Admin →
+     * Configuration says so on that setting's row and offers to turn it off.
+     */
+    passkeysCannotWork() {
+        const configManager = this.engine.getManager('ConfigurationManager');
+        if (!configManager || configManager.getProperty('ngdpbase.auth.passkey.enabled', true) === false)
+            return false;
+        return passkeyRelyingPartyOf(configManager) === null;
+    }
     /** TOTP enrolment (#421), available whenever the credentials store is open. */
     openTotp(configManager) {
         this.totp = null;
@@ -1271,6 +1296,10 @@ class AuthManager extends BaseManager {
     passkeyRelyingParty() {
         return this.passkeyProvider()?.relyingParty() ?? null;
     }
+    /** Can a passkey be added or used here at all (#2345)? False when passkeys are off or the address can't host them. */
+    passkeysAvailable() {
+        return this.passkeyRelyingParty() !== null;
+    }
     /** Options for `username` to enrol a passkey (#448); the caller keeps `challenge` for verify. */
     /**
      * May this account sign in with `providerId`? Its `allowedAuthMethods`, when
@@ -1348,7 +1377,8 @@ class AuthManager extends BaseManager {
             title: 'Security alert: credential rows rejected',
             message
         }).catch(() => { });
-        this.markDegraded(message, 'ngdpbase.auth.credentials.file');
+        // #2354: the dashboard says it in plain words; the rows and the way to re-sign them are in the log line above.
+        this.markDegraded(`${rejected.length === 1 ? 'A saved sign-in record' : `${rejected.length} saved sign-in records`} failed a security check and ${rejected.length === 1 ? 'was' : 'were'} ignored. Treat this as a possible attempt to get into an account, and ask whoever runs the server to look into it.`, 'ngdpbase.auth.credentials.file');
     }
     /**
      * Whether `ctx` may act on `username`'s credentials: their own under
@@ -2348,15 +2378,53 @@ class AuthManager extends BaseManager {
      * is told, on every page, to close.
      */
     async aalReachFor(username) {
+        const { offered, usable } = await this.accountFactors(username);
+        const reach = (factors) => Math.max(factors.some(f => f.primary) ? this.assess(factors).aal : 0, 1);
+        return { now: reach(usable), ifEnrolled: reach(offered) };
+    }
+    /**
+     * The site's factors this account may use (`offered`: narrowed to its
+     * `allowedAuthMethods`), and of those the ones it can use now (`usable`: a
+     * factor that must be enrolled counts only once it is). One reading for
+     * the level the account can reach and for what it is told to add (#2356).
+     */
+    async accountFactors(username) {
         const user = await this.engine.getManager('UserManager')?.getUser(username);
         const allowed = user?.allowedAuthMethods;
         const offered = this.getFactors().filter(f => allowsProvider(allowed, f.provider));
-        const reach = (factors) => Math.max(factors.some(f => f.primary) ? this.assess(factors).aal : 0, 1);
         const usable = offered.filter(f => {
             const kind = ENROLLED_FACTORS[f.provider];
             return kind === undefined || this.hasCredential(username, kind);
         });
-        return { now: reach(usable), ifEnrolled: reach(offered) };
+        return { offered, usable };
+    }
+    /**
+     * What this account can add or use here toward a stronger sign-in (#2356),
+     * for the sign-in banners and the confirm page's wording. Never a decision:
+     * who steps down and what step-up needs stay with `rolesAtSignIn` and
+     * `stepUpNeeded`. "Add" is a passkey or an authenticator app the site
+     * offers, the account is allowed and has not set up; "use" is one it has,
+     * is allowed, and the site offers (the app's code as step-up offers it).
+     * `password` is a password it has and is allowed, which the app's code
+     * needs to reach AAL2. `outside` names any other allowed sign-in method
+     * that reaches AAL2 by itself, such as an outside provider's.
+     * Computed per call; never cached across accounts.
+     */
+    async strongerSignInWays(username) {
+        const { offered, usable } = await this.accountFactors(username);
+        const has = (list, id) => list.some(f => f.provider === id);
+        const password = has(usable, 'password')
+            && (await this.engine.getManager('UserManager')?.hasPassword(username).catch(() => false) ?? false);
+        return {
+            addPasskey: has(offered, 'passkey') && !has(usable, 'passkey'),
+            addTotp: has(offered, 'totp') && !has(usable, 'totp'),
+            usePasskey: has(usable, 'passkey'),
+            useTotp: has(usable, 'totp') && this.stepUpTotpOffered(username),
+            password,
+            outside: usable
+                .filter(f => f.primary && f.aal >= 2 && f.provider !== 'passkey')
+                .map(f => this.providers.get(f.provider)?.displayName ?? f.provider)
+        };
     }
     /**
      * The roles an account holds at a lower level than they require only
@@ -2468,7 +2536,11 @@ class AuthManager extends BaseManager {
         const shipped = unreachable.filter(u => !u.operatorSet);
         if (shipped.length > 0) {
             const roles = shipped.map(u => `${u.role} (AAL${u.aal})`).join(', ');
-            this.markNeedsAttention(`${roles} require a stronger sign-in than this site offers, so they act at AAL${Math.max(reachable, 1)} for now. Set ngdpbase.application.base-url (https) so passkeys can be enabled.`, 'ngdpbase.auth.factors');
+            logger.warn(`[AuthManager] ${roles} require a stronger sign-in than this site offers, so they act at AAL${Math.max(reachable, 1)} for now. Set ngdpbase.application.base-url (https) so passkeys can be enabled.`);
+            // From the server's settings the address row is locked: say where to change it instead of linking to it.
+            const fromServer = !!this.engine.getManager('ConfigurationManager')?.getEnvControlledKeys?.()['ngdpbase.application.base-url'];
+            const needs = `${shipped.length === 1 ? 'One role needs' : 'Some roles need'} a stronger sign-in than this site offers, so ${shipped.length === 1 ? 'it uses' : 'they use'} a simpler one for now. Set the site's web address to a secure (https) one so passkeys can be turned on.`;
+            this.markNeedsAttention(fromServer ? `${needs} ${IN_SERVER_SETTINGS}` : needs, fromServer ? undefined : 'ngdpbase.application.base-url');
         }
         const descriptions = this.unreachableRequiredAal();
         return unreachable.flatMap((u, i) => (u.operatorSet ? [descriptions[i]] : []));

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

@@ -201,6 +201,11 @@ export interface RestoreReport {
 }
 /** BackupManager's fault, and the dashboard banner, while there is no backup key (#1561, #1912). */
 export declare const BACKUP_KEY_MISSING = "NGDPBASE_BACKUP_KEY is not set, so backups are NOT encrypted: the document (password hashes, settings with their secrets) and the file archives beside it are in the clear, and the credentials store, the databases and the instance .env are left out";
+/**
+ * What the dashboard says while there is no backup key (#2354): plain words, one thing to do.
+ * The key is set outside the app, so there is nothing to link to.
+ */
+export declare const BACKUP_KEY_MISSING_PLAIN = "Backups are not encrypted, and some data (the databases and saved secrets) is left out of them, because no backup key is set. This is set in the server's settings, outside this page.";
 /** The title of the one notification about it. */
 export declare const BACKUP_KEY_MISSING_TITLE = "Backups are not encrypted";
 /**
@@ -210,7 +215,7 @@ export declare const BACKUP_KEY_MISSING_TITLE = "Backups are not encrypted";
  */
 export declare const BACKUP_KEY_SAVED_KEY = "ngdpbase.backup.key-saved-fingerprint";
 /** The banner while no admin has confirmed the backup key is saved off the server (#1876). */
-export declare function backupKeyNotSaved(fingerprint: string): string;
+export declare function backupKeyNotSaved(): string;
 /**
  * The config key that records the names (never the values) the instance
  * `.env` set when an admin last confirmed it is saved off the server (#1976),
@@ -229,7 +234,7 @@ export declare const ENV_KEYS_CHANGED_TITLE = "Save a copy of .env";
  */
 export declare const SHARED_FOLDERS_KEY_SAVED_KEY = "ngdpbase.backup.shared-folders-key-saved-fingerprint";
 /** The banner while no admin has confirmed a saved `.env` holding the current shared-folders key (#2124). */
-export declare function sharedFoldersKeyNotSaved(fingerprint: string): string;
+export declare function sharedFoldersKeyNotSaved(): string;
 /** The banner while the instance `.env` sets other names than the ones an admin last confirmed saved (#1976): names only, never a value. */
 export declare function envKeysChanged(change: {
     added: readonly string[];
@@ -274,6 +279,8 @@ export interface BackupFailure {
     /** The document that was written anyway (a backup with a part missing), so it is not counted as good. */
     filename?: string;
 }
+/** What the dashboard says for a health fault (#2354): plain words; the developer reason stays in the log and on the Backup page. */
+export declare function backupHealthPlain(health: Pick<BackupHealth, 'failure' | 'lastGood'>): string;
 /** Whether backups are working, as Admin → Backup and the /admin dashboard show it (#1563). */
 export interface BackupHealth {
     /** The newest backup in the backup directory that is not a failed one: when, how big (with the files beside it), where. */

package/lib/src/managers/BackupManager.js

@@ -174,6 +174,11 @@ export function restoreLabel(manager) {
 }
 /** BackupManager's fault, and the dashboard banner, while there is no backup key (#1561, #1912). */
 export const BACKUP_KEY_MISSING = `${BACKUP_KEY_ENV} is not set, so backups are NOT encrypted: the document (password hashes, settings with their secrets) and the file archives beside it are in the clear, and the credentials store, the databases and the instance .env are left out`;
+/**
+ * What the dashboard says while there is no backup key (#2354): plain words, one thing to do.
+ * The key is set outside the app, so there is nothing to link to.
+ */
+export const BACKUP_KEY_MISSING_PLAIN = "Backups are not encrypted, and some data (the databases and saved secrets) is left out of them, because no backup key is set. This is set in the server's settings, outside this page.";
 /** The title of the one notification about it. */
 export const BACKUP_KEY_MISSING_TITLE = 'Backups are not encrypted';
 /**
@@ -183,8 +188,8 @@ export const BACKUP_KEY_MISSING_TITLE = 'Backups are not encrypted';
  */
 export const BACKUP_KEY_SAVED_KEY = 'ngdpbase.backup.key-saved-fingerprint';
 /** The banner while no admin has confirmed the backup key is saved off the server (#1876). */
-export function backupKeyNotSaved(fingerprint) {
-    return `Save the backup key off this server: Admin → Backup shows it (fingerprint ${fingerprint}). Every backup is encrypted with it, and a restore on a new server needs it. This stays until an admin confirms it is saved`;
+export function backupKeyNotSaved() {
+    return 'Save the backup key somewhere other than this server. Every backup is encrypted with it, and restoring on a new server needs it. This stays until you confirm it is saved.';
 }
 /**
  * The config key that records the names (never the values) the instance
@@ -194,6 +199,8 @@ export function backupKeyNotSaved(fingerprint) {
  * removed.
  */
 export const ENV_KEYS_SAVED_KEY = 'ngdpbase.backup.env-keys-saved';
+/** Where a backup-key reminder is cleared: the Backup page, not the Configuration page (#2348). */
+const BACKUP_PAGE_FIX = { fixUrl: '/admin/backup', fixLabel: 'Open Admin → Backup' };
 /** The title of the one notification per change of the `.env` key set (#1976). */
 export const ENV_KEYS_CHANGED_TITLE = 'Save a copy of .env';
 /**
@@ -203,20 +210,20 @@ export const ENV_KEYS_CHANGED_TITLE = 'Save a copy of .env';
  * key asks again.
  */
 export const SHARED_FOLDERS_KEY_SAVED_KEY = 'ngdpbase.backup.shared-folders-key-saved-fingerprint';
-const ENV_KEYS_CHANGED_PREFIX = 'The keys in .env changed since an admin last saved it';
-const KEY_NOT_SAVED_PREFIX = 'Save the backup key off this server';
-const SHARED_FOLDERS_KEY_NOT_SAVED_PREFIX = 'Save .env off this server: it holds the shared-folders key';
+const ENV_KEYS_CHANGED_PREFIX = 'The server\'s key file has changed since you last saved a copy';
+const KEY_NOT_SAVED_PREFIX = 'Save the backup key somewhere other than this server';
+const SHARED_FOLDERS_KEY_NOT_SAVED_PREFIX = 'Save a copy of the server\'s key file somewhere other than this server';
 /** The banner while no admin has confirmed a saved `.env` holding the current shared-folders key (#2124). */
-export function sharedFoldersKeyNotSaved(fingerprint) {
-    return `${SHARED_FOLDERS_KEY_NOT_SAVED_PREFIX} (${SHARED_FOLDERS_KEY_ENV}, fingerprint ${fingerprint}), which opens every shared folder. Download .env on Admin → Backup and keep the copy off this server. This stays until an admin confirms it is saved`;
+export function sharedFoldersKeyNotSaved() {
+    return `${SHARED_FOLDERS_KEY_NOT_SAVED_PREFIX}: it holds the key that opens every shared folder. Download it on the Backup page. This stays until you confirm it is saved.`;
 }
 /** The banner while the instance `.env` sets other names than the ones an admin last confirmed saved (#1976): names only, never a value. */
 export function envKeysChanged(change) {
     const parts = [
-        ...(change.added.length > 0 ? [`added: ${change.added.join(', ')}`] : []),
-        ...(change.removed.length > 0 ? [`removed: ${change.removed.join(', ')}`] : [])
+        ...(change.added.length > 0 ? [`${change.added.length} added`] : []),
+        ...(change.removed.length > 0 ? [`${change.removed.length} removed`] : [])
     ];
-    return `${ENV_KEYS_CHANGED_PREFIX} (${parts.join('; ')}). Download .env on Admin → Backup and keep the copy off this server. This stays until an admin confirms it is saved`;
+    return `${ENV_KEYS_CHANGED_PREFIX} (${parts.join(', ')}). Download it on the Backup page and keep the copy somewhere other than this server. This stays until you confirm it is saved.`;
 }
 /** The scheduled job automatic backups run as (#1720). */
 export const AUTO_BACKUP_JOB_ID = 'backup.auto';
@@ -225,6 +232,14 @@ export const BACKUP_HEALTH_JOB_ID = 'backup.health';
 /** The title of the notification sent when backups stop working (#1563): a backup failed, or none is recent enough. */
 export const BACKUPS_NOT_WORKING_TITLE = 'Backups are not working';
 const DAY_MS = 86_400_000;
+/** What the dashboard says for a health fault (#2354): plain words; the developer reason stays in the log and on the Backup page. */
+export function backupHealthPlain(health) {
+    const since = health.lastGood ? localTime(health.lastGood.at) : null;
+    const last = since ? `The last good backup was ${since}.` : 'There is no good backup yet.';
+    return health.failure
+        ? `The last backup failed (${localTime(health.failure.at)}), so backups are not working. ${last} Open the Backup page to see what went wrong and make a new one.`
+        : `${since ? `There has been no good backup since ${since}` : 'This site has no backup yet'}. Open the Backup page and make one.`;
+}
 /** A number of bytes as admins read it. */
 export function formatBytes(bytes) {
     if (!Number.isFinite(bytes) || bytes < 1024)
@@ -806,14 +821,14 @@ class BackupManager extends BaseManager {
         const envReminder = await this.checkInstanceEnvKeys();
         const key = currentBackupKey();
         if (key) {
-            this.markReadyIfDegradedBy(BACKUP_KEY_MISSING);
+            this.markReadyIfDegradedBy(BACKUP_KEY_MISSING_PLAIN);
             // #1876: the banner asking an admin to save the key off the server, until one confirms;
             // then #1976's, while the .env key set differs from the one last confirmed. One at a time,
             // and one confirmation ("I have saved .env", which holds the key) can clear both.
             // #2124: then the shared-folders key's, while no saved .env holding the current one is confirmed.
             const shared = this.sharedFoldersKeyInfo();
-            const sharedReminder = shared.set && !shared.saved && shared.fingerprint ? sharedFoldersKeyNotSaved(shared.fingerprint) : null;
-            const reminder = this.backupKeyInfo().saved ? (envReminder ?? sharedReminder) : backupKeyNotSaved(backupKeyFingerprint(key));
+            const sharedReminder = shared.set && !shared.saved && shared.fingerprint ? sharedFoldersKeyNotSaved() : null;
+            const reminder = this.backupKeyInfo().saved ? (envReminder ?? sharedReminder) : backupKeyNotSaved();
             const status = this.getManagerStatus();
             const ours = status.state === 'degraded' && [KEY_NOT_SAVED_PREFIX, ENV_KEYS_CHANGED_PREFIX, SHARED_FOLDERS_KEY_NOT_SAVED_PREFIX].some((p) => status.reason?.startsWith(p));
             if (!reminder) {
@@ -821,14 +836,15 @@ class BackupManager extends BaseManager {
                     this.markReady();
             }
             else if (status.state !== 'degraded' || ours) {
-                this.markNeedsAttention(reminder, reminder === envReminder ? ENV_KEYS_SAVED_KEY : reminder === sharedReminder ? SHARED_FOLDERS_KEY_SAVED_KEY : BACKUP_KEY_SAVED_KEY);
+                // The saved-key settings are records the app writes when an admin confirms, not values to edit: the fix is the Backup page, with no link to them (#2348, #2354).
+                this.markNeedsAttention(reminder, undefined, BACKUP_PAGE_FIX);
             }
             return;
         }
         // A degraded backup directory (preflight) is the worse fault, and keeps the banner.
         const status = this.getManagerStatus();
-        if (status.state !== 'degraded' || status.reason === BACKUP_KEY_MISSING)
-            this.markNeedsAttention(BACKUP_KEY_MISSING, BACKUP_KEY_ENV);
+        if (status.state !== 'degraded' || status.reason === BACKUP_KEY_MISSING_PLAIN)
+            this.markNeedsAttention(BACKUP_KEY_MISSING_PLAIN, BACKUP_KEY_ENV);
         if (this.alreadyNotified(BACKUP_KEY_MISSING_TITLE))
             return;
         await this.notifyAdmins('error', BACKUP_KEY_MISSING_TITLE, `${BACKUP_KEY_MISSING}. Set ${BACKUP_KEY_ENV} in the environment or the instance .env, and restart. Until then the dashboard lists Backup under "Working, but needs your attention"; this is the only notification about it.`);
@@ -881,7 +897,13 @@ class BackupManager extends BaseManager {
         if (info.added.length === 0 && info.removed.length === 0)
             return null;
         const reminder = envKeysChanged(info);
-        const message = `${reminder}. The /admin dashboard lists Backup under "Working, but needs your attention" until then.`;
+        // The notification keeps the names (never a value); the dashboard item says only how many.
+        const names = [
+            ...(info.added.length > 0 ? [`added: ${info.added.join(', ')}`] : []),
+            ...(info.removed.length > 0 ? [`removed: ${info.removed.join(', ')}`] : [])
+        ];
+        logger.info(`[BackupManager] The instance .env key set changed since an admin last saved it (${names.join('; ')})`);
+        const message = `${reminder} Changes: ${names.join('; ')}. The /admin dashboard lists Backup under "Working, but needs your attention" until then.`;
         if (!this.alreadyNotified(ENV_KEYS_CHANGED_TITLE, message))
             await this.notifyAdmins('warning', ENV_KEYS_CHANGED_TITLE, message);
         return reminder;
@@ -1182,8 +1204,9 @@ class BackupManager extends BaseManager {
             if (this.provider) {
                 health = await this.getBackupHealth();
                 if (health.fault) {
-                    this.markDegraded(health.fault, health.failure ? undefined : 'ngdpbase.backup.auto-backup');
-                    this.healthFault = health.fault;
+                    const plain = backupHealthPlain(health);
+                    this.markDegraded(plain, health.failure ? undefined : 'ngdpbase.backup.auto-backup', BACKUP_PAGE_FIX);
+                    this.healthFault = plain;
                     if (!health.failure)
                         await this.notifyStaleOnce(health);
                 }

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

@@ -282,7 +282,21 @@ export interface ManagerStatus {
     configKey?: string;
     /** Whether the feature is down or works but needs an admin (#1946). Present when degraded or failed. */
     kind?: DegradedKind;
+    /** Where the fix is, when it is not the setting `configKey` names (a record the app writes, not a value to edit). */
+    fixUrl?: string;
+    /** What the link to `fixUrl` says, e.g. "Open Admin → Backup". */
+    fixLabel?: string;
+    /** One line per problem, drawn as a list under `reason` (#2348). `reason` stays the headline and the audit text. */
+    details?: string[];
+    /** Buttons under the item (#2355): each posts a form to `action` with `fields`; the page adds the CSRF token. Labels and values are text. */
+    buttons?: Array<{
+        label: string;
+        action: string;
+        fields: Record<string, string>;
+    }>;
 }
+/** What a caller may add to a needs-attention status (#2348). */
+export type AttentionOptions = Pick<ManagerStatus, 'fixUrl' | 'fixLabel' | 'details' | 'buttons'>;
 declare abstract class BaseManager {
     /** Reference to the wiki engine */
     protected engine: WikiEngine;
@@ -425,18 +439,18 @@ declare abstract class BaseManager {
      *   starts degraded and stays degraded must not re-emit on every boot, or
      *   the signal is buried in its own noise.
      */
-    protected markDegraded(reason: string, configKey?: string): boolean;
+    protected markDegraded(reason: string, configKey?: string, opts?: AttentionOptions): boolean;
     /**
      * Record that this manager works, but an administrator has something to do
      * (#1946). Still `degraded` — it stays on the dashboard, is audited, and
      * clears with `markReadyIfDegradedBy` — but shown as needing attention, not
      * as down.
      */
-    protected markNeedsAttention(reason: string, configKey?: string): boolean;
+    protected markNeedsAttention(reason: string, configKey?: string, opts?: AttentionOptions): boolean;
     /** Record that this manager is deliberately off. Not a problem (#1155). */
     protected markDisabled(reason: string): boolean;
     /** Record that this manager could not initialise at all (#1155). */
-    protected markFailed(reason: string, configKey?: string): boolean;
+    protected markFailed(reason: string, configKey?: string, opts?: AttentionOptions): boolean;
     /**
      * Record that this manager is working.
      *

package/lib/src/managers/BaseManager.js

@@ -18,6 +18,7 @@ import logger from '../utils/logger.js';
 import { checkConfiguredPath } from '../utils/PathPreflight.js';
 import { recordAuditEvent } from '../utils/auditEvents.js';
 import { AUDIT_EVENT } from '../utils/auditEventNames.js';
+import { STAGED_RESTORE_FIX, stagedRestoreNotApplied, UNUSABLE_FOLDER_REASON } from '../utils/plainAttention.js';
 class BaseManager {
     /** Reference to the wiki engine */
     engine;
@@ -121,7 +122,9 @@ class BaseManager {
         const { applyStagedPartsAtStart } = await import('./BackupManager.js');
         this.stagedRestore = applyStagedPartsAtStart(this.engine, this.registeredName(), declared);
         if (this.stagedRestore?.refused) {
-            this.markNeedsAttention(`A staged restore of ${declared.map((d) => d.part).join(', ')} was not applied: ${this.stagedRestore.refused}`);
+            // #2354: the dashboard says it in plain words; the parts and the cause stay in the log.
+            logger.warn(`[${this.constructor.name}] A staged restore of ${declared.map((d) => d.part).join(', ')} was not applied: ${this.stagedRestore.refused}`);
+            this.markNeedsAttention(stagedRestoreNotApplied('some of the site\'s data'), undefined, STAGED_RESTORE_FIX);
         }
     }
     /**
@@ -193,7 +196,8 @@ class BaseManager {
             // degrading manager already goes through, so setting the state here is
             // what makes twelve invisible degradations visible without each caller
             // remembering to say so.
-            this.markDegraded(result.message ?? 'the configured path could not be used', configKey);
+            // #2354: the dashboard says it in plain words; the path and key are in the line above.
+            this.markDegraded(UNUSABLE_FOLDER_REASON, configKey);
         }
         return result;
     }
@@ -216,8 +220,8 @@ class BaseManager {
      *   starts degraded and stays degraded must not re-emit on every boot, or
      *   the signal is buried in its own noise.
      */
-    markDegraded(reason, configKey) {
-        return this.transition({ state: 'degraded', reason, configKey, kind: 'outage' });
+    markDegraded(reason, configKey, opts = {}) {
+        return this.transition({ state: 'degraded', reason, configKey, kind: 'outage', ...opts });
     }
     /**
      * Record that this manager works, but an administrator has something to do
@@ -225,16 +229,16 @@ class BaseManager {
      * clears with `markReadyIfDegradedBy` — but shown as needing attention, not
      * as down.
      */
-    markNeedsAttention(reason, configKey) {
-        return this.transition({ state: 'degraded', reason, configKey, kind: 'attention' });
+    markNeedsAttention(reason, configKey, opts = {}) {
+        return this.transition({ state: 'degraded', reason, configKey, kind: 'attention', ...opts });
     }
     /** Record that this manager is deliberately off. Not a problem (#1155). */
     markDisabled(reason) {
         return this.transition({ state: 'disabled', reason });
     }
     /** Record that this manager could not initialise at all (#1155). */
-    markFailed(reason, configKey) {
-        return this.transition({ state: 'failed', reason, configKey, kind: 'outage' });
+    markFailed(reason, configKey, opts = {}) {
+        return this.transition({ state: 'failed', reason, configKey, kind: 'outage', ...opts });
     }
     /**
      * Record that this manager is working.

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

@@ -54,6 +54,8 @@ declare class ConfigurationManager extends BaseManager {
     private defaultConfig;
     private customConfig;
     private mergedConfig;
+    /** #2279: counts every change to `mergedConfig`, so a reader may keep what it derived from a value until the next one. */
+    private revision;
     /** #1638: shipped ⊕ enabled addons, before the operator's file — what the build declares. */
     private declaredConfig;
     /** #1813: each enabled addon's own default-config.json, as folded into the merge. */
@@ -200,6 +202,32 @@ declare class ConfigurationManager extends BaseManager {
      * @throws {Error} If default configuration file cannot be loaded
      */
     private loadConfigurations;
+    /**
+     * A number that changes whenever the configuration in force changes (#2279):
+     * a load or reload, a save, a reset, a restore, a runtime value an add-on
+     * sets. Equal numbers mean nothing was changed through this manager, so
+     * what a reader derived from `getProperty` then still holds. A value
+     * returned by `getProperty` must not be changed in place; that is the one
+     * change this cannot see.
+     */
+    getRevision(): number;
+    /** What the #2255 page-write migration rewrote in memory, one sentence each; PolicyDecisionPoint reports it. */
+    pageWritePolicyMigration: string[];
+    /** Each `pageWritePolicyMigration` line in plain words, for the needs-attention entry. */
+    pageWritePolicyMigrationShown: Record<string, string>;
+    /**
+     * #2255: before the merge, rewrite the custom layer's stored copies of the
+     * shipped role policies whose page writes moved to the category policies
+     * (`migrateStoredPageWritePolicies`). In memory only, like the other
+     * migrations here; one warning per policy changed.
+     */
+    private migrateStoredPageWritePolicies;
+    /**
+     * #2246: `ngdpbase.stores.<kind>.owner|encrypt` in the custom config have
+     * been ignored since #1505. One warning per key, and one needs-attention
+     * entry naming them all. Nothing is changed, carried over or removed.
+     */
+    private reportLegacyStoreKeys;
     /**
      * #642: One-shot migration shim. If the custom config sets either of the
      * legacy keys `ngdpbase.base-url` or `ngdpbase.baseURL`, copy the value

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

@@ -56,7 +56,7 @@ declare class ConsentManager extends BaseManager {
     private readonly addons;
     /** Username → their records, read once and dropped on every write. */
     private readonly cache;
-    /** Document id → why it cannot be asked for; the needs-attention reason is made from these. */
+    /** Document id → why it cannot be asked for (the needs-attention reason is made from these), and whether it comes with an add-on (core's Required Pages Sync does not restore those). */
     private readonly problems;
     private attentionReason;
     constructor(engine: WikiEngine);

package/lib/src/managers/DatabaseManager.js

@@ -50,6 +50,7 @@ import { applyStagedRestore, manifestPath, runOffThread, setAsideStagedRestore,
 import { BACKUP_KEY_ENV, backupKeyFingerprint, currentBackupKey, LEFT_OUT_FOR_NO_KEY } from '../utils/backupKey.js';
 // The environment variable holding the SQLCipher key: one declaration, `src/utils/databaseKey.ts`.
 import { DATABASE_KEY_ENV } from '../utils/databaseKey.js';
+import { STAGED_RESTORE_FIX } from '../utils/plainAttention.js';
 export { DATABASE_KEY_ENV };
 // #1723, #1876: the backup key has one declaration (`src/utils/backupKey.ts`); re-exported for the callers that import it from here.
 export { BACKUP_KEY_ENV, backupKeyFingerprint } from '../utils/backupKey.js';
@@ -138,7 +139,7 @@ class DatabaseManager extends BaseManager {
         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)`);
+                `${path.basename(manifestPath(file))}. Stop the server, put the files back as they should be, and restart (#1892)`, 'A saved copy of the databases was being put back and it did not finish, so the site is in maintenance mode and no database is open. Some may already have been replaced. Ask whoever runs the server to check the database files and restart the site; this is done on the server, outside this page.');
             return;
         }
         // #1892: a database that cannot be opened safely (no key or the wrong key
@@ -151,7 +152,7 @@ class DatabaseManager extends BaseManager {
             provider = new SqliteDatabaseProvider(file, key, DATABASE_MIGRATIONS, 'schema_migrations', { busyTimeoutMs: this.busyTimeoutMs });
         }
         catch (err) {
-            this.markUnavailable(DatabaseManager.openFailure(file, err.message, key));
+            this.markUnavailable(DatabaseManager.openFailure(file, err.message, key), 'The database could not be opened safely, so the site is in maintenance mode. If its key is missing or wrong, fix it in the server\'s settings (outside this page) and restart the site. If the file is damaged, restore the databases from a backup.', STAGED_RESTORE_FIX);
             return;
         }
         this.provider = provider;
@@ -195,11 +196,12 @@ class DatabaseManager extends BaseManager {
      * administrators can sign in and reach /admin, and `reportAtBoot()` sends
      * them the reason as a critical notification once notifications exist.
      */
-    markUnavailable(reason) {
+    markUnavailable(reason, plain, fix) {
         this.unavailable = reason;
         this.provider = null;
         logger.error(`[DatabaseManager] ${reason}`);
-        this.markFailed(reason, 'ngdpbase.database.file');
+        // #2354: the dashboard says it in plain words; the developer text is the log line above.
+        this.markFailed(plain, 'ngdpbase.database.file', fix);
         // #1906: no message of its own, so visitors see the site's maintenance message.
         this.engine.maintenance.enter(reason);
     }
@@ -690,7 +692,13 @@ class DatabaseManager extends BaseManager {
     }
     /** Degrade for one cause; the dashboard shows every cause still standing. */
     fault(cause, reason, kind) {
-        this.faults.set(cause, { reason, kind });
+        // #2354: the dashboard shows the plain words; `reason` is the developer text, already logged by the caller.
+        const plain = cause === 'restore'
+            ? 'A saved copy of the databases was not put back when the site started, so the databases that were there before are still in use. Open the Backup page to see what to do next.'
+            : this.backupKey()
+                ? "The backup key is the same as the database key, so one stolen secret would open both. Give the backups a key of their own, in the server's settings, outside this page."
+                : "Databases are not being backed up, because the backup key is not set. This is set in the server's settings, outside this page.";
+        this.faults.set(cause, { reason, plain, kind });
         this.markFaults();
     }
     clearFault(cause) {
@@ -704,11 +712,12 @@ class DatabaseManager extends BaseManager {
     /** Every cause still standing; down when any one of them is (#1946). */
     markFaults() {
         const faults = [...this.faults.values()];
-        const reason = faults.map((f) => f.reason).join('; ');
+        const reason = faults.map((f) => f.plain).join(' ');
+        const fix = this.faults.has('restore') ? STAGED_RESTORE_FIX : {};
         if (faults.some((f) => f.kind === 'outage'))
-            this.markDegraded(reason);
+            this.markDegraded(reason, undefined, fix);
         else
-            this.markNeedsAttention(reason);
+            this.markNeedsAttention(reason, undefined, fix);
     }
     async notify(level, title, message) {
         try {

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

@@ -35,7 +35,7 @@ import type { MailAttachment, MailMessage, MailProvider } from '../mail/MailProv
 import type { ActorContext } from '../context/ActorContext.js';
 export type { MailAttachment } from '../mail/MailProvider.js';
 /** The degraded reason while sends fail; cleared by the next success. */
-export declare const SEND_FAILING_REASON = "outbound email is failing \u2014 see the server log and the administrator notification";
+export declare const SEND_FAILING_REASON = "The site can't send email right now. Check the email settings.";
 /** Title of the administrator notice. */
 export declare const SEND_FAILING_TITLE = "Email could not be sent";
 /** An attachment the message cannot carry (#1974): refused before sending, so it is not a delivery failure. */