README
¶
Install
togo install togo-framework/authz
authz is the togo answer to Laravel Policies / Pundit / django-guardian. RBAC tells you a user's roles; authz decides the specific question "may this subject perform this action on this resource?" — ownership, tenancy, state, and any custom rule.
- Policies — per-resource-type, per-action rules (
updateaPostonly if you authored it). - Gates — standalone abilities with no specific resource (
access-admin). - Before hooks — short-circuit every check (super-admin bypass, maintenance lock).
- Default deny — unknown action/resource is denied; nothing is allowed by omission.
Usage
// Policies — keyed by authz.TypeName(resource), e.g. "*models.Post".
authz.Policy("*models.Post", map[string]authz.PolicyFunc{
"update": func(ctx context.Context, subject, resource any) (bool, error) {
return resource.(*models.Post).AuthorID == subject.(*models.User).ID, nil
},
"delete": func(ctx context.Context, subject, resource any) (bool, error) {
return subject.(*models.User).Admin, nil
},
})
// Gates — standalone abilities.
authz.RegisterGate("access-admin", func(ctx context.Context, s any) (bool, error) {
return s.(*models.User).Admin, nil
})
// Before — super-admin bypass.
authz.Before(func(ctx context.Context, s any, action string) (decided, allow bool) {
if u, ok := s.(*models.User); ok && u.SuperAdmin {
return true, true
}
return false, false
})
Checking access
ok, err := authz.Can(ctx, user, "update", post) // policy (resource non-nil)
ok2 := authz.Allows(ctx, user, "access-admin", nil) // gate (resource nil); error → deny
if err := authz.Authorize(ctx, user, "update", post); err != nil {
return err // authz.ErrForbidden when denied
}
Guarding routes
ctx := authz.WithSubject(r.Context(), currentUser) // usually set by your auth middleware
r.With(authz.Require("access-admin")).Get("/admin", adminHandler) // 403 if denied
REST + kernel
| Endpoint | |
|---|---|
GET /api/authz/can?action=<gate> |
gate check for the context subject |
GET /api/authz/abilities |
registered gates + policy types/actions |
s, _ := authz.FromKernel(k) returns the service (Can / Allows / Authorize).
Configuration
No env required. Composes with togo install togo-framework/auth (read roles off the subject in your policies) but works standalone with any subject type.
Documentation
¶
Overview ¶
Package authz adds policy- and gate-based authorization to togo — the layer above RBAC (Laravel Policies / Pundit / django-guardian for togo).
A POLICY answers "may this subject perform ACTION on this RESOURCE?" and is registered per resource type. A GATE answers a standalone ability with no specific resource ("may this subject access-admin?"). BEFORE hooks run first and can short-circuit every check (e.g. a super-admin bypass).
authz.Policy("models.Post", map[string]authz.PolicyFunc{
"update": func(ctx context.Context, subject, resource any) (bool, error) {
return resource.(*Post).AuthorID == subject.(*User).ID, nil
},
})
ok, _ := authz.Can(ctx, user, "update", post)
Index ¶
- Variables
- func Allows(ctx context.Context, subject any, action string, resource any) bool
- func Authorize(ctx context.Context, subject any, action string, resource any) error
- func Before(fn BeforeFunc)
- func Can(ctx context.Context, subject any, action string, resource any) (bool, error)
- func Denies(ctx context.Context, subject any, action string, resource any) bool
- func Policy(resourceType string, actions map[string]PolicyFunc)
- func RegisterGate(name string, fn GateFunc)
- func Registry() map[string]any
- func Require(action string) func(http.Handler) http.Handler
- func Reset()
- func SubjectFrom(ctx context.Context) any
- func TypeName(resource any) string
- func WithSubject(ctx context.Context, subject any) context.Context
- type BeforeFunc
- type GateFunc
- type PolicyFunc
- type Service
Constants ¶
This section is empty.
Variables ¶
var ErrForbidden = fmt.Errorf("authz: forbidden")
ErrForbidden is returned by Authorize when access is denied.
Functions ¶
func Before ¶
func Before(fn BeforeFunc)
Before registers a pre-check hook (evaluated in registration order).
func Can ¶
Can reports whether subject may perform action. When resource is non-nil the decision uses the per-resource Policy registered for TypeName(resource); otherwise it uses the Gate named action. Unknown action/resource → deny. Before hooks are consulted first and can short-circuit.
func Policy ¶
func Policy(resourceType string, actions map[string]PolicyFunc)
Policy registers per-action policies for a resource type. The key should match TypeName(resource) for the resources you'll check (e.g. "*models.Post").
func RegisterGate ¶
RegisterGate registers a standalone ability handler.
func Require ¶
Require is HTTP middleware that allows the request only if the context subject passes the gate ability; otherwise it responds 403.
func SubjectFrom ¶
SubjectFrom returns the subject stored by WithSubject (nil if none).
Types ¶
type BeforeFunc ¶
BeforeFunc runs before any check. If it returns decided=true its allow value short-circuits the whole check (use it for super-admin bypass, global locks…).
type PolicyFunc ¶
PolicyFunc decides whether subject may perform action on a specific resource.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service is the authz runtime stored on the kernel (k.Get("authz")). The policy/gate registries are package-global; the service exposes them over the kernel + REST and carries the kernel for integrations.
func FromKernel ¶
FromKernel returns the authz Service registered on the kernel.
Source Files