fix(mailing): send real HTML with a text alternative, not bare text

[marcelo-maciel]

Carries two infrastructure fixes that are not this PR's topic. Without them CI cannot even reach this PR's code.

• Dependency bump: Microsoft.SourceLink.GitHub to 10.0.401 and Testcontainers to 4.14.0, clearing NU1902/NU1903 so restore succeeds. Those are the versions #1375 (SourceLink) and #1369 (Testcontainers) carry: this hunk is the union of the two, plus one comment per pin naming the advisory it answers.
• MinIO (8129527a): minio/minio is gone from Docker Hub, so every Testcontainers-backed integration test dies on the image pull. Pulls from quay.io on a pinned tag instead. Same fix as #1388.

The MinIO hunk is byte-identical to #1388. The dependency hunk is not byte-identical to #1375 or #1369, which each carry half of it without the comments, but it is identical across all twelve PRs in this series: src/Directory.Packages.props resolves to the same blob (854deb95) at every head. Either way they merge in any order, and these copies can be dropped once the PRs that own them land.

Reopened from #1351. That PR was closed automatically on 2026-09-14, when the head fork
was deleted. It reopened at bada7cee, and review has added commits on top since then (the
commit list above is the current one). The earlier review history stays on #1351.

---

Problem

Every mail provider in the kit puts MailRequest.Body in the HTML slot:

// SmtpMailService
var builder = new BodyBuilder { HtmlBody = request.Body };

// SendGridMailService
MailHelper.CreateSingleEmail(from, to, request.Subject, request.Body, request.Body);
//                                                      ^ plainText   ^ html — the same string

But two callers pass plain text into it:

• UserPasswordService.ForgotPasswordAsync — $"Please reset your password using the following link: {resetPasswordUri}"
• UserRegisteredEmailHandler — $"Hi {@event.FirstName}, thanks for registering."

A bare URL inside a text/html part is not auto-linked by most clients (auto-linking is text/plain behaviour), so the password-reset link arrives as dead text and the user cannot complete the flow. I hit this on a real deployment: the reset mail landed with the URL unclickable.

Two more consequences of the same root cause:

• The welcome mail interpolates FirstName — user-supplied — straight into markup. A name containing < breaks the message; it is an HTML injection into the rendered mail.
• SendGrid received Body as both parts, so the confirmation and billing templates were shipped as the text/plain alternative too: a text-only client rendered raw markup.

The confirmation mail (BuildConfirmationEmailHtml) and the billing bodies were already HTML with escaping, so the defect this PR fixes is the inconsistency rather than the templates. Two caveats review was right to add: the billing escaper covers only & < >, and amountText (which embeds currency) reaches the markup unescaped. Neither is exploitable today — currency is NotEmpty().Length(3) behind BillingPermissions.Manage, and three characters in element content are not a payload — but "already correct" was too strong. #1385 is what actually fixes both.

Solution

MailRequest gains an optional TextBody (appended last, so existing positional calls keep compiling):

• SmtpMailService sets both HtmlBody and TextBody → MailKit emits multipart/alternative.
• SendGridMailService maps TextBody → plainTextContent and Body → htmlContent, instead of sending the HTML as both.
• New EmailBodies helper in Identity (LinkActionHtml, NoticeHtml) renders the action link as a real <a href> and HTML-encodes every interpolated value.
• Reset, confirmation, welcome and the four billing mails now all carry a text/plain twin, so nothing goes out HTML-only.

Note for reviewers: inside HTML the query separator is &, so the reset URL in the HTML part reads ...?token=…&email=…&tenant=…. That is correct per the HTML spec — the browser hands & to the server. The verbatim URL lives in TextBody, which is where the existing link-shape test now asserts.

