@jwilleke/ngdpbase-types 5.21.0 → 5.23.0

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

@@ -461,6 +461,14 @@ declare class UserManager extends BaseManager {
         limit?: number;
         activeOnly?: boolean;
     }, ctx: ActorContext): Promise<Omit<User, 'password'>[]>;
+    /**
+     * The account lifecycle reaches PersonManager's door under a system context
+     * (#1930): keeping an account's person in step with the account is core's
+     * own bookkeeping, not the caller's contact management, so it never depends
+     * on the caller holding `contact-manage`. The reason names the account and
+     * who changed it, so the record says why.
+     */
+    private personSyncContext;
     /**
      * Persist a Person record paired with a newly-created User. The install's
      * anchor org (when configured) is referenced via `memberOf`; without it
@@ -468,12 +476,39 @@ declare class UserManager extends BaseManager {
      * thrown — auth must still succeed if Person storage is degraded.
      */
     private syncPersonOnCreate;
+    /**
+     * At sign-up, offer the new account a person with no account who has the
+     * same email (#1930): PersonManager mails an "Is this you?" link, and joins
+     * them only when the account confirms. Skipped when email is off. Never
+     * fails the account write.
+     */
+    private offerContactLink;
     private syncPersonOnUpdate;
     private syncPersonOnDelete;
     createSession(username: string, additionalData?: Record<string, unknown>): Promise<string>;
     getSession(sessionId: string): Promise<UserSession | null>;
     deleteSession(sessionId: string): Promise<void>;
-    deleteUserSessions(username: string): Promise<void>;
+    /**
+     * End every signed-in session of `username` in the live session store
+     * (#1937): the account was deleted or turned off (`AuthManager.closeAccess`).
+     * Each goes through `endSession` (its keys dropped, `authentication-logout`
+     * recorded with the reason) and is removed from the store. Returns how many.
+     * The provider's own session list was cleared here before; nothing writes it,
+     * and the store express-session reads was never touched.
+     */
+    deleteUserSessions(username: string, reason: 'account-deleted' | 'account-disabled', from?: {
+        ipAddress?: string;
+    }): Promise<number>;
+    /**
+     * End every signed-in session in the store that no longer belongs to its
+     * account (#1937): the account is gone, turned off, another account of the
+     * same name, or its password changed since (`checkSessionAccount`, the
+     * per-request rule). Run once at startup, so sessions left from before the
+     * fix, or from a close the store missed, do not wait for their next request.
+     */
+    endStaleSessions(): Promise<number>;
+    /** End and remove each signed-in session `which` names a reason for; none without a session store. */
+    private endStoredSessions;
     backup(): Promise<BackupData>;
     restore(backupData: BackupData): Promise<void>;
 }

package/lib/src/providers/BaseAttachmentProvider.d.ts

@@ -3,6 +3,8 @@ import type { StoreFileEntry, StoreFileLocation } from '../types/Provider.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import { ProviderInfo } from './BasePageProvider.js';
 import BaseProvider from './BaseProvider.js';
+import type { AttachmentFilesBackupData, AttachmentFilesBackupOutcome } from './attachmentFilesBackup.js';
+import type { PartOutcome } from '../utils/siteRestore.js';
 /**
  * File information for attachment uploads
  */
@@ -187,6 +189,18 @@ declare abstract class BaseAttachmentProvider extends BaseProvider implements At
      * @returns {Promise<void>}
      */
     abstract restore(backupData: Record<string, unknown>): Promise<void>;
