@jwilleke/ngdpbase-types 5.43.0 → 5.44.0

package/lib/src/context/ApiContext.d.ts

@@ -28,6 +28,7 @@ import type { AgentTokenGrant, PermissionSubject, ProxyClaim } from '../managers
 import type { ShareGrant } from '../types/Share.js';
 import { type ReauthMode } from '../managers/AuthManager.js';
 import { type Decision } from '../types/Policy.js';
+import type { OwnedAuditResource } from '../security/ownedRecords.js';
 /**
  * Thrown by ApiContext guard methods (requirePermission, actingUsername).
  * Route handlers should catch this and forward `status` to `res.status()`.
@@ -201,8 +202,14 @@ export declare class ApiContext extends BaseContext {
      * - an allow: a programming error. A refusal never silently passes.
      *
      * @example
-     * const d = await pdp.decide(ctx.getActor(), { action: 'ledger-adjust', resource: { type: 'ledger-entry', id } });
-     * if (!d.permit) await ctx.enforceDeny('ledger-adjust', d);
+     * const d = await pdp.decideOwnedRecord(ctx.subject, { action: 'phr-read', resource: { type: 'phr-record', id, attributes: { owner } } });
+     * if (!d.permit) await ctx.enforceDeny('phr-read', d, { type: 'phr-record', id, owner, ownerUser });
      */
-    enforceDeny(permission: string, decision: Decision): Promise<never>;
+    enforceDeny(permission: string, decision: Decision, resource?: OwnedAuditResource): Promise<never>;
+    /**
+     * The refusal of one add-on record (#1823), recorded before the error is
+     * thrown. `authorization-deny` is continue-on-failure, so a lost record does
+     * not change the refusal. `owner` is the stored identity @id.
+     */
+    private recordOwnedDenial;
 }

package/lib/src/context/ApiContext.js

@@ -6,6 +6,9 @@ import { BaseContext } from './BaseContext.js';
 import { answeredWithPage } from '../managers/AuthManager.js';
 import { STEP_UP_REASON } from '../types/Policy.js';
 import { CONSENT_PATH } from '../types/Consent.js';
+import { actorOf } from './ActorContext.js';
+import { AUDIT_EVENT } from '../utils/auditEventNames.js';
+import { recordAuditEvent } from '../utils/auditEvents.js';
 // ── ApiError ────────────────────────────────────────────────────────────────
 /**
  * Thrown by ApiContext guard methods (requirePermission, actingUsername).
@@ -269,13 +272,15 @@ export class ApiContext extends BaseContext {
      * - an allow: a programming error. A refusal never silently passes.
      *
      * @example
-     * const d = await pdp.decide(ctx.getActor(), { action: 'ledger-adjust', resource: { type: 'ledger-entry', id } });
-     * if (!d.permit) await ctx.enforceDeny('ledger-adjust', d);
+     * const d = await pdp.decideOwnedRecord(ctx.subject, { action: 'phr-read', resource: { type: 'phr-record', id, attributes: { owner } } });
+     * if (!d.permit) await ctx.enforceDeny('phr-read', d, { type: 'phr-record', id, owner, ownerUser });
      */
