fix: Move spam to mailbox associated to the `\Junk` special-use attribute (#3925)

Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>

CHANGELOG.md

@@ -36,6 +36,10 @@ The most noteworthy change of this release is the update of the container's base
       - DMS `main.cf` has renamed `postscreen_dnsbl_whitelist_threshold` to `postscreen_dnsbl_allowlist_threshold` as part of this change.
     - `smtpd_relay_restrictions` (relay policy) is now evaluated after `smtpd_recipient_restrictions` (spam policy). Previously it was evaluated before `smtpd_recipient_restrictions`. Mail to be relayed via DMS must now pass through the spam policy first.
     - The TLS fingerprint policy has changed the default from MD5 to SHA256 (_DMS does not modify this Postfix parameter, but may affect any user customizations that do_).
+- **Dovecot**
+  - The "Junk" mailbox (folder) is now referenced by it's [special-use flag `\Junk`](https://docker-mailserver.github.io/docker-mailserver/v13.3/examples/use-cases/imap-folders/) instead of an explicit mailbox. ([#3925](https://github.com/docker-mailserver/docker-mailserver/pull/3925))
+    - This provides compatibility for the Junk mailbox when it's folder name differs (_eg: Renamed to "Spam"_).
+    - Potential breakage if your deployment modifies our `spam_to_junk.sieve` sieve script (_which is created during container startup when ENV `MOVE_SPAM_TO_JUNK=1`_) that handles storing spam mail into a users "Junk" mailbox folder.
 - **rsyslog:**
   - Debian 12 adjusted the `rsyslog` configuration for the default file template from `RSYSLOG_TraditionalFileFormat` to `RSYSLOG_FileFormat` (_upstream default since 2012_). This change may affect you if you have any monitoring / analysis of log output (_eg: `mail.log` / `docker logs`_).
     - The two formats are roughly equivalent to [RFC 3164](https://www.rfc-editor.org/rfc/rfc3164)) and [RFC 5424](https://datatracker.ietf.org/doc/html/rfc5424#section-1) respectively.

docs/content/config/environment.md

@@ -328,10 +328,12 @@ Note: More information at <https://dovecot.org/doc/dovecot-example.conf>
 
 ##### MOVE_SPAM_TO_JUNK
 
-- 0 => Spam messages will be delivered in the mailbox.
-- **1** => Spam messages will be delivered in the `Junk` folder.
+- 0 => Spam messages will be delivered to the inbox.
+- **1** => Spam messages will be delivered to the Junk mailbox.
 
-Routes mail identified as spam into the recipient(s) Junk folder (_via a Dovecot Sieve script_).
+Routes mail identified as spam into the recipient(s) Junk mailbox (_a specialized folder for junk associated to the [special-use flag `\Junk`][docs::dovecot::special-use-flag], handled via a Dovecot sieve script internally_).
+
+[docs::dovecot::special-use-flag]: ../examples/use-cases/imap-folders.md
 
 !!! info
 

target/dovecot/90-sieve.conf

@@ -51,7 +51,7 @@ plugin {
   # deprecated imapflags extension in addition to all extensions were already
   # enabled by default.
   #sieve_extensions = +notify +imapflags
-  sieve_extensions = +notify +imapflags +vnd.dovecot.pipe +vnd.dovecot.filter
+  sieve_extensions = +notify +imapflags +special-use +vnd.dovecot.pipe +vnd.dovecot.filter
 
   # Which Sieve language extensions are ONLY available in global scripts. This
   # can be used to restrict the use of certain Sieve extensions to administrator

target/scripts/startup/setup.d/security/misc.sh

@@ -304,11 +304,11 @@ function _setup_spam_to_junk() {
     _log 'debug' 'Spam emails will be moved to the Junk folder'
     mkdir -p /usr/lib/dovecot/sieve-global/after/
     cat >/usr/lib/dovecot/sieve-global/after/spam_to_junk.sieve << EOF
-require ["fileinto","mailbox"];
+require ["fileinto","special-use"];
 
 if anyof (header :contains "X-Spam-Flag" "YES",
           header :contains "X-Spam" "Yes") {
-    fileinto "Junk";
+    fileinto :specialuse "\\\\Junk" "Junk";
 }
 EOF
     sievec /usr/lib/dovecot/sieve-global/after/spam_to_junk.sieve

test/config/junk-mailbox/user-patches.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+##
+# This user script will be executed between configuration and starting daemons
+# To enable it you must save it in your config directory as "user-patches.sh"
+##
+
+echo "[user-patches.sh] Adjusting 'Junk' mailbox name to verify delivery to Junk mailbox based on special-use flag instead of mailbox's name"
+
+sed -i -e 's/mailbox Junk/mailbox Spam/' /etc/dovecot/conf.d/15-mailboxes.conf
+
+### Before / After ###
+
+# mailbox Junk {
+#   auto = subscribe
+#   special_use = \Junk
+# }
+
+# mailbox Spam {
+#   auto = subscribe
+#   special_use = \Junk
+# }

test/tests/parallel/set1/spam_virus/rspamd_full.bats

@@ -244,7 +244,7 @@ function teardown_file() { _default_teardown ; }
   _service_log_should_contain_string 'rspamd' 'add header "Gtube pattern"'
 
   _print_mail_log_for_msgid 'rspamd-test-email-header'
-  assert_output --partial "fileinto action: stored mail into mailbox 'Junk'"
+  assert_output --partial "fileinto action: stored mail into mailbox [SPECIAL-USE \\Junk]"
 
   _count_files_in_directory_in_container /var/mail/localhost.localdomain/user1/new/ 2
   _count_files_in_directory_in_container /var/mail/localhost.localdomain/user1/.Junk/new/ 1

test/tests/parallel/set1/spam_virus/spam_junk_folder.bats

@@ -49,9 +49,11 @@ function teardown() { _default_teardown ; }
   _should_receive_spam_at '/var/mail/localhost.localdomain/user1/new/'
 }
 
-@test "(enabled + MOVE_SPAM_TO_JUNK=1) should deliver spam message into Junk folder" {
+@test "(enabled + MOVE_SPAM_TO_JUNK=1) should deliver spam message into Junk mailbox" {
   export CONTAINER_NAME=${CONTAINER3_NAME}
 
+  _init_with_defaults
+
   local CUSTOM_SETUP_ARGUMENTS=(
     --env ENABLE_AMAVIS=1
     --env ENABLE_SPAMASSASSIN=1
@@ -60,14 +62,17 @@ function teardown() { _default_teardown ; }
     --env MOVE_SPAM_TO_JUNK=1
     --env PERMIT_DOCKER=container
   )
-  _init_with_defaults
+
+  # Adjust 'Junk' mailbox name to verify delivery to Junk mailbox based on special-use flag instead of mailbox's name
+  mv "${TEST_TMP_CONFIG}/junk-mailbox/user-patches.sh" "${TEST_TMP_CONFIG}/"
+
   _common_container_setup 'CUSTOM_SETUP_ARGUMENTS'
 
   _should_send_spam_message
   _should_be_received_by_amavis 'Passed SPAM {RelayedTaggedInbound,Quarantined}'
 
-  # Should move delivered spam to Junk folder
-  _should_receive_spam_at '/var/mail/localhost.localdomain/user1/.Junk/new/'
+  # Should move delivered spam to the Junk mailbox (adjusted to be located at '.Spam/')
+  _should_receive_spam_at '/var/mail/localhost.localdomain/user1/.Spam/new/'
 }
 
 # NOTE: Same as test for `CONTAINER3_NAME`, only differing by ENV `MARK_SPAM_AS_READ=1` + `_should_receive_spam_at` location