Class CapabilityGrantValidationOptions
- Namespace
- AsiBackbone.Core.CapabilityGrants
- Assembly
- AsiBackbone.Core.dll
Describes the expectations a capability grant is validated against by CapabilityGrantValidator.
public sealed class CapabilityGrantValidationOptions
- Inheritance
-
CapabilityGrantValidationOptions
- Inherited Members
Remarks
Each optional expectation is checked only when it is set; string comparisons are ordinal, and blank values are treated as absent. Choose a factory that matches the validation context: CreateBoundExecutionBoundary(CapabilityGrantBindingExpectations, string?, string?, IEnumerable<string>?, DateTimeOffset?, string?, string?, string?, string?, string?, string?, bool, bool, int, TimeSpan, string?, string?, string?, string?, string?, string?, CanonicalPayloadOptions?) for an execution boundary that requires proof and binds the grant to the authenticated subject, CreateMetadataValidation(string?, string?, IEnumerable<string>?, DateTimeOffset?, string?, string?, string?, string?, string?, string?, bool, TimeSpan) for proof-free inspection of grant metadata, and Create(string?, string?, IEnumerable<string>?, DateTimeOffset?, string?, string?, string?, string?, string?, string?, bool, bool, bool, int, TimeSpan, string?, string?, string?, string?, string?, string?, CanonicalPayloadOptions?) for a fully custom profile.
Requiring proof or a use check without an audience expectation is rejected, because proof alone does not establish that the grant was issued for this audience.
Properties
AcknowledgmentId
Gets the acknowledgment identifier the grant must reference, when an acknowledgment expectation is configured.
public string? AcknowledgmentId { get; }
Property Value
AllowedClockSkew
Gets the non-negative tolerance applied to the grant not-before and expiry times.
public TimeSpan AllowedClockSkew { get; }
Property Value
Audience
Gets the audience the grant must name, when an audience expectation is configured.
public string? Audience { get; }
Property Value
Remarks
An audience is required whenever RequireProof or RequireUseCheck is set.
ExpectedOperationName
Gets the requested operation that the grant must identify, when operation binding is configured.
public string? ExpectedOperationName { get; }
Property Value
ExpectedProofKeyId
Gets the signing key identifier the grant proof must use, when configured.
public string? ExpectedProofKeyId { get; }
Property Value
ExpectedProofKeyVersion
Gets the signing key version the grant proof must use, when configured.
public string? ExpectedProofKeyVersion { get; }
Property Value
ExpectedProofPolicyHash
Gets the policy hash the grant proof must carry, when configured.
public string? ExpectedProofPolicyHash { get; }
Property Value
ExpectedProofPolicyVersion
Gets the policy version the grant proof must carry, when configured.
public string? ExpectedProofPolicyVersion { get; }
Property Value
ExpectedSubjectId
Gets the authenticated subject that the grant must identify, when subject binding is configured.
public string? ExpectedSubjectId { get; }
Property Value
GatewayBinding
Gets the gateway binding the grant must carry, when a gateway expectation is configured.
public string? GatewayBinding { get; }
Property Value
HandshakeId
Gets the liability handshake identifier the grant must reference, when a handshake expectation is configured.
public string? HandshakeId { get; }
Property Value
Issuer
Gets the issuer the grant must name, when an issuer expectation is configured.
public string? Issuer { get; }
Property Value
MaxUseCount
Gets the maximum use count allowed by this validation context.
public int MaxUseCount { get; }
Property Value
Remarks
When the grant carries its own signed use limit, the narrower of the two applies, so local policy can tighten but never widen what was issued.
PolicyHash
Gets the policy hash the grant must carry, when a policy hash expectation is configured.
public string? PolicyHash { get; }
Property Value
PolicyVersion
Gets the policy version the grant must carry, when a policy version expectation is configured.
public string? PolicyVersion { get; }
Property Value
ProofPayloadOptions
Gets the canonical payload options used to rebuild the grant payload when proof is required.
public CanonicalPayloadOptions? ProofPayloadOptions { get; }
Property Value
Remarks
Proof validation recomputes the canonical payload from the grant and compares its hash to the signed hash, so these options must match the options the issuer signed with. The default options bind every grant field except metadata, whose allow-list is empty until a host opts a key in.
RequireAcknowledgmentReference
Gets a value indicating whether the grant must reference a handshake acknowledgment.
public bool RequireAcknowledgmentReference { get; }
Property Value
Remarks
A grant without an acknowledgment reference fails with RequireAcknowledgment.
RequireProof
Gets a value indicating whether the grant must carry a signature that verifies and is bound to the grant content.
public bool RequireProof { get; }
Property Value
Remarks
When set, validation requires an IGovernanceSignatureVerificationService and rebuilds the canonical payload from the grant using ProofPayloadOptions.
RequireUseCheck
Gets a value indicating whether validation must consume a grant use through an ICapabilityGrantUseStore.
public bool RequireUseCheck { get; }
Property Value
RequiredProofHashAlgorithm
Gets the hash algorithm the grant proof must use, when configured.
public string? RequiredProofHashAlgorithm { get; }
Property Value
RequiredProofProvider
Gets the signing provider that must have produced the grant proof, when configured.
public string? RequiredProofProvider { get; }
Property Value
ResourceBinding
Gets the resource binding the grant must carry, when a resource expectation is configured.
public string? ResourceBinding { get; }
Property Value
Scopes
Gets the scopes the grant must contain, trimmed, de-duplicated, and sorted ordinally.
public IReadOnlyList<string> Scopes { get; }
Property Value
Remarks
The grant may carry additional scopes. An empty list disables the scope check.
ValidationUtc
Gets the UTC instant used to evaluate the grant validity window, or null to use the current time.
public DateTimeOffset? ValidationUtc { get; }
Property Value
Methods
Create(string?, string?, IEnumerable<string>?, DateTimeOffset?, string?, string?, string?, string?, string?, string?, bool, bool, bool, int, TimeSpan, string?, string?, string?, string?, string?, string?, CanonicalPayloadOptions?)
Creates a custom validation profile from the supplied expectations.
public static CapabilityGrantValidationOptions Create(string? issuer = null, string? audience = null, IEnumerable<string>? scopes = null, DateTimeOffset? validationUtc = null, string? policyVersion = null, string? policyHash = null, string? acknowledgmentId = null, string? handshakeId = null, string? gatewayBinding = null, string? resourceBinding = null, bool requireProof = false, bool requireAcknowledgmentReference = false, bool requireUseCheck = false, int maxUseCount = 1, TimeSpan allowedClockSkew = default, string? expectedProofKeyId = null, string? expectedProofKeyVersion = null, string? expectedProofPolicyVersion = null, string? expectedProofPolicyHash = null, string? requiredProofProvider = null, string? requiredProofHashAlgorithm = null, CanonicalPayloadOptions? proofPayloadOptions = null)
Parameters
issuerstringThe issuer the grant must name, or null to skip the issuer check.
audiencestringThe audience the grant must name; required when proof or a use check is required.
scopesIEnumerable<string>The scopes the grant must contain; blank entries are ignored.
validationUtcDateTimeOffset?The instant used for the validity window; defaults to the current time.
policyVersionstringThe policy version the grant must carry, when set.
policyHashstringThe policy hash the grant must carry, when set.
acknowledgmentIdstringThe acknowledgment identifier the grant must reference, when set.
handshakeIdstringThe handshake identifier the grant must reference, when set.
gatewayBindingstringThe gateway binding the grant must carry, when set.
resourceBindingstringThe resource binding the grant must carry, when set.
requireProofboolWhether the grant must carry verified proof bound to its content.
requireAcknowledgmentReferenceboolWhether the grant must reference a handshake acknowledgment.
requireUseCheckboolWhether validation must consume a grant use through a use store.
maxUseCountintThe maximum use count for this validation context; must be at least one.
allowedClockSkewTimeSpanThe non-negative tolerance applied to the validity window.
expectedProofKeyIdstringThe signing key identifier the proof must use, when set.
expectedProofKeyVersionstringThe signing key version the proof must use, when set.
expectedProofPolicyVersionstringThe policy version the proof must carry, when set.
expectedProofPolicyHashstringThe policy hash the proof must carry, when set.
requiredProofProviderstringThe signing provider that must have produced the proof, when set.
requiredProofHashAlgorithmstringThe hash algorithm the proof must use, when set.
proofPayloadOptionsCanonicalPayloadOptionsThe canonical payload options the issuer signed with; defaults apply when null.
Returns
- CapabilityGrantValidationOptions
The validation options.
Remarks
This factory does not bind the grant to an authenticated subject. At an execution boundary, prefer CreateBoundExecutionBoundary(CapabilityGrantBindingExpectations, string?, string?, IEnumerable<string>?, DateTimeOffset?, string?, string?, string?, string?, string?, string?, bool, bool, int, TimeSpan, string?, string?, string?, string?, string?, string?, CanonicalPayloadOptions?), or call WithExpectedBindings(string?, string?) on the result.
Exceptions
- ArgumentOutOfRangeException
allowedClockSkewis negative, ormaxUseCountis less than one.- ArgumentException
requireProoforrequireUseCheckis set without anaudience.
CreateBoundExecutionBoundary(CapabilityGrantBindingExpectations, string?, string?, IEnumerable<string>?, DateTimeOffset?, string?, string?, string?, string?, string?, string?, bool, bool, int, TimeSpan, string?, string?, string?, string?, string?, string?, CanonicalPayloadOptions?)
Creates a proof-verifying execution-boundary profile with authoritative host binding expectations.
public static CapabilityGrantValidationOptions CreateBoundExecutionBoundary(CapabilityGrantBindingExpectations bindingExpectations, string? issuer = null, string? audience = null, IEnumerable<string>? scopes = null, DateTimeOffset? validationUtc = null, string? policyVersion = null, string? policyHash = null, string? acknowledgmentId = null, string? handshakeId = null, string? gatewayBinding = null, string? resourceBinding = null, bool requireAcknowledgmentReference = false, bool requireUseCheck = true, int maxUseCount = 1, TimeSpan allowedClockSkew = default, string? expectedProofKeyId = null, string? expectedProofKeyVersion = null, string? expectedProofPolicyVersion = null, string? expectedProofPolicyHash = null, string? requiredProofProvider = null, string? requiredProofHashAlgorithm = null, CanonicalPayloadOptions? proofPayloadOptions = null)
Parameters
bindingExpectationsCapabilityGrantBindingExpectationsissuerstringaudiencestringscopesIEnumerable<string>validationUtcDateTimeOffset?policyVersionstringpolicyHashstringacknowledgmentIdstringhandshakeIdstringgatewayBindingstringresourceBindingstringrequireAcknowledgmentReferenceboolrequireUseCheckboolmaxUseCountintallowedClockSkewTimeSpanexpectedProofKeyIdstringexpectedProofKeyVersionstringexpectedProofPolicyVersionstringexpectedProofPolicyHashstringrequiredProofProviderstringrequiredProofHashAlgorithmstringproofPayloadOptionsCanonicalPayloadOptions
Returns
CreateExecutionBoundary(string?, string?, IEnumerable<string>?, DateTimeOffset?, string?, string?, string?, string?, string?, string?, bool, bool, int, TimeSpan, string?, string?, string?, string?, string?, string?, CanonicalPayloadOptions?)
Obsolete. Retains the legacy execution-boundary signature for binary compatibility and always fails closed.
[Obsolete("CreateExecutionBoundary always fails closed and is retained only for binary compatibility. Use CreateBoundExecutionBoundary(CapabilityGrantBindingExpectations, ...) instead. Planned removal in 8.0.", DiagnosticId = "ASIB901", UrlFormat = "https://asibackbone.github.io/AsiBackbone/articles/asib901-create-execution-boundary.html")]
public static CapabilityGrantValidationOptions CreateExecutionBoundary(string? issuer = null, string? audience = null, IEnumerable<string>? scopes = null, DateTimeOffset? validationUtc = null, string? policyVersion = null, string? policyHash = null, string? acknowledgmentId = null, string? handshakeId = null, string? gatewayBinding = null, string? resourceBinding = null, bool requireAcknowledgmentReference = false, bool requireUseCheck = true, int maxUseCount = 1, TimeSpan allowedClockSkew = default, string? expectedProofKeyId = null, string? expectedProofKeyVersion = null, string? expectedProofPolicyVersion = null, string? expectedProofPolicyHash = null, string? requiredProofProvider = null, string? requiredProofHashAlgorithm = null, CanonicalPayloadOptions? proofPayloadOptions = null)
Parameters
issuerstringaudiencestringscopesIEnumerable<string>validationUtcDateTimeOffset?policyVersionstringpolicyHashstringacknowledgmentIdstringhandshakeIdstringgatewayBindingstringresourceBindingstringrequireAcknowledgmentReferenceboolrequireUseCheckboolmaxUseCountintallowedClockSkewTimeSpanexpectedProofKeyIdstringexpectedProofKeyVersionstringexpectedProofPolicyVersionstringexpectedProofPolicyHashstringrequiredProofProviderstringrequiredProofHashAlgorithmstringproofPayloadOptionsCanonicalPayloadOptions
Returns
Remarks
This method is retained only for compatibility and always throws InvalidOperationException.
Replace calls with CreateBoundExecutionBoundary(CapabilityGrantBindingExpectations, ...), whose required
first argument supplies the authoritative subject and optional operation binding. The warning remains non-error
in the 7.x line; removal is planned for the next permitted major version.
CreateMetadataValidation(string?, string?, IEnumerable<string>?, DateTimeOffset?, string?, string?, string?, string?, string?, string?, bool, TimeSpan)
Creates a metadata-only profile that checks grant claims without requiring proof or consuming a use.
public static CapabilityGrantValidationOptions CreateMetadataValidation(string? issuer = null, string? audience = null, IEnumerable<string>? scopes = null, DateTimeOffset? validationUtc = null, string? policyVersion = null, string? policyHash = null, string? acknowledgmentId = null, string? handshakeId = null, string? gatewayBinding = null, string? resourceBinding = null, bool requireAcknowledgmentReference = false, TimeSpan allowedClockSkew = default)
Parameters
issuerstringThe issuer the grant must name, or null to skip the issuer check.
audiencestringThe audience the grant must name, or null to skip the audience check.
scopesIEnumerable<string>The scopes the grant must contain; blank entries are ignored.
validationUtcDateTimeOffset?The instant used for the validity window; defaults to the current time.
policyVersionstringThe policy version the grant must carry, when set.
policyHashstringThe policy hash the grant must carry, when set.
acknowledgmentIdstringThe acknowledgment identifier the grant must reference, when set.
handshakeIdstringThe handshake identifier the grant must reference, when set.
gatewayBindingstringThe gateway binding the grant must carry, when set.
resourceBindingstringThe resource binding the grant must carry, when set.
requireAcknowledgmentReferenceboolWhether the grant must reference a handshake acknowledgment.
allowedClockSkewTimeSpanThe non-negative tolerance applied to the validity window.
Returns
- CapabilityGrantValidationOptions
The validation options.
Remarks
Because the grant signature is not verified, a valid result only means the grant claims match the expectations. Do not use this profile to authorize execution; use CreateBoundExecutionBoundary(CapabilityGrantBindingExpectations, string?, string?, IEnumerable<string>?, DateTimeOffset?, string?, string?, string?, string?, string?, string?, bool, bool, int, TimeSpan, string?, string?, string?, string?, string?, string?, CanonicalPayloadOptions?) instead.
Exceptions
- ArgumentOutOfRangeException
allowedClockSkewis negative.
WithExpectedBindings(string?, string?)
Creates a copy with optional host expectations for the authenticated subject and requested operation.
public CapabilityGrantValidationOptions WithExpectedBindings(string? expectedSubjectId = null, string? expectedOperationName = null)