@matthesketh/fleet 1.8.1 → 1.11.0

package/dist/core/secrets-ops.js

@@ -28,7 +28,7 @@ function tryTightenPerms(envPath, app) {
         process.stderr.write(`[fleet-unseal] perm tightening skipped for ${app}: ${err}\n`);
     }
 }
-import { KEY_PATH, VAULT_DIR, RUNTIME_DIR, loadManifest, saveManifest, decryptApp, parseSecretsBundle, sealApp, sealDbSecrets, ageEncrypt, ageDecryptFile, getPublicKey, isInitialized, isSealed, backupVaultFile, restoreVaultFile, removeBackup, } from './secrets.js';
+import { KEY_PATH, VAULT_DIR, RUNTIME_DIR, loadManifest, saveManifest, decryptApp, parseSecretsBundle, sealApp, sealDbSecrets, ageEncrypt, ageDecryptFile, getPublicKey, isInitialized, isSealed, backupVaultFile, restoreVaultFile, removeBackup, lockManifest, } from './secrets.js';
 // --- helpers ---
 function safeEqual(a, b) {
     const bufA = Buffer.from(a);
@@ -72,15 +72,24 @@ export function validateBeforeSeal(app, newContent) {
     return { added, removed, unchanged };
 }
 // --- Phase 8: Safe seal wrappers ---
+//
+// safeSealApp / safeSealDbSecrets are the "validate + backup + seal +
+// cleanup" primitives. They do NOT take the manifest lock themselves because
+// they're called from inside already-locked outer flows (setSecret,
+// sealFromRuntime). External callers that need concurrency safety should go
+// via setSecret / importEnvFile / importDbSecrets / sealFromRuntime instead;
+// those wrap the whole flow in lockManifest().
 export function safeSealApp(app, content, sourceFile) {
     const validation = validateBeforeSeal(app, content);
-    backupVaultFile(app);
+    const bak = backupVaultFile(app);
     try {
         sealApp(app, content, sourceFile);
-        removeBackup(app);
+        if (bak)
+            removeBackup(app, bak);
     }
     catch (err) {
-        restoreVaultFile(app);
+        if (bak)
+            restoreVaultFile(app, bak);
         throw err;
     }
     return validation;
@@ -92,18 +101,20 @@ export function safeSealDbSecrets(app, secretsMap, sourceDir) {
     const parts = filenames.map(f => `${SECRET_DELIMITER}${f}---\n${secretsMap[f]}`);
     const bundleContent = parts.join('\n');
     const validation = validateBeforeSeal(app, bundleContent);
-    backupVaultFile(app);
+    const bak = backupVaultFile(app);
     try {
         sealDbSecrets(app, secretsMap, sourceDir);
-        removeBackup(app);
+        if (bak)
+            removeBackup(app, bak);
     }
     catch (err) {
-        restoreVaultFile(app);
+        if (bak)
+            restoreVaultFile(app, bak);
         throw err;
     }
     return validation;
 }
-export function setSecret(app, key, value, opts = {}) {
+export async function setSecret(app, key, value, opts = {}) {
     assertAppName(app);
     assertSecretKey(key);
     // Entropy / placeholder check unless explicitly bypassed.
@@ -114,26 +125,37 @@ export function setSecret(app, key, value, opts = {}) {
             throw new SecretsError(`${entropyErr}. Pass --allow-weak to override (not recommended).`);
         }
     }
-    const plaintext = decryptApp(app);
-    const manifest = loadManifest();
-    const entry = manifest.apps[app];
-    if (entry.type !== 'env')
-        throw new SecretsError(`Cannot set key/value on secrets-dir type for ${app}`);
-    const lines = plaintext.split('\n');
-    let found = false;
-    const updated = lines.map(line => {
-        const eqIdx = line.indexOf('=');
-        if (eqIdx > 0 && line.substring(0, eqIdx) === key) {
-            found = true;
-            return `${key}=${value}`;
-        }
-        return line;
+    // Hold the manifest lock for the entire decrypt → mutate → re-seal cycle so
+    // a parallel CLI/cron writer can't insert a stale write between our read
+    // and our seal. safeSealApp does its own loadManifest/saveManifest inside —
+    // those reads/writes happen under our lock.
+    await lockManifest(() => {
+        const plaintext = decryptApp(app);
+        const manifest = loadManifest();
+        const entry = manifest.apps[app];
+        if (entry.type !== 'env')
+            throw new SecretsError(`Cannot set key/value on secrets-dir type for ${app}`);
+        const lines = plaintext.split('\n');
+        let found = false;
+        const updated = lines.map(line => {
+            const eqIdx = line.indexOf('=');
+            if (eqIdx > 0 && line.substring(0, eqIdx) === key) {
+                found = true;
+                return `${key}=${value}`;
+            }
+            return line;
+        });
+        if (!found)
+            updated.push(`${key}=${value}`);
+        safeSealApp(app, updated.join('\n'), entry.sourceFile);
+        auditLog({ op: 'set', app, secret: key, ok: true });
     });
-    if (!found)
-        updated.push(`${key}=${value}`);
-    safeSealApp(app, updated.join('\n'), entry.sourceFile);
-    auditLog({ op: 'set', app, secret: key, ok: true });
 }
+/** read a single secret value. deliberately does NOT hold the manifest
+ *  lock — a concurrent setSecret/seal does an atomic file rename, so the
+ *  worst-case race here is reading the immediate-pre-rotation vault blob.
+ *  audit logging happens at the command layer so programmatic reads
+ *  (background sync, validation) don't pollute the audit trail. */
 export function getSecret(app, key) {
     const plaintext = decryptApp(app);
     const manifest = loadManifest();
@@ -154,26 +176,30 @@ export function getSecret(app, key) {
 // human-driven reads (set/get/import/export). Programmatic reads done by
 // other fleet operations (sealing, validation, drift) are not audited to
 // avoid log noise.
-export function importEnvFile(app, path) {
+export async function importEnvFile(app, path) {
     if (!existsSync(path))
         throw new SecretsError(`File not found: ${path}`);
     const content = readFileSync(path, 'utf-8');
-    // importEnvFile is an explicit replace — bypass validation, but still backup
-    backupVaultFile(app);
-    try {
-        sealApp(app, content, path);
-        removeBackup(app);
-    }
-    catch (err) {
-        restoreVaultFile(app);
-        auditLog({ op: 'import', app, ok: false, details: `${path}: ${err}` });
-        throw err;
-    }
-    const manifest = loadManifest();
-    auditLog({ op: 'import', app, ok: true, details: `${path}: ${manifest.apps[app].keyCount} keys` });
-    return manifest.apps[app].keyCount;
+    return await lockManifest(() => {
+        // importEnvFile is an explicit replace — bypass validation, but still backup
+        const bak = backupVaultFile(app);
+        try {
+            sealApp(app, content, path);
+            if (bak)
+                removeBackup(app, bak);
+        }
+        catch (err) {
+            if (bak)
+                restoreVaultFile(app, bak);
+            auditLog({ op: 'import', app, ok: false, details: `${path}: ${err}` });
+            throw err;
+        }
+        const manifest = loadManifest();
+        auditLog({ op: 'import', app, ok: true, details: `${path}: ${manifest.apps[app].keyCount} keys` });
+        return manifest.apps[app].keyCount;
+    });
 }
-export function importDbSecrets(app, dir) {
+export async function importDbSecrets(app, dir) {
     if (!existsSync(dir))
         throw new SecretsError(`Directory not found: ${dir}`);
     const stat = statSync(dir);
@@ -184,17 +210,21 @@ export function importDbSecrets(app, dir) {
     for (const file of files) {
         secretsMap[file] = readFileSync(join(dir, file), 'utf-8');
     }
-    // importDbSecrets is an explicit replace — bypass validation, but still backup
-    backupVaultFile(app);
-    try {
-        sealDbSecrets(app, secretsMap, dir);
-        removeBackup(app);
-    }
-    catch (err) {
-        restoreVaultFile(app);
-        throw err;
-    }
-    return files.length;
+    return await lockManifest(() => {
+        // importDbSecrets is an explicit replace — bypass validation, but still backup
+        const bak = backupVaultFile(app);
+        try {
+            sealDbSecrets(app, secretsMap, dir);
+            if (bak)
+                removeBackup(app, bak);
+        }
+        catch (err) {
+            if (bak)
+                restoreVaultFile(app, bak);
+            throw err;
+        }
+        return files.length;
+    });
 }
 export function exportApp(app) {
     auditLog({ op: 'export', app, ok: true });
@@ -322,58 +352,134 @@ export function unsealAll() {
         }
     }
 }
-export function sealFromRuntime(app) {
-    const manifest = loadManifest();
-    const apps = app ? [app] : Object.keys(manifest.apps);
-    const sealed = [];
-    for (const a of apps) {
-        const entry = manifest.apps[a];
-        if (!entry)
-            throw new SecretsError(`No secrets found for app: ${a}`);
-        if (entry.type === 'env') {
-            const runtimePath = join(RUNTIME_DIR, a, '.env');
-            if (!existsSync(runtimePath))
-                throw new SecretsError(`Runtime file not found: ${runtimePath}`);
-            const content = readFileSync(runtimePath, 'utf-8');
-            safeSealApp(a, content, entry.sourceFile);
-        }
-        else {
-            const runtimeDir = join(RUNTIME_DIR, a, 'secrets');
-            if (!existsSync(runtimeDir))
-                throw new SecretsError(`Runtime dir not found: ${runtimeDir}`);
-            const dirFiles = readdirSync(runtimeDir);
-            const secretsMap = {};
-            for (const f of dirFiles) {
-                secretsMap[f] = readFileSync(join(runtimeDir, f), 'utf-8');
+export async function sealFromRuntime(app) {
+    return await lockManifest(() => {
+        const manifest = loadManifest();
+        const apps = app ? [app] : Object.keys(manifest.apps);
+        const sealed = [];
+        for (const a of apps) {
+            const entry = manifest.apps[a];
+            if (!entry)
+                throw new SecretsError(`No secrets found for app: ${a}`);
+            if (entry.type === 'env') {
+                const runtimePath = join(RUNTIME_DIR, a, '.env');
+                if (!existsSync(runtimePath))
+                    throw new SecretsError(`Runtime file not found: ${runtimePath}`);
+                const content = readFileSync(runtimePath, 'utf-8');
+                safeSealApp(a, content, entry.sourceFile);
+            }
+            else {
+                const runtimeDir = join(RUNTIME_DIR, a, 'secrets');
+                if (!existsSync(runtimeDir))
+                    throw new SecretsError(`Runtime dir not found: ${runtimeDir}`);
+                const dirFiles = readdirSync(runtimeDir);
+                const secretsMap = {};
+                for (const f of dirFiles) {
+                    secretsMap[f] = readFileSync(join(runtimeDir, f), 'utf-8');
+                }
+                safeSealDbSecrets(a, secretsMap, entry.sourceFile);
             }
-            safeSealDbSecrets(a, secretsMap, entry.sourceFile);
+            sealed.push(a);
         }
-        sealed.push(a);
-    }
-    return sealed;
+        return sealed;
+    });
 }
-export function rotateKey() {
-    const manifest = loadManifest();
-    const oldPubkey = getPublicKey();
-    const decrypted = {};
-    for (const [app, entry] of Object.entries(manifest.apps)) {
-        decrypted[app] = ageDecryptFile(join(VAULT_DIR, entry.encryptedFile));
-    }
-    const backupPath = KEY_PATH + '.old';
-    copyFileSync(KEY_PATH, backupPath);
-    const keygen = execSafe('age-keygen', ['-o', KEY_PATH]);
-    if (!keygen.ok)
-        throw new SecretsError(`Failed to generate new key: ${keygen.stderr}`);
-    chmodSync(KEY_PATH, 0o600);
-    const newPubkey = getPublicKey();
-    for (const [app, entry] of Object.entries(manifest.apps)) {
-        const encrypted = ageEncrypt(decrypted[app]);
-        writeFileSync(join(VAULT_DIR, entry.encryptedFile), encrypted);
-        entry.lastSealedAt = new Date().toISOString();
-    }
-    saveManifest(manifest);
-    rmSync(backupPath, { force: true });
-    return { oldPubkey, newPubkey, appsRotated: Object.keys(manifest.apps) };
+/**
+ * Rotate the age private key and re-encrypt every app's vault file with it.
+ *
+ * RECOVERY PROCEDURE (manual, only if rollback itself fails):
+ *   1. The previous private key is preserved at `<KEY_PATH>.old` while a
+ *      rotation is in flight. If you see that file lying around, a rotation
+ *      crashed mid-way.
+ *   2. Each app's pre-rotate encrypted file is preserved as
+ *      `vault/<app>.{env,secrets}.age.bak-rotate-<ts>` for the duration of
+ *      the rotation. They are removed automatically on success OR after a
+ *      successful rollback.
+ *   3. To restore by hand: copy `<KEY_PATH>.old` back to `<KEY_PATH>`
+ *      (chmod 0600), then for each `*.bak-rotate-<ts>` copy it over the
+ *      matching encrypted file. This puts the vault back into the
+ *      pre-rotation state.
+ *
+ * On a partial-failure path inside this function, that recovery is performed
+ * automatically before re-throwing. The whole rotation runs under the
+ * manifest's inter-process lock.
+ */
+export async function rotateKey() {
+    return await lockManifest(() => {
+        const manifest = loadManifest();
+        const oldPubkey = getPublicKey();
+        // 1. Decrypt all apps with the OLD key (still on disk at KEY_PATH).
+        const decrypted = {};
+        for (const [app, entry] of Object.entries(manifest.apps)) {
+            decrypted[app] = ageDecryptFile(join(VAULT_DIR, entry.encryptedFile));
+        }
+        // 2. Backup the old key so we can roll back if anything below throws.
+        const backupPath = KEY_PATH + '.old';
+        copyFileSync(KEY_PATH, backupPath);
+        // 3. Generate the new key in place. If keygen fails BEFORE we've mutated
+        //    any vault file, the old key on disk is still good — clean up the
+        //    sidecar backup and bail without touching the vault.
+        const keygen = execSafe('age-keygen', ['-o', KEY_PATH]);
+        if (!keygen.ok) {
+            rmSync(backupPath, { force: true });
+            throw new SecretsError(`Failed to generate new key: ${keygen.stderr}`);
+        }
+        chmodSync(KEY_PATH, 0o600);
+        const newPubkey = getPublicKey();
+        // 4. Snapshot every app's CURRENT (still old-key-encrypted) vault file
+        //    BEFORE we start rewriting anything. Same rotation tag for all of them
+        //    so a human can grep for `bak-rotate-<ts>` if they need to recover.
+        const rotateTag = `rotate-${Date.now()}`;
+        const backups = [];
+        try {
+            for (const app of Object.keys(manifest.apps)) {
+                const b = backupVaultFile(app, rotateTag);
+                if (b)
+                    backups.push({ app, bak: b });
+            }
+            // 5. Re-encrypt each app's plaintext under the NEW key and overwrite
+            //    its vault file. If any encryption or write throws partway through,
+            //    we land in the catch block below.
+            for (const [app, entry] of Object.entries(manifest.apps)) {
+                const encrypted = ageEncrypt(decrypted[app]);
+                writeFileSync(join(VAULT_DIR, entry.encryptedFile), encrypted);
+                entry.lastSealedAt = new Date().toISOString();
+            }
+            saveManifest(manifest);
+            // 6. Success — drop the per-app rotation backups and the old-key sidecar.
+            for (const b of backups)
+                rmSync(b.bak, { force: true });
+            rmSync(backupPath, { force: true });
+        }
+        catch (err) {
+            // Rollback: put the old key back, then restore every vault file from the
+            // matching pre-rotate backup. If rollback itself fails we deliberately
+            // leak the .bak-rotate-* files and KEY_PATH.old so a human has the
+            // pieces needed to recover by hand (see comment at top of function).
+            try {
+                copyFileSync(backupPath, KEY_PATH);
+                chmodSync(KEY_PATH, 0o600);
+                for (const b of backups) {
+                    const entry = manifest.apps[b.app];
+                    if (!entry)
+                        continue;
+                    copyFileSync(b.bak, join(VAULT_DIR, entry.encryptedFile));
+                }
+            }
+            catch (rollbackErr) {
+                throw new SecretsError(`rotateKey failed AND rollback failed: ${err.message}; ` +
+                    `rollback: ${rollbackErr.message}; ` +
+                    `manual recovery needed (KEY_PATH.old + vault/*.bak-${rotateTag} files preserved)`);
+            }
+            // Rollback succeeded — vault is back where it started under the old key.
+            // Safe to clean up the per-app backups and the old-key sidecar.
+            for (const b of backups)
+                rmSync(b.bak, { force: true });
+            rmSync(backupPath, { force: true });
+            throw new SecretsError(`rotateKey failed (rolled back): ${err.message}`);
+        }
+        return { oldPubkey, newPubkey, appsRotated: Object.keys(manifest.apps) };
+    });
 }
 export function getStatus() {
     const init = isInitialized();

package/dist/core/secrets-providers.js

@@ -124,7 +124,7 @@ export const PROVIDERS = [
         matches: /^(EMAIL_SERVER_PASSWORD|GMAIL_APP_PASSWORD|SMTP_PASS|SMTP_PASSWORD)$/,
         name: 'Gmail App Password / SMTP Password',
         url: 'https://myaccount.google.com/apppasswords',
-        instructions: '1. Sign in and create a new App Password (e.g. "macpool-2026")\n' +
+        instructions: '1. Sign in and create a new App Password (e.g. "poolside-2026")\n' +
             '2. Copy the 16-character value and paste below WITHOUT spaces\n' +
             '3. Revoke the old App Password from the same page',
         // Gmail app passwords are 16 lowercase alphanumeric chars. Google
@@ -193,7 +193,7 @@ export const PROVIDERS = [
         rotationFrequencyDays: 365,
         strategy: 'at-rest-key',
     },
-    // ── Bookwhen (used by macpool) ───────────────────────────────────────────
+    // ── Bookwhen (used by poolside) ───────────────────────────────────────────
     {
         id: 'bookwhen-token',
         matches: /^BOOKWHEN_API_TOKEN$/,

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

@@ -49,4 +49,4 @@ export declare function performRotation(app: string, key: string, newValue: stri
     dryRun?: boolean;
     notes?: string;
     dataMigrated?: boolean;
-}): RotationResult;
+}): Promise<RotationResult>;

package/dist/core/secrets-rotation.js

@@ -4,7 +4,7 @@
  * gate, and rolls back on failure. Pure functions where possible — I/O isolated
  * to thin wrappers so tests can run without a real vault.
  */
-import { decryptApp, sealApp, loadManifest } from './secrets.js';
+import { decryptApp, sealApp, loadManifest, lockManifest } from './secrets.js';
 import { snapshotApp, restoreSnapshot } from './secrets-snapshots.js';
 import { auditLog } from './secrets-audit.js';
 import { markRotated } from './secrets-metadata.js';
@@ -108,58 +108,64 @@ export function applyRotation(plaintext, key, newValue, strategy) {
  * snapshot → seal → audit. Restart + health-gate are caller's responsibility
  * (we want the engine pure-ish so it's easy to test).
  */
-export function performRotation(app, key, newValue, opts = {}) {
-    const manifest = loadManifest();
-    const entry = manifest.apps[app];
-    if (!entry)
-        throw new SecretsError(`No app in manifest: ${app}`);
-    if (entry.type !== 'env') {
-        throw new SecretsError(`Rotation only supports env-type apps, got ${entry.type}`);
-    }
-    const provider = classifySecret(key);
-    const strategy = provider?.strategy ?? 'immediate';
-    if (strategy === 'user-issued') {
-        throw new SecretsError(`${key} is a user-issued token. Rotating yours doesn't help — invalidate per-user instead.`);
-    }
-    // Strict typed opt — was previously a substring match on opts.notes which
-    // could be bypassed by any caller embedding the flag in free-text notes.
-    if (strategy === 'at-rest-key' && !opts.dataMigrated) {
-        throw new SecretsError(`${key} encrypts data at rest. Re-encrypt your data first, then pass --data-migrated.`);
-    }
-    if (opts.dryRun) {
-        auditLog({ op: 'rotate-attempted', app, secret: key, ok: true, details: 'dry-run' });
-        return { app, key, strategy, snapshot: '(dry-run)', rolledBack: false };
-    }
-    // 1. Snapshot before any change.
-    const snapshot = snapshotApp(app);
-    auditLog({ op: 'snapshot', app, secret: key, ok: true, details: snapshot });
-    try {
-        // 2. Decrypt, apply rotation, re-encrypt.
-        const plaintext = decryptApp(app);
-        const updated = applyRotation(plaintext, key, newValue, strategy);
-        sealApp(app, updated, entry.sourceFile);
-        // 3. Stamp metadata.
-        markRotated(app, key, { strategy, notes: opts.notes });
-        auditLog({ op: 'rotate', app, secret: key, ok: true, details: `strategy=${strategy}` });
-        return { app, key, strategy, snapshot, rolledBack: false };
-    }
-    catch (err) {
-        const reason = err instanceof Error ? err.message : String(err);
-        // Restore from snapshot on any failure.
+export async function performRotation(app, key, newValue, opts = {}) {
+    // Hold the manifest lock for the whole snapshot → seal → markRotated cycle
+    // so a concurrent CLI/cron writer can't slip a stale write between our
+    // seal and our metadata stamp. markRotated calls saveManifest internally;
+    // that write happens under our lock.
+    return await lockManifest(() => {
+        const manifest = loadManifest();
+        const entry = manifest.apps[app];
+        if (!entry)
+            throw new SecretsError(`No app in manifest: ${app}`);
+        if (entry.type !== 'env') {
+            throw new SecretsError(`Rotation only supports env-type apps, got ${entry.type}`);
+        }
+        const provider = classifySecret(key);
+        const strategy = provider?.strategy ?? 'immediate';
+        if (strategy === 'user-issued') {
+            throw new SecretsError(`${key} is a user-issued token. Rotating yours doesn't help — invalidate per-user instead.`);
+        }
+        // Strict typed opt — was previously a substring match on opts.notes which
+        // could be bypassed by any caller embedding the flag in free-text notes.
+        if (strategy === 'at-rest-key' && !opts.dataMigrated) {
+            throw new SecretsError(`${key} encrypts data at rest. Re-encrypt your data first, then pass --data-migrated.`);
+        }
+        if (opts.dryRun) {
+            auditLog({ op: 'rotate-attempted', app, secret: key, ok: true, details: 'dry-run' });
+            return { app, key, strategy, snapshot: '(dry-run)', rolledBack: false };
+        }
+        // 1. Snapshot before any change.
+        const snapshot = snapshotApp(app);
+        auditLog({ op: 'snapshot', app, secret: key, ok: true, details: snapshot });
         try {
-            restoreSnapshot(app);
-            auditLog({ op: 'rollback', app, secret: key, ok: true, details: `auto: ${reason}` });
+            // 2. Decrypt, apply rotation, re-encrypt.
+            const plaintext = decryptApp(app);
+            const updated = applyRotation(plaintext, key, newValue, strategy);
+            sealApp(app, updated, entry.sourceFile);
+            // 3. Stamp metadata.
+            markRotated(app, key, { strategy, notes: opts.notes });
+            auditLog({ op: 'rotate', app, secret: key, ok: true, details: `strategy=${strategy}` });
+            return { app, key, strategy, snapshot, rolledBack: false };
         }
-        catch (rollbackErr) {
-            auditLog({
-                op: 'rollback',
-                app,
-                secret: key,
-                ok: false,
-                details: `auto rollback also failed: ${rollbackErr}`,
-            });
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            // Restore from snapshot on any failure.
+            try {
+                restoreSnapshot(app);
+                auditLog({ op: 'rollback', app, secret: key, ok: true, details: `auto: ${reason}` });
+            }
+            catch (rollbackErr) {
+                auditLog({
+                    op: 'rollback',
+                    app,
+                    secret: key,
+                    ok: false,
+                    details: `auto rollback also failed: ${rollbackErr}`,
+                });
+            }
+            auditLog({ op: 'rotate-failed', app, secret: key, ok: false, details: reason });
+            return { app, key, strategy, snapshot, rolledBack: true, reason };
         }
-        auditLog({ op: 'rotate-failed', app, secret: key, ok: false, details: reason });
-        return { app, key, strategy, snapshot, rolledBack: true, reason };
-    }
+    });
 }

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

@@ -0,0 +1,19 @@
+export interface CleanupOpts {
+    app: string;
+    retentionDays?: number;
+    dryRun?: boolean;
+}
+export interface CleanupResult {
+    app: string;
+    removedBak: boolean;
+    removedSnapshots: string[];
+    keptSnapshots: string[];
+    dryRun: boolean;
+}
+/**
+ * parse a filesystem-safe snapshot timestamp back to a Date.
+ * input: '2026-05-06T12-00-00-000Z' (colons and dots replaced with dashes)
+ * output: Date('2026-05-06T12:00:00.000Z'), or null if unparseable
+ */
+export declare function parseSnapshotTimestamp(ts: string): Date | null;
+export declare function cleanupV2Backups(opts: CleanupOpts): Promise<CleanupResult>;

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

@@ -0,0 +1,94 @@
+import { dirname, join } from 'node:path';
+import { existsSync, readdirSync, rmSync, unlinkSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { findApp, load } from './registry.js';
+import { listSnapshots } from './secrets-v2-snapshot.js';
+import { SecretsError } from './errors.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** resolve vault dir: env override (used in tests) or the default computed path */
+function resolveVaultDir() {
+    return process.env.FLEET_VAULT_DIR ?? join(__dirname, '..', '..', 'vault');
+}
+/** read manifest directly without calling requireInit() */
+function readManifest(vaultDir) {
+    const p = join(vaultDir, 'manifest.json');
+    if (!existsSync(p))
+        return { version: 1, apps: {} };
+    try {
+        return JSON.parse(readFileSync(p, 'utf-8'));
+    }
+    catch {
+        return { version: 1, apps: {} };
+    }
+}
+/**
+ * parse a filesystem-safe snapshot timestamp back to a Date.
+ * input: '2026-05-06T12-00-00-000Z' (colons and dots replaced with dashes)
+ * output: Date('2026-05-06T12:00:00.000Z'), or null if unparseable
+ */
+export function parseSnapshotTimestamp(ts) {
+    const m = ts.match(/^(\d{4}-\d{2}-\d{2}T)(\d{2})-(\d{2})-(\d{2})-(\d{3})Z$/);
+    if (!m)
+        return null;
+    return new Date(`${m[1]}${m[2]}:${m[3]}:${m[4]}.${m[5]}Z`);
+}
+export async function cleanupV2Backups(opts) {
+    const { app, retentionDays = 30, dryRun = false } = opts;
+    const registry = load();
+    const appEntry = findApp(registry, app);
+    if (!appEntry) {
+        throw new SecretsError(`app '${app}' not found in fleet registry`);
+    }
+    const vaultDir = resolveVaultDir();
+    const manifest = readManifest(vaultDir);
+    const entry = manifest.apps[app];
+    if (!entry || entry.mode !== 'socket') {
+        throw new SecretsError(`app '${app}' is not in v2 mode; cleanup is for post-v2-migration apps only`);
+    }
+    const cutoff = Date.now() - retentionDays * 86_400_000;
+    const backupRoot = join(vaultDir, 'backups');
+    const snapshots = listSnapshots(backupRoot, app);
+    const removedSnapshots = [];
+    const keptSnapshots = [];
+    for (const snap of snapshots) {
+        const ts = parseSnapshotTimestamp(snap.timestamp);
+        if (!ts) {
+            // unparseable timestamp — keep rather than risk destroying unknown content
+            keptSnapshots.push(snap.timestamp);
+            continue;
+        }
+        if (ts.getTime() < cutoff) {
+            removedSnapshots.push(snap.timestamp);
+            if (!dryRun) {
+                rmSync(snap.dir, { recursive: true, force: true });
+                // best-effort: remove the parent timestamp dir if it's now empty
+                const parentDir = dirname(snap.dir);
+                try {
+                    const remaining = readdirSync(parentDir);
+                    if (remaining.length === 0)
+                        rmSync(parentDir, { recursive: true, force: true });
+                }
+                catch { /* ignore */ }
+            }
+        }
+        else {
+            keptSnapshots.push(snap.timestamp);
+        }
+    }
+    let removedBak = false;
+    const bakPath = join(vaultDir, `${app}.env.age.v1.bak`);
+    if (existsSync(bakPath)) {
+        if (!dryRun) {
+            try {
+                unlinkSync(bakPath);
+                removedBak = true;
+            }
+            catch { /* best-effort */ }
+        }
+        else {
+            removedBak = true;
+        }
+    }
+    return { app, removedBak, removedSnapshots, keptSnapshots, dryRun };
+}