garrison 0.9.0

Garrison - 面向 Rust 生态的一站式身份认证鉴权框架
Documentation
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
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
// Copyright (c) 2026 Kirky.X🌠
// SPDX-License-Identifier: Apache-2.0

//! 邮箱验证码模块单元测试。

use super::rate_limiter::{normalize_email, validate_email};
use super::service::generate_code;
use super::*;
use crate::dao::tests::MockDao;
use crate::error::GarrisonError;
use crate::secure::ct_eq::constant_time_eq;
use async_trait::async_trait;
use std::sync::Arc;

// normalize_email 测试

#[test]
fn normalize_email_trims_and_lowercases() {
    assert_eq!(normalize_email(" Foo@Example.COM "), "foo@example.com");
    assert_eq!(normalize_email("USER@DOMAIN.ORG"), "user@domain.org");
    assert_eq!(normalize_email("  a@b.c  "), "a@b.c");
}

#[test]
fn normalize_email_empty_string() {
    assert_eq!(normalize_email(""), "");
    assert_eq!(normalize_email("   "), "");
}

// validate_email 测试

#[test]
fn validate_email_valid() {
    assert!(validate_email("user@example.com").is_ok());
    assert!(validate_email("a@b.c").is_ok());
    assert!(validate_email("test+tag@domain.org").is_ok());
}

#[test]
fn validate_email_empty_rejected() {
    let err = validate_email("").unwrap_err();
    assert!(
        matches!(err, crate::error::GarrisonError::InvalidParam(msg) if msg.starts_with("secure-email-empty"))
    );
}

#[test]
fn validate_email_colon_rejected() {
    let err = validate_email("a:b@c.com").unwrap_err();
    assert!(
        matches!(err, crate::error::GarrisonError::InvalidParam(msg) if msg.starts_with("secure-email-no-colon"))
    );
}

#[test]
fn validate_email_control_char_rejected() {
    let err = validate_email("user\x00@example.com").unwrap_err();
    assert!(
        matches!(err, crate::error::GarrisonError::InvalidParam(msg) if msg.starts_with("secure-email-no-control-char"))
    );
}

#[test]
fn validate_email_too_long_rejected() {
    let long = format!("{}@b.com", "a".repeat(250));
    let err = validate_email(&long).unwrap_err();
    assert!(
        matches!(err, crate::error::GarrisonError::InvalidParam(msg) if msg.starts_with("secure-email-invalid-format"))
    );
}

#[test]
fn validate_email_no_at_rejected() {
    let err = validate_email("userexample.com").unwrap_err();
    assert!(
        matches!(err, crate::error::GarrisonError::InvalidParam(msg) if msg.starts_with("secure-email-invalid-format"))
    );
}

// generate_code 测试

#[test]
fn generate_code_returns_six_digits() {
    for _ in 0..100 {
        let code = generate_code().unwrap();
        assert_eq!(code.len(), 6);
        assert!(code.chars().all(|c| c.is_ascii_digit()));
        assert_ne!(code, "000000");
        let num: u32 = code.parse().unwrap();
        assert!((100000..1000000).contains(&num));
    }
}

// 验证码比对原语测试(ADR-0003 决策 2:统一走 secure::ct_eq)

#[test]
fn code_ct_eq_equal_strings() {
    use crate::secure::ct_eq::constant_time_eq;
    assert!(constant_time_eq(b"123456", b"123456"));
}

#[test]
fn code_ct_eq_different_strings() {
    use crate::secure::ct_eq::constant_time_eq;
    assert!(!constant_time_eq(b"123456", b"654321"));
    assert!(!constant_time_eq(b"123456", b"123457"));
}

// constant_time_eq 测试(verify_code 存储码与用户输入的统一比较原语)

#[test]
fn constant_time_eq_equal_strings() {
    assert!(constant_time_eq(b"123456", b"123456"));
    assert!(constant_time_eq(b"", b""));
}

#[test]
fn constant_time_eq_different_strings() {
    assert!(!constant_time_eq(b"123456", b"654321"));
    assert!(!constant_time_eq(b"123456", b"123457"));
}

