11 KiB
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), U2andreaslop-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.WebsiteModeenum:SpaFallback(default, exactly today's behaviour) andPrerenderedPages.ApiandApi.SlpSoftwareuntouched; 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):/servesindex.html;/xservesx.html(andx/index.htmlif present).- Canonical form applies to known pages only. nginx uses a hard-coded page list; the host derives the known-page set from the
*.htmlfiles 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-.htmlform;/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.
/404and/404.htmlrequested directly answer 404 (no redirect).
- FR-U1-03 Unknown path. Serve
404.htmlwith status 404 (neverindex.html); plain 404 if404.htmlis missing. A directory without a page file is 404; no directory listing. - FR-U1-04 Reserved prefixes.
/admin,/api/v1,/healthare never handled by this middleware. An unknown API path remains an API 404 (today's website SPA fallback answers unknown/api/v1paths withindex.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, nofollowon all website responses (pages, assets, 404, redirects) and/robots.txtanswers 200 withUser-agent: */Disallow: /. - FR-U1-08 StrictSite policy. New policy name
StrictSiteinCspPolicyCatalog(inKnownPolicies, accepted byPathPolicyRulevalidation; unknown names still fail startup;StrictandRelaxedunchanged). 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'plusX-Frame-Options: DENYandReferrer-Policy: strict-origin-when-cross-origin. Origins come from the existing security-header configuration. An exact match is achievable (order is catalog-internal);Strictneed 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-originand 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.mdandREADME.mdfor 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.
ApiandApi.SlpSoftwaresuites 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 absolutehttp://redirects; website redirects are relative (nginxabsolute_redirect offparity). Verified in design.
3. Unit U2 - andreaslop-client
- FR-U2-01 Client project
SlpModularCms.Api.AndreaSlopFotografieunder Clients in the solution: thinProgram.csonCmsHost,WebsiteMode = PrerenderedPages, three-file appsettings (appsettings.json,appsettings.{Env}.json, uncommittedappsettings.local.json), own database, own dev port,SecurityHeaders:DefaultPolicy = StrictSitewith the Umami (https://analytics.slpsoftware.nl) and Sentry (https://o4511795618185216.ingest.de.sentry.io) origins,Website:NoIndex = truefor test. - FR-U2-02 Module set = module projects the client references (no config filter). Determine and report the minimum (Identity; is Availability required?).
Offeringsnot referenced;/api/v1/System/capabilitiesmust 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_THEMEselects it at build time (unset = today's look). NewVITE_DEFAULT_LANGUAGE(nlfor 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 isfont-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 forApi.SlpSoftwareis 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
- 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.
- Interaction of
UseHttpsRedirection/ forwarded headers with the reverse-proxy Pi. - Whether
Availabilityis required next toIdentityfor the admin. - Where the setup-token check lives (Identity module vs. host) without changing existing hosts.
- Whether compression is limited to the website mount (proposal: yes, avoids BREACH-style exposure on authenticated API responses).