Documentation
¶
Overview ¶
Package budgets implements the AAuth Budgets protocol companion.
Index ¶
- Constants
- func FormatAuthTokenRequirement(value aauth.AuthTokenRequirement, reason Reason) (string, error)
- func FormatFeedback(feedback Feedback) (string, error)
- func IsTokenClaimError(err error) bool
- func MintAuthToken(key jose.SigningKey, claims aauth.AuthTokenClaims, grant Value) (string, error)
- func MintResourceToken(key jose.SigningKey, claims aauth.ResourceTokenClaims, offer Value, ...) (string, error)
- func TokenCarriesClaims(compact string) (bool, error)
- func TokenClaimError(err error) error
- func ValidateDeclaredValue(declarations []UnitDeclaration, value Value) error
- func ValidateFeedback(grant Value, feedback Feedback) error
- func ValidateFeedbackUnit(unit Unit) error
- func ValidateNarrowing(offered, granted Value) error
- func ValidateUnitDeclarations(declarations []UnitDeclaration) error
- func VerifyResourceToken(ctx context.Context, compact string, resolver signaturekey.KeyResolver, ...) (aauth.ResourceTokenClaims, Value, []ConsumptionRecord, error)
- type ConsumptionRecord
- type Feedback
- type Reason
- type Unit
- type UnitDeclaration
- type Value
Constants ¶
const MaximumAmount int64 = 999_999_999_999_999
MaximumAmount is the 15-digit limit shared by Budget JSON values and RFC 9651 Integer members.
Variables ¶
This section is empty.
Functions ¶
func FormatAuthTokenRequirement ¶
func FormatAuthTokenRequirement(value aauth.AuthTokenRequirement, reason Reason) (string, error)
FormatAuthTokenRequirement formats the Core auth-token requirement with one typed Budget reason parameter.
func FormatFeedback ¶
FormatFeedback emits the canonical RFC 9651 Dictionary form.
func IsTokenClaimError ¶
IsTokenClaimError reports whether Core token verification succeeded but the Budget companion claims were malformed. Token endpoints use this distinction to return the Budgets protocol's registered invalid_budget error.
func MintAuthToken ¶
func MintAuthToken(key jose.SigningKey, claims aauth.AuthTokenClaims, grant Value) (string, error)
MintAuthToken adds one validated Budget grant to Core Auth-token claims.
func MintResourceToken ¶
func MintResourceToken( key jose.SigningKey, claims aauth.ResourceTokenClaims, offer Value, consumed []ConsumptionRecord, ) (string, error)
MintResourceToken adds one validated Budget offer and optional recent consumption records to Core Resource-token claims.
func TokenCarriesClaims ¶
TokenCarriesClaims reports whether an unverified compact token names a Budget claim, including partial and case-variant forms that must route to strict Budget verification.
func TokenClaimError ¶
TokenClaimError marks an error found after Core token verification while consuming Budget companion claims. Endpoints use it to return the registered invalid_budget response for composed token profiles too.
func ValidateDeclaredValue ¶
func ValidateDeclaredValue(declarations []UnitDeclaration, value Value) error
ValidateDeclaredValue checks that a signed offer or grant uses one declared denomination and does not exceed its advertised maximum when present.
func ValidateFeedback ¶
ValidateFeedback checks unsigned informational feedback against the signed Auth-token budget. An omitted unit pair remains valid because the pair is optional; a present pair must match exactly.
func ValidateFeedbackUnit ¶
ValidateFeedbackUnit checks that a JSON Budget unit is representable as an RFC 9651 String in AAuth-Budget. The token object permits arbitrary UTF-8, but a metering profile that emits the response field must establish this narrower carrier before any charge.
func ValidateNarrowing ¶
ValidateNarrowing requires the same denomination and an amount no greater than the resource's offer.
func ValidateUnitDeclarations ¶
func ValidateUnitDeclarations(declarations []UnitDeclaration) error
ValidateUnitDeclarations requires valid entries and one scale per unit identifier.
func VerifyResourceToken ¶
func VerifyResourceToken( ctx context.Context, compact string, resolver signaturekey.KeyResolver, clock aauth.Clock, ) (aauth.ResourceTokenClaims, Value, []ConsumptionRecord, error)
VerifyResourceToken verifies Core trust and consumes the complete Budget companion claim set.
Types ¶
type ConsumptionRecord ¶
type ConsumptionRecord struct {
// contains filtered or unexported fields
}
ConsumptionRecord reports metered consumption against one prior Auth token.
func NewConsumptionRecord ¶
func NewConsumptionRecord(jti string, consumed int64) (ConsumptionRecord, error)
NewConsumptionRecord validates one prior Auth-token consumption record.
func (ConsumptionRecord) Consumed ¶
func (record ConsumptionRecord) Consumed() int64
Consumed returns the amount metered against the prior Auth token.
func (ConsumptionRecord) JTI ¶
func (record ConsumptionRecord) JTI() string
JTI returns the prior Auth token identifier.
func (ConsumptionRecord) MarshalJSON ¶
func (record ConsumptionRecord) MarshalJSON() ([]byte, error)
MarshalJSON emits the exact Budget consumption-record object.
func (*ConsumptionRecord) UnmarshalJSON ¶
func (record *ConsumptionRecord) UnmarshalJSON(data []byte) error
UnmarshalJSON accepts only the exact Budget consumption-record object.
type Feedback ¶
type Feedback struct {
// contains filtered or unexported fields
}
Feedback is the parsed AAuth-Budget response field for the fixed-price success and refusal paths.
func NewRefusalFeedback ¶
NewRefusalFeedback constructs feedback for an exhausted or insufficient fixed-price request. Required is omitted when the Resource does not state a maximum cost for the refused request.
func NewSuccessFeedback ¶
NewSuccessFeedback constructs feedback for a completed fixed-price request.
func ParseFeedback ¶
ParseFeedback parses one or more AAuth-Budget field lines as an RFC 9651 Dictionary. Unknown members are ignored.
type Reason ¶
type Reason string
Reason is one Budget-specific reason on an auth-token requirement.
func ParseAuthTokenRequirement ¶
func ParseAuthTokenRequirement(values []string) (aauth.AuthTokenRequirement, Reason, error)
ParseAuthTokenRequirement parses the Core auth-token requirement and its required Budget reason parameter. Unrelated extension parameters remain ignored as required by the base extension model.
func ParseOptionalAuthTokenRequirement ¶
func ParseOptionalAuthTokenRequirement(values []string) (aauth.AuthTokenRequirement, Reason, bool, error)
ParseOptionalAuthTokenRequirement parses the Core auth-token requirement and, when present, one typed Budget reason. A missing reason is the ordinary Core step-up shape; an unknown or malformed present reason fails.
func ParseReason ¶
ParseReason validates a Budget-specific requirement reason.
type Unit ¶
type Unit struct {
// contains filtered or unexported fields
}
Unit is one resource-selected Budget denomination and scale.
type UnitDeclaration ¶
type UnitDeclaration struct {
// contains filtered or unexported fields
}
UnitDeclaration is one budget_units Resource-metadata entry. Unit and scale identify the denomination. Maximum is optional in the protocol; a host may require it for a bounded pricing profile.
func FindUnitDeclaration ¶
func FindUnitDeclaration(declarations []UnitDeclaration, unit Unit) (UnitDeclaration, bool)
FindUnitDeclaration returns the declaration for one exact denomination.
func NewBoundedUnitDeclaration ¶
func NewBoundedUnitDeclaration(unit Unit, maximum int64, description string) (UnitDeclaration, error)
NewBoundedUnitDeclaration constructs a declaration with an advertised maximum amount for one Auth token.
func NewUnitDeclaration ¶
func NewUnitDeclaration(unit Unit, description string) (UnitDeclaration, error)
NewUnitDeclaration constructs a declaration without an advertised maximum.
func (UnitDeclaration) Description ¶
func (declaration UnitDeclaration) Description() string
Description returns the optional Markdown description.
func (UnitDeclaration) MarshalJSON ¶
func (declaration UnitDeclaration) MarshalJSON() ([]byte, error)
MarshalJSON emits the flat budget_units metadata object.
func (UnitDeclaration) Maximum ¶
func (declaration UnitDeclaration) Maximum() (int64, bool)
Maximum returns the advertised maximum when present.
func (UnitDeclaration) Unit ¶
func (declaration UnitDeclaration) Unit() Unit
Unit returns the declared denomination and scale.
func (*UnitDeclaration) UnmarshalJSON ¶
func (declaration *UnitDeclaration) UnmarshalJSON(data []byte) error
UnmarshalJSON accepts one strict budget_units metadata object.
type Value ¶
type Value struct {
// contains filtered or unexported fields
}
Value is one non-negative Budget amount in a resource-selected unit.
func ParseValueJSON ¶
ParseValueJSON parses exactly one strict Budget object.
func VerifyAuthToken ¶
func VerifyAuthToken( ctx context.Context, compact string, resolver signaturekey.KeyResolver, clock aauth.Clock, ) (aauth.AuthTokenClaims, Value, error)
VerifyAuthToken verifies Core trust and consumes the complete Budget companion claim set.
func (Value) MarshalJSON ¶
MarshalJSON emits the exact Budget object.
func (*Value) UnmarshalJSON ¶
UnmarshalJSON accepts only the exact Budget object.
Source Files