< Summary

Information
Class: AsiBackbone.Signing.LocalDevelopment.LocalDevelopmentSigningOptions
Assembly: AsiBackbone.Signing.LocalDevelopment
File(s): /home/runner/work/AsiBackbone/AsiBackbone/src/AsiBackbone.Signing.LocalDevelopment/LocalDevelopmentSigningOptions.cs
Line coverage
100%
Covered lines: 35
Uncovered lines: 0
Coverable lines: 35
Total lines: 194
Line coverage: 100%
Branch coverage
100%
Covered branches: 12
Total branches: 12
Branch coverage: 100%
Method coverage

Feature is only available for sponsors

Upgrade to PRO version

Metrics

MethodBranch coverage Crap Score Cyclomatic complexity Line coverage
Validate()100%22100%
Snapshot()100%11100%
Create(...)100%1010100%

File(s)

/home/runner/work/AsiBackbone/AsiBackbone/src/AsiBackbone.Signing.LocalDevelopment/LocalDevelopmentSigningOptions.cs

#LineLine coverage
 1namespace AsiBackbone.Signing.LocalDevelopment;
 2
 3/// <summary>
 4/// Configures the local-development signing provider.
 5/// </summary>
 6/// <remarks>
 7/// This provider is intended for local development, samples, and tests. It is not a production managed-key provider and
 8/// </remarks>
 9public sealed class LocalDevelopmentSigningOptions
 10{
 11    /// <summary>
 12    /// Gets the minimum supported RSA key size for generated local-development keys.
 13    /// </summary>
 14    public const int MinimumKeySizeBits = 2048;
 15
 16    /// <summary>
 17    /// Gets the default provider descriptor returned in signing metadata.
 18    /// </summary>
 19    public const string DefaultProviderName = "local-development";
 20
 21    /// <summary>
 22    /// Gets the default local-development key identifier.
 23    /// </summary>
 24    public const string DefaultKeyId = "local-dev-key";
 25
 26    /// <summary>
 27    /// Gets the default local-development key version.
 28    /// </summary>
 29    public const string DefaultKeyVersion = "dev";
 30
 31    /// <summary>
 32    /// Gets the default provider-neutral signature algorithm descriptor.
 33    /// </summary>
 34    public const string DefaultSignatureAlgorithm = "RSASSA-PSS-SHA256-LOCAL-DEV";
 35
 36    /// <summary>
 37    /// Gets the default RSA key size for generated local-development keys.
 38    /// </summary>
 39    public const int DefaultKeySizeBits = MinimumKeySizeBits;
 40
 41    /// <summary>
 42    /// Gets or sets the provider descriptor returned in signing metadata.
 43    /// </summary>
 44    public string ProviderName { get; set; } = DefaultProviderName;
 45
 46    /// <summary>
 47    /// Gets or sets the local-development key identifier returned in signing metadata.
 48    /// </summary>
 49    public string KeyId { get; set; } = DefaultKeyId;
 50
 51    /// <summary>
 52    /// Gets or sets the local-development key version returned in signing metadata.
 53    /// </summary>
 54    public string KeyVersion { get; set; } = DefaultKeyVersion;
 55
 56    /// <summary>
 57    /// Gets or sets the signature algorithm descriptor returned in signing metadata.
 58    /// </summary>
 59    public string SignatureAlgorithm { get; set; } = DefaultSignatureAlgorithm;
 60
 61    /// <summary>
 62    /// Gets or sets the generated RSA key size in bits.
 63    /// </summary>
 64    /// <remarks>
 65    /// Values below <see cref="MinimumKeySizeBits" /> are invalid. Omitted configuration uses
 66    /// <see cref="DefaultKeySizeBits" />.
 67    /// </remarks>
 68    public int KeySizeBits { get; set; } = DefaultKeySizeBits;
 69
 70    /// <summary>
 71    /// Gets or sets a PEM-encoded RSA key to use instead of generating one per process.
 72    /// </summary>
 73    /// <remarks>
 74    /// <para>
 75    /// When null or blank, the provider generates a <see cref="KeySizeBits" /> key in each process, so signatures stop
 76    /// verifying after a restart and cannot be verified by another process. Supplying a key gives every process
 77    /// configured with it the same signing identity, which lets a capability grant issued by one process, or before a
 78    /// restart, verify in another.
 79    /// </para>
 80    /// <para>
 81    /// A private key (<c>RSA PRIVATE KEY</c> or <c>PRIVATE KEY</c>) supports signing and verification. A public key
 82    /// (<c>PUBLIC KEY</c> or <c>RSA PUBLIC KEY</c>) supports verification only; signing with it fails. The key must be 
 83    /// least <see cref="MinimumKeySizeBits" /> bits, and <see cref="KeySizeBits" /> is ignored. Encrypted PEM is not
 84    /// supported.
 85    /// </para>
 86    /// <para>
 87    /// This remains a local-development provider: the key is held in process memory with no custody, rotation, or
 88    /// revocation story. Load it from a development secret store rather than source control, and use a managed key
 89    /// provider in production.
 90    /// </para>
 91    /// </remarks>
 92    public string? RsaKeyPem { get; set; }
 93
 94    /// <summary>
 95    /// Gets or sets a value indicating whether signing failures should return unsigned metadata with explicit failure d
 96    /// </summary>
 97    public bool ReturnUnsignedOnFailure { get; set; } = true;
 98
 99    /// <summary>
 100    /// Gets or sets a value indicating whether this provider may be registered while the host reports a production envi
 101    /// </summary>
 102    /// <remarks>
 103    /// Registration fails in Production by default. This provider is not a production key-custody control, even when a
 104    /// configured PEM is supplied. Setting this property to <see langword="true" /> is an explicit escape hatch for
 105    /// exceptional test/demo scenarios only; it does not make LocalDevelopment signing suitable for normal production
 106    /// use. Production hosts should use <c>AsiBackbone.Signing.ManagedKey</c> with a reviewed host-owned managed-key
 107    /// implementation. See the signing-provider package-boundary guidance in the AsiBackbone documentation.
 108    /// </remarks>
 109    public bool AllowInProduction { get; set; }
 110
 111    /// <summary>
 112    /// Gets or sets the environment name used by the production guard, overriding the ambient environment variables.
 113    /// </summary>
 114    /// <remarks>
 115    /// When null, the guard reads <c>DOTNET_ENVIRONMENT</c> and then <c>ASPNETCORE_ENVIRONMENT</c>. This package does n
 116    /// depend on the hosting abstractions, so non-hosted/unit-test scenarios remain usable without fabricating a host
 117    /// environment. A host that determines its environment another way supplies the name here.
 118    /// </remarks>
 119    public string? EnvironmentName { get; set; }
 120
 121    /// <summary>
 122    /// Validates the configured local-development signing options.
 123    /// </summary>
 124    /// <exception cref="InvalidOperationException">
 125    /// Thrown when <see cref="KeySizeBits" /> is below <see cref="MinimumKeySizeBits" />.
 126    /// </exception>
 127    public void Validate()
 128    {
 67129        if (KeySizeBits < MinimumKeySizeBits)
 130        {
 11131            throw new InvalidOperationException(
 11132                $"Local-development RSA key size must be at least {MinimumKeySizeBits} bits. Configured value: {KeySizeB
 133        }
 56134    }
 135
 136    /// <summary>
 137    /// Creates an independent copy of these options.
 138    /// </summary>
 139    /// <remarks>
 140    /// Registration and the signing service each hold a snapshot rather than the caller's instance. Every property has 
 141    /// public setter, so holding the caller's instance would let a later assignment, such as setting
 142    /// <see cref="AllowInProduction" /> after the production guard ran, change a registered service's behavior.
 143    /// </remarks>
 144    /// <returns>A copy whose later changes do not affect this instance, and the reverse.</returns>
 145    internal LocalDevelopmentSigningOptions Snapshot()
 146    {
 69147        return new LocalDevelopmentSigningOptions
 69148        {
 69149            ProviderName = ProviderName,
 69150            KeyId = KeyId,
 69151            KeyVersion = KeyVersion,
 69152            SignatureAlgorithm = SignatureAlgorithm,
 69153            KeySizeBits = KeySizeBits,
 69154            RsaKeyPem = RsaKeyPem,
 69155            ReturnUnsignedOnFailure = ReturnUnsignedOnFailure,
 69156            AllowInProduction = AllowInProduction,
 69157            EnvironmentName = EnvironmentName
 69158        };
 159    }
 160
 161    /// <summary>
 162    /// Creates options for the local-development signing provider.
 163    /// </summary>
 164    public static LocalDevelopmentSigningOptions Create(
 165        string? providerName = null,
 166        string? keyId = null,
 167        string? keyVersion = null,
 168        string? signatureAlgorithm = null,
 169        int keySizeBits = DefaultKeySizeBits,
 170        bool returnUnsignedOnFailure = true,
 171        bool allowInProduction = false,
 172        string? environmentName = null)
 173    {
 57174        return new LocalDevelopmentSigningOptions
 57175        {
 57176            AllowInProduction = allowInProduction,
 57177            EnvironmentName = string.IsNullOrWhiteSpace(environmentName) ? null : environmentName.Trim(),
 57178            ProviderName = string.IsNullOrWhiteSpace(providerName)
 57179                ? DefaultProviderName
 57180                : providerName.Trim(),
 57181            KeyId = string.IsNullOrWhiteSpace(keyId)
 57182                ? DefaultKeyId
 57183                : keyId.Trim(),
 57184            KeyVersion = string.IsNullOrWhiteSpace(keyVersion)
 57185                ? DefaultKeyVersion
 57186                : keyVersion.Trim(),
 57187            SignatureAlgorithm = string.IsNullOrWhiteSpace(signatureAlgorithm)
 57188                ? DefaultSignatureAlgorithm
 57189                : signatureAlgorithm.Trim(),
 57190            KeySizeBits = keySizeBits,
 57191            ReturnUnsignedOnFailure = returnUnsignedOnFailure
 57192        };
 193    }
 194}