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(); + } +}