authz

Documentation

Overview

Package authz contains the permission model primitives used by the SDK: PermissionKey, PermissionDefinition, the Resolver interface that maps roles → permissions, and the context-aware HasPermission helper.

Index

• Variables
• func HasAllPermissions(targets []PermissionKey, granted []string) bool
• func HasAnyPermission(targets []PermissionKey, granted []string) bool
• func HasPermission(target PermissionKey, granted []string) bool
• func Matches(target PermissionKey, granted string) bool
• func MustPermission(ctx context.Context, perm PermissionKey) error
• func WithUser(ctx context.Context, u *User) context.Context
• type Actor
• type HttpResolver
  • func NewHttpResolver(client ResolveClient, opts HttpResolverOptions) (*HttpResolver, error)
  • func (r *HttpResolver) Clear()
  • func (r *HttpResolver) Invalidate(clientID string, roles []string)
  • func (r *HttpResolver) Resolve(ctx context.Context, clientID string, roles []string) ([]string, error)
• type HttpResolverOptions
• type InvalidPermissionError
  • func (e *InvalidPermissionError) Error() string
• type PermissionDefinition
  • func (d PermissionDefinition) Key() PermissionKey
• type PermissionKey
  • func ParsePermission(s string) (PermissionKey, error)
  • func (k PermissionKey) Authority() string
  • func (k PermissionKey) IsConcrete() bool
  • func (k PermissionKey) IsZero() bool
  • func (k PermissionKey) String() string
• type ResolveClient
• type ResolvePermissionsResponse
• type Resolver
• type ResolverFunc
  • func (f ResolverFunc) Resolve(ctx context.Context, clientID string, roles []string) ([]string, error)
• type User
  • func FromContext(ctx context.Context) *User
  • func (u *User) HasMFA() bool
  • func (u *User) HasPermission(resource, action string) bool
  • func (u *User) IsImpersonating() bool

Variables

var (
	ErrUnauthenticated = errors.New("authz: unauthenticated")
	ErrForbidden       = errors.New("authz: forbidden")
)

Errors returned from the context helpers.

Functions

func HasAllPermissions

func HasAllPermissions(targets []PermissionKey, granted []string) bool

HasAllPermissions reports whether every target is satisfied by granted.

func HasAnyPermission

func HasAnyPermission(targets []PermissionKey, granted []string) bool

HasAnyPermission reports whether at least one target is satisfied by granted.

func HasPermission

func HasPermission(target PermissionKey, granted []string) bool

HasPermission reports whether any of the granted permission strings satisfies target.

func Matches

func Matches(target PermissionKey, granted string) bool

Matches reports whether a granted permission string satisfies the target. Matching rules (aligned with sdk-js / sdk-java):

• exact match: "orders:read" matches "orders:read"
• action wildcard: "orders:*" matches "orders:read" and "orders:create"
• full wildcard: "*:*" matches everything
• resource-agnostic action wildcard "*:read" is rejected
• malformed or non-canonical entries never match
• matching is case sensitive

func MustPermission

func MustPermission(ctx context.Context, perm PermissionKey) error

MustPermission returns an error if the current context does not satisfy perm.

func WithUser

func WithUser(ctx context.Context, u *User) context.Context

WithUser returns a new context carrying u.

Types

type Actor

type Actor struct {
	Subject string
}

Actor is the delegating subject for impersonation (JWT act claim).

type HttpResolver

type HttpResolver struct {
	// contains filtered or unexported fields
}

HttpResolver resolves role → permission mappings via the IAM /open/v1 API with a local ristretto cache and singleflight deduplication.

func NewHttpResolver

func NewHttpResolver(client ResolveClient, opts HttpResolverOptions) (*HttpResolver, error)

NewHttpResolver wires up a resolver backed by ristretto.

func (*HttpResolver) Clear

func (r *HttpResolver) Clear()

Clear evicts every cached entry.

func (*HttpResolver) Invalidate

