Skip to content

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.

refactor(unify): §6 Phase C6b — Postfix relay backed by EmailProviderConnection

Juan Denis2cbbb61dbf7f
diff --git a/backend/app/__init__.py b/backend/app/__init__.py
index 12154ca8..e31de055 100644
--- a/backend/app/__init__.py
+++ b/backend/app/__init__.py
@@ -440,6 +440,15 @@ def create_app(config_name=None):
# connection store (idempotent), so every zone resolves creds the same way.
from app.services.dns_zone_service import DNSZoneService
n_zones = DNSZoneService.link_legacy_zones()
+ # Fold a legacy single-row email relay config into the unified
+ # EmailProviderConnection table (§6); idempotent, best-effort.
+ try:
+ from app.services.email_relay_service import EmailRelayService
+ EmailRelayService.migrate_legacy_config()
+ except Exception as _relay_exc: # never block boot on this
+ import logging as _logging
+ _logging.getLogger(__name__).warning(
+ f'Email relay legacy migration skipped: {_relay_exc}')
if n_dns or n_store or n_cloud or n_settings or n_zones:
import logging as _logging
_logging.getLogger(__name__).info(
diff --git a/backend/app/api/notifications.py b/backend/app/api/notifications.py
index 29356b02..1fe0640d 100644
--- a/backend/app/api/notifications.py
+++ b/backend/app/api/notifications.py
@@ -403,6 +403,18 @@ def test_email_provider(provider_id):
return jsonify(result), 200 if result.get('success') else 400
+@notifications_bp.route('/admin/email-providers/<int:provider_id>', methods=['PUT'])
+@jwt_required()
+@admin_required
+def update_email_provider(provider_id):
+ """Update a provider's usage flags (uses_notifications / uses_relay /
+ relay_priority) — §6 unification. uses_relay applies only to SMTP."""
+ row = EmailProviderService.update_usage(provider_id, request.get_json() or {})
+ if row is None:
+ return jsonify({'error': 'Provider not found'}), 404
+ return jsonify({'success': True, 'provider': row.to_dict()}), 200
+
+
@notifications_bp.route('/admin/email-providers/<int:provider_id>/default', methods=['POST'])
@jwt_required()
@admin_required
diff --git a/backend/app/notifications/providers.py b/backend/app/notifications/providers.py
index 4db09f16..f712c4d0 100644
--- a/backend/app/notifications/providers.py
+++ b/backend/app/notifications/providers.py
@@ -140,6 +140,25 @@ class EmailProviderService:
db.session.commit()
return row
+ @classmethod
+ def update_usage(cls, provider_id, fields):
+ """Toggle a provider's usage flags (§6): uses_notifications, uses_relay,
+ relay_priority. uses_relay is only honored for SMTP connections."""
+ row = cls.get_provider(provider_id)
+ if not row:
+ return None
+ if 'uses_notifications' in fields:
+ row.uses_notifications = bool(fields['uses_notifications'])
+ if 'uses_relay' in fields:
+ row.uses_relay = bool(fields['uses_relay']) and row.provider == 'smtp'
+ if 'relay_priority' in fields and fields['relay_priority'] is not None:
+ try:
+ row.relay_priority = int(fields['relay_priority'])
+ except (TypeError, ValueError):
+ pass
+ db.session.commit()
+ return row
+
@classmethod
def set_default(cls, provider_id):
row = cls.get_provider(provider_id)
diff --git a/backend/app/services/email_relay_service.py b/backend/app/services/email_relay_service.py
index 5545f164..ee7547f7 100644
--- a/backend/app/services/email_relay_service.py
+++ b/backend/app/services/email_relay_service.py
@@ -1,23 +1,33 @@
"""Outbound SMTP relay (smarthost) for the mail server.
-Persists a single relay configuration (host/port/credentials, password
-Fernet-encrypted) and applies it to Postfix when present. The config is stored
-platform-agnostically so the dev panel can hold it; the Postfix apply is a no-op
-(with a note) on hosts where Postfix isn't installed. `test()` opens a real SMTP
-connection so credentials are validated on any OS.
+The relay is now one row of the unified ``EmailProviderConnection`` table — an
+``smtp`` connection flagged ``uses_relay`` (§6 unification) — so a single store
+drives both the Notification Bus and the Postfix relay. The legacy single-row
+``email_relay_config`` is migrated in on first boot and kept only as a read
+fallback during the deprecation window.
+
+Config is held platform-agnostically so the dev panel can hold it; the Postfix
+apply is a no-op (with a note) where Postfix isn't installed. ``test()`` opens a
+real SMTP connection so credentials validate on any OS.
"""
import ssl
+import json
import smtplib
import logging
from app import db
from app.models.email import EmailRelayConfig
+from app.models.email_provider import EmailProviderConnection
+from app.notifications.providers import EmailProviderService
from app.services.postfix_service import PostfixService
-from app.utils.crypto import encrypt_secret, decrypt_secret
+from app.utils.crypto import encrypt_secret
logger = logging.getLogger(__name__)
+# The relay connection is created/owned by this service.
+RELAY_PROVIDER_NAME = 'Postfix Relay'
+
def _is_masked(value):
"""True for our masking sentinels, so a round-tripped masked value never
@@ -27,84 +37,138 @@ def _is_masked(value):
return value.startswith('****') or set(value) == {'*'}
+def _coerce_port(value, default=587):
+ try:
+ return int(value or default)
+ except (TypeError, ValueError):
+ return default
+
+
+def _coerce_tls(value):
+ if isinstance(value, str):
+ return value.lower() not in ('0', 'false', 'no')
+ return bool(value) if value is not None else True
+
+
class EmailRelayService:
DEFAULT = {
'enabled': False, 'host': '', 'port': 587, 'username': '',
'use_tls': True, 'provider_hint': None, 'password_set': False,
}
+ # ------------------------------------------------------------------ #
+ # The relay connection (EmailProviderConnection, uses_relay=True)
+ # ------------------------------------------------------------------ #
+ @staticmethod
+ def _relay_row():
+ """The canonical relay connection regardless of active state (for
+ display/edit). Active-only selection for *applying* lives in
+ EmailProviderService.relay_provider()."""
+ return (EmailProviderConnection.query
+ .filter_by(uses_relay=True)
+ .order_by(EmailProviderConnection.relay_priority.desc(),
+ EmailProviderConnection.created_at.asc())
+ .first())
+
@staticmethod
- def _row():
- return EmailRelayConfig.query.first()
+ def _view_from_provider(row):
+ """Public relay view from a connection — never exposes the password."""
+ creds = row.credentials() # decrypted; non-secret fields pass through
+ return {
+ 'enabled': bool(row.is_active),
+ 'host': creds.get('host') or '',
+ 'port': _coerce_port(creds.get('port')),
+ 'username': creds.get('username') or '',
+ 'use_tls': _coerce_tls(creds.get('use_tls')),
+ 'provider_hint': creds.get('provider_hint'),
+ 'password_set': bool(creds.get('password')),
+ 'updated_at': row.updated_at.isoformat() if row.updated_at else None,
+ 'provider_id': row.id,
+ }
@classmethod
def get_config(cls):
- row = cls._row()
- return row.to_dict() if row else dict(cls.DEFAULT)
+ row = cls._relay_row()
+ if row:
+ return cls._view_from_provider(row)
+ # Back-compat: a legacy single-row config not yet migrated.
+ legacy = EmailRelayConfig.query.first()
+ if legacy:
+ return legacy.to_dict()
+ return dict(cls.DEFAULT)
@classmethod
def save_config(cls, data):
- row = cls._row() or EmailRelayConfig()
- row.host = (data.get('host') or '').strip()
- try:
- row.port = int(data.get('port') or 587)
- except (TypeError, ValueError):
- row.port = 587
- row.username = (data.get('username') or '').strip()
- row.use_tls = bool(data.get('use_tls', True))
- row.enabled = bool(data.get('enabled', True))
- row.provider_hint = data.get('provider_hint')
+ row = cls._relay_row()
+ creds = row.raw_credentials() if row else {}
+ creds['host'] = (data.get('host') or '').strip()
+ creds['port'] = _coerce_port(data.get('port'))
+ creds['username'] = (data.get('username') or '').strip()
+ creds['use_tls'] = bool(data.get('use_tls', True))
+ if data.get('provider_hint') is not None:
+ creds['provider_hint'] = data.get('provider_hint')
pw = data.get('password')
if pw and not _is_masked(pw):
- row.password_encrypted = encrypt_secret(pw)
- if row.id is None:
+ creds['password'] = encrypt_secret(pw)
+ enabled = bool(data.get('enabled', True))
+
+ if row is None:
+ row = EmailProviderConnection(
+ provider='smtp', name=RELAY_PROVIDER_NAME,
+ uses_relay=True, uses_notifications=False, relay_priority=0,
+ )
db.session.add(row)
+ row.credentials_json = json.dumps(creds)
+ row.is_active = enabled
+ row.uses_relay = True
db.session.commit()
- return {'config': row.to_dict(), 'apply': cls.apply(row)}
+ return {'config': cls._view_from_provider(row), 'apply': cls.apply()}
@classmethod
- def apply(cls, row=None):
- """Push the stored config to Postfix (if installed)."""
- row = row or cls._row()
- if not row:
- return {'applied': False, 'note': 'No relay configured'}
+ def apply(cls):
+ """Push the active relay connection to Postfix (if installed)."""
+ provider = EmailProviderService.relay_provider() # active relay only
status = PostfixService.get_status()
if not status.get('installed'):
- return {'applied': False, 'note': 'Saved. Postfix is not installed here — the relay applies on a configured mail server.'}
- if row.enabled and row.host:
- password = decrypt_secret(row.password_encrypted) if row.password_encrypted else ''
- result = PostfixService.configure_relay(row.host, row.port, row.username, password, row.use_tls)
- else:
- result = PostfixService.disable_relay()
+ return {'applied': False,
+ 'note': 'Saved. Postfix is not installed here — the relay applies on a configured mail server.'}
+ if provider:
+ creds = provider.credentials()
+ host = creds.get('host')
+ if host:
+ result = PostfixService.configure_relay(
+ host, _coerce_port(creds.get('port')), creds.get('username') or '',
+ creds.get('password') or '', _coerce_tls(creds.get('use_tls')))
+ result['applied'] = result.get('success', False)
+ return result
+ result = PostfixService.disable_relay()
result['applied'] = result.get('success', False)
return result
@classmethod
def disable(cls):
- row = cls._row()
+ row = cls._relay_row()
if row:
- row.enabled = False
+ row.is_active = False
db.session.commit()
- return cls.apply(row)
+ return cls.apply()
@classmethod
def test(cls, data):
"""Open a real SMTP connection to validate host/port/credentials."""
- row = cls._row()
- host = (data.get('host') or (row.host if row else '') or '').strip()
+ row = cls._relay_row()
+ creds = row.credentials() if row else {}
+ host = (data.get('host') or creds.get('host') or '').strip()
if not host:
return {'success': False, 'error': 'A relay host is required'}
- try:
- port = int(data.get('port') or (row.port if row else 587))
- except (TypeError, ValueError):
- port = 587
- username = data.get('username') or (row.username if row else '')
- use_tls = data.get('use_tls', row.use_tls if row else True)
+ port = _coerce_port(data.get('port') or creds.get('port'))
+ username = data.get('username') or creds.get('username') or ''
+ use_tls = _coerce_tls(data.get('use_tls', creds.get('use_tls', True)))
password = data.get('password')
if password and _is_masked(password):
password = None
- if not password and row and row.password_encrypted:
- password = decrypt_secret(row.password_encrypted)
+ if not password:
+ password = creds.get('password') # already decrypted by credentials()
try:
if port == 465:
@@ -121,3 +185,38 @@ class EmailRelayService:
return {'success': True, 'message': f'Connected to {host}:{port}'}
except Exception as e:
return {'success': False, 'error': str(e)}
+
+ # ------------------------------------------------------------------ #
+ # One-time legacy migration
+ # ------------------------------------------------------------------ #
+ @classmethod
+ def migrate_legacy_config(cls):
+ """Idempotently fold a legacy ``email_relay_config`` row into a
+ ``uses_relay`` EmailProviderConnection. No-op if a relay connection
+ already exists or there is no usable legacy row. The legacy password is
+ already Fernet-encrypted with the same key, so it copies verbatim."""
+ if cls._relay_row() is not None:
+ return False
+ legacy = EmailRelayConfig.query.first()
+ if not legacy or not (legacy.host or '').strip():
+ return False
+ creds = {
+ 'host': legacy.host or '',
+ 'port': legacy.port or 587,
+ 'username': legacy.username or '',
+ 'use_tls': bool(legacy.use_tls),
+ }
+ if legacy.provider_hint:
+ creds['provider_hint'] = legacy.provider_hint
+ if legacy.password_encrypted:
+ creds['password'] = legacy.password_encrypted # already encrypted
+ row = EmailProviderConnection(
+ provider='smtp', name=RELAY_PROVIDER_NAME,
+ credentials_json=json.dumps(creds),
+ uses_relay=True, uses_notifications=False,
+ is_active=bool(legacy.enabled), relay_priority=0,
+ )
+ db.session.add(row)
+ db.session.commit()
+ logger.info('Migrated legacy email relay config into EmailProviderConnection %s', row.id)
+ return True
diff --git a/backend/tests/test_email_relay_unified.py b/backend/tests/test_email_relay_unified.py
new file mode 100644
index 00000000..a65725ef
--- /dev/null
+++ b/backend/tests/test_email_relay_unified.py
@@ -0,0 +1,99 @@
+"""§6 Phase C6b — EmailRelayService backed by the unified provider table.
+
+The relay is an smtp EmailProviderConnection flagged uses_relay. Verifies
+save/read/disable round-trips and the idempotent legacy migration. Postfix
+apply is a no-op in tests (not installed), so we assert config state, not
+Postfix side effects.
+"""
+from app.services.email_relay_service import EmailRelayService
+from app.notifications.providers import EmailProviderService
+from app.models.email_provider import EmailProviderConnection
+from app.utils.crypto import decrypt_secret_safe
+
+
+def test_save_creates_relay_provider(app):
+ with app.app_context():
+ EmailRelayService.save_config({
+ 'enabled': True, 'host': 'smtp.relay.io', 'port': 587,
+ 'username': 'relayuser', 'password': 'secretpw', 'use_tls': True,
+ 'provider_hint': 'mailgun',
+ })
+ view = EmailRelayService.get_config()
+ assert view['enabled'] is True
+ assert view['host'] == 'smtp.relay.io'
+ assert view['username'] == 'relayuser'
+ assert view['password_set'] is True
+ assert view['provider_hint'] == 'mailgun'
+
+ # Stored as a uses_relay smtp connection; password encrypted at rest.
+ row = EmailProviderConnection.query.filter_by(uses_relay=True).first()
+ assert row is not None and row.provider == 'smtp'
+ assert row.uses_notifications is False
+ raw_pw = row.raw_credentials().get('password')
+ assert raw_pw and raw_pw != 'secretpw'
+ assert decrypt_secret_safe(raw_pw) == 'secretpw'
+
+
+def test_relay_provider_not_used_for_notifications(app):
+ with app.app_context():
+ EmailRelayService.save_config({
+ 'enabled': True, 'host': 'smtp.relay.io', 'username': 'u', 'password': 'p',
+ })
+ # The relay connection must not be picked as the notification default.
+ assert EmailProviderService.default_provider() is None
+
+
+def test_masked_password_preserved_on_resave(app):
+ with app.app_context():
+ EmailRelayService.save_config({'enabled': True, 'host': 'h', 'username': 'u', 'password': 'orig'})
+ # Re-save with a masked password (UI round-trip) — secret must persist.
+ EmailRelayService.save_config({'enabled': True, 'host': 'h2', 'username': 'u', 'password': '****'})
+ row = EmailProviderConnection.query.filter_by(uses_relay=True).first()
+ assert decrypt_secret_safe(row.raw_credentials().get('password')) == 'orig'
+ assert EmailRelayService.get_config()['host'] == 'h2'
+
+
+def test_disable_marks_inactive(app):
+ with app.app_context():
+ EmailRelayService.save_config({'enabled': True, 'host': 'h', 'username': 'u', 'password': 'p'})
+ EmailRelayService.disable()
+ assert EmailRelayService.get_config()['enabled'] is False
+ # Inactive relay is not selected for applying.
+ assert EmailProviderService.relay_provider() is None
+
+
+def test_migrate_legacy_config_idempotent(app):
+ from app import db
+ from app.models.email import EmailRelayConfig
+ from app.utils.crypto import encrypt_secret
+ with app.app_context():
+ legacy = EmailRelayConfig(
+ enabled=True, host='legacy.smtp', port=2525, username='legacyuser',
+ password_encrypted=encrypt_secret('legacypw'), use_tls=True, provider_hint='ses',
+ )
+ db.session.add(legacy)
+ db.session.commit()
+
+ assert EmailRelayService.migrate_legacy_config() is True
+ row = EmailProviderConnection.query.filter_by(uses_relay=True).first()
+ assert row is not None
+ creds = row.credentials()
+ assert creds['host'] == 'legacy.smtp'
+ assert creds['password'] == 'legacypw' # decrypts cleanly (same key)
+ assert EmailRelayService.get_config()['host'] == 'legacy.smtp'
+
+ # Idempotent: a second run is a no-op (relay row already exists).
+ assert EmailRelayService.migrate_legacy_config() is False
+
+
+def test_update_usage_smtp_only_relay(app):
+ with app.app_context():
+ sg = EmailProviderService.add_provider({'provider': 'sendgrid', 'name': 'SG', 'api_key': 'k'})
+ EmailProviderService.update_usage(sg.id, {'uses_relay': True})
+ assert EmailProviderConnection.query.get(sg.id).uses_relay is False # API provider rejected
+
+ smtp = EmailProviderService.add_provider({
+ 'provider': 'smtp', 'name': 'S', 'host': 'h', 'username': 'u', 'password': 'p'})
+ EmailProviderService.update_usage(smtp.id, {'uses_relay': True, 'relay_priority': 3})
+ updated = EmailProviderConnection.query.get(smtp.id)
+ assert updated.uses_relay is True and updated.relay_priority == 3