U1 mail-foundation (frontend en documentatie): Mail-kaart bij Instellingen

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-08 18:22:27 +01:00
co-authored by Claude Sonnet 5.5
parent 745f0b2203
commit 2a0561a58e
15 changed files with 442 additions and 5 deletions
@@ -0,0 +1,28 @@
# Code summary - U1 mail-foundation
## What was built
**Core (`SlpModularCms.Core/Email`, `/SiteSettings`)**
- `IEmailSender` (`SendAsync(OutgoingMail)` returning `MailSendResult`; SimpleDeckApp-shaped extension `SendAsync(to, subject, html)`), `SmtpEmailSender` (MailKit 4.18.2: StartTls when `EnableSsl`, authenticate only with a username, connect/send bounded by `TimeoutSeconds`, every exception mapped to `timeout|auth_failed|rejected|unknown`, exception type only in the log), `NullEmailSender` (`disabled`).
- Headers are validated before connecting (`EmailAddressRules`: strict ASCII address allowlist, display name without control characters, colour `#rrggbb`); a bad value is refused with `rejected` and nothing is sent.
- `EmailOptions` (section `Email`) and `AppMailOptions` (section `App`: `PublicBaseUrl`, `DefaultLanguage`), `EmailOptionsValidator` (start-up validation, only when `Email:Smtp:Host` is set; messages never contain credentials).
- `MailTemplateRenderer` (six kinds, nl/en, one shared HTML layout with logo or site name, brand colour, button plus raw link, plain-text part; all values HTML-encoded; subject without control characters; unknown language falls back to Dutch), `LanguageResolver` (user, site default, Dutch).
- `SiteSettingsEntity` + `ISiteSettingsService`/`SiteSettingsService` (sender address only from default + `Email:AllowedFromAddresses`, name 1..80 without control characters, blank = reset to defaults, a stored address that is no longer allowed falls back to the default on use). Table `SiteSettings` (migration `AddSiteSettings`, additive, with `Down`).
- `AddCmsEmail` registration (null sender when mail is off), `SystemController` capabilities now include `EmailEnabled` and `DefaultLanguage`.
**Identity module**: `SiteSettingsController` (`GET SiteSettings/mail` AdminOnly, `PUT SiteSettings/mail` OwnerOnly; 400 with code for invalid, 409 when mail is off).
**Config**: `Email` and `App` sections (mail OFF, no credentials) in the ASF and SlpSoftware `appsettings.json`.
**Frontend**: `MailSettingsCard` on the Settings page (only when `emailEnabled`; Owner edits, Administrator read-only; select limited to allowed addresses; restore defaults), `useMailSettings`, capabilities hook reads `emailEnabled`/`defaultLanguage`, nl/en strings.
## Decisions kept from the design
No mail configuration means no behaviour change anywhere. Sending never throws into callers. Sender address is never free text. Logo and colour come from per-site config (`Email:LogoUrl`, `Email:BrandColor`).
## Tests
- Core.Tests 452: option validation (every rule, no credentials in messages), address/name rules, renderer (nl/en, fallback, encoding, role names, no link without button, invalid colour), `SmtpEmailSender` against an in-process SMTP stub (success, sender override, SimpleDeckApp-shaped call, header injection refused without connecting, timeout, nothing listening, not configured, disabled), site settings (default, allowed, rejected, reset, narrowed allowlist, mail off), registration (null/SMTP sender, start-up failure), capabilities flag.
- Property-based (PBT-03/07/08/09 partial): rendering never throws/never leaks raw markup/subject stays one line for any generated value; control characters never valid in a display name; only the allowed alphabet in addresses; sender never outside default + allowlist; token survives the link round trip (PBT-02).
- MariaDB-backed (run when `ConnectionStrings__DefaultConnection` is set, as in CI; own scratch databases): all migrations apply on MariaDB, the newest is undone and re-applied; `DateTimeOffset` round trip.
- Identity.Tests 96 (new `SiteSettingsControllerTests`: policies AdminOnly/OwnerOnly, status mapping). Frontend 333 (card: hidden when off, Owner saves, allowed options only, save disabled/empty/too-long name, reset, Administrator read-only; capabilities flags). ESLint and tsc clean. `dotnet list package --vulnerable` clean.
## Not run locally
`Api.Tests` and the ASF `HostPipelineTests` (the developer's `appsettings.local.json` overrides the connection string and points to a database that is not running); CI runs them. The new migration was verified separately on a real MariaDB (above).