fix(gateway): detect Certificate:Thumbprint and cover more KestrelTlsInspector cases

fix(client-java): keep Temurin 21 toolchain, auto-provision instead of bumping to 26
feat(gateway): validate MxGateway:Tls options
2026-06-01 07:22:24 -04:00 · 2026-06-01 07:20:04 -04:00 · 2026-06-01 07:19:22 -04:00 · 2026-06-01 07:18:39 -04:00 · 2026-06-01 07:17:36 -04:00 · 2026-06-01 07:13:45 -04:00
38 changed files with 2705 additions and 301 deletions
@@ -0,0 +1,42 @@
+using System.Net.Http;
+using ZB.MOM.WW.MxGateway.Client;
+
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
+
+public sealed class MxGatewayClientTlsHandlerTests
+{
+    /// <summary>
+    /// Verifies that when TLS is used with no pinned CA and RequireCertificateValidation is false (default),
+    /// the handler installs an accept-all callback so the gateway's self-signed cert is trusted.
+    /// </summary>
+    [Fact]
+    public void Handler_SkipsVerification_WhenTlsAndNoCaPinned()
+    {
+        MxGatewayClientOptions options = new()
+        {
+            Endpoint = new Uri("https://localhost:5120"),
+            ApiKey = "k",
+            UseTls = true,
+        };
+        using SocketsHttpHandler handler = MxGatewayClient.CreateHttpHandlerForTests(options);
+        Assert.NotNull(handler.SslOptions.RemoteCertificateValidationCallback);
+    }
+
+    /// <summary>
+    /// Verifies that when RequireCertificateValidation is true, the callback is left null
+    /// so the OS trust store performs validation.
+    /// </summary>
+    [Fact]
+    public void Handler_KeepsDefaultVerification_WhenRequireCertificateValidation()
+    {
+        MxGatewayClientOptions options = new()
+        {
+            Endpoint = new Uri("https://localhost:5120"),
+            ApiKey = "k",
+            UseTls = true,
+            RequireCertificateValidation = true,
+        };
+        using SocketsHttpHandler handler = MxGatewayClient.CreateHttpHandlerForTests(options);
+        Assert.Null(handler.SslOptions.RemoteCertificateValidationCallback);
+    }
+}
@@ -315,7 +315,10 @@ public sealed class MxGatewayClient : IAsyncDisposable
            .ConfigureAwait(false);
    }

-    private static HttpMessageHandler CreateHttpHandler(MxGatewayClientOptions options)
+    private static HttpMessageHandler CreateHttpHandler(MxGatewayClientOptions options) =>
+        CreateHttpHandlerForTests(options);
+
+    internal static SocketsHttpHandler CreateHttpHandlerForTests(MxGatewayClientOptions options)
    {
        SocketsHttpHandler handler = new()
        {
@@ -350,6 +353,10 @@ public sealed class MxGatewayClient : IAsyncDisposable
                    return customChain.Build(certificateToValidate);
                };
            }
+            else if (!options.RequireCertificateValidation)
+            {
+                handler.SslOptions.RemoteCertificateValidationCallback = (_, _, _, _) => true;
+            }
        }

        return handler;
@@ -27,6 +27,14 @@ public sealed class MxGatewayClientOptions
    /// </summary>
    public string? CaCertificatePath { get; init; }

+    /// <summary>
+    /// When true, TLS connections without a pinned <see cref="CaCertificatePath"/>
+    /// use the OS trust store. When false (default), the gateway certificate is
+    /// accepted without verification — appropriate for this internal tool's
+    /// auto-generated self-signed certificate. Pinning a CA always verifies.
+    /// </summary>
+    public bool RequireCertificateValidation { get; init; }
+
    /// <summary>
    /// Gets the server name override for SNI during TLS handshake.
    /// </summary>
@@ -27,4 +27,10 @@
    <None Include="..\README.md" Pack="true" PackagePath="\" />
  </ItemGroup>

+  <ItemGroup>
+    <AssemblyAttribute Include="System.Runtime.CompilerServices.InternalsVisibleTo">
+      <_Parameter1>ZB.MOM.WW.MxGateway.Client.Tests</_Parameter1>
+    </AssemblyAttribute>
+  </ItemGroup>
+
 </Project>
@@ -222,10 +222,24 @@ func resolveTransportCredentials(opts Options) (credentials.TransportCredentials
 		return credentials.NewTLS(cfg), nil
 	}

-	return credentials.NewTLS(&tls.Config{
+	return credentials.NewTLS(tlsConfigForOptions(opts)), nil
+}
+
+// tlsConfigForOptions returns the *tls.Config for the no-CA, no-custom-config TLS path.
+// It returns nil when the caller should use a different credentials path (CA file or custom TLSConfig).
+// Exposed as an internal helper so unit tests can assert the InsecureSkipVerify posture.
+func tlsConfigForOptions(opts Options) *tls.Config {
+	// CA file and custom TLSConfig take their own paths in resolveTransportCredentials.
+	if opts.CACertFile != "" || opts.TLSConfig != nil {
+		return nil
+	}
+	return &tls.Config{
 		MinVersion: tls.VersionTLS12,
 		ServerName: opts.ServerNameOverride,
-	}), nil
+		//nolint:gosec // internal tool; self-signed cert is the expected gateway default;
+		// opt-in to strict verification via RequireCertificateValidation.
+		InsecureSkipVerify: !opts.RequireCertificateValidation,
+	}
 }

 // OpenSessionOptions describes fields used to create an OpenSessionRequest.
@@ -0,0 +1,59 @@
+package mxgateway
+
+import (
+	"crypto/tls"
+	"testing"
+)
+
+// tlsConfigFromOptions is the internal helper under test.
+// It extracts the *tls.Config from the no-CA TLS path of resolveTransportCredentials.
+// We exercise it directly to avoid needing a real dial target.
+
+func TestTLSInsecureSkipVerify_DefaultTrue(t *testing.T) {
+	cfg := tlsConfigForOptions(Options{
+		Endpoint: "localhost:5120",
+	})
+	if cfg == nil {
+		t.Fatal("expected non-nil tls.Config")
+	}
+	if !cfg.InsecureSkipVerify {
+		t.Error("InsecureSkipVerify should be true by default when no CA is pinned")
+	}
+}
+
+func TestTLSInsecureSkipVerify_FalseWhenRequireCertificateValidation(t *testing.T) {
+	cfg := tlsConfigForOptions(Options{
+		Endpoint:                     "localhost:5120",
+		RequireCertificateValidation: true,
+	})
+	if cfg == nil {
+		t.Fatal("expected non-nil tls.Config")
+	}
+	if cfg.InsecureSkipVerify {
+		t.Error("InsecureSkipVerify should be false when RequireCertificateValidation is true")
+	}
+}
+
+func TestTLSInsecureSkipVerify_FalseWhenCACertFileSet(t *testing.T) {
+	// When a CA file is pinned, the CA-verification path is taken instead.
+	// tlsConfigForOptions should return nil (the CA path does not use our helper).
+	cfg := tlsConfigForOptions(Options{
+		Endpoint:   "localhost:5120",
+		CACertFile: "/some/ca.pem",
+	})
+	if cfg != nil {
+		t.Error("expected nil tls.Config when CACertFile is set (CA path taken)")
+	}
+}
+
+func TestTLSInsecureSkipVerify_FalseWhenCustomTLSConfig(t *testing.T) {
+	// When TLSConfig is supplied explicitly, our default skip-verify must not overwrite it.
+	custom := &tls.Config{MinVersion: tls.VersionTLS13}
+	cfg := tlsConfigForOptions(Options{
+		Endpoint:  "localhost:5120",
+		TLSConfig: custom,
+	})
+	if cfg != nil {
+		t.Error("expected nil tls.Config when TLSConfig is already set (custom config path taken)")
+	}
+}
@@ -34,6 +34,10 @@ type Options struct {
 	TransportCredentials credentials.TransportCredentials
 	// DialOptions are appended to the gRPC dial options after the defaults.
 	DialOptions []grpc.DialOption
+	// RequireCertificateValidation forces TLS certificate verification even when
+	// no CACertFile is pinned. Default false: the gateway's self-signed cert is
+	// accepted without verification (internal-tool posture).
+	RequireCertificateValidation bool
 }

 // BrowseChildrenOptions configures lazy Galaxy hierarchy walks performed by
@@ -9,6 +9,10 @@ pluginManagement {
    }
 }

+plugins {
+    id 'org.gradle.toolchains.foojay-resolver-convention' version '1.0.0'
+}
+
 dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
@@ -384,6 +384,15 @@ public final class MxGatewayClient implements AutoCloseable {
            } catch (SSLException error) {
                throw new MxGatewayException("failed to configure gateway TLS", error);
            }
+        } else if (!options.requireCertificateValidation()) {
+            try {
+                builder.sslContext(GrpcSslContexts.forClient()
+                        .trustManager(io.grpc.netty.shaded.io.netty.handler.ssl.util
+                                .InsecureTrustManagerFactory.INSTANCE)
+                        .build());
+            } catch (SSLException error) {
+                throw new MxGatewayException("failed to configure lenient gateway TLS", error);
+            }
        } else {
            builder.useTransportSecurity();
        }
@@ -393,6 +402,19 @@ public final class MxGatewayClient implements AutoCloseable {
        return builder.build();
    }

