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

[marcelo-maciel]

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 correct HTML with escaping — the defect is the inconsistency, not the templates.

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: dotnet build src/FSH.Starter.slnx -warnaserror → 0 warnings, 0 errors; unit suites green (Identity 317, Framework 122, Billing 123, Architecture 51, and the rest). The integration suite did not run on my machine — dotnet test returns instantly with no output in that worktree, an environment fault I could not clear — so I am relying on CI for it. No integration test exercises the mail path today (the harness does not run enqueued mail jobs).

Heads-up: main is currently red on NU1903 (System.Security.Cryptography.Xml 10.0.8). This branch does not carry the pin — #1323 does — so CI here will fail restore until one of them lands.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[marcelo-maciel]

Pushed bb89a24f: cherry-picked the System.Security.Cryptography.Xml 10.0.10 pin so this branch can actually be evaluated. Without it every backend job dies in restore on NU1903, which is failing main today rather than anything in this diff.

The same pin is in #1323, so whichever lands first leaves the other with a one-hunk conflict in Directory.Packages.props — happy to drop it here the moment #1323 (or your own pin) merges.

Beyond unblocking CI, this matters for review confidence: I could not run the integration suite locally (dotnet test returns instantly with no output in that worktree — an environment fault on my machine), so the CI run is the only place it executes.

[marcelo-maciel]

Docs + changelog for this change (Golden Rule #10): fullstackhero/docs#239 — the Mailing page gets the TextBody signature, a correction to the SendGrid sentence (it no longer receives Body as both parts) and a caution about bare text in Body, plus a changelog entry.

CI here is green now that the NU1903 pin is on the branch: Backend CI, Frontend CI, Unit, Integration (6m26s), Coverage Gate, DbMigrator Smoke, both Scaffold jobs and CodeQL all pass.