#[test]
fn code_ct_eq_different_lengths() {
    use crate::secure::ct_eq::constant_time_eq;
    assert!(!constant_time_eq(b"123456", b"12345"));
    assert!(!constant_time_eq(b"12", b"123456"));
}

#[test]
fn constant_time_eq_different_lengths() {
    assert!(!constant_time_eq(b"123456", b"12345"));
    assert!(!constant_time_eq(b"12", b"123456"));
    assert!(!constant_time_eq(b"", b"123456"));
    assert!(!constant_time_eq(b"123456", b""));
}

/// 超长/短验证码输入按「错误验证码」失败路径处理(计入尝试次数)。
///
/// 安全属性:验证码定长 6 位,长度不符必然不等,`verify_code` 进入比较前即拒绝——用户可控输入长度不得放大服务端计算量(调用方长度预校验约定);长度是公开参数,提前拒绝不泄露秘密。
#[tokio::test]
async fn wrong_length_code_counts_as_failed_attempt() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
    let service = make_service_with(dao.clone(), 3, 3);
    service.send_code("user6@example.com").await.unwrap();

    // 超长输入(1MB):拒绝且计入一次失败尝试(与失败语义一致)
    let oversized = "1".repeat(1024 * 1024);
    let result = service.verify_code("user6@example.com", &oversized).await;
    assert!(
        matches!(result, Err(GarrisonError::InvalidParam(ref m)) if m.starts_with(service::ERR_EMAIL_CODE_WRONG)),
        "超长验证码应按错误验证码拒绝,实际: {:?}",
        result
    );
    // 短输入同型
    let result = service.verify_code("user6@example.com", "12345").await;
    assert!(matches!(result, Err(GarrisonError::InvalidParam(_))));
    let attempts = dao.get("email:attempts:user6@example.com").await.unwrap();
    assert_eq!(
        attempts,
        Some("2".to_string()),
        "长度不符的输入应计入失败尝试"
    );
}

// SmtpConfig 测试(仅 email-verification-smtp feature)

#[cfg(feature = "email-verification-smtp")]
#[test]
fn smtp_config_defaults() {
    let config = super::smtp::SmtpConfig::default();
    assert_eq!(config.port, 587);
    assert_eq!(config.from_name, "Garrison");
    assert!(config.use_tls);
    assert!(config.host.is_empty());
    assert!(config.username.is_empty());
}

// EmailVerificationService 服务级行为测试(对齐 sms/tests.rs 模式)

/// 仅记录不实际发送的 Noop 实现(测试用)。
struct NoopEmailSender;

#[async_trait]
impl EmailSender for NoopEmailSender {
    async fn send(&self, _to: &str, _subject: &str, _body: &str) -> GarrisonResult<()> {
        Ok(())
    }
}

/// 捕获最近一次邮件(to, subject, body)的测试实现。
struct CapturingEmailSender {
    mail: parking_lot::Mutex<Option<(String, String, String)>>,
}

#[async_trait]
impl EmailSender for CapturingEmailSender {
    async fn send(&self, to: &str, subject: &str, body: &str) -> GarrisonResult<()> {
        *self.mail.lock() = Some((to.to_string(), subject.to_string(), body.to_string()));
        Ok(())
    }
}

/// 始终发送失败的测试实现(模拟 SMTP 网关不可达)。
struct FailingEmailSender;

#[async_trait]
impl EmailSender for FailingEmailSender {
    async fn send(&self, _to: &str, _subject: &str, _body: &str) -> GarrisonResult<()> {
        Err(GarrisonError::Network(
            "email-smtp-send-failed::mock-network-down".to_string(),
        ))
    }
}

/// 构造测试用 EmailVerificationService(默认配置:5/h、10/d、3 次尝试、阈值 100、TTL 600s)。
fn make_service() -> EmailVerificationService {
    let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
    make_service_with(dao, 3, 100)
}

/// 以自定义 DAO 与阈值构造服务(限速 5/h、10/d,TTL 600s)。
fn make_service_with(
    dao: Arc<dyn GarrisonDao>,
    max_attempts: u32,
    unverified_threshold: u32,
) -> EmailVerificationService {
    let rate_limiter = EmailRateLimiter::new(dao.clone(), 5, 10);
    EmailVerificationService::new(
        rate_limiter,
        Arc::new(NoopEmailSender),
        dao,
        max_attempts,
        unverified_threshold,
        600,
    )
}

