@jwilleke/ngdpbase-types 5.20.0 → 5.22.0

package/lib/src/utils/sensitiveValues.js

@@ -15,12 +15,20 @@
  * hides secret-looking fields nested inside an object value (an OIDC client's
  * `client_secret` inside `oidc-auth-server.clients`).
  *
+ * An entry may also name something inside a key's value by its path (#1889):
+ * `ngdpbase.addons.accounting.accounts.*.account-number`, where `*` stands for
+ * any one map key (or list index). It hides what sits there, at the entry's
+ * level, wherever a value is shown, except a bare `$NAME` reference, which is
+ * a pointer to the environment, not the secret. The paths are walked by
+ * `utils/configPaths.ts`, the same walk that resolves `$NAME` inside a value.
+ *
  * Hidden values are replaced on the server, before any HTML is built: they
  * never reach a page, its source or the parse cache.
  *
  * @module utils/sensitiveValues
  */
 import { enabledEntries } from './configFiles.js';
+import { envRefName, mapConfigValue, parsePathEntry, pathMatches, pathString, patternBelow, valueAt } from './configPaths.js';
 export const SENSITIVE_VALUES_KEY = 'ngdpbase.config.sensitive-values';
 /** The list's name before #1750; still read, with a boot warning to rename it. */
 export const LEGACY_SECRET_KEYS_KEY = 'ngdpbase.config.secret-keys';
@@ -30,34 +38,83 @@ const SECRET_NAME_PATTERN = /secret|passw(or)?d|token|credential|api[-_]?key|pri
 export function looksSecret(name) {
     return SECRET_NAME_PATTERN.test(name);
 }
+/**
+ * What an administrator's screen, a log line and an audit record may hold:
+ * sensitive values, never secrets. Secrets there are revealed one key at a
+ * time, on demand (`secret-reveal`).
+ */
+export const NO_SECRETS = Object.freeze({ sensitive: true, secret: false });
 /** What a hidden value is shown as. */
 export const HIDDEN = '(hidden)';
 /**
  * The declared levels: the legacy list's keys as `secret`, then the new map
  * (`"secret"`, `"sensitive"`, `true` = secret; `false` / `null` removes an
- * entry, so an instance can override a shipped one).
+ * entry, so an instance can override a shipped one). An entry that is not a
+ * well-formed key or path (#1889: an empty segment, a `*` inside a segment, or
+ * a `*` before `ngdpbase.<category>`) is no entry, as a level that is none of
+ * these is no entry; {@link sensitiveValueProblems} names both.
  */
 export function valueLevels(read) {
     const levels = new Map();
-    for (const key of enabledEntries(read(LEGACY_SECRET_KEYS_KEY, {})))
-        levels.set(key, 'secret');
+    const entry = (key) => (parsePathEntry(key.trim()) ? key.trim() : null);
+    for (const key of enabledEntries(read(LEGACY_SECRET_KEYS_KEY, {}))) {
+        const k = entry(key);
+        if (k)
+            levels.set(k, 'secret');
+    }
     const declared = read(SENSITIVE_VALUES_KEY, {});
     if (declared && typeof declared === 'object' && !Array.isArray(declared)) {
         for (const [key, level] of Object.entries(declared)) {
+            const k = entry(key);
+            if (!k)
+                continue;
             if (level === 'secret' || level === true)
-                levels.set(key, 'secret');
+                levels.set(k, 'secret');
             else if (level === 'sensitive')
-                levels.set(key, 'sensitive');
+                levels.set(k, 'sensitive');
             else
-                levels.delete(key);
+                levels.delete(k);
         }
     }
     else {
-        for (const key of enabledEntries(declared))
-            levels.set(key, 'secret');
+        for (const key of enabledEntries(declared)) {
+            const k = entry(key);
+            if (k)
+                levels.set(k, 'secret');
+        }
     }
     return levels;
 }
