5.4 KiB
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
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)
- (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
KnownProxiesis set and the proxy-Pi block passesX-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. - Gitea
varsin a job-levelif:(used already in stepif:elsewhere): verify the syntax in the workflow file with a dry read; the skip behaviour is observed on the first run. - Forwarded headers / HTTP/1.0 behind the proxy Pi: observed on the first test deploy (peer request).