@jwilleke/ngdpbase-types 5.21.0 → 5.22.0

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

@@ -0,0 +1,153 @@
+/**
+ * Maintenance mode: the one owner (#1906), and the settings it reads (#1147).
+ *
+ * {@link MaintenanceState} (at the end of this file) is the door every manager
+ * uses to put the site in maintenance mode. {@link resolveMaintenanceState}
+ * reads the administrator's settings for it from configuration.
+ *
+ * #1147, the history behind the settings reader:
+ *
+ * One switch, one state. Before this module, maintenance mode had two readers
+ * on two different sources and the admin toggle wrote to only one of them:
+ *
+ *   - the gate middleware read `engine.config.features.maintenance`, an
+ *     in-memory object that configuration never populates — `Engine.initialize`
+ *     will not overwrite `this.config` once set (`core/Engine.ts:63`), and the
+ *     constructor sets it to `{}`, so it stayed empty for the process lifetime
+ *   - `PolicyInformationPoint.checkContextRestrictions` read the documented keys through
+ *     `ConfigurationManager`
+ *
+ * So the shipped `ngdpbase.features.maintenance.enabled` key did not gate the
+ * site, the toggle did not survive a restart, and the two halves could
+ * disagree at runtime — the gate serving traffic normally while the ACL
+ * evaluator denied on maintenance grounds, or the reverse.
+ *
+ * Every reader now resolves through here, which is what makes "one switch, one
+ * state" provable rather than asserted.
+ */
+/** Configuration read function, matching `ConfigurationManager.getProperty`. */
+export type ReadProperty = (key: string, fallback: unknown) => unknown;
+/** The administrator's maintenance settings, as configured. */
+export interface MaintenanceSettings {
+    /** Whether the admin switch was left on: the persisted record of {@link ADMIN_SWITCH_REASON}. */
+    enabled: boolean;
+    /** Whether administrators may still reach the instance while it is closed. */
+    allowAdmins: boolean;
+    /** Shown on the maintenance page. Never empty. */
+    message: string;
+    /** Operator-supplied estimate, or null when none is configured. */
+    estimatedDuration: string | null;
+}
+export declare const MAINTENANCE_ENABLED_KEY = "ngdpbase.features.maintenance.enabled";
+export declare const MAINTENANCE_ALLOW_ADMINS_KEY = "ngdpbase.features.maintenance.allow-admins";
+export declare const MAINTENANCE_MESSAGE_KEY = "ngdpbase.features.maintenance.message";
+export declare const MAINTENANCE_DURATION_KEY = "ngdpbase.features.maintenance.estimated-duration";
+/**
+ * Read the administrator's maintenance settings from configuration.
+ *
+ * Read when asked rather than cached at boot, so a changed message, estimate
+ * or allow-admins applies at once. Whether the site IS in maintenance mode is
+ * {@link MaintenanceState}'s, not this: `enabled` here is only the admin
+ * switch's persisted record (#1906).
+ */
+export declare function resolveMaintenanceState(get: ReadProperty): MaintenanceSettings;
+/**
+ * #1883's key, retired by #1906. Still read when a site set it, so an instance
+ * that wrote its own outage wording for v5.20.0 keeps it — but only while the
+ * site has not set {@link MAINTENANCE_MESSAGE_KEY} itself. No shipped default.
+ */
+export declare const LEGACY_MESSAGE_KEY = "ngdpbase.managers.addons-manager.site-critical.public-message";
+/**
+ * Why the admin switch holds the site in maintenance mode: the one reason an
+ * administrator enters and leaves, through the toggle on the admin dashboard.
+ */
+export declare const ADMIN_SWITCH_REASON = "An administrator turned maintenance mode on (Admin Dashboard \u2192 Enable Maintenance; ngdpbase.features.maintenance.enabled).";
+/** What a manager may say when it puts the site in maintenance mode. */
+export interface EnterOptions {
+    /** What visitors are told, in place of the configured message. */
+    message?: string;
+    /** What visitors are told about how long, in place of the configured estimate. */
+    estimatedDuration?: string;
+    /**
+     * Whether administrators may use the whole site while this reason holds.
+     * False (the default) for a failure: everyone, administrators included, gets
+     * only `/admin`, `/login` and `/logout`, because the rest of the site cannot
+     * be trusted to work. True only for the admin switch, where nothing is broken.
+     */
+    adminsMayEnter?: boolean;
+}
+/**
+ * The configuration reads the visitor view needs — `ConfigurationManager`'s
+ * own methods, so callers pass the manager itself. `getCustomProperty` tells
+ * "the site set this" from "this is the shipped default", which decides
+ * whether the legacy key may still speak.
+ */
+export interface MaintenanceConfig {
+    getProperty(key: string, fallback: unknown): unknown;
+    getCustomProperty?(key: string): unknown;
+}
+/** What a visitor is shown while the site is in maintenance mode. It carries no reason. */
+export interface MaintenanceVisitorView {
+    message: string;
+    estimatedDuration: string | null;
+    /** Whether a signed-in administrator may use the whole site. */
+    adminsMayEnter: boolean;
+}
+/**
+ * Whether the site is in maintenance mode, and why (#1906, operator 2026-10-19).
+ *
+ * The one door. Whatever needs the site closed calls {@link enter} with a
+ * reason for administrators and, if it has one, its own message for visitors;
+ * {@link leave} reopens the site when that reason clears. AuditManager
+ * (refuse-boot), AddonsManager (a site-critical add-on that did not load),
+ * DatabaseManager (the application database cannot be opened), the boot-time
+ * configuration checks in `app.ts` (TLS files, egress ranges) and the admin
+ * toggle all go through here. `engine.blockConfiguration` is retired.
+ *
+ * __Where the state lives.__ One instance per Engine, created in its
+ * constructor (`engine.maintenance`), in memory. Not in configuration: the
+ * boot paths call `enter` while managers are still initialising —
+ * DatabaseManager before most of the others, AuditManager before the
+ * notification layer — and a failure that is only true for this run must not
+ * be written into the operator's file, where it would outlive the failure.
+ * Not a module global: each Engine, and so each test, has its own.
+ *
+ * The admin switch is the one reason that must survive a restart (#1147), so
+ * the toggle also persists `ngdpbase.features.maintenance.enabled`, and
+ * {@link restoreSwitch} enters it again at boot. That key is the reason's
+ * record; nothing reads it to decide whether the site is open.
+ *
+ * Reasons are for administrators only: the log, the admin dashboard, and the
+ * notifications the managers send. Visitors, and `/health/readiness`, get
+ * {@link visitorView}, which carries none.
+ */
+export declare class MaintenanceState {
+    private readonly entries;
+    /** Put the site in maintenance mode for `reason`. Entering a held reason again replaces its options. */
+    enter(reason: string, options?: EnterOptions): void;
+    /** Clear `reason`. The site reopens when no reason is left. False when it was not held. */
+    leave(reason: string): boolean;
+    /** Whether any reason holds the site in maintenance mode. */
+    isOn(): boolean;
+    /** Whether `reason` currently holds it. */
+    has(reason: string): boolean;
+    /** Every reason, in the order entered. For administrators only. */
+    reasons(): readonly string[];
+    /**
+     * Whether a reason holds that keeps everyone, administrators included, to
+     * `/admin`, `/login` and `/logout`: a failure, rather than the admin switch.
+     */
+    isClosedToAdmins(): boolean;
+    /** Enter the admin switch again when the configuration says it was left on (#1147). */
+    restoreSwitch(config: MaintenanceConfig | null | undefined): void;
+    /**
+     * What visitors see; null when the site is open.
+     *
+     * The message is the first reason's own, when a manager passed one; else
+     * `ngdpbase.features.maintenance.message` as the site set it; else the
+     * retired {@link LEGACY_MESSAGE_KEY}, when the site set that; else the
+     * shipped message. The estimate: the first reason's own, else
+     * `ngdpbase.features.maintenance.estimated-duration`, else none.
+     */
+    visitorView(config: MaintenanceConfig | null | undefined): MaintenanceVisitorView | null;
+}

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

