Processor

Processor は JWT 操作のコア型で、TokenManager インターフェースを実装しています。すべてのメソッドは並行安全です。

jwt.New(cfg) でインスタンスを作成します。

Create

func (p *Processor) Create(claims CustomClaims) (string, error)

新しい JWT アクセストークンを作成します。CustomClaims インターフェースを実装する任意の型を受け付けます。

パラメータ

パラメータ	型	説明
`claims`	`CustomClaims`	トークンクレーム

戻り値

戻り値	型	説明
`token`	`string`	署名済み JWT 文字列
`err`	`error`	検証または署名に失敗した場合にエラーを返す

エラー

エラー	発生条件
`ErrProcessorClosed`	Processor がクローズ済み
`ErrInvalidClaims`	Claims の検証に失敗
`ErrRateLimitExceeded`	レート制限のしきい値を超過

例

// 内蔵 Claims
claims := &jwt.Claims{UserID: "user123", Username: "alice"}
token, err := processor.Create(claims)

// カスタム Claims
myClaims := &MyClaims{UserID: "123"}
token, err := processor.Create(myClaims)

Validate

func (p *Processor) Validate(tokenString string) (Claims, bool, error)

JWT アクセストークンを検証し、パースされた Claims を返します。

パラメータ

パラメータ	型	説明
`tokenString`	`string`	JWT 文字列

戻り値

戻り値	型	説明
`claims`	`Claims`	パースされたクレーム（値のコピー）
`valid`	`bool`	有効かどうか
`err`	`error`	検証に失敗した場合にエラーを返す

エラー

エラー	発生条件
`ErrProcessorClosed`	Processor がクローズ済み
`ErrEmptyToken`	トークンが空
`ErrInvalidToken`	署名が無効
`ErrAlgorithmMismatch`	トークンのアルゴリズムが設定と一致しない
`ErrExpirationRequired`	`RequireExpiration` が有効だがトークンに `exp` クレームがない
`ErrTokenExpired`	トークンの有効期限切れ
`ErrTokenNotValidYet`	トークンがまだ有効ではない
`ErrTokenInvalidIssuer`	発行者が一致しない
`ErrTokenInvalidAudience`	オーディエンスが一致しない
`ErrTokenRevoked`	トークンが失効済み
`ErrInvalidClaims`	Claims の検証に失敗

例

claims, valid, err := processor.Validate(tokenString)
if err != nil {
    // エラー処理
    return
}
if valid {
    fmt.Println(claims.UserID)
}

CreateRefresh

func (p *Processor) CreateRefresh(claims CustomClaims) (string, error)

リフレッシュトークンを作成します。AccessTokenTTL ではなく RefreshTokenTTL を使用します。

パラメータ

パラメータ	型	説明
`claims`	`CustomClaims`	トークンクレーム

戻り値

戻り値	型	説明
`token`	`string`	署名済みリフレッシュトークン
`err`	`error`	検証または署名に失敗した場合にエラーを返す

エラー

エラー	発生条件
`ErrProcessorClosed`	Processor がクローズ済み
`ErrInvalidClaims`	Claims の検証に失敗
`ErrRateLimitExceeded`	レート制限のしきい値を超過

Refresh

func (p *Processor) Refresh(refreshTokenString string) (string, error)

既存のリフレッシュトークンを更新し、新しいアクセストークンを返します。リフレッシュトークンは新しいアクセストークンを発行する前に完全に検証（署名、有効期限、ブラックリスト）され、元のトークンの IssuedAt、ExpiresAt、ID はリセットおよび再生成されます。

トークンタイプとローテーション

トークンタイプチェック：token_type=access のトークンは拒否され（ErrTokenTypeMismatch を返す）、アクセストークンが新たなトークン取得に使われるのを防ぎます。token_type を持たない古いトークンは後方互換性のため引き続き受け付けられます。
元のトークンを自動失効させない：Refresh は渡されたリフレッシュトークンを失効させません。元のトークンは期限切れまたは明示的に Revoke() されるまで有効なままです。ワンタイム使用のセマンティクスが必要な場合は、Refresh 成功後に Revoke(refreshTokenString) を呼び出してください。

セキュリティ上の注意

リフレッシュ時は標準 JWT フィールド（exp、nbf、iss、aud、ブラックリスト）と基本構造の有効性（UserID または Username が必須）のみ検証します。深いフィールド制約（長さ制限、注入パターン）は作成時に検証済みのため、再チェックされません。

パラメータ

パラメータ	型	説明
`refreshTokenString`	`string`	リフレッシュトークン

戻り値

戻り値	型	説明
`token`	`string`	新しいアクセストークン
`err`	`error`	検証に失敗した場合にエラーを返す

エラー

