@jwilleke/ngdpbase-types 5.20.0 → 5.22.0

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
@@ -38,33 +40,22 @@ import path from 'node:path';
 import BaseManager from './BaseManager.js';
 import SqliteDatabaseProvider, { DEFAULT_BUSY_TIMEOUT_MS } from '../providers/SqliteDatabaseProvider.js';
 import DATABASE_MIGRATIONS from '../providers/databaseMigrations.js';
-import { createHmac } from 'node:crypto';
 import { existsSync, readFileSync, rmSync } from 'node:fs';
 import { actorOf } from '../context/ActorContext.js';
 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 { 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';
-/**
- * The environment variable holding the key every database backup is encrypted
- * under (#1723). Its own secret, not the database key: the copy that travels
- * and the copy that stays should not fall to the same compromise. Never a
- * config key. Unset, no database is backed up, and admins are told.
- */
-export const BACKUP_KEY_ENV = 'NGDPBASE_BACKUP_KEY';
+import { applyStagedRestore, manifestPath, runOffThread, setAsideStagedRestore, stagedPath, writeManifest } from '../providers/sqliteBackup.js';
+import { gatePart, markPart, recordStagedPart, siteRestoreFile } from '../utils/siteRestore.js';
+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';
+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';
 /** How long a database backup or restore staging may run on its worker before it is stopped, when not configured. */
 export const DEFAULT_BACKUP_WORKER_TIMEOUT_MS = 3_600_000;
-/**
- * A short fingerprint of a backup key (#1723, D3): the first 16 hex digits of
- * an HMAC of a fixed label under the key. Recorded in each backup so a restore
- * under another key says so plainly; it never reveals the key.
- */
-export function backupKeyFingerprint(key) {
-    return createHmac('sha256', key).update('ngdpbase backup key fingerprint v1').digest('hex').slice(0, 16);
-}
 /** The backup's name for the application database; an add-on's is `addon-<owner>`. */
 const APPLICATION = 'application';
 const addonName = (owner) => `addon-${owner}`;
@@ -109,8 +100,14 @@ class DatabaseManager extends BaseManager {
     addonDatabases = new Map();
     /** What the start did with a staged restore (#1723), reported once the notifications exist. */
     restoreAtStart = null;
+    /** The databases a staged restore put back at this start (#1876): kept after the report, for the managers whose data is in them. */
+    restoredNow = [];
+    /** When the restored backup was taken, and where the replaced application database is kept, when a restore was applied at this start (#1876). */
+    replaced = 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 +130,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 +171,45 @@ 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 the one
+     * door (`engine.maintenance`, #1906): visitors see only the site's maintenance message,
+     * 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');
+        // #1906: no message of its own, so visitors see the site's maintenance message.
+        this.engine.maintenance.enter(reason);
+    }
+    /** 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 +238,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 +263,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 +294,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 +325,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)' };
         }
@@ -278,7 +345,7 @@ class DatabaseManager extends BaseManager {
         }
         const backupKey = this.backupKey();
         if (!backupKey) {
-            const reason = `${BACKUP_KEY_ENV} is not set, so no database was backed up. Database backups are always encrypted and are never written without it (#1723)`;
+            const reason = `${LEFT_OUT_FOR_NO_KEY}no database was backed up. Database backups are always encrypted and are never written without it (#1723)`;
             this.fault('backup-key', reason);
             throw new Error(reason);
         }
@@ -342,7 +409,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) {
@@ -419,15 +492,51 @@ class DatabaseManager extends BaseManager {
             databases: stages.map((s) => ({ name: s.name, live: s.live, staged: stagedPath(s.live) }))
         };
         writeManifest(manifestFile, manifest);
+        // #1876: part of a site restore — the databases go in with the other parts, or not at all.
+        if (options.siteRestore) {
+            recordStagedPart(options.siteRestore, {
+                manager: 'DatabaseManager',
+                swaps: manifest.databases.map((d) => ({ live: d.live, staged: d.staged })),
+                discard: [manifestFile]
+            });
+        }
         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}`);
             await this.notify('error', 'Some databases in the backup were not restored', message);
         }
     }
+    /** Whether a staged restore put the databases back at this start (#1876): the job state in them is then the backup's. */
+    restoredAtStart() {
+        return this.restoredNow.length > 0;
+    }
+    /**
+     * Read the application database as it was just before this start's restore
+     * replaced it (#1876): the kept `*.pre-restore` file, read-only, under the
+     * site's database key, which it was encrypted under. For the owner of data
+     * in it (BackgroundJobManager's job runs since the backup) to say what the
+     * restore took away. Null when no restore replaced it at this start.
+     */
+    readReplacedApplicationDatabase(read) {
+        const kept = this.replaced?.applicationKept;
+        if (!kept || !existsSync(kept))
+            return null;
+        return SqliteDatabaseProvider.readOnce(kept, process.env[DATABASE_KEY_ENV] ?? '', (db) => read(db, this.replaced.backup));
+    }
+    /** The databases a staged restore put back at this start, by name (#1876). */
+    getRestoredAtStart() {
+        return [...this.restoredNow];
+    }
+    /** Its restore is staged for the next start (#1723), and joins a site restore (#1876). */
+    restoreIsStaged() {
+        return true;
+    }
     /** The restore staged and waiting for the next start, or null. */
     getStagedRestore() {
         if (!this.databaseFile)
@@ -476,6 +585,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);
@@ -507,7 +619,23 @@ class DatabaseManager extends BaseManager {
             const name = path.basename(resolved);
             return path.dirname(resolved) === dir && name.endsWith('.db') && ADDON_SLUG.test(name.slice(0, -3));
         };
-        const outcome = applyStagedRestore(file, allowed);
+        // #1876: a database restore staged as part of a site restore goes in only
+        // when the whole site restore does; otherwise it is set aside with it.
+        const siteFile = siteRestoreFile(this.engine.getManager('ConfigurationManager'));
+        const stagedBackupAt = this.getStagedRestore()?.backup ?? '';
+        const gate = gatePart(siteFile, 'DatabaseManager');
+        let outcome;
+        if (gate.decision === 'set-aside') {
+            outcome = setAsideStagedRestore(file, `the site restore it belongs to was not applied: ${gate.reason}`);
+            if (gate.part)
+                markPart(siteFile, 'DatabaseManager', 'set-aside', gate.reason);
+        }
+        else {
+            outcome = applyStagedRestore(file, allowed);
+            if (gate.decision === 'apply') {
+                markPart(siteFile, 'DatabaseManager', outcome && !outcome.refused ? 'applied' : 'set-aside', outcome?.refused ?? (outcome ? undefined : 'no staged database restore was found'));
+            }
+        }
         if (!outcome)
             return;
         this.restoreAtStart = outcome;
@@ -517,12 +645,16 @@ class DatabaseManager extends BaseManager {
             this.fault('restore', reason);
             return;
         }
+        this.restoredNow = outcome.applied.map((a) => a.name);
+        if (outcome.applied.length > 0) {
+            this.replaced = { backup: stagedBackupAt, applicationKept: outcome.applied.find((a) => path.resolve(a.live) === path.resolve(file))?.kept ?? null };
+        }
         for (const a of outcome.applied) {
             logger.warn(`[DatabaseManager] Restore applied: ${a.name} -> ${a.live} (previous kept as ${path.basename(a.kept)}) (#1723)`);
         }
     }
     backupKey() {
-        return (process.env[BACKUP_KEY_ENV] ?? '').trim();
+        return currentBackupKey();
     }
     /** What is wrong with the backup key: missing, or the database key itself (D3). Null when sound. */
     backupKeyProblem() {
@@ -566,8 +698,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/managers/EmailManager.d.ts

@@ -12,6 +12,14 @@
  * Implements the MailProvider interface so it can be passed directly to
  * MagicLinkAuthProvider without any changes to that class.
  *
+ * A failed send is never silent (#1916). Every sender goes through `send()`,
+ * so it is reported here, once for all of them: logged (provider, recipient
+ * domain, subject, error — never the body or the full address), the manager
+ * shows degraded until the next send succeeds, and administrators get one
+ * notification per `ngdpbase.mail.failure-notice.window-minutes` carrying a
+ * running count, not one per email. `send()` still rejects, so a caller with
+ * a person waiting can tell them.
+ *
  * @see docs/admin/email-setup.md for operator setup instructions
  * @see {@link https://github.com/jwilleke/ngdpbase/issues/456}
  */
@@ -19,21 +27,55 @@ import BaseManager from './BaseManager.js';
 import type { BackupData } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import type { MailMessage, MailProvider } 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";
+/** Title of the administrator notice. */
+export declare const SEND_FAILING_TITLE = "Email could not be sent";
 declare class EmailManager extends BaseManager implements MailProvider {
     private provider;
     private providerName;
     private from;
     private enabled;
+    private noticeWindowMs;
+    private notice;
+    private failuresSinceSuccess;
     constructor(engine: WikiEngine);
     initialize(config?: Record<string, unknown>): Promise<void>;
     /**
      * Send an email. Injects the configured from address if the message omits it.
+     *
+     * A failure is reported here (#1916) and then rethrown, so a caller with a
+     * person waiting can tell them it was not sent.
      */
     send(message: MailMessage): Promise<void>;
     /**
      * Convenience wrapper — build and send a message in one call.
      */
     sendTo(to: string, subject: string, text: string, html?: string): Promise<void>;
+    /**
+     * Send without waiting, for a sender nobody is waiting on (a form's copy, a
+     * reservation notice). Never rejects: a failure is already logged and
+     * reported to administrators by `send()` (#1916), so there is nothing left
+     * for the caller to do with it.
+     */
+    sendInBackground(to: string, subject: string, text: string, html?: string): void;
+    /** Whether sends are failing right now: degraded by a failed send, not yet cleared by a success. */
+    isDeliveryFailing(): boolean;
+    private reportFailure;
+    private reportSuccess;
+    /**
+     * One notice per window, with a running count (#1916). A failure inside an
+     * open window updates that notice; the first failure after it opens a new
+     * one. The notice is created with `escalate: false`, so it is never emailed:
+     * that send would fail and report another failure.
+     *
+     * Never throws — it runs off the failed send, and a notice that cannot be
+     * written is already covered by the error log above.
+     */
+    private noticeAdministrators;
+    private createNotice;
+    private noticeMessage;
+    private notifications;
     /** Name of the active provider: 'console' | 'smtp' */
     getProviderName(): string;
     /** Effective from address (smtp.from or mail.from) */

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

@@ -1,4 +1,4 @@
-import BaseManager from './BaseManager.js';
+import BaseManager, { type BackupData, type ManagerBackupOptions, type ManagerRestoreOptions } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import { type ActorContext } from '../context/ActorContext.js';
 import { type VaultPageNotesOutside, type PageRef } from '../utils/pageNotes.js';
@@ -17,6 +17,15 @@ export default class FootnoteManager extends BaseManager {
     private readonly outsideCheck;
     constructor(engine: WikiEngine);
     initialize(): Promise<void>;
+    /**
+     * The public folder is in the backup (#1876), as `<stem>.footnotes.tar` beside
+     * the document: the public pages' footnotes. A vault page's are in its vault, which
+     * PageManager backs up with the vault, sealed as stored.
+     */
+    backup(options?: ManagerBackupOptions): Promise<BackupData>;
+    /** Staged for the next start with the rest of a site restore (#1876); the live folder is untouched. */
+    restore(backupData: BackupData, options?: ManagerRestoreOptions): Promise<void>;
+    restoreIsStaged(): boolean;
     isEnabled(): boolean;
     /** The public folder and the vaults, as configured now (#1839). */
     private roots;

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

@@ -25,6 +25,12 @@ export interface NotificationInput {
     level?: 'info' | 'warning' | 'error' | 'success';
     targetUsers?: string[];
     expiresAt?: Date | null;
+    /**
+     * False: never email this notification, whatever the escalation settings
+     * (#1916). A notice that email is failing must not itself be emailed — the
+     * send would fail and report another failure. Not stored.
+     */
+    escalate?: boolean;
 }
 /**
  * Notification statistics
@@ -102,6 +108,13 @@ declare class NotificationManager extends BaseManager {
      * @returns {Promise<string>} Notification ID
      */
     createNotification(notification: NotificationInput): Promise<string>;
+    /**
+     * Replace an active notification's message in place (#1916) — a running
+     * count on one notice instead of a new notice per event. Never escalates:
+     * the notification was already escalated, or not, when it was created.
+     * @returns false when there is no such notification
+     */
+    updateNotificationMessage(notificationId: string, message: string): Promise<boolean>;
     /**
      * Add a notification (alias for createNotification for backward compatibility)
      * @param {NotificationInput} notification - Notification object

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

@@ -1,7 +1,9 @@
-import BaseManager, { type ManagerStats } from './BaseManager.js';
+import BaseManager, { type BackupData, type ManagerBackupOptions, type ManagerRestoreOptions, type ManagerStats } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
-import type { Organization, OrganizationUpdate } from '../types/Organization.js';
+import type { Organization, OrganizationInput, OrganizationUpdate } from '../types/Organization.js';
 import type { OrganizationProvider } from '../types/OrganizationProvider.js';
+import type { Person } from '../types/Person.js';
+import type { ActorContext } from '../context/ActorContext.js';
 /**
  * Subset of install-form data this manager needs to seed the anchor org.
  * Kept narrow so InstallService and tests can pass plain objects without
@@ -34,6 +36,8 @@ declare class OrganizationManager extends BaseManager {
     readonly description = "Canonical Organization records (#617)";
     private provider;
     private providerClass?;
+    /** `ngdpbase.application.organization.storagedir`, resolved at start: what a backup copies (#1876). */
+    private storageDir;
     private installOrgCache;
     private byIdCache;
     private byFileCache;
@@ -41,6 +45,11 @@ declare class OrganizationManager extends BaseManager {
     constructor(engine: WikiEngine);
     initialize(config?: Record<string, unknown>): Promise<void>;
     /** Provider accessor, mainly for tests. */
+    /** Organization records are in the backup (#1876), as `<stem>.organizations.tar` beside the document. */
+    backup(options?: ManagerBackupOptions): Promise<BackupData>;
+    /** Staged for the next start with the rest of a site restore (#1876); the live records are untouched. */
+    restore(backupData: BackupData, options?: ManagerRestoreOptions): Promise<void>;
+    restoreIsStaged(): boolean;
     getProvider(): OrganizationProvider | null;
     /**
      * Create the anchor organization from the instance's own identity (#1027).
@@ -81,10 +90,35 @@ declare class OrganizationManager extends BaseManager {
     getByFile(filename: string): Promise<Organization | null>;
     /** #1006: how many organizations this instance holds. Count only. */
     getManagerStats(): Promise<ManagerStats>;
-    list(): Promise<Organization[]>;
-    create(org: Organization, filename?: string): Promise<Organization>;
-    update(id: string, patch: OrganizationUpdate): Promise<Organization | null>;
-    delete(id: string): Promise<boolean>;
+    /** Every organization, for a caller who may read contacts (`contact-read`). */
+    list(ctx: ActorContext): Promise<Organization[]>;
+    /** One organization by `@id`, for a caller who may read contacts (`contact-read`). */
+    get(ctx: ActorContext, id: string): Promise<Organization | null>;
+    /**
+     * Organizations whose `name`, `legalName`, `email` or a contact point's
+     * email contains `query`, ignoring case; an empty query matches all. At
+     * most `limit` (`ngdpbase.application.organization.search.limit` by default).
+     */
+    search(ctx: ActorContext, query: string, options?: {
+        limit?: number;
+    }): Promise<Organization[]>;
+    /**
+     * The people affiliated with an organization, read from each person's
+     * `affiliation` (#1930): the link is stored once, on the person. Each comes
+     * with the role they hold there, when one is given.
+     */
+    people(ctx: ActorContext, organizationId: string): Promise<Array<{
+        person: Person;
+        role?: string;
+    }>>;
+    /**
+     * Create an organization. `name` is required; `@id` defaults to the `url`,
+     * else a new `urn:uuid:`. `filename` is for the install anchor (seeding);
+     * other records take one from the url or name.
+     */
+    create(ctx: ActorContext, org: OrganizationInput, filename?: string): Promise<Organization>;
+    update(ctx: ActorContext, id: string, patch: OrganizationUpdate): Promise<Organization | null>;
+    delete(ctx: ActorContext, id: string): Promise<boolean>;
     /**
      * Clear all caches. Called on every write — the simplest correct
      * invalidation. Per-key invalidation can come later if needed.