| | | 1 | | namespace AsiBackbone.Core.Signing; |
| | | 2 | | |
| | | 3 | | /// <summary> |
| | | 4 | | /// Provides provider-neutral helpers for verifying signed governance artifacts and applying verification policy. |
| | | 5 | | /// </summary> |
| | | 6 | | /// <remarks> |
| | | 7 | | /// The verifier wrapper does not resolve provider-specific keys in Core and does not imply legal evidence, compliance c |
| | | 8 | | /// </remarks> |
| | | 9 | | public static class GovernanceArtifactVerifier |
| | | 10 | | { |
| | | 11 | | /// <summary> |
| | | 12 | | /// Verifies a signed governance artifact and maps the result to a host-facing policy outcome. |
| | | 13 | | /// </summary> |
| | | 14 | | public static async ValueTask<VerificationPolicyOutcome> VerifyAsync<TArtifact>( |
| | | 15 | | SignedGovernanceArtifact<TArtifact> artifact, |
| | | 16 | | IAsiBackboneSignatureVerificationService verificationService, |
| | | 17 | | VerificationPolicyOptions? options = null, |
| | | 18 | | VerificationPolicyContext? context = null, |
| | | 19 | | CancellationToken cancellationToken = default) |
| | | 20 | | { |
| | 72 | 21 | | ArgumentNullException.ThrowIfNull(artifact); |
| | 72 | 22 | | ArgumentNullException.ThrowIfNull(verificationService); |
| | 72 | 23 | | cancellationToken.ThrowIfCancellationRequested(); |
| | | 24 | | |
| | 72 | 25 | | VerificationPolicyContext effectiveContext = context ?? VerificationPolicyContext.Default; |
| | 72 | 26 | | SignatureVerificationResult? preflightResult = ValidateBeforeProvider(artifact, effectiveContext); |
| | | 27 | | |
| | 72 | 28 | | if (preflightResult is not null) |
| | | 29 | | { |
| | 34 | 30 | | return VerificationPolicyEvaluator.Evaluate(artifact, preflightResult, options); |
| | | 31 | | } |
| | | 32 | | |
| | | 33 | | try |
| | | 34 | | { |
| | 38 | 35 | | SignatureVerificationResult verificationResult = await verificationService |
| | 38 | 36 | | .VerifyAsync( |
| | 38 | 37 | | new SignatureVerificationRequest( |
| | 38 | 38 | | artifact.SigningHash, |
| | 38 | 39 | | artifact.SigningMetadata, |
| | 38 | 40 | | purpose: effectiveContext.Purpose ?? artifact.ArtifactType, |
| | 38 | 41 | | metadata: effectiveContext.Metadata), |
| | 38 | 42 | | cancellationToken) |
| | 38 | 43 | | .ConfigureAwait(false); |
| | | 44 | | |
| | 30 | 45 | | return VerificationPolicyEvaluator.Evaluate(artifact, verificationResult, options); |
| | | 46 | | } |
| | 4 | 47 | | catch (InvalidOperationException exception) |
| | | 48 | | { |
| | 4 | 49 | | return CreateProviderUnavailableOutcome(artifact, options, exception); |
| | | 50 | | } |
| | 2 | 51 | | catch (NotSupportedException exception) |
| | | 52 | | { |
| | 2 | 53 | | return CreateProviderUnavailableOutcome(artifact, options, exception); |
| | | 54 | | } |
| | 2 | 55 | | catch (TimeoutException exception) |
| | | 56 | | { |
| | 2 | 57 | | return CreateProviderUnavailableOutcome(artifact, options, exception); |
| | | 58 | | } |
| | 72 | 59 | | } |
| | | 60 | | |
| | | 61 | | private static VerificationPolicyOutcome CreateProviderUnavailableOutcome<TArtifact>( |
| | | 62 | | SignedGovernanceArtifact<TArtifact> artifact, |
| | | 63 | | VerificationPolicyOptions? options, |
| | | 64 | | Exception exception) |
| | | 65 | | { |
| | 8 | 66 | | var providerUnavailableResult = SignatureVerificationResult.Failed( |
| | 8 | 67 | | "signature.provider-unavailable", |
| | 8 | 68 | | exception.GetType().Name); |
| | | 69 | | |
| | 8 | 70 | | return VerificationPolicyEvaluator.Evaluate(artifact, providerUnavailableResult, options); |
| | | 71 | | } |
| | | 72 | | |
| | | 73 | | private static SignatureVerificationResult? ValidateBeforeProvider<TArtifact>( |
| | | 74 | | SignedGovernanceArtifact<TArtifact> artifact, |
| | | 75 | | VerificationPolicyContext context) |
| | | 76 | | { |
| | 72 | 77 | | SigningMetadata metadata = artifact.SigningMetadata; |
| | | 78 | | |
| | 72 | 79 | | return artifact.HasNoSignature || !metadata.HasSignature |
| | 72 | 80 | | ? SignatureVerificationResult.MissingSignature("The governance artifact does not carry signature metadata.") |
| | 72 | 81 | | : string.IsNullOrWhiteSpace(metadata.SigningHash) |
| | 72 | 82 | | ? SignatureVerificationResult.MissingSignature("The governance artifact does not carry the hash that was sig |
| | 72 | 83 | | : !string.Equals(metadata.SigningHash, artifact.SigningHash, StringComparison.Ordinal) |
| | 72 | 84 | | ? SignatureVerificationResult.Failed( |
| | 72 | 85 | | "signature.hash-mismatch", |
| | 72 | 86 | | "The signing metadata hash does not match the canonical artifact hash.") |
| | 72 | 87 | | : metadata.HashAlgorithm is not null |
| | 72 | 88 | | && !string.Equals(metadata.HashAlgorithm, artifact.HashAlgorithm, StringComparison.OrdinalIgnoreCase) |
| | 72 | 89 | | ? SignatureVerificationResult.Failed( |
| | 72 | 90 | | "signature.hash-algorithm-unsupported", |
| | 72 | 91 | | "The signing metadata hash algorithm does not match the canonical artifact hash algorithm.") |
| | 72 | 92 | | : context.RequiredHashAlgorithm is not null |
| | 72 | 93 | | && !string.Equals(context.RequiredHashAlgorithm, artifact.HashAlgorithm, StringComparison.OrdinalIgnoreCase) |
| | 72 | 94 | | ? SignatureVerificationResult.Failed( |
| | 72 | 95 | | "signature.hash-algorithm-unsupported", |
| | 72 | 96 | | "The canonical artifact hash algorithm does not match the required verification policy algorithm.") |
| | 72 | 97 | | : !MatchesCanonicalMetadata(metadata, "artifact_id", artifact.ArtifactId) |
| | 72 | 98 | | || !MatchesCanonicalMetadata(metadata, "artifact_type", artifact.ArtifactType) |
| | 72 | 99 | | || !MatchesCanonicalMetadata(metadata, "canonicalization_version", artifact.CanonicalHash.CanonicalizationVe |
| | 72 | 100 | | || !MatchesCanonicalMetadata(metadata, "payload_schema_version", artifact.CanonicalHash.PayloadSchemaVersion |
| | 72 | 101 | | ? SignatureVerificationResult.Failed( |
| | 72 | 102 | | "signature.canonicalization-mismatch", |
| | 72 | 103 | | "The signing metadata canonical artifact descriptors do not match the artifact being verified.") |
| | 72 | 104 | | : context.ExpectedKeyId is not null |
| | 72 | 105 | | && !string.Equals(context.ExpectedKeyId, metadata.KeyId, StringComparison.Ordinal) |
| | 72 | 106 | | ? SignatureVerificationResult.Failed( |
| | 72 | 107 | | "signature.key-version-unknown", |
| | 72 | 108 | | "The signing key identifier does not match the verification policy expectation.") |
| | 72 | 109 | | : context.ExpectedKeyVersion is not null |
| | 72 | 110 | | && !string.Equals(context.ExpectedKeyVersion, metadata.KeyVersion, StringComparison.Ordinal) |
| | 72 | 111 | | ? SignatureVerificationResult.Failed( |
| | 72 | 112 | | "signature.key-version-unknown", |
| | 72 | 113 | | "The signing key version does not match the verification policy expectation.") |
| | 72 | 114 | | : context.RequiredProvider is not null |
| | 72 | 115 | | && !string.Equals(context.RequiredProvider, metadata.Provider, StringComparison.Ordinal) |
| | 72 | 116 | | ? SignatureVerificationResult.Failed( |
| | 72 | 117 | | "signature.provider-unavailable", |
| | 72 | 118 | | "The signing provider does not match the required verification policy provider.") |
| | 72 | 119 | | : !MatchesOptionalPolicyMetadata(metadata, "policy_version", context.ExpectedPolicyVersion) |
| | 72 | 120 | | || !MatchesOptionalPolicyMetadata(metadata, "policy_hash", context.ExpectedPolicyHash) |
| | 72 | 121 | | ? SignatureVerificationResult.Failed( |
| | 72 | 122 | | "signature.canonicalization-mismatch", |
| | 72 | 123 | | "The signing metadata policy context does not match the verification policy expectation.") |
| | 72 | 124 | | : null; |
| | | 125 | | } |
| | | 126 | | |
| | | 127 | | private static bool MatchesCanonicalMetadata(SigningMetadata metadata, string key, string expectedValue) |
| | | 128 | | { |
| | 228 | 129 | | return !metadata.Metadata.TryGetValue(key, out string? value) |
| | 228 | 130 | | || string.Equals(value, expectedValue, StringComparison.Ordinal); |
| | | 131 | | } |
| | | 132 | | |
| | | 133 | | private static bool MatchesOptionalPolicyMetadata(SigningMetadata metadata, string key, string? expectedValue) |
| | | 134 | | { |
| | 82 | 135 | | return expectedValue is null |
| | 82 | 136 | | || (metadata.Metadata.TryGetValue(key, out string? value) |
| | 82 | 137 | | && string.Equals(value, expectedValue, StringComparison.Ordinal)); |
| | | 138 | | } |
| | | 139 | | } |