feat(java-client): operator credentials on acknowledge-alarm

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT
2026-10-19 19:42:10 -04:00
parent 417a47bdb5
commit 84e04b6552
6 changed files with 1354 additions and 453 deletions
@@ -114,8 +114,11 @@ try (MxEventStream events = session.streamEventsAfter(lastSeenSequence)) {
 For alarms, `MxGatewayClient` exposes `queryActiveAlarms` (one-shot snapshot),
 `streamAlarms` (returns an `MxGatewayAlarmFeedSubscription` whose iterator
 yields alarm-feed messages from the gateway's central monitor), and
-`acknowledgeAlarm` (ack by full alarm reference with an optional comment and
-ack target). Close the subscription to cancel the underlying gRPC stream.
+`acknowledgeAlarm` (ack by full alarm reference with an optional comment).
+The ack carries operator credentials: `operator_user` is required, and
+`operator_password` / `operator_domain` let the gateway authenticate as that
+operator so the Historian records the real operator. An empty password is
+allowed. The password is scrubbed from exceptions the client throws. Close the subscription to cancel the underlying gRPC stream.

 `ActiveAlarmSnapshot.getFromTruncatedSnapshot()` reports that the record came
 from a provider fetch which hit the per-fetch cap: the snapshot set may omit
@@ -417,7 +420,7 @@ gradle :zb-mom-ww-mxgateway-cli:run --args="authenticate-user --endpoint localho
 gradle :zb-mom-ww-mxgateway-cli:run --args="write-secured --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --server-handle 1 --item-handle 1 --type int32 --value 123 --current-user-id 100 --verifier-user-id 100 --json"
 gradle :zb-mom-ww-mxgateway-cli:run --args="stream-events --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --limit 1 --json"
 gradle :zb-mom-ww-mxgateway-cli:run --args="stream-alarms --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --filter-prefix Galaxy --limit 4 --json"
-gradle :zb-mom-ww-mxgateway-cli:run --args="acknowledge-alarm --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --reference \"\\Galaxy\Area001.Pump001.PumpFault\" --json"
+gradle :zb-mom-ww-mxgateway-cli:run --args="acknowledge-alarm --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --reference \"\\Galaxy\Area001.Pump001.PumpFault\" --operator operator1 --operator-password-env MXGATEWAY_OPERATOR_PASSWORD --json"
 gradle :zb-mom-ww-mxgateway-cli:run --args="smoke --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --item TestObject.TestInt --json"
 ```

@@ -1822,6 +1822,31 @@ public final class MxGatewayCli implements Callable<Integer> {
        @Option(names = "--operator", description = "Operator user performing the acknowledge.")
        String operator = "";

+        @Option(names = "--operator-domain", description = "Operator Galaxy domain (optional).")
+        String operatorDomain = "";
+
+        @Option(
+                names = "--operator-password",
+                description = "Operator Galaxy password (credential; prefer --operator-password-env). Never echoed.")
+        String operatorPassword;
+
+        @Option(
+                names = "--operator-password-env",
+                defaultValue = "MXGATEWAY_OPERATOR_PASSWORD",
+                description = "Environment variable holding the operator password when --operator-password is omitted.")
+        String operatorPasswordEnv;
+
+        private String resolveOperatorPassword() {
+            if (operatorPassword != null && !operatorPassword.isEmpty()) {
+                return operatorPassword;
+            }
+            String name = operatorPasswordEnv == null || operatorPasswordEnv.isBlank()
+                    ? "MXGATEWAY_OPERATOR_PASSWORD"
+                    : operatorPasswordEnv;
+            String value = System.getenv(name);
+            return value == null ? "" : value;
+        }
+
        AcknowledgeAlarmCommand(MxGatewayCliClientFactory clientFactory) {
            super(clientFactory);
        }
@@ -1833,6 +1858,8 @@ public final class MxGatewayCli implements Callable<Integer> {
                        .setAlarmFullReference(reference)
                        .setComment(comment)
                        .setOperatorUser(operator)
+                        .setOperatorDomain(operatorDomain == null ? "" : operatorDomain)
+                        .setOperatorPassword(resolveOperatorPassword())
                        .build());
                writeOutput(
                        "acknowledge-alarm",
@@ -714,9 +714,16 @@ final class MxGatewayCliTests {
                "checked",
                "--operator",
                "operator1",
+                "--operator-domain",
+                "CORP",
+                "--operator-password",
+                "pw-secret",
                "--json");

        assertEquals(0, run.exitCode());
+        assertEquals("CORP", factory.client.lastAcknowledgeAlarmRequest.getOperatorDomain());
+        assertEquals("pw-secret", factory.client.lastAcknowledgeAlarmRequest.getOperatorPassword());
+        assertFalse(run.output().contains("pw-secret"), run.output());
        assertEquals("Tank01.Level.HiHi", factory.client.lastAcknowledgeAlarmRequest.getAlarmFullReference());
        assertEquals("checked", factory.client.lastAcknowledgeAlarmRequest.getComment());
        assertEquals("operator1", factory.client.lastAcknowledgeAlarmRequest.getOperatorUser());
@@ -770,6 +777,10 @@ final class MxGatewayCliTests {
                "--plaintext",
                "--reference",
                "\\Galaxy\\Area001.Pump001.PumpFault",
+                "--operator",
+                "operator1",
+                "--operator-password-env",
+                "MXGATEWAY_OPERATOR_PASSWORD",
                "--json"
        };
        assertReadmeExampleParses(args);
@@ -273,6 +273,11 @@ public final class MxGatewayClient implements AutoCloseable {
     * worker's MXAccess session; the resulting native MxStatus is returned
     * in the reply. Acks are idempotent at the MxAccess layer.
     *
+     * <p>{@code operator_user} is required; the gateway authenticates it with
+     * {@code operator_password} (and optional {@code operator_domain}) and the
+     * Historian records that operator. An empty password is allowed. The
+     * password is scrubbed from any exception this method throws.
+     *
     * @param request the {@code AcknowledgeAlarmRequest}
     * @return the raw acknowledge reply
     * @throws MxGatewayException on transport or protocol failure
@@ -283,10 +288,14 @@ public final class MxGatewayClient implements AutoCloseable {
            MxGatewayErrors.ensureProtocolSuccess("acknowledge alarm", reply.getProtocolStatus(), null);
            return reply;
        } catch (RuntimeException error) {
-            if (error instanceof MxGatewayException) {
-                throw error;
+            MxGatewayException mapped = error instanceof MxGatewayException gatewayError
+                    ? gatewayError
+                    : (MxGatewayException) MxGatewayErrors.fromGrpc("acknowledge alarm", error);
+            String secret = request.getOperatorPassword();
+            if (secret.isEmpty()) {
+                throw mapped;
            }
-            throw MxGatewayErrors.fromGrpc("acknowledge alarm", error);
+            throw MxGatewayErrors.redacted(mapped, secret);
        }
    }

@@ -28,6 +28,43 @@ final class MxGatewayErrors {
        return new MxGatewayException("gateway " + operation + " failed: " + error.getMessage(), error);
    }

+    /**
+     * Rebuilds a gateway exception with an exact secret scrubbed from its
+     * message and protocol status. The original is not chained as a cause
+     * because its message and cause chain may carry the secret.
+     */
+    static MxGatewayException redacted(MxGatewayException error, String secret) {
+        String message = MxGatewaySecrets.redactExact(error.getMessage(), secret);
+        if (error instanceof MxAccessException ex) {
+            return new MxAccessException(message, scrub(ex.protocolStatus(), secret), ex.reply(), null);
+        }
+        if (error instanceof MxGatewayCommandException ex) {
+            return new MxGatewayCommandException(message, scrub(ex.protocolStatus(), secret), ex.reply(), null);
+        }
+        if (error instanceof MxGatewaySessionException ex) {
+            return new MxGatewaySessionException(message, scrub(ex.protocolStatus(), secret), null);
+        }
+        if (error instanceof MxGatewayWorkerException ex) {
+            return new MxGatewayWorkerException(message, scrub(ex.protocolStatus(), secret), null);
+        }
+        if (error instanceof MxGatewayAuthenticationException) {
+            return new MxGatewayAuthenticationException(message, null);
+        }
+        if (error instanceof MxGatewayAuthorizationException) {
+            return new MxGatewayAuthorizationException(message, null);
+        }
+        return new MxGatewayException(message);
+    }
+
+    private static ProtocolStatus scrub(ProtocolStatus status, String secret) {
+        if (status == null) {
+            return null;
+        }
+        return status.toBuilder()
+                .setMessage(MxGatewaySecrets.redactExact(status.getMessage(), secret))
+                .build();
+    }
+
    static void ensureProtocolSuccess(String operation, ProtocolStatus status, MxCommandReply reply) {
        if (status == null || status.getCode() == ProtocolStatusCode.PROTOCOL_STATUS_CODE_OK) {
            return;