Route Authorization

The authz package provides route-level and method-level authorization rules with a first-match-wins, default-deny route rule DSL.

Import

import "github.com/thuongh2/go-security/authz"

mwf, err := authz.Routes(
    authz.Match("/admin/**").HasRole("ADMIN"),
    authz.Match("/api/**").Authenticated(),
    authz.Match("/public/**").PermitAll(),
    authz.AnyRequest().Authenticated(),
)
if err != nil {
    log.Fatal(err)
}

Rules are evaluated top-to-bottom. The first matching rule decides the outcome. AnyRequest() is a required catch-all — omitting it causes Routes() to return an error (unless AllowUnmatched() is set, see below).

Path matching

Pattern	Matches
`/admin/**`	`/admin/`, `/admin/users`, `/admin/users/1`
`/api/v1/*`	`/api/v1/users` but NOT `/api/v1/users/1`
`/login`	Exact path only

Method-scoped rules

Match takes the path pattern plus an optional list of HTTP methods:

mwf, err := authz.Routes(
    authz.Match("/items/**", http.MethodPost).HasRole("WRITER"),
    authz.Match("/items/**").Authenticated(),
    authz.AnyRequest().Authenticated(),
)
if err != nil {
    log.Fatal(err)
}

For a matching predicate Match can’t express, drop to MatchRequest, which takes a single middleware.RequestMatcher built from the web/middleware combinators:

import "github.com/thuongh2/go-security/web/middleware"

mwf, err := authz.Routes(
    authz.MatchRequest(middleware.And(
        middleware.Matcher("/items/**"),
        middleware.ByMethod(http.MethodPost, http.MethodPut),
    )).HasRole("WRITER"),
    authz.AnyRequest().Authenticated(),
)
if err != nil {
    log.Fatal(err)
}

Authorizers

HasRole / HasAnyRole

.HasRole("ADMIN")               // ROLE_ADMIN (auto-prefixed)
.HasAnyRole("ADMIN", "SUPER")   // ROLE_ADMIN or ROLE_SUPER

Role checks are hierarchy-aware when WithHierarchy is configured.

HasAuthority / HasAnyAuthority

.HasAuthority("read:reports")
.HasAnyAuthority("read:reports", "admin:all")

Exact string match; no prefix is added.

Authenticated / Anonymous / PermitAll / DenyAll

.Authenticated()  // Any non-anonymous principal
.Anonymous()      // Only ROLE_ANONYMOUS
.PermitAll()      // Always grants
.DenyAll()        // Always denies

Access (custom)

Access takes an Authorizer — func(ctx, auth, target) Decision — not a plain boolean predicate, so it composes with hierarchy and audit like every other verb:

mwf, err := authz.Routes(
    authz.Match("/api/internal/**").Access(authz.AuthorizerFunc(func(ctx context.Context, auth core.Authentication, target any) authz.Decision {
        if auth.Authenticated() && strings.HasPrefix(auth.Name(), "svc-") {
            return authz.Grant("service account")
        }
        return authz.Deny("not a service account")
    })),
    authz.AnyRequest().Authenticated(),
)
if err != nil {
    log.Fatal(err)
}

Composing authorizers

AllOf, AnyOf, and Negate combine authorizers into larger boolean rules:

writerInDept := authz.AllOf(
    authz.HasRole("WRITER"),
    authz.HasAuthority("dept:eng"),
)

adminOrOwner := authz.AnyOf(
    authz.HasRole("ADMIN"),
    authz.HasAuthority("owner"),
)

readOnly := authz.Negate(authz.HasRole("WRITER"))

mwf, err := authz.Routes(
    authz.Match("/docs/**", http.MethodPost).Access(writerInDept),
    authz.AnyRequest().Authenticated(),
)
if err != nil {
    log.Fatal(err)
}

Role Hierarchy

Build a RoleHierarchy from a > string spec with ParseRoleHierarchy. Segments separated by > mean “the left role includes the right role”; chains ("A > B > C") and newline-separated edges are both accepted, and may be mixed:

hierarchy, err := authz.ParseRoleHierarchy(`
    SUPER > ADMIN
    ADMIN > USER
`)
if err != nil {
    log.Fatal(err)
}

…or programmatically from an adjacency map with NewMapRoleHierarchy:

hierarchy, err := authz.NewMapRoleHierarchy(map[core.Authority][]core.Authority{
    core.RoleAuthority("SUPER"): {core.RoleAuthority("ADMIN")},
    core.RoleAuthority("ADMIN"): {core.RoleAuthority("USER")},
})

Both return an error on a cycle. Apply the hierarchy when starting the route set with WithHierarchy — it is a Routes() option:

mwf, err := authz.Routes(
    authz.WithHierarchy(hierarchy),
    authz.Match("/admin/**").HasRole("ADMIN"),
    authz.AnyRequest().Authenticated(),
)
if err != nil {
    log.Fatal(err)
}

A user with ROLE_SUPER automatically passes HasRole("ADMIN") and HasRole("USER").

Audit hooks

WithAuthzPublisher is a Routes() option that emits a granted/denied event for every decision, via event.AuthzPublisher. event.FuncAuthzPublisher adapts plain functions so a one-off publisher doesn’t need its own named type:

import "github.com/thuongh2/go-security/core/event"

publisher := event.FuncAuthzPublisher{
    OnDenied: func(ctx context.Context, auth core.Authentication, target any, reason string) {
        log.Printf("authz: denied user=%s reason=%s", auth.Name(), reason)
    },
}

mwf, err := authz.Routes(
    authz.WithAuthzPublisher(publisher),
    authz.Match("/admin/**").HasRole("ADMIN"),
    authz.AnyRequest().Authenticated(),
)
if err != nil {
    log.Fatal(err)
}

To audit a single Authorizer outside of Routes/Guard (e.g. before Check), wrap it with NewAuditingAuthorizer:

audited := authz.NewAuditingAuthorizer(authz.HasRole("ADMIN"), publisher)

Method-level guards

Guard wraps an Authorizer into a reusable closure for method-level checks — an explicit function call instead of a reflection-based annotation. It resolves the subject from ctx and returns nil on grant, or an error wrapping core.ErrUnauthenticated / core.ErrAccessDenied on deny:

var checkAdmin = authz.Guard(authz.HasRole("ADMIN"))

func (s *Service) DeleteUser(ctx context.Context, id string) error {
    if err := checkAdmin(ctx, nil); err != nil {
        return err
    }
    // ...
}

Check is the one-shot form when a reusable closure isn’t needed:

if err := authz.Check(ctx, authz.HasRole("ADMIN"), nil); err != nil {
    return err
}

Guard accepts the same hierarchy and audit options as Routes, scoped to this one guard via GuardWithHierarchy / GuardWithAuthzPublisher:

var checkAdmin = authz.Guard(authz.HasRole("ADMIN"),
    authz.GuardWithHierarchy(hierarchy),
    authz.GuardWithAuthzPublisher(publisher),
)

Exception translation (401 vs 403)

ExceptionTranslation is the single source of truth for the 401-vs-403 branch: an unauthenticated or anonymous caller gets the AuthenticationEntryPoint (401), an authenticated caller gets the AccessDeniedHandler (403). The zero value uses the built-in defaults (DefaultAuthenticationEntryPoint, DefaultAccessDeniedHandler), so overriding is opt-in via the WithExceptionTranslation Routes() option:

translation := authz.ExceptionTranslation{
    EntryPoint: authz.EntryPointFunc(func(w http.ResponseWriter, r *http.Request, reason string) {
        http.Error(w, "please log in", http.StatusUnauthorized)
    }),
    DeniedHandler: authz.AccessDeniedFunc(func(w http.ResponseWriter, r *http.Request, reason string) {
        http.Error(w, "not allowed", http.StatusForbidden)
    }),
}

mwf, err := authz.Routes(
    authz.WithExceptionTranslation(translation),
    authz.Match("/admin/**").HasRole("ADMIN"),
    authz.AnyRequest().Authenticated(),
)
if err != nil {
    log.Fatal(err)
}

Default-deny escape hatches

Building Routes() without an AnyRequest() rule fails by design (default-deny completeness). AllowUnmatched() is the explicit, named opt-out for a permit-by-default chain — prefer a declared AnyRequest() rule when you can:

mwf, err := authz.Routes(
    authz.AllowUnmatched(),
    authz.Match("/admin/**").HasRole("ADMIN"),
)
if err != nil {
    log.Fatal(err)
}

OnRuleShadowed is a best-effort build-time lint: it warns when an earlier permissive path rule (PermitAll/Authenticated) prefixes a later, more restrictive rule, which would otherwise silently shadow it:

mwf, err := authz.Routes(
    authz.OnRuleShadowed(func(earlier, later authz.RuleInfo) {
        log.Printf("authz: rule %d (%s) may shadow rule %d (%s)",
            earlier.Index, earlier.Pattern, later.Index, later.Pattern)
    }),
    authz.Match("/admin/**").PermitAll(),
    authz.Match("/admin/secrets").HasRole("ADMIN"),
    authz.AnyRequest().Authenticated(),
)
if err != nil {
    log.Fatal(err)
}

Design notes

AnyRequest() is required or Routes() errors — opt out with authz.AllowUnmatched()
method-level checks are explicit calls: authz.Guard(...) / authz.Check(ctx, ...)
role hierarchy via authz.ParseRoleHierarchy("ADMIN > USER") / authz.NewMapRoleHierarchy(...)
authz events via authz.WithAuthzPublisher(...) / authz.GuardWithAuthzPublisher(...)
error translation via authz.WithExceptionTranslation(...)

Foundation

Authentication

Authorization

Session & Cookies

OAuth2 & JWT

HTTP Layer

Resilience

Observability

Distributed Stores

Route Authorization

Import