AIDLC-documentatie voor andreaslop-site-hosting (U1 tot en met Code Generation)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-06 15:52:04 +01:00
co-authored by Claude Sonnet 5.5
parent 7d21d9024a
commit d355519cec
31 changed files with 1598 additions and 0 deletions
@@ -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).
@@ -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.
@@ -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: `<name>.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("/<lowercase-name>")`, 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' <site script origins>; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self' <site connect origins>; 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.
@@ -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 `<lowercase-name>.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.
@@ -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.
@@ -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) `<name>.html`, (2) the literal file for extension paths or `<name>/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.
@@ -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).
@@ -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.
@@ -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.
@@ -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")
@@ -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)
@@ -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.
@@ -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")