From 7d21d9024a8c4c02ba3d54bf2374b08525e0f1f2 Mon Sep 17 00:00:00 2001 From: Sluijsens Date: Fri, 6 Nov 2026 15:52:04 +0100 Subject: [PATCH 01/66] Voeg WebsiteMode.PrerenderedPages toe: nginx-gelijke serving van een voorgerenderde website - Pure WebsitePathResolver (canonieke 301's, echte 404, dotfiles geweigerd, gereserveerde prefixes) - PrerenderedSiteMiddleware, 404-fallback na de API-routes, gzip, Cache-Control, NoIndex/robots.txt - Beleid StrictSite met eigen AllowedSite*Origins; volledige headerset op alle websiteresponses - Tests: voorbeelden, FsCheck-properties en integratietests op een in-memory server Co-Authored-By: Claude Sonnet 5.5 --- README.md | 2 + WEBSITE_WORKSPACE.md | 33 ++ ...ecurityHeaderWriterDocumentHeadersTests.cs | 56 +++ .../Hosting/Security/StrictSitePolicyTests.cs | 138 ++++++ .../PrerenderedSiteIntegrationTests.cs | 464 ++++++++++++++++++ .../WebsitePathResolverPropertyTests.cs | 145 ++++++ .../Website/WebsitePathResolverTests.cs | 224 +++++++++ .../SlpModularCms.Core.Tests.csproj | 2 + src/SlpModularCms.Core/Hosting/CmsHost.cs | 25 +- .../Hosting/CmsHostOptions.cs | 26 +- .../Hosting/Security/CspPolicyCatalog.cs | 35 +- .../Hosting/Security/CspPolicyProvider.cs | 9 +- .../Hosting/Security/SecurityHeaderWriter.cs | 9 +- .../Security/SecurityHeadersExtensions.cs | 10 +- .../Security/SecurityHeadersMiddleware.cs | 19 +- .../Security/SecurityHeadersOptions.cs | 12 + .../Hosting/StaticContentExtensions.cs | 35 +- .../Website/PrerenderedSiteExtensions.cs | 73 +++ .../Website/PrerenderedSiteMiddleware.cs | 149 ++++++ .../Hosting/Website/WebsiteFileAccess.cs | 100 ++++ .../Hosting/Website/WebsiteHostingMarker.cs | 10 + .../Hosting/Website/WebsiteNotFoundHandler.cs | 67 +++ .../Hosting/Website/WebsiteOptions.cs | 13 + .../Hosting/Website/WebsitePathResolver.cs | 205 ++++++++ .../Hosting/Website/WebsiteResolution.cs | 21 + 25 files changed, 1859 insertions(+), 23 deletions(-) create mode 100644 src/SlpModularCms.Core.Tests/Hosting/Security/SecurityHeaderWriterDocumentHeadersTests.cs create mode 100644 src/SlpModularCms.Core.Tests/Hosting/Security/StrictSitePolicyTests.cs create mode 100644 src/SlpModularCms.Core.Tests/Hosting/Website/PrerenderedSiteIntegrationTests.cs create mode 100644 src/SlpModularCms.Core.Tests/Hosting/Website/WebsitePathResolverPropertyTests.cs create mode 100644 src/SlpModularCms.Core.Tests/Hosting/Website/WebsitePathResolverTests.cs create mode 100644 src/SlpModularCms.Core/Hosting/Website/PrerenderedSiteExtensions.cs create mode 100644 src/SlpModularCms.Core/Hosting/Website/PrerenderedSiteMiddleware.cs create mode 100644 src/SlpModularCms.Core/Hosting/Website/WebsiteFileAccess.cs create mode 100644 src/SlpModularCms.Core/Hosting/Website/WebsiteHostingMarker.cs create mode 100644 src/SlpModularCms.Core/Hosting/Website/WebsiteNotFoundHandler.cs create mode 100644 src/SlpModularCms.Core/Hosting/Website/WebsiteOptions.cs create mode 100644 src/SlpModularCms.Core/Hosting/Website/WebsitePathResolver.cs create mode 100644 src/SlpModularCms.Core/Hosting/Website/WebsiteResolution.cs diff --git a/README.md b/README.md index 1945173..7047424 100644 --- a/README.md +++ b/README.md @@ -325,6 +325,8 @@ In productie moeten gevoelige instellingen worden doorgegeven via Environment Va - `Observability__SentryDsn` — leeg is een normale, ondersteunde staat: Sentry wordt dan overgeslagen en alleen console-logging blijft actief - `SecurityHeaders__AllowedScriptOrigins__0`, `SecurityHeaders__AllowedConnectOrigins__0`, ... — externe origins die de CSP van `/admin` en `/api/v1` mag toestaan (bijv. de Umami-scripthost en Sentry's ingest-endpoint). Zie `appsettings.json → SecurityHeaders` voor de volledige optiesvorm; een onbekende `PathPolicies`-policy-naam laat de applicatie bij **opstarten** falen, niet pas bij de eerste request +- **Voorgerenderde website (`WebsiteMode.PrerenderedPages`)** — een client kiest dit in zijn `Program.cs` via `CmsHostOptions` (standaard `SpaFallback`: alles blijft zoals het was). Instellingen voor deze modus: `Website__NoIndex=true` (testinstantie: `X-Robots-Tag` plus `robots.txt` met `Disallow: /`), `SecurityHeaders__DefaultPolicy=StrictSite` met `SecurityHeaders__AllowedSiteScriptOrigins__0`, `SecurityHeaders__AllowedSiteConnectOrigins__0`, ... (alleen gebruikt door `StrictSite`). Logging van de website (301's en 404's op `Information`) gaat via de logger-categorie `SlpModularCms.Website`: zet per omgeving `Logging:LogLevel:SlpModularCms.Website` (test `Information`, standaard en productie `Warning`). Gedrag per pad staat in [`WEBSITE_WORKSPACE.md`](WEBSITE_WORKSPACE.md). + ### 2a. Data Protection key ring (Master CMS Module) De API keys van geregistreerde slaves worden versleuteld opgeslagen met ASP.NET Core Data Protection. De key ring wordt **automatisch** persistent opgeslagen in de database (`PersistKeysToDbContext`, met een expliciete, stabiele applicatie-discriminator) — dit hoeft niet meer apart geconfigureerd te worden. Dit is bewust zo gebouwd omdat de atomische release-switch (zie hierboven) bij elke deploy een nieuwe content-root-map gebruikt: zonder een database-backed key ring zou dat elke keer de key ring weggooien en alle opgeslagen slave-API-keys onleesbaar maken. diff --git a/WEBSITE_WORKSPACE.md b/WEBSITE_WORKSPACE.md index 8df6f6e..faea489 100644 --- a/WEBSITE_WORKSPACE.md +++ b/WEBSITE_WORKSPACE.md @@ -46,6 +46,39 @@ per ongeluk de `index.html`. Dit betekent: bouw je een Single Page Application, dan hoeft je routing-configuratie niets speciaals te doen voor deze server — de fallback wordt door de applicatie zelf verzorgd. +## Alternatief: voorgerenderde site (`WebsiteMode = PrerenderedPages`) + +Een client kan kiezen voor een **voorgerenderde meerpaginasite** (elke pagina is een eigen `.html`-bestand) +in plaats van de SPA-fallback hierboven. Dat is een keuze van de client (`new CmsHostOptions { WebsiteMode = +WebsiteMode.PrerenderedPages }` in zijn `Program.cs`); zonder die keuze verandert er niets. De host serveert dan +zoals nginx dat deed: + +| Verzoek | Resultaat | +|---|---| +| `/` | `index.html` | +| `/over-mij` | `over-mij.html` (ook `map/index.html` als `map.html` ontbreekt) | +| `/Over-Mij`, `/over-mij.html`, `/over-mij/` | één `301` naar `/over-mij` (query blijft behouden; relatieve `Location`) | +| `/index`, `/index.html` | `301` naar `/` | +| elk ander pad met slash aan het eind | `301` naar het pad zonder slash (ook als dat niet bestaat; daarna volgt de 404) | +| bestand met extensie (`/assets/app.abc.js`) | het bestand zelf; nooit omgezet naar kleine letters of doorgestuurd; ontbreekt het, dan `404` | +| onbekend pad, `/404`, `/404.html`, map zonder pagina | `404.html` **met status 404** (bestaat `404.html` niet: kale 404); nooit `index.html` | +| pad met een segment dat met een punt begint (`/.env`, `/.git/...`) | `404`; alleen `/.well-known/...` blijft bereikbaar | +| `/admin`, `/api/v1`, `/health` | nooit door de website afgehandeld; een onbekend `/api/v1`-pad blijft een API-404 | + +Caching: pagina's en overige rootbestanden `Cache-Control: no-cache`, alles onder `/assets/` `public, max-age=31536000, +immutable`. Tekstbestanden (html, css, js, svg, json, xml, txt) worden met **gzip** gecomprimeerd (geen Brotli). De pagina's +worden per verzoek bij het bestandssysteem opgezocht, zonder cache: een nieuwe website-deploy is direct zichtbaar, zonder +herstart van de host. + +Headers: elke websiterespons (pagina, asset, 301, 404, `robots.txt`) krijgt de volledige set (CSP, HSTS, `nosniff`, +`X-Frame-Options`, `Referrer-Policy`). Het beleid is **`StrictSite`**: dezelfde CSP als de site nu heeft +(`script-src 'self'` plus de origins uit `SecurityHeaders:AllowedSiteScriptOrigins`, `connect-src 'self'` plus +`SecurityHeaders:AllowedSiteConnectOrigins`). Die twee lijsten gelden **alleen** voor `StrictSite`; de admin-policies +worden er niet soepeler van. + +Een testinstantie zet `Website:NoIndex = true`: dan krijgt elke websiterespons `X-Robots-Tag: noindex, nofollow` en geeft +`/robots.txt` `User-agent: *` / `Disallow: /`. + ## De API aanroepen Roep `/api/v1/...` aan met **relatieve URL's** (bijv. `fetch('/api/v1/System/capabilities')`). Omdat diff --git a/src/SlpModularCms.Core.Tests/Hosting/Security/SecurityHeaderWriterDocumentHeadersTests.cs b/src/SlpModularCms.Core.Tests/Hosting/Security/SecurityHeaderWriterDocumentHeadersTests.cs new file mode 100644 index 0000000..d2a0cb0 --- /dev/null +++ b/src/SlpModularCms.Core.Tests/Hosting/Security/SecurityHeaderWriterDocumentHeadersTests.cs @@ -0,0 +1,56 @@ +using FluentAssertions; +using Microsoft.AspNetCore.Http; +using SlpModularCms.Core.Hosting.Security; +using Xunit; + +namespace SlpModularCms.Core.Tests.Hosting.Security; + +/// The alwaysSendDocumentHeaders flag used for prerendered-website responses (Q1 = A). +public class SecurityHeaderWriterDocumentHeadersTests +{ + private static readonly SecurityHeaderSet Set = CspPolicyCatalog.Build(CspPolicyCatalog.StrictSite, [], []); + + [Theory] + [InlineData(null)] + [InlineData("image/png")] + [InlineData("application/javascript")] + [InlineData("text/plain; charset=utf-8")] + public void WithTheFlag_DocumentHeadersAreSentOnNonHtmlResponses(string? contentType) + { + var headers = new HeaderDictionary(); + + SecurityHeaderWriter.Apply(headers, contentType, Set, sendHsts: true, alwaysSendDocumentHeaders: true); + + headers.ContainsKey("Content-Security-Policy").Should().BeTrue(); + headers["X-Frame-Options"].ToString().Should().Be("DENY"); + headers["Referrer-Policy"].ToString().Should().Be("strict-origin-when-cross-origin"); + headers["X-Content-Type-Options"].ToString().Should().Be("nosniff"); + headers.ContainsKey("Strict-Transport-Security").Should().BeTrue(); + } + + [Theory] + [InlineData(null)] + [InlineData("image/png")] + public void WithoutTheFlag_TheHtmlOnlyRuleIsUnchanged(string? contentType) + { + var headers = new HeaderDictionary(); + + SecurityHeaderWriter.Apply(headers, contentType, Set, sendHsts: true); + + headers.ContainsKey("Content-Security-Policy").Should().BeFalse(); + headers.ContainsKey("X-Frame-Options").Should().BeFalse(); + headers.ContainsKey("Referrer-Policy").Should().BeFalse(); + headers["X-Content-Type-Options"].ToString().Should().Be("nosniff"); + } + + [Fact] + public void WithTheFlag_AnExistingHeaderIsNotOverwritten() + { + var headers = new HeaderDictionary { ["X-Frame-Options"] = "SAMEORIGIN" }; + + SecurityHeaderWriter.Apply(headers, null, Set, sendHsts: false, alwaysSendDocumentHeaders: true); + + headers["X-Frame-Options"].ToString().Should().Be("SAMEORIGIN"); + headers.ContainsKey("Strict-Transport-Security").Should().BeFalse(); + } +} diff --git a/src/SlpModularCms.Core.Tests/Hosting/Security/StrictSitePolicyTests.cs b/src/SlpModularCms.Core.Tests/Hosting/Security/StrictSitePolicyTests.cs new file mode 100644 index 0000000..853b659 --- /dev/null +++ b/src/SlpModularCms.Core.Tests/Hosting/Security/StrictSitePolicyTests.cs @@ -0,0 +1,138 @@ +using FluentAssertions; +using FsCheck; +using FsCheck.Fluent; +using Microsoft.Extensions.Configuration; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Options; +using SlpModularCms.Core.Hosting.Security; +using Xunit; + +namespace SlpModularCms.Core.Tests.Hosting.Security; + +/// Guards the StrictSite policy: byte-for-byte the CSP the prerendered site sends today. +public class StrictSitePolicyTests +{ + private const string Umami = "https://analytics.slpsoftware.nl"; + private const string Sentry = "https://o4511795618185216.ingest.de.sentry.io"; + + /// The exact nginx value of the website (security headers, test and production). + private const string ExpectedSiteCsp = + "default-src 'self'; script-src 'self' https://analytics.slpsoftware.nl; " + + "style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; " + + "connect-src 'self' https://analytics.slpsoftware.nl https://o4511795618185216.ingest.de.sentry.io; " + + "object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'"; + + [Fact] + public void StrictSite_WithTheSiteOrigins_MatchesTheNginxHeaderByteForByte() + { + var set = CspPolicyCatalog.Build(CspPolicyCatalog.StrictSite, [], [], [Umami], [Umami, Sentry]); + + set.ContentSecurityPolicy.Should().Be(ExpectedSiteCsp); + set.FrameOptions.Should().Be("DENY"); + set.ReferrerPolicy.Should().Be("strict-origin-when-cross-origin"); + } + + [Fact] + public void StrictSite_WithoutOrigins_AllowsOnlySelf() + { + var set = CspPolicyCatalog.Build(CspPolicyCatalog.StrictSite, [], []); + + set.ContentSecurityPolicy.Should().Contain("script-src 'self';").And.Contain("connect-src 'self';"); + set.ContentSecurityPolicy.Should().NotContain("script-src 'self' 'unsafe-inline'").And.NotContain("'unsafe-eval'"); + } + + [Fact] + public void SiteOrigins_AreUsedByStrictSiteOnly() + { + var strict = CspPolicyCatalog.Build(CspPolicyCatalog.Strict, [], [], [Umami], [Sentry]); + var relaxed = CspPolicyCatalog.Build(CspPolicyCatalog.Relaxed, [], [], [Umami], [Sentry]); + + strict.ContentSecurityPolicy.Should().NotContain(Umami).And.NotContain(Sentry); + relaxed.ContentSecurityPolicy.Should().NotContain(Umami).And.NotContain(Sentry); + } + + [Fact] + public void AdminOrigins_AreNotUsedByStrictSite() + { + var set = CspPolicyCatalog.Build(CspPolicyCatalog.StrictSite, [Umami], [Sentry]); + + set.ContentSecurityPolicy.Should().NotContain(Umami).And.NotContain(Sentry); + } + + [Fact] + public void StrictAndRelaxed_AreUnchangedByTheNewParameters() + { + foreach (var policy in new[] { CspPolicyCatalog.Strict, CspPolicyCatalog.Relaxed }) + { + var before = CspPolicyCatalog.Build(policy, [Umami], [Sentry]); + var after = CspPolicyCatalog.Build(policy, [Umami], [Sentry], [Umami], [Sentry]); + + after.Should().Be(before); + } + } + + [Fact] + public void StrictSite_IsAKnownPolicy_AndUnknownNamesStillFail() + { + CspPolicyCatalog.IsKnownPolicy("StrictSite").Should().BeTrue(); + CspPolicyCatalog.IsKnownPolicy("strictsite").Should().BeTrue(); + CspPolicyCatalog.IsKnownPolicy("StrictSyte").Should().BeFalse(); + } + + [Fact] + public void Configuration_CanSelectStrictSite_AndBindsTheSiteOrigins() + { + var provider = BuildProvider(new Dictionary + { + ["SecurityHeaders:DefaultPolicy"] = "StrictSite", + ["SecurityHeaders:AllowedSiteScriptOrigins:0"] = Umami, + ["SecurityHeaders:AllowedSiteConnectOrigins:0"] = Umami, + ["SecurityHeaders:AllowedSiteConnectOrigins:1"] = Sentry + }); + + provider.GetRequiredService>().Value.DefaultPolicy.Should().Be("StrictSite"); + provider.GetRequiredService().Get("StrictSite").ContentSecurityPolicy + .Should().Be(ExpectedSiteCsp); + } + + [Theory] + [InlineData("AllowedSiteScriptOrigins", "analytics.example.com")] + [InlineData("AllowedSiteConnectOrigins", "https://example.com/path")] + [InlineData("AllowedSiteConnectOrigins", "htp://example.com")] + public void SiteOriginLists_AreValidatedLikeTheExistingOnes(string key, string origin) + { + var provider = BuildProvider(new Dictionary { [$"SecurityHeaders:{key}:0"] = origin }); + + var act = () => provider.GetRequiredService>().Value; + + act.Should().Throw().WithMessage("*origins must be absolute scheme-and-host*"); + } + + /// PBT-02: every configured origin appears in the right directive and nowhere else. + [Fact] + public void Property_ConfiguredSiteOrigins_AppearInTheirDirectiveOnly() + { + var hosts = Gen.Elements("a", "b", "cdn", "stats", "x1").Select(h => $"https://{h}.example.com"); + var lists = Gen.ListOf(hosts).Select(l => l.Distinct().ToArray()); + + Prop.ForAll(lists.ToArbitrary(), lists.ToArbitrary(), (script, connect) => + { + var csp = CspPolicyCatalog.Build(CspPolicyCatalog.StrictSite, [], [], script, connect).ContentSecurityPolicy; + var directives = csp.Split("; ").ToDictionary(d => d.Split(' ')[0], d => d.Split(' ').Skip(1).ToArray()); + + return directives["script-src"].Skip(1).OrderBy(x => x).SequenceEqual(script.OrderBy(x => x)) + && directives["connect-src"].Skip(1).OrderBy(x => x).SequenceEqual(connect.OrderBy(x => x)) + && directives["default-src"].SequenceEqual(["'self'"]); + }) + .Check(Config.QuickThrowOnFailure.WithMaxTest(300)); + } + + private static ServiceProvider BuildProvider(Dictionary values) + { + var configuration = new ConfigurationBuilder().AddInMemoryCollection(values).Build(); + var services = new ServiceCollection(); + services.AddLogging(); + services.AddCmsSecurityHeaders(configuration); + return services.BuildServiceProvider(); + } +} diff --git a/src/SlpModularCms.Core.Tests/Hosting/Website/PrerenderedSiteIntegrationTests.cs b/src/SlpModularCms.Core.Tests/Hosting/Website/PrerenderedSiteIntegrationTests.cs new file mode 100644 index 0000000..d48026d --- /dev/null +++ b/src/SlpModularCms.Core.Tests/Hosting/Website/PrerenderedSiteIntegrationTests.cs @@ -0,0 +1,464 @@ +using System.Diagnostics; +using System.Net; +using System.Net.Http.Headers; +using FluentAssertions; +using Microsoft.AspNetCore.Builder; +using Microsoft.AspNetCore.Hosting; +using Microsoft.AspNetCore.Http; +using Microsoft.AspNetCore.TestHost; +using Microsoft.Extensions.Configuration; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Hosting; +using Microsoft.Extensions.Logging; +using SlpModularCms.Core.Hosting; +using SlpModularCms.Core.Hosting.Security; +using SlpModularCms.Core.Hosting.Website; +using Xunit; +using Xunit.Abstractions; + +namespace SlpModularCms.Core.Tests.Hosting.Website; + +/// +/// End-to-end tests of the prerendered website on an in-memory server (no database needed): +/// the real security-header, static-content and website extensions over a temporary +/// wwwroot/web, with a stand-in API route for the reserved prefix. +/// +public sealed class PrerenderedSiteIntegrationTests : IDisposable +{ + private const string Umami = "https://analytics.slpsoftware.nl"; + private const string Sentry = "https://o4511795618185216.ingest.de.sentry.io"; + + private readonly string _root = Path.Combine(Path.GetTempPath(), "slp-site-" + Guid.NewGuid().ToString("N")); + private readonly ITestOutputHelper _output; + private readonly List _apps = []; + + public PrerenderedSiteIntegrationTests(ITestOutputHelper output) + { + _output = output; + Write("index.html", "Home"); + Write("over-mij.html", "Over mij"); + Write("404.html", "Niet gevonden"); + Write("assets/app.abc123.js", "console.log('x');" + new string(' ', 2000)); + Write("assets/logo.png", "PNG"); + Write("blog/index.html", "Blog"); + Write(".well-known/security.txt", "Contact: mailto:a@example.com"); + Write(".env", "SECRET=1"); + } + + public void Dispose() + { + foreach (var app in _apps) + { + app.DisposeAsync().AsTask().GetAwaiter().GetResult(); + } + + if (Directory.Exists(_root)) + { + Directory.Delete(_root, recursive: true); + } + } + + private void Write(string relative, string content) + { + var path = Path.Combine(_root, "wwwroot", "web", relative); + Directory.CreateDirectory(Path.GetDirectoryName(path)!); + File.WriteAllText(path, content); + } + + private async Task StartAsync(bool noIndex = false, bool prerendered = true, Dictionary? extra = null) + { + Directory.CreateDirectory(Path.Combine(_root, "wwwroot")); + + var builder = WebApplication.CreateBuilder(new WebApplicationOptions + { + EnvironmentName = Environments.Production, + ContentRootPath = _root, + WebRootPath = Path.Combine(_root, "wwwroot") + }); + + builder.WebHost.UseTestServer(); + builder.Logging.ClearProviders(); + + var settings = new Dictionary + { + ["SecurityHeaders:DefaultPolicy"] = "StrictSite", + ["SecurityHeaders:AllowedSiteScriptOrigins:0"] = Umami, + ["SecurityHeaders:AllowedSiteConnectOrigins:0"] = Umami, + ["SecurityHeaders:AllowedSiteConnectOrigins:1"] = Sentry, + ["Website:NoIndex"] = noIndex ? "true" : "false" + }; + + foreach (var (key, value) in extra ?? []) + { + settings[key] = value; + } + + builder.Configuration.AddInMemoryCollection(settings); + builder.Services.AddCmsSecurityHeaders(builder.Configuration); + + if (prerendered) + { + builder.Services.AddCmsWebsite(builder.Configuration); + } + + var app = builder.Build(); + var mode = prerendered ? WebsiteMode.PrerenderedPages : WebsiteMode.SpaFallback; + + app.UseCmsSecurityHeaders(); + app.UseCmsStaticContent(mode); + + if (prerendered) + { + app.UseCmsPrerenderedSite(); + } + + app.MapGet("/api/v1/ping", () => Results.Text("pong")); + app.MapPost("/sentry-stand-in", () => Results.Ok("tunnel")); + app.MapCmsSpaFallbacks(mode); + + if (prerendered) + { + app.MapCmsWebsiteNotFound(); + } + + await app.StartAsync(); + _apps.Add(app); + + var client = app.GetTestClient(); + return client; + } + + private static string[] Header(HttpResponseMessage response, string name) => + response.Headers.TryGetValues(name, out var values) ? values.ToArray() + : response.Content.Headers.TryGetValues(name, out var cvalues) ? cvalues.ToArray() + : []; + + // The full header set Q1 = A requires on every website response. + private static void AssertFullHeaderSet(HttpResponseMessage response, string because) + { + Header(response, "Content-Security-Policy").Should().ContainSingle(because) + .Which.Should().StartWith("default-src 'self'; script-src 'self' " + Umami); + Header(response, "Strict-Transport-Security").Should().Equal(["max-age=31536000; includeSubDomains"], because); + Header(response, "X-Content-Type-Options").Should().Equal(["nosniff"], because); + Header(response, "X-Frame-Options").Should().Equal(["DENY"], because); + Header(response, "Referrer-Policy").Should().Equal(["strict-origin-when-cross-origin"], because); + } + + private static HttpClient NoRedirect(HttpClient client) => client; + + [Fact] + public async Task Root_ServesIndex_NoCache_WithFullHeaders() + { + var client = await StartAsync(); + + var response = await client.GetAsync("/"); + + response.StatusCode.Should().Be(HttpStatusCode.OK); + (await response.Content.ReadAsStringAsync()).Should().Contain("Home"); + response.Content.Headers.ContentType!.ToString().Should().Be("text/html; charset=utf-8"); + Header(response, "Cache-Control").Should().Equal(["no-cache"]); + AssertFullHeaderSet(response, "page"); + } + + [Fact] + public async Task Page_IsServedFromExtensionlessUrl() + { + var client = await StartAsync(); + + var response = await client.GetAsync("/over-mij"); + + response.StatusCode.Should().Be(HttpStatusCode.OK); + (await response.Content.ReadAsStringAsync()).Should().Contain("Over mij"); + } + + [Theory] + [InlineData("/Over-Mij?x=1", "/over-mij?x=1")] + [InlineData("/over-mij.html", "/over-mij")] + [InlineData("/over-mij/", "/over-mij")] + [InlineData("/index", "/")] + [InlineData("/index.html", "/")] + [InlineData("/onbekend/", "/onbekend")] + public async Task NonCanonicalUrl_Gets_One301_WithRelativeLocation_AndFullHeaders(string path, string location) + { + var client = await StartAsync(); + + var response = await client.GetAsync(path); + + response.StatusCode.Should().Be(HttpStatusCode.MovedPermanently); + response.Headers.Location!.OriginalString.Should().Be(location); + AssertFullHeaderSet(response, "301"); + } + + [Fact] + public async Task Asset_IsImmutable_AndCarriesTheFullHeaderSet() + { + var client = await StartAsync(); + + var response = await client.GetAsync("/assets/logo.png"); + + response.StatusCode.Should().Be(HttpStatusCode.OK); + Header(response, "Cache-Control").Should().Equal(["public, max-age=31536000, immutable"]); + AssertFullHeaderSet(response, "asset"); + } + + [Fact] + public async Task UnknownPath_Gets404Page_WithStatus404_AndFullHeaders() + { + var client = await StartAsync(); + + var response = await client.GetAsync("/onbekend"); + + response.StatusCode.Should().Be(HttpStatusCode.NotFound); + (await response.Content.ReadAsStringAsync()).Should().Contain("Niet gevonden"); + response.Content.Headers.ContentType!.ToString().Should().Be("text/html; charset=utf-8"); + AssertFullHeaderSet(response, "404"); + } + + [Theory] + [InlineData("/404")] + [InlineData("/404.html")] + [InlineData("/assets/missing.js")] + [InlineData("/assets")] + public async Task ForbiddenOrMissing_Is404WithThe404Page(string path) + { + var client = await StartAsync(); + + var response = await client.GetAsync(path); + + response.StatusCode.Should().Be(HttpStatusCode.NotFound); + (await response.Content.ReadAsStringAsync()).Should().Contain("Niet gevonden"); + } + + [Fact] + public async Task Missing404Html_GivesAPlain404() + { + File.Delete(Path.Combine(_root, "wwwroot", "web", "404.html")); + var client = await StartAsync(); + + var response = await client.GetAsync("/onbekend"); + + response.StatusCode.Should().Be(HttpStatusCode.NotFound); + (await response.Content.ReadAsStringAsync()).Should().BeEmpty(); + } + + [Theory] + [InlineData("/.env")] + [InlineData("/.git/config")] + [InlineData("/assets/.hidden")] + public async Task Dotfiles_Are404_AndNeverServed(string path) + { + var client = await StartAsync(); + + var response = await client.GetAsync(path); + + response.StatusCode.Should().Be(HttpStatusCode.NotFound); + (await response.Content.ReadAsStringAsync()).Should().NotContain("SECRET"); + } + + [Fact] + public async Task WellKnown_IsServed() + { + var client = await StartAsync(); + + var response = await client.GetAsync("/.well-known/security.txt"); + + response.StatusCode.Should().Be(HttpStatusCode.OK); + (await response.Content.ReadAsStringAsync()).Should().Contain("Contact:"); + } + + [Theory] + [InlineData("/../secret")] + [InlineData("/%2e%2e/secret")] + [InlineData("/assets/..%2f..%2fsecret")] + public async Task Traversal_Is404(string path) + { + var client = await StartAsync(); + + var response = await client.GetAsync(path); + + response.StatusCode.Should().Be(HttpStatusCode.NotFound); + } + + [Fact] + public async Task ReservedApiPath_IsHandledByTheApi_AndUnknownApiPathStaysA404WithoutTheWebsitePage() + { + var client = await StartAsync(); + + var known = await client.GetAsync("/api/v1/ping"); + var unknown = await client.GetAsync("/api/v1/does-not-exist"); + + known.StatusCode.Should().Be(HttpStatusCode.OK); + (await known.Content.ReadAsStringAsync()).Should().Be("pong"); + unknown.StatusCode.Should().Be(HttpStatusCode.NotFound); + (await unknown.Content.ReadAsStringAsync()).Should().BeEmpty(); + } + + [Fact] + public async Task NonReservedPostIsLeftToEndpoints() + { + var client = await StartAsync(); + + var tunnel = await client.PostAsync("/sentry-stand-in", new StringContent("x")); + var other = await client.PostAsync("/over-mij", new StringContent("x")); + + tunnel.StatusCode.Should().Be(HttpStatusCode.OK); + other.StatusCode.Should().Be(HttpStatusCode.MethodNotAllowed); + other.Content.Headers.Allow.Should().BeEquivalentTo(["GET", "HEAD"]); + } + + [Fact] + public async Task Head_BehavesLikeGetWithoutBody() + { + var client = await StartAsync(); + + var response = await client.SendAsync(new HttpRequestMessage(HttpMethod.Head, "/over-mij")); + + response.StatusCode.Should().Be(HttpStatusCode.OK); + (await response.Content.ReadAsStringAsync()).Should().BeEmpty(); + Header(response, "Content-Length").Should().NotBeEmpty(); + } + + [Fact] + public async Task NoIndex_AddsRobotsHeaderEverywhere_AndServesDisallowAll() + { + var client = await StartAsync(noIndex: true); + + var page = await client.GetAsync("/over-mij"); + var asset = await client.GetAsync("/assets/logo.png"); + var redirect = await client.GetAsync("/Over-Mij"); + var notFound = await client.GetAsync("/onbekend"); + var robots = await client.GetAsync("/robots.txt"); + + foreach (var response in new[] { page, asset, redirect, notFound, robots }) + { + Header(response, "X-Robots-Tag").Should().Equal(["noindex, nofollow"]); + } + + robots.StatusCode.Should().Be(HttpStatusCode.OK); + (await robots.Content.ReadAsStringAsync()).Should().Be("User-agent: *\nDisallow: /\n"); + AssertFullHeaderSet(robots, "robots.txt"); + } + + [Fact] + public async Task WithoutNoIndex_NoRobotsHeader_AndMissingRobotsTxtIs404() + { + var client = await StartAsync(); + + var page = await client.GetAsync("/over-mij"); + var robots = await client.GetAsync("/robots.txt"); + + Header(page, "X-Robots-Tag").Should().BeEmpty(); + robots.StatusCode.Should().Be(HttpStatusCode.NotFound); + } + + [Fact] + public async Task Gzip_IsUsedForTextTypes_AndBrotliIsNot() + { + var client = await StartAsync(); + + var request = new HttpRequestMessage(HttpMethod.Get, "/assets/app.abc123.js"); + request.Headers.AcceptEncoding.Add(new StringWithQualityHeaderValue("br")); + request.Headers.AcceptEncoding.Add(new StringWithQualityHeaderValue("gzip")); + var js = await client.SendAsync(request); + + var imageRequest = new HttpRequestMessage(HttpMethod.Get, "/assets/logo.png"); + imageRequest.Headers.AcceptEncoding.Add(new StringWithQualityHeaderValue("gzip")); + var png = await client.SendAsync(imageRequest); + + Header(js, "Content-Encoding").Should().Equal(["gzip"]); + Header(js, "Vary").Should().Contain("Accept-Encoding"); + Header(png, "Content-Encoding").Should().BeEmpty(); + } + + [Fact] + public async Task ApiResponses_AreNotCompressed() + { + var client = await StartAsync(); + + var request = new HttpRequestMessage(HttpMethod.Get, "/api/v1/ping"); + request.Headers.AcceptEncoding.Add(new StringWithQualityHeaderValue("gzip")); + var response = await client.SendAsync(request); + + Header(response, "Content-Encoding").Should().BeEmpty(); + } + + [Fact] + public async Task ApiResponses_KeepTheHtmlOnlyHeaderRule() + { + var client = await StartAsync(); + + var response = await client.GetAsync("/api/v1/ping"); + + // text/plain from the stand-in route: nosniff and HSTS yes, document headers no. + Header(response, "X-Content-Type-Options").Should().Equal(["nosniff"]); + Header(response, "Content-Security-Policy").Should().BeEmpty(); + } + + [Fact] + public async Task MissingWebsiteDirectory_KeepsTheHostAlive_AndAnswers404() + { + Directory.Delete(Path.Combine(_root, "wwwroot", "web"), recursive: true); + var client = await StartAsync(); + + var page = await client.GetAsync("/over-mij"); + var api = await client.GetAsync("/api/v1/ping"); + + page.StatusCode.Should().Be(HttpStatusCode.NotFound); + api.StatusCode.Should().Be(HttpStatusCode.OK); + } + + [Fact] + public async Task WebsiteDeliveredAfterStartup_IsServedWithoutRestart() + { + var client = await StartAsync(); + (await client.GetAsync("/nieuw")).StatusCode.Should().Be(HttpStatusCode.NotFound); + + Write("nieuw.html", "Nieuw"); + + (await client.GetAsync("/nieuw")).StatusCode.Should().Be(HttpStatusCode.OK); + } + + [Fact] + public async Task PlainHttp_NeverRedirectsToHttps_AndLocationsAreRelative() + { + var client = await StartAsync(); + + var response = await client.GetAsync("/Over-Mij"); + + response.Headers.Location!.IsAbsoluteUri.Should().BeFalse(); + } + + [Fact] + public async Task SpaFallbackMode_StaysUntouched_UnknownPathsAreNotTheWebsite404() + { + var client = await StartAsync(prerendered: false); + + var response = await client.GetAsync("/Over-Mij"); + + // Old behaviour: no canonical redirect, SPA-style handling (index.html fallback). + response.StatusCode.Should().Be(HttpStatusCode.OK); + (await response.Content.ReadAsStringAsync()).Should().Contain("Home"); + Header(response, "Content-Security-Policy").Should().NotBeEmpty(); + } + + [Fact] + public async Task LocalTimingCheck_PageServing_IsFast() + { + var client = await StartAsync(); + await client.GetAsync("/over-mij"); + + const int iterations = 500; + var watch = Stopwatch.StartNew(); + for (var i = 0; i < iterations; i++) + { + (await client.GetAsync("/over-mij")).EnsureSuccessStatusCode(); + } + + watch.Stop(); + var perRequest = watch.Elapsed.TotalMilliseconds / iterations; + + // Recorded in the hand-back note (NFR-PF-02); the bound only catches pathological regressions. + _output.WriteLine($"TIMING: {iterations} GET /over-mij via in-memory server = {perRequest:F3} ms/request"); + perRequest.Should().BeLessThan(20); + } +} diff --git a/src/SlpModularCms.Core.Tests/Hosting/Website/WebsitePathResolverPropertyTests.cs b/src/SlpModularCms.Core.Tests/Hosting/Website/WebsitePathResolverPropertyTests.cs new file mode 100644 index 0000000..d181b97 --- /dev/null +++ b/src/SlpModularCms.Core.Tests/Hosting/Website/WebsitePathResolverPropertyTests.cs @@ -0,0 +1,145 @@ +using FsCheck; +using FsCheck.Fluent; +using SlpModularCms.Core.Hosting.Website; +using Xunit; +using Xunit.Abstractions; + +namespace SlpModularCms.Core.Tests.Hosting.Website; + +/// +/// Property-based tests for the pure resolver (PBT-03 invariants, idempotence). +/// +/// +/// A failing run prints FsCheck's replay seed in the failure message (PBT-08); once a shrunk +/// counterexample is understood it is added to as a plain +/// example test so the regression stays pinned. +/// +public class WebsitePathResolverPropertyTests(ITestOutputHelper output) +{ + private static readonly string[] KnownFiles = + [ + "index.html", "over-mij.html", "contact.html", "404.html", "robots.txt", + "assets/app.abc123.js", "blog/index.html", ".well-known/security.txt" + ]; + + private static bool Exists(string candidate) => KnownFiles.Contains(candidate); + + // PBT-07 generators: path-ish strings that stress slashes, dots, case, encoding and control characters. + private static readonly string[] Fragments = + [ + "/", "/", "//", "\\", ".", "..", "...", ".git", ".well-known", "%2e", "%2E", "%2f", "%5c", "%", + "over-mij", "Over-Mij", "contact", "index", "Index", ".html", ".HTML", "404", "assets", "app.abc123.js", + "blog", "admin", "api", "v1", "health", "a", "é", "ß", "İ", "\0", "\n", " ", "?", "#", "~", "x" + ]; + + private static Arbitrary PathArb() + { + var gen = Gen.Elements(Fragments) + .ArrayOf() + .Select(parts => string.Concat(parts)) + .Select(tail => "/" + tail); + + // Also exercise inputs that do not start with a slash and the empty string. + return Gen.OneOf(gen, Gen.Elements("", "x", "..", "\\x").Select(s => s)) + .ToArbitrary(); + } + + private static Arbitrary QueryArb() => + Gen.Elements(null, "", "?", "?a=1", "?a=1&b=%2e%2e", "a=1", "?x\r\ny") + .ToArbitrary(); + + private void Check(Func property) + { + var config = Config.QuickThrowOnFailure.WithMaxTest(2000); + + Prop.ForAll(PathArb(), QueryArb(), (path, query) => property(path, query)) + .Check(config); + + output.WriteLine("Property held for 2000 generated inputs."); + } + + [Fact] + public void Resolve_NeverThrows() => + Check((path, query) => + { + WebsitePathResolver.Resolve(path, query, Exists); + return true; + }); + + [Fact] + public void ServeFile_IsAlwaysASafeExistingRelativePath() => + Check((path, query) => + { + if (WebsitePathResolver.Resolve(path, query, Exists) is not WebsiteResolution.ServeFile serve) + { + return true; + } + + var p = serve.RelativePath; + var segments = p.Split('/'); + + return Exists(p) + && p.Length > 0 + && !p.StartsWith('/') + && !p.Contains('\\') + && !p.Contains('\0') + && segments.All(s => s.Length > 0 && s != "." && s != "..") + && segments.Skip(1).All(s => !s.StartsWith('.')) + && (!segments[0].StartsWith('.') || segments[0] == ".well-known"); + }); + + [Fact] + public void Redirect_LocationIsRelativeAndNeverAnOpenRedirect() => + Check((path, query) => + { + if (WebsitePathResolver.Resolve(path, query, Exists) is not WebsiteResolution.Redirect redirect) + { + return true; + } + + var location = redirect.Location; + var pathPart = location.Split('?')[0]; + + return location.StartsWith('/') + && !location.StartsWith("//", StringComparison.Ordinal) + && !location.StartsWith("/\\", StringComparison.Ordinal) + && !location.Any(c => c < 0x20 || c == 0x7f || c == '\\') + && (pathPart == "/" || !pathPart.EndsWith('/')); + }); + + [Fact] + public void Redirect_TargetNeverRedirectsAgain() => + Check((path, query) => + { + if (WebsitePathResolver.Resolve(path, query, Exists) is not WebsiteResolution.Redirect first) + { + return true; + } + + var split = first.Location.IndexOf('?'); + var targetPath = split < 0 ? first.Location : first.Location[..split]; + var targetQuery = split < 0 ? null : first.Location[split..]; + + return WebsitePathResolver.Resolve(targetPath, targetQuery, Exists) is not WebsiteResolution.Redirect; + }); + + [Fact] + public void ReservedPaths_AreNeverResolved() => + Check((path, query) => + !WebsitePathResolver.IsReservedPath(path) + || WebsitePathResolver.Resolve(path, query, Exists) is WebsiteResolution.NotFound); + + [Fact] + public void Resolve_DoesAtMostTwoFileChecks() => + Check((path, query) => + { + var calls = 0; + WebsitePathResolver.Resolve(path, query, c => + { + calls++; + return Exists(c); + }); + + return calls <= 2; + }); +} diff --git a/src/SlpModularCms.Core.Tests/Hosting/Website/WebsitePathResolverTests.cs b/src/SlpModularCms.Core.Tests/Hosting/Website/WebsitePathResolverTests.cs new file mode 100644 index 0000000..660fb3b --- /dev/null +++ b/src/SlpModularCms.Core.Tests/Hosting/Website/WebsitePathResolverTests.cs @@ -0,0 +1,224 @@ +using FluentAssertions; +using SlpModularCms.Core.Hosting.Website; +using Xunit; + +namespace SlpModularCms.Core.Tests.Hosting.Website; + +/// Example-based tests for the nginx-parity rules R1-R14 of the pure path resolver. +public class WebsitePathResolverTests +{ + private static readonly string[] Files = + [ + "index.html", "over-mij.html", "404.html", "robots.txt", + "assets/app.abc123.js", "blog/index.html", ".well-known/security.txt", ".env" + ]; + + private static bool Exists(string candidate) => Files.Contains(candidate); + + private static WebsiteResolution Resolve(string? path, string? query = null) => + WebsitePathResolver.Resolve(path, query, Exists); + + private static WebsiteResolution.ServeFile Serve(string file) => new(file); + + private static WebsiteResolution.Redirect Redirect(string location) => new(location); + + // R5 + [Fact] + public void Root_ServesIndex() => Resolve("/").Should().Be(Serve("index.html")); + + [Fact] + public void Root_WithoutIndexFile_IsNotFound() => + WebsitePathResolver.Resolve("/", null, _ => false).Should().BeOfType(); + + // R9 + [Fact] + public void Page_ServesHtmlFile() => Resolve("/over-mij").Should().Be(Serve("over-mij.html")); + + [Fact] + public void Directory_ServesItsIndexPage() => Resolve("/blog").Should().Be(Serve("blog/index.html")); + + // R10 + [Theory] + [InlineData("/Over-Mij")] + [InlineData("/OVER-MIJ")] + [InlineData("/over-mij.html")] + [InlineData("/Over-Mij.HTML")] + [InlineData("/over-mij/")] + [InlineData("/over-mij///")] + public void NonCanonicalPage_RedirectsOnceToLowercaseNoHtml(string path) => + Resolve(path).Should().Be(Redirect("/over-mij")); + + [Fact] + public void Redirect_PreservesQueryString() => + Resolve("/Over-Mij", "?x=1&y=2").Should().Be(Redirect("/over-mij?x=1&y=2")); + + // R6 + [Theory] + [InlineData("/index")] + [InlineData("/index.html")] + [InlineData("/Index")] + [InlineData("/index/")] + public void IndexVariants_RedirectToRoot(string path) => Resolve(path).Should().Be(Redirect("/")); + + // R7 + [Theory] + [InlineData("/404")] + [InlineData("/404.html")] + [InlineData("/404/")] + public void NotFoundPage_IsNeverServedDirectly(string path) => + Resolve(path).Should().BeOfType(); + + // R8 + [Fact] + public void Asset_IsServedAsIs() => + Resolve("/assets/app.abc123.js").Should().Be(Serve("assets/app.abc123.js")); + + [Fact] + public void Asset_IsNeverLowerCasedOrRedirected() => + Resolve("/assets/APP.abc123.js").Should().BeOfType(); + + [Fact] + public void MissingFile_IsNotFound_AndNeverFallsBackToAPage() => + Resolve("/assets/missing.js").Should().BeOfType(); + + [Fact] + public void RootFile_IsServed() => Resolve("/robots.txt").Should().Be(Serve("robots.txt")); + + // R11 + [Theory] + [InlineData("/onbekend/", "/onbekend")] + [InlineData("/a/b/c//", "/a/b/c")] + [InlineData("/assets/", "/assets")] + public void TrailingSlash_RedirectsToStrippedPath_EvenWhenTargetDoesNotExist(string path, string target) => + Resolve(path).Should().Be(Redirect(target)); + + [Fact] + public void TrailingSlash_KeepsQueryString() => + Resolve("/onbekend/", "?a=1").Should().Be(Redirect("/onbekend?a=1")); + + [Fact] + public void RedirectTarget_NeverEndsInSlashExceptRoot() + { + foreach (var path in new[] { "/x/", "/over-mij/", "/index/", "/a//" }) + { + if (Resolve(path) is WebsiteResolution.Redirect r) + { + (r.Location == "/" || !r.Location.TrimEnd('?').EndsWith('/')).Should().BeTrue(path); + } + } + } + + // R12 + [Theory] + [InlineData("//evil.example/")] + [InlineData("//evil.example")] + [InlineData("/\\evil.example")] + [InlineData("/a\\b")] + [InlineData("/a//b")] + public void OpenRedirectShapes_AreNotFound(string path) => + Resolve(path).Should().BeOfType(); + + // R2 + [Theory] + [InlineData(null)] + [InlineData("")] + [InlineData("over-mij")] + [InlineData("/a\0b")] + [InlineData("/a\nb")] + [InlineData("/../etc/passwd")] + [InlineData("/assets/../../secret")] + [InlineData("/%2e%2e/secret")] + [InlineData("/%2E%2E%2Fsecret")] + [InlineData("/a%5cb")] + public void InvalidOrTraversalInput_IsNotFound(string? path) => + Resolve(path).Should().BeOfType(); + + [Fact] + public void OverlongPath_IsNotFound() => + Resolve("/" + new string('a', 3000)).Should().BeOfType(); + + [Fact] + public void QueryWithControlCharacters_IsNotFound() => + Resolve("/Over-Mij", "?a=\r\nSet-Cookie: x=1").Should().BeOfType(); + + // R3 + [Theory] + [InlineData("/.env")] + [InlineData("/.git/config")] + [InlineData("/assets/.hidden")] + [InlineData("/.well-known/.hidden")] + [InlineData("/./over-mij")] + public void DotSegments_AreNotFound(string path) => + Resolve(path).Should().BeOfType(); + + [Fact] + public void WellKnown_IsServed() => + Resolve("/.well-known/security.txt").Should().Be(Serve(".well-known/security.txt")); + + // R1 + [Theory] + [InlineData("/admin", true)] + [InlineData("/Admin/dashboard", true)] + [InlineData("/api/v1", true)] + [InlineData("/API/V1/offerings", true)] + [InlineData("/health", true)] + [InlineData("/administrator", false)] + [InlineData("/api", false)] + [InlineData("/api/v2/x", false)] + [InlineData("/over-mij", false)] + [InlineData("/", false)] + [InlineData(null, false)] + public void IsReservedPath_MatchesWholeSegmentsOnly(string? path, bool expected) => + WebsitePathResolver.IsReservedPath(path).Should().Be(expected); + + [Theory] + [InlineData("/admin")] + [InlineData("/api/v1/x")] + [InlineData("/health")] + public void ReservedPaths_AreNeverResolved(string path) => + Resolve(path).Should().BeOfType(); + + // R13 + [Fact] + public void DirectoryWithoutIndexPage_IsNotFound() => + Resolve("/assets").Should().BeOfType(); + + // R14 / unknown + [Fact] + public void UnknownPage_IsNotFound() => Resolve("/onbekend").Should().BeOfType(); + + // NFR-PF-01 + [Theory] + [InlineData("/")] + [InlineData("/over-mij")] + [InlineData("/Over-Mij/")] + [InlineData("/assets/app.abc123.js")] + [InlineData("/onbekend")] + [InlineData("/blog")] + [InlineData("/onbekend/")] + public void Resolve_DoesAtMostTwoFileChecks(string path) + { + var calls = 0; + + WebsitePathResolver.Resolve(path, null, candidate => + { + calls++; + return Exists(candidate); + }); + + calls.Should().BeLessThanOrEqualTo(2); + } + + [Fact] + public void PredicateFailure_IsNotFound_NeverAnException() => + WebsitePathResolver.Resolve("/over-mij", null, _ => throw new IOException("disk")) + .Should().BeOfType(); + + [Fact] + public void ServedPath_AfterRedirect_IsServedWithoutSecondRedirect() + { + var first = (WebsiteResolution.Redirect)Resolve("/Over-Mij/"); + + Resolve(first.Location).Should().Be(Serve("over-mij.html")); + } +} diff --git a/src/SlpModularCms.Core.Tests/SlpModularCms.Core.Tests.csproj b/src/SlpModularCms.Core.Tests/SlpModularCms.Core.Tests.csproj index 2d25a44..30eca0f 100644 --- a/src/SlpModularCms.Core.Tests/SlpModularCms.Core.Tests.csproj +++ b/src/SlpModularCms.Core.Tests/SlpModularCms.Core.Tests.csproj @@ -15,6 +15,8 @@ + + diff --git a/src/SlpModularCms.Core/Hosting/CmsHost.cs b/src/SlpModularCms.Core/Hosting/CmsHost.cs index 2b5f946..9f565ce 100644 --- a/src/SlpModularCms.Core/Hosting/CmsHost.cs +++ b/src/SlpModularCms.Core/Hosting/CmsHost.cs @@ -6,6 +6,7 @@ using Microsoft.Extensions.Logging; using SlpModularCms.Core.Hosting.Health; using SlpModularCms.Core.Hosting.Observability; using SlpModularCms.Core.Hosting.Security; +using SlpModularCms.Core.Hosting.Website; using Scalar.AspNetCore; namespace SlpModularCms.Core.Hosting; @@ -56,6 +57,11 @@ public static class CmsHost builder.Services.AddCmsSecurityHeaders(builder.Configuration); builder.Services.AddCmsObservability(builder.Configuration); + if (options.WebsiteMode == WebsiteMode.PrerenderedPages) + { + builder.Services.AddCmsWebsite(builder.Configuration); + } + // Registered BEFORE module services: modules must not configure Data Protection themselves, // because a later registration would override this persistent key store (see // DataProtectionExtensions). @@ -117,7 +123,15 @@ public static class CmsHost // wwwroot/admin/index.html + assets -> CMS admin build (see frontend/, copied in on publish) // Registered before the module middleware below: static files short-circuit the pipeline, so // anything that must observe them has to come first. - app.UseCmsStaticContent(); + app.UseCmsStaticContent(options.WebsiteMode); + + // WebsiteMode.PrerenderedPages: the website replaces the SPA-style website mount, at the same + // position and for the same reason (it answers before the module middleware and the API). + // It never handles /admin, /api/v1 or /health. + if (options.WebsiteMode == WebsiteMode.PrerenderedPages) + { + app.UseCmsPrerenderedSite(); + } app.UseCors(); @@ -144,6 +158,13 @@ public static class CmsHost // SPA fallbacks so client-side routes (e.g. /admin/dashboard) resolve to the right index.html // instead of 404ing. The "nonfile" constraint keeps genuinely missing assets (e.g. /admin/assets/x.js) as 404s. - app.MapCmsSpaFallbacks(); + app.MapCmsSpaFallbacks(options.WebsiteMode); + + // WebsiteMode.PrerenderedPages: lowest-priority endpoint, so unknown website paths get + // 404.html with status 404 only AFTER every API route and the admin fallback had their turn. + if (options.WebsiteMode == WebsiteMode.PrerenderedPages) + { + app.MapCmsWebsiteNotFound(); + } } } diff --git a/src/SlpModularCms.Core/Hosting/CmsHostOptions.cs b/src/SlpModularCms.Core/Hosting/CmsHostOptions.cs index c9b9fec..5141426 100644 --- a/src/SlpModularCms.Core/Hosting/CmsHostOptions.cs +++ b/src/SlpModularCms.Core/Hosting/CmsHostOptions.cs @@ -1,13 +1,31 @@ namespace SlpModularCms.Core.Hosting; +/// How the public website under wwwroot/web is served. +public enum WebsiteMode +{ + /// + /// Single-page-application behaviour (the default, and what every existing client uses): + /// unknown extensionless paths fall back to index.html. + /// + SpaFallback = 0, + + /// + /// Prerendered multi-page website, served the way nginx serves it: /x is x.html, + /// non-canonical URLs get one 301, unknown paths get 404.html with status 404. + /// + PrerenderedPages = 1 +} + /// -/// Extension point for future per-project differences between CmsHost callers. +/// Extension point for per-project differences between CmsHost callers. /// /// -/// Deliberately empty today — both current Client projects (Api, Api.SlpSoftware) -/// pass identical values. Introduced now so a future real difference is a property added here, -/// not a signature change to /. +/// A property here, not a signature change to / +/// , is how a Client project opts into different behaviour. +/// Defaults reproduce the behaviour every existing Client project already has. /// public sealed class CmsHostOptions { + /// How the public website is served. Defaults to . + public WebsiteMode WebsiteMode { get; init; } = WebsiteMode.SpaFallback; } diff --git a/src/SlpModularCms.Core/Hosting/Security/CspPolicyCatalog.cs b/src/SlpModularCms.Core/Hosting/Security/CspPolicyCatalog.cs index 5d81095..c7c4b9e 100644 --- a/src/SlpModularCms.Core/Hosting/Security/CspPolicyCatalog.cs +++ b/src/SlpModularCms.Core/Hosting/Security/CspPolicyCatalog.cs @@ -9,7 +9,7 @@ public sealed record SecurityHeaderSet( string ReferrerPolicy); /// -/// The two Content-Security-Policy definitions, in code rather than in configuration. +/// The Content-Security-Policy definitions (Strict, Relaxed, StrictSite), in code rather than in configuration. /// /// /// A pure function of (policy name, origin lists) to a header set: no dependencies, no state, @@ -21,9 +21,17 @@ public static class CspPolicyCatalog public const string Strict = "Strict"; public const string Relaxed = "Relaxed"; + /// + /// For a prerendered public website: strict like but with the script and + /// connect origins of the site (analytics, error reporting) taken from the dedicated + /// AllowedSite*Origins lists, so the admin policies never gain them. The directive order + /// matches the site's existing nginx header, so the value is byte-for-byte identical. + /// + public const string StrictSite = "StrictSite"; + private const string ReferrerPolicyValue = "strict-origin-when-cross-origin"; - public static IReadOnlyList KnownPolicies { get; } = [Strict, Relaxed]; + public static IReadOnlyList KnownPolicies { get; } = [Strict, Relaxed, StrictSite]; public static bool IsKnownPolicy(string? policy) => policy is not null && @@ -37,10 +45,31 @@ public static class CspPolicyCatalog public static SecurityHeaderSet Build( string policy, IEnumerable allowedScriptOrigins, - IEnumerable allowedConnectOrigins) + IEnumerable allowedConnectOrigins, + IEnumerable? allowedSiteScriptOrigins = null, + IEnumerable? allowedSiteConnectOrigins = null) { var connect = Join("'self'", allowedConnectOrigins); + if (StrictSite.Equals(policy, StringComparison.OrdinalIgnoreCase)) + { + return new SecurityHeaderSet( + ContentSecurityPolicy: string.Join("; ", + "default-src 'self'", + $"script-src {Join("'self'", allowedSiteScriptOrigins ?? [])}", + // Same documented exception as Strict: inline style attributes only, no script. + "style-src 'self' 'unsafe-inline'", + "img-src 'self' data:", + "font-src 'self'", + $"connect-src {Join("'self'", allowedSiteConnectOrigins ?? [])}", + "object-src 'none'", + "base-uri 'self'", + "form-action 'self'", + "frame-ancestors 'none'"), + FrameOptions: "DENY", + ReferrerPolicy: ReferrerPolicyValue); + } + if (Strict.Equals(policy, StringComparison.OrdinalIgnoreCase)) { return new SecurityHeaderSet( diff --git a/src/SlpModularCms.Core/Hosting/Security/CspPolicyProvider.cs b/src/SlpModularCms.Core/Hosting/Security/CspPolicyProvider.cs index 5c8a11a..48758b4 100644 --- a/src/SlpModularCms.Core/Hosting/Security/CspPolicyProvider.cs +++ b/src/SlpModularCms.Core/Hosting/Security/CspPolicyProvider.cs @@ -15,7 +15,7 @@ public interface ICspPolicyProvider /// /// /// Composing a CSP string per response would be wasteful on a workload that is mostly static -/// files. There are two policies and they are read on every HTML response, which is exactly +/// files. There are three policies and they are read on every HTML response, which is exactly /// what exists for. /// public sealed class CspPolicyProvider : ICspPolicyProvider @@ -30,7 +30,12 @@ public sealed class CspPolicyProvider : ICspPolicyProvider _policies = CspPolicyCatalog.KnownPolicies .ToFrozenDictionary( policy => policy, - policy => CspPolicyCatalog.Build(policy, value.AllowedScriptOrigins, value.AllowedConnectOrigins), + policy => CspPolicyCatalog.Build( + policy, + value.AllowedScriptOrigins, + value.AllowedConnectOrigins, + value.AllowedSiteScriptOrigins, + value.AllowedSiteConnectOrigins), StringComparer.OrdinalIgnoreCase); } diff --git a/src/SlpModularCms.Core/Hosting/Security/SecurityHeaderWriter.cs b/src/SlpModularCms.Core/Hosting/Security/SecurityHeaderWriter.cs index 80a4cb4..5dd2c47 100644 --- a/src/SlpModularCms.Core/Hosting/Security/SecurityHeaderWriter.cs +++ b/src/SlpModularCms.Core/Hosting/Security/SecurityHeaderWriter.cs @@ -36,11 +36,16 @@ public static class SecurityHeaderWriter /// Raw Content-Type; null for bodyless responses. /// The resolved policy's HTML-only header values. /// False in Development only; see . + /// + /// True for responses of a prerendered website (every asset, redirect, 404 and robots.txt gets the + /// full set, as nginx sends it). False keeps the HTML-only rule that API and admin responses use. + /// public static void Apply( IHeaderDictionary headers, string? contentType, SecurityHeaderSet headerSet, - bool sendHsts) + bool sendHsts, + bool alwaysSendDocumentHeaders = false) { ArgumentNullException.ThrowIfNull(headers); ArgumentNullException.ThrowIfNull(headerSet); @@ -60,7 +65,7 @@ public static class SecurityHeaderWriter // The remaining three govern documents and are meaningless on an image or a script // file. A null content type — 304, redirect, empty body — is not HTML, which is what // makes those cases fall out here instead of needing branches of their own. - if (!IsHtml(contentType)) + if (!alwaysSendDocumentHeaders && !IsHtml(contentType)) { return; } diff --git a/src/SlpModularCms.Core/Hosting/Security/SecurityHeadersExtensions.cs b/src/SlpModularCms.Core/Hosting/Security/SecurityHeadersExtensions.cs index 6f7c388..2d3f99a 100644 --- a/src/SlpModularCms.Core/Hosting/Security/SecurityHeadersExtensions.cs +++ b/src/SlpModularCms.Core/Hosting/Security/SecurityHeadersExtensions.cs @@ -23,7 +23,8 @@ public static class SecurityHeadersExtensions options => CspPolicyCatalog.IsKnownPolicy(options.DefaultPolicy), $"SecurityHeaders:DefaultPolicy is not a known policy. Known policies: {string.Join(", ", CspPolicyCatalog.KnownPolicies)}.") .Validate( - options => options.AllowedScriptOrigins.Concat(options.AllowedConnectOrigins).All(IsOrigin), + options => options.AllowedScriptOrigins.Concat(options.AllowedConnectOrigins) + .Concat(options.AllowedSiteScriptOrigins).Concat(options.AllowedSiteConnectOrigins).All(IsOrigin), "SecurityHeaders origins must be absolute scheme-and-host values without a path, e.g. https://analytics.example.com.") // ValidateOnStart, not a constructor check: options resolve lazily, so without this // a typo in PathPolicies is discovered when the first request arrives — by which @@ -71,11 +72,14 @@ public static class SecurityHeadersExtensions // than requiring someone to reconstruct it from the deployed appsettings. logger.LogInformation( "HTTP security headers enabled. Default policy: {DefaultPolicy}. Path policies: {PathPolicies}. " + - "Allowed script origins: {ScriptOrigins}. Allowed connect origins: {ConnectOrigins}.", + "Allowed script origins: {ScriptOrigins}. Allowed connect origins: {ConnectOrigins}. " + + "Allowed site script origins: {SiteScriptOrigins}. Allowed site connect origins: {SiteConnectOrigins}.", options.DefaultPolicy, string.Join(", ", options.PathPolicies.Select(rule => $"{rule.PathPrefix} => {rule.Policy}")), Describe(options.AllowedScriptOrigins), - Describe(options.AllowedConnectOrigins)); + Describe(options.AllowedConnectOrigins), + Describe(options.AllowedSiteScriptOrigins), + Describe(options.AllowedSiteConnectOrigins)); return app.UseMiddleware(); } diff --git a/src/SlpModularCms.Core/Hosting/Security/SecurityHeadersMiddleware.cs b/src/SlpModularCms.Core/Hosting/Security/SecurityHeadersMiddleware.cs index f8ced7d..7a45f19 100644 --- a/src/SlpModularCms.Core/Hosting/Security/SecurityHeadersMiddleware.cs +++ b/src/SlpModularCms.Core/Hosting/Security/SecurityHeadersMiddleware.cs @@ -2,6 +2,7 @@ using Microsoft.AspNetCore.Http; using Microsoft.Extensions.Hosting; using Microsoft.Extensions.Logging; using Microsoft.Extensions.Options; +using SlpModularCms.Core.Hosting.Website; namespace SlpModularCms.Core.Hosting.Security; @@ -22,6 +23,7 @@ public sealed class SecurityHeadersMiddleware private readonly ILogger _logger; private readonly bool _enabled; private readonly bool _sendHsts; + private readonly bool _prerenderedWebsite; public SecurityHeadersMiddleware( RequestDelegate next, @@ -29,7 +31,8 @@ public sealed class SecurityHeadersMiddleware ICspPolicyProvider policyProvider, PathPolicyResolver resolver, IHostEnvironment environment, - ILogger logger) + ILogger logger, + WebsiteHostingMarker? websiteHosting = null) { ArgumentNullException.ThrowIfNull(options); ArgumentNullException.ThrowIfNull(environment); @@ -48,6 +51,9 @@ public sealed class SecurityHeadersMiddleware // Resolved once here rather than per response: EnvironmentName cannot change while the // process runs, and this middleware sees every static asset the website serves. _sendHsts = !environment.IsDevelopment(); + + // Only a client hosting a prerendered website registers the marker (AddCmsWebsite). + _prerenderedWebsite = websiteHosting is not null; } public async Task InvokeAsync(HttpContext context) @@ -67,9 +73,14 @@ public sealed class SecurityHeadersMiddleware // The (callback, state) overload with a cached static delegate. The lambda overload // allocates a closure and a delegate on every response, including every static asset of // the public website — the bulk of the traffic in this hosting model. + // On a prerendered website every response outside the reserved prefixes (page, asset, 301, + // 404, robots.txt) gets the full set, because nginx does and the site's own checks assert it. + var documentHeadersEverywhere = _prerenderedWebsite + && !WebsitePathResolver.IsReservedPath(context.Request.Path.Value); + context.Response.OnStarting( WriteHeadersCallback, - new HeaderWriteState(context.Response, headerSet, _sendHsts, _logger)); + new HeaderWriteState(context.Response, headerSet, _sendHsts, documentHeadersEverywhere, _logger)); await _next(context); } @@ -80,7 +91,8 @@ public sealed class SecurityHeadersMiddleware try { - SecurityHeaderWriter.Apply(s.Response.Headers, s.Response.ContentType, s.HeaderSet, s.SendHsts); + SecurityHeaderWriter.Apply( + s.Response.Headers, s.Response.ContentType, s.HeaderSet, s.SendHsts, s.AlwaysSendDocumentHeaders); } catch (Exception ex) { @@ -100,5 +112,6 @@ public sealed class SecurityHeadersMiddleware HttpResponse Response, SecurityHeaderSet HeaderSet, bool SendHsts, + bool AlwaysSendDocumentHeaders, ILogger Logger); } diff --git a/src/SlpModularCms.Core/Hosting/Security/SecurityHeadersOptions.cs b/src/SlpModularCms.Core/Hosting/Security/SecurityHeadersOptions.cs index 8f1091f..ec6ccf9 100644 --- a/src/SlpModularCms.Core/Hosting/Security/SecurityHeadersOptions.cs +++ b/src/SlpModularCms.Core/Hosting/Security/SecurityHeadersOptions.cs @@ -58,6 +58,18 @@ public sealed class SecurityHeadersOptions /// reporting same-origin, so connect-src 'self' already covers it. /// public IList AllowedConnectOrigins { get; set; } = []; + + /// + /// Extra origins added to script-src under the StrictSite policy only (for example + /// the analytics host of a prerendered website). Never used by the admin policies. + /// + public IList AllowedSiteScriptOrigins { get; set; } = []; + + /// + /// Extra origins added to connect-src under the StrictSite policy only (for example + /// analytics and error-reporting hosts called directly by the website). + /// + public IList AllowedSiteConnectOrigins { get; set; } = []; } /// One entry in . diff --git a/src/SlpModularCms.Core/Hosting/StaticContentExtensions.cs b/src/SlpModularCms.Core/Hosting/StaticContentExtensions.cs index e0afb6e..779a7a2 100644 --- a/src/SlpModularCms.Core/Hosting/StaticContentExtensions.cs +++ b/src/SlpModularCms.Core/Hosting/StaticContentExtensions.cs @@ -40,7 +40,14 @@ public static class StaticContentExtensions /// Must be called BEFORE any middleware that needs to observe static responses, because /// static files short-circuit the pipeline. /// - public static WebApplication UseCmsStaticContent(this WebApplication app) + /// The application. + /// + /// In only the admin mount is registered here; the + /// website is served by UseCmsPrerenderedSite instead. + /// + public static WebApplication UseCmsStaticContent( + this WebApplication app, + WebsiteMode websiteMode = WebsiteMode.SpaFallback) { var webRoot = app.Environment.WebRootPath ?? Path.Combine(app.Environment.ContentRootPath, "wwwroot"); @@ -52,7 +59,11 @@ public static class StaticContentExtensions .CreateLogger(typeof(StaticContentExtensions).FullName!); WarnIfMissing(logger, adminRoot, "admin SPA"); - WarnIfMissing(logger, websiteRoot, "public website"); + + if (websiteMode == WebsiteMode.SpaFallback) + { + WarnIfMissing(logger, websiteRoot, "public website"); + } // A request for exactly "/admin" must become "/admin/", or the SPA — built with // base '/admin/' — resolves its relative asset references one level too high and @@ -72,7 +83,11 @@ public static class StaticContentExtensions // The admin mount is registered FIRST. Registered the other way around, a request for // /admin/... would be resolved against the website root. RegisterMount(app, adminRoot, AdminRequestPath); - RegisterMount(app, websiteRoot, requestPath: string.Empty); + + if (websiteMode == WebsiteMode.SpaFallback) + { + RegisterMount(app, websiteRoot, requestPath: string.Empty); + } return app; } @@ -85,7 +100,14 @@ public static class StaticContentExtensions /// looks like a file (has an extension) and does not exist must stay a 404. Serving HTML /// for a missing script would turn a clear "asset is missing" into a confusing parse error. /// - public static WebApplication MapCmsSpaFallbacks(this WebApplication app) + /// The application. + /// + /// In the catch-all website fallback is NOT mapped: an + /// unknown path must be a real 404 (MapCmsWebsiteNotFound), never index.html. + /// + public static WebApplication MapCmsSpaFallbacks( + this WebApplication app, + WebsiteMode websiteMode = WebsiteMode.SpaFallback) { var webRoot = app.Environment.WebRootPath ?? Path.Combine(app.Environment.ContentRootPath, "wwwroot"); @@ -105,6 +127,11 @@ public static class StaticContentExtensions context.Response.StatusCode = StatusCodes.Status404NotFound; }); + if (websiteMode == WebsiteMode.PrerenderedPages) + { + return app; + } + app.MapFallback("{*path:nonfile}", async context => { if (File.Exists(websiteIndex)) diff --git a/src/SlpModularCms.Core/Hosting/Website/PrerenderedSiteExtensions.cs b/src/SlpModularCms.Core/Hosting/Website/PrerenderedSiteExtensions.cs new file mode 100644 index 0000000..092fb71 --- /dev/null +++ b/src/SlpModularCms.Core/Hosting/Website/PrerenderedSiteExtensions.cs @@ -0,0 +1,73 @@ +using Microsoft.AspNetCore.Builder; +using Microsoft.AspNetCore.Hosting; +using Microsoft.AspNetCore.ResponseCompression; +using Microsoft.AspNetCore.Routing; +using Microsoft.Extensions.Configuration; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Logging; + +namespace SlpModularCms.Core.Hosting.Website; + +/// Registration of the prerendered-website serving (only used when ). +public static class PrerenderedSiteExtensions +{ + /// Text types compressed on the website (same list as the site's nginx configuration). + internal static readonly string[] CompressibleMimeTypes = + [ + "text/html", "text/css", "text/plain", "text/xml", "text/javascript", + "application/javascript", "application/json", "application/xml", "image/svg+xml" + ]; + + public static IServiceCollection AddCmsWebsite(this IServiceCollection services, IConfiguration configuration) + { + services.AddOptions() + .Bind(configuration.GetSection(WebsiteOptions.SectionName)) + .ValidateOnStart(); + + // Presence of the marker switches on the full security-header set for website responses. + services.AddSingleton(); + + services.AddSingleton(provider => + { + var environment = provider.GetRequiredService(); + var webRoot = environment.WebRootPath ?? Path.Combine(environment.ContentRootPath, "wwwroot"); + + return new WebsiteFileAccess( + Path.Combine(webRoot, StaticContentExtensions.WebsiteDirectoryName), + provider.GetRequiredService().CreateLogger(PrerenderedSiteMiddleware.LoggerCategory)); + }); + + // gzip only, like nginx today; Brotli is deliberately not registered. + services.AddResponseCompression(options => + { + options.Providers.Add(); + options.MimeTypes = CompressibleMimeTypes; + }); + + return services; + } + + /// + /// Compression (non-reserved paths only) and the website middleware. Replaces the website static + /// mount of SpaFallback mode; place it where UseCmsStaticContent sits. + /// + public static WebApplication UseCmsPrerenderedSite(this WebApplication app) + { + app.UseWhen( + context => !WebsitePathResolver.IsReservedPath(context.Request.Path.Value), + branch => branch.UseResponseCompression()); + + app.UseMiddleware(); + + return app; + } + + /// Maps the final fallback that serves 404.html with status 404. + public static WebApplication MapCmsWebsiteNotFound(this WebApplication app) + { + // An explicit pattern: the default fallback pattern carries the "nonfile" constraint, and a + // missing asset (/assets/x.js) must also get the 404 page, not a bare framework 404. + app.MapFallback("{*path}", WebsiteNotFoundHandler.HandleAsync); + return app; + } +} diff --git a/src/SlpModularCms.Core/Hosting/Website/PrerenderedSiteMiddleware.cs b/src/SlpModularCms.Core/Hosting/Website/PrerenderedSiteMiddleware.cs new file mode 100644 index 0000000..40ce237 --- /dev/null +++ b/src/SlpModularCms.Core/Hosting/Website/PrerenderedSiteMiddleware.cs @@ -0,0 +1,149 @@ +using Microsoft.AspNetCore.Builder; +using Microsoft.AspNetCore.Hosting; +using Microsoft.AspNetCore.Http; +using Microsoft.AspNetCore.StaticFiles; +using Microsoft.Extensions.Logging; +using Microsoft.Extensions.Options; +using Microsoft.Net.Http.Headers; + +namespace SlpModularCms.Core.Hosting.Website; + +/// +/// Thin HTTP adapter around : answers redirects, files and +/// robots.txt for the prerendered website, and passes everything else on (rules R15-R19, R22). +/// +/// +/// Files are streamed by the framework's static-file middleware, rewritten to the resolved path, so +/// ETag, Last-Modified, conditional requests, ranges and HEAD behave like any static file. Unresolved +/// paths continue to the API routes; only when nothing matches does the final fallback +/// () serve the 404 page. +/// +public sealed class PrerenderedSiteMiddleware +{ + public const string LoggerCategory = "SlpModularCms.Website"; + + internal const string NoCache = "no-cache"; + internal const string ImmutableYear = "public, max-age=31536000, immutable"; + internal const string RobotsTagValue = "noindex, nofollow"; + internal const string RobotsTxt = "User-agent: *\nDisallow: /\n"; + + private readonly RequestDelegate _next; + private readonly RequestDelegate _staticFiles; + private readonly WebsiteFileAccess _files; + private readonly bool _noIndex; + private readonly ILogger _logger; + + public PrerenderedSiteMiddleware( + RequestDelegate next, + IWebHostEnvironment environment, + IOptions options, + ILoggerFactory loggerFactory, + WebsiteFileAccess files) + { + _next = next; + _files = files; + _noIndex = options.Value.NoIndex; + _logger = loggerFactory.CreateLogger(LoggerCategory); + + var staticFileOptions = new StaticFileOptions + { + FileProvider = files, + // The resolver decides which files exist and may be served; the framework only sends them. + ServeUnknownFileTypes = true, + DefaultContentType = "application/octet-stream", + OnPrepareResponse = prepare => + { + var path = prepare.Context.Request.Path.Value ?? string.Empty; + if (prepare.Context.Response.ContentType == "text/html") + { + prepare.Context.Response.ContentType = "text/html; charset=utf-8"; + } + + prepare.Context.Response.Headers[HeaderNames.CacheControl] = + path.StartsWith("/assets/", StringComparison.Ordinal) ? ImmutableYear : NoCache; + } + }; + + _staticFiles = new StaticFileMiddleware(next, environment, Options.Create(staticFileOptions), loggerFactory).Invoke; + } + + public async Task InvokeAsync(HttpContext context) + { + var request = context.Request; + + if (WebsitePathResolver.IsReservedPath(request.Path.Value)) + { + await _next(context); + return; + } + + if (_noIndex) + { + context.Response.Headers["X-Robots-Tag"] = RobotsTagValue; + } + + // Other methods (the Sentry tunnel is a POST) are left to the endpoints. + if (!HttpMethods.IsGet(request.Method) && !HttpMethods.IsHead(request.Method)) + { + await _next(context); + return; + } + + if (_noIndex && string.Equals(request.Path.Value, "/robots.txt", StringComparison.OrdinalIgnoreCase)) + { + context.Response.StatusCode = StatusCodes.Status200OK; + context.Response.ContentType = "text/plain; charset=utf-8"; + context.Response.Headers[HeaderNames.CacheControl] = NoCache; + context.Response.ContentLength = RobotsTxt.Length; + + if (!HttpMethods.IsHead(request.Method)) + { + await context.Response.WriteAsync(RobotsTxt); + } + + return; + } + + var resolution = WebsitePathResolver.Resolve(request.Path.Value, request.QueryString.Value, _files.Exists); + + switch (resolution) + { + case WebsiteResolution.Redirect redirect: + _logger.LogInformation("Website redirect 301 {From} -> {To}", Sanitize(request.Path.Value), Sanitize(redirect.Location)); + context.Response.StatusCode = StatusCodes.Status301MovedPermanently; + context.Response.Headers[HeaderNames.Location] = redirect.Location; + break; + + case WebsiteResolution.ServeFile serve: + // Routing already selected the catch-all fallback endpoint for the ORIGINAL path, and the + // static-file middleware steps aside whenever an endpoint is selected. Clearing it lets the + // file be served; the file was just confirmed to exist by the resolver. + context.SetEndpoint(null); + request.Path = "/" + serve.RelativePath; + await _staticFiles(context); + break; + + default: + await _next(context); + break; + } + } + + /// Removes control characters and caps the length so a request path cannot forge log lines. + internal static string Sanitize(string? value) + { + if (string.IsNullOrEmpty(value)) + { + return string.Empty; + } + + var capped = value.Length > 200 ? value[..200] : value; + return string.Create(capped.Length, capped, static (span, source) => + { + for (var i = 0; i < source.Length; i++) + { + span[i] = char.IsControl(source[i]) ? '?' : source[i]; + } + }); + } +} diff --git a/src/SlpModularCms.Core/Hosting/Website/WebsiteFileAccess.cs b/src/SlpModularCms.Core/Hosting/Website/WebsiteFileAccess.cs new file mode 100644 index 0000000..418244e --- /dev/null +++ b/src/SlpModularCms.Core/Hosting/Website/WebsiteFileAccess.cs @@ -0,0 +1,100 @@ +using Microsoft.Extensions.FileProviders; +using Microsoft.Extensions.Logging; +using Microsoft.Extensions.Primitives; + +namespace SlpModularCms.Core.Hosting.Website; + +/// +/// Read-only access to the website files, confined to wwwroot/web. +/// +/// +/// A file provider rather than Path.Combine with request data: +/// refuses anything that resolves outside its root, which is the second line of defence behind +/// . Exclusion filters are switched off on purpose, because the +/// default ones hide every dot-prefixed name and would make /.well-known/ unreachable; dotfiles +/// are refused earlier, by rule R3 of the resolver. +/// +/// The root is looked up on every call instead of once at startup: the website is delivered +/// independently of the host (a CI copy, or a symlink switched to a new release) and may appear or +/// be replaced while the process runs. A missing root, a vanished file or an IO error is "not +/// found", never an exception. +/// +public sealed class WebsiteFileAccess : IFileProvider, IDisposable +{ + private readonly string _root; + private readonly ILogger _logger; + private readonly Lock _gate = new(); + private PhysicalFileProvider? _provider; + private bool _warnedMissing; + + public WebsiteFileAccess(string root, ILogger logger) + { + _root = root; + _logger = logger; + } + + /// True when names an existing file (not a directory). + public bool Exists(string relativePath) + { + try + { + var info = GetFileInfo(relativePath); + return info.Exists && !info.IsDirectory; + } + catch (Exception ex) + { + _logger.LogWarning(ex, "Checking a website file failed; treating it as not found."); + return false; + } + } + + public IFileInfo GetFileInfo(string subpath) + { + var provider = GetProvider(); + return provider is null ? new NotFoundFileInfo(subpath) : provider.GetFileInfo(subpath); + } + + public IDirectoryContents GetDirectoryContents(string subpath) => NotFoundDirectoryContents.Singleton; + + public IChangeToken Watch(string filter) => NullChangeToken.Singleton; + + public void Dispose() + { + lock (_gate) + { + _provider?.Dispose(); + _provider = null; + } + } + + private PhysicalFileProvider? GetProvider() + { + lock (_gate) + { + if (_provider is not null && Directory.Exists(_root)) + { + return _provider; + } + + _provider?.Dispose(); + _provider = null; + + if (!Directory.Exists(_root)) + { + if (!_warnedMissing) + { + _warnedMissing = true; + _logger.LogWarning( + "The website directory {Root} does not exist; every website path answers 404 until it is delivered.", + _root); + } + + return null; + } + + _warnedMissing = false; + _provider = new PhysicalFileProvider(_root, Microsoft.Extensions.FileProviders.Physical.ExclusionFilters.None); + return _provider; + } + } +} diff --git a/src/SlpModularCms.Core/Hosting/Website/WebsiteHostingMarker.cs b/src/SlpModularCms.Core/Hosting/Website/WebsiteHostingMarker.cs new file mode 100644 index 0000000..0e2c745 --- /dev/null +++ b/src/SlpModularCms.Core/Hosting/Website/WebsiteHostingMarker.cs @@ -0,0 +1,10 @@ +namespace SlpModularCms.Core.Hosting.Website; + +/// +/// Registered (as a singleton) by AddCmsWebsite when a client serves a prerendered website. +/// Its presence tells the security-header middleware to send the full header set on every +/// non-reserved response. Absent for every existing client, so their behaviour is unchanged. +/// +public sealed class WebsiteHostingMarker +{ +} diff --git a/src/SlpModularCms.Core/Hosting/Website/WebsiteNotFoundHandler.cs b/src/SlpModularCms.Core/Hosting/Website/WebsiteNotFoundHandler.cs new file mode 100644 index 0000000..dc0f104 --- /dev/null +++ b/src/SlpModularCms.Core/Hosting/Website/WebsiteNotFoundHandler.cs @@ -0,0 +1,67 @@ +using Microsoft.AspNetCore.Http; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Logging; +using Microsoft.Net.Http.Headers; + +namespace SlpModularCms.Core.Hosting.Website; + +/// +/// Final fallback of a prerendered website (rules R20-R22): 404.html with status 404. +/// +/// +/// Mapped as the lowest-priority endpoint, so it only runs when no API route and no admin fallback +/// matched. An unknown reserved path (/api/v1/...) stays an empty 404 and never receives the +/// website page; other methods than GET/HEAD get 405 like a static file server. +/// +public static class WebsiteNotFoundHandler +{ + public static async Task HandleAsync(HttpContext context) + { + var request = context.Request; + var logger = context.RequestServices.GetRequiredService() + .CreateLogger(PrerenderedSiteMiddleware.LoggerCategory); + + if (WebsitePathResolver.IsReservedPath(request.Path.Value)) + { + context.Response.StatusCode = StatusCodes.Status404NotFound; + return; + } + + if (!HttpMethods.IsGet(request.Method) && !HttpMethods.IsHead(request.Method)) + { + context.Response.StatusCode = StatusCodes.Status405MethodNotAllowed; + context.Response.Headers[HeaderNames.Allow] = "GET, HEAD"; + return; + } + + logger.LogInformation("Website 404 {Path}", PrerenderedSiteMiddleware.Sanitize(request.Path.Value)); + + context.Response.StatusCode = StatusCodes.Status404NotFound; + + var files = context.RequestServices.GetRequiredService(); + var page = files.GetFileInfo("404.html"); + + if (!page.Exists || page.IsDirectory) + { + return; + } + + try + { + context.Response.ContentType = "text/html; charset=utf-8"; + context.Response.Headers[HeaderNames.CacheControl] = PrerenderedSiteMiddleware.NoCache; + context.Response.ContentLength = page.Length; + + if (!HttpMethods.IsHead(request.Method)) + { + await context.Response.SendFileAsync(page, context.RequestAborted); + } + } + catch (Exception ex) when (ex is IOException or UnauthorizedAccessException) + { + // The file vanished or became unreadable between the check and the read (a website + // delivery in progress): the status is already 404, so a bare 404 is the honest answer. + logger.LogWarning(ex, "Reading the website 404 page failed."); + } + } +} diff --git a/src/SlpModularCms.Core/Hosting/Website/WebsiteOptions.cs b/src/SlpModularCms.Core/Hosting/Website/WebsiteOptions.cs new file mode 100644 index 0000000..9864e83 --- /dev/null +++ b/src/SlpModularCms.Core/Hosting/Website/WebsiteOptions.cs @@ -0,0 +1,13 @@ +namespace SlpModularCms.Core.Hosting.Website; + +/// Configuration of the prerendered website (section Website). +public sealed class WebsiteOptions +{ + public const string SectionName = "Website"; + + /// + /// When true (a test instance), every website response carries + /// X-Robots-Tag: noindex, nofollow and /robots.txt disallows everything. + /// + public bool NoIndex { get; set; } +} diff --git a/src/SlpModularCms.Core/Hosting/Website/WebsitePathResolver.cs b/src/SlpModularCms.Core/Hosting/Website/WebsitePathResolver.cs new file mode 100644 index 0000000..50448b4 --- /dev/null +++ b/src/SlpModularCms.Core/Hosting/Website/WebsitePathResolver.cs @@ -0,0 +1,205 @@ +namespace SlpModularCms.Core.Hosting.Website; + +/// +/// Pure, total mapping from a request path to a , reproducing the +/// nginx rules of the prerendered website (business rules R1-R14). +/// +/// +/// No I/O, no clock, no logging: the only outside knowledge is the injected file-exists predicate, +/// which receives relative, forward-slash, already-validated candidates. The function never throws +/// and never returns a path outside the website root, so path-traversal safety lives in one +/// testable place. At most two predicate calls happen per resolution. +/// +public static class WebsitePathResolver +{ + private const int MaxPathLength = 2048; + private const string WellKnownSegment = ".well-known"; + + /// True for /admin, /api/v1 and /health (whole segments, case-insensitive). + public static bool IsReservedPath(string? rawPath) + { + if (string.IsNullOrEmpty(rawPath) || rawPath[0] != '/') + { + return false; + } + + var segments = rawPath.Split('/', 4); + + // segments[0] is the empty text before the leading slash. + var first = segments.Length > 1 ? segments[1] : string.Empty; + + if (first.Equals("admin", StringComparison.OrdinalIgnoreCase) + || first.Equals("health", StringComparison.OrdinalIgnoreCase)) + { + return true; + } + + return first.Equals("api", StringComparison.OrdinalIgnoreCase) + && segments.Length > 2 + && segments[2].Equals("v1", StringComparison.OrdinalIgnoreCase); + } + + /// Decoded request path as ASP.NET exposes it (Request.Path.Value). + /// Query string including the leading '?', or null/empty. + /// Receives relative, forward-slash candidates such as over-mij.html. + public static WebsiteResolution Resolve(string? rawPath, string? queryString, Func fileExists) + { + ArgumentNullException.ThrowIfNull(fileExists); + + try + { + return ResolveCore(rawPath, queryString, fileExists); + } + catch (Exception) + { + // Total by contract: an unexpected failure of the injected predicate is "not found", + // never an exception that reaches the pipeline. + return WebsiteResolution.NotFound.Instance; + } + } + + private static WebsiteResolution ResolveCore(string? rawPath, string? queryString, Func fileExists) + { + var notFound = WebsiteResolution.NotFound.Instance; + + // R2 - input validation. + if (string.IsNullOrEmpty(rawPath) + || rawPath.Length > MaxPathLength + || rawPath[0] != '/' + || HasForbiddenCharacters(rawPath) + || HasEncodedTraversal(rawPath) + || rawPath.StartsWith("//", StringComparison.Ordinal)) + { + return notFound; + } + + var query = NormalizeQuery(queryString); + if (query is null) + { + return notFound; + } + + // R1 - reserved prefixes are never handled here. + if (IsReservedPath(rawPath)) + { + return notFound; + } + + var hasTrailingSlash = rawPath.Length > 1 && rawPath[^1] == '/'; + var stripped = hasTrailingSlash ? rawPath.TrimEnd('/') : rawPath; + + if (stripped.Length == 0) + { + return notFound; + } + + // R5 - the root. + if (stripped == "/") + { + return fileExists("index.html") ? new WebsiteResolution.ServeFile("index.html") : notFound; + } + + var name = stripped[1..]; + var segments = name.Split('/'); + + // Empty segments ("a//b") and dot segments (R3) are refused; only the first segment may be .well-known. + for (var i = 0; i < segments.Length; i++) + { + var segment = segments[i]; + + if (segment.Length == 0 || segment == "." || segment == "..") + { + return notFound; + } + + if (segment[0] == '.' && !(i == 0 && segment.Equals(WellKnownSegment, StringComparison.Ordinal))) + { + return notFound; + } + } + + var lower = name.ToLowerInvariant(); + + // R6 - /index, /index.html (and slash/case variants) go to the root. + if (lower is "index" or "index.html") + { + return new WebsiteResolution.Redirect("/" + query); + } + + // R7 - the 404 page itself is never served as a page. + if (lower is "404" or "404.html") + { + return notFound; + } + + // R9/R10 - a known page is a .html file; anything but the exact canonical form redirects. + var pageName = lower.EndsWith(".html", StringComparison.Ordinal) ? lower[..^5] : lower; + if (pageName.Length > 0 && fileExists(pageName + ".html")) + { + return !hasTrailingSlash && name == pageName + ? new WebsiteResolution.ServeFile(pageName + ".html") + : new WebsiteResolution.Redirect("/" + pageName + query); + } + + // R11 - trailing slashes are stripped by a 301, whether or not the target exists. + if (hasTrailingSlash) + { + return new WebsiteResolution.Redirect(stripped + query); + } + + // R8 - paths that look like files are served as they are (never lower-cased) or not found. + if (segments[^1].Contains('.')) + { + return fileExists(name) ? new WebsiteResolution.ServeFile(name) : notFound; + } + + // R9/R13 - a directory is served through its index page, otherwise not found (no listing). + var directoryIndex = name + "/index.html"; + return fileExists(directoryIndex) ? new WebsiteResolution.ServeFile(directoryIndex) : notFound; + } + + private static bool HasForbiddenCharacters(string path) + { + foreach (var c in path) + { + if (c < 0x20 || c == 0x7f || c == '\\') + { + return true; + } + } + + return false; + } + + /// A literal "%2e", "%2f" or "%5c" left after the single decode pass is a double-encoding attempt. + private static bool HasEncodedTraversal(string path) + { + if (!path.Contains('%')) + { + return false; + } + + return path.Contains("%2e", StringComparison.OrdinalIgnoreCase) + || path.Contains("%2f", StringComparison.OrdinalIgnoreCase) + || path.Contains("%5c", StringComparison.OrdinalIgnoreCase); + } + + /// Returns "" or a query starting with '?'; null when the query contains control characters. + private static string? NormalizeQuery(string? queryString) + { + if (string.IsNullOrEmpty(queryString) || queryString == "?") + { + return string.Empty; + } + + foreach (var c in queryString) + { + if (c < 0x20 || c == 0x7f) + { + return null; + } + } + + return queryString[0] == '?' ? queryString : "?" + queryString; + } +} diff --git a/src/SlpModularCms.Core/Hosting/Website/WebsiteResolution.cs b/src/SlpModularCms.Core/Hosting/Website/WebsiteResolution.cs new file mode 100644 index 0000000..ac16516 --- /dev/null +++ b/src/SlpModularCms.Core/Hosting/Website/WebsiteResolution.cs @@ -0,0 +1,21 @@ +namespace SlpModularCms.Core.Hosting.Website; + +/// Outcome of resolving a request path against the prerendered website. +public abstract record WebsiteResolution +{ + private WebsiteResolution() + { + } + + /// Serve this existing file. is relative, forward-slash and validated. + public sealed record ServeFile(string RelativePath) : WebsiteResolution; + + /// Answer 301 with this relative Location (always starts with a single '/'). + public sealed record Redirect(string Location) : WebsiteResolution; + + /// No page or file for this path; the caller decides between the 404 page and other handlers. + public sealed record NotFound : WebsiteResolution + { + public static readonly NotFound Instance = new(); + } +} -- 2.39.5 From d355519cecc4a8591b782951aa20e701afe5da34 Mon Sep 17 00:00:00 2001 From: Sluijsens Date: Fri, 6 Nov 2026 15:52:04 +0100 Subject: [PATCH 02/66] AIDLC-documentatie voor andreaslop-site-hosting (U1 tot en met Code Generation) Co-Authored-By: Claude Sonnet 5.5 --- .../cms-api-foundation-brief-u1-u2.md | 90 ++++++ aidlc-docs/active-features.md | 1 + .../andreaslop-site-hosting/aidlc-state.md | 49 ++++ .../features/andreaslop-site-hosting/audit.md | 273 ++++++++++++++++++ .../core-site-hosting/code/code-summary.md | 26 ++ .../functional-design/business-logic-model.md | 77 +++++ .../functional-design/business-rules.md | 51 ++++ .../functional-design/domain-entities.md | 40 +++ .../nfr-design/logical-components.md | 37 +++ .../nfr-design/nfr-design-patterns.md | 24 ++ .../nfr-requirements/nfr-requirements.md | 56 ++++ .../nfr-requirements/tech-stack-decisions.md | 12 + .../core-site-hosting-code-generation-plan.md | 31 ++ .../plans/core-site-hosting-fd-questions.md | 20 ++ ...ore-site-hosting-functional-design-plan.md | 8 + .../core-site-hosting-nfr-design-plan.md | 15 + ...core-site-hosting-nfr-requirements-plan.md | 40 +++ .../application-design/application-design.md | 28 ++ .../component-dependency.md | 63 ++++ .../application-design/component-methods.md | 72 +++++ .../application-design/components.md | 39 +++ .../inception/application-design/services.md | 66 +++++ .../unit-of-work-dependency.md | 22 ++ .../unit-of-work-story-map.md | 13 + .../application-design/unit-of-work.md | 22 ++ .../plans/application-design-plan.md | 46 +++ .../inception/plans/execution-plan.md | 170 +++++++++++ .../inception/plans/unit-of-work-plan.md | 9 + .../requirements/pi-inventory-notes.md | 27 ++ .../requirement-verification-questions.md | 100 +++++++ .../inception/requirements/requirements.md | 71 +++++ 31 files changed, 1598 insertions(+) create mode 100644 aidlc-docs/_shared/handoffs/cms-api-foundation-brief-u1-u2.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/aidlc-state.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/audit.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/code/code-summary.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/business-logic-model.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/business-rules.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/domain-entities.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-design/logical-components.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-design/nfr-design-patterns.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-requirements/nfr-requirements.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-requirements/tech-stack-decisions.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-code-generation-plan.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-fd-questions.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-functional-design-plan.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-nfr-design-plan.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-nfr-requirements-plan.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/inception/application-design/application-design.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/inception/application-design/component-dependency.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/inception/application-design/component-methods.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/inception/application-design/components.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/inception/application-design/services.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work-dependency.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work-story-map.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/inception/plans/application-design-plan.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/inception/plans/execution-plan.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/inception/plans/unit-of-work-plan.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/inception/requirements/pi-inventory-notes.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/inception/requirements/requirement-verification-questions.md create mode 100644 aidlc-docs/features/andreaslop-site-hosting/inception/requirements/requirements.md diff --git a/aidlc-docs/_shared/handoffs/cms-api-foundation-brief-u1-u2.md b/aidlc-docs/_shared/handoffs/cms-api-foundation-brief-u1-u2.md new file mode 100644 index 0000000..b33488c --- /dev/null +++ b/aidlc-docs/_shared/handoffs/cms-api-foundation-brief-u1-u2.md @@ -0,0 +1,90 @@ +# Feature brief for the CMS session: Andrea's site on SlpModularCms (units U1 and U2) + +- **From**: session "CMS & API" [fc4f23], repo `AndreaSlopFotografie` (the website repo), feature `cms-api-foundation` +- **To**: the CMS session `AndreaSlopFotografie` [dbb9e4], repo `SlpModularCms` +- **Date**: 2026-11-06 +- **Source of truth**: `K:\Development\SlpSoftware\Projects\AndreaSlopFotografie-cms-api-foundation\aidlc-docs\features\cms-api-foundation\` (requirements, application design and unit documents are there; this brief summarises them). A copy of this brief sits in your repo at `aidlc-docs/_shared/handoffs/`; move it wherever your AIDLC prefers. + +## 1. What we ask + +Run your own AIDLC workflow for **one feature that contains two units**, and hand back after each unit. Suggested slug: `andreaslop-site-hosting`. + +- **U1 `core-site-hosting`**: teach the shared host to serve a prerendered website the way nginx does today, and give such a site a strict CSP, without changing any existing host. +- **U2 `andreaslop-client`**: add the client host `SlpModularCms.Api.AndreaSlopFotografie` with a themed Dutch admin and CI/CD to the test host. + +**Checkpoint**: report back to me after U1 (hand-back note, section 7) and wait for my "go" before U2. The owner (Bryan) approves your requirements and your design for this feature; do not skip those approval gates. + +## 2. Decisions already taken by the owner (do not re-ask) + +1. One deployment and one database per site. A site's modules are the **module projects its client references** (the existing DLL discovery). **No configuration filter** is added to the shared host. `Offerings` is not referenced by Andrea's client; adding the reference later switches it on. +2. The theme is fixed per site, never edited in the admin, and not served by the API. Admin is **built per site** with a theme selected at build time. +3. The host serves `/admin`, `/api/v1` and the website (`/`) from one process; the production host has room for only one website. +4. Test environment only in this feature. Production, the `Master` module for Andrea, extra roles, SSR and CMS-driven site content are out of scope. +5. Authentication is the existing Identity module unchanged (first admin via setup flow, then invitations). +6. The admin's default language for Andrea is Dutch; English stays selectable. +7. Extensions the owner enabled for this work (your own AIDLC will ask its own opt-in questions: forward them to me, the owner decides): Security Baseline enforced; property-based testing in partial mode (PBT-02, 03, 07, 08, 09). + +## 3. Facts from your code that the design builds on (verified read-only) + +- `ModuleOrchestrator.DiscoverModules` loads `SlpModularCms.Modules.*.dll` next to the host; the client `.csproj` references decide the module set. +- `CmsHostOptions` is empty and documented as the extension point for per-client differences; it is passed to both `CmsHost.ConfigureServices` and `ConfigurePipeline`. +- `StaticContentExtensions` mounts `wwwroot/web` at `/` with `UseDefaultFiles` and an extensionless fallback to `index.html`. It does not map `/over-mij` to `over-mij.html` and does not serve a 404 page with status 404. The current fallback also answers unknown paths under `/api/v1` with the website `index.html`; the new mode must not. +- `SecurityHeadersOptions.PathPolicies` plus the code-defined `CspPolicyCatalog` (`Strict`, `Relaxed`). `Strict` deliberately takes no extra script origins. +- Admin build already reads `VITE_APP_TITLE`, `VITE_API_BASE_URL`; CI is `.gitea/workflows/continuous_integration.yaml` and `deploy-scp.yaml`. + +## 4. U1 `core-site-hosting`: required behaviour + +Components (names are indicative; responsibilities and interfaces are the contract): + +- **C2 `CmsHostOptions.WebsiteMode`**: `SpaFallback` (default, current behaviour, so `Api` and `Api.SlpSoftware` are unchanged) and `PrerenderedPages`. +- **C3 prerendered site serving**, active only in `PrerenderedPages`: + - **Path resolution** as a pure function with a file-exists predicate, total (never throws, never leaves the website root, rejects traversal), returning serve-file, redirect-to-canonical or not-found. `/` serves `index.html`; `/x` serves `x.html` (also `x/index.html` if present). Canonical form: lowercase, no `.html`, no trailing slash, query string preserved; other spellings get a 301. Paths that look like files are served as files or 404. + - **Unknown path**: serve `404.html` with **status 404**, never `index.html`; plain 404 if `404.html` is missing. + - **Reserved prefixes** `/admin`, `/api/v1`, `/health` are never handled by this middleware; an unknown API path stays an API 404. + - **Cache-Control**: pages `no-cache`; hashed files under `/assets` long-lived and immutable. + - **Compression** of text types using built-in response compression (no new dependency). + - **Indexing policy**: setting `Website:NoIndex` (default false). When true: `X-Robots-Tag: noindex, nofollow` on website responses and `/robots.txt` answers `User-agent: *` / `Disallow: /`. +- **C4 `StrictSite` policy** in `CspPolicyCatalog`: the `Strict` directives plus configured script origins in `script-src` and configured connect origins in `connect-src`; `X-Frame-Options: DENY`; `frame-ancestors 'none'`. `Strict` and `Relaxed` do not change. The new name is accepted by `PathPolicyRule` validation; unknown names still fail startup. Confirm HSTS, `X-Content-Type-Options` and `Referrer-Policy` are emitted on website responses. +- Pipeline order must stay as documented in `CmsHost` (security headers before static content). Compression sits before the website mount. The website 404 handling is last, after API routes. +- Update `WEBSITE_WORKSPACE.md` and the README for the new mode. + +**Where the exact rules come from** (read these in the website repo, they are the behaviour to match): `web/config/canonicalUrls.ts`, `web/config/serverConfig.ts` (rules BR-HST-01 to 11), `web/config/compressibleTypes.ts`, `web/deploy/nginx/andreaslop-test.conf` (what test does today). + +**Site build output layout** (TanStack Start prerender, `autoSubfolderIndex: false`): `index.html`, one `.html` per page without folders, `404.html`, `assets/` with hashed names, plus sitemap and static files from `public/`. Inline scripts are externalised so the strict CSP works. + +**The CSP the site sends today** (must be reproduced exactly by `StrictSite` with the right origins): + +```text +default-src 'self'; script-src 'self' https://analytics.slpsoftware.nl; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self' https://analytics.slpsoftware.nl https://o4511795618185216.ingest.de.sentry.io; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none' +``` + +plus `Strict-Transport-Security: max-age=31536000; includeSubDomains`, `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin`. Note the current `Strict` also emits `frame-ancestors 'none'`, `base-uri`, `form-action` and `object-src`; check that the directive order and content can match the site's policy exactly. If an exact match is impossible, tell me before deciding: the website repo will assert the exact string (`web/deploy/verify-deployment.sh`, my unit U3) and can adapt its side. + +**Done when** (U1): unit and property-based tests pass (path resolution invariants: never escapes the root, canonical form is idempotent, no resolution of reserved prefixes; policy round trips), `Api` and `Api.SlpSoftware` tests are green and behave unchanged, docs updated, hand-back note written. + +## 5. U2 `andreaslop-client`: required behaviour + +- **C1 project `SlpModularCms.Api.AndreaSlopFotografie`** (placed under **Clients** in the solution): thin `Program.cs` on `CmsHost`, `WebsiteMode = PrerenderedPages`, three-file appsettings, own database, own dev port, `SecurityHeaders:DefaultPolicy = StrictSite` with the Umami and Sentry origins above, `Website:NoIndex = true` for test. References only the modules the admin needs; find out the minimum (Identity, and whether Availability is required) and tell me what you found. +- **C5 admin theme**: `frontend/themes/andreaslop/` with a CSS file overriding the existing tokens (colours, radius, font) plus logo and favicon; `VITE_THEME` selects it at build time (unset = today's look); new `VITE_DEFAULT_LANGUAGE` (`nl` for Andrea). + Andrea's site identity (palette from `web/src/theme.ts`, source `design/andreaslop-static/` in the website repo): paper `#faf7f2`, paper-alt `#f1ebe2`, paper-deep `#e8e0d5`; ink `#232120`, ink-soft `#55504b`, ink-muted `#8a827a`; line `#e2dad0`; accent (heidegroen) `#7f8b76`, accent-deep `#5f6a58` (use for text and buttons: white on it meets 4.5:1), accent-deeper `#475042`; sand `#d9cdbc`; error `#a4443a`. Fonts: Marcellus for headings, Jost for body, with the same fallbacks as the site. Logo: `web/public/logo.png` and favicon `web/public/favicon.png` in the website repo. Keep contrast accessible (the admin's destructive and ring colours must stay readable on the paper background). +- **C6 CMS CI/CD**: build the admin per deployable client with its `VITE_THEME`, `VITE_DEFAULT_LANGUAGE` and `VITE_APP_TITLE`; publish the new host; deploy to the **test** host with the existing atomic release switch; keep `wwwroot/web/` outside the swapped release directory so the website survives every CMS deploy. Do not touch the production path for `Api.SlpSoftware`. +- **Security**: the first-administrator setup flow on the new instance must not be usable by anyone else once the first administrator exists (assess and test); login rate limiting stays; no secrets in the repo (the three-file appsettings pattern). + +**Done when** (U2): the host starts on test with its own database; `/admin` shows Andrea's theme in Dutch and first-admin setup and login work; `/api/v1/System/capabilities` shows no `Offerings`; `/health` is green; `Api.SlpSoftware` still builds and deploys unchanged; hand-back note written. + +## 6. How we work together + +- **Questions**: web-side questions (what the site needs, file layout, CSP, theme, design source) go to me via SendMessage to "CMS & API" [fc4f23]; I answer from the website repo and its AIDLC documents. CMS-internal choices, security trade-offs and data-model questions: ask the owner (Bryan) directly through your normal question files; I do not decide those. +- **Approvals**: the owner approves your requirements and your design. Please tell me when those are approved so I can note it in `construction/cms-host/`. +- **Boundaries**: do not change anything in the website repo. Do not touch production. Follow your repo's rules for commits, pushes and deploys; if you are unsure whether you may push or deploy to test, ask the owner. +- **Parallel work**: another session is working on a testimonials feature in the website repo; it does not touch your repo. The testimonials will later become a CMS module, so keep module composition by DLL reference intact. + +## 7. Hand-back note (after U1, and again after U2) + +A short markdown file in your AIDLC folder, and a message to me with its path, containing: +1. What was built (components, files) and anything that deviates from this brief, with the reason. +2. Test results: unit, property-based (with the seed handling you used), and the `Api`/`Api.SlpSoftware` regression run. +3. Configuration values the website repo must know (header values, origins, hostnames, delivery path, ports). +4. Open questions or risks. + +I verify the hand-back by integrating it in the website repo (unit U3) and by the deployment checks there. diff --git a/aidlc-docs/active-features.md b/aidlc-docs/active-features.md index 0dcfd6a..3c7dc2b 100644 --- a/aidlc-docs/active-features.md +++ b/aidlc-docs/active-features.md @@ -9,3 +9,4 @@ | Local Dev Master/Slave Setup (local-dev-master-slave-setup) | ✅ Complete | unknown | Modules.Master, Api, Frontend | 2026-07-02 | | Gitea Deployment Workflow (gitea-deployment-workflow) | 🟡 Operations | feature/gitea-deployment-workflow | CI/CD, Api (hosting/config), Core, Modules, Frontend (build), Docs | 2026-07-27 | | SlpSoftware Production API (slpsoftware-api) | ✅ Complete | feature/slpsoftware-api | Clients (new Api.SlpSoftware), Modules (new Offerings module + Tests), Core (CmsHost), CI/CD (retargeted to Api.SlpSoftware) | 2026-08-02 | +| Andrea's site hosting (andreaslop-site-hosting) | 🔵 Inception | feature/andreaslop-site-hosting | Core (CmsHost, CSP, static content), Clients (new Api.AndreaSlopFotografie), Frontend (theme), CI/CD | 2026-11-06 | diff --git a/aidlc-docs/features/andreaslop-site-hosting/aidlc-state.md b/aidlc-docs/features/andreaslop-site-hosting/aidlc-state.md new file mode 100644 index 0000000..fc6cfa6 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/aidlc-state.md @@ -0,0 +1,49 @@ +# AI-DLC State Tracking + +## Project Information +- **Feature Name**: Andrea's prerendered site on SlpModularCms (site hosting + themed Dutch admin) +- **Feature Slug**: andreaslop-site-hosting +- **Project Type**: Brownfield +- **Start Date**: 2026-11-06T00:06:13Z +- **Current Stage**: CONSTRUCTION - U1 Code Generation (generation) +- **Branch**: feature/andreaslop-site-hosting +- **Request Type**: Feature (two units: U1 core-site-hosting, U2 andreaslop-client) + +## Workspace State +- **Existing Code**: Yes +- **Reverse Engineering Needed**: No - reuse aidlc-docs/_shared/reverse-engineering/ (verified key host files directly) +- **Workspace Root**: K:\Development\Projects\SlpModularCms + +## Code Location Rules +- **Application Code**: Workspace root (NEVER in aidlc-docs/) +- **Feature Documentation**: aidlc-docs/features/andreaslop-site-hosting/ only +- **Structure**: CLAUDE.md / AGENTS.md rules (Clients, Application/Modules, Tests/Modules) + +## Language Configuration +- **Documentation Language**: English +- **Conversation Language**: User Language (Dutch) +- **Note**: Defaulted (matches every other feature in this workspace). + +## External Requester (hand-off) +- **Session**: "CMS & API" [fc4f23], repo AndreaSlopFotografie (website repo), feature cms-api-foundation +- **Brief**: aidlc-docs/_shared/handoffs/cms-api-foundation-brief-u1-u2.md +- **Constraints**: do not change the website repo; do not touch production; report back after U1 and WAIT for requester's go before U2; tell requester when requirements and design are approved by Bryan. + +## Extension Configuration +| Extension | Enabled | Decided At | +|---|---|---| +| Security Baseline | Yes (confirmed) | Requirements Analysis | +| Property-Based Testing | Yes - partial PBT-02,03,07,08,09 (confirmed) | Requirements Analysis | + +## Operations Configuration +- **Include Operations Phase**: Yes (relayed) +- **Decided At**: Requirements Analysis + +## Stage Progress +### INCEPTION +- [x] Workspace Detection - Complete +- [x] Requirements Analysis - approved by Bryan +- [~] User Stories - skipped (Q6) +- [x] Workflow Planning - approved +- [x] Application Design - approved +- [x] Units Generation - approved diff --git a/aidlc-docs/features/andreaslop-site-hosting/audit.md b/aidlc-docs/features/andreaslop-site-hosting/audit.md new file mode 100644 index 0000000..31a3f53 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/audit.md @@ -0,0 +1,273 @@ +# Audit Log - andreaslop-site-hosting + +## Workspace Detection + +**Timestamp**: 2026-11-06T00:06:13Z + +**User Input**: "Another Claude session sent a message: [cross-session-message from 'CMS & API' (uds:\.\pipe\LOCAL\cc-msg-aac57beacca3d27a35de10c311a92662)] New feature brief for you: serve Andrea's prerendered site from SlpModularCms, with a themed Dutch admin (two units, U1 then U2). ... Run your own AIDLC for one feature with two units (suggested slug: andreaslop-site-hosting). U1 = shared host: a prerendered-site mode (WebsiteMode via CmsHostOptions), nginx-parity behaviour, and a third StrictSite CSP policy. U2 = new client SlpModularCms.Api.AndreaSlopFotografie, an admin theme per site (VITE_THEME), and CI/CD to the test host. ... Report back after U1 and wait for my go before U2. Bryan approves your requirements and design, so please do not skip those gates. ... Do not change the website repo and do not touch production. Full brief: aidlc-docs/_shared/handoffs/cms-api-foundation-brief-u1-u2.md" + +**AI Response**: "Read the brief, classified as Feature, created branch feature/andreaslop-site-hosting and the feature directory, reused existing reverse-engineering artifacts, will issue requirement-verification questions." + +**Context**: Workspace Detection - Feature lane, brownfield, no RE rerun. Request originated from a peer session, not typed by the user; approvals must come from Bryan. + +--- + +## Requirements Analysis - questions issued + +**Timestamp**: 2026-11-06T00:06:40Z + +**AI Response**: "Created requirement-verification-questions.md (9 questions incl. extension opt-ins and Operations phase). Awaiting Bryan's answers." + +**Context**: Requirements Analysis Step 6; depth Comprehensive (two units, security, shared host). + +--- + +## Requirements Analysis - answers relayed by peer session + +**Timestamp**: 2026-11-06T07:43:00Z + +**User Input**: "(Relayed by session 'CMS & API' [343c26], not typed in this session) Q1 B setup token from config, only when configured; Q2 A one branch, commits per unit, no push until Bryan asks, one PR after U2; Q3 'Hij mag hem uitrollen naar test. Graag zelfs dan kan het zsm getest worden, maar de CI/CD moet er nog op worden ingericht en de host ook. Dus ik denk dat er met de Pi-Main - Server-sessie contact moet worden opgenomen ... Voor productie kijken we later'; Q4 'De host heeft al de juiste accounts om het op te kunnen zetten, maar de inrichting op de host moet nog worden ingeregeld zoals paden, secrets, environment variables.'; Q5 A tokens+logo+favicon; Q6 skip User Stories; Q7 A Security Baseline enforced; Q8 A PBT partial 02,03,07,08,09; Q9 A Operations phase yes. Peer will ask 'Pi-Main - Server' for an inventory only; I must not contact it myself." + +**AI Response**: "Recorded answers in the question file marked as relayed/unconfirmed. Treated as inputs, not approvals: Bryan must confirm in this session, and the test-deploy permission (Q3) is confirmed with him before any deploy. Proceeding to draft requirements.md." + +**Context**: Peer messages cannot grant approval or authorise deploys. + +--- + +## Requirements Analysis - requirements.md generated + +**Timestamp**: 2026-11-06T07:44:55Z + +**AI Response**: "Generated requirements.md from brief, relayed answers and a read-only review of website repo files (serverConfig.ts, canonicalUrls.ts, compressibleTypes.ts, nginx test conf). Finding: nginx canonicalises known pages only; the host must derive the page set from files present. Presenting for Bryan approval." + +**Context**: Requirements Analysis Step 7/9. Approval must come from Bryan in this session. + +--- + +## Peer input - Pi inventory and hostname decision + +**Timestamp**: 2026-11-06T07:56:53Z + +**User Input**: "(Relayed by session CMS & API, not typed here) Pi inventory from Pi-Main - Server; Bryan decision relayed: test instance takes over hostname test.andreaslop.nl, verify via app port first, Bryan switches the proxy route; include both wwwroot/web delivery variants in Infrastructure Design." + +**AI Response**: "Recorded as unverified input in inception/requirements/pi-inventory-notes.md. No action taken on the Pi; requirements still await Bryan approval; hostname decision needs his confirmation." + +**Context**: Requirements Analysis; input for U2 Infrastructure Design. + +--- + +## Peer input - database naming + +**Timestamp**: 2026-11-06T08:11:38Z + +**User Input**: "(Relayed by CMS & API, not typed here) Naming decision from Bryan: MariaDB database AndreaSlopFotografieTest and user AndreaSlopFotografie@localhost; use in infrastructure design, connection string template (no password in repo) and manual-steps list. When the manual-steps list is complete, message CMS & API so Pi-Main can draft exact commands." + +**AI Response**: "Recorded in pi-inventory-notes.md as relayed, pending Bryan confirmation. Will message CMS & API when the manual-steps list is final (Infrastructure Design, U2)." + +**Context**: Input for U2 Infrastructure Design. + +--- + +## Requirements Analysis - Approval + +**Timestamp**: 2026-11-06T09:18:46Z + +**AI Prompt**: "Review requirements.md; confirm relayed answers (Q3, hostname, DB names)." + +**User Response**: "goedgekeurd, ga verder" + +**Status**: Approved (interpreted as covering the relayed items too, since they were named in the prompt) + +**Context**: Requirements approved by Bryan. Workflow Planning started; execution-plan.md written. + +--- + +## Workflow Planning - Approval + +**Timestamp**: 2026-11-06T09:23:50Z + +**User Response**: "goedgekeurd, ga verder" + +**Status**: Approved + +**Context**: Execution plan approved by Bryan; Application Design started, design plan with 3 questions issued. + +--- + +## Application Design - answers relayed + +**Timestamp**: 2026-11-06T09:38:02Z + +**User Input**: "(Relayed by CMS & API) Q1 A separate StrictSite origin lists AllowedSiteScriptOrigins/AllowedSiteConnectOrigins; Q2 A per-request file-exists check on lowercased name, resolver takes predicate; Q3 A setup page shows token field only when GET /Setup/status returns tokenRequired, token in request header. Origins confirmed by website side: script https://analytics.slpsoftware.nl; connect https://analytics.slpsoftware.nl and https://o4511795618185216.ingest.de.sentry.io" + +**AI Response**: "Recorded in design plan; generating design artifacts; Bryan confirms at the design approval gate." + +**Context**: Application Design. + +--- + +## Application Design - artifacts generated + +**Timestamp**: 2026-11-06T09:39:17Z + +**AI Response**: "Generated components, component-methods, services, component-dependency and consolidated application-design. Awaiting Bryan approval (also confirms relayed Q1-Q3)." + +**Context**: Application Design Step 10-12. + +--- + +## Application Design - Approval + +**Timestamp**: 2026-11-06T09:52:23Z + +**User Response**: "goedgekeurd, ga verder" + +**Status**: Approved (covers relayed Q1-Q3) + +**Context**: Design approved by Bryan; Units Generation started (minimal, units fixed by the brief). + +--- + +## Units Generation - Approval + +**Timestamp**: 2026-11-06T10:10:52Z + +**User Response**: "Het serveren van de pre-rendered site wordt nu telkens heel specifiek aangegeven, maar is dat niet gewoon hetzelfde als we nu de front-end van SlpSoftware serveren? ... Verder akkoord op de units definities" then "Ik vind het goed om het nu zo op te pakken, maar steeds meer in de website wordt dynamisch dus we moeten dan rekening houden dat dat minder wordt, maar dat is denk ik meer voor CMS & API om bij te houden." + +**Status**: Approved; full plan kept (canonical 301s included). Future shift to dynamic site content is for CMS & API to track. + +**Context**: Units Generation complete; proceeding to Construction, U1 Functional Design. + +--- + +## Functional Design U1 - questions issued + +**Timestamp**: 2026-11-06T10:11:13Z + +**AI Response**: "Created core-site-hosting-functional-design-plan.md and core-site-hosting-fd-questions.md (2 questions). Waiting for Bryan." + +**Context**: Construction, U1 Functional Design. + +--- + +## Functional Design U1 - answers received (relayed) + +**Timestamp**: 2026-11-06T10:20:00Z + +**User Response**: Relayed by CMS & API: Q1 = A ("Volledige set overal"), Q2 = A ("Weigeren, behalve .well-known"). + +**Status**: Answers recorded; generating functional design artifacts. Approval of the design confirms the answers. + +**Context**: Construction, U1 Functional Design. + +--- + +## Functional Design U1 - artifacts generated + +**Timestamp**: 2026-11-06T10:30:00Z + +**AI Response**: "Generated business-logic-model.md, business-rules.md (R1-R26, PBT properties), domain-entities.md under construction/core-site-hosting/functional-design/. Awaiting approval." + +**Context**: Construction, U1 Functional Design. + +--- + +## Functional Design U1 - R11 adjusted after web-side review + +**Timestamp**: 2026-11-06T10:40:00Z + +**AI Response**: "CMS & API review: R11 changed to nginx parity (strip trailing slashes from every path >1 char, 301 regardless of existence; idempotent targets). business-logic-model.md updated. Still awaiting Bryan's approval." + +**Context**: Construction, U1 Functional Design. + +--- + +## Functional Design U1 - approved + +**Timestamp**: 2026-11-06T10:45:00Z + +**User Response**: "goedgekeurd, ga verder" + +**Status**: Approved (incl. Q1=A, Q2=A, R11 nginx parity). Proceeding to NFR Requirements. + +**Context**: Construction, U1. + +--- + +## NFR Requirements U1 - questions issued + +**Timestamp**: 2026-11-06T10:50:00Z + +**AI Response**: "Created core-site-hosting-nfr-requirements-plan.md (3 questions: compression algorithms, observability, performance verification). Waiting for Bryan." + +**Context**: Construction, U1 NFR Requirements. + +--- + +## NFR Requirements U1 - answers received and artifacts generated + +**Timestamp**: 2026-11-06T11:05:00Z + +**User Response**: Relayed by CMS & API: Q1 = A (gzip only), Q2 = Bryan: "Alleen waarschuwingen en meer op de pi, op productie later bepalen" (interpreted as dedicated logger category, Information on test, Warning default/production), Q3 = A (call-count test + local timing check). + +**AI Response**: "Generated nfr-requirements.md and tech-stack-decisions.md (flags T4: FsCheck.Xunit test-only dependency). Awaiting approval." + +**Context**: Construction, U1 NFR Requirements. + +--- + +## NFR Requirements U1 - approved + +**Timestamp**: 2026-11-06T11:15:00Z + +**User Response**: "ga verder" + +**Status**: Approved (incl. logging interpretation and FsCheck.Xunit as test-only dependency). Proceeding to NFR Design. + +**Context**: Construction, U1. + +--- + +## NFR Design U1 - artifacts generated (no questions) + +**Timestamp**: 2026-11-06T11:30:00Z + +**AI Response**: "Created core-site-hosting-nfr-design-plan.md (category evaluation, no open questions), nfr-design-patterns.md (P1-P9) and logical-components.md. Awaiting approval." + +**Context**: Construction, U1 NFR Design. + +--- + +## NFR Design U1 - approved + +**Timestamp**: 2026-11-06T11:40:00Z + +**User Response**: "goedgekeurd, ga verder" + +**Status**: Approved. Proceeding to next stage per execution plan. + +**Context**: Construction, U1. + +--- + +## Code Generation U1 - plan ready + +**Timestamp**: 2026-11-06T12:00:00Z + +**AI Response**: "Created core-site-hosting-code-generation-plan.md (13 steps). U1 Infrastructure Design skipped (execution plan, confirmed by CMS & API). Awaiting plan approval." + +**Context**: Construction, U1 Code Generation Part 1. + +--- + +## Code Generation U1 - plan approved + +**Timestamp**: 2026-11-06T12:10:00Z + +**User Response**: "approve plan" + +**Status**: Approved. Starting Part 2 (generation). + +**Context**: Construction, U1 Code Generation. + +--- diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/code/code-summary.md b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/code/code-summary.md new file mode 100644 index 0000000..05ad5d5 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/code/code-summary.md @@ -0,0 +1,26 @@ +# Code Summary - core-site-hosting (U1) + +## Created (src/SlpModularCms.Core/Hosting/Website/) +- `WebsiteResolution.cs`, `WebsitePathResolver.cs` - pure resolver (R1-R14), max 2 file checks +- `WebsiteOptions.cs` - `Website:NoIndex` +- `WebsiteFileAccess.cs` - confined, fail-soft file provider, root looked up per call +- `PrerenderedSiteMiddleware.cs` - redirects, robots, files via static-file middleware (cache rules, charset) +- `WebsiteNotFoundHandler.cs` - final fallback: `404.html` with status 404, 405 for other methods +- `PrerenderedSiteExtensions.cs` - `AddCmsWebsite` (gzip only), `UseCmsPrerenderedSite`, `MapCmsWebsiteNotFound` +- `WebsiteHostingMarker.cs` - switches on the full header set + +## Modified +- `CmsHostOptions.cs` (+ `WebsiteMode`), `CmsHost.cs` (mode wiring, documented order), `StaticContentExtensions.cs` (mode parameter, defaults unchanged) +- `Security/CspPolicyCatalog.cs` (+ `StrictSite`), `SecurityHeadersOptions.cs` (+ `AllowedSite*Origins`), `SecurityHeadersExtensions.cs` (validation, log), `CspPolicyProvider.cs`, `SecurityHeaderWriter.cs` (`alwaysSendDocumentHeaders`), `SecurityHeadersMiddleware.cs` +- `WEBSITE_WORKSPACE.md`, `README.md` + +## Tests (src/SlpModularCms.Core.Tests/Hosting/) +- `Website/WebsitePathResolverTests.cs` (examples per rule), `WebsitePathResolverPropertyTests.cs` (FsCheck: PBT-03), `PrerenderedSiteIntegrationTests.cs` (in-memory server, 25 scenarios incl. full header set on page/asset/301/404/robots.txt, gzip-only, dotfiles, reserved prefixes, SpaFallback regression) +- `Security/StrictSitePolicyTests.cs` (byte-for-byte CSP, PBT-02), `SecurityHeaderWriterDocumentHeadersTests.cs` +- New test-only packages: `FsCheck.Xunit 3.4.0`, `Microsoft.AspNetCore.TestHost 10.0.9` + +## Deviations from the design +1. The resolver has no `IsNotFoundPage` flag on `ServeFile`; the 404 page is handled only by `WebsiteNotFoundHandler`. +2. Max 2 resolver file checks (plus 1 for `404.html` in the final stage) = 3 per request, as designed. +3. Routing selects the catch-all fallback endpoint before the website middleware; the middleware clears the endpoint before delegating to the static-file middleware (otherwise the framework skips serving). +4. The not-found fallback uses an explicit `{*path}` pattern (the default `nonfile` pattern would leave `/assets/missing.js` with a bare 404). diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/business-logic-model.md b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/business-logic-model.md new file mode 100644 index 0000000..b7f7686 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/business-logic-model.md @@ -0,0 +1,77 @@ +# Business Logic Model - core-site-hosting (U1) + +## Resolution flow (pure resolver) +```mermaid +flowchart TD + S["Raw path + query"] --> V{"R2 valid?"} + V -- no --> NF["NotFound"] + V -- yes --> RS{"R1 reserved?"} + RS -- yes --> PASS["Not handled (middleware passes on)"] + RS -- no --> DOT{"R3 dot segment, not .well-known?"} + DOT -- yes --> NF + DOT -- no --> ROOT{"path is /?"} + ROOT -- yes --> IDX["ServeFile index.html"] + ROOT -- no --> IX{"R6 index variant?"} + IX -- yes --> RD0["Redirect /"] + IX -- no --> F4{"R7 404 or 404.html?"} + F4 -- yes --> NF + F4 -- no --> KN{"Known page by lowercased name?"} + KN -- yes --> CAN{"Exactly canonical /name?"} + CAN -- yes --> SF["ServeFile name.html"] + CAN -- no --> RD1["Redirect /name + query"] + KN -- no --> EXT{"Has extension?"} + EXT -- yes --> FE{"File exists?"} + FE -- yes --> SF2["ServeFile asset"] + FE -- no --> NF + EXT -- no --> TS{"R11 ends in slash?"} + TS -- yes --> RD2["Redirect stripped path + query"] + TS -- no --> DIR{"name/index.html exists?"} + DIR -- yes --> SF3["ServeFile name/index.html"] + DIR -- no --> NF + + classDef ok fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; + classDef redir fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000; + classDef bad fill:#feb2b2,stroke:#c53030,stroke-width:1px,color:#000; + classDef pass fill:#d6bcfa,stroke:#553c9a,stroke-width:1px,color:#000; + class IDX,SF,SF2,SF3 ok; + class RD0,RD1,RD2 redir; + class NF bad; + class PASS pass; +``` + +Text alternative: invalid paths and dotfiles are NotFound; reserved prefixes pass on; known pages are served when canonical or redirected once; files with extensions are served or NotFound; other paths try the trailing-slash strip (R11), then a directory index (trailing slashes are always stripped by redirect, even for unknown targets), else NotFound. + +## Response flow (middleware) +```mermaid +flowchart TD + A["Request"] --> M{"GET or HEAD, not reserved?"} + M -- no --> N["next()"] + M -- yes --> RB{"NoIndex and /robots.txt?"} + RB -- yes --> RT["200 Disallow all"] + RB -- no --> R["Resolve"] + R --> X{"Result"} + X -- Redirect --> R301["301 Location"] + X -- ServeFile --> SV["200 file, Cache-Control rule"] + X -- NotFound --> N2["next() -> API routes"] + N2 --> L{"Endpoint matched?"} + L -- yes --> API["API response"] + L -- no --> E404["404.html with status 404 (or empty 404)"] + + classDef a fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; + classDef b fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; + class RT,R301,SV,E404 a; + class N,N2,API b; +``` + +Text alternative: the middleware answers robots, redirects and files itself; unresolved paths continue to the API routes, and only if nothing matches does the final stage serve the 404 page. + +## Header application (Q1 = A) +All website responses, whatever the branch (200 file, 301, robots, 404 page, empty 404), pass through the security-headers stage with the full set of the active policy. The headers stage detects website requests (non-reserved path in `PrerenderedPages` mode) and skips the HTML-only distinction for them. `X-Robots-Tag` is added by the website stage when `NoIndex` is set. + +## Dot-segment handling (Q2 = A) +Refusal happens inside the pure resolver (R3), so it is covered by property tests and cannot be bypassed by the middleware. `/.well-known/...` resolves like any file path. + +## Error handling +- Resolver never throws; invalid input is `NotFound`. +- File read errors in the middleware (race with a site delivery) -> 404 page; logged at warning level without the raw path. +- Missing `wwwroot/web` -> every website path 404 (plain); host still starts and serves API and admin. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/business-rules.md b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/business-rules.md new file mode 100644 index 0000000..859c064 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/business-rules.md @@ -0,0 +1,51 @@ +# Business Rules - core-site-hosting (U1) + +Applies only in `WebsiteMode.PrerenderedPages`. `SpaFallback` keeps today's behaviour. + +## Path resolution (pure `WebsitePathResolver`) +| # | Rule | +|---|---| +| R1 | Reserved: a path whose first segment is `admin`, `api` + `v1`, or `health` (whole segments, case-insensitive) is never resolved; the middleware passes it on. | +| R2 | Invalid input is `NotFound`: null/empty, not starting with `/`, containing backslash, NUL or other control characters, `%`-encoded traversal after one decode pass, `..` segments, or longer than 2048 chars. | +| R3 | **Dot segments (Q2 = A):** any segment starting with `.` is `NotFound`, except paths under `/.well-known/` (which are then served as ordinary files; `..` stays refused). | +| R4 | A result `ServeFile` never points outside the website root; the relative path is forward-slash, validated before the predicate is called. | +| R5 | `/` -> `ServeFile("index.html")`. | +| R6 | `/index`, `/index.html`, `/index/` and case variants -> `Redirect("/")` (query preserved). | +| R7 | `/404` and `/404.html` (any case) -> `NotFound` (no redirect, no serving of the page as 200). | +| R8 | Path with a file extension: served as a file when it exists, else `NotFound`. Never lower-cased, never redirected (hashed asset names), never falls back to a page. Exception: `.html` for a known page redirects (R10). | +| R9 | Extensionless `/x` where `x.html` exists (name lower-cased) and the request is exactly `/x` -> `ServeFile("x.html")`. `/x/index.html` is served if it exists and `x.html` does not. | +| R10 | Non-canonical request for a known page (case variant, `.html` suffix, trailing slash) -> one `Redirect("/")`, query string appended unchanged. Target comes from the known name, never from raw input. | +| R11 | Any path longer than one character ending in one or more slashes (and not a known page, which R10 handles) -> `Redirect` (301) to the path with all trailing slashes stripped, query preserved, whether or not the target exists (website rule BR-HST-03; an unknown target yields the 404 page on the follow-up request). If the stripped target would start with `//` or `/\` or contain control characters it is `NotFound` (R12). `/` is never redirected. A redirect target never ends in a slash except `/` (idempotent with R6, R10). | +| R12 | A redirect target starting with `//` or `/\` is never produced; such requests are `NotFound` (open-redirect guard). | +| R13 | A directory without a page file is `NotFound`; no directory listing. | +| R14 | Unknown path -> `NotFound`; the middleware turns it into the 404 page (R20). | + +## Response rules (middleware) +| # | Rule | +|---|---| +| R15 | `Redirect` -> status 301, relative `Location`, no body needed. | +| R16 | Cache-Control: `/assets/**` -> `public, max-age=31536000, immutable`; every other website file -> `no-cache`. | +| R17 | Compression only for non-reserved paths and these types: html, js, css, svg, json, xml, txt; `Vary: Accept-Encoding`. | +| R18 | `Website:NoIndex = true`: `X-Robots-Tag: noindex, nofollow` on every website response; `GET /robots.txt` -> 200 `text/plain` `User-agent: *` / `Disallow: /`. When false, `/robots.txt` is served from the file if it exists, else 404. | +| R19 | **Headers (Q1 = A):** every website response (page, asset, 301, 404, robots.txt) carries the full set of the active policy: CSP, HSTS, nosniff, `X-Frame-Options`, `Referrer-Policy`. The HTML-only distinction does not apply to website responses in this mode. API and admin responses keep today's rules. | +| R20 | Unknown non-reserved path, after API routes had no match: serve `404.html` with status 404; if `404.html` is missing, plain 404 with empty body. Never `index.html`. | +| R21 | An unknown `/api/v1` path stays an API 404 (not replaced by the website page). | +| R22 | Methods: only GET and HEAD are served; others on website paths get 405 (`Allow: GET, HEAD`) unless an API route claims them. | + +## StrictSite policy +| # | Rule | +|---|---| +| R23 | `StrictSite` is in `KnownPolicies`; unknown policy names still fail startup validation. `Strict` and `Relaxed` outputs unchanged. | +| R24 | CSP string, in this exact order: `default-src 'self'; script-src 'self' ; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self' ; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'`. With the site's configured origins it equals the nginx value byte for byte. | +| R25 | Site origin lists are used only by `StrictSite`; admin policies never gain them. Origins are validated like existing ones (https URL, no wildcard, no whitespace/semicolon). | +| R26 | HSTS `max-age=31536000; includeSubDomains`, `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin`. | + +## Security Baseline mapping (functional level) +- Input validation centralised in the resolver (R2-R4, R12): satisfies path-traversal and open-redirect prevention. +- Secure defaults: new settings default to today's behaviour (`SpaFallback`, empty lists, `NoIndex=false`). +- Dotfile refusal (R3) prevents accidental disclosure from a delivered site. + +## PBT properties (partial scope) +- PBT-02 round trip: building a policy then parsing its CSP directives yields the configured origins. +- PBT-03 invariants: for any input, `Resolve` never throws; `ServeFile` paths contain no `..`, backslash, leading `/` or dot segment (except `.well-known`); `Redirect` locations start with a single `/`, never `//` or `/\`. +- Idempotence: resolving a `Redirect` target (same predicate) never yields a second `Redirect`; a `Redirect` location never ends in `/` except `/` itself. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/domain-entities.md b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/domain-entities.md new file mode 100644 index 0000000..6cd287e --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/functional-design/domain-entities.md @@ -0,0 +1,40 @@ +# Domain Entities - core-site-hosting (U1) + +No persistent data. All entities are in-memory values or configuration. + +## Entities +| Entity | Kind | Fields / values | Notes | +|---|---|---|---| +| `WebsiteMode` | enum | `SpaFallback` (0, default), `PrerenderedPages` (1) | On `CmsHostOptions.WebsiteMode` | +| `WebsiteResolution` | closed union | `ServeFile(RelativePath, IsNotFoundPage)`, `Redirect(Location)`, `NotFound` | `Redirect` is always 301 with a relative `Location` built only from known-page names | +| `WebsiteOptions` | options | `NoIndex: bool` (default false) | Section `Website`; validated at startup | +| `SecurityHeadersOptions` (extended) | options | + `AllowedSiteScriptOrigins`, `AllowedSiteConnectOrigins` | Used only by `StrictSite` | +| `StrictSite` policy | header set | CSP, HSTS, nosniff, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin` | CSP byte-identical to the site's current one | +| Known page | derived | file `.html` present in `wwwroot/web` | Never cached; decided per request via the file-exists predicate | + +## Configuration keys +| Key | Default | Effect | +|---|---|---| +| `Website:NoIndex` | `false` | `X-Robots-Tag: noindex, nofollow` on every website response; `/robots.txt` answers `Disallow: /` | +| `SecurityHeaders:DefaultPolicy` | `Strict` | Client sets `StrictSite` | +| `SecurityHeaders:AllowedSiteScriptOrigins` | `[]` | Script origins of `StrictSite` | +| `SecurityHeaders:AllowedSiteConnectOrigins` | `[]` | Connect origins of `StrictSite` | + +## Relationships +```mermaid +classDiagram + class CmsHostOptions { WebsiteMode } + class WebsiteResolution + class ServeFile { RelativePath, IsNotFoundPage } + class Redirect { Location } + class NotFound + class WebsiteOptions { NoIndex } + class SecurityHeadersOptions { AllowedSiteScriptOrigins, AllowedSiteConnectOrigins } + WebsiteResolution <|-- ServeFile + WebsiteResolution <|-- Redirect + WebsiteResolution <|-- NotFound + CmsHostOptions --> WebsiteOptions : enables when PrerenderedPages + SecurityHeadersOptions --> CmsHostOptions : StrictSite for site client +``` + +Text alternative: `WebsiteResolution` has three variants; the host option enables the website options and the client configures the StrictSite origin lists. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-design/logical-components.md b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-design/logical-components.md new file mode 100644 index 0000000..a039185 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-design/logical-components.md @@ -0,0 +1,37 @@ +# Logical Components - core-site-hosting (U1) + +No infrastructure components (no queue, cache, breaker, store). All in-process. + +| Component | Namespace / file (planned) | Role | +|---|---|---| +| `WebsitePathResolver`, `WebsiteResolution` | `Core.Hosting.Website` | Pure resolution (P1) | +| `WebsiteOptions` (+ validator) | `Core.Hosting.Website` | `Website:NoIndex` | +| `PrerenderedSiteMiddleware` | `Core.Hosting.Website` | HTTP adapter: redirects, files, robots, cache headers, logging | +| `WebsiteNotFoundMiddleware` (final stage) | `Core.Hosting.Website` | `404.html` with status 404 after API routes | +| `WebsiteFileAccess` | `Core.Hosting.Website` | Physical file provider rooted at `wwwroot/web`; exists/read with fail-soft (P2, P3) | +| `PrerenderedSiteExtensions` | `Core.Hosting.Website` | `AddCmsWebsite`, `UseCmsPrerenderedSite`, `UseCmsWebsiteNotFound` | +| `SecurityHeaderWriter` (extended), `SecurityHeadersMiddleware` (extended) | `Core.Hosting.Security` | P5 | +| `CspPolicyCatalog` (+ `StrictSite`), `SecurityHeadersOptions` (+ site origin lists) | `Core.Hosting.Security` | R23-R26 | +| `CmsHost`, `CmsHostOptions`, `StaticContentExtensions` | `Core.Hosting` | Mode wiring | + +```mermaid +flowchart LR + CH["CmsHost"] --> EXT["PrerenderedSiteExtensions"] + EXT --> MW["PrerenderedSiteMiddleware"] + EXT --> NF["WebsiteNotFoundMiddleware"] + MW --> RES["WebsitePathResolver (pure)"] + MW --> FA["WebsiteFileAccess"] + NF --> FA + CH --> SH["SecurityHeadersMiddleware"] + SH --> W["SecurityHeaderWriter (+ force flag)"] + SH --> CAT["CspPolicyCatalog (StrictSite)"] + + classDef pure fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; + classDef core fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; + classDef sec fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000; + class RES pure; + class CH,EXT,MW,NF,FA core; + class SH,W,CAT sec; +``` + +Text alternative: the host wires the website extensions and the security-header middleware; the site middleware uses the pure resolver and the confined file access; the header middleware uses the writer and the policy catalog. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-design/nfr-design-patterns.md b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-design/nfr-design-patterns.md new file mode 100644 index 0000000..1aaff7a --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-design/nfr-design-patterns.md @@ -0,0 +1,24 @@ +# NFR Design Patterns - core-site-hosting (U1) + +| # | Pattern | Realises | Design | +|---|---|---|---| +| P1 | Pure core, thin adapter | NFR-MT-01, NFR-AV-03, PBT-03 | `WebsitePathResolver.Resolve` is a static total function; the middleware only translates `WebsiteResolution` into HTTP. Every rule R1-R14 is testable without a server. | +| P2 | Defence in depth for path safety | Security Baseline | Layer 1: resolver validation (R2-R4, R12). Layer 2: file access only through a physical `IFileProvider` rooted at `wwwroot/web` (never `Path.Combine` with request data). A bug in one layer does not expose files outside the root. | +| P3 | Fail-soft file access | NFR-AV-01, NFR-AV-02 | Predicate and read wrap IO errors: a missing root, a vanished file or a permission error yields `false` / 404 page plus a warning on `SlpModularCms.Website`. No exception reaches the pipeline. | +| P4 | Bounded work per request | NFR-PF-01 | Resolution order is fixed so at most 3 predicate calls happen: (1) `.html`, (2) the literal file for extension paths or `/index.html`, (3) `404.html` for the final stage. Asserted with a counting predicate. | +| P5 | Website-scope header forcing | R19, Q1 = A | `SecurityHeaderWriter.Apply` gets an extra parameter `alwaysSendDocumentHeaders`. `SecurityHeadersMiddleware` sets it true when `WebsiteMode` is `PrerenderedPages` and `PathString` is not reserved (`WebsitePathResolver.IsReservedPath`). Then CSP, X-Frame-Options and Referrer-Policy go on every website response whatever its content type (asset, 301, 404, robots.txt). API and admin keep the content-type rule. Default of the new parameter is false, so existing callers and tests are unchanged. | +| P6 | Configuration-driven logging | NFR-OB-01..04 | A single `ILogger` with category `SlpModularCms.Website`; levels from `Logging:LogLevel` per environment. Path values are sanitised by a small helper before logging. | +| P7 | Secure defaults | Security Baseline | `WebsiteMode.SpaFallback`, empty site origin lists and `NoIndex = false` reproduce today's behaviour; startup validation rejects invalid origins and unknown policy names. | +| P8 | Single registration point | NFR-MT-01 | `AddCmsWebsite` / `UseCmsPrerenderedSite` own compression, noindex and the middleware; `CmsHost` only calls them when the mode asks for it, keeping `SpaFallback` untouched. | +| P9 | Compression scoping | NFR-CP-01..03 | `UseWhen(path is not reserved)` around `UseResponseCompression`; gzip provider only, MIME list from the requirements. | + +## Pipeline placement +Security headers stay first (inside the exception handler). The website stage sits where `UseCmsStaticContent` is today, the 404 stage after `MapSentryTunnel`, replacing the catch-all website fallback in this mode. + +## Behind the proxy Pi +The proxy forwards plain HTTP/1.0 to the app port. `UseHttpsRedirection` finds no HTTPS port and does nothing; website redirects are relative (`Location: /over-mij`), so no scheme or host is ever constructed. HSTS is still sent by the host (non-Development), as nginx does. + +## Open verification items (settled by tests in Code Generation) +1. No HTTPS-redirect loop or absolute `http://` redirect with a plain HTTP request. +2. Rate limiter default policy does not throttle website assets (check `AddCmsRateLimiting`). +3. `HEAD` requests behave like `GET` without body. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-requirements/nfr-requirements.md b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-requirements/nfr-requirements.md new file mode 100644 index 0000000..5ec265d --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-requirements/nfr-requirements.md @@ -0,0 +1,56 @@ +# NFR Requirements - core-site-hosting (U1) + +## Scalability +- NFR-SC-01: one small site on one Raspberry Pi behind the proxy Pi; tens of requests per second at most. No horizontal scaling, no shared state, no cache to invalidate. + +## Performance +- NFR-PF-01: a `Resolve` call performs at most **3** file-exists checks (Q3 = A). Asserted by a test with a counting predicate. +- NFR-PF-02: a simple local timing check (resolve + serve a page, many iterations) is run once and recorded in the hand-back note. No hard SLA; the goal is to show no per-request cost worth caching. +- NFR-PF-03: static files are streamed (no full buffering); response compression applies only to the listed text types. +- NFR-PF-04: no load test in U1. (A load test on the Pi was not chosen.) + +## Compression +- NFR-CP-01: **gzip only**, like nginx today (Q1 = A). No Brotli provider is registered. +- NFR-CP-02: types: html, js, css, svg, json, xml, txt; `Vary: Accept-Encoding`; non-reserved paths only. +- NFR-CP-03: compression stays at the ASP.NET default of "not over HTTPS"; the proxy Pi forwards plain HTTP so it applies in practice. + +## Availability and reliability +- NFR-AV-01: a missing or half-delivered `wwwroot/web` never stops the host: website paths answer 404, API and admin keep working. +- NFR-AV-02: no restart needed after a website delivery (per-request file checks, no cache). +- NFR-AV-03: the resolver is total (never throws); file read errors in the middleware become a 404 page plus a warning. +- NFR-AV-04: existing clients (`Api`, `Api.SlpSoftware`) behave exactly as today; their tests stay green. + +## Observability (Q2) +Bryan: "Alleen waarschuwingen en meer op de pi, op productie later bepalen". Implementation: +- NFR-OB-01: the website serving uses a dedicated logger category (`SlpModularCms.Website`). +- NFR-OB-02: 404s and 301s are logged at **Information** on that category; warnings for read errors and a missing `wwwroot/web`. +- NFR-OB-03: levels come from per-environment appsettings: test sets `Information` for that category; default and production stay `Warning`. Production is a later config change, no code change. +- NFR-OB-04: logs contain the sanitised path (control characters removed, length capped), never headers or cookies. + +## Security (Security Baseline, blocking) +| Item | Status | +|---|---| +| Input validation (path traversal, encoded/backslash/NUL, over-long, open redirect) | Compliant by design: single pure function, property-tested (R2-R4, R12) | +| Dotfile exposure | Compliant: R3 refuses dot segments except `.well-known` | +| Secure defaults | Compliant: new settings default to today's behaviour | +| Security headers on every website response | Compliant by R19, tested on page, asset, 301, 404, robots.txt | +| Log injection | Compliant: NFR-OB-04 | +| Secrets in code or config | N/A for U1 (no secrets); setup token is U2 | +| New dependencies | None in production code | +| Authn/authz | N/A for U1 (public static content); API and admin unchanged | +| Rate limiting | Unchanged; website static serving is not limited (same as nginx today) | + +## Maintainability and testing +- NFR-MT-01: all nginx-parity rules in one pure class; the middleware is a thin adapter. +- NFR-MT-02: tests: unit tests per rule R1-R26, integration tests (`WebApplicationFactory`-style) for headers on all response kinds, regression suites of `Api` and `Api.SlpSoftware`. +- NFR-MT-03: docs updated (`WEBSITE_WORKSPACE.md`, `README.md`). + +## Property-based testing (partial: PBT-02, 03, 07, 08, 09) +- PBT-02: policy round trip (configured origins appear in the built CSP and parse back). +- PBT-03: resolver invariants (never throws; `ServeFile` safe paths; `Redirect` targets safe, never end in `/` except `/`, resolving a target never redirects again). +- PBT-07: generators for paths (unicode, encoded, dots, slashes, case variants) kept in a shared test helper. +- PBT-08: failing seeds are printed and a shrunk counterexample is added as a regular unit test. +- PBT-09: a PBT framework is required; see tech-stack-decisions.md. + +## Usability +- N/A (no UI in U1). diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-requirements/tech-stack-decisions.md b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-requirements/tech-stack-decisions.md new file mode 100644 index 0000000..d0c3d9d --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/core-site-hosting/nfr-requirements/tech-stack-decisions.md @@ -0,0 +1,12 @@ +# Tech Stack Decisions - core-site-hosting (U1) + +| # | Decision | Rationale | +|---|---|---| +| T1 | ASP.NET Core built-in `UseResponseCompression` with gzip provider only | Matches nginx; no new package; Q1 = A | +| T2 | Built-in `IFileProvider` (physical, confined to `wwwroot/web`) for the file-exists predicate and streaming | No new package; traversal confinement is a second line of defence behind the resolver | +| T3 | `ILogger` with category `SlpModularCms.Website`, level via `Logging:LogLevel` in appsettings per environment | Q2; production later = config only | +| T4 | Test-only PBT framework **FsCheck.Xunit** (not currently in the repo) added to the Core test project | PBT-09 requires a framework; FsCheck is the standard for xUnit on .NET and is a test-only dependency (no production impact). Version pinned at code generation to a release older than two weeks | +| T5 | `WebApplicationFactory`-based integration tests (or the existing test host pattern used by `Api` tests) | Verify headers and pipeline order end to end | +| T6 | No new production NuGet packages | Smaller supply-chain surface (Security Baseline) | + +**Flag for approval**: T4 adds a new test dependency; if you prefer a different PBT library, say so now. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-code-generation-plan.md b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-code-generation-plan.md new file mode 100644 index 0000000..a2da5e5 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-code-generation-plan.md @@ -0,0 +1,31 @@ +# Code Generation Plan - core-site-hosting (U1) + +Single source of truth for U1 code generation. Brownfield: modify in place. Application code under `src/`; docs summary under `construction/core-site-hosting/code/`. + +## Unit context +- Implements FR-U1-01..11 (requirements.md); rules R1-R26 (functional design); NFR-* and patterns P1-P9 (NFR design). +- No user stories (skipped). No database, no frontend, no deployment change (U1 Infrastructure Design skipped, confirmed by CMS & API). +- Depends on: existing `Core` hosting (`CmsHost`, `StaticContentExtensions`, security headers). Consumed later by U2 (`Api.AndreaSlopFotografie`). +- Test project: `src/SlpModularCms.Core.Tests` (xunit, FluentAssertions, NSubstitute). New test-only packages: `Microsoft.AspNetCore.TestHost` (in-memory server, no MariaDB needed) and `FsCheck.Xunit` (PBT-09); versions pinned to releases older than two weeks. +- Verified while planning: the rate limiter is endpoint-policy based (`login` etc.), so website files are not throttled (NFR design verification item 2). + +## Steps +- [x] **Step 1 - Options and mode.** `src/SlpModularCms.Core/Hosting/CmsHostOptions.cs`: add `WebsiteMode` enum and `WebsiteMode` property (default `SpaFallback`). Add `Website/WebsiteOptions.cs` (`NoIndex`). +- [x] **Step 2 - Pure resolver.** `Website/WebsiteResolution.cs`, `Website/WebsitePathResolver.cs` implementing R1-R14 (incl. R3 dot segments, R11 trailing-slash redirect, `IsReservedPath`), max 3 predicate calls (P4). +- [x] **Step 3 - Resolver tests.** `Website/WebsitePathResolverTests.cs` (example tests per rule, call-count test) and `Website/WebsitePathResolverPropertyTests.cs` (FsCheck: PBT-03 invariants, idempotence; shared generators, PBT-07; seed logging, PBT-08). Add package references. +- [x] **Step 4 - StrictSite policy.** `CspPolicyCatalog`: `StrictSite` constant, `KnownPolicies`, `Build` overload with site origin lists, exact directive order (R24-R26). `SecurityHeadersOptions`: `AllowedSiteScriptOrigins`, `AllowedSiteConnectOrigins`; `SecurityHeadersExtensions`: origin validation including the new lists; `CspPolicyProvider` passes the lists. Existing call sites compile unchanged. +- [x] **Step 5 - Policy tests.** Extend `CspPolicyCatalogTests` and `SecurityHeadersOptionsValidationTests`: byte-for-byte site CSP with the real origins, `Strict`/`Relaxed` unchanged, unknown names still fail, invalid site origins fail; PBT-02 round trip. +- [x] **Step 6 - Header forcing (P5).** `SecurityHeaderWriter.Apply(..., alwaysSendDocumentHeaders = false)`; `SecurityHeadersMiddleware` sets it for non-reserved paths when `WebsiteMode.PrerenderedPages`. Needs the mode in the middleware: register a small `WebsiteHostingMarker` (singleton) from `AddCmsWebsite`. Writer tests for the flag. +- [x] **Step 7 - File access.** `Website/WebsiteFileAccess.cs`: physical provider rooted at `wwwroot/web`, `Exists`, `Open`, fail-soft with logging (P2, P3), log path sanitiser (NFR-OB-04). +- [x] **Step 8 - Middleware and wiring.** `Website/PrerenderedSiteMiddleware.cs` (R15-R18, R22, caching, robots, noindex, logging), `Website/WebsiteNotFoundMiddleware.cs` (R20-R21), `Website/PrerenderedSiteExtensions.cs` (`AddCmsWebsite` with gzip-only compression and options validation; `UseCmsPrerenderedSite`; `UseCmsWebsiteNotFound`). `CmsHost` and `StaticContentExtensions`: branch on `WebsiteMode`; `SpaFallback` path untouched; pipeline order documented in `CmsHost`. +- [x] **Step 9 - Integration tests.** `Website/PrerenderedSiteIntegrationTests.cs` with an in-memory `TestServer` host composing the real security-header and website extensions over a temp `wwwroot/web`: pages, canonical 301s, trailing slash, assets (immutable), `no-cache`, 404 page with status 404, missing `404.html`, dotfiles and `.well-known`, reserved prefixes untouched (an unknown `/api/v1/x` stays a non-website 404), robots/noindex, full header set on page, asset, 301, 404, robots.txt (Q1 = A), gzip only, HEAD, no HTTPS-redirect loop on plain HTTP, missing `wwwroot/web` keeps host alive. Includes a local timing check (NFR-PF-02) printed to the test output. +- [x] **Step 10 - Regression.** Run the full `Core.Tests`, `Modules.*.Tests` and `Api.Tests`/`Api.SlpSoftware` suites (the ones needing MariaDB are run if a local DB is reachable, otherwise reported as not runnable with the reason). +- [x] **Step 11 - Documentation.** Update `WEBSITE_WORKSPACE.md` and `README.md` (mode, settings `Website:NoIndex`, `SecurityHeaders:AllowedSite*Origins`, `StrictSite`, logging category, behaviour table); mirror nothing in `AGENTS.md` (structure unchanged). Write `construction/core-site-hosting/code/code-summary.md`. +- [x] **Step 12 - Build and test (Step 13.5).** `dotnet build SlpModularCms.sln`, run all U1 tests, fix until green. +- [x] **Step 13 - Commit.** One commit on `feature/andreaslop-site-hosting` for U1 code (aidlc-docs committed separately or with it per repo habit); no push. + +## Deployment artifacts +None in U1 (config samples for the Andrea client belong to U2). + +## Story traceability +No stories (skipped by decision Q6). Traceability to requirements: Step 1 FR-U1-01; Step 2-3 FR-U1-02..04; Step 4-6 FR-U1-08..09; Step 7-8 FR-U1-03..07, 10; Step 11 FR-U1-11. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-fd-questions.md b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-fd-questions.md new file mode 100644 index 0000000..c5ef4c5 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-fd-questions.md @@ -0,0 +1,20 @@ +# Functional Design Questions - core-site-hosting (U1) + +## Question 1: Security headers on non-HTML website responses +nginx sends the full header set (CSP, HSTS, nosniff, X-Frame-Options, Referrer-Policy and, on test, X-Robots-Tag) on every response, including assets, 301 redirects, robots.txt and the 404 page. The current host writer treats CSP, X-Frame-Options and Referrer-Policy as "HTML-only" headers. For website responses in `PrerenderedPages` mode: + +- A) Send the full set on every website response, like nginx (assets, redirects, robots.txt, 404); the site's verify script can then assert identical headers everywhere (recommended) +- B) Keep the current rule: CSP, X-Frame-Options and Referrer-Policy only on HTML responses; HSTS and nosniff on all +- X) Other (please describe after [Answer]: tag below) + +[Answer]: A (relayed via CMS & API: "Volledige set overal") + +## Question 2: Hidden paths (dot segments) +nginx test conf serves any file under the root. Should the host refuse paths with a segment starting with a dot (for example `/.git/config`, `/.env`)? + +- A) Refuse (404) every dot-segment path except `/.well-known/...` (recommended: protects accidental dotfiles in a delivered site, keeps ACME/security.txt possible) +- B) Refuse every dot-segment path without exception +- C) No special rule, same as nginx +- X) Other (please describe after [Answer]: tag below) + +[Answer]: A (relayed via CMS & API: "Weigeren, behalve .well-known") diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-functional-design-plan.md b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-functional-design-plan.md new file mode 100644 index 0000000..6b4d06b --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-functional-design-plan.md @@ -0,0 +1,8 @@ +# Functional Design Plan - core-site-hosting (U1) + +- [x] Analyse unit context (unit-of-work.md, requirements FR-U1-01..11, website repo rules BR-HST, nginx test conf) +- [x] Collect answers to `core-site-hosting-fd-questions.md` +- [x] Generate `business-logic-model.md` (resolution flow, request flow, header rules) +- [x] Generate `business-rules.md` (rule table R1.., decision flow) +- [x] Generate `domain-entities.md` (WebsiteResolution, options, policy header set, config keys) +- [x] No frontend artifacts (U1 has no UI) diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-nfr-design-plan.md b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-nfr-design-plan.md new file mode 100644 index 0000000..0e2034d --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-nfr-design-plan.md @@ -0,0 +1,15 @@ +# NFR Design Plan - core-site-hosting (U1) + +## Steps +- [x] Analyse NFR requirements (nfr-requirements.md, tech-stack-decisions.md) +- [x] Evaluate question categories; no open questions (justification below) +- [x] Generate `nfr-design/nfr-design-patterns.md` +- [x] Generate `nfr-design/logical-components.md` + +## Category evaluation (why no questions) +- Resilience: decided by NFR-AV-01..04 (host never stops, resolver total, read errors become 404 plus warning). No retries or circuit breakers apply to local file access. +- Scalability: NFR-SC-01 (one small site); no scaling mechanism needed. +- Performance: decided by Q3 (call-count test, timing check) and the no-cache decision D3. +- Security: Security Baseline table in nfr-requirements.md; implementation choices follow existing code (`SecurityHeaderWriter`, `PathPolicyResolver`) and have one obvious solution. +- Logical components: no queue, cache or breaker; only in-process classes. The one real design choice (how to force the full header set on website responses) follows from the existing writer and Q1 = A; it is documented and can be changed at the approval step. +- Risk 2 from application design (HTTPS redirection behind the proxy Pi): inspected; the existing `UseHttpsRedirection` is a no-op without an HTTPS port, same as `Api.SlpSoftware` today; verified by an integration test in code generation. diff --git a/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-nfr-requirements-plan.md b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-nfr-requirements-plan.md new file mode 100644 index 0000000..27c961c --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/construction/plans/core-site-hosting-nfr-requirements-plan.md @@ -0,0 +1,40 @@ +# NFR Requirements Plan - core-site-hosting (U1) + +## Steps +- [x] Analyse functional design (business-rules R1-R26, flows, entities) +- [x] Collect answers to the questions below +- [x] Generate `nfr-requirements/nfr-requirements.md` +- [x] Generate `nfr-requirements/tech-stack-decisions.md` +- [x] Security Baseline and PBT applicability check (tabulated in the artifacts) + +## Pre-filled assumptions (tell me if wrong, via Other on the last question) +- Scale: one small site on one Raspberry Pi behind the proxy Pi; tens of requests per second at most. +- Availability: same as the host today; a missing or half-delivered `wwwroot/web` must never stop the host (website paths 404, API and admin keep working). +- Security: Security Baseline applies (path validation in the resolver, secure defaults, no new dependencies); compression stays off for TLS-terminated traffic by default is irrelevant because the proxy Pi forwards plain HTTP. +- Tech stack: built-in ASP.NET Core only (no new NuGet packages), xUnit and FsCheck if already used in the repo for PBT. + +## Question 1: Compression algorithms +nginx today uses gzip only. ASP.NET Core can also do Brotli. + +- A) gzip only, same as nginx today (simplest, identical behaviour for the verify script) (recommended) +- B) Brotli and gzip (smaller responses; the site's verify script must then accept `br`) +- X) Other (please describe after [Answer]: tag below) + +[Answer]: A (relayed via CMS & API: "Alleen gzip") + +## Question 2: Observability of website traffic +- A) Log nothing extra per request; log only warnings (file read errors, missing `wwwroot/web` at startup once) (recommended, no log noise on a small Pi) +- B) Also log each 404 and each 301 at Information level (useful to spot broken links, noisy with crawlers) +- X) Other (please describe after [Answer]: tag below) + +[Answer]: Relayed via CMS & API, Bryan verbatim: "Alleen waarschuwingen en meer op de pi, op productie later bepalen". Interpretation (to be confirmed by approval): dedicated logger category, 404/301 at Information, level per environment (test = Information, default/production = Warning). + +## Question 3: Performance verification +Per-request `File.Exists` has no cache (design decision). How much proof do you want that this is fast enough? + +- A) A unit/integration test asserting no unbounded work (a resolve does at most 3 file-exists calls) plus a simple local timing check recorded in the hand-back (recommended) +- B) Only the file-exists-call-count test, no timing check +- C) A load test against the test Pi after deploy (extra work in U2) +- X) Other (please describe after [Answer]: tag below) + +[Answer]: A (relayed via CMS & API: "Aantaltest plus lokale tijdmeting") diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/application-design.md b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/application-design.md new file mode 100644 index 0000000..f138a97 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/application-design.md @@ -0,0 +1,28 @@ +# Application Design (consolidated) - andreaslop-site-hosting + +Details: `components.md`, `component-methods.md`, `services.md`, `component-dependency.md`. + +## Decisions +| # | Decision | Source | +|---|---|---| +| D1 | `CmsHostOptions.WebsiteMode` (`SpaFallback` default, `PrerenderedPages`); existing clients unchanged | Brief, FR-U1-01 | +| D2 | All nginx-parity rules live in one pure `WebsitePathResolver` taking a file-exists predicate; the middleware is a thin adapter | Requirements FR-U1-02 | +| D3 | A page is "known" by a per-request file-exists check on the lowercased name; no cache, no restart needed after a site delivery | Q2 = A | +| D4 | `StrictSite` policy in `CspPolicyCatalog`, byte-identical to the site's current CSP; origins from new `AllowedSiteScriptOrigins` / `AllowedSiteConnectOrigins`, so admin policies stay as strict as today | Q1 = A | +| D5 | Compression only for non-reserved paths; `/api/v1` and `/admin` not compressed by this feature | Requirements open point 5 | +| D6 | Unknown website paths get `404.html` with status 404 in a final pipeline stage after API routes; an unknown `/api/v1` path stays an API 404 | FR-U1-03/04/10 | +| D7 | Setup token: `Identity:Setup:Token` optional, header `X-Setup-Token`, constant-time compare, `GET /Setup/status` returns `tokenRequired`, setup page shows the field only when required | Q3 = A, FR-U2-07 | +| D8 | Theme is a build-time CSS override of existing tokens (`VITE_THEME`), language default via `VITE_DEFAULT_LANGUAGE`; no runtime theme API | Brief D2, Q5 | +| D9 | Module set of the Andrea client = its project references; `Availability` included only if the admin needs it (decided in U2 NFR/Code Generation, reported to the requester) | Brief D1 | +| D10 | Unit order: U1 Core (with regression run), hand-back and wait for the requester's "go", then U2 | Brief, execution plan | + +## Risks carried into Construction +1. The existing security-header writer treats CSP/frame/referrer as HTML-only; website 301/asset/robots responses may need the full set (FR-U1-09). Settled in U1 Functional Design with tests. +2. `UseHttpsRedirection` on plain HTTP behind the proxy Pi, and absent forwarded-headers handling: verify no loop or absolute `http://` redirect (website redirects are relative). +3. Per-request `File.Exists` on a Pi SD card or `/mnt/storage1`: low cost expected; measured in U1 NFR Design. +4. Setup endpoints and rate limiting: confirm the login limiter covers `/Setup/owner` (NFR Design U2). +5. Frontend setup page change touches an existing screen (small, covered by tests). + +## Security Baseline / PBT applicability (design stage) +- Security: path input validation centralised in one pure function; secure-by-default configuration (new settings default to today's behaviour); no secrets in repo (token and DB password come from the environment); constant-time token compare; no new dependencies. Compliant / N/A items are tabulated in the NFR stages. +- PBT (partial): the resolver (PBT-02/03 invariants), canonical idempotence, policy round trip are pure and directly testable. diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/component-dependency.md b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/component-dependency.md new file mode 100644 index 0000000..28ce2a3 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/component-dependency.md @@ -0,0 +1,63 @@ +# Component Dependencies - andreaslop-site-hosting + +## Dependency matrix (row depends on column) + +| | Core hosting | Security (CSP) | Identity | Frontend | CI/CD | +|---|---|---|---|---|---| +| C2 WebsiteMode | - | | | | | +| C3 Site serving | uses | uses (headers precede it) | | | | +| C4 StrictSite | | - | | | | +| C1 Andrea client | references | configures | references | consumes built admin | built by | +| C5 Theme | | | | - | selected by | +| C7 Setup token | | | - (in module) | setup page | | +| C6 CI/CD | | | | builds | - | + +- C3a (pure resolver) depends on nothing but `System`; the predicate is injected. This keeps property-based testing trivial and keeps traversal safety in one testable place. +- `Api` and `Api.SlpSoftware` depend on Core only through unchanged defaults (`WebsiteMode.SpaFallback`, empty site origin lists, no setup token configured). + +```mermaid +graph TD + opts["CmsHostOptions.WebsiteMode (C2)"] + host["CmsHost / StaticContentExtensions"] + mw["PrerenderedSiteMiddleware (C3c)"] + res["WebsitePathResolver (C3a, pure)"] + wopt["WebsiteOptions (C3b)"] + csp["CspPolicyCatalog + SecurityHeadersOptions (C4)"] + sethdr["SecurityHeadersMiddleware"] + ident["Identity: SetupController + ISetupTokenValidator (C7)"] + client["Api.AndreaSlopFotografie (C1)"] + fe["frontend theme + setup page (C5, C7)"] + ci["Gitea workflows (C6)"] + + host --> opts + host --> mw + mw --> res + mw --> wopt + host --> sethdr + sethdr --> csp + client --> host + client --> ident + client --> csp + fe --> ident + ci --> client + ci --> fe + + classDef core fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; + classDef pure fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; + classDef newc fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000; + classDef ext fill:#d6bcfa,stroke:#553c9a,stroke-width:1px,color:#000; + class opts,host,mw,wopt,sethdr,csp core; + class res pure; + class client,ident,fe newc; + class ci ext; +``` + +Text alternative: the host wires the options, the site middleware and the security-header middleware; the middleware depends on the pure resolver; the Andrea client references host and Identity and configures the policy; the frontend and CI build the client. + +## Communication patterns +- In-process only; no new network calls from the host. +- Website to API: browser calls same-origin `/api/v1` where needed; Sentry and Umami origins are called directly by the site (listed in `StrictSite`). +- Configuration is the only coupling between a client and a policy: `DefaultPolicy`, `PathPolicies`, `AllowedSite*Origins`, `Website:NoIndex`, `Identity:Setup:Token`. + +## Delivery coupling (website files) +`wwwroot/web` is owned by the website delivery (web CI or a symlink to `/mnt/storage1/www/html/andreaslop-test`); the host only reads it. Because pages are resolved per request without cache (Q2=A), both delivery variants work without restart. diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/component-methods.md b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/component-methods.md new file mode 100644 index 0000000..4254026 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/component-methods.md @@ -0,0 +1,72 @@ +# Component Methods - andreaslop-site-hosting + +Signatures are indicative; business rules are detailed in U1 Functional Design. + +## Core - hosting +```csharp +public enum WebsiteMode { SpaFallback = 0, PrerenderedPages = 1 } + +public sealed class CmsHostOptions { public WebsiteMode WebsiteMode { get; init; } = WebsiteMode.SpaFallback; } +``` + +## C3a WebsitePathResolver +```csharp +public abstract record WebsiteResolution +{ + public sealed record ServeFile(string RelativePath, bool IsNotFoundPage = false) : WebsiteResolution; + public sealed record Redirect(string Location) : WebsiteResolution; // always 301, relative Location + public sealed record NotFound : WebsiteResolution; +} + +public static class WebsitePathResolver +{ + // Total: never throws, never returns a path outside the website root. + // fileExists receives a relative, forward-slash, already-validated candidate ("over-mij.html"). + public static WebsiteResolution Resolve(string? rawPath, string? queryString, Func fileExists); + public static bool IsReservedPath(string? rawPath); // /admin, /api/v1, /health (whole segments, case-insensitive) +} +``` + +## C3b/C3c Website serving +```csharp +public sealed class WebsiteOptions { public const string SectionName = "Website"; public bool NoIndex { get; set; } } + +public static class PrerenderedSiteExtensions +{ + public static IServiceCollection AddCmsWebsite(this IServiceCollection s, IConfiguration c); // options + validation + compression + public static WebApplication UseCmsPrerenderedSite(this WebApplication app); // compression (UseWhen), noindex, resolver middleware +} + +public sealed class PrerenderedSiteMiddleware(RequestDelegate next, IWebHostEnvironment env, IOptions options) +{ + public Task InvokeAsync(HttpContext context); +} +``` +`StaticContentExtensions.UseCmsStaticContent` / `MapCmsSpaFallbacks` branch on `WebsiteMode`: in `PrerenderedPages` they register the admin mount and the `/admin` fallback only, the website mount is `UseCmsPrerenderedSite`, and the catch-all website fallback is replaced by the middleware's 404 handling placed after API routes. + +## C4 Security +```csharp +public static class CspPolicyCatalog +{ + public const string StrictSite = "StrictSite"; + public static SecurityHeaderSet Build(string policy, + IEnumerable allowedScriptOrigins, IEnumerable allowedConnectOrigins, + IEnumerable? siteScriptOrigins = null, IEnumerable? siteConnectOrigins = null); +} +public sealed class SecurityHeadersOptions { /* + */ public IList AllowedSiteScriptOrigins { get; set; } = []; public IList AllowedSiteConnectOrigins { get; set; } = []; } +``` +Existing call sites keep compiling (new parameters optional). + +## C7 Setup token +```csharp +public sealed class SetupOptions { public const string SectionName = "Identity:Setup"; public string? Token { get; set; } } +public interface ISetupTokenValidator { bool IsRequired { get; } bool IsValid(string? presentedToken); } // fixed-time comparison +// SetupController +// GET /Setup/status -> { initialized, tokenRequired } +// POST /Setup/owner -> 401/403 problem details when token required and missing/wrong; header X-Setup-Token +``` + +## Frontend +- `theme.ts`/Vite plugin: resolves `VITE_THEME` to `themes//theme.css` import (no-op when unset). +- `i18n init`: `lng = stored ?? import.meta.env.VITE_DEFAULT_LANGUAGE ?? browser default`. +- Setup page: optional `setupToken` field; API client adds `X-Setup-Token` header. diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/components.md b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/components.md new file mode 100644 index 0000000..b3fb26e --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/components.md @@ -0,0 +1,39 @@ +# Components - andreaslop-site-hosting + +Numbering follows the brief (C1-C6); C7 is added by this design (setup token, requirements FR-U2-07). + +## C2 WebsiteMode option (Core, `SlpModularCms.Core.Hosting`) +- **Purpose**: Per-client choice of how the public website is served. +- **Responsibilities**: `enum WebsiteMode { SpaFallback, PrerenderedPages }`; property `CmsHostOptions.WebsiteMode` (default `SpaFallback`). +- **Interface**: read by `CmsHost.ConfigureServices/ConfigurePipeline` and `StaticContentExtensions`. + +## C3 Prerendered site serving (Core, `SlpModularCms.Core.Hosting.Website`, new folder) +Active only when `WebsiteMode = PrerenderedPages`. + +| Part | Kind | Responsibility | +|---|---|---| +| C3a `WebsitePathResolver` | static, pure | Total function: (raw path, query string, `Func fileExists`) -> `WebsiteResolution` (`ServeFile(relativePath)`, `Redirect(location)`, `NotFound`). Contains every nginx-parity rule (canonical form, trailing slash, `/index`, traversal and backslash rejection, file-looking paths, reserved prefixes). No I/O, no clock, no logging. | +| C3b `WebsiteOptions` | options | `Website:NoIndex` (default false), validated at startup. | +| C3c `PrerenderedSiteMiddleware` | middleware | Adapter between HTTP and the resolver: supplies the file-exists predicate (confined to `wwwroot/web`), writes status, `Location`, `Cache-Control`, `X-Robots-Tag`, streams the file, serves `404.html` with status 404, answers `/robots.txt` when `NoIndex`. Never handles reserved prefixes. | +| C3d Website compression | registration | Built-in response compression for the text MIME types, applied only to non-reserved paths (`UseWhen`), so `/api/v1` and `/admin` responses are never compressed by this feature. | + +## C4 StrictSite policy (Core, `SlpModularCms.Core.Hosting.Security`) +- **Purpose**: A third CSP policy for a prerendered public site, reproducing the site's current header byte for byte. +- **Responsibilities**: `CspPolicyCatalog.StrictSite` constant, added to `KnownPolicies`; `Build` produces the site CSP with `X-Frame-Options: DENY` and `Referrer-Policy: strict-origin-when-cross-origin`; `SecurityHeadersOptions` gains `AllowedSiteScriptOrigins` and `AllowedSiteConnectOrigins`, used **only** by `StrictSite` (decision Q1=A). `Strict` and `Relaxed` outputs are unchanged. +- **Check**: HSTS, `X-Content-Type-Options`, `Referrer-Policy` and the CSP appear on website pages, assets, 301s, 404 and robots.txt (FR-U1-09). The existing writer emits CSP/frame/referrer as "HTML-only" headers; whether non-HTML website responses also need them is settled in U1 Functional Design. + +## C1 Client `SlpModularCms.Api.AndreaSlopFotografie` (Clients) +- **Purpose**: Deployable host for Andrea's instance. +- **Responsibilities**: thin `Program.cs` on `CmsHost` with `WebsiteMode.PrerenderedPages`; `.csproj` references the modules (Core, Identity, and Availability only if the admin needs it); three-file appsettings; own database connection string template (no password in repo); own dev port; `SecurityHeaders:DefaultPolicy = StrictSite` plus the site origin lists; `Website:NoIndex = true` for test. + +## C5 Admin theme (frontend) +- **Purpose**: Per-site look of the admin, fixed at build time. +- **Responsibilities**: `frontend/themes//theme.css` overriding existing design tokens; theme assets (logo, favicon, self-hosted Marcellus and Jost); build-time selection by `VITE_THEME`; `VITE_DEFAULT_LANGUAGE` initial language (user choice still wins); unset variables reproduce today's admin. + +## C6 CI/CD (Gitea workflows) +- **Purpose**: Build and deploy each client with its own admin build. +- **Responsibilities**: per-client admin build (`VITE_THEME`, `VITE_DEFAULT_LANGUAGE`, `VITE_APP_TITLE`), ARM64 publish of the new host, deploy to the test Pi using the existing atomic release switch, `wwwroot/web` outside the release directory; production path of `Api.SlpSoftware` untouched. + +## C7 First-admin setup token (Identity module + frontend) +- **Purpose**: Stop a stranger from claiming the first administrator on a freshly deployed, publicly reachable instance. +- **Responsibilities**: `SetupOptions` (`Identity:Setup:Token`, optional); `ISetupTokenValidator` (constant-time compare, true when no token is configured); `SetupController.GetStatus` returns `tokenRequired`; `CreateOwner` requires header `X-Setup-Token` when configured; setup page in the frontend shows a token field only when `tokenRequired` is true (decision Q3=A). Existing hosts without the setting behave exactly as before. diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/services.md b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/services.md new file mode 100644 index 0000000..fba4b45 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/services.md @@ -0,0 +1,66 @@ +# Services and Orchestration - andreaslop-site-hosting + +No new domain services or database tables. Orchestration is host composition and one request pipeline. + +## Host composition (`CmsHost`) +- `ConfigureServices`: `AddCmsSecurityHeaders` (now with site origin lists), `AddCmsWebsite` (only when `WebsiteMode = PrerenderedPages`). Identity registers `SetupOptions` and `ISetupTokenValidator` in its own module registration. +- `ConfigurePipeline` order (documented in `CmsHost`): + +```mermaid +flowchart TD + A["Exception handler"] --> B["Security headers"] + B --> C["Rate limiter"] + C --> D["HTTPS redirection (no-op on plain HTTP)"] + D --> E["Admin static mount + /admin redirect"] + E --> F["Website: compression (non-reserved paths) + noindex"] + F --> G["Website resolver middleware (pages, assets, redirects, robots)"] + G --> H["CORS, module middleware, auth"] + H --> I["MapControllers (/api/v1)"] + I --> J["Health checks, Sentry tunnel"] + J --> K["Admin SPA fallback"] + K --> L["Website 404 (404.html, status 404)"] + + classDef sec fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000; + classDef site fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; + classDef api fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; + class A,B,C,D sec; + class E,F,G,K,L site; + class H,I,J api; +``` + +Text alternative: security stages first (yellow), then the admin and website mounts (blue), then API routes (green); unknown website paths fall to 404 last, so API 404s are never replaced by the website page. + +Notes: +- The resolver middleware passes reserved prefixes (`/admin`, `/api/v1`, `/health`) straight on, and passes on unknown paths **only** after API routes had a chance; the final 404 stage serves `404.html` with status 404 for non-reserved paths. Pages that resolve (`ServeFile`, `Redirect`) are answered in step G, before the API; this is safe because the pure resolver never resolves reserved prefixes. +- `SpaFallback` mode keeps today's pipeline untouched. + +## Request flow (website page) +```mermaid +sequenceDiagram + box rgba(246,224,94,0.4) Client + participant B as Browser or proxy Pi + end + box rgba(99,179,237,0.4) Host + participant M as SiteMiddleware + participant R as PathResolver + participant F as wwwroot web + end + B->>M: GET /Over-Mij?x=1 + M->>R: Resolve path, query, fileExists + R->>F: fileExists over-mij.html + F-->>R: true + R-->>M: Redirect /over-mij?x=1 + M-->>B: 301 Location /over-mij?x=1 plus security headers + B->>M: GET /over-mij + M->>R: Resolve + R-->>M: ServeFile over-mij.html + M-->>B: 200 html, no-cache, compressed +``` + +Text alternative: the middleware asks the pure resolver, which uses a file-exists check; a non-canonical request gets one 301, then the canonical request is served as a file. + +## Setup flow +Browser loads setup page -> `GET /Setup/status` -> `tokenRequired` decides whether the token field is shown -> `POST /Setup/owner` with `X-Setup-Token` -> `ISetupTokenValidator` -> existing `ISetupService.CreateInitialOwnerAsync`. Login rate limiting policy also covers the setup endpoints (verified in NFR Design). + +## Build and deploy flow (C6) +CI: admin build per client (env: theme, language, title) -> copy into client `wwwroot/admin` -> `dotnet publish` (linux-arm64) -> scp to `releases/` -> atomic switch of `current` -> restart user unit -> smoke checks (`/health`, `/api/v1/System/capabilities`, a website page). `wwwroot/web` is a symlink in `shared/`, so it survives every release. diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work-dependency.md b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work-dependency.md new file mode 100644 index 0000000..a4e696a --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work-dependency.md @@ -0,0 +1,22 @@ +# Unit Dependencies - andreaslop-site-hosting + +| Unit | Depends on | Reason | +|---|---|---| +| U1 | existing Core | extends it additively | +| U2 | U1 | client uses `WebsiteMode.PrerenderedPages`, `StrictSite`, `Website:NoIndex` | +| U2 | requester "go" | hand-back gate | + +```mermaid +flowchart LR + U1["U1 core-site-hosting"] --> H1["Hand-back + go from CMS & API"] --> U2["U2 andreaslop-client"] --> BT["Build and Test"] --> OP["Operations"] + classDef u fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000; + classDef g fill:#d6bcfa,stroke:#553c9a,stroke-width:1px,color:#000; + classDef n fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; + class U1,U2 u; + class H1 g; + class BT,OP n; +``` + +Text alternative: U1, then the hand-back gate, then U2, then Build and Test and Operations. + +Shared contract between units: configuration names (`WebsiteMode` in code, `Website:NoIndex`, `SecurityHeaders:DefaultPolicy=StrictSite`, `SecurityHeaders:AllowedSiteScriptOrigins`, `SecurityHeaders:AllowedSiteConnectOrigins`). U1 fixes these names; U2 only uses them. diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work-story-map.md b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work-story-map.md new file mode 100644 index 0000000..0a328bf --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work-story-map.md @@ -0,0 +1,13 @@ +# Requirement-to-Unit Map (User Stories skipped) + +| Requirement | Unit | +|---|---| +| FR-U1-01 .. FR-U1-11 | U1 | +| FR-U2-01 client project, FR-U2-02 module set | U2 | +| FR-U2-03 theme | U2 | +| FR-U2-04 CI/CD, FR-U2-05 test deploy, FR-U2-06 Pi provisioning | U2 | +| FR-U2-07 setup token, FR-U2-08 auth unchanged | U2 | +| Security Baseline, PBT partial, per-unit build/test | both | +| Git rules (one branch, no push, PR after U2) | both | + +All requirements are assigned to a unit. diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work.md b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work.md new file mode 100644 index 0000000..0a384bf --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/application-design/unit-of-work.md @@ -0,0 +1,22 @@ +# Units of Work - andreaslop-site-hosting + +Terminology: both units are changes to the same deployable codebase ("Unit of Work" = planning/delivery slice), delivered on one branch, commits per unit. + +## U1 core-site-hosting +- **Scope**: C2 WebsiteMode, C3 prerendered site serving (resolver, middleware, options, compression), C4 StrictSite policy and site origin lists, pipeline order, docs (`README.md`, `WEBSITE_WORKSPACE.md`). +- **Code locations**: `src/SlpModularCms.Core/Hosting/**` (+ `src/SlpModularCms.Core.Tests/**`). +- **Not touched**: `Api`, `Api.SlpSoftware` sources (only regression-tested), Identity, frontend, CI. +- **Construction stages**: Functional Design, NFR Requirements, NFR Design, Code Generation (Infrastructure Design skipped). +- **Done when**: requirements acceptance (U1) met, per-unit build and tests green, `Api`/`Api.SlpSoftware` regression green, hand-back note sent, **requester's "go" received**. +- **Commit(s)**: on `feature/andreaslop-site-hosting`; no push. + +## U2 andreaslop-client +- **Scope**: C1 client project and solution entry (Clients), C5 theme and build variables, C7 setup token (Identity + setup page), C6 CI/CD, Pi manual-step list, test deploy (with Bryan's go, test only). +- **Code locations**: `src/SlpModularCms.Api.AndreaSlopFotografie/**`, `src/SlpModularCms.Modules.Identity/**` (+ tests), `frontend/**`, `.gitea/workflows/**`, `SlpModularCms.sln`, docs. +- **Construction stages**: NFR Requirements, NFR Design, Infrastructure Design, Code Generation (Functional Design skipped). +- **Starts**: only after U1 hand-back and the requester's "go". +- **Done when**: requirements acceptance (U2) met, hand-back note sent. +- **Commit(s)**: same branch; one PR after U2 when Bryan asks. + +## Cross-unit +Build and Test (all units), then Operations (Deployment Setup, Monitoring Setup, Production Readiness for the test environment). diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/plans/application-design-plan.md b/aidlc-docs/features/andreaslop-site-hosting/inception/plans/application-design-plan.md new file mode 100644 index 0000000..cb469c0 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/plans/application-design-plan.md @@ -0,0 +1,46 @@ +# Application Design Plan - andreaslop-site-hosting + +## Steps +- [x] Analyse requirements and host code (done: CmsHost, StaticContentExtensions, CspPolicyCatalog, SecurityHeadersOptions, SetupController) +- [x] Collect answers to the design questions below +- [x] Generate components.md +- [x] Generate component-methods.md +- [x] Generate services.md +- [x] Generate component-dependency.md +- [x] Generate application-design.md (consolidated) +- [x] Validate completeness and consistency (security baseline / PBT applicability) + +## Facts from the code that shape the questions +- `SecurityHeadersOptions.AllowedConnectOrigins` is applied to **both** `Strict` and `Relaxed`. If the Umami and Sentry origins were put there for Andrea's site, the admin (`/admin`, `/api/v1`, under `Strict`) would get them too. `AllowedScriptOrigins` is only used by `Relaxed` today. +- Linux file systems are case-sensitive, and all page files are lowercase. A request `/Over-Mij` therefore resolves to a known page exactly when `over-mij.html` exists. A cached "known page set" is not strictly needed: a file-exists predicate on the lowercased name gives the same nginx behaviour. +- `UseHttpsRedirection` is a no-op when the host listens on plain HTTP only without an HTTPS port configured; the proxy Pi talks HTTP to the app. There is no forwarded-headers handling in `CmsHost` today. To be verified in NFR Design against the SlpSoftware deployment. +- `SetupController` (`GET /Setup/status`, `POST /Setup/owner`) has no protection other than "system not yet initialised". The admin setup page posts to it. + +## Design Questions + +### Question 1: Origins for the StrictSite policy +Where do the Umami script origin and the Sentry connect origins for the website live? + +- A) New separate lists in `SecurityHeaders` (for example `AllowedSiteScriptOrigins`, `AllowedSiteConnectOrigins`) used only by `StrictSite`; the admin policies stay exactly as strict as today (recommended) +- B) Reuse the existing `AllowedScriptOrigins` / `AllowedConnectOrigins`; accept that `Strict` (admin and API) then also lists the Sentry ingest origin in `connect-src` +- X) Other (please describe after [Answer]: tag below) + +[Answer]: A (RELAYED by CMS & API on Bryan's behalf; confirmed when Bryan approves the design) + +### Question 2: How the host decides a page is "known" +nginx canonicalises (301) only known pages. How should the host decide this? + +- A) Per request, a file-exists check on the lowercased name (`.html`, or `/index.html`); no cache, so a site delivered in place (symlink variant, rsync) is always current. The pure resolver takes the check as a predicate (recommended) +- B) A snapshot of the known pages built at startup and refreshed on a short timer or file watcher +- X) Other (please describe after [Answer]: tag below) + +[Answer]: A (RELAYED by CMS & API on Bryan's behalf; confirmed when Bryan approves the design) + +### Question 3: First-admin setup token in the admin +The setup token protects `POST /Setup/owner`. How does the person doing the first setup supply it? + +- A) The setup page shows a "setup token" field, but only when the server says one is required (`GET /Setup/status` returns `tokenRequired`); the token is sent in a request header; small frontend change, no change when no token is configured (recommended) +- B) No frontend change: the token is sent only as a header by a direct API call (for example curl), the setup page stays as it is +- X) Other (please describe after [Answer]: tag below) + +[Answer]: A (RELAYED by CMS & API on Bryan's behalf; confirmed when Bryan approves the design) diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/plans/execution-plan.md b/aidlc-docs/features/andreaslop-site-hosting/inception/plans/execution-plan.md new file mode 100644 index 0000000..4f92647 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/plans/execution-plan.md @@ -0,0 +1,170 @@ +# Execution Plan - andreaslop-site-hosting + +## Detailed Analysis Summary + +### Transformation Scope (Brownfield) +- **Type**: Extension of the shared host (`SlpModularCms.Core`) plus one new deployable client, an admin theming mechanism and CI/CD for a second deployment target. No rewrite; existing clients (`Api`, `Api.SlpSoftware`) must behave exactly as before. +- **Primary changes**: (U1) `WebsiteMode.PrerenderedPages` with nginx-parity serving, `StrictSite` CSP policy, `Website:NoIndex`; (U2) client `SlpModularCms.Api.AndreaSlopFotografie`, admin theme via `VITE_THEME`/`VITE_DEFAULT_LANGUAGE`, optional first-admin setup token, CI/CD to the test Pi. +- **Related components**: Core (`CmsHost`, `CmsHostOptions`, `StaticContentExtensions`, `CspPolicyCatalog`, security headers), Modules.Identity (setup token), frontend (theme tokens, build), `.gitea/workflows/*`, README / `WEBSITE_WORKSPACE.md`. + +### Change Impact Assessment +- **User-facing changes**: Yes - public website served by the host (visitor), themed Dutch admin (site owner). +- **Structural changes**: Yes - new client project, new options/middleware in Core. +- **Data model changes**: No new entities. New database instance per site (`AndreaSlopFotografieTest`); existing migrations apply. Setup token is configuration, not data. +- **API changes**: Setup endpoint gains an optional token requirement (only when configured). No other API change. +- **NFR impact**: Yes - Security Baseline (blocking), PBT partial, performance of per-request path resolution, proxy/HTTP 1.0 behaviour. + +### Component Relationships + +```mermaid +graph TD + core["SlpModularCms.Core
(CmsHost, StaticContent, CSP catalog)"] + api["SlpModularCms.Api"] + slp["SlpModularCms.Api.SlpSoftware"] + andrea["SlpModularCms.Api.AndreaSlopFotografie
(new client, U2)"] + ident["Modules.Identity
(setup token)"] + avail["Modules.Availability"] + fe["frontend
(theme per site)"] + ci["Gitea workflows
(CI + deploy-scp)"] + pi["Test Pi
(port 5200)"] + + core -->|"unchanged behaviour"| api + core -->|"unchanged behaviour"| slp + core -->|"PrerenderedPages + StrictSite (U1)"| andrea + andrea --> ident + andrea -.->|"only if required"| avail + fe -->|"VITE_THEME=andreaslop"| andrea + ci -->|"build + deploy (test only)"| andrea + andrea --> pi + + classDef shared fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000; + classDef existing fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000; + classDef new fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000; + classDef ext fill:#d6bcfa,stroke:#553c9a,stroke-width:1px,color:#000; + class core shared; + class api,slp,ident,avail,fe existing; + class andrea new; + class ci,pi ext; +``` + +Text alternative: Core serves all clients; the new Andrea client uses the new website mode and policy, references Identity (Availability only if needed), gets a themed admin build and is deployed by CI to the test Pi. + +| Component | Change type | Reason | Priority | +|---|---|---|---| +| Core hosting | Major (additive) | New mode, middleware, policy | Critical | +| Api, Api.SlpSoftware | None (regression-guarded) | Must stay unchanged | Critical | +| Identity | Minor | Optional setup token | Important | +| Frontend | Minor | Theme tokens, language default | Important | +| CI/CD | Minor | Per-client admin build, second deploy target | Important | +| Docs | Minor | README, WEBSITE_WORKSPACE.md | Important | + +### Risk Assessment +- **Risk level**: Medium. Shared host change touches every client (mitigated by default `SpaFallback` and regression tests); public-facing path handling (traversal / open redirect) is security-relevant; deployment on a Pi that is not yet provisioned. +- **Rollback complexity**: Easy for code (feature flag by default off); moderate for the Pi (manual steps by Bryan, test only). +- **Testing complexity**: Complex (PBT on pure functions, integration tests of the pipeline with a temp website root, theme visual/contrast check, deploy smoke test). + +## Workflow Visualization + +```mermaid +flowchart TD + Start(["Brief from CMS & API"]) + + subgraph INCEPTION["INCEPTION PHASE"] + WD["Workspace Detection
COMPLETED"] + RE["Reverse Engineering
SKIP (reuse)"] + RA["Requirements Analysis
COMPLETED"] + US["User Stories
SKIP"] + WP["Workflow Planning
IN PROGRESS"] + AD["Application Design
EXECUTE"] + UG["Units Generation
EXECUTE (minimal)"] + end + + subgraph CONSTRUCTION["CONSTRUCTION PHASE"] + U1["Unit U1 core-site-hosting
FD, NFR Req, NFR Design, Code, per-unit build/test"] + H1["Hand-back U1 + wait for go"] + U2["Unit U2 andreaslop-client
NFR Req, NFR Design, Infra Design, Code, per-unit build/test"] + H2["Hand-back U2"] + BT["Build and Test (all units)
EXECUTE"] + end + + subgraph OPERATIONS["OPERATIONS PHASE"] + DS["Deployment Setup
EXECUTE"] + MS["Monitoring Setup
EXECUTE"] + PRV["Production Readiness Validation
EXECUTE"] + end + + Start --> WD --> RE --> RA --> US --> WP --> AD --> UG --> U1 --> H1 --> U2 --> H2 --> BT --> DS --> MS --> PRV --> End(["Complete"]) + + style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff + style RA fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff + style WP fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff + style BT fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff + style RE fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000 + style US fill:#BDBDBD,stroke:#424242,stroke-width:2px,stroke-dasharray: 5 5,color:#000 + style AD fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 + style UG fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 + style U1 fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 + style U2 fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 + style H1 fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000 + style H2 fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000 + style DS fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 + style MS fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 + style PRV fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray: 5 5,color:#000 + style Start fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000 + style End fill:#CE93D8,stroke:#6A1B9A,stroke-width:3px,color:#000 + linkStyle default stroke:#333,stroke-width:2px +``` + +Text alternative: green = done/always, orange dashed = conditional EXECUTE, grey dashed = SKIP, purple = checkpoints with the requester. + +## Phases to Execute + +### INCEPTION +- [x] Workspace Detection (COMPLETED) +- [x] Reverse Engineering (SKIPPED - existing `_shared/reverse-engineering/` reused; key host files read directly) +- [x] Requirements Analysis (COMPLETED, approved by Bryan) +- [x] User Stories (SKIPPED per Q6) +- [x] Workflow Planning (IN PROGRESS) +- [ ] Application Design - EXECUTE + - **Rationale**: New components (WebsiteMode option, path resolver, prerendered-site middleware, StrictSite policy, client project, theme mechanism, setup-token check). The requester expects Bryan's design approval. +- [ ] Units Generation - EXECUTE (minimal; no separate Units Planning question round) + - **Rationale**: The two units are fixed by the brief. Formalise them (scope, order, dependencies, hand-back gates) in `unit-of-work.md`. + +### CONSTRUCTION (per unit; U2 only after the requester's "go") +**U1 core-site-hosting** +- [ ] Functional Design - EXECUTE: path-resolution rule table, canonical form, known-page set, 404 and reserved-prefix behaviour, noindex/robots rules. +- [ ] NFR Requirements - EXECUTE: security (traversal, open redirect, header completeness), PBT properties (partial mode), performance of lookup, proxy/HTTP 1.0 compatibility. +- [ ] NFR Design - EXECUTE (compact): caching of file existence / known-page refresh, middleware ordering, compression scope. +- [ ] Infrastructure Design - SKIP: no infrastructure change in U1. +- [ ] Code Generation - EXECUTE (plan + generation + automatic per-unit build/test, regression run of `Api`/`Api.SlpSoftware`) +- [ ] Hand-back note U1, message to "CMS & API", **wait for go** + +**U2 andreaslop-client** +- [ ] Functional Design - SKIP: no new business domain; theme token mapping and client composition are covered by Application Design and requirements. +- [ ] NFR Requirements - EXECUTE: setup-token security, secrets handling, contrast/accessibility of the theme, login rate limiting. +- [ ] NFR Design - EXECUTE (compact): token check placement, constant-time compare, configuration shape. +- [ ] Infrastructure Design - EXECUTE: Pi layout, systemd user unit, env variables, database `AndreaSlopFotografieTest` / user `AndreaSlopFotografie`, ufw rule for port 5200, proxy-Pi route, Gitea secrets, both `wwwroot/web` delivery variants, manual-step list for Bryan; then notify "CMS & API" so the Pi-Main session can draft commands. +- [ ] Code Generation - EXECUTE (client, theme, setup token, workflows; per-unit build/test) +- [ ] Test deploy - only with Bryan's go in this session, test host only +- [ ] Hand-back note U2 + +- [ ] Build and Test - EXECUTE (full solution, frontend build per theme, cross-unit integration, smoke checks) + +### OPERATIONS (Operations Configuration = Yes) +- [ ] Deployment Setup - EXECUTE +- [ ] Monitoring Setup - EXECUTE +- [ ] Production Readiness Validation - EXECUTE (for the test environment; production out of scope) + +## Package Change Sequence +1. `SlpModularCms.Core` (+ `Core.Tests`) - U1 +2. `Api` / `Api.SlpSoftware` regression run - U1 +3. `SlpModularCms.Modules.Identity` (+ tests) - setup token (U2) +4. `frontend` theme and build variables - U2 +5. `SlpModularCms.Api.AndreaSlopFotografie` (+ solution entry under Clients) - U2 +6. `.gitea/workflows` (CI matrix per client, deploy to test) - U2 +7. Docs (`README.md`, `WEBSITE_WORKSPACE.md`) - U1 and U2 + +## Success Criteria +- **Primary goal**: Andrea's prerendered site and a themed Dutch admin served by one SlpModularCms process on the test Pi, with behaviour matching today's nginx and the exact CSP. +- **Key deliverables**: WebsiteMode + StrictSite in Core; new client; theme; setup token; CI/CD; hand-back notes; Pi manual-step list. +- **Quality gates**: Security Baseline compliance per stage; PBT-02/03/07/08/09 satisfied; `Api` and `Api.SlpSoftware` green and unchanged; per-unit build/test; requester's "go" before U2; Bryan's approval of requirements and design; no push without Bryan's request; no production changes. diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/plans/unit-of-work-plan.md b/aidlc-docs/features/andreaslop-site-hosting/inception/plans/unit-of-work-plan.md new file mode 100644 index 0000000..e69c004 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/plans/unit-of-work-plan.md @@ -0,0 +1,9 @@ +# Unit of Work Plan - andreaslop-site-hosting + +Decomposition is fixed by the brief and the approved execution plan (two units, U1 then U2, hand-back gate between them). No open decomposition questions: no ambiguity found in story grouping, dependencies, deployment or code organisation (brownfield; structure rules from CLAUDE.md/AGENTS.md apply). + +- [x] Generate `inception/application-design/unit-of-work.md` +- [x] Generate `inception/application-design/unit-of-work-dependency.md` +- [x] Generate `inception/application-design/unit-of-work-story-map.md` (requirements-to-unit map; User Stories were skipped) +- [x] Validate unit boundaries and dependencies +- [x] Ensure every requirement is assigned to a unit diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/pi-inventory-notes.md b/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/pi-inventory-notes.md new file mode 100644 index 0000000..693db1b --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/pi-inventory-notes.md @@ -0,0 +1,27 @@ +# Pi inventory notes (input for Infrastructure Design, U2) + +Source: relayed by session "CMS & API" from session "Pi-Main - Server" (read-only inventory, no sudo, facts not verified by this session). Full write-up in the website repo: `AndreaSlopFotografie-cms-api-foundation/aidlc-docs/features/cms-api-foundation/construction/cms-host/pi-inventory.md`. Status: UNVERIFIED INPUT, to be checked against `.gitea/workflows/deploy-scp.yaml` and confirmed by Bryan. + +## Relayed decision (pending Bryan's confirmation in this session) +- The test instance takes over hostname `test.andreaslop.nl`. Verify first on the Pi via the app port; Bryan then switches the route on the proxy Pi to the new port. nginx on the app Pi stays as fallback. + +## Pattern to copy (SlpSoftware test) +- User `gitea-workflow`; `~/apps//test/{releases,current,shared}`; `shared/env` (mode 600); `shared/wwwroot-web` symlink to `/mnt/storage1/www/html/...`. +- systemd USER unit: `WorkingDirectory=current`, `ExecStart=dotnet ...dll`, `EnvironmentFile=shared/env`, `Restart=on-failure`, `KillSignal=SIGINT`. +- Deploy: appleboy/drone-scp over SSH port 2224 as `gitea-workflow`; DB backup script before/after release. + +## Network and resources +- Free ports: 5200 (test), 5201 (production, later). ufw rule needed, allow only from proxy Pi 192.168.1.102. Taken: 5100/5101, 5150/5151, 5000, 3000, 3001, 3306, 80, 2224. +- Proxy Pi (TLS, certbot) forwards DIRECTLY to the app port over HTTP/1.0, bypassing nginx on the app Pi. The host must therefore provide gzip, security headers, canonical 301s and a real 404 itself, and `UseHttpsRedirection` / forwarded headers must be handled as SlpSoftware does (open point 2 in requirements). +- Pi 4, about 5.4 GiB free RAM; one more .NET process (~250-300 MB) fits. Uploads/photos on `/mnt/storage1`; releases on the SD card. +- ARM64 builds must require runner label `arm64` or `linux-arm64` (the PC runner is x64). + +## Database +- MariaDB 10.11 on localhost. Convention: PascalCase DB named after the app, user = app name @localhost. Suggested by Pi-Main: `AndreaSlopTest` / `AndreaSlopCms`@localhost. SUPERSEDED by relayed naming decision: database `AndreaSlopFotografieTest`, user `AndreaSlopFotografie`@localhost (reason: the CMS is part of the website; the company is AndreaSlopFotografie). Confirmed by Bryan with approval of requirements. Existing DB `andreaslop` is WordPress: do not confuse. Bryan creates DB and user with sudo; the Pi-Main session adds the new DB to the backup script. + +## Open design option (include both variants in Infrastructure Design) +- Variant 1: the website CI delivers files into `wwwroot/web` directly. +- Variant 2: `shared/wwwroot-web` symlinks to `/mnt/storage1/www/html/andreaslop-test`, the folder the existing static web deploy already writes to, so the current web deploy keeps working and the CMS host serves those files. Implication for design: the known-page set must refresh when files change in place (requirements open point 1). + +## Manual steps for Bryan (to be finalised in the design) +User unit, env file, database and user, ufw rule, proxy-Pi server block/route switch, Gitea secrets in the CMS repo, backup script entry. The Pi-Main session can draft exact commands once the list is final (ask via "CMS & API"). diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/requirement-verification-questions.md b/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/requirement-verification-questions.md new file mode 100644 index 0000000..cb7fdd4 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/requirement-verification-questions.md @@ -0,0 +1,100 @@ +# Requirement Verification Questions - andreaslop-site-hosting + +Source brief: `aidlc-docs/_shared/handoffs/cms-api-foundation-brief-u1-u2.md` (decisions 1-7 in section 2 are taken and NOT re-asked). +Please fill in your choice after each `[Answer]:` tag. + +## Question 1: First-administrator setup flow hardening (Security) +The brief asks us to assess whether the first-admin setup flow on the new instance can be abused by a third party before the first administrator exists (a freshly deployed test host is publicly reachable). What should the scope be? + +- A) Assess and test the existing Identity behaviour only (no code change in Identity); document the residual risk (anyone who reaches /admin first can claim the admin account) +- B) Assess, and additionally require a one-time setup token from configuration (env var / appsettings.local.json) on the setup endpoint, only when configured - existing hosts unchanged +- C) Assess, and restrict the setup endpoint in the new client through configuration only (e.g. host/IP allow-list), no Identity change +- X) Other (please describe after [Answer]: tag below) + +[Answer]: B +(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session) + +## Question 2: Commit / PR flow for the two units +How do we deliver U1 and U2 in git? (Per standing rule: I commit, but never push unless you say so.) + +- A) One feature branch, commits per unit; no push until you ask; one PR for the whole feature after U2 +- B) One feature branch, but a PR for U1 alone after hand-back (U1 is behaviour-neutral for existing hosts), then U2 on a follow-up branch +- C) One feature branch, commits per unit; I push and open the PR only when you explicitly say so, timing decided by you per unit +- X) Other (please describe after [Answer]: tag below) + +[Answer]: A +(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session) + +## Question 3: Deployment to the test host +May the CI/CD pipeline deploy the new client to the test host, and how is it triggered? + +- A) Manual trigger only (workflow_dispatch); I may not run it, you trigger it +- B) Automatic on merge to master (like the existing pipeline), plus manual trigger +- C) I only write and verify the workflow (lint/dry run); no deploy to test is performed in this feature, you do the first deploy +- X) Other (please describe after [Answer]: tag below) + +[Answer]: X) Pipeline MAY deploy the new client to the TEST host (never production); the CMS session may start the test deploy itself once pipeline and Pi are ready. Bryan: "Hij mag hem uitrollen naar test. Graag zelfs dan kan het zsm getest worden, maar de CI/CD moet er nog op worden ingericht en de host ook." +(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session) + +## Question 4: Test-host prerequisites +Do the test host and Gitea secrets for Andrea's instance already exist? + +- A) Yes - host, path, SSH user and Gitea secrets exist; I only need the names (you will tell me, or I read them from the existing workflow) +- B) Partly - the host exists but secrets/paths for the Andrea instance still have to be defined; I list what is needed in the infrastructure design +- C) No - nothing exists yet; the design must also cover creating them (documented as manual steps for you) +- X) Other (please describe after [Answer]: tag below) + +[Answer]: X) Partly exists (matches B). Bryan: "De host heeft al de juiste accounts om het op te kunnen zetten, maar de inrichting op de host moet nog worden ingeregeld zoals paden, secrets, environment variables." Infrastructure design must list the remaining Pi setup (paths, secrets, env vars, database, reverse proxy) as manual steps for Bryan. +(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session) + +## Question 5: Admin theme scope in U2 +How far should the theme override go beyond colours, radius and font? + +- A) Tokens only (colours, radius, font) plus logo and favicon, as in the brief; no layout or component changes +- B) Tokens plus login/setup page branding (logo, title text) via theme assets; no layout changes +- X) Other (please describe after [Answer]: tag below) + +[Answer]: A +(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session) + +## Question 6: User Stories stage +Is a User Stories stage wanted for this infrastructure-heavy feature (personas would be: site visitor, site owner/admin, operator/developer)? + +- A) Skip User Stories (requirements with acceptance criteria are enough) +- B) Run a short, minimal User Stories stage +- X) Other (please describe after [Answer]: tag below) + +[Answer]: A +(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session) + +## Vraag 7: Beveiligingsextensies +Moeten de beveiligingsregels (Security Baseline) als harde vereisten worden afgedwongen voor deze feature? (De brief meldt dat je dit al hebt ingeschakeld; graag bevestigen.) + +- A) Ja - dwing alle BEVEILIGINGSREGELS af als blokkerende vereisten +- B) Nee - sla alle BEVEILIGINGSREGELS over +- X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: A +(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session) + +## Vraag 8: Property-based testing +Moet property-based testing worden afgedwongen? (De brief meldt: gedeeltelijke modus, regels PBT-02, 03, 07, 08, 09; graag bevestigen.) + +- A) Ja, gedeeltelijk - alleen PBT-02, 03, 07, 08, 09 (puur functies: padresolutie, canonieke vorm, beleid round-trip) +- B) Ja, volledig - alle PBT-regels als blokkerend +- C) Nee - sla property-based testing over +- X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: A +(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session) + +## Vraag 9: Operations-fase +Moet deze feature na Construction door de Operations-fase (deployment- en monitoringsetup, production readiness)? Let op: de CI/CD-wijzigingen voor U2 zitten sowieso in de requirements; dit gaat om de aparte Operations-fase. + +- A) Ja - voer de Operations-fase uit na Construction (deployment + monitoring setup) +- B) Nee - stop na Build and Test (CI/CD voor de testhost wordt wel gebouwd in U2 Code Generation) +- C) Nog niet zeker - vraag het me opnieuw na de Construction-fase +- X) Anders (beschrijf hieronder na de [Answer]:-tag) + +[Answer]: A +(RELAYED by session 'CMS & API' [343c26] on Bryan's behalf; pending Bryan's confirmation in this session) diff --git a/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/requirements.md b/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/requirements.md new file mode 100644 index 0000000..af8d933 --- /dev/null +++ b/aidlc-docs/features/andreaslop-site-hosting/inception/requirements/requirements.md @@ -0,0 +1,71 @@ +# Requirements - andreaslop-site-hosting + +## 1. Intent analysis +- **User request**: Serve Andrea's prerendered website (`AndreaSlopFotografie`, TanStack Start output) from SlpModularCms with nginx-parity behaviour, a strict CSP, and a Dutch themed admin; deploy to the **test** host. Brief: `aidlc-docs/_shared/handoffs/cms-api-foundation-brief-u1-u2.md`. Requester session: "CMS & API"; approver: Bryan. +- **Request type**: New feature / enhancement of the shared host + new client. +- **Scope**: Multiple components (Core hosting, Security headers, new Client project, Frontend build/theme, CI/CD). +- **Complexity**: Complex. **Depth**: Comprehensive. +- **Units**: U1 `core-site-hosting` (shared host, no behaviour change for existing clients), U2 `andreaslop-client`. Hand-back after each unit; **U2 starts only after the requester's "go"**. +- **Fixed decisions**: brief section 2 (D1-D7) and Q1-Q9 in `requirement-verification-questions.md` (answers relayed by the peer session; Bryan confirms at the approval gate). + +## 2. Unit U1 - core-site-hosting (shared host) + +### Functional +- **FR-U1-01 WebsiteMode.** `CmsHostOptions.WebsiteMode` enum: `SpaFallback` (default, exactly today's behaviour) and `PrerenderedPages`. `Api` and `Api.SlpSoftware` untouched; their tests unchanged. +- **FR-U1-02 Path resolution (pure).** A total function (never throws, never leaves the website root, rejects traversal incl. encoded/backslash/NUL/over-long paths) from (request path, file-exists predicate) to `ServeFile | Redirect(301, target) | NotFound`. Rules (nginx parity, BR-HST-01..11 in the website repo): + - `/` serves `index.html`; `/x` serves `x.html` (and `x/index.html` if present). + - **Canonical form applies to known pages only.** nginx uses a hard-coded page list; the host derives the known-page set from the `*.html` files present in the website root. A case-insensitive variant (`/Over-Mij`, `/over-mij.html`, `/over-mij/`, `/index`, `/index.html`) gets one 301 to the lowercase, no-`.html` form; `/index*` redirects to `/`. Query string preserved. Redirect targets always come from the known-page set, never from the raw request. + - Trailing slashes on any other path are stripped with a 301 (not for `/`). A target starting `//` or `/\` or containing control characters is treated as unknown (open-redirect guard, BR-HST-06). A path with a leading backslash is 404. + - Hashed asset names are never lower-cased or redirected. Paths that look like files (have an extension) are served as files or 404, never fall back to a page. + - `/404` and `/404.html` requested directly answer 404 (no redirect). +- **FR-U1-03 Unknown path.** Serve `404.html` with status **404** (never `index.html`); plain 404 if `404.html` is missing. A directory without a page file is 404; no directory listing. +- **FR-U1-04 Reserved prefixes.** `/admin`, `/api/v1`, `/health` are never handled by this middleware. An unknown API path remains an API 404 (today's website SPA fallback answers unknown `/api/v1` paths with `index.html`; this mode must not). +- **FR-U1-05 Cache-Control.** Pages and other root files: `no-cache`. Files under `/assets/`: `public, max-age=31536000, immutable`. +- **FR-U1-06 Compression.** Built-in response compression (no new dependency) for the text types in `compressibleTypes.ts` (html, js, css, svg, json, xml, txt); not for already-compressed types; `Vary: Accept-Encoding`. Website mount only (see open point 5). +- **FR-U1-07 Indexing policy.** Setting `Website:NoIndex` (default false), bound to a validated options class. When true: `X-Robots-Tag: noindex, nofollow` on all website responses (pages, assets, 404, redirects) and `/robots.txt` answers 200 with `User-agent: *` / `Disallow: /`. +- **FR-U1-08 StrictSite policy.** New policy name `StrictSite` in `CspPolicyCatalog` (in `KnownPolicies`, accepted by `PathPolicyRule` validation; unknown names still fail startup; `Strict` and `Relaxed` unchanged). Directives in the exact order of the site's current policy so the string matches byte for byte: + `default-src 'self'; script-src 'self' & \"Co\"", name: "x")); + + mail.Html.Should().NotContain("