+    /**
+     * Write the attachment files themselves beside the backup document (#1876),
+     * streamed, bytes as stored. A provider without it can't be backed up whole,
+     * and AttachmentManager's backup says so.
+     */
+    backupFiles?(directory: string, stem: string): Promise<AttachmentFilesBackupOutcome>;
+    /** Stage the files and metadata from a backup for the next start, as part of a site restore (#1876). */
+    stageFilesRestore?(providerBackup: Record<string, unknown>, files: AttachmentFilesBackupData, directory: string, siteRestore: string): Promise<{
+        skippedVaults: string[];
+    }>;
+    /** What the start did with a staged restore of the files (#1876), once; null when there was none. */
+    takeRestoreAtStart?(): PartOutcome | null;
     /**
      * Shutdown the provider (cleanup resources)
      * @returns {Promise<void>}

package/lib/src/providers/BasicAttachmentProvider.d.ts

@@ -5,6 +5,8 @@ import type { AssetProvider, AssetRecord, AssetQuery, AssetPage, AssetInput, Ass
 import type { CreativeWork } from '../types/Schema.js';
 import type { ActorContext } from '../context/ActorContext.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
+import { type PartOutcome } from '../utils/siteRestore.js';
+import { type AttachmentFilesBackupData, type AttachmentFilesBackupOutcome } from './attachmentFilesBackup.js';
 /**
  * Schema.org Person metadata
  */
