Table of Contents

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

string

AllowedClockSkew

Gets the non-negative tolerance applied to the grant not-before and expiry times.

public TimeSpan AllowedClockSkew { get; }

Property Value

TimeSpan

Audience

Gets the audience the grant must name, when an audience expectation is configured.

public string? Audience { get; }

Property Value

string

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

string

ExpectedProofKeyId

Gets the signing key identifier the grant proof must use, when configured.

public string? ExpectedProofKeyId { get; }

Property Value

string

ExpectedProofKeyVersion

Gets the signing key version the grant proof must use, when configured.

public string? ExpectedProofKeyVersion { get; }

Property Value

string

ExpectedProofPolicyHash

Gets the policy hash the grant proof must carry, when configured.

public string? ExpectedProofPolicyHash { get; }

Property Value

string

ExpectedProofPolicyVersion

Gets the policy version the grant proof must carry, when configured.

public string? ExpectedProofPolicyVersion { get; }

Property Value

string

ExpectedSubjectId

Gets the authenticated subject that the grant must identify, when subject binding is configured.

public string? ExpectedSubjectId { get; }

Property Value

string

GatewayBinding

Gets the gateway binding the grant must carry, when a gateway expectation is configured.

public string? GatewayBinding { get; }

Property Value

string

HandshakeId

Gets the liability handshake identifier the grant must reference, when a handshake expectation is configured.

public string? HandshakeId { get; }

Property Value

string

Issuer

Gets the issuer the grant must name, when an issuer expectation is configured.

public string? Issuer { get; }

Property Value

string

MaxUseCount

Gets the maximum use count allowed by this validation context.

public int MaxUseCount { get; }

Property Value

int

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

string

PolicyVersion

Gets the policy version the grant must carry, when a policy version expectation is configured.

public string? PolicyVersion { get; }

Property Value

string

ProofPayloadOptions

Gets the canonical payload options used to rebuild the grant payload when proof is required.

public CanonicalPayloadOptions? ProofPayloadOptions { get; }

Property Value

CanonicalPayloadOptions

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

bool

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

bool

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

bool

RequiredProofHashAlgorithm

Gets the hash algorithm the grant proof must use, when configured.

public string? RequiredProofHashAlgorithm { get; }

Property Value

string

RequiredProofProvider

Gets the signing provider that must have produced the grant proof, when configured.

public string? RequiredProofProvider { get; }

Property Value

string

ResourceBinding

Gets the resource binding the grant must carry, when a resource expectation is configured.

public string? ResourceBinding { get; }

Property Value

string

Scopes

Gets the scopes the grant must contain, trimmed, de-duplicated, and sorted ordinally.

public IReadOnlyList<string> Scopes { get; }

Property Value

IReadOnlyList<string>

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

DateTimeOffset?

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

issuer string

The issuer the grant must name, or null to skip the issuer check.

audience string

The audience the grant must name; required when proof or a use check is required.

scopes IEnumerable<string>

The scopes the grant must contain; blank entries are ignored.

validationUtc DateTimeOffset?

The instant used for the validity window; defaults to the current time.

policyVersion string

The policy version the grant must carry, when set.

policyHash string

The policy hash the grant must carry, when set.

acknowledgmentId string

The acknowledgment identifier the grant must reference, when set.

handshakeId string

The handshake identifier the grant must reference, when set.

gatewayBinding string

The gateway binding the grant must carry, when set.

resourceBinding string

The resource binding the grant must carry, when set.

requireProof bool

Whether the grant must carry verified proof bound to its content.

requireAcknowledgmentReference bool

Whether the grant must reference a handshake acknowledgment.

requireUseCheck bool

Whether validation must consume a grant use through a use store.

maxUseCount int

The maximum use count for this validation context; must be at least one.

allowedClockSkew TimeSpan

The non-negative tolerance applied to the validity window.

expectedProofKeyId string

The signing key identifier the proof must use, when set.

expectedProofKeyVersion string

The signing key version the proof must use, when set.

expectedProofPolicyVersion string

The policy version the proof must carry, when set.

expectedProofPolicyHash string

The policy hash the proof must carry, when set.

requiredProofProvider string

The signing provider that must have produced the proof, when set.

requiredProofHashAlgorithm string

The hash algorithm the proof must use, when set.

proofPayloadOptions CanonicalPayloadOptions

The canonical payload options the issuer signed with; defaults apply when null.

Returns

CapabilityGrantValidationOptions

The validation options.

Remarks

Exceptions

ArgumentOutOfRangeException

allowedClockSkew is negative, or maxUseCount is less than one.

ArgumentException

requireProof or requireUseCheck is set without an audience.

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

bindingExpectations CapabilityGrantBindingExpectations
issuer string
audience string
scopes IEnumerable<string>
validationUtc DateTimeOffset?
policyVersion string
policyHash string
acknowledgmentId string
handshakeId string
gatewayBinding string
resourceBinding string
requireAcknowledgmentReference bool
requireUseCheck bool
maxUseCount int
allowedClockSkew TimeSpan
expectedProofKeyId string
expectedProofKeyVersion string
expectedProofPolicyVersion string
expectedProofPolicyHash string
requiredProofProvider string
requiredProofHashAlgorithm string
proofPayloadOptions CanonicalPayloadOptions

Returns

CapabilityGrantValidationOptions

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

issuer string
audience string
scopes IEnumerable<string>
validationUtc DateTimeOffset?
policyVersion string
policyHash string
acknowledgmentId string
handshakeId string
gatewayBinding string
resourceBinding string
requireAcknowledgmentReference bool
requireUseCheck bool
maxUseCount int
allowedClockSkew TimeSpan
expectedProofKeyId string
expectedProofKeyVersion string
expectedProofPolicyVersion string
expectedProofPolicyHash string
requiredProofProvider string
requiredProofHashAlgorithm string
proofPayloadOptions CanonicalPayloadOptions

Returns

CapabilityGrantValidationOptions

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

issuer string

The issuer the grant must name, or null to skip the issuer check.

audience string

The audience the grant must name, or null to skip the audience check.

scopes IEnumerable<string>

The scopes the grant must contain; blank entries are ignored.

validationUtc DateTimeOffset?

The instant used for the validity window; defaults to the current time.

policyVersion string

The policy version the grant must carry, when set.

policyHash string

The policy hash the grant must carry, when set.

acknowledgmentId string

The acknowledgment identifier the grant must reference, when set.

handshakeId string

The handshake identifier the grant must reference, when set.

gatewayBinding string

The gateway binding the grant must carry, when set.

resourceBinding string

The resource binding the grant must carry, when set.

requireAcknowledgmentReference bool

Whether the grant must reference a handshake acknowledgment.

allowedClockSkew TimeSpan

The non-negative tolerance applied to the validity window.

Returns

CapabilityGrantValidationOptions

The validation options.

Remarks

Exceptions

ArgumentOutOfRangeException

allowedClockSkew is 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)

Parameters

expectedSubjectId string
expectedOperationName string

Returns

CapabilityGrantValidationOptions