bundle

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 19, 2025 License: Apache-2.0 Imports: 10 Imported by: 1

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	KeepAll  = Predicate(func(Token) bool { return true })
	KeepNone = Predicate(func(Token) bool { return false })

	IsNonMacaroon        = Predicate(isType[NonMacaroon])
	IsMalformedMacaroon  = Predicate(isType[*MalformedMacaroon])
	IsVerifiedMacaroon   = Predicate(isType[*VerifiedMacaroon])
	IsUnverifiedMacaroon = Predicate(isType[*UnverifiedMacaroon])
	IsFailedMacaroon     = Predicate(isType[*FailedMacaroon])

	IsWellFormedMacaroon = Predicate(isType[Macaroon])
	IsVerificationResult = Predicate(isType[VerificationResult])

	NonMacaroonPredicate        = TypedPredicate[NonMacaroon]
	MalformedMacaroonPredicate  = TypedPredicate[*MalformedMacaroon]
	VerifiedMacaroonPredicate   = TypedPredicate[*VerifiedMacaroon]
	UnverifiedMacaroonPredicate = TypedPredicate[*UnverifiedMacaroon]
	FailedMacaroonPredicate     = TypedPredicate[*FailedMacaroon]
	MacaroonPredicate           = TypedPredicate[Macaroon]
	VerificationResultPredicate = TypedPredicate[VerificationResult]
)

Functions

func ForEach 

func ForEach[T Token](b *Bundle, cb func(T))

ForEach calls the provided callback for each token in the Bundle.

func HasCaveat 

func HasCaveat[C macaroon.Caveat](t Token) bool

HasCaveat returns a Predicate that selects Tokens with caveats of the given type. 

func Header[T Token](ts ...T) string

func Map 

func Map[R any, T Token](b *Bundle, cb func(T) R) []R

Map applies the callback to each token in the Bundle and returns a slice of the callback's return values.

func Reduce 

func Reduce[A any, T Token](b *Bundle, cb func(A, T) A) A

Reduce applies the callback to each token in the Bundle, accumulating the result.

func String 

func String[T Token](ts ...T) string

Types

type Bundle 

type Bundle struct {
	IsPermissionToken Predicate
	// contains filtered or unexported fields
}

Bundle is a collection of tokens parsed from an Authorization header. It is safe for concurrent use.

func ParseBundle 

func ParseBundle(permissionLocation, hdr string) (*Bundle, error)

ParseBundle is the same as ParseBundleWithFilter, but uses the DefaultFilter.

func ParseBundleWithFilter 

func ParseBundleWithFilter(permissionLocation, hdr string, filter Filter) (*Bundle, error)

ParseBundleWithFilter parses a FlyV1 Authorization header into a Bundle. The Bundle is usable regardless of whether an error is returned. The provided filter is applied to the parsed tokens. The returned error is constructed before the tokens are filtered and will contain information about invalid tokens that may be filtered.

func (*Bundle) AddTokens 

func (b *Bundle) AddTokens(hdr string) error

AddTokens parses the provided header and adds the tokens to the Bundle. If an error occurs during parsing, the Bundle remains unchanged.

func (*Bundle) Any 

func (b *Bundle) Any(f Filter) bool

Any returns true if any of the tokens in the Bundle match the filter.

func (*Bundle) Attenuate 

func (b *Bundle) Attenuate(caveats ...macaroon.Caveat) error

Attenuate adds caveats to the permission macaroons in the Bundle. If any part of this fails, the bundle remains unchanged.

func (*Bundle) Clone 

func (b *Bundle) Clone() *Bundle

Clone returns a deep copy of the Bundle by serializing and re-parsing it.

func (*Bundle) Count 

func (b *Bundle) Count(f Filter) int

Count returns the number of tokens in the Bundle that match the filter.

func (*Bundle) Discharge 

func (b *Bundle) Discharge(tpLocation string, tpKey macaroon.EncryptionKey, cb Discharger) error