/// 测试 1:小时限速 5/h 放行(前 5 次成功)。
#[tokio::test]
async fn hourly_limit_allows_first_5() {
    let service = make_service();
    for i in 0..5 {
        let result = service.send_code("user@example.com").await;
        assert!(
            result.is_ok(),
            "第 {} 次发送应成功,实际: {:?}",
            i + 1,
            result
        );
    }
}

/// 测试 2:小时限速 5/h 拦截第 6 次。
#[tokio::test]
async fn hourly_limit_blocks_6th() {
    let service = make_service();
    for _ in 0..5 {
        service.send_code("user1@example.com").await.unwrap();
    }
    let result = service.send_code("user1@example.com").await;
    assert!(
        matches!(result, Err(GarrisonError::EmailRateLimitExceeded { ref window }) if window == "hourly"),
        "第 6 次应被小时限速拦截,实际: {:?}",
        result
    );
}

/// 测试 3:天限速 10/d 拦截第 11 次(小时窗口调大以隔离验证天窗口)。
#[tokio::test]
async fn daily_limit_blocks_11th() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
    let service = EmailVerificationService::new(
        EmailRateLimiter::new(dao.clone(), 100, 10),
        Arc::new(NoopEmailSender),
        dao.clone(),
        3,
        100,
        600,
    );
    for _ in 0..10 {
        service.send_code("user2@example.com").await.unwrap();
    }
    let result = service.send_code("user2@example.com").await;
    assert!(
        matches!(result, Err(GarrisonError::EmailRateLimitExceeded { ref window }) if window == "daily"),
        "第 11 次应被天限速拦截,实际: {:?}",
        result
    );
}

/// 测试 4:验证码验证失败 3 次后失效(第 4 次返回 EmailVerifyMaxAttempts)。
#[tokio::test]
async fn verify_max_attempts_after_3_failures() {
    let service = make_service_with(Arc::new(MockDao::new()), 3, 100);
    service.send_code("user3@example.com").await.unwrap();
    for _ in 0..3 {
        let r = service.verify_code("user3@example.com", "000000").await;
        assert!(
            matches!(r, Err(GarrisonError::InvalidParam(_))),
            "前 3 次错误应返回 InvalidParam"
        );
    }
    let result = service.verify_code("user3@example.com", "000000").await;
    assert!(
        matches!(result, Err(GarrisonError::EmailVerifyMaxAttempts)),
        "第 4 次应返回 EmailVerifyMaxAttempts,实际: {:?}",
        result
    );
}

/// 测试 5:正确验证码通过后清除 code/unverified/attempts 全部状态;并断言收件人为规范化地址、本地化正文含验证码。
#[tokio::test]
async fn correct_code_verifies_and_clears_state() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
    let sender = Arc::new(CapturingEmailSender {
        mail: parking_lot::Mutex::new(None),
    });
    let service = EmailVerificationService::new(
        EmailRateLimiter::new(dao.clone(), 5, 10),
        sender.clone(),
        dao.clone(),
        3,
        3,
        600,
    );
    service.send_code("User@Example.COM").await.unwrap();
    let (to, subject, body) = sender.mail.lock().clone().unwrap();
    assert_eq!(to, "user@example.com", "收件人应为规范化(小写)地址");
    assert!(!subject.is_empty(), "邮件主题不应为空");
    let code = dao
        .get("email:code:user@example.com")
        .await
        .unwrap()
        .unwrap();
    assert!(body.contains(&code), "邮件正文应包含验证码 {}", code);

    let result = service.verify_code("user@example.com", &code).await;
    assert!(result.is_ok(), "正确验证码应验证通过");
    assert!(
        dao.get("email:code:user@example.com")
            .await
            .unwrap()
            .is_none(),
        "验证后验证码应被删除"
    );
    assert!(
        dao.get("email:unverified:user@example.com")
            .await
            .unwrap()
            .is_none(),
        "验证后未验证计数应被清零"
    );
    assert!(
        dao.get("email:attempts:user@example.com")
            .await
            .unwrap()
            .is_none(),
        "验证后尝试计数应被清零"
    );
}

