pub struct TokenManager { /* private fields */ }Expand description
Token 管理器
提供 JWT Token 的生成、验证、解析和刷新功能。
§支持的算法
- 对称加密:HS256、HS384、HS512
- 非对称加密:RS256、RS384、RS512
§示例
use yang_base::token::TokenManager;
use jsonwebtoken::Algorithm;
// 创建对称加密的 Token 管理器
let manager = TokenManager::new_symmetric(
"your_secret_key",
Algorithm::HS256,
"issuer".to_string(),
"audience".to_string(),
3600, // Access Token 有效期 1 小时
86400, // Refresh Token 有效期 1 天
);
// 生成 Access Token
let token = manager.generate_access_token(
"user_123",
serde_json::json!({"role": "admin"}),
)?;
// 验证 Token
let claims = manager.verify_token(&token)?;
println!("用户 ID: {}", claims.sub);Implementations§
Source§impl TokenManager
impl TokenManager
Sourcepub fn new_symmetric(
secret: &str,
algorithm: Algorithm,
issuer: String,
audience: String,
access_token_expiry: u64,
refresh_token_expiry: u64,
) -> Result<Self, BaseError>
pub fn new_symmetric( secret: &str, algorithm: Algorithm, issuer: String, audience: String, access_token_expiry: u64, refresh_token_expiry: u64, ) -> Result<Self, BaseError>
创建新的 Token 管理器(对称加密)
§参数
secret: 密钥字符串algorithm: 加密算法(HS256、HS384、HS512)issuer: 签发者标识audience: 受众标识access_token_expiry: Access Token 有效期(秒)refresh_token_expiry: Refresh Token 有效期(秒)
§返回
Ok(TokenManager): Token 管理器实例Err(BaseError::TokenKeyInvalid): 密钥少于 32 字节(AUTH-9),或 算法不是 HS256/HS384/HS512(AUTH-8;非对称算法请使用TokenManager::new_asymmetric)
§示例
use yang_base::token::TokenManager;
use jsonwebtoken::Algorithm;
let manager = TokenManager::new_symmetric(
"my_secret_key_0123456789abcdef0123",
Algorithm::HS256,
"my_app".to_string(),
"my_users".to_string(),
3600,
86400,
)
.expect("不少于 32 字节的密钥应构建成功");Sourcepub fn new_symmetric_keyring(
active_key_id: String,
active_secret: &str,
retiring_keys: Vec<(String, String)>,
algorithm: Algorithm,
issuer: String,
audience: String,
access_token_expiry: u64,
refresh_token_expiry: u64,
) -> Result<Self, BaseError>
pub fn new_symmetric_keyring( active_key_id: String, active_secret: &str, retiring_keys: Vec<(String, String)>, algorithm: Algorithm, issuer: String, audience: String, access_token_expiry: u64, refresh_token_expiry: u64, ) -> Result<Self, BaseError>
创建带稳定 kid 的对称 Token keyring。
新 Token 只由 active key 签发;验证时只按 Header 中的 kid 精确选择
active 或 retiring key。keyring 模式不接受缺失/未知 kid,避免回退到
“逐把试签名”的模糊验证链。retiring key 应至少保留一个 Refresh Token
最大有效期,再由运维显式移除。
Sourcepub fn new_asymmetric(
private_key: &str,
public_key: &str,
algorithm: Algorithm,
issuer: String,
audience: String,
access_token_expiry: u64,
refresh_token_expiry: u64,
) -> Result<Self, BaseError>
pub fn new_asymmetric( private_key: &str, public_key: &str, algorithm: Algorithm, issuer: String, audience: String, access_token_expiry: u64, refresh_token_expiry: u64, ) -> Result<Self, BaseError>
创建新的 Token 管理器(非对称加密)
§参数
private_key: 私钥(PEM 格式)public_key: 公钥(PEM 格式)algorithm: 加密算法(RS256、RS384、RS512)issuer: 签发者标识audience: 受众标识access_token_expiry: Access Token 有效期(秒)refresh_token_expiry: Refresh Token 有效期(秒)
§返回
Ok(TokenManager): Token 管理器实例Err(BaseError): 密钥格式无效
§示例
use yang_base::token::TokenManager;
use jsonwebtoken::Algorithm;
let private_key = "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----";
let public_key = "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----";
let manager = TokenManager::new_asymmetric(
private_key,
public_key,
Algorithm::RS256,
"my_app".to_string(),
"my_users".to_string(),
3600,
86400,
)?;Sourcepub fn generate_access_token(
&self,
subject: &str,
custom_claims: Value,
) -> Result<String, BaseError>
pub fn generate_access_token( &self, subject: &str, custom_claims: Value, ) -> Result<String, BaseError>
Sourcepub fn generate_refresh_token_with_claims(
&self,
subject: &str,
custom_claims: Value,
) -> Result<String, BaseError>
pub fn generate_refresh_token_with_claims( &self, subject: &str, custom_claims: Value, ) -> Result<String, BaseError>
生成携带自定义声明的 Refresh Token。
Refresh Token 通常只应携带版本号等刷新流程必需的最小声明,不应复制 Access Token 中的角色、权限等高频变化信息。
Sourcepub fn generate_token_pair(
&self,
subject: &str,
custom_claims: Value,
) -> Result<(String, String), BaseError>
pub fn generate_token_pair( &self, subject: &str, custom_claims: Value, ) -> Result<(String, String), BaseError>
Sourcepub fn generate_token_pair_with_refresh_claims(
&self,
subject: &str,
access_claims: Value,
refresh_claims: Value,
) -> Result<(String, String), BaseError>
pub fn generate_token_pair_with_refresh_claims( &self, subject: &str, access_claims: Value, refresh_claims: Value, ) -> Result<(String, String), BaseError>
生成分别携带自定义声明的 Token 对。
access_claims 与 refresh_claims 必须由同一次业务授权快照派生,避免
同一 Token 对内部出现版本撕裂。调用方应保持 Refresh 声明最小化。
Sourcepub fn verify_token(&self, token: &str) -> Result<TokenClaims, BaseError>
pub fn verify_token(&self, token: &str) -> Result<TokenClaims, BaseError>
验证 Token
验证 Token 的签名、过期时间、签发者和受众。
§参数
token: Token 字符串
§返回
Ok(TokenClaims): Token 声明Err(BaseError::TokenExpired): Token 已过期Err(BaseError::TokenVerifyFailed): 签名或声明校验失败Err(BaseError::TokenParseFailed): Token 解析失败
错误分类由 From<jsonwebtoken::errors::Error> 自动分流:
ExpiredSignature → TokenExpired,InvalidToken/InvalidSignature → TokenVerifyFailed,
其他 → TokenParseFailed。
§示例
let claims = manager.verify_token(&token)?;
println!("用户 ID: {}", claims.sub);
println!("Token 类型: {}", claims.token_type);Sourcepub fn parse_token_unsafe(&self, token: &str) -> Result<TokenClaims, BaseError>
👎Deprecated since 0.1.0: 此方法跳过所有 JWT 安全验证(签名/过期/签发者),仅可用于调试日志和单元测试。鉴权路径必须使用 verify_token 或 verify_token_checked。
pub fn parse_token_unsafe(&self, token: &str) -> Result<TokenClaims, BaseError>
此方法跳过所有 JWT 安全验证(签名/过期/签发者),仅可用于调试日志和单元测试。鉴权路径必须使用 verify_token 或 verify_token_checked。
解析 Token(不验证签名)
⚠️ 安全警告:此方法不验证签名、不检查过期、不校验签发者/受众。 攻击者可伪造任意 JWT。严禁在鉴权/授权决策中使用此方法的返回值。
用于调试或获取 Token 信息而不验证其有效性。
§参数
token: Token 字符串
§返回
Ok(TokenClaims): Token 声明Err(BaseError): 解析失败
§Safety
此方法绝对不能用于鉴权决策。
该方法跳过签名验证、过期时间检查及所有标准声明校验, 任何人均可伪造 Token 内容并通过此方法解析。 仅允许在以下场景使用:
- 调试与日志记录(打印 Token 内容)
- 从已过期 Token 中提取用户标识以便刷新
- 单元测试中检查 Token 结构
在任何涉及权限判断、身份认证的代码路径中,
必须使用 TokenManager::verify_token 代替本方法。
§警告
此方法不验证签名和过期时间,仅用于调试目的。 不要在生产环境中使用此方法进行身份验证。
§示例
let claims = manager.parse_token_unsafe(&token)?;
println!("Token 内容: {:?}", claims);Sourcepub fn is_token_expiring_soon(
&self,
token: &str,
threshold_secs: u64,
) -> Result<bool, BaseError>
pub fn is_token_expiring_soon( &self, token: &str, threshold_secs: u64, ) -> Result<bool, BaseError>
Sourcepub async fn refresh_access_token(
&self,
refresh_token: &str,
custom_claims: Value,
) -> Result<String, BaseError>
👎Deprecated since 0.1.0: 此方法不轮换 Refresh Token(旧 token 在过期前始终可用,且不触发复用检测/家族撤销)。刷新请使用 RefreshAction,或 TokenManager::rotate_refresh_token / rotate_refresh_token_from_claims。
pub async fn refresh_access_token( &self, refresh_token: &str, custom_claims: Value, ) -> Result<String, BaseError>
此方法不轮换 Refresh Token(旧 token 在过期前始终可用,且不触发复用检测/家族撤销)。刷新请使用 RefreshAction,或 TokenManager::rotate_refresh_token / rotate_refresh_token_from_claims。
使用 Refresh Token 刷新 Access Token
此方法会检查 Redis 黑名单,已撤销的 Refresh Token 将被拒绝。
§安全权衡
本方法不轮换 Refresh Token(旧 token 在过期前始终可用,且不触发复用检测/
家族撤销),会重新引入轮换刷新要堵的重放窗口。刷新请使用 [RefreshAction] 或
TokenManager::rotate_refresh_token / [rotate_refresh_token_from_claims]。
§参数
refresh_token: Refresh Token 字符串custom_claims: 新的自定义声明
§返回
Ok(String): 新的 Access TokenErr(BaseError): 刷新失败
§示例
// 推荐:轮换刷新,旧 Refresh Token 立即失效,重放触发全账号撤销
let (access_token, refresh_token) = manager
.rotate_refresh_token(&old_refresh_token, serde_json::json!({"role": "admin"}))
.await?;Sourcepub async fn rotate_refresh_token(
&self,
old_refresh: &str,
custom_claims: Value,
) -> Result<(String, String), BaseError>
pub async fn rotate_refresh_token( &self, old_refresh: &str, custom_claims: Value, ) -> Result<(String, String), BaseError>
轮换 Refresh Token(刷新令牌轮换 / Refresh Token Rotation,token-1)。
每次刷新都签发全新的 Token 对,并立刻把旧 Refresh Token 原子拉黑, 使其无法再次使用。这能限制刷新令牌泄露的影响面:一旦旧令牌被重放, 因已进入黑名单而验证失败。
注:原子拉黑使用 [SET key val NX EX ttl],竞态安全——
并发请求中仅第一个能成功写入黑名单,后续返回 BaseError::TokenRevoked。
执行流程:
TokenManager::verify_token_checked验证旧 Refresh Token 且确认未被撤销;- 校验其
token_type必须为"refresh"; TokenManager::try_revoke_once原子写入黑名单(SET NX EX); 若返回 false(竞态中落败)则触发复用检测并返回BaseError::TokenRevoked;TokenManager::generate_token_pair以原sub与新的自定义声明签发新 Token 对。
§复用检测语义
旧 Refresh Token 被重放(SET NX 落败)视为泄露信号:撤销该用户全部
会话(写 subject 水位线)并拒绝本次轮换。注意水位线判定含等号
(iat <= min_iat,NEW-6):两个并发合法刷新同秒完成时,落败方触发的
家族撤销会使获胜方刚签发的新 Token 对一并失效。因此客户端必须串行化
刷新(单飞/去重),不得对同一 Refresh Token 并发发起多次轮换。
已过期的旧 Token 不算重放,直接返回 BaseError::TokenExpired,
不触发家族撤销。
§参数
old_refresh: 旧的 Refresh Token 字符串custom_claims: 新 Access Token 的自定义声明(JSON 格式)
§返回
Ok((access_token, refresh_token)): 新签发的 Token 对Err(BaseError::TokenVerifyFailed): 旧 Token 签名/声明校验失败Err(BaseError::TokenExpired): 旧 Token 已过期Err(BaseError::TokenRevoked): 旧 Token 已被撤销(含竞态中落败)Err(BaseError::TokenTypeInvalid): 传入的不是 Refresh TokenErr(BaseError::RedisOperationFailed): 原子写入黑名单失败
§依赖
本方法依赖基于 Redis 的 Token 黑名单(见 TokenManager::verify_token_checked
与 TokenManager::try_revoke_once),调用前需由 ToolsBuilder 注入 Redis 撤销存储。
Sourcepub async fn rotate_refresh_token_with_refresh_claims(
&self,
old_refresh: &str,
access_claims: Value,
refresh_claims: Value,
) -> Result<(String, String), BaseError>
pub async fn rotate_refresh_token_with_refresh_claims( &self, old_refresh: &str, access_claims: Value, refresh_claims: Value, ) -> Result<(String, String), BaseError>
轮换 Refresh Token,并分别设置新 Access/Refresh Token 的自定义声明。
Sourcepub async fn rotate_refresh_token_from_claims(
&self,
old_claims: &TokenClaims,
custom_claims: Value,
) -> Result<(String, String), BaseError>
pub async fn rotate_refresh_token_from_claims( &self, old_claims: &TokenClaims, custom_claims: Value, ) -> Result<(String, String), BaseError>
基于已验证 claims 轮换 Refresh Token(跳过内部二次验证)。
当调用方已在外部完成 TokenManager::verify_token_checked 并持有 TokenClaims 时,
使用本方法可避免重复验证(节省 2 次 Redis RTT:黑名单查询 + 水位线查询)。
本方法仅执行:
- 校验
token_type必须为"refresh"; - 原子拉黑旧 Refresh Token(
SET NX EX); - 以原
sub与新自定义声明签发新 Token 对。
§参数
old_claims: 已通过TokenManager::verify_token_checked验证的旧 Refresh Token 声明custom_claims: 新 Access Token 的自定义声明(JSON 格式)
§返回
Ok((access_token, refresh_token)): 新签发的 Token 对Err(BaseError::TokenTypeInvalid):old_claims.token_type不是"refresh"Err(BaseError::TokenRevoked): 旧 Token 已被撤销(竞态中落败)Err(BaseError::RedisOperationFailed): 原子写入黑名单失败
Sourcepub async fn rotate_refresh_token_from_claims_with_refresh_claims(
&self,
old_claims: &TokenClaims,
access_claims: Value,
refresh_claims: Value,
) -> Result<(String, String), BaseError>
pub async fn rotate_refresh_token_from_claims_with_refresh_claims( &self, old_claims: &TokenClaims, access_claims: Value, refresh_claims: Value, ) -> Result<(String, String), BaseError>
基于已验证 claims 轮换 Refresh Token,并分别设置新 Token 对的自定义声明。
Source§impl TokenManager
impl TokenManager
Sourcepub async fn revoke_token(&self, token: &str) -> Result<(), BaseError>
pub async fn revoke_token(&self, token: &str) -> Result<(), BaseError>
撤销一个 Token(写入 Redis 黑名单)。
先验证 Token(确保 jti/exp 合法且签名有效),再按 exp - now 计算
剩余 TTL 写入黑名单。若 Token 已过期则无需撤销,直接返回 Ok(())。
§参数
token: 待撤销的 Token 字符串
§返回
Ok(()): 撤销成功,或 Token 已过期无需撤销Err(BaseError::TokenVerifyFailed): Token 签名/声明校验失败Err(BaseError::TokenExpired): Token 已过期(无需撤销,返回Ok(()))Err(BaseError::RedisOperationFailed): 写黑名单失败
Sourcepub async fn revoke_claims(&self, claims: &TokenClaims) -> Result<(), BaseError>
pub async fn revoke_claims(&self, claims: &TokenClaims) -> Result<(), BaseError>
Sourcepub async fn revoke_by_jti_with_ttl(
&self,
jti: &str,
ttl_seconds: u64,
) -> Result<(), BaseError>
pub async fn revoke_by_jti_with_ttl( &self, jti: &str, ttl_seconds: u64, ) -> Result<(), BaseError>
按 jti 直接写入撤销黑名单(按给定 TTL 保留)。
用于「踢出单个会话」等场景:调用方已知会话的当前 refresh jti, 但手上没有完整 claims(无法计算 exp)。TTL 由调用方提供, 应覆盖对应 refresh token 的剩余有效期(保守取完整 refresh TTL)。
Sourcepub async fn revoke_by_subject(&self, sub: &str) -> Result<(), BaseError>
pub async fn revoke_by_subject(&self, sub: &str) -> Result<(), BaseError>
按用户(subject)批量撤销该用户在此刻之前签发的所有 Token(token-3)。
在 Redis 中将 token:user:{hex(sub)}:min_iat 写为当前时间戳,作为该用户的
“最小有效签发时间“水位线。此后 TokenManager::verify_token_checked
会拒绝任何 iat 早于或等于该水位线的 Token,从而让此前签发的全部 Token 一次性失效。
适用于改密、强制下线等需要让某用户全部会话立即失效的场景。
水位线 TTL 取 Access / Refresh 有效期的较大值(TokenManager::revocation_watermark_ttl),
确保覆盖撤销前签发的最长寿命 Token,避免 key 过早过期导致已撤销会话「复活」。
§调用约束(架构门禁)
本方法设置 subject 水位线,立即杀死该用户全部已签发 Token(含 Access 与
Refresh),代价是该用户所有设备同时失效。禁止在批量撤销路径中使用——
批量操作必须走 Outbox + 版本传播,参考 batch_revoke_permissions.rs 头部注释。
yang-system 生产代码中仅允许以下两处调用(由 scripts/check_architecture.py
的 check_revoke_by_subject_placement 门禁机械强制执行):
src/addon/access/grants/actions/revoke_permission.rs— 单条撤销路径, 事务提交后即时收敛 Redis;src/addon/account/domain/context.rs—converge_revocation集中封装, 供 logout / disable_self / change_password 等账号安全事件共享。
新增调用点前请先确认语义等价于「让该用户全部会话立即失效」,而非仅仅 「撤销某条授权记录」;后者应走 Outbox 异步传播。
§参数
sub: 用户主题标识(即 Token 的sub)
§返回
Ok(()): 水位线写入成功Err(BaseError::RedisOperationFailed): Redis 写入失败
§依赖
依赖 ToolsBuilder 已为 TokenManager 连接 Redis 撤销存储。
Sourcepub async fn verify_token_checked(
&self,
token: &str,
expected: TokenType,
) -> Result<TokenClaims, BaseError>
pub async fn verify_token_checked( &self, token: &str, expected: TokenType, ) -> Result<TokenClaims, BaseError>
验证 Token,并额外检查黑名单。
在 TokenManager::verify_token 的全部校验之上,再做两层撤销检查:
- 查
jti黑名单(单 Token 撤销 / 登出); - 查该用户的
min_iat水位线(按用户批量撤销 / 改密、强制下线): 若存在水位线且 Token 的iat早于或等于它,则视为已撤销。
鉴权路径若需支持登出/撤销,应使用本方法替代 verify_token。
§参数
token: 待验证的 Token 字符串expected: 期望的 Token 类型(下沉校验:签名验证通过后、Redis 查询之前 比对token_type,鉴权路径不再依赖调用点自行比对)
§返回
Ok(TokenClaims): 验证通过且未被撤销Err(BaseError::TokenVerifyFailed): 签名/过期/声明校验失败Err(BaseError::TokenTypeInvalid): Token 类型与expected不匹配Err(BaseError::TokenRevoked): Token 已被撤销(命中黑名单或不晚于用户水位线)Err(BaseError::RedisOperationFailed): 黑名单查询失败Err(BaseError::TokenRevocationStateInvalid): 撤销查询结果或水位线损坏
§Cluster
Cluster 拓扑下两个 key 通常不同槽,无法用单条 Lua 原子读取;本方法会退化 为两次单 key 读(接受亚毫秒 TOCTOU 窗口),不会因 CROSSSLOT 让鉴权整体失败。
Trait Implementations§
Auto Trait Implementations§
impl !RefUnwindSafe for TokenManager
impl !UnwindSafe for TokenManager
impl Forget for TokenManager
impl Freeze for TokenManager
impl Move for TokenManager
impl Send for TokenManager
impl Sync for TokenManager
impl Unpin for TokenManager
impl UnsafeUnpin for TokenManager
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
Source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more