Discharge attempts to discharge any third-party caveats for tpLocation. The provided callback (cb) is invoked to validate any caveats in tickets and to provide discharge macaroons.

func (*Bundle) Error 

func (b *Bundle) Error() error

Error returns the combined errors from all macaroons in the Bundle. These errors are populated during initial parsing as well as during [Verify].

func (*Bundle) Filter 

func (b *Bundle) Filter(f Filter)

Filter modifies the Bundle in place, removing tokens that don't match the provided Filter.

func (*Bundle) Header 

func (b *Bundle) Header() string

Header returns the Authorization header value for the Bundle.

func (*Bundle) IsEmpty 

func (b *Bundle) IsEmpty() bool

IsEmpty returns true if the Bundle contains no tokens.

func (*Bundle) IsMissingDischarge 

func (b *Bundle) IsMissingDischarge(tpLocation string) Filter

IsMissingDischarge returns a Filter that selects only permission tokens that are missing discharges for the specified 3p location.

func (*Bundle) Len 

func (b *Bundle) Len() int

Len returns the number of tokens in the Bundle.

func (*Bundle) Select 

func (b *Bundle) Select(f Filter) *Bundle

Select returns a new Bundle containing only the tokens matching the filter. The underlying Tokens are the same.

func (*Bundle) String 

func (b *Bundle) String() string

String returns the string representation of the Bundle.

func (*Bundle) UndischargedThirdPartyTickets 

func (b *Bundle) UndischargedThirdPartyTickets() map[string][][]byte

UndischargedThirdPartyTickets returns a map of third-party locations to their third party tickets that we don't have a discharge for.

func (*Bundle) UndischargedTicketsForThirdParty 

func (b *Bundle) UndischargedTicketsForThirdParty(tpLocation string) [][]byte

UndischargedTicketsForThirdParty returns a list of tickets for the specified third party that we don't have a discharge for.

func (*Bundle) Validate 

func (b *Bundle) Validate(accesses ...macaroon.Access) error

Validate attempts to validate the provided accesses against all verified macaroons in the Bundle. If no macaroon satisfies all the accesses, the combination of errors from all failed macaroons is returned.

func (*Bundle) Verify 

func (b *Bundle) Verify(ctx context.Context, v Verifier) ([]*macaroon.CaveatSet, error)

Verify attempts to verify the signature of every macaroon in the Bundle. Successfully verified macaroons will be the subject for future [Validate] calls. Unsuccessfully verified tokens will be annotated with their error, which can be checked with the Error method.

func (*Bundle) WithDischarges 

func (b *Bundle) WithDischarges(f Filter) Filter

WithDischarges returns a Filter selecting tokens matching f and their discharges.

type Discharger 

type Discharger func([]macaroon.Caveat) ([]macaroon.Caveat, error)

Discharger is a callback for validating caveats extracted from a third-party ticket. These caveats are a restriction placed by the 1p on under what conditions the 3p should issue a discharge. If there are caveats and the 3p doesn't know how to deal with them, it should return an error. If the 3p is willing to discharge the ticket, it should return the set of caveats to add to the discharge macaroon.

type FailedMacaroon 

type FailedMacaroon struct {
	*UnverifiedMacaroon

	// Error is the error that occurred while verifying the token.
	Err error
}

FailedMacaroon is a Macaroon that failed signature verification.

func (*FailedMacaroon) Error 

func (m *FailedMacaroon) Error() error

type Filter 

type Filter interface {
	// Apply does the work of filtering Toks. It is expected that the filter
	// modifies the slice that is passed in, but doesn't change the order of
	// elements.
	Apply([]Token) []Token
}

Filter filters a slice of Toks. It can be passed to Bundle.Select or ParseBundleWithFilter.

func DefaultFilter 

func DefaultFilter(isPerm Predicate) Filter

DefaultFilter rejects malformed macaroons and discharge tokens that aren't associated with any permission token.

