@matthesketh/fleet 1.8.1 → 1.11.1

package/dist/core/secrets-v2-snapshot.d.ts

@@ -0,0 +1,36 @@
+export interface SnapshotInput {
+    app: string;
+    backupRoot: string;
+    vaultDir: string;
+    encryptedFile: string;
+    composeDir: string;
+    composeFile: string;
+    appUnitFile: string;
+}
+export interface Snapshot {
+    app: string;
+    timestamp: string;
+    dir: string;
+    manifestEntry: unknown;
+}
+/**
+ * capture a timestamped backup of all four artefacts for an app:
+ *  - encrypted vault blob
+ *  - manifest entry (as manifest.json in the snapshot dir)
+ *  - compose file
+ *  - systemd unit (if it exists)
+ */
+export declare function snapshotApp(input: SnapshotInput): Snapshot;
+/**
+ * restore all four artefacts from a snapshot back to their original locations.
+ * the manifest is merged: only apps[app] is replaced, other apps are untouched.
+ * if the unit file wasn't captured (didn't exist at snapshot time), no unit is written.
+ */
+export declare function restoreSnapshot(input: SnapshotInput, snap: Snapshot): void;
+/**
+ * walk backupRoot looking for <timestamp>/<app>/ directories.
+ * returns snapshots sorted newest-first by timestamp string (lexicographic, which
+ * works correctly for the ISO-safe format with dashes instead of colons/dots).
+ * returns [] if backupRoot doesn't exist.
+ */
+export declare function listSnapshots(backupRoot: string, app: string): Snapshot[];

package/dist/core/secrets-v2-snapshot.js

