Merge commit from fork

With [smtp] ssl = False (the default) or [imap] ssl = False, mailsuite
upgraded the connection only if the server's plain-text EHLO/CAPABILITY
reply advertised STARTTLS, and otherwise authenticated in plain text. An
on-path attacker who stripped STARTTLS received the credentials and the
emailed results (CWE-319).

- Require mailsuite >= 2.3.4 (GHSA-2x4j-7g3q-wr6f), whose default
  refuses to authenticate over a connection that was not upgraded.
- Add [imap] and [smtp] starttls (unset = require STARTTLS; false =
  explicit plain-text opt-out, for loopback servers such as DavMail),
  with a startup warning when the opt-out is set and ssl is False.
- Add a starttls argument to email_results().
- Document both options; set starttls = False in the DavMail example.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

docs/source/davmail.md

@@ -183,7 +183,16 @@ config file:
 host=127.0.0.1
 port=1143
 ssl=False
+starttls=False
+
+[mailbox]
 watch=True
 ```
 
+The DavMail configuration above runs its IMAP listener without TLS
+(`davmail.ssl.nosecureimap=true`), so parsedmarc refuses to log in unless
+`starttls=False` allows plain-text authentication. Only set it when DavMail
+listens on the loopback address only (`davmail.bindAddress=127.0.0.1` and
+`davmail.allowRemote=false`, as above).
+
 [modern auth/multi-factor authentication]: https://davmail.sourceforge.net/faq.html

docs/source/usage.md

@@ -319,8 +319,19 @@ The full set of configuration options is:
     If your host recommends another port, still try 993
     :::
 
-  - `ssl` - bool: Use an encrypted SSL/TLS connection
-      (Default: `True`)
+  - `ssl` - bool: Use an encrypted SSL/TLS connection from the start
+      (implicit TLS, usually port 993) (Default: `True`). When `False`,
+      the connection starts in plain text and must be upgraded with
+      STARTTLS before logging in (usually port 143); see `starttls`.
+  - `starttls` - bool: Whether to upgrade a plain-text (`ssl = False`)
+      connection with STARTTLS. When unset (the default), the connection
+      is upgraded if the server advertises STARTTLS, and parsedmarc
+      refuses to log in if it does not, so the credentials are never sent
+      in plain text. `true` always requires the upgrade. `false` never
+      upgrades, even when the server advertises STARTTLS, so the
+      credentials and messages are sent in plain text; use it only for a
+      server on the same host, such as [DavMail](davmail.md) on the
+      loopback address. Ignored when `ssl = True`.
   - `skip_certificate_verification` - bool: Skip certificate
       verification (not recommended)
   - `timeout` - int: Number of seconds to wait for an IMAP operation
@@ -679,8 +690,21 @@ The full set of configuration options is:
     configured, in which case omitting it sends the summary via
     Microsoft Graph instead — see "Sending the summary email via
     Microsoft Graph" above.
-  - `port` - int: The SMTP port (Default: `25`)
-  - `ssl` - bool: Require SSL/TLS instead of using STARTTLS
+  - `port` - int: The SMTP port (Default: `25`). Usually `587` for
+    STARTTLS, or `465` with `ssl = True`.
+  - `ssl` - bool: Use an encrypted SSL/TLS connection from the start
+    (implicit TLS, usually port 465) (Default: `False`). When `False`,
+    the connection starts in plain text and must be upgraded with
+    STARTTLS before authenticating; see `starttls`.
+  - `starttls` - bool: Whether to upgrade a plain-text (`ssl = False`)
+    connection with STARTTLS. When unset (the default), the connection
+    is upgraded if the server advertises STARTTLS, and parsedmarc
+    refuses to authenticate if it does not, so the credentials are never
+    sent in plain text ("Failed to email results" is logged). `true`
+    always requires the upgrade. `false` never upgrades, even when the
+    server advertises STARTTLS, so the credentials and the results
+    email are sent in plain text; use it only for a server on the same
+    host. Ignored when `ssl = True`.
   - `skip_certificate_verification` - bool: Skip certificate
     verification (not recommended)
   - `user` - str: the SMTP username. SMTP-only; not used when sending