fix(smtp): the EMAIL and DIRECT TLS hops were encrypted but unauthenticated (#323, layers 1-2)

smtplib takes no context by default and falls back to ssl._create_stdlib_context, which IS
ssl._create_unverified_context -- measured on this project's required interpreter (CPython
3.14.6): verify_mode=CERT_NONE, check_hostname=False. So use_tls=true bought encryption
without authentication on every SMTP send, and any certificate was accepted.

That is worse than a plain gap because three shipped controls asserted the opposite:

  * transports/email.py registered a RevocationHopGuard on the hop, whose own definition in
    tls_policy.py says "the caller has already built a verifying context". An enforcing
    production-PHI instance therefore REFUSED TO START over a possibly-REVOKED certificate,
    on a hop that never validated a certificate at all.
  * the same file's comment claimed STARTTLS/SMTP_SSL "verifies the server cert".
  * the AUTH refusal keyed only on use_tls=false, so with TLS "on" the password went over
    the unauthenticated hop.

WHAT LANDS (2 of the 3 cells):

  config/tls_policy.py  build_smtp_tls_context() -- the shared verifying-context factory,
    mirroring remotefile.py's _ftps_ssl_context step for step (TLS 1.2 floor, harden_kex_groups,
    harden_cipher_suites, harden_verify_flags on the verify path). It lives in config/ rather
    than transports/ because pipeline/alert_sinks.py is the third caller and a transport must
    not import pipeline/ (ADR 0029's one-way rule).
  transports/email.py, transports/direct.py  a three-arm branch (cleartext / verify-off /
    verifying) and context= on both smtplib arms. The verify-off arm refuses unless the
    CLAMPED weakened_tls_escape_permitted_here() allows it, and refuses AUTH outright.
  config/wiring.py  tls_verify / tls_ca_file / tls_check_hostname on Email() and Direct().

Trust config, not verification-off, is the escape: [tls].internal_ca_file is ALREADY threaded
onto every Destination and was simply never read here, so an estate that pinned its internal CA
for MLLP/FTPS needs no change at all.

SEPARABLE FIX, called out rather than folded in silently: direct.py's cleartext arm read the
UNCLAMPED insecure_tls_allowed() while its sibling one branch away read the clamped form. It now
reads the clamped one -- strictly ADDS refusals (ADR 0092 decision 5). Partially closes #329.

VERIFICATION -- the part that matters. The pre-existing tests asserted "STARTTLS was issued",
which was true the whole time it was insecure; that assertion could never have caught this. The
eight new tests assert the CONTEXT (CERT_REQUIRED, check_hostname, TLS1.2 floor, CERT_NONE only
under the escape, the clamp under enforcing PHI, and that a per-connection CA pins to ONLY that
CA). Negative control run: with the code change stashed and the tests kept, all eight go RED.
ruff + format clean; mypy unchanged at its 21-error pre-existing baseline (missing pynetdicom /
webauthn extras, none in touched files); 437 targeted tests green.

DELIBERATELY NOT DONE -- the alerts cell (pipeline/alert_sinks.py:384) still calls starttls()
bare. It needs an acknowledgment switch rather than the clamp, because the contextvar hop posture
is never stamped for that cell. Tracked as the residual on #323. #139's "verifying context by
design" claim therefore remains FALSE and is not corrected here.

BLOCKED, needs one follow-up commit: adding `ssl` to transports/{email,direct}.py reds the
required crypto-inventory gate until scripts/security/crypto_inventory_check.py documents it.
That file is checked out live in another session; the collision gate refused the edit and I
asked that session for the two lines rather than clobbering their work. docs/BACKLOG.md (#323's
banner, #139) is held by two other sessions for the same reason.

Author: wshallwshall

messagefoundry/config/tls_policy.py

@@ -62,6 +62,7 @@
     "TrustAnchorMode",
     "TrustAnchorPolicy",
     "active_hop_posture",
+    "build_smtp_tls_context",
     "build_verifying_client_context",
     "cleartext_acceptance_audit_sink",
     "current_hop_posture",
@@ -919,3 +920,61 @@ def build_verifying_client_context(
         return ctx
     # pinned / per-connection: ONLY this CA (no load_default_certs), matching forward_tls_ca_file.
     return ssl.create_default_context(purpose, cafile=anchor.cafile)
+
+
+def build_smtp_tls_context(
+    *,
+    host: str,
+    cell: str,
+    verify: bool = True,
+    ca_file: str | None = None,
+    check_hostname: bool = True,
+    trust_anchor_policy: TrustAnchorPolicy | None = None,
+) -> ssl.SSLContext:
+    """Build the TLS context for an outbound SMTP hop (#323) — STARTTLS or implicit ``SMTP_SSL``.
+
+    ``smtplib`` accepts no context by default, and its fallback is
+    :func:`ssl._create_stdlib_context`, which **is** ``ssl._create_unverified_context`` — measured on
+    CPython 3.14.6: ``verify_mode=CERT_NONE``, ``check_hostname=False``. So every certificate was
+    accepted and the encrypted session was unauthenticated: an on-path attacker presenting any
+    certificate read the message body (PHI) and the SMTP AUTH credential. This is the SMTP sibling of
+    :func:`~messagefoundry.transports.remotefile._ftps_ssl_context` and the MLLP outbound arm, and is
+    deliberately built here rather than in ``transports/`` because ``pipeline/alert_sinks.py`` is a
+    third caller and a transport must not import ``pipeline/`` (ADR 0029's one-way rule).
+
+    ``verify=False`` is NOT gated here — the caller refuses it against the clamped
+    :func:`~messagefoundry.config.settings.weakened_tls_escape_permitted_here` first, matching how
+    MLLP/FTPS inline that check. This module cannot read it: ``config.settings`` imports *from* here,
+    so the dependency runs one way only.
+
+    ``trust_anchor_policy`` (#190, ADR 0093) supplies the instance ``[tls]`` internal-CA fallback when
+    the connection names no ``ca_file`` of its own. It only chooses WHICH roots verify the peer — it
+    never turns verification off.
+    """
+    if verify:
+        anchor = resolve_trust_anchor(
+            connection_ca_file=ca_file,
+            host=host,
+            policy=trust_anchor_policy if trust_anchor_policy is not None else TrustAnchorPolicy(),
+        )
+        ctx = build_verifying_client_context(anchor)
+    else:
+        ctx = ssl.create_default_context(ssl.Purpose.SERVER_AUTH, cafile=ca_file)
+    ctx.minimum_version = ssl.TLSVersion.TLSv1_2
+    if verify:
+        ctx.check_hostname = check_hostname
+    else:
+        logger.warning(
+            "%s TLS certificate verification is DISABLED (tls_verify=false) — the SMTP session to %s "
+            "is encrypted but UNAUTHENTICATED and MITM-able; trusted-network dev/test only.",
+            cell,
+            host,
+        )
+        # Order is load-bearing: check_hostname must go False BEFORE verify_mode, or ssl raises.
+        ctx.check_hostname = False
+        ctx.verify_mode = ssl.CERT_NONE
+    harden_kex_groups(ctx)  # pin approved ECDHE groups where supported (ASVS 11.6.2)
+    harden_cipher_suites(ctx, connector=cell)  # assert forward secrecy (ASVS 12.1.2)
+    if verify:  # nothing to strict-validate on the CERT_NONE path (ASVS 12.1.4)
+        harden_verify_flags(ctx)
+    return ctx

messagefoundry/config/wiring.py

@@ -1785,6 +1785,9 @@ def Email(
     username: str | EnvRef | None = None,  # optional SMTP AUTH user (use env() for the secret)
     password: str | EnvRef | None = None,  # optional SMTP AUTH password (use env() for the secret)
     use_tls: bool = True,  # STARTTLS by default; False (dev only) needs MEFOR_ALLOW_INSECURE_TLS
+    tls_verify: bool = True,  # verify the server cert (#323); False (dev only) needs the escape
+    tls_ca_file: str | EnvRef | None = None,  # PEM to verify the SMTP server against (not a secret)
+    tls_check_hostname: bool = True,  # match the cert against `host` (leave on)
     timeout_seconds: float = 30.0,
     encoding: str = "utf-8",
 ) -> ConnectionSpec:
@@ -1793,9 +1796,18 @@ def Email(
     text); this delivers it as a plain-text SMTP message to ``host:port`` from ``sender`` to
     ``recipients`` with a static ``subject``. STARTTLS by default (``use_tls=True``) on the ``587``
     submission port; port ``465`` is implicit TLS (``SMTP_SSL``). Optional ``username``/``password`` do
-    SMTP ``AUTH`` (over TLS only — a cleartext-credential config is refused). Disabling TLS
-    (``use_tls=False``) is MITM-able and refused unless ``MEFOR_ALLOW_INSECURE_TLS`` is set (loud
-    warning), like LDAPS / SQL Server / MLLP. The egress host is gated by ``[egress].allowed_smtp``. Put
+    SMTP ``AUTH`` (over a **verified** TLS session only — a cleartext- or unverified-credential config
+    is refused). Disabling TLS (``use_tls=False``) is MITM-able and refused unless
+    ``MEFOR_ALLOW_INSECURE_TLS`` is set (loud warning), like LDAPS / SQL Server / MLLP.
+
+    **The server certificate is verified** (``tls_verify=True``, #323) — chain, hostname and strict RFC
+    5280 flags, anchored to the OS roots, a per-connection ``tls_ca_file``, or the instance-wide
+    ``[tls].internal_ca_file`` (ADR 0093). ``smtplib``'s own default context verifies **nothing**
+    (``CERT_NONE``/``check_hostname=False``), so before #323 ``use_tls=True`` bought encryption without
+    authentication. Point ``tls_ca_file`` at your relay's CA PEM for a private-CA server;
+    ``tls_verify=False`` is a trusted-network dev/test escape, refused on an enforcing production-PHI
+    instance even with ``MEFOR_ALLOW_INSECURE_TLS``, and it also refuses SMTP ``AUTH``.
+    The egress host is gated by ``[egress].allowed_smtp``. Put
     secrets in ``env()`` (``username``/``password``), never inline. Delivery is at-least-once, so a retry
     re-sends the email — a mailbox has no idempotency key, so a rare duplicate is possible and accepted
     (a duplicate beats a drop). ADR 0029."""
@@ -1810,6 +1822,9 @@ def Email(
             "username": username,
             "password": password,
             "use_tls": use_tls,
+            "tls_verify": tls_verify,
+            "tls_ca_file": tls_ca_file,
+            "tls_check_hostname": tls_check_hostname,
             "timeout_seconds": timeout_seconds,
             "encoding": encoding,
         },
@@ -1836,6 +1851,9 @@ def Direct(
     username: str | EnvRef | None = None,  # optional SMTP AUTH user (use env() for the secret)
     password: str | EnvRef | None = None,  # optional SMTP AUTH password (use env() for the secret)
     use_tls: bool = True,  # STARTTLS by default; False (dev only) needs MEFOR_ALLOW_INSECURE_TLS
+    tls_verify: bool = True,  # verify the relay's cert (#323); False (dev only) needs the escape
+    tls_ca_file: str | EnvRef | None = None,  # PEM to verify the SMTP/HISP relay against
+    tls_check_hostname: bool = True,  # match the cert against `host` (leave on)
     timeout_seconds: float = 30.0,
     encoding: str = "utf-8",
 ) -> ConnectionSpec:
@@ -1844,7 +1862,14 @@ def Direct(
     **body** (content-agnostic — an HL7 string, a CDA/XML document, plain text); this **signs** it with
     ``signing_key``/``signing_cert``, **encrypts** the signed blob to the partner's ``recipient_cert``
     (which must chain to ``trust_anchor``), and submits the S/MIME message to ``host:port`` over
-    STARTTLS. All cert/key material is loaded + validated at construction (fail loud). The egress host
+    STARTTLS. All cert/key material is loaded + validated at construction (fail loud).
+
+    **The relay's TLS certificate is verified** (``tls_verify=True``, #323 — ``smtplib``'s own default
+    verifies nothing). Note the two trust settings are unrelated and easy to confuse: ``trust_anchor``
+    is the CA the **partner's S/MIME certificate** must chain to (message-layer), while ``tls_ca_file``
+    is the CA the **SMTP relay's TLS certificate** must chain to (transport-layer). The S/MIME body
+    protects the clinical payload either way, but the SMTP session still carries envelope metadata and
+    any ``AUTH`` credential, which is why the transport hop is verified too. The egress host
     is gated by ``[egress].allowed_direct``. Put secrets in ``env()`` (``signing_key_password``,
     ``username``/``password``), never inline. Delivery is at-least-once, so a retry re-sends — a Direct
     mailbox has no idempotency key, so a rare duplicate is possible and accepted (a duplicate beats a
@@ -1865,6 +1890,9 @@ def Direct(
             "username": username,
             "password": password,
             "use_tls": use_tls,
+            "tls_verify": tls_verify,
+            "tls_ca_file": tls_ca_file,
+            "tls_check_hostname": tls_check_hostname,
             "timeout_seconds": timeout_seconds,
             "encoding": encoding,
         },

messagefoundry/transports/direct.py

@@ -46,6 +46,7 @@
 import asyncio
 import logging
 import smtplib
+import ssl
 from collections.abc import Mapping
 from email.message import EmailMessage
 from pathlib import Path
@@ -57,7 +58,11 @@
 from cryptography.hazmat.primitives.serialization import pkcs7
 
 from messagefoundry.config.models import ConnectorType, Destination
-from messagefoundry.config.settings import INSECURE_TLS_ESCAPE_ENV, insecure_tls_allowed
+from messagefoundry.config.settings import (
+    INSECURE_TLS_ESCAPE_ENV,
+    weakened_tls_escape_permitted_here,
+)
+from messagefoundry.config.tls_policy import build_smtp_tls_context
 from messagefoundry.transports.base import (
     DeliveryError,
     DeliveryResponse,
@@ -140,6 +145,13 @@ def __init__(self, config: Destination) -> None:
         self.username: str | None = str(username) if username else None
         self.password: str | None = str(password) if password else None
         self.use_tls = bool(s.get("use_tls", True))
+        # #323: server-certificate verification on the TLS hop, kept byte-identical to
+        # EmailDestination's spelling (this connector's SMTP core is a deliberate copy, not an import —
+        # the one-way dependency rule — so the two must not drift).
+        self.tls_verify = bool(s.get("tls_verify", True))
+        tls_ca_file = s.get("tls_ca_file")
+        self.tls_ca_file: str | None = str(tls_ca_file) if tls_ca_file else None
+        self.tls_check_hostname = bool(s.get("tls_check_hostname", True))
         self.timeout: float = float(s.get("timeout_seconds", 30.0))
         self.encoding: str = str(s.get("encoding", "utf-8"))
 
@@ -167,11 +179,16 @@ def __init__(self, config: Destination) -> None:
         # SMTP is refused unless the project-wide dev escape is set, and credentials are NEVER sent over
         # a cleartext channel.
         if not self.use_tls:
-            if not insecure_tls_allowed():
+            # #323: read through the CLAMPED escape, not the raw insecure_tls_allowed(). This call site
+            # was the last unclamped one in the file, sitting one branch away from the clamped arm
+            # below — two different escapes in one connector is how the next bug gets written. The
+            # change strictly ADDS refusals (ADR 0092 decision 5): an enforcing production-PHI instance
+            # can no longer silence a cleartext Direct hop with the blunt process-wide env var.
+            if not weakened_tls_escape_permitted_here():
                 raise ValueError(
                     "Direct destination use_tls=false submits over cleartext SMTP; refused unless "
-                    f"{INSECURE_TLS_ESCAPE_ENV} is set (dev/trusted-network only) — use STARTTLS "
-                    "(the default)"
+                    f"{INSECURE_TLS_ESCAPE_ENV} is set (dev/trusted-network only, and refused on a "
+                    "production-PHI instance even with the escape, #200) — use STARTTLS (the default)"
                 )
             if self.username is not None:
                 raise ValueError(
@@ -183,6 +200,40 @@ def __init__(self, config: Destination) -> None:
                 "network in CLEARTEXT (dev/trusted-network only)",
                 self.host,
             )
+        elif not self.tls_verify:
+            # #323 arm 2 — same shape and wording as EmailDestination's, deliberately.
+            if not weakened_tls_escape_permitted_here():
+                raise ValueError(
+                    "Direct destination tls_verify=false disables server-certificate verification on "
+                    f"the SMTP hop to {self.host} — the session is encrypted but UNAUTHENTICATED. The "
+                    "S/MIME body still protects the clinical payload, but envelope metadata and any "
+                    "SMTP AUTH credential are exposed to an on-path attacker presenting any "
+                    "certificate. Use a trusted CA (tls_ca_file, or [tls].internal_ca_file for the "
+                    f"instance), or set {INSECURE_TLS_ESCAPE_ENV}=1 to allow it on a trusted-network "
+                    "bind (refused on a production-PHI instance even with the escape, #200)."
+                )
+            if self.username is not None:
+                raise ValueError(
+                    "Direct destination sends SMTP AUTH credentials over an UNVERIFIED TLS session "
+                    "(tls_verify=false); refused — credentials require a verified TLS session"
+                )
+        # Built once at construction (fail-fast), reused by every send. None when TLS is off entirely.
+        # DIRECT does not take a RevocationHopGuard even though the hop now verifies: adding it would
+        # make the enumerated count eight and force four "seven verifying hops" docs to change, and the
+        # clinical payload is S/MIME-protected at the message layer so the PHI argument is materially
+        # weaker than EMAIL's (ADR 0085). Recorded rather than silently omitted.
+        self._tls_context: ssl.SSLContext | None = (
+            build_smtp_tls_context(
+                host=self.host,
+                cell="Direct destination",
+                verify=self.tls_verify,
+                ca_file=self.tls_ca_file,
+                check_hostname=self.tls_check_hostname,
+                trust_anchor_policy=config.trust_anchor_policy,
+            )
+            if self.use_tls
+            else None
+        )
 
     def _load_private_key(self, value: Any, password: Any) -> Any:
         """Load the sender's signing private key (PEM/DER, optionally passphrase-protected). PHI/secret-
@@ -317,10 +368,13 @@ def _connect(self) -> smtplib.SMTP:
         """Open an SMTP connection, applying STARTTLS / implicit TLS per config (identical posture to
         EmailDestination). The caller closes it (``with`` / ``quit``)."""
         if self.port == 465 and self.use_tls:
-            return smtplib.SMTP_SSL(self.host, self.port, timeout=self.timeout)
+            # context= is REQUIRED (#323) — SMTP_SSL's own default is an unverified stdlib context.
+            return smtplib.SMTP_SSL(
+                self.host, self.port, timeout=self.timeout, context=self._tls_context
+            )
         smtp = smtplib.SMTP(self.host, self.port, timeout=self.timeout)
         if self.use_tls:
-            smtp.starttls()
+            smtp.starttls(context=self._tls_context)
         return smtp
 
     def _send(self, payload: str) -> None: