인터페이스 정의

TokenManager

type TokenManager interface {
    Create(claims CustomClaims) (string, error)
    Validate(tokenString string) (Claims, bool, error)
    CreateRefresh(claims CustomClaims) (string, error)
    Refresh(refreshTokenString string) (string, error)
    ValidateInto(tokenString string, claims CustomClaims) (CustomClaims, bool, error)
    RefreshInto(refreshTokenString string, claims CustomClaims) (string, error)
    Revoke(tokenString string) error
    IsRevoked(tokenString string) (bool, error)
    ParseUnverified(tokenString string, claims any) error
    Close() error
    IsClosed() bool
}

JWT 토큰 작업 핵심 인터페이스. 모든 구현은 동시성에 안전해야 합니다. 기본 구현은 *Processor입니다.

메서드는 세 그룹으로 나뉩니다:

• 토큰 생성: Create, CreateRefresh
• 검증 및 갱신: Validate, ValidateInto, Refresh, RefreshInto
• 일반 작업: Revoke, IsRevoked, ParseUnverified, Close, IsClosed

interface

메서드

메서드	시그니처	설명
Create	Create(claims CustomClaims) (string, error)	액세스 토큰 생성
Validate	Validate(tokenString string) (Claims, bool, error)	토큰 검증
CreateRefresh	CreateRefresh(claims CustomClaims) (string, error)	리프레시 토큰 생성
Refresh	Refresh(refreshTokenString string) (string, error)	토큰 갱신
ValidateInto	ValidateInto(tokenString string, claims CustomClaims) (CustomClaims, bool, error)	커스텀 Claims 로 검증
RefreshInto	RefreshInto(refreshTokenString string, claims CustomClaims) (string, error)	커스텀 Claims 로 갱신
Revoke	Revoke(tokenString string) error	토큰 취소
IsRevoked	IsRevoked(tokenString string) (bool, error)	취소 여부 확인
ParseUnverified	ParseUnverified(tokenString string, claims any) error	검증 없이 파싱
Close	Close() error	리소스 해제
IsClosed	IsClosed() bool	종료 여부 확인

구현 타입

타입	설명
*Processor	기본 구현

---

CustomClaims

type CustomClaims interface {
    GetRegisteredClaims() *RegisteredClaims
    Validate() error
}

커스텀 Claims 인터페이스. Create, ValidateInto, RefreshInto 등의 메서드에서 사용됩니다.

interface

검증 계약

Processor 는 *Claims와 다른 타입에 대해 다른 검증 경로를 실행합니다:

타입	검증 동작
*Claims	심층 검증: 모든 필드 (길이 제한, 인젝션 패턴, 제어 문자)
기타 타입	Validate() 호출 + 등록 선언 문자열 정제 (Issuer, Subject, ID, TokenType, Audience)

주의

*Claims가 아닌 타입의 경우, 커스텀 구조체 필드는 심층 검증되지 않습니다. 구현자는 Validate() 메서드에서 모든 비즈니스 필드를 직접 검증해야 합니다.

메서드

메서드	시그니처	설명
GetRegisteredClaims	GetRegisteredClaims() *RegisteredClaims	표준 JWT 필드 반환
Validate	Validate() error	커스텀 검증 로직

구현 타입

타입	설명
*Claims	내장 Claims 구현

---

BlacklistStore

type BlacklistStore interface {
    Add(tokenID string, expiresAt time.Time) error
    Contains(tokenID string) (bool, error)
    Close() error
}

블랙리스트 저장소 백엔드 인터페이스.

interface

메서드

메서드	시그니처	설명
Add	Add(tokenID string, expiresAt time.Time) error	블랙리스트에 추가
Contains	Contains(tokenID string) (bool, error)	블랙리스트 포함 여부 확인
Close	Close() error	리소스 해제

---

RateLimitProvider

type RateLimitProvider interface {
    Allow(key string) bool
    Reset(key string)
    Close()
}

속도 제한 인터페이스. Processor 는 토큰 생성 중 단일 검사를 위해 Allow(key)를 호출합니다.

AllowN 에 대하여

인터페이스 자체는 단일 요청 검사를 위한 Allow만 정의합니다. 배치 메서드 AllowN(key string, n int) bool은 구체 타입 *RateLimiter의 확장 메서드이며 이 인터페이스의 일부가 아닙니다.

interface

메서드

메서드	시그니처	설명
Allow	Allow(key string) bool	단일 요청 허용 여부 확인
Reset	Reset(key string)	지정된 키의 속도 제한 상태 초기화
Close	Close()	리소스 해제

구현 타입

타입	설명
*RateLimiter	내장 토큰 버킷 구현

---

ClockProvider

type ClockProvider interface {
    Now() time.Time
}

클럭 인터페이스, 시간 주입용 (테스트 시나리오).

interface

구현 타입

타입	설명
SystemClock	시스템 클럭
FixedClock	고정 시간 클럭

---

RateLimitKeyer

type RateLimitKeyer interface {
    RateLimitKey() string
}

선택적 인터페이스, 커스텀 Claims 가 이 인터페이스를 구현하여 속도 제한 키를 제공할 수 있습니다. 속도 제한 키 조회 우선순위: Subject → *Claims.UserID → RateLimitKey().

interface