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};
21
22/// Redis 黑名单 key 前缀。最终 key 形如 `token:blacklist:{jti}`。
23const BLACKLIST_PREFIX: &str = "token:blacklist:";
24
25/// 根据 jti 构造黑名单 Redis key。
26fn blacklist_key(jti: &str) -> String {
27    format!("{BLACKLIST_PREFIX}{jti}")
28}
29
30/// 按用户撤销的时间水位线 key 前缀。最终 key 形如 `token:user:{hex(sub)}:min_iat`。
31const SUBJECT_MIN_IAT_PREFIX: &str = "token:user:";
32
33/// 将字节切片编码为小写 hex 字符串(无外部依赖)。
34fn hex_encode(bytes: &[u8]) -> String {
35    let mut s = String::with_capacity(bytes.len() * 2);
36    for b in bytes {
37        s.push_str(&format!("{b:02x}"));
38    }
39    s
40}
41
42/// 根据 subject 构造"最小签发时间水位线"Redis key。
43///
44/// `sub` 经 hex 编码后嵌入 key,避免含 `:` 等特殊字符导致 Redis key 歧义。
45fn subject_min_iat_key(sub: &str) -> String {
46    format!(
47        "{SUBJECT_MIN_IAT_PREFIX}{}:min_iat",
48        hex_encode(sub.as_bytes())
49    )
50}
51
52/// 判定一个 Token 的签发时间 `iat` 是否被用户水位线 `min_iat` 撤销。
53///
54/// 采用 `iat <= min_iat`(含等号)而非严格小于:撤销与签发都是**秒级**时间戳,
55/// 若用 `<`,则在改密/强制下线那一秒内签发的 Token(`iat == min_iat`)会逃过
56/// 撤销,留下 1 秒旁路窗口(NEW-6)。安全取「过撤一侧」——同秒签发的 Token 一并
57/// 撤销(用户至多需在该秒后重新登录一次),杜绝旁路。
58fn iat_revoked_by_watermark(iat: u64, min_iat: u64) -> bool {
59    iat <= min_iat
60}
61
62impl TokenManager {
63    /// 撤销一个 Token(写入 Redis 黑名单)。
64    ///
65    /// 先验证 Token(确保 `jti`/`exp` 合法且签名有效),再按 `exp - now` 计算
66    /// 剩余 TTL 写入黑名单。若 Token 已过期则无需撤销,直接返回 `Ok(())`。
67    ///
68    /// # 参数
69    ///
70    /// - `token`: 待撤销的 Token 字符串
71    ///
72    /// # 返回
73    ///
74    /// - `Ok(())`: 撤销成功,或 Token 已过期无需撤销
75    /// - `Err(BaseError::TokenVerifyFailed)`: Token 签名/声明校验失败
76    /// - `Err(BaseError::TokenExpired)`: Token 已过期(无需撤销,返回 `Ok(())`)
77    /// - `Err(BaseError::RedisOperationFailed)`: 写黑名单失败
78    pub async fn revoke_token(&self, token: &str) -> Result<(), BaseError> {
79        let claims = self.verify_token(token)?;
80        self.revoke_claims(&claims).await
81    }
82
83    /// 按已验证的 [`TokenClaims`] 撤销 Token。
84    ///
85    /// 当调用方手头已有验证过的 claims 时,可避免重复验证。
86    ///
87    /// # 参数
88    ///
89    /// - `claims`: 已通过验证的 Token 声明
90    pub async fn revoke_claims(&self, claims: &TokenClaims) -> Result<(), BaseError> {
91        let now = current_unix_timestamp()?;
92        // 剩余有效期;已过期则无需写黑名单
93        let ttl = claims.exp.saturating_sub(now);
94        if ttl == 0 {
95            return Ok(());
96        }
97
98        self.revocation_cache()?
99            .setex(blacklist_key(&claims.jti), ttl as i64, "1")
100            .await
101            .map_err(BaseError::RedisOperationFailed)?;
102        Ok(())
103    }
104
105    /// 查询某个 `jti` 是否已被撤销。
106    ///
107    /// # 参数
108    ///
109    /// - `jti`: Token 的唯一标识
110    ///
111    /// # 返回
112    ///
113    /// - `Ok(true)`: 已撤销(命中黑名单)
114    /// - `Ok(false)`: 未撤销
115    /// - `Err(BaseError::RedisOperationFailed)`: Redis 查询失败
116    pub async fn is_revoked(&self, jti: &str) -> Result<bool, BaseError> {
117        let count = self
118            .revocation_cache()?
119            .exists(&[blacklist_key(jti)])
120            .await
121            .map_err(BaseError::RedisOperationFailed)?;
122        Ok(count > 0)
123    }
124
125    /// 按用户(subject)批量撤销该用户在此刻之前签发的所有 Token(token-3)。
126    ///
127    /// 在 Redis 中将 `token:user:{hex(sub)}:min_iat` 写为当前时间戳,作为该用户的
128    /// "最小有效签发时间"水位线。此后 [`TokenManager::verify_token_checked`]
129    /// 会拒绝任何 `iat` 早于该水位线的 Token,从而让此前签发的全部 Token 一次性失效。
130    ///
131    /// 适用于**改密、强制下线**等需要让某用户全部会话立即失效的场景。
132    /// 水位线 TTL 取 Refresh Token 有效期(`TokenManager::refresh_token_expiry`),
133    /// 因为更早签发的 Token 至此必然已过期,水位线无需再保留,避免无限增长。
134    ///
135    /// # 参数
136    ///
137    /// - `sub`: 用户主题标识(即 Token 的 `sub`)
138    ///
139    /// # 返回
140    ///
141    /// - `Ok(())`: 水位线写入成功
142    /// - `Err(BaseError::RedisOperationFailed)`: Redis 写入失败
143    ///
144    /// # 依赖
145    ///
146    /// 依赖 `ToolsBuilder` 已为 TokenManager 连接 Redis 撤销存储。
147    pub async fn revoke_by_subject(&self, sub: &str) -> Result<(), BaseError> {
148        let now = current_unix_timestamp()?;
149        let ttl = self.refresh_token_expiry();
150        self.revocation_cache()?
151            .setex(subject_min_iat_key(sub), ttl as i64, now.to_string())
152            .await
153            .map_err(BaseError::RedisOperationFailed)?;
154        Ok(())
155    }
156
157    /// 查询某用户的"最小有效签发时间"水位线(若不存在返回 `None`)。
158    ///
159    /// # 参数
160    ///
161    /// - `sub`: 用户主题标识
162    ///
163    /// # 返回
164    ///
165    /// - `Ok(Some(ts))`: 该用户已被批量撤销,水位线时间戳为 `ts`
166    /// - `Ok(None)`: 该用户无批量撤销记录
167    /// - `Err(BaseError::RedisOperationFailed)`: Redis 查询失败
168    pub async fn subject_min_iat(&self, sub: &str) -> Result<Option<u64>, BaseError> {
169        match self
170            .revocation_cache()?
171            .get(subject_min_iat_key(sub))
172            .await
173            .map_err(BaseError::RedisOperationFailed)?
174        {
175            // 解析失败视为无水位线,避免因脏数据误杀合法 Token
176            Some(raw) => {
177                if let Ok(ts) = raw.parse::<u64>() {
178                    Ok(Some(ts))
179                } else {
180                    tracing::warn!(sub, raw, "水位线解析失败,视为无水位线");
181                    Ok(None)
182                }
183            }
184            None => Ok(None),
185        }
186    }
187
188    /// 尝试原子撤销一次(SET key val NX EX ttl)。
189    ///
190    /// 与 `revoke_claims`(无条件 SETEX)不同,本方法仅在黑名单中尚不存在该 jti
191    /// 时执行写入。为轮换流程 [`TokenManager::rotate_refresh_token`] 提供竞态保护:
192    /// 并发请求中仅第一个能成功写入,后续返回 `false`。
193    ///
194    /// # 参数
195    ///
196    /// - `jti`: Token 唯一标识
197    /// - `ttl`: 黑名单过期时间(秒),源自 Token 剩余有效期。为 `0` 时直接返回
198    ///   `false`,避免向 Redis 发送 `EX 0`(非法参数)
199    ///
200    /// # 返回
201    ///
202    /// - `Ok(true)`: 成功将 jti 写入黑名单(本次是第一个到达的)
203    /// - `Ok(false)`: jti 已在黑名单中(竞态中落败),或 ttl 为 0(Token 已过期)
204    pub(crate) async fn try_revoke_once(&self, jti: &str, ttl: u64) -> Result<bool, BaseError> {
205        if ttl == 0 {
206            return Ok(false);
207        }
208        self.revocation_cache()?
209            .set_nx_ex(blacklist_key(jti), "1", ttl as i64)
210            .await
211            .map_err(BaseError::RedisOperationFailed)
212    }
213
214    /// 验证 Token,并额外检查黑名单。
215    ///
216    /// 在 [`TokenManager::verify_token`] 的全部校验之上,再做两层撤销检查:
217    /// 1. 查 `jti` 黑名单(单 Token 撤销 / 登出);
218    /// 2. 查该用户的 `min_iat` 水位线(按用户批量撤销 / 改密、强制下线):
219    ///    若存在水位线且 Token 的 `iat` 早于它,则视为已撤销。
220    ///
221    /// 鉴权路径若需支持登出/撤销,应使用本方法替代 `verify_token`。
222    ///
223    /// # 参数
224    ///
225    /// - `token`: 待验证的 Token 字符串
226    ///
227    /// # 返回
228    ///
229    /// - `Ok(TokenClaims)`: 验证通过且未被撤销
230    /// - `Err(BaseError::TokenVerifyFailed)`: 签名/过期/声明校验失败
231    /// - `Err(BaseError::TokenRevoked)`: Token 已被撤销(命中黑名单或早于用户水位线)
232    /// - `Err(BaseError::RedisOperationFailed)`: 黑名单查询失败
233    pub async fn verify_token_checked(&self, token: &str) -> Result<TokenClaims, BaseError> {
234        let claims = self.verify_token(token)?;
235
236        // PERF-2: 将两次 Redis 读(EXISTS + GET)合并为一条 pipeline,2 RTT → 1 RTT。
237        // 对已黑名单 token 会失去短路(不再提前返回),但撤销场景罕见,可接受。
238        let mut pipeline = self.revocation_cache()?.pipeline();
239        pipeline
240            .exists(blacklist_key(&claims.jti))
241            .get(subject_min_iat_key(&claims.sub));
242        let results = pipeline
243            .execute()
244            .await
245            .map_err(BaseError::RedisOperationFailed)?;
246
247        // results[0]: EXISTS → Int(0) 或 Int(1)
248        let revoked_count = results[0].as_i64().unwrap_or(0);
249        if revoked_count > 0 {
250            return Err(BaseError::TokenRevoked);
251        }
252
253        // results[1]: GET → Nil(无水位线)或 String(水位线时间戳)
254        if let Some(raw) = results[1].as_str() {
255            if let Ok(min_iat) = raw.parse::<u64>() {
256                if iat_revoked_by_watermark(claims.iat, min_iat) {
257                    return Err(BaseError::TokenRevoked);
258                }
259            } else {
260                tracing::warn!(sub = %claims.sub, raw, "水位线解析失败,视为无水位线");
261            }
262        }
263
264        Ok(claims)
265    }
266}
267
268#[cfg(test)]
269mod tests {
270    use super::*;
271
272    #[test]
273    fn test_blacklist_key_format() {
274        assert_eq!(blacklist_key("abc-123"), "token:blacklist:abc-123");
275    }
276
277    #[test]
278    fn test_subject_min_iat_key_format() {
279        // sub 经 hex 编码,避免特殊字符导致 key 歧义
280        assert_eq!(
281            subject_min_iat_key("user_42"),
282            "token:user:757365725f3432:min_iat"
283        );
284    }
285
286    #[test]
287    fn test_subject_min_iat_key_colon_safe() {
288        // sub 含冒号时 hex 编码后不再产生歧义
289        let key = subject_min_iat_key("user:admin");
290        assert_eq!(key, "token:user:757365723a61646d696e:min_iat");
291        // 确保 key 中不会出现未转义的冒号(除固定分隔符外)
292        let after_prefix = key.strip_prefix("token:user:").unwrap();
293        let (hex_part, rest) = after_prefix.split_once(':').unwrap();
294        assert_eq!(rest, "min_iat");
295        // hex 部分只含 0-9a-f
296        assert!(hex_part.chars().all(|c| c.is_ascii_hexdigit()));
297    }
298
299    /// NEW-6:同秒签发(iat == min_iat)必须被撤销,杜绝 1 秒旁路窗口。
300    #[test]
301    fn test_iat_revoked_by_watermark_same_second() {
302        // 早于水位线:撤销
303        assert!(iat_revoked_by_watermark(100, 200));
304        // 同秒签发:必须撤销(含等号,这是修复点)
305        assert!(iat_revoked_by_watermark(200, 200));
306        // 晚于水位线:放行
307        assert!(!iat_revoked_by_watermark(201, 200));
308    }
309}