< Summary

Information
Class: AsiBackbone.Core.CapabilityGrants.CapabilityGrantValidator
Assembly: AsiBackbone.Core
File(s): /home/runner/work/AsiBackbone/AsiBackbone/src/AsiBackbone.Core/CapabilityGrants/CapabilityGrantValidator.cs
Line coverage
95%
Covered lines: 231
Uncovered lines: 11
Coverable lines: 242
Total lines: 451
Line coverage: 95.4%
Branch coverage
92%
Covered branches: 115
Total branches: 125
Branch coverage: 92%
Method coverage

Feature is only available for sponsors

Upgrade to PRO version

Metrics

MethodBranch coverage Crap Score Cyclomatic complexity Line coverage
ValidateAsync()92.86%1414100%
ValidateProofAsync()90%1010100%
ValidateProofBinding(...)100%6676.47%
ValidateMetadata(...)100%5252100%
IsNotYetValid(...)100%44100%
IsExpired(...)100%22100%
ValidateUseAsync()73.68%1919100%
ContainsRequiredScopes(...)100%44100%
MapVerificationCategory(...)78.57%151482.35%

File(s)

/home/runner/work/AsiBackbone/AsiBackbone/src/AsiBackbone.Core/CapabilityGrants/CapabilityGrantValidator.cs

