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
- func RefreshToken(tokenString string) (string, error)
- func SetDefaultJWTManager(m *Manager)
- type Claims
- type Manager
- type TokenBlacklist
Constants ¶
This section is empty.
Variables ¶
var ( //ErrTokenExpired 令牌已过期 ErrTokenExpired = errors.New("令牌已过期") //ErrTokenInvalid 令牌无效 ErrTokenInvalid = errors.New("令牌无效") //ErrTokenMalformed 令牌格式错误 ErrTokenMalformed = errors.New("令牌格式错误") //ErrTokenNotValidYet 令牌尚未生效 ErrTokenNotValidYet = errors.New("令牌尚未生效") //ErrTokenRevoked 令牌已被撤销 ErrTokenRevoked = errors.New("令牌已被撤销") // 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）") )
Functions ¶
func GenerateToken ¶
GenerateToken 生成 JWT Token
func GenerateTokenWithCustomExpiry ¶
func GenerateTokenWithCustomExpiry(userID uint, username, role, userType string, expireSeconds int) (string, error)
GenerateTokenWithCustomExpiry 生成带自定义过期时间的 Token
func InvalidateToken ¶
InvalidateToken 使 Token 失效（加入黑名单）
func InvalidateTokenByID ¶
InvalidateTokenByID 直接通过 JTI 使 Token 失效 参数: jti JWT ID，expiry 过期时间
func RefreshToken ¶
RefreshToken 刷新 Token
安全约束（C9b 修复）：将旧 Token 加入黑名单的 Add 错误必须向上传播——若 Add 失败 （Redis 抖动或未启用）仍签发新 token，会导致旧 token 未拉黑、新旧 token 双有效， 形成会话固定窗口。故 Add 失败时不签发新 token（fail-closed）。
func SetDefaultJWTManager ¶ added in v1.1.0
func SetDefaultJWTManager(m *Manager)
SetDefaultJWTManager 提升指定 Manager 为全局默认（atomic 置换，并发安全，J1 修复）。
Types ¶
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 ¶
GetClaimsFromToken 获取 Token 的 Claims（不验证过期） 用于获取已过期 Token 的信息
type Manager ¶ added in v1.1.0
type Manager struct {
// contains filtered or unexported fields
}
Manager JWT 管理器（#10）。持有独立的 TokenBlacklist， 支持多实例（如区分 user-token 与 refresh-token 黑名单）。
func GetDefaultJWT ¶ added in v1.2.0
func GetDefaultJWT() *Manager
GetDefaultJWT 返回全局默认 JWT 管理器（并发安全，C9c/J1 修复）。 替代已删除的 DefaultJWT 包级变量。
func NewJWTManager ¶ added in v1.1.0
func NewJWTManager() *Manager
NewJWTManager 创建 JWT 管理器实例（blacklist 懒取全局 Redis）。
func NewJWTManagerWithRedis ¶ added in v1.1.0
NewJWTManagerWithRedis 创建 JWT 管理器并注入指定 Redis 客户端（用于多 Redis/测试隔离）。
func (*Manager) Blacklist ¶ added in v1.1.0
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 ¶ added in v1.1.0
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
IsBlacklisted 检查 JTI 是否在黑名单中
Source Files