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