AIDLC-documentatie U2 (NFR, infrastructuur, code generation)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-07 01:16:34 +01:00
co-authored by Claude Sonnet 5.5
parent 88f5d20a78
commit c69ef9188e
16 changed files with 628 additions and 3 deletions
@@ -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.
@@ -0,0 +1,43 @@
# NFR Design Patterns - andreaslop-client (U2)
| # | Pattern | Realises | Design |
|---|---|---|---|
| P1 | Optional guard with secure default | NFR-SEC-01/02 | `ISetupTokenValidator { IsRequired; IsValid(presented) }`. `IsRequired` is true only when `Identity:Setup:Token` is a non-empty string. With no token configured everything behaves as today (existing hosts unaffected). `CreateOwner` checks the validator **before** calling `ISetupService`, so a wrong token creates nothing. |
| P2 | Constant-time comparison | NFR-SEC-01 | Both sides are hashed with SHA-256 to 32 bytes and compared with `CryptographicOperations.FixedTimeEquals`. Equal length by construction, so no length leak; null/empty presented token is simply invalid. The validator never throws. |
| P3 | Fail closed on bad configuration | NFR-SEC-02 | A whitespace-only configured token is treated as a configuration error at startup (options validation), not as "no token". |
| P4 | No information leak | NFR-SEC-02 | `GET /Setup/status` returns `{ initialized, tokenRequired }` only. A rejected token answers `401` with the same problem-details body whatever the reason (missing or wrong). |
| P5 | Reuse the existing limiter | NFR-SEC-03 | `[EnableRateLimiting("login")]` on `GetStatus` and `CreateOwner`. Limits come from the existing `RateLimiting:Login` settings (5 per 60 s). A 429 already produces the `rate_limit_triggered` security event. |
| P6 | Alertable security event | NFR-SEC-03 | New constant event name `setup_token_rejected` (event id 5007) in `SecurityEventNames`/`SecurityEvents`, source-generated like the others, constant template, endpoint as the only field; no token, no email. Level Warning so it crosses the Sentry threshold. |
| P7 | Secrets only from the environment | NFR-SEC-04/05 | Committed appsettings hold placeholders. Real values come from `shared/env` via the systemd unit: `ConnectionStrings__DefaultConnection`, `JwtSettings__Secret`, `Identity__Setup__Token`, `Observability__SentryDsn`, `SecurityHeaders__...`. The infrastructure design lists them. |
| P8 | Explicit skip switch for CI | NFR-DEP-02, DEP-03 | Job-level condition `vars.ASF_TEST_DEPLOY_ENABLED == 'true'` on `publish-asf-test` and `deploy-asf-test`. Failing/skipped ASF jobs are not in any SlpSoftware job's `needs`. The Andrea deploy job reuses `deploy-scp.yaml` with its own path, service and health-check variables. |
| P9 | Build-time theme selection | NFR-UX-01/02 | `VITE_THEME` selects `themes/<name>/theme.css` via a Vite alias; unset = empty module (today's admin). The CSS only re-declares existing tokens (`--background`, `--primary`, `--radius`, fonts ...), nothing structural. |
| P10 | Language default without overriding the user | NFR-UX-01 | i18n init order: stored choice, then `VITE_DEFAULT_LANGUAGE`, then browser detection. |
| P11 | Trusted-proxy forwarded headers (opt-in) | NFR-SEC-09/10/12 | `ForwardedHeadersOptions` built from `ForwardedHeaders:KnownProxies`; `KnownProxies`/`KnownNetworks` cleared first (framework default trusts loopback), `ForwardLimit = 1`, `ForwardedHeaders = XForwardedFor \| XForwardedProto`. Added with `UseForwardedHeaders()` as the **first** middleware after the database migration, only when at least one proxy is configured. Options validation (`ValidateOnStart`): every entry parses as an IP address and is not any-address. |
| P12 | Per-client limiter partitions | NFR-SEC-11 | A helper `ClientPartitionKey(HttpContext)` returns `RemoteIpAddress` text or a fixed fallback. Each named limiter is registered with `AddPolicy(name, context => RateLimitPartition.GetFixedWindowLimiter(key, _ => options))` (sliding for `refresh`), keeping the same permit/window/queue settings. Rejection callback and `rate_limit_triggered` event unchanged. Idle partitions are reclaimed by the framework. |
## Where the checks sit
```mermaid
flowchart LR
R["POST /api/v1/Setup/owner"] --> L{"login limiter"}
L -- over limit --> T429["429 + rate_limit_triggered"]
L -- ok --> V{"token required?"}
V -- no --> S["ISetupService.CreateInitialOwnerAsync"]
V -- yes --> C{"X-Setup-Token valid? (fixed time)"}
C -- yes --> S
C -- no --> T401["401 + setup_token_rejected"]
classDef ok fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
classDef bad fill:#feb2b2,stroke:#c53030,stroke-width:1px,color:#000;
classDef step fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
class S ok;
class T429,T401 bad;
class L,V,C step;
```
Text alternative: the limiter runs first, then the token check when a token is configured; only a valid (or not required) token reaches the setup service.
## Open verification items (settled in Code Generation or on the first test deploy)
1. (Resolved by option B, P11/P12.) Finding: the limiters were global buckets and no host handled forwarded headers. After this change, behind the proxy Pi the limiter only partitions per visitor once `KnownProxies` is set and the proxy-Pi block passes `X-Forwarded-For`/`-Proto`; the proxy must set the header from the real client address (`$remote_addr`), and the host takes the last entry (forward limit 1). Verified by tests with a simulated trusted and an untrusted proxy.
2. Gitea `vars` in a job-level `if:` (used already in step `if:` elsewhere): verify the syntax in the workflow file with a dry read; the skip behaviour is observed on the first run.
3. Forwarded headers / HTTP/1.0 behind the proxy Pi: observed on the first test deploy (peer request).