# Audit — current state: OtOpcUa

Repo: `~/Desktop/OtOpcUa` (Gitea `lmxopcua`). Stack: .NET 10, Akka.NET cluster, EF Core + SQL Server.
All paths below are relative to the repo root. Verified against source on 2026-06-01.

OtOpcUa already has a structured, idempotent audit pipeline: a cluster-broadcast `AuditEvent`
message, a cluster-singleton writer actor that batches and bulk-inserts, and an append-only
`ConfigAuditLog` EF entity with two-layer dedup. There is **also** a second, older write path —
SQL stored procedures that `INSERT dbo.ConfigAuditLog` directly — so the table has two
producers with slightly different column conventions (see §1).

## 1. How it works today

**Record shape** — `src/Core/ZB.MOM.WW.OtOpcUa.Commons/Messages/Audit/AuditEvent.cs:9-17`:
a sealed record `AuditEvent(Guid EventId, string Category, string Action, string Actor,
DateTime OccurredAtUtc, string? DetailsJson, NodeId SourceNode, CorrelationId CorrelationId)`.
`NodeId` and `CorrelationId` are Commons value-types — `NodeId` wraps a string (the *logical
cluster node / host name*, explicitly **not** an OPC UA NodeId per its XML doc,
`src/Core/ZB.MOM.WW.OtOpcUa.Commons/Types/NodeId.cs:3-8`); `CorrelationId` wraps a `Guid`
(`src/Core/ZB.MOM.WW.OtOpcUa.Commons/Types/CorrelationId.cs:3`).

