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
This commit is contained in:
Joseph Doherty
2026-11-09 16:28:43 -05:00
parent 3cf97f6dda
commit fd4be80913
24 changed files with 4596 additions and 6 deletions
@@ -0,0 +1,46 @@
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>
/// <param name="batchSize">Maximum rows to chain in this pass.</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, 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);
}
@@ -155,6 +155,11 @@ public interface IAuditLogRepository
/// <c>OccurredAtUtc</c> is strictly older than <paramref name="threshold"/>, in
/// bounded batches of <paramref name="batchSize"/> rows, looping until no further
/// 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>
/// <remarks>
/// <para>
@@ -0,0 +1,100 @@
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>
/// 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 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.
/// </param>
/// <param name="FirstBreak">The first break, or null when <see cref="Status"/> is not <see cref="AuditChainStatus.Broken"/>.</param>
public sealed record AuditChainVerificationResult(
string Partition,
AuditChainStatus Status,
long RowsVerified,
long TombstonesApplied,
long? PurgedThroughSeq,
long? HeadSeq,
long UnchainedRows,
AuditChainBreak? FirstBreak);
/// <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);