shared

Documentation

Overview

Package shared centralizes auth middleware primitives that need to stay behaviorally aligned across JWT-based integrations.

Index

• func AuthErrorDetail(err error, present bool) string
• func CopyClaims(claims jwt.MapClaims) map[string]any
• func FirstNonEmpty(values ...string) string
• func NormalizeAlgorithms(algs []string) ([]string, error)
• func OptionalBearerHandler(next http.Handler, enabled bool, log ports.Logger, ...) http.Handler
• func ParseBearerToken(header string) (string, bool, error)
• func ParseSkipTrustedProxies(trustedProxies []string) (identity.Resolver, error)
• func ParseTokenClaims(tokenStr string, keyfunc jwt.Keyfunc, cfg TokenParserConfig) (jwt.MapClaims, error)
• func RequiredBearerHandler(next http.Handler, enabled bool, log ports.Logger, ...) http.Handler
• func ShouldSkipRequest(r *http.Request, policy SkipPolicy) bool
• func StringClaim(claims jwt.MapClaims, key string) string
• func ValidateRequiredClaims(claims jwt.MapClaims, req ClaimRequirements) error
• type ClaimRequirements
  • func NormalizeClaimRequirements(input ClaimRequirementsInput) ClaimRequirements
• type ClaimRequirementsInput
• type HandlerMessages
• type SkipPolicy
• type SubjectContextFunc
• type TokenFromRequestFunc
• type TokenParserConfig
• type ValidationConfig
• type ValidationState
  • func PrepareValidationState(ctx context.Context, cfg ValidationConfig) (ValidationState, error)

Functions

func AuthErrorDetail

func AuthErrorDetail(err error, present bool) string

AuthErrorDetail converts header parse results into a stable log message.

func CopyClaims

func CopyClaims(claims jwt.MapClaims) map[string]any

CopyClaims clones JWT claims into a plain map.

func FirstNonEmpty

func FirstNonEmpty(values ...string) string

FirstNonEmpty returns the first non-empty trimmed value.

func NormalizeAlgorithms

func NormalizeAlgorithms(algs []string) ([]string, error)

NormalizeAlgorithms canonicalizes the configured JWT algorithm allowlist.

func OptionalBearerHandler

func OptionalBearerHandler(
	next http.Handler,
	enabled bool,
	log ports.Logger,
	shouldSkip func(*http.Request) bool,
	messages HandlerMessages,
	tokenFromRequest TokenFromRequestFunc,
	subjectContext SubjectContextFunc,
) http.Handler

OptionalBearerHandler injects subject context when a valid token is present.

func ParseBearerToken

func ParseBearerToken(header string) (string, bool, error)

ParseBearerToken extracts a bearer token from the Authorization header.

func ParseSkipTrustedProxies

func ParseSkipTrustedProxies(trustedProxies []string) (identity.Resolver, error)

ParseSkipTrustedProxies normalizes trusted proxy CIDRs for skip-header use.

func ParseTokenClaims

func ParseTokenClaims(
	tokenStr string,
	keyfunc jwt.Keyfunc,
	cfg TokenParserConfig,
) (jwt.MapClaims, error)

ParseTokenClaims parses and validates JWT claims using the configured keyfunc.

func RequiredBearerHandler

func RequiredBearerHandler(
	next http.Handler,
	enabled bool,
	log ports.Logger,
	shouldSkip func(*http.Request) bool,
	messages HandlerMessages,
	tokenFromRequest TokenFromRequestFunc,
	subjectContext SubjectContextFunc,
) http.Handler

RequiredBearerHandler enforces authentication and injects subject context.

func ShouldSkipRequest

func ShouldSkipRequest(r *http.Request, policy SkipPolicy) bool

ShouldSkipRequest reports whether auth should be skipped for the request.

func StringClaim

func StringClaim(claims jwt.MapClaims, key string) string

StringClaim extracts a string claim when present.

func ValidateRequiredClaims

func ValidateRequiredClaims(claims jwt.MapClaims, req ClaimRequirements) error

ValidateRequiredClaims enforces presence of the configured JWT claims.

Types

type ClaimRequirements

type ClaimRequirements struct {
	RequireSubject    bool
	RequireExpiration bool
	RequireIssuedAt   bool
	RequireNotBefore  bool
}

ClaimRequirements is the normalized required-claim policy.

func NormalizeClaimRequirements

func NormalizeClaimRequirements(input ClaimRequirementsInput) ClaimRequirements

NormalizeClaimRequirements applies the default required-claim policy.

type ClaimRequirementsInput

type ClaimRequirementsInput struct {
	RequireSubject    *bool
	RequireExpiration *bool
	RequireIssuedAt   *bool
	RequireNotBefore  *bool
}

ClaimRequirementsInput configures required JWT claims.

type HandlerMessages

type HandlerMessages struct {
	SkipLog       string
	FailureLog    string
	MissingDetail string
	InvalidDetail string
}

HandlerMessages configures shared auth middleware logging and responses.

type SkipPolicy

type SkipPolicy struct {
	Enabled                   bool
	AllowDangerousDevBypasses bool
	HeaderName                string
	Resolver                  identity.Resolver
}

SkipPolicy configures skip-header behavior for trusted proxies.

type SubjectContextFunc

type SubjectContextFunc func(ctx context.Context, token string) (context.Context, error)

SubjectContextFunc resolves the authenticated request context from a token.

type TokenFromRequestFunc

type TokenFromRequestFunc func(r *http.Request) (string, bool, error)

TokenFromRequestFunc extracts a bearer token from an HTTP request.

type TokenParserConfig

type TokenParserConfig struct {
	Audience          string
	Issuer            string
	AllowedClockSkew  time.Duration
	AllowedAlgorithms []string
	Requirements      ClaimRequirements
}

TokenParserConfig configures JWT claim parsing and validation.

type ValidationConfig

type ValidationConfig struct {
	Enabled                   bool
	ProviderName              string
	JWKSDescriptor            string
	JWKSURL                   string
	Issuer                    string
	Audience                  string
	AllowedAlgorithms         []string
	AllowedClockSkew          time.Duration
	JWKSRefreshTimeout        time.Duration
	JWKSRefreshInterval       time.Duration
	RequiredClaims            ClaimRequirementsInput
	AllowDangerousDevBypasses bool
	SkipHeaderEnabled         bool
	SkipHeaderName            string
	SkipTrustedProxies        []string
}

ValidationConfig configures shared JWT/JWKS middleware setup.

type ValidationState

type ValidationState struct {
	Enabled           bool
	SkipHeader        string
	SkipResolver      identity.Resolver
	AllowedAlgorithms []string
	ClaimRequirements ClaimRequirements
	JWKS              keyfunc.Keyfunc
	Cancel            context.CancelFunc
}

ValidationState contains the prepared runtime for JWT validation middleware.

func PrepareValidationState

func PrepareValidationState(ctx context.Context, cfg ValidationConfig) (ValidationState, error)

PrepareValidationState normalizes shared middleware runtime configuration.