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.
2026-08-07 06:42:40 -04:00
parent d2bb32d97b
commit dc7fd16dd5
33 changed files with 1465 additions and 97 deletions
@@ -29,4 +29,18 @@ public final class MxAccessException extends MxGatewayCommandException {
    public MxAccessException(String operation, MxCommandReply reply) {
        super(operation, reply == null ? null : reply.getProtocolStatus(), reply);
    }
+
+    /**
+     * Creates a new MXAccess exception with an already-built, verbatim message.
+     * Used to re-surface an MXAccess failure with a redacted message while
+     * preserving the original protocol status and reply.
+     *
+     * @param message the exact message to surface (already formatted/redacted)
+     * @param protocolStatus protocol status reported by the gateway
+     * @param reply raw command reply containing the MXAccess failure detail
+     * @param cause underlying error, or {@code null}
+     */
+    public MxAccessException(String message, ProtocolStatus protocolStatus, MxCommandReply reply, Throwable cause) {
+        super(message, protocolStatus, reply, cause);
+    }
 }
@@ -25,6 +25,23 @@ public class MxGatewayCommandException extends MxGatewayException {
        this.reply = reply;
    }

+    /**
+     * Creates a new command exception with an already-built, verbatim message.
+     * Used to re-surface a failure with a redacted message while preserving the
+     * original protocol status and reply.
+     *
+     * @param message the exact message to surface (already formatted/redacted)
+     * @param protocolStatus protocol status returned by the gateway
+     * @param reply raw command reply, or {@code null} when none was produced
+     * @param cause underlying error, or {@code null}
+     */
+    protected MxGatewayCommandException(
+            String message, ProtocolStatus protocolStatus, MxCommandReply reply, Throwable cause) {
+        super(message, cause);
+        this.protocolStatus = protocolStatus;
+        this.reply = reply;
+    }
+
    /**
     * Returns the gateway protocol status that triggered this exception.
     *
@@ -0,0 +1,32 @@
+package com.zb.mom.ww.mxgateway.client;
+
+/**
+ * Thrown when the gateway returns a protocol-OK command reply that carries
+ * neither the expected typed payload nor a usable {@code return_value}.
+ *
+ * <p>A successful reply for a value-returning command (for example
+ * {@code AuthenticateUser}, {@code ArchestrAUserToId}, or {@code AddBufferedItem})
+ * must supply either the command's typed payload or an int32 {@code return_value}.
+ * A reply that satisfies neither is malformed, and the client surfaces this
+ * distinct failure rather than silently returning a default {@code 0}.
+ */
+public final class MxGatewayMalformedReplyException extends MxGatewayException {
+    /**
+     * Creates a new malformed-reply exception with the supplied message.
+     *
+     * @param message human-readable description of the malformed reply
+     */
+    public MxGatewayMalformedReplyException(String message) {
+        super(message);
+    }
+
+    /**
+     * Creates a new malformed-reply exception with the supplied message and cause.
+     *
+     * @param message human-readable description of the malformed reply
+     * @param cause underlying error that triggered the failure
+     */
+    public MxGatewayMalformedReplyException(String message, Throwable cause) {
+        super(message, cause);
+    }
+}
@@ -54,4 +54,32 @@ public final class MxGatewaySecrets {
        }
        return String.join(" ", parts);
    }
+
+    /**
+     * Replaces every occurrence of each supplied secret with the redaction
+     * marker {@code "<redacted>"}. Unlike {@link #redactCredentials(String)},
+     * which scrubs by pattern, this performs an exact-substring scrub of the
+     * caller-known secrets — used to strip a credential the gateway echoed back
+     * into a free-form failure message.
+     *
+     * @param message the message to scrub, may be {@code null}
+     * @param secrets the exact secret substrings to remove; {@code null}/empty
+     *     entries and a {@code null} array are ignored
+     * @return {@code message} unchanged when it is {@code null} or no non-empty
+     *     secret is supplied, otherwise the message with every secret occurrence
+     *     replaced by {@code "<redacted>"}
+     */
+    public static String redactExact(String message, String... secrets) {
+        if (message == null || secrets == null) {
+            return message;
+        }
+
+        String result = message;
+        for (String secret : secrets) {
+            if (secret != null && !secret.isEmpty()) {
+                result = result.replace(secret, "<redacted>");
+            }
+        }
+        return result;
+    }
 }
