@matthesketh/fleet 1.2.0 → 1.7.0

package/dist/core/secrets-motd.js

@@ -0,0 +1,72 @@
+/**
+ * MOTD reporter: short summary of secret rotation health, intended for
+ * /etc/update-motd.d/99-fleet-secrets to print on shell login.
+ */
+import { enumerateAllSecrets } from './secrets-metadata.js';
+export function summariseSecrets() {
+    const all = enumerateAllSecrets();
+    const stale = all.filter(s => s.stale);
+    const bySensitivity = { critical: 0, high: 0, medium: 0, low: 0 };
+    for (const s of stale) {
+        const sens = s.provider?.sensitivity ?? 'low';
+        bySensitivity[sens]++;
+    }
+    const appsWithStale = Array.from(new Set(stale.map(s => s.app))).sort();
+    const sensRank = { critical: 0, high: 1, medium: 2, low: 3 };
+    const topStale = stale
+        .slice()
+        .sort((a, b) => {
+        const sa = sensRank[a.provider?.sensitivity ?? 'low'];
+        const sb = sensRank[b.provider?.sensitivity ?? 'low'];
+        if (sa !== sb)
+            return sa - sb;
+        return (b.ageDays ?? 0) - (a.ageDays ?? 0);
+    })
+        .slice(0, 5)
+        .map(s => ({
+        app: s.app,
+        name: s.name,
+        ageDays: s.ageDays ?? 0,
+        sensitivity: s.provider?.sensitivity ?? 'low',
+    }));
+    return {
+        totalSecrets: all.length,
+        staleCount: stale.length,
+        bySensitivity,
+        appsWithStale,
+        topStale,
+    };
+}
+export function formatSecretsMotd(summary) {
+    const lines = [];
+    lines.push('-- Fleet Secrets ' + '-'.repeat(40));
+    if (summary.staleCount === 0) {
+        lines.push(`  All ${summary.totalSecrets} secrets within rotation frequency`);
+        lines.push('  Run: fleet secrets ages');
+        return lines.join('\n');
+    }
+    const parts = [];
+    if (summary.bySensitivity.critical > 0)
+        parts.push(`${summary.bySensitivity.critical} critical`);
+    if (summary.bySensitivity.high > 0)
+        parts.push(`${summary.bySensitivity.high} high`);
+    if (summary.bySensitivity.medium > 0)
+        parts.push(`${summary.bySensitivity.medium} medium`);
+    if (summary.bySensitivity.low > 0)
+        parts.push(`${summary.bySensitivity.low} low`);
+    lines.push(`  ${summary.staleCount} secrets need rotation (${parts.join(', ')}) across ${summary.appsWithStale.length} apps`);
+    for (const t of summary.topStale) {
+        const prefix = t.sensitivity === 'critical' ? '!!' : t.sensitivity === 'high' ? ' !' : '  ';
+        lines.push(`  ${prefix} ${t.app}: ${t.name} (${t.ageDays}d old)`);
+    }
+    lines.push('  Run: fleet secrets ages --stale-only');
+    lines.push('  Rotate: fleet secrets rotate <app>');
+    return lines.join('\n');
+}
+export function generateSecretsMotdScript() {
+    return `#!/bin/bash
+# fleet secrets motd — auto-generated by 'fleet secrets motd-init'
+# shows secret rotation health summary on shell login
+/usr/local/bin/fleet secrets ages --motd 2>/dev/null || true
+`;
+}

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