**Transport** — `AuditEvent` is an Akka message meant to be sent to the `AuditWriterActor`
**cluster singleton** (`AuditEvent.cs:6` describes it as "cluster-broadcast … consumed by the
`AuditWriterActor` singleton"). The singleton is registered through Akka.Hosting at
`src/Server/ZB.MOM.WW.OtOpcUa.ControlPlane/ServiceCollectionExtensions.cs:68-75`
(`WithSingleton<AuditWriterActorKey>(AuditWriterSingletonName, …)`). Any cluster member can
emit an `AuditEvent`; the singleton is the one sink that persists it.

**Storage** — EF entity `ConfigAuditLog`
(`src/Core/ZB.MOM.WW.OtOpcUa.Configuration/Entities/ConfigAuditLog.cs:7-44`): append-only
("Grants revoked for UPDATE/DELETE on all principals", `ConfigAuditLog.cs:4-5`). Columns:
`AuditId` (identity PK), `Timestamp` (default `SYSUTCDATETIME()`), `Principal`, `EventType`,
`ClusterId?`, `NodeId?`, `GenerationId?`, `DetailsJson?`, `EventId?` (Guid), `CorrelationId?`
(Guid). Mapping/constraints in `OtOpcUaConfigDbContext.cs:429-463`: `DetailsJson` must be valid
JSON (`CK_ConfigAuditLog_DetailsJson_IsJson`, line 435-436); `Principal`/`EventType`/`ClusterId`/`NodeId`
length-capped (lines 441-444); supporting indexes `IX_ConfigAuditLog_Cluster_Time` (line 449-451)
and `IX_ConfigAuditLog_Generation` (line 452-454).

**Writer / batching** — `src/Server/ZB.MOM.WW.OtOpcUa.ControlPlane/Audit/AuditWriterActor.cs`:
a `ReceiveActor` with `FlushBatchSize = 500` (line 25) and `FlushInterval = 5s` (line 26).
It buffers events in a `Dictionary<Guid, AuditEvent>` keyed by `EventId` (line 30), flushing
when the buffer hits 500 (line 60), when the 5s periodic timer fires (`PreStart`, line 50-53),
or on `PreRestart`/`PostStop` (lines 96-107) so a supervisor swap or coordinated shutdown does
not lose the buffer. `FlushBuffer` (lines 63-93) snapshots and clears the buffer, then for each
event constructs a `ConfigAuditLog` row (lines 75-84): `Timestamp = OccurredAtUtc`,
`Principal = Actor`, `EventType = $"{Category}:{Action}"`, `NodeId = SourceNode.Value`,
`DetailsJson`, `EventId`, `CorrelationId = CorrelationId.Value`. A failed flush is logged and the
batch is **dropped** (`catch` at lines 89-92) — best-effort, no retry/dead-letter.

**Dedup / idempotency (two layers)** — described at `AuditWriterActor.cs:17-21`:
1. *In-buffer* — duplicate `EventId`s within a batch collapse via the dictionary (last-write-wins;
   `HandleEvent`, lines 55-61).
2. *Database* — a **filtered unique index** `UX_ConfigAuditLog_EventId` (`OtOpcUaConfigDbContext.cs:459-462`,
   `IsUnique()` + `HasFilter("[EventId] IS NOT NULL")`) gives cross-restart safety: a retry of an
   already-flushed batch hits the constraint, the duplicate insert is dropped, and the rest of the
   batch survives. `EventId`/`CorrelationId` are nullable so legacy/backfill rows (NULL) don't
   collide — confirmed in the entity XML (`ConfigAuditLog.cs:33-43`) and migration
   `Migrations/20260526105027_AddConfigAuditLogEventIdColumns.cs:26-31`.

**Scope** — two producers, two conventions:
- **Akka `AuditEvent` path** (the structured one): config writes + authorization checks. The
  EventType vocabulary lives in the entity XML doc (`ConfigAuditLog.cs:18`): `DraftCreated |
  DraftEdited | Published | RolledBack | NodeApplied | CredentialAdded | CredentialDisabled |
  ClusterCreated | NodeAdded | ExternalIdReleased | CrossClusterNamespaceAttempt |
  OpcUaAccessDenied | …`. Note the access-denied / cross-cluster entries are authz-check events,
  not config writes.
- **SQL stored-procedure path** (older, still present): several SPs `INSERT dbo.ConfigAuditLog`
  directly — e.g. `Published`/`RolledBack`/`NodeApplied`/`ExternalIdReleased`/`CrossClusterNamespaceAttempt`
  in `Migrations/20260417215224_StoredProcedures.cs:151,217,351,407,504`. These use `SUSER_SNAME()`
  as `Principal`, set `ClusterId`/`GenerationId`, write a **bare** `EventType` (no `Category:Action`
  split), and leave `EventId`/`CorrelationId` NULL.

**Query / UI** — the only read surface is the Admin UI page
`src/Server/ZB.MOM.WW.OtOpcUa.AdminUI/Components/Pages/Clusters/ClusterAudit.razor`
(`@page "/clusters/{ClusterId}/audit"`, `[Authorize]`, lines 1-2). It reads the latest
`PageSize = 200` rows (line 69) **filtered by `ClusterId`**, newest-first (`OnInitializedAsync`,
lines 74-82), and renders Timestamp / Principal / Event(Type) / Node / Correlation(first 8 hex) /
Details columns (lines 38-58). Tested in
`tests/Server/ZB.MOM.WW.OtOpcUa.ControlPlane.Tests/AuditWriterActorTests.cs`: count-threshold
flush (lines 26-41), in-buffer dedup of duplicate EventIds (lines 45-62), `PostStop` flush
(lines 66-81), and the column mapping incl. `EventType == "Config:Edit"` and `NodeId == "node-a"`
(lines 85-104).

> Load-bearing gotcha: the actor path **never sets `ClusterId`** (lines 75-84), but the UI filters
> on `ClusterId` (`ClusterAudit.razor:78`). So today the cluster-scoped view surfaces the
> stored-procedure rows; structured `AuditEvent` rows written by the actor (which carry the host in
> `NodeId`, not `ClusterId`) won't appear under a cluster. Worth flagging during normalization.

## 2. Mapping to the canonical `AuditEvent`

Target = `ZB.MOM.WW.Audit.AuditEvent` (built in parallel). OtOpcUa's existing `AuditEvent` is
already almost field-for-field aligned; the only synthesized field is `Outcome`.

| Canonical field | OtOpcUa source | Mapping |
|---|---|---|
| `Guid EventId` | `AuditEvent.EventId` | Direct. Already the idempotency key (buffer key + `UX_ConfigAuditLog_EventId`). |
| `DateTimeOffset OccurredAtUtc` | `AuditEvent.OccurredAtUtc` (`DateTime`) | Direct; widen `DateTime`(UTC) → `DateTimeOffset`. |
| `string Actor` | `AuditEvent.Actor` | Direct (→ `ConfigAuditLog.Principal`). At Auth adoption this becomes the `ZB.MOM.WW.Auth` principal. |
| `string Action` | `AuditEvent.Action` (+ `Category`) | Direct. Today persisted as `"{Category}:{Action}"` in `EventType`; canonical keeps `Action` and `Category` separate. |
| `AuditOutcome Outcome` | *(none)* | **Derived** from the EventType vocabulary, not stored today. `OpcUaAccessDenied`/`CrossClusterNamespaceAttempt` → `Denied`; the config-write verbs → `Success`. No explicit `Failure` value exists yet (a failed flush is dropped, not recorded as an event). |
| `string? Category` | `AuditEvent.Category` | Direct (e.g. `"Config"`). |
| `string? Target` | *(none)* | No dedicated field today; the closest is `SourceNode`→`NodeId` (the acting host) or details. Leave null or carry the affected object in `DetailsJson`. |
| `string? SourceNode` | `AuditEvent.SourceNode` (`NodeId.Value`) | Direct — the logical cluster node / host name (NOT an OPC UA NodeId). Currently lands in `ConfigAuditLog.NodeId`. |
| `Guid? CorrelationId` | `AuditEvent.CorrelationId` (`CorrelationId.Value`) | Direct. |
| `string? DetailsJson` | `AuditEvent.DetailsJson` | Direct; carries everything else (incl. `ClusterId`/`GenerationId`, which today are separate columns on the SP path). |

## 3. Adoption plan → `ZB.MOM.WW.Audit`

**Effort: medium.** OtOpcUa is the *donor* design for the canonical record, so most of the work is
re-pointing types and bridging two persistence conventions, not redesigning the pipeline.

**Replace with the shared library:**
- `Commons/Messages/Audit/AuditEvent.cs` → the canonical `ZB.MOM.WW.Audit.AuditEvent`. Add the new
  `Outcome` field (derive it at every emit site from the EventType vocabulary, e.g.
  `OpcUaAccessDenied → Denied`); keep `Category`/`Action`/`SourceNode`/`CorrelationId` as-is. Decide
  whether `SourceNode`/`CorrelationId` carry the Commons value-types or the canonical primitives at
  the seam (likely a thin adapter at construction).
- `AuditWriterActor` → implement the library's `IAuditWriter` (keep the actor as OtOpcUa's
  Akka-cluster-singleton transport/batching adapter behind that seam; the 500/5s batching,
  PreRestart/PostStop flush, and two-layer dedup stay bespoke per §"left per-project").

