Documentation
¶
Index ¶
- Constants
- Variables
- func ContextWithClaims(ctx context.Context, claims *Claims) context.Context
- func ContextWithToken(ctx context.Context, token string) context.Context
- func FromContext(ctx context.Context) string
- func GenerateAdminTestToken() string
- func GenerateTestToken(userID, role string, permissions []string) string
- func NewSecurityHandlerModule(opts ...Option) fx.Option
- type Claims
- func (c *Claims) Get(key string, v any) error
- func (c *Claims) GetString(key string) (string, error)
- func (c *Claims) HasAnyPermission(permissions []string) bool
- func (c *Claims) HasPermission(permission string) bool
- func (c *Claims) IsAccess() bool
- func (c *Claims) IsExpired() bool
- func (c *Claims) IsRefresh() bool
- type Config
- type Option
- type SecurityHandler
- type Validator
Constants ¶
const WildcardPermission = "*"
WildcardPermission grants access to all permissions.
Variables ¶
var ( // ErrInvalidToken is returned when the token cannot be parsed or verified. ErrInvalidToken = errors.New("invalid token") // ErrExpiredToken is returned when the token has expired. ErrExpiredToken = errors.New("token expired") // ErrInvalidPublicKey is returned when the public key is invalid. ErrInvalidPublicKey = errors.New("invalid public key") )
var ErrInsufficientPermissions = errors.New("insufficient permissions")
ErrInsufficientPermissions is returned when user lacks required permissions.
Functions ¶
func ContextWithClaims ¶
ContextWithClaims returns a new context with the claims stored.
func ContextWithToken ¶ added in v0.2.6
ContextWithToken returns a new context with the raw token string stored. This is useful for token propagation in service-to-service calls.
func FromContext ¶ added in v0.3.5
FromContext retrieves the raw token string from the context. Returns empty string if no token is present.
func GenerateAdminTestToken ¶ added in v0.4.3
func GenerateAdminTestToken() string
GenerateAdminTestToken creates a test token with admin role and wildcard permissions.
func GenerateTestToken ¶ added in v0.4.3
GenerateTestToken creates a base64-encoded JSON token from claims. Use this in tests to create tokens that testValidator can decode.
func NewSecurityHandlerModule ¶ added in v0.4.3
NewSecurityHandlerModule provides a SecurityHandler for dependency injection. This is the recommended way to handle authentication in services. Also provides Validator for services that need direct token validation (e.g., refresh tokens).
Options:
- WithTokenConfig: provide static token Config (useful for tests)
- WithDisableValidation: bypass all security, returns admin claims
- WithTestValidator: use base64 JSON tokens (for e2e tests with realistic flow)
Example usage:
// Production - validates PASETO tokens token.NewSecurityHandlerModule() // Testing - bypass security completely token.NewSecurityHandlerModule(token.WithDisableValidation()) // E2E testing - use base64 JSON tokens token.NewSecurityHandlerModule(token.WithTestValidator())
Types ¶
type Claims ¶
type Claims struct {
// UserID is the unique identifier of the user (subject).
UserID string
// Role is the user's role (e.g., "super_admin", "catalog_manager", "viewer").
Role string
// Permissions is the list of permissions granted to the user.
Permissions []string
// Type is the token type (e.g., "access", "refresh").
Type string
// IssuedAt is the time when the token was issued.
IssuedAt time.Time
// ExpiresAt is the time when the token expires.
ExpiresAt time.Time
// NotBefore is the time before which the token is not valid.
NotBefore time.Time
// contains filtered or unexported fields
}
Claims represents the token claims. This is used across all services for authentication.
func ClaimsFromContext ¶
ClaimsFromContext retrieves claims from the context. Returns nil if no claims are present.
func (*Claims) HasAnyPermission ¶
HasAnyPermission checks if the user has at least one of the required permissions. Returns true if the user has any of the specified permissions or the wildcard permission.
func (*Claims) HasPermission ¶
HasPermission checks if the user has a specific permission. Returns true if the user has the exact permission or the wildcard permission.
type Config ¶
type Config struct {
// PublicKey is the hex-encoded Ed25519 public key for verifying tokens.
// Required for all services that need to validate incoming tokens.
PublicKey string `mapstructure:"public-key"`
// ServiceToken is a pre-generated PASETO token for service-to-service communication.
// Optional: only needed for services that make outgoing authenticated requests.
// This token should be generated by auth-service with appropriate permissions.
ServiceToken string `mapstructure:"service-token"`
}
Config holds the configuration for PASETO token handling.
type Option ¶ added in v0.4.3
type Option func(*tokenOptions)
Option is a functional option for configuring the token module.
func WithDisableValidation ¶ added in v0.4.3
func WithDisableValidation() Option
WithDisableValidation disables token validation and returns noop validator. Useful for tests where token validation should be bypassed.
func WithTestClaims ¶ added in v0.4.3
WithTestClaims provides a validator that always returns the given claims. Useful for tests that need specific user context.
func WithTestValidator ¶ added in v0.4.3
func WithTestValidator() Option
WithTestValidator enables the test validator that decodes base64-encoded JSON tokens. Use GenerateTestToken or GenerateAdminTestToken to create tokens for this validator. Useful for e2e/integration tests where you want realistic token flow without PASETO.
func WithTokenConfig ¶ added in v0.4.3
WithTokenConfig provides a static Config (useful for tests).
type SecurityHandler ¶ added in v0.4.3
type SecurityHandler interface {
// HandleBearerAuth validates a token and checks permissions.
// Returns the context with claims stored, the claims, and any error.
HandleBearerAuth(ctx context.Context, token string, requiredPermissions []string) (context.Context, *Claims, error)
}
SecurityHandler handles bearer token authentication and authorization. Different validators provide different behaviors for production vs testing.
func NewSecurityHandler ¶ added in v0.4.3
func NewSecurityHandler(validator Validator) SecurityHandler
NewSecurityHandler creates a SecurityHandler with the given validator. The validator determines the behavior:
- tokenValidator: production PASETO validation
- testValidator: base64 JSON tokens for e2e tests
- noopValidator: always returns admin claims (bypasses security)
Source Files