# NFR Requirements - andreaslop-client (U2) Answers: Q1 deploy trigger "Zelfde als nu" (automatic on push to master + manual box, test only, must skip cleanly while Andrea is not set up); Q2 = A separate jobs; Q3 = A setup endpoints under the `login` limiter + security event; Q4 = A token required on test; Q5 = B brand colours exactly, no contrast check. ## Security (Security Baseline, blocking) | ID | Requirement | |---|---| | NFR-SEC-01 | First-admin setup token: `Identity:Setup:Token` from configuration (env `Identity__Setup__Token`), compared with `CryptographicOperations.FixedTimeEquals` over fixed-length hashes; no short-circuit on length. Header `X-Setup-Token`. | | NFR-SEC-02 | Token configured = `POST /Setup/owner` without or with a wrong token answers 401 problem details and creates nothing; not configured = behaviour exactly as today (existing hosts unaffected). `GET /Setup/status` returns `tokenRequired` only, never the token or its length. | | NFR-SEC-03 | Both setup endpoints get `[EnableRateLimiting("login")]` (5 per 60 s per the existing policy). A rejected token attempt is logged as a security event through the existing `SecurityEvents` mechanism (no token value, no email in the message). | | NFR-SEC-04 | The token is a deploy-time secret: only in `shared/env` (mode 600) on the Pi, never in the repository, workflow logs or appsettings; removable after the first administrator exists (the setup endpoint already refuses once initialised). | | NFR-SEC-05 | Secrets in general (DB password, JWT secret, Sentry DSN, setup token): environment only. Committed appsettings contain placeholders only (like `Api.SlpSoftware`). | | NFR-SEC-06 | The Andrea client starts with `Website:NoIndex=true` and `StrictSite` on test; production values are out of scope. | | NFR-SEC-07 | The pipeline never touches production for Andrea: no production deploy job, no production variables. | | NFR-SEC-08 | No new NuGet or npm dependencies in production code. | ### Added after the requirements approval: proxy-aware rate limiting (Bryan chose option B) Finding: the named limiters (`login`, `refresh`, `sentry-tunnel`, `offerings-public`) are single global buckets, and no host handles forwarded headers. Decision (Bryan, in chat): "meteen goed opzetten", changing existing hosts and pipelines is acceptable. | ID | Requirement | |---|---| | NFR-SEC-09 | Opt-in forwarded-headers support in the shared host: section `ForwardedHeaders` with `KnownProxies` (list of IP addresses). Empty or absent = middleware not added = behaviour of every host without a proxy unchanged. | | NFR-SEC-10 | Only the listed proxies are trusted (`X-Forwarded-For`, `X-Forwarded-Proto`; forward limit 1). Startup validation refuses unparsable addresses and any wildcard/any-address (`0.0.0.0`, `::`), so a client can never spoof its address to dodge a limiter. The middleware runs before everything that uses the client address or scheme (limiter, HTTPS redirection). | | NFR-SEC-11 | The four named limiters are partitioned per client address (resulting `RemoteIpAddress`; fallback key when unknown) instead of one global bucket, with the existing permit/window settings. A missing/unreadable address maps to one shared fallback partition, never to "unlimited". | | NFR-SEC-12 | Safe degradation: if a host has a proxy but `KnownProxies` is not (yet) configured, all callers share the proxy's address, which equals today's global bucket. No new failure mode. | | NFR-SEC-13 | Existing environments (`Api`, `Api.SlpSoftware`, `Api.Slave`) change only by this shared code; their deployment config stays as is until Bryan sets `ForwardedHeaders__KnownProxies__0` in their `shared/env` and the proxy-Pi blocks pass the headers (listed in the manual steps, test and production separately; production is not touched by this feature). | ## Deployment and availability | ID | Requirement | |---|---| | NFR-DEP-01 | Automatic deploy of the Andrea client to the test host on every push to master, and via the manual box `deploy_andrea_test` (Q1). Test only. | | NFR-DEP-02 | **Skip cleanly while Andrea is not set up**: the Andrea publish/deploy jobs only run when the Gitea variable `ASF_TEST_DEPLOY_ENABLED` equals `true` (Bryan sets it after the Pi and secrets exist). Until then the jobs are skipped, the existing pipeline stays green and unchanged, and nothing about Andrea can fail the run. (Secrets cannot be tested in an `if:`, hence the explicit variable.) | | NFR-DEP-03 | Separate jobs (Q2): `publish-asf-test` and `deploy-asf-test`, reusing `deploy-scp.yaml` unchanged; the `Api.SlpSoftware` jobs, the env block and `deploy-scp.yaml` stay byte-for-byte unchanged. A failure in an Andrea job must not block the SlpSoftware deploy and vice versa. | | NFR-DEP-04 | Deploy keeps the existing guarantees: timestamped release, atomic `current` switch, `/health` check, one previous release kept. Website delivery works in both variants (CI/web job writes into `shared/wwwroot-web`, or `shared/wwwroot-web` is a symlink to `/mnt/storage1/www/html/andreaslop-test`). | | NFR-DEP-05 | Smoke checks after deploy: `/health`, `/api/v1/System/capabilities` (no `Offerings`), one website page, headers (CSP, noindex). Observe forwarded-header / HTTP 1.0 behaviour behind the proxy Pi on the first deploy and report it. | | NFR-DEP-06 | linux-arm64 publish, `--self-contained false`, same as SlpSoftware. | ## Usability and theme (Q5 = B) | ID | Requirement | |---|---| | NFR-UX-01 | Theme = CSS variables overriding the existing admin design tokens, chosen at build time (`VITE_THEME`); unset reproduces today's admin exactly. Language default `nl` via `VITE_DEFAULT_LANGUAGE`; a user's stored choice still wins. | | NFR-UX-02 | **Brand colours exactly as the website; no contrast check (Bryan's explicit choice).** Trade-off recorded: some token pairs (for example muted text on a light background, or white text on a light brand accent) may fall below WCAG AA (4.5:1 text, 3:1 large text and UI components). This overrides the brief's accessibility hint. The theme does not invent extra colours to compensate; error and destructive states use the exact brand tokens if the website defines them, otherwise the existing admin tokens, so they stay as readable as the brand allows. A short list of pairs that fall below AA goes into the hand-back as information. | | NFR-UX-03 | Fonts (Marcellus, Jost) are self-hosted with the theme (no third-party font request, consistent with `font-src 'self'`). | ## Reliability and operations | ID | Requirement | |---|---| | NFR-OPS-01 | Own database `AndreaSlopFotografieTest`, user `AndreaSlopFotografie@localhost`; startup migration runs as today. | | NFR-OPS-02 | Systemd user unit with restart on failure; environment from `shared/env`. | | NFR-OPS-03 | Logs: warnings by default, `SlpModularCms.Website` at Information on test (U1). | | NFR-OPS-04 | Tests of the changed parts stay green; `Api.Tests` is run against a real MariaDB (Pi test DB or local) during U2 and reported in handback-u2. | ## Performance / scalability N/A beyond U1 (one small instance). The per-request file lookup is measured on the Pi if cheap (peer request). ## Property-based testing (partial) - PBT-02/03 in U2: setup-token validator. A presented token is accepted iff it equals the configured one (generated strings including unicode and empty); never throws; a prefix or different token is rejected. - PBT-07/08/09 follow U1's helpers and framework (FsCheck.Xunit, test-only; referenced from `Modules.Identity.Tests`).