feat(audit): OtOpcUa IAuditActorAccessor seam + HTTP impl (audit Actor from Auth principal) (Phase 3)

Introduces the IAuditActorAccessor seam and HttpAuditActorAccessor impl so the
ZB.MOM.WW.Audit.AuditEvent Actor field can be sourced from the authenticated Blazor
cookie principal (ZbClaimTypes.Username) when structured emitters are added. Adds the
AuditActor.Resolve static helper (accessor value → SystemFallback/"system") as the
canonical pattern for future emit sites. Wires DI in AddOtOpcUaAuth (TryAddScoped) with
AddHttpContextAccessor(). The structured AuditEvent path remains DORMANT — no live emit
sites exist; seam is forward-looking. SP-based audit path left untouched. 9 new unit
tests all green; Security (54) and ControlPlane (45) test suites fully pass.

src/Server/ZB.MOM.WW.OtOpcUa.Security/Audit/AuditActor.cs

@@ -0,0 +1,50 @@
+namespace ZB.MOM.WW.OtOpcUa.Security.Audit;
+
+/// <summary>
+/// Default-resolution helpers for the <c>Actor</c> field of a canonical
+/// <c>ZB.MOM.WW.Audit.AuditEvent</c>.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Usage pattern — call <see cref="Resolve"/> when constructing an <c>AuditEvent</c>:
+/// <code>
+/// new AuditEvent
+/// {
+///     Actor  = AuditActor.Resolve(auditActorAccessor),
+///     ...
+/// }
+/// </code>
+/// </para>
+/// <para>
+/// <b>Note:</b> OtOpcUa has no live structured <c>AuditEvent</c> emit sites as of Phase 3
+/// (all production audit flows through the bespoke stored-procedure path). This helper is
+/// forward-looking — it is tested and ready so that future emit sites pick up the correct
+/// Actor automatically.
+/// </para>
+/// </remarks>
+public static class AuditActor
+{
+    /// <summary>The fallback actor string used when no authenticated principal is available.</summary>
+    public const string SystemFallback = "system";
+
+    /// <summary>
+    /// Returns the current principal's actor string from <paramref name="accessor"/>, or
+    /// <see cref="SystemFallback"/> when the accessor returns <see langword="null"/>
+    /// (no HTTP context, unauthenticated, or in a background/non-HTTP execution context).
+    /// </summary>
+    /// <param name="accessor">The audit-actor accessor. May be <see langword="null"/>
+    /// (e.g. in a background context where DI did not wire the accessor).</param>
+    /// <returns>The actor string — never <see langword="null"/>.</returns>
+    public static string Resolve(IAuditActorAccessor? accessor) =>
+        Resolve(accessor, SystemFallback);
+
+    /// <summary>
+    /// Returns the current principal's actor string from <paramref name="accessor"/>, or
+    /// <paramref name="fallback"/> when the accessor returns <see langword="null"/>.
+    /// </summary>
+    /// <param name="accessor">The audit-actor accessor. May be <see langword="null"/>.</param>
+    /// <param name="fallback">The explicit fallback value.</param>
+    /// <returns>The actor string — never <see langword="null"/>.</returns>
+    public static string Resolve(IAuditActorAccessor? accessor, string fallback) =>
+        accessor?.CurrentActor ?? fallback;
+}

src/Server/ZB.MOM.WW.OtOpcUa.Security/Audit/HttpAuditActorAccessor.cs

