@jwilleke/ngdpbase-types 5.24.0 → 5.26.0

package/lib/src/utils/instanceEnvSecret.js

@@ -0,0 +1,79 @@
+/**
+ * A secret that must be defined in the instance `.env`, generated once when
+ * nothing supplies it (#1194, generalised for #1524).
+ *
+ * The session secret was the first; the credentials-store key is the second.
+ * Both follow one rule, so it is written once:
+ *
+ * 1. Set in the environment — use it, write nothing.
+ * 2. Blank in the environment, but the instance `.env` has a usable line — use
+ *    that (a launcher passing `NAME=` empty would otherwise regenerate on every
+ *    boot).
+ * 3. Otherwise generate, append one commented line to `<instanceDataDir>/.env`
+ *    (created `0600` when new), and use it.
+ *
+ * The repo-root `.env` is never written: it is shared by every instance that
+ * launches from the checkout.
+ */
+import fs from 'fs';
+import path from 'path';
+import { randomBytes } from 'crypto';
+export function ensureInstanceEnvSecret(spec, env, instanceDataDir, fs) {
+    const accept = spec.accept ?? ((v) => v);
+    const ambient = (env[spec.name] ?? '').trim();
+    if (ambient !== '')
+        return { secret: accept(ambient), origin: { kind: 'env' } };
+    const envPath = `${instanceDataDir.replace(/\/+$/, '')}/.env`;
+    const existing = fs.readFile(envPath);
+    if (existing !== null) {
+        const fromFile = readEnvLine(existing, spec.name);
+        if (fromFile !== null)
+            return { secret: accept(fromFile), origin: { kind: 'instance-env-file', path: envPath } };
+    }
+    const secret = fs.randomSecret();
+    const needsLeadingNewline = existing !== null && existing !== '' && !existing.endsWith('\n');
+    const line = (needsLeadingNewline ? '\n' : '') + `# ${spec.comment}\n${spec.name}=${secret}\n`;
+    try {
+        fs.appendFile(envPath, line, 0o600);
+    }
+    catch (err) {
+        throw spec.refusal(envPath, err);
+    }
+    return { secret, origin: { kind: 'generated', path: envPath } };
+}
+/** The last `NAME=` line in a dotenv file, unquoted; null when absent or blank. */
+export function readEnvLine(content, name) {
+    const pattern = new RegExp(`^\\s*(?:export\\s+)?${name}\\s*=\\s*(.*)$`);
+    let found = null;
+    for (const raw of content.split('\n')) {
+        const m = raw.match(pattern);
+        if (!m)
+            continue;
+        let value = m[1].trim();
+        const quoted = value.match(/^(['"])(.*)\1$/);
+        if (quoted)
+            value = quoted[2];
+        else
+            value = value.replace(/\s+#.*$/, '').trim();
+        found = value;
+    }
+    return found === '' ? null : found;
+}
+/** The real filesystem behind every generated `.env` secret. */
+export const nodeInstanceEnvFs = {
+    readFile: (p) => {
+        try {
+            return fs.readFileSync(p, 'utf8');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return null;
+            throw err;
+        }
+    },
+    appendFile: (p, line, mode) => {
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.appendFileSync(p, line, { mode });
+    },
+    randomSecret: () => randomBytes(32).toString('base64')
+};

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;