yang_base/action/auth/refresh.rs
1//! 刷新 Action 与刷新声明解析:用 Refresh Token 旋转换取新的 Token 对。
2
3use super::audit::{AuthAuditEvent, AuthAuditHook, TracingAuditHook};
4use super::dto::{RefreshInput, TokenPairClaims, TokenPairResponse};
5use crate::action::{ActionContext, TypedHandler};
6use crate::error::BaseError;
7use crate::token::TokenClaims;
8use async_trait::async_trait;
9use yang_base_derive::Action;
10
11// ──────────────────────────────────────────────────────────────────────────────
12// RefreshAction
13// ──────────────────────────────────────────────────────────────────────────────
14
15/// 刷新声明解析器:决定刷新出的新 Access Token 携带哪些自定义声明。
16///
17/// 刷新时若不重新解析声明,新 Access Token 会丢失角色/权限等自定义声明。业务方
18/// 实现本 trait,从已验证的 Refresh Token 主体(`sub`)出发(通常回查数据库取最新
19/// 角色),返回要写入新 Access Token 的自定义声明。
20#[async_trait]
21pub trait RefreshClaimsResolver: Send + Sync + 'static {
22 /// 解析新 Access Token 的自定义声明。
23 ///
24 /// # 参数
25 ///
26 /// - `ctx`: 动作上下文(可借此访问数据库等)
27 /// - `sub`: 已验证的 Refresh Token 主体(用户标识)
28 ///
29 /// # 返回
30 ///
31 /// - `Ok(Value)`: 写入新 Access Token 的自定义声明(`Value::Null` 表示无)
32 /// - `Err(BaseError)`: 解析失败(如用户已禁用)
33 async fn resolve(&self, ctx: &ActionContext, sub: &str)
34 -> Result<serde_json::Value, BaseError>;
35
36 /// 从同一次业务快照解析新 Access/Refresh Token 的声明。
37 ///
38 /// 默认只复用 [`RefreshClaimsResolver::resolve`] 生成 Access 声明,Refresh
39 /// 声明保持为空,因此既有实现无需修改。需要成对版本声明的实现可覆盖本方法,
40 /// 保证只执行一次数据库快照查询。
41 async fn resolve_pair(
42 &self,
43 ctx: &ActionContext,
44 sub: &str,
45 ) -> Result<TokenPairClaims, BaseError> {
46 Ok(TokenPairClaims::new(self.resolve(ctx, sub).await?))
47 }
48
49 /// 基于已通过核心签名、时效、类型和撤销校验的旧 Refresh Token 完整声明,解析
50 /// 新 Token 对的声明。
51 ///
52 /// 应用可覆盖本方法校验 `credential_version` 等 Refresh 专属事实,并从同一次数据库
53 /// 快照生成新 Access/Refresh 声明。默认仅把可信 `sub` 转交给
54 /// [`RefreshClaimsResolver::resolve_pair`],因此既有实现保持兼容。
55 ///
56 /// 本 hook 在旧 JTI 被原子消费前执行;校验失败不会消耗仍然有效的 Refresh Token。
57 async fn resolve_pair_from_claims(
58 &self,
59 ctx: &ActionContext,
60 claims: &TokenClaims,
61 ) -> Result<TokenPairClaims, BaseError> {
62 self.resolve_pair(ctx, &claims.sub).await
63 }
64}
65
66/// 默认刷新声明解析器:不附加任何自定义声明(零配置可用)。
67#[derive(Debug, Clone, Default)]
68pub struct DefaultRefreshClaims;
69
70#[async_trait]
71impl RefreshClaimsResolver for DefaultRefreshClaims {
72 async fn resolve(
73 &self,
74 _ctx: &ActionContext,
75 _sub: &str,
76 ) -> Result<serde_json::Value, BaseError> {
77 Ok(serde_json::Value::Null)
78 }
79}
80
81/// 刷新 Action:用 Refresh Token 换取新的 Access Token。公开。
82///
83/// 仅调用一次 [`TokenManager::verify_token_checked`](crate::token::TokenManager::verify_token_checked)
84/// 完成验证(签名 + 过期 + 黑名单),随后将已验证的 [`TokenClaims`] 直接传给
85/// [`TokenManager::rotate_refresh_token_from_claims`](crate::token::TokenManager::rotate_refresh_token_from_claims),跳过内部二次验证,
86/// 节省 2 次 Redis RTT。自定义声明由注入的 [`RefreshClaimsResolver`] 决定,
87/// 默认 [`DefaultRefreshClaims`] 不附加声明,零配置即可使用。
88///
89/// # 示例
90///
91/// ```rust,ignore
92/// use yang_base::action::auth::{RefreshAction, RefreshClaimsResolver};
93/// use yang_base::action::ActionContext;
94/// use yang_base::error::BaseError;
95/// use async_trait::async_trait;
96///
97/// // 零配置:默认 resolver
98/// let refresh = RefreshAction::default();
99///
100/// // 自定义:刷新时回查用户最新角色
101/// struct RoleResolver;
102/// #[async_trait]
103/// impl RefreshClaimsResolver for RoleResolver {
104/// async fn resolve(&self, _ctx: &ActionContext, sub: &str)
105/// -> Result<serde_json::Value, BaseError>
106/// {
107/// Ok(serde_json::json!({ "role": "user", "sub": sub }))
108/// }
109/// }
110/// let refresh = RefreshAction::new(RoleResolver);
111/// ```
112#[derive(Action, Default)]
113#[action(
114 name = "refresh",
115 display_name = "刷新 Token",
116 description = "用 Refresh Token 换取新的 Access Token",
117 public
118)]
119pub struct RefreshAction<
120 R: RefreshClaimsResolver = DefaultRefreshClaims,
121 A: AuthAuditHook = TracingAuditHook,
122> {
123 resolver: R,
124 audit: A,
125}
126
127impl<R: RefreshClaimsResolver> RefreshAction<R, TracingAuditHook> {
128 /// 用业务声明解析器创建 RefreshAction(默认 tracing 审计钩子)。
129 pub fn new(resolver: R) -> Self {
130 Self {
131 resolver,
132 audit: TracingAuditHook,
133 }
134 }
135}
136
137impl<R: RefreshClaimsResolver, A: AuthAuditHook> RefreshAction<R, A> {
138 /// 用业务声明解析器 + 自定义审计钩子创建 RefreshAction。
139 pub fn with_audit(resolver: R, audit: A) -> Self {
140 Self { resolver, audit }
141 }
142}
143
144/// Refresh Token 旋转刷新 Action。
145///
146/// 此方法使用 **Token Rotation** 模式:每次刷新时同时撤销旧 Refresh Token 并签发
147/// 新的 Token 对(Access Token + Refresh Token),防止 Refresh Token 被盗后的
148/// 无限刷新攻击。
149///
150/// # 破坏性变更(BREAKING CHANGE)
151///
152/// 原 `RefreshAction` 仅返回 [`AccessTokenResponse`](super::AccessTokenResponse)(只含新的 Access Token)。
153/// 现改为返回 [`TokenPairResponse`](super::TokenPairResponse)(同时包含新的 Access Token 与新的 Refresh Token)。
154/// 请更新客户端以替换保存的 Refresh Token,否则旧 Refresh Token 将无法用于后续刷新。
155#[async_trait]
156impl<R: RefreshClaimsResolver, A: AuthAuditHook> TypedHandler for RefreshAction<R, A> {
157 type Input = RefreshInput;
158 type Output = TokenPairResponse;
159
160 async fn handle(
161 &self,
162 ctx: ActionContext,
163 input: RefreshInput,
164 ) -> Result<TokenPairResponse, BaseError> {
165 let request_id = ctx.request_id.to_string();
166 let manager = ctx.tools().token()?;
167
168 let run = async {
169 // 先验证旧 Token 以获取 subject(供业务解析器确定新声明)
170 let claims = manager.verify_token_checked(&input.refresh_token).await?;
171 if claims.token_type != crate::token::TokenType::Refresh {
172 return Err(BaseError::TokenTypeInvalid(
173 "期望 refresh token".to_string(),
174 ));
175 }
176 // 先由业务解析器校验旧 Refresh 完整声明并决定新 Token 声明;失败不消费旧 JTI
177 let custom_claims = self
178 .resolver
179 .resolve_pair_from_claims(&ctx, &claims)
180 .await?;
181 // 使用已验证的 claims 直接轮换,跳过 rotate_refresh_token 内部二次验证
182 let (access_token, refresh_token) = manager
183 .rotate_refresh_token_from_claims_with_refresh_claims(
184 &claims,
185 custom_claims.access,
186 custom_claims.refresh,
187 )
188 .await?;
189 Ok::<_, BaseError>((access_token, refresh_token, claims.sub))
190 };
191
192 match run.await {
193 Ok((access_token, refresh_token, sub)) => {
194 self.audit
195 .on_success(AuthAuditEvent {
196 request_id,
197 action: "refresh",
198 subject: Some(sub),
199 error_code: None,
200 })
201 .await;
202 Ok(TokenPairResponse {
203 access_token,
204 refresh_token,
205 })
206 }
207 Err(e) => {
208 self.audit
209 .on_failure(AuthAuditEvent {
210 request_id,
211 action: "refresh",
212 subject: None,
213 error_code: Some(e.code_str()),
214 })
215 .await;
216 Err(e)
217 }
218 }
219 }
220}