feat(options): eager startup validation for central-component options (Transport, SiteCallAudit, DeploymentManager) (arch-review 08 §1.5)

Claude-Session: https://claude.ai/code/session_01MtdgwpEeCUn6cUA5f1LMPj

src/ZB.MOM.WW.ScadaBridge.DeploymentManager/DeploymentManagerOptionsValidator.cs

@@ -0,0 +1,31 @@
+using ZB.MOM.WW.Configuration;
+
+namespace ZB.MOM.WW.ScadaBridge.DeploymentManager;
+
+/// <summary>
+/// Validates <see cref="DeploymentManagerOptions"/> at startup. Each timeout is
+/// applied as a linked-CTS deadline around a lifecycle command, per-site artifact
+/// deployment, or operation-lock acquisition; a zero/negative value makes the
+/// deadline fire immediately (or the <see cref="System.Threading.CancellationTokenSource"/>
+/// constructor throw), breaking deployments with an opaque failure. Registered
+/// with <c>ValidateOnStart()</c> so a bad <c>ScadaBridge:DeploymentManager</c>
+/// section fails fast at boot with a clear, key-naming message.
+/// </summary>
+public sealed class DeploymentManagerOptionsValidator : OptionsValidatorBase<DeploymentManagerOptions>
+{
+    /// <inheritdoc />
+    protected override void Validate(ValidationBuilder builder, DeploymentManagerOptions options)
+    {
+        builder.RequireThat(options.LifecycleCommandTimeout > TimeSpan.Zero,
+            $"ScadaBridge:DeploymentManager:LifecycleCommandTimeout must be a positive duration " +
+            $"(was {options.LifecycleCommandTimeout}); it bounds a lifecycle command round-trip.");
+
+        builder.RequireThat(options.ArtifactDeploymentTimeoutPerSite > TimeSpan.Zero,
+            $"ScadaBridge:DeploymentManager:ArtifactDeploymentTimeoutPerSite must be a positive duration " +
+            $"(was {options.ArtifactDeploymentTimeoutPerSite}); it bounds per-site artifact deployment.");
+
+        builder.RequireThat(options.OperationLockTimeout > TimeSpan.Zero,
+            $"ScadaBridge:DeploymentManager:OperationLockTimeout must be a positive duration " +
+            $"(was {options.OperationLockTimeout}); it bounds acquiring an instance operation lock.");
+    }
+}

src/ZB.MOM.WW.ScadaBridge.DeploymentManager/ServiceCollectionExtensions.cs

@@ -1,4 +1,6 @@
 using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.DependencyInjection.Extensions;
+using Microsoft.Extensions.Options;
 using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Transport;
 
 namespace ZB.MOM.WW.ScadaBridge.DeploymentManager;
