jwt

Documentation

Index

• Variables
• func GenerateToken(userID uint, username, role, userType string) (string, error)
• func GenerateTokenWithCustomExpiry(userID uint, username, role, userType string, expireSeconds int) (string, error)
• func GetJTI(tokenString string) (string, error)
• func InvalidateToken(tokenString string) error
• func InvalidateTokenByID(jti string, expiry time.Time) error
• func IsTokenRevoked(jti string) (bool, error)
• func RefreshToken(tokenString string) (string, error)
• func SetDefaultJWTManager(m *Manager)
• type BlacklistPolicy
• type Claims
  • func GetClaimsFromToken(tokenString string) (*Claims, error)
  • func ParseToken(tokenString string) (*Claims, error)
  • func ParseTokenWithBlacklistPolicy(tokenString string, policy BlacklistPolicy) (*Claims, error)
• type Manager
  • func GetDefaultJWT() *Manager
  • func NewJWTManager() *Manager
  • func NewJWTManagerWithRedis(client *redis.Client) *Manager
  • func (m *Manager) Blacklist() *TokenBlacklist
• type TokenBlacklist
  • func NewTokenBlacklist(client *redis.Client) *TokenBlacklist
  • func (tb *TokenBlacklist) Add(jti string, expiry time.Time) error
  • func (tb *TokenBlacklist) IsBlacklisted(jti string) (bool, error)

Variables

var (
	//ErrTokenExpired 令牌已过期
	ErrTokenExpired = errors.New("令牌已过期")
	//ErrTokenInvalid 令牌无效
	ErrTokenInvalid = errors.New("令牌无效")
	//ErrTokenMalformed 令牌格式错误
	ErrTokenMalformed = errors.New("令牌格式错误")
	//ErrTokenNotValidYet 令牌尚未生效
	ErrTokenNotValidYet = errors.New("令牌尚未生效")
	//ErrTokenRevoked 令牌已被撤销
	ErrTokenRevoked = errors.New("令牌已被撤销")
	// ErrBlacklistUnavailable Redis 未初始化或不可用，黑名单功能失效（C9a 修复）。
	// Add 返回此错误使调用方（RefreshToken/InvalidateToken）感知黑名单不可用并 fail-closed，
	// 避免无 Redis 时静默成功致撤销/刷新失效、新旧 token 双有效。
	// IsBlacklisted 在无 Redis 时仍返回 false（验证侧 fail-open 是无 Redis 部署的固有局限，
	// 文档约束：安全敏感场景必须启用 Redis）。
	ErrBlacklistUnavailable = errors.New("token 黑名单不可用：Redis 未初始化")
	// ErrEmptySecret JWT 密钥为空（P0 修复）。空 secret 意味着以零长度 HMAC 密钥签发/校验，
	// 任何以 "" 签名的 token 都会通过——签发与校验一律 fail-closed 拒绝，杜绝该空密钥绕过。
	ErrEmptySecret = errors.New("jwt.secret 未配置：拒绝签发/校验（防空密钥导致任意 token 通过）")
	// ErrUnsupportedAlgorithm 配置了不支持的签名算法（P0 修复）。
	// 本实现仅支持 HMAC 族（HS256/HS384/HS512）；RS256 等非对称算法暂不支持，
	// 不再静默回退 HS256——避免用户误以为在用非对称算法、实则 HMAC，并助长算法混淆攻击。
	ErrUnsupportedAlgorithm = errors.New("jwt: 不支持的签名算法（仅支持 HS256/HS384/HS512）")
	// ErrInvalidExpiry 过期时间非法。签发非正过期时间的 token 会立即失效或产生不可预期会话语义。
	ErrInvalidExpiry = errors.New("jwt: 过期时间必须大于 0")
	// ErrEmptyJTI 空 JTI 无法匹配任何正常 token，却会写入 jwt_bl: 这种永不命中的黑名单键。
	ErrEmptyJTI = errors.New("jwt: jti 不能为空")
)

Functions

func GenerateToken

func GenerateToken(userID uint, username, role, userType string) (string, error)

GenerateToken 生成 JWT Token

func GenerateTokenWithCustomExpiry

func GenerateTokenWithCustomExpiry(userID uint, username, role, userType string, expireSeconds int) (string, error)

GenerateTokenWithCustomExpiry 生成带自定义过期时间的 Token

func GetJTI

func GetJTI(tokenString string) (string, error)

GetJTI 从 Token 中提取 JTI（不验证签名） 用于需要在验证前获取 JTI 的场景

func InvalidateToken

func InvalidateToken(tokenString string) error

InvalidateToken 使 Token 失效（加入黑名单）

func InvalidateTokenByID

func InvalidateTokenByID(jti string, expiry time.Time) error

InvalidateTokenByID 直接通过 JTI 使 Token 失效 参数: jti JWT ID，expiry 过期时间

func IsTokenRevoked

func IsTokenRevoked(jti string) (bool, error)

