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
@@ -25,6 +25,30 @@ public sealed class RedactionTests
        }
    }

+    private sealed class RemovingRedactor : ILogRedactor
+    {
+        private readonly string _key;
+
+        public RemovingRedactor(string key) => _key = key;
+
+        public void Redact(IDictionary<string, object?> properties) => properties.Remove(_key);
+    }
+
+    private sealed class StructuredFieldRedactor : ILogRedactor
+    {
+        // Attempts to mask a nested field of a destructured ({@Object}) property by mutating the
+        // value the seam exposes. Documents that the seam reaches scalar top-level properties only.
+        public void Redact(IDictionary<string, object?> properties)
+        {
+            if (properties.TryGetValue("command", out var value) && value is StructureValue)
+            {
+                // The seam exposes the raw StructureValue wrapper, not a mutable dictionary of the
+                // object's fields, so a project redactor cannot reach inside to mask a nested field.
+                properties["command"] = Masked;
+            }
+        }
+    }
+
    private static string? ScalarOrNull(LogEvent logEvent, string propertyName) =>
        logEvent.Properties.TryGetValue(propertyName, out var value) && value is ScalarValue scalar
            ? scalar.Value?.ToString()
@@ -68,6 +92,68 @@ public sealed class RedactionTests
        Assert.Equal("mxgw_secret", ScalarOrNull(logEvent, "apiKey"));
    }

+    /// <summary>
+    /// Telemetry-001: a redactor that REMOVES a key (the most natural way to implement "must not
+    /// leave the process") must result in the property being absent from the emitted event, not
+    /// silently retained.
+    /// </summary>
+    [Fact]
+    public void Removing_redactor_scrubs_the_property_from_the_event()
+    {
+        var serviceProvider = new ServiceCollection()
+            .AddSingleton<ILogRedactor>(new RemovingRedactor("apiKey"))
+            .BuildServiceProvider();
+
+        var sink = new InMemorySink();
+        var options = new ZbTelemetryOptions { ServiceName = "mxgateway" };
+
+        var loggerConfig = new LoggerConfiguration();
+        ZbSerilogConfig.Apply(loggerConfig, options, serviceProvider);
+        using Logger logger = loggerConfig.WriteTo.Sink(sink).CreateLogger();
+
+        logger.Information("authenticating {apiKey} for {user}", "mxgw_secret", "alice");
+
+        var logEvent = Assert.Single(sink.LogEvents);
+        Assert.False(
+            logEvent.Properties.ContainsKey("apiKey"),
+            "apiKey must be removed from the event when the redactor removes the key");
+        // A non-sensitive property the redactor left alone must survive.
+        Assert.Equal("alice", ScalarOrNull(logEvent, "user"));
+    }
+
+    /// <summary>
+    /// Telemetry-002/003: the redaction seam reaches scalar top-level properties only. A
+    /// destructured ({@Object}) property is exposed to the redactor as the raw Serilog
+    /// <see cref="StructureValue"/> wrapper, so a project redactor cannot mask a field nested
+    /// inside the object — it can only replace/remove the whole top-level property. This test
+    /// pins that documented limitation (see ILogRedactor XML doc and the shared contract).
+    /// </summary>
+    [Fact]
+    public void Redactor_cannot_reach_a_field_inside_a_destructured_object()
+    {
+        var serviceProvider = new ServiceCollection()
+            .AddSingleton<ILogRedactor>(new StructuredFieldRedactor())
+            .BuildServiceProvider();
+
+        var sink = new InMemorySink();
+        var options = new ZbTelemetryOptions { ServiceName = "mxgateway" };
+
+        var loggerConfig = new LoggerConfiguration();
+        ZbSerilogConfig.Apply(loggerConfig, options, serviceProvider);
+        using Logger logger = loggerConfig.WriteTo.Sink(sink).CreateLogger();
+
+        var command = new { Name = "Write", ApiKey = "mxgw_secret" };
+        logger.Information("dispatching {@command}", command);
+
+        var logEvent = Assert.Single(sink.LogEvents);
+        Assert.True(logEvent.Properties.TryGetValue("command", out var value));
+
+        // The property was destructured into a StructureValue and exposed to the redactor as that
+        // wrapper. The redactor recognized it and replaced the whole top-level property with the
+        // mask — confirming the seam can only act at top-level granularity for structured values.
+        Assert.Equal(Masked, (value as ScalarValue)?.Value?.ToString());
+    }
+
    [Fact]
    public void AddZbSerilog_with_otlp_options_builds_without_error()
    {
@@ -122,6 +208,32 @@ public sealed class RedactionTests
        Assert.Equal("central", attributes["node.role"]);
    }

