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

11 KiB

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