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) -> 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}