fix(CLI-40,CLI-41,CLI-44): exact-secret scrub, uniform malformed-reply contract, Go terminal-error mislabel

CLI-40: port the exact-secret credential scrub to Rust/Java/.NET (Go/Python
already did it). AuthenticateUser/WriteSecured(2) helpers now redact the exact
caller-supplied secret from any surfaced error, as defense-in-depth on top of the
by-construction guarantee. Rust hand-writes a redacting Debug (derived Debug would
leak the reply); Java/.NET rebuild the same exception type with the redacted
message and do not carry the secret-bearing original forward (so ToString/stack
traces stay clean too).

CLI-41: uniform malformed-reply contract for AuthenticateUser/ArchestrAUserToId/
AddBufferedItem across all five clients — typed payload, else a present int32
return_value, else a typed malformed-reply error. Fixes Go/Java silent-0, .NET
NRE, and Rust's own internal inconsistency.

CLI-44: the Go event goroutine's Recv-error path now uses a non-blocking
sendTerminalEventResult on the reserved slot, so a genuine terminal stream error
is reported as itself instead of being mislabeled ErrSlowConsumer under overflow.

Riders from the CLI-37/38 review: (a) .NET ToDiagnosticSummary and Python
_mxaccess_message surface the raw success member (diagnostics-only parity with
Rust); (b) the status-conversion fixture carries an independent wantSuccess
boolean and the Go/.NET fixture tests assert against it instead of recomputing
the formula under test.

Shared fixtures (authenticate-user.{echoed-credential,missing-payload,
return-value-only}.reply.json) + manifest + ClientBehaviorFixtures.md +
ClientLibrariesDesign.md updated in the same change. Tracking: CLI-40/41/44 -> Done.

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/MxGatewaySessionReplyContractTests.cs

