Fix all baseline code-review findings across the six shared libraries

Resolves the 35 findings from the 2026-06-01 baseline (commit 26ba1c7), test-first for every behavioral change. +51 tests (331 -> 382 passing, 0 failed). - Telemetry-001 (HIGH): RedactionEnricher now honours property removal, so a redactor that drops a key actually scrubs the secret from the event. - Auth: LDAP validator ValidateOnStart; API-key verify no longer fails on a best-effort MarkUsed write or a corrupt scopes column (fail-closed); LDAP cert validation hook; KeyPrefix persistence aligned; README algorithm corrected. - Health: Akka checks return Degraded (not throw) when the cluster isn't up yet; GrpcDependencyHealthCheck catch-all; null 'description' rendered; composite endpoint builder; XML docs shipped. - Audit: CompositeAuditWriter no longer re-throws OperationCanceledException; TruncatingAuditRedactor over-redact scrubs Target + safe negative max; options record; XML docs shipped. - Configuration: TryAddEnumerable idempotent registration; consistent port quoting; strict invariant port parsing; XML docs + README packaged. - Theme: mobile toggle is now CSS-only (no Bootstrap JS); token/CSS hygiene; XML docs on the public parameter surface. Shared-contract/spec docs updated where the code was the source of truth (observability service.instance.id, MapZbMetrics, redactor reach). All changes additive/back-compatible at v0.1.0. code-reviews bookkeeping follows separately.
2026-06-01 11:22:14 -04:00
parent 26ba1c7215
commit 544a6ddb77
72 changed files with 1539 additions and 191 deletions
@@ -1,3 +1,5 @@
+using System.Net.Security;
+
 namespace ZB.MOM.WW.Auth.Abstractions.Ldap;

 public enum LdapTransport { Ldaps, StartTls, None }
@@ -16,6 +18,16 @@ public sealed record LdapOptions
    public string DisplayNameAttribute { get; init; } = "cn";
    public string GroupAttribute { get; init; } = "memberOf";
    public int ConnectionTimeoutMs { get; init; } = 10_000;
+
+    /// <summary>
+    /// Optional hook to harden (or, in dev, relax) TLS server-certificate validation for the
+    /// <see cref="LdapTransport.Ldaps"/> / <see cref="LdapTransport.StartTls"/> transports. When
+    /// <see langword="null"/> (the default) the LDAP client validates the server certificate against
+    /// the OS trust store — it does <em>not</em> blind-accept. Supply a callback to pin a CA, validate
+    /// the SAN against <see cref="Server"/>, or otherwise tighten validation. This is a code-only seam
+    /// (not bound from configuration) and takes precedence over <see cref="AllowInsecure"/>.
+    /// </summary>
+    public RemoteCertificateValidationCallback? ServerCertificateValidationCallback { get; init; }
 }

 public enum LdapAuthFailure { BadCredentials, UserNotFound, AmbiguousUser, GroupLookupFailed, ServiceAccountBindFailed, Disabled }
