Files
slp-modular-cms/aidlc-docs/features/andreaslop-site-hosting/construction/plans/andreaslop-client-code-generation-plan.md

5.7 KiB

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)

  • 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).
  • 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.
  • 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).
  • 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)

  • B1 SetupOptions (Identity:Setup:Token), whitespace-only token = startup error; ISetupTokenValidator / SetupTokenValidator (SHA-256 + CryptographicOperations.FixedTimeEquals, header X-Setup-Token).
  • B2 SetupController: [EnableRateLimiting("login")] on both endpoints; POST owner checks token (identical 401 for missing/wrong, no detail); GET status returns initialized + tokenRequired.
  • B3 SecurityEvents.SetupTokenRejected (id 5007, setup_token_rejected), logged on failed attempts without echoing the token.
  • 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.
  • B5 Build + test Modules.Identity and its tests.

Part C - New client project SlpModularCms.Api.AndreaSlopFotografie

  • 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).
  • 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.
  • 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)
  • C4 Build + test.

Part D - Frontend: ASF theme, language, setup token (P9, P10)

  • 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.
  • 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).
  • D3 Setup page: token field only when tokenRequired; sends X-Setup-Token; translations nl/en.
  • D4 Vitest: theme alias unset/set, language order, setup page with/without token. Compute below-AA contrast pairs for the hand-back.
  • D5 Frontend lint, type-check, test, build for both default and VITE_THEME=asf.

Part E - CI/CD (P8)

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

  • 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.
  • F2 construction/andreaslop-client/code/code-summary.md.
  • F3 Full solution build and all tests; report results honestly.
  • 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.