@jwilleke/ngdpbase-types 5.25.0 → 5.26.0

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

@@ -0,0 +1,11 @@
+export interface IpLocationSources {
+    /** The site is reached only through Cloudflare, so its location headers can be believed. */
+    behindCloudflare: boolean;
+    /** Path to a GeoLite2 City `.mmdb` file, or '' for none. */
+    geoliteFile: string;
+}
+/**
+ * Roughly where `ip` is: Cloudflare's headers when the site is behind it and
+ * they name a place, else the GeoLite2 file when one is configured, else null.
+ */
+export declare function approximateLocation(ip: string | undefined, header: (name: string) => string | undefined, sources: IpLocationSources): Promise<string | null>;

package/lib/src/utils/schedule.js

@@ -0,0 +1,171 @@
+/**
+ * The schedule engine for scheduled jobs (#1713, epic #1611).
+ *
+ * A schedule is an iCalendar recurrence rule (RFC 5545 RRULE), the format the
+ * calendar add-on already stores, with a start (`dtstart`) and a time zone.
+ * Cron is not used: it cannot say "every 30 days" or "the last business day".
+ * Named shorthands (`daily 06:00`, `end-of-month`, …) expand to an RRULE.
+ *
+ * Recurrence is computed on wall-clock time and then placed in the time zone,
+ * so daylight saving does what a person expects:
+ *   - spring forward: a slot inside the skipped hour runs at the next valid
+ *     instant (02:30 becomes 03:30), rather than not at all;
+ *   - fall back: a slot inside the repeated hour runs once, at its first
+ *     occurrence.
+ * A date that does not exist is skipped, as RFC 5545 says: `BYMONTHDAY=31`
+ * skips short months; the last day of a month is `BYMONTHDAY=-1`. RFC 7529
+ * (RSCALE / SKIP) is not used (operator, 2026-10-08).
+ *
+ * Pure: no configuration is read here. The caller passes the default time zone
+ * (`ngdpbase.default.timezone`) and the minimum interval.
+ *
+ * @module utils/schedule
+ */
+import { RRuleTemporal } from 'rrule-temporal';
+import { Temporal } from 'temporal-polyfill';
+/**
+ * The default start. Rules that count an interval (`every 30 days`) are
+ * counted from it, so their phase is the same on every restart.
+ */
+const DEFAULT_DTSTART = '2000-01-01T00:00:00';
+const TIME = String.raw `(?:\s+(?:at\s+)?(\d{1,2}):(\d{2}))?`;
+const DAYS = ['MO', 'TU', 'WE', 'TH', 'FR', 'SA', 'SU'];
+/** Hour and minute parts for an optional `HH:MM`; midnight when absent. */
+function at(hour, minute) {
+    const h = hour === undefined ? 0 : Number(hour);
+    const m = minute === undefined ? 0 : Number(minute);
+    if (h > 23 || m > 59)
+        throw new Error(`Invalid time ${hour}:${minute}`);
+    return `BYHOUR=${h};BYMINUTE=${m}`;
+}
+/**
+ * The shorthands, each expanding to one RRULE. Case-insensitive; a time is
+ * optional where shown and defaults to 00:00.
+ */
+const SHORTHANDS = [
+    [/^hourly$/i, () => 'FREQ=HOURLY;BYMINUTE=0'],
+    [new RegExp(`^daily${TIME}$`, 'i'), (m) => `FREQ=DAILY;${at(m[1], m[2])}`],
+    [new RegExp(`^weekly\\s+(mo|tu|we|th|fr|sa|su)${TIME}$`, 'i'), (m) => `FREQ=WEEKLY;BYDAY=${m[1].toUpperCase()};${at(m[2], m[3])}`],
+    [/^every\s+(\d+)\s*m(?:in(?:utes?)?)?$/i, (m) => `FREQ=MINUTELY;INTERVAL=${Number(m[1])}`],
+    [/^every\s+(\d+)\s*h(?:ours?)?$/i, (m) => `FREQ=HOURLY;INTERVAL=${Number(m[1])};BYMINUTE=0`],
+    [new RegExp(`^every\\s+(\\d+)\\s*d(?:ays?)?${TIME}$`, 'i'), (m) => `FREQ=DAILY;INTERVAL=${Number(m[1])};${at(m[2], m[3])}`],
+    [new RegExp(`^start-of-month${TIME}$`, 'i'), (m) => `FREQ=MONTHLY;BYMONTHDAY=1;${at(m[1], m[2])}`],
+    [new RegExp(`^end-of-month${TIME}$`, 'i'), (m) => `FREQ=MONTHLY;BYMONTHDAY=-1;${at(m[1], m[2])}`],
+    [new RegExp(`^last-business-day${TIME}$`, 'i'), (m) => `FREQ=MONTHLY;BYDAY=${DAYS.slice(0, 5).join(',')};BYSETPOS=-1;${at(m[1], m[2])}`],
+    [new RegExp(`^end-of-quarter${TIME}$`, 'i'), (m) => `FREQ=MONTHLY;BYMONTH=3,6,9,12;BYMONTHDAY=-1;${at(m[1], m[2])}`],
+    [new RegExp(`^start-of-year${TIME}$`, 'i'), (m) => `FREQ=YEARLY;BYMONTH=1;BYMONTHDAY=1;${at(m[1], m[2])}`]
+];
+/** A shorthand's RRULE, a bare RRULE as given, or an error naming what was not understood. */
+export function expandShorthand(text) {
+    const trimmed = text.trim();
+    const bare = trimmed.replace(/^RRULE:/i, '');
+    if (/(?:^|;)FREQ=/i.test(bare))
+        return bare;
+    for (const [pattern, build] of SHORTHANDS) {
+        const m = pattern.exec(trimmed);
+        if (m)
+            return build(m);
+    }
+    throw new Error(`Unknown schedule "${text}": use an RRULE (FREQ=…) or one of hourly, daily HH:MM, weekly MO HH:MM, every Nm / Nh / Nd, start-of-month, end-of-month, last-business-day, end-of-quarter, start-of-year`);
+}
+/** The same wall-clock reading, as an instant in UTC: the frame recurrence is computed in. */
+function toWallUtc(instant, timeZone) {
+    return Temporal.Instant.fromEpochMilliseconds(instant.getTime())
+        .toZonedDateTimeISO(timeZone)
+        .toPlainDateTime()
+        .toZonedDateTime('UTC');
+}
+/** A wall-clock reading placed in the time zone; a skipped hour moves forward, a repeated one takes its first. */
+function fromWallUtc(wall, timeZone) {
+    const plain = Temporal.PlainDateTime.from(wall.toString().replace(/[+-]\d{2}:\d{2}\[UTC\]$|Z?\[UTC\]$/, ''));
+    return new Date(plain.toZonedDateTime(timeZone, { disambiguation: 'compatible' }).epochMilliseconds);
+}
+/**
+ * Compile a schedule. Throws, with a message a job author can act on, for an
+ * unknown shorthand, an invalid rule, an unknown time zone, `FREQ=SECONDLY`,
+ * an `RSCALE` other than GREGORIAN, or slots closer than the minimum interval.
+ */
+export function parseSchedule(input, options) {
+    const spec = typeof input === 'string' ? { rrule: input } : input;
+    const rrule = expandShorthand(spec.rrule);
+    const timeZone = spec.tz ?? options.defaultTimeZone;
+    const dtstart = spec.dtstart ?? DEFAULT_DTSTART;
+    const minIntervalMs = options.minIntervalMs ?? 60_000;
+    if (/(^|;)FREQ=SECONDLY(;|$)/i.test(rrule))
+        throw new Error(`Schedule "${spec.rrule}": FREQ=SECONDLY is not allowed`);
+    const rscale = /(?:^|;)RSCALE=([^;]+)/i.exec(rrule);
+    if (rscale && rscale[1].toUpperCase() !== 'GREGORIAN')
+        throw new Error(`Schedule "${spec.rrule}": RSCALE=${rscale[1]} is not supported`);
+    try {
+        Temporal.Now.instant().toZonedDateTimeISO(timeZone);
+    }
+    catch (err) {
+        throw new Error(`Schedule "${spec.rrule}": unknown time zone "${timeZone}"`, { cause: err });
+    }
+    let start;
+    try {
+        start = Temporal.PlainDateTime.from(dtstart).toZonedDateTime('UTC');
+    }
+    catch (err) {
+        throw new Error(`Schedule "${spec.rrule}": dtstart "${dtstart}" is not a wall-clock date-time (YYYY-MM-DDTHH:MM:SS)`, { cause: err });
+    }
+    let rule;
+    try {
+        rule = new RRuleTemporal({ rruleString: rrule, dtstart: start });
+    }
+    catch (err) {
+        throw new Error(`Schedule "${spec.rrule}": ${err.message}`, { cause: err });
+    }
+    const schedule = {
+        rrule,
+        dtstart,
+        timeZone,
+        nextSlot(after) {
+            // Ask in the wall-clock frame, then place the answer in the zone. A slot
+            // that lands at or before `after` once placed (the repeated hour) is
+            // passed over.
+            let from = toWallUtc(after, timeZone);
+            for (let guard = 0; guard < 4; guard++) {
+                const next = rule.next(from, false);
+                if (!next)
+                    return null;
+                const slot = fromWallUtc(next, timeZone);
+                if (slot.getTime() > after.getTime())
+                    return slot;
+                from = Temporal.ZonedDateTime.from(next.toString());
+            }
+            return null;
+        },
+        slotsBetween(from, to) {
+            if (to.getTime() < from.getTime())
+                return [];
+            // Widen by a day so slots moved across the edge by daylight saving are
+            // seen, then keep the ones whose instant is in range.
+            const day = 24 * 60 * 60 * 1000;
+            const hits = rule.between(new Date(toWallUtc(new Date(from.getTime() - day), timeZone).epochMilliseconds), new Date(toWallUtc(new Date(to.getTime() + day), timeZone).epochMilliseconds), true);
+            const seen = new Set();
+            const out = [];
+            for (const hit of hits) {
+                const slot = fromWallUtc(hit, timeZone);
+                const t = slot.getTime();
+                if (t < from.getTime() || t > to.getTime() || seen.has(t))
+                    continue;
+                seen.add(t);
+                out.push(slot);
+            }
+            return out;
+        }
+    };
+    // The minimum interval, measured on the rule's first slots from its start.
+    let previous = schedule.nextSlot(new Date(fromWallUtc(start, timeZone).getTime() - 1));
+    for (let i = 0; previous && i < 48; i++) {
+        const next = schedule.nextSlot(previous);
+        if (!next)
+            break;
+        if (next.getTime() - previous.getTime() < minIntervalMs) {
+            throw new Error(`Schedule "${spec.rrule}": slots ${Math.round((next.getTime() - previous.getTime()) / 1000)} s apart are closer than the minimum interval of ${Math.round(minIntervalMs / 1000)} s`);
+        }
+        previous = next;
+    }
+    return schedule;
+}