@@ -0,0 +1,127 @@
+using Google.Protobuf;
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
+
+namespace ZB.MOM.WW.MxGateway.Client.Tests;
+
+/// <summary>
+/// Tests for the credential-scrub (CLI-40) and malformed-reply (CLI-41) contracts on the
+/// credential and id-returning session helpers, driven from shared behavior fixtures.
+/// </summary>
+public sealed class MxGatewaySessionReplyContractTests
+{
+    /// <summary>
+    /// CLI-40: when MXAccess echoes the submitted credential back in its failure diagnostic,
+    /// the surfaced exception message must scrub it to the library redaction marker.
+    /// </summary>
+    [Fact]
+    public async Task AuthenticateUserAsync_RedactsEchoedCredentialInFailureMessage()
+    {
+        const string password = "sup3rSecretVerify9f3a2b";
+        FakeGatewayTransport transport = CreateTransport();
+        transport.AddInvokeReply(ReadReplyFixture("authenticate-user.echoed-credential.reply.json"));
+        await using MxGatewayClient client = CreateClient(transport);
+        MxGatewaySession session = await client.OpenSessionAsync();
+
+        MxAccessException exception = await Assert.ThrowsAsync<MxAccessException>(
+            async () => await session.AuthenticateUserAsync(12, "operator", password));
+
+        Assert.DoesNotContain(password, exception.Message, StringComparison.Ordinal);
+        Assert.Contains("<redacted>", exception.Message, StringComparison.Ordinal);
+        // ToString() is what logging frameworks emit; the secret-bearing original must not be
+        // chained as an inner exception where it would re-surface the credential verbatim.
+        Assert.DoesNotContain(password, exception.ToString(), StringComparison.Ordinal);
+    }
+
+    /// <summary>
+    /// CLI-41: an OK reply that carries neither the typed AuthenticateUser payload nor an
+    /// int32 return_value is a malformed reply, surfaced as a typed exception rather than an NRE.
+    /// </summary>
+    [Fact]
+    public async Task AuthenticateUserAsync_MissingPayloadAndReturnValue_ThrowsMalformedReply()
+    {
+        FakeGatewayTransport transport = CreateTransport();
+        transport.AddInvokeReply(ReadReplyFixture("authenticate-user.missing-payload.reply.json"));
+        await using MxGatewayClient client = CreateClient(transport);
+        MxGatewaySession session = await client.OpenSessionAsync();
+
+        await Assert.ThrowsAsync<MxGatewayMalformedReplyException>(
+            async () => await session.AuthenticateUserAsync(12, "operator", "pw"));
+    }
+
+    /// <summary>
+    /// CLI-41: an OK reply that omits the typed payload but carries an int32 return_value
+    /// resolves to that return value.
+    /// </summary>
+    [Fact]
+    public async Task AuthenticateUserAsync_ReturnValueOnly_ResolvesReturnValue()
+    {
+        FakeGatewayTransport transport = CreateTransport();
+        transport.AddInvokeReply(ReadReplyFixture("authenticate-user.return-value-only.reply.json"));
+        await using MxGatewayClient client = CreateClient(transport);
+        MxGatewaySession session = await client.OpenSessionAsync();
+
+        int userId = await session.AuthenticateUserAsync(12, "operator", "pw");
+
+        Assert.Equal(7, userId);
+    }
+
+    /// <summary>
+    /// CLI-41: the AddBufferedItem fallback shares the malformed-reply contract — an OK reply
+    /// with neither a typed item handle nor an int32 return_value throws the typed exception.
+    /// </summary>
+    [Fact]
+    public async Task AddBufferedItemAsync_MissingPayloadAndReturnValue_ThrowsMalformedReply()
+    {
+        FakeGatewayTransport transport = CreateTransport();
+        transport.AddInvokeReply(new MxCommandReply
+        {
+            SessionId = "session-fixture",
+            Kind = MxCommandKind.AddBufferedItem,
+            ProtocolStatus = new ProtocolStatus { Code = ProtocolStatusCode.Ok },
+        });
+        await using MxGatewayClient client = CreateClient(transport);
+        MxGatewaySession session = await client.OpenSessionAsync();
+
+        await Assert.ThrowsAsync<MxGatewayMalformedReplyException>(
+            async () => await session.AddBufferedItemAsync(12, "Area001.Pump001.Speed", "runtime"));
+    }
+
+    private static MxGatewayClient CreateClient(FakeGatewayTransport transport)
+    {
+        return new MxGatewayClient(transport.Options, transport);
+    }
+
+    private static FakeGatewayTransport CreateTransport()
+    {
+        return new FakeGatewayTransport(new MxGatewayClientOptions
+        {
+            Endpoint = new Uri("http://localhost:5000"),
+            ApiKey = "test-api-key",
+        });
+    }
+
+    private static MxCommandReply ReadReplyFixture(string fileName)
+    {
+        DirectoryInfo directory = new(AppContext.BaseDirectory);
+        while (directory is not null)
+        {
+            string path = Path.Combine(
+                directory.FullName,
+                "clients",
+                "proto",
+                "fixtures",
+                "behavior",
+                "command-replies",
+                fileName);
+
+            if (File.Exists(path))
+            {
+                return JsonParser.Default.Parse<MxCommandReply>(File.ReadAllText(path));
+            }
+
+            directory = directory.Parent!;
+        }
+
+        throw new FileNotFoundException(fileName);
+    }
+}

clients/dotnet/ZB.MOM.WW.MxGateway.Client.Tests/MxStatusProxyExtensionsTests.cs

@@ -20,7 +20,8 @@ public sealed class MxStatusProxyExtensionsTests
             MxStatusProxy status = JsonParser.Default.Parse<MxStatusProxy>(
                 testCase.GetProperty("status").GetRawText());
 
-            Assert.Equal(status.Category is MxStatusCategory.Ok, status.IsSuccess());
+            bool wantSuccess = testCase.GetProperty("wantSuccess").GetBoolean();
+            Assert.Equal(wantSuccess, status.IsSuccess());
             Assert.Equal(
                 testCase.GetProperty("status").GetProperty("rawCategory").GetInt32(),
                 status.RawCategory);

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxGatewayMalformedReplyException.cs

@@ -0,0 +1,46 @@
+using ZB.MOM.WW.MxGateway.Contracts.Proto;
+
+namespace ZB.MOM.WW.MxGateway.Client;
+
+/// <summary>
+/// Exception thrown when the gateway returns a protocol-OK reply that carries neither the
+/// expected typed payload nor an int32 <c>return_value</c>, so the client cannot resolve the
+/// operation result. This replaces the historical <see cref="NullReferenceException"/> that a
+/// blind <c>reply.ReturnValue.Int32Value</c> fallback would throw.
+/// </summary>
+public sealed class MxGatewayMalformedReplyException : MxGatewayException
+{
+    /// <summary>Initializes a new instance with the given message.</summary>
+    /// <param name="message">The error message describing the malformed reply.</param>
+    public MxGatewayMalformedReplyException(string message)
+        : base(message)
+    {
+    }
+
+    /// <summary>Initializes a new instance with full diagnostic context.</summary>
+    /// <param name="message">The error message describing the malformed reply.</param>
+    /// <param name="sessionId">The session ID, if available.</param>
+    /// <param name="correlationId">The correlation ID for tracing, if available.</param>
+    /// <param name="protocolStatus">The protocol status details, if available.</param>
+    /// <param name="hResult">The HResult code, if available.</param>
+    /// <param name="statuses">The MXAccess statuses, if available.</param>
+    /// <param name="innerException">The underlying exception, if any.</param>
+    public MxGatewayMalformedReplyException(
+        string message,
+        string? sessionId = null,
+        string? correlationId = null,
+        ProtocolStatus? protocolStatus = null,
+        int? hResult = null,
+        IReadOnlyList<MxStatusProxy>? statuses = null,
+        Exception? innerException = null)
+        : base(
+            message,
+            sessionId,
+            correlationId,
+            protocolStatus,
+            hResult,
+            statuses ?? [],
+            innerException)
+    {
+    }
+}

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxGatewaySecretRedaction.cs

