@jwilleke/ngdpbase-types 5.21.0 → 5.23.0

package/lib/packages/ngdpbase-types/index.d.ts

@@ -30,3 +30,8 @@ export type { Migration } from '../../src/providers/sqliteMigrations.js';
 export type { AddonDatabaseDeclaration, DatabaseEncrypt } from '../../src/utils/addonDatabaseRules.js';
 export type { default as ExportManager } from '../../src/managers/ExportManager.js';
 export type { default as PolicyDecisionPoint } from '../../src/security/PolicyDecisionPoint.js';
+export type { default as PersonManager, LinkOfferOutcome } from '../../src/managers/PersonManager.js';
+export type { default as OrganizationManager } from '../../src/managers/OrganizationManager.js';
+export type { Person, PersonAffiliation, PersonInput, PersonUpdate } from '../../src/types/Person.js';
+export type { Organization, OrganizationInput, OrganizationUpdate } from '../../src/types/Organization.js';
+export type { ContactRefusedError } from '../../src/utils/contactAccess.js';

package/lib/src/mail/MailProvider.d.ts

@@ -30,6 +30,8 @@ export interface MailProvider {
 /**
  * Development transport — writes the email to the server log instead of
  * sending it. Useful for local installs where no SMTP server is available.
+ * Like every log line, it names the recipient's domain only, and any address
+ * in the body is cut to its domain (#1916).
  */
 export declare class ConsoleMailProvider implements MailProvider {
     send(message: MailMessage): Promise<void>;

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

@@ -364,9 +364,9 @@ declare class AddonsManager extends BaseManager {
      * not load, whatever the reason. Admins get a notification at the most
      * severe level naming it and the reason, which says how to fix it where the
      * reason does. A site-critical add-on (`ngdpbase.addons.<slug>.site-critical`)
-     * also holds the whole site in maintenance mode through core's survivable
-     * path (#1152): visitors see only the configured public message, with no
-     * details, and administrators can still sign in and reach /admin. Once per
+     * also holds the whole site in maintenance mode through the one door
+     * (`engine.maintenance`, #1906): visitors see only the site's maintenance
+     * message, with no details, and administrators can still sign in and reach /admin. Once per
      * add-on per start. Nothing is opened in its place.
      */
     private recordLoadFailure;

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

@@ -1,4 +1,6 @@
-import BaseManager, { BackupData, type ManagerStats } from './BaseManager.js';
+import BaseManager, { BackupData, type ManagerBackupOptions, type ManagerRestoreOptions, type ManagerStats } from './BaseManager.js';
+import type { AttachmentFilesBackupData, AttachmentFilesBackupOutcome } from '../providers/attachmentFilesBackup.js';
+import type { PartOutcome } from '../utils/siteRestore.js';
 import { type ActorContext } from '../context/ActorContext.js';
 /**
  * Marks an error as "the audit record could not be written", not "the action
@@ -7,13 +9,16 @@ import { type ActorContext } from '../context/ActorContext.js';
 export declare const AUDIT_WRITE_FAILED = "EAUDITWRITE";
 import type { WikiEngine } from '../types/WikiEngine.js';
 import type { CatalogSource, CatalogQuery, CatalogPage, CreativeWork, SchemaType, RebuildOpts } from '../types/Schema.js';
-import type { AssetQuery, AssetRecord } from '../types/Asset.js';
+import type { User } from '../providers/BaseAttachmentProvider.js';
+import { type AssetQuery, type AssetRecord } from '../types/Asset.js';
 import type { StoreFileEntry, StoreFileLocation } from '../types/Provider.js';
 /**
  * Base attachment provider interface
  */
 interface BaseAttachmentProvider {
-    initialize(): Promise<void>;
+    initialize(options?: {
+        readOnly?: boolean;
+    }): Promise<void>;
     storeAttachment(fileBuffer: Buffer, fileInfo: FileInfo, metadata: AttachmentMetadataInput, user: User | null): Promise<AttachmentMetadata>;
     getAttachment(attachmentId: string): Promise<{
         buffer: Buffer;
@@ -30,6 +35,12 @@ interface BaseAttachmentProvider {
     getThumbnail?(id: string, size: string): Promise<Buffer | null>;
     backup(): Promise<unknown>;
     restore(backupData: unknown): Promise<void>;
+    /** #1876: the files themselves beside the backup document, and their staged restore. */
+    backupFiles?(directory: string, stem: string): Promise<AttachmentFilesBackupOutcome>;
+    stageFilesRestore?(providerBackup: Record<string, unknown>, files: AttachmentFilesBackupData, directory: string, siteRestore: string): Promise<{
+        skippedVaults: string[];
+    }>;
+    takeRestoreAtStart?(): PartOutcome | null;
     shutdown(): Promise<void>;
     getProviderInfo(): {
         features: string[];
@@ -95,13 +106,6 @@ export interface UploadOptions {
     /** Store id when private with no private page; default from ConfigurationManager defaultstoreid */
     store?: string;
 }
-/**
- * User object interface
- */
-export interface User {
-    name: string;
-    email?: string;
-}
 /**
  * Mention object (WebPage reference)
  */
@@ -148,6 +152,8 @@ export interface AttachmentMetadataInput {
 export interface AttachmentBackupData extends BackupData {
     providerClass: string | null;
     providerBackup?: unknown;
+    /** The files themselves, as archives beside the document (#1876). */
+    files?: AttachmentFilesBackupData;
     data?: null;
 }
 declare class AttachmentManager extends BaseManager implements CatalogSource {
@@ -302,6 +308,16 @@ declare class AttachmentManager extends BaseManager implements CatalogSource {
      * @returns {Promise<AttachmentMetadata>} Attachment metadata
      */
     uploadAttachment(fileBuffer: Buffer, fileInfo: FileInfo, ctx: ActorContext, options?: UploadOptions): Promise<AttachmentMetadata>;
+    /**
+     * The username an upload is recorded under (#1926): the person the context
+     * names. Asked after policy has allowed the upload and before anything is
+     * written; it decides nothing about authority, only whether there is
+     * someone to record. No one uploads anonymously (operator, 2026-10-20, on
+     * #1852), so the anonymous subject — a share visitor included — and a job
+     * with no person behind it are refused. A refusal reads 'Permission denied'
+     * so the route answers it as one (401 for an anonymous caller).
+     */
+    private static uploaderOf;
     /** A file is added to a private page only by someone who may edit it: the page's own decision (#1398). */
     private assertMayEditPage;
     /**
@@ -446,6 +462,40 @@ declare class AttachmentManager extends BaseManager implements CatalogSource {
      * is findable exactly as a public one is.
      */
     searchPrivateStoreAttachments(query: AssetQuery, ctx: ActorContext): Promise<AssetRecord[]>;
+    /**
+     * {@link searchPrivateStoreAttachments}, kept apart by vault (#1852): the
+     * files layer needs to say which vault each file is in. The same stores,
+     * the same container rule, the same matching.
+     */
+    readableVaultAssetRecords(ctx: ActorContext, query?: AssetQuery): Promise<Array<{
+        owner: string;
+        vault: string;
+        files: AssetRecord[];
+    }>>;
+    /**
+     * The shared pool as asset records (#1852), every one of them: the
+     * provider's own mapping, so the files layer and asset search show a
+     * public file the same way. Whether the requester may read the pool is the
+     * caller's question (`asset-read`).
+     */
+    sharedPoolAssetRecords(): Promise<AssetRecord[]>;
+    /**
+     * Every vault's files, for an operator inventory with no viewer (#1852,
+     * the files migration dry run), the way {@link findVaultPagesUsingPoolFiles}
+     * walks them: an unsealed vault's index entries; for any other vault
+     * (sealed, or not yet opened) only the files on disk and their size, since
+     * its index can't be read without its owner's key. Reads only. The entries
+     * are for the files layer to count; they are never shown.
+     */
+    vaultFileInventory(): Promise<Array<{
+        owner: string;
+        vault: string;
+        /** Whether its index could be read: an unsealed vault. */
+        readable: boolean;
+        entries: StoreFileEntry[] | null;
+        filesOnDisk: number;
+        bytesOnDisk: number;
+    }>>;
     /**
      * Move every unencrypted private file record out of the global
      * `attachment-metadata.json` and into its store's own index, at start-up.
@@ -1000,7 +1050,7 @@ declare class AttachmentManager extends BaseManager implements CatalogSource {
      *
      * @returns {Promise<AttachmentBackupData>}
      */
-    backup(): Promise<AttachmentBackupData>;
+    backup(options?: ManagerBackupOptions): Promise<AttachmentBackupData>;
     /**
      * Restore manager data from backup
      * Delegates to provider's restore method
@@ -1008,7 +1058,9 @@ declare class AttachmentManager extends BaseManager implements CatalogSource {
      * @param {AttachmentBackupData} backupData - Backup data from backup() method
      * @returns {Promise<void>}
      */
-    restore(backupData: AttachmentBackupData): Promise<void>;
+    restore(backupData: AttachmentBackupData, options?: ManagerRestoreOptions): Promise<void>;
+    /** Its restore is staged for the next start with the rest of a site restore (#1876). */
+    restoreIsStaged(): boolean;
     /**
      * Shutdown the manager
      * @returns {Promise<void>}

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

@@ -30,7 +30,7 @@
  * @see {@link https://github.com/jwilleke/ngdpbase/issues/396}
  */
 import BaseManager from './BaseManager.js';
-import type { BackupData } from './BaseManager.js';
+import type { BackupData, ManagerBackupOptions, ManagerRestoreOptions } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import type { PermissionSubject } from './UserManager.js';
 import type { JobContext } from '../context/JobContext.js';
@@ -396,6 +396,8 @@ declare class AuthManager extends BaseManager {
     private factorCache;
     /** The credentials store (#1524); null when it could not be opened. */
     private credentials;
+    /** `ngdpbase.auth.credentials.file`, resolved at start: what a backup copies (#1876). */
+    private credentialsFile;
     constructor(engine: WikiEngine);
     initialize(config?: Record<string, unknown>): Promise<void>;
     /**
@@ -618,7 +620,9 @@ declare class AuthManager extends BaseManager {
      * Disable and delete both come through here, from UserManager, so nothing
      * an account holds is left reachable by one path and not the other.
      *
-     * - Both: every session of the account ends.
+     * - Both: every session of the account ends, destroyed in the live session
+     *   store (#1937); a session the store could not reach is still refused on
+     *   its next request (`checkSessionAccount`).
      * - Disable: its agent tokens, app grants and shares are suspended by the
      *   live owner-is-active checks that refuse them, and its credentials stay,
      *   so turning the account back on restores them.
@@ -1037,7 +1041,8 @@ declare class AuthManager extends BaseManager {
     /**
      * Stamp the session with the account's password-change generation (#1482):
      * at every sign-in, and on the session that changed the password, so that
-     * one stays signed in while every other session of the account ends.
+     * one stays signed in while every other session of the account ends. Also
+     * binds the session to the account itself (`accountCreatedAt`, #1937).
      */
     stampSessionGeneration(req: Request, username: string): Promise<void>;
     /**
@@ -1126,7 +1131,7 @@ declare class AuthManager extends BaseManager {
      * The link only opens the approval page; the button there approves, so a
      * mail scanner opening links approves nothing. Limited to one per minute.
      */
-    sendEmailApproval(handle: string, binding: string): Promise<'sent' | 'too-soon' | 'unavailable'>;
+    sendEmailApproval(handle: string, binding: string): Promise<'sent' | 'too-soon' | 'unavailable' | 'failed'>;
     /** What the approval page shows about the waiting sign-in; null for an unknown or used link. */
     approvalDetails(token: string): {
         username: string;
@@ -1260,7 +1265,25 @@ declare class AuthManager extends BaseManager {
     isEnabled(providerId: string): boolean;
     /** Returns all registered providers (for admin UI). */
     getProviders(): AuthProvider[];
-    backup(): Promise<BackupData>;
-    restore(_backupData: BackupData): Promise<void>;
+    /**
+     * The provider list, and the credentials store (#1876): passkeys, TOTP,
+     * verified email and phone, devices, linked identities and proxy grants,
+     * as its own file beside the document, __always encrypted under
+     * `NGDPBASE_BACKUP_KEY`__ (`<stem>.credentials.tar.enc`). Without the key the
+     * store is left out and the backup is reported incomplete; it is never in a
+     * backup unencrypted. The rows stay signed with `NGDPBASE_CREDENTIALS_KEY`,
+     * which is not in the backup: a site restored under another credentials key
+     * holds them in quarantine (#1633).
+     */
+    backup(options?: ManagerBackupOptions): Promise<BackupData>;
+    /**
+     * Stage the credentials store from a backup for the next start, with the
+     * rest of a site restore (#1876). A backup that left it out (no backup key
+     * when it was taken) stages nothing: the store on the site stays, and the
+     * restore's notification names it as not restored.
+     */
+    restore(backupData: BackupData, options?: ManagerRestoreOptions): Promise<void>;
+    /** Staged for the next start with the rest of a site restore (#1876). */
+    restoreIsStaged(): boolean;
 }
 export default AuthManager;

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

@@ -1,9 +1,21 @@
-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 JobContext } from '../context/JobContext.js';
 import { type ScheduleInput } from '../utils/schedule.js';
 import { type CatchUp, type Overlap } from '../utils/jobSlots.js';
 import { type JobRunRecord, type JobStateProvider } from '../providers/jobState.js';
+/** Who holds a slot lock: this host, this process, this start. */
+/**
+ * One run between a backup and the restore of it (#1876): what admins are
+ * told was done on the site and is no longer in the restored job state.
+ */
+export interface JobRunSince {
+    jobId: string;
+    startedAt: string;
+    completedAt?: string;
+    status: JobRunRecord['status'];
+    error?: string;
+}
 /**
  * Callback supplied to job run functions so they can push live progress
  * messages that the client can display while polling.
@@ -212,6 +224,19 @@ declare class BackgroundJobManager extends BaseManager {
     private controllers;
     /** For each running scheduled run: write it as interrupted and let go of its slot. */
     private handoffs;
+    /** `ngdpbase.jobs.state.dir`, when job state is files: what a backup copies (#1876). */
+    private stateDir;
+    /**
+     * The job state was put back from a backup at this start (#1876): every
+     * job then starts from now — no slot since the backup is caught up, and a
+     * run unfinished in the backup is closed, never resumed or retried. Jobs
+     * are never re-run because of a restore.
+     */
+    private restoredAtStart;
+    /** Jobs whose restored state has been settled, since this start. */
+    private settledAfterRestore;
+    /** The runs found in the live file state before a restore replaced it (#1876). */
+    private runsReplacedAtStart;
     /**
      * @param options - for tests: a state provider in place of the configured
      *   one, and the clock.
@@ -390,6 +415,45 @@ declare class BackgroundJobManager extends BaseManager {
     /** Whether the person who started a run still holds the job's permission — by policy, as at the time it is asked (P2). */
     private stillHolds;
     /** A run a restart cut off and that is not run again: recorded as failed, audited, and told to the admins. Never silent. */
+    /**
+     * A scheduled job's first look after its state was restored (#1876): a run
+     * the backup caught unfinished is closed as failed, never resumed or
+     * retried, and the next slot is the next one from now, so no slot between
+     * the backup and the restore is caught up. The restore's notification
+     * lists the runs that had happened since the backup.
+     */
+    private settleAfterRestore;
+    /**
+     * Job state in a backup (#1876). Files (`ngdpbase.jobs.state.dir`): the
+     * state, run history and checkpoints as `<stem>.jobs.tar` beside the
+     * document, without the slot locks, which belong to the server that holds
+     * them. In the database: nothing here — it is in the database backup.
+     */
+    backup(options?: ManagerBackupOptions): Promise<BackupData>;
+    /** File job state is staged for the next start with the rest of a site restore (#1876). Database job state comes back with the database. */
+    restore(backupData: BackupData, options?: ManagerRestoreOptions): Promise<void>;
+    restoreIsStaged(): boolean;
+    /**
+     * Put staged file job state in place, at start, before it is opened
+     * (#1876). The runs in the live state since the backup was taken are read
+     * first, before it is replaced, for the restore's notification.
+     */
+    private applyRestoreAtStart;
+    /**
+     * The job runs the live application database held, since the backup, when
+     * this start's restore replaced it (#1876): read from the copy DatabaseManager
+     * kept, which is the database as it was at the moment of the swap — so runs
+     * between staging and the restart are named too.
+     */
+    private readReplacedDatabaseRuns;
+    /** The runs in the file job state at `stateDir` started after `since`, read from disk. */
+    private readLiveRunsSince;
+    /** The runs of every registered job started after `since`, from the live state (#1876): read before a restore replaces it. */
+    runsSince(since: string): Promise<JobRunSince[]>;
+    /** The runs the live file state held before a restore replaced it at this start (#1876). */
+    getRunsReplacedAtStart(): JobRunSince[];
+    /** A job's display name, or its id when no job of that id is registered. */
+    displayNameOf(jobId: string): string;
     private reportCutOff;
     /**
      * Get the current state of a run by runId.

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

@@ -78,6 +78,13 @@ export interface ManagerRestoreOptions {
     replaceStaged?: boolean;
     /** The backup of the live data BackupManager took just before this restore (#1723, D6), by filename. */
     safetyBackup?: string;
+    /**
+     * The site restore manifest this restore is staged under (#1876). A
+     * manager whose restore is staged (`restoreIsStaged()`) stages its files
+     * beside its live ones and records its part there; the next start applies
+     * every part or none (`src/utils/siteRestore.ts`).
+     */
+    siteRestore?: string;
 }
 /**
  * Base class for all managers
@@ -341,6 +348,13 @@ declare abstract class BaseManager {
      * }
      */
     restore(backupData: BackupData, _options?: ManagerRestoreOptions): Promise<void>;
+    /**
+     * Whether this manager's `restore()` stages for the next start instead of
+     * writing into the running site (#1723, #1876). BackupManager stages every
+     * such manager in a site restore together, all or nothing, after a backup
+     * of the live data. The default is false: the restore writes live.
+     */
+    restoreIsStaged(): boolean;
     /**
      * Return a plain-text string suitable for use as MarqueePlugin banner text.
      *

package/lib/src/managers/BaseManager.js

@@ -299,6 +299,15 @@ class BaseManager {
             throw new Error(`${this.constructor.name}: No backup data provided for restore`);
         }
     }
+    /**
+     * Whether this manager's `restore()` stages for the next start instead of
+     * writing into the running site (#1723, #1876). BackupManager stages every
+     * such manager in a site restore together, all or nothing, after a backup
+     * of the live data. The default is false: the restore writes live.
+     */
+    restoreIsStaged() {
+        return false;
+    }
     /**
      * Return a plain-text string suitable for use as MarqueePlugin banner text.
      *

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

@@ -1,4 +1,4 @@
-import BaseManager from './BaseManager.js';
+import BaseManager, { type BackupData, type ManagerBackupOptions, type ManagerRestoreOptions } from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
 import type { PageComment } from '../types/Comment.js';
 import { type ActorContext } from '../context/ActorContext.js';
@@ -10,6 +10,15 @@ export default class CommentManager extends BaseManager {
     private readonly outsideCheck;
     constructor(engine: WikiEngine);
     initialize(): Promise<void>;
+    /**
+     * The public folder is in the backup (#1876), as `<stem>.comments.tar` beside
+     * the document: the public pages' comments. A vault page's are in its vault, which
+     * PageManager backs up with the vault, sealed as stored.
+     */
+    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/DatabaseManager.d.ts

@@ -1,27 +1,16 @@
 import BaseManager from './BaseManager.js';
 import type { WikiEngine } from '../types/WikiEngine.js';
+import { type SqliteHandle } from '../providers/SqliteDatabaseProvider.js';
 import type { Migration } from '../providers/sqliteMigrations.js';
 import { type ActorContext } from '../context/ActorContext.js';
 import type { BackupData, ManagerBackupOptions, ManagerRestoreOptions } from './BaseManager.js';
 import { type AddonDatabaseDeclaration } from '../utils/addonDatabaseRules.js';
 import { type StagedRestoreManifest } from '../providers/sqliteBackup.js';
-/** The environment variable holding the SQLCipher key. Never a config key: config is readable from the admin screens. */
-export declare 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 declare const BACKUP_KEY_ENV = "NGDPBASE_BACKUP_KEY";
+import { DATABASE_KEY_ENV } from '../utils/databaseKey.js';
+export { DATABASE_KEY_ENV };
+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 declare const DEFAULT_BACKUP_WORKER_TIMEOUT_MS = 3600000;
-/**
- * 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 declare function backupKeyFingerprint(key: string): string;
 /** One database in a backup, as DatabaseManager's entry in the backup document lists it. */
 export interface DatabaseBackupEntry {
     /** `application`, or `addon-<owner>`. */
@@ -91,6 +80,10 @@ declare class DatabaseManager extends BaseManager {
     private readonly addonDatabases;
     /** What the start did with a staged restore (#1723), reported once the notifications exist. */
     private restoreAtStart;
+    /** The databases a staged restore put back at this start (#1876): kept after the report, for the managers whose data is in them. */
+    private restoredNow;
+    /** When the restored backup was taken, and where the replaced application database is kept, when a restore was applied at this start (#1876). */
+    private replaced;
     /** Why this manager is degraded, one entry per cause, so one cause clearing leaves the others. */
     private readonly faults;
     /** Why the configured application database could not be opened safely (#1892); null otherwise. */
@@ -108,8 +101,8 @@ declare class DatabaseManager extends BaseManager {
     getUnavailableReason(): string | null;
     /**
      * #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.
      */
@@ -181,6 +174,20 @@ declare class DatabaseManager extends BaseManager {
      * staged, and admins are told.
      */
     restore(backupData: BackupData, options?: ManagerRestoreOptions): Promise<void>;
+    /** Whether a staged restore put the databases back at this start (#1876): the job state in them is then the backup's. */
+    restoredAtStart(): boolean;
+    /**
+     * 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<T>(read: (db: SqliteHandle, backupTakenAt: string) => T): T | null;
+    /** The databases a staged restore put back at this start, by name (#1876). */
+    getRestoredAtStart(): string[];
+    /** Its restore is staged for the next start (#1723), and joins a site restore (#1876). */
+    restoreIsStaged(): boolean;
     /** The restore staged and waiting for the next start, or null. */
     getStagedRestore(): StagedRestoreManifest | null;
     /**