@jwilleke/ngdpbase-types 5.21.0 → 5.23.0

package/lib/src/managers/DatabaseManager.js

@@ -40,34 +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 { sitePublicMessage } from '../utils/startupState.js';
-import { applyStagedRestore, manifestPath, runOffThread, stagedPath, writeManifest } from '../providers/sqliteBackup.js';
-/** The environment variable holding the SQLCipher key. Never a config key: config is readable from the admin screens. */
-export const DATABASE_KEY_ENV = 'NGDPBASE_DATABASE_KEY';
-/**
- * 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}`;
@@ -112,6 +100,10 @@ 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. */
@@ -190,8 +182,8 @@ class DatabaseManager extends BaseManager {
     }
     /**
      * #1892 (operator D3 rule, 2026-10-18): the application database can't be
-     * opened safely. The process stays up in maintenance mode through core's
-     * survivable path (#1152): visitors see only the public message (#1883),
+     * 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.
      */
@@ -200,10 +192,8 @@ class DatabaseManager extends BaseManager {
         this.provider = null;
         logger.error(`[DatabaseManager] ${reason}`);
         this.markFailed(reason, 'ngdpbase.database.file');
-        const configManager = this.engine.getManager('ConfigurationManager');
-        this.engine.blockConfiguration(reason, {
-            publicMessage: sitePublicMessage(configManager ? (k, d) => configManager.getProperty(k, d) : undefined)
-        });
+        // #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) {
@@ -355,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);
         }
@@ -502,6 +492,14 @@ 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)`);
         const unopened = this.unavailable
@@ -514,6 +512,31 @@ class DatabaseManager extends BaseManager {
             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)
@@ -596,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;
@@ -606,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() {

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.

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

@@ -1,12 +1,37 @@
-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 { Person, PersonUpdate } from '../types/Person.js';
+import type { Person, PersonInput, PersonUpdate } from '../types/Person.js';
 import type { PersonProvider } from '../types/PersonProvider.js';
+import { type ActorContext } from '../context/ActorContext.js';
+/** What the confirmation page shows: the person the link would join. */
+export interface LinkOfferDetails {
+    personName: string | null;
+    email: string;
+}
+/** The outcome of offering a sign-up link (#1930). */
+export type LinkOfferOutcome = 'sent' | 'no-match' | 'several' | 'unavailable' | 'failed';
 /**
- * PersonManager — canonical core record for persons (#617).
+ * PersonManager — canonical core record for persons (#617), and the door for
+ * contacts (#1930).
+ *
+ * A person may have an account or not. Each account has exactly one person
+ * (`identifier` = the username); a person with no account has the identifier
+ * `person:<uuid>`, which no username may take. UserManager calls the door on
+ * the account lifecycle under a system context.
+ *
+ * The door: `create`, `update`, `delete`, `get`, `list`, `search` and
+ * `linkAccount` take the caller's context first and ask the PDP: `contact-read`
+ * to list, search or get; `contact-manage` to change (`linkAccount` also `user-edit`). Each change is recorded as
+ * the `contact-manage` audit event. A refusal throws `ContactRefusedError`.
+ * `getById` / `getByIdentifier` stay as context-free lookups for core's own
+ * hot paths (RoleManager resolves roles through them on every request).
+ *
+ * A later sign-up joins a person with no account in one of two ways: the new
+ * account confirms an emailed link (`offerSignUpLink` → `confirmSignUpLink`),
+ * or an administrator links them (`linkAccount`). Either way the existing
+ * person keeps its `@id` and takes the account; the person made for the new
+ * account is folded into it and removed, so there is never a second person.
  *
- * Each User has at most one paired Person record. UserManager calls
- * `create`/`update`/`delete` here on the matching user lifecycle events.
  * `getByUserIdentifier(username)` remains as a lazy-migration entry point
  * for legacy users that pre-date the sync wiring.
  */
@@ -14,20 +39,91 @@ declare class PersonManager extends BaseManager {
     readonly description = "Canonical Person records (#617)";
     private provider;
     private providerClass?;
+    /** `ngdpbase.application.persons.storagedir`, resolved at start: what a backup copies (#1876). */
+    private storageDir;
     private byIdentifierCache;
     private byIdCache;
     private metricsRef;
+    /** Sign-up link offers by token (#1930). In memory: a restart drops them, and an administrator links by hand. */
+    private linkOffers;
     constructor(engine: WikiEngine);
     initialize(config?: Record<string, unknown>): Promise<void>;
+    /** Person records are in the backup (#1876), as `<stem>.persons.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(): PersonProvider | null;
     getById(id: string): Promise<Person | null>;
     getByIdentifier(identifier: string): Promise<Person | null>;
     /** #1006: how many people this instance holds. Count only, never records. */
     getManagerStats(): Promise<ManagerStats>;
