Skip to main content

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;