1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
//! Copyright (c) 2026 Kirky.X. All rights reserved.
//! See LICENSE for full license text.
//! 凭证模型 SPI 子模块(吸收 keycloak CredentialModel SPI)。
//! 提供统一凭证抽象,支持 password / TOTP / WebAuthn(v0.7+)等多种凭证类型。
//! 详见 spec `credential-model`。
//!
//! # 核心类型
//!
//! - `Credential` trait:统一凭证校验接口(对象安全,可作 `dyn Credential`)
//! - `CredentialModel`:凭证存储模型(DAO 持久化结构,8 字段 schema)
//! - `CredentialRepository` trait:凭证存储抽象(CRUD 5 方法)
//!
//! # 设计决策
//!
//! - D1: `Credential::verify(&self, input: &str)` 接收 `&str` 而非泛型(对象安全)
//! - D5: `PasswordHasher` 从 `secure/password/` 破坏性迁移到本模块的 `password` 子模块
/// 密码哈希子模块(v0.6.0 从 secure/password/ 迁移)。
///
/// 提供 `PasswordHasher` trait + `Argon2Hasher` / `BcryptHasher` + `PasswordVerifier`。
// 模块重导出:通过 mod 路径访问子模块类型(避免外部代码引用具体文件路径)
pub use ;
/// TOTP 凭证子模块(复用 `secure::totp::TotpHandler`)。
///
/// 需同时启用 `account-credential` + `secure-totp` feature。
/// 备份码凭证子模块。
use crateDaoKeyPrefix;
use crateGarrisonDao;
use crate;
use async_trait;
use Arc;
// ============================================================================
// 类型别名
// ============================================================================
/// 凭证类型标识(字符串形式,如 `"password"` / `"totp"` / `"webauthn"`)。
///
/// 使用 `&'static str` 而非 `String`:凭证类型在编译期已知,避免分配。
pub type CredentialType = &'static str;
// ============================================================================
// Credential trait(统一凭证校验接口)
// ============================================================================
/// 凭证统一 trait(吸收 keycloak CredentialModel SPI)。
///
/// 每种凭证类型(password / TOTP / WebAuthn)实现此 trait,提供统一的
/// `credential_type()` / `to_model()` / `verify()` 接口。
///
/// # 对象安全
///
/// `verify` 接收 `&str` 而非泛型(决策 D1),保证 trait 对象安全,
/// 可作 `Box<dyn Credential>` / `Arc<dyn Credential>` 使用。
///
/// # 示例
///
/// ```ignore
/// use garrison::account::credential::{Credential, CredentialModel};
///
/// let cred: Box<dyn Credential> = /* PasswordCredential / TotpCredential */;
/// let ok = cred.verify("user-input").await?;
/// ```
// ============================================================================
// CredentialModel(凭证存储模型)
// ============================================================================
/// 凭证存储模型(DAO 持久化结构)。
///
/// 8 字段 schema(pre-1.0 锁定,与 design.md §3.1 严格一致)。
/// 通过 `serde::Serialize` / `serde::Deserialize` 序列化为 JSON 存入 DAO。
///
/// # 字段说明
///
/// | 字段 | 类型 | 说明 |
/// |:---|:---|:---|
/// | `id` | `String` | 凭证 ID(UUID v4) |
/// | `user_id` | `String` | 用户 ID(关联 login_id) |
/// | `credential_type` | `String` | 凭证类型(`"password"` / `"totp"` / ...) |
/// | `secret_data` | `String` | 凭证数据(hash / secret / public key,JSON 编码) |
/// | `label` | `Option<String>` | 用户自定义标签(如 `"iPhone TOTP"`) |
/// | `created_at` | `i64` | 创建时间(Unix 时间戳) |
/// | `enabled` | `bool` | 是否启用 |
/// | `priority` | `i32` | 优先级(多凭证时排序,小值优先) |
// ============================================================================
// CredentialRepository trait(凭证存储抽象)
// ============================================================================
/// 凭证存储抽象(DAO 层接口)。
///
/// 5 方法 CRUD:`create` / `find_by_user` / `find_by_user_and_type` / `update` / `delete`。
/// 由 `DaoCredentialRepository`(T006 实现)基于 `GarrisonDao` 实现,也可由业务方自定义实现。
///
/// # IDOR 防护(vuln-0004 修复)
///
/// `find_by_user` / `update` / `delete` 强制要求 `caller_login_id` 参数,由实现层验证
/// `caller_login_id` 与目标凭证的 `user_id` 一致,否则返回 `GarrisonError::NotPermission`
/// (HTTP 403 Forbidden)。`update` 额外禁止修改 `user_id` 字段(防止凭证跨用户转移)。
///
/// # DAO key 格式
///
/// `cred:{user_id}:{cred_id}`(如 `cred:alice:550e8400-...`)
///
/// # 示例
///
/// ```ignore
/// use garrison::account::credential::{CredentialModel, CredentialRepository};
/// use std::sync::Arc;
///
/// let repo: Arc<dyn CredentialRepository> = /* DaoCredentialRepository */;
/// // caller_login_id 必须等于 user_id,否则返回 NotPermission
/// let creds = repo.find_by_user("alice", "alice").await?;
/// ```
// ============================================================================
// DaoCredentialRepository(基于 GarrisonDao 的默认实现)
// ============================================================================
/// 基于 `GarrisonDao` 的 `CredentialRepository` 默认实现。
///
/// 凭证以 JSON 序列化存入 DAO,key 格式严格为 `cred:{user_id}:{cred_id}`,
/// 永久存储(无 TTL,使用 `set_permanent`)。
///
/// # DAO key 格式
///
/// `cred:{user_id}:{cred_id}`(如 `cred:alice:550e8400-e29b-...`)
///
/// # 已知限制
///
/// - `find_by_user` / `find_by_user_and_type` / `delete` 依赖 `GarrisonDao::keys()`。
/// `GarrisonDaoOxcache` 当前未实现 `keys()`(返回 `NotImplemented`,详见 A-010),
/// 生产环境需使用支持 `keys()` 的 DAO 后端,或由业务方维护 key 索引。
/// - `delete(caller_login_id, credential_id)` 通过扫描 `cred:*:{credential_id}` 定位
/// 完整 key(`credential_id` 为 UUID v4 全局唯一,理论上仅匹配一个 key),
/// 再反序列化校验 `user_id == caller_login_id` 后删除。