package/lib/src/utils/secretFileMode.js

@@ -0,0 +1,78 @@
+/**
+ * Files that hold secrets are owner-only (#1560).
+ *
+ * The user store (password hashes), the credentials store, the instance
+ * `.env` and backups were written with the process's default mode, which on
+ * most systems is world-readable (`-rw-r--r--`). They are written `0600` in
+ * `0700` directories now, and at boot an existing file is checked:
+ *
+ * - wider than `0600` — tightened, and said so;
+ * - owned by another account than the server runs as — the boot refuses,
+ *   naming both, since the server could neither secure nor safely trust it.
+ *
+ * No UID is configured anywhere: the mode is set on write, so the owner is
+ * whoever runs the server (a login, `node` in the image, the pod's user).
+ * Permissions keep out other local accounts and processes, not root; anyone
+ * with root, the disk or a backup is outside what they protect against —
+ * backup encryption, an optional setting still to be built (#1561), is for that.
+ */
+import fs from 'node:fs';
+export const SECRET_FILE_MODE = 0o600;
+export const SECRET_DIR_MODE = 0o700;
+/** The server's own UID, or null where the platform has none (Windows). */
+function ownUid() {
+    return typeof process.getuid === 'function' ? process.getuid() : null;
+}
+/**
+ * Check an existing secret file at boot. Missing is fine (it is created
+ * owner-only on first write). Returns a line to log when it was tightened.
+ * Throws, naming both UIDs, when another account owns it.
+ */
+export function secureExistingSecretFile(file) {
+    let st;
+    try {
+        st = fs.statSync(file);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+    const uid = ownUid();
+    if (uid !== null && st.uid !== uid) {
+        throw new Error(`Refusing to start: ${file} holds secrets and is owned by UID ${st.uid}, but the server runs as UID ${uid}. ` +
+            'Give it to the server\'s account (chown) or start the server as its owner (#1560).');
+    }
+    if ((st.mode & 0o077) === 0)
+        return null;
+    fs.chmodSync(file, SECRET_FILE_MODE);
+    return `🔐 Tightened ${file} from ${(st.mode & 0o777).toString(8)} to 600: it holds secrets (#1560)`;
+}
+/**
+ * Make a directory holding secrets owner-only, creating it when absent.
+ * Best effort on a filesystem that does not honour modes (an SMB share):
+ * returns a warning instead of failing, since refusing to write a backup
+ * over it would be worse than writing it with the share's permissions.
+ */
+export function ensureSecretDir(dir) {
+    fs.mkdirSync(dir, { recursive: true, mode: SECRET_DIR_MODE });
+    try {
+        const st = fs.statSync(dir);
+        if ((st.mode & 0o077) !== 0)
+            fs.chmodSync(dir, SECRET_DIR_MODE);
+        return null;
+    }
+    catch (err) {
+        return `Could not make ${dir} owner-only (${err.message}); its filesystem may not support permissions (#1560)`;
+    }
+}
+/** After writing a secret file directly (not through writeFileAtomic's mode), make it owner-only. */
+export function chmodSecretFile(file) {
+    try {
+        fs.chmodSync(file, SECRET_FILE_MODE);
+        return null;
+    }
+    catch (err) {
+        return `Could not make ${file} owner-only (${err.message}); its filesystem may not support permissions (#1560)`;
+    }
+}

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

@@ -1,12 +1,8 @@
+import type { SiteRestoreStaging, StagedRestoreAtStart, StagedSwap } from '../managers/BaseManager.js';
 /** 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;
@@ -48,6 +44,12 @@ export declare function readSiteRestore(file: string): SiteRestoreManifest | nul
 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 site restore being staged, as one manager's `restore()` gets it
+ * (`ManagerRestoreOptions.siteRestore`, #1986): its part is recorded under
+ * that manager's name, so a manager records its own part and no other.
+ */
+export declare function stagingFor(file: string, manager: string): SiteRestoreStaging;
 /** The commit: every part is staged. */
 export declare function commitSiteRestore(file: string): SiteRestoreManifest;
 /**
@@ -80,27 +82,22 @@ export declare function gatePart(file: string, manager: string): PartGate;
  * 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.
+ * `put` puts one swap in place instead of the rename, for a part whose live
+ * path is not one file or folder of its own (the audit files share the log
+ * folder): it moves the live content to `kept` and the staged one in, and
+ * throws to refuse. 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;
+    put?: (swap: StagedSwap, kept: string) => void;
+}): StagedRestoreAtStart | 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

package/lib/src/utils/siteRestore.js

@@ -36,6 +36,14 @@
  *
  * Everything here is synchronous file renames on the owner's own paths: it
  * runs once at start, before the owner serves anything.
+ *
+ * __BackupManager's own__ (#1986): only BackupManager and the backup
+ * internals (`directoryBackup.ts`, and `instanceEnvBackup.ts`, which applies
+ * the staged `.env` at the very start of the process, before BackupManager
+ * can be loaded) import this module, enforced by `npm run lint:backup`. A
+ * manager or provider records its part through the `siteRestore` restore
+ * option and applies it at start through BackupManager's
+ * `applyStagedPartAtStart` / `siteRestorePartAtStart`.
  */
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
@@ -92,6 +100,17 @@ export function recordStagedPart(file, part) {
     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 site restore being staged, as one manager's `restore()` gets it
+ * (`ManagerRestoreOptions.siteRestore`, #1986): its part is recorded under
+ * that manager's name, so a manager records its own part and no other.
+ */
+export function stagingFor(file, manager) {
+    return {
+        stagedPathFor,
+        record: (swaps, options) => recordStagedPart(file, { manager, swaps, ...(options?.discard ? { discard: options.discard } : {}) })
+    };
+}
 /** The commit: every part is staged. */
 export function commitSiteRestore(file) {
     const manifest = readSiteRestore(file);
@@ -218,7 +237,10 @@ export function markPart(file, manager, status, note) {
  * 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.
+ * `put` puts one swap in place instead of the rename, for a part whose live
+ * path is not one file or folder of its own (the audit files share the log
+ * folder): it moves the live content to `kept` and the staged one in, and
+ * throws to refuse. Returns null when there was nothing to do.
  */
 export function applyPartAtStart(file, manager, options) {
     const gate = gatePart(file, manager);
@@ -252,11 +274,16 @@ export function applyPartAtStart(file, manager, options) {
     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);
+            if (options.put) {
+                options.put(swap, kept);
+            }
+            else {
+                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 });
         }
     }

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

@@ -16,6 +16,8 @@ export interface TreeArchiveOutcome {
  * Every other error (EACCES, EIO, …) is a real failure and still fails.
  */
 export declare function vanishedDuringBackup(err: unknown): boolean;
+/** The log's note of entries deleted while they were backed up (#1563): skipped, not a failure. */
+export declare function vanishedNote(vanished: string[]): string;
 type TreeArchiveOptions = {
     entries?: string[];
     exclude?: (relative: string) => boolean;

package/lib/src/utils/treeArchive.js

@@ -0,0 +1,242 @@
+/**
+ * A folder of a site's files as one `.tar` beside a backup document, and back
+ * (#1876).
+ *
+ * The backup document is JSON built in memory, so file contents never go in
+ * it: a manager whose data is files (attachments, role and person records,
+ * footnotes, comments) writes them here instead, as `<stem>.<part>.tar`
+ * beside the document, the way DatabaseManager writes `<stem>.<name>.db`.
+ * BackupManager prunes and downloads these with the document.
+ *
+ * - __Streamed__ both ways: each file is read from disk as the archive is
+ *   written, and written to disk as it is read, so a file's size never
+ *   becomes memory.
+ * - __Bytes as stored__: nothing is decoded, so a sealed vault file stays the
+ *   sealed bytes it is on disk.
+ * - __Only files and folders__: a symbolic link or any other kind of entry is
+ *   left out of a backup, and named; one in an archive refuses the extract.
+ * - __Paths are data__: an extract refuses an entry that is absolute or
+ *   climbs out of its folder (`strict`), never writing outside `dest`.
+ * - __Encrypted under the backup key__ when one is given (#1561, #1876): the
+ *   archive is streamed through `backupCrypto.ts` as it is written, and an
+ *   extract or a listing given the key decrypts it as it reads. One that is
+ *   encrypted is never read without the key, one made under another key is
+ *   refused by its fingerprint, and given a key a plain archive is refused:
+ *   it is not the one the backup wrote.
+ */
+import { createReadStream, createWriteStream, existsSync, mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { create as createTar, extract as extractTar, list as listTar } from 'tar';
+import { decryptBuffer, decryptStream, encryptBuffer, encryptStream, fileIsEncrypted } from './backupCrypto.js';
+import { BACKUP_KEY_ENV } from './backupKey.js';
+/**
+ * Whether a backup's read failed because the entry it was reading was
+ * deleted meanwhile (#1563): a page, a version folder or a file removed
+ * while the backup walked past it. That entry is skipped and counted, never
+ * a failed backup — the site keeps running while it is backed up (#1213).
+ * Every other error (EACCES, EIO, …) is a real failure and still fails.
+ */
+export function vanishedDuringBackup(err) {
+    return err?.code === 'ENOENT';
+}
+/** The log's note of entries deleted while they were backed up (#1563): skipped, not a failure. */
+export function vanishedNote(vanished) {
+    return vanished.length > 0 ? `; ${vanished.length} entr${vanished.length === 1 ? 'y' : 'ies'} deleted during the backup skipped (${vanished.slice(0, 5).join(', ')})` : '';
+}
+/** Two 512-byte zero blocks: a tar with no entries. */
+const EMPTY_TAR = Buffer.alloc(1024);
+/**
+ * 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.
+ *
+ * An entry deleted while the archive is written (#1563) — the tar stream
+ * stops at the first file it can no longer find — is not a failure: the
+ * archive is written again from a fresh listing, without it, and the entry
+ * is named in `vanished`. It is written again only while each attempt finds
+ * another entry gone, so it ends once the deleting stops; the same entry
+ * missing twice, or one still there, is a real failure.
+ */
+export async function writeTreeArchive(target, root, options = {}) {
+    if (existsSync(target))
+        throw new Error(`${path.basename(target)} already exists; a backup never overwrites one`);
+    const vanished = new Set();
+    for (;;) {
+        try {
+            const outcome = await writeTreeArchiveOnce(target, root, options);
+            return { ...outcome, vanished: [...vanished].map((p) => toPosix(path.relative(root, p))).sort() };
+        }
+        catch (err) {
+            const gone = err.path;
+            if (!vanishedDuringBackup(err) || !gone || vanished.has(gone) || existsSync(gone))
+                throw err;
+            vanished.add(gone);
+        }
+    }
+}
+async function writeTreeArchiveOnce(target, root, options) {
+    const outcome = { files: 0, bytes: 0, skipped: [] };
+    const entries = (options.entries ?? (existsSync(root) ? readdirSync(root) : []))
+        .filter((e) => existsSync(path.join(root, e)))
+        .filter((e) => !options.exclude?.(toPosix(e)))
+        .sort();
+    if (entries.length === 0) {
+        writeFileSync(target, options.backupKey ? await encryptBuffer(EMPTY_TAR, options.backupKey) : EMPTY_TAR, { mode: 0o600, flag: 'wx' });
+        return outcome;
+    }
+    try {
+        const tarOptions = {
+            cwd: root,
+            portable: true,
+            filter: (p, stat) => {
+                const relative = toPosix(path.normalize(p));
+                if (options.exclude?.(relative))
+                    return false;
+                const s = stat;
+                if (s.isDirectory())
+                    return true;
+                if (!s.isFile()) {
+                    outcome.skipped.push(relative);
+                    return false;
+                }
+                outcome.files++;
+                outcome.bytes += s.size;
+                return true;
+            }
+        };
+        if (options.backupKey) {
+            const pack = createTar(tarOptions, entries);
+            await pipeline(pack, encryptStream(options.backupKey), createWriteStream(target, { flags: 'wx', mode: 0o600 }));
+        }
+        else {
+            await createTar({ ...tarOptions, file: target, mode: 0o600 }, entries);
+        }
+    }
+    catch (err) {
+        rmSync(target, { force: true });
+        throw err;
+    }
+    return outcome;
+}
+/**
+ * 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 async function extractTreeArchive(archive, dest, options = {}) {
+    if (!existsSync(archive) || !statSync(archive).isFile())
+        throw new Error(`${path.basename(archive)} is missing`);
+    const source = await openArchive(archive, options.backupKey);
+    rmSync(dest, { recursive: true, force: true });
+    mkdirSync(dest, { recursive: true });
+    // An archive of an empty folder is only its end blocks, which a strict read refuses.
+    if (source.empty)
+        return { files: 0, bytes: 0 };
+    const refused = [];
+    let files = 0;
+    let bytes = 0;
+    try {
+        const unpackOptions = {
+            cwd: dest,
+            strict: true,
+            preservePaths: false,
+            preserveOwner: false,
+            ...(options.strip ? { strip: options.strip } : {}),
+            filter: (p, entry) => {
+                const e = entry;
+                const relative = toPosix(p).replace(/^\.\//, '');
+                if (options.select && !options.select(relative))
+                    return false;
+                if (!['File', 'OldFile', 'ContiguousFile', 'Directory'].includes(e.type)) {
+                    refused.push(`${relative} (${e.type})`);
+                    return false;
+                }
+                if (e.type !== 'Directory') {
+                    files++;
+                    bytes += e.size ?? 0;
+                }
+                return true;
+            }
+        };
+        if (source.into)
+            await source.into(extractTar(unpackOptions));
+        else
+            await extractTar({ ...unpackOptions, file: archive });
+    }
+    catch (err) {
+        rmSync(dest, { recursive: true, force: true });
+        throw new Error(`${path.basename(archive)} could not be read: ${err.message}`, { cause: err });
+    }
+    if (refused.length > 0) {
+        rmSync(dest, { recursive: true, force: true });
+        throw new Error(`${path.basename(archive)} holds entries that are not files or folders: ${refused.slice(0, 5).join(', ')}`);
+    }
+    return { files, bytes };
+}
+/** An encrypted archive this small is decrypted whole, to recognise an empty one; anything larger streams. */
+const SMALL_ENCRYPTED = 64 * 1024;
+/**
+ * How to read an archive: plain (`stream` absent, tar reads the file), or
+ * decrypted as a stream. `empty` when it holds no entry at all. Throws for an
+ * encrypted archive with no key or another key, before anything is written.
+ */
+async function openArchive(archive, backupKey) {
+    const name = path.basename(archive);
+    if (!(await fileIsEncrypted(archive))) {
+        // A backup that says its archive is encrypted never takes a plain one in its place.
+        if (backupKey)
+            throw new Error(`${name} is not encrypted, but the backup says it is: it was replaced or damaged`);
+        const empty = statSync(archive).size === EMPTY_TAR.length && (await readHead(archive, EMPTY_TAR.length)).equals(EMPTY_TAR);
+        return { empty };
+    }
+    if (!backupKey)
+        throw new Error(`${name} is encrypted under a backup key, and none was given to read it (${BACKUP_KEY_ENV} is not set, or the backup does not say the archive is encrypted)`);
+    if (statSync(archive).size <= SMALL_ENCRYPTED) {
+        let plain;
+        try {
+            plain = await decryptBuffer(await readHead(archive, SMALL_ENCRYPTED), backupKey);
+        }
+        catch (err) {
+            throw new Error(`${name} could not be read: ${err.message}`, { cause: err });
+        }
+        if (plain.length === EMPTY_TAR.length && plain.equals(EMPTY_TAR))
+            return { empty: true };
+        return { empty: false, into: (sink) => pipeline(Readable.from([plain]), sink) };
+    }
+    // The decrypting stream checks the header (a wrong key is refused) before it passes on any byte.
+    return { empty: false, into: (sink) => pipeline(createReadStream(archive), decryptStream(backupKey), sink) };
+}
+/**
+ * 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 async function listTreeArchive(archive, onEntry, options = {}) {
+    if (!existsSync(archive) || !statSync(archive).isFile())
+        throw new Error(`${path.basename(archive)} is missing`);
+    const source = await openArchive(archive, options.backupKey);
+    if (source.empty)
+        return;
+    const listOptions = { onReadEntry: (e) => onEntry({ path: e.path, type: e.type }) };
+    if (source.into)
+        await source.into(listTar(listOptions));
+    else
+        await listTar({ ...listOptions, file: archive });
+}
+/** The first `n` bytes of a file, read without reading the rest. */
+export async function readHead(file, n) {
+    const chunks = [];
+    let total = 0;
+    if (n <= 0)
+        return Buffer.alloc(0);
+    for await (const chunk of createReadStream(file, { start: 0, end: n - 1 })) {
+        chunks.push(chunk);
+        total += chunk.length;
+    }
+    return Buffer.concat(chunks, total);
+}
+function toPosix(p) {
+    return p.split(path.sep).join('/');
+}