Files

7.4 KiB

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