lmxopcua/docs/plans/2026-06-19-cert-audit-and-probe-deadletter-tidy-design.md

Cert-action audit logging + OpcUaProbeResult dead-letter tidy — Design

Date: 2026-06-19 Status: Approved (brainstorming) Branch: feat/cert-audit-and-probe-tidy (off master 40e8a23e)

Two independent, self-contained backlog items, batched into one branch.

• Item 1 — Cert-action audit logging (stillpending.md §A.7 deferred follow-up): the meaty one. Standard complexity.
• Item 2 — OpcUaProbeResult dead-letter tidy (Phase-4 final-integration-review follow-up (i)): trivial actor hygiene.

Hard guardrails (both): no EF migration, no Commons/proto/interface change, no bUnit. Stage by explicit path; never stage the never-stage files (sql_login.txt, Host/pki/, docker-dev/docker-compose.yml, pending.md, current.md, stillpending.md). No --no-verify, no force-push. Finish = merge to master + push.

---

Background: H2 was reclassified, then this was chosen

The session began on the "within-timestamp tie-cluster paging (#400)" follow-up — found already shipped (2e6c6d3a/0f929ae6, 2026-06-17); reconciled the stale pending.md banners. Then surveyed the backlog: the only genuinely-OPEN §A item, H2 (OPC UA HistoryUpdate service), was reclassified infra-gated/DEFERRED (no historian backend can durably insert/replace/delete — IHistorianDataSource is read-only and the Wonderware sidecar has no update RPC; same boundary as H5b). The two remaining actionable, in-repo, non-infra items are the two below.

---

Item 1 — Cert-action audit logging

Problem

When a FleetAdmin Trusts / Untrusts / Deletes a peer certificate (Certificates.razor → CertificateStoreManager), nothing is written to the audit DB. Today only certificate validation is logged (to Serilog). These are security-relevant mutations and should leave a durable audit trail.

Key discovery that shapes the design

OtOpcUa has no live structured AuditEvent emit sites yet. The Security/AuditActor helper is explicitly forward-looking ("tested and ready so future emit sites pick up the correct Actor automatically"), and IAuditWriter is not registered as an injectable DI service anywhere. But the persistence path exists end-to-end:

• AuditWriterActor (an AdminRole cluster singleton, ControlPlane/Audit/) implements IAuditWriter (from the external ZB.MOM.WW.Audit package), batches AuditEvents, and bulk-inserts into the existing ConfigAuditLog table (filtered-unique-index dedup on EventId).
• AdminUI already reaches an AdminRole singleton from the ActorRegistry: AdminOperationsClient does registry.Get<AdminOperationsActorKey>(). Same pattern works for AuditWriterActorKey.

So this is the first structured emit site — exactly what the infra was built for. The ConfigAuditLog table and AuditWriterActor already exist ⇒ no EF migration, no Commons change.

Components

1. ActorAuditWriter : IAuditWriter — new, AdminUI/Audit/ActorAuditWriter.cs. Holds the AuditWriterActorKey singleton-proxy IActorRef (resolved from ActorRegistry, mirroring AdminOperationsClient); WriteAsync(evt, ct) does _proxy.Tell(evt) and returns Task.CompletedTask (best-effort, non-blocking — the actor owns batching/dedup/flush). Registered AddSingleton<IAuditWriter, ActorAuditWriter>() in the AdminUI DI extension.

2. CertAuditEvents.Build(action, store, thumbprint, actor, success, error) → AuditEvent — new, AdminUI/Audit/CertAuditEvents.cs. Pure static factory:

   • Category = "Certificate", Action ∈ {Trust, Untrust, Delete}
   • SourceNode = thumbprint
   • DetailsJson = compact JSON { "store": …, "thumbprint": …, "error": …? }
   • Outcome = Success / Failure (from success)
   • Actor = actor, fresh EventId, OccurredAtUtc = DateTimeOffset.UtcNow Pure ⇒ fully unit-testable; the implementer confirms the exact AuditEvent required / optional fields + the AuditOutcome enum member names against the ZB.MOM.WW.Audit package.

3. CertificateStoreManager — modify. Audit at the choke point (the thing that performs the mutation; already has a unit-test class — far more testable than the razor, which has no bUnit). Each public method gains the actor string and emits the event from the CertActionResult it already computes:

   • Trust(string thumbprint, string actor)
   • Untrust(string thumbprint, string actor)
   • Delete(string store, string thumbprint, string actor) Production ctor gains IAuditWriter _audit; the internal test ctor defaults it to a null/fake writer so existing tests compile. Each method calls _audit.WriteAsync(CertAuditEvents.Build(...)) (non-blocking) — including the not-found / invalid-thumbprint failure paths (audited with Outcome = Failure).

4. Certificates.razor — modify. Pass the authenticated principal name into the manager calls: authState.User.Identity?.Name ?? "system" (already fetched at the FleetAdmin re-check, ~line 185). Sourcing the actor from AuthenticationState (not the scoped IAuditActorAccessor/HttpContext) avoids the Blazor-Server HttpContext-null pitfall over the SignalR circuit.

Data flow

FleetAdmin clicks Trust
  → Certificates.razor RequestAction  (FleetAdmin re-checked)
  → CertManager.Trust(thumbprint, actor)
      → filesystem move (rejected → trusted)          [unchanged]
      → CertAuditEvents.Build(Trust, store, thumbprint, actor, success, error)
      → IAuditWriter.WriteAsync(evt)  (= ActorAuditWriter → proxy.Tell)
  → AuditWriterActor batches → bulk insert → ConfigAuditLog

Both success and failure are audited (Outcome reflects result.Success).

Testing (xUnit + Shouldly; no bUnit)

• CertAuditEventsTests — factory output for trust/untrust/delete × success/failure: Category, Action, SourceNode, Outcome, DetailsJson shape.
• Extend CertificateStoreManagerTests — inject a recording fake IAuditWriter; assert exactly one event per action with the correct Action + Outcome, including the not-found failure path.
• ActorAuditWriterTests — a TestKit probe registered under AuditWriterActorKey receives the Tell'd AuditEvent.
• Razor wiring proven by dotnet build + a live docker-dev /run (login disabled on the local rig — agent drives it; deploy, perform a Trust/Untrust on the Certificates page, confirm a new ConfigAuditLog row).

Classification: standard (additive DI + first structured emit path; multi-file).

---

Item 2 — OpcUaProbeResult dead-letter tidy

Problem

DriverHostActor, HistorianAdapterActor, ScriptedAlarmHostActor subscribe the redundancy-state topic (for state changes) but have no handler for the co-published PeerOpcUaProbeActor.OpcUaProbeResult, so each INFO-dead-letters that message (benign, capped at 10 then 5-min-suppressed, but noisy).

Change

Add Receive<PeerOpcUaProbeActor.OpcUaProbeResult>(_ => { }) to each of the three actors — the exact intentional-drop pattern already used by PeerProbeSupervisor.cs:69 and OpcUaPublishActor (which actually consumes it). ~3 lines + a one-line doc comment each. The implementer confirms each actor's topic subscription before adding the drop.

Testing

A dead-letter probe test (EventStream / AllDeadLetters) asserting that an OpcUaProbeResult published to the redundancy topic produces no dead-letter for each actor — mirrors the existing Phase-B dead-letter-probe test idiom.

Classification: trivial → small (mechanical drop handler + one guard test).

---

Execution

Subagent-driven (this session). Item 1 and Item 2 touch disjoint files ⇒ their implementers can be dispatched concurrently. Item 1 gets spec + code review (standard); Item 2 gets a code review (small). Final integration review before finish. Finish = merge to master + push.