flyio

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: 12 Imported by: 4

README

github.com/superfly/macaroon/flyio

This package contains fly.io-specific caveats.

Documentation

Index

Constants

View Source 
const (
	FeatureWireGuard       = "wg"
	FeatureDomains         = "domain"
	FeatureSites           = "site"
	FeatureRemoteBuilders  = "builder"
	FeatureAddOns          = "addon"
	FeatureChecks          = "checks"
	FeatureLFSC            = "litefs-cloud"
	FeatureMembership      = "membership"
	FeatureBilling         = "billing"
	FeatureDeletion        = "deletion"
	FeatureDocumentSigning = "document_signing"
	FeatureAuthentication  = "authentication"
)
View Source 
const (
	CavOrganization      = macaroon.CavFlyioOrganization
	CavVolumes           = macaroon.CavFlyioVolumes
	CavApps              = macaroon.CavFlyioApps
	CavFeatureSet        = macaroon.CavFlyioFeatureSet
	CavMutations         = macaroon.CavFlyioMutations
	CavMachines          = macaroon.CavFlyioMachines
	CavIsUser            = macaroon.CavFlyioIsUser
	CavMachineFeatureSet = macaroon.CavFlyioMachineFeatureSet
	CavFromMachineSource = macaroon.CavFlyioFromMachineSource
	CavClusters          = macaroon.CavFlyioClusters
	CavIsMember          = macaroon.CavFlyioIsMember
	CavCommands          = macaroon.CavFlyioCommands
	CavAppFeatureSet     = macaroon.CavFlyioAppFeatureSet
	CavStorageObjects    = macaroon.CavFlyioStorageObjects
	CavAllowedRoles      = macaroon.CavAllowedRoles
	CavFlySrc            = macaroon.CavFlyioFlySrc
)
View Source 
const (
	// well-known locations
	LocationPermission        = "https://api.fly.io/v1"
	LocationAuthentication    = "https://api.fly.io/aaa/v1"
	LocationNewAuthentication = "https://auth.fly.io"
	LocationSecrets           = "https://api.fly.io/secrets/v1"
)

Variables

View Source 
var (
	IsPermissionToken = bundle.LocationFilter(LocationPermission).Predicate()
	IsAuthToken       = bundle.LocationFilter(LocationAuthentication).Predicate()
	IsNewAuthToken    = bundle.LocationFilter(LocationNewAuthentication).Predicate()
	IsSecretsToken    = bundle.LocationFilter(LocationSecrets).Predicate()
)
View Source 
var (
	ErrUnauthorizedForRole = fmt.Errorf("%w for role", macaroon.ErrUnauthorized)
)
View Source 
var (
	// MemberFeatures describes the level of access that non-admins are allowed
	// for various org features.
	MemberFeatures = map[string]resset.Action{
		FeatureWireGuard:      resset.ActionAll,
		FeatureDomains:        resset.ActionAll,
		FeatureSites:          resset.ActionAll,
		FeatureRemoteBuilders: resset.ActionAll,
		FeatureAddOns:         resset.ActionAll,
		FeatureChecks:         resset.ActionAll,
		FeatureLFSC:           resset.ActionAll,

		FeatureMembership:     resset.ActionRead,
		FeatureBilling:        resset.ActionRead,
		FeatureAuthentication: resset.ActionRead,

		FeatureDeletion:        resset.ActionNone,
		FeatureDocumentSigning: resset.ActionNone,
	}
)

Functions

func AppScope added in v0.2.6 

func AppScope(cs *macaroon.CaveatSet) []uint64

AppScope finds the IDs of the apps that application queries should be scoped to. This doesn't imply any specific access to the apps, since it disregards caveats requiring specific child/sibling resources and doesn't check for any level of access.

func AppsAllowing added in v0.2.6 

func AppsAllowing(cs *macaroon.CaveatSet, action resset.Action) (uint64, []uint64, error)

WARNING: it is the caller's responsibility to ensure that apps actually belong to the organization before completing an operation for the user!

