Skip to main content

yang_base/token/
manager.rs

1//! Token 管理器实现
2//!
3//! 提供 JWT Token 的生成、验证、解析和刷新功能。
4
5use crate::error::BaseError;
6use crate::token::TokenClaims;
7use jsonwebtoken::{
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}