entitlements

README

entitlements

A simple entitlments checking library

Documentation

Index

• type Entitlements
• type EntitlementsChecker
  • func NewEntitlementsChecker(anonymousEntitlements []string, defaultScheme string, grantReadyByDefault bool) *EntitlementsChecker
  • func (ec *EntitlementsChecker) CalculateResourceRequirements(resource string, resourceName string, requirements Requirements, ...) (Requirements, error)
  • func (ec *EntitlementsChecker) ParseEntitlements(entitlements Entitlements) ParsedEntitlements
  • func (ec *EntitlementsChecker) ParseRequirements(requirements Requirements) ParsedRequirements
  • func (ec *EntitlementsChecker) VerifyEntitlements(entitlements Entitlements, requirements Requirements) (result bool)
  • func (ec *EntitlementsChecker) VerifyParsedEntitlements(entitlements ParsedEntitlements, requirements ParsedRequirements) (result bool)
  • func (ec *EntitlementsChecker) VerifyResourceEntitlements(resource string, resourceName string, entitlements Entitlements, ...) (bool, error)
  • func (ec *EntitlementsChecker) VerifyResourceParsedEntitlements(resource string, resourceName string, parsedEntitlements ParsedEntitlements, ...) (bool, error)
  • func (ec *EntitlementsChecker) WithLogger(log logr.Logger) *EntitlementsChecker
• type ParsedEntitlements
• type ParsedRequirements
• type Requirements

Types

type Entitlements

type Entitlements map[string][]string

Entitlements is a map where keys are security schemes (e.g., "bearer", "oauth2") and values are slices of entitlement strings. Entitlement strings can be in long, medium, short, or opaque forms.

type EntitlementsChecker

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

EntitlementsChecker handles the verification of user entitlements against security requirements. It supports exact matches and wildcard patterns for resource names and verbs.

Pattern Forms:

• Long Form: <resource>:<resourceName>:<verb>
• Medium Form: <resource>::<verb> (means <resource>:*:<verb>)
• Short Form: <resource>:<verb> (means <resource>:*:<verb>)
• Opaque Form: <resource> (not a wildcard, only matches exactly)

Opaque form is intended to support JWT claims and other forms of requirements like HTTP Headers.

Encoding: resourceName should be URL-encoded (url.PathEscape) if it contains colons ':' to prevent it from being misinterpreted by the pattern splitting logic.

Examples:

• pages:/foo:read - read access to page "foo" (explicit resource name)
• pages:*:read - read access to all pages (explicit wildcard)
• pages::read - read access to all pages (implicit wildcard)
• pages:read - read access to all pages (short form)
• pages:/foo:all - all access to page "foo" (explicit resource name)
• pages:*:all - all access to all pages (explicit wildcard)
• pages::all - all access to all pages (implicit wildcard)
• pages:all - all access to all pages (short form)
• email - exact match only (opaque form)

func NewEntitlementsChecker

func NewEntitlementsChecker(
	anonymousEntitlements []string,
	defaultScheme string,
	grantReadyByDefault bool,
) *EntitlementsChecker

NewEntitlementsChecker creates a new entitlements checker with the specified settings. anonymousEntitlements is a list of patterns that are granted to all users. defaultScheme is the fallback security scheme used when none is specified. grantReadyByDefault determines if the identity requirement is automatically satisfied.

func (*EntitlementsChecker) CalculateResourceRequirements

func (ec *EntitlementsChecker) CalculateResourceRequirements(
	resource string,
	resourceName string,
	requirements Requirements,
	verbs ...string,
) (Requirements, error)

CalculateResourceRequirements calculates the requirements for a resource instance. It returns a copy of the requirements with an identity requirement added for the specific resource. The optional verbs parameter allows specifying the verb for the identity requirement (defaults to "read").

func (*EntitlementsChecker) ParseEntitlements

func (ec *EntitlementsChecker) ParseEntitlements(entitlements Entitlements) ParsedEntitlements

ParseEntitlements converts a raw Entitlements map into ParsedEntitlements for efficient reuse in multiple verification calls.

func (*EntitlementsChecker) ParseRequirements

func (ec *EntitlementsChecker) ParseRequirements(requirements Requirements) ParsedRequirements

ParseRequirements converts raw Requirements into ParsedRequirements for efficient reuse in multiple verification calls.

func (*EntitlementsChecker) VerifyEntitlements

func (ec *EntitlementsChecker) VerifyEntitlements(
	entitlements Entitlements,
	requirements Requirements,
) (result bool)

VerifyEntitlements checks if the user's entitlements satisfy the given security requirements. It returns true if any of the alternative requirement sets (OR'd) is fully satisfied.

func (*EntitlementsChecker) VerifyParsedEntitlements

func (ec *EntitlementsChecker) VerifyParsedEntitlements(
	entitlements ParsedEntitlements,
	requirements ParsedRequirements,
) (result bool)

VerifyParsedEntitlements is a high-performance check that uses pre-parsed entitlements and requirements. It is intended for scenarios where the same entitlements or requirements are checked repeatedly.

func (*EntitlementsChecker) VerifyResourceEntitlements

func (ec *EntitlementsChecker) VerifyResourceEntitlements(
	resource string,
	resourceName string,
	entitlements Entitlements,
	requirements Requirements,
	verbs ...string,
) (bool, error)

VerifyResourceEntitlements checks if the user's entitlements satisfy the security requirements for a specific resource instance. It automatically adds an identity requirement for the resource. The optional verbs parameter allows specifying the verb for the identity requirement (defaults to "read").

func (*EntitlementsChecker) VerifyResourceParsedEntitlements

func (ec *EntitlementsChecker) VerifyResourceParsedEntitlements(
	resource string,
	resourceName string,
	parsedEntitlements ParsedEntitlements,
	parsedRequirements ParsedRequirements,
	verbs ...string,
) (bool, error)

VerifyResourceParsedEntitlements is a high-performance check for a specific resource instance using pre-parsed entitlements and requirements.

func (*EntitlementsChecker) WithLogger

func (ec *EntitlementsChecker) WithLogger(log logr.Logger) *EntitlementsChecker

WithLogger attaches a logger to the EntitlementsChecker for debugging purposes.

type ParsedEntitlements

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

ParsedEntitlements represents a set of user entitlements that have been pre-parsed into internal patterns for high-performance verification.

type ParsedRequirements

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

ParsedRequirements represents a set of security requirements that have been pre-parsed into internal patterns for high-performance verification.

type Requirements

type Requirements []map[string][]string

Requirements is a slice of maps representing alternative security requirement sets. Each map in the slice represents an alternative set of requirements (OR'd). Within each map, all schemes and their associated scopes must be satisfied (AND'd).