func (r *HttpResolver) Invalidate(clientID string, roles []string)

Invalidate drops the cached mapping for a (clientID, roles) pair.

func (*HttpResolver) Resolve

func (r *HttpResolver) Resolve(ctx context.Context, clientID string, roles []string) ([]string, error)

Resolve implements Resolver.

type HttpResolverOptions

type HttpResolverOptions struct {
	TTL        time.Duration
	MaxEntries int64
	FailOpen   bool
}

HttpResolverOptions configures an HttpResolver.

type InvalidPermissionError

type InvalidPermissionError struct{ Raw string }

InvalidPermissionError is returned when a permission string is malformed.

func (*InvalidPermissionError) Error

func (e *InvalidPermissionError) Error() string

type PermissionDefinition

type PermissionDefinition struct {
	Resource    string
	Action      string
	Description string
}

PermissionDefinition is a permission declaration — the registered form uploaded to the IAM server and referenced by codegen.

func (PermissionDefinition) Key

func (d PermissionDefinition) Key() PermissionKey

Key returns the PermissionKey corresponding to this definition.

type PermissionKey

type PermissionKey struct {
	Resource string
	Action   string
}

PermissionKey is the canonical identifier for a permission — a pair of resource and action strings.

func ParsePermission

func ParsePermission(s string) (PermissionKey, error)

ParsePermission parses a "resource:action" string. Empty components and missing colons yield an error.

func (PermissionKey) Authority

func (k PermissionKey) Authority() string

Authority returns the "resource:action" string form used on the wire.

func (PermissionKey) IsConcrete

func (k PermissionKey) IsConcrete() bool

IsConcrete reports whether the key is a canonical non-wildcard declaration key.

func (PermissionKey) IsZero

func (k PermissionKey) IsZero() bool

IsZero reports whether the key is empty.

func (PermissionKey) String

func (k PermissionKey) String() string

String implements fmt.Stringer and returns the same as Authority.

type ResolveClient

type ResolveClient interface {
	ResolvePermissions(ctx context.Context, clientID string, roles []string) (*ResolvePermissionsResponse, error)
}

ResolveClient is the minimum surface HttpResolver needs from the IAM client. It is satisfied by *iam.Client.

type ResolvePermissionsResponse

type ResolvePermissionsResponse struct {
	Permissions []string `json:"permissions"`
}

ResolvePermissionsResponse must match the shape returned by the IAM server. It is redeclared here (rather than imported from the top-level iam package) to avoid an import cycle.

type Resolver

type Resolver interface {
	Resolve(ctx context.Context, clientID string, roles []string) ([]string, error)
}

Resolver maps a (clientID, roles) tuple to the flat list of permissions the user holds. Implementations may cache, fall back or fail open.

type ResolverFunc

type ResolverFunc func(ctx context.Context, clientID string, roles []string) ([]string, error)

ResolverFunc adapts a plain function into a Resolver.

func (ResolverFunc) Resolve

func (f ResolverFunc) Resolve(ctx context.Context, clientID string, roles []string) ([]string, error)

Resolve implements Resolver.

type User

type User struct {
	Subject     string
	AppID       string
	Email       string
	OrgID       string
	OrgRole     string
	WorkspaceID string
	SessionID   string
	Roles       []string
	Permissions []string
	AMR         []string
	ACR         string
	Actor       *Actor
	Claims      map[string]any
}

User is the authenticated caller as seen by the request-scoped context.

func FromContext

func FromContext(ctx context.Context) *User

FromContext returns the User previously stored with WithUser, or nil.

func (*User) HasMFA

func (u *User) HasMFA() bool

HasMFA reports whether the JWT's amr claim includes an MFA factor.

func (*User) HasPermission

func (u *User) HasPermission(resource, action string) bool

HasPermission mirrors the package-level HasPermission against this user's permission list.

func (*User) IsImpersonating

func (u *User) IsImpersonating() bool

IsImpersonating reports whether the current request is an admin acting as another user.