feat(audit): SHA-256 hash chain over the central AuditLog (ScadaBridge#41)

Audit roadmap T1 (alog.md §11.4): one chain per UTC calendar month of OccurredAtUtc. Each chained row carries ChainSeq (gap-free within its month) and RowHash = SHA-256(prev.RowHash || canonical(row)); the v1 canonical form (AuditChainHasher) is pinned by a known-answer vector computed independently. - Migration AddAuditLogHashChain: nullable ChainSeq/RowHash on dbo.AuditLog (metadata-only add), AuditLogChainHead (per-month chain end + partition-purge checkpoint anchor), AuditLogChainTombstone, two partition-aligned filtered indexes, scadabridge_audit_chainer role with a column-level UPDATE grant. Production script docs/plans/sql/AddAuditLogHashChain.sql. - AuditLogHashChain chains unchained rows oldest month first under an exclusive sp_getapplock (zero timeout, so a dual-active central pair still yields one chain), with an optimistic head check and a ChainSeq IS NULL row-count check that roll a pass back instead of leaving a gap. The ingest path is untouched. - Purges keep the chain verifiable: the partition switch records the month's checkpoint anchor and drops its tombstones; the per-channel DELETE writes a tombstone per chained row in the same transaction (OUTPUT INTO). Both, and the SourceNode backfill, hold the chain lock; the backfill skips chained rows. The switch staging table gains the two new columns. - AuditChainVerifier reports the first break (partition, ChainSeq, EventId, kind) for edited, deleted, reordered rows and tail truncation. - AuditLogHashChainService (central, default OFF via AuditLog:HashChain). Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
2026-11-09 16:28:43 -05:00
parent 3cf97f6dda
commit fd4be80913
24 changed files with 4596 additions and 6 deletions
@@ -0,0 +1,125 @@
+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 Task<AuditChainBatchResult> ChainPendingAsync(int batchSize, CancellationToken ct = default)
+        {
+            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>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);
+    }
+}