エラー	発生条件
`ErrProcessorClosed`	Processor がクローズ済み
`ErrEmptyToken`	トークンが空
`ErrInvalidToken`	署名が無効
`ErrAlgorithmMismatch`	トークンのアルゴリズムが設定と一致しない
`ErrExpirationRequired`	`RequireExpiration` が有効だがトークンに `exp` クレームがない
`ErrTokenExpired`	トークンの有効期限切れ
`ErrTokenNotValidYet`	トークンがまだ有効ではない
`ErrTokenInvalidIssuer`	発行者が一致しない
`ErrTokenInvalidAudience`	オーディエンスが一致しない
`ErrTokenRevoked`	トークンが失効済み
`ErrInvalidClaims`	Claims の検証に失敗
`ErrTokenTypeMismatch`	アクセストークン（`token_type=access`）でリフレッシュを試行
`ErrRateLimitExceeded`	レート制限のしきい値を超過

ValidateInto

func (p *Processor) ValidateInto(tokenString string, claims CustomClaims) (CustomClaims, bool, error)

トークンを検証し、カスタム Claims 構造体に格納します。渡された claims と同じポインタを返します。

パラメータ

パラメータ	型	説明
`tokenString`	`string`	JWT 文字列
`claims`	`CustomClaims`	ターゲットの Claims ポインタ

戻り値

戻り値	型	説明
`claims`	`CustomClaims`	格納後の Claims
`valid`	`bool`	有効かどうか
`err`	`error`	検証に失敗した場合にエラーを返す

例

myClaims := &MyClaims{}
result, valid, err := processor.ValidateInto(tokenString, myClaims)
if valid {
    fmt.Println(result.(*MyClaims).UserID)
}

エラー

エラー	発生条件
`ErrProcessorClosed`	Processor がクローズ済み
`ErrEmptyToken`	トークンが空
`ErrInvalidToken`	署名が無効
`ErrAlgorithmMismatch`	トークンのアルゴリズムが設定と一致しない
`ErrExpirationRequired`	`RequireExpiration` が有効だがトークンに `exp` クレームがない
`ErrTokenExpired`	トークンの有効期限切れ
`ErrTokenNotValidYet`	トークンがまだ有効ではない
`ErrTokenInvalidIssuer`	発行者が一致しない
`ErrTokenInvalidAudience`	オーディエンスが一致しない
`ErrTokenRevoked`	トークンが失効済み
`ErrInvalidClaims`	Claims の検証に失敗

RefreshInto

func (p *Processor) RefreshInto(refreshTokenString string, claims CustomClaims) (string, error)

カスタム Claims を使用してトークンをリフレッシュします。Claims オブジェクトの時系列フィールド（IssuedAt、ExpiresAt、ID）は操作後に自動的に復元され、エラーや panic が発生しても復元が保証されます。

トークンタイプチェック

token_type=access のトークンは拒否され（ErrTokenTypeMismatch を返す）、アクセストークンが新たなトークン取得に使われるのを防ぎます。token_type を持たない古いトークンは後方互換性のため引き続き受け付けられます。

セキュリティ上の注意

リフレッシュ時は標準 JWT フィールド（exp、nbf、iss、aud、ブラックリスト）と基本構造の有効性のみ検証します。深いフィールド制約（長さ制限、注入パターン）は作成時に検証済みのため、再チェックされません。

パラメータ

パラメータ	型	説明
`refreshTokenString`	`string`	リフレッシュトークン
`claims`	`CustomClaims`	ターゲットの Claims ポインタ

戻り値

戻り値	型	説明
`token`	`string`	新しいアクセストークン
`err`	`error`	検証に失敗した場合にエラーを返す

エラー

エラー	発生条件
`ErrProcessorClosed`	Processor がクローズ済み
`ErrEmptyToken`	トークンが空
`ErrInvalidToken`	署名が無効
`ErrAlgorithmMismatch`	トークンのアルゴリズムが設定と一致しない
`ErrExpirationRequired`	`RequireExpiration` が有効だがトークンに `exp` クレームがない
`ErrTokenExpired`	トークンの有効期限切れ
`ErrTokenNotValidYet`	トークンがまだ有効ではない
`ErrTokenInvalidIssuer`	発行者が一致しない
`ErrTokenInvalidAudience`	オーディエンスが一致しない
`ErrTokenRevoked`	トークンが失効済み
`ErrInvalidClaims`	Claims の検証に失敗
`ErrTokenTypeMismatch`	アクセストークン（`token_type=access`）でリフレッシュを試行
`ErrRateLimitExceeded`	レート制限のしきい値を超過

Revoke

func (p *Processor) Revoke(tokenString string) error

署名を検証してトークン ID（jti）を抽出し、トークンをブラックリストに追加します。有効な署名を持つトークンのみが失効可能で、悪意のある呼び出し元が任意のトークン ID をブラックリストに追加するのを防ぎます。

