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