type KeyResolver 

type KeyResolver func(context.Context, macaroon.Nonce) (macaroon.SigningKey, map[string][]macaroon.EncryptionKey, error)

KeyResolver is a helper for generating a Verifier for use by macaroon authorities. It is responsible for looking up the appropriate key to use for the given nonce's KID.

func WithKey 

func WithKey(kid []byte, key macaroon.SigningKey, trustedTPs map[string][]macaroon.EncryptionKey) KeyResolver

WithKey returns a KeyResolver for authorities with a single key.

func WithKeys 

func WithKeys(keyByKID map[string]macaroon.SigningKey, trustedTPs map[string][]macaroon.EncryptionKey) KeyResolver

WithKeys returns a KeyResolver for authorities with multiple keys.

func (KeyResolver) Verify 

func (kr KeyResolver) Verify(ctx context.Context, dissByPerm map[Macaroon][]Macaroon) map[Macaroon]VerificationResult

func (KeyResolver) VerifyOne 

func (kr KeyResolver) VerifyOne(ctx context.Context, perm Macaroon, diss []Macaroon) VerificationResult

VerifyOne is a VerifierFunc

type LocationFilter 

type LocationFilter string

LocationFilter is a Filter that selects macaroons with the given location.

func (LocationFilter) Apply 

func (l LocationFilter) Apply(ts []Token) []Token

Apply implements Filter

func (LocationFilter) Predicate 

func (l LocationFilter) Predicate() Predicate

Predicate returns a Predicate based on the Filter.

type Macaroon 

type Macaroon interface {
	Token

	// Unverified returns the token as an UnverifiedMacaroon.
	Unverified() *UnverifiedMacaroon

	// UnsafeMacaroon returns the parsed macaroon.Macaroon. It is not safe to
	// access this when another goroutine is accessing the Bundle it came from.
	// It is never safe to modify this directly.
	UnsafeMacaroon() *macaroon.Macaroon

	// Location returns the location of this macaroon.
	Location() string

	// Nonce returns the nonce of this macaroon.
	Nonce() macaroon.Nonce

	// UnsafeCaveats returns the unverified caveats from this macaroon.
	UnsafeCaveats() *macaroon.CaveatSet

	// ThirdPartyTickets returns all third party tickets in this macaroon.
	ThirdPartyTickets() map[string][][]byte

	// TicketsForThirdParty returns the tickets for a given third party location.
	TicketsForThirdParty(string) [][]byte
}

Macaroon is a UnverifiedMacaroon, VerifiedMacaroon, or FailedMacaroon.

type MalformedMacaroon 

type MalformedMacaroon struct {
	// Str is the string representation of the token.
	Str string

	// Err is the error that occurred while parsing the token.
	Err error
}

MalformedMacaroon is a token that looked like a macaroon, but couldn't be parsed.

func (*MalformedMacaroon) Error 

func (t *MalformedMacaroon) Error() error

func (*MalformedMacaroon) String 

func (t *MalformedMacaroon) String() string

implement Token

type NonMacaroon 

type NonMacaroon string

NonMacaroon is a token that doesn't look like a macaroon.

func (NonMacaroon) String 

func (t NonMacaroon) String() string

implement Token

type Predicate 

type Predicate func(Token) bool

Predicate is a type of Filter that returns a yes/no answer for each Token.

func AllowsAccess 

func AllowsAccess(accesses ...macaroon.Access) Predicate

AllowsAccess returns a Predicate that selects verified macaroons allowing the given accesses.

func And 

func And(ps ...Predicate) Predicate

And returns a Predicate requiring all of ps to be true.

func Not 

func Not(p Predicate) Predicate

Not returns a Predicate requiring the opposite of p.

func Or 

func Or(ps ...Predicate) Predicate

Or returns a Predicate requiring one of ps to be true.

func TypedPredicate 

func TypedPredicate[T Token](p func(T) bool) Predicate

