Skip to main content

TokenManager

Struct TokenManager 

Source
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

Source

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 字节的密钥应构建成功");
Source

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 最大有效期,再由运维显式移除。

Source

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,
)?;
Source

pub fn generate_access_token( &self, subject: &str, custom_claims: Value, ) -> Result<String, BaseError>

生成 Access Token

§参数
  • subject: 主题(通常是用户 ID)
  • custom_claims: 自定义声明(JSON 格式)
§返回
  • Ok(String): Token 字符串
  • Err(BaseError): 生成失败
§示例
ⓘ
let token = manager.generate_access_token(
    "user_123",
    serde_json::json!({
        "role": "admin",
        "permissions": ["read", "write"]
    }),
)?;
Source

pub fn generate_refresh_token(&self, subject: &str) -> Result<String, BaseError>

生成 Refresh Token

§参数
  • subject: 主题(通常是用户 ID)
§返回
  • Ok(String): Token 字符串
  • Err(BaseError): 生成失败
§示例
ⓘ
let refresh_token = manager.generate_refresh_token("user_123")?;
Source

pub fn generate_refresh_token_with_claims( &self, subject: &str, custom_claims: Value, ) -> Result<String, BaseError>

生成携带自定义声明的 Refresh Token。

Refresh Token 通常只应携带版本号等刷新流程必需的最小声明,不应复制 Access Token 中的角色、权限等高频变化信息。

Source

pub fn generate_token_pair( &self, subject: &str, custom_claims: Value, ) -> Result<(String, String), BaseError>

生成 Token 对(Access Token + Refresh Token)

§参数
  • subject: 主题(通常是用户 ID)
  • custom_claims: 自定义声明(JSON 格式)
§返回
  • Ok((access_token, refresh_token)): Token 对
  • Err(BaseError): 生成失败
§示例
ⓘ
let (access_token, refresh_token) = manager.generate_token_pair(
    "user_123",
    serde_json::json!({"role": "admin"}),
)?;
Source

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 声明最小化。

Source

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);
Source

pub fn parse_token_unsafe(&self, token: &str) -> Result<TokenClaims, BaseError>

👎Deprecated since 0.1.0:

此方法跳过所有 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);
Source

pub fn is_token_expiring_soon( &self, token: &str, threshold_secs: u64, ) -> Result<bool, BaseError>

检查 Token 是否即将过期

§参数
  • token: Token 字符串
  • threshold_secs: 阈值(秒),如果剩余时间少于此值则返回 true
§返回
  • Ok(bool): 是否即将过期
  • Err(BaseError): 检查失败
§示例
ⓘ
// 检查 Token 是否在 5 分钟内过期
if manager.is_token_expiring_soon(&token, 300)? {
    println!("Token 即将过期,需要刷新");
}
Source

pub 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。

使用 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 Token
  • Err(BaseError): 刷新失败
§示例
ⓘ
// 推荐:轮换刷新,旧 Refresh Token 立即失效,重放触发全账号撤销
let (access_token, refresh_token) = manager
    .rotate_refresh_token(&old_refresh_token, serde_json::json!({"role": "admin"}))
    .await?;
Source

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。

执行流程:

  1. TokenManager::verify_token_checked 验证旧 Refresh Token 且确认未被撤销;
  2. 校验其 token_type 必须为 "refresh";
  3. TokenManager::try_revoke_once 原子写入黑名单(SET NX EX); 若返回 false(竞态中落败)则触发复用检测并返回 BaseError::TokenRevoked;
  4. 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 Token
  • Err(BaseError::RedisOperationFailed): 原子写入黑名单失败
§依赖

本方法依赖基于 Redis 的 Token 黑名单(见 TokenManager::verify_token_checked 与 TokenManager::try_revoke_once),调用前需由 ToolsBuilder 注入 Redis 撤销存储。

Source

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 的自定义声明。

Source

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:黑名单查询 + 水位线查询)。

本方法仅执行:

  1. 校验 token_type 必须为 "refresh";
  2. 原子拉黑旧 Refresh Token(SET NX EX);
  3. 以原 sub 与新自定义声明签发新 Token 对。
§参数
§返回
  • Ok((access_token, refresh_token)): 新签发的 Token 对
  • Err(BaseError::TokenTypeInvalid): old_claims.token_type 不是 "refresh"
  • Err(BaseError::TokenRevoked): 旧 Token 已被撤销(竞态中落败)
  • Err(BaseError::RedisOperationFailed): 原子写入黑名单失败
Source

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

Source

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): 写黑名单失败
Source

pub async fn revoke_claims(&self, claims: &TokenClaims) -> Result<(), BaseError>

按已验证的 TokenClaims 撤销 Token。

当调用方手头已有验证过的 claims 时,可避免重复验证。

§参数
  • claims: 已通过验证的 Token 声明
Source

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)。

Source

pub async fn is_revoked(&self, jti: &str) -> Result<bool, BaseError>

查询某个 jti 是否已被撤销。

§参数
  • jti: Token 的唯一标识
§返回
  • Ok(true): 已撤销(命中黑名单)
  • Ok(false): 未撤销
  • Err(BaseError::RedisOperationFailed): Redis 查询失败
Source

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 门禁机械强制执行):

  1. src/addon/access/grants/actions/revoke_permission.rs — 单条撤销路径, 事务提交后即时收敛 Redis;
  2. 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 撤销存储。

Source

pub async fn subject_min_iat(&self, sub: &str) -> Result<Option<u64>, BaseError>

查询某用户的“最小有效签发时间“水位线(若不存在返回 None)。

§参数
  • sub: 用户主题标识
§返回
  • Ok(Some(ts)): 该用户已被批量撤销,水位线时间戳为 ts
  • Ok(None): 该用户无批量撤销记录
  • Err(BaseError::RedisOperationFailed): Redis 查询失败
  • Err(BaseError::TokenRevocationStateInvalid): 水位线值损坏
Source

pub async fn verify_token_checked( &self, token: &str, expected: TokenType, ) -> Result<TokenClaims, BaseError>

验证 Token,并额外检查黑名单。

在 TokenManager::verify_token 的全部校验之上,再做两层撤销检查:

  1. 查 jti 黑名单(单 Token 撤销 / 登出);
  2. 查该用户的 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§

Source§

impl Debug for TokenManager

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts 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 more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts 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
Source§

impl<T> PolicyExt for T
where T: ?Sized,

Source§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow only if self and other return Action::Follow. Read more
Source§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow if either self or other returns Action::Follow. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more