@@ -0,0 +1,53 @@
+using Microsoft.AspNetCore.Http;
+using ZB.MOM.WW.Auth.AspNetCore;
+
+namespace ZB.MOM.WW.OtOpcUa.Security.Audit;
+
+/// <summary>
+/// HTTP-context–backed <see cref="IAuditActorAccessor"/> for the OtOpcUa control-plane.
+/// </summary>
+/// <remarks>
+/// Reads the authenticated principal from <see cref="IHttpContextAccessor"/>:
+/// <list type="number">
+///   <item>If there is no current <c>HttpContext</c> or the user is not authenticated,
+///   returns <see langword="null"/>.</item>
+///   <item>Otherwise, returns the <see cref="ZbClaimTypes.Username"/> claim value (the
+///   canonical directory login name set at sign-in by <c>AuthEndpoints</c>).</item>
+///   <item>Falls back to the <see cref="ZbClaimTypes.Name"/> claim, then to
+///   <see cref="System.Security.Principal.IIdentity.Name"/>, in that order.</item>
+/// </list>
+/// <para>
+/// Registered as <b>scoped</b> in <see cref="ZB.MOM.WW.OtOpcUa.Security.ServiceCollectionExtensions.AddOtOpcUaAuth"/>
+/// so that it correctly follows the request scope used by Blazor Server interactive components
+/// and minimal-API endpoints. <c>IHttpContextAccessor</c> is registered by
+/// <c>AddOtOpcUaAuth</c> via <c>services.AddHttpContextAccessor()</c>.
+/// </para>
+/// </remarks>
+public sealed class HttpAuditActorAccessor : IAuditActorAccessor
+{
+    private readonly IHttpContextAccessor _httpContextAccessor;
+
+    /// <summary>Initializes the accessor with the ASP.NET Core HTTP context accessor.</summary>
+    /// <param name="httpContextAccessor">The HTTP context accessor.</param>
+    public HttpAuditActorAccessor(IHttpContextAccessor httpContextAccessor)
+    {
+        _httpContextAccessor = httpContextAccessor;
+    }
+
+    /// <inheritdoc />
+    public string? CurrentActor
+    {
+        get
+        {
+            var user = _httpContextAccessor.HttpContext?.User;
+            if (user?.Identity?.IsAuthenticated != true)
+                return null;
+
+            // Prefer the canonical login-name claim; fall back to the Name claim or
+            // Identity.Name (both of which map to ClaimTypes.Name / ZbClaimTypes.Name).
+            return user.FindFirst(ZbClaimTypes.Username)?.Value
+                   ?? user.FindFirst(ZbClaimTypes.Name)?.Value
+                   ?? user.Identity.Name;
+        }
+    }
+}

src/Server/ZB.MOM.WW.OtOpcUa.Security/Audit/IAuditActorAccessor.cs

@@ -0,0 +1,30 @@
+namespace ZB.MOM.WW.OtOpcUa.Security.Audit;
+
+/// <summary>
+/// Resolves the current HTTP principal's actor string for inclusion in a canonical
+/// <c>ZB.MOM.WW.Audit.AuditEvent</c> as the <c>Actor</c> field.
+/// </summary>
+/// <remarks>
+/// The seam abstracts the identity source so that:
+/// <list type="bullet">
+///   <item>production code uses <see cref="HttpAuditActorAccessor"/> (reads the
+///   authenticated Blazor cookie principal from <c>IHttpContextAccessor</c>); and</item>
+///   <item>unit tests or non-HTTP contexts can substitute a stub or return
+///   <see langword="null"/> (which triggers the <c>"system"</c> fallback in
+///   <see cref="AuditActor.Resolve"/>).</item>
+/// </list>
+/// <para>
+/// <b>Note:</b> OtOpcUa has no live structured <c>AuditEvent</c> emit sites as of Phase 3
+/// (all production audit flows through the bespoke stored-procedure path). This seam is
+/// forward-looking — wired and tested so that future emit sites can call
+/// <see cref="AuditActor.Resolve"/> and get the Auth principal automatically.
+/// </para>
+/// </remarks>
+public interface IAuditActorAccessor
+{
+    /// <summary>
+    /// Returns the authenticated principal's actor string, or <see langword="null"/> when
+    /// there is no current HTTP context or the user is not authenticated.
+    /// </summary>
+    string? CurrentActor { get; }
+}

src/Server/ZB.MOM.WW.OtOpcUa.Security/ServiceCollectionExtensions.cs

@@ -10,6 +10,7 @@ using Microsoft.Extensions.Options;
 using ZB.MOM.WW.Auth.AspNetCore;
 using ZB.MOM.WW.Auth.Abstractions.Roles;
 using ZB.MOM.WW.OtOpcUa.Configuration;
+using ZB.MOM.WW.OtOpcUa.Security.Audit;
 using ZB.MOM.WW.OtOpcUa.Security.Jwt;
 using ZB.MOM.WW.OtOpcUa.Security.Ldap;
 
@@ -37,6 +38,19 @@ public static class ServiceCollectionExtensions
         services.AddOptions<LdapOptions>().Bind(configuration.GetSection(LdapOptions.SectionName));
 
         services.AddSingleton<JwtTokenService>();