@@ -55,7 +55,7 @@ export type StoreTakeout = {
  * Returns an empty file list when the store does not exist, so a caller can ask
  * about a store without first proving it is there.
  */
-export declare function collectStore(pagesDirectory: string, owner: string, store: string, layout?: PrivateStoreLayoutOverrides): Promise<StoreTakeout>;
+export declare function collectStore(pagesDirectory: string, owner: string, store: string, layout?: PrivateStoreLayoutOverrides, skip?: (relativeToStore: string) => boolean): Promise<StoreTakeout>;
 /** The store ids a user has on disk, in directory order. */
 export declare function listStoreIds(pagesDirectory: string, owner: string, layout?: PrivateStoreLayoutOverrides): Promise<string[]>;
 /** The users who have a private directory on disk, in directory order. */
@@ -68,7 +68,7 @@ export declare function listPrivateOwners(pagesDirectory: string, layout?: Priva
  * This is the unit both callers work in — an instance backup asks for it once
  * per owner, and a user's own download asks for it once, for themselves.
  */
-export declare function collectUser(pagesDirectory: string, owner: string, layout?: PrivateStoreLayoutOverrides): Promise<{
+export declare function collectUser(pagesDirectory: string, owner: string, layout?: PrivateStoreLayoutOverrides, skip?: (relativeToStore: string) => boolean): Promise<{
     owner: string;
     userFiles: StoreFile[];
     stores: StoreTakeout[];

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

@@ -0,0 +1,110 @@
+/** The config key naming the site restore manifest. */
+export declare const SITE_RESTORE_MANIFEST_KEY = "ngdpbase.backup.restore-manifest";
+/** Its default: beside the other instance data in FAST_STORAGE. */
+export declare const SITE_RESTORE_MANIFEST_DEFAULT = "./data/site-restore.json";
+/** One live path and the staged copy that replaces it at the next start. */
+export interface StagedSwap {
+    live: string;
+    staged: string;
+}
+/** One manager's share of a site restore. */
+export interface SiteRestorePart {
+    manager: string;
+    swaps: StagedSwap[];
+    /** Further files to remove when the restore is discarded (DatabaseManager's own manifest). */
+    discard?: string[];
+    status?: 'applied' | 'set-aside';
+    note?: string;
+}
+export interface SiteRestoreManifest {
+    version: 1;
+    state: 'staging' | 'staged' | 'refused';
+    reason?: string;
+    /** When staging began. */
+    stagedAt: string;
+    /** When the backup it came from was taken. */
+    backup: string;
+    /** The backup document's filename. */
+    source: string;
+    stagedBy: string;
+    /** The backup of the live data taken just before staging: restoring it undoes this one. */
+    safetyBackup?: string;
+    parts: SiteRestorePart[];
+}
+/** The staged copy of a live path: beside it, so staging and applying name the same path. */
+export declare const stagedPathFor: (live: string) => string;
+/** Where a live path is kept once a restore has replaced it. */
+export declare const keptPathFor: (live: string) => string;
+/** The manifest file for this site, read through the configuration (never a constant). */
+export declare function siteRestoreFile(configManager: {
+    getResolvedDataPath(key: string, def: string): string;
+} | null | undefined): string;
+/**
+ * The manifest, or null when there is none. Throws when a file is there but
+ * is not a manifest: a restore record that can't be read is never ignored.
+ */
+export declare function readSiteRestore(file: string): SiteRestoreManifest | null;
+/** Start staging a site restore: the record exists before any part is staged, so an interrupted staging is recognised. */
+export declare function beginSiteRestore(file: string, meta: Omit<SiteRestoreManifest, 'version' | 'state' | 'parts'>): void;
+/** Record one owner's staged part. Only while staging. */
+export declare function recordStagedPart(file: string, part: SiteRestorePart): void;
+/** The commit: every part is staged. */
+export declare function commitSiteRestore(file: string): SiteRestoreManifest;
+/**
+ * Throw a staged (or half-staged) site restore away: every part's staged
+ * files and the manifest are removed. Live data is never touched.
+ */
+export declare function discardSiteRestore(file: string): SiteRestoreManifest | null;
+/** Move a staged path aside as `*.incomplete`, so it is neither applied nor retried. */
+export declare function setAsidePath(staged: string): void;
+export type PartGate = {
+    decision: 'none';
+} | {
+    decision: 'apply';
+    part: SiteRestorePart;
+    manifest: SiteRestoreManifest;
+} | {
+    decision: 'set-aside';
+    reason: string;
+    part?: SiteRestorePart;
+};
+/**
+ * Whether `manager`'s part of a site restore is to be applied now. `none`:
+ * there is no site restore, or it has no part for this manager, or that part
+ * is done. `apply`: the restore is committed and every part still pending has
+ * its staged files. `set-aside`: it isn't, and the set is marked refused.
+ */
+export declare function gatePart(file: string, manager: string): PartGate;
+/**
+ * Record what became of `manager`'s part. A part set aside refuses the rest
+ * of the set. When every part is done the manifest becomes `<file>.done`.
+ */
+export declare function markPart(file: string, manager: string, status: 'applied' | 'set-aside', note?: string): void;
+export interface PartOutcome {
+    /** Each live path now restored, with where its previous content was kept. */
+    applied: Array<{
+        live: string;
+        kept: string;
+    }>;
+    /** Why nothing (or, after a failed rename, not everything) was applied. */
+    refused?: string;
+}
+/**
+ * Apply `manager`'s part of a staged site restore, at start, before the
+ * manager reads its data. `allowed` says which live paths this manager may
+ * replace, so a tampered manifest cannot rename an arbitrary file.
+ * `strays` lists staged paths of this manager's that exist on disk, found by
+ * the manager: with no committed restore naming them they are set aside.
+ * Returns null when there was nothing to do.
+ */
+export declare function applyPartAtStart(file: string, manager: string, options: {
+    allowed: (swap: StagedSwap) => boolean;
+    strays?: () => string[];
+}): PartOutcome | null;
+/**
+ * What a start did with a site restore, for BackupManager to tell admins at
+ * the end of the start: the finished record (`<file>.done`, then kept as
+ * `<file>.last`), or a record with parts still pending — their managers did
+ * not start — which is then refused and its pending parts set aside.
+ */
+export declare function finishSiteRestoreAtBoot(file: string): SiteRestoreManifest | null;

package/lib/src/utils/siteRestore.js

@@ -0,0 +1,309 @@
+/**
+ * A whole-site restore, staged for the next start, all or nothing (#1876).
+ *
+ * The databases already restore this way (#1723): each is copied to
+ * `<live>.staged`, and the next start renames it into place before anything
+ * opens it. This extends the same shape to every part of the site whose
+ * owning manager stages its restore (attachments, role membership, persons,
+ * organizations, footnotes and comments). Each owner does its own work, as
+ * Manager-SOT asks; this module only holds the one record that binds the
+ * parts together, so they go in together or not at all.
+ *
+ * The record is the __site restore manifest__ (`ngdpbase.backup.restore-manifest`,
+ * default `${FAST_STORAGE}/site-restore.json`):
+ *
+ * - __Staging__ (BackupManager.restoreFromFile): the manifest is written in
+ *   state `staging` before any part is staged. Each owner stages its files
+ *   beside its live ones and records its part — the pairs `{ live, staged }`
+ *   it will swap. Any failure discards every part already recorded and the
+ *   manifest. Only when every part is staged is the state set to `staged`:
+ *   that write is the commit.
+ * - __Applying__ (each owner's `initialize`, before it reads its data): the
+ *   owner asks {@link gatePart}. A part is applied only when the manifest is
+ *   committed and every part that is still pending has all of its staged
+ *   files in place, so a set that lost a part applies none of it. Each live
+ *   path steps aside as `<live>.pre-restore`, and the staged one takes its
+ *   name: a rename, never a write into live data. The part is then marked
+ *   applied in the manifest, so a start that stops half-way picks up where it
+ *   stopped instead of seeing a "missing" part.
+ * - __Refused__: an interrupted staging, a part whose staged files are gone,
+ *   or a tampered manifest (an owner checks every live path it is asked to
+ *   replace) sets the manifest to `refused`, and each part's staged files are
+ *   set aside as `*.incomplete` — never applied, never retried.
+ * - __Done__: once every part is applied or set aside, the manifest is
+ *   renamed `<manifest>.done`, which BackupManager reports to admins at the
+ *   end of the start and keeps as `<manifest>.last`.
+ *
+ * Everything here is synchronous file renames on the owner's own paths: it
+ * runs once at start, before the owner serves anything.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+/** The config key naming the site restore manifest. */
+export const SITE_RESTORE_MANIFEST_KEY = 'ngdpbase.backup.restore-manifest';
+/** Its default: beside the other instance data in FAST_STORAGE. */
+export const SITE_RESTORE_MANIFEST_DEFAULT = './data/site-restore.json';
+/** The staged copy of a live path: beside it, so staging and applying name the same path. */
+export const stagedPathFor = (live) => `${live}.staged`;
+/** Where a live path is kept once a restore has replaced it. */
+export const keptPathFor = (live) => `${live}.pre-restore`;
+/** The manifest file for this site, read through the configuration (never a constant). */
+export function siteRestoreFile(configManager) {
+    return configManager?.getResolvedDataPath(SITE_RESTORE_MANIFEST_KEY, SITE_RESTORE_MANIFEST_DEFAULT) ?? SITE_RESTORE_MANIFEST_DEFAULT;
+}
+function isFile(file) {
+    try {
+        return statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The manifest, or null when there is none. Throws when a file is there but
+ * is not a manifest: a restore record that can't be read is never ignored.
+ */
+export function readSiteRestore(file) {
+    if (!isFile(file))
+        return null;
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    if (parsed?.version !== 1 || !Array.isArray(parsed.parts) || !['staging', 'staged', 'refused'].includes(parsed.state)) {
+        throw new Error(`${path.basename(file)} is not a site restore manifest`);
+    }
+    return parsed;
+}
+function writeSiteRestore(file, manifest) {
+    mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.tmp`;
+    writeFileSync(tmp, JSON.stringify(manifest, null, 2) + '\n', { mode: 0o600 });
+    renameSync(tmp, file);
+}
+/** Start staging a site restore: the record exists before any part is staged, so an interrupted staging is recognised. */
+export function beginSiteRestore(file, meta) {
+    if (isFile(file))
+        throw new Error('A site restore is already staged; cancel it or replace it first');
+    writeSiteRestore(file, { version: 1, state: 'staging', ...meta, parts: [] });
+}
+/** Record one owner's staged part. Only while staging. */
+export function recordStagedPart(file, part) {
+    const manifest = readSiteRestore(file);
+    if (!manifest || manifest.state !== 'staging')
+        throw new Error('No site restore is being staged');
+    manifest.parts = [...manifest.parts.filter((p) => p.manager !== part.manager), { manager: part.manager, swaps: part.swaps, ...(part.discard ? { discard: part.discard } : {}) }];
+    writeSiteRestore(file, manifest);
+}
+/** The commit: every part is staged. */
+export function commitSiteRestore(file) {
+    const manifest = readSiteRestore(file);
+    if (!manifest || manifest.state !== 'staging')
+        throw new Error('No site restore is being staged');
+    for (const part of manifest.parts) {
+        const missing = part.swaps.filter((s) => !existsSync(s.staged));
+        if (missing.length > 0)
+            throw new Error(`${part.manager} recorded staged files that are not there: ${missing.map((s) => path.basename(s.staged)).join(', ')}`);
+    }
+    manifest.state = 'staged';
+    writeSiteRestore(file, manifest);
+    return manifest;
+}
+/**
+ * Throw a staged (or half-staged) site restore away: every part's staged
+ * files and the manifest are removed. Live data is never touched.
+ */
+export function discardSiteRestore(file) {
+    let manifest;
+    try {
+        manifest = readSiteRestore(file);
+    }
+    catch {
+        manifest = null;
+    }
+    for (const part of manifest?.parts ?? []) {
+        for (const swap of part.swaps)
+            rmSync(swap.staged, { recursive: true, force: true });
+        for (const extra of part.discard ?? [])
+            rmSync(extra, { recursive: true, force: true });
+    }
+    rmSync(file, { force: true });
+    return manifest;
+}
+/** Move a staged path aside as `*.incomplete`, so it is neither applied nor retried. */
+export function setAsidePath(staged) {
+    if (!existsSync(staged))
+        return;
+    const target = `${staged}.incomplete`;
+    rmSync(target, { recursive: true, force: true });
+    renameSync(staged, target);
+}
+/**
+ * Whether `manager`'s part of a site restore is to be applied now. `none`:
+ * there is no site restore, or it has no part for this manager, or that part
+ * is done. `apply`: the restore is committed and every part still pending has
+ * its staged files. `set-aside`: it isn't, and the set is marked refused.
+ */
+export function gatePart(file, manager) {
+    let manifest;
+    try {
+        manifest = readSiteRestore(file);
+    }
+    catch (err) {
+        // A record that can't be read applies nothing. It is left where it is,
+        // untouched — the path may be misconfigured to name some other file —
+        // and every start says so until it is fixed.
+        return { decision: 'set-aside', reason: `the site restore manifest ${file} cannot be read: ${err.message}` };
+    }
+    if (!manifest)
+        return { decision: 'none' };
+    const part = manifest.parts.find((p) => p.manager === manager);
+    if (!part || part.status)
+        return { decision: 'none' };
+    if (manifest.state === 'staging') {
+        return refuse(file, manifest, part, 'the site restore was still being staged when the server stopped (interrupted staging)');
+    }
+    if (manifest.state === 'refused') {
+        return { decision: 'set-aside', reason: manifest.reason ?? 'the site restore was refused', part };
+    }
+    const setAsideAlready = manifest.parts.filter((p) => p.status === 'set-aside').map((p) => p.manager);
+    if (setAsideAlready.length > 0) {
+        return refuse(file, manifest, part, `part of it (${setAsideAlready.join(', ')}) was not applied, and the parts belong together`);
+    }
+    const missing = manifest.parts
+        .filter((p) => !p.status)
+        .flatMap((p) => p.swaps.filter((s) => !existsSync(s.staged)).map((s) => `${p.manager}: ${path.basename(s.staged)}`));
+    if (missing.length > 0) {
+        return refuse(file, manifest, part, `staged files are missing (${missing.join(', ')}), and the parts belong together`);
+    }
+    return { decision: 'apply', part, manifest };
+}
+function refuse(file, manifest, part, reason) {
+    manifest.state = 'refused';
+    manifest.reason = reason;
+    writeSiteRestore(file, manifest);
+    return { decision: 'set-aside', reason, part };
+}
+/**
+ * Record what became of `manager`'s part. A part set aside refuses the rest
+ * of the set. When every part is done the manifest becomes `<file>.done`.
+ */
+export function markPart(file, manager, status, note) {
+    let manifest;
+    try {
+        manifest = readSiteRestore(file);
+    }
+    catch {
+        return;
+    }
+    if (!manifest)
+        return;
+    const part = manifest.parts.find((p) => p.manager === manager);
+    if (!part)
+        return;
+    part.status = status;
+    if (note)
+        part.note = note;
+    if (status === 'set-aside' && manifest.state !== 'refused') {
+        manifest.state = 'refused';
+        manifest.reason = note ?? `${manager}'s part was not applied`;
+    }
+    writeSiteRestore(file, manifest);
+    if (manifest.parts.every((p) => p.status)) {
+        const done = `${file}.done`;
+        rmSync(done, { force: true });
+        renameSync(file, done);
+    }
+}
+/**
+ * Apply `manager`'s part of a staged site restore, at start, before the
+ * manager reads its data. `allowed` says which live paths this manager may
+ * replace, so a tampered manifest cannot rename an arbitrary file.
+ * `strays` lists staged paths of this manager's that exist on disk, found by
+ * the manager: with no committed restore naming them they are set aside.
+ * Returns null when there was nothing to do.
+ */
+export function applyPartAtStart(file, manager, options) {
+    const gate = gatePart(file, manager);
+    if (gate.decision === 'none') {
+        const strays = options.strays?.() ?? [];
+        if (strays.length === 0)
+            return null;
+        for (const s of strays)
+            setAsidePath(s);
+        return { applied: [], refused: `staged files with no site restore naming them (an interrupted staging): ${strays.map((s) => path.basename(s)).join(', ')} — set aside as *.incomplete` };
+    }
+    if (gate.decision === 'set-aside') {
+        for (const swap of gate.part?.swaps ?? [])
+            setAsidePath(swap.staged);
+        for (const s of options.strays?.() ?? [])
+            setAsidePath(s);
+        if (gate.part)
+            markPart(file, manager, 'set-aside', gate.reason);
+        return { applied: [], refused: gate.reason };
+    }
+    const bad = gate.part.swaps.find((s) => !options.allowed(s) || s.staged !== stagedPathFor(s.live));
+    if (bad) {
+        const reason = `the site restore manifest names ${bad.live}, which is not ${manager}'s to replace`;
+        for (const swap of gate.part.swaps)
+            if (swap.staged === stagedPathFor(swap.live))
+                setAsidePath(swap.staged);
+        markPart(file, manager, 'set-aside', reason);
+        return { applied: [], refused: reason };
+    }
+    const applied = [];
+    try {
+        for (const swap of gate.part.swaps) {
+            const kept = keptPathFor(swap.live);
+            rmSync(kept, { recursive: true, force: true });
+            if (existsSync(swap.live))
+                renameSync(swap.live, kept);
+            mkdirSync(path.dirname(swap.live), { recursive: true });
+            renameSync(swap.staged, swap.live);
+            applied.push({ live: swap.live, kept });
+        }
+    }
+    catch (err) {
+        const reason = `applying ${manager}'s part failed after ${applied.length} of ${gate.part.swaps.length} paths: ${err.message}`;
+        markPart(file, manager, 'set-aside', reason);
+        return { applied, refused: reason };
+    }
+    markPart(file, manager, 'applied');
+    return { applied };
+}
+/**
+ * What a start did with a site restore, for BackupManager to tell admins at
+ * the end of the start: the finished record (`<file>.done`, then kept as
+ * `<file>.last`), or a record with parts still pending — their managers did
+ * not start — which is then refused and its pending parts set aside.
+ */
+export function finishSiteRestoreAtBoot(file) {
+    const done = `${file}.done`;
+    let manifest;
+    try {
+        manifest = readSiteRestore(file);
+    }
+    catch {
+        manifest = null;
+    }
+    if (manifest) {
+        if (manifest.state === 'staging')
+            refuse(file, manifest, manifest.parts[0], 'the site restore was still being staged when the server stopped (interrupted staging)');
+        const pending = manifest.parts.filter((p) => !p.status);
+        for (const part of pending) {
+            for (const swap of part.swaps)
+                setAsidePath(swap.staged);
+            for (const extra of part.discard ?? [])
+                setAsidePath(extra);
+            markPart(file, part.manager, 'set-aside', `${part.manager} did not apply its part at start, so it was set aside`);
+        }
+        if (manifest.parts.length === 0 && isFile(file)) {
+            rmSync(done, { force: true });
+            renameSync(file, done);
+        }
+    }
+    if (!isFile(done))
+        return null;
+    const finished = JSON.parse(readFileSync(done, 'utf8'));
+    const last = `${file}.last`;
+    rmSync(last, { force: true });
+    renameSync(done, last);
+    return finished;
+}

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

@@ -0,0 +1,44 @@
+export interface TreeArchiveOutcome {
+    /** Regular files written. */
+    files: number;
+    /** Their bytes. */
+    bytes: number;
+    /** Entries left out because they are not a file or a folder (a symbolic link), relative to the root. */
+    skipped: string[];
+}
+/**
+ * Write `entries` (paths relative to `root`; default: everything in it) into
+ * `target`, streamed. `exclude` leaves out a path relative to `root`, in
+ * posix form. A missing `root` writes an empty archive. Never overwrites.
+ */
+export declare function writeTreeArchive(target: string, root: string, options?: {
+    entries?: string[];
+    exclude?: (relative: string) => boolean;
+    backupKey?: string;
+}): Promise<TreeArchiveOutcome>;
+/**
+ * Extract `archive` into `dest`, which is emptied first, streamed.
+ * `select(relative)` picks the entries to extract (default: all). Refuses —
+ * removing `dest` — an entry that is not a file or a folder, an absolute
+ * path, or one that climbs out (`..`).
+ */
+export declare function extractTreeArchive(archive: string, dest: string, options?: {
+    select?: (relative: string) => boolean;
+    strip?: number;
+    backupKey?: string;
+}): Promise<{
+    files: number;
+    bytes: number;
+}>;
+/**
+ * Every entry in an archive, plain or encrypted, read as a stream: what a
+ * caller checks before extracting. `onEntry` gets each entry's path and type.
+ */
+export declare function listTreeArchive(archive: string, onEntry: (entry: {
+    path: string;
+    type: string;
+}) => void, options?: {
+    backupKey?: string;
+}): Promise<void>;
+/** The first `n` bytes of a file, read without reading the rest. */
+export declare function readHead(file: string, n: number): Promise<Buffer>;

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

@@ -49,5 +49,11 @@ export declare function sameUsername(a: unknown, b: unknown): boolean;
  * checked separately by `isSystemPrincipal`, because an operator chooses it.
  */
 export declare const RESERVED_USERNAMES: readonly string[];
-/** True when the name belongs to a principal rather than a person. */
+/**
+ * The prefix of a person's identifier when the person has no account (#1930):
+ * `person:<uuid>`. No username may start with it, so an account-less person's
+ * identifier can never be, or later become, someone's username.
+ */
+export declare const ACCOUNTLESS_PERSON_PREFIX = "person:";
+/** True when the name belongs to a principal rather than a person, or has the account-less person prefix. */
 export declare function isReservedUsername(username: unknown): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.21.0",
+  "version": "5.22.0",
   "description": "TypeScript types for ngdpbase add-ons, and a test kit of core's own values. A dev dependency, versioned with ngdpbase.",
   "license": "Apache-2.0",
   "author": "Jim Willeke",