/// 测试 6:错误验证码递增尝试计数。
#[tokio::test]
async fn wrong_code_increments_attempts() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
    let service = make_service_with(dao.clone(), 3, 3);
    service.send_code("user4@example.com").await.unwrap();
    service
        .verify_code("user4@example.com", "wrong1")
        .await
        .unwrap_err();
    let attempts = dao.get("email:attempts:user4@example.com").await.unwrap();
    assert_eq!(attempts, Some("1".to_string()));
    service
        .verify_code("user4@example.com", "wrong2")
        .await
        .unwrap_err();
    let attempts = dao.get("email:attempts:user4@example.com").await.unwrap();
    assert_eq!(attempts, Some("2".to_string()));
}

/// 测试 7:验证码不存在返回 EmailCodeNotFound。
#[tokio::test]
async fn missing_code_returns_not_found() {
    let service = make_service();
    let result = service.verify_code("user5@example.com", "123456").await;
    assert!(
        matches!(result, Err(GarrisonError::EmailCodeNotFound)),
        "不存在的验证码应返回 EmailCodeNotFound,实际: {:?}",
        result
    );
}

/// 测试 8:限速账本 key 格式验证(quota:hour:email:{addr})。
#[tokio::test]
async fn rate_key_format_hour() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
    let service = make_service_with(dao.clone(), 3, 3);
    service.send_code("user6@example.com").await.unwrap();
    // 账本模型:小时窗 key 形如 quota:hour:email:{addr}(无时间桶成分)
    let value = dao.get("quota:hour:email:user6@example.com").await.unwrap();
    assert!(
        value.is_some(),
        "应存在 quota:hour:email:{{addr}} 格式的限速账本 key"
    );
}

/// 测试 9:验证码 key 使用规范化地址(email:code:{addr})。
#[tokio::test]
async fn code_key_format_is_normalized() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
    let service = make_service_with(dao.clone(), 3, 3);
    service.send_code("User7@Example.COM").await.unwrap();
    let stored = dao.get("email:code:user7@example.com").await.unwrap();
    assert!(stored.is_some(), "应存在小写规范化 email:code:{{addr}} key");
}

/// 测试 10:并发发送不超限(MockDao 原子 incr 保证)。
#[tokio::test(flavor = "multi_thread")]
async fn concurrent_send_does_not_exceed_limit() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
    let rate_limiter = EmailRateLimiter::new(dao.clone(), 5, 10);
    let service = Arc::new(EmailVerificationService::new(
        rate_limiter,
        Arc::new(NoopEmailSender),
        dao.clone(),
        3,
        100,
        600,
    ));
    let mut handles = Vec::new();
    for _ in 0..10 {
        let s = service.clone();
        handles.push(tokio::spawn(async move {
            s.send_code("user8@example.com").await
        }));
    }
    let mut success = 0;
    let mut rate_limited = 0;
    for handle in handles {
        match handle.await.unwrap() {
            Ok(()) => success += 1,
            Err(GarrisonError::EmailRateLimitExceeded { .. }) => rate_limited += 1,
            Err(e) => panic!("不应返回其他错误: {:?}", e),
        }
    }
    assert_eq!(success, 5, "仅 5 次发送应成功(小时限速 5/h)");
    assert_eq!(rate_limited, 5, "其余 5 次应被限速");
}

/// 测试 11:异常发送检测(连续未验证超过阈值后回收通道)。
#[tokio::test]
async fn unverified_threshold_recycles_channel() {
    let service = make_service_with(Arc::new(MockDao::new()), 3, 3);
    for i in 0..3 {
        let r = service.send_code("user9@example.com").await;
        assert!(r.is_ok(), "第 {} 次发送应成功", i + 1);
    }
    let result = service.send_code("user9@example.com").await;
    assert!(
        matches!(result, Err(GarrisonError::EmailChannelRecycled)),
        "第 4 次发送应触发 EmailChannelRecycled,实际: {:?}",
        result
    );
    let result = service.send_code("user9@example.com").await;
    assert!(
        matches!(result, Err(GarrisonError::EmailChannelRecycled)),
        "通道回收后应继续返回 EmailChannelRecycled"
    );
}

