feat: add Campaign delivery ownership and IMAP claim primitives

src/govoplan_campaign/backend/campaign/mail_profile_boundary.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+CAMPAIGN_MAIL_SERVER_KEYS = frozenset({"mail_profile_id"})
+
+
+class CampaignMailProfileBoundaryError(ValueError):
+    """Raised when campaign JSON owns mail transport configuration.
+
+    SMTP/IMAP endpoints and credentials are Mail-module data. Campaign JSON
+    may select one Mail-owned profile, but it must never copy or override that
+    profile's transport configuration.
+    """
+
+
+def campaign_mail_profile_id(raw_json: dict[str, Any] | None) -> str | None:
+    server = raw_json.get("server") if isinstance(raw_json, dict) else None
+    if not isinstance(server, dict):
+        return None
+    value = server.get("mail_profile_id")
+    if not isinstance(value, str):
+        return None
+    normalized = value.strip()
+    return normalized or None
+
+
+def campaign_mail_profile_boundary_violations(raw_json: dict[str, Any] | None) -> tuple[str, ...]:
+    server = raw_json.get("server") if isinstance(raw_json, dict) else None
+    if not isinstance(server, dict):
+        return ()
+
+    violations = [f"/server/{key}" for key in sorted(server) if key not in CAMPAIGN_MAIL_SERVER_KEYS]
+    if "mail_profile_id" in server:
+        profile_id = server["mail_profile_id"]
+        if not isinstance(profile_id, str) or not profile_id.strip():
+            violations.append("/server/mail_profile_id")
+    return tuple(violations)
+
+
+def assert_campaign_uses_mail_profile_reference(
+    raw_json: dict[str, Any] | None,
+    *,
+    require_profile: bool = False,
+) -> None:
+    violations = campaign_mail_profile_boundary_violations(raw_json)
+    if violations:
+        fields = ", ".join(violations)
+        raise CampaignMailProfileBoundaryError(
+            "Campaign JSON may only reference a Mail-module profile through "
+            f"server.mail_profile_id; remove campaign-local SMTP/IMAP settings ({fields}), "
+            "select an authorized Mail profile, and save a new campaign version."
+        )
+    if require_profile and campaign_mail_profile_id(raw_json) is None:
+        raise CampaignMailProfileBoundaryError(
+            "Campaign delivery requires server.mail_profile_id. Select an authorized, active "
+            "profile from the Mail module and validate the campaign again."
+        )
+
+
+def public_campaign_mail_server(raw_json: dict[str, Any] | None) -> dict[str, str]:
+    """Return the complete public/persisted Campaign-to-Mail contract."""
+
+    profile_id = campaign_mail_profile_id(raw_json)
+    return {"mail_profile_id": profile_id} if profile_id else {}