@jwilleke/ngdpbase-types 5.25.0 → 5.27.0

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

@@ -63,6 +63,114 @@ export interface ManagerBackupOptions {
      * failed: the restore keeps its file beside the restored one instead.
      */
     safetyBackup?: boolean;
+    /**
+     * One more archive beside the document, named and keyed by BackupManager
+     * (#1985), for a manager whose files are not a declared folder. A declared
+     * folder or file (`backupFolders()`) needs none of this.
+     */
+    archive?: (part: string) => BackupArchiveTarget;
+}
+/**
+ * A folder or file part's record in a manager's entry of the backup document
+ * (#1876, #1985): the archive beside the document and what it holds. The
+ * shape every backup since v5.21 writes; a restore reads it as it is.
+ */
+export interface BackupPartRecord {
+    format: 1;
+    /** The archive beside the document: `<stem>.<part>.tar`, or `.tar.enc` when encrypted. */
+    archive: string;
+    files: number;
+    bytes: number;
+    /** `backupKeyFingerprint()` of the key the archive is encrypted under; absent when it is not encrypted. */
+    keyFingerprint?: string;
+}
+/**
+ * A folder a manager keeps its data in (#1985): BackupManager archives it
+ * beside the backup document, stages it in a site restore, and puts the
+ * staged copy in place at the next start before the manager reads it.
+ */
+export interface BackupFolderPart {
+    /** The archive's name: `<stem>.<part>.tar` (`.tar.enc` under the backup key). Never change it: old backups are matched by it. */
+    part: string;
+    /** The folder, resolved; null when this site has none configured. */
+    folder: string | null;
+    /** Leave out a path relative to the folder, in posix form (job state's slot locks). */
+    exclude?: (relative: string) => boolean;
+    /**
+     * A backup with no record of this part stages nothing for it, and the
+     * restore names it as not restored. Without it such a backup refuses the
+     * whole site restore (one taken before the part was backed up).
+     */
+    optional?: boolean;
+}
+/**
+ * One file a manager keeps its data in (#1985): the credentials store. As a
+ * folder, but the archive holds the one file.
+ */
+export interface BackupFilePart {
+    part: string;
+    /** The file, resolved; null when this site has none configured. */
+    file: string | null;
+    /** How the backup and the log name it ("credentials store"). */
+    what: string;
+    /** Only ever backed up encrypted: without the backup key it is left out, with a warning (#1876). */
+    requireKey?: boolean;
+    /** Staged in its place when the file was absent at backup time, so the restore still puts the site back as it was. */
+    whenAbsent: string;
+    optional?: boolean;
+}
+/** What a manager declares as its data (#1985). */
+export type BackupFolder = BackupFolderPart | BackupFilePart;
+/**
+ * One more archive beside the backup document, named and keyed by
+ * BackupManager (#1985): for a manager whose files are not one declared
+ * folder (the attachment pool and vaults, the audit log among the
+ * application logs). Encrypted under the backup key when it is set.
+ */
+export interface BackupArchiveTarget {
+    /** Its file name, `<stem>.<part>.tar` or `.tar.enc`: what the entry records. */
+    archive: string;
+    /** Where to write it. */
+    path: string;
+    backupKey?: string;
+    keyFingerprint?: string;
+}
+/** One live path and the staged copy that replaces it at the next start (#1876). */
+export interface StagedSwap {
+    live: string;
+    staged: string;
+}
+/**
+ * A whole-site restore being staged (#1876), handed to a manager's
+ * `restore()` by BackupManager, which keeps the record that binds the parts
+ * together (#1986). A manager whose restore is staged
+ * (`restoreIsStaged()`) stages its files beside its live ones and records
+ * its part here; nothing else writes that record.
+ */
+export interface SiteRestoreStaging {
+    /** Where the staged copy of a live path goes: beside it, `<live>.staged`. The next start applies nothing named otherwise. */
+    stagedPathFor(live: string): string;
+    /**
+     * Record this manager's part: the pairs the next start swaps in, all
+     * together with every other part or not at all. `discard` names further
+     * files to remove if the restore is thrown away (DatabaseManager's own
+     * manifest).
+     */
+    record(swaps: StagedSwap[], options?: {
+        discard?: string[];
+    }): void;
+}
+/** What a staged restore of a manager's part did at this start (#1985, #1986). */
+export interface StagedRestoreAtStart {
+    /** Each live path now restored, with where its previous content was kept. */
+    applied: Array<{
+        live: string;
+        kept: string;
+    }>;
+    /** Why nothing (or, after a failed rename, not everything) was applied. */
+    refused?: string;
+    /** When the backup it came from was taken. */
+    backupTakenAt?: string;
 }
 /** What BackupManager hands each manager's `restore()` (#1723): who asked, and the directory the backup document was read from. */
 export interface ManagerRestoreOptions {
@@ -79,12 +187,23 @@ export interface ManagerRestoreOptions {
     /** The backup of the live data BackupManager took just before this restore (#1723, D6), by filename. */
     safetyBackup?: string;
     /**
-     * The site restore manifest this restore is staged under (#1876). A
-     * manager whose restore is staged (`restoreIsStaged()`) stages its files
-     * beside its live ones and records its part there; the next start applies
-     * every part or none (`src/utils/siteRestore.ts`).
+     * Present when this restore is staged as part of a whole-site restore
+     * (#1876): a manager whose restore is staged (`restoreIsStaged()`) stages
+     * its files beside its live ones and records its part through it; the
+     * next start applies every part or none. BackupManager keeps the record
+     * (#1986).
      */
-    siteRestore?: string;
+    siteRestore?: SiteRestoreStaging;
+    /**
+     * An archive the backup names, checked by BackupManager (#1985): a bare
+     * file name in the backup directory, read under the key its fingerprint
+     * names. Throws, naming `manager`, for anything else. For a manager that
+     * stages its own files (attachments, the audit log).
+     */
+    readArchive?: (manager: string, archive: unknown, keyFingerprint: string | undefined) => {
+        path: string;
+        backupKey?: string;
+    };
 }
 /**
  * Base class for all managers
@@ -209,6 +328,35 @@ declare abstract class BaseManager {
      * }
      */
     initialize(config?: Record<string, unknown>): Promise<void>;
+    /**
+     * Where this manager keeps its data as folders or files (#1985): declared,
+     * never backed up by hand. BackupManager archives each beside the backup
+     * document (`<stem>.<part>.tar`), stages it in a site restore, and puts the
+     * staged copy in place at the next start, in `initialize()` above, before
+     * the subclass reads it. Resolved from the configuration, so it can be
+     * answered before the subclass's own `initialize()` has run. Default none.
+     *
+     * A manager with data in the document as well keeps its `backup()`; a
+     * declared part's record goes beside that data (`data[part]`), or is the
+     * entry's `data` when the manager has none and declares one part.
+     */
+    backupFolders(): BackupFolder[];
+    /** What putting a staged restore of the declared parts in place did at this start, or null (#1985). */
+    private stagedRestore;
+    /** What this start did with a staged restore of this manager's declared parts (#1985): null when there was none. */
+    protected stagedRestoreAtStart(): StagedRestoreAtStart | null;
+    /**
+     * The name this manager is registered under: a staged part is recorded by
+     * it. Its class name when it is not registered (a test).
+     */
+    private registeredName;
+    /**
+     * #1985: a staged site restore of the declared parts goes in before the
+     * subclass reads them. BackupManager's own step, reached through its
+     * module (BackupManager starts after most managers); loaded only when there
+     * is something declared. A part not applied is said on the dashboard.
+     */
+    private applyStagedBackupParts;
     /**
      * Check if manager has been initialized
      *
@@ -375,7 +523,9 @@ declare abstract class BaseManager {
      * Whether this manager's `restore()` stages for the next start instead of
      * writing into the running site (#1723, #1876). BackupManager stages every
      * such manager in a site restore together, all or nothing, after a backup
-     * of the live data. The default is false: the restore writes live.
+     * of the live data. The default: true when it declares folders or files
+     * (#1985), which BackupManager stages; otherwise false, the restore writes
+     * live.
      */
     restoreIsStaged(): boolean;
     /**

package/lib/src/managers/BaseManager.js

@@ -67,8 +67,63 @@ class BaseManager {
      */
     async initialize(config = {}) {
         this.config = config;
+        // #1985: before anything is read, and before the manager counts as started.
+        await this.applyStagedBackupParts();
         this.initialized = true;
     }
+    /**
+     * Where this manager keeps its data as folders or files (#1985): declared,
+     * never backed up by hand. BackupManager archives each beside the backup
+     * document (`<stem>.<part>.tar`), stages it in a site restore, and puts the
+     * staged copy in place at the next start, in `initialize()` above, before
+     * the subclass reads it. Resolved from the configuration, so it can be
+     * answered before the subclass's own `initialize()` has run. Default none.
+     *
+     * A manager with data in the document as well keeps its `backup()`; a
+     * declared part's record goes beside that data (`data[part]`), or is the
+     * entry's `data` when the manager has none and declares one part.
+     */
+    backupFolders() {
+        return [];
+    }
+    /** What putting a staged restore of the declared parts in place did at this start, or null (#1985). */
+    stagedRestore = null;
+    /** What this start did with a staged restore of this manager's declared parts (#1985): null when there was none. */
+    stagedRestoreAtStart() {
+        return this.stagedRestore;
+    }
+    /**
+     * The name this manager is registered under: a staged part is recorded by
+     * it. Its class name when it is not registered (a test).
+     */
+    registeredName() {
+        const engine = this.engine;
+        const names = typeof engine?.getRegisteredManagers === 'function' ? engine.getRegisteredManagers() : [];
+        return names.find((n) => engine?.getManager?.(n) === this) ?? this.constructor.name;
+    }
+    /**
+     * #1985: a staged site restore of the declared parts goes in before the
+     * subclass reads them. BackupManager's own step, reached through its
+     * module (BackupManager starts after most managers); loaded only when there
+     * is something declared. A part not applied is said on the dashboard.
+     */
+    async applyStagedBackupParts() {
+        let declared;
+        try {
+            declared = this.backupFolders();
+        }
+        catch (err) {
+            logger.error(`[${this.constructor.name}] Its backup folders could not be read, so a staged restore of them was not checked: ${err.message}`);
+            return;
+        }
+        if (declared.length === 0)
+            return;
+        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}`);
+        }
+    }
     /**
      * Check if manager has been initialized
      *
@@ -312,10 +367,17 @@ class BaseManager {
      * Whether this manager's `restore()` stages for the next start instead of
      * writing into the running site (#1723, #1876). BackupManager stages every
      * such manager in a site restore together, all or nothing, after a backup
-     * of the live data. The default is false: the restore writes live.
+     * of the live data. The default: true when it declares folders or files
+     * (#1985), which BackupManager stages; otherwise false, the restore writes
+     * live.
      */
     restoreIsStaged() {
-        return false;
+        try {
+            return this.backupFolders().length > 0;
+        }
+        catch {
+            return false;
+        }
     }
     /**
      * Return a plain-text string suitable for use as MarqueePlugin banner text.

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

@@ -1,4 +1,4 @@
-import BaseManager, { type BackupData, type ManagerBackupOptions, type ManagerRestoreOptions } from './BaseManager.js';
+import BaseManager, { type BackupFolder } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import type { PageComment } from '../types/Comment.js';
 import { type ActorContext } from '../context/ActorContext.js';
@@ -10,15 +10,15 @@ export default class CommentManager extends BaseManager {
     private readonly outsideCheck;
     constructor(engine: WikiEngine);
     initialize(): Promise<void>;
+    /** `ngdpbase.comments.storagedir`, resolved, or the default when there is no configuration (a test). */
+    private configuredDir;
     /**
      * The public folder is in the backup (#1876), as `<stem>.comments.tar` beside
      * the document: the public pages' comments. A vault page's are in its vault, which
-     * PageManager backs up with the vault, sealed as stored.
+     * PageManager backs up with the vault, sealed as stored. BackupManager backs
+     * it up, stages it, and puts it in place at the next start (#1985).
      */
-    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;
+    backupFolders(): BackupFolder[];
     isEnabled(): boolean;
     /** The public folder and the vaults, as configured now (#1839). */
     private roots;

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

@@ -0,0 +1,130 @@
+/**
+ * ConsentManager — what each person has accepted, and asking them (#1603).
+ *
+ * It owns two things and asks for everything else:
+ *
+ * - __The records.__ One append-only file per account
+ *   (`ngdpbase.consent.storagedir`, `FileConsentProvider`), owner-only: which
+ *   document, which version, its effective date, when, and who and how.
+ * - __The prompts.__ Which documents a person still has to accept: core's
+ *   (`ngdpbase.consent.documents`, asked at sign-up and at an interactive
+ *   sign-in) and each add-on's (asked before its per-person switch turns on,
+ *   and again on a version change when the person next uses it).
+ *
+ * The documents themselves are pages, read when asked (`version:` and
+ * `effective:` front matter), never copied. Whether a person has accepted
+ * the current version is derived each time from their records and the page,
+ * so a version change "clears" everyone's acceptance without touching a
+ * record. Per-use consents — apps approved through `/oidc`, share links —
+ * stay with their owners (OidcManager, ShareManager).
+ *
+ * Only the person accepts, for themselves: never a token, a share or a proxy
+ * acting for them, and never an administrator on their behalf. Each
+ * acceptance is recorded in the audit log (`consent-grant`, on-failure
+ * refuse) before it is stored.
+ */
+import BaseManager, { type BackupFolder } from './BaseManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import { type ActorContext } from '../context/ActorContext.js';
+import { type AddonConsentRegistration, type ConsentDocument, type ConsentRecord, type ConsentScope, type ConsentSeen, type ConsentStatus } from '../types/Consent.js';
+export declare const CONSENT_DOCUMENTS_KEY = "ngdpbase.consent.documents";
+/** Refused: not this person, not signed in themselves, or not allowed. Nothing was recorded. */
+export declare class ConsentRefusedError extends Error {
+    readonly name = "ConsentRefusedError";
+}
+/** A document changed (or appeared) after the person was shown it; show it again. Nothing was recorded. */
+export declare class ConsentChangedError extends Error {
+    readonly name = "ConsentChangedError";
+}
+/** The documents of one scope with this person's state, for "Your consents". */
+export interface ConsentScopeStatus {
+    scope: ConsentScope;
+    statuses: ConsentStatus[];
+}
+declare class ConsentManager extends BaseManager {
+    readonly description = "What each person has accepted \u2014 core's terms and add-ons' documents \u2014 and asking them (#1603)";
+    private provider;
+    private storageDir;
+    /** Add-on slug → its documents and the paths it is used at, registered at load. */
+    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. */
+    private readonly problems;
+    private attentionReason;
+    constructor(engine: WikiEngine);
+    initialize(config?: Record<string, unknown>): Promise<void>;
+    private configuredStorageDir;
+    /** The consent records folder is in the backup (#1985); a backup from before #1603 has none, so it is optional. */
+    backupFolders(): BackupFolder[];
+    /**
+     * An add-on's documents (#1603), registered from its `register()`. Each id
+     * must start `<slug>-`, so an add-on can never register core's documents or
+     * another add-on's; the add-on must be per-person (`perPerson: true`),
+     * since its documents are accepted when a person turns it on. Registering
+     * twice replaces the first.
+     */
+    registerAddonDocuments(slug: string, registration: AddonConsentRegistration): void;
+    /** The add-ons that registered documents, in registration order. */
+    registeredAddons(): string[];
+    /** The add-on whose registered path `path` is under, or null. */
+    addonForPath(path: string): string | null;
+    /** Every document id a person may be asked to accept, core's and every add-on's: the pages that stay readable while they are asked. */
+    allDocumentIds(): string[];
+    private documentIds;
+    /**
+     * The documents of `scope` as they stand now. A page that is missing, or
+     * has no `version:`, is left out — nobody is asked for it, nothing is
+     * blocked — and ConsentManager needs attention until it is back.
+     */
+    documents(scope?: ConsentScope): Promise<ConsentDocument[]>;
+    private readDocument;
+    /** Needs attention while any document cannot be asked for; ready again once none is (warn, never force). */
+    private reportProblems;
+    /** Read every document once, so a missing one shows on the dashboard from start-up. Called after the required pages are seeded. */
+    checkDocuments(): Promise<void>;
+    /**
+     * `username`'s records on their current account, oldest first. A record
+     * made on an earlier account of the same name is never theirs (#1937).
+     */
+    private recordsOf;
+    private accountOf;
+    /**
+     * The documents of `scope` that `username` has not accepted at their
+     * current version — what they are to be asked. Empty when there is
+     * nothing to ask (no documents, or no consent folder).
+     */
+    pendingFor(username: string, scope?: ConsentScope): Promise<ConsentDocument[]>;
+    /**
+     * "Your consents" for the person `ctx` acts as: each document of core's and
+     * of each registered add-on, with their acceptance of the current version
+     * (or none) and their latest of any version.
+     */
+    statusFor(ctx: ActorContext): Promise<ConsentScopeStatus[]>;
+    /**
+     * Record that the person `ctx` acts as accepted what they were shown:
+     * every document of `scope` they have not accepted at its current version.
+     *
+     * - Only the person, for themselves: a token, share or proxy is refused, and
+     *   there is no way to name anyone else. The person must hold
+     *   `profile-manage`, the permission for managing their own account.
+     * - `seen` is what they were shown. A pending document missing from it, or
+     *   shown at another version, refuses with `ConsentChangedError`, so nobody
+     *   is recorded as accepting a version they never saw.
+     * - Each acceptance is recorded as `consent-grant` (on-failure refuse)
+     *   before it is stored: a failed audit record refuses the acceptance.
+     *
+     * @param how How they were asked: `sign-up`, `sign-in` or `add-on`
+     * @returns The records written; empty when there was nothing to accept
+     */
+    accept(ctx: ActorContext, scope: ConsentScope, seen: ConsentSeen[], how: string): Promise<ConsentRecord[]>;
+    /**
+     * The account `username` was deleted (`AuthManager.closeAccess`): its
+     * records go with it, after `consent-withdraw` names what it had accepted
+     * (on-failure refuse: the records stay, and a later account of that name
+     * still never inherits them). The audit log keeps the events for its
+     * retention window.
+     */
+    removeAccount(username: string, ctx: ActorContext): Promise<void>;
+}
+export default ConsentManager;

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

@@ -92,6 +92,12 @@ declare class DatabaseManager extends BaseManager {
     initialize(config?: Record<string, unknown>): Promise<void>;
     /** Whether an application database is open. */
     isEnabled(): boolean;
+    /**
+     * Whether the open application database is encrypted at rest (SQLCipher,
+     * `NGDPBASE_DATABASE_KEY`); false when none is open. Asked by a provider
+     * that reports what its records are stored under (#1537).
+     */
+    isEncrypted(): boolean;
     /**
      * Why the configured application database is not open (#1892): it could not
      * be opened safely, and the site is in maintenance mode. Null when it is

package/lib/src/managers/DatabaseManager.js

@@ -47,7 +47,6 @@ 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, 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';
@@ -134,7 +133,7 @@ class DatabaseManager extends BaseManager {
         this.databaseFile = file;
         // #1723: a staged restore goes in now, before any database opens.
         try {
-            this.applyRestoreAtStart(file);
+            await this.applyRestoreAtStart(file);
         }
         catch (err) {
             this.markUnavailable(`A staged database restore could not be put in place: ${err.message}. ` +
@@ -172,6 +171,14 @@ class DatabaseManager extends BaseManager {
     isEnabled() {
         return this.provider !== null;
     }
+    /**
+     * Whether the open application database is encrypted at rest (SQLCipher,
+     * `NGDPBASE_DATABASE_KEY`); false when none is open. Asked by a provider
+     * that reports what its records are stored under (#1537).
+     */
+    isEncrypted() {
+        return this.provider?.storage().encrypted ?? false;
+    }
     /**
      * 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
@@ -361,6 +368,15 @@ class DatabaseManager extends BaseManager {
         else {
             this.clearFault('backup-key');
         }
+        // #1537: the database audit provider buffers `continue` records; written
+        // first, so every record accepted before the backup is in the copy. A
+        // flush that fails leaves them queued and is logged; the backup goes on.
+        try {
+            await this.engine.getManager('AuditManager')?.flushAuditQueue?.();
+        }
+        catch (err) {
+            logger.warn('[DatabaseManager] The audit queue could not be written before the backup; records still queued are not in it (#1537):', err);
+        }
         const sources = this.backupSources(this.databaseFile);
         const absent = sources.filter((s) => !existsSync(s.file)).map((s) => s.name);
         const exports = sources
@@ -494,13 +510,7 @@ class DatabaseManager extends BaseManager {
         };
         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]
-            });
-        }
+        options.siteRestore?.record(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)`);
         const unopened = this.unavailable