+
+        // IHttpContextAccessor is not registered by default — call AddHttpContextAccessor()
+        // so HttpAuditActorAccessor and any Blazor/minimal-API component that reads the current
+        // HTTP context by injection can resolve it. AddHttpContextAccessor is idempotent (internal
+        // TryAdd), so calling it here is safe even if the host also calls it elsewhere.
+        services.AddHttpContextAccessor();
+
+        // IAuditActorAccessor — resolves the authenticated HTTP principal's actor string for use
+        // as the Actor field when constructing a canonical ZB.MOM.WW.Audit.AuditEvent. Registered
+        // Scoped so it correctly follows the request scope used by Blazor Server and minimal-API
+        // endpoints.
+        services.TryAddScoped<IAuditActorAccessor, HttpAuditActorAccessor>();
+
         // Singleton — OtOpcUaLdapAuthService is stateless (the shared-library directory client it
         // wraps opens/disposes an LdapConnection per call) and must be consumable by the Singleton
         // LdapOpcUaUserAuthenticator on driver-role nodes. This is the app's ILdapAuthService: it

tests/Server/ZB.MOM.WW.OtOpcUa.Security.Tests/Audit/AuditActorTests.cs

@@ -0,0 +1,81 @@
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Security.Audit;
+
+namespace ZB.MOM.WW.OtOpcUa.Security.Tests.Audit;
+
+/// <summary>
+/// Unit tests for <see cref="AuditActor"/> — the static resolution helper that sources the
+/// <c>Actor</c> field of a canonical <c>ZB.MOM.WW.Audit.AuditEvent</c> from the current
+/// HTTP principal and falls back to a configurable value when no principal is available.
+/// </summary>
+public sealed class AuditActorTests
+{
+    /// <summary>
+    /// <see cref="AuditActor.Resolve(IAuditActorAccessor?)"/> returns the accessor's value
+    /// when the accessor returns a non-null string.
+    /// </summary>
+    [Fact]
+    public void Resolve_returns_accessor_value_when_present()
+    {
+        var accessor = new StubAccessor("alice");
+
+        AuditActor.Resolve(accessor).ShouldBe("alice");
+    }
+
+    /// <summary>
+    /// <see cref="AuditActor.Resolve(IAuditActorAccessor?)"/> returns
+    /// <see cref="AuditActor.SystemFallback"/> when the accessor returns null
+    /// (unauthenticated / no HTTP context).
+    /// </summary>
+    [Fact]
+    public void Resolve_returns_system_fallback_when_accessor_returns_null()
+    {
+        var accessor = new StubAccessor(null);
+
+        AuditActor.Resolve(accessor).ShouldBe(AuditActor.SystemFallback);
+    }
+
+    /// <summary>
+    /// <see cref="AuditActor.Resolve(IAuditActorAccessor?)"/> returns
+    /// <see cref="AuditActor.SystemFallback"/> when the accessor reference itself is null
+    /// (e.g. in a background/non-HTTP context where DI did not inject the accessor).
+    /// </summary>
+    [Fact]
+    public void Resolve_returns_system_fallback_when_accessor_is_null()
+    {
+        AuditActor.Resolve(null).ShouldBe(AuditActor.SystemFallback);
+    }
+
+    /// <summary>
+    /// <see cref="AuditActor.Resolve(IAuditActorAccessor?,string)"/> uses the explicit
+    /// fallback string rather than <see cref="AuditActor.SystemFallback"/> when the accessor
+    /// returns null.
+    /// </summary>
+    [Fact]
+    public void Resolve_uses_explicit_fallback_when_accessor_returns_null()
+    {
+        var accessor = new StubAccessor(null);
+
+        AuditActor.Resolve(accessor, "scheduler").ShouldBe("scheduler");
+    }
+
+    /// <summary>
+    /// <see cref="AuditActor.Resolve(IAuditActorAccessor?,string)"/> prefers the accessor's
+    /// value over the explicit fallback when the accessor returns a non-null string.
+    /// </summary>
+    [Fact]
+    public void Resolve_prefers_accessor_value_over_explicit_fallback()
+    {
+        var accessor = new StubAccessor("bob");
+
+        AuditActor.Resolve(accessor, "scheduler").ShouldBe("bob");
+    }
+
+    // ── stub ──────────────────────────────────────────────────────────────────────
+
+    private sealed class StubAccessor(string? value) : IAuditActorAccessor
+    {
+        public string? CurrentActor { get; } = value;
+    }
+}

tests/Server/ZB.MOM.WW.OtOpcUa.Security.Tests/Audit/HttpAuditActorAccessorTests.cs

