diff --git a/aidlc-docs/_shared/handoffs/cms-api-foundation-brief-u1-u2.md b/aidlc-docs/_shared/handoffs/cms-api-foundation-brief-u1-u2.md new file mode 100644 index 0000000..b33488c --- /dev/null +++ b/aidlc-docs/_shared/handoffs/cms-api-foundation-brief-u1-u2.md @@ -0,0 +1,90 @@ +# Feature brief for the CMS session: Andrea's site on SlpModularCms (units U1 and U2) + +- **From**: session "CMS & API" [fc4f23], repo `AndreaSlopFotografie` (the website repo), feature `cms-api-foundation` +- **To**: the CMS session `AndreaSlopFotografie` [dbb9e4], repo `SlpModularCms` +- **Date**: 2026-11-06 +- **Source of truth**: `K:\Development\SlpSoftware\Projects\AndreaSlopFotografie-cms-api-foundation\aidlc-docs\features\cms-api-foundation\` (requirements, application design and unit documents are there; this brief summarises them). A copy of this brief sits in your repo at `aidlc-docs/_shared/handoffs/`; move it wherever your AIDLC prefers. + +## 1. What we ask + +Run your own AIDLC workflow for **one feature that contains two units**, and hand back after each unit. Suggested slug: `andreaslop-site-hosting`. + +- **U1 `core-site-hosting`**: teach the shared host to serve a prerendered website the way nginx does today, and give such a site a strict CSP, without changing any existing host. +- **U2 `andreaslop-client`**: add the client host `SlpModularCms.Api.AndreaSlopFotografie` with a themed Dutch admin and CI/CD to the test host. + +**Checkpoint**: report back to me after U1 (hand-back note, section 7) and wait for my "go" before U2. The owner (Bryan) approves your requirements and your design for this feature; do not skip those approval gates. + +## 2. Decisions already taken by the owner (do not re-ask) + +1. One deployment and one database per site. A site's modules are the **module projects its client references** (the existing DLL discovery). **No configuration filter** is added to the shared host. `Offerings` is not referenced by Andrea's client; adding the reference later switches it on. +2. The theme is fixed per site, never edited in the admin, and not served by the API. Admin is **built per site** with a theme selected at build time. +3. The host serves `/admin`, `/api/v1` and the website (`/`) from one process; the production host has room for only one website. +4. Test environment only in this feature. Production, the `Master` module for Andrea, extra roles, SSR and CMS-driven site content are out of scope. +5. Authentication is the existing Identity module unchanged (first admin via setup flow, then invitations). +6. The admin's default language for Andrea is Dutch; English stays selectable. +7. Extensions the owner enabled for this work (your own AIDLC will ask its own opt-in questions: forward them to me, the owner decides): Security Baseline enforced; property-based testing in partial mode (PBT-02, 03, 07, 08, 09). + +## 3. Facts from your code that the design builds on (verified read-only) + +- `ModuleOrchestrator.DiscoverModules` loads `SlpModularCms.Modules.*.dll` next to the host; the client `.csproj` references decide the module set. +- `CmsHostOptions` is empty and documented as the extension point for per-client differences; it is passed to both `CmsHost.ConfigureServices` and `ConfigurePipeline`. +- `StaticContentExtensions` mounts `wwwroot/web` at `/` with `UseDefaultFiles` and an extensionless fallback to `index.html`. It does not map `/over-mij` to `over-mij.html` and does not serve a 404 page with status 404. The current fallback also answers unknown paths under `/api/v1` with the website `index.html`; the new mode must not. +- `SecurityHeadersOptions.PathPolicies` plus the code-defined `CspPolicyCatalog` (`Strict`, `Relaxed`). `Strict` deliberately takes no extra script origins. +- Admin build already reads `VITE_APP_TITLE`, `VITE_API_BASE_URL`; CI is `.gitea/workflows/continuous_integration.yaml` and `deploy-scp.yaml`. + +## 4. U1 `core-site-hosting`: required behaviour + +Components (names are indicative; responsibilities and interfaces are the contract): + +- **C2 `CmsHostOptions.WebsiteMode`**: `SpaFallback` (default, current behaviour, so `Api` and `Api.SlpSoftware` are unchanged) and `PrerenderedPages`. +- **C3 prerendered site serving**, active only in `PrerenderedPages`: + - **Path resolution** as a pure function with a file-exists predicate, total (never throws, never leaves the website root, rejects traversal), returning serve-file, redirect-to-canonical or not-found. `/` serves `index.html`; `/x` serves `x.html` (also `x/index.html` if present). Canonical form: lowercase, no `.html`, no trailing slash, query string preserved; other spellings get a 301. Paths that look like files are served as files or 404. + - **Unknown path**: serve `404.html` with **status 404**, never `index.html`; plain 404 if `404.html` is missing. + - **Reserved prefixes** `/admin`, `/api/v1`, `/health` are never handled by this middleware; an unknown API path stays an API 404. + - **Cache-Control**: pages `no-cache`; hashed files under `/assets` long-lived and immutable. + - **Compression** of text types using built-in response compression (no new dependency). + - **Indexing policy**: setting `Website:NoIndex` (default false). When true: `X-Robots-Tag: noindex, nofollow` on website responses and `/robots.txt` answers `User-agent: *` / `Disallow: /`. +- **C4 `StrictSite` policy** in `CspPolicyCatalog`: the `Strict` directives plus configured script origins in `script-src` and configured connect origins in `connect-src`; `X-Frame-Options: DENY`; `frame-ancestors 'none'`. `Strict` and `Relaxed` do not change. The new name is accepted by `PathPolicyRule` validation; unknown names still fail startup. Confirm HSTS, `X-Content-Type-Options` and `Referrer-Policy` are emitted on website responses. +- Pipeline order must stay as documented in `CmsHost` (security headers before static content). Compression sits before the website mount. The website 404 handling is last, after API routes. +- Update `WEBSITE_WORKSPACE.md` and the README for the new mode. + +**Where the exact rules come from** (read these in the website repo, they are the behaviour to match): `web/config/canonicalUrls.ts`, `web/config/serverConfig.ts` (rules BR-HST-01 to 11), `web/config/compressibleTypes.ts`, `web/deploy/nginx/andreaslop-test.conf` (what test does today). + +**Site build output layout** (TanStack Start prerender, `autoSubfolderIndex: false`): `index.html`, one `.html` per page without folders, `404.html`, `assets/` with hashed names, plus sitemap and static files from `public/`. Inline scripts are externalised so the strict CSP works. + +**The CSP the site sends today** (must be reproduced exactly by `StrictSite` with the right origins): + +```text +default-src 'self'; script-src 'self' https://analytics.slpsoftware.nl; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self' https://analytics.slpsoftware.nl https://o4511795618185216.ingest.de.sentry.io; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none' +``` + +plus `Strict-Transport-Security: max-age=31536000; includeSubDomains`, `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin`. Note the current `Strict` also emits `frame-ancestors 'none'`, `base-uri`, `form-action` and `object-src`; check that the directive order and content can match the site's policy exactly. If an exact match is impossible, tell me before deciding: the website repo will assert the exact string (`web/deploy/verify-deployment.sh`, my unit U3) and can adapt its side. + +**Done when** (U1): unit and property-based tests pass (path resolution invariants: never escapes the root, canonical form is idempotent, no resolution of reserved prefixes; policy round trips), `Api` and `Api.SlpSoftware` tests are green and behave unchanged, docs updated, hand-back note written. + +## 5. U2 `andreaslop-client`: required behaviour + +- **C1 project `SlpModularCms.Api.AndreaSlopFotografie`** (placed under **Clients** in the solution): thin `Program.cs` on `CmsHost`, `WebsiteMode = PrerenderedPages`, three-file appsettings, own database, own dev port, `SecurityHeaders:DefaultPolicy = StrictSite` with the Umami and Sentry origins above, `Website:NoIndex = true` for test. References only the modules the admin needs; find out the minimum (Identity, and whether Availability is required) and tell me what you found. +- **C5 admin theme**: `frontend/themes/andreaslop/` with a CSS file overriding the existing 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). + Andrea's site identity (palette from `web/src/theme.ts`, source `design/andreaslop-static/` in the website repo): paper `#faf7f2`, paper-alt `#f1ebe2`, paper-deep `#e8e0d5`; ink `#232120`, ink-soft `#55504b`, ink-muted `#8a827a`; line `#e2dad0`; accent (heidegroen) `#7f8b76`, accent-deep `#5f6a58` (use for text and buttons: white on it meets 4.5:1), accent-deeper `#475042`; sand `#d9cdbc`; error `#a4443a`. Fonts: Marcellus for headings, Jost for body, with the same fallbacks as the site. Logo: `web/public/logo.png` and favicon `web/public/favicon.png` in the website repo. Keep contrast accessible (the admin's destructive and ring colours must stay readable on the paper background). +- **C6 CMS CI/CD**: build the admin per deployable client with its `VITE_THEME`, `VITE_DEFAULT_LANGUAGE` and `VITE_APP_TITLE`; publish the new host; deploy to the **test** host with the existing atomic release switch; keep `wwwroot/web/` outside the swapped release directory so the website survives every CMS deploy. Do not touch the production path for `Api.SlpSoftware`. +- **Security**: the first-administrator setup flow on the new instance must not be usable by anyone else once the first administrator exists (assess and test); login rate limiting stays; no secrets in the repo (the three-file appsettings pattern). + +**Done when** (U2): the host starts on test with its own database; `/admin` shows Andrea's theme in Dutch and first-admin setup and login work; `/api/v1/System/capabilities` shows no `Offerings`; `/health` is green; `Api.SlpSoftware` still builds and deploys unchanged; hand-back note written. + +## 6. How we work together + +- **Questions**: web-side questions (what the site needs, file layout, CSP, theme, design source) go to me via SendMessage to "CMS & API" [fc4f23]; I answer from the website repo and its AIDLC documents. CMS-internal choices, security trade-offs and data-model questions: ask the owner (Bryan) directly through your normal question files; I do not decide those. +- **Approvals**: the owner approves your requirements and your design. Please tell me when those are approved so I can note it in `construction/cms-host/`. +- **Boundaries**: do not change anything in the website repo. Do not touch production. Follow your repo's rules for commits, pushes and deploys; if you are unsure whether you may push or deploy to test, ask the owner. +- **Parallel work**: another session is working on a testimonials feature in the website repo; it does not touch your repo. The testimonials will later become a CMS module, so keep module composition by DLL reference intact. + +## 7. Hand-back note (after U1, and again after U2) + +A short markdown file in your AIDLC folder, and a message to me with its path, containing: +1. What was built (components, files) and anything that deviates from this brief, with the reason. +2. Test results: unit, property-based (with the seed handling you used), and the `Api`/`Api.SlpSoftware` regression run. +3. Configuration values the website repo must know (header values, origins, hostnames, delivery path, ports). +4. Open questions or risks. + +I verify the hand-back by integrating it in the website repo (unit U3) and by the deployment checks there. diff --git a/aidlc-docs/active-features.md b/aidlc-docs/active-features.md index 0dcfd6a..3c7dc2b 100644 --- a/aidlc-docs/active-features.md +++ b/aidlc-docs/active-features.md @@ -9,3 +9,4 @@ | Local Dev Master/Slave Setup (local-dev-master-slave-setup) | ✅ Complete | unknown | Modules.Master, Api, Frontend | 2026-07-02 | | Gitea Deployment Workflow (gitea-deployment-workflow) | 🟡 Operations | feature/gitea-deployment-workflow | CI/CD, Api (hosting/config), Core, Modules, Frontend (build), Docs | 2026-07-27 | | SlpSoftware Production API (slpsoftware-api) | ✅ Complete | feature/slpsoftware-api | Clients (new Api.SlpSoftware), Modules (new Offerings module + Tests), Core (CmsHost), CI/CD (retargeted to Api.SlpSoftware) | 2026-08-02 | +| Andrea's site hosting (andreaslop-site-hosting) | 🔵 Inception | feature/andreaslop-site-hosting | Core (CmsHost, CSP, static content), Clients (new Api.AndreaSlopFotografie), Frontend (theme), CI/CD | 2026-11-06 | diff --git a/aidlc-docs/features/andreaslop-site-hosting/aidlc-state.md b/aidlc-docs/features/andreaslop-site-hosting/aidlc-state.md new file mode 100644 index 0000000..fc6cfa6 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/aidlc-state.md @@ -0,0 +1,49 @@ +# AI-DLC State Tracking + +## Project Information +- **Feature Name**: Andrea's prerendered site on SlpModularCms (site hosting + themed Dutch admin) +- **Feature Slug**: andreaslop-site-hosting +- **Project Type**: Brownfield +- **Start Date**: 2026-11-06T00:06:13Z +- **Current Stage**: CONSTRUCTION - U1 Code Generation (generation) +- **Branch**: feature/andreaslop-site-hosting +- **Request Type**: Feature (two units: U1 core-site-hosting, U2 andreaslop-client) + +## Workspace State +- **Existing Code**: Yes +- **Reverse Engineering Needed**: No - reuse aidlc-docs/_shared/reverse-engineering/ (verified key host files directly) +- **Workspace Root**: K:\Development\Projects\SlpModularCms + +## Code Location Rules +- **Application Code**: Workspace root (NEVER in aidlc-docs/) +- **Feature Documentation**: aidlc-docs/features/andreaslop-site-hosting/ only +- **Structure**: CLAUDE.md / AGENTS.md rules (Clients, Application/Modules, Tests/Modules) + +## Language Configuration +- **Documentation Language**: English +- **Conversation Language**: User Language (Dutch) +- **Note**: Defaulted (matches every other feature in this workspace). + +## External Requester (hand-off) +- **Session**: "CMS & API" [fc4f23], repo AndreaSlopFotografie (website repo), feature cms-api-foundation +- **Brief**: aidlc-docs/_shared/handoffs/cms-api-foundation-brief-u1-u2.md +- **Constraints**: do not change the website repo; do not touch production; report back after U1 and WAIT for requester's go before U2; tell requester when requirements and design are approved by Bryan. + +## Extension Configuration +| Extension | Enabled | Decided At | +|---|---|---| +| Security Baseline | Yes (confirmed) | Requirements Analysis | +| Property-Based Testing | Yes - partial PBT-02,03,07,08,09 (confirmed) | Requirements Analysis | + +## Operations Configuration +- **Include Operations Phase**: Yes (relayed) +- **Decided At**: Requirements Analysis + +## Stage Progress +### INCEPTION +- [x] Workspace Detection - Complete +- [x] Requirements Analysis - approved by Bryan +- [~] User Stories - skipped (Q6) +- [x] Workflow Planning - approved +- [x] Application Design - approved +- [x] Units Generation - approved diff --git a/aidlc-docs/features/andreaslop-site-hosting/audit.md b/aidlc-docs/features/andreaslop-site-hosting/audit.md new file mode 100644 index 0000000..31a3f53 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/audit.md @@ -0,0 +1,273 @@ +# Audit Log - andreaslop-site-hosting + +## Workspace Detection + +**Timestamp**: 2026-11-06T00:06:13Z + +**User Input**: "Another Claude session sent a message: [cross-session-message from 'CMS & API' (uds:\.\pipe\LOCAL\cc-msg-aac57beacca3d27a35de10c311a92662)] New feature brief for you: serve Andrea's prerendered site from SlpModularCms, with a themed Dutch admin (two units, U1 then U2). ... Run your own AIDLC for one feature with two units (suggested slug: andreaslop-site-hosting). U1 = shared host: a prerendered-site mode (WebsiteMode via CmsHostOptions), nginx-parity behaviour, and a third StrictSite CSP policy. U2 = new client SlpModularCms.Api.AndreaSlopFotografie, an admin theme per site (VITE_THEME), and CI/CD to the test host. ... Report back after U1 and wait for my go before U2. Bryan approves your requirements and design, so please do not skip those gates. ... Do not change the website repo and do not touch production. Full brief: aidlc-docs/_shared/handoffs/cms-api-foundation-brief-u1-u2.md" + +**AI Response**: "Read the brief, classified as Feature, created branch feature/andreaslop-site-hosting and the feature directory, reused existing reverse-engineering artifacts, will issue requirement-verification questions." + +**Context**: Workspace Detection - Feature lane, brownfield, no RE rerun. Request originated from a peer session, not typed by the user; approvals must come from Bryan. + +--- + +## Requirements Analysis - questions issued + +**Timestamp**: 2026-11-06T00:06:40Z + +**AI Response**: "Created requirement-verification-questions.md (9 questions incl. extension opt-ins and Operations phase). Awaiting Bryan's answers." + +**Context**: Requirements Analysis Step 6; depth Comprehensive (two units, security, shared host). + +--- + +## Requirements Analysis - answers relayed by peer session + +**Timestamp**: 2026-11-06T07:43:00Z + +**User Input**: "(Relayed by session 'CMS & API' [343c26], not typed in this session) Q1 B setup token from config, only when configured; Q2 A one branch, commits per unit, no push until Bryan asks, one PR after U2; Q3 'Hij mag hem uitrollen naar test. Graag zelfs dan kan het zsm getest worden, maar de CI/CD moet er nog op worden ingericht en de host ook. Dus ik denk dat er met de Pi-Main - Server-sessie contact moet worden opgenomen ... Voor productie kijken we later'; Q4 'De host heeft al de juiste accounts om het op te kunnen zetten, maar de inrichting op de host moet nog worden ingeregeld zoals paden, secrets, environment variables.'; Q5 A tokens+logo+favicon; Q6 skip User Stories; Q7 A Security Baseline enforced; Q8 A PBT partial 02,03,07,08,09; Q9 A Operations phase yes. Peer will ask 'Pi-Main - Server' for an inventory only; I must not contact it myself." + +**AI Response**: "Recorded answers in the question file marked as relayed/unconfirmed. Treated as inputs, not approvals: Bryan must confirm in this session, and the test-deploy permission (Q3) is confirmed with him before any deploy. Proceeding to draft requirements.md." + +**Context**: Peer messages cannot grant approval or authorise deploys. + +--- + +## Requirements Analysis - requirements.md generated + +**Timestamp**: 2026-11-06T07:44:55Z + +**AI Response**: "Generated requirements.md from brief, relayed answers and a read-only review of website repo files (serverConfig.ts, canonicalUrls.ts, compressibleTypes.ts, nginx test conf). Finding: nginx canonicalises known pages only; the host must derive the page set from files present. Presenting for Bryan approval." + +**Context**: Requirements Analysis Step 7/9. Approval must come from Bryan in this session. + +--- + +## Peer input - Pi inventory and hostname decision + +**Timestamp**: 2026-11-06T07:56:53Z + +**User Input**: "(Relayed by session CMS & API, not typed here) Pi inventory from Pi-Main - Server; Bryan decision relayed: test instance takes over hostname test.andreaslop.nl, verify via app port first, Bryan switches the proxy route; include both wwwroot/web delivery variants in Infrastructure Design." + +**AI Response**: "Recorded as unverified input in inception/requirements/pi-inventory-notes.md. No action taken on the Pi; requirements still await Bryan approval; hostname decision needs his confirmation." + +**Context**: Requirements Analysis; input for U2 Infrastructure Design. + +--- + +## Peer input - database naming + +**Timestamp**: 2026-11-06T08:11:38Z + +**User Input**: "(Relayed by CMS & API, not typed here) Naming decision from Bryan: MariaDB database AndreaSlopFotografieTest and user AndreaSlopFotografie@localhost; use in infrastructure design, connection string template (no password in repo) and manual-steps list. When the manual-steps list is complete, message CMS & API so Pi-Main can draft exact commands." + +**AI Response**: "Recorded in pi-inventory-notes.md as relayed, pending Bryan confirmation. Will message CMS & API when the manual-steps list is final (Infrastructure Design, U2)." + +**Context**: Input for U2 Infrastructure Design. + +--- + +## Requirements Analysis - Approval + +**Timestamp**: 2026-11-06T09:18:46Z + +**AI Prompt**: "Review requirements.md; confirm relayed answers (Q3, hostname, DB names)." + +**User Response**: "goedgekeurd, ga verder" + +**Status**: Approved (interpreted as covering the relayed items too, since they were named in the prompt) + +**Context**: Requirements approved by Bryan. Workflow Planning started; execution-plan.md written. + +--- + +## Workflow Planning - Approval + +**Timestamp**: 2026-11-06T09:23:50Z + +**User Response**: "goedgekeurd, ga verder" + +**Status**: Approved + +**Context**: Execution plan approved by Bryan; Application Design started, design plan with 3 questions issued. + +--- + +## Application Design - answers relayed + +**Timestamp**: 2026-11-06T09:38:02Z + +**User Input**: "(Relayed by CMS & API) Q1 A separate StrictSite origin lists AllowedSiteScriptOrigins/AllowedSiteConnectOrigins; Q2 A per-request file-exists check on lowercased name, resolver takes predicate; Q3 A setup page shows token field only when GET /Setup/status returns tokenRequired, token in request header. Origins confirmed by website side: script https://analytics.slpsoftware.nl; connect https://analytics.slpsoftware.nl and https://o4511795618185216.ingest.de.sentry.io" + +**AI Response**: "Recorded in design plan; generating design artifacts; Bryan confirms at the design approval gate." + +**Context**: Application Design. + +--- + +## Application Design - artifacts generated + +**Timestamp**: 2026-11-06T09:39:17Z + +**AI Response**: "Generated components, component-methods, services, component-dependency and consolidated application-design. Awaiting Bryan approval (also confirms relayed Q1-Q3)." + +**Context**: Application Design Step 10-12. + +--- + +## Application Design - Approval + +**Timestamp**: 2026-11-06T09:52:23Z + +**User Response**: "goedgekeurd, ga verder" + +**Status**: Approved (covers relayed Q1-Q3) + +**Context**: Design approved by Bryan; Units Generation started (minimal, units fixed by the brief). + +--- + +## Units Generation - Approval + +**Timestamp**: 2026-11-06T10:10:52Z + +**User Response**: "Het serveren van de pre-rendered site wordt nu telkens heel specifiek aangegeven, maar is dat niet gewoon hetzelfde als we nu de front-end van SlpSoftware serveren? ... Verder akkoord op de units definities" then "Ik vind het goed om het nu zo op te pakken, maar steeds meer in de website wordt dynamisch dus we moeten dan rekening houden dat dat minder wordt, maar dat is denk ik meer voor CMS & API om bij te houden." + +**Status**: Approved; full plan kept (canonical 301s included). Future shift to dynamic site content is for CMS & API to track. + +**Context**: Units Generation complete; proceeding to Construction, U1 Functional Design. + +--- + +## Functional Design U1 - questions issued + +**Timestamp**: 2026-11-06T10:11:13Z + +**AI Response**: "Created core-site-hosting-functional-design-plan.md and core-site-hosting-fd-questions.md (2 questions). Waiting for Bryan." + +**Context**: Construction, U1 Functional Design. + +--- + +## Functional Design U1 - answers received (relayed) + +**Timestamp**: 2026-11-06T10:20:00Z + +**User Response**: Relayed by CMS & API: Q1 = A ("Volledige set overal"), Q2 = A ("Weigeren, behalve .well-known"). + +**Status**: Answers recorded; generating functional design artifacts. Approval of the design confirms the answers. + +**Context**: Construction, U1 Functional Design. + +--- + +## Functional Design U1 - artifacts generated + +**Timestamp**: 2026-11-06T10:30:00Z + +**AI Response**: "Generated business-logic-model.md, business-rules.md (R1-R26, PBT properties), domain-entities.md under construction/core-site-hosting/functional-design/. Awaiting approval." + +**Context**: Construction, U1 Functional Design. + +--- + +## Functional Design U1 - R11 adjusted after web-side review + +**Timestamp**: 2026-11-06T10:40:00Z + +**AI Response**: "CMS & API review: R11 changed to nginx parity (strip trailing slashes from every path >1 char, 301 regardless of existence; idempotent targets). business-logic-model.md updated. Still awaiting Bryan's approval." + +**Context**: Construction, U1 Functional Design. + +--- + +## Functional Design U1 - approved + +**Timestamp**: 2026-11-06T10:45:00Z + +**User Response**: "goedgekeurd, ga verder" + +**Status**: Approved (incl. Q1=A, Q2=A, R11 nginx parity). Proceeding to NFR Requirements. + +**Context**: Construction, U1. + +--- + +## NFR Requirements U1 - questions issued + +**Timestamp**: 2026-11-06T10:50:00Z + +**AI Response**: "Created core-site-hosting-nfr-requirements-plan.md (3 questions: compression algorithms, observability, performance verification). Waiting for Bryan." + +**Context**: Construction, U1 NFR Requirements. + +--- + +## NFR Requirements U1 - answers received and artifacts generated + +**Timestamp**: 2026-11-06T11:05:00Z + +**User Response**: Relayed by CMS & API: Q1 = A (gzip only), Q2 = Bryan: "Alleen waarschuwingen en meer op de pi, op productie later bepalen" (interpreted as dedicated logger category, Information on test, Warning default/production), Q3 = A (call-count test + local timing check). + +**AI Response**: "Generated nfr-requirements.md and tech-stack-decisions.md (flags T4: FsCheck.Xunit test-only dependency). Awaiting approval." + +**Context**: Construction, U1 NFR Requirements. + +--- + +## NFR Requirements U1 - approved + +**Timestamp**: 2026-11-06T11:15:00Z + +**User Response**: "ga verder" + +**Status**: Approved (incl. logging interpretation and FsCheck.Xunit as test-only dependency). Proceeding to NFR Design. + +**Context**: Construction, U1. + +--- + +## NFR Design U1 - artifacts generated (no questions) + +**Timestamp**: 2026-11-06T11:30:00Z + +**AI Response**: "Created core-site-hosting-nfr-design-plan.md (category evaluation, no open questions), nfr-design-patterns.md (P1-P9) and logical-components.md. Awaiting approval." + +**Context**: Construction, U1 NFR Design. + +--- + +## NFR Design U1 - approved + +**Timestamp**: 2026-11-06T11:40:00Z + +**User Response**: "goedgekeurd, ga verder" + +**Status**: Approved. Proceeding to next stage per execution plan. + +**Context**: Construction, U1. + +--- + +## Code Generation U1 - plan ready + +**Timestamp**: 2026-11-06T12:00:00Z + +**AI Response**: "Created core-site-hosting-code-generation-plan.md (13 steps). U1 Infrastructure Design skipped (execution plan, confirmed by CMS & API). Awaiting plan approval." + +**Context**: Construction, U1 Code Generation Part 1. + +--- + +## Code Generation U1 - plan approved + +**Timestamp**: 2026-11-06T12:10:00Z + +**User Response**: "approve plan" + +**Status**: Approved. Starting Part 2 (generation). + +**Context**: Construction, U1 Code Generation. + +--- diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/code/code-summary.md b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/code/code-summary.md new file mode 100644 index 0000000..05ad5d5 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/code/code-summary.md @@ -0,0 +1,26 @@ +# Code Summary - core-site-hosting (U1) + +## Created (src/SlpModularCms.Core/Hosting/Website/) +- `WebsiteResolution.cs`, `WebsitePathResolver.cs` - pure resolver (R1-R14), max 2 file checks +- `WebsiteOptions.cs` - `Website:NoIndex` +- `WebsiteFileAccess.cs` - confined, fail-soft file provider, root looked up per call +- `PrerenderedSiteMiddleware.cs` - redirects, robots, files via static-file middleware (cache rules, charset) +- `WebsiteNotFoundHandler.cs` - final fallback: `404.html` with status 404, 405 for other methods +- `PrerenderedSiteExtensions.cs` - `AddCmsWebsite` (gzip only), `UseCmsPrerenderedSite`, `MapCmsWebsiteNotFound` +- `WebsiteHostingMarker.cs` - switches on the full header set + +## Modified +- `CmsHostOptions.cs` (+ `WebsiteMode`), `CmsHost.cs` (mode wiring, documented order), `StaticContentExtensions.cs` (mode parameter, defaults unchanged) +- `Security/CspPolicyCatalog.cs` (+ `StrictSite`), `SecurityHeadersOptions.cs` (+ `AllowedSite*Origins`), `SecurityHeadersExtensions.cs` (validation, log), `CspPolicyProvider.cs`, `SecurityHeaderWriter.cs` (`alwaysSendDocumentHeaders`), `SecurityHeadersMiddleware.cs` +- `WEBSITE_WORKSPACE.md`, `README.md` + +## Tests (src/SlpModularCms.Core.Tests/Hosting/) +- `Website/WebsitePathResolverTests.cs` (examples per rule), `WebsitePathResolverPropertyTests.cs` (FsCheck: PBT-03), `PrerenderedSiteIntegrationTests.cs` (in-memory server, 25 scenarios incl. full header set on page/asset/301/404/robots.txt, gzip-only, dotfiles, reserved prefixes, SpaFallback regression) +- `Security/StrictSitePolicyTests.cs` (byte-for-byte CSP, PBT-02), `SecurityHeaderWriterDocumentHeadersTests.cs` +- New test-only packages: `FsCheck.Xunit 3.4.0`, `Microsoft.AspNetCore.TestHost 10.0.9` + +## Deviations from the design +1. The resolver has no `IsNotFoundPage` flag on `ServeFile`; the 404 page is handled only by `WebsiteNotFoundHandler`. +2. Max 2 resolver file checks (plus 1 for `404.html` in the final stage) = 3 per request, as designed. +3. Routing selects the catch-all fallback endpoint before the website middleware; the middleware clears the endpoint before delegating to the static-file middleware (otherwise the framework skips serving). +4. The not-found fallback uses an explicit `{*path}` pattern (the default `nonfile` pattern would leave `/assets/missing.js` with a bare 404). diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/business-logic-model.md b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/business-logic-model.md new file mode 100644 index 0000000..b7f7686 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/business-logic-model.md @@ -0,0 +1,77 @@ +# Business Logic Model - core-site-hosting (U1) + +## Resolution flow (pure resolver) +```mermaid +flowchart TD + S["Raw path + query"] --> V{"R2 valid?"} + V -- no --> NF["NotFound"] + V -- yes --> RS{"R1 reserved?"} + RS -- yes --> PASS["Not handled (middleware passes on)"] + RS -- no --> DOT{"R3 dot segment, not .well-known?"} + DOT -- yes --> NF + DOT -- no --> ROOT{"path is /?"} + ROOT -- yes --> IDX["ServeFile index.html"] + ROOT -- no --> IX{"R6 index variant?"} + IX -- yes --> RD0["Redirect /"] + IX -- no --> F4{"R7 404 or 404.html?"} + F4 -- yes --> NF + F4 -- no --> KN{"Known page by lowercased name?"} + KN -- yes --> CAN{"Exactly canonical /name?"} + CAN -- yes --> SF["ServeFile name.html"] + CAN -- no --> RD1["Redirect /name + query"] + KN -- no --> EXT{"Has extension?"} + EXT -- yes --> FE{"File exists?"} + FE -- yes --> SF2["ServeFile asset"] + FE -- no --> NF + EXT -- no --> TS{"R11 ends in slash?"} + TS -- yes --> RD2["Redirect stripped path + query"] + TS -- no --> DIR{"name/index.html exists?"} + DIR -- yes --> SF3["ServeFile name/index.html"] + DIR -- no --> NF + + classDef ok fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; + classDef redir fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000; + classDef bad fill:#feb2b2,stroke:#c53030,stroke-width:1px,color:#000; + classDef pass fill:#d6bcfa,stroke:#553c9a,stroke-width:1px,color:#000; + class IDX,SF,SF2,SF3 ok; + class RD0,RD1,RD2 redir; + class NF bad; + class PASS pass; +``` + +Text alternative: invalid paths and dotfiles are NotFound; reserved prefixes pass on; known pages are served when canonical or redirected once; files with extensions are served or NotFound; other paths try the trailing-slash strip (R11), then a directory index (trailing slashes are always stripped by redirect, even for unknown targets), else NotFound. + +## Response flow (middleware) +```mermaid +flowchart TD + A["Request"] --> M{"GET or HEAD, not reserved?"} + M -- no --> N["next()"] + M -- yes --> RB{"NoIndex and /robots.txt?"} + RB -- yes --> RT["200 Disallow all"] + RB -- no --> R["Resolve"] + R --> X{"Result"} + X -- Redirect --> R301["301 Location"] + X -- ServeFile --> SV["200 file, Cache-Control rule"] + X -- NotFound --> N2["next() -> API routes"] + N2 --> L{"Endpoint matched?"} + L -- yes --> API["API response"] + L -- no --> E404["404.html with status 404 (or empty 404)"] + + classDef a fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; + classDef b fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; + class RT,R301,SV,E404 a; + class N,N2,API b; +``` + +Text alternative: the middleware answers robots, redirects and files itself; unresolved paths continue to the API routes, and only if nothing matches does the final stage serve the 404 page. + +## Header application (Q1 = A) +All website responses, whatever the branch (200 file, 301, robots, 404 page, empty 404), pass through the security-headers stage with the full set of the active policy. The headers stage detects website requests (non-reserved path in `PrerenderedPages` mode) and skips the HTML-only distinction for them. `X-Robots-Tag` is added by the website stage when `NoIndex` is set. + +## Dot-segment handling (Q2 = A) +Refusal happens inside the pure resolver (R3), so it is covered by property tests and cannot be bypassed by the middleware. `/.well-known/...` resolves like any file path. + +## Error handling +- Resolver never throws; invalid input is `NotFound`. +- File read errors in the middleware (race with a site delivery) -> 404 page; logged at warning level without the raw path. +- Missing `wwwroot/web` -> every website path 404 (plain); host still starts and serves API and admin. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/business-rules.md b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/business-rules.md new file mode 100644 index 0000000..859c064 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/business-rules.md @@ -0,0 +1,51 @@ +# Business Rules - core-site-hosting (U1) + +Applies only in `WebsiteMode.PrerenderedPages`. `SpaFallback` keeps today's behaviour. + +## Path resolution (pure `WebsitePathResolver`) +| # | Rule | +|---|---| +| R1 | Reserved: a path whose first segment is `admin`, `api` + `v1`, or `health` (whole segments, case-insensitive) is never resolved; the middleware passes it on. | +| R2 | Invalid input is `NotFound`: null/empty, not starting with `/`, containing backslash, NUL or other control characters, `%`-encoded traversal after one decode pass, `..` segments, or longer than 2048 chars. | +| R3 | **Dot segments (Q2 = A):** any segment starting with `.` is `NotFound`, except paths under `/.well-known/` (which are then served as ordinary files; `..` stays refused). | +| R4 | A result `ServeFile` never points outside the website root; the relative path is forward-slash, validated before the predicate is called. | +| R5 | `/` -> `ServeFile("index.html")`. | +| R6 | `/index`, `/index.html`, `/index/` and case variants -> `Redirect("/")` (query preserved). | +| R7 | `/404` and `/404.html` (any case) -> `NotFound` (no redirect, no serving of the page as 200). | +| R8 | Path with a file extension: served as a file when it exists, else `NotFound`. Never lower-cased, never redirected (hashed asset names), never falls back to a page. Exception: `.html` for a known page redirects (R10). | +| R9 | Extensionless `/x` where `x.html` exists (name lower-cased) and the request is exactly `/x` -> `ServeFile("x.html")`. `/x/index.html` is served if it exists and `x.html` does not. | +| R10 | Non-canonical request for a known page (case variant, `.html` suffix, trailing slash) -> one `Redirect("/")`, query string appended unchanged. Target comes from the known name, never from raw input. | +| R11 | Any path longer than one character ending in one or more slashes (and not a known page, which R10 handles) -> `Redirect` (301) to the path with all trailing slashes stripped, query preserved, whether or not the target exists (website rule BR-HST-03; an unknown target yields the 404 page on the follow-up request). If the stripped target would start with `//` or `/\` or contain control characters it is `NotFound` (R12). `/` is never redirected. A redirect target never ends in a slash except `/` (idempotent with R6, R10). | +| R12 | A redirect target starting with `//` or `/\` is never produced; such requests are `NotFound` (open-redirect guard). | +| R13 | A directory without a page file is `NotFound`; no directory listing. | +| R14 | Unknown path -> `NotFound`; the middleware turns it into the 404 page (R20). | + +## Response rules (middleware) +| # | Rule | +|---|---| +| R15 | `Redirect` -> status 301, relative `Location`, no body needed. | +| R16 | Cache-Control: `/assets/**` -> `public, max-age=31536000, immutable`; every other website file -> `no-cache`. | +| R17 | Compression only for non-reserved paths and these types: html, js, css, svg, json, xml, txt; `Vary: Accept-Encoding`. | +| R18 | `Website:NoIndex = true`: `X-Robots-Tag: noindex, nofollow` on every website response; `GET /robots.txt` -> 200 `text/plain` `User-agent: *` / `Disallow: /`. When false, `/robots.txt` is served from the file if it exists, else 404. | +| R19 | **Headers (Q1 = A):** every website response (page, asset, 301, 404, robots.txt) carries the full set of the active policy: CSP, HSTS, nosniff, `X-Frame-Options`, `Referrer-Policy`. The HTML-only distinction does not apply to website responses in this mode. API and admin responses keep today's rules. | +| R20 | Unknown non-reserved path, after API routes had no match: serve `404.html` with status 404; if `404.html` is missing, plain 404 with empty body. Never `index.html`. | +| R21 | An unknown `/api/v1` path stays an API 404 (not replaced by the website page). | +| R22 | Methods: only GET and HEAD are served; others on website paths get 405 (`Allow: GET, HEAD`) unless an API route claims them. | + +## StrictSite policy +| # | Rule | +|---|---| +| R23 | `StrictSite` is in `KnownPolicies`; unknown policy names still fail startup validation. `Strict` and `Relaxed` outputs unchanged. | +| R24 | CSP string, in this exact order: `default-src 'self'; script-src 'self' ; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self' ; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'`. With the site's configured origins it equals the nginx value byte for byte. | +| R25 | Site origin lists are used only by `StrictSite`; admin policies never gain them. Origins are validated like existing ones (https URL, no wildcard, no whitespace/semicolon). | +| R26 | HSTS `max-age=31536000; includeSubDomains`, `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin`. | + +## Security Baseline mapping (functional level) +- Input validation centralised in the resolver (R2-R4, R12): satisfies path-traversal and open-redirect prevention. +- Secure defaults: new settings default to today's behaviour (`SpaFallback`, empty lists, `NoIndex=false`). +- Dotfile refusal (R3) prevents accidental disclosure from a delivered site. + +## PBT properties (partial scope) +- PBT-02 round trip: building a policy then parsing its CSP directives yields the configured origins. +- PBT-03 invariants: for any input, `Resolve` never throws; `ServeFile` paths contain no `..`, backslash, leading `/` or dot segment (except `.well-known`); `Redirect` locations start with a single `/`, never `//` or `/\`. +- Idempotence: resolving a `Redirect` target (same predicate) never yields a second `Redirect`; a `Redirect` location never ends in `/` except `/` itself. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/domain-entities.md b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/domain-entities.md new file mode 100644 index 0000000..6cd287e --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/domain-entities.md @@ -0,0 +1,40 @@ +# Domain Entities - core-site-hosting (U1) + +No persistent data. All entities are in-memory values or configuration. + +## Entities +| Entity | Kind | Fields / values | Notes | +|---|---|---|---| +| `WebsiteMode` | enum | `SpaFallback` (0, default), `PrerenderedPages` (1) | On `CmsHostOptions.WebsiteMode` | +| `WebsiteResolution` | closed union | `ServeFile(RelativePath, IsNotFoundPage)`, `Redirect(Location)`, `NotFound` | `Redirect` is always 301 with a relative `Location` built only from known-page names | +| `WebsiteOptions` | options | `NoIndex: bool` (default false) | Section `Website`; validated at startup | +| `SecurityHeadersOptions` (extended) | options | + `AllowedSiteScriptOrigins`, `AllowedSiteConnectOrigins` | Used only by `StrictSite` | +| `StrictSite` policy | header set | CSP, HSTS, nosniff, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin` | CSP byte-identical to the site's current one | +| Known page | derived | file `.html` present in `wwwroot/web` | Never cached; decided per request via the file-exists predicate | + +## Configuration keys +| Key | Default | Effect | +|---|---|---| +| `Website:NoIndex` | `false` | `X-Robots-Tag: noindex, nofollow` on every website response; `/robots.txt` answers `Disallow: /` | +| `SecurityHeaders:DefaultPolicy` | `Strict` | Client sets `StrictSite` | +| `SecurityHeaders:AllowedSiteScriptOrigins` | `[]` | Script origins of `StrictSite` | +| `SecurityHeaders:AllowedSiteConnectOrigins` | `[]` | Connect origins of `StrictSite` | + +## Relationships +```mermaid +classDiagram + class CmsHostOptions { WebsiteMode } + class WebsiteResolution + class ServeFile { RelativePath, IsNotFoundPage } + class Redirect { Location } + class NotFound + class WebsiteOptions { NoIndex } + class SecurityHeadersOptions { AllowedSiteScriptOrigins, AllowedSiteConnectOrigins } + WebsiteResolution <|-- ServeFile + WebsiteResolution <|-- Redirect + WebsiteResolution <|-- NotFound + CmsHostOptions --> WebsiteOptions : enables when PrerenderedPages + SecurityHeadersOptions --> CmsHostOptions : StrictSite for site client +``` + +Text alternative: `WebsiteResolution` has three variants; the host option enables the website options and the client configures the StrictSite origin lists. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-design/logical-components.md b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-design/logical-components.md new file mode 100644 index 0000000..a039185 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-design/logical-components.md @@ -0,0 +1,37 @@ +# Logical Components - core-site-hosting (U1) + +No infrastructure components (no queue, cache, breaker, store). All in-process. + +| Component | Namespace / file (planned) | Role | +|---|---|---| +| `WebsitePathResolver`, `WebsiteResolution` | `Core.Hosting.Website` | Pure resolution (P1) | +| `WebsiteOptions` (+ validator) | `Core.Hosting.Website` | `Website:NoIndex` | +| `PrerenderedSiteMiddleware` | `Core.Hosting.Website` | HTTP adapter: redirects, files, robots, cache headers, logging | +| `WebsiteNotFoundMiddleware` (final stage) | `Core.Hosting.Website` | `404.html` with status 404 after API routes | +| `WebsiteFileAccess` | `Core.Hosting.Website` | Physical file provider rooted at `wwwroot/web`; exists/read with fail-soft (P2, P3) | +| `PrerenderedSiteExtensions` | `Core.Hosting.Website` | `AddCmsWebsite`, `UseCmsPrerenderedSite`, `UseCmsWebsiteNotFound` | +| `SecurityHeaderWriter` (extended), `SecurityHeadersMiddleware` (extended) | `Core.Hosting.Security` | P5 | +| `CspPolicyCatalog` (+ `StrictSite`), `SecurityHeadersOptions` (+ site origin lists) | `Core.Hosting.Security` | R23-R26 | +| `CmsHost`, `CmsHostOptions`, `StaticContentExtensions` | `Core.Hosting` | Mode wiring | + +```mermaid +flowchart LR + CH["CmsHost"] --> EXT["PrerenderedSiteExtensions"] + EXT --> MW["PrerenderedSiteMiddleware"] + EXT --> NF["WebsiteNotFoundMiddleware"] + MW --> RES["WebsitePathResolver (pure)"] + MW --> FA["WebsiteFileAccess"] + NF --> FA + CH --> SH["SecurityHeadersMiddleware"] + SH --> W["SecurityHeaderWriter (+ force flag)"] + SH --> CAT["CspPolicyCatalog (StrictSite)"] + + classDef pure fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; + classDef core fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; + classDef sec fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000; + class RES pure; + class CH,EXT,MW,NF,FA core; + class SH,W,CAT sec; +``` + +Text alternative: the host wires the website extensions and the security-header middleware; the site middleware uses the pure resolver and the confined file access; the header middleware uses the writer and the policy catalog. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-design/nfr-design-patterns.md b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-design/nfr-design-patterns.md new file mode 100644 index 0000000..1aaff7a --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-design/nfr-design-patterns.md @@ -0,0 +1,24 @@ +# NFR Design Patterns - core-site-hosting (U1) + +| # | Pattern | Realises | Design | +|---|---|---|---| +| P1 | Pure core, thin adapter | NFR-MT-01, NFR-AV-03, PBT-03 | `WebsitePathResolver.Resolve` is a static total function; the middleware only translates `WebsiteResolution` into HTTP. Every rule R1-R14 is testable without a server. | +| P2 | Defence in depth for path safety | Security Baseline | Layer 1: resolver validation (R2-R4, R12). Layer 2: file access only through a physical `IFileProvider` rooted at `wwwroot/web` (never `Path.Combine` with request data). A bug in one layer does not expose files outside the root. | +| P3 | Fail-soft file access | NFR-AV-01, NFR-AV-02 | Predicate and read wrap IO errors: a missing root, a vanished file or a permission error yields `false` / 404 page plus a warning on `SlpModularCms.Website`. No exception reaches the pipeline. | +| P4 | Bounded work per request | NFR-PF-01 | Resolution order is fixed so at most 3 predicate calls happen: (1) `.html`, (2) the literal file for extension paths or `/index.html`, (3) `404.html` for the final stage. Asserted with a counting predicate. | +| P5 | Website-scope header forcing | R19, Q1 = A | `SecurityHeaderWriter.Apply` gets an extra parameter `alwaysSendDocumentHeaders`. `SecurityHeadersMiddleware` sets it true when `WebsiteMode` is `PrerenderedPages` and `PathString` is not reserved (`WebsitePathResolver.IsReservedPath`). Then CSP, X-Frame-Options and Referrer-Policy go on every website response whatever its content type (asset, 301, 404, robots.txt). API and admin keep the content-type rule. Default of the new parameter is false, so existing callers and tests are unchanged. | +| P6 | Configuration-driven logging | NFR-OB-01..04 | A single `ILogger` with category `SlpModularCms.Website`; levels from `Logging:LogLevel` per environment. Path values are sanitised by a small helper before logging. | +| P7 | Secure defaults | Security Baseline | `WebsiteMode.SpaFallback`, empty site origin lists and `NoIndex = false` reproduce today's behaviour; startup validation rejects invalid origins and unknown policy names. | +| P8 | Single registration point | NFR-MT-01 | `AddCmsWebsite` / `UseCmsPrerenderedSite` own compression, noindex and the middleware; `CmsHost` only calls them when the mode asks for it, keeping `SpaFallback` untouched. | +| P9 | Compression scoping | NFR-CP-01..03 | `UseWhen(path is not reserved)` around `UseResponseCompression`; gzip provider only, MIME list from the requirements. | + +## Pipeline placement +Security headers stay first (inside the exception handler). The website stage sits where `UseCmsStaticContent` is today, the 404 stage after `MapSentryTunnel`, replacing the catch-all website fallback in this mode. + +## Behind the proxy Pi +The proxy forwards plain HTTP/1.0 to the app port. `UseHttpsRedirection` finds no HTTPS port and does nothing; website redirects are relative (`Location: /over-mij`), so no scheme or host is ever constructed. HSTS is still sent by the host (non-Development), as nginx does. + +## Open verification items (settled by tests in Code Generation) +1. No HTTPS-redirect loop or absolute `http://` redirect with a plain HTTP request. +2. Rate limiter default policy does not throttle website assets (check `AddCmsRateLimiting`). +3. `HEAD` requests behave like `GET` without body. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-requirements/nfr-requirements.md b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-requirements/nfr-requirements.md new file mode 100644 index 0000000..5ec265d --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-requirements/nfr-requirements.md @@ -0,0 +1,56 @@ +# NFR Requirements - core-site-hosting (U1) + +## Scalability +- NFR-SC-01: one small site on one Raspberry Pi behind the proxy Pi; tens of requests per second at most. No horizontal scaling, no shared state, no cache to invalidate. + +## Performance +- NFR-PF-01: a `Resolve` call performs at most **3** file-exists checks (Q3 = A). Asserted by a test with a counting predicate. +- NFR-PF-02: a simple local timing check (resolve + serve a page, many iterations) is run once and recorded in the hand-back note. No hard SLA; the goal is to show no per-request cost worth caching. +- NFR-PF-03: static files are streamed (no full buffering); response compression applies only to the listed text types. +- NFR-PF-04: no load test in U1. (A load test on the Pi was not chosen.) + +## Compression +- NFR-CP-01: **gzip only**, like nginx today (Q1 = A). No Brotli provider is registered. +- NFR-CP-02: types: html, js, css, svg, json, xml, txt; `Vary: Accept-Encoding`; non-reserved paths only. +- NFR-CP-03: compression stays at the ASP.NET default of "not over HTTPS"; the proxy Pi forwards plain HTTP so it applies in practice. + +## Availability and reliability +- NFR-AV-01: a missing or half-delivered `wwwroot/web` never stops the host: website paths answer 404, API and admin keep working. +- NFR-AV-02: no restart needed after a website delivery (per-request file checks, no cache). +- NFR-AV-03: the resolver is total (never throws); file read errors in the middleware become a 404 page plus a warning. +- NFR-AV-04: existing clients (`Api`, `Api.SlpSoftware`) behave exactly as today; their tests stay green. + +## Observability (Q2) +Bryan: "Alleen waarschuwingen en meer op de pi, op productie later bepalen". Implementation: +- NFR-OB-01: the website serving uses a dedicated logger category (`SlpModularCms.Website`). +- NFR-OB-02: 404s and 301s are logged at **Information** on that category; warnings for read errors and a missing `wwwroot/web`. +- NFR-OB-03: levels come from per-environment appsettings: test sets `Information` for that category; default and production stay `Warning`. Production is a later config change, no code change. +- NFR-OB-04: logs contain the sanitised path (control characters removed, length capped), never headers or cookies. + +## Security (Security Baseline, blocking) +| Item | Status | +|---|---| +| Input validation (path traversal, encoded/backslash/NUL, over-long, open redirect) | Compliant by design: single pure function, property-tested (R2-R4, R12) | +| Dotfile exposure | Compliant: R3 refuses dot segments except `.well-known` | +| Secure defaults | Compliant: new settings default to today's behaviour | +| Security headers on every website response | Compliant by R19, tested on page, asset, 301, 404, robots.txt | +| Log injection | Compliant: NFR-OB-04 | +| Secrets in code or config | N/A for U1 (no secrets); setup token is U2 | +| New dependencies | None in production code | +| Authn/authz | N/A for U1 (public static content); API and admin unchanged | +| Rate limiting | Unchanged; website static serving is not limited (same as nginx today) | + +## Maintainability and testing +- NFR-MT-01: all nginx-parity rules in one pure class; the middleware is a thin adapter. +- NFR-MT-02: tests: unit tests per rule R1-R26, integration tests (`WebApplicationFactory`-style) for headers on all response kinds, regression suites of `Api` and `Api.SlpSoftware`. +- NFR-MT-03: docs updated (`WEBSITE_WORKSPACE.md`, `README.md`). + +## Property-based testing (partial: PBT-02, 03, 07, 08, 09) +- PBT-02: policy round trip (configured origins appear in the built CSP and parse back). +- PBT-03: resolver invariants (never throws; `ServeFile` safe paths; `Redirect` targets safe, never end in `/` except `/`, resolving a target never redirects again). +- PBT-07: generators for paths (unicode, encoded, dots, slashes, case variants) kept in a shared test helper. +- PBT-08: failing seeds are printed and a shrunk counterexample is added as a regular unit test. +- PBT-09: a PBT framework is required; see tech-stack-decisions.md. + +## Usability +- N/A (no UI in U1). diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-requirements/tech-stack-decisions.md b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-requirements/tech-stack-decisions.md new file mode 100644 index 0000000..d0c3d9d --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-requirements/tech-stack-decisions.md @@ -0,0 +1,12 @@ +# Tech Stack Decisions - core-site-hosting (U1) + +| # | Decision | Rationale | +|---|---|---| +| T1 | ASP.NET Core built-in `UseResponseCompression` with gzip provider only | Matches nginx; no new package; Q1 = A | +| T2 | Built-in `IFileProvider` (physical, confined to `wwwroot/web`) for the file-exists predicate and streaming | No new package; traversal confinement is a second line of defence behind the resolver | +| T3 | `ILogger` with category `SlpModularCms.Website`, level via `Logging:LogLevel` in appsettings per environment | Q2; production later = config only | +| T4 | Test-only PBT framework **FsCheck.Xunit** (not currently in the repo) added to the Core test project | PBT-09 requires a framework; FsCheck is the standard for xUnit on .NET and is a test-only dependency (no production impact). Version pinned at code generation to a release older than two weeks | +| T5 | `WebApplicationFactory`-based integration tests (or the existing test host pattern used by `Api` tests) | Verify headers and pipeline order end to end | +| T6 | No new production NuGet packages | Smaller supply-chain surface (Security Baseline) | + +**Flag for approval**: T4 adds a new test dependency; if you prefer a different PBT library, say so now. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-code-generation-plan.md b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-code-generation-plan.md new file mode 100644 index 0000000..a2da5e5 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-code-generation-plan.md @@ -0,0 +1,31 @@ +# Code Generation Plan - core-site-hosting (U1) + +Single source of truth for U1 code generation. Brownfield: modify in place. Application code under `src/`; docs summary under `construction/core-site-hosting/code/`. + +## Unit context +- Implements FR-U1-01..11 (requirements.md); rules R1-R26 (functional design); NFR-* and patterns P1-P9 (NFR design). +- No user stories (skipped). No database, no frontend, no deployment change (U1 Infrastructure Design skipped, confirmed by CMS & API). +- Depends on: existing `Core` hosting (`CmsHost`, `StaticContentExtensions`, security headers). Consumed later by U2 (`Api.AndreaSlopFotografie`). +- Test project: `src/SlpModularCms.Core.Tests` (xunit, FluentAssertions, NSubstitute). New test-only packages: `Microsoft.AspNetCore.TestHost` (in-memory server, no MariaDB needed) and `FsCheck.Xunit` (PBT-09); versions pinned to releases older than two weeks. +- Verified while planning: the rate limiter is endpoint-policy based (`login` etc.), so website files are not throttled (NFR design verification item 2). + +## Steps +- [x] **Step 1 - Options and mode.** `src/SlpModularCms.Core/Hosting/CmsHostOptions.cs`: add `WebsiteMode` enum and `WebsiteMode` property (default `SpaFallback`). Add `Website/WebsiteOptions.cs` (`NoIndex`). +- [x] **Step 2 - Pure resolver.** `Website/WebsiteResolution.cs`, `Website/WebsitePathResolver.cs` implementing R1-R14 (incl. R3 dot segments, R11 trailing-slash redirect, `IsReservedPath`), max 3 predicate calls (P4). +- [x] **Step 3 - Resolver tests.** `Website/WebsitePathResolverTests.cs` (example tests per rule, call-count test) and `Website/WebsitePathResolverPropertyTests.cs` (FsCheck: PBT-03 invariants, idempotence; shared generators, PBT-07; seed logging, PBT-08). Add package references. +- [x] **Step 4 - StrictSite policy.** `CspPolicyCatalog`: `StrictSite` constant, `KnownPolicies`, `Build` overload with site origin lists, exact directive order (R24-R26). `SecurityHeadersOptions`: `AllowedSiteScriptOrigins`, `AllowedSiteConnectOrigins`; `SecurityHeadersExtensions`: origin validation including the new lists; `CspPolicyProvider` passes the lists. Existing call sites compile unchanged. +- [x] **Step 5 - Policy tests.** Extend `CspPolicyCatalogTests` and `SecurityHeadersOptionsValidationTests`: byte-for-byte site CSP with the real origins, `Strict`/`Relaxed` unchanged, unknown names still fail, invalid site origins fail; PBT-02 round trip. +- [x] **Step 6 - Header forcing (P5).** `SecurityHeaderWriter.Apply(..., alwaysSendDocumentHeaders = false)`; `SecurityHeadersMiddleware` sets it for non-reserved paths when `WebsiteMode.PrerenderedPages`. Needs the mode in the middleware: register a small `WebsiteHostingMarker` (singleton) from `AddCmsWebsite`. Writer tests for the flag. +- [x] **Step 7 - File access.** `Website/WebsiteFileAccess.cs`: physical provider rooted at `wwwroot/web`, `Exists`, `Open`, fail-soft with logging (P2, P3), log path sanitiser (NFR-OB-04). +- [x] **Step 8 - Middleware and wiring.** `Website/PrerenderedSiteMiddleware.cs` (R15-R18, R22, caching, robots, noindex, logging), `Website/WebsiteNotFoundMiddleware.cs` (R20-R21), `Website/PrerenderedSiteExtensions.cs` (`AddCmsWebsite` with gzip-only compression and options validation; `UseCmsPrerenderedSite`; `UseCmsWebsiteNotFound`). `CmsHost` and `StaticContentExtensions`: branch on `WebsiteMode`; `SpaFallback` path untouched; pipeline order documented in `CmsHost`. +- [x] **Step 9 - Integration tests.** `Website/PrerenderedSiteIntegrationTests.cs` with an in-memory `TestServer` host composing the real security-header and website extensions over a temp `wwwroot/web`: pages, canonical 301s, trailing slash, assets (immutable), `no-cache`, 404 page with status 404, missing `404.html`, dotfiles and `.well-known`, reserved prefixes untouched (an unknown `/api/v1/x` stays a non-website 404), robots/noindex, full header set on page, asset, 301, 404, robots.txt (Q1 = A), gzip only, HEAD, no HTTPS-redirect loop on plain HTTP, missing `wwwroot/web` keeps host alive. Includes a local timing check (NFR-PF-02) printed to the test output. +- [x] **Step 10 - Regression.** Run the full `Core.Tests`, `Modules.*.Tests` and `Api.Tests`/`Api.SlpSoftware` suites (the ones needing MariaDB are run if a local DB is reachable, otherwise reported as not runnable with the reason). +- [x] **Step 11 - Documentation.** Update `WEBSITE_WORKSPACE.md` and `README.md` (mode, settings `Website:NoIndex`, `SecurityHeaders:AllowedSite*Origins`, `StrictSite`, logging category, behaviour table); mirror nothing in `AGENTS.md` (structure unchanged). Write `construction/core-site-hosting/code/code-summary.md`. +- [x] **Step 12 - Build and test (Step 13.5).** `dotnet build SlpModularCms.sln`, run all U1 tests, fix until green. +- [x] **Step 13 - Commit.** One commit on `feature/andreaslop-site-hosting` for U1 code (aidlc-docs committed separately or with it per repo habit); no push. + +## Deployment artifacts +None in U1 (config samples for the Andrea client belong to U2). + +## Story traceability +No stories (skipped by decision Q6). Traceability to requirements: Step 1 FR-U1-01; Step 2-3 FR-U1-02..04; Step 4-6 FR-U1-08..09; Step 7-8 FR-U1-03..07, 10; Step 11 FR-U1-11. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-fd-questions.md b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-fd-questions.md new file mode 100644 index 0000000..c5ef4c5 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-fd-questions.md @@ -0,0 +1,20 @@ +# Functional Design Questions - core-site-hosting (U1) + +## Question 1: Security headers on non-HTML website responses +nginx sends the full header set (CSP, HSTS, nosniff, X-Frame-Options, Referrer-Policy and, on test, X-Robots-Tag) on every response, including assets, 301 redirects, robots.txt and the 404 page. The current host writer treats CSP, X-Frame-Options and Referrer-Policy as "HTML-only" headers. For website responses in `PrerenderedPages` mode: + +- A) Send the full set on every website response, like nginx (assets, redirects, robots.txt, 404); the site's verify script can then assert identical headers everywhere (recommended) +- B) Keep the current rule: CSP, X-Frame-Options and Referrer-Policy only on HTML responses; HSTS and nosniff on all +- X) Other (please describe after [Answer]: tag below) + +[Answer]: A (relayed via CMS & API: "Volledige set overal") + +## Question 2: Hidden paths (dot segments) +nginx test conf serves any file under the root. Should the host refuse paths with a segment starting with a dot (for example `/.git/config`, `/.env`)? + +- A) Refuse (404) every dot-segment path except `/.well-known/...` (recommended: protects accidental dotfiles in a delivered site, keeps ACME/security.txt possible) +- B) Refuse every dot-segment path without exception +- C) No special rule, same as nginx +- X) Other (please describe after [Answer]: tag below) + +[Answer]: A (relayed via CMS & API: "Weigeren, behalve .well-known") diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-functional-design-plan.md b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-functional-design-plan.md new file mode 100644 index 0000000..6b4d06b --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-functional-design-plan.md @@ -0,0 +1,8 @@ +# Functional Design Plan - core-site-hosting (U1) + +- [x] Analyse unit context (unit-of-work.md, requirements FR-U1-01..11, website repo rules BR-HST, nginx test conf) +- [x] Collect answers to `core-site-hosting-fd-questions.md` +- [x] Generate `business-logic-model.md` (resolution flow, request flow, header rules) +- [x] Generate `business-rules.md` (rule table R1.., decision flow) +- [x] Generate `domain-entities.md` (WebsiteResolution, options, policy header set, config keys) +- [x] No frontend artifacts (U1 has no UI) diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-nfr-design-plan.md b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-nfr-design-plan.md new file mode 100644 index 0000000..0e2034d --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-nfr-design-plan.md @@ -0,0 +1,15 @@ +# NFR Design Plan - core-site-hosting (U1) + +## Steps +- [x] Analyse NFR requirements (nfr-requirements.md, tech-stack-decisions.md) +- [x] Evaluate question categories; no open questions (justification below) +- [x] Generate `nfr-design/nfr-design-patterns.md` +- [x] Generate `nfr-design/logical-components.md` + +## Category evaluation (why no questions) +- Resilience: decided by NFR-AV-01..04 (host never stops, resolver total, read errors become 404 plus warning). No retries or circuit breakers apply to local file access. +- Scalability: NFR-SC-01 (one small site); no scaling mechanism needed. +- Performance: decided by Q3 (call-count test, timing check) and the no-cache decision D3. +- Security: Security Baseline table in nfr-requirements.md; implementation choices follow existing code (`SecurityHeaderWriter`, `PathPolicyResolver`) and have one obvious solution. +- Logical components: no queue, cache or breaker; only in-process classes. The one real design choice (how to force the full header set on website responses) follows from the existing writer and Q1 = A; it is documented and can be changed at the approval step. +- Risk 2 from application design (HTTPS redirection behind the proxy Pi): inspected; the existing `UseHttpsRedirection` is a no-op without an HTTPS port, same as `Api.SlpSoftware` today; verified by an integration test in code generation. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-nfr-requirements-plan.md b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-nfr-requirements-plan.md new file mode 100644 index 0000000..27c961c --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-nfr-requirements-plan.md @@ -0,0 +1,40 @@ +# NFR Requirements Plan - core-site-hosting (U1) + +## Steps +- [x] Analyse functional design (business-rules R1-R26, flows, entities) +- [x] Collect answers to the questions below +- [x] Generate `nfr-requirements/nfr-requirements.md` +- [x] Generate `nfr-requirements/tech-stack-decisions.md` +- [x] Security Baseline and PBT applicability check (tabulated in the artifacts) + +## Pre-filled assumptions (tell me if wrong, via Other on the last question) +- Scale: one small site on one Raspberry Pi behind the proxy Pi; tens of requests per second at most. +- Availability: same as the host today; a missing or half-delivered `wwwroot/web` must never stop the host (website paths 404, API and admin keep working). +- Security: Security Baseline applies (path validation in the resolver, secure defaults, no new dependencies); compression stays off for TLS-terminated traffic by default is irrelevant because the proxy Pi forwards plain HTTP. +- Tech stack: built-in ASP.NET Core only (no new NuGet packages), xUnit and FsCheck if already used in the repo for PBT. + +## Question 1: Compression algorithms +nginx today uses gzip only. ASP.NET Core can also do Brotli. + +- A) gzip only, same as nginx today (simplest, identical behaviour for the verify script) (recommended) +- B) Brotli and gzip (smaller responses; the site's verify script must then accept `br`) +- X) Other (please describe after [Answer]: tag below) + +[Answer]: A (relayed via CMS & API: "Alleen gzip") + +## Question 2: Observability of website traffic +- A) Log nothing extra per request; log only warnings (file read errors, missing `wwwroot/web` at startup once) (recommended, no log noise on a small Pi) +- B) Also log each 404 and each 301 at Information level (useful to spot broken links, noisy with crawlers) +- X) Other (please describe after [Answer]: tag below) + +[Answer]: Relayed via CMS & API, Bryan verbatim: "Alleen waarschuwingen en meer op de pi, op productie later bepalen". Interpretation (to be confirmed by approval): dedicated logger category, 404/301 at Information, level per environment (test = Information, default/production = Warning). + +## Question 3: Performance verification +Per-request `File.Exists` has no cache (design decision). How much proof do you want that this is fast enough? + +- A) A unit/integration test asserting no unbounded work (a resolve does at most 3 file-exists calls) plus a simple local timing check recorded in the hand-back (recommended) +- B) Only the file-exists-call-count test, no timing check +- C) A load test against the test Pi after deploy (extra work in U2) +- X) Other (please describe after [Answer]: tag below) + +[Answer]: A (relayed via CMS & API: "Aantaltest plus lokale tijdmeting") diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/application-design.md b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/application-design.md new file mode 100644 index 0000000..f138a97 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/application-design.md @@ -0,0 +1,28 @@ +# Application Design (consolidated) - andreaslop-site-hosting + +Details: `components.md`, `component-methods.md`, `services.md`, `component-dependency.md`. + +## Decisions +| # | Decision | Source | +|---|---|---| +| D1 | `CmsHostOptions.WebsiteMode` (`SpaFallback` default, `PrerenderedPages`); existing clients unchanged | Brief, FR-U1-01 | +| D2 | All nginx-parity rules live in one pure `WebsitePathResolver` taking a file-exists predicate; the middleware is a thin adapter | Requirements FR-U1-02 | +| D3 | A page is "known" by a per-request file-exists check on the lowercased name; no cache, no restart needed after a site delivery | Q2 = A | +| D4 | `StrictSite` policy in `CspPolicyCatalog`, byte-identical to the site's current CSP; origins from new `AllowedSiteScriptOrigins` / `AllowedSiteConnectOrigins`, so admin policies stay as strict as today | Q1 = A | +| D5 | Compression only for non-reserved paths; `/api/v1` and `/admin` not compressed by this feature | Requirements open point 5 | +| D6 | Unknown website paths get `404.html` with status 404 in a final pipeline stage after API routes; an unknown `/api/v1` path stays an API 404 | FR-U1-03/04/10 | +| D7 | Setup token: `Identity:Setup:Token` optional, header `X-Setup-Token`, constant-time compare, `GET /Setup/status` returns `tokenRequired`, setup page shows the field only when required | Q3 = A, FR-U2-07 | +| D8 | Theme is a build-time CSS override of existing tokens (`VITE_THEME`), language default via `VITE_DEFAULT_LANGUAGE`; no runtime theme API | Brief D2, Q5 | +| D9 | Module set of the Andrea client = its project references; `Availability` included only if the admin needs it (decided in U2 NFR/Code Generation, reported to the requester) | Brief D1 | +| D10 | Unit order: U1 Core (with regression run), hand-back and wait for the requester's "go", then U2 | Brief, execution plan | + +## Risks carried into Construction +1. The existing security-header writer treats CSP/frame/referrer as HTML-only; website 301/asset/robots responses may need the full set (FR-U1-09). Settled in U1 Functional Design with tests. +2. `UseHttpsRedirection` on plain HTTP behind the proxy Pi, and absent forwarded-headers handling: verify no loop or absolute `http://` redirect (website redirects are relative). +3. Per-request `File.Exists` on a Pi SD card or `/mnt/storage1`: low cost expected; measured in U1 NFR Design. +4. Setup endpoints and rate limiting: confirm the login limiter covers `/Setup/owner` (NFR Design U2). +5. Frontend setup page change touches an existing screen (small, covered by tests). + +## Security Baseline / PBT applicability (design stage) +- Security: path input validation centralised in one pure function; secure-by-default configuration (new settings default to today's behaviour); no secrets in repo (token and DB password come from the environment); constant-time token compare; no new dependencies. Compliant / N/A items are tabulated in the NFR stages. +- PBT (partial): the resolver (PBT-02/03 invariants), canonical idempotence, policy round trip are pure and directly testable. diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/component-dependency.md b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/component-dependency.md new file mode 100644 index 0000000..28ce2a3 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/component-dependency.md @@ -0,0 +1,63 @@ +# Component Dependencies - andreaslop-site-hosting + +## Dependency matrix (row depends on column) + +| | Core hosting | Security (CSP) | Identity | Frontend | CI/CD | +|---|---|---|---|---|---| +| C2 WebsiteMode | - | | | | | +| C3 Site serving | uses | uses (headers precede it) | | | | +| C4 StrictSite | | - | | | | +| C1 Andrea client | references | configures | references | consumes built admin | built by | +| C5 Theme | | | | - | selected by | +| C7 Setup token | | | - (in module) | setup page | | +| C6 CI/CD | | | | builds | - | + +- C3a (pure resolver) depends on nothing but `System`; the predicate is injected. This keeps property-based testing trivial and keeps traversal safety in one testable place. +- `Api` and `Api.SlpSoftware` depend on Core only through unchanged defaults (`WebsiteMode.SpaFallback`, empty site origin lists, no setup token configured). + +```mermaid +graph TD + opts["CmsHostOptions.WebsiteMode (C2)"] + host["CmsHost / StaticContentExtensions"] + mw["PrerenderedSiteMiddleware (C3c)"] + res["WebsitePathResolver (C3a, pure)"] + wopt["WebsiteOptions (C3b)"] + csp["CspPolicyCatalog + SecurityHeadersOptions (C4)"] + sethdr["SecurityHeadersMiddleware"] + ident["Identity: SetupController + ISetupTokenValidator (C7)"] + client["Api.AndreaSlopFotografie (C1)"] + fe["frontend theme + setup page (C5, C7)"] + ci["Gitea workflows (C6)"] + + host --> opts + host --> mw + mw --> res + mw --> wopt + host --> sethdr + sethdr --> csp + client --> host + client --> ident + client --> csp + fe --> ident + ci --> client + ci --> fe + + classDef core fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; + classDef pure fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; + classDef newc fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000; + classDef ext fill:#d6bcfa,stroke:#553c9a,stroke-width:1px,color:#000; + class opts,host,mw,wopt,sethdr,csp core; + class res pure; + class client,ident,fe newc; + class ci ext; +``` + +Text alternative: the host wires the options, the site middleware and the security-header middleware; the middleware depends on the pure resolver; the Andrea client references host and Identity and configures the policy; the frontend and CI build the client. + +## Communication patterns +- In-process only; no new network calls from the host. +- Website to API: browser calls same-origin `/api/v1` where needed; Sentry and Umami origins are called directly by the site (listed in `StrictSite`). +- Configuration is the only coupling between a client and a policy: `DefaultPolicy`, `PathPolicies`, `AllowedSite*Origins`, `Website:NoIndex`, `Identity:Setup:Token`. + +## Delivery coupling (website files) +`wwwroot/web` is owned by the website delivery (web CI or a symlink to `/mnt/storage1/www/html/andreaslop-test`); the host only reads it. Because pages are resolved per request without cache (Q2=A), both delivery variants work without restart. diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/component-methods.md b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/component-methods.md new file mode 100644 index 0000000..4254026 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/component-methods.md @@ -0,0 +1,72 @@ +# Component Methods - andreaslop-site-hosting + +Signatures are indicative; business rules are detailed in U1 Functional Design. + +## Core - hosting +```csharp +public enum WebsiteMode { SpaFallback = 0, PrerenderedPages = 1 } + +public sealed class CmsHostOptions { public WebsiteMode WebsiteMode { get; init; } = WebsiteMode.SpaFallback; } +``` + +## C3a WebsitePathResolver +```csharp +public abstract record WebsiteResolution +{ + public sealed record ServeFile(string RelativePath, bool IsNotFoundPage = false) : WebsiteResolution; + public sealed record Redirect(string Location) : WebsiteResolution; // always 301, relative Location + public sealed record NotFound : WebsiteResolution; +} + +public static class WebsitePathResolver +{ + // Total: never throws, never returns a path outside the website root. + // fileExists receives a relative, forward-slash, already-validated candidate ("over-mij.html"). + public static WebsiteResolution Resolve(string? rawPath, string? queryString, Func fileExists); + public static bool IsReservedPath(string? rawPath); // /admin, /api/v1, /health (whole segments, case-insensitive) +} +``` + +## C3b/C3c Website serving +```csharp +public sealed class WebsiteOptions { public const string SectionName = "Website"; public bool NoIndex { get; set; } } + +public static class PrerenderedSiteExtensions +{ + public static IServiceCollection AddCmsWebsite(this IServiceCollection s, IConfiguration c); // options + validation + compression + public static WebApplication UseCmsPrerenderedSite(this WebApplication app); // compression (UseWhen), noindex, resolver middleware +} + +public sealed class PrerenderedSiteMiddleware(RequestDelegate next, IWebHostEnvironment env, IOptions options) +{ + public Task InvokeAsync(HttpContext context); +} +``` +`StaticContentExtensions.UseCmsStaticContent` / `MapCmsSpaFallbacks` branch on `WebsiteMode`: in `PrerenderedPages` they register the admin mount and the `/admin` fallback only, the website mount is `UseCmsPrerenderedSite`, and the catch-all website fallback is replaced by the middleware's 404 handling placed after API routes. + +## C4 Security +```csharp +public static class CspPolicyCatalog +{ + public const string StrictSite = "StrictSite"; + public static SecurityHeaderSet Build(string policy, + IEnumerable allowedScriptOrigins, IEnumerable allowedConnectOrigins, + IEnumerable? siteScriptOrigins = null, IEnumerable? siteConnectOrigins = null); +} +public sealed class SecurityHeadersOptions { /* + */ public IList AllowedSiteScriptOrigins { get; set; } = []; public IList AllowedSiteConnectOrigins { get; set; } = []; } +``` +Existing call sites keep compiling (new parameters optional). + +## C7 Setup token +```csharp +public sealed class SetupOptions { public const string SectionName = "Identity:Setup"; public string? Token { get; set; } } +public interface ISetupTokenValidator { bool IsRequired { get; } bool IsValid(string? presentedToken); } // fixed-time comparison +// SetupController +// GET /Setup/status -> { initialized, tokenRequired } +// POST /Setup/owner -> 401/403 problem details when token required and missing/wrong; header X-Setup-Token +``` + +## Frontend +- `theme.ts`/Vite plugin: resolves `VITE_THEME` to `themes//theme.css` import (no-op when unset). +- `i18n init`: `lng = stored ?? import.meta.env.VITE_DEFAULT_LANGUAGE ?? browser default`. +- Setup page: optional `setupToken` field; API client adds `X-Setup-Token` header. diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/components.md b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/components.md new file mode 100644 index 0000000..b3fb26e --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/components.md @@ -0,0 +1,39 @@ +# Components - andreaslop-site-hosting + +Numbering follows the brief (C1-C6); C7 is added by this design (setup token, requirements FR-U2-07). + +## C2 WebsiteMode option (Core, `SlpModularCms.Core.Hosting`) +- **Purpose**: Per-client choice of how the public website is served. +- **Responsibilities**: `enum WebsiteMode { SpaFallback, PrerenderedPages }`; property `CmsHostOptions.WebsiteMode` (default `SpaFallback`). +- **Interface**: read by `CmsHost.ConfigureServices/ConfigurePipeline` and `StaticContentExtensions`. + +## C3 Prerendered site serving (Core, `SlpModularCms.Core.Hosting.Website`, new folder) +Active only when `WebsiteMode = PrerenderedPages`. + +| Part | Kind | Responsibility | +|---|---|---| +| C3a `WebsitePathResolver` | static, pure | Total function: (raw path, query string, `Func fileExists`) -> `WebsiteResolution` (`ServeFile(relativePath)`, `Redirect(location)`, `NotFound`). Contains every nginx-parity rule (canonical form, trailing slash, `/index`, traversal and backslash rejection, file-looking paths, reserved prefixes). No I/O, no clock, no logging. | +| C3b `WebsiteOptions` | options | `Website:NoIndex` (default false), validated at startup. | +| C3c `PrerenderedSiteMiddleware` | middleware | Adapter between HTTP and the resolver: supplies the file-exists predicate (confined to `wwwroot/web`), writes status, `Location`, `Cache-Control`, `X-Robots-Tag`, streams the file, serves `404.html` with status 404, answers `/robots.txt` when `NoIndex`. Never handles reserved prefixes. | +| C3d Website compression | registration | Built-in response compression for the text MIME types, applied only to non-reserved paths (`UseWhen`), so `/api/v1` and `/admin` responses are never compressed by this feature. | + +## C4 StrictSite policy (Core, `SlpModularCms.Core.Hosting.Security`) +- **Purpose**: A third CSP policy for a prerendered public site, reproducing the site's current header byte for byte. +- **Responsibilities**: `CspPolicyCatalog.StrictSite` constant, added to `KnownPolicies`; `Build` produces the site CSP with `X-Frame-Options: DENY` and `Referrer-Policy: strict-origin-when-cross-origin`; `SecurityHeadersOptions` gains `AllowedSiteScriptOrigins` and `AllowedSiteConnectOrigins`, used **only** by `StrictSite` (decision Q1=A). `Strict` and `Relaxed` outputs are unchanged. +- **Check**: HSTS, `X-Content-Type-Options`, `Referrer-Policy` and the CSP appear on website pages, assets, 301s, 404 and robots.txt (FR-U1-09). The existing writer emits CSP/frame/referrer as "HTML-only" headers; whether non-HTML website responses also need them is settled in U1 Functional Design. + +## C1 Client `SlpModularCms.Api.AndreaSlopFotografie` (Clients) +- **Purpose**: Deployable host for Andrea's instance. +- **Responsibilities**: thin `Program.cs` on `CmsHost` with `WebsiteMode.PrerenderedPages`; `.csproj` references the modules (Core, Identity, and Availability only if the admin needs it); three-file appsettings; own database connection string template (no password in repo); own dev port; `SecurityHeaders:DefaultPolicy = StrictSite` plus the site origin lists; `Website:NoIndex = true` for test. + +## C5 Admin theme (frontend) +- **Purpose**: Per-site look of the admin, fixed at build time. +- **Responsibilities**: `frontend/themes//theme.css` overriding existing design tokens; theme assets (logo, favicon, self-hosted Marcellus and Jost); build-time selection by `VITE_THEME`; `VITE_DEFAULT_LANGUAGE` initial language (user choice still wins); unset variables reproduce today's admin. + +## C6 CI/CD (Gitea workflows) +- **Purpose**: Build and deploy each client with its own admin build. +- **Responsibilities**: per-client admin build (`VITE_THEME`, `VITE_DEFAULT_LANGUAGE`, `VITE_APP_TITLE`), ARM64 publish of the new host, deploy to the test Pi using the existing atomic release switch, `wwwroot/web` outside the release directory; production path of `Api.SlpSoftware` untouched. + +## C7 First-admin setup token (Identity module + frontend) +- **Purpose**: Stop a stranger from claiming the first administrator on a freshly deployed, publicly reachable instance. +- **Responsibilities**: `SetupOptions` (`Identity:Setup:Token`, optional); `ISetupTokenValidator` (constant-time compare, true when no token is configured); `SetupController.GetStatus` returns `tokenRequired`; `CreateOwner` requires header `X-Setup-Token` when configured; setup page in the frontend shows a token field only when `tokenRequired` is true (decision Q3=A). Existing hosts without the setting behave exactly as before. diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/services.md b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/services.md new file mode 100644 index 0000000..fba4b45 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/services.md @@ -0,0 +1,66 @@ +# Services and Orchestration - andreaslop-site-hosting + +No new domain services or database tables. Orchestration is host composition and one request pipeline. + +## Host composition (`CmsHost`) +- `ConfigureServices`: `AddCmsSecurityHeaders` (now with site origin lists), `AddCmsWebsite` (only when `WebsiteMode = PrerenderedPages`). Identity registers `SetupOptions` and `ISetupTokenValidator` in its own module registration. +- `ConfigurePipeline` order (documented in `CmsHost`): + +```mermaid +flowchart TD + A["Exception handler"] --> B["Security headers"] + B --> C["Rate limiter"] + C --> D["HTTPS redirection (no-op on plain HTTP)"] + D --> E["Admin static mount + /admin redirect"] + E --> F["Website: compression (non-reserved paths) + noindex"] + F --> G["Website resolver middleware (pages, assets, redirects, robots)"] + G --> H["CORS, module middleware, auth"] + H --> I["MapControllers (/api/v1)"] + I --> J["Health checks, Sentry tunnel"] + J --> K["Admin SPA fallback"] + K --> L["Website 404 (404.html, status 404)"] + + classDef sec fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000; + classDef site fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; + classDef api fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; + class A,B,C,D sec; + class E,F,G,K,L site; + class H,I,J api; +``` + +Text alternative: security stages first (yellow), then the admin and website mounts (blue), then API routes (green); unknown website paths fall to 404 last, so API 404s are never replaced by the website page. + +Notes: +- The resolver middleware passes reserved prefixes (`/admin`, `/api/v1`, `/health`) straight on, and passes on unknown paths **only** after API routes had a chance; the final 404 stage serves `404.html` with status 404 for non-reserved paths. Pages that resolve (`ServeFile`, `Redirect`) are answered in step G, before the API; this is safe because the pure resolver never resolves reserved prefixes. +- `SpaFallback` mode keeps today's pipeline untouched. + +## Request flow (website page) +```mermaid +sequenceDiagram + box rgba(246,224,94,0.4) Client + participant B as Browser or proxy Pi + end + box rgba(99,179,237,0.4) Host + participant M as SiteMiddleware + participant R as PathResolver + participant F as wwwroot web + end + B->>M: GET /Over-Mij?x=1 + M->>R: Resolve path, query, fileExists + R->>F: fileExists over-mij.html + F-->>R: true + R-->>M: Redirect /over-mij?x=1 + M-->>B: 301 Location /over-mij?x=1 plus security headers + B->>M: GET /over-mij + M->>R: Resolve + R-->>M: ServeFile over-mij.html + M-->>B: 200 html, no-cache, compressed +``` + +Text alternative: the middleware asks the pure resolver, which uses a file-exists check; a non-canonical request gets one 301, then the canonical request is served as a file. + +## Setup flow +Browser loads setup page -> `GET /Setup/status` -> `tokenRequired` decides whether the token field is shown -> `POST /Setup/owner` with `X-Setup-Token` -> `ISetupTokenValidator` -> existing `ISetupService.CreateInitialOwnerAsync`. Login rate limiting policy also covers the setup endpoints (verified in NFR Design). + +## Build and deploy flow (C6) +CI: admin build per client (env: theme, language, title) -> copy into client `wwwroot/admin` -> `dotnet publish` (linux-arm64) -> scp to `releases/` -> atomic switch of `current` -> restart user unit -> smoke checks (`/health`, `/api/v1/System/capabilities`, a website page). `wwwroot/web` is a symlink in `shared/`, so it survives every release. diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work-dependency.md b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work-dependency.md new file mode 100644 index 0000000..a4e696a --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work-dependency.md @@ -0,0 +1,22 @@ +# Unit Dependencies - andreaslop-site-hosting + +| Unit | Depends on | Reason | +|---|---|---| +| U1 | existing Core | extends it additively | +| U2 | U1 | client uses `WebsiteMode.PrerenderedPages`, `StrictSite`, `Website:NoIndex` | +| U2 | requester "go" | hand-back gate | + +```mermaid +flowchart LR + U1["U1 core-site-hosting"] --> H1["Hand-back + go from CMS & API"] --> U2["U2 andreaslop-client"] --> BT["Build and Test"] --> OP["Operations"] + classDef u fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000; + classDef g fill:#d6bcfa,stroke:#553c9a,stroke-width:1px,color:#000; + classDef n fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; + class U1,U2 u; + class H1 g; + class BT,OP n; +``` + +Text alternative: U1, then the hand-back gate, then U2, then Build and Test and Operations. + +Shared contract between units: configuration names (`WebsiteMode` in code, `Website:NoIndex`, `SecurityHeaders:DefaultPolicy=StrictSite`, `SecurityHeaders:AllowedSiteScriptOrigins`, `SecurityHeaders:AllowedSiteConnectOrigins`). U1 fixes these names; U2 only uses them. diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work-story-map.md b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work-story-map.md new file mode 100644 index 0000000..0a328bf --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work-story-map.md @@ -0,0 +1,13 @@ +# Requirement-to-Unit Map (User Stories skipped) + +| Requirement | Unit | +|---|---| +| FR-U1-01 .. FR-U1-11 | U1 | +| FR-U2-01 client project, FR-U2-02 module set | U2 | +| FR-U2-03 theme | U2 | +| FR-U2-04 CI/CD, FR-U2-05 test deploy, FR-U2-06 Pi provisioning | U2 | +| FR-U2-07 setup token, FR-U2-08 auth unchanged | U2 | +| Security Baseline, PBT partial, per-unit build/test | both | +| Git rules (one branch, no push, PR after U2) | both | + +All requirements are assigned to a unit. diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work.md b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work.md new file mode 100644 index 0000000..0a384bf --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work.md @@ -0,0 +1,22 @@ +# Units of Work - andreaslop-site-hosting + +Terminology: both units are changes to the same deployable codebase ("Unit of Work" = planning/delivery slice), delivered on one branch, commits per unit. + +## U1 core-site-hosting +- **Scope**: C2 WebsiteMode, C3 prerendered site serving (resolver, middleware, options, compression), C4 StrictSite policy and site origin lists, pipeline order, docs (`README.md`, `WEBSITE_WORKSPACE.md`). +- **Code locations**: `src/SlpModularCms.Core/Hosting/**` (+ `src/SlpModularCms.Core.Tests/**`). +- **Not touched**: `Api`, `Api.SlpSoftware` sources (only regression-tested), Identity, frontend, CI. +- **Construction stages**: Functional Design, NFR Requirements, NFR Design, Code Generation (Infrastructure Design skipped). +- **Done when**: requirements acceptance (U1) met, per-unit build and tests green, `Api`/`Api.SlpSoftware` regression green, hand-back note sent, **requester's "go" received**. +- **Commit(s)**: on `feature/andreaslop-site-hosting`; no push. + +## U2 andreaslop-client +- **Scope**: C1 client project and solution entry (Clients), C5 theme and build variables, C7 setup token (Identity + setup page), C6 CI/CD, Pi manual-step list, test deploy (with Bryan's go, test only). +- **Code locations**: `src/SlpModularCms.Api.AndreaSlopFotografie/**`, `src/SlpModularCms.Modules.Identity/**` (+ tests), `frontend/**`, `.gitea/workflows/**`, `SlpModularCms.sln`, docs. +- **Construction stages**: NFR Requirements, NFR Design, Infrastructure Design, Code Generation (Functional Design skipped). +- **Starts**: only after U1 hand-back and the requester's "go". +- **Done when**: requirements acceptance (U2) met, hand-back note sent. +- **Commit(s)**: same branch; one PR after U2 when Bryan asks. + +## Cross-unit +Build and Test (all units), then Operations (Deployment Setup, Monitoring Setup, Production Readiness for the test environment). diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/plans/application-design-plan.md b/aidlc-docs/features/andreaslop-site-hosting/inception/plans/application-design-plan.md new file mode 100644 index 0000000..cb469c0 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/plans/application-design-plan.md @@ -0,0 +1,46 @@ +# Application Design Plan - andreaslop-site-hosting + +## Steps +- [x] Analyse requirements and host code (done: CmsHost, StaticContentExtensions, CspPolicyCatalog, SecurityHeadersOptions, SetupController) +- [x] Collect answers to the design questions below +- [x] Generate components.md +- [x] Generate component-methods.md +- [x] Generate services.md +- [x] Generate component-dependency.md +- [x] Generate application-design.md (consolidated) +- [x] Validate completeness and consistency (security baseline / PBT applicability) + +## Facts from the code that shape the questions +- `SecurityHeadersOptions.AllowedConnectOrigins` is applied to **both** `Strict` and `Relaxed`. If the Umami and Sentry origins were put there for Andrea's site, the admin (`/admin`, `/api/v1`, under `Strict`) would get them too. `AllowedScriptOrigins` is only used by `Relaxed` today. +- Linux file systems are case-sensitive, and all page files are lowercase. A request `/Over-Mij` therefore resolves to a known page exactly when `over-mij.html` exists. A cached "known page set" is not strictly needed: a file-exists predicate on the lowercased name gives the same nginx behaviour. +- `UseHttpsRedirection` is a no-op when the host listens on plain HTTP only without an HTTPS port configured; the proxy Pi talks HTTP to the app. There is no forwarded-headers handling in `CmsHost` today. To be verified in NFR Design against the SlpSoftware deployment. +- `SetupController` (`GET /Setup/status`, `POST /Setup/owner`) has no protection other than "system not yet initialised". The admin setup page posts to it. + +## Design Questions + +### Question 1: Origins for the StrictSite policy +Where do the Umami script origin and the Sentry connect origins for the website live? + +- A) New separate lists in `SecurityHeaders` (for example `AllowedSiteScriptOrigins`, `AllowedSiteConnectOrigins`) used only by `StrictSite`; the admin policies stay exactly as strict as today (recommended) +- B) Reuse the existing `AllowedScriptOrigins` / `AllowedConnectOrigins`; accept that `Strict` (admin and API) then also lists the Sentry ingest origin in `connect-src` +- X) Other (please describe after [Answer]: tag below) + +[Answer]: A (RELAYED by CMS & API on Bryan's behalf; confirmed when Bryan approves the design) + +### Question 2: How the host decides a page is "known" +nginx canonicalises (301) only known pages. How should the host decide this? + +- A) Per request, a file-exists check on the lowercased name (`.html`, or `/index.html`); no cache, so a site delivered in place (symlink variant, rsync) is always current. The pure resolver takes the check as a predicate (recommended) +- B) A snapshot of the known pages built at startup and refreshed on a short timer or file watcher +- X) Other (please describe after [Answer]: tag below) + +[Answer]: A (RELAYED by CMS & API on Bryan's behalf; confirmed when Bryan approves the design) + +### Question 3: First-admin setup token in the admin +The setup token protects `POST /Setup/owner`. How does the person doing the first setup supply it? + +- A) The setup page shows a "setup token" field, but only when the server says one is required (`GET /Setup/status` returns `tokenRequired`); the token is sent in a request header; small frontend change, no change when no token is configured (recommended) +- B) No frontend change: the token is sent only as a header by a direct API call (for example curl), the setup page stays as it is +- X) Other (please describe after [Answer]: tag below) + +[Answer]: A (RELAYED by CMS & API on Bryan's behalf; confirmed when Bryan approves the design) diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/plans/execution-plan.md b/aidlc-docs/features/andreaslop-site-hosting/inception/plans/execution-plan.md new file mode 100644 index 0000000..4f92647 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/plans/execution-plan.md @@ -0,0 +1,170 @@ +# Execution Plan - andreaslop-site-hosting + +## Detailed Analysis Summary + +### Transformation Scope (Brownfield) +- **Type**: Extension of the shared host (`SlpModularCms.Core`) plus one new deployable client, an admin theming mechanism and CI/CD for a second deployment target. No rewrite; existing clients (`Api`, `Api.SlpSoftware`) must behave exactly as before. +- **Primary changes**: (U1) `WebsiteMode.PrerenderedPages` with nginx-parity serving, `StrictSite` CSP policy, `Website:NoIndex`; (U2) client `SlpModularCms.Api.AndreaSlopFotografie`, admin theme via `VITE_THEME`/`VITE_DEFAULT_LANGUAGE`, optional first-admin setup token, CI/CD to the test Pi. +- **Related components**: Core (`CmsHost`, `CmsHostOptions`, `StaticContentExtensions`, `CspPolicyCatalog`, security headers), Modules.Identity (setup token), frontend (theme tokens, build), `.gitea/workflows/*`, README / `WEBSITE_WORKSPACE.md`. + +### Change Impact Assessment +- **User-facing changes**: Yes - public website served by the host (visitor), themed Dutch admin (site owner). +- **Structural changes**: Yes - new client project, new options/middleware in Core. +- **Data model changes**: No new entities. New database instance per site (`AndreaSlopFotografieTest`); existing migrations apply. Setup token is configuration, not data. +- **API changes**: Setup endpoint gains an optional token requirement (only when configured). No other API change. +- **NFR impact**: Yes - Security Baseline (blocking), PBT partial, performance of per-request path resolution, proxy/HTTP 1.0 behaviour. + +### Component Relationships + +```mermaid +graph TD + core["SlpModularCms.Core
(CmsHost, StaticContent, CSP catalog)"] + api["SlpModularCms.Api"] + slp["SlpModularCms.Api.SlpSoftware"] + andrea["SlpModularCms.Api.AndreaSlopFotografie
(new client, U2)"] + ident["Modules.Identity
(setup token)"] + avail["Modules.Availability"] + fe["frontend
(theme per site)"] + ci["Gitea workflows
(CI + deploy-scp)"] + pi["Test Pi
(port 5200)"] + + core -->|"unchanged behaviour"| api + core -->|"unchanged behaviour"| slp + core -->|"PrerenderedPages + StrictSite (U1)"| andrea + andrea --> ident + andrea -.->|"only if required"| avail + fe -->|"VITE_THEME=andreaslop"| andrea + ci -->|"build + deploy (test only)"| andrea + andrea --> pi + + classDef shared fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; + classDef existing fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; + classDef new fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000; + classDef ext fill:#d6bcfa,stroke:#553c9a,stroke-width:1px,color:#000; + class core shared; + class api,slp,ident,avail,fe existing; + class andrea new; + class ci,pi ext; +``` + +Text alternative: Core serves all clients; the new Andrea client uses the new website mode and policy, references Identity (Availability only if needed), gets a themed admin build and is deployed by CI to the test Pi. + +| Component | Change type | Reason | Priority | +|---|---|---|---| +| Core hosting | Major (additive) | New mode, middleware, policy | Critical | +| Api, Api.SlpSoftware | None (regression-guarded) | Must stay unchanged | Critical | +| Identity | Minor | Optional setup token | Important | +| Frontend | Minor | Theme tokens, language default | Important | +| CI/CD | Minor | Per-client admin build, second deploy target | Important | +| Docs | Minor | README, WEBSITE_WORKSPACE.md | Important | + +### Risk Assessment +- **Risk level**: Medium. Shared host change touches every client (mitigated by default `SpaFallback` and regression tests); public-facing path handling (traversal / open redirect) is security-relevant; deployment on a Pi that is not yet provisioned. +- **Rollback complexity**: Easy for code (feature flag by default off); moderate for the Pi (manual steps by Bryan, test only). +- **Testing complexity**: Complex (PBT on pure functions, integration tests of the pipeline with a temp website root, theme visual/contrast check, deploy smoke test). + +## Workflow Visualization + +```mermaid +flowchart TD + Start(["Brief from CMS & API"]) + + subgraph INCEPTION["INCEPTION PHASE"] + WD["Workspace Detection
COMPLETED"] + RE["Reverse Engineering
SKIP (reuse)"] + RA["Requirements Analysis
COMPLETED"] + US["User Stories
SKIP"] + WP["Workflow Planning
IN PROGRESS"] + AD["Application Design
EXECUTE"] + UG["Units Generation
EXECUTE (minimal)"] + end + + subgraph CONSTRUCTION["CONSTRUCTION PHASE"] + U1["Unit U1 core-site-hosting
FD, NFR Req, NFR Design, Code, per-unit build/test"] + H1["Hand-back U1 + wait for go"] + U2["Unit U2 andreaslop-client
NFR Req, NFR Design, Infra Design, Code, per-unit build/test"] + H2["Hand-back U2"] + BT["Build and Test (all units)
EXECUTE"] + end + + subgraph OPERATIONS["OPERATIONS PHASE"] + DS["Deployment Setup
EXECUTE"] + MS["Monitoring Setup
EXECUTE"] + PRV["Production Readiness Validation
EXECUTE"] + end + + Start --> WD --> RE --> RA --> US --> WP --> AD --> UG --> U1 --> H1 --> U2 --> H2 --> BT --> DS --> MS --> PRV --> End(["Complete"]) + + style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff + style RA fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff + style WP fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff + style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff + style RE fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000 + style US fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000 + style AD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 + style UG fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 + style U1 fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 + style U2 fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 + style H1 fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000 + style H2 fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000 + style DS fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 + style MS fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 + style PRV fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 + style Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000 + style End fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000 + linkStyle default stroke:#333,stroke-width:2px +``` + +Text alternative: green = done/always, orange dashed = conditional EXECUTE, grey dashed = SKIP, purple = checkpoints with the requester. + +## Phases to Execute + +### INCEPTION +- [x] Workspace Detection (COMPLETED) +- [x] Reverse Engineering (SKIPPED - existing `_shared/reverse-engineering/` reused; key host files read directly) +- [x] Requirements Analysis (COMPLETED, approved by Bryan) +- [x] User Stories (SKIPPED per Q6) +- [x] Workflow Planning (IN PROGRESS) +- [ ] Application Design - EXECUTE + - **Rationale**: New components (WebsiteMode option, path resolver, prerendered-site middleware, StrictSite policy, client project, theme mechanism, setup-token check). The requester expects Bryan's design approval. +- [ ] Units Generation - EXECUTE (minimal; no separate Units Planning question round) + - **Rationale**: The two units are fixed by the brief. Formalise them (scope, order, dependencies, hand-back gates) in `unit-of-work.md`. + +### CONSTRUCTION (per unit; U2 only after the requester's "go") +**U1 core-site-hosting** +- [ ] Functional Design - EXECUTE: path-resolution rule table, canonical form, known-page set, 404 and reserved-prefix behaviour, noindex/robots rules. +- [ ] NFR Requirements - EXECUTE: security (traversal, open redirect, header completeness), PBT properties (partial mode), performance of lookup, proxy/HTTP 1.0 compatibility. +- [ ] NFR Design - EXECUTE (compact): caching of file existence / known-page refresh, middleware ordering, compression scope. +- [ ] Infrastructure Design - SKIP: no infrastructure change in U1. +- [ ] Code Generation - EXECUTE (plan + generation + automatic per-unit build/test, regression run of `Api`/`Api.SlpSoftware`) +- [ ] Hand-back note U1, message to "CMS & API", **wait for go** + +**U2 andreaslop-client** +- [ ] Functional Design - SKIP: no new business domain; theme token mapping and client composition are covered by Application Design and requirements. +- [ ] NFR Requirements - EXECUTE: setup-token security, secrets handling, contrast/accessibility of the theme, login rate limiting. +- [ ] NFR Design - EXECUTE (compact): token check placement, constant-time compare, configuration shape. +- [ ] Infrastructure Design - EXECUTE: Pi layout, systemd user unit, env variables, database `AndreaSlopFotografieTest` / user `AndreaSlopFotografie`, ufw rule for port 5200, proxy-Pi route, Gitea secrets, both `wwwroot/web` delivery variants, manual-step list for Bryan; then notify "CMS & API" so the Pi-Main session can draft commands. +- [ ] Code Generation - EXECUTE (client, theme, setup token, workflows; per-unit build/test) +- [ ] Test deploy - only with Bryan's go in this session, test host only +- [ ] Hand-back note U2 + +- [ ] Build and Test - EXECUTE (full solution, frontend build per theme, cross-unit integration, smoke checks) + +### OPERATIONS (Operations Configuration = Yes) +- [ ] Deployment Setup - EXECUTE +- [ ] Monitoring Setup - EXECUTE +- [ ] Production Readiness Validation - EXECUTE (for the test environment; production out of scope) + +## Package Change Sequence +1. `SlpModularCms.Core` (+ `Core.Tests`) - U1 +2. `Api` / `Api.SlpSoftware` regression run - U1 +3. `SlpModularCms.Modules.Identity` (+ tests) - setup token (U2) +4. `frontend` theme and build variables - U2 +5. `SlpModularCms.Api.AndreaSlopFotografie` (+ solution entry under Clients) - U2 +6. `.gitea/workflows` (CI matrix per client, deploy to test) - U2 +7. Docs (`README.md`, `WEBSITE_WORKSPACE.md`) - U1 and U2 + +## Success Criteria +- **Primary goal**: Andrea's prerendered site and a themed Dutch admin served by one SlpModularCms process on the test Pi, with behaviour matching today's nginx and the exact CSP. +- **Key deliverables**: WebsiteMode + StrictSite in Core; new client; theme; setup token; CI/CD; hand-back notes; Pi manual-step list. +- **Quality gates**: Security Baseline compliance per stage; PBT-02/03/07/08/09 satisfied; `Api` and `Api.SlpSoftware` green and unchanged; per-unit build/test; requester's "go" before U2; Bryan's approval of requirements and design; no push without Bryan's request; no production changes. diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/plans/unit-of-work-plan.md b/aidlc-docs/features/andreaslop-site-hosting/inception/plans/unit-of-work-plan.md new file mode 100644 index 0000000..e69c004 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/plans/unit-of-work-plan.md @@ -0,0 +1,9 @@ +# Unit of Work Plan - andreaslop-site-hosting + +Decomposition is fixed by the brief and the approved execution plan (two units, U1 then U2, hand-back gate between them). No open decomposition questions: no ambiguity found in story grouping, dependencies, deployment or code organisation (brownfield; structure rules from CLAUDE.md/AGENTS.md apply). + +- [x] Generate `inception/application-design/unit-of-work.md` +- [x] Generate `inception/application-design/unit-of-work-dependency.md` +- [x] Generate `inception/application-design/unit-of-work-story-map.md` (requirements-to-unit map; User Stories were skipped) +- [x] Validate unit boundaries and dependencies +- [x] Ensure every requirement is assigned to a unit diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/pi-inventory-notes.md b/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/pi-inventory-notes.md new file mode 100644 index 0000000..693db1b --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/pi-inventory-notes.md @@ -0,0 +1,27 @@ +# Pi inventory notes (input for Infrastructure Design, U2) + +Source: relayed by session "CMS & API" from session "Pi-Main - Server" (read-only inventory, no sudo, facts not verified by this session). Full write-up in the website repo: `AndreaSlopFotografie-cms-api-foundation/aidlc-docs/features/cms-api-foundation/construction/cms-host/pi-inventory.md`. Status: UNVERIFIED INPUT, to be checked against `.gitea/workflows/deploy-scp.yaml` and confirmed by Bryan. + +## Relayed decision (pending Bryan's confirmation in this session) +- The test instance takes over hostname `test.andreaslop.nl`. Verify first on the Pi via the app port; Bryan then switches the route on the proxy Pi to the new port. nginx on the app Pi stays as fallback. + +## Pattern to copy (SlpSoftware test) +- User `gitea-workflow`; `~/apps//test/{releases,current,shared}`; `shared/env` (mode 600); `shared/wwwroot-web` symlink to `/mnt/storage1/www/html/...`. +- systemd USER unit: `WorkingDirectory=current`, `ExecStart=dotnet ...dll`, `EnvironmentFile=shared/env`, `Restart=on-failure`, `KillSignal=SIGINT`. +- Deploy: appleboy/drone-scp over SSH port 2224 as `gitea-workflow`; DB backup script before/after release. + +## Network and resources +- Free ports: 5200 (test), 5201 (production, later). ufw rule needed, allow only from proxy Pi 192.168.1.102. Taken: 5100/5101, 5150/5151, 5000, 3000, 3001, 3306, 80, 2224. +- Proxy Pi (TLS, certbot) forwards DIRECTLY to the app port over HTTP/1.0, bypassing nginx on the app Pi. The host must therefore provide gzip, security headers, canonical 301s and a real 404 itself, and `UseHttpsRedirection` / forwarded headers must be handled as SlpSoftware does (open point 2 in requirements). +- Pi 4, about 5.4 GiB free RAM; one more .NET process (~250-300 MB) fits. Uploads/photos on `/mnt/storage1`; releases on the SD card. +- ARM64 builds must require runner label `arm64` or `linux-arm64` (the PC runner is x64). + +## Database +- MariaDB 10.11 on localhost. Convention: PascalCase DB named after the app, user = app name @localhost. Suggested by Pi-Main: `AndreaSlopTest` / `AndreaSlopCms`@localhost. SUPERSEDED by relayed naming decision: database `AndreaSlopFotografieTest`, user `AndreaSlopFotografie`@localhost (reason: the CMS is part of the website; the company is AndreaSlopFotografie). Confirmed by Bryan with approval of requirements. Existing DB `andreaslop` is WordPress: do not confuse. Bryan creates DB and user with sudo; the Pi-Main session adds the new DB to the backup script. + +## Open design option (include both variants in Infrastructure Design) +- Variant 1: the website CI delivers files into `wwwroot/web` directly. +- Variant 2: `shared/wwwroot-web` symlinks to `/mnt/storage1/www/html/andreaslop-test`, the folder the existing static web deploy already writes to, so the current web deploy keeps working and the CMS host serves those files. Implication for design: the known-page set must refresh when files change in place (requirements open point 1). + +## Manual steps for Bryan (to be finalised in the design) +User unit, env file, database and user, ufw rule, proxy-Pi server block/route switch, Gitea secrets in the CMS repo, backup script entry. The Pi-Main session can draft exact commands once the list is final (ask via "CMS & API"). diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/requirement-verification-questions.md b/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/requirement-verification-questions.md new file mode 100644 index 0000000..cb7fdd4 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/requirement-verification-questions.md @@ -0,0 +1,100 @@ +# Requirement Verification Questions - andreaslop-site-hosting + +Source brief: `aidlc-docs/_shared/handoffs/cms-api-foundation-brief-u1-u2.md` (decisions 1-7 in section 2 are taken and NOT re-asked). +Please fill in your choice after each `[Answer]:` tag. + +## Question 1: First-administrator setup flow hardening (Security) +The brief asks us to assess whether the first-admin setup flow on the new instance can be abused by a third party before the first administrator exists (a freshly deployed test host is publicly reachable). What should the scope be? + +- A) Assess and test the existing Identity behaviour only (no code change in Identity); document the residual risk (anyone who reaches /admin first can claim the admin account) +- B) Assess, and additionally require a one-time setup token from configuration (env var / appsettings.local.json) on the setup endpoint, only when configured - existing hosts unchanged +- C) Assess, and restrict the setup endpoint in the new client through configuration only (e.g. host/IP allow-list), no Identity change +- X) Other (please describe after [Answer]: tag below) + +[Answer]: B +(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session) + +## Question 2: Commit / PR flow for the two units +How do we deliver U1 and U2 in git? (Per standing rule: I commit, but never push unless you say so.) + +- A) One feature branch, commits per unit; no push until you ask; one PR for the whole feature after U2 +- B) One feature branch, but a PR for U1 alone after hand-back (U1 is behaviour-neutral for existing hosts), then U2 on a follow-up branch +- C) One feature branch, commits per unit; I push and open the PR only when you explicitly say so, timing decided by you per unit +- X) Other (please describe after [Answer]: tag below) + +[Answer]: A +(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session) + +## Question 3: Deployment to the test host +May the CI/CD pipeline deploy the new client to the test host, and how is it triggered? + +- A) Manual trigger only (workflow_dispatch); I may not run it, you trigger it +- B) Automatic on merge to master (like the existing pipeline), plus manual trigger +- C) I only write and verify the workflow (lint/dry run); no deploy to test is performed in this feature, you do the first deploy +- X) Other (please describe after [Answer]: tag below) + +[Answer]: X) Pipeline MAY deploy the new client to the TEST host (never production); the CMS session may start the test deploy itself once pipeline and Pi are ready. Bryan: "Hij mag hem uitrollen naar test. Graag zelfs dan kan het zsm getest worden, maar de CI/CD moet er nog op worden ingericht en de host ook." +(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session) + +## Question 4: Test-host prerequisites +Do the test host and Gitea secrets for Andrea's instance already exist? + +- A) Yes - host, path, SSH user and Gitea secrets exist; I only need the names (you will tell me, or I read them from the existing workflow) +- B) Partly - the host exists but secrets/paths for the Andrea instance still have to be defined; I list what is needed in the infrastructure design +- C) No - nothing exists yet; the design must also cover creating them (documented as manual steps for you) +- X) Other (please describe after [Answer]: tag below) + +[Answer]: X) Partly exists (matches B). Bryan: "De host heeft al de juiste accounts om het op te kunnen zetten, maar de inrichting op de host moet nog worden ingeregeld zoals paden, secrets, environment variables." Infrastructure design must list the remaining Pi setup (paths, secrets, env vars, database, reverse proxy) as manual steps for Bryan. +(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session) + +## Question 5: Admin theme scope in U2 +How far should the theme override go beyond colours, radius and font? + +- A) Tokens only (colours, radius, font) plus logo and favicon, as in the brief; no layout or component changes +- B) Tokens plus login/setup page branding (logo, title text) via theme assets; no layout changes +- X) Other (please describe after [Answer]: tag below) + +[Answer]: A +(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session) + +## Question 6: User Stories stage +Is a User Stories stage wanted for this infrastructure-heavy feature (personas would be: site visitor, site owner/admin, operator/developer)? + +- A) Skip User Stories (requirements with acceptance criteria are enough) +- B) Run a short, minimal User Stories stage +- X) Other (please describe after [Answer]: tag below) + +[Answer]: A +(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session) + +## Vraag 7: Beveiligingsextensies +Moeten de beveiligingsregels (Security Baseline) als harde vereisten worden afgedwongen voor deze feature? (De brief meldt dat je dit al hebt ingeschakeld; graag bevestigen.) + +- A) Ja - dwing alle BEVEILIGINGSREGELS af als blokkerende vereisten +- B) Nee - sla alle BEVEILIGINGSREGELS over +- X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: A +(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session) + +## Vraag 8: Property-based testing +Moet property-based testing worden afgedwongen? (De brief meldt: gedeeltelijke modus, regels PBT-02, 03, 07, 08, 09; graag bevestigen.) + +- A) Ja, gedeeltelijk - alleen PBT-02, 03, 07, 08, 09 (puur functies: padresolutie, canonieke vorm, beleid round-trip) +- B) Ja, volledig - alle PBT-regels als blokkerend +- C) Nee - sla property-based testing over +- X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: A +(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session) + +## Vraag 9: Operations-fase +Moet deze feature na Construction door de Operations-fase (deployment- en monitoringsetup, production readiness)? Let op: de CI/CD-wijzigingen voor U2 zitten sowieso in de requirements; dit gaat om de aparte Operations-fase. + +- A) Ja - voer de Operations-fase uit na Construction (deployment + monitoring setup) +- B) Nee - stop na Build and Test (CI/CD voor de testhost wordt wel gebouwd in U2 Code Generation) +- C) Nog niet zeker - vraag het me opnieuw na de Construction-fase +- X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: A +(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session) diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/requirements.md b/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/requirements.md new file mode 100644 index 0000000..af8d933 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/requirements.md @@ -0,0 +1,71 @@ +# 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'