Acknowledge alarms as the authenticated operator (AckMsg write) #162

Closed

dohertj2 wants to merge 0 commits from feat/ackmsg-as-operator into main

pull from: feat/ackmsg-as-operator

merge into: dohertj2:main

dohertj2:main

dohertj2:docs/managed-alarm-ack-live-result

dohertj2:feat/managed-guid-alarm-ack

dohertj2:fix/fake-worker-fault-diagnostics

dohertj2:fix/framed-worker-test-gates

dohertj2:fix/generated-rust-must-use

dohertj2:docs/prose-audit

dohertj2:docs/xml-doc-comments

dohertj2:feat/adopt-zb-telemetry-serilog

dohertj2:test/client-e2e-coverage

dohertj2:docs/alarm-client-wm-app-finding

dohertj2:codex/fix-runtime-review-findings

Conversation 1 Commits - Files Changed -

dohertj2 commented 2026-10-19 20:09:33 -04:00

Owner

Copy Link

Copy Source

Acknowledges an alarm as the operator who requested it, so the Historian events table records the real operator, the way InTouch does.

The worker authenticates the operator with AuthenticateUser, then writes the ack comment to <TAGNAME>.AckMsg over MXAccess. It does this on its own LMXProxyServer, registered under MxGateway:Alarms:AckClientName (default MxGateway); the Historian records that name as OperatorNode. The alarm-client ack paths (wnwrap AlarmAckByName/ByGUID, the managed aaAlarmManagedClient, WNAL) are inert when run headless (see docs/AlarmProbeFindings.md, "Fourth attempt"), so this PR removes them.

Changes

• Contract: AcknowledgeAlarmRequest.operator_password = 6, operator_domain = 7. Worker ack commands also carry the password. GatewayProtocolVersion stays at 3.
• Worker:
  • New AlarmAckWriter: authenticate, AddItem+Advise, Write, then a bounded pumped wait for OnWriteComplete. It keeps an LRU item cache, rebuilds the item after an unconfirmed write, tears down and re-registers on RPC disconnect, and classifies interop failures by HRESULT.
  • Consumers now only resolve the AckMsg item; a non-Galaxy provider is NotAckable.
  • The wnwrap ACK_* XML fields are parsed and attributed on Acknowledge transitions.
  • The managed and WNAL ack path and the second wnwrap ack consumer are deleted.
• Gateway: forwards the credentials. operator_user is required (InvalidArgument otherwise). Ack commands are now treated as credential-bearing for log redaction, and any property named like password is redacted. New AckClientName option, passed to the worker by env var.
• Clients (.NET, Python, Go, Rust, Java): request fields, password redaction on ack errors, and CLI flags --operator-domain, --operator-password, --operator-password-env (default MXGATEWAY_OPERATOR_PASSWORD).
• Docs: Grpc.md (status mapping, upgrade note), DesignDecisions.md, GatewayConfiguration.md, Diagnostics.md, Authorization.md (the credential-oracle trade-off of keeping ack under invoke:write), AlarmProbeFindings.md, CLAUDE.md.

Status mapping

Outcome	Status	hresult
Applied / unconfirmed	OK	0
Unknown alarm / non-Galaxy provider	INVALID_REQUEST	-1
Authentication failed	MXACCESS_FAILURE	the AuthenticateUser HRESULT (wrong password = 0x80070057)
Write rejected	MXACCESS_FAILURE	the HRESULT, or the OnWriteComplete detail

Upgrade impact

Callers must send operator_user and the operator's Galaxy password. OtOpcUa's GatewayGalaxyAlarmAcknowledger (Runtime/GatewayGalaxyAlarmAcknowledger.cs:50) sends no password. Update it before this gateway is deployed anywhere OtOpcUa acks alarms.

Verification

• macOS: gateway suite 1216/1216. .NET client 135 pass. Go, Python (171), Rust (111), and Java test + checkGeneratedClean all green.
• windev worker CI: SUCCESS, 574 pass / 0 fail.
• Live on windev (Server + Worker at e7f5662 deployed, then rolled back):
  • An RPC ack as Administrator returns OK / hresult 0. .Acked=True, .AckMsg = the comment.
  • Historian ACK_ALM row: Operator=Administrator, DomainName=ArchestrA, UserFullName=Administrator, OperatorNode=MxGateway, Description=<comment>.
  • Wrong password returns MXACCESS_FAILURE "Operator authentication failed"; the alarm stays unacked, no ack row is written, and the password has 0 hits in the gateway log, stdout and stderr.
  • InTouch provider returns INVALID_REQUEST. Empty user returns InvalidArgument.
• Not driven live: the GUID arm. The public RPCs expose only full references, so it is covered by unit tests only.

Deploy notes found on windev (not changed by this PR)

