Identity e-mail notifications, ASF-hosting en testfixes (run 636) #11
@@ -11,6 +11,10 @@ on:
|
||||
description: 'Deploy to Production'
|
||||
type: boolean
|
||||
default: false
|
||||
deploy_asf_test:
|
||||
description: 'Deploy ASF test (Andrea Slop Fotografie)'
|
||||
type: boolean
|
||||
default: false
|
||||
pull_request:
|
||||
types: [opened, synchronize, reopened]
|
||||
push:
|
||||
@@ -514,3 +518,111 @@ jobs:
|
||||
service_name: ${{ needs.config.outputs.service_name_production }}
|
||||
health_check_url: ${{ needs.config.outputs.health_check_url_production }}
|
||||
run_db_backup: true
|
||||
|
||||
# ==========================================================================================
|
||||
# Andrea Slop Fotografie (ASF) test host. Deliberately SEPARATE jobs: nothing above (the
|
||||
# SlpSoftware jobs, the env block, deploy-scp.yaml) is changed, a failure here never blocks the
|
||||
# SlpSoftware deploy and vice versa.
|
||||
#
|
||||
# Everything below is switched on by ONE Gitea variable, ASF_TEST_DEPLOY_ENABLED == 'true'.
|
||||
# While it is unset (or anything else) all three jobs are skipped and the pipeline behaves
|
||||
# exactly as before. Secrets cannot be tested in an `if:`, hence an explicit variable; it is set
|
||||
# only after the Pi and the other ASF_* variables exist.
|
||||
# Runs: on every push to master (like the SlpSoftware test deploy) or manually with the
|
||||
# "Deploy ASF test" box ticked. Test only: there is no production path for ASF.
|
||||
# ==========================================================================================
|
||||
config-asf:
|
||||
if: ${{ vars.ASF_TEST_DEPLOY_ENABLED == 'true' }}
|
||||
runs-on: ubuntu-latest
|
||||
outputs:
|
||||
deploy_path: ${{ steps.set.outputs.deploy_path }}
|
||||
service_name: ${{ steps.set.outputs.service_name }}
|
||||
health_check_url: ${{ steps.set.outputs.health_check_url }}
|
||||
steps:
|
||||
- id: set
|
||||
env:
|
||||
DEPLOY_PATH: ${{ vars.DEPLOY_PATH_ASF_TEST }}
|
||||
SERVICE_NAME: ${{ vars.SERVICE_NAME_ASF_TEST }}
|
||||
HEALTH_CHECK_URL: ${{ vars.HEALTH_CHECK_URL_ASF_TEST }}
|
||||
run: |
|
||||
for v in DEPLOY_PATH SERVICE_NAME HEALTH_CHECK_URL; do
|
||||
if [ -z "${!v}" ]; then
|
||||
echo "The Gitea variable for $v (…_ASF_TEST) is not set; set it or switch ASF_TEST_DEPLOY_ENABLED off."
|
||||
exit 1
|
||||
fi
|
||||
done
|
||||
echo "deploy_path=$DEPLOY_PATH" >> "$GITHUB_OUTPUT"
|
||||
echo "service_name=$SERVICE_NAME" >> "$GITHUB_OUTPUT"
|
||||
echo "health_check_url=$HEALTH_CHECK_URL" >> "$GITHUB_OUTPUT"
|
||||
|
||||
publish-asf-test:
|
||||
needs: [changes, backend-build, backend-test, vulnerability-scan, frontend-build, frontend-test, frontend-lint]
|
||||
# Same gate handling as publish-test (see there for why always() and explicit results), plus the
|
||||
# ASF switch, and built only when it will actually be deployed.
|
||||
if: |
|
||||
always() &&
|
||||
vars.ASF_TEST_DEPLOY_ENABLED == 'true' &&
|
||||
needs.changes.result == 'success' &&
|
||||
needs.backend-build.result != 'failure' && needs.backend-build.result != 'cancelled' &&
|
||||
needs.backend-test.result != 'failure' && needs.backend-test.result != 'cancelled' &&
|
||||
needs.vulnerability-scan.result != 'failure' && needs.vulnerability-scan.result != 'cancelled' &&
|
||||
needs.frontend-build.result != 'failure' && needs.frontend-build.result != 'cancelled' &&
|
||||
needs.frontend-test.result != 'failure' && needs.frontend-test.result != 'cancelled' &&
|
||||
needs.frontend-lint.result != 'failure' && needs.frontend-lint.result != 'cancelled' &&
|
||||
(needs.changes.outputs.backend == 'true' || needs.changes.outputs.frontend == 'true') &&
|
||||
((github.event_name == 'workflow_dispatch' && github.event.inputs.deploy_asf_test == 'true') ||
|
||||
(github.event_name == 'push' && github.ref == 'refs/heads/master'))
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-dotnet@v4
|
||||
with:
|
||||
dotnet-version: ${{ env.DOTNET_VERSION }}
|
||||
- uses: actions/setup-node@v3
|
||||
with:
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
- uses: pnpm/action-setup@v4
|
||||
with:
|
||||
version: ${{ env.PNPM_VERSION }}
|
||||
|
||||
# Admin SPA with the ASF theme and Dutch as the default language. Lands in wwwroot/admin
|
||||
# BEFORE dotnet publish, for the same reason as in publish-test. No Umami for the admin.
|
||||
- name: Build admin frontend (ASF theme)
|
||||
working-directory: frontend
|
||||
env:
|
||||
VITE_APP_ENV: test
|
||||
VITE_APP_TITLE: Andrea Slop Fotografie
|
||||
VITE_THEME: asf
|
||||
VITE_DEFAULT_LANGUAGE: nl
|
||||
VITE_SENTRY_DSN: ${{ vars.VITE_SENTRY_DSN_ASF }}
|
||||
run: |
|
||||
pnpm install --frozen-lockfile
|
||||
pnpm build
|
||||
mkdir -p ../src/SlpModularCms.Api.AndreaSlopFotografie/wwwroot/admin
|
||||
cp -r dist/. ../src/SlpModularCms.Api.AndreaSlopFotografie/wwwroot/admin/
|
||||
|
||||
- name: Publish (ASF test)
|
||||
working-directory: src/SlpModularCms.Api.AndreaSlopFotografie
|
||||
run: >
|
||||
dotnet publish -c Release -r ${{ env.PUBLISH_RID }} --self-contained false
|
||||
-o ${{ github.workspace }}/app-asf-test
|
||||
|
||||
- name: Upload publish artifact
|
||||
uses: actions/upload-artifact@v3
|
||||
with:
|
||||
name: app-asf-test
|
||||
path: app-asf-test
|
||||
retention-days: 1
|
||||
|
||||
deploy-asf-test:
|
||||
needs: [publish-asf-test, config-asf]
|
||||
if: vars.ASF_TEST_DEPLOY_ENABLED == 'true' && ((github.event_name == 'workflow_dispatch' && github.event.inputs.deploy_asf_test == 'true') || (github.event_name == 'push' && github.ref == 'refs/heads/master'))
|
||||
uses: ./.gitea/workflows/deploy-scp.yaml
|
||||
secrets: inherit
|
||||
with:
|
||||
artifact_name: app-asf-test
|
||||
environment: test
|
||||
deploy_path: ${{ needs.config-asf.outputs.deploy_path }}
|
||||
service_name: ${{ needs.config-asf.outputs.service_name }}
|
||||
health_check_url: ${{ needs.config-asf.outputs.health_check_url }}
|
||||
run_db_backup: false
|
||||
|
||||
@@ -6,6 +6,7 @@ Een modulaire monolith CMS gebouwd met .NET 10.
|
||||
|
||||
- `src/SlpModularCms.Api`: De host applicatie en API shell (lokale ontwikkeling / dev-host).
|
||||
- `src/SlpModularCms.Api.SlpSoftware`: Tweede Client-project, de daadwerkelijk gedeployde API voor `test.slpsoftware.nl`/`slpsoftware.nl` (CI/CD-cutover vanaf `SlpModularCms.Api`). Host dezelfde modules als `SlpModularCms.Api` via dezelfde gedeelde `CmsHost`-compositie (zie hieronder), plus de `Offerings`-module. Heeft een eigen, geïsoleerde lokale ontwikkeldatabase — zie `appsettings.Development.json` in dat project.
|
||||
- `src/SlpModularCms.Api.AndreaSlopFotografie`: Derde Client-project voor Andrea Slop Fotografie (testomgeving `test.andreaslop.nl`). Host alleen de modules `Identity` en `Availability` (geen `Master`, geen `Offerings`) en serveert de voorgerenderde website uit `wwwroot/web/` (`WebsiteMode.PrerenderedPages`) plus de admin met het thema `asf` op `/admin`. Lokaal op poort `5200`, eigen database (`appsettings.Development.json`). Bijbehorende tests: `SlpModularCms.Api.AndreaSlopFotografie.Tests` (de pipelinetests daarin hebben net als `Api.Tests` een bereikbare MariaDB nodig).
|
||||
- `src/SlpModularCms.Core`: Kern functionaliteiten, data modellen en interfaces. Bevat ook `Core/Hosting/CmsHost.cs` — de gedeelde service- en pipeline-compositie die elk Client-project (`Api`, `Api.SlpSoftware`) vanuit zijn eigen dunne `Program.cs` aanroept, zodat beide projecten niet uit elkaar kunnen groeien.
|
||||
- `src/SlpModularCms.Modules.*`: Onafhankelijke functionele modules.
|
||||
- `frontend/`: De CMS admin web-UI (Vite + React + TypeScript). Bewust buiten `src/` gehouden om de .NET solution schoon te houden.
|
||||
@@ -65,9 +66,24 @@ De API gebruikt een beveiligde flow voor authenticatie:
|
||||
### Belangrijke NFR Details:
|
||||
- **CORS**: Alleen toegestane origins uit `appsettings.json → Cors:AllowedOrigins` worden geaccepteerd. De frontend moet draaien op een van deze origins.
|
||||
- **Cookies**: De `refreshToken` cookie is `httpOnly`, `SameSite=Strict` en heeft het pad `/api/v1/auth`.
|
||||
- **Rate Limiting**: Login endpoints hebben rate limiting (Fixed window 5/min, Sliding window 20/min).
|
||||
- **Rate Limiting**: Login endpoints hebben rate limiting (Fixed window 5/min, Sliding window 20/min). De limieten gelden **per clientadres**. Achter een reverse proxy is dat alleen het echte bezoekersadres als `ForwardedHeaders__KnownProxies__0` (en volgende) het IP van de proxy bevat; zonder die instelling worden `X-Forwarded-*`-headers genegeerd en delen alle bezoekers het adres van de proxy (één bucket, het gedrag van vóór deze optie). Alleen de opgegeven proxies worden vertrouwd (één hop); een onparseerbaar of wildcard-adres (`0.0.0.0`, `::`) laat de host bij **opstarten** falen.
|
||||
- **Error Handling**: Foutmeldingen volgen de RFC 9457 `ProblemDetails` standaard.
|
||||
|
||||
## E-mail (uitnodigingen, wachtwoord opnieuw instellen, meldingen)
|
||||
|
||||
E-mail staat standaard UIT: zolang `Email:Smtp:Host` leeg is, werkt alles zoals voorheen (de beheerder kopieert de uitnodigingslink). Aanzetten per omgeving met omgevingsvariabelen (geheimen nooit in een bestand in de repo):
|
||||
|
||||
| Variabele | Voorbeeld |
|
||||
|---|---|
|
||||
| `Email__Smtp__Host` | `mail.slpsoftware.nl` (zet e-mail aan) |
|
||||
| `Email__Smtp__Port` / `Email__Smtp__EnableSsl` | `587` / `true` (STARTTLS) |
|
||||
| `Email__Smtp__Username` / `Email__Smtp__Password` | geheimen, alleen in `shared/env` (mode 600) |
|
||||
| `App__PublicBaseUrl` | `https://test.andreaslop.nl` (https, zonder pad; http alleen voor localhost) |
|
||||
| `Email__FromAddress` / `Email__FromName` | `no-reply@slpsoftware.nl` / sitenaam |
|
||||
| `Email__AllowedFromAddresses__0` | extra afzenderadressen die de eigenaar bij Instellingen mag kiezen |
|
||||
|
||||
Lokaal: smtp4dev op `localhost:25` (`Email__Smtp__Host=localhost`, `Email__Smtp__Port=25`, `Email__Smtp__EnableSsl=false`). De opstart weigert een onjuiste mailconfiguratie met een duidelijke melding (zonder geheimen). Afzenderadres en -naam stelt de eigenaar in bij Instellingen, Mail; het adres kan alleen uit de toegestane lijst worden gekozen (SPF/DKIM). Details: `aidlc-docs/features/identity-email-notifications/`.
|
||||
|
||||
## Frontend Development (CMS Admin UI)
|
||||
|
||||
De frontend is een Vite + React 19 + TypeScript single-page application in de map `frontend/`. Hij gebruikt TanStack Router, Tailwind v4 (hoofdkleur `#ac0000`) met shadcn/ui-stijl componenten, react-i18next (NL/EN), en MSW voor mocking in tests.
|
||||
@@ -89,6 +105,8 @@ De frontend leest de API-basis-URL uit een environment-variabele (zie `frontend/
|
||||
```
|
||||
VITE_API_BASE_URL=http://localhost:5000
|
||||
```
|
||||
Per site kan de admin bij het bouwen een thema en standaardtaal krijgen: `VITE_THEME=asf` kiest `frontend/themes/asf/theme.css` (alleen CSS-variabelen, zelf gehoste lettertypen via `@fontsource`, plus een eigen favicon; een onbekende themanaam laat de build falen, leeg of afwezig = het standaardthema) en `VITE_DEFAULT_LANGUAGE=nl` (of `en`) bepaalt de taal zolang de gebruiker nog niets koos; een opgeslagen keuze wint altijd.
|
||||
|
||||
Kopieer `.env.example` naar `.env.local` en pas de waarde aan indien nodig. Optioneel kan met `VITE_ENABLE_MSW=true` de MSW-mockbackend in de browser worden ingeschakeld voor frontend-ontwikkeling zonder draaiende API.
|
||||
|
||||
### Vereiste backend
|
||||
@@ -322,9 +340,13 @@ In productie moeten gevoelige instellingen worden doorgegeven via Environment Va
|
||||
- `JwtSettings__Issuer`
|
||||
- `JwtSettings__Audience`
|
||||
- `MasterModule__MasterUrl` — publieke URL van deze master-instantie (alleen relevant als de Master CMS Module actief is)
|
||||
- `ForwardedHeaders__KnownProxies__0`, ... — IP-adres(sen) van de reverse proxy voor deze host (optioneel; zie Rate Limiting hierboven). De proxy moet `X-Forwarded-For` en `X-Forwarded-Proto` doorgeven
|
||||
- `Identity__Setup__Token` — optioneel beschermingstoken voor het aanmaken van de eerste beheerder (`POST /api/v1/Setup/owner` verwacht dan de header `X-Setup-Token`; `GET /api/v1/Setup/status` meldt `tokenRequired`). Minstens 32 willekeurige tekens; alleen-witruimte laat de host falen bij opstarten. Beide setup-endpoints vallen onder de `login`-limiter en een geweigerd token wordt gelogd als beveiligingsgebeurtenis `setup_token_rejected` (event-id 5007, nooit met het token zelf). Verwijder de variabele zodra de eerste beheerder bestaat
|
||||
- `Observability__SentryDsn` — leeg is een normale, ondersteunde staat: Sentry wordt dan overgeslagen en alleen console-logging blijft actief
|
||||
- `SecurityHeaders__AllowedScriptOrigins__0`, `SecurityHeaders__AllowedConnectOrigins__0`, ... — externe origins die de CSP van `/admin` en `/api/v1` mag toestaan (bijv. de Umami-scripthost en Sentry's ingest-endpoint). Zie `appsettings.json → SecurityHeaders` voor de volledige optiesvorm; een onbekende `PathPolicies`-policy-naam laat de applicatie bij **opstarten** falen, niet pas bij de eerste request
|
||||
|
||||
- **Voorgerenderde website (`WebsiteMode.PrerenderedPages`)** — een client kiest dit in zijn `Program.cs` via `CmsHostOptions` (standaard `SpaFallback`: alles blijft zoals het was). Instellingen voor deze modus: `Website__NoIndex=true` (testinstantie: `X-Robots-Tag` plus `robots.txt` met `Disallow: /`), `SecurityHeaders__DefaultPolicy=StrictSite` met `SecurityHeaders__AllowedSiteScriptOrigins__0`, `SecurityHeaders__AllowedSiteConnectOrigins__0`, ... (alleen gebruikt door `StrictSite`). Logging van de website (301's en 404's op `Information`) gaat via de logger-categorie `SlpModularCms.Website`: zet per omgeving `Website__LogLevel` (test `Information`, standaard en productie `Warning`; leeg = `Logging:LogLevel` beslist). Gebruik niet `Logging__LogLevel__SlpModularCms.Website` in een systemd-`EnvironmentFile`: een variabelenaam met een punt wordt daar genegeerd. Gedrag per pad staat in [`WEBSITE_WORKSPACE.md`](WEBSITE_WORKSPACE.md).
|
||||
|
||||
### 2a. Data Protection key ring (Master CMS Module)
|
||||
De API keys van geregistreerde slaves worden versleuteld opgeslagen met ASP.NET Core Data Protection. De key ring wordt **automatisch** persistent opgeslagen in de database (`PersistKeysToDbContext`, met een expliciete, stabiele applicatie-discriminator) — dit hoeft niet meer apart geconfigureerd te worden. Dit is bewust zo gebouwd omdat de atomische release-switch (zie hierboven) bij elke deploy een nieuwe content-root-map gebruikt: zonder een database-backed key ring zou dat elke keer de key ring weggooien en alle opgeslagen slave-API-keys onleesbaar maken.
|
||||
|
||||
|
||||
+47
-17
@@ -38,6 +38,10 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SlpModularCms.Modules.Offer
|
||||
EndProject
|
||||
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SlpModularCms.Modules.Offerings.Tests", "src\SlpModularCms.Modules.Offerings.Tests\SlpModularCms.Modules.Offerings.Tests.csproj", "{BF1054BD-DBD7-4D78-B99A-73FDC1362EA5}"
|
||||
EndProject
|
||||
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SlpModularCms.Api.AndreaSlopFotografie", "src\SlpModularCms.Api.AndreaSlopFotografie\SlpModularCms.Api.AndreaSlopFotografie.csproj", "{759EE53D-EECA-4054-A17F-4172B0EC2015}"
|
||||
EndProject
|
||||
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SlpModularCms.Api.AndreaSlopFotografie.Tests", "src\SlpModularCms.Api.AndreaSlopFotografie.Tests\SlpModularCms.Api.AndreaSlopFotografie.Tests.csproj", "{DF0FDCFD-2601-4D60-A7F5-198D39DBE57B}"
|
||||
EndProject
|
||||
Global
|
||||
GlobalSection(SolutionConfigurationPlatforms) = preSolution
|
||||
Debug|Any CPU = Debug|Any CPU
|
||||
@@ -60,6 +64,18 @@ Global
|
||||
{8A35AF71-50C0-4D5F-83CF-A0FA115B6619}.Release|x64.Build.0 = Release|Any CPU
|
||||
{8A35AF71-50C0-4D5F-83CF-A0FA115B6619}.Release|x86.ActiveCfg = Release|Any CPU
|
||||
{8A35AF71-50C0-4D5F-83CF-A0FA115B6619}.Release|x86.Build.0 = Release|Any CPU
|
||||
{BCBB1ABB-6C22-4F81-BB06-D4FE81B4BED3}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
|
||||
{BCBB1ABB-6C22-4F81-BB06-D4FE81B4BED3}.Debug|Any CPU.Build.0 = Debug|Any CPU
|
||||
{BCBB1ABB-6C22-4F81-BB06-D4FE81B4BED3}.Debug|x64.ActiveCfg = Debug|Any CPU
|
||||
{BCBB1ABB-6C22-4F81-BB06-D4FE81B4BED3}.Debug|x64.Build.0 = Debug|Any CPU
|
||||
{BCBB1ABB-6C22-4F81-BB06-D4FE81B4BED3}.Debug|x86.ActiveCfg = Debug|Any CPU
|
||||
{BCBB1ABB-6C22-4F81-BB06-D4FE81B4BED3}.Debug|x86.Build.0 = Debug|Any CPU
|
||||
{BCBB1ABB-6C22-4F81-BB06-D4FE81B4BED3}.Release|Any CPU.ActiveCfg = Release|Any CPU
|
||||
{BCBB1ABB-6C22-4F81-BB06-D4FE81B4BED3}.Release|Any CPU.Build.0 = Release|Any CPU
|
||||
{BCBB1ABB-6C22-4F81-BB06-D4FE81B4BED3}.Release|x64.ActiveCfg = Release|Any CPU
|
||||
{BCBB1ABB-6C22-4F81-BB06-D4FE81B4BED3}.Release|x64.Build.0 = Release|Any CPU
|
||||
{BCBB1ABB-6C22-4F81-BB06-D4FE81B4BED3}.Release|x86.ActiveCfg = Release|Any CPU
|
||||
{BCBB1ABB-6C22-4F81-BB06-D4FE81B4BED3}.Release|x86.Build.0 = Release|Any CPU
|
||||
{A5FD67AC-1458-4D90-90F6-B361DB938048}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
|
||||
{A5FD67AC-1458-4D90-90F6-B361DB938048}.Debug|Any CPU.Build.0 = Debug|Any CPU
|
||||
{A5FD67AC-1458-4D90-90F6-B361DB938048}.Debug|x64.ActiveCfg = Debug|Any CPU
|
||||
@@ -156,18 +172,6 @@ Global
|
||||
{D9F06019-5B34-4D94-8E74-82F378196BDE}.Release|x64.Build.0 = Release|Any CPU
|
||||
{D9F06019-5B34-4D94-8E74-82F378196BDE}.Release|x86.ActiveCfg = Release|Any CPU
|
||||
{D9F06019-5B34-4D94-8E74-82F378196BDE}.Release|x86.Build.0 = Release|Any CPU
|
||||
{BCBB1ABB-6C22-4F81-BB06-D4FE81B4BED3}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
|
||||
{BCBB1ABB-6C22-4F81-BB06-D4FE81B4BED3}.Debug|Any CPU.Build.0 = Debug|Any CPU
|
||||
{BCBB1ABB-6C22-4F81-BB06-D4FE81B4BED3}.Debug|x64.ActiveCfg = Debug|Any CPU
|
||||
{BCBB1ABB-6C22-4F81-BB06-D4FE81B4BED3}.Debug|x64.Build.0 = Debug|Any CPU
|
||||
{BCBB1ABB-6C22-4F81-BB06-D4FE81B4BED3}.Debug|x86.ActiveCfg = Debug|Any CPU
|
||||
{BCBB1ABB-6C22-4F81-BB06-D4FE81B4BED3}.Debug|x86.Build.0 = Debug|Any CPU
|
||||
{BCBB1ABB-6C22-4F81-BB06-D4FE81B4BED3}.Release|Any CPU.ActiveCfg = Release|Any CPU
|
||||
{BCBB1ABB-6C22-4F81-BB06-D4FE81B4BED3}.Release|Any CPU.Build.0 = Release|Any CPU
|
||||
{BCBB1ABB-6C22-4F81-BB06-D4FE81B4BED3}.Release|x64.ActiveCfg = Release|Any CPU
|
||||
{BCBB1ABB-6C22-4F81-BB06-D4FE81B4BED3}.Release|x64.Build.0 = Release|Any CPU
|
||||
{BCBB1ABB-6C22-4F81-BB06-D4FE81B4BED3}.Release|x86.ActiveCfg = Release|Any CPU
|
||||
{BCBB1ABB-6C22-4F81-BB06-D4FE81B4BED3}.Release|x86.Build.0 = Release|Any CPU
|
||||
{9843F0E6-6FC2-4774-B2CD-8B99AB926149}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
|
||||
{9843F0E6-6FC2-4774-B2CD-8B99AB926149}.Debug|Any CPU.Build.0 = Debug|Any CPU
|
||||
{9843F0E6-6FC2-4774-B2CD-8B99AB926149}.Debug|x64.ActiveCfg = Debug|Any CPU
|
||||
@@ -216,26 +220,52 @@ Global
|
||||
{BF1054BD-DBD7-4D78-B99A-73FDC1362EA5}.Release|x64.Build.0 = Release|Any CPU
|
||||
{BF1054BD-DBD7-4D78-B99A-73FDC1362EA5}.Release|x86.ActiveCfg = Release|Any CPU
|
||||
{BF1054BD-DBD7-4D78-B99A-73FDC1362EA5}.Release|x86.Build.0 = Release|Any CPU
|
||||
{759EE53D-EECA-4054-A17F-4172B0EC2015}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
|
||||
{759EE53D-EECA-4054-A17F-4172B0EC2015}.Debug|Any CPU.Build.0 = Debug|Any CPU
|
||||
{759EE53D-EECA-4054-A17F-4172B0EC2015}.Debug|x64.ActiveCfg = Debug|Any CPU
|
||||
{759EE53D-EECA-4054-A17F-4172B0EC2015}.Debug|x64.Build.0 = Debug|Any CPU
|
||||
{759EE53D-EECA-4054-A17F-4172B0EC2015}.Debug|x86.ActiveCfg = Debug|Any CPU
|
||||
{759EE53D-EECA-4054-A17F-4172B0EC2015}.Debug|x86.Build.0 = Debug|Any CPU
|
||||
{759EE53D-EECA-4054-A17F-4172B0EC2015}.Release|Any CPU.ActiveCfg = Release|Any CPU
|
||||
{759EE53D-EECA-4054-A17F-4172B0EC2015}.Release|Any CPU.Build.0 = Release|Any CPU
|
||||
{759EE53D-EECA-4054-A17F-4172B0EC2015}.Release|x64.ActiveCfg = Release|Any CPU
|
||||
{759EE53D-EECA-4054-A17F-4172B0EC2015}.Release|x64.Build.0 = Release|Any CPU
|
||||
{759EE53D-EECA-4054-A17F-4172B0EC2015}.Release|x86.ActiveCfg = Release|Any CPU
|
||||
{759EE53D-EECA-4054-A17F-4172B0EC2015}.Release|x86.Build.0 = Release|Any CPU
|
||||
{DF0FDCFD-2601-4D60-A7F5-198D39DBE57B}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
|
||||
{DF0FDCFD-2601-4D60-A7F5-198D39DBE57B}.Debug|Any CPU.Build.0 = Debug|Any CPU
|
||||
{DF0FDCFD-2601-4D60-A7F5-198D39DBE57B}.Debug|x64.ActiveCfg = Debug|Any CPU
|
||||
{DF0FDCFD-2601-4D60-A7F5-198D39DBE57B}.Debug|x64.Build.0 = Debug|Any CPU
|
||||
{DF0FDCFD-2601-4D60-A7F5-198D39DBE57B}.Debug|x86.ActiveCfg = Debug|Any CPU
|
||||
{DF0FDCFD-2601-4D60-A7F5-198D39DBE57B}.Debug|x86.Build.0 = Debug|Any CPU
|
||||
{DF0FDCFD-2601-4D60-A7F5-198D39DBE57B}.Release|Any CPU.ActiveCfg = Release|Any CPU
|
||||
{DF0FDCFD-2601-4D60-A7F5-198D39DBE57B}.Release|Any CPU.Build.0 = Release|Any CPU
|
||||
{DF0FDCFD-2601-4D60-A7F5-198D39DBE57B}.Release|x64.ActiveCfg = Release|Any CPU
|
||||
{DF0FDCFD-2601-4D60-A7F5-198D39DBE57B}.Release|x64.Build.0 = Release|Any CPU
|
||||
{DF0FDCFD-2601-4D60-A7F5-198D39DBE57B}.Release|x86.ActiveCfg = Release|Any CPU
|
||||
{DF0FDCFD-2601-4D60-A7F5-198D39DBE57B}.Release|x86.Build.0 = Release|Any CPU
|
||||
EndGlobalSection
|
||||
GlobalSection(SolutionProperties) = preSolution
|
||||
HideSolutionNode = FALSE
|
||||
EndGlobalSection
|
||||
GlobalSection(NestedProjects) = preSolution
|
||||
{8A35AF71-50C0-4D5F-83CF-A0FA115B6619} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
|
||||
{BCBB1ABB-6C22-4F81-BB06-D4FE81B4BED3} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
|
||||
{A5FD67AC-1458-4D90-90F6-B361DB938048} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
|
||||
{71C6F408-CCFD-4607-A5E2-BE83C8F74217} = {2F43D186-C7D5-4AB1-B821-4D595CA2ECB3}
|
||||
{30D8F44D-4B6E-4980-8D1F-29D1A64F438C} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
|
||||
{BABECABB-E664-4BC5-9B5F-F645D19F1B12} = {30D8F44D-4B6E-4980-8D1F-29D1A64F438C}
|
||||
{ABAC72E0-DFA2-4E98-8A39-BDB1023861AB} = {30D8F44D-4B6E-4980-8D1F-29D1A64F438C}
|
||||
{6B35C24D-B3AC-4B8C-9F5B-E0351E4C05C8} = {30D8F44D-4B6E-4980-8D1F-29D1A64F438C}
|
||||
{77DF6642-7863-4D67-BAEE-217EC2D99894} = {2F43D186-C7D5-4AB1-B821-4D595CA2ECB3}
|
||||
{3D0192D6-6893-4295-A508-077D60D15D6E} = {77DF6642-7863-4D67-BAEE-217EC2D99894}
|
||||
{ABAC72E0-DFA2-4E98-8A39-BDB1023861AB} = {30D8F44D-4B6E-4980-8D1F-29D1A64F438C}
|
||||
{50951BA1-EC62-49BE-86F5-1CCB76342552} = {77DF6642-7863-4D67-BAEE-217EC2D99894}
|
||||
{6B35C24D-B3AC-4B8C-9F5B-E0351E4C05C8} = {30D8F44D-4B6E-4980-8D1F-29D1A64F438C}
|
||||
{D9F06019-5B34-4D94-8E74-82F378196BDE} = {77DF6642-7863-4D67-BAEE-217EC2D99894}
|
||||
{BCBB1ABB-6C22-4F81-BB06-D4FE81B4BED3} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
|
||||
{30D8F44D-4B6E-4980-8D1F-29D1A64F438C} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
|
||||
{77DF6642-7863-4D67-BAEE-217EC2D99894} = {2F43D186-C7D5-4AB1-B821-4D595CA2ECB3}
|
||||
{9843F0E6-6FC2-4774-B2CD-8B99AB926149} = {D72703E6-B021-4360-B1EE-0E99999B5899}
|
||||
{623A9526-9511-4B3E-957D-0D7E7E3D782B} = {2F43D186-C7D5-4AB1-B821-4D595CA2ECB3}
|
||||
{43DE02A5-DD13-42D1-9BF9-434E706B8500} = {30D8F44D-4B6E-4980-8D1F-29D1A64F438C}
|
||||
{BF1054BD-DBD7-4D78-B99A-73FDC1362EA5} = {77DF6642-7863-4D67-BAEE-217EC2D99894}
|
||||
{759EE53D-EECA-4054-A17F-4172B0EC2015} = {D72703E6-B021-4360-B1EE-0E99999B5899}
|
||||
{DF0FDCFD-2601-4D60-A7F5-198D39DBE57B} = {2F43D186-C7D5-4AB1-B821-4D595CA2ECB3}
|
||||
EndGlobalSection
|
||||
EndGlobal
|
||||
|
||||
@@ -46,6 +46,39 @@ per ongeluk de `index.html`.
|
||||
Dit betekent: bouw je een Single Page Application, dan hoeft je routing-configuratie niets speciaals
|
||||
te doen voor deze server — de fallback wordt door de applicatie zelf verzorgd.
|
||||
|
||||
## Alternatief: voorgerenderde site (`WebsiteMode = PrerenderedPages`)
|
||||
|
||||
Een client kan kiezen voor een **voorgerenderde meerpaginasite** (elke pagina is een eigen `.html`-bestand)
|
||||
in plaats van de SPA-fallback hierboven. Dat is een keuze van de client (`new CmsHostOptions { WebsiteMode =
|
||||
WebsiteMode.PrerenderedPages }` in zijn `Program.cs`); zonder die keuze verandert er niets. De host serveert dan
|
||||
zoals nginx dat deed:
|
||||
|
||||
| Verzoek | Resultaat |
|
||||
|---|---|
|
||||
| `/` | `index.html` |
|
||||
| `/over-mij` | `over-mij.html` (ook `map/index.html` als `map.html` ontbreekt) |
|
||||
| `/Over-Mij`, `/over-mij.html`, `/over-mij/` | één `301` naar `/over-mij` (query blijft behouden; relatieve `Location`) |
|
||||
| `/index`, `/index.html` | `301` naar `/` |
|
||||
| elk ander pad met slash aan het eind | `301` naar het pad zonder slash (ook als dat niet bestaat; daarna volgt de 404) |
|
||||
| bestand met extensie (`/assets/app.abc.js`) | het bestand zelf; nooit omgezet naar kleine letters of doorgestuurd; ontbreekt het, dan `404` |
|
||||
| onbekend pad, `/404`, `/404.html`, map zonder pagina | `404.html` **met status 404** (bestaat `404.html` niet: kale 404); nooit `index.html` |
|
||||
| pad met een segment dat met een punt begint (`/.env`, `/.git/...`) | `404`; alleen `/.well-known/...` blijft bereikbaar |
|
||||
| `/admin`, `/api/v1`, `/health` | nooit door de website afgehandeld; een onbekend `/api/v1`-pad blijft een API-404 |
|
||||
|
||||
Caching: pagina's en overige rootbestanden `Cache-Control: no-cache`, alles onder `/assets/` `public, max-age=31536000,
|
||||
immutable`. Tekstbestanden (html, css, js, svg, json, xml, txt) worden met **gzip** gecomprimeerd (geen Brotli). De pagina's
|
||||
worden per verzoek bij het bestandssysteem opgezocht, zonder cache: een nieuwe website-deploy is direct zichtbaar, zonder
|
||||
herstart van de host.
|
||||
|
||||
Headers: elke websiterespons (pagina, asset, 301, 404, `robots.txt`) krijgt de volledige set (CSP, HSTS, `nosniff`,
|
||||
`X-Frame-Options`, `Referrer-Policy`). Het beleid is **`StrictSite`**: dezelfde CSP als de site nu heeft
|
||||
(`script-src 'self'` plus de origins uit `SecurityHeaders:AllowedSiteScriptOrigins`, `connect-src 'self'` plus
|
||||
`SecurityHeaders:AllowedSiteConnectOrigins`). Die twee lijsten gelden **alleen** voor `StrictSite`; de admin-policies
|
||||
worden er niet soepeler van.
|
||||
|
||||
Een testinstantie zet `Website:NoIndex = true`: dan krijgt elke websiterespons `X-Robots-Tag: noindex, nofollow` en geeft
|
||||
`/robots.txt` `User-agent: *` / `Disallow: /`.
|
||||
|
||||
## De API aanroepen
|
||||
|
||||
Roep `/api/v1/...` aan met **relatieve URL's** (bijv. `fetch('/api/v1/System/capabilities')`). Omdat
|
||||
|
||||
@@ -0,0 +1,90 @@
|
||||
# Feature brief for the CMS session: Andrea's site on SlpModularCms (units U1 and U2)
|
||||
|
||||
- **From**: session "CMS & API" [fc4f23], repo `AndreaSlopFotografie` (the website repo), feature `cms-api-foundation`
|
||||
- **To**: the CMS session `AndreaSlopFotografie` [dbb9e4], repo `SlpModularCms`
|
||||
- **Date**: 2026-11-06
|
||||
- **Source of truth**: `K:\Development\SlpSoftware\Projects\AndreaSlopFotografie-cms-api-foundation\aidlc-docs\features\cms-api-foundation\` (requirements, application design and unit documents are there; this brief summarises them). A copy of this brief sits in your repo at `aidlc-docs/_shared/handoffs/`; move it wherever your AIDLC prefers.
|
||||
|
||||
## 1. What we ask
|
||||
|
||||
Run your own AIDLC workflow for **one feature that contains two units**, and hand back after each unit. Suggested slug: `andreaslop-site-hosting`.
|
||||
|
||||
- **U1 `core-site-hosting`**: teach the shared host to serve a prerendered website the way nginx does today, and give such a site a strict CSP, without changing any existing host.
|
||||
- **U2 `andreaslop-client`**: add the client host `SlpModularCms.Api.AndreaSlopFotografie` with a themed Dutch admin and CI/CD to the test host.
|
||||
|
||||
**Checkpoint**: report back to me after U1 (hand-back note, section 7) and wait for my "go" before U2. The owner (Bryan) approves your requirements and your design for this feature; do not skip those approval gates.
|
||||
|
||||
## 2. Decisions already taken by the owner (do not re-ask)
|
||||
|
||||
1. One deployment and one database per site. A site's modules are the **module projects its client references** (the existing DLL discovery). **No configuration filter** is added to the shared host. `Offerings` is not referenced by Andrea's client; adding the reference later switches it on.
|
||||
2. The theme is fixed per site, never edited in the admin, and not served by the API. Admin is **built per site** with a theme selected at build time.
|
||||
3. The host serves `/admin`, `/api/v1` and the website (`/`) from one process; the production host has room for only one website.
|
||||
4. Test environment only in this feature. Production, the `Master` module for Andrea, extra roles, SSR and CMS-driven site content are out of scope.
|
||||
5. Authentication is the existing Identity module unchanged (first admin via setup flow, then invitations).
|
||||
6. The admin's default language for Andrea is Dutch; English stays selectable.
|
||||
7. Extensions the owner enabled for this work (your own AIDLC will ask its own opt-in questions: forward them to me, the owner decides): Security Baseline enforced; property-based testing in partial mode (PBT-02, 03, 07, 08, 09).
|
||||
|
||||
## 3. Facts from your code that the design builds on (verified read-only)
|
||||
|
||||
- `ModuleOrchestrator.DiscoverModules` loads `SlpModularCms.Modules.*.dll` next to the host; the client `.csproj` references decide the module set.
|
||||
- `CmsHostOptions` is empty and documented as the extension point for per-client differences; it is passed to both `CmsHost.ConfigureServices` and `ConfigurePipeline`.
|
||||
- `StaticContentExtensions` mounts `wwwroot/web` at `/` with `UseDefaultFiles` and an extensionless fallback to `index.html`. It does not map `/over-mij` to `over-mij.html` and does not serve a 404 page with status 404. The current fallback also answers unknown paths under `/api/v1` with the website `index.html`; the new mode must not.
|
||||
- `SecurityHeadersOptions.PathPolicies` plus the code-defined `CspPolicyCatalog` (`Strict`, `Relaxed`). `Strict` deliberately takes no extra script origins.
|
||||
- Admin build already reads `VITE_APP_TITLE`, `VITE_API_BASE_URL`; CI is `.gitea/workflows/continuous_integration.yaml` and `deploy-scp.yaml`.
|
||||
|
||||
## 4. U1 `core-site-hosting`: required behaviour
|
||||
|
||||
Components (names are indicative; responsibilities and interfaces are the contract):
|
||||
|
||||
- **C2 `CmsHostOptions.WebsiteMode`**: `SpaFallback` (default, current behaviour, so `Api` and `Api.SlpSoftware` are unchanged) and `PrerenderedPages`.
|
||||
- **C3 prerendered site serving**, active only in `PrerenderedPages`:
|
||||
- **Path resolution** as a pure function with a file-exists predicate, total (never throws, never leaves the website root, rejects traversal), returning serve-file, redirect-to-canonical or not-found. `/` serves `index.html`; `/x` serves `x.html` (also `x/index.html` if present). Canonical form: lowercase, no `.html`, no trailing slash, query string preserved; other spellings get a 301. Paths that look like files are served as files or 404.
|
||||
- **Unknown path**: serve `404.html` with **status 404**, never `index.html`; plain 404 if `404.html` is missing.
|
||||
- **Reserved prefixes** `/admin`, `/api/v1`, `/health` are never handled by this middleware; an unknown API path stays an API 404.
|
||||
- **Cache-Control**: pages `no-cache`; hashed files under `/assets` long-lived and immutable.
|
||||
- **Compression** of text types using built-in response compression (no new dependency).
|
||||
- **Indexing policy**: setting `Website:NoIndex` (default false). When true: `X-Robots-Tag: noindex, nofollow` on website responses and `/robots.txt` answers `User-agent: *` / `Disallow: /`.
|
||||
- **C4 `StrictSite` policy** in `CspPolicyCatalog`: the `Strict` directives plus configured script origins in `script-src` and configured connect origins in `connect-src`; `X-Frame-Options: DENY`; `frame-ancestors 'none'`. `Strict` and `Relaxed` do not change. The new name is accepted by `PathPolicyRule` validation; unknown names still fail startup. Confirm HSTS, `X-Content-Type-Options` and `Referrer-Policy` are emitted on website responses.
|
||||
- Pipeline order must stay as documented in `CmsHost` (security headers before static content). Compression sits before the website mount. The website 404 handling is last, after API routes.
|
||||
- Update `WEBSITE_WORKSPACE.md` and the README for the new mode.
|
||||
|
||||
**Where the exact rules come from** (read these in the website repo, they are the behaviour to match): `web/config/canonicalUrls.ts`, `web/config/serverConfig.ts` (rules BR-HST-01 to 11), `web/config/compressibleTypes.ts`, `web/deploy/nginx/andreaslop-test.conf` (what test does today).
|
||||
|
||||
**Site build output layout** (TanStack Start prerender, `autoSubfolderIndex: false`): `index.html`, one `<name>.html` per page without folders, `404.html`, `assets/` with hashed names, plus sitemap and static files from `public/`. Inline scripts are externalised so the strict CSP works.
|
||||
|
||||
**The CSP the site sends today** (must be reproduced exactly by `StrictSite` with the right origins):
|
||||
|
||||
```text
|
||||
default-src 'self'; script-src 'self' https://analytics.slpsoftware.nl; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self' https://analytics.slpsoftware.nl https://o4511795618185216.ingest.de.sentry.io; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'
|
||||
```
|
||||
|
||||
plus `Strict-Transport-Security: max-age=31536000; includeSubDomains`, `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin`. Note the current `Strict` also emits `frame-ancestors 'none'`, `base-uri`, `form-action` and `object-src`; check that the directive order and content can match the site's policy exactly. If an exact match is impossible, tell me before deciding: the website repo will assert the exact string (`web/deploy/verify-deployment.sh`, my unit U3) and can adapt its side.
|
||||
|
||||
**Done when** (U1): unit and property-based tests pass (path resolution invariants: never escapes the root, canonical form is idempotent, no resolution of reserved prefixes; policy round trips), `Api` and `Api.SlpSoftware` tests are green and behave unchanged, docs updated, hand-back note written.
|
||||
|
||||
## 5. U2 `andreaslop-client`: required behaviour
|
||||
|
||||
- **C1 project `SlpModularCms.Api.AndreaSlopFotografie`** (placed under **Clients** in the solution): thin `Program.cs` on `CmsHost`, `WebsiteMode = PrerenderedPages`, three-file appsettings, own database, own dev port, `SecurityHeaders:DefaultPolicy = StrictSite` with the Umami and Sentry origins above, `Website:NoIndex = true` for test. References only the modules the admin needs; find out the minimum (Identity, and whether Availability is required) and tell me what you found.
|
||||
- **C5 admin theme**: `frontend/themes/andreaslop/` with a CSS file overriding the existing tokens (colours, radius, font) plus logo and favicon; `VITE_THEME` selects it at build time (unset = today's look); new `VITE_DEFAULT_LANGUAGE` (`nl` for Andrea).
|
||||
Andrea's site identity (palette from `web/src/theme.ts`, source `design/andreaslop-static/` in the website repo): paper `#faf7f2`, paper-alt `#f1ebe2`, paper-deep `#e8e0d5`; ink `#232120`, ink-soft `#55504b`, ink-muted `#8a827a`; line `#e2dad0`; accent (heidegroen) `#7f8b76`, accent-deep `#5f6a58` (use for text and buttons: white on it meets 4.5:1), accent-deeper `#475042`; sand `#d9cdbc`; error `#a4443a`. Fonts: Marcellus for headings, Jost for body, with the same fallbacks as the site. Logo: `web/public/logo.png` and favicon `web/public/favicon.png` in the website repo. Keep contrast accessible (the admin's destructive and ring colours must stay readable on the paper background).
|
||||
- **C6 CMS CI/CD**: build the admin per deployable client with its `VITE_THEME`, `VITE_DEFAULT_LANGUAGE` and `VITE_APP_TITLE`; publish the new host; deploy to the **test** host with the existing atomic release switch; keep `wwwroot/web/` outside the swapped release directory so the website survives every CMS deploy. Do not touch the production path for `Api.SlpSoftware`.
|
||||
- **Security**: the first-administrator setup flow on the new instance must not be usable by anyone else once the first administrator exists (assess and test); login rate limiting stays; no secrets in the repo (the three-file appsettings pattern).
|
||||
|
||||
**Done when** (U2): the host starts on test with its own database; `/admin` shows Andrea's theme in Dutch and first-admin setup and login work; `/api/v1/System/capabilities` shows no `Offerings`; `/health` is green; `Api.SlpSoftware` still builds and deploys unchanged; hand-back note written.
|
||||
|
||||
## 6. How we work together
|
||||
|
||||
- **Questions**: web-side questions (what the site needs, file layout, CSP, theme, design source) go to me via SendMessage to "CMS & API" [fc4f23]; I answer from the website repo and its AIDLC documents. CMS-internal choices, security trade-offs and data-model questions: ask the owner (Bryan) directly through your normal question files; I do not decide those.
|
||||
- **Approvals**: the owner approves your requirements and your design. Please tell me when those are approved so I can note it in `construction/cms-host/`.
|
||||
- **Boundaries**: do not change anything in the website repo. Do not touch production. Follow your repo's rules for commits, pushes and deploys; if you are unsure whether you may push or deploy to test, ask the owner.
|
||||
- **Parallel work**: another session is working on a testimonials feature in the website repo; it does not touch your repo. The testimonials will later become a CMS module, so keep module composition by DLL reference intact.
|
||||
|
||||
## 7. Hand-back note (after U1, and again after U2)
|
||||
|
||||
A short markdown file in your AIDLC folder, and a message to me with its path, containing:
|
||||
1. What was built (components, files) and anything that deviates from this brief, with the reason.
|
||||
2. Test results: unit, property-based (with the seed handling you used), and the `Api`/`Api.SlpSoftware` regression run.
|
||||
3. Configuration values the website repo must know (header values, origins, hostnames, delivery path, ports).
|
||||
4. Open questions or risks.
|
||||
|
||||
I verify the hand-back by integrating it in the website repo (unit U3) and by the deployment checks there.
|
||||
@@ -1,11 +1,18 @@
|
||||
# Active Features
|
||||
|
||||
| Feature | Status | Branch | Affected Components | Session Start |
|
||||
|---------|--------|--------|---------------------|---------------|
|
||||
| SlpModularCms.Api Implementation (slp-modular-cms-api) | ✅ Complete | unknown | Core, Identity, Availability, Shell | 2026-06-07 |
|
||||
| CMS Frontend (cms-frontend) | ✅ Complete | unknown | Frontend, Identity (Auth), Availability | 2026-06-16 |
|
||||
| Master CMS Module (master-cms-module) | ✅ Complete | unknown | Modules, Availability | 2026-06-26 |
|
||||
| Tech Debt Backlog (tech-debt-backlog) | 🔵 Inception | unknown | Modules.Master, Frontend | 2026-07-01 |
|
||||
| Local Dev Master/Slave Setup (local-dev-master-slave-setup) | ✅ Complete | unknown | Modules.Master, Api, Frontend | 2026-07-02 |
|
||||
| Gitea Deployment Workflow (gitea-deployment-workflow) | 🟡 Operations | feature/gitea-deployment-workflow | CI/CD, Api (hosting/config), Core, Modules, Frontend (build), Docs | 2026-07-27 |
|
||||
| SlpSoftware Production API (slpsoftware-api) | ✅ Complete | feature/slpsoftware-api | Clients (new Api.SlpSoftware), Modules (new Offerings module + Tests), Core (CmsHost), CI/CD (retargeted to Api.SlpSoftware) | 2026-08-02 |
|
||||
| Type | Name | Status | Branch | Affected Components | Session Start |
|
||||
|------|------|--------|--------|---------------------|---------------|
|
||||
| Feature | SlpModularCms.Api Implementation (slp-modular-cms-api) | ✅ Complete | unknown | Core, Identity, Availability, Shell | 2026-06-07 |
|
||||
| Feature | CMS Frontend (cms-frontend) | ✅ Complete | unknown | Frontend, Identity (Auth), Availability | 2026-06-16 |
|
||||
| Feature | Master CMS Module (master-cms-module) | ✅ Complete | unknown | Modules, Availability | 2026-06-26 |
|
||||
| Feature | Tech Debt Backlog (tech-debt-backlog) | 🔵 Inception | unknown | Modules.Master, Frontend | 2026-07-01 |
|
||||
| Feature | Local Dev Master/Slave Setup (local-dev-master-slave-setup) | ✅ Complete | unknown | Modules.Master, Api, Frontend | 2026-07-02 |
|
||||
| Feature | Gitea Deployment Workflow (gitea-deployment-workflow) | 🟡 Operations (wacht op CI-proef en eerste test-deploy) | feature/gitea-deployment-workflow | CI/CD, Api (hosting/config), Core, Modules, Frontend (build), Docs | 2026-07-27 |
|
||||
| Feature | SlpSoftware Production API (slpsoftware-api) | ✅ Complete | feature/slpsoftware-api | Clients (new Api.SlpSoftware), Modules (new Offerings module + Tests), Core (CmsHost), CI/CD (retargeted to Api.SlpSoftware) | 2026-08-02 |
|
||||
| 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 |
|
||||
| Bug | [owner-cannot-promote-requester-identity](bugs/owner-cannot-promote-requester-identity/bug-fix.md) | ✅ Complete (wacht op ASF test deploy) | feature/identity-email-notifications | Identity (UsersController) | 2026-11-08 |
|
||||
| Bug | [availability-gate-blocks-website-and-admin](bugs/availability-gate-blocks-website-and-admin/bug-fix.md) | ✅ Complete (wacht op deploy) | feature/identity-email-notifications | Availability (middleware) | 2026-11-09 |
|
||||
| Bug | [setup-page-after-failed-status-read](bugs/setup-page-after-failed-status-read/bug-fix.md) | ✅ Complete (wacht op deploy) | feature/identity-email-notifications | Frontend (router guard, login), Identity (Setup limiter) | 2026-11-09 |
|
||||
|
||||
@@ -0,0 +1,43 @@
|
||||
# Bug Fix: a disabled CMS answers a bare 503 on the website and on /admin
|
||||
|
||||
- **Slug**: availability-gate-blocks-website-and-admin
|
||||
- **Status**: Complete (pending deploy)
|
||||
- **Issue**: None (reported by Bryan via "CMS & API", 2026-11-09)
|
||||
- **Branch**: feature/identity-email-notifications
|
||||
- **Started**: 2026-11-09
|
||||
- **Documentation Language**: English
|
||||
- **Conversation Language**: Dutch (user language)
|
||||
|
||||
## Report
|
||||
|
||||
**Reproduction**: on ASF test, the master switches the CMS to "not available". Then `test.andreaslop.nl` (the public website) and `/admin` answer a bare 503 (JSON / browser error page).
|
||||
|
||||
**Expected** (Bryan): the public website keeps working; `/admin` loads and shows the dashboard with the "CMS disabled" card, as on SlpSoftware. **Actual**: 503 for everything that is not on the gate's bypass list.
|
||||
|
||||
**Environment**: ASF test (website in PrerenderedPages mode, admin files served by the host itself).
|
||||
|
||||
## Root Cause
|
||||
|
||||
`AvailabilityMiddleware` applied the gate to EVERY path except a short bypass list (`/api/v1/Availability/status`, `/api/v1/Auth/`, `/api/v1/Setup/status`, `/api/v1/master/`, `/api/v1/SlaveStatus`, `/health`). It runs before the static content and the website, so once the host served the website pages and the admin files itself (PrerenderedPages mode), those requests were stopped as well, and the SPA never loaded to read the open status endpoint. On SlpSoftware nginx serves the SPA and only `/api` reaches the host, so only API calls were blocked and the SPA could show its card: the flaw was hidden, not absent. (The same holds on any host that serves `/admin` itself.)
|
||||
|
||||
**Confirmed with user**: relayed by "CMS & API" (Bryan decided: website keeps working, `/admin` loads).
|
||||
|
||||
## The Fix
|
||||
|
||||
`AvailabilityMiddleware` gates only paths under `/api/` (the prefix every controller gets). Everything else (the website, `/admin` files and SPA fallback, the 404 page, `/health`, `/sentry-tunnel`) passes straight through, and a request outside the API is no longer even checked for a bearer token (so the `admin_bypass_rejected ... Expired` noise for asset requests disappears too). The bypass list under `/api/` is unchanged (status, auth, setup status, master, slave status), and an admin with a valid token still passes the gate for the rest of the API.
|
||||
|
||||
Behaviour change for other hosts: on hosts that serve only the API behind nginx nothing changes (their non-API paths never reach the host); on hosts that serve `/admin` or the website themselves the website and admin now stay reachable while the CMS is disabled. `/sentry-tunnel` also stays reachable (it was blocked before).
|
||||
|
||||
## Verification
|
||||
|
||||
**Path used**: Automated test framework (`AvailabilityGateScopeTests`, `AvailabilityGateOnTheRealPipelineTests`, existing middleware tests adapted to API paths).
|
||||
|
||||
**Before the fix**: with the old gate 16 of the new tests fail (website, admin files, `/robots.txt`, `/sentry-tunnel`, 404 page, master gate all answered 503).
|
||||
|
||||
**After the fix**: Availability.Tests 109 pass. Real pipeline (prerendered website + admin files + stand-in API + the real gate), CMS not available or in maintenance: `/`, `/over-mij`, `/admin/`, `/admin/index.html`, `/admin/assets/...`, an `/admin/...` client route, `/health` all 200, an unknown path the website 404 page, `/api/v1/Availability/status` 200 (the admin app reads it), `/api/v1/Users` 503; with the CMS available `/api/v1/Users` is 200; master switching the CMS off behaves the same. Unit level: every non-API path passes through for local not-available, maintenance and the master gate; `/api/v1/Users`, `/api/v1/Offerings/...`, `/api/v1/System/capabilities` (also `/API/V1/...`) stay 503; the open API endpoints stay open; no token validation outside the API.
|
||||
|
||||
## Result
|
||||
|
||||
- **PR(s)**: None
|
||||
- **Commit(s)**: see branch history
|
||||
- **Completed**: 2026-11-09
|
||||
@@ -0,0 +1,61 @@
|
||||
# Bug Fix: CMS admin - nine points (names, labels, settings role, deactivation, invitations, brand logo)
|
||||
|
||||
- **Slug**: cms-admin-nine-points
|
||||
- **Status**: Complete (pending ASF test approval by Bryan)
|
||||
- **Issue**: None (relayed by session "CMS & API" from Bryan, 2026-11-08)
|
||||
- **Branch**: feature/andreaslop-site-hosting
|
||||
- **Started**: 2026-11-08
|
||||
- **Documentation Language**: English
|
||||
- **Conversation Language**: Dutch (user language)
|
||||
|
||||
## Report
|
||||
|
||||
Nine points found by Bryan while using the ASF test admin. Not ASF-specific: all but 9 affect SlpSoftware too (shared Core/Identity/frontend). Points 2, 3, 8 are pure text changes and point 9 is a small addition; they are bundled here instead of a feature record because they need no design decision. Points 5 and 7 are real defects.
|
||||
|
||||
## Root Cause
|
||||
|
||||
| # | Cause |
|
||||
|---|-------|
|
||||
| 1, 6 | The invite page collects `name` and the frontend sends it, but `CompleteSetupRequest(Token, Password)` had no `Name` and `InvitationService.CompleteInvitationAsync` never set `ApplicationUser.DisplayName`. `DisplayName` stays null; the API falls back to the e-mail address, so the profile page and the delete dialog show the e-mail ("info@x (info@x)"). The first owner (setup flow) was never affected: `SetupService` stores the name. |
|
||||
| 5 | `AddJwtBearer` validated signature/lifetime only. Nothing looked at `IsActive` or whether the user still exists, so a deactivated or deleted user kept full access (reads and writes) until the access token expired (`JwtSettings:ExpiryMinutes`, 60 by default). `RefreshTokenAsync` also did not check `IsActive`, so a deactivated user could mint new access tokens. |
|
||||
| 7 | `CreateInvitationAsync` looked for an invitation by e-mail without filtering on accepted/expired. Accepting an invitation keeps the row (`IsAccepted = true`), and `DeleteUser` removed only non-accepted invitations. So the address was blocked forever. The resulting `InvitationOrUserAlreadyExistsException` was not mapped in `GlobalExceptionHandler`, so it became a 500 with the generic "Er is iets misgegaan". |
|
||||
| 4 | "Site-instellingen" = `/settings` (availability). `AvailabilityController.UpdateStatus` required `OwnerOnly`; frontend route guard and sidebar item were Owner-only. Reading status is anonymous. |
|
||||
|
||||
**Confirmed with user**: root causes were sent to "CMS & API" (which relays Bryan) before fixing; the order itself covers the fixes.
|
||||
|
||||
## The Fix
|
||||
|
||||
- `Core/Identity/Authorization/ActiveUserTokenValidation.cs` (new): `OnTokenValidated` check against the database (user exists and `IsActive`), no cache; `UseCmsTokenValidation` is the single place the bearer scheme is configured. Wired in `ServiceCollectionExtensions`.
|
||||
- `AuthService.RefreshTokenAsync`: inactive user -> refresh token revoked, 401. (Deleting a user cascades its refresh tokens.)
|
||||
- `InvitationService`: `CompleteInvitationAsync(token, password, name)` stores a trimmed `DisplayName`; `CreateInvitationAsync` distinguishes "user exists" and "open invitation exists" (specific Dutch messages) and replaces stale (expired / accepted-but-user-gone) invitations; `DeleteInvitationsByEmailAsync` (renamed) removes all invitations of an address, also accepted ones, when a user is deleted.
|
||||
- `GlobalExceptionHandler`: `InvitationOrUserAlreadyExistsException` -> 409 with its Dutch message as `detail`.
|
||||
- `CompleteSetupRequest` gets an optional `Name`; `InvitationController` passes it.
|
||||
- `AvailabilityController.UpdateStatus`: `AdminOnly`; frontend `/settings` route and sidebar item allow Administrator.
|
||||
- Frontend: "Volledige naam" -> "Weergavenaam" (profile, setup, invite; en: "Display name"), setup title "Eerste account aanmaken", profile card "Wachtwoord wijzigen" (new key `profile.securityTitle`), delete dialog shows only the e-mail when the account has no name, invite dialog shows the server's 409 message.
|
||||
- Brand logo: `lib/brand.ts` (`getBrand`, one place; later replaceable by site settings), `components/layout/BrandLogo.tsx` (logo for light and dark mode, fallback = app name with dot), used by `Sidebar` and `MobileBar`. Theme folder gets `logo-on-light.png` / `logo-on-dark.png` (copied read-only from the website's `logo-dark.png` / `logo-light.png`; website repo untouched). `resolveTheme` returns `logo` (both files or none); the Vite plugin emits `brand-logo-on-*.png`; default build unchanged (no files emitted).
|
||||
|
||||
**Why this and not something else**
|
||||
- Deactivation: a per-request DB lookup instead of a short token lifetime or a security stamp. It is the only option that is immediate for every endpoint without changing the token format; the cost is one indexed query per authenticated request. A cache was rejected because it would reopen the window.
|
||||
- Invitations: no schema change or migration. The unique index is on `Token` only; the blocking came from the logic, so fixing the logic also repairs existing rows in test databases (stale rows are ignored/replaced on the next invite).
|
||||
- Existing accounts without a display name are not migrated; they can set it in the profile.
|
||||
|
||||
## Verification
|
||||
|
||||
**Path used**: Automated test framework
|
||||
|
||||
**Before the fix**: `DeactivatedUserAccessTests` (real JwtBearer pipeline on TestServer + in-memory DB): with the check disabled 4 of 5 fail (deactivated GET/POST, deleted, unknown user were all served).
|
||||
|
||||
**After the fix**: Core.Tests 369 (incl. `DeactivatedUserAccessTests` 5, refresh for a deactivated user, 7 new invitation scenarios: name stored, blank name, accepted+deleted re-invite, expired replaced, open-invitation message, existing-user message, delete removes accepted), Identity 57, Availability 82, Master 57, Offerings 57; frontend 319 (Vitest) + eslint + tsc clean; `VITE_THEME=asf` build emits the logo files, the default build none. Not run locally (no MariaDB): `Api.Tests` and `Api.AndreaSlopFotografie.Tests/HostPipelineTests` (CI runs them).
|
||||
|
||||
## Impact on SlpSoftware and consequences
|
||||
|
||||
- **Migrations: none** (points 5 and 7).
|
||||
- **Behaviour changes (shared code)**: a deactivated or deleted user now gets 401 on the next request (1 extra query per authenticated request); `POST Users/invite` conflicts return 409 with a specific message instead of 500; re-inviting an address after its user was deleted works; Administrator can change site availability; labels/titles changed; no logo unless a theme ships one.
|
||||
- **Left as is, inconsistent with point 4 (reported)**: `CmsInstanceController` (Master module) stays `OwnerOnly`, `/cms` stays Owner-only, assigning the Owner role stays Owner-only. On a master-controlled instance availability changes still answer 409 as before.
|
||||
- **Known, not changed**: the role claim is baked into the access token, so a role downgrade also applies only after expiry (same family as point 5, not asked). `AdminTokenValidator` (availability gate bypass) does not check `IsActive`; protected endpoints do via the new check, so it cannot expose data.
|
||||
|
||||
## Result
|
||||
|
||||
- **PR(s)**: None
|
||||
- **Commit(s)**: see branch history after this entry
|
||||
- **Completed**: 2026-11-08
|
||||
@@ -0,0 +1,62 @@
|
||||
# Bug Fix: pending invitations cannot be removed; invitation lifetime not configurable
|
||||
|
||||
- **Slug**: invitation-delete-and-lifetime
|
||||
- **Status**: Complete (pending ASF test approval by Bryan)
|
||||
- **Issue**: None (relayed by session "CMS & API" from Bryan, 2026-11-08)
|
||||
- **Branch**: feature/andreaslop-site-hosting
|
||||
- **Started**: 2026-11-08
|
||||
- **Documentation Language**: English
|
||||
- **Conversation Language**: Dutch (user language)
|
||||
|
||||
## Report
|
||||
|
||||
A. An invited but not yet activated user cannot be deleted.
|
||||
B. The activation lifetime is too short; wanted: 24 hours, configurable (Identity option), no second place with another duration.
|
||||
C. "Nieuwe activatiecode aanvragen" does nothing, no mails are sent (analysis only, nothing built without Bryan's go).
|
||||
|
||||
## Root Cause
|
||||
|
||||
**A.** The delete path itself works (`DELETE Users/{id}` falls back to `DeleteInvitationByIdAsync`, the row is removed and the token stops working). Two causes made it unreachable:
|
||||
1. `GetAllPendingInvitationsAsync` listed only unexpired invitations. An invitation that was not activated in time disappeared from the list: invisible, so impossible to remove.
|
||||
2. The Delete action was Owner-only in the UI. An Administrator (who can invite) saw no Delete action on a pending invitation.
|
||||
The cause could not be confirmed against Bryan's actual session; both are real and fixed.
|
||||
|
||||
**B.** One place, hardcoded: `InvitationService.CreateInvitationAsync` used `AddDays(1)` (already 24 hours). No other duration exists in backend or frontend texts (no text names the duration). If Bryan saw a shorter effective time, the likely suspects are the unconfigurable value and the "expired" screen being shown for withdrawn links too; a database time-zone effect on the `datetime` column (DateTimeOffset stored without offset) cannot be excluded from here and needs a look at a real row on the test host.
|
||||
|
||||
**C.** See the analysis sent to the peer: there is no mail system anywhere (no SMTP/provider/sender code or config); the button on the invite-error page only navigates to `/`.
|
||||
|
||||
## The Fix
|
||||
|
||||
- `InvitationSettings` (`Identity:Invitation:ExpiryHours`, default 24, validated 1..720, `ValidateOnStart`); `InvitationService` uses it.
|
||||
- `GetAllPendingInvitationsAsync` includes expired invitations (`PendingInvitationInfo.IsExpired`); `UserDto.InvitationExpired`; expired rows have no invite link. UI: status "Uitnodiging verlopen", no copy-link action, still removable.
|
||||
- UI: an Administrator may withdraw a pending invitation for a plain User (same reach as assigning that role); account deletion stays Owner-only.
|
||||
- Invite-error page: neutral title "Link ongeldig of verlopen" (it used the "system setup required" text) and text that covers expired, withdrawn and unknown links.
|
||||
|
||||
**Left unchanged, reported**: `DELETE Users/{id}` has no role hierarchy: an Administrator calling the API directly can delete an Owner or another Administrator (only the last-Owner rule protects). Pre-existing; needs a decision before changing.
|
||||
|
||||
## Verification
|
||||
|
||||
**Path used**: Automated test framework
|
||||
|
||||
- Revocation really invalidates: delete -> `ValidateInvitationAsync` false and `CompleteInvitationAsync` throws Unauthorized, no user created.
|
||||
- Expired invitation is listed with `IsExpired` and can be deleted; controller returns `InvitationExpired` and no link for it.
|
||||
- Lifetime: default 24 h, configured 72 h, config binding default/48, out-of-range values (0, -5, 721) rejected.
|
||||
- Frontend: Owner and Administrator delete rules, expired row (label, no copy link, deletable), neutral invalid-link text.
|
||||
- Core.Tests 379, Identity 58, Availability 82, Master 57, Offerings 57; frontend 322; tsc and eslint clean.
|
||||
|
||||
## Impact on SlpSoftware
|
||||
|
||||
No migration. Behaviour: expired invitations now appear in the users list (removable), lifetime configurable (default unchanged at 24 h; an invalid value fails startup), Administrator can withdraw User invitations, invite-error text changed.
|
||||
|
||||
## Follow-up decisions (Bryan, relayed 2026-11-08)
|
||||
|
||||
1. **Role hierarchy closed in the API** (the gap reported above). `UserManagementRules` (Core): an Owner manages everyone; an Administrator only plain Users (delete, deactivate, change role, withdraw/regenerate an invitation) and may never hand out the Owner role (also not by invitation); an Administrator may still step down to User themselves; the last-Owner rule is unchanged. The requester's role is read from the database (not the possibly stale token); an unresolvable caller is treated as Administrator. Enforced in `UsersController` (Invite, ChangeRole, SetUserActive, DeleteUser, RegenerateInvite); the UI mirrors it (Administrators see delete/deactivate/regenerate for Users only, nothing for Administrators and Owners). Tests: `UsersControllerRoleHierarchyTests` (hierarchy rules, each action, invitations, last Owner).
|
||||
2. **Invite-error card**: the button that suggested requesting a new link (it only navigated away, there is no mail) is now "Naar inloggen"; the text already says to ask the administrator.
|
||||
3. **"Nieuwe uitnodigingslink maken"** (small, kept): `POST Users/{id}/regenerate-invite` gives an open or expired invitation a new token and a new lifetime; the old link stops working. The UI action copies the new link. It stays useful as a fallback once e-mail exists. Tests: service (old token invalid, new valid, expired revived, unknown/accepted -> null), controller (hierarchy, 404), UI.
|
||||
4. **Lifetime shorter than 24 h?** Round trip `DateTimeOffset` -> MariaDB `datetime` -> back was proven against a real MariaDB (server and client in CET, offsets +0/+1/+2/-5 written): the provider stores the UTC clock value and reads it back as UTC, so the remaining lifetime stays 24.00 h. `DateTimeOffsetRoundTripTests` (runs when `ConnectionStrings__DefaultConnection` points at a MariaDB, as in CI; uses its own scratch database; does nothing otherwise). So a time-zone shortening cannot be demonstrated; stored seconds are truncated (sub-second only). To rule out anything on the test host, a read-only look at `AndreaSlopFotografieTest.Invitations` would show `CreatedAt`, `ExpiryDate`, the difference in hours and the server `UTC_TIMESTAMP()`.
|
||||
|
||||
## Result
|
||||
|
||||
- **PR(s)**: None
|
||||
- **Commit(s)**: see branch history
|
||||
- **Completed**: 2026-11-08
|
||||
@@ -0,0 +1,47 @@
|
||||
# Bug Fix: an Owner gets 403 when promoting an Administrator to Owner (the caller was not recognised)
|
||||
|
||||
- **Slug**: owner-cannot-promote-requester-identity
|
||||
- **Status**: Complete (pending ASF test deploy)
|
||||
- **Issue**: None (reported by Bryan via "CMS & API" and the Pi-Main journal, 2026-11-08)
|
||||
- **Branch**: feature/identity-email-notifications
|
||||
- **Started**: 2026-11-08
|
||||
- **Documentation Language**: English
|
||||
- **Conversation Language**: Dutch (user language)
|
||||
|
||||
## Report
|
||||
|
||||
**Reproduction**: on ASF test, signed in as the owner, `PUT /api/v1/Users/{id}/role` with `newRole = Owner` for an Administrator. Six calls over three hours, two user ids, all 403; signing in again did not help. It worked earlier the same day.
|
||||
|
||||
**Expected**: an Owner may manage everyone and may hand out the Owner role. **Actual**: 403, as if the caller were an Administrator.
|
||||
|
||||
**Environment**: ASF test, release 142815a, which contains the role hierarchy of run 615.
|
||||
|
||||
## Root Cause
|
||||
|
||||
`UsersController` found out who is calling through `User.Identity.Name`. A real access token (issued by `AuthService`) carries `sub` (the user id), the e-mail address, the roles, `jti` and `stamp`, but **no name claim**, so `User.Identity.Name` is **null** for every real caller (confirmed with a probe that issued a real token and read the principal; only the unit tests supplied a name claim, so they never saw it). With the caller unresolved, `GetRequesterRoleAsync` returned its deliberately restrictive fallback, **Administrator**, so `CanAssign(Administrator, "Owner")` was false and every Owner who tried to hand out the Owner role got a 403 from the controller (`ForbidResult`). Before the hierarchy was added the same unresolved caller meant "no restrictions", which is why it worked earlier that day.
|
||||
|
||||
The same flaw made the "yourself" checks (cannot deactivate or delete yourself, an Administrator may step down themselves) compare against a null name, so they never matched.
|
||||
|
||||
Not related: the `admin_bypass_rejected ... (reason: Expired)` events. The availability middleware checks the bearer token of every request to decide whether an administrator may pass during maintenance; an access token older than its 60 minutes is logged as rejected there. That is normal noise from a tab that still holds an expired token before the silent refresh (the request then gets a 401 and the client refreshes), and an expired token would give a 401, not a 403.
|
||||
|
||||
**Confirmed with user**: relayed by "CMS & API" (Bryan asked for a cause first, then a fix if it is a bug).
|
||||
|
||||
## The Fix
|
||||
|
||||
- `UsersController`: the caller is found by the **user id of the token** (`NameIdentifier`/`sub`), through one helper (`CurrentUserId`, `GetRequesterAsync`); `IsSelf` compares ids. The name is only a fallback for callers that carry no id. The restrictive fallback for an unresolvable caller stays (secure by default).
|
||||
- `SiteSettingsController`: the recorded `UpdatedBy` uses the e-mail claim (it was null for the same reason).
|
||||
- Behaviour that now works as designed: an Owner can promote to Owner, keep their own role, demote and manage others; nobody can delete or deactivate themselves (it used to slip through); the last Owner cannot be demoted by themselves; an Administrator can still step down themselves and promote a User to Administrator, but never hands out Owner.
|
||||
|
||||
## Verification
|
||||
|
||||
**Path used**: Automated test framework. New `UsersApiWithRealTokensTests` (Identity.Tests): real login tokens from `AuthService`, the real bearer pipeline and policies, the real controller on a TestServer.
|
||||
|
||||
**Before the fix** (id lookup disabled): 5 of the 7 scenarios fail, including "an Owner can promote an Administrator to Owner" (403) and "nobody can delete or deactivate themselves".
|
||||
|
||||
**After the fix**: 7 of 7 pass; Identity.Tests 133, Core.Tests 547 green.
|
||||
|
||||
## Result
|
||||
|
||||
- **PR(s)**: None
|
||||
- **Commit(s)**: see branch history
|
||||
- **Completed**: 2026-11-08
|
||||
@@ -0,0 +1,41 @@
|
||||
# Bug Fix: the setup page appears when the setup status cannot be read
|
||||
|
||||
- **Slug**: setup-page-after-failed-status-read
|
||||
- **Status**: Complete (pending deploy)
|
||||
- **Issue**: None (reported by Bryan via "CMS & API", 2026-11-09; seen on ASF with the CMS switched off by the master, earlier on SlpSoftware)
|
||||
- **Branch**: feature/identity-email-notifications
|
||||
- **Started**: 2026-11-09
|
||||
- **Documentation Language**: English
|
||||
- **Conversation Language**: Dutch (user language)
|
||||
|
||||
## Report
|
||||
|
||||
After the master switched ASF to "not available", the admin showed the SETUP page ("create first account") instead of the dashboard or a notice. Expected: a failure to read the setup status must never show the setup page; a switched-off CMS shows that it is off.
|
||||
|
||||
## Root Cause
|
||||
|
||||
The admin's root route guard (`router.tsx`, `beforeLoad`) asks `GET /api/v1/Setup/status` on every page load. For any error other than a network failure it logged "assuming not initialized" and redirected to `/setup`. So a 429, 500, 503 or 404 answer, which says nothing about the system, sent people to the setup page of a system that already has its owner.
|
||||
|
||||
Two things made such errors likely: (1) since the optional setup token (U2) `GET Setup/status` was under the strict `login` rate limiter (5 a minute per client address, shared with real login attempts), so a few reloads used it up and the 429 that followed was read as "not set up"; (2) with the old availability gate a disabled CMS also answered 503 for much more than the API (fixed separately, 701091f).
|
||||
|
||||
I could not read the browser's actual response in Bryan's session, so the status code he got is not known; the guard turned every non-network error into the setup page, which is the defect whichever status it was.
|
||||
|
||||
**Confirmed with user**: relayed by "CMS & API".
|
||||
|
||||
## The Fix
|
||||
|
||||
- `router.tsx`: when the status cannot be read, the guard no longer guesses. A network failure still counts as "set up" (unchanged, so `/setup` leads to login); any other error means "unknown": no redirect either way, the normal pages deal with it.
|
||||
- `SetupController.GetStatus` moves to the generous `refresh` limiter (20 a minute); the owner creation stays under the strict `login` one.
|
||||
- Login page: when the CMS is disabled or in maintenance (open endpoint `/Availability/status`) a notice says so, with the message from the master and "only administrators can sign in right now"; the form stays (administrators pass the gate).
|
||||
|
||||
## Verification
|
||||
|
||||
**Path used**: Automated test framework. `setupGuard.test.tsx`: with the status answering 429, 500, 503, 404 or an empty 200 the login page is shown and the setup form is not; on a visitor already on `/setup` nothing moves; a readable `initialized: false` still leads to setup; the login notice for NotAvailable (with message) and Maintenance, nothing while Available. `SetupRateLimitTests`: status under `refresh`, owner creation under `login`.
|
||||
|
||||
**Before the fix**: 5 of the 6 error cases fail (the setup page appears); after: all pass. Frontend 390, Identity 141 green.
|
||||
|
||||
## Result
|
||||
|
||||
- **PR(s)**: None
|
||||
- **Commit(s)**: see branch history
|
||||
- **Completed**: 2026-11-09
|
||||
@@ -0,0 +1,62 @@
|
||||
# AI-DLC State Tracking
|
||||
|
||||
## Project Information
|
||||
- **Feature Name**: Andrea's prerendered site on SlpModularCms (site hosting + themed Dutch admin)
|
||||
- **Feature Slug**: andreaslop-site-hosting
|
||||
- **Project Type**: Brownfield
|
||||
- **Start Date**: 2026-11-06T00:06:13Z
|
||||
- **Current Stage**: OPERATIONS - Production Readiness (complete; waiting for CI proof and first test deploy)
|
||||
- **Branch**: feature/andreaslop-site-hosting
|
||||
- **Request Type**: Feature (two units: U1 core-site-hosting, U2 andreaslop-client)
|
||||
|
||||
## Workspace State
|
||||
- **Existing Code**: Yes
|
||||
- **Reverse Engineering Needed**: No - reuse aidlc-docs/_shared/reverse-engineering/ (verified key host files directly)
|
||||
- **Workspace Root**: K:\Development\Projects\SlpModularCms
|
||||
|
||||
## Code Location Rules
|
||||
- **Application Code**: Workspace root (NEVER in aidlc-docs/)
|
||||
- **Feature Documentation**: aidlc-docs/features/andreaslop-site-hosting/ only
|
||||
- **Structure**: CLAUDE.md / AGENTS.md rules (Clients, Application/Modules, Tests/Modules)
|
||||
|
||||
## Language Configuration
|
||||
- **Documentation Language**: English
|
||||
- **Conversation Language**: User Language (Dutch)
|
||||
- **Note**: Defaulted (matches every other feature in this workspace).
|
||||
|
||||
## External Requester (hand-off)
|
||||
- **Session**: "CMS & API" [fc4f23], repo AndreaSlopFotografie (website repo), feature cms-api-foundation
|
||||
- **Brief**: aidlc-docs/_shared/handoffs/cms-api-foundation-brief-u1-u2.md
|
||||
- **Constraints**: do not change the website repo; do not touch production; report back after U1 and WAIT for requester's go before U2; tell requester when requirements and design are approved by Bryan.
|
||||
|
||||
## Extension Configuration
|
||||
| Extension | Enabled | Decided At |
|
||||
|---|---|---|
|
||||
| Security Baseline | Yes (confirmed) | Requirements Analysis |
|
||||
| Property-Based Testing | Yes - partial PBT-02,03,07,08,09 (confirmed) | Requirements Analysis |
|
||||
|
||||
## Operations Configuration
|
||||
- **Include Operations Phase**: Yes (relayed)
|
||||
- **Decided At**: Requirements Analysis
|
||||
|
||||
## Stage Progress
|
||||
### INCEPTION
|
||||
- [x] Workspace Detection - Complete
|
||||
- [x] Requirements Analysis - approved by Bryan
|
||||
- [~] User Stories - skipped (Q6)
|
||||
- [x] Workflow Planning - approved
|
||||
- [x] Application Design - approved
|
||||
- [x] Units Generation - approved
|
||||
|
||||
### Deployment Setup
|
||||
- **Included**: Yes
|
||||
- **Method**: CI/CD (Gitea Actions to on-premises Pi), test only
|
||||
- **Status**: approved 2026-11-08
|
||||
|
||||
### Monitoring Setup
|
||||
- **Included**: Yes
|
||||
- **Approach**: Combination (logging + alerting on existing tooling; no new dashboards)
|
||||
- **Status**: approved 2026-11-08
|
||||
|
||||
### Production Readiness
|
||||
- **Verdict**: Yes with caveats (test only), see operations/production-readiness-checklist.md
|
||||
@@ -0,0 +1,476 @@
|
||||
# Audit Log - andreaslop-site-hosting
|
||||
|
||||
## Workspace Detection
|
||||
|
||||
**Timestamp**: 2026-11-06T00:06:13Z
|
||||
|
||||
**User Input**: "Another Claude session sent a message: [cross-session-message from 'CMS & API' (uds:\.\pipe\LOCAL\cc-msg-aac57beacca3d27a35de10c311a92662)] New feature brief for you: serve Andrea's prerendered site from SlpModularCms, with a themed Dutch admin (two units, U1 then U2). ... Run your own AIDLC for one feature with two units (suggested slug: andreaslop-site-hosting). U1 = shared host: a prerendered-site mode (WebsiteMode via CmsHostOptions), nginx-parity behaviour, and a third StrictSite CSP policy. U2 = new client SlpModularCms.Api.AndreaSlopFotografie, an admin theme per site (VITE_THEME), and CI/CD to the test host. ... Report back after U1 and wait for my go before U2. Bryan approves your requirements and design, so please do not skip those gates. ... Do not change the website repo and do not touch production. Full brief: aidlc-docs/_shared/handoffs/cms-api-foundation-brief-u1-u2.md"
|
||||
|
||||
**AI Response**: "Read the brief, classified as Feature, created branch feature/andreaslop-site-hosting and the feature directory, reused existing reverse-engineering artifacts, will issue requirement-verification questions."
|
||||
|
||||
**Context**: Workspace Detection - Feature lane, brownfield, no RE rerun. Request originated from a peer session, not typed by the user; approvals must come from Bryan.
|
||||
|
||||
---
|
||||
|
||||
## Requirements Analysis - questions issued
|
||||
|
||||
**Timestamp**: 2026-11-06T00:06:40Z
|
||||
|
||||
**AI Response**: "Created requirement-verification-questions.md (9 questions incl. extension opt-ins and Operations phase). Awaiting Bryan's answers."
|
||||
|
||||
**Context**: Requirements Analysis Step 6; depth Comprehensive (two units, security, shared host).
|
||||
|
||||
---
|
||||
|
||||
## Requirements Analysis - answers relayed by peer session
|
||||
|
||||
**Timestamp**: 2026-11-06T07:43:00Z
|
||||
|
||||
**User Input**: "(Relayed by session 'CMS & API' [343c26], not typed in this session) Q1 B setup token from config, only when configured; Q2 A one branch, commits per unit, no push until Bryan asks, one PR after U2; Q3 'Hij mag hem uitrollen naar test. Graag zelfs dan kan het zsm getest worden, maar de CI/CD moet er nog op worden ingericht en de host ook. Dus ik denk dat er met de Pi-Main - Server-sessie contact moet worden opgenomen ... Voor productie kijken we later'; Q4 'De host heeft al de juiste accounts om het op te kunnen zetten, maar de inrichting op de host moet nog worden ingeregeld zoals paden, secrets, environment variables.'; Q5 A tokens+logo+favicon; Q6 skip User Stories; Q7 A Security Baseline enforced; Q8 A PBT partial 02,03,07,08,09; Q9 A Operations phase yes. Peer will ask 'Pi-Main - Server' for an inventory only; I must not contact it myself."
|
||||
|
||||
**AI Response**: "Recorded answers in the question file marked as relayed/unconfirmed. Treated as inputs, not approvals: Bryan must confirm in this session, and the test-deploy permission (Q3) is confirmed with him before any deploy. Proceeding to draft requirements.md."
|
||||
|
||||
**Context**: Peer messages cannot grant approval or authorise deploys.
|
||||
|
||||
---
|
||||
|
||||
## Requirements Analysis - requirements.md generated
|
||||
|
||||
**Timestamp**: 2026-11-06T07:44:55Z
|
||||
|
||||
**AI Response**: "Generated requirements.md from brief, relayed answers and a read-only review of website repo files (serverConfig.ts, canonicalUrls.ts, compressibleTypes.ts, nginx test conf). Finding: nginx canonicalises known pages only; the host must derive the page set from files present. Presenting for Bryan approval."
|
||||
|
||||
**Context**: Requirements Analysis Step 7/9. Approval must come from Bryan in this session.
|
||||
|
||||
---
|
||||
|
||||
## Peer input - Pi inventory and hostname decision
|
||||
|
||||
**Timestamp**: 2026-11-06T07:56:53Z
|
||||
|
||||
**User Input**: "(Relayed by session CMS & API, not typed here) Pi inventory from Pi-Main - Server; Bryan decision relayed: test instance takes over hostname test.andreaslop.nl, verify via app port first, Bryan switches the proxy route; include both wwwroot/web delivery variants in Infrastructure Design."
|
||||
|
||||
**AI Response**: "Recorded as unverified input in inception/requirements/pi-inventory-notes.md. No action taken on the Pi; requirements still await Bryan approval; hostname decision needs his confirmation."
|
||||
|
||||
**Context**: Requirements Analysis; input for U2 Infrastructure Design.
|
||||
|
||||
---
|
||||
|
||||
## Peer input - database naming
|
||||
|
||||
**Timestamp**: 2026-11-06T08:11:38Z
|
||||
|
||||
**User Input**: "(Relayed by CMS & API, not typed here) Naming decision from Bryan: MariaDB database AndreaSlopFotografieTest and user AndreaSlopFotografie@localhost; use in infrastructure design, connection string template (no password in repo) and manual-steps list. When the manual-steps list is complete, message CMS & API so Pi-Main can draft exact commands."
|
||||
|
||||
**AI Response**: "Recorded in pi-inventory-notes.md as relayed, pending Bryan confirmation. Will message CMS & API when the manual-steps list is final (Infrastructure Design, U2)."
|
||||
|
||||
**Context**: Input for U2 Infrastructure Design.
|
||||
|
||||
---
|
||||
|
||||
## Requirements Analysis - Approval
|
||||
|
||||
**Timestamp**: 2026-11-06T09:18:46Z
|
||||
|
||||
**AI Prompt**: "Review requirements.md; confirm relayed answers (Q3, hostname, DB names)."
|
||||
|
||||
**User Response**: "goedgekeurd, ga verder"
|
||||
|
||||
**Status**: Approved (interpreted as covering the relayed items too, since they were named in the prompt)
|
||||
|
||||
**Context**: Requirements approved by Bryan. Workflow Planning started; execution-plan.md written.
|
||||
|
||||
---
|
||||
|
||||
## Workflow Planning - Approval
|
||||
|
||||
**Timestamp**: 2026-11-06T09:23:50Z
|
||||
|
||||
**User Response**: "goedgekeurd, ga verder"
|
||||
|
||||
**Status**: Approved
|
||||
|
||||
**Context**: Execution plan approved by Bryan; Application Design started, design plan with 3 questions issued.
|
||||
|
||||
---
|
||||
|
||||
## Application Design - answers relayed
|
||||
|
||||
**Timestamp**: 2026-11-06T09:38:02Z
|
||||
|
||||
**User Input**: "(Relayed by CMS & API) Q1 A separate StrictSite origin lists AllowedSiteScriptOrigins/AllowedSiteConnectOrigins; Q2 A per-request file-exists check on lowercased name, resolver takes predicate; Q3 A setup page shows token field only when GET /Setup/status returns tokenRequired, token in request header. Origins confirmed by website side: script https://analytics.slpsoftware.nl; connect https://analytics.slpsoftware.nl and https://o4511795618185216.ingest.de.sentry.io"
|
||||
|
||||
**AI Response**: "Recorded in design plan; generating design artifacts; Bryan confirms at the design approval gate."
|
||||
|
||||
**Context**: Application Design.
|
||||
|
||||
---
|
||||
|
||||
## Application Design - artifacts generated
|
||||
|
||||
**Timestamp**: 2026-11-06T09:39:17Z
|
||||
|
||||
**AI Response**: "Generated components, component-methods, services, component-dependency and consolidated application-design. Awaiting Bryan approval (also confirms relayed Q1-Q3)."
|
||||
|
||||
**Context**: Application Design Step 10-12.
|
||||
|
||||
---
|
||||
|
||||
## Application Design - Approval
|
||||
|
||||
**Timestamp**: 2026-11-06T09:52:23Z
|
||||
|
||||
**User Response**: "goedgekeurd, ga verder"
|
||||
|
||||
**Status**: Approved (covers relayed Q1-Q3)
|
||||
|
||||
**Context**: Design approved by Bryan; Units Generation started (minimal, units fixed by the brief).
|
||||
|
||||
---
|
||||
|
||||
## Units Generation - Approval
|
||||
|
||||
**Timestamp**: 2026-11-06T10:10:52Z
|
||||
|
||||
**User Response**: "Het serveren van de pre-rendered site wordt nu telkens heel specifiek aangegeven, maar is dat niet gewoon hetzelfde als we nu de front-end van SlpSoftware serveren? ... Verder akkoord op de units definities" then "Ik vind het goed om het nu zo op te pakken, maar steeds meer in de website wordt dynamisch dus we moeten dan rekening houden dat dat minder wordt, maar dat is denk ik meer voor CMS & API om bij te houden."
|
||||
|
||||
**Status**: Approved; full plan kept (canonical 301s included). Future shift to dynamic site content is for CMS & API to track.
|
||||
|
||||
**Context**: Units Generation complete; proceeding to Construction, U1 Functional Design.
|
||||
|
||||
---
|
||||
|
||||
## Functional Design U1 - questions issued
|
||||
|
||||
**Timestamp**: 2026-11-06T10:11:13Z
|
||||
|
||||
**AI Response**: "Created core-site-hosting-functional-design-plan.md and core-site-hosting-fd-questions.md (2 questions). Waiting for Bryan."
|
||||
|
||||
**Context**: Construction, U1 Functional Design.
|
||||
|
||||
---
|
||||
|
||||
## Functional Design U1 - answers received (relayed)
|
||||
|
||||
**Timestamp**: 2026-11-06T10:20:00Z
|
||||
|
||||
**User Response**: Relayed by CMS & API: Q1 = A ("Volledige set overal"), Q2 = A ("Weigeren, behalve .well-known").
|
||||
|
||||
**Status**: Answers recorded; generating functional design artifacts. Approval of the design confirms the answers.
|
||||
|
||||
**Context**: Construction, U1 Functional Design.
|
||||
|
||||
---
|
||||
|
||||
## Functional Design U1 - artifacts generated
|
||||
|
||||
**Timestamp**: 2026-11-06T10:30:00Z
|
||||
|
||||
**AI Response**: "Generated business-logic-model.md, business-rules.md (R1-R26, PBT properties), domain-entities.md under construction/core-site-hosting/functional-design/. Awaiting approval."
|
||||
|
||||
**Context**: Construction, U1 Functional Design.
|
||||
|
||||
---
|
||||
|
||||
## Functional Design U1 - R11 adjusted after web-side review
|
||||
|
||||
**Timestamp**: 2026-11-06T10:40:00Z
|
||||
|
||||
**AI Response**: "CMS & API review: R11 changed to nginx parity (strip trailing slashes from every path >1 char, 301 regardless of existence; idempotent targets). business-logic-model.md updated. Still awaiting Bryan's approval."
|
||||
|
||||
**Context**: Construction, U1 Functional Design.
|
||||
|
||||
---
|
||||
|
||||
## Functional Design U1 - approved
|
||||
|
||||
**Timestamp**: 2026-11-06T10:45:00Z
|
||||
|
||||
**User Response**: "goedgekeurd, ga verder"
|
||||
|
||||
**Status**: Approved (incl. Q1=A, Q2=A, R11 nginx parity). Proceeding to NFR Requirements.
|
||||
|
||||
**Context**: Construction, U1.
|
||||
|
||||
---
|
||||
|
||||
## NFR Requirements U1 - questions issued
|
||||
|
||||
**Timestamp**: 2026-11-06T10:50:00Z
|
||||
|
||||
**AI Response**: "Created core-site-hosting-nfr-requirements-plan.md (3 questions: compression algorithms, observability, performance verification). Waiting for Bryan."
|
||||
|
||||
**Context**: Construction, U1 NFR Requirements.
|
||||
|
||||
---
|
||||
|
||||
## NFR Requirements U1 - answers received and artifacts generated
|
||||
|
||||
**Timestamp**: 2026-11-06T11:05:00Z
|
||||
|
||||
**User Response**: Relayed by CMS & API: Q1 = A (gzip only), Q2 = Bryan: "Alleen waarschuwingen en meer op de pi, op productie later bepalen" (interpreted as dedicated logger category, Information on test, Warning default/production), Q3 = A (call-count test + local timing check).
|
||||
|
||||
**AI Response**: "Generated nfr-requirements.md and tech-stack-decisions.md (flags T4: FsCheck.Xunit test-only dependency). Awaiting approval."
|
||||
|
||||
**Context**: Construction, U1 NFR Requirements.
|
||||
|
||||
---
|
||||
|
||||
## NFR Requirements U1 - approved
|
||||
|
||||
**Timestamp**: 2026-11-06T11:15:00Z
|
||||
|
||||
**User Response**: "ga verder"
|
||||
|
||||
**Status**: Approved (incl. logging interpretation and FsCheck.Xunit as test-only dependency). Proceeding to NFR Design.
|
||||
|
||||
**Context**: Construction, U1.
|
||||
|
||||
---
|
||||
|
||||
## NFR Design U1 - artifacts generated (no questions)
|
||||
|
||||
**Timestamp**: 2026-11-06T11:30:00Z
|
||||
|
||||
**AI Response**: "Created core-site-hosting-nfr-design-plan.md (category evaluation, no open questions), nfr-design-patterns.md (P1-P9) and logical-components.md. Awaiting approval."
|
||||
|
||||
**Context**: Construction, U1 NFR Design.
|
||||
|
||||
---
|
||||
|
||||
## NFR Design U1 - approved
|
||||
|
||||
**Timestamp**: 2026-11-06T11:40:00Z
|
||||
|
||||
**User Response**: "goedgekeurd, ga verder"
|
||||
|
||||
**Status**: Approved. Proceeding to next stage per execution plan.
|
||||
|
||||
**Context**: Construction, U1.
|
||||
|
||||
---
|
||||
|
||||
## Code Generation U1 - plan ready
|
||||
|
||||
**Timestamp**: 2026-11-06T12:00:00Z
|
||||
|
||||
**AI Response**: "Created core-site-hosting-code-generation-plan.md (13 steps). U1 Infrastructure Design skipped (execution plan, confirmed by CMS & API). Awaiting plan approval."
|
||||
|
||||
**Context**: Construction, U1 Code Generation Part 1.
|
||||
|
||||
---
|
||||
|
||||
## Code Generation U1 - plan approved
|
||||
|
||||
**Timestamp**: 2026-11-06T12:10:00Z
|
||||
|
||||
**User Response**: "approve plan"
|
||||
|
||||
**Status**: Approved. Starting Part 2 (generation).
|
||||
|
||||
**Context**: Construction, U1 Code Generation.
|
||||
|
||||
---
|
||||
|
||||
## Code Generation U1 - generated, built and tested
|
||||
|
||||
**Timestamp**: 2026-11-06T13:30:00Z
|
||||
|
||||
**AI Response**: "Plan steps 1-13 done. Build succeeded. Core.Tests 330 passed; Identity 37, Master 57, Offerings 57, Availability 82 passed; Api.Tests could not run (no MariaDB reachable: socket errors, same precondition as before). Committed locally on feature/andreaslop-site-hosting (2 commits), not pushed. Awaiting approval."
|
||||
|
||||
**Context**: Construction, U1 Code Generation Part 2.
|
||||
|
||||
---
|
||||
|
||||
## Code Generation U1 - approved; hand-back written
|
||||
|
||||
**Timestamp**: 2026-11-06T14:00:00Z
|
||||
|
||||
**User Response**: "Ga verder"
|
||||
|
||||
**Status**: Approved. Hand-back note written at `handback-u1.md`; sent to CMS & API. Waiting for their "go" before U2.
|
||||
|
||||
**Context**: Construction, U1 complete.
|
||||
|
||||
---
|
||||
|
||||
## U2 go received
|
||||
|
||||
**Timestamp**: 2026-11-06T14:20:00Z
|
||||
|
||||
**Input (CMS & API)**: "U1 hand-back accepted. Go for U2." Notes: run Api.Tests where MariaDB exists and report in handback-u2; observe forwarded headers/HTTP 1.0 on the first test deploy; measure file lookup on the Pi if cheap; U2 Infrastructure Design must end with the complete manual-steps list (both web-delivery variants) and I must tell them when complete. Boundaries unchanged: test only, no production, no push until Bryan asks.
|
||||
|
||||
**Context**: Construction, starting U2 andreaslop-client.
|
||||
|
||||
---
|
||||
|
||||
## U2 NFR Requirements - questions issued
|
||||
|
||||
**Timestamp**: 2026-11-06T14:50:00Z
|
||||
|
||||
**AI Response**: "U2 Functional Design skipped per execution plan. Created andreaslop-client-nfr-requirements-plan.md (5 questions: deploy trigger, pipeline structure, setup rate limiting, setup token on test, theme contrast). Waiting for Bryan."
|
||||
|
||||
**Context**: Construction, U2 NFR Requirements.
|
||||
|
||||
---
|
||||
|
||||
## U2 NFR Requirements - answers received and artifacts generated
|
||||
|
||||
**Timestamp**: 2026-11-06T15:10:00Z
|
||||
|
||||
**User Response**: Relayed by CMS and API: Q1 Zelfde als nu (auto test deploy on push to master plus manual box; must skip cleanly while Andrea is not set up), Q2 = A, Q3 = A, Q4 = A, Q5 = B (brand colours exactly, no contrast check; Bryan explicit choice, overrides brief hint).
|
||||
|
||||
**AI Response**: Generated nfr-requirements.md (skip-clean via variable ANDREA_TEST_DEPLOY_ENABLED, trade-off recorded) and tech-stack-decisions.md. Awaiting approval.
|
||||
|
||||
**Context**: Construction, U2 NFR Requirements.
|
||||
|
||||
---
|
||||
|
||||
## U2 NFR Requirements - approved
|
||||
|
||||
**Timestamp**: 2026-11-06T15:30:00Z
|
||||
|
||||
**User Response**: "ga verder"
|
||||
|
||||
**Status**: Approved. NFR Design artifacts generated without questions (category evaluation in the plan); awaiting approval.
|
||||
|
||||
**Context**: Construction, U2.
|
||||
|
||||
---
|
||||
|
||||
## U2 decision: proxy-aware rate limiting (option B)
|
||||
|
||||
**Timestamp**: 2026-11-06T16:00:00Z
|
||||
|
||||
**User Response**: "Ik wil het meteen goed opzetten. Als dat betekent dat de bestaande pipelines of omgevingen ook moeten worden aangepast is dat goed. Dus dan optie B, want dat is de meest volledige toch?"
|
||||
|
||||
**AI Response**: Added NFR-SEC-09..13, P11, P12, T10 to the U2 NFR documents. Shared Core change (touches Api, Api.SlpSoftware, Api.Slave) is opt-in via ForwardedHeaders:KnownProxies; limiters become per-client. Existing environments need the env var and proxy-Pi headers as manual steps. Awaiting approval of the updated NFR design.
|
||||
|
||||
**Context**: Construction, U2 NFR Design.
|
||||
|
||||
---
|
||||
|
||||
## U2 NFR Design - approved; Infrastructure Design questions issued
|
||||
|
||||
**Timestamp**: 2026-11-06T16:30:00Z
|
||||
|
||||
**User Response**: "Akkoord, ga verder"
|
||||
|
||||
**AI Response**: Created andreaslop-client-infrastructure-design-plan.md (3 questions: web delivery variant, first-deploy/health check sequence, Sentry). Waiting for Bryan.
|
||||
|
||||
**Context**: Construction, U2 Infrastructure Design.
|
||||
|
||||
---
|
||||
|
||||
## U2 Infrastructure Design - answers received (relayed)
|
||||
|
||||
**Timestamp**: 2026-11-06T17:00:00Z
|
||||
|
||||
**User Response**: Relayed by CMS and API: Q1 = A (symlink to /mnt/storage1/www/html/andreaslop-test), Q2 = A (switch proxy-Pi route first, then first deploy; downtime accepted; explicit order incl. nginx fallback revert), Q3 = B (reuse the website Sentry project/DSN).
|
||||
|
||||
**AI Response**: Checked Sentry: admin reports through the same-origin /sentry-tunnel (connect-src self suffices); tunnel target derives from the backend DSN. Generating infrastructure artifacts and the ordered manual-steps list.
|
||||
|
||||
---
|
||||
|
||||
## U2 Infrastructure Design - artifacts generated
|
||||
|
||||
**Timestamp**: 2026-11-06T17:20:00Z
|
||||
|
||||
**AI Response**: Generated infrastructure-design.md, deployment-architecture.md and manual-steps-for-bryan.md (18 ordered steps in phases A prepare, B cut over, C verify, plus rollback and optional existing-host steps). Awaiting approval; then CMS and API is told the list is final.
|
||||
|
||||
**Context**: Construction, U2 Infrastructure Design.
|
||||
|
||||
---
|
||||
|
||||
## U2 Infrastructure Design - naming convention applied
|
||||
**Timestamp**: 2026-11-07
|
||||
**User Input (relayed by "CMS & API")**: Company is "Andrea Slop Fotografie"; new names use AndreaSlopFotografie/ASF/Asf, never "Andrea"/"AndreaSlop" alone. Clarified: Sentry Q3=B is the ASF website's own Sentry project; Umami only in the website CSP.
|
||||
**AI Response**: Renamed in all U2/inception docs: ANDREA_TEST_* -> ASF_TEST_*, VITE_SENTRY_DSN_ANDREA -> VITE_SENTRY_DSN_ASF, jobs publish/deploy-asf-test, theme folder themes/asf (VITE_THEME=asf). Convention and Sentry/Umami clarification recorded in infrastructure-design.md. Earlier audit entries keep their historical wording (append-only). Awaiting approval.
|
||||
|
||||
## U2 Infrastructure Design - approval
|
||||
**Timestamp**: 2026-11-07
|
||||
**User Input**: "Akkoord, ga verder"
|
||||
**AI Response**: Infrastructure Design approved; manual-steps list FINAL. Peer notified. Code Generation plan written (`andreaslop-client-code-generation-plan.md`), awaiting approval.
|
||||
|
||||
## U2 Infrastructure Design - correction (proxy block)
|
||||
**Timestamp**: 2026-11-07
|
||||
**Input (peer "CMS & API")**: The live proxy-Pi block for test.andreaslop.nl already sets Host, X-Forwarded-For, X-Forwarded-Proto, X-Real-IP; only proxy_pass changes (http://192.168.1.103 -> :5200). Generator in website repo updated in U3.
|
||||
**AI Response**: manual-steps step 11 reworded (verify headers, change target only); earlier statement was wrong.
|
||||
|
||||
## U2 Code Generation - plan approval
|
||||
**Timestamp**: 2026-11-07
|
||||
**User Input**: "Approve plan"
|
||||
**AI Response**: Plan approved; starting Part A (Core forwarded headers + per-client limiters).
|
||||
|
||||
## U2 Code Generation - complete
|
||||
**Timestamp**: 2026-11-07
|
||||
**AI Response**: Parts A-F implemented (see construction/andreaslop-client/code/code-summary.md). Core 351, Identity 57, Availability 82, Master 57, Offerings 57, ASF host config 5, frontend 293 tests green; ESLint/tsc clean; Api.Tests and ASF host pipeline tests need MariaDB (not available locally, run in CI). U1 defect found by the property test (unencoded 301 Location) fixed with regression tests. No push, no deploy. Awaiting approval.
|
||||
|
||||
## U2 Code approval, hand-back and Build and Test
|
||||
**Timestamp**: 2026-11-07
|
||||
**User Input**: "Ga verder" (approved U2 code)
|
||||
**AI Response**: handback-u2.md written (incl. U1 Location-encoding correction, below-AA pairs as information, dependency advisory finding). Build and Test documents generated under construction/build-and-test/. Finding: pre-existing vulnerable packages will fail the CI vulnerability-scan gate; decision requested. Awaiting approval.
|
||||
|
||||
## Build and Test approval + dependency bump
|
||||
**Timestamp**: 2026-11-07
|
||||
**User Input**: "Goedkeuren en doe maar optie A"
|
||||
**AI Response**: Build and Test approved. Option A done: Cryptography.Xml 10.0.14 (Core + 3 test projects), zod ^4.6.6, @tanstack/react-router 1.170.46; vulnerability scans clean, all suites green. Proceeding to Operations.
|
||||
|
||||
## Operations - Deployment Setup plan
|
||||
**Timestamp**: 2026-11-07
|
||||
**AI Response**: Build and Test complete. Deployment Setup question file created (operations/plans/deployment-setup-plan.md) with recommended answers that confirm the U2 infrastructure decisions. Awaiting answers.
|
||||
|
||||
## Operations - Deployment Setup artifacts
|
||||
**Timestamp**: 2026-11-07
|
||||
**User Input**: "alles A"
|
||||
**AI Response**: Answers recorded (all A). Generated operations/deployment/{deployment-plan,deployment-instructions,rollback-plan}.md. Awaiting approval.
|
||||
|
||||
## Operations - Deployment Setup approval
|
||||
**Timestamp**: 2026-11-08
|
||||
**User Input**: "ga verder"
|
||||
**AI Response**: Deployment Setup approved and complete. Starting Monitoring Setup.
|
||||
|
||||
## Operations - Monitoring Setup plan
|
||||
**Timestamp**: 2026-11-08
|
||||
**AI Response**: Monitoring question file created (operations/plans/monitoring-setup-plan.md), awaiting answers.
|
||||
|
||||
## Operations - Monitoring Setup artifacts
|
||||
**Timestamp**: 2026-11-08
|
||||
**User Input (via CMS & API)**: Q1 A, Q2 D, Q3 A, Q4 A, Q5 A. Also: CI proof via workflow_dispatch started by Bryan (option B), no PR, no merge; branch feature/andreaslop-site-hosting pushed (explicit go relayed 2026-11-08).
|
||||
**AI Response**: Generated operations/monitoring/{monitoring-plan,monitoring-setup}.md. No Sentry alert rules were created (shared project; documented for Bryan/website session). Awaiting approval.
|
||||
|
||||
## Operations - Monitoring approval and Production Readiness Validation
|
||||
**Timestamp**: 2026-11-08
|
||||
**User Input (via CMS & API)**: Monitoring Setup approved; go to Production Readiness (test only; list production items); do not push doc commits now; Sentry alert rules after the first successful deploy; Bryan starts the CI workflow_dispatch himself.
|
||||
**AI Response**: No gaps requiring questions. Checklist generated; appsettings compliance passed. Overall Readiness (test): Yes with caveats; 8 open follow-ups. Feature remains open until CI proof and the first test deploy are reported.
|
||||
|
||||
## CI proof on the pushed branch
|
||||
**Timestamp**: 2026-11-08
|
||||
**Source**: Gitea API (runs 606, 607; dispatched by the CMS & API session on Bryan's behalf, deploy inputs false)
|
||||
**AI Response**: Run 606 red on one SetupPage test (cold-start timing), run 607 on the same commit green: backend-test with MariaDB incl. Api.Tests and ASF HostPipelineTests, vulnerability-scan, frontend. No deploy job ran. `vars` in job-level `if:` confirmed working. Docs updated (handback-u2, deployment-instructions, production-readiness-checklist). Nothing pushed besides the branch earlier.
|
||||
|
||||
## First ASF test deploy (permission relayed from Bryan via CMS & API)
|
||||
**Timestamp**: 2026-11-08
|
||||
**Run**: 608, workflow_dispatch on feature/andreaslop-site-hosting (deploy_asf_test=true only; test/production false). All gates green, publish-asf-test and deploy-asf-test succeeded (health check through https://test.andreaslop.nl/health passed), SlpSoftware jobs skipped.
|
||||
**Verification by curl (https://test.andreaslop.nl)**: / 200 with full header set (CSP byte-exact, HSTS, nosniff, DENY, Referrer-Policy, X-Robots-Tag noindex), Cache-Control no-cache; /assets immutable; gzip on GET, no br; /Over-Mij -> 301 /over-mij; /a%3Fb/ -> 301 /a%3Fb; /doesnotexist and /404.html -> 404 with the 404 page and headers; /api/v1/onbekend-pad -> 404 empty; /robots.txt Disallow: /; POST on a page -> 405 Allow: GET, HEAD; /health 200 (version 1.0.0+91f14d5); /admin/ 200 with theme favicon; capabilities = Identity, Availability; Setup status = initialized false, tokenRequired true.
|
||||
**Observations**: bare `curl -X POST /` (no body/Content-Length) answers 400 via the HTTP/1.0 proxy hop, `-d ''` gives 405; forwarded-header effect not yet observed; Sentry rules and first administrator still open.
|
||||
|
||||
## Defect on the first ASF test deploy: admin files 404 (U1 code)
|
||||
**Timestamp**: 2026-11-08
|
||||
**Found by**: Bryan (blank /admin), analysed with CMS & API.
|
||||
**Root cause**: `MapCmsWebsiteNotFound` maps the catch-all `{*path}` without `nonfile`; routing selects it as endpoint for /admin/assets/x.css and the static-file middleware skips requests that already have an endpoint, so only the admin index (SPA fallback) worked. Existing tests only fetched /admin/. Reproduced locally by 4 failing tests first.
|
||||
**Fix**: route constraint `notreserved` (`NotReservedPathConstraint`) on the catch-all so the reserved prefixes (/admin, /api/v1, /health) behave exactly as in SpaFallback mode (chosen over clearing/restoring the endpoint: simpler, covers future prefixes). Tests: admin index/css/js/favicon 200 with content types, /admin/dashboard SPA index, unknown admin asset 404 non-HTML, unknown /api/v1 empty 404, website /assets/missing.js still the 404 page. Open (pre-existing, not changed): admin inline theme-init script is blocked by CSP script-src 'self' (same on SlpSoftware); candidates: externalise the script or hash it in the admin policy.
|
||||
|
||||
## Redeploy after the admin-files fix
|
||||
**Timestamp**: 2026-11-08
|
||||
**Run**: 610 (dispatch, deploy_asf_test only), head d0c1d26, all gates and deploy-asf-test green. Live checks: /admin/ , /admin/index.html, /admin/favicon-theme.png (image/png), hashed css (text/css, contains the ASF palette) and js (text/javascript) all 200; /admin/dashboard 200 SPA; /admin/assets/missing.js and /api/v1/unknown 404 with empty body; /assets/missing.js 404 with the website 404 page; /health version 1.0.0+d0c1d26.
|
||||
|
||||
## Defect on the live ASF test host: invitation link pointed at the website root
|
||||
**Timestamp**: 2026-11-08
|
||||
**Found by**: Bryan; analysed with CMS & API.
|
||||
**Root cause**: the API returns an app-relative path (`/invite/complete?token=...`); the frontend built the shown/copied URL as `origin + inviteLink` in InviteUserDialog (2x) and UsersPage, ignoring the router basepath (`/admin/` in builds). On ASF the root is the prerendered website, so the link hit its 404 page; SlpSoftware only worked through its root SPA fallback.
|
||||
**Fix** (frontend only; API contract and shared Identity unchanged, SlpSoftware unaffected, already-issued links keep working there): `lib/links.ts buildAppUrl = origin + BASE_URL (no trailing slash) + path`, used in the 3 places. Tests: helper (prod/dev base, trailing slashes, missing leading slash, no double slash, encoded token), dialog link value. Frontend 304 tests green.
|
||||
|
||||
## Redeploy after the invitation-link fix
|
||||
**Timestamp**: 2026-11-08
|
||||
**Run**: 612 (dispatch, deploy_asf_test only), head 0908f42, all gates and deploy-asf-test green. Live: /health version 1.0.0+0908f42; /admin/invite/complete?token=x 200 text/html (SPA); old /invite/complete?token=x on ASF 404 website page (acceptable); /admin/ and favicon unchanged.
|
||||
+37
@@ -0,0 +1,37 @@
|
||||
# Code Summary - andreaslop-client (U2)
|
||||
|
||||
Names follow the ASF convention (see `infrastructure-design.md`). Test environment only; nothing was pushed or deployed.
|
||||
|
||||
## Part A - Core: forwarded headers and per-client limiters (option B)
|
||||
- `Core/Hosting/Proxy/ForwardedHeadersSettings.cs`: `ForwardedHeaders:KnownProxies`, `ParseKnownProxies` (unparsable entry and any-address `0.0.0.0`/`::` fail at startup).
|
||||
- `ForwardedHeadersExtensions.cs`: `AddCmsForwardedHeaders` (XForwardedFor|XForwardedProto, ForwardLimit 1, default known proxies/networks cleared) and `UseCmsForwardedHeaders` (adds the middleware only when a proxy is configured). `CmsHost.ConfigurePipeline` calls it first after the database migration.
|
||||
- `ClientPartitionKey.cs` + `AddCmsRateLimiting`: `login`, `refresh`, sentry-tunnel and `offerings-public` are now partitioned per client address (IPv4-mapped IPv6 normalised, fallback key `(unknown)`).
|
||||
- Safe degradation: without `KnownProxies` the headers are ignored and every caller shares the proxy address, i.e. the old single bucket.
|
||||
- Tests (`Core.Tests/Hosting/Proxy`): parsing, partition key (PBT: injective over addresses), TestServer pipeline (no proxy = headers ignored and shared bucket; trusted proxy = real address, scheme and separate buckets; untrusted peer cannot spoof; wildcard fails at startup).
|
||||
|
||||
## Part B - Identity: setup token
|
||||
- `Modules.Identity/Setup`: `SetupOptions` (`Identity:Setup:Token`, whitespace-only = startup error via `ValidateOnStart`), `ISetupTokenValidator`/`SetupTokenValidator` (SHA-256 + `CryptographicOperations.FixedTimeEquals`).
|
||||
- `SetupController`: `[EnableRateLimiting("login")]` on both endpoints; `POST owner` requires header `X-Setup-Token` when configured and answers an identical 401 for missing and wrong tokens; `GET status` returns `initialized` + `tokenRequired`.
|
||||
- `SecurityEvents.SetupTokenRejected` (event id 5007, tag `setup_token_rejected`, added to `SecurityEventProcessor`); the presented token is never logged.
|
||||
- Tests: validator (examples, PBT: only the exact token passes, never throws), controller (401 uniformity, no owner created, event logged without the token, header passed on), options validation, security-event tests extended to seven events.
|
||||
|
||||
## Part C - Client `SlpModularCms.Api.AndreaSlopFotografie`
|
||||
- New project under Clients: Identity + Availability only (no Master, no Offerings; Availability kept because the admin reads its status). `CmsHostOptions { WebsiteMode = PrerenderedPages }`, `public partial class Program` for host tests.
|
||||
- appsettings.json (no secrets; `SecurityHeaders:DefaultPolicy=StrictSite` + website Umami/Sentry origins for the site lists only, `Website:NoIndex=true`, empty `Identity:Setup:Token` and `ForwardedHeaders:KnownProxies`), appsettings.Development.json (own dev DB, CORS for `pnpm dev:asf`), launchSettings port 5200/7200. `appsettings.local.json` is optional and git-ignored like in the other clients.
|
||||
- Tests project `Api.AndreaSlopFotografie.Tests` (solution folder Tests): `HostConfigurationTests` (5, no database) and `HostPipelineTests` (5, need MariaDB like `Api.Tests`; they run in CI `backend-test`, which starts MariaDB).
|
||||
|
||||
## Part D - Frontend
|
||||
- `frontend/themes/asf/theme.css` (website palette exactly, Q5 = B; light and a derived dark variant; Marcellus/Jost self-hosted via `@fontsource/*@5.3.0`), `favicon.svg` (placeholder monogram, see hand-back), `none.css`, `resolveTheme.ts` (unknown theme = build error). `vite.config.ts`: alias `@theme`, favicon plugin. `main.tsx` imports `@theme`.
|
||||
- `VITE_DEFAULT_LANGUAGE`: `parseDefaultLanguage`, `languageDetection` (stored choice > default > browser).
|
||||
- Setup page: token field only when `tokenRequired`, header `X-Setup-Token`, `skipAuthRefresh` so a 401 does not trigger a session refresh; nl/en texts.
|
||||
- Verified: default build unchanged (no theme CSS, no fonts), `VITE_THEME=asf` build contains the palette, 4 woff2 files, no `data:` fonts (admin CSP `font-src 'self'`), favicon link swapped; `VITE_THEME=nope` fails the build.
|
||||
- Vitest 293 passed, ESLint and `tsc -b` clean.
|
||||
|
||||
## Part E - CI
|
||||
- `continuous_integration.yaml` only gained the `deploy_asf_test` dispatch input and three jobs at the end (`config-asf`, `publish-asf-test`, `deploy-asf-test`), all gated by `vars.ASF_TEST_DEPLOY_ENABLED == 'true'`. Diff = additions only; `deploy-scp.yaml` unchanged.
|
||||
|
||||
## Defect found and fixed in U1 along the way
|
||||
- `WebsitePathResolver` built the 301 `Location` from the decoded path without re-encoding (`/a%3Fb/` redirected to `/a?b`, `#` started a fragment, non-ASCII ended up raw in a header). Found by the existing property test (flaky 1 in ~15 runs); fixed with `PathString.ToUriComponent`, regression tests added, property test now models the browser (splits the Location, decodes the path).
|
||||
|
||||
## Not verified here
|
||||
- `Api.Tests` and `Api.AndreaSlopFotografie.Tests/HostPipelineTests` need MariaDB (none on this machine); they run in CI. Behaviour behind the real proxy (forwarded headers, HTTP/1.0), `vars` in job-level `if:` on this Gitea, and the Pi timing are only observable on the first test deploy.
|
||||
+50
@@ -0,0 +1,50 @@
|
||||
# Deployment Architecture - andreaslop-client (U2, test)
|
||||
|
||||
## Runtime topology
|
||||
```mermaid
|
||||
flowchart LR
|
||||
V["Visitor / Andrea"] --> P["Proxy Pi 192.168.1.102 (TLS, certbot)"]
|
||||
P -- "HTTP/1.0 + X-Forwarded-For/-Proto :5200" --> A["App Pi: ufw 5200 only from proxy"]
|
||||
A --> H["andreaslopfotografie-test.service (.NET host)"]
|
||||
H --> D[("MariaDB AndreaSlopFotografieTest")]
|
||||
H --> W["shared/wwwroot-web -> /mnt/storage1/www/html/andreaslop-test"]
|
||||
WS["Website repo deploy"] --> W
|
||||
H -. "/sentry-tunnel" .-> S["Sentry (website project)"]
|
||||
N["nginx on app Pi (fallback, old route)"]
|
||||
|
||||
classDef user fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
classDef net fill:#d6bcfa,stroke:#553c9a,stroke-width:1px,color:#000;
|
||||
classDef app fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef data fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
class V user;
|
||||
class P,A,N net;
|
||||
class H app;
|
||||
class D,W,WS,S data;
|
||||
```
|
||||
|
||||
Text alternative: visitors reach the proxy Pi, which forwards to the host on port 5200 with the client address in headers; the host reads the database and the website files (a symlinked folder that the website repo's own deploy writes), and forwards browser error reports to Sentry. The old nginx route remains as a fallback.
|
||||
|
||||
## Deploy sequence (CI, automatic on push to master or via the manual box, only when `ASF_TEST_DEPLOY_ENABLED=true`)
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
box rgba(214,188,250,0.4) CI
|
||||
participant G as Gitea runner
|
||||
end
|
||||
box rgba(99,179,237,0.4) App Pi
|
||||
participant R as releases/ts
|
||||
participant S as shared
|
||||
participant U as systemd user unit
|
||||
end
|
||||
G->>G: build admin (VITE_THEME=asf, nl), publish linux-arm64
|
||||
G->>R: scp release to releases/ts
|
||||
G->>S: mkdir -p shared/wwwroot-web (symlink already exists)
|
||||
G->>R: wwwroot/web -> ../../../shared/wwwroot-web
|
||||
G->>U: ln -sfn current, restart unit
|
||||
G->>G: curl https://test.andreaslop.nl/health (10 tries)
|
||||
G->>R: prune to current + 1 previous
|
||||
```
|
||||
|
||||
Text alternative: build, upload to a timestamped release, link the persistent website folder, switch `current` atomically, restart, check `/health` through the public URL, prune old releases.
|
||||
|
||||
## Rollback
|
||||
`ln -sfn releases/<previous> current && systemctl --user restart andreaslopfotografie-test`; the previous release is always kept. Route rollback: restore the saved nginx block on the proxy Pi (see the manual steps).
|
||||
+68
@@ -0,0 +1,68 @@
|
||||
# Infrastructure Design - andreaslop-client (U2, test environment only)
|
||||
|
||||
Status of the facts: the Pi details come from the Pi-Main inventory (unverified by this session) and are confirmed against `deploy-scp.yaml`. Items marked **(verify)** must be checked on the Pi by Bryan or the Pi-Main session before use. Production is out of scope.
|
||||
|
||||
## Naming convention (project decision, Bryan, relayed by "CMS & API")
|
||||
The website/company is **Andrea Slop Fotografie**. New names in code, config and infrastructure use `AndreaSlopFotografie` / `andreaslopfotografie` / `andrea-slop-fotografie` or the abbreviation `ASF` / `Asf`, whichever fits the local convention (env vars and Gitea variables/secrets `ASF_...`, PascalCase identifiers `Asf...` or the full name). Never "Andrea" or "AndreaSlop" alone for NEW names. Existing names stay (domain `andreaslop.nl`, host `test.andreaslop.nl`, website repo, feature slug `andreaslop-site-hosting`, DB `AndreaSlopFotografieTest`, DB user `AndreaSlopFotografie`).
|
||||
|
||||
Final new names: Gitea variables `ASF_TEST_DEPLOY_ENABLED`, `DEPLOY_PATH_ASF_TEST`, `SERVICE_NAME_ASF_TEST`, `HEALTH_CHECK_URL_ASF_TEST`, `VITE_SENTRY_DSN_ASF`; jobs `publish-asf-test`, `deploy-asf-test`; theme folder `frontend/themes/asf/` with `VITE_THEME=asf`; project `SlpModularCms.Api.AndreaSlopFotografie`; Pi folder `apps/andreaslopfotografie/test`; unit `andreaslopfotografie-test.service`; env file `shared/env`; security-event label `setup_token_rejected` (generic, unchanged).
|
||||
|
||||
## Which Sentry project (Q3 = B)
|
||||
The DSNs (`Observability__SentryDsn` and `VITE_SENTRY_DSN_ASF`) must come from the existing Sentry project of the **Andrea Slop Fotografie website**, NOT from SlpSoftware's admin project. The Umami origin (`analytics.slpsoftware.nl`) appears only in the website CSP (`StrictSite`); the host and admin set up no Umami.
|
||||
|
||||
## Component mapping
|
||||
| Logical component | Infrastructure |
|
||||
|---|---|
|
||||
| `Api.AndreaSlopFotografie` host | One .NET process (linux-arm64, framework-dependent) as systemd **user** unit `andreaslopfotografie-test.service` of user `gitea-workflow`, listening on `http://0.0.0.0:5200` |
|
||||
| Admin SPA (themed) | Built in CI, shipped inside the release (`wwwroot/admin`) |
|
||||
| Website files | `wwwroot/web` -> `shared/wwwroot-web` -> symlink to `/mnt/storage1/www/html/andreaslop-test` (Q1 = A). The website repo's own deploy keeps writing there; no host restart needed. |
|
||||
| Database | MariaDB 10.11 on the same Pi: database `AndreaSlopFotografieTest`, user `AndreaSlopFotografie`@`localhost`, rights on that database only (the host runs its own migrations at start) |
|
||||
| TLS + public hostname | Proxy Pi (192.168.1.102): `test.andreaslop.nl` -> HTTP/1.0 -> app Pi port 5200; certbot stays on the proxy Pi |
|
||||
| Firewall | ufw on the app Pi: port 5200/tcp only from 192.168.1.102 |
|
||||
| Build + deploy | Gitea Actions: new jobs `publish-asf-test` (ubuntu-latest, `-r linux-arm64`) and `deploy-asf-test` (reuses `deploy-scp.yaml`, SSH as `gitea-workflow` with the existing `PI_MAIN_*` secrets) |
|
||||
| Error reporting | Existing website Sentry project (Q3 = B) |
|
||||
| Backups | Pi-Main adds `AndreaSlopFotografieTest` to the DB backup script |
|
||||
|
||||
## Pi layout (under the home of `gitea-workflow`, **(verify)** the absolute path)
|
||||
```
|
||||
apps/andreaslopfotografie/test/
|
||||
releases/<yyyymmddHHMMSS>/ written by the deploy
|
||||
current -> releases/<latest> switched atomically by the deploy
|
||||
shared/
|
||||
env mode 600, secrets, read by the unit
|
||||
wwwroot-web -> /mnt/storage1/www/html/andreaslop-test
|
||||
modules/ created by the deploy (empty)
|
||||
```
|
||||
|
||||
## Environment file `shared/env` (names only; values are created by Bryan, never committed)
|
||||
| Variable | Value / source |
|
||||
|---|---|
|
||||
| `ASPNETCORE_ENVIRONMENT` | `Production` |
|
||||
| `ASPNETCORE_URLS` | `http://0.0.0.0:5200` |
|
||||
| `ConnectionStrings__DefaultConnection` | `Server=localhost;Port=3306;Database=AndreaSlopFotografieTest;Uid=AndreaSlopFotografie;Pwd=<db password>` |
|
||||
| `JwtSettings__Secret` | random, at least 64 characters |
|
||||
| `Identity__Setup__Token` | random, at least 32 characters; remove after the first administrator exists |
|
||||
| `Observability__SentryDsn` | the website's existing Sentry DSN (backend; the admin reports through the same-origin `/sentry-tunnel`) |
|
||||
| `Observability__Environment` | `test` |
|
||||
| `ForwardedHeaders__KnownProxies__0` | `192.168.1.102` |
|
||||
| `Website__LogLevel` | `Information` (test only). Replaces `Logging__LogLevel__SlpModularCms.Website`: a variable name containing a dot is ignored by a systemd `EnvironmentFile`. (The committed default log level is already `Information`, so the website logs 301/404 at that level without it.) |
|
||||
|
||||
Committed defaults (in the client's `appsettings.json`, no secrets): `SecurityHeaders` with `DefaultPolicy=StrictSite`, the site's Umami and Sentry origins, `Website:NoIndex=true` (secure default; a later production setup must set it to `false` explicitly), JWT issuer/audience, rate limiting values.
|
||||
|
||||
## Gitea (repository SlpModularCms) variables and secrets
|
||||
| Name | Kind | Value |
|
||||
|---|---|---|
|
||||
| `DEPLOY_PATH_ASF_TEST` | variable | absolute path of `apps/andreaslopfotografie/test` **(verify)** |
|
||||
| `SERVICE_NAME_ASF_TEST` | variable | `andreaslopfotografie-test` (**check** whether the existing SlpSoftware variable includes `.service`; use the same form) |
|
||||
| `HEALTH_CHECK_URL_ASF_TEST` | variable | `https://test.andreaslop.nl/health` |
|
||||
| `VITE_SENTRY_DSN_ASF` | variable | the website's Sentry DSN (a public DSN, same value as backend) |
|
||||
| `ASF_TEST_DEPLOY_ENABLED` | variable | `true` ONLY when everything else is ready (the on/off switch) |
|
||||
| `PI_MAIN_USERNAME`, `PI_MAIN_PASSWORD`, `PI_MAIN_PORT`, `PI_MAIN_ADDRESS` | secrets | **already exist** and are reused; they must point at the same Pi and user (`gitea-workflow`, SSH port 2224) |
|
||||
|
||||
Fixed in the workflow (not variables): `VITE_THEME=asf`, `VITE_DEFAULT_LANGUAGE=nl`, `VITE_APP_ENV=test`, `VITE_APP_TITLE`. No Umami for the admin.
|
||||
|
||||
## Sentry and CSP check (answer to the question from the website side)
|
||||
The admin sends browser errors to the same-origin path `/sentry-tunnel` (`tunnel` option), and the host forwards them to the destination derived from `Observability__SentryDsn`. The admin policy `Strict` (`connect-src 'self'`) therefore needs **no** Sentry ingest origin; the website's own `StrictSite` list keeps its direct ingest host for the website's browser code. Variable names: backend `Observability__SentryDsn` (in `shared/env`), frontend build `VITE_SENTRY_DSN_ASF` (Gitea variable, passed to the build as `VITE_SENTRY_DSN`). Events from admin, host and website share one project; the environment tag (`test`) and the release/URL tell them apart.
|
||||
|
||||
## Existing hosts touched by the shared change (option B)
|
||||
`Api`, `Api.SlpSoftware`, `Api.Slave` get the new opt-in forwarded-headers code and per-client limiters. Until `ForwardedHeaders__KnownProxies__0` is set in their environment and their proxy block passes `X-Forwarded-For`/`-Proto`, they behave as before (all callers share the proxy's address, same as today's global bucket). Enabling it for SlpSoftware test/production is an optional separate step in the manual list.
|
||||
+39
@@ -0,0 +1,39 @@
|
||||
# Manual steps for Bryan - Andrea Slop Fotografie (ASF) test host (ordered, complete)
|
||||
|
||||
Scope: test environment only. Nothing here touches production. Commands are drafted by the Pi-Main session (via "CMS & API") from this list; this list says WHAT and in WHICH ORDER. Items marked **(verify)** are facts from the inventory that were not verified by the author.
|
||||
|
||||
Legend: **[Pi]** app Pi, **[Proxy]** proxy Pi 192.168.1.102, **[Gitea]** the CMS repository settings, **[Code]** needs the code on Gitea.
|
||||
|
||||
## Phase A - Prepare (nothing is live yet; the old nginx route keeps serving)
|
||||
1. **[Pi] Verify prerequisites**: user `gitea-workflow` exists and has lingering enabled for user units (`loginctl enable-linger gitea-workflow`) (verify); `dotnet` runtime 10 is installed and its path is known (verify); port 5200 is free; the folder `/mnt/storage1/www/html/andreaslop-test` exists and `gitea-workflow` can read it (group/mode; the SlpSoftware setup needed a cross-account permission fix of the same kind) (verify).
|
||||
2. **[Pi] Database** (sudo): create database `AndreaSlopFotografieTest` (utf8mb4) and user `AndreaSlopFotografie`@`localhost` with a strong password; grant all privileges on that database only. Note the password for step 4. Do not confuse with the WordPress database `andreaslop`.
|
||||
3. **[Pi] Directories** as `gitea-workflow`: `apps/andreaslopfotografie/test/{releases,shared}`. Create the symlink `shared/wwwroot-web` -> `/mnt/storage1/www/html/andreaslop-test`. (Variant B, only if you choose it later: skip the symlink; the website pipeline then copies into `shared/wwwroot-web` itself.)
|
||||
4. **[Pi] `shared/env`** (mode 600, owner `gitea-workflow`) with the variables from `infrastructure-design.md`: `ASPNETCORE_ENVIRONMENT`, `ASPNETCORE_URLS`, `ConnectionStrings__DefaultConnection`, `JwtSettings__Secret`, `Identity__Setup__Token`, `Observability__SentryDsn`, `Observability__Environment`, `ForwardedHeaders__KnownProxies__0`, `Logging__LogLevel__SlpModularCms.Website`. Generate the JWT secret (64+ chars) and the setup token (32+ chars) randomly; keep the token for step 17.
|
||||
5. **[Pi] systemd user unit** `~/.config/systemd/user/andreaslopfotografie-test.service`: `WorkingDirectory=<deploy path>/current`, `EnvironmentFile=<deploy path>/shared/env`, `ExecStart=<dotnet path> SlpModularCms.Api.AndreaSlopFotografie.dll`, `Restart=on-failure`, `KillSignal=SIGINT`, `WantedBy=default.target`. Run `systemctl --user daemon-reload` and `systemctl --user enable` (do **not** start yet: `current` does not exist until the first deploy).
|
||||
6. **[Pi] Firewall**: allow 5200/tcp only from 192.168.1.102; verify with `ufw status`.
|
||||
7. **[Pi, Pi-Main] Backup**: add `AndreaSlopFotografieTest` to the DB backup script.
|
||||
8. **[Gitea] Variables** (repository SlpModularCms): `DEPLOY_PATH_ASF_TEST`, `SERVICE_NAME_ASF_TEST` (same form as the SlpSoftware one), `HEALTH_CHECK_URL_ASF_TEST=https://test.andreaslop.nl/health`, `VITE_SENTRY_DSN_ASF` (the website's Sentry DSN). The existing secrets `PI_MAIN_*` are reused: confirm they point at the same Pi and user. **Do NOT set `ASF_TEST_DEPLOY_ENABLED` yet.** Until it is `true` the ASF jobs are skipped and the pipeline stays as it is.
|
||||
9. **[Code] Make the code available to Gitea**: this feature's branch must be pushed (or merged into master) before any deploy can run. I do not push; tell me when you want that. A merge to master with the switch off changes nothing for Andrea.
|
||||
|
||||
## Phase B - Cut over (this causes the short test downtime you accepted)
|
||||
10. **[Proxy] Save the current server block** for `test.andreaslop.nl` (copy the file; this is the revert point).
|
||||
11. **[Proxy] Switch the route**: the block for `test.andreaslop.nl` (website repo copy: `web/deploy/nginx/test.andreaslop.nl.proxy.conf`, generated by `web/config/serverConfig.ts`) already sets `Host`, `X-Forwarded-For` (`$proxy_add_x_forwarded_for`), `X-Forwarded-Proto` (`$scheme`) and `X-Real-IP`. **Verify** these three forwarded headers are present in the live block (grep), then change only the target: `proxy_pass http://192.168.1.103;` (port 80, nginx fallback) -> `proxy_pass http://192.168.1.103:5200;`. Keep the certbot TLS settings. Test the config, reload nginx. Until the first deploy the site answers 502/503 (expected). The generator in the website repo is updated in U3 so the repo copy matches.
|
||||
12. **[Gitea] Set `ASF_TEST_DEPLOY_ENABLED=true`.**
|
||||
13. **[Gitea/Code] Run the first deploy**: push to master, or start "Continuous Integration" manually with the box "Deploy ASF test" ticked. Watch the job: build admin, publish, upload, link, switch, restart, `/health` check on the public URL, prune.
|
||||
|
||||
## Phase C - Verify (can be done together with this session)
|
||||
14. `curl -I https://test.andreaslop.nl/` -> 200 with CSP, HSTS, `X-Robots-Tag: noindex, nofollow`; `/over-mij` (or any page) 200; `/Over-Mij` -> one 301; an unknown path -> 404 with the 404 page; `/robots.txt` -> `Disallow: /`.
|
||||
15. `https://test.andreaslop.nl/health` -> healthy; `/api/v1/System/capabilities` -> no `Offerings`.
|
||||
16. `/admin/`: Andrea's theme, Dutch; the setup page asks for the setup token.
|
||||
17. Create the first administrator with the setup token. Afterwards **remove `Identity__Setup__Token` from `shared/env`** and restart the unit (the setup endpoint is closed once initialised; removing the token is hygiene).
|
||||
18. Report what you see for the forwarded headers (visitor address in the logs/limiter rather than 192.168.1.102) and optionally time a page request on the Pi; both are asked for in the hand-back.
|
||||
|
||||
## Rollback
|
||||
- **Release**: `ln -sfn releases/<previous> current` and `systemctl --user restart andreaslopfotografie-test`.
|
||||
- **Route**: restore the saved nginx block on the proxy Pi (step 10) and reload; the old nginx fallback on the app Pi serves the test site again.
|
||||
- **Switch off CI**: set `ASF_TEST_DEPLOY_ENABLED` to anything but `true`.
|
||||
|
||||
## Optional, separate (existing hosts; only if you want per-visitor rate limits there too)
|
||||
- **SlpSoftware test**: add `ForwardedHeaders__KnownProxies__0=192.168.1.102` to its `shared/env`, make sure its proxy-Pi block sets `X-Forwarded-For`/`-Proto`, restart the unit after the next deploy of the new code.
|
||||
- **SlpSoftware production and other hosts**: the same two things, later, when you decide. Until then they behave exactly as before.
|
||||
- Production Andrea: out of scope for this feature (when it comes: `Website__NoIndex=false`, its own database/port 5201/route).
|
||||
+39
@@ -0,0 +1,39 @@
|
||||
# Logical Components - andreaslop-client (U2)
|
||||
|
||||
No new infrastructure components. All changes are in-process code, CSS and workflow files.
|
||||
|
||||
| Component | Location (planned) | Role |
|
||||
|---|---|---|
|
||||
| `SlpModularCms.Api.AndreaSlopFotografie` | `src/` (solution folder Clients) | Thin host: `CmsHostOptions { WebsiteMode = PrerenderedPages }`, three-file appsettings, own `launchSettings` port |
|
||||
| `SetupOptions`, `ISetupTokenValidator`, `SetupTokenValidator` | `Modules.Identity` | P1-P3 |
|
||||
| `SetupController` (changed) | `Modules.Identity/Controllers` | Limiter, token check, `tokenRequired` in status |
|
||||
| `SecurityEvents.SetupTokenRejected` | `Core/Observability` | P6 |
|
||||
| Setup page change | `frontend/src/features/setup` | Token field only when `tokenRequired`; header `X-Setup-Token` |
|
||||
| Theme | `frontend/themes/asf/` + Vite alias + `VITE_THEME` | P9 |
|
||||
| i18n default language | `frontend/src/i18n/config.ts` | P10 |
|
||||
| `publish-asf-test`, `deploy-asf-test` | `.gitea/workflows/continuous_integration.yaml` | P8 |
|
||||
| `ForwardedHeaders` options + registration (new), `CmsHost` pipeline (changed: first middleware) | `Core/Hosting` | P11; shared by all clients, opt-in |
|
||||
| `AddCmsRateLimiting` (changed) + `ClientPartitionKey` | `Core/Hosting` | P12; shared by all clients |
|
||||
| Test projects | `Modules.Identity.Tests`, `frontend` Vitest | Validator (incl. PBT), controller, setup page, theme/i18n |
|
||||
| `Api.AndreaSlopFotografie` tests | host regression: `capabilities` has no `Offerings` | Needs MariaDB like `Api.Tests` |
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
CI["continuous_integration.yaml"] --> PUB["publish-asf-test"]
|
||||
PUB --> FE["frontend build (VITE_THEME=asf, VITE_DEFAULT_LANGUAGE=nl)"]
|
||||
PUB --> HOST["Api.AndreaSlopFotografie publish (linux-arm64)"]
|
||||
CI --> DEP["deploy-asf-test"]
|
||||
DEP --> SCP["deploy-scp.yaml (unchanged)"]
|
||||
HOST --> CORE["Core: CmsHost, WebsiteMode, StrictSite"]
|
||||
HOST --> IDM["Modules.Identity: setup token"]
|
||||
FE --> TH["themes/asf"]
|
||||
|
||||
classDef ci fill:#d6bcfa,stroke:#553c9a,stroke-width:1px,color:#000;
|
||||
classDef app fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef fe fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
class CI,PUB,DEP,SCP ci;
|
||||
class HOST,CORE,IDM app;
|
||||
class FE,TH fe;
|
||||
```
|
||||
|
||||
Text alternative: the pipeline builds the themed admin and publishes the Andrea host, which uses Core and the Identity module; the deploy job reuses the existing SCP workflow.
|
||||
+43
@@ -0,0 +1,43 @@
|
||||
# NFR Design Patterns - andreaslop-client (U2)
|
||||
|
||||
| # | Pattern | Realises | Design |
|
||||
|---|---|---|---|
|
||||
| P1 | Optional guard with secure default | NFR-SEC-01/02 | `ISetupTokenValidator { IsRequired; IsValid(presented) }`. `IsRequired` is true only when `Identity:Setup:Token` is a non-empty string. With no token configured everything behaves as today (existing hosts unaffected). `CreateOwner` checks the validator **before** calling `ISetupService`, so a wrong token creates nothing. |
|
||||
| P2 | Constant-time comparison | NFR-SEC-01 | Both sides are hashed with SHA-256 to 32 bytes and compared with `CryptographicOperations.FixedTimeEquals`. Equal length by construction, so no length leak; null/empty presented token is simply invalid. The validator never throws. |
|
||||
| P3 | Fail closed on bad configuration | NFR-SEC-02 | A whitespace-only configured token is treated as a configuration error at startup (options validation), not as "no token". |
|
||||
| P4 | No information leak | NFR-SEC-02 | `GET /Setup/status` returns `{ initialized, tokenRequired }` only. A rejected token answers `401` with the same problem-details body whatever the reason (missing or wrong). |
|
||||
| P5 | Reuse the existing limiter | NFR-SEC-03 | `[EnableRateLimiting("login")]` on `GetStatus` and `CreateOwner`. Limits come from the existing `RateLimiting:Login` settings (5 per 60 s). A 429 already produces the `rate_limit_triggered` security event. |
|
||||
| P6 | Alertable security event | NFR-SEC-03 | New constant event name `setup_token_rejected` (event id 5007) in `SecurityEventNames`/`SecurityEvents`, source-generated like the others, constant template, endpoint as the only field; no token, no email. Level Warning so it crosses the Sentry threshold. |
|
||||
| P7 | Secrets only from the environment | NFR-SEC-04/05 | Committed appsettings hold placeholders. Real values come from `shared/env` via the systemd unit: `ConnectionStrings__DefaultConnection`, `JwtSettings__Secret`, `Identity__Setup__Token`, `Observability__SentryDsn`, `SecurityHeaders__...`. The infrastructure design lists them. |
|
||||
| P8 | Explicit skip switch for CI | NFR-DEP-02, DEP-03 | Job-level condition `vars.ASF_TEST_DEPLOY_ENABLED == 'true'` on `publish-asf-test` and `deploy-asf-test`. Failing/skipped ASF jobs are not in any SlpSoftware job's `needs`. The Andrea deploy job reuses `deploy-scp.yaml` with its own path, service and health-check variables. |
|
||||
| P9 | Build-time theme selection | NFR-UX-01/02 | `VITE_THEME` selects `themes/<name>/theme.css` via a Vite alias; unset = empty module (today's admin). The CSS only re-declares existing tokens (`--background`, `--primary`, `--radius`, fonts ...), nothing structural. |
|
||||
| P10 | Language default without overriding the user | NFR-UX-01 | i18n init order: stored choice, then `VITE_DEFAULT_LANGUAGE`, then browser detection. |
|
||||
|
||||
| P11 | Trusted-proxy forwarded headers (opt-in) | NFR-SEC-09/10/12 | `ForwardedHeadersOptions` built from `ForwardedHeaders:KnownProxies`; `KnownProxies`/`KnownNetworks` cleared first (framework default trusts loopback), `ForwardLimit = 1`, `ForwardedHeaders = XForwardedFor \| XForwardedProto`. Added with `UseForwardedHeaders()` as the **first** middleware after the database migration, only when at least one proxy is configured. Options validation (`ValidateOnStart`): every entry parses as an IP address and is not any-address. |
|
||||
| P12 | Per-client limiter partitions | NFR-SEC-11 | A helper `ClientPartitionKey(HttpContext)` returns `RemoteIpAddress` text or a fixed fallback. Each named limiter is registered with `AddPolicy(name, context => RateLimitPartition.GetFixedWindowLimiter(key, _ => options))` (sliding for `refresh`), keeping the same permit/window/queue settings. Rejection callback and `rate_limit_triggered` event unchanged. Idle partitions are reclaimed by the framework. |
|
||||
|
||||
## Where the checks sit
|
||||
```mermaid
|
||||
flowchart LR
|
||||
R["POST /api/v1/Setup/owner"] --> L{"login limiter"}
|
||||
L -- over limit --> T429["429 + rate_limit_triggered"]
|
||||
L -- ok --> V{"token required?"}
|
||||
V -- no --> S["ISetupService.CreateInitialOwnerAsync"]
|
||||
V -- yes --> C{"X-Setup-Token valid? (fixed time)"}
|
||||
C -- yes --> S
|
||||
C -- no --> T401["401 + setup_token_rejected"]
|
||||
|
||||
classDef ok fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef bad fill:#feb2b2,stroke:#c53030,stroke-width:1px,color:#000;
|
||||
classDef step fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
class S ok;
|
||||
class T429,T401 bad;
|
||||
class L,V,C step;
|
||||
```
|
||||
|
||||
Text alternative: the limiter runs first, then the token check when a token is configured; only a valid (or not required) token reaches the setup service.
|
||||
|
||||
## Open verification items (settled in Code Generation or on the first test deploy)
|
||||
1. (Resolved by option B, P11/P12.) Finding: the limiters were global buckets and no host handled forwarded headers. After this change, behind the proxy Pi the limiter only partitions per visitor once `KnownProxies` is set and the proxy-Pi block passes `X-Forwarded-For`/`-Proto`; the proxy must set the header from the real client address (`$remote_addr`), and the host takes the last entry (forward limit 1). Verified by tests with a simulated trusted and an untrusted proxy.
|
||||
2. Gitea `vars` in a job-level `if:` (used already in step `if:` elsewhere): verify the syntax in the workflow file with a dry read; the skip behaviour is observed on the first run.
|
||||
3. Forwarded headers / HTTP/1.0 behind the proxy Pi: observed on the first test deploy (peer request).
|
||||
+58
@@ -0,0 +1,58 @@
|
||||
# NFR Requirements - andreaslop-client (U2)
|
||||
|
||||
Answers: Q1 deploy trigger "Zelfde als nu" (automatic on push to master + manual box, test only, must skip cleanly while Andrea is not set up); Q2 = A separate jobs; Q3 = A setup endpoints under the `login` limiter + security event; Q4 = A token required on test; Q5 = B brand colours exactly, no contrast check.
|
||||
|
||||
## Security (Security Baseline, blocking)
|
||||
| ID | Requirement |
|
||||
|---|---|
|
||||
| NFR-SEC-01 | First-admin setup token: `Identity:Setup:Token` from configuration (env `Identity__Setup__Token`), compared with `CryptographicOperations.FixedTimeEquals` over fixed-length hashes; no short-circuit on length. Header `X-Setup-Token`. |
|
||||
| NFR-SEC-02 | Token configured = `POST /Setup/owner` without or with a wrong token answers 401 problem details and creates nothing; not configured = behaviour exactly as today (existing hosts unaffected). `GET /Setup/status` returns `tokenRequired` only, never the token or its length. |
|
||||
| NFR-SEC-03 | Both setup endpoints get `[EnableRateLimiting("login")]` (5 per 60 s per the existing policy). A rejected token attempt is logged as a security event through the existing `SecurityEvents` mechanism (no token value, no email in the message). |
|
||||
| NFR-SEC-04 | The token is a deploy-time secret: only in `shared/env` (mode 600) on the Pi, never in the repository, workflow logs or appsettings; removable after the first administrator exists (the setup endpoint already refuses once initialised). |
|
||||
| NFR-SEC-05 | Secrets in general (DB password, JWT secret, Sentry DSN, setup token): environment only. Committed appsettings contain placeholders only (like `Api.SlpSoftware`). |
|
||||
| NFR-SEC-06 | The Andrea client starts with `Website:NoIndex=true` and `StrictSite` on test; production values are out of scope. |
|
||||
| NFR-SEC-07 | The pipeline never touches production for Andrea: no production deploy job, no production variables. |
|
||||
| NFR-SEC-08 | No new NuGet or npm dependencies in production code. |
|
||||
|
||||
### Added after the requirements approval: proxy-aware rate limiting (Bryan chose option B)
|
||||
Finding: the named limiters (`login`, `refresh`, `sentry-tunnel`, `offerings-public`) are single global buckets, and no host handles forwarded headers. Decision (Bryan, in chat): "meteen goed opzetten", changing existing hosts and pipelines is acceptable.
|
||||
|
||||
| ID | Requirement |
|
||||
|---|---|
|
||||
| NFR-SEC-09 | Opt-in forwarded-headers support in the shared host: section `ForwardedHeaders` with `KnownProxies` (list of IP addresses). Empty or absent = middleware not added = behaviour of every host without a proxy unchanged. |
|
||||
| NFR-SEC-10 | Only the listed proxies are trusted (`X-Forwarded-For`, `X-Forwarded-Proto`; forward limit 1). Startup validation refuses unparsable addresses and any wildcard/any-address (`0.0.0.0`, `::`), so a client can never spoof its address to dodge a limiter. The middleware runs before everything that uses the client address or scheme (limiter, HTTPS redirection). |
|
||||
| NFR-SEC-11 | The four named limiters are partitioned per client address (resulting `RemoteIpAddress`; fallback key when unknown) instead of one global bucket, with the existing permit/window settings. A missing/unreadable address maps to one shared fallback partition, never to "unlimited". |
|
||||
| NFR-SEC-12 | Safe degradation: if a host has a proxy but `KnownProxies` is not (yet) configured, all callers share the proxy's address, which equals today's global bucket. No new failure mode. |
|
||||
| NFR-SEC-13 | Existing environments (`Api`, `Api.SlpSoftware`, `Api.Slave`) change only by this shared code; their deployment config stays as is until Bryan sets `ForwardedHeaders__KnownProxies__0` in their `shared/env` and the proxy-Pi blocks pass the headers (listed in the manual steps, test and production separately; production is not touched by this feature). |
|
||||
|
||||
## Deployment and availability
|
||||
| ID | Requirement |
|
||||
|---|---|
|
||||
| NFR-DEP-01 | Automatic deploy of the Andrea client to the test host on every push to master, and via the manual box `deploy_andrea_test` (Q1). Test only. |
|
||||
| NFR-DEP-02 | **Skip cleanly while Andrea is not set up**: the Andrea publish/deploy jobs only run when the Gitea variable `ASF_TEST_DEPLOY_ENABLED` equals `true` (Bryan sets it after the Pi and secrets exist). Until then the jobs are skipped, the existing pipeline stays green and unchanged, and nothing about Andrea can fail the run. (Secrets cannot be tested in an `if:`, hence the explicit variable.) |
|
||||
| NFR-DEP-03 | Separate jobs (Q2): `publish-asf-test` and `deploy-asf-test`, reusing `deploy-scp.yaml` unchanged; the `Api.SlpSoftware` jobs, the env block and `deploy-scp.yaml` stay byte-for-byte unchanged. A failure in an Andrea job must not block the SlpSoftware deploy and vice versa. |
|
||||
| NFR-DEP-04 | Deploy keeps the existing guarantees: timestamped release, atomic `current` switch, `/health` check, one previous release kept. Website delivery works in both variants (CI/web job writes into `shared/wwwroot-web`, or `shared/wwwroot-web` is a symlink to `/mnt/storage1/www/html/andreaslop-test`). |
|
||||
| NFR-DEP-05 | Smoke checks after deploy: `/health`, `/api/v1/System/capabilities` (no `Offerings`), one website page, headers (CSP, noindex). Observe forwarded-header / HTTP 1.0 behaviour behind the proxy Pi on the first deploy and report it. |
|
||||
| NFR-DEP-06 | linux-arm64 publish, `--self-contained false`, same as SlpSoftware. |
|
||||
|
||||
## Usability and theme (Q5 = B)
|
||||
| ID | Requirement |
|
||||
|---|---|
|
||||
| NFR-UX-01 | Theme = CSS variables overriding the existing admin design tokens, chosen at build time (`VITE_THEME`); unset reproduces today's admin exactly. Language default `nl` via `VITE_DEFAULT_LANGUAGE`; a user's stored choice still wins. |
|
||||
| NFR-UX-02 | **Brand colours exactly as the website; no contrast check (Bryan's explicit choice).** Trade-off recorded: some token pairs (for example muted text on a light background, or white text on a light brand accent) may fall below WCAG AA (4.5:1 text, 3:1 large text and UI components). This overrides the brief's accessibility hint. The theme does not invent extra colours to compensate; error and destructive states use the exact brand tokens if the website defines them, otherwise the existing admin tokens, so they stay as readable as the brand allows. A short list of pairs that fall below AA goes into the hand-back as information. |
|
||||
| NFR-UX-03 | Fonts (Marcellus, Jost) are self-hosted with the theme (no third-party font request, consistent with `font-src 'self'`). |
|
||||
|
||||
## Reliability and operations
|
||||
| ID | Requirement |
|
||||
|---|---|
|
||||
| NFR-OPS-01 | Own database `AndreaSlopFotografieTest`, user `AndreaSlopFotografie@localhost`; startup migration runs as today. |
|
||||
| NFR-OPS-02 | Systemd user unit with restart on failure; environment from `shared/env`. |
|
||||
| NFR-OPS-03 | Logs: warnings by default, `SlpModularCms.Website` at Information on test (U1). |
|
||||
| NFR-OPS-04 | Tests of the changed parts stay green; `Api.Tests` is run against a real MariaDB (Pi test DB or local) during U2 and reported in handback-u2. |
|
||||
|
||||
## Performance / scalability
|
||||
N/A beyond U1 (one small instance). The per-request file lookup is measured on the Pi if cheap (peer request).
|
||||
|
||||
## Property-based testing (partial)
|
||||
- PBT-02/03 in U2: setup-token validator. A presented token is accepted iff it equals the configured one (generated strings including unicode and empty); never throws; a prefix or different token is rejected.
|
||||
- PBT-07/08/09 follow U1's helpers and framework (FsCheck.Xunit, test-only; referenced from `Modules.Identity.Tests`).
|
||||
+14
@@ -0,0 +1,14 @@
|
||||
# Tech Stack Decisions - andreaslop-client (U2)
|
||||
|
||||
| # | Decision | Rationale |
|
||||
|---|---|---|
|
||||
| T1 | New project `SlpModularCms.Api.AndreaSlopFotografie` (net10.0, Microsoft.NET.Sdk.Web), thin `Program.cs` on `CmsHost` with `WebsiteMode.PrerenderedPages`; same package references as `Api.SlpSoftware`, only the modules it needs | Brief; no new packages |
|
||||
| T2 | Modules: Core + Identity; `Master` and `Offerings` not referenced (capabilities must not list `Offerings`); `Availability` decided in Code Generation by checking whether the admin needs it | Brief D1/D9 |
|
||||
| T3 | Setup token: `SetupOptions` + `ISetupTokenValidator` in `Modules.Identity`; comparison via `CryptographicOperations.FixedTimeEquals` on SHA-256 digests | Constant time, no length leak, in-box API |
|
||||
| T4 | Rate limiting: reuse the `login` fixed-window policy via `[EnableRateLimiting("login")]` | Q3 = A; existing, tested mechanism |
|
||||
| T5 | Theme: plain CSS custom properties in `frontend/themes/asf/theme.css`, imported through a build-time Vite alias driven by `VITE_THEME`; fonts, logo and favicon as theme assets | No new dependency; Q5 = B |
|
||||
| T6 | Language default: `VITE_DEFAULT_LANGUAGE` read in i18n init | Existing i18next setup |
|
||||
| T7 | CI: new jobs `publish-asf-test` and `deploy-asf-test` in `continuous_integration.yaml`, gated by the Gitea variable `ASF_TEST_DEPLOY_ENABLED`; reuse `deploy-scp.yaml` unchanged | Q1, Q2; NFR-DEP-02 |
|
||||
| T8 | Gitea variables for ASF (non-secret): `DEPLOY_PATH_ASF_TEST`, `SERVICE_NAME_ASF_TEST`, `HEALTH_CHECK_URL_ASF_TEST`, `ASF_TEST_DEPLOY_ENABLED`; the SSH secrets `PI_MAIN_*` are the existing ones | Mirrors the existing pattern |
|
||||
| T10 | Forwarded headers: built-in `ForwardedHeadersMiddleware`, options from section `ForwardedHeaders` (`KnownProxies`), registered only when configured; limiters re-registered with `AddPolicy` and `RateLimitPartition.Get*Limiter` keyed on the client address | Option B; in-box APIs, no new packages |
|
||||
| T9 | Tests: xUnit + FluentAssertions + FsCheck.Xunit (test-only) for the validator and controller; Vitest for the setup page and theme/i18n; `Api.Tests` on MariaDB for regression | Existing frameworks |
|
||||
+20
@@ -0,0 +1,20 @@
|
||||
# Build and Test Summary - andreaslop-site-hosting (U1 + U2)
|
||||
|
||||
## Build Status
|
||||
- **Backend**: `dotnet build SlpModularCms.sln` succeeded (0 errors). **Frontend**: default and `VITE_THEME=asf` builds succeeded; `VITE_THEME=nope` fails as intended.
|
||||
- **Artifacts**: none published here (CI publishes `app-asf-test`).
|
||||
|
||||
## Test Execution Summary (local, 2026-11-07)
|
||||
### Unit tests
|
||||
- Core 351, Modules.Identity 57, Availability 82, Master 57, Offerings 57, ASF host configuration 5, frontend 293: **all passed**, 0 failed. ESLint and `tsc -b` clean.
|
||||
### Integration tests
|
||||
- In-memory integration (website routing, headers, proxy awareness, setup token controller): passed (inside Core/Identity counts).
|
||||
- **Not run locally**: `Api.Tests` and `Api.AndreaSlopFotografie.Tests/HostPipelineTests` (10 tests) need MariaDB, which is not available on this machine. They run in CI `backend-test`; result to be reported after the first push and CI run.
|
||||
### Performance
|
||||
- Local 0.72 ms/request (in-memory). Pi measurement pending the first test deploy.
|
||||
### Additional
|
||||
- **Security / dependency scan: was FAIL (pre-existing), FIXED with option A (Xml 10.0.14, zod ^4.6.6, react-router 1.170.46): now clean for NuGet and `pnpm audit --prod`; suites rerun green. Original finding:** `dotnet list package --vulnerable` reports `System.Security.Cryptography.Xml 10.0.10` and transitive `Pkcs 10.0.10` (high; patched in 10.0.12+, 10.0.14 available) in `Core` and four test projects; `pnpm audit --prod` reports 6 findings (seroval, zod; patched versions exist). Not caused by this feature, but the CI `vulnerability-scan` gate will fail and block publishing. Decision needed.
|
||||
- Contract/E2E: the curl checks in manual-steps 14-18 act as the E2E check on the test host after the first deploy.
|
||||
|
||||
## Overall Status
|
||||
- **Build**: Success. **All locally runnable tests**: Pass. **Ready for Operations**: Yes; the database-backed tests are unproven until CI runs.
|
||||
+16
@@ -0,0 +1,16 @@
|
||||
# Build Instructions
|
||||
|
||||
## Prerequisites
|
||||
- **Build tools**: .NET SDK 10 (`10.0.x`), Node 20+ with pnpm (CI uses Node 20, pnpm 9; local pnpm 12 works, lockfile format unchanged).
|
||||
- **Dependencies**: NuGet and npm registries reachable. New frontend packages: `@fontsource/jost@5.3.0`, `@fontsource/marcellus@5.3.0` (only bundled when `VITE_THEME=asf`).
|
||||
- **Environment variables** (admin build only, all optional): `VITE_THEME` (`asf`), `VITE_DEFAULT_LANGUAGE` (`nl`|`en`), `VITE_APP_TITLE`, `VITE_APP_ENV`, `VITE_SENTRY_DSN`.
|
||||
|
||||
## Build steps
|
||||
1. Backend, all projects: `dotnet build SlpModularCms.sln` (from the repo root). Expected: 0 errors; warnings NU1903/NU1902/NU1510 about packages are known (see summary).
|
||||
2. Admin, default look: `cd frontend && pnpm install --frozen-lockfile && pnpm build`.
|
||||
3. Admin, ASF look: `VITE_THEME=asf VITE_DEFAULT_LANGUAGE=nl VITE_APP_TITLE="Andrea Slop Fotografie" pnpm build`. Expect `dist/favicon-theme.png`, four `*.woff2` files and `index.html` linking `/admin/favicon-theme.png`. An unknown `VITE_THEME` must fail the build.
|
||||
4. Publish as CI does: copy `frontend/dist/.` to `src/SlpModularCms.Api.AndreaSlopFotografie/wwwroot/admin/`, then `dotnet publish -c Release -r linux-arm64 --self-contained false` in that project.
|
||||
|
||||
## Troubleshooting
|
||||
- `Unknown VITE_THEME "x"`: the name must be a folder under `frontend/themes/` containing `theme.css` (available: `asf`).
|
||||
- Lockfile mismatch in CI: run `pnpm install` locally with the same major lockfile format and commit `pnpm-lock.yaml`.
|
||||
+12
@@ -0,0 +1,12 @@
|
||||
# Integration Test Instructions
|
||||
|
||||
## Scenarios
|
||||
1. **Real host with database** (`Api.Tests`, `Api.AndreaSlopFotografie.Tests/HostPipelineTests`): `WebApplicationFactory` boots the composed pipeline in `Development`; checks `/health`, `/api/v1/System/capabilities` (Identity and Availability present; Offerings and Master absent), `Setup/status` (`tokenRequired:false` without token), the unknown website path (404 with `StrictSite` CSP and `X-Robots-Tag: noindex, nofollow`), and `/robots.txt` (`Disallow: /`). The startup migration needs a reachable MariaDB.
|
||||
2. **Proxy awareness** (`Core.Tests/Hosting/Proxy`, in-memory, no database): untrusted peers cannot spoof `X-Forwarded-For`; a trusted proxy yields the real address/scheme and separate limiter buckets; no configuration keeps the old shared bucket.
|
||||
3. **Prerendered website** (`Core.Tests/Hosting/Website`, in-memory): routing parity, headers on every response, 404 page, 301 including the percent-encoded `Location`.
|
||||
|
||||
## Environment for scenario 1
|
||||
Local MariaDB matching `appsettings.Development.json`, or override `ConnectionStrings__DefaultConnection`. CI (`backend-test`) starts `mariadb:11` on port 3307 and runs `dotnet test SlpModularCms.sln -c Release`.
|
||||
|
||||
## Run
|
||||
`dotnet test SlpModularCms.sln -c Release` (with the database available). Cleanup: stop the container.
|
||||
+5
@@ -0,0 +1,5 @@
|
||||
# Performance Test Instructions
|
||||
|
||||
Requirement (NFR-PF): website responses must not add noticeable latency; per-request file lookup, no cache.
|
||||
- **Local (done)**: 500 `GET /over-mij` on an in-memory server = 0.72 ms per request (U1).
|
||||
- **On the Pi (after the first test deploy, optional, cheap)**: `for i in $(seq 1 200); do curl -s -o /dev/null -w "%{time_total}\n" http://127.0.0.1:5200/over-mij; done | sort -n | awk '{a[NR]=$1} END{print "median",a[int(NR/2)],"p95",a[int(NR*0.95)]}'`; repeat with the website folder on `/mnt/storage1`. Report the numbers in the hand-back; no load test is planned (single small site).
|
||||
+6
@@ -0,0 +1,6 @@
|
||||
# Security Test Instructions
|
||||
|
||||
- **Dependency scan**: `dotnet list SlpModularCms.sln package --vulnerable --include-transitive` (CI gate `vulnerability-scan` fails when it prints "has the following vulnerable packages") and `cd frontend && pnpm audit --prod`.
|
||||
- **Setup token**: unit tests cover only-exact-token-passes (PBT), uniform 401, no token in logs, whitespace-only token rejected at startup, limiter on both endpoints (configuration). Manual after the first deploy (manual-steps 16-17): wrong token gives the Dutch error and a `setup_token_rejected` log line, right token creates the owner, then remove the token from `shared/env`.
|
||||
- **Forwarded headers**: tests prove an untrusted peer cannot spoof; wildcard/unparsable proxy entries fail at startup. Manual: after the first deploy the visitor address (not 192.168.1.102) should be what the limiter/logs see.
|
||||
- **Headers**: CSP byte-identical to nginx (asserted); verify with `curl -I https://test.andreaslop.nl/` (manual-steps 14).
|
||||
+12
@@ -0,0 +1,12 @@
|
||||
# Unit Test Execution
|
||||
|
||||
## Run
|
||||
- Backend, suites that need no database (run each from the repo root):
|
||||
`dotnet test src/SlpModularCms.Core.Tests`, `...Modules.Identity.Tests`, `...Modules.Availability.Tests`, `...Modules.Master.Tests`, `...Modules.Offerings.Tests`, and `dotnet test src/SlpModularCms.Api.AndreaSlopFotografie.Tests --filter "FullyQualifiedName~HostConfigurationTests"`.
|
||||
- Frontend: `cd frontend && pnpm test` (Vitest, includes `themes/*.test.ts`), plus `pnpm lint` and `npx tsc -b`.
|
||||
|
||||
## Expected (2026-11-07, local)
|
||||
Core 351, Identity 57, Availability 82, Master 57, Offerings 57, ASF host configuration 5, frontend 293; 0 failures. Property-based tests (FsCheck, random seed per run) are part of Core and Identity; on failure the replay seed is printed in the message; pin the shrunk counterexample as an example test.
|
||||
|
||||
## If a test fails
|
||||
Read the failure and seed, reproduce, fix the code (not the test) unless the test is wrong, rerun several times for property tests (a failure may appear in only 1 of ~15 runs: this is how the U1 `Location` encoding defect was found).
|
||||
+26
@@ -0,0 +1,26 @@
|
||||
# Code Summary - core-site-hosting (U1)
|
||||
|
||||
## Created (src/SlpModularCms.Core/Hosting/Website/)
|
||||
- `WebsiteResolution.cs`, `WebsitePathResolver.cs` - pure resolver (R1-R14), max 2 file checks
|
||||
- `WebsiteOptions.cs` - `Website:NoIndex`
|
||||
- `WebsiteFileAccess.cs` - confined, fail-soft file provider, root looked up per call
|
||||
- `PrerenderedSiteMiddleware.cs` - redirects, robots, files via static-file middleware (cache rules, charset)
|
||||
- `WebsiteNotFoundHandler.cs` - final fallback: `404.html` with status 404, 405 for other methods
|
||||
- `PrerenderedSiteExtensions.cs` - `AddCmsWebsite` (gzip only), `UseCmsPrerenderedSite`, `MapCmsWebsiteNotFound`
|
||||
- `WebsiteHostingMarker.cs` - switches on the full header set
|
||||
|
||||
## Modified
|
||||
- `CmsHostOptions.cs` (+ `WebsiteMode`), `CmsHost.cs` (mode wiring, documented order), `StaticContentExtensions.cs` (mode parameter, defaults unchanged)
|
||||
- `Security/CspPolicyCatalog.cs` (+ `StrictSite`), `SecurityHeadersOptions.cs` (+ `AllowedSite*Origins`), `SecurityHeadersExtensions.cs` (validation, log), `CspPolicyProvider.cs`, `SecurityHeaderWriter.cs` (`alwaysSendDocumentHeaders`), `SecurityHeadersMiddleware.cs`
|
||||
- `WEBSITE_WORKSPACE.md`, `README.md`
|
||||
|
||||
## Tests (src/SlpModularCms.Core.Tests/Hosting/)
|
||||
- `Website/WebsitePathResolverTests.cs` (examples per rule), `WebsitePathResolverPropertyTests.cs` (FsCheck: PBT-03), `PrerenderedSiteIntegrationTests.cs` (in-memory server, 25 scenarios incl. full header set on page/asset/301/404/robots.txt, gzip-only, dotfiles, reserved prefixes, SpaFallback regression)
|
||||
- `Security/StrictSitePolicyTests.cs` (byte-for-byte CSP, PBT-02), `SecurityHeaderWriterDocumentHeadersTests.cs`
|
||||
- New test-only packages: `FsCheck.Xunit 3.4.0`, `Microsoft.AspNetCore.TestHost 10.0.9`
|
||||
|
||||
## Deviations from the design
|
||||
1. The resolver has no `IsNotFoundPage` flag on `ServeFile`; the 404 page is handled only by `WebsiteNotFoundHandler`.
|
||||
2. Max 2 resolver file checks (plus 1 for `404.html` in the final stage) = 3 per request, as designed.
|
||||
3. Routing selects the catch-all fallback endpoint before the website middleware; the middleware clears the endpoint before delegating to the static-file middleware (otherwise the framework skips serving).
|
||||
4. The not-found fallback uses an explicit `{*path}` pattern (the default `nonfile` pattern would leave `/assets/missing.js` with a bare 404).
|
||||
+77
@@ -0,0 +1,77 @@
|
||||
# Business Logic Model - core-site-hosting (U1)
|
||||
|
||||
## Resolution flow (pure resolver)
|
||||
```mermaid
|
||||
flowchart TD
|
||||
S["Raw path + query"] --> V{"R2 valid?"}
|
||||
V -- no --> NF["NotFound"]
|
||||
V -- yes --> RS{"R1 reserved?"}
|
||||
RS -- yes --> PASS["Not handled (middleware passes on)"]
|
||||
RS -- no --> DOT{"R3 dot segment, not .well-known?"}
|
||||
DOT -- yes --> NF
|
||||
DOT -- no --> ROOT{"path is /?"}
|
||||
ROOT -- yes --> IDX["ServeFile index.html"]
|
||||
ROOT -- no --> IX{"R6 index variant?"}
|
||||
IX -- yes --> RD0["Redirect /"]
|
||||
IX -- no --> F4{"R7 404 or 404.html?"}
|
||||
F4 -- yes --> NF
|
||||
F4 -- no --> KN{"Known page by lowercased name?"}
|
||||
KN -- yes --> CAN{"Exactly canonical /name?"}
|
||||
CAN -- yes --> SF["ServeFile name.html"]
|
||||
CAN -- no --> RD1["Redirect /name + query"]
|
||||
KN -- no --> EXT{"Has extension?"}
|
||||
EXT -- yes --> FE{"File exists?"}
|
||||
FE -- yes --> SF2["ServeFile asset"]
|
||||
FE -- no --> NF
|
||||
EXT -- no --> TS{"R11 ends in slash?"}
|
||||
TS -- yes --> RD2["Redirect stripped path + query"]
|
||||
TS -- no --> DIR{"name/index.html exists?"}
|
||||
DIR -- yes --> SF3["ServeFile name/index.html"]
|
||||
DIR -- no --> NF
|
||||
|
||||
classDef ok fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef redir fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
classDef bad fill:#feb2b2,stroke:#c53030,stroke-width:1px,color:#000;
|
||||
classDef pass fill:#d6bcfa,stroke:#553c9a,stroke-width:1px,color:#000;
|
||||
class IDX,SF,SF2,SF3 ok;
|
||||
class RD0,RD1,RD2 redir;
|
||||
class NF bad;
|
||||
class PASS pass;
|
||||
```
|
||||
|
||||
Text alternative: invalid paths and dotfiles are NotFound; reserved prefixes pass on; known pages are served when canonical or redirected once; files with extensions are served or NotFound; other paths try the trailing-slash strip (R11), then a directory index (trailing slashes are always stripped by redirect, even for unknown targets), else NotFound.
|
||||
|
||||
## Response flow (middleware)
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["Request"] --> M{"GET or HEAD, not reserved?"}
|
||||
M -- no --> N["next()"]
|
||||
M -- yes --> RB{"NoIndex and /robots.txt?"}
|
||||
RB -- yes --> RT["200 Disallow all"]
|
||||
RB -- no --> R["Resolve"]
|
||||
R --> X{"Result"}
|
||||
X -- Redirect --> R301["301 Location"]
|
||||
X -- ServeFile --> SV["200 file, Cache-Control rule"]
|
||||
X -- NotFound --> N2["next() -> API routes"]
|
||||
N2 --> L{"Endpoint matched?"}
|
||||
L -- yes --> API["API response"]
|
||||
L -- no --> E404["404.html with status 404 (or empty 404)"]
|
||||
|
||||
classDef a fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef b fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
class RT,R301,SV,E404 a;
|
||||
class N,N2,API b;
|
||||
```
|
||||
|
||||
Text alternative: the middleware answers robots, redirects and files itself; unresolved paths continue to the API routes, and only if nothing matches does the final stage serve the 404 page.
|
||||
|
||||
## Header application (Q1 = A)
|
||||
All website responses, whatever the branch (200 file, 301, robots, 404 page, empty 404), pass through the security-headers stage with the full set of the active policy. The headers stage detects website requests (non-reserved path in `PrerenderedPages` mode) and skips the HTML-only distinction for them. `X-Robots-Tag` is added by the website stage when `NoIndex` is set.
|
||||
|
||||
## Dot-segment handling (Q2 = A)
|
||||
Refusal happens inside the pure resolver (R3), so it is covered by property tests and cannot be bypassed by the middleware. `/.well-known/...` resolves like any file path.
|
||||
|
||||
## Error handling
|
||||
- Resolver never throws; invalid input is `NotFound`.
|
||||
- File read errors in the middleware (race with a site delivery) -> 404 page; logged at warning level without the raw path.
|
||||
- Missing `wwwroot/web` -> every website path 404 (plain); host still starts and serves API and admin.
|
||||
+51
@@ -0,0 +1,51 @@
|
||||
# Business Rules - core-site-hosting (U1)
|
||||
|
||||
Applies only in `WebsiteMode.PrerenderedPages`. `SpaFallback` keeps today's behaviour.
|
||||
|
||||
## Path resolution (pure `WebsitePathResolver`)
|
||||
| # | Rule |
|
||||
|---|---|
|
||||
| R1 | Reserved: a path whose first segment is `admin`, `api` + `v1`, or `health` (whole segments, case-insensitive) is never resolved; the middleware passes it on. |
|
||||
| R2 | Invalid input is `NotFound`: null/empty, not starting with `/`, containing backslash, NUL or other control characters, `%`-encoded traversal after one decode pass, `..` segments, or longer than 2048 chars. |
|
||||
| R3 | **Dot segments (Q2 = A):** any segment starting with `.` is `NotFound`, except paths under `/.well-known/` (which are then served as ordinary files; `..` stays refused). |
|
||||
| R4 | A result `ServeFile` never points outside the website root; the relative path is forward-slash, validated before the predicate is called. |
|
||||
| R5 | `/` -> `ServeFile("index.html")`. |
|
||||
| R6 | `/index`, `/index.html`, `/index/` and case variants -> `Redirect("/")` (query preserved). |
|
||||
| R7 | `/404` and `/404.html` (any case) -> `NotFound` (no redirect, no serving of the page as 200). |
|
||||
| R8 | Path with a file extension: served as a file when it exists, else `NotFound`. Never lower-cased, never redirected (hashed asset names), never falls back to a page. Exception: `<name>.html` for a known page redirects (R10). |
|
||||
| R9 | Extensionless `/x` where `x.html` exists (name lower-cased) and the request is exactly `/x` -> `ServeFile("x.html")`. `/x/index.html` is served if it exists and `x.html` does not. |
|
||||
| R10 | Non-canonical request for a known page (case variant, `.html` suffix, trailing slash) -> one `Redirect("/<lowercase-name>")`, query string appended unchanged. Target comes from the known name, never from raw input. |
|
||||
| R11 | Any path longer than one character ending in one or more slashes (and not a known page, which R10 handles) -> `Redirect` (301) to the path with all trailing slashes stripped, query preserved, whether or not the target exists (website rule BR-HST-03; an unknown target yields the 404 page on the follow-up request). If the stripped target would start with `//` or `/\` or contain control characters it is `NotFound` (R12). `/` is never redirected. A redirect target never ends in a slash except `/` (idempotent with R6, R10). |
|
||||
| R12 | A redirect target starting with `//` or `/\` is never produced; such requests are `NotFound` (open-redirect guard). |
|
||||
| R13 | A directory without a page file is `NotFound`; no directory listing. |
|
||||
| R14 | Unknown path -> `NotFound`; the middleware turns it into the 404 page (R20). |
|
||||
|
||||
## Response rules (middleware)
|
||||
| # | Rule |
|
||||
|---|---|
|
||||
| R15 | `Redirect` -> status 301, relative `Location`, no body needed. |
|
||||
| R16 | Cache-Control: `/assets/**` -> `public, max-age=31536000, immutable`; every other website file -> `no-cache`. |
|
||||
| R17 | Compression only for non-reserved paths and these types: html, js, css, svg, json, xml, txt; `Vary: Accept-Encoding`. |
|
||||
| R18 | `Website:NoIndex = true`: `X-Robots-Tag: noindex, nofollow` on every website response; `GET /robots.txt` -> 200 `text/plain` `User-agent: *` / `Disallow: /`. When false, `/robots.txt` is served from the file if it exists, else 404. |
|
||||
| R19 | **Headers (Q1 = A):** every website response (page, asset, 301, 404, robots.txt) carries the full set of the active policy: CSP, HSTS, nosniff, `X-Frame-Options`, `Referrer-Policy`. The HTML-only distinction does not apply to website responses in this mode. API and admin responses keep today's rules. |
|
||||
| R20 | Unknown non-reserved path, after API routes had no match: serve `404.html` with status 404; if `404.html` is missing, plain 404 with empty body. Never `index.html`. |
|
||||
| R21 | An unknown `/api/v1` path stays an API 404 (not replaced by the website page). |
|
||||
| R22 | Methods: only GET and HEAD are served; others on website paths get 405 (`Allow: GET, HEAD`) unless an API route claims them. |
|
||||
|
||||
## StrictSite policy
|
||||
| # | Rule |
|
||||
|---|---|
|
||||
| R23 | `StrictSite` is in `KnownPolicies`; unknown policy names still fail startup validation. `Strict` and `Relaxed` outputs unchanged. |
|
||||
| R24 | CSP string, in this exact order: `default-src 'self'; script-src 'self' <site script origins>; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self' <site connect origins>; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'`. With the site's configured origins it equals the nginx value byte for byte. |
|
||||
| R25 | Site origin lists are used only by `StrictSite`; admin policies never gain them. Origins are validated like existing ones (https URL, no wildcard, no whitespace/semicolon). |
|
||||
| R26 | HSTS `max-age=31536000; includeSubDomains`, `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin`. |
|
||||
|
||||
## Security Baseline mapping (functional level)
|
||||
- Input validation centralised in the resolver (R2-R4, R12): satisfies path-traversal and open-redirect prevention.
|
||||
- Secure defaults: new settings default to today's behaviour (`SpaFallback`, empty lists, `NoIndex=false`).
|
||||
- Dotfile refusal (R3) prevents accidental disclosure from a delivered site.
|
||||
|
||||
## PBT properties (partial scope)
|
||||
- PBT-02 round trip: building a policy then parsing its CSP directives yields the configured origins.
|
||||
- PBT-03 invariants: for any input, `Resolve` never throws; `ServeFile` paths contain no `..`, backslash, leading `/` or dot segment (except `.well-known`); `Redirect` locations start with a single `/`, never `//` or `/\`.
|
||||
- Idempotence: resolving a `Redirect` target (same predicate) never yields a second `Redirect`; a `Redirect` location never ends in `/` except `/` itself.
|
||||
+40
@@ -0,0 +1,40 @@
|
||||
# Domain Entities - core-site-hosting (U1)
|
||||
|
||||
No persistent data. All entities are in-memory values or configuration.
|
||||
|
||||
## Entities
|
||||
| Entity | Kind | Fields / values | Notes |
|
||||
|---|---|---|---|
|
||||
| `WebsiteMode` | enum | `SpaFallback` (0, default), `PrerenderedPages` (1) | On `CmsHostOptions.WebsiteMode` |
|
||||
| `WebsiteResolution` | closed union | `ServeFile(RelativePath, IsNotFoundPage)`, `Redirect(Location)`, `NotFound` | `Redirect` is always 301 with a relative `Location` built only from known-page names |
|
||||
| `WebsiteOptions` | options | `NoIndex: bool` (default false) | Section `Website`; validated at startup |
|
||||
| `SecurityHeadersOptions` (extended) | options | + `AllowedSiteScriptOrigins`, `AllowedSiteConnectOrigins` | Used only by `StrictSite` |
|
||||
| `StrictSite` policy | header set | CSP, HSTS, nosniff, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin` | CSP byte-identical to the site's current one |
|
||||
| Known page | derived | file `<lowercase-name>.html` present in `wwwroot/web` | Never cached; decided per request via the file-exists predicate |
|
||||
|
||||
## Configuration keys
|
||||
| Key | Default | Effect |
|
||||
|---|---|---|
|
||||
| `Website:NoIndex` | `false` | `X-Robots-Tag: noindex, nofollow` on every website response; `/robots.txt` answers `Disallow: /` |
|
||||
| `SecurityHeaders:DefaultPolicy` | `Strict` | Client sets `StrictSite` |
|
||||
| `SecurityHeaders:AllowedSiteScriptOrigins` | `[]` | Script origins of `StrictSite` |
|
||||
| `SecurityHeaders:AllowedSiteConnectOrigins` | `[]` | Connect origins of `StrictSite` |
|
||||
|
||||
## Relationships
|
||||
```mermaid
|
||||
classDiagram
|
||||
class CmsHostOptions { WebsiteMode }
|
||||
class WebsiteResolution
|
||||
class ServeFile { RelativePath, IsNotFoundPage }
|
||||
class Redirect { Location }
|
||||
class NotFound
|
||||
class WebsiteOptions { NoIndex }
|
||||
class SecurityHeadersOptions { AllowedSiteScriptOrigins, AllowedSiteConnectOrigins }
|
||||
WebsiteResolution <|-- ServeFile
|
||||
WebsiteResolution <|-- Redirect
|
||||
WebsiteResolution <|-- NotFound
|
||||
CmsHostOptions --> WebsiteOptions : enables when PrerenderedPages
|
||||
SecurityHeadersOptions --> CmsHostOptions : StrictSite for site client
|
||||
```
|
||||
|
||||
Text alternative: `WebsiteResolution` has three variants; the host option enables the website options and the client configures the StrictSite origin lists.
|
||||
+37
@@ -0,0 +1,37 @@
|
||||
# Logical Components - core-site-hosting (U1)
|
||||
|
||||
No infrastructure components (no queue, cache, breaker, store). All in-process.
|
||||
|
||||
| Component | Namespace / file (planned) | Role |
|
||||
|---|---|---|
|
||||
| `WebsitePathResolver`, `WebsiteResolution` | `Core.Hosting.Website` | Pure resolution (P1) |
|
||||
| `WebsiteOptions` (+ validator) | `Core.Hosting.Website` | `Website:NoIndex` |
|
||||
| `PrerenderedSiteMiddleware` | `Core.Hosting.Website` | HTTP adapter: redirects, files, robots, cache headers, logging |
|
||||
| `WebsiteNotFoundMiddleware` (final stage) | `Core.Hosting.Website` | `404.html` with status 404 after API routes |
|
||||
| `WebsiteFileAccess` | `Core.Hosting.Website` | Physical file provider rooted at `wwwroot/web`; exists/read with fail-soft (P2, P3) |
|
||||
| `PrerenderedSiteExtensions` | `Core.Hosting.Website` | `AddCmsWebsite`, `UseCmsPrerenderedSite`, `UseCmsWebsiteNotFound` |
|
||||
| `SecurityHeaderWriter` (extended), `SecurityHeadersMiddleware` (extended) | `Core.Hosting.Security` | P5 |
|
||||
| `CspPolicyCatalog` (+ `StrictSite`), `SecurityHeadersOptions` (+ site origin lists) | `Core.Hosting.Security` | R23-R26 |
|
||||
| `CmsHost`, `CmsHostOptions`, `StaticContentExtensions` | `Core.Hosting` | Mode wiring |
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
CH["CmsHost"] --> EXT["PrerenderedSiteExtensions"]
|
||||
EXT --> MW["PrerenderedSiteMiddleware"]
|
||||
EXT --> NF["WebsiteNotFoundMiddleware"]
|
||||
MW --> RES["WebsitePathResolver (pure)"]
|
||||
MW --> FA["WebsiteFileAccess"]
|
||||
NF --> FA
|
||||
CH --> SH["SecurityHeadersMiddleware"]
|
||||
SH --> W["SecurityHeaderWriter (+ force flag)"]
|
||||
SH --> CAT["CspPolicyCatalog (StrictSite)"]
|
||||
|
||||
classDef pure fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef core fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef sec fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
class RES pure;
|
||||
class CH,EXT,MW,NF,FA core;
|
||||
class SH,W,CAT sec;
|
||||
```
|
||||
|
||||
Text alternative: the host wires the website extensions and the security-header middleware; the site middleware uses the pure resolver and the confined file access; the header middleware uses the writer and the policy catalog.
|
||||
+24
@@ -0,0 +1,24 @@
|
||||
# NFR Design Patterns - core-site-hosting (U1)
|
||||
|
||||
| # | Pattern | Realises | Design |
|
||||
|---|---|---|---|
|
||||
| P1 | Pure core, thin adapter | NFR-MT-01, NFR-AV-03, PBT-03 | `WebsitePathResolver.Resolve` is a static total function; the middleware only translates `WebsiteResolution` into HTTP. Every rule R1-R14 is testable without a server. |
|
||||
| P2 | Defence in depth for path safety | Security Baseline | Layer 1: resolver validation (R2-R4, R12). Layer 2: file access only through a physical `IFileProvider` rooted at `wwwroot/web` (never `Path.Combine` with request data). A bug in one layer does not expose files outside the root. |
|
||||
| P3 | Fail-soft file access | NFR-AV-01, NFR-AV-02 | Predicate and read wrap IO errors: a missing root, a vanished file or a permission error yields `false` / 404 page plus a warning on `SlpModularCms.Website`. No exception reaches the pipeline. |
|
||||
| P4 | Bounded work per request | NFR-PF-01 | Resolution order is fixed so at most 3 predicate calls happen: (1) `<name>.html`, (2) the literal file for extension paths or `<name>/index.html`, (3) `404.html` for the final stage. Asserted with a counting predicate. |
|
||||
| P5 | Website-scope header forcing | R19, Q1 = A | `SecurityHeaderWriter.Apply` gets an extra parameter `alwaysSendDocumentHeaders`. `SecurityHeadersMiddleware` sets it true when `WebsiteMode` is `PrerenderedPages` and `PathString` is not reserved (`WebsitePathResolver.IsReservedPath`). Then CSP, X-Frame-Options and Referrer-Policy go on every website response whatever its content type (asset, 301, 404, robots.txt). API and admin keep the content-type rule. Default of the new parameter is false, so existing callers and tests are unchanged. |
|
||||
| P6 | Configuration-driven logging | NFR-OB-01..04 | A single `ILogger` with category `SlpModularCms.Website`; levels from `Logging:LogLevel` per environment. Path values are sanitised by a small helper before logging. |
|
||||
| P7 | Secure defaults | Security Baseline | `WebsiteMode.SpaFallback`, empty site origin lists and `NoIndex = false` reproduce today's behaviour; startup validation rejects invalid origins and unknown policy names. |
|
||||
| P8 | Single registration point | NFR-MT-01 | `AddCmsWebsite` / `UseCmsPrerenderedSite` own compression, noindex and the middleware; `CmsHost` only calls them when the mode asks for it, keeping `SpaFallback` untouched. |
|
||||
| P9 | Compression scoping | NFR-CP-01..03 | `UseWhen(path is not reserved)` around `UseResponseCompression`; gzip provider only, MIME list from the requirements. |
|
||||
|
||||
## Pipeline placement
|
||||
Security headers stay first (inside the exception handler). The website stage sits where `UseCmsStaticContent` is today, the 404 stage after `MapSentryTunnel`, replacing the catch-all website fallback in this mode.
|
||||
|
||||
## Behind the proxy Pi
|
||||
The proxy forwards plain HTTP/1.0 to the app port. `UseHttpsRedirection` finds no HTTPS port and does nothing; website redirects are relative (`Location: /over-mij`), so no scheme or host is ever constructed. HSTS is still sent by the host (non-Development), as nginx does.
|
||||
|
||||
## Open verification items (settled by tests in Code Generation)
|
||||
1. No HTTPS-redirect loop or absolute `http://` redirect with a plain HTTP request.
|
||||
2. Rate limiter default policy does not throttle website assets (check `AddCmsRateLimiting`).
|
||||
3. `HEAD` requests behave like `GET` without body.
|
||||
+56
@@ -0,0 +1,56 @@
|
||||
# NFR Requirements - core-site-hosting (U1)
|
||||
|
||||
## Scalability
|
||||
- NFR-SC-01: one small site on one Raspberry Pi behind the proxy Pi; tens of requests per second at most. No horizontal scaling, no shared state, no cache to invalidate.
|
||||
|
||||
## Performance
|
||||
- NFR-PF-01: a `Resolve` call performs at most **3** file-exists checks (Q3 = A). Asserted by a test with a counting predicate.
|
||||
- NFR-PF-02: a simple local timing check (resolve + serve a page, many iterations) is run once and recorded in the hand-back note. No hard SLA; the goal is to show no per-request cost worth caching.
|
||||
- NFR-PF-03: static files are streamed (no full buffering); response compression applies only to the listed text types.
|
||||
- NFR-PF-04: no load test in U1. (A load test on the Pi was not chosen.)
|
||||
|
||||
## Compression
|
||||
- NFR-CP-01: **gzip only**, like nginx today (Q1 = A). No Brotli provider is registered.
|
||||
- NFR-CP-02: types: html, js, css, svg, json, xml, txt; `Vary: Accept-Encoding`; non-reserved paths only.
|
||||
- NFR-CP-03: compression stays at the ASP.NET default of "not over HTTPS"; the proxy Pi forwards plain HTTP so it applies in practice.
|
||||
|
||||
## Availability and reliability
|
||||
- NFR-AV-01: a missing or half-delivered `wwwroot/web` never stops the host: website paths answer 404, API and admin keep working.
|
||||
- NFR-AV-02: no restart needed after a website delivery (per-request file checks, no cache).
|
||||
- NFR-AV-03: the resolver is total (never throws); file read errors in the middleware become a 404 page plus a warning.
|
||||
- NFR-AV-04: existing clients (`Api`, `Api.SlpSoftware`) behave exactly as today; their tests stay green.
|
||||
|
||||
## Observability (Q2)
|
||||
Bryan: "Alleen waarschuwingen en meer op de pi, op productie later bepalen". Implementation:
|
||||
- NFR-OB-01: the website serving uses a dedicated logger category (`SlpModularCms.Website`).
|
||||
- NFR-OB-02: 404s and 301s are logged at **Information** on that category; warnings for read errors and a missing `wwwroot/web`.
|
||||
- NFR-OB-03: levels come from per-environment appsettings: test sets `Information` for that category; default and production stay `Warning`. Production is a later config change, no code change.
|
||||
- NFR-OB-04: logs contain the sanitised path (control characters removed, length capped), never headers or cookies.
|
||||
|
||||
## Security (Security Baseline, blocking)
|
||||
| Item | Status |
|
||||
|---|---|
|
||||
| Input validation (path traversal, encoded/backslash/NUL, over-long, open redirect) | Compliant by design: single pure function, property-tested (R2-R4, R12) |
|
||||
| Dotfile exposure | Compliant: R3 refuses dot segments except `.well-known` |
|
||||
| Secure defaults | Compliant: new settings default to today's behaviour |
|
||||
| Security headers on every website response | Compliant by R19, tested on page, asset, 301, 404, robots.txt |
|
||||
| Log injection | Compliant: NFR-OB-04 |
|
||||
| Secrets in code or config | N/A for U1 (no secrets); setup token is U2 |
|
||||
| New dependencies | None in production code |
|
||||
| Authn/authz | N/A for U1 (public static content); API and admin unchanged |
|
||||
| Rate limiting | Unchanged; website static serving is not limited (same as nginx today) |
|
||||
|
||||
## Maintainability and testing
|
||||
- NFR-MT-01: all nginx-parity rules in one pure class; the middleware is a thin adapter.
|
||||
- NFR-MT-02: tests: unit tests per rule R1-R26, integration tests (`WebApplicationFactory`-style) for headers on all response kinds, regression suites of `Api` and `Api.SlpSoftware`.
|
||||
- NFR-MT-03: docs updated (`WEBSITE_WORKSPACE.md`, `README.md`).
|
||||
|
||||
## Property-based testing (partial: PBT-02, 03, 07, 08, 09)
|
||||
- PBT-02: policy round trip (configured origins appear in the built CSP and parse back).
|
||||
- PBT-03: resolver invariants (never throws; `ServeFile` safe paths; `Redirect` targets safe, never end in `/` except `/`, resolving a target never redirects again).
|
||||
- PBT-07: generators for paths (unicode, encoded, dots, slashes, case variants) kept in a shared test helper.
|
||||
- PBT-08: failing seeds are printed and a shrunk counterexample is added as a regular unit test.
|
||||
- PBT-09: a PBT framework is required; see tech-stack-decisions.md.
|
||||
|
||||
## Usability
|
||||
- N/A (no UI in U1).
|
||||
+12
@@ -0,0 +1,12 @@
|
||||
# Tech Stack Decisions - core-site-hosting (U1)
|
||||
|
||||
| # | Decision | Rationale |
|
||||
|---|---|---|
|
||||
| T1 | ASP.NET Core built-in `UseResponseCompression` with gzip provider only | Matches nginx; no new package; Q1 = A |
|
||||
| T2 | Built-in `IFileProvider` (physical, confined to `wwwroot/web`) for the file-exists predicate and streaming | No new package; traversal confinement is a second line of defence behind the resolver |
|
||||
| T3 | `ILogger` with category `SlpModularCms.Website`, level via `Logging:LogLevel` in appsettings per environment | Q2; production later = config only |
|
||||
| T4 | Test-only PBT framework **FsCheck.Xunit** (not currently in the repo) added to the Core test project | PBT-09 requires a framework; FsCheck is the standard for xUnit on .NET and is a test-only dependency (no production impact). Version pinned at code generation to a release older than two weeks |
|
||||
| T5 | `WebApplicationFactory`-based integration tests (or the existing test host pattern used by `Api` tests) | Verify headers and pipeline order end to end |
|
||||
| T6 | No new production NuGet packages | Smaller supply-chain surface (Security Baseline) |
|
||||
|
||||
**Flag for approval**: T4 adds a new test dependency; if you prefer a different PBT library, say so now.
|
||||
+51
@@ -0,0 +1,51 @@
|
||||
# Code Generation Plan - andreaslop-client (U2)
|
||||
|
||||
Single source of truth for U2 code generation. Brownfield. Application code under `src/` and `frontend/`; workflow under `.gitea/workflows/`; docs summary under `construction/andreaslop-client/code/`. Names follow the ASF convention (see infrastructure-design.md). No push; one local commit per part.
|
||||
|
||||
## Unit context
|
||||
- Implements FR-U2-01..05, NFR-* and P1-P12 (NFR design), infrastructure design (test only).
|
||||
- Depends on U1 (done): `WebsiteMode.PrerenderedPages`, `StrictSite`, `Website:NoIndex`.
|
||||
- Shared change (option B) touches `Api`, `Api.SlpSoftware`, `Api.Slave`: opt-in, safe degradation, full regression required.
|
||||
- Tests needing MariaDB (`Api.Tests`, host regression) are run if a local/Pi DB is reachable; otherwise reported as not runnable.
|
||||
|
||||
## Part A - Core: forwarded headers and per-client limiters (P11, P12)
|
||||
- [x] **A1** `Core/Hosting/ForwardedHeadersOptions` (`ForwardedHeaders:KnownProxies`), validation (unparsable and any-address entries rejected), registration; `UseForwardedHeaders` first in `CmsHost` only when proxies are configured (ForwardLimit 1, XForwardedFor|XForwardedProto, default known proxies cleared).
|
||||
- [x] **A2** `ClientPartitionKey` + `AddCmsRateLimiting`: per-client-address partitions for `login`, `refresh`, sentry-tunnel, `offerings-public`; fallback key when address unknown. Behaviour with no config is unchanged.
|
||||
- [x] **A3** Tests: options validation, partition key (incl. PBT: distinct addresses never share a bucket, same address always does), integration via TestServer (spoofed header from untrusted peer ignored; trusted proxy honoured; limiter isolates clients).
|
||||
- [x] **A4** Build + test Core and all three existing hosts' projects; regression for Api/Api.SlpSoftware/Api.Slave (MariaDB-dependent ones reported). (non-DB suites green; Api.Tests needs MariaDB, run in CI)
|
||||
|
||||
## Part B - Identity: setup token (P1-P3, P6)
|
||||
- [x] **B1** `SetupOptions` (`Identity:Setup:Token`), whitespace-only token = startup error; `ISetupTokenValidator` / `SetupTokenValidator` (SHA-256 + `CryptographicOperations.FixedTimeEquals`, header `X-Setup-Token`).
|
||||
- [x] **B2** `SetupController`: `[EnableRateLimiting("login")]` on both endpoints; `POST owner` checks token (identical 401 for missing/wrong, no detail); `GET status` returns `initialized` + `tokenRequired`.
|
||||
- [x] **B3** `SecurityEvents.SetupTokenRejected` (id 5007, `setup_token_rejected`), logged on failed attempts without echoing the token.
|
||||
- [x] **B4** Tests: validator (examples + PBT: only the exact token passes, any other string fails, no exception), controller (no token configured = today's behaviour; token required; 401 uniformity; event logged), status payload.
|
||||
- [x] **B5** Build + test `Modules.Identity` and its tests.
|
||||
|
||||
## Part C - New client project `SlpModularCms.Api.AndreaSlopFotografie`
|
||||
- [x] **C1** Project in `src/`, added to the solution under **Clients**; thin `Program.cs` with `CmsHostOptions { WebsiteMode = PrerenderedPages }`; Identity module; Availability module only if required (capabilities must not list `Offerings`).
|
||||
- [x] **C2** Three-file appsettings per the `dotnet-appsettings` skill (`appsettings.json` without secrets: `SecurityHeaders` `DefaultPolicy=StrictSite` + site Umami/Sentry origins, `Website:NoIndex=true`, JWT issuer/audience, rate limits), `launchSettings` port 5200, publish settings like Api.SlpSoftware.
|
||||
- [x] **C3** Tests: host regression (capabilities has no `Offerings`, `/health`, website serving from a temp `wwwroot/web`, headers), needs MariaDB like `Api.Tests`. (config tests run; pipeline tests need MariaDB, run in CI)
|
||||
- [x] **C4** Build + test.
|
||||
|
||||
## Part D - Frontend: ASF theme, language, setup token (P9, P10)
|
||||
- [x] **D1** `frontend/themes/asf/theme.css`: CSS variables only, ASF palette exactly as the website (Q5 = B, no contrast adjustment; trade-off recorded), self-hosted Marcellus/Jost, logo + favicon assets.
|
||||
- [x] **D2** Vite alias driven by `VITE_THEME` (unset = empty module, today's admin); `VITE_DEFAULT_LANGUAGE` in `i18n/config.ts` (stored choice > env default > browser).
|
||||
- [x] **D3** Setup page: token field only when `tokenRequired`; sends `X-Setup-Token`; translations nl/en.
|
||||
- [x] **D4** Vitest: theme alias unset/set, language order, setup page with/without token. Compute below-AA contrast pairs for the hand-back.
|
||||
- [x] **D5** Frontend lint, type-check, test, build for both default and `VITE_THEME=asf`.
|
||||
|
||||
## Part E - CI/CD (P8)
|
||||
- [x] **E1** `continuous_integration.yaml`: add `publish-asf-test` and `deploy-asf-test`, gated by `vars.ASF_TEST_DEPLOY_ENABLED == 'true'`, reusing `deploy-scp.yaml`; manual box "Deploy ASF test". Existing SlpSoftware jobs, env block and `deploy-scp.yaml` byte-for-byte unchanged (verified by diff). Admin build env: `VITE_THEME=asf`, `VITE_DEFAULT_LANGUAGE=nl`, `VITE_APP_ENV=test`, `VITE_SENTRY_DSN` from `VITE_SENTRY_DSN_ASF`.
|
||||
- [x] **E2** Validate YAML; confirm via diff that nothing else changed; note the open verification item (Gitea `vars` in job-level `if:`).
|
||||
|
||||
## Part F - Documentation and wrap-up
|
||||
- [x] **F1** Update `README.md`/`AGENTS.md` (+ mirrors `CLAUDE.md`, `.junie/guidelines.md`, `.github/copilot-instructions.md` together) for the new Clients project and the opt-in `ForwardedHeaders` setting; `WEBSITE_WORKSPACE.md` if affected.
|
||||
- [x] **F2** `construction/andreaslop-client/code/code-summary.md`.
|
||||
- [x] **F3** Full solution build and all tests; report results honestly.
|
||||
- [x] **F4** Local commits (code, then docs); no push.
|
||||
|
||||
## Deployment artifacts
|
||||
Workflow jobs (Part E) and appsettings (C2); Pi steps are in `manual-steps-for-bryan.md`. The test deploy itself only happens with Bryan's explicit go.
|
||||
|
||||
## Traceability
|
||||
A -> option B / NFR (proxy awareness); B -> FR-U2-05 (setup token); C -> FR-U2-01/02; D -> FR-U2-03; E -> FR-U2-04; F -> docs.
|
||||
+43
@@ -0,0 +1,43 @@
|
||||
# Infrastructure Design Plan - andreaslop-client (U2)
|
||||
|
||||
## Steps
|
||||
- [x] Analyse design artifacts (NFR requirements/design, `pi-inventory-notes.md`, `deploy-scp.yaml`, `continuous_integration.yaml`)
|
||||
- [x] Collect answers to the questions below
|
||||
- [x] Generate `infrastructure-design/infrastructure-design.md` (components, Pi layout, env variables, Gitea variables/secrets)
|
||||
- [x] Generate `infrastructure-design/deployment-architecture.md` (diagrams, deploy sequence)
|
||||
- [x] Generate `infrastructure-design/manual-steps-for-bryan.md` (complete ordered list, both web-delivery variants)
|
||||
- [x] Tell "CMS & API" the list is complete so Pi-Main can draft the commands
|
||||
|
||||
## Category evaluation
|
||||
- Deployment environment: on-premise Pis, test only (decided). Pattern copied from SlpSoftware test.
|
||||
- Compute: one .NET process (~250-300 MB), systemd user unit, port 5200; sizing fits the Pi 4 (decided).
|
||||
- Storage: MariaDB 10.11 `AndreaSlopFotografieTest` / `AndreaSlopFotografie@localhost` (decided); website files either in the release tree or on `/mnt/storage1` (Question 1).
|
||||
- Messaging: not applicable.
|
||||
- Networking: proxy Pi (TLS, certbot) forwards HTTP/1.0 to 192.168.1.102 -> app port 5200; ufw only from the proxy Pi; the proxy block must pass `X-Forwarded-For`/`-Proto` (decided by option B); first-deploy sequence (Question 2).
|
||||
- Monitoring: `/health`, logs via journald, Sentry (Question 3).
|
||||
- Shared infrastructure: runner (arm64 label for builds is NOT needed: publish runs on ubuntu-latest with `-r linux-arm64` exactly like SlpSoftware), the SSH deploy secrets `PI_MAIN_*`, the DB backup script (Pi-Main adds the new DB).
|
||||
|
||||
## Question 1: How does the website reach `wwwroot/web` on the test host?
|
||||
Both variants work without restart (U1 looks pages up per request). Which one do we document as THE path?
|
||||
- A) Symlink: `shared/wwwroot-web` points to `/mnt/storage1/www/html/andreaslop-test`, the folder the existing web deploy already writes to, so the current website pipeline keeps working unchanged (recommended: no change in the website repo; files live on the big disk, not on the SD card)
|
||||
- B) Direct: the website CI copies its build into `shared/wwwroot-web` on the SD card (needs a change in the website pipeline and its target path)
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (relayed via CMS and API, Bryan): symlink shared/wwwroot-web to /mnt/storage1/www/html/andreaslop-test; website repo deploy unchanged.
|
||||
|
||||
## Question 2: Health check and the first deploy
|
||||
The deploy workflow checks `/health` on the PUBLIC test URL after switching the release. That URL (`test.andreaslop.nl`) still points at the old nginx fallback until you switch the proxy-Pi route, so a first deploy before the switch fails its health check (the new release is then already live on port 5200, only the job is red).
|
||||
- A) Switch the proxy-Pi route to port 5200 first, then run the first deploy; the test site is down only for the minutes between the switch and the first successful deploy (recommended: simplest, test environment)
|
||||
- B) Deploy first with the health-check variable pointing to a temporary URL that already reaches port 5200 (extra hostname + certificate work for you), then switch the route
|
||||
- C) Deploy first, accept one red health check, verify manually on port 5200 from the proxy Pi, then switch the route
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (relayed via CMS and API, Bryan): switch the proxy-Pi route to port 5200 first, then run the first deploy; short downtime accepted; order and nginx fallback revert explicit in the manual steps.
|
||||
|
||||
## Question 3: Sentry for the new host and its admin
|
||||
- A) A new, separate Sentry project for the CMS host and admin, DSNs supplied through `shared/env` (backend `Observability__SentryDsn`) and the Gitea variable `VITE_SENTRY_DSN_ASF` (frontend) (recommended: keeps the website's own Sentry project clean)
|
||||
- B) Reuse the website's existing Sentry project (same DSN) for host and admin
|
||||
- C) No Sentry for now (empty DSN is a supported state); add later
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: B (relayed via CMS and API, Bryan): reuse the website existing Sentry project (same DSN) for host and admin.
|
||||
+14
@@ -0,0 +1,14 @@
|
||||
# NFR Design Plan - andreaslop-client (U2)
|
||||
|
||||
## Steps
|
||||
- [x] Analyse NFR requirements (nfr-requirements.md, tech-stack-decisions.md)
|
||||
- [x] Evaluate question categories; no open questions (justification below)
|
||||
- [x] Generate `nfr-design/nfr-design-patterns.md`
|
||||
- [x] Generate `nfr-design/logical-components.md`
|
||||
|
||||
## Category evaluation (why no questions)
|
||||
- Resilience: deploy resilience is inherited from `deploy-scp.yaml` (atomic switch, health check, previous release kept); the new part is only the skip switch (NFR-DEP-02), which has one obvious design.
|
||||
- Scalability and performance: N/A for U2 (one small instance).
|
||||
- Security: the token check, limiter and security event follow the answers Q3/Q4 and the existing `SecurityEvents` and rate-limiting mechanisms; placement has one sensible solution.
|
||||
- Logical components: no new infrastructure; one validator, one controller change, one security event, one CSS theme, two CI jobs.
|
||||
- Open verification items are listed in `nfr-design-patterns.md` and are settled by tests or the first test deploy.
|
||||
+57
@@ -0,0 +1,57 @@
|
||||
# NFR Requirements Plan - andreaslop-client (U2)
|
||||
|
||||
U2 Functional Design is skipped (execution plan: no new business domain).
|
||||
|
||||
## Steps
|
||||
- [x] Analyse unit context (requirements FR-U2-01..08, application design C1/C5/C6/C7, existing `continuous_integration.yaml`, `deploy-scp.yaml`, `SetupController`)
|
||||
- [x] Collect answers to the questions below
|
||||
- [x] Generate `nfr-requirements/nfr-requirements.md` and `tech-stack-decisions.md`
|
||||
- [x] Security Baseline and PBT applicability (tabulated in the artifacts)
|
||||
|
||||
## Findings from the existing code that shape the questions
|
||||
- `continuous_integration.yaml` deploys `Api.SlpSoftware` to its test host **automatically on every push to master** and has a separate opt-in production deploy. The reusable `deploy-scp.yaml` already does what Andrea needs (timestamped release, `shared/wwwroot-web` symlink, atomic `current` switch, health check), so both website-delivery variants only differ in what `shared/wwwroot-web` is.
|
||||
- `POST /Setup/owner` and `GET /Setup/status` are anonymous and have **no rate limiter**; only `/Auth/login` (`login` policy: 5 per 60 s) and refresh are limited.
|
||||
- The shared admin frontend is built once per publish job with Vite variables; it has `dev:slpsoftware` modes and a `useTheme` hook (light/dark).
|
||||
|
||||
## Pre-filled assumptions
|
||||
- Scale/availability: one small instance on the test Pi; no HA; rollback = previous release kept by `deploy-scp.yaml`.
|
||||
- Secrets (DB password, JWT secret, setup token, Sentry DSN) only in `shared/env` on the Pi and Gitea secrets/variables, never in the repository.
|
||||
- Tech stack: no new packages; theme is plain CSS variables; token comparison via `CryptographicOperations.FixedTimeEquals`.
|
||||
|
||||
## Question 1: When does the ASF test deploy run?
|
||||
- A) Only when someone starts the workflow manually and ticks a new box "Deploy ASF test" (recommended: a merge to master never touches Andrea's site by surprise; test only)
|
||||
- B) Automatically on every push to master, like `Api.SlpSoftware`, plus the manual box
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: B-ish (relayed via CMS and API, Bryan: Zelfde als nu): automatic test deploy on every push to master like Api.SlpSoftware, plus the manual box. Test only. Must skip cleanly while Andrea deploy variables and secrets are unset.
|
||||
|
||||
## Question 2: How do the pipelines relate?
|
||||
- A) Add separate jobs for the Andrea client (build its admin with its theme, publish its project, call the existing `deploy-scp.yaml`); the `Api.SlpSoftware` jobs stay byte-for-byte as they are (recommended: zero risk for the existing deploy)
|
||||
- B) Turn the existing publish job into a matrix over both clients (less duplication, but changes the working SlpSoftware pipeline)
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (relayed via CMS and API)
|
||||
|
||||
## Question 3: Rate limiting for the first-admin setup endpoints
|
||||
`/Setup/owner` and `/Setup/status` have no limiter today. With the optional setup token a stranger could still guess the token.
|
||||
- A) Put both setup endpoints under the existing `login` limiter policy (5 per 60 s), and log failed token attempts as a security event (recommended)
|
||||
- B) A new, separate `setup` limiter policy with its own settings
|
||||
- C) No limiter, only the token
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (relayed via CMS and API)
|
||||
|
||||
## Question 4: Setup token on the test instance
|
||||
- A) Required on test (set in `shared/env`); the token is only needed until the first administrator exists, and it can be removed from `shared/env` afterwards (recommended)
|
||||
- B) Optional on test (not set); the setup page is open until the first admin is created
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (relayed via CMS and API)
|
||||
|
||||
## Question 5: Theme accessibility target
|
||||
The theme maps Andrea's brand colours onto the admin's design tokens.
|
||||
- A) Text and interactive elements must reach WCAG AA contrast (4.5:1 text, 3:1 large text and UI); where the brand colour fails, the admin uses a darker/lighter variant of it (recommended)
|
||||
- B) Use the brand colours exactly as the website does, without a contrast check
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: B (relayed via CMS and API, Bryan explicit choice): brand colours exactly as the website, no contrast check. Trade-off recorded in nfr-requirements.md.
|
||||
+31
@@ -0,0 +1,31 @@
|
||||
# Code Generation Plan - core-site-hosting (U1)
|
||||
|
||||
Single source of truth for U1 code generation. Brownfield: modify in place. Application code under `src/`; docs summary under `construction/core-site-hosting/code/`.
|
||||
|
||||
## Unit context
|
||||
- Implements FR-U1-01..11 (requirements.md); rules R1-R26 (functional design); NFR-* and patterns P1-P9 (NFR design).
|
||||
- No user stories (skipped). No database, no frontend, no deployment change (U1 Infrastructure Design skipped, confirmed by CMS & API).
|
||||
- Depends on: existing `Core` hosting (`CmsHost`, `StaticContentExtensions`, security headers). Consumed later by U2 (`Api.AndreaSlopFotografie`).
|
||||
- Test project: `src/SlpModularCms.Core.Tests` (xunit, FluentAssertions, NSubstitute). New test-only packages: `Microsoft.AspNetCore.TestHost` (in-memory server, no MariaDB needed) and `FsCheck.Xunit` (PBT-09); versions pinned to releases older than two weeks.
|
||||
- Verified while planning: the rate limiter is endpoint-policy based (`login` etc.), so website files are not throttled (NFR design verification item 2).
|
||||
|
||||
## Steps
|
||||
- [x] **Step 1 - Options and mode.** `src/SlpModularCms.Core/Hosting/CmsHostOptions.cs`: add `WebsiteMode` enum and `WebsiteMode` property (default `SpaFallback`). Add `Website/WebsiteOptions.cs` (`NoIndex`).
|
||||
- [x] **Step 2 - Pure resolver.** `Website/WebsiteResolution.cs`, `Website/WebsitePathResolver.cs` implementing R1-R14 (incl. R3 dot segments, R11 trailing-slash redirect, `IsReservedPath`), max 3 predicate calls (P4).
|
||||
- [x] **Step 3 - Resolver tests.** `Website/WebsitePathResolverTests.cs` (example tests per rule, call-count test) and `Website/WebsitePathResolverPropertyTests.cs` (FsCheck: PBT-03 invariants, idempotence; shared generators, PBT-07; seed logging, PBT-08). Add package references.
|
||||
- [x] **Step 4 - StrictSite policy.** `CspPolicyCatalog`: `StrictSite` constant, `KnownPolicies`, `Build` overload with site origin lists, exact directive order (R24-R26). `SecurityHeadersOptions`: `AllowedSiteScriptOrigins`, `AllowedSiteConnectOrigins`; `SecurityHeadersExtensions`: origin validation including the new lists; `CspPolicyProvider` passes the lists. Existing call sites compile unchanged.
|
||||
- [x] **Step 5 - Policy tests.** Extend `CspPolicyCatalogTests` and `SecurityHeadersOptionsValidationTests`: byte-for-byte site CSP with the real origins, `Strict`/`Relaxed` unchanged, unknown names still fail, invalid site origins fail; PBT-02 round trip.
|
||||
- [x] **Step 6 - Header forcing (P5).** `SecurityHeaderWriter.Apply(..., alwaysSendDocumentHeaders = false)`; `SecurityHeadersMiddleware` sets it for non-reserved paths when `WebsiteMode.PrerenderedPages`. Needs the mode in the middleware: register a small `WebsiteHostingMarker` (singleton) from `AddCmsWebsite`. Writer tests for the flag.
|
||||
- [x] **Step 7 - File access.** `Website/WebsiteFileAccess.cs`: physical provider rooted at `wwwroot/web`, `Exists`, `Open`, fail-soft with logging (P2, P3), log path sanitiser (NFR-OB-04).
|
||||
- [x] **Step 8 - Middleware and wiring.** `Website/PrerenderedSiteMiddleware.cs` (R15-R18, R22, caching, robots, noindex, logging), `Website/WebsiteNotFoundMiddleware.cs` (R20-R21), `Website/PrerenderedSiteExtensions.cs` (`AddCmsWebsite` with gzip-only compression and options validation; `UseCmsPrerenderedSite`; `UseCmsWebsiteNotFound`). `CmsHost` and `StaticContentExtensions`: branch on `WebsiteMode`; `SpaFallback` path untouched; pipeline order documented in `CmsHost`.
|
||||
- [x] **Step 9 - Integration tests.** `Website/PrerenderedSiteIntegrationTests.cs` with an in-memory `TestServer` host composing the real security-header and website extensions over a temp `wwwroot/web`: pages, canonical 301s, trailing slash, assets (immutable), `no-cache`, 404 page with status 404, missing `404.html`, dotfiles and `.well-known`, reserved prefixes untouched (an unknown `/api/v1/x` stays a non-website 404), robots/noindex, full header set on page, asset, 301, 404, robots.txt (Q1 = A), gzip only, HEAD, no HTTPS-redirect loop on plain HTTP, missing `wwwroot/web` keeps host alive. Includes a local timing check (NFR-PF-02) printed to the test output.
|
||||
- [x] **Step 10 - Regression.** Run the full `Core.Tests`, `Modules.*.Tests` and `Api.Tests`/`Api.SlpSoftware` suites (the ones needing MariaDB are run if a local DB is reachable, otherwise reported as not runnable with the reason).
|
||||
- [x] **Step 11 - Documentation.** Update `WEBSITE_WORKSPACE.md` and `README.md` (mode, settings `Website:NoIndex`, `SecurityHeaders:AllowedSite*Origins`, `StrictSite`, logging category, behaviour table); mirror nothing in `AGENTS.md` (structure unchanged). Write `construction/core-site-hosting/code/code-summary.md`.
|
||||
- [x] **Step 12 - Build and test (Step 13.5).** `dotnet build SlpModularCms.sln`, run all U1 tests, fix until green.
|
||||
- [x] **Step 13 - Commit.** One commit on `feature/andreaslop-site-hosting` for U1 code (aidlc-docs committed separately or with it per repo habit); no push.
|
||||
|
||||
## Deployment artifacts
|
||||
None in U1 (config samples for the Andrea client belong to U2).
|
||||
|
||||
## Story traceability
|
||||
No stories (skipped by decision Q6). Traceability to requirements: Step 1 FR-U1-01; Step 2-3 FR-U1-02..04; Step 4-6 FR-U1-08..09; Step 7-8 FR-U1-03..07, 10; Step 11 FR-U1-11.
|
||||
+20
@@ -0,0 +1,20 @@
|
||||
# Functional Design Questions - core-site-hosting (U1)
|
||||
|
||||
## Question 1: Security headers on non-HTML website responses
|
||||
nginx sends the full header set (CSP, HSTS, nosniff, X-Frame-Options, Referrer-Policy and, on test, X-Robots-Tag) on every response, including assets, 301 redirects, robots.txt and the 404 page. The current host writer treats CSP, X-Frame-Options and Referrer-Policy as "HTML-only" headers. For website responses in `PrerenderedPages` mode:
|
||||
|
||||
- A) Send the full set on every website response, like nginx (assets, redirects, robots.txt, 404); the site's verify script can then assert identical headers everywhere (recommended)
|
||||
- B) Keep the current rule: CSP, X-Frame-Options and Referrer-Policy only on HTML responses; HSTS and nosniff on all
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (relayed via CMS & API: "Volledige set overal")
|
||||
|
||||
## Question 2: Hidden paths (dot segments)
|
||||
nginx test conf serves any file under the root. Should the host refuse paths with a segment starting with a dot (for example `/.git/config`, `/.env`)?
|
||||
|
||||
- A) Refuse (404) every dot-segment path except `/.well-known/...` (recommended: protects accidental dotfiles in a delivered site, keeps ACME/security.txt possible)
|
||||
- B) Refuse every dot-segment path without exception
|
||||
- C) No special rule, same as nginx
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (relayed via CMS & API: "Weigeren, behalve .well-known")
|
||||
+8
@@ -0,0 +1,8 @@
|
||||
# Functional Design Plan - core-site-hosting (U1)
|
||||
|
||||
- [x] Analyse unit context (unit-of-work.md, requirements FR-U1-01..11, website repo rules BR-HST, nginx test conf)
|
||||
- [x] Collect answers to `core-site-hosting-fd-questions.md`
|
||||
- [x] Generate `business-logic-model.md` (resolution flow, request flow, header rules)
|
||||
- [x] Generate `business-rules.md` (rule table R1.., decision flow)
|
||||
- [x] Generate `domain-entities.md` (WebsiteResolution, options, policy header set, config keys)
|
||||
- [x] No frontend artifacts (U1 has no UI)
|
||||
+15
@@ -0,0 +1,15 @@
|
||||
# NFR Design Plan - core-site-hosting (U1)
|
||||
|
||||
## Steps
|
||||
- [x] Analyse NFR requirements (nfr-requirements.md, tech-stack-decisions.md)
|
||||
- [x] Evaluate question categories; no open questions (justification below)
|
||||
- [x] Generate `nfr-design/nfr-design-patterns.md`
|
||||
- [x] Generate `nfr-design/logical-components.md`
|
||||
|
||||
## Category evaluation (why no questions)
|
||||
- Resilience: decided by NFR-AV-01..04 (host never stops, resolver total, read errors become 404 plus warning). No retries or circuit breakers apply to local file access.
|
||||
- Scalability: NFR-SC-01 (one small site); no scaling mechanism needed.
|
||||
- Performance: decided by Q3 (call-count test, timing check) and the no-cache decision D3.
|
||||
- Security: Security Baseline table in nfr-requirements.md; implementation choices follow existing code (`SecurityHeaderWriter`, `PathPolicyResolver`) and have one obvious solution.
|
||||
- Logical components: no queue, cache or breaker; only in-process classes. The one real design choice (how to force the full header set on website responses) follows from the existing writer and Q1 = A; it is documented and can be changed at the approval step.
|
||||
- Risk 2 from application design (HTTPS redirection behind the proxy Pi): inspected; the existing `UseHttpsRedirection` is a no-op without an HTTPS port, same as `Api.SlpSoftware` today; verified by an integration test in code generation.
|
||||
+40
@@ -0,0 +1,40 @@
|
||||
# NFR Requirements Plan - core-site-hosting (U1)
|
||||
|
||||
## Steps
|
||||
- [x] Analyse functional design (business-rules R1-R26, flows, entities)
|
||||
- [x] Collect answers to the questions below
|
||||
- [x] Generate `nfr-requirements/nfr-requirements.md`
|
||||
- [x] Generate `nfr-requirements/tech-stack-decisions.md`
|
||||
- [x] Security Baseline and PBT applicability check (tabulated in the artifacts)
|
||||
|
||||
## Pre-filled assumptions (tell me if wrong, via Other on the last question)
|
||||
- Scale: one small site on one Raspberry Pi behind the proxy Pi; tens of requests per second at most.
|
||||
- Availability: same as the host today; a missing or half-delivered `wwwroot/web` must never stop the host (website paths 404, API and admin keep working).
|
||||
- Security: Security Baseline applies (path validation in the resolver, secure defaults, no new dependencies); compression stays off for TLS-terminated traffic by default is irrelevant because the proxy Pi forwards plain HTTP.
|
||||
- Tech stack: built-in ASP.NET Core only (no new NuGet packages), xUnit and FsCheck if already used in the repo for PBT.
|
||||
|
||||
## Question 1: Compression algorithms
|
||||
nginx today uses gzip only. ASP.NET Core can also do Brotli.
|
||||
|
||||
- A) gzip only, same as nginx today (simplest, identical behaviour for the verify script) (recommended)
|
||||
- B) Brotli and gzip (smaller responses; the site's verify script must then accept `br`)
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (relayed via CMS & API: "Alleen gzip")
|
||||
|
||||
## Question 2: Observability of website traffic
|
||||
- A) Log nothing extra per request; log only warnings (file read errors, missing `wwwroot/web` at startup once) (recommended, no log noise on a small Pi)
|
||||
- B) Also log each 404 and each 301 at Information level (useful to spot broken links, noisy with crawlers)
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: Relayed via CMS & API, Bryan verbatim: "Alleen waarschuwingen en meer op de pi, op productie later bepalen". Interpretation (to be confirmed by approval): dedicated logger category, 404/301 at Information, level per environment (test = Information, default/production = Warning).
|
||||
|
||||
## Question 3: Performance verification
|
||||
Per-request `File.Exists` has no cache (design decision). How much proof do you want that this is fast enough?
|
||||
|
||||
- A) A unit/integration test asserting no unbounded work (a resolve does at most 3 file-exists calls) plus a simple local timing check recorded in the hand-back (recommended)
|
||||
- B) Only the file-exists-call-count test, no timing check
|
||||
- C) A load test against the test Pi after deploy (extra work in U2)
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (relayed via CMS & API: "Aantaltest plus lokale tijdmeting")
|
||||
@@ -0,0 +1,36 @@
|
||||
# Hand-back U1 - core-site-hosting
|
||||
|
||||
Branch `feature/andreaslop-site-hosting` (2 local commits, not pushed). Code summary: `construction/core-site-hosting/code/code-summary.md`.
|
||||
|
||||
## 1. What was built
|
||||
- `CmsHostOptions.WebsiteMode` (`SpaFallback` default, `PrerenderedPages`); existing clients unchanged.
|
||||
- Pure `WebsitePathResolver` (rules R1-R14), `PrerenderedSiteMiddleware`, final 404 fallback, gzip-only compression, `Website:NoIndex` (X-Robots-Tag + robots.txt), `WebsiteFileAccess` (per-request file lookup, no cache, no restart after delivery).
|
||||
- `StrictSite` policy with `SecurityHeaders:AllowedSiteScriptOrigins` / `AllowedSiteConnectOrigins` (used only by StrictSite); CSP is byte-identical to the nginx value (asserted in a test with the Umami and Sentry origins).
|
||||
- Full header set on every website response (page, asset, 301, 404, robots.txt) via a flag on the security-header writer; API and admin keep the HTML-only rule.
|
||||
- Docs: `WEBSITE_WORKSPACE.md`, `README.md`.
|
||||
|
||||
Deviations from the brief (reasons in code-summary.md): none in behaviour. Behaviour choices you reviewed: R11 nginx parity (301 on every trailing slash), dot segments refused except `/.well-known/`, full headers everywhere, gzip only, logging category `SlpModularCms.Website`.
|
||||
|
||||
Behaviour notes for the verify script: 405 (`Allow: GET, HEAD`) for non-GET/HEAD on non-reserved paths that no endpoint claims; `HEAD` is supported; `Location` is always relative; `/404` and `/404.html` answer the 404 page with status 404; a directory without a page file is 404; unknown `/api/v1/...` is an empty API 404.
|
||||
|
||||
## 2. Test results
|
||||
- Build: success. `Core.Tests`: 330 passed (resolver examples, FsCheck properties, StrictSite policy, 25 in-memory integration scenarios). `Modules.Identity.Tests` 37, `Master` 57, `Offerings` 57, `Availability` 82: all passed.
|
||||
- Property-based: FsCheck.Xunit 3.4.0 (test-only), 2000 generated paths per property, a new random seed each run; a failure prints the replay seed and the shrunk counterexample, which is then pinned as a plain example test (PBT-08). Properties: resolver never throws, ServeFile paths safe and existing, Redirect targets relative and never ending in `/` (except `/`), a redirect target never redirects again, reserved prefixes never resolved, at most 2 file checks; CSP origin round trip.
|
||||
- Regression `Api` / `Api.SlpSoftware`: `Api.Tests` (the only host test project; SlpSoftware has none) **could not run here**: it needs a reachable MariaDB and failed with socket errors at the startup migration. Not a code failure, but also not proven green. `Api` and `Api.SlpSoftware` build, default to `SpaFallback`, and a SpaFallback-mode integration test shows unchanged behaviour. Please run `Api.Tests` where a database exists (or I run it on the Pi in U2).
|
||||
- Local timing: 500 `GET /over-mij` on an in-memory server = 0.72 ms per request (not a Pi measurement).
|
||||
|
||||
## 3. Configuration values for the website repo
|
||||
- Client opt-in: `new CmsHostOptions { WebsiteMode = WebsiteMode.PrerenderedPages }` (done in U2 in `Api.AndreaSlopFotografie`).
|
||||
- `SecurityHeaders:DefaultPolicy = StrictSite`; `AllowedSiteScriptOrigins = [https://analytics.slpsoftware.nl]`; `AllowedSiteConnectOrigins = [https://analytics.slpsoftware.nl, https://o4511795618185216.ingest.de.sentry.io]`.
|
||||
- `Website:NoIndex = true` on test.
|
||||
- Headers sent on every website response: CSP (exact nginx string), `Strict-Transport-Security: max-age=31536000; includeSubDomains` (not in Development), `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin`; plus `X-Robots-Tag: noindex, nofollow` when NoIndex.
|
||||
- Cache-Control: `no-cache` for pages/root files, `public, max-age=31536000, immutable` under `/assets/`. HTML content type `text/html; charset=utf-8`.
|
||||
- Delivery path: `wwwroot/web/` of the published app (U2 decides whether CI writes there or a symlink to `/mnt/storage1/www/html/...`; both work without restart). Hostname, ports (5200 test) and the test deploy come with U2.
|
||||
- Logging: `Logging:LogLevel:SlpModularCms.Website = Information` on test (301/404 lines), Warning elsewhere.
|
||||
|
||||
## 4. Open questions and risks
|
||||
1. `Api.Tests` not run (no database); see section 2.
|
||||
2. HSTS is not sent when the host runs in `Development`; irrelevant on the Pi, relevant for local verify runs.
|
||||
3. Behind the proxy Pi the host sees plain HTTP; redirects are relative and `UseHttpsRedirection` stays a no-op, covered by a test, not yet observed on the Pi.
|
||||
4. No forwarded-headers handling was added; nothing in U1 needs the original scheme or host.
|
||||
5. Per-request file lookup is not measured on the Pi SD card / `/mnt/storage1`; I expect it to be fine, a measurement can follow in U2.
|
||||
@@ -0,0 +1,55 @@
|
||||
# Hand-back U2 - andreaslop-client
|
||||
|
||||
Branch `feature/andreaslop-site-hosting` (3 U2 commits on top of the U1 ones, **not pushed**, nothing deployed). Code summary: `construction/andreaslop-client/code/code-summary.md`. Test deploy status: **not done**, it needs Bryan's explicit go in this session and the Pi steps (`construction/andreaslop-client/infrastructure-design/manual-steps-for-bryan.md`, final).
|
||||
|
||||
## 1. What was built
|
||||
- New client `SlpModularCms.Api.AndreaSlopFotografie` (Identity + Availability; no Master, no Offerings), `WebsiteMode.PrerenderedPages`, port 5200, `StrictSite` default policy with the website's Umami/Sentry origins, `Website:NoIndex=true` committed, tests project.
|
||||
- Optional first-admin setup token (`Identity:Setup:Token`, `X-Setup-Token`, 401 identical for missing/wrong, `tokenRequired` in `GET Setup/status`, both setup endpoints under the `login` limiter, security event `setup_token_rejected` 5007).
|
||||
- Shared Core change (option B): opt-in `ForwardedHeaders:KnownProxies` and per-client-address rate-limit partitions for `login`, `refresh`, sentry-tunnel, `offerings-public`. Without configuration the old behaviour applies to `Api`, `Api.SlpSoftware`, `Api.Slave`.
|
||||
- Admin theme `asf` (`VITE_THEME=asf`, website palette exactly, Marcellus/Jost self-hosted, the website's real `favicon.png`), `VITE_DEFAULT_LANGUAGE=nl` (stored choice still wins), token field on the setup page.
|
||||
- CI: `config-asf`, `publish-asf-test`, `deploy-asf-test` behind Gitea variable `ASF_TEST_DEPLOY_ENABLED == 'true'`, manual box "Deploy ASF test"; existing jobs, env block and `deploy-scp.yaml` unchanged (diff = additions only).
|
||||
|
||||
## 2. Names (for U3 and Pi-Main)
|
||||
Gitea variables `ASF_TEST_DEPLOY_ENABLED`, `DEPLOY_PATH_ASF_TEST`, `SERVICE_NAME_ASF_TEST` (same form as `SERVICE_NAME_TEST`), `HEALTH_CHECK_URL_ASF_TEST`, `VITE_SENTRY_DSN_ASF` (DSN of the ASF **website** Sentry project); jobs `publish-asf-test`/`deploy-asf-test`; theme `frontend/themes/asf`; unit `andreaslopfotografie-test`; folder `apps/andreaslopfotografie/test`; DB `AndreaSlopFotografieTest` / user `AndreaSlopFotografie`; port 5200; shared/env variables listed in `infrastructure-design.md`.
|
||||
|
||||
## 3. U1 correction found during U2
|
||||
The 301 `Location` was built from the decoded path without re-encoding: `/a%3Fb/` redirected to `/a?b` (another resource), `#` would start a fragment, non-ASCII ended up raw in a header value. Found by the existing property test (flaky about 1 in 15 runs), fixed with `PathString.ToUriComponent` plus regression tests. Normal paths are unchanged. The host is never worse than before for such paths; whether nginx encodes identically is for the web verify (one encoded path), I cannot run nginx here.
|
||||
|
||||
## 4. Test results
|
||||
- Green locally: Core 351, Identity 57, Availability 82, Master 57, Offerings 57, ASF host configuration 5, frontend 293 (Vitest), ESLint and `tsc -b` clean, frontend builds for default and `asf` verified.
|
||||
- **Not run here (no MariaDB on this machine): `Api.Tests` and `Api.AndreaSlopFotografie.Tests/HostPipelineTests`.** The CI job `backend-test` starts MariaDB and runs them; the result will be reported after the first push and CI run.
|
||||
- **CI proof (branch `feature/andreaslop-site-hosting`, head e37b8f3, `workflow_dispatch`, all deploy inputs false)**: run 606 failed on one frontend test (first test of `SetupPage.test`, lazy-route spinner still shown after 8 s on the slow runner; CI frontend-test takes ~290 s, also on master); run 607 on the same commit is **fully green**: backend-test with MariaDB (Api.Tests 4/4, ASF host tests 10/10 incl. HostPipelineTests, Core 351, Identity 57, Availability 82, Master 57, Offerings 57), vulnerability-scan, frontend build/test/lint. Conclusion: cold-start timing flake of the first lazy-loaded test, not a defect; hardening is optional. No deploy job ran (all publish/deploy jobs skipped). `config-asf` ran because `ASF_TEST_DEPLOY_ENABLED=true` was set, which shows that `vars` in a job-level `if:` works on this Gitea.
|
||||
- Not yet observed, only possible on the first test deploy: forwarded headers and HTTP/1.0 behind the proxy Pi, `vars` in a job-level `if:` on this Gitea, per-request file lookup timing on the Pi.
|
||||
|
||||
## 5. Information, no action needed
|
||||
- Contrast pairs below WCAG AA (decision Q5 = B, colours exactly as the website): border on background 1.30:1 (decorative line colour) and ink-3 `#8a827a` on paper 3.54:1 (not used as a text colour by the theme). All text and button pairs pass AA, in light mode with the website palette. Dark mode is derived (the website has none; button accent lightened to `#8a9681` for 5.16:1).
|
||||
- Radius `0.25rem` is a choice; the website defines no radius token.
|
||||
- `logo.png` is not used: the admin has no logo element and the scope is tokens + favicon.
|
||||
- The admin favicon is `themes/asf/favicon.png` (copied read-only from the website; the website repo was not touched).
|
||||
|
||||
## 6. Open items and risks
|
||||
1. **Vulnerability gate (pre-existing advisories) - resolved with Bryan's go (option A)**: `System.Security.Cryptography.Xml` pin 10.0.10 -> 10.0.14 in `Core` and the Availability/Master/Offerings test projects (transitive `Pkcs` follows); frontend `zod` ^4.6.6 and `@tanstack/react-router` 1.170.46 (pulls `seroval` 1.7.9). `dotnet list package --vulnerable` is clean and `pnpm audit --prod` finds nothing; all suites rerun green. Shared packages changed: SlpSoftware and the other hosts get these patched versions too (DataProtection uses the Xml package), so watch the first SlpSoftware test deploy after merge.
|
||||
2. Setup token must be removed from `shared/env` after the first administrator exists (step 17).
|
||||
3. The proxy block change is only the `proxy_pass` target (port 5200); the website repo generator is updated in U3.
|
||||
4. Production for ASF is out of scope.
|
||||
|
||||
## 7. Addendum 2026-11-09: what happened after this hand-back (all on ASF test; nothing on production)
|
||||
After the first test deploy (run 608) the feature was used on `test.andreaslop.nl` and a series of defects and requests came back through the "CMS & API" session. Each has its own record under `aidlc-docs/bugs/` (cause, fix, test) and the deploys are in `audit.md`.
|
||||
|
||||
| Item | Record / where | Shared-code consequence for SlpSoftware |
|
||||
|---|---|---|
|
||||
| Admin files gave 404 in PrerenderedPages mode (catch-all route won over the admin static files) | audit.md, run 610; `notreserved` route constraint | none |
|
||||
| Invitation link pointed at the website root instead of `/admin/...` | audit.md, run 612; `buildAppUrl` | none (frontend only) |
|
||||
| Nine CMS points: invited name not stored, labels, Administrator may use site settings, deactivated or deleted users refused at once (JWT active check), re-inviting a deleted address, setup title, brand logo | `bugs/cms-admin-nine-points` | deactivation takes effect immediately; two additive nullable fields later; Administrator can switch availability |
|
||||
| Pending/expired invitations cannot be removed; invitation lifetime configurable | `bugs/invitation-delete-and-lifetime` | expired invitations now listed; `Identity:Invitation:ExpiryHours` |
|
||||
| Role hierarchy enforced in the API (Administrator only manages Users, never hands out Owner) | same record, follow-up decisions | stricter API |
|
||||
| Owner got 403 when promoting an Administrator to Owner (caller identified by a null name claim) | `bugs/owner-cannot-promote-requester-identity` | fixes the user-management API on every host |
|
||||
| Availability gate stopped the website and `/admin` of a disabled CMS (503) | `bugs/availability-gate-blocks-website-and-admin` | gate now covers `/api/` only |
|
||||
| Setup page shown when the setup status could not be read (429 from the strict login limiter) | `bugs/setup-page-after-failed-status-read` | status read moved to the `refresh` limiter |
|
||||
| Website log level cannot be set through a systemd EnvironmentFile (dot in the variable name) | `Website__LogLevel` (README, infra docs) | none |
|
||||
| Admin layout: the whole page scrolled and the sidebar moved with it | audit/commit `f242da8` | shared layout |
|
||||
| Flaky CI frontend test (redirect timers left running after unmount) | commit `892c548`, hook `useDelayedAction` | shared pages |
|
||||
|
||||
Also built on top of this feature, as its own feature branch: **identity-email-notifications** (mail for invitations, new links, notices and password reset; per-site sender in the site settings; three additive migrations). See `aidlc-docs/features/identity-email-notifications/handback.md`.
|
||||
|
||||
ASF test currently runs the branch `feature/identity-email-notifications` (it contains this whole feature plus the e-mail feature). Still not done for this feature: merge to master (needs Bryan's explicit go and the watched SlpSoftware test deploy), production.
|
||||
+28
@@ -0,0 +1,28 @@
|
||||
# Application Design (consolidated) - andreaslop-site-hosting
|
||||
|
||||
Details: `components.md`, `component-methods.md`, `services.md`, `component-dependency.md`.
|
||||
|
||||
## Decisions
|
||||
| # | Decision | Source |
|
||||
|---|---|---|
|
||||
| D1 | `CmsHostOptions.WebsiteMode` (`SpaFallback` default, `PrerenderedPages`); existing clients unchanged | Brief, FR-U1-01 |
|
||||
| D2 | All nginx-parity rules live in one pure `WebsitePathResolver` taking a file-exists predicate; the middleware is a thin adapter | Requirements FR-U1-02 |
|
||||
| D3 | A page is "known" by a per-request file-exists check on the lowercased name; no cache, no restart needed after a site delivery | Q2 = A |
|
||||
| D4 | `StrictSite` policy in `CspPolicyCatalog`, byte-identical to the site's current CSP; origins from new `AllowedSiteScriptOrigins` / `AllowedSiteConnectOrigins`, so admin policies stay as strict as today | Q1 = A |
|
||||
| D5 | Compression only for non-reserved paths; `/api/v1` and `/admin` not compressed by this feature | Requirements open point 5 |
|
||||
| D6 | Unknown website paths get `404.html` with status 404 in a final pipeline stage after API routes; an unknown `/api/v1` path stays an API 404 | FR-U1-03/04/10 |
|
||||
| D7 | Setup token: `Identity:Setup:Token` optional, header `X-Setup-Token`, constant-time compare, `GET /Setup/status` returns `tokenRequired`, setup page shows the field only when required | Q3 = A, FR-U2-07 |
|
||||
| D8 | Theme is a build-time CSS override of existing tokens (`VITE_THEME`), language default via `VITE_DEFAULT_LANGUAGE`; no runtime theme API | Brief D2, Q5 |
|
||||
| D9 | Module set of the Andrea client = its project references; `Availability` included only if the admin needs it (decided in U2 NFR/Code Generation, reported to the requester) | Brief D1 |
|
||||
| D10 | Unit order: U1 Core (with regression run), hand-back and wait for the requester's "go", then U2 | Brief, execution plan |
|
||||
|
||||
## Risks carried into Construction
|
||||
1. The existing security-header writer treats CSP/frame/referrer as HTML-only; website 301/asset/robots responses may need the full set (FR-U1-09). Settled in U1 Functional Design with tests.
|
||||
2. `UseHttpsRedirection` on plain HTTP behind the proxy Pi, and absent forwarded-headers handling: verify no loop or absolute `http://` redirect (website redirects are relative).
|
||||
3. Per-request `File.Exists` on a Pi SD card or `/mnt/storage1`: low cost expected; measured in U1 NFR Design.
|
||||
4. Setup endpoints and rate limiting: confirm the login limiter covers `/Setup/owner` (NFR Design U2).
|
||||
5. Frontend setup page change touches an existing screen (small, covered by tests).
|
||||
|
||||
## Security Baseline / PBT applicability (design stage)
|
||||
- Security: path input validation centralised in one pure function; secure-by-default configuration (new settings default to today's behaviour); no secrets in repo (token and DB password come from the environment); constant-time token compare; no new dependencies. Compliant / N/A items are tabulated in the NFR stages.
|
||||
- PBT (partial): the resolver (PBT-02/03 invariants), canonical idempotence, policy round trip are pure and directly testable.
|
||||
+63
@@ -0,0 +1,63 @@
|
||||
# Component Dependencies - andreaslop-site-hosting
|
||||
|
||||
## Dependency matrix (row depends on column)
|
||||
|
||||
| | Core hosting | Security (CSP) | Identity | Frontend | CI/CD |
|
||||
|---|---|---|---|---|---|
|
||||
| C2 WebsiteMode | - | | | | |
|
||||
| C3 Site serving | uses | uses (headers precede it) | | | |
|
||||
| C4 StrictSite | | - | | | |
|
||||
| C1 Andrea client | references | configures | references | consumes built admin | built by |
|
||||
| C5 Theme | | | | - | selected by |
|
||||
| C7 Setup token | | | - (in module) | setup page | |
|
||||
| C6 CI/CD | | | | builds | - |
|
||||
|
||||
- C3a (pure resolver) depends on nothing but `System`; the predicate is injected. This keeps property-based testing trivial and keeps traversal safety in one testable place.
|
||||
- `Api` and `Api.SlpSoftware` depend on Core only through unchanged defaults (`WebsiteMode.SpaFallback`, empty site origin lists, no setup token configured).
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
opts["CmsHostOptions.WebsiteMode (C2)"]
|
||||
host["CmsHost / StaticContentExtensions"]
|
||||
mw["PrerenderedSiteMiddleware (C3c)"]
|
||||
res["WebsitePathResolver (C3a, pure)"]
|
||||
wopt["WebsiteOptions (C3b)"]
|
||||
csp["CspPolicyCatalog + SecurityHeadersOptions (C4)"]
|
||||
sethdr["SecurityHeadersMiddleware"]
|
||||
ident["Identity: SetupController + ISetupTokenValidator (C7)"]
|
||||
client["Api.AndreaSlopFotografie (C1)"]
|
||||
fe["frontend theme + setup page (C5, C7)"]
|
||||
ci["Gitea workflows (C6)"]
|
||||
|
||||
host --> opts
|
||||
host --> mw
|
||||
mw --> res
|
||||
mw --> wopt
|
||||
host --> sethdr
|
||||
sethdr --> csp
|
||||
client --> host
|
||||
client --> ident
|
||||
client --> csp
|
||||
fe --> ident
|
||||
ci --> client
|
||||
ci --> fe
|
||||
|
||||
classDef core fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef pure fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef newc fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
classDef ext fill:#d6bcfa,stroke:#553c9a,stroke-width:1px,color:#000;
|
||||
class opts,host,mw,wopt,sethdr,csp core;
|
||||
class res pure;
|
||||
class client,ident,fe newc;
|
||||
class ci ext;
|
||||
```
|
||||
|
||||
Text alternative: the host wires the options, the site middleware and the security-header middleware; the middleware depends on the pure resolver; the Andrea client references host and Identity and configures the policy; the frontend and CI build the client.
|
||||
|
||||
## Communication patterns
|
||||
- In-process only; no new network calls from the host.
|
||||
- Website to API: browser calls same-origin `/api/v1` where needed; Sentry and Umami origins are called directly by the site (listed in `StrictSite`).
|
||||
- Configuration is the only coupling between a client and a policy: `DefaultPolicy`, `PathPolicies`, `AllowedSite*Origins`, `Website:NoIndex`, `Identity:Setup:Token`.
|
||||
|
||||
## Delivery coupling (website files)
|
||||
`wwwroot/web` is owned by the website delivery (web CI or a symlink to `/mnt/storage1/www/html/andreaslop-test`); the host only reads it. Because pages are resolved per request without cache (Q2=A), both delivery variants work without restart.
|
||||
+72
@@ -0,0 +1,72 @@
|
||||
# Component Methods - andreaslop-site-hosting
|
||||
|
||||
Signatures are indicative; business rules are detailed in U1 Functional Design.
|
||||
|
||||
## Core - hosting
|
||||
```csharp
|
||||
public enum WebsiteMode { SpaFallback = 0, PrerenderedPages = 1 }
|
||||
|
||||
public sealed class CmsHostOptions { public WebsiteMode WebsiteMode { get; init; } = WebsiteMode.SpaFallback; }
|
||||
```
|
||||
|
||||
## C3a WebsitePathResolver
|
||||
```csharp
|
||||
public abstract record WebsiteResolution
|
||||
{
|
||||
public sealed record ServeFile(string RelativePath, bool IsNotFoundPage = false) : WebsiteResolution;
|
||||
public sealed record Redirect(string Location) : WebsiteResolution; // always 301, relative Location
|
||||
public sealed record NotFound : WebsiteResolution;
|
||||
}
|
||||
|
||||
public static class WebsitePathResolver
|
||||
{
|
||||
// Total: never throws, never returns a path outside the website root.
|
||||
// fileExists receives a relative, forward-slash, already-validated candidate ("over-mij.html").
|
||||
public static WebsiteResolution Resolve(string? rawPath, string? queryString, Func<string, bool> fileExists);
|
||||
public static bool IsReservedPath(string? rawPath); // /admin, /api/v1, /health (whole segments, case-insensitive)
|
||||
}
|
||||
```
|
||||
|
||||
## C3b/C3c Website serving
|
||||
```csharp
|
||||
public sealed class WebsiteOptions { public const string SectionName = "Website"; public bool NoIndex { get; set; } }
|
||||
|
||||
public static class PrerenderedSiteExtensions
|
||||
{
|
||||
public static IServiceCollection AddCmsWebsite(this IServiceCollection s, IConfiguration c); // options + validation + compression
|
||||
public static WebApplication UseCmsPrerenderedSite(this WebApplication app); // compression (UseWhen), noindex, resolver middleware
|
||||
}
|
||||
|
||||
public sealed class PrerenderedSiteMiddleware(RequestDelegate next, IWebHostEnvironment env, IOptions<WebsiteOptions> options)
|
||||
{
|
||||
public Task InvokeAsync(HttpContext context);
|
||||
}
|
||||
```
|
||||
`StaticContentExtensions.UseCmsStaticContent` / `MapCmsSpaFallbacks` branch on `WebsiteMode`: in `PrerenderedPages` they register the admin mount and the `/admin` fallback only, the website mount is `UseCmsPrerenderedSite`, and the catch-all website fallback is replaced by the middleware's 404 handling placed after API routes.
|
||||
|
||||
## C4 Security
|
||||
```csharp
|
||||
public static class CspPolicyCatalog
|
||||
{
|
||||
public const string StrictSite = "StrictSite";
|
||||
public static SecurityHeaderSet Build(string policy,
|
||||
IEnumerable<string> allowedScriptOrigins, IEnumerable<string> allowedConnectOrigins,
|
||||
IEnumerable<string>? siteScriptOrigins = null, IEnumerable<string>? siteConnectOrigins = null);
|
||||
}
|
||||
public sealed class SecurityHeadersOptions { /* + */ public IList<string> AllowedSiteScriptOrigins { get; set; } = []; public IList<string> AllowedSiteConnectOrigins { get; set; } = []; }
|
||||
```
|
||||
Existing call sites keep compiling (new parameters optional).
|
||||
|
||||
## C7 Setup token
|
||||
```csharp
|
||||
public sealed class SetupOptions { public const string SectionName = "Identity:Setup"; public string? Token { get; set; } }
|
||||
public interface ISetupTokenValidator { bool IsRequired { get; } bool IsValid(string? presentedToken); } // fixed-time comparison
|
||||
// SetupController
|
||||
// GET /Setup/status -> { initialized, tokenRequired }
|
||||
// POST /Setup/owner -> 401/403 problem details when token required and missing/wrong; header X-Setup-Token
|
||||
```
|
||||
|
||||
## Frontend
|
||||
- `theme.ts`/Vite plugin: resolves `VITE_THEME` to `themes/<name>/theme.css` import (no-op when unset).
|
||||
- `i18n init`: `lng = stored ?? import.meta.env.VITE_DEFAULT_LANGUAGE ?? browser default`.
|
||||
- Setup page: optional `setupToken` field; API client adds `X-Setup-Token` header.
|
||||
+39
@@ -0,0 +1,39 @@
|
||||
# Components - andreaslop-site-hosting
|
||||
|
||||
Numbering follows the brief (C1-C6); C7 is added by this design (setup token, requirements FR-U2-07).
|
||||
|
||||
## C2 WebsiteMode option (Core, `SlpModularCms.Core.Hosting`)
|
||||
- **Purpose**: Per-client choice of how the public website is served.
|
||||
- **Responsibilities**: `enum WebsiteMode { SpaFallback, PrerenderedPages }`; property `CmsHostOptions.WebsiteMode` (default `SpaFallback`).
|
||||
- **Interface**: read by `CmsHost.ConfigureServices/ConfigurePipeline` and `StaticContentExtensions`.
|
||||
|
||||
## C3 Prerendered site serving (Core, `SlpModularCms.Core.Hosting.Website`, new folder)
|
||||
Active only when `WebsiteMode = PrerenderedPages`.
|
||||
|
||||
| Part | Kind | Responsibility |
|
||||
|---|---|---|
|
||||
| C3a `WebsitePathResolver` | static, pure | Total function: (raw path, query string, `Func<string,bool> fileExists`) -> `WebsiteResolution` (`ServeFile(relativePath)`, `Redirect(location)`, `NotFound`). Contains every nginx-parity rule (canonical form, trailing slash, `/index`, traversal and backslash rejection, file-looking paths, reserved prefixes). No I/O, no clock, no logging. |
|
||||
| C3b `WebsiteOptions` | options | `Website:NoIndex` (default false), validated at startup. |
|
||||
| C3c `PrerenderedSiteMiddleware` | middleware | Adapter between HTTP and the resolver: supplies the file-exists predicate (confined to `wwwroot/web`), writes status, `Location`, `Cache-Control`, `X-Robots-Tag`, streams the file, serves `404.html` with status 404, answers `/robots.txt` when `NoIndex`. Never handles reserved prefixes. |
|
||||
| C3d Website compression | registration | Built-in response compression for the text MIME types, applied only to non-reserved paths (`UseWhen`), so `/api/v1` and `/admin` responses are never compressed by this feature. |
|
||||
|
||||
## C4 StrictSite policy (Core, `SlpModularCms.Core.Hosting.Security`)
|
||||
- **Purpose**: A third CSP policy for a prerendered public site, reproducing the site's current header byte for byte.
|
||||
- **Responsibilities**: `CspPolicyCatalog.StrictSite` constant, added to `KnownPolicies`; `Build` produces the site CSP with `X-Frame-Options: DENY` and `Referrer-Policy: strict-origin-when-cross-origin`; `SecurityHeadersOptions` gains `AllowedSiteScriptOrigins` and `AllowedSiteConnectOrigins`, used **only** by `StrictSite` (decision Q1=A). `Strict` and `Relaxed` outputs are unchanged.
|
||||
- **Check**: HSTS, `X-Content-Type-Options`, `Referrer-Policy` and the CSP appear on website pages, assets, 301s, 404 and robots.txt (FR-U1-09). The existing writer emits CSP/frame/referrer as "HTML-only" headers; whether non-HTML website responses also need them is settled in U1 Functional Design.
|
||||
|
||||
## C1 Client `SlpModularCms.Api.AndreaSlopFotografie` (Clients)
|
||||
- **Purpose**: Deployable host for Andrea's instance.
|
||||
- **Responsibilities**: thin `Program.cs` on `CmsHost` with `WebsiteMode.PrerenderedPages`; `.csproj` references the modules (Core, Identity, and Availability only if the admin needs it); three-file appsettings; own database connection string template (no password in repo); own dev port; `SecurityHeaders:DefaultPolicy = StrictSite` plus the site origin lists; `Website:NoIndex = true` for test.
|
||||
|
||||
## C5 Admin theme (frontend)
|
||||
- **Purpose**: Per-site look of the admin, fixed at build time.
|
||||
- **Responsibilities**: `frontend/themes/<name>/theme.css` overriding existing design tokens; theme assets (logo, favicon, self-hosted Marcellus and Jost); build-time selection by `VITE_THEME`; `VITE_DEFAULT_LANGUAGE` initial language (user choice still wins); unset variables reproduce today's admin.
|
||||
|
||||
## C6 CI/CD (Gitea workflows)
|
||||
- **Purpose**: Build and deploy each client with its own admin build.
|
||||
- **Responsibilities**: per-client admin build (`VITE_THEME`, `VITE_DEFAULT_LANGUAGE`, `VITE_APP_TITLE`), ARM64 publish of the new host, deploy to the test Pi using the existing atomic release switch, `wwwroot/web` outside the release directory; production path of `Api.SlpSoftware` untouched.
|
||||
|
||||
## C7 First-admin setup token (Identity module + frontend)
|
||||
- **Purpose**: Stop a stranger from claiming the first administrator on a freshly deployed, publicly reachable instance.
|
||||
- **Responsibilities**: `SetupOptions` (`Identity:Setup:Token`, optional); `ISetupTokenValidator` (constant-time compare, true when no token is configured); `SetupController.GetStatus` returns `tokenRequired`; `CreateOwner` requires header `X-Setup-Token` when configured; setup page in the frontend shows a token field only when `tokenRequired` is true (decision Q3=A). Existing hosts without the setting behave exactly as before.
|
||||
@@ -0,0 +1,66 @@
|
||||
# Services and Orchestration - andreaslop-site-hosting
|
||||
|
||||
No new domain services or database tables. Orchestration is host composition and one request pipeline.
|
||||
|
||||
## Host composition (`CmsHost`)
|
||||
- `ConfigureServices`: `AddCmsSecurityHeaders` (now with site origin lists), `AddCmsWebsite` (only when `WebsiteMode = PrerenderedPages`). Identity registers `SetupOptions` and `ISetupTokenValidator` in its own module registration.
|
||||
- `ConfigurePipeline` order (documented in `CmsHost`):
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["Exception handler"] --> B["Security headers"]
|
||||
B --> C["Rate limiter"]
|
||||
C --> D["HTTPS redirection (no-op on plain HTTP)"]
|
||||
D --> E["Admin static mount + /admin redirect"]
|
||||
E --> F["Website: compression (non-reserved paths) + noindex"]
|
||||
F --> G["Website resolver middleware (pages, assets, redirects, robots)"]
|
||||
G --> H["CORS, module middleware, auth"]
|
||||
H --> I["MapControllers (/api/v1)"]
|
||||
I --> J["Health checks, Sentry tunnel"]
|
||||
J --> K["Admin SPA fallback"]
|
||||
K --> L["Website 404 (404.html, status 404)"]
|
||||
|
||||
classDef sec fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
classDef site fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef api fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
class A,B,C,D sec;
|
||||
class E,F,G,K,L site;
|
||||
class H,I,J api;
|
||||
```
|
||||
|
||||
Text alternative: security stages first (yellow), then the admin and website mounts (blue), then API routes (green); unknown website paths fall to 404 last, so API 404s are never replaced by the website page.
|
||||
|
||||
Notes:
|
||||
- The resolver middleware passes reserved prefixes (`/admin`, `/api/v1`, `/health`) straight on, and passes on unknown paths **only** after API routes had a chance; the final 404 stage serves `404.html` with status 404 for non-reserved paths. Pages that resolve (`ServeFile`, `Redirect`) are answered in step G, before the API; this is safe because the pure resolver never resolves reserved prefixes.
|
||||
- `SpaFallback` mode keeps today's pipeline untouched.
|
||||
|
||||
## Request flow (website page)
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
box rgba(246,224,94,0.4) Client
|
||||
participant B as Browser or proxy Pi
|
||||
end
|
||||
box rgba(99,179,237,0.4) Host
|
||||
participant M as SiteMiddleware
|
||||
participant R as PathResolver
|
||||
participant F as wwwroot web
|
||||
end
|
||||
B->>M: GET /Over-Mij?x=1
|
||||
M->>R: Resolve path, query, fileExists
|
||||
R->>F: fileExists over-mij.html
|
||||
F-->>R: true
|
||||
R-->>M: Redirect /over-mij?x=1
|
||||
M-->>B: 301 Location /over-mij?x=1 plus security headers
|
||||
B->>M: GET /over-mij
|
||||
M->>R: Resolve
|
||||
R-->>M: ServeFile over-mij.html
|
||||
M-->>B: 200 html, no-cache, compressed
|
||||
```
|
||||
|
||||
Text alternative: the middleware asks the pure resolver, which uses a file-exists check; a non-canonical request gets one 301, then the canonical request is served as a file.
|
||||
|
||||
## Setup flow
|
||||
Browser loads setup page -> `GET /Setup/status` -> `tokenRequired` decides whether the token field is shown -> `POST /Setup/owner` with `X-Setup-Token` -> `ISetupTokenValidator` -> existing `ISetupService.CreateInitialOwnerAsync`. Login rate limiting policy also covers the setup endpoints (verified in NFR Design).
|
||||
|
||||
## Build and deploy flow (C6)
|
||||
CI: admin build per client (env: theme, language, title) -> copy into client `wwwroot/admin` -> `dotnet publish` (linux-arm64) -> scp to `releases/<id>` -> atomic switch of `current` -> restart user unit -> smoke checks (`/health`, `/api/v1/System/capabilities`, a website page). `wwwroot/web` is a symlink in `shared/`, so it survives every release.
|
||||
+22
@@ -0,0 +1,22 @@
|
||||
# Unit Dependencies - andreaslop-site-hosting
|
||||
|
||||
| Unit | Depends on | Reason |
|
||||
|---|---|---|
|
||||
| U1 | existing Core | extends it additively |
|
||||
| U2 | U1 | client uses `WebsiteMode.PrerenderedPages`, `StrictSite`, `Website:NoIndex` |
|
||||
| U2 | requester "go" | hand-back gate |
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
U1["U1 core-site-hosting"] --> H1["Hand-back + go from CMS & API"] --> U2["U2 andreaslop-client"] --> BT["Build and Test"] --> OP["Operations"]
|
||||
classDef u fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
classDef g fill:#d6bcfa,stroke:#553c9a,stroke-width:1px,color:#000;
|
||||
classDef n fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
class U1,U2 u;
|
||||
class H1 g;
|
||||
class BT,OP n;
|
||||
```
|
||||
|
||||
Text alternative: U1, then the hand-back gate, then U2, then Build and Test and Operations.
|
||||
|
||||
Shared contract between units: configuration names (`WebsiteMode` in code, `Website:NoIndex`, `SecurityHeaders:DefaultPolicy=StrictSite`, `SecurityHeaders:AllowedSiteScriptOrigins`, `SecurityHeaders:AllowedSiteConnectOrigins`). U1 fixes these names; U2 only uses them.
|
||||
+13
@@ -0,0 +1,13 @@
|
||||
# Requirement-to-Unit Map (User Stories skipped)
|
||||
|
||||
| Requirement | Unit |
|
||||
|---|---|
|
||||
| FR-U1-01 .. FR-U1-11 | U1 |
|
||||
| FR-U2-01 client project, FR-U2-02 module set | U2 |
|
||||
| FR-U2-03 theme | U2 |
|
||||
| FR-U2-04 CI/CD, FR-U2-05 test deploy, FR-U2-06 Pi provisioning | U2 |
|
||||
| FR-U2-07 setup token, FR-U2-08 auth unchanged | U2 |
|
||||
| Security Baseline, PBT partial, per-unit build/test | both |
|
||||
| Git rules (one branch, no push, PR after U2) | both |
|
||||
|
||||
All requirements are assigned to a unit.
|
||||
+22
@@ -0,0 +1,22 @@
|
||||
# Units of Work - andreaslop-site-hosting
|
||||
|
||||
Terminology: both units are changes to the same deployable codebase ("Unit of Work" = planning/delivery slice), delivered on one branch, commits per unit.
|
||||
|
||||
## U1 core-site-hosting
|
||||
- **Scope**: C2 WebsiteMode, C3 prerendered site serving (resolver, middleware, options, compression), C4 StrictSite policy and site origin lists, pipeline order, docs (`README.md`, `WEBSITE_WORKSPACE.md`).
|
||||
- **Code locations**: `src/SlpModularCms.Core/Hosting/**` (+ `src/SlpModularCms.Core.Tests/**`).
|
||||
- **Not touched**: `Api`, `Api.SlpSoftware` sources (only regression-tested), Identity, frontend, CI.
|
||||
- **Construction stages**: Functional Design, NFR Requirements, NFR Design, Code Generation (Infrastructure Design skipped).
|
||||
- **Done when**: requirements acceptance (U1) met, per-unit build and tests green, `Api`/`Api.SlpSoftware` regression green, hand-back note sent, **requester's "go" received**.
|
||||
- **Commit(s)**: on `feature/andreaslop-site-hosting`; no push.
|
||||
|
||||
## U2 andreaslop-client
|
||||
- **Scope**: C1 client project and solution entry (Clients), C5 theme and build variables, C7 setup token (Identity + setup page), C6 CI/CD, Pi manual-step list, test deploy (with Bryan's go, test only).
|
||||
- **Code locations**: `src/SlpModularCms.Api.AndreaSlopFotografie/**`, `src/SlpModularCms.Modules.Identity/**` (+ tests), `frontend/**`, `.gitea/workflows/**`, `SlpModularCms.sln`, docs.
|
||||
- **Construction stages**: NFR Requirements, NFR Design, Infrastructure Design, Code Generation (Functional Design skipped).
|
||||
- **Starts**: only after U1 hand-back and the requester's "go".
|
||||
- **Done when**: requirements acceptance (U2) met, hand-back note sent.
|
||||
- **Commit(s)**: same branch; one PR after U2 when Bryan asks.
|
||||
|
||||
## Cross-unit
|
||||
Build and Test (all units), then Operations (Deployment Setup, Monitoring Setup, Production Readiness for the test environment).
|
||||
+46
@@ -0,0 +1,46 @@
|
||||
# Application Design Plan - andreaslop-site-hosting
|
||||
|
||||
## Steps
|
||||
- [x] Analyse requirements and host code (done: CmsHost, StaticContentExtensions, CspPolicyCatalog, SecurityHeadersOptions, SetupController)
|
||||
- [x] Collect answers to the design questions below
|
||||
- [x] Generate components.md
|
||||
- [x] Generate component-methods.md
|
||||
- [x] Generate services.md
|
||||
- [x] Generate component-dependency.md
|
||||
- [x] Generate application-design.md (consolidated)
|
||||
- [x] Validate completeness and consistency (security baseline / PBT applicability)
|
||||
|
||||
## Facts from the code that shape the questions
|
||||
- `SecurityHeadersOptions.AllowedConnectOrigins` is applied to **both** `Strict` and `Relaxed`. If the Umami and Sentry origins were put there for Andrea's site, the admin (`/admin`, `/api/v1`, under `Strict`) would get them too. `AllowedScriptOrigins` is only used by `Relaxed` today.
|
||||
- Linux file systems are case-sensitive, and all page files are lowercase. A request `/Over-Mij` therefore resolves to a known page exactly when `over-mij.html` exists. A cached "known page set" is not strictly needed: a file-exists predicate on the lowercased name gives the same nginx behaviour.
|
||||
- `UseHttpsRedirection` is a no-op when the host listens on plain HTTP only without an HTTPS port configured; the proxy Pi talks HTTP to the app. There is no forwarded-headers handling in `CmsHost` today. To be verified in NFR Design against the SlpSoftware deployment.
|
||||
- `SetupController` (`GET /Setup/status`, `POST /Setup/owner`) has no protection other than "system not yet initialised". The admin setup page posts to it.
|
||||
|
||||
## Design Questions
|
||||
|
||||
### Question 1: Origins for the StrictSite policy
|
||||
Where do the Umami script origin and the Sentry connect origins for the website live?
|
||||
|
||||
- A) New separate lists in `SecurityHeaders` (for example `AllowedSiteScriptOrigins`, `AllowedSiteConnectOrigins`) used only by `StrictSite`; the admin policies stay exactly as strict as today (recommended)
|
||||
- B) Reuse the existing `AllowedScriptOrigins` / `AllowedConnectOrigins`; accept that `Strict` (admin and API) then also lists the Sentry ingest origin in `connect-src`
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (RELAYED by CMS & API on Bryan's behalf; confirmed when Bryan approves the design)
|
||||
|
||||
### Question 2: How the host decides a page is "known"
|
||||
nginx canonicalises (301) only known pages. How should the host decide this?
|
||||
|
||||
- A) Per request, a file-exists check on the lowercased name (`<name>.html`, or `<name>/index.html`); no cache, so a site delivered in place (symlink variant, rsync) is always current. The pure resolver takes the check as a predicate (recommended)
|
||||
- B) A snapshot of the known pages built at startup and refreshed on a short timer or file watcher
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (RELAYED by CMS & API on Bryan's behalf; confirmed when Bryan approves the design)
|
||||
|
||||
### Question 3: First-admin setup token in the admin
|
||||
The setup token protects `POST /Setup/owner`. How does the person doing the first setup supply it?
|
||||
|
||||
- A) The setup page shows a "setup token" field, but only when the server says one is required (`GET /Setup/status` returns `tokenRequired`); the token is sent in a request header; small frontend change, no change when no token is configured (recommended)
|
||||
- B) No frontend change: the token is sent only as a header by a direct API call (for example curl), the setup page stays as it is
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (RELAYED by CMS & API on Bryan's behalf; confirmed when Bryan approves the design)
|
||||
@@ -0,0 +1,170 @@
|
||||
# Execution Plan - andreaslop-site-hosting
|
||||
|
||||
## Detailed Analysis Summary
|
||||
|
||||
### Transformation Scope (Brownfield)
|
||||
- **Type**: Extension of the shared host (`SlpModularCms.Core`) plus one new deployable client, an admin theming mechanism and CI/CD for a second deployment target. No rewrite; existing clients (`Api`, `Api.SlpSoftware`) must behave exactly as before.
|
||||
- **Primary changes**: (U1) `WebsiteMode.PrerenderedPages` with nginx-parity serving, `StrictSite` CSP policy, `Website:NoIndex`; (U2) client `SlpModularCms.Api.AndreaSlopFotografie`, admin theme via `VITE_THEME`/`VITE_DEFAULT_LANGUAGE`, optional first-admin setup token, CI/CD to the test Pi.
|
||||
- **Related components**: Core (`CmsHost`, `CmsHostOptions`, `StaticContentExtensions`, `CspPolicyCatalog`, security headers), Modules.Identity (setup token), frontend (theme tokens, build), `.gitea/workflows/*`, README / `WEBSITE_WORKSPACE.md`.
|
||||
|
||||
### Change Impact Assessment
|
||||
- **User-facing changes**: Yes - public website served by the host (visitor), themed Dutch admin (site owner).
|
||||
- **Structural changes**: Yes - new client project, new options/middleware in Core.
|
||||
- **Data model changes**: No new entities. New database instance per site (`AndreaSlopFotografieTest`); existing migrations apply. Setup token is configuration, not data.
|
||||
- **API changes**: Setup endpoint gains an optional token requirement (only when configured). No other API change.
|
||||
- **NFR impact**: Yes - Security Baseline (blocking), PBT partial, performance of per-request path resolution, proxy/HTTP 1.0 behaviour.
|
||||
|
||||
### Component Relationships
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
core["SlpModularCms.Core<br/>(CmsHost, StaticContent, CSP catalog)"]
|
||||
api["SlpModularCms.Api"]
|
||||
slp["SlpModularCms.Api.SlpSoftware"]
|
||||
andrea["SlpModularCms.Api.AndreaSlopFotografie<br/>(new client, U2)"]
|
||||
ident["Modules.Identity<br/>(setup token)"]
|
||||
avail["Modules.Availability"]
|
||||
fe["frontend<br/>(theme per site)"]
|
||||
ci["Gitea workflows<br/>(CI + deploy-scp)"]
|
||||
pi["Test Pi<br/>(port 5200)"]
|
||||
|
||||
core -->|"unchanged behaviour"| api
|
||||
core -->|"unchanged behaviour"| slp
|
||||
core -->|"PrerenderedPages + StrictSite (U1)"| andrea
|
||||
andrea --> ident
|
||||
andrea -.->|"only if required"| avail
|
||||
fe -->|"VITE_THEME=asf"| andrea
|
||||
ci -->|"build + deploy (test only)"| andrea
|
||||
andrea --> pi
|
||||
|
||||
classDef shared fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef existing fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef new fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
classDef ext fill:#d6bcfa,stroke:#553c9a,stroke-width:1px,color:#000;
|
||||
class core shared;
|
||||
class api,slp,ident,avail,fe existing;
|
||||
class andrea new;
|
||||
class ci,pi ext;
|
||||
```
|
||||
|
||||
Text alternative: Core serves all clients; the new Andrea client uses the new website mode and policy, references Identity (Availability only if needed), gets a themed admin build and is deployed by CI to the test Pi.
|
||||
|
||||
| Component | Change type | Reason | Priority |
|
||||
|---|---|---|---|
|
||||
| Core hosting | Major (additive) | New mode, middleware, policy | Critical |
|
||||
| Api, Api.SlpSoftware | None (regression-guarded) | Must stay unchanged | Critical |
|
||||
| Identity | Minor | Optional setup token | Important |
|
||||
| Frontend | Minor | Theme tokens, language default | Important |
|
||||
| CI/CD | Minor | Per-client admin build, second deploy target | Important |
|
||||
| Docs | Minor | README, WEBSITE_WORKSPACE.md | Important |
|
||||
|
||||
### Risk Assessment
|
||||
- **Risk level**: Medium. Shared host change touches every client (mitigated by default `SpaFallback` and regression tests); public-facing path handling (traversal / open redirect) is security-relevant; deployment on a Pi that is not yet provisioned.
|
||||
- **Rollback complexity**: Easy for code (feature flag by default off); moderate for the Pi (manual steps by Bryan, test only).
|
||||
- **Testing complexity**: Complex (PBT on pure functions, integration tests of the pipeline with a temp website root, theme visual/contrast check, deploy smoke test).
|
||||
|
||||
## Workflow Visualization
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["Brief from CMS & API"])
|
||||
|
||||
subgraph INCEPTION["INCEPTION PHASE"]
|
||||
WD["Workspace Detection<br/><b>COMPLETED</b>"]
|
||||
RE["Reverse Engineering<br/><b>SKIP (reuse)</b>"]
|
||||
RA["Requirements Analysis<br/><b>COMPLETED</b>"]
|
||||
US["User Stories<br/><b>SKIP</b>"]
|
||||
WP["Workflow Planning<br/><b>IN PROGRESS</b>"]
|
||||
AD["Application Design<br/><b>EXECUTE</b>"]
|
||||
UG["Units Generation<br/><b>EXECUTE (minimal)</b>"]
|
||||
end
|
||||
|
||||
subgraph CONSTRUCTION["CONSTRUCTION PHASE"]
|
||||
U1["Unit U1 core-site-hosting<br/>FD, NFR Req, NFR Design, Code, per-unit build/test"]
|
||||
H1["Hand-back U1 + wait for go"]
|
||||
U2["Unit U2 andreaslop-client<br/>NFR Req, NFR Design, Infra Design, Code, per-unit build/test"]
|
||||
H2["Hand-back U2"]
|
||||
BT["Build and Test (all units)<br/><b>EXECUTE</b>"]
|
||||
end
|
||||
|
||||
subgraph OPERATIONS["OPERATIONS PHASE"]
|
||||
DS["Deployment Setup<br/><b>EXECUTE</b>"]
|
||||
MS["Monitoring Setup<br/><b>EXECUTE</b>"]
|
||||
PRV["Production Readiness Validation<br/><b>EXECUTE</b>"]
|
||||
end
|
||||
|
||||
Start --> WD --> RE --> RA --> US --> WP --> AD --> UG --> U1 --> H1 --> U2 --> H2 --> BT --> DS --> MS --> PRV --> End(["Complete"])
|
||||
|
||||
style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style RA fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style WP fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
|
||||
style RE fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
|
||||
style US fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000
|
||||
style AD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||||
style UG fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||||
style U1 fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||||
style U2 fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||||
style H1 fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
|
||||
style H2 fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
|
||||
style DS fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||||
style MS fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||||
style PRV fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000
|
||||
style Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
|
||||
style End fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000
|
||||
linkStyle default stroke:#333,stroke-width:2px
|
||||
```
|
||||
|
||||
Text alternative: green = done/always, orange dashed = conditional EXECUTE, grey dashed = SKIP, purple = checkpoints with the requester.
|
||||
|
||||
## Phases to Execute
|
||||
|
||||
### INCEPTION
|
||||
- [x] Workspace Detection (COMPLETED)
|
||||
- [x] Reverse Engineering (SKIPPED - existing `_shared/reverse-engineering/` reused; key host files read directly)
|
||||
- [x] Requirements Analysis (COMPLETED, approved by Bryan)
|
||||
- [x] User Stories (SKIPPED per Q6)
|
||||
- [x] Workflow Planning (IN PROGRESS)
|
||||
- [ ] Application Design - EXECUTE
|
||||
- **Rationale**: New components (WebsiteMode option, path resolver, prerendered-site middleware, StrictSite policy, client project, theme mechanism, setup-token check). The requester expects Bryan's design approval.
|
||||
- [ ] Units Generation - EXECUTE (minimal; no separate Units Planning question round)
|
||||
- **Rationale**: The two units are fixed by the brief. Formalise them (scope, order, dependencies, hand-back gates) in `unit-of-work.md`.
|
||||
|
||||
### CONSTRUCTION (per unit; U2 only after the requester's "go")
|
||||
**U1 core-site-hosting**
|
||||
- [ ] Functional Design - EXECUTE: path-resolution rule table, canonical form, known-page set, 404 and reserved-prefix behaviour, noindex/robots rules.
|
||||
- [ ] NFR Requirements - EXECUTE: security (traversal, open redirect, header completeness), PBT properties (partial mode), performance of lookup, proxy/HTTP 1.0 compatibility.
|
||||
- [ ] NFR Design - EXECUTE (compact): caching of file existence / known-page refresh, middleware ordering, compression scope.
|
||||
- [ ] Infrastructure Design - SKIP: no infrastructure change in U1.
|
||||
- [ ] Code Generation - EXECUTE (plan + generation + automatic per-unit build/test, regression run of `Api`/`Api.SlpSoftware`)
|
||||
- [ ] Hand-back note U1, message to "CMS & API", **wait for go**
|
||||
|
||||
**U2 andreaslop-client**
|
||||
- [ ] Functional Design - SKIP: no new business domain; theme token mapping and client composition are covered by Application Design and requirements.
|
||||
- [ ] NFR Requirements - EXECUTE: setup-token security, secrets handling, contrast/accessibility of the theme, login rate limiting.
|
||||
- [ ] NFR Design - EXECUTE (compact): token check placement, constant-time compare, configuration shape.
|
||||
- [ ] Infrastructure Design - EXECUTE: Pi layout, systemd user unit, env variables, database `AndreaSlopFotografieTest` / user `AndreaSlopFotografie`, ufw rule for port 5200, proxy-Pi route, Gitea secrets, both `wwwroot/web` delivery variants, manual-step list for Bryan; then notify "CMS & API" so the Pi-Main session can draft commands.
|
||||
- [ ] Code Generation - EXECUTE (client, theme, setup token, workflows; per-unit build/test)
|
||||
- [ ] Test deploy - only with Bryan's go in this session, test host only
|
||||
- [ ] Hand-back note U2
|
||||
|
||||
- [ ] Build and Test - EXECUTE (full solution, frontend build per theme, cross-unit integration, smoke checks)
|
||||
|
||||
### OPERATIONS (Operations Configuration = Yes)
|
||||
- [ ] Deployment Setup - EXECUTE
|
||||
- [ ] Monitoring Setup - EXECUTE
|
||||
- [ ] Production Readiness Validation - EXECUTE (for the test environment; production out of scope)
|
||||
|
||||
## Package Change Sequence
|
||||
1. `SlpModularCms.Core` (+ `Core.Tests`) - U1
|
||||
2. `Api` / `Api.SlpSoftware` regression run - U1
|
||||
3. `SlpModularCms.Modules.Identity` (+ tests) - setup token (U2)
|
||||
4. `frontend` theme and build variables - U2
|
||||
5. `SlpModularCms.Api.AndreaSlopFotografie` (+ solution entry under Clients) - U2
|
||||
6. `.gitea/workflows` (CI matrix per client, deploy to test) - U2
|
||||
7. Docs (`README.md`, `WEBSITE_WORKSPACE.md`) - U1 and U2
|
||||
|
||||
## Success Criteria
|
||||
- **Primary goal**: Andrea's prerendered site and a themed Dutch admin served by one SlpModularCms process on the test Pi, with behaviour matching today's nginx and the exact CSP.
|
||||
- **Key deliverables**: WebsiteMode + StrictSite in Core; new client; theme; setup token; CI/CD; hand-back notes; Pi manual-step list.
|
||||
- **Quality gates**: Security Baseline compliance per stage; PBT-02/03/07/08/09 satisfied; `Api` and `Api.SlpSoftware` green and unchanged; per-unit build/test; requester's "go" before U2; Bryan's approval of requirements and design; no push without Bryan's request; no production changes.
|
||||
@@ -0,0 +1,9 @@
|
||||
# Unit of Work Plan - andreaslop-site-hosting
|
||||
|
||||
Decomposition is fixed by the brief and the approved execution plan (two units, U1 then U2, hand-back gate between them). No open decomposition questions: no ambiguity found in story grouping, dependencies, deployment or code organisation (brownfield; structure rules from CLAUDE.md/AGENTS.md apply).
|
||||
|
||||
- [x] Generate `inception/application-design/unit-of-work.md`
|
||||
- [x] Generate `inception/application-design/unit-of-work-dependency.md`
|
||||
- [x] Generate `inception/application-design/unit-of-work-story-map.md` (requirements-to-unit map; User Stories were skipped)
|
||||
- [x] Validate unit boundaries and dependencies
|
||||
- [x] Ensure every requirement is assigned to a unit
|
||||
+27
@@ -0,0 +1,27 @@
|
||||
# Pi inventory notes (input for Infrastructure Design, U2)
|
||||
|
||||
Source: relayed by session "CMS & API" from session "Pi-Main - Server" (read-only inventory, no sudo, facts not verified by this session). Full write-up in the website repo: `AndreaSlopFotografie-cms-api-foundation/aidlc-docs/features/cms-api-foundation/construction/cms-host/pi-inventory.md`. Status: UNVERIFIED INPUT, to be checked against `.gitea/workflows/deploy-scp.yaml` and confirmed by Bryan.
|
||||
|
||||
## Relayed decision (pending Bryan's confirmation in this session)
|
||||
- The test instance takes over hostname `test.andreaslop.nl`. Verify first on the Pi via the app port; Bryan then switches the route on the proxy Pi to the new port. nginx on the app Pi stays as fallback.
|
||||
|
||||
## Pattern to copy (SlpSoftware test)
|
||||
- User `gitea-workflow`; `~/apps/<name>/test/{releases,current,shared}`; `shared/env` (mode 600); `shared/wwwroot-web` symlink to `/mnt/storage1/www/html/...`.
|
||||
- systemd USER unit: `WorkingDirectory=current`, `ExecStart=dotnet ...dll`, `EnvironmentFile=shared/env`, `Restart=on-failure`, `KillSignal=SIGINT`.
|
||||
- Deploy: appleboy/drone-scp over SSH port 2224 as `gitea-workflow`; DB backup script before/after release.
|
||||
|
||||
## Network and resources
|
||||
- Free ports: 5200 (test), 5201 (production, later). ufw rule needed, allow only from proxy Pi 192.168.1.102. Taken: 5100/5101, 5150/5151, 5000, 3000, 3001, 3306, 80, 2224.
|
||||
- Proxy Pi (TLS, certbot) forwards DIRECTLY to the app port over HTTP/1.0, bypassing nginx on the app Pi. The host must therefore provide gzip, security headers, canonical 301s and a real 404 itself, and `UseHttpsRedirection` / forwarded headers must be handled as SlpSoftware does (open point 2 in requirements).
|
||||
- Pi 4, about 5.4 GiB free RAM; one more .NET process (~250-300 MB) fits. Uploads/photos on `/mnt/storage1`; releases on the SD card.
|
||||
- ARM64 builds must require runner label `arm64` or `linux-arm64` (the PC runner is x64).
|
||||
|
||||
## Database
|
||||
- MariaDB 10.11 on localhost. Convention: PascalCase DB named after the app, user = app name @localhost. Suggested by Pi-Main: `AndreaSlopTest` / `AndreaSlopCms`@localhost. SUPERSEDED by relayed naming decision: database `AndreaSlopFotografieTest`, user `AndreaSlopFotografie`@localhost (reason: the CMS is part of the website; the company is AndreaSlopFotografie). Confirmed by Bryan with approval of requirements. Existing DB `andreaslop` is WordPress: do not confuse. Bryan creates DB and user with sudo; the Pi-Main session adds the new DB to the backup script.
|
||||
|
||||
## Open design option (include both variants in Infrastructure Design)
|
||||
- Variant 1: the website CI delivers files into `wwwroot/web` directly.
|
||||
- Variant 2: `shared/wwwroot-web` symlinks to `/mnt/storage1/www/html/andreaslop-test`, the folder the existing static web deploy already writes to, so the current web deploy keeps working and the CMS host serves those files. Implication for design: the known-page set must refresh when files change in place (requirements open point 1).
|
||||
|
||||
## Manual steps for Bryan (to be finalised in the design)
|
||||
User unit, env file, database and user, ufw rule, proxy-Pi server block/route switch, Gitea secrets in the CMS repo, backup script entry. The Pi-Main session can draft exact commands once the list is final (ask via "CMS & API").
|
||||
+100
@@ -0,0 +1,100 @@
|
||||
# Requirement Verification Questions - andreaslop-site-hosting
|
||||
|
||||
Source brief: `aidlc-docs/_shared/handoffs/cms-api-foundation-brief-u1-u2.md` (decisions 1-7 in section 2 are taken and NOT re-asked).
|
||||
Please fill in your choice after each `[Answer]:` tag.
|
||||
|
||||
## Question 1: First-administrator setup flow hardening (Security)
|
||||
The brief asks us to assess whether the first-admin setup flow on the new instance can be abused by a third party before the first administrator exists (a freshly deployed test host is publicly reachable). What should the scope be?
|
||||
|
||||
- A) Assess and test the existing Identity behaviour only (no code change in Identity); document the residual risk (anyone who reaches /admin first can claim the admin account)
|
||||
- B) Assess, and additionally require a one-time setup token from configuration (env var / appsettings.local.json) on the setup endpoint, only when configured - existing hosts unchanged
|
||||
- C) Assess, and restrict the setup endpoint in the new client through configuration only (e.g. host/IP allow-list), no Identity change
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: B
|
||||
(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session)
|
||||
|
||||
## Question 2: Commit / PR flow for the two units
|
||||
How do we deliver U1 and U2 in git? (Per standing rule: I commit, but never push unless you say so.)
|
||||
|
||||
- A) One feature branch, commits per unit; no push until you ask; one PR for the whole feature after U2
|
||||
- B) One feature branch, but a PR for U1 alone after hand-back (U1 is behaviour-neutral for existing hosts), then U2 on a follow-up branch
|
||||
- C) One feature branch, commits per unit; I push and open the PR only when you explicitly say so, timing decided by you per unit
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A
|
||||
(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session)
|
||||
|
||||
## Question 3: Deployment to the test host
|
||||
May the CI/CD pipeline deploy the new client to the test host, and how is it triggered?
|
||||
|
||||
- A) Manual trigger only (workflow_dispatch); I may not run it, you trigger it
|
||||
- B) Automatic on merge to master (like the existing pipeline), plus manual trigger
|
||||
- C) I only write and verify the workflow (lint/dry run); no deploy to test is performed in this feature, you do the first deploy
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: X) Pipeline MAY deploy the new client to the TEST host (never production); the CMS session may start the test deploy itself once pipeline and Pi are ready. Bryan: "Hij mag hem uitrollen naar test. Graag zelfs dan kan het zsm getest worden, maar de CI/CD moet er nog op worden ingericht en de host ook."
|
||||
(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session)
|
||||
|
||||
## Question 4: Test-host prerequisites
|
||||
Do the test host and Gitea secrets for Andrea's instance already exist?
|
||||
|
||||
- A) Yes - host, path, SSH user and Gitea secrets exist; I only need the names (you will tell me, or I read them from the existing workflow)
|
||||
- B) Partly - the host exists but secrets/paths for the Andrea instance still have to be defined; I list what is needed in the infrastructure design
|
||||
- C) No - nothing exists yet; the design must also cover creating them (documented as manual steps for you)
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: X) Partly exists (matches B). Bryan: "De host heeft al de juiste accounts om het op te kunnen zetten, maar de inrichting op de host moet nog worden ingeregeld zoals paden, secrets, environment variables." Infrastructure design must list the remaining Pi setup (paths, secrets, env vars, database, reverse proxy) as manual steps for Bryan.
|
||||
(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session)
|
||||
|
||||
## Question 5: Admin theme scope in U2
|
||||
How far should the theme override go beyond colours, radius and font?
|
||||
|
||||
- A) Tokens only (colours, radius, font) plus logo and favicon, as in the brief; no layout or component changes
|
||||
- B) Tokens plus login/setup page branding (logo, title text) via theme assets; no layout changes
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A
|
||||
(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session)
|
||||
|
||||
## Question 6: User Stories stage
|
||||
Is a User Stories stage wanted for this infrastructure-heavy feature (personas would be: site visitor, site owner/admin, operator/developer)?
|
||||
|
||||
- A) Skip User Stories (requirements with acceptance criteria are enough)
|
||||
- B) Run a short, minimal User Stories stage
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A
|
||||
(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session)
|
||||
|
||||
## Vraag 7: Beveiligingsextensies
|
||||
Moeten de beveiligingsregels (Security Baseline) als harde vereisten worden afgedwongen voor deze feature? (De brief meldt dat je dit al hebt ingeschakeld; graag bevestigen.)
|
||||
|
||||
- A) Ja - dwing alle BEVEILIGINGSREGELS af als blokkerende vereisten
|
||||
- B) Nee - sla alle BEVEILIGINGSREGELS over
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session)
|
||||
|
||||
## Vraag 8: Property-based testing
|
||||
Moet property-based testing worden afgedwongen? (De brief meldt: gedeeltelijke modus, regels PBT-02, 03, 07, 08, 09; graag bevestigen.)
|
||||
|
||||
- A) Ja, gedeeltelijk - alleen PBT-02, 03, 07, 08, 09 (puur functies: padresolutie, canonieke vorm, beleid round-trip)
|
||||
- B) Ja, volledig - alle PBT-regels als blokkerend
|
||||
- C) Nee - sla property-based testing over
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session)
|
||||
|
||||
## Vraag 9: Operations-fase
|
||||
Moet deze feature na Construction door de Operations-fase (deployment- en monitoringsetup, production readiness)? Let op: de CI/CD-wijzigingen voor U2 zitten sowieso in de requirements; dit gaat om de aparte Operations-fase.
|
||||
|
||||
- A) Ja - voer de Operations-fase uit na Construction (deployment + monitoring setup)
|
||||
- B) Nee - stop na Build and Test (CI/CD voor de testhost wordt wel gebouwd in U2 Code Generation)
|
||||
- C) Nog niet zeker - vraag het me opnieuw na de Construction-fase
|
||||
- X) Anders (beschrijf hieronder na de [Answer]:-tag)
|
||||
|
||||
[Answer]: A
|
||||
(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session)
|
||||
@@ -0,0 +1,71 @@
|
||||
# Requirements - andreaslop-site-hosting
|
||||
|
||||
## 1. Intent analysis
|
||||
- **User request**: Serve Andrea's prerendered website (`AndreaSlopFotografie`, TanStack Start output) from SlpModularCms with nginx-parity behaviour, a strict CSP, and a Dutch themed admin; deploy to the **test** host. Brief: `aidlc-docs/_shared/handoffs/cms-api-foundation-brief-u1-u2.md`. Requester session: "CMS & API"; approver: Bryan.
|
||||
- **Request type**: New feature / enhancement of the shared host + new client.
|
||||
- **Scope**: Multiple components (Core hosting, Security headers, new Client project, Frontend build/theme, CI/CD).
|
||||
- **Complexity**: Complex. **Depth**: Comprehensive.
|
||||
- **Units**: U1 `core-site-hosting` (shared host, no behaviour change for existing clients), U2 `andreaslop-client`. Hand-back after each unit; **U2 starts only after the requester's "go"**.
|
||||
- **Fixed decisions**: brief section 2 (D1-D7) and Q1-Q9 in `requirement-verification-questions.md` (answers relayed by the peer session; Bryan confirms at the approval gate).
|
||||
|
||||
## 2. Unit U1 - core-site-hosting (shared host)
|
||||
|
||||
### Functional
|
||||
- **FR-U1-01 WebsiteMode.** `CmsHostOptions.WebsiteMode` enum: `SpaFallback` (default, exactly today's behaviour) and `PrerenderedPages`. `Api` and `Api.SlpSoftware` untouched; their tests unchanged.
|
||||
- **FR-U1-02 Path resolution (pure).** A total function (never throws, never leaves the website root, rejects traversal incl. encoded/backslash/NUL/over-long paths) from (request path, file-exists predicate) to `ServeFile | Redirect(301, target) | NotFound`. Rules (nginx parity, BR-HST-01..11 in the website repo):
|
||||
- `/` serves `index.html`; `/x` serves `x.html` (and `x/index.html` if present).
|
||||
- **Canonical form applies to known pages only.** nginx uses a hard-coded page list; the host derives the known-page set from the `*.html` files present in the website root. A case-insensitive variant (`/Over-Mij`, `/over-mij.html`, `/over-mij/`, `/index`, `/index.html`) gets one 301 to the lowercase, no-`.html` form; `/index*` redirects to `/`. Query string preserved. Redirect targets always come from the known-page set, never from the raw request.
|
||||
- Trailing slashes on any other path are stripped with a 301 (not for `/`). A target starting `//` or `/\` or containing control characters is treated as unknown (open-redirect guard, BR-HST-06). A path with a leading backslash is 404.
|
||||
- Hashed asset names are never lower-cased or redirected. Paths that look like files (have an extension) are served as files or 404, never fall back to a page.
|
||||
- `/404` and `/404.html` requested directly answer 404 (no redirect).
|
||||
- **FR-U1-03 Unknown path.** Serve `404.html` with status **404** (never `index.html`); plain 404 if `404.html` is missing. A directory without a page file is 404; no directory listing.
|
||||
- **FR-U1-04 Reserved prefixes.** `/admin`, `/api/v1`, `/health` are never handled by this middleware. An unknown API path remains an API 404 (today's website SPA fallback answers unknown `/api/v1` paths with `index.html`; this mode must not).
|
||||
- **FR-U1-05 Cache-Control.** Pages and other root files: `no-cache`. Files under `/assets/`: `public, max-age=31536000, immutable`.
|
||||
- **FR-U1-06 Compression.** Built-in response compression (no new dependency) for the text types in `compressibleTypes.ts` (html, js, css, svg, json, xml, txt); not for already-compressed types; `Vary: Accept-Encoding`. Website mount only (see open point 5).
|
||||
- **FR-U1-07 Indexing policy.** Setting `Website:NoIndex` (default false), bound to a validated options class. When true: `X-Robots-Tag: noindex, nofollow` on all website responses (pages, assets, 404, redirects) and `/robots.txt` answers 200 with `User-agent: *` / `Disallow: /`.
|
||||
- **FR-U1-08 StrictSite policy.** New policy name `StrictSite` in `CspPolicyCatalog` (in `KnownPolicies`, accepted by `PathPolicyRule` validation; unknown names still fail startup; `Strict` and `Relaxed` unchanged). Directives in the exact order of the site's current policy so the string matches byte for byte:
|
||||
`default-src 'self'; script-src 'self' <script origins>; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self' <connect origins>; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'`
|
||||
plus `X-Frame-Options: DENY` and `Referrer-Policy: strict-origin-when-cross-origin`. Origins come from the existing security-header configuration. An exact match is achievable (order is catalog-internal); `Strict` need not change.
|
||||
- **FR-U1-09 Other headers.** Verify and test that website responses carry `Strict-Transport-Security: max-age=31536000; includeSubDomains`, `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin` and the CSP, including on 301, 404, assets and robots.txt.
|
||||
- **FR-U1-10 Pipeline order.** Security headers before static content; compression before the website mount; website 404 handling last, after API routes; documented in `CmsHost`.
|
||||
- **FR-U1-11 Docs.** Update `WEBSITE_WORKSPACE.md` and `README.md` for the new mode and settings.
|
||||
|
||||
### Acceptance (U1)
|
||||
- Unit tests and property-based tests (partial PBT, section 5): path resolution never escapes the root, canonicalisation is idempotent, reserved prefixes never resolve, policy round trip.
|
||||
- `Api` and `Api.SlpSoftware` suites green, behaviour unchanged (regression run recorded).
|
||||
- Hand-back note (brief section 7) written and sent to "CMS & API".
|
||||
- Proxy awareness: the test site sits behind a reverse-proxy Pi that terminates TLS. Existing `UseHttpsRedirection` / forwarded-header handling must not cause redirect loops or absolute `http://` redirects; website redirects are relative (nginx `absolute_redirect off` parity). Verified in design.
|
||||
|
||||
## 3. Unit U2 - andreaslop-client
|
||||
|
||||
- **FR-U2-01 Client project** `SlpModularCms.Api.AndreaSlopFotografie` under **Clients** in the solution: thin `Program.cs` on `CmsHost`, `WebsiteMode = PrerenderedPages`, three-file appsettings (`appsettings.json`, `appsettings.{Env}.json`, uncommitted `appsettings.local.json`), own database, own dev port, `SecurityHeaders:DefaultPolicy = StrictSite` with the Umami (`https://analytics.slpsoftware.nl`) and Sentry (`https://o4511795618185216.ingest.de.sentry.io`) origins, `Website:NoIndex = true` for test.
|
||||
- **FR-U2-02 Module set** = module projects the client references (no config filter). Determine and report the minimum (Identity; is Availability required?). `Offerings` not referenced; `/api/v1/System/capabilities` must not list it.
|
||||
- **FR-U2-03 Admin theme.** `frontend/themes/asf/` with CSS overriding the existing design tokens (colours, radius, font), plus logo and favicon. `VITE_THEME` selects it at build time (unset = today's look). New `VITE_DEFAULT_LANGUAGE` (`nl` for Andrea; English stays selectable). Palette: paper `#faf7f2` / `#f1ebe2` / `#e8e0d5`, ink `#232120` / `#55504b` / `#8a827a`, line `#e2dad0`, accent `#7f8b76`, accent-deep `#5f6a58` (text/buttons), accent-deeper `#475042`, sand `#d9cdbc`, error `#a4443a`. Fonts Marcellus (headings) and Jost (body) with the site's fallbacks, **self-hosted** (the admin's CSP is `font-src 'self'`). Scope per Q5: tokens + logo + favicon only, no layout or component changes. Contrast stays accessible (destructive and focus-ring colours readable on paper).
|
||||
- **FR-U2-04 CI/CD.** Build the admin per deployable client with its `VITE_THEME`, `VITE_DEFAULT_LANGUAGE`, `VITE_APP_TITLE`; publish the new host; deploy to the **test** host with the existing atomic release switch; `wwwroot/web/` stays outside the swapped release directory so the site survives every CMS deploy. The production path for `Api.SlpSoftware` is not touched.
|
||||
- **FR-U2-05 Test deploy** (Q3, relayed): the pipeline may deploy to the test host, and this session may start the test deploy itself once pipeline and Pi are ready - **test only, never production**. Bryan's go is confirmed in this session before the first deploy.
|
||||
- **FR-U2-06 Host provisioning** (Q4): the Raspberry Pi accounts exist, but paths, secrets, environment variables, database, service unit and reverse proxy are not set up yet. The infrastructure design lists every remaining step as a manual checklist for Bryan. Pi inventory comes via "CMS & API" from "Pi-Main - Server"; this session does not contact that session directly.
|
||||
- **FR-U2-07 First-admin setup token** (Q1=B): assess the existing setup flow (who can call it while no admin exists) and add an optional one-time setup token read from configuration. When configured, the setup endpoint requires it; when not configured, behaviour is unchanged for existing hosts. Constant-time comparison, never logged, covered by the same rate limiting as login. Tests: no token configured, wrong token, correct token, setup after the first admin exists (rejected). The token is a secret supplied outside the repo.
|
||||
- **FR-U2-08 Auth** otherwise unchanged (Identity module; invitations after the first admin). Login rate limiting stays.
|
||||
|
||||
### Acceptance (U2)
|
||||
Host starts on test with its own database; `/admin` shows Andrea's theme in Dutch; first-admin setup and login work; `/api/v1/System/capabilities` has no `Offerings`; `/health` is green; `Api.SlpSoftware` still builds and deploys unchanged; hand-back note written.
|
||||
|
||||
## 4. Out of scope
|
||||
Production deployment, the `Master` module for Andrea, extra roles, SSR, CMS-driven site content, a configuration-based module filter, changes to the website repo, theme editing in the admin, serving the theme from the API.
|
||||
|
||||
## 5. Cross-cutting
|
||||
- **Security Baseline**: enforced (blocking): path input validation, secure headers, no secrets in the repo, rate limiting, safe error handling, no sensitive data in logs, no new packages planned.
|
||||
- **Property-based testing**: partial mode, rules PBT-02, 03, 07, 08, 09 (pure functions: path resolution, canonical idempotence, policy round trip). Seeds are logged on failure and reproducible; tooling follows the existing test framework (decided in NFR/Code Generation).
|
||||
- **Per-unit build/test**: build and run tests after each unit's code generation.
|
||||
- **Git**: branch `feature/andreaslop-site-hosting`, commits per unit, no push until Bryan asks, one PR after U2 (Q2=A).
|
||||
- **Operations phase**: yes (Q9=A): deployment and monitoring setup and production readiness, assessed for the test environment. Production itself stays out of scope.
|
||||
- **User Stories**: skipped (Q6).
|
||||
- **Language**: documentation English, conversation Dutch.
|
||||
- **Boundaries**: website repo is read-only; no production changes; Pi contact only through "CMS & API".
|
||||
|
||||
## 6. Open points to resolve in design
|
||||
1. Where the known-page set is built (scan at startup vs. per-request lookup) and how it refreshes when a new site build is deployed.
|
||||
2. Interaction of `UseHttpsRedirection` / forwarded headers with the reverse-proxy Pi.
|
||||
3. Whether `Availability` is required next to `Identity` for the admin.
|
||||
4. Where the setup-token check lives (Identity module vs. host) without changing existing hosts.
|
||||
5. Whether compression is limited to the website mount (proposal: yes, avoids BREACH-style exposure on authenticated API responses).
|
||||
+27
@@ -0,0 +1,27 @@
|
||||
# Deployment Instructions - ASF test host
|
||||
|
||||
The pipeline definition already exists in `.gitea/workflows/continuous_integration.yaml` (jobs `config-asf`, `publish-asf-test`, `deploy-asf-test`, reusing `deploy-scp.yaml`); this runbook sequences the one-time Pi work, the first deploy and every later deploy. The exact one-time steps (1-18) are in `construction/andreaslop-client/infrastructure-design/manual-steps-for-bryan.md`; the Pi-Main session drafts the commands from that list.
|
||||
|
||||
## 0. Before anything is pushed
|
||||
1. The vulnerability gate is clean (done: Xml 10.0.14, zod, react-router). Run `dotnet test SlpModularCms.sln` where MariaDB exists, or let CI do it.
|
||||
2. Decide when to push or merge (done by Bryan; the assistant never pushes unasked). A merge to master with `ASF_TEST_DEPLOY_ENABLED` unset changes nothing for ASF, but does deploy the shared Core change (patched packages, per-client limiters, opt-in forwarded headers) to SlpSoftware test on that push. Watch that first SlpSoftware deploy.
|
||||
|
||||
## 1. One-time preparation (manual-steps phase A, nothing live yet)
|
||||
Verify prerequisites, create database/user, directories + symlink `shared/wwwroot-web`, `shared/env`, user unit (enabled, not started), ufw 5200 from 192.168.1.102, DB backup entry, Gitea variables (`DEPLOY_PATH_ASF_TEST`, `SERVICE_NAME_ASF_TEST`, `HEALTH_CHECK_URL_ASF_TEST`, `VITE_SENTRY_DSN_ASF`). Leave `ASF_TEST_DEPLOY_ENABLED` unset.
|
||||
|
||||
## 2. Cut over (phase B, accepted short test downtime)
|
||||
Save the current proxy block; verify the three forwarded headers are present; change only `proxy_pass` to `http://192.168.1.103:5200`; test config; reload. Set `ASF_TEST_DEPLOY_ENABLED=true`; push to master or run the workflow manually with "Deploy ASF test".
|
||||
|
||||
## 2b. Consequences of the switch being `true` (verified on Gitea, run 606/607)
|
||||
- `vars.ASF_TEST_DEPLOY_ENABLED == 'true'` in a job-level `if:` works on this Gitea (`config-asf` ran with the variable set).
|
||||
- With the variable `true`, **a push or merge to master now deploys ASF test** (besides SlpSoftware test).
|
||||
- The first ASF deploy does **not** need a merge: run "Continuous Integration" manually on the branch `feature/andreaslop-site-hosting` with only "Deploy ASF test" ticked (`deploy-asf-test` accepts any ref on dispatch). A dispatch with all boxes unticked builds and tests only (runs 606/607) and deploys nothing.
|
||||
|
||||
## 3. What a deploy does (every time)
|
||||
Build admin (`VITE_THEME=asf`, Dutch default) -> publish linux-arm64 -> upload to `releases/<timestamp>` -> link `wwwroot/web` to `shared/wwwroot-web` -> atomic switch of `current` -> `systemctl --user restart` -> `/health` on the public URL (10 tries) -> prune to current + previous.
|
||||
|
||||
## 4. Verify after the first deploy (phase C)
|
||||
`curl -I https://test.andreaslop.nl/` (CSP, HSTS, noindex), an inner page, `/Over-Mij` -> one 301, unknown path -> 404 page, `/robots.txt`, `/health`, `/api/v1/System/capabilities` (no Offerings), admin in Dutch with ASF theme, create the first administrator with the setup token, then remove `Identity__Setup__Token` from `shared/env` and restart the unit. Report forwarded-header observation and optional timing.
|
||||
|
||||
## 5. Later deploys
|
||||
Push to master (or manual run). The website itself is delivered by its own repository into `/mnt/storage1/www/html/andreaslop-test`; no host restart is needed.
|
||||
@@ -0,0 +1,8 @@
|
||||
# Deployment Plan - andreaslop-site-hosting (test only)
|
||||
|
||||
- **Method**: CI/CD pipeline (Gitea Actions) to an on-premises Pi, as decided in U2 Infrastructure Design (answers: all A).
|
||||
- **Environment**: test only, `https://test.andreaslop.nl`. Production for Andrea Slop Fotografie is a separate later decision (`Website__NoIndex=false`, own database, port 5201, own route) and not part of this feature.
|
||||
- **Why this shape**: it reuses the proven SlpSoftware path (`deploy-scp.yaml`: timestamped release, atomic `current` switch, restart, public `/health` check, prune to two releases) without touching it. ASF has its own jobs behind one switch, `ASF_TEST_DEPLOY_ENABLED`.
|
||||
- **Triggers**: push to master, or manual run with "Deploy ASF test" ticked; both only when the switch variable is `true`.
|
||||
- **Secrets**: Gitea secrets `PI_MAIN_*` (existing) and the Pi file `shared/env` (mode 600). Nothing secret is committed. No approval gate for test.
|
||||
- **Sources of truth**: `construction/andreaslop-client/infrastructure-design/{infrastructure-design,deployment-architecture,manual-steps-for-bryan}.md`.
|
||||
@@ -0,0 +1,10 @@
|
||||
# Rollback Plan - ASF test host
|
||||
|
||||
| What went wrong | Rollback |
|
||||
|---|---|
|
||||
| Bad release (health check red or wrong behaviour) | On the Pi: `ln -sfn releases/<previous> current && systemctl --user restart andreaslopfotografie-test`. The previous release is always kept (prune keeps current + 1). |
|
||||
| Proxy route broke the test site | Restore the saved nginx server block on the proxy Pi (manual step 10), test config, reload; the old nginx fallback on the app Pi serves the site again. |
|
||||
| Pipeline misbehaves | Set `ASF_TEST_DEPLOY_ENABLED` to anything but `true`: all ASF jobs are skipped, SlpSoftware is unaffected. |
|
||||
| Shared Core change misbehaves on another host | Redeploy the previous release of that host the same way. The new behaviour is opt-in (forwarded headers) or equivalent to before (limiter buckets share the proxy address when no proxy is configured). |
|
||||
| Database | Migrations run automatically at start and are forward-only. The test database is backed up by the Pi DB backup (step 7); restore from that backup if a migration must be undone. |
|
||||
| Setup token leaked | Replace `Identity__Setup__Token` in `shared/env` and restart, or remove it once the first administrator exists. |
|
||||
@@ -0,0 +1,7 @@
|
||||
# Monitoring Plan - andreaslop-site-hosting (test)
|
||||
|
||||
- **Approach** (Q2 = D): logging plus alerting on tooling that already exists; no new dashboards (Q5 = A), no central log aggregator (Q3 = A).
|
||||
- **Tooling reused**: systemd/journald on the Pi (host logs), the Andrea Slop Fotografie **website's** existing Sentry project (Q3 = B in U2; NOT SlpSoftware's admin project), the host's `/health` endpoint (already checked by every deploy), the admin's same-origin `/sentry-tunnel`.
|
||||
- **Covered**: host errors and security events (Sentry), 301/404 website lines (journald), browser errors from the admin (via the tunnel), liveness (`/health` after each deploy and optionally an uptime monitor).
|
||||
- **Not covered / known gaps**: no performance dashboard or latency alerting; the website's own browser errors are reported by the website itself; Sentry events from website, host and admin share one project, separated by the `environment` tag (`test`) and URL; test only, production monitoring comes with a future production setup.
|
||||
- **Verification**: after the first deploy, trigger one wrong setup token and one 404 and confirm they show up (see `monitoring-setup.md`, section 4).
|
||||
@@ -0,0 +1,31 @@
|
||||
# Monitoring Setup - ASF test host
|
||||
|
||||
## 1. Logging
|
||||
- **Where**: stdout of the systemd user unit `andreaslopfotografie-test`, read with `journalctl --user -u andreaslopfotografie-test -f` (as `gitea-workflow`).
|
||||
- **Levels** (from `shared/env`): `Logging__LogLevel__SlpModularCms.Website=Information` on test (one line per website 301 and 404; `Warning` on production later); everything else keeps the committed defaults; `Microsoft.EntityFrameworkCore.Database.Command` stays at `Warning` so SQL parameters (e-mail addresses) are not logged.
|
||||
- **Never logged**: the setup token, passwords, tokens, full e-mail addresses. Website log lines are sanitised paths.
|
||||
- **Sample lines**: `Website redirect 301 /Over-Mij -> /over-mij`; `Security event setup_token_rejected: setup token rejected on /api/v1/Setup/owner`.
|
||||
- **Sentry**: `Observability__SentryDsn` (website project DSN) and `Observability__Environment=test` in `shared/env`; the admin build gets the same DSN through `VITE_SENTRY_DSN_ASF` and reports through `/sentry-tunnel`.
|
||||
|
||||
## 2. Alerting (Q4 = A), in the website's Sentry project, notification by e-mail to the project owner
|
||||
Create these rules once, filtered on `environment:test` (the assistant did NOT create them; they change a shared Sentry project, so Bryan or the website session adds them, or asks for the `sentry:sentry-create-alert` skill to do it):
|
||||
|
||||
| Rule | Condition | Why |
|
||||
|---|---|---|
|
||||
| Setup token rejected | tag `security_event:setup_token_rejected`, 1+ events in 5 min | someone guesses the first-admin token |
|
||||
| Failed logins | tag `security_event:failed_login`, 10+ in 5 min | brute force on the admin |
|
||||
| Rate limit | tag `security_event:rate_limit_triggered`, 1+ in 5 min | limiter hit; with forwarded headers this is per visitor |
|
||||
| Migration failure | tag `security_event:migration_failure`, 1 event | host cannot start; also /health goes silent |
|
||||
| Unhandled errors | new issue in `environment:test`, level error or higher | host or admin bug |
|
||||
| Uptime | monitor `https://test.andreaslop.nl/health` every 5 min if Sentry uptime is available (otherwise any external pinger) | the deploy only checks once |
|
||||
|
||||
Each alert event carries the tag via `SecurityEventProcessor`, so the rules survive message wording changes. The first `rate_limit_triggered` events also confirm whether forwarded headers work: the limiter should count real visitors, not 192.168.1.102.
|
||||
|
||||
## 3. Dashboards (Q5 = A)
|
||||
None added. Use Sentry Issues filtered on `environment:test`, and on the Pi `journalctl`, `systemctl --user status andreaslopfotografie-test`, `ls -l current`.
|
||||
|
||||
## 4. Verification after the first deploy
|
||||
1. Open `/doesnotexist` -> journald shows a 404 line.
|
||||
2. POST a wrong `X-Setup-Token` to `/api/v1/Setup/owner` (before the first administrator exists) -> 401 and a `setup_token_rejected` event in Sentry with tag `security_event`.
|
||||
3. Stop the unit briefly -> uptime alert (if configured) and the deploy health check would fail.
|
||||
4. Check that no event contains the token or a full e-mail address.
|
||||
@@ -0,0 +1,43 @@
|
||||
# Deployment Setup Plan - andreaslop-site-hosting
|
||||
|
||||
Context: most deployment decisions were already made in U2 Infrastructure Design (CI/CD via Gitea Actions to the test Pi, atomic release switch, rollback by symlink, secrets in `shared/env`, switch variable `ASF_TEST_DEPLOY_ENABLED`). The recommended answers below simply confirm that, so Operations produces one consolidated runbook instead of re-deciding it. Test environment only.
|
||||
|
||||
## Question 1: Include Deployment Setup?
|
||||
Do you want a consolidated deployment runbook and checks for this feature as part of this workflow?
|
||||
|
||||
- A) Yes - consolidate the existing pipeline, the Pi steps and the rollback into one runbook (recommended)
|
||||
- B) No - deployment is handled elsewhere (the infrastructure design and manual steps already cover it)
|
||||
- C) Not sure - suggest an approach and I decide
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (Bryan: "alles A")
|
||||
|
||||
## Question 2: Deployment Method
|
||||
- A) CI/CD pipeline (Gitea Actions, the jobs added in U2) (recommended)
|
||||
- B) Cloud platform
|
||||
- C) On-premises / self-hosted server deployment (done via the pipeline above)
|
||||
- D) Manual deployment
|
||||
- E) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (Bryan: "alles A")
|
||||
|
||||
## Question 3: Environments
|
||||
- A) Test only (`test.andreaslop.nl`); production is a separate later decision (recommended)
|
||||
- B) Test and production
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (Bryan: "alles A")
|
||||
|
||||
## Question 4: Rollback Strategy
|
||||
- A) Keep the documented approach: previous release stays on disk, `ln -sfn` + restart; route rollback by restoring the saved proxy block; CI off via the switch variable (recommended)
|
||||
- B) Add an automated rollback job to the pipeline
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (Bryan: "alles A")
|
||||
|
||||
## Question 5: Secrets and approval gates
|
||||
- A) Keep: secrets only in Gitea secrets and the Pi `shared/env` (mode 600), no approval gate for test (recommended)
|
||||
- B) Add a manual approval step before the test deploy
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (Bryan: "alles A")
|
||||
@@ -0,0 +1,43 @@
|
||||
# Monitoring Setup Plan - andreaslop-site-hosting
|
||||
|
||||
Context: the CMS already ships structured logging (journald on the Pi), Sentry with alertable security events (`security_event` tag, including the new `setup_token_rejected`), a same-origin `/sentry-tunnel` for the admin, and `/health` (checked by the deploy). The decision (Q3 = B) is to reuse the Andrea Slop Fotografie website's existing Sentry project. Test environment only. Recommended answers are marked.
|
||||
|
||||
## Question 1: Include Monitoring Setup?
|
||||
- A) Yes - document what is observed and add alert recommendations on the existing tooling (recommended)
|
||||
- B) No - reuse the existing setup as is
|
||||
- C) Not sure - suggest an approach
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (Bryan via CMS & API, one by one: all recommended; Q2 = D)
|
||||
|
||||
## Question 2: Monitoring Approach
|
||||
- A) Logging only
|
||||
- B) Alerting only
|
||||
- C) Dashboards only
|
||||
- D) Combination: logging + alerting on existing tooling, no new dashboards (recommended)
|
||||
- E) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (Bryan via CMS & API, one by one: all recommended; Q2 = D)
|
||||
|
||||
## Question 3: Logging
|
||||
- A) Keep journald on the Pi plus Sentry; `Information` for `SlpModularCms.Website` on test (301/404 lines), `Warning` elsewhere; token never logged (recommended)
|
||||
- B) Add a central log aggregator
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (Bryan via CMS & API, one by one: all recommended; Q2 = D)
|
||||
|
||||
## Question 4: Alerting
|
||||
Which alerts, in the website's Sentry project, notified by email to the project owner?
|
||||
- A) Security events (`setup_token_rejected`, `failed_login`, `rate_limit_triggered`) and any `migration_failure`/unhandled error; plus the website's uptime check on `/health` if Sentry uptime is available (recommended)
|
||||
- B) Only `migration_failure` and unhandled errors
|
||||
- C) No alerts yet
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (Bryan via CMS & API, one by one: all recommended; Q2 = D)
|
||||
|
||||
## Question 5: Dashboards and existing infrastructure
|
||||
- A) No new dashboard; use Sentry issues filtered by environment `test` and the existing Pi tooling (recommended)
|
||||
- B) Add a dedicated dashboard
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (Bryan via CMS & API, one by one: all recommended; Q2 = D)
|
||||
+49
@@ -0,0 +1,49 @@
|
||||
# Production Readiness Checklist - andreaslop-site-hosting
|
||||
|
||||
Scope: the TEST environment `test.andreaslop.nl`. Production is out of scope; its open items are only listed at the end.
|
||||
|
||||
## Deployment
|
||||
- **Status**: Configured
|
||||
- **Method**: CI/CD (Gitea Actions) to the on-premises Pi, test only; switch `ASF_TEST_DEPLOY_ENABLED`
|
||||
- **Rollback Plan**: Yes (`operations/deployment/rollback-plan.md`: previous release kept, symlink + restart; saved proxy block; CI switch off). Not yet exercised on the Pi.
|
||||
|
||||
## Monitoring
|
||||
- **Status**: Configured (documented; alert rules not yet created)
|
||||
- **Approach**: Combination: journald + Sentry (website project, environment `test`) with alert rules and an uptime check; no new dashboards
|
||||
|
||||
## Additional Readiness Items
|
||||
- **Backups**: Database `AndreaSlopFotografieTest` must be in the Pi DB backup script (manual step 7, Pi-Main). Status to be confirmed by Pi-Main. The website files live on `/mnt/storage1` and are rebuilt from the website repo. Data Protection keys live in the database.
|
||||
- **Secrets Management**: Pass. Only in Gitea secrets (`PI_MAIN_*`) and the Pi file `shared/env` (mode 600); `Identity__Setup__Token` is removed after the first administrator exists; nothing secret is committed.
|
||||
- **Runbook/Support Handover**: Yes. `deployment-instructions.md`, `rollback-plan.md`, `manual-steps-for-bryan.md`, `monitoring-setup.md` are enough for someone other than the author.
|
||||
- **Alert Ownership**: Bryan receives Sentry e-mail alerts as project owner; fixing is owned by Bryan with the CMS & API and Pi-Main sessions. Rules are created after the first successful deploy.
|
||||
|
||||
## .NET Appsettings Compliance
|
||||
- **Three-file pattern present**: Yes for `Api.AndreaSlopFotografie` (`appsettings.json`, `appsettings.Development.json`, git-ignored optional `appsettings.local.json`, created locally with a placeholder only).
|
||||
- **No committed secrets**: Pass. `appsettings.json` holds placeholders (`<db-password>`, `<secure-long-random-secret-key-from-env>`), empty token, empty DSN. `appsettings.Development.json` holds the same development-only JWT secret the other clients use and a placeholder database password.
|
||||
- **`appsettings.local.json` gitignored**: Yes (`.gitignore` line `appsettings.local.json`).
|
||||
- **Production secrets wired to env vars/secrets manager**: Yes for the test host: `ConnectionStrings__DefaultConnection`, `JwtSettings__Secret`, `Identity__Setup__Token`, `Observability__SentryDsn` via `shared/env`. (Production uses the same mechanism later.)
|
||||
|
||||
## Overall Readiness
|
||||
- **Ready for Production**: Not applicable to production. For TEST: Yes with caveats (below).
|
||||
- **Open Follow-ups**:
|
||||
1. CI proof: DONE. Run 607 (branch, head e37b8f3, dispatch, no deploy) is fully green incl. backend-test with MariaDB (`Api.Tests`, ASF `HostPipelineTests`), frontend and vulnerability scan. Run 606 had one cold-start timing failure in the first `SetupPage` test (flake, same commit passed in 607). Optional: harden that test.
|
||||
2. First test deploy not done (needs the explicit go from CMS & API/Bryan; Pi preparation reported done, proxy route already switched, `ASF_TEST_DEPLOY_ENABLED` unset).
|
||||
3. After the first deploy: verification list (manual steps 14-18), forwarded-header observation, optional Pi timing, remove the setup token, report in the hand-back.
|
||||
4. Sentry alert rules to be created after the first successful deploy (by the CMS & API session, with Bryan's go).
|
||||
5. Backup entry for the test database to be confirmed (Pi-Main).
|
||||
6. Merging to master deploys the shared Core change and patched packages to SlpSoftware test automatically; watch that deploy.
|
||||
7. Doc-only commits are local and unpushed.
|
||||
8. Production for Andrea Slop Fotografie (not prepared, listed only): own database and user, port 5201, own proxy route and certificate, `Website__NoIndex=false`, own `shared/env`, production deploy path/variables and an approval decision, production Sentry environment and alert rules, backup entry, HSTS preload/redirect review, decision on the placeholder radius and dark mode.
|
||||
|
||||
|
||||
## Status update 2026-11-09 (open follow-ups above, now)
|
||||
1. CI proof: done (runs 607 onward, all later runs green except one timer flake fixed in 892c548).
|
||||
2. First test deploy: DONE (run 608, then 610, 612, 613-626 on the branch). ASF test is live and used by Bryan and Andrea.
|
||||
3. After the first deploy: first administrators exist (Andrea Owner, Bryan Administrator); the verification list was exercised in use. Still to confirm by Bryan/Pi-Main: setup token removed from `shared/env`, forwarded-header behaviour observed (per-client rate-limit partitions), optional Pi timing.
|
||||
4. Sentry alert rules: not confirmed created (owner: "CMS & API" with Bryan's go). Open.
|
||||
5. Backup entry for the test database: not confirmed (Pi-Main). Open.
|
||||
6. Merge to master (and the automatic SlpSoftware test deploy of the shared Core changes, which are now much larger: see handback-u2 addendum): not done, needs Bryan's explicit go; the branch has already been deployed to SlpSoftware test once (run 625/626/627 from the e-mail branch).
|
||||
7. Doc commits: pushed.
|
||||
8. Production: unchanged (not prepared).
|
||||
Operations questions for this feature were all answered (deployment Q1-5 "alles A", monitoring Q1-5 recommended, Q2 = D). Nothing in this feature's Operations stage is waiting for an answer; what remains is the list above plus the e-mail feature's own Operations stage.
|
||||
Note: the log-level variable in the documents above was replaced by `Website__LogLevel` (a variable name with a dot is ignored by systemd).
|
||||
@@ -0,0 +1,24 @@
|
||||
# Contact feature - prerequisites (read before building)
|
||||
|
||||
Status: not started. Written 2026-11-09 so a new session finds what was decided in conversations. Not part of the identity-email-notifications release.
|
||||
|
||||
## 1. Decision (Bryan): availability statuses block the CMS only, never the public site
|
||||
- Both the master status and the instance's own status (disabled / maintenance) block **CMS actions only**: changing data or settings, and the admin.
|
||||
- **Public routes must never answer 503**: public offerings, contact token, contact submit, `System/capabilities` for guests, `Availability/status`.
|
||||
- The maintenance status stays queryable (open `GET /api/v1/Availability/status`), so the front-end decides what to do with it.
|
||||
- A status that also switches the public site off may come later. Not now.
|
||||
- Admin routes are never exempted.
|
||||
|
||||
## 2. Current gate and proposed change
|
||||
- **Now** (`AvailabilityMiddleware`): everything under `/api/` is gated except a bypass list (`Availability/status`, `Auth/`, `Setup/status`, `master/`, `SlaveStatus`, `/health`). A verified Owner/Administrator token passes. Master status is checked first, then the own status; both answer 503. Since 85d0f6a an *expired* token on a blocked route answers 401 so the app refreshes its session.
|
||||
- **Proposed**: keep deny-by-default and mark public routes explicitly as open. Preferred: a marker attribute (e.g. `[PublicSiteEndpoint]`, defined in Core) read from endpoint metadata - needs the middleware to run after routing; fallback: a second prefix list next to the bypass list. A forgotten or new admin route then stays closed.
|
||||
- **Tests affected** (Availability.Tests, roughly 6-10): `AvailabilityGateScopeTests` (move public paths from "still blocked" to "open", add a negative check that admin routes stay blocked), `AvailabilityMiddlewareMasterGateTests` and `AvailabilityMiddlewareTests` (public route stays 200 under master-down, Disabled and Maintenance). With the attribute approach add a test that lists all public actions so none is added silently.
|
||||
- No migration. Behaviour change: public offerings no longer 503 on a disabled CMS.
|
||||
|
||||
## 3. Evidence that this is needed
|
||||
`GET /api/v1/System/capabilities` returns 503 to a guest while the CMS is off (ASF test journal, 2026-11-09 ~23:33 local; the gate logs "Request blocked by master gate"). The login page reads it, so a guest on a disabled CMS sees failed requests.
|
||||
|
||||
## 4. Deferred items (decide with Bryan, not part of the release)
|
||||
- Own rate-limit policy for `Setup/status` (e.g. 60/min): it now shares the `refresh` policy (20 per 60 s per client IP), and one admin page load costs two permits.
|
||||
- Judge the admin token only when a request would really be blocked: today every gated API call evaluates it, so any normal User call logs a "bypass rejected" security event (log noise).
|
||||
- A visible error state with a "Reload" button as a safety net for the admin app, and a fetch timeout in the API client (a hanging request currently means an endless spinner; start-up retries can also wait up to ~45 s on a 429 with Retry-After).
|
||||
@@ -0,0 +1,70 @@
|
||||
# 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**: OPERATIONS - code complete and on ASF test and SlpSoftware test; waiting for Bryan's testing of run 635 (65ee73f) on both test environments before any merge
|
||||
- **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 | 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**: Yes (Q17 A)
|
||||
- **Decided At**: Requirements Analysis
|
||||
|
||||
## Stage Progress
|
||||
### INCEPTION
|
||||
- [x] Workspace Detection - Complete
|
||||
- [x] Requirements Analysis - P1-P5 decided by Bryan (relayed); requirements.md updated
|
||||
- [~] User Stories - skipped (see execution plan)
|
||||
- [x] Workflow Planning - approved (relayed)
|
||||
- [x] Application Design - approved (relayed); D1 picker in invite dialog, D2 stamp in access token (U3)
|
||||
- [x] Units Generation - U1 mail-foundation, U2 identity-mail-flows, U3 password-reset
|
||||
|
||||
### CONSTRUCTION
|
||||
- [x] U1 mail-foundation - Infrastructure Design (construction/mail-foundation/infrastructure-design/infrastructure-design.md), Code Generation done, build and tests green (see code-summary.md); hand-back pending
|
||||
- [x] U2 identity-mail-flows - Code Generation done, build and tests green (see construction/identity-mail-flows/code/code-summary.md); includes D1 and D2; hand-back pending
|
||||
- [x] U3 password-reset - Code Generation done, build and tests green (see construction/password-reset/code/code-summary.md); hand-back pending (D2, the security stamp in the access token, was built in U2)
|
||||
- [~] Build and Test - summary written (construction/build-and-test/build-and-test-summary.md); manual real test mail on ASF test pending
|
||||
- [ ] Operations (deployment, monitoring, production readiness incl. SPF/DKIM alignment checklist)
|
||||
- Hand-back written (handback.md); Operations questions issued (operations/plans/operations-questions.md), nothing executed until answered
|
||||
### OPERATIONS
|
||||
- [x] Deployment Setup - approved answers Q1 A, Q2 A (ASF production separate, IIS), Q3 A, Q7 A; operations/deployment/*
|
||||
- [x] Monitoring Setup - Q4 B (config-related mail failures at Error), Q5 A; log-level change built and tested; operations/monitoring/*
|
||||
- [x] Production Readiness - checklist written; verdict: not yet (real test mails, Sentry rule, Bryan's approval); operations/production-readiness-checklist.md
|
||||
- Open for a later feature: ASF production on IIS (hosting assumptions listed in operations/deployment/deployment-plan.md)
|
||||
|
||||
### Late fixes after the first test deploys (2026-11-09/10, all on the branch)
|
||||
- [x] Mail layout: SLP red, dark-mode button, logo swap (dark variant) and white badge, site name next to the logo, dark card that stands out (page `#0a0e14`, card `#273244`, 1px border), inline card border `#d1d5db` and Outlook `data-ogsb`/`data-ogsc` rules, 16 px gutter around the card. Light mode unchanged. Real behaviour in the Gmail app (Gmail and non-Gmail account) and Outlook still to be confirmed by a real test mail.
|
||||
- [x] Master/slave status: the slave's fail-open grace period now runs from the master's last contact (poll, push, registration), not from the last successful poll (a pushed "not available" fell open at the next failed poll). Poll failures log `master_poll_failed reason=... detail=...` (first stack frame, `url_absolute`, `scheme`, `key_present`; never URL, key or message).
|
||||
- [x] Master URL: the shipped `appsettings.json` holds a placeholder; the hourly/start-up integrity check (no request) used it and re-registered slaves with it, so their polls failed. Now `MasterUrlRules` (absolute http(s), no credentials/query/fragment): the master skips background checks on an unusable value (warning), a slave refuses one (400 `invalid_master_url`), the poller reports `invalid_master_url`. **The variable is `MasterModule__MasterUrl`** (section `MasterModule`); an earlier note said `Master__MasterUrl`, which is never bound - corrected in `operations/deployment/deployment-plan.md`.
|
||||
- [x] Availability gate: an expired token on a blocked route answers 401 (not 503) so the app refreshes its session and passes as admin; missing, forged, wrong-key and non-admin tokens stay 503.
|
||||
- [x] Session at start-up: a refresh without a verdict (429/5xx/network) ends in an "unreachable" retry screen, not as a guest; Retry-After is sent (refresh 15 s) and honoured (max 15 s per wait).
|
||||
- [x] Logout hang: with the CMS switched off (own setting or master) signing out froze the app. Cause: the AppLayout effect "NotAvailable -> go to /dashboard" also ran for a guest, which the authenticated route sent back to /login - an endless navigation loop. Fixed (only for an authenticated user); test `LogoutWhileCmsOff.test.tsx` never finished on the old code.
|
||||
- [ ] Not built, decisions with Bryan: own rate-limit policy for `Setup/status`, judge the admin token only when a request is really blocked, a visible error state with "Reload" and a fetch timeout (see `../contact-feature/contact-feature-prereqs.md`, local commit 3f060a8, not pushed).
|
||||
- Merge to master: **not approved**. Bryan wants to test both test environments first (including run 635 / 65ee73f); the CMS session may merge later on his explicit go (Gitea PR with merge commit and green CI unless he chooses otherwise).
|
||||
@@ -0,0 +1,134 @@
|
||||
# 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.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
---
|
||||
|
||||
## Requirements Analysis / Workflow Planning / Application Design - P1-P5 decided
|
||||
|
||||
**Timestamp**: 2026-11-08T18:00:00Z
|
||||
|
||||
**User Input**: "(Relayed by 'CMS & API', Bryan's answers in his chat) P1: JA, SiteSettings-opslag bouwen + verplichte toegestane lijst (Email:AllowedFromAddresses) ... alleen Owner wijzigt, Beheerder leest; kaart 'Mail' bij Instellingen; default = Email:FromAddress. P2: akkoord met de forgot/reset-flow. Bryan vraagt: sessies/refresh-tokens pas intrekken NA het kiezen van een nieuw wachtwoord, niet bij het aanvragen van de reset ... P3: Bryan kiest TAAL PER GEBRUIKER NU ... kolom op de gebruiker + migratie (additief ...), keuze in het profiel, fallback op sitestandaard (App:DefaultLanguage) ... P4: JA, in-memory cooldown 1 resetmail per 5 min per adres. P5: zonder opgeslagen status (respons-resultaat + resend-knop). ... Ga door met Workflow Planning en Application Design; geen code tot ik het ontwerp aan Bryan heb voorgelegd als er keuzes zijn. Maak ook de SPF-opmerking over aligned domeinen onderdeel van het Operations-plan (checklist voor productie)."
|
||||
|
||||
**AI Response**: "Updated requirements.md with the decisions (FR-07a: reset request never touches password or sessions, tests required), wrote inception/plans/execution-plan.md (three units, additive migrations), inception/application-design/application-design.md and unit-of-work.md. Open choices for Bryan: D1 invitation language (picker in the invite dialog, default proposed), D2 stamp in access tokens so a completed reset or password change ends sessions immediately (recommended)."
|
||||
|
||||
**Context**: Inception documents complete; approval of requirements and design pending, no code.
|
||||
|
||||
---
|
||||
|
||||
## Construction U1 - approval and code generation
|
||||
|
||||
**Timestamp**: 2026-11-08T20:30:00Z
|
||||
|
||||
**User Input**: "(Relayed by 'CMS & API', Bryan's decisions) Requirements + ontwerp identity-email-notifications: AKKOORD, begin met Code Generation van U1. D1: beheerder kiest nl/en in het uitnodigingsvenster (default sitetaal), bewaard op de uitnodiging, bij afronden overgenomen. D2: direct beeindigen: security stamp in access-token en vergelijken in de actief-controle (ook voor gewone wachtwoordwijziging); tokens van voor de deploy eenmalig geweigerd, refresh geeft stil een nieuw token. Test dit expliciet en meld het als gedragswijziging voor SLP Software. SMTP voor Infrastructure Design: Email__Smtp__Host=mail.slpsoftware.nl, Port=587, EnableSsl=true (STARTTLS). FromAddress/FromName ... no-reply@slpsoftware.nl. Let op SPF-aligned ... blijft productie-checklistpunt. ... Werk U1 op feature/identity-email-notifications, commit lokaal, geen push voordat U1 getest is; meld je na U1 met testresultaten en wat je op ASF test wilt uitrollen."
|
||||
|
||||
**AI Response**: "Built U1 (Core email building blocks, SiteSettings store + migration, SiteSettings API, Mail card, capabilities flags, config sections, README). Tests: Core 452, Identity 96, Availability 82, Master 57, Offerings 57, ASF config 6, frontend 333; MariaDB-backed migration up/down/up and DateTimeOffset round trip verified against a real MariaDB container; vulnerability scan clean. D2 (stamp in access tokens) belongs to U3 and is recorded in the plan."
|
||||
|
||||
**Context**: Construction U1, per-unit build and test done; completion message to follow via the peer session.
|
||||
|
||||
---
|
||||
|
||||
## Construction U2 - code generation
|
||||
|
||||
**Timestamp**: 2026-11-08T22:00:00Z
|
||||
|
||||
**User Input**: "(Relayed by 'CMS & API') Start nu U2 identity-mail-flows (Bryan heeft ontwerp, D1 en D2 goedgekeurd): taal per gebruiker (kolom + profielkeuze), uitnodigingsmail met door beheerder gekozen taal, nieuwe link, opnieuw versturen (respons-resultaat, knop bij openstaande uitnodigingen), meldingen bij deactiveren/heractiveren/rolwijziging, plus de D2 security-stamp-controle. ... Bryan zegt in zijn chat: 'Er mag door jullie gecommit en gepusht worden.' ... Dat geldt NIET voor mergen naar master, deploy naar productie of rollen van mail-secrets; ASF test deploy blijft toegestaan zoals eerder."
|
||||
|
||||
**AI Response**: "Built U2 (migration AddLanguagePreference, IdentityMailService, invite/regenerate/resend with mail result, notices on deactivation/reactivation/role change, language preference in the profile and at sign-in, D2 stamp claim and check). Tests: Core 478 (incl. MariaDB-backed migration up/down/up on a real container), Identity 115, frontend 345. Pushing the branch and dispatching deploy_asf_test (mail stays off until the host gets its mail settings)."
|
||||
|
||||
**Context**: Construction U2 complete; completion message via the peer session.
|
||||
|
||||
---
|
||||
|
||||
## Construction U3 - code generation
|
||||
|
||||
**Timestamp**: 2026-11-08T23:00:00Z
|
||||
|
||||
**User Input**: "(Relayed by 'CMS & API') Bryan: gewone wachtwoordwijziging trekt alleen oude access-tokens in, NIET de refresh-tokens (zoals nu). Alleen de voltooide reset (U3) trekt alle refresh-tokens in. Ga door met U3 password-reset, niet je beurt beeindigen voor U3 gebouwd en getest is."
|
||||
|
||||
**AI Response**: "Built U3 (forgot-password / reset-password, token providers, cooldown, background dispatcher, pages and login link). Tests: Core 500 (reset flow with real Identity and tokens: a request touches nothing, a completed reset ends all sessions), Identity 126, frontend 355. A plain password change keeps refresh tokens (only access tokens end through the stamp), as decided. Design deviation noted: the anonymous forgot-password endpoint handles the request after answering, to keep the response time uniform."
|
||||
|
||||
**Context**: Construction U3 complete; Build and Test and Operations follow.
|
||||
|
||||
---
|
||||
|
||||
## Documentation update and Operations questions
|
||||
|
||||
**Timestamp**: 2026-11-09T08:30:00Z
|
||||
|
||||
**User Input**: "(Relayed by 'CMS & API') JA, werk de handback-docs en de Build-and-Test-samenvatting bij (latere fixes: roltoekenning, poort, timers, SMTP-fases, 503-poort, setup-guard, 9 punten, bug-records), commit en push. Operations-fase e-mailfeature: stel een vragenbestand op met de keuzes voor Bryan (deployment, monitoring/alerts voor mail_configuration_invalid / identity_mail_failed / auth_failed, SPF/DKIM-checklist, productie-uitrol) en geef me de vragen; geen Operations-uitvoering zonder zijn antwoorden. Ook de ASF-feature andreaslop-site-hosting Operations: kijk of die vragen/keuzes al beantwoord zijn ..."
|
||||
|
||||
**AI Response**: "Wrote handback.md, updated build-and-test-summary.md, wrote operations/plans/operations-questions.md (8 questions), added an addendum to the ASF handback-u2.md and a status update to its production-readiness checklist (all its Operations questions were answered; open items listed). No Operations execution."
|
||||
|
||||
**Context**: Documentation and Operations planning; waiting for Bryan's answers.
|
||||
|
||||
---
|
||||
|
||||
## Operations stage
|
||||
|
||||
**Timestamp**: 2026-11-09T10:00:00Z
|
||||
|
||||
**User Input**: "(Relayed by 'CMS & API', Bryan's answers) 1 A (met de hand in shared/env). 2 A, MAAR: voor ASF bestaat nog geen productieomgeving en die wordt een IIS-server i.p.v. Raspberry Pi; ASF-productie pakken we dus los op (niet in deze feature). Volgorde nu: ASF test, SlpSoftware test, dan SlpSoftware-productie met eigen akkoord. 3 A (no-reply@andreaslop.nl op mail.andreaslop.nl). 4 B ... 5 A ... 6 A ... 7 A ... 8 A ... Voer nu Deployment Setup, Monitoring Setup en Production Readiness uit voor de e-mailfeature (alleen docs + de kleine logniveau-wijziging uit vraag 4 ...). Leg vast dat ASF-productie op IIS komt en wat dat betekent voor de hostingaannames in jouw docs ... markeer als open punt voor die latere ASF-productiefeature, niet nu uitwerken."
|
||||
|
||||
**AI Response**: "Recorded the answers, wrote deployment plan/instructions/rollback, monitoring plan/setup, production readiness checklist, and built the log-level change (configuration-related mail failures auth_failed, rejected_sender, tls_failed, not_configured are Error events, the rest Warning) with tests. IIS recorded as an open point for the later ASF-production feature."
|
||||
|
||||
**Context**: Operations phase complete for the e-mail feature (docs and code); production readiness verdict: not yet.
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
## Test findings and fixes after the first deploys
|
||||
|
||||
**Timestamp**: 2026-11-10T00:30:00Z
|
||||
|
||||
**User Input**: "(Relayed by 'CMS & API', Bryan's test results and decisions, runs 632-635) ASF status falls back after ~9 s; owner logged out while ASF is not available; mail card invisible in dark mode; ASF poll failing with InvalidOperationException; app keeps loading after logout with the CMS switched off; merge to master not yet - test first. Update aidlc-state.md, audit.md and the production readiness checklist with what happened and turned out."
|
||||
|
||||
**AI Response**: "Found and fixed (separate commits on the branch, see aidlc-state.md 'Late fixes'): fail-open grace period measured from the last contact of the master; unusable master URL (shipped placeholder re-registered into slaves by the integrity check) with validation on both sides and safe poll diagnostics; expired token answered 401 by the gate; start-up refresh without a verdict ends in a retry screen with Retry-After; mail card (title next to logo, border, Outlook rules, gutter); logout hang (AppLayout redirect effect ran for a guest, endless navigation loop, reproduced by a test that never finished before the fix). Corrected a wrong variable name in my release note: MasterModule__MasterUrl, not Master__MasterUrl (it was never bound, which is why the master kept the placeholder). Not proven: why clearing site data cured the hang on the phone; whether the Gmail app/Outlook now show the dark card (needs a real test mail). Proposals left to Bryan: Setup/status rate-limit policy, admin-token evaluation only on a real block, error state with Reload, fetch timeout, and the availability-gate change for the contact feature (written down in features/contact-feature/contact-feature-prereqs.md)."
|
||||
|
||||
**Context**: Operations/test feedback loop; merge to master explicitly not approved until Bryan has tested both test environments including run 635 (65ee73f).
|
||||
|
||||
---
|
||||
|
||||
+55
@@ -0,0 +1,55 @@
|
||||
# Build and Test summary - identity-email-notifications (U1 + U2 + U3)
|
||||
|
||||
Branch `feature/identity-email-notifications`, head after U3. Everything below was run locally except the MariaDB-backed API host tests, which run in CI (the developer's `appsettings.local.json` overrides the connection string on this machine).
|
||||
|
||||
## Build
|
||||
- `dotnet build` of the solution: succeeds (no new warnings from this feature; the pre-existing NU1510 pruning warnings are unrelated).
|
||||
- Frontend: `npx tsc -b` clean, `npx eslint .` clean, `vite build` for the default build and `VITE_THEME=asf` succeeds.
|
||||
- New dependency: MailKit 4.18.2 (MimeKit transitive). `dotnet list package --vulnerable --include-transitive`: none.
|
||||
|
||||
## Unit and component tests
|
||||
| Suite | Result |
|
||||
|---|---|
|
||||
| Core.Tests | 502 passed (mail options/validator, address rules, renderer, SMTP sender against an in-process stub, site settings, mail service, language, password-reset flow with real Identity and tokens, cooldown, dispatcher, stamp check, DI wiring; property-based tests PBT-02/03/07/08/09) |
|
||||
| Modules.Identity.Tests | 126 passed (users, hierarchy, mail flows, site settings API, auth incl. forgot/reset) |
|
||||
| Modules.Availability / Master / Offerings | 82 / 57 / 57 passed (unchanged) |
|
||||
| Api.AndreaSlopFotografie.Tests (config) | 6 passed (mail off by default, no credential committed) |
|
||||
| Frontend (Vitest) | 355 passed |
|
||||
|
||||
## Integration tests
|
||||
- **Real MariaDB (run locally in a throw-away container, and in CI via `ConnectionStrings__DefaultConnection`)**: all migrations apply on a fresh database; the two newest are undone and re-applied (`AddSiteSettings`, `AddLanguagePreference`); the `DateTimeOffset` round trip keeps the full 24 hours whatever the written offset.
|
||||
- **Real pipeline on a TestServer**: real Identity, real data-protection tokens, real JWT bearer check: deactivated or deleted users are refused with a valid token (GET and POST), a password change or reset ends earlier access tokens (stamp), refresh keeps working after a plain change, a completed reset revokes refresh tokens, a request touches nothing.
|
||||
- **SMTP**: the sender talks to an in-process SMTP server (success, sender override, header-injection refused without connecting, timeout, nothing listening).
|
||||
- **Not run here, runs in CI**: `Api.Tests` and the ASF `HostPipelineTests` (they start the full hosts against MariaDB and apply the new migrations through the real start-up path).
|
||||
- **Manual, still to do (needs Bryan's go and the mail settings on the host)**: one real test mail from the ASF test host to an address of Bryan (invitation; "Wachtwoord vergeten?"; resend), the Mail card, the language choice, a deactivation notice. smtp4dev can be used locally first.
|
||||
|
||||
## Performance
|
||||
Not applicable beyond: one extra indexed query per authenticated request (active and stamp check, no cache by design). Mail is sent inside administrator requests with a 10 s bound; the anonymous reset request answers immediately.
|
||||
|
||||
## Security checks (Security Baseline)
|
||||
Input validation on every new endpoint (address allowlist, bounded lengths), anonymous endpoints rate limited and uniform (no account enumeration), tokens single-use and time-limited, no secrets or tokens or links in logs (recipient domain only), credentials only via environment, start-up validation without echoing secrets, dependency scan clean. Compliant; items N/A as listed in the requirements.
|
||||
|
||||
## Behaviour changes for SlpSoftware (when it is deployed there)
|
||||
Access tokens issued before the release are refused once (silent refresh issues a new one); a password change ends earlier access tokens; three additive migrations (`SiteSettings`, `Users.PreferredLanguage`, `Invitations.Language`); default token providers registered; two new anonymous endpoints that answer 404 while mail is off; nothing else changes without an SMTP host.
|
||||
|
||||
## Open items before the feature can close
|
||||
1. The real test mail on ASF test (manual, above). 2. Operations stage (deployment config, monitoring, production readiness incl. the SPF/DKIM alignment checklist). 3. Bryan's approval of this stage.
|
||||
|
||||
|
||||
## Update 2026-11-09: later changes on this branch (all with tests, all pushed)
|
||||
| Change | Test evidence |
|
||||
|---|---|
|
||||
| D2 stamp in the access token (built in U2) | Core: real Identity + real tokens, password change ends earlier access tokens, refresh issues a new one |
|
||||
| Soft mail configuration: a half-finished mail configuration starts the host with mail OFF and one Error line naming the settings (no values, no secrets) | `MailSoftFailureTests`, `DeployedConfigurationTests` for master, slave, SlpSoftware, ASF |
|
||||
| `Website__LogLevel` (systemd drops variable names with a dot) | `WebsiteLogLevelTests` |
|
||||
| Role hierarchy in the API; the caller is recognised by the user id of the token (a real token has no name claim: an Owner got 403 promoting to Owner) | `UsersApiWithRealTokensTests` (real tokens, real pipeline; 5 of 7 failed before the fix) |
|
||||
| Mail diagnostics: SMTP command failure phase and status, redacted first reply line, specific codes (`rejected_sender`, `rejected_recipient`, `tls_failed`, `connection_failed`), `timeout_connect/auth/send`, a timeout of its own per step (it was one shared budget), `TimeoutSeconds` 1..120 | `SmtpFailureTests`, `SmtpSenderDiagnosticsTests` (SMTP stub that refuses or stalls), property test (control characters could re-glue an address) |
|
||||
| "New invitation link" mails only on request (`sendEmail`), with a choice dialog | controller, real-HTTP and UI tests |
|
||||
| Layout: only the content scrolls, the sidebar stays | layout class tests |
|
||||
| Redirect timers cleaned up on unmount (a CI-only "window is not defined") | page test fails on the old code, `useDelayedAction` tests |
|
||||
| Availability gate only covers `/api/` (a disabled CMS still serves the website and `/admin`) | 27 new Availability tests incl. a real in-memory pipeline; 16 failed before |
|
||||
| Setup page never shown for an unreadable setup status; login notice for a disabled CMS | 6 error cases (5 failed before), limiter test |
|
||||
|
||||
Current counts (local, last full run): Core 563, Identity 141, Availability 109, Master 57, Offerings 57, ASF host configuration 6, frontend 390. CI (with MariaDB): all green on the runs 626 and before; the MariaDB-backed migration up/down/up and `DateTimeOffset` round trip run there.
|
||||
|
||||
Still open for this stage: the manual real test mail from the ASF test host (the SMTP sender address and TLS mode of `mail.andreaslop.nl` are being sorted out by Bryan and Pi-Main; the failure diagnostics above exist to see why a mail is refused) and Bryan's approval.
|
||||
+25
@@ -0,0 +1,25 @@
|
||||
# Code summary - U2 identity-mail-flows
|
||||
|
||||
## What was built
|
||||
**Data (migration `AddLanguagePreference`, additive, reversible)**: `Users.PreferredLanguage` (nullable, nl/en), `Invitations.Language` (nullable).
|
||||
|
||||
**Core**
|
||||
- `IIdentityMailService` / `IdentityMailService`: one orchestration point for invitation, new-link, deactivation, reactivation and role-change mails. Builds the link as `App:PublicBaseUrl + /admin + path`, resolves the language (user preference, else the invitation's, else `App:DefaultLanguage`, else nl), takes the sender and name from the site settings, logo and colour from config, renders, sends, logs only kind and recipient domain, and never throws (a failure is a `MailSendResult`). Returns `disabled` when the site has no SMTP host.
|
||||
- `InvitationService`: language stored normalised on the invitation and copied to the new account's `PreferredLanguage` on completion.
|
||||
- **D2**: the security stamp is a claim of the access token (`AuthService`) and is compared in `ActiveUserTokenValidation`. A password change or reset changes the stamp, so every access token issued before it is refused; a token without the claim (issued before this release) is refused once; the refresh token silently issues a new one that carries the claim.
|
||||
- `UserResponse`/`UserDto` carry `Language`.
|
||||
|
||||
**Identity module (`UsersController`)**
|
||||
- `POST Users/invite` accepts `language`, sends the mail, returns `{ inviteLink, mail }` (the invitation exists whatever happens to the mail). `POST Users/{id}/regenerate-invite` now also mails the new link. New `POST Users/{id}/resend-invite`: resends the current link, or creates a new one first when expired. `mail` is `{ sent, error }`, or null on a site without mail. Same role-hierarchy rules as the other invitation actions.
|
||||
- Deactivate, reactivate and role change send a notice only on a real change (and not for invitations); a failure never fails the action.
|
||||
- `PUT Users/me` accepts `language` (null = unchanged, "" = clear, nl/en, anything else 400).
|
||||
|
||||
**Frontend**: language select in the profile (applied immediately; clearing falls back to the site default), the saved language is applied at sign-in and on the first silent refresh after a page load (not on later refreshes, so a temporary top-bar switch survives); invite dialog gets a language select (default = site language) and shows "mail sent to X" or a failure with a short reason next to the copyable link; users list gets "Uitnodiging opnieuw mailen" and the regenerate action reports the mail result; everything mail-related is hidden when the site has no mail (`emailEnabled` false).
|
||||
|
||||
## Tests
|
||||
- Core.Tests 478: `IdentityMailServiceTests` (link, sender, logo, lifetime, language chain, disabled, failure value, exceptions never escape, notices, role names, `BuildLink`), invitation language (normalised, unsupported ignored, copied to the account), D2 (`DeactivatedUserAccessTests`: stamp change ends tokens for GET and POST, missing and wrong stamp refused; `SessionEndsOnPasswordChangeTests`: real Identity password change with real tokens, the old access token is refused, the refresh token gives a working new one, login response carries the language). MariaDB-backed migration test now covers both new migrations up, down, up (verified on a real MariaDB container).
|
||||
- Identity.Tests 115: `UsersControllerMailTests` (invite with language and result, failure still succeeds, no mail result without mail, unsupported language, regenerate/resend including expired and failed, hierarchy, notices only on real change, notice failure never fails the action, role change of an invitation sends nothing, profile language set/clear/unchanged/invalid, list shows languages).
|
||||
- Frontend 345: invite dialog (no language field without mail, default site language, chosen language sent, sent/failed/no mail line), resend (hidden without mail, success, failure hands over the link, expired), profile language, language applied at sign-in or left alone. ESLint and tsc clean; asf build ok.
|
||||
|
||||
## Behaviour change for SlpSoftware (and every host)
|
||||
1. After deploy, access tokens issued before it lack the stamp and are refused once; the silent refresh issues a new one (users stay signed in). 2. A password change now ends earlier access tokens immediately (refresh tokens are not revoked by a plain password change; only the reset flow in U3 revokes them). 3. Two nullable columns are added by migration. 4. Mail only when `Email:Smtp:Host` is set; otherwise nothing changes (the new `language` field of the invite request is ignored when mail is off in the UI).
|
||||
+28
@@ -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).
|
||||
+71
@@ -0,0 +1,71 @@
|
||||
# Infrastructure design - U1 mail-foundation
|
||||
|
||||
## Configuration keys (per environment, on the host)
|
||||
| Key | Where | Example / note |
|
||||
|---|---|---|
|
||||
| `Email__Smtp__Host` | `shared/env` | `mail.slpsoftware.nl` (the SMTP host SimpleDeckApp uses in production, per Bryan). Setting it switches mail ON. |
|
||||
| `Email__Smtp__Port` | `shared/env` | `587` |
|
||||
| `Email__Smtp__EnableSsl` | `shared/env` | `true` (STARTTLS) |
|
||||
| `Email__Smtp__Username`, `Email__Smtp__Password` | `shared/env` (mode 600) | secrets, never committed, never in messages or logs |
|
||||
| `App__PublicBaseUrl` | `shared/env` | `https://test.andreaslop.nl` (https, no path) |
|
||||
| `App__DefaultLanguage` | optional | `nl` (default) or `en` |
|
||||
| `Email__FromAddress`, `Email__FromName` | committed default or env | `no-reply@slpsoftware.nl` / site name (SimpleDeckApp's committed default) |
|
||||
| `Email__AllowedFromAddresses__0..n` | env | extra sender addresses a site may choose in its settings; empty = only `FromAddress` |
|
||||
| `Email__LogoUrl`, `Email__BrandColor` | committed (ASF) or env | `/admin/brand-logo-on-light.png`, `#5f6a58` |
|
||||
|
||||
Start-up validation refuses a broken mail configuration (when a host is set) with a message that never contains the credentials. Without a host nothing changes.
|
||||
|
||||
## Local development
|
||||
smtp4dev (already installed) on `localhost:25`: `Email__Smtp__Host=localhost`, `Email__Smtp__Port=25`, `Email__Smtp__EnableSsl=false`, no username, `App__PublicBaseUrl=http://localhost:5200` (http is accepted for loopback only).
|
||||
|
||||
## ASF test host (Operations will do it, needs Bryan's go for the real test mail)
|
||||
1. Add the keys above to `shared/env` of `andreaslopfotografie-test` (mode 600 stays), restart the unit.
|
||||
2. `Email__FromAddress` stays `no-reply@slpsoftware.nl` (the SMTP service's own domain). A sender on `@andreaslop.nl` only after the check below.
|
||||
3. One real test mail to an address of Bryan before approval.
|
||||
|
||||
## Sender-domain alignment (production checklist item)
|
||||
`From:` domain, SPF and DKIM must agree with the SMTP service that actually sends:
|
||||
- SPF of the `From:` domain must authorise the sending service (today both `slpsoftware.nl` and `andreaslop.nl` publish `v=spf1 a mx include:smtp.spf.ziggo.nl ~all`).
|
||||
- That service must DKIM-sign for the `From:` domain (a `dkim._domainkey` record exists for both domains; whether the service signs with it is not visible from outside).
|
||||
- `mail.slpsoftware.nl` will deliver `@andreaslop.nl` mail properly only if it may send/sign for that domain. DMARC is `p=none` today (monitoring only).
|
||||
- Therefore the sender list is an allowlist: add an `@andreaslop.nl` address to `Email__AllowedFromAddresses` only after this is confirmed.
|
||||
|
||||
## No other infrastructure
|
||||
No new service, port, queue or storage. One additive table (`SiteSettings`) in the existing database.
|
||||
|
||||
## Per-host SMTP server (update 2026-11-08, from Bryan via "CMS & API")
|
||||
The SMTP settings are per host (all in that host's `shared/env`), so each site can use its own mail server:
|
||||
|
||||
| Site | SMTP host | Sender domain | Status |
|
||||
|---|---|---|---|
|
||||
| SlpSoftware | `mail.slpsoftware.nl` (the host SimpleDeckApp uses) | `@slpsoftware.nl` | as before |
|
||||
| ASF (test, later production) | probably `mail.andreaslop.nl` (not `mail.slpsoftware.nl`) | `@andreaslop.nl` | **to be confirmed** |
|
||||
|
||||
Read-only checks done from the developer PC (by "CMS & API"): `mail.andreaslop.nl` and `andreaslop.nl` both resolve to 217.121.250.215; the MX of `andreaslop.nl` is `mail.andreaslop.nl` (preference 10); TCP 587 is reachable. This fits the published SPF (`a mx`): a mail sent by that server for `@andreaslop.nl` is SPF-aligned, which the earlier plan (`mail.slpsoftware.nl` for ASF) would not have been.
|
||||
|
||||
**Open points (Operations plan, no code needed):**
|
||||
1. Which mailbox/account on `mail.andreaslop.nl` is used, and whether it may send with `no-reply@andreaslop.nl` (or another address) as `From`. Then ASF sets `Email__FromAddress` and `Email__AllowedFromAddresses__n` accordingly (the committed ASF default `no-reply@slpsoftware.nl` is only a placeholder until then). SlpSoftware keeps `mail.slpsoftware.nl`.
|
||||
2. Port and TLS: not yet confirmed that the server offers STARTTLS on 587 (`Email__Smtp__EnableSsl=true`); if it needs implicit TLS (465) or none, the sender must be adapted (it supports STARTTLS or plain today) and a plain connection would not be acceptable beyond a private network.
|
||||
3. DKIM: a `dkim._domainkey.andreaslop.nl` record exists; confirm the server signs with that key. DMARC is `p=none` (monitoring only).
|
||||
4. Credentials for that account go into the ASF test unit's `shared/env` by whoever manages the host (not by this feature's code or by chat).
|
||||
|
||||
## Release notes for the host manager (required environment variables per release)
|
||||
- **This release adds NO required environment variable.** A host without any mail setting starts exactly as before; this is tested for every deployed host configuration (master, slave, SlpSoftware, ASF).
|
||||
- Mail is switched on only by setting `Email__Smtp__Host`, and it only turns ON when the whole mail configuration is valid: `App__PublicBaseUrl` (https, no path), `Email__FromAddress`/`Email__FromName` (committed defaults), `Email__Smtp__Username` together with `Email__Smtp__Password`, and sane port, timeout, colour and logo values. **A half-finished or wrong mail configuration never stops the host from starting** (decided by Bryan after the 2026-11-08 incident): the host starts with mail OFF (`emailEnabled=false`, all mail UI hidden, the copy-link flow keeps working) and logs ONE Error line, `mail_configuration_invalid`, that names each missing or invalid setting (names only, never values or secrets; Sentry sees it). Check the log after changing mail settings. Set `App__PublicBaseUrl` together with `Email__Smtp__Host`.
|
||||
- Optional: `Identity__Invitation__ExpiryHours` (24), `Identity__PasswordReset__TokenLifetimeMinutes` (60), `Identity__PasswordReset__CooldownMinutes` (5), `App__DefaultLanguage` (nl), `Email__AllowedFromAddresses__0..n`, `Website__LogLevel`.
|
||||
- Incident 2026-11-08: ASF test returned 502 after a restart because `Email__Smtp__Host` was set but `App__PublicBaseUrl` was not (the start-up validation at that time refused a half-configured mail setup). Not a deploy without mail configuration. Since changed: the soft behaviour above.
|
||||
|
||||
## Which sender is used, and what the server must accept (update 2026-11-08)
|
||||
The `From:` address of every mail is decided in this order: (1) the sender chosen in the site settings (Mail card), if it is still on the allowlist; otherwise (2) `Email:FromAddress` (environment variable `Email__FromAddress`, else the committed default of that host's `appsettings.json`). The committed default of the ASF host is `no-reply@slpsoftware.nl` (copied from SimpleDeckApp); the SlpSoftware host has the same. The SMTP server checks the `MAIL FROM` against the logged-in account (the envelope sender is always the `From:` address here, MailKit uses it).
|
||||
|
||||
**So for `mail.andreaslop.nl` the ASF host must set**, in `shared/env`: `Email__FromAddress=<an address on andreaslop.nl>` and `Email__AllowedFromAddresses__0=<the same address>` (plus `Email__FromName`), where that address is one the SMTP account is allowed to use as sender. With the default `no-reply@slpsoftware.nl` the server is likely to refuse the sender (error code `rejected_sender`, SMTP 5xx at MAIL FROM) or not relay it. A change of the committed ASF default to an `@andreaslop.nl` address is a decision for Bryan (not made).
|
||||
|
||||
**Diagnosis in the log** (Pi-Main journal): at start `mail_status enabled=true smtp_host=... smtp_port=... starttls=... default_from_domain=...`; per failed mail `identity_mail_failed code=... detail=... from_domain=... smtp_port=...`, where `detail` for a refused command is `SmtpCommandException phase=SenderNotAccepted|RecipientNotAccepted|MessageNotAccepted smtp_status=<name>(<number>) reply="<first line of the server reply, addresses replaced by [adres], at most 120 characters>"`. The codes shown to the administrator: `rejected_sender`, `rejected_recipient`, `rejected`, `auth_failed`, `tls_failed`, `connection_failed`, `timeout`, `not_configured`, `unknown`. Never logged: credentials, addresses, tokens, links, the rest of a server reply.
|
||||
|
||||
## SMTP connection, security mode and timeouts (update 2026-11-09, for the Pi-Main journal questions)
|
||||
- **Security mode**: `Email__Smtp__EnableSsl=true` (the default) means MailKit `SecureSocketOptions.StartTls` (plain connection, then the STARTTLS upgrade; the normal setting for port 587). `false` means no encryption at all (`SecureSocketOptions.None`, only for a local catcher such as smtp4dev). Implicit TLS (port 465) is not supported.
|
||||
- **Authentication**: only when `Email__Smtp__Username` is set (then the password is required); MailKit picks the strongest mechanism the server offers.
|
||||
- **Timeout**: `Email__Smtp__TimeoutSeconds`, default **10**, allowed **1 to 120** (a value outside that switches mail off at start-up with an Error line naming the setting). It applies to EACH step separately (connect including the STARTTLS upgrade, login, send), so a slow login no longer uses up the time of the send; the worst case for one mail is three times the value. An administrator's request waits for it, so keep it modest; raise it (for example to 30) when the server is slow to log in.
|
||||
- **Per environment**: every SMTP setting lives in that host's `shared/env` (host, port, EnableSsl, username, password, timeout, `App__PublicBaseUrl`); hosts can differ (SlpSoftware `mail.slpsoftware.nl`, ASF probably `mail.andreaslop.nl`).
|
||||
- **Reading a failure in the journal**: `identity_mail_failed code=<code> detail=... phase=<connect|auth|send> timings="connect=120ms auth=4800ms(failed)" timeout_per_phase_s=10 from_domain=... smtp_port=...`. `timings` lists every step that ran and how long it took in milliseconds; the step marked `(failed)` is where it went wrong. MailKit does the STARTTLS upgrade inside the connect step, so "connect" covers the TCP connection, the greeting and the TLS upgrade together. Timeout codes: `timeout_connect`, `timeout_auth`, `timeout_send` (the screen text names the step). For a refused command the `detail` already holds the phase, the SMTP status code and the redacted first line of the server reply (since daaadcb). Nothing in the line is secret: no credentials, no addresses, no tokens.
|
||||
- **Typical readings**: `auth_failed` with `phase=AUTH` = wrong username or password (and repeated failures can make a server throttle or block the client address, for example fail2ban); `timeout_auth` = the server accepted the connection but took too long to answer the login (slow authentication backend, or a throttle); `timeout_connect` = no greeting or STARTTLS in time (firewall, wrong port, server down); `timeout_send` = the server stalled while taking the message.
|
||||
+23
@@ -0,0 +1,23 @@
|
||||
# Code summary - U3 password-reset
|
||||
|
||||
## What was built
|
||||
**Core**
|
||||
- Identity gets the default token providers (stateless data-protection reset token, single use through the security stamp). `PasswordResetSettings` (section `Identity:PasswordReset`: `TokenLifetimeMinutes` default 60, range 5..1440; `CooldownMinutes` default 5, range 1..60), validated at start-up; the reset link lifetime is the data-protection token lifetime.
|
||||
- `IPasswordResetService`:
|
||||
- `RequestAsync(email)`: only when mail is on and the cooldown allows; unknown, deactivated and blank addresses do nothing; sends the reset mail. It writes nothing else: no password, security stamp, access token or refresh token is touched. Never throws.
|
||||
- `ResetAsync(userId, token, newPassword)`: `UserManager.ResetPasswordAsync`; a bad, expired, used or foreign token, an unknown or deactivated user are one generic `InvalidLink`; a password-policy failure (checked after the token, so only a link holder sees it) is `PasswordRejected` and does not use up the link. **Only a completed reset revokes every refresh token of the account**; earlier access tokens end through the changed security stamp (D2).
|
||||
- `ResetCooldown` (in memory, `TimeProvider`-driven): one mail per address per window, unknown addresses included, bounded memory (purge, hard cap 10,000, refuse new addresses when full).
|
||||
- `IPasswordResetDispatcher` / `BackgroundPasswordResetDispatcher`: the anonymous endpoint answers first and the request is handled afterwards in its own scope, so the response time does not tell whether the address exists and a slow SMTP server cannot hold the request (a deliberate difference from the in-request sending of administrator-triggered mails).
|
||||
- `IIdentityMailService.SendPasswordResetAsync`: link `App:PublicBaseUrl/admin/reset-password?uid=<user id>&token=<token>` (user id, no e-mail address in a URL), recipient's language, lifetime stated in the mail.
|
||||
|
||||
**Identity module (`AuthController`)**: `POST auth/forgot-password` (anonymous, `login` rate limiter): 404 on a site without mail, 400 for a malformed address, otherwise always the same 202 body. `POST auth/reset-password` (anonymous, `login` rate limiter): input bounds (token 2048, password 128, non-empty user id), 200, or 400 with `invalid_link` / `password_rejected`.
|
||||
|
||||
**Frontend**: `/forgot-password` (neutral "if this address belongs to an account..." message; 404 explained), `/reset-password?uid&token` (same password rules as everywhere, success, one generic "link invalid or expired" page with "request a new link", a rejected password keeps the form), "Wachtwoord vergeten?" on the login page only when `emailEnabled`, nl/en strings.
|
||||
|
||||
## Tests
|
||||
- Core.Tests (real Identity, real data-protection tokens, real bearer check on a TestServer): **a request leaves password hash, security stamp, refresh tokens, the earlier access token and the old password all working** (Bryan's rule); **a completed reset sets the new password, ends the earlier access token (401), revokes the refresh token, no active refresh tokens remain, the old password fails**; the link works once; an expired link is refused and the password stays; another user's token, garbage and an unknown user are refused; a weak password is reported without using up the link; unknown, deactivated and blank addresses send nothing and do not throw; a deactivated account cannot complete a reset; a site without mail does nothing; one mail per address per window (case-insensitive) then works again; the cooldown also applies to unknown addresses; cooldown memory bound; property-based: for any request sequence two accepted requests for one address are never closer than the window (PBT-03); settings ranges; DI wiring and start-up validation; dispatcher returns at once and handles in the background, a failing request never surfaces; reset mail link carries the user id and no address.
|
||||
- Identity.Tests 126: both endpoints anonymous and under the `login` limiter, same 202 for any well-formed address, malformed addresses rejected without dispatching, 404 without mail, outcome mapping, bounds.
|
||||
- Frontend 355: login link only with mail, validation, neutral sent message, 404, missing link, rules, token/uid sent, generic invalid page, rejected password keeps the form.
|
||||
|
||||
## Behaviour change for SlpSoftware (and every host)
|
||||
Identity registration now includes the default token providers (inert unless a reset is requested); the two endpoints answer 404 while mail is off; nothing else changes without mail.
|
||||
@@ -0,0 +1,24 @@
|
||||
# Hand-back - identity-email-notifications (U1 + U2 + U3 and what followed)
|
||||
|
||||
Branch `feature/identity-email-notifications` (contains the whole andreaslop-site-hosting feature as well). Not merged, not on production. Deployed (test only): ASF test and SlpSoftware test (mail switched OFF there until the host gets its mail settings).
|
||||
|
||||
## 1. What exists
|
||||
- **Mail core** (Core): `IEmailSender` (MailKit, StartTls, one timeout per step, failures are values), options with one decision point `IMailAvailability` (SMTP host set AND configuration valid, otherwise mail OFF with one Error line naming the settings), nl/en template (logo, brand colour, button plus raw link, plain-text part), language per user (user, invitation, site default, nl).
|
||||
- **Site settings** (new table `SiteSettings`): sender address chosen only from `Email:AllowedFromAddresses` plus the default, sender name 1..80 characters; Owner changes, Administrator reads; Mail card on the Settings page (only when mail is on).
|
||||
- **Flows**: invitation mail (language chosen by the administrator), new link (choice: copy only / copy and mail), resend, notices on deactivation, reactivation, role change, password reset (`forgot-password`, `reset-password`; request touches nothing, only a completed reset revokes sessions; link single use, 60 minutes; per-address cooldown 5 minutes; the request is handled after the response so timing does not reveal accounts).
|
||||
- **Security**: the security stamp is part of the access token (a password change/reset ends earlier access tokens, refresh keeps working); deactivated/deleted users refused at once; role hierarchy in the API; no secret, address, token or link in any log.
|
||||
|
||||
## 2. Configuration for a host (see construction/mail-foundation/infrastructure-design)
|
||||
`Email__Smtp__Host/Port/EnableSsl/Username/Password/TimeoutSeconds`, `App__PublicBaseUrl`, `Email__FromAddress`, `Email__FromName`, `Email__AllowedFromAddresses__n`, optional `Email__LogoUrl`, `Email__BrandColor`, `App__DefaultLanguage`, `Identity__Invitation__ExpiryHours`, `Identity__PasswordReset__*`. All per host in `shared/env`. A host without a mail setting is unchanged; no new variable is required by this release.
|
||||
|
||||
## 3. Behaviour changes for SlpSoftware (when it is on a release with this branch)
|
||||
First deploy: three additive migrations (`SiteSettings`, `Users.PreferredLanguage`, `Invitations.Language`), existing access tokens refused once (silent refresh), a password change ends earlier access tokens, user management API stricter (role hierarchy, caller recognition by id), a deactivated or deleted user is refused at once (one extra query per authenticated request), availability gate covers `/api/` only, setup status read under the ordinary limiter, expired invitations listed, two new anonymous endpoints (404 while mail is off), default Identity token providers registered. Mail stays off without an SMTP host.
|
||||
|
||||
## 4. Verification
|
||||
See `construction/build-and-test/build-and-test-summary.md` (including the update of 2026-11-09). Real MariaDB: migrations up, down, up and the `DateTimeOffset` round trip (CI and locally in a throw-away container). Not yet done: the manual real test mail on ASF test.
|
||||
|
||||
## 5. Open items
|
||||
1. Real test mail from ASF test (needs the sender address on `andreaslop.nl` via env and the TLS mode of `mail.andreaslop.nl` confirmed; the failure log now names the phase and SMTP status).
|
||||
2. Operations stage: questions in `operations/plans/operations-questions.md` (for Bryan), nothing executed.
|
||||
3. Merge to master and the SlpSoftware production roll-out: not approved.
|
||||
4. Optional follow-up decisions: per-user language is in, per-site template editing is not; whether "Gebruiker uitnodigen" should also ask before mailing (Bryan: no, unchanged).
|
||||
+126
@@ -0,0 +1,126 @@
|
||||
# Application Design - identity-email-notifications
|
||||
|
||||
## 1. Components
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph Core["SlpModularCms.Core"]
|
||||
ES["IEmailSender<br/>SmtpEmailSender (MailKit)"]
|
||||
EO["EmailOptions<br/>(section Email) + validator"]
|
||||
MR["IMailTemplateRenderer<br/>nl/en resources, shared HTML"]
|
||||
LR["ILanguageResolver<br/>user, site default"]
|
||||
SS["ISiteSettingsService<br/>SiteSettings table"]
|
||||
IM["IIdentityMailService<br/>orchestrates one mail"]
|
||||
CD["ResetCooldown<br/>(in-memory)"]
|
||||
end
|
||||
subgraph Identity["Modules.Identity"]
|
||||
UC["UsersController<br/>invite, regenerate, resend,<br/>active, role, me"]
|
||||
AC["AuthController<br/>forgot-password, reset-password"]
|
||||
SC["SiteSettingsController<br/>mail card API"]
|
||||
end
|
||||
subgraph FE["frontend"]
|
||||
SP["Settings: Mail card"]
|
||||
PR["Profile: language"]
|
||||
IV["Invite dialog + users list"]
|
||||
PW["Forgot / reset pages"]
|
||||
end
|
||||
UC --> IM
|
||||
AC --> IM
|
||||
AC --> CD
|
||||
IM --> ES
|
||||
IM --> MR
|
||||
IM --> LR
|
||||
IM --> SS
|
||||
ES --> EO
|
||||
SC --> SS
|
||||
SP --> SC
|
||||
PR --> UC
|
||||
IV --> UC
|
||||
PW --> AC
|
||||
classDef core fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
classDef mod fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef fe fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
class ES,EO,MR,LR,SS,IM,CD core;
|
||||
class UC,AC,SC mod;
|
||||
class SP,PR,IV,PW fe;
|
||||
```
|
||||
Text alternative: controllers call one orchestrator (IIdentityMailService) in Core, which uses the sender, the template renderer, the language resolver and the site settings; the frontend talks only to the controllers.
|
||||
|
||||
### Core
|
||||
- **`IEmailSender`** (same shape as SimpleDeckApp): `Task SendAsync(string toAddress, string subject, string htmlBody, CancellationToken ct)`. A second overload carrying the plain-text part and the From override is internal to `SmtpEmailSender` through a `MailMessage` record, so the public name and first signature stay compatible. `SmtpEmailSender`: MailKit + MimeKit, StartTls when `EnableSsl`, authenticate only with a username, connect and operation timeout from options. Registered only when mail is enabled; otherwise `NullEmailSender` (returns `Disabled`) is registered so callers never null-check.
|
||||
- **`EmailOptions`** (section `Email`): `FromAddress`, `FromName`, `LogoUrl` (optional, absolute or relative to `App:PublicBaseUrl`), `BrandColor` (optional `#rrggbb`), `AllowedFromAddresses` (array), `Smtp{Host, Port=587, EnableSsl=true, Username, Password, TimeoutSeconds=10}`. `App:PublicBaseUrl`, `App:DefaultLanguage` (nl|en, default nl). Validated at start when `Smtp:Host` is set: `FromAddress` valid and in `AllowedFromAddresses` (or the list is exactly that one address by default), https or localhost base URL without path, logo and colour well-formed, port 1..65535, timeout 1..60.
|
||||
- **`MailSendResult`**: `Sent` bool plus `ErrorCode` (`disabled`, `not_configured`, `timeout`, `auth_failed`, `rejected`, `unknown`). No exception text, no addresses beyond the recipient domain in logs.
|
||||
- **`IMailTemplateRenderer`**: `Render(MailKind kind, string language, MailModel model)` returns subject, HTML and text. One shared layout (inline CSS, tables, brand colour and optional logo, button plus raw link, footer). Resource dictionaries in code, one class per language, missing key falls back to `nl`. All dynamic values HTML-encoded; subject and display names reject CR/LF. Kinds: `Invitation`, `NewInvitationLink`, `PasswordReset`, `AccountDeactivated`, `AccountReactivated`, `RoleChanged`.
|
||||
- **`ILanguageResolver`**: `Resolve(string? userLanguage)` returns `nl`/`en` using user preference, then `App:DefaultLanguage`, then `nl`.
|
||||
- **`ISiteSettingsService`**: `GetMailAsync()` returns stored `FromAddress`/`FromName` or the configured defaults plus the allowlist; `SetMailAsync(address, name, actor)` validates (address must be in `AllowedFromAddresses`, name 1..80, no control characters) and stores. Table `SiteSettings` (one row, id fixed to 1).
|
||||
- **`IIdentityMailService`**: `SendInvitationAsync(invitation, token, isNewLink)`, `SendPasswordResetAsync(user, token)`, `SendDeactivatedAsync/ReactivatedAsync/RoleChangedAsync(user, ...)`. Each builds the link from `PublicBaseUrl + "/admin" + path`, resolves language, renders, sends through `IEmailSender`, catches everything at the boundary, logs `identity_mail_sent`/`identity_mail_failed` (recipient domain, kind, error code) and returns `MailSendResult`. It never throws into the caller.
|
||||
- **`ResetCooldown`**: singleton, `bool TryEnter(string normalizedAddress)`; one entry per address per 5 minutes; bounded memory (entries purged on access, hard cap) so it cannot grow without limit.
|
||||
|
||||
### Identity module
|
||||
- **`UsersController`** (existing): `POST invite` accepts optional `language`, returns `{ inviteLink, mail }`. `POST {id}/regenerate-invite` returns `{ inviteLink, mail }`. New `POST {id}/resend-invite`: resends the current link, or regenerates first when expired; same hierarchy as the other invitation actions (`UserManagementRules`). `PUT {id}/active` and `PUT {id}/role` send the notice after success (a failure of the mail never fails the action). `PUT me` accepts `language`. `UserDto`/`UserResponse` gain `language`.
|
||||
- **`AuthController`** (existing): `POST auth/forgot-password {email}` anonymous, rate limited by the existing `login` limiter, identical 202 for every outcome, mail only when the account exists, is active and the cooldown allows. `POST auth/reset-password {email, token, newPassword}` anonymous, `login` limiter, validates through `UserManager.ResetPasswordAsync`; success revokes all refresh tokens (completion only); any failure answers one generic 400.
|
||||
- **`SiteSettingsController`**: `GET SiteSettings/mail` (Owner, Administrator), `PUT SiteSettings/mail` (Owner only). Response includes the allowlist so the UI offers only allowed choices.
|
||||
- **System capabilities** (existing `SystemController`): adds `emailEnabled` and `defaultLanguage`.
|
||||
|
||||
### Frontend
|
||||
Settings: "Mail" card (Owner edits: allowed address select + display name; Administrator sees it read-only). Profile: language select (nl/en, "default" option), applied immediately and saved. Invite dialog: language select (default = site default), shows the mail result with the copy-link fallback. Users list: resend action for pending invitations. Login: "Wachtwoord vergeten?" when `emailEnabled`; new pages `/forgot-password` and `/reset-password`. Everything hidden or unchanged when `emailEnabled` is false.
|
||||
|
||||
## 2. Data model (all additive)
|
||||
| Change | Detail |
|
||||
|---|---|
|
||||
| `SiteSettings` (new table) | `Id` int PK (always 1), `MailFromAddress` varchar(256) null, `MailFromName` varchar(80) null, `UpdatedAt`, `UpdatedBy` varchar(256) null |
|
||||
| `Users.PreferredLanguage` | varchar(8) null |
|
||||
| `Invitations.Language` | varchar(8) null |
|
||||
Down migrations drop exactly these. No data is rewritten; existing rows read as null (= site default).
|
||||
|
||||
## 3. Key flows
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant A as Administrator
|
||||
participant U as UsersController
|
||||
participant M as IdentityMailService
|
||||
participant S as SmtpEmailSender
|
||||
A->>U: POST Users/invite
|
||||
U->>U: create invitation (existing)
|
||||
U->>M: SendInvitationAsync
|
||||
M->>S: SendAsync
|
||||
S-->>M: sent or error code
|
||||
M-->>U: MailSendResult
|
||||
U-->>A: inviteLink and mail result
|
||||
```
|
||||
Text alternative: the invitation is created first; the mail result (sent or error code) is returned together with the copyable link, so a mail failure never loses the invitation.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant V as Visitor
|
||||
participant AU as AuthController
|
||||
participant C as ResetCooldown
|
||||
participant M as IdentityMailService
|
||||
V->>AU: POST forgot-password
|
||||
AU->>C: TryEnter(address)
|
||||
AU->>M: SendPasswordResetAsync (only if user active and allowed)
|
||||
AU-->>V: 202 neutral (always the same)
|
||||
V->>AU: POST reset-password with token
|
||||
AU->>AU: ResetPasswordAsync (stamp changes, token single-use)
|
||||
AU->>AU: revoke all refresh tokens (completion only)
|
||||
AU-->>V: 200 or generic 400
|
||||
```
|
||||
Text alternative: requesting a reset only sends a mail and changes nothing else; revoking sessions happens only when a new password is actually set.
|
||||
|
||||
## 4. Design decisions and open choices
|
||||
- **Reset does not touch sessions on request (Bryan's rule).** `forgot-password` writes nothing except the in-memory cooldown. Tests prove: password hash, security stamp, access token and refresh tokens are unchanged after a request; after a completed reset refresh tokens are revoked, the old password fails, the token fails a second time.
|
||||
- **D1 invitation language (choice, default proposed):** the administrator picks nl/en in the invite dialog (default = site default); stored on the invitation, copied to the new account's `PreferredLanguage` on completion. Alternative: always site default, no field. Default proposal = the picker.
|
||||
- **D2 access tokens after a completed reset (choice, recommended: yes):** a reset or password change updates the security stamp, but today's access tokens stay valid until they expire (up to 60 minutes). Recommended: put the stamp in the access token and compare it in `ActiveUserTokenValidation`, so a completed reset (or password change) ends all sessions immediately. Cost: tokens issued before the deploy lack the claim and are refused once (refresh silently re-issues them). Alternative: leave access tokens to expire. This also closes the old gap that a password change did not end other sessions.
|
||||
- **D3 sender envelope.** When a site changes its sender in the settings, the mail uses that address in `From`; the SMTP envelope sender stays the SMTP account's own address (set by the server), which is what SPF checks. The `From` domain must therefore be aligned (SPF and DKIM) for DMARC, which is why the allowlist is mandatory and the check is in the Operations checklist.
|
||||
- **D4 logo and colour in mail** come from `Email:LogoUrl` / `Email:BrandColor` per site configuration (the backend does not know the frontend theme). ASF test sets the logo to `/admin/brand-logo-on-light.png`.
|
||||
- **D5 message of the capability flag**: a host without mail configuration reports `emailEnabled: false`; every new UI element is hidden and every endpoint that would send answers as today.
|
||||
- **D6 timeouts**: sending happens inside the request (Q8 A), so `TimeoutSeconds` bounds it; a timeout is reported as `timeout` and the fallback link is shown.
|
||||
|
||||
## 5. Property-based test targets (partial PBT)
|
||||
- **PBT-02 round trip**: link builder and parser: token encode then decode returns the token for any token; `forgot`/`reset` link query round trip.
|
||||
- **PBT-03 invariants**: rendered HTML never contains an unencoded `<`/`"` from any display name or link; subject never contains CR/LF whatever the input; allowlist validator never accepts an address outside the list; cooldown never allows two sends within the window for one address.
|
||||
- **PBT-07/08/09**: generators for tokens, display names (including control characters, unicode, very long) and addresses; seeds logged and shrinking kept on; FsCheck.Xunit (already referenced in Core.Tests).
|
||||
|
||||
## 6. Security Baseline check of the design
|
||||
SECURITY-03 (no PII/tokens/links in logs), 05 (all inputs validated, bounded), 08 (role checks; Owner-only settings write), 09 (no committed credentials, options validated at start), 11 (mail failure isolated, copy-link fallback), 12 (single-use time-limited tokens, uniform responses, revocation only on completion), 13 (pinned MailKit/MimeKit, scan gate), 14 (sent/failed events, alert in Operations), 15 (exceptions handled at the sender boundary): compliant by design. 01, 02, 04, 06, 07, 10: N/A or unchanged.
|
||||
+21
@@ -0,0 +1,21 @@
|
||||
# Units of Work - identity-email-notifications
|
||||
|
||||
Order: U1, then U2, then U3. Hand-back and approval after each unit. Each unit runs Code Generation with its own build and test; functional and NFR design are light and recorded in the unit's code summary.
|
||||
|
||||
## U1 mail-foundation
|
||||
- Core: `IEmailSender`, `SmtpEmailSender`, `NullEmailSender`, `EmailOptions` + start-up validation, `MailSendResult`, `IMailTemplateRenderer` + nl/en resources + shared layout, `ILanguageResolver`, fake sender for tests.
|
||||
- `SiteSettings` table + migration, `ISiteSettingsService`, `SiteSettingsController`, Mail card (Owner edits, Administrator reads), `emailEnabled` and `defaultLanguage` in system capabilities.
|
||||
- Config documentation (appsettings placeholders, env secrets `Email__Smtp__Username/Password`, smtp4dev), `Infrastructure Design` for the host.
|
||||
- Tests: option validation, sender behaviour with an in-process SMTP stub, renderer (encoding, header injection, fallback), settings (allowlist, roles), PBT-02/03/07/08/09 targets for renderer and validator.
|
||||
|
||||
## U2 identity-mail-flows
|
||||
- Migration: `Users.PreferredLanguage`, `Invitations.Language`. Profile language select; login applies the user's language.
|
||||
- `IIdentityMailService` and its use in invite, regenerate, new resend action, deactivate/reactivate and role change; response `mail` result; invite dialog language and result; resend action in the users list.
|
||||
- Tests: each mail kind with the fake sender; failure never fails the action; hierarchy for resend; language fallback chain; migration up/down on MariaDB; UI tests.
|
||||
|
||||
## U3 password-reset
|
||||
- `forgot-password` / `reset-password`, Identity default token provider (lifetime configurable, default 60 minutes), `ResetCooldown`, revocation of refresh tokens on completion only, stamp in access tokens (decision D2), login link, `/forgot-password` and `/reset-password` pages.
|
||||
- Tests: request leaves password, stamp and sessions untouched; completed reset revokes refresh tokens, old password fails, token single-use; identical responses for known and unknown addresses; cooldown; rate limiter wired; PBT for link round trip.
|
||||
|
||||
## Dependencies
|
||||
U2 needs U1 (sender, renderer, capabilities). U3 needs U1 and U2 (language column, mail service). No unit changes behaviour for a host without mail configuration.
|
||||
@@ -0,0 +1,51 @@
|
||||
# Execution Plan - identity-email-notifications
|
||||
|
||||
## Detailed analysis
|
||||
- **Request type**: New feature across shared Core, Identity and the admin frontend.
|
||||
- **Risk**: Medium-high. It handles SMTP credentials, links that grant account access, an anonymous endpoint, and three additive database changes that run on every host (SlpSoftware included).
|
||||
- **Depth**: Comprehensive. **Extensions**: Security Baseline (enforced), PBT partial (PBT-02, 03, 07, 08, 09). **Operations**: yes.
|
||||
- **Lane**: Feature.
|
||||
|
||||
## Stages
|
||||
| Stage | Run? | Reason |
|
||||
|---|---|---|
|
||||
| Workspace Detection | done | |
|
||||
| Reverse Engineering | skip | shared artifacts reused |
|
||||
| Requirements Analysis | done (approval pending) | |
|
||||
| User Stories | skip | one user type (administrators, plus the person who resets a password); acceptance criteria are in requirements.md |
|
||||
| Workflow Planning | this document | |
|
||||
| Application Design | run | new components (sender, templates, settings store, reset flow) |
|
||||
| Units Generation | run | three units with clear dependencies |
|
||||
| Functional Design | per unit, where noted below | mail rules, reset rules, language fallback |
|
||||
| NFR Requirements / NFR Design | per unit, light | security-driven (tokens, anonymity, timeouts) |
|
||||
| Infrastructure Design | U1 only | config keys, env secrets on the Pi, smtp4dev, SPF/DKIM alignment |
|
||||
| Code Generation | each unit | per-unit build and test |
|
||||
| Build and Test | once at the end | |
|
||||
| Operations | yes | deployment config, monitoring, production-readiness incl. SPF alignment |
|
||||
|
||||
## Units and order
|
||||
```mermaid
|
||||
flowchart LR
|
||||
U1["U1 mail-foundation<br/>sender, options, templates,<br/>SiteSettings + Mail card"] --> U2["U2 identity-mail-flows<br/>language per user, invitation,<br/>new link, resend, notices"]
|
||||
U2 --> U3["U3 password-reset<br/>forgot/reset, cooldown,<br/>session revocation on completion"]
|
||||
classDef u fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
class U1,U2,U3 u;
|
||||
```
|
||||
Text alternative: U1 (foundation) is built first, then U2 (flows that use it and the language column), then U3 (password reset, which needs both).
|
||||
|
||||
| Unit | Scope | Migration |
|
||||
|---|---|---|
|
||||
| U1 mail-foundation | `IEmailSender` + `SmtpEmailSender`, `EmailOptions` + start-up validation, template renderer + resources (nl, en), `SiteSettings` store + service + API + Mail card, `emailEnabled` and `defaultLanguage` in system capabilities, fake sender, smtp4dev docs | new table `SiteSettings` |
|
||||
| U2 identity-mail-flows | `PreferredLanguage` on users, `Language` on invitations, profile language select, invite dialog language and mail result, invitation / new-link / resend mails, deactivation, reactivation and role-change notices, resend action in the users list | columns `Users.PreferredLanguage`, `Invitations.Language` (nullable) |
|
||||
| U3 password-reset | `forgot-password` / `reset-password`, Identity token provider, cooldown, revocation of refresh tokens on completion only, access-token stamp check (decision D2), login link and two pages | none (token provider is stateless) |
|
||||
|
||||
All three migrations are additive, nullable (or new tables), with a working `Down`, and safe to run on SlpSoftware's database.
|
||||
|
||||
## Approval and delivery gates
|
||||
- Requirements and this design go to Bryan through "CMS & API" before any code (his rule for this feature).
|
||||
- Each unit is built and tested (per-unit build and test), hand-back after each unit.
|
||||
- Branch `feature/identity-email-notifications`; push and deploy to ASF test only with the relayed permission pattern used so far (branch push, `deploy_asf_test`; no merge, no SLP Software, no production).
|
||||
- A real test mail to an address of Bryan from the test host is part of acceptance (Operations).
|
||||
|
||||
## Success criteria
|
||||
Mail disabled = behaviour unchanged (all existing tests green). Mail enabled = every mail kind sent correctly with a fake sender; failures never fail an action; reset request never touches password or sessions; completed reset revokes them; sender address only from the allowlist; no secrets in logs or messages.
|
||||
+165
@@ -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]: 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?
|
||||
|
||||
- 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]: 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?
|
||||
|
||||
- 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]: 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.)
|
||||
|
||||
- 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]: 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?
|
||||
|
||||
- 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]: 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?
|
||||
|
||||
- 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]: 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)?
|
||||
|
||||
- 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]: 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?
|
||||
|
||||
- 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]: A (directly during the request).
|
||||
|
||||
## 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]: 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?
|
||||
|
||||
- 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]: 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?
|
||||
|
||||
- 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]: 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?
|
||||
|
||||
- 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]: A (IEmailSender + EmailOptions in Core, same shape as SimpleDeckApp, no shared code).
|
||||
|
||||
## 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]: 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?
|
||||
|
||||
- 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]: 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?
|
||||
|
||||
- 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]: A (Security extension on).
|
||||
|
||||
## 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]: B (PBT partial).
|
||||
|
||||
## 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]: A (Operations phase yes).
|
||||
+108
@@ -0,0 +1,108 @@
|
||||
# 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 (changed by Bryan, 2026-11-08: soft).** When an SMTP host is set: valid `FromAddress`/`FromName`, a port in range, credentials as a pair, and an absolute https (or localhost) `App:PublicBaseUrl` without a path. If anything is missing or invalid the host STILL starts, mail stays OFF (`emailEnabled=false`) and one Error log line names each setting (names only, no values, no secrets).
|
||||
- **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.
|
||||
|
||||
### Decisions on P1-P5 (Bryan, relayed 2026-11-08) - these override the proposal text above where they differ
|
||||
- **P1 approved**: build the `SiteSettings` store with the mandatory allowlist `Email:AllowedFromAddresses`. Only an Owner changes it; an Administrator reads it. A "Mail" card on the Settings page. Default when nothing is set: `Email:FromAddress`.
|
||||
- **P2 approved, with a rule**: sessions and refresh tokens are revoked only AFTER a new password has been chosen (a completed reset). Requesting a reset must not touch the existing password, sessions or refresh tokens. This is a hard requirement (FR-07a) with tests: request -> password unchanged, existing access token and refresh token still work; completed reset -> all refresh tokens revoked, old password rejected, reset token unusable a second time.
|
||||
- **P3 changed to per user, now**: a nullable `PreferredLanguage` column on the user (additive migration, values `nl`/`en`), chosen in the profile. Fallback chain: user preference, else the site default `App:DefaultLanguage` (default `nl`). For an invitee without an account: the administrator may choose a language when inviting (stored on the invitation, copied to the new account); without a choice the site default applies (design decision D1, see application design). The password-reset mail uses the user's preference, then the site default.
|
||||
- **P4 approved**: in-memory cooldown, one reset mail per address per 5 minutes, silently ignored with the identical response.
|
||||
- **P5 approved**: no stored mail status; result in the response plus a resend action.
|
||||
- **Operations checklist item (production)**: the sender domain must be aligned: SPF of the sender domain must authorise the SMTP service that actually sends, and that service must DKIM-sign for that domain. See section 7; carried into the Operations plan.
|
||||
|
||||
## 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.
|
||||
+25
@@ -0,0 +1,25 @@
|
||||
# Deployment instructions - turning mail on for a host
|
||||
|
||||
For whoever manages the host (Pi-Main). Do this per host and per environment; credentials never go into the repository, a chat or a ticket.
|
||||
|
||||
## Before you start
|
||||
- The release containing the mail feature is already deployed (a host without mail settings behaves exactly as before).
|
||||
- You have: the SMTP host and port, the account (username, password) that may send as the chosen sender address, the public https address of the site (no path).
|
||||
|
||||
## Steps
|
||||
1. Open the host's environment file (Pi: `~/apps/<site>/<env>/shared/env`, mode 600).
|
||||
2. Add, in one go (the order inside the file does not matter, but set `App__PublicBaseUrl` together with the host or the host starts with mail off):
|
||||
- `App__PublicBaseUrl=https://<site address>`
|
||||
- `Email__Smtp__Host=<smtp host>`, `Email__Smtp__Port=587`, `Email__Smtp__EnableSsl=true`
|
||||
- `Email__Smtp__Username=<account>`, `Email__Smtp__Password=<password>`
|
||||
- ASF: `Email__FromAddress=no-reply@andreaslop.nl`, `Email__AllowedFromAddresses__0=no-reply@andreaslop.nl`, `Email__FromName=Andrea Slop Fotografie` (SlpSoftware: nothing more is needed)
|
||||
3. Restart the unit (Pi: `systemctl --user restart <unit>`).
|
||||
4. Read the journal (Pi: `journalctl --user -u <unit> -n 50`):
|
||||
- success: a line `mail_status enabled=true smtp_host=... starttls=true default_from_domain=...`;
|
||||
- a line `mail_configuration_invalid ... <setting names>` (Error): mail stays OFF, the site runs; fix the named settings and restart.
|
||||
5. `curl https://<site>/api/v1/System/capabilities` shows `"emailEnabled":true`.
|
||||
6. Real test (Bryan): in the admin invite a mailbox of yours (Gmail and Outlook, see the readiness checklist); the dialog says "mail sent" or names the reason. Also try "Wachtwoord vergeten?" on the login page.
|
||||
7. If a mail is refused, the journal line `identity_mail_failed code=... detail=... phase=... timings=...` tells what happened (`rejected_sender`: the account may not send as that address; `auth_failed`: wrong credentials; `tls_failed`: STARTTLS problem; `timeout_*`: slow or blocked server). Settings to change: see the infrastructure design.
|
||||
|
||||
## Changing or removing mail later
|
||||
Edit the same file and restart. To switch mail off: delete `Email__Smtp__Host` (the copy-link flow keeps working) and restart.
|
||||
+37
@@ -0,0 +1,37 @@
|
||||
# Deployment plan - identity-email-notifications
|
||||
|
||||
Decisions (Operations questions, answered by Bryan via "CMS & API"): Q1 A, Q2 A (with the ASF production exception below), Q3 A, Q7 A.
|
||||
|
||||
## Method
|
||||
The code ships through the existing Gitea Actions pipeline (`deploy_asf_test`, `deploy_test`; production only with its own approval). Nothing in the workflow changes. The mail settings are NOT part of the deploy: Pi-Main sets them by hand in the host's `shared/env` (mode 600), because they contain credentials.
|
||||
|
||||
## Order
|
||||
1. ASF test (code live; mail settings in `shared/env`, real test mail pending).
|
||||
2. SlpSoftware test (code live since run 625/626; mail still off until its `shared/env` has the settings).
|
||||
3. SlpSoftware production, only after steps 1 and 2 are accepted and with Bryan's separate approval.
|
||||
4. **ASF production is not part of this feature**: it does not exist yet and will run on an IIS server instead of a Raspberry Pi. It becomes its own piece of work (see "Open point: ASF production on IIS" below).
|
||||
|
||||
## Per-host mail settings (all in that host's environment)
|
||||
| Host | `Email__Smtp__Host` | Sender | Notes |
|
||||
|---|---|---|---|
|
||||
| ASF test | `mail.andreaslop.nl`, port 587, `EnableSsl=true` | `no-reply@andreaslop.nl` in `Email__FromAddress` and `Email__AllowedFromAddresses__0` | account on that server created by Bryan; TLS mode (STARTTLS on 587) to be confirmed by the first real test mail |
|
||||
| SlpSoftware test | `mail.slpsoftware.nl`, 587, `EnableSsl=true` | default `no-reply@slpsoftware.nl` (no variable needed) | credentials of the account that may send as that address |
|
||||
| SlpSoftware production | same server as test | same | own environment, own `App__PublicBaseUrl` |
|
||||
|
||||
Common: `Email__Smtp__Username`, `Email__Smtp__Password`, `App__PublicBaseUrl` (https, no path, per environment), optional `Email__Smtp__TimeoutSeconds` (default 10 per step), `Email__FromName`. Full list: `construction/mail-foundation/infrastructure-design/infrastructure-design.md`.
|
||||
|
||||
## Master host: `MasterModule__MasterUrl` is required (test and production)
|
||||
On every host that runs the master module (SlpSoftware test, SlpSoftware production), set `MasterModule__MasterUrl` to the public address of that master: **https, no path**, e.g. `https://master.example.com`. The shipped `appsettings.json` carries only a placeholder (`<public-url-of-this-master-instance>`).
|
||||
- **Why:** the hourly integrity check (and the one at start-up) runs without a request, so it cannot derive the address from the request and uses this setting. With the placeholder it used to re-register the slaves with the placeholder, after which a slave could not poll the master any more (`master_poll_failed`). Now a missing or unusable value makes the master log `MasterModule:MasterUrl is not an absolute http(s) address` and skip those background checks; nothing is overwritten.
|
||||
- **Slaves** (ASF test, later ASF production) need no such variable: they store the address the master registers. A slave refuses an unusable address (`400 invalid_master_url`) and the poller logs `invalid_master_url`.
|
||||
- **Recovery** of a slave that holds a bad address: set the variable on the master and restart it; the start-up check re-registers the slave. A changed variable needs a restart.
|
||||
|
||||
## Open point: ASF production on IIS (decided 2026-11-09, not designed here)
|
||||
Everything in this feature's and the andreaslop-site-hosting documents that talks about the host assumes the Raspberry Pi: a systemd user unit (`andreaslopfotografie-test`), an `EnvironmentFile` named `shared/env` (mode 600, readable only by the service user), `journalctl` for logs, `systemctl --user restart` after a change, `deploy-scp.yaml` (scp + symlink `current` + restart), a reverse-proxy Pi in front, and Linux paths. For an IIS host these assumptions need an answer in the later ASF-production feature (listed, NOT worked out now):
|
||||
- **Environment variables**: the same variable names work (double underscore), but are set in `web.config` (`<aspNetCore><environmentVariables>`), as machine-level variables or per app pool, not in `shared/env`. Secrets: no file mode 600, so decide where the SMTP credentials live (ACL-protected `web.config` section or machine variables, never in the repository) and who may read them.
|
||||
- **Restart**: an app pool recycle or `app_offline.htm` instead of `systemctl restart`; a changed variable needs a recycle.
|
||||
- **Logs**: stdout logging to a file or the Windows event log instead of `journalctl`; the `mail_status`, `mail_configuration_invalid` and `identity_mail_failed` lines must be reachable there (and Sentry keeps working as is).
|
||||
- **Deployment**: the scp-plus-symlink workflow does not fit; another deploy path is needed (Web Deploy, or file copy into a release folder with a physical-path switch), with the same previous-release rollback idea.
|
||||
- **Hosting model**: ASP.NET Core module (in-process or out-of-process), the .NET runtime on the server, HTTPS binding and certificate on IIS itself (no reverse-proxy Pi), `ForwardedHeaders__KnownProxies` probably different or unnecessary, `ASPNETCORE_ENVIRONMENT`.
|
||||
- **Database and mail server**: where MariaDB lives for that host, and whether `mail.andreaslop.nl` is reachable from the IIS server (firewall, port 587).
|
||||
- **Health check**: the `/health` URL check of the workflow is fine; the way it is reached changes with the new hostname.
|
||||
+9
@@ -0,0 +1,9 @@
|
||||
# Rollback plan - identity-email-notifications
|
||||
|
||||
Decision (Q7 A).
|
||||
|
||||
1. **Switch mail off quickly** (no code change): remove `Email__Smtp__Host` from the host's environment file and restart the unit. The admin hides every mail feature (`emailEnabled=false`), invitations work by copying the link, the two anonymous endpoints answer 404. Nothing is lost.
|
||||
2. **Bad release**: use the existing previous-release switch of the deploy (re-point `current` to the previous release and restart; see the andreaslop-site-hosting rollback plan for the Pi). The three database changes of this feature (`SiteSettings` table, `Users.PreferredLanguage`, `Invitations.Language`) are additive and nullable; the previous code simply ignores them, so no database change is needed to go back.
|
||||
3. **After a rollback of the code**: access tokens issued by the newer release carry a security-stamp claim that the old code ignores; they keep working. Tokens issued by the old code lack the claim and are refused once by a newer release (the silent refresh fixes that).
|
||||
4. A documented way to drop the new columns and table is deliberately not part of the plan (Bryan chose option A); it would only be needed for a full restore.
|
||||
5. IIS (later, ASF production): the same two switches exist in another form (remove the variable and recycle the app pool; keep the previous release folder and switch the physical path).
|
||||
+23
@@ -0,0 +1,23 @@
|
||||
# Monitoring plan - identity-email-notifications
|
||||
|
||||
Decisions (Q4 B, Q5 A): journal plus Sentry on the existing tooling; no new dashboards; no threshold rule.
|
||||
|
||||
## Signals (structured log events, never with credentials, addresses, tokens or links)
|
||||
| Event | Level | When | Meaning |
|
||||
|---|---|---|---|
|
||||
| `mail_status enabled=true|false ...` | Information | every start | whether mail is on, with SMTP host, port, STARTTLS and the default sender DOMAIN |
|
||||
| `mail_configuration_invalid: ... {settings}` | **Error** | start, once | an SMTP host is set but the configuration is incomplete or invalid: mail stays OFF; names the settings |
|
||||
| `identity_mail_failed code=auth_failed / rejected_sender / tls_failed / not_configured` | **Error** | per failed mail | configuration problem, somebody has to fix it (wrong credentials, a sender the account may not use, TLS, no host) |
|
||||
| `identity_mail_failed code=timeout_* / rejected_recipient / rejected / connection_failed / unknown` | Warning | per failed mail | passes by itself or concerns one message; journal and breadcrumbs only |
|
||||
| `identity_mail_sent kind=... recipient_domain=...` | Information | per sent mail | volume, no address |
|
||||
| `password_reset_request_ignored`, `password_reset_completed`, `password_reset_request_failed` | Information / Warning | reset flow | cooldown hits, completed resets |
|
||||
|
||||
## Alerting (Sentry, existing project of each site, notification by e-mail to the project owner)
|
||||
Sentry turns Error events into issues. Create one rule per environment (test and production) in the site's Sentry project:
|
||||
- **Rule "mail configuration problem"**: when an issue is created or reopened and its message contains `identity_mail_failed` or `mail_configuration_invalid` (level Error), notify the project owner by e-mail. No frequency threshold (Q4 B).
|
||||
Nothing else: timeouts and recipient problems are not alerted.
|
||||
|
||||
## Where to look
|
||||
- Pi: `journalctl --user -u <unit> | grep -E "mail_status|identity_mail_|mail_configuration_invalid"`.
|
||||
- IIS (later): the stdout log or the event log of the app pool (to be settled in the ASF-production work).
|
||||
- Sentry: issues filtered on `environment:<test|production>`.
|
||||
+13
@@ -0,0 +1,13 @@
|
||||
# Monitoring setup - identity-email-notifications
|
||||
|
||||
## Done in code (this feature)
|
||||
- The log level follows the kind of failure: Error for configuration problems (`auth_failed`, `rejected_sender`, `tls_failed`, `not_configured`), Warning for the rest, so Sentry alerts only when somebody has to act. Tested (`SmtpSenderDiagnosticsTests`: wrong login and refused sender are Error events, refused recipient and timeouts stay Warning; level mapping for every code; no secret in any line).
|
||||
- A start-up line states whether mail is on, and an Error names every missing or invalid setting when it is not.
|
||||
|
||||
## To be done by a person (the assistant does not change shared Sentry projects)
|
||||
1. In the Sentry project of ASF (environment `test`) and of SlpSoftware (environments `test`, later `production`): create the issue-alert rule of the monitoring plan (message contains `identity_mail_failed` or `mail_configuration_invalid`, notify the owner by e-mail). The `sentry:sentry-create-alert` skill can create it on request, with Bryan's go.
|
||||
2. Check once per host after switching mail on: the journal shows `mail_status enabled=true`.
|
||||
3. Trigger the alert once on test (for example a wrong password in `shared/env` for a minute) to see that the e-mail arrives; restore the password.
|
||||
|
||||
## Runbook lines (Q5 A)
|
||||
After any change of mail settings: restart, read the journal for `mail_status enabled=true` or `mail_configuration_invalid`, check `/System/capabilities` for `emailEnabled`.
|
||||
+65
@@ -0,0 +1,65 @@
|
||||
# Operations questions - identity-email-notifications
|
||||
|
||||
Nothing here is executed until the questions are answered (through the "CMS & API" session). Context: mail is built and tested; it is live (switched on) on ASF test only once its sender address and TLS mode are settled, and off on SlpSoftware test until its host gets the settings. Production for both sites is not part of the current approval.
|
||||
|
||||
## Question 1: Rolling the mail settings out
|
||||
How do the mail settings reach each host?
|
||||
|
||||
- A) By hand by Pi-Main in the host's `shared/env` (mode 600), using the variable list in the infrastructure design (secrets stay out of Gitea); nothing in CI changes
|
||||
- B) The non-secret settings (`App__PublicBaseUrl`, `Email__FromName`, ...) come from Gitea variables written by the deploy workflow; only the SMTP credentials are set by hand
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (Bryan: by hand in shared/env)
|
||||
|
||||
## Question 2: Order of the roll-out
|
||||
- A) ASF test (done) then SlpSoftware test, each with its own SMTP host, then production of each site later, one at a time, each needing its own approval
|
||||
- B) ASF test, then straight to both productions together after the real test mails succeed
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A, BUT: ASF has no production environment yet and it will be an IIS server instead of a Raspberry Pi, so ASF production is a separate, later piece of work (not in this feature). Order now: ASF test, SlpSoftware test, then SlpSoftware production with its own approval.
|
||||
|
||||
## Question 3: The sender account for ASF
|
||||
- A) A dedicated mailbox/account on `mail.andreaslop.nl` (for example `no-reply@andreaslop.nl`) created by Bryan for this purpose; its address goes into `Email__FromAddress` and `Email__AllowedFromAddresses__0`
|
||||
- B) An existing mailbox of the site (for example `info@andreaslop.nl`), accepting that replies reach that mailbox
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (no-reply@andreaslop.nl on mail.andreaslop.nl)
|
||||
|
||||
## Question 4: Which mail problems should raise an alert
|
||||
Today a failed mail is logged at Warning level (journal only; Sentry sees Error events and uses Warnings only as breadcrumbs), and a bad mail configuration at start-up is an Error (Sentry sees it). What do you want?
|
||||
|
||||
- A) Nothing more: failed mails are looked at in the journal when somebody reports a problem
|
||||
- B) Raise the log level to Error (so Sentry sends an alert to Bryan) for mail failures that point to a configuration problem: `auth_failed`, `rejected_sender`, `tls_failed`, `not_configured`; keep timeouts and recipient problems at Warning
|
||||
- C) B, plus an alert when the same host fails at least three mails in fifteen minutes whatever the reason (a Sentry rule on the events)
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: B (configuration-related mail failures auth_failed, rejected_sender, tls_failed, not_configured at Error level so Sentry alerts; timeouts and recipient problems stay Warning; no threshold rule)
|
||||
|
||||
## Question 5: Start-up check after a release
|
||||
- A) The deploy's existing `/health` check stays as it is; after changing mail settings the person doing it reads the journal for `mail_status enabled=true` or `mail_configuration_invalid` (written in the runbook)
|
||||
- B) A) plus the CMS reports `emailEnabled` on `/health` details so a pinger can see that mail is off on a host that should have it
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (runbook line plus the journal)
|
||||
|
||||
## Question 6: Deliverability (SPF, DKIM, DMARC) before production
|
||||
Facts today: both `slpsoftware.nl` and `andreaslop.nl` have SPF (`a mx include:smtp.spf.ziggo.nl`), a `dkim` record and DMARC `p=none`.
|
||||
- A) Before production: send test mails to a Gmail and an Outlook mailbox, check in "show original" that SPF, DKIM and DMARC pass and are aligned with the From domain; leave DMARC at `p=none` for now and revisit it later
|
||||
- B) A), and tighten DMARC to `p=quarantine` for the site's domain before production
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (test mails to Gmail and Outlook, DMARC stays p=none for now)
|
||||
|
||||
## Question 7: Rollback
|
||||
Rolling a release back keeps the three additive database changes (older code simply ignores the new columns and table).
|
||||
- A) To switch mail off quickly: remove `Email__Smtp__Host` from `shared/env` and restart the unit (the copy-link flow keeps working); for a bad release use the existing previous-release switch of the deploy
|
||||
- B) A), and additionally a documented way to drop the new columns/table (only if a restore is ever needed)
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (mail off by removing Email__Smtp__Host and restarting; release rollback through the previous-release switch)
|
||||
|
||||
## Question 8: Who approves production readiness for this feature
|
||||
- A) Bryan, after the real test mails on ASF test and SlpSoftware test and the answers above are carried out
|
||||
- X) Other (please describe after [Answer]: tag below)
|
||||
|
||||
[Answer]: A (Bryan approves after the real test mails on ASF test and SlpSoftware test)
|
||||
+42
@@ -0,0 +1,42 @@
|
||||
# Production Readiness Checklist - identity-email-notifications
|
||||
|
||||
Scope: ASF test and SlpSoftware test now; SlpSoftware production after Bryan's approval. ASF production is outside this feature (no environment yet; it will be an IIS server).
|
||||
|
||||
## Deployment
|
||||
- **Status**: Configured (documented, no workflow change)
|
||||
- **Method**: existing CI/CD for the code; mail settings by hand in each host's environment file (Q1 A)
|
||||
- **Rollback Plan**: Yes (`deployment/rollback-plan.md`: remove the SMTP host and restart; previous-release switch; additive migrations)
|
||||
|
||||
## Monitoring
|
||||
- **Status**: Configured in code (log levels), alert rule documented and still to be created in Sentry by a person
|
||||
- **Approach**: journal plus Sentry Error events for configuration-related mail failures; no threshold, no dashboard (Q4 B)
|
||||
|
||||
## Master host setting (added 2026-11-10)
|
||||
- **`MasterModule__MasterUrl` is required on every master host** (SlpSoftware test and production): https, no path. The shipped `appsettings.json` only holds a placeholder. Without a valid value the master logs `MasterModule:MasterUrl is not an absolute http(s) address` and skips its background checks (before the fix it overwrote slaves with the placeholder and their polls failed). The variable is NOT `Master__MasterUrl`. Production readiness item: set and verify it, then restart the master and watch the slaves' `master_poll_recovered`.
|
||||
|
||||
## Additional Readiness Items
|
||||
- **Deliverability (Q6 A)**, before SlpSoftware production: send test mails to a Gmail and an Outlook mailbox and check in "show original" that SPF, DKIM and DMARC pass and are ALIGNED with the From domain (the From domain, the SPF-authorised server and the DKIM signing domain must match); DMARC stays `p=none` for now. Facts at 2026-11-08: both `slpsoftware.nl` and `andreaslop.nl` publish `v=spf1 a mx include:smtp.spf.ziggo.nl ~all`, a `dkim._domainkey` record and DMARC `p=none`. For ASF the sender `no-reply@andreaslop.nl` through `mail.andreaslop.nl` is expected to align (the host is the domain's own `a`/`mx`); to be proven by the real test mail.
|
||||
- **Real test mails (Q8 A)**: one per site on test (invitation, new link by mail, password reset, a notice) to an address of Bryan; the approval of this feature depends on them.
|
||||
- **Secrets Management**: Pass by design. SMTP credentials only in each host's environment file (mode 600), never in the repository, a chat or the logs (tested: no credential, address, token or link in any log line).
|
||||
- **Backups**: the new table `SiteSettings` and the two new columns are in the existing databases and so in the existing backups. Nothing new to back up.
|
||||
- **Runbook/Support Handover**: Yes: `deployment/deployment-instructions.md` (turning mail on, reading the journal), `deployment/rollback-plan.md`, `monitoring/monitoring-setup.md`, the infrastructure design (variables, SMTP modes, how to read a failure).
|
||||
- **Alert Ownership**: Bryan (Sentry e-mail as project owner); fixing with the CMS & API and Pi-Main sessions.
|
||||
|
||||
## .NET Appsettings Compliance
|
||||
- **Three-file pattern present**: Yes (unchanged; the mail section was added to the committed `appsettings.json` of the ASF and SlpSoftware hosts).
|
||||
- **No committed secrets**: Pass. Smtp host, username and password are empty in the committed files (a test asserts it for the ASF host); the committed sender default is a placeholder-style address, not a credential.
|
||||
- **`appsettings.local.json` gitignored**: Yes.
|
||||
- **Production secrets wired to env vars/secrets manager**: Yes: `Email__Smtp__Username/Password` in the host's environment file (Pi). For IIS see the open point.
|
||||
|
||||
## Open Points
|
||||
1. **ASF production on IIS** (decided 2026-11-09): not worked out here. The Pi-specific assumptions (systemd unit, `shared/env`, journalctl, scp deploy, reverse-proxy Pi) and what changes on IIS are listed in `deployment/deployment-plan.md`; a later ASF-production feature must settle them (environment variables and secrets, restart, logs, deploy path, hosting model, database and mail-server reachability).
|
||||
2. Sentry alert rule to be created (monitoring setup).
|
||||
3. Real test mails on ASF test and SlpSoftware test.
|
||||
4. Merge to master / SlpSoftware production: not approved yet (the branch is already on ASF test and SlpSoftware test). Bryan first tests both test environments including run 635 (65ee73f: logout hang, mail card gutter); the merge then happens on his explicit go.
|
||||
5. Per-site DMARC tightening later (stays `p=none` now).
|
||||
6. Confirm the dark-mode mail card in the Gmail app (Gmail and non-Gmail account) and Outlook with a real test mail; the layout uses inline styles and Outlook selectors but the clients' own colour conversion cannot be tested in code.
|
||||
7. Decisions left to Bryan (not built): own rate-limit policy for `Setup/status`, judging the admin token only on a real block (log noise), a visible error state with "Reload" and a fetch timeout; the contact-feature gate change is in `features/contact-feature/contact-feature-prereqs.md`.
|
||||
8. CI of run 635 (65ee73f) was not confirmed green when this was written.
|
||||
|
||||
## Overall Readiness
|
||||
- **Ready for Production**: Not yet. SlpSoftware production needs the real test mails, the alert rule and Bryan's approval; ASF production is a separate piece of work.
|
||||
@@ -45,3 +45,12 @@ VITE_UMAMI_WEBSITE_ID=
|
||||
# VITE_API_BASE_URL=https://localhost:7223
|
||||
# VITE_APP_TITLE=SlpModularCms (SlpSoftware)
|
||||
# and run `pnpm dev:slpsoftware` (uses --mode slpsoftware, port 5175) instead of `pnpm dev`.
|
||||
|
||||
# --- Local SlpModularCms.Api.AndreaSlopFotografie dev setup (themed admin) ---
|
||||
# Copy this file to `.env.asf.local` with:
|
||||
# VITE_API_BASE_URL=https://localhost:7200
|
||||
# VITE_APP_TITLE=Andrea Slop Fotografie
|
||||
# VITE_THEME=asf
|
||||
# VITE_DEFAULT_LANGUAGE=nl
|
||||
# and run `pnpm dev:asf` (uses --mode asf, port 5176). VITE_THEME selects frontend/themes/<name>
|
||||
# (unset = the default look); VITE_DEFAULT_LANGUAGE ('nl' | 'en') applies until a user picks a language.
|
||||
|
||||
@@ -7,6 +7,7 @@
|
||||
"dev": "vite",
|
||||
"dev:slave": "vite --mode slave --port 5174",
|
||||
"dev:slpsoftware": "vite --mode slpsoftware --port 5175",
|
||||
"dev:asf": "vite --mode asf --port 5176",
|
||||
"dev:all": "concurrently -n master,slave -c blue,magenta \"pnpm dev\" \"pnpm dev:slave\"",
|
||||
"build": "tsc -b && vite build",
|
||||
"lint": "eslint .",
|
||||
@@ -21,6 +22,8 @@
|
||||
"@dnd-kit/core": "^6.3.1",
|
||||
"@dnd-kit/sortable": "^10.0.0",
|
||||
"@dnd-kit/utilities": "^3.2.2",
|
||||
"@fontsource/jost": "5.3.0",
|
||||
"@fontsource/marcellus": "5.3.0",
|
||||
"@hookform/resolvers": "^5.4.0",
|
||||
"@radix-ui/react-dialog": "^1.1.17",
|
||||
"@radix-ui/react-dropdown-menu": "^2.1.18",
|
||||
@@ -29,7 +32,7 @@
|
||||
"@radix-ui/react-slot": "^1.3.0",
|
||||
"@sentry/react": "^10.68.0",
|
||||
"@tanstack/react-query": "^5.101.0",
|
||||
"@tanstack/react-router": "^1.170.16",
|
||||
"@tanstack/react-router": "^1.170.46",
|
||||
"class-variance-authority": "^0.7.1",
|
||||
"clsx": "^2.1.1",
|
||||
"i18next": "^26.3.1",
|
||||
@@ -41,7 +44,7 @@
|
||||
"react-i18next": "^17.0.8",
|
||||
"sonner": "^2.0.7",
|
||||
"tailwind-merge": "^3.6.0",
|
||||
"zod": "^4.4.3"
|
||||
"zod": "^4.6.6"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@eslint/js": "^10.0.1",
|
||||
|
||||
Generated
+58
-42
@@ -17,6 +17,12 @@ importers:
|
||||
'@dnd-kit/utilities':
|
||||
specifier: ^3.2.2
|
||||
version: 3.2.2(react@19.2.7)
|
||||
'@fontsource/jost':
|
||||
specifier: 5.3.0
|
||||
version: 5.3.0
|
||||
'@fontsource/marcellus':
|
||||
specifier: 5.3.0
|
||||
version: 5.3.0
|
||||
'@hookform/resolvers':
|
||||
specifier: ^5.4.0
|
||||
version: 5.4.0(react-hook-form@7.79.0(react@19.2.7))
|
||||
@@ -42,8 +48,8 @@ importers:
|
||||
specifier: ^5.101.0
|
||||
version: 5.101.0(react@19.2.7)
|
||||
'@tanstack/react-router':
|
||||
specifier: ^1.170.16
|
||||
version: 1.170.16(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
|
||||
specifier: ^1.170.46
|
||||
version: 1.170.46(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
|
||||
class-variance-authority:
|
||||
specifier: ^0.7.1
|
||||
version: 0.7.1
|
||||
@@ -78,8 +84,8 @@ importers:
|
||||
specifier: ^3.6.0
|
||||
version: 3.6.0
|
||||
zod:
|
||||
specifier: ^4.4.3
|
||||
version: 4.4.3
|
||||
specifier: ^4.6.6
|
||||
version: 4.6.7
|
||||
devDependencies:
|
||||
'@eslint/js':
|
||||
specifier: ^10.0.1
|
||||
@@ -380,6 +386,12 @@ packages:
|
||||
'@floating-ui/utils@0.2.11':
|
||||
resolution: {integrity: sha512-RiB/yIh78pcIxl6lLMG0CgBXAZ2Y0eVHqMPYugu+9U0AeT6YBeiJpf7lbdJNIugFP5SIjwNRgo4DhR1Qxi26Gg==}
|
||||
|
||||
'@fontsource/jost@5.3.0':
|
||||
resolution: {integrity: sha512-lORv5y49hSoLVxjGb0qNuBzXvnaNYI3B94200uGPGJFei8fao6d6LLz2ziWbOZubGfZnibzuT6GVNX8fBw8WQQ==}
|
||||
|
||||
'@fontsource/marcellus@5.3.0':
|
||||
resolution: {integrity: sha512-cMnanjpiPIC7Rq4GXIA/Zal5WLSoDV5Mc681tMkWsWfKHXnRnLGlhuGeBnLF6HrqtFkiSdiuy4NCSPfOrz266w==}
|
||||
|
||||
'@hookform/resolvers@5.4.0':
|
||||
resolution: {integrity: sha512-EIsqr/t/qbinPIhGjMdtvutIN1Kk4uwbROE9/UQ93CAVGR7GkA7Y92+fX80OzXi/OB67jVFYwKGO1WzkxmkFZw==}
|
||||
peerDependencies:
|
||||
@@ -1043,8 +1055,8 @@ packages:
|
||||
peerDependencies:
|
||||
vite: ^5.2.0 || ^6 || ^7 || ^8
|
||||
|
||||
'@tanstack/history@1.162.0':
|
||||
resolution: {integrity: sha512-79pf/RkhteYZTRgcR4F9kbk84P2N8rugQJswxfIqovlbRiT3yI7eBE+5QorIrZaOKktsgzRlXh1l/du/xpl4iA==}
|
||||
'@tanstack/history@1.162.5':
|
||||
resolution: {integrity: sha512-w1+YvwmTkwt5n8yUqEH3IWZ9DsmorCZW/EQ3KYHnqEgIkOZpH54NvW6/Epq3Dzb8H0ifIeYX8PExvrNLIH5FIA==}
|
||||
engines: {node: '>=20.19'}
|
||||
|
||||
'@tanstack/query-core@5.101.0':
|
||||
@@ -1055,25 +1067,25 @@ packages:
|
||||
peerDependencies:
|
||||
react: ^18 || ^19
|
||||
|
||||
'@tanstack/react-router@1.170.16':
|
||||
resolution: {integrity: sha512-w6eq1IJklujs1tESazaK/FxH0+H2l8vm/QPuu1cD3oRW/ubgKneQpd7b64ti/8gUyEimzimJQZDmJr6YHfP5+g==}
|
||||
'@tanstack/react-router@1.170.46':
|
||||
resolution: {integrity: sha512-ez1iNIhsPjGlaDHg3BXWs67EWVIYzB2tbopEHYDESdkO7owgkGb5de52+5Kv2v1fxdkggcNzo35bdk4arTVGQw==}
|
||||
engines: {node: '>=20.19'}
|
||||
peerDependencies:
|
||||
react: '>=18.0.0 || >=19.0.0'
|
||||
react-dom: '>=18.0.0 || >=19.0.0'
|
||||
|
||||
'@tanstack/react-store@0.9.3':
|
||||
resolution: {integrity: sha512-y2iHd/N9OkoQbFJLUX1T9vbc2O9tjH0pQRgTcx1/Nz4IlwLvkgpuglXUx+mXt0g5ZDFrEeDnONPqkbfxXJKwRg==}
|
||||
'@tanstack/react-store@0.11.2':
|
||||
resolution: {integrity: sha512-oj5O5DmiMWE+ih+SioX2ayC1kbK7d3fpLx0B75fPJr9nY3zU+hoW010yr64qXsY/9fyiLVE2bn5mGNV3owm8RQ==}
|
||||
peerDependencies:
|
||||
react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
|
||||
react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
|
||||
|
||||
'@tanstack/router-core@1.171.13':
|
||||
resolution: {integrity: sha512-+NOwEj1kO/6IGmpHRIZHasYxYWpyBQGNIZAST9aNrk9Q3YlU9SgqVnl1pbLa9qAKfeNdXQIRve0RQb/0kyDeDA==}
|
||||
'@tanstack/router-core@1.171.39':
|
||||
resolution: {integrity: sha512-qUhoJ0meuSUqGYQbHbcJYdASr06YtK+bulbj6vtrhKYFkLgkSsZ6tXmMyym7sFxiSJSPYgasgozrL01LyyR/6A==}
|
||||
engines: {node: '>=20.19'}
|
||||
|
||||
'@tanstack/store@0.9.3':
|
||||
resolution: {integrity: sha512-8reSzl/qGWGGVKhBoxXPMWzATSbZLZFWhwBAFO9NAyp0TxzfBP0mIrGb8CP8KrQTmvzXlR/vFPPUrHTLBGyFyw==}
|
||||
'@tanstack/store@0.11.2':
|
||||
resolution: {integrity: sha512-sJ4mjol8uQsHV0gOJzzjwXfh2Fwm+Sz0+8deqiTm4jGbMdjzNSW+xZCFm0kUa870uhd8yi+DpKnZb5Kc4apa0Q==}
|
||||
|
||||
'@testing-library/dom@10.4.1':
|
||||
resolution: {integrity: sha512-o4PXJQidqJl82ckFaXUeoAW+XysPLauYI43Abki5hABd853iMhitooc6znOnczgbTYmEP6U6/y1ZyKAIsvMKGg==}
|
||||
@@ -2016,15 +2028,15 @@ packages:
|
||||
engines: {node: '>=10'}
|
||||
hasBin: true
|
||||
|
||||
seroval-plugins@1.5.4:
|
||||
resolution: {integrity: sha512-S0xQPhUTefAhNvNWFg0c1J8qJArHt5KdtJ/cFAofo06KD1MVSeFWyl4iiu+ApDIuw0WhjpOfCdgConOfAnLgkw==}
|
||||
engines: {node: '>=10'}
|
||||
seroval-plugins@1.7.8:
|
||||
resolution: {integrity: sha512-SCfCNzJ8CEz3spf1jNd6XE7mrtrKMchVRMGLFNUEXjY0wIUhKl1bXhkNG3/i0X8uLCWLOhUdMjcM286JZqnCbg==}
|
||||
engines: {node: '>=20'}
|
||||
peerDependencies:
|
||||
seroval: ^1.0
|
||||
|
||||
seroval@1.5.4:
|
||||
resolution: {integrity: sha512-46uFvgrXTVxZcUorgSSRZ4y+ieqLLQRMlG4bnCZKW3qI6BZm7Rg4ntMW4p1mILEEBZWrFlcpp0AyIIlM6jD9iw==}
|
||||
engines: {node: '>=10'}
|
||||
seroval@1.7.9:
|
||||
resolution: {integrity: sha512-ocL7l8aqYWy/dXDHQF3Z8bt5R4Z9IBB4hASCkBDQhl3ZUclxVEzRMQNmRNshiEEIPF1g7uz+2nENDqg+9TU86A==}
|
||||
engines: {node: '>=20'}
|
||||
|
||||
set-cookie-parser@3.1.0:
|
||||
resolution: {integrity: sha512-kjnC1DXBHcxaOaOXBHBeRtltsDG2nUiUni+jP92M9gYdW12rsmx92UsfpH7o5tDRs7I1ZZPSQJQGv3UaRfCiuw==}
|
||||
@@ -2373,8 +2385,8 @@ packages:
|
||||
peerDependencies:
|
||||
zod: ^3.25.0 || ^4.0.0
|
||||
|
||||
zod@4.4.3:
|
||||
resolution: {integrity: sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==}
|
||||
zod@4.6.7:
|
||||
resolution: {integrity: sha512-g8W2D2kU6a8untc053fX1uVBKzM7yqAxW/3zwk83+6RyF2+SKOuV+c0wBDhUwzV1PaGapmZH+rmcUzPf+3CGwg==}
|
||||
|
||||
snapshots:
|
||||
|
||||
@@ -2626,6 +2638,10 @@ snapshots:
|
||||
|
||||
'@floating-ui/utils@0.2.11': {}
|
||||
|
||||
'@fontsource/jost@5.3.0': {}
|
||||
|
||||
'@fontsource/marcellus@5.3.0': {}
|
||||
|
||||
'@hookform/resolvers@5.4.0(react-hook-form@7.79.0(react@19.2.7))':
|
||||
dependencies:
|
||||
'@standard-schema/utils': 0.3.0
|
||||
@@ -3203,7 +3219,7 @@ snapshots:
|
||||
tailwindcss: 4.3.1
|
||||
vite: 8.0.16(@types/node@24.13.2)(jiti@2.7.0)
|
||||
|
||||
'@tanstack/history@1.162.0': {}
|
||||
'@tanstack/history@1.162.5': {}
|
||||
|
||||
'@tanstack/query-core@5.101.0': {}
|
||||
|
||||
@@ -3212,30 +3228,30 @@ snapshots:
|
||||
'@tanstack/query-core': 5.101.0
|
||||
react: 19.2.7
|
||||
|
||||
'@tanstack/react-router@1.170.16(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
|
||||
'@tanstack/react-router@1.170.46(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
|
||||
dependencies:
|
||||
'@tanstack/history': 1.162.0
|
||||
'@tanstack/react-store': 0.9.3(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
|
||||
'@tanstack/router-core': 1.171.13
|
||||
'@tanstack/history': 1.162.5
|
||||
'@tanstack/react-store': 0.11.2(react-dom@19.2.7(react@19.2.7))(react@19.2.7)
|
||||
'@tanstack/router-core': 1.171.39
|
||||
isbot: 5.1.43
|
||||
react: 19.2.7
|
||||
react-dom: 19.2.7(react@19.2.7)
|
||||
|
||||
'@tanstack/react-store@0.9.3(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
|
||||
'@tanstack/react-store@0.11.2(react-dom@19.2.7(react@19.2.7))(react@19.2.7)':
|
||||
dependencies:
|
||||
'@tanstack/store': 0.9.3
|
||||
'@tanstack/store': 0.11.2
|
||||
react: 19.2.7
|
||||
react-dom: 19.2.7(react@19.2.7)
|
||||
use-sync-external-store: 1.6.0(react@19.2.7)
|
||||
|
||||
'@tanstack/router-core@1.171.13':
|
||||
'@tanstack/router-core@1.171.39':
|
||||
dependencies:
|
||||
'@tanstack/history': 1.162.0
|
||||
'@tanstack/history': 1.162.5
|
||||
cookie-es: 3.1.1
|
||||
seroval: 1.5.4
|
||||
seroval-plugins: 1.5.4(seroval@1.5.4)
|
||||
seroval: 1.7.9
|
||||
seroval-plugins: 1.7.8(seroval@1.7.9)
|
||||
|
||||
'@tanstack/store@0.9.3': {}
|
||||
'@tanstack/store@0.11.2': {}
|
||||
|
||||
'@testing-library/dom@10.4.1':
|
||||
dependencies:
|
||||
@@ -3629,8 +3645,8 @@ snapshots:
|
||||
'@babel/parser': 7.29.7
|
||||
eslint: 10.5.0(jiti@2.7.0)(supports-color@8.1.1)
|
||||
hermes-parser: 0.25.1
|
||||
zod: 4.4.3
|
||||
zod-validation-error: 4.0.2(zod@4.4.3)
|
||||
zod: 4.6.7
|
||||
zod-validation-error: 4.0.2(zod@4.6.7)
|
||||
transitivePeerDependencies:
|
||||
- supports-color
|
||||
|
||||
@@ -4160,11 +4176,11 @@ snapshots:
|
||||
|
||||
semver@7.8.4: {}
|
||||
|
||||
seroval-plugins@1.5.4(seroval@1.5.4):
|
||||
seroval-plugins@1.7.8(seroval@1.7.9):
|
||||
dependencies:
|
||||
seroval: 1.5.4
|
||||
seroval: 1.7.9
|
||||
|
||||
seroval@1.5.4: {}
|
||||
seroval@1.7.9: {}
|
||||
|
||||
set-cookie-parser@3.1.0: {}
|
||||
|
||||
@@ -4424,8 +4440,8 @@ snapshots:
|
||||
|
||||
yocto-queue@0.1.0: {}
|
||||
|
||||
zod-validation-error@4.0.2(zod@4.4.3):
|
||||
zod-validation-error@4.0.2(zod@4.6.7):
|
||||
dependencies:
|
||||
zod: 4.4.3
|
||||
zod: 4.6.7
|
||||
|
||||
zod@4.4.3: {}
|
||||
zod@4.6.7: {}
|
||||
|
||||
@@ -27,6 +27,39 @@ describe('AppLayout desktop', () => {
|
||||
});
|
||||
});
|
||||
|
||||
describe('AppLayout scrolling', () => {
|
||||
// jsdom has no layout engine, so these assert the classes that make the browser behave: a one-screen-high
|
||||
// shell that does not scroll itself, with the content area as the only scroll container.
|
||||
it('is one screen high and does not scroll as a whole, so the sidebar stays put', async () => {
|
||||
mockAuthenticated();
|
||||
renderApp('/dashboard');
|
||||
const shell = await screen.findByTestId('app-shell');
|
||||
|
||||
expect(shell).toHaveClass('h-svh', 'overflow-hidden');
|
||||
expect(shell).not.toHaveClass('min-h-svh');
|
||||
});
|
||||
|
||||
it('scrolls only the content area', async () => {
|
||||
mockAuthenticated();
|
||||
renderApp('/dashboard');
|
||||
await screen.findByTestId('app-sidebar');
|
||||
|
||||
expect(screen.getByTestId('app-main')).toHaveClass('overflow-y-auto');
|
||||
expect(screen.getByTestId('app-sidebar-column')).toHaveClass('h-full');
|
||||
// The sidebar's own menu scrolls inside it on a very short screen, never the page.
|
||||
expect(screen.getByTestId('app-sidebar').querySelector('nav')).toHaveClass('overflow-y-auto');
|
||||
});
|
||||
|
||||
it('applies on every page of the shell, for example the settings page', async () => {
|
||||
mockAuthenticated();
|
||||
renderApp('/settings');
|
||||
await screen.findByTestId('settings-title', {}, { timeout: 10000 });
|
||||
|
||||
expect(screen.getByTestId('app-shell')).toHaveClass('h-svh', 'overflow-hidden');
|
||||
expect(screen.getByTestId('app-main')).toContainElement(screen.getByTestId('settings-title'));
|
||||
});
|
||||
});
|
||||
|
||||
describe('AppLayout mobile menu', () => {
|
||||
it('opens sidebar overlay when hamburger is clicked', async () => {
|
||||
mockAuthenticated();
|
||||
|
||||
@@ -22,25 +22,32 @@ export function AppLayout() {
|
||||
}, [status, navigate]);
|
||||
|
||||
useEffect(() => {
|
||||
// Only for a signed-in user. A guest (just signed out) must be left alone: sending a guest to /dashboard
|
||||
// makes the authenticated route redirect straight back to /login, and with the CMS switched off this
|
||||
// effect then fires again - an endless navigation loop that froze the app after logout.
|
||||
if (status !== 'authenticated') return;
|
||||
if (availability?.status === 'NotAvailable') {
|
||||
const allowed = ALLOWED_WHEN_UNAVAILABLE.some(p => location.pathname.startsWith(p));
|
||||
if (!allowed) void navigate({ to: '/dashboard' });
|
||||
}
|
||||
}, [availability?.status, location.pathname, navigate]);
|
||||
}, [status, availability?.status, location.pathname, navigate]);
|
||||
|
||||
if (!isAuthenticated) {
|
||||
return null;
|
||||
}
|
||||
|
||||
return (
|
||||
<div className="flex min-h-svh">
|
||||
<div className="hidden md:flex">
|
||||
// The shell is exactly one screen high and does not scroll itself: the sidebar stays where it is and
|
||||
// only the content area scrolls. (With min-h-svh the whole document scrolled as soon as the content
|
||||
// was a little taller than the screen, and the sidebar scrolled away with it.)
|
||||
<div className="flex h-svh overflow-hidden" data-testid="app-shell">
|
||||
<div className="hidden h-full md:flex" data-testid="app-sidebar-column">
|
||||
<Sidebar />
|
||||
</div>
|
||||
{isMenuOpen && <SidebarOverlay onClose={() => setIsMenuOpen(false)} />}
|
||||
<div className="flex flex-1 flex-col">
|
||||
<div className="flex min-w-0 flex-1 flex-col">
|
||||
<MobileBar onMenuOpen={() => setIsMenuOpen(true)} />
|
||||
<main className="flex-1 p-6" data-testid="app-main">
|
||||
<main className="flex-1 overflow-y-auto p-6" data-testid="app-main">
|
||||
<Outlet />
|
||||
</main>
|
||||
</div>
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { screen } from '@testing-library/react';
|
||||
import { renderWithProviders } from '@/test/utils';
|
||||
import { BrandLogo } from '@/components/layout/BrandLogo';
|
||||
|
||||
describe('BrandLogo', () => {
|
||||
it('falls back to the application name with its dot when the site has no logo', () => {
|
||||
renderWithProviders(<BrandLogo logo={null} />);
|
||||
|
||||
expect(screen.getByTestId('brand-fallback')).toHaveTextContent('SlpModularCms');
|
||||
expect(screen.queryByTestId('brand-logo')).not.toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('shows the default (unthemed) admin the same way', () => {
|
||||
renderWithProviders(<BrandLogo />);
|
||||
|
||||
expect(screen.getByTestId('brand-fallback')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('draws the logo for both colour modes, named for screen readers', () => {
|
||||
renderWithProviders(<BrandLogo logo={{ onLight: '/admin/l.png', onDark: '/admin/d.png' }} />);
|
||||
|
||||
const images = screen.getAllByRole('img', { hidden: true });
|
||||
expect(images).toHaveLength(2);
|
||||
expect(images.map((i) => i.getAttribute('src'))).toEqual(['/admin/l.png', '/admin/d.png']);
|
||||
images.forEach((i) => expect(i).toHaveAttribute('alt', 'SlpModularCms'));
|
||||
expect(screen.queryByTestId('brand-fallback')).not.toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,36 @@
|
||||
import { useTranslation } from 'react-i18next';
|
||||
import { cn } from '@/lib/utils';
|
||||
import { getBrand } from '@/lib/brand';
|
||||
import type { BrandLogo as BrandLogoFiles } from '@/lib/brand';
|
||||
|
||||
interface BrandLogoProps {
|
||||
/** Overrides the site brand; mainly for tests and, later, a logo loaded from site settings. */
|
||||
logo?: BrandLogoFiles | null;
|
||||
className?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* The site's logo, or, when it has none, the application name with its dot (what the admin always
|
||||
* showed). The single place the admin draws the brand: do not hardcode it elsewhere.
|
||||
*/
|
||||
export function BrandLogo({ logo, className }: BrandLogoProps) {
|
||||
const { t } = useTranslation();
|
||||
const resolved = logo === undefined ? getBrand().logo : logo;
|
||||
const name = t('common.appName');
|
||||
|
||||
if (resolved === null) {
|
||||
return (
|
||||
<div className={cn('flex items-center gap-2', className)} data-testid="brand-fallback">
|
||||
<span className="h-3 w-3 rounded-full bg-primary" aria-hidden="true" />
|
||||
<span className="text-lg font-semibold">{name}</span>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
return (
|
||||
<div className={cn('flex items-center', className)} data-testid="brand-logo">
|
||||
<img src={resolved.onLight} alt={name} className="h-10 w-auto dark:hidden" />
|
||||
<img src={resolved.onDark} alt={name} className="hidden h-10 w-auto dark:block" />
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -1,5 +1,6 @@
|
||||
import { Menu } from 'lucide-react';
|
||||
import { useTranslation } from 'react-i18next';
|
||||
import { BrandLogo } from './BrandLogo';
|
||||
|
||||
interface MobileBarProps {
|
||||
onMenuOpen: () => void;
|
||||
@@ -22,7 +23,7 @@ export function MobileBar({ onMenuOpen }: MobileBarProps) {
|
||||
>
|
||||
<Menu className="size-5" />
|
||||
</button>
|
||||
<span className="font-semibold">{t('common.appName')}</span>
|
||||
<BrandLogo className="[&_img]:h-8 [&_span]:text-base" />
|
||||
</header>
|
||||
);
|
||||
}
|
||||
|
||||
@@ -32,12 +32,12 @@ describe('Sidebar role filtering (BR-U3-01 – BR-U3-06)', () => {
|
||||
expect(screen.queryByTestId('nav-profile')).not.toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('Administrator sees Dashboard and Users — not Settings or CMS', async () => {
|
||||
it('Administrator sees Dashboard, Users and Settings — not CMS', async () => {
|
||||
mockAuthenticatedAs('Administrator');
|
||||
renderApp('/dashboard');
|
||||
expect(await screen.findByTestId('nav-dashboard')).toBeInTheDocument();
|
||||
expect(screen.getByTestId('nav-users')).toBeInTheDocument();
|
||||
expect(screen.queryByTestId('nav-settings')).not.toBeInTheDocument();
|
||||
expect(screen.getByTestId('nav-settings')).toBeInTheDocument();
|
||||
expect(screen.queryByTestId('nav-cms')).not.toBeInTheDocument();
|
||||
expect(screen.queryByTestId('nav-profile')).not.toBeInTheDocument();
|
||||
});
|
||||
|
||||
@@ -7,6 +7,7 @@ import { useAuth } from '@/features/auth/context/auth-context';
|
||||
import { useAvailabilityStatus } from '@/features/availability/services/useAvailability';
|
||||
import { useSystemCapabilities } from '@/features/system/services/useSystemCapabilities';
|
||||
import { LanguageSwitcher } from '@/i18n/LanguageSwitcher';
|
||||
import { BrandLogo } from './BrandLogo';
|
||||
import { ThemeToggle } from './ThemeToggle';
|
||||
import { UserMenu } from './UserMenu';
|
||||
|
||||
@@ -38,7 +39,7 @@ const NAV_ITEMS: NavItem[] = [
|
||||
];
|
||||
|
||||
const SETTINGS_ITEM: NavItem = {
|
||||
to: '/settings', labelKey: 'nav.settings', icon: Settings, testId: 'nav-settings', roles: ['Owner'],
|
||||
to: '/settings', labelKey: 'nav.settings', icon: Settings, testId: 'nav-settings', roles: ['Owner', 'Administrator'],
|
||||
};
|
||||
|
||||
interface SidebarProps {
|
||||
@@ -66,10 +67,7 @@ export function Sidebar({ onClose }: SidebarProps = {}) {
|
||||
data-testid="app-sidebar"
|
||||
>
|
||||
<div className="flex h-16 items-center justify-between border-b border-border px-6">
|
||||
<div className="flex items-center gap-2">
|
||||
<span className="h-3 w-3 rounded-full bg-primary" aria-hidden="true" />
|
||||
<span className="text-lg font-semibold">{t('common.appName')}</span>
|
||||
</div>
|
||||
<BrandLogo />
|
||||
{onClose && (
|
||||
<button
|
||||
type="button"
|
||||
@@ -83,7 +81,7 @@ export function Sidebar({ onClose }: SidebarProps = {}) {
|
||||
)}
|
||||
</div>
|
||||
|
||||
<nav className="flex-1 space-y-1 p-3">
|
||||
<nav className="flex-1 space-y-1 overflow-y-auto p-3">
|
||||
{visibleItems.map((item) => {
|
||||
const Icon = item.icon;
|
||||
const blocked = systemUnavailable && !ALLOWED_WHEN_UNAVAILABLE.some(p => item.to.startsWith(p));
|
||||
|
||||
@@ -0,0 +1,52 @@
|
||||
import { describe, expect, it } from 'vitest';
|
||||
import { render, screen, waitFor } from '@testing-library/react';
|
||||
import userEvent from '@testing-library/user-event';
|
||||
import { http, HttpResponse } from 'msw';
|
||||
import { I18nextProvider } from 'react-i18next';
|
||||
import type { ReactNode } from 'react';
|
||||
import { AuthProvider } from '@/features/auth/context/AuthProvider';
|
||||
import { useAuth } from '@/features/auth/context/auth-context';
|
||||
import { SessionUnreachable } from '@/features/auth/components/SessionUnreachable';
|
||||
import { server } from '@/mocks/server';
|
||||
import { API_BASE, makeAuthResponse } from '@/features/auth/mocks/fixtures';
|
||||
import { refreshBackoff } from '@/lib/refreshPolicy';
|
||||
import i18n from '@/i18n/config';
|
||||
|
||||
function Probe() {
|
||||
const { status } = useAuth();
|
||||
return status === 'unreachable' ? <SessionUnreachable /> : <p data-testid="status">{status}</p>;
|
||||
}
|
||||
|
||||
function Wrapper({ children }: { children: ReactNode }) {
|
||||
return (
|
||||
<I18nextProvider i18n={i18n}>
|
||||
<AuthProvider>{children}</AuthProvider>
|
||||
</I18nextProvider>
|
||||
);
|
||||
}
|
||||
|
||||
describe('SessionUnreachable', () => {
|
||||
it('offers a retry that signs the visitor in once the server answers again', async () => {
|
||||
const original = [...refreshBackoff.delays];
|
||||
refreshBackoff.delays = [5];
|
||||
try {
|
||||
let down = true;
|
||||
server.use(
|
||||
http.post(`${API_BASE}/api/v1/auth/refresh`, () =>
|
||||
down ? HttpResponse.json({ status: 429 }, { status: 429 }) : HttpResponse.json(makeAuthResponse()),
|
||||
),
|
||||
);
|
||||
render(<Probe />, { wrapper: Wrapper });
|
||||
const retry = await screen.findByTestId('session-unreachable-retry');
|
||||
|
||||
await userEvent.click(retry); // still down
|
||||
expect(await screen.findByTestId('session-unreachable-failed')).toBeInTheDocument();
|
||||
|
||||
down = false;
|
||||
await userEvent.click(screen.getByTestId('session-unreachable-retry'));
|
||||
await waitFor(() => expect(screen.getByTestId('status')).toHaveTextContent('authenticated'));
|
||||
} finally {
|
||||
refreshBackoff.delays = original;
|
||||
}
|
||||
});
|
||||
});
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user