@@ -0,0 +1,84 @@
+namespace ZB.MOM.WW.MxGateway.Client;
+
+/// <summary>
+/// Scrubs exact secret substrings out of diagnostic text before it leaves the client on an
+/// exception path. MXAccess can echo a submitted credential or secured value back inside a
+/// failure diagnostic (protocol message, MXSTATUS_PROXY diagnostic text, HRESULT description);
+/// this helper replaces any such verbatim occurrence with <c>&lt;redacted&gt;</c> so the raw
+/// request payload never reaches a caught exception's message. The marker matches the Go, Rust,
+/// and Java clients.
+/// </summary>
+internal static class MxGatewaySecretRedaction
+{
+    private const string Marker = "<redacted>";
+
+    /// <summary>
+    /// Replaces every non-null, non-empty secret in <paramref name="secrets"/> with the
+    /// redaction marker (ordinal comparison). Returns the message unchanged when it is null or
+    /// empty, or when no usable secret is supplied.
+    /// </summary>
+    /// <param name="message">The diagnostic message to scrub.</param>
+    /// <param name="secrets">The secret values to remove from the message.</param>
+    /// <returns>The scrubbed message.</returns>
+    internal static string Redact(string message, params string?[] secrets)
+    {
+        if (string.IsNullOrEmpty(message) || secrets is null)
+        {
+            return message;
+        }
+
+        string result = message;
+        foreach (string? secret in secrets)
+        {
+            if (!string.IsNullOrEmpty(secret))
+            {
+                result = result.Replace(secret, Marker, StringComparison.Ordinal);
+            }
+        }
+
+        return result;
+    }
+
+    /// <summary>
+    /// Returns an exception equivalent to <paramref name="ex"/> but with any verbatim secret
+    /// scrubbed from its message. When nothing changes, the original exception is returned
+    /// unchanged; otherwise a new exception of the same concrete runtime type is built and the
+    /// original reply/status context is preserved. The secret-bearing original is deliberately
+    /// <b>not</b> chained as the inner exception — doing so would let its unredacted message
+    /// re-surface through <see cref="Exception.ToString"/> (which logging frameworks call). The
+    /// original's own inner cause (a transport error, never the request payload) is carried
+    /// forward instead.
+    /// </summary>
+    /// <param name="ex">The exception to redact.</param>
+    /// <param name="secrets">The secret values to remove from the message.</param>
+    /// <returns>The redacted exception, or the original when no change was needed.</returns>
+    internal static MxGatewayException Redacted(MxGatewayException ex, params string?[] secrets)
+    {
+        ArgumentNullException.ThrowIfNull(ex);
+
+        string redacted = Redact(ex.Message, secrets);
+        if (string.Equals(redacted, ex.Message, StringComparison.Ordinal))
+        {
+            return ex;
+        }
+
+        Exception? cause = ex.InnerException;
+        return ex switch
+        {
+            MxAccessException access => new MxAccessException(redacted, access.Reply, cause),
+            MxGatewaySessionException => new MxGatewaySessionException(
+                redacted, ex.SessionId, ex.CorrelationId, ex.ProtocolStatus, ex.HResultCode, ex.Statuses, cause),
+            MxGatewayWorkerException => new MxGatewayWorkerException(
+                redacted, ex.SessionId, ex.CorrelationId, ex.ProtocolStatus, ex.HResultCode, ex.Statuses, cause),
+            MxGatewayAuthenticationException => new MxGatewayAuthenticationException(
+                redacted, ex.SessionId, ex.CorrelationId, ex.ProtocolStatus, ex.HResultCode, ex.Statuses, cause),
+            MxGatewayAuthorizationException => new MxGatewayAuthorizationException(
+                redacted, ex.SessionId, ex.CorrelationId, ex.ProtocolStatus, ex.HResultCode, ex.Statuses, cause),
+            MxGatewayMalformedReplyException => new MxGatewayMalformedReplyException(
+                redacted, ex.SessionId, ex.CorrelationId, ex.ProtocolStatus, ex.HResultCode, ex.Statuses, cause),
+            MxGatewayCommandException => new MxGatewayCommandException(
+                redacted, ex.SessionId, ex.CorrelationId, ex.ProtocolStatus, ex.HResultCode, ex.Statuses, cause),
+            _ => new MxGatewayException(redacted, cause),
+        };
+    }
+}

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxGatewaySession.cs

@@ -945,7 +945,7 @@ public sealed class MxGatewaySession : IAsyncDisposable
                 cancellationToken)
             .ConfigureAwait(false);
         reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
-        return reply.AddBufferedItem?.ItemHandle ?? reply.ReturnValue.Int32Value;
+        return ResolveInt32Result(reply.AddBufferedItem?.ItemHandle, reply, "AddBufferedItem");
     }
 
     /// <summary>
@@ -1141,7 +1141,14 @@ public sealed class MxGatewaySession : IAsyncDisposable
                 verifierUserId,
                 cancellationToken)
             .ConfigureAwait(false);
-        reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
+        try
+        {
+            reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
+        }
+        catch (MxGatewayException ex)
+        {
+            throw MxGatewaySecretRedaction.Redacted(ex, ExtractSecretString(value));
+        }
     }
 
     /// <summary>
@@ -1215,7 +1222,14 @@ public sealed class MxGatewaySession : IAsyncDisposable
                 verifierUserId,
                 cancellationToken)
             .ConfigureAwait(false);
-        reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
+        try
+        {
+            reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
+        }
+        catch (MxGatewayException ex)
+        {
+            throw MxGatewaySecretRedaction.Redacted(ex, ExtractSecretString(value));
+        }
     }
 
     /// <summary>