• The current Secrets library rejects a relative Secrets:SqlitePath, or one inside the content root. The old live appsettings.json used mxgateway-secrets.db, so the test deploy moved the store to C:\publish\mxaccessgw\secrets\.
• NU1903 (GHSA-846f-f764-76mx) on transitive System.Security.Cryptography.Pkcs 9.0.4 now fails dotnet restore on windev because of TreatWarningsAsErrors. This also affects main.

https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

Acknowledges an alarm as the operator who requested it, so the Historian events table records the real operator, the way InTouch does. The worker authenticates the operator with `AuthenticateUser`, then writes the ack comment to `<TAGNAME>.AckMsg` over MXAccess. It does this on its own `LMXProxyServer`, registered under `MxGateway:Alarms:AckClientName` (default `MxGateway`); the Historian records that name as `OperatorNode`. The alarm-client ack paths (wnwrap `AlarmAckByName`/`ByGUID`, the managed `aaAlarmManagedClient`, WNAL) are inert when run headless (see `docs/AlarmProbeFindings.md`, "Fourth attempt"), so this PR removes them. ## Changes - **Contract:** `AcknowledgeAlarmRequest.operator_password = 6`, `operator_domain = 7`. Worker ack commands also carry the password. `GatewayProtocolVersion` stays at 3. - **Worker:** - New `AlarmAckWriter`: authenticate, AddItem+Advise, Write, then a bounded pumped wait for `OnWriteComplete`. It keeps an LRU item cache, rebuilds the item after an unconfirmed write, tears down and re-registers on RPC disconnect, and classifies interop failures by HRESULT. - Consumers now only resolve the AckMsg item; a non-Galaxy provider is NotAckable. - The wnwrap `ACK_*` XML fields are parsed and attributed on Acknowledge transitions. - The managed and WNAL ack path and the second wnwrap ack consumer are deleted. - **Gateway:** forwards the credentials. `operator_user` is required (InvalidArgument otherwise). Ack commands are now treated as credential-bearing for log redaction, and any property named like `password` is redacted. New `AckClientName` option, passed to the worker by env var. - **Clients (.NET, Python, Go, Rust, Java):** request fields, password redaction on ack errors, and CLI flags `--operator-domain`, `--operator-password`, `--operator-password-env` (default `MXGATEWAY_OPERATOR_PASSWORD`). - **Docs:** `Grpc.md` (status mapping, upgrade note), `DesignDecisions.md`, `GatewayConfiguration.md`, `Diagnostics.md`, `Authorization.md` (the credential-oracle trade-off of keeping ack under `invoke:write`), `AlarmProbeFindings.md`, `CLAUDE.md`. ## Status mapping | Outcome | Status | hresult | |---|---|---| | Applied / unconfirmed | OK | 0 | | Unknown alarm / non-Galaxy provider | INVALID_REQUEST | -1 | | Authentication failed | MXACCESS_FAILURE | the AuthenticateUser HRESULT (wrong password = 0x80070057) | | Write rejected | MXACCESS_FAILURE | the HRESULT, or the OnWriteComplete detail | ## Upgrade impact Callers must send `operator_user` and the operator's Galaxy password. **OtOpcUa's `GatewayGalaxyAlarmAcknowledger` (`Runtime/GatewayGalaxyAlarmAcknowledger.cs:50`) sends no password.** Update it before this gateway is deployed anywhere OtOpcUa acks alarms. ## Verification - **macOS:** gateway suite 1216/1216. .NET client 135 pass. Go, Python (171), Rust (111), and Java `test` + `checkGeneratedClean` all green. - **windev worker CI:** `SUCCESS`, 574 pass / 0 fail. - **Live on windev** (Server + Worker at e7f5662 deployed, then rolled back): - An RPC ack as `Administrator` returns OK / hresult 0. `.Acked=True`, `.AckMsg` = the comment. - Historian `ACK_ALM` row: `Operator=Administrator, DomainName=ArchestrA, UserFullName=Administrator, OperatorNode=MxGateway, Description=<comment>`. - Wrong password returns MXACCESS_FAILURE "Operator authentication failed"; the alarm stays unacked, no ack row is written, and the password has 0 hits in the gateway log, stdout and stderr. - InTouch provider returns INVALID_REQUEST. Empty user returns InvalidArgument. - **Not driven live:** the GUID arm. The public RPCs expose only full references, so it is covered by unit tests only. ## Deploy notes found on windev (not changed by this PR) - The current Secrets library rejects a relative `Secrets:SqlitePath`, or one inside the content root. The old live `appsettings.json` used `mxgateway-secrets.db`, so the test deploy moved the store to `C:\publish\mxaccessgw\secrets\`. - `NU1903` (GHSA-846f-f764-76mx) on transitive `System.Security.Cryptography.Pkcs` 9.0.4 now fails `dotnet restore` on windev because of `TreatWarningsAsErrors`. This also affects `main`. https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