@@ -0,0 +1,115 @@
+using System.Security.Claims;
+using Microsoft.AspNetCore.Http;
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.Auth.AspNetCore;
+using ZB.MOM.WW.OtOpcUa.Security.Audit;
+
+namespace ZB.MOM.WW.OtOpcUa.Security.Tests.Audit;
+
+/// <summary>
+/// Unit tests for <see cref="HttpAuditActorAccessor"/>.
+/// <para>
+/// Covers the three cases:
+/// <list type="bullet">
+///   <item>Authenticated principal with a <see cref="ZbClaimTypes.Username"/> claim →
+///   returns the username claim value.</item>
+///   <item>Authenticated principal with only a <see cref="ZbClaimTypes.Name"/> / no
+///   username claim → falls back to the Name claim.</item>
+///   <item>No HTTP context (null) or unauthenticated principal → returns
+///   <see langword="null"/>.</item>
+/// </list>
+/// </para>
+/// </summary>
+public sealed class HttpAuditActorAccessorTests
+{
+    // ── helpers ──────────────────────────────────────────────────────────────────
+
+    private static IHttpContextAccessor ContextWith(ClaimsPrincipal principal)
+    {
+        var context = new DefaultHttpContext { User = principal };
+        return new HttpContextAccessorStub(context);
+    }
+
+    private static IHttpContextAccessor NoContext() =>
+        new HttpContextAccessorStub(null);
+
+    private static ClaimsPrincipal AuthenticatedWith(params Claim[] claims)
+    {
+        var identity = new ClaimsIdentity(
+            claims,
+            authenticationType: "TestScheme",   // non-null authenticationType → IsAuthenticated = true
+            nameType: ZbClaimTypes.Name,
+            roleType: ZbClaimTypes.Role);
+        return new ClaimsPrincipal(identity);
+    }
+
+    private static ClaimsPrincipal Unauthenticated() =>
+        new(new ClaimsIdentity()); // no authenticationType → IsAuthenticated = false
+
+    // ── tests ─────────────────────────────────────────────────────────────────────
+
+    /// <summary>
+    /// An authenticated principal that carries <see cref="ZbClaimTypes.Username"/>
+    /// returns exactly that claim value — it is the canonical actor string.
+    /// </summary>
+    [Fact]
+    public void Returns_username_claim_for_authenticated_principal()
+    {
+        var principal = AuthenticatedWith(
+            new Claim(ZbClaimTypes.Username, "alice"),
+            new Claim(ZbClaimTypes.Name, "alice-name"),
+            new Claim(ZbClaimTypes.DisplayName, "Alice User"));
+
+        var sut = new HttpAuditActorAccessor(ContextWith(principal));
+
+        sut.CurrentActor.ShouldBe("alice");
+    }
+
+    /// <summary>
+    /// When the principal has no <see cref="ZbClaimTypes.Username"/> claim but does have
+    /// a <see cref="ZbClaimTypes.Name"/> claim, the Name claim value is returned as the
+    /// fallback actor.
+    /// </summary>
+    [Fact]
+    public void Falls_back_to_Name_claim_when_Username_claim_is_absent()
+    {
+        var principal = AuthenticatedWith(
+            new Claim(ZbClaimTypes.Name, "bob"));
+
+        var sut = new HttpAuditActorAccessor(ContextWith(principal));
+
+        sut.CurrentActor.ShouldBe("bob");
+    }
+
+    /// <summary>
+    /// An unauthenticated principal (Identity.IsAuthenticated == false) returns null —
+    /// the caller's fallback (typically <see cref="AuditActor.SystemFallback"/>) is used.
+    /// </summary>
+    [Fact]
+    public void Returns_null_for_unauthenticated_principal()
+    {
+        var sut = new HttpAuditActorAccessor(ContextWith(Unauthenticated()));
+
+        sut.CurrentActor.ShouldBeNull();
+    }
+
+    /// <summary>
+    /// When there is no current <c>HttpContext</c> (e.g. background task, actor mailbox
+    /// worker), returns null.
+    /// </summary>
+    [Fact]
+    public void Returns_null_when_no_HttpContext()
+    {
+        var sut = new HttpAuditActorAccessor(NoContext());
+
+        sut.CurrentActor.ShouldBeNull();
+    }
+
+    // ── stub ──────────────────────────────────────────────────────────────────────
+
+    private sealed class HttpContextAccessorStub(HttpContext? context) : IHttpContextAccessor
+    {
+        public HttpContext? HttpContext { get; set; } = context;
+    }
+}