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
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
//! TOTP (Time-based One-Time Password) manager
use crate::errors::{AuthError, Result};
use crate::storage::AuthStorage;
use crate::storage::encryption::{
EncryptedStorage, KeyProvider, KvEncryptionMigrationReport, KvRewrapReport, MigrationOptions,
StorageEncryption, migrate_kv_keys_to_encrypted, rewrap_kv_keys,
};
use std::sync::Arc;
use subtle::ConstantTimeEq;
use tracing::{debug, info, warn};
/// TOTP manager for handling time-based one-time passwords
pub struct TotpManager {
storage: Arc<dyn AuthStorage>,
}
impl TotpManager {
/// Create a TOTP manager over `storage`.
///
/// Secrets are stored as `storage` stores any value. If `storage` does not encrypt at rest (see
/// [`AuthStorage::encrypts_kv_at_rest`]) this logs ONE warning, here at construction, saying so;
/// nothing else changes. To encrypt TOTP secrets with a key you supply use
/// [`Self::new_encrypted`]; to keep plain storage deliberately, without the warning, use
/// [`Self::new_plaintext`].
pub fn new(storage: Arc<dyn AuthStorage>) -> Self {
if !storage.encrypts_kv_at_rest() {
warn!(
"TotpManager is storing TOTP secrets without encryption at rest: anyone who can read \
the backing store can generate valid codes. Use TotpManager::new_encrypted with a \
KeyProvider, or TotpManager::new_plaintext to acknowledge plain storage."
);
}
Self { storage }
}
/// Create a TOTP manager that stores secrets as `storage` stores any value, deliberately and
/// without the warning [`Self::new`] logs for storage that does not encrypt at rest.
pub fn new_plaintext(storage: Arc<dyn AuthStorage>) -> Self {
Self { storage }
}
/// Create a TOTP manager whose secrets are AES-256-GCM encrypted at rest under keys from
/// `provider` (the caller supplies and owns the key).
///
/// `inner` is wrapped in [`EncryptedStorage`] with plaintext and legacy reads OFF: a stored value
/// that is not a valid envelope for its own key is refused, not read as a secret. Everything
/// this manager stores goes through the wrapper, so a row copied onto another user's key does
/// not decrypt. Existing plain secrets must be encrypted first with
/// [`Self::migrate_plain_secrets`]; to rotate keys put the old and the new key in the provider,
/// make the new one current, and run [`Self::rewrap_secrets`].
///
/// # Errors
/// If `provider` cannot supply a usable current key (there is no fallback to plain storage).
pub fn new_encrypted(inner: Arc<dyn AuthStorage>, provider: &dyn KeyProvider) -> Result<Self> {
let encryption = StorageEncryption::new(provider)?;
Ok(Self {
storage: Arc::new(EncryptedStorage::new(inner, encryption, false, false)),
})
}
/// The storage keys under which TOTP secrets live: `mfa_secret:{id}` (the `/mfa/setup` API route)
/// and `user:{id}:totp_secret` (the modular `generate_secret` path), and only those.
async fn secret_keys<S: AuthStorage + ?Sized>(storage: &S) -> Result<Vec<String>> {
let mut keys = storage.list_kv_keys("mfa_secret:").await?;
keys.extend(
storage
.list_kv_keys("user:")
.await?
.into_iter()
.filter(|key| key.ends_with(":totp_secret")),
);
Ok(keys)
}
/// Encrypt, in place, the TOTP secrets that are still stored in the clear in `inner`.
///
/// Touches exactly the two TOTP key shapes (see [`Self::new_encrypted`]), not the rest of a
/// prefix such as `user:`. Idempotent and resumable; each row's TTL is kept. `inner` is the
/// storage underneath any `EncryptedStorage` wrapper, and `encryption` is built from the same
/// provider [`Self::new_encrypted`] will use.
pub async fn migrate_plain_secrets<S: AuthStorage + ?Sized>(
inner: &S,
encryption: &StorageEncryption,
options: MigrationOptions,
) -> Result<KvEncryptionMigrationReport> {
let keys = Self::secret_keys(inner).await?;
migrate_kv_keys_to_encrypted(inner, encryption, keys, options).await
}
/// Re-encrypt, under the current key of `encryption`, the TOTP secrets still under an older
/// key id: the step after making a new key current. See [`rewrap_kv_keys`] for what is and is
/// not touched. `inner` is the storage underneath any `EncryptedStorage` wrapper.
pub async fn rewrap_secrets<S: AuthStorage + ?Sized>(
inner: &S,
encryption: &StorageEncryption,
dry_run: bool,
) -> Result<KvRewrapReport> {
let keys = Self::secret_keys(inner).await?;
rewrap_kv_keys(inner, encryption, keys, dry_run).await
}
/// Generate TOTP secret for a user
pub async fn generate_secret(&self, user_id: &str) -> Result<String> {
debug!("Generating TOTP secret for user '{}'", user_id);
// Generate 20 cryptographically-secure random bytes encoded as RFC 4648 Base32,
// compatible with generate_code_for_window() which base32-decodes the secret.
let rng = ring::rand::SystemRandom::new();
let mut raw_bytes = [0u8; 20];
ring::rand::SecureRandom::fill(&rng, &mut raw_bytes)
.map_err(|_| AuthError::internal("Failed to generate random bytes for TOTP secret"))?;
let secret = base32::encode(base32::Alphabet::Rfc4648 { padding: true }, &raw_bytes);
// Store the secret securely
let key = format!("user:{}:totp_secret", user_id);
self.storage.store_kv(&key, secret.as_bytes(), None).await?;
info!("TOTP secret generated for user '{}'", user_id);
Ok(secret)
}
/// Generate TOTP QR code URL
pub async fn generate_qr_code(
&self,
user_id: &str,
app_name: &str,
secret: &str,
) -> Result<String> {
let qr_url =
format!("otpauth://totp/{app_name}:{user_id}?secret={secret}&issuer={app_name}");
info!("TOTP QR code generated for user '{}'", user_id);
Ok(qr_url)
}
/// Generate current TOTP code using provided secret
pub async fn generate_code(&self, secret: &str) -> Result<String> {
self.generate_code_for_window(secret, None).await
}
/// Generate TOTP code for given secret and optional specific time window
pub async fn generate_code_for_window(
&self,
secret: &str,
time_window: Option<u64>,
) -> Result<String> {
if secret.is_empty() {
return Err(AuthError::validation("TOTP secret cannot be empty"));
}
let window = time_window.unwrap_or_else(|| {
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap_or_default()
.as_secs()
/ 30
});
// Generate TOTP code using ring/sha2 for production cryptographic implementation
use ring::hmac;
// Decode base32 secret
let secret_bytes = base32::decode(base32::Alphabet::Rfc4648 { padding: true }, secret)
.ok_or_else(|| AuthError::InvalidRequest("Invalid TOTP secret format".to_string()))?;
// Create HMAC key for TOTP (using SHA1 as per RFC)
let key = hmac::Key::new(hmac::HMAC_SHA1_FOR_LEGACY_USE_ONLY, &secret_bytes);
// Convert time window to 8-byte big-endian
let time_bytes = window.to_be_bytes();
// Compute HMAC
let signature = hmac::sign(&key, &time_bytes);
let hmac_result = signature.as_ref();
// Dynamic truncation (RFC 4226)
let offset = (hmac_result[19] & 0xf) as usize;
let code = ((hmac_result[offset] as u32 & 0x7f) << 24)
| ((hmac_result[offset + 1] as u32) << 16)
| ((hmac_result[offset + 2] as u32) << 8)
| (hmac_result[offset + 3] as u32);
// Generate 6-digit code
let totp_code = code % 1_000_000;
Ok(format!("{:06}", totp_code))
}
/// Verify TOTP code for a user
pub async fn verify_code(&self, user_id: &str, code: &str) -> Result<bool> {
debug!("Verifying TOTP code for user '{}'", user_id);
if code.len() != 6 || !code.chars().all(|c| c.is_ascii_digit()) {
return Ok(false);
}
// Get user's TOTP secret
let user_secret = match self.get_user_secret(user_id).await {
Ok(secret) => secret,
Err(_) => {
warn!("No TOTP secret found for user '{}'", user_id);
return Ok(false);
}
};
// Generate expected TOTP codes for current and adjacent time windows
let current_time = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap_or_default()
.as_secs();
// TOTP uses 30-second time steps
let time_step = 30;
let current_window = current_time / time_step;
// Check current window and ±1 window for clock drift tolerance
let mut matched_window: Option<u64> = None;
for window in (current_window.saturating_sub(1))..=(current_window + 1) {
if let Ok(expected_code) = self
.generate_code_for_window(&user_secret, Some(window))
.await
&& bool::from(code.as_bytes().ct_eq(expected_code.as_bytes()))
{
matched_window = matched_window.max(Some(window));
}
}
if let Some(window) = matched_window
&& self.claim_step(user_id, window).await?
{
info!("TOTP code verification successful for user '{}'", user_id);
return Ok(true);
}
info!("TOTP code verification failed for user '{}'", user_id);
Ok(false)
}
/// Get user's TOTP secret from secure storage.
///
/// Checks both storage locations a secret may have been enrolled under
/// -- `mfa_secret:{user_id}` (the live `/mfa/setup` API route) and
/// `user:{user_id}:totp_secret` (the modular `generate_secret` path) --
/// matching [`Self::verify_login_code`]'s existing dual-key lookup, so
/// a user enrolled via either route is recognized by this method too.
///
/// Returns an error if the user has no secret enrolled under either
/// key. There is no fallback secret: a user with nothing enrolled must
/// fail verification, never receive a silently-derived one.
async fn get_user_secret(&self, user_id: &str) -> Result<String> {
let api_key = format!("mfa_secret:{}", user_id);
if let Some(secret_data) = self.storage.get_kv(&api_key).await? {
return String::from_utf8(secret_data)
.map_err(|e| AuthError::internal(format!("Failed to parse TOTP secret: {}", e)));
}
let modular_key = format!("user:{}:totp_secret", user_id);
if let Some(secret_data) = self.storage.get_kv(&modular_key).await? {
return String::from_utf8(secret_data)
.map_err(|e| AuthError::internal(format!("Failed to parse TOTP secret: {}", e)));
}
Err(AuthError::validation(format!(
"No TOTP secret enrolled for user '{}'",
user_id
)))
}
/// Check if user has TOTP secret configured
pub async fn has_totp_secret(&self, user_id: &str) -> Result<bool> {
let api_key = format!("mfa_secret:{}", user_id);
match self.storage.get_kv(&api_key).await {
Ok(Some(_)) => Ok(true),
Ok(None) => {
let modular_key = format!("user:{}:totp_secret", user_id);
match self.storage.get_kv(&modular_key).await {
Ok(Some(_)) => Ok(true),
Ok(None) => Ok(false),
Err(_) => Ok(false),
}
}
Err(_) => Ok(false), // Assume false on error
}
}
/// Verify a TOTP code during the login MFA flow.
/// Reads from `mfa_secret:{user_id}` (API setup) or `user:{user_id}:totp_secret` (modular setup).
pub async fn verify_login_code(&self, user_id: &str, code: &str) -> Result<bool> {
use crate::security::secure_utils::constant_time_compare;
if code.len() != 6 || !code.chars().all(|c| c.is_ascii_digit()) {
return Ok(false);
}
// Try the API MFA key first, then fall back to the modular TOTP key.
let secret_b32 = match self
.storage
.get_kv(&format!("mfa_secret:{}", user_id))
.await?
{
Some(data) => String::from_utf8_lossy(&data).to_string(),
None => match self
.storage
.get_kv(&format!("user:{}:totp_secret", user_id))
.await?
{
Some(data) => String::from_utf8_lossy(&data).to_string(),
None => return Ok(false),
},
};
let secret_bytes = match base32::decode(
base32::Alphabet::Rfc4648 { padding: false },
&secret_b32,
)
.or_else(|| base32::decode(base32::Alphabet::Rfc4648 { padding: true }, &secret_b32))
{
Some(bytes) => bytes,
None => return Ok(false),
};
let now = chrono::Utc::now().timestamp() as u64;
const STEP: u64 = 30;
const DIGITS: u32 = 6;
let mut matched_step: Option<u64> = None;
for offset in [0u64, STEP, STEP.wrapping_neg()] {
let timestamp = now.wrapping_add(offset);
let expected =
totp_lite::totp_custom::<totp_lite::Sha1>(STEP, DIGITS, &secret_bytes, timestamp);
if constant_time_compare(expected.as_bytes(), code.as_bytes()) {
matched_step = matched_step.max(Some(timestamp / STEP));
}
}
match matched_step {
Some(step) => self.claim_step(user_id, step).await,
None => Ok(false),
}
}
/// Accept a matched TOTP time step only if it is newer than the last one accepted for
/// this user, so a code (e.g. one observed over a shoulder or in a log) works once.
async fn claim_step(&self, user_id: &str, step: u64) -> Result<bool> {
let key = format!("mfa_totp_last_step:{user_id}");
let last = match self.storage.get_kv(&key).await? {
Some(bytes) => std::str::from_utf8(&bytes)
.ok()
.and_then(|s| s.parse::<u64>().ok()),
None => None,
};
if last.is_some_and(|last| step <= last) {
return Ok(false);
}
// Claim THIS step atomically: of simultaneous submissions of the same code exactly one
// wins. A code is valid for at most three steps; remember the claim a little longer.
if !self
.storage
.store_kv_if_absent(
&format!("mfa_totp_used:{user_id}:{step}"),
b"1",
Some(std::time::Duration::from_secs(300)),
)
.await?
{
return Ok(false);
}
self.storage
.store_kv(
&key,
step.to_string().as_bytes(),
Some(std::time::Duration::from_secs(300)),
)
.await?;
Ok(true)
}
}