dohertj2 added 21 commits 2026-10-19 20:09:34 -04:00

docs(plan): AckMsg-as-operator alarm acknowledgement plan ... bf4b9c6c09

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

feat(contracts): carry operator credentials on alarm acknowledgement ... a94b502ce6

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

feat(worker): attribute alarm ack transitions from wnwrap ACK fields ... 64dc1215fd

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

feat(worker): acknowledge alarms via authenticated AckMsg write ... 76db822df3

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

fix(worker): disambiguate MxStatusCategory in AlarmAckWriter ... 7900df3dce

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

fix(worker): handle AckMsg add/advise/write COM failures and server death ... 8199553734

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

refactor(worker): alarm consumers resolve the AckMsg item instead of acking ... 0d4b2aea2d

IMxAccessAlarmConsumer.ResolveAckTarget/ResolveAckTargetByName replace AcknowledgeByGuid/AcknowledgeByName. wnwrap maps Galaxy-provider alarms to <tag>.AckMsg and drops its inert parallel ack consumer; subtag resolves to the target's AckCommentSubtag and no longer advises or writes it; ISubtagAlarmSource.Write is removed. Does not build alone: AlarmDispatcher moves to the new API in the next commit.

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

feat(worker): route alarm acks through the operator-authenticated AckMsg writer ... d6db0ff40d

AlarmCommandHandler -> AlarmDispatcher -> IAlarmAckWriter: the dispatcher resolves the ack item through the consumer and the writer authenticates the operator and writes the comment. The executor builds AlarmAckOperator from operator_user/domain/password, maps AlarmAckOutcome to the reply (Applied/Unconfirmed Ok, AlarmNotFound/NotAckable InvalidRequest, AuthenticationFailed/WriteRejected MxaccessFailure) and reports escaping exceptions by type and HRESULT only, so operator_password cannot leak. Removes the inert managed/WNAL alarm-client ack path.

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

feat(gateway): forward operator credentials on alarm acknowledgement ... 2858e42e80

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

docs: alarm acknowledgement writes AckMsg as the authenticated operator ... 9409488008

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

feat(go-client): operator credentials on acknowledge-alarm ... cfe9f817a3

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

feat(rust-client): operator credentials on acknowledge-alarm ... 417a47bdb5

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

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

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

fix(java-client): redact operator password on async acknowledge-alarm failures ... 9907a97cb0

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

feat(dotnet-client): operator credentials on acknowledge-alarm ... e8ace39418

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

docs(dotnet-client): keep XML docs with their CLI members ... 0143591858

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

feat(python-client): operator credentials on acknowledge-alarm ... 7b81cb7f72

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

fix(python-client): redact operator password from AcknowledgeAlarmReply errors ... 027cc7393d

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

docs: address Task 12 review (supersede stale ack steps, outcome rows) ... 1998ee3e20

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

fix: address final ackmsg-as-operator review findings ... e7f56622c1

- AlarmAckWriter: classify AuthenticateUser and AddItem/Advise/Write
  failures by HRESULT for any interop exception (ArgumentException for
  E_INVALIDARG, UnauthorizedAccessException, COMException); server-gone
  HRESULTs at AuthenticateUser tear down the registration and report
  WriteRejected.
- Bound the ack item cache with a 256-entry LRU (eviction best-effort
  UnAdvise+RemoveItem).
- After an Unconfirmed ack, drop and re-add the item before the next
  write so a late OnWriteComplete on the old handle is not credited.
- Pass StaRuntime.PumpPendingMessages to the ack writer through a
  pump-aware alarm handler factory so long completion waits refresh the
  STA watchdog heartbeat.
- Rust CLI: --operator is required for acknowledge-alarm.
- Docs: full ack status table, credential-oracle trade-off, upgrade note.

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

docs: record gateway-level live verification of AckMsg-as-operator acks ... 3e988ede88

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

dohertj2 referenced this pull request 2026-10-20 07:04:21 -04:00

AlarmAckWriter: broad ArgumentException filter reports programming errors as auth/write failures #164

dohertj2 referenced this pull request 2026-10-20 07:04:21 -04:00

AlarmAckWriter: write-completion cache keeps entries for dropped item handles #165

dohertj2 referenced this pull request 2026-10-20 07:04:22 -04:00

AlarmAckWriter: stale late write completion can be credited to the next ack if MXAccess reuses an item handle number #166

dohertj2 added 3 commits 2026-10-20 07:15:17 -04:00

fix(worker): narrow AlarmAckWriter ArgumentException interop filter ... 219611c821

Resolve the operator user, password and comment before the interop try
blocks, and match ArgumentException as an MXAccess failure only when it
carries E_INVALIDARG and is not ArgumentNullException or
ArgumentOutOfRangeException. A programming error inside the try blocks
now propagates instead of being reported as an authentication or write
failure.