@@ -1285,8 +1299,15 @@ public sealed class MxGatewaySession : IAsyncDisposable
                 verifyUserPassword,
                 cancellationToken)
             .ConfigureAwait(false);
-        reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
-        return reply.AuthenticateUser?.UserId ?? reply.ReturnValue.Int32Value;
+        try
+        {
+            reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
+            return ResolveInt32Result(reply.AuthenticateUser?.UserId, reply, "AuthenticateUser");
+        }
+        catch (MxGatewayException ex)
+        {
+            throw MxGatewaySecretRedaction.Redacted(ex, verifyUserPassword);
+        }
     }
 
     /// <summary>
@@ -1337,7 +1358,7 @@ public sealed class MxGatewaySession : IAsyncDisposable
         MxCommandReply reply = await ArchestraUserToIdRawAsync(serverHandle, userIdGuid, cancellationToken)
             .ConfigureAwait(false);
         reply.EnsureProtocolSuccess().EnsureMxAccessSuccess();
-        return reply.ArchestraUserToId?.UserId ?? reply.ReturnValue.Int32Value;
+        return ResolveInt32Result(reply.ArchestraUserToId?.UserId, reply, "ArchestrAUserToId");
     }
 
     /// <summary>
@@ -1367,6 +1388,51 @@ public sealed class MxGatewaySession : IAsyncDisposable
             cancellationToken);
     }
 
+    /// <summary>
+    /// Resolves the int32 result of an OK command reply: the typed payload value when present,
+    /// otherwise an int32 <c>return_value</c> when the reply carries one. A reply that provides
+    /// neither is malformed and surfaces as <see cref="MxGatewayMalformedReplyException"/>
+    /// rather than the historical <see cref="NullReferenceException"/>.
+    /// </summary>
+    /// <param name="typedValue">The typed payload value, or <see langword="null"/> when absent.</param>
+    /// <param name="reply">The OK command reply.</param>
+    /// <param name="operation">The MXAccess operation name, for the diagnostic message.</param>
+    /// <returns>The resolved int32 result.</returns>
+    private static int ResolveInt32Result(int? typedValue, MxCommandReply reply, string operation)
+    {
+        if (typedValue.HasValue)
+        {
+            return typedValue.Value;
+        }
+
+        if (reply.ReturnValue is not null
+            && reply.ReturnValue.KindCase == MxValue.KindOneofCase.Int32Value)
+        {
+            return reply.ReturnValue.Int32Value;
+        }
+
+        throw new MxGatewayMalformedReplyException(
+            $"{operation} returned a malformed reply: OK reply carried neither the typed payload nor an int32 return_value",
+            reply.SessionId,
+            reply.CorrelationId,
+            reply.ProtocolStatus,
+            reply.HasHresult ? reply.Hresult : null,
+            reply.Statuses.ToArray());
+    }
+
+    /// <summary>
+    /// Extracts the raw string form of a credential-bearing <see cref="MxValue"/> for redaction,
+    /// or <see langword="null"/> when the value does not carry a string.
+    /// </summary>
+    /// <param name="value">The value written by a secured write.</param>
+    /// <returns>The string payload, or <see langword="null"/>.</returns>
+    private static string? ExtractSecretString(MxValue value)
+    {
+        return value.KindCase == MxValue.KindOneofCase.StringValue
+            ? value.StringValue
+            : null;
+    }
+
     /// <summary>
     /// Invokes an MXAccess command on this session.
     /// </summary>

clients/dotnet/ZB.MOM.WW.MxGateway.Client/MxStatusProxyExtensions.cs

@@ -30,6 +30,6 @@ public static class MxStatusProxyExtensions
             ? "no diagnostic text"
             : status.DiagnosticText;
 
-        return $"{status.Category} by {status.DetectedBy}; detail={status.Detail}; {diagnosticText}";
+        return $"success={status.Success}; {status.Category} by {status.DetectedBy}; detail={status.Detail}; {diagnosticText}";
     }
 }