Research enforceable minimum Email and recipient requirements through existing overrides (ADR)

[bbottema]

Why

Organizations may need a message policy that application-created emails cannot weaken: for example, every message sent through a configured Mailer must request REQUIRETLS for onward SMTP delivery. Individual emails should still be able to ask for stronger protection.

This is useful for enterprise applications where operations or security teams configure requirements through properties/Spring instead of relying on every application call site to remember them. It supports that use case with a concrete, predictable contract rather than another collection of feature switches.

REQUIRETLS is the lead-in, but the architectural question is broader: which existing Email and recipient settings make sense as enforceable requirements, and how should users express those requirements without learning a second configuration API?

Target: resolve this research and ADR before the 10.0.0 release. Deliver an ADR and a reviewed API proposal first; implementation remains subject to that review.

Starting point: reuse Email overrides

withEmailOverrides(...) already centralizes message configuration. It is not currently enforceable against per-message choices:

• A submitted Email can suppress overrides with ignoringOverrides(...) or dontApplyOverrideValueFor(...).
• Explicit recipient settings, such as S/MIME certificates, can take precedence over Email-level overrides.
• Exact EML follows a separate preparation path that bypasses Email defaults/overrides.
• Single values, collections, headers, and compound configurations have different resolution rules. An override is not always replacement, and replacement is not always a stronger security requirement.

These are existing contracts, not defects to silently change.

Do not introduce a parallel set of setters such as withRequiredRelayTlsForAllEmails(), withSigningForAllEmails(), etc. Start from the existing overrides Email as the policy declaration and investigate a small, centralized opt-in enforcement control, configurable through a single property as well as the normal Java/Spring configuration paths. Prefer that reuse over a second builder mirroring Email.

The exact API/property names, eligible fields, and whether enforcement needs field selection remain design questions. Turning enforcement off must preserve existing behavior; turning it on must have a clearly defined scope rather than silently changing the meaning of every override.

Inventory the existing API

Audit composed/exact Email, Recipient and Recipients builders, their copying/default/override/clear/suppression paths, and the relevant provider/module boundaries. Produce a candidate matrix, including useful non-candidates, rather than assuming every field belongs in this doctrine.

Starting areas to examine, not a list of promised features:

• REQUIRETLS: a message-wide requirement, distinct from TLS on the application-to-SMTP-server connection. Requiring it for all sends is the motivating example.
• DKIM and S/MIME signing: requiring a signature versus fixing the signing identity, key, or algorithm.
• S/MIME and OpenPGP encryption/signing: requiring protection and adequate recipient coverage versus replacing recipient keys/certificates or selecting a particular protection family. Do not assume algorithms or protection families have a universal stronger/weaker ordering.
• DSN policy: determine whether notification choices have meaningful enforceable semantics at all; NEVER and event sets are not an obvious security hierarchy.
• Sender, envelope, header, and recipient configuration: distinguish a useful fixed-value rule or required addition from an ordinary content override, an additive collection, or a rule that needs a different abstraction.

For each candidate, record the application use case, current owner and precedence, policy kind (minimum / fixed choice / required addition / unsuitable), configuration representation, satisfaction test, and enforcement limitations.

Questions the ADR must settle

1. Minimum versus fixed override. How can a message strengthen a requirement without being rewritten to a weaker template value? Which fields require exact matching, and which have no sensible minimum? Avoid blindly merging compound security configurations.
2. Ergonomic policy configuration. Can the existing overrides template plus one opt-in enforcement setting express the common cases? If selective enforcement is necessary, keep it small and explain why. Define what the property controls, where the actual policy values come from, and how immutable configuration snapshots, explicit templates, and Spring interact. Do not create a duplicate feature API or a general-purpose rules language by default.
3. Suppression and conflicts. Specify the behavior of explicit disabling, clearing, ignoringDefaults, ignoringOverrides, per-property suppression, and already-completed/copied Emails. Decide when to apply a requirement versus reject an incompatible choice; never silently send with weaker protection.
4. Recipient boundaries. Preserve recipient identity and correct keys/certificates. Requiring encryption for every recipient is not the same as replacing every recipient's certificate with the Email fallback. Define group-fixed values, duplicate recipients, and Email/recipient conflicts without assuming message splitting or a new recursive configuration tree.
5. Exact and protected messages. Envelope-only requirements may be satisfiable without changing MIME bytes. Content/signature requirements need a way to establish compliance or reject an incompatible/opaque message; enforcement must not quietly invalidate signatures or abandon exact-byte preservation.
6. Execution boundaries. Define consistent treatment across synchronous/asynchronous sends, batches, open connections, validation, and rehearsal. Separate locally checkable requirements from capabilities confirmed on the actual send connection. Define limitations or rejection behavior for caller-owned Sessions, custom mailers, and third-party providers rather than reporting enforcement that could not be verified.
7. Errors and diagnostics. Explain which requirement failed, where the policy came from, and what the caller/operator can change, without exposing secrets. Distinguish configured policy, its effective application, and facts actually observed during submission.
8. Trust boundary. Enforcement concerns sends through the configured Mailer; a Java library cannot stop application code from constructing another Mailer, changing configuration, or using another transport. Organization-wide enforcement may also require submission-server/network controls. Do not describe this as a security sandbox or proof of downstream compliance.

Deliverables / acceptance criteria

• Inventory the current Email/recipient API and publish the candidate matrix with rationale, including exclusions.
• Compare the small override-enforcement design with necessary alternatives; show concise Java and property/Spring examples for a normal default, an enforced minimum, a stronger per-email choice, and a conflict.
• Write the ADR, explicitly relating it to ADR 0001/0002 and identifying any superseded decisions. Do not rewrite their historical contracts as if enforcement already existed.
• Define precedence, opt-in compatibility, exact-message/provider boundaries, failure behavior, and a verification matrix covering bypass attempts and per-send isolation.
• Review the proposal before creating implementation work. Follow the API expansion workflow and coding guide for any subsequent implementation.

References and related work

• ADR 0001: Email configuration scopes and inheritance
• ADR 0002: Email defaults and overrides
• #737: shared DKIM/S/MIME configuration and #738: recipient DSN policy: preserve the recently agreed scope and reuse principles.
• Planned per-message REQUIRETLS, within #722. This research does not automatically expand that plan or reopen completed work.
• RFC 8689: protocol context for the motivating requirement.
• #739: additional SMTP delivery-policy research: related exploration, not the scope of this ADR.