scadaproj/code-reviews/Audit/findings.md

Code Review — Audit

Field	Value
Library	ZB.MOM.WW.Audit/
Packages	ZB.MOM.WW.Audit
Component spec	components/audit/spec/SPEC.md
Shared contract	components/audit/shared-contract/ZB.MOM.WW.Audit.md
Status	Reviewed
Last reviewed	2026-06-01
Reviewer	Claude (automated baseline)
Commit reviewed	5f75cd4
Open findings	0

Summary

ZB.MOM.WW.Audit is a small, clean, well-scoped library: one canonical AuditEvent sealed record, a 3-value AuditOutcome enum, two narrow seams (IAuditWriter, IAuditRedactor), five shipped helpers, and a single AddZbAudit registration. The record matches EVENT-MODEL.md field-for-field (names, types, required/optional split, and the OccurredAtUtc UTC-normalization contract — including value-equality on the normalized instant). The dependency footprint is exactly as specified: the only non-BCL reference is Microsoft.Extensions.DependencyInjection.Abstractions (verified against the built deps.json), with no Akka/EF/SQLite/Serilog/Telemetry leakage. Guard clauses are present on every public entry point, RedactingAuditWriter guarantees redaction runs before the inner writer (no unredacted-PII leak), and CompositeAuditWriter isolates per-writer failures so a throwing writer does not lose downstream events. 19 tests cover the happy paths and the most important contract guards. No Critical or High findings. The five findings are all Medium/Low and concern: a cancellation-propagation tension with the "never throw to the caller" writer contract (Audit-001), a partial over-redaction path in TruncatingAuditRedactor (Audit-002), mutable options on a singleton redactor (Audit-003), un-emitted XML docs (Audit-004, a family-wide baseline pattern), and a couple of missing edge-case tests (Audit-005).

Checklist coverage

#	Category	Examined	Notes
1	Correctness & logic bugs	☑	Truncate boundary logic correct for sane configs; marker-longer-than-max clips safely. Partial over-redaction edge under negative max → Audit-002.
2	Public API surface & compatibility	☑	Minimal, intentional surface; sealed records/classes; nullable annotations correct; no internal-type leakage. Options type is a mutable class, not the record the contract describes → Audit-003.
3	Concurrency & thread safety	☑	AuditEvent immutable (readonly backing field); singletons (NoOp/Null) stateless; composite snapshots its writers via ToArray(). Mutable singleton options noted in Audit-003.
4	Error handling & resilience	☑	Guard clauses on all entry points; composite swallows writer faults. OCE re-throw vs writer contract → Audit-001; partial over-redact → Audit-002.
5	Security & secret handling	☑	RedactingAuditWriter applies the redactor strictly before the inner writer — no unredacted-event leak. Actor kept a plain string (no Auth coupling), as specified. No secrets in code/messages.
6	Performance & resource management	☑	No IDisposable to manage; no hot-path allocations beyond a single with-copy per redact; DI registration is trivial. No issues found.
7	Spec & shared-contract adherence	☑	AuditEvent + AuditOutcome match EVENT-MODEL.md exactly; AddZbAudit uses TryAdd as specified. OCE re-throw deviates from the §1 writer hard rule → Audit-001.
8	Packaging, dependencies & project layout	☑	Sole non-BCL dep confirmed via deps.json; net10.0; correct PackageId/version (0.1.0). XML docs not packed → Audit-004.
9	Testing coverage	☑	19 tests; public contract exercised (round-trip, UTC normalization, fan-out, cancellation, redaction ordering). Missing never-throw/over-redact and null-writer cases → Audit-005.
10	Documentation & XML docs	☑	XML docs present and accurate on the whole public surface; README accurate. Docs not emitted to a file → Audit-004.

Findings

Audit-001 — CompositeAuditWriter re-throws OperationCanceledException to the caller, contradicting the "must not throw" writer contract

Severity	Medium
Category	Error handling & resilience
Status	Resolved
Location	ZB.MOM.WW.Audit/src/ZB.MOM.WW.Audit/CompositeAuditWriter.cs:24

Description

