Config

Config

type Config struct {
    SecretKey       string
    SigningKey      any
    VerificationKey any
    SigningMethod   SigningMethod

    AccessTokenTTL    time.Duration
    RefreshTokenTTL   time.Duration
    Issuer            string
    ExpectedAudience  string
    RequireExpiration bool
    ClockSkew         time.Duration

    Blacklist BlacklistConfig

    EnableRateLimit bool
    RateLimitRate   int
    RateLimitWindow time.Duration
    RateLimiter     RateLimitProvider

    Clock ClockProvider
}

Unified configuration for the JWT Processor. Zero-value fields are automatically populated with defaults in New() (via normalizeConfig).

Auto-fill Rules

• RateLimitRate and RateLimitWindow are only populated when EnableRateLimit = true
• Built-in blacklist store's EnableAutoCleanup is always forced to true (to prevent unbounded growth)
• SecretKey, SigningKey, and VerificationKey are not auto-populated; they must be set manually

struct

Fields

Field	Type	Default	Description
SecretKey	string	—	HMAC key (at least 32 bytes)
SigningKey	any	—	Asymmetric algorithm private key (*rsa.PrivateKey or *ecdsa.PrivateKey)
VerificationKey	any	—	Asymmetric algorithm public key (optional, defaults to SigningKey)
SigningMethod	SigningMethod	HS256	Signing algorithm
AccessTokenTTL	time.Duration	15m	Access token time-to-live
RefreshTokenTTL	time.Duration	168h	Refresh token time-to-live
Issuer	string	"jwt-service"	Issuer
ExpectedAudience	string	—	Expected audience (optional)
RequireExpiration	bool	false	When true, rejects tokens lacking an exp claim during validation (returns ErrExpirationRequired)
ClockSkew	time.Duration	0	Clock skew leeway applied to exp/nbf during validation (tolerates clock drift between issuer and validator); negative values are rejected by Validate()
Blacklist	BlacklistConfig	—	Blacklist configuration
EnableRateLimit	bool	false	Enable rate limiting
RateLimitRate	int	100	Max requests per window
RateLimitWindow	time.Duration	1m	Rate limit window
RateLimiter	RateLimitProvider	—	Custom rate limiter (optional)
Clock	ClockProvider	SystemClock{}	Clock provider

Methods

Method	Signature	Description
Validate	func (c *Config) Validate() error	Validates configuration

Validate() checks:

Check	Description
Signing keys	HMAC requires SecretKey ≥32 bytes and non-weak; RSA/ECDSA requires correct SigningKey type; ECDSA requires curve match; VerificationKey must match algorithm public key type
TTL validity	AccessTokenTTL and RefreshTokenTTL must be positive
TTL ordering	AccessTokenTTL must be less than RefreshTokenTTL
ClockSkew	ClockSkew must not be negative
Signing algorithm	Must be one of the 12 built-in algorithms
Blacklist	Built-in store requires positive MaxSize and CleanupInterval

---

BlacklistConfig

type BlacklistConfig struct {
    CleanupInterval   time.Duration
    MaxSize           int
    EnableAutoCleanup bool
    Store             BlacklistStore
}

Blacklist configuration.

struct

Fields

Field	Type	Default	Description
CleanupInterval	time.Duration	5m	Expired entry cleanup interval (built-in store only)
MaxSize	int	100000	Max entries in memory store (built-in store only)
EnableAutoCleanup	bool	true	Auto-cleanup of expired entries (built-in store only)
Store	BlacklistStore	—	Custom storage backend (when set, other fields are ignored)