scopes

Documentation

Index

• Variables
• func PermissionToMetadataScope(permission Permission) (string, error)
• func Strategy(matcherLiterals []string, needleLiteral string) bool
• func ToStrings(scopes []Scope) []string
• type Action
• type AllowedScopes
  • func Allowed() AllowedScopes
  • func (s AllowedScopes) Contains(scope Scope) bool
• type ParsedScope
  • func ParseScope(scope Scope) (_ ParsedScope, valid bool)
• type Permission
• type Scope
  • func ToScope(service services.Service, permission Permission, action Action) Scope
• type Scopes
  • func ToScopes(strings []string) Scopes
  • func (s Scopes) Match(target Scope) bool

Variables

var (
	ServiceRegex    = regexp.MustCompile(`^[a-z_]{1,30}$`)
	PermissionRegex = regexp.MustCompile(`^[a-z_.]{1,215}$`)
	ActionRegex     = regexp.MustCompile(`^(read|write|delete)$`)
)

Ths list of regular expressions to make sure each part of a scope is spec-compliant.

Functions

func PermissionToMetadataScope

func PermissionToMetadataScope(permission Permission) (string, error)

PermissionToMetadataScope extracts the metadata scope from a permission. Only valid for 'user.metadata'-prefixed permissions.

Examples:

• user.metadata => *
• user.metadata.cody => cody
• user.metadata.dotcom => dotcom

func Strategy

func Strategy(matcherLiterals []string, needleLiteral string) bool

Strategy is a custom scope strategy that matches scopes based on the following rules:

• Builtin scopes ("openid", "email", "offline_access") without alias are matched by their exact name.
• Any matcher or needle that must have the desired the format, "service::permission::action". Otherwise consider not match (returns false).
• A overall match is considered when all "service", "permission", and "action" match (returns true).
• The "permission" part of the scope is (conceptually) prefix matching, i.e. "user" matches "user" as well as "user.roles" and "user.metadata".

Full specification of the token scope is available at https://handbook.sourcegraph.com/departments/engineering/teams/core-services/sams/token_scope_specification/

NOTE: This function must accept strings to have the type of `fosite.ScopeStrategy`.

func ToStrings

func ToStrings(scopes []Scope) []string

ToStrings converts a list of scopes to a list of strings.

Types

type Action

type Action string

Action is a type for the action part of a scope.

const (
	ActionRead   Action = "read"
	ActionWrite  Action = "write"
	ActionDelete Action = "delete"
)

type AllowedScopes

type AllowedScopes []Scope

AllowedScopes is a concrete list of allowed scopes that can be registered by a client.

func Allowed

func Allowed() AllowedScopes

Allowed returns all allowed scopes for a client. The caller should use AllowedScopes.Contains for matching requested scopes.

func (AllowedScopes) Contains

func (s AllowedScopes) Contains(scope Scope) bool

Contains returns true if the scope is in the list of allowed scopes. It DOES NOT do prefix matching like Strategy to prevent clients registering free-form and nonsense scopes.

type ParsedScope

type ParsedScope struct {
	Service    services.Service
	Permission Permission
	Action     Action
}

func ParseScope

func ParseScope(scope Scope) (_ ParsedScope, valid bool)

ParseScope parses a scope into its parts. It returns the service, permission, action, and a boolean indicating if the scope is valid.

Not using strings.Split and returning a non-pointer type to achieve "0 allocs/op" based on benchmarks:

go test -bench=. -benchmem -cpu=4

BenchmarkStrategy_Match-4     	 6745492	       156.6 ns/op	       0 B/op	       0 allocs/op
BenchmarkStrategy_NoMatch-4   	 7670725	       155.6 ns/op	       0 B/op	       0 allocs/op

type Permission

type Permission string

Permission is a type for the permission part of a scope.

const (

	// PermissionEnterprisePortalSubscription designates permissions for
	// Enteprrise subscriptions.
	PermissionEnterprisePortalSubscription Permission = "subscription"
	// PermissionEnterprisePortalSubscriptionPermission designates permissions
	// for managing permissions on Enterprise subscriptions.
	PermissionEnterprisePortalSubscriptionPermission Permission = "permission.subscription"

	// PermissionEnterprisePortalCodyAccess designates permissions for Enterprise
	// Cody Access for managed Cody features.
	PermissionEnterprisePortalCodyAccess Permission = "codyaccess"
)

type Scope

type Scope string

Scope is the string literal of a scope.

const (
	OpenID        Scope = "openid"
	Profile       Scope = "profile"
	Email         Scope = "email"
	OfflineAccess Scope = "offline_access"

	// The list of scopes for governing access of a client to a service. For
	// example, "client.ssc" should only be granted to clients that can retrieve SSC
	// data, etc.
	ClientSSC    Scope = "client.ssc"
	ClientDotcom Scope = "client.dotcom"
)

The list of concrete scopes that can be requested by a client.

func ToScope

func ToScope(service services.Service, permission Permission, action Action) Scope

ToScope returns a scope string in the format of "service::permission::action".

type Scopes

type Scopes []Scope

Scopes is a list of scopes.

func ToScopes

func ToScopes(strings []string) Scopes

ToScopes converts a list of strings to a list of scopes.

func (Scopes) Match

func (s Scopes) Match(target Scope) bool

Match returns true if any of the scope in the list matches the target scope using Strategy.