IAuditWriter's hard contract is unambiguous: "Best-effort; must not throw to the caller" (IAuditWriter.cs:11), and SPEC §1 states "WriteAsync MUST NOT throw to the caller … a failed write must never abort the user-facing action it is recording." The shared contract further says a cancellation "does not constitute a contract violation" and the implementation "may choose to complete a partially-written event anyway" — it permits ignoring the token, not throwing on it.

CompositeAuditWriter.WriteAsync re-throws OperationCanceledException (catch (OperationCanceledException) { throw; }, line 24). The very common call shape is to pass the ambient request token, e.g. writer.WriteAsync(evt, httpContext.RequestAborted). When a client disconnects mid-request, the inner writer observes the cancelled token, throws OCE, and the composite propagates it straight into the user-facing action — exactly the abort the seam promises never to cause. This also directly contradicts the helper's own XML doc, which claims "the fan-out drains and the caller is never aborted" (CompositeAuditWriter.cs:4). Because the composite is the recommended way to wire multiple sinks, every consumer that uses it inherits this behaviour; the only workaround is to not pass a request-scoped token, which is non-obvious.

Note this is a deliberate, tested choice (CompositeAuditWriterTests.cs:41), so it is a design/contract conflict rather than an oversight — but the conflict is real: the writer contract says "never throw," the composite says "drains, never aborts," and the code throws on cancellation.

Recommendation

Reconcile the contract and the implementation. Either (a) honour the "never throw" rule literally — swallow OCE like any other writer failure (drop the remaining writers or continue, but do not propagate), and update the XML doc accordingly; or (b) if cancellation propagation is genuinely wanted, amend the IAuditWriter SPEC/shared-contract to carve out OCE explicitly and add a doc warning that consumers must not pass a request-scoped token they cannot afford to see surface. Option (a) is the lower-blast-radius choice and matches the seam's stated intent.

Resolution

Resolved in 544a6dd, 2026-06-01 — CompositeAuditWriter.WriteAsync now swallows OperationCanceledException like any other writer failure (single bare catch), so cancellation never surfaces to the caller; XML doc and the cancellation test updated to assert non-propagation.

Audit-002 — TruncatingAuditRedactor over-redaction is partial: the catch path scrubs only DetailsJson, leaving Target unredacted

Severity	Low
Category	Error handling & resilience
Status	Resolved
Location	ZB.MOM.WW.Audit/src/ZB.MOM.WW.Audit/TruncatingAuditRedactor.cs:27-31, :34-40

Description

The redactor's over-redact fallback returns rawEvent with { DetailsJson = null } (line 30). That scrubs only DetailsJson — Target, which this redactor is also responsible for capping, is carried through untouched. The spec's "over-redact" rule is "returns a strictly safer event" (SPEC §2); leaving an oversized/sensitive Target in place is not strictly safer.

This becomes reachable under misconfiguration. Truncate(value, max) does marker[..max] when marker.Length >= max (line 38). For a negative MaxTargetLength or MaxDetailsJsonLength, that slice throws ArgumentOutOfRangeException, the Apply catch fires, and the result keeps the original, untruncated Target while only nulling DetailsJson. So a config bug that should fail safe instead leaves the Target field unredacted. (max == 0 is handled correctly — marker[..0] is "".) The redactor never throws, so the "must not throw" half of the contract holds; it is the "strictly safer" half that is violated.

Recommendation

Make the fallback strictly safer across the fields this redactor owns, e.g. return rawEvent with { DetailsJson = null, Target = null }; in the catch. Additionally, guard against nonsensical caps at the boundary — clamp max to >= 0 in Truncate (treat negative as 0), or validate the options in the constructor — so the catch path is only ever hit by truly unexpected failures rather than a predictable negative-length misconfiguration.

Resolution

Resolved in 544a6dd, 2026-06-01 — the over-redact catch now returns rawEvent with { DetailsJson = null, Target = null } (strictly safer), and Truncate clamps a negative max to 0 so a negative-length misconfiguration fails safe instead of throwing; new tests pin both behaviours.

Audit-003 — TruncatingAuditRedactorOptions is a mutable class, not the immutable "options record" the contract describes

Severity	Low
Category	Public API surface & compatibility
Status	Resolved
Location	ZB.MOM.WW.Audit/src/ZB.MOM.WW.Audit/TruncatingAuditRedactorOptions.cs:4-12

Description

