scopes

Documentation

Overview

Package scopes provides utilities for manipulating and interpreting Taskcluster scopes.

See https://docs.taskcluster.net/presentations/scopes/#/definitions for formal definitions.

Index

• type Given
  • func (given Given) Expand(scopeExpander ScopeExpander) (expanded Given, err error)
  • func (given Given) Satisfies(required Required, scopeExpander ScopeExpander) (bool, error)
  • func (given Given) String() string
• type Required
  • func (required Required) String() string
• type ScopeExpander

Types

type Given

type Given []string

`Given` represents a set of scopes assigned to a client. For example:

myScopes := scopes.Given{
	"abc:*",
	"123:4:56",
	"xyz",
	"AB:*",
}

In order for a given scope to satisfy a required scope, either the given scope and required scope need to match as strings, or the given scope needs to be a prefix of the required scope, plus the `*` character. For example, the given scope `abc:*` satisfies the required scope `abc:def`.

func (Given) Expand

func (given Given) Expand(scopeExpander ScopeExpander) (expanded Given, err error)

func (Given) Satisfies

func (given Given) Satisfies(required Required, scopeExpander ScopeExpander) (bool, error)

Returns `true` if the given scopes satisfy the required scopes.

This function is ported from https://github.com/taskcluster/taskcluster-base/blob/218225942212e24596cee211389c276b2b985ffe/utils.js#L37-L68

func (Given) String

func (given Given) String() string

Returns "<scope> and <scope> and ... and <scope>" for all scopes in given.

type Required

type Required [][]string

`Required` represents (in disjunctive normal form) permutations of scopes that are sufficient to authorise a client to perform a particular action. For example:

requiredScopes := scopes.Required{
	{"abc:def", "AB:CD:EF"},
	{"123:4:5"},
	{"abc:def", "123:4"},
	{"Xxyz"},
}

represents the requirement that the following scopes are "satisfied":

("abc:def" AND "AB:CD:EF") OR "123:4:5" OR ("abc:def" AND "123:4") OR "Xxyz"

Please note that since a required scope satisfies a given scope if they are equal, required scopes ending with a `*` can be used, although are relatively uncommon. See the examples.

func (Required) String

func (required Required) String() string

Returns a description of the required scopes in English.

type ScopeExpander

type ScopeExpander interface {
	ExpandScopes(*tcauth.SetOfScopes) (*tcauth.SetOfScopes, error)
}

Note, this is trivially implemented by *Auth in github.com/taskcluster/taskcluster/v29/clients/client-go/tcauth package, so typically tcauth.New(nil) will satisfy this interface.