diff --git a/aidlc-docs/active-features.md b/aidlc-docs/active-features.md index c08dbb0..51d31b8 100644 --- a/aidlc-docs/active-features.md +++ b/aidlc-docs/active-features.md @@ -12,3 +12,4 @@ | Feature | Andrea's site hosting (andreaslop-site-hosting) | 🟡 Operations (wacht op CI-proef en eerste test-deploy) | feature/andreaslop-site-hosting | Core (CmsHost, CSP, static content), Clients (new Api.AndreaSlopFotografie), Frontend (theme), CI/CD | 2026-11-06 | | Bug | [cms-admin-nine-points](bugs/cms-admin-nine-points/bug-fix.md) | ✅ Complete (wacht op goedkeuring ASF test) | feature/andreaslop-site-hosting | Core (auth, invitations), Identity, Availability, Frontend | 2026-11-08 | | Bug | [invitation-delete-and-lifetime](bugs/invitation-delete-and-lifetime/bug-fix.md) | ✅ Complete (wacht op goedkeuring ASF test) | feature/andreaslop-site-hosting | Core (invitations), Identity, Frontend | 2026-11-08 | +| Feature | Identity e-mail notifications (identity-email-notifications) | 🔵 Inception (wacht op antwoorden) | feature/identity-email-notifications | Core (IEmailSender), Identity, Frontend | 2026-11-08 | diff --git a/aidlc-docs/features/identity-email-notifications/aidlc-state.md b/aidlc-docs/features/identity-email-notifications/aidlc-state.md new file mode 100644 index 0000000..1a28926 --- /dev/null +++ b/aidlc-docs/features/identity-email-notifications/aidlc-state.md @@ -0,0 +1,47 @@ +# AI-DLC State Tracking + +## Project Information +- **Feature Name**: E-mail notifications for identity (invitation, new activation link, password reset) +- **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") +- **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") + +## Workspace State +- **Existing Code**: Yes +- **Reverse Engineering Needed**: No - reuse aidlc-docs/_shared/reverse-engineering/ +- **Workspace Root**: K:\Development\Projects\SlpModularCms + +## Code Location Rules +- **Application Code**: Workspace root (NEVER in aidlc-docs/) +- **Feature Documentation**: aidlc-docs/features/identity-email-notifications/ only + +## Language Configuration +- **Documentation Language**: English +- **Conversation Language**: User Language (Dutch) +- **Note**: Inherited from the other features in this workspace. + +## External Requester (hand-off) +- **Session**: "CMS & API", relays Bryan's decisions. Questions for Bryan go through that session. No implementation before the answers are in. +- **Reference implementation (read-only)**: K:\Development\Projects\SimpleDeckApp (MailKit/MimeKit `SmtpEmailSender`, `IEmailSender.SendAsync(to, subject, htmlBody, ct)`, `EmailOptions` section "Email"). + +## 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 | + +## Operations Configuration +- **Include Operations Phase**: Undecided (question in questions file) +- **Decided At**: Pending - asked at Requirements Analysis + +## Stage Progress +### INCEPTION +- [x] Workspace Detection - Complete +- [ ] Requirements Analysis - questions issued +- [ ] User Stories +- [ ] Workflow Planning +- [ ] Application Design +- [ ] Units Generation diff --git a/aidlc-docs/features/identity-email-notifications/audit.md b/aidlc-docs/features/identity-email-notifications/audit.md new file mode 100644 index 0000000..1620138 --- /dev/null +++ b/aidlc-docs/features/identity-email-notifications/audit.md @@ -0,0 +1,35 @@ +# Audit Log - identity-email-notifications + +## Workspace Detection + +**Timestamp**: 2026-11-08T16:15:00Z + +**User Input**: "(Relayed by session 'CMS & API', Bryan's decisions in his own chat) Knop/mail: Bryan kiest ECHTE E-MAIL. Dat is een aparte feature (niet in deze branch bouwen). Start die als nieuwe AIDLC-feature (bv. 'identity-email-notifications') in een eigen branch/worktree vanaf de huidige branch na de deploy van punt 1. Begin met requirements-analyse; zet vragen aan Bryan aan mij door (ik stel ze in zijn chat): provider/SMTP-keuze (eigen SMTP via hostingpartner vs transactionele dienst), afzenderadres/domein + SPF/DKIM/DMARC, welke mails (uitnodiging, nieuwe activatiecode, wachtwoord-reset?), per-site configuratie van afzendernaam/logo, secrets-beheer op de Pi, rate limiting, sjabloon NL, fallback als mail faalt (kopieerbare link blijft bestaan), testen zonder echte verzending (fake sender). Geen implementatie voor die vragen beantwoord zijn." + +**AI Response**: "Classified as Feature (new capability). Created branch feature/identity-email-notifications from e9feb37 after the ASF test deploy of run 615, created the feature directory, reused the shared reverse-engineering artifacts, wrote requirement-verification-questions.md (17 questions). Findings used: no mail code or config anywhere in this repo." + +**Context**: Workspace Detection, Feature lane, brownfield, no RE rerun. Request relayed by a peer session; approvals must come from Bryan. + +--- + +## Requirements Analysis - reference implementation read + +**Timestamp**: 2026-11-08T16:20:00Z + +**User Input**: "(Relayed by 'CMS & API') Aanvulling voor de e-mailfeature: SimpleDeckApp (K:\Development\Projects\SimpleDeckApp, alleen lezen) heeft al mail. Kijk daar eerst naar en volg het patroon tenzij je een goede reden hebt ... Zoek ook uit welke SMTP-server/provider productie daar gebruikt en of afzenderdomein + SPF/DKIM daar al ingericht zijn ... Eventueel een gedeelde Core-abstractie (IEmailSender in Core) i.p.v. kopieer." + +**AI Response**: "Read SimpleDeckApp read-only: SmtpEmailSender (MailKit/MimeKit, StartTls when EnableSsl, auth only when Username set), EmailOptions (section Email: FromAddress, FromName, Smtp{Host,Port=587,EnableSsl,Username,Password}), committed appsettings sender no-reply@slpsoftware.nl / name 'Decks', secrets via Email__Smtp__* env vars, local catcher on localhost:25. The production SMTP host/provider and the SPF/DKIM state are NOT in that repo (config lives outside it); asked as Questions 1 to 3." + +**Context**: Requirements Analysis, inputs for the question file. + +--- + +## Requirements Analysis - questions issued + +**Timestamp**: 2026-11-08T16:25:00Z + +**AI Response**: "Question file inception/requirements/requirement-verification-questions.md (17 questions incl. both extension opt-ins and the Operations question) forwarded to Bryan through session 'CMS & API'. Waiting for answers; no implementation." + +**Context**: Requirements Analysis gate: await answers. + +--- diff --git a/aidlc-docs/features/identity-email-notifications/inception/requirements/requirement-verification-questions.md b/aidlc-docs/features/identity-email-notifications/inception/requirements/requirement-verification-questions.md new file mode 100644 index 0000000..ec64dd9 --- /dev/null +++ b/aidlc-docs/features/identity-email-notifications/inception/requirements/requirement-verification-questions.md @@ -0,0 +1,165 @@ +# Requirements Clarification Questions - identity-email-notifications + +Context: the CMS has no mail at all today. Invitations work through a link that an administrator copies and passes on. Bryan chose real e-mail. SimpleDeckApp already sends mail (MailKit, `IEmailSender`, options section `Email`, sender `no-reply@slpsoftware.nl`); the plan is to follow that pattern, preferably as a shared abstraction in Core. Nothing is built until these are answered. Answers are relayed by session "CMS & API". + +## Question 1: SMTP server / provider +Which mail server should the CMS send through (test and, later, production)? + +- A) The same SMTP server SimpleDeckApp uses in production (reuse host, account type and domain pattern) +- B) The SMTP server of the hosting partner (own account/mailbox) +- C) A transactional mail service (for example Brevo, Mailgun, Postmark, Amazon SES) with its own account +- D) Own mail server on the Pi (Postfix and similar) +- X) Other (please describe after [Answer]: tag below) + +[Answer]: + +## Question 2: Sender address and domain +From which address should the mails come? + +- A) One shared sender for all sites (for example no-reply@slpsoftware.nl), per-site name only in the display name +- B) A sender per site on that site's own domain (for example no-reply@andreaslop.nl for Andrea's site) +- C) A shared address for the test environment and a per-site address for production +- X) Other (please describe after [Answer]: tag below) + +[Answer]: + +## Question 3: Sender authentication (SPF / DKIM / DMARC) +Is the chosen sender domain already set up so that mail is not marked as spam? + +- A) Yes, SPF, DKIM and DMARC are already set up for the sender domain (reuse the SimpleDeckApp setup) +- B) Not sure; please check (read-only) what is published and report +- 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]: + +## 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.) + +- A) Only the invitation mail (link to complete the account), plus a "new invitation link" mail when an administrator regenerates one +- B) A, plus password reset ("forgot password") with a mail link +- C) B, plus a notification when the account is deactivated or the role changes +- X) Other (please describe after [Answer]: tag below) + +[Answer]: + +## Question 5: Per-site mail content +How much should the mail look like each site? + +- A) Per site: sender name and mail text in Dutch, plain and without a logo +- B) Per site: sender name, Dutch text, and the site's logo and brand colour in a shared template +- C) Fully custom template per site (separate HTML per site) +- X) Other (please describe after [Answer]: tag below) + +[Answer]: + +## Question 6: Languages +In which language(s) should the mails be written? + +- A) Dutch only (the admin of these sites is Dutch) +- B) Dutch and English, following the recipient's or the site's default language +- X) Other (please describe after [Answer]: tag below) + +[Answer]: + +## Question 7: When sending fails +What should happen when the mail cannot be sent (server down, wrong credentials)? + +- A) The invitation is still created and the administrator sees a clear message plus the copyable link (the current link stays available as fallback) +- B) The invitation is not created and the administrator sees an error +- 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]: + +## Question 8: Where the mail is sent from (sending model) +How should the sending be done technically? + +- A) Directly during the request (simple; the request waits for the mail server) +- B) In the background (queue in the database or in memory), the request returns immediately +- X) Other (please describe after [Answer]: tag below) + +[Answer]: + +## Question 9: Secrets on the host +How do the SMTP credentials get onto the Pi? + +- A) As environment variables in the host's `shared/env` (mode 600), same as other secrets (Email__Smtp__Username, Email__Smtp__Password) +- B) Via another secrets mechanism (please describe) +- X) Other (please describe after [Answer]: tag below) + +[Answer]: + +## Question 10: Abuse and cost protection +How should the CMS prevent being used to spam or run up costs? + +- A) A rate limit per administrator and per recipient address (for example a few mails per address per hour) plus the existing login rate limits +- B) Only the existing role checks (only Owner/Administrator can trigger mails), no extra limit +- X) Other (please describe after [Answer]: tag below) + +[Answer]: + +## 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? + +- A) A configured setting per site (for example `App:PublicBaseUrl`), validated at start-up +- B) From the incoming request (Host header, behind the proxy) +- X) Other (please describe after [Answer]: tag below) + +[Answer]: + +## Question 12: Shared code +How should the mail code be shared between SlpModularCms and SimpleDeckApp? + +- A) A new `IEmailSender` in SlpModularCms.Core, following the SimpleDeckApp pattern (same interface and options names); no code shared across the two repos +- B) A small shared NuGet package used by both repos +- X) Other (please describe after [Answer]: tag below) + +[Answer]: + +## Question 13: Testing without real sending +How do we test? + +- A) A fake sender in unit and integration tests (always), plus a local catcher (smtp4dev/Papercut) for manual runs; one manual test mail to a real address on the test host before approval +- B) Fake sender only, no real test mail +- X) Other (please describe after [Answer]: tag below) + +[Answer]: + +## Question 14: Scope across sites +For which sites should this be switched on? + +- A) All sites on the shared code, switched on per site by configuration (no mail configured = the current copy-link flow keeps working unchanged) +- B) First only ASF test; SlpSoftware later +- X) Other (please describe after [Answer]: tag below) + +[Answer]: + +## Question 15: Security Extensions +Should security extension rules be enforced for this feature? + +- A) Yes - enforce all SECURITY rules as blocking constraints (recommended; this feature handles credentials, links that grant account access, and personal data) +- B) No - skip all SECURITY rules +- X) Other (please describe after [Answer]: tag below) + +[Answer]: + +## Question 16: Property-Based Testing Extension +Should property-based testing (PBT) rules be enforced for this feature? + +- A) Yes - enforce all PBT rules as blocking constraints +- B) Partial - only for pure functions and serialization round-trips (for example building links and templates) +- C) No - skip all PBT rules +- X) Other (please describe after [Answer]: tag below) + +[Answer]: + +## Question 17: Operations Phase +Should this feature go through the Operations phase after Construction (setting up deployment and monitoring)? + +- A) Yes - run the Operations phase after Construction (deployment + monitoring setup) +- B) No - stop after Build and Test (deployment/monitoring are out of scope for this feature) +- C) Not sure yet - ask me again after the Construction phase +- X) Other (please describe after [Answer]: tag below) + +[Answer]: