feat(audit)!: remove the AuditLog hash chain, head export and two-login maintenance hardening

Owner decision 2026-11-15, at IT security's request, pending a family-wide general solution.

Removed: the chaining service, hasher, verifier, chain head/tombstone entities and store, the #139
chain-start cutoff, AuditLog:HashChain (incl. ChainBacklog and HeadExport with its File/Syslog sinks
and export service), the audit-chain-head-export health check, the VerifyAuditChain /
VerifyAuditChainHeads management commands and the `audit verify-chain` / `audit verify-heads` CLI
commands, and the two-login plumbing (AuditLog:MaintenanceConnectionString, AuditMaintenanceContext,
the keyed audit-maintenance repository/archive). Purge, archive, retention, partition roll-forward
and backfill-source-node all run on the runtime connection again, as before #107.

Parquet archive (#42) kept, chain-free: format v2 (ten stored columns, no tombstone file, manifest
without chain state), the switch guard is the row count only (51003 gone), verify = data-file size,
SHA-256 and row count, and superseded-stale cleanup proves coverage by EventId. Format-v1 archives
still list, verify and are cleaned up (their tombstone file too).

Migration RemoveAuditLogHashChain drops the chain indexes, the scadabridge_audit_chainer role
(members first), both chain tables, ChainSeq/RowHash and the purger's AuditMaintenanceGrants grants;
writer/purger roles stay. Down restores them. Every chain-column reference is EXEC-deferred for the
idempotent script (#126); FlipAuditLogClusteredKey's two chain index statements get the same
deferral, behaviour unchanged, so re-running the idempotent script on a migrated database works.
The partition-switch staging table adds the chain columns only when the live table has them, so the
new binary purges either schema. Deploy gate: old binaries map the chain columns, so the migration
ships with the new binaries, both centrals stopped.

A leftover AuditLog:HashChain section or MaintenanceConnectionString (DEV/QA still carry
AuditLog__HashChain__Enabled=true) is ignored with one startup warning (RetiredAuditSettingsWarning).

Claude-Session: https://claude.ai/code/session_01GT67AFKC45MBz1wPZnVbX8
This commit is contained in:
Joseph Doherty
2026-11-15 17:37:33 -05:00
parent 125db03232
commit ed2ed0a367
82 changed files with 3203 additions and 7603 deletions
@@ -30,8 +30,6 @@ public sealed class AuditLogArchiveOptionsValidator : OptionsValidatorBase<Audit
$"AuditLog:Archive:{nameof(AuditLogArchiveOptions.RowGroupSize)} ({options.RowGroupSize}) must be between 1000 and 1000000."); $"AuditLog:Archive:{nameof(AuditLogArchiveOptions.RowGroupSize)} ({options.RowGroupSize}) must be between 1000 and 1000000.");
builder.RequireThat(options.ReadCommandTimeoutMinutes > 0, builder.RequireThat(options.ReadCommandTimeoutMinutes > 0,
$"AuditLog:Archive:{nameof(AuditLogArchiveOptions.ReadCommandTimeoutMinutes)} ({options.ReadCommandTimeoutMinutes}) must be > 0."); $"AuditLog:Archive:{nameof(AuditLogArchiveOptions.ReadCommandTimeoutMinutes)} ({options.ReadCommandTimeoutMinutes}) must be > 0.");
builder.RequireThat(options.ChainLockTimeoutSeconds > 0,
$"AuditLog:Archive:{nameof(AuditLogArchiveOptions.ChainLockTimeoutSeconds)} ({options.ChainLockTimeoutSeconds}) must be > 0.");
builder.RequireThat(options.RetentionDays is >= 0 and <= 36_500, builder.RequireThat(options.RetentionDays is >= 0 and <= 36_500,
$"AuditLog:Archive:{nameof(AuditLogArchiveOptions.RetentionDays)} ({options.RetentionDays}) must be between 0 (never delete) and 36500."); $"AuditLog:Archive:{nameof(AuditLogArchiveOptions.RetentionDays)} ({options.RetentionDays}) must be between 0 (never delete) and 36500.");
} }
@@ -1,99 +0,0 @@
using ZB.MOM.WW.Configuration;
using ZB.MOM.WW.ScadaBridge.AuditLog.Central.HeadExport;
namespace ZB.MOM.WW.ScadaBridge.AuditLog.Central;
/// <summary>
/// Options for the central <see cref="AuditLogHashChainService"/> (section
/// <c>AuditLog:HashChain</c>) — hash-chain tamper evidence for the AuditLog
/// (audit roadmap T1, alog.md §11.4, ScadaBridge#41).
/// </summary>
/// <remarks>
/// <para>
/// <b>Default OFF</b> (alog.md §11.4: "Default off … to avoid operational burden"). When
/// enabled, both central nodes run the job; the SQL application lock means only one of
/// them chains at a time, so a dual-active pair still produces one gap-free chain per month.
/// </para>
/// <para>
/// <b>Chain start (ScadaBridge#139).</b> Enabling it on an existing database does NOT chain the
/// historical backlog: the first chaining pass records a chain-start anchor in the database at
/// the database's current UTC time, and only rows dated from then on are chained. Older rows
/// stay unchained and are reported by <c>audit verify-chain</c> as pre-cutoff rows, never as a
/// break. The anchor is written once and is the same for both central nodes. Set
/// <see cref="ChainBacklog"/> to chain the backlog instead (only effective on the very first
/// enablement). Run <c>audit backfill-source-node</c> BEFORE enabling either way: a chained
/// row's SourceNode is frozen.
/// </para>
/// </remarks>
public sealed class AuditLogHashChainOptions
{
/// <summary>Whether the chaining job runs (default false).</summary>
public bool Enabled { get; set; }
/// <summary>
/// Chain the historical backlog on first enablement instead of starting the chain at the
/// enablement instant (default false — owner decision on ScadaBridge#107, 2026-11-13: no
/// backlog chaining). Only read while nothing has been chained yet: once the database holds
/// a chain-start anchor or any chained row, the decision is fixed and this value is ignored.
/// Set it the same on both central nodes; if they differ, whichever chains first decides.
/// </summary>
public bool ChainBacklog { get; set; }
/// <summary>Seconds between chaining ticks (default 60).</summary>
public int IntervalSeconds { get; set; } = 60;
/// <summary>Rows linked per transaction (default 1000).</summary>
public int BatchSize { get; set; } = 1000;
/// <summary>Upper bound on batches per tick so a backlog yields between ticks (default 100).</summary>
public int MaxBatchesPerTick { get; set; } = 100;
/// <summary>
/// Off-box export of the per-month chain heads (<c>AuditLog:HashChain:HeadExport</c>,
/// ScadaBridge#107 item 1) — the chain's external anchor. Default off.
/// </summary>
public AuditChainHeadExportOptions HeadExport { get; set; } = new();
}
/// <summary>Validates <see cref="AuditLogHashChainOptions"/> at host startup.</summary>
public sealed class AuditLogHashChainOptionsValidator : OptionsValidatorBase<AuditLogHashChainOptions>
{
/// <inheritdoc />
protected override void Validate(ValidationBuilder builder, AuditLogHashChainOptions options)
{
builder.RequireThat(options.IntervalSeconds > 0,
$"AuditLog:HashChain:{nameof(AuditLogHashChainOptions.IntervalSeconds)} ({options.IntervalSeconds}) must be > 0.");
builder.RequireThat(options.BatchSize is > 0 and <= 10_000,
$"AuditLog:HashChain:{nameof(AuditLogHashChainOptions.BatchSize)} ({options.BatchSize}) must be between 1 and 10000.");
builder.RequireThat(options.MaxBatchesPerTick > 0,
$"AuditLog:HashChain:{nameof(AuditLogHashChainOptions.MaxBatchesPerTick)} ({options.MaxBatchesPerTick}) must be > 0.");
var export = options.HeadExport ?? new AuditChainHeadExportOptions();
if (!export.Enabled)
{
return;
}
const string section = "AuditLog:HashChain:HeadExport";
builder.RequireThat(export.IntervalMinutes > 0,
$"{section}:IntervalMinutes ({export.IntervalMinutes}) must be > 0.");
if (export.Sink == AuditChainHeadSinkKind.File)
{
var dir = export.File?.Directory;
builder.RequireThat(!string.IsNullOrWhiteSpace(dir) && Path.IsPathFullyQualified(dir),
$"{section}:File:Directory ('{dir}') must be an absolute path (local or UNC) when Sink=File.");
}
else
{
var syslog = export.Syslog ?? new AuditChainHeadSyslogSinkOptions();
builder.RequireThat(!string.IsNullOrWhiteSpace(syslog.Host),
$"{section}:Syslog:Host is required when Sink=Syslog.");
builder.RequireThat(syslog.Port is > 0 and <= 65535,
$"{section}:Syslog:Port ({syslog.Port}) must be between 1 and 65535.");
builder.RequireThat(syslog.Facility is >= 0 and <= 23,
$"{section}:Syslog:Facility ({syslog.Facility}) must be between 0 and 23.");
builder.RequireThat(syslog.TimeoutSeconds > 0,
$"{section}:Syslog:TimeoutSeconds ({syslog.TimeoutSeconds}) must be > 0.");
}
}
}
@@ -1,151 +0,0 @@
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories;
namespace ZB.MOM.WW.ScadaBridge.AuditLog.Central;
/// <summary>
/// Central hosted service that links newly written AuditLog rows into their month's
/// SHA-256 hash chain (audit roadmap T1, alog.md §11.4, ScadaBridge#41). The chaining
/// job of alog.md §11.4, run incrementally — every <see cref="AuditLogHashChainOptions.IntervalSeconds"/>
/// rather than only once a month has closed, so a row is tamper-evident within about a
/// minute of reaching central instead of up to a month later.
/// </summary>
/// <remarks>
/// <para>
/// Same shape as <see cref="AuditLogPartitionMaintenanceService"/>: a background loop, a
/// fresh DI scope per tick, every failure logged and contained. Runs on BOTH central nodes;
/// <see cref="IAuditLogHashChain.ChainPendingAsync"/> takes an exclusive SQL application
/// lock with a zero timeout, so the peer's pass skips instead of racing (and correctness
/// does not depend on Akka's view of which node is active).
/// </para>
/// </remarks>
public sealed class AuditLogHashChainService : IHostedService, IDisposable
{
private readonly IServiceScopeFactory _scopeFactory;
private readonly IOptions<AuditLogHashChainOptions> _options;
private readonly ILogger<AuditLogHashChainService> _logger;
private CancellationTokenSource? _cts;
private Task? _loop;
/// <summary>Initializes the service.</summary>
/// <param name="scopeFactory">Scope factory used to resolve the scoped chain implementation per tick.</param>
/// <param name="options">Hash-chain options.</param>
/// <param name="logger">Logger.</param>
public AuditLogHashChainService(
IServiceScopeFactory scopeFactory,
IOptions<AuditLogHashChainOptions> options,
ILogger<AuditLogHashChainService> logger)
{
_scopeFactory = scopeFactory ?? throw new ArgumentNullException(nameof(scopeFactory));
_options = options ?? throw new ArgumentNullException(nameof(options));
_logger = logger ?? throw new ArgumentNullException(nameof(logger));
}
/// <inheritdoc />
public Task StartAsync(CancellationToken cancellationToken)
{
if (!_options.Value.Enabled)
{
_logger.LogInformation("AuditLog hash chain disabled (AuditLog:HashChain:Enabled=false); no chaining job started.");
return Task.CompletedTask;
}
var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
_cts = cts;
var token = cts.Token;
_loop = Task.Run(() => RunLoopAsync(token), CancellationToken.None);
return Task.CompletedTask;
}
private async Task RunLoopAsync(CancellationToken ct)
{
while (!ct.IsCancellationRequested)
{
await TickAsync(ct).ConfigureAwait(false);
try
{
await Task.Delay(TimeSpan.FromSeconds(_options.Value.IntervalSeconds), ct).ConfigureAwait(false);
}
catch (OperationCanceledException)
{
break;
}
}
}
/// <summary>
/// Runs one tick: chains batches until the backlog is empty, the peer holds the lock,
/// or <see cref="AuditLogHashChainOptions.MaxBatchesPerTick"/> is reached.
/// </summary>
/// <param name="ct">Cancellation token.</param>
/// <returns>The number of rows chained in this tick.</returns>
internal async Task<long> TickAsync(CancellationToken ct)
{
long total = 0;
try
{
var options = _options.Value;
await using var scope = _scopeFactory.CreateAsyncScope();
var chain = scope.ServiceProvider.GetRequiredService<IAuditLogHashChain>();
for (var i = 0; i < options.MaxBatchesPerTick && !ct.IsCancellationRequested; i++)
{
var result = await chain.ChainPendingAsync(options.BatchSize, options.ChainBacklog, ct).ConfigureAwait(false);
total += result.RowsChained;
if (result.LockBusy || result.RowsChained == 0)
{
break;
}
}
if (total > 0)
{
_logger.LogDebug("AuditLog hash chain linked {Rows} rows this tick.", total);
}
}
catch (OperationCanceledException) when (ct.IsCancellationRequested)
{
// Shutdown.
}
catch (Exception ex)
{
// Contained: a transient SQL failure must not end the loop; the next tick
// resumes from wherever the last committed pass left the chain.
_logger.LogError(ex, "AuditLog hash-chain tick failed after linking {Rows} rows.", total);
}
return total;
}
/// <inheritdoc />
public Task StopAsync(CancellationToken cancellationToken)
{
try
{
_cts?.Cancel();
}
catch (ObjectDisposedException)
{
// Dispose already cancelled the loop.
}
return _loop ?? Task.CompletedTask;
}
/// <inheritdoc />
public void Dispose()
{
try
{
_cts?.Cancel();
}
catch (ObjectDisposedException)
{
// Idempotent.
}
_cts?.Dispose();
}
}
@@ -49,9 +49,7 @@ namespace ZB.MOM.WW.ScadaBridge.AuditLog.Central;
/// </para> /// </para>
/// <para> /// <para>
/// <b>DI scopes.</b> <see cref="IAuditLogRepository"/> is a scoped EF Core /// <b>DI scopes.</b> <see cref="IAuditLogRepository"/> is a scoped EF Core
/// service registered by <c>AddConfigurationDatabase</c> — the /// service registered by <c>AddConfigurationDatabase</c>. The singleton
/// <see cref="AuditMaintenanceContext.ServiceKey"/>-keyed one, on the AuditLog maintenance
/// connection (ScadaBridge#107 item 3), when registered. The singleton
/// opens one DI scope per tick and reuses the same repository across every /// opens one DI scope per tick and reuses the same repository across every
/// boundary in that tick — mirrors the /// boundary in that tick — mirrors the
/// <see cref="SiteAuditReconciliationActor"/> pattern. /// <see cref="SiteAuditReconciliationActor"/> pattern.
@@ -152,11 +150,7 @@ public class AuditLogPurgeActor : ReceiveActor
IAuditLogRepository repository; IAuditLogRepository repository;
try try
{ {
// The maintenance-connection repository when the host registered one repository = scope.ServiceProvider.GetRequiredService<IAuditLogRepository>();
// (AddConfigurationDatabase, ScadaBridge#107 item 3 — on the separate maintenance
// login if AuditLog:MaintenanceConnectionString is set), else the plain one.
repository = scope.ServiceProvider.GetKeyedService<IAuditLogRepository>(AuditMaintenanceContext.ServiceKey)
?? scope.ServiceProvider.GetRequiredService<IAuditLogRepository>();
} }
catch (Exception ex) catch (Exception ex)
{ {
@@ -210,8 +204,7 @@ public class AuditLogPurgeActor : ReceiveActor
{ {
try try
{ {
archive = scope.ServiceProvider.GetKeyedService<IAuditLogArchive>(AuditMaintenanceContext.ServiceKey) archive = scope.ServiceProvider.GetRequiredService<IAuditLogArchive>();
?? scope.ServiceProvider.GetRequiredService<IAuditLogArchive>();
} }
catch (Exception ex) catch (Exception ex)
{ {
@@ -305,8 +298,7 @@ public class AuditLogPurgeActor : ReceiveActor
return; return;
} }
archive = services.GetKeyedService<IAuditLogArchive>(AuditMaintenanceContext.ServiceKey) archive = services.GetRequiredService<IAuditLogArchive>();
?? services.GetRequiredService<IAuditLogArchive>();
} }
var result = await archive.CleanupAsync(dryRun: false).ConfigureAwait(false); var result = await archive.CleanupAsync(dryRun: false).ConfigureAwait(false);
@@ -1,87 +0,0 @@
namespace ZB.MOM.WW.ScadaBridge.AuditLog.Central.HeadExport;
/// <summary>Where exported chain heads go.</summary>
public enum AuditChainHeadSinkKind
{
/// <summary>Append-only JSON-lines files in a directory (local or UNC).</summary>
File,
/// <summary>RFC 5424 syslog over UDP or TCP.</summary>
Syslog,
}
/// <summary>Syslog transport.</summary>
public enum AuditSyslogProtocol
{
/// <summary>One datagram per record (RFC 5426).</summary>
Udp,
/// <summary>Octet-counted frames on one TCP connection per export (RFC 6587).</summary>
Tcp,
}
/// <summary>
/// Off-box export of the AuditLog hash-chain heads (section <c>AuditLog:HashChain:HeadExport</c>,
/// ScadaBridge#107 item 1). <b>Default OFF.</b> Every <see cref="IntervalMinutes"/> both central
/// nodes read each month's chain head (month, last sequence + hash, partition-purge anchor,
/// chained-row and tombstone counts) and append the heads that changed since their previous
/// export to a sink the database login cannot write. <c>audit verify-heads</c> later compares
/// those records with the database: a chain someone rewrote and re-hashed inside SQL Server no
/// longer carries the hash that was exported.
/// </summary>
public sealed class AuditChainHeadExportOptions
{
/// <summary>Whether the export runs (default false).</summary>
public bool Enabled { get; set; }
/// <summary>Minutes between exports (default 60).</summary>
public int IntervalMinutes { get; set; } = 60;
/// <summary>
/// Re-export unchanged heads every tick too (default false: only heads whose sequence,
/// anchor or counts moved since this node's previous export, plus every head on the first
/// tick after start).
/// </summary>
public bool ExportUnchanged { get; set; }
/// <summary>Which sink (default <see cref="AuditChainHeadSinkKind.File"/>).</summary>
public AuditChainHeadSinkKind Sink { get; set; } = AuditChainHeadSinkKind.File;
/// <summary>File sink settings.</summary>
public AuditChainHeadFileSinkOptions File { get; set; } = new();
/// <summary>Syslog sink settings.</summary>
public AuditChainHeadSyslogSinkOptions Syslog { get; set; } = new();
}
/// <summary>File sink: <c>{Directory}/{yyyy}/audit-chain-heads-{yyyy-MM-dd}-{node}.jsonl</c>, opened for append only.</summary>
public sealed class AuditChainHeadFileSinkOptions
{
/// <summary>
/// Absolute directory (local path or UNC share). Give the service account create + append
/// rights only; the SQL Server login has no access to it by construction.
/// </summary>
public string? Directory { get; set; }
}
/// <summary>Syslog sink (RFC 5424).</summary>
public sealed class AuditChainHeadSyslogSinkOptions
{
/// <summary>Collector host name or address.</summary>
public string? Host { get; set; }
/// <summary>Collector port (default 514).</summary>
public int Port { get; set; } = 514;
/// <summary>Transport (default UDP).</summary>
public AuditSyslogProtocol Protocol { get; set; } = AuditSyslogProtocol.Udp;
/// <summary>Syslog facility 0–23 (default 13, "log audit").</summary>
public int Facility { get; set; } = 13;
/// <summary>APP-NAME field (default <c>scadabridge</c>).</summary>
public string AppName { get; set; } = "scadabridge";
/// <summary>Send/connect timeout in seconds (default 10).</summary>
public int TimeoutSeconds { get; set; } = 10;
}
@@ -1,205 +0,0 @@
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
using ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance;
namespace ZB.MOM.WW.ScadaBridge.AuditLog.Central.HeadExport;
/// <summary>
/// Central hosted service that exports the AuditLog hash-chain heads off-box
/// (<c>AuditLog:HashChain:HeadExport</c>, ScadaBridge#107 item 1). Default off.
/// </summary>
/// <remarks>
/// <para>
/// Runs on both central nodes (each record names its node). A tick reads every month's head in
/// one consistent snapshot (<see cref="IAuditChainHeadStore.ReadHeadsAsync"/>, chain lock
/// SHARED) and writes the heads that changed since this node's last successful export — all of
/// them on the first tick after start — to the configured <see cref="IAuditChainHeadSink"/>.
/// A failed write is logged and retried on the next tick with the same heads (the in-memory
/// "last exported" state only advances on success). No signing: the protection is that the
/// sink sits outside the database login's reach.
/// </para>
/// </remarks>
public sealed class AuditChainHeadExportService : IHostedService, IDisposable
{
private readonly IServiceScopeFactory _scopeFactory;
private readonly AuditChainHeadExportOptions _options;
private readonly IAuditChainHeadSink? _sink;
private readonly string? _node;
private readonly TimeProvider _time;
private readonly ILogger<AuditChainHeadExportService> _logger;
private readonly AuditChainHeadExportStatus _status;
private readonly Dictionary<DateTime, (long Seq, long? Purged, long Links)> _lastExported = new();
private CancellationTokenSource? _cts;
private Task? _loop;
/// <summary>Initializes the service.</summary>
/// <param name="scopeFactory">Scope factory for the scoped head store.</param>
/// <param name="options">Hash-chain options (the <c>HeadExport</c> sub-section is used).</param>
/// <param name="sink">The sink (null when the export is disabled).</param>
/// <param name="nodeName">This node's name for the records.</param>
/// <param name="logger">Logger.</param>
/// <param name="time">Clock.</param>
/// <param name="status">Health status the tick outcome is recorded on (ScadaBridge#115).</param>
public AuditChainHeadExportService(
IServiceScopeFactory scopeFactory,
IOptions<AuditLogHashChainOptions> options,
IAuditChainHeadSink? sink,
string? nodeName,
ILogger<AuditChainHeadExportService> logger,
TimeProvider? time = null,
AuditChainHeadExportStatus? status = null)
{
_status = status ?? new AuditChainHeadExportStatus();
_scopeFactory = scopeFactory ?? throw new ArgumentNullException(nameof(scopeFactory));
_options = (options ?? throw new ArgumentNullException(nameof(options))).Value.HeadExport;
_sink = sink;
_node = nodeName;
_logger = logger ?? throw new ArgumentNullException(nameof(logger));
_time = time ?? TimeProvider.System;
}
/// <inheritdoc />
public Task StartAsync(CancellationToken cancellationToken)
{
if (!_options.Enabled || _sink is null)
{
_logger.LogInformation("AuditLog chain-head export disabled (AuditLog:HashChain:HeadExport:Enabled=false).");
return Task.CompletedTask;
}
_status.MarkStarted(_options.IntervalMinutes, _time.GetUtcNow().UtcDateTime);
_logger.LogInformation("AuditLog chain-head export every {Minutes} min to {Sink}.", _options.IntervalMinutes, _sink.Describe);
var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
_cts = cts;
var token = cts.Token;
_loop = Task.Run(() => RunLoopAsync(token), CancellationToken.None);
return Task.CompletedTask;
}
private async Task RunLoopAsync(CancellationToken ct)
{
while (!ct.IsCancellationRequested)
{
await TickAsync(ct).ConfigureAwait(false);
try
{
await Task.Delay(TimeSpan.FromMinutes(_options.IntervalMinutes), ct).ConfigureAwait(false);
}
catch (OperationCanceledException)
{
break;
}
}
}
/// <summary>Runs one export tick.</summary>
/// <param name="ct">Cancellation token.</param>
/// <returns>The number of records written (0 on failure or nothing changed).</returns>
internal async Task<int> TickAsync(CancellationToken ct)
{
if (_sink is null)
{
return 0;
}
try
{
IReadOnlyList<AuditChainHeadSnapshot> heads;
await using (var scope = _scopeFactory.CreateAsyncScope())
{
heads = await scope.ServiceProvider.GetRequiredService<IAuditChainHeadStore>()
.ReadHeadsAsync(ct).ConfigureAwait(false);
}
var now = _time.GetUtcNow().UtcDateTime;
var changed = heads
.Where(h => _options.ExportUnchanged
|| !_lastExported.TryGetValue(h.Month, out var last)
|| last != (h.LastSeq, h.PurgedThroughSeq, h.ChainedRows + h.Tombstones))
.ToList();
if (changed.Count == 0)
{
_status.RecordSuccess(now);
return 0;
}
var records = changed.Select(h => ToRecord(h, now, _node)).ToList();
await _sink.WriteAsync(records, ct).ConfigureAwait(false);
foreach (var h in changed)
{
_lastExported[h.Month] = (h.LastSeq, h.PurgedThroughSeq, h.ChainedRows + h.Tombstones);
}
_status.RecordSuccess(now);
_logger.LogDebug("Exported {Count} AuditLog chain head(s) to {Sink}.", records.Count, _sink.Describe);
return records.Count;
}
catch (OperationCanceledException) when (ct.IsCancellationRequested)
{
return 0;
}
catch (Exception ex)
{
// Contained: the next tick retries the same heads (nothing was marked exported).
_logger.LogError(ex, "AuditLog chain-head export to {Sink} failed; retrying next tick.", _sink.Describe);
_status.RecordFailure(_time.GetUtcNow().UtcDateTime, ex.Message);
return 0;
}
}
/// <summary>Maps a database head to its exported record.</summary>
/// <param name="head">The head.</param>
/// <param name="exportedAtUtc">Export time.</param>
/// <param name="node">Exporting node.</param>
/// <returns>The record.</returns>
public static AuditChainHeadRecord ToRecord(AuditChainHeadSnapshot head, DateTime exportedAtUtc, string? node)
{
ArgumentNullException.ThrowIfNull(head);
return new AuditChainHeadRecord(
AuditChainHeadRecord.CurrentVersion,
AuditChainHasher.PartitionLabel(head.Month),
head.LastSeq,
AuditChainHeadComparer.ToHex(head.LastHash),
head.PurgedThroughSeq,
head.PurgedThroughHash is null ? null : AuditChainHeadComparer.ToHex(head.PurgedThroughHash),
head.ChainedRows,
head.Tombstones,
head.UpdatedAtUtc,
exportedAtUtc,
node);
}
/// <inheritdoc />
public Task StopAsync(CancellationToken cancellationToken)
{
try
{
_cts?.Cancel();
}
catch (ObjectDisposedException)
{
// Dispose already cancelled the loop.
}
return _loop ?? Task.CompletedTask;
}
/// <inheritdoc />
public void Dispose()
{
try
{
_cts?.Cancel();
}
catch (ObjectDisposedException)
{
// Idempotent.
}
_cts?.Dispose();
}
}
@@ -1,91 +0,0 @@
using System.Diagnostics.Metrics;
using ZB.MOM.WW.ScadaBridge.Commons.Observability;
namespace ZB.MOM.WW.ScadaBridge.AuditLog.Central.HeadExport;
/// <summary>
/// Health signal of the off-box chain-head export (ScadaBridge#115). Updated by
/// <see cref="AuditChainHeadExportService"/> on every tick; read by the Host's
/// <c>audit-chain-head-export</c> /health/ready check. A sink that stays down used to be a
/// log line only, silently stopping the external anchor.
/// </summary>
public sealed class AuditChainHeadExportStatus
{
private static readonly Meter Meter = new(ScadaBridgeTelemetry.MeterName);
private static readonly Counter<long> FailuresCounter =
Meter.CreateCounter<long>("scadabridge.audit.chain_head_export.failures", unit: "1",
description: "AuditLog chain-head export ticks that failed to read or write the heads (sink offline / unreachable); retried next tick.");
private readonly object _gate = new();
private long _totalFailures;
private int _consecutiveFailures;
private DateTime? _lastSuccessUtc;
private DateTime? _lastFailureUtc;
private string? _lastError;
private DateTime? _startedUtc;
/// <summary>Whether the export is running at all (false = disabled, nothing to report).</summary>
public bool Enabled { get; private set; }
/// <summary>Minutes between export ticks (for the staleness test).</summary>
public int IntervalMinutes { get; private set; } = 60;
/// <summary>Total failed ticks since process start.</summary>
public long TotalFailures { get { lock (_gate) { return _totalFailures; } } }
/// <summary>Failed ticks since the last success.</summary>
public int ConsecutiveFailures { get { lock (_gate) { return _consecutiveFailures; } } }
/// <summary>UTC time of the last successful tick, or null.</summary>
public DateTime? LastSuccessUtc { get { lock (_gate) { return _lastSuccessUtc; } } }
/// <summary>UTC time of the last failed tick, or null.</summary>
public DateTime? LastFailureUtc { get { lock (_gate) { return _lastFailureUtc; } } }
/// <summary>Message of the last failure (never a secret: the exception message only), or null.</summary>
public string? LastError { get { lock (_gate) { return _lastError; } } }
/// <summary>UTC time the export loop started, or null.</summary>
public DateTime? StartedUtc { get { lock (_gate) { return _startedUtc; } } }
/// <summary>Marks the export as running.</summary>
/// <param name="intervalMinutes">Tick interval.</param>
/// <param name="nowUtc">Start time.</param>
public void MarkStarted(int intervalMinutes, DateTime nowUtc)
{
lock (_gate)
{
Enabled = true;
IntervalMinutes = intervalMinutes;
_startedUtc = nowUtc;
}
}
/// <summary>Records a successful tick.</summary>
/// <param name="nowUtc">Time of the tick.</param>
public void RecordSuccess(DateTime nowUtc)
{
lock (_gate)
{
_consecutiveFailures = 0;
_lastSuccessUtc = nowUtc;
}
}
/// <summary>Records a failed tick and bumps the failure counter metric.</summary>
/// <param name="nowUtc">Time of the tick.</param>
/// <param name="error">The failure message.</param>
public void RecordFailure(DateTime nowUtc, string error)
{
lock (_gate)
{
_totalFailures++;
_consecutiveFailures++;
_lastFailureUtc = nowUtc;
_lastError = error;
}
FailuresCounter.Add(1);
}
}
@@ -1,21 +0,0 @@
using System.Text.Json;
using System.Text.Json.Serialization;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
namespace ZB.MOM.WW.ScadaBridge.AuditLog.Central.HeadExport;
/// <summary>The one JSON shape every sink writes (and <c>audit verify-heads</c> reads).</summary>
public static class AuditChainHeadJson
{
/// <summary>camelCase, compact, nulls kept so every record has every field.</summary>
public static readonly JsonSerializerOptions Options = new(JsonSerializerDefaults.Web)
{
WriteIndented = false,
DefaultIgnoreCondition = JsonIgnoreCondition.Never,
};
/// <summary>Serialises one record to a single line.</summary>
/// <param name="record">The record.</param>
/// <returns>Compact JSON.</returns>
public static string Serialize(AuditChainHeadRecord record) => JsonSerializer.Serialize(record, Options);
}
@@ -1,79 +0,0 @@
using System.Text;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
namespace ZB.MOM.WW.ScadaBridge.AuditLog.Central.HeadExport;
/// <summary>
/// Appends exported heads as JSON lines to <c>{Directory}/{yyyy}/audit-chain-heads-{yyyy-MM-dd}-{node}.jsonl</c>.
/// </summary>
/// <remarks>
/// The file is only ever opened with <see cref="FileMode.Append"/> — never truncated, rewritten
/// or deleted by ScadaBridge — so the share can grant the service account create + append data
/// only. One file per node per UTC day keeps the two central nodes from interleaving writes in
/// one file. Each batch is flushed to disk before the call returns.
/// </remarks>
public sealed class FileAuditChainHeadSink : IAuditChainHeadSink
{
private readonly string _directory;
private readonly string _node;
private readonly TimeProvider _time;
/// <summary>Creates the sink.</summary>
/// <param name="directory">Absolute export directory.</param>
/// <param name="node">This node's name (part of the file name).</param>
/// <param name="time">Clock (file-per-day naming).</param>
public FileAuditChainHeadSink(string directory, string node, TimeProvider? time = null)
{
ArgumentException.ThrowIfNullOrWhiteSpace(directory);
if (!Path.IsPathFullyQualified(directory))
{
throw new ArgumentException($"Head-export directory '{directory}' must be absolute.", nameof(directory));
}
_directory = directory;
_node = SafeName(string.IsNullOrWhiteSpace(node) ? "node" : node);
_time = time ?? TimeProvider.System;
}
/// <inheritdoc />
public string Describe => _directory;
/// <summary>The file a write at <paramref name="nowUtc"/> lands in.</summary>
/// <param name="nowUtc">The write time.</param>
/// <returns>The full path.</returns>
public string PathFor(DateTime nowUtc) => Path.Combine(
_directory, nowUtc.ToString("yyyy", System.Globalization.CultureInfo.InvariantCulture),
$"audit-chain-heads-{nowUtc:yyyy-MM-dd}-{_node}.jsonl");
/// <inheritdoc />
public async Task WriteAsync(IReadOnlyList<AuditChainHeadRecord> records, CancellationToken ct)
{
ArgumentNullException.ThrowIfNull(records);
if (records.Count == 0)
{
return;
}
var path = PathFor(_time.GetUtcNow().UtcDateTime);
Directory.CreateDirectory(Path.GetDirectoryName(path)!);
var text = new StringBuilder();
foreach (var record in records)
{
text.Append(AuditChainHeadJson.Serialize(record)).Append('\n');
}
var bytes = new UTF8Encoding(encoderShouldEmitUTF8Identifier: false).GetBytes(text.ToString());
await using var stream = new FileStream(path, FileMode.Append, FileAccess.Write, FileShare.Read, 4096, useAsync: true);
await stream.WriteAsync(bytes, ct).ConfigureAwait(false);
await stream.FlushAsync(ct).ConfigureAwait(false);
stream.Flush(flushToDisk: true);
}
private static string SafeName(string value)
{
var invalid = Path.GetInvalidFileNameChars();
var chars = value.Select(c => invalid.Contains(c) || c == ' ' ? '_' : c).ToArray();
return new string(chars);
}
}
@@ -1,16 +0,0 @@
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
namespace ZB.MOM.WW.ScadaBridge.AuditLog.Central.HeadExport;
/// <summary>An off-box destination for exported chain heads (ScadaBridge#107 item 1).</summary>
public interface IAuditChainHeadSink
{
/// <summary>Short description for logs (e.g. the directory or <c>host:port/udp</c>).</summary>
string Describe { get; }
/// <summary>Writes the records; throws when they could not all be delivered.</summary>
/// <param name="records">The records, oldest month first.</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>A task that completes when the records are durably handed off.</returns>
Task WriteAsync(IReadOnlyList<AuditChainHeadRecord> records, CancellationToken ct);
}
@@ -1,108 +0,0 @@
using System.Globalization;
using System.Net.Sockets;
using System.Text;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
namespace ZB.MOM.WW.ScadaBridge.AuditLog.Central.HeadExport;
/// <summary>
/// Sends exported heads as RFC 5424 syslog messages — one message per head, the JSON record as
/// MSG — over UDP (RFC 5426, one datagram each) or TCP (RFC 6587 octet-counting framing, one
/// connection per export).
/// </summary>
/// <remarks>
/// Message: <c>&lt;PRI&gt;1 TIMESTAMP HOSTNAME APP-NAME PROCID chainhead - {json}</c>, severity
/// Notice (5), PRI = facility × 8 + 5. No structured data (a private enterprise number would be
/// needed); the collector keeps the JSON body, which <c>audit verify-heads</c> reads back from
/// any line that contains it. UDP is fire-and-forget — use TCP where a lost datagram matters.
/// </remarks>
public sealed class SyslogAuditChainHeadSink : IAuditChainHeadSink
{
/// <summary>MSGID of every head message.</summary>
public const string MessageId = "chainhead";
private const int SeverityNotice = 5;
private readonly AuditChainHeadSyslogSinkOptions _options;
private readonly string _hostName;
private readonly TimeProvider _time;
/// <summary>Creates the sink.</summary>
/// <param name="options">Syslog settings.</param>
/// <param name="hostName">HOSTNAME field (defaults to the machine name).</param>
/// <param name="time">Clock for TIMESTAMP.</param>
public SyslogAuditChainHeadSink(AuditChainHeadSyslogSinkOptions options, string? hostName = null, TimeProvider? time = null)
{
_options = options ?? throw new ArgumentNullException(nameof(options));
ArgumentException.ThrowIfNullOrWhiteSpace(options.Host);
_hostName = Token(hostName ?? Environment.MachineName, 255);
_time = time ?? TimeProvider.System;
}
/// <inheritdoc />
public string Describe => $"{_options.Host}:{_options.Port}/{_options.Protocol.ToString().ToLowerInvariant()}";
/// <summary>Formats one RFC 5424 message (no framing).</summary>
/// <param name="record">The record.</param>
/// <returns>The message text.</returns>
public string Format(AuditChainHeadRecord record)
{
var pri = (_options.Facility * 8) + SeverityNotice;
var timestamp = _time.GetUtcNow().UtcDateTime.ToString("yyyy-MM-dd'T'HH:mm:ss.fff'Z'", CultureInfo.InvariantCulture);
return string.Create(CultureInfo.InvariantCulture,
$"<{pri}>1 {timestamp} {_hostName} {Token(_options.AppName, 48)} {Environment.ProcessId} {MessageId} - {AuditChainHeadJson.Serialize(record)}");
}
/// <inheritdoc />
public async Task WriteAsync(IReadOnlyList<AuditChainHeadRecord> records, CancellationToken ct)
{
ArgumentNullException.ThrowIfNull(records);
if (records.Count == 0)
{
return;
}
using var timeout = CancellationTokenSource.CreateLinkedTokenSource(ct);
timeout.CancelAfter(TimeSpan.FromSeconds(Math.Max(1, _options.TimeoutSeconds)));
var token = timeout.Token;
if (_options.Protocol == AuditSyslogProtocol.Udp)
{
using var udp = new UdpClient();
udp.Connect(_options.Host!, _options.Port);
foreach (var record in records)
{
var bytes = Encoding.UTF8.GetBytes(Format(record));
await udp.SendAsync(bytes, token).ConfigureAwait(false);
}
return;
}
using var tcp = new TcpClient();
await tcp.ConnectAsync(_options.Host!, _options.Port, token).ConfigureAwait(false);
var stream = tcp.GetStream();
foreach (var record in records)
{
var message = Encoding.UTF8.GetBytes(Format(record));
var frame = Encoding.ASCII.GetBytes(message.Length.ToString(CultureInfo.InvariantCulture) + " ");
await stream.WriteAsync(frame, token).ConfigureAwait(false);
await stream.WriteAsync(message, token).ConfigureAwait(false);
}
await stream.FlushAsync(token).ConfigureAwait(false);
tcp.Client.Shutdown(SocketShutdown.Send);
}
// RFC 5424 header fields are PRINTUSASCII (33-126), no spaces; "-" when empty.
private static string Token(string? value, int max)
{
if (string.IsNullOrEmpty(value))
{
return "-";
}
var chars = value.Where(c => c is >= '!' and <= '~').Take(max).ToArray();
return chars.Length == 0 ? "-" : new string(chars);
}
}
@@ -0,0 +1,73 @@
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
namespace ZB.MOM.WW.ScadaBridge.AuditLog.Central;
/// <summary>
/// Logs one warning at central startup for each AuditLog setting that no longer does anything.
/// </summary>
/// <remarks>
/// The hash chain (<c>AuditLog:HashChain</c>, including its head export) and the two-login
/// maintenance hardening (<c>AuditLog:MaintenanceConnectionString</c>) were removed on
/// 2026-11-15 at IT security's request. Nothing validates unknown keys, so a node still carrying
/// them (for example <c>AuditLog__HashChain__Enabled=true</c> in its service environment) boots
/// normally; this warning tells the operator the keys can be deleted.
/// </remarks>
public sealed class RetiredAuditSettingsWarning : IHostedService
{
/// <summary>The retired hash-chain section.</summary>
public const string HashChainSection = "AuditLog:HashChain";
/// <summary>The retired maintenance-login connection string.</summary>
public const string MaintenanceConnectionStringKey = "AuditLog:MaintenanceConnectionString";
private readonly IConfiguration _configuration;
private readonly ILogger<RetiredAuditSettingsWarning> _logger;
/// <summary>Initializes a new instance of the <see cref="RetiredAuditSettingsWarning"/> class.</summary>
/// <param name="configuration">Application configuration.</param>
/// <param name="logger">Logger.</param>
public RetiredAuditSettingsWarning(IConfiguration configuration, ILogger<RetiredAuditSettingsWarning> logger)
{
_configuration = configuration ?? throw new ArgumentNullException(nameof(configuration));
_logger = logger ?? throw new ArgumentNullException(nameof(logger));
}
/// <summary>The retired keys present in <paramref name="configuration"/>.</summary>
/// <param name="configuration">The configuration to inspect.</param>
/// <returns>Each retired key or section that is set.</returns>
public static IReadOnlyList<string> FindRetired(IConfiguration configuration)
{
ArgumentNullException.ThrowIfNull(configuration);
var found = new List<string>();
if (configuration.GetSection(HashChainSection).Exists())
{
found.Add(HashChainSection);
}
if (!string.IsNullOrWhiteSpace(configuration[MaintenanceConnectionStringKey]))
{
found.Add(MaintenanceConnectionStringKey);
}
return found;
}
/// <inheritdoc />
public Task StartAsync(CancellationToken cancellationToken)
{
foreach (var key in FindRetired(_configuration))
{
_logger.LogWarning(
"{Setting} is no longer supported and is ignored: the AuditLog hash chain and the two-login "
+ "maintenance hardening were removed on 2026-11-15. Delete the setting.",
key);
}
return Task.CompletedTask;
}
/// <inheritdoc />
public Task StopAsync(CancellationToken cancellationToken) => Task.CompletedTask;
}
@@ -52,15 +52,6 @@ public static class ServiceCollectionExtensions
/// <summary>Configuration section bound to <see cref="AuditLogPartitionMaintenanceOptions"/>.</summary> /// <summary>Configuration section bound to <see cref="AuditLogPartitionMaintenanceOptions"/>.</summary>
public const string PartitionMaintenanceSectionName = "AuditLog:PartitionMaintenance"; public const string PartitionMaintenanceSectionName = "AuditLog:PartitionMaintenance";
/// <summary>
/// Optional connection string for the AuditLog maintenance paths — the hash-chain job and both
/// purge paths (ScadaBridge#107 item 3). Unset: they run on <c>ScadaBridge:Database:ConfigurationDb</c>.
/// </summary>
public const string MaintenanceConnectionStringKey = "AuditLog:MaintenanceConnectionString";
/// <summary>Configuration section bound to <see cref="AuditLogHashChainOptions"/> (ScadaBridge#41).</summary>
public const string HashChainSectionName = "AuditLog:HashChain";
/// <summary> /// <summary>
/// Configuration section bound to /// Configuration section bound to
/// <see cref="ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance.AuditLogArchiveOptions"/> (ScadaBridge#42). /// <see cref="ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance.AuditLogArchiveOptions"/> (ScadaBridge#42).
@@ -410,34 +401,9 @@ public static class ServiceCollectionExtensions
AuditLogPartitionMaintenanceOptionsValidator>(config, PartitionMaintenanceSectionName); AuditLogPartitionMaintenanceOptionsValidator>(config, PartitionMaintenanceSectionName);
services.AddHostedService<AuditLogPartitionMaintenanceService>(); services.AddHostedService<AuditLogPartitionMaintenanceService>();
// Hash-chain tamper evidence (ScadaBridge#41). Default OFF; the hosted service is // The hash chain and the two-login maintenance hardening were removed on 2026-11-15;
// always registered and returns from StartAsync without a loop when disabled. // a node still carrying their settings boots normally and is told to delete them.
// IAuditLogHashChain is registered by AddConfigurationDatabase (central only). services.AddHostedService<RetiredAuditSettingsWarning>();
services.AddValidatedOptions<AuditLogHashChainOptions, AuditLogHashChainOptionsValidator>(
config, HashChainSectionName);
services.AddHostedService<AuditLogHashChainService>();
// Off-box chain-head export (ScadaBridge#107 item 1, AuditLog:HashChain:HeadExport,
// default off). The sink is built from the bound options; null when disabled.
services.AddSingleton<Central.HeadExport.AuditChainHeadExportStatus>();
services.AddHostedService(sp =>
{
var options = sp.GetRequiredService<Microsoft.Extensions.Options.IOptions<AuditLogHashChainOptions>>();
var node = sp.GetService<INodeIdentityProvider>()?.NodeName;
var export = options.Value.HeadExport;
Central.HeadExport.IAuditChainHeadSink? sink = !export.Enabled ? null : export.Sink switch
{
Central.HeadExport.AuditChainHeadSinkKind.Syslog => new Central.HeadExport.SyslogAuditChainHeadSink(export.Syslog),
_ => new Central.HeadExport.FileAuditChainHeadSink(export.File.Directory!, node ?? Environment.MachineName),
};
return new Central.HeadExport.AuditChainHeadExportService(
sp.GetRequiredService<IServiceScopeFactory>(),
options,
sink,
node,
sp.GetRequiredService<ILogger<Central.HeadExport.AuditChainHeadExportService>>(),
status: sp.GetRequiredService<Central.HeadExport.AuditChainHeadExportStatus>());
});
// Parquet cold archive (ScadaBridge#42). Default OFF; when enabled the purge actor // Parquet cold archive (ScadaBridge#42). Default OFF; when enabled the purge actor
// archives each expired partition before switching it out. IAuditLogArchive is // archives each expired partition before switching it out. IAuditLogArchive is
@@ -11,16 +11,16 @@ namespace ZB.MOM.WW.ScadaBridge.CLI.Commands;
/// </summary> /// </summary>
/// <remarks> /// <remarks>
/// <c>verify</c> exit codes: <c>0</c> verified, <see cref="NotVerifiedExitCode"/> when the /// <c>verify</c> exit codes: <c>0</c> verified, <see cref="NotVerifiedExitCode"/> when the
/// files, the chain or the purge anchor disagree, <c>1</c> on a request error, <c>2</c> on an /// data file disagrees with its manifest, <c>1</c> on a request error, <c>2</c> on an
/// authorization failure. /// authorization failure.
/// </remarks> /// </remarks>
public static class AuditArchiveHelpers public static class AuditArchiveHelpers
{ {
/// <summary>Process exit code when an archive failed verification (tamper evidence).</summary> /// <summary>Process exit code when an archive failed verification.</summary>
public const int NotVerifiedExitCode = 3; public const int NotVerifiedExitCode = 3;
/// <summary> /// <summary>
/// Client deadline for <c>verify</c>: the server hashes and re-chains a whole month under /// Client deadline for <c>verify</c>: the server hashes and reads a whole month under
/// the long-running management Ask (5 min); the client waits a little longer. /// the long-running management Ask (5 min); the client waits a little longer.
/// </summary> /// </summary>
public static readonly TimeSpan VerifyRequestTimeout = TimeSpan.FromMinutes(6); public static readonly TimeSpan VerifyRequestTimeout = TimeSpan.FromMinutes(6);
@@ -50,11 +50,11 @@ public static class AuditArchiveHelpers
return 0; return 0;
} }
output.WriteLine($"{"NAME",-42} {"PARTITION",-9} {"STATUS",-8} {"ROWS",12} {"CHAINED",12} {"BYTES",14}"); output.WriteLine($"{"NAME",-42} {"PARTITION",-9} {"STATUS",-8} {"ROWS",12} {"BYTES",14}");
foreach (var a in archives.EnumerateArray()) foreach (var a in archives.EnumerateArray())
{ {
output.WriteLine(string.Create(CultureInfo.InvariantCulture, output.WriteLine(string.Create(CultureInfo.InvariantCulture,
$"{Str(a, "name"),-42} {Str(a, "partition"),-9} {Str(a, "status"),-8} {Num(a, "rowCount"),12} {Num(a, "chainedRowCount"),12} {Num(a, "dataBytes"),14}")); $"{Str(a, "name"),-42} {Str(a, "partition"),-9} {Str(a, "status"),-8} {Num(a, "rowCount"),12} {Num(a, "dataBytes"),14}"));
} }
output.Flush(); output.Flush();
@@ -90,20 +90,6 @@ public static class AuditArchiveHelpers
} }
output.WriteLine($"Rows read : {Num(root, "rowsRead")}"); output.WriteLine($"Rows read : {Num(root, "rowsRead")}");
if (root.TryGetProperty("chains", out var chains) && chains.ValueKind == JsonValueKind.Array)
{
foreach (var c in chains.EnumerateArray())
{
var chain = c.GetProperty("chain");
output.WriteLine($"Chain {Str(chain, "partition")}: {Str(chain, "status")}, {Num(chain, "rowsVerified")} rows verified, "
+ $"{Num(chain, "tombstonesApplied")} tombstones, {Num(chain, "unchainedRows")} unchained; anchor {Str(c, "anchor")}");
output.WriteLine($" {Str(c, "anchorDetail")}");
if (chain.TryGetProperty("firstBreak", out var brk) && brk.ValueKind == JsonValueKind.Object)
{
output.WriteLine($" first break: chainSeq {Num(brk, "chainSeq")}, eventId {Str(brk, "eventId", "-")}, {Str(brk, "kind")} — {Str(brk, "detail")}");
}
}
}
output.Flush(); output.Flush();
return verified ? 0 : NotVerifiedExitCode; return verified ? 0 : NotVerifiedExitCode;
@@ -8,17 +8,14 @@ namespace ZB.MOM.WW.ScadaBridge.CLI.Commands;
/// The <c>scadabridge audit</c> command group. Provides read access to /// The <c>scadabridge audit</c> command group. Provides read access to
/// the centralized append-only Audit Log via the REST endpoints /// the centralized append-only Audit Log via the REST endpoints
/// (<c>GET /api/audit/query</c>, <c>GET /api/audit/export</c>, /// (<c>GET /api/audit/query</c>, <c>GET /api/audit/export</c>,
/// <c>GET /api/audit/tree</c>), plus <c>verify-chain</c>, which sends the /// <c>GET /api/audit/tree</c>), plus <c>archive list</c> / <c>archive verify</c>
/// <c>VerifyAuditChain</c> management command (hash-chain tamper evidence, ScadaBridge#41),
/// <c>verify-heads</c>, which checks off-box exported chain heads with
/// <c>VerifyAuditChainHeads</c> (ScadaBridge#107), and <c>archive list</c> / <c>archive verify</c>
/// / <c>archive cleanup</c>, which send <c>ListAuditArchives</c> / <c>VerifyAuditArchive</c> /// / <c>archive cleanup</c>, which send <c>ListAuditArchives</c> / <c>VerifyAuditArchive</c>
/// (Parquet cold archive, ScadaBridge#42) / <c>CleanupAuditArchives</c> (ScadaBridge#109). /// (Parquet cold archive, ScadaBridge#42) / <c>CleanupAuditArchives</c> (ScadaBridge#109).
/// </summary> /// </summary>
public static class AuditCommands public static class AuditCommands
{ {
/// <summary> /// <summary>
/// Builds the <c>audit</c> command group with query, export, tree, and verify-chain /// Builds the <c>audit</c> command group with query, export, tree and archive
/// sub-commands. /// sub-commands.
/// </summary> /// </summary>
/// <param name="urlOption">Global <c>--url</c> option for the management API endpoint.</param> /// <param name="urlOption">Global <c>--url</c> option for the management API endpoint.</param>
@@ -33,8 +30,6 @@ public static class AuditCommands
command.Add(BuildQuery(urlOption, formatOption, usernameOption, passwordOption)); command.Add(BuildQuery(urlOption, formatOption, usernameOption, passwordOption));
command.Add(BuildExport(urlOption, formatOption, usernameOption, passwordOption)); command.Add(BuildExport(urlOption, formatOption, usernameOption, passwordOption));
command.Add(BuildTree(urlOption, formatOption, usernameOption, passwordOption)); command.Add(BuildTree(urlOption, formatOption, usernameOption, passwordOption));
command.Add(BuildVerifyChain(urlOption, formatOption, usernameOption, passwordOption));
command.Add(BuildVerifyHeads(urlOption, formatOption, usernameOption, passwordOption));
command.Add(BuildBackfillSourceNode(urlOption, formatOption, usernameOption, passwordOption)); command.Add(BuildBackfillSourceNode(urlOption, formatOption, usernameOption, passwordOption));
command.Add(BuildArchive(urlOption, formatOption, usernameOption, passwordOption)); command.Add(BuildArchive(urlOption, formatOption, usernameOption, passwordOption));
@@ -293,87 +288,10 @@ public static class AuditCommands
return cmd; return cmd;
} }
private static Command BuildVerifyChain(Option<string> urlOption, Option<string> formatOption, Option<string> usernameOption, Option<string> passwordOption)
{
var monthOption = new Option<string>("--month") { Description = "UTC calendar month to verify (YYYY-MM)", Required = true };
var cmd = new Command("verify-chain")
{
Description = "Verify the audit log hash chain for a month; exit 3 and report the first break if it was tampered with",
};
cmd.Add(monthOption);
cmd.SetAction(async (ParseResult result) =>
{
var month = result.GetValue(monthOption)!;
if (!AuditVerifyChainHelpers.IsValidMonth(month))
{
OutputFormatter.WriteError(
$"Invalid month '{month}'. Expected YYYY-MM (e.g. 2026-05).", "INVALID_ARGUMENT");
return 1;
}
var format = AuditCommandHelpers.ResolveFormat(result, formatOption);
return await CommandHelpers.ExecuteCommandAsync(
result, urlOption, formatOption, usernameOption, passwordOption,
new VerifyAuditChainCommand(month),
timeout: AuditVerifyChainHelpers.RequestTimeout,
onSuccess: json => AuditVerifyChainHelpers.Render(json, format, Console.Out));
});
return cmd;
}
/// <summary> /// <summary>
/// Builds the <c>audit archive</c> group (ScadaBridge#42): <c>list</c> and <c>verify</c> /// Builds the <c>audit archive</c> group (ScadaBridge#42): <c>list</c>, <c>verify</c> and
/// over the AuditLog Parquet cold archives on the central archive directory. /// <c>cleanup</c> over the AuditLog Parquet cold archives on the central archive directory.
/// </summary> /// </summary>
private static Command BuildVerifyHeads(Option<string> urlOption, Option<string> formatOption, Option<string> usernameOption, Option<string> passwordOption)
{
var pathOption = new Option<string>("--path")
{
Description = "Export file, or directory of *.jsonl/*.log/*.txt export files (file sink or syslog collector output)",
Required = true,
};
var cmd = new Command("verify-heads")
{
Description = "Check AuditLog chain heads exported off-box against the database chain; exit 3 if any no longer matches",
};
cmd.Add(pathOption);
cmd.SetAction(async (ParseResult result) =>
{
AuditVerifyHeadsHelpers.ReadResult read;
try
{
read = AuditVerifyHeadsHelpers.ReadRecords(result.GetValue(pathOption)!);
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
{
OutputFormatter.WriteError(ex.Message, "INVALID_ARGUMENT");
return 1;
}
if (read.Records.Count == 0)
{
OutputFormatter.WriteError(
$"No chain-head records found in {read.Files} file(s) ({read.LinesSkipped} unparsable line(s)).",
"INVALID_ARGUMENT");
return 1;
}
if (read.LinesSkipped > 0)
{
Console.Error.WriteLine($"warning: skipped {read.LinesSkipped} line(s) without a chain-head record.");
}
var format = AuditCommandHelpers.ResolveFormat(result, formatOption);
return await CommandHelpers.ExecuteCommandAsync(
result, urlOption, formatOption, usernameOption, passwordOption,
new VerifyAuditChainHeadsCommand(read.Records),
timeout: AuditVerifyHeadsHelpers.RequestTimeout,
onSuccess: json => AuditVerifyHeadsHelpers.Render(json, format, Console.Out));
});
return cmd;
}
private static Command BuildArchive(Option<string> urlOption, Option<string> formatOption, Option<string> usernameOption, Option<string> passwordOption) private static Command BuildArchive(Option<string> urlOption, Option<string> formatOption, Option<string> usernameOption, Option<string> passwordOption)
{ {
var group = new Command("archive") { Description = "List, verify and clean up the AuditLog Parquet cold archives" }; var group = new Command("archive") { Description = "List, verify and clean up the AuditLog Parquet cold archives" };
@@ -396,7 +314,7 @@ public static class AuditCommands
}; };
var verify = new Command("verify") var verify = new Command("verify")
{ {
Description = "Verify an archive's files, its hash chain and its purge anchor; exit 3 if it does not verify", Description = "Verify an archive's data file against its manifest; exit 3 if it does not verify",
}; };
verify.Add(nameOption); verify.Add(nameOption);
verify.SetAction(async (ParseResult result) => verify.SetAction(async (ParseResult result) =>
@@ -1,88 +0,0 @@
using System.Globalization;
using System.Text.Json;
namespace ZB.MOM.WW.ScadaBridge.CLI.Commands;
/// <summary>
/// Helpers for the <c>audit verify-chain</c> subcommand (ScadaBridge#41). The command sends
/// the <c>VerifyAuditChain</c> management command for one UTC calendar month and reports
/// whether that month's AuditLog hash chain is intact, or the first break (chain partition,
/// <c>ChainSeq</c>, <c>EventId</c>, kind).
/// </summary>
/// <remarks>
/// Exit codes: <c>0</c> intact (or nothing chained yet), <see cref="BrokenExitCode"/> when
/// the chain is broken, <c>1</c> on a request error, <c>2</c> on an authorization failure.
/// </remarks>
public static class AuditVerifyChainHelpers
{
/// <summary>Process exit code when verification found a break (tamper evidence).</summary>
public const int BrokenExitCode = 3;
/// <summary>
/// Client deadline. The server bounds the call with the long-running management Ask
/// (5 min); the client waits a little longer so the server's answer always arrives.
/// </summary>
public static readonly TimeSpan RequestTimeout = TimeSpan.FromMinutes(6);
/// <summary>
/// Returns true if <paramref name="month"/> is a well-formed <c>YYYY-MM</c> value
/// with a real month (01-12). A malformed month (e.g. <c>2026-13</c>) is rejected.
/// </summary>
/// <param name="month">The month string to validate in YYYY-MM format.</param>
/// <returns><c>true</c> if the string is a well-formed YYYY-MM value with a real month; otherwise <c>false</c>.</returns>
public static bool IsValidMonth(string? month)
=> !string.IsNullOrWhiteSpace(month)
&& DateTime.TryParseExact(month, "yyyy-MM", CultureInfo.InvariantCulture,
DateTimeStyles.None, out _);
/// <summary>
/// Renders a <c>VerifyAuditChain</c> result and maps it to the process exit code.
/// <c>json</c> prints the server body verbatim; <c>table</c> prints a short report.
/// </summary>
/// <param name="json">The success body (an <c>AuditChainVerificationResult</c>, camelCase).</param>
/// <param name="format">Resolved output format.</param>
/// <param name="output">Writer for the report.</param>
/// <returns><c>0</c> when intact / not chained, <see cref="BrokenExitCode"/> when broken.</returns>
public static int Render(string json, string format, TextWriter output)
{
using var doc = JsonDocument.Parse(json);
var root = doc.RootElement;
var status = root.TryGetProperty("status", out var s) ? s.GetString() ?? "" : "";
var broken = string.Equals(status, "Broken", StringComparison.OrdinalIgnoreCase);
if (!string.Equals(format, "table", StringComparison.OrdinalIgnoreCase))
{
output.WriteLine(json);
output.Flush();
return broken ? BrokenExitCode : 0;
}
output.WriteLine($"Partition : {Str(root, "partition")}");
output.WriteLine($"Status : {status}");
output.WriteLine($"Rows verified : {Num(root, "rowsVerified")}");
output.WriteLine($"Tombstones applied: {Num(root, "tombstonesApplied")}");
output.WriteLine($"Purged through : {Num(root, "purgedThroughSeq", "-")}");
output.WriteLine($"Head sequence : {Num(root, "headSeq", "-")}");
output.WriteLine($"Unchained rows : {Num(root, "unchainedRows")}");
output.WriteLine($"Chain from : {Str(root, "chainFromUtc", "- (whole table in scope)")}");
output.WriteLine($"Pre-cutoff rows : {Num(root, "preCutoffRows")}");
if (root.TryGetProperty("firstBreak", out var brk) && brk.ValueKind == JsonValueKind.Object)
{
output.WriteLine("First break:");
output.WriteLine($" partition : {Str(brk, "partition")}");
output.WriteLine($" chainSeq : {Num(brk, "chainSeq")}");
output.WriteLine($" eventId : {Str(brk, "eventId", "-")}");
output.WriteLine($" kind : {Str(brk, "kind")}");
output.WriteLine($" detail : {Str(brk, "detail")}");
}
output.Flush();
return broken ? BrokenExitCode : 0;
}
private static string Str(JsonElement e, string name, string missing = "")
=> e.TryGetProperty(name, out var v) && v.ValueKind == JsonValueKind.String ? v.GetString() ?? missing : missing;
private static string Num(JsonElement e, string name, string missing = "0")
=> e.TryGetProperty(name, out var v) && v.ValueKind == JsonValueKind.Number ? v.GetInt64().ToString(CultureInfo.InvariantCulture) : missing;
}
@@ -1,160 +0,0 @@
using System.Globalization;
using System.Text.Json;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
namespace ZB.MOM.WW.ScadaBridge.CLI.Commands;
/// <summary>
/// Helpers for <c>audit verify-heads</c> (ScadaBridge#107 item 1): read AuditLog chain heads
/// exported off-box (the <c>AuditLog:HashChain:HeadExport</c> JSON lines — straight from the
/// file sink, or from a syslog collector's log), send them in a
/// <c>VerifyAuditChainHeads</c> management command, and render the verdicts.
/// </summary>
/// <remarks>
/// Exit codes: <c>0</c> every exported head is consistent with the database,
/// <see cref="FailedExitCode"/> at least one is not (tamper evidence), <c>1</c> on a request
/// or input error, <c>2</c> on an authorization failure.
/// </remarks>
public static class AuditVerifyHeadsHelpers
{
/// <summary>Process exit code when a head check failed.</summary>
public const int FailedExitCode = 3;
/// <summary>Client deadline (the server bounds the call with the long-running Ask).</summary>
public static readonly TimeSpan RequestTimeout = TimeSpan.FromMinutes(6);
private static readonly JsonSerializerOptions ReadOptions = new(JsonSerializerDefaults.Web);
/// <summary>The result of reading export files.</summary>
/// <param name="Records">Distinct records (by month, sequence, hash), latest export kept.</param>
/// <param name="LinesRead">Lines that held a head record.</param>
/// <param name="LinesSkipped">Non-empty lines without a parsable record.</param>
/// <param name="Files">Files read.</param>
public sealed record ReadResult(IReadOnlyList<AuditChainHeadRecord> Records, int LinesRead, int LinesSkipped, int Files);
/// <summary>
/// Reads every record from <paramref name="path"/> — one file, or every <c>*.jsonl</c> /
/// <c>*.log</c> / <c>*.txt</c> file below a directory. Each line's JSON object is taken from
/// its first <c>{</c> to its last <c>}</c>, so syslog-prefixed lines parse too.
/// </summary>
/// <param name="path">File or directory.</param>
/// <returns>The records read.</returns>
/// <exception cref="FileNotFoundException">The path does not exist.</exception>
public static ReadResult ReadRecords(string path)
{
string[] files;
if (File.Exists(path))
{
files = [path];
}
else if (Directory.Exists(path))
{
files = Directory.EnumerateFiles(path, "*", SearchOption.AllDirectories)
.Where(f => f.EndsWith(".jsonl", StringComparison.OrdinalIgnoreCase)
|| f.EndsWith(".log", StringComparison.OrdinalIgnoreCase)
|| f.EndsWith(".txt", StringComparison.OrdinalIgnoreCase))
.Order(StringComparer.Ordinal)
.ToArray();
}
else
{
throw new FileNotFoundException($"'{path}' is neither a file nor a directory.", path);
}
var records = new List<AuditChainHeadRecord>();
int read = 0, skipped = 0;
foreach (var file in files)
{
foreach (var line in File.ReadLines(file))
{
if (string.IsNullOrWhiteSpace(line))
{
continue;
}
var record = TryParseLine(line);
if (record is null)
{
skipped++;
continue;
}
read++;
records.Add(record);
}
}
var distinct = records
.GroupBy(r => (r.Month, r.LastSeq, Hash: r.LastHash.ToLowerInvariant()))
.Select(g => g.OrderByDescending(r => r.ExportedAtUtc).First())
.OrderBy(r => r.Month, StringComparer.Ordinal)
.ThenBy(r => r.LastSeq)
.ToList();
return new ReadResult(distinct, read, skipped, files.Length);
}
/// <summary>Parses one export line; null when it holds no valid record.</summary>
/// <param name="line">The line.</param>
/// <returns>The record, or null.</returns>
public static AuditChainHeadRecord? TryParseLine(string line)
{
var start = line.IndexOf('{');
var end = line.LastIndexOf('}');
if (start < 0 || end <= start)
{
return null;
}
try
{
var record = JsonSerializer.Deserialize<AuditChainHeadRecord>(line.AsSpan(start, end - start + 1), ReadOptions);
return record is { V: >= 1, Month.Length: 7, LastHash.Length: > 0 } && record.LastSeq > 0 ? record : null;
}
catch (JsonException)
{
return null;
}
}
/// <summary>Renders a <c>VerifyAuditChainHeads</c> result and maps it to the exit code.</summary>
/// <param name="json">Success body (an <c>AuditChainHeadVerificationResult</c>, camelCase).</param>
/// <param name="format">Resolved output format.</param>
/// <param name="output">Writer for the report.</param>
/// <returns><c>0</c> when verified, <see cref="FailedExitCode"/> otherwise.</returns>
public static int Render(string json, string format, TextWriter output)
{
using var doc = JsonDocument.Parse(json);
var root = doc.RootElement;
var verified = root.TryGetProperty("verified", out var v) && v.ValueKind == JsonValueKind.True;
if (!string.Equals(format, "table", StringComparison.OrdinalIgnoreCase))
{
output.WriteLine(json);
output.Flush();
return verified ? 0 : FailedExitCode;
}
output.WriteLine($"Verified : {(verified ? "yes" : "NO")}");
output.WriteLine($"Heads checked : {Num(root, "recordsChecked")}");
if (root.TryGetProperty("checks", out var checks) && checks.ValueKind == JsonValueKind.Array)
{
output.WriteLine($"{"MONTH",-8} {"EXPORTED SEQ",12} {"DB SEQ",8} {"STATUS",-13} DETAIL");
foreach (var c in checks.EnumerateArray())
{
output.WriteLine(string.Create(CultureInfo.InvariantCulture,
$"{Str(c, "month"),-8} {Num(c, "exportedSeq"),12} {Num(c, "databaseSeq", "-"),8} {Str(c, "status"),-13} {Str(c, "detail")}"));
}
}
output.Flush();
return verified ? 0 : FailedExitCode;
}
private static string Str(JsonElement e, string name)
=> e.TryGetProperty(name, out var v) && v.ValueKind == JsonValueKind.String ? v.GetString() ?? "" : "";
private static string Num(JsonElement e, string name, string missing = "0")
=> e.TryGetProperty(name, out var v) && v.ValueKind == JsonValueKind.Number
? v.GetInt64().ToString(CultureInfo.InvariantCulture)
: missing;
}
@@ -1,11 +0,0 @@
namespace ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories;
/// <summary>DI keys for the AuditLog maintenance-login registrations (ScadaBridge#107/#113).</summary>
public static class AuditLogServiceKeys
{
/// <summary>
/// Key of the maintenance-login <see cref="IAuditLogRepository"/> / <c>IAuditLogArchive</c>:
/// the connection from <c>AuditLog:MaintenanceConnectionString</c>, or the runtime connection when unset.
/// </summary>
public const string Maintenance = "audit-maintenance";
}
@@ -1,28 +0,0 @@
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
namespace ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories;
/// <summary>
/// Reads the AuditLog hash-chain heads for off-box export and checks exported heads against
/// the database chain (ScadaBridge#107 item 1 — the external anchor of the #41 chain).
/// </summary>
public interface IAuditChainHeadStore
{
/// <summary>
/// Reads every month's chain head with its live chained-row and tombstone counts, in one
/// consistent snapshot (under the chain lock SHARED, so no chaining pass or purge is half-way).
/// </summary>
/// <param name="ct">Cancellation token.</param>
/// <returns>One snapshot per month that has a head, oldest first.</returns>
Task<IReadOnlyList<AuditChainHeadSnapshot>> ReadHeadsAsync(CancellationToken ct = default);
/// <summary>
/// Checks exported head records against the database: for each distinct exported head, does
/// the database still carry the exported hash at the exported sequence?
/// </summary>
/// <param name="records">Exported records (duplicates are collapsed).</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>The per-record verdicts.</returns>
Task<AuditChainHeadVerificationResult> VerifyExportedHeadsAsync(
IReadOnlyList<AuditChainHeadRecord> records, CancellationToken ct = default);
}
@@ -10,16 +10,10 @@ namespace ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories;
/// <remarks> /// <remarks>
/// <para> /// <para>
/// <b>Archive before purge.</b> <see cref="ArchivePartitionAsync"/> writes the partition's /// <b>Archive before purge.</b> <see cref="ArchivePartitionAsync"/> writes the partition's
/// rows (with their hash-chain columns), the month's chain head and its per-channel purge /// rows; <see cref="PurgeArchivedPartitionAsync"/> then switches the partition out inside a
/// tombstones; <see cref="PurgeArchivedPartitionAsync"/> then switches the partition out /// guard that refuses to drop it if the partition gained or lost a row since the archive was
/// inside a guard that refuses to drop it if the partition gained or lost a row, or its /// written. A partition is therefore never purged without an archive that holds exactly the
/// chain advanced, since the archive was written. A partition is therefore never purged /// rows the purge drops.
/// without an archive that holds exactly the rows the purge drops.
/// </para>
/// <para>
/// <b>Hash chain.</b> The switch records each month's chain end as the checkpoint anchor
/// (ScadaBridge#41); the archive records the same chain end, so <see cref="VerifyAsync"/>
/// can recompute the archived chain and tie its end to the anchor still in the database.
/// </para> /// </para>
/// </remarks> /// </remarks>
public interface IAuditLogArchive public interface IAuditLogArchive
@@ -58,8 +52,7 @@ public interface IAuditLogArchive
Task<IReadOnlyList<AuditArchiveManifest>> ListAsync(CancellationToken ct = default); Task<IReadOnlyList<AuditArchiveManifest>> ListAsync(CancellationToken ct = default);
/// <summary> /// <summary>
/// Verifies one archive: file integrity against the manifest, the hash chain recomputed /// Verifies one archive: data-file integrity (size, SHA-256, row count) against the manifest.
/// over the archived rows, and the chain end against the database's checkpoint anchor.
/// </summary> /// </summary>
/// <param name="name">The archive name (as <see cref="ListAsync"/> reports it).</param> /// <param name="name">The archive name (as <see cref="ListAsync"/> reports it).</param>
/// <param name="ct">Cancellation token.</param> /// <param name="ct">Cancellation token.</param>
@@ -70,7 +63,7 @@ public interface IAuditLogArchive
/// <summary> /// <summary>
/// Archive cleanup (ScadaBridge#109): deletes superseded stale archives a retried purge left /// Archive cleanup (ScadaBridge#109): deletes superseded stale archives a retried purge left
/// behind (when <c>AuditLog:Archive:DeleteSupersededStaleArchives</c>), and archives past /// behind (when <c>AuditLog:Archive:DeleteSupersededStaleArchives</c>), and archives past
/// <c>AuditLog:Archive:RetentionDays</c> (0 = never). Only ever deletes the three files of a /// <c>AuditLog:Archive:RetentionDays</c> (0 = never). Only ever deletes the files of a
/// well-formed archive inside the configured directory, manifest first. /// well-formed archive inside the configured directory, manifest first.
/// </summary> /// </summary>
/// <param name="dryRun">Report only; delete nothing.</param> /// <param name="dryRun">Report only; delete nothing.</param>
@@ -81,7 +74,7 @@ public interface IAuditLogArchive
/// <summary> /// <summary>
/// Thrown by <see cref="IAuditLogArchive.PurgeArchivedPartitionAsync"/> when the partition /// Thrown by <see cref="IAuditLogArchive.PurgeArchivedPartitionAsync"/> when the partition
/// gained or lost rows, or its hash chain advanced, after the archive was written. Nothing /// gained or lost rows after the archive was written. Nothing
/// is purged; the next purge tick writes a fresh archive. /// is purged; the next purge tick writes a fresh archive.
/// </summary> /// </summary>
public sealed class AuditArchiveStaleException : Exception public sealed class AuditArchiveStaleException : Exception
@@ -1,58 +0,0 @@
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
namespace ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories;
/// <summary>
/// Hash-chain tamper evidence for the central <c>AuditLog</c> table (audit roadmap T1,
/// alog.md §11.4, ScadaBridge#41).
/// </summary>
/// <remarks>
/// <para>
/// One chain per <b>partition</b> = UTC calendar month of <c>OccurredAtUtc</c> (the same
/// month the <c>ps_AuditLog_Month</c> scheme partitions on). Each chained row carries a
/// <c>ChainSeq</c> (1, 2, 3 … within its month) and
/// <c>RowHash = SHA-256(prev.RowHash || canonical(row))</c>, where <c>prev</c> is the row
/// at <c>ChainSeq - 1</c> (32 zero bytes for the first). The canonical serialisation
/// covers every writable column plus the month and sequence number.
/// </para>
/// <para>
/// Rows are linked by a <b>chaining job</b>, not by the hot-path writers: two central
/// nodes and the site-ingest path all INSERT concurrently, so a write-time chain would
/// need a global serialisation point on every audit write. The job serialises itself
/// with an exclusive SQL Server application lock, so even a dual-active central pair
/// produces one gap-free chain per month.
/// </para>
/// </remarks>
public interface IAuditLogHashChain
{
/// <summary>
/// Links up to <paramref name="batchSize"/> unchained rows (oldest
/// <c>OccurredAtUtc</c> first) onto the end of their month's chain, in one transaction.
/// Returns immediately with <see cref="AuditChainBatchResult.LockBusy"/> set when another
/// chainer holds the chain lock.
/// </summary>
/// <remarks>
/// <b>Chain start (ScadaBridge#139).</b> On a pristine database (nothing ever chained) and
/// with <paramref name="chainBacklog"/> false, the first pass records a chain-start anchor
/// at the database's current UTC time; from then on only rows dated at or after it are
/// chained, whatever either node passes later. With <paramref name="chainBacklog"/> true on
/// that first pass, no anchor is written and every row is chained, oldest month first. A
/// database that already has a chain and no anchor keeps chaining every row.
/// </remarks>
/// <param name="batchSize">Maximum rows to chain in this pass.</param>
/// <param name="chainBacklog">
/// Only consulted on a pristine database: true chains the historical backlog instead of
/// starting the chain now.
/// </param>
/// <param name="ct">Cancellation token.</param>
/// <returns>How many rows were chained, and whether the lock was busy.</returns>
Task<AuditChainBatchResult> ChainPendingAsync(int batchSize, bool chainBacklog = false, CancellationToken ct = default);
/// <summary>
/// Verifies one month's chain end to end and reports the first break.
/// </summary>
/// <param name="monthStartUtc">The first instant of the month (UTC, day 1, midnight).</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>The verification result.</returns>
Task<AuditChainVerificationResult> VerifyMonthAsync(DateTime monthStartUtc, CancellationToken ct = default);
}
@@ -158,11 +158,6 @@ public interface IAuditLogRepository
/// <c>OccurredAtUtc</c> is strictly older than <paramref name="threshold"/>, in /// <c>OccurredAtUtc</c> is strictly older than <paramref name="threshold"/>, in
/// bounded batches of <paramref name="batchSize"/> rows, looping until no further /// bounded batches of <paramref name="batchSize"/> rows, looping until no further
/// rows match. Returns the total number of rows deleted across all batches. /// rows match. Returns the total number of rows deleted across all batches.
/// <para>
/// Hash chain (ScadaBridge#41): every CHAINED row the DELETE removes leaves a
/// <c>dbo.AuditLogChainTombstone</c> (month, ChainSeq, RowHash) written in the same
/// transaction, under the exclusive chain lock, so the month's chain still verifies.
/// </para>
/// </summary> /// </summary>
/// <remarks> /// <remarks>
/// <para> /// <para>
@@ -25,23 +25,6 @@ public record QueryAuditLogCommand(
/// <param name="TotalCount">Total number of rows matching the filters (unpaged).</param> /// <param name="TotalCount">Total number of rows matching the filters (unpaged).</param>
public record AuditLogQueryResult(IReadOnlyList<AuditLogEntry> Entries, int TotalCount); public record AuditLogQueryResult(IReadOnlyList<AuditLogEntry> Entries, int TotalCount);
/// <summary>
/// Verifies the central AuditLog hash chain for one UTC calendar month (audit roadmap T1,
/// ScadaBridge#41). Read-only; gated on the OperationalAudit roles and refused for a
/// site-scoped caller, because a month's chain spans every site.
/// </summary>
/// <param name="Month">The month to verify, <c>YYYY-MM</c>.</param>
public record VerifyAuditChainCommand(string Month);
/// <summary>
/// Checks AuditLog chain heads exported off-box (<c>AuditLog:HashChain:HeadExport</c>,
/// ScadaBridge#107 item 1) against the database chain: does the database still carry each
/// exported hash at its exported sequence? Read-only; same gate as
/// <see cref="VerifyAuditChainCommand"/>. The CLI reads the records from the export files.
/// </summary>
/// <param name="Records">The exported head records (at most 50,000; duplicates are collapsed).</param>
public record VerifyAuditChainHeadsCommand(IReadOnlyList<AuditChainHeadRecord> Records);
/// <summary> /// <summary>
/// Lists the AuditLog Parquet cold archives under the configured archive directory (audit /// Lists the AuditLog Parquet cold archives under the configured archive directory (audit
/// roadmap T2, ScadaBridge#42). Read-only; OperationalAudit roles, refused for a site-scoped /// roadmap T2, ScadaBridge#42). Read-only; OperationalAudit roles, refused for a site-scoped
@@ -50,9 +33,8 @@ public record VerifyAuditChainHeadsCommand(IReadOnlyList<AuditChainHeadRecord> R
public record ListAuditArchivesCommand; public record ListAuditArchivesCommand;
/// <summary> /// <summary>
/// Verifies one AuditLog Parquet archive (ScadaBridge#42): file integrity against its /// Verifies one AuditLog Parquet archive (ScadaBridge#42): data-file integrity against its
/// manifest, the hash chain recomputed over the archived rows, and the chain end against the /// manifest (size, SHA-256, row count). Read-only; same gate as
/// checkpoint anchor the partition purge left. Read-only; same gate as
/// <see cref="ListAuditArchivesCommand"/>. /// <see cref="ListAuditArchivesCommand"/>.
/// </summary> /// </summary>
/// <param name="Name">The archive name, as <c>audit archive list</c> reports it.</param> /// <param name="Name">The archive name, as <c>audit archive list</c> reports it.</param>
@@ -11,8 +11,7 @@ public enum AuditArchiveStatus
/// <summary> /// <summary>
/// The archive files are durable but the partition switch that should follow has not /// The archive files are durable but the partition switch that should follow has not
/// been confirmed: either it failed (the archive went stale and a later tick wrote a /// been confirmed: either it failed (the archive went stale and a later tick wrote a
/// fresh one) or the node stopped between the switch and the manifest update. Verify /// fresh one) or the node stopped between the switch and the manifest update.
/// tells the two apart: only the second one's chain end matches the database anchor.
/// </summary> /// </summary>
Archived, Archived,
@@ -20,48 +19,25 @@ public enum AuditArchiveStatus
Purged, Purged,
} }
/// <summary>
/// One chain partition (UTC calendar month) as it stood when its rows were archived: the
/// chain head and the checkpoint anchor an earlier partition purge had left, so the archived
/// rows can be re-verified with <c>AuditChainVerifier</c> long after the database dropped them.
/// </summary>
/// <param name="Partition">The chain partition, <c>YYYY-MM</c>.</param>
/// <param name="LastSeq">The head's last sequence number at archive time.</param>
/// <param name="LastHash">The head's last hash at archive time (lowercase hex).</param>
/// <param name="PriorPurgedThroughSeq">The checkpoint anchor an earlier purge of this month left, or null.</param>
/// <param name="PriorPurgedThroughHash">The hash at <paramref name="PriorPurgedThroughSeq"/> (lowercase hex), or null.</param>
/// <param name="TombstoneCount">Per-channel purge tombstones of this month carried in the archive.</param>
public sealed record AuditArchiveChainState(
string Partition,
long LastSeq,
string LastHash,
long? PriorPurgedThroughSeq,
string? PriorPurgedThroughHash,
long TombstoneCount);
/// <summary> /// <summary>
/// The JSON manifest written beside every AuditLog Parquet archive (ScadaBridge#42). It is /// The JSON manifest written beside every AuditLog Parquet archive (ScadaBridge#42). It is
/// written LAST, so its presence is the commit marker for the archive's two Parquet files. /// written LAST, so its presence is the commit marker for the archive's Parquet data file.
/// A format-v1 manifest (written while the audit hash chain existed, before 2026-11-15) also
/// carries chain and tombstone fields; they are ignored when it is read.
/// </summary> /// </summary>
/// <param name="FormatVersion">Manifest/file layout version (currently 1).</param> /// <param name="FormatVersion">Manifest/file layout version (currently 2; 1 = written with the hash chain).</param>
/// <param name="Name">Archive name, <c>auditlog-YYYY-MM-yyyyMMddTHHmmssfffZ</c>; the file stem of all three files.</param> /// <param name="Name">Archive name, <c>auditlog-YYYY-MM-yyyyMMddTHHmmssfffZ</c>; the file stem of the archive's files.</param>
/// <param name="PartitionBoundaryUtc">The <c>pf_AuditLog_Month</c> lower boundary of the archived partition.</param> /// <param name="PartitionBoundaryUtc">The <c>pf_AuditLog_Month</c> lower boundary of the archived partition.</param>
/// <param name="Partition">The archived partition, <c>YYYY-MM</c>.</param> /// <param name="Partition">The archived partition, <c>YYYY-MM</c>.</param>
/// <param name="ArchivedAtUtc">When the archive was written.</param> /// <param name="ArchivedAtUtc">When the archive was written.</param>
/// <param name="Status">Whether the partition switch that follows the archive has been confirmed.</param> /// <param name="Status">Whether the partition switch that follows the archive has been confirmed.</param>
/// <param name="PurgedAtUtc">When the partition switch completed, or null.</param> /// <param name="PurgedAtUtc">When the partition switch completed, or null.</param>
/// <param name="RowCount">Rows in the data file.</param> /// <param name="RowCount">Rows in the data file.</param>
/// <param name="ChainedRowCount">Rows that carried a ChainSeq/RowHash.</param>
/// <param name="UnchainedRowCount">Rows the chaining job had not reached (not covered by the chain).</param>
/// <param name="MinOccurredAtUtc">Earliest OccurredAtUtc in the data file, or null when empty.</param> /// <param name="MinOccurredAtUtc">Earliest OccurredAtUtc in the data file, or null when empty.</param>
/// <param name="MaxOccurredAtUtc">Latest OccurredAtUtc in the data file, or null when empty.</param> /// <param name="MaxOccurredAtUtc">Latest OccurredAtUtc in the data file, or null when empty.</param>
/// <param name="DataFile">Data file name, relative to the manifest's directory.</param> /// <param name="DataFile">Data file name, relative to the manifest's directory.</param>
/// <param name="DataSha256">SHA-256 of the data file (lowercase hex).</param> /// <param name="DataSha256">SHA-256 of the data file (lowercase hex).</param>
/// <param name="DataBytes">Size of the data file in bytes.</param> /// <param name="DataBytes">Size of the data file in bytes.</param>
/// <param name="TombstoneFile">Tombstone file name, relative to the manifest's directory.</param>
/// <param name="TombstoneSha256">SHA-256 of the tombstone file (lowercase hex).</param>
/// <param name="TombstoneCount">Tombstones in the tombstone file.</param>
/// <param name="Chains">One entry per chain partition that had a head when the rows were archived.</param>
public sealed record AuditArchiveManifest( public sealed record AuditArchiveManifest(
int FormatVersion, int FormatVersion,
string Name, string Name,
@@ -71,66 +47,23 @@ public sealed record AuditArchiveManifest(
AuditArchiveStatus Status, AuditArchiveStatus Status,
DateTime? PurgedAtUtc, DateTime? PurgedAtUtc,
long RowCount, long RowCount,
long ChainedRowCount,
long UnchainedRowCount,
DateTime? MinOccurredAtUtc, DateTime? MinOccurredAtUtc,
DateTime? MaxOccurredAtUtc, DateTime? MaxOccurredAtUtc,
string DataFile, string DataFile,
string DataSha256, string DataSha256,
long DataBytes, long DataBytes);
string TombstoneFile,
string TombstoneSha256,
long TombstoneCount,
IReadOnlyList<AuditArchiveChainState> Chains);
/// <summary> /// <summary>
/// How an archive's recorded chain end relates to the checkpoint anchor the partition purge /// Result of <c>audit archive verify</c> (ScadaBridge#42): the data file matches its manifest
/// left on the database's chain head. /// (size, SHA-256 and row count).
/// </summary>
[JsonConverter(typeof(JsonStringEnumConverter<AuditArchiveAnchorStatus>))]
public enum AuditArchiveAnchorStatus
{
/// <summary>The database anchor is exactly the archive's chain end (sequence and hash).</summary>
Matches,
/// <summary>
/// The database anchor is past the archive's chain end: rows that arrived late for this
/// month were chained and purged (and archived) again afterwards.
/// </summary>
Superseded,
/// <summary>The partition has not been purged: the archive's rows are still in <c>dbo.AuditLog</c>.</summary>
NotPurged,
/// <summary>
/// The anchor disagrees with the archive (an earlier sequence number, a different hash, or
/// no chain head at all): the archive or the head was altered.
/// </summary>
Mismatch,
}
/// <summary>Verification of one chain partition inside an archive.</summary>
/// <param name="Chain">The chain recomputed over the archived rows, the archived head and tombstones.</param>
/// <param name="Anchor">How the archived chain end relates to the database's checkpoint anchor.</param>
/// <param name="AnchorDetail">Human-readable explanation of <paramref name="Anchor"/>.</param>
public sealed record AuditArchiveChainVerification(
AuditChainVerificationResult Chain,
AuditArchiveAnchorStatus Anchor,
string AnchorDetail);
/// <summary>
/// Result of <c>audit archive verify</c> (ScadaBridge#42): the archive files match their
/// manifest, every archived chain recomputes to the archived head, and each chain end is the
/// anchor the partition purge left in the database.
/// </summary> /// </summary>
/// <param name="Name">The archive verified.</param> /// <param name="Name">The archive verified.</param>
/// <param name="Partition">The archived partition, <c>YYYY-MM</c>.</param> /// <param name="Partition">The archived partition, <c>YYYY-MM</c>.</param>
/// <param name="ManifestStatus">The manifest's lifecycle status.</param> /// <param name="ManifestStatus">The manifest's lifecycle status.</param>
/// <param name="Verified">True when the files are intact, no chain is broken and no anchor mismatches.</param> /// <param name="Verified">True when the data file is intact.</param>
/// <param name="FilesIntact">True when both files' size and SHA-256 and the row/tombstone counts match the manifest.</param> /// <param name="FilesIntact">True when the data file's size, SHA-256 and row count match the manifest.</param>
/// <param name="FileProblem">Why <paramref name="FilesIntact"/> is false, or null.</param> /// <param name="FileProblem">Why <paramref name="FilesIntact"/> is false, or null.</param>
/// <param name="RowsRead">Rows read from the data file.</param> /// <param name="RowsRead">Rows read from the data file.</param>
/// <param name="Chains">Per chain partition verification.</param>
public sealed record AuditArchiveVerificationResult( public sealed record AuditArchiveVerificationResult(
string Name, string Name,
string Partition, string Partition,
@@ -138,8 +71,7 @@ public sealed record AuditArchiveVerificationResult(
bool Verified, bool Verified,
bool FilesIntact, bool FilesIntact,
string? FileProblem, string? FileProblem,
long RowsRead, long RowsRead);
IReadOnlyList<AuditArchiveChainVerification> Chains);
/// <summary>Result of <c>audit archive list</c> (ScadaBridge#42).</summary> /// <summary>Result of <c>audit archive list</c> (ScadaBridge#42).</summary>
/// <param name="Enabled">Whether the retention purge is archiving partitions (<c>AuditLog:Archive:Enabled</c>).</param> /// <param name="Enabled">Whether the retention purge is archiving partitions (<c>AuditLog:Archive:Enabled</c>).</param>
@@ -159,8 +91,7 @@ public enum AuditArchiveCleanupAction
/// <summary> /// <summary>
/// Deleted as a superseded stale archive: status <c>Archived</c> (its partition switch never /// Deleted as a superseded stale archive: status <c>Archived</c> (its partition switch never
/// completed — a retried purge), and a LATER, verified, <c>Purged</c> archive of the same /// completed — a retried purge), and a LATER, verified, <c>Purged</c> archive of the same
/// partition provably holds every row it holds (same chain through its chain end, every /// partition provably holds every row it holds (every row present by EventId).
/// unchained row present by EventId).
/// </summary> /// </summary>
DeletedSuperseded, DeletedSuperseded,
@@ -172,7 +103,7 @@ public enum AuditArchiveCleanupAction
/// <summary> /// <summary>
/// Deleted as an orphan of an interrupted archive write (ScadaBridge#114): a temp file of the /// Deleted as an orphan of an interrupted archive write (ScadaBridge#114): a temp file of the
/// archive writer (<c>*.parquet.tmp</c>, <c>*.tombstones.parquet.tmp</c>, <c>*.manifest.json.tmp</c>) /// archive writer (<c>*.parquet.tmp</c>, <c>*.manifest.json.tmp</c>, or a format-v1 <c>*.tombstones.parquet.tmp</c>)
/// or a data file whose <c>.manifest.json</c> was never written, older than the safe age. /// or a data file whose <c>.manifest.json</c> was never written, older than the safe age.
/// </summary> /// </summary>
DeletedOrphan, DeletedOrphan,
@@ -1,126 +0,0 @@
using System.Text.Json.Serialization;
namespace ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
/// <summary>
/// One month's AuditLog hash-chain head as exported off-box (ScadaBridge#107 item 1). The
/// export is the external anchor the in-database chain lacks: a principal able to rewrite rows,
/// recompute every later link and update <c>AuditLogChainHead</c> produces a chain that
/// <c>verify-chain</c> accepts, but cannot change a head hash that already left the box.
/// </summary>
/// <remarks>
/// Serialised as one JSON object per line (camelCase) by both export sinks; the
/// <c>audit verify-heads</c> CLI reads those lines back and the server compares them with the
/// database. Hashes are lowercase hex. The format is versioned by <see cref="V"/>.
/// </remarks>
/// <param name="V">Record format version (1).</param>
/// <param name="Month">Chain partition, the UTC calendar month <c>YYYY-MM</c>.</param>
/// <param name="LastSeq">The head's last sequence number — links written for the month so far.</param>
/// <param name="LastHash">The head's last link hash (hex).</param>
/// <param name="PurgedThroughSeq">The partition-purge checkpoint anchor's sequence, or null.</param>
/// <param name="PurgedThroughHash">The anchor's hash (hex), or null.</param>
/// <param name="ChainedRows">Chained rows of the month still in <c>dbo.AuditLog</c> at export time.</param>
/// <param name="Tombstones">Per-channel purge tombstones of the month at export time.</param>
/// <param name="HeadUpdatedAtUtc">When the head row was last advanced.</param>
/// <param name="ExportedAtUtc">When this record was exported.</param>
/// <param name="Node">The central node that exported it.</param>
public sealed record AuditChainHeadRecord(
int V,
string Month,
long LastSeq,
string LastHash,
long? PurgedThroughSeq,
string? PurgedThroughHash,
long ChainedRows,
long Tombstones,
DateTime HeadUpdatedAtUtc,
DateTime ExportedAtUtc,
string? Node)
{
/// <summary>The current record format version.</summary>
public const int CurrentVersion = 1;
}
/// <summary>Outcome of comparing one exported head with the database chain.</summary>
[JsonConverter(typeof(JsonStringEnumConverter<AuditChainHeadStatus>))]
public enum AuditChainHeadStatus
{
/// <summary>The database head is exactly the exported head (same sequence, same hash, same row + tombstone count).</summary>
Matches,
/// <summary>The chain has grown since the export and the link at the exported sequence still carries the exported hash.</summary>
Extended,
/// <summary>
/// The link at the exported sequence was removed by a monthly partition purge (it is at or
/// before the checkpoint anchor and not the anchor itself), so the database cannot confirm
/// it; verify the month's Parquet archive instead (<c>audit archive verify</c>).
/// </summary>
Purged,
/// <summary>The link at the exported sequence carries a different hash: the chain was rewritten.</summary>
Mismatch,
/// <summary>The database head's sequence is BELOW the exported one: links were removed and the head rolled back.</summary>
Regressed,
/// <summary>The month's head row is gone although links had been exported for it.</summary>
MissingHead,
/// <summary>No row, tombstone or anchor carries the exported sequence any more: a chained row was deleted outside the purge paths.</summary>
MissingLink,
/// <summary>
/// Same head as exported, no partition purge since, but chained rows + tombstones differ
/// from the exported counts: a chained row was removed or its link cleared.
/// </summary>
CountMismatch,
}
/// <summary>One exported head checked against the database.</summary>
/// <param name="Month">Chain partition (<c>YYYY-MM</c>).</param>
/// <param name="ExportedSeq">The exported head's sequence.</param>
/// <param name="ExportedAtUtc">When it was exported.</param>
/// <param name="Node">Which node exported it.</param>
/// <param name="Status">The verdict.</param>
/// <param name="DatabaseSeq">The database head's current sequence, or null when it has none.</param>
/// <param name="Detail">Human-readable explanation.</param>
public sealed record AuditChainHeadCheck(
string Month,
long ExportedSeq,
DateTime ExportedAtUtc,
string? Node,
AuditChainHeadStatus Status,
long? DatabaseSeq,
string Detail)
{
/// <summary>True for the verdicts that are tamper evidence.</summary>
[JsonIgnore]
public bool IsFailure => Status is AuditChainHeadStatus.Mismatch or AuditChainHeadStatus.Regressed
or AuditChainHeadStatus.MissingHead or AuditChainHeadStatus.MissingLink or AuditChainHeadStatus.CountMismatch;
}
/// <summary>Result of <c>audit verify-heads</c>.</summary>
/// <param name="Verified">True when no check is a failure.</param>
/// <param name="RecordsChecked">Distinct exported heads checked.</param>
/// <param name="Checks">Every check, failures first, then by month and sequence.</param>
public sealed record AuditChainHeadVerificationResult(bool Verified, int RecordsChecked, IReadOnlyList<AuditChainHeadCheck> Checks);
/// <summary>The database's current chain head for a month, as read for export.</summary>
/// <param name="Month">First instant of the month (UTC).</param>
/// <param name="LastSeq">Head sequence.</param>
/// <param name="LastHash">Head hash.</param>
/// <param name="PurgedThroughSeq">Checkpoint anchor sequence, or null.</param>
/// <param name="PurgedThroughHash">Checkpoint anchor hash, or null.</param>
/// <param name="ChainedRows">Chained rows of the month still present.</param>
/// <param name="Tombstones">Tombstones of the month.</param>
/// <param name="UpdatedAtUtc">When the head row was last advanced.</param>
public sealed record AuditChainHeadSnapshot(
DateTime Month,
long LastSeq,
byte[] LastHash,
long? PurgedThroughSeq,
byte[]? PurgedThroughHash,
long ChainedRows,
long Tombstones,
DateTime UpdatedAtUtc);
@@ -1,126 +0,0 @@
using System.Text.Json.Serialization;
namespace ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
/// <summary>
/// Overall outcome of verifying one month's AuditLog hash chain (audit roadmap T1,
/// ScadaBridge#41).
/// </summary>
[JsonConverter(typeof(JsonStringEnumConverter<AuditChainStatus>))]
public enum AuditChainStatus
{
/// <summary>Every chained row, tombstone and the chain head agree.</summary>
Intact,
/// <summary>The chain is broken; <see cref="AuditChainVerificationResult.FirstBreak"/> names where.</summary>
Broken,
/// <summary>The month has no chained rows and no chain head — nothing to verify yet.</summary>
NotChained,
}
/// <summary>How the first chain break manifested.</summary>
[JsonConverter(typeof(JsonStringEnumConverter<AuditChainBreakKind>))]
public enum AuditChainBreakKind
{
/// <summary>
/// A row's recomputed hash differs from its stored <c>RowHash</c>: the row's content
/// was edited, or rows were reordered (their <c>ChainSeq</c> values swapped).
/// </summary>
HashMismatch,
/// <summary>
/// A sequence number is absent and no purge tombstone covers it: a chained row was
/// deleted outside the sanctioned purge path, or its <c>ChainSeq</c> was cleared.
/// </summary>
MissingRow,
/// <summary>Two rows carry the same <c>ChainSeq</c>.</summary>
DuplicateSequence,
/// <summary>A chained row carries a <c>ChainSeq</c> but no <c>RowHash</c> (or vice versa).</summary>
IncompleteLink,
/// <summary>
/// The chain ends before (or after) the sequence/hash the chain head records: rows were
/// deleted from the tail, or the head itself was altered.
/// </summary>
HeadMismatch,
/// <summary>
/// A chained row is dated before the chain cutoff (ScadaBridge#139). Rows before the cutoff
/// are never chained, so the row's <c>OccurredAtUtc</c> was moved back (to hide it among the
/// unprotected pre-cutoff rows) or the cutoff itself was moved forward.
/// </summary>
ChainedBeforeCutoff,
/// <summary>
/// The chain-start (cutoff) anchor is inconsistent (ScadaBridge#139): its stored hash does not
/// match its cutoff, it sits in the wrong month, or more than one anchor exists. The cutoff
/// that decides which rows are in scope cannot be trusted.
/// </summary>
CutoffAnchorInvalid,
}
/// <summary>
/// The first point at which a month's chain fails verification.
/// </summary>
/// <param name="Partition">The chain partition — the UTC calendar month, formatted <c>YYYY-MM</c>.</param>
/// <param name="ChainSeq">The sequence number at which the break was detected.</param>
/// <param name="EventId">
/// The <c>EventId</c> of the row at (or, for <see cref="AuditChainBreakKind.MissingRow"/>,
/// immediately after) the break; null when no row is present there (tail truncation).
/// </param>
/// <param name="Kind">How the break manifested.</param>
/// <param name="Detail">Human-readable explanation.</param>
public sealed record AuditChainBreak(
string Partition,
long ChainSeq,
Guid? EventId,
AuditChainBreakKind Kind,
string Detail);
/// <summary>
/// Result of <c>audit verify-chain --month YYYY-MM</c>: whether the month's AuditLog hash
/// chain is intact, and if not, the first break.
/// </summary>
/// <param name="Partition">The chain partition verified (<c>YYYY-MM</c>).</param>
/// <param name="Status">Overall outcome.</param>
/// <param name="RowsVerified">Chained rows whose hash was recomputed and matched before the first break (or in total when intact).</param>
/// <param name="TombstonesApplied">Sequence numbers bridged by a sanctioned purge tombstone (per-channel retention).</param>
/// <param name="PurgedThroughSeq">
/// The checkpoint anchor left by a monthly partition purge: the last sequence number the
/// purge removed. Verification starts immediately after it. Null when the month was never purged.
/// </param>
/// <param name="HeadSeq">The last sequence number the chain head records, or null when the month has no head.</param>
/// <param name="UnchainedRows">
/// Rows in the month, at or after the chain cutoff, that the chaining job has not reached yet
/// (written since the last tick, or written while chaining was disabled). They are not covered
/// by the chain yet.
/// </param>
/// <param name="FirstBreak">The first break, or null when <see cref="Status"/> is not <see cref="AuditChainStatus.Broken"/>.</param>
/// <param name="PreCutoffRows">
/// Rows in the month dated before the chain cutoff (ScadaBridge#139). They are out of scope by
/// design — the chain covers only rows written from its first enablement on — so they are
/// never chained and never a break. Zero when the chain has no cutoff.
/// </param>
/// <param name="ChainFromUtc">
/// The chain cutoff: the instant the chain was first enabled without backlog chaining. Null
/// when the chain covers the whole table (legacy / <c>ChainBacklog</c> enablement).
/// </param>
public sealed record AuditChainVerificationResult(
string Partition,
AuditChainStatus Status,
long RowsVerified,
long TombstonesApplied,
long? PurgedThroughSeq,
long? HeadSeq,
long UnchainedRows,
AuditChainBreak? FirstBreak,
long PreCutoffRows = 0,
DateTime? ChainFromUtc = null);
/// <summary>Outcome of one chaining pass over unchained AuditLog rows.</summary>
/// <param name="RowsChained">Rows linked into a chain by this pass.</param>
/// <param name="LockBusy">True when another chainer (the peer central node) held the chain lock, so this pass did nothing.</param>
public sealed record AuditChainBatchResult(int RowsChained, bool LockBusy);
@@ -169,17 +169,6 @@ public class AuditLogEntityTypeConfiguration : IEntityTypeConfiguration<AuditLog
stored: false) stored: false)
.ValueGeneratedOnAddOrUpdate(); .ValueGeneratedOnAddOrUpdate();
// ── Hash-chain link (ScadaBridge#41) ─────────────────────────────────
//
// Written only by the chaining job (column-level UPDATE grant to
// scadabridge_audit_chainer; the writer role keeps its table-wide DENY UPDATE).
// binary(32) on SQL Server; BLOB on the SQLite test provider.
builder.Property(e => e.ChainSeq);
builder.Property(e => e.RowHash)
.HasMaxLength(32)
.IsFixedLength();
// ── Keys + indexes ─────────────────────────────────────────────────── // ── Keys + indexes ───────────────────────────────────────────────────
// Clustered PK (OccurredAtUtc, EventId) — FlipAuditLogClusteredKey (ScadaBridge#111, // Clustered PK (OccurredAtUtc, EventId) — FlipAuditLogClusteredKey (ScadaBridge#111,
@@ -262,46 +251,5 @@ public class AuditLogEntityTypeConfiguration : IEntityTypeConfiguration<AuditLog
builder.HasIndex(e => new { e.Actor, e.OccurredAtUtc }) builder.HasIndex(e => new { e.Actor, e.OccurredAtUtc })
.IsDescending(false, true) .IsDescending(false, true)
.HasDatabaseName("IX_AuditLog_Actor_Occurred"); .HasDatabaseName("IX_AuditLog_Actor_Occurred");
// Hash-chain indexes (AddAuditLogHashChain migration, raw SQL ON ps_AuditLog_Month
// so they stay partition-aligned). Unchained: the chaining job's work queue —
// filtered to ChainSeq IS NULL, so it shrinks to the rows written since the last
// tick. ChainSeq: verification streams one month's chain in sequence order.
builder.HasIndex(e => new { e.OccurredAtUtc, e.EventId })
.HasFilter("[ChainSeq] IS NULL")
.HasDatabaseName("IX_AuditLog_Unchained");
builder.HasIndex(e => e.ChainSeq)
.HasFilter("[ChainSeq] IS NOT NULL")
.HasDatabaseName("IX_AuditLog_ChainSeq");
}
}
/// <summary>Maps <see cref="AuditLogChainHead"/> to <c>dbo.AuditLogChainHead</c> (ScadaBridge#41).</summary>
public class AuditLogChainHeadEntityTypeConfiguration : IEntityTypeConfiguration<AuditLogChainHead>
{
/// <summary>Applies the EF Core type configuration for <see cref="AuditLogChainHead"/>.</summary>
/// <param name="builder">The entity type builder to configure.</param>
public void Configure(EntityTypeBuilder<AuditLogChainHead> builder)
{
builder.ToTable("AuditLogChainHead");
builder.HasKey(e => e.ChainMonth);
builder.Property(e => e.ChainMonth).HasColumnType("date");
builder.Property(e => e.LastHash).HasMaxLength(32).IsFixedLength().IsRequired();
builder.Property(e => e.PurgedThroughHash).HasMaxLength(32).IsFixedLength();
}
}
/// <summary>Maps <see cref="AuditLogChainTombstone"/> to <c>dbo.AuditLogChainTombstone</c> (ScadaBridge#41).</summary>
public class AuditLogChainTombstoneEntityTypeConfiguration : IEntityTypeConfiguration<AuditLogChainTombstone>
{
/// <summary>Applies the EF Core type configuration for <see cref="AuditLogChainTombstone"/>.</summary>
/// <param name="builder">The entity type builder to configure.</param>
public void Configure(EntityTypeBuilder<AuditLogChainTombstone> builder)
{
builder.ToTable("AuditLogChainTombstone");
builder.HasKey(e => new { e.ChainMonth, e.ChainSeq });
builder.Property(e => e.ChainMonth).HasColumnType("date");
builder.Property(e => e.RowHash).HasMaxLength(32).IsFixedLength().IsRequired();
} }
} }
@@ -1,61 +0,0 @@
namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Entities;
/// <summary>
/// One row per chain partition (UTC calendar month) of the AuditLog hash chain
/// (ScadaBridge#41): where the chain currently ends, plus the checkpoint anchor a
/// monthly partition purge leaves behind.
/// </summary>
/// <remarks>
/// The head is what lets verification detect <b>tail truncation</b> — deleting the last
/// rows of a month leaves a chain that is internally consistent but shorter than the
/// head says. It is written by the chaining job (<see cref="LastSeq"/>/<see cref="LastHash"/>)
/// and by the partition-switch purge (<see cref="PurgedThroughSeq"/>/<see cref="PurgedThroughHash"/>).
/// </remarks>
public sealed class AuditLogChainHead
{
/// <summary>First day of the chain's month (UTC). Primary key.</summary>
public DateTime ChainMonth { get; set; }
/// <summary>Sequence number of the last row linked into the chain.</summary>
public long LastSeq { get; set; }
/// <summary>RowHash of the last row linked into the chain (32 bytes).</summary>
public byte[] LastHash { get; set; } = [];
/// <summary>
/// Checkpoint anchor: the last sequence number removed by a monthly partition-switch
/// purge. Verification resumes at <c>PurgedThroughSeq + 1</c> with
/// <see cref="PurgedThroughHash"/> as the previous link. Null when never purged.
/// </summary>
public long? PurgedThroughSeq { get; set; }
/// <summary>RowHash at <see cref="PurgedThroughSeq"/>; null when never purged.</summary>
public byte[]? PurgedThroughHash { get; set; }
/// <summary>UTC time the head last moved.</summary>
public DateTime UpdatedAtUtc { get; set; }
}
/// <summary>
/// The link a sanctioned per-channel retention DELETE removed from the middle of a chain
/// (ScadaBridge#41). Written in the SAME statement batch as the DELETE (via
/// <c>OUTPUT … INTO</c>) so the purge can never remove a chained row without leaving its
/// hash behind; verification bridges the gap with it.
/// </summary>
public sealed class AuditLogChainTombstone
{
/// <summary>First day of the chain's month (UTC). Part of the primary key.</summary>
public DateTime ChainMonth { get; set; }
/// <summary>Sequence number of the purged row. Part of the primary key.</summary>
public long ChainSeq { get; set; }
/// <summary>RowHash of the purged row (32 bytes).</summary>
public byte[] RowHash { get; set; } = [];
/// <summary>The purged row's EventId, kept for the operator's benefit.</summary>
public Guid EventId { get; set; }
/// <summary>UTC time of the purge.</summary>
public DateTime PurgedAtUtc { get; set; }
}
@@ -138,19 +138,4 @@ public sealed record AuditLogRow
: null; : null;
} }
private readonly DateTime? _ingestedAtUtc; private readonly DateTime? _ingestedAtUtc;
// ── Hash-chain link (audit roadmap T1, ScadaBridge#41) ────────────────────
/// <summary>
/// Position of this row in its month's hash chain (1-based, gap-free per UTC calendar
/// month of <see cref="OccurredAtUtc"/>); null until the chaining job reaches the row.
/// Written ONLY by the chaining job — never by the ingest/writer path.
/// </summary>
public long? ChainSeq { get; init; }
/// <summary>
/// <c>SHA-256(prev.RowHash || canonical(row))</c> — 32 bytes; null until chained. See
/// <c>AuditChainHasher</c> for the canonical serialisation.
/// </summary>
public byte[]? RowHash { get; init; }
} }
@@ -1,3 +1,5 @@
using System.Data;
using System.Data.Common;
using System.Globalization; using System.Globalization;
using System.Runtime.CompilerServices; using System.Runtime.CompilerServices;
using System.Security.Cryptography; using System.Security.Cryptography;
@@ -7,50 +9,58 @@ using Parquet.Schema;
namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance; namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance;
/// <summary> /// <summary>
/// One per-channel purge tombstone carried in an archive (ScadaBridge#41/#42): the link a /// One archived <c>dbo.AuditLog</c> row: the ten stored (writable) columns. The persisted
/// sanctioned per-channel retention DELETE removed from the middle of a month's chain. /// computed columns (Kind, Status, SourceSiteId, …) are derived from <c>DetailsJson</c> and
/// are not carried.
/// </summary> /// </summary>
/// <param name="ChainMonth">The chain partition's first instant (UTC).</param> /// <param name="EventId">The row's EventId.</param>
/// <param name="ChainSeq">The purged row's sequence number.</param> /// <param name="OccurredAtUtc">When the event occurred (UTC, <c>datetime2(7)</c> precision).</param>
/// <param name="RowHash">The purged row's 32-byte hash.</param> /// <param name="Actor">Actor, or null.</param>
/// <param name="EventId">The purged row's EventId.</param> /// <param name="Action">Action.</param>
/// <param name="PurgedAtUtc">When the per-channel purge removed it.</param> /// <param name="Outcome">Outcome.</param>
public sealed record AuditArchiveTombstone( /// <param name="Category">Channel (the canonical <c>Category</c> column).</param>
DateTime ChainMonth, /// <param name="Target">Target, or null.</param>
long ChainSeq, /// <param name="SourceNode">Node of origin, or null.</param>
byte[] RowHash, /// <param name="CorrelationId">Correlation id, or null.</param>
/// <param name="DetailsJson">Details JSON, or null.</param>
public sealed record AuditArchiveRow(
Guid EventId, Guid EventId,
DateTime PurgedAtUtc); DateTime OccurredAtUtc,
string? Actor,
string Action,
string Outcome,
string Category,
string? Target,
string? SourceNode,
Guid? CorrelationId,
string? DetailsJson);
/// <summary> /// <summary>
/// The Parquet layout of an AuditLog archive (audit roadmap T2, ScadaBridge#42), format v1. /// The Parquet layout of an AuditLog archive (audit roadmap T2, ScadaBridge#42), format v2.
/// </summary> /// </summary>
/// <remarks> /// <remarks>
/// <para> /// <para>
/// <b>Data file</b> — one row per archived <c>dbo.AuditLog</c> row, the ten stored (writable) /// <b>Data file</b> — one row per archived <c>dbo.AuditLog</c> row, the ten stored (writable)
/// columns plus the two hash-chain columns, so a row can be re-hashed with /// columns: <c>EventId</c> (string, <c>D</c> format), <c>OccurredAtUtc</c> (timestamp, UTC,
/// <see cref="AuditChainHasher"/> exactly as the database chained it: /// microseconds — for analytics), <c>OccurredAtUtcTicks</c> (int64 — the exact
/// <c>EventId</c> (string, <c>D</c> format), <c>OccurredAtUtc</c> (timestamp, UTC, microseconds — /// <c>datetime2(7)</c> value), <c>Actor</c>, <c>Action</c>, <c>Outcome</c>, <c>Category</c>,
/// for analytics), <c>OccurredAtUtcTicks</c> (int64 — the exact <c>datetime2(7)</c> value the hash /// <c>Target</c>, <c>SourceNode</c>, <c>CorrelationId</c>, <c>DetailsJson</c> (strings).
/// covers), <c>Actor</c>, <c>Action</c>, <c>Outcome</c>, <c>Category</c>, <c>Target</c>,
/// <c>SourceNode</c>, <c>CorrelationId</c>, <c>DetailsJson</c> (strings), <c>ChainSeq</c> (int64,
/// null when unchained) and <c>RowHash</c> (binary, null when unchained). The persisted computed
/// columns (Kind, Status, SourceSiteId, …) are not stored: they are derived from
/// <c>DetailsJson</c>, which the hash covers.
/// </para> /// </para>
/// <para> /// <para>
/// <b>Tombstone file</b> — <c>ChainMonth</c> (<c>YYYY-MM</c>), <c>ChainSeq</c>, <c>RowHash</c>, /// <b>Format v1</b> (written before 2026-11-15, when the audit hash chain was removed) also
/// <c>EventId</c>, <c>PurgedAtUtc</c>. /// carried <c>ChainSeq</c>/<c>RowHash</c> columns and a <c>.tombstones.parquet</c> sibling. The
/// reader reads a v1 data file by column name and ignores those columns; cleanup still deletes a
/// v1 archive's tombstone file with it.
/// </para> /// </para>
/// <para> /// <para>
/// Both are plain Parquet: DuckDB (<c>SELECT * FROM 'auditlog-….parquet'</c>), pandas/pyarrow /// Plain Parquet: DuckDB (<c>SELECT * FROM 'auditlog-….parquet'</c>), pandas/pyarrow and Spark
/// and Spark read them without any ScadaBridge code. /// read it without any ScadaBridge code.
/// </para> /// </para>
/// </remarks> /// </remarks>
public static class AuditArchiveParquet public static class AuditArchiveParquet
{ {
/// <summary>The archive layout version written into the file metadata and the manifest.</summary> /// <summary>The archive layout version written into the file metadata and the manifest.</summary>
public const int FormatVersion = 1; public const int FormatVersion = 2;
/// <summary>Key-value metadata key carrying <see cref="FormatVersion"/>.</summary> /// <summary>Key-value metadata key carrying <see cref="FormatVersion"/>.</summary>
public const string FormatVersionKey = "scadabridge.auditlog.archive.formatVersion"; public const string FormatVersionKey = "scadabridge.auditlog.archive.formatVersion";
@@ -70,24 +80,60 @@ public static class AuditArchiveParquet
private static readonly DataField<string> SourceNodeField = new("SourceNode", true); private static readonly DataField<string> SourceNodeField = new("SourceNode", true);
private static readonly DataField<string> CorrelationIdField = new("CorrelationId", true); private static readonly DataField<string> CorrelationIdField = new("CorrelationId", true);
private static readonly DataField<string> DetailsJsonField = new("DetailsJson", true); private static readonly DataField<string> DetailsJsonField = new("DetailsJson", true);
private static readonly DataField<long> ChainSeqField = new("ChainSeq", true);
private static readonly DataField<byte[]> RowHashField = new("RowHash", true);
private static readonly DataField<string> TombstoneMonthField = new("ChainMonth", false); /// <summary>Suffix of the per-channel-purge tombstone file a format-v1 archive carried.</summary>
private static readonly DataField<long> TombstoneSeqField = new("ChainSeq", false); public const string LegacyTombstoneSuffix = ".tombstones.parquet";
private static readonly DataField<byte[]> TombstoneHashField = new("RowHash", false);
private static readonly DataField<string> TombstoneEventIdField = new("EventId", false); /// <summary>The ten stored <c>dbo.AuditLog</c> columns, in table order (see <see cref="ReadRow"/>).</summary>
private static readonly DateTimeDataField TombstonePurgedAtField = internal const string RowColumns =
new("PurgedAtUtc", DateTimeFormat.Timestamp, isAdjustedToUTC: true, unit: DateTimeTimeUnit.Micros, isNullable: false); "EventId, OccurredAtUtc, Actor, Action, Outcome, Category, Target, SourceNode, CorrelationId, DetailsJson";
/// <summary>The data-file schema.</summary> /// <summary>The data-file schema.</summary>
public static ParquetSchema DataSchema { get; } = new( public static ParquetSchema DataSchema { get; } = new(
EventIdField, OccurredAtField, OccurredAtTicksField, ActorField, ActionField, OutcomeField, CategoryField, EventIdField, OccurredAtField, OccurredAtTicksField, ActorField, ActionField, OutcomeField, CategoryField,
TargetField, SourceNodeField, CorrelationIdField, DetailsJsonField, ChainSeqField, RowHashField); TargetField, SourceNodeField, CorrelationIdField, DetailsJsonField);
/// <summary>The tombstone-file schema.</summary> /// <summary>The first instant (UTC) of the calendar month holding <paramref name="occurredAtUtc"/>.</summary>
public static ParquetSchema TombstoneSchema { get; } = new( /// <param name="occurredAtUtc">A UTC instant.</param>
TombstoneMonthField, TombstoneSeqField, TombstoneHashField, TombstoneEventIdField, TombstonePurgedAtField); /// <returns>Day 1, midnight UTC.</returns>
public static DateTime MonthOf(DateTime occurredAtUtc)
=> new(occurredAtUtc.Year, occurredAtUtc.Month, 1, 0, 0, 0, DateTimeKind.Utc);
/// <summary>Formats a month as <c>YYYY-MM</c>.</summary>
/// <param name="monthStartUtc">The month's first instant.</param>
/// <returns>The partition label.</returns>
public static string PartitionLabel(DateTime monthStartUtc)
=> monthStartUtc.ToString("yyyy-MM", CultureInfo.InvariantCulture);
/// <summary>Reads one row selected as <see cref="RowColumns"/>, strictly in ordinal order (SequentialAccess-safe).</summary>
/// <param name="reader">The reader, positioned on a row.</param>
/// <returns>The row.</returns>
internal static AuditArchiveRow ReadRow(DbDataReader reader) => new(
reader.GetGuid(0),
DateTime.SpecifyKind(reader.GetDateTime(1), DateTimeKind.Utc),
reader.IsDBNull(2) ? null : reader.GetString(2),
reader.GetString(3),
reader.GetString(4),
reader.GetString(5),
reader.IsDBNull(6) ? null : reader.GetString(6),
reader.IsDBNull(7) ? null : reader.GetString(7),
reader.IsDBNull(8) ? null : reader.GetGuid(8),
reader.IsDBNull(9) ? null : reader.GetString(9));
/// <summary>Opens <paramref name="conn"/> when it is not already open.</summary>
/// <param name="conn">The connection.</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>True when this call opened it (the caller closes it).</returns>
internal static async Task<bool> OpenAsync(DbConnection conn, CancellationToken ct)
{
if (conn.State == ConnectionState.Open)
{
return false;
}
await conn.OpenAsync(ct).ConfigureAwait(false);
return true;
}
/// <summary>Opens a buffered writer of archive data rows over <paramref name="output"/>.</summary> /// <summary>Opens a buffered writer of archive data rows over <paramref name="output"/>.</summary>
/// <param name="output">Destination stream (need not be seekable).</param> /// <param name="output">Destination stream (need not be seekable).</param>
@@ -102,24 +148,11 @@ public static class AuditArchiveParquet
return new DataWriter(writer, rowGroupSize); return new DataWriter(writer, rowGroupSize);
} }
/// <summary>Opens a buffered writer of tombstones over <paramref name="output"/>.</summary>
/// <param name="output">Destination stream (need not be seekable).</param>
/// <param name="partition">The archived partition (<c>YYYY-MM</c>), stamped into the file metadata.</param>
/// <param name="rowGroupSize">Rows per Parquet row group.</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>The writer; dispose it to flush the last row group and the footer.</returns>
public static async Task<TombstoneWriter> CreateTombstoneWriterAsync(Stream output, string partition, int rowGroupSize, CancellationToken ct = default)
{
var writer = await ParquetWriter.CreateAsync(TombstoneSchema, output, cancellationToken: ct).ConfigureAwait(false);
writer.CustomMetadata = Metadata(partition);
return new TombstoneWriter(writer, rowGroupSize);
}
/// <summary>Streams the rows of an archive data file in file order.</summary> /// <summary>Streams the rows of an archive data file in file order.</summary>
/// <param name="input">A readable, seekable stream over the data file.</param> /// <param name="input">A readable, seekable stream over the data file.</param>
/// <param name="ct">Cancellation token.</param> /// <param name="ct">Cancellation token.</param>
/// <returns>The rows, as the chain hasher sees them.</returns> /// <returns>The rows.</returns>
public static async IAsyncEnumerable<AuditChainRow> ReadRowsAsync(Stream input, [EnumeratorCancellation] CancellationToken ct = default) public static async IAsyncEnumerable<AuditArchiveRow> ReadRowsAsync(Stream input, [EnumeratorCancellation] CancellationToken ct = default)
{ {
await using var reader = await ParquetReader.CreateAsync(input, leaveStreamOpen: true, cancellationToken: ct).ConfigureAwait(false); await using var reader = await ParquetReader.CreateAsync(input, leaveStreamOpen: true, cancellationToken: ct).ConfigureAwait(false);
for (var g = 0; g < reader.RowGroupCount; g++) for (var g = 0; g < reader.RowGroupCount; g++)
@@ -137,14 +170,10 @@ public static class AuditArchiveParquet
var nodes = await Strings(group, SourceNodeField, n, ct).ConfigureAwait(false); var nodes = await Strings(group, SourceNodeField, n, ct).ConfigureAwait(false);
var correlations = await Strings(group, CorrelationIdField, n, ct).ConfigureAwait(false); var correlations = await Strings(group, CorrelationIdField, n, ct).ConfigureAwait(false);
var details = await Strings(group, DetailsJsonField, n, ct).ConfigureAwait(false); var details = await Strings(group, DetailsJsonField, n, ct).ConfigureAwait(false);
var seqs = new long?[n];
await group.ReadAsync<long>(ChainSeqField, seqs, cancellationToken: ct).ConfigureAwait(false);
var hashes = new byte[]?[n];
await group.ReadAsync(RowHashField, hashes!, cancellationToken: ct).ConfigureAwait(false);
for (var i = 0; i < n; i++) for (var i = 0; i < n; i++)
{ {
yield return new AuditChainRow( yield return new AuditArchiveRow(
Guid.Parse(eventIds[i]!), Guid.Parse(eventIds[i]!),
new DateTime(ticks[i], DateTimeKind.Utc), new DateTime(ticks[i], DateTimeKind.Utc),
actors[i], actors[i],
@@ -154,46 +183,12 @@ public static class AuditArchiveParquet
targets[i], targets[i],
nodes[i], nodes[i],
correlations[i] is { } c ? Guid.Parse(c) : null, correlations[i] is { } c ? Guid.Parse(c) : null,
details[i], details[i]);
seqs[i],
hashes[i]);
} }
} }
} }
/// <summary>Streams the tombstones of an archive tombstone file.</summary> /// <summary>Parses a <c>YYYY-MM</c> partition label to its first instant (UTC).</summary>
/// <param name="input">A readable, seekable stream over the tombstone file.</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>The tombstones.</returns>
public static async IAsyncEnumerable<AuditArchiveTombstone> ReadTombstonesAsync(Stream input, [EnumeratorCancellation] CancellationToken ct = default)
{
await using var reader = await ParquetReader.CreateAsync(input, leaveStreamOpen: true, cancellationToken: ct).ConfigureAwait(false);
for (var g = 0; g < reader.RowGroupCount; g++)
{
using var group = reader.OpenRowGroupReader(g);
var n = checked((int)group.RowCount);
var months = await Strings(group, TombstoneMonthField, n, ct).ConfigureAwait(false);
var seqs = new long[n];
await group.ReadAsync<long>(TombstoneSeqField, seqs, cancellationToken: ct).ConfigureAwait(false);
var hashes = new byte[]?[n];
await group.ReadAsync(TombstoneHashField, hashes!, cancellationToken: ct).ConfigureAwait(false);
var eventIds = await Strings(group, TombstoneEventIdField, n, ct).ConfigureAwait(false);
var purgedAt = new DateTime[n];
await group.ReadAsync<DateTime>(TombstonePurgedAtField, purgedAt, cancellationToken: ct).ConfigureAwait(false);
for (var i = 0; i < n; i++)
{
yield return new AuditArchiveTombstone(
ParseMonth(months[i]!),
seqs[i],
hashes[i]!,
Guid.Parse(eventIds[i]!),
DateTime.SpecifyKind(purgedAt[i], DateTimeKind.Utc));
}
}
}
/// <summary>Parses a <c>YYYY-MM</c> chain partition label to its first instant (UTC).</summary>
/// <param name="partition">The label.</param> /// <param name="partition">The label.</param>
/// <returns>Day 1, midnight UTC.</returns> /// <returns>Day 1, midnight UTC.</returns>
public static DateTime ParseMonth(string partition) public static DateTime ParseMonth(string partition)
@@ -220,14 +215,14 @@ public static class AuditArchiveParquet
{ {
private readonly ParquetWriter _writer; private readonly ParquetWriter _writer;
private readonly int _rowGroupSize; private readonly int _rowGroupSize;
private readonly List<AuditChainRow> _buffer; private readonly List<AuditArchiveRow> _buffer;
private bool _disposed; private bool _disposed;
internal DataWriter(ParquetWriter writer, int rowGroupSize) internal DataWriter(ParquetWriter writer, int rowGroupSize)
{ {
_writer = writer; _writer = writer;
_rowGroupSize = Math.Max(1, rowGroupSize); _rowGroupSize = Math.Max(1, rowGroupSize);
_buffer = new List<AuditChainRow>(Math.Min(_rowGroupSize, 65_536)); _buffer = new List<AuditArchiveRow>(Math.Min(_rowGroupSize, 65_536));
} }
/// <summary>Rows added so far.</summary> /// <summary>Rows added so far.</summary>
@@ -237,7 +232,7 @@ public static class AuditArchiveParquet
/// <param name="row">The row.</param> /// <param name="row">The row.</param>
/// <param name="ct">Cancellation token.</param> /// <param name="ct">Cancellation token.</param>
/// <returns>A task that completes when the row is buffered (or its row group written).</returns> /// <returns>A task that completes when the row is buffered (or its row group written).</returns>
public async Task AddAsync(AuditChainRow row, CancellationToken ct = default) public async Task AddAsync(AuditArchiveRow row, CancellationToken ct = default)
{ {
ArgumentNullException.ThrowIfNull(row); ArgumentNullException.ThrowIfNull(row);
_buffer.Add(row); _buffer.Add(row);
@@ -283,75 +278,6 @@ public static class AuditArchiveParquet
await group.WriteAsync(SourceNodeField, rows.Select(r => r.SourceNode).ToArray()!).ConfigureAwait(false); await group.WriteAsync(SourceNodeField, rows.Select(r => r.SourceNode).ToArray()!).ConfigureAwait(false);
await group.WriteAsync(CorrelationIdField, rows.Select(r => r.CorrelationId?.ToString("D")).ToArray()!).ConfigureAwait(false); await group.WriteAsync(CorrelationIdField, rows.Select(r => r.CorrelationId?.ToString("D")).ToArray()!).ConfigureAwait(false);
await group.WriteAsync(DetailsJsonField, rows.Select(r => r.DetailsJson).ToArray()!).ConfigureAwait(false); await group.WriteAsync(DetailsJsonField, rows.Select(r => r.DetailsJson).ToArray()!).ConfigureAwait(false);
await group.WriteAsync<long>(ChainSeqField, rows.Select(r => r.ChainSeq).ToArray(), cancellationToken: ct).ConfigureAwait(false);
await group.WriteAsync(RowHashField, rows.Select(r => r.RowHash).ToArray()!).ConfigureAwait(false);
}
_buffer.Clear();
}
}
/// <summary>Buffers tombstones and writes them a row group at a time.</summary>
public sealed class TombstoneWriter : IAsyncDisposable
{
private readonly ParquetWriter _writer;
private readonly int _rowGroupSize;
private readonly List<AuditArchiveTombstone> _buffer = [];
private bool _disposed;
internal TombstoneWriter(ParquetWriter writer, int rowGroupSize)
{
_writer = writer;
_rowGroupSize = Math.Max(1, rowGroupSize);
}
/// <summary>Tombstones added so far.</summary>
public long Count { get; private set; }
/// <summary>Adds one tombstone, flushing a row group when the buffer is full.</summary>
/// <param name="tombstone">The tombstone.</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>A task that completes when the tombstone is buffered (or its row group written).</returns>
public async Task AddAsync(AuditArchiveTombstone tombstone, CancellationToken ct = default)
{
ArgumentNullException.ThrowIfNull(tombstone);
_buffer.Add(tombstone);
Count++;
if (_buffer.Count >= _rowGroupSize)
{
await FlushAsync(ct).ConfigureAwait(false);
}
}
/// <summary>Writes any buffered tombstones as a row group, then the file footer.</summary>
/// <returns>A task that completes when the file is finished.</returns>
public async ValueTask DisposeAsync()
{
if (_disposed)
{
return;
}
_disposed = true;
await FlushAsync(CancellationToken.None).ConfigureAwait(false);
await _writer.DisposeAsync().ConfigureAwait(false);
}
private async Task FlushAsync(CancellationToken ct)
{
if (_buffer.Count == 0)
{
return;
}
var rows = _buffer;
using (var group = _writer.CreateRowGroup())
{
await group.WriteAsync(TombstoneMonthField, rows.Select(t => AuditChainHasher.PartitionLabel(t.ChainMonth)).ToArray()).ConfigureAwait(false);
await group.WriteAsync<long>(TombstoneSeqField, rows.Select(t => t.ChainSeq).ToArray(), cancellationToken: ct).ConfigureAwait(false);
await group.WriteAsync(TombstoneHashField, rows.Select(t => t.RowHash).ToArray()).ConfigureAwait(false);
await group.WriteAsync(TombstoneEventIdField, rows.Select(t => t.EventId.ToString("D")).ToArray()).ConfigureAwait(false);
await group.WriteAsync<DateTime>(TombstonePurgedAtField, rows.Select(t => t.PurgedAtUtc).ToArray(), cancellationToken: ct).ConfigureAwait(false);
} }
_buffer.Clear(); _buffer.Clear();
@@ -1,184 +0,0 @@
using System.Buffers.Binary;
using System.Globalization;
using System.Security.Cryptography;
using System.Text;
namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance;
/// <summary>
/// The stored column values of one <c>dbo.AuditLog</c> row as the hash chain sees them
/// (ScadaBridge#41). Strings are the raw column values exactly as SQL Server returns them
/// (e.g. <see cref="Outcome"/> / <see cref="Category"/> are the stored enum NAMES), so
/// the hash never depends on how a later build happens to map them to CLR enums.
/// </summary>
/// <param name="EventId">The row's EventId.</param>
/// <param name="OccurredAtUtc">The row's OccurredAtUtc (datetime2(7) — full tick precision).</param>
/// <param name="Actor">Actor column.</param>
/// <param name="Action">Action column.</param>
/// <param name="Outcome">Outcome column.</param>
/// <param name="Category">Category (channel) column.</param>
/// <param name="Target">Target column.</param>
/// <param name="SourceNode">SourceNode column.</param>
/// <param name="CorrelationId">CorrelationId column.</param>
/// <param name="DetailsJson">DetailsJson column.</param>
/// <param name="ChainSeq">Stored ChainSeq, or null when unchained.</param>
/// <param name="RowHash">Stored RowHash, or null when unchained.</param>
public sealed record AuditChainRow(
Guid EventId,
DateTime OccurredAtUtc,
string? Actor,
string Action,
string Outcome,
string Category,
string? Target,
string? SourceNode,
Guid? CorrelationId,
string? DetailsJson,
long? ChainSeq = null,
byte[]? RowHash = null);
/// <summary>
/// Canonical serialisation + SHA-256 link computation for the AuditLog hash chain
/// (alog.md §11.4, ScadaBridge#41): <c>RowHash = SHA-256(prev.RowHash || canonical(row))</c>.
/// </summary>
/// <remarks>
/// <para>
/// <b>Canonical form (v1), all integers big-endian:</b> the ASCII domain tag
/// <c>"ScadaBridge.AuditLog.Chain.v1"</c>; the chain partition (<c>YYYY-MM</c>); the
/// 64-bit <c>ChainSeq</c>; then the ten writable columns in table order — EventId (as its
/// lowercase <c>D</c>-format string), OccurredAtUtc (64-bit ticks), Actor, Action, Outcome,
/// Category, Target, SourceNode, CorrelationId (<c>D</c>-format string), DetailsJson.
/// Every string-valued field is encoded as one presence byte (<c>0</c> = SQL NULL,
/// <c>1</c> = present) followed, when present, by a 32-bit byte length and its UTF-8 bytes —
/// so NULL and the empty string hash differently, and no field boundary is ambiguous.
/// </para>
/// <para>
/// The partition and sequence number are inside the hashed bytes so a row moved to a
/// different position, or into another month's chain, fails verification on its own,
/// independently of the previous-hash link. The computed columns (Kind, Status, …) are
/// derived from DetailsJson, so hashing DetailsJson covers them.
/// </para>
/// <para>
/// Changing anything here invalidates every chain already written. A new form needs a new
/// domain tag and a migration story; never edit v1 in place.
/// </para>
/// </remarks>
public static class AuditChainHasher
{
/// <summary>Length of a link hash in bytes.</summary>
public const int HashLength = 32;
private static readonly byte[] DomainTag = Encoding.ASCII.GetBytes("ScadaBridge.AuditLog.Chain.v1");
/// <summary>The previous-hash value the first row of every chain links to (32 zero bytes).</summary>
public static ReadOnlySpan<byte> GenesisHash => new byte[HashLength];
/// <summary>Returns the first instant (UTC) of the month containing <paramref name="occurredAtUtc"/>.</summary>
/// <param name="occurredAtUtc">A UTC timestamp.</param>
/// <returns>Day 1, 00:00:00 UTC of that month.</returns>
public static DateTime MonthOf(DateTime occurredAtUtc)
=> new(occurredAtUtc.Year, occurredAtUtc.Month, 1, 0, 0, 0, DateTimeKind.Utc);
/// <summary>Formats a chain partition as <c>YYYY-MM</c>.</summary>
/// <param name="monthStartUtc">The month's first instant.</param>
/// <returns>The partition label.</returns>
public static string PartitionLabel(DateTime monthStartUtc)
=> monthStartUtc.ToString("yyyy-MM", CultureInfo.InvariantCulture);
/// <summary>Computes the link hash for <paramref name="row"/> at <paramref name="chainSeq"/>.</summary>
/// <param name="previousHash">The RowHash of the row at <c>chainSeq - 1</c>, or <see cref="GenesisHash"/>.</param>
/// <param name="monthStartUtc">The chain partition the row belongs to.</param>
/// <param name="chainSeq">The row's position in the chain.</param>
/// <param name="row">The row's stored column values.</param>
/// <returns>The 32-byte SHA-256 link hash.</returns>
public static byte[] ComputeRowHash(ReadOnlySpan<byte> previousHash, DateTime monthStartUtc, long chainSeq, AuditChainRow row)
{
ArgumentNullException.ThrowIfNull(row);
if (previousHash.Length != HashLength)
{
throw new ArgumentException($"Previous hash must be {HashLength} bytes.", nameof(previousHash));
}
using var hash = IncrementalHash.CreateHash(HashAlgorithmName.SHA256);
hash.AppendData(previousHash);
hash.AppendData(Canonicalize(monthStartUtc, chainSeq, row));
return hash.GetHashAndReset();
}
/// <summary>Builds the canonical v1 byte form of <paramref name="row"/> at its chain position.</summary>
/// <param name="monthStartUtc">The chain partition.</param>
/// <param name="chainSeq">The row's position in the chain.</param>
/// <param name="row">The row's stored column values.</param>
/// <returns>The canonical bytes (excluding the previous hash).</returns>
public static byte[] Canonicalize(DateTime monthStartUtc, long chainSeq, AuditChainRow row)
{
ArgumentNullException.ThrowIfNull(row);
using var buffer = new MemoryStream(256 + (row.DetailsJson?.Length ?? 0) * 3);
buffer.Write(DomainTag);
WriteString(buffer, PartitionLabel(monthStartUtc));
WriteInt64(buffer, chainSeq);
WriteString(buffer, row.EventId.ToString("D"));
WriteInt64(buffer, row.OccurredAtUtc.Ticks);
WriteString(buffer, row.Actor);
WriteString(buffer, row.Action);
WriteString(buffer, row.Outcome);
WriteString(buffer, row.Category);
WriteString(buffer, row.Target);
WriteString(buffer, row.SourceNode);
WriteString(buffer, row.CorrelationId?.ToString("D"));
WriteString(buffer, row.DetailsJson);
return buffer.ToArray();
}
/// <summary>
/// The <c>ChainSeq</c> of the chain-start (cutoff) anchor in <c>dbo.AuditLogChainTombstone</c>
/// (ScadaBridge#139). Real links start at 1, so slot 0 is "the link before the first row":
/// the anchor's <c>RowHash</c> is the genesis hash of the cutoff month's chain.
/// </summary>
public const long CutoffAnchorSeq = 0;
/// <summary>The fixed <c>EventId</c> the chain-start anchor row carries, so it is recognisable by eye.</summary>
public static readonly Guid CutoffAnchorEventId = new("5cadab1d-c4a1-4c0f-a000-000000000139");
private static readonly byte[] CutoffDomainTag = Encoding.ASCII.GetBytes("ScadaBridge.AuditLog.ChainCutoff.v1");
/// <summary>
/// Computes the chain-start anchor hash for a cutoff instant (ScadaBridge#139):
/// <c>SHA-256("ScadaBridge.AuditLog.ChainCutoff.v1" || YYYY-MM || ticks)</c>, big-endian like
/// the row form. It is both the anchor row's stored <c>RowHash</c> and the previous-hash the
/// first row of the cutoff month links to, so moving the cutoff breaks that month's chain.
/// </summary>
/// <param name="chainFromUtc">The cutoff: rows with an earlier <c>OccurredAtUtc</c> are never chained.</param>
/// <returns>The 32-byte anchor hash.</returns>
public static byte[] ComputeCutoffAnchorHash(DateTime chainFromUtc)
{
using var buffer = new MemoryStream(64);
buffer.Write(CutoffDomainTag);
WriteString(buffer, PartitionLabel(MonthOf(chainFromUtc)));
WriteInt64(buffer, chainFromUtc.Ticks);
return SHA256.HashData(buffer.ToArray());
}
private static void WriteInt64(Stream stream, long value)
{
Span<byte> bytes = stackalloc byte[8];
BinaryPrimitives.WriteInt64BigEndian(bytes, value);
stream.Write(bytes);
}
private static void WriteString(Stream stream, string? value)
{
if (value is null)
{
stream.WriteByte(0);
return;
}
stream.WriteByte(1);
var bytes = Encoding.UTF8.GetBytes(value);
Span<byte> length = stackalloc byte[4];
BinaryPrimitives.WriteInt32BigEndian(length, bytes.Length);
stream.Write(length);
stream.Write(bytes);
}
}
@@ -1,139 +0,0 @@
using System.Globalization;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance;
/// <summary>
/// Pure comparison of one exported chain head (ScadaBridge#107 item 1) with the database's
/// current state for that month. Kept free of I/O so every verdict is unit-testable; the
/// database side supplies the head snapshot and, when needed, the link stored at the
/// exported sequence number.
/// </summary>
public static class AuditChainHeadComparer
{
/// <summary>What the database stores at one chain sequence number.</summary>
/// <param name="RowHash">The <c>RowHash</c> of the live row carrying the sequence, or null.</param>
/// <param name="TombstoneHash">The <c>RowHash</c> of a per-channel purge tombstone carrying it, or null.</param>
public readonly record struct StoredLink(byte[]? RowHash, byte[]? TombstoneHash);
/// <summary>Compares one exported head with the database.</summary>
/// <param name="record">The exported head.</param>
/// <param name="head">The database head for the record's month, or null when there is none.</param>
/// <param name="linkAt">Reads the stored link at a sequence number (only called when the chain has grown).</param>
/// <returns>The verdict.</returns>
public static async Task<AuditChainHeadCheck> CompareAsync(
AuditChainHeadRecord record, AuditChainHeadSnapshot? head, Func<long, Task<StoredLink>> linkAt)
{
ArgumentNullException.ThrowIfNull(record);
ArgumentNullException.ThrowIfNull(linkAt);
AuditChainHeadCheck Result(AuditChainHeadStatus status, string detail) =>
new(record.Month, record.LastSeq, record.ExportedAtUtc, record.Node, status, head?.LastSeq, detail);
if (!TryParseHex(record.LastHash, out var exported))
{
return Result(AuditChainHeadStatus.Mismatch, $"Exported hash '{record.LastHash}' is not 32 bytes of hex.");
}
if (head is null)
{
return Result(AuditChainHeadStatus.MissingHead,
$"{record.Month} has no chain head in the database, but {record.LastSeq} links were exported for it.");
}
if (head.LastSeq < record.LastSeq)
{
return Result(AuditChainHeadStatus.Regressed,
$"Database head is at sequence {head.LastSeq}, below the exported {record.LastSeq}: links were removed and the head rolled back.");
}
if (head.LastSeq == record.LastSeq)
{
if (!exported.AsSpan().SequenceEqual(head.LastHash))
{
return Result(AuditChainHeadStatus.Mismatch,
$"Database head hash at sequence {head.LastSeq} is {ToHex(head.LastHash)}, exported {record.LastHash}: the chain was rewritten.");
}
// No link was added since the export. Unless a partition purge set (or moved) the
// anchor since, rows + tombstones are invariant: the per-channel purge turns a row
// into a tombstone, nothing else may remove a chained row.
if (head.PurgedThroughSeq == record.PurgedThroughSeq
&& head.ChainedRows + head.Tombstones != record.ChainedRows + record.Tombstones)
{
return Result(AuditChainHeadStatus.CountMismatch,
$"Chained rows + tombstones are {head.ChainedRows} + {head.Tombstones} in the database, {record.ChainedRows} + {record.Tombstones} exported.");
}
return Result(AuditChainHeadStatus.Matches, "Database head equals the exported head.");
}
// The chain has grown: the link at the exported sequence must still carry the exported hash.
if (head.PurgedThroughSeq is { } anchor && record.LastSeq <= anchor)
{
if (record.LastSeq < anchor)
{
return Result(AuditChainHeadStatus.Purged,
$"Sequence {record.LastSeq} was removed by a partition purge (anchor at {anchor}); verify the month's archive.");
}
return head.PurgedThroughHash is { } anchorHash && exported.AsSpan().SequenceEqual(anchorHash)
? Result(AuditChainHeadStatus.Extended, $"Exported head is the partition-purge anchor at {anchor}.")
: Result(AuditChainHeadStatus.Mismatch, $"Partition-purge anchor at {anchor} does not carry the exported hash.");
}
var link = await linkAt(record.LastSeq).ConfigureAwait(false);
var stored = link.RowHash ?? link.TombstoneHash;
if (stored is null)
{
return Result(AuditChainHeadStatus.MissingLink,
$"No row, tombstone or anchor carries sequence {record.LastSeq}: a chained row was deleted outside the purge paths.");
}
return exported.AsSpan().SequenceEqual(stored)
? Result(AuditChainHeadStatus.Extended,
$"Chain grew to {head.LastSeq}; the {(link.RowHash is null ? "tombstone" : "row")} at {record.LastSeq} still carries the exported hash.")
: Result(AuditChainHeadStatus.Mismatch,
$"The {(link.RowHash is null ? "tombstone" : "row")} at sequence {record.LastSeq} carries {ToHex(stored)}, exported {record.LastHash}: the chain was rewritten.");
}
/// <summary>Lowercase hex of a hash.</summary>
/// <param name="bytes">The bytes.</param>
/// <returns>Hex string.</returns>
public static string ToHex(byte[] bytes) => Convert.ToHexString(bytes).ToLowerInvariant();
/// <summary>Parses a <c>YYYY-MM</c> month into its first instant (UTC).</summary>
/// <param name="month">The month text.</param>
/// <param name="monthStart">The parsed month.</param>
/// <returns>True when well-formed.</returns>
public static bool TryParseMonth(string? month, out DateTime monthStart)
{
if (DateTime.TryParseExact(month, "yyyy-MM", CultureInfo.InvariantCulture, DateTimeStyles.None, out var parsed))
{
monthStart = new DateTime(parsed.Year, parsed.Month, 1, 0, 0, 0, DateTimeKind.Utc);
return true;
}
monthStart = default;
return false;
}
private static bool TryParseHex(string? hex, out byte[] bytes)
{
bytes = [];
if (hex is null || hex.Length != AuditChainHasher.HashLength * 2)
{
return false;
}
try
{
bytes = Convert.FromHexString(hex);
return true;
}
catch (FormatException)
{
return false;
}
}
}
@@ -1,252 +0,0 @@
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance;
/// <summary>A month's chain head as verification sees it (ScadaBridge#41).</summary>
/// <param name="LastSeq">Last sequence number linked.</param>
/// <param name="LastHash">RowHash at <paramref name="LastSeq"/>.</param>
/// <param name="PurgedThroughSeq">Checkpoint anchor left by a partition-switch purge, or null.</param>
/// <param name="PurgedThroughHash">RowHash at <paramref name="PurgedThroughSeq"/>, or null.</param>
public sealed record AuditChainHeadState(
long LastSeq,
byte[] LastHash,
long? PurgedThroughSeq,
byte[]? PurgedThroughHash);
/// <summary>
/// Streaming verifier for one month's AuditLog hash chain (ScadaBridge#41). Feed it the
/// month's chained rows in <c>ChainSeq</c> order via <see cref="Accept"/>, then call
/// <see cref="Complete"/>. Storage-agnostic so the detection rules are unit-testable
/// without SQL Server.
/// </summary>
/// <remarks>
/// <para>
/// Verification starts at the checkpoint anchor (<c>PurgedThroughSeq + 1</c>, previous
/// link <c>PurgedThroughHash</c>) when a partition purge left one, otherwise at sequence 1
/// with the genesis hash. Each row's hash is recomputed from the previous link and its own
/// stored columns; a sequence number with no row is bridged only by a purge tombstone. At
/// the end the chain must land exactly on the head's <c>(LastSeq, LastHash)</c>, which is
/// what catches deletion of the newest rows.
/// </para>
/// <para>
/// Detection, by tampering act: an <b>edited</b> row → <see cref="AuditChainBreakKind.HashMismatch"/>
/// at that row; a <b>deleted</b> row → <see cref="AuditChainBreakKind.MissingRow"/> at its
/// sequence number (or <see cref="AuditChainBreakKind.HeadMismatch"/> if it was the tail);
/// <b>reordered</b> rows (ChainSeq values swapped) → <see cref="AuditChainBreakKind.HashMismatch"/>
/// at the first moved row, because the sequence number is inside the hashed bytes.
/// </para>
/// <para>
/// <b>Chain start (cutoff, ScadaBridge#139).</b> When the chain was enabled with no backlog,
/// a link-0 anchor in the tombstones of the cutoff month is that month's genesis hash (instead
/// of 32 zero bytes), and no row before the cutoff is ever chained. So a chained row whose
/// <c>OccurredAtUtc</c> is before the cutoff is a break (<see cref="AuditChainBreakKind.ChainedBeforeCutoff"/>):
/// either the row's timestamp was moved back to hide it among the unprotected rows, or the
/// cutoff was moved forward. An anchor that does not hash to its own cutoff is reported as
/// <see cref="AuditChainBreakKind.CutoffAnchorInvalid"/> by the caller.
/// </para>
/// </remarks>
public sealed class AuditChainVerifier
{
private readonly DateTime _monthStartUtc;
private readonly string _partition;
private readonly AuditChainHeadState? _head;
private readonly IReadOnlyDictionary<long, byte[]> _tombstones;
private readonly long _startAfter;
private readonly DateTime? _chainFromUtc;
private byte[] _previous;
private long _expected;
private long _verified;
private long _tombstonesApplied;
private AuditChainBreak? _break;
/// <summary>Initializes a verifier for one month.</summary>
/// <param name="monthStartUtc">The chain partition (first instant of the month, UTC).</param>
/// <param name="head">The month's chain head, or null when none exists.</param>
/// <param name="tombstones">
/// Purge tombstones for the month, keyed by ChainSeq; a key of
/// <see cref="AuditChainHasher.CutoffAnchorSeq"/> is the chain-start anchor (the month's genesis).
/// </param>
/// <param name="chainFromUtc">The chain cutoff, or null when the whole table is in scope (legacy / backlog chaining).</param>
/// <param name="anchorProblem">When non-null, the chain-start anchor is invalid; verification fails with this detail.</param>
public AuditChainVerifier(
DateTime monthStartUtc,
AuditChainHeadState? head,
IReadOnlyDictionary<long, byte[]> tombstones,
DateTime? chainFromUtc = null,
string? anchorProblem = null)
{
_monthStartUtc = monthStartUtc;
_partition = AuditChainHasher.PartitionLabel(monthStartUtc);
_head = head;
_tombstones = tombstones ?? throw new ArgumentNullException(nameof(tombstones));
if (head?.PurgedThroughSeq is { } purgedThrough && head.PurgedThroughHash is { } anchor)
{
_startAfter = purgedThrough;
_previous = anchor;
}
else
{
_startAfter = 0;
_previous = _tombstones.TryGetValue(AuditChainHasher.CutoffAnchorSeq, out var cutoffAnchor)
? cutoffAnchor
: AuditChainHasher.GenesisHash.ToArray();
}
_expected = _startAfter + 1;
_chainFromUtc = chainFromUtc;
if (anchorProblem is not null)
{
Fail(AuditChainHasher.CutoffAnchorSeq, AuditChainHasher.CutoffAnchorEventId,
AuditChainBreakKind.CutoffAnchorInvalid, anchorProblem);
}
}
/// <summary>The chain cutoff this verification applies, or null.</summary>
public DateTime? ChainFromUtc => _chainFromUtc;
/// <summary>The chain partition label (<c>YYYY-MM</c>).</summary>
public string Partition => _partition;
/// <summary>The checkpoint anchor this verification resumed after, or null.</summary>
public long? PurgedThroughSeq => _head?.PurgedThroughSeq;
/// <summary>True once a break has been found; further rows are ignored.</summary>
public bool IsBroken => _break is not null;
/// <summary>Feeds the next chained row (ascending ChainSeq).</summary>
/// <param name="row">The row; its <see cref="AuditChainRow.ChainSeq"/> must be non-null.</param>
/// <returns>False once a break has been found, so the caller can stop reading.</returns>
public bool Accept(AuditChainRow row)
{
ArgumentNullException.ThrowIfNull(row);
if (_break is not null)
{
return false;
}
var seq = row.ChainSeq ?? throw new ArgumentException("Only chained rows can be verified.", nameof(row));
// Rows at or below a partition-purge anchor cannot exist (the switch removed the
// whole month's partition); ignore rather than mis-report them.
if (seq <= _startAfter)
{
return true;
}
if (_chainFromUtc is { } chainFrom && row.OccurredAtUtc < chainFrom)
{
return Fail(seq, row.EventId, AuditChainBreakKind.ChainedBeforeCutoff,
$"Row at ChainSeq {seq} is dated {row.OccurredAtUtc:O}, before the chain cutoff {chainFrom:O}: "
+ "no row before the cutoff is ever chained, so its timestamp was moved back or the cutoff was moved forward.");
}
if (seq < _expected)
{
return Fail(seq, row.EventId, AuditChainBreakKind.DuplicateSequence,
$"ChainSeq {seq} appears more than once.");
}
while (_expected < seq)
{
if (!_tombstones.TryGetValue(_expected, out var tombstone))
{
return Fail(_expected, row.EventId, AuditChainBreakKind.MissingRow,
$"ChainSeq {_expected} is missing and no purge tombstone covers it; "
+ $"the next chained row is ChainSeq {seq} (EventId {row.EventId}).");
}
_previous = tombstone;
_tombstonesApplied++;
_expected++;
}
if (row.RowHash is not { Length: AuditChainHasher.HashLength } stored)
{
return Fail(seq, row.EventId, AuditChainBreakKind.IncompleteLink,
$"Row at ChainSeq {seq} has a sequence number but no 32-byte RowHash.");
}
var computed = AuditChainHasher.ComputeRowHash(_previous, _monthStartUtc, seq, row);
if (!computed.AsSpan().SequenceEqual(stored))
{
return Fail(seq, row.EventId, AuditChainBreakKind.HashMismatch,
$"Recomputed hash of the row at ChainSeq {seq} does not match its stored RowHash: "
+ "the row was edited, moved to a different position, or an earlier link was altered.");
}
_previous = stored;
_expected++;
_verified++;
return true;
}
/// <summary>Finishes verification against the chain head.</summary>
/// <param name="unchainedRows">Rows in the month, at or after the cutoff, not yet chained (reported, never a break).</param>
/// <param name="preCutoffRows">Rows in the month before the chain cutoff: out of scope, never chained (reported, never a break).</param>
/// <returns>The verification result.</returns>
public AuditChainVerificationResult Complete(long unchainedRows, long preCutoffRows = 0)
{
if (_break is null)
{
// A purge tombstone may cover the newest links.
while (_tombstones.TryGetValue(_expected, out var tombstone))
{
_previous = tombstone;
_tombstonesApplied++;
_expected++;
}
var lastSeq = _expected - 1;
if (_head is null)
{
if (lastSeq > _startAfter)
{
Fail(lastSeq, null, AuditChainBreakKind.HeadMismatch,
$"Chained rows exist through ChainSeq {lastSeq} but the month has no chain head.");
}
else
{
return Result(AuditChainStatus.NotChained, unchainedRows, preCutoffRows);
}
}
else if (lastSeq < _head.LastSeq)
{
Fail(lastSeq + 1, null, AuditChainBreakKind.HeadMismatch,
$"The chain ends at ChainSeq {lastSeq} but the head records {_head.LastSeq}: "
+ $"ChainSeq {lastSeq + 1}..{_head.LastSeq} are missing (rows deleted from the end).");
}
else if (lastSeq > _head.LastSeq)
{
Fail(_head.LastSeq + 1, null, AuditChainBreakKind.HeadMismatch,
$"The chain continues to ChainSeq {lastSeq} past the head's {_head.LastSeq}.");
}
else if (!_previous.AsSpan().SequenceEqual(_head.LastHash))
{
Fail(lastSeq, null, AuditChainBreakKind.HeadMismatch,
$"The hash at ChainSeq {lastSeq} does not match the chain head's recorded hash.");
}
}
return Result(_break is null ? AuditChainStatus.Intact : AuditChainStatus.Broken, unchainedRows, preCutoffRows);
}
private AuditChainVerificationResult Result(AuditChainStatus status, long unchainedRows, long preCutoffRows)
=> new(
_partition,
status,
_verified,
_tombstonesApplied,
_head?.PurgedThroughSeq,
_head?.LastSeq,
unchainedRows,
_break,
preCutoffRows,
_chainFromUtc);
private bool Fail(long seq, Guid? eventId, AuditChainBreakKind kind, string detail)
{
_break ??= new AuditChainBreak(_partition, seq, eventId, kind, detail);
return false;
}
}
@@ -38,12 +38,6 @@ public sealed class AuditLogArchiveOptions
/// </summary> /// </summary>
public int ReadCommandTimeoutMinutes { get; set; } = 60; public int ReadCommandTimeoutMinutes { get; set; } = 60;
/// <summary>
/// How long, in seconds, archiving waits for a chaining pass or another purge to release
/// the hash-chain lock before giving up for this tick (default 300).
/// </summary>
public int ChainLockTimeoutSeconds { get; set; } = 300;
/// <summary> /// <summary>
/// Archive retention in days, counted from the END of the archived month (ScadaBridge#109). /// Archive retention in days, counted from the END of the archived month (ScadaBridge#109).
/// <c>0</c> (the default) = archives are never deleted — until compliance names a period. /// <c>0</c> (the default) = archives are never deleted — until compliance names a period.
@@ -1,729 +0,0 @@
using System.Data;
using System.Data.Common;
using System.Text;
using Microsoft.Data.SqlClient;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;
using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance;
/// <summary>
/// The SQL Server application lock that serialises every writer of AuditLog hash-chain
/// state (ScadaBridge#41): the chaining job and both purge paths take it EXCLUSIVE;
/// verification takes it SHARED so it reads a chain no writer is half-way through.
/// </summary>
public static class AuditChainLock
{
/// <summary>The <c>sp_getapplock</c> resource name.</summary>
public const string Resource = "ScadaBridge.AuditLogHashChain";
}
/// <summary>
/// SQL Server implementation of <see cref="IAuditLogHashChain"/> (ScadaBridge#41,
/// alog.md §11.4). See the interface for the chain model.
/// </summary>
/// <remarks>
/// <para>
/// <b>Concurrency.</b> Two central nodes and the site-ingest path INSERT into
/// <c>dbo.AuditLog</c> concurrently; none of them touches the chain. The chaining pass runs
/// in one transaction that first takes the exclusive <see cref="AuditChainLock"/> with a
/// zero timeout (the peer node's pass simply skips its tick), then reads the head row with
/// <c>UPDLOCK, HOLDLOCK</c> and advances it with an optimistic <c>LastSeq</c> check. Every
/// link UPDATE is guarded by <c>ChainSeq IS NULL</c> and its row count is checked, so a row
/// purged or chained underneath the pass rolls the whole pass back instead of leaving a gap.
/// A row INSERTed while the pass runs is invisible to it (READ COMMITTED) and is chained on
/// a later pass with a later sequence number — chain order is chaining order, not
/// <c>OccurredAtUtc</c> order, which is why late-arriving site rows need no special case.
/// </para>
/// <para>
/// <b>Chain start (ScadaBridge#139).</b> Unless the caller asks for backlog chaining, the first
/// pass on a pristine database (no chain head, no chained row) records a <b>chain-start
/// anchor</b> and only rows dated at or after it are ever chained; the historical backlog stays
/// unchained and out of scope. The anchor is one row in <c>dbo.AuditLogChainTombstone</c> at
/// <c>ChainSeq = 0</c> of the cutoff month: <c>PurgedAtUtc</c> holds the cutoff (the database's
/// <c>SYSUTCDATETIME()</c> at first enablement, so both central nodes see the same instant
/// whatever their own clocks say), <c>RowHash</c> holds
/// <see cref="AuditChainHasher.ComputeCutoffAnchorHash"/> of it, and that hash is the genesis
/// the cutoff month's first row links to. It is written once, under the exclusive chain lock,
/// and never updated; the partition-switch purge keeps it. A database that already has a
/// chain (heads or chained rows) and no anchor keeps chaining every row, as before.
/// </para>
/// <para>
/// <b>Append-only.</b> The only AuditLog columns this class writes are <c>ChainSeq</c> and
/// <c>RowHash</c>, and only while they are NULL. In production that UPDATE runs under the
/// <c>scadabridge_audit_chainer</c> role, which holds a COLUMN-level UPDATE grant on just
/// those two columns; the ingest writer role keeps its table-wide DENY UPDATE.
/// </para>
/// </remarks>
public sealed class AuditLogHashChain : IAuditLogHashChain, IAuditChainHeadStore
{
// 4 parameters per row; 200 rows = 800 parameters, far under SQL Server's 2,100 cap.
private const int UpdateChunkRows = 200;
/// <summary>The ten writable AuditLog columns, in table order — the hashed row content.</summary>
internal const string RowColumns =
"EventId, OccurredAtUtc, Actor, Action, Outcome, Category, Target, SourceNode, CorrelationId, DetailsJson";
private readonly ScadaBridgeDbContext _context;
private readonly ILogger<AuditLogHashChain> _logger;
/// <summary>Initializes a new instance of the <see cref="AuditLogHashChain"/> class.</summary>
/// <param name="context">The database context whose connection is used.</param>
/// <param name="logger">Optional logger.</param>
public AuditLogHashChain(ScadaBridgeDbContext context, ILogger<AuditLogHashChain>? logger = null)
{
_context = context ?? throw new ArgumentNullException(nameof(context));
_logger = logger ?? NullLogger<AuditLogHashChain>.Instance;
}
/// <summary>
/// Command timeout for verification statements, in seconds. A month can hold millions
/// of rows; the management Ask (long-running, 5 min) is the real deadline.
/// </summary>
public int VerifyCommandTimeoutSeconds { get; init; } = 300;
/// <summary>
/// Test seam: the cutoff a new chain-start anchor records. Null (production) uses the
/// database's <c>SYSUTCDATETIME()</c> so both central nodes agree regardless of node clocks.
/// </summary>
internal Func<DateTime>? AnchorClock { get; init; }
/// <summary>How long verification waits for an in-flight chaining/purge pass to release the lock.</summary>
public TimeSpan VerifyLockTimeout { get; init; } = TimeSpan.FromSeconds(60);
/// <inheritdoc />
public async Task<AuditChainBatchResult> ChainPendingAsync(int batchSize, bool chainBacklog = false, CancellationToken ct = default)
{
if (batchSize <= 0)
{
throw new ArgumentOutOfRangeException(nameof(batchSize), batchSize, "Batch size must be > 0.");
}
var conn = _context.Database.GetDbConnection();
var openedHere = await OpenAsync(conn, ct).ConfigureAwait(false);
try
{
await using var tx = await conn.BeginTransactionAsync(IsolationLevel.ReadCommitted, ct).ConfigureAwait(false);
if (!await TryAcquireLockAsync(conn, tx, "Exclusive", TimeSpan.Zero, ct).ConfigureAwait(false))
{
await tx.RollbackAsync(ct).ConfigureAwait(false);
return new AuditChainBatchResult(0, LockBusy: true);
}
// Chain start (ScadaBridge#139): the cutoff, recorded on the first pass.
var cutoff = await ReadChainerCutoffAsync(conn, tx, ct).ConfigureAwait(false);
if (cutoff is null && !chainBacklog && await IsPristineAsync(conn, tx, ct).ConfigureAwait(false))
{
cutoff = await CreateCutoffAnchorAsync(conn, tx, ct).ConfigureAwait(false);
}
// Oldest month that still has unchained rows in scope. One month per pass keeps the
// candidate read partition-eliminated and index-ordered (no cross-partition sort).
DateTime? oldest;
await using (var cmd = Command(conn, tx,
"SELECT TOP (1) OccurredAtUtc FROM dbo.AuditLog WHERE ChainSeq IS NULL AND OccurredAtUtc >= @chainFrom ORDER BY OccurredAtUtc;"))
{
AddChainFrom(cmd, cutoff?.ChainFromUtc);
var scalar = await cmd.ExecuteScalarAsync(ct).ConfigureAwait(false);
oldest = scalar is DateTime dt ? DateTime.SpecifyKind(dt, DateTimeKind.Utc) : null;
}
if (oldest is null)
{
await tx.CommitAsync(ct).ConfigureAwait(false);
return new AuditChainBatchResult(0, LockBusy: false);
}
var month = AuditChainHasher.MonthOf(oldest.Value);
var candidates = new List<AuditChainRow>(Math.Min(batchSize, 4096));
await using (var cmd = Command(conn, tx,
$"SELECT TOP (@batch) {RowColumns} FROM dbo.AuditLog " +
"WHERE ChainSeq IS NULL AND OccurredAtUtc >= @monthStart AND OccurredAtUtc < @monthEnd " +
"AND OccurredAtUtc >= @chainFrom " +
"ORDER BY OccurredAtUtc, EventId;"))
{
AddInt(cmd, "@batch", batchSize);
AddMonthRange(cmd, month);
AddChainFrom(cmd, cutoff?.ChainFromUtc);
await using var reader = await cmd.ExecuteReaderAsync(ct).ConfigureAwait(false);
while (await reader.ReadAsync(ct).ConfigureAwait(false))
{
candidates.Add(ReadRow(reader, withLink: false));
}
}
// Current chain end for the month, locked until commit.
long? headSeq = null;
byte[] previous = AuditChainHasher.GenesisHash.ToArray();
await using (var cmd = Command(conn, tx,
"SELECT LastSeq, LastHash FROM dbo.AuditLogChainHead WITH (UPDLOCK, HOLDLOCK) WHERE ChainMonth = @month;"))
{
AddDate(cmd, "@month", month);
await using var reader = await cmd.ExecuteReaderAsync(ct).ConfigureAwait(false);
if (await reader.ReadAsync(ct).ConfigureAwait(false))
{
headSeq = reader.GetInt64(0);
previous = (byte[])reader.GetValue(1);
}
}
// The cutoff month's chain starts from the anchor, not from 32 zero bytes, so the
// cutoff is inside every later link of that month.
if (headSeq is null && cutoff is not null && cutoff.Month == month)
{
previous = cutoff.AnchorHash.ToArray();
}
var seq = headSeq ?? 0;
var links = new List<(AuditChainRow Row, long Seq, byte[] Hash)>(candidates.Count);
foreach (var row in candidates)
{
seq++;
var hash = AuditChainHasher.ComputeRowHash(previous, month, seq, row);
links.Add((row, seq, hash));
previous = hash;
}
for (var offset = 0; offset < links.Count; offset += UpdateChunkRows)
{
var chunk = links.Skip(offset).Take(UpdateChunkRows).ToList();
var updated = await WriteLinksAsync(conn, tx, chunk, ct).ConfigureAwait(false);
if (updated != chunk.Count)
{
// A candidate was purged (or chained by a pass that bypassed the lock)
// between the read and the write. Linking the rest would leave a gap.
_logger.LogWarning(
"AuditLog hash chain: {Updated} of {Expected} links written for {Partition}; rolling the pass back to retry.",
updated, chunk.Count, AuditChainHasher.PartitionLabel(month));
await tx.RollbackAsync(ct).ConfigureAwait(false);
return new AuditChainBatchResult(0, LockBusy: false);
}
}
if (links.Count > 0 && !await AdvanceHeadAsync(conn, tx, month, headSeq, seq, previous, ct).ConfigureAwait(false))
{
_logger.LogWarning(
"AuditLog hash chain: head for {Partition} moved underneath the pass; rolling back to retry.",
AuditChainHasher.PartitionLabel(month));
await tx.RollbackAsync(ct).ConfigureAwait(false);
return new AuditChainBatchResult(0, LockBusy: false);
}
await tx.CommitAsync(ct).ConfigureAwait(false);
return new AuditChainBatchResult(links.Count, LockBusy: false);
}
finally
{
if (openedHere)
{
await conn.CloseAsync().ConfigureAwait(false);
}
}
}
/// <inheritdoc />
public async Task<AuditChainVerificationResult> VerifyMonthAsync(DateTime monthStartUtc, CancellationToken ct = default)
{
var month = AuditChainHasher.MonthOf(DateTime.SpecifyKind(monthStartUtc, DateTimeKind.Utc));
var conn = _context.Database.GetDbConnection();
var openedHere = await OpenAsync(conn, ct).ConfigureAwait(false);
try
{
await using var tx = await conn.BeginTransactionAsync(IsolationLevel.ReadCommitted, ct).ConfigureAwait(false);
if (!await TryAcquireLockAsync(conn, tx, "Shared", VerifyLockTimeout, ct).ConfigureAwait(false))
{
await tx.RollbackAsync(ct).ConfigureAwait(false);
throw new TimeoutException(
$"The AuditLog hash chain was busy (chaining or purge in progress) for {VerifyLockTimeout.TotalSeconds:0}s; retry.");
}
AuditChainHeadState? head = null;
await using (var cmd = Command(conn, tx,
"SELECT LastSeq, LastHash, PurgedThroughSeq, PurgedThroughHash FROM dbo.AuditLogChainHead WHERE ChainMonth = @month;"))
{
AddDate(cmd, "@month", month);
await using var reader = await cmd.ExecuteReaderAsync(ct).ConfigureAwait(false);
if (await reader.ReadAsync(ct).ConfigureAwait(false))
{
head = new AuditChainHeadState(
reader.GetInt64(0),
(byte[])reader.GetValue(1),
reader.IsDBNull(2) ? null : reader.GetInt64(2),
reader.IsDBNull(3) ? null : (byte[])reader.GetValue(3));
}
}
var cutoff = await ReadVerifierCutoffAsync(conn, tx, ct).ConfigureAwait(false);
var tombstones = new Dictionary<long, byte[]>();
await using (var cmd = Command(conn, tx,
"SELECT ChainSeq, RowHash FROM dbo.AuditLogChainTombstone WHERE ChainMonth = @month;"))
{
AddDate(cmd, "@month", month);
await using var reader = await cmd.ExecuteReaderAsync(ct).ConfigureAwait(false);
while (await reader.ReadAsync(ct).ConfigureAwait(false))
{
tombstones[reader.GetInt64(0)] = (byte[])reader.GetValue(1);
}
}
// Unchained rows split at the cutoff: pending (in scope, not reached yet) versus
// pre-cutoff (out of scope by design, never chained).
long unchained = 0, preCutoff = 0;
await using (var cmd = Command(conn, tx,
"SELECT COUNT_BIG(CASE WHEN OccurredAtUtc >= @chainFrom THEN 1 END), COUNT_BIG(CASE WHEN OccurredAtUtc < @chainFrom THEN 1 END) " +
"FROM dbo.AuditLog WHERE ChainSeq IS NULL AND OccurredAtUtc >= @monthStart AND OccurredAtUtc < @monthEnd;"))
{
cmd.CommandTimeout = VerifyCommandTimeoutSeconds;
AddMonthRange(cmd, month);
AddChainFrom(cmd, cutoff.ChainFromUtc);
await using var reader = await cmd.ExecuteReaderAsync(ct).ConfigureAwait(false);
if (await reader.ReadAsync(ct).ConfigureAwait(false))
{
unchained = reader.GetInt64(0);
preCutoff = reader.GetInt64(1);
}
}
var verifier = new AuditChainVerifier(month, head, tombstones, cutoff.ChainFromUtc, cutoff.Problem);
await using (var cmd = Command(conn, tx,
$"SELECT {RowColumns}, ChainSeq, RowHash FROM dbo.AuditLog " +
"WHERE ChainSeq IS NOT NULL AND OccurredAtUtc >= @monthStart AND OccurredAtUtc < @monthEnd " +
"ORDER BY ChainSeq;"))
{
cmd.CommandTimeout = VerifyCommandTimeoutSeconds;
AddMonthRange(cmd, month);
await using var reader = await cmd.ExecuteReaderAsync(CommandBehavior.SequentialAccess, ct).ConfigureAwait(false);
while (await reader.ReadAsync(ct).ConfigureAwait(false))
{
if (!verifier.Accept(ReadRow(reader, withLink: true)))
{
break;
}
}
}
await tx.CommitAsync(ct).ConfigureAwait(false);
return verifier.Complete(unchained, preCutoff);
}
finally
{
if (openedHere)
{
await conn.CloseAsync().ConfigureAwait(false);
}
}
}
/// <inheritdoc />
public async Task<IReadOnlyList<AuditChainHeadSnapshot>> ReadHeadsAsync(CancellationToken ct = default)
{
var conn = _context.Database.GetDbConnection();
var openedHere = await OpenAsync(conn, ct).ConfigureAwait(false);
try
{
await using var tx = await conn.BeginTransactionAsync(IsolationLevel.ReadCommitted, ct).ConfigureAwait(false);
await AcquireSharedOrThrowAsync(conn, tx, ct).ConfigureAwait(false);
var heads = await ReadHeadsCoreAsync(conn, tx, ct).ConfigureAwait(false);
await tx.CommitAsync(ct).ConfigureAwait(false);
return heads;
}
finally
{
if (openedHere)
{
await conn.CloseAsync().ConfigureAwait(false);
}
}
}
/// <inheritdoc />
public async Task<AuditChainHeadVerificationResult> VerifyExportedHeadsAsync(
IReadOnlyList<AuditChainHeadRecord> records, CancellationToken ct = default)
{
ArgumentNullException.ThrowIfNull(records);
// Collapse duplicates (both centrals export, and every unchanged re-export repeats a
// record): one check per distinct (month, sequence, hash) claim.
var distinct = records
.GroupBy(r => (r.Month, r.LastSeq, Hash: r.LastHash?.ToLowerInvariant()))
.Select(g => g.OrderByDescending(r => r.ExportedAtUtc).First())
.ToList();
var conn = _context.Database.GetDbConnection();
var openedHere = await OpenAsync(conn, ct).ConfigureAwait(false);
try
{
await using var tx = await conn.BeginTransactionAsync(IsolationLevel.ReadCommitted, ct).ConfigureAwait(false);
await AcquireSharedOrThrowAsync(conn, tx, ct).ConfigureAwait(false);
var heads = (await ReadHeadsCoreAsync(conn, tx, ct).ConfigureAwait(false))
.ToDictionary(h => AuditChainHasher.PartitionLabel(h.Month), StringComparer.Ordinal);
var checks = new List<AuditChainHeadCheck>(distinct.Count);
foreach (var record in distinct)
{
if (!AuditChainHeadComparer.TryParseMonth(record.Month, out var month))
{
checks.Add(new AuditChainHeadCheck(record.Month ?? "", record.LastSeq, record.ExportedAtUtc, record.Node,
AuditChainHeadStatus.Mismatch, null, $"Exported month '{record.Month}' is not YYYY-MM."));
continue;
}
heads.TryGetValue(AuditChainHasher.PartitionLabel(month), out var head);
checks.Add(await AuditChainHeadComparer.CompareAsync(
record, head, seq => ReadStoredLinkAsync(conn, tx, month, seq, ct)).ConfigureAwait(false));
}
await tx.CommitAsync(ct).ConfigureAwait(false);
var ordered = checks
.OrderByDescending(c => c.IsFailure)
.ThenBy(c => c.Month, StringComparer.Ordinal)
.ThenBy(c => c.ExportedSeq)
.ToList();
return new AuditChainHeadVerificationResult(ordered.All(c => !c.IsFailure), ordered.Count, ordered);
}
finally
{
if (openedHere)
{
await conn.CloseAsync().ConfigureAwait(false);
}
}
}
private async Task AcquireSharedOrThrowAsync(DbConnection conn, DbTransaction tx, CancellationToken ct)
{
if (!await TryAcquireLockAsync(conn, tx, "Shared", VerifyLockTimeout, ct).ConfigureAwait(false))
{
await tx.RollbackAsync(ct).ConfigureAwait(false);
throw new TimeoutException(
$"The AuditLog hash chain was busy (chaining or purge in progress) for {VerifyLockTimeout.TotalSeconds:0}s; retry.");
}
}
private async Task<IReadOnlyList<AuditChainHeadSnapshot>> ReadHeadsCoreAsync(DbConnection conn, DbTransaction tx, CancellationToken ct)
{
// Per month: the head row, the chained rows still present (the filtered ChainSeq index,
// partition-eliminated by the month range) and the tombstones. The head table holds one
// row per month ever chained, so this is a few dozen rows.
var heads = new List<AuditChainHeadSnapshot>();
await using var cmd = Command(conn, tx, @"
SELECT h.ChainMonth, h.LastSeq, h.LastHash, h.PurgedThroughSeq, h.PurgedThroughHash, h.UpdatedAtUtc,
(SELECT COUNT_BIG(*) FROM dbo.AuditLog a
WHERE a.ChainSeq IS NOT NULL
AND a.OccurredAtUtc >= CAST(h.ChainMonth AS datetime2(7))
AND a.OccurredAtUtc < DATEADD(MONTH, 1, CAST(h.ChainMonth AS datetime2(7)))) AS ChainedRows,
(SELECT COUNT_BIG(*) FROM dbo.AuditLogChainTombstone t WHERE t.ChainMonth = h.ChainMonth AND t.ChainSeq > 0) AS Tombstones
FROM dbo.AuditLogChainHead h
ORDER BY h.ChainMonth;");
cmd.CommandTimeout = VerifyCommandTimeoutSeconds;
await using var reader = await cmd.ExecuteReaderAsync(ct).ConfigureAwait(false);
while (await reader.ReadAsync(ct).ConfigureAwait(false))
{
heads.Add(new AuditChainHeadSnapshot(
DateTime.SpecifyKind(reader.GetDateTime(0), DateTimeKind.Utc),
reader.GetInt64(1),
(byte[])reader.GetValue(2),
reader.IsDBNull(3) ? null : reader.GetInt64(3),
reader.IsDBNull(4) ? null : (byte[])reader.GetValue(4),
reader.GetInt64(6),
reader.GetInt64(7),
DateTime.SpecifyKind(reader.GetDateTime(5), DateTimeKind.Utc)));
}
return heads;
}
private async Task<AuditChainHeadComparer.StoredLink> ReadStoredLinkAsync(
DbConnection conn, DbTransaction tx, DateTime month, long seq, CancellationToken ct)
{
byte[]? rowHash;
await using (var cmd = Command(conn, tx,
"SELECT TOP (1) RowHash FROM dbo.AuditLog WHERE ChainSeq = @seq AND OccurredAtUtc >= @monthStart AND OccurredAtUtc < @monthEnd;"))
{
cmd.CommandTimeout = VerifyCommandTimeoutSeconds;
cmd.Parameters.Add(new SqlParameter("@seq", SqlDbType.BigInt) { Value = seq });
AddMonthRange(cmd, month);
rowHash = await cmd.ExecuteScalarAsync(ct).ConfigureAwait(false) as byte[];
}
byte[]? tombstoneHash = null;
if (rowHash is null)
{
await using var cmd = Command(conn, tx,
"SELECT RowHash FROM dbo.AuditLogChainTombstone WHERE ChainMonth = @month AND ChainSeq = @seq;");
AddDate(cmd, "@month", month);
cmd.Parameters.Add(new SqlParameter("@seq", SqlDbType.BigInt) { Value = seq });
tombstoneHash = await cmd.ExecuteScalarAsync(ct).ConfigureAwait(false) as byte[];
}
return new AuditChainHeadComparer.StoredLink(rowHash, tombstoneHash);
}
/// <summary>The chain-start anchor as the chainer uses it (ScadaBridge#139).</summary>
/// <param name="ChainFromUtc">The cutoff.</param>
/// <param name="Month">The cutoff month (the anchor's <c>ChainMonth</c>).</param>
/// <param name="AnchorHash">The anchor's stored hash: the cutoff month's genesis.</param>
private sealed record ChainCutoff(DateTime ChainFromUtc, DateTime Month, byte[] AnchorHash);
/// <summary>The cutoff as verification sees it (ScadaBridge#139).</summary>
/// <param name="ChainFromUtc">The cutoff, or null when the chain covers the whole table.</param>
/// <param name="Problem">Why the anchor cannot be trusted, or null.</param>
private sealed record VerifierCutoff(DateTime? ChainFromUtc, string? Problem);
/// <summary>
/// Reads the chain-start anchor for the chaining pass. It can only sit in a month at or
/// before the earliest chain head (it is written before anything is chained, and nothing
/// before it ever is), so the read is bounded to those months rather than scanning every
/// per-channel purge tombstone each tick. Verification reads them all.
/// </summary>
private static async Task<ChainCutoff?> ReadChainerCutoffAsync(DbConnection conn, DbTransaction tx, CancellationToken ct)
{
await using var cmd = Command(conn, tx,
"SELECT TOP (1) ChainMonth, RowHash, PurgedAtUtc FROM dbo.AuditLogChainTombstone " +
"WHERE ChainSeq = 0 AND ChainMonth <= ISNULL((SELECT MIN(ChainMonth) FROM dbo.AuditLogChainHead), '9999-12-01') " +
"ORDER BY PurgedAtUtc, ChainMonth;");
await using var reader = await cmd.ExecuteReaderAsync(ct).ConfigureAwait(false);
if (!await reader.ReadAsync(ct).ConfigureAwait(false))
{
return null;
}
return new ChainCutoff(
DateTime.SpecifyKind(reader.GetDateTime(2), DateTimeKind.Utc),
DateTime.SpecifyKind(reader.GetDateTime(0), DateTimeKind.Utc),
(byte[])reader.GetValue(1));
}
/// <summary>
/// Reads every chain-start anchor and checks it: exactly one, in its cutoff's month, hashing
/// to its own cutoff. The earliest anchor's cutoff is used either way, matching the chainer.
/// </summary>
private async Task<VerifierCutoff> ReadVerifierCutoffAsync(DbConnection conn, DbTransaction tx, CancellationToken ct)
{
var anchors = new List<(DateTime Month, byte[] Hash, DateTime ChainFrom)>();
await using (var cmd = Command(conn, tx,
"SELECT ChainMonth, RowHash, PurgedAtUtc FROM dbo.AuditLogChainTombstone WHERE ChainSeq = 0 ORDER BY PurgedAtUtc, ChainMonth;"))
{
cmd.CommandTimeout = VerifyCommandTimeoutSeconds;
await using var reader = await cmd.ExecuteReaderAsync(ct).ConfigureAwait(false);
while (await reader.ReadAsync(ct).ConfigureAwait(false))
{
anchors.Add((
DateTime.SpecifyKind(reader.GetDateTime(0), DateTimeKind.Utc),
(byte[])reader.GetValue(1),
DateTime.SpecifyKind(reader.GetDateTime(2), DateTimeKind.Utc)));
}
}
if (anchors.Count == 0)
{
return new VerifierCutoff(null, null);
}
var (anchorMonth, hash, chainFrom) = anchors[0];
string? problem = null;
if (anchors.Count > 1)
{
problem = $"{anchors.Count} chain-start anchors exist (cutoffs {string.Join(", ", anchors.Select(a => a.ChainFrom.ToString("O", System.Globalization.CultureInfo.InvariantCulture)))}); "
+ "exactly one is ever written.";
}
else if (anchorMonth != AuditChainHasher.MonthOf(chainFrom))
{
problem = $"The chain-start anchor is filed under {AuditChainHasher.PartitionLabel(anchorMonth)} but its cutoff {chainFrom:O} is in another month.";
}
else if (!AuditChainHasher.ComputeCutoffAnchorHash(chainFrom).AsSpan().SequenceEqual(hash))
{
problem = $"The chain-start anchor's hash does not match its cutoff {chainFrom:O}: the cutoff or the anchor was altered.";
}
return new VerifierCutoff(chainFrom, problem);
}
/// <summary>True when nothing has ever been chained: no chain head and no chained row.</summary>
private static async Task<bool> IsPristineAsync(DbConnection conn, DbTransaction tx, CancellationToken ct)
{
await using var cmd = Command(conn, tx,
"SELECT CASE WHEN EXISTS (SELECT 1 FROM dbo.AuditLogChainHead) " +
"OR EXISTS (SELECT 1 FROM dbo.AuditLog WHERE ChainSeq IS NOT NULL) THEN 0 ELSE 1 END;");
return Convert.ToInt32(await cmd.ExecuteScalarAsync(ct).ConfigureAwait(false)) == 1;
}
/// <summary>
/// Writes the chain-start anchor at the database's current UTC time (ScadaBridge#139). Runs
/// inside the chaining transaction, under the exclusive chain lock, so exactly one node
/// writes it and the peer's next pass reads it.
/// </summary>
private async Task<ChainCutoff> CreateCutoffAnchorAsync(DbConnection conn, DbTransaction tx, CancellationToken ct)
{
DateTime chainFrom;
if (AnchorClock is { } clock)
{
chainFrom = DateTime.SpecifyKind(clock(), DateTimeKind.Utc);
}
else
{
await using var cmd = Command(conn, tx, "SELECT SYSUTCDATETIME();");
chainFrom = DateTime.SpecifyKind((DateTime)(await cmd.ExecuteScalarAsync(ct).ConfigureAwait(false))!, DateTimeKind.Utc);
}
var month = AuditChainHasher.MonthOf(chainFrom);
var hash = AuditChainHasher.ComputeCutoffAnchorHash(chainFrom);
await using (var cmd = Command(conn, tx,
"INSERT INTO dbo.AuditLogChainTombstone (ChainMonth, ChainSeq, RowHash, EventId, PurgedAtUtc) " +
"VALUES (@month, 0, @hash, @eventId, @chainFrom);"))
{
AddDate(cmd, "@month", month);
cmd.Parameters.Add(new SqlParameter("@hash", SqlDbType.Binary, AuditChainHasher.HashLength) { Value = hash });
cmd.Parameters.Add(new SqlParameter("@eventId", SqlDbType.UniqueIdentifier) { Value = AuditChainHasher.CutoffAnchorEventId });
cmd.Parameters.Add(new SqlParameter("@chainFrom", SqlDbType.DateTime2) { Scale = 7, Value = chainFrom });
await cmd.ExecuteNonQueryAsync(ct).ConfigureAwait(false);
}
_logger.LogInformation(
"AuditLog hash chain started at {ChainFrom:O}: only rows dated from then on are chained; earlier rows stay unchained and out of scope (ScadaBridge#139).",
chainFrom);
return new ChainCutoff(chainFrom, month, hash);
}
private static void AddChainFrom(DbCommand cmd, DateTime? chainFromUtc)
=> cmd.Parameters.Add(new SqlParameter("@chainFrom", SqlDbType.DateTime2) { Scale = 7, Value = chainFromUtc ?? DateTime.MinValue });
/// <summary>
/// Takes the chain application lock inside <paramref name="tx"/> (released at commit /
/// rollback). Returns false when the lock could not be granted within <paramref name="timeout"/>.
/// </summary>
internal static async Task<bool> TryAcquireLockAsync(
DbConnection conn, DbTransaction tx, string mode, TimeSpan timeout, CancellationToken ct)
{
await using var cmd = Command(conn, tx,
"DECLARE @result int; " +
"EXEC @result = sp_getapplock @Resource = @resource, @LockMode = @mode, @LockOwner = 'Transaction', @LockTimeout = @timeoutMs; " +
"SELECT @result;");
cmd.Parameters.Add(new SqlParameter("@resource", SqlDbType.NVarChar, 255) { Value = AuditChainLock.Resource });
cmd.Parameters.Add(new SqlParameter("@mode", SqlDbType.VarChar, 32) { Value = mode });
AddInt(cmd, "@timeoutMs", (int)Math.Min(int.MaxValue, timeout.TotalMilliseconds));
if (timeout > TimeSpan.Zero)
{
cmd.CommandTimeout = (int)Math.Ceiling(timeout.TotalSeconds) + 30;
}
var result = Convert.ToInt32(await cmd.ExecuteScalarAsync(ct).ConfigureAwait(false));
return result >= 0;
}
private static async Task<int> WriteLinksAsync(
DbConnection conn, DbTransaction tx, IReadOnlyList<(AuditChainRow Row, long Seq, byte[] Hash)> chunk, CancellationToken ct)
{
var sql = new StringBuilder();
// The ONE sanctioned UPDATE against AuditLog outside the maintenance backfill: it
// writes only the two chain columns, only while they are still NULL.
sql.Append("UPDATE dbo.AuditLog SET ChainSeq = v.ChainSeq, RowHash = v.RowHash\n"); // AUDIT-PURGE-ALLOWED: hash-chain link (ChainSeq/RowHash only, NULL→value), chaining job
sql.Append("FROM dbo.AuditLog INNER JOIN (VALUES ");
await using var cmd = conn.CreateCommand();
cmd.Transaction = tx;
for (var i = 0; i < chunk.Count; i++)
{
if (i > 0)
{
sql.Append(", ");
}
sql.Append($"(@e{i}, @o{i}, @s{i}, @h{i})");
cmd.Parameters.Add(new SqlParameter($"@e{i}", SqlDbType.UniqueIdentifier) { Value = chunk[i].Row.EventId });
cmd.Parameters.Add(new SqlParameter($"@o{i}", SqlDbType.DateTime2) { Scale = 7, Value = chunk[i].Row.OccurredAtUtc });
cmd.Parameters.Add(new SqlParameter($"@s{i}", SqlDbType.BigInt) { Value = chunk[i].Seq });
cmd.Parameters.Add(new SqlParameter($"@h{i}", SqlDbType.Binary, AuditChainHasher.HashLength) { Value = chunk[i].Hash });
}
sql.Append(") AS v (EventId, OccurredAtUtc, ChainSeq, RowHash)\n");
sql.Append("ON dbo.AuditLog.EventId = v.EventId AND dbo.AuditLog.OccurredAtUtc = v.OccurredAtUtc\n");
sql.Append("WHERE dbo.AuditLog.ChainSeq IS NULL;");
cmd.CommandText = sql.ToString();
return await cmd.ExecuteNonQueryAsync(ct).ConfigureAwait(false);
}
private static async Task<bool> AdvanceHeadAsync(
DbConnection conn, DbTransaction tx, DateTime month, long? oldSeq, long newSeq, byte[] newHash, CancellationToken ct)
{
await using var cmd = Command(conn, tx, oldSeq is null
? "INSERT INTO dbo.AuditLogChainHead (ChainMonth, LastSeq, LastHash, UpdatedAtUtc) VALUES (@month, @seq, @hash, SYSUTCDATETIME());"
: "UPDATE dbo.AuditLogChainHead SET LastSeq = @seq, LastHash = @hash, UpdatedAtUtc = SYSUTCDATETIME() " +
"WHERE ChainMonth = @month AND LastSeq = @oldSeq;");
AddDate(cmd, "@month", month);
cmd.Parameters.Add(new SqlParameter("@seq", SqlDbType.BigInt) { Value = newSeq });
cmd.Parameters.Add(new SqlParameter("@hash", SqlDbType.Binary, AuditChainHasher.HashLength) { Value = newHash });
if (oldSeq is not null)
{
cmd.Parameters.Add(new SqlParameter("@oldSeq", SqlDbType.BigInt) { Value = oldSeq.Value });
}
return await cmd.ExecuteNonQueryAsync(ct).ConfigureAwait(false) == 1;
}
/// <summary>
/// Reads one row selected as <see cref="RowColumns"/> (plus <c>ChainSeq, RowHash</c> when
/// <paramref name="withLink"/>), strictly in ordinal order so it is safe under SequentialAccess.
/// </summary>
internal static AuditChainRow ReadRow(DbDataReader reader, bool withLink)
{
// Ordinals follow RowColumns (+ ChainSeq, RowHash). Read strictly in order — the
// verification reader is opened with SequentialAccess.
var eventId = reader.GetGuid(0);
var occurred = DateTime.SpecifyKind(reader.GetDateTime(1), DateTimeKind.Utc);
var actor = reader.IsDBNull(2) ? null : reader.GetString(2);
var action = reader.GetString(3);
var outcome = reader.GetString(4);
var category = reader.GetString(5);
var target = reader.IsDBNull(6) ? null : reader.GetString(6);
var sourceNode = reader.IsDBNull(7) ? null : reader.GetString(7);
Guid? correlationId = reader.IsDBNull(8) ? null : reader.GetGuid(8);
var details = reader.IsDBNull(9) ? null : reader.GetString(9);
long? chainSeq = null;
byte[]? rowHash = null;
if (withLink)
{
chainSeq = reader.IsDBNull(10) ? null : reader.GetInt64(10);
rowHash = reader.IsDBNull(11) ? null : (byte[])reader.GetValue(11);
}
return new AuditChainRow(eventId, occurred, actor, action, outcome, category, target, sourceNode,
correlationId, details, chainSeq, rowHash);
}
private static DbCommand Command(DbConnection conn, DbTransaction tx, string sql)
{
var cmd = conn.CreateCommand();
cmd.Transaction = tx;
cmd.CommandText = sql;
return cmd;
}
private static void AddInt(DbCommand cmd, string name, int value)
=> cmd.Parameters.Add(new SqlParameter(name, SqlDbType.Int) { Value = value });
private static void AddDate(DbCommand cmd, string name, DateTime month)
=> cmd.Parameters.Add(new SqlParameter(name, SqlDbType.Date) { Value = month.Date });
private static void AddMonthRange(DbCommand cmd, DateTime month)
{
cmd.Parameters.Add(new SqlParameter("@monthStart", SqlDbType.DateTime2) { Scale = 7, Value = month });
cmd.Parameters.Add(new SqlParameter("@monthEnd", SqlDbType.DateTime2) { Scale = 7, Value = month.AddMonths(1) });
}
internal static async Task<bool> OpenAsync(DbConnection conn, CancellationToken ct)
{
if (conn.State == ConnectionState.Open)
{
return false;
}
await conn.OpenAsync(ct).ConfigureAwait(false);
return true;
}
}
@@ -12,16 +12,13 @@ namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance;
/// <remarks> /// <remarks>
/// <para> /// <para>
/// <b>Superseded stale archives.</b> A purge whose guard finds the partition changed after it /// <b>Superseded stale archives.</b> A purge whose guard finds the partition changed after it
/// was archived (51002/51003) purges nothing and leaves its archive at status /// was archived (51002) purges nothing and leaves its archive at status
/// <see cref="AuditArchiveStatus.Archived"/>; the next tick writes a fresh archive and purges /// <see cref="AuditArchiveStatus.Archived"/>; the next tick writes a fresh archive and purges
/// with it. The stale one is redundant only if a LATER archive B of the same partition, which /// with it. The stale one is redundant only if a LATER archive B of the same partition, which
/// is <see cref="AuditArchiveStatus.Purged"/> and verifies, holds everything the stale archive A /// is <see cref="AuditArchiveStatus.Purged"/> and verifies, holds everything the stale archive A
/// holds. That is proven, not assumed: for every chain month of A, B starts from the same /// holds. That is proven, not assumed: every row of A is found in B by EventId. Anything
/// earlier purge anchor and carries A's chain-end hash at A's chain-end sequence (as a row or a /// else — notably a row a per-channel purge removed in between — keeps A
/// tombstone) — so, the chain being a hash chain B itself verifies, every chained row of A is /// (<see cref="AuditArchiveCleanupAction.KeptStale"/>). An archive left at
/// in B; and every UNCHAINED row of A is found in B (row or tombstone) by EventId. Anything
/// else — notably an unchained row a per-channel purge removed in between, which leaves no
/// tombstone — keeps A (<see cref="AuditArchiveCleanupAction.KeptStale"/>). An archive left at
/// <c>Archived</c> because the node stopped between the switch and the manifest update has no /// <c>Archived</c> because the node stopped between the switch and the manifest update has no
/// later purged archive and is kept: it is the only copy. /// later purged archive and is kept: it is the only copy.
/// </para> /// </para>
@@ -31,8 +28,9 @@ namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance;
/// an <c>Archived</c> one — when its partition no longer holds rows in <c>dbo.AuditLog</c>. /// an <c>Archived</c> one — when its partition no longer holds rows in <c>dbo.AuditLog</c>.
/// </para> /// </para>
/// <para> /// <para>
/// <b>Safe deletion.</b> Only the three files a well-formed archive name implies /// <b>Safe deletion.</b> Only the files a well-formed archive name implies
/// (<c>{name}.manifest.json</c>, <c>{name}.parquet</c>, <c>{name}.tombstones.parquet</c>) in the /// (<c>{name}.manifest.json</c>, <c>{name}.parquet</c>, and a format-v1 archive's
/// <c>{name}.tombstones.parquet</c>) in the
/// archive's own <c>{Directory}/{YYYY}</c> folder are deleted — never a path read from the /// archive's own <c>{Directory}/{YYYY}</c> folder are deleted — never a path read from the
/// manifest — and the manifest goes FIRST, so an interrupted deletion leaves leftovers that are /// manifest — and the manifest goes FIRST, so an interrupted deletion leaves leftovers that are
/// no longer an archive rather than a manifest naming missing files. /// no longer an archive rather than a manifest naming missing files.
@@ -41,10 +39,10 @@ namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance;
public sealed partial class AuditLogPartitionArchive public sealed partial class AuditLogPartitionArchive
{ {
/// <summary> /// <summary>
/// Upper bound on unchained rows compared by EventId when proving a stale archive redundant; /// Upper bound on rows compared by EventId when proving a stale archive redundant;
/// a larger set keeps the archive rather than spend the memory. /// a larger archive is kept rather than spend the memory.
/// </summary> /// </summary>
internal const long MaxUnchainedRowsCompared = 5_000_000; internal const long MaxRowsCompared = 5_000_000;
/// <inheritdoc /> /// <inheritdoc />
public async Task<AuditArchiveCleanupResult> CleanupAsync(bool dryRun, CancellationToken ct = default) public async Task<AuditArchiveCleanupResult> CleanupAsync(bool dryRun, CancellationToken ct = default)
@@ -104,7 +102,7 @@ public sealed partial class AuditLogPartitionArchive
var now = _time.GetUtcNow().UtcDateTime; var now = _time.GetUtcNow().UtcDateTime;
foreach (var manifest in manifests.Where(m => !deleted.Contains(m.Name))) foreach (var manifest in manifests.Where(m => !deleted.Contains(m.Name)))
{ {
var monthEnd = AuditChainHasher.MonthOf(manifest.PartitionBoundaryUtc).AddMonths(1); var monthEnd = AuditArchiveParquet.MonthOf(manifest.PartitionBoundaryUtc).AddMonths(1);
if (monthEnd.AddDays(_options.RetentionDays) > now) if (monthEnd.AddDays(_options.RetentionDays) > now)
{ {
continue; continue;
@@ -230,102 +228,44 @@ public sealed partial class AuditLogPartitionArchive
/// </summary> /// </summary>
private async Task<string?> ProveCoveredAsync(AuditArchiveManifest stale, AuditArchiveManifest later, CancellationToken ct) private async Task<string?> ProveCoveredAsync(AuditArchiveManifest stale, AuditArchiveManifest later, CancellationToken ct)
{ {
// Same chain generation and at least as far, for every chain month the stale archive has. if (stale.RowCount > MaxRowsCompared)
var laterChains = later.Chains.ToDictionary(c => c.Partition, StringComparer.Ordinal);
var targets = new Dictionary<(DateTime Month, long Seq), string>();
foreach (var chain in stale.Chains)
{ {
if (!laterChains.TryGetValue(chain.Partition, out var next)) return $"{stale.RowCount} rows exceed the {MaxRowsCompared} compared by EventId.";
{
return $"{later.Name} has no chain for {chain.Partition}.";
}
if (next.PriorPurgedThroughSeq != chain.PriorPurgedThroughSeq || next.LastSeq < chain.LastSeq)
{
return $"{later.Name}'s chain for {chain.Partition} does not extend this archive's (prior anchor or end differs).";
}
if (chain.LastSeq > (chain.PriorPurgedThroughSeq ?? 0))
{
targets[(AuditArchiveParquet.ParseMonth(chain.Partition), chain.LastSeq)] = chain.LastHash.ToLowerInvariant();
}
} }
if (stale.UnchainedRowCount > MaxUnchainedRowsCompared) // The later archive must itself be intact.
{
return $"{stale.UnchainedRowCount} unchained rows exceed the {MaxUnchainedRowsCompared} compared by EventId.";
}
// The later archive must itself be intact and tied to the database.
var verification = await VerifyAsync(later.Name, ct).ConfigureAwait(false); var verification = await VerifyAsync(later.Name, ct).ConfigureAwait(false);
if (!verification.Verified) if (!verification.Verified)
{ {
return $"{later.Name} does not verify ({verification.FileProblem ?? "chain or anchor problem"})."; return $"{later.Name} does not verify ({verification.FileProblem}).";
} }
var directory = ArchiveDirectory(stale); var missing = new HashSet<Guid>();
var unchained = new HashSet<Guid>(); await using (var input = File.OpenRead(Path.Combine(ArchiveDirectory(stale), stale.Name + ".parquet")))
await using (var input = File.OpenRead(Path.Combine(directory, stale.Name + ".parquet")))
{ {
await foreach (var row in AuditArchiveParquet.ReadRowsAsync(input, ct).ConfigureAwait(false)) await foreach (var row in AuditArchiveParquet.ReadRowsAsync(input, ct).ConfigureAwait(false))
{ {
if (row.ChainSeq is null) missing.Add(row.EventId);
{
unchained.Add(row.EventId);
}
} }
} }
var laterDirectory = ArchiveDirectory(later); await using (var input = File.OpenRead(Path.Combine(ArchiveDirectory(later), later.Name + ".parquet")))
await using (var input = File.OpenRead(Path.Combine(laterDirectory, later.Name + ".parquet")))
{ {
await foreach (var row in AuditArchiveParquet.ReadRowsAsync(input, ct).ConfigureAwait(false)) await foreach (var row in AuditArchiveParquet.ReadRowsAsync(input, ct).ConfigureAwait(false))
{ {
unchained.Remove(row.EventId); missing.Remove(row.EventId);
if (row.ChainSeq is { } seq
&& targets.TryGetValue((AuditChainHasher.MonthOf(row.OccurredAtUtc), seq), out var expected))
{
if (row.RowHash is null || !string.Equals(Convert.ToHexStringLower(row.RowHash), expected, StringComparison.Ordinal))
{
return $"{later.Name} carries a different hash at the stale archive's chain end.";
}
targets.Remove((AuditChainHasher.MonthOf(row.OccurredAtUtc), seq));
}
} }
} }
await using (var input = File.OpenRead(Path.Combine(laterDirectory, later.Name + ".tombstones.parquet"))) return missing.Count == 0
{
await foreach (var tombstone in AuditArchiveParquet.ReadTombstonesAsync(input, ct).ConfigureAwait(false))
{
unchained.Remove(tombstone.EventId);
if (targets.TryGetValue((tombstone.ChainMonth, tombstone.ChainSeq), out var expected))
{
if (!string.Equals(Convert.ToHexStringLower(tombstone.RowHash), expected, StringComparison.Ordinal))
{
return $"{later.Name} carries a different hash at the stale archive's chain end.";
}
targets.Remove((tombstone.ChainMonth, tombstone.ChainSeq));
}
}
}
if (targets.Count > 0)
{
return $"{later.Name} does not contain the stale archive's chain end.";
}
return unchained.Count == 0
? null ? null
: $"{unchained.Count} unchained row(s) of this archive are not in {later.Name} (e.g. removed by a per-channel purge, which leaves no tombstone for an unchained row)."; : $"{missing.Count} row(s) of this archive are not in {later.Name} (e.g. removed by a per-channel purge in between).";
} }
private async Task<bool> PartitionHasRowsAsync(DateTime boundary, CancellationToken ct) private async Task<bool> PartitionHasRowsAsync(DateTime boundary, CancellationToken ct)
{ {
var conn = _context.Database.GetDbConnection(); var conn = _context.Database.GetDbConnection();
var openedHere = await AuditLogHashChain.OpenAsync(conn, ct).ConfigureAwait(false); var openedHere = await AuditArchiveParquet.OpenAsync(conn, ct).ConfigureAwait(false);
try try
{ {
await using var cmd = conn.CreateCommand(); await using var cmd = conn.CreateCommand();
@@ -354,7 +294,7 @@ public sealed partial class AuditLogPartitionArchive
} }
/// <summary> /// <summary>
/// Deletes exactly the archive's three files, manifest first. File names are derived from /// Deletes exactly the archive's files (a format-v1 archive also has a tombstone file), manifest first. File names are derived from
/// the validated archive name, never taken from the manifest. /// the validated archive name, never taken from the manifest.
/// </summary> /// </summary>
private void DeleteArchiveFiles(AuditArchiveManifest manifest) private void DeleteArchiveFiles(AuditArchiveManifest manifest)
@@ -21,8 +21,7 @@ namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance;
/// </summary> /// </summary>
/// <remarks> /// <remarks>
/// <para> /// <para>
/// <b>Layout.</b> <c>{Directory}/{YYYY}/{name}.parquet</c> (rows), /// <b>Layout.</b> <c>{Directory}/{YYYY}/{name}.parquet</c> (rows) and
/// <c>{name}.tombstones.parquet</c> (per-channel purge tombstones) and
/// <c>{name}.manifest.json</c>, where <c>name</c> is /// <c>{name}.manifest.json</c>, where <c>name</c> is
/// <c>auditlog-{YYYY-MM}-{archivedAt:yyyyMMddTHHmmssfff}Z</c>. Each file is written to a /// <c>auditlog-{YYYY-MM}-{archivedAt:yyyyMMddTHHmmssfff}Z</c>. Each file is written to a
/// <c>.tmp</c> sibling, flushed to disk and renamed; the manifest goes last, so a manifest /// <c>.tmp</c> sibling, flushed to disk and renamed; the manifest goes last, so a manifest
@@ -30,10 +29,9 @@ namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance;
/// new archive, and the superseded one keeps status <see cref="AuditArchiveStatus.Archived"/>. /// new archive, and the superseded one keeps status <see cref="AuditArchiveStatus.Archived"/>.
/// </para> /// </para>
/// <para> /// <para>
/// <b>Consistency with the hash chain.</b> The partition is read inside one transaction that /// <b>Consistency with the purge.</b> The partition is read inside one transaction; the purge
/// holds the chain lock SHARED, so no chaining pass or purge moves a head or writes a /// then re-counts the partition inside the switch transaction
/// tombstone while the rows, heads and tombstones are read. The purge then re-checks the /// (<see cref="AuditPartitionSwitchGuard"/>) and purges nothing when the count moved.
/// row count and heads under the EXCLUSIVE lock (<see cref="AuditPartitionSwitchGuard"/>).
/// </para> /// </para>
/// </remarks> /// </remarks>
public sealed partial class AuditLogPartitionArchive : IAuditLogArchive public sealed partial class AuditLogPartitionArchive : IAuditLogArchive
@@ -86,93 +84,27 @@ public sealed partial class AuditLogPartitionArchive : IAuditLogArchive
} }
var boundary = DateTime.SpecifyKind(partitionBoundaryUtc, DateTimeKind.Utc); var boundary = DateTime.SpecifyKind(partitionBoundaryUtc, DateTimeKind.Utc);
var partition = AuditChainHasher.PartitionLabel(AuditChainHasher.MonthOf(boundary)); var partition = AuditArchiveParquet.PartitionLabel(AuditArchiveParquet.MonthOf(boundary));
var archivedAt = _time.GetUtcNow().UtcDateTime; var archivedAt = _time.GetUtcNow().UtcDateTime;
var name = $"auditlog-{partition}-{archivedAt.ToString("yyyyMMdd'T'HHmmssfff", CultureInfo.InvariantCulture)}Z"; var name = $"auditlog-{partition}-{archivedAt.ToString("yyyyMMdd'T'HHmmssfff", CultureInfo.InvariantCulture)}Z";
var directory = Path.Combine(_options.Directory!, partition[..4]); var directory = Path.Combine(_options.Directory!, partition[..4]);
Directory.CreateDirectory(directory); Directory.CreateDirectory(directory);
var dataFile = name + ".parquet"; var dataFile = name + ".parquet";
var tombstoneFile = name + ".tombstones.parquet";
var dataTmp = Path.Combine(directory, dataFile + ".tmp"); var dataTmp = Path.Combine(directory, dataFile + ".tmp");
var tombstoneTmp = Path.Combine(directory, tombstoneFile + ".tmp");
var chains = new List<AuditArchiveChainState>(); long rowCount = 0;
long rowCount = 0, chained = 0;
DateTime? minOccurred = null, maxOccurred = null; DateTime? minOccurred = null, maxOccurred = null;
string dataSha, tombstoneSha; string dataSha;
long dataBytes, tombstoneCount; long dataBytes;
try try
{ {
var conn = _context.Database.GetDbConnection(); var conn = _context.Database.GetDbConnection();
var openedHere = await AuditLogHashChain.OpenAsync(conn, ct).ConfigureAwait(false); var openedHere = await AuditArchiveParquet.OpenAsync(conn, ct).ConfigureAwait(false);
try try
{ {
await using var tx = await conn.BeginTransactionAsync(IsolationLevel.ReadCommitted, ct).ConfigureAwait(false); await using var tx = await conn.BeginTransactionAsync(IsolationLevel.ReadCommitted, ct).ConfigureAwait(false);
if (!await AuditLogHashChain.TryAcquireLockAsync(
conn, tx, "Shared", TimeSpan.FromSeconds(Math.Max(1, _options.ChainLockTimeoutSeconds)), ct)
.ConfigureAwait(false))
{
await tx.RollbackAsync(ct).ConfigureAwait(false);
throw new TimeoutException(
$"The AuditLog hash-chain lock stayed busy for {_options.ChainLockTimeoutSeconds}s; partition {partition} not archived this tick.");
}
// 1. Chain heads of every month the partition holds (normally exactly one).
var tombstoneCounts = new Dictionary<DateTime, long>();
var heads = new List<(DateTime Month, long LastSeq, byte[] LastHash, long? PurgedSeq, byte[]? PurgedHash)>();
await using (var cmd = Command(conn, tx,
"SELECT ChainMonth, LastSeq, LastHash, PurgedThroughSeq, PurgedThroughHash FROM dbo.AuditLogChainHead " +
"WHERE $partition.pf_AuditLog_Month(CAST(ChainMonth AS datetime2(7))) = $partition.pf_AuditLog_Month(@boundary) " +
"ORDER BY ChainMonth;", boundary))
{
await using var reader = await cmd.ExecuteReaderAsync(ct).ConfigureAwait(false);
while (await reader.ReadAsync(ct).ConfigureAwait(false))
{
heads.Add((
DateTime.SpecifyKind(reader.GetDateTime(0), DateTimeKind.Utc),
reader.GetInt64(1),
(byte[])reader.GetValue(2),
reader.IsDBNull(3) ? null : reader.GetInt64(3),
reader.IsDBNull(4) ? null : (byte[])reader.GetValue(4)));
}
}
// 2. Per-channel purge tombstones (verification bridges gaps with them).
await using (var file = NewFile(tombstoneTmp))
{
var hashing = new HashingWriteStream(file);
await using (var writer = await AuditArchiveParquet
.CreateTombstoneWriterAsync(hashing, partition, _options.RowGroupSize, ct).ConfigureAwait(false))
{
await using var cmd = Command(conn, tx,
"SELECT ChainMonth, ChainSeq, RowHash, EventId, PurgedAtUtc FROM dbo.AuditLogChainTombstone " +
"WHERE $partition.pf_AuditLog_Month(CAST(ChainMonth AS datetime2(7))) = $partition.pf_AuditLog_Month(@boundary) " +
"ORDER BY ChainMonth, ChainSeq;", boundary);
await using var reader = await cmd.ExecuteReaderAsync(ct).ConfigureAwait(false);
while (await reader.ReadAsync(ct).ConfigureAwait(false))
{
var tombstone = new AuditArchiveTombstone(
DateTime.SpecifyKind(reader.GetDateTime(0), DateTimeKind.Utc),
reader.GetInt64(1),
(byte[])reader.GetValue(2),
reader.GetGuid(3),
DateTime.SpecifyKind(reader.GetDateTime(4), DateTimeKind.Utc));
tombstoneCounts[tombstone.ChainMonth] = tombstoneCounts.GetValueOrDefault(tombstone.ChainMonth) + 1;
await writer.AddAsync(tombstone, ct).ConfigureAwait(false);
}
tombstoneCount = writer.Count;
}
await hashing.FlushAsync(ct).ConfigureAwait(false);
file.Flush(flushToDisk: true);
tombstoneSha = hashing.HashHex();
}
// 3. The rows, grouped by chain month and in chain order within it (unchained
// rows last), which is the order verification needs.
await using (var file = NewFile(dataTmp)) await using (var file = NewFile(dataTmp))
{ {
var hashing = new HashingWriteStream(file); var hashing = new HashingWriteStream(file);
@@ -180,20 +112,14 @@ public sealed partial class AuditLogPartitionArchive : IAuditLogArchive
.CreateDataWriterAsync(hashing, partition, _options.RowGroupSize, ct).ConfigureAwait(false)) .CreateDataWriterAsync(hashing, partition, _options.RowGroupSize, ct).ConfigureAwait(false))
{ {
await using var cmd = Command(conn, tx, await using var cmd = Command(conn, tx,
$"SELECT {AuditLogHashChain.RowColumns}, ChainSeq, RowHash FROM dbo.AuditLog " + $"SELECT {AuditArchiveParquet.RowColumns} FROM dbo.AuditLog " +
"WHERE $PARTITION.pf_AuditLog_Month(OccurredAtUtc) = $partition.pf_AuditLog_Month(@boundary) " + "WHERE $PARTITION.pf_AuditLog_Month(OccurredAtUtc) = $partition.pf_AuditLog_Month(@boundary) " +
"ORDER BY DATEFROMPARTS(YEAR(OccurredAtUtc), MONTH(OccurredAtUtc), 1), " + "ORDER BY OccurredAtUtc, EventId;", boundary);
"CASE WHEN ChainSeq IS NULL THEN 1 ELSE 0 END, ChainSeq, OccurredAtUtc, EventId;", boundary);
cmd.CommandTimeout = Math.Max(1, _options.ReadCommandTimeoutMinutes) * 60; cmd.CommandTimeout = Math.Max(1, _options.ReadCommandTimeoutMinutes) * 60;
await using var reader = await cmd.ExecuteReaderAsync(CommandBehavior.SequentialAccess, ct).ConfigureAwait(false); await using var reader = await cmd.ExecuteReaderAsync(CommandBehavior.SequentialAccess, ct).ConfigureAwait(false);
while (await reader.ReadAsync(ct).ConfigureAwait(false)) while (await reader.ReadAsync(ct).ConfigureAwait(false))
{ {
var row = AuditLogHashChain.ReadRow(reader, withLink: true); var row = AuditArchiveParquet.ReadRow(reader);
if (row.ChainSeq is not null)
{
chained++;
}
minOccurred = minOccurred is { } lo && lo <= row.OccurredAtUtc ? lo : row.OccurredAtUtc; minOccurred = minOccurred is { } lo && lo <= row.OccurredAtUtc ? lo : row.OccurredAtUtc;
maxOccurred = maxOccurred is { } hi && hi >= row.OccurredAtUtc ? hi : row.OccurredAtUtc; maxOccurred = maxOccurred is { } hi && hi >= row.OccurredAtUtc ? hi : row.OccurredAtUtc;
await writer.AddAsync(row, ct).ConfigureAwait(false); await writer.AddAsync(row, ct).ConfigureAwait(false);
@@ -209,17 +135,6 @@ public sealed partial class AuditLogPartitionArchive : IAuditLogArchive
} }
await tx.CommitAsync(ct).ConfigureAwait(false); await tx.CommitAsync(ct).ConfigureAwait(false);
foreach (var head in heads)
{
chains.Add(new AuditArchiveChainState(
AuditChainHasher.PartitionLabel(head.Month),
head.LastSeq,
Convert.ToHexStringLower(head.LastHash),
head.PurgedSeq,
head.PurgedHash is null ? null : Convert.ToHexStringLower(head.PurgedHash),
tombstoneCounts.GetValueOrDefault(head.Month)));
}
} }
finally finally
{ {
@@ -230,12 +145,10 @@ public sealed partial class AuditLogPartitionArchive : IAuditLogArchive
} }
File.Move(dataTmp, Path.Combine(directory, dataFile)); File.Move(dataTmp, Path.Combine(directory, dataFile));
File.Move(tombstoneTmp, Path.Combine(directory, tombstoneFile));
} }
catch catch
{ {
TryDelete(dataTmp); TryDelete(dataTmp);
TryDelete(tombstoneTmp);
throw; throw;
} }
@@ -248,22 +161,16 @@ public sealed partial class AuditLogPartitionArchive : IAuditLogArchive
AuditArchiveStatus.Archived, AuditArchiveStatus.Archived,
PurgedAtUtc: null, PurgedAtUtc: null,
rowCount, rowCount,
chained,
rowCount - chained,
minOccurred, minOccurred,
maxOccurred, maxOccurred,
dataFile, dataFile,
dataSha, dataSha,
dataBytes, dataBytes);
tombstoneFile,
tombstoneSha,
tombstoneCount,
chains);
await WriteManifestAsync(directory, manifest, ct).ConfigureAwait(false); await WriteManifestAsync(directory, manifest, ct).ConfigureAwait(false);
_logger.LogInformation( _logger.LogInformation(
"Archived AuditLog partition {Partition} to {Archive}: {Rows} rows ({Chained} chained), {Tombstones} tombstones, {Bytes} bytes.", "Archived AuditLog partition {Partition} to {Archive}: {Rows} rows, {Bytes} bytes.",
partition, name, rowCount, chained, tombstoneCount, dataBytes); partition, name, rowCount, dataBytes);
return manifest; return manifest;
} }
@@ -272,9 +179,7 @@ public sealed partial class AuditLogPartitionArchive : IAuditLogArchive
AuditArchiveManifest manifest, TimeSpan? commandTimeout = null, CancellationToken ct = default) AuditArchiveManifest manifest, TimeSpan? commandTimeout = null, CancellationToken ct = default)
{ {
ArgumentNullException.ThrowIfNull(manifest); ArgumentNullException.ThrowIfNull(manifest);
var guard = new AuditPartitionSwitchGuard( var guard = new AuditPartitionSwitchGuard(manifest.RowCount);
manifest.RowCount,
manifest.Chains.Select(c => (AuditArchiveParquet.ParseMonth(c.Partition), c.LastSeq)).ToList());
long purged; long purged;
try try
@@ -283,8 +188,7 @@ public sealed partial class AuditLogPartitionArchive : IAuditLogArchive
.SwitchOutPartitionAsync(manifest.PartitionBoundaryUtc, guard, commandTimeout, ct) .SwitchOutPartitionAsync(manifest.PartitionBoundaryUtc, guard, commandTimeout, ct)
.ConfigureAwait(false); .ConfigureAwait(false);
} }
catch (Exception ex) when (FindSqlError(ex) is { } number catch (Exception ex) when (FindSqlError(ex) is AuditPartitionSwitchGuard.RowCountChangedError)
&& number is AuditPartitionSwitchGuard.RowCountChangedError or AuditPartitionSwitchGuard.ChainAdvancedError)
{ {
throw new AuditArchiveStaleException( throw new AuditArchiveStaleException(
$"Partition {manifest.Partition} changed after archive {manifest.Name} was written; nothing was purged, " $"Partition {manifest.Partition} changed after archive {manifest.Name} was written; nothing was purged, "
@@ -302,8 +206,7 @@ public sealed partial class AuditLogPartitionArchive : IAuditLogArchive
} }
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException) catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
{ {
// The rows are gone and the archive files are complete; only the status flag is // The rows are gone and the archive file is complete; only the status flag is stale.
// stale. Verify still ties the archive to the purge anchor (anchor Matches).
_logger.LogError(ex, _logger.LogError(ex,
"AuditLog partition {Partition} was purged but archive {Archive}'s manifest could not be marked Purged.", "AuditLog partition {Partition} was purged but archive {Archive}'s manifest could not be marked Purged.",
manifest.Partition, manifest.Name); manifest.Partition, manifest.Name);
@@ -365,85 +268,20 @@ public sealed partial class AuditLogPartitionArchive : IAuditLogArchive
var manifest = await ReadManifestAsync(manifestPath, ct).ConfigureAwait(false); var manifest = await ReadManifestAsync(manifestPath, ct).ConfigureAwait(false);
var problems = new List<string>(); var problems = new List<string>();
var dataPath = Path.Combine(directory, Path.GetFileName(manifest.DataFile)); var dataPath = Path.Combine(directory, Path.GetFileName(manifest.DataFile));
var tombstonePath = Path.Combine(directory, Path.GetFileName(manifest.TombstoneFile));
await CheckFileAsync(dataPath, manifest.DataSha256, manifest.DataBytes, problems, ct).ConfigureAwait(false); await CheckFileAsync(dataPath, manifest.DataSha256, manifest.DataBytes, problems, ct).ConfigureAwait(false);
await CheckFileAsync(tombstonePath, manifest.TombstoneSha256, null, problems, ct).ConfigureAwait(false);
if (problems.Count > 0) if (problems.Count > 0)
{ {
return new AuditArchiveVerificationResult( return new AuditArchiveVerificationResult(
manifest.Name, manifest.Partition, manifest.Status, Verified: false, FilesIntact: false, manifest.Name, manifest.Partition, manifest.Status, Verified: false, FilesIntact: false,
string.Join(" ", problems), RowsRead: 0, []); string.Join(" ", problems), RowsRead: 0);
}
// Tombstones per month, then one streaming verifier per chain month.
var tombstones = new Dictionary<DateTime, Dictionary<long, byte[]>>();
long tombstonesRead = 0;
DateTime? chainFrom = null;
await using (var input = File.OpenRead(tombstonePath))
{
await foreach (var t in AuditArchiveParquet.ReadTombstonesAsync(input, ct).ConfigureAwait(false))
{
if (!tombstones.TryGetValue(t.ChainMonth, out var byMonth))
{
tombstones[t.ChainMonth] = byMonth = [];
}
byMonth[t.ChainSeq] = t.RowHash;
tombstonesRead++;
if (t.ChainSeq == AuditChainHasher.CutoffAnchorSeq)
{
// The chain-start anchor (ScadaBridge#139) travels with the archive of its month.
chainFrom = chainFrom is { } seen && seen <= t.PurgedAtUtc ? seen : t.PurgedAtUtc;
}
}
}
// Otherwise the cutoff comes from the database's anchor, which outlives every purge.
chainFrom ??= await ReadChainFromAsync(ct).ConfigureAwait(false);
var states = manifest.Chains.ToDictionary(c => AuditArchiveParquet.ParseMonth(c.Partition));
var verifiers = new SortedDictionary<DateTime, AuditChainVerifier>();
var unchained = new Dictionary<DateTime, long>();
var preCutoff = new Dictionary<DateTime, long>();
AuditChainVerifier VerifierFor(DateTime month)
{
if (!verifiers.TryGetValue(month, out var verifier))
{
AuditChainHeadState? head = states.TryGetValue(month, out var s)
? new AuditChainHeadState(
s.LastSeq,
Convert.FromHexString(s.LastHash),
s.PriorPurgedThroughSeq,
s.PriorPurgedThroughHash is null ? null : Convert.FromHexString(s.PriorPurgedThroughHash))
: null;
verifier = new AuditChainVerifier(month, head, tombstones.GetValueOrDefault(month) ?? [], chainFrom);
verifiers[month] = verifier;
}
return verifier;
}
foreach (var month in states.Keys)
{
VerifierFor(month);
} }
long rowsRead = 0; long rowsRead = 0;
await using (var input = File.OpenRead(dataPath)) await using (var input = File.OpenRead(dataPath))
{ {
await foreach (var row in AuditArchiveParquet.ReadRowsAsync(input, ct).ConfigureAwait(false)) await foreach (var _ in AuditArchiveParquet.ReadRowsAsync(input, ct).ConfigureAwait(false))
{ {
rowsRead++; rowsRead++;
var month = AuditChainHasher.MonthOf(row.OccurredAtUtc);
if (row.ChainSeq is null)
{
var bucket = chainFrom is { } cutoff && row.OccurredAtUtc < cutoff ? preCutoff : unchained;
bucket[month] = bucket.GetValueOrDefault(month) + 1;
VerifierFor(month);
continue;
}
VerifierFor(month).Accept(row);
} }
} }
@@ -452,126 +290,10 @@ public sealed partial class AuditLogPartitionArchive : IAuditLogArchive
problems.Add($"The data file holds {rowsRead} rows; the manifest records {manifest.RowCount}."); problems.Add($"The data file holds {rowsRead} rows; the manifest records {manifest.RowCount}.");
} }
if (tombstonesRead != manifest.TombstoneCount)
{
problems.Add($"The tombstone file holds {tombstonesRead} tombstones; the manifest records {manifest.TombstoneCount}.");
}
var anchors = await ReadAnchorsAsync(verifiers.Keys, ct).ConfigureAwait(false);
var results = new List<AuditArchiveChainVerification>();
foreach (var (month, verifier) in verifiers)
{
var chain = verifier.Complete(unchained.GetValueOrDefault(month), preCutoff.GetValueOrDefault(month));
var (anchor, detail) = CompareAnchor(states.GetValueOrDefault(month), anchors.GetValueOrDefault(month));
results.Add(new AuditArchiveChainVerification(chain, anchor, detail));
}
var filesIntact = problems.Count == 0; var filesIntact = problems.Count == 0;
var verified = filesIntact
&& results.All(r => r.Chain.Status != AuditChainStatus.Broken && r.Anchor != AuditArchiveAnchorStatus.Mismatch);
return new AuditArchiveVerificationResult( return new AuditArchiveVerificationResult(
manifest.Name, manifest.Partition, manifest.Status, verified, filesIntact, manifest.Name, manifest.Partition, manifest.Status, filesIntact, filesIntact,
filesIntact ? null : string.Join(" ", problems), rowsRead, results); filesIntact ? null : string.Join(" ", problems), rowsRead);
}
/// <summary>
/// Compares an archived chain end with the database's current checkpoint anchor for the month.
/// </summary>
internal static (AuditArchiveAnchorStatus Status, string Detail) CompareAnchor(
AuditArchiveChainState? archived, (bool HeadExists, long? PurgedSeq, byte[]? PurgedHash) database)
{
if (archived is null)
{
// No chain head existed when the rows were archived (chaining off, or the month was
// never reached): nothing to tie. A later anchor can only come from a later purge.
return database.PurgedSeq is null
? (AuditArchiveAnchorStatus.Matches, "No hash chain existed for this month when it was archived.")
: (AuditArchiveAnchorStatus.Superseded,
$"No chain at archive time; a later purge anchored the month at ChainSeq {database.PurgedSeq}.");
}
if (!database.HeadExists)
{
return (AuditArchiveAnchorStatus.Mismatch,
$"The archive records a chain through ChainSeq {archived.LastSeq} but the database has no chain head for {archived.Partition}.");
}
if (database.PurgedSeq is null)
{
return (AuditArchiveAnchorStatus.NotPurged,
$"{archived.Partition} has not been purged: the archived rows are still in dbo.AuditLog.");
}
if (database.PurgedSeq == archived.LastSeq)
{
return database.PurgedHash is not null
&& Convert.ToHexStringLower(database.PurgedHash) == archived.LastHash.ToLowerInvariant()
? (AuditArchiveAnchorStatus.Matches,
$"The archived chain ends at the purge anchor (ChainSeq {archived.LastSeq}).")
: (AuditArchiveAnchorStatus.Mismatch,
$"The purge anchor is at ChainSeq {archived.LastSeq} but its hash differs from the archive's chain end.");
}
return database.PurgedSeq > archived.LastSeq
? (AuditArchiveAnchorStatus.Superseded,
$"The purge anchor (ChainSeq {database.PurgedSeq}) is past this archive's chain end ({archived.LastSeq}): "
+ "late rows were purged and archived again afterwards.")
: (AuditArchiveAnchorStatus.Mismatch,
$"The purge anchor (ChainSeq {database.PurgedSeq}) is before this archive's chain end ({archived.LastSeq}).");
}
/// <summary>The database's chain cutoff (ScadaBridge#139), or null when the chain has none.</summary>
private async Task<DateTime?> ReadChainFromAsync(CancellationToken ct)
{
var conn = _context.Database.GetDbConnection();
var openedHere = await AuditLogHashChain.OpenAsync(conn, ct).ConfigureAwait(false);
try
{
await using var cmd = conn.CreateCommand();
cmd.CommandText = "SELECT MIN(PurgedAtUtc) FROM dbo.AuditLogChainTombstone WHERE ChainSeq = 0;";
return await cmd.ExecuteScalarAsync(ct).ConfigureAwait(false) is DateTime dt
? DateTime.SpecifyKind(dt, DateTimeKind.Utc)
: null;
}
finally
{
if (openedHere)
{
await conn.CloseAsync().ConfigureAwait(false);
}
}
}
private async Task<Dictionary<DateTime, (bool HeadExists, long? PurgedSeq, byte[]? PurgedHash)>> ReadAnchorsAsync(
IEnumerable<DateTime> months, CancellationToken ct)
{
var result = new Dictionary<DateTime, (bool, long?, byte[]?)>();
var conn = _context.Database.GetDbConnection();
var openedHere = await AuditLogHashChain.OpenAsync(conn, ct).ConfigureAwait(false);
try
{
foreach (var month in months)
{
await using var cmd = conn.CreateCommand();
cmd.CommandText = "SELECT PurgedThroughSeq, PurgedThroughHash FROM dbo.AuditLogChainHead WHERE ChainMonth = @month;";
cmd.Parameters.Add(new SqlParameter("@month", SqlDbType.Date) { Value = month.Date });
await using var reader = await cmd.ExecuteReaderAsync(ct).ConfigureAwait(false);
result[month] = await reader.ReadAsync(ct).ConfigureAwait(false)
? (true,
reader.IsDBNull(0) ? null : reader.GetInt64(0),
reader.IsDBNull(1) ? null : (byte[])reader.GetValue(1))
: (false, null, null);
}
}
finally
{
if (openedHere)
{
await conn.CloseAsync().ConfigureAwait(false);
}
}
return result;
} }
private static async Task CheckFileAsync(string path, string expectedSha, long? expectedBytes, List<string> problems, CancellationToken ct) private static async Task CheckFileAsync(string path, string expectedSha, long? expectedBytes, List<string> problems, CancellationToken ct)
@@ -1,83 +0,0 @@
using Microsoft.AspNetCore.DataProtection;
using Microsoft.EntityFrameworkCore;
using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories;
namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance;
/// <summary>
/// The connection the AuditLog maintenance paths run on — the hash-chain job and both purge
/// paths (partition switch-out with its archive, per-channel DELETE) — ScadaBridge#107 item 3.
/// </summary>
/// <remarks>
/// <para>
/// With <c>AuditLog:MaintenanceConnectionString</c> unset (the default), this is the scope's
/// ordinary <see cref="ScadaBridgeDbContext"/>: one login for everything, exactly as before.
/// With it set, the maintenance paths get their OWN context on that connection string, so a
/// DBA can give the runtime (writer) login only <c>scadabridge_audit_writer</c> — whose DENYs
/// stop it writing chain state or deleting audit rows — and a separate maintenance login the
/// <c>scadabridge_audit_chainer</c> + <c>scadabridge_audit_purger</c> roles. The string is read
/// after the pre-host <c>${secret:}</c> expansion, so it may (and in production should) be a
/// secret reference.
/// </para>
/// <para>Scoped: an owned context is disposed with the scope; a borrowed one is left to DI.</para>
/// </remarks>
public sealed class AuditMaintenanceContext : IAsyncDisposable, IDisposable
{
/// <summary>DI key of the maintenance-login <c>IAuditLogRepository</c> and <c>IAuditLogArchive</c>.</summary>
public const string ServiceKey = AuditLogServiceKeys.Maintenance;
private readonly bool _owned;
private AuditMaintenanceContext(ScadaBridgeDbContext context, bool owned)
{
Context = context;
_owned = owned;
}
/// <summary>The context to run maintenance SQL on.</summary>
public ScadaBridgeDbContext Context { get; }
/// <summary>True when <see cref="Context"/> is on the separate maintenance connection string.</summary>
public bool UsesSeparateLogin => _owned;
/// <summary>Wraps the scope's ordinary context (no separate maintenance login configured).</summary>
/// <param name="context">The scope's context.</param>
/// <returns>The wrapper.</returns>
public static AuditMaintenanceContext Shared(ScadaBridgeDbContext context)
=> new(context ?? throw new ArgumentNullException(nameof(context)), owned: false);
/// <summary>Opens an owned context on the maintenance connection string.</summary>
/// <param name="connectionString">The maintenance connection string.</param>
/// <param name="protectionProvider">Data protection for secret-bearing columns (same as the runtime context).</param>
/// <returns>The wrapper; disposing it disposes the context.</returns>
public static AuditMaintenanceContext Separate(string connectionString, IDataProtectionProvider? protectionProvider)
{
ArgumentException.ThrowIfNullOrWhiteSpace(connectionString);
var options = new DbContextOptionsBuilder<ScadaBridgeDbContext>()
.UseSqlServer(connectionString, sql => sql.EnableRetryOnFailure(
maxRetryCount: 5, maxRetryDelay: TimeSpan.FromSeconds(30), errorNumbersToAdd: null))
.ConfigureWarnings(w => w.Ignore(
Microsoft.EntityFrameworkCore.Diagnostics.RelationalEventId.PendingModelChangesWarning))
.Options;
var context = protectionProvider is null
? new ScadaBridgeDbContext(options)
: new ScadaBridgeDbContext(options, protectionProvider);
return new AuditMaintenanceContext(context, owned: true);
}
/// <inheritdoc />
public ValueTask DisposeAsync() => _owned ? Context.DisposeAsync() : ValueTask.CompletedTask;
/// <inheritdoc />
public void Dispose()
{
if (_owned)
{
Context.Dispose();
}
}
}
/// <summary>The configured maintenance connection string (null = use the runtime connection).</summary>
/// <param name="ConnectionString">The connection string, or null.</param>
public sealed record AuditMaintenanceConnection(string? ConnectionString);
@@ -8,49 +8,28 @@ namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance;
/// partition-switch transaction so the purge drops exactly the rows the archive holds. /// partition-switch transaction so the purge drops exactly the rows the archive holds.
/// </summary> /// </summary>
/// <param name="ExpectedRows">Rows the archive holds for the partition.</param> /// <param name="ExpectedRows">Rows the archive holds for the partition.</param>
/// <param name="ExpectedHeads">Each chain month's <c>LastSeq</c> at archive time.</param> public sealed record AuditPartitionSwitchGuard(long ExpectedRows)
public sealed record AuditPartitionSwitchGuard(long ExpectedRows, IReadOnlyList<(DateTime ChainMonth, long LastSeq)> ExpectedHeads)
{ {
/// <summary>SQL error number THROWn when the partition row count changed.</summary> /// <summary>SQL error number THROWn when the partition row count changed.</summary>
public const int RowCountChangedError = 51002; public const int RowCountChangedError = 51002;
/// <summary>SQL error number THROWn when a chain head in the partition changed.</summary>
public const int ChainAdvancedError = 51003;
/// <summary> /// <summary>
/// Renders the guard as T-SQL for the switch batch. Every value is a number or a /// Renders the guard as T-SQL for the switch batch. The only value is a number produced
/// <c>yyyy-MM-dd</c> date produced here, so inlining them as literals is injection-safe and /// here, so inlining it as a literal is injection-safe and keeps the switch a
/// keeps the switch a parameterless <c>ExecuteSqlRaw</c> batch. /// parameterless <c>ExecuteSqlRaw</c> batch.
/// </summary> /// </summary>
/// <param name="monthBoundaryLiteral">The boundary literal the switch batch already uses.</param> /// <param name="monthBoundaryLiteral">The boundary literal the switch batch already uses.</param>
/// <returns>The guard statements (run after the chain lock, inside the TRY).</returns> /// <returns>The guard statements (run inside the switch TRY, before the SWITCH).</returns>
internal string ToSql(string monthBoundaryLiteral) internal string ToSql(string monthBoundaryLiteral)
{ {
var sql = new StringBuilder(); var sql = new StringBuilder();
sql.AppendLine(); sql.AppendLine();
sql.AppendLine(" -- 0b. Archive guard (ScadaBridge#42): the archive must hold exactly the rows this"); sql.AppendLine(" -- 0. Archive guard (ScadaBridge#42): the archive must hold exactly the rows this");
sql.AppendLine(" -- switch drops. Under the exclusive chain lock, so nothing chains or per-channel"); sql.AppendLine(" -- switch drops.");
sql.AppendLine(" -- purges between this check and the SWITCH.");
sql.AppendLine(CultureInfo.InvariantCulture, $" DECLARE @guardPartition int = $partition.pf_AuditLog_Month('{monthBoundaryLiteral}');"); sql.AppendLine(CultureInfo.InvariantCulture, $" DECLARE @guardPartition int = $partition.pf_AuditLog_Month('{monthBoundaryLiteral}');");
sql.AppendLine(" IF (SELECT COUNT_BIG(*) FROM dbo.AuditLog WHERE $PARTITION.pf_AuditLog_Month(OccurredAtUtc) = @guardPartition)"); sql.AppendLine(" IF (SELECT COUNT_BIG(*) FROM dbo.AuditLog WHERE $PARTITION.pf_AuditLog_Month(OccurredAtUtc) = @guardPartition)");
sql.AppendLine(CultureInfo.InvariantCulture, $" <> {ExpectedRows}"); sql.AppendLine(CultureInfo.InvariantCulture, $" <> {ExpectedRows}");
sql.AppendLine(CultureInfo.InvariantCulture, $" THROW {RowCountChangedError}, 'AuditLog archive is stale: the partition row count changed after it was archived.', 1;"); sql.AppendLine(CultureInfo.InvariantCulture, $" THROW {RowCountChangedError}, 'AuditLog archive is stale: the partition row count changed after it was archived.', 1;");
sql.AppendLine(" DECLARE @guardHeads TABLE (ChainMonth date NOT NULL PRIMARY KEY, LastSeq bigint NOT NULL);");
foreach (var (month, lastSeq) in ExpectedHeads)
{
sql.AppendLine(CultureInfo.InvariantCulture,
$" INSERT INTO @guardHeads (ChainMonth, LastSeq) VALUES ('{month:yyyy-MM-dd}', {lastSeq});");
}
sql.AppendLine(" IF EXISTS (");
sql.AppendLine(" SELECT h.ChainMonth, h.LastSeq FROM dbo.AuditLogChainHead h");
sql.AppendLine(" WHERE $partition.pf_AuditLog_Month(CAST(h.ChainMonth AS datetime2(7))) = @guardPartition");
sql.AppendLine(" EXCEPT SELECT ChainMonth, LastSeq FROM @guardHeads)");
sql.AppendLine(" OR EXISTS (");
sql.AppendLine(" SELECT ChainMonth, LastSeq FROM @guardHeads");
sql.AppendLine(" EXCEPT SELECT h.ChainMonth, h.LastSeq FROM dbo.AuditLogChainHead h");
sql.AppendLine(" WHERE $partition.pf_AuditLog_Month(CAST(h.ChainMonth AS datetime2(7))) = @guardPartition)");
sql.AppendLine(CultureInfo.InvariantCulture, $" THROW {ChainAdvancedError}, 'AuditLog archive is stale: the hash chain advanced after it was archived.', 1;");
return sql.ToString(); return sql.ToString();
} }
} }
@@ -69,8 +69,11 @@ CREATE NONCLUSTERED INDEX IX_AuditLog_ParentExecution ON dbo.AuditLog (ParentExe
CREATE NONCLUSTERED INDEX IX_AuditLog_Node_Occurred ON dbo.AuditLog (SourceNode, OccurredAtUtc) ON ps_AuditLog_Month(OccurredAtUtc); CREATE NONCLUSTERED INDEX IX_AuditLog_Node_Occurred ON dbo.AuditLog (SourceNode, OccurredAtUtc) ON ps_AuditLog_Month(OccurredAtUtc);
CREATE NONCLUSTERED INDEX IX_AuditLog_Kind_Occurred ON dbo.AuditLog (Kind ASC, OccurredAtUtc DESC) ON ps_AuditLog_Month(OccurredAtUtc); CREATE NONCLUSTERED INDEX IX_AuditLog_Kind_Occurred ON dbo.AuditLog (Kind ASC, OccurredAtUtc DESC) ON ps_AuditLog_Month(OccurredAtUtc);
CREATE NONCLUSTERED INDEX IX_AuditLog_Actor_Occurred ON dbo.AuditLog (Actor ASC, OccurredAtUtc DESC) ON ps_AuditLog_Month(OccurredAtUtc); CREATE NONCLUSTERED INDEX IX_AuditLog_Actor_Occurred ON dbo.AuditLog (Actor ASC, OccurredAtUtc DESC) ON ps_AuditLog_Month(OccurredAtUtc);
CREATE NONCLUSTERED INDEX IX_AuditLog_Unchained ON dbo.AuditLog (OccurredAtUtc, EventId) WHERE ChainSeq IS NULL ON ps_AuditLog_Month(OccurredAtUtc); -- The two hash-chain indexes go through EXEC (compiled only when run): RemoveAuditLogHashChain
CREATE NONCLUSTERED INDEX IX_AuditLog_ChainSeq ON dbo.AuditLog (ChainSeq) WHERE ChainSeq IS NOT NULL ON ps_AuditLog_Month(OccurredAtUtc);"; -- (2026-11-15) drops ChainSeq, and the idempotent script compiles this migration's batch against
-- that schema on a re-run, where a direct reference is Msg 207 (ScadaBridge#126). Same indexes.
EXEC(N'CREATE NONCLUSTERED INDEX IX_AuditLog_Unchained ON dbo.AuditLog (OccurredAtUtc, EventId) WHERE ChainSeq IS NULL ON ps_AuditLog_Month(OccurredAtUtc);');
EXEC(N'CREATE NONCLUSTERED INDEX IX_AuditLog_ChainSeq ON dbo.AuditLog (ChainSeq) WHERE ChainSeq IS NOT NULL ON ps_AuditLog_Month(OccurredAtUtc);');";
/// <summary>Drops every non-clustered index on dbo.AuditLog (the twelve above plus the B2 unique index), each existence-guarded.</summary> /// <summary>Drops every non-clustered index on dbo.AuditLog (the twelve above plus the B2 unique index), each existence-guarded.</summary>
internal const string DropNonClusteredIndexesSql = @" internal const string DropNonClusteredIndexesSql = @"
@@ -0,0 +1,153 @@
using Microsoft.EntityFrameworkCore.Migrations;
#nullable disable
namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Migrations
{
/// <summary>
/// Removes the AuditLog hash chain (ScadaBridge#41, #107, #139) and the two-login maintenance
/// hardening (#113), at IT security's request (2026-11-15), pending a family-wide general
/// solution. Drops what <c>AddAuditLogHashChain</c> and <c>AuditMaintenanceGrants</c> added:
/// <list type="bullet">
/// <item>the two partition-aligned filtered indexes <c>IX_AuditLog_Unchained</c> and
/// <c>IX_AuditLog_ChainSeq</c>;</item>
/// <item>the <c>scadabridge_audit_chainer</c> role (members removed first) and its
/// column-level grant on <c>(ChainSeq, RowHash)</c>;</item>
/// <item><c>dbo.AuditLogChainHead</c> and <c>dbo.AuditLogChainTombstone</c> (their grants
/// and the writer role's DENYs on them go with the tables);</item>
/// <item><c>dbo.AuditLog.ChainSeq</c> and <c>RowHash</c>;</item>
/// <item>the two grants <c>AuditMaintenanceGrants</c> gave <c>scadabridge_audit_purger</c>
/// (<c>ALTER ANY DATASPACE</c>, <c>UPDATE (SourceNode)</c>).</item>
/// </list>
/// <para>
/// <c>scadabridge_audit_purger</c> and <c>scadabridge_audit_writer</c> themselves are KEPT:
/// they predate the chain (<c>AddAuditLogTable</c>, <c>FixAuditPurgerRoleGrants</c>) and are
/// the original append-only design.
/// </para>
/// <para>
/// Every statement is existence-guarded, and every reference to a chain column goes through
/// <c>EXEC</c>: <c>dotnet ef migrations script --idempotent</c> puts a migration in one
/// batch, and SQL Server compiles the batch before any guard runs, so a direct reference to
/// a column that is (or is not yet) there fails with Msg 207 (ScadaBridge#126).
/// </para>
/// <para>
/// <b>Deploy gate.</b> Binaries before this change map <c>ChainSeq</c>/<c>RowHash</c> and read
/// the chain tables, so they cannot run against the migrated schema: apply with both centrals
/// stopped, together with the new binaries. The new binaries purge either schema (the
/// partition-switch staging table copies the chain columns only when the live table has them).
/// </para>
/// </summary>
public partial class RemoveAuditLogHashChain : Migration
{
/// <inheritdoc />
protected override void Up(MigrationBuilder migrationBuilder)
{
migrationBuilder.Sql(@"
IF EXISTS (SELECT 1 FROM sys.indexes WHERE name = 'IX_AuditLog_ChainSeq' AND object_id = OBJECT_ID('dbo.AuditLog'))
EXEC(N'DROP INDEX IX_AuditLog_ChainSeq ON dbo.AuditLog;');
IF EXISTS (SELECT 1 FROM sys.indexes WHERE name = 'IX_AuditLog_Unchained' AND object_id = OBJECT_ID('dbo.AuditLog'))
EXEC(N'DROP INDEX IX_AuditLog_Unchained ON dbo.AuditLog;');");
migrationBuilder.Sql(@"
IF DATABASE_PRINCIPAL_ID('scadabridge_audit_chainer') IS NOT NULL
BEGIN
IF COL_LENGTH('dbo.AuditLog', 'ChainSeq') IS NOT NULL
EXEC(N'REVOKE UPDATE (ChainSeq, RowHash) ON dbo.AuditLog FROM scadabridge_audit_chainer;');
EXEC(N'REVOKE SELECT ON dbo.AuditLog FROM scadabridge_audit_chainer;');
DECLARE @dropMembers nvarchar(max) = N'';
SELECT @dropMembers = @dropMembers + N'ALTER ROLE scadabridge_audit_chainer DROP MEMBER ' + QUOTENAME(m.name) + N';' + CHAR(10)
FROM sys.database_role_members rm
JOIN sys.database_principals r ON r.principal_id = rm.role_principal_id
JOIN sys.database_principals m ON m.principal_id = rm.member_principal_id
WHERE r.name = N'scadabridge_audit_chainer';
EXEC sp_executesql @dropMembers;
EXEC(N'DROP ROLE scadabridge_audit_chainer;');
END");
migrationBuilder.Sql(@"
IF OBJECT_ID('dbo.AuditLogChainHead', 'U') IS NOT NULL
EXEC(N'DROP TABLE dbo.AuditLogChainHead;');
IF OBJECT_ID('dbo.AuditLogChainTombstone', 'U') IS NOT NULL
EXEC(N'DROP TABLE dbo.AuditLogChainTombstone;');");
migrationBuilder.Sql(@"
IF COL_LENGTH('dbo.AuditLog', 'ChainSeq') IS NOT NULL
EXEC(N'ALTER TABLE dbo.AuditLog DROP COLUMN ChainSeq;');
IF COL_LENGTH('dbo.AuditLog', 'RowHash') IS NOT NULL
EXEC(N'ALTER TABLE dbo.AuditLog DROP COLUMN RowHash;');");
migrationBuilder.Sql(@"
IF DATABASE_PRINCIPAL_ID('scadabridge_audit_purger') IS NOT NULL
BEGIN
EXEC(N'REVOKE ALTER ANY DATASPACE FROM scadabridge_audit_purger;');
EXEC(N'REVOKE UPDATE (SourceNode) ON dbo.AuditLog FROM scadabridge_audit_purger;');
END");
}
/// <inheritdoc />
protected override void Down(MigrationBuilder migrationBuilder)
{
// Recreates exactly what AddAuditLogHashChain and AuditMaintenanceGrants created, so
// the migrations before this one (and their Down methods) find the schema they expect.
// The chain itself is not restored: every row comes back unchained.
migrationBuilder.Sql(@"
IF COL_LENGTH('dbo.AuditLog', 'ChainSeq') IS NULL
EXEC(N'ALTER TABLE dbo.AuditLog ADD ChainSeq bigint NULL;');
IF COL_LENGTH('dbo.AuditLog', 'RowHash') IS NULL
EXEC(N'ALTER TABLE dbo.AuditLog ADD RowHash binary(32) NULL;');");
migrationBuilder.Sql(@"
IF OBJECT_ID('dbo.AuditLogChainHead', 'U') IS NULL
EXEC(N'CREATE TABLE dbo.AuditLogChainHead (
ChainMonth date NOT NULL,
LastSeq bigint NOT NULL,
LastHash binary(32) NOT NULL,
PurgedThroughSeq bigint NULL,
PurgedThroughHash binary(32) NULL,
UpdatedAtUtc datetime2 NOT NULL,
CONSTRAINT PK_AuditLogChainHead PRIMARY KEY (ChainMonth));');
IF OBJECT_ID('dbo.AuditLogChainTombstone', 'U') IS NULL
EXEC(N'CREATE TABLE dbo.AuditLogChainTombstone (
ChainMonth date NOT NULL,
ChainSeq bigint NOT NULL,
RowHash binary(32) NOT NULL,
EventId uniqueidentifier NOT NULL,
PurgedAtUtc datetime2 NOT NULL,
CONSTRAINT PK_AuditLogChainTombstone PRIMARY KEY (ChainMonth, ChainSeq));');");
migrationBuilder.Sql(@"
IF NOT EXISTS (SELECT 1 FROM sys.indexes WHERE name = 'IX_AuditLog_Unchained' AND object_id = OBJECT_ID('dbo.AuditLog'))
EXEC(N'CREATE NONCLUSTERED INDEX IX_AuditLog_Unchained
ON dbo.AuditLog (OccurredAtUtc, EventId)
WHERE ChainSeq IS NULL
ON ps_AuditLog_Month(OccurredAtUtc);');
IF NOT EXISTS (SELECT 1 FROM sys.indexes WHERE name = 'IX_AuditLog_ChainSeq' AND object_id = OBJECT_ID('dbo.AuditLog'))
EXEC(N'CREATE NONCLUSTERED INDEX IX_AuditLog_ChainSeq
ON dbo.AuditLog (ChainSeq)
WHERE ChainSeq IS NOT NULL
ON ps_AuditLog_Month(OccurredAtUtc);');");
migrationBuilder.Sql(@"
IF DATABASE_PRINCIPAL_ID('scadabridge_audit_chainer') IS NULL
EXEC sp_executesql N'CREATE ROLE scadabridge_audit_chainer';
EXEC(N'GRANT SELECT ON dbo.AuditLog TO scadabridge_audit_chainer;
GRANT UPDATE (ChainSeq, RowHash) ON dbo.AuditLog TO scadabridge_audit_chainer;
GRANT SELECT, INSERT, UPDATE ON dbo.AuditLogChainHead TO scadabridge_audit_chainer;
GRANT SELECT ON dbo.AuditLogChainTombstone TO scadabridge_audit_chainer;');
IF DATABASE_PRINCIPAL_ID('scadabridge_audit_purger') IS NULL
EXEC sp_executesql N'CREATE ROLE scadabridge_audit_purger';
EXEC(N'GRANT SELECT, UPDATE ON dbo.AuditLogChainHead TO scadabridge_audit_purger;
GRANT SELECT, INSERT, DELETE ON dbo.AuditLogChainTombstone TO scadabridge_audit_purger;
GRANT ALTER ANY DATASPACE TO scadabridge_audit_purger;
GRANT UPDATE (SourceNode) ON dbo.AuditLog TO scadabridge_audit_purger;');
IF DATABASE_PRINCIPAL_ID('scadabridge_audit_writer') IS NULL
EXEC sp_executesql N'CREATE ROLE scadabridge_audit_writer';
EXEC(N'DENY INSERT, UPDATE, DELETE ON dbo.AuditLogChainHead TO scadabridge_audit_writer;
DENY INSERT, UPDATE, DELETE ON dbo.AuditLogChainTombstone TO scadabridge_audit_writer;');");
}
}
}
@@ -1922,61 +1922,6 @@ namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Migrations
b.ToTable("BundleUnlockAttempt", (string)null); b.ToTable("BundleUnlockAttempt", (string)null);
}); });
modelBuilder.Entity("ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Entities.AuditLogChainHead", b =>
{
b.Property<DateTime>("ChainMonth")
.HasColumnType("date");
b.Property<byte[]>("LastHash")
.IsRequired()
.HasMaxLength(32)
.HasColumnType("binary(32)")
.IsFixedLength();
b.Property<long>("LastSeq")
.HasColumnType("bigint");
b.Property<byte[]>("PurgedThroughHash")
.HasMaxLength(32)
.HasColumnType("binary(32)")
.IsFixedLength();
b.Property<long?>("PurgedThroughSeq")
.HasColumnType("bigint");
b.Property<DateTime>("UpdatedAtUtc")
.HasColumnType("datetime2");
b.HasKey("ChainMonth");
b.ToTable("AuditLogChainHead", (string)null);
});
modelBuilder.Entity("ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Entities.AuditLogChainTombstone", b =>
{
b.Property<DateTime>("ChainMonth")
.HasColumnType("date");
b.Property<long>("ChainSeq")
.HasColumnType("bigint");
b.Property<Guid>("EventId")
.HasColumnType("uniqueidentifier");
b.Property<DateTime>("PurgedAtUtc")
.HasColumnType("datetime2");
b.Property<byte[]>("RowHash")
.IsRequired()
.HasMaxLength(32)
.HasColumnType("binary(32)")
.IsFixedLength();
b.HasKey("ChainMonth", "ChainSeq");
b.ToTable("AuditLogChainTombstone", (string)null);
});
modelBuilder.Entity("ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Entities.AuditLogRow", b => modelBuilder.Entity("ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Entities.AuditLogRow", b =>
{ {
b.Property<DateTime>("OccurredAtUtc") b.Property<DateTime>("OccurredAtUtc")
@@ -1995,9 +1940,6 @@ namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Migrations
.HasMaxLength(256) .HasMaxLength(256)
.HasColumnType("nvarchar(256)"); .HasColumnType("nvarchar(256)");
b.Property<long?>("ChainSeq")
.HasColumnType("bigint");
b.Property<string>("Channel") b.Property<string>("Channel")
.IsRequired() .IsRequired()
.HasMaxLength(32) .HasMaxLength(32)
@@ -2040,11 +1982,6 @@ namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Migrations
.HasColumnType("uniqueidentifier") .HasColumnType("uniqueidentifier")
.HasComputedColumnSql("CAST(JSON_VALUE(DetailsJson,'$.parentExecutionId') AS uniqueidentifier)", true); .HasComputedColumnSql("CAST(JSON_VALUE(DetailsJson,'$.parentExecutionId') AS uniqueidentifier)", true);
b.Property<byte[]>("RowHash")
.HasMaxLength(32)
.HasColumnType("binary(32)")
.IsFixedLength();
b.Property<string>("SourceNode") b.Property<string>("SourceNode")
.HasMaxLength(64) .HasMaxLength(64)
.IsUnicode(false) .IsUnicode(false)
@@ -2071,10 +2008,6 @@ namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Migrations
b.HasKey("OccurredAtUtc", "EventId"); b.HasKey("OccurredAtUtc", "EventId");
b.HasIndex("ChainSeq")
.HasDatabaseName("IX_AuditLog_ChainSeq")
.HasFilter("[ChainSeq] IS NOT NULL");
b.HasIndex("CorrelationId") b.HasIndex("CorrelationId")
.HasDatabaseName("IX_AuditLog_CorrelationId") .HasDatabaseName("IX_AuditLog_CorrelationId")
.HasFilter("[CorrelationId] IS NOT NULL"); .HasFilter("[CorrelationId] IS NOT NULL");
@@ -2103,10 +2036,6 @@ namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Migrations
.IsDescending(false, true) .IsDescending(false, true)
.HasDatabaseName("IX_AuditLog_Kind_Occurred"); .HasDatabaseName("IX_AuditLog_Kind_Occurred");
b.HasIndex("OccurredAtUtc", "EventId")
.HasDatabaseName("IX_AuditLog_Unchained")
.HasFilter("[ChainSeq] IS NULL");
b.HasIndex("SourceNode", "OccurredAtUtc") b.HasIndex("SourceNode", "OccurredAtUtc")
.HasDatabaseName("IX_AuditLog_Node_Occurred"); .HasDatabaseName("IX_AuditLog_Node_Occurred");
@@ -49,22 +49,6 @@ public class AuditLogRepository : IAuditLogRepository
private const string CanonicalColumnList = private const string CanonicalColumnList =
"EventId, OccurredAtUtc, Actor, Action, Outcome, Category, Target, SourceNode, CorrelationId, DetailsJson"; "EventId, OccurredAtUtc, Actor, Action, Outcome, Category, Target, SourceNode, CorrelationId, DetailsJson";
// Hash chain (ScadaBridge#41). Wraps a maintenance-path batch in a transaction holding
// the EXCLUSIVE chain application lock (Maintenance.AuditChainLock), so it never
// interleaves with a chaining pass or a verification. NOCOUNT is ON for everything but
// the one mutating statement the caller places between prefix and suffix, so
// ExecuteNonQuery still returns exactly that statement's row count. XACT_ABORT rolls
// the transaction back on any error or client timeout (attention).
private const string ChainLockedBatchPrefix =
"SET XACT_ABORT ON;\nSET NOCOUNT ON;\nBEGIN TRANSACTION;\n" +
"DECLARE @chainLock int;\n" +
"EXEC @chainLock = sp_getapplock @Resource = N'" + Maintenance.AuditChainLock.Resource + "', @LockMode = 'Exclusive', @LockOwner = 'Transaction', @LockTimeout = -1;\n" +
"IF @chainLock < 0 THROW 51000, 'AuditLog hash-chain lock was not granted.', 1;\n" +
"SET NOCOUNT OFF;\n";
private const string ChainLockedBatchSuffix =
"\nSET NOCOUNT ON;\nCOMMIT TRANSACTION;";
private readonly ScadaBridgeDbContext _context; private readonly ScadaBridgeDbContext _context;
private readonly ILogger<AuditLogRepository> _logger; private readonly ILogger<AuditLogRepository> _logger;
@@ -494,11 +478,10 @@ VALUES
/// <summary> /// <summary>
/// The partition switch-out, optionally guarded by an archive's expectations /// The partition switch-out, optionally guarded by an archive's expectations
/// (ScadaBridge#42). With a <paramref name="guard"/>, the switch transaction — after it /// (ScadaBridge#42). With a <paramref name="guard"/>, the switch transaction re-counts
/// holds the exclusive chain lock — re-counts the partition and re-reads its months' /// the partition and THROWs (error 51002, nothing purged) when the count differs from
/// chain heads, and THROWs (error 51002 / 51003, nothing purged) when either differs /// what the archive captured, so "archive, then purge" never drops a row the archive
/// from what the archive captured. That is what makes "archive, then purge" safe /// does not hold.
/// against a row arriving, a per-channel purge or a chaining pass in between.
/// </summary> /// </summary>
/// <param name="monthBoundary">The partition's lower boundary.</param> /// <param name="monthBoundary">The partition's lower boundary.</param>
/// <param name="guard">Archive expectations, or null for the unguarded purge.</param> /// <param name="guard">Archive expectations, or null for the unguarded purge.</param>
@@ -556,21 +539,15 @@ VALUES
WHERE $PARTITION.pf_AuditLog_Month(OccurredAtUtc) = WHERE $PARTITION.pf_AuditLog_Month(OccurredAtUtc) =
$partition.pf_AuditLog_Month('{monthBoundaryStr}');"; $partition.pf_AuditLog_Month('{monthBoundaryStr}');";
// ScadaBridge#42 archive guard (empty for the unguarded purge). Runs under the chain // ScadaBridge#42 archive guard (empty for the unguarded purge). The per-channel purge
// lock, so no chaining pass or per-channel purge can move the partition between the // and this switch run on the same purge actor, one after the other, so nothing else
// check and the SWITCH; an INSERT racing it is caught by the next tick's archive. // removes rows between the check and the SWITCH; an INSERT racing it is caught by the
// next tick's archive.
var guardSql = guard is null ? string.Empty : guard.ToSql(monthBoundaryStr); var guardSql = guard is null ? string.Empty : guard.ToSql(monthBoundaryStr);
var sql = $@" var sql = $@"
BEGIN TRY BEGIN TRY
BEGIN TRANSACTION; BEGIN TRANSACTION;
-- 0. Hash chain (ScadaBridge#41): hold the exclusive chain lock for the whole
-- switch so no chaining pass / verification interleaves with the anchor
-- update in step 3b.
DECLARE @chainLock int;
EXEC @chainLock = sp_getapplock @Resource = N'{Maintenance.AuditChainLock.Resource}', @LockMode = 'Exclusive', @LockOwner = 'Transaction', @LockTimeout = -1;
IF @chainLock < 0 THROW 51000, 'AuditLog hash-chain lock was not granted.', 1;
{guardSql} {guardSql}
-- 1. Defensive cleanup for databases created before -- 1. Defensive cleanup for databases created before
-- AlignAuditLogEventIdUniqueness: the migration drops the -- AlignAuditLogEventIdUniqueness: the migration drops the
@@ -588,8 +565,7 @@ VALUES
-- expression text + PERSISTED) or ALTER TABLE ... SWITCH PARTITION -- expression text + PERSISTED) or ALTER TABLE ... SWITCH PARTITION
-- rejects the operation with msg 4904/4948. The ordinal order also -- rejects the operation with msg 4904/4948. The ordinal order also
-- matches dbo.AuditLog_v2 (the CollapseAuditLogToCanonical migration): -- matches dbo.AuditLog_v2 (the CollapseAuditLogToCanonical migration):
-- 10 canonical columns first, then the 6 computed columns, then the two -- 10 canonical columns first, then the 6 computed columns.
-- hash-chain columns AddAuditLogHashChain appended (ScadaBridge#41).
CREATE TABLE dbo.[{stagingTableName}] ( CREATE TABLE dbo.[{stagingTableName}] (
EventId uniqueidentifier NOT NULL, EventId uniqueidentifier NOT NULL,
OccurredAtUtc datetime2(7) NOT NULL, OccurredAtUtc datetime2(7) NOT NULL,
@@ -606,11 +582,15 @@ VALUES
SourceSiteId AS JSON_VALUE(DetailsJson,'$.sourceSiteId') PERSISTED, SourceSiteId AS JSON_VALUE(DetailsJson,'$.sourceSiteId') PERSISTED,
ExecutionId AS CAST(JSON_VALUE(DetailsJson,'$.executionId') AS uniqueidentifier) PERSISTED, ExecutionId AS CAST(JSON_VALUE(DetailsJson,'$.executionId') AS uniqueidentifier) PERSISTED,
ParentExecutionId AS CAST(JSON_VALUE(DetailsJson,'$.parentExecutionId') AS uniqueidentifier) PERSISTED, ParentExecutionId AS CAST(JSON_VALUE(DetailsJson,'$.parentExecutionId') AS uniqueidentifier) PERSISTED,
IngestedAtUtc AS CAST(SWITCHOFFSET(CAST(JSON_VALUE(DetailsJson,'$.ingestedAtUtc') AS datetimeoffset), 0) AS datetime2(7)), IngestedAtUtc AS CAST(SWITCHOFFSET(CAST(JSON_VALUE(DetailsJson,'$.ingestedAtUtc') AS datetimeoffset), 0) AS datetime2(7))
ChainSeq bigint NULL,
RowHash binary(32) NULL
) ON [PRIMARY]; ) ON [PRIMARY];
-- 2a. A database that has not yet run RemoveAuditLogHashChain still carries the two
-- columns AddAuditLogHashChain appended; SWITCH needs them on staging too. Read
-- the live table instead of assuming, so this binary purges either schema.
IF COL_LENGTH('dbo.AuditLog', 'ChainSeq') IS NOT NULL
EXEC(N'ALTER TABLE dbo.[{stagingTableName}] ADD ChainSeq bigint NULL, RowHash binary(32) NULL;');
-- 2b. The staging clustered key must match dbo.AuditLog's or SWITCH refuses -- 2b. The staging clustered key must match dbo.AuditLog's or SWITCH refuses
-- (msg 4913/4947). FlipAuditLogClusteredKey (ScadaBridge#111) changed it from -- (msg 4913/4947). FlipAuditLogClusteredKey (ScadaBridge#111) changed it from
-- (EventId, OccurredAtUtc) to (OccurredAtUtc, EventId), so read the live key -- (EventId, OccurredAtUtc) to (OccurredAtUtc, EventId), so read the live key
@@ -631,19 +611,6 @@ VALUES
DECLARE @sql nvarchar(max) = 'ALTER TABLE dbo.AuditLog SWITCH PARTITION ' + CAST(@partitionNumber AS nvarchar(10)) + ' TO dbo.[{stagingTableName}];'; DECLARE @sql nvarchar(max) = 'ALTER TABLE dbo.AuditLog SWITCH PARTITION ' + CAST(@partitionNumber AS nvarchar(10)) + ' TO dbo.[{stagingTableName}];';
EXEC sp_executesql @sql; EXEC sp_executesql @sql;
-- 3b. Hash chain (ScadaBridge#41): the months this partition held are gone as a
-- whole, so record each month's current chain end as its checkpoint anchor
-- (verification resumes after it; a late-arriving row chains on from it)
-- and drop the per-channel tombstones the anchor now subsumes. The chain-start
-- anchor (ChainSeq 0, ScadaBridge#139) is NOT a purge tombstone: it records the
-- cutoff for the life of the database, so it stays.
UPDATE dbo.AuditLogChainHead
SET PurgedThroughSeq = LastSeq, PurgedThroughHash = LastHash, UpdatedAtUtc = SYSUTCDATETIME()
WHERE $partition.pf_AuditLog_Month(CAST(ChainMonth AS datetime2(7))) = @partitionNumber;
DELETE FROM dbo.AuditLogChainTombstone
WHERE $partition.pf_AuditLog_Month(CAST(ChainMonth AS datetime2(7))) = @partitionNumber
AND ChainSeq > 0;
-- 4. Drop staging — the rows are discarded here. This is the purge. -- 4. Drop staging — the rows are discarded here. This is the purge.
DROP TABLE dbo.[{stagingTableName}]; DROP TABLE dbo.[{stagingTableName}];
@@ -771,22 +738,8 @@ VALUES
// The trailing AUDIT-PURGE-ALLOWED marker on the DELETE line below is the // The trailing AUDIT-PURGE-ALLOWED marker on the DELETE line below is the
// single narrow exemption the append-only CI guard (AuditLogAppendOnlyGuardTests) // single narrow exemption the append-only CI guard (AuditLogAppendOnlyGuardTests)
// recognizes; any other UPDATE/DELETE targeting AuditLog still trips the guard. // recognizes; any other UPDATE/DELETE targeting AuditLog still trips the guard.
//
// Hash chain (ScadaBridge#41): a row deleted from the middle of a month's chain must
// leave its link behind or verification reports the gap as tampering. The DELETE
// OUTPUTs every removed row into a table variable and the same transaction writes a
// tombstone (month, ChainSeq, RowHash) for each CHAINED one; the whole batch runs
// under the exclusive chain lock so a chaining pass or a verification never sees the
// row gone without its tombstone. Rows not yet chained need no tombstone.
const string deleteBatchSql = const string deleteBatchSql =
ChainLockedBatchPrefix + "DELETE TOP (@batch) FROM dbo.AuditLog WHERE Category = @channel AND OccurredAtUtc < @threshold;"; // AUDIT-PURGE-ALLOWED: per-channel retention override, maintenance path
"DECLARE @purged TABLE (EventId uniqueidentifier NOT NULL, OccurredAtUtc datetime2(7) NOT NULL, ChainSeq bigint NULL, RowHash binary(32) NULL);\n" +
"DELETE TOP (@batch) FROM dbo.AuditLog OUTPUT deleted.EventId, deleted.OccurredAtUtc, deleted.ChainSeq, deleted.RowHash INTO @purged WHERE Category = @channel AND OccurredAtUtc < @threshold;\n" + // AUDIT-PURGE-ALLOWED: per-channel retention override, maintenance path
"SET NOCOUNT ON;\n" +
"INSERT INTO dbo.AuditLogChainTombstone (ChainMonth, ChainSeq, RowHash, EventId, PurgedAtUtc)\n" +
"SELECT DATEFROMPARTS(YEAR(OccurredAtUtc), MONTH(OccurredAtUtc), 1), ChainSeq, RowHash, EventId, SYSUTCDATETIME()\n" +
"FROM @purged WHERE ChainSeq IS NOT NULL AND RowHash IS NOT NULL;\n" +
ChainLockedBatchSuffix;
long totalDeleted = 0; long totalDeleted = 0;
@@ -1462,16 +1415,8 @@ VALUES
// The trailing AUDIT-PURGE-ALLOWED marker on the UPDATE line below is the // The trailing AUDIT-PURGE-ALLOWED marker on the UPDATE line below is the
// single narrow exemption the append-only CI guard (AuditLogAppendOnlyGuardTests) // single narrow exemption the append-only CI guard (AuditLogAppendOnlyGuardTests)
// recognises for an UPDATE; any other UPDATE targeting AuditLog still trips the guard. // recognises for an UPDATE; any other UPDATE targeting AuditLog still trips the guard.
//
// Hash chain (ScadaBridge#41): SourceNode is inside every chained row's hash, so the
// backfill touches ONLY unchained rows (ChainSeq IS NULL) and runs under the
// exclusive chain lock — a chaining pass can never hash a row whose SourceNode this
// batch is about to change. Run the backfill BEFORE enabling AuditLog:HashChain;
// once a row is chained its SourceNode is frozen.
const string updateBatchSql = const string updateBatchSql =
ChainLockedBatchPrefix + "UPDATE TOP (@batch) dbo.AuditLog SET SourceNode = @sentinel WHERE SourceNode IS NULL AND OccurredAtUtc < @before;"; // AUDIT-PURGE-ALLOWED: SourceNode sentinel backfill, maintenance path
"UPDATE TOP (@batch) dbo.AuditLog SET SourceNode = @sentinel WHERE SourceNode IS NULL AND OccurredAtUtc < @before AND ChainSeq IS NULL;" + // AUDIT-PURGE-ALLOWED: SourceNode sentinel backfill, maintenance path
ChainLockedBatchSuffix;
long totalUpdated = 0; long totalUpdated = 0;
@@ -139,10 +139,6 @@ public class ScadaBridgeDbContext : DbContext, IDataProtectionKeyContext
public DbSet<AuditLogEntry> AuditLogEntries => Set<AuditLogEntry>(); public DbSet<AuditLogEntry> AuditLogEntries => Set<AuditLogEntry>();
/// <summary>Gets the set of audit log rows (central <c>dbo.AuditLog</c> persistence shape; mapped to/from the canonical record at the repository boundary).</summary> /// <summary>Gets the set of audit log rows (central <c>dbo.AuditLog</c> persistence shape; mapped to/from the canonical record at the repository boundary).</summary>
public DbSet<AuditLogRow> AuditLogs => Set<AuditLogRow>(); public DbSet<AuditLogRow> AuditLogs => Set<AuditLogRow>();
/// <summary>Gets the per-month AuditLog hash-chain heads (ScadaBridge#41).</summary>
public DbSet<AuditLogChainHead> AuditLogChainHeads => Set<AuditLogChainHead>();
/// <summary>Gets the AuditLog hash-chain purge tombstones (ScadaBridge#41).</summary>
public DbSet<AuditLogChainTombstone> AuditLogChainTombstones => Set<AuditLogChainTombstone>();
/// <summary>Gets the set of site calls.</summary> /// <summary>Gets the set of site calls.</summary>
public DbSet<SiteCall> SiteCalls => Set<SiteCall>(); public DbSet<SiteCall> SiteCalls => Set<SiteCall>();
@@ -20,14 +20,9 @@ public static class ServiceCollectionExtensions
/// </summary> /// </summary>
/// <param name="services">The service collection to register into.</param> /// <param name="services">The service collection to register into.</param>
/// <param name="connectionString">SQL Server connection string for the central configuration database.</param> /// <param name="connectionString">SQL Server connection string for the central configuration database.</param>
/// <param name="auditMaintenanceConnectionString">
/// Optional separate connection string for the AuditLog maintenance paths — hash-chain job
/// and both purge paths (<c>AuditLog:MaintenanceConnectionString</c>, ScadaBridge#107 item 3).
/// Null or blank runs them on <paramref name="connectionString"/> as before.
/// </param>
/// <returns>The same <paramref name="services"/> collection, for chaining.</returns> /// <returns>The same <paramref name="services"/> collection, for chaining.</returns>
public static IServiceCollection AddConfigurationDatabase( public static IServiceCollection AddConfigurationDatabase(
this IServiceCollection services, string connectionString, string? auditMaintenanceConnectionString = null) this IServiceCollection services, string connectionString)
{ {
// The DbContext is constructed via the (options, IDataProtectionProvider) overload so // The DbContext is constructed via the (options, IDataProtectionProvider) overload so
// secret-bearing configuration columns are encrypted at rest. AddDataProtection below // secret-bearing configuration columns are encrypted at rest. AddDataProtection below
@@ -115,37 +110,7 @@ public static class ServiceCollectionExtensions
// hosted service. Scoped because the implementation reuses the per-scope // hosted service. Scoped because the implementation reuses the per-scope
// ScadaBridgeDbContext for raw-SQL execution; the hosted service opens a // ScadaBridgeDbContext for raw-SQL execution; the hosted service opens a
// fresh scope on each tick (mirrors AuditLogPurgeActor / AuditLogIngestActor). // fresh scope on each tick (mirrors AuditLogPurgeActor / AuditLogIngestActor).
// Runs on the maintenance connection when AuditLog:MaintenanceConnectionString is set services.AddScoped<IPartitionMaintenance, AuditLogPartitionMaintenance>();
// (ScadaBridge#113), else on the scope's own context as before.
services.AddScoped<IPartitionMaintenance>(sp => new AuditLogPartitionMaintenance(
sp.GetRequiredService<AuditMaintenanceContext>().Context,
sp.GetService<Microsoft.Extensions.Logging.ILogger<AuditLogPartitionMaintenance>>()));
// AuditLog maintenance connection (ScadaBridge#107 item 3): the chain job and both purge
// paths run on AuditMaintenanceContext — the scope's own context unless a separate
// maintenance login is configured, in which case an owned context on that string.
services.AddSingleton(new AuditMaintenanceConnection(
string.IsNullOrWhiteSpace(auditMaintenanceConnectionString) ? null : auditMaintenanceConnectionString));
services.AddScoped(sp =>
{
var maintenance = sp.GetRequiredService<AuditMaintenanceConnection>().ConnectionString;
return maintenance is null
? AuditMaintenanceContext.Shared(sp.GetRequiredService<ScadaBridgeDbContext>())
: AuditMaintenanceContext.Separate(maintenance, sp.GetService<IDataProtectionProvider>());
});
services.AddKeyedScoped<IAuditLogRepository>(AuditMaintenanceContext.ServiceKey, (sp, _) => new AuditLogRepository(
sp.GetRequiredService<AuditMaintenanceContext>().Context,
sp.GetService<Microsoft.Extensions.Logging.ILogger<AuditLogRepository>>()));
// AuditLog hash-chain tamper evidence (ScadaBridge#41): chained by the central
// AuditLogHashChainService, verified by the VerifyAuditChain management command; the
// same instance reads/verifies the off-box head export (#107 item 1). Both on the
// maintenance connection.
services.AddScoped(sp => new AuditLogHashChain(
sp.GetRequiredService<AuditMaintenanceContext>().Context,
sp.GetService<Microsoft.Extensions.Logging.ILogger<AuditLogHashChain>>()));
services.AddScoped<IAuditLogHashChain>(sp => sp.GetRequiredService<AuditLogHashChain>());
services.AddScoped<IAuditChainHeadStore>(sp => sp.GetRequiredService<AuditLogHashChain>());
// AuditLog Parquet cold archive (ScadaBridge#42): written by the purge actor before a // AuditLog Parquet cold archive (ScadaBridge#42): written by the purge actor before a
// partition switch, listed/verified by the ListAuditArchives / VerifyAuditArchive // partition switch, listed/verified by the ListAuditArchives / VerifyAuditArchive
@@ -155,12 +120,6 @@ public static class ServiceCollectionExtensions
sp.GetRequiredService<ScadaBridgeDbContext>(), sp.GetRequiredService<ScadaBridgeDbContext>(),
sp.GetService<Microsoft.Extensions.Options.IOptions<AuditLogArchiveOptions>>()?.Value ?? new AuditLogArchiveOptions(), sp.GetService<Microsoft.Extensions.Options.IOptions<AuditLogArchiveOptions>>()?.Value ?? new AuditLogArchiveOptions(),
sp.GetService<Microsoft.Extensions.Logging.ILogger<AuditLogPartitionArchive>>())); sp.GetService<Microsoft.Extensions.Logging.ILogger<AuditLogPartitionArchive>>()));
// The purge actor's archive-then-purge runs on the maintenance connection (#107 item 3);
// list/verify from the management surface stay on the runtime connection (reads only).
services.AddKeyedScoped<IAuditLogArchive>(AuditMaintenanceContext.ServiceKey, (sp, _) => new AuditLogPartitionArchive(
sp.GetRequiredService<AuditMaintenanceContext>().Context,
sp.GetService<Microsoft.Extensions.Options.IOptions<AuditLogArchiveOptions>>()?.Value ?? new AuditLogArchiveOptions(),
sp.GetService<Microsoft.Extensions.Logging.ILogger<AuditLogPartitionArchive>>()));
// Opt-in config-audit retention (ScadaBridge:ConfigAudit:RetentionDays, default 0 = off). // Opt-in config-audit retention (ScadaBridge:ConfigAudit:RetentionDays, default 0 = off).
// Options binding to configuration is done by the host; without it the defaults apply // Options binding to configuration is done by the host; without it the defaults apply
@@ -1,63 +0,0 @@
using Microsoft.Extensions.Diagnostics.HealthChecks;
using ZB.MOM.WW.ScadaBridge.AuditLog.Central.HeadExport;
namespace ZB.MOM.WW.ScadaBridge.Host.Health;
/// <summary>
/// /health/ready entry (ScadaBridge#115): Degraded while the off-box AuditLog chain-head export
/// (<c>AuditLog:HashChain:HeadExport</c>) is failing, or has had no success for more than two
/// intervals. Degraded maps to HTTP 200, so it shows on the Overview dashboard without taking
/// the node out of rotation. Healthy when the export is disabled.
/// </summary>
public sealed class AuditChainHeadExportHealthCheck : IHealthCheck
{
private readonly AuditChainHeadExportStatus _status;
private readonly TimeProvider _time;
/// <summary>Initializes the check.</summary>
/// <param name="status">The export status singleton.</param>
/// <param name="time">Clock (defaults to the system clock).</param>
public AuditChainHeadExportHealthCheck(AuditChainHeadExportStatus status, TimeProvider? time = null)
{
_status = status ?? throw new ArgumentNullException(nameof(status));
_time = time ?? TimeProvider.System;
}
/// <inheritdoc />
public Task<HealthCheckResult> CheckHealthAsync(
HealthCheckContext context, CancellationToken cancellationToken = default)
{
if (!_status.Enabled)
{
return Task.FromResult(HealthCheckResult.Healthy("Chain-head export disabled."));
}
var now = _time.GetUtcNow().UtcDateTime;
var data = new Dictionary<string, object>(StringComparer.Ordinal)
{
["totalFailures"] = _status.TotalFailures,
["consecutiveFailures"] = _status.ConsecutiveFailures,
["intervalMinutes"] = _status.IntervalMinutes,
};
if (_status.LastSuccessUtc is { } ok)
{
data["lastSuccessUtc"] = ok;
}
if (_status.ConsecutiveFailures > 0)
{
return Task.FromResult(HealthCheckResult.Degraded(
$"Chain-head export failing ({_status.ConsecutiveFailures} consecutive): {_status.LastError}", data: data));
}
var limit = TimeSpan.FromMinutes(2L * _status.IntervalMinutes);
var reference = _status.LastSuccessUtc ?? _status.StartedUtc;
if (reference is { } r && now - r > limit)
{
return Task.FromResult(HealthCheckResult.Degraded(
$"No successful chain-head export for more than 2 intervals (last {(_status.LastSuccessUtc is null ? "never" : _status.LastSuccessUtc.Value.ToString("O"))}).", data: data));
}
return Task.FromResult(HealthCheckResult.Healthy("Chain-head export OK.", data));
}
}
+1 -12
View File
@@ -541,12 +541,7 @@ try
var configDbConnectionString = configuration["ScadaBridge:Database:ConfigurationDb"] var configDbConnectionString = configuration["ScadaBridge:Database:ConfigurationDb"]
?? throw new InvalidOperationException("ScadaBridge:Database:ConfigurationDb connection string is required for Central role."); ?? throw new InvalidOperationException("ScadaBridge:Database:ConfigurationDb connection string is required for Central role.");
// Optional second login for the AuditLog maintenance paths (chain job + both purge builder.Services.AddConfigurationDatabase(configDbConnectionString);
// paths, ScadaBridge#107 item 3). Read from the pre-host-expanded configuration, so it
// may be a ${secret:} reference; unset = everything on the runtime connection, as before.
builder.Services.AddConfigurationDatabase(
configDbConnectionString,
configuration[ZB.MOM.WW.ScadaBridge.AuditLog.ServiceCollectionExtensions.MaintenanceConnectionStringKey]);
builder.Services.AddOptions<ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance.ConfigAuditOptions>() builder.Services.AddOptions<ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance.ConfigAuditOptions>()
.Bind(configuration.GetSection(ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance.ConfigAuditOptions.SectionName)) .Bind(configuration.GetSection(ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance.ConfigAuditOptions.SectionName))
.ValidateOnStart(); .ValidateOnStart();
@@ -589,12 +584,6 @@ try
"bundle-signing-policy", "bundle-signing-policy",
failureStatus: null, failureStatus: null,
tags: new[] { ZbHealthTags.Ready }) tags: new[] { ZbHealthTags.Ready })
// ScadaBridge#115: Degraded (HTTP 200) while the off-box chain-head export is failing
// or stale; healthy when the export is disabled.
.AddTypeActivatedCheck<AuditChainHeadExportHealthCheck>(
"audit-chain-head-export",
failureStatus: null,
tags: new[] { ZbHealthTags.Ready })
// Oldest-Up-member check (review 01 [High]), unscoped: every central member competes for // Oldest-Up-member check (review 01 [High]), unscoped: every central member competes for
// the one active slot. Since ZB.MOM.WW.Health 0.3.0 this IS the shared check — it selects // the one active slot. Since ZB.MOM.WW.Health 0.3.0 this IS the shared check — it selects
// by age, so the host-local OldestNodeActiveHealthCheck that existed only to avoid the old // by age, so the host-local OldestNodeActiveHealthCheck that existed only to avoid the old
@@ -426,10 +426,7 @@ public static class AuditEndpoints
statusCode: 400); statusCode: 400);
} }
// Maintenance login when AuditLog:MaintenanceConnectionString is set (ScadaBridge#113); var repo = context.RequestServices.GetRequiredService<IAuditLogRepository>();
// otherwise the keyed registration resolves to the runtime connection's context.
var repo = context.RequestServices.GetKeyedService<IAuditLogRepository>(AuditLogServiceKeys.Maintenance)
?? context.RequestServices.GetRequiredService<IAuditLogRepository>();
var rowsUpdated = await repo.BackfillSourceNodeAsync(sentinel, beforeUtc.Value, batchSize, context.RequestAborted); var rowsUpdated = await repo.BackfillSourceNodeAsync(sentinel, beforeUtc.Value, batchSize, context.RequestAborted);
return Results.Json(new return Results.Json(new
@@ -246,7 +246,7 @@ public class ManagementActor : ReceiveActor
// three Live run commands stay DeployerOnly. // three Live run commands stay DeployerOnly.
private static readonly string[] FlowDebuggerReplayRoles = AuthorizationPolicies.FlowDebuggerAccessRoles; private static readonly string[] FlowDebuggerReplayRoles = AuthorizationPolicies.FlowDebuggerAccessRoles;
// ScadaBridge#41: verify-chain is an audit read — the OperationalAudit role set. // AuditLog archive list/verify are audit reads — the OperationalAudit role set.
private static readonly string[] OperationalAuditReaders = AuthorizationPolicies.OperationalAuditRoles; private static readonly string[] OperationalAuditReaders = AuthorizationPolicies.OperationalAuditRoles;
// arch-review C6: area management is reconciled to any-of [Designer, Deployer]. // arch-review C6: area management is reconciled to any-of [Designer, Deployer].
@@ -387,16 +387,8 @@ public class ManagementActor : ReceiveActor
// (arch-review UA1). // (arch-review UA1).
ListSecuredWritesCommand => SecuredWriteReaders, ListSecuredWritesCommand => SecuredWriteReaders,
// AuditLog hash-chain verification (ScadaBridge#41): an audit read, so the // AuditLog Parquet archives (ScadaBridge#42): audit reads — OperationalAudit roles
// OperationalAudit roles (alog.md §15.1 — verify-chain carries audit query's // (alog.md §15.1, audit query's permission), site-scoped callers refused in the handler.
// permission). A site-scoped caller is refused in the handler: a month's chain
// spans every site.
VerifyAuditChainCommand => OperationalAuditReaders,
// Off-box chain-head check (ScadaBridge#107 item 1): the same audit read.
VerifyAuditChainHeadsCommand => OperationalAuditReaders,
// AuditLog Parquet archives (ScadaBridge#42): audit reads with verify-chain's gate —
// OperationalAudit roles, site-scoped callers refused in the handler.
ListAuditArchivesCommand => OperationalAuditReaders, ListAuditArchivesCommand => OperationalAuditReaders,
// Archive cleanup deletes archive files (ScadaBridge#109): Administrator only. // Archive cleanup deletes archive files (ScadaBridge#109): Administrator only.
CleanupAuditArchivesCommand => AdminOnly, CleanupAuditArchivesCommand => AdminOnly,
@@ -572,8 +564,6 @@ public class ManagementActor : ReceiveActor
// Audit Log // Audit Log
QueryAuditLogCommand cmd => await HandleQueryAuditLog(sp, cmd), QueryAuditLogCommand cmd => await HandleQueryAuditLog(sp, cmd),
VerifyAuditChainCommand cmd => await HandleVerifyAuditChain(sp, cmd, user),
VerifyAuditChainHeadsCommand cmd => await HandleVerifyAuditChainHeads(sp, cmd, user),
ListAuditArchivesCommand => await HandleListAuditArchives(sp, user), ListAuditArchivesCommand => await HandleListAuditArchives(sp, user),
VerifyAuditArchiveCommand cmd => await HandleVerifyAuditArchive(sp, cmd, user), VerifyAuditArchiveCommand cmd => await HandleVerifyAuditArchive(sp, cmd, user),
CleanupAuditArchivesCommand cmd => await HandleCleanupAuditArchives(sp, cmd, user), CleanupAuditArchivesCommand cmd => await HandleCleanupAuditArchives(sp, cmd, user),
@@ -3230,42 +3220,6 @@ public class ManagementActor : ReceiveActor
return new AuditLogQueryResult(entries, totalCount); return new AuditLogQueryResult(entries, totalCount);
} }
/// <summary>
/// Verifies one month of the AuditLog hash chain (ScadaBridge#41). The month must be
/// <c>YYYY-MM</c>; a site-scoped, non-Administrator caller is refused because the chain
/// covers every site's rows and a break report names rows by EventId.
/// </summary>
private static async Task<object?> HandleVerifyAuditChain(
IServiceProvider sp, VerifyAuditChainCommand cmd, AuthenticatedUser user)
{
if (string.IsNullOrWhiteSpace(cmd.Month)
|| !DateTime.TryParseExact(cmd.Month, "yyyy-MM", System.Globalization.CultureInfo.InvariantCulture,
System.Globalization.DateTimeStyles.None, out var month))
{
throw new ManagementCommandException(
$"Invalid month '{cmd.Month}'. Expected YYYY-MM (e.g. 2026-05).", "INVALID_ARGUMENT");
}
if (user.PermittedSiteIds.Length > 0
&& !user.Roles.Contains(Roles.Administrator, StringComparer.OrdinalIgnoreCase))
{
throw new SiteScopeViolationException(
"Access denied: the audit hash chain spans every site; verify-chain needs an "
+ "OperationalAudit role that is not scoped to specific sites.");
}
var chain = sp.GetRequiredService<IAuditLogHashChain>();
try
{
return await chain.VerifyMonthAsync(
new DateTime(month.Year, month.Month, 1, 0, 0, 0, DateTimeKind.Utc));
}
catch (TimeoutException ex)
{
throw new ManagementCommandException(ex.Message, "CHAIN_BUSY");
}
}
/// <summary> /// <summary>
/// Lists the AuditLog Parquet archives (ScadaBridge#42). Refused for a site-scoped, /// Lists the AuditLog Parquet archives (ScadaBridge#42). Refused for a site-scoped,
/// non-Administrator caller: an archive holds every site's rows. /// non-Administrator caller: an archive holds every site's rows.
@@ -3276,51 +3230,8 @@ public class ManagementActor : ReceiveActor
return new AuditArchiveListResult(archive.IsEnabled, await archive.ListAsync()); return new AuditArchiveListResult(archive.IsEnabled, await archive.ListAsync());
} }
/// <summary>Upper bound on records per <see cref="VerifyAuditChainHeadsCommand"/>.</summary>
internal const int MaxChainHeadRecords = 50_000;
/// <summary> /// <summary>
/// Checks exported AuditLog chain heads against the database (ScadaBridge#107 item 1). Same /// Verifies one AuditLog Parquet archive (ScadaBridge#42): the data file against its manifest.
/// gate as verify-chain: a site-scoped, non-Administrator caller is refused because the
/// chain spans every site.
/// </summary>
private static async Task<object?> HandleVerifyAuditChainHeads(
IServiceProvider sp, VerifyAuditChainHeadsCommand cmd, AuthenticatedUser user)
{
if (cmd.Records is null || cmd.Records.Count == 0)
{
throw new ManagementCommandException("No exported chain-head records were supplied.", "INVALID_ARGUMENT");
}
if (cmd.Records.Count > MaxChainHeadRecords)
{
throw new ManagementCommandException(
$"{cmd.Records.Count} records exceed the {MaxChainHeadRecords} limit; verify fewer export files at a time.",
"INVALID_ARGUMENT");
}
if (user.PermittedSiteIds.Length > 0
&& !user.Roles.Contains(Roles.Administrator, StringComparer.OrdinalIgnoreCase))
{
throw new SiteScopeViolationException(
"Access denied: the audit hash chain spans every site; verify-heads needs an "
+ "OperationalAudit role that is not scoped to specific sites.");
}
var store = sp.GetRequiredService<IAuditChainHeadStore>();
try
{
return await store.VerifyExportedHeadsAsync(cmd.Records);
}
catch (TimeoutException ex)
{
throw new ManagementCommandException(ex.Message, "CHAIN_BUSY");
}
}
/// <summary>
/// Verifies one AuditLog Parquet archive (ScadaBridge#42): files against the manifest,
/// the chain recomputed from the archived rows, the chain end against the purge anchor.
/// </summary> /// </summary>
private static async Task<object?> HandleVerifyAuditArchive( private static async Task<object?> HandleVerifyAuditArchive(
IServiceProvider sp, VerifyAuditArchiveCommand cmd, AuthenticatedUser user) IServiceProvider sp, VerifyAuditArchiveCommand cmd, AuthenticatedUser user)
@@ -3341,16 +3252,12 @@ public class ManagementActor : ReceiveActor
} }
/// <summary> /// <summary>
/// Runs the archive cleanup now (ScadaBridge#109), on the maintenance-connection archive when /// Runs the archive cleanup now (ScadaBridge#109). Dry run reports only.
/// registered. Dry run reports only.
/// </summary> /// </summary>
private static async Task<object?> HandleCleanupAuditArchives( private static async Task<object?> HandleCleanupAuditArchives(
IServiceProvider sp, CleanupAuditArchivesCommand cmd, AuthenticatedUser user) IServiceProvider sp, CleanupAuditArchivesCommand cmd, AuthenticatedUser user)
{ {
RequireAuditArchive(sp, user); var archive = RequireAuditArchive(sp, user);
var archive = sp.GetKeyedService<IAuditLogArchive>(
ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance.AuditMaintenanceContext.ServiceKey)
?? sp.GetRequiredService<IAuditLogArchive>();
return await archive.CleanupAsync(cmd.DryRun); return await archive.CleanupAsync(cmd.DryRun);
} }
@@ -60,13 +60,7 @@ public static class ManagementEndpoints
// script entry (design 2026-09-08): a direct call lasts up to the script's timeout // script entry (design 2026-09-08): a direct call lasts up to the script's timeout
// (+ grace), a write kind up to its wait window. // (+ grace), a write kind up to its wait window.
typeof(FlowDebugRunScriptCommand), typeof(FlowDebugRunScriptCommand),
// AuditLog hash-chain verification (ScadaBridge#41) recomputes one hash per row of // AuditLog archive verification (ScadaBridge#42) hashes and reads a whole month's
// a whole month — millions of rows on a busy central.
typeof(VerifyAuditChainCommand),
// Off-box chain-head check (ScadaBridge#107): one link lookup per exported head, under
// the chain lock SHARED (waits behind a chaining pass).
typeof(VerifyAuditChainHeadsCommand),
// AuditLog archive verification (ScadaBridge#42) hashes and re-chains a whole month's
// Parquet archive. // Parquet archive.
typeof(VerifyAuditArchiveCommand), typeof(VerifyAuditArchiveCommand),
// Archive cleanup proves stale archives redundant by reading Parquet files (ScadaBridge#109). // Archive cleanup proves stale archives redundant by reading Parquet files (ScadaBridge#109).
@@ -1,155 +0,0 @@
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging.Abstractions;
using Microsoft.Extensions.Options;
using ZB.MOM.WW.ScadaBridge.AuditLog.Central;
using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
namespace ZB.MOM.WW.ScadaBridge.AuditLog.Tests.Central;
/// <summary>
/// Policy tests for <see cref="AuditLogHashChainService"/> (ScadaBridge#41) over a scripted
/// <see cref="IAuditLogHashChain"/>: default-off, draining a backlog within the per-tick
/// cap, yielding to the peer node's lock, and containing failures. The SQL chaining itself
/// is covered by <c>AuditLogHashChainTests</c> in ConfigurationDatabase.Tests.
/// </summary>
public class AuditLogHashChainServiceTests
{
private sealed class ScriptedChain(params AuditChainBatchResult[] script) : IAuditLogHashChain
{
private int _next;
public int Calls => _next;
public Exception? Throw { get; init; }
public List<bool> ChainBacklogSeen { get; } = [];
public Task<AuditChainBatchResult> ChainPendingAsync(int batchSize, bool chainBacklog = false, CancellationToken ct = default)
{
ChainBacklogSeen.Add(chainBacklog);
if (Throw is not null) throw Throw;
var i = _next++;
return Task.FromResult(i < script.Length ? script[i] : new AuditChainBatchResult(0, false));
}
public Task<AuditChainVerificationResult> VerifyMonthAsync(DateTime monthStartUtc, CancellationToken ct = default)
=> throw new NotSupportedException();
}
private static AuditLogHashChainService Create(IAuditLogHashChain chain, AuditLogHashChainOptions options)
{
var services = new ServiceCollection();
services.AddScoped(_ => chain);
return new AuditLogHashChainService(
services.BuildServiceProvider().GetRequiredService<IServiceScopeFactory>(),
Options.Create(options),
NullLogger<AuditLogHashChainService>.Instance);
}
/// <summary>The job is off by default and starting it then does nothing.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Disabled_ByDefault_StartsNoLoop()
{
var chain = new ScriptedChain(new AuditChainBatchResult(5, false));
Assert.False(new AuditLogHashChainOptions().Enabled);
using var service = Create(chain, new AuditLogHashChainOptions());
await service.StartAsync(CancellationToken.None);
await Task.Delay(50);
await service.StopAsync(CancellationToken.None);
Assert.Equal(0, chain.Calls);
}
/// <summary>A tick drains batches until one comes back empty.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Tick_DrainsUntilEmpty()
{
var chain = new ScriptedChain(
new AuditChainBatchResult(10, false), new AuditChainBatchResult(10, false), new AuditChainBatchResult(3, false));
using var service = Create(chain, new AuditLogHashChainOptions { Enabled = true, BatchSize = 10 });
Assert.Equal(23, await service.TickAsync(CancellationToken.None));
Assert.Equal(4, chain.Calls); // the 4th returns 0 and ends the tick
}
/// <summary>
/// ScadaBridge#139: backlog chaining is off by default (owner decision, #107) and the
/// option reaches every chaining pass when set.
/// </summary>
/// <param name="chainBacklog">The configured value, or null to leave the default.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
[Theory]
[InlineData(null)]
[InlineData(false)]
[InlineData(true)]
public async Task Tick_PassesChainBacklog_DefaultOff(bool? chainBacklog)
{
var options = new AuditLogHashChainOptions { Enabled = true };
if (chainBacklog is { } value)
{
options.ChainBacklog = value;
}
var chain = new ScriptedChain(new AuditChainBatchResult(4, false));
using var service = Create(chain, options);
await service.TickAsync(CancellationToken.None);
Assert.Equal(2, chain.ChainBacklogSeen.Count);
Assert.All(chain.ChainBacklogSeen, seen => Assert.Equal(chainBacklog ?? false, seen));
}
/// <summary>The peer node holding the lock ends the tick at once.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Tick_StopsWhenPeerHoldsTheLock()
{
var chain = new ScriptedChain(new AuditChainBatchResult(0, LockBusy: true), new AuditChainBatchResult(10, false));
using var service = Create(chain, new AuditLogHashChainOptions { Enabled = true });
Assert.Equal(0, await service.TickAsync(CancellationToken.None));
Assert.Equal(1, chain.Calls);
}
/// <summary>A backlog yields after MaxBatchesPerTick batches.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Tick_RespectsMaxBatchesPerTick()
{
var chain = new ScriptedChain(Enumerable.Repeat(new AuditChainBatchResult(10, false), 50).ToArray());
using var service = Create(chain, new AuditLogHashChainOptions { Enabled = true, MaxBatchesPerTick = 3 });
Assert.Equal(30, await service.TickAsync(CancellationToken.None));
Assert.Equal(3, chain.Calls);
}
/// <summary>A failing tick is contained (logged), never thrown out of the loop.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Tick_ContainsFailures()
{
var chain = new ScriptedChain { Throw = new InvalidOperationException("sql down") };
using var service = Create(chain, new AuditLogHashChainOptions { Enabled = true });
Assert.Equal(0, await service.TickAsync(CancellationToken.None));
}
/// <summary>Invalid tuning fails startup validation.</summary>
/// <param name="interval">IntervalSeconds.</param>
/// <param name="batch">BatchSize.</param>
/// <param name="maxBatches">MaxBatchesPerTick.</param>
[Theory]
[InlineData(0, 1000, 100)]
[InlineData(60, 0, 100)]
[InlineData(60, 10_001, 100)]
[InlineData(60, 1000, 0)]
public void Validator_RejectsInvalidTuning(int interval, int batch, int maxBatches)
{
var result = new AuditLogHashChainOptionsValidator().Validate(null,
new AuditLogHashChainOptions { IntervalSeconds = interval, BatchSize = batch, MaxBatchesPerTick = maxBatches });
Assert.False(result.Succeeded);
Assert.True(new AuditLogHashChainOptionsValidator().Validate(null, new AuditLogHashChainOptions()).Succeeded);
}
}
@@ -713,9 +713,9 @@ public class AuditLogPurgeActorTests : TestKit, IClassFixture<MsSqlMigrationFixt
} }
private static AuditArchiveManifest ManifestFor(DateTime boundary) => new( private static AuditArchiveManifest ManifestFor(DateTime boundary) => new(
1, $"auditlog-{boundary:yyyy-MM}-20261109T120000000Z", boundary, boundary.ToString("yyyy-MM"), 2, $"auditlog-{boundary:yyyy-MM}-20261109T120000000Z", boundary, boundary.ToString("yyyy-MM"),
DateTime.UtcNow, AuditArchiveStatus.Archived, null, 7, 7, 0, null, null, DateTime.UtcNow, AuditArchiveStatus.Archived, null, 7, null, null,
"d.parquet", "00", 99, "t.parquet", "00", 0, []); "d.parquet", "00", 99);
/// <summary> /// <summary>
/// With archiving enabled every expired partition is archived and then purged by the /// With archiving enabled every expired partition is archived and then purged by the
@@ -793,36 +793,6 @@ public class AuditLogPurgeActorTests : TestKit, IClassFixture<MsSqlMigrationFixt
StopPurgeActor(actor); StopPurgeActor(actor);
} }
/// <summary>
/// ScadaBridge#107 item 3: when the host registered the maintenance-connection repository
/// (keyed <c>audit-maintenance</c>), the purge runs on it, never on the runtime one.
/// </summary>
[Fact]
public void Tick_UsesTheMaintenanceConnectionRepository_WhenRegistered()
{
var runtime = new RecordingRepo { Boundaries = [new DateTime(2025, 1, 1, 0, 0, 0, DateTimeKind.Utc)] };
var maintenance = new RecordingRepo { Boundaries = [new DateTime(2025, 1, 1, 0, 0, 0, DateTimeKind.Utc)] };
var services = new ServiceCollection();
services.AddScoped<IAuditLogRepository>(_ => runtime);
services.AddKeyedScoped<IAuditLogRepository>(
ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance.AuditMaintenanceContext.ServiceKey, (_, _) => maintenance);
var sp = services.BuildServiceProvider();
var actor = Sys.ActorOf(Props.Create(() => new AuditLogPurgeActor(
sp,
Options.Create(FastTickOptions()),
Options.Create(new AuditLogOptions()),
NullLogger<AuditLogPurgeActor>.Instance)));
AwaitAssert(
() => Assert.NotEmpty(maintenance.SwitchedBoundaries),
duration: TimeSpan.FromSeconds(3),
interval: TimeSpan.FromMilliseconds(50));
Assert.Empty(runtime.ThresholdQueries);
Assert.Empty(runtime.SwitchedBoundaries);
StopPurgeActor(actor);
}
/// <summary> /// <summary>
/// ScadaBridge#109: with archiving enabled every tick ends with the archive cleanup pass — /// ScadaBridge#109: with archiving enabled every tick ends with the archive cleanup pass —
/// also on a tick with no expired partition — and never runs it when archiving is off. /// also on a tick with no expired partition — and never runs it when archiving is off.
@@ -1,207 +0,0 @@
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging.Abstractions;
using Microsoft.Extensions.Options;
using ZB.MOM.WW.ScadaBridge.AuditLog.Central;
using ZB.MOM.WW.ScadaBridge.AuditLog.Central.HeadExport;
using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
namespace ZB.MOM.WW.ScadaBridge.AuditLog.Tests.Central.HeadExport;
/// <summary>
/// <see cref="AuditChainHeadExportService"/> (ScadaBridge#107 item 1): first tick exports every
/// head, later ticks only the changed ones, a failed write is retried with the same heads, and
/// the options validator guards each sink's settings.
/// </summary>
public sealed class AuditChainHeadExportServiceTests
{
private sealed class FakeStore : IAuditChainHeadStore
{
public List<AuditChainHeadSnapshot> Heads { get; } = [];
public Task<IReadOnlyList<AuditChainHeadSnapshot>> ReadHeadsAsync(CancellationToken ct = default)
=> Task.FromResult<IReadOnlyList<AuditChainHeadSnapshot>>(Heads.ToList());
public Task<AuditChainHeadVerificationResult> VerifyExportedHeadsAsync(
IReadOnlyList<AuditChainHeadRecord> records, CancellationToken ct = default) => throw new NotSupportedException();
}
private sealed class RecordingSink : IAuditChainHeadSink
{
public List<IReadOnlyList<AuditChainHeadRecord>> Writes { get; } = [];
public bool Fail { get; set; }
public string Describe => "recording";
public Task WriteAsync(IReadOnlyList<AuditChainHeadRecord> records, CancellationToken ct)
{
if (Fail)
{
throw new IOException("share offline");
}
Writes.Add(records);
return Task.CompletedTask;
}
}
private static AuditChainHeadSnapshot Head(int month, long seq, long rows) => new(
new DateTime(2026, month, 1, 0, 0, 0, DateTimeKind.Utc), seq, Enumerable.Repeat((byte)seq, 32).ToArray(),
null, null, rows, 0, new DateTime(2026, month, 2, 0, 0, 0, DateTimeKind.Utc));
private static (AuditChainHeadExportService Service, FakeStore Store, RecordingSink Sink) Create(
bool exportUnchanged = false, AuditChainHeadExportStatus? status = null, TimeProvider? time = null)
{
var store = new FakeStore();
var sink = new RecordingSink();
var services = new ServiceCollection();
services.AddScoped<IAuditChainHeadStore>(_ => store);
var options = Options.Create(new AuditLogHashChainOptions
{
HeadExport = new AuditChainHeadExportOptions { Enabled = true, ExportUnchanged = exportUnchanged },
});
var service = new AuditChainHeadExportService(
services.BuildServiceProvider().GetRequiredService<IServiceScopeFactory>(),
options, sink, "central-a", NullLogger<AuditChainHeadExportService>.Instance, time, status);
return (service, store, sink);
}
/// <summary>First tick: every head; next tick: only the head that moved; unchanged: nothing.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Tick_ExportsAllHeadsFirst_ThenOnlyChangedOnes()
{
var (service, store, sink) = Create();
store.Heads.AddRange([Head(4, 10, 10), Head(5, 20, 20)]);
Assert.Equal(2, await service.TickAsync(default));
Assert.Equal(0, await service.TickAsync(default));
store.Heads[1] = Head(5, 25, 25);
Assert.Equal(1, await service.TickAsync(default));
// A per-channel purge (row -> tombstone) keeps rows + tombstones, so it is not a change;
// a row disappearing without a tombstone is.
store.Heads[0] = Head(4, 10, 9);
Assert.Equal(1, await service.TickAsync(default));
Assert.Equal(3, sink.Writes.Count);
Assert.Equal(["2026-04", "2026-05"], sink.Writes[0].Select(r => r.Month));
var moved = Assert.Single(sink.Writes[1]);
Assert.Equal(("2026-05", 25L, string.Concat(Enumerable.Repeat("19", 32))), (moved.Month, moved.LastSeq, moved.LastHash));
Assert.Equal("central-a", moved.Node);
Assert.Equal(AuditChainHeadRecord.CurrentVersion, moved.V);
}
/// <summary>ExportUnchanged re-exports every head every tick.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Tick_WithExportUnchanged_ExportsEveryHeadEveryTick()
{
var (service, store, _) = Create(exportUnchanged: true);
store.Heads.AddRange([Head(4, 10, 10), Head(5, 20, 20)]);
Assert.Equal(2, await service.TickAsync(default));
Assert.Equal(2, await service.TickAsync(default));
}
/// <summary>A failed write is contained and the same heads go out on the next tick.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task Tick_AfterAFailedWrite_RetriesTheSameHeads()
{
var (service, store, sink) = Create();
store.Heads.Add(Head(4, 10, 10));
sink.Fail = true;
Assert.Equal(0, await service.TickAsync(default));
sink.Fail = false;
Assert.Equal(1, await service.TickAsync(default));
Assert.Equal(10, Assert.Single(Assert.Single(sink.Writes)).LastSeq);
}
/// <summary>
/// ScadaBridge#115: a failed tick bumps the failure counter metric and the status
/// (consecutive + total + last error); the next success clears the consecutive count.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task FailedTick_RecordsMetricAndStatus_SuccessResetsConsecutive()
{
var status = new AuditChainHeadExportStatus();
var (service, store, sink) = Create(status: status);
store.Heads.Add(Head(4, 10, 10));
long measured = 0;
using var listener = new System.Diagnostics.Metrics.MeterListener();
listener.InstrumentPublished = (i, l) =>
{
if (i.Name == "scadabridge.audit.chain_head_export.failures")
{
l.EnableMeasurementEvents(i);
}
};
listener.SetMeasurementEventCallback<long>((_, v, _, _) => Interlocked.Add(ref measured, v));
listener.Start();
sink.Fail = true;
await service.TickAsync(default);
await service.TickAsync(default);
Assert.Equal(2, Interlocked.Read(ref measured));
Assert.Equal(2, status.ConsecutiveFailures);
Assert.Equal(2, status.TotalFailures);
Assert.Equal("share offline", status.LastError);
Assert.Null(status.LastSuccessUtc);
sink.Fail = false;
await service.TickAsync(default);
Assert.Equal(0, status.ConsecutiveFailures);
Assert.Equal(2, status.TotalFailures);
Assert.NotNull(status.LastSuccessUtc);
Assert.Equal(2, Interlocked.Read(ref measured));
}
/// <summary>The validator ignores a disabled export and checks each sink's settings when enabled.</summary>
/// <param name="configure">Which settings to apply.</param>
/// <param name="expectedError">A fragment of the expected failure, or null when valid.</param>
[Theory]
[InlineData("disabled-bad", null)]
[InlineData("file-ok", null)]
[InlineData("file-relative", "File:Directory")]
[InlineData("file-missing", "File:Directory")]
[InlineData("syslog-ok", null)]
[InlineData("syslog-no-host", "Syslog:Host")]
[InlineData("syslog-bad-port", "Syslog:Port")]
[InlineData("syslog-bad-facility", "Syslog:Facility")]
[InlineData("interval-zero", "IntervalMinutes")]
public void Validator_ChecksTheSelectedSink(string configure, string? expectedError)
{
var root = OperatingSystem.IsWindows() ? @"C:\heads" : "/var/heads";
var export = configure switch
{
"disabled-bad" => new AuditChainHeadExportOptions { Enabled = false, IntervalMinutes = 0 },
"file-ok" => new AuditChainHeadExportOptions { Enabled = true, File = { Directory = root } },
"file-relative" => new AuditChainHeadExportOptions { Enabled = true, File = { Directory = "heads" } },
"file-missing" => new AuditChainHeadExportOptions { Enabled = true },
"syslog-ok" => new AuditChainHeadExportOptions { Enabled = true, Sink = AuditChainHeadSinkKind.Syslog, Syslog = { Host = "collector" } },
"syslog-no-host" => new AuditChainHeadExportOptions { Enabled = true, Sink = AuditChainHeadSinkKind.Syslog },
"syslog-bad-port" => new AuditChainHeadExportOptions { Enabled = true, Sink = AuditChainHeadSinkKind.Syslog, Syslog = { Host = "c", Port = 0 } },
"syslog-bad-facility" => new AuditChainHeadExportOptions { Enabled = true, Sink = AuditChainHeadSinkKind.Syslog, Syslog = { Host = "c", Facility = 24 } },
_ => new AuditChainHeadExportOptions { Enabled = true, IntervalMinutes = 0, File = { Directory = root } },
};
var result = new AuditLogHashChainOptionsValidator().Validate(null, new AuditLogHashChainOptions { HeadExport = export });
if (expectedError is null)
{
Assert.True(result.Succeeded, result.FailureMessage);
}
else
{
Assert.True(result.Failed);
Assert.Contains(expectedError, result.FailureMessage);
}
}
}
@@ -1,135 +0,0 @@
using System.Net;
using System.Net.Sockets;
using System.Text;
using System.Text.Json;
using ZB.MOM.WW.ScadaBridge.AuditLog.Central.HeadExport;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
namespace ZB.MOM.WW.ScadaBridge.AuditLog.Tests.Central.HeadExport;
/// <summary>
/// The two off-box chain-head sinks (ScadaBridge#107 item 1): the append-only JSON-lines file
/// sink, and RFC 5424 syslog over UDP and TCP (octet-counted framing).
/// </summary>
public sealed class AuditChainHeadSinkTests : IDisposable
{
private readonly DirectoryInfo _dir = Directory.CreateTempSubdirectory("head-sink-");
/// <inheritdoc />
public void Dispose() => _dir.Delete(recursive: true);
private static AuditChainHeadRecord Record(string month, long seq) => new(
1, month, seq, new string('a', 64), null, null, seq, 0,
new DateTime(2026, 5, 3, 0, 0, 0, DateTimeKind.Utc), new DateTime(2026, 5, 3, 1, 0, 0, DateTimeKind.Utc), "central-a");
private sealed class FixedClock(DateTimeOffset now) : TimeProvider
{
public override DateTimeOffset GetUtcNow() => now;
}
/// <summary>
/// Writes append to the node's file for the day — never truncate it — one JSON record per
/// line, and a pre-existing line survives.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task FileSink_AppendsJsonLines_ToThePerNodePerDayFile_WithoutTruncating()
{
var clock = new FixedClock(new DateTimeOffset(2026, 5, 3, 1, 0, 0, TimeSpan.Zero));
var sink = new FileAuditChainHeadSink(_dir.FullName, "central-a", clock);
var path = sink.PathFor(clock.GetUtcNow().UtcDateTime);
Assert.Equal(Path.Combine(_dir.FullName, "2026", "audit-chain-heads-2026-05-03-central-a.jsonl"), path);
Directory.CreateDirectory(Path.GetDirectoryName(path)!);
await File.WriteAllTextAsync(path, "earlier line\n");
await sink.WriteAsync([Record("2026-04", 3), Record("2026-05", 7)], default);
await sink.WriteAsync([Record("2026-05", 9)], default);
var lines = await File.ReadAllLinesAsync(path);
Assert.Equal(4, lines.Length);
Assert.Equal("earlier line", lines[0]);
var parsed = lines.Skip(1).Select(l => JsonSerializer.Deserialize<AuditChainHeadRecord>(l, new JsonSerializerOptions(JsonSerializerDefaults.Web))!).ToList();
Assert.Equal([3L, 7L, 9L], parsed.Select(r => r.LastSeq));
Assert.Equal(Record("2026-05", 9), parsed[2]);
}
/// <summary>A relative export directory is refused.</summary>
[Fact]
public void FileSink_RejectsARelativeDirectory()
{
Assert.Throws<ArgumentException>(() => new FileAuditChainHeadSink("relative/dir", "central-a"));
}
/// <summary>UDP: one RFC 5424 datagram per record — PRI, version, MSGID, nil SD, JSON body.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task SyslogSink_Udp_SendsOneRfc5424DatagramPerRecord()
{
using var server = new UdpClient(new IPEndPoint(IPAddress.Loopback, 0));
var port = ((IPEndPoint)server.Client.LocalEndPoint!).Port;
var sink = new SyslogAuditChainHeadSink(
new AuditChainHeadSyslogSinkOptions { Host = "127.0.0.1", Port = port, Protocol = AuditSyslogProtocol.Udp, Facility = 13 },
hostName: "central a", time: new FixedClock(new DateTimeOffset(2026, 5, 3, 1, 2, 3, 456, TimeSpan.Zero)));
await sink.WriteAsync([Record("2026-04", 3), Record("2026-05", 7)], default);
var first = Encoding.UTF8.GetString((await server.ReceiveAsync().WaitAsync(TimeSpan.FromSeconds(5))).Buffer);
var second = Encoding.UTF8.GetString((await server.ReceiveAsync().WaitAsync(TimeSpan.FromSeconds(5))).Buffer);
// facility 13 (log audit) * 8 + severity 5 (notice) = 109; the space in the host name is dropped.
Assert.StartsWith($"<109>1 2026-05-03T01:02:03.456Z centrala scadabridge {Environment.ProcessId} chainhead - {{", first);
AssertRecordBody(first, 3);
AssertRecordBody(second, 7);
}
/// <summary>TCP: octet-counted frames (RFC 6587), one per record, on one connection.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task SyslogSink_Tcp_SendsOctetCountedFrames()
{
var listener = new TcpListener(IPAddress.Loopback, 0);
listener.Start();
try
{
var port = ((IPEndPoint)listener.LocalEndpoint).Port;
var received = Task.Run(async () =>
{
using var client = await listener.AcceptTcpClientAsync();
using var ms = new MemoryStream();
await client.GetStream().CopyToAsync(ms);
return ms.ToArray();
});
var sink = new SyslogAuditChainHeadSink(
new AuditChainHeadSyslogSinkOptions { Host = "127.0.0.1", Port = port, Protocol = AuditSyslogProtocol.Tcp });
await sink.WriteAsync([Record("2026-04", 3), Record("2026-05", 7)], default);
var bytes = await received.WaitAsync(TimeSpan.FromSeconds(5));
var frames = new List<string>();
var i = 0;
while (i < bytes.Length)
{
var space = Array.IndexOf(bytes, (byte)' ', i);
var length = int.Parse(Encoding.ASCII.GetString(bytes, i, space - i));
frames.Add(Encoding.UTF8.GetString(bytes, space + 1, length));
i = space + 1 + length;
}
Assert.Equal(2, frames.Count);
Assert.All(frames, f => Assert.StartsWith("<109>1 ", f));
AssertRecordBody(frames[0], 3);
AssertRecordBody(frames[1], 7);
}
finally
{
listener.Stop();
}
}
private static void AssertRecordBody(string message, long seq)
{
var json = message[message.IndexOf('{')..];
var record = JsonSerializer.Deserialize<AuditChainHeadRecord>(json, new JsonSerializerOptions(JsonSerializerDefaults.Web))!;
Assert.Equal(seq, record.LastSeq);
Assert.Equal(new string('a', 64), record.LastHash);
}
}
@@ -0,0 +1,42 @@
using Microsoft.Extensions.Configuration;
using ZB.MOM.WW.ScadaBridge.AuditLog.Central;
namespace ZB.MOM.WW.ScadaBridge.AuditLog.Tests.Central;
/// <summary>
/// The hash chain and the maintenance login were removed on 2026-11-15; a node still carrying
/// their settings (DEV/QA have <c>AuditLog__HashChain__Enabled=true</c> in the Central service
/// env) must boot and be told the keys are ignored.
/// </summary>
public class RetiredAuditSettingsWarningTests
{
private static IConfiguration Config(params (string Key, string Value)[] values) =>
new ConfigurationBuilder()
.AddInMemoryCollection(values.Select(v => new KeyValuePair<string, string?>(v.Key, v.Value)))
.Build();
/// <summary>The env var left on DEV/QA (and the maintenance login) are both reported.</summary>
[Fact]
public void FindRetired_ReportsTheHashChainSection_AndTheMaintenanceConnectionString()
{
var config = Config(
("AuditLog:HashChain:Enabled", "true"),
("AuditLog:MaintenanceConnectionString", "Server=x;Database=y"));
Assert.Equal(
[RetiredAuditSettingsWarning.HashChainSection, RetiredAuditSettingsWarning.MaintenanceConnectionStringKey],
RetiredAuditSettingsWarning.FindRetired(config));
}
/// <summary>A clean configuration (and the archive settings that remain) reports nothing.</summary>
[Fact]
public void FindRetired_ReportsNothing_ForCurrentSettings()
{
var config = Config(
("AuditLog:Archive:Enabled", "true"),
("AuditLog:RetentionDays", "365"),
("AuditLog:MaintenanceConnectionString", " "));
Assert.Empty(RetiredAuditSettingsWarning.FindRetired(config));
}
}
@@ -69,9 +69,9 @@ public class CommandTreeTests
Assert.Contains("bundle", groupNames); Assert.Contains("bundle", groupNames);
} }
/// <summary>Verifies that the audit command group exposes the query, export, verify-chain and archive subcommands.</summary> /// <summary>Verifies that the audit command group exposes the query, export and archive subcommands, and no hash-chain verify (removed 2026-11-15).</summary>
[Fact] [Fact]
public void AuditCommandGroup_HasQueryExportAndVerifyChain() public void AuditCommandGroup_HasQueryExportAndArchive()
{ {
// Pin the audit sub-command surface so a rename / accidental // Pin the audit sub-command surface so a rename / accidental
// removal of one of these is caught. // removal of one of these is caught.
@@ -79,8 +79,9 @@ public class CommandTreeTests
var subNames = audit.Subcommands.Select(c => c.Name).ToHashSet(); var subNames = audit.Subcommands.Select(c => c.Name).ToHashSet();
Assert.Contains("query", subNames); Assert.Contains("query", subNames);
Assert.Contains("export", subNames); Assert.Contains("export", subNames);
Assert.Contains("verify-chain", subNames);
Assert.Contains("archive", subNames); Assert.Contains("archive", subNames);
Assert.DoesNotContain("verify-chain", subNames);
Assert.DoesNotContain("verify-heads", subNames);
} }
/// <summary>Verifies that the bundle command group exposes the export, preview and import subcommands.</summary> /// <summary>Verifies that the bundle command group exposes the export, preview and import subcommands.</summary>
@@ -18,17 +18,15 @@ public class AuditArchiveCommandTests
private const string ListBody = private const string ListBody =
"{\"enabled\":true,\"archives\":[{\"name\":\"" + Name + "\",\"partition\":\"2025-10\",\"status\":\"Purged\"," + "{\"enabled\":true,\"archives\":[{\"name\":\"" + Name + "\",\"partition\":\"2025-10\",\"status\":\"Purged\"," +
"\"rowCount\":11,\"chainedRowCount\":10,\"dataBytes\":4096}]}"; "\"rowCount\":11,\"dataBytes\":4096}]}";
private const string VerifiedBody = private const string VerifiedBody =
"{\"name\":\"" + Name + "\",\"partition\":\"2025-10\",\"manifestStatus\":\"Purged\",\"verified\":true,\"filesIntact\":true," + "{\"name\":\"" + Name + "\",\"partition\":\"2025-10\",\"manifestStatus\":\"Purged\",\"verified\":true,\"filesIntact\":true," +
"\"rowsRead\":11,\"chains\":[{\"chain\":{\"partition\":\"2025-10\",\"status\":\"Intact\",\"rowsVerified\":10," + "\"rowsRead\":11}";
"\"tombstonesApplied\":2,\"unchainedRows\":1},\"anchor\":\"Matches\",\"anchorDetail\":\"ends at the anchor\"}]}";
private const string MismatchBody = private const string MismatchBody =
"{\"name\":\"" + Name + "\",\"partition\":\"2025-10\",\"manifestStatus\":\"Purged\",\"verified\":false,\"filesIntact\":true," + "{\"name\":\"" + Name + "\",\"partition\":\"2025-10\",\"manifestStatus\":\"Purged\",\"verified\":false,\"filesIntact\":false," +
"\"rowsRead\":11,\"chains\":[{\"chain\":{\"partition\":\"2025-10\",\"status\":\"Intact\",\"rowsVerified\":10," + "\"fileProblem\":\"The data file holds 10 rows; the manifest records 11.\",\"rowsRead\":10}";
"\"tombstonesApplied\":0,\"unchainedRows\":0},\"anchor\":\"Mismatch\",\"anchorDetail\":\"hash differs\"}]}";
/// <summary>The audit group carries the archive group with list + verify + cleanup (ScadaBridge#109).</summary> /// <summary>The audit group carries the archive group with list + verify + cleanup (ScadaBridge#109).</summary>
[Fact] [Fact]
@@ -60,10 +58,10 @@ public class AuditArchiveCommandTests
/// <param name="expectedText">Text the report must contain.</param> /// <param name="expectedText">Text the report must contain.</param>
/// <returns>A task that represents the asynchronous operation.</returns> /// <returns>A task that represents the asynchronous operation.</returns>
[Theory] [Theory]
[InlineData(VerifiedBody, "table", 0, "anchor Matches")] [InlineData(VerifiedBody, "table", 0, "Rows read : 11")]
[InlineData(VerifiedBody, "json", 0, "\"verified\":true")] [InlineData(VerifiedBody, "json", 0, "\"verified\":true")]
[InlineData(MismatchBody, "table", 3, "Verified : NO")] [InlineData(MismatchBody, "table", 3, "Verified : NO")]
[InlineData(MismatchBody, "json", 3, "\"anchor\":\"Mismatch\"")] [InlineData(MismatchBody, "json", 3, "\"filesIntact\":false")]
public async Task Verify_SendsVerifyAuditArchive_AndMapsVerdictToExitCode( public async Task Verify_SendsVerifyAuditArchive_AndMapsVerdictToExitCode(
string body, string format, int expectedExit, string expectedText) string body, string format, int expectedExit, string expectedText)
{ {
@@ -27,14 +27,14 @@ public class AuditCommandsScaffoldTests
Assert.False(string.IsNullOrWhiteSpace(audit.Description)); Assert.False(string.IsNullOrWhiteSpace(audit.Description));
} }
/// <summary>Verifies that the audit group exposes the query, export, tree, verify-chain, verify-heads, backfill-source-node and archive subcommands.</summary> /// <summary>Verifies that the audit group exposes the query, export, tree, backfill-source-node and archive subcommands (verify-chain / verify-heads removed with the hash chain, 2026-11-15).</summary>
[Fact] [Fact]
public void Audit_HasSevenSubcommands_QueryExportTreeVerifyChainVerifyHeadsBackfillSourceNodeArchive() public void Audit_HasFiveSubcommands_QueryExportTreeBackfillSourceNodeArchive()
{ {
var audit = BuildAudit(); var audit = BuildAudit();
var names = audit.Subcommands.Select(c => c.Name).OrderBy(n => n).ToArray(); var names = audit.Subcommands.Select(c => c.Name).OrderBy(n => n).ToArray();
Assert.Equal( Assert.Equal(
new[] { "archive", "backfill-source-node", "export", "query", "tree", "verify-chain", "verify-heads" }, new[] { "archive", "backfill-source-node", "export", "query", "tree" },
names); names);
} }
@@ -54,7 +54,7 @@ public class AuditCommandsScaffoldTests
Assert.Contains("query", text); Assert.Contains("query", text);
Assert.Contains("export", text); Assert.Contains("export", text);
Assert.Contains("tree", text); Assert.Contains("tree", text);
Assert.Contains("verify-chain", text); Assert.DoesNotContain("verify-chain", text);
Assert.Contains("backfill-source-node", text); Assert.Contains("backfill-source-node", text);
} }
@@ -65,7 +65,7 @@ public class AuditCommandsScaffoldTests
// `archive` is a group (list / verify, ScadaBridge#42; cleanup, ScadaBridge#109): check its leaves, not it. // `archive` is a group (list / verify, ScadaBridge#42; cleanup, ScadaBridge#109): check its leaves, not it.
var audit = BuildAudit(); var audit = BuildAudit();
var leaves = audit.Subcommands.SelectMany(c => c.Subcommands.Count == 0 ? [c] : c.Subcommands).ToList(); var leaves = audit.Subcommands.SelectMany(c => c.Subcommands.Count == 0 ? [c] : c.Subcommands).ToList();
Assert.Equal(9, leaves.Count); // + verify-heads (ScadaBridge#107), archive cleanup (ScadaBridge#109) Assert.Equal(7, leaves.Count); // query, export, tree, backfill-source-node, archive list|verify|cleanup
Assert.All(leaves, sub => Assert.All(leaves, sub =>
Assert.True(sub.Action != null, $"Leaf command '{sub.Name}' has no action.")); Assert.True(sub.Action != null, $"Leaf command '{sub.Name}' has no action."));
} }
@@ -91,12 +91,12 @@ public class AuditConfigDeprecationTests
} }
// The two groups are distinct objects with distinct subcommand sets: // The two groups are distinct objects with distinct subcommand sets:
// `audit` has query/export/verify-chain; `audit-config` has only query. // `audit` has query/export/archive; `audit-config` has only query.
var audit = root.Subcommands.Single(c => c.Name == "audit"); var audit = root.Subcommands.Single(c => c.Name == "audit");
var auditConfig = root.Subcommands.Single(c => c.Name == "audit-config"); var auditConfig = root.Subcommands.Single(c => c.Name == "audit-config");
Assert.NotSame(audit, auditConfig); Assert.NotSame(audit, auditConfig);
Assert.Contains(audit.Subcommands, c => c.Name == "verify-chain"); Assert.Contains(audit.Subcommands, c => c.Name == "archive");
Assert.DoesNotContain(auditConfig.Subcommands, c => c.Name == "verify-chain"); Assert.DoesNotContain(auditConfig.Subcommands, c => c.Name == "archive");
// `audit-config` carries the deprecated `audit-log` alias; `audit` does not. // `audit-config` carries the deprecated `audit-log` alias; `audit` does not.
Assert.Contains(AuditLogCommands.DeprecatedAlias, auditConfig.Aliases); Assert.Contains(AuditLogCommands.DeprecatedAlias, auditConfig.Aliases);
@@ -1,161 +0,0 @@
using System.Net;
using System.Net.Sockets;
using System.Text;
using System.Text.Json;
using ZB.MOM.WW.ScadaBridge.CLI.Commands;
namespace ZB.MOM.WW.ScadaBridge.CLI.Tests.Commands;
/// <summary>
/// Tests for the <c>scadabridge audit verify-chain</c> subcommand (ScadaBridge#41). The
/// command sends the <c>VerifyAuditChain</c> management command for the month and maps
/// the verification status onto the exit code: 0 intact / not chained, 3 broken.
/// </summary>
[Collection("Console")]
public class AuditVerifyChainCommandTests
{
private const string IntactBody =
"{\"partition\":\"2026-05\",\"status\":\"Intact\",\"rowsVerified\":42,\"tombstonesApplied\":1,\"headSeq\":43,\"unchainedRows\":0}";
private const string BrokenBody =
"{\"partition\":\"2026-05\",\"status\":\"Broken\",\"rowsVerified\":6,\"tombstonesApplied\":0,\"headSeq\":43,\"unchainedRows\":2," +
"\"firstBreak\":{\"partition\":\"2026-05\",\"chainSeq\":7,\"eventId\":\"11111111-2222-3333-4444-555555555555\",\"kind\":\"HashMismatch\",\"detail\":\"edited\"}}";
/// <summary>
/// CLI round trip: the request carries <c>VerifyAuditChain</c> + the month, and the
/// server's verdict drives the exit code and the report.
/// </summary>
/// <param name="body">The verification result the fake management endpoint serves.</param>
/// <param name="format">Output format.</param>
/// <param name="expectedExit">Expected exit code.</param>
/// <param name="expectedText">Text the report must contain.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
[Theory]
[InlineData(IntactBody, "table", 0, "Status : Intact")]
[InlineData(IntactBody, "json", 0, "\"status\":\"Intact\"")]
[InlineData(BrokenBody, "table", 3, "eventId : 11111111-2222-3333-4444-555555555555")]
[InlineData(BrokenBody, "json", 3, "\"chainSeq\":7")]
public async Task VerifyChain_SendsVerifyAuditChain_AndMapsVerdictToExitCode(
string body, string format, int expectedExit, string expectedText)
{
var listener = new TcpListener(IPAddress.Loopback, 0);
listener.Start();
try
{
var port = ((IPEndPoint)listener.LocalEndpoint).Port;
string? requestBody = null;
var server = Task.Run(async () =>
{
using var client = await listener.AcceptTcpClientAsync();
await using var stream = client.GetStream();
using var reader = new StreamReader(stream, Encoding.UTF8, leaveOpen: true);
var length = 0;
while (await reader.ReadLineAsync() is { Length: > 0 } line)
if (line.StartsWith("Content-Length:", StringComparison.OrdinalIgnoreCase))
length = int.Parse(line[15..].Trim());
var buffer = new char[length];
var read = 0;
while (read < length)
{
var count = await reader.ReadAsync(buffer.AsMemory(read));
if (count == 0) throw new EndOfStreamException();
read += count;
}
requestBody = new string(buffer);
var bytes = Encoding.UTF8.GetBytes(body);
var headers = Encoding.ASCII.GetBytes(
$"HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {bytes.Length}\r\nConnection: close\r\n\r\n");
await stream.WriteAsync(headers);
await stream.WriteAsync(bytes);
});
var root = AuditCommandTestHarness.BuildRoot();
var (exit, output, _) = AuditCommandTestHarness.Invoke(
root, "audit", "verify-chain", "--month", "2026-05",
"--url", $"http://127.0.0.1:{port}", "--username", "u", "--password", "p", "--format", format);
await server.WaitAsync(TimeSpan.FromSeconds(5));
Assert.Equal(expectedExit, exit);
Assert.Contains(expectedText, output);
using var payload = JsonDocument.Parse(requestBody!);
Assert.Equal("VerifyAuditChain", payload.RootElement.GetProperty("command").GetString());
var month = payload.RootElement.GetProperty("payload").EnumerateObject()
.First(p => string.Equals(p.Name, "month", StringComparison.OrdinalIgnoreCase)).Value.GetString();
Assert.Equal("2026-05", month);
}
finally
{
listener.Stop();
}
}
/// <summary>Verifies that a malformed month value exits non-zero without contacting the server.</summary>
[Fact]
public void VerifyChain_MalformedMonth_ExitsNonZero()
{
var root = AuditCommandTestHarness.BuildRoot();
var (exit, _, _) = AuditCommandTestHarness.Invoke(
root, "audit", "verify-chain", "--month", "2026-13");
Assert.NotEqual(0, exit);
}
/// <summary>Verifies that omitting the month option produces the required-option error.</summary>
[Fact]
public void VerifyChain_MissingMonth_ProducesRequiredFlagError()
{
var root = AuditCommandTestHarness.BuildRoot();
var (exit, _, err) = AuditCommandTestHarness.Invoke(root, "audit", "verify-chain");
Assert.NotEqual(0, exit);
Assert.Contains("--month", err);
}
/// <summary>
/// ScadaBridge#139: the table report shows the chain cutoff and the pre-cutoff rows, and a
/// month whose backlog is out of scope still exits 0 (pre-cutoff rows are never a break).
/// </summary>
[Fact]
public void Render_Table_ShowsCutoffAndPreCutoffRows()
{
const string body = "{\"partition\":\"2026-11\",\"status\":\"Intact\",\"rowsVerified\":12,\"tombstonesApplied\":0," +
"\"purgedThroughSeq\":null,\"headSeq\":12,\"unchainedRows\":0,\"firstBreak\":null," +
"\"preCutoffRows\":3441,\"chainFromUtc\":\"2026-11-13T09:30:00.1234567Z\"}";
using var output = new StringWriter();
var exit = AuditVerifyChainHelpers.Render(body, "table", output);
Assert.Equal(0, exit);
Assert.Contains("Chain from : 2026-11-13T09:30:00.1234567Z", output.ToString());
Assert.Contains("Pre-cutoff rows : 3441", output.ToString());
}
/// <summary>A legacy (whole-table) chain renders without a cutoff.</summary>
[Fact]
public void Render_Table_NoCutoff_SaysWholeTable()
{
const string body = "{\"partition\":\"2026-05\",\"status\":\"Intact\",\"rowsVerified\":1,\"unchainedRows\":0}";
using var output = new StringWriter();
Assert.Equal(0, AuditVerifyChainHelpers.Render(body, "table", output));
Assert.Contains("Chain from : - (whole table in scope)", output.ToString());
Assert.Contains("Pre-cutoff rows : 0", output.ToString());
}
/// <summary>Verifies that month validation accepts only values in <c>yyyy-MM</c> format.</summary>
/// <param name="month">The month string to validate.</param>
/// <param name="expected">Whether the month is expected to be valid.</param>
[Theory]
[InlineData("2026-05", true)]
[InlineData("2026-01", true)]
[InlineData("2026-12", true)]
[InlineData("2026-13", false)]
[InlineData("2026-00", false)]
[InlineData("2026-5", false)]
[InlineData("not-a-month", false)]
[InlineData("", false)]
public void IsValidMonth_ValidatesYyyyMm(string month, bool expected)
{
Assert.Equal(expected, AuditVerifyChainHelpers.IsValidMonth(month));
}
}
@@ -1,158 +0,0 @@
using System.Net;
using System.Net.Sockets;
using System.Text;
using System.Text.Json;
using ZB.MOM.WW.ScadaBridge.CLI.Commands;
namespace ZB.MOM.WW.ScadaBridge.CLI.Tests.Commands;
/// <summary>
/// Tests for <c>scadabridge audit verify-heads</c> (ScadaBridge#107 item 1): reading off-box
/// exported chain heads (file-sink lines and syslog-collector lines), collapsing duplicates,
/// sending <c>VerifyAuditChainHeads</c>, and mapping the verdict to the exit code.
/// </summary>
[Collection("Console")]
public sealed class AuditVerifyHeadsCommandTests : IDisposable
{
private readonly DirectoryInfo _dir = Directory.CreateTempSubdirectory("verify-heads-");
/// <inheritdoc />
public void Dispose() => _dir.Delete(recursive: true);
private static string Line(string month, long seq, char hash, string exportedAt = "2026-05-02T00:00:00Z", string node = "central-a") =>
"{\"v\":1,\"month\":\"" + month + "\",\"lastSeq\":" + seq + ",\"lastHash\":\"" + new string(hash, 64)
+ "\",\"purgedThroughSeq\":null,\"purgedThroughHash\":null,\"chainedRows\":" + seq + ",\"tombstones\":0,"
+ "\"headUpdatedAtUtc\":\"2026-05-02T00:00:00Z\",\"exportedAtUtc\":\"" + exportedAt + "\",\"node\":\"" + node + "\"}";
/// <summary>
/// File-sink lines and RFC 5424 syslog lines both parse; junk is skipped; the same head
/// exported by both nodes (and re-exported) collapses to one record.
/// </summary>
[Fact]
public void ReadRecords_ParsesFileAndSyslogLines_SkipsJunk_AndCollapsesDuplicates()
{
Directory.CreateDirectory(Path.Combine(_dir.FullName, "2026"));
File.WriteAllLines(Path.Combine(_dir.FullName, "2026", "audit-chain-heads-2026-05-02-central-a.jsonl"),
[
Line("2026-05", 10, 'a'),
Line("2026-05", 12, 'b'),
"not json at all",
"",
]);
File.WriteAllLines(Path.Combine(_dir.FullName, "syslog.log"),
[
"Nov 10 03:00:00 collector <109>1 2026-05-02T00:00:00.000Z central-b scadabridge 42 chainhead - "
+ Line("2026-05", 12, 'b', "2026-05-02T01:00:00Z", "central-b"),
"<109>1 2026-05-02T00:00:00.000Z central-b scadabridge 42 chainhead - " + Line("2026-04", 7, 'c'),
]);
File.WriteAllText(Path.Combine(_dir.FullName, "ignored.csv"), Line("2026-03", 1, 'd'));
var read = AuditVerifyHeadsHelpers.ReadRecords(_dir.FullName);
Assert.Equal(2, read.Files);
Assert.Equal(4, read.LinesRead);
Assert.Equal(1, read.LinesSkipped);
Assert.Equal(["2026-04/7", "2026-05/10", "2026-05/12"], read.Records.Select(r => $"{r.Month}/{r.LastSeq}"));
// The duplicate kept is the latest export.
Assert.Equal("central-b", read.Records.Single(r => r.LastSeq == 12).Node);
}
/// <summary>A record missing its hash or sequence is not a record.</summary>
/// <param name="line">The line.</param>
[Theory]
[InlineData("{\"v\":1,\"month\":\"2026-05\",\"lastSeq\":0,\"lastHash\":\"aa\"}")]
[InlineData("{\"v\":1,\"month\":\"2026-05\",\"lastSeq\":3}")]
[InlineData("{\"month\":\"2026-05\",\"lastSeq\":3,\"lastHash\":\"aa\"}")]
[InlineData("{ broken")]
public void TryParseLine_RejectsIncompleteRecords(string line)
{
Assert.Null(AuditVerifyHeadsHelpers.TryParseLine(line));
}
/// <summary>
/// Round trip: the request carries <c>VerifyAuditChainHeads</c> with the distinct records,
/// and the verdict drives the exit code (0 verified, 3 not).
/// </summary>
/// <param name="verified">Whether the fake server reports verified.</param>
/// <param name="format">Output format.</param>
/// <param name="expectedExit">Expected exit code.</param>
/// <param name="expectedText">Text the report must contain.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
[Theory]
[InlineData(true, "table", 0, "Verified : yes")]
[InlineData(false, "table", 3, "Mismatch")]
[InlineData(false, "json", 3, "\"verified\":false")]
public async Task VerifyHeads_SendsTheRecords_AndMapsVerdictToExitCode(bool verified, string format, int expectedExit, string expectedText)
{
var file = Path.Combine(_dir.FullName, "heads.jsonl");
File.WriteAllLines(file, [Line("2026-05", 12, 'b'), Line("2026-05", 12, 'b', "2026-05-02T02:00:00Z")]);
var body = "{\"verified\":" + (verified ? "true" : "false") + ",\"recordsChecked\":1,\"checks\":[{\"month\":\"2026-05\","
+ "\"exportedSeq\":12,\"exportedAtUtc\":\"2026-05-02T02:00:00Z\",\"node\":\"central-a\",\"status\":\""
+ (verified ? "Matches" : "Mismatch") + "\",\"databaseSeq\":12,\"detail\":\"d\"}]}";
var listener = new TcpListener(IPAddress.Loopback, 0);
listener.Start();
try
{
var port = ((IPEndPoint)listener.LocalEndpoint).Port;
string? requestBody = null;
var server = Task.Run(async () =>
{
using var client = await listener.AcceptTcpClientAsync();
await using var stream = client.GetStream();
using var reader = new StreamReader(stream, Encoding.UTF8, leaveOpen: true);
var length = 0;
while (await reader.ReadLineAsync() is { Length: > 0 } line)
if (line.StartsWith("Content-Length:", StringComparison.OrdinalIgnoreCase))
length = int.Parse(line[15..].Trim());
var buffer = new char[length];
var read = 0;
while (read < length)
{
var count = await reader.ReadAsync(buffer.AsMemory(read));
if (count == 0) throw new EndOfStreamException();
read += count;
}
requestBody = new string(buffer);
var bytes = Encoding.UTF8.GetBytes(body);
var headers = Encoding.ASCII.GetBytes(
$"HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {bytes.Length}\r\nConnection: close\r\n\r\n");
await stream.WriteAsync(headers);
await stream.WriteAsync(bytes);
});
var root = AuditCommandTestHarness.BuildRoot();
var (exit, output, _) = AuditCommandTestHarness.Invoke(
root, "audit", "verify-heads", "--path", file,
"--url", $"http://127.0.0.1:{port}", "--username", "u", "--password", "p", "--format", format);
await server.WaitAsync(TimeSpan.FromSeconds(5));
Assert.Equal(expectedExit, exit);
Assert.Contains(expectedText, output);
using var payload = JsonDocument.Parse(requestBody!);
Assert.Equal("VerifyAuditChainHeads", payload.RootElement.GetProperty("command").GetString());
var records = payload.RootElement.GetProperty("payload").EnumerateObject()
.First(p => string.Equals(p.Name, "records", StringComparison.OrdinalIgnoreCase)).Value;
Assert.Equal(1, records.GetArrayLength());
Assert.Equal(new string('b', 64), records[0].EnumerateObject()
.First(p => string.Equals(p.Name, "lastHash", StringComparison.OrdinalIgnoreCase)).Value.GetString());
}
finally
{
listener.Stop();
}
}
/// <summary>No records found is an input error, and nothing is sent.</summary>
[Fact]
public void VerifyHeads_NoRecords_ExitsOneWithoutContactingTheServer()
{
var file = Path.Combine(_dir.FullName, "empty.jsonl");
File.WriteAllText(file, "nothing here\n");
var root = AuditCommandTestHarness.BuildRoot();
var (exit, _, _) = AuditCommandTestHarness.Invoke(
root, "audit", "verify-heads", "--path", file, "--url", "http://127.0.0.1:1", "--username", "u", "--password", "p");
Assert.Equal(1, exit);
}
}
@@ -45,7 +45,7 @@ public class ManagementSurfaceParityTests
} }
private static readonly HashSet<string> AuditManagementLeaves = private static readonly HashSet<string> AuditManagementLeaves =
["audit verify-chain", "audit verify-heads", "audit archive list", "audit archive verify", "audit archive cleanup"]; ["audit archive list", "audit archive verify", "audit archive cleanup"];
private static async Task<ConcurrentDictionary<string, string>> ProbeProductionTree(string? omitGroup = null) private static async Task<ConcurrentDictionary<string, string>> ProbeProductionTree(string? omitGroup = null)
{ {
@@ -56,12 +56,6 @@ public class ManagementSurfaceParityTests
await File.WriteAllTextAsync(file, "{}"); await File.WriteAllTextAsync(file, "{}");
var csv = Path.Combine(directory.FullName, "native.csv"); var csv = Path.Combine(directory.FullName, "native.csv");
await File.WriteAllTextAsync(csv, "SourceName,Connection,SourceReference,Filter\nSource,Connection,Path,\n"); await File.WriteAllTextAsync(csv, "SourceName,Connection,SourceReference,Filter\nSource,Connection,Path,\n");
// `audit verify-heads` (ScadaBridge#107) reads exported chain heads before it sends anything.
HeadsFile = Path.Combine(directory.FullName, "heads.jsonl");
await File.WriteAllTextAsync(HeadsFile,
"{\"v\":1,\"month\":\"2026-05\",\"lastSeq\":3,\"lastHash\":\"" + new string('a', 64)
+ "\",\"purgedThroughSeq\":null,\"purgedThroughHash\":null,\"chainedRows\":3,\"tombstones\":0,"
+ "\"headUpdatedAtUtc\":\"2026-05-02T00:00:00Z\",\"exportedAtUtc\":\"2026-05-02T00:00:00Z\",\"node\":\"central-a\"}\n");
using var stop = new CancellationTokenSource(TimeSpan.FromSeconds(30)); using var stop = new CancellationTokenSource(TimeSpan.FromSeconds(30));
var listener = new TcpListener(IPAddress.Loopback, 0); var listener = new TcpListener(IPAddress.Loopback, 0);
listener.Start(); listener.Start();
@@ -102,10 +96,9 @@ public class ManagementSurfaceParityTests
foreach (var (leaf, path) in Leaves(root, [])) foreach (var (leaf, path) in Leaves(root, []))
{ {
// Separate REST and persistent SignalR surfaces, not management contracts. // Separate REST and persistent SignalR surfaces, not management contracts.
// `audit verify-chain` (VerifyAuditChain, ScadaBridge#41), `audit verify-heads` // `audit archive list|verify|cleanup` (ListAuditArchives / VerifyAuditArchive /
// (VerifyAuditChainHeads, ScadaBridge#107) and `audit archive // CleanupAuditArchives, ScadaBridge#42/#109) are the audit leaves that ARE
// list|verify` (ListAuditArchives / VerifyAuditArchive, ScadaBridge#42) are the // management contracts, so they stay in the probe.
// audit leaves that ARE management contracts, so they stay in the probe.
if (path.Length == 0 || (path[0] == "audit" && !AuditManagementLeaves.Contains(string.Join(' ', path))) if (path.Length == 0 || (path[0] == "audit" && !AuditManagementLeaves.Contains(string.Join(' ', path)))
|| path[0] == omitGroup || path[0] == omitGroup
|| string.Join(' ', path) == "debug stream") continue; || string.Join(' ', path) == "debug stream") continue;
@@ -142,11 +135,8 @@ public class ManagementSurfaceParityTests
foreach (var entry in Leaves(child, [.. path, child.Name])) yield return entry; foreach (var entry in Leaves(child, [.. path, child.Name])) yield return entry;
} }
private static string HeadsFile = "";
private static string ValueFor(Option option, string path, string file, string csv) private static string ValueFor(Option option, string path, string file, string csv)
{ {
if (path == "audit verify-heads" && option.Name == "--path") return HeadsFile;
var type = option.GetType().GetGenericArguments().FirstOrDefault(); var type = option.GetType().GetGenericArguments().FirstOrDefault();
type = Nullable.GetUnderlyingType(type ?? typeof(string)) ?? type; type = Nullable.GetUnderlyingType(type ?? typeof(string)) ?? type;
if (type == typeof(int) || type == typeof(long) || type == typeof(double)) return "1"; if (type == typeof(int) || type == typeof(long) || type == typeof(double)) return "1";
@@ -47,11 +47,6 @@ namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Tests;
/// one-time ops procedure; the append-only invariant still applies to all /// one-time ops procedure; the append-only invariant still applies to all
/// other columns and all other UPDATE forms. /// other columns and all other UPDATE forms.
/// </description></item> /// </description></item>
/// <item><description>
/// <c>AuditLogHashChain.WriteLinksAsync</c> (ScadaBridge#41): the chaining job's
/// <c>UPDATE dbo.AuditLog SET ChainSeq, RowHash</c>, guarded by
/// <c>ChainSeq IS NULL</c> — it only ever fills the two hash-chain link columns once.
/// </description></item>
/// </list> /// </list>
/// The allow-list is applied in the file-scan test only /// The allow-list is applied in the file-scan test only
/// (<see cref="ConfigurationDatabase_ShouldNotContainAuditLogMutations"/>) — the /// (<see cref="ConfigurationDatabase_ShouldNotContainAuditLogMutations"/>) — the
@@ -105,9 +105,9 @@ public class AuditLogEntityTypeConfigurationTests : IDisposable
// C5: 10 canonical columns (EventId, OccurredAtUtc, Actor, Action, Outcome, // C5: 10 canonical columns (EventId, OccurredAtUtc, Actor, Action, Outcome,
// Channel[=Category], Target, SourceNode, CorrelationId, DetailsJson) + 6 // Channel[=Category], Target, SourceNode, CorrelationId, DetailsJson) + 6
// persisted computed columns (Kind, Status, SourceSiteId, ExecutionId, // persisted computed columns (Kind, Status, SourceSiteId, ExecutionId,
// ParentExecutionId, IngestedAtUtc) + 2 hash-chain link columns (ChainSeq, // ParentExecutionId, IngestedAtUtc) = 16. (The two hash-chain link columns were
// RowHash — ScadaBridge#41) = 18. // removed with the hash chain on 2026-11-15.)
Assert.Equal(18, properties.Count); Assert.Equal(16, properties.Count);
} }
/// <summary>Verifies that the channel property maps to the canonical category column.</summary> /// <summary>Verifies that the channel property maps to the canonical category column.</summary>
@@ -186,7 +186,6 @@ public class AuditLogEntityTypeConfigurationTests : IDisposable
var expected = new[] var expected = new[]
{ {
"IX_AuditLog_Actor_Occurred", "IX_AuditLog_Actor_Occurred",
"IX_AuditLog_ChainSeq", // hash chain (ScadaBridge#41)
"IX_AuditLog_Channel_Status_Occurred", "IX_AuditLog_Channel_Status_Occurred",
"IX_AuditLog_CorrelationId", "IX_AuditLog_CorrelationId",
"IX_AuditLog_Execution", "IX_AuditLog_Execution",
@@ -196,7 +195,6 @@ public class AuditLogEntityTypeConfigurationTests : IDisposable
"IX_AuditLog_ParentExecution", "IX_AuditLog_ParentExecution",
"IX_AuditLog_Site_Occurred", "IX_AuditLog_Site_Occurred",
"IX_AuditLog_Target_Occurred", "IX_AuditLog_Target_Occurred",
"IX_AuditLog_Unchained", // hash chain (ScadaBridge#41)
"UX_AuditLog_EventId_Occurred", // FlipAuditLogClusteredKey (ScadaBridge#111) "UX_AuditLog_EventId_Occurred", // FlipAuditLogClusteredKey (ScadaBridge#111)
// UX_AuditLog_EventId (single-column, non-aligned) is intentionally absent — // UX_AuditLog_EventId (single-column, non-aligned) is intentionally absent —
// dropped by AlignAuditLogEventIdUniqueness. // dropped by AlignAuditLogEventIdUniqueness.
@@ -1,14 +1,14 @@
using Parquet; using Parquet;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit; using Parquet.Schema;
using ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance; using ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance;
namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Tests.Maintenance; namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Tests.Maintenance;
/// <summary> /// <summary>
/// Storage-free tests for the AuditLog archive Parquet layout (ScadaBridge#42): rows and /// Storage-free tests for the AuditLog archive Parquet layout (ScadaBridge#42): rows round-trip
/// tombstones round-trip exactly (tick-precise timestamps, NULL vs empty strings, unicode, /// exactly (tick-precise timestamps, NULL vs empty strings, unicode), and a format-v1 data file
/// the chain columns), the archived rows re-verify against the archived chain head, and an /// — written while the hash chain existed, with its <c>ChainSeq</c>/<c>RowHash</c> columns —
/// edit made inside the Parquet file breaks that verification. /// still reads.
/// </summary> /// </summary>
public class AuditArchiveParquetTests public class AuditArchiveParquetTests
{ {
@@ -19,8 +19,7 @@ public class AuditArchiveParquetTests
[Fact] [Fact]
public async Task Rows_RoundTrip_Exactly_AcrossRowGroups() public async Task Rows_RoundTrip_Exactly_AcrossRowGroups()
{ {
var (rows, _) = BuildChain(2_503); var rows = Enumerable.Range(1, 2_503).Select(Row).ToList();
rows.Add(Row(9_999) with { ChainSeq = null, RowHash = null }); // an unchained row
var bytes = await WriteAsync(rows, rowGroupSize: 1_000); var bytes = await WriteAsync(rows, rowGroupSize: 1_000);
var back = await ReadAsync(bytes); var back = await ReadAsync(bytes);
@@ -28,100 +27,44 @@ public class AuditArchiveParquetTests
Assert.Equal(rows.Select(Key), back.Select(Key)); Assert.Equal(rows.Select(Key), back.Select(Key));
await using var reader = await ParquetReader.CreateAsync(new MemoryStream(bytes)); await using var reader = await ParquetReader.CreateAsync(new MemoryStream(bytes));
Assert.Equal(3, reader.RowGroupCount); Assert.Equal(3, reader.RowGroupCount);
Assert.Equal("1", reader.CustomMetadata[AuditArchiveParquet.FormatVersionKey]); Assert.Equal("2", reader.CustomMetadata[AuditArchiveParquet.FormatVersionKey]);
Assert.Equal("2025-10", reader.CustomMetadata[AuditArchiveParquet.PartitionKey]); Assert.Equal("2025-10", reader.CustomMetadata[AuditArchiveParquet.PartitionKey]);
} }
/// <summary>Tombstones round-trip exactly.</summary> /// <summary>The v2 data file carries the ten stored columns and nothing from the removed hash chain.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact] [Fact]
public async Task Tombstones_RoundTrip_Exactly() public void DataSchema_HasNoChainColumns()
{ {
var tombstones = Enumerable.Range(1, 5).Select(i => new AuditArchiveTombstone( var names = AuditArchiveParquet.DataSchema.DataFields.Select(f => f.Name).ToList();
Month, i * 3, Enumerable.Repeat((byte)i, 32).ToArray(), Guid.NewGuid(), Assert.DoesNotContain("ChainSeq", names);
new DateTime(2026, 1, 2, 3, 4, 5, DateTimeKind.Utc).AddMilliseconds(i))).ToList(); Assert.DoesNotContain("RowHash", names);
Assert.Contains("DetailsJson", names); // positive control: the schema was read
var stream = new MemoryStream();
await using (var writer = await AuditArchiveParquet.CreateTombstoneWriterAsync(stream, "2025-10", 2))
{
foreach (var t in tombstones)
{
await writer.AddAsync(t);
}
}
var back = new List<AuditArchiveTombstone>();
await foreach (var t in AuditArchiveParquet.ReadTombstonesAsync(new MemoryStream(stream.ToArray())))
{
back.Add(t);
}
Assert.Equal(
tombstones.Select(t => (t.ChainMonth, t.ChainSeq, Convert.ToHexString(t.RowHash), t.EventId, t.PurgedAtUtc)),
back.Select(t => (t.ChainMonth, t.ChainSeq, Convert.ToHexString(t.RowHash), t.EventId, t.PurgedAtUtc)));
} }
/// <summary> /// <summary>
/// The rows read back from an archive re-verify against the archived head — the same /// A format-v1 archive data file (the v2 columns plus <c>ChainSeq</c>/<c>RowHash</c>) reads
/// check <c>audit archive verify</c> makes long after the database dropped them. /// with the v2 reader: the extra columns are ignored and every stored column is intact.
/// </summary> /// </summary>
/// <returns>A task that represents the asynchronous operation.</returns> /// <returns>A task that represents the asynchronous operation.</returns>
[Fact] [Fact]
public async Task ArchivedRows_ReverifyAgainstTheArchivedHead() public async Task FormatV1DataFile_WithChainColumns_StillReads()
{ {
var (rows, head) = BuildChain(50); var rows = Enumerable.Range(1, 40).Select(Row).ToList();
var verifier = new AuditChainVerifier(Month, head, new Dictionary<long, byte[]>()); var bytes = await WriteV1Async(rows);
foreach (var row in await ReadAsync(await WriteAsync(rows, 16)))
await using (var raw = await ParquetReader.CreateAsync(new MemoryStream(bytes)))
{ {
verifier.Accept(row); // Positive control: the file really carries the v1 chain columns.
Assert.Contains(raw.Schema.DataFields, f => f.Name == "ChainSeq");
} }
var result = verifier.Complete(0); var back = await ReadAsync(bytes);
Assert.Equal(AuditChainStatus.Intact, result.Status); Assert.Equal(rows.Select(Key), back.Select(Key));
Assert.Equal(50, result.RowsVerified);
} }
/// <summary> private static AuditArchiveRow Row(int i) => new(
/// Positive control for the test above: a row edited inside the archive (re-written
/// file, as a forger would) fails re-verification at that row.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task RowEditedInsideTheArchive_FailsReverification()
{
var (rows, head) = BuildChain(50);
rows[17] = rows[17] with { DetailsJson = "{\"kind\":\"ApiCall\",\"forged\":true}" };
var verifier = new AuditChainVerifier(Month, head, new Dictionary<long, byte[]>());
foreach (var row in await ReadAsync(await WriteAsync(rows, 16)))
{
verifier.Accept(row);
}
var result = verifier.Complete(0);
Assert.Equal(AuditChainStatus.Broken, result.Status);
Assert.Equal(AuditChainBreakKind.HashMismatch, result.FirstBreak!.Kind);
Assert.Equal(18, result.FirstBreak.ChainSeq);
}
internal static (List<AuditChainRow> Rows, AuditChainHeadState Head) BuildChain(int count)
{
var rows = new List<AuditChainRow>();
var previous = AuditChainHasher.GenesisHash.ToArray();
for (var i = 1; i <= count; i++)
{
var row = Row(i);
var hash = AuditChainHasher.ComputeRowHash(previous, Month, i, row);
rows.Add(row with { ChainSeq = i, RowHash = hash });
previous = hash;
}
return (rows, new AuditChainHeadState(count, previous, null, null));
}
private static AuditChainRow Row(int i) => new(
Guid.NewGuid(), Guid.NewGuid(),
// Odd ticks on purpose: the archive must keep datetime2(7) precision the hash covers. // Odd ticks on purpose: the archive must keep datetime2(7) precision.
Month.AddMinutes(i).AddTicks(1_234_567 + i), Month.AddMinutes(i).AddTicks(1_234_567 + i),
i % 5 == 0 ? null : i % 7 == 0 ? string.Empty : "api-key-" + i, i % 5 == 0 ? null : i % 7 == 0 ? string.Empty : "api-key-" + i,
"ApiOutbound.ApiCall", "ApiOutbound.ApiCall",
@@ -132,12 +75,11 @@ public class AuditArchiveParquetTests
i % 2 == 0 ? Guid.NewGuid() : null, i % 2 == 0 ? Guid.NewGuid() : null,
i % 8 == 0 ? null : $"{{\"kind\":\"ApiCall\",\"status\":\"Delivered\",\"n\":{i}}}"); i % 8 == 0 ? null : $"{{\"kind\":\"ApiCall\",\"status\":\"Delivered\",\"n\":{i}}}");
private static string Key(AuditChainRow r) => string.Join('|', private static string Key(AuditArchiveRow r) => string.Join('|',
r.EventId, r.OccurredAtUtc.Ticks, r.OccurredAtUtc.Kind, r.Actor ?? "<null>", r.Action, r.Outcome, r.Category, r.EventId, r.OccurredAtUtc.Ticks, r.OccurredAtUtc.Kind, r.Actor ?? "<null>", r.Action, r.Outcome, r.Category,
r.Target ?? "<null>", r.SourceNode ?? "<null>", r.CorrelationId?.ToString() ?? "<null>", r.DetailsJson ?? "<null>", r.Target ?? "<null>", r.SourceNode ?? "<null>", r.CorrelationId?.ToString() ?? "<null>", r.DetailsJson ?? "<null>");
r.ChainSeq?.ToString() ?? "<null>", r.RowHash is null ? "<null>" : Convert.ToHexString(r.RowHash));
private static async Task<byte[]> WriteAsync(IEnumerable<AuditChainRow> rows, int rowGroupSize) internal static async Task<byte[]> WriteAsync(IEnumerable<AuditArchiveRow> rows, int rowGroupSize)
{ {
var stream = new MemoryStream(); var stream = new MemoryStream();
await using (var writer = await AuditArchiveParquet.CreateDataWriterAsync(stream, "2025-10", rowGroupSize)) await using (var writer = await AuditArchiveParquet.CreateDataWriterAsync(stream, "2025-10", rowGroupSize))
@@ -151,9 +93,44 @@ public class AuditArchiveParquetTests
return stream.ToArray(); return stream.ToArray();
} }
private static async Task<List<AuditChainRow>> ReadAsync(byte[] bytes) /// <summary>Writes rows in the format-v1 layout: the v2 columns, then the two chain columns.</summary>
private static async Task<byte[]> WriteV1Async(IReadOnlyList<AuditArchiveRow> rows)
{ {
var rows = new List<AuditChainRow>(); var v2 = AuditArchiveParquet.DataSchema.DataFields;
var chainSeq = new DataField<long>("ChainSeq", true);
var rowHash = new DataField<byte[]>("RowHash", true);
var schema = new ParquetSchema(v2.Cast<Field>().Append(chainSeq).Append(rowHash).ToArray());
var stream = new MemoryStream();
await using (var writer = await ParquetWriter.CreateAsync(schema, stream))
{
writer.CustomMetadata = new Dictionary<string, string>
{
[AuditArchiveParquet.FormatVersionKey] = "1",
[AuditArchiveParquet.PartitionKey] = "2025-10",
};
using var group = writer.CreateRowGroup();
await group.WriteAsync((DataField<string>)v2[0], rows.Select(r => r.EventId.ToString("D")).ToArray());
await group.WriteAsync<DateTime>((DateTimeDataField)v2[1], rows.Select(r => r.OccurredAtUtc).ToArray());
await group.WriteAsync<long>((DataField<long>)v2[2], rows.Select(r => r.OccurredAtUtc.Ticks).ToArray());
await group.WriteAsync((DataField<string>)v2[3], rows.Select(r => r.Actor).ToArray()!);
await group.WriteAsync((DataField<string>)v2[4], rows.Select(r => r.Action).ToArray());
await group.WriteAsync((DataField<string>)v2[5], rows.Select(r => r.Outcome).ToArray());
await group.WriteAsync((DataField<string>)v2[6], rows.Select(r => r.Category).ToArray());
await group.WriteAsync((DataField<string>)v2[7], rows.Select(r => r.Target).ToArray()!);
await group.WriteAsync((DataField<string>)v2[8], rows.Select(r => r.SourceNode).ToArray()!);
await group.WriteAsync((DataField<string>)v2[9], rows.Select(r => r.CorrelationId?.ToString("D")).ToArray()!);
await group.WriteAsync((DataField<string>)v2[10], rows.Select(r => r.DetailsJson).ToArray()!);
await group.WriteAsync<long>(chainSeq, rows.Select((_, i) => (long?)(i + 1)).ToArray());
await group.WriteAsync(rowHash, rows.Select(_ => new byte[32]).ToArray());
}
return stream.ToArray();
}
internal static async Task<List<AuditArchiveRow>> ReadAsync(byte[] bytes)
{
var rows = new List<AuditArchiveRow>();
await foreach (var row in AuditArchiveParquet.ReadRowsAsync(new MemoryStream(bytes))) await foreach (var row in AuditArchiveParquet.ReadRowsAsync(new MemoryStream(bytes)))
{ {
rows.Add(row); rows.Add(row);
@@ -1,81 +0,0 @@
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
using ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance;
namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Tests.Maintenance;
/// <summary>
/// Pure verdict table of <see cref="AuditChainHeadComparer"/> (ScadaBridge#107 item 1) for the
/// branches the SQL Server tests do not reach: a link carried by a tombstone, the partition
/// anchor itself, and malformed input.
/// </summary>
public sealed class AuditChainHeadComparerTests
{
private static readonly byte[] H1 = Enumerable.Repeat((byte)1, 32).ToArray();
private static readonly byte[] H2 = Enumerable.Repeat((byte)2, 32).ToArray();
private static AuditChainHeadRecord Exported(long seq, byte[] hash) => new(
1, "2026-05", seq, AuditChainHeadComparer.ToHex(hash), null, null, seq, 0, DateTime.UtcNow, DateTime.UtcNow, "central-a");
private static AuditChainHeadSnapshot Head(long seq, byte[] hash, long? anchor = null, byte[]? anchorHash = null) =>
new(new DateTime(2026, 5, 1, 0, 0, 0, DateTimeKind.Utc), seq, hash, anchor, anchorHash, seq, 0, DateTime.UtcNow);
private static Func<long, Task<AuditChainHeadComparer.StoredLink>> Link(byte[]? row, byte[]? tombstone)
=> _ => Task.FromResult(new AuditChainHeadComparer.StoredLink(row, tombstone));
private static Func<long, Task<AuditChainHeadComparer.StoredLink>> NoLookup
=> _ => throw new InvalidOperationException("no link lookup expected");
/// <summary>The exported link was later purged per channel: the tombstone carries the hash.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task GrownChain_LinkOnATombstone_IsExtended_OrMismatch()
{
Assert.Equal(AuditChainHeadStatus.Extended,
(await AuditChainHeadComparer.CompareAsync(Exported(3, H1), Head(9, H2), Link(null, H1))).Status);
Assert.Equal(AuditChainHeadStatus.Mismatch,
(await AuditChainHeadComparer.CompareAsync(Exported(3, H1), Head(9, H2), Link(null, H2))).Status);
}
/// <summary>The exported head is the partition-purge anchor: compared with the anchor's hash, no lookup.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task GrownChain_ExportedHeadIsTheAnchor_ComparesTheAnchorHash()
{
Assert.Equal(AuditChainHeadStatus.Extended,
(await AuditChainHeadComparer.CompareAsync(Exported(4, H1), Head(9, H2, 4, H1), NoLookup)).Status);
Assert.Equal(AuditChainHeadStatus.Mismatch,
(await AuditChainHeadComparer.CompareAsync(Exported(4, H1), Head(9, H2, 4, H2), NoLookup)).Status);
Assert.Equal(AuditChainHeadStatus.Purged,
(await AuditChainHeadComparer.CompareAsync(Exported(2, H1), Head(9, H2, 4, H2), NoLookup)).Status);
}
/// <summary>A record whose hash is not 32 bytes of hex can never match.</summary>
/// <param name="hash">The exported hash text.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
[Theory]
[InlineData("abc")]
[InlineData("zz0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f")]
public async Task MalformedExportedHash_IsMismatch(string hash)
{
var record = Exported(3, H1) with { LastHash = hash };
Assert.Equal(AuditChainHeadStatus.Mismatch,
(await AuditChainHeadComparer.CompareAsync(record, Head(3, H1), NoLookup)).Status);
}
/// <summary>Only the tamper verdicts count as failures.</summary>
/// <param name="status">The verdict.</param>
/// <param name="failure">Whether it is a failure.</param>
[Theory]
[InlineData(AuditChainHeadStatus.Matches, false)]
[InlineData(AuditChainHeadStatus.Extended, false)]
[InlineData(AuditChainHeadStatus.Purged, false)]
[InlineData(AuditChainHeadStatus.Mismatch, true)]
[InlineData(AuditChainHeadStatus.Regressed, true)]
[InlineData(AuditChainHeadStatus.MissingHead, true)]
[InlineData(AuditChainHeadStatus.MissingLink, true)]
[InlineData(AuditChainHeadStatus.CountMismatch, true)]
public void IsFailure_IsTrueOnlyForTamperVerdicts(AuditChainHeadStatus status, bool failure)
{
Assert.Equal(failure, new AuditChainHeadCheck("2026-05", 1, DateTime.UtcNow, null, status, 1, "").IsFailure);
}
}
@@ -1,312 +0,0 @@
using Microsoft.Data.SqlClient;
using Microsoft.EntityFrameworkCore;
using ZB.MOM.WW.Audit;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums;
using ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance;
using ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Repositories;
using ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Tests.Migrations;
namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Tests.Maintenance;
/// <summary>
/// SQL Server tests for the chain-head export store (ScadaBridge#107 item 1): heads read with
/// their counts, and exported heads checked against the database. The key case is the forgery
/// the export exists for: rows rewritten AND every later link and the head recomputed — which
/// <c>verify-chain</c> accepts — is caught because the exported hash no longer matches.
/// </summary>
/// <remarks>Each test owns one month (partition) of the shared fixture database.</remarks>
public sealed class AuditChainHeadStoreTests : IClassFixture<MsSqlMigrationFixture>
{
private readonly MsSqlMigrationFixture _fixture;
/// <summary>Creates the test class with the shared migrated SQL Server fixture.</summary>
/// <param name="fixture">The shared migration fixture.</param>
public AuditChainHeadStoreTests(MsSqlMigrationFixture fixture) => _fixture = fixture;
/// <summary>The head snapshot carries the chain end and the live row + tombstone counts.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task ReadHeads_ReportsTheChainEnd_AndRowAndTombstoneCounts()
{
Skip.IfNot(_fixture.Available, _fixture.SkipReason);
var month = Month(2026, 3);
await InsertAsync(Enumerable.Range(1, 5).Select(i => NewEvent(month.AddDays(i))));
await InsertAsync([NewEvent(month.AddHours(1), AuditChannel.DbOutbound)]);
await DrainAsync();
await using (var ctx = CreateContext())
{
Assert.Equal(1, await new AuditLogRepository(ctx).PurgeChannelOlderThanAsync("DbOutbound", month.AddDays(1), 100));
}
var head = await HeadAsync(month);
Assert.Equal(6, head.LastSeq);
Assert.Equal(5, head.ChainedRows);
Assert.Equal(1, head.Tombstones);
Assert.Null(head.PurgedThroughSeq);
}
/// <summary>
/// Unchanged chain: Matches. The chain grew: Extended. Both centrals' duplicate exports
/// collapse to one check.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task ExportedHeads_MatchTheUnchangedChain_AndAreExtendedByLaterLinks()
{
Skip.IfNot(_fixture.Available, _fixture.SkipReason);
var month = Month(2026, 4);
await InsertAsync(Enumerable.Range(1, 4).Select(i => NewEvent(month.AddDays(i))));
await DrainAsync();
var exported = Export(await HeadAsync(month));
var same = await VerifyAsync(exported, exported with { Node = "central-b" });
Assert.True(same.Verified);
Assert.Equal(AuditChainHeadStatus.Matches, Assert.Single(same.Checks).Status);
await InsertAsync([NewEvent(month.AddDays(10))]);
await DrainAsync();
var grown = await VerifyAsync(exported);
Assert.True(grown.Verified);
var check = Assert.Single(grown.Checks);
Assert.Equal(AuditChainHeadStatus.Extended, check.Status);
Assert.Equal(5, check.DatabaseSeq);
}
/// <summary>
/// The forgery: a chained row's content is rewritten and every link from it plus the head
/// are recomputed with the real hasher. <c>VerifyMonthAsync</c> reports the forged chain
/// Intact (positive control: the in-database chain alone cannot see it); the exported head
/// does not match it.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task ARewrittenAndRehashedChain_PassesVerifyChain_ButFailsTheExportedHead()
{
Skip.IfNot(_fixture.Available, _fixture.SkipReason);
var month = Month(2026, 5);
await InsertAsync(Enumerable.Range(1, 6).Select(i => NewEvent(month.AddDays(i))));
await DrainAsync();
var exported = Export(await HeadAsync(month));
await ForgeChainAsync(month, fromSeq: 3);
await using (var ctx = CreateContext())
{
var chain = await new AuditLogHashChain(ctx).VerifyMonthAsync(month);
Assert.Equal(AuditChainStatus.Intact, chain.Status);
}
var result = await VerifyAsync(exported);
Assert.False(result.Verified);
Assert.Equal(AuditChainHeadStatus.Mismatch, Assert.Single(result.Checks).Status);
}
/// <summary>Each structural tampering maps to its own verdict.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task TamperedHeadsAndRows_AreReported_WithTheirOwnVerdicts()
{
Skip.IfNot(_fixture.Available, _fixture.SkipReason);
// Head rolled back below the export (tail deletion + head rewrite).
var regressed = Month(2026, 6);
await InsertAsync(Enumerable.Range(1, 3).Select(i => NewEvent(regressed.AddDays(i))));
await DrainAsync();
var regressedExport = Export(await HeadAsync(regressed));
await ExecAsync("UPDATE dbo.AuditLogChainHead SET LastSeq = LastSeq - 1 WHERE ChainMonth = @m;", regressed);
// Head row deleted.
var missingHead = Month(2026, 7);
await InsertAsync([NewEvent(missingHead.AddDays(1))]);
await DrainAsync();
var missingHeadExport = Export(await HeadAsync(missingHead));
await ExecAsync("DELETE FROM dbo.AuditLogChainHead WHERE ChainMonth = @m;", missingHead);
// A chained row deleted with no tombstone, head unchanged: counts no longer add up.
var counted = Month(2026, 8);
await InsertAsync(Enumerable.Range(1, 3).Select(i => NewEvent(counted.AddDays(i))));
await DrainAsync();
var countedExport = Export(await HeadAsync(counted));
await ExecAsync("DELETE FROM dbo.AuditLog WHERE ChainSeq = 2 AND OccurredAtUtc >= @m AND OccurredAtUtc < DATEADD(MONTH, 1, @m);", counted);
// The exported link itself deleted after the chain grew past it.
var missingLink = Month(2026, 9);
await InsertAsync(Enumerable.Range(1, 2).Select(i => NewEvent(missingLink.AddDays(i))));
await DrainAsync();
var missingLinkExport = Export(await HeadAsync(missingLink));
await InsertAsync([NewEvent(missingLink.AddDays(5))]);
await DrainAsync();
await ExecAsync("DELETE FROM dbo.AuditLog WHERE ChainSeq = 2 AND OccurredAtUtc >= @m AND OccurredAtUtc < DATEADD(MONTH, 1, @m);", missingLink);
var result = await VerifyAsync(regressedExport, missingHeadExport, countedExport, missingLinkExport);
Assert.False(result.Verified);
var byMonth = result.Checks.ToDictionary(c => c.Month, c => c.Status);
Assert.Equal(AuditChainHeadStatus.Regressed, byMonth["2026-06"]);
Assert.Equal(AuditChainHeadStatus.MissingHead, byMonth["2026-07"]);
Assert.Equal(AuditChainHeadStatus.CountMismatch, byMonth["2026-08"]);
Assert.Equal(AuditChainHeadStatus.MissingLink, byMonth["2026-09"]);
}
/// <summary>
/// Sanctioned purges are not tamper evidence: a per-channel purge (row to tombstone) keeps
/// Matches; after a partition switch the exported head is the anchor, so the check still
/// passes, and an older exported sequence the switch removed is reported Purged.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task SanctionedPurges_AreNotFailures()
{
Skip.IfNot(_fixture.Available, _fixture.SkipReason);
var month = Month(2026, 10);
await InsertAsync(Enumerable.Range(1, 3).Select(i => NewEvent(month.AddDays(i))));
await DrainAsync();
var early = Export(await HeadAsync(month));
await InsertAsync([NewEvent(month.AddDays(5), AuditChannel.Notification)]);
await DrainAsync();
var late = Export(await HeadAsync(month));
await using (var ctx = CreateContext())
{
Assert.Equal(1, await new AuditLogRepository(ctx).PurgeChannelOlderThanAsync("Notification", month.AddDays(6), 100));
}
Assert.Equal(AuditChainHeadStatus.Matches, Assert.Single((await VerifyAsync(late)).Checks).Status);
await using (var ctx = CreateContext())
{
await new AuditLogRepository(ctx).SwitchOutPartitionAsync(month);
}
var afterSwitch = await VerifyAsync(late, early);
Assert.True(afterSwitch.Verified);
var statuses = afterSwitch.Checks.ToDictionary(c => c.ExportedSeq, c => c.Status);
Assert.Equal(AuditChainHeadStatus.Matches, statuses[4]);
Assert.Equal(AuditChainHeadStatus.Purged, statuses[3]);
}
private static AuditChainHeadRecord Export(AuditChainHeadSnapshot head) => new(
AuditChainHeadRecord.CurrentVersion,
AuditChainHasher.PartitionLabel(head.Month),
head.LastSeq,
AuditChainHeadComparer.ToHex(head.LastHash),
head.PurgedThroughSeq,
head.PurgedThroughHash is null ? null : AuditChainHeadComparer.ToHex(head.PurgedThroughHash),
head.ChainedRows,
head.Tombstones,
head.UpdatedAtUtc,
DateTime.UtcNow,
"central-a");
private async Task<AuditChainHeadSnapshot> HeadAsync(DateTime month)
{
await using var ctx = CreateContext();
var heads = await new AuditLogHashChain(ctx).ReadHeadsAsync();
return Assert.Single(heads, h => h.Month == month);
}
private async Task<AuditChainHeadVerificationResult> VerifyAsync(params AuditChainHeadRecord[] records)
{
await using var ctx = CreateContext();
return await new AuditLogHashChain(ctx).VerifyExportedHeadsAsync(records);
}
/// <summary>
/// Rewrites the row at <paramref name="fromSeq"/> and re-links it and every later row plus the
/// head with the production hasher — what a principal with full write access could do.
/// </summary>
private async Task ForgeChainAsync(DateTime month, long fromSeq)
{
await using var conn = _fixture.OpenConnection();
await using (var edit = new SqlCommand(
"UPDATE dbo.AuditLog SET Target = N'forged' WHERE ChainSeq = @s AND OccurredAtUtc >= @m AND OccurredAtUtc < DATEADD(MONTH, 1, @m);", conn))
{
edit.Parameters.AddWithValue("@s", fromSeq);
edit.Parameters.Add(new SqlParameter("@m", System.Data.SqlDbType.DateTime2) { Scale = 7, Value = month });
Assert.Equal(1, await edit.ExecuteNonQueryAsync());
}
var rows = new List<AuditChainRow>();
await using (var read = new SqlCommand(
$"SELECT {AuditLogHashChain.RowColumns}, ChainSeq, RowHash FROM dbo.AuditLog " +
"WHERE ChainSeq IS NOT NULL AND OccurredAtUtc >= @m AND OccurredAtUtc < DATEADD(MONTH, 1, @m) ORDER BY ChainSeq;", conn))
{
read.Parameters.Add(new SqlParameter("@m", System.Data.SqlDbType.DateTime2) { Scale = 7, Value = month });
await using var reader = await read.ExecuteReaderAsync();
while (await reader.ReadAsync())
{
rows.Add(AuditLogHashChain.ReadRow(reader, withLink: true));
}
}
var previous = rows.Single(r => r.ChainSeq == fromSeq - 1).RowHash!;
foreach (var row in rows.Where(r => r.ChainSeq >= fromSeq))
{
var hash = AuditChainHasher.ComputeRowHash(previous, month, row.ChainSeq!.Value, row);
await using var update = new SqlCommand("UPDATE dbo.AuditLog SET RowHash = @h WHERE EventId = @e AND OccurredAtUtc = @o;", conn);
update.Parameters.AddWithValue("@h", hash);
update.Parameters.AddWithValue("@e", row.EventId);
update.Parameters.Add(new SqlParameter("@o", System.Data.SqlDbType.DateTime2) { Scale = 7, Value = row.OccurredAtUtc });
Assert.Equal(1, await update.ExecuteNonQueryAsync());
previous = hash;
}
await using var head = new SqlCommand("UPDATE dbo.AuditLogChainHead SET LastHash = @h WHERE ChainMonth = @m;", conn);
head.Parameters.AddWithValue("@h", previous);
head.Parameters.Add(new SqlParameter("@m", System.Data.SqlDbType.Date) { Value = month });
Assert.Equal(1, await head.ExecuteNonQueryAsync());
}
private async Task ExecAsync(string sql, DateTime month)
{
await using var conn = _fixture.OpenConnection();
await using var cmd = new SqlCommand(sql, conn);
cmd.Parameters.Add(new SqlParameter("@m", System.Data.SqlDbType.DateTime2) { Scale = 7, Value = month });
Assert.True(await cmd.ExecuteNonQueryAsync() >= 1);
}
private async Task InsertAsync(IEnumerable<AuditEvent> events)
{
await using var ctx = CreateContext();
var repo = new AuditLogRepository(ctx);
foreach (var e in events)
{
await repo.InsertIfNotExistsAsync(e);
}
}
private async Task DrainAsync()
{
await using var ctx = CreateContext();
var chain = new AuditLogHashChain(ctx);
for (var i = 0; i < 1000; i++)
{
var r = await chain.ChainPendingAsync(500, chainBacklog: true);
if (r.RowsChained == 0 && !r.LockBusy)
{
return;
}
}
throw new InvalidOperationException("Chain did not drain.");
}
private static DateTime Month(int year, int month) => new(year, month, 1, 0, 0, 0, DateTimeKind.Utc);
private ScadaBridgeDbContext CreateContext()
=> new(new DbContextOptionsBuilder<ScadaBridgeDbContext>().UseSqlServer(_fixture.ConnectionString).Options);
private static AuditEvent NewEvent(DateTime occurredAtUtc, AuditChannel channel = AuditChannel.ApiOutbound) =>
ScadaBridgeAuditEventFactory.Create(
channel: channel,
kind: channel == AuditChannel.DbOutbound ? AuditKind.DbWrite : AuditKind.ApiCall,
status: AuditStatus.Delivered,
occurredAtUtc: occurredAtUtc,
actor: "head-test",
target: "erp",
sourceNode: "central-a",
sourceSiteId: "head-test",
correlationId: Guid.NewGuid());
}
@@ -1,370 +0,0 @@
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
using ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance;
namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Tests.Maintenance;
/// <summary>
/// Storage-free tests for the AuditLog hash-chain hasher + verifier (ScadaBridge#41):
/// tamper detection for an edited, a deleted and a reordered row, tombstone and
/// partition-anchor bridging, and a pinned known-answer vector for the v1 canonical form.
/// </summary>
public class AuditChainVerifierTests
{
private static readonly DateTime Month = new(2026, 5, 1, 0, 0, 0, DateTimeKind.Utc);
/// <summary>An untouched chain verifies intact and covers every row.</summary>
[Fact]
public void IntactChain_Verifies()
{
var (rows, head) = BuildChain(5);
var result = Verify(rows, head);
Assert.Equal(AuditChainStatus.Intact, result.Status);
Assert.Equal(5, result.RowsVerified);
Assert.Null(result.FirstBreak);
}
/// <summary>Editing any stored column of a chained row is a HashMismatch at that row.</summary>
[Fact]
public void EditedRow_IsHashMismatch_AtThatRow()
{
var (rows, head) = BuildChain(5);
rows[2] = rows[2] with { Target = "tampered" };
var result = Verify(rows, head);
Assert.Equal(AuditChainStatus.Broken, result.Status);
Assert.Equal(AuditChainBreakKind.HashMismatch, result.FirstBreak!.Kind);
Assert.Equal(3, result.FirstBreak.ChainSeq);
Assert.Equal(rows[2].EventId, result.FirstBreak.EventId);
Assert.Equal("2026-05", result.FirstBreak.Partition);
Assert.Equal(2, result.RowsVerified);
}
/// <summary>A row deleted from the middle (no tombstone) is a MissingRow at its sequence number.</summary>
[Fact]
public void DeletedMiddleRow_IsMissingRow()
{
var (rows, head) = BuildChain(5);
var deleted = rows[1];
rows.RemoveAt(1);
var result = Verify(rows, head);
Assert.Equal(AuditChainStatus.Broken, result.Status);
Assert.Equal(AuditChainBreakKind.MissingRow, result.FirstBreak!.Kind);
Assert.Equal(deleted.ChainSeq, result.FirstBreak.ChainSeq);
Assert.Equal(rows[1].EventId, result.FirstBreak.EventId); // the next surviving row
}
/// <summary>Deleting the newest rows leaves a self-consistent prefix; the head catches it.</summary>
[Fact]
public void DeletedTailRows_IsHeadMismatch()
{
var (rows, head) = BuildChain(5);
rows.RemoveRange(3, 2);
var result = Verify(rows, head);
Assert.Equal(AuditChainStatus.Broken, result.Status);
Assert.Equal(AuditChainBreakKind.HeadMismatch, result.FirstBreak!.Kind);
Assert.Equal(4, result.FirstBreak.ChainSeq);
Assert.Null(result.FirstBreak.EventId);
}
/// <summary>Swapping two rows' sequence numbers is a HashMismatch at the first moved row.</summary>
[Fact]
public void ReorderedRows_IsHashMismatch()
{
var (rows, head) = BuildChain(5);
var a = rows[1];
var b = rows[3];
rows[1] = b with { ChainSeq = a.ChainSeq };
rows[3] = a with { ChainSeq = b.ChainSeq };
var result = Verify(rows, head);
Assert.Equal(AuditChainStatus.Broken, result.Status);
Assert.Equal(AuditChainBreakKind.HashMismatch, result.FirstBreak!.Kind);
Assert.Equal(2, result.FirstBreak.ChainSeq);
Assert.Equal(b.EventId, result.FirstBreak.EventId);
}
/// <summary>A duplicated sequence number is reported, not silently skipped.</summary>
[Fact]
public void DuplicateSequence_IsReported()
{
var (rows, head) = BuildChain(3);
rows.Insert(2, rows[1] with { EventId = Guid.NewGuid() });
var result = Verify(rows, head);
Assert.Equal(AuditChainBreakKind.DuplicateSequence, result.FirstBreak!.Kind);
}
/// <summary>A sanctioned per-channel purge leaves a tombstone that bridges the gap.</summary>
[Fact]
public void TombstonedRow_BridgesTheGap()
{
var (rows, head) = BuildChain(5);
var purged = rows[2];
rows.RemoveAt(2);
var tombstones = new Dictionary<long, byte[]> { [purged.ChainSeq!.Value] = purged.RowHash! };
var result = Verify(rows, head, tombstones);
Assert.Equal(AuditChainStatus.Intact, result.Status);
Assert.Equal(4, result.RowsVerified);
Assert.Equal(1, result.TombstonesApplied);
}
/// <summary>A tombstone with the wrong hash does not hide a deletion.</summary>
[Fact]
public void ForgedTombstone_IsDetectedAtTheNextRow()
{
var (rows, head) = BuildChain(5);
var purged = rows[2];
rows.RemoveAt(2);
var tombstones = new Dictionary<long, byte[]> { [purged.ChainSeq!.Value] = new byte[32] };
var result = Verify(rows, head, tombstones);
Assert.Equal(AuditChainBreakKind.HashMismatch, result.FirstBreak!.Kind);
Assert.Equal(4, result.FirstBreak.ChainSeq);
}
/// <summary>After a partition purge, verification resumes at the checkpoint anchor.</summary>
[Fact]
public void PartitionPurgeAnchor_VerifiesTheRest()
{
var (rows, head) = BuildChain(6);
var anchor = rows[3];
var survivors = rows.Skip(4).ToList();
var anchored = head with { PurgedThroughSeq = anchor.ChainSeq, PurgedThroughHash = anchor.RowHash };
var result = Verify(survivors, anchored);
Assert.Equal(AuditChainStatus.Intact, result.Status);
Assert.Equal(2, result.RowsVerified);
Assert.Equal(4, result.PurgedThroughSeq);
}
/// <summary>A month with neither rows nor head reports NotChained.</summary>
[Fact]
public void EmptyMonth_IsNotChained()
{
var result = Verify([], null, unchained: 7);
Assert.Equal(AuditChainStatus.NotChained, result.Status);
Assert.Equal(7, result.UnchainedRows);
}
/// <summary>
/// Pins the v1 canonical form: a change to the serialisation silently invalidates every
/// chain already in a database, so it must fail a test first. The expected value was
/// computed by an independent implementation of the documented v1 encoding (Python
/// hashlib/struct), not by this code.
/// </summary>
[Fact]
public void KnownAnswerVector_V1()
{
var row = new AuditChainRow(
Guid.Parse("0f8fad5b-d9cb-469f-a165-70867728950e"),
new DateTime(2026, 5, 20, 10, 30, 0, DateTimeKind.Utc).AddTicks(1234567),
"alice", "ApiOutbound.ApiCall", "Success", "ApiOutbound", "Erp", "central-a",
Guid.Parse("7c9e6679-7425-40de-944b-e07fc1f90ae7"), "{\"kind\":\"ApiCall\",\"status\":\"Delivered\"}");
var hash = AuditChainHasher.ComputeRowHash(AuditChainHasher.GenesisHash, Month, 1, row);
Assert.Equal("a3137c9961f35f931c7d84de6bced66ce1fe8bbb1dc500f9740b97efd9983ad4", Convert.ToHexStringLower(hash));
}
/// <summary>NULL and the empty string hash differently (presence byte), as do adjacent-field shifts.</summary>
[Fact]
public void Canonical_DistinguishesNullEmptyAndFieldBoundaries()
{
var baseRow = NewRow(1);
var nullTarget = baseRow with { Target = null };
var emptyTarget = baseRow with { Target = "" };
var shifted = baseRow with { Actor = "ab", Target = "c" };
var shifted2 = baseRow with { Actor = "a", Target = "bc" };
Assert.NotEqual(Hash(nullTarget), Hash(emptyTarget));
Assert.NotEqual(Hash(shifted), Hash(shifted2));
}
private static string Hash(AuditChainRow row)
=> Convert.ToHexString(AuditChainHasher.ComputeRowHash(AuditChainHasher.GenesisHash, Month, 1, row));
private static AuditChainVerificationResult Verify(
IEnumerable<AuditChainRow> rows,
AuditChainHeadState? head,
IReadOnlyDictionary<long, byte[]>? tombstones = null,
long unchained = 0)
{
var verifier = new AuditChainVerifier(Month, head, tombstones ?? new Dictionary<long, byte[]>());
foreach (var row in rows)
{
if (!verifier.Accept(row))
{
break;
}
}
return verifier.Complete(unchained);
}
// ── chain start / cutoff (ScadaBridge#139) ───────────────────────────────
private static readonly DateTime CutoffAt = Month.AddHours(12); // rows are dated Month + i days
/// <summary>A cutoff-started month links its first row to the anchor and verifies intact.</summary>
[Fact]
public void CutoffStartedChain_Verifies_FromTheAnchor()
{
var anchor = AuditChainHasher.ComputeCutoffAnchorHash(CutoffAt);
var (rows, head) = BuildChain(4, anchor);
var result = VerifyCutoff(rows, head, anchor);
Assert.Equal(AuditChainStatus.Intact, result.Status);
Assert.Equal(4, result.RowsVerified);
Assert.Equal(0, result.TombstonesApplied); // the anchor is not a purge tombstone
Assert.Equal(CutoffAt, result.ChainFromUtc);
Assert.Equal(7, result.PreCutoffRows);
}
/// <summary>Without its anchor, a cutoff-started month fails at its first link.</summary>
[Fact]
public void CutoffStartedChain_WithoutItsAnchor_FailsAtTheFirstLink()
{
var anchor = AuditChainHasher.ComputeCutoffAnchorHash(CutoffAt);
var (rows, head) = BuildChain(4, anchor);
var result = Verify(rows, head);
Assert.Equal(AuditChainBreakKind.HashMismatch, result.FirstBreak!.Kind);
Assert.Equal(1, result.FirstBreak.ChainSeq);
}
/// <summary>A different cutoff is a different anchor: the anchor hash binds the instant.</summary>
[Fact]
public void CutoffAnchorHash_BindsTheInstant()
{
Assert.False(AuditChainHasher.ComputeCutoffAnchorHash(CutoffAt).AsSpan()
.SequenceEqual(AuditChainHasher.ComputeCutoffAnchorHash(CutoffAt.AddTicks(1))));
Assert.Equal(AuditChainHasher.HashLength, AuditChainHasher.ComputeCutoffAnchorHash(CutoffAt).Length);
}
/// <summary>
/// The eligibility attack: a chained row re-dated before the cutoff is a
/// ChainedBeforeCutoff break even when its hash were recomputed to match.
/// </summary>
[Fact]
public void ChainedRowDatedBeforeTheCutoff_IsChainedBeforeCutoff()
{
var anchor = AuditChainHasher.ComputeCutoffAnchorHash(CutoffAt);
var (rows, _) = BuildChain(4, anchor);
// Re-date row 3 before the cutoff and re-hash the chain from it (an attacker who
// rewrites the links): only the cutoff rule can still see it.
rows[2] = rows[2] with { OccurredAtUtc = CutoffAt.AddMinutes(-1) };
var previous = rows[1].RowHash!;
for (var i = 2; i < rows.Count; i++)
{
var hash = AuditChainHasher.ComputeRowHash(previous, Month, i + 1, rows[i] with { ChainSeq = null, RowHash = null });
rows[i] = rows[i] with { RowHash = hash };
previous = hash;
}
var result = VerifyCutoff(rows, new AuditChainHeadState(4, previous, null, null), anchor);
Assert.Equal(AuditChainStatus.Broken, result.Status);
Assert.Equal(AuditChainBreakKind.ChainedBeforeCutoff, result.FirstBreak!.Kind);
Assert.Equal(3, result.FirstBreak.ChainSeq);
Assert.Equal(rows[2].EventId, result.FirstBreak.EventId);
}
/// <summary>An anchor the caller found invalid fails the month even when every link verifies.</summary>
[Fact]
public void InvalidAnchor_IsCutoffAnchorInvalid()
{
var anchor = AuditChainHasher.ComputeCutoffAnchorHash(CutoffAt);
var (rows, head) = BuildChain(4, anchor);
var tombstones = new Dictionary<long, byte[]> { [AuditChainHasher.CutoffAnchorSeq] = anchor };
var verifier = new AuditChainVerifier(Month, head, tombstones, CutoffAt, "anchor altered");
foreach (var row in rows)
{
verifier.Accept(row);
}
var result = verifier.Complete(0);
Assert.Equal(AuditChainStatus.Broken, result.Status);
Assert.Equal(AuditChainBreakKind.CutoffAnchorInvalid, result.FirstBreak!.Kind);
Assert.Equal(AuditChainHasher.CutoffAnchorSeq, result.FirstBreak.ChainSeq);
}
/// <summary>
/// After a partition purge the checkpoint anchor, not the cutoff anchor, is where
/// verification resumes; the cutoff anchor in the same tombstone set is ignored.
/// </summary>
[Fact]
public void PurgeCheckpoint_TakesPrecedenceOverTheCutoffAnchor()
{
var anchor = AuditChainHasher.ComputeCutoffAnchorHash(CutoffAt);
var (rows, _) = BuildChain(5, anchor);
var head = new AuditChainHeadState(5, rows[4].RowHash!, 3, rows[2].RowHash!);
var result = VerifyCutoff(rows.Skip(3), head, anchor);
Assert.Equal(AuditChainStatus.Intact, result.Status);
Assert.Equal(2, result.RowsVerified);
}
private static AuditChainVerificationResult VerifyCutoff(IEnumerable<AuditChainRow> rows, AuditChainHeadState head, byte[] anchor)
{
var tombstones = new Dictionary<long, byte[]> { [AuditChainHasher.CutoffAnchorSeq] = anchor };
var verifier = new AuditChainVerifier(Month, head, tombstones, CutoffAt);
foreach (var row in rows)
{
if (!verifier.Accept(row))
{
break;
}
}
return verifier.Complete(0, preCutoffRows: 7);
}
private static (List<AuditChainRow> Rows, AuditChainHeadState Head) BuildChain(int count)
=> BuildChain(count, AuditChainHasher.GenesisHash.ToArray());
private static (List<AuditChainRow> Rows, AuditChainHeadState Head) BuildChain(int count, byte[] genesis)
{
var rows = new List<AuditChainRow>();
var previous = genesis;
for (var seq = 1; seq <= count; seq++)
{
var row = NewRow(seq);
var hash = AuditChainHasher.ComputeRowHash(previous, Month, seq, row);
rows.Add(row with { ChainSeq = seq, RowHash = hash });
previous = hash;
}
return (rows, new AuditChainHeadState(count, previous, null, null));
}
private static AuditChainRow NewRow(int i)
=> new(
Guid.NewGuid(),
Month.AddDays(i).AddTicks(i),
$"actor-{i}",
"ApiOutbound.ApiCall",
"Success",
"ApiOutbound",
$"target-{i}",
"central-a",
null,
$"{{\"kind\":\"ApiCall\",\"n\":{i}}}");
}
@@ -31,9 +31,8 @@ public sealed class AuditLogArchiveCleanupTests : IClassFixture<MsSqlMigrationFi
public void Dispose() => _root.Delete(recursive: true); public void Dispose() => _root.Delete(recursive: true);
/// <summary> /// <summary>
/// The retried purge: archive A goes stale (a row arrives and the chain advances), B purges. /// The retried purge: archive A goes stale (a row arrives), B purges. Dry run reports A as
/// Dry run reports A as superseded and deletes nothing; the real pass deletes exactly A's /// superseded and deletes nothing; the real pass deletes exactly A's files and B still verifies.
/// three files and B still verifies.
/// </summary> /// </summary>
/// <returns>A task that represents the asynchronous operation.</returns> /// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact] [SkippableFact]
@@ -42,14 +41,11 @@ public sealed class AuditLogArchiveCleanupTests : IClassFixture<MsSqlMigrationFi
Skip.IfNot(_fixture.Available, _fixture.SkipReason); Skip.IfNot(_fixture.Available, _fixture.SkipReason);
var dir = Dir("retried"); var dir = Dir("retried");
var month = Month(2027, 1); var month = Month(2027, 1);
await InsertAsync(Enumerable.Range(1, 5).Select(i => NewEvent(month.AddDays(i)))); await InsertAsync(Enumerable.Range(1, 6).Select(i => NewEvent(month.AddDays(i))));
await DrainAsync();
await InsertAsync([NewEvent(month.AddDays(7))]); // unchained in A
var stale = await ArchiveAsync(dir, month); var stale = await ArchiveAsync(dir, month);
Assert.Equal(1, stale.UnchainedRowCount); Assert.Equal(6, stale.RowCount);
await InsertAsync([NewEvent(month.AddDays(9))]); await InsertAsync([NewEvent(month.AddDays(9))]);
await DrainAsync(); // A's unchained row is now chained; the chain moved past A's end
await using (var ctx = CreateContext()) await using (var ctx = CreateContext())
{ {
await Assert.ThrowsAsync<AuditArchiveStaleException>(() => Archive(ctx, dir).PurgeArchivedPartitionAsync(stale)); await Assert.ThrowsAsync<AuditArchiveStaleException>(() => Archive(ctx, dir).PurgeArchivedPartitionAsync(stale));
@@ -83,8 +79,8 @@ public sealed class AuditLogArchiveCleanupTests : IClassFixture<MsSqlMigrationFi
} }
/// <summary> /// <summary>
/// A stale archive holding an unchained row that a per-channel purge removed before the /// A stale archive holding a row that a per-channel purge removed before the later archive
/// later archive (no tombstone for an unchained row) is the only copy of that row: kept. /// is the only copy of that row: kept.
/// </summary> /// </summary>
/// <returns>A task that represents the asynchronous operation.</returns> /// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact] [SkippableFact]
@@ -94,8 +90,7 @@ public sealed class AuditLogArchiveCleanupTests : IClassFixture<MsSqlMigrationFi
var dir = Dir("kept"); var dir = Dir("kept");
var month = Month(2027, 3); var month = Month(2027, 3);
await InsertAsync(Enumerable.Range(1, 3).Select(i => NewEvent(month.AddDays(i)))); await InsertAsync(Enumerable.Range(1, 3).Select(i => NewEvent(month.AddDays(i))));
await DrainAsync(); await InsertAsync([NewEvent(month.AddHours(1), AuditChannel.DbOutbound)]);
await InsertAsync([NewEvent(month.AddHours(1), AuditChannel.DbOutbound)]); // unchained
var stale = await ArchiveAsync(dir, month); var stale = await ArchiveAsync(dir, month);
await using (var ctx = CreateContext()) await using (var ctx = CreateContext())
@@ -114,7 +109,7 @@ public sealed class AuditLogArchiveCleanupTests : IClassFixture<MsSqlMigrationFi
var kept = Assert.Single(result.Items); var kept = Assert.Single(result.Items);
Assert.Equal((stale.Name, AuditArchiveCleanupAction.KeptStale), (kept.Name, kept.Action)); Assert.Equal((stale.Name, AuditArchiveCleanupAction.KeptStale), (kept.Name, kept.Action));
Assert.Contains("unchained row", kept.Detail); Assert.Contains("1 row(s) of this archive are not in", kept.Detail);
Assert.True(File.Exists(ManifestPath(dir, stale))); Assert.True(File.Exists(ManifestPath(dir, stale)));
} }
@@ -130,7 +125,6 @@ public sealed class AuditLogArchiveCleanupTests : IClassFixture<MsSqlMigrationFi
var dir = Dir("sole"); var dir = Dir("sole");
var month = Month(2027, 4); var month = Month(2027, 4);
await InsertAsync(Enumerable.Range(1, 3).Select(i => NewEvent(month.AddDays(i)))); await InsertAsync(Enumerable.Range(1, 3).Select(i => NewEvent(month.AddDays(i))));
await DrainAsync();
var manifest = await ArchiveAsync(dir, month); var manifest = await ArchiveAsync(dir, month);
await using (var ctx = CreateContext()) await using (var ctx = CreateContext())
{ {
@@ -165,6 +159,10 @@ public sealed class AuditLogArchiveCleanupTests : IClassFixture<MsSqlMigrationFi
await InsertAsync([NewEvent(liveMonth.AddDays(1))]); await InsertAsync([NewEvent(liveMonth.AddDays(1))]);
var live = await ArchiveAsync(dir, liveMonth); // never purged: rows still in the table var live = await ArchiveAsync(dir, liveMonth); // never purged: rows still in the table
// As if it were a format-v1 archive (written with the hash chain): it also has a tombstone file.
var legacyTombstones = Path.Combine(dir, "2027", purged.Name + AuditArchiveParquet.LegacyTombstoneSuffix);
await File.WriteAllTextAsync(legacyTombstones, "v1");
var monthEnd = purgedMonth.AddMonths(1); var monthEnd = purgedMonth.AddMonths(1);
var farFuture = liveMonth.AddMonths(1).AddDays(1000); var farFuture = liveMonth.AddMonths(1).AddDays(1000);
Assert.Empty((await CleanupAsync(dir, dryRun: false, retentionDays: 0, now: farFuture)).Items); Assert.Empty((await CleanupAsync(dir, dryRun: false, retentionDays: 0, now: farFuture)).Items);
@@ -175,10 +173,11 @@ public sealed class AuditLogArchiveCleanupTests : IClassFixture<MsSqlMigrationFi
var expired = Assert.Single(result.Items); var expired = Assert.Single(result.Items);
Assert.Equal((purged.Name, AuditArchiveCleanupAction.DeletedExpired), (expired.Name, expired.Action)); Assert.Equal((purged.Name, AuditArchiveCleanupAction.DeletedExpired), (expired.Name, expired.Action));
Assert.False(File.Exists(ManifestPath(dir, purged))); Assert.False(File.Exists(ManifestPath(dir, purged)));
Assert.False(File.Exists(legacyTombstones)); // a format-v1 archive's tombstone file goes with it
Assert.True(File.Exists(ManifestPath(dir, live))); Assert.True(File.Exists(ManifestPath(dir, live)));
} }
/// <summary>Deletion uses the archive name's own three files — never a path from the manifest.</summary> /// <summary>Deletion uses the archive name's own files — never a path from the manifest.</summary>
/// <returns>A task that represents the asynchronous operation.</returns> /// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact] [SkippableFact]
public async Task Deletion_NeverFollowsAManifestPath_OutOfTheArchiveFolder() public async Task Deletion_NeverFollowsAManifestPath_OutOfTheArchiveFolder()
@@ -199,7 +198,6 @@ public sealed class AuditLogArchiveCleanupTests : IClassFixture<MsSqlMigrationFi
var tampered = JsonSerializer.Deserialize<AuditArchiveManifest>(await File.ReadAllTextAsync(path), Json)! with var tampered = JsonSerializer.Deserialize<AuditArchiveManifest>(await File.ReadAllTextAsync(path), Json)! with
{ {
DataFile = "../../outside.parquet", DataFile = "../../outside.parquet",
TombstoneFile = "../../outside.parquet",
}; };
await File.WriteAllTextAsync(path, JsonSerializer.Serialize(tampered, Json)); await File.WriteAllTextAsync(path, JsonSerializer.Serialize(tampered, Json));
@@ -223,7 +221,6 @@ public sealed class AuditLogArchiveCleanupTests : IClassFixture<MsSqlMigrationFi
var dir = Dir("orphans"); var dir = Dir("orphans");
var month = Month(2027, 6); var month = Month(2027, 6);
await InsertAsync(Enumerable.Range(1, 3).Select(i => NewEvent(month.AddDays(i)))); await InsertAsync(Enumerable.Range(1, 3).Select(i => NewEvent(month.AddDays(i))));
await DrainAsync();
var committed = await ArchiveAsync(dir, month); var committed = await ArchiveAsync(dir, month);
var year = Directory.CreateDirectory(Path.Combine(dir, "2027")).FullName; var year = Directory.CreateDirectory(Path.Combine(dir, "2027")).FullName;
@@ -239,7 +236,7 @@ public sealed class AuditLogArchiveCleanupTests : IClassFixture<MsSqlMigrationFi
} }
var oldTmpData = Make(orphanA + ".parquet.tmp"); var oldTmpData = Make(orphanA + ".parquet.tmp");
var oldTmpTomb = Make(orphanA + ".tombstones.parquet.tmp"); var oldTmpTomb = Make(orphanA + ".tombstones.parquet.tmp"); // a format-v1 writer's temp file
var oldTmpManifest = Make(orphanA + ".manifest.json.tmp"); var oldTmpManifest = Make(orphanA + ".manifest.json.tmp");
var oldNoManifestData = Make(orphanA + ".parquet"); var oldNoManifestData = Make(orphanA + ".parquet");
var oldNoManifestTomb = Make(orphanA + ".tombstones.parquet"); var oldNoManifestTomb = Make(orphanA + ".tombstones.parquet");
@@ -252,7 +249,7 @@ public sealed class AuditLogArchiveCleanupTests : IClassFixture<MsSqlMigrationFi
var otherDir = Path.Combine(dir, "misc", orphanA + ".parquet.tmp"); var otherDir = Path.Combine(dir, "misc", orphanA + ".parquet.tmp");
File.WriteAllText(otherDir, "x"); File.WriteAllText(otherDir, "x");
File.SetLastWriteTimeUtc(otherDir, old); File.SetLastWriteTimeUtc(otherDir, old);
var committedFiles = new[] { ManifestPath(dir, committed), Path.Combine(year, committed.Name + ".parquet"), Path.Combine(year, committed.Name + ".tombstones.parquet") }; var committedFiles = new[] { ManifestPath(dir, committed), Path.Combine(year, committed.Name + ".parquet") };
foreach (var f in committedFiles) foreach (var f in committedFiles)
{ {
File.SetLastWriteTimeUtc(f, old); File.SetLastWriteTimeUtc(f, old);
@@ -323,22 +320,6 @@ public sealed class AuditLogArchiveCleanupTests : IClassFixture<MsSqlMigrationFi
} }
} }
private async Task DrainAsync()
{
await using var ctx = CreateContext();
var chain = new AuditLogHashChain(ctx);
for (var i = 0; i < 1000; i++)
{
var r = await chain.ChainPendingAsync(500, chainBacklog: true);
if (r.RowsChained == 0 && !r.LockBusy)
{
return;
}
}
throw new InvalidOperationException("Chain did not drain.");
}
private static DateTime Month(int year, int month) => new(year, month, 1, 0, 0, 0, DateTimeKind.Utc); private static DateTime Month(int year, int month) => new(year, month, 1, 0, 0, 0, DateTimeKind.Utc);
private ScadaBridgeDbContext CreateContext() private ScadaBridgeDbContext CreateContext()
@@ -1,561 +0,0 @@
using System.Data;
using Microsoft.Data.SqlClient;
using Microsoft.EntityFrameworkCore;
using ZB.MOM.WW.Audit;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums;
using ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance;
using ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Repositories;
using ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Tests.Migrations;
namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Tests.Maintenance;
/// <summary>
/// SQL Server integration tests for the hash-chain cutoff (ScadaBridge#139): enabling the
/// chain on a database with history chains only rows from the enablement instant on (owner
/// decision on #107, 2026-11-13), verification treats the backlog as out of scope, the
/// tamper cases are still caught, moving a row (or the cutoff) across the cutoff is caught,
/// both purge paths keep the chain verifiable across the cutoff, and both central nodes
/// settle on one cutoff.
/// </summary>
/// <remarks>
/// The cutoff is one row per database, so every test starts from an empty AuditLog and empty
/// chain tables (<see cref="ResetAsync"/>). xunit runs a class's tests sequentially.
/// </remarks>
public sealed class AuditLogHashChainCutoffTests : IClassFixture<MsSqlMigrationFixture>, IDisposable
{
private static readonly DateTime Backlog = new(2026, 2, 1, 0, 0, 0, DateTimeKind.Utc);
private static readonly DateTime CutoffMonth = new(2026, 3, 1, 0, 0, 0, DateTimeKind.Utc);
private static readonly DateTime After = new(2026, 4, 1, 0, 0, 0, DateTimeKind.Utc);
private static readonly DateTime Cutoff = new(2026, 3, 15, 12, 0, 0, DateTimeKind.Utc);
private readonly MsSqlMigrationFixture _fixture;
private readonly DirectoryInfo _archiveRoot = Directory.CreateTempSubdirectory("auditlog-cutoff-archive-");
/// <summary>Creates the test class with its own migrated SQL Server database.</summary>
/// <param name="fixture">The per-class migration fixture.</param>
public AuditLogHashChainCutoffTests(MsSqlMigrationFixture fixture) => _fixture = fixture;
/// <inheritdoc />
public void Dispose() => _archiveRoot.Delete(recursive: true);
/// <summary>
/// The owner's decision end to end: a backlog exists, the chain is enabled, only rows dated
/// from the cutoff on are chained, the backlog is untouched, and every month verifies —
/// the backlog as pre-cutoff rows, never as unchained rows or a break.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task FirstEnablement_ChainsOnlyFromTheCutoff_BacklogUntouched_VerifiesIntact()
{
Skip.IfNot(_fixture.Available, _fixture.SkipReason);
await ResetAsync();
var backlog = Rows(Backlog.AddDays(3), 4).Concat(Rows(CutoffMonth.AddDays(2), 3)).ToList();
await InsertAsync(backlog);
await DrainAsync(); // first enablement: records the anchor at Cutoff, chains nothing
Assert.Equal(Cutoff, await AnchorCutoffAsync());
Assert.Equal(0L, await ScalarAsync<long>("SELECT COUNT_BIG(*) FROM dbo.AuditLog WHERE ChainSeq IS NOT NULL;"));
Assert.Equal(0L, await ScalarAsync<long>("SELECT COUNT_BIG(*) FROM dbo.AuditLogChainHead;"));
var post = Rows(Cutoff.AddMinutes(1), 5).Concat(Rows(After.AddDays(1), 2)).ToList();
await InsertAsync(post);
await DrainAsync();
// Every backlog row stays exactly as it was: unchained.
foreach (var e in backlog)
{
Assert.Equal(DBNull.Value, await ScalarAsync<object>($"SELECT ChainSeq FROM dbo.AuditLog WHERE EventId = '{e.EventId}';"));
}
var march = await VerifyAsync(CutoffMonth);
Assert.Equal(AuditChainStatus.Intact, march.Status);
Assert.Equal(5, march.RowsVerified);
Assert.Equal(0, march.UnchainedRows);
Assert.Equal(3, march.PreCutoffRows);
Assert.Equal(Cutoff, march.ChainFromUtc);
var february = await VerifyAsync(Backlog);
Assert.Equal(AuditChainStatus.NotChained, february.Status);
Assert.Equal(0, february.UnchainedRows);
Assert.Equal(4, february.PreCutoffRows);
var april = await VerifyAsync(After);
Assert.Equal(AuditChainStatus.Intact, april.Status);
Assert.Equal(2, april.RowsVerified);
Assert.Equal(0, april.PreCutoffRows);
// A late site row dated before the cutoff that reaches central after enablement is
// keyed on OccurredAtUtc: it stays out of scope (documented limit), not pending.
await InsertAsync(Rows(Cutoff.AddHours(-2), 1));
await DrainAsync();
march = await VerifyAsync(CutoffMonth);
Assert.Equal(AuditChainStatus.Intact, march.Status);
Assert.Equal(4, march.PreCutoffRows);
Assert.Equal(0, march.UnchainedRows);
}
/// <summary>
/// The cutoff month's first row links to the anchor, not to 32 zero bytes, and the
/// ordinary tamper cases are still caught after a cutoff start: edit, delete, tail delete.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task TamperCases_AreStillDetected_AfterACutoffStart()
{
Skip.IfNot(_fixture.Available, _fixture.SkipReason);
var events = await SeedCutoffChainAsync(postRows: 6);
Assert.Equal(AuditChainStatus.Intact, (await VerifyAsync(CutoffMonth)).Status);
// Edit the FIRST link (the one hashed against the anchor).
await ExecAsync($"UPDATE dbo.AuditLog SET Target = N'forged' WHERE EventId = '{events[0]}';");
var edited = await VerifyAsync(CutoffMonth);
Assert.Equal(AuditChainStatus.Broken, edited.Status);
Assert.Equal(AuditChainBreakKind.HashMismatch, edited.FirstBreak!.Kind);
Assert.Equal(1, edited.FirstBreak.ChainSeq);
Assert.Equal(events[0], edited.FirstBreak.EventId);
await ExecAsync($"UPDATE dbo.AuditLog SET Target = N'erp' WHERE EventId = '{events[0]}';");
Assert.Equal(AuditChainStatus.Intact, (await VerifyAsync(CutoffMonth)).Status);
var middleSeq = await SeqOfAsync(events[2]);
await ExecAsync($"DELETE FROM dbo.AuditLog WHERE EventId = '{events[2]}';");
var deleted = await VerifyAsync(CutoffMonth);
Assert.Equal(AuditChainStatus.Broken, deleted.Status);
Assert.Equal(AuditChainBreakKind.MissingRow, deleted.FirstBreak!.Kind);
Assert.Equal(middleSeq, deleted.FirstBreak.ChainSeq);
await ResetAsync();
events = await SeedCutoffChainAsync(postRows: 4);
await ExecAsync($"DELETE FROM dbo.AuditLog WHERE EventId = '{events[^1]}';");
var tail = await VerifyAsync(CutoffMonth);
Assert.Equal(AuditChainStatus.Broken, tail.Status);
Assert.Equal(AuditChainBreakKind.HeadMismatch, tail.FirstBreak!.Kind);
}
/// <summary>
/// The cutoff-eligibility attack: move a chained row's timestamp back before the cutoff to
/// hide it among the unprotected backlog rows. Caught with its ChainSeq left in place
/// (<see cref="AuditChainBreakKind.ChainedBeforeCutoff"/>), and with its link cleared too
/// (its sequence number goes missing). Moving it into an earlier month is caught in both months.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task ChainedRowMovedBeforeTheCutoff_IsDetected()
{
Skip.IfNot(_fixture.Available, _fixture.SkipReason);
var events = await SeedCutoffChainAsync(postRows: 5);
var victim = events[2];
var victimSeq = await SeqOfAsync(victim);
// 1. Timestamp moved back across the cutoff, link left in place.
await ExecAsync($"UPDATE dbo.AuditLog SET OccurredAtUtc = '{Cutoff.AddHours(-1):yyyy-MM-dd HH:mm:ss}' WHERE EventId = '{victim}';");
var moved = await VerifyAsync(CutoffMonth);
Assert.Equal(AuditChainStatus.Broken, moved.Status);
Assert.Equal(AuditChainBreakKind.ChainedBeforeCutoff, moved.FirstBreak!.Kind);
Assert.Equal(victim, moved.FirstBreak.EventId);
Assert.Equal(victimSeq, moved.FirstBreak.ChainSeq);
// 2. ...and its link cleared, so it looks like any other pre-cutoff row.
await ExecAsync($"UPDATE dbo.AuditLog SET ChainSeq = NULL, RowHash = NULL WHERE EventId = '{victim}';");
var hidden = await VerifyAsync(CutoffMonth);
Assert.Equal(AuditChainStatus.Broken, hidden.Status);
Assert.Equal(AuditChainBreakKind.MissingRow, hidden.FirstBreak!.Kind);
Assert.Equal(victimSeq, hidden.FirstBreak.ChainSeq);
Assert.Equal(4, hidden.PreCutoffRows); // the 3 backlog rows + the hidden one
// 3. Moved into the previous (backlog) month with its link: caught in both months.
await ResetAsync();
events = await SeedCutoffChainAsync(postRows: 5);
victim = events[1];
await ExecAsync($"UPDATE dbo.AuditLog SET OccurredAtUtc = '{Backlog.AddDays(9):yyyy-MM-dd HH:mm:ss}' WHERE EventId = '{victim}';");
Assert.Equal(AuditChainBreakKind.MissingRow, (await VerifyAsync(CutoffMonth)).FirstBreak!.Kind);
var february = await VerifyAsync(Backlog);
Assert.Equal(AuditChainStatus.Broken, february.Status);
Assert.Equal(AuditChainBreakKind.ChainedBeforeCutoff, february.FirstBreak!.Kind);
Assert.Equal(victim, february.FirstBreak.EventId);
}
/// <summary>
/// The other half of the eligibility attack: moving the cutoff itself. Editing the anchor's
/// cutoff, re-hashing the anchor to match, deleting it, or adding a second anchor are each
/// reported, so the backlog/scope boundary cannot be shifted silently.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task CutoffAnchorTampering_IsDetected()
{
Skip.IfNot(_fixture.Available, _fixture.SkipReason);
await SeedCutoffChainAsync(postRows: 4);
var later = Cutoff.AddDays(5);
// Cutoff moved forward, anchor hash left alone.
await ExecAsync($"UPDATE dbo.AuditLogChainTombstone SET PurgedAtUtc = '{later:yyyy-MM-dd HH:mm:ss}' WHERE ChainSeq = 0;");
var moved = await VerifyAsync(CutoffMonth);
Assert.Equal(AuditChainStatus.Broken, moved.Status);
Assert.Equal(AuditChainBreakKind.CutoffAnchorInvalid, moved.FirstBreak!.Kind);
Assert.Equal(AuditChainStatus.Broken, (await VerifyAsync(After)).Status); // every month sees it
// Cutoff moved forward AND the anchor re-hashed to match: the chained rows now precede it.
await SetAnchorAsync(later, AuditChainHasher.ComputeCutoffAnchorHash(later));
var rehashed = await VerifyAsync(CutoffMonth);
Assert.Equal(AuditChainStatus.Broken, rehashed.Status);
Assert.Equal(AuditChainBreakKind.ChainedBeforeCutoff, rehashed.FirstBreak!.Kind);
// Anchor deleted: the cutoff month's first link no longer starts from it.
await ExecAsync("DELETE FROM dbo.AuditLogChainTombstone WHERE ChainSeq = 0;");
var deleted = await VerifyAsync(CutoffMonth);
Assert.Equal(AuditChainStatus.Broken, deleted.Status);
Assert.Equal(AuditChainBreakKind.HashMismatch, deleted.FirstBreak!.Kind);
Assert.Equal(1, deleted.FirstBreak.ChainSeq);
// Restored → intact (positive control); then a second anchor is reported.
await SetAnchorAsync(Cutoff, AuditChainHasher.ComputeCutoffAnchorHash(Cutoff));
Assert.Equal(AuditChainStatus.Intact, (await VerifyAsync(CutoffMonth)).Status);
var earlier = Backlog.AddDays(1);
await ExecAsync(
"INSERT INTO dbo.AuditLogChainTombstone (ChainMonth, ChainSeq, RowHash, EventId, PurgedAtUtc) " +
$"VALUES ('{Backlog:yyyy-MM-dd}', 0, 0x{Convert.ToHexString(AuditChainHasher.ComputeCutoffAnchorHash(earlier))}, NEWID(), '{earlier:yyyy-MM-dd HH:mm:ss}');");
var twoAnchors = await VerifyAsync(CutoffMonth);
Assert.Equal(AuditChainStatus.Broken, twoAnchors.Status);
Assert.Equal(AuditChainBreakKind.CutoffAnchorInvalid, twoAnchors.FirstBreak!.Kind);
}
/// <summary>
/// Both purge paths across the cutoff: a per-channel purge that deletes backlog and chained
/// rows alike leaves an intact chain; the head store and an export of it agree (the anchor is
/// not counted as a purge tombstone); the partition switch-out of the cutoff month keeps the
/// anchor and anchors the month; the archive of that month verifies from its own files; and
/// the chainer still honours the cutoff afterwards.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task PurgeAcrossTheCutoff_KeepsEveryChainVerifiable()
{
Skip.IfNot(_fixture.Available, _fixture.SkipReason);
await ResetAsync();
var preDb = Rows(CutoffMonth.AddDays(1), 2, AuditChannel.DbOutbound);
var preApi = Rows(CutoffMonth.AddDays(2), 2);
await InsertAsync(preDb.Concat(preApi));
await DrainAsync();
var postDb = Rows(Cutoff.AddHours(1), 3, AuditChannel.DbOutbound);
var postApi = Rows(Cutoff.AddHours(2), 3);
await InsertAsync(postDb.Concat(postApi));
await DrainAsync();
// Per-channel purge with a threshold past the cutoff: 2 backlog + 3 chained DbOutbound rows.
await using (var ctx = CreateContext())
{
var purged = await new AuditLogRepository(ctx).PurgeChannelOlderThanAsync(
nameof(AuditChannel.DbOutbound), Cutoff.AddDays(1), batchSize: 2);
Assert.Equal(5, purged);
}
var afterChannelPurge = await VerifyAsync(CutoffMonth);
Assert.Equal(AuditChainStatus.Intact, afterChannelPurge.Status);
Assert.Equal(3, afterChannelPurge.TombstonesApplied);
Assert.Equal(3, afterChannelPurge.RowsVerified);
Assert.Equal(2, afterChannelPurge.PreCutoffRows);
// Head store + export: the anchor is not a purge tombstone; an export verifies as Matches.
await using (var ctx = CreateContext())
{
var head = Assert.Single(await new AuditLogHashChain(ctx).ReadHeadsAsync());
Assert.Equal(3, head.Tombstones);
Assert.Equal(3, head.ChainedRows);
var exported = await new AuditLogHashChain(ctx).VerifyExportedHeadsAsync([Export(head)]);
Assert.True(exported.Verified);
Assert.Equal(AuditChainHeadStatus.Matches, Assert.Single(exported.Checks).Status);
}
// Archive the cutoff month, then switch it out through the archive guard.
AuditArchiveManifest manifest;
await using (var ctx = CreateContext())
{
manifest = await Archive(ctx).ArchivePartitionAsync(CutoffMonth);
await Archive(ctx).PurgeArchivedPartitionAsync(manifest);
}
Assert.Equal(Cutoff, await AnchorCutoffAsync()); // the anchor survives the switch-out
var switched = await VerifyAsync(CutoffMonth);
Assert.Equal(AuditChainStatus.Intact, switched.Status);
Assert.Equal(6, switched.PurgedThroughSeq);
Assert.Equal(0, switched.PreCutoffRows);
await using (var ctx = CreateContext())
{
var archived = await Archive(ctx).VerifyAsync(manifest.Name);
Assert.True(archived.Verified, archived.FileProblem);
var chain = Assert.Single(archived.Chains).Chain;
Assert.Equal(AuditChainStatus.Intact, chain.Status);
Assert.Equal(3, chain.RowsVerified);
Assert.Equal(3, chain.TombstonesApplied);
Assert.Equal(2, chain.PreCutoffRows); // the archive classifies its backlog rows too
Assert.Equal(0, chain.UnchainedRows);
Assert.Equal(Cutoff, chain.ChainFromUtc);
}
// After the purge the cutoff still holds: a late backlog row stays out, a late post-cutoff row chains on.
var lateBacklog = Rows(Backlog.AddDays(4), 1);
var latePost = Rows(Cutoff.AddHours(5), 1);
await InsertAsync(lateBacklog.Concat(latePost));
await DrainAsync();
Assert.Equal(DBNull.Value, await ScalarAsync<object>($"SELECT ChainSeq FROM dbo.AuditLog WHERE EventId = '{lateBacklog[0].EventId}';"));
var late = await VerifyAsync(CutoffMonth);
Assert.Equal(AuditChainStatus.Intact, late.Status);
Assert.Equal(7, late.HeadSeq);
Assert.Equal(1, (await VerifyAsync(Backlog)).PreCutoffRows);
}
/// <summary>
/// Both central nodes settle on ONE cutoff: two chainers race the first enablement on a
/// pristine database with the real database clock, exactly one anchor is written (inside the
/// database clock window of the race), and a node configured to chain the backlog that runs
/// after the decision cannot override it.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task BothNodes_AgreeOnOneCutoff()
{
Skip.IfNot(_fixture.Available, _fixture.SkipReason);
await ResetAsync();
var backlog = Rows(CutoffMonth.AddDays(1), 5);
await InsertAsync(backlog);
var before = await ScalarAsync<DateTime>("SELECT SYSUTCDATETIME();");
var start = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
async Task Node()
{
await start.Task;
for (var i = 0; i < 20; i++)
{
await using var ctx = CreateContext();
await new AuditLogHashChain(ctx).ChainPendingAsync(100); // production clock
}
}
var nodes = new[] { Task.Run(Node), Task.Run(Node) };
start.SetResult();
await Task.WhenAll(nodes);
var after = await ScalarAsync<DateTime>("SELECT SYSUTCDATETIME();");
Assert.Equal(1L, await ScalarAsync<long>("SELECT COUNT_BIG(*) FROM dbo.AuditLogChainTombstone WHERE ChainSeq = 0;"));
var cutoff = await AnchorCutoffAsync();
Assert.InRange(cutoff, before, after);
// The peer node configured with ChainBacklog=true runs after the decision: still no backlog chained.
await using (var ctx = CreateContext())
{
Assert.Equal(0, (await new AuditLogHashChain(ctx).ChainPendingAsync(100, chainBacklog: true)).RowsChained);
}
Assert.Equal(0L, await ScalarAsync<long>("SELECT COUNT_BIG(*) FROM dbo.AuditLog WHERE ChainSeq IS NOT NULL;"));
Assert.Equal(1L, await ScalarAsync<long>("SELECT COUNT_BIG(*) FROM dbo.AuditLogChainTombstone WHERE ChainSeq = 0;"));
var verified = await VerifyAsync(AuditChainHasher.MonthOf(cutoff));
Assert.Equal(cutoff, verified.ChainFromUtc);
}
/// <summary>
/// The old behaviour stays reachable and unchanged: ChainBacklog=true on a pristine database
/// writes no anchor and chains everything, and a database that already holds a chain (legacy
/// enablement, no anchor) keeps chaining every row even with ChainBacklog=false.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task ChainBacklog_AndLegacyChains_KeepChainingEverything()
{
Skip.IfNot(_fixture.Available, _fixture.SkipReason);
await ResetAsync();
await InsertAsync(Rows(Backlog.AddDays(1), 3));
await DrainAsync(chainBacklog: true);
Assert.Equal(0L, await ScalarAsync<long>("SELECT COUNT_BIG(*) FROM dbo.AuditLogChainTombstone WHERE ChainSeq = 0;"));
Assert.Equal(3L, await ScalarAsync<long>("SELECT COUNT_BIG(*) FROM dbo.AuditLog WHERE ChainSeq IS NOT NULL;"));
// Now a node on the default (no backlog) sees an existing chain: no anchor, old rows still chain.
await InsertAsync(Rows(Backlog.AddDays(10), 2));
await DrainAsync();
Assert.Equal(0L, await ScalarAsync<long>("SELECT COUNT_BIG(*) FROM dbo.AuditLogChainTombstone WHERE ChainSeq = 0;"));
var february = await VerifyAsync(Backlog);
Assert.Equal(AuditChainStatus.Intact, february.Status);
Assert.Equal(5, february.RowsVerified);
Assert.Null(february.ChainFromUtc);
Assert.Equal(0, february.PreCutoffRows);
}
/// <summary>
/// The hardened maintenance login (<c>scadabridge_audit_chainer</c> + <c>scadabridge_audit_purger</c>,
/// ScadaBridge#107 item 3) can write the chain-start anchor: no extra grant, no migration.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task MaintenanceLogin_CanWriteTheAnchor()
{
Skip.IfNot(_fixture.Available, _fixture.SkipReason);
await ResetAsync();
var login = "sbc_" + Guid.NewGuid().ToString("N")[..10];
const string password = "Sb_W22_cutoff#2026";
await ExecAsync($@"
CREATE LOGIN [{login}] WITH PASSWORD = N'{password}', CHECK_POLICY = OFF;
CREATE USER [{login}] FOR LOGIN [{login}];
ALTER ROLE scadabridge_audit_chainer ADD MEMBER [{login}];
ALTER ROLE scadabridge_audit_purger ADD MEMBER [{login}];");
try
{
await InsertAsync(Rows(Backlog.AddDays(2), 2));
var maintenance = new SqlConnectionStringBuilder(_fixture.ConnectionString)
{
IntegratedSecurity = false,
UserID = login,
Password = password,
Pooling = false,
}.ConnectionString;
await using (var ctx = new ScadaBridgeDbContext(
new DbContextOptionsBuilder<ScadaBridgeDbContext>().UseSqlServer(maintenance).Options))
{
var chain = new AuditLogHashChain(ctx) { AnchorClock = () => Cutoff };
Assert.Equal(0, (await chain.ChainPendingAsync(100)).RowsChained);
}
Assert.Equal(Cutoff, await AnchorCutoffAsync());
}
finally
{
SqlConnection.ClearAllPools();
await ExecAsync($@"
DECLARE @kill nvarchar(max) = N'';
SELECT @kill = @kill + N'KILL ' + CAST(session_id AS nvarchar(10)) + N';' FROM sys.dm_exec_sessions WHERE login_name = N'{login}';
EXEC sp_executesql @kill;
DROP USER [{login}];
DROP LOGIN [{login}];");
}
}
// ── helpers ──────────────────────────────────────────────────────────────
/// <summary>
/// Backlog in February and early March, first enablement at <see cref="Cutoff"/>, then
/// <paramref name="postRows"/> rows after it, all chained. Returns the post-cutoff EventIds in chain order.
/// </summary>
private async Task<List<Guid>> SeedCutoffChainAsync(int postRows)
{
await ResetAsync();
await InsertAsync(Rows(Backlog.AddDays(3), 2).Concat(Rows(CutoffMonth.AddDays(2), 3)));
await DrainAsync();
var post = Rows(Cutoff.AddMinutes(1), postRows);
await InsertAsync(post);
await DrainAsync();
return post.Select(e => e.EventId).ToList();
}
private async Task ResetAsync()
{
if (!_fixture.Available)
{
return;
}
await ExecAsync("DELETE FROM dbo.AuditLog; DELETE FROM dbo.AuditLogChainHead; DELETE FROM dbo.AuditLogChainTombstone;");
}
private async Task DrainAsync(bool chainBacklog = false)
{
await using var ctx = CreateContext();
var chain = new AuditLogHashChain(ctx) { AnchorClock = () => Cutoff };
for (var i = 0; i < 1000; i++)
{
var r = await chain.ChainPendingAsync(500, chainBacklog);
if (r.RowsChained == 0 && !r.LockBusy)
{
return;
}
}
throw new InvalidOperationException("Chain did not drain.");
}
private async Task<AuditChainVerificationResult> VerifyAsync(DateTime month)
{
await using var ctx = CreateContext();
return await new AuditLogHashChain(ctx).VerifyMonthAsync(month);
}
private async Task<DateTime> AnchorCutoffAsync()
=> DateTime.SpecifyKind(
await ScalarAsync<DateTime>("SELECT PurgedAtUtc FROM dbo.AuditLogChainTombstone WHERE ChainSeq = 0;"),
DateTimeKind.Utc);
private async Task SetAnchorAsync(DateTime chainFrom, byte[] hash)
{
await ExecAsync("DELETE FROM dbo.AuditLogChainTombstone WHERE ChainSeq = 0;");
await ExecAsync(
"INSERT INTO dbo.AuditLogChainTombstone (ChainMonth, ChainSeq, RowHash, EventId, PurgedAtUtc) " +
$"VALUES ('{AuditChainHasher.MonthOf(chainFrom):yyyy-MM-dd}', 0, 0x{Convert.ToHexString(hash)}, '{AuditChainHasher.CutoffAnchorEventId}', '{chainFrom:yyyy-MM-dd HH:mm:ss}');");
}
private async Task<long> SeqOfAsync(Guid eventId)
=> await ScalarAsync<long>($"SELECT ChainSeq FROM dbo.AuditLog WHERE EventId = '{eventId}';");
private async Task InsertAsync(IEnumerable<AuditEvent> events)
{
await using var ctx = CreateContext();
var repo = new AuditLogRepository(ctx);
foreach (var e in events)
{
await repo.InsertIfNotExistsAsync(e);
}
}
private async Task ExecAsync(string sql)
{
await using var conn = new SqlConnection(_fixture.ConnectionString);
await conn.OpenAsync();
await using var cmd = conn.CreateCommand();
cmd.CommandText = sql;
await cmd.ExecuteNonQueryAsync();
}
private async Task<T> ScalarAsync<T>(string sql)
{
await using var conn = new SqlConnection(_fixture.ConnectionString);
await conn.OpenAsync();
await using var cmd = conn.CreateCommand();
cmd.CommandText = sql;
var value = await cmd.ExecuteScalarAsync();
return value is DateTime dt && typeof(T) == typeof(DateTime)
? (T)(object)DateTime.SpecifyKind(dt, DateTimeKind.Utc)
: (T)value!;
}
private AuditLogPartitionArchive Archive(ScadaBridgeDbContext ctx) => new(ctx, new AuditLogArchiveOptions
{
Enabled = true,
Directory = _archiveRoot.FullName,
RowGroupSize = 1_000,
});
private static AuditChainHeadRecord Export(AuditChainHeadSnapshot head) => new(
AuditChainHeadRecord.CurrentVersion,
AuditChainHasher.PartitionLabel(head.Month),
head.LastSeq,
AuditChainHeadComparer.ToHex(head.LastHash),
head.PurgedThroughSeq,
head.PurgedThroughHash is null ? null : AuditChainHeadComparer.ToHex(head.PurgedThroughHash),
head.ChainedRows,
head.Tombstones,
head.UpdatedAtUtc,
DateTime.UtcNow,
"central-a");
private ScadaBridgeDbContext CreateContext()
=> new(new DbContextOptionsBuilder<ScadaBridgeDbContext>().UseSqlServer(_fixture.ConnectionString).Options);
private static List<AuditEvent> Rows(DateTime first, int count, AuditChannel channel = AuditChannel.ApiOutbound)
=> Enumerable.Range(0, count).Select(i => ScadaBridgeAuditEventFactory.Create(
channel: channel,
kind: channel == AuditChannel.DbOutbound ? AuditKind.DbWrite : AuditKind.ApiCall,
status: AuditStatus.Delivered,
occurredAtUtc: first.AddMinutes(i),
target: "erp",
sourceNode: "central-a",
sourceSiteId: "cutoff-test")).ToList();
}
@@ -1,346 +0,0 @@
using Microsoft.Data.SqlClient;
using Microsoft.EntityFrameworkCore;
using ZB.MOM.WW.Audit;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums;
using ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance;
using ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Repositories;
using ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Tests.Migrations;
namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Tests.Maintenance;
/// <summary>
/// SQL Server integration tests for the AuditLog hash chain (ScadaBridge#41) against the
/// real migrated, partitioned schema: continuity under concurrent writers and chainers,
/// detection of an edited / deleted / reordered row, and survival of both purge paths.
/// </summary>
/// <remarks>
/// The fixture database is shared by the class and the chain is per month across the whole
/// table, so every test owns a distinct month (xunit runs one class's tests sequentially).
/// Each test drains the chain before tampering so no other month is left unchained.
/// </remarks>
public class AuditLogHashChainTests : IClassFixture<MsSqlMigrationFixture>
{
private readonly MsSqlMigrationFixture _fixture;
/// <summary>Creates the test class with the shared migrated SQL Server fixture.</summary>
/// <param name="fixture">The shared migration fixture.</param>
public AuditLogHashChainTests(MsSqlMigrationFixture fixture) => _fixture = fixture;
/// <summary>
/// Many concurrent INSERTs (the two central nodes + site ingest) racing two concurrent
/// chainers (a dual-active central pair) still produce one gap-free, intact chain.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task ConcurrentWritersAndChainers_ProduceOneIntactGapFreeChain()
{
Skip.IfNot(_fixture.Available, _fixture.SkipReason);
var month = Month(2026, 2);
const int writers = 8;
const int rowsPerWriter = 40;
using var stop = new CancellationTokenSource();
var lockBusySeen = 0;
async Task ChainLoop()
{
while (!stop.IsCancellationRequested)
{
await using var ctx = CreateContext();
var r = await new AuditLogHashChain(ctx).ChainPendingAsync(17, chainBacklog: true);
if (r.LockBusy) Interlocked.Increment(ref lockBusySeen);
if (r.RowsChained == 0) await Task.Delay(5);
}
}
var chainers = new[] { Task.Run(ChainLoop), Task.Run(ChainLoop) };
var writerTasks = Enumerable.Range(0, writers).Select(w => Task.Run(async () =>
{
for (var i = 0; i < rowsPerWriter; i++)
{
await using var ctx = CreateContext();
// Out-of-order OccurredAtUtc on purpose: late-arriving site rows.
var at = month.AddDays((w * 7 + i * 13) % 27).AddSeconds(i);
await new AuditLogRepository(ctx).InsertIfNotExistsAsync(NewEvent(at, sourceNode: $"node-{w}"));
}
})).ToArray();
await Task.WhenAll(writerTasks);
await Task.Delay(200);
await stop.CancelAsync();
await Task.WhenAll(chainers);
await DrainAsync();
var result = await VerifyAsync(month);
Assert.Equal(AuditChainStatus.Intact, result.Status);
Assert.Equal(writers * rowsPerWriter, result.RowsVerified);
Assert.Equal(writers * rowsPerWriter, result.HeadSeq);
Assert.Equal(0, result.UnchainedRows);
var seqs = await ChainSeqsAsync(month);
Assert.Equal(Enumerable.Range(1, writers * rowsPerWriter).Select(i => (long)i), seqs);
}
/// <summary>Editing a chained row's content is reported at that row.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task EditedRow_IsDetected_WithRowIdAndPartition()
{
Skip.IfNot(_fixture.Available, _fixture.SkipReason);
var month = Month(2026, 3);
var events = await SeedAndChainAsync(month, 6);
Assert.Equal(AuditChainStatus.Intact, (await VerifyAsync(month)).Status);
var victim = events[3];
await ExecAsync($"UPDATE dbo.AuditLog SET Target = N'forged' WHERE EventId = '{victim}';");
var result = await VerifyAsync(month);
Assert.Equal(AuditChainStatus.Broken, result.Status);
Assert.Equal(AuditChainBreakKind.HashMismatch, result.FirstBreak!.Kind);
Assert.Equal("2026-03", result.FirstBreak.Partition);
Assert.Equal(victim, result.FirstBreak.EventId);
Assert.Equal(await SeqOfAsync(victim), result.FirstBreak.ChainSeq);
}
/// <summary>Deleting a chained row outside the purge path is reported as a missing sequence number.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task DeletedRow_IsDetected()
{
Skip.IfNot(_fixture.Available, _fixture.SkipReason);
var month = Month(2026, 4);
var events = await SeedAndChainAsync(month, 6);
var victim = events[2];
var victimSeq = await SeqOfAsync(victim);
await ExecAsync($"DELETE FROM dbo.AuditLog WHERE EventId = '{victim}';");
var result = await VerifyAsync(month);
Assert.Equal(AuditChainStatus.Broken, result.Status);
Assert.Equal(AuditChainBreakKind.MissingRow, result.FirstBreak!.Kind);
Assert.Equal(victimSeq, result.FirstBreak.ChainSeq);
Assert.Equal("2026-04", result.FirstBreak.Partition);
}
/// <summary>Swapping two rows' chain positions is reported.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task ReorderedRows_AreDetected()
{
Skip.IfNot(_fixture.Available, _fixture.SkipReason);
var month = Month(2026, 5);
var events = await SeedAndChainAsync(month, 6);
var a = events[1];
var b = events[4];
var seqA = await SeqOfAsync(a);
var seqB = await SeqOfAsync(b);
await ExecAsync(
$"UPDATE dbo.AuditLog SET ChainSeq = CASE WHEN EventId = '{a}' THEN {seqB} ELSE {seqA} END " +
$"WHERE EventId IN ('{a}', '{b}');");
var result = await VerifyAsync(month);
Assert.Equal(AuditChainStatus.Broken, result.Status);
Assert.Equal(AuditChainBreakKind.HashMismatch, result.FirstBreak!.Kind);
Assert.Equal(Math.Min(seqA, seqB), result.FirstBreak.ChainSeq);
}
/// <summary>
/// The per-channel retention DELETE removes chained rows from the middle of a month and
/// the chain still verifies (tombstones); a later chaining pass continues the chain.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task PerChannelPurge_LeavesAVerifiableChain()
{
Skip.IfNot(_fixture.Available, _fixture.SkipReason);
var month = Month(2026, 6);
var rows = new List<AuditEvent>();
for (var i = 0; i < 10; i++)
{
rows.Add(NewEvent(month.AddDays(i + 1),
channel: i % 2 == 0 ? AuditChannel.DbOutbound : AuditChannel.ApiOutbound,
kind: i % 2 == 0 ? AuditKind.DbWrite : AuditKind.ApiCall));
}
await InsertAsync(rows);
await DrainAsync();
await using (var ctx = CreateContext())
{
var purged = await new AuditLogRepository(ctx).PurgeChannelOlderThanAsync(
nameof(AuditChannel.DbOutbound), month.AddDays(8), batchSize: 2);
Assert.Equal(4, purged); // days 1,3,5,7
}
var result = await VerifyAsync(month);
Assert.Equal(AuditChainStatus.Intact, result.Status);
Assert.Equal(4, result.TombstonesApplied);
Assert.Equal(6, result.RowsVerified);
// A row arriving after the purge chains on from the existing head.
await InsertAsync([NewEvent(month.AddDays(20))]);
await DrainAsync();
result = await VerifyAsync(month);
Assert.Equal(AuditChainStatus.Intact, result.Status);
Assert.Equal(11, result.HeadSeq);
}
/// <summary>
/// The monthly partition-switch purge removes the whole month; the head's checkpoint
/// anchor keeps the month verifiable, including for a late row chained afterwards.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task PartitionSwitchPurge_LeavesAnAnchoredVerifiableChain()
{
Skip.IfNot(_fixture.Available, _fixture.SkipReason);
var month = Month(2026, 7);
await SeedAndChainAsync(month, 5);
await using (var ctx = CreateContext())
{
await new AuditLogRepository(ctx).SwitchOutPartitionAsync(month);
}
var result = await VerifyAsync(month);
Assert.Equal(AuditChainStatus.Intact, result.Status);
Assert.Equal(5, result.PurgedThroughSeq);
Assert.Equal(0, result.RowsVerified);
await InsertAsync([NewEvent(month.AddDays(3))]);
await DrainAsync();
result = await VerifyAsync(month);
Assert.Equal(AuditChainStatus.Intact, result.Status);
Assert.Equal(1, result.RowsVerified);
Assert.Equal(6, result.HeadSeq);
}
/// <summary>
/// The SourceNode backfill (the other sanctioned AuditLog UPDATE) must not touch a chained
/// row — SourceNode is inside its hash.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task SourceNodeBackfill_SkipsChainedRows()
{
Skip.IfNot(_fixture.Available, _fixture.SkipReason);
var month = Month(2026, 8);
await InsertAsync([NewEvent(month.AddDays(2), sourceNode: null)]);
await DrainAsync();
var unchained = NewEvent(month.AddDays(3), sourceNode: null);
// A row written after the drain stays unchained until the next pass.
await InsertAsync([unchained]);
await using (var ctx = CreateContext())
{
await new AuditLogRepository(ctx).BackfillSourceNodeAsync("unknown", month.AddMonths(1), batchSize: 10);
}
await DrainAsync();
var result = await VerifyAsync(month);
Assert.Equal(AuditChainStatus.Intact, result.Status);
Assert.Equal(2, result.RowsVerified);
Assert.Equal("unknown", await ScalarAsync<string>($"SELECT SourceNode FROM dbo.AuditLog WHERE EventId = '{unchained.EventId}';"));
}
// ── helpers ──────────────────────────────────────────────────────────────
private static DateTime Month(int year, int month) => new(year, month, 1, 0, 0, 0, DateTimeKind.Utc);
private async Task<List<Guid>> SeedAndChainAsync(DateTime month, int count)
{
var events = Enumerable.Range(1, count).Select(i => NewEvent(month.AddDays(i).AddMinutes(i))).ToList();
await InsertAsync(events);
await DrainAsync();
return events.Select(e => e.EventId).ToList();
}
private async Task InsertAsync(IEnumerable<AuditEvent> events)
{
await using var ctx = CreateContext();
var repo = new AuditLogRepository(ctx);
foreach (var e in events)
{
await repo.InsertIfNotExistsAsync(e);
}
}
private async Task DrainAsync()
{
await using var ctx = CreateContext();
var chain = new AuditLogHashChain(ctx);
for (var i = 0; i < 1000; i++)
{
var r = await chain.ChainPendingAsync(500, chainBacklog: true);
if (r.RowsChained == 0 && !r.LockBusy)
{
return;
}
}
throw new InvalidOperationException("Chain did not drain.");
}
private async Task<AuditChainVerificationResult> VerifyAsync(DateTime month)
{
await using var ctx = CreateContext();
return await new AuditLogHashChain(ctx).VerifyMonthAsync(month);
}
private async Task<long> SeqOfAsync(Guid eventId)
=> await ScalarAsync<long>($"SELECT ChainSeq FROM dbo.AuditLog WHERE EventId = '{eventId}';");
private async Task<List<long>> ChainSeqsAsync(DateTime month)
{
await using var conn = new SqlConnection(_fixture.ConnectionString);
await conn.OpenAsync();
await using var cmd = conn.CreateCommand();
cmd.CommandText = "SELECT ChainSeq FROM dbo.AuditLog WHERE OccurredAtUtc >= @s AND OccurredAtUtc < @e ORDER BY ChainSeq;";
cmd.Parameters.Add(new SqlParameter("@s", System.Data.SqlDbType.DateTime2) { Value = month });
cmd.Parameters.Add(new SqlParameter("@e", System.Data.SqlDbType.DateTime2) { Value = month.AddMonths(1) });
var list = new List<long>();
await using var reader = await cmd.ExecuteReaderAsync();
while (await reader.ReadAsync())
{
list.Add(reader.GetInt64(0));
}
return list;
}
private async Task ExecAsync(string sql)
{
await using var conn = new SqlConnection(_fixture.ConnectionString);
await conn.OpenAsync();
await using var cmd = conn.CreateCommand();
cmd.CommandText = sql;
await cmd.ExecuteNonQueryAsync();
}
private async Task<T> ScalarAsync<T>(string sql)
{
await using var conn = new SqlConnection(_fixture.ConnectionString);
await conn.OpenAsync();
await using var cmd = conn.CreateCommand();
cmd.CommandText = sql;
return (T)(await cmd.ExecuteScalarAsync())!;
}
private ScadaBridgeDbContext CreateContext()
=> new(new DbContextOptionsBuilder<ScadaBridgeDbContext>().UseSqlServer(_fixture.ConnectionString).Options);
private static AuditEvent NewEvent(
DateTime occurredAtUtc,
AuditChannel channel = AuditChannel.ApiOutbound,
AuditKind kind = AuditKind.ApiCall,
string? sourceNode = "central-a") =>
ScadaBridgeAuditEventFactory.Create(
channel: channel,
kind: kind,
status: AuditStatus.Delivered,
occurredAtUtc: occurredAtUtc,
target: "erp",
sourceNode: sourceNode,
sourceSiteId: "hash-chain-test");
}
@@ -13,13 +13,12 @@ namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Tests.Maintenance;
/// <summary> /// <summary>
/// SQL Server integration tests for the AuditLog Parquet archive (ScadaBridge#42) against the /// SQL Server integration tests for the AuditLog Parquet archive (ScadaBridge#42) against the
/// real migrated, partitioned schema: archive-then-purge leaves the month's hash chain /// real migrated, partitioned schema: archive-then-purge archives exactly the partition's rows
/// verifiable and the archive re-verifiable against the purge anchor; the purge refuses to /// and then drops them; the purge refuses to drop a partition that changed after it was
/// drop a partition that changed after it was archived; tampering with an archive is caught. /// archived; a damaged archive file is caught by verify.
/// </summary> /// </summary>
/// <remarks> /// <remarks>
/// Every test owns a distinct month (partition) of the shared fixture database; the chain /// Every test owns a distinct month (partition) of the shared fixture database.
/// and the per-channel purge are table-wide, so each test drains the chain itself.
/// </remarks> /// </remarks>
public sealed class AuditLogPartitionArchiveTests : IClassFixture<MsSqlMigrationFixture>, IDisposable public sealed class AuditLogPartitionArchiveTests : IClassFixture<MsSqlMigrationFixture>, IDisposable
{ {
@@ -34,42 +33,37 @@ public sealed class AuditLogPartitionArchiveTests : IClassFixture<MsSqlMigration
public void Dispose() => _root.Delete(recursive: true); public void Dispose() => _root.Delete(recursive: true);
/// <summary> /// <summary>
/// Archive, then purge: the archive holds exactly the partition's rows (chained, /// Archive, then purge: the archive holds exactly the partition's stored rows; the switch
/// unchained, with their chain columns) and its tombstones; after the switch the month's /// drops them, the manifest is marked Purged, and the archive verifies.
/// chain still verifies from the anchor, and the archive verifies against that anchor.
/// </summary> /// </summary>
/// <returns>A task that represents the asynchronous operation.</returns> /// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact] [SkippableFact]
public async Task ArchiveThenPurge_KeepsTheChainVerifiable_AndTheArchiveMatchesTheAnchor() public async Task ArchiveThenPurge_ArchivesExactlyThePartition_AndVerifies()
{ {
Skip.IfNot(_fixture.Available, _fixture.SkipReason); Skip.IfNot(_fixture.Available, _fixture.SkipReason);
var month = Month(2026, 2); var month = Month(2026, 2);
await InsertAsync(Enumerable.Range(1, 10).Select(i => NewEvent(month.AddDays(i).AddTicks(i * 7_777)))); await InsertAsync(Enumerable.Range(1, 10).Select(i => NewEvent(month.AddDays(i).AddTicks(i * 7_777))));
// Two rows of a short-retention channel, purged per channel mid-chain → tombstones. // Two rows of a short-retention channel, purged per channel before the archive.
await InsertAsync([NewEvent(month.AddHours(1), AuditChannel.DbOutbound), NewEvent(month.AddHours(2), AuditChannel.DbOutbound)]); await InsertAsync([NewEvent(month.AddHours(1), AuditChannel.DbOutbound), NewEvent(month.AddHours(2), AuditChannel.DbOutbound)]);
await DrainAsync();
await using (var ctx = CreateContext()) await using (var ctx = CreateContext())
{ {
Assert.Equal(2, await new AuditLogRepository(ctx).PurgeChannelOlderThanAsync("DbOutbound", month.AddDays(1), 100)); Assert.Equal(2, await new AuditLogRepository(ctx).PurgeChannelOlderThanAsync("DbOutbound", month.AddDays(1), 100));
} }
await InsertAsync([NewEvent(month.AddDays(20))]); // written after the drain: unchained await InsertAsync([NewEvent(month.AddDays(20))]);
var before = await PartitionRowsAsync(month); var before = await PartitionRowsAsync(month);
Assert.Equal(11, before.Count); Assert.Equal(11, before.Count);
var manifest = await ArchiveAsync(month); var manifest = await ArchiveAsync(month);
Assert.Equal(AuditArchiveStatus.Archived, manifest.Status); Assert.Equal(AuditArchiveStatus.Archived, manifest.Status);
Assert.Equal(AuditArchiveParquet.FormatVersion, manifest.FormatVersion);
Assert.Equal(11, manifest.RowCount); Assert.Equal(11, manifest.RowCount);
Assert.Equal(10, manifest.ChainedRowCount); Assert.Equal("2026-02", manifest.Partition);
Assert.Equal(1, manifest.UnchainedRowCount);
Assert.Equal(2, manifest.TombstoneCount);
var chain = Assert.Single(manifest.Chains);
Assert.Equal("2026-02", chain.Partition);
Assert.Equal(12, chain.LastSeq);
// Row equality: the archive's data file holds exactly the partition's stored rows. // Row equality: the archive's data file holds exactly the partition's stored rows.
var archived = await ReadArchiveRowsAsync(manifest); var archived = await ReadArchiveRowsAsync(manifest);
Assert.Equal(before.Select(Key).Order(), archived.Select(Key).Order()); Assert.Equal(before.Select(Key).Order(), archived.Select(Key).Order());
Assert.False(File.Exists(Path.Combine(_root.FullName, "2026", manifest.Name + AuditArchiveParquet.LegacyTombstoneSuffix)));
await using (var ctx = CreateContext()) await using (var ctx = CreateContext())
{ {
@@ -77,20 +71,11 @@ public sealed class AuditLogPartitionArchiveTests : IClassFixture<MsSqlMigration
} }
Assert.Empty(await PartitionRowsAsync(month)); Assert.Empty(await PartitionRowsAsync(month));
var monthChain = await VerifyMonthAsync(month);
Assert.Equal(AuditChainStatus.Intact, monthChain.Status);
Assert.Equal(12, monthChain.PurgedThroughSeq);
var verification = await VerifyArchiveAsync(manifest.Name); var verification = await VerifyArchiveAsync(manifest.Name);
Assert.True(verification.Verified, verification.FileProblem); Assert.True(verification.Verified, verification.FileProblem);
Assert.Equal(AuditArchiveStatus.Purged, verification.ManifestStatus); Assert.Equal(AuditArchiveStatus.Purged, verification.ManifestStatus);
Assert.Equal(11, verification.RowsRead); Assert.Equal(11, verification.RowsRead);
var v = Assert.Single(verification.Chains);
Assert.Equal(AuditChainStatus.Intact, v.Chain.Status);
Assert.Equal(10, v.Chain.RowsVerified);
Assert.Equal(2, v.Chain.TombstonesApplied);
Assert.Equal(1, v.Chain.UnchainedRows);
Assert.Equal(AuditArchiveAnchorStatus.Matches, v.Anchor);
await using (var ctx = CreateContext()) await using (var ctx = CreateContext())
{ {
@@ -112,7 +97,6 @@ public sealed class AuditLogPartitionArchiveTests : IClassFixture<MsSqlMigration
Skip.IfNot(_fixture.Available, _fixture.SkipReason); Skip.IfNot(_fixture.Available, _fixture.SkipReason);
var month = Month(2026, 3); var month = Month(2026, 3);
await InsertAsync(Enumerable.Range(1, 5).Select(i => NewEvent(month.AddDays(i)))); await InsertAsync(Enumerable.Range(1, 5).Select(i => NewEvent(month.AddDays(i))));
await DrainAsync();
var stale = await ArchiveAsync(month); var stale = await ArchiveAsync(month);
await InsertAsync([NewEvent(month.AddDays(9))]); await InsertAsync([NewEvent(month.AddDays(9))]);
@@ -123,12 +107,10 @@ public sealed class AuditLogPartitionArchiveTests : IClassFixture<MsSqlMigration
} }
Assert.Equal(6, (await PartitionRowsAsync(month)).Count); Assert.Equal(6, (await PartitionRowsAsync(month)).Count);
Assert.Null((await VerifyMonthAsync(month)).PurgedThroughSeq);
var staleVerification = await VerifyArchiveAsync(stale.Name); var staleVerification = await VerifyArchiveAsync(stale.Name);
Assert.True(staleVerification.Verified); Assert.True(staleVerification.Verified);
Assert.Equal(AuditArchiveStatus.Archived, staleVerification.ManifestStatus); Assert.Equal(AuditArchiveStatus.Archived, staleVerification.ManifestStatus);
Assert.Equal(AuditArchiveAnchorStatus.NotPurged, Assert.Single(staleVerification.Chains).Anchor);
// Positive control: a fresh archive holds the new row and is allowed to purge. // Positive control: a fresh archive holds the new row and is allowed to purge.
var fresh = await ArchiveAsync(month); var fresh = await ArchiveAsync(month);
@@ -142,45 +124,16 @@ public sealed class AuditLogPartitionArchiveTests : IClassFixture<MsSqlMigration
} }
/// <summary> /// <summary>
/// A chaining pass between the archive and the purge (the row count is unchanged, the /// A damaged archive fails verification: a flipped byte (file hash), and a re-written file
/// chain head moved) also stops the purge: otherwise the anchor would cover links the /// with one row dropped and the manifest's hash/size updated (row count).
/// archive does not hold.
/// </summary> /// </summary>
/// <returns>A task that represents the asynchronous operation.</returns> /// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact] [SkippableFact]
public async Task ChainAdvancingAfterTheArchive_StopsThePurge() public async Task DamagedArchive_FailsVerification()
{
Skip.IfNot(_fixture.Available, _fixture.SkipReason);
var month = Month(2026, 4);
await InsertAsync(Enumerable.Range(1, 4).Select(i => NewEvent(month.AddDays(i))));
await DrainAsync();
await InsertAsync([NewEvent(month.AddDays(8))]); // unchained at archive time
var manifest = await ArchiveAsync(month);
Assert.Equal(1, manifest.UnchainedRowCount);
await DrainAsync(); // links the row: head 4 → 5, row count unchanged
await using (var ctx = CreateContext())
{
var ex = await Assert.ThrowsAsync<AuditArchiveStaleException>(() => Archive(ctx).PurgeArchivedPartitionAsync(manifest));
Assert.Equal(AuditPartitionSwitchGuard.ChainAdvancedError, ((SqlException)ex.InnerException!).Number);
}
Assert.Equal(5, (await PartitionRowsAsync(month)).Count);
}
/// <summary>
/// Tampering with a purged archive is caught three ways: a flipped byte (file hash), a
/// re-written file with an edited row and a re-hashed manifest (chain), and a forger who
/// also recomputes the whole chain (the purge anchor in the database no longer matches).
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task TamperedArchive_FailsVerification()
{ {
Skip.IfNot(_fixture.Available, _fixture.SkipReason); Skip.IfNot(_fixture.Available, _fixture.SkipReason);
var month = Month(2026, 5); var month = Month(2026, 5);
await InsertAsync(Enumerable.Range(1, 8).Select(i => NewEvent(month.AddDays(i)))); await InsertAsync(Enumerable.Range(1, 8).Select(i => NewEvent(month.AddDays(i))));
await DrainAsync();
var manifest = await ArchiveAndPurgeAsync(month); var manifest = await ArchiveAndPurgeAsync(month);
Assert.True((await VerifyArchiveAsync(manifest.Name)).Verified); Assert.True((await VerifyArchiveAsync(manifest.Name)).Verified);
@@ -198,34 +151,14 @@ public sealed class AuditLogPartitionArchiveTests : IClassFixture<MsSqlMigration
Assert.False(result.FilesIntact); Assert.False(result.FilesIntact);
Assert.Contains("SHA-256", result.FileProblem); Assert.Contains("SHA-256", result.FileProblem);
// 2. An edited row in a re-written file, manifest hash/size updated to match. // 2. A row dropped from a re-written file, manifest hash/size updated to match.
var rows = await ReadArchiveRowsAsync(manifest, original); var rows = await ReadArchiveRowsAsync(manifest, original);
var victim = rows[3]; rows.RemoveAt(3);
rows[3] = victim with { Target = "forged" }; await RewriteAsync(rows, manifest, dataPath, manifestPath);
await RewriteAsync(rows, manifest, dataPath, manifestPath, lastHash: null);
result = await VerifyArchiveAsync(manifest.Name); result = await VerifyArchiveAsync(manifest.Name);
Assert.False(result.Verified); Assert.False(result.Verified);
Assert.True(result.FilesIntact); Assert.False(result.FilesIntact);
var brk = Assert.Single(result.Chains).Chain.FirstBreak!; Assert.Contains("7 rows", result.FileProblem);
Assert.Equal(AuditChainBreakKind.HashMismatch, brk.Kind);
Assert.Equal(victim.EventId, brk.EventId);
// 3. The forger recomputes every link and the manifest's chain end: the archive is
// self-consistent, but its end no longer matches the anchor the purge left.
var previous = AuditChainHasher.GenesisHash.ToArray();
for (var i = 0; i < rows.Count; i++)
{
var hash = AuditChainHasher.ComputeRowHash(previous, month, rows[i].ChainSeq!.Value, rows[i]);
rows[i] = rows[i] with { RowHash = hash };
previous = hash;
}
await RewriteAsync(rows, manifest, dataPath, manifestPath, lastHash: Convert.ToHexStringLower(previous));
result = await VerifyArchiveAsync(manifest.Name);
Assert.False(result.Verified);
var c = Assert.Single(result.Chains);
Assert.Equal(AuditChainStatus.Intact, c.Chain.Status);
Assert.Equal(AuditArchiveAnchorStatus.Mismatch, c.Anchor);
// Positive control: the untouched archive still verifies. // Positive control: the untouched archive still verifies.
await File.WriteAllBytesAsync(dataPath, original); await File.WriteAllBytesAsync(dataPath, original);
@@ -234,36 +167,63 @@ public sealed class AuditLogPartitionArchiveTests : IClassFixture<MsSqlMigration
} }
/// <summary> /// <summary>
/// Rows that arrive for a month after it was purged chain on from the anchor; archiving /// Rows that arrive for a month after it was purged are archived and purged again in a
/// and purging them again produces a second archive that resumes from the first one's end. /// second archive; both verify.
/// The first archive then reports its anchor as superseded, and both verify.
/// </summary> /// </summary>
/// <returns>A task that represents the asynchronous operation.</returns> /// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact] [SkippableFact]
public async Task LateRows_AreArchivedAgain_FromTheAnchor() public async Task LateRows_AreArchivedAgain()
{ {
Skip.IfNot(_fixture.Available, _fixture.SkipReason); Skip.IfNot(_fixture.Available, _fixture.SkipReason);
var month = Month(2026, 6); var month = Month(2026, 6);
await InsertAsync(Enumerable.Range(1, 3).Select(i => NewEvent(month.AddDays(i)))); await InsertAsync(Enumerable.Range(1, 3).Select(i => NewEvent(month.AddDays(i))));
await DrainAsync();
var first = await ArchiveAndPurgeAsync(month); var first = await ArchiveAndPurgeAsync(month);
await InsertAsync([NewEvent(month.AddDays(15)), NewEvent(month.AddDays(16))]); await InsertAsync([NewEvent(month.AddDays(15)), NewEvent(month.AddDays(16))]);
await DrainAsync();
await Task.Delay(5); // distinct archive name (millisecond stamp) await Task.Delay(5); // distinct archive name (millisecond stamp)
var second = await ArchiveAndPurgeAsync(month); var second = await ArchiveAndPurgeAsync(month);
var chain = Assert.Single(second.Chains); Assert.Equal(2, second.RowCount);
Assert.Equal(3, chain.PriorPurgedThroughSeq); Assert.Empty(await PartitionRowsAsync(month));
Assert.Equal(5, chain.LastSeq);
var secondResult = await VerifyArchiveAsync(second.Name); Assert.True((await VerifyArchiveAsync(second.Name)).Verified);
Assert.True(secondResult.Verified); Assert.True((await VerifyArchiveAsync(first.Name)).Verified);
Assert.Equal(AuditArchiveAnchorStatus.Matches, Assert.Single(secondResult.Chains).Anchor); }
Assert.Equal(2, Assert.Single(secondResult.Chains).Chain.RowsVerified);
var firstResult = await VerifyArchiveAsync(first.Name); /// <summary>
Assert.True(firstResult.Verified); /// A format-v1 manifest (written while the hash chain existed, with chain and tombstone
Assert.Equal(AuditArchiveAnchorStatus.Superseded, Assert.Single(firstResult.Chains).Anchor); /// fields) is still listed and verified.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task FormatV1Manifest_IsListedAndVerified()
{
Skip.IfNot(_fixture.Available, _fixture.SkipReason);
var month = Month(2026, 7);
await InsertAsync(Enumerable.Range(1, 4).Select(i => NewEvent(month.AddDays(i))));
var manifest = await ArchiveAndPurgeAsync(month);
var manifestPath = Path.Combine(_root.FullName, "2026", manifest.Name + ".manifest.json");
var node = System.Text.Json.Nodes.JsonNode.Parse(await File.ReadAllTextAsync(manifestPath))!.AsObject();
node["formatVersion"] = 1;
node["chainedRowCount"] = 4;
node["unchainedRowCount"] = 0;
node["tombstoneFile"] = manifest.Name + AuditArchiveParquet.LegacyTombstoneSuffix;
node["tombstoneSha256"] = new string('0', 64);
node["tombstoneCount"] = 0;
node["chains"] = new System.Text.Json.Nodes.JsonArray(new System.Text.Json.Nodes.JsonObject
{
["partition"] = "2026-07", ["lastSeq"] = 4, ["lastHash"] = new string('a', 64), ["tombstoneCount"] = 0,
});
await File.WriteAllTextAsync(manifestPath, node.ToJsonString());
await using (var ctx = CreateContext())
{
var listed = Assert.Single(await Archive(ctx).ListAsync(), m => m.Partition == "2026-07");
Assert.Equal(1, listed.FormatVersion);
Assert.Equal(4, listed.RowCount);
}
Assert.True((await VerifyArchiveAsync(manifest.Name)).Verified);
} }
/// <summary>A name that is not an archive name (e.g. a path) is rejected before any file access.</summary> /// <summary>A name that is not an archive name (e.g. a path) is rejected before any file access.</summary>
@@ -308,16 +268,10 @@ public sealed class AuditLogPartitionArchiveTests : IClassFixture<MsSqlMigration
return await Archive(ctx).VerifyAsync(name); return await Archive(ctx).VerifyAsync(name);
} }
private async Task<AuditChainVerificationResult> VerifyMonthAsync(DateTime month) private async Task<List<AuditArchiveRow>> ReadArchiveRowsAsync(AuditArchiveManifest manifest, byte[]? bytes = null)
{
await using var ctx = CreateContext();
return await new AuditLogHashChain(ctx).VerifyMonthAsync(month);
}
private async Task<List<AuditChainRow>> ReadArchiveRowsAsync(AuditArchiveManifest manifest, byte[]? bytes = null)
{ {
bytes ??= await File.ReadAllBytesAsync(Path.Combine(_root.FullName, manifest.Partition[..4], manifest.DataFile)); bytes ??= await File.ReadAllBytesAsync(Path.Combine(_root.FullName, manifest.Partition[..4], manifest.DataFile));
var rows = new List<AuditChainRow>(); var rows = new List<AuditArchiveRow>();
await foreach (var row in AuditArchiveParquet.ReadRowsAsync(new MemoryStream(bytes))) await foreach (var row in AuditArchiveParquet.ReadRowsAsync(new MemoryStream(bytes)))
{ {
rows.Add(row); rows.Add(row);
@@ -327,7 +281,7 @@ public sealed class AuditLogPartitionArchiveTests : IClassFixture<MsSqlMigration
} }
private static async Task RewriteAsync( private static async Task RewriteAsync(
List<AuditChainRow> rows, AuditArchiveManifest manifest, string dataPath, string manifestPath, string? lastHash) List<AuditArchiveRow> rows, AuditArchiveManifest manifest, string dataPath, string manifestPath)
{ {
var stream = new MemoryStream(); var stream = new MemoryStream();
await using (var writer = await AuditArchiveParquet.CreateDataWriterAsync(stream, manifest.Partition, 1_000)) await using (var writer = await AuditArchiveParquet.CreateDataWriterAsync(stream, manifest.Partition, 1_000))
@@ -345,7 +299,6 @@ public sealed class AuditLogPartitionArchiveTests : IClassFixture<MsSqlMigration
Status = AuditArchiveStatus.Purged, Status = AuditArchiveStatus.Purged,
DataSha256 = Convert.ToHexStringLower(System.Security.Cryptography.SHA256.HashData(bytes)), DataSha256 = Convert.ToHexStringLower(System.Security.Cryptography.SHA256.HashData(bytes)),
DataBytes = bytes.Length, DataBytes = bytes.Length,
Chains = lastHash is null ? manifest.Chains : [manifest.Chains[0] with { LastHash = lastHash }],
}; };
await File.WriteAllTextAsync(manifestPath, JsonSerializer.Serialize(forged, new JsonSerializerOptions await File.WriteAllTextAsync(manifestPath, JsonSerializer.Serialize(forged, new JsonSerializerOptions
{ {
@@ -353,29 +306,28 @@ public sealed class AuditLogPartitionArchiveTests : IClassFixture<MsSqlMigration
})); }));
} }
private async Task<List<AuditChainRow>> PartitionRowsAsync(DateTime month) private async Task<List<AuditArchiveRow>> PartitionRowsAsync(DateTime month)
{ {
await using var conn = new SqlConnection(_fixture.ConnectionString); await using var conn = new SqlConnection(_fixture.ConnectionString);
await conn.OpenAsync(); await conn.OpenAsync();
await using var cmd = conn.CreateCommand(); await using var cmd = conn.CreateCommand();
cmd.CommandText = $"SELECT {AuditLogHashChain.RowColumns}, ChainSeq, RowHash FROM dbo.AuditLog " cmd.CommandText = $"SELECT {AuditArchiveParquet.RowColumns} FROM dbo.AuditLog "
+ "WHERE OccurredAtUtc >= @s AND OccurredAtUtc < @e;"; + "WHERE OccurredAtUtc >= @s AND OccurredAtUtc < @e;";
cmd.Parameters.Add(new SqlParameter("@s", System.Data.SqlDbType.DateTime2) { Value = month }); cmd.Parameters.Add(new SqlParameter("@s", System.Data.SqlDbType.DateTime2) { Value = month });
cmd.Parameters.Add(new SqlParameter("@e", System.Data.SqlDbType.DateTime2) { Value = month.AddMonths(1) }); cmd.Parameters.Add(new SqlParameter("@e", System.Data.SqlDbType.DateTime2) { Value = month.AddMonths(1) });
var rows = new List<AuditChainRow>(); var rows = new List<AuditArchiveRow>();
await using var reader = await cmd.ExecuteReaderAsync(); await using var reader = await cmd.ExecuteReaderAsync();
while (await reader.ReadAsync()) while (await reader.ReadAsync())
{ {
rows.Add(AuditLogHashChain.ReadRow(reader, withLink: true)); rows.Add(AuditArchiveParquet.ReadRow(reader));
} }
return rows; return rows;
} }
private static string Key(AuditChainRow r) => string.Join('|', private static string Key(AuditArchiveRow r) => string.Join('|',
r.EventId, r.OccurredAtUtc.Ticks, r.Actor ?? "<null>", r.Action, r.Outcome, r.Category, r.Target ?? "<null>", r.EventId, r.OccurredAtUtc.Ticks, r.Actor ?? "<null>", r.Action, r.Outcome, r.Category, r.Target ?? "<null>",
r.SourceNode ?? "<null>", r.CorrelationId?.ToString() ?? "<null>", r.DetailsJson ?? "<null>", r.SourceNode ?? "<null>", r.CorrelationId?.ToString() ?? "<null>", r.DetailsJson ?? "<null>");
r.ChainSeq?.ToString() ?? "<null>", r.RowHash is null ? "<null>" : Convert.ToHexString(r.RowHash));
private async Task InsertAsync(IEnumerable<AuditEvent> events) private async Task InsertAsync(IEnumerable<AuditEvent> events)
{ {
@@ -387,22 +339,6 @@ public sealed class AuditLogPartitionArchiveTests : IClassFixture<MsSqlMigration
} }
} }
private async Task DrainAsync()
{
await using var ctx = CreateContext();
var chain = new AuditLogHashChain(ctx);
for (var i = 0; i < 1000; i++)
{
var r = await chain.ChainPendingAsync(500, chainBacklog: true);
if (r.RowsChained == 0 && !r.LockBusy)
{
return;
}
}
throw new InvalidOperationException("Chain did not drain.");
}
private ScadaBridgeDbContext CreateContext() private ScadaBridgeDbContext CreateContext()
=> new(new DbContextOptionsBuilder<ScadaBridgeDbContext>().UseSqlServer(_fixture.ConnectionString).Options); => new(new DbContextOptionsBuilder<ScadaBridgeDbContext>().UseSqlServer(_fixture.ConnectionString).Options);
@@ -1,249 +0,0 @@
using Microsoft.Data.SqlClient;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Options;
using ZB.MOM.WW.Audit;
using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums;
using ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance;
using ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Repositories;
using ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Tests.Migrations;
namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Tests.Maintenance;
/// <summary>
/// The hardened two-login setup (ScadaBridge#107 item 3), end to end on SQL Server: a writer
/// login (<c>db_datareader</c> + <c>db_datawriter</c> + <c>scadabridge_audit_writer</c>) and a
/// maintenance login (<c>scadabridge_audit_chainer</c> + <c>scadabridge_audit_purger</c> only),
/// wired through <c>AddConfigurationDatabase(writer, maintenance)</c>. The writer ingests but
/// cannot chain, update or delete; the maintenance services run on the maintenance login and
/// can chain, verify, export heads, per-channel purge, enumerate partitions, archive and switch.
/// </summary>
public sealed class AuditMaintenanceLoginTests : IClassFixture<MsSqlMigrationFixture>, IAsyncLifetime
{
private const string Password = "Sb_W22_maint#2026";
private readonly MsSqlMigrationFixture _fixture;
private readonly string _suffix = Guid.NewGuid().ToString("N")[..10];
private readonly DirectoryInfo _archiveDir = Directory.CreateTempSubdirectory("maint-login-archive-");
/// <summary>Creates the test class with its own migrated SQL Server database.</summary>
/// <param name="fixture">The per-class migration fixture.</param>
public AuditMaintenanceLoginTests(MsSqlMigrationFixture fixture) => _fixture = fixture;
private string WriterLogin => "sbw_" + _suffix;
private string MaintenanceLogin => "sbm_" + _suffix;
/// <inheritdoc />
public async Task InitializeAsync()
{
if (!_fixture.Available)
{
return;
}
await using var conn = _fixture.OpenConnection();
await using var cmd = new SqlCommand($@"
CREATE LOGIN [{WriterLogin}] WITH PASSWORD = N'{Password}', CHECK_POLICY = OFF;
CREATE LOGIN [{MaintenanceLogin}] WITH PASSWORD = N'{Password}', CHECK_POLICY = OFF;
CREATE USER [{WriterLogin}] FOR LOGIN [{WriterLogin}];
CREATE USER [{MaintenanceLogin}] FOR LOGIN [{MaintenanceLogin}];
ALTER ROLE db_datareader ADD MEMBER [{WriterLogin}];
ALTER ROLE db_datawriter ADD MEMBER [{WriterLogin}];
ALTER ROLE scadabridge_audit_writer ADD MEMBER [{WriterLogin}];
ALTER ROLE scadabridge_audit_chainer ADD MEMBER [{MaintenanceLogin}];
ALTER ROLE scadabridge_audit_purger ADD MEMBER [{MaintenanceLogin}];", conn);
await cmd.ExecuteNonQueryAsync();
}
/// <inheritdoc />
public async Task DisposeAsync()
{
_archiveDir.Delete(recursive: true);
if (!_fixture.Available)
{
return;
}
SqlConnection.ClearAllPools();
await using var conn = _fixture.OpenConnection();
await using var cmd = new SqlCommand($@"
DECLARE @kill nvarchar(max) = N'';
SELECT @kill = @kill + N'KILL ' + CAST(session_id AS nvarchar(10)) + N';' FROM sys.dm_exec_sessions
WHERE login_name IN (N'{WriterLogin}', N'{MaintenanceLogin}');
EXEC sp_executesql @kill;
IF USER_ID(N'{WriterLogin}') IS NOT NULL DROP USER [{WriterLogin}];
IF USER_ID(N'{MaintenanceLogin}') IS NOT NULL DROP USER [{MaintenanceLogin}];
IF SUSER_ID(N'{WriterLogin}') IS NOT NULL DROP LOGIN [{WriterLogin}];
IF SUSER_ID(N'{MaintenanceLogin}') IS NOT NULL DROP LOGIN [{MaintenanceLogin}];", conn);
await cmd.ExecuteNonQueryAsync();
}
/// <summary>
/// Writer ingests and is refused every maintenance write; the maintenance services, resolved
/// from DI on the separate login, do the whole chain + purge + archive cycle.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task HardenedTwoLoginSetup_WriterIngestsOnly_MaintenanceLoginRunsChainAndPurges()
{
Skip.IfNot(_fixture.Available, _fixture.SkipReason);
var writerCs = As(WriterLogin);
var maintenanceCs = As(MaintenanceLogin);
var month = new DateTime(2027, 2, 1, 0, 0, 0, DateTimeKind.Utc);
// The writer login ingests.
await using (var writerCtx = Context(writerCs))
{
var repo = new AuditLogRepository(writerCtx);
foreach (var i in Enumerable.Range(1, 4))
{
await repo.InsertIfNotExistsAsync(NewEvent(month.AddDays(i), AuditChannel.ApiOutbound));
}
await repo.InsertIfNotExistsAsync(NewEvent(month.AddHours(2), AuditChannel.DbOutbound));
}
// Negative controls: the writer login can neither chain nor delete.
await using (var writerCtx = Context(writerCs))
{
await Assert.ThrowsAsync<SqlException>(() => new AuditLogHashChain(writerCtx).ChainPendingAsync(100, chainBacklog: true));
await Assert.ThrowsAsync<SqlException>(() =>
new AuditLogRepository(writerCtx).PurgeChannelOlderThanAsync("DbOutbound", month.AddDays(1), 100));
}
var services = new ServiceCollection();
services.AddLogging();
services.AddConfigurationDatabase(writerCs, maintenanceCs);
services.AddSingleton(Options.Create(new AuditLogArchiveOptions
{
Enabled = true,
Directory = _archiveDir.FullName,
RowGroupSize = 1_000,
}));
await using var provider = services.BuildServiceProvider();
await using (var scope = provider.CreateAsyncScope())
{
var maintenance = scope.ServiceProvider.GetRequiredService<AuditMaintenanceContext>();
Assert.True(maintenance.UsesSeparateLogin);
Assert.Equal(MaintenanceLogin, await LoginNameAsync(maintenance.Context));
Assert.Equal(WriterLogin, await LoginNameAsync(scope.ServiceProvider.GetRequiredService<ScadaBridgeDbContext>()));
var chain = scope.ServiceProvider.GetRequiredService<IAuditLogHashChain>();
Assert.Equal(5, (await chain.ChainPendingAsync(100, chainBacklog: true)).RowsChained);
Assert.Equal(AuditChainStatus.Intact, (await chain.VerifyMonthAsync(month)).Status);
var head = Assert.Single(await scope.ServiceProvider.GetRequiredService<IAuditChainHeadStore>().ReadHeadsAsync());
Assert.Equal(5, head.LastSeq);
var repo = scope.ServiceProvider.GetRequiredKeyedService<IAuditLogRepository>(AuditMaintenanceContext.ServiceKey);
Assert.Equal(1, await repo.PurgeChannelOlderThanAsync("DbOutbound", month.AddDays(1), 100));
Assert.Contains(month, await repo.GetPartitionBoundariesOlderThanAsync(month.AddYears(5)));
var archive = scope.ServiceProvider.GetRequiredKeyedService<IAuditLogArchive>(AuditMaintenanceContext.ServiceKey);
var manifest = await archive.ArchivePartitionAsync(month);
Assert.Equal(4, manifest.RowCount);
Assert.Equal(4, await archive.PurgeArchivedPartitionAsync(manifest));
Assert.Equal(AuditChainStatus.Intact, (await chain.VerifyMonthAsync(month)).Status);
}
// Unset maintenance string: the maintenance context is the runtime context, as before.
var plain = new ServiceCollection();
plain.AddLogging();
plain.AddConfigurationDatabase(writerCs);
await using var plainProvider = plain.BuildServiceProvider();
await using var plainScope = plainProvider.CreateAsyncScope();
var shared = plainScope.ServiceProvider.GetRequiredService<AuditMaintenanceContext>();
Assert.False(shared.UsesSeparateLogin);
Assert.Same(plainScope.ServiceProvider.GetRequiredService<ScadaBridgeDbContext>(), shared.Context);
}
/// <summary>
/// ScadaBridge#113: the monthly roll-forward (<c>ALTER PARTITION FUNCTION … SPLIT RANGE</c>) and
/// the <c>SourceNode</c> backfill run on the maintenance login — and are refused to the writer
/// login — with only the role grants the <c>AuditMaintenanceGrants</c> migration provisions.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task RollForwardAndSourceNodeBackfill_RunOnTheMaintenanceLogin_NotTheWriter()
{
Skip.IfNot(_fixture.Available, _fixture.SkipReason);
var writerCs = As(WriterLogin);
var maintenanceCs = As(MaintenanceLogin);
var month = new DateTime(2027, 4, 1, 0, 0, 0, DateTimeKind.Utc);
// A pre-feature row: no SourceNode, not chained.
await using (var writerCtx = Context(writerCs))
{
var legacy = NewEvent(month.AddDays(1), AuditChannel.ApiOutbound) with { SourceNode = null };
await new AuditLogRepository(writerCtx).InsertIfNotExistsAsync(legacy);
}
// Negative controls: the writer login can neither split the partition function nor backfill.
await using (var writerCtx = Context(writerCs))
{
await Assert.ThrowsAsync<SqlException>(() => new AuditLogPartitionMaintenance(writerCtx).EnsureLookaheadAsync(60));
await Assert.ThrowsAsync<SqlException>(() =>
new AuditLogRepository(writerCtx).BackfillSourceNodeAsync("unknown", month.AddYears(1), 100));
}
var services = new ServiceCollection();
services.AddLogging();
services.AddConfigurationDatabase(writerCs, maintenanceCs);
await using var provider = services.BuildServiceProvider();
await using (var scope = provider.CreateAsyncScope())
{
var maintenance = scope.ServiceProvider.GetRequiredService<AuditMaintenanceContext>();
var roll = scope.ServiceProvider.GetRequiredService<ZB.MOM.WW.ScadaBridge.Commons.Interfaces.IPartitionMaintenance>();
var before = await roll.GetMaxBoundaryAsync();
var added = await roll.EnsureLookaheadAsync(60);
Assert.NotEmpty(added);
Assert.True(await roll.GetMaxBoundaryAsync() > before);
var repo = scope.ServiceProvider.GetRequiredKeyedService<IAuditLogRepository>(
ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories.AuditLogServiceKeys.Maintenance);
Assert.Equal(1, await repo.BackfillSourceNodeAsync("unknown", month.AddYears(1), 100));
Assert.Equal(MaintenanceLogin, await LoginNameAsync(maintenance.Context));
}
}
private string As(string login) => new SqlConnectionStringBuilder(_fixture.ConnectionString)
{
UserID = login,
Password = Password,
IntegratedSecurity = false,
}.ConnectionString;
private static ScadaBridgeDbContext Context(string cs)
=> new(new DbContextOptionsBuilder<ScadaBridgeDbContext>().UseSqlServer(cs).Options);
private static async Task<string> LoginNameAsync(ScadaBridgeDbContext ctx)
{
var conn = ctx.Database.GetDbConnection();
await conn.OpenAsync();
try
{
await using var cmd = conn.CreateCommand();
cmd.CommandText = "SELECT SUSER_SNAME();";
return (string)(await cmd.ExecuteScalarAsync())!;
}
finally
{
await conn.CloseAsync();
}
}
private static AuditEvent NewEvent(DateTime occurredAtUtc, AuditChannel channel) =>
ScadaBridgeAuditEventFactory.Create(
channel: channel,
kind: channel == AuditChannel.DbOutbound ? AuditKind.DbWrite : AuditKind.ApiCall,
status: AuditStatus.Delivered,
occurredAtUtc: occurredAtUtc,
actor: "maint-login-test",
target: "erp",
sourceNode: "central-a",
sourceSiteId: "maint-login-test",
correlationId: Guid.NewGuid());
}
@@ -29,14 +29,18 @@ public sealed class FlipAuditLogClusteredKeyMigrationTests : IClassFixture<MsSql
// The migration immediately before the flip, so "Down" reverts exactly this one. // The migration immediately before the flip, so "Down" reverts exactly this one.
private static readonly string PreviousMigration = MigrationBefore(FlipMigration); private static readonly string PreviousMigration = MigrationBefore(FlipMigration);
// The ten non-clustered indexes at head. RemoveAuditLogHashChain (2026-11-15, after the
// flip) dropped the two hash-chain indexes; one migration before the flip they still exist.
private static readonly string[] NonClusteredIndexes = private static readonly string[] NonClusteredIndexes =
[ [
"IX_AuditLog_OccurredAtUtc", "IX_AuditLog_Site_Occurred", "IX_AuditLog_CorrelationId", "IX_AuditLog_OccurredAtUtc", "IX_AuditLog_Site_Occurred", "IX_AuditLog_CorrelationId",
"IX_AuditLog_Channel_Status_Occurred", "IX_AuditLog_Target_Occurred", "IX_AuditLog_Execution", "IX_AuditLog_Channel_Status_Occurred", "IX_AuditLog_Target_Occurred", "IX_AuditLog_Execution",
"IX_AuditLog_ParentExecution", "IX_AuditLog_Node_Occurred", "IX_AuditLog_Kind_Occurred", "IX_AuditLog_ParentExecution", "IX_AuditLog_Node_Occurred", "IX_AuditLog_Kind_Occurred",
"IX_AuditLog_Actor_Occurred", "IX_AuditLog_Unchained", "IX_AuditLog_ChainSeq", "IX_AuditLog_Actor_Occurred",
]; ];
private static readonly string[] ChainIndexes = ["IX_AuditLog_Unchained", "IX_AuditLog_ChainSeq"];
private readonly MsSqlMigrationFixture _fixture; private readonly MsSqlMigrationFixture _fixture;
private readonly ITestOutputHelper _output; private readonly ITestOutputHelper _output;
@@ -50,9 +54,10 @@ public sealed class FlipAuditLogClusteredKeyMigrationTests : IClassFixture<MsSql
} }
/// <summary> /// <summary>
/// After the full chain: clustered PK (OccurredAtUtc, EventId), the unique aligned /// After the full migration chain: clustered PK (OccurredAtUtc, EventId), the unique aligned
/// (EventId, OccurredAtUtc) index, all twelve non-clustered indexes with unchanged keys and /// (EventId, OccurredAtUtc) index, the ten non-clustered indexes with unchanged keys and
/// filters, everything on ps_AuditLog_Month, and every append-only/chain grant intact. /// filters (the two hash-chain indexes gone), everything on ps_AuditLog_Month, and every
/// append-only grant intact.
/// </summary> /// </summary>
/// <returns>A task that represents the asynchronous operation.</returns> /// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact] [SkippableFact]
@@ -67,7 +72,7 @@ public sealed class FlipAuditLogClusteredKeyMigrationTests : IClassFixture<MsSql
Assert.True(indexes["UX_AuditLog_EventId_Occurred"].Unique); Assert.True(indexes["UX_AuditLog_EventId_Occurred"].Unique);
Assert.Equal(NonClusteredIndexes.Length + 2, indexes.Count); Assert.Equal(NonClusteredIndexes.Length + 2, indexes.Count);
Assert.All(indexes.Values, i => Assert.Equal("ps_AuditLog_Month", i.DataSpace)); Assert.All(indexes.Values, i => Assert.Equal("ps_AuditLog_Month", i.DataSpace));
AssertTwelveNonClusteredIndexes(indexes); AssertNonClusteredIndexes(indexes, withChainIndexes: false);
Assert.Equal(ExpectedGrants, await ReadGrantsAsync()); Assert.Equal(ExpectedGrants, await ReadGrantsAsync());
} }
@@ -86,14 +91,16 @@ public sealed class FlipAuditLogClusteredKeyMigrationTests : IClassFixture<MsSql
var down = await ReadIndexesAsync(); var down = await ReadIndexesAsync();
Assert.Equal("EventId, OccurredAtUtc", down["PK_AuditLog"].Keys); Assert.Equal("EventId, OccurredAtUtc", down["PK_AuditLog"].Keys);
Assert.False(down.ContainsKey("UX_AuditLog_EventId_Occurred")); Assert.False(down.ContainsKey("UX_AuditLog_EventId_Occurred"));
AssertTwelveNonClusteredIndexes(down); AssertNonClusteredIndexes(down, withChainIndexes: true);
Assert.Equal(GrantsBeforeMaintenanceGrants, await ReadGrantsAsync()); Assert.Equal(GrantsBeforeTheFlip, await ReadGrantsAsync());
// Old shape: the purge's staging table must take the old key order. // Old shape: the purge's staging table must take the old key order — and, since this is
// also before RemoveAuditLogHashChain, carry the two chain columns the live table still has.
await AssertSwitchOutPurgesAsync(new DateTime(2027, 3, 1, 0, 0, 0, DateTimeKind.Utc)); await AssertSwitchOutPurgesAsync(new DateTime(2027, 3, 1, 0, 0, 0, DateTimeKind.Utc));
// Back to head (not just to the flip): migrations after it — AuditMaintenanceGrants — // Back to head (not just to the flip): migrations after it — AuditMaintenanceGrants,
// were reverted by the Down too, and the class leaves the database fully migrated. // RemoveAuditLogHashChain — were reverted by the Down too, and the class leaves the
// database fully migrated.
await MigrateToHeadAsync(); await MigrateToHeadAsync();
var up = await ReadIndexesAsync(); var up = await ReadIndexesAsync();
Assert.Equal("OccurredAtUtc, EventId", up["PK_AuditLog"].Keys); Assert.Equal("OccurredAtUtc, EventId", up["PK_AuditLog"].Keys);
@@ -146,26 +153,29 @@ public sealed class FlipAuditLogClusteredKeyMigrationTests : IClassFixture<MsSql
} }
} }
// At head: RemoveAuditLogHashChain dropped the chainer role and revoked the purger's
// AuditMaintenanceGrants column grant.
private static readonly string[] ExpectedGrants = private static readonly string[] ExpectedGrants =
[ [
"scadabridge_audit_chainer|SELECT|GRANT|",
"scadabridge_audit_chainer|UPDATE|GRANT|ChainSeq",
"scadabridge_audit_chainer|UPDATE|GRANT|RowHash",
"scadabridge_audit_purger|DELETE|GRANT|", "scadabridge_audit_purger|DELETE|GRANT|",
"scadabridge_audit_purger|SELECT|GRANT|", "scadabridge_audit_purger|SELECT|GRANT|",
// AuditMaintenanceGrants (migration 64, after the flip) — the archive path's column grant.
"scadabridge_audit_purger|UPDATE|GRANT|SourceNode",
"scadabridge_audit_writer|DELETE|DENY|", "scadabridge_audit_writer|DELETE|DENY|",
"scadabridge_audit_writer|INSERT|GRANT|", "scadabridge_audit_writer|INSERT|GRANT|",
"scadabridge_audit_writer|SELECT|GRANT|", "scadabridge_audit_writer|SELECT|GRANT|",
"scadabridge_audit_writer|UPDATE|DENY|", "scadabridge_audit_writer|UPDATE|DENY|",
]; ];
// The grants one migration before the flip: AuditMaintenanceGrants is not applied yet. // One migration before the flip: the hash chain's chainer grants exist (AddAuditLogHashChain)
private static readonly string[] GrantsBeforeMaintenanceGrants = // and AuditMaintenanceGrants is not applied yet.
ExpectedGrants.Where(g => !g.EndsWith("|SourceNode", StringComparison.Ordinal)).ToArray(); private static readonly string[] GrantsBeforeTheFlip =
ExpectedGrants.Concat(
[
"scadabridge_audit_chainer|SELECT|GRANT|",
"scadabridge_audit_chainer|UPDATE|GRANT|ChainSeq",
"scadabridge_audit_chainer|UPDATE|GRANT|RowHash",
]).Order(StringComparer.Ordinal).ToArray();
private static void AssertTwelveNonClusteredIndexes(IReadOnlyDictionary<string, IndexShape> indexes) private static void AssertNonClusteredIndexes(IReadOnlyDictionary<string, IndexShape> indexes, bool withChainIndexes)
{ {
Assert.Equal("OccurredAtUtc DESC", indexes["IX_AuditLog_OccurredAtUtc"].Keys); Assert.Equal("OccurredAtUtc DESC", indexes["IX_AuditLog_OccurredAtUtc"].Keys);
Assert.Equal("Status", indexes["IX_AuditLog_OccurredAtUtc"].Included); Assert.Equal("Status", indexes["IX_AuditLog_OccurredAtUtc"].Included);
@@ -180,11 +190,18 @@ public sealed class FlipAuditLogClusteredKeyMigrationTests : IClassFixture<MsSql
Assert.Equal("SourceNode, OccurredAtUtc", indexes["IX_AuditLog_Node_Occurred"].Keys); Assert.Equal("SourceNode, OccurredAtUtc", indexes["IX_AuditLog_Node_Occurred"].Keys);
Assert.Equal("Kind, OccurredAtUtc DESC", indexes["IX_AuditLog_Kind_Occurred"].Keys); Assert.Equal("Kind, OccurredAtUtc DESC", indexes["IX_AuditLog_Kind_Occurred"].Keys);
Assert.Equal("Actor, OccurredAtUtc DESC", indexes["IX_AuditLog_Actor_Occurred"].Keys); Assert.Equal("Actor, OccurredAtUtc DESC", indexes["IX_AuditLog_Actor_Occurred"].Keys);
Assert.Equal("OccurredAtUtc, EventId", indexes["IX_AuditLog_Unchained"].Keys);
Assert.Equal("([ChainSeq] IS NULL)", indexes["IX_AuditLog_Unchained"].Filter);
Assert.Equal("ChainSeq", indexes["IX_AuditLog_ChainSeq"].Keys);
Assert.Equal("([ChainSeq] IS NOT NULL)", indexes["IX_AuditLog_ChainSeq"].Filter);
Assert.All(NonClusteredIndexes, n => Assert.False(indexes[n].Clustered, n)); Assert.All(NonClusteredIndexes, n => Assert.False(indexes[n].Clustered, n));
if (withChainIndexes)
{
Assert.Equal("OccurredAtUtc, EventId", indexes["IX_AuditLog_Unchained"].Keys);
Assert.Equal("([ChainSeq] IS NULL)", indexes["IX_AuditLog_Unchained"].Filter);
Assert.Equal("ChainSeq", indexes["IX_AuditLog_ChainSeq"].Keys);
Assert.Equal("([ChainSeq] IS NOT NULL)", indexes["IX_AuditLog_ChainSeq"].Filter);
}
else
{
Assert.All(ChainIndexes, n => Assert.False(indexes.ContainsKey(n), n));
}
} }
private async Task AssertSwitchOutPurgesAsync(DateTime month) private async Task AssertSwitchOutPurgesAsync(DateTime month)
@@ -60,7 +60,8 @@ public sealed class IdempotentMigrationScriptTests : IClassFixture<MsSqlMigratio
await RunScriptAsync(script); await RunScriptAsync(script);
Assert.Equal(all, await ReadHistoryAsync()); Assert.Equal(all, await ReadHistoryAsync());
Assert.Equal(2, await CountChainIndexesAsync()); // AddAuditLogHashChain created the two chain indexes, RemoveAuditLogHashChain dropped them.
Assert.Equal(0, await CountChainIndexesAsync());
// Second run against the fully-migrated database: every guard is false. // Second run against the fully-migrated database: every guard is false.
await RunScriptAsync(script); await RunScriptAsync(script);
@@ -0,0 +1,167 @@
using Microsoft.Data.SqlClient;
using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.Infrastructure;
using Microsoft.EntityFrameworkCore.Migrations;
using Microsoft.EntityFrameworkCore.Migrations.Operations;
using ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Migrations;
namespace ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Tests.Migrations;
/// <summary>
/// SQL Server tests for the <c>RemoveAuditLogHashChain</c> migration (2026-11-15): at head the
/// hash-chain columns, tables, indexes and chainer role are gone and the purger keeps only its
/// original grants; Down restores what <c>AddAuditLogHashChain</c> + <c>AuditMaintenanceGrants</c>
/// created; and Up is re-runnable and drops a chainer role that still has members.
/// </summary>
/// <remarks>
/// The tests in this class migrate the fixture database down and back up, so they own their
/// fixture (one database per test class) and every test leaves the database fully migrated.
/// </remarks>
public sealed class RemoveAuditLogHashChainMigrationTests : IClassFixture<MsSqlMigrationFixture>
{
private const string RemoveMigration = "20261115221558_RemoveAuditLogHashChain";
private static readonly string PreviousMigration = MigrationBefore(RemoveMigration);
private readonly MsSqlMigrationFixture _fixture;
/// <summary>Creates the test class with its own migrated SQL Server database.</summary>
/// <param name="fixture">The per-class migration fixture.</param>
public RemoveAuditLogHashChainMigrationTests(MsSqlMigrationFixture fixture) => _fixture = fixture;
/// <summary>At head nothing of the hash chain or the maintenance grants is left.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task AtHead_TheChainSchema_AndTheMaintenanceGrants_AreGone()
{
Skip.IfNot(_fixture.Available, _fixture.SkipReason);
await AssertRemovedAsync();
}
/// <summary>
/// Down restores the chain schema exactly (columns, tables, indexes, chainer role and grants,
/// the purger's maintenance grants); Up then drops it again, also when the chainer role has a
/// member; and re-running Up's SQL on the migrated schema changes nothing.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[SkippableFact]
public async Task DownUp_RoundTrips_DropsAChainerRoleWithMembers_AndIsReRunnable()
{
Skip.IfNot(_fixture.Available, _fixture.SkipReason);
await MigrateToAsync(PreviousMigration);
try
{
Assert.True(await ScalarAsync<int>("SELECT CASE WHEN COL_LENGTH('dbo.AuditLog','ChainSeq') IS NULL THEN 0 ELSE 1 END;") == 1);
Assert.True(await ScalarAsync<int>("SELECT CASE WHEN COL_LENGTH('dbo.AuditLog','RowHash') IS NULL THEN 0 ELSE 1 END;") == 1);
Assert.True(await ScalarAsync<int>("SELECT CASE WHEN OBJECT_ID('dbo.AuditLogChainHead','U') IS NULL THEN 0 ELSE 1 END;") == 1);
Assert.True(await ScalarAsync<int>("SELECT CASE WHEN OBJECT_ID('dbo.AuditLogChainTombstone','U') IS NULL THEN 0 ELSE 1 END;") == 1);
Assert.Equal(2, await ScalarAsync<int>(
"SELECT COUNT(*) FROM sys.indexes WHERE object_id = OBJECT_ID('dbo.AuditLog') AND name IN ('IX_AuditLog_Unchained','IX_AuditLog_ChainSeq');"));
Assert.Contains("scadabridge_audit_chainer|UPDATE|GRANT|ChainSeq", await ReadAuditLogGrantsAsync());
Assert.Contains("scadabridge_audit_purger|UPDATE|GRANT|SourceNode", await ReadAuditLogGrantsAsync());
Assert.Equal(1, await ScalarAsync<int>(
"SELECT COUNT(*) FROM sys.database_permissions p JOIN sys.database_principals pr ON pr.principal_id = p.grantee_principal_id "
+ "WHERE pr.name = 'scadabridge_audit_purger' AND p.class = 0 AND p.permission_name = 'ALTER ANY DATASPACE' AND p.state_desc = 'GRANT';"));
// A login was put in the chainer role (the hardened two-login setup): Up must still drop the role.
await ExecAsync("IF DATABASE_PRINCIPAL_ID('rm_chain_test_user') IS NULL CREATE USER rm_chain_test_user WITHOUT LOGIN;"
+ "ALTER ROLE scadabridge_audit_chainer ADD MEMBER rm_chain_test_user;");
}
finally
{
await MigrateToHeadAsync();
}
await AssertRemovedAsync();
Assert.Equal(1, await ScalarAsync<int>("SELECT CASE WHEN DATABASE_PRINCIPAL_ID('rm_chain_test_user') IS NULL THEN 0 ELSE 1 END;"));
// Re-run Up's SQL against the migrated schema: every statement is guarded.
foreach (var op in new RemoveAuditLogHashChain().UpOperations.OfType<SqlOperation>())
{
await ExecAsync(op.Sql);
}
await AssertRemovedAsync();
}
private async Task AssertRemovedAsync()
{
Assert.Equal(0, await ScalarAsync<int>("SELECT CASE WHEN COL_LENGTH('dbo.AuditLog','ChainSeq') IS NULL THEN 0 ELSE 1 END;"));
Assert.Equal(0, await ScalarAsync<int>("SELECT CASE WHEN COL_LENGTH('dbo.AuditLog','RowHash') IS NULL THEN 0 ELSE 1 END;"));
Assert.Equal(0, await ScalarAsync<int>("SELECT CASE WHEN OBJECT_ID('dbo.AuditLogChainHead','U') IS NULL THEN 0 ELSE 1 END;"));
Assert.Equal(0, await ScalarAsync<int>("SELECT CASE WHEN OBJECT_ID('dbo.AuditLogChainTombstone','U') IS NULL THEN 0 ELSE 1 END;"));
Assert.Equal(0, await ScalarAsync<int>(
"SELECT COUNT(*) FROM sys.indexes WHERE object_id = OBJECT_ID('dbo.AuditLog') AND name IN ('IX_AuditLog_Unchained','IX_AuditLog_ChainSeq');"));
Assert.Equal(0, await ScalarAsync<int>("SELECT CASE WHEN DATABASE_PRINCIPAL_ID('scadabridge_audit_chainer') IS NULL THEN 0 ELSE 1 END;"));
Assert.Equal(0, await ScalarAsync<int>(
"SELECT COUNT(*) FROM sys.database_permissions p JOIN sys.database_principals pr ON pr.principal_id = p.grantee_principal_id "
+ "WHERE pr.name = 'scadabridge_audit_purger' AND p.class = 0 AND p.permission_name = 'ALTER ANY DATASPACE';"));
// The roles that predate the chain stay, with exactly their original AuditLog grants.
Assert.Equal(
new[]
{
"scadabridge_audit_purger|DELETE|GRANT|",
"scadabridge_audit_purger|SELECT|GRANT|",
"scadabridge_audit_writer|DELETE|DENY|",
"scadabridge_audit_writer|INSERT|GRANT|",
"scadabridge_audit_writer|SELECT|GRANT|",
"scadabridge_audit_writer|UPDATE|DENY|",
},
await ReadAuditLogGrantsAsync());
}
private async Task<T> ScalarAsync<T>(string sql)
{
await using var conn = _fixture.OpenConnection();
await using var cmd = new SqlCommand(sql, conn);
return (T)Convert.ChangeType((await cmd.ExecuteScalarAsync())!, typeof(T), System.Globalization.CultureInfo.InvariantCulture);
}
private async Task ExecAsync(string sql)
{
await using var conn = _fixture.OpenConnection();
await using var cmd = new SqlCommand(sql, conn) { CommandTimeout = 300 };
await cmd.ExecuteNonQueryAsync();
}
private async Task<string[]> ReadAuditLogGrantsAsync()
{
await using var conn = _fixture.OpenConnection();
await using var cmd = new SqlCommand(@"
SELECT pr.name, p.permission_name, p.state_desc, COL_NAME(p.major_id, p.minor_id)
FROM sys.database_permissions p JOIN sys.database_principals pr ON pr.principal_id = p.grantee_principal_id
WHERE p.major_id = OBJECT_ID('dbo.AuditLog') AND p.class = 1;", conn);
var list = new List<string>();
await using var reader = await cmd.ExecuteReaderAsync();
while (await reader.ReadAsync())
{
list.Add($"{reader.GetString(0)}|{reader.GetString(1)}|{reader.GetString(2)}|{(reader.IsDBNull(3) ? "" : reader.GetString(3))}");
}
return list.Order(StringComparer.Ordinal).ToArray();
}
private async Task MigrateToAsync(string migration)
{
await using var ctx = new ScadaBridgeDbContext(new DbContextOptionsBuilder<ScadaBridgeDbContext>()
.UseSqlServer(_fixture.ConnectionString, sql => sql.CommandTimeout(600)).Options);
await ctx.GetService<IMigrator>().MigrateAsync(migration);
}
private async Task MigrateToHeadAsync()
{
await using var ctx = new ScadaBridgeDbContext(new DbContextOptionsBuilder<ScadaBridgeDbContext>()
.UseSqlServer(_fixture.ConnectionString, sql => sql.CommandTimeout(600)).Options);
await ctx.GetService<IMigrator>().MigrateAsync();
}
private static string MigrationBefore(string migration)
{
using var ctx = new ScadaBridgeDbContext(new DbContextOptionsBuilder<ScadaBridgeDbContext>()
.UseSqlServer("Server=unused;Database=unused").Options);
var all = ctx.Database.GetMigrations().ToList();
return all[all.IndexOf(migration) - 1];
}
}
@@ -1,45 +0,0 @@
using Microsoft.Extensions.Diagnostics.HealthChecks;
using ZB.MOM.WW.ScadaBridge.AuditLog.Central.HeadExport;
using ZB.MOM.WW.ScadaBridge.Host.Health;
namespace ZB.MOM.WW.ScadaBridge.Host.Tests;
/// <summary>ScadaBridge#115: the chain-head export readiness entry.</summary>
public sealed class AuditChainHeadExportHealthCheckTests
{
private sealed class Clock(DateTime now) : TimeProvider
{
public DateTime Now { get; set; } = now;
public override DateTimeOffset GetUtcNow() => new(DateTime.SpecifyKind(Now, DateTimeKind.Utc));
}
private static readonly DateTime T0 = new(2026, 11, 10, 12, 0, 0, DateTimeKind.Utc);
private static async Task<HealthStatus> Check(AuditChainHeadExportStatus s, Clock c)
=> (await new AuditChainHeadExportHealthCheck(s, c).CheckHealthAsync(new HealthCheckContext())).Status;
/// <summary>Disabled export is healthy; failing or stale export is Degraded; recovery clears it.</summary>
[Fact]
public async Task Status_follows_export_outcome()
{
var clock = new Clock(T0);
var status = new AuditChainHeadExportStatus();
Assert.Equal(HealthStatus.Healthy, await Check(status, clock)); // disabled
status.MarkStarted(60, T0);
Assert.Equal(HealthStatus.Healthy, await Check(status, clock));
status.RecordFailure(T0, "share offline");
var result = await new AuditChainHeadExportHealthCheck(status, clock).CheckHealthAsync(new HealthCheckContext());
Assert.Equal(HealthStatus.Degraded, result.Status);
Assert.Contains("share offline", result.Description);
status.RecordSuccess(T0);
Assert.Equal(HealthStatus.Healthy, await Check(status, clock));
clock.Now = T0.AddMinutes(121); // no success for > 2 intervals
Assert.Equal(HealthStatus.Degraded, await Check(status, clock));
status.RecordSuccess(clock.Now);
Assert.Equal(HealthStatus.Healthy, await Check(status, clock));
}
}
@@ -44,11 +44,10 @@ public class AuditArchiveCommandTests : TestKit
new(new AuthenticatedUser("u", "U", roles, sites), command, Guid.NewGuid().ToString("N")); new(new AuthenticatedUser("u", "U", roles, sites), command, Guid.NewGuid().ToString("N"));
private static AuditArchiveManifest Manifest() => new( private static AuditArchiveManifest Manifest() => new(
1, Name, new DateTime(2025, 10, 1, 0, 0, 0, DateTimeKind.Utc), "2025-10", 2, Name, new DateTime(2025, 10, 1, 0, 0, 0, DateTimeKind.Utc), "2025-10",
new DateTime(2026, 11, 9, 12, 0, 0, DateTimeKind.Utc), AuditArchiveStatus.Purged, new DateTime(2026, 11, 9, 12, 0, 0, DateTimeKind.Utc), AuditArchiveStatus.Purged,
new DateTime(2026, 11, 9, 12, 0, 1, DateTimeKind.Utc), 10, 9, 1, null, null, new DateTime(2026, 11, 9, 12, 0, 1, DateTimeKind.Utc), 10, null, null,
Name + ".parquet", "ab", 1234, Name + ".tombstones.parquet", "cd", 0, Name + ".parquet", "ab", 1234);
[new AuditArchiveChainState("2025-10", 9, new string('0', 64), null, null, 0)]);
/// <summary>A Viewer lists the archives; status renders as a name.</summary> /// <summary>A Viewer lists the archives; status renders as a name.</summary>
[Fact] [Fact]
@@ -66,23 +65,21 @@ public class AuditArchiveCommandTests : TestKit
Assert.Equal("Purged", archive.GetProperty("status").GetString()); Assert.Equal("Purged", archive.GetProperty("status").GetString());
} }
/// <summary>Verification results reach the wire with the anchor and chain status as names.</summary> /// <summary>Verification results reach the wire, status as a name.</summary>
[Fact] [Fact]
public void Viewer_GetsVerificationResult() public void Viewer_GetsVerificationResult()
{ {
var chain = new AuditChainVerificationResult("2025-10", AuditChainStatus.Intact, 9, 0, null, 9, 1, null);
_archive.VerifyAsync(Name, Arg.Any<CancellationToken>()).Returns(new AuditArchiveVerificationResult( _archive.VerifyAsync(Name, Arg.Any<CancellationToken>()).Returns(new AuditArchiveVerificationResult(
Name, "2025-10", AuditArchiveStatus.Purged, true, true, null, 10, Name, "2025-10", AuditArchiveStatus.Purged, true, true, null, 10));
[new AuditArchiveChainVerification(chain, AuditArchiveAnchorStatus.Matches, "ends at the anchor")]));
CreateActor().Tell(Envelope(new VerifyAuditArchiveCommand(Name), [], "Viewer")); CreateActor().Tell(Envelope(new VerifyAuditArchiveCommand(Name), [], "Viewer"));
var response = ExpectMsg<ManagementSuccess>(TimeSpan.FromSeconds(5)); var response = ExpectMsg<ManagementSuccess>(TimeSpan.FromSeconds(5));
using var json = JsonDocument.Parse(response.JsonData); using var json = JsonDocument.Parse(response.JsonData);
Assert.True(json.RootElement.GetProperty("verified").GetBoolean()); Assert.True(json.RootElement.GetProperty("verified").GetBoolean());
var c = json.RootElement.GetProperty("chains")[0]; Assert.Equal("Purged", json.RootElement.GetProperty("manifestStatus").GetString());
Assert.Equal("Matches", c.GetProperty("anchor").GetString()); Assert.Equal(10, json.RootElement.GetProperty("rowsRead").GetInt64());
Assert.Equal("Intact", c.GetProperty("chain").GetProperty("status").GetString()); Assert.False(json.RootElement.TryGetProperty("chains", out _));
} }
/// <summary>Designer/Deployer without an OperationalAudit role are refused both commands.</summary> /// <summary>Designer/Deployer without an OperationalAudit role are refused both commands.</summary>
@@ -168,12 +168,8 @@ public class RequiredRoleMatrixTests
["FlowDebugReplay"] = FlowDebuggerReplayers, ["FlowDebugReplay"] = FlowDebuggerReplayers,
// ---- Audit reads (OperationalAudit) ----------------------------------------- // ---- Audit reads (OperationalAudit) -----------------------------------------
// AuditLog hash-chain verification (ScadaBridge#41) carries audit query's // AuditLog Parquet archives (ScadaBridge#42) carry audit query's OperationalAudit
// OperationalAudit permission (alog.md §15.1); written out by hand to keep the freeze. // permission (alog.md §15.1); written out by hand to keep the freeze.
["VerifyAuditChain"] = [Roles.Administrator, Roles.Viewer],
// Off-box exported chain heads (ScadaBridge#107): same audit-read gate.
["VerifyAuditChainHeads"] = [Roles.Administrator, Roles.Viewer],
// AuditLog Parquet archives (ScadaBridge#42): same audit-read gate as verify-chain.
["ListAuditArchives"] = [Roles.Administrator, Roles.Viewer], ["ListAuditArchives"] = [Roles.Administrator, Roles.Viewer],
["VerifyAuditArchive"] = [Roles.Administrator, Roles.Viewer], ["VerifyAuditArchive"] = [Roles.Administrator, Roles.Viewer],
// Archive cleanup deletes files (ScadaBridge#109): Administrator only. // Archive cleanup deletes files (ScadaBridge#109): Administrator only.
@@ -1,125 +0,0 @@
using System.Text.Json;
using Akka.Actor;
using Akka.TestKit.Xunit2;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging.Abstractions;
using NSubstitute;
using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories;
using ZB.MOM.WW.ScadaBridge.Commons.Messages.Management;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
namespace ZB.MOM.WW.ScadaBridge.ManagementService.Tests;
/// <summary>
/// The <c>VerifyAuditChain</c> management command (ScadaBridge#41): role gate, month
/// parsing, site-scope refusal, and the verification result reaching the wire with its
/// enums as names.
/// </summary>
public class VerifyAuditChainCommandTests : TestKit
{
private readonly IAuditLogHashChain _chain = Substitute.For<IAuditLogHashChain>();
private IActorRef CreateActor()
{
var services = new ServiceCollection().AddTestConfigurationTransaction();
services.AddScoped(_ => _chain);
return Sys.ActorOf(Props.Create(() => new ManagementActor(
services.BuildServiceProvider(), NullLogger<ManagementActor>.Instance)));
}
private static ManagementEnvelope Envelope(object command, string[] sites, params string[] roles) =>
new(new AuthenticatedUser("u", "U", roles, sites), command, Guid.NewGuid().ToString("N"));
/// <summary>A Viewer gets the verifier's result for the requested month, enums as names.</summary>
[Fact]
public void Viewer_GetsVerificationResult_ForTheRequestedMonth()
{
var brk = new AuditChainBreak("2026-05", 7, Guid.Parse("11111111-2222-3333-4444-555555555555"),
AuditChainBreakKind.HashMismatch, "edited");
_chain.VerifyMonthAsync(Arg.Any<DateTime>(), Arg.Any<CancellationToken>())
.Returns(new AuditChainVerificationResult("2026-05", AuditChainStatus.Broken, 6, 0, null, 43, 2, brk));
CreateActor().Tell(Envelope(new VerifyAuditChainCommand("2026-05"), [], "Viewer"));
var response = ExpectMsg<ManagementSuccess>(TimeSpan.FromSeconds(5));
using var json = JsonDocument.Parse(response.JsonData);
Assert.Equal("Broken", json.RootElement.GetProperty("status").GetString());
Assert.Equal("HashMismatch", json.RootElement.GetProperty("firstBreak").GetProperty("kind").GetString());
Assert.Equal(7, json.RootElement.GetProperty("firstBreak").GetProperty("chainSeq").GetInt64());
_chain.Received(1).VerifyMonthAsync(
new DateTime(2026, 5, 1, 0, 0, 0, DateTimeKind.Utc), Arg.Any<CancellationToken>());
}
/// <summary>
/// ScadaBridge#139: the cutoff, the pre-cutoff row count and the new break kinds reach the
/// wire (the CLI renders them; the kinds as names like every other kind).
/// </summary>
[Fact]
public void CutoffFields_AndCutoffBreakKind_ReachTheWire()
{
var chainFrom = new DateTime(2026, 11, 13, 9, 30, 0, DateTimeKind.Utc);
var brk = new AuditChainBreak("2026-11", 4, Guid.NewGuid(), AuditChainBreakKind.ChainedBeforeCutoff, "moved back");
_chain.VerifyMonthAsync(Arg.Any<DateTime>(), Arg.Any<CancellationToken>())
.Returns(new AuditChainVerificationResult("2026-11", AuditChainStatus.Broken, 3, 0, null, 9, 0, brk, 3441, chainFrom));
CreateActor().Tell(Envelope(new VerifyAuditChainCommand("2026-11"), [], "Viewer"));
var response = ExpectMsg<ManagementSuccess>(TimeSpan.FromSeconds(5));
using var json = JsonDocument.Parse(response.JsonData);
Assert.Equal(3441, json.RootElement.GetProperty("preCutoffRows").GetInt64());
Assert.Equal(chainFrom, json.RootElement.GetProperty("chainFromUtc").GetDateTime().ToUniversalTime());
Assert.Equal("ChainedBeforeCutoff", json.RootElement.GetProperty("firstBreak").GetProperty("kind").GetString());
}
/// <summary>A Designer/Deployer without an OperationalAudit role is refused.</summary>
[Fact]
public void NonAuditRole_IsUnauthorized()
{
CreateActor().Tell(Envelope(new VerifyAuditChainCommand("2026-05"), [], "Designer", "Deployer"));
ExpectMsg<ManagementUnauthorized>(TimeSpan.FromSeconds(5));
_chain.DidNotReceiveWithAnyArgs().VerifyMonthAsync(default, default);
}
/// <summary>A site-scoped Viewer is refused: the chain spans every site.</summary>
[Fact]
public void SiteScopedViewer_IsRefused()
{
CreateActor().Tell(Envelope(new VerifyAuditChainCommand("2026-05"), ["3"], "Viewer"));
var response = ExpectMsg<ManagementUnauthorized>(TimeSpan.FromSeconds(5));
Assert.Contains("spans every site", response.Message);
_chain.DidNotReceiveWithAnyArgs().VerifyMonthAsync(default, default);
}
/// <summary>A malformed month is a caller error, not an internal fault.</summary>
[Fact]
public void MalformedMonth_IsInvalidArgument()
{
CreateActor().Tell(Envelope(new VerifyAuditChainCommand("2026-13"), [], "Administrator"));
var response = ExpectMsg<ManagementError>(TimeSpan.FromSeconds(5));
Assert.Equal("INVALID_ARGUMENT", response.ErrorCode);
}
/// <summary>A verification that cannot get the chain lock surfaces as CHAIN_BUSY.</summary>
[Fact]
public void BusyChain_IsChainBusy()
{
_chain.VerifyMonthAsync(Arg.Any<DateTime>(), Arg.Any<CancellationToken>())
.Returns<Task<AuditChainVerificationResult>>(_ => throw new TimeoutException("busy"));
CreateActor().Tell(Envelope(new VerifyAuditChainCommand("2026-05"), [], "Administrator"));
var response = ExpectMsg<ManagementError>(TimeSpan.FromSeconds(5));
Assert.Equal("CHAIN_BUSY", response.ErrorCode);
}
/// <summary>Verification runs under the long-running Ask timeout, not the 30 s default.</summary>
[Fact]
public void VerifyAuditChain_UsesLongRunningAskTimeout()
{
Assert.Equal(TimeSpan.FromMinutes(5),
ManagementEndpoints.ResolveAskTimeout(new ManagementServiceOptions(), typeof(VerifyAuditChainCommand)));
}
}
@@ -1,110 +0,0 @@
using System.Text.Json;
using Akka.Actor;
using Akka.TestKit.Xunit2;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging.Abstractions;
using NSubstitute;
using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Repositories;
using ZB.MOM.WW.ScadaBridge.Commons.Messages.Management;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Audit;
namespace ZB.MOM.WW.ScadaBridge.ManagementService.Tests;
/// <summary>
/// The <c>VerifyAuditChainHeads</c> management command (ScadaBridge#107 item 1): role gate,
/// site-scope refusal, input bounds, and the verdicts reaching the wire with enums as names.
/// </summary>
public class VerifyAuditChainHeadsCommandTests : TestKit
{
private readonly IAuditChainHeadStore _store = Substitute.For<IAuditChainHeadStore>();
private static readonly AuditChainHeadRecord Record = new(
1, "2026-05", 12, new string('a', 64), null, null, 12, 0,
new DateTime(2026, 5, 3, 0, 0, 0, DateTimeKind.Utc), new DateTime(2026, 5, 3, 1, 0, 0, DateTimeKind.Utc), "central-a");
private IActorRef CreateActor()
{
var services = new ServiceCollection().AddTestConfigurationTransaction();
services.AddScoped(_ => _store);
return Sys.ActorOf(Props.Create(() => new ManagementActor(
services.BuildServiceProvider(), NullLogger<ManagementActor>.Instance)));
}
private static ManagementEnvelope Envelope(object command, string[] sites, params string[] roles) =>
new(new AuthenticatedUser("u", "U", roles, sites), command, Guid.NewGuid().ToString("N"));
/// <summary>A Viewer gets the store's verdicts; the records reach the store unchanged.</summary>
[Fact]
public void Viewer_GetsTheVerdicts_ForTheSuppliedRecords()
{
var check = new AuditChainHeadCheck("2026-05", 12, Record.ExportedAtUtc, "central-a",
AuditChainHeadStatus.Mismatch, 12, "rewritten");
_store.VerifyExportedHeadsAsync(Arg.Any<IReadOnlyList<AuditChainHeadRecord>>(), Arg.Any<CancellationToken>())
.Returns(new AuditChainHeadVerificationResult(false, 1, [check]));
CreateActor().Tell(Envelope(new VerifyAuditChainHeadsCommand([Record]), [], "Viewer"));
var response = ExpectMsg<ManagementSuccess>(TimeSpan.FromSeconds(5));
using var json = JsonDocument.Parse(response.JsonData);
Assert.False(json.RootElement.GetProperty("verified").GetBoolean());
Assert.Equal("Mismatch", json.RootElement.GetProperty("checks")[0].GetProperty("status").GetString());
_store.Received(1).VerifyExportedHeadsAsync(
Arg.Is<IReadOnlyList<AuditChainHeadRecord>>(r => r.Count == 1 && r[0] == Record), Arg.Any<CancellationToken>());
}
/// <summary>A Designer/Deployer without an OperationalAudit role is refused.</summary>
[Fact]
public void NonAuditRole_IsUnauthorized()
{
CreateActor().Tell(Envelope(new VerifyAuditChainHeadsCommand([Record]), [], "Designer", "Deployer"));
ExpectMsg<ManagementUnauthorized>(TimeSpan.FromSeconds(5));
_store.DidNotReceiveWithAnyArgs().VerifyExportedHeadsAsync(default!, default);
}
/// <summary>A site-scoped Viewer is refused: the chain spans every site.</summary>
[Fact]
public void SiteScopedViewer_IsRefused()
{
CreateActor().Tell(Envelope(new VerifyAuditChainHeadsCommand([Record]), ["3"], "Viewer"));
var response = ExpectMsg<ManagementUnauthorized>(TimeSpan.FromSeconds(5));
Assert.Contains("spans every site", response.Message);
_store.DidNotReceiveWithAnyArgs().VerifyExportedHeadsAsync(default!, default);
}
/// <summary>No records, or more than the cap, is a caller error.</summary>
/// <param name="count">Records supplied.</param>
[Theory]
[InlineData(0)]
[InlineData(ManagementActor.MaxChainHeadRecords + 1)]
public void EmptyOrOversizedInput_IsInvalidArgument(int count)
{
CreateActor().Tell(Envelope(
new VerifyAuditChainHeadsCommand(Enumerable.Repeat(Record, count).ToList()), [], "Administrator"));
var response = ExpectMsg<ManagementError>(TimeSpan.FromSeconds(5));
Assert.Equal("INVALID_ARGUMENT", response.ErrorCode);
_store.DidNotReceiveWithAnyArgs().VerifyExportedHeadsAsync(default!, default);
}
/// <summary>A chain lock that cannot be had surfaces as CHAIN_BUSY.</summary>
[Fact]
public void BusyChain_IsChainBusy()
{
_store.VerifyExportedHeadsAsync(Arg.Any<IReadOnlyList<AuditChainHeadRecord>>(), Arg.Any<CancellationToken>())
.Returns<Task<AuditChainHeadVerificationResult>>(_ => throw new TimeoutException("busy"));
CreateActor().Tell(Envelope(new VerifyAuditChainHeadsCommand([Record]), [], "Administrator"));
Assert.Equal("CHAIN_BUSY", ExpectMsg<ManagementError>(TimeSpan.FromSeconds(5)).ErrorCode);
}
/// <summary>Runs under the long-running Ask timeout.</summary>
[Fact]
public void VerifyAuditChainHeads_UsesLongRunningAskTimeout()
{
Assert.Equal(TimeSpan.FromMinutes(5),
ManagementEndpoints.ResolveAskTimeout(new ManagementServiceOptions(), typeof(VerifyAuditChainHeadsCommand)));
}
}