From 254e0e729febb467220c6f74cb4b9c45a35b7061 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Thu, 18 Jun 2026 01:44:40 -0400 Subject: [PATCH] =?UTF-8?q?docs(m7):=20approved=20design=20=E2=80=94=20OPC?= =?UTF-8?q?=20UA=20/=20MxGateway=20UX=20(T13-T17)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Full-M7 scope: operator Alarm Summary (per-instance live snapshots), MxGateway secured writes (Operator+Verifier roles + PendingSecuredWrite + central relay), OPC UA BrowseNext paging + bounded recursive search, type-info surfacing + attribute-override CSV import, Verify-endpoint button + site-local cert trust (broadcast to both nodes). Builds on the merged opcua-tag-browser + mxgw-supervisory-write foundations already in main. --- ...2026-06-18-m7-opcua-mxgateway-ux-design.md | 263 ++++++++++++++++++ 1 file changed, 263 insertions(+) create mode 100644 docs/plans/2026-06-18-m7-opcua-mxgateway-ux-design.md diff --git a/docs/plans/2026-06-18-m7-opcua-mxgateway-ux-design.md b/docs/plans/2026-06-18-m7-opcua-mxgateway-ux-design.md new file mode 100644 index 00000000..423bc464 --- /dev/null +++ b/docs/plans/2026-06-18-m7-opcua-mxgateway-ux-design.md @@ -0,0 +1,263 @@ +# Design: M7 — OPC UA / MxGateway UX (T13–T17) + +> Part of the `stillpending.md` completion roadmap (Phase 2 — Expand). Milestone **M7** of +> `docs/plans/2026-06-15-stillpending-completion-design.md`. Native task **#18**. +> Successor to M6 (KPI History, #26 KpiHistory, landed 241a792). + +**Date:** 2026-06-18 +**Branch:** `worktree-m7-opcua-mxgateway-ux` (off `origin/main` @ 241a792) +**Scope decision:** Full M7 — all five features T13–T17. + +--- + +## Goal + +Round out the operator- and design-time UX for native alarms and OPC UA / MxAccess Gateway +data connections: + +- **T13** — a dedicated operator **Alarm Summary** page (cross-instance, read-only). +- **T14** — **MxGateway secured writes**: a two-person (operator initiates, verifier approves) + authorization workflow for writes through the MxAccess Gateway. +- **T15** — OPC UA **address-space search + `BrowseNext` paging** in the node picker. +- **T16** — OPC UA **type-info surfacing** in browse + **bulk instance-override CSV import**. +- **T17** — OPC UA **"Verify endpoint"** connectivity button + **site-local certificate trust**. + +This is a large, multi-theme milestone. It is built on infrastructure that already exists in +`main`: the OPC UA node browser (`NodeBrowserDialog`/`BrowseService`, from the merged +`feat/opcua-tag-browser`) and the MxGateway write path (`MxGatewayDataConnection.WriteAsync`, +from the merged `fix/mxgw-supervisory-write`). M7 does **not** reinvent those — it layers on top. + +## Non-goals / deferred (logged as follow-ups) + +- **Central alarm store / history / journal** — T13 reads live snapshots; no central alarm + tables (remains `[PERM]` per `2026-05-29-native-alarms-design.md`). No aggregated live gRPC + stream for the summary page in v1 (snapshot + poll only). +- **Native-alarm ack / shelve / suppress write-back** — read-only by design, unchanged. +- **CSV bulk import of native-alarm-source overrides** (`InstanceNativeAlarmSourceOverride`) — + the T16 importer targets *attribute* overrides only; native-alarm-source CSV is a follow-up. +- **Central-persisted server-cert trust** — T17 trust is site-local (no central entity/migration). + +--- + +## Locked architecture decisions (from brainstorm) + +| # | Feature | Decision | +|---|---------|----------| +| D1 | **T13 data path** | **Per-instance live snapshots.** Central fans out the existing per-instance `DebugViewSnapshot` Ask to each deployed instance and aggregates client-side. Zero new site-side code; no central store. N round-trips per site (concurrency-capped). | +| D2 | **T14 auth model** | **New global `Operator` + `Verifier` roles** + a dedicated **Secured Writes** page. `PendingSecuredWrite` central entity; central relays approved write to the site MxGateway; both users audited; no self-approval; single-tag first; MxGateway-protocol connections only. | +| D3 | **T15 search** | **`BrowseNext` paging + site-side bounded recursive search** (depth + result caps) matching substring on DisplayName/path. | +| D4 | **T17 cert trust** | **Site-local trust-on-verify** — the operator's Trust decision writes the cert directly into the site's OPC UA trusted-peer PKI store; central does **not** persist it. | +| D5 | **T16 CSV target** | **Instance attribute overrides** (same data as `instance set-overrides` / the InstanceConfigure list editor). Pairs with type-info; reuses existing override validation + handlers (MV-10). | +| D6 | **T17 HA divergence** | **Broadcast `TrustServerCert` to both site nodes** so node-a/node-b PKI stores stay consistent (active-node-only trust would silently fail cert validation after failover). | +| D7 | **T17 role gating** | **Verify = `Design`** (read-only probe); **Trust / Reject / Remove = `Administrator`** (changes a security trust boundary — least privilege). | + +--- + +## Shared infrastructure + +All cross-cluster verbs hang off the **existing request/response pattern** that +`BrowseNodeCommand` already uses: + +``` +CentralUI service + → CommunicationService.XxxAsync(siteId, cmd) + → SiteEnvelope(siteId, cmd) + → CentralCommunicationActor (ClusterClient Ask, QueryTimeout budget) + → SiteCommunicationActor (unwrap, route to site singleton) + → DeploymentManagerActor → DataConnectionManagerActor (index by connection name) + → DataConnectionActor (holds the IDataConnection adapter) + → adapter (RealOpcUaClient / MxGatewayDataConnection) + ← typed response flows back via Sender / PipeTo +``` + +M7 adds these verbs on that path (all additive, mirroring `BrowseCommands.cs` + +`DataConnectionActor.HandleBrowse`): + +- `SearchAddressSpaceCommand` / browse-continuation (T15) +- `VerifyEndpointCommand`, `TrustServerCertCommand`, `ListServerCertsCommand` (T17) +- `ExecuteSecuredWriteCommand` (T14 relay) + +> **Sequencing chokepoint:** the site-side handlers for T14 (execute relay), T15 (search / +> browse-next) and T17 (verify / trust) all add cases to `DataConnectionActor` / +> `DataConnectionManagerActor`. Those edits are serialized within the OPC UA / DCL stream to +> avoid file collisions (see Delivery). + +--- + +## Feature designs + +### T13 — Operator Alarm Summary page *(size: M)* + +- **Page:** new `/monitoring/alarms` (`AlarmSummary.razor`) in the Monitoring nav group, + `RequireDeployment` policy (operator observability, same tier as Event Logs / Parked Messages). +- **Data path (D1):** site selector → query the site's deployed instances (existing + deployment-state query) → fan out the existing per-instance `DebugViewSnapshot` Ask + concurrently (capped via `SemaphoreSlim`), aggregate `AlarmStates` client-side. Partial-results + tolerant: instances that time out are listed as "not reporting", the rest still render. +- **View:** roll-up tiles (total active / worst severity / unacked count / per-`AlarmKind` + counts) + a flat, sortable, filterable table. Filters: instance, `AlarmKind` + (Computed / NativeOpcUa / NativeMxAccess), state (Active/Normal), acked/unacked, severity + threshold, name search. +- **Read-only** — no ack/shelve controls. +- **Reuse:** extract DebugView's inline alarm badge/formatter markup into a shared + `AlarmStateBadges` component consumed by both DebugView and the summary page. +- **Refresh:** manual button + optional poll timer (mirrors Health dashboard 10 s). No + aggregated live stream in v1. +- **Files (indicative):** `Components/Pages/Monitoring/AlarmSummary.razor(.cs)`, a CentralUI + `IAlarmSummaryService`/impl (fan-out + aggregate), `Components/Shared/AlarmStateBadges.razor`, + `NavMenu.razor`, Playwright test. + +### T14 — MxGateway secured writes (operator + verifier) *(size: L — highest risk)* + +- **Roles:** add `Operator` + `Verifier` to `Roles.cs` / `Roles.All`; add `RequireOperator` / + `RequireVerifier` authorization policies; update the LDAP group-mapping seed migration + (idempotent) + the role-mapping UI list. +- **Entity:** `PendingSecuredWrite` (Commons POCO + EF config + migration + regenerated model + snapshot, central MS SQL): + `Id, SiteId, ConnectionName, TagPath, ValueJson, ValueType, + Status {Pending → Approved/Rejected → Executed/Failed/Expired}, + OperatorUser, OperatorComment, SubmittedAtUtc, + VerifierUser, VerifierComment, DecidedAtUtc, + ExecutedAtUtc, ExecutionError`. + Repository interface in Commons + impl in ConfigurationDatabase; registered in the unit of work. +- **ManagementActor handlers / commands:** + - `SubmitSecuredWriteCommand` (Operator) → insert `Pending` row. + - `ApproveSecuredWriteCommand` (Verifier) → enforce `VerifierUser ≠ OperatorUser` + server-side → mark `Approved` → relay `ExecuteSecuredWriteCommand` to the site → record + `Executed`/`Failed` from the `MxWriteOutcome`. + - `RejectSecuredWriteCommand` (Verifier) → `Rejected` + reason. + - List/query pending + history (global + per-site). +- **Site relay:** `ExecuteSecuredWriteCommand(connectionName, tagPath, value, valueType)` → + `SiteEnvelope` → `DataConnectionManagerActor` → `DataConnectionActor` → + `MxGatewayDataConnection.WriteAsync`. Validate **MxGateway protocol** at submit *and* execute. + Mirrors the parked-call Retry/Discard relay. +- **Central UI 'Secured Writes' page** (new nav entry): + - Operator: submit form (site → MxGateway connection → tag path → typed value → comment; + tag pick may reuse the T15 node browser). + - Verifier: pending queue table with Approve / Reject (+comment); own submissions disabled + in the UI *and* rejected server-side. + - History: terminal rows with full who/when/outcome. +- **Audit:** new `AuditKind.SecuredWrite` (+ channel); central direct-write a row per lifecycle + event (Submit / Approve / Reject / Execute), sharing the `PendingSecuredWrite.Id` as + `CorrelationId`, capturing operator + verifier + outcome — the "who approved" trail. Uses the + existing central direct-write path (as Notification Outbox dispatch + Inbound API do). +- **Safety:** Approve shows a confirm dialog with the exact site / connection / tag / value; the + write fires *only* on explicit verifier approval. +- **Dev caveat:** with `DisableLogin` on (docker), `AutoLoginAuthenticationHandler` grants + `Roles.All` to one identity, so the two-person flow cannot be exercised end-to-end via the dev + UI with a single user. No-self-approval is covered by handler-level tests; real two-person use + needs two real identities. + +### T15 — Address-space search + `BrowseNext` paging *(size: M)* + +- **`BrowseNext`:** today `RealOpcUaClient.BrowseChildrenAsync` (~line 763) discards the + continuation point and returns `Truncated = true` ("type the node id manually"). Thread an + opaque base64 continuation token through `BrowseNodeCommand` + `BrowseChildrenResult`; when + present, the site calls `Session.BrowseNext` on the connection's live session. Picker gains a + **"Load more"** affordance. Expired/invalid continuation points fall back to a fresh browse. +- **Search:** new `SearchAddressSpaceCommand(ConnectionName, Query, MaxDepth, MaxResults)` → + site does a **bounded recursive browse** (depth + result caps) matching case-insensitive + substring on DisplayName/path; returns matches with full node ids + paths; UI surfaces + "showing first N — refine" when a cap is hit. New `IAddressSpaceSearchable` capability seam on + the OPC UA adapter; `StubOpcUaClient` gets a canned browse/search impl (it currently throws + `NotImplementedException`, needed for unit/bUnit tests). +- **Central:** `BrowseService.SearchAsync` (Design role) + a search box + results list in + `NodeBrowserDialog` (click a result → select it). + +### T16 — Type-info surfacing + bulk override CSV import *(size: S + M)* + +- **Type-info:** extend the `BrowseNode` record with optional `DataType` (friendly name), + `ValueRank` (scalar/array), `AccessLevel` (read/write). `RealOpcUaClient` batch-reads these + attributes for Variable nodes during browse; `NodeBrowserDialog` shows a Type column. Small + built-in-type nodeid → friendly-name lookup. +- **CSV bulk import (D5 — attribute overrides):** CSV columns `AttributeName, Value, ElementType?` + (`ElementType` only for `List` attributes). Per-row validation against the instance's flattened + attribute schema (name exists + type compatible — reuse the override validation + + `AttributeValueCodec`); collects per-row errors; all-or-nothing upsert with a result summary. + Writes reuse the existing ManagementActor add/update-override handlers (MV-10). Surfaces via: + - `InputFile` upload on the InstanceConfigure page (built-in Blazor; no third-party lib). + - CLI `instance import-overrides --instance-id --file `. + +### T17 — Verify-endpoint + cert-management (site-local) *(size: M + M)* + +- **Verify-endpoint:** `VerifyEndpointCommand(SiteId, protocol, configJson)` → site spins a + **temporary** `RealOpcUaClient` from the submitted config (works for unsaved edits *and* + existing connections), connects (discovery + session) with a short timeout (~5–8 s), then + disconnects; returns `VerifyEndpointResult(Success, FailureKind, Error, ServerCert?)`. The probe + forces `AutoAcceptUntrustedCerts = false` and hooks the certificate-validation event to + **capture** an untrusted server cert (Subject / Issuer / Thumbprint / NotBefore / NotAfter / + DER). Button lives in `OpcUaEndpointEditor` (Design role — D7). +- **Cert trust (D4 site-local + D6 both-nodes):** when verify reports untrusted, the UI shows the + cert detail + a **Trust** button (Administrator role — D7). Trust → `TrustServerCertCommand` + **broadcast to both site nodes** → each node writes the `.der` into its own OPC UA + trusted-peer PKI store; re-verify then succeeds. A small cert-management view lists the site's + trusted/rejected store contents (`ListServerCertsCommand` reading the PKI dirs) with + Trust / Remove (Administrator). No central persistence/migration. +- **Open detail for planning:** the broadcast-to-both-nodes mechanism (per-node actor vs. cluster + broadcast vs. re-apply-on-failover) is settled at plan time; the trust handler must run on each + node because PKI dirs are node-local. + +--- + +## Delivery approach (waves) + +Three mostly-independent streams; full build + docker rebuild + Playwright only at integration. + +1. **Wave A (parallel-safe foundations):** + - **T13** (CentralUI alarm summary + snapshot fan-out + `AlarmStateBadges` extraction). + - **T14a** (Security project: `Operator`/`Verifier` roles, policies, LDAP mapping seed + UI). + These are disjoint from each other and from the OPC UA / DCL files. +2. **Wave B (OPC UA / DCL stream — serialized on `RealOpcUaClient`/`StubOpcUaClient`/`DataConnectionActor`/`BrowseService`):** + - T16-typeinfo → T15 BrowseNext → T15 search → T17 verify → T17 trust (DCL edits in order), + then the UI layers (`NodeBrowserDialog`, `OpcUaEndpointEditor`, `DataConnectionForm`). +3. **Wave C (T14b — depends on T14a):** + - `PendingSecuredWrite` entity + migration → ManagementActor handlers + commands → + site execute-relay (`DataConnectionActor`, merges after Wave B's DCL edits) → + Secured Writes page → `AuditKind.SecuredWrite` wiring. +4. **Integration:** docs (Component-* updates, README/CLAUDE component count stays 26 — no new + component; these are features on existing components), `2026-06-15-stillpending-completion-design.md` + M7 status, full-solution build, `bash docker/deploy.sh`, Playwright, live smoke + (alarm summary renders; secured-write submit→approve relay; browse search/load-more; + verify-endpoint button). + +**Execution conventions (per CLAUDE.md + standing constraints):** dedicated worktree (this one), +pathspec commits (`git commit -- `, never `git add -A`), ≤2–3 concurrent committers with +post-wave HEAD-presence checks, targeted builds/tests per task, full build + docker rebuild only +at integration. `TreatWarningsAsErrors=true` everywhere. + +## Testing strategy + +- **Unit:** T13 alarm aggregation/roll-up + partial-results; T14 no-self-approval + status + transitions + MxGateway-only validation; T15 bounded recursive search + BrowseNext continuation + + stub impl; T16 CSV parse/validate (good + per-row-error corpus) + type-info mapping; + T17 verify-result mapping + cert-store write + both-node broadcast. +- **Integration (against the cluster):** secured-write end-to-end relay; browse / search / + verify round-trips; trust-then-reverify. +- **Playwright:** alarm summary page (filters, roll-up); secured-writes submit → approve → history; + node-browser search + load-more; verify-endpoint button (success + untrusted-cert path). + +## Risks & open items + +- **T14 is the heaviest and most security-sensitive** — writes to live process equipment. Mitigated + by the two-person gate, no-self-approval, confirm dialog, and full audit. High-risk + classification; serial spec→code review + final integration review. +- **OPC UA `BrowseNext` continuation points are session-bound** and can expire/be released — handle + invalid-CP by restarting the browse; never assume a CP survives indefinitely. +- **`StubOpcUaClient` currently throws on browse** — must gain a canned browse/search impl or the + new bUnit/unit tests can't run without a live server. +- **DisableLogin dev caveat** for T14 (single identity gets all roles) — documented above. +- **Cert trust HA** — broadcast-to-both-nodes (D6) chosen; the exact broadcast mechanism is a + plan-time detail. + +## Follow-ups (not in M7) + +- Native-alarm-source-override CSV bulk import (`InstanceNativeAlarmSourceOverride`). +- Aggregated **live** alarm stream for the summary page (vs. snapshot+poll). +- Central-persisted, auditable server-cert trust (supersede the site-local v1) if cross-site + governance is later wanted. + +## Next step + +Hand off to the **writing-plans** skill to produce the bite-sized, classification-tagged +implementation plan (`docs/plans/2026-06-18-m7-opcua-mxgateway-ux.md` + `.tasks.json`), then +execute subagent-driven in this session.