@matthesketh/fleet 1.8.1 → 1.11.1

package/dist/core/routines/store.d.ts

@@ -109,15 +109,14 @@ declare const FileSchema: z.ZodObject<{
         createdAt: z.ZodOptional<z.ZodString>;
         updatedAt: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        enabled: boolean;
         name: string;
+        enabled: boolean;
         id: string;
         notify: {
             config: Record<string, unknown>;
             kind: "email" | "stdout" | "webhook" | "slack";
             on: "always" | "failure" | "success";
         }[];
-        description: string;
         schedule: {
             kind: "manual";
         } | {
@@ -126,6 +125,8 @@ declare const FileSchema: z.ZodObject<{
             randomizedDelaySec: number;
             persistent: boolean;
         };
+        tags: string[];
+        description: string;
         targets: string[];
         perTarget: boolean;
         task: {
@@ -149,7 +150,6 @@ declare const FileSchema: z.ZodObject<{
             tool: string;
             args: Record<string, unknown>;
         };
-        tags: string[];
         updatedAt?: string | undefined;
         createdAt?: string | undefined;
     }, {
@@ -191,25 +191,24 @@ declare const FileSchema: z.ZodObject<{
             config?: Record<string, unknown> | undefined;
             on?: "always" | "failure" | "success" | undefined;
         }[] | undefined;
+        tags?: string[] | undefined;
         description?: string | undefined;
         targets?: string[] | undefined;
         perTarget?: boolean | undefined;
-        tags?: string[] | undefined;
         createdAt?: string | undefined;
     }>, "many">;
     defaultsSeededAt: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     version: 1;
     routines: {
-        enabled: boolean;
         name: string;
+        enabled: boolean;
         id: string;
         notify: {
             config: Record<string, unknown>;
             kind: "email" | "stdout" | "webhook" | "slack";
             on: "always" | "failure" | "success";
         }[];
-        description: string;
         schedule: {
             kind: "manual";
         } | {
@@ -218,6 +217,8 @@ declare const FileSchema: z.ZodObject<{
             randomizedDelaySec: number;
             persistent: boolean;
         };
+        tags: string[];
+        description: string;
         targets: string[];
         perTarget: boolean;
         task: {
@@ -241,7 +242,6 @@ declare const FileSchema: z.ZodObject<{
             tool: string;
             args: Record<string, unknown>;
         };
-        tags: string[];
         updatedAt?: string | undefined;
         createdAt?: string | undefined;
     }[];
@@ -287,10 +287,10 @@ declare const FileSchema: z.ZodObject<{
             config?: Record<string, unknown> | undefined;
             on?: "always" | "failure" | "success" | undefined;
         }[] | undefined;
+        tags?: string[] | undefined;
         description?: string | undefined;
         targets?: string[] | undefined;
         perTarget?: boolean | undefined;
-        tags?: string[] | undefined;
         createdAt?: string | undefined;
     }[];
     defaultsSeededAt?: string | undefined;

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

@@ -8,10 +8,15 @@ export declare function safeSealApp(app: string, content: string, sourceFile: st
 export declare function safeSealDbSecrets(app: string, secretsMap: Record<string, string>, sourceDir: string): SealValidation;
 export declare function setSecret(app: string, key: string, value: string, opts?: {
     allowWeak?: boolean;
-}): void;
+}): Promise<void>;
+/** 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 declare function getSecret(app: string, key: string): string | null;
-export declare function importEnvFile(app: string, path: string): number;
-export declare function importDbSecrets(app: string, dir: string): number;
+export declare function importEnvFile(app: string, path: string): Promise<number>;
+export declare function importDbSecrets(app: string, dir: string): Promise<number>;
 export declare function exportApp(app: string): string;
 export interface DriftResult {
     app: string;
@@ -22,12 +27,32 @@ export interface DriftResult {
 }
 export declare function detectDrift(app?: string): DriftResult[];
 export declare function unsealAll(): void;
-export declare function sealFromRuntime(app?: string): string[];
-export declare function rotateKey(): {
+export declare function sealFromRuntime(app?: string): Promise<string[]>;
+/**
+ * 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 declare function rotateKey(): Promise<{
     oldPubkey: string;
     newPubkey: string;
     appsRotated: string[];
-};
+}>;
 export declare function getStatus(): {
     initialized: boolean;
     sealed: boolean;

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>;