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}