Add institutional provenance and approval gates

2026-08-01 20:57:26 +02:00
parent cec3d17bff
commit 2afdd38128
16 changed files with 2472 additions and 509 deletions
@@ -7,6 +7,13 @@ from contextlib import contextmanager
 from pathlib import Path
 from typing import Any, Iterator

+from govoplan_core.core.approvals import (
+    ApprovalCheck,
+    ApprovalRequestCreateCommand,
+    ApprovalRequestProvider,
+    ApprovalRequestRef,
+    CAPABILITY_APPROVAL_REQUESTS,
+)
 from govoplan_core.core.postbox import (
    CAPABILITY_POSTBOX_DIRECTORY,
    CAPABILITY_POSTBOX_DELIVERY,
@@ -29,6 +36,7 @@ MAIL_CAPABILITY = "mail.campaign_delivery"
 POSTBOX_CAPABILITY = CAPABILITY_POSTBOX_DELIVERY
 POSTBOX_DIRECTORY_CAPABILITY = CAPABILITY_POSTBOX_DIRECTORY
 POSTBOX_EVIDENCE_CAPABILITY = CAPABILITY_POSTBOX_EVIDENCE
+APPROVALS_CAPABILITY = CAPABILITY_APPROVAL_REQUESTS


 class OptionalModuleUnavailable(RuntimeError):
@@ -40,7 +48,9 @@ class SmtpConfigurationError(RuntimeError):


 class SmtpSendError(RuntimeError):
-    def __init__(self, message: str, *, temporary: bool = False, outcome_unknown: bool = False) -> None:
+    def __init__(
+        self, message: str, *, temporary: bool = False, outcome_unknown: bool = False
+    ) -> None:
        super().__init__(message)
        self.temporary = temporary
        self.outcome_unknown = outcome_unknown
@@ -75,6 +85,10 @@ class PostboxDeliveryUnavailable(OptionalModuleUnavailable):
    pass


+class ApprovalGateUnavailable(OptionalModuleUnavailable):
+    pass
+
+
 class _PreparedCampaignSnapshot:
    def __init__(self, directory: Path, path: Path, raw_json: dict[str, Any]) -> None:
        self._directory = directory
@@ -103,20 +117,30 @@ class FilesCampaignIntegration:
                yield prepared
            return

-        raw_json = kwargs.get("raw_json") if isinstance(kwargs.get("raw_json"), dict) else {}
+        raw_json = (
+            kwargs.get("raw_json") if isinstance(kwargs.get("raw_json"), dict) else {}
+        )
        prefix = str(kwargs.get("prefix") or "govoplan-campaign-")
        directory = Path(tempfile.mkdtemp(prefix=prefix))
-        snapshot = _PreparedCampaignSnapshot(directory, directory / "campaign.json", raw_json)
-        snapshot.path.write_text(json.dumps(raw_json, ensure_ascii=False, indent=2), encoding="utf-8")
+        snapshot = _PreparedCampaignSnapshot(
+            directory, directory / "campaign.json", raw_json
+        )
+        snapshot.path.write_text(
+            json.dumps(raw_json, ensure_ascii=False, indent=2), encoding="utf-8"
+        )
        try:
            yield snapshot
        finally:
            snapshot.cleanup()

-    def managed_match_payloads(self, matches: Any, managed_files_by_local_path: dict[str, Any]) -> list[dict[str, Any]]:
+    def managed_match_payloads(
+        self, matches: Any, managed_files_by_local_path: dict[str, Any]
+    ) -> list[dict[str, Any]]:
        if self._delegate is None:
            return []
-        return self._delegate.managed_match_payloads(matches, managed_files_by_local_path)
+        return self._delegate.managed_match_payloads(
+            matches, managed_files_by_local_path
+        )

    def public_attachment_summary_payload(self, attachment: Any) -> dict[str, Any]:
        if self._delegate is not None:
@@ -127,20 +151,30 @@ class FilesCampaignIntegration:
            return dict(attachment)
        return {"path": str(attachment)}

-    def annotate_built_messages_with_managed_files(self, built_messages: Any, managed_files_by_local_path: dict[str, Any]) -> None:
+    def annotate_built_messages_with_managed_files(
+        self, built_messages: Any, managed_files_by_local_path: dict[str, Any]
+    ) -> None:
        if self._delegate is not None:
-            self._delegate.annotate_built_messages_with_managed_files(built_messages, managed_files_by_local_path)
+            self._delegate.annotate_built_messages_with_managed_files(
+                built_messages, managed_files_by_local_path
+            )

-    def record_campaign_attachment_uses_for_jobs(self, session: Any, jobs: Any, *, stage: str) -> None:
+    def record_campaign_attachment_uses_for_jobs(
+        self, session: Any, jobs: Any, *, stage: str
+    ) -> None:
        if self._delegate is not None:
-            self._delegate.record_campaign_attachment_uses_for_jobs(session, jobs, stage=stage)
+            self._delegate.record_campaign_attachment_uses_for_jobs(
+                session, jobs, stage=stage
+            )

    def current_version_and_blob(self, session: Any, asset: Any) -> tuple[Any, Any]:
        if self._delegate is None:
            raise OptionalModuleUnavailable("Files module is not available")
        return self._delegate.current_version_and_blob(session, asset)

-    def share_assets_with_campaign(self, session: Any, **kwargs: Any) -> list[dict[str, Any]]:
+    def share_assets_with_campaign(
+        self, session: Any, **kwargs: Any
+    ) -> list[dict[str, Any]]:
        if self._delegate is None:
            raise OptionalModuleUnavailable("Files module is not available")
        return self._delegate.share_assets_with_campaign(session, **kwargs)
@@ -154,7 +188,9 @@ class MailCampaignIntegration:
    def __init__(self, delegate: Any | None = None) -> None:
        self._delegate = delegate
        if delegate is not None:
-            self.MailProfileError = getattr(delegate, "MailProfileError", MailProfileError)
+            self.MailProfileError = getattr(
+                delegate, "MailProfileError", MailProfileError
+            )

    MailProfileError = MailProfileError
    SmtpConfigurationError = SmtpConfigurationError
@@ -177,26 +213,38 @@ class MailCampaignIntegration:
            raise MailProfileError("Mail module is not available")
        return self._delegate

-    def assert_campaign_mail_policy_allows_json(self, session: Any, **kwargs: Any) -> None:
+    def assert_campaign_mail_policy_allows_json(
+        self, session: Any, **kwargs: Any
+    ) -> None:
        if self._delegate is None:
            raw_json = kwargs.get("raw_json")
-            profile_id = self.mail_profile_id_from_campaign_json(raw_json if isinstance(raw_json, dict) else {})
+            profile_id = self.mail_profile_id_from_campaign_json(
+                raw_json if isinstance(raw_json, dict) else {}
+            )
            if profile_id:
-                raise MailProfileError("Campaign mail-server profiles require the mail module")
+                raise MailProfileError(
+                    "Campaign mail-server profiles require the mail module"
+                )
            return None
        try:
-            return self._delegate.assert_campaign_mail_policy_allows_json(session, **kwargs)
+            return self._delegate.assert_campaign_mail_policy_allows_json(
+                session, **kwargs
+            )
        except getattr(self._delegate, "MailProfileError", MailProfileError) as exc:
            raise MailProfileError(str(exc)) from exc

-    def mail_profile_id_from_campaign_json(self, raw_json: dict[str, Any]) -> str | None:
+    def mail_profile_id_from_campaign_json(
+        self, raw_json: dict[str, Any]
+    ) -> str | None:
        if self._delegate is not None:
            return self._delegate.mail_profile_id_from_campaign_json(raw_json)
        server = raw_json.get("server") if isinstance(raw_json, dict) else None
        profile_id = server.get("mail_profile_id") if isinstance(server, dict) else None
        return str(profile_id).strip() if profile_id else None

-    def campaign_profile_delivery_summary(self, session: Any, **kwargs: Any) -> dict[str, Any]:
+    def campaign_profile_delivery_summary(
+        self, session: Any, **kwargs: Any
+    ) -> dict[str, Any]:
        delegate = self._require()
        try:
            return delegate.campaign_profile_delivery_summary(session, **kwargs)
@@ -213,8 +261,14 @@ class MailCampaignIntegration:
        try:
            return delegate.send_campaign_email_bytes(*args, **kwargs)
        except getattr(delegate, "SmtpSendError", SmtpSendError) as exc:
-            raise SmtpSendError(str(exc), temporary=bool(getattr(exc, "temporary", False)), outcome_unknown=bool(getattr(exc, "outcome_unknown", False))) from exc
-        except getattr(delegate, "SmtpConfigurationError", SmtpConfigurationError) as exc:
+            raise SmtpSendError(
+                str(exc),
+                temporary=bool(getattr(exc, "temporary", False)),
+                outcome_unknown=bool(getattr(exc, "outcome_unknown", False)),
+            ) from exc
+        except getattr(
+            delegate, "SmtpConfigurationError", SmtpConfigurationError
+        ) as exc:
            raise SmtpConfigurationError(str(exc)) from exc
        except getattr(delegate, "MailProfileError", MailProfileError) as exc:
            raise MailProfileError(str(exc)) from exc
@@ -229,7 +283,9 @@ class MailCampaignIntegration:
                temporary=getattr(exc, "temporary", None),
                outcome_unknown=bool(getattr(exc, "outcome_unknown", False)),
            ) from exc