-    async enforceDeny(permission, decision) {
+    async enforceDeny(permission, decision, resource) {
         if (decision.permit) {
             throw new Error(`ApiContext.enforceDeny('${permission}') was handed an allow decision: it enforces only a deny`);
         }
+        if (resource)
+            await this.recordOwnedDenial(permission, decision, resource);
         if (decision.reason === STEP_UP_REASON && this.request) {
             // #1758: step-up is AuthManager's — the answer and its reauth-prompt record.
             const authManager = this.engine.getManager('AuthManager');
@@ -288,4 +293,32 @@ export class ApiContext extends BaseContext {
             ? new ApiError(403, 'Forbidden')
             : new ApiError(401, 'Authentication required');
     }
+    /**
+     * The refusal of one add-on record (#1823), recorded before the error is
+     * thrown. `authorization-deny` is continue-on-failure, so a lost record does
+     * not change the refusal. `owner` is the stored identity @id.
+     */
+    async recordOwnedDenial(permission, decision, resource) {
+        const who = this.subject
+            ? actorOf(this.subject)
+            : { user: 'anonymous', ipAddress: this.ipAddress, metadata: { origin: 'request' } };
+        const sink = this.engine.getManager?.('AuditManager');
+        await recordAuditEvent(sink, {
+            eventType: AUDIT_EVENT.AUTHORIZATION_DENY,
+            ...who,
+            action: permission,
+            resource: resource.id ?? '',
+            resourceType: resource.type,
+            result: 'deny',
+            reason: decision.reason || 'not permitted',
+            severity: 'medium',
+            metadata: {
+                ...who.metadata,
+                ...(resource.owner ? { owner: resource.owner } : {}),
+                ...(resource.ownerUser ? { ownerUser: resource.ownerUser } : {}),
+                ...(decision.policyIds?.length ? { policyIds: [...decision.policyIds] } : {}),
+                ...(decision.conditionNotMet?.length ? { conditionNotMet: [...decision.conditionNotMet] } : {})
+            }
+        });
+    }
 }

package/lib/src/ice/runExport.d.ts

@@ -31,11 +31,16 @@ export declare function exportSize(items: readonly IceItem[]): number;
 export declare function checkExportSize(items: readonly IceItem[], maxBytes: number): void;
 /**
  * Run the source's items through the chain, each shim's output the next
- * one's input, and return the one file the last shim made. What came before
+ * one's input, and return the file the last shim made. What came before
  * travels with each item while a shim keeps the count: earlier metadata
  * under later, as an import's chain does.
  *
+ * Items that are already `file`s skip the chain and join what it makes. One
+ * file is returned as it is; several, or any when `zipName` is given, are
+ * packed into `<zipName>.zip` (`export.zip` by default), each under its own
+ * name, a repeated name made unique. The zip is held to `maxBytes` too.
+ *
  * @throws IceExportFailed when a step holds more than `maxBytes`, a shim
- *   makes something other than what it declares, or the end is not one file
+ *   makes something other than what it declares, or the end is no file
  */
-export declare function runExportChain(items: IceItem[], chain: readonly RegisteredShim[], tools: (shim: RegisteredShim) => ExportShimTools, settings: IceExportSettings): Promise<IceItem>;
+export declare function runExportChain(items: IceItem[], chain: readonly RegisteredShim[], tools: (shim: RegisteredShim) => ExportShimTools, settings: IceExportSettings, zipName?: string): Promise<IceItem>;

package/lib/src/ice/searchExportSource.d.ts

@@ -0,0 +1,44 @@
+import type { ActorContext } from '../context/ActorContext.js';
+import { type IceExportSource, type IceItem } from './types.js';
+/** Core's search export source. */
+export declare const SEARCH_EXPORT_SOURCE = "core.search";
+/** A search, as the page search takes it: the fields `/search` and `/api/assets/search` read. */
+export interface SearchExportParams {
+    q?: string;
+    types?: string;
+    mimeCategory?: string;
+    year?: number;
+    category?: string[];
+    keywords?: string[];
+    systemKeywords?: string[];
+    status?: string[];
+    searchIn?: string[];
+    since?: string;
+    until?: string;
+    date?: string;
+}
+/** The search's parameters from a query string or a body: known fields only, empty ones left out. */
+export declare function searchExportParams(src: Record<string, unknown> | null | undefined): SearchExportParams;
+/** What `read` and `mayExport` take as `ref`. */
+export declare const searchExportRef: (src: Record<string, unknown> | null | undefined) => string;
+/** A page as an NCM item: its text and what a document made from it shows. */
+export declare function pageItem(name: string, content: string, metadata: Record<string, unknown>): IceItem;
+interface Manager {
+    getManager<M>(name: string): M | null | undefined;
+}
+export interface SearchExportDeps {
+    engine: Manager;
+    /** May this user export this page alone (`page-export` for it, in its private store or shared folder)? */
+    mayExportPage(ctx: ActorContext, pageName: string): Promise<boolean>;
+    limits(): {
+        maxItems: number;
+        maxBytes: number;
+    };
+    /** Is the Export action for a search offered to this user (page-export held)? */
+    offered(ctx: ActorContext): Promise<boolean>;
+    /** Does this user hold `page-export` now? Throws the step-up answer when it needs a fresh sign-in. */
+    allowed(ctx: ActorContext): Promise<boolean>;
+    permits(ctx: ActorContext, permission: string): Promise<boolean>;
+}
+export declare function searchExportSource(deps: SearchExportDeps): IceExportSource;
+export {};

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

@@ -641,6 +641,8 @@ export declare const EXPORT_FILE_KIND = "file";
 export interface ExportReadInfo {
     /** The shim that will make the file (`core.pdf`). */
     format: string;
+    /** Tell the user something about what was read (what was left out and why); shown with the finished export. */
+    note(text: string): void;
 }
 /**
  * The owner's door for reading the thing being exported (#2120, D5): a page
@@ -654,6 +656,8 @@ export interface IceExportSource {
     label?: string;
     /** The kind of the items it yields, e.g. `ncm` for a page. */
     yields: IceKind;
+    /** Make the export a zip with this name (`search-results`) even when it holds one file. */
+    zipAs?: string;
     /**
      * Would this context be allowed to export `ref`? Asked only to decide
      * whether to offer the Export action: an affordance, which records nothing.
@@ -724,6 +728,8 @@ export interface IceExportReport {
     startedAt?: string;
     finishedAt?: string;
     error?: string;
+    /** What the source says about what it read, such as how many items were left out. */
+    notes?: string[];
     file?: IceExportFile;
     /** When the file is let go (`ngdpbase.export.engine.keep-minutes`). */
     expiresAt?: string;

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

@@ -500,6 +500,17 @@ declare class AttachmentManager extends BaseManager implements CatalogSource {
         buffer: Buffer;
         metadata: AttachmentMetadata;
     } | null>;
+    /**
+     * May `ctx` read this file, by the rules `GET /attachments/:id` serves it
+     * under: a file in the requester's own store, else `asset-read`, and a
+     * private file only to its owner or their delegate (PIP). No bytes are read.
+     */
+    mayReadAttachment(attachmentId: string, ctx: ActorContext): Promise<boolean>;
+    /** A file's original bytes and metadata, when {@link mayReadAttachment} lets `ctx` read it; else null. */
+    readAttachmentFor(attachmentId: string, ctx: ActorContext): Promise<{
+        buffer: Buffer;
+        metadata: AttachmentMetadata;
+    } | null>;
     /**
      * The requester's own private stores, as provider locations (#1460).
      *

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

@@ -94,7 +94,6 @@ interface AccessContext {
 interface PolicyInfo {
     id: string;
     name: string;
-    priority?: number;
 }
 /**
  * Context for authentication events

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

@@ -60,6 +60,15 @@ export interface FactorEntry {
      */
     preference?: number;
 }
+/** What an account can add or use toward a stronger sign-in (#2356); see `strongerSignInWays`. */
+export interface StrongerSignInWays {
+    addPasskey: boolean;
+    addTotp: boolean;
+    usePasskey: boolean;
+    useTotp: boolean;
+    password: boolean;
+    outside: string[];
+}
 export interface Factor {
     provider: string;
     primary: boolean;
@@ -797,6 +806,13 @@ declare class AuthManager extends BaseManager {
      * the request — so a passkey made here works only on that hostname.
      */
     private registerPasskeys;
+    /**
+     * #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(): boolean;
     /** TOTP enrolment (#421), available whenever the credentials store is open. */
     private openTotp;
     /** Whether an authenticator app can be enrolled here (#421). */
@@ -826,6 +842,8 @@ declare class AuthManager extends BaseManager {
     private passkeyProvider;
     /** The host passkeys are tied to, or null when passkeys are off (#448). */
     passkeyRelyingParty(): PasskeyRelyingParty | 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(): boolean;
     /** Options for `username` to enrol a passkey (#448); the caller keeps `challenge` for verify. */
     /**
      * May this account sign in with `providerId`? Its `allowedAuthMethods`, when
@@ -1212,6 +1230,26 @@ declare class AuthManager extends BaseManager {
         now: Aal;
         ifEnrolled: Aal;
     }>;
+    /**
+     * 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).
+     */
+    private accountFactors;
+    /**
+     * 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.
+     */
+    strongerSignInWays(username: string): Promise<StrongerSignInWays>;
     /**
      * The roles an account holds at a lower level than they require only
      * because it has not enrolled a factor it is allowed (#1690): it acts with

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);
                 }