Table of Contents

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

int

FormatPrefix

Gets the prefix that identifies a version 1 capability grant token.

public const string FormatPrefix = "asibcg1."

Field Value

string

FormatVersion

Gets the token format version written into, and required in, the token document.

public const int FormatVersion = 1

Field Value

int

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

string

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

string

MissingFailureCode

The failure code returned when no token was supplied.

public const string MissingFailureCode = "capability.token-missing"

Field Value

string

TooLargeFailureCode

The failure code returned when the token exceeds the configured maximum length.

public const string TooLargeFailureCode = "capability.token-too-large"

Field Value

string

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

string

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

string

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

token string

The token to decode.

options CanonicalPayloadOptions

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

maxTokenLength int

The 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

maxTokenLength is 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

signedGrant SignedGovernanceArtifact<CapabilityGrant>

The signed grant, typically from SignCapabilityGrantAsync(CapabilityGrant, IGovernanceSigningService, CanonicalPayloadOptions?, string?, string?, string?, IReadOnlyDictionary<string, string>?, bool, string?, CancellationToken).

options CanonicalPayloadOptions

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

maxTokenLength int

The maximum token length in characters.

Returns

string

The encoded token.

Exceptions

ArgumentNullException

signedGrant is null.

ArgumentOutOfRangeException

maxTokenLength is 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.