Skip to main content

yang_base/action/auth/
dto.rs

1//! 认证内置 Action 的输入 / 输出 DTO 与 Token 声明载体。
2
3use serde::{Deserialize, Serialize};
4
5// ──────────────────────────────────────────────────────────────────────────────
6// 输入 / 输出 DTO
7// ──────────────────────────────────────────────────────────────────────────────
8
9/// 登录输入:凭证字段。
10///
11/// 注意:字段固定,与具体 [`CredentialVerifier`](super::CredentialVerifier) 实现无关——`LoginAction<V>` 是
12/// 泛型,而 `#[derive(Action)]` 生成的 schema 静态量在各实例化间共享,故 Input
13/// 不能依赖 `V`。如需额外字段,可在 `extra` 中携带任意 JSON。
14#[derive(Clone, Deserialize, schemars::JsonSchema)]
15pub struct LoginInput {
16    /// 用户名 / 账号 / 邮箱等登录标识
17    pub username: String,
18    /// 密码 / 凭据
19    pub password: String,
20    /// 额外的业务自定义字段(可选)
21    #[serde(default)]
22    pub extra: serde_json::Value,
23}
24
25// NEW-38: 手写 Debug 脱敏,防止密码明文泄漏到日志/tracing
26impl core::fmt::Debug for LoginInput {
27    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
28        f.debug_struct("LoginInput")
29            .field("username", &self.username)
30            .field("password", &"***")
31            .field("extra", &self.extra)
32            .finish()
33    }
34}
35
36/// Token 对响应。
37#[derive(Clone, Serialize, schemars::JsonSchema)]
38pub struct TokenPairResponse {
39    /// Access Token
40    pub access_token: String,
41    /// Refresh Token
42    pub refresh_token: String,
43}
44
45// NEW-38: 手写 Debug 脱敏,防止 Token 明文泄漏到日志/tracing
46impl core::fmt::Debug for TokenPairResponse {
47    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
48        f.debug_struct("TokenPairResponse")
49            .field(
50                "access_token",
51                &format!("***({} chars)", self.access_token.len()),
52            )
53            .field(
54                "refresh_token",
55                &format!("***({} chars)", self.refresh_token.len()),
56            )
57            .finish()
58    }
59}
60
61/// 刷新输入。
62#[derive(Clone, Deserialize, schemars::JsonSchema)]
63#[serde(deny_unknown_fields)]
64pub struct RefreshInput {
65    /// Refresh Token
66    pub refresh_token: String,
67}
68
69// NEW-38: 手写 Debug 脱敏
70impl core::fmt::Debug for RefreshInput {
71    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
72        f.debug_struct("RefreshInput")
73            .field(
74                "refresh_token",
75                &format!("***({} chars)", self.refresh_token.len()),
76            )
77            .finish()
78    }
79}
80
81/// 刷新响应(仅新的 Access Token)。
82#[derive(Clone, Serialize, schemars::JsonSchema)]
83pub struct AccessTokenResponse {
84    /// 新的 Access Token
85    pub access_token: String,
86}
87
88// NEW-38: 手写 Debug 脱敏
89impl core::fmt::Debug for AccessTokenResponse {
90    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
91        f.debug_struct("AccessTokenResponse")
92            .field(
93                "access_token",
94                &format!("***({} chars)", self.access_token.len()),
95            )
96            .finish()
97    }
98}
99
100/// 登出输入。
101///
102/// 撤销按 `sub`(用户主题)水位线一次性生效:该用户在此刻之前签发的**全部**
103/// Token(Access + Refresh)与后续任何已签发 Token 均立即失效,无需分别传入。
104#[derive(Clone, Deserialize, schemars::JsonSchema)]
105#[serde(deny_unknown_fields)]
106pub struct LogoutInput {
107    /// 待撤销的 Token(通常是 Access Token)
108    pub token: String,
109}
110
111// NEW-38: 手写 Debug 脱敏
112impl core::fmt::Debug for LogoutInput {
113    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
114        f.debug_struct("LogoutInput")
115            .field("token", &format!("***({} chars)", self.token.len()))
116            .finish()
117    }
118}
119
120/// 通用成功消息响应。
121#[derive(Debug, Clone, Serialize, schemars::JsonSchema)]
122pub struct MessageResponse {
123    /// 结果消息
124    pub message: String,
125}
126
127/// 同一授权快照派生出的 Access/Refresh Token 自定义声明。
128///
129/// Access Token 可携带角色、权限等完整授权信息;Refresh Token 应只保留刷新流程
130/// 所需的最小稳定声明。默认不为 Refresh Token 附加声明,保持既有行为。
131#[derive(Debug, Clone)]
132pub struct TokenPairClaims {
133    /// 写入 Access Token 的自定义声明。
134    pub access: serde_json::Value,
135    /// 写入 Refresh Token 的自定义声明。
136    pub refresh: serde_json::Value,
137}
138
139impl TokenPairClaims {
140    /// 创建仅含 Access Token 自定义声明的声明对。
141    pub fn new(access: serde_json::Value) -> Self {
142        Self {
143            access,
144            refresh: serde_json::Value::Null,
145        }
146    }
147
148    /// 设置 Refresh Token 的最小自定义声明(链式)。
149    pub fn with_refresh(mut self, refresh: serde_json::Value) -> Self {
150        self.refresh = refresh;
151        self
152    }
153}
154
155/// 校验通过后的主体信息,由 [`CredentialVerifier`](super::CredentialVerifier) 返回。
156#[derive(Debug, Clone)]
157pub struct VerifiedSubject {
158    /// Token 主题(通常是用户 ID,写入 JWT `sub`)
159    pub subject: String,
160    /// 写入 Access Token 的自定义声明(如角色、权限)
161    pub custom_claims: serde_json::Value,
162    /// 写入 Refresh Token 的最小自定义声明
163    pub refresh_claims: serde_json::Value,
164}
165
166impl VerifiedSubject {
167    /// 用主题创建,无自定义声明。
168    pub fn new(subject: impl Into<String>) -> Self {
169        Self {
170            subject: subject.into(),
171            custom_claims: serde_json::Value::Null,
172            refresh_claims: serde_json::Value::Null,
173        }
174    }
175
176    /// 设置自定义声明(链式)。
177    pub fn with_claims(mut self, claims: serde_json::Value) -> Self {
178        self.custom_claims = claims;
179        self
180    }
181
182    /// 设置 Refresh Token 的最小自定义声明(链式)。
183    pub fn with_refresh_claims(mut self, claims: serde_json::Value) -> Self {
184        self.refresh_claims = claims;
185        self
186    }
187
188    /// 设置同一授权快照派生出的 Access/Refresh Token 声明(链式)。
189    pub fn with_token_pair_claims(mut self, claims: TokenPairClaims) -> Self {
190        self.custom_claims = claims.access;
191        self.refresh_claims = claims.refresh;
192        self
193    }
194}