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 <noreply@anthropic.com>
This commit is contained in:
2026-11-06 15:52:04 +01:00
co-authored by Claude Sonnet 5.5
parent d9cc539481
commit 7d21d9024a
25 changed files with 1859 additions and 23 deletions
+23 -2
View File
@@ -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();
}
}
}
@@ -1,13 +1,31 @@
namespace SlpModularCms.Core.Hosting;
/// <summary>How the public website under <c>wwwroot/web</c> is served.</summary>
public enum WebsiteMode
{
/// <summary>
/// Single-page-application behaviour (the default, and what every existing client uses):
/// unknown extensionless paths fall back to <c>index.html</c>.
/// </summary>
SpaFallback = 0,
/// <summary>
/// Prerendered multi-page website, served the way nginx serves it: <c>/x</c> is <c>x.html</c>,
/// non-canonical URLs get one 301, unknown paths get <c>404.html</c> with status 404.
/// </summary>
PrerenderedPages = 1
}
/// <summary>
/// Extension point for future per-project differences between <c>CmsHost</c> callers.
/// Extension point for per-project differences between <c>CmsHost</c> callers.
/// </summary>
/// <remarks>
/// Deliberately empty today — both current Client projects (<c>Api</c>, <c>Api.SlpSoftware</c>)
/// pass identical values. Introduced now so a future real difference is a property added here,
/// not a signature change to <see cref="CmsHost.ConfigureServices"/>/<see cref="CmsHost.ConfigurePipeline"/>.
/// A property here, not a signature change to <see cref="CmsHost.ConfigureServices"/> /
/// <see cref="CmsHost.ConfigurePipeline"/>, is how a Client project opts into different behaviour.
/// Defaults reproduce the behaviour every existing Client project already has.
/// </remarks>
public sealed class CmsHostOptions
{
/// <summary>How the public website is served. Defaults to <see cref="WebsiteMode.SpaFallback"/>.</summary>
public WebsiteMode WebsiteMode { get; init; } = WebsiteMode.SpaFallback;
}
@@ -9,7 +9,7 @@ public sealed record SecurityHeaderSet(
string ReferrerPolicy);
/// <summary>
/// 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.
/// </summary>
/// <remarks>
/// 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";
/// <summary>
/// For a prerendered public website: strict like <see cref="Strict"/> but with the script and
/// connect origins of the site (analytics, error reporting) taken from the dedicated
/// <c>AllowedSite*Origins</c> 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.
/// </summary>
public const string StrictSite = "StrictSite";
private const string ReferrerPolicyValue = "strict-origin-when-cross-origin";
public static IReadOnlyList<string> KnownPolicies { get; } = [Strict, Relaxed];
public static IReadOnlyList<string> 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<string> allowedScriptOrigins,
IEnumerable<string> allowedConnectOrigins)
IEnumerable<string> allowedConnectOrigins,
IEnumerable<string>? allowedSiteScriptOrigins = null,
IEnumerable<string>? 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(
@@ -15,7 +15,7 @@ public interface ICspPolicyProvider
/// </summary>
/// <remarks>
/// 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 <see cref="FrozenDictionary{TKey,TValue}"/> exists for.
/// </remarks>
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);
}
@@ -36,11 +36,16 @@ public static class SecurityHeaderWriter
/// <param name="contentType">Raw <c>Content-Type</c>; null for bodyless responses.</param>
/// <param name="headerSet">The resolved policy's HTML-only header values.</param>
/// <param name="sendHsts">False in Development only; see <see cref="SecurityHeadersMiddleware"/>.</param>
/// <param name="alwaysSendDocumentHeaders">
/// 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.
/// </param>
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;
}
@@ -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<SecurityHeadersMiddleware>();
}
@@ -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<SecurityHeadersMiddleware> _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<SecurityHeadersMiddleware> logger)
ILogger<SecurityHeadersMiddleware> 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);
}
@@ -58,6 +58,18 @@ public sealed class SecurityHeadersOptions
/// reporting same-origin, so <c>connect-src 'self'</c> already covers it.
/// </remarks>
public IList<string> AllowedConnectOrigins { get; set; } = [];
/// <summary>
/// Extra origins added to <c>script-src</c> under the <c>StrictSite</c> policy only (for example
/// the analytics host of a prerendered website). Never used by the admin policies.
/// </summary>
public IList<string> AllowedSiteScriptOrigins { get; set; } = [];
/// <summary>
/// Extra origins added to <c>connect-src</c> under the <c>StrictSite</c> policy only (for example
/// analytics and error-reporting hosts called directly by the website).
/// </summary>
public IList<string> AllowedSiteConnectOrigins { get; set; } = [];
}
/// <summary>One entry in <see cref="SecurityHeadersOptions.PathPolicies"/>.</summary>
@@ -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.
/// </summary>
public static WebApplication UseCmsStaticContent(this WebApplication app)
/// <param name="app">The application.</param>
/// <param name="websiteMode">
/// In <see cref="WebsiteMode.PrerenderedPages"/> only the admin mount is registered here; the
/// website is served by <c>UseCmsPrerenderedSite</c> instead.
/// </param>
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.
/// </remarks>
public static WebApplication MapCmsSpaFallbacks(this WebApplication app)
/// <param name="app">The application.</param>
/// <param name="websiteMode">
/// In <see cref="WebsiteMode.PrerenderedPages"/> the catch-all website fallback is NOT mapped: an
/// unknown path must be a real 404 (<c>MapCmsWebsiteNotFound</c>), never <c>index.html</c>.
/// </param>
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))
@@ -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;
/// <summary>Registration of the prerendered-website serving (only used when <see cref="WebsiteMode.PrerenderedPages"/>).</summary>
public static class PrerenderedSiteExtensions
{
/// <summary>Text types compressed on the website (same list as the site's nginx configuration).</summary>
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<WebsiteOptions>()
.Bind(configuration.GetSection(WebsiteOptions.SectionName))
.ValidateOnStart();
// Presence of the marker switches on the full security-header set for website responses.
services.AddSingleton<WebsiteHostingMarker>();
services.AddSingleton(provider =>
{
var environment = provider.GetRequiredService<IWebHostEnvironment>();
var webRoot = environment.WebRootPath ?? Path.Combine(environment.ContentRootPath, "wwwroot");
return new WebsiteFileAccess(
Path.Combine(webRoot, StaticContentExtensions.WebsiteDirectoryName),
provider.GetRequiredService<ILoggerFactory>().CreateLogger(PrerenderedSiteMiddleware.LoggerCategory));
});
// gzip only, like nginx today; Brotli is deliberately not registered.
services.AddResponseCompression(options =>
{
options.Providers.Add<GzipCompressionProvider>();
options.MimeTypes = CompressibleMimeTypes;
});
return services;
}
/// <summary>
/// Compression (non-reserved paths only) and the website middleware. Replaces the website static
/// mount of <c>SpaFallback</c> mode; place it where <c>UseCmsStaticContent</c> sits.
/// </summary>
public static WebApplication UseCmsPrerenderedSite(this WebApplication app)
{
app.UseWhen(
context => !WebsitePathResolver.IsReservedPath(context.Request.Path.Value),
branch => branch.UseResponseCompression());
app.UseMiddleware<PrerenderedSiteMiddleware>();
return app;
}
/// <summary>Maps the final fallback that serves <c>404.html</c> with status 404.</summary>
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;
}
}
@@ -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;
/// <summary>
/// Thin HTTP adapter around <see cref="WebsitePathResolver"/>: answers redirects, files and
/// <c>robots.txt</c> for the prerendered website, and passes everything else on (rules R15-R19, R22).
/// </summary>
/// <remarks>
/// 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
/// (<see cref="WebsiteNotFoundHandler"/>) serve the 404 page.
/// </remarks>
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<WebsiteOptions> 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;
}
}
/// <summary>Removes control characters and caps the length so a request path cannot forge log lines.</summary>
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];
}
});
}
}
@@ -0,0 +1,100 @@
using Microsoft.Extensions.FileProviders;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Primitives;
namespace SlpModularCms.Core.Hosting.Website;
/// <summary>
/// Read-only access to the website files, confined to <c>wwwroot/web</c>.
/// </summary>
/// <remarks>
/// A file provider rather than <c>Path.Combine</c> with request data: <see cref="PhysicalFileProvider"/>
/// refuses anything that resolves outside its root, which is the second line of defence behind
/// <see cref="WebsitePathResolver"/>. Exclusion filters are switched off on purpose, because the
/// default ones hide every dot-prefixed name and would make <c>/.well-known/</c> 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.
/// </remarks>
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;
}
/// <summary>True when <paramref name="relativePath"/> names an existing file (not a directory).</summary>
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;
}
}
}
@@ -0,0 +1,10 @@
namespace SlpModularCms.Core.Hosting.Website;
/// <summary>
/// Registered (as a singleton) by <c>AddCmsWebsite</c> 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.
/// </summary>
public sealed class WebsiteHostingMarker
{
}
@@ -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;
/// <summary>
/// Final fallback of a prerendered website (rules R20-R22): <c>404.html</c> with status 404.
/// </summary>
/// <remarks>
/// Mapped as the lowest-priority endpoint, so it only runs when no API route and no admin fallback
/// matched. An unknown reserved path (<c>/api/v1/...</c>) stays an empty 404 and never receives the
/// website page; other methods than GET/HEAD get 405 like a static file server.
/// </remarks>
public static class WebsiteNotFoundHandler
{
public static async Task HandleAsync(HttpContext context)
{
var request = context.Request;
var logger = context.RequestServices.GetRequiredService<ILoggerFactory>()
.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<WebsiteFileAccess>();
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.");
}
}
}
@@ -0,0 +1,13 @@
namespace SlpModularCms.Core.Hosting.Website;
/// <summary>Configuration of the prerendered website (section <c>Website</c>).</summary>
public sealed class WebsiteOptions
{
public const string SectionName = "Website";
/// <summary>
/// When true (a test instance), every website response carries
/// <c>X-Robots-Tag: noindex, nofollow</c> and <c>/robots.txt</c> disallows everything.
/// </summary>
public bool NoIndex { get; set; }
}
@@ -0,0 +1,205 @@
namespace SlpModularCms.Core.Hosting.Website;
/// <summary>
/// Pure, total mapping from a request path to a <see cref="WebsiteResolution"/>, reproducing the
/// nginx rules of the prerendered website (business rules R1-R14).
/// </summary>
/// <remarks>
/// 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.
/// </remarks>
public static class WebsitePathResolver
{
private const int MaxPathLength = 2048;
private const string WellKnownSegment = ".well-known";
/// <summary>True for <c>/admin</c>, <c>/api/v1</c> and <c>/health</c> (whole segments, case-insensitive).</summary>
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);
}
/// <param name="rawPath">Decoded request path as ASP.NET exposes it (<c>Request.Path.Value</c>).</param>
/// <param name="queryString">Query string including the leading '?', or null/empty.</param>
/// <param name="fileExists">Receives relative, forward-slash candidates such as <c>over-mij.html</c>.</param>
public static WebsiteResolution Resolve(string? rawPath, string? queryString, Func<string, bool> 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<string, bool> 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 <lowercase-name>.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;
}
/// <summary>A literal "%2e", "%2f" or "%5c" left after the single decode pass is a double-encoding attempt.</summary>
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);
}
/// <summary>Returns "" or a query starting with '?'; null when the query contains control characters.</summary>
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;
}
}
@@ -0,0 +1,21 @@
namespace SlpModularCms.Core.Hosting.Website;
/// <summary>Outcome of resolving a request path against the prerendered website.</summary>
public abstract record WebsiteResolution
{
private WebsiteResolution()
{
}
/// <summary>Serve this existing file. <see cref="RelativePath"/> is relative, forward-slash and validated.</summary>
public sealed record ServeFile(string RelativePath) : WebsiteResolution;
/// <summary>Answer 301 with this relative <c>Location</c> (always starts with a single '/').</summary>
public sealed record Redirect(string Location) : WebsiteResolution;
/// <summary>No page or file for this path; the caller decides between the 404 page and other handlers.</summary>
public sealed record NotFound : WebsiteResolution
{
public static readonly NotFound Instance = new();
}
}