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
}

JWT Processor 의 통합 설정. 제로값 필드는 New()에서 자동으로 기본값이 채워집니다 (normalizeConfig 통해).

자동 채우기 규칙

• RateLimitRate, RateLimitWindow는 EnableRateLimit = true인 경우에만 채워짐
• 내장 블랙리스트 저장소의 EnableAutoCleanup은 항상 true로 강제됨 (무한 증가 방지)
• SecretKey, SigningKey, VerificationKey는 자동으로 채워지지 않으므로 수동 설정 필요

struct

필드

필드	타입	기본값	설명
SecretKey	string	—	HMAC 키 (최소 32 바이트)
SigningKey	any	—	비대칭 알고리즘 개인 키 (*rsa.PrivateKey 또는 *ecdsa.PrivateKey)
VerificationKey	any	—	비대칭 알고리즘 공개 키 (선택, 기본값은 SigningKey 사용)
SigningMethod	SigningMethod	HS256	서명 알고리즘
AccessTokenTTL	time.Duration	15m	액세스 토큰 유효 기간
RefreshTokenTTL	time.Duration	168h	리프레시 토큰 유효 기간
Issuer	string	"jwt-service"	발급자
ExpectedAudience	string	—	예상 수신자 (선택)
RequireExpiration	bool	false	true인 경우 검증 시 exp 클레임이 없는 토큰을 거부 (ErrExpirationRequired 반환)
ClockSkew	time.Duration	0	검증 시 exp/nbf에 적용되는 클럭 스큐 허용 오차 (발급자와 검증자 사이의 클럭 드리프트 허용); 음수 값은 Validate()에서 거부됨
Blacklist	BlacklistConfig	—	블랙리스트 설정
EnableRateLimit	bool	false	속도 제한 활성화
RateLimitRate	int	100	윈도우당 최대 요청 수
RateLimitWindow	time.Duration	1m	속도 제한 윈도우
RateLimiter	RateLimitProvider	—	커스텀 속도 제한기 (선택)
Clock	ClockProvider	SystemClock{}	클럭 제공자

메서드

메서드	시그니처	설명
Validate	func (c *Config) Validate() error	설정 유효성 검증

Validate() 검사 항목:

검사 항목	설명
서명 키	HMAC 은 SecretKey ≥32 바이트 및 약한 키가 아니어야 함; RSA/ECDSA는 올바른 타입의 SigningKey 필요; ECDSA 는 곡선 일치 필요; VerificationKey 는 알고리즘 공개 키 타입과 일치해야 함
TTL 유효성	AccessTokenTTL과 RefreshTokenTTL은 양수여야 함
TTL 순서	AccessTokenTTL은 RefreshTokenTTL보다 작아야 함
ClockSkew	ClockSkew는 음수일 수 없음
서명 알고리즘	내장 지원하는 12 개 알고리즘 중 하나여야 함
블랙리스트	내장 저장소 사용 시 MaxSize 와 CleanupInterval 은 양수여야 함

---

BlacklistConfig

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

블랙리스트 설정.

struct

필드

필드	타입	기본값	설명
CleanupInterval	time.Duration	5m	만료 항목 정리 간격 (내장 저장소에만 적용)
MaxSize	int	100000	메모리 저장소 최대 항목 수 (내장 저장소에만 적용)
EnableAutoCleanup	bool	true	만료 항목 자동 정리 (내장 저장소에만 적용)
Store	BlacklistStore	—	커스텀 저장소 백엔드 (설정 시 다른 필드는 무시됨)