-        except getattr(delegate, "ImapConfigurationError", ImapConfigurationError) as exc:
+        except getattr(
+            delegate, "ImapConfigurationError", ImapConfigurationError
+        ) as exc:
            raise ImapConfigurationError(str(exc)) from exc
        except getattr(delegate, "MailProfileError", MailProfileError) as exc:
            raise MailProfileError(str(exc)) from exc
@@ -302,8 +358,7 @@ class PostboxCampaignIntegration:
    @property
    def available(self) -> bool:
        return (
-            self._delivery_delegate is not None
-            and self._directory_delegate is not None
+            self._delivery_delegate is not None and self._directory_delegate is not None
        )

    @property
@@ -381,6 +436,63 @@ class PostboxCampaignIntegration:
        return summaries


+class ApprovalCampaignIntegration:
+    def __init__(self, delegate: object | None = None) -> None:
+        self._delegate = (
+            delegate if isinstance(delegate, ApprovalRequestProvider) else None
+        )
+
+    @property
+    def available(self) -> bool:
+        return self._delegate is not None
+
+    def create_request(
+        self,
+        session: object,
+        principal: object,
+        *,
+        command: ApprovalRequestCreateCommand,
+        idempotency_key: str,
+    ) -> ApprovalRequestRef:
+        if self._delegate is None:
+            raise ApprovalGateUnavailable(
+                "Campaign approval gates require the Approvals module."
+            )
+        return self._delegate.create_request(
+            session,
+            principal,
+            command=command,
+            idempotency_key=idempotency_key,
+        )
+
+    def check_approved(
+        self,
+        session: object,
+        principal: object,
+        *,
+        request_id: str,
+        subject_module: str,
+        subject_type: str,
+        subject_id: str,
+        subject_version: str | None,
+        subject_digest: str,
+    ) -> ApprovalCheck:
+        if self._delegate is None:
+            raise ApprovalGateUnavailable(
+                "Campaign delivery is approval-gated, but the Approvals module is unavailable."
+            )
+        return self._delegate.check_approved(
+            session,
+            principal,
+            request_id=request_id,
+            subject_module=subject_module,
+            subject_type=subject_type,
+            subject_id=subject_id,
+            subject_version=subject_version,
+            subject_digest=subject_digest,
+        )
+
+
 def files_integration() -> FilesCampaignIntegration:
    return FilesCampaignIntegration(capability(FILES_CAPABILITY))

@@ -395,3 +507,7 @@ def postbox_integration() -> PostboxCampaignIntegration:
        capability(POSTBOX_DIRECTORY_CAPABILITY),
        capability(POSTBOX_EVIDENCE_CAPABILITY),
    )
+
+
+def approvals_integration() -> ApprovalCampaignIntegration:
+    return ApprovalCampaignIntegration(capability(APPROVALS_CAPABILITY))