AppsAllowing gets the set of apps that allow the specified action. An organization ID and a slice of app IDs are returned. A nil slice means that the action is allowed on any org-owned app, which an empty slice (which won't be returned without an accompanying error) means that the action isn't allowed on any apps.

func ClusterScope added in v0.2.6 

func ClusterScope(cs *macaroon.CaveatSet) []string

ClusterScope finds the IDs of the clusters that clusters queries should be scoped to. This doesn't imply any specific access to the clusters , since it disregards caveats requiring specific child/sibling resources and doesn't check for any level of access.

func DangerousUserID added in v0.2.8 

func DangerousUserID(cs *macaroon.CaveatSet) (uint64, error)

DangerousUserID iterates over the caveats to determine the associated user ID. This identity should only be used for logging and auditing. It should not be used for making authorization decisions.

func DischargeClient added in v0.2.0 

func DischargeClient(opts ...tp.ClientOption) *tp.Client

DischargeClient returns a *tp.Client suitable for discharging third party caveats in fly.io permission tokens.

func IsForOrg added in v0.3.0 

func IsForOrg(orgID uint64) bundle.Predicate

IsForOrg returns a Predicate, checking that the token is scoped to the given organization. This doesn't imply any specific level of access to the organization.

func IsForOrgUnverified added in v0.3.0 

func IsForOrgUnverified(oid uint64) bundle.Predicate

IsForOrgUnverified returns a Predicate, checking that the token is scoped to the given organization. Because this operates on unverified tokens, it doesn't imply any level of access to the org or that the selected tokens are valid.

func NonceEmail added in v0.3.0 

func NonceEmail(n macaroon.Nonce) string

NonceEmail is a pseudo-email address for a nonce. It's useful when we want an email address associated with a token.

func OrganizationScope added in v0.2.6 

func OrganizationScope(cs *macaroon.CaveatSet) (uint64, error)

OrganizationScope finds the ID of the organization that application queries should be scoped to. This doesn't imply any specific access to the organization, since it disregards caveats requiring specific child resources and doesn't check for any level of access.

func ParseBundle added in v0.3.0 

func ParseBundle(hdr string) (*bundle.Bundle, error)

func ParseBundleWithFilter added in v0.3.0 

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

func ParsePermissionAndDischargeTokens 

func ParsePermissionAndDischargeTokens(header string) ([]byte, [][]byte, error)

ParseRootAndDischargeTokens takes a string header and parses out the fly.io permission and discharge tokens.

Types

type Access 

type Access struct {
	Action             resset.Action  `json:"action,omitempty"`
	OrgID              *uint64        `json:"orgid,omitempty"`
	AppID              *uint64        `json:"appid,omitempty"`
	AppFeature         *string        `json:"app_feature,omitempty"`
	Feature            *string        `json:"feature,omitempty"`
	Volume             *string        `json:"volume,omitempty"`
	Machine            *string        `json:"machine,omitempty"`
	MachineFeature     *string        `json:"machine_feature,omitempty"`
	Mutation           *string        `json:"mutation,omitempty"`
	SourceMachine      *string        `json:"sourceMachine,omitempty"`
	SourceApp          *string        `json:"sourceApp,omitempty"`
	SourceOrganization *string        `json:"sourceOrganization,omitempty"`
	Cluster            *string        `json:"cluster,omitempty"`
	Command            []string       `json:"command,omitempty"`
	StorageObject      *resset.Prefix `json:"storage_object,omitempty"`
}

func (*Access) GetAction 

func (a *Access) GetAction() resset.Action

func (*Access) GetAppFeature added in v0.3.0 

func (a *Access) GetAppFeature() *string

GetAppFeature implements AppFeatureGetter.

func (*Access) GetAppID added in v0.2.11 

func (a *Access) GetAppID() *uint64

GetAppID implements AppIDGetter.

func (*Access) GetCluster added in v0.2.11 

func (a *Access) GetCluster() *string

GetCluster implements ClusterGetter.

func (*Access) GetCommand added in v0.2.13 

func (a *Access) GetCommand() []string

GetCommand implements CommandGetter.

func (*Access) GetFeature added in v0.2.11 

func (a *Access) GetFeature() *string

GetFeature implements FeatureGetter.

func (*Access) GetMachine added in v0.2.11 

func (a *Access) GetMachine() *string

GetMachine implements MachineGetter.

func (*Access) GetMachineFeature added in v0.2.11 

func (a *Access) GetMachineFeature() *string

GetMachineFeature implements MachineFeatureGetter.

func (*Access) GetMutation added in v0.2.11 

func (a *Access) GetMutation() *string

GetMutation implements MutationGetter.

func (*Access) GetOrgID added in v0.2.11 

func (a *Access) GetOrgID() *uint64

GetOrgID implements OrgIDGetter.

func (*Access) GetPermittedRoles added in v0.3.0 

func (a *Access) GetPermittedRoles() []Role

GetPermittedRoles implements macaroon.PermittedRolesGetter. We require RoleAdmin for unrecognized organization features or features for which the attempted action is not allowed by ordinary members.

func (*Access) GetSourceApp added in v0.3.0 

func (a *Access) GetSourceApp() *string

GetSourceApp implements SourceAppGetter.

func (*Access) GetSourceMachine added in v0.2.11 

func (a *Access) GetSourceMachine() *string

GetSourceMachine implements SourceMachineGetter.

func (*Access) GetSourceOrganization added in v0.3.0 

func (a *Access) GetSourceOrganization() *string

GetSourceOrganization implements SourceOrganizationGetter.

func (*Access) GetStorageObject added in v0.3.0 

func (a *Access) GetStorageObject() *resset.Prefix

GetStorageObject implements StorageObjectGetter.

func (*Access) GetVolume added in v0.2.11 

func (a *Access) GetVolume() *string

GetVolume implements VolumeGetter.

func (*Access) Now 

func (a *Access) Now() time.Time

func (*Access) Validate 

func (f *Access) Validate() error

validate checks that the Access has sensible values set. This consists of ensuring that parent-resources are specified when child-resources are present (e.g. machine requires app requires org) and ensuring that multiple child resources aren't specified for a single parent resource (e.g. machine and volume are mutually exclusive).

This ensure that a Access represents a single action taken on a single object.

type AllowedRoles added in v0.3.0 

type AllowedRoles Role

AllowedRoles is a bitmask of roles that may be assumed. Only usable with Accesses implementing PermittedRolesGetter. Checks that a role returned by [GetPermittedRoles] matches the mask.

func (*AllowedRoles) CaveatType added in v0.3.0 

func (c *AllowedRoles) CaveatType() macaroon.CaveatType

func (*AllowedRoles) Name added in v0.3.0 

func (c *AllowedRoles) Name() string

func (*AllowedRoles) Prohibits added in v0.3.0 

func (c *AllowedRoles) Prohibits(a macaroon.Access) error

type AppFeatureGetter added in v0.3.0 

type AppFeatureGetter interface {
	resset.Access
	GetAppFeature() *string
}

AppFeatureGetter is an interface allowing other packages to implement Accesses that work with Caveats defined in this package.

type AppFeatureSet added in v0.3.0 

type AppFeatureSet struct {
	Features resset.ResourceSet[string, resset.Action] `json:"features"`
}

func (*AppFeatureSet) CaveatType added in v0.3.0 

func (c *AppFeatureSet) CaveatType() macaroon.CaveatType

func (*AppFeatureSet) Name added in v0.3.0 

func (c *AppFeatureSet) Name() string

func (*AppFeatureSet) Prohibits added in v0.3.0 

func (c *AppFeatureSet) Prohibits(a macaroon.Access) error

type AppIDGetter added in v0.2.11 

type AppIDGetter interface {
	resset.Access
	GetAppID() *uint64
}

AppIDGetter is an interface allowing other packages to implement Accesses that work with Caveats defined in this package.

type Apps 

type Apps struct {
	Apps resset.ResourceSet[uint64, resset.Action] `json:"apps"`
}

Apps is a set of App caveats, with their RWX access levels. A token with this set can be used only with the listed apps, regardless of what the token says. Additional Apps can be added, but they can only narrow, not expand, which apps (or access levels) can be reached from the token.

func (*Apps) CaveatType 

func (c *Apps) CaveatType() macaroon.CaveatType

func (*Apps) Name added in v0.0.5 

func (c *Apps) Name() string

func (*Apps) Prohibits 

func (c *Apps) Prohibits(a macaroon.Access) error

type CSV added in v0.3.0 

type CSV []string

func NonceEmails added in v0.3.0 

func NonceEmails(bun *bundle.Bundle) CSV

NonceEmails returns a CSV of the permission token pseudo email addresses for the given bundle.

func UUIDs added in v0.3.0 

func UUIDs(bun *bundle.Bundle) CSV

UUIDs returns a CSV of the permission token UUIDs for the given bundle.

func (CSV) String added in v0.3.0 

func (c CSV) String() string

type ClusterGetter added in v0.2.11 

type ClusterGetter interface {
	resset.Access
	GetCluster() *string
}

ClusterGetter is an interface allowing other packages to implement Accesses that work with Caveats defined in this package.

type Clusters 

type Clusters struct {
	Clusters resset.ResourceSet[string, resset.Action] `json:"clusters"`
}

Clusters is a set of Cluster caveats, with their RWX access levels. Clusters belong to the "litefs-cloud" org-feature.

func (*Clusters) CaveatType 

func (c *Clusters) CaveatType() macaroon.CaveatType

func (*Clusters) Name added in v0.0.5 

func (c *Clusters) Name() string

func (*Clusters) Prohibits 

func (c *Clusters) Prohibits(a macaroon.Access) error

type Command added in v0.2.13 

type Command struct {
	Args  []string `json:"args"`
	Exact bool     `json:"exact,omitempty"`
}

Command is a single command to allow. The zero value allows any command. If exact is true, the args must match exactly. Otherwise the args must match the prefix of the command being executed.

type CommandGetter added in v0.2.13 

type CommandGetter interface {
	macaroon.Access
	GetCommand() []string
}

CommandGetter is an interface allowing other packages to implement Accesses that work with Caveats defined in this package.

type Commands added in v0.2.13 

type Commands []Command

Commands is a list of commands allowed by this token. The zero value rejects any command.

func (*Commands) CaveatType added in v0.2.13 

func (c *Commands) CaveatType() macaroon.CaveatType

func (*Commands) Name added in v0.2.13 

func (c *Commands) Name() string

func (*Commands) Prohibits added in v0.2.13 

func (c *Commands) Prohibits(a macaroon.Access) error

type FeatureGetter added in v0.2.11 

type FeatureGetter interface {
	resset.Access
	GetFeature() *string
}

FeatureGetter is an interface allowing other packages to implement Accesses that work with Caveats defined in this package.

type FeatureSet 

type FeatureSet struct {
	Features resset.ResourceSet[string, resset.Action] `json:"features"`
}

FeatureSet is a collection of organization-level "features" that are managed as single units. For example, the ability to manage wireguard networks is gated by the "wg" feature, though you could conceptually gate access to them individually with a Networks caveat. The feature name is free-form and more should be addded as it makes sense.

func (*FeatureSet) CaveatType 

func (c *FeatureSet) CaveatType() macaroon.CaveatType

func (*FeatureSet) Name added in v0.0.5 

func (c *FeatureSet) Name() string

func (*FeatureSet) Prohibits 

func (c *FeatureSet) Prohibits(a macaroon.Access) error

type FlySrc added in v0.3.0 

type FlySrc struct {
	Organization string `json:"organization"`
	App          string `json:"app"`
	Instance     string `json:"instance"`
}

FlySrc limits tokens to being used by specific machines, based on the Fly-Src header included in flycast requests.

func (*FlySrc) CaveatType added in v0.3.0 

func (c *FlySrc) CaveatType() macaroon.CaveatType

func (*FlySrc) Name added in v0.3.0 

func (c *FlySrc) Name() string

func (*FlySrc) Prohibits added in v0.3.0 

func (c *FlySrc) Prohibits(a macaroon.Access) error

type FromMachine 

type FromMachine struct {
	ID string `json:"id"`
}

func (*FromMachine) CaveatType 

func (c *FromMachine) CaveatType() macaroon.CaveatType

func (*FromMachine) Name added in v0.0.5 

func (c *FromMachine) Name() string

func (*FromMachine) Prohibits 

func (c *FromMachine) Prohibits(a macaroon.Access) error

type IsMember added in v0.3.0 

type IsMember struct{}

IsMember is an alias for RoleMask(RoleMember). It used to be called NoAdminFeatures.

func (*IsMember) CaveatType added in v0.3.0 

func (c *IsMember) CaveatType() macaroon.CaveatType

func (*IsMember) Name added in v0.3.0 

func (c *IsMember) Name() string

func (*IsMember) Prohibits added in v0.3.0 

func (c *IsMember) Prohibits(a macaroon.Access) error

type IsUser 

type IsUser struct {
	ID uint64 `json:"uint64"`
}

deprecated in favor of auth.FlyioUserID

func (*IsUser) CaveatType 

func (c *IsUser) CaveatType() macaroon.CaveatType

func (*IsUser) Name added in v0.0.5 

func (c *IsUser) Name() string

func (*IsUser) Prohibits 

func (c *IsUser) Prohibits(a macaroon.Access) error

type MachineFeatureGetter added in v0.2.11 

type MachineFeatureGetter interface {
	resset.Access
	GetMachineFeature() *string
}

MachineFeatureGetter is an interface allowing other packages to implement Accesses that work with Caveats defined in this package.

type MachineFeatureSet 

type MachineFeatureSet struct {
	Features resset.ResourceSet[string, resset.Action] `json:"features"`
}

func (*MachineFeatureSet) CaveatType 

func (c *MachineFeatureSet) CaveatType() macaroon.CaveatType

func (*MachineFeatureSet) Name added in v0.0.5 

func (c *MachineFeatureSet) Name() string

func (*MachineFeatureSet) Prohibits 

func (c *MachineFeatureSet) Prohibits(a macaroon.Access) error

type MachineGetter added in v0.2.11 

type MachineGetter interface {
	resset.Access
	GetMachine() *string
}

MachineGetter is an interface allowing other packages to implement Accesses that work with Caveats defined in this package.

type Machines 

type Machines struct {
	Machines resset.ResourceSet[string, resset.Action] `json:"machines"`
}

func (*Machines) CaveatType 

func (c *Machines) CaveatType() macaroon.CaveatType

func (*Machines) Name added in v0.0.5 

func (c *Machines) Name() string

func (*Machines) Prohibits 

func (c *Machines) Prohibits(a macaroon.Access) error

type MutationGetter added in v0.2.11 

type MutationGetter interface {
	macaroon.Access
	GetMutation() *string
}

MutationGetter is an interface allowing other packages to implement Accesses that work with Caveats defined in this package.

type Mutations 

type Mutations struct {
	Mutations []string `json:"mutations"`
}

Mutations is a set of GraphQL mutations allowed by this token.

func (*Mutations) CaveatType 

func (c *Mutations) CaveatType() macaroon.CaveatType

func (*Mutations) Name added in v0.0.5 

func (c *Mutations) Name() string

func (*Mutations) Prohibits 

func (c *Mutations) Prohibits(a macaroon.Access) error

type OrgIDGetter added in v0.2.11 

type OrgIDGetter interface {
	resset.Access
	GetOrgID() *uint64
}

OrgIDGetter is an interface allowing other packages to implement Accesses that work with Caveats defined in this package.

type Organization 

type Organization struct {
	ID   uint64        `json:"id"`
	Mask resset.Action `json:"mask"`
}

Organization is an orgid, plus RWX-style access control.

func (*Organization) CaveatType 

func (c *Organization) CaveatType() macaroon.CaveatType

func (*Organization) Name added in v0.0.5 

func (c *Organization) Name() string

func (*Organization) Prohibits 

func (c *Organization) Prohibits(a macaroon.Access) error

type PermittedRolesGetter added in v0.3.0 

type PermittedRolesGetter interface {
	macaroon.Access

	// GetPermittedRoles returns a slice of roles that are allowed to perform the
	// operation.
	GetPermittedRoles() []Role
}

PermittedRolesGetter is an interface for Accesses capable of indicating what roles are allowed for the operation.

type Role added in v0.3.0 

type Role uint32

Role is used by the AllowedRoles and IsMember caveats. 

const (
	RoleMember Role = 1 << iota
	RoleBillingManager

	RoleAdmin Role = 0xFFFFFFFF
)

func (Role) HasAllRoles added in v0.3.0 

func (r Role) HasAllRoles(other Role) bool

HasAllRoles returns whether other is a subset of r.

func (Role) String added in v0.3.0 

func (r Role) String() string

type SourceAppGetter added in v0.3.0 

type SourceAppGetter interface {
	macaroon.Access
	GetSourceApp() *string
}

SourceAppGetter is an interface allowing other packages to implement Accesses that work with Caveats defined in this package.

type SourceMachineGetter added in v0.2.11 

type SourceMachineGetter interface {
	macaroon.Access
	GetSourceMachine() *string
}

SourceMachineGetter is an interface allowing other packages to implement Accesses that work with Caveats defined in this package.

type SourceOrganizationGetter added in v0.3.0 

type SourceOrganizationGetter interface {
	macaroon.Access
	GetSourceOrganization() *string
}

SourceOrganizationGetter is an interface allowing other packages to implement Accesses that work with Caveats defined in this package.

type StorageObjectGetter added in v0.3.0 

type StorageObjectGetter interface {
	resset.Access
	GetStorageObject() *resset.Prefix
}

StorageObjectGetter is an interface allowing other packages to implement Accesses that work with Caveats defined in this package.

type StorageObjects added in v0.3.0 

type StorageObjects struct {
	Prefixes resset.ResourceSet[resset.Prefix, resset.Action] `json:"storage_objects"`
}

StorageObjects limits what storage objects can be accessed. Objects are identified by a URL prefix string, so you can specify just the storage provider (e.g. `https://storage.fly/`), a specific bucket within a storage provider (e.g. `https://storage.fly/my_bucket`), or a object within a bucket (e.g. `https://storage.fly/my_bucket/my_file`).

func (*StorageObjects) CaveatType added in v0.3.0 

func (c *StorageObjects) CaveatType() macaroon.CaveatType

func (*StorageObjects) Name added in v0.3.0 

func (c *StorageObjects) Name() string

func (*StorageObjects) Prohibits added in v0.3.0 

func (c *StorageObjects) Prohibits(a macaroon.Access) error

type VolumeGetter added in v0.2.11 

type VolumeGetter interface {
	resset.Access
	GetVolume() *string
}

VolumeGetter is an interface allowing other packages to implement Accesses that work with Caveats defined in this package.

type Volumes 

type Volumes struct {
	Volumes resset.ResourceSet[string, resset.Action] `json:"volumes"`
}

func (*Volumes) CaveatType 

func (c *Volumes) CaveatType() macaroon.CaveatType

func (*Volumes) Name added in v0.0.5 

func (c *Volumes) Name() string

func (*Volumes) Prohibits 

func (c *Volumes) Prohibits(a macaroon.Access) error

Source Files

View all Source files

Directories

Path Synopsis

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.