Documentation
¶
Overview ¶
Package token 提供会话令牌的全生命周期管理:签发、验证、续签、注销。 采用 dual token 模式(短命 session + 长命 refresh,分离密钥)+ 黑名单注销, 补齐 pkg/middleware/auth(只做验证)缺失的"签发/续签/注销"半边。
设计要点:
- SessionToken claims: user_id + username + vars + token_id + exp + iat;
- refresh token 用独立密钥签发,携带 vars 以便续签时保留原值;
- 注销走黑名单:按 token_id 注销单会话,或按全局时间戳踢所有旧 token;
- 黑名单自动清理过期条目(ticker 周期剪枝)。
JWT 签名复用 github.com/golang-jwt/jwt/v5(HS256)。
与 pkg/middleware/auth 的分工:auth 中间件从请求提取 token 调 token.Verify, 本包负责 token 的产生与失效。两者组合即完整登录态。
零值不可用,用 New 构造。Manager 并发安全。
Index ¶
- Variables
- type Claims
- type Manager
- func (m *Manager) Issue(userID, username string, vars map[string]string, tokenID string) (session, refresh string, err error)
- func (m *Manager) Refresh(refreshToken string, newVars *map[string]string) (string, error)
- func (m *Manager) Revoke(tokenID string)
- func (m *Manager) RevokeAll(userID string)
- func (m *Manager) Stop()
- func (m *Manager) Verify(tokenStr string) (*Claims, error)
- func (m *Manager) VerifyRefresh(tokenStr string) (*Claims, error)
- type Option
Constants ¶
This section is empty.
Variables ¶
var ErrExpired = errors.New("token: expired")
ErrExpired token 已过期。
var ErrInvalidToken = errors.New("token: invalid")
ErrInvalidToken token 签名无效或格式错误。
var ErrKicked = errors.New("token: kicked")
ErrKicked 用户已被全局踢出(此时间前签发的 token 全部失效)。
var ErrRevoked = errors.New("token: revoked")
ErrRevoked token 已被注销(黑名单)。
Functions ¶
This section is empty.
Types ¶
type Claims ¶
type Claims struct {
TokenID string `json:"tid"` // 会话标识(非用户标识),用于黑名单注销
UserID string `json:"sub"` // 用户 ID(jwt sub)
Username string `json:"name,omitempty"` // 用户名(可选)
Vars map[string]string `json:"vars,omitempty"` // 业务元数据,免外查
jwt.RegisteredClaims
}
Claims 是 session token 的声明集合,嵌入 jwt.RegisteredClaims 提供标准字段。
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager 管理令牌签发、验证与注销。
func (*Manager) Issue ¶
func (m *Manager) Issue(userID, username string, vars map[string]string, tokenID string) (session, refresh string, err error)
Issue 签发一对 session + refresh token。tokenID 为空则随机生成。 vars 嵌入 session token(业务元数据),refresh token 不带 vars。
func (*Manager) Refresh ¶
Refresh 用 refresh token 换发新的 session token(复用原 tokenID,不产生新会话)。 newVars 非 nil 则覆盖原 vars,nil 则保留 refresh token 中携带的原 vars。
func (*Manager) RevokeAll ¶
RevokeAll 注销某用户的所有 token:记录全局失效时间,此前签发的全部失效。 RevokeAll 之后新签发的 token(iat > kickedAt)不受影响。 秒级粒度(jwt iat 截断到秒);为正确踢出同秒内已签发的 token,采用 <=。
type Option ¶
type Option func(*config)
Option 配置 Manager。
func WithRefreshKey ¶
WithRefreshKey 设置 refresh token 签名密钥(独立于 session key)。
func WithRefreshTTL ¶
WithRefreshTTL refresh token 有效期(默认 7 天)。
func WithSessionKey ¶
WithSessionKey 设置 session token 签名密钥(HS256,建议 32 字节)。
func WithSessionTTL ¶
WithSessionTTL session token 有效期(默认 1 小时)。
Source Files