@@ -0,0 +1,115 @@
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, } from 'node:fs';
+import { basename, join } from 'node:path';
+// callers must serialise migration operations: same-millisecond invocations
+// would write to the same backup dir and silently overwrite each other.
+// migrate-v2 (Task 21) is the only caller and is invoked one app at a time.
+function makeTimestamp() {
+    return new Date().toISOString().replace(/[:.]/g, '-');
+}
+/**
+ * capture a timestamped backup of all four artefacts for an app:
+ *  - encrypted vault blob
+ *  - manifest entry (as manifest.json in the snapshot dir)
+ *  - compose file
+ *  - systemd unit (if it exists)
+ */
+export function snapshotApp(input) {
+    const { app, backupRoot, vaultDir, encryptedFile, composeDir, composeFile, appUnitFile } = input;
+    // ensure backupRoot exists at 0700 — mkdirSync only sets mode on newly
+    // created dirs; if it pre-existed with a looser mode, chmod it explicitly.
+    if (!existsSync(backupRoot)) {
+        mkdirSync(backupRoot, { recursive: true, mode: 0o700 });
+    }
+    else {
+        chmodSync(backupRoot, 0o700);
+    }
+    const timestamp = makeTimestamp();
+    const snapDir = join(backupRoot, timestamp, app);
+    mkdirSync(snapDir, { recursive: true, mode: 0o700 });
+    // 1. encrypted vault blob
+    copyFileSync(join(vaultDir, encryptedFile), join(snapDir, encryptedFile));
+    // 2. manifest entry for this app only
+    const manifestPath = join(vaultDir, 'manifest.json');
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    const manifestEntry = manifest.apps[app] ?? {};
+    writeFileSync(join(snapDir, 'manifest.json'), JSON.stringify(manifestEntry, null, 2));
+    // 3. compose file
+    copyFileSync(join(composeDir, composeFile), join(snapDir, composeFile));
+    // 4. systemd unit (omitted if it doesn't exist yet)
+    if (existsSync(appUnitFile)) {
+        copyFileSync(appUnitFile, join(snapDir, basename(appUnitFile)));
+    }
+    return { app, timestamp, dir: snapDir, manifestEntry };
+}
+/**
+ * restore all four artefacts from a snapshot back to their original locations.
+ * the manifest is merged: only apps[app] is replaced, other apps are untouched.
+ * if the unit file wasn't captured (didn't exist at snapshot time), no unit is written.
+ */
+export function restoreSnapshot(input, snap) {
+    const { app, vaultDir, encryptedFile, composeDir, composeFile, appUnitFile } = input;
+    const { dir: snapDir } = snap;
+    // 1. encrypted vault blob
+    copyFileSync(join(snapDir, encryptedFile), join(vaultDir, encryptedFile));
+    // 2. manifest entry — merge back into live manifest, leaving other apps untouched
+    const snapEntryRaw = readFileSync(join(snapDir, 'manifest.json'), 'utf-8');
+    const snapEntry = JSON.parse(snapEntryRaw);
+    const manifestPath = join(vaultDir, 'manifest.json');
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    manifest.apps[app] = snapEntry;
+    writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+    // 3. compose file
+    copyFileSync(join(snapDir, composeFile), join(composeDir, composeFile));
+    // 4. systemd unit — only write back if it was captured in the snapshot
+    const unitBasename = basename(appUnitFile);
+    const snapUnit = join(snapDir, unitBasename);
+    if (existsSync(snapUnit)) {
+        copyFileSync(snapUnit, appUnitFile);
+    }
+}
+/**
+ * walk backupRoot looking for <timestamp>/<app>/ directories.
+ * returns snapshots sorted newest-first by timestamp string (lexicographic, which
+ * works correctly for the ISO-safe format with dashes instead of colons/dots).
+ * returns [] if backupRoot doesn't exist.
+ */
+export function listSnapshots(backupRoot, app) {
+    if (!existsSync(backupRoot))
+        return [];
+    const results = [];
+    for (const entry of readdirSync(backupRoot)) {
+        const tsDir = join(backupRoot, entry);
+        try {
+            if (!statSync(tsDir).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        const appDir = join(tsDir, app);
+        try {
+            if (!statSync(appDir).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        let manifestEntry = null;
+        const mPath = join(appDir, 'manifest.json');
+        if (existsSync(mPath)) {
+            try {
+                manifestEntry = JSON.parse(readFileSync(mPath, 'utf-8'));
+            }
+            catch { /* leave null */ }
+        }
+        results.push({
+            app,
+            timestamp: entry,
+            dir: appDir,
+            manifestEntry,
+        });
+    }
+    // Sort newest-first — the timestamp format is lexicographically sortable
+    results.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+    return results;
+}

package/dist/core/secrets-v2.d.ts

@@ -0,0 +1,21 @@
+export declare const IDLE_TIMEOUT_MS = 30000;
+export declare function _resetRateLimit(initialTokens?: number): void;
+export declare function decryptVaultBlob(privateKeyPath: string, blobPath: string): Record<string, string>;
+export interface AgentDeps {
+    app: string;
+    getSecrets: () => Record<string, string>;
+    refresh: () => void;
+}
+export interface Server {
+    listen(path: string): Promise<void>;
+    close(): Promise<void>;
+}
+export declare function createServer(deps: AgentDeps): Server;
+export interface AgentArgs {
+    app: string;
+    vault: string;
+    socket: string;
+    credential?: string;
+}
+export declare function parseArgs(argv: string[]): AgentArgs;
+export declare function main(argv: string[]): Promise<void>;

package/dist/core/secrets-v2.js

@@ -0,0 +1,249 @@
+import { createServer as netCreateServer } from 'node:net';
+import { existsSync, unlinkSync, chmodSync } from 'node:fs';
+import { execSafe } from './exec.js';
+import { SecretsError } from './errors.js';
+import { parseRequest, writeResponse, ProtocolError } from './secrets-v2-protocol.js';
+export const IDLE_TIMEOUT_MS = 30_000;
+const TERM = Buffer.from('\r\n\r\n');
+// module-level token bucket — limits total throughput to 100 req/sec across all connections
+let _tokens = 100;
+let _lastRefill = Date.now();
+function takeToken() {
+    const now = Date.now();
+    const elapsed = (now - _lastRefill) / 1000;
+    if (elapsed > 0) {
+        _tokens = Math.min(100, _tokens + elapsed * 100);
+        _lastRefill = now;
+    }
+    if (_tokens < 1)
+        return false;
+    _tokens -= 1;
+    return true;
+}
+export function _resetRateLimit(initialTokens = 100) {
+    _tokens = initialTokens;
+    _lastRefill = Date.now();
+}
+export function decryptVaultBlob(privateKeyPath, blobPath) {
+    if (!existsSync(blobPath))
+        throw new SecretsError(`vault blob not found: ${blobPath}`);
+    if (!existsSync(privateKeyPath))
+        throw new SecretsError(`private key not found: ${privateKeyPath}`);
+    const r = execSafe('age', ['-d', '-i', privateKeyPath, blobPath]);
+    if (!r.ok)
+        throw new SecretsError(`age decrypt failed: ${r.stderr}`);
+    return parseEnvFormat(r.stdout);
+}
+/**
+ * Parse plaintext env content into a key/value map.
+ *
+ * Note: callers receive `content` after `execSafe` has applied `.trim()` to
+ * the full stdout. Leading/trailing whitespace at the start of the first
+ * line and end of the last line is consumed before parsing. Secret values
+ * with deliberate edge whitespace will be subtly altered. This is a known
+ * project-wide gotcha (also affects v1 secrets); see brain note q5YkhSmRVx9m.
+ */
+function parseEnvFormat(content) {
+    const map = {};
+    for (const rawLine of content.split('\n')) {
+        if (!rawLine.trim() || rawLine.startsWith('#'))
+            continue;
+        const i = rawLine.indexOf('=');
+        if (i > 0) {
+            map[rawLine.slice(0, i)] = rawLine.slice(i + 1);
+        }
+    }
+    return map;
+}
+const MAX_REQUEST_BYTES = 8192;
+export function createServer(deps) {
+    const server = netCreateServer((sock) => handleConnection(sock, deps));
+    let socketPath = '';
+    return {
+        listen: (path) => new Promise((resolve, reject) => {
+            socketPath = path;
+            if (existsSync(path)) {
+                try {
+                    unlinkSync(path);
+                }
+                catch { /* race; let listen fail naturally */ }
+            }
+            const onError = (err) => reject(err);
+            server.once('error', onError);
+            server.listen(path, () => {
+                server.off('error', onError);
+                // 0o660 (not 0o600) is deliberate: the systemd unit runs the agent
+                // as DynamicUser, and the consumer container bind-mounts this
+                // socket and connects as a separate uid sharing the systemd-
+                // allocated group. tightening to 0o600 would break that. if the
+                // consumer pattern ever changes, drop to 0o600.
+                try {
+                    chmodSync(path, 0o660);
+                }
+                catch (err) {
+                    process.stderr.write(`[fleet-agent] WARNING: chmod 0660 on ${path} failed: ${err.message}\n`);
+                }
+                resolve();
+            });
+        }),
+        close: () => new Promise((resolve) => {
+            server.close(() => {
+                if (socketPath && existsSync(socketPath)) {
+                    try {
+                        unlinkSync(socketPath);
+                    }
+                    catch { /* ignore */ }
+                }
+                resolve();
+            });
+        }),
+    };
+}
+function handleConnection(sock, deps) {
+    const chunks = [];
+    let totalBytes = 0;
+    let handled = false;
+    let searchedUpTo = 0;
+    sock.setTimeout(IDLE_TIMEOUT_MS, () => sock.destroy());
+    const handle = () => {
+        if (handled)
+            return;
+        handled = true;
+        if (!takeToken()) {
+            sock.end(writeResponse(429, { error: 'rate_limited' }));
+            return;
+        }
+        const buf = Buffer.concat(chunks);
+        try {
+            const req = parseRequest(buf);
+            const resp = dispatch(req, deps);
+            sock.end(resp);
+        }
+        catch (err) {
+            const isProto = err instanceof ProtocolError;
+            const status = isProto ? 400 : 500;
+            const message = isProto ? err.message : 'internal';
+            sock.end(writeResponse(status, { error: message }));
+        }
+    };
+    sock.on('data', (chunk) => {
+        chunks.push(chunk);
+        totalBytes += chunk.length;
+        if (totalBytes > MAX_REQUEST_BYTES) {
+            handled = true;
+            sock.end(writeResponse(413, { error: 'request too large' }));
+            return;
+        }
+        const buf = Buffer.concat(chunks);
+        const idx = buf.indexOf(TERM, Math.max(0, searchedUpTo - 3));
+        if (idx >= 0) {
+            handle();
+        }
+        else {
+            searchedUpTo = buf.length;
+        }
+    });
+    sock.on('end', () => { if (!handled)
+        handle(); });
+    sock.on('error', () => { });
+}
+const KNOWN_FLAGS = new Set(['--app', '--vault', '--socket', '--credential']);
+const USAGE = 'Usage: fleet-agent --app <name> --vault <dir> --socket <path> [--credential <path>]';
+export function parseArgs(argv) {
+    const parsed = {};
+    let i = 0;
+    while (i < argv.length) {
+        const flag = argv[i];
+        if (!flag.startsWith('--')) {
+            throw new SecretsError(`unexpected argument: ${flag}\n${USAGE}`);
+        }
+        if (!KNOWN_FLAGS.has(flag)) {
+            throw new SecretsError(`unknown flag: ${flag}\n${USAGE}`);
+        }
+        i++;
+        if (i >= argv.length || argv[i].startsWith('--')) {
+            throw new SecretsError(`flag ${flag} requires a value\n${USAGE}`);
+        }
+        parsed[flag.slice(2)] = argv[i];
+        i++;
+    }
+    for (const required of ['app', 'vault', 'socket']) {
+        if (!parsed[required]) {
+            throw new SecretsError(`missing required flag --${required}\n${USAGE}`);
+        }
+    }
+    return {
+        app: parsed['app'],
+        vault: parsed['vault'],
+        socket: parsed['socket'],
+        ...(parsed['credential'] !== undefined ? { credential: parsed['credential'] } : {}),
+    };
+}
+export async function main(argv) {
+    const args = parseArgs(argv);
+    const credentialPath = args.credential
+        ?? (process.env.CREDENTIALS_DIRECTORY
+            ? `${process.env.CREDENTIALS_DIRECTORY}/age-key`
+            : undefined);
+    if (!credentialPath) {
+        throw new SecretsError('no credential path: pass --credential or run under systemd with LoadCredential');
+    }
+    const vaultBlobPath = `${args.vault}/${args.app}.env.age`;
+    let secrets = decryptVaultBlob(credentialPath, vaultBlobPath);
+    const deps = {
+        app: args.app,
+        getSecrets: () => secrets,
+        refresh: () => {
+            secrets = decryptVaultBlob(credentialPath, vaultBlobPath);
+        },
+    };
+    const server = createServer(deps);
+    await server.listen(args.socket);
+    const notify = process.env.NOTIFY_SOCKET;
+    if (notify) {
+        const r = execSafe('systemd-notify', ['--ready'], {});
+        if (!r.ok) {
+            process.stderr.write(`[fleet-agent ${args.app}] systemd-notify failed: ${r.stderr}\n`);
+        }
+    }
+    return new Promise((resolve) => {
+        let shuttingDown = false;
+        const handleSignal = async (sig) => {
+            if (shuttingDown)
+                return;
+            shuttingDown = true;
+            process.stderr.write(`[fleet-agent ${args.app}] ${sig}, shutting down\n`);
+            try {
+                await server.close();
+            }
+            catch { /* ignore */ }
+            resolve();
+        };
+        process.once('SIGTERM', () => handleSignal('SIGTERM'));
+        process.once('SIGINT', () => handleSignal('SIGINT'));
+    });
+}
+function dispatch(req, deps) {
+    if (req.method === 'GET' && req.path === '/health') {
+        const m = deps.getSecrets();
+        return writeResponse(200, { app: deps.app, secrets: Object.keys(m).length });
+    }
+    if (req.method === 'POST' && req.path === '/refresh') {
+        deps.refresh();
+        return writeResponse(200, { reloaded: true });
+    }
+    if (req.method === 'GET' && req.path === '/secrets') {
+        return writeResponse(200, deps.getSecrets());
+    }
+    if (req.method === 'GET' && req.path.startsWith('/secrets/')) {
+        const key = req.path.slice('/secrets/'.length);
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+            return writeResponse(400, { error: 'invalid_key' });
+        }
+        const m = deps.getSecrets();
+        if (key in m)
+            return writeResponse(200, { value: m[key] });
+        return writeResponse(404, { error: 'not_found' });
+    }
+    return writeResponse(404, { error: 'not_found' });
+}

package/dist/core/secrets.d.ts

@@ -1,6 +1,7 @@
 export declare const VAULT_DIR: string;
 export declare const KEY_PATH = "/etc/fleet/age.key";
 export declare const RUNTIME_DIR = "/run/fleet-secrets";
+export declare const MANIFEST_PATH: string;
 export interface SecretMetadata {
     lastRotated: string;
     provider?: string;
@@ -17,8 +18,10 @@ export interface ManifestEntry {
     /** Per-secret metadata, keyed by secret name. Backwards-compatible: missing means
      * lastRotated falls back to lastSealedAt and provider is auto-classified at read time. */
     secrets?: Record<string, SecretMetadata>;
-    /** Per-app age recipient public key, used by harden --per-app to limit blast radius. */
+    /** per-app age recipient public key. required when mode === 'socket'. */
     recipient?: string;
+    /** delivery mode. defaults to 'unseal' (v1 tmpfs path) when undefined for backward compat. */
+    mode?: 'unseal' | 'socket';
 }
 export interface Manifest {
     version: number;
@@ -31,9 +34,41 @@ export declare function getPublicKey(): string;
 export declare function initVault(): string;
 export declare function loadManifest(): Manifest;
 export declare function saveManifest(manifest: Manifest): void;
-export declare function backupVaultFile(app: string): string | null;
-export declare function restoreVaultFile(app: string): boolean;
-export declare function removeBackup(app: string): void;
+/**
+ * Run an arbitrary transaction under the manifest's inter-process lock.
+ * The callback receives no manifest — it's responsible for any load / save
+ * it needs (the seal flows do their own validate → backup → seal → cleanup
+ * dance and don't fit a simple load/mutate/save shape).
+ *
+ * Important: NOT reentrant. Wrap only the outermost RMW boundary; inner
+ * helpers should call plain `loadManifest` / `saveManifest`.
+ */
+export declare function lockManifest<T>(fn: () => Promise<T> | T): Promise<T>;
+/**
+ * Run a simple load → mutate → save transaction against the secrets
+ * manifest under an inter-process lock. Used by callers that need a
+ * straightforward RMW with no extra side-effects.
+ *
+ * The mutator may return a different Manifest object or mutate the input
+ * and return it. The returned value is persisted on a successful run; if
+ * the mutator throws, no save happens and the lock is released.
+ *
+ * Important: NOT reentrant. Wrap only the outermost RMW boundary; inner
+ * helpers should call plain `loadManifest` / `saveManifest`.
+ */
+export declare function withManifest(fn: (m: Manifest) => Manifest | Promise<Manifest>): Promise<void>;
+/**
+ * Create a per-op backup of an app's encrypted vault file.
+ *
+ * Each call produces a unique `.bak-<tag>` path so concurrent operations do
+ * not silently overwrite each other's recovery point. If you don't supply a
+ * tag, one is generated from PID + timestamp + an in-process monotonic
+ * counter. Callers MUST keep the returned path and pass it to
+ * `restoreVaultFile` / `removeBackup`.
+ */
+export declare function backupVaultFile(app: string, tag?: string): string | null;
+export declare function restoreVaultFile(app: string, bakPath?: string): boolean;
+export declare function removeBackup(app: string, bakPath?: string): void;
 export declare function ageEncrypt(plaintext: string): string;
 export declare function ageDecrypt(ciphertext: string | Buffer): string;
 export declare function ageDecryptFile(filePath: string): string;

package/dist/core/secrets.js

@@ -1,14 +1,20 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, chmodSync, rmSync, copyFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, chmodSync, statSync, rmSync, copyFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { SecretsError, VaultNotInitializedError } from './errors.js';
 import { execSafe } from './exec.js';
 import { assertAppName, assertFilePath } from './validate.js';
+import { withFileLock } from './file-lock.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
-export const VAULT_DIR = join(__dirname, '..', '..', 'vault');
+// vault dir resolves from FLEET_VAULT_DIR if set; otherwise falls back to
+// the repo-local vault dir for dev. captures at module load — tests that
+// want to override need to set the env var before importing. matches the
+// pattern used in secrets-v2-cleanup.ts.
+export const VAULT_DIR = process.env.FLEET_VAULT_DIR
+    ?? join(__dirname, '..', '..', 'vault');
 export const KEY_PATH = '/etc/fleet/age.key';
 export const RUNTIME_DIR = '/run/fleet-secrets';
-const MANIFEST_PATH = join(VAULT_DIR, 'manifest.json');
+export const MANIFEST_PATH = join(VAULT_DIR, 'manifest.json');
 const SECRET_DELIMITER = '---SECRET:';
 export function ensureAge() {
     if (!execSafe('which', ['age']).ok) {
@@ -64,7 +70,50 @@ export function loadManifest() {
 export function saveManifest(manifest) {
     writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2) + '\n');
 }
-export function backupVaultFile(app) {
+/**
+ * Run an arbitrary transaction under the manifest's inter-process lock.
+ * The callback receives no manifest — it's responsible for any load / save
+ * it needs (the seal flows do their own validate → backup → seal → cleanup
+ * dance and don't fit a simple load/mutate/save shape).
+ *
+ * Important: NOT reentrant. Wrap only the outermost RMW boundary; inner
+ * helpers should call plain `loadManifest` / `saveManifest`.
+ */
+export async function lockManifest(fn) {
+    return withFileLock(MANIFEST_PATH, fn);
+}
+/**
+ * Run a simple load → mutate → save transaction against the secrets
+ * manifest under an inter-process lock. Used by callers that need a
+ * straightforward RMW with no extra side-effects.
+ *
+ * The mutator may return a different Manifest object or mutate the input
+ * and return it. The returned value is persisted on a successful run; if
+ * the mutator throws, no save happens and the lock is released.
+ *
+ * Important: NOT reentrant. Wrap only the outermost RMW boundary; inner
+ * helpers should call plain `loadManifest` / `saveManifest`.
+ */
+export async function withManifest(fn) {
+    await lockManifest(async () => {
+        const manifest = loadManifest();
+        const next = await fn(manifest);
+        saveManifest(next);
+    });
+}
+// monotonic counter so two backupVaultFile calls in the same millisecond
+// (same process, same default-tag path) still produce distinct bak filenames.
+let backupSeq = 0;
+/**
+ * Create a per-op backup of an app's encrypted vault file.
+ *
+ * Each call produces a unique `.bak-<tag>` path so concurrent operations do
+ * not silently overwrite each other's recovery point. If you don't supply a
+ * tag, one is generated from PID + timestamp + an in-process monotonic
+ * counter. Callers MUST keep the returned path and pass it to
+ * `restoreVaultFile` / `removeBackup`.
+ */
+export function backupVaultFile(app, tag) {
     const manifest = loadManifest();
     const entry = manifest.apps[app];
     if (!entry)
@@ -72,30 +121,61 @@ export function backupVaultFile(app) {
     const src = join(VAULT_DIR, entry.encryptedFile);
     if (!existsSync(src))
         return null;
-    const bak = src + '.bak';
+    const t = tag ?? `${process.pid}-${Date.now()}-${++backupSeq}`;
+    const bak = `${src}.bak-${t}`;
     copyFileSync(src, bak);
     return bak;
 }
-export function restoreVaultFile(app) {
+/**
+ * Find the newest `<encryptedFile>.bak-*` for an app, if any. Returns the full
+ * path (in VAULT_DIR) or null. Used as a best-effort fallback when no specific
+ * backup path was supplied (e.g. the simple CLI / MCP `secrets restore` flow).
+ */
+function findNewestBackup(encryptedFile) {
+    if (!existsSync(VAULT_DIR))
+        return null;
+    const prefix = `${encryptedFile}.bak-`;
+    let newest = null;
+    for (const name of readdirSync(VAULT_DIR)) {
+        if (!name.startsWith(prefix))
+            continue;
+        const full = join(VAULT_DIR, name);
+        try {
+            const m = statSync(full).mtimeMs;
+            if (!newest || m > newest.mtime)
+                newest = { path: full, mtime: m };
+        }
+        catch {
+            // ignore stat failures — file may have been removed mid-scan
+        }
+    }
+    return newest ? newest.path : null;
+}
+export function restoreVaultFile(app, bakPath) {
     const manifest = loadManifest();
     const entry = manifest.apps[app];
     if (!entry)
         return false;
     const src = join(VAULT_DIR, entry.encryptedFile);
-    const bak = src + '.bak';
-    if (!existsSync(bak))
+    const bak = bakPath ?? findNewestBackup(entry.encryptedFile);
+    if (!bak || !existsSync(bak))
         return false;
     copyFileSync(bak, src);
     rmSync(bak, { force: true });
     return true;
 }
-export function removeBackup(app) {
+export function removeBackup(app, bakPath) {
+    if (bakPath) {
+        rmSync(bakPath, { force: true });
+        return;
+    }
     const manifest = loadManifest();
     const entry = manifest.apps[app];
     if (!entry)
         return;
-    const bak = join(VAULT_DIR, entry.encryptedFile) + '.bak';
-    rmSync(bak, { force: true });
+    const bak = findNewestBackup(entry.encryptedFile);
+    if (bak)
+        rmSync(bak, { force: true });
 }
 export function ageEncrypt(plaintext) {
     const pubkey = getPublicKey();