feat(transport): production-boundary signing advisory, secret-key proof, runbook (#110)

Owner decisions on #110: one signing key per environment; TrustedKeys stay hand-edited;
Signing:ProductionBoundary (new, default off) logs a startup warning and reports a Degraded
bundle-signing-policy /health/ready entry while RequireSignedBundles is off; the private key
is read via ${secret:} (proved end to end, never logged); cluster pull decided not to be
built; differential deletions stay deferred. Adds docs/operations/bundle-signing-runbook.md.

Claude-Session: https://claude.ai/code/session_01GT67AEHd2Acv1YPwGfXEoV
This commit is contained in:
Joseph Doherty
2026-11-09 22:50:18 -05:00
parent a4806576af
commit 559e02f5c8
11 changed files with 421 additions and 10 deletions
@@ -71,6 +71,9 @@ public static class ServiceCollectionExtensions
// T-007: periodic eviction sweep so abandoned sessions clear without
// needing a fresh Get() to trigger lazy eviction.
services.AddHostedService<BundleSessionEvictionService>();
// ScadaBridge#110: warn at startup when a production-boundary cluster does not
// require signed bundles.
services.AddHostedService<BundleSigningPolicyStartupWarning>();
// SemanticValidator is a stateless utility used by ApplyAsync; use
// TryAdd so a host that already calls AddTemplateEngine() (which
// registers the same type as Transient) wins. Either registration
@@ -0,0 +1,61 @@
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
namespace ZB.MOM.WW.ScadaBridge.Transport.Signing;
/// <summary>
/// ScadaBridge#110: the production-boundary signing advisory. An environment marked
/// <c>ScadaBridge:Transport:Signing:ProductionBoundary</c> is expected to run with
/// <c>RequireSignedBundles</c> on; this is the single place that decides whether that
/// expectation is unmet, shared by the startup warning and the readiness health check.
/// </summary>
public static class BundleSigningPolicyAdvisory
{
/// <summary>
/// Evaluates the signing options.
/// </summary>
/// <param name="signing">The bound signing options.</param>
/// <returns>The advisory text when a production-boundary cluster accepts unsigned bundles; otherwise <c>null</c>.</returns>
public static string? Evaluate(TransportSigningOptions signing)
{
ArgumentNullException.ThrowIfNull(signing);
if (!signing.ProductionBoundary || signing.RequireSignedBundles)
{
return null;
}
return "ScadaBridge:Transport:Signing:ProductionBoundary is true but RequireSignedBundles is false: "
+ "this production-boundary cluster will import unsigned bundles and bundles signed by untrusted keys. "
+ "Turn on RequireSignedBundles once every exporting environment signs and its public key is in TrustedKeys.";
}
}
/// <summary>
/// ScadaBridge#110: logs the <see cref="BundleSigningPolicyAdvisory"/> once at startup.
/// </summary>
internal sealed class BundleSigningPolicyStartupWarning : IHostedService
{
private readonly IOptions<TransportOptions> _options;
private readonly ILogger<BundleSigningPolicyStartupWarning> _logger;
public BundleSigningPolicyStartupWarning(
IOptions<TransportOptions> options, ILogger<BundleSigningPolicyStartupWarning> logger)
{
_options = options ?? throw new ArgumentNullException(nameof(options));
_logger = logger ?? throw new ArgumentNullException(nameof(logger));
}
public Task StartAsync(CancellationToken cancellationToken)
{
var advisory = BundleSigningPolicyAdvisory.Evaluate(_options.Value.Signing);
if (advisory is not null)
{
_logger.LogWarning("{Advisory}", advisory);
}
return Task.CompletedTask;
}
public Task StopAsync(CancellationToken cancellationToken) => Task.CompletedTask;
}
@@ -102,6 +102,17 @@ public sealed class TransportSigningOptions
/// </summary>
public bool RequireSignedBundles { get; set; }
/// <summary>
/// Owner decision (ScadaBridge#110): marks this cluster as sitting on the production
/// boundary — an environment that imports bundles from other environments. While it is
/// <c>true</c> and <see cref="RequireSignedBundles"/> is <c>false</c> the node logs a
/// startup WARNING and the central <c>bundle-signing-policy</c> readiness check reports
/// Degraded. It changes no import behaviour: <see cref="RequireSignedBundles"/> stays
/// default-off in code, and is flipped per environment once every exporting cluster signs.
/// Default <c>false</c>.
/// </summary>
public bool ProductionBoundary { get; set; }
/// <summary>
/// Public keys this cluster trusts to sign bundles. Each entry's key id is the
/// <c>sha256:</c> fingerprint of its SubjectPublicKeyInfo, so no id needs to be