@@ -101,7 +101,10 @@ public sealed class ApiKeyAdminCommands

        var record = new ApiKeyRecord(
            KeyId: keyId,
-            KeyPrefix: $"{_options.TokenPrefix}_{keyId}",
+            // KeyPrefix is the bare token prefix (e.g. "mxgw"), NOT prefix_keyId — the key id is
+            // already its own column. Embedding it here produced a self-referential value that
+            // confused admin tooling and disagreed with the read/test paths (see Auth-005).
+            KeyPrefix: _options.TokenPrefix,
            SecretHash: secretHash,
            DisplayName: displayName,
            Scopes: scopes,
@@ -62,8 +62,24 @@ public sealed class ApiKeyVerifier(
            return Fail(ApiKeyFailure.SecretMismatch);
        }

-        // 6. Record successful use, then return the identity (no secret/hash/pepper included).
-        await store.MarkUsedAsync(record.KeyId, _timeProvider.GetUtcNow(), ct).ConfigureAwait(false);
+        // 6. The authentication decision is already made (line 60). Recording last-used is
+        //    best-effort bookkeeping: a transient storage hiccup (SQLITE_BUSY past the busy-timeout,
+        //    disk full, DB locked by a migration) must NOT turn an otherwise-valid credential into a
+        //    failed auth. Swallow any non-cancellation failure so the only exception path remains
+        //    cancellation, as the class contract promises. Cancellation is honoured (re-thrown).
+        try
+        {
+            await store.MarkUsedAsync(record.KeyId, _timeProvider.GetUtcNow(), ct).ConfigureAwait(false);
+        }
+        catch (OperationCanceledException)
+        {
+            throw;
+        }
+        catch
+        {
+            // Best-effort: the last-used write failed, but the credential is valid. Fail open on the
+            // bookkeeping (not the auth decision) rather than denying a legitimate caller.
+        }

        return new ApiKeyVerification(
            Succeeded: true,
@@ -20,7 +20,12 @@ public static class ScopeSerializer

    /// <summary>Deserializes scopes from a JSON array string.</summary>
    /// <param name="value">The JSON string to deserialize; may be null or empty.</param>
-    /// <returns>An ordinal-compared set of scopes; empty when the input is null/blank.</returns>
+    /// <returns>
+    /// An ordinal-compared set of scopes; empty when the input is null/blank. A malformed or
+    /// non-array column (operator tampering, a partial write, a format change, or a buggy writer)
+    /// fails closed to an EMPTY set rather than throwing, so a single poisoned row degrades to a
+    /// zero-scope identity on the auth path instead of an unhandled <see cref="JsonException"/>.
+    /// </returns>
    public static IReadOnlySet<string> Deserialize(string? value)
    {
        if (string.IsNullOrWhiteSpace(value))
@@ -28,7 +33,18 @@ public static class ScopeSerializer
            return new HashSet<string>(StringComparer.Ordinal);
        }

-        string[]? scopes = JsonSerializer.Deserialize<string[]>(value);
+        string[]? scopes;
+        try
+        {
+            scopes = JsonSerializer.Deserialize<string[]>(value);
+        }
+        catch (JsonException)
+        {
+            // Fail closed: a corrupt scopes column yields no scopes rather than an exception on the
+            // verification hot path. The verifier's "only exception path is cancellation" contract
+            // is preserved, and a key with an unreadable scope set is left with zero authority.
+            return new HashSet<string>(StringComparer.Ordinal);
+        }

        return new HashSet<string>(scopes ?? [], StringComparer.Ordinal);
    }
@@ -37,7 +37,14 @@ public static class ServiceCollectionExtensions
        ArgumentNullException.ThrowIfNull(config);
        ArgumentException.ThrowIfNullOrWhiteSpace(sectionPath);

-        services.Configure<LdapOptions>(config.GetSection(sectionPath));
+        // Bind via the options builder and opt into start-time validation. An IValidateOptions<T>
+        // otherwise only runs when the options are first materialized (IOptions<T>.Value) — which
+        // here is the first login (ILdapAuthService factory below), not boot. ValidateOnStart hooks
+        // the host's start-time options validation so a misconfigured directory (e.g. insecure
+        // transport without AllowInsecure) fails fast at startup rather than on first login.
+        services.AddOptions<LdapOptions>()
+            .Bind(config.GetSection(sectionPath))
+            .ValidateOnStart();

        // Fail fast at startup on a misconfigured directory rather than on first login.
        services.AddSingleton<IValidateOptions<LdapOptions>, LdapOptionsValidator>();
@@ -1,5 +1,6 @@
 namespace ZB.MOM.WW.Auth.Ldap.Internal;

+using System.Net.Security;
 using ZB.MOM.WW.Auth.Abstractions.Ldap;

 /// <summary>
@@ -15,8 +16,29 @@ internal sealed record LdapSearchEntry(
 /// </summary>
 internal interface ILdapConnection : IDisposable
 {
-    /// <summary>Opens (and optionally upgrades to TLS) a connection to the given host.</summary>
-    void Connect(string host, int port, LdapTransport transport, bool allowInsecure, int timeoutMs);
+    /// <summary>
+    /// Opens (and optionally upgrades to TLS) a connection to the given host.
+    /// </summary>
+    /// <param name="host">The LDAP server hostname or IP.</param>
+    /// <param name="port">The LDAP server port.</param>
+    /// <param name="transport">The transport security mode.</param>
+    /// <param name="allowInsecure">
+    /// When <see langword="true"/> AND no <paramref name="serverCertificateValidationCallback"/> is
+    /// supplied, TLS server-certificate validation is bypassed (dev/test only). Ignored when a
+    /// validation callback is supplied (the callback wins) or for plaintext transport.
+    /// </param>
+    /// <param name="timeoutMs">The connection/operation timeout in milliseconds.</param>
+    /// <param name="serverCertificateValidationCallback">
+    /// Optional TLS server-certificate validation callback. When <see langword="null"/>, the OS trust
+    /// store is used (the client does not blind-accept).
+    /// </param>
+    void Connect(
+        string host,
+        int port,
+        LdapTransport transport,
+        bool allowInsecure,
+        int timeoutMs,
+        RemoteCertificateValidationCallback? serverCertificateValidationCallback);

    /// <summary>Binds with the supplied DN and password. Throws <c>LdapException</c> on bad credentials.</summary>
    void Bind(string dn, string password);
@@ -2,19 +2,67 @@ namespace ZB.MOM.WW.Auth.Ldap.Internal;

 using Novell.Directory.Ldap;
 using ZB.MOM.WW.Auth.Abstractions.Ldap;
+// Disambiguate: Novell also declares a RemoteCertificateValidationCallback delegate; the seam and
+// LdapConnectionOptions.ConfigureRemoteCertificateValidationCallback both use the BCL one.
+using RemoteCertificateValidationCallback = System.Net.Security.RemoteCertificateValidationCallback;

 /// <summary>
 /// Production <see cref="ILdapConnection"/> backed by <c>Novell.Directory.Ldap.LdapConnection</c>.
 /// Mirrors the connection/search idioms from ZB.MOM.WW.ScadaBridge.Security.LdapAuthService.
 /// </summary>
+/// <remarks>
+/// TLS server-certificate validation: by default the underlying
+/// <c>Novell.Directory.Ldap.NETStandard</c> client validates the server certificate against the OS
+/// trust store (it does NOT blind-accept). A caller-supplied
+/// <c>RemoteCertificateValidationCallback</c> overrides that default (CA pinning / SAN checks); when
+/// none is supplied and <c>allowInsecure</c> is set, validation is bypassed for dev/test only.
+/// </remarks>
 internal sealed class NovellLdapConnection : ILdapConnection
 {
-    private readonly LdapConnection _conn = new();
+    private readonly LdapConnection _conn;
    private bool _disposed;

-    /// <inheritdoc/>
-    public void Connect(string host, int port, LdapTransport transport, bool allowInsecure, int timeoutMs)
+    /// <summary>
+    /// Builds the connection, wiring a TLS server-certificate validation policy: a supplied
+    /// <paramref name="serverCertificateValidationCallback"/> wins; otherwise <paramref name="allowInsecure"/>
+    /// bypasses validation (dev/test only); otherwise the OS-trust-store default applies.
+    /// </summary>
+    public NovellLdapConnection(
+        bool allowInsecure = false,
+        RemoteCertificateValidationCallback? serverCertificateValidationCallback = null)
    {
+        if (serverCertificateValidationCallback is not null)
+        {
+            var options = new LdapConnectionOptions()
+                .ConfigureRemoteCertificateValidationCallback(serverCertificateValidationCallback);
+            _conn = new LdapConnection(options);
+        }
+        else if (allowInsecure)
+        {
+            // Dev/test only: accept any server certificate. Reachable solely when an operator has set
+            // AllowInsecure (rejected for plaintext-without-AllowInsecure by LdapOptionsValidator).
+            var options = new LdapConnectionOptions()
+                .ConfigureRemoteCertificateValidationCallback((_, _, _, _) => true);
+            _conn = new LdapConnection(options);
+        }
+        else
+        {
+            // Default: validate against the OS trust store (no blind-accept).
+            _conn = new LdapConnection();
+        }
+    }
+
+    /// <inheritdoc/>
+    public void Connect(
+        string host,
+        int port,
+        LdapTransport transport,
+        bool allowInsecure,
+        int timeoutMs,
+        RemoteCertificateValidationCallback? serverCertificateValidationCallback)
+    {
+        // The TLS-validation policy (allowInsecure / callback) is wired at construction time on the
+        // LdapConnectionOptions; the per-call arguments here are accepted for seam symmetry.
        ApplyTimeout(timeoutMs);

        // LDAPS: TLS is negotiated at the TCP-connection level.
@@ -98,8 +146,16 @@ internal sealed class NovellLdapConnection : ILdapConnection
    }
 }

-/// <summary>Factory that produces fresh <see cref="NovellLdapConnection"/> instances.</summary>
-internal sealed class NovellLdapConnectionFactory : ILdapConnectionFactory
+/// <summary>
+/// Factory that produces fresh <see cref="NovellLdapConnection"/> instances, carrying the TLS
+/// server-certificate validation policy (a supplied callback, or an <c>allowInsecure</c> bypass) so
+/// it is wired onto each connection at construction time.
+/// </summary>
+internal sealed class NovellLdapConnectionFactory(
+    bool allowInsecure = false,
+    RemoteCertificateValidationCallback? serverCertificateValidationCallback = null)
+    : ILdapConnectionFactory
 {
-    public ILdapConnection Create() => new NovellLdapConnection();
+    public ILdapConnection Create() =>
+        new NovellLdapConnection(allowInsecure, serverCertificateValidationCallback);
 }
@@ -26,10 +26,14 @@ public sealed class LdapAuthService : ILdapAuthService

    /// <summary>
    /// Production constructor: binds against a live directory via the real
-    /// Novell-backed connection factory.
+    /// Novell-backed connection factory. The TLS server-certificate validation policy
+    /// (<see cref="LdapOptions.ServerCertificateValidationCallback"/> or the
+    /// <see cref="LdapOptions.AllowInsecure"/> bypass) is carried into the factory so each
+    /// connection is built with it.
    /// </summary>
    public LdapAuthService(LdapOptions options)
-        : this(options, new NovellLdapConnectionFactory())
+        : this(options, new NovellLdapConnectionFactory(
+            options.AllowInsecure, options.ServerCertificateValidationCallback))
    {
    }

@@ -92,7 +96,13 @@ public sealed class LdapAuthService : ILdapAuthService
            //       Abstractions change could add DirectoryUnavailable to disambiguate.
            try
            {
-                conn.Connect(_options.Server, _options.Port, _options.Transport, _options.AllowInsecure, _options.ConnectionTimeoutMs);
+                conn.Connect(
+                    _options.Server,
+                    _options.Port,
+                    _options.Transport,
+                    _options.AllowInsecure,
+                    _options.ConnectionTimeoutMs,
+                    _options.ServerCertificateValidationCallback);
            }
            catch (LdapException)
            {