+    /// <summary>
+    /// Telemetry-005: the Serilog OTLP log-sink attribute map and the OTel SDK metrics/traces
+    /// attribute map must be key-for-key and value-for-value identical, because both now derive from
+    /// the single <see cref="ZbResource.BuildAttributes"/> source of truth. This pins that they
+    /// cannot silently drift apart.
+    /// </summary>
+    [Fact]
+    public void Serilog_and_OTel_resource_attribute_sets_are_identical()
+    {
+        var options = new ZbTelemetryOptions
+        {
+            ServiceName = "mxgateway",
+            ServiceNamespace = "ZB.MOM.WW",
+            ServiceVersion = "9.9.9",
+            SiteId = "site-z",
+            NodeRole = "hub",
+        };
+
+        var serilogAttributes = ZbSerilogConfig.BuildResourceAttributes(options);
+        var canonical = ZbResource.BuildAttributes(options);
+
+        Assert.Equal(
+            canonical.OrderBy(kvp => kvp.Key, StringComparer.Ordinal),
+            serilogAttributes.OrderBy(kvp => kvp.Key, StringComparer.Ordinal));
+    }
+
    [Fact]
    public void BuildResourceAttributes_omits_optional_keys_when_not_set()
    {
@@ -37,6 +37,55 @@ public sealed class AddZbTelemetryTests
        Assert.Equal("configure", ex.ParamName);
    }

+    // Telemetry-006: malformed/missing OtlpEndpoint must fail fast with a clear, named error
+    // instead of a late UriFormatException deep inside exporter construction.
+
+    [Fact]
+    public void AddZbTelemetry_Throws_WhenOtlpExporterHasMalformedEndpoint()
+    {
+        var builder = WebApplication.CreateBuilder();
+        var ex = Assert.Throws<ArgumentException>(() =>
+            builder.AddZbTelemetry(o =>
+            {
+                o.ServiceName = "telemetry-test";
+                o.Exporter = ZbExporter.Otlp;
+                o.OtlpEndpoint = "not a uri";   // missing scheme — not an absolute URI
+            }));
+        Assert.Equal("configure", ex.ParamName);
+        Assert.Contains("OtlpEndpoint", ex.Message);
+    }
+
+    [Fact]
+    public void AddZbTelemetry_Throws_WhenOtlpExporterHasNoEndpoint()
+    {
+        var builder = WebApplication.CreateBuilder();
+        var ex = Assert.Throws<ArgumentException>(() =>
+            builder.AddZbTelemetry(o =>
+            {
+                o.ServiceName = "telemetry-test";
+                o.Exporter = ZbExporter.Otlp;
+                // OtlpEndpoint left null
+            }));
+        Assert.Equal("configure", ex.ParamName);
+        Assert.Contains("OtlpEndpoint", ex.Message);
+    }
+
+    [Fact]
+    public void AddZbTelemetry_DoesNotValidateEndpoint_WhenExporterIsPrometheus()
+    {
+        // A stray (even malformed) endpoint is harmless under the Prometheus exporter and must not
+        // be validated — it is ignored.
+        var builder = WebApplication.CreateBuilder();
+        var ex = Record.Exception(() =>
+            builder.AddZbTelemetry(o =>
+            {
+                o.ServiceName = "telemetry-test";
+                o.Exporter = ZbExporter.Prometheus;
+                o.OtlpEndpoint = "not a uri";
+            }));
+        Assert.Null(ex);
+    }
+
    // Fix #1: Prometheus coexists with OTLP — /metrics must still serve under Otlp exporter

    [Fact]
@@ -48,8 +97,10 @@ public sealed class AddZbTelemetryTests
        {
            o.ServiceName = "telemetry-test";
            o.Exporter = ZbExporter.Otlp;
-            // OtlpEndpoint intentionally left null — exporter will be registered but won't
-            // connect anywhere; we are only verifying Prometheus remains present.
+            // A well-formed endpoint is required under the Otlp exporter (Telemetry-006); the
+            // exporter is registered but won't connect anywhere in the test. We are only verifying
+            // Prometheus remains present.
+            o.OtlpEndpoint = "http://localhost:4317";
            o.Meters = ["Test.OtlpCoexist.Meter"];
        });