-    list(): Promise<Person[]>;
-    create(person: Person): Promise<Person>;
-    update(id: string, patch: PersonUpdate): Promise<Person | null>;
-    delete(id: string): Promise<boolean>;
+    /** True when the person has no account: its identifier is `person:<uuid>` (#1930). */
+    static isAccountless(person: Pick<Person, 'identifier'>): boolean;
+    /** Every person, for a caller who may read contacts (`contact-read`). */
+    list(ctx: ActorContext): Promise<Person[]>;
+    /** One person by `@id`, for a caller who may read contacts (`contact-read`). */
+    get(ctx: ActorContext, id: string): Promise<Person | null>;
+    /**
+     * Persons whose name (`name`, `givenName`, `familyName`) or `email` contains
+     * `query`, ignoring case; an empty query matches everyone. `accountless`
+     * narrows to persons with no account. At most `limit` results
+     * (`ngdpbase.application.persons.search.limit` by default).
+     */
+    search(ctx: ActorContext, query: string, options?: {
+        limit?: number;
+        accountless?: boolean;
+    }): Promise<Person[]>;
+    /**
+     * Create a person. With no `identifier` the person has no account and gets
+     * `person:<uuid>`. An `identifier` must be an existing account that has no
+     * person yet: that is how UserManager makes the person for a new account.
+     */
+    create(ctx: ActorContext, input: PersonInput): Promise<Person>;
+    /** Change a person's fields, affiliations included. `@id` and `identifier` never change here. */
+    update(ctx: ActorContext, id: string, patch: PersonUpdate): Promise<Person | null>;
+    delete(ctx: ActorContext, id: string): Promise<boolean>;
+    /**
+     * An administrator joins a person who has no account to an account (#1930),
+     * for when the email differs or none was given. Asks `contact-manage` and
+     * `user-edit`. The person keeps its `@id`; the account's own person, if it
+     * has one, is folded in and removed.
+     */
+    linkAccount(ctx: ActorContext, personId: string, username: string): Promise<Person>;
+    /**
+     * Offer a new account the person with no account who has the same email
+     * ("Is this you?"): a single-use link is mailed to that address, and the
+     * account joins the person only when it confirms. Called by UserManager
+     * after an account is created. Skipped when email links are not available
+     * on this site; nothing is offered when no person, or more than one, has
+     * that address (an administrator links those by hand). `ctx` is the context
+     * the account was created under, named in the log.
+     */
+    offerSignUpLink(ctx: ActorContext, username: string): Promise<LinkOfferOutcome>;
+    /** What the confirmation page shows, for the signed-in account the link was sent to; null for an unknown, used, expired or other account's link. */
+    signUpLinkOffer(ctx: ActorContext, token: string): Promise<LinkOfferDetails | null>;
+    /**
+     * The new account confirms the emailed link: it is joined to the person.
+     * Single use. The link is the authority — it proves the address and is
+     * bound to the account it was sent for — so no permission is asked; the
+     * change is recorded under the account's own context. Null for a link that
+     * is unknown, used, expired, or another account's.
+     */
+    confirmSignUpLink(ctx: ActorContext, token: string): Promise<Person | null>;
+    /** The new account says the record is not theirs: the link is dropped. */
+    declineSignUpLink(ctx: ActorContext, token: string): boolean;
+    private liveOffer;
+    private sweepLinkOffers;
+    /**
+     * Join `username` to the person `personId`, who has no account. The person
+     * takes the account's identifier and keeps its `@id`; fields it lacks are
+     * filled from the account's own person, that person's role memberships move
+     * to it, and that person is removed. Never a second person.
+     */
+    private join;
+    /** Each affiliation names an organization that exists; `role` is trimmed text. Throws on any other shape. */
+    private checkedAffiliations;
+    private configNumber;
     /**
      * Clear all caches. Called on every write — the simplest correct
      * invalidation. Per-key invalidation can come later if needed.
@@ -45,4 +141,5 @@ declare class PersonManager extends BaseManager {
     private getMetrics;
     private normalizeProviderName;
 }
+export { ContactRefusedError } from '../utils/contactAccess.js';
 export default PersonManager;

package/lib/src/managers/RoleManager.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 { Role, RoleUpdate } from '../types/Role.js';
 import type { RoleProvider } from '../types/RoleProvider.js';
@@ -8,6 +8,8 @@ declare class RoleManager extends BaseManager {
     readonly description = "Canonical OrganizationRole records (#617 follow-up)";
     private provider;
     private providerClass?;
+    /** `ngdpbase.application.roles.storagedir`, resolved at start: what a backup copies (#1876). */
+    private storageDir;
     private memberCache;
     private byOrgPositionCache;
     private metricsRef;
