feat(audit): MxGateway IAuditActorAccessor + dashboard audit Actor = operator principal (keyId→Target) (Phase 3)

Introduce IAuditActorAccessor seam + HttpAuditActorAccessor impl (reads ZbClaimTypes.Username
from IHttpContextAccessor; falls back to Identity.Name / ZbClaimTypes.Name; null when
unauthenticated). Register in DI via DashboardServiceCollectionExtensions.

Wire DashboardApiKeyManagementService: WriteDashboardAuditAsync now accepts the ClaimsPrincipal
user already in scope at each call site; ResolveOperatorActor extracts ZbClaimTypes.Username
(preferred) or Identity.Name. All four dashboard-* events now emit Actor = LDAP operator
username and Target = managed keyId, fixing the semantic gap where both fields held the keyId.

ConstraintEnforcer (gRPC / API-key actor) and CanonicalForwardingApiKeyAuditStore (CLI /
"system"/"cli" fallback) are unchanged.

Tests: DashboardApiKeyManagementServiceTests updated — CreateAuthorizedUser adds ZbClaimTypes.Username
("alice"), all dashboard-* audit assertions updated to Actor = "alice" / Target = "operator01";
new CreateAsync_AuthorizedUser_CanonicalAuditEventHasOperatorAsActorAndKeyIdAsTarget verifies the
canonical AuditEvent directly. New HttpAuditActorAccessorTests (4 cases: username claim, Identity.Name
fallback, unauthenticated → null, no context → null). ConstraintEnforcer tests still assert API-key/anonymous actor.

CLAUDE.md

@@ -100,7 +100,7 @@ When source code changes, build and test the affected component before reporting
 ## Design Sources To Consult Before Non-Trivial Changes
 
 - `gateway.md` — top-level architecture, command/event surface, IPC envelope, STA thread model, fault handling.
-- `glauth.md` — local LDAP server (GLAuth on `localhost:3893`, base DN `dc=lmxopcua,dc=local`) used for dev authn. Pre-provisioned users (`admin/admin123`, `readonly/readonly123`, etc.) and the role→capability mapping live there.
+- `glauth.md` — local LDAP server (GLAuth on `localhost:3893`, base DN `dc=zb,dc=local`) used for dev authn. Pre-provisioned users (`admin/admin123`, `readonly/readonly123`, etc.) and the role→capability mapping live there.
 - `docs/DesignDecisions.md` — v1 choices (MXAccess COM target `LMXProxyServerClass` from `C:\Program Files (x86)\ArchestrA\Framework\Bin\ArchestrA.MXAccess.dll`, API-key-in-SQLite auth, fail-fast event backpressure, etc.).
 - `docs/GatewayProcessDesign.md`, `docs/MxAccessWorkerInstanceDesign.md`, `docs/WorkerFrameProtocol.md`, `docs/WorkerProcessLauncher.md` — detailed component designs.
 - `docs/GatewayConfiguration.md` — full `MxGateway:*` options bound by `GatewayOptions` and validated at startup by `GatewayOptionsValidator`.

glauth.md

@@ -20,9 +20,9 @@ against them, and what's needed to add a gw-specific role.
 | Host | `localhost` |
 | Port | `3893` |
 | LDAPS | disabled in dev (set `[ldaps]` block to enable) |
-| Base DN | `dc=lmxopcua,dc=local` |
-| Bind DN format | `cn={username},dc=lmxopcua,dc=local` |
-| Group OU | `ou=<groupname>,ou=groups,dc=lmxopcua,dc=local` |
+| Base DN | `dc=zb,dc=local` |
+| Bind DN format | `cn={username},dc=zb,dc=local` |
+| Group OU | `ou=<groupname>,ou=groups,dc=zb,dc=local` |
 | Failed-bind throttle | 3 fails → 10-minute IP lockout (per `[behaviors]`) |
 
 ## Pre-existing groups (LmxOpcUa role taxonomy)
@@ -33,11 +33,11 @@ LmxOpcUa write rights doesn't need a second account for the gw.
 
 | Group | GID | DN | LmxOpcUa meaning | Suggested mxgw mapping |
 |---|---|---|---|---|
