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