@jwilleke/ngdpbase-types 5.21.0 → 5.23.0

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

@@ -0,0 +1,23 @@
+/**
+ * The environment variable holding the key every backup is encrypted under.
+ * 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.
+ */
+export declare const BACKUP_KEY_ENV = "NGDPBASE_BACKUP_KEY";
+/**
+ * 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;
+/**
+ * How every part left out of a backup for want of the key says so: the
+ * message starts with this. BackupManager recognises such a part by it
+ * (`isLeftOutForNoKey`): those are covered by its banner and one-time
+ * notice, never a notice per backup (operator, #1912).
+ */
+export declare const LEFT_OUT_FOR_NO_KEY = "NGDPBASE_BACKUP_KEY is not set, so ";
+/** Whether a backup warning or error says a part was left out only because there is no backup key. */
+export declare function isLeftOutForNoKey(message: string): boolean;
+/** The backup key as set now, trimmed; '' when there is none. Read at use, never cached. */
+export declare function currentBackupKey(): string;

package/lib/src/utils/backupKey.js

@@ -0,0 +1,37 @@
+/**
+ * The backup key (#1723, #1561, #1876): the one secret every encrypted part of
+ * a backup is made under — the database files (SQLCipher, `sqliteBackup.ts`),
+ * and the backup document, the file archives and the credentials store
+ * (`backupCrypto.ts`). One declaration here; DatabaseManager and the file
+ * parts read it from this module.
+ */
+import { createHmac } from 'node:crypto';
+/**
+ * The environment variable holding the key every backup is encrypted under.
+ * 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.
+ */
+export const BACKUP_KEY_ENV = 'NGDPBASE_BACKUP_KEY';
+/**
+ * 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 function backupKeyFingerprint(key) {
+    return createHmac('sha256', key).update('ngdpbase backup key fingerprint v1').digest('hex').slice(0, 16);
+}
+/**
+ * How every part left out of a backup for want of the key says so: the
+ * message starts with this. BackupManager recognises such a part by it
+ * (`isLeftOutForNoKey`): those are covered by its banner and one-time
+ * notice, never a notice per backup (operator, #1912).
+ */
+export const LEFT_OUT_FOR_NO_KEY = `${BACKUP_KEY_ENV} is not set, so `;
+/** Whether a backup warning or error says a part was left out only because there is no backup key. */
+export function isLeftOutForNoKey(message) {
+    return message.startsWith(LEFT_OUT_FOR_NO_KEY);
+}
+/** The backup key as set now, trimmed; '' when there is none. Read at use, never cached. */
+export function currentBackupKey() {
+    return (process.env[BACKUP_KEY_ENV] ?? '').trim();
+}

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

@@ -0,0 +1,58 @@
+/**
+ * The contacts door's one decision and its one record (#1930).
+ *
+ * PersonManager and OrganizationManager are the enforcement points for
+ * contacts. Both ask the PDP the same two questions with the caller's
+ * context: `contact-read` to list, search or view, `contact-manage` to
+ * create, change, delete or link; and both record each change as the
+ * `contact-manage` audit event. That rule lives here once, so the two doors
+ * cannot drift (operator, 2026-10-20).
+ *
+ * A refusal is thrown as {@link ContactRefusedError}, carrying the decision.
+ * A route turns it into the answer with `ApiContext.enforceDeny(err.permission,
+ * err.decision)`, the one place a refusal is shaped (#1431); the door never
+ * builds an HTTP answer itself.
+ */
+import { type ActorContext } from '../context/ActorContext.js';
+import type { CorePermission } from '../security/permissions.generated.js';
+import type { Decision } from '../types/Policy.js';
+type EngineLike = {
+    getManager: <T = unknown>(name: string) => T | null | undefined;
+};
+/** What a contacts door asks: `read` to list, search or view; `manage` to change. */
+export declare const CONTACT_PERMISSION: {
+    readonly read: "contact-read";
+    readonly manage: "contact-manage";
+};
+/** A contacts door said no. `permission` is what was refused; `decision` is the PDP's answer. */
+export declare class ContactRefusedError extends Error {
+    readonly permission: string;
+    readonly decision: Decision;
+    constructor(permission: string, decision: Decision);
+}
+/**
+ * Throws {@link ContactRefusedError} unless `ctx` may do `kind` (`read` asks
+ * `contact-read`, `manage` asks `contact-manage`), and each of `also` (a link
+ * to an account also asks `user-edit`). A missing context or decision point
+ * refuses: closed, never open.
+ */
+export declare function requireContactPermission(engine: EngineLike, ctx: ActorContext, kind: keyof typeof CONTACT_PERMISSION, also?: readonly CorePermission[]): Promise<void>;
+/** What a contacts record says was done. Names fields, never their values. */
+export interface ContactChange {
+    kind: 'person' | 'organization';
+    operation: 'create' | 'update' | 'delete' | 'link';
+    id: string;
+    fields?: string[];
+    /** For a link: the account joined to the person. */
+    account?: string;
+    /** For a link: how it was confirmed, `admin` or `email`. */
+    via?: 'admin' | 'email';
+}
+/**
+ * Record a contacts change as `contact-manage`, under the caller's context.
+ * `continue`: a lost record is counted, the change stands. A system context
+ * goes through `recordSystemAction`, so the bootstrap admin's person, made
+ * before the audit sink is up, is recorded once it is.
+ */
+export declare function recordContactChange(engine: EngineLike, ctx: ActorContext, change: ContactChange): Promise<void>;
+export {};

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

