ScadaBridge/docs/plans/2026-06-18-m7-opcua-mxgateway-ux-design.md

# 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 <N> --file <path.csv>`.

### 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 -- <paths>`, 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.