authz

type AllowAllAuthorizer ¶

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

AllowAllAuthorizer is an Authorizer that grants every capability. It is intended for dev/test environments where RBAC enforcement is explicitly disabled via configuration. It must never be used in production.

func NewAllowAllAuthorizer(metadata PolicyMetadata) *AllowAllAuthorizer

func (a *AllowAllAuthorizer) Can(_ context.Context, _ *auth.PrincipalContext, cap Capability) (*Decision, error)

func (a *AllowAllAuthorizer) Metadata() PolicyMetadata

func (a *AllowAllAuthorizer) Privileges(_ context.Context, _ *auth.PrincipalContext) (Privilege, error)

type Authorizer ¶

type Authorizer interface {
	// Privileges returns the full capability set for the principal. It returns
	// nil when the principal has no recognised roles (not an error). Callers
	// should treat a nil Privilege as "no capabilities".
	Privileges(ctx context.Context, principalCtx *auth.PrincipalContext) (Privilege, error)

	// Can checks whether the principal holds cap. A non-nil *Decision is
	// returned for every policy outcome; nil only on infrastructure errors.
	// Use errors.Is(err, ErrUnauthorized) to detect a missing principal, and
	// errors.Is(err, ErrForbidden) to detect a policy denial.
	Can(ctx context.Context, principalCtx *auth.PrincipalContext, cap Capability) (*Decision, error)

	// Metadata returns the policy metadata for introspection.
	Metadata() PolicyMetadata
}

Authorizer determines whether a principal may exercise a capability.

Flow control ¶

[Can] returns a non-nil *Decision for every policy outcome (allow or deny). It returns a nil *Decision only for infrastructure failures unrelated to policy.

Two sentinel errors signal distinct failure modes:

• ErrUnauthorized — the request could not be evaluated because there is no authenticated principal (principalCtx is nil). This corresponds to an HTTP 401 condition.
• ErrForbidden — the principal was authenticated but the policy denied the requested capability. This corresponds to an HTTP 403 condition; a non-nil *Decision with audit information always accompanies this error.

Example:

d, err := authorizer.Can(ctx, principalCtx, authz.Permission("tunnel", "write"))
if errors.Is(err, authz.ErrUnauthorized) {
    // no principal — redirect to login
}
if errors.Is(err, authz.ErrForbidden) {
    // denied by policy — d contains audit info
}

Connect pattern (fetch-once, check-many) ¶

[Privileges] fetches the full capability set for a principal once; the caller then checks individual capabilities inline using Privilege.Has. This is efficient for handlers that perform multiple capability checks. Privilege.Has follows the same wildcard semantics as [Can], including "resource:any" action wildcards and keyMatch-style resource patterns:

privs, _ := authorizer.Privileges(ctx, principalCtx)
if privs.Has(authz.FeatureCapability("custom-domain")) { ... }
if privs.Has(authz.Permission("tunnel", "write")) { ... }

func NewDefaultCasbinAuthorizer(metadata PolicyMetadata, logger zerolog.Logger) (Authorizer, error)

type AuthorizerConfig ¶

type AuthorizerConfig struct {
	// RoleCapabilities is the list of role→capability assignments.
	RoleCapabilities []RoleCapabilityConfig `mapstructure:"role-capabilities"`

	// RoleAliases maps external token role names to internal role names.
	// Only roles listed here (as keys) are accepted; others are dropped.
	RoleAliases map[string]string `mapstructure:"role-aliases"`

	// AllowAll disables all policy checks; every capability is granted.
	// Must only be set in dev/test environments.
	AllowAll bool `mapstructure:"allow-all"`
}

AuthorizerConfig is the top-level config for constructing an Authorizer from a YAML/mapstructure config source.

func (c AuthorizerConfig) ToMetadata() PolicyMetadata

type Capability ¶

type Capability string

Capability is a named thing a principal is allowed to do or use. All capabilities use ':' as the separator (Casbin convention):

"feature:<name>"      — product entitlement (feature:custom-domain)
"<resource>:<action>" — resource:action permission (tunnel:write)

Use FeatureCapability or Permission to construct values; avoid bare string literals in application code.

func FeatureCapability(name string) Capability

func Permission(resource, action string) Capability

type CasbinAuthorizer ¶

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

CasbinAuthorizer is an Authorizer backed by Casbin v2. It is the recommended production backend for both connect and connect-control.

Policy rules are loaded from PolicyMetadata.RoleCapabilities at construction. [Can] uses Casbin enforce for efficient per-action checks and records the granting role in the returned Decision.

func NewCasbinAuthorizer(metadata PolicyMetadata) (*CasbinAuthorizer, error)

func (a *CasbinAuthorizer) Can(_ context.Context, principalCtx *auth.PrincipalContext, cap Capability) (*Decision, error)

func (a *CasbinAuthorizer) Metadata() PolicyMetadata

func (a *CasbinAuthorizer) Privileges(_ context.Context, principalCtx *auth.PrincipalContext) (Privilege, error)

type Decision ¶

type Decision struct {
	// Allowed is true when the capability was granted.
	Allowed bool

	// Reason is a stable token describing the outcome.
	Reason DecisionReason

	// GrantedBy is the Role that granted the capability.
	// Empty when Allowed is false or when AllowAllAuthorizer is used.
	GrantedBy Role

	// Required is the Capability that was evaluated.
	Required Capability
}

Decision records the outcome of an authorization check for audit logging. It is non-nil whenever the authorizer reaches a policy conclusion (allow or deny). It is nil only when the error is unrelated to policy — for example, an infrastructure failure in the underlying enforcement engine.

