5.7 KiB
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;UseForwardedHeadersfirst inCmsHostonly when proxies are configured (ForwardLimit 1, XForwardedFor|XForwardedProto, default known proxies cleared). - A2
ClientPartitionKey+AddCmsRateLimiting: per-client-address partitions forlogin,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, headerX-Setup-Token). - B2
SetupController:[EnableRateLimiting("login")]on both endpoints;POST ownerchecks token (identical 401 for missing/wrong, no detail);GET statusreturnsinitialized+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.Identityand its tests.
Part C - New client project SlpModularCms.Api.AndreaSlopFotografie
- C1 Project in
src/, added to the solution under Clients; thinProgram.cswithCmsHostOptions { WebsiteMode = PrerenderedPages }; Identity module; Availability module only if required (capabilities must not listOfferings). - C2 Three-file appsettings per the
dotnet-appsettingsskill (appsettings.jsonwithout secrets:SecurityHeadersDefaultPolicy=StrictSite+ site Umami/Sentry origins,Website:NoIndex=true, JWT issuer/audience, rate limits),launchSettingsport 5200, publish settings like Api.SlpSoftware. - C3 Tests: host regression (capabilities has no
Offerings,/health, website serving from a tempwwwroot/web, headers), needs MariaDB likeApi.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_LANGUAGEini18n/config.ts(stored choice > env default > browser). - D3 Setup page: token field only when
tokenRequired; sendsX-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: addpublish-asf-testanddeploy-asf-test, gated byvars.ASF_TEST_DEPLOY_ENABLED == 'true', reusingdeploy-scp.yaml; manual box "Deploy ASF test". Existing SlpSoftware jobs, env block anddeploy-scp.yamlbyte-for-byte unchanged (verified by diff). Admin build env:VITE_THEME=asf,VITE_DEFAULT_LANGUAGE=nl,VITE_APP_ENV=test,VITE_SENTRY_DSNfromVITE_SENTRY_DSN_ASF. - E2 Validate YAML; confirm via diff that nothing else changed; note the open verification item (Gitea
varsin job-levelif:).
Part F - Documentation and wrap-up
- F1 Update
README.md/AGENTS.md(+ mirrorsCLAUDE.md,.junie/guidelines.md,.github/copilot-instructions.mdtogether) for the new Clients project and the opt-inForwardedHeaderssetting;WEBSITE_WORKSPACE.mdif 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.