@@ -31,6 +33,15 @@ declare class RoleManager extends BaseManager {
      * as is any other `additionalProperty` entry.
      */
     private stripCatalogueCopies;
+    /**
+     * Role membership is in the backup (#1876): the role records folder, as
+     * `<stem>.roles.tar` beside the document. Without it restored users would
+     * have no roles.
+     */
+    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;
     /** Provider accessor, mainly for tests. */
     getProvider(): RoleProvider | null;
     getById(id: string): Promise<Role | null>;
@@ -102,6 +113,13 @@ declare class RoleManager extends BaseManager {
      * @returns how many accounts were given the role (0 once it has been given)
      */
     grantToEveryAccountOnce(roleName: string, usernames: readonly string[], ctx: JobContext): Promise<number>;
+    /**
+     * Move every membership held by one Person `@id` to another (#1930): when
+     * PersonManager joins an account to an existing person, the roles the
+     * account's person held go with the account. One write per role record;
+     * returns how many records changed. PersonManager's join records the change.
+     */
+    moveMemberships(fromPersonId: string, toPersonId: string): Promise<number>;
     /** Remove a deleted account's Person from every role it held. */
     removeAllMemberships(username: string): Promise<void>;
     /**

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

@@ -0,0 +1,94 @@
+/**
+ * SessionStatsManager — in-process reads of the session store (#1246).
+ *
+ * Two things want to know how many sessions exist and who holds them: the
+ * `/api/session-count` and `/api/session-users` routes, and SessionsPlugin,
+ * which renders those numbers into a page. The plugin used to get them by
+ * making an HTTP request to this server's own address through a bare global
+ * `fetch` — an outbound call outside `src/http/` (#1133) that `guardedFetch`
+ * cannot take, because loopback is refused unconditionally (#1186), and one
+ * that silently rendered `0` in any container whose configured host was not
+ * reachable from inside the process.
+ *
+ * The store is an in-process object. Nothing about reading it needs a socket.
+ * app.ts attaches the store it built for express-session; the routes keep
+ * reading `req.sessionStore` (the same object) and both go through the same
+ * two helpers, so there is exactly one implementation of "count sessions" and
+ * "list session users".
+ */
+import BaseManager from './BaseManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+/** The two optional store methods express-session stores may implement. */
+export interface SessionStoreLike {
+    length?(callback: (err: unknown, count?: number) => void): void;
+    all?(callback: (err: unknown, sessions?: unknown) => void): void;
+    /** session-file-store: the session file names, not the sessions. */
+    list?(callback: (err: unknown, files?: string[]) => void): void;
+    get?(sid: string, callback: (err: unknown, session?: unknown) => void): void;
+    destroy?(sid: string, callback: (err: unknown) => void): void;
+    /** session-file-store keeps its file extension here (default `.json`). */
+    options?: {
+        fileExtension?: string;
+    };
+}
+export interface SessionCount {
+    sessionCount: number;
+    distinctUsers: number;
+}
+export interface SessionUsers {
+    users: string[];
+    anonymous: number;
+    total: number;
+}
+/** Thrown when the store implements neither `length` nor `all`. */
+export declare class SessionStoreUnsupportedError extends Error {
+    constructor(what: string);
+}
+/**
+ * Session count and distinct-user count. Prefers `length` (cheap), falls back
+ * to `all`. Under `length` the distinct-user figure equals the session count,
+ * which is what the route always reported on that path.
+ */
+export declare function countSessions(store: SessionStoreLike): Promise<SessionCount>;
+/**
+ * Authenticated usernames (sorted, distinct) and the anonymous session count.
+ * Needs `all`; under `length` alone the list is empty and every session is
+ * reported as anonymous.
+ */
+export declare function listSessionUsers(store: SessionStoreLike): Promise<SessionUsers>;
+/** A session in the store, with its id. */
+export interface StoredSession {
+    sid: string;
+    session: Record<string, unknown>;
+}
+/**
+ * Every session in the store with its id (#1937): `all()` keyed by id where
+ * the store has it, else list and read each (the file store). A store whose
+ * `all()` returns a bare array gives no ids, so it cannot be listed this way.
+ */
+export declare function storedSessions(store: SessionStoreLike): Promise<StoredSession[]>;
+/**
+ * The private-store handles held by sessions still in the store (#1626).
+ * Uses `all()` where the store has it, else lists and reads each session:
+ * the file store has no `all()`, so the sweep failed on every run there and
+ * no orphaned key was ever dropped.
+ */
+export declare function liveSessionHandles(store: SessionStoreLike): Promise<Set<string>>;
+declare class SessionStatsManager extends BaseManager {
+    private store;
+    constructor(engine: WikiEngine);
+    /** app.ts hands over the store it built for express-session. */
+    attachStore(store: SessionStoreLike): void;
+    hasStore(): boolean;
+    /** @throws Error when no store is attached; SessionStoreUnsupportedError when it cannot count. */
+    count(): Promise<SessionCount>;
+    /** @throws Error when no store is attached; SessionStoreUnsupportedError when it cannot list. */
+    users(): Promise<SessionUsers>;
+    /** @throws Error when no store is attached; SessionStoreUnsupportedError when it cannot list. */
+    liveHandles(): Promise<Set<string>>;
+    /** Every session in the store with its id (#1937). @throws Error when no store is attached; SessionStoreUnsupportedError when it cannot list by id. */
+    sessions(): Promise<StoredSession[]>;
+    /** Remove one session from the store (#1937). @throws Error when no store is attached, or SessionStoreUnsupportedError when it cannot destroy. */
+    destroy(sid: string): Promise<void>;
+}
+export default SessionStatsManager;