Fixes #164

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

fix(worker): forget write-completion entries for dropped ack item handles ... f13950e453

Add MxAccessWriteCompletionCache.Remove and RemoveServer and call them
from AlarmAckWriter when it drops an item (dirty re-add, LRU eviction,
failed AddItem/Advise/Write) and when it tears down its registration, so
the cache no longer keeps one entry per dropped handle for the life of
the worker.

Fixes #165

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

docs(worker): record live item-handle-reuse probe for ack writer ... bd82036d5f

Add the Skip-gated ItemHandleReuseProbeTests probe and its windev result
(2026-10-20): within one MXAccess registration, item handles increase
monotonically and are never reused across remove/re-add, so the ack
writer's Unconfirmed drop-and-re-add mitigation holds and no per-handle
generation counter is needed. Numbering restarts only on a new
registration, which teardown already isolates. Document the guarantee at
the Dirty re-add and in AlarmProbeFindings.md.

Fixes #166

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

dohertj2 added 1 commit 2026-10-20 07:28:29 -04:00

fix(worker): classify ack interop failures at the COM call; ignore late completions ... 463748e395

Address review of the #164-#166 fixes:

- The HRESULT check could not tell interop from programming errors
  (a managed ArgumentException already defaults to 0x80070057). Wrap each
  MXAccess call (AuthenticateUser, AddItem, Advise, Write) in a narrow
  filter that converts an interop failure to a private marker exception,
  and catch only that marker, so exceptions from the writer's own code
  (argument checks, caching, the pump) propagate.
- A late OnWriteComplete for a dropped handle recreated the cache entry
  that DropItem removed. The writer now records completions only for item
  handles it holds on its live registration.
- The item-handle-reuse probe now asserts that handles within one
  registration strictly increase, so a rerun is a regression check.

Refs #164, #165, #166

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

dohertj2 added 1 commit 2026-10-20 07:28:50 -04:00

Merge branch 'main' into feat/ackmsg-as-operator ... 02228b2717

Picks up the System.Security.Cryptography.Pkcs 10.0.13 pin (NU1903).

Claude-Session: https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

dohertj2 referenced this pull request 2026-10-20 07:29:01 -04:00

AlarmAckWriter: broad ArgumentException filter reports programming errors as auth/write failures #164

dohertj2 referenced this pull request 2026-10-20 07:29:01 -04:00

AlarmAckWriter: write-completion cache keeps entries for dropped item handles #165

dohertj2 referenced this pull request 2026-10-20 07:29:01 -04:00

AlarmAckWriter: stale late write completion can be credited to the next ack if MXAccess reuses an item handle number #166

dohertj2 referenced this issue from a commit 2026-10-20 08:52:23 -04:00

Merge branch 'feat/ackmsg-as-operator' into main (PR #162)

dohertj2 commented 2026-10-20 08:53:00 -04:00

Author

Owner

Copy Link

Copy Source

Merged into main as 488649c (merge of 02228b2, which windev verified in live mode: Worker.Tests 585/0, gateway 1216/0, live MXAccess 8/0). Closing by hand because the repo does not allow the manually-merged style.

https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

Merged into main as 488649c (merge of 02228b2, which windev verified in live mode: Worker.Tests 585/0, gateway 1216/0, live MXAccess 8/0). Closing by hand because the repo does not allow the manually-merged style. https://claude.ai/code/session_016J6isfcgqy4SB2RK3ZvFvT

dohertj2 closed this pull request 2026-10-20 08:53:00 -04:00

Some checks are pending

Hide all checks

ci / nightly-windev (push) Has been skipped

Details

ci / java (push) Successful in 2m7s

Details

ci / java (pull_request) Successful in 2m18s

Details

ci / nightly-windev (pull_request) Has been skipped

Details

ci / portable (push) Failing after 4m47s

Details

ci / windows-x86 (pull_request) Successful in 2m40s

Details

ci / portable (pull_request) Failing after 4m43s

Details

ci / windows-x86 (push) Successful in 5m38s

Details

Pull request closed

Please reopen this pull request to perform a merge.

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

area:auth

Authentication and authorization

area:client-dotnet

.NET client library

area:client-go

Go client library

area:client-java

Java client library

area:client-python

Python client library

area:client-rust

Rust client library

area:contracts

Protocol and generated contract work

area:dashboard

Blazor dashboard work

area:docs

Documentation

area:gateway

Gateway server work

area:tests

Automated and live tests

area:worker

MXAccess worker process work

blocked

Blocked by dependency

priority:p0

Must-have / blocking

priority:p1

High priority

priority:p2

Normal priority

type:docs

Documentation work

type:feature

Feature implementation

type:infra

Infrastructure and scaffolding

type:test

Test work

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

dohertj2 (dohertj2)

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: dohertj2/mxaccessgw#162