authz

Documentation

Overview

Package authz provides Gate (function-based) and Policy (struct-based) authorisation primitives modelled on Laravel's Gate facade.

Two patterns are supported:

1. Gate — register an ability name with a closure. Useful for ad-hoc checks that don't fit a model boundary:

   g := authz.New() authz.Define(g, "manage-billing", func(_ context.Context, u User, _ any) bool { return u.Role == "admin" }) ok, _ := g.Allows(ctx, "manage-billing", currentUser, nil)

2. Policy — a struct whose methods cover the per-resource abilities. Register it once per resource type and the gate routes the ability name to the matching method:

   type PostPolicy struct{} func (PostPolicy) Update(_ context.Context, u User, p Post) bool { return p.AuthorID == u.ID } authz.Policy[Post](g, PostPolicy{}) ok, _ := g.Allows(ctx, "update", currentUser, somePost)

Authorize is the panic-friendlier variant; Check returns the same information without the panic.

Index

• Variables
• func Before[U any](g *Gate[U], fn func(ctx context.Context, user U, ability string) bool)
• func Define[U any, R any](g *Gate[U], ability string, ...)
• func Policy[R any, U any](g *Gate[U], policy any)
• type Decision
• type Gate
  • func New[U any]() *Gate[U]
  • func (g *Gate[U]) Allows(ctx context.Context, ability string, user U, resource any) (bool, error)
  • func (g *Gate[U]) Authorize(ctx context.Context, ability string, user U, resource any) error
  • func (g *Gate[U]) Check(ctx context.Context, ability string, user U, resource any) Decision
  • func (g *Gate[U]) Denies(ctx context.Context, ability string, user U, resource any) bool

Variables

var ErrDenied = errors.New("authz: denied")

ErrDenied is returned by Authorize when a check fails.

var ErrUnknownAbility = errors.New("authz: unknown ability")

ErrUnknownAbility is returned when no gate or policy matches the requested ability.

Functions

func Before

func Before[U any](g *Gate[U], fn func(ctx context.Context, user U, ability string) bool)

Before registers a hook that runs before every check. If it returns true, the check short-circuits to allow. Use sparingly — typically for an "admin can do anything" override.

func Define

func Define[U any, R any](g *Gate[U], ability string, fn func(ctx context.Context, user U, resource R) bool)

Define registers a closure for ability. Re-registration replaces the previous closure.

Use the generic R parameter to let callers receive a typed resource:

authz.Define(g, "delete-post", func(ctx context.Context, u User, p Post) bool { ... })

func Policy

func Policy[R any, U any](g *Gate[U], policy any)

Policy registers a policy struct for resource type R. Each exported method on the policy whose name matches an ability (case-insensitive, kebab/snake-aware) and whose signature is one of:

func(ctx context.Context, user U, resource R) bool
func(ctx context.Context, user U, resource R) (bool, error)

is registered. Methods that don't match are ignored.

Types

type Decision

type Decision struct {
	Allowed bool
	Reason  string
}

Decision captures the result of a check.

type Gate

type Gate[U any] struct {
	// contains filtered or unexported fields
}

Gate is the registry that routes ability names to closures and resource-typed methods on registered policies. Safe for concurrent use.

func New

func New[U any]() *Gate[U]

New returns a fresh Gate parameterised on the user type.

func (*Gate[U]) Allows

func (g *Gate[U]) Allows(ctx context.Context, ability string, user U, resource any) (bool, error)

Allows reports whether user is permitted to perform ability on the (optional) resource. Resource may be nil for gate-only abilities.

func (*Gate[U]) Authorize

func (g *Gate[U]) Authorize(ctx context.Context, ability string, user U, resource any) error

Authorize is Allows that returns ErrDenied instead of (false, nil). Idiomatic in handler code:

if err := gate.Authorize(ctx, "update", user, post); err != nil {
    return err
}

func (*Gate[U]) Check

func (g *Gate[U]) Check(ctx context.Context, ability string, user U, resource any) Decision

Check returns a Decision so callers can render rich responses.

func (*Gate[U]) Denies

func (g *Gate[U]) Denies(ctx context.Context, ability string, user U, resource any) bool

Denies is the boolean opposite of Allows. Errors collapse to denial.