feat(mail): add governed JMAP mailbox sync and search

src/govoplan_mail/backend/documentation.py

@@ -26,7 +26,7 @@ MAIL_SECRET_MANAGE_SCOPE = "mail:secret:manage"  # noqa: S105  # nosec B105
 MAIL_SECRET_MANAGE_OWN_SCOPE = "mail:secret:manage_own"  # noqa: S105  # nosec B105
 MAIL_PROFILE_TEST_SCOPE = "mail:profile:test"
 MAIL_PROFILE_USE_SCOPE = "mail:profile:use"
-_HOST_POLICY_FIELDS = (("SMTP", "smtp_hosts"), ("IMAP", "imap_hosts"))
+_HOST_POLICY_FIELDS = (("SMTP", "smtp_hosts"), ("IMAP", "imap_hosts"), ("JMAP", "jmap_hosts"))
 
 
 def documentation_topics(context: DocumentationContext) -> tuple[DocumentationTopic, ...]:
@@ -233,7 +233,7 @@ def _custom_mail_profile_topic(context: DocumentationContext) -> DocumentationTo
         title="Create a custom Mail profile",
         summary=(
             "Create a reusable profile in the current account's user-scoped Settings view, "
-            "within the active SMTP and IMAP hostname policy."
+            "within the active SMTP, IMAP, and JMAP hostname policy."
         ),
         body="\n".join(authority_lines),
         layer="configured",
@@ -345,12 +345,12 @@ def _custom_profile_authority_lines(
     approval_required: bool,
 ) -> tuple[str, ...]:
     credentials = (
-        "Credential authority: you may save or replace Mail-owned SMTP/IMAP passwords."
+        "Credential authority: you may save or replace Mail-owned SMTP/IMAP passwords and JMAP tokens or Basic credentials."
         if can_manage_credentials
         else "Credential authority: you may define the profile, but you cannot save or replace passwords; an actor with both profile-write and secret-management authority must do that when authentication requires one."
     )
     testing = (
-        "Test authority: you may run the profile's SMTP/IMAP connection tests after saving it as active."
+        "Test authority: you may run the profile's SMTP/IMAP/JMAP connection tests after saving it as active."
         if can_test_profile
         else "Test authority: creating the profile does not let you run connection tests; ask an actor with both profile-test and profile-use authority to verify an active profile."
     )
@@ -376,18 +376,18 @@ def _custom_profile_steps(
 ) -> tuple[str, ...]:
     steps = [
         "Open Settings, choose Mail profiles, and select Add profile in the current account's user-scoped view.",
-        "Enter a stable name and configure SMTP plus optional IMAP hostnames that satisfy every host-policy statement shown above.",
+        "Enter a stable name and configure SMTP plus optional IMAP settings; add an optional JMAP server after the profile exists. Every endpoint must satisfy the host-policy statements shown above.",
     ]
     steps.append(
-        "Enter the required SMTP/IMAP credentials in the dedicated password fields."
+        "Enter the required SMTP/IMAP credentials, or link an encrypted bearer token or Basic credential to the JMAP server."
         if can_manage_credentials
         else "Save the non-secret profile definition, then ask an actor with both profile-write and secret-management authority to add credentials if the server requires authentication."
     )
     steps.append("Save the profile; Mail validates the effective user-scope host policy again on the server.")
     steps.append(
-        "Save the profile as active, then run the available SMTP and IMAP connection tests."
+        "Save the profile as active, then run the available SMTP, IMAP, and JMAP connection tests."
         if can_test_profile
-        else "Ask an actor with both profile-test and profile-use authority to run the SMTP and IMAP connection tests after the profile is active."
+        else "Ask an actor with both profile-test and profile-use authority to run the SMTP, IMAP, and JMAP connection tests after the profile is active."
     )
     if approval_required:
         steps.append("Ask a Mail administrator to add the new profile to the active approved-profile list.")
@@ -402,9 +402,9 @@ def _custom_profile_steps(
 def _custom_profile_verification(*, can_test_profile: bool, can_use_profile: bool, approval_required: bool) -> str:
     checks = ["Reopen My Mail profiles and confirm the saved profile remains in the current account's user-scoped view."]
     checks.append(
-        "Confirm the authorized SMTP/IMAP tests succeed."
+        "Confirm the authorized SMTP/IMAP/JMAP tests succeed."
         if can_test_profile
-        else "Have an authorized tester confirm the SMTP/IMAP tests succeed."
+        else "Have an authorized tester confirm the SMTP/IMAP/JMAP tests succeed."
     )
     if approval_required:
         checks.append("Confirm an administrator approved the generated profile reference before expecting it in a picker.")
@@ -424,7 +424,7 @@ def _mail_policy_admin_text(policy: dict[str, Any], *, source_count: int) -> tup
     locked_limit_count = sum(1 for value in _lower_limit_values(policy) if value is False)
 
     if approved_profile_limit and not lower_scopes:
-        summary = "This tenant is in approved-profile mode: users can choose configured mail profiles, but lower scopes cannot bring arbitrary SMTP or IMAP servers."
+        summary = "This tenant is in approved-profile mode: users can choose configured mail profiles, but lower scopes cannot bring arbitrary SMTP, IMAP, or JMAP servers."
     elif approved_profile_limit:
         summary = "This tenant limits mail sending to approved profile ids, while selected lower scopes can still define profiles within policy limits."
     elif lower_scopes:
@@ -451,10 +451,10 @@ def _mail_policy_user_text(policy: dict[str, Any]) -> tuple[str, str]:
         body = "This is set by tenant policy. If the mail server you need is not offered, ask an administrator to add it as an approved mail profile."
     elif approved_profile_limit:
         summary = "You can use approved Mail profiles. Some scopes may also define additional reusable profiles."
-        body = "The available profiles are limited by tenant policy. Campaigns select one profile by reference; SMTP/IMAP settings and credentials remain managed in Mail."
+        body = "The available profiles are limited by tenant policy. Campaigns select one profile by reference; SMTP/IMAP/JMAP settings and credentials remain managed in Mail."
     elif lower_scopes:
         summary = "You may be able to define reusable Mail profiles in selected scopes, subject to tenant rules."
-        body = "GovOPlaN checks each profile before use. Campaigns reference an available profile and never store its SMTP/IMAP settings or credentials."
+        body = "GovOPlaN checks each profile before use. Campaigns reference an available profile and never store its SMTP/IMAP/JMAP settings or credentials."
     else:
         summary = "Mail servers are managed centrally for this tenant."
         body = "You cannot add a personal, group, or campaign mail server here. Choose one of the configured options or ask an administrator to add another approved profile."