type DecisionReason ¶

type DecisionReason string

DecisionReason is a stable string token that describes why an authorization decision was made. It is intended for structured audit logging; callers should still use errors.Is with ErrUnauthorized or ErrForbidden for flow control, depending on the failure mode.

const (
	// ReasonAllowAll is returned by [AllowAllAuthorizer] — every capability
	// is granted regardless of principal or policy.
	ReasonAllowAll DecisionReason = "allow_all"

	// ReasonGranted means a policy rule explicitly grants the capability.
	ReasonGranted DecisionReason = "granted"

	// ReasonDeniedNilPrincipal means no principal was supplied.
	ReasonDeniedNilPrincipal DecisionReason = "denied_nil_principal"

	// ReasonDeniedNoRoles means the principal carries no roles that appear in
	// the policy's RoleAliases map. Unmapped external roles are rejected.
	ReasonDeniedNoRoles DecisionReason = "denied_no_roles"

	// ReasonDeniedNoPermission means the principal's roles are recognised but
	// none of them grant the required capability.
	ReasonDeniedNoPermission DecisionReason = "denied_no_permission"
)

type MapAuthorizer ¶

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

MapAuthorizer is an Authorizer backed by a principal-ID → PrivilegeSet map. It is useful for inline test configs and simple static deployments where each principal's capabilities are enumerated directly.

If a principal ID is not found in the map, Privileges returns nil (no capabilities). In a MultiAuthorizer chain this causes the next backend to be tried.

func NewMapAuthorizer(privileges map[string]*PrivilegeSet, metadata PolicyMetadata) *MapAuthorizer

func (a *MapAuthorizer) Can(ctx context.Context, principalCtx *auth.PrincipalContext, cap Capability) (*Decision, error)

func (a *MapAuthorizer) Metadata() PolicyMetadata

func (a *MapAuthorizer) Privileges(_ context.Context, principalCtx *auth.PrincipalContext) (Privilege, error)

type MultiAuthorizer ¶

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

MultiAuthorizer chains multiple Authorizer backends. [Privileges] returns the result from the first backend that returns a non-nil Privilege; [Can] similarly short-circuits on the first non-nil Privilege result. If all backends return nil Privileges the principal is denied.

This matches the connect MultiAuthoriser semantics and is useful for composing inline + dynamic backends.

func NewMultiAuthorizer(authorizers ...Authorizer) *MultiAuthorizer

func (m *MultiAuthorizer) Can(ctx context.Context, principalCtx *auth.PrincipalContext, cap Capability) (*Decision, error)

func (m *MultiAuthorizer) Metadata() PolicyMetadata

func (m *MultiAuthorizer) Privileges(ctx context.Context, principalCtx *auth.PrincipalContext) (Privilege, error)

type PolicyMetadata ¶

type PolicyMetadata struct {
	// RoleCapabilities maps each internal Role to the set of Capabilities it grants.
	RoleCapabilities map[Role][]Capability

	// RoleAliases maps external role/group names (from IdP tokens) to internal
	// Roles. Canonical internal role names are accepted when they appear in
	// RoleCapabilities; otherwise only aliases listed here are accepted, and
	// unrecognised role strings are ignored.
	RoleAliases map[string]Role
}

PolicyMetadata describes a static role→capability policy used to configure RoleAuthorizer and CasbinAuthorizer.

func CloneMetadata(m PolicyMetadata) PolicyMetadata

func MergeRoleAliases(meta PolicyMetadata, aliases map[string]Role) PolicyMetadata

type Privilege ¶

type Privilege interface {
	Has(Capability) bool
}

Privilege represents the set of capabilities granted to a principal. Callers use [Has] to check whether a specific capability is present. The concrete implementation is PrivilegeSet.

func NewWildcardPrivilege(ps *PrivilegeSet) Privilege

type PrivilegeSet ¶

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

PrivilegeSet is a capability set backed by a map. It implements Privilege and can be built incrementally via [Grant]. Use NewPrivilegeSet to create a set from a slice of known capabilities.

func NewPrivilegeSet(caps ...Capability) *PrivilegeSet

func (p *PrivilegeSet) Capabilities() []Capability

func (p *PrivilegeSet) Grant(cap Capability)

func (p *PrivilegeSet) Has(cap Capability) bool

func (p *PrivilegeSet) Union(other *PrivilegeSet) *PrivilegeSet

type Role ¶

type Role string

Role is an internal policy role name.

type RoleAuthorizer ¶

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

RoleAuthorizer is an Authorizer backed by an in-memory role→capability map. Matching roles are unioned to form the principal's privilege set. It is suitable for static config-driven deployments and unit tests. For production use with complex policies, prefer CasbinAuthorizer.

func NewRoleAuthorizer(metadata PolicyMetadata) *RoleAuthorizer

func (a *RoleAuthorizer) Can(ctx context.Context, principalCtx *auth.PrincipalContext, cap Capability) (*Decision, error)

func (a *RoleAuthorizer) Metadata() PolicyMetadata

func (a *RoleAuthorizer) Privileges(_ context.Context, principalCtx *auth.PrincipalContext) (Privilege, error)

type RoleCapabilityConfig ¶

type RoleCapabilityConfig struct {
	// Role is the internal role name.
	Role string `mapstructure:"role"`

	// Capabilities is the list of capability strings granted to this role.
	// Each must use ':' as the separator, e.g. "tunnel:write", "feature:custom-domain".
	Capabilities []string `mapstructure:"capabilities"`
}

RoleCapabilityConfig maps a role name to the capabilities it grants. Used in YAML/mapstructure-based configuration.