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