-| ReadOnly | 5501 | `ou=ReadOnly,ou=groups,dc=lmxopcua,dc=local` | Browse + read OPC UA nodes | `Browse` + `Subscribe` (read paths only) |
-| WriteOperate | 5502 | `ou=WriteOperate,ou=groups,dc=lmxopcua,dc=local` | Write FreeAccess / Operate attrs | `Write` (plain) |
-| WriteTune | 5504 | `ou=WriteTune,ou=groups,dc=lmxopcua,dc=local` | Write Tune attrs | `WriteSecured` (Tune only) |
-| WriteConfigure | 5505 | `ou=WriteConfigure,ou=groups,dc=lmxopcua,dc=local` | Write Configure attrs | `WriteSecured` (Configure) |
-| AlarmAck | 5503 | `ou=AlarmAck,ou=groups,dc=lmxopcua,dc=local` | Acknowledge alarms | gw alarm-ack RPC, when added |
+| ReadOnly | 5501 | `ou=ReadOnly,ou=groups,dc=zb,dc=local` | Browse + read OPC UA nodes | `Browse` + `Subscribe` (read paths only) |
+| WriteOperate | 5502 | `ou=WriteOperate,ou=groups,dc=zb,dc=local` | Write FreeAccess / Operate attrs | `Write` (plain) |
+| WriteTune | 5504 | `ou=WriteTune,ou=groups,dc=zb,dc=local` | Write Tune attrs | `WriteSecured` (Tune only) |
+| WriteConfigure | 5505 | `ou=WriteConfigure,ou=groups,dc=zb,dc=local` | Write Configure attrs | `WriteSecured` (Configure) |
+| AlarmAck | 5503 | `ou=AlarmAck,ou=groups,dc=zb,dc=local` | Acknowledge alarms | gw alarm-ack RPC, when added |
 
 **A user can be in multiple groups** — `othergroups = [...]` in the
 config is a list. `admin` is the canonical example (in every role
@@ -67,12 +67,18 @@ GLAuth config — it must be provisioned before dashboard authn or the
 LDAP live tests work. See [Provisioning the GwAdmin
 group](#provisioning-the-gwadmin-group) below.
 
+> **Dashboard role value (Task 1.7):** the LDAP `GwAdmin` group now maps to
+> the canonical dashboard role **`Administrator`** (was `Admin`); `GwReader`
+> maps to `Viewer`. This is a pure value rename via
+> `MxGateway:Dashboard:GroupToRole` — same operations are authorized. (This
+> dashboard role is distinct from the lowercase gRPC `admin` *API-key scope*.)
+
 ## Two bind patterns
 
 ### 1. Direct bind (simplest)
 
 ```
-DN:       cn=admin,dc=lmxopcua,dc=local
+DN:       cn=admin,dc=zb,dc=local
 Password: admin123
 ```
 
@@ -84,9 +90,9 @@ by `sAMAccountName`, not `cn`. Use this only for dev convenience.
 ### 2. Bind-then-search (production-grade)
 
 ```
-1. Bind as the service account (cn=serviceaccount,dc=lmxopcua,dc=local
+1. Bind as the service account (cn=serviceaccount,dc=zb,dc=local
    / serviceaccount123).
-2. Search under dc=lmxopcua,dc=local with filter
+2. Search under dc=zb,dc=local with filter
    (uid=<entered-username>) — or any attribute the deployment
    identifies users by. GLAuth populates uid + cn.
 3. Read the returned entry's DN + memberOf list (groups).
@@ -116,8 +122,8 @@ ldap:
   port: 3893
   useTls: false
   allowInsecureLdap: true       # dev only
-  searchBase: "dc=lmxopcua,dc=local"
-  serviceAccountDn: "cn=serviceaccount,dc=lmxopcua,dc=local"
+  searchBase: "dc=zb,dc=local"
+  serviceAccountDn: "cn=serviceaccount,dc=zb,dc=local"
   serviceAccountPassword: "serviceaccount123"
   userNameAttribute: "uid"      # GLAuth populates this; AD uses sAMAccountName
   displayNameAttribute: "cn"
@@ -131,7 +137,7 @@ ldap:
 ```
 
 `groupAttribute` returns full DNs like
-`ou=ReadOnly,ou=groups,dc=lmxopcua,dc=local` — the authenticator
+`ou=ReadOnly,ou=groups,dc=zb,dc=local` — the authenticator
 should strip the leading `ou=` (or `cn=` against AD) RDN value and
 look that up in `groupToRole`.
 
@@ -172,7 +178,7 @@ server:
 4. `nssm restart GLAuth`
 
 After the restart, `admin`'s `memberOf` includes
-`ou=GwAdmin,ou=groups,dc=lmxopcua,dc=local`, which the authenticator
+`ou=GwAdmin,ou=groups,dc=zb,dc=local`, which the authenticator
 strips to `GwAdmin` and matches against `RequiredGroup`. The same
 pattern applies to any future permission that doesn't fit the existing
 five roles.
@@ -201,7 +207,7 @@ $ldap = New-Object System.DirectoryServices.Protocols.LdapConnection("localhost:
 $ldap.AuthType = [System.DirectoryServices.Protocols.AuthType]::Basic
 $ldap.SessionOptions.ProtocolVersion = 3
 $ldap.SessionOptions.SecureSocketLayer = $false
-$cred = New-Object System.Net.NetworkCredential("cn=admin,dc=lmxopcua,dc=local","admin123")
+$cred = New-Object System.Net.NetworkCredential("cn=admin,dc=zb,dc=local","admin123")
 $ldap.Bind($cred)
 "Bind OK"
 ```
@@ -210,8 +216,8 @@ Or via `ldapsearch` if you have OpenLDAP CLI tools:
 
 ```bash
 ldapsearch -x -H ldap://localhost:3893 \
-  -D "cn=admin,dc=lmxopcua,dc=local" -w admin123 \
-  -b "dc=lmxopcua,dc=local" "(uid=admin)"
+  -D "cn=admin,dc=zb,dc=local" -w admin123 \
+  -b "dc=zb,dc=local" "(uid=admin)"
 ```
 
 The response should list `admin`'s entry with `memberOf` populated for
@@ -257,8 +263,8 @@ applies to mxaccessgw verbatim. Keys that change:
 | `Port` | `3893` | `636` (LDAPS) — AD increasingly rejects plain bind under LDAP-signing enforcement |
 | `UseTls` | `false` | `true` |
 | `AllowInsecureLdap` | `true` | `false` |
-| `SearchBase` | `dc=lmxopcua,dc=local` | `DC=corp,DC=example,DC=com` |
-| `ServiceAccountDn` | `cn=serviceaccount,dc=lmxopcua,dc=local` | `CN=MxGwSvc,OU=Service Accounts,DC=corp,...` |
+| `SearchBase` | `dc=zb,dc=local` | `DC=corp,DC=example,DC=com` |
+| `ServiceAccountDn` | `cn=serviceaccount,dc=zb,dc=local` | `CN=MxGwSvc,OU=Service Accounts,DC=corp,...` |
 | `UserNameAttribute` | `uid` | `sAMAccountName` (or `userPrincipalName`) |
 | `GroupAttribute` | `memberOf` (unchanged) | `memberOf` (unchanged) |
 

nuget.config

@@ -17,6 +17,9 @@
       <package pattern="ZB.MOM.WW.Telemetry" />
       <package pattern="ZB.MOM.WW.Telemetry.*" />
       <package pattern="ZB.MOM.WW.Configuration" />
+      <package pattern="ZB.MOM.WW.Auth" />
+      <package pattern="ZB.MOM.WW.Auth.*" />
+      <package pattern="ZB.MOM.WW.Audit" />
     </packageSource>
   </packageSourceMapping>
 </configuration>

src/ZB.MOM.WW.MxGateway.IntegrationTests/DashboardLdapLiveTests.cs

@@ -1,8 +1,11 @@
 using System.Security.Claims;
 using Microsoft.Extensions.Logging.Abstractions;
 using Microsoft.Extensions.Options;
+using ZB.MOM.WW.Auth.Abstractions.Ldap;
+using ZB.MOM.WW.Auth.Ldap;
 using ZB.MOM.WW.MxGateway.Server.Configuration;
 using ZB.MOM.WW.MxGateway.Server.Dashboard;
+using LibraryLdapOptions = ZB.MOM.WW.Auth.Abstractions.Ldap.LdapOptions;
 
 namespace ZB.MOM.WW.MxGateway.IntegrationTests;
 
@@ -28,12 +31,11 @@ public sealed class DashboardLdapLiveTests
             claim.Type == DashboardAuthenticationDefaults.LdapGroupClaimType
             && claim.Value.Contains("GwAdmin", StringComparison.OrdinalIgnoreCase));
 
-        // IntegrationTests-023: DashboardAuthenticator.CreatePrincipal emits a
-        // ClaimTypes.Role claim derived from MapGroupsToRoles. The seeded
-        // GroupToRole map (GwAdmin -> Admin) means the admin principal must
-        // carry Role=Admin alongside the raw LDAP-group claim. A regression in
-        // MapGroupsToRoles (returning an empty list, missing the RDN fallback)
-        // would silently pass without this assertion.
+        // IntegrationTests-023: DashboardAuthenticator builds the principal with a
+        // ClaimTypes.Role claim resolved from the LDAP groups via the
+        // DashboardGroupRoleMapper. The seeded GroupToRole map (GwAdmin -> Admin)
+        // means the admin principal must carry Role=Admin alongside the raw LDAP-group
+        // claim. A regression in the group→role mapping would fail this assertion.
         Assert.Contains(result.Principal.Claims, claim =>
             claim.Type == ClaimTypes.Role
             && claim.Value == DashboardRoles.Admin);
@@ -59,7 +61,7 @@ public sealed class DashboardLdapLiveTests
     [LiveLdapFact]
     public async Task AuthenticateAsync_AdminWithWrongPassword_FailsWithoutLeakingPassword()
     {
-        // Exercises the LdapException branch: the user exists and the service
+        // Exercises the user-bind-failure branch: the user exists and the service
         // account search succeeds, but the candidate bind is rejected.
         const string wrongPassword = "definitely-not-the-admin-password";
         DashboardAuthenticator authenticator = CreateAuthenticator();
@@ -78,8 +80,8 @@ public sealed class DashboardLdapLiveTests
     [LiveLdapFact]
     public async Task AuthenticateAsync_UnknownUsername_Fails()
     {
-        // Exercises the `candidate is null` branch: the service-account search
-        // returns no entry, so no candidate bind is attempted.
+        // Exercises the user-not-found branch: the service-account search returns no
+        // entry, so no candidate bind is attempted.
         DashboardAuthenticator authenticator = CreateAuthenticator();
 
         DashboardAuthenticationResult result = await authenticator.AuthenticateAsync(
@@ -96,18 +98,13 @@ public sealed class DashboardLdapLiveTests
     public async Task AuthenticateAsync_ServerUnreachable_FailsWithoutThrowing()
     {
         // Exercises the connect-failure path: a closed loopback port produces a
-        // connection error that DashboardAuthenticator must absorb into a Fail
+        // connection error that the shared LdapAuthService must absorb into a Fail
         // result rather than propagating an exception to the dashboard.
-        DashboardAuthenticator authenticator = new(
-            Options.Create(new GatewayOptions
-            {
-                Ldap = new LdapOptions
-                {
-                    // 1 is a reserved port number that no LDAP server listens on.
-                    Port = 1,
-                },
-            }),
-            NullLogger<DashboardAuthenticator>.Instance);
+        DashboardAuthenticator authenticator = CreateAuthenticator(LibraryOptions() with
+        {
+            // 1 is a reserved port number that no LDAP server listens on.
+            Port = 1,
+        });
 
         DashboardAuthenticationResult result = await authenticator.AuthenticateAsync(
             "admin",
@@ -118,19 +115,48 @@ public sealed class DashboardLdapLiveTests
         Assert.Null(result.Principal);
     }
 
-    private static DashboardAuthenticator CreateAuthenticator()
+    private static DashboardAuthenticator CreateAuthenticator() => CreateAuthenticator(LibraryOptions());
+
+    private static DashboardAuthenticator CreateAuthenticator(LibraryLdapOptions ldapOptions)
     {
-        return new DashboardAuthenticator(
-            Options.Create(new GatewayOptions
+        GatewayOptions gatewayOptions = new()
+        {
+            Dashboard = new DashboardOptions
             {
-                Dashboard = new DashboardOptions
+                GroupToRole = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
                 {
-                    GroupToRole = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
-                    {
-                        ["GwAdmin"] = DashboardRoles.Admin,
-                    },
+                    ["GwAdmin"] = DashboardRoles.Admin,
                 },
-            }),
+            },
+        };
+
+        return new DashboardAuthenticator(
+            new LdapAuthService(ldapOptions),
+            new DashboardGroupRoleMapper(Options.Create(gatewayOptions)),
             NullLogger<DashboardAuthenticator>.Instance);
     }
+
+    /// <summary>
+    /// Builds the shared library <see cref="LibraryLdapOptions"/> from the gateway's
+    /// default LDAP settings so the live tests exercise the same seeded directory the
+    /// gateway connects to (localhost:3893, plaintext, with AllowInsecure for dev).
+    /// </summary>
+    private static LibraryLdapOptions LibraryOptions()
+    {
+        ZB.MOM.WW.MxGateway.Server.Configuration.LdapOptions gateway = new();
+        return new LibraryLdapOptions
+        {
+            Enabled = gateway.Enabled,
+            Server = gateway.Server,
+            Port = gateway.Port,
+            Transport = gateway.Transport,
+            AllowInsecure = gateway.AllowInsecure,
+            SearchBase = gateway.SearchBase,
+            ServiceAccountDn = gateway.ServiceAccountDn,
+            ServiceAccountPassword = gateway.ServiceAccountPassword,
+            UserNameAttribute = gateway.UserNameAttribute,
+            DisplayNameAttribute = gateway.DisplayNameAttribute,
+            GroupAttribute = gateway.GroupAttribute,
+        };
+    }
 }

src/ZB.MOM.WW.MxGateway.Server/Configuration/EffectiveLdapConfiguration.cs

@@ -4,8 +4,8 @@ public sealed record EffectiveLdapConfiguration(
     bool Enabled,
     string Server,
     int Port,
-    bool UseTls,
-    bool AllowInsecureLdap,
+    string Transport,
+    bool AllowInsecure,
     string SearchBase,
     string ServiceAccountDn,
     string ServiceAccountPassword,

src/ZB.MOM.WW.MxGateway.Server/Configuration/GatewayConfigurationProvider.cs

@@ -23,8 +23,8 @@ public sealed class GatewayConfigurationProvider(IOptions<GatewayOptions> option
                 Enabled: value.Ldap.Enabled,
                 Server: value.Ldap.Server,
                 Port: value.Ldap.Port,
-                UseTls: value.Ldap.UseTls,
-                AllowInsecureLdap: value.Ldap.AllowInsecureLdap,
+                Transport: value.Ldap.Transport.ToString(),
+                AllowInsecure: value.Ldap.AllowInsecure,
                 SearchBase: value.Ldap.SearchBase,
                 ServiceAccountDn: value.Ldap.ServiceAccountDn,
                 ServiceAccountPassword: RedactedValue,

src/ZB.MOM.WW.MxGateway.Server/Configuration/GatewayOptionsValidator.cs

@@ -1,3 +1,4 @@
+using ZB.MOM.WW.Auth.Abstractions.Ldap;
 using ZB.MOM.WW.Configuration;
 using ZB.MOM.WW.MxGateway.Contracts;
 
@@ -82,9 +83,9 @@ public sealed class GatewayOptionsValidator : OptionsValidatorBase<GatewayOption
             builder);
         builder.Port(options.Port, "MxGateway:Ldap:Port");
 
-        if (!options.UseTls && !options.AllowInsecureLdap)
+        if (options.Transport == LdapTransport.None && !options.AllowInsecure)
         {
-            builder.Add("MxGateway:Ldap:AllowInsecureLdap must be true when UseTls is false.");
+            builder.Add("MxGateway:Ldap:AllowInsecure must be true when Transport is None (plaintext).");
         }
     }
 

src/ZB.MOM.WW.MxGateway.Server/Configuration/LdapOptions.cs

@@ -1,5 +1,32 @@
+using ZB.MOM.WW.Auth.Abstractions.Ldap;
+
 namespace ZB.MOM.WW.MxGateway.Server.Configuration;
 
+/// <summary>
+/// Gateway-side view of the <c>MxGateway:Ldap</c> section. This is a SHADOW of the
+/// shared <see cref="ZB.MOM.WW.Auth.Abstractions.Ldap.LdapOptions"/> type and is NOT
+/// used to perform LDAP authentication at runtime — runtime bind/search is done by the
+/// shared <c>ZB.MOM.WW.Auth.Ldap</c> provider, whose options are bound directly from the
+/// same <c>MxGateway:Ldap</c> section by <c>AddZbLdapAuth</c> (see
+/// <see cref="ZB.MOM.WW.MxGateway.Server.Dashboard.DashboardServiceCollectionExtensions"/>).
+/// <para>
+/// This shadow exists for three things only: (1) startup validation via
+/// <see cref="GatewayOptionsValidator"/>; (2) the redacted effective-config display
+/// (<see cref="EffectiveLdapConfiguration"/> / <see cref="GatewayConfigurationProvider"/>);
+/// and (3) it is the single home of the gateway's dev/default LDAP values, which the
+/// integration live-test helper copies onto the shared options.
+/// </para>
+/// <para>
+/// Review C2 — DRIFT WARNING: this class MUST stay field-compatible with the shared
+/// <see cref="ZB.MOM.WW.Auth.Abstractions.Ldap.LdapOptions"/> so the one config section
+/// binds cleanly onto both. The two are intentionally NOT merged because their defaults
+/// differ on purpose: this shadow ships dev-friendly defaults (plaintext localhost,
+/// <c>AllowInsecure=true</c>, populated <c>SearchBase</c>/<c>ServiceAccount*</c>), whereas
+/// the shared type is secure-by-default (<c>Transport=Ldaps</c>, <c>AllowInsecure=false</c>,
+/// empty DN fields). If you add/rename/remove a field on the shared type, mirror it here
+/// (and in the validator + effective-config) so the section keeps binding to both.
+/// </para>
+/// </summary>
 public sealed class LdapOptions
 {
     /// <summary>Gets a value indicating whether LDAP authentication is enabled.</summary>
@@ -11,17 +38,24 @@ public sealed class LdapOptions
     /// <summary>Gets the LDAP server port.</summary>
     public int Port { get; init; } = 3893;
 
-    /// <summary>Gets a value indicating whether TLS is required for the connection.</summary>
-    public bool UseTls { get; init; }
+    /// <summary>
+    /// Gets the transport/TLS mode for the LDAP connection. Replaces the former
+    /// boolean <c>UseTls</c> (true ≈ <see cref="LdapTransport.Ldaps"/>, false =
+    /// <see cref="LdapTransport.None"/>). <see cref="LdapTransport.StartTls"/> upgrades
+    /// a plaintext connection to TLS. Matches the shared
+    /// <see cref="ZB.MOM.WW.Auth.Abstractions.Ldap.LdapOptions.Transport"/> field so the
+    /// <c>MxGateway:Ldap</c> section binds straight onto the shared options.
+    /// </summary>
+    public LdapTransport Transport { get; init; } = LdapTransport.None;
 
-    /// <summary>Gets a value indicating whether insecure LDAP connections are allowed.</summary>
-    public bool AllowInsecureLdap { get; init; } = true;
+    /// <summary>Gets a value indicating whether insecure (plaintext) LDAP connections are allowed.</summary>
+    public bool AllowInsecure { get; init; } = true;
 
     /// <summary>Gets the LDAP search base distinguished name.</summary>
-    public string SearchBase { get; init; } = "dc=lmxopcua,dc=local";
+    public string SearchBase { get; init; } = "dc=zb,dc=local";
 
     /// <summary>Gets the service account distinguished name.</summary>
-    public string ServiceAccountDn { get; init; } = "cn=serviceaccount,dc=lmxopcua,dc=local";
+    public string ServiceAccountDn { get; init; } = "cn=serviceaccount,dc=zb,dc=local";
 
     /// <summary>Gets the service account password.</summary>
     public string ServiceAccountPassword { get; init; } = "serviceaccount123";

src/ZB.MOM.WW.MxGateway.Server/Dashboard/Components/Pages/SettingsPage.razor

@@ -26,7 +26,7 @@ else
                     <tr><th scope="row">Run migrations</th><td>@Snapshot.Configuration.Authentication.RunMigrationsOnStartup</td></tr>
                     <tr><th scope="row">LDAP enabled</th><td>@Snapshot.Configuration.Ldap.Enabled</td></tr>
                     <tr><th scope="row">LDAP server</th><td>@Snapshot.Configuration.Ldap.Server:@Snapshot.Configuration.Ldap.Port</td></tr>
-                    <tr><th scope="row">LDAP TLS</th><td>@Snapshot.Configuration.Ldap.UseTls</td></tr>
+                    <tr><th scope="row">LDAP transport</th><td>@Snapshot.Configuration.Ldap.Transport</td></tr>
                     <tr><th scope="row">LDAP search base</th><td><code>@Snapshot.Configuration.Ldap.SearchBase</code></td></tr>
                     <tr><th scope="row">LDAP service account</th><td><code>@Snapshot.Configuration.Ldap.ServiceAccountDn</code></td></tr>
                     <tr><th scope="row">LDAP service password</th><td>@Snapshot.Configuration.Ldap.ServiceAccountPassword</td></tr>

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardApiKeyManagementService.cs

@@ -1,5 +1,10 @@
 using System.Security.Claims;
+using System.Text.Json;
 using Microsoft.Data.Sqlite;
+using ZB.MOM.WW.Audit;
+using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
+using ZB.MOM.WW.Auth.ApiKeys.Admin;
+using ZB.MOM.WW.MxGateway.Server.Security.Audit;
 using ZB.MOM.WW.MxGateway.Server.Security.Authentication;
 using ZB.MOM.WW.MxGateway.Server.Security.Authorization;
 
@@ -7,12 +12,13 @@ namespace ZB.MOM.WW.MxGateway.Server.Dashboard;
 
 public sealed class DashboardApiKeyManagementService(
     DashboardApiKeyAuthorization authorization,
+    ApiKeyAdminCommands adminCommands,
     IApiKeyAdminStore adminStore,
-    IApiKeyAuditStore auditStore,
-    IApiKeySecretHasher hasher,
+    IAuditWriter auditWriter,
     IHttpContextAccessor httpContextAccessor) : IDashboardApiKeyManagementService
 {
     private const string UnauthorizedMessage = "Sign in with an authorized LDAP account to manage API keys.";
+    private const string PepperUnavailableMarker = "pepper unavailable";
 
     /// <summary>Determines whether the user can manage API keys.</summary>
     /// <param name="user">The authenticated user principal.</param>
@@ -42,28 +48,31 @@ public sealed class DashboardApiKeyManagementService(
         }
 
         string keyId = request.KeyId.Trim();
-        string secret = ApiKeySecretGenerator.Generate();
-        string apiKey = FormatApiKey(keyId, secret);
 
         try
         {
-            await adminStore.CreateAsync(
-                    new ApiKeyCreateRequest(
-                        KeyId: keyId,
-                        KeyPrefix: $"mxgw_{keyId}",
-                        SecretHash: hasher.HashSecret(secret),
-                        DisplayName: request.DisplayName.Trim(),
-                        Scopes: request.Scopes,
-                        Constraints: request.Constraints,
-                        CreatedUtc: DateTimeOffset.UtcNow),
+            // The shared command set generates the secret, hashes it with the pepper, persists the
+            // record and assembles the mxgw_<id>_<secret> token (shown once). It also appends its own
+            // "create-key" audit entry (now canonicalized through the IApiKeyAuditStore->IAuditWriter
+            // adapter); the dashboard layers a richer "dashboard-create-key" canonical AuditEvent
+            // (Target + CorrelationId + remote address) on top via IAuditWriter to preserve the
+            // dashboard audit vocabulary — both rows land in the canonical audit_event store.
+            CreateKeyResult created = await adminCommands.CreateKeyAsync(
+                    keyId,
+                    request.DisplayName.Trim(),
+                    request.Scopes,
+                    ApiKeyConstraintSerializer.Serialize(request.Constraints),
+                    RemoteAddress(),
                     cancellationToken)
                 .ConfigureAwait(false);
 
-            await AppendAuditAsync(keyId, "dashboard-create-key", null, cancellationToken).ConfigureAwait(false);
+            await WriteDashboardAuditAsync(user, keyId, "dashboard-create-key", null, cancellationToken).ConfigureAwait(false);
 
-            return DashboardApiKeyManagementResult.Success("API key created. Copy the key now; it will not be shown again.", apiKey);
+            return DashboardApiKeyManagementResult.Success(
+                "API key created. Copy the key now; it will not be shown again.",
+                created.Token);
         }
-        catch (ApiKeyPepperUnavailableException)
+        catch (InvalidOperationException exception) when (IsPepperUnavailable(exception))
         {
             return DashboardApiKeyManagementResult.Fail("API key pepper is not configured.");
         }
@@ -94,18 +103,19 @@ public sealed class DashboardApiKeyManagementService(
         }
 
         string normalizedKeyId = keyId.Trim();
-        bool revoked = await adminStore
-            .RevokeAsync(normalizedKeyId, DateTimeOffset.UtcNow, cancellationToken)
+        KeyActionResult result = await adminCommands
+            .RevokeKeyAsync(normalizedKeyId, RemoteAddress(), cancellationToken)
             .ConfigureAwait(false);
 
-        await AppendAuditAsync(
+        await WriteDashboardAuditAsync(
+                user,
                 normalizedKeyId,
                 "dashboard-revoke-key",
-                revoked ? "revoked" : "not-found-or-already-revoked",
+                result.Succeeded ? "revoked" : "not-found-or-already-revoked",
                 cancellationToken)
             .ConfigureAwait(false);
 
-        return revoked
+        return result.Succeeded
             ? DashboardApiKeyManagementResult.Success("API key revoked.")
             : DashboardApiKeyManagementResult.Fail("API key was not found or is already revoked.");
     }
@@ -131,27 +141,30 @@ public sealed class DashboardApiKeyManagementService(
         }
 
         string normalizedKeyId = keyId.Trim();
-        string secret = ApiKeySecretGenerator.Generate();
-        string apiKey = FormatApiKey(normalizedKeyId, secret);
 
         try
         {
-            bool rotated = await adminStore
-                .RotateAsync(normalizedKeyId, hasher.HashSecret(secret), DateTimeOffset.UtcNow, cancellationToken)
+            CreateKeyResult rotated = await adminCommands
+                .RotateKeyAsync(normalizedKeyId, RemoteAddress(), cancellationToken)
                 .ConfigureAwait(false);
 
-            await AppendAuditAsync(
+            bool succeeded = rotated.Token is not null;
+
+            await WriteDashboardAuditAsync(
+                    user,
                     normalizedKeyId,
                     "dashboard-rotate-key",
-                    rotated ? "rotated" : "not-found",
+                    succeeded ? "rotated" : "not-found",
                     cancellationToken)
                 .ConfigureAwait(false);
 
-            return rotated
-                ? DashboardApiKeyManagementResult.Success("API key rotated. Copy the key now; it will not be shown again.", apiKey)
+            return succeeded
+                ? DashboardApiKeyManagementResult.Success(
+                    "API key rotated. Copy the key now; it will not be shown again.",
+                    rotated.Token)
                 : DashboardApiKeyManagementResult.Fail("API key was not found.");
         }
-        catch (ApiKeyPepperUnavailableException)
+        catch (InvalidOperationException exception) when (IsPepperUnavailable(exception))
         {
             return DashboardApiKeyManagementResult.Fail("API key pepper is not configured.");
         }
@@ -182,7 +195,8 @@ public sealed class DashboardApiKeyManagementService(
             .DeleteAsync(normalizedKeyId, cancellationToken)
             .ConfigureAwait(false);
 
-        await AppendAuditAsync(
+        await WriteDashboardAuditAsync(
+                user,
                 normalizedKeyId,
                 "dashboard-delete-key",
                 deleted ? "deleted" : "not-found-or-active",
@@ -194,22 +208,92 @@ public sealed class DashboardApiKeyManagementService(
             : DashboardApiKeyManagementResult.Fail("API key was not found, or is still active. Revoke it before deleting.");
     }
 
-    private async Task AppendAuditAsync(
-        string? keyId,
-        string eventType,
-        string? details,
+    private string? RemoteAddress() =>
+        httpContextAccessor.HttpContext?.Connection.RemoteIpAddress?.ToString();
+
+    /// <summary>
+    /// Resolves the operator's username from the authenticated dashboard principal.
+    /// </summary>
+    /// <remarks>
+    /// The passed <paramref name="user"/> is preferred over the ambient HTTP context because it
+    /// is already in scope at every call site (the callers gate on <see cref="CanManage"/> using
+    /// it) and is unambiguous. Falls back to <see cref="IAuditActorAccessor.CurrentActor"/> for
+    /// defensive coverage, then to <c>"unknown"</c> when neither is available.
+    /// </remarks>
+    private static string ResolveOperatorActor(ClaimsPrincipal user)
+    {
+        // ZbClaimTypes.Username = "zb:username" — the canonical LDAP login name.
+        string? username = user.FindFirstValue(ZB.MOM.WW.Auth.AspNetCore.ZbClaimTypes.Username);
+        if (!string.IsNullOrWhiteSpace(username))
+        {
+            return username;
+        }
+
+        // Framework fallback: Identity.Name is driven by the nameClaimType on the ClaimsIdentity
+        // (set to ZbClaimTypes.Name = ClaimTypes.Name by DashboardAuthenticator → display name).
+        string? identityName = user.Identity?.Name;
+        if (!string.IsNullOrWhiteSpace(identityName))
+        {
+            return identityName;
+        }
+
+        return "unknown";
+    }
+
+    /// <summary>
+    /// Emits the dashboard's own canonical <see cref="AuditEvent"/> for a <c>dashboard-*</c> op
+    /// directly through the best-effort <see cref="IAuditWriter"/> (Task 2.3 #6). This is in
+    /// addition to the <c>create/revoke/rotate-key</c> event that <see cref="ApiKeyAdminCommands"/>
+    /// emits via the canonical-forwarding <c>IApiKeyAuditStore</c> adapter — the doubled-audit
+    /// behaviour is preserved, both rows now land in the canonical <c>audit_event</c> store.
+    /// </summary>
+    /// <remarks>
+    /// Phase 3 (Actor = operator principal): <c>Actor</c> is the LDAP operator who performed the
+    /// action (resolved from the <paramref name="user"/> principal); <c>Target</c> is the managed
+    /// API key id. This fixes the pre-Phase-3 semantic gap where both fields held the keyId.
+    /// </remarks>
+    private async Task WriteDashboardAuditAsync(
+        ClaimsPrincipal user,
+        string keyId,
+        string action,
+        string? detail,
         CancellationToken cancellationToken)
     {
-        await auditStore.AppendAsync(
-                new ApiKeyAuditEntry(
-                    KeyId: keyId,
-                    EventType: eventType,
-                    RemoteAddress: httpContextAccessor.HttpContext?.Connection.RemoteIpAddress?.ToString(),
-                    Details: details),
-                cancellationToken)
-            .ConfigureAwait(false);
+        AuditEvent auditEvent = new()
+        {
+            EventId = Guid.NewGuid(),
+            OccurredAtUtc = DateTimeOffset.UtcNow,
+            Actor = ResolveOperatorActor(user),
+            Action = action,
+            Outcome = AuditOutcome.Success,
+            Category = CanonicalForwardingApiKeyAuditStore.ApiKeyCategory,
+            Target = keyId,
+            SourceNode = RemoteAddress(),
+            CorrelationId = ParseCorrelationId(),
+            DetailsJson = WrapDetail(detail),
+        };
+
+        await auditWriter.WriteAsync(auditEvent, cancellationToken).ConfigureAwait(false);
     }
 
+    /// <summary>
+    /// Derives a correlation id from the ASP.NET Core request trace identifier when it is a
+    /// well-formed GUID; otherwise null (the default <c>HttpContext.TraceIdentifier</c> is the
+    /// connection:request form, not a GUID, so it correlates to null rather than fabricating one).
+    /// </summary>
+    private Guid? ParseCorrelationId() =>
+        Guid.TryParse(httpContextAccessor.HttpContext?.TraceIdentifier, out Guid correlationId)
+            ? correlationId
+            : null;
+
+    private static string? WrapDetail(string? detail) =>
+        detail is null
+            ? null
+            : JsonSerializer.Serialize(new Dictionary<string, string> { ["detail"] = detail });
+
+    private static bool IsPepperUnavailable(InvalidOperationException exception) =>
+        exception.Message.Contains(PepperUnavailableMarker, StringComparison.OrdinalIgnoreCase);
+
     private static string? ValidateCreateRequest(DashboardApiKeyManagementRequest request)
     {
         string? keyIdValidation = ValidateKeyId(request.KeyId);
@@ -248,9 +332,4 @@ public sealed class DashboardApiKeyManagementService(
             ? null
             : "API key id may contain only letters, numbers, periods, and hyphens.";
     }
-
-    private static string FormatApiKey(string keyId, string secret)
-    {
-        return $"mxgw_{keyId}_{secret}";
-    }
 }

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardAuthenticator.cs

@@ -1,14 +1,26 @@
 using System.Security.Claims;
-using System.Text;
-using Microsoft.Extensions.Options;
-using ZB.MOM.WW.MxGateway.Server.Configuration;
-using ZB.MOM.WW.MxGateway.Server.Security.Authorization;
-using Novell.Directory.Ldap;
+using ZB.MOM.WW.Auth.Abstractions.Ldap;
+using ZB.MOM.WW.Auth.Abstractions.Roles;
+using ZB.MOM.WW.Auth.AspNetCore;
 
 namespace ZB.MOM.WW.MxGateway.Server.Dashboard;
 
+/// <summary>
+/// Authenticates interactive dashboard logins against LDAP. The bind/search
+/// mechanics are delegated to the shared <see cref="ILdapAuthService"/>
+/// (<c>ZB.MOM.WW.Auth.Ldap</c>), which performs bind-then-search, fails closed,
+/// and never throws — returning the user's display name and LDAP groups on
+/// success. This class keeps the dashboard-specific policy: groups are resolved
+/// to dashboard roles via <see cref="IGroupRoleMapper{TRole}"/>, a login with no
+/// matching role is denied, and the resulting <see cref="ClaimsPrincipal"/> is
+/// shaped exactly as before (see <see cref="CreatePrincipal"/>).
+/// </summary>
+/// <param name="ldapAuthService">Shared LDAP bind-then-search provider.</param>
+/// <param name="roleMapper">Maps LDAP groups to dashboard roles (Task 1.1 seam).</param>
+/// <param name="logger">Logger for diagnostic, credential-free login outcomes.</param>
 public sealed class DashboardAuthenticator(
-    IOptions<GatewayOptions> options,
+    ILdapAuthService ldapAuthService,
+    IGroupRoleMapper<string> roleMapper,
     ILogger<DashboardAuthenticator> logger) : IDashboardAuthenticator
 {
     private const string GenericFailureMessage = "The username or password is invalid, or the user is not authorized.";
@@ -19,240 +31,72 @@ public sealed class DashboardAuthenticator(
         string? password,
         CancellationToken cancellationToken)
     {
-        LdapOptions ldapOptions = options.Value.Ldap;
-        DashboardOptions dashboardOptions = options.Value.Dashboard;
-        if (!ldapOptions.Enabled
-            || string.IsNullOrWhiteSpace(username)
-            || string.IsNullOrWhiteSpace(password))
-        {
-            return DashboardAuthenticationResult.Fail(GenericFailureMessage);
-        }
-
-        if (!ldapOptions.UseTls && !ldapOptions.AllowInsecureLdap)
+        if (string.IsNullOrWhiteSpace(username) || string.IsNullOrWhiteSpace(password))
         {
             return DashboardAuthenticationResult.Fail(GenericFailureMessage);
         }
 
         string normalizedUsername = username.Trim();
 
-        try
+        // The shared service owns connect/bind/search and the fail-closed contract:
+        // it returns Fail(Disabled) when LDAP is off, enforces TLS-or-AllowInsecure via
+        // its startup validator, and never throws. We only translate its outcome into a
+        // dashboard principal here.
+        LdapAuthResult ldapResult = await ldapAuthService
+            .AuthenticateAsync(normalizedUsername, password, cancellationToken)
+            .ConfigureAwait(false);
+
+        if (!ldapResult.Succeeded)
         {
-            using LdapConnection connection = new();
-            connection.SecureSocketLayer = ldapOptions.UseTls;
-
-            await Task.Run(
-                    () => connection.Connect(ldapOptions.Server, ldapOptions.Port),
-                    cancellationToken)
-                .ConfigureAwait(false);
-
-            await BindServiceAccountAsync(connection, ldapOptions, cancellationToken).ConfigureAwait(false);
-            LdapEntry? candidate = await SearchUserAsync(
-                    connection,
-                    ldapOptions,
-                    normalizedUsername,
-                    cancellationToken)
-                .ConfigureAwait(false);
-
-            if (candidate is null)
-            {
-                return DashboardAuthenticationResult.Fail(GenericFailureMessage);
-            }
-
-            await Task.Run(
-                    () => connection.Bind(candidate.Dn, password),
-                    cancellationToken)
-                .ConfigureAwait(false);
-
-            await BindServiceAccountAsync(connection, ldapOptions, cancellationToken).ConfigureAwait(false);
-            LdapEntry? authenticatedEntry = await SearchUserAsync(
-                    connection,
-                    ldapOptions,
-                    normalizedUsername,
-                    cancellationToken)
-                .ConfigureAwait(false);
-
-            if (authenticatedEntry is null)
-            {
-                return DashboardAuthenticationResult.Fail(GenericFailureMessage);
-            }
-
-            string displayName = ReadAttribute(authenticatedEntry, ldapOptions.DisplayNameAttribute)
-                ?? normalizedUsername;
-            IReadOnlyList<string> groups = ReadAttributeValues(authenticatedEntry, ldapOptions.GroupAttribute);
-
-            IReadOnlyList<string> roles = MapGroupsToRoles(groups, dashboardOptions.GroupToRole);
-            if (roles.Count == 0)
-            {
-                logger.LogInformation(
-                    "LDAP dashboard login denied for user {User}: no GroupToRole mapping matched their LDAP groups.",
-                    normalizedUsername);
-
-                return DashboardAuthenticationResult.Fail(GenericFailureMessage);
-            }
-
-            return DashboardAuthenticationResult.Success(CreatePrincipal(
-                normalizedUsername,
-                displayName,
-                groups,
-                roles));
+            return DashboardAuthenticationResult.Fail(GenericFailureMessage);
         }
-        catch (OperationCanceledException)
-        {
-            throw;
-        }
-        catch (LdapException ex)
+
+        GroupRoleMapping<string> mapping = await roleMapper
+            .MapAsync(ldapResult.Groups, cancellationToken)
+            .ConfigureAwait(false);
+
+        IReadOnlyList<string> roles = mapping.Roles;
+        if (roles.Count == 0)
         {
+            // Preserve the long-standing "no roles matched -> login denied" rule.
             logger.LogInformation(
-                "LDAP dashboard login rejected for user {User}: result code {ResultCode}.",
-                normalizedUsername,
-                ex.ResultCode);
+                "LDAP dashboard login denied for user {User}: no GroupToRole mapping matched their LDAP groups.",
+                ldapResult.Username);
 
             return DashboardAuthenticationResult.Fail(GenericFailureMessage);
         }
-        catch (Exception ex)
-        {
-            logger.LogError(ex, "Unexpected LDAP dashboard login error for user {User}.", normalizedUsername);
 
-            return DashboardAuthenticationResult.Fail(GenericFailureMessage);
-        }
-    }
-
-    /// <summary>Escapes special characters in LDAP filter strings.</summary>
-    /// <param name="value">The string value to escape.</param>
-    internal static string EscapeLdapFilter(string value)
-    {
-        StringBuilder builder = new(value.Length);
-        foreach (char character in value)
-        {
-            builder.Append(character switch
-            {
-                '\\' => @"\5c",
-                '*' => @"\2a",
-                '(' => @"\28",
-                ')' => @"\29",
-                '\0' => @"\00",
-                _ => character.ToString()
-            });
-        }
-
-        return builder.ToString();
+        return DashboardAuthenticationResult.Success(CreatePrincipal(
+            ldapResult.Username,
+            ldapResult.DisplayName,
+            ldapResult.Groups,
+            roles));
     }
 
     /// <summary>
-    /// Maps the user's LDAP groups to dashboard roles. A user can pick up
-    /// multiple roles; Admin and Viewer are the only legal values. Returns
-    /// an empty list when no group matches (caller rejects the login).
+    /// Builds the dashboard <see cref="ClaimsPrincipal"/> from the LDAP outcome.
     /// </summary>
-    /// <param name="groups">The collection of LDAP groups the user belongs to.</param>
-    /// <param name="groupToRole">The mapping from group names to dashboard role names.</param>
-    internal static IReadOnlyList<string> MapGroupsToRoles(
-        IEnumerable<string> groups,
-        IReadOnlyDictionary<string, string> groupToRole)
-    {
-        if (groupToRole.Count == 0)
-        {
-            return [];
-        }
-
-        HashSet<string> roles = new(StringComparer.Ordinal);
-        foreach (string group in groups)
-        {
-            string normalizedGroup = group.Trim();
-
-            // Lookup precedence (Server-040): the full literal group string is
-            // tried first; only if that misses do we fall back to the leading
-            // RDN value (e.g. "GwAdmin" extracted from
-            // "ou=GwAdmin,ou=groups,..."). The map's comparer is
-            // OrdinalIgnoreCase (see DashboardOptions.GroupToRole), so e.g.
-            // "GwAdmin" and "gwadmin" both match.
-            if (groupToRole.TryGetValue(normalizedGroup, out string? mapped)
-                || groupToRole.TryGetValue(ExtractFirstRdnValue(normalizedGroup), out mapped))
-            {
-                roles.Add(mapped);
-            }
-        }
-
-        return [.. roles];
-    }
-
-    /// <summary>Extracts the first RDN value from a distinguished name.</summary>
-    /// <param name="distinguishedName">The LDAP distinguished name.</param>
-    internal static string ExtractFirstRdnValue(string distinguishedName)
-    {
-        int equalsIndex = distinguishedName.IndexOf('=');
-        if (equalsIndex < 0)
-        {
-            return distinguishedName;
-        }
-
-        int valueStart = equalsIndex + 1;
-        int commaIndex = distinguishedName.IndexOf(',', valueStart);
-
-        return commaIndex > valueStart
-            ? distinguishedName[valueStart..commaIndex]
-            : distinguishedName[valueStart..];
-    }
-
-    private static Task BindServiceAccountAsync(
-        LdapConnection connection,
-        LdapOptions ldapOptions,
-        CancellationToken cancellationToken)
-    {
-        return Task.Run(
-            () => connection.Bind(ldapOptions.ServiceAccountDn, ldapOptions.ServiceAccountPassword),
-            cancellationToken);
-    }
-
-    private static async Task<LdapEntry?> SearchUserAsync(
-        LdapConnection connection,
-        LdapOptions ldapOptions,
-        string username,
-        CancellationToken cancellationToken)
-    {
-        string filter = $"({ldapOptions.UserNameAttribute}={EscapeLdapFilter(username)})";
-        ILdapSearchResults results = await Task.Run(
-                () => connection.Search(
-                    ldapOptions.SearchBase,
-                    LdapConnection.ScopeSub,
-                    filter,
-                    attrs: null,
-                    typesOnly: false),
-                cancellationToken)
-            .ConfigureAwait(false);
-
-        LdapEntry? entry = null;
-        while (results.HasMore())
-        {
-            LdapEntry next = results.Next();
-            if (entry is not null)
-            {
-                return null;
-            }
-
-            entry = next;
-        }
-
-        return entry;
-    }
-
-    private static string? ReadAttribute(LdapEntry entry, string attributeName)
-    {
-        return ReadLdapAttribute(entry, attributeName)?.StringValue;
-    }
-
-    private static IReadOnlyList<string> ReadAttributeValues(LdapEntry entry, string attributeName)
-    {
-        LdapAttribute? attribute = ReadLdapAttribute(entry, attributeName);
-        return attribute?.StringValueArray ?? [];
-    }
-
-    private static LdapAttribute? ReadLdapAttribute(LdapEntry entry, string attributeName)
-    {
-        return entry.GetAttribute(attributeName)
-            ?? entry.GetAttribute(attributeName.ToLowerInvariant())
-            ?? entry.GetAttribute(attributeName.ToUpperInvariant());
-    }
-
+    /// <param name="username">
+    /// The (trimmed) login name. Emitted as <see cref="ClaimTypes.NameIdentifier"/> (kept for
+    /// back-compat reads) and as the canonical <see cref="ZbClaimTypes.Username"/> ("zb:username").
+    /// </param>
+    /// <param name="displayName">
+    /// The user's display name. Emitted as <see cref="ZbClaimTypes.Name"/> (= <see cref="ClaimTypes.Name"/>
+    /// so <c>Identity.Name</c> resolves) and as <see cref="ZbClaimTypes.DisplayName"/> ("zb:displayname")
+    /// for cross-app consistency.
+    /// </param>
+    /// <param name="groups">
+    /// The user's LDAP groups, as returned by <see cref="ILdapAuthService"/>. NOTE
+    /// (review C1): these are <b>already-normalized short RDN names</b> (e.g.
+    /// <c>GwAdmin</c>), not raw distinguished names. The shared
+    /// <c>ZB.MOM.WW.Auth.Ldap</c> provider strips each group DN to its first RDN
+    /// value before returning it, so the <see cref="DashboardAuthenticationDefaults.LdapGroupClaimType"/>
+    /// claim carries the short name. This differs from the pre-cutover behaviour,
+    /// which surfaced the raw <c>memberOf</c> values (full DNs) on the claim; the
+    /// claim is informational only (no policy or UI reads its value — authorization
+    /// is role-based), so the shape change is non-breaking for dashboard consumers.
+    /// </param>
+    /// <param name="roles">The dashboard roles resolved from <paramref name="groups"/>.</param>
     private static ClaimsPrincipal CreatePrincipal(
         string username,
         string displayName,
@@ -261,11 +105,21 @@ public sealed class DashboardAuthenticator(
     {
         List<Claim> claims =
         [
+            // Keep NameIdentifier so any existing read-site that uses it continues to work.
             new Claim(ClaimTypes.NameIdentifier, username),
-            new Claim(ClaimTypes.Name, displayName),
+            // Canonical login-username claim (Task 1.5).
+            new Claim(ZbClaimTypes.Username, username),
+            // ZbClaimTypes.Name == ClaimTypes.Name — drives Identity.Name resolution.
+            new Claim(ZbClaimTypes.Name, displayName),
+            // Canonical display-name claim for cross-app consistency (Task 1.5).
+            new Claim(ZbClaimTypes.DisplayName, displayName),
         ];
 
-        claims.AddRange(roles.Select(role => new Claim(ClaimTypes.Role, role)));
+        // ZbClaimTypes.Role == ClaimTypes.Role — drives IsInRole and [Authorize(Roles=...)].
+        claims.AddRange(roles.Select(role => new Claim(ZbClaimTypes.Role, role)));
+        // Groups are short RDN names from ILdapAuthService (see param doc above), so
+        // this claim value is the short group name, not the original DN.
+        // LdapGroupClaimType is MxGateway-specific ("mxgateway:ldap_group") — no ZbClaimType for groups.
         claims.AddRange(groups.Select(group => new Claim(
             DashboardAuthenticationDefaults.LdapGroupClaimType,
             group)));
@@ -273,8 +127,8 @@ public sealed class DashboardAuthenticator(
         ClaimsIdentity claimsIdentity = new(
             claims,
             DashboardAuthenticationDefaults.AuthenticationScheme,
-            ClaimTypes.Name,
-            ClaimTypes.Role);
+            ZbClaimTypes.Name,
+            ZbClaimTypes.Role);
 
         return new ClaimsPrincipal(claimsIdentity);
     }

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardGroupRoleMapper.cs

@@ -0,0 +1,31 @@
+using Microsoft.Extensions.Options;
+using ZB.MOM.WW.Auth.Abstractions.Roles;
+using ZB.MOM.WW.MxGateway.Server.Configuration;
+
+namespace ZB.MOM.WW.MxGateway.Server.Dashboard;
+
+/// <summary>
+/// Shared-Auth <see cref="IGroupRoleMapper{TRole}"/> seam over the dashboard's
+/// LDAP-group → role mapping. Roles are plain strings
+/// (<see cref="DashboardRoles.Admin"/> / <see cref="DashboardRoles.Viewer"/>),
+/// so <c>TRole</c> is <see cref="string"/>. The mapping rules (full-DN first,
+/// leading-RDN fallback, case-insensitive) live in
+/// <see cref="DashboardGroupRoleMapping"/>, shared with
+/// <see cref="DashboardAuthenticator"/> so behaviour stays identical.
+/// </summary>
+/// <param name="options">Gateway options supplying the dashboard GroupToRole map.</param>
+public sealed class DashboardGroupRoleMapper(IOptions<GatewayOptions> options)
+    : IGroupRoleMapper<string>
+{
+    /// <inheritdoc />
+    public Task<GroupRoleMapping<string>> MapAsync(
+        IReadOnlyList<string> groups,
+        CancellationToken ct)
+    {
+        IReadOnlyList<string> roles = DashboardGroupRoleMapping.MapGroupsToRoles(
+            groups,
+            options.Value.Dashboard.GroupToRole);
+
+        return Task.FromResult(new GroupRoleMapping<string>(roles, Scope: null));
+    }
+}

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardGroupRoleMapping.cs

@@ -0,0 +1,79 @@
+namespace ZB.MOM.WW.MxGateway.Server.Dashboard;
+
+/// <summary>
+/// Single source of truth for mapping a user's LDAP groups to dashboard roles.
+/// Both <see cref="DashboardAuthenticator"/> (the existing login flow) and
+/// <see cref="DashboardGroupRoleMapper"/> (the shared-Auth
+/// <see cref="ZB.MOM.WW.Auth.Abstractions.Roles.IGroupRoleMapper{TRole}"/> seam)
+/// delegate here so the precedence and case rules stay identical.
+/// </summary>
+internal static class DashboardGroupRoleMapping
+{
+    /// <summary>
+    /// Maps the user's LDAP groups to dashboard roles. A user can pick up
+    /// multiple roles; Admin and Viewer are the only legal values. Returns
+    /// an empty list when no group matches (caller rejects the login).
+    /// </summary>
+    /// <param name="groups">The collection of LDAP groups the user belongs to.</param>
+    /// <param name="groupToRole">The mapping from group names to dashboard role names.</param>
+    internal static IReadOnlyList<string> MapGroupsToRoles(
+        IEnumerable<string> groups,
+        IReadOnlyDictionary<string, string> groupToRole)
+    {
+        if (groupToRole.Count == 0)
+        {
+            return [];
+        }
+
+        HashSet<string> roles = new(StringComparer.Ordinal);
+        foreach (string group in groups)
+        {
+            string normalizedGroup = group.Trim();
+
+            // Lookup precedence (Server-040): the full literal group string is
+            // tried first; only if that misses do we fall back to the leading
+            // RDN value (e.g. "GwAdmin" extracted from
+            // "ou=GwAdmin,ou=groups,..."). The map's comparer is
+            // OrdinalIgnoreCase (see DashboardOptions.GroupToRole), so e.g.
+            // "GwAdmin" and "gwadmin" both match.
+            //
+            // Review C1: with the shared ZB.MOM.WW.Auth.Ldap provider, groups
+            // arrive here already stripped to short RDN names (the library calls
+            // FirstRdnValue before returning them). So through the live login path
+            // the full-string branch only ever sees short names and the RDN
+            // fallback is effectively a no-op — they collapse to the same key.
+            // The fallback is retained because this mapping is also reachable
+            // directly via the IGroupRoleMapper<string> seam (DashboardGroupRoleMapper),
+            // where a caller could still pass a full DN. CONSEQUENCE: configuring a
+            // full-DN GroupToRole *key* (e.g. "ou=GwAdmin,ou=groups,...") is
+            // UNSUPPORTED with the shared library — the incoming group is a short
+            // name, so it will never equal a full-DN key. Keep GroupToRole keys as
+            // short group names.
+            if (groupToRole.TryGetValue(normalizedGroup, out string? mapped)
+                || groupToRole.TryGetValue(ExtractFirstRdnValue(normalizedGroup), out mapped))
+            {
+                roles.Add(mapped);
+            }
+        }
+
+        return [.. roles];
+    }
+
+    /// <summary>Extracts the first RDN value from a distinguished name.</summary>
+    /// <param name="distinguishedName">The LDAP distinguished name.</param>
+    internal static string ExtractFirstRdnValue(string distinguishedName)
+    {
+        int equalsIndex = distinguishedName.IndexOf('=');
+        if (equalsIndex < 0)
+        {
+            return distinguishedName;
+        }
+
+        int valueStart = equalsIndex + 1;
+        int commaIndex = distinguishedName.IndexOf(',', valueStart);
+
+        return commaIndex > valueStart
+            ? distinguishedName[valueStart..commaIndex]
+            : distinguishedName[valueStart..];
+    }
+}

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardRoles.cs

@@ -8,8 +8,10 @@ public static class DashboardRoles
 {
     /// <summary>
     /// Read-write access: API-key CRUD, settings, any state-changing UI.
+    /// Canonical role value (Task 1.7); formerly <c>"Admin"</c> — pure value
+    /// rename, the operations this role authorizes are unchanged.
     /// </summary>
-    public const string Admin = "Admin";
+    public const string Admin = "Administrator";
 
     /// <summary>
     /// Read-only access: all pages render but write affordances are hidden.

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardServiceCollectionExtensions.cs

@@ -1,8 +1,12 @@
 using Microsoft.AspNetCore.Authentication;
 using Microsoft.AspNetCore.Authentication.Cookies;
 using Microsoft.AspNetCore.Authorization;
+using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.Options;
+using ZB.MOM.WW.Auth.Abstractions.Roles;
+using ZB.MOM.WW.Auth.AspNetCore;
 using ZB.MOM.WW.MxGateway.Server.Configuration;
+using ZB.MOM.WW.MxGateway.Server.Security.Audit;
 
 namespace ZB.MOM.WW.MxGateway.Server.Dashboard;
 
@@ -15,11 +19,25 @@ public static class DashboardServiceCollectionExtensions
     /// Registers all dashboard services, authentication, and Razor components.
     /// </summary>
     /// <param name="services">Service collection to register services.</param>
-    public static IServiceCollection AddGatewayDashboard(this IServiceCollection services)
+    /// <param name="configuration">
+    /// Application configuration, used to bind the shared LDAP provider's options
+    /// from the <c>MxGateway:Ldap</c> section.
+    /// </param>
+    public static IServiceCollection AddGatewayDashboard(
+        this IServiceCollection services,
+        IConfiguration configuration)
     {
+        // Dashboard logins delegate bind/search to the shared ZB.MOM.WW.Auth.Ldap
+        // provider. Its LdapOptions bind straight from MxGateway:Ldap (the gateway's
+        // LdapOptions field names match the shared options: Transport / AllowInsecure /
+        // SearchBase / ServiceAccount* / *Attribute). AddZbLdapAuth also adds a
+        // ValidateOnStart() so an insecure-transport misconfiguration fails fast at boot.
+        services.AddZbLdapAuth(configuration, "MxGateway:Ldap");
+
         services.AddSingleton<IDashboardSnapshotService, DashboardSnapshotService>();
         services.AddSingleton<IDashboardLiveDataService, DashboardLiveDataService>();
         services.AddSingleton<IDashboardAuthenticator, DashboardAuthenticator>();
+        services.AddSingleton<IGroupRoleMapper<string>, DashboardGroupRoleMapper>();
         services.AddSingleton<DashboardApiKeyAuthorization>();
         services.AddSingleton<IDashboardApiKeyManagementService, DashboardApiKeyManagementService>();
         services.AddSingleton<IDashboardSessionAdminService, DashboardSessionAdminService>();
@@ -30,6 +48,7 @@ public static class DashboardServiceCollectionExtensions
         services.AddHostedService<Hubs.DashboardSnapshotPublisher>();
         services.AddHostedService<Hubs.AlarmsHubPublisher>();
         services.AddHttpContextAccessor();
+        services.AddSingleton<IAuditActorAccessor, HttpAuditActorAccessor>();
         services.AddAntiforgery();
         services.AddCascadingAuthenticationState();
         services.AddRazorComponents()
@@ -40,23 +59,25 @@ public static class DashboardServiceCollectionExtensions
             .AddAuthentication(DashboardAuthenticationDefaults.AuthenticationScheme)
             .AddCookie(DashboardAuthenticationDefaults.AuthenticationScheme, cookieOptions =>
             {
+                // Hardened defaults (HttpOnly, SameSite=Strict, SecurePolicy, SlidingExpiration,
+                // ExpireTimeSpan) via the shared ZbCookieDefaults.Apply. requireHttps is set to
+                // its default (true / Always) here and overridden per-environment by the
+                // PostConfigure below; the 8-hour idle timeout is preserved (not the 30-min default).
+                ZbCookieDefaults.Apply(cookieOptions, requireHttps: true, idleTimeout: TimeSpan.FromHours(8));
+                // Cookie name, path, and redirect paths are MxGateway-specific — set after Apply
+                // so they are never overwritten by the shared helper (Apply intentionally skips name).
                 cookieOptions.Cookie.Name = DashboardAuthenticationDefaults.CookieName;
-                cookieOptions.Cookie.HttpOnly = true;
-                cookieOptions.Cookie.SameSite = SameSiteMode.Strict;
-                // SecurePolicy is bound via PostConfigure below so it can honour
-                // DashboardOptions.RequireHttpsCookie (default Always; dev HTTP
-                // deployments set RequireHttpsCookie=false to use SameAsRequest).
                 cookieOptions.Cookie.Path = "/";
                 cookieOptions.LoginPath = "/login";
                 cookieOptions.LogoutPath = "/logout";
                 cookieOptions.AccessDeniedPath = "/denied";
-                cookieOptions.ExpireTimeSpan = TimeSpan.FromHours(8);
-                cookieOptions.SlidingExpiration = true;
             })
             .AddScheme<AuthenticationSchemeOptions, HubTokenAuthenticationHandler>(
                 DashboardAuthenticationDefaults.HubAuthenticationScheme,
                 _ => { });
 
+        // Honour DashboardOptions.RequireHttpsCookie (default true / Always; set false for dev
+        // HTTP deployments → SameAsRequest). This overrides the Apply default above.
         services.AddOptions<CookieAuthenticationOptions>(DashboardAuthenticationDefaults.AuthenticationScheme)
             .Configure<IOptions<GatewayOptions>>((cookieOptions, gatewayOptions) =>
             {

src/ZB.MOM.WW.MxGateway.Server/Dashboard/DashboardSnapshotService.cs

@@ -2,6 +2,7 @@ using System.Runtime.CompilerServices;
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Logging.Abstractions;
 using Microsoft.Extensions.Options;
+using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
 using ZB.MOM.WW.MxGateway.Server.Configuration;
 using ZB.MOM.WW.MxGateway.Server.Galaxy;
 using ZB.MOM.WW.MxGateway.Server.Metrics;
@@ -242,7 +243,7 @@ public sealed class DashboardSnapshotService : IDashboardSnapshotService
                     KeyId: key.KeyId,
                     DisplayName: key.DisplayName,
                     Scopes: key.Scopes,
-                    Constraints: key.Constraints,
+                    Constraints: ApiKeyConstraintSerializer.Deserialize(key.ConstraintsJson),
                     CreatedUtc: key.CreatedUtc,
                     LastUsedUtc: key.LastUsedUtc,
                     RevokedUtc: key.RevokedUtc))

src/ZB.MOM.WW.MxGateway.Server/Diagnostics/AuthStoreHealthCheck.cs

@@ -1,6 +1,6 @@
 using Microsoft.Data.Sqlite;
 using Microsoft.Extensions.Diagnostics.HealthChecks;
-using ZB.MOM.WW.MxGateway.Server.Security.Authentication;
+using ZB.MOM.WW.Auth.ApiKeys.Sqlite;
 
 namespace ZB.MOM.WW.MxGateway.Server.Diagnostics;
 

src/ZB.MOM.WW.MxGateway.Server/GatewayApplication.cs

@@ -66,7 +66,7 @@ public static class GatewayApplication
         builder.AddZbSerilog(o => o.ServiceName = "mxgateway");
 
         builder.Services.AddGatewayConfiguration(builder.Configuration);
-        builder.Services.AddSqliteAuthStore();
+        builder.Services.AddSqliteAuthStore(builder.Configuration);
         builder.Services.AddGatewayGrpcAuthorization();
         builder.Services.AddHealthChecks()
             .AddTypeActivatedCheck<AuthStoreHealthCheck>(
@@ -91,7 +91,7 @@ public static class GatewayApplication
         builder.Services.AddWorkerProcessLauncher();
         builder.Services.AddGatewaySessions();
         builder.Services.AddGatewayAlarms();
-        builder.Services.AddGatewayDashboard();
+        builder.Services.AddGatewayDashboard(builder.Configuration);
         builder.Services.AddGalaxyRepository();
 
         return builder;

src/ZB.MOM.WW.MxGateway.Server/Security/Audit/CanonicalAuditWriter.cs

@@ -0,0 +1,42 @@
+using ZB.MOM.WW.Audit;
+
+namespace ZB.MOM.WW.MxGateway.Server.Security.Audit;
+
+/// <summary>
+/// Best-effort <see cref="IAuditWriter"/> over the MxGateway-owned
+/// <see cref="SqliteCanonicalAuditStore"/>. It honours the canonical
+/// <see cref="IAuditWriter"/> contract: a failed audit write is swallowed and logged
+/// rather than propagated, so it can never abort the user-facing action that produced it.
+/// </summary>
+/// <remarks>
+/// This is the single sink through which ALL MxGateway audit flows — the library admin
+/// verbs (via <see cref="CanonicalForwardingApiKeyAuditStore"/>) and the gateway's own
+/// dashboard / constraint-denial producers, which write canonical events directly. The
+/// best-effort wrapping here also closes the gap that the library's
+/// <c>SqliteApiKeyAuditStore.AppendAsync</c> propagated exceptions.
+/// </remarks>
+public sealed class CanonicalAuditWriter(
+    SqliteCanonicalAuditStore store,
+    ILogger<CanonicalAuditWriter> logger) : IAuditWriter
+{
+    /// <inheritdoc />
+    public async Task WriteAsync(AuditEvent auditEvent, CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(auditEvent);
+
+        try
+        {
+            await store.InsertAsync(auditEvent, cancellationToken).ConfigureAwait(false);
+        }
+        catch (Exception exception)
+        {
+            // Best-effort: a failed audit write must never abort the action that produced it.
+            // Swallow everything (including OperationCanceledException) and log for diagnosis.
+            logger.LogWarning(
+                exception,
+                "Failed to persist audit event {EventId} (action {Action}); audit write is best-effort and was suppressed.",
+                auditEvent.EventId,
+                auditEvent.Action);
+        }
+    }
+}

src/ZB.MOM.WW.MxGateway.Server/Security/Audit/CanonicalForwardingApiKeyAuditStore.cs

@@ -0,0 +1,143 @@
+using System.Text.Json;
+using ZB.MOM.WW.Audit;
+using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
+
+namespace ZB.MOM.WW.MxGateway.Server.Security.Audit;
+
+/// <summary>
+/// Adapter that overrides the shared library's <see cref="IApiKeyAuditStore"/> so that
+/// library-emitted API-key audit events (CLI / admin verbs from
+/// <c>ApiKeyAdminCommands</c>) are canonicalized onto <see cref="AuditEvent"/> and routed
+/// through the gateway's <see cref="IAuditWriter"/> into the canonical
+/// <c>audit_event</c> store.
+/// </summary>
+/// <remarks>
+/// Overriding the registered <see cref="IApiKeyAuditStore"/> is the ONLY way to
+/// canonicalize the library-internal <c>ApiKeyAdminCommands</c> events, since that type
+/// cannot be edited. <see cref="ListRecentAsync"/> reads back from the canonical store
+/// and maps each <see cref="AuditEvent"/> to an <see cref="ApiKeyAuditEntry"/> so the
+/// existing dashboard "recent audit" view (and the CLI/store tests) keep working through
+/// this same seam, unchanged.
+/// <para>
+/// The library's own <c>api_key_audit</c> table is left in place but UNUSED — nothing
+/// writes to it once this adapter overrides the library's <c>SqliteApiKeyAuditStore</c>
+/// registration.
+/// </para>
+/// </remarks>
+public sealed class CanonicalForwardingApiKeyAuditStore(
+    IAuditWriter auditWriter,
+    SqliteCanonicalAuditStore store) : IApiKeyAuditStore
+{
+    /// <summary>The canonical <see cref="AuditEvent.Category"/> assigned to API-key events.</summary>
+    public const string ApiKeyCategory = "ApiKey";
+
+    /// <summary>Actor used for the library's keyless <c>init-db</c> event.</summary>
+    private const string SystemActor = "system";
+
+    /// <summary>Actor used for any other keyless (CLI-originated) library event.</summary>
+    private const string CliActor = "cli";
+
+    /// <summary>The library event type that denotes a constraint denial.</summary>
+    private const string ConstraintDeniedEventType = "constraint-denied";
+
+    /// <summary>The library's keyless schema-init event type.</summary>
+    private const string InitDbEventType = "init-db";
+
+    /// <inheritdoc />
+    public async Task AppendAsync(ApiKeyAuditEntry entry, CancellationToken ct)
+    {
+        ArgumentNullException.ThrowIfNull(entry);
+
+        AuditEvent auditEvent = new()
+        {
+            EventId = Guid.NewGuid(),
+            OccurredAtUtc = entry.CreatedUtc,
+            // Keyless library events: init-db is system-originated; any other keyless event
+            // is a CLI/admin verb run without an authenticated principal.
+            Actor = entry.KeyId
+                ?? (entry.EventType == InitDbEventType ? SystemActor : CliActor),
+            Action = entry.EventType,
+            Outcome = entry.EventType == ConstraintDeniedEventType
+                ? AuditOutcome.Denied
+                : AuditOutcome.Success,
+            Category = ApiKeyCategory,
+            Target = entry.KeyId,
+            SourceNode = entry.RemoteAddress,
+            CorrelationId = null,
+            DetailsJson = WrapDetails(entry.Details),
+        };
+
+        // Best-effort: IAuditWriter swallows/logs failures, so this never throws.
+        await auditWriter.WriteAsync(auditEvent, ct).ConfigureAwait(false);
+    }
+
+    /// <inheritdoc />
+    public async Task<IReadOnlyList<ApiKeyAuditEntry>> ListRecentAsync(int limit, CancellationToken ct)
+    {
+        IReadOnlyList<AuditEvent> events = await store.ListRecentAsync(limit, ct).ConfigureAwait(false);
+
+        ApiKeyAuditEntry[] entries = new ApiKeyAuditEntry[events.Count];
+        for (int index = 0; index < events.Count; index++)
+        {
+            AuditEvent auditEvent = events[index];
+            entries[index] = new ApiKeyAuditEntry(
+                KeyId: auditEvent.Actor switch
+                {
+                    // Keyless library events were mapped to the system/cli sentinel actors on the
+                    // way in; map them back to a null KeyId so the dashboard view is faithful.
+                    SystemActor or CliActor => null,
+                    string actor => actor,
+                },
+                EventType: auditEvent.Action,
+                RemoteAddress: auditEvent.SourceNode,
+                CreatedUtc: auditEvent.OccurredAtUtc,
+                Details: UnwrapDetails(auditEvent.DetailsJson));
+        }
+
+        return entries;
+    }
+
+    /// <summary>
+    /// Wraps a free-form library detail string into the canonical
+    /// <c>{"detail": "&lt;escaped&gt;"}</c> JSON envelope, or null when there is no detail.
+    /// </summary>
+    private static string? WrapDetails(string? details)
+    {
+        if (details is null)
+        {
+            return null;
+        }
+
+        return JsonSerializer.Serialize(new Dictionary<string, string> { ["detail"] = details });
+    }
+
+    /// <summary>
+    /// Unwraps the canonical detail envelope back to the original free-form string. Falls
+    /// back to the raw JSON when it is not a recognised <c>{"detail": ...}</c> envelope, so
+    /// directly-emitted canonical events (whose DetailsJson is richer) still surface text.
+    /// </summary>
+    private static string? UnwrapDetails(string? detailsJson)
+    {
+        if (string.IsNullOrEmpty(detailsJson))
+        {
+            return null;
+        }
+
+        try
+        {
+            using JsonDocument document = JsonDocument.Parse(detailsJson);
+            if (document.RootElement.ValueKind == JsonValueKind.Object
+                && document.RootElement.TryGetProperty("detail", out JsonElement detail)
+                && detail.ValueKind == JsonValueKind.String)
+            {
+                return detail.GetString();
+            }
+        }
+        catch (JsonException)
+        {
+            // Not JSON we recognise; surface the raw payload below.
+        }
+
+        return detailsJson;
+    }
+}

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

@@ -0,0 +1,51 @@
+using System.Security.Claims;
+using ZB.MOM.WW.Auth.AspNetCore;
+
+namespace ZB.MOM.WW.MxGateway.Server.Security.Audit;
+
+/// <summary>
+/// HTTP-context-backed implementation of <see cref="IAuditActorAccessor"/> that reads the
+/// dashboard operator's identity from the current <see cref="IHttpContextAccessor"/>.
+/// </summary>
+/// <remarks>
+/// Claim resolution order:
+/// <list type="number">
+///   <item><see cref="ZbClaimTypes.Username"/> ("zb:username") — the canonical LDAP login name.</item>
+///   <item><see cref="ClaimsPrincipal.Identity"/>.<see cref="System.Security.Principal.IIdentity.Name"/> — framework fallback (= <see cref="ZbClaimTypes.Name"/> = <see cref="ClaimTypes.Name"/> = display name).</item>
+///   <item><see cref="ZbClaimTypes.Name"/> — explicit fallback matching the claim emitted by <c>DashboardAuthenticator.CreatePrincipal</c>.</item>
+/// </list>
+/// Returns <see langword="null"/> when there is no HTTP context or the user is not authenticated.
+/// </remarks>
+public sealed class HttpAuditActorAccessor(IHttpContextAccessor httpContextAccessor) : IAuditActorAccessor
+{
+    /// <inheritdoc />
+    public string? CurrentActor
+    {
+        get
+        {
+            ClaimsPrincipal? user = httpContextAccessor.HttpContext?.User;
+            if (user?.Identity?.IsAuthenticated != true)
+            {
+                return null;
+            }
+
+            // Prefer the canonical login-username claim (set by DashboardAuthenticator).
+            string? username = user.FindFirstValue(ZbClaimTypes.Username);
+            if (!string.IsNullOrWhiteSpace(username))
+            {
+                return username;
+            }
+
+            // Framework fallback: Identity.Name is driven by the ClaimsIdentity nameClaimType,
+            // which DashboardAuthenticator sets to ZbClaimTypes.Name (= ClaimTypes.Name = display name).
+            string? identityName = user.Identity?.Name;
+            if (!string.IsNullOrWhiteSpace(identityName))
+            {
+                return identityName;
+            }
+
+            // Final explicit fallback — ZbClaimTypes.Name claim value directly.
+            return user.FindFirstValue(ZbClaimTypes.Name);
+        }
+    }
+}

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

@@ -0,0 +1,18 @@
+namespace ZB.MOM.WW.MxGateway.Server.Security.Audit;
+
+/// <summary>
+/// Returns the current actor name for use in audit events.
+/// </summary>
+/// <remarks>
+/// Implementations resolve the actor from the ambient request context. For the dashboard
+/// this is the authenticated LDAP operator; for non-HTTP contexts (gRPC, CLI) the caller
+/// provides the actor directly and this seam is not used.
+/// </remarks>
+public interface IAuditActorAccessor
+{
+    /// <summary>
+    /// Gets the current actor's username, or <see langword="null"/> when there is no
+    /// authenticated principal in scope (e.g. an anonymous or unauthenticated request).
+    /// </summary>
+    string? CurrentActor { get; }
+}

src/ZB.MOM.WW.MxGateway.Server/Security/Audit/SqliteCanonicalAuditStore.cs

@@ -0,0 +1,138 @@
+using System.Globalization;
+using Microsoft.Data.Sqlite;
+using ZB.MOM.WW.Audit;
+using ZB.MOM.WW.Auth.ApiKeys.Sqlite;
+
+namespace ZB.MOM.WW.MxGateway.Server.Security.Audit;
+
+/// <summary>
+/// MxGateway-owned, append-only SQLite store for canonical
+/// <see cref="AuditEvent"/>s. It writes to a NEW <c>audit_event</c> table in the
+/// SAME database file as the shared <c>ZB.MOM.WW.Auth.ApiKeys</c> stores: both share
+/// the library's <see cref="AuthSqliteConnectionFactory"/> (so they target the same
+/// <c>ApiKeyOptions.SqlitePath</c> with the same WAL/busy-timeout connection config).
+/// </summary>
+/// <remarks>
+/// This store is the canonical sink for ALL MxGateway audit. The library's own
+/// <c>api_key_audit</c> table is left in place but UNUSED after adoption — the library's
+/// <c>IApiKeyAuditStore</c> registration is overridden by
+/// <see cref="CanonicalForwardingApiKeyAuditStore"/>, which forwards onto this store via
+/// <see cref="CanonicalAuditWriter"/>. The library's <c>schema_version</c> /
+/// <c>api_key_audit</c> tables are not touched here; the <c>audit_event</c> table is
+/// created idempotently (<c>CREATE TABLE IF NOT EXISTS</c>) on each write so it
+/// self-bootstraps regardless of migration ordering.
+/// </remarks>
+public sealed class SqliteCanonicalAuditStore(AuthSqliteConnectionFactory connectionFactory)
+{
+    private const string CreateTableSql =
+        """
+        CREATE TABLE IF NOT EXISTS audit_event (
+            event_id        TEXT PRIMARY KEY,
+            occurred_at_utc TEXT NOT NULL,
+            actor           TEXT NOT NULL,
+            action          TEXT NOT NULL,
+            outcome         TEXT NOT NULL,
+            category        TEXT NULL,
+            target          TEXT NULL,
+            source_node     TEXT NULL,
+            correlation_id  TEXT NULL,
+            details_json    TEXT NULL
+        );
+        """;
+
+    /// <summary>Inserts a canonical audit event into the <c>audit_event</c> table.</summary>
+    /// <param name="auditEvent">The canonical event to persist.</param>
+    /// <param name="cancellationToken">Token to observe for cancellation.</param>
+    public async Task InsertAsync(AuditEvent auditEvent, CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(auditEvent);
+
+        await using SqliteConnection connection =
+            await connectionFactory.OpenConnectionAsync(cancellationToken).ConfigureAwait(false);
+
+        await EnsureTableAsync(connection, cancellationToken).ConfigureAwait(false);
+
+        await using SqliteCommand command = connection.CreateCommand();
+        command.CommandText =
+            """
+            INSERT INTO audit_event
+                (event_id, occurred_at_utc, actor, action, outcome,
+                 category, target, source_node, correlation_id, details_json)
+            VALUES
+                ($event_id, $occurred_at_utc, $actor, $action, $outcome,
+                 $category, $target, $source_node, $correlation_id, $details_json);
+            """;
+        command.Parameters.AddWithValue("$event_id", auditEvent.EventId.ToString());
+        command.Parameters.AddWithValue("$occurred_at_utc", auditEvent.OccurredAtUtc.ToString("O", CultureInfo.InvariantCulture));
+        command.Parameters.AddWithValue("$actor", auditEvent.Actor);
+        command.Parameters.AddWithValue("$action", auditEvent.Action);
+        command.Parameters.AddWithValue("$outcome", auditEvent.Outcome.ToString());
+        command.Parameters.AddWithValue("$category", (object?)auditEvent.Category ?? DBNull.Value);
+        command.Parameters.AddWithValue("$target", (object?)auditEvent.Target ?? DBNull.Value);
+        command.Parameters.AddWithValue("$source_node", (object?)auditEvent.SourceNode ?? DBNull.Value);
+        command.Parameters.AddWithValue("$correlation_id", (object?)auditEvent.CorrelationId?.ToString() ?? DBNull.Value);
+        command.Parameters.AddWithValue("$details_json", (object?)auditEvent.DetailsJson ?? DBNull.Value);
+
+        await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
+    }
+
+    /// <summary>Returns the most recent canonical audit events, newest first.</summary>
+    /// <param name="limit">Maximum number of events to return.</param>
+    /// <param name="cancellationToken">Token to observe for cancellation.</param>
+    public async Task<IReadOnlyList<AuditEvent>> ListRecentAsync(int limit, CancellationToken cancellationToken)
+    {
+        if (limit <= 0)
+        {
+            return [];
+        }
+
+        await using SqliteConnection connection =
+            await connectionFactory.OpenConnectionAsync(cancellationToken).ConfigureAwait(false);
+
+        await EnsureTableAsync(connection, cancellationToken).ConfigureAwait(false);
+
+        await using SqliteCommand command = connection.CreateCommand();
+        command.CommandText =
+            """
+            SELECT event_id, occurred_at_utc, actor, action, outcome,
+                   category, target, source_node, correlation_id, details_json
+            FROM audit_event
+            ORDER BY rowid DESC
+            LIMIT $limit;
+            """;
+        command.Parameters.AddWithValue("$limit", limit);
+
+        List<AuditEvent> events = [];
+
+        await using SqliteDataReader reader = await command.ExecuteReaderAsync(cancellationToken).ConfigureAwait(false);
+
+        while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false))
+        {
+            events.Add(new AuditEvent
+            {
+                EventId = Guid.Parse(reader.GetString(0)),
+                OccurredAtUtc = ParseUtc(reader.GetString(1)),
+                Actor = reader.GetString(2),
+                Action = reader.GetString(3),
+                Outcome = Enum.Parse<AuditOutcome>(reader.GetString(4)),
+                Category = reader.IsDBNull(5) ? null : reader.GetString(5),
+                Target = reader.IsDBNull(6) ? null : reader.GetString(6),
+                SourceNode = reader.IsDBNull(7) ? null : reader.GetString(7),
+                CorrelationId = reader.IsDBNull(8) ? null : Guid.Parse(reader.GetString(8)),
+                DetailsJson = reader.IsDBNull(9) ? null : reader.GetString(9),
+            });
+        }
+
+        return events;
+    }
+
+    private static async Task EnsureTableAsync(SqliteConnection connection, CancellationToken cancellationToken)
+    {
+        await using SqliteCommand command = connection.CreateCommand();
+        command.CommandText = CreateTableSql;
+        await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
+    }
+
+    private static DateTimeOffset ParseUtc(string value) =>
+        DateTimeOffset.Parse(value, CultureInfo.InvariantCulture, DateTimeStyles.RoundtripKind);
+}

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/ApiKeyAdminCliRunner.cs

@@ -1,15 +1,19 @@
 using System.Text.Json;
+using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
+using ZB.MOM.WW.Auth.ApiKeys.Admin;
 
 namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
 
 /// <summary>
 /// Executes API key administration commands from the CLI.
 /// </summary>
-public sealed class ApiKeyAdminCliRunner(
-    IAuthStoreMigrator migrator,
-    IApiKeyAdminStore adminStore,
-    IApiKeyAuditStore auditStore,
-    IApiKeySecretHasher hasher)
+/// <remarks>
+/// The create/revoke/rotate/list/init-db verbs (secret generation, peppered hashing, token
+/// assembly and per-action audit) are delegated to the shared
+/// <see cref="ApiKeyAdminCommands"/>. This runner adapts the gateway's strongly-typed command and
+/// output DTOs (which carry <see cref="ApiKeyConstraints"/>) onto the library's JSON-based contract.
+/// </remarks>
+public sealed class ApiKeyAdminCliRunner(ApiKeyAdminCommands commands)
 {
     private static readonly JsonSerializerOptions JsonOptions = new()
     {
@@ -44,8 +48,7 @@ public sealed class ApiKeyAdminCliRunner(
 
     private async Task<ApiKeyAdminOutput> InitDbAsync(CancellationToken cancellationToken)
     {
-        await migrator.MigrateAsync(cancellationToken).ConfigureAwait(false);
-        await AppendAuditAsync(null, "init-db", null, cancellationToken).ConfigureAwait(false);
+        await commands.InitDbAsync(remoteAddress: null, cancellationToken).ConfigureAwait(false);
 
         return new ApiKeyAdminOutput("init-db", "initialized", null, []);
     }
@@ -54,33 +57,26 @@ public sealed class ApiKeyAdminCliRunner(
         ApiKeyAdminCommand command,
         CancellationToken cancellationToken)
     {
-        await migrator.MigrateAsync(cancellationToken).ConfigureAwait(false);
+        // The shared command set requires the schema to exist; init-db is idempotent.
+        await commands.InitDbAsync(remoteAddress: null, cancellationToken).ConfigureAwait(false);
 
         string keyId = Required(command.KeyId);
-        string secret = ApiKeySecretGenerator.Generate();
-        string apiKey = FormatApiKey(keyId, secret);
-
-        await adminStore.CreateAsync(
-                new ApiKeyCreateRequest(
-                    KeyId: keyId,
-                    KeyPrefix: $"mxgw_{keyId}",
-                    SecretHash: hasher.HashSecret(secret),
-                    DisplayName: Required(command.DisplayName),
-                    Scopes: command.Scopes,
-                    Constraints: command.Constraints,
-                    CreatedUtc: DateTimeOffset.UtcNow),
+        CreateKeyResult created = await commands.CreateKeyAsync(
+                keyId,
+                Required(command.DisplayName),
+                command.Scopes,
+                ApiKeyConstraintSerializer.Serialize(command.Constraints),
+                remoteAddress: null,
                 cancellationToken)
             .ConfigureAwait(false);
-        await AppendAuditAsync(keyId, "create-key", null, cancellationToken).ConfigureAwait(false);
 
-        return new ApiKeyAdminOutput("create-key", "created", apiKey, []);
+        return new ApiKeyAdminOutput("create-key", "created", created.Token, []);
     }
 
     private async Task<ApiKeyAdminOutput> ListKeysAsync(CancellationToken cancellationToken)
     {
-        await migrator.MigrateAsync(cancellationToken).ConfigureAwait(false);
-        IReadOnlyList<ApiKeyRecord> keys = await adminStore.ListAsync(cancellationToken).ConfigureAwait(false);
-        await AppendAuditAsync(null, "list-keys", null, cancellationToken).ConfigureAwait(false);
+        await commands.InitDbAsync(remoteAddress: null, cancellationToken).ConfigureAwait(false);
+        IReadOnlyList<ApiKeyListItem> keys = await commands.ListKeysAsync(cancellationToken).ConfigureAwait(false);
 
         return new ApiKeyAdminOutput(
             "list-keys",
@@ -93,35 +89,28 @@ public sealed class ApiKeyAdminCliRunner(
         ApiKeyAdminCommand command,
         CancellationToken cancellationToken)
     {
-        await migrator.MigrateAsync(cancellationToken).ConfigureAwait(false);
+        await commands.InitDbAsync(remoteAddress: null, cancellationToken).ConfigureAwait(false);
 
         string keyId = Required(command.KeyId);
-        bool revoked = await adminStore.RevokeAsync(keyId, DateTimeOffset.UtcNow, cancellationToken)
+        KeyActionResult result = await commands.RevokeKeyAsync(keyId, remoteAddress: null, cancellationToken)
             .ConfigureAwait(false);
 
-        await AppendAuditAsync(keyId, "revoke-key", revoked ? "revoked" : "not-found-or-already-revoked", cancellationToken)
-            .ConfigureAwait(false);
-
-        return new ApiKeyAdminOutput("revoke-key", revoked ? "revoked" : "not-found-or-already-revoked", null, []);
+        return new ApiKeyAdminOutput("revoke-key", result.Succeeded ? "revoked" : "not-found-or-already-revoked", null, []);
     }
 
     private async Task<ApiKeyAdminOutput> RotateKeyAsync(
         ApiKeyAdminCommand command,
         CancellationToken cancellationToken)
     {
-        await migrator.MigrateAsync(cancellationToken).ConfigureAwait(false);
+        await commands.InitDbAsync(remoteAddress: null, cancellationToken).ConfigureAwait(false);
 
         string keyId = Required(command.KeyId);
-        string secret = ApiKeySecretGenerator.Generate();
-        string apiKey = FormatApiKey(keyId, secret);
-
-        bool rotated = await adminStore.RotateAsync(keyId, hasher.HashSecret(secret), DateTimeOffset.UtcNow, cancellationToken)
+        CreateKeyResult rotated = await commands.RotateKeyAsync(keyId, remoteAddress: null, cancellationToken)
             .ConfigureAwait(false);
 
-        await AppendAuditAsync(keyId, "rotate-key", rotated ? "rotated" : "not-found", cancellationToken)
-            .ConfigureAwait(false);
+        bool succeeded = rotated.Token is not null;
 
-        return new ApiKeyAdminOutput("rotate-key", rotated ? "rotated" : "not-found", rotated ? apiKey : null, []);
+        return new ApiKeyAdminOutput("rotate-key", succeeded ? "rotated" : "not-found", rotated.Token, []);
     }
 
     private static async Task WriteOutputAsync(
@@ -150,40 +139,19 @@ public sealed class ApiKeyAdminCliRunner(
         }
     }
 
-    private async Task AppendAuditAsync(
-        string? keyId,
-        string eventType,
-        string? details,
-        CancellationToken cancellationToken)
-    {
-        await auditStore.AppendAsync(
-                new ApiKeyAuditEntry(
-                    KeyId: keyId,
-                    EventType: eventType,
-                    RemoteAddress: null,
-                    Details: details),
-                cancellationToken)
-            .ConfigureAwait(false);
-    }
-
-    private static ApiKeyAdminListedKey ToListedKey(ApiKeyRecord key)
+    private static ApiKeyAdminListedKey ToListedKey(ApiKeyListItem key)
     {
         return new ApiKeyAdminListedKey(
             KeyId: key.KeyId,
             KeyPrefix: key.KeyPrefix,
             DisplayName: key.DisplayName,
             Scopes: key.Scopes,
-            Constraints: key.Constraints,
+            Constraints: ApiKeyConstraintSerializer.Deserialize(key.ConstraintsJson),
             CreatedUtc: key.CreatedUtc,
             LastUsedUtc: key.LastUsedUtc,
             RevokedUtc: key.RevokedUtc);
     }
 
-    private static string FormatApiKey(string keyId, string secret)
-    {
-        return $"mxgw_{keyId}_{secret}";
-    }
-
     private static string Required(string? value)
     {
         return value ?? throw new InvalidOperationException("Required command value was not provided.");

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/ApiKeyAuditEntry.cs

@@ -1,7 +0,0 @@
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-public sealed record ApiKeyAuditEntry(
-    string? KeyId,
-    string EventType,
-    string? RemoteAddress,
-    string? Details);

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/ApiKeyAuditRecord.cs

@@ -1,9 +0,0 @@
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-public sealed record ApiKeyAuditRecord(
-    long AuditId,
-    string? KeyId,
-    string EventType,
-    string? RemoteAddress,
-    DateTimeOffset CreatedUtc,
-    string? Details);

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/ApiKeyCreateRequest.cs

@@ -1,10 +0,0 @@
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-public sealed record ApiKeyCreateRequest(
-    string KeyId,
-    string KeyPrefix,
-    byte[] SecretHash,
-    string DisplayName,
-    IReadOnlySet<string> Scopes,
-    ApiKeyConstraints Constraints,
-    DateTimeOffset CreatedUtc);

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/ApiKeyParser.cs

@@ -1,49 +0,0 @@
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-public sealed class ApiKeyParser : IApiKeyParser
-{
-    private const string BearerPrefix = "Bearer ";
-    private const string TokenPrefix = "mxgw_";
-
-    /// <summary>Attempts to parse a Bearer token from an Authorization header and extract the API key ID and secret.</summary>
-    /// <param name="authorizationHeader">Authorization header value to parse.</param>
-    /// <param name="apiKey">Parsed API key with ID and secret, or null if parsing failed.</param>
-    /// <returns>True if the header was successfully parsed; otherwise, false.</returns>
-    public bool TryParseAuthorizationHeader(string? authorizationHeader, out ParsedApiKey? apiKey)
-    {
-        apiKey = null;
-
-        if (string.IsNullOrWhiteSpace(authorizationHeader)
-            || !authorizationHeader.StartsWith(BearerPrefix, StringComparison.OrdinalIgnoreCase))
-        {
-            return false;
-        }
-
-        string token = authorizationHeader[BearerPrefix.Length..].Trim();
-
-        if (!token.StartsWith(TokenPrefix, StringComparison.OrdinalIgnoreCase))
-        {
-            return false;
-        }
-
-        string keyPayload = token[TokenPrefix.Length..];
-        int separatorIndex = keyPayload.IndexOf('_', StringComparison.Ordinal);
-
-        if (separatorIndex <= 0 || separatorIndex == keyPayload.Length - 1)
-        {
-            return false;
-        }
-
-        string keyId = keyPayload[..separatorIndex];
-        string secret = keyPayload[(separatorIndex + 1)..];
-
-        if (string.IsNullOrWhiteSpace(keyId) || string.IsNullOrWhiteSpace(secret))
-        {
-            return false;
-        }
-
-        apiKey = new ParsedApiKey(keyId, secret);
-
-        return true;
-    }
-}

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/ApiKeyPepperUnavailableException.cs

@@ -1,4 +0,0 @@
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-public sealed class ApiKeyPepperUnavailableException(string pepperSecretName)
-    : InvalidOperationException($"API key pepper secret '{pepperSecretName}' is not configured.");

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/ApiKeyRecord.cs

@@ -1,12 +0,0 @@
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-public sealed record ApiKeyRecord(
-    string KeyId,
-    string KeyPrefix,
-    byte[] SecretHash,
-    string DisplayName,
-    IReadOnlySet<string> Scopes,
-    ApiKeyConstraints Constraints,
-    DateTimeOffset CreatedUtc,
-    DateTimeOffset? LastUsedUtc,
-    DateTimeOffset? RevokedUtc);

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/ApiKeyRecordReader.cs

@@ -1,31 +0,0 @@
-using Microsoft.Data.Sqlite;
-
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-/// <summary>Reads API key records from SQLite query results.</summary>
-public static class ApiKeyRecordReader
-{
-    /// <summary>Deserializes a row from the API key table into an ApiKeyRecord.</summary>
-    /// <param name="reader">The data reader positioned at the API key row.</param>
-    /// <returns>The deserialized API key record.</returns>
-    public static ApiKeyRecord Read(SqliteDataReader reader)
-    {
-        return new ApiKeyRecord(
-            KeyId: reader.GetString(0),
-            KeyPrefix: reader.GetString(1),
-            SecretHash: (byte[])reader["secret_hash"],
-            DisplayName: reader.GetString(3),
-            Scopes: ApiKeyScopeSerializer.Deserialize(reader.GetString(4)),
-            Constraints: ApiKeyConstraintSerializer.Deserialize(reader.IsDBNull(5) ? null : reader.GetString(5)),
-            CreatedUtc: DateTimeOffset.Parse(reader.GetString(6), System.Globalization.CultureInfo.InvariantCulture),
-            LastUsedUtc: ReadNullableDateTimeOffset(reader, 7),
-            RevokedUtc: ReadNullableDateTimeOffset(reader, 8));
-    }
-
-    private static DateTimeOffset? ReadNullableDateTimeOffset(SqliteDataReader reader, int ordinal)
-    {
-        return reader.IsDBNull(ordinal)
-            ? null
-            : DateTimeOffset.Parse(reader.GetString(ordinal), System.Globalization.CultureInfo.InvariantCulture);
-    }
-}

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/ApiKeyScopeSerializer.cs

@@ -1,29 +0,0 @@
-using System.Text.Json;
-
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-public static class ApiKeyScopeSerializer
-{
-    /// <summary>Serializes scopes to JSON string.</summary>
-    /// <param name="scopes">The scopes to serialize.</param>
-    /// <returns>JSON string representation.</returns>
-    public static string Serialize(IReadOnlySet<string> scopes)
-    {
-        return JsonSerializer.Serialize(scopes.Order(StringComparer.Ordinal));
-    }
-
-    /// <summary>Deserializes scopes from JSON string.</summary>
-    /// <param name="value">The JSON string to deserialize.</param>
-    /// <returns>Deserialized scopes set.</returns>
-    public static IReadOnlySet<string> Deserialize(string value)
-    {
-        if (string.IsNullOrWhiteSpace(value))
-        {
-            return new HashSet<string>(StringComparer.Ordinal);
-        }
-
-        string[]? scopes = JsonSerializer.Deserialize<string[]>(value);
-
-        return new HashSet<string>(scopes ?? [], StringComparer.Ordinal);
-    }
-}

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/ApiKeySecretGenerator.cs

@@ -1,19 +0,0 @@
-using System.Security.Cryptography;
-
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-/// <summary>Generates cryptographically secure API key secrets.</summary>
-public static class ApiKeySecretGenerator
-{
-    /// <summary>Generates a new random API key secret string.</summary>
-    public static string Generate()
-    {
-        Span<byte> bytes = stackalloc byte[32];
-        RandomNumberGenerator.Fill(bytes);
-
-        return Convert.ToBase64String(bytes)
-            .TrimEnd('=')
-            .Replace('+', '-')
-            .Replace('/', '_');
-    }
-}

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/ApiKeySecretHasher.cs

@@ -1,38 +0,0 @@
-using System.Security.Cryptography;
-using System.Text;
-using Microsoft.Extensions.Options;
-using ZB.MOM.WW.MxGateway.Server.Configuration;
-
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-public sealed class ApiKeySecretHasher(
-    IConfiguration configuration,
-    IOptions<GatewayOptions> options) : IApiKeySecretHasher
-{
-    /// <summary>Hashes an API key secret with pepper using HMAC-SHA256.</summary>
-    /// <param name="secret">The secret to hash.</param>
-    /// <returns>The hashed secret.</returns>
-    public byte[] HashSecret(string secret)
-    {
-        string pepper = GetPepper();
-        byte[] pepperBytes = Encoding.UTF8.GetBytes(pepper);
-        byte[] secretBytes = Encoding.UTF8.GetBytes(secret);
-
-        using HMACSHA256 hmac = new(pepperBytes);
-
-        return hmac.ComputeHash(secretBytes);
-    }
-
-    private string GetPepper()
-    {
-        string pepperSecretName = options.Value.Authentication.PepperSecretName;
-        string? pepper = configuration[pepperSecretName];
-
-        if (string.IsNullOrWhiteSpace(pepper))
-        {
-            throw new ApiKeyPepperUnavailableException(pepperSecretName);
-        }
-
-        return pepper;
-    }
-}

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/ApiKeyVerificationFailure.cs

@@ -1,11 +0,0 @@
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-public enum ApiKeyVerificationFailure
-{
-    None,
-    MissingOrMalformedCredentials,
-    PepperUnavailable,
-    KeyNotFound,
-    KeyRevoked,
-    SecretMismatch
-}

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/ApiKeyVerificationResult.cs

@@ -1,33 +0,0 @@
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-public sealed record ApiKeyVerificationResult(
-    bool Succeeded,
-    ApiKeyIdentity? Identity,
-    ApiKeyVerificationFailure Failure)
-{
-    /// <summary>
-    /// Creates a successful verification result.
-    /// </summary>
-    /// <param name="identity">API key identity.</param>
-    /// <returns>Success result.</returns>
-    public static ApiKeyVerificationResult Success(ApiKeyIdentity identity)
-    {
-        return new ApiKeyVerificationResult(
-            Succeeded: true,
-            Identity: identity,
-            Failure: ApiKeyVerificationFailure.None);
-    }
-
-    /// <summary>
-    /// Creates a failed verification result.
-    /// </summary>
-    /// <param name="failure">Verification failure reason.</param>
-    /// <returns>Failure result.</returns>
-    public static ApiKeyVerificationResult Fail(ApiKeyVerificationFailure failure)
-    {
-        return new ApiKeyVerificationResult(
-            Succeeded: false,
-            Identity: null,
-            Failure: failure);
-    }
-}

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/ApiKeyVerifier.cs

@@ -1,64 +0,0 @@
-using System.Security.Cryptography;
-
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-public sealed class ApiKeyVerifier(
-    IApiKeyParser parser,
-    IApiKeySecretHasher hasher,
-    IApiKeyStore keyStore) : IApiKeyVerifier
-{
-    /// <summary>
-    /// Verifies an API key from an authorization header asynchronously.
-    /// </summary>
-    /// <param name="authorizationHeader">Authorization header value.</param>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>Verification result.</returns>
-    public async Task<ApiKeyVerificationResult> VerifyAsync(
-        string? authorizationHeader,
-        CancellationToken cancellationToken)
-    {
-        if (!parser.TryParseAuthorizationHeader(authorizationHeader, out ParsedApiKey? parsedKey)
-            || parsedKey is null)
-        {
-            return ApiKeyVerificationResult.Fail(ApiKeyVerificationFailure.MissingOrMalformedCredentials);
-        }
-
-        ApiKeyRecord? storedKey = await keyStore.FindByKeyIdAsync(parsedKey.KeyId, cancellationToken)
-            .ConfigureAwait(false);
-
-        if (storedKey is null)
-        {
-            return ApiKeyVerificationResult.Fail(ApiKeyVerificationFailure.KeyNotFound);
-        }
-
-        if (storedKey.RevokedUtc is not null)
-        {
-            return ApiKeyVerificationResult.Fail(ApiKeyVerificationFailure.KeyRevoked);
-        }
-
-        byte[] presentedHash;
-        try
-        {
-            presentedHash = hasher.HashSecret(parsedKey.Secret);
-        }
-        catch (ApiKeyPepperUnavailableException)
-        {
-            return ApiKeyVerificationResult.Fail(ApiKeyVerificationFailure.PepperUnavailable);
-        }
-
-        if (!CryptographicOperations.FixedTimeEquals(presentedHash, storedKey.SecretHash))
-        {
-            return ApiKeyVerificationResult.Fail(ApiKeyVerificationFailure.SecretMismatch);
-        }
-
-        await keyStore.MarkKeyUsedAsync(storedKey.KeyId, DateTimeOffset.UtcNow, cancellationToken)
-            .ConfigureAwait(false);
-
-        return ApiKeyVerificationResult.Success(new ApiKeyIdentity(
-            KeyId: storedKey.KeyId,
-            KeyPrefix: storedKey.KeyPrefix,
-            DisplayName: storedKey.DisplayName,
-            Scopes: storedKey.Scopes,
-            Constraints: storedKey.Constraints));
-    }
-}

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/AuthSqliteConnectionFactory.cs

@@ -1,80 +0,0 @@
-using Microsoft.Data.Sqlite;
-using Microsoft.Extensions.Options;
-using ZB.MOM.WW.MxGateway.Server.Configuration;
-
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-/// <summary>
-/// Factory for creating SQLite connections to the authentication store.
-/// </summary>
-public sealed class AuthSqliteConnectionFactory(IOptions<GatewayOptions> options)
-{
-    /// <summary>
-    /// Busy timeout applied to every auth-store connection. SQLite retries a busy
-    /// database for this long before surfacing <c>SQLITE_BUSY</c>, so the concurrent
-    /// <c>MarkKeyUsedAsync</c> / audit-append writers degrade gracefully under load
-    /// instead of failing the request path.
-    /// </summary>
-    private static readonly TimeSpan BusyTimeout = TimeSpan.FromSeconds(5);
-
-    /// <summary>
-    /// Creates an unopened SQLite connection to the auth database. Prefer
-    /// <see cref="OpenConnectionAsync"/>, which also applies WAL journaling and the
-    /// busy timeout.
-    /// </summary>
-    public SqliteConnection CreateConnection()
-    {
-        string sqlitePath = options.Value.Authentication.SqlitePath;
-        string? directory = Path.GetDirectoryName(sqlitePath);
-
-        if (!string.IsNullOrWhiteSpace(directory))
-        {
-            Directory.CreateDirectory(directory);
-        }
-
-        SqliteConnectionStringBuilder builder = new()
-        {
-            DataSource = sqlitePath,
-            Mode = SqliteOpenMode.ReadWriteCreate,
-            Pooling = true,
-            DefaultTimeout = (int)BusyTimeout.TotalSeconds,
-        };
-
-        return new SqliteConnection(builder.ToString());
-    }
-
-    /// <summary>
-    /// Creates a SQLite connection, opens it, and configures WAL journaling and a
-    /// non-zero busy timeout so concurrent readers and writers degrade gracefully
-    /// rather than surfacing <c>SQLITE_BUSY</c> as a hard failure.
-    /// </summary>
-    /// <param name="cancellationToken">Cancellation token for the operation.</param>
-    /// <returns>An opened and configured SQLite connection.</returns>
-    public async Task<SqliteConnection> OpenConnectionAsync(CancellationToken cancellationToken)
-    {
-        SqliteConnection connection = CreateConnection();
-        try
-        {
-            await connection.OpenAsync(cancellationToken).ConfigureAwait(false);
-            await ConfigureConnectionAsync(connection, cancellationToken).ConfigureAwait(false);
-            return connection;
-        }
-        catch
-        {
-            await connection.DisposeAsync().ConfigureAwait(false);
-            throw;
-        }
-    }
-
-    private static async Task ConfigureConnectionAsync(
-        SqliteConnection connection,
-        CancellationToken cancellationToken)
-    {
-        // WAL is a persistent, database-level setting; re-applying it per connection
-        // is cheap and a no-op once set. busy_timeout is per-connection state.
-        await using SqliteCommand command = connection.CreateCommand();
-        command.CommandText =
-            $"PRAGMA journal_mode=WAL; PRAGMA busy_timeout={(int)BusyTimeout.TotalMilliseconds};";
-        await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
-    }
-}

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/AuthStoreMigrationException.cs

@@ -1,3 +0,0 @@
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-public sealed class AuthStoreMigrationException(string message) : InvalidOperationException(message);

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/AuthStoreMigrationHostedService.cs

@@ -1,29 +0,0 @@
-using Microsoft.Extensions.Options;
-using ZB.MOM.WW.MxGateway.Server.Configuration;
-
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-/// <summary>
-/// Hosted service that runs authentication store migrations on startup.
-/// </summary>
-public sealed class AuthStoreMigrationHostedService(
-    IOptions<GatewayOptions> options,
-    IAuthStoreMigrator migrator) : IHostedService
-{
-    /// <inheritdoc />
-    public async Task StartAsync(CancellationToken cancellationToken)
-    {
-        AuthenticationOptions authentication = options.Value.Authentication;
-
-        if (authentication.Mode == AuthenticationMode.ApiKey && authentication.RunMigrationsOnStartup)
-        {
-            await migrator.MigrateAsync(cancellationToken).ConfigureAwait(false);
-        }
-    }
-
-    /// <inheritdoc />
-    public Task StopAsync(CancellationToken cancellationToken)
-    {
-        return Task.CompletedTask;
-    }
-}

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/AuthStoreServiceCollectionExtensions.cs

@@ -1,27 +1,109 @@
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.Options;
+using ZB.MOM.WW.Audit;
+using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
+using ZB.MOM.WW.Auth.ApiKeys;
+using ZB.MOM.WW.Auth.ApiKeys.Admin;
+using ZB.MOM.WW.Auth.ApiKeys.DependencyInjection;
+using ZB.MOM.WW.Auth.ApiKeys.Sqlite;
+using ZB.MOM.WW.MxGateway.Server.Security.Audit;
+
 namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
 
 /// <summary>
 /// Extension methods for configuring the SQLite authentication store.
 /// </summary>
+/// <remarks>
+/// The peppered-HMAC API-key pipeline (token format, hashing, constant-time compare, SQLite
+/// schema, stores, verifier and migration) is provided by the shared
+/// <c>ZB.MOM.WW.Auth.ApiKeys</c> library, of which this gateway is the donor. This wiring binds
+/// the library's <see cref="ApiKeyOptions"/> from the gateway's <c>MxGateway:Authentication</c>
+/// section and layers the gateway-specific constraint enforcement, gRPC interceptor, CLI and
+/// dashboard on top.
+/// </remarks>
 public static class AuthStoreServiceCollectionExtensions
 {
+    /// <summary>The configuration section the gateway binds API-key options from.</summary>
+    public const string AuthenticationSectionPath = "MxGateway:Authentication";
+
+    /// <summary>The gateway API-key token prefix (token format <c>mxgw_&lt;id&gt;_&lt;secret&gt;</c>).</summary>
+    public const string TokenPrefix = "mxgw";
+
+    /// <summary>The configuration key the API-key pepper is resolved from.</summary>
+    public const string PepperSecretName = "MxGateway:ApiKeyPepper";
+
     /// <summary>
     /// Adds the SQLite authentication store and related services to the dependency container.
     /// </summary>
     /// <param name="services">Service collection to configure.</param>
+    /// <param name="configuration">Application configuration carrying the API-key options.</param>
     /// <returns>The service collection for chaining.</returns>
-    public static IServiceCollection AddSqliteAuthStore(this IServiceCollection services)
+    public static IServiceCollection AddSqliteAuthStore(
+        this IServiceCollection services,
+        IConfiguration configuration)
     {
-        services.AddSingleton<IApiKeyParser, ApiKeyParser>();
-        services.AddSingleton<IApiKeySecretHasher, ApiKeySecretHasher>();
-        services.AddSingleton<IApiKeyVerifier, ApiKeyVerifier>();
+        ArgumentNullException.ThrowIfNull(services);
+        ArgumentNullException.ThrowIfNull(configuration);
+
+        // Pin the gateway's API-key contract (token prefix "mxgw"; pepper resolved from
+        // MxGateway:ApiKeyPepper) by layering fallback defaults UNDER the supplied configuration:
+        // an in-memory source provides TokenPrefix/PepperSecretName only when the bound
+        // MxGateway:Authentication section omits them (the section has no TokenPrefix, and the pepper
+        // is intentionally not in appsettings — it is supplied at runtime). Explicit config wins
+        // because it is added last. ApiKeyOptions is an init-only record, so the values must be
+        // present at bind time rather than mutated post-configure.
+        IConfiguration effectiveConfig = new ConfigurationBuilder()
+            .AddInMemoryCollection(new Dictionary<string, string?>
+            {
+                [$"{AuthenticationSectionPath}:TokenPrefix"] = TokenPrefix,
+                [$"{AuthenticationSectionPath}:PepperSecretName"] = PepperSecretName,
+            })
+            .AddConfiguration(configuration)
+            .Build();
+
+        // Register the shared API-key provider: binds ApiKeyOptions from MxGateway:Authentication,
+        // wires up the SQLite stores, the configuration-backed pepper provider, the verifier, the
+        // migrator and the migration hosted service.
+        services.AddZbApiKeyAuth(effectiveConfig, AuthenticationSectionPath);
+
+        // Canonical audit (Task 2.3 — DEEP adopt ZB.MOM.WW.Audit). All MxGateway audit flows as a
+        // canonical AuditEvent through the library IAuditWriter, persisted in a NEW gateway-owned
+        // audit_event table that lives in the SAME SQLite DB file as the api-key stores (it reuses
+        // the library's AuthSqliteConnectionFactory, registered by AddZbApiKeyAuth above).
+        services.AddSingleton(sp =>
+            new SqliteCanonicalAuditStore(sp.GetRequiredService<AuthSqliteConnectionFactory>()));
+        // Resolve the logger defensively: the production host always registers ILogger<T>, but the
+        // DI-only auth/CLI/dashboard unit tests build a bare ServiceCollection without AddLogging().
+        // Fall back to NullLogger there so the audit writer (and the IApiKeyAuditStore override that
+        // depends on it) still resolve. The write path is best-effort regardless.
+        services.AddSingleton<IAuditWriter>(sp =>
+            new CanonicalAuditWriter(
+                sp.GetRequiredService<SqliteCanonicalAuditStore>(),
+                sp.GetService<ILogger<CanonicalAuditWriter>>()
+                    ?? Microsoft.Extensions.Logging.Abstractions.NullLogger<CanonicalAuditWriter>.Instance));
+
+        // OVERRIDE the library's IApiKeyAuditStore (AddZbApiKeyAuth registered the library's
+        // SqliteApiKeyAuditStore via TryAddSingleton) with an adapter that canonicalizes every
+        // library-emitted ApiKeyAuditEntry onto AuditEvent and forwards it through IAuditWriter.
+        // This is the only way to canonicalize the library-internal ApiKeyAdminCommands verbs
+        // (create/revoke/rotate/init-db, etc.), which we cannot edit. The adapter is registered
+        // after AddZbApiKeyAuth so it (last registration) is what ApiKeyAdminCommands resolves and
+        // what the dashboard "recent audit" view reads via IApiKeyAuditStore.ListRecentAsync.
+        // The library's api_key_audit table is left in place but is now UNUSED — nothing writes to
+        // it once this adapter replaces the library's audit store.
+        services.AddSingleton<IApiKeyAuditStore, CanonicalForwardingApiKeyAuditStore>();
+
+        // The shared admin command set (create/revoke/rotate/list/init-db with audit) is not
+        // auto-registered by AddZbApiKeyAuth; the gateway CLI and dashboard drive it, so register
+        // it here over the already-wired stores, pepper provider and migrator.
+        services.AddSingleton(sp => new ApiKeyAdminCommands(
+            sp.GetRequiredService<IOptions<ApiKeyOptions>>().Value,
+            sp.GetRequiredService<IApiKeyAdminStore>(),
+            sp.GetRequiredService<IApiKeyAuditStore>(),
+            sp.GetRequiredService<IApiKeyPepperProvider>(),
+            sp.GetRequiredService<SqliteAuthStoreMigrator>()));
+
         services.AddSingleton<ApiKeyAdminCliRunner>();
-        services.AddSingleton<AuthSqliteConnectionFactory>();
-        services.AddSingleton<IAuthStoreMigrator, SqliteAuthStoreMigrator>();
-        services.AddSingleton<IApiKeyStore, SqliteApiKeyStore>();
-        services.AddSingleton<IApiKeyAdminStore, SqliteApiKeyAdminStore>();
-        services.AddSingleton<IApiKeyAuditStore, SqliteApiKeyAuditStore>();
-        services.AddHostedService<AuthStoreMigrationHostedService>();
 
         return services;
     }

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/GatewayApiKeyIdentityMapper.cs

@@ -0,0 +1,43 @@
+using LibApiKeyIdentity = ZB.MOM.WW.Auth.Abstractions.ApiKeys.ApiKeyIdentity;
+
+namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
+
+/// <summary>
+/// Maps the shared <see cref="ZB.MOM.WW.Auth.Abstractions.ApiKeys.ApiKeyIdentity"/> (which
+/// carries the key's scopes plus the opaque constraints JSON blob) onto the gateway's
+/// <see cref="ApiKeyIdentity"/> (which exposes the deserialized
+/// <see cref="ApiKeyConstraints"/> the downstream authorization code enforces).
+/// </summary>
+/// <remarks>
+/// The shared verifier does not interpret the constraints column; it returns the stored
+/// JSON verbatim in <see cref="ZB.MOM.WW.Auth.Abstractions.ApiKeys.ApiKeyIdentity.Constraints"/>.
+/// This mapper re-hydrates it via <see cref="ApiKeyConstraintSerializer"/> so the gateway's
+/// constraint enforcement (<c>ConstraintEnforcer</c>) and request-identity accessor continue
+/// to operate on the strongly-typed model unchanged.
+/// </remarks>
+public static class GatewayApiKeyIdentityMapper
+{
+    /// <summary>
+    /// Converts a shared API-key identity into the gateway identity, deserializing the opaque
+    /// constraints JSON into <see cref="ApiKeyConstraints"/>.
+    /// </summary>
+    /// <param name="identity">The shared identity returned by the library verifier.</param>
+    /// <returns>The gateway identity carrying the effective constraints.</returns>
+    public static ApiKeyIdentity ToGatewayIdentity(LibApiKeyIdentity identity)
+    {
+        ArgumentNullException.ThrowIfNull(identity);
+
+        // The library stores the opaque constraints blob in Constraints as the ConstraintsJson
+        // string (or null when the key has no constraints).
+        string? constraintsJson = identity.Constraints as string;
+
+        return new ApiKeyIdentity(
+            KeyId: identity.KeyId,
+            // The gateway token prefix is fixed ("mxgw"); the key id is its own field. KeyPrefix
+            // is retained only for surface compatibility with the gateway identity record.
+            KeyPrefix: "mxgw",
+            DisplayName: identity.DisplayName,
+            Scopes: identity.Scopes,
+            Constraints: ApiKeyConstraintSerializer.Deserialize(constraintsJson));
+    }
+}

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/IApiKeyAdminStore.cs

@@ -1,53 +0,0 @@
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-public interface IApiKeyAdminStore
-{
-    /// <summary>
-    /// Creates a new API key asynchronously.
-    /// </summary>
-    /// <param name="request">API key creation request.</param>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>Completed task.</returns>
-    Task CreateAsync(ApiKeyCreateRequest request, CancellationToken cancellationToken);
-
-    /// <summary>
-    /// Lists all API keys asynchronously.
-    /// </summary>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>List of API key records.</returns>
-    Task<IReadOnlyList<ApiKeyRecord>> ListAsync(CancellationToken cancellationToken);
-
-    /// <summary>
-    /// Revokes an API key asynchronously.
-    /// </summary>
-    /// <param name="keyId">Key identifier.</param>
-    /// <param name="revokedUtc">Revocation timestamp.</param>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>True if revoked; otherwise false.</returns>
-    Task<bool> RevokeAsync(string keyId, DateTimeOffset revokedUtc, CancellationToken cancellationToken);
-
-    /// <summary>
-    /// Rotates an API key secret asynchronously.
-    /// </summary>
-    /// <param name="keyId">Key identifier.</param>
-    /// <param name="secretHash">New secret hash.</param>
-    /// <param name="rotatedUtc">Rotation timestamp.</param>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>True if rotated; otherwise false.</returns>
-    Task<bool> RotateAsync(
-        string keyId,
-        byte[] secretHash,
-        DateTimeOffset rotatedUtc,
-        CancellationToken cancellationToken);
-
-    /// <summary>
-    /// Permanently deletes an API key, but only if it is already revoked. Active keys are
-    /// untouched (returns false) so an admin cannot delete a working credential without
-    /// first revoking it — that preserves the audit trail and forces the revoke event to
-    /// land in the audit log before the row disappears.
-    /// </summary>
-    /// <param name="keyId">Key identifier.</param>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>True if a revoked key was deleted; false if the key is missing or active.</returns>
-    Task<bool> DeleteAsync(string keyId, CancellationToken cancellationToken);
-}

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/IApiKeyAuditStore.cs

@@ -1,23 +0,0 @@
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-/// <summary>
-/// Stores and retrieves audit events for API key operations.
-/// </summary>
-public interface IApiKeyAuditStore
-{
-    /// <summary>
-    /// Appends an audit entry to the audit log.
-    /// </summary>
-    /// <param name="entry">Audit entry to record.</param>
-    /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
-    /// <returns>Asynchronous task representing the append operation.</returns>
-    Task AppendAsync(ApiKeyAuditEntry entry, CancellationToken cancellationToken);
-
-    /// <summary>
-    /// Lists the most recent audit entries, up to the specified count.
-    /// </summary>
-    /// <param name="count">Maximum number of entries to return.</param>
-    /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
-    /// <returns>Asynchronous task returning the list of audit records.</returns>
-    Task<IReadOnlyList<ApiKeyAuditRecord>> ListRecentAsync(int count, CancellationToken cancellationToken);
-}

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/IApiKeyParser.cs

@@ -1,9 +0,0 @@
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-public interface IApiKeyParser
-{
-    /// <summary>Attempts to parse an authorization header and extract the API key.</summary>
-    /// <param name="authorizationHeader">Authorization header value to parse.</param>
-    /// <param name="apiKey">Parsed API key if successful.</param>
-    bool TryParseAuthorizationHeader(string? authorizationHeader, out ParsedApiKey? apiKey);
-}

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/IApiKeySecretHasher.cs

@@ -1,8 +0,0 @@
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-public interface IApiKeySecretHasher
-{
-    /// <summary>Hashes an API key secret and returns the hash bytes.</summary>
-    /// <param name="secret">API key secret to hash.</param>
-    byte[] HashSecret(string secret);
-}

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/IApiKeyStore.cs

@@ -1,21 +0,0 @@
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-/// <summary>Persists API keys and audit records for authentication and accounting.</summary>
-public interface IApiKeyStore
-{
-    /// <summary>Retrieves an API key by ID regardless of revocation status.</summary>
-    /// <param name="keyId">Identifier of the API key.</param>
-    /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
-    Task<ApiKeyRecord?> FindByKeyIdAsync(string keyId, CancellationToken cancellationToken);
-
-    /// <summary>Retrieves an active (non-revoked) API key by ID.</summary>
-    /// <param name="keyId">Identifier of the API key.</param>
-    /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
-    Task<ApiKeyRecord?> FindActiveByKeyIdAsync(string keyId, CancellationToken cancellationToken);
-
-    /// <summary>Records that an API key was used for auditing and tracking.</summary>
-    /// <param name="keyId">Identifier of the API key.</param>
-    /// <param name="usedUtc">Timestamp when the key was used in UTC.</param>
-    /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
-    Task MarkKeyUsedAsync(string keyId, DateTimeOffset usedUtc, CancellationToken cancellationToken);
-}

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/IApiKeyVerifier.cs

@@ -1,12 +0,0 @@
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-/// <summary>Verifies API key authorization headers and returns the authenticated identity.</summary>
-public interface IApiKeyVerifier
-{
-    /// <summary>Parses and verifies an authorization header, returning success with identity or a failure reason.</summary>
-    /// <param name="authorizationHeader">The authorization header value to verify.</param>
-    /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
-    Task<ApiKeyVerificationResult> VerifyAsync(
-        string? authorizationHeader,
-        CancellationToken cancellationToken);
-}

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/IAuthStoreMigrator.cs

@@ -1,10 +0,0 @@
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-/// <summary>Migrates authentication storage between versions.</summary>
-public interface IAuthStoreMigrator
-{
-    /// <summary>Performs authentication store migration asynchronously.</summary>
-    /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
-    /// <returns>Asynchronous task representing the migration operation.</returns>
-    Task MigrateAsync(CancellationToken cancellationToken);
-}

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/ParsedApiKey.cs

@@ -1,3 +0,0 @@
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-public sealed record ParsedApiKey(string KeyId, string Secret);

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/SqliteApiKeyAdminStore.cs

@@ -1,141 +0,0 @@
-using Microsoft.Data.Sqlite;
-
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-/// <summary>
-/// SQLite-backed storage for API key administration (create, list, revoke, rotate).
-/// </summary>
-public sealed class SqliteApiKeyAdminStore(AuthSqliteConnectionFactory connectionFactory) : IApiKeyAdminStore
-{
-    /// <inheritdoc />
-    public async Task CreateAsync(ApiKeyCreateRequest request, CancellationToken cancellationToken)
-    {
-        await using SqliteConnection connection = await connectionFactory.OpenConnectionAsync(cancellationToken).ConfigureAwait(false);
-
-        await using SqliteCommand command = connection.CreateCommand();
-        command.CommandText = """
-            INSERT INTO api_keys (
-                key_id,
-                key_prefix,
-                secret_hash,
-                display_name,
-                scopes,
-                constraints,
-                created_utc,
-                last_used_utc,
-                revoked_utc)
-            VALUES (
-                $key_id,
-                $key_prefix,
-                $secret_hash,
-                $display_name,
-                $scopes,
-                $constraints,
-                $created_utc,
-                NULL,
-                NULL);
-            """;
-        AddCreateParameters(command, request);
-
-        await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
-    }
-
-    /// <inheritdoc />
-    public async Task<IReadOnlyList<ApiKeyRecord>> ListAsync(CancellationToken cancellationToken)
-    {
-        await using SqliteConnection connection = await connectionFactory.OpenConnectionAsync(cancellationToken).ConfigureAwait(false);
-
-        await using SqliteCommand command = connection.CreateCommand();
-        command.CommandText = """
-            SELECT key_id, key_prefix, secret_hash, display_name, scopes, constraints, created_utc, last_used_utc, revoked_utc
-            FROM api_keys
-            ORDER BY key_id;
-            """;
-
-        List<ApiKeyRecord> records = [];
-
-        await using SqliteDataReader reader = await command.ExecuteReaderAsync(cancellationToken)
-            .ConfigureAwait(false);
-
-        while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false))
-        {
-            records.Add(ApiKeyRecordReader.Read(reader));
-        }
-
-        return records;
-    }
-
-    /// <inheritdoc />
-    public async Task<bool> RevokeAsync(string keyId, DateTimeOffset revokedUtc, CancellationToken cancellationToken)
-    {
-        await using SqliteConnection connection = await connectionFactory.OpenConnectionAsync(cancellationToken).ConfigureAwait(false);
-
-        await using SqliteCommand command = connection.CreateCommand();
-        command.CommandText = """
-            UPDATE api_keys
-            SET revoked_utc = $revoked_utc
-            WHERE key_id = $key_id AND revoked_utc IS NULL;
-            """;
-        command.Parameters.AddWithValue("$key_id", keyId);
-        command.Parameters.AddWithValue("$revoked_utc", revokedUtc.ToString("O"));
-
-        int rows = await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
-
-        return rows > 0;
-    }
-
-    /// <inheritdoc />
-    public async Task<bool> RotateAsync(
-        string keyId,
-        byte[] secretHash,
-        DateTimeOffset rotatedUtc,
-        CancellationToken cancellationToken)
-    {
-        await using SqliteConnection connection = await connectionFactory.OpenConnectionAsync(cancellationToken).ConfigureAwait(false);
-
-        await using SqliteCommand command = connection.CreateCommand();
-        command.CommandText = """
-            UPDATE api_keys
-            SET secret_hash = $secret_hash,
-                last_used_utc = NULL,
-                revoked_utc = NULL
-            WHERE key_id = $key_id;
-            """;
-        command.Parameters.AddWithValue("$key_id", keyId);
-        command.Parameters.Add("$secret_hash", SqliteType.Blob).Value = secretHash;
-
-        int rows = await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
-
-        return rows > 0;
-    }
-
-    /// <inheritdoc />
-    public async Task<bool> DeleteAsync(string keyId, CancellationToken cancellationToken)
-    {
-        await using SqliteConnection connection = await connectionFactory.OpenConnectionAsync(cancellationToken).ConfigureAwait(false);
-
-        await using SqliteCommand command = connection.CreateCommand();
-        command.CommandText = """
-            DELETE FROM api_keys
-            WHERE key_id = $key_id AND revoked_utc IS NOT NULL;
-            """;
-        command.Parameters.AddWithValue("$key_id", keyId);
-
-        int rows = await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
-
-        return rows > 0;
-    }
-
-    private static void AddCreateParameters(SqliteCommand command, ApiKeyCreateRequest request)
-    {
-        command.Parameters.AddWithValue("$key_id", request.KeyId);
-        command.Parameters.AddWithValue("$key_prefix", request.KeyPrefix);
-        command.Parameters.Add("$secret_hash", SqliteType.Blob).Value = request.SecretHash;
-        command.Parameters.AddWithValue("$display_name", request.DisplayName);
-        command.Parameters.AddWithValue("$scopes", ApiKeyScopeSerializer.Serialize(request.Scopes));
-        command.Parameters.AddWithValue(
-            "$constraints",
-            (object?)ApiKeyConstraintSerializer.Serialize(request.Constraints) ?? DBNull.Value);
-        command.Parameters.AddWithValue("$created_utc", request.CreatedUtc.ToString("O"));
-    }
-}

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/SqliteApiKeyAuditStore.cs

@@ -1,65 +0,0 @@
-using Microsoft.Data.Sqlite;
-
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-public sealed class SqliteApiKeyAuditStore(AuthSqliteConnectionFactory connectionFactory) : IApiKeyAuditStore
-{
-    /// <inheritdoc />
-    public async Task AppendAsync(ApiKeyAuditEntry entry, CancellationToken cancellationToken)
-    {
-        await using SqliteConnection connection = await connectionFactory.OpenConnectionAsync(cancellationToken).ConfigureAwait(false);
-
-        await using SqliteCommand command = connection.CreateCommand();
-        command.CommandText = """
-            INSERT INTO api_key_audit (key_id, event_type, remote_address, created_utc, details)
-            VALUES ($key_id, $event_type, $remote_address, $created_utc, $details);
-            """;
-        command.Parameters.AddWithValue("$key_id", (object?)entry.KeyId ?? DBNull.Value);
-        command.Parameters.AddWithValue("$event_type", entry.EventType);
-        command.Parameters.AddWithValue("$remote_address", (object?)entry.RemoteAddress ?? DBNull.Value);
-        command.Parameters.AddWithValue("$created_utc", DateTimeOffset.UtcNow.ToString("O"));
-        command.Parameters.AddWithValue("$details", (object?)entry.Details ?? DBNull.Value);
-
-        await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
-    }
-
-    /// <inheritdoc />
-    public async Task<IReadOnlyList<ApiKeyAuditRecord>> ListRecentAsync(int count, CancellationToken cancellationToken)
-    {
-        if (count <= 0)
-        {
-            return [];
-        }
-
-        await using SqliteConnection connection = await connectionFactory.OpenConnectionAsync(cancellationToken).ConfigureAwait(false);
-
-        await using SqliteCommand command = connection.CreateCommand();
-        command.CommandText = """
-            SELECT audit_id, key_id, event_type, remote_address, created_utc, details
-            FROM api_key_audit
-            ORDER BY audit_id DESC
-            LIMIT $count;
-            """;
-        command.Parameters.AddWithValue("$count", count);
-
-        List<ApiKeyAuditRecord> records = [];
-
-        await using SqliteDataReader reader = await command.ExecuteReaderAsync(cancellationToken)
-            .ConfigureAwait(false);
-
-        while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false))
-        {
-            records.Add(new ApiKeyAuditRecord(
-                AuditId: reader.GetInt64(0),
-                KeyId: reader.IsDBNull(1) ? null : reader.GetString(1),
-                EventType: reader.GetString(2),
-                RemoteAddress: reader.IsDBNull(3) ? null : reader.GetString(3),
-                CreatedUtc: DateTimeOffset.Parse(
-                    reader.GetString(4),
-                    System.Globalization.CultureInfo.InvariantCulture),
-                Details: reader.IsDBNull(5) ? null : reader.GetString(5)));
-        }
-
-        return records;
-    }
-}

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/SqliteApiKeyStore.cs

@@ -1,68 +0,0 @@
-using Microsoft.Data.Sqlite;
-
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-/// <summary>SQLite-based store for API key records.</summary>
-public sealed class SqliteApiKeyStore(AuthSqliteConnectionFactory connectionFactory) : IApiKeyStore
-{
-    /// <inheritdoc />
-    public Task<ApiKeyRecord?> FindByKeyIdAsync(string keyId, CancellationToken cancellationToken)
-    {
-        return FindByKeyIdAsync(keyId, requireActive: false, cancellationToken);
-    }
-
-    /// <inheritdoc />
-    public Task<ApiKeyRecord?> FindActiveByKeyIdAsync(string keyId, CancellationToken cancellationToken)
-    {
-        return FindByKeyIdAsync(keyId, requireActive: true, cancellationToken);
-    }
-
-    /// <inheritdoc />
-    public async Task MarkKeyUsedAsync(string keyId, DateTimeOffset usedUtc, CancellationToken cancellationToken)
-    {
-        await using SqliteConnection connection = await connectionFactory.OpenConnectionAsync(cancellationToken).ConfigureAwait(false);
-
-        await using SqliteCommand command = connection.CreateCommand();
-        command.CommandText = """
-            UPDATE api_keys
-            SET last_used_utc = $last_used_utc
-            WHERE key_id = $key_id AND revoked_utc IS NULL;
-            """;
-        command.Parameters.AddWithValue("$key_id", keyId);
-        command.Parameters.AddWithValue("$last_used_utc", usedUtc.ToString("O"));
-
-        await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
-    }
-
-    private async Task<ApiKeyRecord?> FindByKeyIdAsync(
-        string keyId,
-        bool requireActive,
-        CancellationToken cancellationToken)
-    {
-        await using SqliteConnection connection = await connectionFactory.OpenConnectionAsync(cancellationToken).ConfigureAwait(false);
-
-        await using SqliteCommand command = connection.CreateCommand();
-        command.CommandText = requireActive
-            ? """
-              SELECT key_id, key_prefix, secret_hash, display_name, scopes, constraints, created_utc, last_used_utc, revoked_utc
-              FROM api_keys
-              WHERE key_id = $key_id AND revoked_utc IS NULL;
-              """
-            : """
-              SELECT key_id, key_prefix, secret_hash, display_name, scopes, constraints, created_utc, last_used_utc, revoked_utc
-              FROM api_keys
-              WHERE key_id = $key_id;
-              """;
-        command.Parameters.AddWithValue("$key_id", keyId);
-
-        await using SqliteDataReader reader = await command.ExecuteReaderAsync(cancellationToken)
-            .ConfigureAwait(false);
-
-        if (!await reader.ReadAsync(cancellationToken).ConfigureAwait(false))
-        {
-            return null;
-        }
-
-        return ApiKeyRecordReader.Read(reader);
-    }
-}

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/SqliteAuthSchema.cs

@@ -1,12 +0,0 @@
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-public static class SqliteAuthSchema
-{
-    public const int CurrentVersion = 2;
-
-    public const string SchemaVersionTable = "schema_version";
-
-    public const string ApiKeysTable = "api_keys";
-
-    public const string ApiKeyAuditTable = "api_key_audit";
-}

src/ZB.MOM.WW.MxGateway.Server/Security/Authentication/SqliteAuthStoreMigrator.cs

@@ -1,192 +0,0 @@
-using Microsoft.Data.Sqlite;
-
-namespace ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-public sealed class SqliteAuthStoreMigrator(AuthSqliteConnectionFactory connectionFactory) : IAuthStoreMigrator
-{
-    /// <summary>Applies database migrations to the authentication store.</summary>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    public async Task MigrateAsync(CancellationToken cancellationToken)
-    {
-        await using SqliteConnection connection = await connectionFactory.OpenConnectionAsync(cancellationToken).ConfigureAwait(false);
-
-        await using SqliteTransaction transaction =
-            (SqliteTransaction)await connection.BeginTransactionAsync(cancellationToken).ConfigureAwait(false);
-
-        int existingVersion = await ReadExistingSchemaVersionAsync(connection, transaction, cancellationToken)
-            .ConfigureAwait(false);
-
-        if (existingVersion > SqliteAuthSchema.CurrentVersion)
-        {
-            throw new AuthStoreMigrationException(
-                $"Auth database schema version {existingVersion} is newer than supported version {SqliteAuthSchema.CurrentVersion}.");
-        }
-
-        await ApplyVersionOneAsync(connection, transaction, cancellationToken).ConfigureAwait(false);
-        await ApplyVersionTwoAsync(connection, transaction, cancellationToken).ConfigureAwait(false);
-        await WriteSchemaVersionAsync(connection, transaction, cancellationToken).ConfigureAwait(false);
-
-        await transaction.CommitAsync(cancellationToken).ConfigureAwait(false);
-    }
-
-    private static async Task<int> ReadExistingSchemaVersionAsync(
-        SqliteConnection connection,
-        SqliteTransaction transaction,
-        CancellationToken cancellationToken)
-    {
-        await using SqliteCommand tableExistsCommand = connection.CreateCommand();
-        tableExistsCommand.Transaction = transaction;
-        tableExistsCommand.CommandText = """
-            SELECT COUNT(*)
-            FROM sqlite_master
-            WHERE type = 'table' AND name = $table_name;
-            """;
-        tableExistsCommand.Parameters.AddWithValue("$table_name", SqliteAuthSchema.SchemaVersionTable);
-
-        long tableCount = (long)(await tableExistsCommand.ExecuteScalarAsync(cancellationToken).ConfigureAwait(false) ?? 0L);
-
-        if (tableCount == 0)
-        {
-            return 0;
-        }
-
-        await using SqliteCommand versionCommand = connection.CreateCommand();
-        versionCommand.Transaction = transaction;
-        versionCommand.CommandText = """
-            SELECT version
-            FROM schema_version
-            WHERE id = 1;
-            """;
-
-        object? version = await versionCommand.ExecuteScalarAsync(cancellationToken).ConfigureAwait(false);
-
-        return version is null || version == DBNull.Value
-            ? 0
-            : Convert.ToInt32(version, System.Globalization.CultureInfo.InvariantCulture);
-    }
-
-    private static async Task ApplyVersionOneAsync(
-        SqliteConnection connection,
-        SqliteTransaction transaction,
-        CancellationToken cancellationToken)
-    {
-        await ExecuteNonQueryAsync(
-            connection,
-            transaction,
-            """
-            CREATE TABLE IF NOT EXISTS schema_version (
-                id INTEGER PRIMARY KEY CHECK (id = 1),
-                version INTEGER NOT NULL,
-                applied_utc TEXT NOT NULL
-            );
-
-            CREATE TABLE IF NOT EXISTS api_keys (
-                key_id TEXT PRIMARY KEY,
-                key_prefix TEXT NOT NULL,
-                secret_hash BLOB NOT NULL,
-                display_name TEXT NOT NULL,
-                scopes TEXT NOT NULL,
-                constraints TEXT NULL,
-                created_utc TEXT NOT NULL,
-                last_used_utc TEXT NULL,
-                revoked_utc TEXT NULL
-            );
-
-            CREATE TABLE IF NOT EXISTS api_key_audit (
-                audit_id INTEGER PRIMARY KEY AUTOINCREMENT,
-                key_id TEXT NULL,
-                event_type TEXT NOT NULL,
-                remote_address TEXT NULL,
-                created_utc TEXT NOT NULL,
-                details TEXT NULL
-            );
-
-            CREATE INDEX IF NOT EXISTS ix_api_keys_revoked_utc
-                ON api_keys (revoked_utc);
-
-            CREATE INDEX IF NOT EXISTS ix_api_key_audit_key_id_created_utc
-                ON api_key_audit (key_id, created_utc);
-            """,
-            cancellationToken).ConfigureAwait(false);
-
-    }
-
-    private static async Task ApplyVersionTwoAsync(
-        SqliteConnection connection,
-        SqliteTransaction transaction,
-        CancellationToken cancellationToken)
-    {
-        if (await ColumnExistsAsync(connection, transaction, SqliteAuthSchema.ApiKeysTable, "constraints", cancellationToken)
-            .ConfigureAwait(false))
-        {
-            return;
-        }
-
-        await ExecuteNonQueryAsync(
-            connection,
-            transaction,
-            """
-            ALTER TABLE api_keys
-            ADD COLUMN constraints TEXT NULL;
-            """,
-            cancellationToken).ConfigureAwait(false);
-    }
-
-    private static async Task WriteSchemaVersionAsync(
-        SqliteConnection connection,
-        SqliteTransaction transaction,
-        CancellationToken cancellationToken)
-    {
-        await using SqliteCommand versionCommand = connection.CreateCommand();
-        versionCommand.Transaction = transaction;
-        versionCommand.CommandText = """
-            INSERT INTO schema_version (id, version, applied_utc)
-            VALUES (1, $version, $applied_utc)
-            ON CONFLICT(id) DO UPDATE SET
-                version = excluded.version,
-                applied_utc = excluded.applied_utc;
-            """;
-        versionCommand.Parameters.AddWithValue("$version", SqliteAuthSchema.CurrentVersion);
-        versionCommand.Parameters.AddWithValue("$applied_utc", DateTimeOffset.UtcNow.ToString("O"));
-
-        await versionCommand.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
-    }
-
-    private static async Task<bool> ColumnExistsAsync(
-        SqliteConnection connection,
-        SqliteTransaction transaction,
-        string tableName,
-        string columnName,
-        CancellationToken cancellationToken)
-    {
-        await using SqliteCommand command = connection.CreateCommand();
-        command.Transaction = transaction;
-        command.CommandText = $"PRAGMA table_info({tableName});";
-
-        await using SqliteDataReader reader = await command.ExecuteReaderAsync(cancellationToken)
-            .ConfigureAwait(false);
-
-        while (await reader.ReadAsync(cancellationToken).ConfigureAwait(false))
-        {
-            if (string.Equals(reader.GetString(1), columnName, StringComparison.OrdinalIgnoreCase))
-            {
-                return true;
-            }
-        }
-
-        return false;
-    }
-
-    private static async Task ExecuteNonQueryAsync(
-        SqliteConnection connection,
-        SqliteTransaction transaction,
-        string commandText,
-        CancellationToken cancellationToken)
-    {
-        await using SqliteCommand command = connection.CreateCommand();
-        command.Transaction = transaction;
-        command.CommandText = commandText;
-
-        await command.ExecuteNonQueryAsync(cancellationToken).ConfigureAwait(false);
-    }
-}

src/ZB.MOM.WW.MxGateway.Server/Security/Authorization/ConstraintEnforcer.cs

@@ -1,13 +1,20 @@
+using System.Text.Json;
+using ZB.MOM.WW.Audit;
 using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
 using ZB.MOM.WW.MxGateway.Server.Galaxy;
+using ZB.MOM.WW.MxGateway.Server.Security.Audit;
 using ZB.MOM.WW.MxGateway.Server.Security.Authentication;
 using ZB.MOM.WW.MxGateway.Server.Sessions;
 
+// The gateway carries its own constraint-bearing identity downstream; the shared library also
+// defines an ApiKeyIdentity (scopes + opaque constraints JSON), so disambiguate to the gateway type.
+using ApiKeyIdentity = ZB.MOM.WW.MxGateway.Server.Security.Authentication.ApiKeyIdentity;
+
 namespace ZB.MOM.WW.MxGateway.Server.Security.Authorization;
 
 public sealed class ConstraintEnforcer(
     IGalaxyHierarchyCache cache,
-    IApiKeyAuditStore auditStore) : IConstraintEnforcer
+    IAuditWriter auditWriter) : IConstraintEnforcer
 {
     /// <summary>Checks read constraints on a tag address.</summary>
     /// <param name="identity">The API key identity to check constraints for.</param>
@@ -121,14 +128,33 @@ public sealed class ConstraintEnforcer(
         ConstraintFailure failure,
         CancellationToken cancellationToken)
     {
-        await auditStore.AppendAsync(
-                new ApiKeyAuditEntry(
-                    KeyId: identity?.KeyId,
-                    EventType: "constraint-denied",
-                    RemoteAddress: null,
-                    Details: $"{commandKind}: {target}: {failure.ConstraintName}: {failure.Message}"),
-                cancellationToken)
-            .ConfigureAwait(false);
+        // Emit a canonical Denied AuditEvent directly through the best-effort IAuditWriter
+        // (Task 2.3 #6): structured Target ("<commandKind>:<target>") and a richer DetailsJson
+        // envelope carrying constraint/message/commandKind/target.
+        // TODO(Task 2.3): CorrelationId is left null here. Threading the per-request
+        // ClientCorrelationId down to RecordDenialAsync would require an invasive IConstraintEnforcer
+        // signature change across the gRPC call path; that is deferred to a follow-up.
+        AuditEvent auditEvent = new()
+        {
+            EventId = Guid.NewGuid(),
+            OccurredAtUtc = DateTimeOffset.UtcNow,
+            Actor = identity?.KeyId ?? "anonymous",
+            Action = "constraint-denied",
+            Outcome = AuditOutcome.Denied,
+            Category = CanonicalForwardingApiKeyAuditStore.ApiKeyCategory,
+            Target = $"{commandKind}:{target}",
+            SourceNode = null,
+            CorrelationId = null,
+            DetailsJson = JsonSerializer.Serialize(new Dictionary<string, string>
+            {
+                ["constraint"] = failure.ConstraintName,
+                ["message"] = failure.Message,
+                ["commandKind"] = commandKind,
+                ["target"] = target,
+            }),
+        };
+
+        await auditWriter.WriteAsync(auditEvent, cancellationToken).ConfigureAwait(false);
     }
 
     private ConstraintFailure? CheckReadTarget(

src/ZB.MOM.WW.MxGateway.Server/Security/Authorization/GatewayGrpcAuthorizationInterceptor.cs

@@ -1,9 +1,14 @@
 using Grpc.Core;
 using Grpc.Core.Interceptors;
 using Microsoft.Extensions.Options;
+using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
 using ZB.MOM.WW.MxGateway.Server.Configuration;
 using ZB.MOM.WW.MxGateway.Server.Security.Authentication;
 
+// The handler pushes the gateway's constraint-bearing identity; alias away the shared library's
+// ApiKeyIdentity so the unqualified name resolves to the gateway type.
+using ApiKeyIdentity = ZB.MOM.WW.MxGateway.Server.Security.Authentication.ApiKeyIdentity;
+
 namespace ZB.MOM.WW.MxGateway.Server.Security.Authorization;
 
 public sealed class GatewayGrpcAuthorizationInterceptor(
@@ -57,25 +62,31 @@ public sealed class GatewayGrpcAuthorizationInterceptor(
         }
 
         string? authorizationHeader = context.RequestHeaders.GetValue("authorization");
-        ApiKeyVerificationResult verificationResult = await apiKeyVerifier
-            .VerifyAsync(authorizationHeader, context.CancellationToken)
+
+        // The shared verifier owns parse + pepper + lookup + revocation + constant-time compare,
+        // returning a discriminated failure rather than throwing. Every authentication failure maps
+        // to Unauthenticated with an opaque message; the client never learns which stage failed.
+        ApiKeyVerification verification = await apiKeyVerifier
+            .VerifyAsync(authorizationHeader ?? string.Empty, context.CancellationToken)
             .ConfigureAwait(false);
 
-        if (!verificationResult.Succeeded || verificationResult.Identity is null)
+        if (!verification.Succeeded || verification.Identity is null)
         {
             throw new RpcException(new Status(
                 StatusCode.Unauthenticated,
                 "Missing or invalid API key."));
         }
 
+        ApiKeyIdentity identity = GatewayApiKeyIdentityMapper.ToGatewayIdentity(verification.Identity);
+
         string requiredScope = scopeResolver.ResolveRequiredScope(request);
-        if (!verificationResult.Identity.Scopes.Contains(requiredScope))
+        if (!identity.Scopes.Contains(requiredScope))
         {
             throw new RpcException(new Status(
                 StatusCode.PermissionDenied,
                 $"API key is missing required scope '{requiredScope}'."));
         }
 
-        return verificationResult.Identity;
+        return identity;
     }
 }

src/ZB.MOM.WW.MxGateway.Server/ZB.MOM.WW.MxGateway.Server.csproj

@@ -6,6 +6,11 @@
 
   <ItemGroup>
     <PackageReference Include="Grpc.AspNetCore" Version="2.76.0" />
+    <PackageReference Include="ZB.MOM.WW.Auth.Abstractions" Version="0.1.2" />
+    <PackageReference Include="ZB.MOM.WW.Auth.Ldap" Version="0.1.2" />
+    <PackageReference Include="ZB.MOM.WW.Auth.ApiKeys" Version="0.1.2" />
+    <PackageReference Include="ZB.MOM.WW.Auth.AspNetCore" Version="0.1.2" />
+    <PackageReference Include="ZB.MOM.WW.Audit" Version="0.1.0" />
     <PackageReference Include="ZB.MOM.WW.Configuration" Version="0.1.0" />
     <PackageReference Include="ZB.MOM.WW.Health" Version="0.1.0" />
     <PackageReference Include="ZB.MOM.WW.Telemetry" Version="0.1.0" />
@@ -16,7 +21,6 @@
     <PackageReference Include="Microsoft.AspNetCore.SignalR.Client" Version="10.0.0" />
     <PackageReference Include="Microsoft.Data.Sqlite" Version="10.0.7" />
     <PackageReference Include="Microsoft.Data.SqlClient" Version="6.0.2" />
-    <PackageReference Include="Novell.Directory.Ldap.NETStandard" Version="3.6.0" />
     <PackageReference Include="Polly.Core" Version="8.6.6" />
   </ItemGroup>
 

src/ZB.MOM.WW.MxGateway.Server/appsettings.json

@@ -22,10 +22,10 @@
       "Enabled": true,
       "Server": "localhost",
       "Port": 3893,
-      "UseTls": false,
-      "AllowInsecureLdap": true,
-      "SearchBase": "dc=lmxopcua,dc=local",
-      "ServiceAccountDn": "cn=serviceaccount,dc=lmxopcua,dc=local",
+      "Transport": "None",
+      "AllowInsecure": true,
+      "SearchBase": "dc=zb,dc=local",
+      "ServiceAccountDn": "cn=serviceaccount,dc=zb,dc=local",
       "ServiceAccountPassword": "serviceaccount123",
       "UserNameAttribute": "cn",
       "DisplayNameAttribute": "cn",
@@ -60,7 +60,7 @@
       "RecentSessionLimit": 200,
       "ShowTagValues": false,
       "GroupToRole": {
-        "GwAdmin": "Admin",
+        "GwAdmin": "Administrator",
         "GwReader": "Viewer"
       }
     },

src/ZB.MOM.WW.MxGateway.Tests/Configuration/GatewayOptionsTests.cs

@@ -87,7 +87,7 @@ public sealed class GatewayOptionsTests
     [InlineData("MxGateway:Events:QueueCapacity", "0", "MxGateway:Events:QueueCapacity must be greater than zero.")]
     [InlineData("MxGateway:Protocol:MaxGrpcMessageBytes", "0", "MxGateway:Protocol:MaxGrpcMessageBytes must be between")]
     [InlineData("MxGateway:Authentication:PepperSecretName", "", "MxGateway:Authentication:PepperSecretName is required")]
-    [InlineData("MxGateway:Dashboard:GroupToRole:GwAdmin", "Sysadmin", "MxGateway:Dashboard:GroupToRole['GwAdmin'] must be 'Admin' or 'Viewer'.")]
+    [InlineData("MxGateway:Dashboard:GroupToRole:GwAdmin", "Sysadmin", "MxGateway:Dashboard:GroupToRole['GwAdmin'] must be 'Administrator' or 'Viewer'.")]
     public void Validation_InvalidConfiguration_FailsClearly(string key, string value, string expectedFailure)
     {
         OptionsValidationException exception = Assert.Throws<OptionsValidationException>(() =>

src/ZB.MOM.WW.MxGateway.Tests/Diagnostics/AuthStoreHealthCheckTests.cs

@@ -1,8 +1,6 @@
 using Microsoft.Extensions.Diagnostics.HealthChecks;
-using Microsoft.Extensions.Options;
-using ZB.MOM.WW.MxGateway.Server.Configuration;
+using ZB.MOM.WW.Auth.ApiKeys.Sqlite;
 using ZB.MOM.WW.MxGateway.Server.Diagnostics;
-using ZB.MOM.WW.MxGateway.Server.Security.Authentication;
 
 namespace ZB.MOM.WW.MxGateway.Tests.Diagnostics;
 
@@ -10,13 +8,8 @@ public sealed class AuthStoreHealthCheckTests
 {
     private static AuthSqliteConnectionFactory FactoryFor(string sqlitePath)
     {
-        // GatewayOptions.Authentication and AuthenticationOptions.SqlitePath are both
-        // init-only, so populate them through object initializers.
-        var options = new GatewayOptions
-        {
-            Authentication = new AuthenticationOptions { SqlitePath = sqlitePath },
-        };
-        return new AuthSqliteConnectionFactory(Options.Create(options));
+        // The shared connection factory targets a database path directly.
+        return new AuthSqliteConnectionFactory(sqlitePath);
     }
 
     [Fact]

src/ZB.MOM.WW.MxGateway.Tests/Gateway/Dashboard/DashboardApiKeyManagementServiceTests.cs

@@ -1,21 +1,39 @@
 using System.Security.Claims;
 using Microsoft.AspNetCore.Http;
-using Microsoft.Extensions.Options;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
+using ZB.MOM.WW.Auth.ApiKeys.Admin;
+using ZB.MOM.WW.Auth.AspNetCore;
 using ZB.MOM.WW.MxGateway.Server.Configuration;
 using ZB.MOM.WW.MxGateway.Server.Dashboard;
+using ZB.MOM.WW.MxGateway.Server.Security.Audit;
 using ZB.MOM.WW.MxGateway.Server.Security.Authentication;
 using ZB.MOM.WW.MxGateway.Server.Security.Authorization;
+using ZB.MOM.WW.MxGateway.Tests.Security.Authentication;
+
+// The mapped identity is the gateway's constraint-bearing type; disambiguate from the library's.
+using ApiKeyIdentity = ZB.MOM.WW.MxGateway.Server.Security.Authentication.ApiKeyIdentity;
 
 namespace ZB.MOM.WW.MxGateway.Tests.Gateway.Dashboard;
 
-public sealed class DashboardApiKeyManagementServiceTests
+/// <summary>
+/// Tests the gateway dashboard API-key management surface over the shared
+/// <c>ZB.MOM.WW.Auth.ApiKeys</c> admin commands and stores (the gateway is the donor). The service
+/// is exercised against a real temporary SQLite store so the create/revoke/rotate/delete flow,
+/// dashboard audit vocabulary, mxgw token format, duplicate-id rejection and revoke-before-delete
+/// rule are all proven end-to-end.
+/// </summary>
+public sealed class DashboardApiKeyManagementServiceTests : IDisposable
 {
+    private readonly List<TempDatabaseDirectory> _tempDirectories = [];
+
     /// <summary>Verifies that unauthorized users cannot create API keys.</summary>
     [Fact]
-    public async Task CreateAsync_UnauthorizedUser_DoesNotCallStore()
+    public async Task CreateAsync_UnauthorizedUser_DoesNotCreate()
     {
-        FakeApiKeyAdminStore adminStore = new();
-        DashboardApiKeyManagementService service = CreateService(adminStore);
+        await using ServiceProvider services = BuildServices();
+        DashboardApiKeyManagementService service = CreateService(services);
 
         DashboardApiKeyManagementResult result = await service.CreateAsync(
             new ClaimsPrincipal(new ClaimsIdentity()),
@@ -23,17 +41,15 @@ public sealed class DashboardApiKeyManagementServiceTests
             CancellationToken.None);
 
         Assert.False(result.Succeeded);
-        Assert.Equal(0, adminStore.CreateCount);
+        Assert.Empty(await ListAsync(services));
     }
 
-    /// <summary>Verifies that authorized users can create keys with secret hashing and audit trail.</summary>
+    /// <summary>Verifies that authorized users create a verifiable, constrained key and audit it.</summary>
     [Fact]
-    public async Task CreateAsync_AuthorizedUser_StoresHashOfSecretAndAudits()
+    public async Task CreateAsync_AuthorizedUser_CreatesVerifiableKeyAndAudits()
     {
-        FakeApiKeyAdminStore adminStore = new();
-        FakeApiKeyAuditStore auditStore = new();
-        FakeApiKeySecretHasher hasher = new();
-        DashboardApiKeyManagementService service = CreateService(adminStore, auditStore, hasher);
+        await using ServiceProvider services = BuildServices();
+        DashboardApiKeyManagementService service = CreateService(services);
 
         DashboardApiKeyManagementResult result = await service.CreateAsync(
             CreateAuthorizedUser(),
@@ -43,42 +59,49 @@ public sealed class DashboardApiKeyManagementServiceTests
         Assert.True(result.Succeeded);
         Assert.NotNull(result.ApiKey);
         Assert.StartsWith("mxgw_operator01_", result.ApiKey, StringComparison.Ordinal);
-        string secret = result.ApiKey["mxgw_operator01_".Length..];
-        Assert.Equal(secret, hasher.LastSecret);
-        Assert.DoesNotContain("mxgw_operator01_", hasher.LastSecret, StringComparison.Ordinal);
-        ApiKeyCreateRequest stored = Assert.Single(adminStore.CreatedRequests);
-        Assert.Equal("operator01", stored.KeyId);
-        Assert.Equal("Operator", stored.DisplayName);
-        Assert.Contains(GatewayScopes.SessionOpen, stored.Scopes);
-        Assert.Equal(["Area1/*"], stored.Constraints.BrowseSubtrees);
-        Assert.Contains(auditStore.Entries, entry =>
+
+        // The freshly minted token authenticates against the same store and surfaces its scopes.
+        ApiKeyVerification verification = await services
+            .GetRequiredService<IApiKeyVerifier>()
+            .VerifyAsync($"Bearer {result.ApiKey}", CancellationToken.None);
+        Assert.True(verification.Succeeded);
+        Assert.Contains(GatewayScopes.SessionOpen, verification.Identity!.Scopes);
+
+        // Constraints round-trip through the opaque JSON blob.
+        ApiKeyIdentity gatewayIdentity = GatewayApiKeyIdentityMapper.ToGatewayIdentity(verification.Identity);
+        Assert.Equal(["Area1/*"], gatewayIdentity.EffectiveConstraints.BrowseSubtrees);
+
+        IReadOnlyList<ApiKeyAuditEntry> audit = await ListAuditAsync(services);
+        // Phase 3: Actor = operator username ("alice"), Target = managed keyId ("operator01").
+        Assert.Contains(audit, entry =>
             entry.EventType == "dashboard-create-key"
-            && entry.KeyId == "operator01");
+            && entry.KeyId == "alice");
     }
 
-    /// <summary>Verifies that unauthorized users cannot revoke API keys.</summary>
+    /// <summary>Verifies that creating a key whose id already exists is rejected.</summary>
     [Fact]
-    public async Task RevokeAsync_UnauthorizedUser_DoesNotCallStore()
+    public async Task CreateAsync_DuplicateKeyId_ReportsConflict()
     {
-        FakeApiKeyAdminStore adminStore = new();
-        DashboardApiKeyManagementService service = CreateService(adminStore);
+        await using ServiceProvider services = BuildServices();
+        DashboardApiKeyManagementService service = CreateService(services);
 
-        DashboardApiKeyManagementResult result = await service.RevokeAsync(
-            new ClaimsPrincipal(new ClaimsIdentity()),
-            "operator01",
+        await service.CreateAsync(CreateAuthorizedUser(), CreateRequest(), CancellationToken.None);
+        DashboardApiKeyManagementResult duplicate = await service.CreateAsync(
+            CreateAuthorizedUser(),
+            CreateRequest(),
             CancellationToken.None);
 
-        Assert.False(result.Succeeded);
-        Assert.Equal(0, adminStore.RevokeCount);
+        Assert.False(duplicate.Succeeded);
+        Assert.Contains("already exists", duplicate.Message, StringComparison.OrdinalIgnoreCase);
     }
 
     /// <summary>Verifies that authorized users can revoke keys with audit trail.</summary>
     [Fact]
     public async Task RevokeAsync_AuthorizedUser_RevokesAndAudits()
     {
-        FakeApiKeyAdminStore adminStore = new() { RevokeResult = true };
-        FakeApiKeyAuditStore auditStore = new();
-        DashboardApiKeyManagementService service = CreateService(adminStore, auditStore);
+        await using ServiceProvider services = BuildServices();
+        DashboardApiKeyManagementService service = CreateService(services);
+        await service.CreateAsync(CreateAuthorizedUser(), CreateRequest(), CancellationToken.None);
 
         DashboardApiKeyManagementResult result = await service.RevokeAsync(
             CreateAuthorizedUser(),
@@ -86,21 +109,25 @@ public sealed class DashboardApiKeyManagementServiceTests
             CancellationToken.None);
 
         Assert.True(result.Succeeded);
-        Assert.Equal("operator01", adminStore.LastRevokedKeyId);
-        Assert.Contains(auditStore.Entries, entry =>
+        ApiKeyListItem key = Assert.Single(await ListAsync(services));
+        Assert.NotNull(key.RevokedUtc);
+        IReadOnlyList<ApiKeyAuditEntry> audit = await ListAuditAsync(services);
+        // Phase 3: Actor = operator username; the dashboard-revoke-key event surfaces KeyId = "alice"
+        // (the operator) and Details = "revoked".
+        Assert.Contains(audit, entry =>
             entry.EventType == "dashboard-revoke-key"
-            && entry.KeyId == "operator01"
+            && entry.KeyId == "alice"
             && entry.Details == "revoked");
     }
 
-    /// <summary>Verifies that authorized users can rotate secret hashes with audit trail.</summary>
+    /// <summary>Verifies that authorized users can rotate a key's secret with audit trail.</summary>
     [Fact]
-    public async Task RotateAsync_AuthorizedUser_RotatesHashAndAudits()
+    public async Task RotateAsync_AuthorizedUser_RotatesAndAudits()
     {
-        FakeApiKeyAdminStore adminStore = new() { RotateResult = true };
-        FakeApiKeyAuditStore auditStore = new();
-        FakeApiKeySecretHasher hasher = new();
-        DashboardApiKeyManagementService service = CreateService(adminStore, auditStore, hasher);
+        await using ServiceProvider services = BuildServices();
+        DashboardApiKeyManagementService service = CreateService(services);
+        DashboardApiKeyManagementResult created = await service.CreateAsync(
+            CreateAuthorizedUser(), CreateRequest(), CancellationToken.None);
 
         DashboardApiKeyManagementResult result = await service.RotateAsync(
             CreateAuthorizedUser(),
@@ -110,36 +137,29 @@ public sealed class DashboardApiKeyManagementServiceTests
         Assert.True(result.Succeeded);
         Assert.NotNull(result.ApiKey);
         Assert.StartsWith("mxgw_operator01_", result.ApiKey, StringComparison.Ordinal);
-        Assert.Equal(hasher.HashSecret(hasher.LastSecret!), adminStore.LastRotatedSecretHash);
-        Assert.Contains(auditStore.Entries, entry =>
+        Assert.NotEqual(created.ApiKey, result.ApiKey);
+
+        // Old token no longer authenticates; new one does.
+        IApiKeyVerifier verifier = services.GetRequiredService<IApiKeyVerifier>();
+        Assert.False((await verifier.VerifyAsync($"Bearer {created.ApiKey}", CancellationToken.None)).Succeeded);
+        Assert.True((await verifier.VerifyAsync($"Bearer {result.ApiKey}", CancellationToken.None)).Succeeded);
+
+        IReadOnlyList<ApiKeyAuditEntry> audit = await ListAuditAsync(services);
+        // Phase 3: Actor = operator username ("alice").
+        Assert.Contains(audit, entry =>
             entry.EventType == "dashboard-rotate-key"
-            && entry.KeyId == "operator01"
+            && entry.KeyId == "alice"
             && entry.Details == "rotated");
     }
 
-    /// <summary>Verifies that unauthorized users cannot delete API keys.</summary>
-    [Fact]
-    public async Task DeleteAsync_UnauthorizedUser_DoesNotCallStore()
-    {
-        FakeApiKeyAdminStore adminStore = new();
-        DashboardApiKeyManagementService service = CreateService(adminStore);
-
-        DashboardApiKeyManagementResult result = await service.DeleteAsync(
-            new ClaimsPrincipal(new ClaimsIdentity()),
-            "operator01",
-            CancellationToken.None);
-
-        Assert.False(result.Succeeded);
-        Assert.Equal(0, adminStore.DeleteCount);
-    }
-
     /// <summary>Verifies that authorized users can delete revoked keys with audit trail.</summary>
     [Fact]
     public async Task DeleteAsync_AuthorizedUser_DeletesRevokedKeyAndAudits()
     {
-        FakeApiKeyAdminStore adminStore = new() { DeleteResult = true };
-        FakeApiKeyAuditStore auditStore = new();
-        DashboardApiKeyManagementService service = CreateService(adminStore, auditStore);
+        await using ServiceProvider services = BuildServices();
+        DashboardApiKeyManagementService service = CreateService(services);
+        await service.CreateAsync(CreateAuthorizedUser(), CreateRequest(), CancellationToken.None);
+        await service.RevokeAsync(CreateAuthorizedUser(), "operator01", CancellationToken.None);
 
         DashboardApiKeyManagementResult result = await service.DeleteAsync(
             CreateAuthorizedUser(),
@@ -147,27 +167,26 @@ public sealed class DashboardApiKeyManagementServiceTests
             CancellationToken.None);
 
         Assert.True(result.Succeeded);
-        Assert.Equal("operator01", adminStore.LastDeletedKeyId);
-        Assert.Contains(auditStore.Entries, entry =>
+        Assert.Empty(await ListAsync(services));
+        IReadOnlyList<ApiKeyAuditEntry> audit = await ListAuditAsync(services);
+        // Phase 3: Actor = operator username ("alice").
+        Assert.Contains(audit, entry =>
             entry.EventType == "dashboard-delete-key"
-            && entry.KeyId == "operator01"
+            && entry.KeyId == "alice"
             && entry.Details == "deleted");
     }
 
     /// <summary>
-    /// Tests-030: when the admin store refuses the delete (returns <c>false</c>), the service
-    /// still emits a <c>dashboard-delete-key</c> audit entry with <c>Details = "not-found-or-active"</c>
-    /// because <c>AppendAuditAsync</c> runs unconditionally after the store call. A regression that
-    /// moved the audit-append call inside the <c>if (deleted)</c> branch would silently drop the
-    /// audit trail for refused deletes — a real audit-completeness gap. This test pins both the
-    /// friendly-error response AND the unconditional audit entry.
+    /// When the key is still active (not revoked), the delete is refused but a
+    /// <c>dashboard-delete-key</c> audit entry with <c>Details = "not-found-or-active"</c> is still
+    /// written — audit completeness for refused deletes.
     /// </summary>
     [Fact]
-    public async Task DeleteAsync_WhenStoreRefuses_ReportsFriendlyErrorAndAudits()
+    public async Task DeleteAsync_ActiveKey_ReportsFriendlyErrorAndAudits()
     {
-        FakeApiKeyAdminStore adminStore = new() { DeleteResult = false };
-        FakeApiKeyAuditStore auditStore = new();
-        DashboardApiKeyManagementService service = CreateService(adminStore, auditStore);
+        await using ServiceProvider services = BuildServices();
+        DashboardApiKeyManagementService service = CreateService(services);
+        await service.CreateAsync(CreateAuthorizedUser(), CreateRequest(), CancellationToken.None);
 
         DashboardApiKeyManagementResult result = await service.DeleteAsync(
             CreateAuthorizedUser(),
@@ -177,17 +196,15 @@ public sealed class DashboardApiKeyManagementServiceTests
         Assert.False(result.Succeeded);
         Assert.Contains("Revoke", result.Message, StringComparison.Ordinal);
 
-        ApiKeyAuditEntry auditEntry = Assert.Single(auditStore.Entries);
-        Assert.Equal("dashboard-delete-key", auditEntry.EventType);
-        Assert.Equal("operator01", auditEntry.KeyId);
-        Assert.Equal("not-found-or-active", auditEntry.Details);
+        IReadOnlyList<ApiKeyAuditEntry> audit = await ListAuditAsync(services);
+        ApiKeyAuditEntry deleteEntry = Assert.Single(
+            audit, entry => entry.EventType == "dashboard-delete-key");
+        // Phase 3: Actor = operator username ("alice"), not the managed keyId.
+        Assert.Equal("alice", deleteEntry.KeyId);
+        Assert.Equal("not-found-or-active", deleteEntry.Details);
     }
 
-    /// <summary>
-    /// Tests-030: <see cref="DashboardApiKeyManagementService.DeleteAsync"/> calls
-    /// <c>ValidateKeyId</c> after the authorisation check. A blank key id must fail with the
-    /// shared "API key id is required." message before any store or audit call runs.
-    /// </summary>
+    /// <summary>A blank key id fails validation before any store or audit call runs.</summary>
     /// <param name="blankKeyId">A blank or whitespace key identifier.</param>
     [Theory]
     [InlineData("")]
@@ -195,9 +212,8 @@ public sealed class DashboardApiKeyManagementServiceTests
     [InlineData("\t")]
     public async Task DeleteAsync_BlankKeyId_ReturnsFailure(string blankKeyId)
     {
-        FakeApiKeyAdminStore adminStore = new();
-        FakeApiKeyAuditStore auditStore = new();
-        DashboardApiKeyManagementService service = CreateService(adminStore, auditStore);
+        await using ServiceProvider services = BuildServices();
+        DashboardApiKeyManagementService service = CreateService(services);
 
         DashboardApiKeyManagementResult result = await service.DeleteAsync(
             CreateAuthorizedUser(),
@@ -205,20 +221,19 @@ public sealed class DashboardApiKeyManagementServiceTests
             CancellationToken.None);
 
         Assert.False(result.Succeeded);
-        Assert.Equal(0, adminStore.DeleteCount);
-        Assert.Empty(auditStore.Entries);
+        Assert.Empty(await ListAuditAsync(services));
     }
 
     /// <summary>
-    ///     Server-004 regression: the dashboard create path must reject a request
-    ///     carrying a non-canonical scope string rather than persisting a key whose
-    ///     scope the authorization resolver never matches.
+    /// Server-004 regression: the dashboard create path must reject a request carrying a
+    /// non-canonical scope string rather than persisting a key whose scope the authorization
+    /// resolver never matches.
     /// </summary>
     [Fact]
-    public async Task CreateAsync_UnknownScope_DoesNotCallStore()
+    public async Task CreateAsync_UnknownScope_DoesNotCreate()
     {
-        FakeApiKeyAdminStore adminStore = new();
-        DashboardApiKeyManagementService service = CreateService(adminStore);
+        await using ServiceProvider services = BuildServices();
+        DashboardApiKeyManagementService service = CreateService(services);
 
         DashboardApiKeyManagementRequest request = CreateRequest() with
         {
@@ -233,25 +248,99 @@ public sealed class DashboardApiKeyManagementServiceTests
             CancellationToken.None);
 
         Assert.False(result.Succeeded);
-        Assert.Equal(0, adminStore.CreateCount);
+        Assert.Empty(await ListAsync(services));
     }
 
-    private static DashboardApiKeyManagementService CreateService(
-        FakeApiKeyAdminStore? adminStore = null,
-        FakeApiKeyAuditStore? auditStore = null,
-        FakeApiKeySecretHasher? hasher = null)
+    /// <summary>
+    /// Phase 3 canonical audit shape: the dashboard-create-key canonical AuditEvent records
+    /// the operator username as Actor and the managed keyId as Target.
+    /// </summary>
+    [Fact]
+    public async Task CreateAsync_AuthorizedUser_CanonicalAuditEventHasOperatorAsActorAndKeyIdAsTarget()
+    {
+        await using ServiceProvider services = BuildServices();
+
+        // Wire a recording writer so we can inspect the canonical AuditEvent directly (bypassing
+        // the CanonicalForwardingApiKeyAuditStore round-trip that ListAuditAsync uses).
+        RecordingAuditWriter recordingWriter = new();
+        DefaultHttpContext httpContext = new();
+        httpContext.Connection.RemoteIpAddress = System.Net.IPAddress.Loopback;
+
+        DashboardApiKeyManagementService service = new(
+            new DashboardApiKeyAuthorization(),
+            services.GetRequiredService<ApiKeyAdminCommands>(),
+            services.GetRequiredService<IApiKeyAdminStore>(),
+            recordingWriter,
+            new HttpContextAccessor { HttpContext = httpContext });
+
+        await service.CreateAsync(
+            CreateAuthorizedUser(),
+            CreateRequest(),
+            CancellationToken.None);
+
+        // The dashboard-create-key event emitted directly by the service (not the library's
+        // create-key event forwarded via the adapter) must have Actor = operator username and
+        // Target = managed keyId.
+        ZB.MOM.WW.Audit.AuditEvent dashboardEvent = Assert.Single(
+            recordingWriter.Events,
+            e => e.Action == "dashboard-create-key");
+        Assert.Equal("alice", dashboardEvent.Actor);
+        Assert.Equal("operator01", dashboardEvent.Target);
+        Assert.Equal(ZB.MOM.WW.Audit.AuditOutcome.Success, dashboardEvent.Outcome);
+    }
+
+    private DashboardApiKeyManagementService CreateService(ServiceProvider services)
     {
         DefaultHttpContext httpContext = new();
         httpContext.Connection.RemoteIpAddress = System.Net.IPAddress.Loopback;
 
         return new DashboardApiKeyManagementService(
             new DashboardApiKeyAuthorization(),
-            adminStore ?? new FakeApiKeyAdminStore(),
-            auditStore ?? new FakeApiKeyAuditStore(),
-            hasher ?? new FakeApiKeySecretHasher(),
+            services.GetRequiredService<ApiKeyAdminCommands>(),
+            services.GetRequiredService<IApiKeyAdminStore>(),
+            services.GetRequiredService<ZB.MOM.WW.Audit.IAuditWriter>(),
             new HttpContextAccessor { HttpContext = httpContext });
     }
 
+    private ServiceProvider BuildServices()
+    {
+        TempDatabaseDirectory directory = TempDatabaseDirectory.Create("mxgateway-dashboard-apikey-tests");
+        _tempDirectories.Add(directory);
+
+        IConfigurationRoot configuration = new ConfigurationBuilder()
+            .AddInMemoryCollection(
+                new Dictionary<string, string?>
+                {
+                    ["MxGateway:Authentication:SqlitePath"] = directory.DatabasePath(),
+                    ["MxGateway:ApiKeyPepper"] = "test-pepper"
+                })
+            .Build();
+
+        ServiceCollection services = new();
+        services.AddSingleton<IConfiguration>(configuration);
+        services.AddGatewayConfiguration(configuration);
+        services.AddSqliteAuthStore(configuration);
+
+        ServiceProvider provider = services.BuildServiceProvider(validateScopes: true);
+
+        // Production migrates the schema via the migration hosted service at startup; in these
+        // DI-only tests no host runs, so apply the (idempotent) migration up front.
+        provider.GetRequiredService<ZB.MOM.WW.Auth.ApiKeys.Sqlite.SqliteAuthStoreMigrator>()
+            .MigrateAsync(CancellationToken.None).GetAwaiter().GetResult();
+
+        return provider;
+    }
+
+    private static Task<IReadOnlyList<ApiKeyListItem>> ListAsync(ServiceProvider services)
+    {
+        return services.GetRequiredService<IApiKeyAdminStore>().ListAsync(CancellationToken.None);
+    }
+
+    private static Task<IReadOnlyList<ApiKeyAuditEntry>> ListAuditAsync(ServiceProvider services)
+    {
+        return services.GetRequiredService<IApiKeyAuditStore>().ListRecentAsync(50, CancellationToken.None);
+    }
+
     private static DashboardApiKeyManagementRequest CreateRequest()
     {
         return new DashboardApiKeyManagementRequest(
@@ -266,8 +355,13 @@ public sealed class DashboardApiKeyManagementServiceTests
 
     private static ClaimsPrincipal CreateAuthorizedUser()
     {
+        // Phase 3: include ZbClaimTypes.Username so ResolveOperatorActor picks up the LDAP
+        // login name ("alice") as the audit Actor. The keyId ("operator01") is the Target.
         ClaimsIdentity identity = new(
-            [new Claim(ClaimTypes.Role, DashboardRoles.Admin)],
+            [
+                new Claim(ClaimTypes.Role, DashboardRoles.Admin),
+                new Claim(ZbClaimTypes.Username, "alice"),
+            ],
             DashboardAuthenticationDefaults.AuthenticationScheme,
             ClaimTypes.Name,
             ClaimTypes.Role);
@@ -275,114 +369,28 @@ public sealed class DashboardApiKeyManagementServiceTests
         return new ClaimsPrincipal(identity);
     }
 
-    private sealed class FakeApiKeyAdminStore : IApiKeyAdminStore
+    /// <summary>Clears SQLite pools and deletes every temporary directory created by this test.</summary>
+    public void Dispose()
     {
-        /// <summary>Gets the count of create operations performed.</summary>
-        public int CreateCount { get; private set; }
-
-        /// <summary>Gets the count of revoke operations performed.</summary>
-        public int RevokeCount { get; private set; }
-
-        /// <summary>Gets the count of delete operations performed.</summary>
-        public int DeleteCount { get; private set; }
-
-        /// <summary>Gets or sets the result value returned by revoke operations.</summary>
-        public bool RevokeResult { get; init; }
-
-        /// <summary>Gets or sets the result value returned by rotate operations.</summary>
-        public bool RotateResult { get; init; }
-
-        /// <summary>Gets or sets the result value returned by delete operations.</summary>
-        public bool DeleteResult { get; init; }
-
-        /// <summary>Gets the last key ID revoked.</summary>
-        public string? LastRevokedKeyId { get; private set; }
-
-        /// <summary>Gets the last key ID deleted.</summary>
-        public string? LastDeletedKeyId { get; private set; }
-
-        /// <summary>Gets the last secret hash rotated.</summary>
-        public byte[]? LastRotatedSecretHash { get; private set; }
-
-        /// <summary>Gets the list of create requests received.</summary>
-        public List<ApiKeyCreateRequest> CreatedRequests { get; } = [];
-
-        /// <inheritdoc />
-        public Task CreateAsync(ApiKeyCreateRequest request, CancellationToken cancellationToken)
+        foreach (TempDatabaseDirectory directory in _tempDirectories)
         {
-            CreateCount++;
-            CreatedRequests.Add(request);
-            return Task.CompletedTask;
+            directory.Dispose();
         }
 
-        /// <inheritdoc />
-        public Task<IReadOnlyList<ApiKeyRecord>> ListAsync(CancellationToken cancellationToken)
-        {
-            return Task.FromResult<IReadOnlyList<ApiKeyRecord>>([]);
-        }
-
-        /// <inheritdoc />
-        public Task<bool> RevokeAsync(
-            string keyId,
-            DateTimeOffset revokedUtc,
-            CancellationToken cancellationToken)
-        {
-            RevokeCount++;
-            LastRevokedKeyId = keyId;
-            return Task.FromResult(RevokeResult);
-        }
-
-        /// <inheritdoc />
-        public Task<bool> RotateAsync(
-            string keyId,
-            byte[] secretHash,
-            DateTimeOffset rotatedUtc,
-            CancellationToken cancellationToken)
-        {
-            LastRotatedSecretHash = secretHash;
-            return Task.FromResult(RotateResult);
-        }
-
-        /// <inheritdoc />
-        public Task<bool> DeleteAsync(string keyId, CancellationToken cancellationToken)
-        {
-            DeleteCount++;
-            LastDeletedKeyId = keyId;
-            return Task.FromResult(DeleteResult);
-        }
+        _tempDirectories.Clear();
     }
 
-    private sealed class FakeApiKeyAuditStore : IApiKeyAuditStore
+    /// <summary>In-memory <see cref="ZB.MOM.WW.Audit.IAuditWriter"/> that records every event.</summary>
+    private sealed class RecordingAuditWriter : ZB.MOM.WW.Audit.IAuditWriter
     {
-        /// <summary>Gets the list of audit entries appended.</summary>
-        public List<ApiKeyAuditEntry> Entries { get; } = [];
+        /// <summary>Gets the recorded canonical audit events.</summary>
+        public List<ZB.MOM.WW.Audit.AuditEvent> Events { get; } = [];
 
         /// <inheritdoc />
-        public Task AppendAsync(ApiKeyAuditEntry entry, CancellationToken cancellationToken)
+        public Task WriteAsync(ZB.MOM.WW.Audit.AuditEvent auditEvent, CancellationToken cancellationToken = default)
         {
-            Entries.Add(entry);
+            Events.Add(auditEvent);
             return Task.CompletedTask;
         }
-
-        /// <inheritdoc />
-        public Task<IReadOnlyList<ApiKeyAuditRecord>> ListRecentAsync(
-            int count,
-            CancellationToken cancellationToken)
-        {
-            return Task.FromResult<IReadOnlyList<ApiKeyAuditRecord>>([]);
-        }
-    }
-
-    private sealed class FakeApiKeySecretHasher : IApiKeySecretHasher
-    {
-        /// <summary>Gets the last secret hashed.</summary>
-        public string? LastSecret { get; private set; }
-
-        /// <inheritdoc />
-        public byte[] HashSecret(string secret)
-        {
-            LastSecret = secret;
-            return System.Text.Encoding.UTF8.GetBytes($"hash:{secret}");
-        }
     }
 }

src/ZB.MOM.WW.MxGateway.Tests/Gateway/Dashboard/DashboardAuthenticatorTests.cs

@@ -1,90 +1,75 @@
+using System.Security.Claims;
 using Microsoft.Extensions.Logging.Abstractions;
 using Microsoft.Extensions.Options;
+using ZB.MOM.WW.Auth.Abstractions.Ldap;
+using ZB.MOM.WW.Auth.Abstractions.Roles;
+using ZB.MOM.WW.Auth.AspNetCore;
 using ZB.MOM.WW.MxGateway.Server.Configuration;
 using ZB.MOM.WW.MxGateway.Server.Dashboard;
 
 namespace ZB.MOM.WW.MxGateway.Tests.Gateway.Dashboard;
 
+/// <summary>
+/// Parity tests for <see cref="DashboardAuthenticator"/> after the cutover to the
+/// shared <see cref="ILdapAuthService"/>. The library now owns connect/bind/search
+/// (covered by its own tests); these tests fake the shared service to return known
+/// groups and assert the dashboard-specific policy is unchanged: groups → roles via
+/// <see cref="IGroupRoleMapper{TRole}"/>, no-roles-matched is denied, and the
+/// resulting principal/claims keep their exact shape.
+/// </summary>
 public sealed class DashboardAuthenticatorTests
 {
-    /// <summary>Verifies that LDAP filter special characters are escaped correctly.</summary>
-    [Fact]
-    public void EscapeLdapFilter_EscapesSpecialCharacters()
-    {
-        string escaped = DashboardAuthenticator.EscapeLdapFilter("a\\b*c(d)e\0f");
-
-        Assert.Equal("a\\5cb\\2ac\\28d\\29e\\00f", escaped);
-    }
-
-    /// <summary>Verifies that group-to-role mapping resolves by short name and distinguished name.</summary>
-    /// <param name="ldapGroup">The LDAP group name or distinguished name.</param>
-    /// <param name="expectedRole">The expected role or null if no match.</param>
+    /// <summary>A blank username is rejected without touching the LDAP provider.</summary>
     [Theory]
-    [InlineData("GwAdmin", DashboardRoles.Admin)]
-    [InlineData("gwadmin", DashboardRoles.Admin)]
-    [InlineData("ou=GwAdmin,ou=groups,dc=lmxopcua,dc=local", DashboardRoles.Admin)]
-    [InlineData("OtherGroup", null)]
-    public void MapGroupsToRoles_ResolvesByShortNameAndDistinguishedName(
-        string ldapGroup,
-        string? expectedRole)
+    [InlineData(null)]
+    [InlineData("")]
+    [InlineData("   ")]
+    public async Task AuthenticateAsync_BlankUsername_FailsWithoutCallingLdap(string? username)
     {
-        Dictionary<string, string> mapping = new(StringComparer.OrdinalIgnoreCase)
-        {
-            ["GwAdmin"] = DashboardRoles.Admin,
-            ["GwReader"] = DashboardRoles.Viewer,
-        };
+        FakeLdapAuthService ldap = new(LdapAuthResult.Fail(LdapAuthFailure.BadCredentials));
+        DashboardAuthenticator authenticator = CreateAuthenticator(ldap, StandardMapping());
 
-        IReadOnlyList<string> roles = DashboardAuthenticator.MapGroupsToRoles([ldapGroup], mapping);
+        DashboardAuthenticationResult result = await authenticator.AuthenticateAsync(
+            username,
+            "password",
+            CancellationToken.None);
 
-        if (expectedRole is null)
-        {
-            Assert.Empty(roles);
-        }
-        else
-        {
-            Assert.Equal(expectedRole, Assert.Single(roles));
-        }
+        Assert.False(result.Succeeded);
+        Assert.Null(result.Principal);
+        Assert.False(ldap.WasCalled);
     }
 
-    /// <summary>Verifies that admin and viewer roles are both emitted when groups are present.</summary>
+    /// <summary>A blank password is rejected without touching the LDAP provider.</summary>
     [Fact]
-    public void MapGroupsToRoles_AdminPlusViewer_BothRolesEmitted()
+    public async Task AuthenticateAsync_BlankPassword_FailsWithoutCallingLdap()
     {
-        Dictionary<string, string> mapping = new(StringComparer.OrdinalIgnoreCase)
-        {
-            ["GwAdmin"] = DashboardRoles.Admin,
-            ["GwReader"] = DashboardRoles.Viewer,
-        };
+        FakeLdapAuthService ldap = new(LdapAuthResult.Fail(LdapAuthFailure.BadCredentials));
+        DashboardAuthenticator authenticator = CreateAuthenticator(ldap, StandardMapping());
 
-        IReadOnlyList<string> roles = DashboardAuthenticator.MapGroupsToRoles(
-            ["GwAdmin", "GwReader"],
-            mapping);
+        DashboardAuthenticationResult result = await authenticator.AuthenticateAsync(
+            "admin",
+            "  ",
+            CancellationToken.None);
 
-        Assert.Contains(DashboardRoles.Admin, roles);
-        Assert.Contains(DashboardRoles.Viewer, roles);
+        Assert.False(result.Succeeded);
+        Assert.Null(result.Principal);
+        Assert.False(ldap.WasCalled);
     }
 
-    /// <summary>Verifies that extraction returns the leading RDN value from a distinguished name.</summary>
-    [Fact]
-    public void ExtractFirstRdnValue_ReturnsLeadingRdnValue()
+    /// <summary>
+    /// A failed LDAP outcome (any failure bucket, including <see cref="LdapAuthFailure.Disabled"/>)
+    /// maps to the generic dashboard failure without leaking the raw password.
+    /// </summary>
+    [Theory]
+    [InlineData(LdapAuthFailure.Disabled)]
+    [InlineData(LdapAuthFailure.BadCredentials)]
+    [InlineData(LdapAuthFailure.UserNotFound)]
+    [InlineData(LdapAuthFailure.ServiceAccountBindFailed)]
+    public async Task AuthenticateAsync_LdapFailure_ReturnsFailureWithoutRawCredentials(
+        LdapAuthFailure failure)
     {
-        string result = DashboardAuthenticator.ExtractFirstRdnValue(
-            "CN=Gateway Admins,OU=Groups,DC=example,DC=com");
-
-        Assert.Equal("Gateway Admins", result);
-    }
-
-    /// <summary>Verifies that authentication fails when LDAP is disabled without exposing raw credentials.</summary>
-    [Fact]
-    public async Task AuthenticateAsync_LdapDisabled_ReturnsFailureWithoutRawCredentials()
-    {
-        DashboardAuthenticator authenticator = CreateAuthenticator(new GatewayOptions
-        {
-            Ldap = new LdapOptions
-            {
-                Enabled = false,
-            },
-        });
+        FakeLdapAuthService ldap = new(LdapAuthResult.Fail(failure));
+        DashboardAuthenticator authenticator = CreateAuthenticator(ldap, StandardMapping());
 
         DashboardAuthenticationResult result = await authenticator.AuthenticateAsync(
             "admin",
@@ -96,10 +81,230 @@ public sealed class DashboardAuthenticatorTests
         Assert.DoesNotContain("admin123", result.FailureMessage, StringComparison.Ordinal);
     }
 
-    private static DashboardAuthenticator CreateAuthenticator(GatewayOptions options)
+    /// <summary>
+    /// On success the principal carries the resolved roles, the LDAP-group claims
+    /// (short RDN names as returned by <see cref="ILdapAuthService"/>), the display
+    /// name (ClaimTypes.Name), and the username (ClaimTypes.NameIdentifier), under the
+    /// dashboard authentication scheme.
+    /// </summary>
+    [Fact]
+    public async Task AuthenticateAsync_Success_BuildsPrincipalWithExpectedClaims()
     {
+        FakeLdapAuthService ldap = new(LdapAuthResult.Success(
+            username: "admin",
+            displayName: "Administrator",
+            groups: ["GwAdmin", "GwReader"]));
+        DashboardAuthenticator authenticator = CreateAuthenticator(ldap, StandardMapping());
+
+        DashboardAuthenticationResult result = await authenticator.AuthenticateAsync(
+            "admin",
+            "admin123",
+            CancellationToken.None);
+
+        Assert.True(result.Succeeded);
+        ClaimsPrincipal principal = Assert.IsType<ClaimsPrincipal>(result.Principal);
+
+        Assert.Equal("admin", principal.FindFirst(ClaimTypes.NameIdentifier)?.Value);
+        Assert.Equal("Administrator", principal.FindFirst(ClaimTypes.Name)?.Value);
+
+        // Identity is built with the dashboard scheme and Name/Role claim types so
+        // IsInRole and Identity.Name keep working.
+        ClaimsIdentity identity = Assert.IsType<ClaimsIdentity>(principal.Identity);
+        Assert.Equal(DashboardAuthenticationDefaults.AuthenticationScheme, identity.AuthenticationType);
+        Assert.Equal("Administrator", identity.Name);
+
+        // Both groups mapped → both roles present.
+        Assert.True(principal.IsInRole(DashboardRoles.Admin));
+        Assert.True(principal.IsInRole(DashboardRoles.Viewer));
+
+        // LDAP groups (already short RDN names from the service) are surfaced under
+        // the dedicated group claim type.
+        IReadOnlyList<string> groupClaims = principal.FindAll(
+                DashboardAuthenticationDefaults.LdapGroupClaimType)
+            .Select(claim => claim.Value)
+            .ToList();
+        Assert.Equal(["GwAdmin", "GwReader"], groupClaims);
+    }
+
+    /// <summary>
+    /// Task 1.5: the principal emits canonical ZbClaimTypes.Username ("zb:username") with
+    /// the login username, ZbClaimTypes.Role (= ClaimTypes.Role) for each resolved role, and
+    /// ZbClaimTypes.DisplayName ("zb:displayname") with the display name — while keeping
+    /// ClaimTypes.NameIdentifier, ClaimTypes.Name, and mxgateway:ldap_group claims intact.
+    /// </summary>
+    [Fact]
+    public async Task AuthenticateAsync_Success_EmitsCanonicalZbClaims()
+    {
+        FakeLdapAuthService ldap = new(LdapAuthResult.Success(
+            username: "jsmith",
+            displayName: "John Smith",
+            groups: ["GwAdmin", "GwReader"]));
+        DashboardAuthenticator authenticator = CreateAuthenticator(ldap, StandardMapping());
+
+        DashboardAuthenticationResult result = await authenticator.AuthenticateAsync(
+            "jsmith",
+            "pw",
+            CancellationToken.None);
+
+        Assert.True(result.Succeeded);
+        ClaimsPrincipal principal = Assert.IsType<ClaimsPrincipal>(result.Principal);
+
+        // ZbClaimTypes.Username ("zb:username") carries the login username.
+        Assert.Equal("jsmith", principal.FindFirstValue(ZbClaimTypes.Username));
+
+        // ZbClaimTypes.DisplayName ("zb:displayname") carries the display name.
+        Assert.Equal("John Smith", principal.FindFirstValue(ZbClaimTypes.DisplayName));
+
+        // ZbClaimTypes.Role (= ClaimTypes.Role) is used for each role claim.
+        IReadOnlyList<string> roleClaims = principal
+            .FindAll(ZbClaimTypes.Role)
+            .Select(c => c.Value)
+            .OrderBy(r => r)
+            .ToList();
+        Assert.Contains(DashboardRoles.Admin, roleClaims);
+        Assert.Contains(DashboardRoles.Viewer, roleClaims);
+
+        // IsInRole still works (identity built with roleType = ZbClaimTypes.Role).
+        Assert.True(principal.IsInRole(DashboardRoles.Admin));
+        Assert.True(principal.IsInRole(DashboardRoles.Viewer));
+
+        // ClaimTypes.Name still resolves as Identity.Name (nameType = ZbClaimTypes.Name = ClaimTypes.Name).
+        Assert.Equal("John Smith", principal.Identity?.Name);
+
+        // mxgateway:ldap_group claims are preserved.
+        IReadOnlyList<string> groups = principal
+            .FindAll(DashboardAuthenticationDefaults.LdapGroupClaimType)
+            .Select(c => c.Value)
+            .ToList();
+        Assert.Equal(["GwAdmin", "GwReader"], groups);
+    }
+
+    /// <summary>
+    /// When the user authenticates but none of their groups map to a dashboard role,
+    /// the login is denied (the long-standing "no roles matched → denied" rule).
+    /// </summary>
+    [Fact]
+    public async Task AuthenticateAsync_NoRolesMatched_DeniesLogin()
+    {
+        FakeLdapAuthService ldap = new(LdapAuthResult.Success(
+            username: "nobody",
+            displayName: "No Body",
+            groups: ["SomeUnmappedGroup"]));
+        DashboardAuthenticator authenticator = CreateAuthenticator(ldap, StandardMapping());
+
+        DashboardAuthenticationResult result = await authenticator.AuthenticateAsync(
+            "nobody",
+            "pw",
+            CancellationToken.None);
+
+        Assert.False(result.Succeeded);
+        Assert.Null(result.Principal);
+    }
+
+    /// <summary>
+    /// Direct-injection path only (review C1): when an <see cref="ILdapAuthService"/>
+    /// implementation hands the authenticator a full distinguished name as a group, the
+    /// mapper's leading-RDN fallback still resolves the role, and whatever string the
+    /// service supplied is surfaced verbatim on the group claim.
+    /// <para>
+    /// This is NOT the real production flow. The shared <c>ZB.MOM.WW.Auth.Ldap</c>
+    /// provider strips each group DN to its short RDN name before returning it, so the
+    /// authenticator never receives a full DN from the real library and the group claim
+    /// in production carries the short name (e.g. <c>GwAdmin</c>), not the DN. This test
+    /// uses a fake service to exercise only the authenticator's own pass-through of group
+    /// values; see <see cref="AuthenticateAsync_Success_BuildsPrincipalWithExpectedClaims"/>
+    /// for the realistic (already-short) group shape.
+    /// </para>
+    /// </summary>
+    [Fact]
+    public async Task AuthenticateAsync_GroupAsDistinguishedNameFromService_ResolvesRoleAndSurfacesServiceValue()
+    {
+        const string groupDn = "ou=GwAdmin,ou=groups,dc=zb,dc=local";
+        FakeLdapAuthService ldap = new(LdapAuthResult.Success(
+            username: "admin",
+            displayName: "admin",
+            groups: [groupDn]));
+        DashboardAuthenticator authenticator = CreateAuthenticator(ldap, StandardMapping());
+
+        DashboardAuthenticationResult result = await authenticator.AuthenticateAsync(
+            "admin",
+            "admin123",
+            CancellationToken.None);
+
+        Assert.True(result.Succeeded);
+        ClaimsPrincipal principal = Assert.IsType<ClaimsPrincipal>(result.Principal);
+        // Role resolves via the leading-RDN fallback in DashboardGroupRoleMapping.
+        Assert.True(principal.IsInRole(DashboardRoles.Admin));
+        // The authenticator surfaces the value the (fake) service returned, verbatim.
+        // With the real library this value would already be the short RDN ("GwAdmin").
+        Assert.Contains(
+            principal.FindAll(DashboardAuthenticationDefaults.LdapGroupClaimType),
+            claim => claim.Value == groupDn);
+    }
+
+    /// <summary>The (already-trimmed) username from the LDAP result flows onto the principal.</summary>
+    [Fact]
+    public async Task AuthenticateAsync_UsesUsernameFromLdapResult()
+    {
+        FakeLdapAuthService ldap = new(LdapAuthResult.Success(
+            username: "canonical",
+            displayName: "Canonical User",
+            groups: ["GwReader"]));
+        DashboardAuthenticator authenticator = CreateAuthenticator(ldap, StandardMapping());
+
+        DashboardAuthenticationResult result = await authenticator.AuthenticateAsync(
+            "  canonical  ",
+            "pw",
+            CancellationToken.None);
+
+        Assert.True(result.Succeeded);
+        ClaimsPrincipal principal = Assert.IsType<ClaimsPrincipal>(result.Principal);
+        Assert.Equal("canonical", principal.FindFirst(ClaimTypes.NameIdentifier)?.Value);
+        // The authenticator trims before delegating, so the provider sees the canonical value.
+        Assert.Equal("canonical", ldap.LastUsername);
+    }
+
+    private static DashboardAuthenticator CreateAuthenticator(
+        ILdapAuthService ldapAuthService,
+        Dictionary<string, string> groupToRole)
+    {
+        GatewayOptions options = new()
+        {
+            Dashboard = new DashboardOptions
+            {
+                GroupToRole = groupToRole,
+            },
+        };
+
+        IGroupRoleMapper<string> roleMapper = new DashboardGroupRoleMapper(Options.Create(options));
+
         return new DashboardAuthenticator(
-            Options.Create(options),
+            ldapAuthService,
+            roleMapper,
             NullLogger<DashboardAuthenticator>.Instance);
     }
+
+    private static Dictionary<string, string> StandardMapping() => new(StringComparer.OrdinalIgnoreCase)
+    {
+        ["GwAdmin"] = DashboardRoles.Admin,
+        ["GwReader"] = DashboardRoles.Viewer,
+    };
+
+    /// <summary>
+    /// Fake <see cref="ILdapAuthService"/> returning a fixed result, recording whether it was
+    /// invoked and with what username so the authenticator's pre-checks and trimming can be asserted.
+    /// </summary>
+    private sealed class FakeLdapAuthService(LdapAuthResult result) : ILdapAuthService
+    {
+        public bool WasCalled { get; private set; }
+
+        public string? LastUsername { get; private set; }
+
+        public Task<LdapAuthResult> AuthenticateAsync(string username, string password, CancellationToken ct)
+        {
+            WasCalled = true;
+            LastUsername = username;
+            return Task.FromResult(result);
+        }
+    }
 }

src/ZB.MOM.WW.MxGateway.Tests/Gateway/Dashboard/DashboardGroupRoleMapperTests.cs

@@ -0,0 +1,139 @@
+using Microsoft.Extensions.Options;
+using ZB.MOM.WW.Auth.Abstractions.Roles;
+using ZB.MOM.WW.MxGateway.Server.Configuration;
+using ZB.MOM.WW.MxGateway.Server.Dashboard;
+
+namespace ZB.MOM.WW.MxGateway.Tests.Gateway.Dashboard;
+
+/// <summary>
+/// Tests for <see cref="DashboardGroupRoleMapper"/>, the shared-Auth
+/// <see cref="IGroupRoleMapper{TRole}"/> seam over the dashboard's
+/// LDAP-group → role mapping. Behaviour must match the existing
+/// <c>DashboardAuthenticator.MapGroupsToRoles</c> precedence/case rules.
+/// </summary>
+public sealed class DashboardGroupRoleMapperTests
+{
+    private static DashboardGroupRoleMapper CreateMapper(Dictionary<string, string> mapping)
+    {
+        GatewayOptions options = new()
+        {
+            Dashboard = new DashboardOptions
+            {
+                GroupToRole = mapping,
+            },
+        };
+
+        return new DashboardGroupRoleMapper(Options.Create(options));
+    }
+
+    private static Dictionary<string, string> StandardMapping() => new(StringComparer.OrdinalIgnoreCase)
+    {
+        ["GwAdmin"] = DashboardRoles.Admin,
+        ["GwReader"] = DashboardRoles.Viewer,
+    };
+
+    /// <summary>Verifies full-DN match, leading-RDN fallback, case-insensitivity, and unmapped → empty.</summary>
+    /// <param name="ldapGroup">The LDAP group name or distinguished name.</param>
+    /// <param name="expectedRole">The expected role or null if no match.</param>
+    [Theory]
+    [InlineData("GwAdmin", DashboardRoles.Admin)]
+    [InlineData("gwadmin", DashboardRoles.Admin)]
+    [InlineData("ou=GwAdmin,ou=groups,dc=zb,dc=local", DashboardRoles.Admin)]
+    [InlineData("OtherGroup", null)]
+    public async Task MapAsync_ResolvesByShortNameAndDistinguishedName(
+        string ldapGroup,
+        string? expectedRole)
+    {
+        DashboardGroupRoleMapper mapper = CreateMapper(StandardMapping());
+
+        GroupRoleMapping<string> result = await mapper.MapAsync([ldapGroup], CancellationToken.None);
+
+        if (expectedRole is null)
+        {
+            Assert.Empty(result.Roles);
+        }
+        else
+        {
+            Assert.Equal(expectedRole, Assert.Single(result.Roles));
+        }
+
+        Assert.Null(result.Scope);
+    }
+
+    /// <summary>Verifies that admin and viewer roles are both emitted when both groups are present.</summary>
+    [Fact]
+    public async Task MapAsync_AdminPlusViewer_BothRolesEmitted()
+    {
+        DashboardGroupRoleMapper mapper = CreateMapper(StandardMapping());
+
+        GroupRoleMapping<string> result = await mapper.MapAsync(
+            ["GwAdmin", "GwReader"],
+            CancellationToken.None);
+
+        Assert.Contains(DashboardRoles.Admin, result.Roles);
+        Assert.Contains(DashboardRoles.Viewer, result.Roles);
+    }
+
+    /// <summary>Verifies that an empty GroupToRole map yields no roles.</summary>
+    [Fact]
+    public async Task MapAsync_EmptyMapping_ReturnsNoRoles()
+    {
+        DashboardGroupRoleMapper mapper = CreateMapper(new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase));
+
+        GroupRoleMapping<string> result = await mapper.MapAsync(["GwAdmin"], CancellationToken.None);
+
+        Assert.Empty(result.Roles);
+    }
+
+    /// <summary>
+    /// Task 1.7 (canonical roles): an LDAP user in the admin group must resolve
+    /// to the canonical role value <c>"Administrator"</c> (not the legacy
+    /// <c>"Admin"</c>), and the reader group to <c>"Viewer"</c>. Asserted with
+    /// string LITERALS — independent of <see cref="DashboardRoles"/> — so a
+    /// regression on the constant's value is caught here.
+    /// </summary>
+    [Fact]
+    public async Task MapAsync_AdminGroup_ResolvesToCanonicalAdministratorValue()
+    {
+        DashboardGroupRoleMapper mapper = CreateMapper(StandardMapping());
+
+        GroupRoleMapping<string> adminResult = await mapper.MapAsync(["GwAdmin"], CancellationToken.None);
+        GroupRoleMapping<string> readerResult = await mapper.MapAsync(["GwReader"], CancellationToken.None);
+
+        Assert.Equal("Administrator", Assert.Single(adminResult.Roles));
+        Assert.Equal("Viewer", Assert.Single(readerResult.Roles));
+    }
+
+    /// <summary>
+    /// Task 1.7: the canonical admin value (<c>"Administrator"</c>) passes the
+    /// admin-only gate while a <c>"Viewer"</c> fails it — asserted with literals,
+    /// proving enforcement is bound to the new value and the legacy <c>"Admin"</c>
+    /// string is no longer what authorizes admin actions.
+    /// </summary>
+    [Fact]
+    public void AdminOnly_AuthorizesCanonicalAdministratorButNotViewer()
+    {
+        IReadOnlyList<string> adminGate = DashboardAuthorizationRequirement.AdminOnly.RequiredRoles;
+
+        Assert.Contains("Administrator", adminGate);
+        Assert.DoesNotContain("Admin", adminGate);
+        Assert.DoesNotContain("Viewer", adminGate);
+    }
+
+    /// <summary>
+    /// Verifies the extracted shared helper is the single source of truth: it
+    /// produces the same roles the mapper does for the same inputs.
+    /// </summary>
+    [Fact]
+    public async Task SharedHelper_MatchesMapperOutput()
+    {
+        Dictionary<string, string> mapping = StandardMapping();
+        DashboardGroupRoleMapper mapper = CreateMapper(mapping);
+        string[] groups = ["ou=GwAdmin,ou=groups,dc=zb,dc=local", "gwreader"];
+
+        IReadOnlyList<string> helperRoles = DashboardGroupRoleMapping.MapGroupsToRoles(groups, mapping);
+        GroupRoleMapping<string> mapperResult = await mapper.MapAsync(groups, CancellationToken.None);
+
+        Assert.Equal([.. helperRoles.OrderBy(r => r)], [.. mapperResult.Roles.OrderBy(r => r)]);
+    }
+}

src/ZB.MOM.WW.MxGateway.Tests/Gateway/Dashboard/DashboardSnapshotServiceTests.cs

@@ -1,5 +1,6 @@
 using System.Globalization;
 using Microsoft.Extensions.Options;
+using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
 using ZB.MOM.WW.MxGateway.Contracts.Proto;
 using ZB.MOM.WW.MxGateway.Server.Configuration;
 using ZB.MOM.WW.MxGateway.Server.Dashboard;
@@ -273,16 +274,15 @@ public sealed class DashboardSnapshotServiceTests
     {
         using GatewayMetrics metrics = new();
         CountingApiKeyAdminStore apiKeyAdminStore = new(
-            new ApiKeyRecord(
+            new ApiKeyListItem(
                 KeyId: "operator01",
-                KeyPrefix: "mxgw_operator01",
-                SecretHash: [1, 2, 3],
+                KeyPrefix: "mxgw",
                 DisplayName: "Operator",
                 Scopes: new HashSet<string>([GatewayScopes.MetadataRead], StringComparer.Ordinal),
-                Constraints: ApiKeyConstraints.Empty with
+                ConstraintsJson: ApiKeyConstraintSerializer.Serialize(ApiKeyConstraints.Empty with
                 {
                     BrowseSubtrees = ["Area1/*"],
-                },
+                }),
                 CreatedUtc: DateTimeOffset.Parse("2026-04-28T12:00:00Z", CultureInfo.InvariantCulture),
                 LastUsedUtc: null,
                 RevokedUtc: null));
@@ -310,13 +310,12 @@ public sealed class DashboardSnapshotServiceTests
     {
         using GatewayMetrics metrics = new();
         SequencedApiKeyAdminStore apiKeyAdminStore = new(
-            new ApiKeyRecord(
+            new ApiKeyListItem(
                 KeyId: "operator01",
-                KeyPrefix: "mxgw_operator01",
-                SecretHash: [1, 2, 3],
+                KeyPrefix: "mxgw",
                 DisplayName: "Operator",
                 Scopes: new HashSet<string>([GatewayScopes.MetadataRead], StringComparer.Ordinal),
-                Constraints: ApiKeyConstraints.Empty,
+                ConstraintsJson: null,
                 CreatedUtc: DateTimeOffset.Parse("2026-04-28T12:00:00Z", CultureInfo.InvariantCulture),
                 LastUsedUtc: null,
                 RevokedUtc: null));
@@ -425,63 +424,56 @@ public sealed class DashboardSnapshotServiceTests
     private class FakeApiKeyAdminStore : IApiKeyAdminStore
     {
         /// <inheritdoc />
-        public Task CreateAsync(ApiKeyCreateRequest request, CancellationToken cancellationToken)
+        public Task CreateAsync(ApiKeyRecord record, CancellationToken ct)
         {
             return Task.CompletedTask;
         }
 
         /// <inheritdoc />
-        public virtual Task<IReadOnlyList<ApiKeyRecord>> ListAsync(CancellationToken cancellationToken)
+        public virtual Task<IReadOnlyList<ApiKeyListItem>> ListAsync(CancellationToken ct)
         {
-            return Task.FromResult<IReadOnlyList<ApiKeyRecord>>([]);
+            return Task.FromResult<IReadOnlyList<ApiKeyListItem>>([]);
         }
 
         /// <inheritdoc />
-        public Task<bool> RevokeAsync(
-            string keyId,
-            DateTimeOffset revokedUtc,
-            CancellationToken cancellationToken)
+        public Task<bool> RevokeAsync(string keyId, DateTimeOffset whenUtc, CancellationToken ct)
         {
             return Task.FromResult(false);
         }
 
         /// <inheritdoc />
-        public Task<bool> RotateAsync(
-            string keyId,
-            byte[] secretHash,
-            DateTimeOffset rotatedUtc,
-            CancellationToken cancellationToken)
+        public Task<bool> RotateAsync(string keyId, byte[] newSecretHash, CancellationToken ct)
         {
             return Task.FromResult(false);
         }
 
         /// <inheritdoc />
-        public Task<bool> DeleteAsync(string keyId, CancellationToken cancellationToken)
+        public Task<bool> DeleteAsync(string keyId, CancellationToken ct)
         {
             return Task.FromResult(false);
         }
     }
 
-    private class CountingApiKeyAdminStore(params ApiKeyRecord[] records) : FakeApiKeyAdminStore
+    private class CountingApiKeyAdminStore(params ApiKeyListItem[] records) : FakeApiKeyAdminStore
     {
         /// <summary>Gets the count of list operations performed.</summary>
         public int ListCount { get; protected set; }
 
         /// <inheritdoc />
-        public override Task<IReadOnlyList<ApiKeyRecord>> ListAsync(CancellationToken cancellationToken)
+        public override Task<IReadOnlyList<ApiKeyListItem>> ListAsync(CancellationToken ct)
         {
             ListCount++;
-            return Task.FromResult<IReadOnlyList<ApiKeyRecord>>(records);
+            return Task.FromResult<IReadOnlyList<ApiKeyListItem>>(records);
         }
     }
 
-    private sealed class SequencedApiKeyAdminStore(ApiKeyRecord record) : CountingApiKeyAdminStore(record)
+    private sealed class SequencedApiKeyAdminStore(ApiKeyListItem record) : CountingApiKeyAdminStore(record)
     {
         /// <summary>Gets or sets a value indicating whether the next list operation should fail.</summary>
         public bool FailNext { get; set; }
 
         /// <inheritdoc />
-        public override Task<IReadOnlyList<ApiKeyRecord>> ListAsync(CancellationToken cancellationToken)
+        public override Task<IReadOnlyList<ApiKeyListItem>> ListAsync(CancellationToken ct)
         {
             if (FailNext)
             {
@@ -490,7 +482,7 @@ public sealed class DashboardSnapshotServiceTests
                 throw new InvalidOperationException("Simulated SQLite failure.");
             }
 
-            return base.ListAsync(cancellationToken);
+            return base.ListAsync(ct);
         }
     }
 

src/ZB.MOM.WW.MxGateway.Tests/Gateway/GatewayApplicationTests.cs

@@ -197,11 +197,11 @@ public sealed class GatewayApplicationTests
     [InlineData(
         "MxGateway:Dashboard:GroupToRole:GwAdmin",
         "BogusRole",
-        "MxGateway:Dashboard:GroupToRole['GwAdmin'] must be 'Admin' or 'Viewer'.")]
+        "MxGateway:Dashboard:GroupToRole['GwAdmin'] must be 'Administrator' or 'Viewer'.")]
     [InlineData(
-        "MxGateway:Ldap:AllowInsecureLdap",
+        "MxGateway:Ldap:AllowInsecure",
         "false",
-        "MxGateway:Ldap:AllowInsecureLdap must be true when UseTls is false.")]
+        "MxGateway:Ldap:AllowInsecure must be true when Transport is None (plaintext).")]
     public async Task StartAsync_InvalidGatewayConfiguration_FailsStartup(
         string key,
         string value,

src/ZB.MOM.WW.MxGateway.Tests/Security/Audit/CanonicalAuditStoreAndAdapterTests.cs

@@ -0,0 +1,287 @@
+using Microsoft.Extensions.Logging.Abstractions;
+using ZB.MOM.WW.Audit;
+using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
+using ZB.MOM.WW.Auth.ApiKeys.Sqlite;
+using ZB.MOM.WW.MxGateway.Server.Security.Audit;
+using ZB.MOM.WW.MxGateway.Tests.Security.Authentication;
+
+namespace ZB.MOM.WW.MxGateway.Tests.Security.Audit;
+
+/// <summary>
+/// Tests the Task 2.3 canonical audit plumbing: the gateway-owned
+/// <see cref="SqliteCanonicalAuditStore"/> (round-trips canonical
+/// <see cref="AuditEvent"/>s through the new <c>audit_event</c> table), the best-effort
+/// <see cref="CanonicalAuditWriter"/>, and the <see cref="CanonicalForwardingApiKeyAuditStore"/>
+/// adapter that maps the library's <see cref="ApiKeyAuditEntry"/> onto the canonical model
+/// and back (so the dashboard recent-audit view keeps working). All against a real
+/// temporary SQLite database, sharing the library's connection factory.
+/// </summary>
+public sealed class CanonicalAuditStoreAndAdapterTests : IDisposable
+{
+    private readonly List<TempDatabaseDirectory> _tempDirectories = [];
+
+    /// <summary>A canonical event with all fields populated round-trips through the store.</summary>
+    [Fact]
+    public async Task Store_InsertThenListRecent_RoundTripsAllFields()
+    {
+        SqliteCanonicalAuditStore store = CreateStore();
+
+        Guid eventId = Guid.NewGuid();
+        Guid correlationId = Guid.NewGuid();
+        DateTimeOffset occurred = new(2026, 6, 1, 12, 34, 56, TimeSpan.Zero);
+        AuditEvent original = new()
+        {
+            EventId = eventId,
+            OccurredAtUtc = occurred,
+            Actor = "operator01",
+            Action = "dashboard-create-key",
+            Outcome = AuditOutcome.Success,
+            Category = "ApiKey",
+            Target = "operator01",
+            SourceNode = "127.0.0.1",
+            CorrelationId = correlationId,
+            DetailsJson = "{\"detail\":\"created\"}",
+        };
+
+        await store.InsertAsync(original, CancellationToken.None);
+
+        IReadOnlyList<AuditEvent> recent = await store.ListRecentAsync(10, CancellationToken.None);
+
+        AuditEvent persisted = Assert.Single(recent);
+        Assert.Equal(eventId, persisted.EventId);
+        Assert.Equal(occurred, persisted.OccurredAtUtc);
+        Assert.Equal("operator01", persisted.Actor);
+        Assert.Equal("dashboard-create-key", persisted.Action);
+        Assert.Equal(AuditOutcome.Success, persisted.Outcome);
+        Assert.Equal("ApiKey", persisted.Category);
+        Assert.Equal("operator01", persisted.Target);
+        Assert.Equal("127.0.0.1", persisted.SourceNode);
+        Assert.Equal(correlationId, persisted.CorrelationId);
+        Assert.Equal("{\"detail\":\"created\"}", persisted.DetailsJson);
+    }
+
+    /// <summary>Nullable canonical fields round-trip as null, not empty string.</summary>
+    [Fact]
+    public async Task Store_InsertWithNullOptionalFields_RoundTripsAsNull()
+    {
+        SqliteCanonicalAuditStore store = CreateStore();
+
+        AuditEvent original = new()
+        {
+            EventId = Guid.NewGuid(),
+            OccurredAtUtc = DateTimeOffset.UtcNow,
+            Actor = "system",
+            Action = "init-db",
+            Outcome = AuditOutcome.Success,
+        };
+
+        await store.InsertAsync(original, CancellationToken.None);
+
+        AuditEvent persisted = Assert.Single(await store.ListRecentAsync(10, CancellationToken.None));
+        Assert.Null(persisted.Category);
+        Assert.Null(persisted.Target);
+        Assert.Null(persisted.SourceNode);
+        Assert.Null(persisted.CorrelationId);
+        Assert.Null(persisted.DetailsJson);
+    }
+
+    /// <summary>ListRecent returns newest-first.</summary>
+    [Fact]
+    public async Task Store_ListRecent_ReturnsNewestFirst()
+    {
+        SqliteCanonicalAuditStore store = CreateStore();
+
+        await store.InsertAsync(MakeEvent("first"), CancellationToken.None);
+        await store.InsertAsync(MakeEvent("second"), CancellationToken.None);
+        await store.InsertAsync(MakeEvent("third"), CancellationToken.None);
+
+        IReadOnlyList<AuditEvent> recent = await store.ListRecentAsync(10, CancellationToken.None);
+        Assert.Equal(["third", "second", "first"], recent.Select(e => e.Action));
+    }
+
+    /// <summary>The writer is best-effort: a faulting store does not surface to the caller.</summary>
+    [Fact]
+    public async Task Writer_WhenStoreFails_DoesNotThrow()
+    {
+        // Point the connection factory at a path that cannot be created (a file used as a
+        // directory) so OpenConnectionAsync/insert fails; the writer must swallow it.
+        TempDatabaseDirectory directory = TempDatabaseDirectory.Create("mxgateway-canonical-audit-fail");
+        _tempDirectories.Add(directory);
+        string filePath = directory.DatabasePath("blocker");
+        File.WriteAllText(filePath, "not a directory");
+        // Nested path under a regular file → directory creation / open fails.
+        AuthSqliteConnectionFactory factory = new(Path.Combine(filePath, "audit.db"));
+        CanonicalAuditWriter writer = new(
+            new SqliteCanonicalAuditStore(factory),
+            NullLogger<CanonicalAuditWriter>.Instance);
+
+        // Must not throw.
+        await writer.WriteAsync(MakeEvent("anything"), CancellationToken.None);
+    }
+
+    /// <summary>
+    /// A library event with a KeyId maps to a canonical Success event under category ApiKey,
+    /// and the adapter maps it back to the original entry for the dashboard view.
+    /// </summary>
+    [Fact]
+    public async Task Adapter_KeyedEvent_RoundTripsThroughCanonicalStore()
+    {
+        (CanonicalForwardingApiKeyAuditStore adapter, SqliteCanonicalAuditStore store) = CreateAdapter();
+        DateTimeOffset created = new(2026, 6, 1, 9, 0, 0, TimeSpan.Zero);
+
+        await adapter.AppendAsync(
+            new ApiKeyAuditEntry(
+                KeyId: "operator01",
+                EventType: "create-key",
+                RemoteAddress: "10.0.0.5",
+                CreatedUtc: created,
+                Details: "created"),
+            CancellationToken.None);
+
+        // Canonical persisted form.
+        AuditEvent canonical = Assert.Single(await store.ListRecentAsync(10, CancellationToken.None));
+        Assert.Equal("operator01", canonical.Actor);
+        Assert.Equal("create-key", canonical.Action);
+        Assert.Equal(AuditOutcome.Success, canonical.Outcome);
+        Assert.Equal(CanonicalForwardingApiKeyAuditStore.ApiKeyCategory, canonical.Category);
+        Assert.Equal("operator01", canonical.Target);
+        Assert.Equal("10.0.0.5", canonical.SourceNode);
+        Assert.Equal("{\"detail\":\"created\"}", canonical.DetailsJson);
+
+        // Dashboard-facing form via the adapter's ListRecentAsync.
+        ApiKeyAuditEntry mappedBack = Assert.Single(await adapter.ListRecentAsync(10, CancellationToken.None));
+        Assert.Equal("operator01", mappedBack.KeyId);
+        Assert.Equal("create-key", mappedBack.EventType);
+        Assert.Equal("10.0.0.5", mappedBack.RemoteAddress);
+        Assert.Equal(created, mappedBack.CreatedUtc);
+        Assert.Equal("created", mappedBack.Details);
+    }
+
+    /// <summary>The keyless library <c>init-db</c> event maps to Actor "system" and back to a null KeyId.</summary>
+    [Fact]
+    public async Task Adapter_InitDbKeylessEvent_MapsToSystemActor()
+    {
+        (CanonicalForwardingApiKeyAuditStore adapter, SqliteCanonicalAuditStore store) = CreateAdapter();
+
+        await adapter.AppendAsync(
+            new ApiKeyAuditEntry(
+                KeyId: null,
+                EventType: "init-db",
+                RemoteAddress: null,
+                CreatedUtc: DateTimeOffset.UtcNow,
+                Details: null),
+            CancellationToken.None);
+
+        AuditEvent canonical = Assert.Single(await store.ListRecentAsync(10, CancellationToken.None));
+        Assert.Equal("system", canonical.Actor);
+        Assert.Equal(AuditOutcome.Success, canonical.Outcome);
+        Assert.Null(canonical.DetailsJson);
+
+        ApiKeyAuditEntry mappedBack = Assert.Single(await adapter.ListRecentAsync(10, CancellationToken.None));
+        Assert.Null(mappedBack.KeyId);
+        Assert.Equal("init-db", mappedBack.EventType);
+        Assert.Null(mappedBack.Details);
+    }
+
+    /// <summary>Any other keyless library event maps to Actor "cli" and back to a null KeyId.</summary>
+    [Fact]
+    public async Task Adapter_OtherKeylessEvent_MapsToCliActor()
+    {
+        (CanonicalForwardingApiKeyAuditStore adapter, SqliteCanonicalAuditStore store) = CreateAdapter();
+
+        await adapter.AppendAsync(
+            new ApiKeyAuditEntry(
+                KeyId: null,
+                EventType: "list-keys",
+                RemoteAddress: null,
+                CreatedUtc: DateTimeOffset.UtcNow,
+                Details: null),
+            CancellationToken.None);
+
+        AuditEvent canonical = Assert.Single(await store.ListRecentAsync(10, CancellationToken.None));
+        Assert.Equal("cli", canonical.Actor);
+
+        ApiKeyAuditEntry mappedBack = Assert.Single(await adapter.ListRecentAsync(10, CancellationToken.None));
+        Assert.Null(mappedBack.KeyId);
+        Assert.Equal("list-keys", mappedBack.EventType);
+    }
+
+    /// <summary>A <c>constraint-denied</c> library event maps to Outcome.Denied.</summary>
+    [Fact]
+    public async Task Adapter_ConstraintDeniedEvent_MapsToDeniedOutcome()
+    {
+        (CanonicalForwardingApiKeyAuditStore adapter, SqliteCanonicalAuditStore store) = CreateAdapter();
+
+        await adapter.AppendAsync(
+            new ApiKeyAuditEntry(
+                KeyId: "operator01",
+                EventType: "constraint-denied",
+                RemoteAddress: null,
+                CreatedUtc: DateTimeOffset.UtcNow,
+                Details: "Write: 42: write_scope: outside scope"),
+            CancellationToken.None);
+
+        AuditEvent canonical = Assert.Single(await store.ListRecentAsync(10, CancellationToken.None));
+        Assert.Equal(AuditOutcome.Denied, canonical.Outcome);
+        Assert.Equal("operator01", canonical.Actor);
+
+        ApiKeyAuditEntry mappedBack = Assert.Single(await adapter.ListRecentAsync(10, CancellationToken.None));
+        Assert.Equal("constraint-denied", mappedBack.EventType);
+        Assert.Equal("Write: 42: write_scope: outside scope", mappedBack.Details);
+    }
+
+    /// <summary>
+    /// The adapter does NOT throw when the underlying write fails (it forwards through the
+    /// best-effort writer), preserving the IApiKeyAuditStore caller's flow.
+    /// </summary>
+    [Fact]
+    public async Task Adapter_WhenWriterFails_DoesNotThrow()
+    {
+        string badPath = Path.Combine(Path.GetTempPath(), "mxgateway-canonical-audit-fail", Guid.NewGuid().ToString("N"), "blocker");
+        Directory.CreateDirectory(Path.GetDirectoryName(badPath)!);
+        File.WriteAllText(badPath, "not a directory");
+        AuthSqliteConnectionFactory factory = new(Path.Combine(badPath, "audit.db"));
+        SqliteCanonicalAuditStore store = new(factory);
+        CanonicalAuditWriter writer = new(store, NullLogger<CanonicalAuditWriter>.Instance);
+        CanonicalForwardingApiKeyAuditStore adapter = new(writer, store);
+
+        await adapter.AppendAsync(
+            new ApiKeyAuditEntry("k", "create-key", null, DateTimeOffset.UtcNow, null),
+            CancellationToken.None);
+    }
+
+    private SqliteCanonicalAuditStore CreateStore()
+    {
+        TempDatabaseDirectory directory = TempDatabaseDirectory.Create("mxgateway-canonical-audit");
+        _tempDirectories.Add(directory);
+        return new SqliteCanonicalAuditStore(new AuthSqliteConnectionFactory(directory.DatabasePath()));
+    }
+
+    private (CanonicalForwardingApiKeyAuditStore Adapter, SqliteCanonicalAuditStore Store) CreateAdapter()
+    {
+        SqliteCanonicalAuditStore store = CreateStore();
+        CanonicalAuditWriter writer = new(store, NullLogger<CanonicalAuditWriter>.Instance);
+        return (new CanonicalForwardingApiKeyAuditStore(writer, store), store);
+    }
+
+    private static AuditEvent MakeEvent(string action) => new()
+    {
+        EventId = Guid.NewGuid(),
+        OccurredAtUtc = DateTimeOffset.UtcNow,
+        Actor = "operator01",
+        Action = action,
+        Outcome = AuditOutcome.Success,
+        Category = "ApiKey",
+    };
+
+    /// <summary>Clears SQLite pools and deletes every temporary directory created by this test.</summary>
+    public void Dispose()
+    {
+        foreach (TempDatabaseDirectory directory in _tempDirectories)
+        {
+            directory.Dispose();
+        }
+
+        _tempDirectories.Clear();
+    }
+}

src/ZB.MOM.WW.MxGateway.Tests/Security/Audit/HttpAuditActorAccessorTests.cs

@@ -0,0 +1,107 @@
+using System.Security.Claims;
+using Microsoft.AspNetCore.Http;
+using ZB.MOM.WW.Auth.AspNetCore;
+using ZB.MOM.WW.MxGateway.Server.Dashboard;
+using ZB.MOM.WW.MxGateway.Server.Security.Audit;
+
+namespace ZB.MOM.WW.MxGateway.Tests.Security.Audit;
+
+/// <summary>
+/// Tests <see cref="HttpAuditActorAccessor"/> — the HTTP-backed <see cref="IAuditActorAccessor"/>
+/// that reads the dashboard operator's username from the current HTTP context.
+/// </summary>
+public sealed class HttpAuditActorAccessorTests
+{
+    /// <summary>
+    /// When the HTTP context carries an authenticated principal with <see cref="ZbClaimTypes.Username"/>,
+    /// <see cref="IAuditActorAccessor.CurrentActor"/> returns that username.
+    /// </summary>
+    [Fact]
+    public void CurrentActor_AuthenticatedUserWithUsernamelaim_ReturnsUsername()
+    {
+        HttpAuditActorAccessor accessor = CreateAccessor(
+            CreateAuthenticatedUser(username: "alice", displayName: "Alice Admin"));
+
+        Assert.Equal("alice", accessor.CurrentActor);
+    }
+
+    /// <summary>
+    /// When the principal has no <see cref="ZbClaimTypes.Username"/> but has a
+    /// <see cref="ClaimTypes.Name"/> claim (display name), the accessor falls back to
+    /// <see cref="System.Security.Principal.IIdentity.Name"/>.
+    /// </summary>
+    [Fact]
+    public void CurrentActor_AuthenticatedUserWithoutUsernameClaim_FallsBackToIdentityName()
+    {
+        // Build a principal with display-name but no zb:username.
+        ClaimsIdentity identity = new(
+            [new Claim(ClaimTypes.Name, "Alice Admin")],
+            DashboardAuthenticationDefaults.AuthenticationScheme,
+            ClaimTypes.Name,
+            ClaimTypes.Role);
+        HttpAuditActorAccessor accessor = CreateAccessor(new ClaimsPrincipal(identity));
+
+        Assert.Equal("Alice Admin", accessor.CurrentActor);
+    }
+
+    /// <summary>
+    /// An unauthenticated (anonymous) principal yields <see langword="null"/>.
+    /// </summary>
+    [Fact]
+    public void CurrentActor_UnauthenticatedUser_ReturnsNull()
+    {
+        HttpAuditActorAccessor accessor = CreateAccessor(new ClaimsPrincipal(new ClaimsIdentity()));
+
+        Assert.Null(accessor.CurrentActor);
+    }
+
+    /// <summary>
+    /// When there is no HTTP context at all (e.g. a background thread), the accessor returns
+    /// <see langword="null"/> rather than throwing.
+    /// </summary>
+    [Fact]
+    public void CurrentActor_NoHttpContext_ReturnsNull()
+    {
+        HttpContextAccessor contextAccessor = new() { HttpContext = null };
+        HttpAuditActorAccessor accessor = new(contextAccessor);
+
+        Assert.Null(accessor.CurrentActor);
+    }
+
+    /// <summary>
+    /// When the <see cref="ZbClaimTypes.Username"/> claim is present it is always preferred
+    /// over the <see cref="ClaimTypes.Name"/> (display-name) value.
+    /// </summary>
+    [Fact]
+    public void CurrentActor_UsernameClaimPreferredOverDisplayName()
+    {
+        // login username = "jsmith"; display name = "John Smith"
+        HttpAuditActorAccessor accessor = CreateAccessor(
+            CreateAuthenticatedUser(username: "jsmith", displayName: "John Smith"));
+
+        Assert.Equal("jsmith", accessor.CurrentActor);
+    }
+
+    // ── helpers ─────────────────────────────────────────────────────────────
+
+    private static HttpAuditActorAccessor CreateAccessor(ClaimsPrincipal user)
+    {
+        DefaultHttpContext httpContext = new() { User = user };
+        return new HttpAuditActorAccessor(new HttpContextAccessor { HttpContext = httpContext });
+    }
+
+    private static ClaimsPrincipal CreateAuthenticatedUser(string username, string displayName)
+    {
+        ClaimsIdentity identity = new(
+            [
+                new Claim(ZbClaimTypes.Username, username),
+                new Claim(ZbClaimTypes.Name, displayName),
+                new Claim(ClaimTypes.Role, DashboardRoles.Admin),
+            ],
+            DashboardAuthenticationDefaults.AuthenticationScheme,
+            ZbClaimTypes.Name,
+            ZbClaimTypes.Role);
+
+        return new ClaimsPrincipal(identity);
+    }
+}

src/ZB.MOM.WW.MxGateway.Tests/Security/Authentication/ApiKeyAdminCliRunnerTests.cs

@@ -1,9 +1,13 @@
 using System.Text.Json;
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
+using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
 using ZB.MOM.WW.MxGateway.Server.Configuration;
 using ZB.MOM.WW.MxGateway.Server.Security.Authentication;
 
+// The mapped identity is the gateway's constraint-bearing type; disambiguate from the library's.
+using ApiKeyIdentity = ZB.MOM.WW.MxGateway.Server.Security.Authentication.ApiKeyIdentity;
+
 namespace ZB.MOM.WW.MxGateway.Tests.Security.Authentication;
 
 public sealed class ApiKeyAdminCliRunnerTests : IDisposable
@@ -33,14 +37,14 @@ public sealed class ApiKeyAdminCliRunnerTests : IDisposable
         string apiKey = ReadApiKey(output.ToString());
 
         IApiKeyVerifier verifier = services.GetRequiredService<IApiKeyVerifier>();
-        ApiKeyVerificationResult verification = await verifier.VerifyAsync($"Bearer {apiKey}", CancellationToken.None);
+        ApiKeyVerification verification = await verifier.VerifyAsync($"Bearer {apiKey}", CancellationToken.None);
 
         Assert.True(verification.Succeeded);
         Assert.NotNull(verification.Identity);
         Assert.Equal("operator01", verification.Identity.KeyId);
         Assert.Contains("session:open", verification.Identity.Scopes);
 
-        IReadOnlyList<ApiKeyAuditRecord> auditRecords = await services
+        IReadOnlyList<ApiKeyAuditEntry> auditRecords = await services
             .GetRequiredService<IApiKeyAuditStore>()
             .ListRecentAsync(10, CancellationToken.None);
 
@@ -98,14 +102,14 @@ public sealed class ApiKeyAdminCliRunnerTests : IDisposable
             TextWriter.Null,
             CancellationToken.None);
 
-        ApiKeyVerificationResult verification = await services
+        ApiKeyVerification verification = await services
             .GetRequiredService<IApiKeyVerifier>()
             .VerifyAsync($"Bearer {apiKey}", CancellationToken.None);
 
         Assert.False(verification.Succeeded);
-        Assert.Equal(ApiKeyVerificationFailure.KeyRevoked, verification.Failure);
+        Assert.Equal(ApiKeyFailure.KeyRevoked, verification.Failure);
 
-        IReadOnlyList<ApiKeyAuditRecord> auditRecords = await services
+        IReadOnlyList<ApiKeyAuditEntry> auditRecords = await services
             .GetRequiredService<IApiKeyAuditStore>()
             .ListRecentAsync(10, CancellationToken.None);
 
@@ -141,11 +145,11 @@ public sealed class ApiKeyAdminCliRunnerTests : IDisposable
         Assert.Equal(1, CountOccurrences(rotateJson, newApiKey));
 
         IApiKeyVerifier verifier = services.GetRequiredService<IApiKeyVerifier>();
-        ApiKeyVerificationResult oldVerification = await verifier.VerifyAsync($"Bearer {oldApiKey}", CancellationToken.None);
-        ApiKeyVerificationResult newVerification = await verifier.VerifyAsync($"Bearer {newApiKey}", CancellationToken.None);
+        ApiKeyVerification oldVerification = await verifier.VerifyAsync($"Bearer {oldApiKey}", CancellationToken.None);
+        ApiKeyVerification newVerification = await verifier.VerifyAsync($"Bearer {newApiKey}", CancellationToken.None);
 
         Assert.False(oldVerification.Succeeded);
-        Assert.Equal(ApiKeyVerificationFailure.SecretMismatch, oldVerification.Failure);
+        Assert.Equal(ApiKeyFailure.SecretMismatch, oldVerification.Failure);
         Assert.True(newVerification.Succeeded);
     }
 
@@ -203,13 +207,16 @@ public sealed class ApiKeyAdminCliRunnerTests : IDisposable
             CancellationToken.None);
 
         string apiKey = ReadApiKey(output.ToString());
-        ApiKeyVerificationResult verification = await services
+        ApiKeyVerification verification = await services
             .GetRequiredService<IApiKeyVerifier>()
             .VerifyAsync($"Bearer {apiKey}", CancellationToken.None);
 
         Assert.True(verification.Succeeded);
-        Assert.Equal(["Area1/*"], verification.Identity!.EffectiveConstraints.BrowseSubtrees);
-        Assert.True(verification.Identity.EffectiveConstraints.ReadAlarmOnly);
+        // The shared verifier returns the opaque constraints JSON; map it to the gateway identity so
+        // the strongly-typed effective constraints round-trip can be asserted.
+        ApiKeyIdentity gatewayIdentity = GatewayApiKeyIdentityMapper.ToGatewayIdentity(verification.Identity!);
+        Assert.Equal(["Area1/*"], gatewayIdentity.EffectiveConstraints.BrowseSubtrees);
+        Assert.True(gatewayIdentity.EffectiveConstraints.ReadAlarmOnly);
     }
 
 
@@ -246,7 +253,7 @@ public sealed class ApiKeyAdminCliRunnerTests : IDisposable
         ServiceCollection services = new();
         services.AddSingleton<IConfiguration>(configuration);
         services.AddGatewayConfiguration(configuration);
-        services.AddSqliteAuthStore();
+        services.AddSqliteAuthStore(configuration);
 
         return services.BuildServiceProvider(validateScopes: true);
     }

src/ZB.MOM.WW.MxGateway.Tests/Security/Authentication/ApiKeyParserTests.cs

@@ -1,41 +0,0 @@
-using ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-namespace ZB.MOM.WW.MxGateway.Tests.Security.Authentication;
-
-public sealed class ApiKeyParserTests
-{
-    /// <summary>Verifies that TryParseAuthorizationHeader parses a valid Bearer token and returns the key ID and secret.</summary>
-    [Fact]
-    public void TryParseAuthorizationHeader_ValidBearerToken_ReturnsKeyIdAndSecret()
-    {
-        ApiKeyParser parser = new();
-
-        bool parsed = parser.TryParseAuthorizationHeader(
-            "Bearer mxgw_operator01_secret_value",
-            out ParsedApiKey? apiKey);
-
-        Assert.True(parsed);
-        Assert.NotNull(apiKey);
-        Assert.Equal("operator01", apiKey.KeyId);
-        Assert.Equal("secret_value", apiKey.Secret);
-    }
-
-    /// <summary>Verifies that TryParseAuthorizationHeader returns false for malformed tokens.</summary>
-    /// <param name="authorizationHeader">Malformed authorization header value.</param>
-    [Theory]
-    [InlineData(null)]
-    [InlineData("")]
-    [InlineData("mxgw_operator01_secret")]
-    [InlineData("Bearer not-a-gateway-key")]
-    [InlineData("Bearer mxgw__secret")]
-    [InlineData("Bearer mxgw_operator01_")]
-    public void TryParseAuthorizationHeader_MalformedToken_ReturnsFalse(string? authorizationHeader)
-    {
-        ApiKeyParser parser = new();
-
-        bool parsed = parser.TryParseAuthorizationHeader(authorizationHeader, out ParsedApiKey? apiKey);
-
-        Assert.False(parsed);
-        Assert.Null(apiKey);
-    }
-}

src/ZB.MOM.WW.MxGateway.Tests/Security/Authentication/ApiKeySecretHasherTests.cs

@@ -1,71 +0,0 @@
-using Microsoft.Extensions.Configuration;
-using Microsoft.Extensions.Options;
-using ZB.MOM.WW.MxGateway.Server.Configuration;
-using ZB.MOM.WW.MxGateway.Server.Security.Authentication;
-
-namespace ZB.MOM.WW.MxGateway.Tests.Security.Authentication;
-
-public sealed class ApiKeySecretHasherTests
-{
-    /// <summary>
-    /// Verifies identical pepper and secret produce identical hashes.
-    /// </summary>
-    [Fact]
-    public void HashSecret_SamePepperAndSecret_ReturnsSameHash()
-    {
-        ApiKeySecretHasher hasher = CreateHasher("pepper-one");
-
-        byte[] firstHash = hasher.HashSecret("raw-secret");
-        byte[] secondHash = hasher.HashSecret("raw-secret");
-
-        Assert.Equal(firstHash, secondHash);
-        Assert.NotEqual("raw-secret"u8.ToArray(), firstHash);
-    }
-
-    /// <summary>
-    /// Verifies different pepper values produce different hashes.
-    /// </summary>
-    [Fact]
-    public void HashSecret_DifferentPepper_ReturnsDifferentHash()
-    {
-        byte[] firstHash = CreateHasher("pepper-one").HashSecret("raw-secret");
-        byte[] secondHash = CreateHasher("pepper-two").HashSecret("raw-secret");
-
-        Assert.NotEqual(firstHash, secondHash);
-    }
-
-    /// <summary>
-    /// Verifies missing pepper throws an exception.
-    /// </summary>
-    [Fact]
-    public void HashSecret_MissingPepper_Throws()
-    {
-        ApiKeySecretHasher hasher = CreateHasher(pepper: null);
-
-        Assert.Throws<ApiKeyPepperUnavailableException>(() => hasher.HashSecret("raw-secret"));
-    }
-
-    private static ApiKeySecretHasher CreateHasher(string? pepper)
-    {
-        Dictionary<string, string?> values = [];
-
-        if (pepper is not null)
-        {
-            values["TestPepper"] = pepper;
-        }
-
-        IConfigurationRoot configuration = new ConfigurationBuilder()
-            .AddInMemoryCollection(values)
-            .Build();
-
-        GatewayOptions options = new()
-        {
-            Authentication = new AuthenticationOptions
-            {
-                PepperSecretName = "TestPepper"
-            }
-        };
-
-        return new ApiKeySecretHasher(configuration, Options.Create(options));
-    }
-}

src/ZB.MOM.WW.MxGateway.Tests/Security/Authentication/ApiKeyVerifierTests.cs

@@ -1,22 +1,30 @@
+using System.Security.Cryptography;
+using System.Text;
 using System.Text.Json;
-using Microsoft.Extensions.Configuration;
-using Microsoft.Extensions.Options;
-using ZB.MOM.WW.MxGateway.Server.Configuration;
-using ZB.MOM.WW.MxGateway.Server.Security.Authentication;
+using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
+using ZB.MOM.WW.Auth.ApiKeys;
 
 namespace ZB.MOM.WW.MxGateway.Tests.Security.Authentication;
 
+/// <summary>
+/// Parity tests for the shared <c>ZB.MOM.WW.Auth.ApiKeys</c> verifier as the gateway relies on it:
+/// the <c>mxgw</c> token format, peppered HMAC-SHA256 secret hashing, constant-time comparison,
+/// fail-closed discrimination (missing/unknown/revoked/wrong-secret/missing-pepper), and that the
+/// raw secret never leaks into the result. The expected hash is computed here independently to keep
+/// the test honest against the library's internal hasher.
+/// </summary>
 public sealed class ApiKeyVerifierTests
 {
+    private static readonly ApiKeyOptions Options = new() { TokenPrefix = "mxgw" };
+
     /// <summary>Verifies that VerifyAsync returns identity and scopes for a valid key.</summary>
     [Fact]
     public async Task VerifyAsync_ValidKey_ReturnsIdentityAndScopes()
     {
-        ApiKeySecretHasher hasher = CreateHasher("pepper");
-        FakeApiKeyStore store = new(CreateRecord(hasher, revokedUtc: null));
-        ApiKeyVerifier verifier = new(new ApiKeyParser(), hasher, store);
+        FakeApiKeyStore store = new(CreateRecord("pepper", revokedUtc: null));
+        ApiKeyVerifier verifier = new(Options, store, new FakePepperProvider("pepper"));
 
-        ApiKeyVerificationResult result = await verifier.VerifyAsync(
+        ApiKeyVerification result = await verifier.VerifyAsync(
             "Bearer mxgw_operator01_correct-secret",
             CancellationToken.None);
 
@@ -33,11 +41,10 @@ public sealed class ApiKeyVerifierTests
     [Fact]
     public async Task VerifyAsync_ValidKey_DoesNotExposeRawSecretInResult()
     {
-        ApiKeySecretHasher hasher = CreateHasher("pepper");
-        FakeApiKeyStore store = new(CreateRecord(hasher, revokedUtc: null));
-        ApiKeyVerifier verifier = new(new ApiKeyParser(), hasher, store);
+        FakeApiKeyStore store = new(CreateRecord("pepper", revokedUtc: null));
+        ApiKeyVerifier verifier = new(Options, store, new FakePepperProvider("pepper"));
 
-        ApiKeyVerificationResult result = await verifier.VerifyAsync(
+        ApiKeyVerification result = await verifier.VerifyAsync(
             "Bearer mxgw_operator01_correct-secret",
             CancellationToken.None);
 
@@ -46,58 +53,51 @@ public sealed class ApiKeyVerifierTests
         Assert.DoesNotContain("correct-secret", serialized, StringComparison.Ordinal);
     }
 
-    /// <summary>Verifies that VerifyAsync fails with unauthenticated status for a malformed key.</summary>
+    /// <summary>Verifies that VerifyAsync fails as missing/malformed for a malformed key.</summary>
     /// <param name="authorizationHeader">Authorization header value to test.</param>
     [Theory]
-    [InlineData(null)]
+    [InlineData("")]
     [InlineData("Bearer mxgw_operator01")]
     [InlineData("Bearer wrong")]
-    public async Task VerifyAsync_MalformedKey_FailsUnauthenticated(string? authorizationHeader)
+    public async Task VerifyAsync_MalformedKey_FailsMissingOrMalformed(string authorizationHeader)
     {
-        ApiKeyVerifier verifier = new(
-            new ApiKeyParser(),
-            CreateHasher("pepper"),
-            new FakeApiKeyStore(storedKey: null));
+        ApiKeyVerifier verifier = new(Options, new FakeApiKeyStore(storedKey: null), new FakePepperProvider("pepper"));
 
-        ApiKeyVerificationResult result = await verifier.VerifyAsync(
+        ApiKeyVerification result = await verifier.VerifyAsync(
             authorizationHeader,
             CancellationToken.None);
 
         Assert.False(result.Succeeded);
-        Assert.Equal(ApiKeyVerificationFailure.MissingOrMalformedCredentials, result.Failure);
+        Assert.Equal(ApiKeyFailure.MissingOrMalformed, result.Failure);
     }
 
     /// <summary>Verifies that VerifyAsync fails for an unknown key.</summary>
     [Fact]
     public async Task VerifyAsync_UnknownKey_Fails()
     {
-        ApiKeyVerifier verifier = new(
-            new ApiKeyParser(),
-            CreateHasher("pepper"),
-            new FakeApiKeyStore(storedKey: null));
+        ApiKeyVerifier verifier = new(Options, new FakeApiKeyStore(storedKey: null), new FakePepperProvider("pepper"));
 
-        ApiKeyVerificationResult result = await verifier.VerifyAsync(
+        ApiKeyVerification result = await verifier.VerifyAsync(
             "Bearer mxgw_missing_secret",
             CancellationToken.None);
 
         Assert.False(result.Succeeded);
-        Assert.Equal(ApiKeyVerificationFailure.KeyNotFound, result.Failure);
+        Assert.Equal(ApiKeyFailure.KeyNotFound, result.Failure);
     }
 
-    /// <summary>Verifies that VerifyAsync fails for a wrong secret.</summary>
+    /// <summary>Verifies that VerifyAsync fails for a wrong secret (constant-time compare rejects it).</summary>
     [Fact]
     public async Task VerifyAsync_WrongSecret_Fails()
     {
-        ApiKeySecretHasher hasher = CreateHasher("pepper");
-        FakeApiKeyStore store = new(CreateRecord(hasher, revokedUtc: null));
-        ApiKeyVerifier verifier = new(new ApiKeyParser(), hasher, store);
+        FakeApiKeyStore store = new(CreateRecord("pepper", revokedUtc: null));
+        ApiKeyVerifier verifier = new(Options, store, new FakePepperProvider("pepper"));
 
-        ApiKeyVerificationResult result = await verifier.VerifyAsync(
+        ApiKeyVerification result = await verifier.VerifyAsync(
             "Bearer mxgw_operator01_wrong-secret",
             CancellationToken.None);
 
         Assert.False(result.Succeeded);
-        Assert.Equal(ApiKeyVerificationFailure.SecretMismatch, result.Failure);
+        Assert.Equal(ApiKeyFailure.SecretMismatch, result.Failure);
         Assert.False(store.MarkedUsed);
     }
 
@@ -105,74 +105,62 @@ public sealed class ApiKeyVerifierTests
     [Fact]
     public async Task VerifyAsync_RevokedKey_Fails()
     {
-        ApiKeySecretHasher hasher = CreateHasher("pepper");
-        FakeApiKeyStore store = new(CreateRecord(hasher, DateTimeOffset.UtcNow));
-        ApiKeyVerifier verifier = new(new ApiKeyParser(), hasher, store);
+        FakeApiKeyStore store = new(CreateRecord("pepper", DateTimeOffset.UtcNow));
+        ApiKeyVerifier verifier = new(Options, store, new FakePepperProvider("pepper"));
 
-        ApiKeyVerificationResult result = await verifier.VerifyAsync(
+        ApiKeyVerification result = await verifier.VerifyAsync(
             "Bearer mxgw_operator01_correct-secret",
             CancellationToken.None);
 
         Assert.False(result.Succeeded);
-        Assert.Equal(ApiKeyVerificationFailure.KeyRevoked, result.Failure);
+        Assert.Equal(ApiKeyFailure.KeyRevoked, result.Failure);
         Assert.False(store.MarkedUsed);
     }
 
-    /// <summary>Verifies that VerifyAsync fails when the pepper is missing.</summary>
+    /// <summary>Verifies that VerifyAsync fails closed when the pepper is missing.</summary>
     [Fact]
     public async Task VerifyAsync_MissingPepper_Fails()
     {
-        FakeApiKeyStore store = new(CreateRecord(CreateHasher("pepper"), revokedUtc: null));
-        ApiKeyVerifier verifier = new(new ApiKeyParser(), CreateHasher(pepper: null), store);
+        FakeApiKeyStore store = new(CreateRecord("pepper", revokedUtc: null));
+        ApiKeyVerifier verifier = new(Options, store, new FakePepperProvider(pepper: null));
 
-        ApiKeyVerificationResult result = await verifier.VerifyAsync(
+        ApiKeyVerification result = await verifier.VerifyAsync(
             "Bearer mxgw_operator01_correct-secret",
             CancellationToken.None);
 
         Assert.False(result.Succeeded);
-        Assert.Equal(ApiKeyVerificationFailure.PepperUnavailable, result.Failure);
+        Assert.Equal(ApiKeyFailure.PepperUnavailable, result.Failure);
     }
 
-    private static ApiKeyRecord CreateRecord(ApiKeySecretHasher hasher, DateTimeOffset? revokedUtc)
+    /// <summary>Computes HMAC-SHA256(pepper, secret) — the documented peppered-hash format.</summary>
+    private static byte[] PepperedHash(string secret, string pepper)
+    {
+        using HMACSHA256 hmac = new(Encoding.UTF8.GetBytes(pepper));
+        return hmac.ComputeHash(Encoding.UTF8.GetBytes(secret));
+    }
+
+    private static ApiKeyRecord CreateRecord(string pepper, DateTimeOffset? revokedUtc)
     {
         return new ApiKeyRecord(
             KeyId: "operator01",
-            KeyPrefix: "mxgw_operator01",
-            SecretHash: hasher.HashSecret("correct-secret"),
+            KeyPrefix: "mxgw",
+            SecretHash: PepperedHash("correct-secret", pepper),
             DisplayName: "Operator Key",
             Scopes: new HashSet<string>(StringComparer.Ordinal)
             {
                 "session:open",
                 "events:read"
             },
-            Constraints: ApiKeyConstraints.Empty,
+            ConstraintsJson: null,
             CreatedUtc: DateTimeOffset.UtcNow,
             LastUsedUtc: null,
             RevokedUtc: revokedUtc);
     }
 
-    private static ApiKeySecretHasher CreateHasher(string? pepper)
+    private sealed class FakePepperProvider(string? pepper) : IApiKeyPepperProvider
     {
-        Dictionary<string, string?> values = [];
-
-        if (pepper is not null)
-        {
-            values["TestPepper"] = pepper;
-        }
-
-        IConfigurationRoot configuration = new ConfigurationBuilder()
-            .AddInMemoryCollection(values)
-            .Build();
-
-        GatewayOptions options = new()
-        {
-            Authentication = new AuthenticationOptions
-            {
-                PepperSecretName = "TestPepper"
-            }
-        };
-
-        return new ApiKeySecretHasher(configuration, Options.Create(options));
+        /// <summary>Returns the configured pepper (or null to simulate an unavailable pepper).</summary>
+        public string? GetPepper() => pepper;
     }
 
     /// <summary>Fake in-memory API key store for testing.</summary>
@@ -181,18 +169,14 @@ public sealed class ApiKeyVerifierTests
         /// <summary>Gets whether the key was marked as used.</summary>
         public bool MarkedUsed { get; private set; }
 
-        /// <summary>Finds an API key record by its ID.</summary>
-        /// <param name="keyId">Identifier of the API key.</param>
-        /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
-        public Task<ApiKeyRecord?> FindByKeyIdAsync(string keyId, CancellationToken cancellationToken)
+        /// <inheritdoc />
+        public Task<ApiKeyRecord?> FindByKeyIdAsync(string keyId, CancellationToken ct)
         {
             return Task.FromResult(storedKey?.KeyId == keyId ? storedKey : null);
         }
 
-        /// <summary>Finds an active (non-revoked) API key record by its ID.</summary>
-        /// <param name="keyId">Identifier of the API key.</param>
-        /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
-        public Task<ApiKeyRecord?> FindActiveByKeyIdAsync(string keyId, CancellationToken cancellationToken)
+        /// <inheritdoc />
+        public Task<ApiKeyRecord?> FindActiveByKeyIdAsync(string keyId, CancellationToken ct)
         {
             return Task.FromResult(
                 storedKey?.KeyId == keyId && storedKey.RevokedUtc is null
@@ -200,11 +184,8 @@ public sealed class ApiKeyVerifierTests
                     : null);
         }
 
-        /// <summary>Marks an API key as used at the specified time.</summary>
-        /// <param name="keyId">Identifier of the API key.</param>
-        /// <param name="usedUtc">Timestamp when the key was used.</param>
-        /// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
-        public Task MarkKeyUsedAsync(string keyId, DateTimeOffset usedUtc, CancellationToken cancellationToken)
+        /// <inheritdoc />
+        public Task MarkUsedAsync(string keyId, DateTimeOffset whenUtc, CancellationToken ct)
         {
             MarkedUsed = storedKey?.KeyId == keyId;
 

src/ZB.MOM.WW.MxGateway.Tests/Security/Authentication/SqliteAuthStoreTests.cs

@@ -2,6 +2,8 @@ using Microsoft.AspNetCore.Builder;
 using Microsoft.Data.Sqlite;
 using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
+using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
+using ZB.MOM.WW.Auth.ApiKeys.Sqlite;
 using ZB.MOM.WW.MxGateway.Server;
 using ZB.MOM.WW.MxGateway.Server.Configuration;
 using ZB.MOM.WW.MxGateway.Server.Security.Authentication;
@@ -9,13 +11,17 @@ using ZB.MOM.WW.MxGateway.Server.Security.Authentication;
 namespace ZB.MOM.WW.MxGateway.Tests.Security.Authentication;
 
 /// <summary>
-/// Tests for <see cref="SqliteAuthStore"/>.
+/// Parity tests for the shared <c>ZB.MOM.WW.Auth.ApiKeys</c> SQLite store as wired by the gateway.
+/// The gateway is the donor this store was extracted from; these tests pin that existing deployed
+/// <c>gateway-auth.db</c> databases (schema version 2, same tables/columns/scopes encoding) remain
+/// readable and that migration is idempotent and refuses a newer on-disk schema.
 /// </summary>
 public sealed class SqliteAuthStoreTests : IDisposable
 {
     private readonly List<TempDatabaseDirectory> _tempDirectories = [];
+
     /// <summary>
-    /// Verifies that MigrateAsync initializes the database schema.
+    /// Verifies that MigrateAsync initializes the database schema at the donor's version (2).
     /// </summary>
     [Fact]
     public async Task MigrateAsync_EmptyDatabase_InitializesCurrentSchema()
@@ -23,7 +29,7 @@ public sealed class SqliteAuthStoreTests : IDisposable
         string databasePath = CreateTempDatabasePath();
         await using ServiceProvider services = BuildAuthServices(databasePath);
 
-        IAuthStoreMigrator migrator = services.GetRequiredService<IAuthStoreMigrator>();
+        SqliteAuthStoreMigrator migrator = services.GetRequiredService<SqliteAuthStoreMigrator>();
 
         await migrator.MigrateAsync(CancellationToken.None);
 
@@ -42,7 +48,7 @@ public sealed class SqliteAuthStoreTests : IDisposable
         await CreateVersionZeroDatabaseAsync(databasePath);
         await using ServiceProvider services = BuildAuthServices(databasePath);
 
-        IAuthStoreMigrator migrator = services.GetRequiredService<IAuthStoreMigrator>();
+        SqliteAuthStoreMigrator migrator = services.GetRequiredService<SqliteAuthStoreMigrator>();
 
         await migrator.MigrateAsync(CancellationToken.None);
         await migrator.MigrateAsync(CancellationToken.None);
@@ -74,14 +80,15 @@ public sealed class SqliteAuthStoreTests : IDisposable
     }
 
     /// <summary>
-    /// Verifies that FindActiveByKeyIdAsync returns an active key.
+    /// Verifies that FindActiveByKeyIdAsync returns an active key, reading a row whose columns match
+    /// the donor schema (peppered secret_hash BLOB, ordinal-sorted scopes JSON).
     /// </summary>
     [Fact]
     public async Task FindActiveByKeyIdAsync_ExistingActiveKey_ReturnsKey()
     {
         string databasePath = CreateTempDatabasePath();
         await using ServiceProvider services = BuildAuthServices(databasePath);
-        await services.GetRequiredService<IAuthStoreMigrator>().MigrateAsync(CancellationToken.None);
+        await services.GetRequiredService<SqliteAuthStoreMigrator>().MigrateAsync(CancellationToken.None);
         await InsertApiKeyAsync(databasePath, revokedUtc: null);
 
         IApiKeyStore store = services.GetRequiredService<IApiKeyStore>();
@@ -104,7 +111,7 @@ public sealed class SqliteAuthStoreTests : IDisposable
     {
         string databasePath = CreateTempDatabasePath();
         await using ServiceProvider services = BuildAuthServices(databasePath);
-        await services.GetRequiredService<IAuthStoreMigrator>().MigrateAsync(CancellationToken.None);
+        await services.GetRequiredService<SqliteAuthStoreMigrator>().MigrateAsync(CancellationToken.None);
         await InsertApiKeyAsync(databasePath, DateTimeOffset.UtcNow);
 
         IApiKeyStore store = services.GetRequiredService<IApiKeyStore>();
@@ -127,7 +134,7 @@ public sealed class SqliteAuthStoreTests : IDisposable
     {
         string databasePath = CreateTempDatabasePath();
         await using ServiceProvider services = BuildAuthServices(databasePath);
-        await services.GetRequiredService<IAuthStoreMigrator>().MigrateAsync(CancellationToken.None);
+        await services.GetRequiredService<SqliteAuthStoreMigrator>().MigrateAsync(CancellationToken.None);
 
         IApiKeyAuditStore auditStore = services.GetRequiredService<IApiKeyAuditStore>();
 
@@ -136,14 +143,15 @@ public sealed class SqliteAuthStoreTests : IDisposable
                 KeyId: "test-key",
                 EventType: "lookup",
                 RemoteAddress: "127.0.0.1",
+                CreatedUtc: DateTimeOffset.UtcNow,
                 Details: "matched active key"),
             CancellationToken.None);
 
-        IReadOnlyList<ApiKeyAuditRecord> records = await auditStore.ListRecentAsync(
+        IReadOnlyList<ApiKeyAuditEntry> records = await auditStore.ListRecentAsync(
             10,
             CancellationToken.None);
 
-        ApiKeyAuditRecord record = Assert.Single(records);
+        ApiKeyAuditEntry record = Assert.Single(records);
         Assert.Equal("test-key", record.KeyId);
         Assert.Equal("lookup", record.EventType);
         Assert.Equal("127.0.0.1", record.RemoteAddress);
@@ -189,7 +197,7 @@ public sealed class SqliteAuthStoreTests : IDisposable
         ServiceCollection services = new();
         services.AddSingleton<IConfiguration>(configuration);
         services.AddGatewayConfiguration(configuration);
-        services.AddSqliteAuthStore();
+        services.AddSqliteAuthStore(configuration);
 
         return services.BuildServiceProvider(validateScopes: true);
     }
@@ -288,7 +296,7 @@ public sealed class SqliteAuthStoreTests : IDisposable
         command.Parameters.AddWithValue("$display_name", "Test Key");
         command.Parameters.AddWithValue(
             "$scopes",
-            ApiKeyScopeSerializer.Serialize(new HashSet<string>(StringComparer.Ordinal) { "session:open", "events:read" }));
+            ScopeSerializer.Serialize(new HashSet<string>(StringComparer.Ordinal) { "session:open", "events:read" }));
         command.Parameters.AddWithValue("$created_utc", DateTimeOffset.UtcNow.ToString("O"));
         command.Parameters.AddWithValue("$revoked_utc", revokedUtc?.ToString("O") ?? (object)DBNull.Value);
 

src/ZB.MOM.WW.MxGateway.Tests/Security/Authorization/ConstraintEnforcerTests.cs

@@ -1,3 +1,4 @@
+using ZB.MOM.WW.Audit;
 using ZB.MOM.WW.MxGateway.Contracts.Proto.Galaxy;
 using ZB.MOM.WW.MxGateway.Contracts.Proto;
 using ZB.MOM.WW.MxGateway.Server.Dashboard;
@@ -6,6 +7,10 @@ using ZB.MOM.WW.MxGateway.Server.Security.Authentication;
 using ZB.MOM.WW.MxGateway.Server.Security.Authorization;
 using ZB.MOM.WW.MxGateway.Server.Sessions;
 
+// ConstraintEnforcer enforces against the gateway's constraint-bearing identity; the shared library
+// also defines an ApiKeyIdentity, so disambiguate to the gateway type.
+using ApiKeyIdentity = ZB.MOM.WW.MxGateway.Server.Security.Authentication.ApiKeyIdentity;
+
 namespace ZB.MOM.WW.MxGateway.Tests.Security.Authorization;
 
 public sealed class ConstraintEnforcerTests
@@ -33,7 +38,7 @@ public sealed class ConstraintEnforcerTests
     [Fact]
     public async Task CheckWriteHandleAsync_WhenClassificationTooHigh_ReturnsFailureAndAudits()
     {
-        ConstraintEnforcer enforcer = CreateEnforcer(out FakeAuditStore auditStore);
+        ConstraintEnforcer enforcer = CreateEnforcer(out FakeAuditWriter auditWriter);
         ApiKeyIdentity identity = CreateIdentity(ApiKeyConstraints.Empty with
         {
             WriteSubtrees = ["Area1/*"],
@@ -66,10 +71,35 @@ public sealed class ConstraintEnforcerTests
 
         await enforcer.RecordDenialAsync(identity, "Write", "42", failure, CancellationToken.None);
 
-        ApiKeyAuditEntry entry = Assert.Single(auditStore.Entries);
-        Assert.Equal("operator01", entry.KeyId);
-        Assert.Equal("constraint-denied", entry.EventType);
-        Assert.Contains("max_write_classification", entry.Details, StringComparison.Ordinal);
+        AuditEvent auditEvent = Assert.Single(auditWriter.Events);
+        Assert.Equal("operator01", auditEvent.Actor);
+        Assert.Equal("constraint-denied", auditEvent.Action);
+        Assert.Equal(AuditOutcome.Denied, auditEvent.Outcome);
+        Assert.Equal("ApiKey", auditEvent.Category);
+        // Target is the structured "<commandKind>:<target>" form.
+        Assert.Equal("Write:42", auditEvent.Target);
+        Assert.NotNull(auditEvent.DetailsJson);
+        Assert.Contains("max_write_classification", auditEvent.DetailsJson, StringComparison.Ordinal);
+        Assert.Null(auditEvent.CorrelationId);
+    }
+
+    /// <summary>A denial with no identity records the canonical "anonymous" actor.</summary>
+    [Fact]
+    public async Task RecordDenialAsync_WithoutIdentity_UsesAnonymousActor()
+    {
+        ConstraintEnforcer enforcer = CreateEnforcer(out FakeAuditWriter auditWriter);
+
+        await enforcer.RecordDenialAsync(
+            identity: null,
+            "Read",
+            "Secret.Tag",
+            new ConstraintFailure("read_scope", "Tag is outside the API key read scope."),
+            CancellationToken.None);
+
+        AuditEvent auditEvent = Assert.Single(auditWriter.Events);
+        Assert.Equal("anonymous", auditEvent.Actor);
+        Assert.Equal(AuditOutcome.Denied, auditEvent.Outcome);
+        Assert.Equal("Read:Secret.Tag", auditEvent.Target);
     }
 
     /// <summary>Verifies that historized-only constraint requires historized attribute.</summary>
@@ -129,10 +159,10 @@ public sealed class ConstraintEnforcerTests
         Assert.Equal("read_historized_only", failure.ConstraintName);
     }
 
-    private static ConstraintEnforcer CreateEnforcer(out FakeAuditStore auditStore)
+    private static ConstraintEnforcer CreateEnforcer(out FakeAuditWriter auditWriter)
     {
-        auditStore = new FakeAuditStore();
-        return new ConstraintEnforcer(new StubGalaxyHierarchyCache(CreateEntry()), auditStore);
+        auditWriter = new FakeAuditWriter();
+        return new ConstraintEnforcer(new StubGalaxyHierarchyCache(CreateEntry()), auditWriter);
     }
 
     private static ApiKeyIdentity CreateIdentity(ApiKeyConstraints constraints)
@@ -237,22 +267,16 @@ public sealed class ConstraintEnforcerTests
         public Task WaitForFirstLoadAsync(CancellationToken cancellationToken) => Task.CompletedTask;
     }
 
-    private sealed class FakeAuditStore : IApiKeyAuditStore
+    private sealed class FakeAuditWriter : IAuditWriter
     {
-        /// <summary>Gets the recorded audit entries.</summary>
-        public List<ApiKeyAuditEntry> Entries { get; } = [];
+        /// <summary>Gets the recorded canonical audit events.</summary>
+        public List<AuditEvent> Events { get; } = [];
 
         /// <inheritdoc />
-        public Task AppendAsync(ApiKeyAuditEntry entry, CancellationToken cancellationToken)
+        public Task WriteAsync(AuditEvent auditEvent, CancellationToken cancellationToken = default)
         {
-            Entries.Add(entry);
+            Events.Add(auditEvent);
             return Task.CompletedTask;
         }
-
-        /// <inheritdoc />
-        public Task<IReadOnlyList<ApiKeyAuditRecord>> ListRecentAsync(int count, CancellationToken cancellationToken)
-        {
-            return Task.FromResult<IReadOnlyList<ApiKeyAuditRecord>>([]);
-        }
     }
 }

src/ZB.MOM.WW.MxGateway.Tests/Security/Authorization/GatewayGrpcAuthorizationInterceptorTests.cs

@@ -2,6 +2,7 @@ using System.Runtime.CompilerServices;
 using Grpc.Core;
 using Microsoft.Extensions.Logging.Abstractions;
 using Microsoft.Extensions.Options;
+using ZB.MOM.WW.Auth.Abstractions.ApiKeys;
 using ZB.MOM.WW.MxGateway.Contracts;
 using ZB.MOM.WW.MxGateway.Contracts.Proto;
 using ZB.MOM.WW.MxGateway.Server.Configuration;
@@ -12,6 +13,11 @@ using ZB.MOM.WW.MxGateway.Server.Security.Authorization;
 using ZB.MOM.WW.MxGateway.Server.Sessions;
 using ZB.MOM.WW.MxGateway.Tests.TestSupport;
 
+// The handler exposes the gateway's constraint-bearing identity; alias the shared library identity
+// (returned by the verifier) so the two can be referenced unambiguously.
+using ApiKeyIdentity = ZB.MOM.WW.MxGateway.Server.Security.Authentication.ApiKeyIdentity;
+using LibApiKeyIdentity = ZB.MOM.WW.Auth.Abstractions.ApiKeys.ApiKeyIdentity;
+
 namespace ZB.MOM.WW.MxGateway.Tests.Security.Authorization;
 
 public sealed class GatewayGrpcAuthorizationInterceptorTests
@@ -21,8 +27,7 @@ public sealed class GatewayGrpcAuthorizationInterceptorTests
     public async Task UnaryServerHandler_MissingApiKey_ReturnsUnauthenticated()
     {
         GatewayGrpcAuthorizationInterceptor interceptor = CreateInterceptor(
-            new FakeApiKeyVerifier(ApiKeyVerificationResult.Fail(
-                ApiKeyVerificationFailure.MissingOrMalformedCredentials)),
+            new FakeApiKeyVerifier(Failure(ApiKeyFailure.MissingOrMalformed)),
             new GatewayRequestIdentityAccessor());
 
         RpcException exception = await Assert.ThrowsAsync<RpcException>(
@@ -40,7 +45,7 @@ public sealed class GatewayGrpcAuthorizationInterceptorTests
     public async Task UnaryServerHandler_InvalidApiKey_DoesNotExposeRawCredentialInStatus()
     {
         GatewayGrpcAuthorizationInterceptor interceptor = CreateInterceptor(
-            new FakeApiKeyVerifier(ApiKeyVerificationResult.Fail(ApiKeyVerificationFailure.SecretMismatch)),
+            new FakeApiKeyVerifier(Failure(ApiKeyFailure.SecretMismatch)),
             new GatewayRequestIdentityAccessor());
 
         RpcException exception = await Assert.ThrowsAsync<RpcException>(
@@ -146,8 +151,7 @@ public sealed class GatewayGrpcAuthorizationInterceptorTests
     public async Task UnaryServerHandler_AuthenticationDisabled_SkipsApiKeyVerification()
     {
         GatewayRequestIdentityAccessor identityAccessor = new();
-        FakeApiKeyVerifier verifier = new(ApiKeyVerificationResult.Fail(
-            ApiKeyVerificationFailure.MissingOrMalformedCredentials));
+        FakeApiKeyVerifier verifier = new(Failure(ApiKeyFailure.MissingOrMalformed));
         GatewayGrpcAuthorizationInterceptor interceptor = CreateInterceptor(
             verifier,
             identityAccessor,
@@ -374,13 +378,21 @@ public sealed class GatewayGrpcAuthorizationInterceptorTests
             }));
     }
 
-    private static ApiKeyVerificationResult SuccessWithScopes(params string[] scopes)
+    private static ApiKeyVerification SuccessWithScopes(params string[] scopes)
     {
-        return ApiKeyVerificationResult.Success(new ApiKeyIdentity(
-            KeyId: "operator01",
-            KeyPrefix: "mxgw_operator01",
-            DisplayName: "Operator Key",
-            Scopes: new HashSet<string>(scopes, StringComparer.Ordinal)));
+        return new ApiKeyVerification(
+            Succeeded: true,
+            Identity: new LibApiKeyIdentity(
+                KeyId: "operator01",
+                DisplayName: "Operator Key",
+                Scopes: new HashSet<string>(scopes, StringComparer.Ordinal),
+                Constraints: null),
+            Failure: null);
+    }
+
+    private static ApiKeyVerification Failure(ApiKeyFailure failure)
+    {
+        return new ApiKeyVerification(Succeeded: false, Identity: null, Failure: failure);
     }
 
     private static TestServerCallContext ContextWithAuthorization(string authorizationHeader)
@@ -495,7 +507,7 @@ public sealed class GatewayGrpcAuthorizationInterceptorTests
         }
     }
 
-    private sealed class FakeApiKeyVerifier(ApiKeyVerificationResult result) : IApiKeyVerifier
+    private sealed class FakeApiKeyVerifier(ApiKeyVerification result) : IApiKeyVerifier
     {
         /// <summary>Gets whether the verifier was called.</summary>
         public bool WasCalled { get; private set; }
@@ -505,11 +517,11 @@ public sealed class GatewayGrpcAuthorizationInterceptorTests
 
         /// <summary>Verifies the authorization header against stored result.</summary>
         /// <param name="authorizationHeader">The authorization header to verify.</param>
-        /// <param name="cancellationToken">Cancellation token.</param>
+        /// <param name="ct">Cancellation token.</param>
         /// <returns>Configured verification result.</returns>
-        public Task<ApiKeyVerificationResult> VerifyAsync(
-            string? authorizationHeader,
-            CancellationToken cancellationToken)
+        public Task<ApiKeyVerification> VerifyAsync(
+            string authorizationHeader,
+            CancellationToken ct)
         {
             WasCalled = true;
             LastAuthorizationHeader = authorizationHeader;