Skip to main content

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
171                .verify_token_checked(&input.refresh_token, crate::token::TokenType::Refresh)
172                .await?;
173            // 先由业务解析器校验旧 Refresh 完整声明并决定新 Token 声明;失败不消费旧 JTI
174            let custom_claims = self
175                .resolver
176                .resolve_pair_from_claims(&ctx, &claims)
177                .await?;
178            // 使用已验证的 claims 直接轮换,跳过 rotate_refresh_token 内部二次验证
179            let (access_token, refresh_token) = manager
180                .rotate_refresh_token_from_claims_with_refresh_claims(
181                    &claims,
182                    custom_claims.access,
183                    custom_claims.refresh,
184                )
185                .await?;
186            Ok::<_, BaseError>((access_token, refresh_token, claims.sub))
187        };
188
189        match run.await {
190            Ok((access_token, refresh_token, sub)) => {
191                self.audit
192                    .on_success(AuthAuditEvent {
193                        request_id,
194                        action: "refresh",
195                        subject: Some(sub),
196                        error_code: None,
197                    })
198                    .await;
199                Ok(TokenPairResponse {
200                    access_token,
201                    refresh_token,
202                })
203            }
204            Err(e) => {
205                self.audit
206                    .on_failure(AuthAuditEvent {
207                        request_id,
208                        action: "refresh",
209                        subject: None,
210                        error_code: Some(e.code_str()),
211                    })
212                    .await;
213                Err(e)
214            }
215        }
216    }
217}