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:
+26
@@ -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).
|
||||
+77
@@ -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.
|
||||
+51
@@ -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.
|
||||
+40
@@ -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.
|
||||
+37
@@ -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.
|
||||
+24
@@ -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.
|
||||
+56
@@ -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).
|
||||
+12
@@ -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.
|
||||
+31
@@ -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.
|
||||
+20
@@ -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")
|
||||
+8
@@ -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)
|
||||
+15
@@ -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.
|
||||
+40
@@ -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")
|
||||
Reference in New Issue
Block a user