Files

52 lines
5.7 KiB
Markdown

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