TTL の振る舞い

トークンの exp がブラックリストエントリの TTL を決定します
exp のないトークンはデフォルトで 7 日間の TTL となります
TTL の上限は 30 日で、偽造された極端に長い exp によるメモリのロックを防ぎます（DoS 防御）
期限切れのトークンも失効可能です。エントリはブラックリストにより自動的にクリーンアップされます

パラメータ

パラメータ	型	説明
`tokenString`	`string`	失効させるトークン

戻り値

戻り値	型	説明
`err`	`error`	失効に失敗した場合にエラーを返す

エラー

エラー	発生条件
`ErrProcessorClosed`	Processor がクローズ済み
`ErrEmptyToken`	トークンが空
`ErrBlacklistNotConfigured`	ブラックリストが未設定
`ErrInvalidToken`	署名が無効または不正な形式のトークン
`ErrTokenInvalidIssuer`	発行者が一致しない
`ErrTokenInvalidAudience`	オーディエンスが一致しない
`ErrTokenMissingID`	トークンに `jti` クレームがない

IsRevoked

func (p *Processor) IsRevoked(tokenString string) (bool, error)

トークンが失効済みかどうかを確認します。署名を検証した後、ブラックリスト内のトークンの jti ステータスを検索します。ブラックリストが未設定の場合、false と nil エラーを返します。

パラメータ

パラメータ	型	説明
`tokenString`	`string`	JWT 文字列

戻り値

戻り値	型	説明
`revoked`	`bool`	失効済みかどうか
`err`	`error`	照会に失敗した場合にエラーを返す

エラー

エラー	発生条件
`ErrProcessorClosed`	Processor がクローズ済み
`ErrEmptyToken`	トークンが空
`ErrInvalidToken`	署名が無効または不正な形式のトークン
`ErrTokenInvalidIssuer`	発行者が一致しない
`ErrTokenInvalidAudience`	オーディエンスが一致しない
`ErrTokenMissingID`	トークンに `jti` クレームがない

ParseUnverified

func (p *Processor) ParseUnverified(tokenString string, claims any) error

署名を検証せずにトークンをパースします。Claims 情報を抽出するが信頼する必要がないシーンに使用します。

警告

返される Claims は未検証のため、信頼できません。デバッグやログ目的でのみ使用してください。

パラメータ

パラメータ	型	説明
`tokenString`	`string`	JWT 文字列
`claims`	`any`	ターゲットの Claims ポインタ

戻り値

戻り値	型	説明
`err`	`error`	パースに失敗した場合にエラーを返す

エラー

エラー	発生条件
`ErrProcessorClosed`	Processor がクローズ済み
`ErrEmptyToken`	トークンが空
ラップされたエラー	不正な形式のトークンに対するラップされたパースエラーを返す（センチネルエラーではなく、`errors.Is` で一致判定できない）

Close

func (p *Processor) Close() error

リソースを解放し、秘密鍵を安全にクリアします。複数回呼び出し可能で、2 回目以降は ErrProcessorClosed を返します。

戻り値

戻り値	型	説明
`err`	`error`	クローズに失敗した場合にエラーを返す

IsClosed

func (p *Processor) IsClosed() bool

Processor がクローズ済みかどうかを確認します。

戻り値

戻り値	型	説明
`closed`	`bool`	クローズ済みかどうか

Processor ​

Create ​

パラメータ ​

戻り値 ​

エラー ​

例 ​

Validate ​

パラメータ ​

戻り値 ​

エラー ​

例 ​

CreateRefresh ​

パラメータ ​

戻り値 ​

エラー ​

Refresh ​

パラメータ ​

戻り値 ​

エラー ​

ValidateInto ​

パラメータ ​

戻り値 ​

例 ​

エラー ​

RefreshInto ​

パラメータ ​

戻り値 ​

エラー ​

Revoke ​

パラメータ ​

戻り値 ​

エラー ​

IsRevoked ​

パラメータ ​

戻り値 ​

エラー ​

ParseUnverified ​

パラメータ ​

戻り値 ​

エラー ​

Close ​

戻り値 ​

IsClosed ​

戻り値 ​

Processor

Create

パラメータ

戻り値

エラー

例

Validate

パラメータ

戻り値

エラー

例

CreateRefresh

パラメータ

戻り値

エラー

Refresh

パラメータ

戻り値

エラー

ValidateInto

パラメータ

戻り値

例

エラー

RefreshInto

パラメータ

戻り値

エラー

Revoke

パラメータ

戻り値

エラー

IsRevoked

パラメータ

戻り値

エラー

ParseUnverified

パラメータ

戻り値

エラー

Close

戻り値

IsClosed

戻り値