@jwilleke/ngdpbase-types 5.20.0 → 5.22.0

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/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,6 +476,13 @@ 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>;

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

@@ -35,6 +35,16 @@ declare class SqliteDatabaseProvider extends BaseDatabaseProvider<SqliteHandle>
     constructor(file: string, key: string, ledger: Migration[], ledgerTable?: string, options?: {
         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;
     /**
      * Run a further migration ledger on this connection, recorded in its own
      * table: an add-on that depends on the add-on owning this database brings
@@ -49,6 +59,8 @@ declare class SqliteDatabaseProvider extends BaseDatabaseProvider<SqliteHandle>
         encrypted: boolean;
     };
     integrityOk(): boolean;
+    /** SQLite's quick check; throws what the driver throws (a wrong key: "file is not a database"). */
+    private quickCheckOk;
     getDurability(): ProviderDurability;
     close(): void;
 }

package/lib/src/providers/SqliteDatabaseProvider.js

@@ -36,14 +36,17 @@ class SqliteDatabaseProvider extends BaseDatabaseProvider {
         super();
         this.file = file;
         refuseNetworkFilesystem(file);
+        // #1892: an existing file is first read through a read-only connection.
+        // A wrong or missing key, or a damaged file, fails there, and nothing is
+        // written: a read-write connection that fails to read still checkpoints
+        // the WAL into the file on close, or deletes a WAL it can't parse. Only
+        // the -shm index, which SQLite rebuilds from the WAL, may be rewritten.
+        if (existsSync(file))
+            SqliteDatabaseProvider.probe(file, key);
         this.db = new Database(file, { timeout: options.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS });
         this.encrypted = key !== '';
         try {
-            if (this.encrypted) {
-                this.db.pragma("cipher='sqlcipher'");
-                this.db.pragma(`key='${key.replace(/'/g, "''")}'`);
-            }
-            // The first read: a wrong key fails here, before anything is written.
+            SqliteDatabaseProvider.unlock(this.db, key);
             this.db.pragma('journal_mode = WAL');
             this.db.pragma('synchronous = FULL');
             this.migrations = runMigrations(this.db, ledger, ledgerTable);
@@ -53,6 +56,42 @@ class SqliteDatabaseProvider extends BaseDatabaseProvider {
             throw err;
         }
     }
+    static unlock(db, key) {
+        if (!key)
+            return;
+        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 });
+        try {
+            SqliteDatabaseProvider.unlock(db, key);
+            const rows = db.pragma('quick_check');
+            if (String(rows[0]?.quick_check ?? '').toLowerCase() !== 'ok') {
+                throw new Error(`The database ${file} failed its integrity check — nothing was migrated or written`);
+            }
+        }
+        finally {
+            db.close();
+        }
+    }
     /**
      * Run a further migration ledger on this connection, recorded in its own
      * table: an add-on that depends on the add-on owning this database brings
@@ -70,13 +109,17 @@ class SqliteDatabaseProvider extends BaseDatabaseProvider {
     }
     integrityOk() {
         try {
-            const rows = this.db.pragma('quick_check');
-            return String(rows[0]?.quick_check ?? '').toLowerCase() === 'ok';
+            return this.quickCheckOk();
         }
         catch {
             return false;
         }
     }
+    /** SQLite's quick check; throws what the driver throws (a wrong key: "file is not a database"). */
+    quickCheckOk() {
+        const rows = this.db.pragma('quick_check');
+        return String(rows[0]?.quick_check ?? '').toLowerCase() === 'ok';
+    }
     getDurability() {
         return { bufferedForMs: 0, bufferedRecords: 0, fsync: 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.