@@ -611,7 +621,7 @@ class DatabaseManager extends BaseManager {
         return sources;
     }
     /** Put a staged restore in place, before any database opens; loud when it cannot. */
-    applyRestoreAtStart(file) {
+    async applyRestoreAtStart(file) {
         const dir = path.resolve(path.dirname(file));
         const allowed = (live) => {
             const resolved = path.resolve(live);
@@ -622,19 +632,19 @@ class DatabaseManager extends BaseManager {
         };
         // #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'));
+        // BackupManager keeps that record and decides (#1986); a module function, as DatabaseManager starts first.
+        const { siteRestorePartAtStart } = await import('./BackupManager.js');
         const stagedBackupAt = this.getStagedRestore()?.backup ?? '';
-        const gate = gatePart(siteFile, 'DatabaseManager');
+        const gate = siteRestorePartAtStart(this.engine, '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);
+            gate.settle('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'));
+                gate.settle(outcome && !outcome.refused ? 'applied' : 'set-aside', outcome?.refused ?? (outcome ? undefined : 'no staged database restore was found'));
             }
         }
         if (!outcome)

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

@@ -20,17 +20,34 @@
  * running count, not one per email. `send()` still rejects, so a caller with
  * a person waiting can tell them.
  *
+ * `sendTo(ctx, …, { attachments })` attaches files, a PDF from
+ * `ExportManager.htmlToPdf` for one (#1974), up to
+ * `ngdpbase.mail.attachments.max-bytes` in total. A log line names how many
+ * files and bytes, never their names or content.
+ *
  * @see docs/admin/email-setup.md for operator setup instructions
  * @see {@link https://github.com/jwilleke/ngdpbase/issues/456}
  */
 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';
+import type { MailAttachment, MailMessage, MailProvider } from '../mail/MailProvider.js';
+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";
 /** 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. */
+export declare class AttachmentRefusedError extends Error {
+    readonly code = "ATTACHMENT_REFUSED";
+    constructor(message: string);
+}
+/** What a caller may add after the body (#1974). */
+export interface SendOptions {
+    /** Files to attach, e.g. a PDF from `ExportManager.htmlToPdf`. */
+    attachments?: MailAttachment[];
+}
 declare class EmailManager extends BaseManager implements MailProvider {
     private provider;
     private providerName;
@@ -39,6 +56,7 @@ declare class EmailManager extends BaseManager implements MailProvider {
     private noticeWindowMs;
     private notice;
     private failuresSinceSuccess;
+    private attachmentMaxBytes;
     constructor(engine: WikiEngine);
     initialize(config?: Record<string, unknown>): Promise<void>;
     /**
@@ -49,16 +67,25 @@ declare class EmailManager extends BaseManager implements MailProvider {
      */
     send(message: MailMessage): Promise<void>;
     /**
-     * Convenience wrapper — build and send a message in one call.
+     * Build and send a message in one call.
+     *
+     * @param ctx - Who is sending (security-posture P1); named in the log line when the message carries attachments
+     * @param to - Recipient address
+     * @param subject - Subject line
+     * @param text - Plain-text body
+     * @param html - Optional HTML body
+     * @param options - Attachments (#1974); their total is capped by `ngdpbase.mail.attachments.max-bytes`
      */
-    sendTo(to: string, subject: string, text: string, html?: string): Promise<void>;
+    sendTo(ctx: ActorContext, to: string, subject: string, text: string, html?: string, options?: SendOptions): 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.
+     * for the caller to do with it. An attachment over the limit is logged here.
      */
-    sendInBackground(to: string, subject: string, text: string, html?: string): void;
+    sendInBackground(ctx: ActorContext, to: string, subject: string, text: string, html?: string, options?: SendOptions): void;
+    /** Refuse attachments a mail relay would choke on, or that are not what they say. */
+    private checkAttachments;
     /** Whether sends are failing right now: degraded by a failed send, not yet cleared by a success. */
     isDeliveryFailing(): boolean;
     private reportFailure;