@@ -122,6 +124,8 @@ export declare function safeStoredExtension(originalName: string, mimeType?: str
  */
 declare class BasicAttachmentProvider extends BaseAttachmentProvider implements AssetProvider {
     private storageDirectory;
+    /** What the start did with a staged restore of the files (#1876). */
+    private restoreAtStart;
     /** Pre-#1386 attachments/{legacyprivateroot}/{user}/ — migrate-FROM and read fallback only. */
     private legacyPrivateDir;
     private pagesDirectory;
@@ -149,8 +153,15 @@ declare class BasicAttachmentProvider extends BaseAttachmentProvider implements
     /**
      * Initialize the provider
      * All configuration access via ConfigurationManager
+     *
+     * @param options.readOnly - Open for reading only (#1852): load the index and
+     *   change nothing on disk. No staged restore is applied, no folder is
+     *   created, and neither start-up migration (legacy private files, stale
+     *   paths) runs. For an operator report such as the files dry run.
      */
-    initialize(): Promise<void>;
+    initialize(options?: {
+        readOnly?: boolean;
+    }): Promise<void>;
     /**
      * Verify that the attachment storage directory is accessible.
      *
@@ -210,7 +221,7 @@ declare class BasicAttachmentProvider extends BaseAttachmentProvider implements
      * @param fileBuffer - File data
      * @param fileInfo - { originalName, mimeType, size }
      * @param metadata - Schema.org CreativeWork metadata
-     * @param user - User object { name, email }
+     * @param user - The uploader: `username` is recorded as author and editor (#1926)
      * @param options - Privacy-aware storage options
      * @returns Complete attachment metadata
      * @private
@@ -435,6 +446,19 @@ declare class BasicAttachmentProvider extends BaseAttachmentProvider implements
      * @returns Backup data
      */
     backup(): Promise<BackupData>;
+    /** Where the attachment files are, for their backup and staged restore (#1876). */
+    private filePlaces;
+    /** The files themselves, beside the backup document (#1876): the shared pool and every vault's, as stored. */
+    backupFiles(directory: string, stem: string): Promise<AttachmentFilesBackupOutcome>;
+    /**
+     * Stage the files and the shared metadata from a backup for the next start
+     * (#1876). The metadata is the document's; the live files and metadata are
+     * not touched.
+     */
+    stageFilesRestore(providerBackup: Record<string, unknown>, files: AttachmentFilesBackupData, directory: string, siteRestore: string): Promise<{
+        skippedVaults: string[];
+    }>;
+    takeRestoreAtStart(): PartOutcome | null;
     /**
      * Restore provider data from backup
      * @param backupData - Backup data

package/lib/src/providers/SqliteDatabaseProvider.d.ts

@@ -36,6 +36,13 @@ declare class SqliteDatabaseProvider extends BaseDatabaseProvider<SqliteHandle>
         busyTimeoutMs?: number;
     });
     private static unlock;
+    /**
+     * Read a database file once, read-only, under `key`, and close it (#1876):
+     * nothing is migrated or written. Used for the copy a restore kept as
+     * `*.pre-restore`, to read what the site had recorded just before the
+     * restore replaced it.
+     */
+    static readOnce<T>(file: string, key: string, read: (db: SqliteHandle) => T): T;
     /** Read an existing file read-only: the key opens it and it passes the quick check, or this throws. */
     private static probe;
     /**

package/lib/src/providers/SqliteDatabaseProvider.js

@@ -62,6 +62,22 @@ class SqliteDatabaseProvider extends BaseDatabaseProvider {
         db.pragma("cipher='sqlcipher'");
         db.pragma(`key='${key.replace(/'/g, "''")}'`);
     }
+    /**
+     * Read a database file once, read-only, under `key`, and close it (#1876):
+     * nothing is migrated or written. Used for the copy a restore kept as
+     * `*.pre-restore`, to read what the site had recorded just before the
+     * restore replaced it.
+     */
+    static readOnce(file, key, read) {
+        const db = new Database(file, { readonly: true, fileMustExist: true });
+        try {
+            SqliteDatabaseProvider.unlock(db, key);
+            return read(db);
+        }
+        finally {
+            db.close();
+        }
+    }
     /** Read an existing file read-only: the key opens it and it passes the quick check, or this throws. */
     static probe(file, key) {
         const db = new Database(file, { readonly: true, fileMustExist: true });

package/lib/src/providers/SqliteJobStateProvider.d.ts

@@ -39,3 +39,13 @@ declare class SqliteJobStateProvider implements JobStateProvider {
     releaseLock(jobId: string, slot: string, owner: string): Promise<void>;
 }
 export default SqliteJobStateProvider;
+/**
+ * Every job's runs started after `since`, from a database handle (#1876): the
+ * application database a restore kept as `*.pre-restore`, read just after it
+ * was replaced, so the restore's notice names the runs the restored job
+ * history no longer has. The same table `listRuns` reads.
+ */
+export declare function runsStartedAfter(db: Handle, since: string): Array<{
+    jobId: string;
+    run: JobRunRecord;
+}>;

package/lib/src/providers/attachmentFilesBackup.d.ts

@@ -0,0 +1,52 @@
+import { type PartOutcome } from '../utils/siteRestore.js';
+import { type PrivateStoreLayout } from '../utils/privateStorePath.js';
+/** Where the attachment files live on this site. */
+export interface AttachmentFilePlaces {
+    /** The shared pool folder. */
+    pool: string;
+    /** The shared pool's metadata file (inside the pool by default). */
+    metadataFile: string;
+    /** The pages folder, which holds the vaults. */
+    pagesDirectory: string | null;
+    layout: PrivateStoreLayout;
+}
+/** The files part of AttachmentManager's entry in the backup document. */
+export interface AttachmentFilesBackupData {
+    format: 1;
+    pool: {
+        archive: string;
+        files: number;
+        bytes: number;
+    };
+    vaults: {
+        archive: string;
+        files: number;
+        bytes: number;
+        stores: string[];
+    };
+    /** `backupKeyFingerprint()` of the key both archives are encrypted under; absent when they are not. */
+    keyFingerprint?: string;
+}
+export interface AttachmentFilesBackupOutcome {
+    data: AttachmentFilesBackupData;
+    /** Parts left out (a symbolic link, a vault folder whose name can't be a path segment), each named. */
+    warnings: string[];
+}
+/** Write the attachment files beside the backup document: the pool, then every vault's. Never base64, never whole in memory. */
+export declare function backupAttachmentFiles(places: AttachmentFilePlaces, directory: string, stem: string): Promise<AttachmentFilesBackupOutcome>;
+/**
+ * Stage the attachment files from a backup for the next start, and record
+ * the part in the site restore. All or nothing: on any failure every staged
+ * path is removed and nothing is recorded.
+ *
+ * @returns the vaults the backup holds that this site doesn't have (not staged).
+ */
+export declare function stageAttachmentFiles(places: AttachmentFilePlaces, directory: string, data: AttachmentFilesBackupData, metadataJson: string, siteRestore: string): Promise<{
+    skippedVaults: string[];
+}>;
+/**
+ * Put staged attachment files in place, at start, before the metadata is
+ * read: only the pool, its metadata file and vault attachment paths may be
+ * replaced, whatever the manifest says.
+ */
+export declare function applyAttachmentFilesAtStart(places: AttachmentFilePlaces, siteRestore: string): PartOutcome | null;

package/lib/src/providers/sqliteBackup.d.ts

@@ -126,3 +126,9 @@ export interface ApplyOutcome {
  * be replaced, so a tampered manifest cannot rename an arbitrary file.
  */
 export declare function applyStagedRestore(applicationFile: string, allowed: (live: string) => boolean): ApplyOutcome | null;
+/**
+ * Set a staged restore aside without applying any of it (#1876): every
+ * `*.db.staged` beside the application database and the manifest become
+ * `*.incomplete`. Used when the site restore it belongs to is not applied.
+ */
+export declare function setAsideStagedRestore(applicationFile: string, reason: string): ApplyOutcome;

package/lib/src/providers/sqliteBackup.js

@@ -307,12 +307,7 @@ export function applyStagedRestore(applicationFile, allowed) {
             move(f, `${f}.incomplete`);
         return { applied: [], refused: `staged database files with no restore manifest (an interrupted staging): ${leftovers.map((f) => path.basename(f)).join(', ')} — set aside as *.incomplete` };
     }
-    const setAside = (reason) => {
-        for (const f of stray())
-            move(f, `${f}.incomplete`);
-        move(manifestFile, `${manifestFile}.incomplete`);
-        return { applied: [], refused: reason };
-    };
+    const setAside = (reason) => setAsideStagedRestore(applicationFile, reason);
     let manifest;
     try {
         manifest = JSON.parse(readFileSync(manifestFile, 'utf8'));
@@ -351,6 +346,21 @@ export function applyStagedRestore(applicationFile, allowed) {
     unlinkSync(manifestFile);
     return { applied };
 }
+/**
+ * Set a staged restore aside without applying any of it (#1876): every
+ * `*.db.staged` beside the application database and the manifest become
+ * `*.incomplete`. Used when the site restore it belongs to is not applied.
+ */
+export function setAsideStagedRestore(applicationFile, reason) {
+    const manifestFile = manifestPath(applicationFile);
+    const dir = path.dirname(applicationFile);
+    const staged = existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith('.db.staged')).map((f) => path.join(dir, f)) : [];
+    for (const f of staged)
+        move(f, `${f}.incomplete`);
+    if (existsSync(manifestFile))
+        move(manifestFile, `${manifestFile}.incomplete`);
+    return { applied: [], refused: reason };
+}
 /** A rename; a copy and unlink when the two paths are on different devices. */
 function move(from, to) {
     try {

package/lib/src/security/permissions.generated.d.ts

@@ -22,6 +22,10 @@ export type CorePermission =
  | 'comment-create'
 /** Change any configuration setting, and download a backup (#1525). Admin only by default; asks for a fresh sign-in when listed in ngdpbase.auth.step-up */
  | 'config-manage'
+/** Create, edit, delete and link contacts: persons (with or without an account) and organizations, and a person's affiliations, through PersonManager and OrganizationManager (#1930). Reading them is contact-read. Admins by default; an add-on grants it to its own roles in its own policy */
+ | 'contact-manage'
+/** List, search and view contacts: persons (with or without an account) and organizations, and their affiliations, through PersonManager and OrganizationManager, and the /admin/contacts and /admin/organizations views (#1930). Admins and demo admins by default; an add-on grants it to its own roles in its own policy */
+ | 'contact-read'
 /** Browse and view the media library (not delegated to anonymous visitors) */
  | 'media-read'
 /** Create new pages */

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

@@ -6,6 +6,14 @@
  * while AttachmentManager / MediaManager remain thin wrappers.
  */
 import type { ActorContext } from '../context/ActorContext.js';
+/**
+ * What an attachment record says when it was stored with no uploader, in the
+ * pool's `author.name`, and what `uploadedBy` shows for a record with none.
+ * Only records written before #1926 carry it: a new upload names its
+ * uploader's username or is refused. Not a user; the files layer reads it as
+ * "no owner" (#1852).
+ */
+export declare const UNKNOWN_UPLOADER = "Unknown";
 /**
  * Capabilities that an AssetProvider may declare.
  * Used to advertise which optional operations the provider supports.
@@ -207,6 +215,8 @@ export interface AssetRecord {
     author?: string;
     /** ISO 8601 timestamp of the last metadata or file modification — schema.org/dateModified */
     dateModified?: string;
+    /** Username of whoever last changed it, when the provider records one — schema.org/editor */
+    editor?: string;
     /** Licensing and rights information */
     usageRights?: AssetUsageRights;
     /** Download counts and access statistics */

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

@@ -116,6 +116,11 @@ export interface WikiConfig {
      */
     'ngdpbase.auth.throttle.max-lock-minutes': number;
     'ngdpbase.mail.rate-limit.enabled': boolean;
+    /**
+     * Outbound email failures: one administrator notice per this many minutes,
+     * counting every failure inside it (#1916). Default: 60.
+     */
+    'ngdpbase.mail.failure-notice.window-minutes': number;
     /**
      * Anti-spam: max submissions per IP per `window-minutes` window before
      * the 429 trips (#670 Phase E). Default: 5.
@@ -305,6 +310,12 @@ export interface ApplicationOrganizationConfig {
     'ngdpbase.application.persons.provider.default': string;
     /** Active Person provider class (lowercased; falls back to .default) */
     'ngdpbase.application.persons.provider': string;
+    /** #1930: the most results `PersonManager.search` returns when the caller gives no limit */
+    'ngdpbase.application.persons.search.limit': number;
+    /** #1930: minutes the emailed "Is this you?" sign-up link stays usable */
+    'ngdpbase.application.persons.link-offer.ttl-minutes': number;
+    /** #1930: the most results `OrganizationManager.search` returns when the caller gives no limit */
+    'ngdpbase.application.organization.search.limit': number;
     /** Storage directory for OrganizationRole JSON files (one per (org, namedPosition) pair) */
     'ngdpbase.application.roles.storagedir': string;
     /** Default Role provider class (lowercased) */

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

@@ -71,6 +71,13 @@ export interface Organization {
     /** Allow extension fields (additionalProperty, etc.) */
     [key: string]: unknown;
 }
+/**
+ * What a caller gives `OrganizationManager.create` (#1930): the fields, with
+ * `@id` optional (it defaults to the `url`, else a new `urn:uuid:`).
+ */
+export type OrganizationInput = Partial<Organization> & {
+    name: string;
+};
 /**
  * Patch shape for update operations.
  * `@context`/`@type` are immutable; `@id` cannot be changed via update.

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

@@ -6,8 +6,9 @@
  * (where the uuid matches the v4 segment of `@id`).
  *
  * `@id` uses the urn:uuid:<v4> form because persons typically lack a
- * canonical web URL. `identifier` matches `User.username` so existing auth
- * records link cleanly to a Person.
+ * canonical web URL. `identifier` is the person's account (`User.username`)
+ * when they have one, and `person:<uuid>` when they do not (#1930) — a form
+ * no username may take (`ACCOUNTLESS_PERSON_PREFIX`, `src/utils/username.ts`).
  *
  * No embedded role-records — those live in the future person-contacts
  * addon (#602) and are folded in at JSON-LD export time.
@@ -15,6 +16,18 @@
  * @see https://schema.org/Person
  */
 import type { PostalAddress, ContactPoint } from './Organization.js';
+/**
+ * One organization a person is affiliated with (#1930): schema.org
+ * `affiliation`, with the person's role or title there when one is known.
+ * The organization is named by its `@id`; OrganizationManager lists an
+ * organization's people by reading these, so the link is stored once, here.
+ */
+export interface PersonAffiliation {
+    /** The organization's `@id`. */
+    organization: string;
+    /** The person's role or title there (schema.org `roleName`), when known. */
+    role?: string;
+}
 /**
  * Canonical Person record.
  *
@@ -26,7 +39,7 @@ export interface Person {
     '@type': 'Person';
     /** urn:uuid:<v4> */
     '@id': string;
-    /** Matches User.username so auth records link to this Person */
+    /** The account's username, or `person:<uuid>` for a person with no account (#1930). */
     identifier: string;
     /** Display name */
     name?: string;
@@ -46,6 +59,8 @@ export interface Person {
     image?: string;
     /** Other URLs that identify this person (LinkedIn, GitHub, etc.) */
     sameAs?: string[];
+    /** Organizations this person is affiliated with, each with an optional role (#1930). */
+    affiliation?: PersonAffiliation[];
     /** Allow extension fields (additionalProperty, etc.) */
     [key: string]: unknown;
 }
@@ -54,3 +69,12 @@ export interface Person {
  * `@context`/`@type` are immutable; `@id` and `identifier` cannot be changed via update.
  */
 export type PersonUpdate = Partial<Omit<Person, '@context' | '@type' | '@id' | 'identifier'>>;
+/**
+ * What a caller gives `PersonManager.create` (#1930): the person's fields.
+ * `identifier` is left out for a person with no account (one is generated);
+ * UserManager passes the account's username when it creates the person for a
+ * new account.
+ */
+export type PersonInput = PersonUpdate & {
+    identifier?: string;
+};

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

@@ -18,6 +18,12 @@ export interface PersonProvider extends BaseProvider {
     getByIdentifier(identifier: string): Promise<Person | null>;
     /** Persist a new Person. Returns the stored record. */
     create(person: Person): Promise<Person>;
+    /**
+     * Write the whole record in place of the one with the same `@id` (#1930).
+     * The only write that may change `identifier`: PersonManager uses it to join
+     * a person to an account.
+     */
+    replace(person: Person): Promise<Person>;
     /** Apply a partial update by `@id`. Returns the updated record, or null if not found. */
     update(id: string, patch: PersonUpdate): Promise<Person | null>;
     /** Delete by `@id`. Returns true if a record was removed. */

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

@@ -8,6 +8,7 @@ import { WikiConfig } from './Config.js';
 import type { Logger } from 'winston';
 import type { Application, Request, RequestHandler, Router, RouterOptions } from 'express';
 import type express from 'express';
+import type { MaintenanceState } from '../utils/maintenanceState.js';
 /**
  * All known manager names as a union type
  * Use with getManager() for type-safe access when combined with explicit type parameter
@@ -95,28 +96,15 @@ export interface WikiEngine {
      */
     shutdown(): Promise<void>;
     /**
-     * Record a configuration value that cannot be used (#1152).
-     *
-     * Recorded rather than thrown so `initialize()` finishes and the admin
-     * screens exist — the instance then serves maintenance mode with a route to
-     * the repair, instead of exiting and leaving the filesystem as the only way
-     * back. Only for values an administrator can fix through the admin UI; a
-     * failure of the machinery needed to serve that UI is fatal and still throws.
-     * Also a site-critical add-on that did not load (#1883, operator
-     * 2026-10-18): its fix may lie outside the UI (a key in the instance .env),
-     * and the admin notification says so.
-     */
-    blockConfiguration(reason: string, options?: {
-        publicMessage?: string;
-    }): void;
-    /** Configuration values that could not be used, in the order found (#1152). */
-    getBlockingConditions(): readonly string[];
-    /**
-     * What visitors see in place of the reasons, when a reason was recorded with
-     * a `publicMessage` (#1883: a site-critical add-on that did not load); null
-     * when every reason may be shown.
+     * Whether the site is in maintenance mode, and why (#1906): the one door.
+     * A manager that needs the site closed calls `maintenance.enter(reason,
+     * { message?, estimatedDuration? })`, and `maintenance.leave(reason)` when
+     * the reason clears. Reasons are for administrators only; visitors get
+     * `maintenance.visitorView(configManager)`. Replaces `blockConfiguration`
+     * (#1152), still recorded rather than thrown so `initialize()` finishes and
+     * `/admin`, `/login` and `/logout` stay reachable.
      */
-    getPublicBlockingMessage(): string | null;
+    readonly maintenance: MaintenanceState;
     /**
      * Get all registered manager names
      * @returns Array of manager names

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

@@ -30,6 +30,8 @@ declare module 'express-session' {
         privateStoreHandle?: string;
         /** The account's password-change generation when this session signed in (#1482). */
         sessionGeneration?: number;
+        /** The `createdAt` of the account this session signed in to (#1937): a later account of the same name is not it. */
+        accountCreatedAt?: string;
         /** How this session signed in: provider, factors with their times, amr / aal / acr (#1523). */
         signIn?: SignInRecord;
         /** A pending WebAuthn challenge (#448): single-use, tied to its purpose, short-lived. */

package/lib/src/utils/addonPageSync.d.ts

@@ -31,6 +31,30 @@ export declare function evaluateSeededAddonPage(args: {
     liveContent: string;
     storedHash: string | undefined;
 }): SeededAddonPageStatus;
+/**
+ * How a shipped item's sync status reads on an admin screen: the status words
+ * and the edit protection of Admin → Required Pages, which every screen that
+ * syncs shipped content shares (`views/_sync-status.ejs`, `views/_sync-button.ejs`;
+ * shipped forms, #1918).
+ *
+ *  - `status` — `modified` when the live copy differs from what ships,
+ *    `current` when it is the same.
+ *  - `userModified` — edited on this site: Sync does not replace it; Force Sync
+ *    does, after a confirm.
+ */
+export interface SyncRowState {
+    status: 'current' | 'modified';
+    userModified: boolean;
+}
+/**
+ * The one mapping from `evaluateSeededAddonPage`'s answer to the admin screen's
+ * words (#1918). `userModifiedFlag` is a page's explicit `user-modified`
+ * frontmatter, which marks it edited even when the hash cannot tell.
+ *
+ * @param seedStatus - `evaluateSeededAddonPage`'s answer for the live copy
+ * @param userModifiedFlag - The live copy is explicitly marked edited
+ */
+export declare function syncRowState(seedStatus: SeededAddonPageStatus, userModifiedFlag?: boolean): SyncRowState;
 /**
  * Default edit access for a page ngdpbase ships (#971, #1411): a `general`
  * page is instance-owned and gets no stamp; any other category — system,

package/lib/src/utils/administrators.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Who an administrator notification goes to.
+ *
+ * __An administrator is whoever holds `admin-system`__, asked per user through
+ * the policy (#1431 7b) — never a role name. Used by every report that must
+ * reach administrators and nobody else: a damaged page (#1431 step 7) and
+ * failing outbound email (#1916).
+ *
+ * An empty answer means "nobody to tell", and the caller must then log only:
+ * an empty `targetUsers` list means ALL users in NotificationManager, which
+ * would announce an operator problem to every reader.
+ *
+ * Null when the managers needed to answer are not registered (tests, a
+ * half-booted engine) — the caller treats that like "nobody to tell".
+ */
+type EngineLike = {
+    getManager: (name: string) => unknown;
+} | null | undefined;
+/** Usernames of every user who holds `admin-system`; null when it cannot be asked. */
+export declare function administratorUsernames(engine: EngineLike): Promise<string[] | null>;
+export {};

package/lib/src/utils/auditEventNames.generated.d.ts

@@ -36,6 +36,8 @@ export declare const AUDIT_EVENT: {
     readonly BACKUP_CREATE: "backup-create";
     /** A restore of a backup's databases started from Admin → Backup: which backup and who asked; recorded before the fresh backup and the staging, which cannot proceed without it (#1723) */
     readonly BACKUP_RESTORE: "backup-restore";
+    /** A staged restore (site or databases-only) put in place at start: which backup, when it was taken, who started the restore and which parts were applied; written into the restored audit log, so the log itself says a restore happened (#1876) */
+    readonly BACKUP_RESTORE_APPLIED: "backup-restore-applied";
     /** A staged database restore cancelled before the restart applied it: which backup, who staged it and who cancelled; recorded first, which cannot proceed without it (#1723) */
     readonly BACKUP_RESTORE_CANCEL: "backup-restore-cancel";
     /** A staged database restore replaced by another before the restart applied it: which backup replaced which, and who asked; recorded first, which cannot proceed without it (#1723) */
@@ -48,6 +50,8 @@ export declare const AUDIT_EVENT: {
     readonly CONFIG_CHANGE: "config-change";
     /** Every custom configuration value discarded; recorded before the reset, which cannot proceed without it */
     readonly CONFIG_RESET: "config-reset";
+    /** Contact created, changed, deleted or linked to an account; metadata names the kind (person or organization), the operation and the fields changed, never their values */
+    readonly CONTACT_MANAGE: "contact-manage";
     /** A page's footnote list changed — action add, import, transfer, update or delete; page content written on someone's behalf (#1233) */
     readonly FOOTNOTE_EDIT: "footnote-edit";
     /** A background job finished successfully */

package/lib/src/utils/auditEventNames.generated.js

@@ -43,6 +43,8 @@ export const AUDIT_EVENT = {
     BACKUP_CREATE: 'backup-create',
     /** A restore of a backup's databases started from Admin → Backup: which backup and who asked; recorded before the fresh backup and the staging, which cannot proceed without it (#1723) */
     BACKUP_RESTORE: 'backup-restore',
+    /** A staged restore (site or databases-only) put in place at start: which backup, when it was taken, who started the restore and which parts were applied; written into the restored audit log, so the log itself says a restore happened (#1876) */
+    BACKUP_RESTORE_APPLIED: 'backup-restore-applied',
     /** A staged database restore cancelled before the restart applied it: which backup, who staged it and who cancelled; recorded first, which cannot proceed without it (#1723) */
     BACKUP_RESTORE_CANCEL: 'backup-restore-cancel',
     /** A staged database restore replaced by another before the restart applied it: which backup replaced which, and who asked; recorded first, which cannot proceed without it (#1723) */
@@ -55,6 +57,8 @@ export const AUDIT_EVENT = {
     CONFIG_CHANGE: 'config-change',
     /** Every custom configuration value discarded; recorded before the reset, which cannot proceed without it */
     CONFIG_RESET: 'config-reset',
+    /** Contact created, changed, deleted or linked to an account; metadata names the kind (person or organization), the operation and the fields changed, never their values */
+    CONTACT_MANAGE: 'contact-manage',
     /** A page's footnote list changed — action add, import, transfer, update or delete; page content written on someone's behalf (#1233) */
     FOOTNOTE_EDIT: 'footnote-edit',
     /** A background job finished successfully */

package/lib/src/utils/backupCrypto.d.ts

@@ -0,0 +1,28 @@
+import { Transform } from 'node:stream';
+/** The first bytes of every encrypted backup file. */
+export declare const BACKUP_FILE_MAGIC: Buffer<ArrayBuffer>;
+/** What an encrypted backup file's name ends with. */
+export declare const ENCRYPTED_SUFFIX = ".enc";
+/** A backup file made under a different backup key than the one set now. */
+export declare class BackupKeyMismatchError extends Error {
+    readonly fileFingerprint: string;
+    readonly keyFingerprint: string;
+    constructor(fileFingerprint: string, keyFingerprint: string);
+}
+/** Whether these bytes (a file's first) are an encrypted backup file. */
+export declare function isEncryptedBackup(head: Buffer): boolean;
+/** Whether the file on disk is an encrypted backup file, read from its first bytes only. */
+export declare function fileIsEncrypted(file: string): Promise<boolean>;
+/** A stream that encrypts what is written to it under `backupKey`. */
+export declare function encryptStream(backupKey: string): Transform;
+/**
+ * A stream that decrypts an encrypted backup file written to it. Fails —
+ * naming why — on a file that is not one, a different backup key
+ * ({@link BackupKeyMismatchError}), any record that does not verify, and a
+ * file cut short or with bytes after its last record.
+ */
+export declare function decryptStream(backupKey: string): Transform;
+/** Encrypt a whole buffer (the backup document, already in memory). */
+export declare function encryptBuffer(data: Buffer, backupKey: string): Promise<Buffer>;
+/** Decrypt a whole buffer. */
+export declare function decryptBuffer(data: Buffer, backupKey: string): Promise<Buffer>;