**Keep bespoke (thin adapter only):**
- Transport — the cluster-broadcast → singleton `AuditWriterActor`, batching, and flush triggers.
- Storage — the `ConfigAuditLog` EF entity, indexes, and `UX_ConfigAuditLog_EventId` idempotency
  index. Map the canonical record onto the existing columns; add an `Outcome` column (or fold it into
  `EventType`/`DetailsJson` if a schema change is undesirable). `ClusterId`/`GenerationId` remain
  OtOpcUa-specific columns fed via `DetailsJson` or kept as side columns.
- Domain vocabulary — the EventType strings (`DraftCreated`, `Published`, `OpcUaAccessDenied`, …)
  and the `Category:Action` composition convention.
- Query/UI — `ClusterAudit.razor` and its `ClusterId` filter.

**Reconcile, not extract:**
- The **two producers** (Akka `AuditEvent` path vs. SQL stored-procedure `INSERT`s using
  `SUSER_SNAME()`). The SP path bypasses the canonical record entirely and writes a different
  column convention (bare `EventType`, NULL `EventId`/`CorrelationId`, populated
  `ClusterId`/`GenerationId`). Adopting the library does not by itself unify these; either route the
  SP events through the actor or accept that SP rows stay non-idempotent and absent from the
  `EventId` dedup guarantee. Flag for the normalization spec.
- The **`ClusterId`-filter / actor-never-sets-`ClusterId`** mismatch noted in §1 — fix when the
  query surface is normalized so structured `AuditEvent` rows are discoverable by cluster.