feat(audit): hash-chain cutoff - chain only rows written from first enablement, no backlog (#139)

Owner decision on #107 (2026-11-13): enabling AuditLog:HashChain must not
chain the historical backlog. main chained every unchained row oldest-first.

- The first chaining pass on a pristine database (no head, no chained row)
  writes a chain-start anchor: AuditLogChainTombstone (cutoff month,
  ChainSeq 0), PurgedAtUtc = DB SYSUTCDATETIME(), RowHash =
  SHA-256("ScadaBridge.AuditLog.ChainCutoff.v1" || YYYY-MM || ticks).
  Written once under the exclusive chain lock, so both centrals agree
  whatever their clocks/config. No migration: existing table + grants.
- Only rows with OccurredAtUtc >= cutoff are chained. The anchor hash is
  the cutoff month's genesis, binding the cutoff into the chain.
- AuditLog:HashChain:ChainBacklog (default false) restores chain-everything,
  read only on the very first enablement. Legacy chains (heads, no anchor)
  keep chaining everything.
- verify-chain splits unchained rows into UnchainedRows vs PreCutoffRows
  (+ ChainFromUtc); new breaks ChainedBeforeCutoff (row re-dated before the
  cutoff, or cutoff moved forward) and CutoffAnchorInvalid (anchor hash /
  month / multiplicity). Archive verify uses the anchor from its own
  tombstone file or the DB.
- Partition switch-out keeps the anchor (deletes ChainSeq > 0 only); the
  head store / export / verify-heads tombstone count excludes it.
- CLI verify-chain table prints Chain from + Pre-cutoff rows.

Tests: AuditLogHashChainCutoffTests (7, MSSQL), 6 verifier unit tests,
service/CLI/management wire tests; 9 mutations all killed.

Claude-Session: https://claude.ai/code/session_01GT67ACmpMR7b9LGRPLijMi
This commit is contained in:
Joseph Doherty
2026-11-13 03:14:03 -05:00
parent 712c5117ee
commit 52da02a76a
21 changed files with 1208 additions and 49 deletions
@@ -21,8 +21,11 @@ public class AuditLogHashChainServiceTests
public int Calls => _next;
public Exception? Throw { get; init; }
public Task<AuditChainBatchResult> ChainPendingAsync(int batchSize, CancellationToken ct = default)
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));
@@ -71,6 +74,33 @@ public class AuditLogHashChainServiceTests
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]