+    /**
+     * Package-visible test seam — creates a raw {@link ManagedChannel} from the
+     * given options without attaching auth interceptors. Used by TLS fixture
+     * tests to verify channel construction behaviour without a full
+     * {@link MxGatewayClient} wrapper.
+     *
+     * @param options the client options
+     * @return a new {@link ManagedChannel}
+     */
+    static ManagedChannel createChannelForTests(MxGatewayClientOptions options) {
+        return createChannel(options);
+    }
+
    private <T extends io.grpc.stub.AbstractStub<T>> T withDeadline(T stub) {
        if (options.callTimeout().isNegative()) {
            return stub;
@@ -20,6 +20,7 @@ public final class MxGatewayClientOptions {
    private final String apiKey;
    private final boolean plaintext;
    private final Path caCertificatePath;
+    private final boolean requireCertificateValidation;
    private final String serverNameOverride;
    private final Duration connectTimeout;
    private final Duration callTimeout;
@@ -31,6 +32,7 @@ public final class MxGatewayClientOptions {
        apiKey = builder.apiKey == null ? "" : builder.apiKey;
        plaintext = builder.plaintext;
        caCertificatePath = builder.caCertificatePath;
+        requireCertificateValidation = builder.requireCertificateValidation;
        serverNameOverride = builder.serverNameOverride == null ? "" : builder.serverNameOverride;
        connectTimeout = builder.connectTimeout == null ? DEFAULT_CONNECT_TIMEOUT : builder.connectTimeout;
        callTimeout = builder.callTimeout == null ? DEFAULT_CALL_TIMEOUT : builder.callTimeout;
@@ -95,6 +97,18 @@ public final class MxGatewayClientOptions {
        return caCertificatePath;
    }

+    /**
+     * Returns whether TLS certificate verification is required even when no CA is pinned.
+     * When {@code false} (default), the gateway's self-signed certificate is accepted
+     * without verification. When {@code true}, the OS trust store is used.
+     * Pinning a CA via {@link #caCertificatePath()} always verifies regardless of this flag.
+     *
+     * @return {@code true} if strict certificate verification is required
+     */
+    public boolean requireCertificateValidation() {
+        return requireCertificateValidation;
+    }
+
    /**
     * Returns the TLS server-name override, or an empty string when none was supplied.
     *
@@ -148,6 +162,8 @@ public final class MxGatewayClientOptions {
                + plaintext
                + ", caCertificatePath="
                + caCertificatePath
+                + ", requireCertificateValidation="
+                + requireCertificateValidation
                + ", serverNameOverride='"
                + serverNameOverride
                + '\''
@@ -177,6 +193,7 @@ public final class MxGatewayClientOptions {
        private String apiKey;
        private boolean plaintext;
        private Path caCertificatePath;
+        private boolean requireCertificateValidation;
        private String serverNameOverride;
        private Duration connectTimeout;
        private Duration callTimeout;
@@ -230,6 +247,21 @@ public final class MxGatewayClientOptions {
            return this;
        }

+        /**
+         * When {@code true}, TLS connections without a pinned CA use the OS trust store
+         * and will reject the gateway's self-signed certificate. When {@code false}
+         * (default), the gateway certificate is accepted without verification —
+         * appropriate for this internal tool's auto-generated self-signed certificate.
+         * Pinning a CA via {@link #caCertificatePath(Path)} always verifies.
+         *
+         * @param value {@code true} to require certificate validation, {@code false} to accept any cert
+         * @return this builder
+         */
+        public Builder requireCertificateValidation(boolean value) {
+            requireCertificateValidation = value;
+            return this;
+        }
+
        /**
         * Overrides the TLS server name used during the handshake.
         *
@@ -0,0 +1,198 @@
+package com.zb.mom.ww.mxgateway.client;
+
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import io.grpc.ManagedChannel;
+import io.grpc.Server;
+import io.grpc.StatusRuntimeException;
+import io.grpc.netty.shaded.io.grpc.netty.GrpcSslContexts;
+import io.grpc.netty.shaded.io.grpc.netty.NettyServerBuilder;
+import io.grpc.stub.StreamObserver;
+import java.io.File;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.net.InetSocketAddress;
+import java.nio.file.Files;
+import java.security.KeyStore;
+import java.security.PrivateKey;
+import java.security.cert.Certificate;
+import java.security.cert.X509Certificate;
+import java.time.Duration;
+import java.util.Base64;
+import java.util.concurrent.TimeUnit;
+import javax.net.ssl.SSLException;
+import mxaccess_gateway.v1.MxAccessGatewayGrpc;
+import mxaccess_gateway.v1.MxaccessGateway.OpenSessionReply;
+import mxaccess_gateway.v1.MxaccessGateway.OpenSessionRequest;
+import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatus;
+import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatusCode;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Verifies that the Java client connects to a Netty TLS server with a
+ * self-signed certificate when no CA is pinned (lenient default), and that
+ * setting {@code requireCertificateValidation(true)} causes a TLS failure.
+ *
+ * <p>A self-signed certificate is generated using {@code keytool} (always
+ * available in the JDK) to avoid dependencies on internal JDK APIs or
+ * BouncyCastle, and so the test works on all JDK versions used by the project.
+ */
+final class MxGatewayClientTlsTests {
+
+    private Server server;
+    private int port;
+    private File certPemFile;
+    private File keyPemFile;
+    private File keystoreFile;
+
+    @BeforeEach
+    void startTlsServer() throws Exception {
+        keystoreFile = File.createTempFile("gw-test-ks", ".p12");
+        certPemFile = File.createTempFile("gw-test-cert", ".pem");
+        keyPemFile = File.createTempFile("gw-test-key", ".pem");
+
+        // keytool refuses to write to a pre-existing (even empty) file; delete it first.
+        keystoreFile.delete();
+
+        // Use keytool to generate a self-signed PKCS12 keystore.
+        String keytool = ProcessHandle.current().info().command()
+                .map(cmd -> cmd.replace("java", "keytool"))
+                .orElse("keytool");
+        // Fall back to just "keytool" on PATH if the resolved path doesn't exist.
+        if (!new File(keytool).exists()) {
+            keytool = "keytool";
+        }
+        Process p = new ProcessBuilder(
+                keytool,
+                "-genkeypair",
+                "-alias", "server",
+                "-keyalg", "RSA",
+                "-keysize", "2048",
+                "-sigalg", "SHA256withRSA",
+                "-validity", "1",
+                "-dname", "CN=localhost",
+                "-storetype", "PKCS12",
+                "-storepass", "changeit",
+                "-keypass", "changeit",
+                "-keystore", keystoreFile.getAbsolutePath())
+                .redirectErrorStream(true)
+                .start();
+        int exit = p.waitFor();
+        if (exit != 0) {
+            String out = new String(p.getInputStream().readAllBytes());
+            throw new IllegalStateException("keytool failed (exit " + exit + "): " + out);
+        }
+
+        // Export cert and private key from the PKCS12 keystore to PEM files.
+        KeyStore ks = KeyStore.getInstance("PKCS12");
+        try (var is = Files.newInputStream(keystoreFile.toPath())) {
+            ks.load(is, "changeit".toCharArray());
+        }
+        X509Certificate cert = (X509Certificate) ks.getCertificate("server");
+        PrivateKey privateKey = (PrivateKey) ks.getKey("server", "changeit".toCharArray());
+
+        try (FileOutputStream out = new FileOutputStream(certPemFile)) {
+            out.write("-----BEGIN CERTIFICATE-----\n".getBytes());
+            out.write(Base64.getMimeEncoder(64, new byte[]{'\n'}).encode(cert.getEncoded()));
+            out.write("\n-----END CERTIFICATE-----\n".getBytes());
+        }
+        try (FileOutputStream out = new FileOutputStream(keyPemFile)) {
+            out.write("-----BEGIN PRIVATE KEY-----\n".getBytes());
+            out.write(Base64.getMimeEncoder(64, new byte[]{'\n'}).encode(privateKey.getEncoded()));
+            out.write("\n-----END PRIVATE KEY-----\n".getBytes());
+        }
+
+        server = NettyServerBuilder
+                .forAddress(new InetSocketAddress("127.0.0.1", 0))
+                .sslContext(GrpcSslContexts.forServer(certPemFile, keyPemFile).build())
+                .addService(new MinimalGatewayService())
+                .build()
+                .start();
+        port = server.getPort();
+    }
+
+    @AfterEach
+    void stopTlsServer() throws InterruptedException {
+        if (server != null) {
+            server.shutdown();
+            server.awaitTermination(5, TimeUnit.SECONDS);
+        }
+        if (certPemFile != null) {
+            certPemFile.delete();
+        }
+        if (keyPemFile != null) {
+            keyPemFile.delete();
+        }
+        if (keystoreFile != null) {
+            keystoreFile.delete();
+        }
+    }
+
+    @Test
+    void connectsToSelfSignedServer_WhenRequireCertificateValidationIsFalse() throws SSLException {
+        // Default options — requireCertificateValidation defaults to false.
+        MxGatewayClientOptions options = MxGatewayClientOptions.builder()
+                .endpoint("127.0.0.1:" + port)
+                .apiKey("test-key")
+                .connectTimeout(Duration.ofSeconds(5))
+                .callTimeout(Duration.ofSeconds(5))
+                .build();
+
+        ManagedChannel channel = MxGatewayClient.createChannelForTests(options);
+        try {
+            MxAccessGatewayGrpc.MxAccessGatewayBlockingStub stub =
+                    MxAccessGatewayGrpc.newBlockingStub(channel);
+            OpenSessionReply reply = stub.openSession(
+                    OpenSessionRequest.newBuilder()
+                            .setClientSessionName("tls-test")
+                            .build());
+            assertTrue(reply.getProtocolStatus().getCode()
+                    == ProtocolStatusCode.PROTOCOL_STATUS_CODE_OK);
+        } finally {
+            channel.shutdownNow();
+        }
+    }
+
+    @Test
+    void failsToConnect_WhenRequireCertificateValidationIsTrue() throws SSLException {
+        MxGatewayClientOptions options = MxGatewayClientOptions.builder()
+                .endpoint("127.0.0.1:" + port)
+                .apiKey("test-key")
+                .requireCertificateValidation(true)
+                .connectTimeout(Duration.ofSeconds(5))
+                .callTimeout(Duration.ofSeconds(5))
+                .build();
+
+        ManagedChannel channel = MxGatewayClient.createChannelForTests(options);
+        try {
+            MxAccessGatewayGrpc.MxAccessGatewayBlockingStub stub =
+                    MxAccessGatewayGrpc.newBlockingStub(channel);
+            assertThrows(StatusRuntimeException.class, () ->
+                    stub.openSession(OpenSessionRequest.newBuilder()
+                            .setClientSessionName("tls-strict-test")
+                            .build()));
+        } finally {
+            channel.shutdownNow();
+        }
+    }
+
+    /** Minimal gateway stub that succeeds any OpenSession call. */
+    private static final class MinimalGatewayService
+            extends MxAccessGatewayGrpc.MxAccessGatewayImplBase {
+        @Override
+        public void openSession(
+                OpenSessionRequest request,
+                StreamObserver<OpenSessionReply> responseObserver) {
+            responseObserver.onNext(OpenSessionReply.newBuilder()
+                    .setSessionId("tls-test-session")
+                    .setProtocolStatus(ProtocolStatus.newBuilder()
+                            .setCode(ProtocolStatusCode.PROTOCOL_STATUS_CODE_OK)
+                            .build())
+                    .build());
+            responseObserver.onCompleted();
+        }
+    }
+}
@@ -2,6 +2,7 @@

 from __future__ import annotations

+import ssl
 from collections.abc import Sequence
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -9,6 +10,7 @@ from pathlib import Path
 import grpc

 from .auth import REDACTED, ApiKey
+from .errors import MxGatewayTransportError


@dataclass(frozen=True)
@@ -19,6 +21,7 @@ class ClientOptions:
    api_key: str | ApiKey | None = None
    plaintext: bool = False
    ca_file: str | None = None
+    require_certificate_validation: bool = False
    server_name_override: str | None = None
    call_timeout: float | None = 30.0
    stream_timeout: float | None = None
@@ -45,6 +48,7 @@ class ClientOptions:
            f"{type(self).__name__}(endpoint={self.endpoint!r}, "
            f"api_key={api_key!r}, plaintext={self.plaintext!r}, "
            f"ca_file={self.ca_file!r}, "
+            f"require_certificate_validation={self.require_certificate_validation!r}, "
            f"server_name_override={self.server_name_override!r}, "
            f"call_timeout={self.call_timeout!r}, "
            f"stream_timeout={self.stream_timeout!r}, "
@@ -69,8 +73,22 @@ class BrowseChildrenOptions:
    historized_only: bool = False


+def _split_authority(endpoint: str) -> tuple[str, int]:
+    """Split a gRPC target (optionally scheme-prefixed) into (host, port)."""
+    target = endpoint.split("://", 1)[-1]
+    host, _, port = target.rpartition(":")
+    return (host or "localhost", int(port) if port else 443)
+
+
 def create_channel(options: ClientOptions) -> grpc.aio.Channel:
-    """Create a plaintext or TLS `grpc.aio` channel from client options."""
+    """Create a plaintext or TLS `grpc.aio` channel from client options.
+
+    The TLS default is lenient: grpc-python has no per-channel skip-verify, so
+    the server's presented certificate is fetched once (unverified) and pinned
+    as the channel's only trust root (trust-on-first-use). Set
+    `require_certificate_validation=True` to force system-trust verification, or
+    pass `ca_file` to verify against a specific CA — both bypass the TOFU path.
+    """

    channel_options: list[tuple[str, str | int]] = [
        ("grpc.max_receive_message_length", options.max_grpc_message_bytes),
@@ -82,11 +100,28 @@ def create_channel(options: ClientOptions) -> grpc.aio.Channel:
    if options.plaintext:
        return grpc.aio.insecure_channel(options.endpoint, options=channel_options)

-    root_certificates = None
    if options.ca_file:
        root_certificates = Path(options.ca_file).read_bytes()
+        credentials = grpc.ssl_channel_credentials(root_certificates=root_certificates)
+    elif options.require_certificate_validation:
+        credentials = grpc.ssl_channel_credentials()
+    else:
+        # Lenient default: grpc-python has no per-channel skip-verify, so fetch the
+        # server's certificate (unverified) and pin it for this channel (TOFU).
+        host, port = _split_authority(options.endpoint)
+        try:
+            presented = ssl.get_server_certificate((host, port))
+        except OSError as error:
+            raise MxGatewayTransportError(
+                f"failed to fetch TLS certificate from {options.endpoint}: {error}"
+            ) from error
+        credentials = grpc.ssl_channel_credentials(root_certificates=presented.encode("ascii"))
+        # The gateway self-signed cert always carries a "localhost" SAN, so default
+        # the SNI/target-name override to it when none was supplied, tolerating
+        # dial-by-IP or hostname mismatch.
+        if not options.server_name_override:
+            channel_options.append(("grpc.ssl_target_name_override", "localhost"))

-    credentials = grpc.ssl_channel_credentials(root_certificates=root_certificates)
    return grpc.aio.secure_channel(
        options.endpoint,
        credentials,
@@ -72,27 +72,83 @@ def test_create_channel_uses_plaintext_channel(monkeypatch: pytest.MonkeyPatch)
    ]


-def test_create_channel_uses_tls_channel(monkeypatch: pytest.MonkeyPatch) -> None:
-    calls: list[tuple[str, object, object]] = []
+def test_create_channel_uses_tls_channel_tofu_default(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Default TLS (no ca_file, no require_certificate_validation) uses TOFU:
+    fetches the server cert unverified, pins it as root_certificates, and adds
+    grpc.ssl_target_name_override = "localhost" automatically.
+    """
+    _DUMMY_PEM = "-----BEGIN CERTIFICATE-----\nZmFrZQ==\n-----END CERTIFICATE-----\n"
+    get_cert_calls: list[tuple[str, int]] = []

-    def fake_credentials(*, root_certificates: object) -> str:
-        assert root_certificates is None
+    def fake_get_server_certificate(addr: tuple[str, int]) -> str:
+        get_cert_calls.append(addr)
+        return _DUMMY_PEM
+
+    cred_calls: list[object] = []
+
+    def fake_credentials(*, root_certificates: object = None) -> str:
+        cred_calls.append(root_certificates)
        return "creds"

+    channel_calls: list[tuple[str, object, object]] = []
+
    def fake_secure_channel(endpoint: str, credentials: object, *, options: object) -> str:
-        calls.append((endpoint, credentials, options))
+        channel_calls.append((endpoint, credentials, options))
        return "tls-channel"

-    monkeypatch.setattr(
-        options_module.grpc,
-        "ssl_channel_credentials",
-        fake_credentials,
+    monkeypatch.setattr(options_module.ssl, "get_server_certificate", fake_get_server_certificate)
+    monkeypatch.setattr(options_module.grpc, "ssl_channel_credentials", fake_credentials)
+    monkeypatch.setattr(options_module.grpc.aio, "secure_channel", fake_secure_channel)
+
+    channel = create_channel(
+        ClientOptions(endpoint="gateway.example:5001"),
    )
+
+    assert channel == "tls-channel"
+    # TOFU: should have fetched the cert from the server (host, port)
+    assert get_cert_calls == [("gateway.example", 5001)]
+    # Pinned the fetched PEM bytes as root_certificates
+    assert cred_calls == [_DUMMY_PEM.encode("ascii")]
+    # Auto-injected localhost override (no server_name_override supplied)
+    assert channel_calls == [
+        (
+            "gateway.example:5001",
+            "creds",
+            [
+                ("grpc.max_receive_message_length", 16 * 1024 * 1024),
+                ("grpc.max_send_message_length", 16 * 1024 * 1024),
+                ("grpc.ssl_target_name_override", "localhost"),
+            ],
+        ),
+    ]
+
+
+def test_create_channel_uses_tls_channel_tofu_respects_server_name_override(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """When server_name_override is set, TOFU still runs but does NOT add the
+    auto-localhost override (the explicit override is already in channel_options).
+    """
+    _DUMMY_PEM = "-----BEGIN CERTIFICATE-----\nZmFrZQ==\n-----END CERTIFICATE-----\n"
    monkeypatch.setattr(
-        options_module.grpc.aio,
-        "secure_channel",
-        fake_secure_channel,
+        options_module.ssl,
+        "get_server_certificate",
+        lambda addr: _DUMMY_PEM,
    )
+    cred_calls: list[object] = []
+
+    def fake_credentials(*, root_certificates: object = None) -> str:
+        cred_calls.append(root_certificates)
+        return "creds"
+
+    channel_calls: list[tuple[str, object, object]] = []
+
+    def fake_secure_channel(endpoint: str, credentials: object, *, options: object) -> str:
+        channel_calls.append((endpoint, credentials, options))
+        return "tls-channel"
+
+    monkeypatch.setattr(options_module.grpc, "ssl_channel_credentials", fake_credentials)
+    monkeypatch.setattr(options_module.grpc.aio, "secure_channel", fake_secure_channel)

    channel = create_channel(
        ClientOptions(
@@ -102,14 +158,121 @@ def test_create_channel_uses_tls_channel(monkeypatch: pytest.MonkeyPatch) -> Non
    )

    assert channel == "tls-channel"
-    assert calls == [
-            (
-                "gateway.example:5001",
-                "creds",
-                [
-                    ("grpc.max_receive_message_length", 16 * 1024 * 1024),
-                    ("grpc.max_send_message_length", 16 * 1024 * 1024),
-                    ("grpc.ssl_target_name_override", "gateway.test"),
-                ],
-            ),
-        ]
+    assert cred_calls == [_DUMMY_PEM.encode("ascii")]
+    assert channel_calls == [
+        (
+            "gateway.example:5001",
+            "creds",
+            [
+                ("grpc.max_receive_message_length", 16 * 1024 * 1024),
+                ("grpc.max_send_message_length", 16 * 1024 * 1024),
+                # Explicit override from ClientOptions — not the auto-localhost one
+                ("grpc.ssl_target_name_override", "gateway.test"),
+            ],
+        ),
+    ]
+
+
+def test_create_channel_uses_tls_channel_require_cert_validation(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """require_certificate_validation=True uses system trust (no TOFU, no root_certificates)."""
+    get_cert_called = False
+
+    def fake_get_server_certificate(addr: object) -> str:  # pragma: no cover
+        nonlocal get_cert_called
+        get_cert_called = True
+        return "SHOULD_NOT_BE_CALLED"
+
+    cred_calls: list[object] = []
+
+    def fake_credentials(**kwargs: object) -> str:
+        cred_calls.append(kwargs)
+        return "creds"
+
+    channel_calls: list[tuple[str, object, object]] = []
+
+    def fake_secure_channel(endpoint: str, credentials: object, *, options: object) -> str:
+        channel_calls.append((endpoint, credentials, options))
+        return "tls-channel"
+
+    monkeypatch.setattr(options_module.ssl, "get_server_certificate", fake_get_server_certificate)
+    monkeypatch.setattr(options_module.grpc, "ssl_channel_credentials", fake_credentials)
+    monkeypatch.setattr(options_module.grpc.aio, "secure_channel", fake_secure_channel)
+
+    channel = create_channel(
+        ClientOptions(
+            endpoint="gateway.example:5001",
+            require_certificate_validation=True,
+        ),
+    )
+
+    assert channel == "tls-channel"
+    # Must NOT call TOFU prefetch
+    assert not get_cert_called
+    # ssl_channel_credentials() called with NO keyword args (system trust)
+    assert cred_calls == [{}]
+    assert channel_calls == [
+        (
+            "gateway.example:5001",
+            "creds",
+            [
+                ("grpc.max_receive_message_length", 16 * 1024 * 1024),
+                ("grpc.max_send_message_length", 16 * 1024 * 1024),
+            ],
+        ),
+    ]
+
+
+def test_create_channel_uses_tls_channel_ca_file(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: pytest.TempPathFactory,
+) -> None:
+    """ca_file path: reads the PEM file, passes bytes as root_certificates, skips TOFU."""
+    ca_pem = b"-----BEGIN CERTIFICATE-----\nY2FkYXRh\n-----END CERTIFICATE-----\n"
+    ca_file = tmp_path / "ca.pem"
+    ca_file.write_bytes(ca_pem)
+
+    get_cert_called = False
+
+    def fake_get_server_certificate(addr: object) -> str:  # pragma: no cover
+        nonlocal get_cert_called
+        get_cert_called = True
+        return "SHOULD_NOT_BE_CALLED"
+
+    cred_calls: list[object] = []
+
+    def fake_credentials(*, root_certificates: object = None) -> str:
+        cred_calls.append(root_certificates)
+        return "creds"
+
+    channel_calls: list[tuple[str, object, object]] = []
+
+    def fake_secure_channel(endpoint: str, credentials: object, *, options: object) -> str:
+        channel_calls.append((endpoint, credentials, options))
+        return "tls-channel"
+
+    monkeypatch.setattr(options_module.ssl, "get_server_certificate", fake_get_server_certificate)
+    monkeypatch.setattr(options_module.grpc, "ssl_channel_credentials", fake_credentials)
+    monkeypatch.setattr(options_module.grpc.aio, "secure_channel", fake_secure_channel)
+
+    channel = create_channel(
+        ClientOptions(
+            endpoint="gateway.example:5001",
+            ca_file=str(ca_file),
+        ),
+    )
+
+    assert channel == "tls-channel"
+    assert not get_cert_called
+    assert cred_calls == [ca_pem]
+    assert channel_calls == [
+        (
+            "gateway.example:5001",
+            "creds",
+            [
+                ("grpc.max_receive_message_length", 16 * 1024 * 1024),
+                ("grpc.max_send_message_length", 16 * 1024 * 1024),
+            ],
+        ),
+    ]
@@ -0,0 +1,154 @@
+"""TLS behaviour tests for ``create_channel``.
+
+These spin up a real loopback ``grpc.aio`` server with a freshly generated
+self-signed certificate (carrying a ``localhost`` SAN, mirroring the gateway's
+auto-generated cert) and assert the lenient TOFU default lets a client connect
+without any CA configured.
+
+Marked ``tls`` and skipped unless ``MXGATEWAY_RUN_TLS_TESTS=1`` because loopback
+TLS handshakes can be timing-flaky on shared CI runners. This mirrors how the
+suite gates anything that depends on real sockets rather than fakes.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import socket
+import ssl
+import subprocess
+import tempfile
+from collections.abc import AsyncIterator
+from pathlib import Path
+
+import grpc
+import pytest
+import pytest_asyncio
+
+from zb_mom_ww_mxgateway import ClientOptions
+from zb_mom_ww_mxgateway.errors import MxGatewayTransportError
+from zb_mom_ww_mxgateway.generated import mxaccess_gateway_pb2 as pb
+from zb_mom_ww_mxgateway.generated import mxaccess_gateway_pb2_grpc as pb_grpc
+from zb_mom_ww_mxgateway.options import create_channel
+
+pytestmark = pytest.mark.tls
+
+_RUN_TLS_TESTS = os.environ.get("MXGATEWAY_RUN_TLS_TESTS") == "1"
+_OPENSSL = shutil.which("openssl")
+
+requires_tls = pytest.mark.skipif(
+    not _RUN_TLS_TESTS,
+    reason="set MXGATEWAY_RUN_TLS_TESTS=1 to run loopback TLS tests",
+)
+requires_openssl = pytest.mark.skipif(
+    _OPENSSL is None,
+    reason="openssl CLI is required to generate a self-signed test certificate",
+)
+
+
+def _generate_self_signed_cert(directory: Path) -> tuple[Path, Path]:
+    """Generate a self-signed cert/key pair with a ``localhost`` SAN."""
+    key_path = directory / "server.key"
+    cert_path = directory / "server.crt"
+    subprocess.run(
+        [
+            str(_OPENSSL),
+            "req",
+            "-x509",
+            "-newkey",
+            "rsa:2048",
+            "-nodes",
+            "-keyout",
+            str(key_path),
+            "-out",
+            str(cert_path),
+            "-days",
+            "1",
+            "-subj",
+            "/CN=mxgateway-test",
+            "-addext",
+            "subjectAltName=DNS:localhost,IP:127.0.0.1",
+        ],
+        check=True,
+        capture_output=True,
+    )
+    return cert_path, key_path
+
+
+def _free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind(("127.0.0.1", 0))
+        return int(sock.getsockname()[1])
+
+
+class _StaticGatewayServicer(pb_grpc.MxAccessGatewayServicer):
+    """Minimal servicer answering ``OpenSession`` with a fixed session id."""
+
+    async def OpenSession(  # noqa: N802 - generated gRPC method name
+        self, request: pb.OpenSessionRequest, context: object
+    ) -> pb.OpenSessionReply:
+        return pb.OpenSessionReply(session_id="tls-session-1")
+
+
+@pytest_asyncio.fixture
+async def tls_server() -> AsyncIterator[int]:
+    with tempfile.TemporaryDirectory() as tmp:
+        cert_path, key_path = _generate_self_signed_cert(Path(tmp))
+        credentials = grpc.ssl_server_credentials(
+            [(key_path.read_bytes(), cert_path.read_bytes())]
+        )
+        server = grpc.aio.server()
+        pb_grpc.add_MxAccessGatewayServicer_to_server(_StaticGatewayServicer(), server)
+        port = _free_port()
+        server.add_secure_port(f"127.0.0.1:{port}", credentials)
+        await server.start()
+        try:
+            yield port
+        finally:
+            await server.stop(grace=None)
+
+
+@requires_tls
+@requires_openssl
+@pytest.mark.asyncio
+async def test_default_tls_connects_via_tofu(tls_server: int) -> None:
+    """Default TLS options (no CA) connect by pinning the presented cert."""
+    options = ClientOptions(
+        endpoint=f"127.0.0.1:{tls_server}",
+        api_key="mxgw_test_secret",
+    )
+    channel = create_channel(options)
+    try:
+        stub = pb_grpc.MxAccessGatewayStub(channel)
+        reply = await stub.OpenSession(pb.OpenSessionRequest(), timeout=10)
+        assert reply.session_id == "tls-session-1"
+    finally:
+        await channel.close()
+
+
+def test_split_authority_parses_host_and_port() -> None:
+    from zb_mom_ww_mxgateway.options import _split_authority
+
+    assert _split_authority("https://10.0.0.5:5120") == ("10.0.0.5", 5120)
+    assert _split_authority("localhost:5120") == ("localhost", 5120)
+    assert _split_authority(":5120") == ("localhost", 5120)
+
+
+def test_tofu_connect_failure_raises_transport_error() -> None:
+    """A failed cert pre-fetch surfaces the client's transport error type."""
+    options = ClientOptions(endpoint=f"127.0.0.1:{_free_port()}")
+    with pytest.raises(MxGatewayTransportError) as excinfo:
+        create_channel(options)
+    assert options.endpoint in str(excinfo.value)
+
+
+def test_require_certificate_validation_uses_system_trust() -> None:
+    """``require_certificate_validation`` must not attempt a TOFU pre-fetch."""
+    # Pointing at a closed port: with system-trust the channel is created lazily
+    # (no eager pre-fetch), so create_channel must succeed without connecting.
+    options = ClientOptions(
+        endpoint=f"127.0.0.1:{_free_port()}",
+        require_certificate_validation=True,
+    )
+    channel = create_channel(options)
+    assert isinstance(channel, grpc.aio.Channel)
@@ -89,6 +89,26 @@ impl GatewayClient {
                    detail: format!("failed to read CA file {}: {source}", ca_file.display()),
                })?;
                tls = tls.ca_certificate(Certificate::from_pem(certificate));
+            } else if !options.require_certificate_validation() {
+                // Lenient-default fallback (Rust pin-only exception): tonic
+                // 0.13's `ClientTlsConfig` builds its rustls verifier inside a
+                // crate-private connector and exposes no hook for a custom
+                // `ServerCertVerifier`, so — unlike the other clients — the
+                // Rust client cannot accept an arbitrary self-signed cert. Pin
+                // the gateway's CA instead, or opt into strict verification
+                // against the system trust roots. We reject here rather than
+                // silently verifying against system roots (which would fail a
+                // self-signed gateway with a confusing handshake error).
+                return Err(Error::InvalidEndpoint {
+                    endpoint: options.endpoint().to_owned(),
+                    detail: "TLS requested without a pinned CA. The Rust client cannot accept an \
+                             arbitrary self-signed certificate (tonic 0.13 exposes no custom \
+                             rustls verifier). Pin the gateway certificate with \
+                             ClientOptions::with_ca_file, or call \
+                             ClientOptions::with_require_certificate_validation(true) to verify \
+                             against the system trust roots."
+                        .to_owned(),
+                });
            }
            endpoint = endpoint.tls_config(tls)?;
        }
@@ -22,6 +22,7 @@ pub struct ClientOptions {
    api_key: Option<ApiKey>,
    plaintext: bool,
    ca_file: Option<PathBuf>,
+    require_certificate_validation: bool,
    server_name_override: Option<String>,
    connect_timeout: Duration,
    call_timeout: Duration,
@@ -38,6 +39,7 @@ impl ClientOptions {
            api_key: None,
            plaintext: true,
            ca_file: None,
+            require_certificate_validation: false,
            server_name_override: None,
            connect_timeout: Duration::from_secs(10),
            call_timeout: Duration::from_secs(30),
@@ -67,6 +69,22 @@ impl ClientOptions {
        self
    }

+    /// Require TLS certificate verification even without a pinned CA. Default
+    /// false: the gateway's self-signed certificate is accepted (internal-tool
+    /// posture). Setting a CA file always verifies.
+    ///
+    /// Note for Rust: tonic 0.13's `ClientTlsConfig` exposes no hook for a
+    /// custom rustls verifier, so the Rust client cannot accept an arbitrary
+    /// self-signed certificate the way the other clients do. With the default
+    /// (false) and no pinned CA, [`crate::client::GatewayClient::connect`]
+    /// rejects the TLS connection and asks for a CA file. Either pin a CA via
+    /// [`ClientOptions::with_ca_file`] (the supported lenient path on Rust) or
+    /// set this `true` to verify against the system trust roots.
+    pub fn with_require_certificate_validation(mut self, require: bool) -> Self {
+        self.require_certificate_validation = require;
+        self
+    }
+
    /// Override the SNI/server name used during the TLS handshake. Useful
    /// when the dial-target host name does not match the certificate.
    pub fn with_server_name_override(mut self, server_name_override: impl Into<String>) -> Self {
@@ -121,6 +139,12 @@ impl ClientOptions {
        self.ca_file.as_ref()
    }

+    /// Whether TLS certificate verification is required even without a pinned
+    /// CA. See [`ClientOptions::with_require_certificate_validation`].
+    pub fn require_certificate_validation(&self) -> bool {
+        self.require_certificate_validation
+    }
+
    /// Optional SNI / server-name override for TLS handshakes.
    pub fn server_name_override(&self) -> Option<&str> {
        self.server_name_override.as_deref()
@@ -161,6 +185,10 @@ impl fmt::Debug for ClientOptions {
            .field("api_key", &self.api_key.as_ref().map(|_| "<redacted>"))
            .field("plaintext", &self.plaintext)
            .field("ca_file", &self.ca_file)
+            .field(
+                "require_certificate_validation",
+                &self.require_certificate_validation,
+            )
            .field("server_name_override", &self.server_name_override)
            .field("connect_timeout", &self.connect_timeout)
            .field("call_timeout", &self.call_timeout)
@@ -0,0 +1,103 @@
+//! TLS posture coverage for the Rust client.
+//!
+//! tonic 0.13.1's `ClientTlsConfig` exposes no hook for a custom rustls
+//! `ServerCertVerifier` (the verifier is built internally inside the
+//! crate-private `TlsConnector`), so the Rust client cannot implement the
+//! "accept any server certificate" lenient default the other clients use.
+//! Rust is therefore the documented **pin-only exception**: TLS without a
+//! pinned CA is rejected up front with a clear, actionable error, and
+//! supplying a CA file is the supported path. These tests pin that contract.
+
+use std::time::Duration;
+
+use zb_mom_ww_mxgateway_client::{ClientOptions, Error, GatewayClient};
+
+/// Drive `connect` to its error without requiring `GatewayClient: Debug`
+/// (the success arm is dropped explicitly so `unwrap_err` is unnecessary).
+async fn connect_err(options: ClientOptions) -> Error {
+    match GatewayClient::connect(options).await {
+        Ok(_client) => panic!("connect unexpectedly succeeded against a dead TLS address"),
+        Err(error) => error,
+    }
+}
+
+#[tokio::test]
+async fn tls_without_ca_is_rejected_with_actionable_error_by_default() {
+    let options = ClientOptions::new("https://127.0.0.1:1")
+        .with_plaintext(false)
+        .with_connect_timeout(Duration::from_millis(200));
+
+    let error = connect_err(options).await;
+
+    let Error::InvalidEndpoint { detail, .. } = error else {
+        panic!("expected InvalidEndpoint, got {error:?}");
+    };
+    // The message must point the caller at the supported remedy (pin a CA)
+    // and name the opt-in escape hatch.
+    assert!(
+        detail.contains("ca_file") || detail.contains("CA"),
+        "error should instruct the user to pass a CA file: {detail}"
+    );
+    assert!(
+        detail.contains("require_certificate_validation"),
+        "error should mention the require_certificate_validation opt-in: {detail}"
+    );
+}
+
+#[tokio::test]
+async fn tls_with_require_certificate_validation_does_not_short_circuit() {
+    // With strict verification opted in, the no-CA guard must not fire; the
+    // connect attempt instead proceeds to the transport (and fails to reach
+    // the dead address) rather than returning the "CA required" guard error.
+    let options = ClientOptions::new("https://127.0.0.1:1")
+        .with_plaintext(false)
+        .with_require_certificate_validation(true)
+        .with_connect_timeout(Duration::from_millis(200));
+
+    let error = connect_err(options).await;
+
+    assert!(
+        !matches!(&error, Error::InvalidEndpoint { detail, .. }
+            if detail.contains("require_certificate_validation")),
+        "strict verification must bypass the no-CA guard, got {error:?}"
+    );
+}
+
+#[tokio::test]
+async fn tls_with_ca_file_is_permitted_and_proceeds_past_the_guard() {
+    // Pinning a CA is the supported TLS path: the no-CA guard must not fire.
+    // We hand it a readable PEM file; construction proceeds past the guard
+    // and only fails later at the transport (dead address / handshake).
+    let ca_path = std::env::temp_dir().join("mxgw-rust-tls-ca-fixture.pem");
+    std::fs::write(&ca_path, SELF_SIGNED_CA_PEM).unwrap();
+
+    let options = ClientOptions::new("https://127.0.0.1:1")
+        .with_plaintext(false)
+        .with_ca_file(&ca_path)
+        .with_connect_timeout(Duration::from_millis(200));
+
+    let error = connect_err(options).await;
+
+    let _ = std::fs::remove_file(&ca_path);
+
+    assert!(
+        !matches!(&error, Error::InvalidEndpoint { detail, .. }
+            if detail.contains("require_certificate_validation")),
+        "pinning a CA must bypass the no-CA guard, got {error:?}"
+    );
+}
+
+/// A throwaway self-signed CA certificate (PEM). Only needs to parse as a
+/// PEM trust root so the CA-pinning path is exercised past the guard.
+const SELF_SIGNED_CA_PEM: &str = "-----BEGIN CERTIFICATE-----
+MIIBhTCCASugAwIBAgIQIRi6zePL6mKjOipn+dNuaTAKBggqhkjOPQQDAjASMRAw
+DgYDVQQKEwdBY21lIENvMB4XDTE3MTAyMDE5NDMwNloXDTE4MTAyMDE5NDMwNlow
+EjEQMA4GA1UEChMHQWNtZSBDbzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABD0d
+7VNhbWvZLWPuj/RtHFjvtJBEwOkhbN/BnnE8rnZR8+sbwnc/KhCk3FhnpHZnQz7B
+5aETbbIgmuvewdjvSBSjYzBhMA4GA1UdDwEB/wQEAwICpDATBgNVHSUEDDAKBggr
+BgEFBQcDATAPBgNVHRMBAf8EBTADAQH/MCkGA1UdEQQiMCCCDmxvY2FsaG9zdDo1
+NDUzgg4xMjcuMC4wLjE6NTQ1MzAKBggqhkjOPQQDAgNIADBFAiEA2zpJEPQyz6/l
+Wf86aX6PepsntZv2GYlA5UpabfT2EZICICpJ5h/iI+i341gBmLiAFQOyTDT+/wQc
+6MF9+Yw1Yy0t
+-----END CERTIFICATE-----
+";
@@ -0,0 +1,156 @@
+# Gateway TLS Auto-Certificate and Lenient Client Trust — Design
+
+Date: 2026-06-01
+Status: Approved (brainstorming), pending implementation plan
+
+## Problem
+
+The gateway can serve gRPC and the dashboard over TLS, but only if an operator
+supplies a certificate via the Kestrel `https://` endpoint config. With no cert,
+an `https` endpoint fails at startup with Kestrel's opaque "No server certificate
+was specified" error. Both current deployments therefore run plaintext (`h2c`),
+exposing the API key and request payloads on the wire.
+
+`mxaccessgw` is an internal tool. The goal is for TLS to "just work" with zero PKI
+management: the gateway fabricates its own long-lived certificate when an HTTPS
+endpoint is configured without one, and clients accept whatever certificate is
+presented unless an operator explicitly opts into pinning.
+
+## Decisions
+
+1. **Gateway = fill-missing-cert-only.** No new "enable TLS" switch. TLS is still
+   driven by configuring a Kestrel `https://` endpoint. New behavior: when an
+   HTTPS endpoint has no `Certificate` section, the gateway generates/loads a
+   persisted self-signed cert instead of failing. Plaintext-only hosts are
+   untouched — no certificate or key material is ever written for them.
+2. **Persist & reuse.** The self-signed cert is saved as a PFX under
+   `C:\ProgramData\MxGateway\certs`, reused across restarts, regenerated only if
+   missing, expired, or unreadable. Stable thumbprint; survives restarts; any
+   CA-pinning client keeps working.
+3. **Clients = lenient TLS, plaintext default.** When a client connects over TLS
+   without a pinned CA, it skips verification (accepts any cert). Pinning a CA file
+   restores full verification. The per-client connection default (mostly
+   plaintext/`http`) does not change — TLS is still opt-in via the endpoint scheme.
+
+**Scope boundary:** the gateway↔worker named-pipe IPC is unchanged (local,
+OS-secured by the pipe ACL). This work touches only the public gRPC/dashboard
+transport and the five language clients.
+
+## Gateway component
+
+New type `SelfSignedCertificateProvider` in
+`src/ZB.MOM.WW.MxGateway.Server/Security/Tls/`.
+
+1. **Detect need.** Inspect `Kestrel:Endpoints:*` configuration at startup. If any
+   endpoint has an `https://` URL and no `Certificate` subsection, a default cert
+   is needed. If none do, the provider is a no-op (no file written).
+2. **Load-or-create.** Look for the persisted PFX. If present, valid, and
+   unexpired, load it. Otherwise generate and persist.
+3. **Generate.** `CertificateRequest` with **ECDSA P-256**, `notBefore = now - 1
+   day` (clock-skew slack), `notAfter = now + ValidityYears`. SANs: `DNS=localhost`,
+   `DNS=<MachineName>`, `DNS=<MachineName.FQDN>` when resolvable, plus
+   `IP=127.0.0.1` and `IP=::1`. Server-auth EKU.
+4. **Persist securely.** Write the PFX with an **empty** export password (a random
+   in-memory password cannot be reused across restarts, which the persist-and-reuse
+   decision requires); protect the private key with a restrictive ACL (SYSTEM +
+   Administrators + service account) on the `certs` directory and file on Windows,
+   and `0600` on non-Windows; atomic write (temp + rename). After generating, the
+   cert is reloaded from the persisted PFX so Kestrel always serves the on-disk key.
+5. **Wire into Kestrel.** In `GatewayApplication.CreateBuilder`, add
+   `builder.WebHost.ConfigureKestrel(o => o.ConfigureHttpsDefaults(h =>
+   h.ServerCertificate = cert))`. `ConfigureHttpsDefaults` supplies the cert only
+   for HTTPS endpoints that did not specify their own, so an operator-configured
+   `Kestrel:Endpoints:*:Certificate` transparently overrides it. One hook covers
+   both the gRPC and dashboard ports.
+
+### New config block `MxGateway:Tls`
+
+All optional; the zero-config path needs none of them.
+
+| Option | Default | Purpose |
+|---|---|---|
+| `Tls:SelfSignedCertPath` | `C:\ProgramData\MxGateway\certs\gateway-selfsigned.pfx` | Where the generated cert lives |
+| `Tls:ValidityYears` | `10` | Lifetime of the generated cert |
+| `Tls:AdditionalDnsNames` | `[]` | Extra SANs (e.g. a load-balancer name) |
+| `Tls:RegenerateIfExpired` | `true` | Auto-replace an expired persisted cert |
+
+Validated by `GatewayOptionsValidator`: `ValidityYears` in 1–100,
+`SelfSignedCertPath` is a valid path shape when non-blank, and
+`AdditionalDnsNames` entries are non-blank. (The "https endpoint exists but cert
+path is blank" fail-fast lives in the bootstrap/provider, not the validator,
+because the validator only sees the `MxGateway` section, not `Kestrel:Endpoints`.)
+
+**Logging:** on generate/load, log thumbprint + SAN list + `notAfter` at
+Information. Never log the PFX password or private key.
+
+## Client lenient-TLS behavior
+
+Uniform rule: **TLS on + no CA pinned ⇒ skip verification; CA pinned ⇒ full
+verification.** No transport default changes. Each client also exposes an explicit
+switch to force-disable leniency (strict-without-pinning) for the future.
+
+| Client | Mechanism | Effort |
+|---|---|---|
+| .NET | In `CreateHttpHandler`, when `UseTls` and `CaCertificatePath` empty, set `SslOptions.RemoteCertificateValidationCallback = (_,_,_,_) => true`. CA path keeps existing custom-root validation. | trivial |
+| Go | In `buildCredentials`, when TLS and no `CACertFile`/`TLSConfig`, use `tls.Config{InsecureSkipVerify: true, ServerName: override}`. | trivial |
+| Java | grpc-netty-shaded 1.76.0 ships `InsecureTrustManagerFactory`. When TLS and no CA, build `GrpcSslContexts.forClient().trustManager(InsecureTrustManagerFactory.INSTANCE)`. | easy |
+| Python | grpc-python has no per-channel skip-verify. Fetch the server leaf cert at connect via `ssl.get_server_certificate((host, port))`, pass it as `root_certificates` to `ssl_channel_credentials`, plus `grpc.ssl_target_name_override`. Effectively trusts what is presented (TOFU). | moderate, special-cased |
+| Rust | tonic 0.13.1 + rustls (`tls-ring`). Implement a custom `rustls::client::danger::ServerCertVerifier` that accepts everything, build a `rustls::ClientConfig` via `.dangerous().with_custom_certificate_verifier(...)`, feed it to the channel. May require a custom hyper-rustls connector if `ClientTlsConfig` will not take a raw rustls config. **Needs an API spike.** | highest |
+
+### Honesty caveats
+
+- **Python** is not literally "ignore the cert"; it pins whatever the server
+  presents on first contact via a separate unverified TLS probe. For a self-signed
+  internal cert this is the intended outcome. Documented as a difference.
+- **Rust** leniency depends on the tonic 0.13 TLS surface. If a custom verifier is
+  disproportionately invasive, the fallback is to require a CA file for Rust TLS
+  (pin-only) and document Rust as the exception.
+
+## Error handling
+
+Gateway:
+- Cert dir not writable / ACL fails ⇒ fail fast at startup with a diagnostic naming
+  the path and required permission. No silent in-memory fallback.
+- Persisted PFX corrupt/unreadable ⇒ warn, regenerate, overwrite.
+- Persisted cert expired ⇒ regenerate if `RegenerateIfExpired` (default), else fail
+  fast instructing the operator to delete it or enable regeneration.
+- HTTPS endpoint configured but generation disabled / path empty ⇒ validator
+  rejects at startup rather than letting Kestrel throw its opaque error.
+
+Clients: surface unchanged. Skip-verify cannot itself raise. Python's pre-fetch
+wraps connect failure into the existing connect-error type with the endpoint in the
+message. Rust pin-only fallback surfaces the existing CA-file error.
+
+## Documentation (same commit as source, per CLAUDE.md)
+
+- `docs/GatewayConfiguration.md` — extend the TLS section: auto-generation, the
+  `MxGateway:Tls:*` block, persistence location/ACL, thumbprint logging, operator
+  override via `Kestrel:Endpoints:*:Certificate`.
+- Each client README + `*ClientDesign.md` — "TLS is lenient by default; pin a CA to
+  verify," with Python TOFU and any Rust caveat noted.
+- `docs/DesignDecisions.md` — record both posture choices and the why (internal
+  tool, no PKI) so they are not mistaken for an oversight.
+
+## Testing
+
+Gateway (`MxGateway.Tests`, no MXAccess):
+- `SelfSignedCertificateProvider`: SANs, server-auth EKU, `notAfter ≈ now +
+  ValidityYears`, ECDSA P-256.
+- Load-or-create: valid persisted PFX reused (same thumbprint); expired regenerates
+  when enabled; corrupt regenerates with a warning.
+- Detection: HTTPS-without-cert engages; all-plaintext no-ops and writes no file;
+  endpoint with its own cert is not overridden.
+- `GatewayOptionsValidator`: new `Tls:*` rules.
+- Host integration: `Kestrel:Endpoints:Http:Url=https://127.0.0.1:0` builds and
+  binds (today it throws "no certificate specified").
+
+Clients: each test project gets a lenient-TLS test against a throwaway self-signed
+cert — connect with no CA succeeds; pinning a wrong CA fails (proves pinning still
+verifies). Python exercises the pre-fetch path; mark opt-in if loopback timing is
+flaky. Standard (non-live) tests; no MXAccess or external services.
+
+Cross-language: add a TLS variant note to `docs/CrossLanguageSmokeMatrix.md`;
+running the matrix over TLS stays manual/opt-in, consistent with the existing gate.
+
+Per-component verification follows CLAUDE.md's source-update table (build + test
+each touched component independently).
@@ -0,0 +1,18 @@
+{
+  "planPath": "docs/plans/2026-06-01-gateway-cert-autogen-implementation.md",
+  "tasks": [
+    {"id": 1, "subject": "Task 1: Add TlsOptions config + bind into GatewayOptions", "status": "pending"},
+    {"id": 2, "subject": "Task 2: Validate MxGateway:Tls in GatewayOptionsValidator", "status": "pending", "blockedBy": [1]},
+    {"id": 3, "subject": "Task 3: SelfSignedCertificateProvider.GenerateCertificate", "status": "pending", "blockedBy": [1]},
+    {"id": 4, "subject": "Task 4: SelfSignedCertificateProvider.LoadOrCreate (persist/reuse/regenerate/ACL)", "status": "pending", "blockedBy": [3]},
+    {"id": 5, "subject": "Task 5: KestrelTlsInspector (detect HTTPS-without-cert)", "status": "pending"},
+    {"id": 6, "subject": "Task 6: Wire auto-cert into GatewayApplication.CreateBuilder", "status": "pending", "blockedBy": [1, 4, 5]},
+    {"id": 7, "subject": "Task 7: .NET client lenient TLS by default", "status": "pending"},
+    {"id": 8, "subject": "Task 8: Go client lenient TLS by default", "status": "pending"},
+    {"id": 9, "subject": "Task 9: Java client lenient TLS by default", "status": "pending"},
+    {"id": 10, "subject": "Task 10: Python client lenient TLS via TOFU pre-fetch", "status": "pending"},
+    {"id": 11, "subject": "Task 11: Rust client lenient TLS via rustls verifier (spike + fallback)", "status": "pending"},
+    {"id": 12, "subject": "Task 12: Documentation", "status": "pending", "blockedBy": [6, 7, 8, 9, 10, 11]}
+  ],
+  "lastUpdated": "2026-06-01"
+}
@@ -43,4 +43,7 @@ public sealed class GatewayOptions
    /// behaviour (alarms disabled).
    /// </summary>
    public AlarmsOptions Alarms { get; init; } = new();
+
+    /// <summary>Gets self-signed TLS certificate auto-generation options.</summary>
+    public TlsOptions Tls { get; init; } = new();
 }
@@ -26,6 +26,7 @@ public sealed class GatewayOptionsValidator : IValidateOptions<GatewayOptions>
        ValidateDashboard(options.Dashboard, failures);
        ValidateProtocol(options.Protocol, failures);
        ValidateAlarms(options.Alarms, failures);
+        ValidateTls(options.Tls, failures);

        return failures.Count == 0
            ? ValidateOptionsResult.Success
@@ -262,6 +263,31 @@ public sealed class GatewayOptionsValidator : IValidateOptions<GatewayOptions>
        }
    }

+    private const int MinimumCertValidityYears = 1;
+    private const int MaximumCertValidityYears = 100;
+
+    private static void ValidateTls(TlsOptions options, List<string> failures)
+    {
+        if (options.ValidityYears is < MinimumCertValidityYears or > MaximumCertValidityYears)
+        {
+            failures.Add(
+                $"MxGateway:Tls:ValidityYears must be between {MinimumCertValidityYears} and {MaximumCertValidityYears}.");
+        }
+
+        AddIfInvalidPath(
+            options.SelfSignedCertPath,
+            "MxGateway:Tls:SelfSignedCertPath must be a valid filesystem path.",
+            failures);
+
+        foreach (string dns in options.AdditionalDnsNames)
+        {
+            if (string.IsNullOrWhiteSpace(dns))
+            {
+                failures.Add("MxGateway:Tls:AdditionalDnsNames entries must be non-blank.");
+            }
+        }
+    }
+
    private static void ValidateProtocol(ProtocolOptions options, List<string> failures)
    {
        if (options.WorkerProtocolVersion != GatewayContractInfo.WorkerProtocolVersion)
@@ -0,0 +1,22 @@
+namespace ZB.MOM.WW.MxGateway.Server.Configuration;
+
+/// <summary>
+/// Options controlling the gateway's self-signed certificate auto-generation.
+/// Only consulted when a Kestrel HTTPS endpoint is configured without its own
+/// certificate; plaintext deployments never trigger generation.
+/// </summary>
+public sealed class TlsOptions
+{
+    /// <summary>Path to the persisted self-signed PFX. Reused across restarts.</summary>
+    public string SelfSignedCertPath { get; init; } =
+        @"C:\ProgramData\MxGateway\certs\gateway-selfsigned.pfx";
+
+    /// <summary>Lifetime in years of a freshly generated certificate.</summary>
+    public int ValidityYears { get; init; } = 10;
+
+    /// <summary>Extra DNS SANs to embed (e.g. a load-balancer name).</summary>
+    public IReadOnlyList<string> AdditionalDnsNames { get; init; } = [];
+
+    /// <summary>Regenerate the persisted certificate when it has expired.</summary>
+    public bool RegenerateIfExpired { get; init; } = true;
+}
@@ -1,64 +0,0 @@
-using ZB.MOM.WW.Telemetry.Serilog;
-
-namespace ZB.MOM.WW.MxGateway.Server.Diagnostics;
-
-/// <summary>
-/// Bridges the gateway's <see cref="GatewayLogRedactor"/> policy onto the shared
-/// <see cref="ILogRedactor"/> seam consumed by <c>ZB.MOM.WW.Telemetry.Serilog</c>'s redaction
-/// enricher. Applied to every Serilog log event before it reaches a sink, it masks the same
-/// secrets the original MEL-scope path masked: API-key bearer tokens / client identities
-/// (<c>mxgw_*</c>) and command values for credential-bearing MXAccess commands. All masking
-/// decisions delegate to <see cref="GatewayLogRedactor"/> — this type adds no new policy.
-/// </summary>
-public sealed class GatewayLogRedactorAdapter : ILogRedactor
-{
-    /// <summary>Property name carrying a client identity / authorization header value.</summary>
-    private const string ClientIdentityProperty = "ClientIdentity";
-
-    /// <summary>Property name carrying a raw authorization header value.</summary>
-    private const string AuthorizationProperty = "Authorization";
-
-    /// <summary>Property name carrying the MXAccess command method, used to gate value redaction.</summary>
-    private const string CommandMethodProperty = "CommandMethod";
-
-    /// <summary>Property name carrying a command payload value that may bear credentials.</summary>
-    private const string CommandValueProperty = "CommandValue";
-
-    /// <summary>
-    /// Masks any sensitive values in <paramref name="properties"/> in place using the shared
-    /// <see cref="GatewayLogRedactor"/> policy. Identity/authorization properties have their API-key
-    /// secret stripped; a command value is redacted when its associated command method bears
-    /// credentials.
-    /// </summary>
-    /// <param name="properties">The mutable log-event property dictionary for the current event.</param>
-    public void Redact(IDictionary<string, object?> properties)
-    {
-        ArgumentNullException.ThrowIfNull(properties);
-
-        RedactIdentity(properties, ClientIdentityProperty);
-        RedactIdentity(properties, AuthorizationProperty);
-        RedactCommandValue(properties);
-    }
-
-    private static void RedactIdentity(IDictionary<string, object?> properties, string propertyName)
-    {
-        if (properties.TryGetValue(propertyName, out object? value) && value is string identity)
-        {
-            properties[propertyName] = GatewayLogRedactor.RedactClientIdentity(identity);
-        }
-    }
-
-    private static void RedactCommandValue(IDictionary<string, object?> properties)
-    {
-        if (!properties.TryGetValue(CommandValueProperty, out object? value) || value is null)
-        {
-            return;
-        }
-
-        string? commandMethod = properties.TryGetValue(CommandMethodProperty, out object? method)
-            ? method as string
-            : null;
-
-        properties[CommandValueProperty] = GatewayLogRedactor.RedactCommandValue(commandMethod, value);
-    }
-}
@@ -0,0 +1,20 @@
+using Microsoft.Extensions.Logging;
+
+namespace ZB.MOM.WW.MxGateway.Server.Diagnostics;
+
+public static class GatewayLoggerExtensions
+{
+    /// <summary>Begins a gateway log scope with the specified scope properties.</summary>
+    /// <param name="logger">Logger used for diagnostic output.</param>
+    /// <param name="scope">Scope properties to apply.</param>
+    /// <returns>A disposable that ends the scope when disposed.</returns>
+    public static IDisposable? BeginGatewayScope(
+        this ILogger logger,
+        GatewayLogScope scope)
+    {
+        ArgumentNullException.ThrowIfNull(logger);
+        ArgumentNullException.ThrowIfNull(scope);
+
+        return logger.BeginScope(scope.ToDictionary());
+    }
+}
@@ -1,5 +1,4 @@
 using Microsoft.Extensions.Primitives;
-using Serilog.Context;

 namespace ZB.MOM.WW.MxGateway.Server.Diagnostics;

@@ -18,12 +17,7 @@ public static class GatewayRequestLoggingMiddlewareExtensions
    /// <summary>Header name for the command method name.</summary>
    public const string CommandMethodHeaderName = "x-command-method";

-    /// <summary>
-    /// Adds gateway request logging middleware that reads the correlation headers and pushes them
-    /// as Serilog <see cref="LogContext"/> properties for the duration of the request. The pushed
-    /// properties (SessionId / WorkerProcessId / CorrelationId / CommandMethod / ClientIdentity)
-    /// are disposed when the request completes; the shared redaction enricher masks any secrets.
-    /// </summary>
+    /// <summary>Adds gateway request logging scope middleware that reads correlation headers and redacts sensitive data.</summary>
    /// <param name="app">Application builder.</param>
    public static IApplicationBuilder UseGatewayRequestLoggingScope(this IApplicationBuilder app)
    {
@@ -31,56 +25,21 @@ public static class GatewayRequestLoggingMiddlewareExtensions

        return app.Use(async (context, next) =>
        {
-            GatewayLogScope scope = new(
+            ILogger logger = context.RequestServices
+                .GetRequiredService<ILoggerFactory>()
+                .CreateLogger("MxGateway.Request");
+
+            using IDisposable? scope = logger.BeginGatewayScope(new GatewayLogScope(
                SessionId: ReadHeader(context, SessionIdHeaderName),
                WorkerProcessId: ReadInt32Header(context, WorkerProcessIdHeaderName),
                CorrelationId: ReadUInt64Header(context, CorrelationIdHeaderName),
                CommandMethod: ReadHeader(context, CommandMethodHeaderName),
-                ClientIdentity: ReadHeader(context, "authorization"));
-
-            using IDisposable correlationScope = PushCorrelationProperties(scope);
+                ClientIdentity: ReadHeader(context, "authorization")));

            await next(context);
        });
    }

-    /// <summary>
-    /// Pushes the populated <paramref name="scope"/> properties onto the Serilog
-    /// <see cref="LogContext"/>, returning a single disposable that pops them all when the request
-    /// completes. Only the properties present in <see cref="GatewayLogScope.ToDictionary"/> (which
-    /// already applies the client-identity redaction policy) are pushed.
-    /// </summary>
-    /// <param name="scope">The correlation properties for the current request.</param>
-    /// <returns>A disposable that removes the pushed properties on disposal.</returns>
-    private static IDisposable PushCorrelationProperties(GatewayLogScope scope)
-    {
-        Stack<IDisposable> pushed = new();
-
-        foreach (KeyValuePair<string, object?> property in scope.ToDictionary())
-        {
-            pushed.Push(LogContext.PushProperty(property.Key, property.Value));
-        }
-
-        return new CorrelationPropertyScope(pushed);
-    }
-
-    /// <summary>
-    /// Disposes the pushed <see cref="LogContext"/> property bindings in reverse order, restoring
-    /// the ambient context to its pre-request state.
-    /// </summary>
-    private sealed class CorrelationPropertyScope(Stack<IDisposable> bindings) : IDisposable
-    {
-        private readonly Stack<IDisposable> _bindings = bindings;
-
-        public void Dispose()
-        {
-            while (_bindings.Count > 0)
-            {
-                _bindings.Pop().Dispose();
-            }
-        }
-    }
-
    private static string? ReadHeader(HttpContext context, string headerName)
    {
        return context.Request.Headers.TryGetValue(headerName, out StringValues values)
@@ -1,5 +1,4 @@
 using Microsoft.AspNetCore.Hosting.StaticWebAssets;
-using Serilog;
 using ZB.MOM.WW.MxGateway.Contracts;
 using ZB.MOM.WW.MxGateway.Server.Alarms;
 using ZB.MOM.WW.MxGateway.Server.Configuration;
@@ -12,7 +11,6 @@ using ZB.MOM.WW.MxGateway.Server.Security.Authentication;
 using ZB.MOM.WW.MxGateway.Server.Security.Authorization;
 using ZB.MOM.WW.MxGateway.Server.Sessions;
 using ZB.MOM.WW.MxGateway.Server.Workers;
-using ZB.MOM.WW.Telemetry.Serilog;

 namespace ZB.MOM.WW.MxGateway.Server;

@@ -33,10 +31,7 @@ public static class GatewayApplication
        WebApplicationBuilder builder = CreateBuilder(args);
        WebApplication app = builder.Build();

-        // Push the per-request correlation properties (via Serilog LogContext) before the
-        // request-logging middleware emits its completion event, so those properties appear on it.
        app.UseGatewayRequestLoggingScope();
-        app.UseSerilogRequestLogging();
        app.UseStaticFiles();
        app.UseAuthentication();
        app.UseAuthorization();
@@ -60,8 +55,6 @@ public static class GatewayApplication
        });
        StaticWebAssetsLoader.UseStaticWebAssets(builder.Environment, builder.Configuration);

-        ConfigureSerilog(builder);
-
        builder.Services.AddGatewayConfiguration();
        builder.Services.AddSqliteAuthStore();
        builder.Services.AddGatewayGrpcAuthorization();
@@ -79,30 +72,6 @@ public static class GatewayApplication
        return builder;
    }

-    /// <summary>
-    /// Replaces the default Microsoft.Extensions.Logging provider with the shared
-    /// <c>ZB.MOM.WW.Telemetry.Serilog</c> bootstrap (<see cref="ZbSerilogExtensions.AddZbSerilog"/>).
-    /// Sinks and minimum level come from the <c>Serilog</c> configuration section; identity
-    /// (<c>SiteId</c>/<c>NodeRole</c>) is read from <c>MxGateway:Telemetry</c> when present.
-    /// Also registers the project's <see cref="ILogRedactor"/> adapter so the shared redaction
-    /// enricher masks gateway secrets on every event.
-    /// </summary>
-    /// <param name="builder">The web application builder being configured.</param>
-    private static void ConfigureSerilog(WebApplicationBuilder builder)
-    {
-        string? siteId = builder.Configuration["MxGateway:Telemetry:SiteId"];
-        string? nodeRole = builder.Configuration["MxGateway:Telemetry:NodeRole"];
-
-        builder.Services.AddSingleton<ILogRedactor, GatewayLogRedactorAdapter>();
-
-        builder.AddZbSerilog(options =>
-        {
-            options.ServiceName = "mxgateway";
-            options.SiteId = string.IsNullOrWhiteSpace(siteId) ? null : siteId;
-            options.NodeRole = string.IsNullOrWhiteSpace(nodeRole) ? null : nodeRole;
-        });
-    }
-
    private static string ResolveContentRootPath()
    {
        string? configuredContentRootPath = Environment.GetEnvironmentVariable("ASPNETCORE_CONTENTROOT");
@@ -0,0 +1,45 @@
+using Microsoft.Extensions.Configuration;
+
+namespace ZB.MOM.WW.MxGateway.Server.Security.Tls;
+
+/// <summary>
+/// Inspects the Kestrel configuration to decide whether the gateway must supply
+/// a generated default certificate (an HTTPS endpoint exists with no certificate
+/// of its own).
+/// </summary>
+public static class KestrelTlsInspector
+{
+    /// <summary>
+    /// Returns <see langword="true"/> when at least one HTTPS endpoint in
+    /// <c>Kestrel:Endpoints</c> has no certificate of its own (no
+    /// <c>Certificate:Path</c>, <c>Certificate:Subject</c>, or
+    /// <c>Certificate:Thumbprint</c>), meaning the gateway must supply a
+    /// generated fallback certificate.
+    /// </summary>
+    public static bool RequiresGeneratedCertificate(IConfiguration configuration)
+    {
+        IConfigurationSection endpoints = configuration.GetSection("Kestrel:Endpoints");
+        foreach (IConfigurationSection endpoint in endpoints.GetChildren())
+        {
+            string? url = endpoint["Url"];
+            if (string.IsNullOrWhiteSpace(url) ||
+                !url.StartsWith("https://", StringComparison.OrdinalIgnoreCase))
+            {
+                continue;
+            }
+
+            IConfigurationSection certificate = endpoint.GetSection("Certificate");
+            bool hasOwnCertificate =
+                !string.IsNullOrWhiteSpace(certificate["Path"]) ||
+                !string.IsNullOrWhiteSpace(certificate["Subject"]) ||
+                !string.IsNullOrWhiteSpace(certificate["Thumbprint"]);
+
+            if (!hasOwnCertificate)
+            {
+                return true;
+            }
+        }
+
+        return false;
+    }
+}
@@ -0,0 +1,71 @@
+using System.Net;
+using System.Security.Cryptography;
+using System.Security.Cryptography.X509Certificates;
+using Microsoft.Extensions.Logging;
+using ZB.MOM.WW.MxGateway.Server.Configuration;
+
+namespace ZB.MOM.WW.MxGateway.Server.Security.Tls;
+
+/// <summary>
+/// Generates and persists a long-lived self-signed certificate used as the
+/// Kestrel HTTPS default when no operator certificate is configured.
+/// </summary>
+public sealed class SelfSignedCertificateProvider
+{
+    private const string ServerAuthOid = "1.3.6.1.5.5.7.3.1";
+
+    private readonly TlsOptions _options;
+    private readonly ILogger<SelfSignedCertificateProvider> _logger;
+    private readonly TimeProvider _timeProvider;
+
+    public SelfSignedCertificateProvider(
+        TlsOptions options,
+        ILogger<SelfSignedCertificateProvider> logger,
+        TimeProvider timeProvider)
+    {
+        _options = options;
+        _logger = logger;
+        _timeProvider = timeProvider;
+    }
+
+    /// <summary>Creates a fresh in-memory ECDSA P-256 self-signed certificate.</summary>
+    public X509Certificate2 GenerateCertificate()
+    {
+        using ECDsa key = ECDsa.Create(ECCurve.NamedCurves.nistP256);
+        CertificateRequest request = new(
+            new X500DistinguishedName("CN=MxAccessGateway Self-Signed"),
+            key,
+            HashAlgorithmName.SHA256);
+
+        request.CertificateExtensions.Add(new X509BasicConstraintsExtension(false, false, 0, true));
+        request.CertificateExtensions.Add(new X509KeyUsageExtension(
+            X509KeyUsageFlags.DigitalSignature | X509KeyUsageFlags.KeyEncipherment,
+            critical: true));
+        request.CertificateExtensions.Add(new X509EnhancedKeyUsageExtension(
+            [new Oid(ServerAuthOid, "Server Authentication")],
+            critical: false));
+
+        SubjectAlternativeNameBuilder san = new();
+        san.AddDnsName("localhost");
+        string machine = Environment.MachineName;
+        if (!string.IsNullOrWhiteSpace(machine))
+        {
+            san.AddDnsName(machine);
+        }
+
+        foreach (string extra in _options.AdditionalDnsNames)
+        {
+            if (!string.IsNullOrWhiteSpace(extra))
+            {
+                san.AddDnsName(extra);
+            }
+        }
+
+        san.AddIpAddress(IPAddress.Loopback);
+        san.AddIpAddress(IPAddress.IPv6Loopback);
+        request.CertificateExtensions.Add(san.Build());
+
+        DateTimeOffset now = _timeProvider.GetUtcNow();
+        return request.CreateSelfSigned(now.AddDays(-1), now.AddYears(_options.ValidityYears));
+    }
+}
@@ -15,13 +15,6 @@

  <ItemGroup>
    <ProjectReference Include="..\ZB.MOM.WW.MxGateway.Contracts\ZB.MOM.WW.MxGateway.Contracts.csproj" />
-    <!--
-      Shared structured-logging bootstrap (ZB.MOM.WW.Telemetry.Serilog) lives in the sibling
-      scadaproj workspace. Cross-repo ProjectReference: the referenced project resolves its own
-      Directory.Build.props / Directory.Packages.props from its own tree, so it does not perturb
-      this repo's build settings. It transitively brings the ZB.MOM.WW.Telemetry core package.
-    -->
-    <ProjectReference Include="..\..\..\scadaproj\ZB.MOM.WW.Telemetry\src\ZB.MOM.WW.Telemetry.Serilog\ZB.MOM.WW.Telemetry.Serilog.csproj" />
  </ItemGroup>

 </Project>
@@ -1,10 +1,8 @@
 {
-  "Serilog": {
-    "MinimumLevel": {
+  "Logging": {
+    "LogLevel": {
      "Default": "Information",
-      "Override": {
-        "Microsoft.AspNetCore": "Warning"
-      }
+      "Microsoft.AspNetCore": "Warning"
    }
  }
 }
@@ -1,30 +1,9 @@
 {
-  "Serilog": {
-    "Using": [
-      "Serilog.Sinks.Console",
-      "Serilog.Sinks.File"
-    ],
-    "MinimumLevel": {
+  "Logging": {
+    "LogLevel": {
      "Default": "Information",
-      "Override": {
-        "Microsoft.AspNetCore": "Warning"
-      }
-    },
-    "WriteTo": [
-      {
-        "Name": "Console",
-        "Args": {
-          "outputTemplate": "[{Timestamp:HH:mm:ss} {Level:u3}] [{NodeRole}/{NodeHostname}] {Message:lj} {Properties:j}{NewLine}{Exception}"
-        }
-      },
-      {
-        "Name": "File",
-        "Args": {
-          "path": "logs/mxgateway-.log",
-          "rollingInterval": "Day"
-        }
-      }
-    ]
+      "Microsoft.AspNetCore": "Warning"
+    }
  },
  "AllowedHosts": "*",
  "MxGateway": {
@@ -0,0 +1,59 @@
+using Microsoft.Extensions.Options;
+using ZB.MOM.WW.MxGateway.Server.Configuration;
+
+namespace ZB.MOM.WW.MxGateway.Tests.Configuration;
+
+public sealed class GatewayOptionsValidatorTests
+{
+    // Constructs the minimal valid GatewayOptions by relying on each sub-option's
+    // design-default values; those defaults are validated separately in GatewayOptionsTests.
+    private static GatewayOptions ValidOptions() => new();
+
+    private static GatewayOptions CloneWithTls(GatewayOptions source, TlsOptions tls)
+        => new()
+        {
+            Authentication = source.Authentication,
+            Ldap = source.Ldap,
+            Worker = source.Worker,
+            Sessions = source.Sessions,
+            Events = source.Events,
+            Dashboard = source.Dashboard,
+            Protocol = source.Protocol,
+            Alarms = source.Alarms,
+            Tls = tls,
+        };
+
+    [Fact]
+    public void Validate_Succeeds_WithDefaultTlsOptions()
+    {
+        ValidateOptionsResult result = new GatewayOptionsValidator().Validate(null, ValidOptions());
+        Assert.True(result.Succeeded);
+    }
+
+    [Fact]
+    public void Validate_Fails_WhenTlsValidityYearsOutOfRange()
+    {
+        GatewayOptions withBadTls = CloneWithTls(ValidOptions(), new TlsOptions { ValidityYears = 0 });
+        ValidateOptionsResult result = new GatewayOptionsValidator().Validate(null, withBadTls);
+        Assert.True(result.Failed);
+        Assert.Contains(result.Failures!, f => f.Contains("MxGateway:Tls:ValidityYears"));
+    }
+
+    [Fact]
+    public void Validate_Fails_WhenTlsValidityYearsTooLarge()
+    {
+        GatewayOptions withBadTls = CloneWithTls(ValidOptions(), new TlsOptions { ValidityYears = 101 });
+        ValidateOptionsResult result = new GatewayOptionsValidator().Validate(null, withBadTls);
+        Assert.True(result.Failed);
+        Assert.Contains(result.Failures!, f => f.Contains("MxGateway:Tls:ValidityYears"));
+    }
+
+    [Fact]
+    public void Validate_Fails_WhenAdditionalDnsNameBlank()
+    {
+        GatewayOptions options = CloneWithTls(ValidOptions(), new TlsOptions { AdditionalDnsNames = [" "] });
+        ValidateOptionsResult result = new GatewayOptionsValidator().Validate(null, options);
+        Assert.True(result.Failed);
+        Assert.Contains(result.Failures!, f => f.Contains("MxGateway:Tls:AdditionalDnsNames"));
+    }
+}
@@ -0,0 +1,39 @@
+using Microsoft.Extensions.Configuration;
+using ZB.MOM.WW.MxGateway.Server.Configuration;
+using Xunit;
+
+namespace ZB.MOM.WW.MxGateway.Tests.Configuration;
+
+public sealed class TlsOptionsBindingTests
+{
+    [Fact]
+    public void Defaults_AreApplied_WhenSectionAbsent()
+    {
+        TlsOptions options = new();
+        Assert.Equal(10, options.ValidityYears);
+        Assert.True(options.RegenerateIfExpired);
+        Assert.Empty(options.AdditionalDnsNames);
+        Assert.False(string.IsNullOrWhiteSpace(options.SelfSignedCertPath));
+    }
+
+    [Fact]
+    public void Binds_FromMxGatewayTlsSection()
+    {
+        IConfiguration config = new ConfigurationBuilder()
+            .AddInMemoryCollection(new Dictionary<string, string?>
+            {
+                ["MxGateway:Tls:ValidityYears"] = "5",
+                ["MxGateway:Tls:SelfSignedCertPath"] = @"C:\tmp\gw.pfx",
+                ["MxGateway:Tls:RegenerateIfExpired"] = "false",
+                ["MxGateway:Tls:AdditionalDnsNames:0"] = "gw.internal",
+            })
+            .Build();
+
+        GatewayOptions options = config.GetSection(GatewayOptions.SectionName).Get<GatewayOptions>()!;
+
+        Assert.Equal(5, options.Tls.ValidityYears);
+        Assert.Equal(@"C:\tmp\gw.pfx", options.Tls.SelfSignedCertPath);
+        Assert.False(options.Tls.RegenerateIfExpired);
+        Assert.Equal("gw.internal", Assert.Single(options.Tls.AdditionalDnsNames));
+    }
+}
@@ -1,92 +0,0 @@
-using ZB.MOM.WW.MxGateway.Server.Diagnostics;
-using ZB.MOM.WW.Telemetry.Serilog;
-
-namespace ZB.MOM.WW.MxGateway.Tests.Diagnostics;
-
-/// <summary>
-/// Pins that <see cref="GatewayLogRedactorAdapter"/> applies the gateway's redaction policy through
-/// the shared <see cref="ILogRedactor"/> seam — the same secrets the former MEL-scope path masked
-/// must still be masked once events flow through the Serilog redaction enricher.
-/// </summary>
-public sealed class GatewayLogRedactorAdapterTests
-{
-    private readonly ILogRedactor _redactor = new GatewayLogRedactorAdapter();
-
-    /// <summary>Verifies the client identity property has its API-key secret stripped in place.</summary>
-    [Fact]
-    public void Redact_StripsApiKeySecretFromClientIdentity()
-    {
-        Dictionary<string, object?> properties = new()
-        {
-            ["ClientIdentity"] = "Bearer mxgw_operator01_super-secret",
-        };
-
-        _redactor.Redact(properties);
-
-        Assert.Equal("Bearer mxgw_operator01_[redacted]", properties["ClientIdentity"]);
-        Assert.DoesNotContain("super-secret", (string?)properties["ClientIdentity"]);
-    }
-
-    /// <summary>Verifies a raw authorization header property is redacted too.</summary>
-    [Fact]
-    public void Redact_StripsApiKeySecretFromAuthorizationProperty()
-    {
-        Dictionary<string, object?> properties = new()
-        {
-            ["Authorization"] = "Bearer mxgw_admin_top-secret",
-        };
-
-        _redactor.Redact(properties);
-
-        Assert.Equal("Bearer mxgw_admin_[redacted]", properties["Authorization"]);
-    }
-
-    /// <summary>Verifies a command value is redacted for a credential-bearing command method.</summary>
-    [Fact]
-    public void Redact_RedactsCommandValueForCredentialBearingCommand()
-    {
-        Dictionary<string, object?> properties = new()
-        {
-            ["CommandMethod"] = "WriteSecured",
-            ["CommandValue"] = "credential-bearing-value",
-        };
-
-        _redactor.Redact(properties);
-
-        Assert.Equal(GatewayLogRedactor.RedactedValue, properties["CommandValue"]);
-    }
-
-    /// <summary>Verifies a command value is redacted by default (value logging disabled) for any command.</summary>
-    [Fact]
-    public void Redact_RedactsCommandValueByDefault()
-    {
-        Dictionary<string, object?> properties = new()
-        {
-            ["CommandMethod"] = "Write",
-            ["CommandValue"] = "plaintext-tag-value",
-        };
-
-        _redactor.Redact(properties);
-
-        Assert.Equal(GatewayLogRedactor.RedactedValue, properties["CommandValue"]);
-    }
-
-    /// <summary>Verifies non-sensitive properties are left untouched.</summary>
-    [Fact]
-    public void Redact_LeavesNonSensitivePropertiesUnchanged()
-    {
-        Dictionary<string, object?> properties = new()
-        {
-            ["SessionId"] = "session-1",
-            ["CorrelationId"] = (ulong)99,
-            ["ClientIdentity"] = "Bearer plain-token-no-marker",
-        };
-
-        _redactor.Redact(properties);
-
-        Assert.Equal("session-1", properties["SessionId"]);
-        Assert.Equal((ulong)99, properties["CorrelationId"]);
-        // No mxgw_ marker — identity passes through unchanged.
-        Assert.Equal("Bearer plain-token-no-marker", properties["ClientIdentity"]);
-    }
-}
@@ -0,0 +1,61 @@
+using Microsoft.Extensions.Configuration;
+using ZB.MOM.WW.MxGateway.Server.Security.Tls;
+using Xunit;
+
+namespace ZB.MOM.WW.MxGateway.Tests.Security.Tls;
+
+public sealed class KestrelTlsInspectorTests
+{
+    private static IConfiguration Config(params (string Key, string Value)[] entries)
+        => new ConfigurationBuilder()
+            .AddInMemoryCollection(entries.ToDictionary(e => e.Key, e => (string?)e.Value))
+            .Build();
+
+    [Fact]
+    public void RequiresGeneratedCertificate_True_WhenHttpsEndpointHasNoCertificate()
+        => Assert.True(KestrelTlsInspector.RequiresGeneratedCertificate(
+            Config(("Kestrel:Endpoints:Http:Url", "https://0.0.0.0:5120"))));
+
+    [Fact]
+    public void RequiresGeneratedCertificate_False_WhenAllEndpointsPlaintext()
+        => Assert.False(KestrelTlsInspector.RequiresGeneratedCertificate(
+            Config(("Kestrel:Endpoints:Http:Url", "http://0.0.0.0:5120"))));
+
+    [Fact]
+    public void RequiresGeneratedCertificate_False_WhenHttpsEndpointHasOwnCertificate()
+        => Assert.False(KestrelTlsInspector.RequiresGeneratedCertificate(
+            Config(
+                ("Kestrel:Endpoints:Http:Url", "https://0.0.0.0:5120"),
+                ("Kestrel:Endpoints:Http:Certificate:Path", @"C:\certs\real.pfx"))));
+
+    [Fact]
+    public void RequiresGeneratedCertificate_False_WhenNoEndpointsConfigured()
+        => Assert.False(KestrelTlsInspector.RequiresGeneratedCertificate(Config()));
+
+    [Fact]
+    public void RequiresGeneratedCertificate_False_WhenHttpsEndpointHasThumbprintOnly()
+        => Assert.False(KestrelTlsInspector.RequiresGeneratedCertificate(
+            Config(
+                ("Kestrel:Endpoints:Https:Url", "https://0.0.0.0:5120"),
+                ("Kestrel:Endpoints:Https:Certificate:Thumbprint", "AABBCCDDEEFF00112233445566778899AABBCCDD"))));
+
+    [Fact]
+    public void RequiresGeneratedCertificate_False_WhenHttpsEndpointHasSubjectOnly()
+        => Assert.False(KestrelTlsInspector.RequiresGeneratedCertificate(
+            Config(
+                ("Kestrel:Endpoints:Https:Url", "https://0.0.0.0:5120"),
+                ("Kestrel:Endpoints:Https:Certificate:Subject", "CN=myserver"))));
+
+    [Fact]
+    public void RequiresGeneratedCertificate_True_WhenHttpsUrlIsUppercase()
+        => Assert.True(KestrelTlsInspector.RequiresGeneratedCertificate(
+            Config(("Kestrel:Endpoints:Https:Url", "HTTPS://0.0.0.0:5120"))));
+
+    [Fact]
+    public void RequiresGeneratedCertificate_True_WhenMixedEndpointsAndOneHttpsHasNoCert()
+        => Assert.True(KestrelTlsInspector.RequiresGeneratedCertificate(
+            Config(
+                ("Kestrel:Endpoints:Grpc:Url", "https://0.0.0.0:5120"),
+                ("Kestrel:Endpoints:Grpc:Certificate:Thumbprint", "AABBCCDDEEFF00112233445566778899AABBCCDD"),
+                ("Kestrel:Endpoints:Dashboard:Url", "https://0.0.0.0:5130"))));
+}
@@ -0,0 +1,40 @@
+using System.Security.Cryptography.X509Certificates;
+using Microsoft.Extensions.Logging.Abstractions;
+using Microsoft.Extensions.Time.Testing;
+using ZB.MOM.WW.MxGateway.Server.Configuration;
+using ZB.MOM.WW.MxGateway.Server.Security.Tls;
+using Xunit;
+
+namespace ZB.MOM.WW.MxGateway.Tests.Security.Tls;
+
+public sealed class SelfSignedCertificateProviderTests
+{
+    private static SelfSignedCertificateProvider CreateProvider(TlsOptions options, FakeTimeProvider time)
+        => new(options, NullLogger<SelfSignedCertificateProvider>.Instance, time);
+
+    [Fact]
+    public void GenerateCertificate_HasExpectedSansEkuAndValidity()
+    {
+        FakeTimeProvider time = new(new DateTimeOffset(2026, 1, 1, 0, 0, 0, TimeSpan.Zero));
+        TlsOptions options = new() { ValidityYears = 7, AdditionalDnsNames = ["gw.internal"] };
+
+        using X509Certificate2 cert = CreateProvider(options, time).GenerateCertificate();
+
+        Assert.Equal(time.GetUtcNow().AddYears(7).UtcDateTime.Date, cert.NotAfter.ToUniversalTime().Date);
+        Assert.True(cert.NotBefore.ToUniversalTime() < time.GetUtcNow().UtcDateTime);
+        Assert.True(cert.HasPrivateKey);
+
+        string sans = ReadSubjectAltNames(cert);
+        Assert.Contains("localhost", sans);
+        Assert.Contains("gw.internal", sans);
+
+        X509EnhancedKeyUsageExtension eku = cert.Extensions.OfType<X509EnhancedKeyUsageExtension>().Single();
+        Assert.Contains(eku.EnhancedKeyUsages.Cast<System.Security.Cryptography.Oid>(),
+            o => o.Value == "1.3.6.1.5.5.7.3.1"); // serverAuth
+    }
+
+    private static string ReadSubjectAltNames(X509Certificate2 cert)
+        => cert.Extensions
+            .First(e => e.Oid?.Value == "2.5.29.17")
+            .Format(false);
+}
@@ -7,6 +7,7 @@

  <ItemGroup>
    <PackageReference Include="coverlet.collector" Version="6.0.4" />
+    <PackageReference Include="Microsoft.Extensions.TimeProvider.Testing" Version="10.0.0" />
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
    <PackageReference Include="xunit" Version="2.9.3" />
    <PackageReference Include="xunit.runner.visualstudio" Version="3.1.4" />
Author	SHA1	Message	Date
Joseph Doherty	192607ab8c	fix(gateway): detect Certificate:Thumbprint and cover more KestrelTlsInspector cases	2026-06-01 07:22:24 -04:00
Joseph Doherty	ba82afe669	fix(client-java): keep Temurin 21 toolchain, auto-provision instead of bumping to 26	2026-06-01 07:20:04 -04:00
Joseph Doherty	fe7d1ce1ec	feat(gateway): validate MxGateway:Tls options	2026-06-01 07:19:22 -04:00
Joseph Doherty	b8a6695612	feat(gateway): generate self-signed ECDSA cert with SANs	2026-06-01 07:18:39 -04:00
Joseph Doherty	6f9188bc8d	test(client-python): update TLS default-channel test for TOFU behavior	2026-06-01 07:17:36 -04:00
Joseph Doherty	a276f46f81	feat(client-java): accept gateway cert by default over TLS	2026-06-01 07:13:45 -04:00
Joseph Doherty	572b268d81	feat(client-rust): accept gateway cert by default over TLS (or documented pin-only fallback)	2026-06-01 07:11:09 -04:00
Joseph Doherty	4c093a64fa	feat(client-python): accept gateway cert by default via TOFU pre-fetch	2026-06-01 07:10:55 -04:00
Joseph Doherty	f47bbaea95	feat(client-dotnet): accept gateway cert by default over TLS	2026-06-01 07:08:55 -04:00
Joseph Doherty	c463b49f46	feat(client-go): accept gateway cert by default over TLS	2026-06-01 07:08:47 -04:00
Joseph Doherty	87f86503ef	feat(gateway): add MxGateway:Tls options block	2026-06-01 07:08:19 -04:00
Joseph Doherty	e912ef960c	feat(gateway): detect HTTPS endpoints missing a certificate	2026-06-01 07:08:12 -04:00
Joseph Doherty	c4e7ddea70	docs: implementation plan for gateway TLS auto-cert and lenient client trust	2026-06-01 07:01:58 -04:00
Joseph Doherty	6bfa4fe884	docs: design for gateway TLS auto-cert and lenient client trust	2026-06-01 06:54:23 -04:00