yang_base/token/mod.rs
1//! JWT Token 管理模块
2//!
3//! 提供 Token 生成、验证、解析和刷新机制。
4//!
5//! # 主要组件
6//!
7//! - `TokenManager`:Token 管理器
8//! - `TokenClaims`:Token 声明
9//! - `TokenConfig`:Token 配置
10//!
11//! # 示例
12//!
13//! ```rust,ignore
14//! use yang_base::token::{TokenManager, TokenClaims};
15//! use jsonwebtoken::Algorithm;
16//!
17//! // 创建 Token 管理器(对称加密)
18//! let manager = TokenManager::new_symmetric(
19//! "your_secret_key",
20//! Algorithm::HS256,
21//! "issuer".to_string(),
22//! "audience".to_string(),
23//! 3600,
24//! 86400,
25//! );
26//!
27//! // 生成 Access Token
28//! let token = manager.generate_access_token(
29//! "user_id_123",
30//! serde_json::json!({"role": "admin"}),
31//! )?;
32//!
33//! // 验证 Token
34//! let claims = manager.verify_token(&token)?;
35//! println!("用户 ID: {}", claims.sub);
36//! ```
37
38mod manager;
39mod revocation;
40
41pub use manager::TokenManager;
42
43use serde::{Deserialize, Serialize};
44
45/// Token 类型枚举
46///
47/// 封闭集合,仅允许 `Access` 与 `Refresh` 两种值。
48/// 序列化为小写字符串 `"access"` / `"refresh"`,与旧版 `String` 字段的 JSON 格式完全兼容。
49#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
50#[serde(rename_all = "lowercase")]
51#[non_exhaustive]
52pub enum TokenType {
53 /// 访问令牌,用于 API 访问
54 Access,
55 /// 刷新令牌,用于获取新的访问令牌
56 Refresh,
57}
58
59/// Token 声明
60///
61/// JWT Token 的标准声明和自定义声明。
62///
63/// # 标准声明字段
64///
65/// - `iss`:签发者(Issuer)
66/// - `sub`:主题(Subject),通常是用户 ID
67/// - `aud`:受众(Audience)
68/// - `exp`:过期时间(Expiration Time),Unix 时间戳
69/// - `nbf`:生效时间(Not Before),Unix 时间戳
70/// - `iat`:签发时间(Issued At),Unix 时间戳
71/// - `jti`:JWT ID,唯一标识符
72///
73/// # 自定义字段
74///
75/// - `token_type`:Token 类型(access 或 refresh)
76/// - `custom`:自定义声明,使用 JSON 格式存储任意数据
77///
78/// # 示例
79///
80/// ```rust
81/// use yang_base::token::{TokenClaims, TokenType};
82/// use serde_json::json;
83///
84/// let claims = TokenClaims::new(
85/// "yang-base",
86/// "user_123",
87/// "yang-app",
88/// 1234567890,
89/// 1234567800,
90/// 1234567800,
91/// "unique-token-id",
92/// TokenType::Access,
93/// json!({
94/// "role": "admin",
95/// "permissions": ["read", "write"]
96/// }),
97/// );
98/// ```
99/// 标注 `#[non_exhaustive]`:未来新增字段不构成破坏性变更。
100/// 请使用 [`TokenClaims::new`] 构造。
101#[derive(Clone, Serialize, Deserialize)]
102#[non_exhaustive]
103pub struct TokenClaims {
104 /// 签发者(Issuer)
105 ///
106 /// 标识 Token 的签发方,用于验证 Token 来源
107 pub iss: String,
108
109 /// 主题(Subject)
110 ///
111 /// 通常是用户 ID 或其他唯一标识符
112 pub sub: String,
113
114 /// 受众(Audience)
115 ///
116 /// 标识 Token 的目标接收方
117 pub aud: String,
118
119 /// 过期时间(Expiration Time)
120 ///
121 /// Unix 时间戳,表示 Token 的过期时间
122 pub exp: u64,
123
124 /// 生效时间(Not Before)
125 ///
126 /// Unix 时间戳,表示 Token 在此时间之前不可用
127 pub nbf: u64,
128
129 /// 签发时间(Issued At)
130 ///
131 /// Unix 时间戳,表示 Token 的签发时间
132 pub iat: u64,
133
134 /// JWT ID
135 ///
136 /// Token 的唯一标识符,用于防止重放攻击
137 pub jti: String,
138
139 /// Token 类型
140 ///
141 /// 可选值:
142 /// - `TokenType::Access`:访问令牌,用于 API 访问
143 /// - `TokenType::Refresh`:刷新令牌,用于获取新的访问令牌
144 pub token_type: TokenType,
145
146 /// 自定义声明
147 ///
148 /// 使用 JSON 格式存储任意自定义数据,例如用户角色、权限等。
149 /// 使用 `#[serde(flatten)]` 将自定义字段展平到 Token 的顶层。
150 ///
151 /// # 示例
152 ///
153 /// ```json
154 /// {
155 /// "role": "admin",
156 /// "permissions": ["read", "write", "delete"],
157 /// "org_id": "org_123"
158 /// }
159 /// ```
160 #[serde(flatten)]
161 pub custom: serde_json::Value,
162}
163
164// NEW-38: 手写 Debug 脱敏,防止 Token 字段(iss/sub/jti/自定义声明)明文泄漏
165impl core::fmt::Debug for TokenClaims {
166 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
167 f.debug_struct("TokenClaims")
168 .field("iss", &self.iss)
169 .field("sub", &self.sub)
170 .field("aud", &self.aud)
171 .field("exp", &self.exp)
172 .field("nbf", &self.nbf)
173 .field("iat", &self.iat)
174 .field("jti", &"***")
175 .field("token_type", &self.token_type)
176 .field("custom", &"***")
177 .finish()
178 }
179}
180
181impl TokenClaims {
182 /// 构造 `TokenClaims`(`#[non_exhaustive]` 后的唯一公开构造入口)。
183 #[allow(clippy::too_many_arguments)]
184 pub fn new(
185 iss: impl Into<String>,
186 sub: impl Into<String>,
187 aud: impl Into<String>,
188 exp: u64,
189 nbf: u64,
190 iat: u64,
191 jti: impl Into<String>,
192 token_type: TokenType,
193 custom: serde_json::Value,
194 ) -> Self {
195 Self {
196 iss: iss.into(),
197 sub: sub.into(),
198 aud: aud.into(),
199 exp,
200 nbf,
201 iat,
202 jti: jti.into(),
203 token_type,
204 custom,
205 }
206 }
207}
208
209#[cfg(test)]
210#[path = "__tests__/claims_test.rs"]
211mod claims_test;
212
213#[cfg(test)]
214#[path = "__tests__/manager_test.rs"]
215mod manager_test;