/// 测试 12(email 特有):发送失败回滚全部状态——验证码删除、限速计数回退、未验证计数回退,错误原样透传。
#[tokio::test]
async fn send_failure_rolls_back_all_state() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
    let service = EmailVerificationService::new(
        EmailRateLimiter::new(dao.clone(), 5, 10),
        Arc::new(FailingEmailSender),
        dao.clone(),
        3,
        100,
        600,
    );
    let result = service.send_code("user10@example.com").await;
    assert!(
        matches!(&result, Err(GarrisonError::Network(msg)) if msg.contains("email-smtp-send-failed")),
        "发送失败应透传 Network 错误,实际: {:?}",
        result
    );
    assert!(
        dao.get("email:code:user10@example.com")
            .await
            .unwrap()
            .is_none(),
        "发送失败后验证码应被删除"
    );
    assert!(
        dao.get("quota:hour:email:user10@example.com")
            .await
            .unwrap()
            .is_none(),
        "发送失败后小时限速账本应回滚删除"
    );
    assert!(
        dao.get("quota:day:email:user10@example.com")
            .await
            .unwrap()
            .is_none(),
        "发送失败后天限速账本应回滚删除"
    );
    assert!(
        dao.get("email:unverified:user10@example.com")
            .await
            .unwrap()
            .is_none(),
        "发送失败后未验证计数应回滚删除"
    );
}

/// 测试 13(email 特有):大小写变体共享同一限速预算与验证码。
#[tokio::test]
async fn case_variants_share_rate_budget() {
    let service = make_service();
    let variants = [
        "User@Example.COM",
        "USER@example.com",
        "user@example.com",
        "User@example.com",
        "USER@EXAMPLE.COM",
    ];
    for (i, v) in variants.iter().enumerate() {
        let r = service.send_code(v).await;
        assert!(r.is_ok(), "变体 {} 第 {} 次发送应成功: {:?}", v, i + 1, r);
    }
    // 第 6 个变体(同一规范化地址)应被小时限速拦截
    let result = service.send_code("user@Example.com").await;
    assert!(
        matches!(result, Err(GarrisonError::EmailRateLimitExceeded { ref window }) if window == "hourly"),
        "大小写变体应共享限速预算:第 6 次应被拦截,实际: {:?}",
        result
    );
}

/// 测试 14:邮箱长度边界——254 放行、255 拒绝(RFC 5321 上限)。
#[test]
fn validate_email_boundary_254() {
    let ok = format!("{}@b.com", "a".repeat(248));
    assert_eq!(ok.len(), 254);
    assert!(validate_email(&ok).is_ok(), "恰好 254 字符应放行");
    let too_long = format!("{}@b.com", "a".repeat(249));
    assert_eq!(too_long.len(), 255);
    assert!(validate_email(&too_long).is_err(), "255 字符应拒绝");
}

/// 测试 15:回滚入口对非法邮箱前置校验(key 注入防护)。
#[tokio::test]
async fn rollback_invalid_email_returns_invalid_param() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
    let limiter = EmailRateLimiter::new(dao, 100, 100);
    let result = limiter.rollback("a:b@c.com").await;
    assert!(
        matches!(&result, Err(GarrisonError::InvalidParam(msg)) if msg.starts_with("secure-email-no-colon")),
        "回滚含冒号邮箱应返回 InvalidParam(secure-email-no-colon),实际: {:?}",
        result
    );
}

/// 测试 16:限速入口对规范化后为空的邮箱前置校验。
#[tokio::test]
async fn check_and_increment_rejects_blank_email() {
    let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
    let limiter = EmailRateLimiter::new(dao, 100, 100);
    let result = limiter.check_and_increment("   ").await;
    assert!(
        matches!(&result, Err(GarrisonError::InvalidParam(msg)) if msg.starts_with("secure-email-empty")),
        "空白邮箱应返回 InvalidParam(secure-email-empty),实际: {:?}",
        result
    );
}