+/**
+ * What is wrong with the declared entries, one line each (#1889): an entry
+ * that is not a well-formed key or path, or a level that is none of
+ * `"secret"`, `"sensitive"`, `true`, `false`, `null`. {@link valueLevels}
+ * drops each such entry; the engine warns at boot.
+ */
+export function sensitiveValueProblems(read) {
+    const problems = [];
+    const named = (list, key) => {
+        if (!parsePathEntry(key.trim())) {
+            problems.push(`${list}: '${key}' is not a configuration key or path (an empty segment, or a * that is not a whole segment after ngdpbase.<category>); it is ignored`);
+        }
+    };
+    for (const key of enabledEntries(read(LEGACY_SECRET_KEYS_KEY, {})))
+        named(LEGACY_SECRET_KEYS_KEY, key);
+    const declared = read(SENSITIVE_VALUES_KEY, {});
+    if (declared && typeof declared === 'object' && !Array.isArray(declared)) {
+        for (const [key, level] of Object.entries(declared)) {
+            named(SENSITIVE_VALUES_KEY, key);
+            if (!(level === 'secret' || level === 'sensitive' || level === true || level === false || level === null)) {
+                problems.push(`${SENSITIVE_VALUES_KEY}: '${key}' has level ${JSON.stringify(level)}, which is not "secret" or "sensitive"; the entry is ignored`);
+            }
+        }
+    }
+    else {
+        for (const key of enabledEntries(declared))
+            named(SENSITIVE_VALUES_KEY, key);
+    }
+    return problems;
+}
 /** The keys declared `secret`: what logs, the audit log and the admin screen never print. */
 export function secretKeys(read) {
     return [...valueLevels(read)].filter(([, level]) => level === 'secret').map(([key]) => key);
@@ -91,9 +148,79 @@ function hideNestedSecrets(value) {
     }
     return value;
 }
+/** The path entries inside a key's value, as patterns below the key, with their levels. */
+function entriesBelow(key, levels) {
+    const out = [];
+    for (const [entry, level] of levels) {
+        const pattern = patternBelow(entry, key);
+        if (pattern && pattern.length > 0)
+            out.push([pattern, level]);
+    }
+    return out;
+}
+/** Whether a viewer may see a value at this level. */
+function maySee(level, viewer) {
+    return level === 'secret' ? viewer.secret : viewer.sensitive;
+}
+/**
+ * A key's value with what its path entries name hidden from this viewer
+ * (#1889). An empty value, and a bare `$NAME` reference, are kept: neither is
+ * the secret. The key's own level is {@link shownValue}'s business.
+ */
+export function hideDeclaredPaths(key, value, levels, viewer) {
+    const hidden = entriesBelow(key, levels).filter(([, level]) => !maySee(level, viewer)).map(([pattern]) => pattern);
+    if (hidden.length === 0)
+        return value;
+    return mapConfigValue(value, (node, below) => {
+        if (below.length === 0 || !hidden.some((pattern) => pathMatches(pattern, below)))
+            return undefined;
+        return node === undefined || node === null || node === '' || envRefName(node) ? node : HIDDEN;
+    });
+}
+/**
+ * The strings (and numbers, as text) a key's secret path entries name inside
+ * its value, each with its full path (#1889): what log redaction strikes.
+ * Everything under a named map or list counts.
+ */
+export function secretValuesBelow(key, value, levels) {
+    const secret = entriesBelow(key, levels).filter(([, level]) => level === 'secret').map(([pattern]) => pattern);
+    const found = [];
+    if (secret.length === 0)
+        return found;
+    mapConfigValue(value, (node, below) => {
+        if (below.length === 0 || !secret.some((pattern) => pathMatches(pattern, below)))
+            return undefined;
+        const at = [...below];
+        mapConfigValue(node, (leaf, under) => {
+            if (typeof leaf === 'string' || typeof leaf === 'number')
+                found.push({ path: pathString(key, [...at, ...under]), value: String(leaf) });
+            return undefined;
+        });
+        return node;
+    });
+    return found;
+}
+/**
+ * A value submitted from a screen that showed it with paths hidden, with each
+ * `HIDDEN` placeholder at a declared path put back to the stored value there
+ * (#1889). Without this, saving an edit to an accounts map would write the
+ * placeholder over every account number.
+ */
+export function keepHiddenValues(key, submitted, stored, levels) {
+    const patterns = entriesBelow(key, levels).map(([pattern]) => pattern);
+    if (patterns.length === 0)
+        return submitted;
+    return mapConfigValue(submitted, (node, below) => {
+        if (node !== HIDDEN || !patterns.some((pattern) => pathMatches(pattern, below)))
+            return undefined;
+        const kept = valueAt(stored, below);
+        return kept === undefined ? node : kept;
+    });
+}
 /**
- * The value a viewer may see for a key: itself, or `HIDDEN`. An empty value
- * is shown as it is — "not set" reveals nothing.
+ * The value a viewer may see for a key: itself, or `HIDDEN`; inside it, what
+ * its path entries name is hidden as well (#1889). An empty value is shown as
+ * it is: "not set" reveals nothing.
  */
 export function shownValue(key, value, levels, viewer) {
     const empty = value === undefined || value === null || value === '';
@@ -102,5 +229,6 @@ export function shownValue(key, value, levels, viewer) {
         return empty ? value : HIDDEN;
     if (level === 'sensitive' && !viewer.sensitive)
         return empty ? value : HIDDEN;
-    return viewer.secret ? value : hideNestedSecrets(value);
+    const shown = hideDeclaredPaths(key, value, levels, viewer);
+    return viewer.secret ? shown : hideNestedSecrets(shown);
 }

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;