TypedPredicate returns a Predicate for a function operating on a concrete Token type.

func (Predicate) Apply 

func (p Predicate) Apply(ts []Token) []Token

Apply implements Filter.

type Token 

type Token interface {
	String() string
	// contains filtered or unexported methods
}

type UnverifiedMacaroon 

type UnverifiedMacaroon struct {
	// Str is the string representation of the token.
	Str string

	// UnsafeMac is the macaroon.Macaroon that was parsed from Str. It is not
	// safe to modify (e.g. attenuate) this Macaroon directly, since updates
	// need to be written to other fields in this struct. It is not safe to keep
	// references to this Macaroon and use them directly if other goroutines
	// might be accessing the Bundle it came from concurrently.
	UnsafeMac *macaroon.Macaroon
}

UnverifiedMacaroon is a Macaroon that hasn't been verified yet. Discharge tokens are always UnverifiedMacaroons.

func (*UnverifiedMacaroon) Location 

func (t *UnverifiedMacaroon) Location() string

func (*UnverifiedMacaroon) Nonce 

func (t *UnverifiedMacaroon) Nonce() macaroon.Nonce

func (*UnverifiedMacaroon) String 

func (t *UnverifiedMacaroon) String() string

implement Token

func (*UnverifiedMacaroon) ThirdPartyTickets 

func (t *UnverifiedMacaroon) ThirdPartyTickets() map[string][][]byte

func (*UnverifiedMacaroon) TicketsForThirdParty 

func (t *UnverifiedMacaroon) TicketsForThirdParty(loc string) [][]byte

func (*UnverifiedMacaroon) UnsafeCaveats 

func (t *UnverifiedMacaroon) UnsafeCaveats() *macaroon.CaveatSet

func (*UnverifiedMacaroon) UnsafeMacaroon 

func (t *UnverifiedMacaroon) UnsafeMacaroon() *macaroon.Macaroon

func (*UnverifiedMacaroon) Unverified 

func (t *UnverifiedMacaroon) Unverified() *UnverifiedMacaroon

implement Macaroon

type VerificationCache 

type VerificationCache struct {
	// contains filtered or unexported fields
}

VerificationCache is a Verifier that caches successful verification results.

func NewVerificationCache 

func NewVerificationCache(verifier Verifier, ttl time.Duration, size int) *VerificationCache

func (*VerificationCache) Purge 

func (vc *VerificationCache) Purge()

func (*VerificationCache) Verify 

func (vc *VerificationCache) Verify(ctx context.Context, dissByPerm map[Macaroon][]Macaroon) map[Macaroon]VerificationResult

type VerificationResult 

type VerificationResult interface {
	Macaroon
	// contains filtered or unexported methods
}

VerificationResult is a VerifiedMacaroon or FailedMacaroon.

type VerifiedMacaroon 

type VerifiedMacaroon struct {
	*UnverifiedMacaroon

	// Caveats is the set of verified caveats.
	Caveats *macaroon.CaveatSet
}

VerifiedMacaroon is a Macaroon that passed signature verification.

func (*VerifiedMacaroon) Expiration 

func (t *VerifiedMacaroon) Expiration() time.Time

Expiration calculates when this macaroon will expire

type Verifier 

type Verifier interface {
	// Verify does the work of verifying a map of macaroons. It takes a mapping
	// of permission tokens to their potential discharge tokens. It returns a
	// mapping from permission to verification results (either VerifiedMacaroon
	// or FailedMacaroon).
	Verify(ctx context.Context, dischargesByPermission map[Macaroon][]Macaroon) map[Macaroon]VerificationResult
}

Verifier verifies macaroons.

type VerifierFunc 

type VerifierFunc func(ctx context.Context, perm Macaroon, diss []Macaroon) VerificationResult

func (VerifierFunc) Verify 

func (vf VerifierFunc) Verify(ctx context.Context, dissByPerm map[Macaroon][]Macaroon) map[Macaroon]VerificationResult

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.