| | | 1 | | using AsiBackbone.AspNetCore.Endpoints; |
| | | 2 | | using Microsoft.AspNetCore.Http; |
| | | 3 | | |
| | | 4 | | namespace AsiBackbone.AspNetCore.CapabilityGrants; |
| | | 5 | | |
| | | 6 | | /// <summary> |
| | | 7 | | /// Defines what a capability grant's <see cref="Core.CapabilityGrants.CapabilityGrant.ResourceBinding" /> covers for th |
| | | 8 | | /// current request. |
| | | 9 | | /// </summary> |
| | | 10 | | /// <remarks> |
| | | 11 | | /// <para> |
| | | 12 | | /// The provider turns the parts of a request that a grant authorizes, such as form fields, a JSON body, or route values |
| | | 13 | | /// into a binding value. <see cref="SignedCapabilityGrantEndpointValidator" /> requires the grant's resource binding to |
| | | 14 | | /// equal that value exactly, so the issuer must compute the binding with the same rules when it issues the grant. |
| | | 15 | | /// </para> |
| | | 16 | | /// <para> |
| | | 17 | | /// A provider that cannot bind the request returns <see cref="CapabilityGrantRequestBinding.Unavailable" />, which deni |
| | | 18 | | /// the request. Returning <see cref="CapabilityGrantRequestBinding.None" /> states that the request has no bound |
| | | 19 | | /// resource; the validator then accepts only grants that carry no resource binding. |
| | | 20 | | /// </para> |
| | | 21 | | /// </remarks> |
| | | 22 | | public interface ICapabilityGrantRequestBindingProvider |
| | | 23 | | { |
| | | 24 | | /// <summary> |
| | | 25 | | /// Resolves the resource binding expected for the current request. |
| | | 26 | | /// </summary> |
| | | 27 | | /// <param name="httpContext">The current HTTP context.</param> |
| | | 28 | | /// <param name="descriptor">The endpoint governance descriptor.</param> |
| | | 29 | | /// <param name="cancellationToken">A token that can cancel binding resolution.</param> |
| | | 30 | | /// <returns>The resolved binding.</returns> |
| | | 31 | | ValueTask<CapabilityGrantRequestBinding> ResolveAsync( |
| | | 32 | | HttpContext httpContext, |
| | | 33 | | EndpointGovernanceDescriptor descriptor, |
| | | 34 | | CancellationToken cancellationToken = default); |
| | | 35 | | } |
| | | 36 | | |
| | | 37 | | /// <summary> |
| | | 38 | | /// Represents the resource binding a request requires of a capability grant. |
| | | 39 | | /// </summary> |
| | | 40 | | public sealed class CapabilityGrantRequestBinding |
| | | 41 | | { |
| | 47 | 42 | | private CapabilityGrantRequestBinding(bool isAvailable, string? value, string? failureMessage) |
| | | 43 | | { |
| | 47 | 44 | | IsAvailable = isAvailable; |
| | 47 | 45 | | Value = value; |
| | 47 | 46 | | FailureMessage = failureMessage; |
| | 47 | 47 | | } |
| | | 48 | | |
| | | 49 | | /// <summary> |
| | | 50 | | /// Gets a binding stating that the request has no bound resource. |
| | | 51 | | /// </summary> |
| | | 52 | | public static CapabilityGrantRequestBinding None { get; } = new(isAvailable: true, value: null, failureMessage: null |
| | | 53 | | |
| | | 54 | | /// <summary> |
| | | 55 | | /// Gets a value indicating whether the request could be bound. |
| | | 56 | | /// </summary> |
| | | 57 | | public bool IsAvailable { get; } |
| | | 58 | | |
| | | 59 | | /// <summary> |
| | | 60 | | /// Gets the binding value the grant must carry, or <see langword="null" /> when the request has no bound resource. |
| | | 61 | | /// </summary> |
| | | 62 | | public string? Value { get; } |
| | | 63 | | |
| | | 64 | | /// <summary> |
| | | 65 | | /// Gets a message describing why the request could not be bound, when it could not. |
| | | 66 | | /// </summary> |
| | | 67 | | public string? FailureMessage { get; } |
| | | 68 | | |
| | | 69 | | /// <summary> |
| | | 70 | | /// Creates a binding the grant's resource binding must equal. |
| | | 71 | | /// </summary> |
| | | 72 | | /// <param name="value">The binding value.</param> |
| | | 73 | | /// <returns>The binding.</returns> |
| | | 74 | | /// <exception cref="ArgumentException"><paramref name="value" /> is null, empty, or whitespace.</exception> |
| | | 75 | | public static CapabilityGrantRequestBinding Bound(string value) |
| | | 76 | | { |
| | 43 | 77 | | ArgumentException.ThrowIfNullOrWhiteSpace(value); |
| | 42 | 78 | | return new CapabilityGrantRequestBinding(isAvailable: true, value.Trim(), failureMessage: null); |
| | | 79 | | } |
| | | 80 | | |
| | | 81 | | /// <summary> |
| | | 82 | | /// Creates a result stating that the request cannot be bound, which denies it. |
| | | 83 | | /// </summary> |
| | | 84 | | /// <param name="failureMessage">A message describing why the request cannot be bound. It must not contain request c |
| | | 85 | | /// <returns>The unavailable binding.</returns> |
| | | 86 | | /// <exception cref="ArgumentException"><paramref name="failureMessage" /> is null, empty, or whitespace.</exception |
| | | 87 | | public static CapabilityGrantRequestBinding Unavailable(string failureMessage) |
| | | 88 | | { |
| | 5 | 89 | | ArgumentException.ThrowIfNullOrWhiteSpace(failureMessage); |
| | 4 | 90 | | return new CapabilityGrantRequestBinding(isAvailable: false, value: null, failureMessage.Trim()); |
| | | 91 | | } |
| | | 92 | | } |