Skip to main content

yang_base/token/
revocation.rs

1//! Token 撤销 / 黑名单机制(H-4)
2//!
3//! JWT 一经签发,在过期前本身无法失效。对登出、改密、强制下线等场景,
4//! 需要一个额外的撤销层。本模块基于 `ToolsBuilder` 显式注入的 Redis 客户端提供两层撤销能力:
5//!
6//! 1. **按单个 Token 撤销(jti 黑名单)**:用于登出。撤销时把 Token 的 `jti`
7//!    写入 Redis,TTL 设为 Token 剩余有效期(过期后 key 自动消失,黑名单不会
8//!    无限增长)。校验时在标准签名/过期校验之外,额外查一次该黑名单。
9//! 2. **按用户批量撤销(subject 时间水位线)**:用于改密、强制下线。撤销时把
10//!    "当前时间戳"写入 `token:user:{hex(sub)}:min_iat`(sub 经 hex 编码,避免特殊
11//!    字符导致 Redis key 歧义),TTL 取 Refresh Token 有效期。
12//!    校验时若该用户存在水位线且 Token 的 `iat` 早于或等于水位线,则视为已撤销——
13//!    一次写入即可让该用户在此之前签发的所有 Token 全部失效。
14//!
15//! 设计约束:**不修改** [`TokenManager::verify_token`] 的现有签名与行为,
16//! 撤销校验通过 [`TokenManager::verify_token_checked`] 提供,保持向后兼容。
17
18use crate::error::BaseError;
19use crate::token::manager::current_unix_timestamp;
20use crate::token::{TokenClaims, TokenManager};
21use yang_db::RedisValue;
22
23/// Redis 黑名单 key 前缀。最终 key 形如 `token:blacklist:{jti}`。
24const BLACKLIST_PREFIX: &str = "token:blacklist:";
25
26/// 根据 jti 构造黑名单 Redis key。
27fn blacklist_key(jti: &str) -> String {
28    format!("{BLACKLIST_PREFIX}{jti}")
29}
30
31/// 按用户撤销的时间水位线 key 前缀。最终 key 形如 `token:user:{hex(sub)}:min_iat`。
32const SUBJECT_MIN_IAT_PREFIX: &str = "token:user:";
33
34/// 将字节切片编码为小写 hex 字符串(无外部依赖)。
35fn hex_encode(bytes: &[u8]) -> String {
36    let mut s = String::with_capacity(bytes.len() * 2);
37    for b in bytes {
38        s.push_str(&format!("{b:02x}"));
39    }
40    s
41}
42
43/// 根据 subject 构造"最小签发时间水位线"Redis key。
44///
45/// `sub` 经 hex 编码后嵌入 key,避免含 `:` 等特殊字符导致 Redis key 歧义。
46fn subject_min_iat_key(sub: &str) -> String {
47    format!(
48        "{SUBJECT_MIN_IAT_PREFIX}{}:min_iat",
49        hex_encode(sub.as_bytes())
50    )
51}
52
53/// 判定一个 Token 的签发时间 `iat` 是否被用户水位线 `min_iat` 撤销。
54///
55/// 采用 `iat <= min_iat`(含等号)而非严格小于:撤销与签发都是**秒级**时间戳,
56/// 若用 `<`,则在改密/强制下线那一秒内签发的 Token(`iat == min_iat`)会逃过
57/// 撤销,留下 1 秒旁路窗口(NEW-6)。安全取「过撤一侧」——同秒签发的 Token 一并
58/// 撤销(用户至多需在该秒后重新登录一次),杜绝旁路。
59fn iat_revoked_by_watermark(iat: u64, min_iat: u64) -> bool {
60    iat <= min_iat
61}
62
63fn invalid_revocation_state(message: &str) -> BaseError {
64    BaseError::TokenRevocationStateInvalid(message.to_string())
65}
66
67/// 解析撤销水位线的唯一入口。损坏原值不进入错误文本,避免日志注入和敏感数据回显。
68fn parse_subject_min_iat(raw: &str) -> Result<u64, BaseError> {
69    raw.parse::<u64>()
70        .map_err(|_| invalid_revocation_state("用户撤销水位线不是有效的 u64 时间戳"))
71}
72
73/// 解析 Redis GET 水位线结果;只有 Nil 和 UTF-8 String 属于合法协议形态。
74fn parse_subject_min_iat_value(value: &RedisValue) -> Result<Option<u64>, BaseError> {
75    match value {
76        RedisValue::Nil => Ok(None),
77        RedisValue::String(raw) => parse_subject_min_iat(raw).map(Some),
78        _ => Err(invalid_revocation_state(
79            "用户撤销水位线的 Redis 类型不是 nil/string",
80        )),
81    }
82}
83
84/// 解析单条 GET pipeline 结果,避免高层字符串 API 将非 UTF-8 值折叠为 None。
85fn parse_subject_min_iat_pipeline_results(
86    results: &[RedisValue],
87) -> Result<Option<u64>, BaseError> {
88    let [value] = results else {
89        return Err(invalid_revocation_state(
90            "用户撤销水位线 GET pipeline 返回数量不是 1",
91        ));
92    };
93    parse_subject_min_iat_value(value)
94}
95
96/// 解析固定的 EXISTS + GET pipeline 结果,任何形态歧义均失败关闭。
97fn parse_revocation_pipeline_results(
98    results: &[RedisValue],
99) -> Result<(bool, Option<u64>), BaseError> {
100    let [blacklist_result, watermark_result] = results else {
101        return Err(invalid_revocation_state(
102            "Token 撤销查询 pipeline 返回数量不是 2",
103        ));
104    };
105    let blacklisted = match blacklist_result {
106        RedisValue::Int(0) => false,
107        RedisValue::Int(1) => true,
108        _ => {
109            return Err(invalid_revocation_state(
110                "Token 黑名单 EXISTS 结果不是 0/1 整数",
111            ))
112        }
113    };
114    Ok((blacklisted, parse_subject_min_iat_value(watermark_result)?))
115}
116
117impl TokenManager {
118    /// 撤销一个 Token(写入 Redis 黑名单)。
119    ///
120    /// 先验证 Token(确保 `jti`/`exp` 合法且签名有效),再按 `exp - now` 计算
121    /// 剩余 TTL 写入黑名单。若 Token 已过期则无需撤销,直接返回 `Ok(())`。
122    ///
123    /// # 参数
124    ///
125    /// - `token`: 待撤销的 Token 字符串
126    ///
127    /// # 返回
128    ///
129    /// - `Ok(())`: 撤销成功,或 Token 已过期无需撤销
130    /// - `Err(BaseError::TokenVerifyFailed)`: Token 签名/声明校验失败
131    /// - `Err(BaseError::TokenExpired)`: Token 已过期(无需撤销,返回 `Ok(())`)
132    /// - `Err(BaseError::RedisOperationFailed)`: 写黑名单失败
133    pub async fn revoke_token(&self, token: &str) -> Result<(), BaseError> {
134        let claims = self.verify_token(token)?;
135        self.revoke_claims(&claims).await
136    }
137
138    /// 按已验证的 [`TokenClaims`] 撤销 Token。
139    ///
140    /// 当调用方手头已有验证过的 claims 时,可避免重复验证。
141    ///
142    /// # 参数
143    ///
144    /// - `claims`: 已通过验证的 Token 声明
145    pub async fn revoke_claims(&self, claims: &TokenClaims) -> Result<(), BaseError> {
146        let now = current_unix_timestamp()?;
147        // 剩余有效期;已过期则无需写黑名单
148        let ttl = claims.exp.saturating_sub(now);
149        if ttl == 0 {
150            return Ok(());
151        }
152
153        self.revocation_cache()?
154            .setex(blacklist_key(&claims.jti), ttl as i64, "1")
155            .await
156            .map_err(BaseError::RedisOperationFailed)?;
157        Ok(())
158    }
159
160    /// 查询某个 `jti` 是否已被撤销。
161    ///
162    /// # 参数
163    ///
164    /// - `jti`: Token 的唯一标识
165    ///
166    /// # 返回
167    ///
168    /// - `Ok(true)`: 已撤销(命中黑名单)
169    /// - `Ok(false)`: 未撤销
170    /// - `Err(BaseError::RedisOperationFailed)`: Redis 查询失败
171    pub async fn is_revoked(&self, jti: &str) -> Result<bool, BaseError> {
172        let count = self
173            .revocation_cache()?
174            .exists(&[blacklist_key(jti)])
175            .await
176            .map_err(BaseError::RedisOperationFailed)?;
177        Ok(count > 0)
178    }
179
180    /// 按用户(subject)批量撤销该用户在此刻之前签发的所有 Token(token-3)。
181    ///
182    /// 在 Redis 中将 `token:user:{hex(sub)}:min_iat` 写为当前时间戳,作为该用户的
183    /// "最小有效签发时间"水位线。此后 [`TokenManager::verify_token_checked`]
184    /// 会拒绝任何 `iat` 早于或等于该水位线的 Token,从而让此前签发的全部 Token 一次性失效。
185    ///
186    /// 适用于**改密、强制下线**等需要让某用户全部会话立即失效的场景。
187    /// 水位线 TTL 取 Refresh Token 有效期(`TokenManager::refresh_token_expiry`),
188    /// 因为更早签发的 Token 至此必然已过期,水位线无需再保留,避免无限增长。
189    ///
190    /// # 参数
191    ///
192    /// - `sub`: 用户主题标识(即 Token 的 `sub`)
193    ///
194    /// # 返回
195    ///
196    /// - `Ok(())`: 水位线写入成功
197    /// - `Err(BaseError::RedisOperationFailed)`: Redis 写入失败
198    ///
199    /// # 依赖
200    ///
201    /// 依赖 `ToolsBuilder` 已为 TokenManager 连接 Redis 撤销存储。
202    pub async fn revoke_by_subject(&self, sub: &str) -> Result<(), BaseError> {
203        let now = current_unix_timestamp()?;
204        let ttl = self.refresh_token_expiry();
205        self.revocation_cache()?
206            .setex(subject_min_iat_key(sub), ttl as i64, now.to_string())
207            .await
208            .map_err(BaseError::RedisOperationFailed)?;
209        Ok(())
210    }
211
212    /// 查询某用户的"最小有效签发时间"水位线(若不存在返回 `None`)。
213    ///
214    /// # 参数
215    ///
216    /// - `sub`: 用户主题标识
217    ///
218    /// # 返回
219    ///
220    /// - `Ok(Some(ts))`: 该用户已被批量撤销,水位线时间戳为 `ts`
221    /// - `Ok(None)`: 该用户无批量撤销记录
222    /// - `Err(BaseError::RedisOperationFailed)`: Redis 查询失败
223    /// - `Err(BaseError::TokenRevocationStateInvalid)`: 水位线值损坏
224    pub async fn subject_min_iat(&self, sub: &str) -> Result<Option<u64>, BaseError> {
225        let mut pipeline = self.revocation_cache()?.pipeline();
226        pipeline.get(subject_min_iat_key(sub));
227        let results = pipeline
228            .execute()
229            .await
230            .map_err(BaseError::RedisOperationFailed)?;
231        parse_subject_min_iat_pipeline_results(&results)
232    }
233
234    /// 尝试原子撤销一次(SET key val NX EX ttl)。
235    ///
236    /// 与 `revoke_claims`(无条件 SETEX)不同,本方法仅在黑名单中尚不存在该 jti
237    /// 时执行写入。为轮换流程 [`TokenManager::rotate_refresh_token`] 提供竞态保护:
238    /// 并发请求中仅第一个能成功写入,后续返回 `false`。
239    ///
240    /// # 参数
241    ///
242    /// - `jti`: Token 唯一标识
243    /// - `ttl`: 黑名单过期时间(秒),源自 Token 剩余有效期。为 `0` 时直接返回
244    ///   `false`,避免向 Redis 发送 `EX 0`(非法参数)
245    ///
246    /// # 返回
247    ///
248    /// - `Ok(true)`: 成功将 jti 写入黑名单(本次是第一个到达的)
249    /// - `Ok(false)`: jti 已在黑名单中(竞态中落败),或 ttl 为 0(Token 已过期)
250    pub(crate) async fn try_revoke_once(&self, jti: &str, ttl: u64) -> Result<bool, BaseError> {
251        if ttl == 0 {
252            return Ok(false);
253        }
254        self.revocation_cache()?
255            .set_nx_ex(blacklist_key(jti), "1", ttl as i64)
256            .await
257            .map_err(BaseError::RedisOperationFailed)
258    }
259
260    /// 验证 Token,并额外检查黑名单。
261    ///
262    /// 在 [`TokenManager::verify_token`] 的全部校验之上,再做两层撤销检查:
263    /// 1. 查 `jti` 黑名单(单 Token 撤销 / 登出);
264    /// 2. 查该用户的 `min_iat` 水位线(按用户批量撤销 / 改密、强制下线):
265    ///    若存在水位线且 Token 的 `iat` 早于或等于它,则视为已撤销。
266    ///
267    /// 鉴权路径若需支持登出/撤销,应使用本方法替代 `verify_token`。
268    ///
269    /// # 参数
270    ///
271    /// - `token`: 待验证的 Token 字符串
272    ///
273    /// # 返回
274    ///
275    /// - `Ok(TokenClaims)`: 验证通过且未被撤销
276    /// - `Err(BaseError::TokenVerifyFailed)`: 签名/过期/声明校验失败
277    /// - `Err(BaseError::TokenRevoked)`: Token 已被撤销(命中黑名单或不晚于用户水位线)
278    /// - `Err(BaseError::RedisOperationFailed)`: 黑名单查询失败
279    /// - `Err(BaseError::TokenRevocationStateInvalid)`: 撤销查询结果或水位线损坏
280    pub async fn verify_token_checked(&self, token: &str) -> Result<TokenClaims, BaseError> {
281        let claims = self.verify_token(token)?;
282
283        // PERF-2: 将两次 Redis 读(EXISTS + GET)合并为一条 pipeline,2 RTT → 1 RTT。
284        // 对已黑名单 token 会失去短路(不再提前返回),但撤销场景罕见,可接受。
285        let mut pipeline = self.revocation_cache()?.pipeline();
286        pipeline
287            .exists(blacklist_key(&claims.jti))
288            .get(subject_min_iat_key(&claims.sub));
289        let results = pipeline
290            .execute()
291            .await
292            .map_err(BaseError::RedisOperationFailed)?;
293
294        let (blacklisted, min_iat) = parse_revocation_pipeline_results(&results)?;
295        if blacklisted {
296            return Err(BaseError::TokenRevoked);
297        }
298
299        if min_iat.is_some_and(|watermark| iat_revoked_by_watermark(claims.iat, watermark)) {
300            return Err(BaseError::TokenRevoked);
301        }
302
303        Ok(claims)
304    }
305}
306
307#[cfg(test)]
308mod tests {
309    use super::*;
310
311    #[test]
312    fn test_blacklist_key_format() {
313        assert_eq!(blacklist_key("abc-123"), "token:blacklist:abc-123");
314    }
315
316    #[test]
317    fn test_subject_min_iat_key_format() {
318        // sub 经 hex 编码,避免特殊字符导致 key 歧义
319        assert_eq!(
320            subject_min_iat_key("user_42"),
321            "token:user:757365725f3432:min_iat"
322        );
323    }
324
325    #[test]
326    fn test_subject_min_iat_key_colon_safe() {
327        // sub 含冒号时 hex 编码后不再产生歧义
328        let key = subject_min_iat_key("user:admin");
329        assert_eq!(key, "token:user:757365723a61646d696e:min_iat");
330        // 确保 key 中不会出现未转义的冒号(除固定分隔符外)
331        let after_prefix = key.strip_prefix("token:user:").unwrap();
332        let (hex_part, rest) = after_prefix.split_once(':').unwrap();
333        assert_eq!(rest, "min_iat");
334        // hex 部分只含 0-9a-f
335        assert!(hex_part.chars().all(|c| c.is_ascii_hexdigit()));
336    }
337
338    /// NEW-6:同秒签发(iat == min_iat)必须被撤销,杜绝 1 秒旁路窗口。
339    #[test]
340    fn test_iat_revoked_by_watermark_same_second() {
341        // 早于水位线:撤销
342        assert!(iat_revoked_by_watermark(100, 200));
343        // 同秒签发:必须撤销(含等号,这是修复点)
344        assert!(iat_revoked_by_watermark(200, 200));
345        // 晚于水位线:放行
346        assert!(!iat_revoked_by_watermark(201, 200));
347    }
348
349    #[test]
350    fn watermark_parser_accepts_only_absent_or_valid_u64_string() {
351        assert_eq!(
352            parse_subject_min_iat_value(&yang_db::RedisValue::Nil).expect("缺少水位线是合法状态"),
353            None
354        );
355        assert_eq!(
356            parse_subject_min_iat_value(&yang_db::RedisValue::String("0".to_string()))
357                .expect("u64 下界应有效"),
358            Some(0)
359        );
360        assert_eq!(
361            parse_subject_min_iat_value(&yang_db::RedisValue::String(u64::MAX.to_string()))
362                .expect("u64 上界应有效"),
363            Some(u64::MAX)
364        );
365    }
366
367    #[test]
368    fn watermark_parser_rejects_corrupt_strings_and_wrong_redis_types() {
369        let invalid_values = [
370            yang_db::RedisValue::String(String::new()),
371            yang_db::RedisValue::String("-1".to_string()),
372            yang_db::RedisValue::String("18446744073709551616".to_string()),
373            yang_db::RedisValue::String("secret-corrupt-watermark".to_string()),
374            yang_db::RedisValue::Bytes(vec![0xff]),
375            yang_db::RedisValue::Int(42),
376            yang_db::RedisValue::Bool(false),
377            yang_db::RedisValue::Array(Vec::new()),
378        ];
379
380        for value in invalid_values {
381            let error = parse_subject_min_iat_value(&value)
382                .expect_err("损坏或错误类型的水位线必须失败关闭");
383            assert!(
384                matches!(&error, BaseError::TokenRevocationStateInvalid(_)),
385                "损坏水位线必须返回结构化错误,实际为: {error:?}"
386            );
387            assert_eq!(error.code(), 400008);
388            assert!(error.is_server_error());
389            assert!(
390                !error.to_string().contains("secret-corrupt-watermark"),
391                "错误不得回显 Redis 中的损坏原值"
392            );
393        }
394    }
395
396    #[test]
397    fn subject_watermark_pipeline_parser_requires_exactly_one_result() {
398        for values in [
399            vec![],
400            vec![yang_db::RedisValue::Nil, yang_db::RedisValue::Nil],
401        ] {
402            assert!(
403                matches!(
404                    parse_subject_min_iat_pipeline_results(&values),
405                    Err(BaseError::TokenRevocationStateInvalid(_))
406                ),
407                "水位线 GET 必须恰好返回一个结果: {values:?}"
408            );
409        }
410
411        assert_eq!(
412            parse_subject_min_iat_pipeline_results(&[yang_db::RedisValue::Nil])
413                .expect("缺少水位线是合法状态"),
414            None
415        );
416        assert_eq!(
417            parse_subject_min_iat_pipeline_results(&[yang_db::RedisValue::String(
418                "42".to_string()
419            )])
420            .expect("合法水位线应通过"),
421            Some(42)
422        );
423    }
424
425    #[test]
426    fn revocation_pipeline_parser_rejects_ambiguous_results() {
427        for values in [
428            vec![],
429            vec![yang_db::RedisValue::Int(0)],
430            vec![
431                yang_db::RedisValue::Int(0),
432                yang_db::RedisValue::Nil,
433                yang_db::RedisValue::Nil,
434            ],
435            vec![
436                yang_db::RedisValue::String("0".to_string()),
437                yang_db::RedisValue::Nil,
438            ],
439            vec![yang_db::RedisValue::Int(-1), yang_db::RedisValue::Nil],
440            vec![yang_db::RedisValue::Int(2), yang_db::RedisValue::Nil],
441        ] {
442            assert!(
443                matches!(
444                    parse_revocation_pipeline_results(&values),
445                    Err(BaseError::TokenRevocationStateInvalid(_))
446                ),
447                "不明确的撤销查询结果必须失败关闭: {values:?}"
448            );
449        }
450
451        assert_eq!(
452            parse_revocation_pipeline_results(&[
453                yang_db::RedisValue::Int(0),
454                yang_db::RedisValue::String("42".to_string()),
455            ])
456            .expect("固定合法结果应通过"),
457            (false, Some(42))
458        );
459        assert_eq!(
460            parse_revocation_pipeline_results(&[
461                yang_db::RedisValue::Int(1),
462                yang_db::RedisValue::Nil,
463            ])
464            .expect("黑名单命中且无水位线是合法状态"),
465            (true, None)
466        );
467    }
468}