@@ -782,15 +782,17 @@ public final class MxGatewaySession implements AutoCloseable {
     */
    public MxCommandReply writeSecuredRaw(
            int serverHandle, int itemHandle, int currentUserId, int verifierUserId, MxValue value) {
-        return invokeCommand(MxCommand.newBuilder()
-                .setKind(MxCommandKind.MX_COMMAND_KIND_WRITE_SECURED)
-                .setWriteSecured(WriteSecuredCommand.newBuilder()
-                        .setServerHandle(serverHandle)
-                        .setItemHandle(itemHandle)
-                        .setCurrentUserId(currentUserId)
-                        .setVerifierUserId(verifierUserId)
-                        .setValue(value))
-                .build());
+        return invokeCommandRedacted(
+                MxCommand.newBuilder()
+                        .setKind(MxCommandKind.MX_COMMAND_KIND_WRITE_SECURED)
+                        .setWriteSecured(WriteSecuredCommand.newBuilder()
+                                .setServerHandle(serverHandle)
+                                .setItemHandle(itemHandle)
+                                .setCurrentUserId(currentUserId)
+                                .setVerifierUserId(verifierUserId)
+                                .setValue(value))
+                        .build(),
+                secretStringOf(value));
    }

    /**
@@ -837,16 +839,18 @@ public final class MxGatewaySession implements AutoCloseable {
            int verifierUserId,
            MxValue value,
            MxValue timestampValue) {
-        return invokeCommand(MxCommand.newBuilder()
-                .setKind(MxCommandKind.MX_COMMAND_KIND_WRITE_SECURED2)
-                .setWriteSecured2(WriteSecured2Command.newBuilder()
-                        .setServerHandle(serverHandle)
-                        .setItemHandle(itemHandle)
-                        .setCurrentUserId(currentUserId)
-                        .setVerifierUserId(verifierUserId)
-                        .setValue(value)
-                        .setTimestampValue(timestampValue))
-                .build());
+        return invokeCommandRedacted(
+                MxCommand.newBuilder()
+                        .setKind(MxCommandKind.MX_COMMAND_KIND_WRITE_SECURED2)
+                        .setWriteSecured2(WriteSecured2Command.newBuilder()
+                                .setServerHandle(serverHandle)
+                                .setItemHandle(itemHandle)
+                                .setCurrentUserId(currentUserId)
+                                .setVerifierUserId(verifierUserId)
+                                .setValue(value)
+                                .setTimestampValue(timestampValue))
+                        .build(),
+                secretStringOf(value));
    }

    /**
@@ -866,17 +870,24 @@ public final class MxGatewaySession implements AutoCloseable {
     * @throws MxAccessException when MXAccess rejects the credential
     */
    public int authenticateUser(int serverHandle, String verifyUser, String verifyUserPassword) {
-        MxCommandReply reply = invokeCommand(MxCommand.newBuilder()
-                .setKind(MxCommandKind.MX_COMMAND_KIND_AUTHENTICATE_USER)
-                .setAuthenticateUser(AuthenticateUserCommand.newBuilder()
-                        .setServerHandle(serverHandle)
-                        .setVerifyUser(verifyUser)
-                        .setVerifyUserPassword(verifyUserPassword))
-                .build());
+        MxCommandReply reply = invokeCommandRedacted(
+                MxCommand.newBuilder()
+                        .setKind(MxCommandKind.MX_COMMAND_KIND_AUTHENTICATE_USER)
+                        .setAuthenticateUser(AuthenticateUserCommand.newBuilder()
+                                .setServerHandle(serverHandle)
+                                .setVerifyUser(verifyUser)
+                                .setVerifyUserPassword(verifyUserPassword))
+                        .build(),
+                verifyUserPassword);
        if (reply.hasAuthenticateUser()) {
            return reply.getAuthenticateUser().getUserId();
        }
-        return reply.getReturnValue().getInt32Value();
+        if (reply.hasReturnValue() && reply.getReturnValue().getKindCase() == MxValue.KindCase.INT32_VALUE) {
+            return reply.getReturnValue().getInt32Value();
+        }
+        throw new MxGatewayMalformedReplyException(
+                "AuthenticateUser returned a malformed reply: OK reply carried neither "
+                        + "the typed payload nor an int32 return_value");
    }

    /**
@@ -899,7 +910,12 @@ public final class MxGatewaySession implements AutoCloseable {
        if (reply.hasArchestraUserToId()) {
            return reply.getArchestraUserToId().getUserId();
        }
-        return reply.getReturnValue().getInt32Value();
+        if (reply.hasReturnValue() && reply.getReturnValue().getKindCase() == MxValue.KindCase.INT32_VALUE) {
+            return reply.getReturnValue().getInt32Value();
+        }
+        throw new MxGatewayMalformedReplyException(
+                "ArchestrAUserToId returned a malformed reply: OK reply carried neither "
+                        + "the typed payload nor an int32 return_value");
    }

    /**
@@ -925,7 +941,12 @@ public final class MxGatewaySession implements AutoCloseable {
        if (reply.hasAddBufferedItem()) {
            return reply.getAddBufferedItem().getItemHandle();
        }
-        return reply.getReturnValue().getInt32Value();
+        if (reply.hasReturnValue() && reply.getReturnValue().getKindCase() == MxValue.KindCase.INT32_VALUE) {
+            return reply.getReturnValue().getInt32Value();
+        }
+        throw new MxGatewayMalformedReplyException(
+                "AddBufferedItem returned a malformed reply: OK reply carried neither "
+                        + "the typed payload nor an int32 return_value");
    }

    /**
@@ -1027,6 +1048,49 @@ public final class MxGatewaySession implements AutoCloseable {
                .build());
    }

+    /**
+     * Invokes a credential-bearing command, scrubbing any exact secret the
+     * gateway may have echoed back into a surfaced failure message. The secret
+     * lives only in the request, but a non-parity gateway or provider can copy
+     * it into a diagnostic; this guarantees it never survives in the exception
+     * text a caller might log.
+     *
+     * <p>On failure the original exception's message is scrubbed with
+     * {@link MxGatewaySecrets#redactExact}. If nothing changed (the common case
+     * where the message never carried the secret), the original exception is
+     * rethrown untouched. Otherwise it is re-thrown as the same concrete type
+     * carrying the redacted message; the secret-bearing original is not chained
+     * as a cause, so it cannot leak through a printed stack trace.
+     */
+    private MxCommandReply invokeCommandRedacted(MxCommand command, String... secrets) {
+        try {
+            return invokeCommand(command);
+        } catch (MxGatewayException ex) {
+            String original = ex.getMessage();
+            String redacted = MxGatewaySecrets.redactExact(original, secrets);
+            if (redacted == null || redacted.equals(original)) {
+                throw ex;
+            }
+            if (ex instanceof MxAccessException mx) {
+                throw new MxAccessException(redacted, mx.protocolStatus(), mx.reply(), null);
+            }
+            throw new MxGatewayException(redacted);
+        }
+    }
+
+    /**
+     * Extracts the string payload of a secured-write value so it can be scrubbed
+     * from an echoed failure message. Only string-kind values carry a
+     * credential-shaped secret worth redacting; other kinds return {@code null}
+     * (ignored by {@link MxGatewaySecrets#redactExact}).
+     */
+    private static String secretStringOf(MxValue value) {
+        if (value != null && value.getKindCase() == MxValue.KindCase.STRING_VALUE) {
+            return value.getStringValue();
+        }
+        return null;
+    }
+
    private static String newCorrelationId() {
        byte[] bytes = new byte[16];
        RANDOM.nextBytes(bytes);
@@ -0,0 +1,172 @@
+package com.zb.mom.ww.mxgateway.client;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import com.google.protobuf.util.JsonFormat;
+import io.grpc.ManagedChannel;
+import io.grpc.Server;
+import io.grpc.inprocess.InProcessChannelBuilder;
+import io.grpc.inprocess.InProcessServerBuilder;
+import io.grpc.stub.StreamObserver;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.time.Duration;
+import java.util.UUID;
+import mxaccess_gateway.v1.MxAccessGatewayGrpc;
+import mxaccess_gateway.v1.MxaccessGateway.MxCommandReply;
+import mxaccess_gateway.v1.MxaccessGateway.MxCommandRequest;
+import mxaccess_gateway.v1.MxaccessGateway.MxValue;
+import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatus;
+import mxaccess_gateway.v1.MxaccessGateway.ProtocolStatusCode;
+import org.junit.jupiter.api.Test;
+
+final class MxGatewayCredentialReplyTests {
+    private static final String CREDENTIAL = "sup3rSecretVerify9f3a2b";
+
+    @Test
+    void authenticateUserRedactsEchoedCredentialFromReplyDrivenError() throws Exception {
+        MxCommandReply reply = loadReply("authenticate-user.echoed-credential.reply.json");
+
+        try (InProcessGateway gateway = InProcessGateway.startReturning(reply);
+                MxGatewayClient client = gateway.client()) {
+            MxGatewaySession session = MxGatewaySession.forSessionId(client, "auth-echo-session");
+
+            MxAccessException error = assertThrows(
+                    MxAccessException.class,
+                    () -> session.authenticateUser(12, "operator", CREDENTIAL));
+
+            assertFalse(error.getMessage().contains(CREDENTIAL),
+                    "credential echoed by the gateway must not survive in the surfaced message");
+            assertTrue(error.getMessage().contains("<redacted>"),
+                    "the echoed credential must be replaced with the redaction marker");
+        }
+    }
+
+    @Test
+    void authenticateUserMissingPayloadThrowsMalformedReply() throws Exception {
+        MxCommandReply reply = loadReply("authenticate-user.missing-payload.reply.json");
+
+        try (InProcessGateway gateway = InProcessGateway.startReturning(reply);
+                MxGatewayClient client = gateway.client()) {
+            MxGatewaySession session = MxGatewaySession.forSessionId(client, "auth-missing-session");
+
+            assertThrows(
+                    MxGatewayMalformedReplyException.class,
+                    () -> session.authenticateUser(3, "operator", "pw"));
+        }
+    }
+
+    @Test
+    void authenticateUserReturnValueOnlyReplyReturnsInt32Fallback() throws Exception {
+        MxCommandReply reply = loadReply("authenticate-user.return-value-only.reply.json");
+
+        try (InProcessGateway gateway = InProcessGateway.startReturning(reply);
+                MxGatewayClient client = gateway.client()) {
+            MxGatewaySession session = MxGatewaySession.forSessionId(client, "auth-return-session");
+
+            assertEquals(7, session.authenticateUser(3, "operator", "pw"));
+        }
+    }
+
+    @Test
+    void addBufferedItemReturnValueOnlyReplyReturnsInt32Fallback() throws Exception {
+        MxCommandReply reply = MxCommandReply.newBuilder()
+                .setProtocolStatus(ok())
+                .setReturnValue(MxValue.newBuilder().setInt32Value(55))
+                .build();
+
+        try (InProcessGateway gateway = InProcessGateway.startReturning(reply);
+                MxGatewayClient client = gateway.client()) {
+            MxGatewaySession session = MxGatewaySession.forSessionId(client, "buffered-return-session");
+
+            assertEquals(55, session.addBufferedItem(3, "Tank01.Level", "galaxy"));
+        }
+    }
+
+    @Test
+    void addBufferedItemMissingPayloadThrowsMalformedReply() throws Exception {
+        MxCommandReply reply = MxCommandReply.newBuilder().setProtocolStatus(ok()).build();
+
+        try (InProcessGateway gateway = InProcessGateway.startReturning(reply);
+                MxGatewayClient client = gateway.client()) {
+            MxGatewaySession session = MxGatewaySession.forSessionId(client, "buffered-malformed-session");
+
+            assertThrows(
+                    MxGatewayMalformedReplyException.class,
+                    () -> session.addBufferedItem(3, "Tank01.Level", "galaxy"));
+        }
+    }
+
+    private static ProtocolStatus ok() {
+        return ProtocolStatus.newBuilder()
+                .setCode(ProtocolStatusCode.PROTOCOL_STATUS_CODE_OK)
+                .build();
+    }
+
+    private static MxCommandReply loadReply(String fixture) throws Exception {
+        MxCommandReply.Builder builder = MxCommandReply.newBuilder();
+        JsonFormat.parser().merge(
+                Files.readString(fixtureRoot().resolve("command-replies/" + fixture)),
+                builder);
+        return builder.build();
+    }
+
+    private static Path fixtureRoot() {
+        Path current = Path.of(System.getProperty("user.dir")).toAbsolutePath();
+        for (Path path = current; path != null; path = path.getParent()) {
+            Path candidate = path.resolve("clients/proto/fixtures/behavior");
+            if (Files.exists(candidate)) {
+                return candidate;
+            }
+            candidate = path.resolve("../proto/fixtures/behavior").normalize();
+            if (Files.exists(candidate)) {
+                return candidate;
+            }
+        }
+        throw new IllegalStateException("could not locate behavior fixtures from " + current);
+    }
+
+    private record InProcessGateway(Server server, ManagedChannel channel) implements AutoCloseable {
+        static InProcessGateway startReturning(MxCommandReply reply) throws Exception {
+            String serverName = "mxgw-java-cred-" + UUID.randomUUID();
+            MxAccessGatewayGrpc.MxAccessGatewayImplBase service =
+                    new MxAccessGatewayGrpc.MxAccessGatewayImplBase() {
+                        @Override
+                        public void invoke(
+                                MxCommandRequest request, StreamObserver<MxCommandReply> responseObserver) {
+                            responseObserver.onNext(reply);
+                            responseObserver.onCompleted();
+                        }
+                    };
+            Server server = InProcessServerBuilder.forName(serverName)
+                    .directExecutor()
+                    .addService(service)
+                    .build()
+                    .start();
+            ManagedChannel channel = InProcessChannelBuilder.forName(serverName)
+                    .directExecutor()
+                    .build();
+            return new InProcessGateway(server, channel);
+        }
+
+        MxGatewayClient client() {
+            return new MxGatewayClient(
+                    channel,
+                    MxGatewayClientOptions.builder()
+                            .endpoint("in-process")
+                            .apiKey("")
+                            .plaintext(true)
+                            .callTimeout(Duration.ofSeconds(5))
+                            .build());
+        }
+
+        @Override
+        public void close() {
+            channel.shutdownNow();
+            server.shutdownNow();
+        }
+    }
+}