Class CapabilityGrantToken
- Namespace
- AsiBackbone.Core.CapabilityGrants
- Assembly
- AsiBackbone.Core.dll
Encodes and decodes the versioned, size-limited transport form of a signed capability grant.
public static class CapabilityGrantToken
- Inheritance
-
CapabilityGrantToken
- Inherited Members
Remarks
A token is the prefix FormatPrefix followed by the unpadded base64url encoding of a UTF-8 JSON document. The document carries format version FormatVersion, every grant field, and the signing metadata a verifier needs. It does not carry the canonical payload or its hash: Decode(string?, CanonicalPayloadOptions?, int) rebuilds both from the decoded grant fields, so editing any field after signing, including the resource binding, yields a hash the signature does not cover.
The token is not encrypted. Every field is readable by anyone who holds it, so a grant must not carry secrets. Decoding is strict: unknown properties, duplicate properties, an unsupported format version, or a token longer than the configured limit fail rather than being ignored. A successful decode is not verification; validate the result with ValidateAsync(SignedGovernanceArtifact<CapabilityGrant>, CapabilityGrantValidationOptions?, IGovernanceSignatureVerificationService?, ICapabilityGrantUseStore?, CancellationToken) before trusting it.
Grant metadata is transported only for keys that the canonical payload options allow, because only those keys are covered by the signature. The issuer and the relying party must use the same CanonicalPayloadOptions.
Fields
DefaultMaxTokenLength
Gets the default maximum token length, in characters, accepted by Decode(string?, CanonicalPayloadOptions?, int) and produced by Encode(SignedGovernanceArtifact<CapabilityGrant>, CanonicalPayloadOptions?, int).
public const int DefaultMaxTokenLength = 8192
Field Value
FormatPrefix
Gets the prefix that identifies a version 1 capability grant token.
public const string FormatPrefix = "asibcg1."
Field Value
FormatVersion
Gets the token format version written into, and required in, the token document.
public const int FormatVersion = 1
Field Value
InvalidGrantFailureCode
The failure code returned when the token fields do not form a valid capability grant.
public const string InvalidGrantFailureCode = "capability.token-grant-invalid"
Field Value
MalformedFailureCode
The failure code returned when the token is not valid base64url, JSON, or token structure.
public const string MalformedFailureCode = "capability.token-malformed"
Field Value
MissingFailureCode
The failure code returned when no token was supplied.
public const string MissingFailureCode = "capability.token-missing"
Field Value
TooLargeFailureCode
The failure code returned when the token exceeds the configured maximum length.
public const string TooLargeFailureCode = "capability.token-too-large"
Field Value
UnsupportedFormatFailureCode
The failure code returned when the token prefix or format version is not supported.
public const string UnsupportedFormatFailureCode = "capability.token-format-unsupported"
Field Value
UnsupportedHashAlgorithmFailureCode
The failure code returned when the token names a hash algorithm the built-in hasher cannot rebuild.
public const string UnsupportedHashAlgorithmFailureCode = "capability.token-hash-algorithm-unsupported"
Field Value
Methods
Decode(string?, CanonicalPayloadOptions?, int)
Decodes a version 1 token into a signed capability grant whose canonical payload and hash are rebuilt from the decoded fields.
public static CapabilityGrantTokenDecodeResult Decode(string? token, CanonicalPayloadOptions? options = null, int maxTokenLength = 8192)
Parameters
tokenstringThe token to decode.
optionsCanonicalPayloadOptionsThe canonical payload options the issuer signed with; defaults apply when null.
maxTokenLengthintThe maximum accepted token length in characters.
Returns
- CapabilityGrantTokenDecodeResult
The decode result.
Remarks
Decoding never throws for token content. Every malformed, oversized, or unsupported token produces a failed result with a stable failure code.
Exceptions
- ArgumentOutOfRangeException
maxTokenLengthis less than one.
Encode(SignedGovernanceArtifact<CapabilityGrant>, CanonicalPayloadOptions?, int)
Encodes a signed capability grant as a version 1 token.
public static string Encode(SignedGovernanceArtifact<CapabilityGrant> signedGrant, CanonicalPayloadOptions? options = null, int maxTokenLength = 8192)
Parameters
signedGrantSignedGovernanceArtifact<CapabilityGrant>The signed grant, typically from SignCapabilityGrantAsync(CapabilityGrant, IGovernanceSigningService, CanonicalPayloadOptions?, string?, string?, string?, IReadOnlyDictionary<string, string>?, bool, string?, CancellationToken).
optionsCanonicalPayloadOptionsThe canonical payload options the grant was signed with; defaults apply when null.
maxTokenLengthintThe maximum token length in characters.
Returns
- string
The encoded token.
Exceptions
- ArgumentNullException
signedGrantis null.- ArgumentOutOfRangeException
maxTokenLengthis less than one.- ArgumentException
The artifact is not a capability grant, or its canonical hash does not match the grant rebuilt with
options, so the token could never verify.- InvalidOperationException
The grant is not signed, or the token would exceed
maxTokenLength.