Documentation
¶
Overview ¶
Package auth 承载用户认证体系：bcrypt 密码哈希（与 sub2api 同参数）、 JWT 签发/验证（HS256，TTL 24h）与 RBAC 中间件（/user 组 RequireJWT + 快照用户状态校验；/admin = 静态 token OR platform_admin JWT）。
Index ¶
- Constants
- Variables
- func HashPassword(plain string) (string, error)
- func RequireJWT(iss *Issuer, users UserStatusProvider) func(http.Handler) http.Handler
- func RequireRole(roles ...domain.Role) func(http.Handler) http.Handler
- func ValidatePasswordLen(plain string) error
- func VerifyPassword(hash, plain string) bool
- type Claims
- type Issuer
- type UserStatusProvider
Constants ¶
const DefaultTTL = 24 * time.Hour
评审定夺①：JWT 密钥 config 强制（C3API_JWT_SECRET），缺失启动失败—— 随机生成 = 重启全失效 + 多实例不一致。 评审定夺②：TTL 24h（用户决策 2026-08-11，原 15min 短时效导致日常使用频繁掉线）。 降权即时生效 = adminAuth 快照 role 覆盖 claims.Role（见 internal/server/ middleware.go adminAuth——快照刷新 ≤Reload 周期即生效）；TTL 只约束 token 本身有效期，快照失效后长 TTL 仍作最终兜底。
Variables ¶
var ( ErrInvalidToken = errors.New("auth: invalid token") ErrTokenExpired = errors.New("auth: token expired") )
var ErrPasswordTooLong = errors.New("auth: password exceeds 72 bytes (bcrypt limit)")
ErrPasswordTooLong bcrypt 截断限制（≤72 字节；注册/改密拒绝超长——评审 M-2）。
Functions ¶
func HashPassword ¶
HashPassword bcrypt DefaultCost(10)，与 sub2api 完全一致——sub2api 迁移 存量 hash 直接可验证（同参数）。
func RequireJWT ¶
RequireJWT /user 组中间件：验证 Bearer JWT + 内存快照用户状态校验。 用户禁用 → 立即拒绝（快照刷新走 invalidate）；JWT 24h 长时效仅作快照 失效后的最终兜底（评审定夺②，用户决策 2026-08-11）。
func RequireRole ¶
RequireRole 端点级 RBAC 声明：claims.Role 必须 ∈ 允许角色。当前两级角色下 用户面端点不区分角色（platform_admin 也可用 /user 面），本中间件供后续 细分权限使用（/admin 组鉴权 = 静态 token OR platform_admin JWT）。
func ValidatePasswordLen ¶
ValidatePasswordLen 密码 ≤72 字节校验（bcrypt 截断限制；超长拒绝而非 静默截断——评审 M-2）。
func VerifyPassword ¶
VerifyPassword 校验明文与 bcrypt hash（sub2api 同参数 hash 直接可验证）。
Types ¶
type Claims ¶
type Claims struct {
UserID int64 `json:"user_id"`
Email string `json:"email"`
Role string `json:"role"`
Ver int64 `json:"ver"`
jwt.RegisteredClaims
}
Claims JWT 载荷：userID/email/role/ver/exp（HS256）。Ver = 签发时的 users.token_version 快照（spec 2026-08-25-jwt-password-revocation）：改密/ 重置密码原子递增版本号，RequireJWT/adminAuth 与内存快照比对，不等 → 401 ——撤销该用户全部既有 JWT，无需 Redis denylist（版本语义"只认最新"， 天然有界零额外读；存量票 ver 缺失解码 0 = DB 默认 0 ⇒ 升级平滑）。
type Issuer ¶
type Issuer struct {
// contains filtered or unexported fields
}
Issuer JWT 签发/验证器（单实例；HS256）。
type UserStatusProvider ¶
type UserStatusProvider interface {
UserSnapshot(userID int64) (domain.UserSnapshot, bool)
}
UserStatusProvider 用户快照（status+role 单次查找；proxy.Auth 实现；用户 变更走 invalidate → Auth.Reload 全量刷新，RequireJWT/adminAuth 不用 DB 直查——评审定夺②）。
Source Files