@@ -6,7 +6,9 @@ export interface SealValidation {
 export declare function validateBeforeSeal(app: string, newContent: string): SealValidation;
 export declare function safeSealApp(app: string, content: string, sourceFile: string): SealValidation;
 export declare function safeSealDbSecrets(app: string, secretsMap: Record<string, string>, sourceDir: string): SealValidation;
-export declare function setSecret(app: string, key: string, value: string): void;
+export declare function setSecret(app: string, key: string, value: string, opts?: {
+    allowWeak?: boolean;
+}): void;
 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;

package/dist/core/secrets-ops.js

@@ -1,10 +1,42 @@
-import { existsSync, readFileSync, writeFileSync, readdirSync, chmodSync, mkdirSync, rmSync, statSync } from 'node:fs';
-import { join } from 'node:path';
-import { execSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync, readdirSync, chmodSync, mkdirSync, rmSync, statSync, copyFileSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { timingSafeEqual } from 'node:crypto';
 import { validateAll } from './secrets-validate.js';
+import { execSafe } from './exec.js';
+import { assertAppName, assertSecretKey } from './validate.js';
 import { SecretsError } from './errors.js';
+import { auditLog } from './secrets-audit.js';
+import { checkEntropy } from './secrets-rotation.js';
+import { chownSync } from 'node:fs';
+import { load as loadRegistry } from './registry.js';
+/**
+ * Best-effort UID/GID tightening of a runtime secrets file. If the registry
+ * defines runtimeUid/runtimeGid for the app, chown to those values; otherwise
+ * leave as-is (root:root). Never throws — secret availability beats stricter
+ * perms (we already chmod'd 0600 so root-only is the floor).
+ */
+function tryTightenPerms(envPath, app) {
+    try {
+        const reg = loadRegistry();
+        const entry = reg.apps.find(a => a.name === app);
+        if (!entry?.runtimeUid && !entry?.runtimeGid)
+            return;
+        chownSync(envPath, entry.runtimeUid ?? 0, entry.runtimeGid ?? 0);
+    }
+    catch (err) {
+        // log + continue; never block unseal
+        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';
-// --- Helpers ---
+// --- helpers ---
+function safeEqual(a, b) {
+    const bufA = Buffer.from(a);
+    const bufB = Buffer.from(b);
+    if (bufA.length !== bufB.length)
+        return false;
+    return timingSafeEqual(bufA, bufB);
+}
 function parseEnvKeys(content) {
     return content.split('\n')
         .filter(l => l.includes('=') && !l.startsWith('#') && l.trim())
@@ -71,7 +103,17 @@ export function safeSealDbSecrets(app, secretsMap, sourceDir) {
     }
     return validation;
 }
-export function setSecret(app, key, value) {
+export function setSecret(app, key, value, opts = {}) {
+    assertAppName(app);
+    assertSecretKey(key);
+    // Entropy / placeholder check unless explicitly bypassed.
+    if (!opts.allowWeak) {
+        const entropyErr = checkEntropy(value);
+        if (entropyErr) {
+            auditLog({ op: 'set', app, secret: key, ok: false, details: `weak value rejected: ${entropyErr}` });
+            throw new SecretsError(`${entropyErr}. Pass --allow-weak to override (not recommended).`);
+        }
+    }
     const plaintext = decryptApp(app);
     const manifest = loadManifest();
     const entry = manifest.apps[app];
@@ -90,6 +132,7 @@ export function setSecret(app, key, value) {
     if (!found)
         updated.push(`${key}=${value}`);
     safeSealApp(app, updated.join('\n'), entry.sourceFile);
+    auditLog({ op: 'set', app, secret: key, ok: true });
 }
 export function getSecret(app, key) {
     const plaintext = decryptApp(app);
@@ -107,6 +150,10 @@ export function getSecret(app, key) {
     const files = parseSecretsBundle(plaintext);
     return files[key] ?? null;
 }
+// Note: getSecret is read-only; we audit at the command layer to record
+// 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) {
     if (!existsSync(path))
         throw new SecretsError(`File not found: ${path}`);
@@ -119,9 +166,11 @@ export function importEnvFile(app, path) {
     }
     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;
 }
 export function importDbSecrets(app, dir) {
@@ -148,6 +197,7 @@ export function importDbSecrets(app, dir) {
     return files.length;
 }
 export function exportApp(app) {
+    auditLog({ op: 'export', app, ok: true });
     return decryptApp(app);
 }
 export function detectDrift(app) {
@@ -172,7 +222,7 @@ export function detectDrift(app) {
             const runtimeMap = parseEnvMap(runtimeContent);
             const addedKeys = Object.keys(runtimeMap).filter(k => !(k in vaultMap));
             const removedKeys = Object.keys(vaultMap).filter(k => !(k in runtimeMap));
-            const changedKeys = Object.keys(vaultMap).filter(k => k in runtimeMap && vaultMap[k] !== runtimeMap[k]);
+            const changedKeys = Object.keys(vaultMap).filter(k => k in runtimeMap && !safeEqual(vaultMap[k], runtimeMap[k]));
             const status = (addedKeys.length || removedKeys.length || changedKeys.length) ? 'drifted' : 'in-sync';
             results.push({ app: a, status, addedKeys, removedKeys, changedKeys });
         }
@@ -191,7 +241,7 @@ export function detectDrift(app) {
             }
             const addedKeys = runtimeFiles.filter(f => !(f in vaultFiles));
             const removedKeys = Object.keys(vaultFiles).filter(f => !(f in runtimeMap));
-            const changedKeys = Object.keys(vaultFiles).filter(f => f in runtimeMap && vaultFiles[f] !== runtimeMap[f]);
+            const changedKeys = Object.keys(vaultFiles).filter(f => f in runtimeMap && !safeEqual(vaultFiles[f], runtimeMap[f]));
             const status = (addedKeys.length || removedKeys.length || changedKeys.length) ? 'drifted' : 'in-sync';
             results.push({ app: a, status, addedKeys, removedKeys, changedKeys });
         }
@@ -213,6 +263,7 @@ function parseEnvMap(content) {
 // --- Phase 4: Improved unseal (validate before write) ---
 export function unsealAll() {
     const manifest = loadManifest();
+    auditLog({ op: 'unseal', ok: true, details: `apps=${Object.keys(manifest.apps).length}` });
     // Phase 4: Decrypt all apps first and validate BEFORE writing to runtime
     const decrypted = {};
     for (const [app, entry] of Object.entries(manifest.apps)) {
@@ -243,17 +294,29 @@ export function unsealAll() {
             const envPath = join(appDir, '.env');
             writeFileSync(envPath, plaintext);
             chmodSync(envPath, 0o600);
+            // Optional UID/GID tightening (registry.runtimeUid/runtimeGid). Default
+            // root:root if unset. Failures are non-fatal — if the UID doesn't exist
+            // we'd rather have the secret available than fail boot.
+            tryTightenPerms(envPath, app);
         }
         else if (entry.type === 'secrets-dir') {
             const secretsDir = join(RUNTIME_DIR, app, 'secrets');
             if (!existsSync(secretsDir))
-                mkdirSync(secretsDir, { recursive: true, mode: 0o755 });
+                mkdirSync(secretsDir, { recursive: true, mode: 0o700 });
             const parsed = parseSecretsBundle(plaintext);
             for (const [filename, content] of Object.entries(parsed)) {
-                const fpath = join(secretsDir, filename);
+                const safe = basename(filename);
+                if (safe !== filename || filename.includes('..')) {
+                    throw new SecretsError(`Invalid secret filename: ${filename}`);
+                }
+                const fpath = join(secretsDir, safe);
                 writeFileSync(fpath, content);
-                // 0644: docker compose secrets bind-mounts files into containers where
-                // non-root processes (e.g. mongodb uid 999) need read access
+                // 0644: docker bind-mounts these files into containers where non-root
+                // processes need read access. group-only (0640) breaks mongo's
+                // entrypoint, which reads the password file as uid 999 (mongodb)
+                // without first reading as root the way postgres does. host security
+                // still relies on the parent dir being 0700 root:root, so 0644 here
+                // does not widen host exposure.
                 chmodSync(fpath, 0o644);
             }
         }
@@ -297,8 +360,10 @@ export function rotateKey() {
         decrypted[app] = ageDecryptFile(join(VAULT_DIR, entry.encryptedFile));
     }
     const backupPath = KEY_PATH + '.old';
-    execSync(`cp ${KEY_PATH} ${backupPath}`);
-    execSync(`age-keygen -o ${KEY_PATH} 2>/dev/null`);
+    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)) {

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

@@ -0,0 +1,50 @@
+/**
+ * Provider registry: maps secret names to provider metadata used by
+ * `fleet secrets rotate` and `fleet secrets ages`.
+ *
+ * Adding a new provider: append to PROVIDERS. Order matters — the FIRST
+ * matching entry wins, so put more specific patterns before generic ones.
+ *
+ * Strategy reference:
+ *   - immediate     : replace value, old dies instantly. Safe for upstream API keys.
+ *   - dual-mode     : new value becomes primary, old is kept as <NAME>_PREVIOUS for a
+ *                     grace period so existing user sessions/tokens still verify.
+ *                     Requires app code to read the _PREVIOUS variant as a fallback.
+ *   - at-rest-key   : encrypts data sitting in storage. Rotating without re-encrypting
+ *                     bricks the data. Refused unless --data-migrated is passed.
+ *   - user-issued   : tokens YOU give to YOUR users. Rotating yours doesn't help —
+ *                     redirected to per-user rotation tooling.
+ */
+export type RotationStrategy = 'immediate' | 'dual-mode' | 'at-rest-key' | 'user-issued';
+export type Sensitivity = 'low' | 'medium' | 'high' | 'critical';
+export interface ProviderDef {
+    /** Stable id for manifest persistence. */
+    id: string;
+    /** Pattern matched against the secret name (env var key). */
+    matches: RegExp;
+    /** Human label shown in the UI. */
+    name: string;
+    /** Where to go to regenerate this secret. */
+    url?: string;
+    /** Numbered, copy-pasteable rotation steps. */
+    instructions?: string;
+    /** Format the new value should match. Used to validate paste. */
+    format?: RegExp;
+    /** Severity if this leaks. Drives MOTD ordering. */
+    sensitivity: Sensitivity;
+    /** How often this secret should be rotated, in days. Drives staleness. */
+    rotationFrequencyDays: number;
+    /** How rotation should be performed. See file header. */
+    strategy: RotationStrategy;
+    /** Optional: pretty companion env var name for dual-mode rotations. */
+    previousVarName?: (varName: string) => string;
+}
+export declare const PROVIDERS: ProviderDef[];
+/** Find the provider definition that matches the given secret name. */
+export declare function classifySecret(name: string): ProviderDef | null;
+/** Look up by stored provider id (for round-tripping after manifest persistence). */
+export declare function getProviderById(id: string): ProviderDef | null;
+/** Days since a timestamp. Null if invalid. */
+export declare function ageInDays(iso: string | undefined): number | null;
+/** True if the secret is older than its provider's rotationFrequencyDays. */
+export declare function isStale(age: number | null, provider: ProviderDef | null): boolean;

package/dist/core/secrets-providers.js

@@ -0,0 +1,291 @@
+/**
+ * Provider registry: maps secret names to provider metadata used by
+ * `fleet secrets rotate` and `fleet secrets ages`.
+ *
+ * Adding a new provider: append to PROVIDERS. Order matters — the FIRST
+ * matching entry wins, so put more specific patterns before generic ones.
+ *
+ * Strategy reference:
+ *   - immediate     : replace value, old dies instantly. Safe for upstream API keys.
+ *   - dual-mode     : new value becomes primary, old is kept as <NAME>_PREVIOUS for a
+ *                     grace period so existing user sessions/tokens still verify.
+ *                     Requires app code to read the _PREVIOUS variant as a fallback.
+ *   - at-rest-key   : encrypts data sitting in storage. Rotating without re-encrypting
+ *                     bricks the data. Refused unless --data-migrated is passed.
+ *   - user-issued   : tokens YOU give to YOUR users. Rotating yours doesn't help —
+ *                     redirected to per-user rotation tooling.
+ */
+const previousAsSuffix = (n) => `${n}_PREVIOUS`;
+export const PROVIDERS = [
+    // ── Stripe ───────────────────────────────────────────────────────────────
+    {
+        id: 'stripe-secret-key',
+        matches: /^STRIPE_SECRET_KEY$/,
+        name: 'Stripe Secret Key',
+        url: 'https://dashboard.stripe.com/apikeys',
+        instructions: '1. Click "Create secret key" (or "Create restricted key" — both work here)\n' +
+            '2. Set restrictions if desired (RESTRICTED keys are recommended for least-privilege)\n' +
+            '3. Copy the new sk_live_... or rk_live_... value and paste below\n' +
+            '4. After confirming the new key works, revoke the old one in the dashboard',
+        // Accept both standard (sk_) and restricted (rk_) Stripe API keys. Both are
+        // valid values for the STRIPE_SECRET_KEY env var; restricted keys are
+        // Stripe's recommended pattern for least-privilege production use.
+        format: /^(sk|rk)_(live|test)_[A-Za-z0-9]{40,}$/,
+        sensitivity: 'critical',
+        rotationFrequencyDays: 90,
+        strategy: 'immediate',
+    },
+    {
+        id: 'stripe-restricted-key',
+        matches: /^STRIPE_RESTRICTED_KEY$/,
+        name: 'Stripe Restricted Key',
+        url: 'https://dashboard.stripe.com/apikeys',
+        format: /^rk_(live|test)_[A-Za-z0-9]{40,}$/,
+        sensitivity: 'high',
+        rotationFrequencyDays: 90,
+        strategy: 'immediate',
+    },
+    {
+        id: 'stripe-webhook-secret',
+        matches: /^STRIPE_WEBHOOK_SECRET$/,
+        name: 'Stripe Webhook Signing Secret',
+        url: 'https://dashboard.stripe.com/webhooks',
+        instructions: '1. Click your webhook endpoint\n' +
+            '2. Click "Roll secret"\n' +
+            '3. Copy the new whsec_... value and paste below',
+        format: /^whsec_[A-Za-z0-9]{20,}$/,
+        sensitivity: 'high',
+        rotationFrequencyDays: 90,
+        strategy: 'immediate',
+    },
+    // ── GitHub ───────────────────────────────────────────────────────────────
+    {
+        id: 'github-pat-classic',
+        matches: /^(GITHUB_TOKEN|GH_TOKEN|GITHUB_PAT)$/,
+        name: 'GitHub Personal Access Token',
+        url: 'https://github.com/settings/tokens',
+        instructions: '1. Click "Generate new token (classic)" or use a fine-grained token\n' +
+            '2. Match the scopes/permissions of the existing token\n' +
+            '3. Copy the new ghp_... or github_pat_... value and paste below\n' +
+            '4. Delete the old token from the same page once confirmed working',
+        format: /^(ghp_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{50,})$/,
+        sensitivity: 'critical',
+        rotationFrequencyDays: 90,
+        strategy: 'immediate',
+    },
+    // ── AI providers ─────────────────────────────────────────────────────────
+    {
+        id: 'anthropic-api-key',
+        matches: /^ANTHROPIC_API_KEY$/,
+        name: 'Anthropic API Key',
+        url: 'https://console.anthropic.com/settings/keys',
+        format: /^sk-ant-[A-Za-z0-9_\-]{40,}$/,
+        sensitivity: 'high',
+        rotationFrequencyDays: 90,
+        strategy: 'immediate',
+    },
+    {
+        id: 'openai-api-key',
+        matches: /^OPENAI_API_KEY$/,
+        name: 'OpenAI API Key',
+        url: 'https://platform.openai.com/api-keys',
+        format: /^sk-(proj-)?[A-Za-z0-9_\-]{20,}$/,
+        sensitivity: 'high',
+        rotationFrequencyDays: 90,
+        strategy: 'immediate',
+    },
+    // ── Google ───────────────────────────────────────────────────────────────
+    {
+        id: 'google-oauth-client-secret',
+        matches: /^(GOOGLE_CLIENT_SECRET|GOOGLE_OAUTH_CLIENT_SECRET)$/,
+        name: 'Google OAuth Client Secret',
+        url: 'https://console.cloud.google.com/apis/credentials',
+        instructions: '1. Open the OAuth 2.0 Client ID for this app\n' +
+            '2. Add a new client secret (Google now supports multiple)\n' +
+            '3. Paste the new GOCSPX-... value below\n' +
+            '4. Delete the old secret from the same page after verifying',
+        format: /^GOCSPX-[A-Za-z0-9_\-]{20,}$/,
+        sensitivity: 'high',
+        rotationFrequencyDays: 180,
+        strategy: 'immediate',
+    },
+    {
+        id: 'google-api-key',
+        matches: /^(GOOGLE_API_KEY|GMAPS_API_KEY|GEMINI_API_KEY)$/,
+        name: 'Google API Key',
+        url: 'https://console.cloud.google.com/apis/credentials',
+        format: /^AIza[0-9A-Za-z_\-]{35}$/,
+        sensitivity: 'medium',
+        rotationFrequencyDays: 180,
+        strategy: 'immediate',
+    },
+    {
+        id: 'gmail-app-password',
+        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' +
+            '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
+        // displays them with spaces every 4 chars for readability but expects
+        // them WITHOUT spaces in the SMTP password field — we accept only the
+        // de-spaced form so a paste-as-displayed gets rejected with a clear error.
+        format: /^[a-z0-9]{16}$/,
+        sensitivity: 'critical',
+        rotationFrequencyDays: 90,
+        strategy: 'immediate',
+    },
+    // ── App-internal cryptographic secrets (DUAL-MODE — preserves user sessions) ─
+    {
+        id: 'jwt-secret',
+        matches: /^(JWT_SECRET|JWT_SIGNING_SECRET|JWT_PRIVATE_KEY)$/,
+        name: 'JWT Signing Secret',
+        instructions: 'Generate a fresh high-entropy value (e.g. `openssl rand -base64 64`).\n' +
+            'NOTE: Your app must read JWT_SECRET_PREVIOUS as a fallback verifier so\n' +
+            'existing tokens stay valid through the grace period.',
+        sensitivity: 'critical',
+        rotationFrequencyDays: 180,
+        strategy: 'dual-mode',
+        previousVarName: previousAsSuffix,
+    },
+    {
+        id: 'nextauth-secret',
+        matches: /^(NEXTAUTH_SECRET|AUTH_SECRET)$/,
+        name: 'NextAuth / Auth.js Secret',
+        instructions: 'Generate with `openssl rand -base64 64`.\n' +
+            'NextAuth supports multiple secrets in v5; configure both new and previous so\n' +
+            'logged-in users remain logged in.',
+        sensitivity: 'critical',
+        rotationFrequencyDays: 180,
+        strategy: 'dual-mode',
+        previousVarName: previousAsSuffix,
+    },
+    {
+        id: 'session-secret',
+        matches: /^(SESSION_SECRET|COOKIE_SECRET|EXPRESS_SESSION_SECRET)$/,
+        name: 'Session / Cookie Signing Secret',
+        instructions: 'Generate with `openssl rand -base64 64`.',
+        sensitivity: 'high',
+        rotationFrequencyDays: 180,
+        strategy: 'dual-mode',
+        previousVarName: previousAsSuffix,
+    },
+    {
+        id: 'csrf-secret',
+        matches: /^(CSRF_SECRET|CSRF_TOKEN_SECRET)$/,
+        name: 'CSRF Token Secret',
+        instructions: 'Generate with `openssl rand -base64 64`.',
+        sensitivity: 'medium',
+        rotationFrequencyDays: 180,
+        strategy: 'dual-mode',
+        previousVarName: previousAsSuffix,
+    },
+    // ── Encryption-at-rest (REFUSED unless --data-migrated) ──────────────────
+    {
+        id: 'data-encryption-key',
+        matches: /^(ENCRYPTION_KEY|DATA_ENCRYPTION_KEY|FIELD_ENCRYPTION_KEY|AT_REST_KEY)$/,
+        name: 'At-Rest Data Encryption Key',
+        instructions: 'WARNING: Rotating this without re-encrypting stored data will make the data\n' +
+            'unreadable. Re-encrypt all data with the new key BEFORE rotation, then run:\n' +
+            '  fleet secrets rotate <app> <KEY> --data-migrated',
+        sensitivity: 'critical',
+        rotationFrequencyDays: 365,
+        strategy: 'at-rest-key',
+    },
+    // ── Bookwhen (used by macpool) ───────────────────────────────────────────
+    {
+        id: 'bookwhen-token',
+        matches: /^BOOKWHEN_API_TOKEN$/,
+        name: 'Bookwhen API Token',
+        url: 'https://bookwhen.com/account/api',
+        sensitivity: 'medium',
+        rotationFrequencyDays: 180,
+        strategy: 'immediate',
+    },
+    // ── Database connection strings ──────────────────────────────────────────
+    {
+        id: 'database-url',
+        matches: /^(DATABASE_URL|MONGO_URL|REDIS_URL|POSTGRES_URL|MYSQL_URL)$/,
+        name: 'Database Connection String',
+        instructions: 'Update the password component only — keep host, port, db unchanged.\n' +
+            'Rotate the underlying DB user password first, then update this URL.',
+        sensitivity: 'critical',
+        rotationFrequencyDays: 180,
+        strategy: 'immediate',
+    },
+    // ── AWS ──────────────────────────────────────────────────────────────────
+    {
+        id: 'aws-access-key',
+        matches: /^AWS_ACCESS_KEY_ID$/,
+        name: 'AWS Access Key ID',
+        url: 'https://console.aws.amazon.com/iam/home#/security_credentials',
+        format: /^AKIA[0-9A-Z]{16}$/,
+        sensitivity: 'critical',
+        rotationFrequencyDays: 90,
+        strategy: 'immediate',
+    },
+    {
+        id: 'aws-secret-key',
+        matches: /^AWS_SECRET_ACCESS_KEY$/,
+        name: 'AWS Secret Access Key',
+        url: 'https://console.aws.amazon.com/iam/home#/security_credentials',
+        format: /^[A-Za-z0-9/+=]{40}$/,
+        sensitivity: 'critical',
+        rotationFrequencyDays: 90,
+        strategy: 'immediate',
+    },
+    // ── Tokens we issue to OUR users (refused — rotate per user) ─────────────
+    {
+        id: 'user-issued-token',
+        matches: /^(USER_API_TOKEN|CUSTOMER_API_KEYS|TENANT_TOKENS)$/,
+        name: 'User-Issued Token',
+        instructions: 'These are tokens YOU issue to YOUR users. Rotating yours does nothing — you\n' +
+            'need a per-user revocation flow in your app to invalidate them.',
+        sensitivity: 'high',
+        rotationFrequencyDays: 365,
+        strategy: 'user-issued',
+    },
+    // ── Generic fallback ─────────────────────────────────────────────────────
+    // Anything looking like a secret name but not specifically known.
+    // Require an explicit `_` boundary before the suffix (so `MONKEY` and
+    // `BROKEN_KEY` no longer match) and exclude `PUBLIC_KEY` / `PUB_KEY`
+    // which are not secrets despite ending in KEY.
+    {
+        id: 'generic-secret',
+        matches: /^(?!.*(?:PUBLIC_KEY|PUB_KEY)$).*_(SECRET|TOKEN|KEY|PASSWORD|PRIVATE)$/i,
+        name: 'Generic Secret',
+        instructions: 'Generate a fresh high-entropy value, e.g. `openssl rand -base64 32`.',
+        sensitivity: 'medium',
+        rotationFrequencyDays: 180,
+        strategy: 'immediate',
+    },
+];
+/** Find the provider definition that matches the given secret name. */
+export function classifySecret(name) {
+    for (const p of PROVIDERS) {
+        if (p.matches.test(name))
+            return p;
+    }
+    return null;
+}
+/** Look up by stored provider id (for round-tripping after manifest persistence). */
+export function getProviderById(id) {
+    return PROVIDERS.find(p => p.id === id) ?? null;
+}
+/** Days since a timestamp. Null if invalid. */
+export function ageInDays(iso) {
+    if (!iso)
+        return null;
+    const t = Date.parse(iso);
+    if (isNaN(t))
+        return null;
+    const ms = Date.now() - t;
+    return Math.floor(ms / (1000 * 60 * 60 * 24));
+}
+/** True if the secret is older than its provider's rotationFrequencyDays. */
+export function isStale(age, provider) {
+    if (age == null || provider == null)
+        return false;
+    return age >= provider.rotationFrequencyDays;
+}

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

@@ -0,0 +1,52 @@
+/**
+ * Rotation engine: takes a parsed plaintext env, applies a per-secret rotation
+ * (immediate, dual-mode, etc.), re-seals, restarts the service, runs a health
+ * 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 { type ProviderDef } from './secrets-providers.js';
+/** Mask a NEW (just-entered) secret value for confirmation display. */
+export declare function maskNewValue(value: string): string;
+/** Validate against provider format if any. Returns null on pass, error string on fail. */
+export declare function validateFormat(value: string, provider: ProviderDef | null): string | null;
+/** Reject obvious placeholders / low-entropy strings. */
+export declare function checkEntropy(value: string): string | null;
+/**
+ * Parse an .env-style plaintext into ordered entries. Preserves comments
+ * and blank lines so a re-serialised file is diff-friendly.
+ */
+export type EnvLine = {
+    kind: 'kv';
+    key: string;
+    value: string;
+} | {
+    kind: 'raw';
+    text: string;
+};
+export declare function parseEnv(plaintext: string): EnvLine[];
+export declare function serialiseEnv(lines: EnvLine[]): string;
+/**
+ * Apply a single secret update. For dual-mode strategies, the OLD value is
+ * preserved as <NAME>_PREVIOUS so the app can verify legacy tokens during
+ * the grace period. Returns the new env content.
+ */
+export declare function applyRotation(plaintext: string, key: string, newValue: string, strategy: 'immediate' | 'dual-mode' | 'at-rest-key' | 'user-issued'): string;
+export interface RotationResult {
+    app: string;
+    key: string;
+    strategy: string;
+    snapshot: string;
+    rolledBack: boolean;
+    reason?: string;
+}
+/**
+ * Full rotation pipeline. Caller is expected to have already collected and
+ * validated the new value via the interactive prompts. This orchestrates
+ * snapshot → seal → audit. Restart + health-gate are caller's responsibility
+ * (we want the engine pure-ish so it's easy to test).
+ */
+export declare function performRotation(app: string, key: string, newValue: string, opts?: {
+    dryRun?: boolean;
+    notes?: string;
+    dataMigrated?: boolean;
+}): RotationResult;