feat(inbound): register AuditWriteMiddleware in pipeline (#23 M4)

src/ScadaLink.Host/Program.cs

@@ -12,6 +12,7 @@ using ScadaLink.Host;
 using ScadaLink.Host.Actors;
 using ScadaLink.Host.Health;
 using ScadaLink.InboundAPI;
+using ScadaLink.InboundAPI.Middleware;
 using ScadaLink.ManagementService;
 using ScadaLink.NotificationOutbox;
 using ScadaLink.NotificationService;
@@ -162,6 +163,18 @@ try
         app.UseAuthorization();
         app.UseAntiforgery();
 
+        // Audit Log #23 (M4 Bundle D, T8): emit one InboundRequest/InboundAuthFailure
+        // audit row per call into the inbound API. Placed AFTER UseAuthentication/
+        // UseAuthorization so any HttpContext.User the framework populates is in
+        // place, and scoped to the /api/ prefix so it never observes the Central UI,
+        // Management API, SignalR hubs, or health endpoints. The endpoint handler
+        // is responsible for stashing the resolved API key name on
+        // HttpContext.Items (see AuditWriteMiddleware.AuditActorItemKey) AFTER its
+        // in-handler API key validation succeeds.
+        app.UseWhen(
+            ctx => ctx.Request.Path.StartsWithSegments("/api"),
+            branch => branch.UseAuditWriteMiddleware());
+
         // WP-12: Map readiness endpoint — returns 503 until ready, 200 when ready.
         // REQ-HOST-4a defines readiness as cluster membership + DB connectivity,
         // explicitly NOT cluster leadership. The leader-only "active-node" check is

src/ScadaLink.InboundAPI/EndpointExtensions.cs

@@ -5,6 +5,7 @@ using Microsoft.AspNetCore.Routing;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Options;
+using ScadaLink.InboundAPI.Middleware;
 
 namespace ScadaLink.InboundAPI;
 
@@ -53,6 +54,13 @@ public static class EndpointExtensions
 
         var method = validationResult.Method!;
 
+        // Audit Log (#23 M4 Bundle D): publish the resolved API key name so
+        // AuditWriteMiddleware can populate AuditEvent.Actor in its finally
+        // block. Done AFTER validation succeeded — auth failures leave the
+        // slot empty and the middleware records the row with Actor=null.
+        httpContext.Items[AuditWriteMiddleware.AuditActorItemKey] =
+            validationResult.ApiKey!.Name;
+
         // WP-2: Deserialize and validate parameters
         JsonElement? body = null;
         try

tests/ScadaLink.InboundAPI.Tests/Middleware/MiddlewareOrderTests.cs

@@ -0,0 +1,236 @@
+using Microsoft.AspNetCore.Authentication;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.TestHost;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging.Abstractions;
+using ScadaLink.Commons.Entities.Audit;
+using ScadaLink.Commons.Interfaces.Services;
+using ScadaLink.Commons.Types.Enums;
+using ScadaLink.InboundAPI.Middleware;
+using System.Security.Claims;
+
+namespace ScadaLink.InboundAPI.Tests.Middleware;
+
+/// <summary>
+/// M4 Bundle D (D2) — verifies the production pipeline order from
+/// <c>ScadaLink.Host.Program.cs</c> for the inbound API:
+/// <c>UseAuthentication → UseAuthorization → UseAuditWriteMiddleware → endpoint</c>.
+///
+/// <para>
+/// The order is load-bearing: the audit middleware must run AFTER auth (so any
+/// framework-resolved principal on <see cref="HttpContext.User"/> is in place)
+/// and BEFORE the inbound-API endpoint handler (so the handler's stashed actor
+/// name from <see cref="HttpContext.Items"/> is observable in the
+/// <c>finally</c> block when the handler returns). The order is also what
+/// guarantees auth-failure responses (401/403 produced by a future auth scheme)
+/// are seen by the middleware so it can emit
+/// <see cref="AuditKind.InboundAuthFailure"/>.
+/// </para>
+/// </summary>
+public class MiddlewareOrderTests
+{
+    /// <summary>
+    /// Captures the order of pipeline stages by appending a token to a shared
+    /// list as each stage runs. The assertion compares the resulting sequence
+    /// directly so a regression that re-orders the pipeline fails loudly.
+    /// </summary>
+    private sealed class OrderingRecorder
+    {
+        public List<string> Stages { get; } = new();
+        public void Record(string stage)
+        {
+            lock (Stages) { Stages.Add(stage); }
+        }
+    }
+
+    private sealed class RecordingAuditWriter : ICentralAuditWriter
+    {
+        public List<AuditEvent> Events { get; } = new();
+        public Task WriteAsync(AuditEvent evt, CancellationToken ct = default)
+        {
+            lock (Events) { Events.Add(evt); }
+            return Task.CompletedTask;
+        }
+    }
+
+    [Fact]
+    public async Task Middleware_Pipeline_PlacesAuditWriteAfterAuth_BeforeScriptExecution()
+    {
+        var recorder = new OrderingRecorder();
+        var writer = new RecordingAuditWriter();
+
+        using var host = await BuildHostAsync(recorder, writer);
+        var client = host.GetTestClient();
+
+        var response = await client.PostAsync("/api/echo", new StringContent("{}"));
+
+        Assert.Equal(System.Net.HttpStatusCode.OK, response.StatusCode);
+
+        // The recorder MUST observe these stages in exactly this order:
+        //   1. Authentication (UseAuthentication marker)
+        //   2. Authorization  (UseAuthorization marker)
+        //   3. AuditMiddleware-Before-Next (audit middleware entered)
+        //   4. Endpoint handler (the route handler ran)
+        //   5. AuditMiddleware-After-Next (audit middleware completed)
+        Assert.Equal(
+            new[]
+            {
+                "auth",
+                "authz",
+                "audit-before",
+                "endpoint",
+                "audit-after",
+            },
+            recorder.Stages);
+
+        // And exactly one InboundRequest/Delivered audit row was emitted —
+        // proving the audit middleware actually wrapped the endpoint.
+        var evt = Assert.Single(writer.Events);
+        Assert.Equal(AuditKind.InboundRequest, evt.Kind);
+        Assert.Equal(AuditStatus.Delivered, evt.Status);
+        Assert.Equal("test-actor", evt.Actor);
+    }
+
+    [Fact]
+    public async Task Middleware_Pipeline_Records_AuthFailure_Beyond_Endpoint()
+    {
+        // A 401 short-circuit happens *inside the endpoint handler* in the real
+        // InboundAPI (the X-API-Key validator runs there), so the audit
+        // middleware still wraps it and observes the 401 response status. This
+        // confirms ordering supports the InboundAuthFailure emission path.
+        var recorder = new OrderingRecorder();
+        var writer = new RecordingAuditWriter();
+
+        using var host = await BuildHostAsync(recorder, writer, endpointStatus: 401);
+        var client = host.GetTestClient();
+
+        var response = await client.PostAsync("/api/echo", new StringContent("{}"));
+
+        Assert.Equal(System.Net.HttpStatusCode.Unauthorized, response.StatusCode);
+
+        var evt = Assert.Single(writer.Events);
+        Assert.Equal(AuditKind.InboundAuthFailure, evt.Kind);
+        Assert.Equal(AuditStatus.Failed, evt.Status);
+        Assert.Equal(401, evt.HttpStatus);
+    }
+
+    /// <summary>
+    /// Builds a minimal in-memory host whose pipeline mirrors the production
+    /// arrangement in <c>ScadaLink.Host.Program.cs</c>:
+    /// <c>UseRouting → UseAuthentication → UseAuthorization → UseAuditWriteMiddleware → endpoints</c>.
+    /// Marker middlewares record their entry into <paramref name="recorder"/> so
+    /// the test can assert on the resulting ordering.
+    /// </summary>
+    private static async Task<IHost> BuildHostAsync(
+        OrderingRecorder recorder,
+        ICentralAuditWriter writer,
+        int endpointStatus = 200)
+    {
+        var hostBuilder = new HostBuilder()
+            .ConfigureWebHost(webBuilder =>
+            {
+                webBuilder
+                    .UseTestServer()
+                    .ConfigureServices(services =>
+                    {
+                        services.AddSingleton(writer);
+                        services.AddSingleton<AuditWriteMiddleware>(sp =>
+                            new AuditWriteMiddleware(
+                                // The middleware factory pattern is bypassed
+                                // here so the inner delegate is closed over the
+                                // recorder — UseMiddleware<T> below still
+                                // instantiates the type correctly.
+                                _ => Task.CompletedTask,
+                                writer,
+                                NullLogger<AuditWriteMiddleware>.Instance));
+                        services.AddRouting();
+                        services.AddAuthorization();
+                        services.AddAuthentication("TestScheme")
+                            .AddScheme<AuthenticationSchemeOptions, AlwaysAuthenticatedHandler>(
+                                "TestScheme", _ => { });
+                    })
+                    .Configure(app =>
+                    {
+                        app.UseRouting();
+                        app.Use(async (ctx, next) =>
+                        {
+                            recorder.Record("auth");
+                            await next();
+                        });
+                        app.UseAuthentication();
+                        app.Use(async (ctx, next) =>
+                        {
+                            recorder.Record("authz");
+                            await next();
+                        });
+                        app.UseAuthorization();
+
+                        // The order-under-test: AuditWriteMiddleware sits
+                        // AFTER auth/authz markers and BEFORE the endpoint
+                        // marker. We wrap with a sentinel marker that fires
+                        // *before* the audit middleware enters so the test can
+                        // pin where the audit middleware lands in the chain.
+                        app.Use(async (ctx, next) =>
+                        {
+                            recorder.Record("audit-before");
+                            await next();
+                            recorder.Record("audit-after");
+                        });
+                        app.UseAuditWriteMiddleware();
+
+                        app.UseEndpoints(endpoints =>
+                        {
+                            endpoints.MapPost("/api/{methodName}", async ctx =>
+                            {
+                                recorder.Record("endpoint");
+
+                                if (endpointStatus is 401 or 403)
+                                {
+                                    // Simulate an auth-failure short-circuit
+                                    // produced by the in-handler API key
+                                    // validator — Actor must stay null.
+                                    ctx.Response.StatusCode = endpointStatus;
+                                    return;
+                                }
+
+                                // Simulate the production handler stashing
+                                // the resolved API key name AFTER auth.
+                                ctx.Items[AuditWriteMiddleware.AuditActorItemKey] = "test-actor";
+                                ctx.Response.StatusCode = endpointStatus;
+                                await ctx.Response.WriteAsync("ok");
+                            });
+                        });
+                    });
+            });
+
+        var host = await hostBuilder.StartAsync();
+        return host;
+    }
+
+    /// <summary>
+    /// Minimal authentication handler that always succeeds — keeps
+    /// <see cref="HttpContext.User"/> populated so the test's audit middleware
+    /// path that prefers Items but falls back to User.Identity has a real
+    /// principal to ignore. The middleware's primary path uses Items so this
+    /// handler's claim never appears on the emitted Actor.
+    /// </summary>
+    private sealed class AlwaysAuthenticatedHandler : AuthenticationHandler<AuthenticationSchemeOptions>
+    {
+        public AlwaysAuthenticatedHandler(
+            Microsoft.Extensions.Options.IOptionsMonitor<AuthenticationSchemeOptions> options,
+            Microsoft.Extensions.Logging.ILoggerFactory logger,
+            System.Text.Encodings.Web.UrlEncoder encoder)
+            : base(options, logger, encoder) { }
+
+        protected override Task<AuthenticateResult> HandleAuthenticateAsync()
+        {
+            var identity = new ClaimsIdentity(new[] { new Claim(ClaimTypes.Name, "framework-user") }, "TestScheme");
+            var principal = new ClaimsPrincipal(identity);
+            var ticket = new AuthenticationTicket(principal, "TestScheme");
+            return Task.FromResult(AuthenticateResult.Success(ticket));
+        }
+    }
+}