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