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
test(mail): proving suite for serverkit-mail + changelog
Juan Denisd99d4db6a9f4
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 808887ee..72591852 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -28,6 +28,20 @@ awaiting a stable release:### Added+- **Mail Server extension (`serverkit-mail`)** — an opt-in built-in that runs a+ self-hosted mail server (Stalwart, in a managed Docker container) driven+ through its HTTP admin API. Manages mail domains, mailboxes, forwarders,+ autoresponders and catch-all; generates DKIM keys and deploys DKIM/SPF/DMARC/MX/A+ records through the existing DNS-provider integrations; requests a Let's Encrypt+ cert for the mail hostname; and shows the outbound queue. A **deliverability+ preflight** (reverse-DNS/PTR match, port-25 egress, RBL listing, listening+ ports) runs on a daily schedule and **blocks outbound sending until it passes**+ (an explicit force override is audit-logged), because self-hosted mail on a VPS+ is a real commitment — many providers block port 25 and a fresh IP can be+ pre-burned. Ships brute-force auth jails and registers the mail store for+ scheduled backups. Not installed by default; enable it from Marketplace. It runs+ alongside the older Postfix/Dovecot `serverkit-email` extension with entirely+ separate identifiers.- **Configuration drift detection + repair ("doctor")** — a daily read-onlysweep re-renders the expected nginx vhost and compose override for everymanaged resource from panel state and diffs it against disk; drift raises andiff --git a/backend/tests/test_serverkit_mail_extension.py b/backend/tests/test_serverkit_mail_extension.pynew file mode 100644index 00000000..6399f25b--- /dev/null+++ b/backend/tests/test_serverkit_mail_extension.py@@ -0,0 +1,688 @@+"""serverkit-mail extension tests — manifest, models, engine, blueprint.++Covers the Stalwart-based builtin mail extension the same way production loads a+builtin: ``plugin_service._ensure_builtin_backend_importable`` registers+``builtin-extensions/serverkit-mail/backend`` as the dashed package+``app.plugins.serverkit-mail``. The models module is imported at test-module top+level so its ``ext_serverkit_mail_*`` tables register on ``db.metadata`` before+the ``app`` fixture runs ``db.create_all()``.++This file proves: manifest validity + permissions + entry point + frontend+export, the SQLAlchemy models (create + ``to_dict`` + no mailbox password column ++the unique constraint), the StalwartService Docker/API choke-points (install argv+with a loopback-only admin API, status parsing, Windows gating, clean API error+dicts, best-effort reconcile methods), and the blueprint auth/validation paths.++Preflight, the activation gate, DKIM/DNS, and the fail2ban jail live in+``test_serverkit_mail_preflight_dns.py``.+"""+import importlib+import json+import os+from types import SimpleNamespace++import pytest++from app.services import plugin_service++SLUG = 'serverkit-mail'+EXT_DIR = os.path.join(+ os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))),+ 'builtin-extensions', SLUG,+)+++def _load_ext():+ assert plugin_service._ensure_builtin_backend_importable(SLUG), (+ f'builtin extension backend not importable from {EXT_DIR}')+ # Import models at module top so the ext_serverkit_mail_* tables register on+ # db.metadata before any app fixture calls db.create_all().+ models = importlib.import_module(f'app.plugins.{SLUG}.models')+ stalwart = importlib.import_module(f'app.plugins.{SLUG}.stalwart_service')+ bp = importlib.import_module(f'app.plugins.{SLUG}.mail')+ return models, stalwart, bp+++models_mod, svc_mod, bp_mod = _load_ext()+StalwartService = svc_mod.StalwartService+MailDomain = models_mod.MailDomain+Mailbox = models_mod.Mailbox+Forwarder = models_mod.Forwarder+Autoresponder = models_mod.Autoresponder+PreflightResult = models_mod.PreflightResult++CFG = {'admin_password': 'test-admin-pw', 'hostname': 'mail.example.com'}+++def _proc(returncode=0, stdout='', stderr=''):+ return SimpleNamespace(returncode=returncode, stdout=stdout, stderr=stderr)+++class FakeResponse:+ def __init__(self, status_code=200, data=None, text=''):+ self.status_code = status_code+ self._data = data+ self.text = text or (json.dumps(data) if data is not None else '')+ self.content = self.text.encode()++ def json(self):+ if self._data is None:+ raise ValueError('no json')+ return self._data+++def linux(monkeypatch):+ """Pretend we're on Linux with docker installed and admin creds saved."""+ monkeypatch.setattr(svc_mod.os, 'name', 'posix')+ monkeypatch.setattr(svc_mod, 'is_command_available', lambda c: True)+ monkeypatch.setattr(StalwartService, '_config', classmethod(lambda cls: dict(CFG)))+++# ---------------------------------------------------------------------------+# manifest+# ---------------------------------------------------------------------------++def test_manifest_passes_validator():+ with open(os.path.join(EXT_DIR, 'plugin.json'), encoding='utf-8') as f:+ manifest = json.load(f)+ assert plugin_service._validate_manifest(manifest) is True+ assert manifest['name'] == SLUG+ assert manifest['category'] == 'integration'+ assert manifest['entry_point'] == 'mail:mail_bp'+ assert manifest['url_prefix'] == '/api/v1/mail'+ assert manifest['models'] == 'models:register'+ assert set(manifest['permissions']) == {'shell', 'filesystem', 'network', 'docker'}+ nav = manifest['contributions']['nav'][0]+ assert nav['route'] == '/mail'+ assert nav['id'] == 'mail'+ routes = manifest['contributions']['routes']+ assert {'path': 'mail', 'component': 'MailPage'} in routes+ assert manifest['contributions']['page_titles']['/mail'] == 'Mail Server'+++def test_manifest_permissions_are_known():+ from app.plugins_sdk import permissions as sdk_perms+ with open(os.path.join(EXT_DIR, 'plugin.json'), encoding='utf-8') as f:+ manifest = json.load(f)+ assert sdk_perms.unknown_permissions(manifest['permissions']) == []+++def test_lifecycle_hook_keys_match_loader():+ """The loader reads lifecycle.get('install')/('uninstall') — the manifest must+ use those exact keys (not 'on_install'/'on_uninstall'), else the hooks that+ register notify events and tear down the container silently never fire. The+ _validate_manifest check only vets the VALUES, so this guards the KEYS and+ proves each referenced hook actually resolves + is importable."""+ import importlib+ with open(os.path.join(EXT_DIR, 'plugin.json'), encoding='utf-8') as f:+ lifecycle = json.load(f)['lifecycle']+ assert set(lifecycle) <= {'install', 'upgrade', 'uninstall'}+ assert 'install' in lifecycle and 'uninstall' in lifecycle+ for ref in lifecycle.values():+ module_name, func_name = ref.split(':')+ mod = importlib.import_module(f'app.plugins.{SLUG}.{module_name}')+ assert callable(getattr(mod, func_name, None)), ref+++def test_manifest_jobs_and_schedule_resolve():+ """Job handlers + the daily preflight schedule are wired to real callables."""+ import importlib+ with open(os.path.join(EXT_DIR, 'plugin.json'), encoding='utf-8') as f:+ manifest = json.load(f)+ kinds = {j['kind'] for j in manifest['jobs']}+ assert 'mail.preflight.run' in kinds+ for job in manifest['jobs']:+ module_name, func_name = job['handler'].split(':')+ mod = importlib.import_module(f'app.plugins.{SLUG}.{module_name}')+ assert callable(getattr(mod, func_name, None)), job['handler']+ sched = manifest['schedules'][0]+ assert sched['kind'] in kinds and sched.get('cron')+++def test_entry_point_resolves_to_blueprint():+ assert getattr(bp_mod, 'mail_bp', None) is not None+ assert bp_mod.mail_bp.name == 'mail'+++def test_models_register_is_a_noop_passthrough():+ # Manifest declares models: "models:register"; the callable must exist and be+ # a harmless passthrough (tables register as an import side effect).+ from app import db+ assert models_mod.register(db) is None+++def test_frontend_exports_route_component():+ index = os.path.join(EXT_DIR, 'frontend', 'index.jsx')+ if not os.path.isfile(index):+ pytest.skip('serverkit-mail frontend/index.jsx not present in this build')+ with open(index, encoding='utf-8') as f:+ src = f.read()+ assert 'export { default as MailPage }' in src+ # No module-level default export: PluginLoader legacy-auto-renders those.+ assert 'export default' not in src+++# ---------------------------------------------------------------------------+# models+# ---------------------------------------------------------------------------++def test_mail_domain_persists_and_to_dict(app):+ from app import db+ row = MailDomain(name='example.com', catch_all_target='[email protected]',+ is_active=False, sync_state='pending')+ db.session.add(row)+ db.session.commit()++ d = row.to_dict()+ for key in ('id', 'name', 'is_active', 'catch_all_target', 'dkim_selector',+ 'dkim_public_key', 'dkim_configured', 'dns_deployed',+ 'dns_last_result', 'sync_state', 'sync_error', 'mailboxes_count',+ 'forwarders_count', 'created_at', 'updated_at'):+ assert key in d, key+ assert d['name'] == 'example.com'+ assert d['is_active'] is False+ assert d['dkim_selector'] == 'serverkit' # column default+ assert d['dkim_configured'] is False+ assert d['mailboxes_count'] == 0+++def test_mailbox_has_no_password_and_to_dict(app):+ from app import db+ domain = MailDomain(name='mailbox-test.com')+ db.session.add(domain)+ db.session.commit()++ box = Mailbox(domain_id=domain.id, local_part='alice', quota_mb=512,+ display_name='Alice')+ db.session.add(box)+ db.session.commit()++ # Passwords are NEVER persisted panel-side.+ assert not hasattr(box, 'password')+ assert 'password' not in Mailbox.__table__.columns+ assert 'password_hash' not in Mailbox.__table__.columns++ d = box.to_dict()+ assert 'password' not in d+ assert d['local_part'] == 'alice'+ assert d['email'] == '[email protected]'+ assert d['quota_mb'] == 512+ assert d['domain_name'] == 'mailbox-test.com'+++def test_mailbox_unique_domain_local_part(app):+ from app import db+ from sqlalchemy.exc import IntegrityError+ domain = MailDomain(name='dupe.com')+ db.session.add(domain)+ db.session.commit()++ db.session.add(Mailbox(domain_id=domain.id, local_part='postmaster'))+ db.session.commit()++ db.session.add(Mailbox(domain_id=domain.id, local_part='postmaster'))+ with pytest.raises(IntegrityError):+ db.session.commit()+ db.session.rollback()+++def test_forwarder_and_autoresponder_persist(app):+ from app import db+ domain = MailDomain(name='fwd.com')+ db.session.add(domain)+ db.session.commit()++ fwd = Forwarder(domain_id=domain.id, source_local_part='sales',+ destination='[email protected]', keep_copy=True)+ db.session.add(fwd)+ db.session.commit()+ fd = fwd.to_dict()+ assert fd['source'] == '[email protected]'+ assert fd['destination'] == '[email protected]'+ assert fd['keep_copy'] is True++ box = Mailbox(domain_id=domain.id, local_part='bob')+ db.session.add(box)+ db.session.commit()+ ar = Autoresponder(mailbox_id=box.id, enabled=True, subject='OOO', body='Away')+ db.session.add(ar)+ db.session.commit()+ ad = ar.to_dict()+ assert ad['mailbox_id'] == box.id+ assert ad['enabled'] is True+ assert ad['subject'] == 'OOO'+++def test_preflight_result_persist_and_to_dict(app):+ from app import db+ row = PreflightResult(hostname='mail.example.com', server_ip='203.0.113.5',+ ptr_ok=True, ptr_value='mail.example.com',+ port25_ok=True, rbl_ok=True,+ rbl_hits=json.dumps([]), ports_ok=True, passed=True,+ detail=json.dumps({'ptr': {'ok': True}}))+ db.session.add(row)+ db.session.commit()+ d = row.to_dict()+ for key in ('id', 'hostname', 'server_ip', 'ptr_ok', 'ptr_value', 'port25_ok',+ 'rbl_ok', 'rbl_hits', 'ports_ok', 'passed', 'detail', 'checked_at'):+ assert key in d, key+ assert d['passed'] is True+ assert d['rbl_hits'] == [] # JSON text decoded back to a list+ assert d['detail'] == {'ptr': {'ok': True}}+++# ---------------------------------------------------------------------------+# StalwartService: install / lifecycle argv+# ---------------------------------------------------------------------------++def test_install_builds_correct_docker_run(monkeypatch, linux):+ calls = []+ saved = {}++ def fake_run(cmd, timeout=None, **kwargs):+ calls.append(list(cmd))+ if cmd[:2] == ['docker', 'inspect']:+ return _proc(returncode=1, stderr='No such object') # not installed+ return _proc(returncode=0, stdout='container123\n')++ monkeypatch.setattr(svc_mod, 'run_privileged', fake_run)+ monkeypatch.setattr(StalwartService, '_save_config',+ classmethod(lambda cls, updates: saved.update(updates) or True))++ result = StalwartService.install('Mail.Example.COM.')+ assert result['success'] is True, result++ # Data dir created, container started.+ assert ['mkdir', '-p', svc_mod.DATA_DIR] in calls+ run_cmd = next(c for c in calls if c[:2] == ['docker', 'run'])++ # Mail ports published on the host.+ for port in ('25', '465', '587', '993'):+ assert f'{port}:{port}' in run_cmd, port++ # Admin API published on loopback ONLY — never a bare 8080:8080.+ assert f'{svc_mod.API_HOST}:{svc_mod.API_PORT}:{svc_mod.API_PORT}' in run_cmd+ assert '127.0.0.1:8080:8080' in run_cmd+ assert not any(a == '8080:8080' for a in run_cmd)++ # Official image, restart policy, data volume.+ assert svc_mod.IMAGE in run_cmd+ assert '--restart' in run_cmd+ assert f'{svc_mod.DATA_DIR}:{svc_mod.CONTAINER_DATA_DIR}' in run_cmd++ # A generated admin password was seeded into the container AND persisted.+ secret_args = [a for a in run_cmd if a.startswith('FALLBACK_ADMIN_SECRET=')]+ assert len(secret_args) == 1+ generated = secret_args[0].split('=', 1)[1]+ assert generated # non-empty generated secret+ assert saved['admin_password'] == generated+ assert saved['hostname'] == 'mail.example.com' # normalized (lowercased, no dot)+++def test_install_requires_hostname(monkeypatch, linux):+ monkeypatch.setattr(+ svc_mod, 'run_privileged',+ lambda *a, **kw: pytest.fail('docker must not run on invalid input'))+ assert StalwartService.install('')['success'] is False+ assert StalwartService.install(' ')['success'] is False+++def test_install_refuses_when_container_exists(monkeypatch, linux):+ monkeypatch.setattr(+ svc_mod, 'run_privileged',+ lambda cmd, timeout=None, **kw: _proc(returncode=0, stdout='true\n'))+ result = StalwartService.install('mail.example.com')+ assert result['success'] is False+ assert 'already exists' in result['error']+++def test_uninstall_keep_data_vs_purge(monkeypatch, linux):+ calls = []++ def fake_run(cmd, timeout=None, **kwargs):+ calls.append(list(cmd))+ return _proc(returncode=0)++ monkeypatch.setattr(svc_mod, 'run_privileged', fake_run)+ monkeypatch.setattr(StalwartService, '_save_config',+ classmethod(lambda cls, updates: True))++ result = StalwartService.uninstall(keep_data=True)+ assert result['success'] is True+ assert ['docker', 'rm', '-f', svc_mod.CONTAINER_NAME] in calls+ assert not any(c[:1] == ['rm'] for c in calls) # data dir untouched++ calls.clear()+ result = StalwartService.uninstall(keep_data=False)+ assert result['success'] is True+ assert ['rm', '-rf', svc_mod.DATA_DIR] in calls+++def test_windows_is_unsupported(monkeypatch):+ monkeypatch.setattr(svc_mod.os, 'name', 'nt')+ assert StalwartService.is_installed() is False+ result = StalwartService.install('mail.example.com')+ assert result['success'] is False+ assert 'Windows' in result['error']+ status = StalwartService.get_status()+ assert status['installed'] is False+ assert status['running'] is False+ # _api short-circuits on Windows without touching the network.+ api = StalwartService._api('GET', '/principal')+ assert api['success'] is False+ assert 'Windows' in api['error']+++# ---------------------------------------------------------------------------+# StalwartService: status + admin API choke-point+# ---------------------------------------------------------------------------++def test_status_running_reads_version(monkeypatch, linux):+ monkeypatch.setattr(+ svc_mod, 'run_privileged',+ lambda cmd, timeout=None, **kw: _proc(returncode=0, stdout='true\n'))+ monkeypatch.setattr(+ svc_mod.requests, 'request',+ lambda method, url, **kw: FakeResponse(200, {'version': '0.11.1'}))+ status = StalwartService.get_status()+ assert status['installed'] is True+ assert status['running'] is True+ assert status['version'] == '0.11.1'+ assert status['engine'] == 'stalwart'+ assert status['admin_api'] == f'{svc_mod.API_HOST}:{svc_mod.API_PORT}'+++def test_status_not_installed(monkeypatch, linux):+ monkeypatch.setattr(+ svc_mod, 'run_privileged',+ lambda cmd, timeout=None, **kw: _proc(returncode=1, stderr='No such object'))+ status = StalwartService.get_status()+ assert status['installed'] is False+ assert status['running'] is False+++def test_api_uses_basic_auth_and_returns_data(monkeypatch, linux):+ seen = {}++ def fake_request(method, url, auth=None, json=None, timeout=None):+ seen.update(method=method, url=url, auth=auth, json=json)+ return FakeResponse(200, {'ok': True})++ monkeypatch.setattr(svc_mod.requests, 'request', fake_request)+ res = StalwartService._api('POST', '/principal', {'name': '[email protected]'})+ assert res['success'] is True+ assert res['data'] == {'ok': True}+ assert seen['method'] == 'POST'+ assert seen['url'] == svc_mod.API_BASE + '/principal'+ assert seen['auth'] == (svc_mod.ADMIN_USER, CFG['admin_password'])+++def test_api_error_status_is_clean(monkeypatch, linux):+ monkeypatch.setattr(+ svc_mod.requests, 'request',+ lambda *a, **kw: FakeResponse(422, {'error': 'principal exists'}))+ res = StalwartService._api('POST', '/principal', {})+ assert res['success'] is False+ assert res['status_code'] == 422+ assert 'principal exists' in res['error']+++def test_api_unreachable_is_clean(monkeypatch, linux):+ def boom(*a, **kw):+ raise svc_mod.requests.RequestException('connection refused')+ monkeypatch.setattr(svc_mod.requests, 'request', boom)+ res = StalwartService._api('GET', '/principal')+ assert res['success'] is False+ assert 'unreachable' in res['error']+++def test_api_requires_admin_password(monkeypatch, linux):+ monkeypatch.setattr(StalwartService, '_config', classmethod(lambda cls: {}))+ monkeypatch.setattr(+ svc_mod.requests, 'request',+ lambda *a, **kw: pytest.fail('API must not be called without a password'))+ res = StalwartService._api('GET', '/principal')+ assert res['success'] is False+ assert 'password is not configured' in res['error']+++# ---------------------------------------------------------------------------+# StalwartService: best-effort reconcile methods (never raise)+# ---------------------------------------------------------------------------++def test_reconcile_methods_skip_when_not_installed(monkeypatch, linux):+ monkeypatch.setattr(StalwartService, 'is_installed', classmethod(lambda cls: False))+ monkeypatch.setattr(+ svc_mod.requests, 'request',+ lambda *a, **kw: pytest.fail('no API call when engine is absent'))+ for res in (StalwartService.upsert_account('[email protected]', password='x'),+ StalwartService.upsert_domain('b.co'),+ StalwartService.delete_account('[email protected]'),+ StalwartService.set_password('[email protected]', 'x'),+ StalwartService.flush_queue()):+ assert res['success'] is False+ assert res.get('skipped') is True+ # Queue introspection degrades to an empty list, not an error.+ q = StalwartService.list_queue()+ assert q == {'success': True, 'messages': []}+++def test_reconcile_upsert_account_success_and_error(monkeypatch, linux):+ monkeypatch.setattr(StalwartService, 'is_installed', classmethod(lambda cls: True))++ calls = []++ def ok_api(cls, method, path, payload=None):+ calls.append((method, path, payload))+ return {'success': True, 'data': None}+ monkeypatch.setattr(StalwartService, '_api', classmethod(ok_api))+ res = StalwartService.upsert_account('[email protected]', password='pw',+ quota_mb=100, display_name='Alice')+ assert res == {'success': True, 'email': '[email protected]'}+ method, path, payload = calls[0]+ assert method == 'POST'+ assert path == svc_mod.EP_PRINCIPAL+ assert payload['type'] == 'individual'+ assert payload['name'] == '[email protected]'+ assert payload['secrets'] == ['pw']+ assert payload['quota'] == 100 * 1024 * 1024++ monkeypatch.setattr(+ StalwartService, '_api',+ classmethod(lambda cls, m, p, payload=None: {'success': False, 'error': 'boom'}))+ res = StalwartService.upsert_account('[email protected]')+ assert res['success'] is False+ assert 'boom' in res['error']+++def test_list_queue_shapes(monkeypatch, linux):+ monkeypatch.setattr(StalwartService, 'is_installed', classmethod(lambda cls: True))+ monkeypatch.setattr(+ StalwartService, '_api',+ classmethod(lambda cls, m, p, payload=None: {'success': True,+ 'data': [{'id': 1}, {'id': 2}]}))+ res = StalwartService.list_queue()+ assert res['success'] is True+ assert res['messages'] == [{'id': 1}, {'id': 2}]++ # A dict payload with items is unwrapped; an API failure degrades to [].+ monkeypatch.setattr(+ StalwartService, '_api',+ classmethod(lambda cls, m, p, payload=None: {'success': True,+ 'data': {'items': [{'id': 9}]}}))+ assert StalwartService.list_queue()['messages'] == [{'id': 9}]+ monkeypatch.setattr(+ StalwartService, '_api',+ classmethod(lambda cls, m, p, payload=None: {'success': False, 'error': 'down'}))+ res = StalwartService.list_queue()+ assert res['messages'] == []+ assert res['note'] == 'down'+++# ---------------------------------------------------------------------------+# blueprint routes+# ---------------------------------------------------------------------------++def mail_app(app):+ """Register the extension blueprint on the test app (name-guarded)."""+ if 'mail' not in app.blueprints:+ app.register_blueprint(bp_mod.mail_bp, url_prefix='/api/v1/mail')+ return app+++def mail_client(mail_app):+ return mail_app.test_client()+++def test_routes_require_auth(mail_client):+ assert mail_client.get('/api/v1/mail/status').status_code == 401+ assert mail_client.post('/api/v1/mail/install', json={}).status_code == 401+ assert mail_client.get('/api/v1/mail/domains').status_code == 401+ assert mail_client.post('/api/v1/mail/domains', json={}).status_code == 401+ assert mail_client.get('/api/v1/mail/queue').status_code == 401+++def test_status_route(mail_client, auth_headers, monkeypatch):+ monkeypatch.setattr(+ bp_mod.MailService, 'get_status',+ classmethod(lambda cls: {+ 'installed': True, 'running': True, 'version': '0.11',+ 'engine': 'stalwart', 'preflight': None, 'domains_count': 0,+ 'docs_url': svc_mod.DOCS_URL,+ }))+ resp = mail_client.get('/api/v1/mail/status', headers=auth_headers)+ assert resp.status_code == 200+ data = resp.get_json()+ assert data['installed'] is True+ assert data['engine'] == 'stalwart'+++def test_preflight_get_route(mail_client, auth_headers, monkeypatch):+ monkeypatch.setattr(+ bp_mod.PreflightService, 'latest',+ classmethod(lambda cls: {'passed': True, 'hostname': 'mail.example.com'}))+ resp = mail_client.get('/api/v1/mail/preflight', headers=auth_headers)+ assert resp.status_code == 200+ assert resp.get_json()['preflight']['passed'] is True+++def test_preflight_post_route(mail_client, auth_headers, monkeypatch):+ captured = {}++ def fake_run(cls, hostname, server_ip=None):+ captured.update(hostname=hostname, server_ip=server_ip)+ return {'passed': False, 'hostname': hostname}+ monkeypatch.setattr(bp_mod.PreflightService, 'run', classmethod(fake_run))+ resp = mail_client.post('/api/v1/mail/preflight',+ json={'hostname': 'mail.example.com', 'server_ip': '1.2.3.4'},+ headers=auth_headers)+ assert resp.status_code == 200+ assert captured['hostname'] == 'mail.example.com'+ assert captured['server_ip'] == '1.2.3.4'++ # hostname is required.+ resp = mail_client.post('/api/v1/mail/preflight', json={}, headers=auth_headers)+ assert resp.status_code == 400+ assert 'error' in resp.get_json()+++def test_install_route(mail_client, auth_headers, monkeypatch):+ captured = {}++ def fake_install(cls, hostname):+ captured['hostname'] = hostname+ return {'success': True, 'message': 'ok', 'container': svc_mod.CONTAINER_NAME}+ monkeypatch.setattr(bp_mod.StalwartService, 'install', classmethod(fake_install))+ resp = mail_client.post('/api/v1/mail/install',+ json={'hostname': 'mail.example.com'}, headers=auth_headers)+ assert resp.status_code == 201+ assert captured['hostname'] == 'mail.example.com'++ resp = mail_client.post('/api/v1/mail/install', json={}, headers=auth_headers)+ assert resp.status_code == 400+ assert 'error' in resp.get_json()+++def test_domains_routes_happy_path(mail_client, auth_headers, monkeypatch):+ monkeypatch.setattr(+ bp_mod.MailService, 'list_domains',+ classmethod(lambda cls: [{'id': 1, 'name': 'example.com'}]))+ resp = mail_client.get('/api/v1/mail/domains', headers=auth_headers)+ assert resp.status_code == 200+ assert resp.get_json()['domains'][0]['name'] == 'example.com'++ captured = {}++ def fake_add(cls, name, catch_all_target=None):+ captured.update(name=name, catch_all_target=catch_all_target)+ return {'success': True, 'domain': {'id': 1, 'name': name}}+ monkeypatch.setattr(bp_mod.MailService, 'add_domain', classmethod(fake_add))+ resp = mail_client.post('/api/v1/mail/domains',+ json={'name': 'example.com', 'catch_all_target': '[email protected]'},+ headers=auth_headers)+ assert resp.status_code == 201+ assert captured == {'name': 'example.com', 'catch_all_target': '[email protected]'}++ # name is required.+ resp = mail_client.post('/api/v1/mail/domains', json={}, headers=auth_headers)+ assert resp.status_code == 400+ assert 'error' in resp.get_json()+++def test_add_domain_service_error_is_400(mail_client, auth_headers, monkeypatch):+ monkeypatch.setattr(+ bp_mod.MailService, 'add_domain',+ classmethod(lambda cls, name, catch_all_target=None: {+ 'success': False, 'error': 'Domain example.com already exists'}))+ resp = mail_client.post('/api/v1/mail/domains',+ json={'name': 'example.com'}, headers=auth_headers)+ assert resp.status_code == 400+ assert 'already exists' in resp.get_json()['error']+++def test_mailbox_create_validation(mail_client, auth_headers, monkeypatch):+ captured = {}++ def fake_add(cls, domain_id, local_part, password, quota_mb=0, display_name=None):+ captured.update(domain_id=domain_id, local_part=local_part, password=password)+ return {'success': True, 'mailbox': {'id': 1, 'local_part': local_part}}+ monkeypatch.setattr(bp_mod.MailService, 'add_mailbox', classmethod(fake_add))++ # Missing password -> 400 before the service runs.+ resp = mail_client.post('/api/v1/mail/domains/1/mailboxes',+ json={'local_part': 'alice'}, headers=auth_headers)+ assert resp.status_code == 400+ assert captured == {}++ # Missing local_part -> 400.+ resp = mail_client.post('/api/v1/mail/domains/1/mailboxes',+ json={'password': 'x'}, headers=auth_headers)+ assert resp.status_code == 400++ # Happy path -> 201, password forwarded to the service (never persisted).+ resp = mail_client.post('/api/v1/mail/domains/1/mailboxes',+ json={'local_part': 'alice', 'password': 's3cret'},+ headers=auth_headers)+ assert resp.status_code == 201+ assert captured['local_part'] == 'alice'+ assert captured['password'] == 's3cret'+++def test_queue_route_503_when_not_installed(mail_client, auth_headers, monkeypatch):+ monkeypatch.setattr(bp_mod.StalwartService, 'is_installed', classmethod(lambda cls: False))+ resp = mail_client.get('/api/v1/mail/queue', headers=auth_headers)+ assert resp.status_code == 503+ assert 'error' in resp.get_json()+++def test_queue_route_ok_when_installed(mail_client, auth_headers, monkeypatch):+ monkeypatch.setattr(bp_mod.StalwartService, 'is_installed', classmethod(lambda cls: True))+ monkeypatch.setattr(+ bp_mod.StalwartService, 'list_queue',+ classmethod(lambda cls: {'success': True, 'messages': [{'id': 1}]}))+ resp = mail_client.get('/api/v1/mail/queue', headers=auth_headers)+ assert resp.status_code == 200+ assert resp.get_json()['messages'] == [{'id': 1}]diff --git a/backend/tests/test_serverkit_mail_preflight_dns.py b/backend/tests/test_serverkit_mail_preflight_dns.pynew file mode 100644index 00000000..88d5b8bb--- /dev/null+++ b/backend/tests/test_serverkit_mail_preflight_dns.py@@ -0,0 +1,396 @@+"""serverkit-mail extension tests — preflight, activation gate, DKIM/DNS, jail.++Loads the builtin backend exactly like production+(``plugin_service._ensure_builtin_backend_importable`` -> dashed package+``app.plugins.serverkit-mail``) and imports the models module at test-module top+level so its tables register before the ``app`` fixture's ``db.create_all()``.++Proves the safety-critical behaviors:++* PreflightService: all-pass -> ``passed`` + a persisted row; an RBL hit or a+ blocked port 25 -> ``passed=False`` with the failing check surfaced;+ Windows/dev -> skipped and never raises; ``latest()`` returns the newest row.+* The activation gate: ``MailService.set_domain_active(id, True)`` is REFUSED+ without a passing preflight and ALLOWED with ``force=True`` (audit path).+* DkimDnsService: DKIM keygen -> a ``v=DKIM1; k=rsa; p=...`` TXT value + stored+ keys; the pure ``build_records`` shapes; ``deploy_dns`` calls+ ``DNSProviderService.set_record`` with the exact record types/names/values and+ ``source='mail'``, and the no-provider path returns manual instructions.+* MailJailService: unavailable on Windows; enable writes a ``serverkit-mail-*``+ jail via a stubbed ``run_privileged(['tee', ...])`` and never raises.+"""+import importlib+import json+import os+from types import SimpleNamespace++import pytest++from app.services import plugin_service++SLUG = 'serverkit-mail'+EXT_DIR = os.path.join(+ os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))),+ 'builtin-extensions', SLUG,+)+++def _load_ext():+ assert plugin_service._ensure_builtin_backend_importable(SLUG), (+ f'builtin extension backend not importable from {EXT_DIR}')+ models = importlib.import_module(f'app.plugins.{SLUG}.models')+ preflight = importlib.import_module(f'app.plugins.{SLUG}.preflight_service')+ dns = importlib.import_module(f'app.plugins.{SLUG}.dns_mail_service')+ mailsvc = importlib.import_module(f'app.plugins.{SLUG}.mail_service')+ jail = importlib.import_module(f'app.plugins.{SLUG}.mail_jail_service')+ return models, preflight, dns, mailsvc, jail+++models_mod, preflight_mod, dns_mod, mailsvc_mod, jail_mod = _load_ext()+PreflightService = preflight_mod.PreflightService+DkimDnsService = dns_mod.DkimDnsService+MailService = mailsvc_mod.MailService+MailJailService = jail_mod.MailJailService+MailDomain = models_mod.MailDomain+PreflightResult = models_mod.PreflightResult+++def _proc(returncode=0, stdout='', stderr=''):+ return SimpleNamespace(returncode=returncode, stdout=stdout, stderr=stderr)+++def _patch_checks(monkeypatch, *, ptr=(True, 'mail.example.com', None),+ port25=(True, None), rbl=(True, [], None), ports=(True, None)):+ """Stub every individual preflight helper so run() is hermetic."""+ monkeypatch.setattr(PreflightService, '_check_ptr',+ staticmethod(lambda hostname, server_ip: ptr))+ monkeypatch.setattr(PreflightService, '_check_port25',+ staticmethod(lambda: port25))+ monkeypatch.setattr(PreflightService, '_check_rbl',+ classmethod(lambda cls, server_ip: rbl))+ monkeypatch.setattr(PreflightService, '_check_local_ports',+ staticmethod(lambda: ports))+ # Keep the verdict OS-independent even though the machine may be Windows.+ monkeypatch.setattr(preflight_mod.os, 'name', 'posix')+++# ---------------------------------------------------------------------------+# preflight+# ---------------------------------------------------------------------------++def test_preflight_all_pass_persists_row(app, monkeypatch):+ _patch_checks(monkeypatch)+ result = PreflightService.run('mail.example.com', server_ip='203.0.113.5')+ assert result['passed'] is True+ assert result['ptr_ok'] is True+ assert result['port25_ok'] is True+ assert result['rbl_ok'] is True+ # A row was persisted and is the latest.+ assert PreflightResult.query.count() == 1+ latest = PreflightService.latest()+ assert latest['passed'] is True+ assert latest['hostname'] == 'mail.example.com'+++def test_preflight_rbl_hit_fails(app, monkeypatch):+ _patch_checks(monkeypatch, rbl=(False, ['zen.spamhaus.org'], 'Listed on: zen.spamhaus.org'))+ result = PreflightService.run('mail.example.com', server_ip='203.0.113.5')+ assert result['passed'] is False+ assert result['rbl_ok'] is False+ assert 'zen.spamhaus.org' in result['rbl_hits']+ assert result['detail']['rbl']['hits'] == ['zen.spamhaus.org']+++def test_preflight_blocked_port25_fails(app, monkeypatch):+ _patch_checks(monkeypatch, port25=(False, 'provider blocks port 25'))+ result = PreflightService.run('mail.example.com', server_ip='203.0.113.5')+ assert result['passed'] is False+ assert result['port25_ok'] is False+ assert result['detail']['port25']['ok'] is False+++def test_preflight_windows_skips_and_never_raises(app, monkeypatch):+ # Do NOT stub the checks; force the real OS gate to skip host-dependent work.+ monkeypatch.setattr(preflight_mod.os, 'name', 'nt')+ result = PreflightService.run('mail.example.com', server_ip='203.0.113.5')+ assert result['passed'] is False # skipped checks never green-light sending+ assert 'dev_note' in result['detail']+++def test_preflight_latest_returns_newest(app, monkeypatch):+ from app import db+ from datetime import datetime, timedelta+ old = PreflightResult(hostname='old.example.com', passed=False,+ checked_at=datetime.utcnow() - timedelta(hours=2))+ new = PreflightResult(hostname='new.example.com', passed=True,+ checked_at=datetime.utcnow())+ db.session.add_all([old, new])+ db.session.commit()+ latest = PreflightService.latest()+ assert latest['hostname'] == 'new.example.com'+++def test_preflight_latest_none_when_empty(app):+ assert PreflightService.latest() is None+++# ---------------------------------------------------------------------------+# activation gate (the key safety property)+# ---------------------------------------------------------------------------++def _make_domain(active=False):+ from app import db+ row = MailDomain(name='gate.example.com', is_active=active, sync_state='pending')+ db.session.add(row)+ db.session.commit()+ return row+++def test_activation_refused_without_passing_preflight(app):+ row = _make_domain()+ result = MailService.set_domain_active(row.id, True)+ assert result['success'] is False+ assert result['code'] == 'preflight_required'+ # The domain stays inactive.+ from app import db+ db.session.refresh(row)+ assert row.is_active is False+++def test_activation_allowed_with_force_and_audits(app, monkeypatch):+ row = _make_domain()+ audits = []+ monkeypatch.setattr(+ MailService, '_audit',+ staticmethod(lambda action, target_id, details: audits.append(+ (action, target_id, details))))+ result = MailService.set_domain_active(row.id, True, force=True)+ assert result['success'] is True+ from app import db+ db.session.refresh(row)+ assert row.is_active is True+ # The force override was recorded on the audit ledger.+ assert audits and audits[0][0] == 'mail.domain.activate_forced'+ assert audits[0][1] == row.id+++def test_activation_allowed_with_passing_preflight(app):+ from app import db+ db.session.add(PreflightResult(hostname='gate.example.com', passed=True))+ db.session.commit()+ row = _make_domain()+ result = MailService.set_domain_active(row.id, True) # no force needed+ assert result['success'] is True+ db.session.refresh(row)+ assert row.is_active is True+++def test_deactivation_is_never_gated(app):+ row = _make_domain(active=True)+ result = MailService.set_domain_active(row.id, False)+ assert result['success'] is True+ from app import db+ db.session.refresh(row)+ assert row.is_active is False+++# ---------------------------------------------------------------------------+# DKIM keygen + record builder+# ---------------------------------------------------------------------------++def test_generate_dkim_stores_keys_and_txt_value(app):+ from app import db+ row = MailDomain(name='dkim.example.com')+ db.session.add(row)+ db.session.commit()++ result = DkimDnsService.generate_dkim(row)+ assert result['success'] is True, result+ assert result['selector'] == 'serverkit'+ assert result['dkim_value'].startswith('v=DKIM1; k=rsa; p=')++ db.session.refresh(row)+ assert row.dkim_private_key and 'PRIVATE KEY' in row.dkim_private_key+ assert row.dkim_public_key+ # The stored public key round-trips into the same TXT value.+ assert result['dkim_value'].endswith(row.dkim_public_key)+++def test_build_records_shapes():+ domain = MailDomain(name='Example.COM', dkim_selector='serverkit',+ dkim_public_key='PUBKEYB64')+ records = DkimDnsService.build_records(domain, server_ip='203.0.113.5')+ by_type = {}+ for r in records:+ by_type.setdefault(r['type'], []).append(r)++ mx = by_type['MX'][0]+ assert mx['name'] == 'example.com'+ assert mx['value'] == '10 mail.example.com'+ assert mx['priority'] == 10++ txts = {r['name']: r['value'] for r in by_type['TXT']}+ assert txts['example.com'] == 'v=spf1 mx a ~all'+ assert txts['_dmarc.example.com'].startswith('v=DMARC1; p=quarantine')+ assert txts['serverkit._domainkey.example.com'] == 'v=DKIM1; k=rsa; p=PUBKEYB64'++ a = by_type['A'][0]+ assert a['name'] == 'mail.example.com'+ assert a['value'] == '203.0.113.5'+++def test_build_records_omits_dkim_and_a_when_absent():+ domain = MailDomain(name='bare.example.com', dkim_selector='serverkit',+ dkim_public_key=None)+ records = DkimDnsService.build_records(domain, server_ip=None)+ names = {(r['type'], r['name']) for r in records}+ assert ('A', 'mail.bare.example.com') not in names+ assert not any(r['name'].startswith('serverkit._domainkey') for r in records)+++# ---------------------------------------------------------------------------+# DNS deployment via DNSProviderService+# ---------------------------------------------------------------------------++def _patch_provider(monkeypatch, zone=('cfg', 'zone')):+ """Patch DNSProviderService.find_zone_for_domain + set_record; return the+ captured set_record calls."""+ from app.services.dns_provider_service import DNSProviderService+ calls = []++ config = SimpleNamespace(id=7, name='cloudflare')+ zone_dict = {'id': 'zone-abc', 'name': 'example.com'}++ monkeypatch.setattr(DNSProviderService, 'find_zone_for_domain',+ classmethod(lambda cls, name: (config, zone_dict)))++ def fake_set_record(cls, provider_id, zone_id, record_type, name, value,+ ttl=3600, proxied=False, priority=None, source='provider'):+ calls.append({'provider_id': provider_id, 'zone_id': zone_id,+ 'type': record_type, 'name': name, 'value': value,+ 'priority': priority, 'source': source})+ return {'success': True}+ monkeypatch.setattr(DNSProviderService, 'set_record', classmethod(fake_set_record))+ return calls, config, zone_dict+++def test_deploy_dns_pushes_exact_records(app, monkeypatch):+ from app import db+ row = MailDomain(name='example.com', dkim_selector='serverkit',+ dkim_public_key='PUBKEYB64')+ db.session.add(row)+ db.session.commit()++ calls, config, zone = _patch_provider(monkeypatch)+ result = DkimDnsService.deploy_dns(row.id, server_ip='203.0.113.5')+ assert result['success'] is True+ assert result['deployed'] is True+ assert result['manual'] is False++ by = {(c['type'], c['name']): c for c in calls}+ # Every write is tagged source='mail' for the ownership ledger.+ assert all(c['source'] == 'mail' for c in calls)+ assert all(c['provider_id'] == 7 and c['zone_id'] == 'zone-abc' for c in calls)++ mx = by[('MX', 'example.com')]+ assert mx['value'] == '10 mail.example.com'+ assert mx['priority'] == 10+ assert by[('TXT', 'example.com')]['value'] == 'v=spf1 mx a ~all'+ assert by[('TXT', '_dmarc.example.com')]['value'].startswith('v=DMARC1; p=quarantine')+ assert by[('TXT', 'serverkit._domainkey.example.com')]['value'] == \+ 'v=DKIM1; k=rsa; p=PUBKEYB64'+ assert by[('A', 'mail.example.com')]['value'] == '203.0.113.5'++ # The deployment ledger was recorded on the row.+ db.session.refresh(row)+ assert row.dns_deployed is True+ ledger = json.loads(row.dns_last_result)+ assert ledger['all_ok'] is True+ assert ledger['provider'] == 'cloudflare'+++def test_deploy_dns_no_provider_returns_manual(app, monkeypatch):+ from app import db+ from app.services.dns_provider_service import DNSProviderService+ row = MailDomain(name='noprovider.example.com')+ db.session.add(row)+ db.session.commit()++ monkeypatch.setattr(DNSProviderService, 'find_zone_for_domain',+ classmethod(lambda cls, name: (None, None)))+ monkeypatch.setattr(+ DNSProviderService, 'set_record',+ classmethod(lambda *a, **kw: pytest.fail('set_record must not run without a zone')))++ result = DkimDnsService.deploy_dns(row.id, server_ip='203.0.113.5')+ assert result['success'] is True+ assert result['deployed'] is False+ assert result['manual'] is True+ assert isinstance(result['records'], list) and result['records']+++def test_dns_instructions_shape(app):+ from app import db+ row = MailDomain(name='inst.example.com', dkim_selector='serverkit',+ dkim_public_key='PUB')+ db.session.add(row)+ db.session.commit()+ out = DkimDnsService.dns_instructions(row, server_ip='203.0.113.5')+ assert out['domain'] == 'inst.example.com'+ assert out['dns_deployed'] is False+ assert out['dkim_configured'] is False # only public key set here, no private+ assert any(r['type'] == 'MX' for r in out['records'])+++def test_request_cert_skips_on_windows(monkeypatch):+ monkeypatch.setattr(dns_mod.os, 'name', 'nt')+ result = DkimDnsService.request_cert('mail.example.com')+ assert result['success'] is False+ assert result['skipped'] is True+++# ---------------------------------------------------------------------------+# fail2ban jail+# ---------------------------------------------------------------------------++def test_jail_unavailable_on_windows(monkeypatch):+ monkeypatch.setattr(jail_mod.os, 'name', 'nt')+ assert MailJailService.available() is False+ # Mutating calls degrade to a skipped descriptor, never raise.+ res = MailJailService.enable_auth_jail()+ assert res['success'] is True+ assert res['skipped'] is True+ assert res['available'] is False+++def test_jail_enable_writes_serverkit_mail_conf(monkeypatch):+ monkeypatch.setattr(jail_mod.os, 'name', 'posix')+ monkeypatch.setattr(jail_mod, 'is_command_available', lambda c: True)++ writes = []++ def fake_run(cmd, timeout=None, input=None, **kwargs):+ writes.append({'cmd': list(cmd), 'input': input})+ return _proc(returncode=0)+ monkeypatch.setattr(jail_mod, 'run_privileged', fake_run)++ res = MailJailService.enable_auth_jail()+ assert res['success'] is True+ assert res['jail'] == 'serverkit-mail-auth'+ assert res['path'].endswith('serverkit-mail-auth.conf')++ tee = next(w for w in writes if w['cmd'][:1] == ['tee'])+ assert tee['cmd'][1].endswith('serverkit-mail-auth.conf')+ assert '/etc/fail2ban/jail.d' in tee['cmd'][1]+ assert '[serverkit-mail-auth]' in tee['input']+ assert 'enabled = true' in tee['input']+ # fail2ban was reloaded after the write.+ assert any(w['cmd'][:2] == ['fail2ban-client', 'reload'] for w in writes)+++def test_jail_status_reports_availability(monkeypatch):+ monkeypatch.setattr(jail_mod.os, 'name', 'nt')+ info = MailJailService.status()+ assert info['available'] is False+ assert info['enabled'] is False+ assert info['jail'] == 'serverkit-mail-auth'