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/// 终止会话时建议**同时**传入 Access Token 与 Refresh Token:仅撤销 Access Token
103/// 会让攻击者仍能用未失效的 Refresh Token 刷出新的 Access Token,会话并未真正结束。
104#[derive(Clone, Deserialize, schemars::JsonSchema)]
105#[serde(deny_unknown_fields)]
106pub struct LogoutInput {
107    /// 待撤销的 Token(通常是 Access Token)
108    pub token: String,
109    /// 待撤销的 Refresh Token(可选)
110    ///
111    /// 若提供,将与 `token` 一并写入黑名单,从而彻底终止整个会话;
112    /// 不提供时仅撤销 `token`。
113    #[serde(default)]
114    pub refresh_token: Option<String>,
115}
116
117// NEW-38: 手写 Debug 脱敏
118impl core::fmt::Debug for LogoutInput {
119    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
120        f.debug_struct("LogoutInput")
121            .field("token", &format!("***({} chars)", self.token.len()))
122            .field(
123                "refresh_token",
124                &self
125                    .refresh_token
126                    .as_ref()
127                    .map(|s| format!("***({} chars)", s.len())),
128            )
129            .finish()
130    }
131}
132
133/// 通用成功消息响应。
134#[derive(Debug, Clone, Serialize, schemars::JsonSchema)]
135pub struct MessageResponse {
136    /// 结果消息
137    pub message: String,
138}
139
140/// 同一授权快照派生出的 Access/Refresh Token 自定义声明。
141///
142/// Access Token 可携带角色、权限等完整授权信息;Refresh Token 应只保留刷新流程
143/// 所需的最小稳定声明。默认不为 Refresh Token 附加声明,保持既有行为。
144#[derive(Debug, Clone)]
145pub struct TokenPairClaims {
146    /// 写入 Access Token 的自定义声明。
147    pub access: serde_json::Value,
148    /// 写入 Refresh Token 的自定义声明。
149    pub refresh: serde_json::Value,
150}
151
152impl TokenPairClaims {
153    /// 创建仅含 Access Token 自定义声明的声明对。
154    pub fn new(access: serde_json::Value) -> Self {
155        Self {
156            access,
157            refresh: serde_json::Value::Null,
158        }
159    }
160
161    /// 设置 Refresh Token 的最小自定义声明(链式)。
162    pub fn with_refresh(mut self, refresh: serde_json::Value) -> Self {
163        self.refresh = refresh;
164        self
165    }
166}
167
168/// 校验通过后的主体信息,由 [`CredentialVerifier`](super::CredentialVerifier) 返回。
169#[derive(Debug, Clone)]
170pub struct VerifiedSubject {
171    /// Token 主题(通常是用户 ID,写入 JWT `sub`)
172    pub subject: String,
173    /// 写入 Access Token 的自定义声明(如角色、权限)
174    pub custom_claims: serde_json::Value,
175    /// 写入 Refresh Token 的最小自定义声明
176    pub refresh_claims: serde_json::Value,
177}
178
179impl VerifiedSubject {
180    /// 用主题创建,无自定义声明。
181    pub fn new(subject: impl Into<String>) -> Self {
182        Self {
183            subject: subject.into(),
184            custom_claims: serde_json::Value::Null,
185            refresh_claims: serde_json::Value::Null,
186        }
187    }
188
189    /// 设置自定义声明(链式)。
190    pub fn with_claims(mut self, claims: serde_json::Value) -> Self {
191        self.custom_claims = claims;
192        self
193    }
194
195    /// 设置 Refresh Token 的最小自定义声明(链式)。
196    pub fn with_refresh_claims(mut self, claims: serde_json::Value) -> Self {
197        self.refresh_claims = claims;
198        self
199    }
200
201    /// 设置同一授权快照派生出的 Access/Refresh Token 声明(链式)。
202    pub fn with_token_pair_claims(mut self, claims: TokenPairClaims) -> Self {
203        self.custom_claims = claims.access;
204        self.refresh_claims = claims.refresh;
205        self
206    }
207}