@stacksjs/buddy 0.70.229 → 0.70.230

package/dist/commands/build.js

@@ -96,7 +96,8 @@ export function build(buddy) {
   });
   buddy.command("build:components", "Automagically build component libraries for production use & npm/CDN distribution").alias("prod:components").option("-c, --components", descriptions.components, { default: !0 }).option("-p, --project [project]", descriptions.project, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (options) => {
     log.debug("Running `buddy build:components` ...", options);
-    await runAction(Action.BuildComponentLibs, options);
+    if (!await runBuildAction(Action.BuildComponentLibs, "component libraries"))
+      process.exit(ExitCode.FatalError);
   });
   buddy.command("build:cli", descriptions.cli).alias("prod:cli").option("-b, --buddy", descriptions.buddy, { default: !0 }).option("-p, --project [project]", descriptions.project, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (options) => {
     log.debug("Running `buddy build:cli` ...", options);
@@ -114,7 +115,8 @@ export function build(buddy) {
     default: !0
   }).option("-p, --project [project]", descriptions.project, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (options) => {
     log.debug("Running `buddy build:web-components` ...", options);
-    await runAction(Action.BuildWebComponentLib, options);
+    if (!await runBuildAction(Action.BuildWebComponentLib, "web component library"))
+      process.exit(ExitCode.FatalError);
   });
   buddy.command("build:frontend", descriptions.pages).alias("build:pages").alias("build:views").alias("prod:frontend").option("-p, --project [project]", descriptions.project, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (options) => {
     log.debug("Running `buddy build:frontend` ...", options);

package/dist/commands/create.js

@@ -1,4 +1,4 @@
-import { chmodSync } from "node:fs";
+import { chmodSync, existsSync, readdirSync } from "node:fs";
 import process from "node:process";
 import { runAction } from "@stacksjs/actions";
 import { bold, cyan, dim, intro, log, onUnknownSubcommand, runCommand } from "@stacksjs/cli";
@@ -24,9 +24,10 @@ export function create(buddy) {
     email: "Do you need email?",
     project: "Target a specific project",
     minimal: "Skip optional feature bundles (cms, commerce, dashboard, marketing, monitoring, realtime, queue) \u2014 bare-bones API/SPA starter that can re-add them later via `./buddy <feature>:install`.",
+    withCore: "Keep the framework vendored in `storage/framework/core` as a Bun workspace, for working ON Stacks. Apps that only work WITH Stacks want the default, which resolves every @stacksjs/* package from npm.",
     verbose: "Enable verbose output"
   };
-  buddy.command("new [name]", descriptions.command).alias("create [name]").option("-n, --name [name]", descriptions.name, { default: !1 }).option("-u, --ui", descriptions.ui, { default: !0 }).option("-c, --components", descriptions.components, { default: !0 }).option("-w, --web-components", descriptions.webComponents, { default: !0 }).option("-p, --views", descriptions.views, { default: !0 }).option("-f, --functions", descriptions.functions, { default: !0 }).option("-a, --api", descriptions.api, { default: !0 }).option("-d, --database", descriptions.database, { default: !0 }).option("-ca, --cache", descriptions.cache, { default: !1 }).option("-e, --email", descriptions.email, { default: !1 }).option("-P, --project [project]", descriptions.project, { default: !1 }).option("-m, --minimal", descriptions.minimal, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (name, options) => {
+  buddy.command("new [name]", descriptions.command).alias("create [name]").option("-n, --name [name]", descriptions.name, { default: !1 }).option("-u, --ui", descriptions.ui, { default: !0 }).option("-c, --components", descriptions.components, { default: !0 }).option("-w, --web-components", descriptions.webComponents, { default: !0 }).option("-p, --views", descriptions.views, { default: !0 }).option("-f, --functions", descriptions.functions, { default: !0 }).option("-a, --api", descriptions.api, { default: !0 }).option("-d, --database", descriptions.database, { default: !0 }).option("-ca, --cache", descriptions.cache, { default: !1 }).option("-e, --email", descriptions.email, { default: !1 }).option("-P, --project [project]", descriptions.project, { default: !1 }).option("-m, --minimal", descriptions.minimal, { default: !1 }).option("--with-core", descriptions.withCore, { default: !1 }).option("--verbose", descriptions.verbose, { default: !1 }).action(async (name, options) => {
     log.debug("Running `buddy new <name>` ...", options);
     const startTime = await intro("buddy new");
     name = name ?? options.name;
@@ -41,6 +42,8 @@ export function create(buddy) {
     ensureExecutableScripts(path);
     await ensureEnv(path, options);
     await install(path, options);
+    if (!options.withCore)
+      await unvendorCore(path, options);
     if (options.minimal)
       await stripFeatures(path);
     if (startTime) {
@@ -56,10 +59,12 @@ export function create(buddy) {
   onUnknownSubcommand(buddy, "new");
 }
 function isFolderCheck(path) {
-  if (isFolder(path)) {
-    log.error(`Path ${path} already exists`);
-    process.exit(ExitCode.FatalError);
-  }
+  if (!isFolder(path))
+    return;
+  if (readdirSync(path).filter((entry) => entry !== ".git").length === 0)
+    return;
+  log.error(`Path ${path} already exists`);
+  process.exit(ExitCode.FatalError);
 }
 async function onlineCheck() {
   if (await isOnline())
@@ -82,7 +87,7 @@ async function download(name, path, _options) {
   log.info("Setting up your stack.");
   try {
     const { downloadTemplate } = await import("@stacksjs/gitit");
-    await downloadTemplate("gh:stacksjs/stacks", { dir: name });
+    await downloadTemplate("gh:stacksjs/stacks", { dir: name, force: !0 });
     log.success(`Successfully scaffolded your project at ${cyan(path)}`);
     return { isErr: !1 };
   } catch (error) {
@@ -119,13 +124,26 @@ async function install(path, options) {
     log.error(keyResult.error);
     process.exit(ExitCode.FatalError);
   }
-  log.info("Initializing git repository...");
-  result = await runCommand("git init", { ...options, cwd: path });
+  if (existsSync(resolve(path, ".git")))
+    log.info("Existing git repository detected, skipping git init");
+  else {
+    log.info("Initializing git repository...");
+    result = await runCommand("git init", { ...options, cwd: path });
+    if (result.isErr) {
+      log.error(result.error);
+      process.exit(ExitCode.FatalError);
+    }
+  }
+  log.success("Installed & set-up \uD83D\uDE80");
+}
+async function unvendorCore(path, options) {
+  log.info("Resolving the framework from npm (pass --with-core to keep it vendored)...");
+  const result = await runCommand("./buddy unpublish:core --all --force", { ...options, cwd: path });
   if (result.isErr) {
     log.error(result.error);
     process.exit(ExitCode.FatalError);
   }
-  log.success("Installed & set-up \uD83D\uDE80");
+  log.success("Framework resolved from npm");
 }
 async function stripFeatures(path) {
   log.info("Stripping optional feature bundles (--minimal)...");

package/dist/commands/deploy.js

@@ -1163,7 +1163,8 @@ if [ -n "$DOMAIN" ] && [ -f "$CERTFILE" ] && [ -d /opt/tlsx ]; then
       ;;
   esac
 fi
-# 4) Merge auto-forward rules into forwards.json (live-reloaded; no restart).
+# 4) Merge auto-forward rules and compile the canonical RFC 5228 runtime script
+# (live-reloaded; no restart).
 if [ -n "$FWD_B64" ] && [ -x /usr/local/bin/bun ]; then
   echo "$FWD_B64" | base64 -d > /tmp/.mailtenant-fwd.json
   echo "$README_B64" | base64 -d > /tmp/.mailtenant-readme.txt
@@ -1190,6 +1191,12 @@ if [ -s /tmp/.mailtenant-err ]; then echo "FWDERR:$(head -c 200 /tmp/.mailtenant
 rm -f /tmp/.mailtenant-err
   chown mail-server:mail-server "$FJSON" 2>/dev/null || true
   chmod 644 "$FJSON" 2>/dev/null || true
+  if [ -x /usr/local/sbin/mail-forward-compile ]; then
+    if ! /usr/local/sbin/mail-forward-compile "$FJSON" /opt/mail/forwards.sieve 2>/tmp/.mailtenant-sieve-err; then
+      echo "SIEVEERR:$(head -c 200 /tmp/.mailtenant-sieve-err | tr '\\n' ' ')"
+    fi
+    rm -f /tmp/.mailtenant-sieve-err
+  fi
   rm -f /tmp/.mailtenant-fwd.json /tmp/.mailtenant-readme.txt
 fi
 FWD_STATE=nochange; grep -q FWDCHANGED /tmp/.mailtenant-res 2>/dev/null && FWD_STATE=updated; rm -f /tmp/.mailtenant-res

package/dist/commands/email.js

@@ -1,6 +1,7 @@
 import { readFileSync, existsSync } from "node:fs";
 import process from "node:process";
 import { email as emailConfig } from "@stacksjs/config";
+import { extractEmailPreview } from "@stacksjs/email";
 import { ExitCode } from "@stacksjs/types";
 import { onUnknownSubcommand } from "@stacksjs/cli";
 import { getErrorMessage } from "@stacksjs/utils";
@@ -412,14 +413,7 @@ Configuration:`);
           const rawEmail = await withTimeout(s3.getObject(bucketName, obj.Key), 15000);
           if (!rawEmail)
             continue;
-          const headers = parseRawEmailHeaders(rawEmail), messageId = obj.Key.split("/").pop() || obj.Key, from = extractEmailAddress(headers.from || ""), fromName = extractEmailName(headers.from || ""), toList = (headers.to || "").split(",").map((s) => s.trim()).filter(Boolean), subject = headers.subject || "No Subject", date = headers.date || (obj.LastModified ? new Date(obj.LastModified).toISOString() : new Date().toISOString());
-          let preview = "";
-          const bodyStart = rawEmail.indexOf(`\r
-\r
-`);
-          if (bodyStart > 0)
-            preview = rawEmail.substring(bodyStart + 4, bodyStart + 500).replace(/<[^>]+>/g, "").replace(/\s+/g, " ").trim().substring(0, 200);
-          const recipients = toList.length > 0 ? toList : [`unknown@${domain}`];
+          const headers = parseRawEmailHeaders(rawEmail), messageId = obj.Key.split("/").pop() || obj.Key, from = extractEmailAddress(headers.from || ""), fromName = extractEmailName(headers.from || ""), toList = (headers.to || "").split(",").map((s) => s.trim()).filter(Boolean), subject = headers.subject || "No Subject", date = headers.date || (obj.LastModified ? new Date(obj.LastModified).toISOString() : new Date().toISOString()), preview = extractEmailPreview(rawEmail), recipients = toList.length > 0 ? toList : [`unknown@${domain}`];
           for (const recipient of recipients) {
             const recipientEmail = extractEmailAddress(recipient);
             if (!recipientEmail.endsWith(`@${domain}`))

package/dist/commands/features.d.ts

@@ -163,10 +163,10 @@ export declare const FEATURE_FILES: Record<FeatureName, readonly string[]>;
  * @defaultValue
  * ```ts
  * {
- *   cms: ['posts', 'pages', 'comments', 'tags', 'authors', 'categories'],
- *   commerce: [ 'products', 'product_variants', 'product_units', 'manufacturers', 'orders', 'order_items', 'carts', 'cart_items', 'payments', 'payment_methods', 'payment_products', 'payment_transactions', 'customers', 'subscribers', 'subscriber_emails', 'subscriptions', 'gift_cards', 'coupons', 'transactions', 'reviews', 'drivers', 'delivery_routes', 'digital_deliveries', 'shipping_methods', 'shipping_rates', 'shipping_zones', 'license_keys', 'loyalty_points', 'loyalty_rewards', 'print_devices', 'receipts', 'tax_rates', 'waitlist_products', 'waitlist_restaurants', ],
+ *   cms: [ 'posts', 'pages', 'comments', 'tags', 'authors', 'categories', 'taggable_models', 'categorizable_models', 'commentables', ],
+ *   commerce: [ 'products', 'product_variants', 'product_units', 'manufacturers', 'orders', 'order_items', 'order_idempotency', 'carts', 'cart_items', 'payments', 'payment_methods', 'payment_products', 'payment_transactions', 'customers', 'subscribers', 'subscriber_emails', 'subscriptions', 'gift_cards', 'coupons', 'transactions', 'reviews', 'drivers', 'delivery_routes', 'digital_deliveries', 'shipping_methods', 'shipping_rates', 'shipping_zones', 'license_keys', 'loyalty_points', 'loyalty_rewards', 'print_devices', 'receipts', 'tax_rates', 'waitlist_products', 'waitlist_restaurants', ],
  *   dashboard: [ 'boards', 'board_columns', 'cards', 'card_labels', 'card_assignees', 'card_comments', 'labels', 'ci_run_states', 'ci_runner_samples', 'ci_runner_alert_states', 'requests', 'logs', ],
- *   marketing: [],
+ *   marketing: [ 'campaigns', 'campaign_sends', 'email_lists', 'email_list_subscribers', 'social_posts', 'mail_preferences', ],
  *   monitoring: ['errors'],
  *   realtime: ['websockets'],
  *   queue: ['jobs', 'failed_jobs']

package/dist/commands/features.js

@@ -72,7 +72,17 @@ export const FEATURE_NAMES = [
     "resources/views/dashboard/jobs/"
   ]
 }, FEATURE_TABLES = {
-  cms: ["posts", "pages", "comments", "tags", "authors", "categories"],
+  cms: [
+    "posts",
+    "pages",
+    "comments",
+    "tags",
+    "authors",
+    "categories",
+    "taggable_models",
+    "categorizable_models",
+    "commentables"
+  ],
   commerce: [
     "products",
     "product_variants",
@@ -80,6 +90,7 @@ export const FEATURE_NAMES = [
     "manufacturers",
     "orders",
     "order_items",
+    "order_idempotency",
     "carts",
     "cart_items",
     "payments",
@@ -123,7 +134,14 @@ export const FEATURE_NAMES = [
     "requests",
     "logs"
   ],
-  marketing: [],
+  marketing: [
+    "campaigns",
+    "campaign_sends",
+    "email_lists",
+    "email_list_subscribers",
+    "social_posts",
+    "mail_preferences"
+  ],
   monitoring: ["errors"],
   realtime: ["websockets"],
   queue: ["jobs", "failed_jobs"]

package/dist/commands/mail.js

@@ -2,9 +2,9 @@ var {require}=import.meta;import { log, runCommand } from "@stacksjs/cli";
 import { ExitCode } from "@stacksjs/types";
 import { getErrorMessage } from "@stacksjs/utils";
 import { CLI } from "@stacksjs/clapp";
-import { createHash, createHmac, randomBytes } from "crypto";
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "crypto";
 import { readFileSync, existsSync } from "node:fs";
-import { execSync } from "node:child_process";
+import { execSync, spawnSync } from "node:child_process";
 export function resolveDirectMailHost(env = process.env) {
   let configured = env.MAIL_SERVER_HOST || (env.HCLOUD_TOKEN || env.HETZNER_API_TOKEN ? env.MAIL_HOST : void 0);
   if (configured && ["127.0.0.1", "localhost", "mailpit"].includes(configured))
@@ -40,6 +40,410 @@ async function resolveOperationalMailHost() {
   const { email } = await import("@stacksjs/config");
   return email?.domain ? `mail.${email.domain}` : void 0;
 }
+const mailStorageRemote = "/usr/local/sbin/mail-storage-external";
+function loadMailStorageAws(options) {
+  const profile = options.profile || process.env.AWS_PROFILE || "default", region = options.region || process.env.AWS_REGION || "us-east-1";
+  process.env.AWS_PROFILE = profile;
+  loadEnvFiles();
+  if (existsSync(".env.production"))
+    try {
+      const { loadEnv } = require("@stacksjs/env");
+      loadEnv({ path: ".env.production", env: "production", keysFile: ".env.keys", overload: !0, quiet: !0 });
+    } catch {}
+  const credentialsPath = `${process.env.HOME || process.env.USERPROFILE || ""}/.aws/credentials`;
+  if ((!process.env.AWS_ACCESS_KEY_ID || !process.env.AWS_SECRET_ACCESS_KEY) && existsSync(credentialsPath)) {
+    const values = {};
+    let inProfile = !1;
+    for (const line of readFileSync(credentialsPath, "utf8").split(`
+`)) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith("[")) {
+        inProfile = trimmed === `[${profile}]`;
+        continue;
+      }
+      if (!inProfile)
+        continue;
+      const separator = trimmed.indexOf("=");
+      if (separator > 0)
+        values[trimmed.slice(0, separator).trim()] = trimmed.slice(separator + 1).trim();
+    }
+    if (values.aws_access_key_id && values.aws_secret_access_key) {
+      process.env.AWS_ACCESS_KEY_ID = values.aws_access_key_id;
+      process.env.AWS_SECRET_ACCESS_KEY = values.aws_secret_access_key;
+      if (values.aws_session_token)
+        process.env.AWS_SESSION_TOKEN = values.aws_session_token;
+      else
+        delete process.env.AWS_SESSION_TOKEN;
+    }
+  }
+  return { profile, region };
+}
+function mailStorageSecretId(options) {
+  if (options.secret)
+    return options.secret;
+  if (process.env.MAIL_STORAGE_SECRET_ID)
+    return process.env.MAIL_STORAGE_SECRET_ID;
+  const app = (process.env.APP_NAME || "stacks").toLowerCase().replace(/[^a-z0-9-]/g, "-"), environment = (process.env.APP_ENV || "production").toLowerCase().replace(/[^a-z0-9-]/g, "-");
+  return `${app}/${environment}/mail-storage-key`;
+}
+async function mailStorageHost(options) {
+  const host = options.host || await resolveOperationalMailHost();
+  if (!host)
+    throw Error("Could not resolve the mail host. Pass --host <hostname-or-ip>.");
+  if (!/^[a-zA-Z0-9._:-]+$/.test(host))
+    throw Error(`Unsafe mail host: ${host}`);
+  return host;
+}
+function runMailStorageSsh(host, command, input) {
+  const result = spawnSync("ssh", [
+    "-o",
+    "BatchMode=yes",
+    "-o",
+    "ConnectTimeout=15",
+    `root@${host}`,
+    command
+  ], {
+    input,
+    maxBuffer: 33554432
+  });
+  if (result.status !== 0) {
+    const stderr = Buffer.from(result.stderr || []).toString("utf8").trim();
+    throw Error(stderr || `SSH command failed with status ${result.status}`);
+  }
+  return Buffer.from(result.stdout || []);
+}
+function readMailRecoveryKey() {
+  const result = spawnSync("/usr/bin/security", [
+    "find-generic-password",
+    "-a",
+    "mail-storage-recovery",
+    "-s",
+    "com.stacks.production.mail.luks",
+    "-w"
+  ], {
+    maxBuffer: 1048576,
+    timeout: 30000
+  });
+  if (result.status !== 0)
+    throw Error("macOS Keychain recovery-key read failed");
+  const raw = Buffer.from(result.stdout || []), text = raw.toString("ascii").trim(), key = /^[0-9a-f]{128}$/i.test(text) ? Buffer.from(text, "hex") : raw.length === 65 && raw[64] === 10 ? Buffer.from(raw.subarray(0, 64)) : Buffer.from(raw);
+  raw.fill(0);
+  if (key.length !== 64)
+    throw Error("macOS Keychain returned an invalid recovery key");
+  return key;
+}
+async function waitForHetznerAction(token, actionId) {
+  const deadline = Date.now() + 120000;
+  while (Date.now() < deadline) {
+    const response = await fetch(`https://api.hetzner.cloud/v1/actions/${actionId}`, {
+      headers: { Authorization: `Bearer ${token}` }
+    }), data = await response.json();
+    if (!response.ok)
+      throw Error(data?.error?.message || `Hetzner action ${actionId} lookup failed`);
+    if (data.action?.status === "success")
+      return;
+    if (data.action?.status === "error")
+      throw Error(data.action?.error?.message || `Hetzner action ${actionId} failed`);
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+  }
+  throw Error(`Hetzner action ${actionId} timed out`);
+}
+async function ensureMailStorageVolume(options) {
+  loadEnvFiles();
+  const token = process.env.HCLOUD_TOKEN || process.env.HETZNER_API_TOKEN;
+  if (!token)
+    throw Error("HCLOUD_TOKEN or HETZNER_API_TOKEN is required.");
+  const headers = {
+    Authorization: `Bearer ${token}`,
+    "Content-Type": "application/json"
+  }, host = await mailStorageHost(options), server = (await (await fetch(`https://api.hetzner.cloud/v1/servers?name=${encodeURIComponent("stacks-production-app")}`, { headers })).json()).servers?.[0];
+  if (!server)
+    throw Error("Hetzner server stacks-production-app was not found.");
+  const app = (process.env.APP_NAME || "stacks").toLowerCase().replace(/[^a-z0-9-]/g, "-"), name = `${app}-production-mail`, requestedSize = Number.parseInt(options.size || "20", 10);
+  if (!Number.isFinite(requestedSize) || requestedSize < 10 || requestedSize > 1024)
+    throw Error("Mail volume size must be between 10 and 1024 GiB.");
+  let volume = (await (await fetch(`https://api.hetzner.cloud/v1/volumes?name=${encodeURIComponent(name)}`, { headers })).json()).volumes?.[0];
+  if (!volume) {
+    const createResponse = await fetch("https://api.hetzner.cloud/v1/volumes", {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        name,
+        size: requestedSize,
+        server: server.id,
+        automount: !1,
+        labels: {
+          application: app,
+          environment: "production",
+          purpose: "mail-storage"
+        }
+      })
+    }), createData = await createResponse.json();
+    if (!createResponse.ok)
+      throw Error(createData?.error?.message || "Hetzner volume creation failed.");
+    volume = createData.volume;
+    if (createData.action?.id)
+      await waitForHetznerAction(token, createData.action.id);
+  } else if (!volume.server) {
+    const attachResponse = await fetch(`https://api.hetzner.cloud/v1/volumes/${volume.id}/actions/attach`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ server: server.id, automount: !1 })
+    }), attachData = await attachResponse.json();
+    if (!attachResponse.ok)
+      throw Error(attachData?.error?.message || "Hetzner volume attach failed.");
+    await waitForHetznerAction(token, attachData.action.id);
+  } else if (volume.server !== server.id)
+    throw Error(`Hetzner volume ${name} is attached to a different server.`);
+  volume = (await (await fetch(`https://api.hetzner.cloud/v1/volumes/${volume.id}`, { headers })).json()).volume || volume;
+  if (!volume.linux_device)
+    throw Error(`Hetzner volume ${name} has no Linux device path yet.`);
+  return { device: volume.linux_device, host, id: volume.id, name, size: volume.size };
+}
+async function ensureMailKmsKey(options) {
+  const { region } = loadMailStorageAws(options), { AWSClient } = await import("../../../cloud/src/imap/client"), { S3Client } = await import("../../../cloud/src/imap/s3"), { SecretsManagerClient } = await import("../../../cloud/src/imap/secrets-manager"), client = new AWSClient, request = async (target, body) => client.request({
+    service: "kms",
+    region,
+    method: "POST",
+    path: "/",
+    headers: {
+      "Content-Type": "application/x-amz-json-1.1",
+      "X-Amz-Target": `TrentService.${target}`
+    },
+    body: JSON.stringify(body)
+  }), alias = "alias/stacks-production-mail";
+  let keyId = (await request("ListAliases", { Limit: 100 })).Aliases?.find((item) => item.AliasName === alias)?.TargetKeyId;
+  if (!keyId) {
+    keyId = (await request("CreateKey", {
+      Description: "Customer-managed key for production mail secrets and backups",
+      KeyUsage: "ENCRYPT_DECRYPT",
+      Origin: "AWS_KMS",
+      Tags: [
+        { TagKey: "Application", TagValue: "stacks" },
+        { TagKey: "Environment", TagValue: "production" },
+        { TagKey: "Purpose", TagValue: "mail-storage" }
+      ]
+    })).KeyMetadata?.KeyId;
+    if (!keyId)
+      throw Error("AWS KMS did not return a key ID.");
+    await request("CreateAlias", { AliasName: alias, TargetKeyId: keyId });
+    await request("EnableKeyRotation", { KeyId: keyId, RotationPeriodInDays: 90 });
+  }
+  const arn = (await request("DescribeKey", { KeyId: keyId })).KeyMetadata?.Arn;
+  if (!arn)
+    throw Error("AWS KMS did not return a key ARN.");
+  const secrets = new SecretsManagerClient(region);
+  for (const secretId of ["stacks/production/mail-storage-key", "stacks/production/mail-restic"])
+    try {
+      await secrets.updateSecret({ SecretId: secretId, KmsKeyId: arn });
+    } catch (error) {
+      if (error?.code !== "ResourceNotFoundException")
+        throw Error(`Could not re-encrypt secret ${secretId}: ${getErrorMessage(error)}`);
+    }
+  const s3 = new S3Client(region);
+  for (const bucket of ["stacks-production-s3-backups", "stacks-production-s3-email", "stacks-production-email"])
+    try {
+      await s3.putBucketEncryption(bucket, "aws:kms", arn);
+    } catch (error) {
+      throw Error(`Could not apply KMS encryption to ${bucket}: ${getErrorMessage(error)}`);
+    }
+  return { alias, arn };
+}
+async function configureMailRestic(options) {
+  const { region } = loadMailStorageAws(options), host = await mailStorageHost(options), bucket = options.bucket || "stacks-production-s3-backups";
+  if (!/^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/.test(bucket))
+    throw Error(`Unsafe S3 bucket name: ${bucket}`);
+  const kms = await ensureMailKmsKey(options), { AWSClient } = await import("../../../cloud/src/imap/client"), { SecretsManagerClient } = await import("../../../cloud/src/imap/secrets-manager"), iam = new AWSClient, iamRequest = async (action, params = {}) => iam.request({
+    service: "iam",
+    region: "us-east-1",
+    method: "POST",
+    path: "/",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      Action: action,
+      Version: "2010-05-08",
+      ...params
+    }).toString()
+  }), userName = "stacks-production-mail-backup";
+  try {
+    await iamRequest("GetUser", { UserName: userName });
+  } catch (error) {
+    if (error?.code !== "NoSuchEntity")
+      throw error;
+    await iamRequest("CreateUser", {
+      UserName: userName,
+      "Tags.member.1.Key": "Application",
+      "Tags.member.1.Value": "stacks",
+      "Tags.member.2.Key": "Environment",
+      "Tags.member.2.Value": "production",
+      "Tags.member.3.Key": "Purpose",
+      "Tags.member.3.Value": "mail-backup"
+    });
+  }
+  await iamRequest("PutUserPolicy", {
+    UserName: userName,
+    PolicyName: "mail-restic-backup",
+    PolicyDocument: JSON.stringify({
+      Version: "2012-10-17",
+      Statement: [
+        {
+          Effect: "Allow",
+          Action: ["s3:ListBucket", "s3:GetBucketLocation"],
+          Resource: `arn:aws:s3:::${bucket}`,
+          Condition: { StringLike: { "s3:prefix": ["restic-mail", "restic-mail/*"] } }
+        },
+        {
+          Effect: "Allow",
+          Action: [
+            "s3:GetObject",
+            "s3:PutObject",
+            "s3:DeleteObject",
+            "s3:AbortMultipartUpload",
+            "s3:ListMultipartUploadParts"
+          ],
+          Resource: `arn:aws:s3:::${bucket}/restic-mail/*`
+        },
+        {
+          Effect: "Allow",
+          Action: ["kms:Decrypt", "kms:Encrypt", "kms:GenerateDataKey", "kms:DescribeKey"],
+          Resource: kms.arn
+        }
+      ]
+    })
+  });
+  const listedMembers = (await iamRequest("ListAccessKeys", { UserName: userName })).ListAccessKeysResult?.AccessKeyMetadata?.member, oldKeys = listedMembers ? Array.isArray(listedMembers) ? listedMembers : [listedMembers] : [];
+  if (oldKeys.length > 0 && !options.force)
+    throw Error(`IAM user ${userName} already has a key. Pass --force to rotate it.`);
+  if (oldKeys.length >= 2)
+    for (const old of oldKeys)
+      await iamRequest("DeleteAccessKey", { UserName: userName, AccessKeyId: old.AccessKeyId });
+  const access = (await iamRequest("CreateAccessKey", { UserName: userName })).CreateAccessKeyResult?.AccessKey;
+  if (!access?.AccessKeyId || !access?.SecretAccessKey)
+    throw Error("AWS IAM did not return the Restic access key.");
+  const password = randomBytes(48).toString("base64url"), repository = `s3:s3.amazonaws.com/${bucket}/restic-mail`, secretId = "stacks/production/mail-restic", secretPayload = JSON.stringify({
+    version: 1,
+    repository,
+    password,
+    accessKeyId: access.AccessKeyId,
+    secretAccessKey: access.SecretAccessKey,
+    kmsKeyArn: kms.arn,
+    createdAt: new Date().toISOString()
+  }), secrets = new SecretsManagerClient(region);
+  try {
+    await secrets.createSecret({
+      Name: secretId,
+      Description: "Restic credentials for production mail backups",
+      KmsKeyId: kms.arn,
+      SecretString: secretPayload,
+      Tags: [
+        { Key: "Application", Value: "stacks" },
+        { Key: "Environment", Value: "production" },
+        { Key: "Purpose", Value: "mail-backup" }
+      ]
+    });
+  } catch (error) {
+    if (error?.code !== "ResourceExistsException")
+      throw error;
+    await secrets.updateSecret({ SecretId: secretId, KmsKeyId: kms.arn, SecretString: secretPayload });
+  }
+  const configDir = "/var/lib/mail-storage/data/restic", passwordPath = `${configDir}/password`, envPayload = [
+    `RESTIC_REPOSITORY=${repository}`,
+    `RESTIC_PASSWORD_FILE=${passwordPath}`,
+    `AWS_ACCESS_KEY_ID=${access.AccessKeyId}`,
+    `AWS_SECRET_ACCESS_KEY=${access.SecretAccessKey}`,
+    `AWS_DEFAULT_REGION=${region}`,
+    ""
+  ].join(`
+`);
+  runMailStorageSsh(host, `install -d -m 0700 ${configDir}; umask 077; dd of=${configDir}/restic.env status=none`, Buffer.from(envPayload));
+  runMailStorageSsh(host, `umask 077; dd of=${passwordPath} status=none`, Buffer.from(`${password}
+`));
+  runMailStorageSsh(host, `set -a; . ${configDir}/restic.env; set +a; restic snapshots >/dev/null 2>&1 || restic init`);
+  runMailStorageSsh(host, "systemctl enable --now mail-restic-backup.timer mail-storage-health.timer");
+  runMailStorageSsh(host, "systemctl start mail-restic-backup.service");
+  runMailStorageSsh(host, "/usr/local/sbin/mail-restic-restore-check");
+  for (const old of oldKeys)
+    if (old.AccessKeyId !== access.AccessKeyId)
+      await iamRequest("DeleteAccessKey", { UserName: userName, AccessKeyId: old.AccessKeyId });
+  return { repository, secretId };
+}
+function decodeMailStorageSecret(secretString) {
+  if (!secretString)
+    throw Error("The mail storage secret has no SecretString value.");
+  let parsed;
+  try {
+    parsed = JSON.parse(secretString);
+  } catch {
+    throw Error("The mail storage secret is not valid JSON.");
+  }
+  if (parsed.version !== 1 || parsed.encoding !== "base64" || typeof parsed.key !== "string")
+    throw Error("The mail storage secret uses an unsupported format.");
+  const key = Buffer.from(parsed.key, "base64");
+  if (key.length < 32)
+    throw Error("The mail storage key is unexpectedly short.");
+  return key;
+}
+async function getMailStorageSecret(options) {
+  const { profile, region } = loadMailStorageAws(options), secretId = mailStorageSecretId(options), { SecretsManagerClient } = await import("../../../cloud/src/imap/secrets-manager"), value = await new SecretsManagerClient(region, profile).getSecretValue({ SecretId: secretId });
+  return { key: decodeMailStorageSecret(value.SecretString), secretId };
+}
+async function escrowMailStorageKey(options) {
+  const { profile, region } = loadMailStorageAws(options), host = await mailStorageHost(options), secretId = mailStorageSecretId(options), { SecretsManagerClient } = await import("../../../cloud/src/imap/secrets-manager"), secrets = new SecretsManagerClient(region, profile), key = runMailStorageSsh(host, "systemd-creds decrypt --name=mail-storage-key /etc/credstore.encrypted/mail-storage-key.cred -");
+  if (key.length < 32)
+    throw Error("The machine-bound mail storage key is unexpectedly short.");
+  let existing;
+  try {
+    const value = await secrets.getSecretValue({ SecretId: secretId });
+    existing = decodeMailStorageSecret(value.SecretString);
+  } catch (error) {
+    if (error?.code !== "ResourceNotFoundException")
+      throw error;
+  }
+  if (existing && !timingSafeEqual(existing, key)) {
+    existing.fill(0);
+    if (!options.force) {
+      key.fill(0);
+      throw Error(`Secret ${secretId} already contains a different key. Pass --force to replace it.`);
+    }
+  }
+  existing?.fill(0);
+  const payload = {
+    version: 1,
+    encoding: "base64",
+    key: key.toString("base64"),
+    image: "/var/lib/mail-storage.luks",
+    mapper: "mail-storage",
+    createdAt: new Date().toISOString()
+  };
+  if (existing)
+    await secrets.putSecretValue({ SecretId: secretId, SecretString: JSON.stringify(payload) });
+  else
+    try {
+      await secrets.createSecret({
+        Name: secretId,
+        Description: `Externally escrowed LUKS2 key for ${host}`,
+        SecretString: JSON.stringify(payload),
+        Tags: [
+          { Key: "Application", Value: process.env.APP_NAME || "stacks" },
+          { Key: "Environment", Value: process.env.APP_ENV || "production" },
+          { Key: "Purpose", Value: "mail-storage" }
+        ]
+      });
+    } catch (error) {
+      if (error?.code !== "ResourceExistsException")
+        throw error;
+      await secrets.putSecretValue({ SecretId: secretId, SecretString: JSON.stringify(payload) });
+    }
+  const verify = await secrets.getSecretValue({ SecretId: secretId }), verifiedKey = decodeMailStorageSecret(verify.SecretString), matches = verifiedKey.length === key.length && timingSafeEqual(verifiedKey, key);
+  verifiedKey.fill(0);
+  key.fill(0);
+  if (!matches)
+    throw Error(`Secret ${secretId} did not verify after writing.`);
+  return { secretId, host };
+}
+function addMailStorageOptions(command) {
+  return command.option("--host <host>", "Mail server hostname or IP").option("--secret <id>", "AWS Secrets Manager secret ID").option("--region <region>", "AWS region", { default: "us-east-1" }).option("--profile <profile>", "AWS credential profile", { default: "default" });
+}
 export function mailCommands(buddy) {
   buddy.command("mail:provision", "Provision this app's mail from config/email.ts onto the shared mail server (domain + DKIM + mailboxes + MX/SPF/DKIM/DMARC DNS). Reusable + idempotent; the same reconcile buddy deploy runs.").option("--ip <ip>", "Mail server IP (defaults to the A record of config.email.domain)").action(async (options) => {
     const environment = options.env || process.env.APP_ENV || "production";
@@ -73,6 +477,366 @@ export function mailCommands(buddy) {
     log.success(`Mail provisioned for ${domain}. Add MAIL_PASSWORD_<LOCALPART> env vars to pin mailbox passwords.`);
     process.exit(ExitCode.Success);
   });
+  addMailStorageOptions(buddy.command("mail:storage:status", "Show encrypted mail storage and external-key status")).action(async (options) => {
+    loadEnvFiles();
+    try {
+      const host = await mailStorageHost(options), output = runMailStorageSsh(host, `${mailStorageRemote} status`).toString("utf8").trim();
+      console.log(output);
+      process.exit(ExitCode.Success);
+    } catch (error) {
+      console.error(`Failed to read mail storage status: ${getErrorMessage(error)}`);
+      process.exit(ExitCode.FatalError);
+    }
+  });
+  addMailStorageOptions(buddy.command("mail:storage:kms:ensure", "Create and apply the customer-managed production mail KMS key")).action(async (options) => {
+    try {
+      const kms = await ensureMailKmsKey(options);
+      console.log(`alias=${kms.alias}`);
+      console.log(`arn=${kms.arn}`);
+      process.exit(ExitCode.Success);
+    } catch (error) {
+      console.error(`Failed to configure mail KMS: ${getErrorMessage(error)}`);
+      process.exit(ExitCode.FatalError);
+    }
+  });
+  addMailStorageOptions(buddy.command("mail:storage:volume:migrate", "Create a dedicated Hetzner volume and migrate encrypted mail storage")).option("--size <gib>", "Hetzner volume size in GiB", { default: "20" }).action(async (options) => {
+    let key, prepareAttempted = !1;
+    try {
+      const volume = await ensureMailStorageVolume(options);
+      key = (await getMailStorageSecret(options)).key;
+      runMailStorageSsh(volume.host, `for i in $(seq 1 60); do test -b ${shellQuote(volume.device)} && exit 0; sleep 1; done; exit 1`);
+      prepareAttempted = !0;
+      runMailStorageSsh(volume.host, [
+        "umask 077",
+        "key_file=$(mktemp /run/mail-volume-migrate-key.XXXXXX)",
+        `trap 'shred -u "$key_file" 2>/dev/null || rm -f "$key_file"' EXIT`,
+        'dd of="$key_file" bs=64 count=1 iflag=fullblock status=none',
+        `MAIL_ENCRYPTED_IMAGE_SIZE=16G /usr/local/sbin/mail-volume-migrate prepare ${shellQuote(volume.device)}`,
+        `${mailStorageRemote} unlock < "$key_file"`,
+        "/usr/local/sbin/mail-volume-migrate finalize"
+      ].join(" && "), key);
+      const status = runMailStorageSsh(volume.host, `${mailStorageRemote} status`).toString("utf8").trim();
+      console.log(`volume=${volume.name}`);
+      console.log(`volume_id=${volume.id}`);
+      console.log(`volume_size_gib=${volume.size}`);
+      console.log(status);
+      process.exit(ExitCode.Success);
+    } catch (error) {
+      if (prepareAttempted && key) {
+        const host = await mailStorageHost(options);
+        try {
+          runMailStorageSsh(host, "/usr/local/sbin/mail-volume-migrate rollback");
+        } catch (rollbackError) {
+          console.error(`Dedicated-volume rollback step failed: ${getErrorMessage(rollbackError)}`);
+        }
+        try {
+          runMailStorageSsh(host, `${mailStorageRemote} unlock`, key);
+        } catch (unlockError) {
+          console.error(`Mail storage re-unlock failed: ${getErrorMessage(unlockError)}`);
+        }
+      }
+      console.error(`Failed to migrate mail storage volume: ${getErrorMessage(error)}`);
+      process.exit(ExitCode.FatalError);
+    } finally {
+      key?.fill(0);
+    }
+  });
+  addMailStorageOptions(buddy.command("mail:storage:key:recovery:add", "Add an independent LUKS recovery key to macOS Keychain")).action(async (options) => {
+    let currentKey, recoveryKey;
+    try {
+      const host = await mailStorageHost(options);
+      currentKey = (await getMailStorageSecret(options)).key;
+      recoveryKey = randomBytes(64);
+      runMailStorageSsh(host, `${mailStorageRemote} add-recovery-key`, Buffer.concat([currentKey, recoveryKey]));
+      const account = "mail-storage-recovery", service = "com.stacks.production.mail.luks", encoded = recoveryKey.toString("base64"), keychainWriter = `
+          import Foundation
+          import Security
+
+          let input = FileHandle.standardInput.readDataToEndOfFile()
+          guard let encoded = String(data: input, encoding: .utf8)?
+            .trimmingCharacters(in: .whitespacesAndNewlines),
+            let secret = Data(base64Encoded: encoded),
+            secret.count == 64
+          else { exit(2) }
+
+          let query: [CFString: Any] = [
+            kSecClass: kSecClassGenericPassword,
+            kSecAttrAccount: "${account}",
+            kSecAttrService: "${service}",
+          ]
+          var trustedApplications: [SecTrustedApplication] = []
+          for path in ["/usr/bin/security", "/Library/Developer/CommandLineTools/usr/bin/swift-frontend"] {
+            var application: SecTrustedApplication?
+            guard SecTrustedApplicationCreateFromPath(path, &application) == errSecSuccess,
+              let application
+            else { exit(4) }
+            trustedApplications.append(application)
+          }
+          var access: SecAccess?
+          guard SecAccessCreate(
+            "Stacks production mail LUKS recovery key" as CFString,
+            trustedApplications as CFArray,
+            &access
+          ) == errSecSuccess, let access
+          else { exit(5) }
+
+          let attributes: [CFString: Any] = [
+            kSecValueData: secret,
+            kSecAttrLabel: "Stacks production mail LUKS recovery key",
+            kSecAttrAccessible: kSecAttrAccessibleWhenUnlockedThisDeviceOnly,
+            kSecAttrSynchronizable: false,
+            kSecAttrAccess: access,
+          ]
+          var status = SecItemUpdate(query as CFDictionary, attributes as CFDictionary)
+          if status == errSecItemNotFound {
+            var item = query
+            for (key, value) in attributes { item[key] = value }
+            status = SecItemAdd(item as CFDictionary, nil)
+          }
+          guard status == errSecSuccess else { exit(Int32(status)) }
+
+          var verificationQuery = query
+          verificationQuery[kSecReturnData] = true
+          verificationQuery[kSecMatchLimit] = kSecMatchLimitOne
+          var result: CFTypeRef?
+          status = SecItemCopyMatching(verificationQuery as CFDictionary, &result)
+          guard status == errSecSuccess, let stored = result as? Data, stored == secret
+          else { exit(3) }
+        `;
+      if (spawnSync("/usr/bin/swift", ["-e", keychainWriter], {
+        input: `${encoded}
+`,
+        maxBuffer: 1048576
+      }).status !== 0)
+        throw Error("macOS Keychain write failed");
+      console.log(`keychain_service=${service}`);
+      console.log("recovery_keyslot=verified");
+      process.exit(ExitCode.Success);
+    } catch (error) {
+      console.error(`Failed to add recovery key: ${getErrorMessage(error)}`);
+      process.exit(ExitCode.FatalError);
+    } finally {
+      currentKey?.fill(0);
+      recoveryKey?.fill(0);
+    }
+  });
+  addMailStorageOptions(buddy.command("mail:storage:key:recovery:verify", "Verify the Keychain recovery key against the live LUKS header")).action(async (options) => {
+    let key;
+    try {
+      const host = await mailStorageHost(options);
+      key = readMailRecoveryKey();
+      runMailStorageSsh(host, "cryptsetup open --test-passphrase --type luks2 --key-file - /var/lib/mail-storage.luks", key);
+      console.log("Keychain recovery key unlocks the live mail volume.");
+      process.exit(ExitCode.Success);
+    } catch (error) {
+      console.error(`Recovery key verification failed: ${getErrorMessage(error)}`);
+      process.exit(ExitCode.FatalError);
+    } finally {
+      key?.fill(0);
+    }
+  });
+  addMailStorageOptions(buddy.command("mail:storage:key:slot:remove", "Remove an unusable non-primary LUKS keyslot")).option("--slot <number>", "LUKS keyslot number to remove").action(async (options) => {
+    let key;
+    try {
+      const slot = Number.parseInt(options.slot || "", 10);
+      if (!Number.isInteger(slot) || slot < 1 || slot > 31)
+        throw Error("Pass a non-primary keyslot from 1 through 31.");
+      const host = await mailStorageHost(options);
+      key = (await getMailStorageSecret(options)).key;
+      const output = runMailStorageSsh(host, `${mailStorageRemote} remove-keyslot ${slot}`, key).toString("utf8").trim();
+      console.log(output);
+      process.exit(ExitCode.Success);
+    } catch (error) {
+      console.error(`Failed to remove LUKS keyslot: ${getErrorMessage(error)}`);
+      process.exit(ExitCode.FatalError);
+    } finally {
+      key?.fill(0);
+    }
+  });
+  addMailStorageOptions(buddy.command("mail:storage:restic:configure", "Configure client-encrypted Restic backups to S3")).option("--force", "Rotate an existing dedicated IAM access key", { default: !1 }).action(async (options) => {
+    try {
+      const result = await configureMailRestic(options);
+      console.log(`repository=${result.repository}`);
+      console.log(`recovery_secret=${result.secretId}`);
+      console.log("restore_check=ok");
+      process.exit(ExitCode.Success);
+    } catch (error) {
+      console.error(`Failed to configure Restic mail backups: ${getErrorMessage(error)}`);
+      process.exit(ExitCode.FatalError);
+    }
+  });
+  addMailStorageOptions(buddy.command("mail:storage:restore:check", "Restore and validate the newest off-host mail snapshot")).action(async (options) => {
+    try {
+      const host = await mailStorageHost(options), output = runMailStorageSsh(host, "/usr/local/sbin/mail-restic-restore-check").toString("utf8").trim();
+      console.log(output);
+      process.exit(ExitCode.Success);
+    } catch (error) {
+      console.error(`Mail restore check failed: ${getErrorMessage(error)}`);
+      process.exit(ExitCode.FatalError);
+    }
+  });
+  addMailStorageOptions(buddy.command("mail:storage:maildir:migrate", "Migrate live mailboxes to canonical Maildir++ layout")).action(async (options) => {
+    try {
+      const host = await mailStorageHost(options), output = runMailStorageSsh(host, "/usr/local/sbin/maildir-migrate migrate").toString("utf8").trim();
+      console.log(output);
+      const status = runMailStorageSsh(host, "/usr/local/sbin/maildir-migrate status").toString("utf8").trim();
+      console.log(status);
+      process.exit(ExitCode.Success);
+    } catch (error) {
+      console.error(`Maildir++ migration failed: ${getErrorMessage(error)}`);
+      process.exit(ExitCode.FatalError);
+    }
+  });
+  addMailStorageOptions(buddy.command("mail:forward:compile", "Compile and validate the live RFC 5228 forwarding script")).action(async (options) => {
+    try {
+      const host = await mailStorageHost(options), output = runMailStorageSsh(host, '/usr/local/sbin/mail-forward-compile /opt/mail/forwards.json /opt/mail/forwards.sieve && sed -n "1,160p" /opt/mail/forwards.sieve').toString("utf8").trim();
+      console.log(output);
+      process.exit(ExitCode.Success);
+    } catch (error) {
+      console.error(`Forwarding script compilation failed: ${getErrorMessage(error)}`);
+      process.exit(ExitCode.FatalError);
+    }
+  });
+  addMailStorageOptions(buddy.command("mail:storage:escrow", "Copy the machine-bound LUKS key to AWS Secrets Manager")).option("--force", "Replace a different existing secret", { default: !1 }).action(async (options) => {
+    try {
+      const result = await escrowMailStorageKey(options);
+      console.log(`Mail storage key verified in AWS Secrets Manager: ${result.secretId}`);
+      console.log(`Host: ${result.host}`);
+      process.exit(ExitCode.Success);
+    } catch (error) {
+      console.error(`Failed to escrow mail storage key: ${getErrorMessage(error)}`);
+      process.exit(ExitCode.FatalError);
+    }
+  });
+  addMailStorageOptions(buddy.command("mail:storage:key:verify", "Verify the external key against the LUKS2 header")).action(async (options) => {
+    let key;
+    try {
+      const host = await mailStorageHost(options), secret = await getMailStorageSecret(options);
+      key = secret.key;
+      runMailStorageSsh(host, "cryptsetup open --test-passphrase --type luks2 --key-file - /var/lib/mail-storage.luks", key);
+      console.log(`External key ${secret.secretId} unlocks the mail volume.`);
+      process.exit(ExitCode.Success);
+    } catch (error) {
+      console.error(`Mail storage key verification failed: ${getErrorMessage(error)}`);
+      process.exit(ExitCode.FatalError);
+    } finally {
+      key?.fill(0);
+    }
+  });
+  addMailStorageOptions(buddy.command("mail:storage:unlock", "Unlock external mail storage and start mail")).action(async (options) => {
+    let key;
+    try {
+      const host = await mailStorageHost(options), secret = await getMailStorageSecret(options);
+      key = secret.key;
+      const output = runMailStorageSsh(host, `${mailStorageRemote} unlock`, key).toString("utf8").trim();
+      console.log(output);
+      console.log(`External key: ${secret.secretId}`);
+      process.exit(ExitCode.Success);
+    } catch (error) {
+      console.error(`Failed to unlock mail storage: ${getErrorMessage(error)}`);
+      process.exit(ExitCode.FatalError);
+    } finally {
+      key?.fill(0);
+    }
+  });
+  addMailStorageOptions(buddy.command("mail:storage:lock", "Stop mail and lock external mail storage")).action(async (options) => {
+    loadEnvFiles();
+    try {
+      const host = await mailStorageHost(options), output = runMailStorageSsh(host, `${mailStorageRemote} lock`).toString("utf8").trim();
+      console.log(output);
+      process.exit(ExitCode.Success);
+    } catch (error) {
+      console.error(`Failed to lock mail storage: ${getErrorMessage(error)}`);
+      process.exit(ExitCode.FatalError);
+    }
+  });
+  addMailStorageOptions(buddy.command("mail:storage:backup", "Create and verify an encrypted local mail backup")).action(async (options) => {
+    loadEnvFiles();
+    try {
+      const host = await mailStorageHost(options), output = runMailStorageSsh(host, [
+        "set -eu",
+        "systemctl reset-failed mail-backup.service 2>/dev/null || true",
+        "systemctl start mail-backup.service",
+        'latest=$(find -L /opt/mail/backups -maxdepth 1 -type f -name "mail-backup-*.tgz" -printf "%T@ %p\\n" | sort -nr | head -1 | cut -d" " -f2-)',
+        'test -n "$latest"',
+        'tar -tzf "$latest" >/dev/null',
+        'printf "backup=%s\\n" "$latest"',
+        'stat -c "mode=%a owner=%U:%G size=%s" "$latest"'
+      ].join("; ")).toString("utf8").trim();
+      console.log(output);
+      process.exit(ExitCode.Success);
+    } catch (error) {
+      console.error(`Failed to create mail backup: ${getErrorMessage(error)}`);
+      process.exit(ExitCode.FatalError);
+    }
+  });
+  addMailStorageOptions(buddy.command("mail:storage:header:backup", "Stream a LUKS header backup to S3 with KMS encryption")).option("--bucket <bucket>", "Recovery bucket (defaults to <app>-<env>-s3-backups)").action(async (options) => {
+    try {
+      const { region } = loadMailStorageAws(options), host = await mailStorageHost(options), app = (process.env.APP_NAME || "stacks").toLowerCase().replace(/[^a-z0-9-]/g, "-"), environment = (process.env.APP_ENV || "production").toLowerCase().replace(/[^a-z0-9-]/g, "-"), bucket = options.bucket || `${app}-${environment}-s3-backups`;
+      if (!/^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/.test(bucket))
+        throw Error(`Unsafe S3 bucket name: ${bucket}`);
+      const objectKey = `luks-headers/mail-storage-${new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z")}.header`, { AWSClient } = await import("../../../cloud/src/imap/client"), { S3Client } = await import("../../../cloud/src/imap/s3"), kms = await ensureMailKmsKey(options), s3 = new S3Client(region);
+      await s3.putBucketEncryption(bucket, "aws:kms", kms.arn);
+      const uploadUrl = s3.generatePresignedPutUrl(bucket, objectKey, "application/octet-stream", 600), remoteCommand = [
+        "set -eu",
+        "tmp_dir=$(mktemp -d /run/mail-storage-header.XXXXXX)",
+        'tmp="$tmp_dir/header"',
+        `trap 'shred -u "$tmp" 2>/dev/null || rm -f "$tmp"; rmdir "$tmp_dir"' EXIT`,
+        'cryptsetup luksHeaderBackup /var/lib/mail-storage.luks --header-backup-file "$tmp"',
+        `curl --fail-with-body --silent --show-error -H 'Content-Type: application/octet-stream' --upload-file "$tmp" ${shellQuote(uploadUrl)} 1>&2`
+      ].join("; ");
+      runMailStorageSsh(host, remoteCommand);
+      const object = await s3.headObject(bucket, objectKey);
+      if (!object?.ContentLength || object.ContentLength < 1048576)
+        throw Error("The uploaded LUKS header size did not verify.");
+      const head = await new AWSClient().request({
+        service: "s3",
+        region,
+        method: "HEAD",
+        path: `/${bucket}/${objectKey}`,
+        returnHeaders: !0
+      }), encryption = head?.headers?.["x-amz-server-side-encryption"];
+      if (encryption !== "aws:kms")
+        throw Error(`The LUKS header object reported unexpected encryption: ${encryption || "none"}`);
+      const keyId = head?.headers?.["x-amz-server-side-encryption-aws-kms-key-id"];
+      if (keyId !== kms.arn)
+        throw Error(`The LUKS header object used an unexpected KMS key: ${keyId || "none"}`);
+      console.log(`header=s3://${bucket}/${objectKey}`);
+      console.log("encryption=aws:kms");
+      console.log(`kms_key=${kms.arn}`);
+      process.exit(ExitCode.Success);
+    } catch (error) {
+      console.error(`Failed to back up the LUKS header: ${getErrorMessage(error)}`);
+      process.exit(ExitCode.FatalError);
+    }
+  });
+  addMailStorageOptions(buddy.command("mail:storage:externalize", "Move the LUKS key off-host and require external unlocks")).option("--force", "Replace a different existing secret", { default: !1 }).action(async (options) => {
+    let configured = !1, key;
+    try {
+      const escrow = await escrowMailStorageKey(options);
+      key = (await getMailStorageSecret(options)).key;
+      runMailStorageSsh(escrow.host, `${mailStorageRemote} configure-external`);
+      configured = !0;
+      runMailStorageSsh(escrow.host, `${mailStorageRemote} unlock`, key);
+      runMailStorageSsh(escrow.host, `${mailStorageRemote} finalize-external`);
+      const status = runMailStorageSsh(escrow.host, `${mailStorageRemote} status`).toString("utf8").trim();
+      console.log(status);
+      console.log(`External key: ${escrow.secretId}`);
+      process.exit(ExitCode.Success);
+    } catch (error) {
+      if (configured)
+        try {
+          const host = await mailStorageHost(options);
+          runMailStorageSsh(host, `${mailStorageRemote} rollback-machine`);
+        } catch (rollbackError) {
+          console.error(`Automatic rollback also failed: ${getErrorMessage(rollbackError)}`);
+        }
+      console.error(`Failed to externalize mail storage: ${getErrorMessage(error)}`);
+      process.exit(ExitCode.FatalError);
+    } finally {
+      key?.fill(0);
+    }
+  });
   buddy.command("mail:user:add <email>", "Add a mail user").option("--password <password>", "User password (generated if not provided)").action(async (email, options) => {
     log.info(`Adding mail user: ${email}`);
     try {

package/dist/commands/setup.d.ts

@@ -18,4 +18,5 @@ export declare function ensureEnvIsSet(options: CliOptions): Promise<void>;
 declare interface DatabasePackage {
   name: string
   version: string
+  service?: string
 }

package/dist/commands/setup.js

@@ -211,10 +211,13 @@ export function ensureIdeSettings(cwd) {
   log.success("Installed project VS Code settings");
 }
 const DB_CONNECTION_PACKAGES = {
-  postgres: { name: "postgresql.org", version: "^17.10" },
-  mysql: { name: "mysql.com", version: "*" },
+  postgres: { name: "postgresql.org", version: "^17.10", service: "postgres" },
+  mysql: { name: "mysql.com", version: "*", service: "mysql" },
   sqlite: { name: "sqlite.org", version: "^3.47.2" }
 };
+function databaseAliases(connection, pkg) {
+  return [connection, pkg.name];
+}
 export function pantryDatabasePackage(connection) {
   return DB_CONNECTION_PACKAGES[connection];
 }
@@ -234,21 +237,36 @@ export async function optimizePantryDeps() {
     log.debug("No config/deps.ts found, skipping dependency optimization");
     return;
   }
-  let configDeps = {};
+  let configDeps = {}, configServices = [];
   try {
     const mod = await import(depsConfigPath), config = mod.config || mod.default;
     if (config?.dependencies)
       configDeps = { ...config.dependencies };
+    if (Array.isArray(config?.services?.autoStart))
+      configServices = config.services.autoStart.filter((name) => typeof name === "string");
   } catch (err) {
     log.debug("Could not load config/deps.ts, skipping dependency optimization");
     return;
   }
-  const dbPackage = detectDbPackage(cwd);
+  const dbPackage = detectDbPackage(cwd), autoStart = [...configServices];
   if (dbPackage) {
-    if (!Object.keys(configDeps).some((key) => key === dbPackage.name || key.startsWith(`${dbPackage.name}/`))) {
+    const selected = new Set(Object.entries(DB_CONNECTION_PACKAGES).filter(([, pkg]) => pkg.name === dbPackage.name).flatMap(([connection, pkg]) => databaseAliases(connection, pkg))), unused = new Set(Object.entries(DB_CONNECTION_PACKAGES).flatMap(([connection, pkg]) => databaseAliases(connection, pkg)).filter((alias) => !selected.has(alias)));
+    for (const pkg of Object.keys(configDeps)) {
+      const domain = pkg.split("/")[0];
+      if (unused.has(domain)) {
+        log.info(`DB_CONNECTION selects ${dbPackage.name}, dropping unused ${pkg}`);
+        delete configDeps[pkg];
+      }
+    }
+    if (!Object.keys(configDeps).some((key) => {
+      const domain = key.split("/")[0];
+      return selected.has(domain);
+    })) {
       log.info(`Detected DB_CONNECTION requires ${dbPackage.name}, adding to dependencies`);
       configDeps[dbPackage.name] = dbPackage.version;
     }
+    if (dbPackage.service && !autoStart.includes(dbPackage.service))
+      autoStart.push(dbPackage.service);
   }
   const lines = [
     "# Auto-generated from config/deps.ts and .env sniffing.",
@@ -261,6 +279,11 @@ export async function optimizePantryDeps() {
   ];
   for (const [pkg, version] of Object.entries(configDeps))
     lines.push(`  ${pkg}: ${version}`);
+  if (autoStart.length > 0) {
+    lines.push("", "services:", "  enabled: true", "  autoStart:");
+    for (const service of autoStart)
+      lines.push(`    - ${service}`);
+  }
   const depsYamlPath = join(cwd, "deps.yaml");
   writeFileSync(depsYamlPath, `${lines.join(`
 `)}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/buddy",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.229",
+  "version": "0.70.230",
   "description": "Meet Buddy. The Stacks runtime.",
   "author": "Chris Breuer",
   "contributors": [