Documentation
¶
Overview ¶
Package authorization provides stable helpers for API authorization boundaries.
Use Require with an Authorizer when a route needs an explicit policy decision. The package-local authorization and policy aliases remain exactly source-compatible with their root ports counterparts during v3. AllowlistAuthorizer is a small default-deny implementation for simple route/action maps, while owner, tenant, scope, and actor helpers cover common BOLA and multi-tenant checks.
This package is part of the stable core API surface. For runnable authz and policy examples, see docs/cookbook.md and contrib/examples/README.md.
Purpose: See the package summary above. Import: `github.com/aatuh/api-toolkit/v4/authorization`. Example: See docs/api-reference.md for package example links and docs/cookbook.md for task recipes. Errors: Constructors, parsers, and handlers return or write documented errors according to their signatures; packages with plain data types do not add hidden error channels. Concurrency: Treat configured middleware and helpers as immutable after construction; request and response values remain request-scoped unless a type documents stronger guarantees. Stability: Stable core API under VERSIONING.md and scripts/apicheck.sh. When not to use: Prefer net/http, application-owned types, or narrower helpers when this package contract is not needed.
Index ¶
- func ApplyScope(filters map[string]any, scope Scope) map[string]any
- func MaskFields(input map[string]any, denied []string) map[string]any
- func ProjectFields(input map[string]any, allowed []string) map[string]any
- func Require(ctx context.Context, auth Authorizer, subject any, action string, resource any) error
- func RequireOwner(subjectID string, resource Owner) error
- func RequireOwnerID(subjectID, ownerID string) error
- func RequireTenant(tenantID string, resource TenantOwned) error
- func TenantIDFromContext(ctx context.Context) (string, bool)
- func WithActor(ctx context.Context, actor Actor) context.Context
- func WithScope(ctx context.Context, scope Scope) context.Context
- type Actor
- type AllowlistAuthorizer
- func (a *AllowlistAuthorizer) Allow(action string, auth Authorizer) error
- func (a *AllowlistAuthorizer) AllowAny(action string) error
- func (a *AllowlistAuthorizer) AllowFunc(action string, fn AuthorizerFunc) error
- func (a *AllowlistAuthorizer) Can(ctx context.Context, subject any, action string, resource any) error
- type Authorizer
- type AuthorizerFunc
- type Owner
- type PolicyAuthorizer
- type PolicyAuthorizerOptions
- type PolicyContextProvider
- type PolicyDecision
- type PolicyEngine
- type PolicyRequest
- type Scope
- type TenantOwned
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ApplyScope ¶
ApplyScope merges scope filters into an existing filter map.
Example ¶
package main
import (
"fmt"
"github.com/aatuh/api-toolkit/v4/authorization"
)
func main() {
filters := authorization.ApplyScope(
map[string]any{"status": "active"},
authorization.Scope{TenantID: "tenant-1", UserID: "user-1"},
)
fmt.Println(filters["status"])
fmt.Println(filters["tenant_id"])
fmt.Println(filters["user_id"])
}
Output: active tenant-1 user-1
func MaskFields ¶
MaskFields returns a new map without the denied keys.
func ProjectFields ¶
ProjectFields returns a new map with only the allowed keys.
func RequireOwner ¶
RequireOwner enforces ownership using an Owner interface.
func RequireOwnerID ¶
RequireOwnerID enforces resource ownership (BOLA).
func RequireTenant ¶
func RequireTenant(tenantID string, resource TenantOwned) error
RequireTenant enforces tenant scoping.
func TenantIDFromContext ¶
TenantIDFromContext returns the tenant identifier from context scope.
Types ¶
type AllowlistAuthorizer ¶
type AllowlistAuthorizer struct {
// contains filtered or unexported fields
}
AllowlistAuthorizer enforces explicit allow rules for actions. Missing rules default to forbidden.
func NewAllowlistAuthorizer ¶
func NewAllowlistAuthorizer() *AllowlistAuthorizer
NewAllowlistAuthorizer creates an allowlist-based authorizer.
func (*AllowlistAuthorizer) Allow ¶
func (a *AllowlistAuthorizer) Allow(action string, auth Authorizer) error
Allow registers an authorizer for a specific action.
func (*AllowlistAuthorizer) AllowAny ¶
func (a *AllowlistAuthorizer) AllowAny(action string) error
AllowAny permits the specified action without additional checks.
func (*AllowlistAuthorizer) AllowFunc ¶
func (a *AllowlistAuthorizer) AllowFunc(action string, fn AuthorizerFunc) error
AllowFunc registers an authorizer function for a specific action.
type Authorizer ¶
type Authorizer interface {
Can(ctx context.Context, subject any, action string, resource any) error
}
Authorizer checks whether a subject can perform an action on a resource.
type AuthorizerFunc ¶
AuthorizerFunc adapts a function to the Authorizer contract.
type Owner ¶
type Owner interface {
OwnerID() string
}
Owner exposes ownership information for BOLA checks.
type PolicyAuthorizer ¶
type PolicyAuthorizer struct {
// contains filtered or unexported fields
}
PolicyAuthorizer adapts a policy engine to the Authorizer interface.
func NewPolicyAuthorizer ¶
func NewPolicyAuthorizer(engine PolicyEngine, opts PolicyAuthorizerOptions) *PolicyAuthorizer
NewPolicyAuthorizer creates an authorizer backed by a policy engine.
type PolicyAuthorizerOptions ¶
type PolicyAuthorizerOptions struct {
ContextProvider PolicyContextProvider
DenyOnError bool
}
PolicyAuthorizerOptions configures a policy-backed authorizer.
type PolicyContextProvider ¶
PolicyContextProvider supplies contextual attributes for policy evaluation.
type PolicyDecision ¶
PolicyDecision represents a policy evaluation outcome.
type PolicyEngine ¶
type PolicyEngine interface {
Evaluate(ctx context.Context, req PolicyRequest) (PolicyDecision, error)
}
PolicyEngine evaluates policy requests.
type PolicyRequest ¶
PolicyRequest captures policy engine evaluation inputs.
type Scope ¶
Scope captures tenant/user scoping hints for repositories.
func ScopeFromContext ¶
ScopeFromContext retrieves the authorization scope from context.
type TenantOwned ¶
type TenantOwned interface {
TenantID() string
}
TenantOwned exposes tenant ownership for scoping checks.
Source Files