diff --git a/.gitea/workflows/continuous_integration.yaml b/.gitea/workflows/continuous_integration.yaml index 8674d2a..a135c8c 100644 --- a/.gitea/workflows/continuous_integration.yaml +++ b/.gitea/workflows/continuous_integration.yaml @@ -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 diff --git a/README.md b/README.md index 1945173..a7b2831 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/SlpModularCms.sln b/SlpModularCms.sln index 5f95c28..aa999db 100644 --- a/SlpModularCms.sln +++ b/SlpModularCms.sln @@ -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 diff --git a/WEBSITE_WORKSPACE.md b/WEBSITE_WORKSPACE.md index 8df6f6e..faea489 100644 --- a/WEBSITE_WORKSPACE.md +++ b/WEBSITE_WORKSPACE.md @@ -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 diff --git a/aidlc-docs/_shared/handoffs/cms-api-foundation-brief-u1-u2.md b/aidlc-docs/_shared/handoffs/cms-api-foundation-brief-u1-u2.md new file mode 100644 index 0000000..b33488c --- /dev/null +++ b/aidlc-docs/_shared/handoffs/cms-api-foundation-brief-u1-u2.md @@ -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 `.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. diff --git a/aidlc-docs/active-features.md b/aidlc-docs/active-features.md index 0dcfd6a..412a9c8 100644 --- a/aidlc-docs/active-features.md +++ b/aidlc-docs/active-features.md @@ -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 | diff --git a/aidlc-docs/bugs/availability-gate-blocks-website-and-admin/bug-fix.md b/aidlc-docs/bugs/availability-gate-blocks-website-and-admin/bug-fix.md new file mode 100644 index 0000000..888a1ea --- /dev/null +++ b/aidlc-docs/bugs/availability-gate-blocks-website-and-admin/bug-fix.md @@ -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 diff --git a/aidlc-docs/bugs/cms-admin-nine-points/bug-fix.md b/aidlc-docs/bugs/cms-admin-nine-points/bug-fix.md new file mode 100644 index 0000000..79e1fbc --- /dev/null +++ b/aidlc-docs/bugs/cms-admin-nine-points/bug-fix.md @@ -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 diff --git a/aidlc-docs/bugs/invitation-delete-and-lifetime/bug-fix.md b/aidlc-docs/bugs/invitation-delete-and-lifetime/bug-fix.md new file mode 100644 index 0000000..17beb01 --- /dev/null +++ b/aidlc-docs/bugs/invitation-delete-and-lifetime/bug-fix.md @@ -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 diff --git a/aidlc-docs/bugs/owner-cannot-promote-requester-identity/bug-fix.md b/aidlc-docs/bugs/owner-cannot-promote-requester-identity/bug-fix.md new file mode 100644 index 0000000..d0e76dd --- /dev/null +++ b/aidlc-docs/bugs/owner-cannot-promote-requester-identity/bug-fix.md @@ -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 diff --git a/aidlc-docs/bugs/setup-page-after-failed-status-read/bug-fix.md b/aidlc-docs/bugs/setup-page-after-failed-status-read/bug-fix.md new file mode 100644 index 0000000..67411c5 --- /dev/null +++ b/aidlc-docs/bugs/setup-page-after-failed-status-read/bug-fix.md @@ -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 diff --git a/aidlc-docs/features/andreaslop-site-hosting/aidlc-state.md b/aidlc-docs/features/andreaslop-site-hosting/aidlc-state.md new file mode 100644 index 0000000..51440a7 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/aidlc-state.md @@ -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 diff --git a/aidlc-docs/features/andreaslop-site-hosting/audit.md b/aidlc-docs/features/andreaslop-site-hosting/audit.md new file mode 100644 index 0000000..cf31cf4 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/audit.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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/andreaslop-client/code/code-summary.md b/aidlc-docs/features/andreaslop-site-hosting/construction/andreaslop-client/code/code-summary.md new file mode 100644 index 0000000..8d3bb7d --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/andreaslop-client/code/code-summary.md @@ -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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/andreaslop-client/infrastructure-design/deployment-architecture.md b/aidlc-docs/features/andreaslop-site-hosting/construction/andreaslop-client/infrastructure-design/deployment-architecture.md new file mode 100644 index 0000000..81841ee --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/andreaslop-client/infrastructure-design/deployment-architecture.md @@ -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/ 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). diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/andreaslop-client/infrastructure-design/infrastructure-design.md b/aidlc-docs/features/andreaslop-site-hosting/construction/andreaslop-client/infrastructure-design/infrastructure-design.md new file mode 100644 index 0000000..5e6ff9d --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/andreaslop-client/infrastructure-design/infrastructure-design.md @@ -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// written by the deploy + current -> releases/ 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=` | +| `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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/andreaslop-client/infrastructure-design/manual-steps-for-bryan.md b/aidlc-docs/features/andreaslop-site-hosting/construction/andreaslop-client/infrastructure-design/manual-steps-for-bryan.md new file mode 100644 index 0000000..6e320ed --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/andreaslop-client/infrastructure-design/manual-steps-for-bryan.md @@ -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=/current`, `EnvironmentFile=/shared/env`, `ExecStart= 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/ 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). diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/andreaslop-client/nfr-design/logical-components.md b/aidlc-docs/features/andreaslop-site-hosting/construction/andreaslop-client/nfr-design/logical-components.md new file mode 100644 index 0000000..5ef6535 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/andreaslop-client/nfr-design/logical-components.md @@ -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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/andreaslop-client/nfr-design/nfr-design-patterns.md b/aidlc-docs/features/andreaslop-site-hosting/construction/andreaslop-client/nfr-design/nfr-design-patterns.md new file mode 100644 index 0000000..a303668 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/andreaslop-client/nfr-design/nfr-design-patterns.md @@ -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//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). diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/andreaslop-client/nfr-requirements/nfr-requirements.md b/aidlc-docs/features/andreaslop-site-hosting/construction/andreaslop-client/nfr-requirements/nfr-requirements.md new file mode 100644 index 0000000..01f8b1d --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/andreaslop-client/nfr-requirements/nfr-requirements.md @@ -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`). diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/andreaslop-client/nfr-requirements/tech-stack-decisions.md b/aidlc-docs/features/andreaslop-site-hosting/construction/andreaslop-client/nfr-requirements/tech-stack-decisions.md new file mode 100644 index 0000000..db68785 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/andreaslop-client/nfr-requirements/tech-stack-decisions.md @@ -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 | diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/build-and-test/build-and-test-summary.md b/aidlc-docs/features/andreaslop-site-hosting/construction/build-and-test/build-and-test-summary.md new file mode 100644 index 0000000..540a08e --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/build-and-test/build-and-test-summary.md @@ -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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/build-and-test/build-instructions.md b/aidlc-docs/features/andreaslop-site-hosting/construction/build-and-test/build-instructions.md new file mode 100644 index 0000000..50404f5 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/build-and-test/build-instructions.md @@ -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`. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/build-and-test/integration-test-instructions.md b/aidlc-docs/features/andreaslop-site-hosting/construction/build-and-test/integration-test-instructions.md new file mode 100644 index 0000000..0636f33 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/build-and-test/integration-test-instructions.md @@ -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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/build-and-test/performance-test-instructions.md b/aidlc-docs/features/andreaslop-site-hosting/construction/build-and-test/performance-test-instructions.md new file mode 100644 index 0000000..77f5476 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/build-and-test/performance-test-instructions.md @@ -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). diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/build-and-test/security-test-instructions.md b/aidlc-docs/features/andreaslop-site-hosting/construction/build-and-test/security-test-instructions.md new file mode 100644 index 0000000..878e1da --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/build-and-test/security-test-instructions.md @@ -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). diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/build-and-test/unit-test-instructions.md b/aidlc-docs/features/andreaslop-site-hosting/construction/build-and-test/unit-test-instructions.md new file mode 100644 index 0000000..138d387 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/build-and-test/unit-test-instructions.md @@ -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). diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/code/code-summary.md b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/code/code-summary.md new file mode 100644 index 0000000..05ad5d5 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/code/code-summary.md @@ -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). diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/business-logic-model.md b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/business-logic-model.md new file mode 100644 index 0000000..b7f7686 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/business-logic-model.md @@ -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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/business-rules.md b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/business-rules.md new file mode 100644 index 0000000..859c064 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/business-rules.md @@ -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: `.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("/")`, 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' ; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self' ; 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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/domain-entities.md b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/domain-entities.md new file mode 100644 index 0000000..6cd287e --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/domain-entities.md @@ -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 `.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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-design/logical-components.md b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-design/logical-components.md new file mode 100644 index 0000000..a039185 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-design/logical-components.md @@ -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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-design/nfr-design-patterns.md b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-design/nfr-design-patterns.md new file mode 100644 index 0000000..1aaff7a --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-design/nfr-design-patterns.md @@ -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) `.html`, (2) the literal file for extension paths or `/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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-requirements/nfr-requirements.md b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-requirements/nfr-requirements.md new file mode 100644 index 0000000..5ec265d --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-requirements/nfr-requirements.md @@ -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). diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-requirements/tech-stack-decisions.md b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-requirements/tech-stack-decisions.md new file mode 100644 index 0000000..d0c3d9d --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-requirements/tech-stack-decisions.md @@ -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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/plans/andreaslop-client-code-generation-plan.md b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/andreaslop-client-code-generation-plan.md new file mode 100644 index 0000000..c2e0468 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/andreaslop-client-code-generation-plan.md @@ -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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/plans/andreaslop-client-infrastructure-design-plan.md b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/andreaslop-client-infrastructure-design-plan.md new file mode 100644 index 0000000..c75a1f1 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/andreaslop-client-infrastructure-design-plan.md @@ -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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/plans/andreaslop-client-nfr-design-plan.md b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/andreaslop-client-nfr-design-plan.md new file mode 100644 index 0000000..30db418 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/andreaslop-client-nfr-design-plan.md @@ -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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/plans/andreaslop-client-nfr-requirements-plan.md b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/andreaslop-client-nfr-requirements-plan.md new file mode 100644 index 0000000..0553327 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/andreaslop-client-nfr-requirements-plan.md @@ -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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-code-generation-plan.md b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-code-generation-plan.md new file mode 100644 index 0000000..a2da5e5 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-code-generation-plan.md @@ -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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-fd-questions.md b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-fd-questions.md new file mode 100644 index 0000000..c5ef4c5 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-fd-questions.md @@ -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") diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-functional-design-plan.md b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-functional-design-plan.md new file mode 100644 index 0000000..6b4d06b --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-functional-design-plan.md @@ -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) diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-nfr-design-plan.md b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-nfr-design-plan.md new file mode 100644 index 0000000..0e2034d --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-nfr-design-plan.md @@ -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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-nfr-requirements-plan.md b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-nfr-requirements-plan.md new file mode 100644 index 0000000..27c961c --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-nfr-requirements-plan.md @@ -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") diff --git a/aidlc-docs/features/andreaslop-site-hosting/handback-u1.md b/aidlc-docs/features/andreaslop-site-hosting/handback-u1.md new file mode 100644 index 0000000..9e2a640 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/handback-u1.md @@ -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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/handback-u2.md b/aidlc-docs/features/andreaslop-site-hosting/handback-u2.md new file mode 100644 index 0000000..2e5e9ff --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/handback-u2.md @@ -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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/application-design.md b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/application-design.md new file mode 100644 index 0000000..f138a97 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/application-design.md @@ -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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/component-dependency.md b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/component-dependency.md new file mode 100644 index 0000000..28ce2a3 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/component-dependency.md @@ -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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/component-methods.md b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/component-methods.md new file mode 100644 index 0000000..4254026 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/component-methods.md @@ -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 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 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 allowedScriptOrigins, IEnumerable allowedConnectOrigins, + IEnumerable? siteScriptOrigins = null, IEnumerable? siteConnectOrigins = null); +} +public sealed class SecurityHeadersOptions { /* + */ public IList AllowedSiteScriptOrigins { get; set; } = []; public IList 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//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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/components.md b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/components.md new file mode 100644 index 0000000..b3fb26e --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/components.md @@ -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 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//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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/services.md b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/services.md new file mode 100644 index 0000000..fba4b45 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/services.md @@ -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/` -> 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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work-dependency.md b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work-dependency.md new file mode 100644 index 0000000..a4e696a --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work-dependency.md @@ -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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work-story-map.md b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work-story-map.md new file mode 100644 index 0000000..0a328bf --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work-story-map.md @@ -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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work.md b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work.md new file mode 100644 index 0000000..0a384bf --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work.md @@ -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). diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/plans/application-design-plan.md b/aidlc-docs/features/andreaslop-site-hosting/inception/plans/application-design-plan.md new file mode 100644 index 0000000..cb469c0 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/plans/application-design-plan.md @@ -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 (`.html`, or `/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) diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/plans/execution-plan.md b/aidlc-docs/features/andreaslop-site-hosting/inception/plans/execution-plan.md new file mode 100644 index 0000000..c741c04 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/plans/execution-plan.md @@ -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
(CmsHost, StaticContent, CSP catalog)"] + api["SlpModularCms.Api"] + slp["SlpModularCms.Api.SlpSoftware"] + andrea["SlpModularCms.Api.AndreaSlopFotografie
(new client, U2)"] + ident["Modules.Identity
(setup token)"] + avail["Modules.Availability"] + fe["frontend
(theme per site)"] + ci["Gitea workflows
(CI + deploy-scp)"] + pi["Test Pi
(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
COMPLETED"] + RE["Reverse Engineering
SKIP (reuse)"] + RA["Requirements Analysis
COMPLETED"] + US["User Stories
SKIP"] + WP["Workflow Planning
IN PROGRESS"] + AD["Application Design
EXECUTE"] + UG["Units Generation
EXECUTE (minimal)"] + end + + subgraph CONSTRUCTION["CONSTRUCTION PHASE"] + U1["Unit U1 core-site-hosting
FD, NFR Req, NFR Design, Code, per-unit build/test"] + H1["Hand-back U1 + wait for go"] + U2["Unit U2 andreaslop-client
NFR Req, NFR Design, Infra Design, Code, per-unit build/test"] + H2["Hand-back U2"] + BT["Build and Test (all units)
EXECUTE"] + end + + subgraph OPERATIONS["OPERATIONS PHASE"] + DS["Deployment Setup
EXECUTE"] + MS["Monitoring Setup
EXECUTE"] + PRV["Production Readiness Validation
EXECUTE"] + 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. diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/plans/unit-of-work-plan.md b/aidlc-docs/features/andreaslop-site-hosting/inception/plans/unit-of-work-plan.md new file mode 100644 index 0000000..e69c004 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/plans/unit-of-work-plan.md @@ -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 diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/pi-inventory-notes.md b/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/pi-inventory-notes.md new file mode 100644 index 0000000..693db1b --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/pi-inventory-notes.md @@ -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//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"). diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/requirement-verification-questions.md b/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/requirement-verification-questions.md new file mode 100644 index 0000000..cb7fdd4 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/requirement-verification-questions.md @@ -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) diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/requirements.md b/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/requirements.md new file mode 100644 index 0000000..0773a27 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/requirements.md @@ -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' & \"Co\"", name: "x")); + + mail.Html.Should().NotContain("", "#12345", "#12345g", "url(x)", "#ac0000;background:red" }) + { + var mail = _renderer.Render(MailKind.Invitation, "nl", Model() with { BrandColor = bad }); + mail.Html.Should().NotContain("" }).Html; + + html.Should().NotContain("