ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
feat(mail): serverkit-mail extension backend (Stalwart engine)
Juan Denis2f36fa4c927d
diff --git a/builtin-extensions/serverkit-mail/backend/__init__.py b/builtin-extensions/serverkit-mail/backend/__init__.pynew file mode 100644index 00000000..4a3057cc--- /dev/null+++ b/builtin-extensions/serverkit-mail/backend/__init__.py@@ -0,0 +1,4 @@+"""ServerKit Mail Server extension backend package (Stalwart engine)."""+from .mail import mail_bp++__all__ = ['mail_bp']diff --git a/builtin-extensions/serverkit-mail/backend/dns_mail_service.py b/builtin-extensions/serverkit-mail/backend/dns_mail_service.pynew file mode 100644index 00000000..b3b2bede--- /dev/null+++ b/builtin-extensions/serverkit-mail/backend/dns_mail_service.py@@ -0,0 +1,239 @@+"""DKIM keygen + mail DNS record deployment (serverkit-mail extension).++Owns the DNS side of standing up a deliverable domain:++* :meth:`generate_dkim` — mint an RSA-2048 DKIM keypair (via ``cryptography``),+ store the PEM private key + base64 DER public key on the :class:`MailDomain`+ row, and expose the public half as a DKIM TXT value.+* :meth:`build_records` — the **pure, testable** record builder: given a domain+ row + optional server IP, return the exact list of records+ (MX/SPF/DKIM/DMARC/A) the domain needs. No side effects.+* :meth:`deploy_dns` — push those records through the core+ :class:`DNSProviderService` (``source='mail'`` for the ownership ledger),+ recording per-record results on the row. When no connected provider manages+ the zone, degrade to manual instructions.+* :meth:`dns_instructions` — the record list for the UI, provider or not.+* :meth:`request_cert` — best-effort Let's Encrypt cert for the mail hostname.++Best-effort throughout; the provider/SSL layers are imported lazily so a missing+dependency never breaks import, and nothing here raises to the caller.+"""+import base64+import json+import logging+import os++logger = logging.getLogger(__name__)++DEFAULT_SELECTOR = 'serverkit'+DMARC_POLICY = 'quarantine'+++class DkimDnsService:+ """Stateless DKIM + mail-DNS orchestration."""++ # ---------- DKIM key generation ----------++ @classmethod+ def generate_dkim(cls, domain_row):+ """Generate an RSA-2048 DKIM keypair and store it on *domain_row*.++ Returns ``{success, selector, dkim_value}`` (or an error dict). The+ private key is stored as PEM, the public key as base64 DER, and the+ DKIM TXT value ``v=DKIM1; k=rsa; p=<b64>`` is returned for display.+ """+ try:+ from cryptography.hazmat.primitives import serialization+ from cryptography.hazmat.primitives.asymmetric import rsa+ except ImportError as e:+ return {'success': False, 'error': f'cryptography is required for DKIM: {e}'}+ try:+ key = rsa.generate_private_key(public_exponent=65537, key_size=2048)+ private_pem = key.private_bytes(+ encoding=serialization.Encoding.PEM,+ format=serialization.PrivateFormat.TraditionalOpenSSL,+ encryption_algorithm=serialization.NoEncryption(),+ ).decode('ascii')+ public_der = key.public_key().public_bytes(+ encoding=serialization.Encoding.DER,+ format=serialization.PublicFormat.SubjectPublicKeyInfo,+ )+ public_b64 = base64.b64encode(public_der).decode('ascii')+ except Exception as e: # noqa: BLE001+ return {'success': False, 'error': f'DKIM key generation failed: {e}'}++ selector = domain_row.dkim_selector or DEFAULT_SELECTOR+ try:+ from app import db+ domain_row.dkim_selector = selector+ domain_row.dkim_private_key = private_pem+ domain_row.dkim_public_key = public_b64+ db.session.commit()+ except Exception as e: # noqa: BLE001+ try:+ from app import db+ db.session.rollback()+ except Exception:+ pass+ return {'success': False, 'error': f'Could not store DKIM key: {e}'}++ return {+ 'success': True,+ 'selector': selector,+ 'dkim_value': cls._dkim_txt_value(public_b64),+ }++ @staticmethod+ def _dkim_txt_value(public_b64):+ return f'v=DKIM1; k=rsa; p={public_b64}'++ # ---------- pure record builder (testable) ----------++ @classmethod+ def build_records(cls, domain_row, server_ip=None):+ """Return the list of DNS records *domain_row* needs. Pure, no I/O.++ Each record is ``{type, name, value}`` (plus ``priority`` for MX). The+ DKIM record is included only once a key has been generated.+ """+ name = (domain_row.name or '').strip().lower().rstrip('.')+ selector = domain_row.dkim_selector or DEFAULT_SELECTOR+ mail_host = f'mail.{name}'+ records = [+ {'type': 'MX', 'name': name, 'value': f'10 {mail_host}', 'priority': 10},+ {'type': 'TXT', 'name': name, 'value': 'v=spf1 mx a ~all'},+ {'type': 'TXT', 'name': f'_dmarc.{name}',+ 'value': f'v=DMARC1; p={DMARC_POLICY}; rua=mailto:postmaster@{name}'},+ ]+ if domain_row.dkim_public_key:+ records.append({+ 'type': 'TXT',+ 'name': f'{selector}._domainkey.{name}',+ 'value': cls._dkim_txt_value(domain_row.dkim_public_key),+ })+ if server_ip:+ records.append({'type': 'A', 'name': mail_host, 'value': server_ip})+ return records++ # ---------- DNS deployment ----------++ @classmethod+ def deploy_dns(cls, domain_id, server_ip=None):+ """Deploy the domain's mail records through a connected DNS provider.++ Records the per-record result on ``MailDomain.dns_last_result`` and sets+ ``dns_deployed``. When no connected provider manages the zone, returns+ ``{success: True, deployed: False, manual: True, records: [...]}`` so the+ caller can show manual instructions. Never raises.+ """+ try:+ from app import db+ from .models import MailDomain+ except Exception as e: # noqa: BLE001+ return {'success': False, 'error': f'Model import failed: {e}'}++ domain_row = MailDomain.query.get(domain_id)+ if not domain_row:+ return {'success': False, 'error': 'Domain not found'}++ records = cls.build_records(domain_row, server_ip=server_ip)++ try:+ from app.services.dns_provider_service import DNSProviderService+ except Exception as e: # noqa: BLE001+ return {'success': True, 'deployed': False, 'manual': True,+ 'records': records, 'note': f'DNS provider layer unavailable: {e}'}++ try:+ config, zone = DNSProviderService.find_zone_for_domain(domain_row.name)+ except Exception as e: # noqa: BLE001+ return {'success': True, 'deployed': False, 'manual': True,+ 'records': records, 'note': f'Provider lookup failed: {e}'}++ if not config or not zone:+ return {'success': True, 'deployed': False, 'manual': True,+ 'records': records,+ 'note': f'No connected DNS provider manages {domain_row.name}.'}++ results = {}+ all_ok = True+ for rec in records:+ key = f"{rec['type'].lower()}:{rec['name']}"+ try:+ res = DNSProviderService.set_record(+ config.id, zone['id'], rec['type'], rec['name'], rec['value'],+ priority=rec.get('priority'), source='mail')+ except Exception as e: # noqa: BLE001+ res = {'success': False, 'error': str(e)}+ results[key] = {'success': bool(res.get('success')),+ 'error': res.get('error'),+ 'record': rec}+ all_ok = all_ok and bool(res.get('success'))++ payload = {'provider': config.name, 'zone': zone.get('name'),+ 'results': results, 'all_ok': all_ok}+ try:+ domain_row.dns_last_result = json.dumps(payload)+ domain_row.dns_deployed = all_ok+ db.session.commit()+ except Exception as e: # noqa: BLE001+ try:+ db.session.rollback()+ except Exception:+ pass+ logger.warning('Could not persist DNS deploy result: %s', e)++ cls._notify_deployed(domain_row.name, all_ok)+ return {'success': all_ok, 'deployed': all_ok, 'manual': False,+ 'provider': config.name, 'zone': zone.get('name'),+ 'results': results, 'records': records}++ @staticmethod+ def _notify_deployed(domain, all_ok):+ try:+ from app.plugins_sdk import notify+ notify.send('mail.dns_deployed', to='admins',+ data={'domain': domain, 'all_ok': all_ok}, category='system')+ except Exception as e: # noqa: BLE001+ logger.debug('mail.dns_deployed notify failed: %s', e)++ @classmethod+ def dns_instructions(cls, domain_row, server_ip=None):+ """Return the records the operator must publish (for the UI), plus the+ current deployment status. Provider-independent."""+ deployed = bool(getattr(domain_row, 'dns_deployed', False))+ last_result = None+ if getattr(domain_row, 'dns_last_result', None):+ try:+ last_result = json.loads(domain_row.dns_last_result)+ except (ValueError, TypeError):+ last_result = None+ return {+ 'domain': domain_row.name,+ 'records': cls.build_records(domain_row, server_ip=server_ip),+ 'dns_deployed': deployed,+ 'dns_last_result': last_result,+ 'dkim_configured': bool(getattr(domain_row, 'dkim_private_key', None)),+ }++ # ---------- TLS certificate ----------++ @classmethod+ def request_cert(cls, hostname):+ """Best-effort Let's Encrypt cert for ``mail.<hostname>``. Linux-only."""+ if os.name == 'nt':+ return {'success': False, 'skipped': True,+ 'error': 'Certificate issuance is not supported on this OS.'}+ hostname = (hostname or '').strip().lower().rstrip('.')+ if not hostname:+ return {'success': False, 'error': 'A hostname is required'}+ try:+ from app.services.ssl_service import SSLService+ except Exception as e: # noqa: BLE001+ return {'success': False, 'error': f'SSL service unavailable: {e}'}+ email = f'postmaster@{hostname.split(".", 1)[-1]}' if '.' in hostname else f'postmaster@{hostname}'+ try:+ result = SSLService.obtain_certificate([hostname], email, use_nginx=True)+ except Exception as e: # noqa: BLE001+ return {'success': False, 'error': f'Certificate request failed: {e}'}+ return resultdiff --git a/builtin-extensions/serverkit-mail/backend/jobs.py b/builtin-extensions/serverkit-mail/backend/jobs.pynew file mode 100644index 00000000..c7df64f9--- /dev/null+++ b/builtin-extensions/serverkit-mail/backend/jobs.py@@ -0,0 +1,70 @@+"""Background job handlers (serverkit-mail extension).++Registered via the manifest ``jobs`` block; each handler takes the ``job`` row+and must never raise (a raised handler fails the job loudly — these are+best-effort maintenance tasks).++* ``mail.preflight.run`` (:func:`run_preflight`) — re-check deliverability for the+ configured hostname on a daily schedule; notify admins if it regressed to+ failing.+* ``mail.queue.flush`` (:func:`flush_queue`) — ask Stalwart to retry its outbound+ queue.+"""+import logging++logger = logging.getLogger(__name__)++SLUG = 'serverkit-mail'+++def run_preflight(job):+ """Re-run the deliverability preflight for the configured hostname.++ Reads the hostname from the plugin config store, re-runs preflight, and —+ when the verdict regressed from passing to failing — notifies admins. Never+ raises.+ """+ try:+ from app.plugins_sdk import config as plugin_config+ from .preflight_service import PreflightService++ cfg = plugin_config(SLUG)+ hostname = cfg.get('hostname')+ server_ip = cfg.get('server_ip')+ if not hostname:+ return {'skipped': True, 'reason': 'no hostname configured'}++ previous = PreflightService.latest()+ was_passing = bool(previous and previous.get('passed'))++ result = PreflightService.run(hostname, server_ip=server_ip)+ now_passing = bool(result and result.get('passed'))++ if was_passing and not now_passing:+ _notify_regression(hostname, result)++ return {'hostname': hostname, 'passed': now_passing,+ 'regressed': was_passing and not now_passing}+ except Exception as e: # noqa: BLE001 — a maintenance job must not crash the loop+ logger.warning('mail preflight job failed: %s', e)+ return {'error': str(e)}+++def _notify_regression(hostname, result):+ try:+ from app.plugins_sdk import notify+ notify.send('mail.preflight_failed', to='admins',+ data={'hostname': hostname, 'result': result},+ category='system')+ except Exception as e: # noqa: BLE001+ logger.debug('mail.preflight_failed notify failed: %s', e)+++def flush_queue(job):+ """Best-effort flush of the Stalwart outbound queue. Never raises."""+ try:+ from .stalwart_service import StalwartService+ return StalwartService.flush_queue()+ except Exception as e: # noqa: BLE001+ logger.warning('mail queue flush job failed: %s', e)+ return {'error': str(e)}diff --git a/builtin-extensions/serverkit-mail/backend/lifecycle.py b/builtin-extensions/serverkit-mail/backend/lifecycle.pynew file mode 100644index 00000000..ad423ec2--- /dev/null+++ b/builtin-extensions/serverkit-mail/backend/lifecycle.py@@ -0,0 +1,43 @@+"""Install / uninstall lifecycle hooks (serverkit-mail extension).++Contract (per the plugin SDK): a single positional arg — the InstalledPlugin+row. ``on_uninstall`` also accepts a ``purge`` flag. Everything here is wrapped+so a hook failure never blocks install/uninstall.+"""+import logging++logger = logging.getLogger(__name__)+++def on_install(plugin):+ """Register the extension's notification events. Best-effort."""+ try:+ from app.plugins_sdk import notify+ notify.register_event(+ 'mail.preflight_failed',+ 'Mail deliverability preflight failed',+ template='generic', severity='warning', category='system')+ notify.register_event(+ 'mail.dns_deployed',+ 'Mail DNS records deployed',+ template='generic', severity='success', category='system')+ logger.info('serverkit-mail installed: notification events registered')+ except Exception as e: # noqa: BLE001+ logger.warning('serverkit-mail on_install hook error: %s', e)+++def on_uninstall(plugin, purge=False):+ """Best-effort stop/remove the Stalwart container on uninstall.++ On ``purge`` the mail data directory is deleted too; otherwise the container+ is removed but the data is kept so a reinstall can pick it back up.+ """+ try:+ from .stalwart_service import StalwartService+ if StalwartService.is_installed():+ result = StalwartService.uninstall(keep_data=not purge)+ logger.info('serverkit-mail on_uninstall: %s', result)+ else:+ logger.info('serverkit-mail on_uninstall: container not present')+ except Exception as e: # noqa: BLE001+ logger.warning('serverkit-mail on_uninstall hook error: %s', e)diff --git a/builtin-extensions/serverkit-mail/backend/mail.py b/builtin-extensions/serverkit-mail/backend/mail.pynew file mode 100644index 00000000..e2200717--- /dev/null+++ b/builtin-extensions/serverkit-mail/backend/mail.py@@ -0,0 +1,392 @@+"""Mail Server API endpoints (serverkit-mail extension).++Mounted under ``/api/v1/mail`` via the manifest's ``url_prefix``. Thin routing+layer over the extension services — all Docker, Stalwart-API, DNS, and DKIM work+happens in the services. Reads need viewer, mutations need admin (same split as+the serverkit-dns-server extension).++``_installed_or_error`` guards only the routes that genuinely need a running+Stalwart engine (``/queue``, ``/service/<action>``). Domain/mailbox/forwarder+CRUD writes to *our* DB and reconciles to Stalwart best-effort, so it works even+before the engine is installed (operators can stage config first).+"""+from flask import Blueprint, jsonify, request++from app.middleware.rbac import admin_required, viewer_required++from .mail_service import MailService+from .stalwart_service import StalwartService+from .preflight_service import PreflightService+from .dns_mail_service import DkimDnsService++mail_bp = Blueprint('mail', __name__)++_NOT_INSTALLED = (+ 'The mail server is not installed. Install it from the Mail Server page '+ '(admin only).'+)+++def _installed_or_error():+ """Return an error response tuple when the engine is absent, else None."""+ if not StalwartService.is_installed():+ return jsonify({'error': _NOT_INSTALLED}), 503+ return None+++def _server_ip(data=None):+ """Resolve the server public IP: explicit body value, else system settings."""+ if data and data.get('server_ip'):+ return str(data['server_ip']).strip()+ try:+ from app.services.site_domain_service import SiteDomainService+ return SiteDomainService.server_ip()+ except Exception: # noqa: BLE001+ return None+++def _domain_or_404(domain_id):+ from .models import MailDomain+ return MailDomain.query.get(domain_id)+++# ── Status / lifecycle ──++@mail_bp.route('/status', methods=['GET'])+@viewer_required+def get_status():+ """Engine status + latest deliverability preflight."""+ return jsonify(MailService.get_status()), 200+++@mail_bp.route('/install', methods=['POST'])+@admin_required+def install():+ """Start the Stalwart container: {hostname}."""+ data = request.get_json() or {}+ hostname = (data.get('hostname') or '').strip()+ if not hostname:+ return jsonify({'error': 'hostname is required'}), 400+ result = StalwartService.install(hostname)+ if not result.get('success'):+ return jsonify({'error': result.get('error', 'Install failed')}), 400+ return jsonify(result), 201+++@mail_bp.route('/install', methods=['DELETE'])+@admin_required+def uninstall():+ """Remove the container (?keep_data=true keeps the mail data)."""+ keep_data = (request.args.get('keep_data', 'true').lower()+ not in ('false', '0', 'no'))+ result = StalwartService.uninstall(keep_data=keep_data)+ if not result.get('success'):+ return jsonify({'error': result.get('error', 'Uninstall failed')}), 400+ return jsonify(result), 200+++@mail_bp.route('/service/<action>', methods=['POST'])+@admin_required+def control_service(action):+ """Start / stop / restart the engine container."""+ guard = _installed_or_error()+ if guard:+ return guard+ if action not in ('start', 'stop', 'restart'):+ return jsonify({'error': "action must be start, stop or restart"}), 400+ result = StalwartService.control(action)+ if not result.get('success'):+ return jsonify({'error': result.get('error', 'Service control failed')}), 400+ return jsonify(result), 200+++# ── Preflight ──++@mail_bp.route('/preflight', methods=['GET'])+@viewer_required+def get_preflight():+ """Latest persisted preflight result (or null)."""+ return jsonify({'preflight': PreflightService.latest()}), 200+++@mail_bp.route('/preflight', methods=['POST'])+@admin_required+def run_preflight():+ """Run and persist a deliverability preflight: {hostname, server_ip?}."""+ data = request.get_json() or {}+ hostname = (data.get('hostname') or '').strip()+ if not hostname:+ return jsonify({'error': 'hostname is required'}), 400+ server_ip = _server_ip(data)+ result = PreflightService.run(hostname, server_ip=server_ip)+ return jsonify(result), 200+++# ── Domains ──++@mail_bp.route('/domains', methods=['GET'])+@viewer_required+def list_domains():+ return jsonify({'domains': MailService.list_domains()}), 200+++@mail_bp.route('/domains', methods=['POST'])+@admin_required+def add_domain():+ """Add a mail domain: {name, catch_all_target?}."""+ data = request.get_json() or {}+ name = (data.get('name') or '').strip()+ if not name:+ return jsonify({'error': 'name is required'}), 400+ result = MailService.add_domain(name, catch_all_target=data.get('catch_all_target'))+ if not result.get('success'):+ return jsonify({'error': result.get('error', 'Failed to add domain')}), 400+ return jsonify(result), 201+++@mail_bp.route('/domains/<int:domain_id>', methods=['GET'])+@viewer_required+def get_domain(domain_id):+ domain = MailService.get_domain(domain_id)+ if not domain:+ return jsonify({'error': 'Domain not found'}), 404+ return jsonify(domain), 200+++@mail_bp.route('/domains/<int:domain_id>', methods=['PATCH'])+@admin_required+def update_domain(domain_id):+ """Update a domain: {is_active?, catch_all_target?}. Activation is gated on a+ passing preflight (or ?force=true)."""+ data = request.get_json() or {}+ force = (request.args.get('force', 'false').lower() in ('true', '1', 'yes')) \+ or bool(data.get('force'))+ is_active = data.get('is_active')+ if is_active is not None:+ result = MailService.set_domain_active(domain_id, bool(is_active), force=force)+ else:+ result = MailService.update_domain(+ domain_id, catch_all_target=data.get('catch_all_target'))+ if not result.get('success'):+ code = 409 if result.get('code') == 'preflight_required' else 400+ return jsonify({'error': result.get('error', 'Update failed'),+ 'preflight': result.get('preflight')}), code+ return jsonify(result), 200+++@mail_bp.route('/domains/<int:domain_id>', methods=['DELETE'])+@admin_required+def remove_domain(domain_id):+ result = MailService.remove_domain(domain_id)+ if not result.get('success'):+ return jsonify({'error': result.get('error', 'Failed to remove domain')}), 400+ return jsonify(result), 200+++# ── DKIM / DNS / cert ──++@mail_bp.route('/domains/<int:domain_id>/dkim', methods=['POST'])+@admin_required+def generate_dkim(domain_id):+ domain = _domain_or_404(domain_id)+ if not domain:+ return jsonify({'error': 'Domain not found'}), 404+ result = DkimDnsService.generate_dkim(domain)+ if not result.get('success'):+ return jsonify({'error': result.get('error', 'DKIM generation failed')}), 400+ return jsonify(result), 200+++@mail_bp.route('/domains/<int:domain_id>/dns', methods=['GET'])+@viewer_required+def dns_instructions(domain_id):+ domain = _domain_or_404(domain_id)+ if not domain:+ return jsonify({'error': 'Domain not found'}), 404+ return jsonify(DkimDnsService.dns_instructions(domain, server_ip=_server_ip())), 200+++@mail_bp.route('/domains/<int:domain_id>/dns/deploy', methods=['POST'])+@admin_required+def deploy_dns(domain_id):+ domain = _domain_or_404(domain_id)+ if not domain:+ return jsonify({'error': 'Domain not found'}), 404+ data = request.get_json(silent=True) or {}+ result = DkimDnsService.deploy_dns(domain_id, server_ip=_server_ip(data))+ # A manual-instructions outcome is still a 200 (there's nothing to fix).+ if not result.get('success') and not result.get('manual'):+ return jsonify(result), 400+ return jsonify(result), 200+++@mail_bp.route('/domains/<int:domain_id>/cert', methods=['POST'])+@admin_required+def request_cert(domain_id):+ domain = _domain_or_404(domain_id)+ if not domain:+ return jsonify({'error': 'Domain not found'}), 404+ result = DkimDnsService.request_cert(f'mail.{domain.name}')+ if not result.get('success'):+ return jsonify(result), 200 if result.get('skipped') else 400+ return jsonify(result), 200+++# ── Mailboxes ──++@mail_bp.route('/domains/<int:domain_id>/mailboxes', methods=['GET'])+@viewer_required+def list_mailboxes(domain_id):+ if not _domain_or_404(domain_id):+ return jsonify({'error': 'Domain not found'}), 404+ return jsonify({'mailboxes': MailService.list_mailboxes(domain_id)}), 200+++@mail_bp.route('/domains/<int:domain_id>/mailboxes', methods=['POST'])+@admin_required+def add_mailbox(domain_id):+ """Create a mailbox: {local_part, password, quota_mb?, display_name?}."""+ data = request.get_json() or {}+ local_part = (data.get('local_part') or '').strip()+ password = data.get('password')+ if not local_part:+ return jsonify({'error': 'local_part is required'}), 400+ if not password:+ return jsonify({'error': 'password is required'}), 400+ result = MailService.add_mailbox(+ domain_id, local_part, password,+ quota_mb=data.get('quota_mb', 0),+ display_name=data.get('display_name'))+ if not result.get('success'):+ return jsonify({'error': result.get('error', 'Failed to create mailbox')}), 400+ return jsonify(result), 201+++@mail_bp.route('/mailboxes/<int:mailbox_id>', methods=['PATCH'])+@admin_required+def update_mailbox(mailbox_id):+ """Update a mailbox: {quota_mb?, is_active?, display_name?}."""+ data = request.get_json() or {}+ result = MailService.update_mailbox(+ mailbox_id,+ quota_mb=data.get('quota_mb'),+ is_active=data.get('is_active'),+ display_name=data.get('display_name'))+ if not result.get('success'):+ return jsonify({'error': result.get('error', 'Failed to update mailbox')}), 400+ return jsonify(result), 200+++@mail_bp.route('/mailboxes/<int:mailbox_id>/password', methods=['POST'])+@admin_required+def set_mailbox_password(mailbox_id):+ """Set a mailbox password: {password}."""+ data = request.get_json() or {}+ password = data.get('password')+ if not password:+ return jsonify({'error': 'password is required'}), 400+ result = MailService.set_mailbox_password(mailbox_id, password)+ if not result.get('success'):+ return jsonify({'error': result.get('error', 'Failed to set password')}), 400+ return jsonify(result), 200+++@mail_bp.route('/mailboxes/<int:mailbox_id>', methods=['DELETE'])+@admin_required+def remove_mailbox(mailbox_id):+ result = MailService.remove_mailbox(mailbox_id)+ if not result.get('success'):+ return jsonify({'error': result.get('error', 'Failed to remove mailbox')}), 400+ return jsonify(result), 200+++# ── Autoresponder ──++@mail_bp.route('/mailboxes/<int:mailbox_id>/autoresponder', methods=['GET'])+@viewer_required+def get_autoresponder(mailbox_id):+ result = MailService.get_autoresponder(mailbox_id)+ if result is None:+ return jsonify({'error': 'Mailbox not found'}), 404+ return jsonify({'autoresponder': result}), 200+++@mail_bp.route('/mailboxes/<int:mailbox_id>/autoresponder', methods=['PUT'])+@admin_required+def set_autoresponder(mailbox_id):+ """Set the autoresponder: {enabled, subject, body, start_at?, end_at?}."""+ data = request.get_json() or {}+ result = MailService.set_autoresponder(+ mailbox_id,+ enabled=data.get('enabled'),+ subject=data.get('subject'),+ body=data.get('body'),+ start_at=data.get('start_at'),+ end_at=data.get('end_at'))+ if not result.get('success'):+ return jsonify({'error': result.get('error', 'Failed to save autoresponder')}), 400+ return jsonify(result), 200+++# ── Forwarders ──++@mail_bp.route('/domains/<int:domain_id>/forwarders', methods=['GET'])+@viewer_required+def list_forwarders(domain_id):+ if not _domain_or_404(domain_id):+ return jsonify({'error': 'Domain not found'}), 404+ return jsonify({'forwarders': MailService.list_forwarders(domain_id)}), 200+++@mail_bp.route('/domains/<int:domain_id>/forwarders', methods=['POST'])+@admin_required+def add_forwarder(domain_id):+ """Create a forwarder: {source_local_part, destination, keep_copy?}."""+ data = request.get_json() or {}+ source = (data.get('source_local_part') or '').strip()+ destination = (data.get('destination') or '').strip()+ if not source:+ return jsonify({'error': 'source_local_part is required'}), 400+ if not destination:+ return jsonify({'error': 'destination is required'}), 400+ result = MailService.add_forwarder(+ domain_id, source, destination, keep_copy=bool(data.get('keep_copy')))+ if not result.get('success'):+ return jsonify({'error': result.get('error', 'Failed to create forwarder')}), 400+ return jsonify(result), 201+++@mail_bp.route('/forwarders/<int:forwarder_id>', methods=['DELETE'])+@admin_required+def remove_forwarder(forwarder_id):+ result = MailService.remove_forwarder(forwarder_id)+ if not result.get('success'):+ return jsonify({'error': result.get('error', 'Failed to remove forwarder')}), 400+ return jsonify(result), 200+++# ── Queue ──++@mail_bp.route('/queue', methods=['GET'])+@viewer_required+def get_queue():+ """Outbound queue messages from the Stalwart admin API (best-effort)."""+ guard = _installed_or_error()+ if guard:+ return guard+ result = StalwartService.list_queue()+ return jsonify({'messages': result.get('messages', []),+ 'note': result.get('note')}), 200+++@mail_bp.route('/queue/flush', methods=['POST'])+@admin_required+def flush_queue():+ """Ask Stalwart to retry/flush the outbound queue (best-effort)."""+ guard = _installed_or_error()+ if guard:+ return guard+ result = StalwartService.flush_queue()+ if not result.get('success'):+ return jsonify({'error': result.get('error', 'Queue flush failed')}), 400+ return jsonify(result), 200diff --git a/builtin-extensions/serverkit-mail/backend/mail_backup.py b/builtin-extensions/serverkit-mail/backend/mail_backup.pynew file mode 100644index 00000000..73cc0bdb--- /dev/null+++ b/builtin-extensions/serverkit-mail/backend/mail_backup.py@@ -0,0 +1,58 @@+"""Register the mail data directory as a backup policy (serverkit-mail extension).++Thin, best-effort binder over the core :class:`BackupPolicyService`: a mail+domain's maildir lives under the Stalwart data dir, so we register that path as a+``files`` backup target with a daily schedule. Everything is wrapped so a missing+BackupPolicyService (or a dev shell without the job bus) is non-fatal.+"""+import logging++from .stalwart_service import DATA_DIR++logger = logging.getLogger(__name__)+++def register_backup_policy(domain_row):+ """Register/enable a daily files backup of the mail data dir for *domain_row*.++ Best-effort: returns ``{success, ...}`` and never raises.+ """+ try:+ from app.services.backup_policy_service import BackupPolicyService+ except Exception as e: # noqa: BLE001+ logger.debug('BackupPolicyService unavailable, skipping mail backup: %s', e)+ return {'success': False, 'skipped': True, 'error': str(e)}+ try:+ policy = BackupPolicyService.get_or_create_policy(+ target_type='files',+ target_id=domain_row.id,+ target_subtype='pathlist',+ target_meta={'label': f'mail:{domain_row.name}', 'paths': [DATA_DIR]},+ )+ BackupPolicyService.update_policy(policy, {+ 'enabled': True,+ 'schedule_cron': '0 3 * * *', # daily at 03:00+ })+ return {'success': True, 'policy_id': policy.id}+ except Exception as e: # noqa: BLE001+ logger.warning('Could not register mail backup policy for %s: %s',+ getattr(domain_row, 'name', '?'), e)+ return {'success': False, 'error': str(e)}+++def unregister_backup_policy(domain_row):+ """Disable the mail backup policy for *domain_row*. Best-effort; never raises.++ The policy row (and its history) is intentionally left in place — only the+ schedule is disabled — so a re-added domain keeps its backup lineage.+ """+ try:+ from app.services.backup_policy_service import BackupPolicyService+ policy = BackupPolicyService.get_policy('files', domain_row.id)+ if not policy:+ return {'success': True, 'skipped': True}+ BackupPolicyService.update_policy(policy, {'enabled': False})+ return {'success': True, 'policy_id': policy.id}+ except Exception as e: # noqa: BLE001+ logger.debug('Could not unregister mail backup policy: %s', e)+ return {'success': False, 'error': str(e)}diff --git a/builtin-extensions/serverkit-mail/backend/mail_jail_service.py b/builtin-extensions/serverkit-mail/backend/mail_jail_service.pynew file mode 100644index 00000000..84b43c5a--- /dev/null+++ b/builtin-extensions/serverkit-mail/backend/mail_jail_service.py@@ -0,0 +1,165 @@+"""Fail2ban brute-force jails for the mail server (serverkit-mail extension).++Mirrors the core :class:`Fail2banJailService` write-half pattern: ServerKit-owned+``serverkit-mail-*`` jail files under ``/etc/fail2ban/jail.d``, written with+privilege (``sudo tee``), reloaded via ``fail2ban-client reload``.++The auth jail watches the mail auth log for repeated SMTP/IMAP login failures and+bans the offending IP. Best-effort and Linux-only: on Windows (dev) or when+fail2ban is absent, every mutating call returns a ``skipped`` descriptor instead+of raising, so mail setup degrades gracefully.+"""+import logging+import os++from app.utils.system import run_privileged, is_command_available, ServiceControl++logger = logging.getLogger(__name__)+++class MailJailService:+ JAIL_DIR = '/etc/fail2ban/jail.d'+ JAIL_PREFIX = 'serverkit-mail-'+ AUTH_JAIL = 'serverkit-mail-auth'++ # 5 auth failures within 10 min -> 1 hour ban.+ MAXRETRY = 5+ FINDTIME = 600+ BANTIME = 3600++ # Stalwart writes its log inside the container data dir bind-mounted to the+ # host; fall back to the common dovecot/postfix filters if present. The jail+ # uses the stock filters so it works without a custom filter file.+ LOG_PATH = '/var/serverkit/mail/logs/stalwart.log'++ JAIL_TEMPLATE = '''# ServerKit-managed mail brute-force jail.+# Generated by MailJailService - do not edit by hand (regenerated on change).+[{jail}]+enabled = true+filter = {filter}+port = smtp,submission,smtps,imap,imaps,pop3,pop3s+logpath = {logpath}+maxretry = {maxretry}+findtime = {findtime}+bantime = {bantime}+'''++ # ---------- availability ----------++ @classmethod+ def available(cls):+ """True only on a Linux host where the fail2ban client is installed."""+ if os.name == 'nt':+ return False+ return is_command_available('fail2ban-client')++ @staticmethod+ def _unavailable():+ return {+ 'success': True, 'skipped': True, 'available': False, 'reason': 'unavailable',+ 'message': 'fail2ban is not available on this host; mail brute-force '+ 'protection is inactive.',+ }++ # ---------- file helpers ----------++ @classmethod+ def _jail_path(cls):+ filename = f'{cls.AUTH_JAIL}.conf'+ if (not filename.startswith(cls.JAIL_PREFIX)+ or '/' in filename or '\\' in filename or '..' in filename):+ raise ValueError(f'refusing to target non-ServerKit jail file: {filename!r}')+ return os.path.join(cls.JAIL_DIR, filename)++ @staticmethod+ def _write_file(path, content):+ """Write *content* to *path* with privilege (sudo tee)."""+ try:+ proc = run_privileged(['tee', path], input=content)+ if getattr(proc, 'returncode', 1) != 0:+ return {'success': False, 'error': (getattr(proc, 'stderr', '') or 'write failed').strip()}+ return {'success': True, 'path': path}+ except Exception as e: # noqa: BLE001+ return {'success': False, 'error': str(e)}++ @classmethod+ def _render_jail(cls):+ return cls.JAIL_TEMPLATE.format(+ jail=cls.AUTH_JAIL,+ filter='postfix-sasl', # stock filter; broadly present on Debian/RHEL+ logpath=cls.LOG_PATH,+ maxretry=cls.MAXRETRY,+ findtime=cls.FINDTIME,+ bantime=cls.BANTIME,+ )++ # ---------- jail lifecycle ----------++ @classmethod+ def enable_auth_jail(cls):+ """Create/refresh the mail auth brute-force jail and reload fail2ban."""+ if not cls.available():+ return cls._unavailable()+ try:+ path = cls._jail_path()+ except ValueError as e:+ return {'success': False, 'error': str(e)}+ written = cls._write_file(path, cls._render_jail())+ if not written.get('success'):+ return written+ reloaded = cls.reload()+ return {'success': True, 'enabled': True, 'jail': cls.AUTH_JAIL,+ 'path': path, 'reloaded': reloaded.get('success')}++ @classmethod+ def disable_auth_jail(cls):+ """Remove the mail auth jail file and reload fail2ban. No-op when absent."""+ if not cls.available():+ return cls._unavailable()+ try:+ path = cls._jail_path()+ except ValueError as e:+ return {'success': False, 'error': str(e)}+ if not os.path.exists(path):+ return {'success': True, 'removed': False, 'message': 'no jail to remove'}+ try:+ proc = run_privileged(['rm', '-f', path])+ if getattr(proc, 'returncode', 1) != 0:+ return {'success': False, 'error': (getattr(proc, 'stderr', '') or 'remove failed').strip()}+ except Exception as e: # noqa: BLE001+ return {'success': False, 'error': str(e)}+ reloaded = cls.reload()+ return {'success': True, 'removed': True, 'jail': cls.AUTH_JAIL,+ 'reloaded': reloaded.get('success')}++ @classmethod+ def reload(cls):+ """``fail2ban-client reload`` (keeps existing bans), falling back to a+ service restart if the client call fails. Never raises."""+ if not cls.available():+ return cls._unavailable()+ try:+ proc = run_privileged(['fail2ban-client', 'reload'], timeout=30)+ if getattr(proc, 'returncode', 1) == 0:+ return {'success': True, 'message': 'fail2ban reloaded'}+ except Exception:+ pass+ try:+ res = ServiceControl.restart('fail2ban', timeout=30)+ return {'success': getattr(res, 'returncode', 1) == 0,+ 'message': 'fail2ban restarted' if getattr(res, 'returncode', 1) == 0+ else (getattr(res, 'stderr', '') or 'reload failed')}+ except Exception as e: # noqa: BLE001+ return {'success': False, 'error': str(e)}++ @classmethod+ def status(cls):+ """Availability + whether the auth jail file exists."""+ info = {'available': cls.available(), 'enabled': False, 'jail': cls.AUTH_JAIL}+ if not cls.available():+ return info+ try:+ info['enabled'] = os.path.exists(cls._jail_path())+ except ValueError:+ info['enabled'] = False+ return infodiff --git a/builtin-extensions/serverkit-mail/backend/mail_service.py b/builtin-extensions/serverkit-mail/backend/mail_service.pynew file mode 100644index 00000000..dc0bc4a7--- /dev/null+++ b/builtin-extensions/serverkit-mail/backend/mail_service.py@@ -0,0 +1,442 @@+"""DB <-> Stalwart orchestration (serverkit-mail extension).++The panel's tables (:mod:`.models`) are the source of truth for what mail objects+*should* exist; this service is the reconcile layer. Every mutation:++1. Writes the panel DB (this always succeeds, or returns a clean 400).+2. Best-effort reconciles the change to Stalwart via :class:`StalwartService`.+3. Records the outcome on the row's ``sync_state`` / ``sync_error``.++A Stalwart failure therefore never loses panel state: the row exists with+``sync_state='error'`` and the call returns ``{success: True, sync_state:+'error', ...}`` so the panel can surface and later re-sync the drift. Everything+is wrapped so a missing Stalwart/Docker (dev) never raises.++Activation gate: :meth:`set_domain_active` refuses to activate a domain (which+enables outbound sending) unless the latest :class:`PreflightResult` passed, or an+explicit ``force=True`` override is passed (which is audit-logged).+"""+import logging++logger = logging.getLogger(__name__)+++class MailService:+ """Stateless DB/Stalwart reconcile orchestration."""++ # ---------- helpers ----------++ @staticmethod+ def _db():+ from app import db+ return db++ @staticmethod+ def _models():+ from . import models+ return models++ @staticmethod+ def _stalwart():+ from .stalwart_service import StalwartService+ return StalwartService++ @classmethod+ def _apply_sync(cls, row, result):+ """Fold a StalwartService reconcile *result* into a row's sync state."""+ if result.get('success'):+ row.sync_state = 'synced'+ row.sync_error = None+ else:+ row.sync_state = 'error'+ row.sync_error = result.get('error') or 'Stalwart sync failed'+ return row++ @staticmethod+ def _norm(value):+ return (value or '').strip().lower().rstrip('.')++ # ---------- status ----------++ @classmethod+ def get_status(cls):+ """Engine status merged with the latest deliverability preflight."""+ status = cls._stalwart().get_status()+ try:+ from .preflight_service import PreflightService+ status['preflight'] = PreflightService.latest()+ except Exception as e: # noqa: BLE001+ logger.debug('preflight latest failed: %s', e)+ status['preflight'] = None+ try:+ from .models import MailDomain+ status['domains_count'] = MailDomain.query.count()+ except Exception: # noqa: BLE001+ status['domains_count'] = 0+ return status++ # ---------- domains ----------++ @classmethod+ def list_domains(cls):+ MailDomain = cls._models().MailDomain+ return [d.to_dict() for d in MailDomain.query.order_by(MailDomain.name).all()]++ @classmethod+ def get_domain(cls, domain_id):+ MailDomain = cls._models().MailDomain+ row = MailDomain.query.get(domain_id)+ return row.to_dict() if row else None++ @classmethod+ def add_domain(cls, name, catch_all_target=None):+ db = cls._db()+ MailDomain = cls._models().MailDomain+ name = cls._norm(name)+ if not name or '.' not in name:+ return {'success': False, 'error': f'Invalid domain name: {name!r}'}+ if MailDomain.query.filter_by(name=name).first():+ return {'success': False, 'error': f'Domain {name} already exists'}+ row = MailDomain(name=name,+ catch_all_target=(catch_all_target or '').strip() or None,+ is_active=False, sync_state='pending')+ try:+ db.session.add(row)+ db.session.commit()+ except Exception as e: # noqa: BLE001+ db.session.rollback()+ return {'success': False, 'error': str(e)}++ result = cls._safe(lambda: cls._stalwart().upsert_domain(name))+ cls._apply_sync(row, result)+ db.session.commit()+ return {'success': True, 'domain': row.to_dict(),+ 'sync_state': row.sync_state, 'sync_error': row.sync_error}++ @classmethod+ def update_domain(cls, domain_id, is_active=None, catch_all_target=None):+ """Update mutable domain fields (catch-all + activation).++ Activation is delegated to :meth:`set_domain_active` so the preflight+ gate cannot be bypassed here.+ """+ db = cls._db()+ MailDomain = cls._models().MailDomain+ row = MailDomain.query.get(domain_id)+ if not row:+ return {'success': False, 'error': 'Domain not found'}++ if catch_all_target is not None:+ row.catch_all_target = (catch_all_target or '').strip() or None+ db.session.commit()++ if is_active is not None:+ return cls.set_domain_active(domain_id, bool(is_active))++ return {'success': True, 'domain': row.to_dict()}++ @classmethod+ def set_domain_active(cls, domain_id, active, force=False):+ """Activate/deactivate a domain. Activation enables outbound sending and+ is **gated** on the latest preflight passing, unless ``force=True`` (which+ is audit-logged)."""+ db = cls._db()+ MailDomain = cls._models().MailDomain+ row = MailDomain.query.get(domain_id)+ if not row:+ return {'success': False, 'error': 'Domain not found'}++ if active:+ from .preflight_service import PreflightService+ latest = None+ try:+ latest = PreflightService.latest()+ except Exception as e: # noqa: BLE001+ logger.debug('preflight check failed during activation: %s', e)+ passed = bool(latest and latest.get('passed'))+ if not passed and not force:+ return {'success': False, 'code': 'preflight_required',+ 'error': 'Deliverability preflight has not passed. Run '+ 'preflight and resolve any failures, or activate '+ 'with force to override.',+ 'preflight': latest}+ if not passed and force:+ cls._audit('mail.domain.activate_forced', row.id, {+ 'domain': row.name,+ 'preflight_passed': passed,+ })++ row.is_active = bool(active)+ db.session.commit()++ # Reconcile: ensure the domain principal exists when activating.+ if active:+ result = cls._safe(lambda: cls._stalwart().upsert_domain(row.name))+ cls._apply_sync(row, result)+ db.session.commit()++ return {'success': True, 'domain': row.to_dict(),+ 'sync_state': row.sync_state, 'sync_error': row.sync_error}++ @classmethod+ def remove_domain(cls, domain_id):+ db = cls._db()+ MailDomain = cls._models().MailDomain+ row = MailDomain.query.get(domain_id)+ if not row:+ return {'success': False, 'error': 'Domain not found'}+ name = row.name+ # Best-effort Stalwart cleanup before the DB delete (cascade removes+ # mailboxes/forwarders/autoresponders panel-side).+ cls._safe(lambda: cls._stalwart().delete_domain(name))+ try:+ from .mail_backup import unregister_backup_policy+ unregister_backup_policy(row)+ except Exception as e: # noqa: BLE001+ logger.debug('backup unregister failed: %s', e)+ try:+ db.session.delete(row)+ db.session.commit()+ except Exception as e: # noqa: BLE001+ db.session.rollback()+ return {'success': False, 'error': str(e)}+ return {'success': True, 'message': f'Domain {name} removed'}++ # ---------- mailboxes ----------++ @classmethod+ def list_mailboxes(cls, domain_id):+ Mailbox = cls._models().Mailbox+ rows = Mailbox.query.filter_by(domain_id=domain_id).order_by(Mailbox.local_part).all()+ return [m.to_dict() for m in rows]++ @classmethod+ def get_mailbox(cls, mailbox_id):+ Mailbox = cls._models().Mailbox+ row = Mailbox.query.get(mailbox_id)+ return row.to_dict() if row else None++ @classmethod+ def add_mailbox(cls, domain_id, local_part, password, quota_mb=0, display_name=None):+ """Create a mailbox. ``password`` is required (set on Stalwart only) and is+ NEVER persisted panel-side."""+ db = cls._db()+ models = cls._models()+ MailDomain, Mailbox = models.MailDomain, models.Mailbox+ domain = MailDomain.query.get(domain_id)+ if not domain:+ return {'success': False, 'error': 'Domain not found'}+ local_part = (local_part or '').strip().lower()+ if not local_part or '@' in local_part:+ return {'success': False, 'error': f'Invalid local part: {local_part!r}'}+ if not password:+ return {'success': False, 'error': 'A password is required'}+ if Mailbox.query.filter_by(domain_id=domain_id, local_part=local_part).first():+ return {'success': False,+ 'error': f'Mailbox {local_part}@{domain.name} already exists'}++ row = Mailbox(domain_id=domain_id, local_part=local_part,+ quota_mb=int(quota_mb or 0),+ display_name=(display_name or '').strip() or None,+ is_active=True, sync_state='pending')+ try:+ db.session.add(row)+ db.session.commit()+ except Exception as e: # noqa: BLE001+ db.session.rollback()+ return {'success': False, 'error': str(e)}++ email = f'{local_part}@{domain.name}'+ result = cls._safe(lambda: cls._stalwart().upsert_account(+ email, password=password, quota_mb=row.quota_mb, display_name=row.display_name))+ cls._apply_sync(row, result)+ db.session.commit()+ # password intentionally discarded here — never stored.+ return {'success': True, 'mailbox': row.to_dict(),+ 'sync_state': row.sync_state, 'sync_error': row.sync_error}++ @classmethod+ def update_mailbox(cls, mailbox_id, quota_mb=None, is_active=None, display_name=None):+ db = cls._db()+ Mailbox = cls._models().Mailbox+ row = Mailbox.query.get(mailbox_id)+ if not row:+ return {'success': False, 'error': 'Mailbox not found'}+ if quota_mb is not None:+ row.quota_mb = int(quota_mb)+ if display_name is not None:+ row.display_name = (display_name or '').strip() or None+ if is_active is not None:+ row.is_active = bool(is_active)+ db.session.commit()++ result = cls._safe(lambda: cls._stalwart().upsert_account(+ row.email, quota_mb=row.quota_mb, display_name=row.display_name))+ cls._apply_sync(row, result)+ db.session.commit()+ return {'success': True, 'mailbox': row.to_dict(),+ 'sync_state': row.sync_state, 'sync_error': row.sync_error}++ @classmethod+ def set_mailbox_password(cls, mailbox_id, password):+ db = cls._db()+ Mailbox = cls._models().Mailbox+ row = Mailbox.query.get(mailbox_id)+ if not row:+ return {'success': False, 'error': 'Mailbox not found'}+ if not password:+ return {'success': False, 'error': 'A password is required'}+ result = cls._safe(lambda: cls._stalwart().set_password(row.email, password))+ cls._apply_sync(row, result)+ db.session.commit()+ return {'success': True, 'sync_state': row.sync_state,+ 'sync_error': row.sync_error}++ @classmethod+ def remove_mailbox(cls, mailbox_id):+ db = cls._db()+ Mailbox = cls._models().Mailbox+ row = Mailbox.query.get(mailbox_id)+ if not row:+ return {'success': False, 'error': 'Mailbox not found'}+ email = row.email+ cls._safe(lambda: cls._stalwart().delete_account(email))+ try:+ db.session.delete(row)+ db.session.commit()+ except Exception as e: # noqa: BLE001+ db.session.rollback()+ return {'success': False, 'error': str(e)}+ return {'success': True, 'message': f'Mailbox {email} removed'}++ # ---------- autoresponder ----------++ @classmethod+ def get_autoresponder(cls, mailbox_id):+ models = cls._models()+ Mailbox, Autoresponder = models.Mailbox, models.Autoresponder+ if not Mailbox.query.get(mailbox_id):+ return None+ row = Autoresponder.query.filter_by(mailbox_id=mailbox_id).first()+ if row:+ return row.to_dict()+ # A not-yet-configured autoresponder reads as a disabled shell.+ return {'mailbox_id': mailbox_id, 'enabled': False, 'subject': None,+ 'body': None, 'start_at': None, 'end_at': None}++ @classmethod+ def set_autoresponder(cls, mailbox_id, enabled=None, subject=None, body=None,+ start_at=None, end_at=None):+ db = cls._db()+ models = cls._models()+ Mailbox, Autoresponder = models.Mailbox, models.Autoresponder+ if not Mailbox.query.get(mailbox_id):+ return {'success': False, 'error': 'Mailbox not found'}+ row = Autoresponder.query.filter_by(mailbox_id=mailbox_id).first()+ if not row:+ row = Autoresponder(mailbox_id=mailbox_id)+ db.session.add(row)+ if enabled is not None:+ row.enabled = bool(enabled)+ if subject is not None:+ row.subject = subject+ if body is not None:+ row.body = body+ if start_at is not None:+ row.start_at = cls._parse_dt(start_at)+ if end_at is not None:+ row.end_at = cls._parse_dt(end_at)+ try:+ db.session.commit()+ except Exception as e: # noqa: BLE001+ db.session.rollback()+ return {'success': False, 'error': str(e)}+ return {'success': True, 'autoresponder': row.to_dict()}++ @staticmethod+ def _parse_dt(value):+ if not value:+ return None+ if hasattr(value, 'isoformat'):+ return value+ from datetime import datetime+ try:+ return datetime.fromisoformat(str(value).replace('Z', '+00:00'))+ except (ValueError, TypeError):+ return None++ # ---------- forwarders ----------++ @classmethod+ def list_forwarders(cls, domain_id):+ Forwarder = cls._models().Forwarder+ rows = Forwarder.query.filter_by(domain_id=domain_id).order_by(+ Forwarder.source_local_part).all()+ return [f.to_dict() for f in rows]++ @classmethod+ def add_forwarder(cls, domain_id, source_local_part, destination, keep_copy=False):+ db = cls._db()+ models = cls._models()+ MailDomain, Forwarder = models.MailDomain, models.Forwarder+ domain = MailDomain.query.get(domain_id)+ if not domain:+ return {'success': False, 'error': 'Domain not found'}+ source_local_part = (source_local_part or '').strip().lower()+ destination = (destination or '').strip()+ if not source_local_part or '@' in source_local_part:+ return {'success': False, 'error': f'Invalid source: {source_local_part!r}'}+ if not destination:+ return {'success': False, 'error': 'A destination is required'}+ row = Forwarder(domain_id=domain_id, source_local_part=source_local_part,+ destination=destination, keep_copy=bool(keep_copy),+ is_active=True, sync_state='pending')+ try:+ db.session.add(row)+ db.session.commit()+ except Exception as e: # noqa: BLE001+ db.session.rollback()+ return {'success': False, 'error': str(e)}++ # Forwarders map to an aliased principal on Stalwart; reconcile best-effort.+ email = f'{source_local_part}@{domain.name}'+ result = cls._safe(lambda: cls._stalwart().upsert_account(email))+ cls._apply_sync(row, result)+ db.session.commit()+ return {'success': True, 'forwarder': row.to_dict(),+ 'sync_state': row.sync_state, 'sync_error': row.sync_error}++ @classmethod+ def remove_forwarder(cls, forwarder_id):+ db = cls._db()+ Forwarder = cls._models().Forwarder+ row = Forwarder.query.get(forwarder_id)+ if not row:+ return {'success': False, 'error': 'Forwarder not found'}+ try:+ db.session.delete(row)+ db.session.commit()+ except Exception as e: # noqa: BLE001+ db.session.rollback()+ return {'success': False, 'error': str(e)}+ return {'success': True, 'message': 'Forwarder removed'}++ # ---------- internals ----------++ @staticmethod+ def _safe(fn):+ """Run a best-effort Stalwart reconcile call; never raise."""+ try:+ result = fn()+ return result if isinstance(result, dict) else {'success': bool(result)}+ except Exception as e: # noqa: BLE001+ logger.debug('Stalwart reconcile call failed: %s', e)+ return {'success': False, 'error': str(e)}++ @staticmethod+ def _audit(action, target_id, details):+ try:+ from app.plugins_sdk import audit+ audit(action, 'mail_domain', target_id=target_id, details=details)+ except Exception as e: # noqa: BLE001+ logger.debug('audit %s failed: %s', action, e)diff --git a/builtin-extensions/serverkit-mail/backend/models.py b/builtin-extensions/serverkit-mail/backend/models.pynew file mode 100644index 00000000..f03cbb87--- /dev/null+++ b/builtin-extensions/serverkit-mail/backend/models.py@@ -0,0 +1,269 @@+"""Data models for the serverkit-mail extension.++These tables are the panel-side **source of truth** for what mail objects+*should* exist; :class:`StalwartService` reconciles them to the running Stalwart+engine best-effort and each row records its own ``sync_state`` / ``sync_error``+so a Stalwart API failure never corrupts panel state (the row simply reports+drift).++Tables are namespaced ``ext_serverkit_mail_*`` (dash → underscore) per the+extension convention, so ``purge_models`` on uninstall drops exactly these.++Registration: importing this module defines the tables on the shared metadata as+a side effect; the manifest's ``models: "models:register"`` then calls+:func:`register` (a no-op passthrough) and the platform runs ``db.create_all()``.++Security: mailbox passwords are **never** persisted here — they live only on the+Stalwart engine. There is no password column on :class:`Mailbox`.+"""+from datetime import datetime++from app import db+++class MailDomain(db.Model):+ __tablename__ = 'ext_serverkit_mail_domains'++ id = db.Column(db.Integer, primary_key=True)+ name = db.Column(db.String(255), unique=True, nullable=False, index=True)+ is_active = db.Column(db.Boolean, default=False)+ catch_all_target = db.Column(db.String(255), nullable=True)++ # DKIM+ dkim_selector = db.Column(db.String(63), default='serverkit')+ dkim_private_key = db.Column(db.Text, nullable=True)+ dkim_public_key = db.Column(db.Text, nullable=True)++ # DNS deployment ledger+ dns_deployed = db.Column(db.Boolean, default=False)+ dns_last_result = db.Column(db.Text, nullable=True) # JSON string++ # Reconcile state against the Stalwart engine+ sync_state = db.Column(db.String(20), default='pending') # pending|synced|error+ sync_error = db.Column(db.Text, nullable=True)++ created_at = db.Column(db.DateTime, default=datetime.utcnow)+ updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)++ mailboxes = db.relationship('Mailbox', backref='domain', lazy=True,+ cascade='all, delete-orphan')+ forwarders = db.relationship('Forwarder', backref='domain', lazy=True,+ cascade='all, delete-orphan')++ def to_dict(self):+ import json+ dns_result = None+ if self.dns_last_result:+ try:+ dns_result = json.loads(self.dns_last_result)+ except (ValueError, TypeError):+ dns_result = None+ return {+ 'id': self.id,+ 'name': self.name,+ 'is_active': bool(self.is_active),+ 'catch_all_target': self.catch_all_target,+ 'dkim_selector': self.dkim_selector,+ 'dkim_public_key': self.dkim_public_key,+ 'dkim_configured': bool(self.dkim_private_key),+ 'dns_deployed': bool(self.dns_deployed),+ 'dns_last_result': dns_result,+ 'sync_state': self.sync_state,+ 'sync_error': self.sync_error,+ 'mailboxes_count': len(self.mailboxes) if self.mailboxes else 0,+ 'forwarders_count': len(self.forwarders) if self.forwarders else 0,+ 'created_at': self.created_at.isoformat() if self.created_at else None,+ 'updated_at': self.updated_at.isoformat() if self.updated_at else None,+ }++ def __repr__(self):+ return f'<MailDomain {self.name}>'+++class Mailbox(db.Model):+ __tablename__ = 'ext_serverkit_mail_mailboxes'+ __table_args__ = (+ db.UniqueConstraint('domain_id', 'local_part', name='uq_mail_mailbox_local'),+ )++ id = db.Column(db.Integer, primary_key=True)+ domain_id = db.Column(db.Integer,+ db.ForeignKey('ext_serverkit_mail_domains.id'),+ nullable=False, index=True)+ local_part = db.Column(db.String(255), nullable=False)+ quota_mb = db.Column(db.Integer, default=0) # 0 == unlimited+ is_active = db.Column(db.Boolean, default=True)+ display_name = db.Column(db.String(255), nullable=True)++ # NO password column — passwords live only on Stalwart, never persisted.+ sync_state = db.Column(db.String(20), default='pending')+ sync_error = db.Column(db.Text, nullable=True)++ created_at = db.Column(db.DateTime, default=datetime.utcnow)+ updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)++ autoresponder = db.relationship('Autoresponder', backref='mailbox', uselist=False,+ lazy=True, cascade='all, delete-orphan')++ @property+ def email(self):+ return f'{self.local_part}@{self.domain.name}' if self.domain else self.local_part++ def to_dict(self):+ return {+ 'id': self.id,+ 'domain_id': self.domain_id,+ 'domain_name': self.domain.name if self.domain else None,+ 'local_part': self.local_part,+ 'email': self.email,+ 'quota_mb': self.quota_mb,+ 'is_active': bool(self.is_active),+ 'display_name': self.display_name,+ 'sync_state': self.sync_state,+ 'sync_error': self.sync_error,+ 'created_at': self.created_at.isoformat() if self.created_at else None,+ 'updated_at': self.updated_at.isoformat() if self.updated_at else None,+ }++ def __repr__(self):+ return f'<Mailbox {self.email}>'+++class Forwarder(db.Model):+ __tablename__ = 'ext_serverkit_mail_forwarders'++ id = db.Column(db.Integer, primary_key=True)+ domain_id = db.Column(db.Integer,+ db.ForeignKey('ext_serverkit_mail_domains.id'),+ nullable=False, index=True)+ source_local_part = db.Column(db.String(255), nullable=False)+ destination = db.Column(db.Text, nullable=False) # may be an external address+ keep_copy = db.Column(db.Boolean, default=False)+ is_active = db.Column(db.Boolean, default=True)++ sync_state = db.Column(db.String(20), default='pending')+ sync_error = db.Column(db.Text, nullable=True)++ created_at = db.Column(db.DateTime, default=datetime.utcnow)+ updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)++ @property+ def source(self):+ return f'{self.source_local_part}@{self.domain.name}' if self.domain else self.source_local_part++ def to_dict(self):+ return {+ 'id': self.id,+ 'domain_id': self.domain_id,+ 'domain_name': self.domain.name if self.domain else None,+ 'source_local_part': self.source_local_part,+ 'source': self.source,+ 'destination': self.destination,+ 'keep_copy': bool(self.keep_copy),+ 'is_active': bool(self.is_active),+ 'sync_state': self.sync_state,+ 'sync_error': self.sync_error,+ 'created_at': self.created_at.isoformat() if self.created_at else None,+ 'updated_at': self.updated_at.isoformat() if self.updated_at else None,+ }++ def __repr__(self):+ return f'<Forwarder {self.source} -> {self.destination}>'+++class Autoresponder(db.Model):+ __tablename__ = 'ext_serverkit_mail_autoresponders'++ id = db.Column(db.Integer, primary_key=True)+ mailbox_id = db.Column(db.Integer,+ db.ForeignKey('ext_serverkit_mail_mailboxes.id'),+ nullable=False, unique=True, index=True)+ enabled = db.Column(db.Boolean, default=False)+ subject = db.Column(db.String(500), nullable=True)+ body = db.Column(db.Text, nullable=True)+ start_at = db.Column(db.DateTime, nullable=True)+ end_at = db.Column(db.DateTime, nullable=True)++ created_at = db.Column(db.DateTime, default=datetime.utcnow)+ updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)++ def to_dict(self):+ return {+ 'id': self.id,+ 'mailbox_id': self.mailbox_id,+ 'enabled': bool(self.enabled),+ 'subject': self.subject,+ 'body': self.body,+ 'start_at': self.start_at.isoformat() if self.start_at else None,+ 'end_at': self.end_at.isoformat() if self.end_at else None,+ 'created_at': self.created_at.isoformat() if self.created_at else None,+ 'updated_at': self.updated_at.isoformat() if self.updated_at else None,+ }++ def __repr__(self):+ return f'<Autoresponder mailbox={self.mailbox_id} enabled={self.enabled}>'+++class PreflightResult(db.Model):+ __tablename__ = 'ext_serverkit_mail_preflight'++ id = db.Column(db.Integer, primary_key=True)+ hostname = db.Column(db.String(255), nullable=True, index=True)+ server_ip = db.Column(db.String(64), nullable=True)++ ptr_ok = db.Column(db.Boolean, default=False)+ ptr_value = db.Column(db.String(255), nullable=True)+ port25_ok = db.Column(db.Boolean, default=False)+ rbl_ok = db.Column(db.Boolean, default=False)+ rbl_hits = db.Column(db.Text, nullable=True) # JSON list+ ports_ok = db.Column(db.Boolean, default=False)++ passed = db.Column(db.Boolean, default=False)+ detail = db.Column(db.Text, nullable=True) # JSON object++ checked_at = db.Column(db.DateTime, default=datetime.utcnow, index=True)+ created_at = db.Column(db.DateTime, default=datetime.utcnow)+ updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)++ def to_dict(self):+ import json+ rbl_hits = []+ if self.rbl_hits:+ try:+ rbl_hits = json.loads(self.rbl_hits)+ except (ValueError, TypeError):+ rbl_hits = []+ detail = None+ if self.detail:+ try:+ detail = json.loads(self.detail)+ except (ValueError, TypeError):+ detail = None+ return {+ 'id': self.id,+ 'hostname': self.hostname,+ 'server_ip': self.server_ip,+ 'ptr_ok': bool(self.ptr_ok),+ 'ptr_value': self.ptr_value,+ 'port25_ok': bool(self.port25_ok),+ 'rbl_ok': bool(self.rbl_ok),+ 'rbl_hits': rbl_hits,+ 'ports_ok': bool(self.ports_ok),+ 'passed': bool(self.passed),+ 'detail': detail,+ 'checked_at': self.checked_at.isoformat() if self.checked_at else None,+ 'created_at': self.created_at.isoformat() if self.created_at else None,+ 'updated_at': self.updated_at.isoformat() if self.updated_at else None,+ }++ def __repr__(self):+ return f'<PreflightResult {self.hostname} passed={self.passed}>'+++def register(db): # noqa: A002 — signature dictated by the platform (fn(db))+ """No-op passthrough required by the manifest ``models: "models:register"``.++ Importing this module already registered the tables on the metadata; the+ platform calls this then runs ``db.create_all()``. Returns ``None``.+ """+ return Nonediff --git a/builtin-extensions/serverkit-mail/backend/preflight_service.py b/builtin-extensions/serverkit-mail/backend/preflight_service.pynew file mode 100644index 00000000..037cd23e--- /dev/null+++ b/builtin-extensions/serverkit-mail/backend/preflight_service.py@@ -0,0 +1,236 @@+"""Deliverability preflight checks (serverkit-mail extension).++Running a mail server that the world will *accept* mail from has hard host+prerequisites that a panel cannot fix for you. This service checks them and+persists the verdict; :class:`MailService` refuses to activate outbound sending+for a domain until the latest preflight ``passed`` (or an explicit force+override is logged).++Checks (all best-effort, individually monkeypatchable for tests):++* **PTR / reverse DNS** — the server IP's PTR record must resolve back to the+ mail hostname (``socket.gethostbyaddr``). Mismatched PTR is the #1 reason big+ providers reject mail.+* **Port-25 egress** — many VPS providers block outbound TCP :25. We try to open+ a connection to a public MX on :25 with a short timeout.+* **RBL / DNSBL** — query a couple of well-known blocklists for the reversed+ server IP; any hit means the IP is listed.+* **Local listening ports** — best-effort check that the mail ports are open+ locally.++On Windows / dev, every host-dependent check returns ``skipped`` and the overall+verdict is ``passed=False`` with a clear note. Nothing here ever raises.+"""+import json+import logging+import os+import socket++logger = logging.getLogger(__name__)++# A public MX we can dial on :25 to prove outbound egress is not blocked.+PORT25_PROBE_HOST = 'gmail-smtp-in.l.google.com'+PORT25_PROBE_PORT = 25+PORT25_TIMEOUT = 6++# DNSBLs queried for the reversed server IP.+RBL_ZONES = ('zen.spamhaus.org', 'bl.spamcop.net')++# Mail ports we expect to be listening locally once Stalwart is up.+LOCAL_PORTS = (25, 465, 587, 993)+++class PreflightService:+ """Stateless deliverability preflight runner."""++ # ---------- individual checks (monkeypatchable) ----------++ @staticmethod+ def _check_ptr(hostname, server_ip):+ """Reverse-DNS: does the server IP's PTR match *hostname*?++ Returns ``(ok, ptr_value, note)``.+ """+ if os.name == 'nt':+ return None, None, 'skipped (not supported on this OS)'+ if not server_ip:+ return None, None, 'skipped (no server IP provided)'+ try:+ ptr_value = socket.gethostbyaddr(server_ip)[0]+ except (OSError, socket.herror) as e:+ return False, None, f'PTR lookup failed: {e}'+ ptr_norm = (ptr_value or '').strip().lower().rstrip('.')+ host_norm = (hostname or '').strip().lower().rstrip('.')+ ok = bool(host_norm) and ptr_norm == host_norm+ note = None if ok else f'PTR {ptr_norm!r} does not match hostname {host_norm!r}'+ return ok, ptr_value, note++ @staticmethod+ def _check_port25():+ """Outbound TCP :25 egress test against a public MX.++ Returns ``(ok, note)``.+ """+ if os.name == 'nt':+ return None, 'skipped (not supported on this OS)'+ try:+ conn = socket.create_connection(+ (PORT25_PROBE_HOST, PORT25_PROBE_PORT), timeout=PORT25_TIMEOUT)+ conn.close()+ return True, None+ except OSError as e:+ return False, (f'Could not open outbound :25 to {PORT25_PROBE_HOST} '+ f'({e}) — your provider likely blocks port 25.')++ @staticmethod+ def _reverse_ip(server_ip):+ """Return the reversed dotted-quad of an IPv4 address, or None."""+ parts = (server_ip or '').split('.')+ if len(parts) != 4 or not all(p.isdigit() and 0 <= int(p) <= 255 for p in parts):+ return None+ return '.'.join(reversed(parts))++ @classmethod+ def _check_rbl(cls, server_ip):+ """Query the DNSBLs for the reversed server IP.++ Returns ``(ok, hits, note)`` — ``ok`` is True when the IP is on no list.+ """+ if os.name == 'nt':+ return None, [], 'skipped (not supported on this OS)'+ if not server_ip:+ return None, [], 'skipped (no server IP provided)'+ reversed_ip = cls._reverse_ip(server_ip)+ if not reversed_ip:+ return None, [], 'skipped (non-IPv4 address)'+ hits = []+ checked = 0+ for zone in RBL_ZONES:+ query = f'{reversed_ip}.{zone}'+ try:+ socket.gethostbyname(query)+ hits.append(zone) # a resolvable A record == listed+ checked += 1+ except socket.gaierror:+ checked += 1 # NXDOMAIN == not listed (the good case)+ except OSError:+ continue # transient resolver error — don't count it+ if checked == 0:+ return None, [], 'skipped (RBL resolvers unreachable)'+ ok = not hits+ note = None if ok else f'Listed on: {", ".join(hits)}'+ return ok, hits, note++ @staticmethod+ def _check_local_ports():+ """Best-effort: are the mail ports listening on localhost?++ Returns ``(ok, note)``. This is advisory only — a fresh install may not+ be running yet — so it never drives the pass/fail verdict on its own.+ """+ if os.name == 'nt':+ return None, 'skipped (not supported on this OS)'+ open_ports = []+ for port in LOCAL_PORTS:+ try:+ conn = socket.create_connection(('127.0.0.1', port), timeout=2)+ conn.close()+ open_ports.append(port)+ except OSError:+ continue+ ok = bool(open_ports)+ note = None if ok else 'No mail ports are listening locally yet.'+ return ok, note++ # ---------- orchestration ----------++ @classmethod+ def run(cls, hostname, server_ip=None):+ """Run all checks, persist a :class:`PreflightResult`, and return its dict.++ ``passed`` requires the *critical* checks (PTR, port-25 egress, RBL) to+ pass. Skipped checks (Windows/dev, missing IP) count as not-passed so a+ dev box never green-lights sending. Never raises.+ """+ hostname = (hostname or '').strip().lower().rstrip('.')++ ptr_ok, ptr_value, ptr_note = cls._check_ptr(hostname, server_ip)+ port25_ok, port25_note = cls._check_port25()+ rbl_ok, rbl_hits, rbl_note = cls._check_rbl(server_ip)+ ports_ok, ports_note = cls._check_local_ports()++ # Critical checks must be explicitly True (None/skipped => not passed).+ critical = [ptr_ok, port25_ok, rbl_ok]+ passed = all(c is True for c in critical)++ detail = {+ 'ptr': {'ok': ptr_ok, 'value': ptr_value, 'note': ptr_note},+ 'port25': {'ok': port25_ok, 'note': port25_note},+ 'rbl': {'ok': rbl_ok, 'hits': rbl_hits, 'note': rbl_note},+ 'ports': {'ok': ports_ok, 'note': ports_note},+ 'critical_checks': ['ptr', 'port25', 'rbl'],+ }+ if os.name == 'nt':+ detail['dev_note'] = ('Host-dependent checks are skipped on this OS; '+ 'run preflight on the target server before sending.')++ result = {+ 'hostname': hostname,+ 'server_ip': server_ip,+ 'ptr_ok': bool(ptr_ok),+ 'ptr_value': ptr_value,+ 'port25_ok': bool(port25_ok),+ 'rbl_ok': bool(rbl_ok),+ 'rbl_hits': rbl_hits,+ 'ports_ok': bool(ports_ok),+ 'passed': passed,+ 'detail': detail,+ }+ cls._persist(result)+ # Return the freshly persisted row's dict (falls back to the raw result).+ latest = cls.latest()+ return latest or {**result, 'rbl_hits': rbl_hits, 'detail': detail}++ @classmethod+ def _persist(cls, result):+ """Store a PreflightResult row. Best-effort; never raises."""+ try:+ from app import db+ from .models import PreflightResult+ row = PreflightResult(+ hostname=result.get('hostname'),+ server_ip=result.get('server_ip'),+ ptr_ok=result.get('ptr_ok'),+ ptr_value=result.get('ptr_value'),+ port25_ok=result.get('port25_ok'),+ rbl_ok=result.get('rbl_ok'),+ rbl_hits=json.dumps(result.get('rbl_hits') or []),+ ports_ok=result.get('ports_ok'),+ passed=result.get('passed'),+ detail=json.dumps(result.get('detail') or {}),+ )+ db.session.add(row)+ db.session.commit()+ return row+ except Exception as e: # noqa: BLE001 — persistence is best-effort+ logger.warning('Preflight result could not be persisted: %s', e)+ try:+ from app import db+ db.session.rollback()+ except Exception:+ pass+ return None++ @classmethod+ def latest(cls):+ """Most recent PreflightResult as a dict, or None."""+ try:+ from .models import PreflightResult+ row = (PreflightResult.query+ .order_by(PreflightResult.checked_at.desc(),+ PreflightResult.id.desc())+ .first())+ return row.to_dict() if row else None+ except Exception as e: # noqa: BLE001+ logger.debug('Could not load latest preflight: %s', e)+ return Nonediff --git a/builtin-extensions/serverkit-mail/backend/stalwart_service.py b/builtin-extensions/serverkit-mail/backend/stalwart_service.pynew file mode 100644index 00000000..7436a7f2--- /dev/null+++ b/builtin-extensions/serverkit-mail/backend/stalwart_service.py@@ -0,0 +1,409 @@+"""Stalwart mail-server engine service (serverkit-mail extension).++Runs the Stalwart all-in-one mail server (SMTP/IMAP/JMAP/Sieve) in a managed+Docker container so a ServerKit box can host mailboxes for its domains. Driven+entirely through Stalwart's HTTP **admin API**, published on loopback only.++Design mirrors the serverkit-dns-server extension exactly:++* **Two choke-points** — every Docker invocation goes through :meth:`_docker`+ (privilege escalation, timeouts, error shaping) and every admin-API call goes+ through :meth:`_api` (HTTP Basic auth, JSON, error shaping). Nothing else+ shells out or talks HTTP.+* **Best-effort, Linux-only** — on Windows (dev) or when Docker is absent, calls+ return a clean error dict instead of raising.+* **Panel DB is the source of truth** — our tables describe what *should* exist;+ the thin reconcile methods (:meth:`upsert_account`, :meth:`upsert_domain`, …)+ push best-effort to Stalwart and **degrade gracefully**: a 404 / shape change+ in the version-sensitive admin API returns ``{success: False, error}`` and+ never raises, so :class:`MailService` can still record a row with+ ``sync_state='error'``.+* **Secrets in the config store** — the generated admin password lives in the+ plugin config store (``plugins_sdk.config`` + the ``_save_config`` pattern),+ used as HTTP Basic auth to the admin API.++Version note: the Stalwart admin API is version-sensitive. All endpoint paths are+centralized as module constants below and each reconcile call is wrapped so a+future API change degrades to a reported drift rather than a crash.+"""+import logging+import os+import secrets+import subprocess++import requests++from app.utils.system import run_privileged, is_command_available++logger = logging.getLogger(__name__)++SLUG = 'serverkit-mail'++# Official Stalwart all-in-one mail server image.+IMAGE = 'stalwartlabs/mail-server:latest'+CONTAINER_NAME = 'serverkit-mail'+DATA_DIR = '/var/serverkit/mail'+# Bind-mount target inside the container (Stalwart's data/config root).+CONTAINER_DATA_DIR = '/opt/stalwart-mail'++# Admin HTTP API — published on 127.0.0.1 only, never reachable off-host.+API_HOST = '127.0.0.1'+API_PORT = 8080+API_BASE = f'http://{API_HOST}:{API_PORT}/api'+API_TIMEOUT = 10+DOCKER_TIMEOUT = 180++# Default admin account Stalwart provisions on first start.+ADMIN_USER = 'admin'++# Mail ports published on the host (SMTP / submission / IMAP / Sieve).+MAIL_PORTS = ('25', '465', '587', '993', '143', '4190')++DOCS_URL = 'https://stalw.art/docs/'++# ── Admin-API endpoint paths (version-sensitive; centralized on purpose) ──+# Each reconcile method wraps these so a 404 / shape change degrades gracefully.+EP_PRINCIPAL = '/principal' # accounts / mailboxes / domains (CRUD)+EP_DKIM = '/dkim' # DKIM signature management+EP_QUEUE = '/queue/messages' # outbound queue introspection+EP_RECONFIG = '/reload' # ask Stalwart to reload config+++class StalwartService:+ """Stateless wrapper around Docker + the Stalwart admin HTTP API."""++ # ---------- config (plugin config store) ----------++ @classmethod+ def _config(cls):+ """Saved extension settings from the plugin config store."""+ from app.plugins_sdk import config as plugin_config+ return plugin_config(SLUG)++ @classmethod+ def _save_config(cls, updates):+ """Merge *updates* into the plugin's stored config.++ The SDK ``config()`` helper is read-only (the panel owns writes), so the+ generated admin password is persisted through the InstalledPlugin row+ directly. Returns False when the plugin row is absent (dev shells).+ """+ from app import db+ from app.models.plugin import InstalledPlugin+ row = InstalledPlugin.query.filter_by(slug=SLUG).first()+ if not row:+ logger.warning('%s: no InstalledPlugin row; config not persisted', SLUG)+ return False+ merged = dict(row.config or {})+ merged.update(updates)+ row.config = merged+ db.session.commit()+ return True++ # ---------- docker choke-point ----------++ @classmethod+ def _docker(cls, args, timeout=DOCKER_TIMEOUT):+ """Run ``docker <args>`` and return a normalized result dict."""+ if os.name == 'nt':+ return {'success': False,+ 'error': 'The mail server extension is not supported on Windows.'}+ if not is_command_available('docker'):+ return {'success': False, 'not_installed': True,+ 'error': 'Docker is not installed on this host.'}+ cmd = ['docker'] + list(args)+ try:+ result = run_privileged(cmd, timeout=timeout)+ except subprocess.TimeoutExpired:+ return {'success': False, 'error': f'docker timed out after {timeout}s'}+ except (OSError, subprocess.SubprocessError) as e:+ return {'success': False, 'error': f'Failed to run docker: {e}'}+ out = {+ 'success': result.returncode == 0,+ 'returncode': result.returncode,+ 'stdout': result.stdout or '',+ 'stderr': result.stderr or '',+ }+ if not out['success']:+ out['error'] = (out['stderr'] or out['stdout'] or 'docker failed').strip()+ return out++ # ---------- Stalwart admin-API choke-point ----------++ @classmethod+ def _api(cls, method, path, payload=None):+ """Call the container's Stalwart admin HTTP API (loopback only).++ Returns ``{'success': True, 'data': <json-or-None>}`` or an error dict.+ Auth is HTTP Basic with the generated admin password. The API is+ published on 127.0.0.1 exclusively, so this never leaves the host.+ Never raises.+ """+ if os.name == 'nt':+ return {'success': False,+ 'error': 'The mail server extension is not supported on Windows.'}+ password = cls._config().get('admin_password')+ if not password:+ return {'success': False,+ 'error': 'Stalwart admin password is not configured. Reinstall the mail server.'}+ try:+ resp = requests.request(+ method, API_BASE + path,+ auth=(ADMIN_USER, password),+ json=payload,+ timeout=API_TIMEOUT,+ )+ except requests.RequestException as e:+ return {'success': False,+ 'error': f'Stalwart admin API is unreachable: {e}'}+ if resp.status_code >= 400:+ try:+ body = resp.json()+ detail = body.get('error') or body.get('details') or resp.text+ except ValueError:+ detail = resp.text+ return {'success': False, 'status_code': resp.status_code,+ 'error': f'Stalwart admin API error ({resp.status_code}): {detail}'.strip()}+ if not resp.content:+ return {'success': True, 'data': None}+ try:+ return {'success': True, 'data': resp.json()}+ except ValueError:+ return {'success': True, 'data': resp.text}++ # ---------- container lifecycle ----------++ @classmethod+ def is_installed(cls):+ """True when the managed container exists (running or not)."""+ if os.name == 'nt':+ return False+ res = cls._docker(['inspect', '--format', '{{.State.Running}}',+ CONTAINER_NAME], timeout=20)+ return bool(res.get('success'))++ @classmethod+ def get_status(cls):+ """Installed / running / version / ports summary, best-effort."""+ status = {+ 'installed': False,+ 'running': False,+ 'version': None,+ 'engine': 'stalwart',+ 'image': IMAGE,+ 'container': CONTAINER_NAME,+ 'ports': list(MAIL_PORTS),+ 'admin_api': f'{API_HOST}:{API_PORT}',+ 'hostname': cls._config().get('hostname') if os.name != 'nt' else None,+ 'docs_url': DOCS_URL,+ }+ if os.name == 'nt':+ return status+ res = cls._docker(['inspect', '--format', '{{.State.Running}}',+ CONTAINER_NAME], timeout=20)+ if not res.get('success'):+ return status+ status['installed'] = True+ status['running'] = res.get('stdout', '').strip() == 'true'+ if status['running']:+ info = cls._api('GET', EP_RECONFIG)+ # Version is best-effort; a shape change must not break status.+ if info.get('success') and isinstance(info.get('data'), dict):+ status['version'] = info['data'].get('version')+ return status++ @classmethod+ def install(cls, hostname):+ """Create and start the Stalwart container.++ * Data + config bind-mounted at ``DATA_DIR`` (Stalwart bootstraps on+ first start).+ * Mail ports published on the host so the box can send/receive mail.+ * Admin HTTP API published on **127.0.0.1 only** with a generated+ password persisted to the plugin config store.+ """+ if os.name == 'nt':+ return {'success': False,+ 'error': 'The mail server extension is not supported on Windows.'}+ hostname = (hostname or '').strip().lower().rstrip('.')+ if not hostname:+ return {'success': False, 'error': 'A mail server hostname is required'}+ if cls.is_installed():+ return {'success': False,+ 'error': 'The mail server container already exists. Uninstall it first.'}++ dir_res = run_privileged(['mkdir', '-p', DATA_DIR])+ if getattr(dir_res, 'returncode', 1) != 0:+ return {'success': False,+ 'error': f'Could not create data directory {DATA_DIR}: '+ f'{(getattr(dir_res, "stderr", "") or "").strip()}'}++ admin_password = secrets.token_urlsafe(24)+ run_args = [+ 'run', '-d',+ '--name', CONTAINER_NAME,+ '--restart', 'unless-stopped',+ '--hostname', hostname,+ ]+ for port in MAIL_PORTS:+ run_args += ['-p', f'{port}:{port}']+ # Admin API bound to loopback on the host — never reachable off-box.+ run_args += ['-p', f'{API_HOST}:{API_PORT}:{API_PORT}']+ run_args += ['-v', f'{DATA_DIR}:{CONTAINER_DATA_DIR}']+ # Seed the fallback admin credentials Stalwart reads on first boot.+ run_args += [+ '-e', f'FALLBACK_ADMIN_USER={ADMIN_USER}',+ '-e', f'FALLBACK_ADMIN_SECRET={admin_password}',+ IMAGE,+ ]+ res = cls._docker(run_args)+ if not res.get('success'):+ return {'success': False,+ 'error': res.get('error', 'Failed to start the Stalwart container')}++ persisted = cls._save_config({+ 'admin_password': admin_password,+ 'hostname': hostname,+ })+ result = {'success': True,+ 'message': 'Stalwart mail server installed',+ 'container': CONTAINER_NAME,+ 'hostname': hostname}+ if not persisted:+ result['warning'] = ('Container started but the admin password could not '+ 'be persisted to the plugin config store.')+ return result++ @classmethod+ def uninstall(cls, keep_data=True):+ """Remove the container; optionally delete the mail data directory."""+ if os.name == 'nt':+ return {'success': False,+ 'error': 'The mail server extension is not supported on Windows.'}+ res = cls._docker(['rm', '-f', CONTAINER_NAME])+ if not res.get('success'):+ return {'success': False,+ 'error': res.get('error', 'Failed to remove the Stalwart container')}+ if not keep_data:+ rm = run_privileged(['rm', '-rf', DATA_DIR])+ if getattr(rm, 'returncode', 1) != 0:+ return {'success': True,+ 'warning': f'Container removed but mail data at {DATA_DIR} '+ f'could not be deleted: {(getattr(rm, "stderr", "") or "").strip()}'}+ cls._save_config({'admin_password': None})+ return {'success': True,+ 'message': 'Mail server removed'+ + ('' if keep_data else ' (mail data deleted)')}++ @classmethod+ def control(cls, action):+ """Start / stop / restart the managed container."""+ if action not in ('start', 'stop', 'restart'):+ return {'success': False, 'error': f'Invalid action: {action!r}'}+ if not cls.is_installed():+ return {'success': False, 'error': 'The mail server is not installed.'}+ res = cls._docker([action, CONTAINER_NAME], timeout=60)+ if not res.get('success'):+ return {'success': False, 'error': res.get('error', f'docker {action} failed')}+ return {'success': True, 'message': f'Mail server {action}ed', 'action': action}++ # ---------- thin reconcile methods (best-effort, never raise) ----------+ #+ # Each of these pushes the panel's intent to Stalwart via the version-+ # sensitive admin API and returns {success, ...}. On any error they report+ # {success: False, error} so MailService can flag the row's sync_state.++ @classmethod+ def _principal_payload(cls, ptype, name, **extra):+ payload = {'type': ptype, 'name': name}+ payload.update({k: v for k, v in extra.items() if v is not None})+ return payload++ @classmethod+ def upsert_account(cls, email, password=None, quota_mb=0, display_name=None):+ """Create/update a mailbox account principal on Stalwart. Best-effort."""+ if not cls.is_installed():+ return {'success': False, 'error': 'Mail server not installed', 'skipped': True}+ extra = {}+ if password:+ extra['secrets'] = [password]+ if display_name:+ extra['description'] = display_name+ if quota_mb:+ extra['quota'] = int(quota_mb) * 1024 * 1024 # bytes+ payload = cls._principal_payload('individual', email, **extra)+ res = cls._api('POST', EP_PRINCIPAL, payload)+ if res.get('success'):+ return {'success': True, 'email': email}+ return {'success': False, 'error': res.get('error', 'Stalwart account upsert failed')}++ @classmethod+ def delete_account(cls, email):+ """Delete a mailbox account principal on Stalwart. Best-effort."""+ if not cls.is_installed():+ return {'success': False, 'error': 'Mail server not installed', 'skipped': True}+ res = cls._api('DELETE', f'{EP_PRINCIPAL}/{email}')+ if res.get('success') or res.get('status_code') == 404:+ return {'success': True, 'email': email}+ return {'success': False, 'error': res.get('error', 'Stalwart account delete failed')}++ @classmethod+ def set_password(cls, email, password):+ """Set a mailbox account's password on Stalwart. Best-effort."""+ if not cls.is_installed():+ return {'success': False, 'error': 'Mail server not installed', 'skipped': True}+ if not password:+ return {'success': False, 'error': 'A password is required'}+ res = cls._api('PATCH', f'{EP_PRINCIPAL}/{email}', {'secrets': [password]})+ if res.get('success'):+ return {'success': True, 'email': email}+ # Fall back to a full upsert if PATCH is unsupported in this version.+ return cls.upsert_account(email, password=password)++ @classmethod+ def upsert_domain(cls, name):+ """Register a domain principal on Stalwart. Best-effort."""+ if not cls.is_installed():+ return {'success': False, 'error': 'Mail server not installed', 'skipped': True}+ payload = cls._principal_payload('domain', name)+ res = cls._api('POST', EP_PRINCIPAL, payload)+ if res.get('success'):+ return {'success': True, 'domain': name}+ return {'success': False, 'error': res.get('error', 'Stalwart domain upsert failed')}++ @classmethod+ def delete_domain(cls, name):+ """Remove a domain principal from Stalwart. Best-effort."""+ if not cls.is_installed():+ return {'success': False, 'error': 'Mail server not installed', 'skipped': True}+ res = cls._api('DELETE', f'{EP_PRINCIPAL}/{name}')+ if res.get('success') or res.get('status_code') == 404:+ return {'success': True, 'domain': name}+ return {'success': False, 'error': res.get('error', 'Stalwart domain delete failed')}++ @classmethod+ def list_queue(cls):+ """List outbound queue messages from the admin API. ``[]`` when down."""+ if not cls.is_installed():+ return {'success': True, 'messages': []}+ res = cls._api('GET', EP_QUEUE)+ if not res.get('success'):+ return {'success': True, 'messages': [], 'note': res.get('error')}+ data = res.get('data')+ if isinstance(data, list):+ messages = data+ elif isinstance(data, dict):+ messages = data.get('items', [])+ else:+ messages = []+ return {'success': True, 'messages': messages}++ @classmethod+ def flush_queue(cls):+ """Ask Stalwart to retry/flush the outbound queue. Best-effort."""+ if not cls.is_installed():+ return {'success': False, 'error': 'Mail server not installed', 'skipped': True}+ res = cls._api('PATCH', EP_QUEUE, {'action': 'retry'})+ if res.get('success'):+ return {'success': True, 'message': 'Queue flush requested'}+ return {'success': False, 'error': res.get('error', 'Queue flush failed')}diff --git a/builtin-extensions/serverkit-mail/plugin.json b/builtin-extensions/serverkit-mail/plugin.jsonnew file mode 100644index 00000000..e99b6271--- /dev/null+++ b/builtin-extensions/serverkit-mail/plugin.json@@ -0,0 +1,53 @@+{+ "name": "serverkit-mail",+ "display_name": "Mail Server",+ "version": "1.0.0",+ "description": "Self-hosted mail server powered by Stalwart in a managed Docker container — domains, mailboxes, forwarders, and autoresponders, with automatic DKIM/SPF/DMARC/MX record deployment, a deliverability preflight (PTR, port-25 egress, RBL) that gates outbound sending, brute-force jails, and maildir backups. Most panels never run a mail server, so it ships as an opt-in extension.",+ "author": "ServerKit",+ "license": "MIT",+ "category": "integration",+ "homepage": "https://github.com/jhd3197/ServerKit",+ "permissions": ["shell", "filesystem", "network", "docker"],+ "min_panel_version": "1.7.0",+ "entry_point": "mail:mail_bp",+ "url_prefix": "/api/v1/mail",+ "models": "models:register",+ "lifecycle": {+ "on_install": "lifecycle:on_install",+ "on_uninstall": "lifecycle:on_uninstall"+ },+ "jobs": [+ { "kind": "mail.preflight.run", "handler": "jobs:run_preflight" },+ { "kind": "mail.queue.flush", "handler": "jobs:flush_queue" }+ ],+ "schedules": [+ { "name": "mail-preflight-daily", "kind": "mail.preflight.run", "cron": "0 6 * * *" }+ ],+ "icon": "<rect x=\"2\" y=\"4\" width=\"20\" height=\"16\" rx=\"2\"/><path d=\"m22 7-8.97 5.7a1.94 1.94 0 0 1-2.06 0L2 7\"/>",+ "contributions": {+ "nav": [+ {+ "id": "mail",+ "label": "Mail Server",+ "route": "/mail",+ "category": "operations",+ "icon": "<rect x=\"2\" y=\"4\" width=\"20\" height=\"16\" rx=\"2\"/><path d=\"m22 7-8.97 5.7a1.94 1.94 0 0 1-2.06 0L2 7\"/>"+ }+ ],+ "routes": [+ { "path": "mail", "component": "MailPage" },+ { "path": "mail/:tab", "component": "MailPage" }+ ],+ "page_titles": {+ "/mail": "Mail Server"+ },+ "command_palette": [+ {+ "label": "Mail Server",+ "path": "/mail",+ "category": "Pages",+ "keywords": "mail smtp imap stalwart mailbox domain dkim spf dmarc mx deliverability forwarder autoresponder queue"+ }+ ]+ }+}