Files
slp-modular-cms/aidlc-docs/features/identity-email-notifications/construction/mail-foundation/code/code-summary.md
T

4.1 KiB

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).