Files
slp-modular-cms/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/requirements.md
T

72 lines
11 KiB
Markdown

# Requirements - andreaslop-site-hosting
## 1. Intent analysis
- **User request**: Serve Andrea's prerendered website (`AndreaSlopFotografie`, TanStack Start output) from SlpModularCms with nginx-parity behaviour, a strict CSP, and a Dutch themed admin; deploy to the **test** host. Brief: `aidlc-docs/_shared/handoffs/cms-api-foundation-brief-u1-u2.md`. Requester session: "CMS & API"; approver: Bryan.
- **Request type**: New feature / enhancement of the shared host + new client.
- **Scope**: Multiple components (Core hosting, Security headers, new Client project, Frontend build/theme, CI/CD).
- **Complexity**: Complex. **Depth**: Comprehensive.
- **Units**: U1 `core-site-hosting` (shared host, no behaviour change for existing clients), U2 `andreaslop-client`. Hand-back after each unit; **U2 starts only after the requester's "go"**.
- **Fixed decisions**: brief section 2 (D1-D7) and Q1-Q9 in `requirement-verification-questions.md` (answers relayed by the peer session; Bryan confirms at the approval gate).
## 2. Unit U1 - core-site-hosting (shared host)
### Functional
- **FR-U1-01 WebsiteMode.** `CmsHostOptions.WebsiteMode` enum: `SpaFallback` (default, exactly today's behaviour) and `PrerenderedPages`. `Api` and `Api.SlpSoftware` untouched; their tests unchanged.
- **FR-U1-02 Path resolution (pure).** A total function (never throws, never leaves the website root, rejects traversal incl. encoded/backslash/NUL/over-long paths) from (request path, file-exists predicate) to `ServeFile | Redirect(301, target) | NotFound`. Rules (nginx parity, BR-HST-01..11 in the website repo):
- `/` serves `index.html`; `/x` serves `x.html` (and `x/index.html` if present).
- **Canonical form applies to known pages only.** nginx uses a hard-coded page list; the host derives the known-page set from the `*.html` files present in the website root. A case-insensitive variant (`/Over-Mij`, `/over-mij.html`, `/over-mij/`, `/index`, `/index.html`) gets one 301 to the lowercase, no-`.html` form; `/index*` redirects to `/`. Query string preserved. Redirect targets always come from the known-page set, never from the raw request.
- Trailing slashes on any other path are stripped with a 301 (not for `/`). A target starting `//` or `/\` or containing control characters is treated as unknown (open-redirect guard, BR-HST-06). A path with a leading backslash is 404.
- Hashed asset names are never lower-cased or redirected. Paths that look like files (have an extension) are served as files or 404, never fall back to a page.
- `/404` and `/404.html` requested directly answer 404 (no redirect).
- **FR-U1-03 Unknown path.** Serve `404.html` with status **404** (never `index.html`); plain 404 if `404.html` is missing. A directory without a page file is 404; no directory listing.
- **FR-U1-04 Reserved prefixes.** `/admin`, `/api/v1`, `/health` are never handled by this middleware. An unknown API path remains an API 404 (today's website SPA fallback answers unknown `/api/v1` paths with `index.html`; this mode must not).
- **FR-U1-05 Cache-Control.** Pages and other root files: `no-cache`. Files under `/assets/`: `public, max-age=31536000, immutable`.
- **FR-U1-06 Compression.** Built-in response compression (no new dependency) for the text types in `compressibleTypes.ts` (html, js, css, svg, json, xml, txt); not for already-compressed types; `Vary: Accept-Encoding`. Website mount only (see open point 5).
- **FR-U1-07 Indexing policy.** Setting `Website:NoIndex` (default false), bound to a validated options class. When true: `X-Robots-Tag: noindex, nofollow` on all website responses (pages, assets, 404, redirects) and `/robots.txt` answers 200 with `User-agent: *` / `Disallow: /`.
- **FR-U1-08 StrictSite policy.** New policy name `StrictSite` in `CspPolicyCatalog` (in `KnownPolicies`, accepted by `PathPolicyRule` validation; unknown names still fail startup; `Strict` and `Relaxed` unchanged). Directives in the exact order of the site's current policy so the string matches byte for byte:
`default-src 'self'; script-src 'self' <script origins>; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self' <connect origins>; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'`
plus `X-Frame-Options: DENY` and `Referrer-Policy: strict-origin-when-cross-origin`. Origins come from the existing security-header configuration. An exact match is achievable (order is catalog-internal); `Strict` need not change.
- **FR-U1-09 Other headers.** Verify and test that website responses carry `Strict-Transport-Security: max-age=31536000; includeSubDomains`, `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin` and the CSP, including on 301, 404, assets and robots.txt.
- **FR-U1-10 Pipeline order.** Security headers before static content; compression before the website mount; website 404 handling last, after API routes; documented in `CmsHost`.
- **FR-U1-11 Docs.** Update `WEBSITE_WORKSPACE.md` and `README.md` for the new mode and settings.
### Acceptance (U1)
- Unit tests and property-based tests (partial PBT, section 5): path resolution never escapes the root, canonicalisation is idempotent, reserved prefixes never resolve, policy round trip.
- `Api` and `Api.SlpSoftware` suites green, behaviour unchanged (regression run recorded).
- Hand-back note (brief section 7) written and sent to "CMS & API".
- Proxy awareness: the test site sits behind a reverse-proxy Pi that terminates TLS. Existing `UseHttpsRedirection` / forwarded-header handling must not cause redirect loops or absolute `http://` redirects; website redirects are relative (nginx `absolute_redirect off` parity). Verified in design.
## 3. Unit U2 - andreaslop-client
- **FR-U2-01 Client project** `SlpModularCms.Api.AndreaSlopFotografie` under **Clients** in the solution: thin `Program.cs` on `CmsHost`, `WebsiteMode = PrerenderedPages`, three-file appsettings (`appsettings.json`, `appsettings.{Env}.json`, uncommitted `appsettings.local.json`), own database, own dev port, `SecurityHeaders:DefaultPolicy = StrictSite` with the Umami (`https://analytics.slpsoftware.nl`) and Sentry (`https://o4511795618185216.ingest.de.sentry.io`) origins, `Website:NoIndex = true` for test.
- **FR-U2-02 Module set** = module projects the client references (no config filter). Determine and report the minimum (Identity; is Availability required?). `Offerings` not referenced; `/api/v1/System/capabilities` must not list it.
- **FR-U2-03 Admin theme.** `frontend/themes/asf/` with CSS overriding the existing design tokens (colours, radius, font), plus logo and favicon. `VITE_THEME` selects it at build time (unset = today's look). New `VITE_DEFAULT_LANGUAGE` (`nl` for Andrea; English stays selectable). Palette: paper `#faf7f2` / `#f1ebe2` / `#e8e0d5`, ink `#232120` / `#55504b` / `#8a827a`, line `#e2dad0`, accent `#7f8b76`, accent-deep `#5f6a58` (text/buttons), accent-deeper `#475042`, sand `#d9cdbc`, error `#a4443a`. Fonts Marcellus (headings) and Jost (body) with the site's fallbacks, **self-hosted** (the admin's CSP is `font-src 'self'`). Scope per Q5: tokens + logo + favicon only, no layout or component changes. Contrast stays accessible (destructive and focus-ring colours readable on paper).
- **FR-U2-04 CI/CD.** Build the admin per deployable client with its `VITE_THEME`, `VITE_DEFAULT_LANGUAGE`, `VITE_APP_TITLE`; publish the new host; deploy to the **test** host with the existing atomic release switch; `wwwroot/web/` stays outside the swapped release directory so the site survives every CMS deploy. The production path for `Api.SlpSoftware` is not touched.
- **FR-U2-05 Test deploy** (Q3, relayed): the pipeline may deploy to the test host, and this session may start the test deploy itself once pipeline and Pi are ready - **test only, never production**. Bryan's go is confirmed in this session before the first deploy.
- **FR-U2-06 Host provisioning** (Q4): the Raspberry Pi accounts exist, but paths, secrets, environment variables, database, service unit and reverse proxy are not set up yet. The infrastructure design lists every remaining step as a manual checklist for Bryan. Pi inventory comes via "CMS & API" from "Pi-Main - Server"; this session does not contact that session directly.
- **FR-U2-07 First-admin setup token** (Q1=B): assess the existing setup flow (who can call it while no admin exists) and add an optional one-time setup token read from configuration. When configured, the setup endpoint requires it; when not configured, behaviour is unchanged for existing hosts. Constant-time comparison, never logged, covered by the same rate limiting as login. Tests: no token configured, wrong token, correct token, setup after the first admin exists (rejected). The token is a secret supplied outside the repo.
- **FR-U2-08 Auth** otherwise unchanged (Identity module; invitations after the first admin). Login rate limiting stays.
### Acceptance (U2)
Host starts on test with its own database; `/admin` shows Andrea's theme in Dutch; first-admin setup and login work; `/api/v1/System/capabilities` has no `Offerings`; `/health` is green; `Api.SlpSoftware` still builds and deploys unchanged; hand-back note written.
## 4. Out of scope
Production deployment, the `Master` module for Andrea, extra roles, SSR, CMS-driven site content, a configuration-based module filter, changes to the website repo, theme editing in the admin, serving the theme from the API.
## 5. Cross-cutting
- **Security Baseline**: enforced (blocking): path input validation, secure headers, no secrets in the repo, rate limiting, safe error handling, no sensitive data in logs, no new packages planned.
- **Property-based testing**: partial mode, rules PBT-02, 03, 07, 08, 09 (pure functions: path resolution, canonical idempotence, policy round trip). Seeds are logged on failure and reproducible; tooling follows the existing test framework (decided in NFR/Code Generation).
- **Per-unit build/test**: build and run tests after each unit's code generation.
- **Git**: branch `feature/andreaslop-site-hosting`, commits per unit, no push until Bryan asks, one PR after U2 (Q2=A).
- **Operations phase**: yes (Q9=A): deployment and monitoring setup and production readiness, assessed for the test environment. Production itself stays out of scope.
- **User Stories**: skipped (Q6).
- **Language**: documentation English, conversation Dutch.
- **Boundaries**: website repo is read-only; no production changes; Pi contact only through "CMS & API".
## 6. Open points to resolve in design
1. Where the known-page set is built (scan at startup vs. per-request lookup) and how it refreshes when a new site build is deployed.
2. Interaction of `UseHttpsRedirection` / forwarded headers with the reverse-proxy Pi.
3. Whether `Availability` is required next to `Identity` for the admin.
4. Where the setup-token check lives (Identity module vs. host) without changing existing hosts.
5. Whether compression is limited to the website mount (proposal: yes, avoids BREACH-style exposure on authenticated API responses).