actor · apistock docs

import "apistock.dev/actor"Source on GitHub

Package actor records who is performing an operation, in a context.Context. It knows nothing about how the actor was authenticated; authentication middleware sets the actor, and audit, jobs and use cases read it (ADR-0030).

Stability: pre-1.0 (ADR-0015).

Variables#

var ErrUnauthenticated, …#

var (
	// ErrUnauthenticated reports an operation without an actor, or with
	// the anonymous actor.
	ErrUnauthenticated = errors.New("actor: authentication required")
	// ErrForbidden reports an actor without the permission.
	ErrForbidden = errors.New("actor: permission denied")
	// ErrStepUpRequired reports an actor whose roles grant the permission
	// only after a stronger sign-in, such as two-factor authentication.
	ErrStepUpRequired = errors.New("actor: stronger sign-in required")
)

Errors returned by Require. Check them with errors.Is.

var Anonymous#

var Anonymous = Actor{Kind: KindAnonymous}

Anonymous is the actor for unauthenticated operations.

Functions#

func Require#

func Require(ctx context.Context, permission string) error

Require checks that the actor in ctx holds permission. It returns ErrUnauthenticated without an actor, ErrStepUpRequired when the permission is in the actor's StepUp, and ErrForbidden otherwise.

func With#

func With(ctx context.Context, a Actor) context.Context

With returns a copy of ctx carrying a. The permission slices are copied.

Types#

type Actor#

type Actor struct {
	Kind Kind
	// ID is the stable identifier (for example a user ID). Empty for anonymous actors.
	ID string
	// Label is a human-readable name captured at the time of the action.
	Label string
	// OrgID is the organisation the actor is acting in, if any.
	OrgID string
	// Permissions are the permissions granted for this operation.
	Permissions []string
	// StepUp are permissions the actor's roles grant but this operation
	// doesn't get until the actor signs in more strongly, for example with
	// two-factor authentication. They are never granted by Can.
	StepUp []string
}

An Actor is the identity performing an operation.

func From#

func From(ctx context.Context) (Actor, bool)

From returns the actor stored in ctx and whether one was set.

func FromOrAnonymous#

func FromOrAnonymous(ctx context.Context) Actor

FromOrAnonymous returns the actor stored in ctx, or Anonymous.

func System#

func System(name string) Actor

System returns an actor for work the application performs itself, such as a scheduled job.

func (Actor) Can#

func (a Actor) Can(permission string) bool

Can reports whether the actor holds permission.

type Kind#

type Kind string

Kind classifies an actor.

const KindUser, …#

const (
	KindUser      Kind = "user"
	KindService   Kind = "service"
	KindSystem    Kind = "system"
	KindAnonymous Kind = "anonymous"
)

Actor kinds.