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,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.
@@ -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.
@@ -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<string, bool> 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<WebsiteOptions> 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<string> allowedScriptOrigins, IEnumerable<string> allowedConnectOrigins,
IEnumerable<string>? siteScriptOrigins = null, IEnumerable<string>? siteConnectOrigins = null);
}
public sealed class SecurityHeadersOptions { /* + */ public IList<string> AllowedSiteScriptOrigins { get; set; } = []; public IList<string> 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/<name>/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.
@@ -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<string,bool> 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/<name>/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.
@@ -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/<id>` -> 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.
@@ -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.
@@ -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.
@@ -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).
@@ -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 (`<name>.html`, or `<name>/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)
@@ -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<br/>(CmsHost, StaticContent, CSP catalog)"]
api["SlpModularCms.Api"]
slp["SlpModularCms.Api.SlpSoftware"]
andrea["SlpModularCms.Api.AndreaSlopFotografie<br/>(new client, U2)"]
ident["Modules.Identity<br/>(setup token)"]
avail["Modules.Availability"]
fe["frontend<br/>(theme per site)"]
ci["Gitea workflows<br/>(CI + deploy-scp)"]
pi["Test Pi<br/>(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<br/><b>COMPLETED</b>"]
RE["Reverse Engineering<br/><b>SKIP (reuse)</b>"]
RA["Requirements Analysis<br/><b>COMPLETED</b>"]
US["User Stories<br/><b>SKIP</b>"]
WP["Workflow Planning<br/><b>IN PROGRESS</b>"]
AD["Application Design<br/><b>EXECUTE</b>"]
UG["Units Generation<br/><b>EXECUTE (minimal)</b>"]
end
subgraph CONSTRUCTION["CONSTRUCTION PHASE"]
U1["Unit U1 core-site-hosting<br/>FD, NFR Req, NFR Design, Code, per-unit build/test"]
H1["Hand-back U1 + wait for go"]
U2["Unit U2 andreaslop-client<br/>NFR Req, NFR Design, Infra Design, Code, per-unit build/test"]
H2["Hand-back U2"]
BT["Build and Test (all units)<br/><b>EXECUTE</b>"]
end
subgraph OPERATIONS["OPERATIONS PHASE"]
DS["Deployment Setup<br/><b>EXECUTE</b>"]
MS["Monitoring Setup<br/><b>EXECUTE</b>"]
PRV["Production Readiness Validation<br/><b>EXECUTE</b>"]
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.
@@ -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
@@ -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/<name>/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").
@@ -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)
@@ -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' <script origins>; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self' <connect origins>; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'`
plus `X-Frame-Options: DENY` and `Referrer-Policy: strict-origin-when-cross-origin`. Origins come from the existing security-header configuration. An exact match is achievable (order is catalog-internal); `Strict` need not change.
- **FR-U1-09 Other headers.** Verify and test that website responses carry `Strict-Transport-Security: max-age=31536000; includeSubDomains`, `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin` and the CSP, including on 301, 404, assets and robots.txt.
- **FR-U1-10 Pipeline order.** Security headers before static content; compression before the website mount; website 404 handling last, after API routes; documented in `CmsHost`.
- **FR-U1-11 Docs.** Update `WEBSITE_WORKSPACE.md` and `README.md` for the new mode and settings.
### Acceptance (U1)
- Unit tests and property-based tests (partial PBT, section 5): path resolution never escapes the root, canonicalisation is idempotent, reserved prefixes never resolve, policy round trip.
- `Api` and `Api.SlpSoftware` suites green, behaviour unchanged (regression run recorded).
- Hand-back note (brief section 7) written and sent to "CMS & API".
- Proxy awareness: the test site sits behind a reverse-proxy Pi that terminates TLS. Existing `UseHttpsRedirection` / forwarded-header handling must not cause redirect loops or absolute `http://` redirects; website redirects are relative (nginx `absolute_redirect off` parity). Verified in design.
## 3. Unit U2 - andreaslop-client
- **FR-U2-01 Client project** `SlpModularCms.Api.AndreaSlopFotografie` under **Clients** in the solution: thin `Program.cs` on `CmsHost`, `WebsiteMode = PrerenderedPages`, three-file appsettings (`appsettings.json`, `appsettings.{Env}.json`, uncommitted `appsettings.local.json`), own database, own dev port, `SecurityHeaders:DefaultPolicy = StrictSite` with the Umami (`https://analytics.slpsoftware.nl`) and Sentry (`https://o4511795618185216.ingest.de.sentry.io`) origins, `Website:NoIndex = true` for test.
- **FR-U2-02 Module set** = module projects the client references (no config filter). Determine and report the minimum (Identity; is Availability required?). `Offerings` not referenced; `/api/v1/System/capabilities` must not list it.
- **FR-U2-03 Admin theme.** `frontend/themes/andreaslop/` with CSS overriding the existing design tokens (colours, radius, font), plus logo and favicon. `VITE_THEME` selects it at build time (unset = today's look). New `VITE_DEFAULT_LANGUAGE` (`nl` for Andrea; English stays selectable). Palette: paper `#faf7f2` / `#f1ebe2` / `#e8e0d5`, ink `#232120` / `#55504b` / `#8a827a`, line `#e2dad0`, accent `#7f8b76`, accent-deep `#5f6a58` (text/buttons), accent-deeper `#475042`, sand `#d9cdbc`, error `#a4443a`. Fonts Marcellus (headings) and Jost (body) with the site's fallbacks, **self-hosted** (the admin's CSP is `font-src 'self'`). Scope per Q5: tokens + logo + favicon only, no layout or component changes. Contrast stays accessible (destructive and focus-ring colours readable on paper).
- **FR-U2-04 CI/CD.** Build the admin per deployable client with its `VITE_THEME`, `VITE_DEFAULT_LANGUAGE`, `VITE_APP_TITLE`; publish the new host; deploy to the **test** host with the existing atomic release switch; `wwwroot/web/` stays outside the swapped release directory so the site survives every CMS deploy. The production path for `Api.SlpSoftware` is not touched.
- **FR-U2-05 Test deploy** (Q3, relayed): the pipeline may deploy to the test host, and this session may start the test deploy itself once pipeline and Pi are ready - **test only, never production**. Bryan's go is confirmed in this session before the first deploy.
- **FR-U2-06 Host provisioning** (Q4): the Raspberry Pi accounts exist, but paths, secrets, environment variables, database, service unit and reverse proxy are not set up yet. The infrastructure design lists every remaining step as a manual checklist for Bryan. Pi inventory comes via "CMS & API" from "Pi-Main - Server"; this session does not contact that session directly.
- **FR-U2-07 First-admin setup token** (Q1=B): assess the existing setup flow (who can call it while no admin exists) and add an optional one-time setup token read from configuration. When configured, the setup endpoint requires it; when not configured, behaviour is unchanged for existing hosts. Constant-time comparison, never logged, covered by the same rate limiting as login. Tests: no token configured, wrong token, correct token, setup after the first admin exists (rejected). The token is a secret supplied outside the repo.
- **FR-U2-08 Auth** otherwise unchanged (Identity module; invitations after the first admin). Login rate limiting stays.
### Acceptance (U2)
Host starts on test with its own database; `/admin` shows Andrea's theme in Dutch; first-admin setup and login work; `/api/v1/System/capabilities` has no `Offerings`; `/health` is green; `Api.SlpSoftware` still builds and deploys unchanged; hand-back note written.
## 4. Out of scope
Production deployment, the `Master` module for Andrea, extra roles, SSR, CMS-driven site content, a configuration-based module filter, changes to the website repo, theme editing in the admin, serving the theme from the API.
## 5. Cross-cutting
- **Security Baseline**: enforced (blocking): path input validation, secure headers, no secrets in the repo, rate limiting, safe error handling, no sensitive data in logs, no new packages planned.
- **Property-based testing**: partial mode, rules PBT-02, 03, 07, 08, 09 (pure functions: path resolution, canonical idempotence, policy round trip). Seeds are logged on failure and reproducible; tooling follows the existing test framework (decided in NFR/Code Generation).
- **Per-unit build/test**: build and run tests after each unit's code generation.
- **Git**: branch `feature/andreaslop-site-hosting`, commits per unit, no push until Bryan asks, one PR after U2 (Q2=A).
- **Operations phase**: yes (Q9=A): deployment and monitoring setup and production readiness, assessed for the test environment. Production itself stays out of scope.
- **User Stories**: skipped (Q6).
- **Language**: documentation English, conversation Dutch.
- **Boundaries**: website repo is read-only; no production changes; Pi contact only through "CMS & API".
## 6. Open points to resolve in design
1. Where the known-page set is built (scan at startup vs. per-request lookup) and how it refreshes when a new site build is deployed.
2. Interaction of `UseHttpsRedirection` / forwarded headers with the reverse-proxy Pi.
3. Whether `Availability` is required next to `Identity` for the admin.
4. Where the setup-token check lives (Identity module vs. host) without changing existing hosts.
5. Whether compression is limited to the website mount (proposal: yes, avoids BREACH-style exposure on authenticated API responses).