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
// Copyright (c) 2026 Kirky.X🌠
// SPDX-License-Identifier: Apache-2.0
//! 凭证模型 SPI 子模块(吸收 Keycloak CredentialModel SPI):统一凭证抽象,支持 password / TOTP / WebAuthn 等。
//!
//! 核心类型:`Credential` trait(统一校验接口)、`CredentialModel`(DAO 持久化结构,8 字段 schema)、
//! `CredentialRepository` trait(CRUD 5 方法)。`Credential::verify` 接收 `&str` 而非泛型(对象安全);
//! `PasswordHasher` 位于 `password` 子模块。
/// 密码哈希子模块。
///
/// 提供 `PasswordHasher` trait + `Argon2Hasher` / `BcryptHasher` + `PasswordVerifier`。
// 模块重导出:通过 mod 路径访问子模块类型(避免外部代码引用具体文件路径)
pub use ;
/// TOTP 凭证子模块(复用 `secure::totp::TotpHandler`)。
///
/// 需同时启用 `account-credential` + `secure-totp` feature。
/// 邮箱验证码凭证子模块(复用 `secure::email::EmailVerificationService`):`secret_data` 存邮箱地址,
/// 验证委托 `EmailVerificationService::verify_code`(KV 一次性消费 + 限速 + 异常检测)。
///
/// 需同时启用 `account-credential` + `email-verification` feature。
/// 备份码凭证子模块。
use crateDaoKeyPrefix;
use crateGarrisonDao;
use crate;
use async_trait;
use Arc;
/// 凭证类型标识(字符串形式,如 `"password"` / `"totp"` / `"webauthn"`)。
///
/// 使用 `&'static str` 而非 `String`:凭证类型在编译期已知,避免分配。
pub type CredentialType = &'static str;
/// 凭证统一 trait(吸收 Keycloak CredentialModel SPI)。
///
/// 每种凭证类型(password / TOTP / WebAuthn)提供统一的 `credential_type()` / `to_model()` /
/// `verify()` 接口;`verify` 接收 `&str` 而非泛型,保证对象安全(可作 `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?;
/// ```
/// 凭证存储模型(DAO 持久化结构,8 字段 schema 锁定;经 serde 序列化为 JSON 存入 DAO)。
///
/// # 安全注意(secret_data 默认不清零)
///
/// `secret_data` 存密码哈希 / TOTP secret / WebAuthn 公钥等敏感材料。`Zeroize` / `ZeroizeOnDrop`
/// 仅在启用 `credential-zeroize` feature 时派生(独立 opt-in,不随 `account-credential` 自动启用);
/// 默认构建下 drop 后内存不清零,存在 heapdump / 冷启动残留风险,高安全场景请显式启用或在业务层
/// 自行管理生命周期。
/// 凭证存储抽象(DAO 层接口),CRUD 方法:`create` / `find_by_user` / `find_by_user_and_type` /
/// `update` / `delete`;默认实现 `DaoCredentialRepository` 基于 `GarrisonDao`,也可由业务方自定义。
///
/// # IDOR 防护
///
/// `find_by_user` / `update` / `delete` 强制 `caller_login_id` 参数,实现层须验证其与目标凭证
/// `user_id` 一致,否则返回 `GarrisonError::NotPermission`(403);`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?;
/// ```
/// 基于 `GarrisonDao` 的 `CredentialRepository` 默认实现:凭证以 JSON 序列化存入 DAO,
/// key 严格为 `cred:{user_id}:{cred_id}`,永久存储(`set_permanent`,无 TTL)。
///
/// # 已知限制
///
/// - `find_by_user` / `find_by_user_and_type` / `delete` 依赖 `GarrisonDao::keys()`,其错误原样上抛
/// (不静默);`GarrisonDaoOxcache` 未启用 `dao-key-index` feature 时 `keys()` 返回 `NotImplemented`,
/// 生产环境需启用该 feature 或换支持 `keys()` 的后端,或自维护 key 索引。
/// - `delete` 扫描 `cred:*:{credential_id}` 定位完整 key(UUID v4 全局唯一,理论上仅匹配一个),
/// 再反序列化校验 `user_id == caller_login_id` 后删除;异常多键场景逐 key 处理,先删的 key 不回滚
/// (详见 repository_impl 模块文档)。