< Summary

Information
Class: AsiBackbone.Core.CapabilityGrants.CapabilityGrantValidationResult
Assembly: AsiBackbone.Core
File(s): /home/runner/work/AsiBackbone/AsiBackbone/src/AsiBackbone.Core/CapabilityGrants/CapabilityGrantValidationResult.cs
Line coverage
97%
Covered lines: 67
Uncovered lines: 2
Coverable lines: 69
Total lines: 190
Line coverage: 97.1%
Branch coverage
90%
Covered branches: 9
Total branches: 10
Branch coverage: 90%
Method coverage

Feature is only available for sponsors

Upgrade to PRO version

Metrics

MethodBranch coverage Crap Score Cyclomatic complexity Line coverage
.cctor()100%210%
.ctor(...)100%44100%
get_ShouldAllow()100%11100%
Valid(...)100%11100%
Failed(...)100%11100%
BuildSafeMetadata(...)50%22100%
AddIfPresent(...)100%22100%
NormalizeOptional(...)100%22100%

File(s)

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

#LineLine coverage
 1using System.Collections.ObjectModel;
 2using AsiBackbone.Core.Signing;
 3
 4namespace AsiBackbone.Core.CapabilityGrants;
 5
 6/// <summary>
 7/// Represents the outcome of validating a capability grant, including the policy action the host should take.
 8/// </summary>
 9/// <remarks>
 10/// Hosts should gate execution on <see cref="ShouldAllow" /> rather than <see cref="IsValid" /> alone, and act on
 11/// <see cref="Action" /> for failed results, because some failures defer or require acknowledgment instead of denying.
 12/// </remarks>
 13public sealed class CapabilityGrantValidationResult
 14{
 015    private static readonly IReadOnlyDictionary<string, string> EmptyMetadata =
 016        new ReadOnlyDictionary<string, string>(new Dictionary<string, string>(StringComparer.Ordinal));
 17
 23718    private CapabilityGrantValidationResult(
 23719        bool isValid,
 23720        CapabilityGrantValidationCategory category,
 23721        VerificationPolicyAction action,
 23722        string status,
 23723        string? failureCode,
 23724        string? failureMessage,
 23725        string tokenId,
 23726        IReadOnlyDictionary<string, string> safeMetadata)
 27    {
 23728        ArgumentException.ThrowIfNullOrWhiteSpace(status);
 23729        ArgumentException.ThrowIfNullOrWhiteSpace(tokenId);
 30
 23731        if (!Enum.IsDefined(category))
 32        {
 133            throw new ArgumentOutOfRangeException(nameof(category), category, "Validation category must be defined.");
 34        }
 35
 23636        if (!Enum.IsDefined(action))
 37        {
 138            throw new ArgumentOutOfRangeException(nameof(action), action, "Validation action must be defined.");
 39        }
 40
 23541        IsValid = isValid;
 23542        Category = category;
 23543        Action = action;
 23544        Status = status.Trim();
 23545        FailureCode = NormalizeOptional(failureCode);
 23546        FailureMessage = NormalizeOptional(failureMessage);
 23547        TokenId = tokenId.Trim();
 23548        SafeMetadata = safeMetadata;
 23549    }
 50
 51    /// <summary>
 52    /// Gets a value indicating whether the grant satisfied every configured validation check.
 53    /// </summary>
 54    public bool IsValid { get; }
 55
 56    /// <summary>
 57    /// Gets the validation category that describes why the grant passed or failed.
 58    /// </summary>
 59    public CapabilityGrantValidationCategory Category { get; }
 60
 61    /// <summary>
 62    /// Gets the policy action the host should take for this result.
 63    /// </summary>
 64    public VerificationPolicyAction Action { get; }
 65
 66    /// <summary>
 67    /// Gets a value indicating whether the host may proceed with the governed operation.
 68    /// </summary>
 7869    public bool ShouldAllow => Action is VerificationPolicyAction.Allow;
 70
 71    /// <summary>
 72    /// Gets the result status, either <c>Valid</c> or <c>Failed</c>.
 73    /// </summary>
 74    public string Status { get; }
 75
 76    /// <summary>
 77    /// Gets the machine-readable failure code, such as <c>capability.expired</c>, when validation failed.
 78    /// </summary>
 79    public string? FailureCode { get; }
 80
 81    /// <summary>
 82    /// Gets the human-readable failure message, when one was supplied.
 83    /// </summary>
 84    public string? FailureMessage { get; }
 85
 86    /// <summary>
 87    /// Gets the token identifier of the validated grant.
 88    /// </summary>
 89    public string TokenId { get; }
 90
 91    /// <summary>
 92    /// Gets non-secret grant and outcome metadata, such as issuer, audience, policy action, and failure code, that is
 93    /// safe to log or attach to audit records.
 94    /// </summary>
 95    public IReadOnlyDictionary<string, string> SafeMetadata { get; }
 96
 97    /// <summary>
 98    /// Creates a successful result that allows the governed operation.
 99    /// </summary>
 100    /// <param name="grant">The grant that passed validation.</param>
 101    /// <returns>A valid result with <see cref="VerificationPolicyAction.Allow" />.</returns>
 102    /// <exception cref="ArgumentNullException"><paramref name="grant" /> is <see langword="null" />.</exception>
 103    public static CapabilityGrantValidationResult Valid(CapabilityGrant grant)
 104    {
 34105        ArgumentNullException.ThrowIfNull(grant);
 106
 33107        return new CapabilityGrantValidationResult(
 33108            true,
 33109            CapabilityGrantValidationCategory.Valid,
 33110            VerificationPolicyAction.Allow,
 33111            "Valid",
 33112            null,
 33113            null,
 33114            grant.TokenId,
 33115            BuildSafeMetadata(grant, CapabilityGrantValidationCategory.Valid, VerificationPolicyAction.Allow, null));
 116    }
 117
 118    /// <summary>
 119    /// Creates a failed result with the category and policy action the host should apply.
 120    /// </summary>
 121    /// <param name="grant">The grant that failed validation.</param>
 122    /// <param name="category">The validation category that describes the failure.</param>
 123    /// <param name="action">The policy action the host should take, such as deny, defer, or require acknowledgment.</pa
 124    /// <param name="failureCode">The machine-readable failure code.</param>
 125    /// <param name="failureMessage">An optional human-readable failure message.</param>
 126    /// <returns>A failed result.</returns>
 127    /// <exception cref="ArgumentNullException"><paramref name="grant" /> or <paramref name="failureCode" /> is <see lan
 128    /// <exception cref="ArgumentException"><paramref name="failureCode" /> is empty or whitespace.</exception>
 129    /// <exception cref="ArgumentOutOfRangeException"><paramref name="category" /> or <paramref name="action" /> is not 
 130    public static CapabilityGrantValidationResult Failed(
 131        CapabilityGrant grant,
 132        CapabilityGrantValidationCategory category,
 133        VerificationPolicyAction action,
 134        string failureCode,
 135        string? failureMessage = null)
 136    {
 206137        ArgumentNullException.ThrowIfNull(grant);
 205138        ArgumentException.ThrowIfNullOrWhiteSpace(failureCode);
 139
 204140        return new CapabilityGrantValidationResult(
 204141            false,
 204142            category,
 204143            action,
 204144            "Failed",
 204145            failureCode,
 204146            failureMessage,
 204147            grant.TokenId,
 204148            BuildSafeMetadata(grant, category, action, failureCode));
 149    }
 150
 151    private static IReadOnlyDictionary<string, string> BuildSafeMetadata(
 152        CapabilityGrant grant,
 153        CapabilityGrantValidationCategory category,
 154        VerificationPolicyAction action,
 155        string? failureCode)
 156    {
 237157        Dictionary<string, string> metadata = new(StringComparer.Ordinal)
 237158        {
 237159            ["audience"] = grant.Audience,
 237160            ["category"] = category.ToString(),
 237161            ["grant_id"] = grant.TokenId,
 237162            ["issuer"] = grant.Issuer,
 237163            ["policy_action"] = action.ToString()
 237164        };
 165
 237166        AddIfPresent(metadata, "acknowledgment_id", grant.AcknowledgmentId);
 237167        AddIfPresent(metadata, "failure_code", failureCode);
 237168        AddIfPresent(metadata, "handshake_id", grant.HandshakeId);
 237169        AddIfPresent(metadata, "policy_hash", grant.PolicyHash);
 237170        AddIfPresent(metadata, "policy_version", grant.PolicyVersion);
 237171        AddIfPresent(metadata, "resource_binding", grant.ResourceBinding);
 172
 237173        return metadata.Count == 0
 237174            ? EmptyMetadata
 237175            : new ReadOnlyDictionary<string, string>(metadata);
 176    }
 177
 178    private static void AddIfPresent(Dictionary<string, string> metadata, string key, string? value)
 179    {
 1422180        if (!string.IsNullOrWhiteSpace(value))
 181        {
 982182            metadata[key] = value.Trim();
 183        }
 1422184    }
 185
 186    private static string? NormalizeOptional(string? value)
 187    {
 470188        return string.IsNullOrWhiteSpace(value) ? null : value.Trim();
 189    }
 190}