Sieve: Document support for extlists extension

Author: stephanbosch

.github/actions/spelling/expect.txt

@@ -3,6 +3,7 @@ ACAP
 actimeo
 addflag
 addprinc
+addressbook
 ADDRESULT
 ADH
 Adleman
@@ -208,6 +209,7 @@ euid
 examplescripts
 execv
 exim
+extlists
 exportkeytab
 extprograms
 extracttext

.github/actions/spelling/patterns.txt

@@ -161,3 +161,8 @@ key=[0-9a-f]+:\w+\}\s*=\s*(?:[0-9a-f$]+|pass)
 
 # directory permissions
 [-bcdlpsw](?:[-r][-w][-SsTtx]){3}[\.+*]?\s+\d+\s+\S+\s+\S+\s+\d+\s+
+
+# URNs
+urn:[A-Za-z0-9][A-Za-z0-9-]{0,31}:([A-Za-z0-9()+,\-.:=@;$_!*'?\/&]|%[0-9A-Fa-f]{2})+
+:addrbook:([A-Za-z0-9()+,\-.:=@;$_!*'?\/&]|%[0-9A-Fa-f]{2})+
+

data/settings.js

@@ -1092,6 +1092,61 @@ command.
 The minimum value for this setting is \`1024\` bytes.`
 	},
 
+	sieve_extlists_list: {
+		tags: [ 'sieve', 'sieve-extlists' ],
+		plugin: 'sieve',
+		values: setting_types.NAMED_LIST_FILTER,
+		seealso: [ '[[link,sieve_extlists]]' ],
+		text: `
+This named list filter creates a new list definition for the ":list" match type
+in Sieve (extlists extension). The filter name refers to the
+[[setting,sieve_extlists_list_name]] setting. That is the name of the list as it
+will be accessible from the Sieve. A dict definition that is placed inside
+the scope of this list filter will serve as the lookup for this extlists list.
+So, values from Sieve are looked up in the defined dict. This is often used to
+define an address book or whitelist external to the Sieve script. If no dict is
+present, the list will function as an empty list.
+
+Example:
+
+\`\`\`
+sieve_extlists_list :addrbook:default {
+  dict proxy {
+    name = addressbook
+  }
+}
+\`\`\``
+	},
+
+	sieve_extlists_list_name: {
+		tags: [ 'sieve', 'sieve-extlists' ],
+		plugin: 'sieve',
+		values: setting_types.STRING,
+		seealso: [ '[[link,sieve_extlists]]' ],
+		text: `
+The name of the list as it will be accessible through the Sieve ":list" match
+type (extlists extension). According to the standard, this name must be a valid
+URI. This implementation further limits that to a valid URN or TAG URI. Note
+that the standard URN and TAG equality rules dictate that at least parts of
+these URIs are case-sensitive, so it is best to consider the configured name
+case-sensitive entirely.
+
+The [[setting,sieve_extlists_list]] filter refers to this setting.`
+	},
+
+	sieve_extlists_list_max_lookup_size: {
+		tags: [ 'sieve', 'sieve-extlists' ],
+		plugin: 'sieve',
+		values: setting_types.SIZE,
+		default: '1k',
+		seealso: [ '[[link,sieve_extlists]]' ],
+		text: `
+The maximum size of a value looked up from this Sieve extlists list. If the
+value is too large, the lookup will be skipped and will yield no result. Note
+that individual lists may have different limits, meaning that lookups in other
+lists may still succeed.`
+	},
+
 	sieve_notify_mailto_envelope_from: {
 		tags: [ 'sieve', 'sieve-enotify' ],
 		plugin: 'sieve',

docs/core/config/sieve/extensions/extlists.md

@@ -0,0 +1,81 @@
+---
+layout: doc
+title: Extlists
+dovecotlinks:
+  sieve_extlists: Sieve extlists extension
+---
+
+# Sieve: Extlists Extension
+
+The extlists extension ([[rfc,6134]]) enables Sieve scripts to check membership
+of a value in an external list or for redirecting messages to an external list
+of recipients. An "external list" is a list whose members are stored externally
+to the Sieve script. This extension adds a new ":list" match type to apply to
+supported tests and it can be be used to implement email whitelisting,
+blacklisting, addressbook lookups, and other sorts of list matching.
+
+For Dovecot, the external list is always implemented using a dict lookup.
+Redirecting messages to a list of recipients as described in the standard
+([[rfc,6134]]) is currently not implemented in Dovecot and will always trigger
+an error if used.
+
+## Configuration
+
+The extlists extension is not available by default and needs to be
+enabled explicitly by adding it to [[setting,sieve_extensions]].
+
+### Settings
+
+<SettingsComponent tag="sieve-extlists" level="3" />
+
+### Example
+
+```
+# Use extlists
+sieve_extensions {
+  extlists = yes
+}
+
+# No value looked up from a list may exceed 512 bytes, or it will forcibly not
+# match
+sieve_extlists_list_max_lookup_size = 512
+
+# The default addressbook stored in a proxied dict
+sieve_extlists_list :addrbook:default {
+  dict proxy {
+    name = addressbook
+  }
+}
+
+sieve_extlists_list tag:example.com,2025-02-26:BadFileExts {
+  dict proxy {
+    name = bad_file_extensions
+  }
+
+  # Limit lookups to 10 bytes
+  max_lookup_size = 10B
+}
+
+```
+
+## Sieve Example
+
+The following example excludes senders listed in the user's default address book
+from Spam filtering. The example demonstrates the use of the
+[[link,sieve_spamtest,spamtest extension]] as well.
+
+```
+require ["envelope", "extlists", "fileinto", "spamtest",
+         "relational", "comparator-i;ascii-numeric"];
+
+if allof( not envelope :list "from" ":addrbook:default",
+	  spamtest :value "ge" :comparator "i;ascii-numeric" "3" ) {
+  fileinto "spam";
+}
+```
+
+
+
+
+
+

docs/core/config/sieve/overview.md

@@ -56,6 +56,7 @@ The interpreter recognizes the following Sieve extensions:
 | <code>[[link,sieve_enotify,enotify]]</code> ([[rfc,5435]]) | **yes** | Provides the ability to send notifications by various means (currently only mailto) |
 | `envelope` ([[rfc,5228,5.4]]) | **yes** | Allows evaluating envelope parts, i.e. sender and recipient |
 | `environment` ([[rfc,5183]]) | **yes** | Allows testing against various labeled values from the execution environment |
+| <code>[[link,sieve_extlists,extlists]]</code> ([[rfc,6134]]) | no | Allows looking up and matching values from external lists (dict lookup) |
 | `extracttext` ([[rfc,5703,7]]) | **yes** | Allows extracting text from individual message MIME parts |
 | `fileinto` ([[rfc,5228,4.1]]) | **yes** | Allows storing messages in folders other than INBOX |
 | `foreverypart` ([[rfc,5703,3]]) | **yes** | Allows iterating through the message's MIME parts |