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.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>