@@ -27,8 +29,14 @@ public static class ServiceCollectionExtensions
     {
         // Ensure the options class is always resolvable.
         // The Host binds OptionsSection to appsettings.json; absent that binding
-        // the declared option-class defaults apply.
-        services.AddOptions<DeploymentManagerOptions>();
+        // the declared option-class defaults apply. Eager startup validation
+        // (arch-review 08 §1.5): ValidateOnStart makes a zero/negative timeout —
+        // which would fire a linked-CTS deadline immediately (or throw in the
+        // CancellationTokenSource ctor) — fail fast at boot with a clear,
+        // key-naming message. Applies even though defaults are code-configured.
+        services.AddOptions<DeploymentManagerOptions>().ValidateOnStart();
+        services.TryAddEnumerable(
+            ServiceDescriptor.Singleton<IValidateOptions<DeploymentManagerOptions>, DeploymentManagerOptionsValidator>());
         services.AddSingleton<OperationLockManager>();
 
         // Push-based deployment-status notification. Registered

src/ZB.MOM.WW.ScadaBridge.DeploymentManager/ZB.MOM.WW.ScadaBridge.DeploymentManager.csproj

@@ -11,6 +11,7 @@
     <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" />
     <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" />
     <PackageReference Include="Microsoft.Extensions.Options" />
+    <PackageReference Include="ZB.MOM.WW.Configuration" />
   </ItemGroup>
 
   <ItemGroup>

src/ZB.MOM.WW.ScadaBridge.SiteCallAudit/ServiceCollectionExtensions.cs

@@ -1,5 +1,6 @@
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.DependencyInjection.Extensions;
+using Microsoft.Extensions.Options;
 using ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Kpi;
 using ZB.MOM.WW.ScadaBridge.SiteCallAudit.Kpi;
 
@@ -37,8 +38,15 @@ public static class ServiceCollectionExtensions
     {
         ArgumentNullException.ThrowIfNull(services);
 
+        // Eager startup validation (arch-review 08 §1.5): ValidateOnStart makes a
+        // bad ScadaBridge:SiteCallAudit section — a zero/negative cadence that would
+        // spin an Akka scheduler, or a non-positive KPI/retention knob — fail fast
+        // at boot with a clear, key-naming message.
         services.AddOptions<SiteCallAuditOptions>()
-            .BindConfiguration(OptionsSection);
+            .BindConfiguration(OptionsSection)
+            .ValidateOnStart();
+        services.TryAddEnumerable(
+            ServiceDescriptor.Singleton<IValidateOptions<SiteCallAuditOptions>, SiteCallAuditOptionsValidator>());
 
         // KPI History: the central recorder enumerates every registered
         // IKpiSampleSource each sampling pass; this one snapshots the SiteCalls

src/ZB.MOM.WW.ScadaBridge.SiteCallAudit/SiteCallAuditOptionsValidator.cs

@@ -0,0 +1,48 @@
+using ZB.MOM.WW.Configuration;
+
+namespace ZB.MOM.WW.ScadaBridge.SiteCallAudit;
+
+/// <summary>
+/// Validates <see cref="SiteCallAuditOptions"/> at startup. The durations feed
+/// stuck-call detection, KPI windowing, the central→site relay Ask timeout, and
+/// the two central-singleton scheduler cadences (reconciliation + purge); a
+/// zero/negative value makes an Akka scheduler spin or a KPI window collapse.
+/// Registered with <c>ValidateOnStart()</c> so a bad <c>ScadaBridge:SiteCallAudit</c>
+/// section fails fast at boot with a clear, key-naming message. Validates the
+/// BASE properties — the <c>Resolved*</c> computed properties clamp bad cadence
+/// values away and would hide the misconfiguration.
+/// </summary>
+public sealed class SiteCallAuditOptionsValidator : OptionsValidatorBase<SiteCallAuditOptions>
+{
+    /// <inheritdoc />
+    protected override void Validate(ValidationBuilder builder, SiteCallAuditOptions options)
+    {
+        builder.RequireThat(options.StuckAgeThreshold > TimeSpan.Zero,
+            $"ScadaBridge:SiteCallAudit:StuckAgeThreshold must be a positive duration " +
+            $"(was {options.StuckAgeThreshold}); it is the age past which a cached call is flagged stuck.");
+
+        builder.RequireThat(options.KpiInterval > TimeSpan.Zero,
+            $"ScadaBridge:SiteCallAudit:KpiInterval must be a positive duration " +
+            $"(was {options.KpiInterval}); it is the trailing window for the throughput KPIs.");
+
+        builder.RequireThat(options.RelayTimeout > TimeSpan.Zero,
+            $"ScadaBridge:SiteCallAudit:RelayTimeout must be a positive duration " +
+            $"(was {options.RelayTimeout}); it is the Ask timeout for the central→site Retry/Discard relay.");
+
+        builder.RequireThat(options.ReconciliationInterval > TimeSpan.Zero,
+            $"ScadaBridge:SiteCallAudit:ReconciliationInterval must be a positive duration " +
+            $"(was {options.ReconciliationInterval}); it is the period of the per-site reconciliation pull.");
+
+        builder.RequireThat(options.ReconciliationBatchSize > 0,
+            $"ScadaBridge:SiteCallAudit:ReconciliationBatchSize must be positive " +
+            $"(was {options.ReconciliationBatchSize}); it is the max rows requested per PullSiteCalls RPC.");
+
+        builder.RequireThat(options.PurgeInterval > TimeSpan.Zero,
+            $"ScadaBridge:SiteCallAudit:PurgeInterval must be a positive duration " +
+            $"(was {options.PurgeInterval}); it is the period of the daily terminal-row purge tick.");
+
+        builder.RequireThat(options.RetentionDays > 0,
+            $"ScadaBridge:SiteCallAudit:RetentionDays must be positive " +
+            $"(was {options.RetentionDays}); it is the retention window for terminal SiteCalls rows.");
+    }
+}

src/ZB.MOM.WW.ScadaBridge.SiteCallAudit/ZB.MOM.WW.ScadaBridge.SiteCallAudit.csproj

@@ -15,6 +15,7 @@
     <PackageReference Include="Microsoft.Extensions.Options" />
     <!-- BindConfiguration extension for the SiteCallAuditOptions binding. -->
     <PackageReference Include="Microsoft.Extensions.Options.ConfigurationExtensions" />
+    <PackageReference Include="ZB.MOM.WW.Configuration" />
   </ItemGroup>
 
   <ItemGroup>

src/ZB.MOM.WW.ScadaBridge.Transport/ServiceCollectionExtensions.cs

@@ -22,7 +22,14 @@ public static class ServiceCollectionExtensions
     public static IServiceCollection AddTransport(this IServiceCollection services)
     {
         ArgumentNullException.ThrowIfNull(services);
-        services.AddOptions<TransportOptions>().BindConfiguration(OptionsSection);
+        // Eager startup validation (arch-review 08 §1.5): ValidateOnStart makes a
+        // bad ScadaBridge:Transport section — a zero/negative cap, or (critically)
+        // a Pbkdf2Iterations below the security floor that would silently weaken
+        // bundle key derivation — fail fast at boot with a clear, key-naming
+        // message instead of surfacing deep inside the import pipeline.
+        services.AddOptions<TransportOptions>().BindConfiguration(OptionsSection).ValidateOnStart();
+        services.TryAddEnumerable(
+            ServiceDescriptor.Singleton<IValidateOptions<TransportOptions>, TransportOptionsValidator>());
         services.TryAddSingleton(TimeProvider.System);
 
         // Pipeline building blocks: stateless services live as singletons; the

src/ZB.MOM.WW.ScadaBridge.Transport/TransportOptionsValidator.cs

@@ -0,0 +1,67 @@
+using ZB.MOM.WW.Configuration;
+
+namespace ZB.MOM.WW.ScadaBridge.Transport;
+
+/// <summary>
+/// Validates <see cref="TransportOptions"/> at startup. These knobs gate bundle
+/// size, the zip-bomb defences, unlock rate limiting, the schema-version stamp,
+/// and — security-critically — the PBKDF2 iteration count used to derive the
+/// bundle encryption key. A zero/negative value would either disable a cap,
+/// crash the import pipeline, or (for <see cref="TransportOptions.Pbkdf2Iterations"/>)
+/// silently weaken key derivation. Registered with <c>ValidateOnStart()</c> so a
+/// bad <c>ScadaBridge:Transport</c> section fails fast at boot with a clear,
+/// key-naming message.
+/// </summary>
+public sealed class TransportOptionsValidator : OptionsValidatorBase<TransportOptions>
+{
+    /// <summary>
+    /// Minimum acceptable PBKDF2 iteration count. A config typo (e.g. 6_000 in
+    /// place of the 600_000 default) must not silently weaken bundle key
+    /// derivation, so anything below this floor is rejected at startup.
+    /// </summary>
+    private const int MinPbkdf2Iterations = 100_000;
+
+    /// <inheritdoc />
+    protected override void Validate(ValidationBuilder builder, TransportOptions options)
+    {
+        builder.RequireThat(options.BundleSessionTtlMinutes > 0,
+            $"ScadaBridge:Transport:BundleSessionTtlMinutes must be a positive number of minutes " +
+            $"(was {options.BundleSessionTtlMinutes}); it is the TTL for an in-progress import session.");
+
+        builder.RequireThat(options.MaxBundleSizeMb > 0,
+            $"ScadaBridge:Transport:MaxBundleSizeMb must be positive " +
+            $"(was {options.MaxBundleSizeMb}); it caps the accepted bundle size.");
+
+        builder.RequireThat(options.MaxBundleEntryDecompressedMb > 0,
+            $"ScadaBridge:Transport:MaxBundleEntryDecompressedMb must be positive " +
+            $"(was {options.MaxBundleEntryDecompressedMb}); it caps the decompressed size of any single zip entry.");
+
+        builder.RequireThat(options.MaxBundleEntryCount > 0,
+            $"ScadaBridge:Transport:MaxBundleEntryCount must be positive " +
+            $"(was {options.MaxBundleEntryCount}); it caps the number of entries inside a bundle zip.");
+
+        builder.RequireThat(options.MaxBundleEntryCompressionRatio > 0,
+            $"ScadaBridge:Transport:MaxBundleEntryCompressionRatio must be positive " +
+            $"(was {options.MaxBundleEntryCompressionRatio}); it caps the per-entry compression ratio.");
+
+        builder.RequireThat(options.MaxUnlockAttemptsPerSession > 0,
+            $"ScadaBridge:Transport:MaxUnlockAttemptsPerSession must be positive " +
+            $"(was {options.MaxUnlockAttemptsPerSession}); it caps failed passphrase attempts before a session locks.");
+
+        builder.RequireThat(options.MaxUnlockAttemptsPerIpPerHour > 0,
+            $"ScadaBridge:Transport:MaxUnlockAttemptsPerIpPerHour must be positive " +
+            $"(was {options.MaxUnlockAttemptsPerIpPerHour}); it caps unlock attempts per IP address per hour.");
+
+        builder.RequireThat(options.Pbkdf2Iterations >= MinPbkdf2Iterations,
+            $"ScadaBridge:Transport:Pbkdf2Iterations must be at least {MinPbkdf2Iterations:N0} " +
+            $"(was {options.Pbkdf2Iterations}); a lower value silently weakens bundle key derivation.");
+
+        builder.RequireThat(options.SchemaVersionMajor > 0,
+            $"ScadaBridge:Transport:SchemaVersionMajor must be positive " +
+            $"(was {options.SchemaVersionMajor}); it is the major bundle-schema version this instance emits and accepts.");
+
+        builder.RequireThat(!string.IsNullOrWhiteSpace(options.SourceEnvironment),
+            "ScadaBridge:Transport:SourceEnvironment must be a non-empty name; it is stamped into " +
+            "BundleManifest.SourceEnvironment and the export filename.");
+    }
+}

src/ZB.MOM.WW.ScadaBridge.Transport/ZB.MOM.WW.ScadaBridge.Transport.csproj

@@ -11,6 +11,7 @@
     <PackageReference Include="Microsoft.Extensions.Hosting.Abstractions" />
     <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" />
     <PackageReference Include="Microsoft.Extensions.Options.ConfigurationExtensions" />
+    <PackageReference Include="ZB.MOM.WW.Configuration" />
   </ItemGroup>
 
   <ItemGroup>