Skip to main content

yang_base/token/
manager.rs

1//! Token 管理器实现
2//!
3//! 提供 JWT Token 的生成、验证、解析和刷新功能。
4
5use crate::error::BaseError;
6use crate::token::TokenClaims;
7use jsonwebtoken::{decode, encode, Algorithm, DecodingKey, EncodingKey, Header, Validation};
8use std::collections::HashSet;
9use std::time::{SystemTime, UNIX_EPOCH};
10use yang_db::RedisClient;
11
12/// 获取当前 Unix 时间戳(秒)
13///
14/// # 返回
15///
16/// - `Ok(u64)`: 当前 Unix 时间戳(秒)
17/// - `Err(BaseError::ConfigError)`: 系统时钟早于 UNIX_EPOCH(时钟异常)
18///
19/// # 错误
20///
21/// 当系统时钟早于 1970-01-01 00:00:00 UTC 时返回错误,
22/// 这通常意味着系统时钟配置异常。
23pub(crate) fn current_unix_timestamp() -> Result<u64, BaseError> {
24    SystemTime::now()
25        .duration_since(UNIX_EPOCH)
26        .map(|d| d.as_secs())
27        .map_err(|e| BaseError::ConfigError(format!("系统时钟异常,早于 UNIX_EPOCH: {}", e)))
28}
29
30/// 构建 Token 验证规则([`Validation`])。
31///
32/// 在构造 [`TokenManager`] 时一次性生成并缓存,避免每次 [`TokenManager::verify_token`]
33/// 调用都重新分配算法白名单、签发者/受众集合与必需声明集合(token-10 优化)。
34///
35/// 规则与历史行为保持一致:
36/// - 算法白名单仅含构造时指定的单一算法,防止算法混淆攻击(如 `none` 算法绕过)。
37/// - 显式校验签发者与受众。
38/// - 要求 `exp`、`iss`、`aud` 三个标准声明必须存在。
39/// - `leeway = 0`,不允许时间容差。
40fn build_validation(algorithm: Algorithm, issuer: &str, audience: &str) -> Validation {
41    let mut validation = Validation::new(algorithm);
42    validation.algorithms = vec![algorithm];
43    validation.set_issuer(&[issuer]);
44    validation.set_audience(&[audience]);
45    let mut required_claims = HashSet::new();
46    required_claims.insert("exp".to_string());
47    required_claims.insert("iss".to_string());
48    required_claims.insert("aud".to_string());
49    validation.required_spec_claims = required_claims;
50    validation.leeway = 0;
51    validation
52}
53
54/// Token 管理器
55///
56/// 提供 JWT Token 的生成、验证、解析和刷新功能。
57///
58/// # 支持的算法
59///
60/// - 对称加密:HS256、HS384、HS512
61/// - 非对称加密:RS256、RS384、RS512
62///
63/// # 示例
64///
65/// ```rust,ignore
66/// use yang_base::token::TokenManager;
67/// use jsonwebtoken::Algorithm;
68///
69/// // 创建对称加密的 Token 管理器
70/// let manager = TokenManager::new_symmetric(
71///     "your_secret_key",
72///     Algorithm::HS256,
73///     "issuer".to_string(),
74///     "audience".to_string(),
75///     3600,    // Access Token 有效期 1 小时
76///     86400,   // Refresh Token 有效期 1 天
77/// );
78///
79/// // 生成 Access Token
80/// let token = manager.generate_access_token(
81///     "user_123",
82///     serde_json::json!({"role": "admin"}),
83/// )?;
84///
85/// // 验证 Token
86/// let claims = manager.verify_token(&token)?;
87/// println!("用户 ID: {}", claims.sub);
88/// ```
89pub struct TokenManager {
90    /// 编码密钥
91    encoding_key: EncodingKey,
92
93    /// 解码密钥
94    decoding_key: DecodingKey,
95
96    /// 算法
97    algorithm: Algorithm,
98
99    /// 签发者
100    issuer: String,
101
102    /// 受众
103    audience: String,
104
105    /// Access Token 有效期(秒)
106    access_token_expiry: u64,
107
108    /// Refresh Token 有效期(秒)
109    refresh_token_expiry: u64,
110
111    /// 缓存的验证规则
112    ///
113    /// 在构造时由 [`build_validation`] 生成,[`TokenManager::verify_token`]
114    /// 直接复用,避免每次验证重复分配算法白名单与声明集合(token-10 优化)。
115    validation: Validation,
116
117    /// 预构建的 JWT Header
118    ///
119    /// 在构造时一次性设置 `typ: "JWT"` 与对应算法,生成 Token 时直接
120    /// 传引用,避免每次 `generate_*` 都重新分配 Header 与 `"JWT"` String
121    /// (PERF-11 优化)。
122    jwt_header: Header,
123
124    /// 显式注入的撤销存储;由 `ToolsBuilder` 在启动期连接。
125    revocation_cache: Option<RedisClient>,
126}
127
128impl TokenManager {
129    /// 创建新的 Token 管理器(对称加密)
130    ///
131    /// # 参数
132    ///
133    /// - `secret`: 密钥字符串
134    /// - `algorithm`: 加密算法(HS256、HS384、HS512)
135    /// - `issuer`: 签发者标识
136    /// - `audience`: 受众标识
137    /// - `access_token_expiry`: Access Token 有效期(秒)
138    /// - `refresh_token_expiry`: Refresh Token 有效期(秒)
139    ///
140    /// # 返回
141    ///
142    /// - `TokenManager`: Token 管理器实例
143    ///
144    /// # 示例
145    ///
146    /// ```rust
147    /// use yang_base::token::TokenManager;
148    /// use jsonwebtoken::Algorithm;
149    ///
150    /// let manager = TokenManager::new_symmetric(
151    ///     "my_secret_key",
152    ///     Algorithm::HS256,
153    ///     "my_app".to_string(),
154    ///     "my_users".to_string(),
155    ///     3600,
156    ///     86400,
157    /// );
158    /// ```
159    pub fn new_symmetric(
160        secret: &str,
161        algorithm: Algorithm,
162        issuer: String,
163        audience: String,
164        access_token_expiry: u64,
165        refresh_token_expiry: u64,
166    ) -> Self {
167        // AUTH-8: 白名单拦截非对称算法,避免构造后首次签发才失败
168        matches!(
169            algorithm,
170            Algorithm::HS256 | Algorithm::HS384 | Algorithm::HS512
171        )
172        .then_some(())
173        .expect("new_symmetric 仅支持 HMAC 算法 (HS256/HS384/HS512),请使用 new_asymmetric 处理非对称算法");
174
175        let mut jwt_header = Header::new(algorithm);
176        jwt_header.typ = Some("JWT".to_string());
177
178        Self {
179            encoding_key: EncodingKey::from_secret(secret.as_bytes()),
180            decoding_key: DecodingKey::from_secret(secret.as_bytes()),
181            algorithm,
182            validation: build_validation(algorithm, &issuer, &audience),
183            issuer,
184            audience,
185            access_token_expiry,
186            refresh_token_expiry,
187            jwt_header,
188            revocation_cache: None,
189        }
190    }
191
192    /// 创建新的 Token 管理器(非对称加密)
193    ///
194    /// # 参数
195    ///
196    /// - `private_key`: 私钥(PEM 格式)
197    /// - `public_key`: 公钥(PEM 格式)
198    /// - `algorithm`: 加密算法(RS256、RS384、RS512)
199    /// - `issuer`: 签发者标识
200    /// - `audience`: 受众标识
201    /// - `access_token_expiry`: Access Token 有效期(秒)
202    /// - `refresh_token_expiry`: Refresh Token 有效期(秒)
203    ///
204    /// # 返回
205    ///
206    /// - `Ok(TokenManager)`: Token 管理器实例
207    /// - `Err(BaseError)`: 密钥格式无效
208    ///
209    /// # 示例
210    ///
211    /// ```rust,ignore
212    /// use yang_base::token::TokenManager;
213    /// use jsonwebtoken::Algorithm;
214    ///
215    /// let private_key = "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----";
216    /// let public_key = "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----";
217    ///
218    /// let manager = TokenManager::new_asymmetric(
219    ///     private_key,
220    ///     public_key,
221    ///     Algorithm::RS256,
222    ///     "my_app".to_string(),
223    ///     "my_users".to_string(),
224    ///     3600,
225    ///     86400,
226    /// )?;
227    /// ```
228    pub fn new_asymmetric(
229        private_key: &str,
230        public_key: &str,
231        algorithm: Algorithm,
232        issuer: String,
233        audience: String,
234        access_token_expiry: u64,
235        refresh_token_expiry: u64,
236    ) -> Result<Self, BaseError> {
237        let encoding_key = EncodingKey::from_rsa_pem(private_key.as_bytes())
238            .map_err(|e| BaseError::TokenKeyInvalid(format!("私钥无效: {}", e)))?;
239
240        let decoding_key = DecodingKey::from_rsa_pem(public_key.as_bytes())
241            .map_err(|e| BaseError::TokenKeyInvalid(format!("公钥无效: {}", e)))?;
242
243        let mut jwt_header = Header::new(algorithm);
244        jwt_header.typ = Some("JWT".to_string());
245
246        Ok(Self {
247            encoding_key,
248            decoding_key,
249            algorithm,
250            validation: build_validation(algorithm, &issuer, &audience),
251            issuer,
252            audience,
253            access_token_expiry,
254            refresh_token_expiry,
255            jwt_header,
256            revocation_cache: None,
257        })
258    }
259
260    /// 由应用资源构建器注入 Token 撤销所使用的 Redis 客户端。
261    pub(crate) fn attach_revocation_cache(&mut self, cache: RedisClient) {
262        self.revocation_cache = Some(cache);
263    }
264
265    /// 返回显式配置的 Token 撤销存储。
266    pub(crate) fn revocation_cache(&self) -> Result<&RedisClient, BaseError> {
267        self.revocation_cache
268            .as_ref()
269            .ok_or(BaseError::RedisNotInitialized)
270    }
271
272    /// 生成 Access Token
273    ///
274    /// # 参数
275    ///
276    /// - `subject`: 主题(通常是用户 ID)
277    /// - `custom_claims`: 自定义声明(JSON 格式)
278    ///
279    /// # 返回
280    ///
281    /// - `Ok(String)`: Token 字符串
282    /// - `Err(BaseError)`: 生成失败
283    ///
284    /// # 示例
285    ///
286    /// ```rust,ignore
287    /// let token = manager.generate_access_token(
288    ///     "user_123",
289    ///     serde_json::json!({
290    ///         "role": "admin",
291    ///         "permissions": ["read", "write"]
292    ///     }),
293    /// )?;
294    /// ```
295    pub fn generate_access_token(
296        &self,
297        subject: &str,
298        custom_claims: serde_json::Value,
299    ) -> Result<String, BaseError> {
300        let now = current_unix_timestamp()?;
301        self.generate_access_token_at(subject, custom_claims, now)
302    }
303
304    /// 生成 Refresh Token
305    ///
306    /// # 参数
307    ///
308    /// - `subject`: 主题(通常是用户 ID)
309    ///
310    /// # 返回
311    ///
312    /// - `Ok(String)`: Token 字符串
313    /// - `Err(BaseError)`: 生成失败
314    ///
315    /// # 示例
316    ///
317    /// ```rust,ignore
318    /// let refresh_token = manager.generate_refresh_token("user_123")?;
319    /// ```
320    pub fn generate_refresh_token(&self, subject: &str) -> Result<String, BaseError> {
321        let now = current_unix_timestamp()?;
322        self.generate_refresh_token_at(subject, now)
323    }
324
325    /// 生成 Token 对(Access Token + Refresh Token)
326    ///
327    /// # 参数
328    ///
329    /// - `subject`: 主题(通常是用户 ID)
330    /// - `custom_claims`: 自定义声明(JSON 格式)
331    ///
332    /// # 返回
333    ///
334    /// - `Ok((access_token, refresh_token))`: Token 对
335    /// - `Err(BaseError)`: 生成失败
336    ///
337    /// # 示例
338    ///
339    /// ```rust,ignore
340    /// let (access_token, refresh_token) = manager.generate_token_pair(
341    ///     "user_123",
342    ///     serde_json::json!({"role": "admin"}),
343    /// )?;
344    /// ```
345    pub fn generate_token_pair(
346        &self,
347        subject: &str,
348        custom_claims: serde_json::Value,
349    ) -> Result<(String, String), BaseError> {
350        let now = current_unix_timestamp()?;
351        self.generate_token_pair_at(subject, custom_claims, now)
352    }
353
354    /// 使用预取时间戳生成 Token 对(内部方法,PERF-10 优化)。
355    ///
356    /// 与 [`generate_token_pair`] 功能相同,但接受外部传入的 `now` 时间戳,
357    /// 避免 access/refresh 各调一次 `current_unix_timestamp()` 系统调用。
358    ///
359    /// 供 [`rotate_refresh_token_from_claims`] 等已持有时间戳的调用方使用。
360    pub(crate) fn generate_token_pair_at(
361        &self,
362        subject: &str,
363        custom_claims: serde_json::Value,
364        now: u64,
365    ) -> Result<(String, String), BaseError> {
366        let access_token = self.generate_access_token_at(subject, custom_claims, now)?;
367        let refresh_token = self.generate_refresh_token_at(subject, now)?;
368
369        Ok((access_token, refresh_token))
370    }
371
372    /// 使用预取时间戳生成 Access Token(内部方法,PERF-10 优化)。
373    ///
374    /// 与 [`generate_access_token`] 功能相同,但接受外部传入的 `now` 时间戳。
375    fn generate_access_token_at(
376        &self,
377        subject: &str,
378        custom_claims: serde_json::Value,
379        now: u64,
380    ) -> Result<String, BaseError> {
381        let claims = TokenClaims {
382            iss: self.issuer.clone(),
383            sub: subject.to_string(),
384            aud: self.audience.clone(),
385            exp: now + self.access_token_expiry,
386            nbf: now,
387            iat: now,
388            jti: uuid::Uuid::new_v4().to_string(),
389            token_type: crate::token::TokenType::Access,
390            custom: custom_claims,
391        };
392
393        encode(&self.jwt_header, &claims, &self.encoding_key)
394            .map_err(BaseError::TokenGenerateFailed)
395    }
396
397    /// 使用预取时间戳生成 Refresh Token(内部方法,PERF-10 优化)。
398    ///
399    /// 与 [`generate_refresh_token`] 功能相同,但接受外部传入的 `now` 时间戳。
400    fn generate_refresh_token_at(&self, subject: &str, now: u64) -> Result<String, BaseError> {
401        let claims = TokenClaims {
402            iss: self.issuer.clone(),
403            sub: subject.to_string(),
404            aud: self.audience.clone(),
405            exp: now + self.refresh_token_expiry,
406            nbf: now,
407            iat: now,
408            jti: uuid::Uuid::new_v4().to_string(),
409            token_type: crate::token::TokenType::Refresh,
410            custom: serde_json::Value::Null,
411        };
412
413        encode(&self.jwt_header, &claims, &self.encoding_key)
414            .map_err(BaseError::TokenGenerateFailed)
415    }
416
417    /// 返回 Refresh Token 的有效期(秒)。
418    ///
419    /// 供同 crate 的撤销层(`revocation`)复用:按用户批量撤销时以此作为
420    /// `min_iat` 标记的 TTL,避免标记无限增长。
421    pub(crate) fn refresh_token_expiry(&self) -> u64 {
422        self.refresh_token_expiry
423    }
424
425    /// 验证 Token
426    ///
427    /// 验证 Token 的签名、过期时间、签发者和受众。
428    ///
429    /// # 参数
430    ///
431    /// - `token`: Token 字符串
432    ///
433    /// # 返回
434    ///
435    /// - `Ok(TokenClaims)`: Token 声明
436    /// - `Err(BaseError::TokenExpired)`: Token 已过期
437    /// - `Err(BaseError::TokenVerifyFailed)`: 签名或声明校验失败
438    /// - `Err(BaseError::TokenParseFailed)`: Token 解析失败
439    ///
440    /// 错误分类由 [`From<jsonwebtoken::errors::Error>`] 自动分流:
441    /// `ExpiredSignature` → `TokenExpired`,`InvalidToken`/`InvalidSignature` → `TokenVerifyFailed`,
442    /// 其他 → `TokenParseFailed`。
443    ///
444    /// # 示例
445    ///
446    /// ```rust,ignore
447    /// let claims = manager.verify_token(&token)?;
448    /// println!("用户 ID: {}", claims.sub);
449    /// println!("Token 类型: {}", claims.token_type);
450    /// ```
451    pub fn verify_token(&self, token: &str) -> Result<TokenClaims, BaseError> {
452        // 复用构造时缓存的 Validation(token-10),避免每次验证重复分配
453        // 算法白名单、签发者/受众集合与必需声明集合。
454        let token_data = decode::<TokenClaims>(token, &self.decoding_key, &self.validation)?;
455
456        Ok(token_data.claims)
457    }
458
459    /// 解析 Token(不验证签名)
460    ///
461    /// ⚠️ **安全警告:此方法不验证签名、不检查过期、不校验签发者/受众。
462    /// 攻击者可伪造任意 JWT。严禁在鉴权/授权决策中使用此方法的返回值。**
463    ///
464    /// 用于调试或获取 Token 信息而不验证其有效性。
465    ///
466    /// # 参数
467    ///
468    /// - `token`: Token 字符串
469    ///
470    /// # 返回
471    ///
472    /// - `Ok(TokenClaims)`: Token 声明
473    /// - `Err(BaseError)`: 解析失败
474    ///
475    /// # Safety
476    ///
477    /// **此方法绝对不能用于鉴权决策。**
478    ///
479    /// 该方法跳过签名验证、过期时间检查及所有标准声明校验,
480    /// 任何人均可伪造 Token 内容并通过此方法解析。
481    /// 仅允许在以下场景使用:
482    /// - 调试与日志记录(打印 Token 内容)
483    /// - 从已过期 Token 中提取用户标识以便刷新
484    /// - 单元测试中检查 Token 结构
485    ///
486    /// 在任何涉及权限判断、身份认证的代码路径中,
487    /// 必须使用 [`TokenManager::verify_token`] 代替本方法。
488    ///
489    /// # 警告
490    ///
491    /// 此方法不验证签名和过期时间,仅用于调试目的。
492    /// 不要在生产环境中使用此方法进行身份验证。
493    ///
494    /// # 示例
495    ///
496    /// ```rust,ignore
497    /// let claims = manager.parse_token_unsafe(&token)?;
498    /// println!("Token 内容: {:?}", claims);
499    /// ```
500    #[deprecated(
501        since = "0.1.0",
502        note = "此方法跳过所有 JWT 安全验证(签名/过期/签发者),仅可用于调试日志和单元测试。鉴权路径必须使用 verify_token 或 verify_token_checked。"
503    )]
504    pub fn parse_token_unsafe(&self, token: &str) -> Result<TokenClaims, BaseError> {
505        // 先读取 token 自带算法,再显式关闭所有鉴权相关校验。这样仍由 jsonwebtoken
506        // 负责 JWT 结构和 claims 反序列化,同时不会把本调试 API 误装成鉴权入口。
507        let header = jsonwebtoken::decode_header(token).map_err(BaseError::TokenParseFailed)?;
508        let mut validation = jsonwebtoken::Validation::new(header.alg);
509        validation.insecure_disable_signature_validation();
510        validation.validate_exp = false;
511        validation.validate_nbf = false;
512        validation.validate_aud = false;
513        validation.required_spec_claims.clear();
514        let token_data = jsonwebtoken::decode::<TokenClaims>(
515            token,
516            &jsonwebtoken::DecodingKey::from_secret(&[]),
517            &validation,
518        )
519        .map_err(BaseError::TokenParseFailed)?;
520
521        Ok(token_data.claims)
522    }
523
524    /// 检查 Token 是否即将过期
525    ///
526    /// # 参数
527    ///
528    /// - `token`: Token 字符串
529    /// - `threshold_secs`: 阈值(秒),如果剩余时间少于此值则返回 true
530    ///
531    /// # 返回
532    ///
533    /// - `Ok(bool)`: 是否即将过期
534    /// - `Err(BaseError)`: 检查失败
535    ///
536    /// # 示例
537    ///
538    /// ```rust,ignore
539    /// // 检查 Token 是否在 5 分钟内过期
540    /// if manager.is_token_expiring_soon(&token, 300)? {
541    ///     println!("Token 即将过期,需要刷新");
542    /// }
543    /// ```
544    pub fn is_token_expiring_soon(
545        &self,
546        token: &str,
547        threshold_secs: u64,
548    ) -> Result<bool, BaseError> {
549        let claims = self.verify_token(token)?;
550
551        // 使用辅助函数获取时间戳,避免时钟异常时 panic
552        let now = current_unix_timestamp()?;
553
554        let remaining = claims.exp.saturating_sub(now);
555
556        Ok(remaining < threshold_secs)
557    }
558
559    /// 使用 Refresh Token 刷新 Access Token
560    ///
561    /// 此方法会检查 Redis 黑名单,已撤销的 Refresh Token 将被拒绝。
562    ///
563    /// # 参数
564    ///
565    /// - `refresh_token`: Refresh Token 字符串
566    /// - `custom_claims`: 新的自定义声明
567    ///
568    /// # 返回
569    ///
570    /// - `Ok(String)`: 新的 Access Token
571    /// - `Err(BaseError)`: 刷新失败
572    ///
573    /// # 示例
574    ///
575    /// ```rust,ignore
576    /// let new_access_token = manager.refresh_access_token(
577    ///     &refresh_token,
578    ///     serde_json::json!({"role": "admin"}),
579    /// ).await?;
580    /// ```
581    pub async fn refresh_access_token(
582        &self,
583        refresh_token: &str,
584        custom_claims: serde_json::Value,
585    ) -> Result<String, BaseError> {
586        // 验证 Refresh Token(含黑名单检查,阻止已撤销的 Token 获取新 Access Token)
587        let claims = self.verify_token_checked(refresh_token).await?;
588
589        // 检查 Token 类型
590        if claims.token_type != crate::token::TokenType::Refresh {
591            return Err(BaseError::TokenTypeInvalid(
592                "期望 refresh token".to_string(),
593            ));
594        }
595
596        // 生成新的 Access Token
597        self.generate_access_token(&claims.sub, custom_claims)
598    }
599
600    /// 轮换 Refresh Token(刷新令牌轮换 / Refresh Token Rotation,token-1)。
601    ///
602    /// 每次刷新都签发全新的 Token 对,并立刻把旧 Refresh Token 原子拉黑,
603    /// 使其无法再次使用。这能限制刷新令牌泄露的影响面:一旦旧令牌被重放,
604    /// 因已进入黑名单而验证失败。
605    ///
606    /// 注:原子拉黑使用 [`SET key val NX EX ttl`],竞态安全——
607    /// 并发请求中仅第一个能成功写入黑名单,后续返回 [`BaseError::TokenRevoked`]。
608    ///
609    /// 执行流程:
610    /// 1. [`TokenManager::verify_token_checked`] 验证旧 Refresh Token 且确认未被撤销;
611    /// 2. 校验其 `token_type` 必须为 `"refresh"`;
612    /// 3. `TokenManager::try_revoke_once` 原子写入黑名单(SET NX EX);
613    ///    若返回 false(竞态中落败)则返回 [`BaseError::TokenRevoked`];
614    /// 4. [`TokenManager::generate_token_pair`] 以原 `sub` 与新的自定义声明签发新 Token 对。
615    ///
616    /// # 参数
617    ///
618    /// - `old_refresh`: 旧的 Refresh Token 字符串
619    /// - `custom_claims`: 新 Access Token 的自定义声明(JSON 格式)
620    ///
621    /// # 返回
622    ///
623    /// - `Ok((access_token, refresh_token))`: 新签发的 Token 对
624    /// - `Err(BaseError::TokenVerifyFailed)`: 旧 Token 签名/声明校验失败
625    /// - `Err(BaseError::TokenExpired)`: 旧 Token 已过期
626    /// - `Err(BaseError::TokenRevoked)`: 旧 Token 已被撤销(含竞态中落败)
627    /// - `Err(BaseError::TokenTypeInvalid)`: 传入的不是 Refresh Token
628    /// - `Err(BaseError::RedisOperationFailed)`: 原子写入黑名单失败
629    ///
630    /// # 依赖
631    ///
632    /// 本方法依赖基于 Redis 的 Token 黑名单(见 [`TokenManager::verify_token_checked`]
633    /// 与 `TokenManager::try_revoke_once`),调用前需由 `ToolsBuilder` 注入 Redis 撤销存储。
634    pub async fn rotate_refresh_token(
635        &self,
636        old_refresh: &str,
637        custom_claims: serde_json::Value,
638    ) -> Result<(String, String), BaseError> {
639        // 1. 验证旧 Refresh Token 且确认未被撤销
640        let old_claims = self.verify_token_checked(old_refresh).await?;
641
642        // 2~4:委托已验证 claims 的版本,避免重复逻辑
643        self.rotate_refresh_token_from_claims(&old_claims, custom_claims)
644            .await
645    }
646
647    /// 基于已验证 claims 轮换 Refresh Token(跳过内部二次验证)。
648    ///
649    /// 当调用方已在外部完成 [`TokenManager::verify_token_checked`] 并持有 [`TokenClaims`] 时,
650    /// 使用本方法可避免重复验证(节省 2 次 Redis RTT:黑名单查询 + 水位线查询)。
651    ///
652    /// 本方法仅执行:
653    /// 1. 校验 `token_type` 必须为 `"refresh"`;
654    /// 2. 原子拉黑旧 Refresh Token(`SET NX EX`);
655    /// 3. 以原 `sub` 与新自定义声明签发新 Token 对。
656    ///
657    /// # 参数
658    ///
659    /// - `old_claims`: 已通过 [`TokenManager::verify_token_checked`] 验证的旧 Refresh Token 声明
660    /// - `custom_claims`: 新 Access Token 的自定义声明(JSON 格式)
661    ///
662    /// # 返回
663    ///
664    /// - `Ok((access_token, refresh_token))`: 新签发的 Token 对
665    /// - `Err(BaseError::TokenTypeInvalid)`: `old_claims.token_type` 不是 `"refresh"`
666    /// - `Err(BaseError::TokenRevoked)`: 旧 Token 已被撤销(竞态中落败)
667    /// - `Err(BaseError::RedisOperationFailed)`: 原子写入黑名单失败
668    pub async fn rotate_refresh_token_from_claims(
669        &self,
670        old_claims: &TokenClaims,
671        custom_claims: serde_json::Value,
672    ) -> Result<(String, String), BaseError> {
673        // 1. 校验 Token 类型必须为 refresh(防御性检查)
674        if old_claims.token_type != crate::token::TokenType::Refresh {
675            return Err(BaseError::TokenTypeInvalid(
676                "期望 refresh token".to_string(),
677            ));
678        }
679
680        // 2. 原子拉黑旧 Refresh Token(SET NX EX),防止并发双重使用
681        let now = current_unix_timestamp()?;
682        let ttl = old_claims.exp.saturating_sub(now);
683        if !self.try_revoke_once(&old_claims.jti, ttl).await? {
684            return Err(BaseError::TokenRevoked);
685        }
686
687        // 3. 以原 subject 与新的自定义声明签发新的 Token 对
688        //    复用已有的 now 时间戳,避免重复系统调用(PERF-10)
689        self.generate_token_pair_at(&old_claims.sub, custom_claims, now)
690    }
691}
692
693// 手动实现 Debug trait,因为 EncodingKey 和 DecodingKey 不支持 Debug
694// 注意:故意不输出 encoding_key 和 decoding_key,防止密钥泄露到日志或调试输出中
695impl std::fmt::Debug for TokenManager {
696    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
697        f.debug_struct("TokenManager")
698            .field("algorithm", &self.algorithm)
699            .field("issuer", &self.issuer)
700            .field("audience", &self.audience)
701            .field("access_token_expiry", &self.access_token_expiry)
702            .field("refresh_token_expiry", &self.refresh_token_expiry)
703            // validation 仅含算法/签发者/受众/必需声明等非敏感校验规则,可安全输出
704            .field("validation", &self.validation)
705            // 使用 finish_non_exhaustive() 表明结构体还有其他字段(密钥字段)未输出
706            .finish_non_exhaustive()
707    }
708}