Files

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)

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