#LineLine coverage
 1using AsiBackbone.Core.Signing;
 2
 3namespace AsiBackbone.Core.CapabilityGrants;
 4
 5/// <summary>
 6/// Validates signed capability grants against host-supplied expectations before a governed operation executes.
 7/// </summary>
 8public static class CapabilityGrantValidator
 9{
 10    /// <summary>
 11    /// Validates a signed capability grant against the supplied options.
 12    /// </summary>
 13    /// <remarks>
 14    /// <para>
 15    /// Validation runs in a fixed order and returns the first failure: proof binding and signature verification when
 16    /// <see cref="CapabilityGrantValidationOptions.RequireProof" /> is set; then issuer, audience, subject, operation,
 17    /// validity window, scope, policy, acknowledgment, handshake, gateway, and resource expectations; and finally use
 18    /// consumption when <see cref="CapabilityGrantValidationOptions.RequireUseCheck" /> is set.
 19    /// </para>
 20    /// <para>
 21    /// Validation fails closed. Omitted options, a missing verifier when proof is required, or a missing use store
 22    /// when a use check is required each produce a failed result rather than a permissive one. Use consumption runs
 23    /// last so a grant that fails any other check does not consume a use.
 24    /// </para>
 25    /// </remarks>
 26    /// <param name="signedGrant">The signed capability grant to validate.</param>
 27    /// <param name="options">
 28    /// The expectations the grant is validated against. Validation fails when <see langword="null" />; use
 29    /// <see cref="CapabilityGrantValidationOptions.CreateBoundExecutionBoundary" /> at an execution boundary.
 30    /// </param>
 31    /// <param name="verificationService">The signature verification service, required when proof is required.</param>
 32    /// <param name="useStore">The use store that consumes grant uses, required when a use check is required.</param>
 33    /// <param name="cancellationToken">A token used to observe cancellation.</param>
 34    /// <returns>
 35    /// A result whose <see cref="CapabilityGrantValidationResult.Action" /> states whether the host should allow,
 36    /// deny, defer, escalate, or require acknowledgment.
 37    /// </returns>
 38    /// <exception cref="ArgumentNullException"><paramref name="signedGrant" /> is <see langword="null" />.</exception>
 39    /// <exception cref="OperationCanceledException"><paramref name="cancellationToken" /> is cancelled.</exception>
 40    public static async ValueTask<CapabilityGrantValidationResult> ValidateAsync(
 41        SignedGovernanceArtifact<CapabilityGrant> signedGrant,
 42        CapabilityGrantValidationOptions? options = null,
 43        IGovernanceSignatureVerificationService? verificationService = null,
 44        ICapabilityGrantUseStore? useStore = null,
 45        CancellationToken cancellationToken = default)
 46    {
 13447        ArgumentNullException.ThrowIfNull(signedGrant);
 13348        cancellationToken.ThrowIfCancellationRequested();
 49
 13250        CapabilityGrant grant = signedGrant.Artifact;
 51
 52        // The previous default built permissive options: no proof, no use check, and no issuer, audience, or scope
 53        // expectations, so the simplest call was the least safe one and returned Valid for anything unexpired. Validati
 54        // now requires the caller to state what it is validating against.
 13255        if (options is null)
 56        {
 157            return CapabilityGrantValidationResult.Failed(
 158                grant,
 159                CapabilityGrantValidationCategory.Failed,
 160                VerificationPolicyAction.Deny,
 161                "capability.validation-options-required",
 162                "Capability grant validation requires explicit options describing what the grant is validated against.")
 63        }
 64
 13165        CapabilityGrantValidationOptions effectiveOptions = options;
 13166        DateTimeOffset validationUtc = (effectiveOptions.ValidationUtc ?? DateTimeOffset.UtcNow).ToUniversalTime();
 67
 13168        if (effectiveOptions.RequireProof)
 69        {
 8270            CapabilityGrantValidationResult? proofResult = await ValidateProofAsync(
 8271                signedGrant,
 8272                grant,
 8273                effectiveOptions,
 8274                verificationService,
 8275                cancellationToken).ConfigureAwait(false);
 76
 8277            if (proofResult is not null)
 78            {
 4279                return proofResult;
 80            }
 81        }
 82
 8983        CapabilityGrantValidationResult? metadataResult = ValidateMetadata(grant, effectiveOptions, validationUtc);
 84
 8985        if (metadataResult is not null)
 86        {
 4087            return metadataResult;
 88        }
 89
 4990        if (effectiveOptions.RequireUseCheck)
 91        {
 3992            CapabilityGrantValidationResult? useResult = await ValidateUseAsync(
 3993                grant,
 3994                effectiveOptions,
 3995                useStore,
 3996                validationUtc,
 3997                cancellationToken).ConfigureAwait(false);
 98
 3899            if (useResult is not null)
 100            {
 17101                return useResult;
 102            }
 103        }
 104
 31105        return CapabilityGrantValidationResult.Valid(grant);
 131106    }
 107
 108    private static async ValueTask<CapabilityGrantValidationResult?> ValidateProofAsync(
 109        SignedGovernanceArtifact<CapabilityGrant> signedGrant,
 110        CapabilityGrant grant,
 111        CapabilityGrantValidationOptions options,
 112        IGovernanceSignatureVerificationService? verificationService,
 113        CancellationToken cancellationToken)
 114    {
 82115        if (verificationService is null)
 116        {
 3117            return CapabilityGrantValidationResult.Failed(
 3118                grant,
 3119                CapabilityGrantValidationCategory.MissingProof,
 3120                VerificationPolicyAction.Deny,
 3121                "capability.proof-verifier-missing",
 3122                "A proof verifier is required for this validation context.");
 123        }
 124
 79125        CapabilityGrantValidationResult? bindingResult = ValidateProofBinding(signedGrant, grant, options);
 126
 79127        if (bindingResult is not null)
 128        {
 4129            return bindingResult;
 130        }
 131
 75132        var verificationContext = VerificationPolicyContext.Create(
 75133            purpose: CanonicalArtifactTypes.CapabilityGrant,
 75134            expectedKeyId: options.ExpectedProofKeyId,
 75135            expectedKeyVersion: options.ExpectedProofKeyVersion,
 75136            expectedPolicyVersion: options.ExpectedProofPolicyVersion,
 75137            expectedPolicyHash: options.ExpectedProofPolicyHash,
 75138            requiredProvider: options.RequiredProofProvider,
 75139            requiredHashAlgorithm: options.RequiredProofHashAlgorithm);
 140
 75141        VerificationPolicyOutcome verificationOutcome = await GovernanceArtifactVerifier.VerifyAsync(
 75142            signedGrant,
 75143            verificationService,
 75144            context: verificationContext,
 75145            cancellationToken: cancellationToken).ConfigureAwait(false);
 146
 75147        if (verificationOutcome.ShouldAllow)
 148        {
 40149            return null;
 150        }
 151
 152        // A grant whose signature was stripped is not a grant awaiting acknowledgment. Where proof is required, absent
 153        // proof denies, rather than inviting a host that treats RequireAcknowledgment as "proceed after a click" to
 154        // continue on a grant carrying no proof at all. The default verification policy now also denies a missing
 155        // signature; this override is retained so grant validation cannot be weakened by a future default change.
 35156        VerificationPolicyAction action = verificationOutcome.Category is SignatureVerificationCategory.MissingSignature
 35157            ? VerificationPolicyAction.Deny
 35158            : verificationOutcome.Action;
 159
 35160        return CapabilityGrantValidationResult.Failed(
 35161            grant,
 35162            MapVerificationCategory(verificationOutcome.Category),
 35163            action,
 35164            verificationOutcome.FailureCode ?? "capability.proof-invalid",
 35165            verificationOutcome.FailureMessage);
 82166    }
 167
 168    /// <summary>
 169    /// Binds the signed proof to the grant being validated by rebuilding the canonical payload from the grant itself.
 170    /// </summary>
 171    /// <remarks>
 172    /// Signature verification establishes that a signature covers a hash. It does not establish that the hash describes
 173    /// grant whose fields are about to be evaluated. Rebuilding the payload from <see cref="SignedGovernanceArtifact{TA
 174    /// and comparing hashes closes that gap, and the artifact descriptors are asserted so a proof issued for another ar
 175    /// type or token identifier cannot be presented alongside this grant.
 176    /// </remarks>
 177    private static CapabilityGrantValidationResult? ValidateProofBinding(
 178        SignedGovernanceArtifact<CapabilityGrant> signedGrant,
 179        CapabilityGrant grant,
 180        CapabilityGrantValidationOptions options)
 181    {
 79182        if (!string.Equals(signedGrant.ArtifactType, CanonicalArtifactTypes.CapabilityGrant, StringComparison.Ordinal))
 183        {
 1184            return CapabilityGrantValidationResult.Failed(
 1185                grant,
 1186                CapabilityGrantValidationCategory.InvalidProof,
 1187                VerificationPolicyAction.Deny,
 1188                "capability.proof-artifact-type-mismatch",
 1189                "The signed artifact type is not a capability token grant.");
 190        }
 191
 78192        if (!string.Equals(signedGrant.ArtifactId, grant.TokenId, StringComparison.Ordinal))
 193        {
 1194            return CapabilityGrantValidationResult.Failed(
 1195                grant,
 1196                CapabilityGrantValidationCategory.InvalidProof,
 1197                VerificationPolicyAction.Deny,
 1198                "capability.proof-artifact-id-mismatch",
 1199                "The signed artifact identifier does not match the grant token identifier.");
 200        }
 201
 202        CanonicalPayloadHash recomputedHash;
 203
 204        try
 205        {
 77206            recomputedHash = CanonicalPayloadHasher.ComputeHash(
 77207                CanonicalPayloadBuilder.ForCapabilityGrant(grant, options.ProofPayloadOptions),
 77208                signedGrant.HashAlgorithm);
 77209        }
 0210        catch (NotSupportedException)
 211        {
 0212            return CapabilityGrantValidationResult.Failed(
 0213                grant,
 0214                CapabilityGrantValidationCategory.InvalidProof,
 0215                VerificationPolicyAction.Deny,
 0216                "capability.proof-hash-algorithm-unsupported",
 0217                "The grant canonical payload cannot be rebuilt with the built-in hasher, so the proof is not bound to th
 218        }
 219
 77220        return string.Equals(recomputedHash.HashValue, signedGrant.CanonicalHash.HashValue, StringComparison.Ordinal)
 77221            ? null
 77222            : CapabilityGrantValidationResult.Failed(
 77223                grant,
 77224                CapabilityGrantValidationCategory.InvalidProof,
 77225                VerificationPolicyAction.Deny,
 77226                "capability.proof-content-mismatch",
 77227                "The grant does not hash to the signed canonical hash value.");
 0228    }
 229
 230#pragma warning disable IDE0046 // Preserve explicit ordered guard clauses for auditability.
 231    private static CapabilityGrantValidationResult? ValidateMetadata(
 232        CapabilityGrant grant,
 233        CapabilityGrantValidationOptions options,
 234        DateTimeOffset validationUtc)
 235    {
 89236        if (options.Issuer is not null
 89237            && !string.Equals(options.Issuer, grant.Issuer, StringComparison.Ordinal))
 238        {
 3239            return CapabilityGrantValidationResult.Failed(
 3240                grant,
 3241                CapabilityGrantValidationCategory.WrongIssuer,
 3242                VerificationPolicyAction.Deny,
 3243                "capability.issuer-mismatch");
 244        }
 245
 86246        if (options.Audience is not null
 86247            && !string.Equals(options.Audience, grant.Audience, StringComparison.Ordinal))
 248        {
 2249            return CapabilityGrantValidationResult.Failed(
 2250                grant,
 2251                CapabilityGrantValidationCategory.WrongAudience,
 2252                VerificationPolicyAction.Deny,
 2253                "capability.audience-mismatch");
 254        }
 255
 84256        if (options.ExpectedSubjectId is not null
 84257            && !string.Equals(options.ExpectedSubjectId, grant.SubjectId, StringComparison.Ordinal))
 258        {
 7259            return CapabilityGrantValidationResult.Failed(
 7260                grant,
 7261                CapabilityGrantValidationCategory.SubjectMismatch,
 7262                VerificationPolicyAction.Deny,
 7263                "capability.subject-mismatch");
 264        }
 265
 77266        if (options.ExpectedOperationName is not null
 77267            && !string.Equals(options.ExpectedOperationName, grant.OperationName, StringComparison.Ordinal))
 268        {
 4269            return CapabilityGrantValidationResult.Failed(
 4270                grant,
 4271                CapabilityGrantValidationCategory.OperationMismatch,
 4272                VerificationPolicyAction.Deny,
 4273                "capability.operation-mismatch");
 274        }
 275
 73276        if (IsNotYetValid(grant, validationUtc, options.AllowedClockSkew))
 277        {
 4278            return CapabilityGrantValidationResult.Failed(
 4279                grant,
 4280                CapabilityGrantValidationCategory.NotYetValid,
 4281                VerificationPolicyAction.Defer,
 4282                "capability.not-yet-valid");
 283        }
 284
 69285        if (IsExpired(grant, validationUtc, options.AllowedClockSkew))
 286        {
 5287            return CapabilityGrantValidationResult.Failed(
 5288                grant,
 5289                CapabilityGrantValidationCategory.Expired,
 5290                VerificationPolicyAction.Deny,
 5291                "capability.expired");
 292        }
 293
 64294        if (options.Scopes.Count > 0
 64295            && !ContainsRequiredScopes(grant.Scopes, options.Scopes))
 296        {
 4297            return CapabilityGrantValidationResult.Failed(
 4298                grant,
 4299                CapabilityGrantValidationCategory.WrongScope,
 4300                VerificationPolicyAction.Deny,
 4301                "capability.scope-missing");
 302        }
 303
 60304        if ((options.PolicyVersion is not null
 60305                && !string.Equals(options.PolicyVersion, grant.PolicyVersion, StringComparison.Ordinal))
 60306            || (options.PolicyHash is not null
 60307                && !string.Equals(options.PolicyHash, grant.PolicyHash, StringComparison.Ordinal)))
 308        {
 3309            return CapabilityGrantValidationResult.Failed(
 3310                grant,
 3311                CapabilityGrantValidationCategory.PolicyMismatch,
 3312                VerificationPolicyAction.Deny,
 3313                "capability.policy-mismatch");
 314        }
 315
 57316        if (options.RequireAcknowledgmentReference && !grant.HasAcknowledgmentReference)
 317        {
 2318            return CapabilityGrantValidationResult.Failed(
 2319                grant,
 2320                CapabilityGrantValidationCategory.MissingAcknowledgmentReference,
 2321                VerificationPolicyAction.RequireAcknowledgment,
 2322                "capability.acknowledgment-missing");
 323        }
 324
 55325        if (options.AcknowledgmentId is not null
 55326            && !string.Equals(options.AcknowledgmentId, grant.AcknowledgmentId, StringComparison.Ordinal))
 327        {
 1328            return CapabilityGrantValidationResult.Failed(
 1329                grant,
 1330                CapabilityGrantValidationCategory.AcknowledgmentMismatch,
 1331                VerificationPolicyAction.Deny,
 1332                "capability.acknowledgment-mismatch");
 333        }
 334
 54335        if (options.HandshakeId is not null
 54336            && !string.Equals(options.HandshakeId, grant.HandshakeId, StringComparison.Ordinal))
 337        {
 1338            return CapabilityGrantValidationResult.Failed(
 1339                grant,
 1340                CapabilityGrantValidationCategory.HandshakeMismatch,
 1341                VerificationPolicyAction.Deny,
 1342                "capability.handshake-mismatch");
 343        }
 344
 53345        if (options.GatewayBinding is not null
 53346            && !string.Equals(options.GatewayBinding, grant.GatewayBinding, StringComparison.Ordinal))
 347        {
 2348            return CapabilityGrantValidationResult.Failed(
 2349                grant,
 2350                CapabilityGrantValidationCategory.GatewayMismatch,
 2351                VerificationPolicyAction.Deny,
 2352                "capability.gateway-mismatch");
 353        }
 354
 51355        if (options.ResourceBinding is not null
 51356            && !string.Equals(options.ResourceBinding, grant.ResourceBinding, StringComparison.Ordinal))
 357        {
 2358            return CapabilityGrantValidationResult.Failed(
 2359                grant,
 2360                CapabilityGrantValidationCategory.ResourceMismatch,
 2361                VerificationPolicyAction.Deny,
 2362                "capability.resource-mismatch");
 363        }
 364
 49365        return null;
 366    }
 367#pragma warning restore IDE0046
 368
 369    private static bool IsNotYetValid(CapabilityGrant grant, DateTimeOffset validationUtc, TimeSpan allowedClockSkew)
 370    {
 73371        return grant.NotBeforeUtc.HasValue
 73372            && grant.NotBeforeUtc.Value > validationUtc
 73373            && grant.NotBeforeUtc.Value - validationUtc > allowedClockSkew;
 374    }
 375
 376    private static bool IsExpired(CapabilityGrant grant, DateTimeOffset validationUtc, TimeSpan allowedClockSkew)
 377    {
 69378        return validationUtc >= grant.ExpiresUtc
 69379            && validationUtc - grant.ExpiresUtc >= allowedClockSkew;
 380    }
 381
 382    private static async ValueTask<CapabilityGrantValidationResult?> ValidateUseAsync(
 383        CapabilityGrant grant,
 384        CapabilityGrantValidationOptions options,
 385        ICapabilityGrantUseStore? useStore,
 386        DateTimeOffset validationUtc,
 387        CancellationToken cancellationToken)
 388    {
 39389        if (useStore is null)
 390        {
 3391            return CapabilityGrantValidationResult.Failed(grant, CapabilityGrantValidationCategory.ReplayStoreUnavailabl
 392        }
 393
 394        // A limit the caller supplies is local policy; a limit the issuer bound into the signed payload is authority.
 395        // Taking the narrower of the two lets a relying party tighten the limit but never widen what was issued.
 36396        int effectiveMaxUseCount = grant.MaxUseCount.HasValue
 36397            ? Math.Min(grant.MaxUseCount.Value, options.MaxUseCount)
 36398            : options.MaxUseCount;
 399
 36400        CapabilityGrantUseResult result = await useStore
 36401            .TryConsumeAsync(grant, effectiveMaxUseCount, validationUtc, cancellationToken)
 36402            .ConfigureAwait(false);
 403
 35404        return result.State switch
 35405        {
 1406            GrantUseState.Unspecified => CapabilityGrantValidationResult.Failed(grant, CapabilityGrantValidationCategory
 21407            GrantUseState.Accepted => null,
 5408            GrantUseState.UseLimitExceeded => CapabilityGrantValidationResult.Failed(grant, CapabilityGrantValidationCat
 2409            GrantUseState.Stopped => CapabilityGrantValidationResult.Failed(grant, CapabilityGrantValidationCategory.Rev
 2410            GrantUseState.Cancelled => CapabilityGrantValidationResult.Failed(grant, CapabilityGrantValidationCategory.C
 3411            GrantUseState.Unavailable => CapabilityGrantValidationResult.Failed(grant, CapabilityGrantValidationCategory
 1412            _ => CapabilityGrantValidationResult.Failed(grant, CapabilityGrantValidationCategory.Failed, VerificationPol
 35413        };
 38414    }
 415
 416    private static bool ContainsRequiredScopes(IReadOnlyList<string> actualScopes, IReadOnlyList<string> requiredScopes)
 417    {
 58418        HashSet<string> actualScopeSet = new(actualScopes, StringComparer.Ordinal);
 419
 230420        foreach (string requiredScope in requiredScopes)
 421        {
 59422            if (!actualScopeSet.Contains(requiredScope))
 423            {
 4424                return false;
 425            }
 426        }
 427
 54428        return true;
 4429    }
 430
 431    private static CapabilityGrantValidationCategory MapVerificationCategory(SignatureVerificationCategory category)
 432    {
 35433        return category switch
 35434        {
 0435            SignatureVerificationCategory.Unspecified => CapabilityGrantValidationCategory.Failed,
 1436            SignatureVerificationCategory.MissingSignature => CapabilityGrantValidationCategory.MissingProof,
 0437            SignatureVerificationCategory.Valid => CapabilityGrantValidationCategory.Valid,
 20438            SignatureVerificationCategory.InvalidSignature => CapabilityGrantValidationCategory.InvalidProof,
 1439            SignatureVerificationCategory.HashMismatch => CapabilityGrantValidationCategory.InvalidProof,
 2440            SignatureVerificationCategory.RevokedKey => CapabilityGrantValidationCategory.Revoked,
 2441            SignatureVerificationCategory.UntrustedKey => CapabilityGrantValidationCategory.InvalidProof,
 3442            SignatureVerificationCategory.UntrustedSigningContext => CapabilityGrantValidationCategory.InvalidProof,
 2443            SignatureVerificationCategory.ProviderUnavailable => CapabilityGrantValidationCategory.Failed,
 1444            SignatureVerificationCategory.UnknownKeyVersion => CapabilityGrantValidationCategory.Failed,
 1445            SignatureVerificationCategory.CanonicalizationMismatch => CapabilityGrantValidationCategory.InvalidProof,
 1446            SignatureVerificationCategory.UnsupportedAlgorithm => CapabilityGrantValidationCategory.InvalidProof,
 1447            SignatureVerificationCategory.Failed => CapabilityGrantValidationCategory.Failed,
 0448            _ => CapabilityGrantValidationCategory.Failed
 35449        };
 450    }
 451}