Changes to src/BuildingBlocks (Golden Rule #4, requesting sign-off)

• Mailing/MailRequest.cs — new optional TextBody property + XML docs stating that Body is HTML.
• Mailing/Services/SmtpMailService.cs — one line: TextBody on the BodyBuilder.
• Mailing/Services/SendGridMailService.cs — plainTextContent now comes from TextBody.

No behaviour change for a caller that does not set TextBody, except on SendGrid, where the text part becomes absent instead of being a copy of the markup.

Tests

• UserPasswordServiceTests — the reset link is a real anchor; & in the HTML part; a text alternative exists, carries the verbatim URL and no markup. The pre-existing link-shape test (single slash, tenant, %2B encoding) now asserts on TextBody.
• UserRegisteredEmailHandlerTests (new) — a first name of <script>alert(1)</script> comes out encoded; the text alternative is present; nothing is sent when the event carries no e-mail.
• SendGridMailServiceTests — the two bodies land in their own MIME parts (text/html / text/plain).
• MailRequestTests — TextBody round-trips and defaults to null.

Verified locally on the pushed tree, with the NuGet audit on rather than disabled:

• dotnet restore src/FSH.Starter.slnx: exit 0, zero NU1903.
• dotnet build -warnaserror: exit 0.
• Full suite: 14 assemblies, 1806 passed / 0 failed / 1 skipped, including Integration at 746 passed / 1 skipped against a real Postgres (Testcontainers).

That closes the gap left in the earlier description, which said the integration suite would not run here and leaned on CI for it. The fault was local and is cleared; the suite ran end to end this time. It remains true that no integration test exercises the mail path itself — the harness does not run enqueued mail jobs — so the mail assertions are the unit tests listed above.

Rebased on main, and the SSH.NET pin

This branch was CONFLICTING. main has since added the System.Security.Cryptography.Xml 10.0.10 pin that this PR was carrying, which was the only conflict. Resolved by keeping main's version, so this PR no longer touches that pin at all — one less shared-config edit to review.

The remaining red was a different advisory, NU1903 / GHSA-q939-rpr3-3284 on SSH.NET 2025.1.0, pulled transitively by Testcontainers. This branch carried an explicit pin for it; review showed the pin was dead once Testcontainers moved to 4.14.0, which declares SSH.NET >= 2026.0.0, so the pin has been removed and the bump alone clears the advisory (measured: dotnet restore --force, zero NU1902/NU1903, exit 0).

---

Infra carve-outs, corrected after review. Two things in the out-of-topic hunks were wrong and
are fixed on the branch:

• The MinIO carve-out only moved minio/minio to quay.io. minio/mc is gone from Docker Hub too
  (hub.docker.com/v2/repositories/minio/mc/ answers 404) and it is what minio-init runs, so both
  dotnet run --project src/Host/FSH.Starter.AppHost and docker compose up died on the pull and the
  fsh bucket was never created. Now pinned to the same quay tag #1388 uses.
• The SSH.NET pin is gone: it pinned nothing. Its own comment claimed bumping Testcontainers
  does not help, but 4.14.0 — which this branch also carries — declares SSH.NET >= 2026.0.0.
  Measured rather than argued: with the pin removed, dotnet restore src/FSH.Starter.slnx --force
  reports zero NU1902/NU1903 and exits 0. (The MessagePack pin next to it stays; removing that one
  does bring its advisory straight back.)

With both applied, deploy/docker/docker-compose.yml and src/Directory.Packages.props are now
genuinely byte-identical to #1388 (git diff --exit-code, checked today), which the earlier claim
was not.

---

The gate was on the wrong provider. The text/plain regression was covered by
SendGridMailServiceTests, and SendGrid is the optional provider: UseSendGrid defaults to false,
so SMTP is what a default deployment sends with, and its body builder had no test at all. Putting
the markup back into both parts there kept the suite green.

SmtpMailServiceTests drives the real MIME build: both parts present as multipart/alternative,
HTML alone staying text/html with no invented plain part, and an attachment wrapping the
alternative in multipart/mixed without dropping the text. Mapping TextBody back to
request.Body turns all three red. AddAttachmentsAsync is internal with InternalsVisibleTo
for the test assembly, the way Storage already exposes its internals to the integration suite;
the transport itself needs a server and is not where the mapping happens.

And the module that writes the bodies now has a test project. Notifications had none, so
everything it renders was exercised only through the mail services below it. The templates are
pure string builders, so Notifications.Tests runs without a DbContext or a host.

BillingEmailBodiesTests walks all four templates through one theory and asserts the pair is a
real pair: an HTML body carrying the subject and markup, and a plain twin that is non-empty,
repeats the subject and contains no angle bracket. Plus the two places the copy can drift on its
own - a tenant name is escaped in the markup and left literal in the text part (entities in
text/plain are read as entities), and the optional due-date line disappears without leaving a blank
paragraph behind. BillingEmailSenderTests covers the best-effort send that every billing
integration-event handler goes through: both bodies reach the MailRequest, an absent address
sends nothing, a throwing provider does not escape the handler (it runs inside the transaction of
whatever created or renewed the tenant), and the warning it logs identifies the operation without
carrying the recipient.

IMailService is ours, so the doubles are real implementations rather than substitutes, per
.agents/rules/testing.md. The module exposes its internals to this assembly the same way
Mailing already does for Framework.Tests. Registering the project in src/FSH.Starter.slnx turned out not to be the wiring. The unit-test job enumerates test projects by name rather than running the solution, so the slnx entry put the new project in the build and nowhere else: the first run on this branch was green without executing one of its tests (run 35359084326 mentions Notifications.Tests.dll exactly once, from the build step). Notifications is in that list now. Proven rather than assumed: run 35362147081, Unit Tests job, Passed! - Failed: 0, Passed: 13 ... Notifications.Tests.dll.

Verified: 13/13; making Expired reuse its HTML as the text body fails the theory arm and the
sender's pass-through case. dotnet build src/FSH.Starter.slnx exits 0 with the project
registered, and Architecture.Tests stays 55/55.