@@ -0,0 +1,7 @@
+/**
+ * The environment variable holding the SQLCipher key (#1536). Never a config
+ * key: config is readable from the admin screens. Declared here, with no
+ * dependencies, so the boot (`bootstrap-env.ts`) can name it without loading
+ * DatabaseManager; DatabaseManager re-exports it.
+ */
+export declare const DATABASE_KEY_ENV = "NGDPBASE_DATABASE_KEY";

package/lib/src/utils/databaseKey.js

@@ -0,0 +1,7 @@
+/**
+ * The environment variable holding the SQLCipher key (#1536). Never a config
+ * key: config is readable from the admin screens. Declared here, with no
+ * dependencies, so the boot (`bootstrap-env.ts`) can name it without loading
+ * DatabaseManager; DatabaseManager re-exports it.
+ */
+export const DATABASE_KEY_ENV = 'NGDPBASE_DATABASE_KEY';

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

@@ -0,0 +1,78 @@
+import type { BackupData, ManagerBackupOptions, ManagerRestoreOptions } from '../managers/BaseManager.js';
+import { siteRestoreFile, type PartOutcome } from './siteRestore.js';
+/** A folder part's `data` in the backup document. */
+export interface DirectoryBackupData {
+    format: 1;
+    /** The archive beside the document: `<stem>.<part>.tar`, or `.tar.enc` when encrypted. */
+    archive: string;
+    files: number;
+    bytes: number;
+    /** `backupKeyFingerprint()` of the key the archive is encrypted under; absent when it is not encrypted. */
+    keyFingerprint?: string;
+}
+/** Whether `name` is a bare archive name in the backup directory, never a path. */
+export declare function isArchiveName(name: unknown): name is string;
+/**
+ * The name and key for one archive of a backup: encrypted under the backup
+ * key when it is set (#1561), plain otherwise. BackupManager says, once per
+ * backup, that a backup without the key is not encrypted.
+ */
+export declare function archiveTarget(stem: string, part: string): {
+    archive: string;
+    backupKey?: string;
+    keyFingerprint?: string;
+};
+/**
+ * The key to read an archive of a backup with, checked against the
+ * fingerprint the backup recorded: a backup made under another key is
+ * refused before anything is staged. None for a backup that was not
+ * encrypted, which is then read as the plain archive it says it is.
+ */
+export declare function archiveReadKey(manager: string, data: {
+    keyFingerprint?: string;
+}): string | undefined;
+/**
+ * Back the folder up beside the document BackupManager is writing. Throws
+ * outside BackupManager: the files go beside a document, never into it.
+ * `exclude` leaves out a path relative to the folder (posix form).
+ */
+export declare function backupDirectoryPart(manager: string, part: string, folder: string | null, options?: ManagerBackupOptions, extra?: {
+    exclude?: (relative: string) => boolean;
+}): Promise<BackupData>;
+/**
+ * Stage the folder from a backup for the next start: the archive is
+ * extracted to `<folder>.staged`, and the swap recorded in the site restore.
+ * Throws — staging nothing — outside a site restore, for a backup without
+ * this part, or for an archive that is missing, unsafe, or under another key.
+ */
+export declare function stageDirectoryPart(manager: string, folder: string | null, backupData: BackupData, options?: ManagerRestoreOptions): Promise<void>;
+/**
+ * Put a staged restore of the folder in place, at start, before the manager
+ * reads it. Loud when something was staged but not applied.
+ */
+export declare function applyDirectoryPartAtStart(manager: string, folder: string, configManager: Parameters<typeof siteRestoreFile>[0]): PartOutcome | null;
+/**
+ * Back one file up beside the document, encrypted under the backup key, as
+ * `<stem>.<part>.tar.enc`. With `requireKey` and no key the file is left out:
+ * `data` is null and a warning says why, so BackupManager reports the backup
+ * incomplete (#1876: the credentials store is never in a backup unencrypted).
+ */
+export declare function backupFilePart(manager: string, part: string, file: string | null, options: ManagerBackupOptions | undefined, { requireKey, what }: {
+    requireKey: boolean;
+    what: string;
+}): Promise<{
+    data: DirectoryBackupData | null;
+    warnings: string[];
+    note?: string;
+}>;
+/**
+ * Stage one file from a backup as `<file>.staged`, and record the swap. When
+ * the file was absent at backup time the archive holds nothing, and
+ * `whenAbsent` is staged in its place (an empty store), so the restore still
+ * puts the site back as it was.
+ */
+export declare function stageFilePart(manager: string, file: string, data: DirectoryBackupData, options: ManagerRestoreOptions | undefined, { whenAbsent }: {
+    whenAbsent: string;
+}): Promise<void>;
+/** Put a staged restore of one file in place, at start, before the manager reads it. */
+export declare function applyFilePartAtStart(manager: string, file: string, configManager: Parameters<typeof siteRestoreFile>[0]): PartOutcome | null;

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