IsTokenRevoked 检查 Token 是否被撤销（通过 JTI）。 返回 (是否撤销, 错误)；黑名单后端不可用时返回 (false, ErrBlacklistUnavailable)。

func RefreshToken

func RefreshToken(tokenString string) (string, error)

RefreshToken 刷新 Token

安全约束（C9b 修复）：将旧 Token 加入黑名单的 Add 错误必须向上传播——若 Add 失败 （Redis 抖动或未启用）仍签发新 token，会导致旧 token 未拉黑、新旧 token 双有效， 形成会话固定窗口。故 Add 失败时不签发新 token（fail-closed）。

func SetDefaultJWTManager

func SetDefaultJWTManager(m *Manager)

SetDefaultJWTManager 提升指定 Manager 为全局默认（atomic 置换，并发安全，J1 修复）。

Types

type BlacklistPolicy

type BlacklistPolicy int

BlacklistPolicy 控制解析 Token 时遇到黑名单查询错误的处理策略。 ParseToken 默认 BlacklistFailClosed（黑名单不可检查即拒绝）； 需显式 fail-open（仅无 Redis 或低安全场景）用 ParseTokenWithBlacklistPolicy(..., BlacklistFailOpen)。

const (
	// BlacklistFailOpen 黑名单查询出错时放行 Token（仅用于无 Redis 或低安全场景，非默认）。
	BlacklistFailOpen BlacklistPolicy = iota
	// BlacklistFailClosed 黑名单查询出错时拒绝 Token（默认；ParseToken 即用此策略）。
	BlacklistFailClosed
)

type Claims

type Claims struct {
	UserID   uint   `json:"user_id"`
	Username string `json:"username"`
	Role     string `json:"role"`      // admin 或 staff
	UserType string `json:"user_type"` // super_admin, admin, staff
	JTI      string `json:"jti"`       // JWT ID（唯一标识，用于黑名单）
	jwt.RegisteredClaims
}

Claims JWT 声明

func GetClaimsFromToken

func GetClaimsFromToken(tokenString string) (*Claims, error)

GetClaimsFromToken 获取 Token 的 Claims（不验证过期） 用于获取已过期 Token 的信息

func ParseToken

func ParseToken(tokenString string) (*Claims, error)

ParseToken 解析 JWT Token。默认 fail-closed：黑名单后端不可检查时返回 ErrBlacklistUnavailable，拒绝该 Token。需要显式 fail-open（仅无 Redis 或低安全场景） 请用 ParseTokenWithBlacklistPolicy(token, BlacklistFailOpen)。

func ParseTokenWithBlacklistPolicy

func ParseTokenWithBlacklistPolicy(tokenString string, policy BlacklistPolicy) (*Claims, error)

ParseTokenWithBlacklistPolicy 使用显式黑名单查询策略解析 JWT Token。

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

Manager JWT 管理器（#10）。持有独立的 TokenBlacklist， 支持多实例（如区分 user-token 与 refresh-token 黑名单）。

func GetDefaultJWT

func GetDefaultJWT() *Manager

GetDefaultJWT 返回全局默认 JWT 管理器（并发安全，C9c/J1 修复）。 替代已删除的 DefaultJWT 包级变量。

func NewJWTManager

func NewJWTManager() *Manager

NewJWTManager 创建 JWT 管理器实例（blacklist 懒取全局 Redis）。

func NewJWTManagerWithRedis

func NewJWTManagerWithRedis(client *redis.Client) *Manager

NewJWTManagerWithRedis 创建 JWT 管理器并注入指定 Redis 客户端（用于多 Redis/测试隔离）。

func (*Manager) Blacklist

func (m *Manager) Blacklist() *TokenBlacklist

Blacklist 返回 Manager 持有的黑名单实例。

type TokenBlacklist

type TokenBlacklist struct {
	// contains filtered or unexported fields
}

TokenBlacklist Token 黑名单管理（使用 JTI 优化）。 client 为 nil 时回退到 database.GetRedis()，兼容存量未注入场景。

func NewTokenBlacklist

func NewTokenBlacklist(client *redis.Client) *TokenBlacklist

NewTokenBlacklist 创建黑名单实例，client 可为 nil（懒取全局 Redis）。

func (*TokenBlacklist) Add

func (tb *TokenBlacklist) Add(jti string, expiry time.Time) error

Add 将 Token 的 JTI 加入黑名单 参数: jti JWT ID，expiry Token 过期时间

无 Redis 时返回 ErrBlacklistUnavailable（C9a 修复）：让调用方（RefreshToken/InvalidateToken） 感知黑名单不可用并 fail-closed，避免无 Redis 时静默成功致撤销失效。

func (*TokenBlacklist) IsBlacklisted

func (tb *TokenBlacklist) IsBlacklisted(jti string) (bool, error)

IsBlacklisted 检查 JTI 是否在黑名单中。 命中返回 (true, nil)；未命中返回 (false, nil)； Redis 未启用或不可达返回 (false, ErrBlacklistUnavailable)，由调用方决定 fail-open/fail-closed。