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:
@@ -31,10 +31,22 @@ public interface IAuditLogHashChain
|
||||
/// 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, CancellationToken ct = default);
|
||||
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.
|
||||
|
||||
@@ -46,6 +46,20 @@ public enum AuditChainBreakKind
|
||||
/// 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>
|
||||
@@ -80,10 +94,20 @@ public sealed record AuditChainBreak(
|
||||
/// </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.
|
||||
/// 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,
|
||||
@@ -92,7 +116,9 @@ public sealed record AuditChainVerificationResult(
|
||||
long? PurgedThroughSeq,
|
||||
long? HeadSeq,
|
||||
long UnchainedRows,
|
||||
AuditChainBreak? FirstBreak);
|
||||
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>
|
||||
|
||||
Reference in New Issue
Block a user