@@ -0,0 +1,20 @@
+/**
+ * emailForLog — the one way an email address reaches the server log (#1916).
+ *
+ * Rule (operator, 2026-10-20): a full email address never reaches the server
+ * log. A log line names the address's domain only. Audit records are not the
+ * server log and keep full addresses; do not use these helpers on them.
+ */
+/**
+ * The domain(s) of one address or a comma-separated list, lower-cased:
+ * `"Bob <bob@Example.org>, ann@x.io"` → `"example.org,x.io"`. A value
+ * without an `@` (or an empty one) reads as `unknown`.
+ */
+export declare function emailDomain(to: string | null | undefined): string;
+/**
+ * Any address inside free text (an SMTP error often quotes the rejected one)
+ * cut to its domain: `bob@example.org` → `…@example.org`.
+ */
+export declare function redactEmailAddresses(text: string): string;
+/** An error's message, with any address in it cut to its domain. */
+export declare function errorForLog(err: unknown): string;

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/sessionAccount.d.ts

@@ -0,0 +1,26 @@
+export type AccountEndReason = 'account-deleted' | 'account-disabled' | 'password-changed';
+interface AccountLike {
+    createdAt?: unknown;
+    isActive?: boolean;
+    sessionGeneration?: number;
+}
+interface SessionLike {
+    accountCreatedAt?: unknown;
+    signedInAt?: unknown;
+    sessionGeneration?: unknown;
+}
+/** The value a session is bound to: the account's creation time, or '' for a record without one. */
+export declare function accountBindingOf(account: AccountLike | null | undefined): string;
+/**
+ * What one request (or the sweep) does to a signed-in session, given its
+ * account as stored now (null when there is none). `bind` is set on a session
+ * signed in before the binding existed that still belongs to its account: the
+ * caller writes it to `accountCreatedAt`, once.
+ */
+export declare function checkSessionAccount(stored: SessionLike | Record<string, unknown>, account: AccountLike | null | undefined): {
+    end: AccountEndReason;
+} | {
+    end: null;
+    bind?: string;
+};
+export {};

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

@@ -1,4 +1,4 @@
-export type SessionEndReason = 'logout' | 'idle-timeout' | 'max-age' | 'password-changed' | 'superseded';
+export type SessionEndReason = 'logout' | 'idle-timeout' | 'max-age' | 'password-changed' | 'superseded' | 'account-deleted' | 'account-disabled';
 export declare function endSession(engine: {
     getManager(name: string): unknown;
 }, session: {

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;