# actor

```go
import "apistock.dev/actor"
```

Package actor records who is performing an operation, in a [context.Context](https://pkg.go.dev/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, …

```go
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](#Require). Check them with [errors.Is](https://pkg.go.dev/errors#Is).

### var Anonymous

```go
var Anonymous = Actor{Kind: KindAnonymous}
```

Anonymous is the actor for unauthenticated operations.

## Functions

### func Require

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

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

### func With

```go
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

```go
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

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

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

#### func FromOrAnonymous

```go
func FromOrAnonymous(ctx context.Context) Actor
```

FromOrAnonymous returns the actor stored in ctx, or [Anonymous](#Anonymous).

#### func System

```go
func System(name string) Actor
```

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

#### func (Actor) Can

```go
func (a Actor) Can(permission string) bool
```

Can reports whether the actor holds permission.

### type Kind

```go
type Kind string
```

Kind classifies an actor.

#### const KindUser, …

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

Actor kinds.