aicodeman 1.42.0 → 1.44.0

package/dist/config-backup.js

@@ -0,0 +1,794 @@
+/**
+ * @fileoverview Config backups: timestamped snapshots of the files that hold what a user has
+ * customized, kept in a default-but-configurable folder with configurable retention.
+ *
+ * Why it exists: those files are plain JSON in the data dir, rewritten by the server, the Settings UI,
+ * the CLI and (once, by a mis-configured test run) by things that should never touch them, and there
+ * was no copy to go back to. A snapshot is taken at startup and whenever the tracked files' content
+ * changes, so the history is one entry per actual change rather than one per timer tick.
+ *
+ * Safety rules the code enforces rather than documents:
+ * - The tracked file list is a fixed allowlist, never "everything in the data dir".
+ * - Retention only ever deletes folders this module made (name pattern AND a parseable manifest), so
+ *   pointing the backup folder at a directory that holds other things cannot delete them.
+ * - The newest snapshot is never pruned, whatever the retention numbers say.
+ * - A snapshot is built in a temp folder and renamed into place, so a crash leaves no half snapshot.
+ * - Restore verifies each file against the manifest's SHA-256 and takes a `pre-restore` snapshot first.
+ * - Snapshot folders are 0700 and their files 0600: some tracked files carry credentials.
+ *
+ * Pure of the server: every function takes the directories it works in.
+ *
+ * @module config-backup
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { chmodSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve, sep } from 'node:path';
+/**
+ * The files (relative to the data dir) a snapshot holds: what a user configured, not what the server
+ * regenerates (session state, logs, the hook secret, docker seeds, caches).
+ *
+ * ⚠️ Not tracked: `state.json`. It also holds cron jobs and respawn presets, but it is rewritten with
+ * every session event, so tracking it would make a snapshot per event and bury the real changes.
+ *
+ * ⚠️ `.env`, `users.json`, `custom-model-hosts.json` and `push-keys.json` carry credentials or keys.
+ * They are already in the data dir with the same permissions; a snapshot folder is 0700 with 0600
+ * files, so the default location widens nothing. A custom location is the user's own choice.
+ */
+export const CONFIG_BACKUP_FILES = [
+    'settings.json',
+    'clis.json',
+    'custom-model-hosts.json',
+    'webhook.json',
+    'intents.json',
+    'linked-cases.json',
+    'remote-hosts.json',
+    'remote-cases.json',
+    'docker-hosts.json',
+    'docker-cases.json',
+    'webviews.json',
+    'push-keys.json',
+    'users.json',
+    '.env',
+];
+export const CONFIG_BACKUP_DEFAULTS = { enabled: true, keepCount: 20, keepDays: 30 };
+/** 1 would delete the state before every change, so a bad write could never be undone. */
+export const CONFIG_BACKUP_MIN_KEEP_COUNT = 2;
+export const CONFIG_BACKUP_MAX_KEEP_COUNT = 500;
+export const CONFIG_BACKUP_MAX_KEEP_DAYS = 3650;
+/** `cfg-YYYYMMDD-HHMMSS`, plus `-2`, `-3`… if two land in one second. */
+const SNAPSHOT_ID_RE = /^cfg-\d{8}-\d{6}(?:-\d{1,3})?$/;
+const MANIFEST = 'manifest.json';
+const intIn = (value, min, max, fallback) => {
+    const n = typeof value === 'number' ? value : typeof value === 'string' && value.trim() ? Number(value) : NaN;
+    if (!Number.isFinite(n))
+        return fallback;
+    return Math.min(max, Math.max(min, Math.floor(n)));
+};
+/** `~`-expand and require an absolute path; anything else means "use the default". */
+export function normalizeBackupDir(raw, home = homedir()) {
+    if (typeof raw !== 'string')
+        return null;
+    let value = raw.trim();
+    if (!value || value.includes('\0'))
+        return null;
+    if (value === '~')
+        value = home;
+    else if (value.startsWith('~/'))
+        value = join(home, value.slice(2));
+    if (!isAbsolute(value))
+        return null;
+    return resolve(value);
+}
+/** Read the four `configBackup*` settings out of a settings.json object, clamped and defaulted. */
+export function readConfigBackupSettings(raw) {
+    const s = raw ?? {};
+    return {
+        // Absent means ON: the feature protects against an event nobody schedules.
+        enabled: s.configBackupEnabled !== false,
+        dir: normalizeBackupDir(s.configBackupDir),
+        keepCount: intIn(s.configBackupKeepCount, CONFIG_BACKUP_MIN_KEEP_COUNT, CONFIG_BACKUP_MAX_KEEP_COUNT, CONFIG_BACKUP_DEFAULTS.keepCount),
+        keepDays: intIn(s.configBackupKeepDays, 0, CONFIG_BACKUP_MAX_KEEP_DAYS, CONFIG_BACKUP_DEFAULTS.keepDays),
+    };
+}
+export function defaultConfigBackupDir(dataDir) {
+    return join(dataDir, 'backups', 'config');
+}
+/**
+ * The folder snapshots go to: the configured one, or the default. A custom folder that IS the data dir
+ * falls back to the default, because snapshot folders and the live files must not share a directory.
+ */
+export function resolveConfigBackupDir(settings, dataDir) {
+    const fallback = defaultConfigBackupDir(dataDir);
+    const dir = settings.dir;
+    if (!dir)
+        return fallback;
+    const data = resolve(dataDir);
+    if (dir === data)
+        return fallback;
+    return dir;
+}
+const ORIGIN_FILE = 'config-backup-id';
+const ORIGIN_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/**
+ * Who owns a snapshot: a random id made once and kept in the data dir. A hostname would not do (a
+ * Docker container gets a new one on every recreate, which orphaned every earlier snapshot), nor
+ * would the path alone (two machines can share a `$HOME` path). It is a file of its own, not the
+ * hook secret, and is not tracked or restored. If it cannot be written the id is not persisted, so
+ * snapshots made meanwhile are not listed later; the data dir being unwritable breaks far more.
+ */
+export function configBackupOrigin(dataDir) {
+    const path = join(dataDir, ORIGIN_FILE);
+    try {
+        const existing = readFileSync(path, 'utf8').trim();
+        if (ORIGIN_RE.test(existing))
+            return existing;
+    }
+    catch {
+        /* missing: made below */
+    }
+    const id = randomUUID();
+    try {
+        mkdirSync(dataDir, { recursive: true });
+        writeFileSync(path, id + '\n', { mode: 0o600 });
+    }
+    catch {
+        /* see above */
+    }
+    return id;
+}
+/** The id already made for this data dir, or null. Read-only: listing must not write a file. */
+export function readConfigBackupOrigin(dataDir) {
+    try {
+        const existing = readFileSync(join(dataDir, ORIGIN_FILE), 'utf8').trim();
+        return ORIGIN_RE.test(existing) ? existing : null;
+    }
+    catch {
+        return null;
+    }
+}
+const sha256 = (data) => createHash('sha256').update(data).digest('hex');
+/**
+ * Keys a tracked file rewrites on its own schedule, with no change to anything the user set, so
+ * they must not make a snapshot look different. `custom-model-hosts.json` carries a
+ * `lastDiscoveredAt` per host that the model-discovery poll refreshes every 5 minutes: before this,
+ * the change check never matched and the snapshot folder filled with copies that differed by one
+ * timestamp, evicting every older snapshot within about 100 minutes at the default keep count.
+ * The snapshot itself still stores the file exactly as it was, and restore still verifies against
+ * the file's own digest; only the "has anything changed?" comparison looks through these keys.
+ */
+const VOLATILE_KEYS = {
+    'custom-model-hosts.json': ['lastDiscoveredAt'],
+    // Rewritten by activity, not by anything the user set: a Basic-auth login (at most once a minute
+    // per user), a session started in another case, every captured prompt, and a Docker case's
+    // conversation id after a /clear, and a web tab being opened.
+    'users.json': ['lastLoginAt'],
+    'settings.json': ['lastUsedCase'],
+    'intents.json': ['recentPrompts', 'updatedAt'],
+    'docker-cases.json': ['lastClaudeSessionId'],
+    'webviews.json': ['lastOpenedAt'],
+};
+function withoutKeys(value, drop) {
+    if (Array.isArray(value))
+        return value.map((v) => withoutKeys(v, drop));
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (!drop.has(k))
+                out[k] = withoutKeys(v, drop);
+        }
+        return out;
+    }
+    return value;
+}
+/** Digest used only to decide whether two states are the same: the file's own, minus its volatile keys. */
+function changeDigest(name, data, rawSha) {
+    const volatile = VOLATILE_KEYS[name];
+    if (!volatile)
+        return rawSha;
+    try {
+        return sha256(JSON.stringify(withoutKeys(JSON.parse(data.toString('utf8')), new Set(volatile))));
+    }
+    catch {
+        return rawSha; // not JSON (or unreadable as such): compare the bytes, as for any other file
+    }
+}
+function stamp(now) {
+    const d = new Date(now);
+    const p = (n, w = 2) => String(n).padStart(w, '0');
+    return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+}
+function readManifest(dir, id, origin) {
+    if (!SNAPSHOT_ID_RE.test(id))
+        return null;
+    try {
+        const m = JSON.parse(readFileSync(join(dir, id, MANIFEST), 'utf8'));
+        if (!m || m.id !== id || !Array.isArray(m.files) || typeof m.createdAt !== 'number' || typeof m.hash !== 'string') {
+            return null;
+        }
+        if (origin !== undefined && m.origin !== origin)
+            return null;
+        return m;
+    }
+    catch {
+        return null;
+    }
+}
+/** A folder's entry names; none when it cannot be read (absent, or not a folder). */
+function folderEntries(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * The manifests of the snapshots this module made among `names` in `dir`, newest first. Foreign
+ * folders and files are ignored, and so are other instances' snapshots when `origin` is given (see
+ * {@link configBackupOrigin}). Each one is a file read, so a pass does this once and passes the
+ * result on (see {@link runConfigBackupPass}).
+ */
+function manifestsIn(dir, names, origin) {
+    const out = [];
+    for (const id of names) {
+        const m = readManifest(dir, id, origin);
+        if (m)
+            out.push(m);
+    }
+    return out.sort((a, b) => b.createdAt - a.createdAt || (a.id < b.id ? 1 : -1));
+}
+/**
+ * Snapshots this module made in `dir`, newest first. Foreign folders and files are ignored, and so
+ * are other instances' snapshots when `origin` is given (see {@link configBackupOrigin}).
+ */
+export function listConfigBackups(dir, origin) {
+    return manifestsIn(dir, folderEntries(dir), origin).map((m) => {
+        const files = m.files.map((f) => ({ name: f.name, bytes: f.bytes }));
+        return {
+            id: m.id,
+            createdAt: m.createdAt,
+            reason: m.reason,
+            appVersion: m.appVersion,
+            files,
+            bytes: files.reduce((n, f) => n + f.bytes, 0),
+        };
+    });
+}
+/** Snapshot the tracked files that exist, unless the latest snapshot already holds exactly this state. */
+export function createConfigBackup(opts) {
+    return snapshotConfig(opts).result;
+}
+/**
+ * {@link createConfigBackup}, also returning the manifest it wrote, over this instance's snapshots
+ * when the caller has already listed them (`listed`, newest first): one walk of the folder per pass.
+ */
+function snapshotConfig(opts, listed) {
+    const now = opts.now ?? Date.now();
+    const present = [];
+    for (const name of CONFIG_BACKUP_FILES) {
+        try {
+            const path = join(opts.dataDir, name);
+            if (!statSync(path).isFile())
+                continue;
+            const data = readFileSync(path);
+            const sha = sha256(data);
+            present.push({ name, data, sha, change: changeDigest(name, data, sha) });
+        }
+        catch {
+            /* absent or unreadable: simply not part of this snapshot */
+        }
+    }
+    if (present.length === 0)
+        return { result: { status: 'empty' }, manifest: null };
+    const hash = sha256(present.map((f) => `${f.name}\0${f.change}`).join('\n'));
+    const origin = listed?.origin ?? configBackupOrigin(opts.dataDir);
+    const existing = listed?.existing ?? manifestsIn(opts.backupDir, folderEntries(opts.backupDir), origin);
+    if (!opts.force && existing[0] && existing[0].hash === hash) {
+        return { result: { status: 'unchanged', id: existing[0].id }, manifest: null };
+    }
+    // Never dated earlier than this instance's newest snapshot. One written while the clock read ahead
+    // (a dual-boot machine, a VM resumed with a stale clock) would otherwise stay newest after the
+    // correction, differ from every later pass, and have each one write a copy until real time caught up.
+    const createdAt = existing[0] ? Math.max(now, existing[0].createdAt + 1) : now;
+    mkdirSync(opts.backupDir, { recursive: true, mode: 0o700 });
+    const base = `cfg-${stamp(createdAt)}`;
+    let id = base;
+    for (let n = 2; existsSync(join(opts.backupDir, id)); n++)
+        id = `${base}-${n}`;
+    const tmp = join(opts.backupDir, `.tmp-${id}-${process.pid}`);
+    rmSync(tmp, { recursive: true, force: true });
+    mkdirSync(tmp, { mode: 0o700 });
+    const manifest = {
+        id,
+        createdAt,
+        reason: opts.reason,
+        appVersion: opts.appVersion ?? '',
+        hash,
+        origin,
+        ...(opts.keepCount !== undefined && { keepCount: opts.keepCount }),
+        ...(opts.keepDays !== undefined && { keepDays: opts.keepDays }),
+        files: present.map((f) => ({ name: f.name, bytes: f.data.length, sha256: f.sha })),
+    };
+    try {
+        for (const f of present)
+            writeFileSync(join(tmp, f.name), f.data, { mode: 0o600 });
+        writeFileSync(join(tmp, MANIFEST), JSON.stringify(manifest, null, 2) + '\n', { mode: 0o600 });
+        renameSync(tmp, join(opts.backupDir, id));
+        try {
+            chmodSync(join(opts.backupDir, id), 0o700);
+        }
+        catch {
+            /* best effort on filesystems without modes */
+        }
+    }
+    catch (err) {
+        rmSync(tmp, { recursive: true, force: true });
+        throw err;
+    }
+    const bytes = present.reduce((n, f) => n + f.data.length, 0);
+    return { result: { status: 'created', id, files: present.length, bytes }, manifest };
+}
+/** Remove `.tmp-cfg-*` build folders a crashed snapshot left behind (older than an hour, so a live one on a shared folder is safe). */
+export function sweepConfigBackupTemps(dir, now = Date.now()) {
+    sweepTemps(dir, folderEntries(dir), now);
+}
+function sweepTemps(dir, names, now) {
+    for (const n of names) {
+        if (!/^\.tmp-cfg-\d{8}-\d{6}(?:-\d{1,3})?-\d+$/.test(n))
+            continue;
+        const st = lstatSync(join(dir, n), { throwIfNoEntry: false });
+        if (st && now - st.mtimeMs > 3_600_000)
+            rmSync(join(dir, n), { recursive: true, force: true });
+    }
+}
+/**
+ * The retention recorded in this instance's newest snapshot, or null when it recorded none. `listed`
+ * is this instance's manifests in `dir`, newest first, when the caller already read them.
+ */
+export function latestBackupRetention(dir, origin, listed) {
+    // The newest manifest that recorded one: a snapshot from before this field existed must not hide it.
+    for (const m of listed ?? manifestsIn(dir, folderEntries(dir), origin)) {
+        if (typeof m.keepCount === 'number' && typeof m.keepDays === 'number') {
+            return { keepCount: m.keepCount, keepDays: m.keepDays };
+        }
+    }
+    return null;
+}
+/**
+ * The settings in effect, with each retention key that `raw` (the parsed settings.json) lacks, as
+ * after a reset, taken from what the newest backup recorded in `dir` instead of the defaults. It
+ * looks at the retention keys only (not the folder), so re-entering a custom folder after a reset
+ * finds that folder's own manifests. One place for the timer pass and for what the GET route
+ * reports, so they cannot disagree.
+ */
+export function withRecordedRetention(settings, raw, dir, origin, listed) {
+    const lacksCount = !('configBackupKeepCount' in raw);
+    const lacksDays = !('configBackupKeepDays' in raw);
+    if ((!lacksCount && !lacksDays) || !origin)
+        return settings;
+    const kept = latestBackupRetention(dir, origin, listed);
+    if (!kept)
+        return settings;
+    return {
+        ...settings,
+        ...(lacksCount && { keepCount: kept.keepCount }),
+        ...(lacksDays && { keepDays: kept.keepDays }),
+    };
+}
+/**
+ * Apply retention: keep the newest `keepCount`, and (when `keepDays` > 0) drop anything older than
+ * that. The newest snapshot always survives. Returns the ids removed.
+ */
+export function pruneConfigBackups(dir, opts) {
+    return pruneListed(dir, manifestsIn(dir, folderEntries(dir), opts.origin), opts);
+}
+/** {@link pruneConfigBackups} over a listing already made (`all`, newest first). */
+function pruneListed(dir, all, opts) {
+    const now = opts.now ?? Date.now();
+    const cutoff = opts.keepDays > 0 ? now - opts.keepDays * 86_400_000 : null;
+    const removed = [];
+    all.forEach((b, index) => {
+        if (index === 0)
+            return;
+        const tooMany = index >= Math.max(1, opts.keepCount);
+        // A snapshot's state was live until the next one was made: age it from then. Aging by its own
+        // createdAt deleted the last good copy on the first change after a quiet month.
+        const tooOld = cutoff !== null && all[index - 1].createdAt < cutoff;
+        if (!tooMany && !tooOld)
+            return;
+        // The listing already proved this is one of ours (name pattern + manifest).
+        const target = join(dir, b.id);
+        if (!target.startsWith(resolve(dir) + sep))
+            return;
+        try {
+            rmSync(target, { recursive: true, force: true });
+            removed.push(b.id);
+        }
+        catch {
+            /* leave it; the next pass retries */
+        }
+    });
+    return removed;
+}
+/**
+ * One pass of the timer or of Back up now: sweep stale temp folders, snapshot when the state changed,
+ * apply retention. The folder is read and each manifest parsed ONCE, and that listing feeds the
+ * recorded-retention fallback, the change check and the prune. It used to be listed for each of the
+ * three, which on a network folder is every manifest read three times every five minutes.
+ */
+export function runConfigBackupPass(opts) {
+    const names = folderEntries(opts.backupDir);
+    sweepTemps(opts.backupDir, names, Date.now());
+    const origin = configBackupOrigin(opts.dataDir);
+    const existing = manifestsIn(opts.backupDir, names, origin);
+    // No retention in the file (reset, or unreadable): keep what the newest snapshot recorded.
+    const { keepCount, keepDays } = withRecordedRetention(opts.settings, opts.raw, opts.backupDir, origin, existing);
+    const { result, manifest } = snapshotConfig({
+        dataDir: opts.dataDir,
+        backupDir: opts.backupDir,
+        reason: opts.reason,
+        appVersion: opts.appVersion,
+        force: opts.force,
+        keepCount,
+        keepDays,
+        now: opts.now,
+    }, { origin, existing });
+    if (!opts.prune)
+        return { result, removed: [] };
+    // A snapshot made now is dated after existing[0], so it heads the listing retention counts.
+    const all = manifest ? [manifest, ...existing] : existing;
+    return { result, removed: pruneListed(opts.backupDir, all, { keepCount, keepDays, now: opts.now }) };
+}
+export class ConfigBackupNotFoundError extends Error {
+}
+export class ConfigBackupCorruptError extends Error {
+}
+/**
+ * A restore that wrote some files and could not write others (a full disk, a directory where a file
+ * should be). Every file passed verification first, so the ones written are the backup's: the caller
+ * still has to reload what they feed and tell the user which files are which.
+ */
+export class ConfigBackupPartialRestoreError extends Error {
+    restored;
+    failed;
+    untouched;
+    safetySnapshot;
+    constructor(restored, failed, untouched, safetySnapshot) {
+        const done = restored.length ? `${restored.join(', ')} restored` : 'nothing was restored';
+        const undo = safetySnapshot ? `; the files from before the restore are in backup ${safetySnapshot}` : '';
+        super(`Restore incomplete: could not write ${failed.map((f) => f.name).join(', ')} (${failed[0]?.error}); ${done}${undo}`);
+        this.restored = restored;
+        this.failed = failed;
+        this.untouched = untouched;
+        this.safetySnapshot = safetySnapshot;
+    }
+}
+/**
+ * Restore refuses what this module never writes. Snapshots are 0700/0600 real files, and a restore
+ * writes the file as 0600: a symlink, or a file with a group/world bit, was planted or loosened
+ * after the snapshot, and rewriting it as 0600 would turn it into trusted config (`clis.json`
+ * selects the binaries Codeman spawns; `isUnsafePermissions` refuses the same bits there).
+ * POSIX only, like `isUnsafePermissions`. The mode test is skipped (the symlink test is not) on a
+ * filesystem that does not keep modes, see {@link folderKeepsModes}.
+ */
+function assertTrustedSnapshotEntry(path, label, checkMode) {
+    if (process.platform === 'win32')
+        return;
+    const st = lstatSync(path, { throwIfNoEntry: false });
+    if (!st)
+        return; // missing is reported by the read that follows
+    if (st.isSymbolicLink())
+        throw new ConfigBackupCorruptError(`${label} is a symlink, so it is not used`);
+    if (checkMode && (st.mode & 0o077) !== 0) {
+        throw new ConfigBackupCorruptError(`${label} is readable or writable by group or others, so it is not used`);
+    }
+}
+/**
+ * Whether the backup folder's filesystem keeps a file's mode: vfat/exFAT, CIFS shares and WSL's
+ * `/mnt/d` report 0755 or 0777 for everything, so the group/world test would refuse every backup
+ * there even though snapshots succeed (`createConfigBackup` already expects mode-less filesystems).
+ * Probed with a 0600 temp file made with `wx` under a random name; if the probe cannot run, the
+ * strict test stays on.
+ */
+function folderKeepsModes(dir) {
+    if (process.platform === 'win32')
+        return false;
+    // A random name and 'wx' (fail if anything is there): a planted symlink or directory with a
+    // guessable name must neither be written through nor break the probe. Only a file this call
+    // created is removed.
+    const probe = join(dir, `.mode-probe-${randomUUID()}`);
+    let created = false;
+    try {
+        writeFileSync(probe, '', { mode: 0o600, flag: 'wx' });
+        created = true;
+        chmodSync(probe, 0o600);
+        return (lstatSync(probe).mode & 0o777 & 0o077) === 0;
+    }
+    catch {
+        return true;
+    }
+    finally {
+        if (created)
+            rmSync(probe, { force: true });
+    }
+}
+/** The folder's own backup settings stay as they are now: restoring an old `configBackupDir` hides the `pre-restore` copy. */
+const BACKUP_SETTING_KEYS = ['configBackupEnabled', 'configBackupDir', 'configBackupKeepCount', 'configBackupKeepDays'];
+function keepCurrentBackupSettings(snapshot, livePath) {
+    try {
+        const restored = JSON.parse(snapshot.toString('utf8'));
+        const live = JSON.parse(readFileSync(livePath, 'utf8'));
+        if (!restored || typeof restored !== 'object' || !live || typeof live !== 'object')
+            return snapshot;
+        let changed = false;
+        // A reset live file lacks the retention keys. Taking "absent" for them would bring the defaults
+        // back (20 copies, 30 days) on the next pass, so the backup's own retention stays.
+        for (const key of BACKUP_SETTING_KEYS) {
+            if (!(key in live) && (key === 'configBackupKeepCount' || key === 'configBackupKeepDays'))
+                continue;
+            if (JSON.stringify(restored[key]) === JSON.stringify(live[key]))
+                continue;
+            changed = true;
+            if (key in live)
+                restored[key] = live[key];
+            else
+                delete restored[key];
+        }
+        if (!changed)
+            return snapshot; // byte-identical to the snapshot when the folder settings did not move
+        return Buffer.from(JSON.stringify(restored, null, 2) + '\n');
+    }
+    catch {
+        return snapshot; // not JSON, or no live file to take the values from
+    }
+}
+/**
+ * Put a snapshot's files back into the data dir. Every file is checked against the manifest's digest
+ * BEFORE anything is written, a `pre-restore` snapshot of the live files is taken first (unless the
+ * newest backup already holds that state, which is then reported instead), and each file is replaced
+ * atomically (temp + rename) with mode 0600. A file that cannot be written does not stop the others;
+ * it throws {@link ConfigBackupPartialRestoreError} at the end, naming both lists.
+ */
+export function restoreConfigBackup(opts) {
+    const origin = readConfigBackupOrigin(opts.dataDir);
+    const manifest = origin ? readManifest(opts.backupDir, opts.id, origin) : null;
+    if (!manifest || !origin)
+        throw new ConfigBackupNotFoundError(`No config backup named ${opts.id}`);
+    const allowed = new Set(CONFIG_BACKUP_FILES);
+    const loaded = [];
+    const checkMode = opts.keepsModes ?? folderKeepsModes(opts.backupDir);
+    assertTrustedSnapshotEntry(join(opts.backupDir, opts.id), `Backup ${opts.id}`, checkMode);
+    for (const f of manifest.files) {
+        if (!allowed.has(f.name))
+            continue;
+        let data;
+        assertTrustedSnapshotEntry(join(opts.backupDir, opts.id, f.name), `${f.name} in ${opts.id}`, checkMode);
+        try {
+            data = readFileSync(join(opts.backupDir, opts.id, f.name));
+        }
+        catch {
+            throw new ConfigBackupCorruptError(`${f.name} is missing from ${opts.id}`);
+        }
+        if (sha256(data) !== f.sha256)
+            throw new ConfigBackupCorruptError(`${f.name} in ${opts.id} does not match its checksum`);
+        loaded.push({ name: f.name, data });
+    }
+    if (loaded.length === 0)
+        throw new ConfigBackupCorruptError(`${opts.id} holds no restorable files`);
+    // One walk of the folder serves both the recorded retention and the snapshot below.
+    const existing = manifestsIn(opts.backupDir, folderEntries(opts.backupDir), origin);
+    const { result: safety } = snapshotConfig({
+        dataDir: opts.dataDir,
+        backupDir: opts.backupDir,
+        reason: 'pre-restore',
+        appVersion: opts.appVersion,
+        // Not forced: when the live files equal the newest backup, that backup already is the undo copy,
+        // and a forced duplicate would spend a retention slot on nothing.
+        now: opts.now,
+        // The retention in force, so this newest snapshot does not hide it from the next pass.
+        ...(latestBackupRetention(opts.backupDir, origin, existing) ?? {}),
+    }, { origin, existing });
+    mkdirSync(opts.dataDir, { recursive: true });
+    const restored = [];
+    const failed = [];
+    for (const f of loaded) {
+        const target = join(opts.dataDir, f.name);
+        const tmp = `${target}.restore-${process.pid}`;
+        try {
+            writeFileSync(tmp, f.name === 'settings.json' ? keepCurrentBackupSettings(f.data, target) : f.data, {
+                mode: 0o600,
+            });
+            renameSync(tmp, target);
+            restored.push(f.name);
+        }
+        catch (err) {
+            try {
+                rmSync(tmp, { force: true });
+            }
+            catch {
+                /* the temp is a leftover at worst; the failure below is what matters */
+            }
+            // Keep going: each file is replaced on its own, and the files written before this one are the
+            // backup's already. Stopping here used to answer a bare 500 that named neither list.
+            failed.push({ name: f.name, error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    // A restore never deletes: tracked files the snapshot did not hold stay as they are.
+    const untouched = CONFIG_BACKUP_FILES.filter((n) => !restored.includes(n) &&
+        !failed.some((x) => x.name === n) &&
+        lstatSync(join(opts.dataDir, n), { throwIfNoEntry: false })?.isFile());
+    const safetySnapshot = safety.status === 'empty' ? null : safety.id;
+    if (failed.length)
+        throw new ConfigBackupPartialRestoreError(restored, failed, untouched, safetySnapshot);
+    return { restored, untouched, safetySnapshot };
+}
+/** The live files in the data dir, as a side of a diff. */
+export const CONFIG_DIFF_CURRENT = 'current';
+const MAX_DIFF_CHANGES = 200;
+const MAX_DIFF_VALUE_CHARS = 200;
+/** Files whose every value is a credential or key: only names are ever shown. */
+const REDACT_ALL_FILES = new Set([
+    '.env',
+    'users.json',
+    'push-keys.json',
+    'webhook.json',
+    'intents.json',
+]);
+/** Elsewhere a value is hidden when its own key looks like a credential. */
+const SECRET_KEY_RE = /(token|secret|passw|credential|auth|key$)/i;
+function flattenJson(value, path, out) {
+    if (Array.isArray(value) && value.length > 0) {
+        value.forEach((v, i) => flattenJson(v, `${path}[${i}]`, out));
+    }
+    else if (value && typeof value === 'object' && Object.keys(value).length > 0) {
+        for (const [k, v] of Object.entries(value)) {
+            flattenJson(v, path ? `${path}.${k}` : k, out);
+        }
+    }
+    else {
+        out.set(path || '(root)', JSON.stringify(value) ?? 'null');
+    }
+}
+function parseEnv(text) {
+    const out = new Map();
+    for (const line of text.split(/\r?\n/)) {
+        const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_.-]*)\s*=(.*)$/.exec(line);
+        if (m)
+            out.set(m[1], m[2].trim());
+    }
+    return out;
+}
+/** Per-key view of a tracked file, or null when it is not JSON/env text. */
+function leavesOf(name, data) {
+    const text = data.toString('utf8');
+    if (name === '.env')
+        return parseEnv(text);
+    try {
+        const parsed = JSON.parse(text);
+        const volatile = VOLATILE_KEYS[name];
+        const out = new Map();
+        flattenJson(volatile ? withoutKeys(parsed, new Set(volatile)) : parsed, '', out);
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
+/** A URL value loses its userinfo, query and fragment: they carry passwords and tokens. */
+function scrubUrl(jsonText) {
+    try {
+        const v = JSON.parse(jsonText);
+        if (typeof v !== 'string' || !/^[a-z][a-z0-9+.-]*:\/\//i.test(v))
+            return jsonText;
+        const u = new URL(v);
+        if (!u.username && !u.password && !u.search && !u.hash)
+            return jsonText;
+        return JSON.stringify(`${u.protocol}//${u.host}${u.pathname}`);
+    }
+    catch {
+        return jsonText;
+    }
+}
+const clip = (s) => (s.length > MAX_DIFF_VALUE_CHARS ? `${s.slice(0, MAX_DIFF_VALUE_CHARS)}…` : s);
+function diffLeaves(name, a, b) {
+    const all = REDACT_ALL_FILES.has(name);
+    const changes = [];
+    for (const path of [...new Set([...a.keys(), ...b.keys()])].sort()) {
+        const before = a.get(path);
+        const after = b.get(path);
+        if (before === after)
+            continue;
+        const kind = before === undefined ? 'added' : after === undefined ? 'removed' : 'changed';
+        if (all || SECRET_KEY_RE.test(path.split('.').pop() ?? '')) {
+            changes.push({ path, kind, redacted: true });
+        }
+        else {
+            changes.push({
+                path,
+                kind,
+                ...(before !== undefined && { before: clip(scrubUrl(before)) }),
+                ...(after !== undefined && { after: clip(scrubUrl(after)) }),
+            });
+        }
+    }
+    return { changes: changes.slice(0, MAX_DIFF_CHANGES), truncated: changes.length > MAX_DIFF_CHANGES };
+}
+/** The tracked files of one side, verified: a snapshot's against its manifest, the live ones as they are. */
+function loadDiffSide(side, dataDir, backupDir) {
+    const out = new Map();
+    if (side === CONFIG_DIFF_CURRENT) {
+        for (const name of CONFIG_BACKUP_FILES) {
+            try {
+                const path = join(dataDir, name);
+                if (statSync(path).isFile())
+                    out.set(name, readFileSync(path));
+            }
+            catch {
+                /* absent or unreadable: not part of this side */
+            }
+        }
+        return out;
+    }
+    const origin = readConfigBackupOrigin(dataDir);
+    const manifest = origin ? readManifest(backupDir, side, origin) : null;
+    if (!manifest)
+        throw new ConfigBackupNotFoundError(`No config backup named ${side}`);
+    const allowed = new Set(CONFIG_BACKUP_FILES);
+    const checkMode = folderKeepsModes(backupDir);
+    assertTrustedSnapshotEntry(join(backupDir, side), `Backup ${side}`, checkMode);
+    for (const f of manifest.files) {
+        if (!allowed.has(f.name))
+            continue;
+        let data;
+        assertTrustedSnapshotEntry(join(backupDir, side, f.name), `${f.name} in ${side}`, checkMode);
+        try {
+            data = readFileSync(join(backupDir, side, f.name));
+        }
+        catch {
+            throw new ConfigBackupCorruptError(`${f.name} is missing from ${side}`);
+        }
+        if (sha256(data) !== f.sha256)
+            throw new ConfigBackupCorruptError(`${f.name} in ${side} does not match its checksum`);
+        out.set(f.name, data);
+    }
+    return out;
+}
+/**
+ * What differs between two states of the tracked files; a state is a snapshot id or `current`
+ * (the live files). Never returns the value of a credential: see REDACT_ALL_FILES and SECRET_KEY_RE.
+ */
+export function diffConfigBackups(opts) {
+    const a = loadDiffSide(opts.from, opts.dataDir, opts.backupDir);
+    const b = loadDiffSide(opts.to, opts.dataDir, opts.backupDir);
+    const files = [];
+    for (const name of CONFIG_BACKUP_FILES) {
+        const before = a.get(name);
+        const after = b.get(name);
+        if (!before && !after)
+            continue;
+        const base = { name, changes: [], truncated: false };
+        if (before && after && sha256(before) === sha256(after)) {
+            files.push({ ...base, status: 'unchanged', detail: 'keys' });
+            continue;
+        }
+        const la = before ? leavesOf(name, before) : new Map();
+        const lb = after ? leavesOf(name, after) : new Map();
+        const status = !before ? 'added' : !after ? 'removed' : 'changed';
+        if (!la || !lb) {
+            files.push({ ...base, status, detail: 'bytes' });
+            continue;
+        }
+        const { changes, truncated } = diffLeaves(name, la, lb);
+        // Only volatile keys differed (a discovery timestamp): the same state as far as the user is concerned.
+        files.push({
+            name,
+            status: changes.length || status !== 'changed' ? status : 'unchanged',
+            changes,
+            truncated,
+            detail: 'keys',
+        });
+    }
+    return { from: opts.from, to: opts.to, files, changed: files.filter((f) => f.status !== 'unchanged').length };
+}
+//# sourceMappingURL=config-backup.js.map