@maildock/mailctl 0.1.0-rc.2 → 0.1.0-rc.3

package/dist/index.js

@@ -62,6 +62,13 @@ var Mailbox = z2.object({
   quotaBytes: QuotaBytes,
   active: z2.boolean(),
   suspended: z2.boolean(),
+  /**
+   * Submission refused because the mailbox looks compromised (mailserver ADR 0016). Distinct from
+   * `suspended`: the owner can still sign in and read their mail. Only an admin clears it.
+   */
+  sendingBlocked: z2.boolean(),
+  sendingBlockedReason: z2.string().nullable(),
+  sendingBlockedAt: z2.iso.datetime().nullable(),
   ...timestamps
 });
 var MailboxUsage = z2.object({
@@ -85,7 +92,9 @@ var MailboxUpdate = z2.object({
   displayName: z2.string().max(200).nullable().optional(),
   quotaBytes: QuotaBytes.optional(),
   suspended: z2.boolean().optional(),
-  active: z2.boolean().optional()
+  active: z2.boolean().optional(),
+  /** Only ever set to `false` — an admin restoring a mailbox the worker blocked. */
+  sendingBlocked: z2.literal(false).optional()
 });
 var MailboxPasswordReset = z2.object({ password: Password });
 var Alias = z2.object({
@@ -231,6 +240,38 @@ var ServerConfig = z4.object({
     startedAt: z4.iso.datetime().optional(),
     targetPerHour: z4.number().int().min(10).default(2e3)
   }).default({ enabled: false, targetPerHour: 2e3 }),
+  /**
+   * Compromised-mailbox containment. The worker watches outbound delivery per sender and, when a
+   * mailbox's mail is being rejected for reputation or hard-bounce reasons at a rate no legitimate
+   * sender produces, blocks its **submission** and raises a critical alert.
+   *
+   * It never touches `suspended`: the owner keeps IMAP/webmail and can still read their mail. Only
+   * sending stops, and only an admin can restore it (mailserver ADR 0016).
+   */
+  abuse: z4.object({
+    enabled: z4.boolean().default(true),
+    /** Rolling window the outbound statistics are measured over. */
+    windowMinutes: z4.number().int().min(5).max(1440).default(60),
+    /** A mailbox must have sent at least this many outbound messages in the window to be judged at all. */
+    minMessages: z4.number().int().min(5).default(20),
+    /** Share of a sender's outbound deliveries rejected for reputation reasons that trips containment. */
+    reputationRatio: z4.number().min(0.01).max(1).default(0.3),
+    /** Share of a sender's outbound deliveries that hard-bounced that trips containment. */
+    hardBounceRatio: z4.number().min(0.01).max(1).default(0.6),
+    /**
+     * Block sending automatically on a verdict. **Off by default**: containment raises the critical
+     * alert and leaves the mailbox sending until an operator has seen the thresholds fire against
+     * their own traffic and chosen to arm it (ADR 0016).
+     */
+    autoBlock: z4.boolean().default(false)
+  }).default({
+    enabled: true,
+    windowMinutes: 60,
+    minMessages: 20,
+    reputationRatio: 0.3,
+    hardBounceRatio: 0.6,
+    autoBlock: false
+  }),
   /** Trusted networks that may relay without auth (docker network is always included by the adapter). */
   trustedNetworks: z4.array(z4.string().regex(/^[0-9a-f.:]+\/\d{1,3}$/i)).default([])
 });
@@ -240,7 +281,8 @@ var ServerConfigInput = ServerConfig.partial({
   relay: true,
   trustedNetworks: true,
   mtaSts: true,
-  warmup: true
+  warmup: true,
+  abuse: true
 });
 var ServerConfigVersion = z4.object({
   version: z4.number().int(),
@@ -433,9 +475,12 @@ import { z as z8 } from "zod";
 var AlertSeverity = z8.enum(["warning", "critical"]);
 var Alert = z8.object({
   id: z8.string(),
-  /** Stable identity of the condition (`dns:<domainId>:<recordKey>`, `dnsbl:<zone>`, `rdns`, `tls_expiry`). */
+  /**
+   * Stable identity of the condition (`dns:<domainId>:<recordKey>`, `dnsbl:<zone>`, `rdns`,
+   * `tls_expiry`, `outbound_abuse:<mailboxId>`).
+   */
   key: z8.string(),
-  kind: z8.enum(["dns_drift", "dnsbl", "rdns", "tls_expiry"]),
+  kind: z8.enum(["dns_drift", "dnsbl", "rdns", "tls_expiry", "outbound_abuse"]),
   severity: AlertSeverity,
   title: z8.string(),
   detail: z8.record(z8.string(), z8.unknown()),
@@ -575,159 +620,1120 @@ var DeliveryLogPage = z10.object({
   })
 });
 
-// ../../packages/core/src/webmail.ts
+// ../../packages/core/src/license.ts
 import { z as z11 } from "zod";
-var FolderRole = z11.enum(["inbox", "sent", "drafts", "trash", "junk", "archive", "other"]);
-var Folder = z11.object({
+var LicenseStateName = z11.enum(["unlicensed", "active", "grace", "degraded"]);
+var LicenseDetails = z11.object({
+  licenseId: z11.string(),
+  tier: z11.string(),
+  /** 0 means unlimited. */
+  maxMailboxes: z11.number().int(),
+  maxDomains: z11.number().int(),
+  issuedAt: z11.string(),
+  expiresAt: z11.string(),
+  features: z11.array(z11.string()),
+  issuedTo: z11.string().nullable(),
+  /**
+   * The machine fingerprint the key is pinned to, or null for a portable key. Shown rather than
+   * reduced to a boolean because a transfer is a conversation about two fingerprints — the one in
+   * the key and the one this server reports — and the admin has to be able to quote both.
+   */
+  boundTo: z11.string().nullable()
+});
+var LicenseStatus = z11.object({
+  state: LicenseStateName,
+  /** Plain-English explanation for anything other than `active`; shown verbatim in a banner. */
+  reason: z11.string().nullable(),
+  /** Days until the next step down (grace → degraded); null when nothing is counting down. */
+  daysRemaining: z11.number().int().nullable(),
+  license: LicenseDetails.nullable(),
+  /** Current usage, so the UI can show "18 of 25 mailboxes" without a second call. */
+  usage: z11.object({ mailboxes: z11.number().int(), domains: z11.number().int() }),
+  lastHeartbeatAt: z11.string().nullable(),
+  /** Why the last heartbeat failed, if it did. */
+  lastError: z11.string().nullable(),
+  /** This server's fingerprint, so support can match it against what was issued. */
+  machine: z11.string()
+});
+var LicenseActivate = z11.object({
+  /** The `mdl1.…` key, as pasted. Whitespace is trimmed before verification. */
+  key: z11.string().min(16).max(8e3)
+});
+
+// ../../packages/core/src/webmail.ts
+import { z as z12 } from "zod";
+var FolderRole = z12.enum(["inbox", "sent", "drafts", "trash", "junk", "archive", "other"]);
+var Folder = z12.object({
   /** IMAP path (also the id used in every other endpoint), e.g. `INBOX`, `Sent`, `Projects/2026`. */
-  path: z11.string(),
-  name: z11.string(),
+  path: z12.string(),
+  name: z12.string(),
   role: FolderRole,
-  delimiter: z11.string().nullable(),
-  subscribed: z11.boolean(),
-  messages: z11.number().int(),
-  unseen: z11.number().int()
-});
-var Address = z11.object({ name: z11.string().nullable(), address: z11.string() });
-var MessageSummary = z11.object({
-  uid: z11.number().int(),
-  folder: z11.string(),
-  messageId: z11.string().nullable(),
-  /** `References`/`In-Reply-To` heads used for conversation grouping on the client. */
-  inReplyTo: z11.string().nullable(),
-  subject: z11.string(),
-  from: z11.array(Address),
-  to: z11.array(Address),
-  date: z11.string().nullable(),
-  size: z11.number().int(),
-  flags: z11.array(z11.string()),
-  seen: z11.boolean(),
-  flagged: z11.boolean(),
-  answered: z11.boolean(),
-  hasAttachments: z11.boolean()
-});
-var MessageListQuery = z11.object({
-  folder: z11.string().default("INBOX"),
+  delimiter: z12.string().nullable(),
+  subscribed: z12.boolean(),
+  messages: z12.number().int(),
+  unseen: z12.number().int()
+});
+var Address = z12.object({ name: z12.string().nullable(), address: z12.string() });
+var MessageSummary = z12.object({
+  uid: z12.number().int(),
+  folder: z12.string(),
+  messageId: z12.string().nullable(),
+  /** `In-Reply-To` head used for conversation grouping on the client. */
+  inReplyTo: z12.string().nullable(),
+  /** `References` chain (oldest first, angle brackets stripped) — the other half of the grouping. */
+  references: z12.array(z12.string()).default([]),
+  subject: z12.string(),
+  from: z12.array(Address),
+  to: z12.array(Address),
+  date: z12.string().nullable(),
+  size: z12.number().int(),
+  flags: z12.array(z12.string()),
+  seen: z12.boolean(),
+  flagged: z12.boolean(),
+  answered: z12.boolean(),
+  hasAttachments: z12.boolean()
+});
+var MessageListQuery = z12.object({
+  folder: z12.string().default("INBOX"),
   /** Newest first; `before` = uid to continue from (exclusive) for infinite scroll. */
-  before: z11.coerce.number().int().positive().optional(),
-  limit: z11.coerce.number().int().min(1).max(200).default(50),
+  before: z12.coerce.number().int().positive().optional(),
+  limit: z12.coerce.number().int().min(1).max(200).default(50),
   /** Free-text search (from/to/subject/body via IMAP SEARCH, Dovecot FTS when enabled). */
-  q: z11.string().trim().max(200).optional(),
-  unseen: z11.enum(["true", "false"]).optional().transform((v) => v === "true"),
-  flagged: z11.enum(["true", "false"]).optional().transform((v) => v === "true"),
-  attachments: z11.enum(["true", "false"]).optional().transform((v) => v === "true"),
-  since: z11.iso.date().optional(),
-  until: z11.iso.date().optional()
-});
-var MessageList = z11.object({
-  folder: z11.string(),
-  items: z11.array(MessageSummary),
+  q: z12.string().trim().max(200).optional(),
+  unseen: z12.enum(["true", "false"]).optional().transform((v) => v === "true"),
+  flagged: z12.enum(["true", "false"]).optional().transform((v) => v === "true"),
+  attachments: z12.enum(["true", "false"]).optional().transform((v) => v === "true"),
+  since: z12.iso.date().optional(),
+  until: z12.iso.date().optional()
+});
+var MessageList = z12.object({
+  folder: z12.string(),
+  items: z12.array(MessageSummary),
   /** Total messages matching (folder size when unfiltered). */
-  total: z11.number().int(),
+  total: z12.number().int(),
   /** Pass as `before` to fetch the next (older) page; null when exhausted. */
-  next: z11.number().int().nullable()
+  next: z12.number().int().nullable()
 });
-var Attachment = z11.object({
+var Attachment = z12.object({
   /** IMAP body part id (`2`, `1.2`) — download via `/mail/messages/{uid}/parts/{part}`. */
-  part: z11.string(),
-  filename: z11.string(),
-  contentType: z11.string(),
-  size: z11.number().int(),
+  part: z12.string(),
+  filename: z12.string(),
+  contentType: z12.string(),
+  size: z12.number().int(),
   /** `cid:` reference for inline images, without the angle brackets. */
-  contentId: z11.string().nullable(),
-  inline: z11.boolean()
+  contentId: z12.string().nullable(),
+  inline: z12.boolean()
 });
 var Message = MessageSummary.extend({
-  cc: z11.array(Address),
-  bcc: z11.array(Address),
-  replyTo: z11.array(Address),
-  references: z11.array(z11.string()),
+  cc: z12.array(Address),
+  bcc: z12.array(Address),
+  replyTo: z12.array(Address),
   /** Plain-text body (derived from HTML when the message has none). */
-  text: z11.string(),
+  text: z12.string(),
   /** Raw HTML body; the client sanitises before rendering (DOMPurify + sandboxed iframe). */
-  html: z11.string().nullable(),
-  attachments: z11.array(Attachment),
-  headers: z11.record(z11.string(), z11.string())
-});
-var FlagsUpdate = z11.object({
-  folder: z11.string(),
-  uids: z11.array(z11.number().int().positive()).min(1).max(1e3),
-  add: z11.array(z11.string()).default([]),
-  remove: z11.array(z11.string()).default([])
-});
-var MoveRequest = z11.object({
-  folder: z11.string(),
-  uids: z11.array(z11.number().int().positive()).min(1).max(1e3),
-  to: z11.string()
-});
-var DeleteRequest = z11.object({
-  folder: z11.string(),
-  uids: z11.array(z11.number().int().positive()).min(1).max(1e3),
+  html: z12.string().nullable(),
+  attachments: z12.array(Attachment),
+  headers: z12.record(z12.string(), z12.string())
+});
+var FlagsUpdate = z12.object({
+  folder: z12.string(),
+  uids: z12.array(z12.number().int().positive()).min(1).max(1e3),
+  add: z12.array(z12.string()).default([]),
+  remove: z12.array(z12.string()).default([])
+});
+var MoveRequest = z12.object({
+  folder: z12.string(),
+  uids: z12.array(z12.number().int().positive()).min(1).max(1e3),
+  to: z12.string()
+});
+var DeleteRequest = z12.object({
+  folder: z12.string(),
+  uids: z12.array(z12.number().int().positive()).min(1).max(1e3),
   /** Skip the Trash and expunge immediately (what "delete" does inside Trash/Junk). */
-  permanent: z11.boolean().default(false)
-});
-var FolderCreate = z11.object({ path: z11.string().min(1).max(255) });
-var FolderRename = z11.object({ path: z11.string().min(1), to: z11.string().min(1).max(255) });
-var SendRequest = z11.object({
-  to: z11.array(z11.string().min(3)).min(1),
-  cc: z11.array(z11.string()).default([]),
-  bcc: z11.array(z11.string()).default([]),
-  subject: z11.string().max(998).default(""),
-  text: z11.string().default(""),
-  html: z11.string().optional(),
+  permanent: z12.boolean().default(false)
+});
+var FolderCreate = z12.object({ path: z12.string().min(1).max(255) });
+var FolderRename = z12.object({ path: z12.string().min(1), to: z12.string().min(1).max(255) });
+var SendRequest = z12.object({
+  to: z12.array(z12.string().min(3)).min(1),
+  cc: z12.array(z12.string()).default([]),
+  bcc: z12.array(z12.string()).default([]),
+  subject: z12.string().max(998).default(""),
+  text: z12.string().default(""),
+  html: z12.string().optional(),
   /** Message-ID being replied to / forwarded (sets In-Reply-To/References and the \Answered flag). */
-  inReplyTo: z11.string().optional(),
-  replyFolder: z11.string().optional(),
-  replyUid: z11.number().int().positive().optional(),
+  inReplyTo: z12.string().optional(),
+  replyFolder: z12.string().optional(),
+  replyUid: z12.number().int().positive().optional(),
   /** Draft to delete after a successful send. */
-  draftUid: z11.number().int().positive().optional(),
+  draftUid: z12.number().int().positive().optional(),
   /** Attachments already uploaded with POST /mail/uploads (ids), plus optional forwarded parts. */
-  uploads: z11.array(z11.string()).default([]),
-  forwardParts: z11.array(z11.object({ folder: z11.string(), uid: z11.number().int().positive(), part: z11.string() })).default([])
+  uploads: z12.array(z12.string()).default([]),
+  forwardParts: z12.array(z12.object({ folder: z12.string(), uid: z12.number().int().positive(), part: z12.string() })).default([])
 });
 var DraftSave = SendRequest.omit({ draftUid: true, replyFolder: true, replyUid: true }).extend({
   /** Existing draft uid to replace. */
-  uid: z11.number().int().positive().optional()
-});
-var DraftSaved = z11.object({ uid: z11.number().int(), folder: z11.string() });
-var Upload = z11.object({
-  id: z11.string(),
-  filename: z11.string(),
-  size: z11.number().int(),
-  contentType: z11.string()
-});
-var MailEvent = z11.object({
-  type: z11.enum(["exists", "expunge", "flags", "connected", "error"]),
-  folder: z11.string().nullable(),
-  uid: z11.number().int().nullable(),
-  count: z11.number().int().nullable()
-});
-var MailboxSettings = z11.object({
-  signature: z11.string().max(4e3).default(""),
-  signatureHtml: z11.boolean().default(false),
+  uid: z12.number().int().positive().optional()
+});
+var DraftSaved = z12.object({ uid: z12.number().int(), folder: z12.string() });
+var Upload = z12.object({
+  id: z12.string(),
+  filename: z12.string(),
+  size: z12.number().int(),
+  contentType: z12.string()
+});
+var Contact = z12.object({
+  address: z12.string(),
+  /** Best display name seen for the address (the most recent non-empty one), else null. */
+  name: z12.string().nullable(),
+  /** How many sent messages went to this address — the primary ranking. */
+  count: z12.number().int(),
+  /** ISO date of the most recent message to this address; ties are broken on it. */
+  lastUsed: z12.string().nullable()
+});
+var ContactQuery = z12.object({
+  /** Prefix/substring match over the address and display name; empty returns the most-used. */
+  q: z12.string().trim().max(100).optional(),
+  limit: z12.coerce.number().int().min(1).max(50).default(10)
+});
+var MailEvent = z12.object({
+  type: z12.enum(["exists", "expunge", "flags", "connected", "error"]),
+  folder: z12.string().nullable(),
+  uid: z12.number().int().nullable(),
+  count: z12.number().int().nullable()
+});
+var MailboxSettings = z12.object({
+  signature: z12.string().max(4e3).default(""),
+  signatureHtml: z12.boolean().default(false),
   /** Reply-quoting and display preferences. */
-  replyQuote: z11.boolean().default(true),
-  messagesPerPage: z11.number().int().min(10).max(200).default(50),
-  theme: z11.enum(["system", "light", "dark"]).default("system"),
+  replyQuote: z12.boolean().default(true),
+  messagesPerPage: z12.number().int().min(10).max(200).default(50),
+  /** Group the message list into conversations (References/In-Reply-To, subject as a fallback). */
+  threaded: z12.boolean().default(true),
+  theme: z12.enum(["system", "light", "dark"]).default("system"),
   /** Delay before a queued send actually goes out (undo window), seconds. */
-  undoSendSeconds: z11.number().int().min(0).max(30).default(5)
+  undoSendSeconds: z12.number().int().min(0).max(30).default(5)
 });
 var MailboxSettingsUpdate = MailboxSettings.partial();
-var MailAccount = z11.object({
-  mailboxId: z11.string(),
-  address: z11.string(),
-  displayName: z11.string().nullable(),
-  quotaBytes: z11.number().int(),
-  usedBytes: z11.number().int(),
+var MailAccount = z12.object({
+  mailboxId: z12.string(),
+  address: z12.string(),
+  displayName: z12.string().nullable(),
+  quotaBytes: z12.number().int(),
+  usedBytes: z12.number().int(),
   settings: MailboxSettings
 });
-var PasswordChange = z11.object({ current: z11.string().min(1), password: z11.string().min(10).max(200) });
+var PasswordChange = z12.object({ current: z12.string().min(1), password: z12.string().min(10).max(200) });
+
+// ../../packages/core/src/ai.ts
+import { z as z13 } from "zod";
+var AiTransport = z13.enum(["anthropic", "openai", "ollama"]);
+var AiProviderId = z13.enum([
+  "anthropic",
+  "openai",
+  "gemini",
+  "grok",
+  "llama",
+  "groq",
+  "vllm",
+  "ollama",
+  "openai-compatible"
+]);
+var AiCapabilities = z13.object({
+  streaming: z13.boolean(),
+  tools: z13.boolean(),
+  promptCaching: z13.boolean(),
+  embeddings: z13.boolean()
+});
+var AiProviderCatalogueEntry = z13.object({
+  id: AiProviderId,
+  /** Shown in the provider picker. */
+  label: z13.string(),
+  /** Who the customer gets a key from. */
+  vendor: z13.string(),
+  transport: AiTransport,
+  /** Pre-filled base URL; `null` means the admin must supply one (self-hosted). */
+  defaultEndpoint: z13.string().nullable(),
+  auth: z13.enum(["bearer", "x-api-key", "none"]),
+  requiresKey: z13.boolean(),
+  /** Whether this endpoint can sit on a private network, i.e. is usable with `localOnly`. */
+  canBeLocal: z13.boolean(),
+  capabilities: AiCapabilities,
+  /**
+   * `verified` means every Phase 7 feature has been run against it and the phase gate covers it.
+   * `untested` means it speaks a protocol we implement and is expected to work, but we have not
+   * proven it — shown as such in the UI so nobody reads compatibility as a guarantee. Flipped to
+   * `verified` by an actual gate run, never optimistically.
+   */
+  verification: z13.enum(["verified", "untested"]),
+  /** Where the customer gets a key and finds the model names. */
+  docsUrl: z13.string(),
+  /**
+   * Model ids move faster than our release cycle, so the authoritative list is whatever the endpoint
+   * itself returns when the admin tests the connection. These are a starting suggestion only, and
+   * are deliberately empty where we would otherwise be guessing.
+   */
+  suggestedModels: z13.array(z13.string()),
+  notes: z13.string()
+});
+var HOSTED = { streaming: true, tools: true, promptCaching: false, embeddings: true };
+var HOSTED_NO_EMBEDDINGS = { ...HOSTED, embeddings: false };
+var AI_PROVIDER_CATALOGUE = [
+  {
+    id: "anthropic",
+    label: "Anthropic (Claude)",
+    vendor: "Anthropic",
+    transport: "anthropic",
+    defaultEndpoint: "https://api.anthropic.com",
+    auth: "x-api-key",
+    requiresKey: true,
+    canBeLocal: false,
+    capabilities: { streaming: true, tools: true, promptCaching: true, embeddings: false },
+    // Verified 2026-08-31 against `claude-haiku-4-5`: the provider contract (5/5), the prompt
+    // evaluation (11/11) and **every Phase 7 feature** — thread summary, explain, smart replies,
+    // all four compose actions, and the copilot including a stored proposal and its approval.
+    verification: "verified",
+    docsUrl: "https://platform.claude.com/docs",
+    suggestedModels: ["claude-opus-5", "claude-sonnet-5", "claude-haiku-4-5"],
+    notes: "The only provider here with prompt caching, which makes re-sending a long thread on every follow-up cheap. No embeddings endpoint."
+  },
+  {
+    id: "openai",
+    label: "OpenAI",
+    vendor: "OpenAI",
+    transport: "openai",
+    defaultEndpoint: "https://api.openai.com/v1",
+    auth: "bearer",
+    requiresKey: true,
+    canBeLocal: false,
+    capabilities: HOSTED,
+    // Verified 2026-08-31 against `gpt-4o-mini`: the provider contract (5/5), the prompt evaluation
+    // (12/12) and every Phase 7 feature, including the copilot's tool use and a stored proposal.
+    // The contract run found the cancel defect the other two transports were hiding.
+    verification: "verified",
+    docsUrl: "https://platform.openai.com/docs/api-reference/chat",
+    suggestedModels: ["gpt-4o-mini"],
+    notes: "The reference implementation of the chat-completions protocol every entry below shares."
+  },
+  {
+    id: "gemini",
+    label: "Google Gemini",
+    vendor: "Google AI Studio",
+    transport: "openai",
+    defaultEndpoint: "https://generativelanguage.googleapis.com/v1beta/openai/",
+    auth: "bearer",
+    requiresKey: true,
+    canBeLocal: false,
+    capabilities: HOSTED,
+    verification: "untested",
+    docsUrl: "https://ai.google.dev/gemini-api/docs/openai",
+    suggestedModels: [],
+    notes: "Google's OpenAI-compatible route. The trailing /openai/ is required and the model must be a Gemini id. Gemini's native API has extras (context caching, safety settings) this route does not expose."
+  },
+  {
+    id: "grok",
+    label: "xAI (Grok)",
+    vendor: "xAI",
+    transport: "openai",
+    defaultEndpoint: "https://api.x.ai/v1",
+    auth: "bearer",
+    requiresKey: true,
+    canBeLocal: false,
+    capabilities: HOSTED_NO_EMBEDDINGS,
+    verification: "untested",
+    docsUrl: "https://docs.x.ai/docs/api-reference",
+    suggestedModels: [],
+    notes: "Chat-completions compatible. Embeddings are not exposed on this route."
+  },
+  {
+    id: "llama",
+    label: "Meta Llama API",
+    vendor: "Meta",
+    transport: "openai",
+    defaultEndpoint: "https://api.llama.com/compat/v1/",
+    auth: "bearer",
+    requiresKey: true,
+    canBeLocal: false,
+    capabilities: HOSTED_NO_EMBEDDINGS,
+    verification: "untested",
+    docsUrl: "https://llama.developer.meta.com/docs/features/compatibility/",
+    suggestedModels: [],
+    notes: "Meta's hosted Llama models over their compatibility route; access is waitlisted and regionally limited. To run Llama without that, use Ollama or a self-hosted vLLM below."
+  },
+  {
+    id: "groq",
+    label: "Groq",
+    vendor: "Groq",
+    transport: "openai",
+    defaultEndpoint: "https://api.groq.com/openai/v1",
+    auth: "bearer",
+    requiresKey: true,
+    canBeLocal: false,
+    capabilities: HOSTED_NO_EMBEDDINGS,
+    verification: "untested",
+    docsUrl: "https://console.groq.com/docs/openai",
+    suggestedModels: [],
+    notes: "Hosted open-weight models; the quickest of the hosted options for short inbox features."
+  },
+  {
+    id: "vllm",
+    label: "vLLM (self-hosted)",
+    vendor: "self-hosted",
+    transport: "openai",
+    defaultEndpoint: null,
+    auth: "bearer",
+    requiresKey: false,
+    canBeLocal: true,
+    capabilities: HOSTED,
+    verification: "untested",
+    docsUrl: "https://docs.vllm.ai/en/latest/serving/openai_compatible_server.html",
+    suggestedModels: [],
+    notes: "Your own GPU box serving the chat-completions protocol. Usable with local-only mode when it sits on a private network."
+  },
+  {
+    id: "ollama",
+    label: "Ollama (local)",
+    vendor: "self-hosted",
+    transport: "ollama",
+    defaultEndpoint: "http://localhost:11434",
+    auth: "none",
+    requiresKey: false,
+    canBeLocal: true,
+    capabilities: { streaming: true, tools: true, promptCaching: false, embeddings: true },
+    verification: "untested",
+    docsUrl: "https://docs.ollama.com/api",
+    suggestedModels: [],
+    notes: "Runs the model on the mail server itself, so no message content leaves the machine. Tool use depends on the model you pull; a small model makes a poor admin copilot."
+  },
+  {
+    id: "openai-compatible",
+    label: "Other OpenAI-compatible endpoint",
+    vendor: "other",
+    transport: "openai",
+    defaultEndpoint: null,
+    auth: "bearer",
+    requiresKey: false,
+    canBeLocal: true,
+    capabilities: HOSTED,
+    verification: "untested",
+    docsUrl: "https://platform.openai.com/docs/api-reference/chat",
+    suggestedModels: [],
+    notes: "Anything else speaking POST /chat/completions \u2014 llama.cpp, LM Studio, OpenRouter, Together, a corporate gateway. Untested by us by definition."
+  }
+];
+var CATALOGUE_BY_ID = new Map(AI_PROVIDER_CATALOGUE.map((e) => [e.id, e]));
+var LOCAL_AI_PROVIDER_IDS = AI_PROVIDER_CATALOGUE.filter((e) => e.canBeLocal).map(
+  (e) => e.id
+);
+var AiProviderConfigInput = z13.object({
+  provider: AiProviderId,
+  model: z13.string().trim().min(1).max(200),
+  /** Overrides the catalogue default; required where that entry has none. */
+  endpoint: z13.string().trim().url().max(2e3).optional(),
+  /** Omit to keep the stored key unchanged; empty string clears it. */
+  apiKey: z13.string().max(8e3).optional(),
+  /** Refuse any endpoint that is not on a private network. */
+  localOnly: z13.boolean().default(false)
+}).superRefine((cfg, ctx) => {
+  const entry = CATALOGUE_BY_ID.get(cfg.provider);
+  if (!entry) return;
+  if (!entry.defaultEndpoint && !cfg.endpoint)
+    ctx.addIssue({
+      code: "custom",
+      path: ["endpoint"],
+      message: `${entry.label} is self-hosted, so it needs an endpoint URL`
+    });
+  if (cfg.localOnly && !entry.canBeLocal)
+    ctx.addIssue({
+      code: "custom",
+      path: ["provider"],
+      message: `${entry.label} is a hosted service and cannot be used with local-only mode; choose ${LOCAL_AI_PROVIDER_IDS.join(", ")}`
+    });
+});
+var AiProviderConfigView = z13.discriminatedUnion("configured", [
+  z13.object({ configured: z13.literal(false) }),
+  z13.object({
+    configured: z13.literal(true),
+    provider: AiProviderId,
+    model: z13.string(),
+    endpoint: z13.string(),
+    localOnly: z13.boolean(),
+    hasKey: z13.boolean(),
+    /** Last four characters of the stored key, so an admin can tell which one is in place. */
+    keyHint: z13.string().nullable(),
+    /**
+     * Set when the stored key cannot be decrypted — `SECRET_ENCRYPTION_KEY` was lost or replaced.
+     * The UI shows "re-enter your key" rather than a failure, because that is the actual remedy.
+     */
+    keyUnreadable: z13.boolean(),
+    updatedAt: z13.string()
+  })
+]);
+var AiConnectionTest = z13.object({
+  ok: z13.boolean(),
+  /** Models the endpoint advertises; empty when it does not expose a listing. */
+  models: z13.array(z13.string()),
+  /** Whether the configured model is among them; null when the endpoint does not say. */
+  modelAvailable: z13.boolean().nullable(),
+  /** `AiErrorKind` when `ok` is false — `auth`, `network`, `local_only_refused`… */
+  errorKind: z13.string().nullable(),
+  /** Plain-English failure, safe to show an admin verbatim. */
+  message: z13.string().nullable()
+});
+var AiCallRecord = z13.object({
+  provider: AiProviderId,
+  model: z13.string(),
+  /** Which feature made the call — `thread-summary`, `smart-reply`, `admin-copilot`… */
+  feature: z13.string(),
+  /** Version of the prompt template used, so a regression can be traced to a template change. */
+  promptVersion: z13.string(),
+  outcome: z13.enum(["ok", "error", "cancelled"]),
+  /** `AiErrorKind` when the outcome is `error`. */
+  errorKind: z13.string().nullable(),
+  inputTokens: z13.number().int(),
+  outputTokens: z13.number().int(),
+  cacheReadTokens: z13.number().int(),
+  cacheWriteTokens: z13.number().int(),
+  latencyMs: z13.number().int(),
+  /** Digest of the prompt, so repeated calls can be correlated without storing the prompt. */
+  promptDigest: z13.string()
+});
+var AiDomainPolicy = z13.object({
+  domainId: z13.string(),
+  domain: z13.string(),
+  /** Admin veto for this domain. Default true: configuring a provider is already deliberate. */
+  enabled: z13.boolean(),
+  /**
+   * Whether extracted attachment text may be sent along with a message. **Default false**: an
+   * attachment is far more likely than a message body to hold something the sender never meant to
+   * share with a third party.
+   */
+  allowAttachments: z13.boolean(),
+  /** Null when no admin has ever set a policy for this domain. */
+  updatedAt: z13.string().nullable()
+});
+var AiDomainPolicyUpdate = z13.object({
+  enabled: z13.boolean().optional(),
+  allowAttachments: z13.boolean().optional()
+});
+var AiOptIn = z13.object({
+  optedIn: z13.boolean(),
+  /** When consent was given, kept so it can be shown back and audited. */
+  optedInAt: z13.string().nullable()
+});
+var AiOptInUpdate = z13.object({ optedIn: z13.boolean() });
+var AiUnavailableReason = z13.enum([
+  /** No provider configured on this server. */
+  "not_configured",
+  /** An admin has switched AI off for this domain. */
+  "domain_disabled",
+  /** The user has not opted in. */
+  "not_opted_in"
+]);
+var AiAvailability = z13.object({
+  available: z13.boolean(),
+  reason: AiUnavailableReason.nullable(),
+  provider: AiProviderId.nullable(),
+  model: z13.string().nullable(),
+  /** Whether this mailbox's domain permits attachment text to be sent. */
+  attachmentsAllowed: z13.boolean(),
+  optedIn: z13.boolean(),
+  /** Whether the user could opt in — false when a gate above them is closed. */
+  canOptIn: z13.boolean()
+});
+var AiCallLogEntry = AiCallRecord.extend({
+  id: z13.string(),
+  /** Mailbox the call was made for; null for admin-console calls, which read telemetry, not mail. */
+  mailbox: z13.string().nullable(),
+  createdAt: z13.string()
+});
+var AiCallLogQuery = z13.object({
+  limit: z13.coerce.number().int().min(1).max(200).default(50),
+  offset: z13.coerce.number().int().min(0).default(0)
+});
+var AiCallLogPage = z13.object({
+  items: z13.array(AiCallLogEntry),
+  total: z13.number().int()
+});
+var AiSummariseRequest = z13.object({
+  folder: z13.string().min(1).max(500),
+  uids: z13.array(z13.number().int().positive()).min(1).max(50)
+});
+var AiExplainRequest = z13.object({
+  folder: z13.string().min(1).max(500),
+  uid: z13.number().int().positive()
+});
+var AiEmailExplanation = z13.object({
+  verdict: z13.enum(["legitimate", "suspicious", "dangerous", "unclear"]),
+  summary: z13.string(),
+  /** Concrete things in the message that support the verdict. */
+  signals: z13.array(z13.string()),
+  advice: z13.string(),
+  /** Whether the mail server's own spam analysis was available to the model. */
+  usedSpamSignals: z13.boolean()
+});
+var AiRepliesRequest = z13.object({
+  folder: z13.string().min(1).max(500),
+  uids: z13.array(z13.number().int().positive()).min(1).max(50)
+});
+var AiReplies = z13.object({ replies: z13.array(z13.string()) });
+var AiComposeRequest = z13.discriminatedUnion("action", [
+  z13.object({
+    action: z13.literal("draft"),
+    instruction: z13.string().trim().min(1).max(2e3),
+    /** The thread being replied to, so a draft can match what it answers. */
+    folder: z13.string().min(1).max(500).optional(),
+    uid: z13.number().int().positive().optional()
+  }),
+  z13.object({
+    action: z13.literal("rewrite"),
+    draft: z13.string().min(1).max(2e4),
+    tone: z13.enum(["formal", "friendly", "direct", "apologetic"]).optional(),
+    length: z13.enum(["shorter", "longer", "same"]).optional()
+  }),
+  z13.object({
+    action: z13.literal("translate"),
+    draft: z13.string().min(1).max(2e4),
+    language: z13.string().trim().min(1).max(60)
+  }),
+  z13.object({ action: z13.literal("grammar"), draft: z13.string().min(1).max(2e4) })
+]);
+var AiStreamEvent = z13.discriminatedUnion("type", [
+  z13.object({ type: z13.literal("text"), text: z13.string() }),
+  z13.object({ type: z13.literal("done") }),
+  z13.object({ type: z13.literal("error"), kind: z13.string(), message: z13.string() })
+]);
+var AiCopilotTool = z13.enum([
+  "listDomains",
+  "getDeliveryLog",
+  "explainBounce",
+  "checkDns",
+  "getReputation",
+  "getAlerts",
+  "getLicenseState",
+  "getMailbox",
+  "proposeRestoreSending",
+  "proposeRotateDkimKey",
+  "proposeResolveAlert"
+]);
+var AiProposalState = z13.enum(["pending", "applied", "rejected", "expired", "failed"]);
+var AiProposal = z13.object({
+  id: z13.string(),
+  conversationId: z13.string(),
+  tool: AiCopilotTool,
+  title: z13.string(),
+  summary: z13.string(),
+  targetKind: z13.enum(["mailbox", "domain", "alert"]),
+  targetId: z13.string(),
+  targetLabel: z13.string(),
+  change: z13.record(z13.string(), z13.unknown()),
+  precondition: z13.record(z13.string(), z13.unknown()),
+  state: AiProposalState,
+  expiresAt: z13.string(),
+  appliedAt: z13.string().nullable(),
+  /** Why an apply failed or was refused; null while pending and on success. */
+  detail: z13.string().nullable(),
+  createdAt: z13.string()
+});
+var AiProposalQuery = z13.object({
+  state: AiProposalState.optional(),
+  limit: z13.coerce.number().int().min(1).max(200).default(50)
+});
+var AiCopilotTurn = z13.object({
+  role: z13.enum(["user", "assistant"]),
+  text: z13.string().max(2e4)
+});
+var AiCopilotRequest = z13.object({
+  conversationId: z13.string().uuid(),
+  /** Prior turns, oldest first. Only the text is carried across; tool results are not replayed. */
+  history: z13.array(AiCopilotTurn).max(20).default([]),
+  message: z13.string().trim().min(1).max(4e3)
+});
+var AiCopilotEvent = z13.discriminatedUnion("type", [
+  z13.object({ type: z13.literal("text"), text: z13.string() }),
+  /** A tool the server ran, as it ran it — the transcript the admin watches. */
+  z13.object({
+    type: z13.literal("tool"),
+    tool: AiCopilotTool,
+    args: z13.record(z13.string(), z13.unknown()),
+    ok: z13.boolean(),
+    detail: z13.string()
+  }),
+  /** A change awaiting approval. Rendered as a card, never applied by arriving. */
+  z13.object({ type: z13.literal("proposal"), proposal: AiProposal }),
+  z13.object({ type: z13.literal("done") }),
+  z13.object({ type: z13.literal("error"), kind: z13.string(), message: z13.string() })
+]);
+var AiCopilotReadiness = z13.object({
+  available: z13.boolean(),
+  reason: z13.string().nullable(),
+  provider: AiProviderId.nullable(),
+  model: z13.string().nullable(),
+  toolsSupported: z13.boolean()
+});
+var AiToolCallEntry = z13.object({
+  id: z13.string(),
+  conversationId: z13.string(),
+  tool: z13.string(),
+  args: z13.record(z13.string(), z13.unknown()),
+  ok: z13.boolean(),
+  resultCount: z13.number().int().nullable(),
+  detail: z13.string().nullable(),
+  proposalId: z13.string().nullable(),
+  latencyMs: z13.number().int(),
+  createdAt: z13.string()
+});
+
+// ../../packages/core/src/migration.ts
+import { z as z14 } from "zod";
+var MigrationSourceKind = z14.enum(["imap", "cpanel", "plesk", "google", "m365"]);
+var ImapSecurity = z14.enum(["tls", "starttls", "none"]);
+var ImapSourceConfig = z14.object({
+  kind: z14.literal("imap"),
+  host: z14.string().trim().toLowerCase().min(1).max(253),
+  port: z14.number().int().min(1).max(65535).default(993),
+  security: ImapSecurity.default("tls"),
+  /**
+   * Skip certificate verification. Off by default and surfaced as a deliberate choice in the wizard:
+   * plenty of cPanel boxes being migrated *away from* still present an expired or self-signed
+   * certificate, and refusing to connect helps nobody once the admin has seen the hostname.
+   */
+  allowInvalidCert: z14.boolean().default(false)
+});
+var CpanelSourceConfig = z14.object({
+  kind: z14.literal("cpanel"),
+  host: z14.string().trim().toLowerCase().min(1).max(253),
+  port: z14.number().int().min(1).max(65535).default(2083),
+  api: z14.enum(["cpanel", "whm"]).default("cpanel"),
+  /** The cPanel account to read. Required with a WHM token; a cPanel token is already scoped to one. */
+  account: z14.string().trim().min(1).max(64).optional(),
+  /** Defaults to `host` when unset. */
+  imapHost: z14.string().trim().toLowerCase().min(1).max(253).optional(),
+  imapPort: z14.number().int().min(1).max(65535).default(993),
+  imapSecurity: ImapSecurity.default("tls"),
+  allowInvalidCert: z14.boolean().default(false)
+});
+var PleskSourceConfig = z14.object({
+  kind: z14.literal("plesk"),
+  host: z14.string().trim().toLowerCase().min(1).max(253),
+  port: z14.number().int().min(1).max(65535).default(8443),
+  /** One mail domain to read. Unset means every domain this login can see. */
+  domain: z14.string().trim().toLowerCase().min(1).max(253).optional(),
+  /** Defaults to `host` when unset. */
+  imapHost: z14.string().trim().toLowerCase().min(1).max(253).optional(),
+  imapPort: z14.number().int().min(1).max(65535).default(993),
+  imapSecurity: ImapSecurity.default("tls"),
+  allowInvalidCert: z14.boolean().default(false)
+});
+var GoogleSourceConfig = z14.object({
+  kind: z14.literal("google"),
+  /** The Workspace domain whose users are being migrated. */
+  domain: z14.string().trim().toLowerCase().min(1).max(253),
+  /** A super-admin in that domain, impersonated for directory reads only. */
+  adminEmail: z14.string().trim().toLowerCase().min(3).max(320),
+  imapHost: z14.string().trim().toLowerCase().min(1).max(253).default("imap.gmail.com"),
+  imapPort: z14.number().int().min(1).max(65535).default(993),
+  /**
+   * Read each user's Gmail settings — vacation responder, filters, auto-forwarding. Three extra API
+   * calls per mailbox and a wider scope grant, so it is a choice rather than an assumption.
+   */
+  readGmailSettings: z14.boolean().default(true),
+  /** Import Google Groups as aliases. Their archives and moderation do not come across. */
+  includeGroups: z14.boolean().default(true)
+});
+var M365SourceConfig = z14.object({
+  kind: z14.literal("m365"),
+  /** The Entra tenant: its GUID, or any domain it owns. */
+  tenantId: z14.string().trim().min(1).max(253),
+  /** Only migrate mailboxes on this domain. Unset means every mailbox in the tenant. */
+  domain: z14.string().trim().toLowerCase().min(1).max(253).optional(),
+  imapHost: z14.string().trim().toLowerCase().min(1).max(253).default("outlook.office365.com"),
+  imapPort: z14.number().int().min(1).max(65535).default(993),
+  /**
+   * Read each mailbox's automatic replies and inbox rules. Two extra Graph calls per mailbox and the
+   * `MailboxSettings.Read` permission, so it is a choice rather than an assumption.
+   */
+  readMailboxSettings: z14.boolean().default(true),
+  /** Import mail-enabled groups and distribution lists as aliases. */
+  includeGroups: z14.boolean().default(true)
+});
+var MigrationSourceConfig = z14.discriminatedUnion("kind", [
+  ImapSourceConfig,
+  CpanelSourceConfig,
+  PleskSourceConfig,
+  GoogleSourceConfig,
+  M365SourceConfig
+]);
+var ImapSourceSecret = z14.object({
+  kind: z14.literal("imap"),
+  /**
+   * Dovecot/Courier master-user login, when the source has one. `adminSeparator` is the character
+   * between the mailbox address and the master user (`user@example.com*master`); Dovecot's is `*`.
+   */
+  adminUser: z14.string().min(1).max(320).optional(),
+  adminPassword: z14.string().min(1).max(1024).optional(),
+  adminSeparator: z14.string().length(1).default("*")
+});
+var CpanelSourceSecret = z14.object({
+  kind: z14.literal("cpanel"),
+  /** The user the token belongs to: the cPanel account, or the WHM/reseller user. */
+  username: z14.string().trim().min(1).max(64),
+  /** An API token, never a password: cPanel's own tokens are revocable and scoped. */
+  apiToken: z14.string().min(1).max(1024),
+  adminUser: z14.string().min(1).max(320).optional(),
+  adminPassword: z14.string().min(1).max(1024).optional(),
+  adminSeparator: z14.string().length(1).default("*")
+});
+var PleskSourceSecret = z14.object({
+  kind: z14.literal("plesk"),
+  /** Plesk API secret key. Preferred over the password: revocable, and can be bound to our address. */
+  apiKey: z14.string().min(1).max(1024).optional(),
+  /** Panel login, used only with `password`. */
+  username: z14.string().trim().min(1).max(64).optional(),
+  password: z14.string().min(1).max(1024).optional(),
+  adminUser: z14.string().min(1).max(320).optional(),
+  adminPassword: z14.string().min(1).max(1024).optional(),
+  adminSeparator: z14.string().length(1).default("*")
+});
+var GoogleSourceSecret = z14.object({
+  kind: z14.literal("google"),
+  /** The service account's own address, `…@….iam.gserviceaccount.com`. */
+  clientEmail: z14.string().trim().min(3).max(320),
+  /** The PEM private key from the service account's JSON key file. */
+  privateKey: z14.string().min(1).max(8192)
+});
+var M365SourceSecret = z14.object({
+  kind: z14.literal("m365"),
+  /** The application (client) ID from the Entra app registration. */
+  clientId: z14.string().trim().min(1).max(200),
+  /** A client secret from that registration. Not a certificate — Entra allows either; this is simpler. */
+  clientSecret: z14.string().min(1).max(2048)
+});
+var MigrationSourceSecret = z14.discriminatedUnion("kind", [
+  ImapSourceSecret,
+  CpanelSourceSecret,
+  PleskSourceSecret,
+  GoogleSourceSecret,
+  M365SourceSecret
+]);
+var MigrationJobState = z14.enum([
+  "draft",
+  "discovering",
+  "ready",
+  "running",
+  "paused",
+  "done",
+  "failed",
+  "cancelled"
+]);
+var MigrationMailboxState = z14.enum(["pending", "running", "done", "failed", "skipped"]);
+var MigrationErrorCode = z14.enum([
+  "auth",
+  "connection",
+  "tls",
+  "quota",
+  "rate_limited",
+  "folder",
+  "source_missing",
+  "target_missing",
+  "cancelled",
+  "unknown"
+]);
+var MigrationProgress = z14.object({
+  foldersTotal: z14.number().int().nonnegative(),
+  foldersDone: z14.number().int().nonnegative(),
+  messagesTotal: z14.number().int().nonnegative(),
+  messagesDone: z14.number().int().nonnegative(),
+  /** Messages the source had that the target already held — the delta-run "did nothing" number. */
+  messagesSkipped: z14.number().int().nonnegative(),
+  bytesDone: z14.number().int().nonnegative()
+});
+var CutoverStep = z14.enum(["lower_ttl", "initial_sync", "verify_counts", "switch_mx", "final_delta"]);
+var CUTOVER_STEPS = CutoverStep.options;
+var MigrationMailbox = z14.object({
+  id: z14.string(),
+  jobId: z14.string(),
+  /** Address on the source server. */
+  sourceAddress: z14.string(),
+  /** Local mailbox this copies into; null until the admin maps it (or discovery matched one). */
+  targetMailboxId: z14.string().nullable(),
+  targetAddress: z14.string().nullable(),
+  state: MigrationMailboxState,
+  progress: MigrationProgress,
+  errorCode: MigrationErrorCode.nullable(),
+  errorDetail: z14.string().nullable(),
+  /** Set when this mailbox last completed a run; the delta run copies only what appeared since. */
+  lastRunAt: z14.string().nullable(),
+  /** True when a source password is sealed for this mailbox specifically. Never the password itself. */
+  hasSecret: z14.boolean()
+});
+var MigrationJob = z14.object({
+  id: z14.string(),
+  name: z14.string(),
+  kind: MigrationSourceKind,
+  /** Non-secret source configuration. */
+  source: MigrationSourceConfig,
+  state: MigrationJobState,
+  /** Aggregate of the mailbox rows, computed on read. */
+  progress: MigrationProgress,
+  mailboxCount: z14.number().int().nonnegative(),
+  mailboxesDone: z14.number().int().nonnegative(),
+  mailboxesFailed: z14.number().int().nonnegative(),
+  errorCode: MigrationErrorCode.nullable(),
+  errorDetail: z14.string().nullable(),
+  /** True while an admin credential is sealed; false once the job finished and it was wiped. */
+  hasSecret: z14.boolean(),
+  /** Cutover steps the admin has ticked off, in no particular order. */
+  cutover: z14.array(CutoverStep),
+  startedAt: z14.string().nullable(),
+  finishedAt: z14.string().nullable(),
+  createdAt: z14.string(),
+  updatedAt: z14.string()
+});
+var MigrationJobCreate = z14.object({
+  name: z14.string().trim().min(1).max(120),
+  source: MigrationSourceConfig,
+  secret: MigrationSourceSecret
+});
+var DiscoveredMailbox = z14.object({
+  address: z14.string(),
+  /** Bytes on the source, where the source will say; null when it will not. */
+  sizeBytes: z14.number().int().nonnegative().nullable(),
+  /** Quota on the source, so a pre-created mailbox starts with the same allowance. Null = unlimited. */
+  quotaBytes: z14.number().int().nonnegative().nullable(),
+  /** Suspended on the source. Worth copying, and worth not silently re-enabling here. */
+  suspended: z14.boolean(),
+  /** A local mailbox with the same address, when one already exists. */
+  suggestedTargetMailboxId: z14.string().nullable(),
+  suggestedTargetAddress: z14.string().nullable()
+});
+var DiscoveredForwarder = z14.object({
+  source: z14.string(),
+  destination: z14.string()
+});
+var DiscoveredAutoresponder = z14.object({
+  address: z14.string(),
+  subject: z14.string(),
+  /** ISO timestamps; null means open-ended in that direction. */
+  startsAt: z14.string().nullable(),
+  endsAt: z14.string().nullable(),
+  /** False when the window has already closed — imported, but left switched off. */
+  active: z14.boolean()
+});
+var DiscoveredFilter = z14.object({
+  address: z14.string(),
+  name: z14.string(),
+  /** False when the source rule uses something with no equivalent here; `note` says what. */
+  supported: z14.boolean(),
+  note: z14.string().nullable()
+});
+var MigrationDiscovery = z14.object({
+  mailboxes: z14.array(DiscoveredMailbox),
+  forwarders: z14.array(DiscoveredForwarder),
+  autoresponders: z14.array(DiscoveredAutoresponder),
+  filters: z14.array(DiscoveredFilter),
+  /** Domains the source account holds, so the admin can see what is missing here. */
+  domains: z14.array(z14.string()),
+  /** Things worth telling the admin that are not failures: skipped constructs, partial answers. */
+  warnings: z14.array(z14.string()),
+  /**
+   * True when the source was reached with a single admin credential, so per-mailbox passwords are not
+   * needed. False for a plain IMAP source where each mailbox must be entered by hand — and, notably,
+   * false for cPanel without a Dovecot master user: the API token lists mailboxes but cannot open one.
+   */
+  usedAdminCredential: z14.boolean()
+});
+var MigrationMailboxAdd = z14.object({
+  sourceAddress: z14.string().trim().toLowerCase().min(1).max(320),
+  targetMailboxId: z14.string().uuid().nullable().default(null),
+  /** Required when the job has no admin credential. Sealed on arrival, never returned. */
+  sourcePassword: z14.string().min(1).max(1024).optional()
+});
+var MigrationMailboxesAdd = z14.object({
+  mailboxes: z14.array(MigrationMailboxAdd).min(1).max(1e3)
+});
+var MigrationRunStart = z14.object({
+  mode: z14.enum(["full", "delta"]).default("full"),
+  dryRun: z14.boolean().default(false),
+  /** Restrict the run to these mailbox rows; empty means every mailbox on the job. */
+  mailboxIds: z14.array(z14.string().uuid()).default([])
+});
+var MigrationLogLevel = z14.enum(["info", "warn", "error"]);
+var MigrationLogEntry = z14.object({
+  id: z14.string(),
+  jobId: z14.string(),
+  mailboxId: z14.string().nullable(),
+  at: z14.string(),
+  level: MigrationLogLevel,
+  message: z14.string()
+});
+var MigrationLogQuery = z14.object({
+  mailboxId: z14.string().uuid().optional(),
+  level: MigrationLogLevel.optional(),
+  limit: z14.coerce.number().int().min(1).max(1e3).default(200),
+  offset: z14.coerce.number().int().min(0).default(0)
+});
+var MigrationLogPage = z14.object({
+  items: z14.array(MigrationLogEntry),
+  total: z14.number().int()
+});
+var CutoverUpdate = z14.object({
+  step: CutoverStep,
+  done: z14.boolean()
+});
+var MigrationPrecreate = z14.object({
+  addresses: z14.array(z14.string().trim().toLowerCase().min(3).max(320)).min(1).max(1e3),
+  /**
+   * Copy each source mailbox's quota onto the one created here. Off means the domain's default is
+   * used — which is usually what you want when moving off a host with wildly generous quotas.
+   */
+  copyQuotas: z14.boolean().default(false),
+  /** Add every created mailbox to this job's mapping, so the copy can start straight afterwards. */
+  map: z14.boolean().default(true)
+});
+var MigrationPrecreateResult = z14.object({
+  created: z14.array(z14.object({ address: z14.string(), password: z14.string() })),
+  skipped: z14.array(z14.object({ address: z14.string(), reason: z14.string() })),
+  mapped: z14.number().int().nonnegative()
+});
+var MigrationImport = z14.object({
+  forwarders: z14.boolean().default(true),
+  autoresponders: z14.boolean().default(true),
+  filters: z14.boolean().default(true),
+  /** Replace what is already there. Off means an address that already has rules is left alone. */
+  overwrite: z14.boolean().default(false)
+});
+var MigrationImportResult = z14.object({
+  aliases: z14.array(z14.string()),
+  forwarders: z14.array(z14.string()),
+  autoresponders: z14.array(z14.string()),
+  filters: z14.array(z14.string()),
+  skipped: z14.array(z14.object({ what: z14.string(), reason: z14.string() }))
+});
+
+// ../../packages/license/src/index.ts
+import {
+  createHash,
+  createPrivateKey,
+  createPublicKey,
+  generateKeyPairSync,
+  sign,
+  verify
+} from "node:crypto";
+import { networkInterfaces, hostname } from "node:os";
+import { readFileSync } from "node:fs";
+import { z as z15 } from "zod";
+var LicenseTier = z15.enum(["starter", "standard", "business", "enterprise"]);
+var LicenseFeature = z15.string().min(1).max(40);
+var LicensePayload = z15.object({
+  /** Format version, so a future change can be detected rather than mis-parsed. */
+  v: z15.literal(1),
+  licenseId: z15.string().min(8).max(64),
+  tier: LicenseTier,
+  /** 0 means unlimited. Counted excluding `system` mailboxes (DMARC ingestion and friends). */
+  maxMailboxes: z15.number().int().min(0),
+  maxDomains: z15.number().int().min(0),
+  issuedAt: z15.iso.datetime(),
+  expiresAt: z15.iso.datetime(),
+  features: z15.array(LicenseFeature).default([]),
+  /** Machine fingerprint this key is bound to; absent means the key is portable. */
+  fingerprint: z15.string().min(16).max(64).nullable().default(null),
+  /** Free-text label shown in the admin UI (usually the customer's company). */
+  issuedTo: z15.string().max(200).nullable().default(null)
+});
+function fingerprintInputs() {
+  let machineId = null;
+  for (const p of ["/etc/machine-id", "/var/lib/dbus/machine-id"]) {
+    try {
+      const v = readFileSync(p, "utf8").trim();
+      if (v) {
+        machineId = v;
+        break;
+      }
+    } catch {
+    }
+  }
+  const macs = Object.values(networkInterfaces()).flatMap((i) => i ?? []).filter((i) => !i.internal && i.mac && i.mac !== "00:00:00:00:00:00").map((i) => i.mac).sort();
+  return { machineId, mac: macs[0] ?? null, host: hostname() };
+}
+function fingerprint(inputs = fingerprintInputs()) {
+  const material = [inputs.machineId ?? "", inputs.mac ?? "", inputs.host].join("|");
+  return createHash("sha256").update(material).digest("hex").slice(0, 32);
+}
+var LicenseState = z15.enum(["unlicensed", "active", "grace", "degraded"]);
+var GatedAction = z15.enum(["create_mailbox", "create_domain", "ai_features"]);
 
 // src/lib/api.ts
+var ApiError2 = class extends Error {
+  status;
+  code;
+  constructor(status, code, message) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.code = code;
+  }
+};
 var ApiClient = class {
   constructor(baseUrl) {
     this.baseUrl = baseUrl;
   }
+  /**
+   * One request, JSON in and out, errors turned into `ApiError` so a command can print the API's own
+   * sentence rather than an HTTP status. The bearer token is whatever `resolveToken` produced — an
+   * `msk_…` API token or an access token from a sign-in; the API accepts both in the same header.
+   */
+  async json(method, path8, opts = {}) {
+    let res;
+    try {
+      res = await fetch(`${this.baseUrl}/api/v1${path8}`, {
+        method,
+        headers: {
+          ...opts.body === void 0 ? {} : { "content-type": "application/json" },
+          ...opts.token ? { authorization: `Bearer ${opts.token}` } : {}
+        },
+        ...opts.body === void 0 ? {} : { body: JSON.stringify(opts.body) },
+        signal: AbortSignal.timeout(opts.timeoutMs ?? 15e3)
+      });
+    } catch (e) {
+      throw new ApiError2(
+        0,
+        "unreachable",
+        `could not reach the API at ${this.baseUrl}: ${e.message}`
+      );
+    }
+    const body = await res.json().catch(() => void 0);
+    if (!res.ok) {
+      const b = body ?? {};
+      throw new ApiError2(
+        res.status,
+        b.code ?? b.error ?? "error",
+        b.message ?? `request failed (${res.status})`
+      );
+    }
+    return body;
+  }
+  /**
+   * Sign in as an admin user. TOTP is asked for only when the server says it is needed, so an
+   * account without it is never prompted for a code it cannot produce.
+   */
+  async login(creds) {
+    const { accessToken } = await this.json("POST", "/auth/login", {
+      body: {
+        email: creds.email,
+        password: creds.password,
+        ...creds.totp ? { totp: creds.totp } : {}
+      }
+    });
+    return accessToken;
+  }
+  licenseStatus(token) {
+    return this.json("GET", "/license", { token });
+  }
+  /** Install a key. Owner-only, and verified server-side before it is stored. */
+  activateLicense(token, key) {
+    return this.json("POST", "/license/activate", { token, body: { key: key.trim() } });
+  }
   async health() {
     try {
       const res = await fetch(`${this.baseUrl}/api/v1/health`, { signal: AbortSignal.timeout(3e3) });
@@ -780,19 +1786,20 @@ import os from "node:os";
 import { promisify } from "node:util";
 var execFileP = promisify(execFile);
 async function run(cmd, args, opts = {}) {
-  if (opts.stdio === "inherit") {
+  if (opts.stdio === "inherit" || opts.input !== void 0) {
     const { spawn } = await import("node:child_process");
     return new Promise((resolve, reject) => {
       const child = spawn(cmd, args, {
         cwd: opts.cwd,
         env: { ...process.env, ...opts.env },
-        stdio: "inherit"
+        stdio: opts.input === void 0 ? "inherit" : ["pipe", "inherit", "inherit"]
       });
       child.on(
         "exit",
         (code) => code === 0 ? resolve({ stdout: "", stderr: "" }) : reject(new Error(`${cmd} ${args.join(" ")} exited with ${code}`))
       );
       child.on("error", reject);
+      if (opts.input !== void 0) child.stdin?.end(opts.input);
     });
   }
   return execFileP(cmd, args, {
@@ -831,11 +1838,11 @@ function portFree(port, host = "0.0.0.0") {
 function memoryGiB() {
   return os.totalmem() / 1024 ** 3;
 }
-async function diskFreeGiB(path7) {
+async function diskFreeGiB(path8) {
   try {
-    const { stdout } = await execFileP("df", ["-Pk", path7]);
-    const line = stdout.trim().split("\n").at(-1) ?? "";
-    const avail = Number(line.split(/\s+/)[3]);
+    const { stdout } = await execFileP("df", ["-Pk", path8]);
+    const line2 = stdout.trim().split("\n").at(-1) ?? "";
+    const avail = Number(line2.split(/\s+/)[3]);
     return Number.isFinite(avail) ? avail / 1024 ** 2 : null;
   } catch {
     return null;
@@ -852,9 +1859,9 @@ async function publicIp() {
   }
   return null;
 }
-async function resolveA(hostname) {
+async function resolveA(hostname2) {
   try {
-    return await dns.resolve4(hostname);
+    return await dns.resolve4(hostname2);
   } catch {
     return [];
   }
@@ -874,20 +1881,31 @@ function randomSecret(bytes = 32) {
 
 // src/lib/install-dir.ts
 import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 var DEFAULT_DIR = process.env["MAILSERVER_DIR"] ?? "/opt/mailserver";
+var IMAGE_REGISTRY = "603283648754.dkr.ecr.us-east-1.amazonaws.com/maildock";
+function assetsDir(from = path.dirname(fileURLToPath(import.meta.url))) {
+  const tried = ["../../assets", "../assets"].map((rel) => path.resolve(from, rel));
+  const found = tried.find((p) => existsSync(path.join(p, "compose.yaml")));
+  if (!found)
+    throw new Error(
+      `mailctl is missing its bundled assets (looked in ${tried.join(" and ")}). Reinstall it: npm i -g ${"@maildock/mailctl"}`
+    );
+  return found;
+}
 function bundledComposeFile() {
-  return path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "assets", "compose.yaml");
+  return path.join(assetsDir(), "compose.yaml");
 }
 function bundledCaddyfile() {
-  return path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "assets", "Caddyfile");
+  return path.join(assetsDir(), "Caddyfile");
 }
 async function readEnv(dir) {
   const text = await fs.readFile(path.join(dir, ".env"), "utf8").catch(() => "");
   const env = {};
-  for (const line of text.split("\n")) {
-    const m = /^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/.exec(line);
+  for (const line2 of text.split("\n")) {
+    const m = /^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/.exec(line2);
     if (m) env[m[1]] = m[2];
   }
   return env;
@@ -904,6 +1922,13 @@ function defaultEnv(opts) {
   return {
     IMAGE_REGISTRY: opts.registry,
     IMAGE_TAG: opts.tag,
+    /**
+     * The subscription this server runs under. Empty is legitimate — a self-built image needs no
+     * credentials — but a customer pulling from the private registry needs it, and `mailctl upgrade`
+     * back-fills the key so an older install gains the field without hand-editing.
+     */
+    LICENSE_ID: opts.licenseId ?? "",
+    LICENSE_SERVER_URL: "https://license.maildock.io",
     MAIL_HOSTNAME: opts.hostname,
     DB_ADMIN_USER: "mail",
     DB_ADMIN_PASSWORD: randomSecret(24),
@@ -911,8 +1936,15 @@ function defaultEnv(opts) {
     DB_DAEMON_USER: "mail_daemon",
     DB_DAEMON_PASSWORD: randomSecret(24),
     JWT_SECRET: randomSecret(48),
+    SECRET_ENCRYPTION_KEY: randomSecret(48),
     DOVECOT_MASTER_PASSWORD: randomSecret(32),
     SRS_SECRET: randomSecret(32),
+    /**
+     * Seals the source-server credentials a migration holds (ADR 0018). Rotating it makes every
+     * in-flight migration's stored credential unopenable — the admin re-enters them — but touches
+     * nothing else, because no other subsystem uses this key.
+     */
+    MIGRATION_SECRET_KEY: randomSecret(48),
     PUBLIC_IP: opts.publicIp ?? "",
     COOKIE_SECURE: "true",
     SMTP_PORT: "25",
@@ -977,6 +2009,45 @@ async function execInService(base, dir, service, cmd, input) {
   });
 }
 
+// src/lib/registry.ts
+var dockerLogin = async (c) => {
+  await run("docker", ["login", "--username", c.username, "--password-stdin", c.registry], {
+    input: c.password
+  });
+};
+async function registryLogin(env, fingerprint2, fetchImpl = fetch, login = dockerLogin) {
+  const licenseId = env.LICENSE_ID?.trim();
+  const server = env.LICENSE_SERVER_URL?.trim();
+  if (!licenseId)
+    return { status: "skipped", message: "No LICENSE_ID in .env \u2014 pulling without registry credentials." };
+  if (!server)
+    return {
+      status: "skipped",
+      message: "No LICENSE_SERVER_URL in .env \u2014 pulling without registry credentials."
+    };
+  let token;
+  try {
+    const res = await fetchImpl(`${server.replace(/\/$/, "")}/v1/registry/token`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ licenseId, fingerprint: fingerprint2 })
+    });
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      const why = body.error === "expired" ? "This subscription has lapsed. Renew it to pull new images; the running server is unaffected." : body.error === "revoked" ? "This licence has been revoked. Contact support." : body.error === "unknown_license" ? `The licence server does not recognise ${licenseId}.` : body.error === "fingerprint_mismatch" ? "This licence is registered to a different machine. Transfer it before upgrading here." : body.message ?? `The licence server returned ${res.status}.`;
+      return { status: "failed", message: why };
+    }
+    token = await res.json();
+  } catch (e) {
+    return {
+      status: "failed",
+      message: `Could not reach the licence server at ${server}: ${e.message}`
+    };
+  }
+  await login({ registry: token.registry, username: token.username, password: token.password });
+  return { status: "logged-in", message: `Authenticated to ${token.registry}.` };
+}
+
 // src/lib/preflight.ts
 var DEFAULT_PORTS = [25, 80, 443, 465, 587, 993, 995];
 async function preflight(o) {
@@ -1078,14 +2149,24 @@ var Install = class _Install extends Command {
       default: process.env["MAILSERVER_VERSION"] ?? "latest"
     }),
     registry: Flags.string({
+      // ECR, not GHCR (ADR 0011). The namespace is part of the value: compose composes images as
+      // `${IMAGE_REGISTRY}/<service>:${IMAGE_TAG}`, and the repositories are `maildock/<service>`.
       description: "image registry/namespace",
-      default: process.env["MAILSERVER_REGISTRY"] ?? "ghcr.io/mail-dock/mailserver"
+      default: process.env["MAILSERVER_REGISTRY"] ?? IMAGE_REGISTRY
     }),
     "skip-preflight": Flags.boolean({
       description: "continue despite failed preflight checks",
       default: false
     }),
-    "no-pull": Flags.boolean({ description: "do not pull images (use local builds)", default: false })
+    "no-pull": Flags.boolean({ description: "do not pull images (use local builds)", default: false }),
+    "license-id": Flags.string({
+      description: "subscription id, used to authenticate to the private image registry",
+      default: process.env["MAILDOCK_LICENSE_ID"] ?? ""
+    }),
+    "license-server": Flags.string({
+      description: "licence server base URL (override for self-hosted or testing)",
+      default: process.env["MAILDOCK_LICENSE_SERVER"] ?? ""
+    })
   };
   async run() {
     const { flags } = await this.parse(_Install);
@@ -1100,15 +2181,15 @@ ${parsed.error.issues.map((i) => `  ${i.path.join(".")}: ${i.message}`).join("\n
         );
       answers = parsed.data;
     }
-    const hostname = answers?.hostname ?? flags.hostname;
-    if (!hostname) this.error("--hostname is required (or provide --answers)");
+    const hostname2 = answers?.hostname ?? flags.hostname;
+    if (!hostname2) this.error("--hostname is required (or provide --answers)");
     const dir = flags.dir;
     await fs2.mkdir(dir, { recursive: true });
     const existing = await readEnv(dir);
     if (existing["JWT_SECRET"]) this.log(`Existing install found in ${dir}; keeping its secrets.`);
     this.log("Preflight\u2026");
     const checks = await preflight({
-      hostname,
+      hostname: hostname2,
       dataDir: dir,
       ports: DEFAULT_PORTS,
       skipPorts: !!existing["JWT_SECRET"]
@@ -1119,17 +2200,27 @@ ${parsed.error.issues.map((i) => `  ${i.path.join(".")}: ${i.message}`).join("\n
       this.error(`${blockers.length} blocking check(s) failed. Fix them or re-run with --skip-preflight.`);
     const ip = await publicIp();
     const env = {
-      ...defaultEnv({ hostname, tag: flags.tag, registry: flags.registry, publicIp: ip }),
+      ...defaultEnv({
+        hostname: hostname2,
+        tag: flags.tag,
+        registry: flags.registry,
+        publicIp: ip,
+        licenseId: flags["license-id"]
+      }),
       ...existing,
-      MAIL_HOSTNAME: hostname,
+      MAIL_HOSTNAME: hostname2,
       IMAGE_TAG: flags.tag,
-      IMAGE_REGISTRY: flags.registry
+      IMAGE_REGISTRY: flags.registry,
+      // flags win over an existing .env: re-running install with a new licence id should adopt it
+      ...flags["license-id"] ? { LICENSE_ID: flags["license-id"] } : {},
+      ...flags["license-server"] ? { LICENSE_SERVER_URL: flags["license-server"] } : {}
     };
     await writeEnv(dir, env);
     await materialise(dir);
     this.log(`Wrote ${path3.join(dir, ".env")} and compose bundle.`);
     const c = compose(dir);
     if (!flags["no-pull"]) {
+      await this.registryLogin(env);
       this.log("Pulling images\u2026");
       await c.pull();
     }
@@ -1147,21 +2238,31 @@ ${parsed.error.issues.map((i) => `  ${i.path.join(".")}: ${i.message}`).join("\n
           "setup is already complete on this server; --answers ignored. Use the admin UI to change settings."
         );
       this.log("Applying answers file\u2026");
-      const result = await api.applyAnswers(answers);
+      const result2 = await api.applyAnswers(answers);
       this.log("\nSetup complete. Publish these DNS records:\n");
-      this.log(formatDns(result.dns));
+      this.log(formatDns(result2.dns));
       this.log(`
-Admin: https://${hostname}/  \xB7  API docs: https://${hostname}/api/v1/docs`);
+Admin: https://${hostname2}/  \xB7  API docs: https://${hostname2}/api/v1/docs`);
     } else if (health.setup === "pending") {
       this.log(
         `
-Open the Setup Wizard to finish: https://${hostname}/  (or http://${ip ?? "<server-ip>"}/ until DNS resolves)`
+Open the Setup Wizard to finish: https://${hostname2}/  (or http://${ip ?? "<server-ip>"}/ until DNS resolves)`
       );
     } else {
       this.log(`
-Installed. Admin: https://${hostname}/`);
+Installed. Admin: https://${hostname2}/`);
     }
   }
+  /**
+   * Authenticate to the private registry before pulling. An install without a licence id is allowed
+   * to continue — self-built images need no credentials — but a *failure* to authenticate is
+   * reported and stops here, because the alternative is a confusing "image not found" from docker.
+   */
+  async registryLogin(env) {
+    const r = await registryLogin(env, fingerprint());
+    if (r.status === "failed") this.error(r.message, { exit: 3 });
+    this.log(r.message);
+  }
 };
 
 // src/commands/doctor.ts
@@ -1226,7 +2327,7 @@ var Doctor = class _Doctor extends Command2 {
 
 // src/commands/backup.ts
 import { Command as Command3, Flags as Flags3 } from "@oclif/core";
-import { createHash } from "node:crypto";
+import { createHash as createHash2 } from "node:crypto";
 import fs3 from "node:fs/promises";
 import path4 from "node:path";
 var Backup = class _Backup extends Command3 {
@@ -1241,7 +2342,7 @@ var Backup = class _Backup extends Command3 {
     this.log(`Backup written to ${target}`);
   }
 };
-var sha256 = async (file) => createHash("sha256").update(await fs3.readFile(file)).digest("hex");
+var sha256 = async (file) => createHash2("sha256").update(await fs3.readFile(file)).digest("hex");
 async function backup(dir, outRoot, log) {
   const env = await readEnv(dir);
   if (!env["DB_NAME"]) throw new Error(`no install found in ${dir}`);
@@ -1272,6 +2373,10 @@ async function backup(dir, outRoot, log) {
       "tar",
       "czf",
       "/backup/vmail.tar.gz",
+      // The Xapian full-text index (ADR 0013) sits beside each mailbox and is derived data: it would
+      // add a large fraction of the mail size to every backup for nothing. `mailctl restore` rebuilds
+      // it in the background on the first search, or `doveadm index -A '*'` forces it up front.
+      "--exclude=fts-flatcurve",
       "-C",
       "/var",
       "vmail"
@@ -1384,46 +2489,411 @@ var Restore = class _Restore extends Command4 {
 
 // src/commands/upgrade.ts
 import { Command as Command5, Flags as Flags5 } from "@oclif/core";
+
+// src/lib/upgrade.ts
+import path7 from "node:path";
+
+// src/lib/rollback.ts
+import fs5 from "node:fs/promises";
 import path6 from "node:path";
+var SNAPSHOT_DIR = ".upgrade-rollback";
+var SCHEMA_STATE_SQL = "select count(*)::text || '|' || coalesce(max(created_at)::text, '') from drizzle.__drizzle_migrations";
+function parseSchemaState(out) {
+  const [count, latest] = out.trim().split("|");
+  const n = Number(count);
+  if (!Number.isInteger(n) || latest === void 0) return null;
+  return { migrations: n, latest };
+}
+function rollbackDecision(before, after) {
+  if (!before || !after)
+    return {
+      kind: "unknown",
+      reason: !before ? "the database schema could not be read before the upgrade, so there is nothing to compare against" : "the database could not be read after the upgrade, so whether it was migrated is unknown"
+    };
+  if (before.migrations === after.migrations && before.latest === after.latest)
+    return {
+      kind: "roll_back",
+      reason: `the database was not migrated (${before.migrations} migrations, unchanged)`
+    };
+  return {
+    kind: "restore_required",
+    reason: `the database was migrated during the upgrade (${before.migrations} \u2192 ${after.migrations} migrations)`
+  };
+}
+var SNAPSHOT_FILES = [".env", "compose/compose.yaml", "docker/caddy/Caddyfile"];
+async function snapshot(dir) {
+  const out = path6.join(dir, SNAPSHOT_DIR);
+  await fs5.rm(out, { recursive: true, force: true });
+  await fs5.mkdir(path6.join(out, "compose"), { recursive: true });
+  await fs5.mkdir(path6.join(out, "docker", "caddy"), { recursive: true });
+  for (const f of SNAPSHOT_FILES) {
+    await fs5.copyFile(path6.join(dir, f), path6.join(out, f)).catch(() => void 0);
+  }
+  await fs5.chmod(path6.join(out, ".env"), 384).catch(() => void 0);
+}
+async function restoreSnapshot(dir) {
+  const out = path6.join(dir, SNAPSHOT_DIR);
+  const restored = [];
+  for (const f of SNAPSHOT_FILES) {
+    const from = path6.join(out, f);
+    if (!await fs5.stat(from).catch(() => null)) continue;
+    await fs5.mkdir(path6.dirname(path6.join(dir, f)), { recursive: true });
+    await fs5.copyFile(from, path6.join(dir, f));
+    restored.push(f);
+  }
+  await fs5.chmod(path6.join(dir, ".env"), 384).catch(() => void 0);
+  return restored;
+}
+var clearSnapshot = (dir) => fs5.rm(path6.join(dir, SNAPSHOT_DIR), { recursive: true, force: true });
+
+// src/lib/upgrade.ts
+var EXIT = {
+  upgraded: 0,
+  registry_refused: 3,
+  rolled_back: 4,
+  restore_required: 5,
+  left_in_place: 5
+};
+var result = (outcome, message) => ({
+  outcome,
+  exitCode: EXIT[outcome],
+  message
+});
+async function schemaState(deps, env) {
+  try {
+    const out = await deps.compose.execIn("postgres", [
+      "psql",
+      "-U",
+      env["DB_ADMIN_USER"] ?? "mail",
+      "-d",
+      env["DB_NAME"] ?? "mail",
+      "-tAc",
+      SCHEMA_STATE_SQL
+    ]);
+    return parseSchemaState(out.toString("utf8"));
+  } catch {
+    return null;
+  }
+}
+async function runUpgrade(deps, opts) {
+  const env = await readEnv(opts.dir);
+  if (!env["IMAGE_TAG"]) throw new Error(`no install found in ${opts.dir}`);
+  const from = env["IMAGE_TAG"];
+  deps.log(`Upgrading ${env["MAIL_HOSTNAME"]} from ${from} to ${opts.tag}`);
+  const before = await schemaState(deps, env);
+  await snapshot(opts.dir);
+  let backupDir = null;
+  if (!opts.skipBackup) {
+    backupDir = await deps.backup(opts.dir, path7.join(opts.dir, "backups"), deps.log);
+    deps.log(`Pre-upgrade backup: ${backupDir}`);
+  }
+  const hint = backupDir ? `mailctl restore --from ${backupDir}` : "mailctl restore --from <backup dir>  (this run used --skip-backup, so it made none)";
+  const defaults = defaultEnv({
+    hostname: env["MAIL_HOSTNAME"] ?? "",
+    tag: opts.tag,
+    registry: env["IMAGE_REGISTRY"] ?? "",
+    publicIp: env["PUBLIC_IP"]
+  });
+  const added = Object.keys(defaults).filter((k) => !(k in env));
+  if (added.length) deps.log(`Adding new .env keys: ${added.join(", ")}`);
+  await writeEnv(opts.dir, { ...defaults, ...env, IMAGE_TAG: opts.tag });
+  await deps.materialise(opts.dir);
+  const login = await deps.registryLogin(env, opts.fingerprint);
+  if (login.status === "failed") {
+    await restoreSnapshot(opts.dir);
+    await clearSnapshot(opts.dir);
+    return result("registry_refused", login.message);
+  }
+  deps.log(login.message);
+  try {
+    deps.log("Pulling images\u2026");
+    await deps.compose.pull();
+    deps.log("Restarting services (migrations run on API start)\u2026");
+    await deps.compose.up();
+    const h = await deps.api.waitHealthy(opts.healthTimeoutMs);
+    await clearSnapshot(opts.dir);
+    return result(
+      "upgraded",
+      `Upgrade complete: API reports version ${h.version}.
+If something is wrong later: ${hint}`
+    );
+  } catch (e) {
+    return recover(deps, opts, { from, before, hint, cause: e });
+  }
+}
+async function recover(deps, opts, ctx) {
+  deps.log("");
+  deps.log(`Upgrade failed: ${ctx.cause.message}`);
+  if (opts.noRollback)
+    return result("left_in_place", `Left in place as asked (--no-rollback). To undo it: ${ctx.hint}`);
+  const decision = rollbackDecision(ctx.before, await schemaState(deps, await readEnv(opts.dir)));
+  if (decision.kind !== "roll_back") {
+    deps.log(`Not rolling back automatically: ${decision.reason}.`);
+    return result(
+      "restore_required",
+      `Starting ${ctx.from} against this database could turn a recoverable failure into a permanent one, so nothing was changed back. Restore instead: ${ctx.hint}`
+    );
+  }
+  deps.log(`Rolling back to ${ctx.from} \u2014 ${decision.reason}.`);
+  const restored = await restoreSnapshot(opts.dir);
+  deps.log(`Restored ${restored.join(", ")}.`);
+  try {
+    await deps.compose.pull();
+    await deps.compose.up();
+    const h = await deps.api.waitHealthy(opts.healthTimeoutMs);
+    await clearSnapshot(opts.dir);
+    return result(
+      "rolled_back",
+      `Rolled back to ${ctx.from}: the API is healthy again and reports version ${h.version}.
+Nothing was lost. The upgrade that failed is described above.`
+    );
+  } catch (e) {
+    return result(
+      "restore_required",
+      `Rollback to ${ctx.from} also failed to come up healthy (${e.message}). Restore from the backup: ${ctx.hint}`
+    );
+  }
+}
+
+// src/commands/upgrade.ts
 var Upgrade = class _Upgrade extends Command5 {
-  static description = "Upgrade to a new version: pre-upgrade backup, pull images, restart, run migrations, verify health.";
+  static description = "Upgrade to a new version: pre-upgrade backup, pull images, restart, run migrations, verify health, and roll back automatically if the health check fails.";
   static flags = {
     dir: Flags5.string({ description: "install directory", default: DEFAULT_DIR }),
     tag: Flags5.string({ description: "target image tag (default: latest)", default: "latest" }),
     "skip-backup": Flags5.boolean({
       default: false,
       description: "skip the pre-upgrade backup (not recommended)"
+    }),
+    "no-rollback": Flags5.boolean({
+      default: false,
+      description: "leave a failed upgrade in place instead of restoring the previous release"
+    }),
+    "health-timeout": Flags5.integer({
+      description: "seconds to wait for the API to report healthy",
+      default: 180
     })
   };
   async run() {
     const { flags } = await this.parse(_Upgrade);
     const env = await readEnv(flags.dir);
     if (!env["IMAGE_TAG"]) this.error(`no install found in ${flags.dir}`);
-    this.log(`Upgrading ${env["MAIL_HOSTNAME"]} from ${env["IMAGE_TAG"]} to ${flags.tag}`);
-    if (!flags["skip-backup"]) {
-      const out = await backup(flags.dir, path6.join(flags.dir, "backups"), (m) => this.log(m));
-      this.log(`Pre-upgrade backup: ${out}`);
+    const r = await runUpgrade(
+      {
+        compose: compose(flags.dir),
+        api: new ApiClient(`http://127.0.0.1:${env["API_PORT"] ?? "3000"}`),
+        backup,
+        materialise,
+        registryLogin,
+        log: (m) => this.log(m)
+      },
+      {
+        dir: flags.dir,
+        tag: flags.tag,
+        fingerprint: fingerprint(),
+        skipBackup: flags["skip-backup"],
+        noRollback: flags["no-rollback"],
+        healthTimeoutMs: flags["health-timeout"] * 1e3
+      }
+    );
+    if (r.outcome === "upgraded" || r.outcome === "rolled_back") {
+      this.log(r.message);
+      if (r.exitCode !== 0) this.exit(r.exitCode);
+      return;
     }
-    const defaults = defaultEnv({
-      hostname: env["MAIL_HOSTNAME"] ?? "",
-      tag: flags.tag,
-      registry: env["IMAGE_REGISTRY"] ?? "",
-      publicIp: env["PUBLIC_IP"]
-    });
-    const added = Object.keys(defaults).filter((k) => !(k in env));
-    if (added.length) this.log(`Adding new .env keys: ${added.join(", ")}`);
-    await writeEnv(flags.dir, { ...defaults, ...env, IMAGE_TAG: flags.tag });
-    await materialise(flags.dir);
-    const c = compose(flags.dir);
-    this.log("Pulling images\u2026");
-    await c.pull();
-    this.log("Restarting services (migrations run on API start)\u2026");
-    await c.up();
-    const h = await new ApiClient(`http://127.0.0.1:${env["API_PORT"] ?? "3000"}`).waitHealthy(18e4);
-    this.log(`Upgrade complete: API reports version ${h.version}.`);
-    this.log(`If something is wrong: mailctl restore --from <backup dir> restores the pre-upgrade state.`);
+    this.error(r.message, { exit: r.exitCode });
+  }
+};
+
+// src/commands/license.ts
+import { Args, Command as Command6, Flags as Flags6 } from "@oclif/core";
+
+// src/lib/license.ts
+var TOKEN_ENV = "MAILDOCK_TOKEN";
+var line = (label, value) => `  ${`${label}:`.padEnd(16)} ${value}`;
+var date = (iso) => new Date(iso).toISOString().replace("T", " ").slice(0, 16) + " UTC";
+var limit = (used, max) => max > 0 ? `${used} of ${max}` : `${used} (unlimited)`;
+var HEADLINE = {
+  unlicensed: "no licence installed \u2014 nothing is enforced",
+  active: "active",
+  grace: "grace period \u2014 everything still works",
+  degraded: "degraded \u2014 new mailboxes and domains are refused"
+};
+function formatStatus(s) {
+  const out = [`Licence: ${HEADLINE[s.state]}`];
+  if (s.reason) out.push(`  ${s.reason}`);
+  if (s.state === "grace" && s.daysRemaining !== null)
+    out.push(`  ${s.daysRemaining} day(s) before new mailboxes and domains are refused.`);
+  if (s.state === "degraded")
+    out.push("  Delivery, IMAP, POP3, webmail and sending are unaffected and always will be.");
+  out.push("");
+  if (s.license) {
+    out.push(line("Licence ID", s.license.licenseId));
+    out.push(line("Tier", s.license.tier));
+    out.push(line("Issued to", s.license.issuedTo ?? "\u2014"));
+    out.push(line("Issued", date(s.license.issuedAt)));
+    out.push(line("Expires", date(s.license.expiresAt)));
+    if (s.license.features.length) out.push(line("Features", s.license.features.join(", ")));
+  }
+  out.push(line("Mailboxes", limit(s.usage.mailboxes, s.license?.maxMailboxes ?? 0)));
+  out.push(line("Domains", limit(s.usage.domains, s.license?.maxDomains ?? 0)));
+  out.push(line("Machine ID", s.machine));
+  out.push(line("Key bound to", s.license?.boundTo ?? "any machine"));
+  out.push(line("Last check-in", s.lastHeartbeatAt ? date(s.lastHeartbeatAt) : "not yet"));
+  if (s.lastError) out.push(line("Last error", s.lastError));
+  return out.join("\n");
+}
+function transferPlan(s) {
+  if (!s.license)
+    return {
+      kind: "no_license",
+      message: "No licence is installed on this server, so there is nothing to transfer. Run `mailctl license activate <key>` with the key for this subscription."
+    };
+  if (s.license.boundTo === null)
+    return {
+      kind: "portable",
+      message: `Licence ${s.license.licenseId} is not bound to a machine \u2014 it runs here as it stands, and no transfer is needed.`
+    };
+  if (s.license.boundTo === s.machine)
+    return {
+      kind: "already_here",
+      message: `Licence ${s.license.licenseId} is already bound to this machine (${s.machine}). Nothing to transfer.`
+    };
+  return {
+    kind: "mismatch",
+    licenseId: s.license.licenseId,
+    boundTo: s.license.boundTo,
+    machine: s.machine,
+    message: [
+      `Licence ${s.license.licenseId} is bound to machine ${s.license.boundTo}, but this server is ${s.machine}.`,
+      "",
+      "To move it here:",
+      `  1. Ask for licence ${s.license.licenseId} to be transferred to machine ${s.machine}.`,
+      "  2. Run this command again with the re-issued key:",
+      "       mailctl license transfer --key mdl1.\u2026",
+      "",
+      "Until then this server is degraded: it refuses new mailboxes and domains, and nothing else."
+    ].join("\n")
+  };
+}
+async function readKey(fromArg) {
+  if (fromArg?.trim()) return fromArg.trim();
+  const { password } = await import("@inquirer/prompts");
+  const key = await password({ message: "Licence key (mdl1.\u2026)", mask: false });
+  return key.trim();
+}
+async function resolveToken(api, opts = {}) {
+  const explicit = opts.token?.trim() || process.env[TOKEN_ENV]?.trim();
+  if (explicit) return explicit;
+  if (opts.interactive === false || !process.stdin.isTTY)
+    throw new Error(
+      `no credentials: pass --token, or set ${TOKEN_ENV} to an API token with the owner role (Admin UI \u2192 API tokens)`
+    );
+  const { input, password } = await import("@inquirer/prompts");
+  const email = opts.email ?? await input({ message: "Admin email" });
+  const pass = await password({ message: "Password" });
+  try {
+    return await api.login({ email, password: pass });
+  } catch (e) {
+    if (e instanceof ApiError2 && e.code === "totp_required")
+      return api.login({ email, password: pass, totp: await input({ message: "Two-factor code" }) });
+    throw e;
+  }
+}
+
+// src/commands/license.ts
+var common = {
+  dir: Flags6.string({ description: "install directory", default: DEFAULT_DIR }),
+  "api-url": Flags6.string({ description: "control plane base URL (default: the local install)" }),
+  token: Flags6.string({ description: "API token with the owner role; otherwise you are asked to sign in" }),
+  email: Flags6.string({ description: "admin email, to skip one prompt" })
+};
+async function apiFor(dir, override, fail) {
+  if (override) return new ApiClient(override.replace(/\/$/, ""));
+  const env = await readEnv(dir);
+  if (!env["API_PORT"] && !env["MAIL_HOSTNAME"])
+    fail(`no install found in ${dir} (missing .env) \u2014 pass --api-url to reach a server elsewhere`);
+  return new ApiClient(`http://127.0.0.1:${env["API_PORT"] ?? "3000"}`);
+}
+var failing = (s) => s.state === "degraded";
+var LicenseStatusCommand = class _LicenseStatusCommand extends Command6 {
+  static id = "license:status";
+  static description = "Show the licence: state, plan, usage against its limits, this machine\u2019s ID and the last check-in. Exits 1 when degraded.";
+  static examples = ["<%= config.bin %> license status"];
+  static flags = common;
+  async run() {
+    const { flags } = await this.parse(_LicenseStatusCommand);
+    const api = await apiFor(flags.dir, flags["api-url"], (m) => this.error(m));
+    const token = await resolveToken(api, { token: flags.token, email: flags.email });
+    const status = await api.licenseStatus(token);
+    this.log(formatStatus(status));
+    if (failing(status)) this.exit(1);
+  }
+};
+var LicenseActivateCommand = class _LicenseActivateCommand extends Command6 {
+  static id = "license:activate";
+  static description = "Install a licence key. The key is verified by the server before it is stored, so a bad one is refused here rather than silently ignored.";
+  static examples = [
+    "<%= config.bin %> license activate mdl1.\u2026",
+    "<%= config.bin %> license activate"
+  ];
+  static args = { key: Args.string({ description: "the mdl1.\u2026 key; prompted for when omitted" }) };
+  static flags = common;
+  async run() {
+    const { args, flags } = await this.parse(_LicenseActivateCommand);
+    const api = await apiFor(flags.dir, flags["api-url"], (m) => this.error(m));
+    const token = await resolveToken(api, { token: flags.token, email: flags.email });
+    const key = await readKey(args.key);
+    if (!key) this.error("no licence key given");
+    let status;
+    try {
+      status = await api.activateLicense(token, key);
+    } catch (e) {
+      if (e instanceof ApiError2 && e.code === "license_fingerprint_mismatch")
+        this.error(`${e.message}
+Run \`mailctl license transfer\` to see what moving it here involves.`);
+      throw e;
+    }
+    this.log(formatStatus(status));
+    await recordLicenseId(flags.dir, status, (m) => this.log(m));
+  }
+};
+var LicenseTransferCommand = class _LicenseTransferCommand extends Command6 {
+  static id = "license:transfer";
+  static description = "Move this subscription onto this machine: report the two machine IDs a transfer needs, and install the re-issued key.";
+  static examples = [
+    "<%= config.bin %> license transfer",
+    "<%= config.bin %> license transfer --key mdl1.\u2026"
+  ];
+  static flags = {
+    ...common,
+    key: Flags6.string({ description: "re-issued key to install, once the licence has been transferred" })
+  };
+  async run() {
+    const { flags } = await this.parse(_LicenseTransferCommand);
+    const api = await apiFor(flags.dir, flags["api-url"], (m) => this.error(m));
+    const token = await resolveToken(api, { token: flags.token, email: flags.email });
+    const plan = transferPlan(await api.licenseStatus(token));
+    if (flags.key) {
+      const status = await api.activateLicense(token, flags.key);
+      this.log("Licence installed on this machine.\n");
+      this.log(formatStatus(status));
+      await recordLicenseId(flags.dir, status, (m) => this.log(m));
+      return;
+    }
+    this.log(plan.message);
+    if (plan.kind === "mismatch") this.exit(1);
   }
 };
+async function recordLicenseId(dir, status, log) {
+  const id = status.license?.licenseId;
+  if (!id) return;
+  const env = await readEnv(dir);
+  if (Object.keys(env).length === 0 || env["LICENSE_ID"] === id) return;
+  await writeEnv(dir, { ...env, LICENSE_ID: id });
+  log(`
+Recorded LICENSE_ID=${id} in ${dir}/.env \u2014 image pulls authenticate with it.`);
+}
 
 // src/index.ts
 var PACKAGE_NAME = "@maildock/mailctl";
@@ -1432,21 +2902,42 @@ var COMMANDS = {
   doctor: Doctor,
   backup: Backup,
   restore: Restore,
-  upgrade: Upgrade
+  upgrade: Upgrade,
+  // oclif ids use ':' internally; `topicSeparator: ' '` is what makes them `mailctl license status`.
+  "license:status": LicenseStatusCommand,
+  "license:activate": LicenseActivateCommand,
+  "license:transfer": LicenseTransferCommand
 };
 export {
   Backup,
   COMMANDS,
   Doctor,
   Install,
+  LicenseActivateCommand,
+  LicenseStatusCommand,
+  LicenseTransferCommand,
   PACKAGE_NAME,
   Restore,
+  SNAPSHOT_DIR,
+  TOKEN_ENV,
   Upgrade,
+  assetsDir,
   blocking,
+  bundledCaddyfile,
+  bundledComposeFile,
+  clearSnapshot,
   defaultEnv,
   formatChecks,
+  formatStatus,
+  parseSchemaState,
   preflight,
   readEnv,
+  resolveToken,
+  restoreSnapshot,
+  rollbackDecision,
+  runUpgrade,
+  snapshot,
+  transferPlan,
   writeEnv
 };
 //# sourceMappingURL=index.js.map