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
@@ -246,7 +246,7 @@ public class ManagementActor : ReceiveActor
// three Live run commands stay DeployerOnly.
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;
// arch-review C6: area management is reconciled to any-of [Designer, Deployer].
@@ -387,16 +387,8 @@ public class ManagementActor : ReceiveActor
// (arch-review UA1).
ListSecuredWritesCommand => SecuredWriteReaders,
// AuditLog hash-chain verification (ScadaBridge#41): an audit read, so the
// OperationalAudit roles (alog.md §15.1 — verify-chain carries audit query's
// 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.
// AuditLog Parquet archives (ScadaBridge#42): audit reads — OperationalAudit roles
// (alog.md §15.1, audit query's permission), site-scoped callers refused in the handler.
ListAuditArchivesCommand => OperationalAuditReaders,
// Archive cleanup deletes archive files (ScadaBridge#109): Administrator only.
CleanupAuditArchivesCommand => AdminOnly,
@@ -572,8 +564,6 @@ public class ManagementActor : ReceiveActor
// Audit Log
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),
VerifyAuditArchiveCommand cmd => await HandleVerifyAuditArchive(sp, cmd, user),
CleanupAuditArchivesCommand cmd => await HandleCleanupAuditArchives(sp, cmd, user),
@@ -3230,42 +3220,6 @@ public class ManagementActor : ReceiveActor
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>
/// Lists the AuditLog Parquet archives (ScadaBridge#42). Refused for a site-scoped,
/// 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());
}
/// <summary>Upper bound on records per <see cref="VerifyAuditChainHeadsCommand"/>.</summary>
internal const int MaxChainHeadRecords = 50_000;
/// <summary>
/// Checks exported AuditLog chain heads against the database (ScadaBridge#107 item 1). Same
/// 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.
/// Verifies one AuditLog Parquet archive (ScadaBridge#42): the data file against its manifest.
/// </summary>
private static async Task<object?> HandleVerifyAuditArchive(
IServiceProvider sp, VerifyAuditArchiveCommand cmd, AuthenticatedUser user)
@@ -3341,16 +3252,12 @@ public class ManagementActor : ReceiveActor
}
/// <summary>
/// Runs the archive cleanup now (ScadaBridge#109), on the maintenance-connection archive when
/// registered. Dry run reports only.
/// Runs the archive cleanup now (ScadaBridge#109). Dry run reports only.
/// </summary>
private static async Task<object?> HandleCleanupAuditArchives(
IServiceProvider sp, CleanupAuditArchivesCommand cmd, AuthenticatedUser user)
{
RequireAuditArchive(sp, user);
var archive = sp.GetKeyedService<IAuditLogArchive>(
ZB.MOM.WW.ScadaBridge.ConfigurationDatabase.Maintenance.AuditMaintenanceContext.ServiceKey)
?? sp.GetRequiredService<IAuditLogArchive>();
var archive = RequireAuditArchive(sp, user);
return await archive.CleanupAsync(cmd.DryRun);
}