identity-email-notifications: antwoorden vastgelegd, requirements.md met voorstellen P1-P5

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-08 17:48:32 +01:00
co-authored by Claude Sonnet 5.5
parent 02827c590f
commit 10032f5096
4 changed files with 135 additions and 23 deletions
@@ -5,7 +5,7 @@
- **Feature Slug**: identity-email-notifications
- **Project Type**: Brownfield
- **Start Date**: 2026-11-08
- **Current Stage**: INCEPTION - Requirements Analysis (questions issued, waiting for Bryan's answers via session "CMS & API")
- **Current Stage**: INCEPTION - Requirements Analysis (requirements.md written; proposals P1-P5 wait for Bryan's approval)
- **Branch**: feature/identity-email-notifications (branched from feature/andreaslop-site-hosting at e9feb37; own branch, not merged anywhere)
- **Request Type**: Feature (Bryan chose real e-mail over a workaround button; relayed by session "CMS & API")
@@ -30,17 +30,17 @@
## Extension Configuration
| Extension | Enabled | Decided At |
|---|---|---|
| Security Baseline | Pending (question in questions file) | Requirements Analysis |
| Property-Based Testing | Pending (question in questions file) | Requirements Analysis |
| Security Baseline | Yes (Q15 A) | Requirements Analysis |
| Property-Based Testing | Yes - partial PBT-02,03,07,08,09 (Q16 B) | Requirements Analysis |
## Operations Configuration
- **Include Operations Phase**: Undecided (question in questions file)
- **Decided At**: Pending - asked at Requirements Analysis
- **Include Operations Phase**: Yes (Q17 A)
- **Decided At**: Requirements Analysis
## Stage Progress
### INCEPTION
- [x] Workspace Detection - Complete
- [ ] Requirements Analysis - questions issued
- [~] Requirements Analysis - answers received, requirements.md drafted, approval pending (P1-P5)
- [ ] User Stories
- [ ] Workflow Planning
- [ ] Application Design
@@ -33,3 +33,15 @@
**Context**: Requirements Analysis gate: await answers.
---
## Requirements Analysis - answers received
**Timestamp**: 2026-11-08T17:10:00Z
**User Input**: "(Relayed by 'CMS & API', Bryan's answers in his own chat) 1 A (zelfde SMTP als SimpleDeckApp), smtp4dev lokaal. 2 X: afzenderadres PER WEBSITE INSTELBAAR IN DE SITE-INSTELLINGEN ... Leg dit als aandachtspunt/voorstel terug aan mij voor akkoord, bouw het niet stilzwijgend groter. 3 A (SPF/DKIM/DMARC volgens Bryan al ingericht). Dubbelcheck alleen-lezen ... 4 C (uitnodiging + nieuwe link + wachtwoord-reset + melding bij deactiveren/rolwijziging). 5 B. 6 B (Nederlands en Engels ...). 7 A + in het beheerpaneel een optie om de mail OPNIEUW TE VERSTUREN ... 8 A. 9 A. 10 B ... wachtwoord-reset is vermoedelijk anoniem aanroepbaar; hou daar de bestaande limiters aan en geef aan als B daar een risico geeft. 11 A. 12 A. 13 A met smtp4dev + een echte testmail naar een adres van Bryan op de testhost voor goedkeuring. 14 A. 15 A. 16 B. 17 A. Ga door met requirements.md; leg onduidelijkheden/scope-uitbreidingen (met name 2, 4C wachtwoord-reset als nieuwe flow, 6 taalkeuze) eerst aan mij voor, voor je ze bouwt."
**AI Response**: "Recorded the answers in the questions file, ran a read-only DNS check (SPF/DKIM/DMARC for slpsoftware.nl and andreaslop.nl), wrote requirements.md with proposals P1 (sender per site, allowlist, new SiteSettings store), P2 (password reset flow), P3 (language), P4 (anonymous reset cooldown), P5 (mail status) that need Bryan's approval before design or code. Security Baseline compliance table included."
**Context**: Requirements Analysis, gate: approval of requirements.md and proposals P1-P5 pending.
---
@@ -11,7 +11,7 @@ Which mail server should the CMS send through (test and, later, production)?
- D) Own mail server on the Pi (Postfix and similar)
- X) Other (please describe after [Answer]: tag below)
[Answer]:
[Answer]: A (same SMTP as SimpleDeckApp). Local dev tool: smtp4dev (already installed at Bryan).
## Question 2: Sender address and domain
From which address should the mails come?
@@ -21,7 +21,7 @@ From which address should the mails come?
- C) A shared address for the test environment and a per-site address for production
- X) Other (please describe after [Answer]: tag below)
[Answer]:
[Answer]: X - the sender address must be settable PER WEBSITE IN THE SITE SETTINGS (not config only). Scope extension: see requirements.md section 6, proposal P1 (needs approval before it is built).
## Question 3: Sender authentication (SPF / DKIM / DMARC)
Is the chosen sender domain already set up so that mail is not marked as spam?
@@ -31,7 +31,7 @@ Is the chosen sender domain already set up so that mail is not marked as spam?
- C) No; it still has to be set up before production (test may go out without it)
- X) Other (please describe after [Answer]: tag below)
[Answer]:
[Answer]: A (Bryan: SPF/DKIM/DMARC already set up). Read-only DNS check done by the AI, see requirements.md section 7.
## Question 4: Which mails
Which mails should the CMS send in the first version? (Select the lowest letter that covers what you want; each option includes the previous ones.)
@@ -41,7 +41,7 @@ Which mails should the CMS send in the first version? (Select the lowest letter
- C) B, plus a notification when the account is deactivated or the role changes
- X) Other (please describe after [Answer]: tag below)
[Answer]:
[Answer]: C (invitation + new link + password reset + notification on deactivation / role change). Password reset is a new flow: see requirements.md section 6, proposal P2.
## Question 5: Per-site mail content
How much should the mail look like each site?
@@ -51,7 +51,7 @@ How much should the mail look like each site?
- C) Fully custom template per site (separate HTML per site)
- X) Other (please describe after [Answer]: tag below)
[Answer]:
[Answer]: B (logo + brand colour in a shared template; reuse the BrandLogo/getBrand idea).
## Question 6: Languages
In which language(s) should the mails be written?
@@ -60,7 +60,7 @@ In which language(s) should the mails be written?
- B) Dutch and English, following the recipient's or the site's default language
- X) Other (please describe after [Answer]: tag below)
[Answer]:
[Answer]: B (Dutch and English, following site default language or the recipient). How the language is chosen: requirements.md section 6, proposal P3.
## Question 7: When sending fails
What should happen when the mail cannot be sent (server down, wrong credentials)?
@@ -70,7 +70,7 @@ What should happen when the mail cannot be sent (server down, wrong credentials)
- C) The mail is retried in the background a few times; the administrator sees the status ("sent", "failed") and the copyable link
- X) Other (please describe after [Answer]: tag below)
[Answer]:
[Answer]: A + an option in the admin to RESEND the mail (after a failure and optionally by hand); the copyable link is always available.
## Question 8: Where the mail is sent from (sending model)
How should the sending be done technically?
@@ -79,7 +79,7 @@ How should the sending be done technically?
- B) In the background (queue in the database or in memory), the request returns immediately
- X) Other (please describe after [Answer]: tag below)
[Answer]:
[Answer]: A (directly during the request).
## Question 9: Secrets on the host
How do the SMTP credentials get onto the Pi?
@@ -88,7 +88,7 @@ How do the SMTP credentials get onto the Pi?
- B) Via another secrets mechanism (please describe)
- X) Other (please describe after [Answer]: tag below)
[Answer]:
[Answer]: A (Email__Smtp__Username/Password in shared/env, mode 600).
## Question 10: Abuse and cost protection
How should the CMS prevent being used to spam or run up costs?
@@ -97,7 +97,7 @@ How should the CMS prevent being used to spam or run up costs?
- B) Only the existing role checks (only Owner/Administrator can trigger mails), no extra limit
- X) Other (please describe after [Answer]: tag below)
[Answer]:
[Answer]: B (role check only, no extra rate limit). Caveat: the anonymous password-reset request keeps the existing limiters; risk assessment in requirements.md section 6, proposal P4.
## Question 11: Link in the mail
The link in the mail points to the admin on the site's own address. Where does the CMS get that address from?
@@ -106,7 +106,7 @@ The link in the mail points to the admin on the site's own address. Where does t
- B) From the incoming request (Host header, behind the proxy)
- X) Other (please describe after [Answer]: tag below)
[Answer]:
[Answer]: A (App:PublicBaseUrl or similar per site, validated at start-up).
## Question 12: Shared code
How should the mail code be shared between SlpModularCms and SimpleDeckApp?
@@ -115,7 +115,7 @@ How should the mail code be shared between SlpModularCms and SimpleDeckApp?
- B) A small shared NuGet package used by both repos
- X) Other (please describe after [Answer]: tag below)
[Answer]:
[Answer]: A (IEmailSender + EmailOptions in Core, same shape as SimpleDeckApp, no shared code).
## Question 13: Testing without real sending
How do we test?
@@ -124,7 +124,7 @@ How do we test?
- B) Fake sender only, no real test mail
- X) Other (please describe after [Answer]: tag below)
[Answer]:
[Answer]: A with smtp4dev + one real test mail to an address of Bryan on the test host before approval.
## Question 14: Scope across sites
For which sites should this be switched on?
@@ -133,7 +133,7 @@ For which sites should this be switched on?
- B) First only ASF test; SlpSoftware later
- X) Other (please describe after [Answer]: tag below)
[Answer]:
[Answer]: A (all sites, on by configuration; no mail configured = current copy-link flow unchanged).
## Question 15: Security Extensions
Should security extension rules be enforced for this feature?
@@ -142,7 +142,7 @@ Should security extension rules be enforced for this feature?
- B) No - skip all SECURITY rules
- X) Other (please describe after [Answer]: tag below)
[Answer]:
[Answer]: A (Security extension on).
## Question 16: Property-Based Testing Extension
Should property-based testing (PBT) rules be enforced for this feature?
@@ -152,7 +152,7 @@ Should property-based testing (PBT) rules be enforced for this feature?
- C) No - skip all PBT rules
- X) Other (please describe after [Answer]: tag below)
[Answer]:
[Answer]: B (PBT partial).
## Question 17: Operations Phase
Should this feature go through the Operations phase after Construction (setting up deployment and monitoring)?
@@ -162,4 +162,4 @@ Should this feature go through the Operations phase after Construction (setting
- C) Not sure yet - ask me again after the Construction phase
- X) Other (please describe after [Answer]: tag below)
[Answer]:
[Answer]: A (Operations phase yes).
@@ -0,0 +1,100 @@
# Requirements - identity-email-notifications
## 1. Intent analysis
- **User request**: Real e-mail for the CMS identity flows instead of "copy the link and pass it on": invitation mail, new link when an administrator regenerates one, password reset, and a notice on deactivation or role change. Decisions by Bryan, relayed by session "CMS & API" (17 answers in `requirement-verification-questions.md`).
- **Request type**: New feature (shared Core capability plus Identity flows plus admin UI).
- **Scope**: Multiple components: Core (sender abstraction, options, templates), Identity (flows, endpoints), Availability/settings (only if P1 is approved), Frontend (resend action, mail status, password-reset pages), all Clients (switched on per configuration).
- **Complexity**: Complex. **Depth**: Comprehensive (credentials, account-granting links, personal data, an anonymous endpoint).
- **Extensions**: Security Baseline = enforced; Property-Based Testing = partial (PBT-02, 03, 07, 08, 09); Operations phase = yes.
- **Reference implementation (read-only)**: SimpleDeckApp (`SmtpEmailSender`, `IEmailSender`, `EmailOptions`).
## 2. Fixed decisions (from the answers)
| # | Decision |
|---|---|
| Q1 | Same SMTP service as SimpleDeckApp. Local manual runs: smtp4dev (already installed). |
| Q3 | SPF/DKIM/DMARC already set up (Bryan); read-only DNS check in section 7. |
| Q4 | Mails: invitation, new invitation link, password reset, notice on deactivation, notice on role change. |
| Q5 | Shared template with the site's logo and brand colour (reuse the `getBrand` / `BrandLogo` idea). |
| Q6 | Dutch and English; selection rule is proposal P3. |
| Q7 | If sending fails the action still succeeds and the admin sees a clear message plus the copyable link. The admin can resend the mail (after a failure, and by hand). The copyable link is always available. |
| Q8 | Sent directly during the request (no queue). |
| Q9 | Credentials as `Email__Smtp__Username` / `Email__Smtp__Password` in the host's `shared/env` (mode 600). |
| Q10 | Only role checks, no extra rate limit; the anonymous password-reset request keeps the existing limiters (risk in P4). |
| Q11 | Public base URL per site (`App:PublicBaseUrl` or similar), validated at start-up. |
| Q12 | `IEmailSender` and `EmailOptions` in `SlpModularCms.Core`, same shape and names as SimpleDeckApp; no code shared across repos. |
| Q13 | Fake sender in tests (always); smtp4dev for manual runs; one real test mail to an address of Bryan on the test host before approval. |
| Q14 | All sites, switched on by configuration. No mail configured means today's copy-link flow, unchanged. |
## 3. Functional requirements
- **FR-01 Sender abstraction.** `IEmailSender.SendAsync(toAddress, subject, htmlBody, cancellationToken)` in Core; `SmtpEmailSender` (MailKit/MimeKit; StartTls when `EnableSsl`; authenticate only when a username is set). `EmailOptions` (section `Email`): `FromAddress`, `FromName`, `Smtp{Host, Port=587, EnableSsl=true, Username, Password}`, plus a connect/send timeout (new, default 10 s).
- **FR-02 Enabled by configuration.** Mail is enabled when `Email:Smtp:Host` is non-empty. When disabled, every flow behaves exactly as today. `GET` system capabilities exposes `emailEnabled` so the UI knows which actions to offer.
- **FR-03 Start-up validation.** When enabled: valid `FromAddress`, a host, a port in range, and an absolute https (or localhost) `App:PublicBaseUrl` without a path; otherwise start-up fails with a clear message (no secrets in it).
- **FR-04 Invitation mail.** Creating an invitation sends a mail with the link `PublicBaseUrl + /admin + /invite/complete?token=...`. The response still returns `inviteLink` and now also `mail: { sent: true|false, error?: <short code> }`. A failure never rolls back the invitation.
- **FR-05 New link mail.** The "create new invite link" action (existing) also sends the mail when enabled, with the same result object.
- **FR-06 Resend.** Admin action "Mail opnieuw versturen" for a pending invitation: resends the mail with the current valid link; if the invitation is expired it first regenerates it (new token, new lifetime), then sends. Same hierarchy rules as the other invitation actions (Administrator only for role User).
- **FR-07 Password reset.** Proposal P2 (below).
- **FR-08 Notices.** After a successful deactivation (and reactivation) and after a role change, the affected user gets a short notice mail (never the actor's data beyond a generic "an administrator"). Failure to send never fails the action. No notice for self-service changes.
- **FR-09 Template.** One shared HTML template (inline CSS, table layout, no external images except the brand logo URL served by the same site, plain-text alternative part): site name, logo (when the theme has one), brand colour, a primary button plus the raw link as text, footer with the sender. All dynamic values are HTML-encoded. Subject and display names are validated against header injection (no CR/LF).
- **FR-10 Languages.** Proposal P3.
- **FR-11 Sender address per site.** Proposal P1 (needs approval; not built until then).
- **FR-12 UI.** The invite dialog and the users list show the mail result ("Mail verstuurd naar ..." / "Mail kon niet worden verstuurd, kopieer de link"), the resend action, and keep the copy-link action. With mail disabled the UI is unchanged. Dutch and English strings.
- **FR-13 Observability.** Structured log events for sent / failed (recipient domain only, never the full address, never links, tokens or credentials). A security event for repeated failed reset requests per client is optional (P4).
## 4. Non-functional requirements
- **NFR-01 No secrets in code or messages**; credentials only via environment; never logged; options `ToString`/validation messages never echo them.
- **NFR-02 Fail safe**: SMTP errors are caught, logged, mapped to a short error code for the UI; they never become a 500 for the admin action; the request is bounded by the timeout (Q8 sends in-request).
- **NFR-03 No account enumeration**: the anonymous reset request answers identically for known and unknown addresses (status, body, and as far as practical timing).
- **NFR-04 Tokens**: reset and invitation tokens are single-use, time-limited, cryptographically random; reset tokens are stored hashed or are stateless (P2).
- **NFR-05 Testability**: `IEmailSender` is faked in unit and integration tests; the SMTP sender is tested against an in-process SMTP stub or smtp4dev where practical.
- **NFR-06 Compatibility**: no behaviour change for any host without mail configuration; SlpSoftware and ASF both get the capability but only act when configured.
- **NFR-07 Accessibility/usability of the mail**: readable without images, link also as text, sensible subject lines.
## 5. Security Baseline compliance (applies, enforced)
| Rule | How this feature meets it |
|---|---|
| SECURITY-03 logging | Structured sent/failed events; no PII beyond recipient domain; no tokens, links or credentials in logs |
| SECURITY-05 input validation | Address format and length allowlist validation on every request that contains an address; display name length and control-character rules; link and token handling parameterised |
| SECURITY-08 access control | Mail actions follow `UserManagementRules`; settings changes follow the role chosen in P1; reset endpoints anonymous by necessity but limited (P4) |
| SECURITY-09 hardening | No default or sample credentials committed; placeholders only; start-up validation of options |
| SECURITY-11 secure design | Mail failure is non-fatal and isolated behind an interface; copy-link fallback keeps the system usable |
| SECURITY-12 credentials | Reset flow: single-use time-limited tokens, uniform responses, existing password rules, existing token revocation on password change; SMTP credentials via env only |
| SECURITY-13 integrity | Packages pinned (MailKit/MimeKit exact versions, vulnerability scan stays a gate) |
| SECURITY-14 alerting | Sent/failed counts as log events; Sentry picks up errors; an alert on repeated send failures is part of Operations |
| SECURITY-15 exceptions | All SMTP exceptions handled at the sender boundary; generic user-facing messages |
| SECURITY-01/02/04/06/07/10 | N/A or unchanged (no new data store beyond P1/P2 options, no new network intermediary; SMTP over StartTls enforced when `EnableSsl`) |
## 6. Proposals that need Bryan's approval before they are built
Nothing below is built until approved (relayed through "CMS & API").
### P1 - Sender address per site in the site settings (answer to Q2)
Facts: there is no general site-settings store today. The only "settings" screen is availability; the admin-editable brand/site-name capability is a separately planned feature (noted earlier). A per-site sender address therefore needs a new, small settings store.
- **Where it lives**: a new Core table `SiteSettings` (single row per site, versioned columns) with a `SiteSettingsService`; the existing Settings page gets a "Mail" card. It is the same store the planned brand/site-name capability would use, so this is also its first building block. Needs one EF migration (a new table; every host gets it on start, no data change).
- **Security**: the free field must not let someone send as an arbitrary domain through the shared SMTP account (SPF/DKIM mismatch, spoofing, rejection). Proposed rule: the display name is free text (length 1..80, no control characters); the address is chosen from an allowlist configured per host (`Email:AllowedFromAddresses`, exact full addresses, validated at start-up). The UI shows only the allowed choices. Default when nothing is set: `Email:FromAddress` from configuration.
- **Who may change it**: Owner only (it influences deliverability and trust), Administrator may read.
- **Alternatives**: (a) config only now (smallest, no migration; per-site address set by whoever deploys); (b) the proposal above. Recommendation: (b) but built as a small store that the later brand feature reuses; if Bryan prefers a smaller first step, (a) plus the display name editable in settings.
### P2 - Password reset as a new flow (answer to Q4 C)
Today there is no "forgot password". Proposed: `POST auth/forgot-password` (anonymous, always 202 with a neutral message, mail sent only when the address exists and is active) and `POST auth/reset-password` (token, new password). Tokens from ASP.NET Identity's data-protection token provider (stateless, single-use through the security stamp, default 1 hour, configurable), mail link to `/admin/reset-password?token=...&email=...`, new frontend page and a "Wachtwoord vergeten?" link on the login page (only when `emailEnabled`). A completed reset revokes all refresh tokens of the user. The existing "login" rate limiter applies. This adds default token providers to the Identity registration (a Core change that affects all hosts but is inert without mail).
### P3 - Language selection (answer to Q6)
No per-user language exists today. Proposed for v1: the mail language is the site's default language (new `App:DefaultLanguage`, nl or en, default nl, aligned with the admin's `VITE_DEFAULT_LANGUAGE`). Per-user preferred language would need a new user column and migration and is left out. Strings live in one resource per language in Core; a missing key falls back to Dutch.
### P4 - Anonymous reset and answer 10 B (risk)
B (role checks only) is fine for admin-triggered mails. The anonymous `forgot-password` endpoint can be used to flood one person's inbox (spread over many client addresses the per-address limiter does not help). Proposed small addition, no migration: a per-recipient cooldown in memory (one reset mail per address per 5 minutes, silently ignored while cooling down, same response). Needs approval because it goes beyond "no extra rate limit".
### P5 - Mail status persistence (answer to Q7)
"Mail opnieuw versturen" needs to know which mails failed. Proposed v1: show the result in the response of the action and always offer the resend action for pending invitations (no stored status, no migration). A stored `LastMailSentAt/LastMailError` on invitations is a later option.
## 7. Read-only check of sender domains (DNS, 2026-11-08)
- `slpsoftware.nl`: SPF `v=spf1 a mx include:smtp.spf.ziggo.nl ~all`; DMARC `v=DMARC1; p=none`; DKIM record found at selector `dkim._domainkey` (public key present).
- `andreaslop.nl`: SPF `v=spf1 a mx include:smtp.spf.ziggo.nl ~all`; DMARC `v=DMARC1; p=none`; DKIM record found at selector `dkim._domainkey`.
- Observations (for Bryan): SPF authorises the domain's own A/MX hosts and the Ziggo SMTP relay; it does not name any transactional service, so sending through the SimpleDeckApp SMTP service works only when that service is `mail.<domain>` or the Ziggo relay (to be confirmed with the real host name; not visible from the repo). DMARC is `p=none` (monitoring only, not enforced). The DKIM record being present does not prove that the SMTP service signs with it. Per-site domains such as `andreaslop.nl` have the same pattern as `slpsoftware.nl` but are a different domain: a mail with sender `@andreaslop.nl` is only aligned if the SMTP service signs for that domain too. This is exactly why P1 proposes an allowlist.
## 8. Out of scope
HTML template editor, per-user language, queue or retry worker, delivery tracking or bounces, marketing mail, SMS, inbound mail.
## 9. Acceptance (summary)
- Mail disabled: all existing tests unchanged and green.
- Mail enabled with a fake sender: invitation, new link, resend, reset, deactivation and role-change notices produce the expected message (recipient, language, link, encoded values); failures never fail the action and show the copy-link fallback.
- Property-based tests (partial): link builder round trip (token encode/decode), template HTML-encoding invariant for any display name, header-injection rejection for any subject/name, allowlist validator (PBT-02/03/07/08/09).
- Manual: smtp4dev run, then one real test mail to an address of Bryan from the test host before approval.