The shared contract lists TruncatingAuditRedactorOptions as an "Options record" (shared-contract/ZB.MOM.WW.Audit.md:93), but it is implemented as a sealed class with three mutable get; set; auto-properties. TruncatingAuditRedactor captures the instance by reference (_options = options ?? new(...), TruncatingAuditRedactor.cs:14) and the redactor is typically registered as a singleton. Because the options object stays mutable, a caller (or any other holder of the same reference) can change MaxDetailsJsonLength / MaxTargetLength / TruncationMarker after the redactor is built, changing redaction behaviour at runtime under a concurrent host with no synchronization. This is a (minor) thread-safety footgun and a drift from both the documented "record" shape and the library's otherwise consistent immutability posture (AuditEvent is a record with init-only members).

Recommendation

Make the options immutable: convert to a sealed record with init-only properties (matching the contract wording), or have the redactor defensively snapshot the three values into private readonly fields at construction so post-construction mutation cannot affect it.

Resolution

Resolved in 544a6dd, 2026-06-01 — TruncatingAuditRedactorOptions is now a sealed record with init-only properties, matching the contract's "options record" and removing the post-construction mutation footgun on the singleton redactor.

Audit-004 — XML documentation is authored but not emitted, so IntelliSense docs do not ship to consumers

Severity	Low
Category	Documentation & XML docs
Status	Resolved
Location	ZB.MOM.WW.Audit/src/ZB.MOM.WW.Audit/ZB.MOM.WW.Audit.csproj:1-18, ZB.MOM.WW.Audit/Directory.Build.props:1-10

Description

Every public type and member carries accurate XML doc comments, but neither the project nor Directory.Build.props sets GenerateDocumentationFile. As a result no ZB.MOM.WW.Audit.xml is produced or packed alongside the DLL (confirmed: no XML doc file in bin/), so consuming apps get no IntelliSense/tooltip documentation from the package. For a shared library where, per the review process, "public docs matter," the authored docs are effectively invisible to consumers. (This is a family-wide baseline gap — none of the sibling ZB.MOM.WW.* libraries set the flag either — so it is a baseline issue rather than an Audit-specific regression, hence Low.)

Recommendation

Set <GenerateDocumentationFile>true</GenerateDocumentationFile> (ideally once in the shared Directory.Build.props so it applies across the family). Because the public surface is fully documented, no CS1591 "missing XML comment" warnings should appear.

Resolution

Resolved in 544a6dd, 2026-06-01 — set <GenerateDocumentationFile>true</GenerateDocumentationFile> in the packable ZB.MOM.WW.Audit.csproj; ZB.MOM.WW.Audit.xml now builds with zero CS1591 warnings and packs into the nupkg under lib/net10.0/.

Audit-005 — Missing edge-case tests for the redactor never-throw/over-redact contract and composite null/empty handling

Severity	Low
Category	Testing coverage
Status	Resolved
Location	ZB.MOM.WW.Audit/tests/ZB.MOM.WW.Audit.Tests/TruncatingAuditRedactorTests.cs, .../CompositeAuditWriterTests.cs

Description

The 19 tests cover the happy paths and the key guards (UTC normalization + equality, fan-out, cancellation propagation, redaction ordering, marker-longer-than-max). Two contract-critical behaviours are untested:

1. The IAuditRedactor "never throws / over-redacts on failure" contract — no test drives TruncatingAuditRedactor.Apply into its catch branch, so the over-redaction fallback (and the asymmetry flagged in Audit-002) is unverified.
2. CompositeAuditWriter boundary inputs — no test covers an empty writer list (should be a no-op) or a list containing a null writer (currently swallowed via the bare catch, silently dropping that sink — behaviour that should be pinned by a test).

Pinning these would have surfaced Audit-002 and would lock the documented never-throw guarantee.

Recommendation

Add: (a) a redactor test that forces an internal failure (e.g. a misconfigured cap) and asserts Apply returns a strictly-safer event without throwing; (b) a composite test for the empty-list no-op; and (c) a composite test documenting the null-entry behaviour (whether swallowed or guarded — pair with the chosen fix for the null case).

Resolution

Resolved in 544a6dd, 2026-06-01 — added four tests: redactor over-redact catch branch scrubs both fields, negative-max clamp, and CompositeAuditWriter empty-list no-op + null-writer-entry swallow (19 → 23 tests).