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
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
// Copyright (c) 2026 Kirky.X🌠
// SPDX-License-Identifier: Apache-2.0

//! SSO Server 独立抽象模块(`protocol-sso-server` feature):与 `SsoClient` 解耦,经共享 `GarrisonDao` 间接通信。
//!
//! 提供 `SsoServer` / `CenterIdConverter` / `SsoChannel` trait,以及 `DefaultSsoServer` / `IdentityCenterIdConverter` / `NoopSsoChannel` 默认实现。

use crate::dao::GarrisonDao;
use crate::error::{GarrisonError, GarrisonResult};
use async_trait::async_trait;
use std::sync::Arc;
use uuid::Uuid;

// 复用 `sso::client` 的签名函数与 `sso::mod.rs` 的 `SsoTicketData`,避免格式漂移与签名逻辑重复。
use super::client::{sign_ticket, verify_ticket_signature, MIN_SECRET_LEN};
use super::SsoTicketData;

/// SSO ticket 默认 TTL(秒),与 `SsoClient` 保持一致。
const DEFAULT_TICKET_TTL: u64 = 60;

// SSO pub/sub 消息信封(事件认证 + 防重放)

/// SSO pub/sub 消息信封:HMAC-SHA256 认证 + 单调 seq 防重放。
///
/// [`SsoServer::push_message`] 发布侧把业务消息封装为本信封(JSON 序列化后经 `SsoChannel` 发布);订阅侧经 [`verify_sso_message`] 验签后取回 payload。
///
/// # 消费契约
///
/// - `hmac` = base64(HMAC-SHA256(secret, seq(be 字节) || payload)),secret 为票据签名密钥(发布/订阅两侧共享);
/// - `seq` 发布实例内单调递增(AtomicU64),订阅方以 `&mut u64` 维护「已见最大 seq」,`seq <= last_seq` 即判重放拒绝;
/// - **跨实例部署**:各实例 seq 独立计数,订阅方须按(topic × 发布实例)维度维护 last_seq,或以共享单调源扩展。
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct SsoMessageEnvelope {
    /// 业务消息原文。
    pub payload: String,
    /// HMAC-SHA256(base64),覆盖 `seq` 与 `payload`。
    pub hmac: String,
    /// 发布序号(发布实例内单调递增),防重放。
    pub seq: u64,
}

type HmacSha256 = hmac::Hmac<sha2::Sha256>;

/// 计算信封 HMAC(base64):HMAC-SHA256(secret, seq.to_be_bytes() || payload)。
fn sso_message_hmac(secret: &str, payload: &str, seq: u64) -> GarrisonResult<String> {
    use base64::Engine as _;
    use hmac::{KeyInit, Mac};
    let mut mac = HmacSha256::new_from_slice(secret.as_bytes())
        .map_err(|e| GarrisonError::Internal(format!("sso-message-hmac-init::{}", e)))?;
    mac.update(&seq.to_be_bytes());
    mac.update(payload.as_bytes());
    use base64::engine::general_purpose::STANDARD as BASE64_STANDARD;
    Ok(BASE64_STANDARD.encode(mac.finalize().into_bytes()))
}

/// 发布侧:将业务消息封装为 HMAC 信封(JSON 字符串,供 `SsoChannel::push` 发布)。
///
/// `seq` 由调用方保证在发布实例内单调递增(`DefaultSsoServer` 内置 AtomicU64)。
pub fn seal_sso_message(secret: &str, payload: &str, seq: u64) -> GarrisonResult<String> {
    let hmac = sso_message_hmac(secret, payload, seq)?;
    serde_json::to_string(&SsoMessageEnvelope {
        payload: payload.to_string(),
        hmac,
        seq,
    })
    .map_err(|e| GarrisonError::Internal(format!("sso-message-envelope-serialize::{}", e)))
}

/// 订阅侧验签助手:校验 HMAC 信封并返回业务消息 payload。
///
/// - 信封格式非法 / HMAC 不匹配 / `seq <= *last_seq`(重放)均返回 Err(fail-closed);
/// - 验签通过后推进 `*last_seq`(订阅方按 topic × 发布实例 维护该状态)。
pub fn verify_sso_message(secret: &str, raw: &str, last_seq: &mut u64) -> GarrisonResult<String> {
    use base64::Engine as _;
    use hmac::{KeyInit, Mac};
    let envelope: SsoMessageEnvelope = serde_json::from_str(raw)
        .map_err(|_| GarrisonError::InvalidToken("sso-message-envelope-format::".to_string()))?;
    // 常量时间比较(与 ticket 验签一致):先重算 HMAC 再 verify_slice
    let mut mac = HmacSha256::new_from_slice(secret.as_bytes())
        .map_err(|e| GarrisonError::Internal(format!("sso-message-hmac-init::{}", e)))?;
    mac.update(&envelope.seq.to_be_bytes());
    mac.update(envelope.payload.as_bytes());
    let sig_bytes = base64::engine::general_purpose::STANDARD
        .decode(&envelope.hmac)
        .map_err(|_| GarrisonError::InvalidToken("sso-message-hmac-verify::".to_string()))?;
    mac.verify_slice(&sig_bytes)
        .map_err(|_| GarrisonError::InvalidToken("sso-message-hmac-verify::".to_string()))?;
    if envelope.seq <= *last_seq {
        return Err(GarrisonError::InvalidToken(format!(
            "sso-message-seq-replay::seq={}::last_seq={}",
            envelope.seq, *last_seq
        )));
    }
    *last_seq = envelope.seq;
    Ok(envelope.payload)
}

// Trait 定义

/// SSO 服务端抽象 trait:与 `SsoClient` 解耦,经共享 `GarrisonDao` 间接通信;ticket 一次性使用,校验成功后立即销毁。
#[async_trait]
pub trait SsoServer: Send + Sync {
    /// 签发 SSO ticket:`login_id` 先经 `CenterIdConverter::to_center_id` 转换后存储。
    async fn issue_ticket(&self, login_id: &str, client_id: i64) -> GarrisonResult<String>;

    /// 校验 SSO ticket(一次性使用,成功后立即销毁):经 `get_and_delete` 原子消费;票据不存在/已过期/client_id 不匹配返回 `GarrisonError::InvalidToken`。
    async fn validate_ticket(&self, ticket: &str, client_id: i64) -> GarrisonResult<String>;

    /// 销毁 SSO ticket(幂等,即使票据不存在也返回 `Ok(())`)。
    async fn destroy_ticket(&self, ticket: &str) -> GarrisonResult<()>;

    /// 推送 SSO 消息到指定 login_id(未注入 `SsoChannel` 时 noop 返回 `Ok(())`)。
    ///
    /// topic 为 `sso:user:{sha256(login_id)[..32hex]}`(确定性指纹脱敏,防邮箱/手机号等 PII 泄漏到 topic/日志),订阅方按同一规则拼接。
    ///
    /// # 消息认证契约
    ///
    /// 发布侧把 `message` 封装为 HMAC-SHA256 信封([`SsoMessageEnvelope`]:`{payload, hmac, seq}`,seq 单调防重放)后发布;
    /// 订阅侧必须经 [`verify_sso_message`] 验签消费——pub/sub 通道对任意订阅者/发布者开放,无传输层认证。
    async fn push_message(&self, login_id: &str, message: &str) -> GarrisonResult<()>;
}

/// 中心 ID 转换器:多子系统 login_id 双向映射。
pub trait CenterIdConverter: Send + Sync {
    /// 将 login_id 转换为 center_id。
    fn to_center_id(&self, login_id: &str) -> String;

    /// 将 center_id 转换回 login_id。
    fn to_login_id(&self, center_id: &str) -> String;
}

/// SSO 消息推送通道抽象,支持自定义实现(如 Redis pub/sub)。
#[async_trait]
pub trait SsoChannel: Send + Sync {
    /// 推送消息到指定 topic。
    async fn push(&self, topic: &str, message: &str) -> GarrisonResult<()>;

    /// 订阅指定 topic;`handler` 为消息回调(owned `String` 以满足 `'static` 要求)。
    async fn subscribe(
        &self,
        topic: &str,
        handler: Box<dyn Fn(String) + Send + Sync>,
    ) -> GarrisonResult<()>;
}

// 默认实现

/// identity 转换:`to_center_id` / `to_login_id` 均返回原始值。
pub struct IdentityCenterIdConverter;

impl CenterIdConverter for IdentityCenterIdConverter {
    fn to_center_id(&self, login_id: &str) -> String {
        login_id.to_string()
    }

    fn to_login_id(&self, center_id: &str) -> String {
        center_id.to_string()
    }
}

/// 空操作 `SsoChannel`:所有方法返回 `Ok(())`,不实际推送消息。
pub struct NoopSsoChannel;

#[async_trait]
impl SsoChannel for NoopSsoChannel {
    async fn push(&self, _topic: &str, _message: &str) -> GarrisonResult<()> {
        Ok(())
    }

    async fn subscribe(
        &self,
        _topic: &str,
        _handler: Box<dyn Fn(String) + Send + Sync>,
    ) -> GarrisonResult<()> {
        Ok(())
    }
}

/// 默认 `SsoServer` 实现:持有 `Arc<dyn GarrisonDao>`(票据存储)、可选 `SsoChannel`(未注入时 noop)与 `CenterIdConverter`。
pub struct DefaultSsoServer {
    /// DAO 抽象层,用于票据存储。
    dao: Arc<dyn GarrisonDao>,
    /// 票据 TTL(秒)。
    ticket_ttl_seconds: u64,
    /// 消息推送通道(可选,未注入时 noop)。
    channel: Option<Arc<dyn SsoChannel>>,
    /// 中心 ID 转换器。
    converter: Arc<dyn CenterIdConverter>,
    /// HMAC 签名密钥(与 `SsoClient` 格式一致,ticket 必签)。
    secret: String,
    /// pub/sub 消息发布序号(实例内单调递增,供信封防重放)。
    message_seq: std::sync::atomic::AtomicU64,
}

impl DefaultSsoServer {
    /// 创建 `DefaultSsoServer` 实例(默认 TTL 60 秒、noop channel、identity 转换器)。
    ///
    /// `secret` 不可为空且不少于 `MIN_SECRET_LEN`(32 字节),须与 `SsoClient` 一致;否则返回 `GarrisonError::InvalidParam`(不 panic)。
    pub fn new(dao: Arc<dyn GarrisonDao>, secret: impl Into<String>) -> GarrisonResult<Self> {
        let secret: String = secret.into();
        if secret.is_empty() {
            return Err(GarrisonError::InvalidParam(
                "sso-server-secret-empty::".to_string(),
            ));
        }
        if secret.len() < MIN_SECRET_LEN {
            return Err(GarrisonError::InvalidParam(format!(
                "sso-server-secret-too-short::len={}::min={}",
                secret.len(),
                MIN_SECRET_LEN
            )));
        }
        Ok(Self {
            dao,
            ticket_ttl_seconds: DEFAULT_TICKET_TTL,
            channel: None,
            converter: Arc::new(IdentityCenterIdConverter),
            secret,
            // 首条 seq 从 1 起:订阅方 last_seq 初始 0,0 <= 0 会被防重放检查误判为重放
            message_seq: std::sync::atomic::AtomicU64::new(1),
        })
    }

    /// 设置票据 TTL(秒),默认 60 秒。
    pub fn with_ticket_ttl(mut self, ttl_seconds: u64) -> Self {
        self.ticket_ttl_seconds = ttl_seconds;
        self
    }

    /// 注入消息推送通道。
    pub fn with_channel(mut self, channel: Arc<dyn SsoChannel>) -> Self {
        self.channel = Some(channel);
        self
    }

    /// 注入中心 ID 转换器。
    pub fn with_converter(mut self, converter: Arc<dyn CenterIdConverter>) -> Self {
        self.converter = converter;
        self
    }
}

#[async_trait]
impl SsoServer for DefaultSsoServer {
    async fn issue_ticket(&self, login_id: &str, client_id: i64) -> GarrisonResult<String> {
        let center_id = self.converter.to_center_id(login_id);
        // 拼接两个 UUID v4 simple(各 32 hex = 64 字符),与 SsoClient 格式一致
        let random_part = format!("{}{}", Uuid::new_v4().simple(), Uuid::new_v4().simple());
        // 对 ticket 签名,防止 DAO 攻破后伪造
        let sig = sign_ticket(&self.secret, &random_part)?;
        let ticket = format!("{}.{}", random_part, sig);
        let data = SsoTicketData {
            login_id: center_id,
            client_id,
        };
        let value = serde_json::to_string(&data)
            .map_err(|e| GarrisonError::Internal(format!("sso-ticket-serialize::{}", e)))?;
        let key = format!("garrison:sso:ticket:{}", ticket);
        self.dao.set(&key, &value, self.ticket_ttl_seconds).await?;
        Ok(ticket)
    }

    async fn validate_ticket(&self, ticket: &str, client_id: i64) -> GarrisonResult<String> {
        // 先验签,防止 DAO 攻破后伪造 ticket
        let _random_part = verify_ticket_signature(&self.secret, ticket)?;

        let key = format!("garrison:sso:ticket:{}", ticket);
        // 非原子 get 校验 client_id:不匹配时不消费票据,允许正确 client_id 重试(与 `SsoClient` 行为对齐)
        let value = self
            .dao
            .get(&key)
            .await
            .map_err(|e| GarrisonError::Dao(format!("sso-ticket-read::{}", e)))?;
        let value = value.ok_or_else(|| {
            GarrisonError::InvalidToken("sso-ticket-missing-or-expired::".to_string())
        })?;
        let data: SsoTicketData = serde_json::from_str(&value)
            .map_err(|e| GarrisonError::Internal(format!("sso-ticket-deserialize::{}", e)))?;
        if data.client_id != client_id {
            // 错误消息固定,不回显存储/调用方 client_id(防枚举有效 client_id)
            return Err(GarrisonError::InvalidToken(
                "sso-ticket-client-id-mismatch::".to_string(),
            ));
        }
        // 原子消费票据消除 TOCTOU 竞态
        let consumed = self
            .dao
            .get_and_delete(&key)
            .await
            .map_err(|e| GarrisonError::Dao(format!("sso-ticket-atomic-consume::{}", e)))?;
        if consumed.is_none() {
            return Err(GarrisonError::InvalidToken(
                "sso-ticket-consumed-by-concurrent::".to_string(),
            ));
        }
        let login_id = self.converter.to_login_id(&data.login_id);
        Ok(login_id)
    }

    async fn destroy_ticket(&self, ticket: &str) -> GarrisonResult<()> {
        let key = format!("garrison:sso:ticket:{}", ticket);
        self.dao.delete(&key).await
    }

    async fn push_message(&self, login_id: &str, message: &str) -> GarrisonResult<()> {
        if let Some(channel) = &self.channel {
            // PII 防护:login_id(可能为邮箱/手机号)改用 SHA-256 指纹(截断 32 hex)作 topic,
            // 防泄漏到 Redis topic / 监控面板 / broker 元数据;订阅方按同一规则拼接
            let topic = format!("sso:user:{}", fingerprint_id(login_id));
            // 发布侧 HMAC 信封(seq 实例内单调递增),订阅侧经 verify_sso_message 验签消费
            let seq = self
                .message_seq
                .fetch_add(1, std::sync::atomic::Ordering::Relaxed);
            let envelope = seal_sso_message(&self.secret, message, seq)?;
            channel.push(&topic, &envelope).await?;
        }
        Ok(())
    }
}

/// 标识符确定性指纹(SHA-256 截断 32 hex,小写):同输入恒同输出,但不暴露原始标识符(邮箱/手机号等 PII),用于 pub/sub topic 等可能进入日志/监控的场景。
fn fingerprint_id(id: &str) -> String {
    use sha2::{Digest, Sha256};
    let digest = Sha256::digest(id.as_bytes());
    digest[..16]
        .iter()
        .map(|b| format!("{:02x}", b))
        .collect::<String>()
}

#[cfg(feature = "protocol-zeroize")]
impl Drop for DefaultSsoServer {
    fn drop(&mut self) {
        use zeroize::Zeroize;
        self.secret.zeroize();
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::dao::tests::MockDao;
    use crate::protocol::sso::SsoClient;
    use std::sync::atomic::{AtomicUsize, Ordering};

    // 构造测试

    /// 构造 DefaultSsoServer(持有 dao)。
    #[test]
    fn new_creates_server_with_dao() {
        let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
        let _server = DefaultSsoServer::new(dao, "test-sso-secret-key-for-unit-tests-01")
            .expect("secret 非空构造应成功");
        // 构造成功即验证(dao 通过类型系统保证非空)
    }

    /// with_ticket_ttl / with_channel / with_converter 链式构造。
    #[test]
    fn builder_chain_sets_fields() {
        let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
        let server = DefaultSsoServer::new(dao, "test-sso-secret-key-for-unit-tests-01")
            .expect("secret 非空构造应成功")
            .with_ticket_ttl(120)
            .with_channel(Arc::new(NoopSsoChannel))
            .with_converter(Arc::new(IdentityCenterIdConverter));
        assert_eq!(server.ticket_ttl_seconds, 120);
        assert!(server.channel.is_some());
    }

    // CenterIdConverter 测试

    /// IdentityCenterIdConverter 默认实现往返一致。
    #[test]
    fn identity_converter_roundtrip() {
        let converter = IdentityCenterIdConverter;
        let center_id = converter.to_center_id("1001");
        let login_id = converter.to_login_id(&center_id);
        assert_eq!(login_id, "1001");
        assert_eq!(center_id, "1001");
    }

    /// 自定义 CenterIdConverter 实现(login_id 加前缀 c- 作为 center_id)。
    #[test]
    fn custom_converter_roundtrip() {
        struct OffsetConverter;
        impl CenterIdConverter for OffsetConverter {
            fn to_center_id(&self, login_id: &str) -> String {
                format!("c-{}", login_id)
            }
            fn to_login_id(&self, center_id: &str) -> String {
                center_id
                    .strip_prefix("c-")
                    .unwrap_or(center_id)
                    .to_string()
            }
        }
        let converter = OffsetConverter;
        let center_id = converter.to_center_id("1001");
        assert_eq!(center_id, "c-1001");
        let login_id = converter.to_login_id(&center_id);
        assert_eq!(login_id, "1001");
    }

    // NoopSsoChannel 测试

    #[tokio::test]
    async fn noop_channel_push_returns_ok() {
        let channel = NoopSsoChannel;
        let result = channel.push("topic", "msg").await;
        assert_eq!(result.unwrap(), (), "NoopSsoChannel::push 应返回 Ok(())");
    }

    #[tokio::test]
    async fn noop_channel_subscribe_returns_ok() {
        let channel = NoopSsoChannel;
        let handler: Box<dyn Fn(String) + Send + Sync> = Box::new(|_msg: String| {});
        let result = channel.subscribe("topic", handler).await;
        assert_eq!(
            result.unwrap(),
            (),
            "NoopSsoChannel::subscribe 应返回 Ok(())"
        );
    }

    // DefaultSsoServer::issue_ticket + validate_ticket 测试

    /// issue_ticket + validate_ticket 往返(一次性使用)。
    #[tokio::test]
    async fn issue_and_validate_ticket_roundtrip() {
        let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
        let server = DefaultSsoServer::new(dao, "test-sso-secret-key-for-unit-tests-01")
            .expect("secret 非空构造应成功");
        let ticket = server.issue_ticket("1001", 2001).await.unwrap();
        let login_id = server.validate_ticket(&ticket, 2001).await.unwrap();
        assert_eq!(login_id, "1001");
    }

    /// ticket 格式 `{64_hex_random}.{hmac_b64}`:random 部分为 64 字符 hex。
    #[tokio::test]
    async fn issue_ticket_returns_64_chars() {
        let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
        let server = DefaultSsoServer::new(dao, "test-sso-secret-key-for-unit-tests-01")
            .expect("secret 非空构造应成功");
        let ticket = server.issue_ticket("1001", 2001).await.unwrap();
        let parts: Vec<&str> = ticket.splitn(2, '.').collect();
        assert_eq!(parts.len(), 2, "ticket 应包含分隔符 '.'");
        assert_eq!(parts[0].len(), 64, "random 部分应为 64 字符 hex");
        assert!(parts[0].chars().all(|c| c.is_ascii_hexdigit()));
    }

    #[tokio::test]
    async fn validate_ticket_one_time_use_second_fails() {
        let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
        let server = DefaultSsoServer::new(dao, "test-sso-secret-key-for-unit-tests-01")
            .expect("secret 非空构造应成功");
        let ticket = server.issue_ticket("1001", 2001).await.unwrap();
        let first = server.validate_ticket(&ticket, 2001).await;
        let second = server.validate_ticket(&ticket, 2001).await;
        assert_eq!(first.unwrap(), "1001", "第一次校验应返回 login_id");
        assert!(
            matches!(second, Err(GarrisonError::InvalidToken(_))),
            "第二次校验应返回 InvalidToken"
        );
    }

    #[tokio::test]
    async fn validate_ticket_client_id_mismatch_returns_error() {
        let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
        let server = DefaultSsoServer::new(dao, "test-sso-secret-key-for-unit-tests-01")
            .expect("secret 非空构造应成功");
        let ticket = server.issue_ticket("1001", 2001).await.unwrap();
        let result = server.validate_ticket(&ticket, 9999).await;
        assert!(result.is_err());
        match result.err() {
            Some(GarrisonError::InvalidToken(_)) => {},
            other => panic!("期望 InvalidToken 错误,实际: {:?}", other),
        }
    }

    #[tokio::test]
    async fn validate_ticket_nonexistent_returns_error() {
        let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
        let server = DefaultSsoServer::new(dao, "test-sso-secret-key-for-unit-tests-01")
            .expect("secret 非空构造应成功");
        let result = server.validate_ticket("nonexistent-ticket", 2001).await;
        assert!(result.is_err());
        match result.err() {
            Some(GarrisonError::InvalidToken(_)) => {},
            other => panic!("期望 InvalidToken 错误,实际: {:?}", other),
        }
    }

    // destroy_ticket 测试

    #[tokio::test]
    async fn destroy_ticket_idempotent() {
        let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
        let server = DefaultSsoServer::new(dao, "test-sso-secret-key-for-unit-tests-01")
            .expect("secret 非空构造应成功");
        let result = server.destroy_ticket("nonexistent-ticket").await;
        assert_eq!(result.unwrap(), (), "销毁不存在的票据应返回 Ok(())(幂等)");
        let ticket = server.issue_ticket("1001", 2001).await.unwrap();
        let result1 = server.destroy_ticket(&ticket).await;
        let result2 = server.destroy_ticket(&ticket).await;
        assert_eq!(result1.unwrap(), (), "销毁存在的票据应返回 Ok(())");
        assert_eq!(result2.unwrap(), (), "重复销毁应返回 Ok(())(幂等)");
    }

    // 自定义 CenterIdConverter 集成测试

    /// 注入自定义 CenterIdConverter 后,issue_ticket 存储 center_id,validate_ticket 返回原始 login_id。
    #[tokio::test]
    async fn custom_converter_issue_validate_roundtrip() {
        struct OffsetConverter;
        impl CenterIdConverter for OffsetConverter {
            fn to_center_id(&self, login_id: &str) -> String {
                format!("c-{}", login_id)
            }
            fn to_login_id(&self, center_id: &str) -> String {
                center_id
                    .strip_prefix("c-")
                    .unwrap_or(center_id)
                    .to_string()
            }
        }
        let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
        let server = DefaultSsoServer::new(dao, "test-sso-secret-key-for-unit-tests-01")
            .expect("secret 非空构造应成功")
            .with_converter(Arc::new(OffsetConverter));
        let ticket = server.issue_ticket("1001", 2001).await.unwrap();
        let login_id = server.validate_ticket(&ticket, 2001).await.unwrap();
        // 往返一致:返回原始 login_id(而非 center_id)
        assert_eq!(login_id, "1001");
    }

    // push_message 测试

    /// push_message 未注入 channel 时返回 Ok(noop)。
    #[tokio::test]
    async fn push_message_noop_when_no_channel() {
        let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
        let server = DefaultSsoServer::new(dao, "test-sso-secret-key-for-unit-tests-01")
            .expect("secret 非空构造应成功");
        let result = server.push_message("1001", "hello").await;
        assert_eq!(
            result.unwrap(),
            (),
            "未注入 channel 时 push_message 应返回 Ok(())(noop)"
        );
    }

    /// push_message 注入 channel 后委托 channel.push。
    #[tokio::test]
    async fn push_message_delegates_to_channel() {
        /// 计数器 channel,记录 push 调用次数。
        struct CountingChannel {
            count: AtomicUsize,
        }
        #[async_trait]
        impl SsoChannel for CountingChannel {
            async fn push(&self, _topic: &str, _message: &str) -> GarrisonResult<()> {
                self.count.fetch_add(1, Ordering::SeqCst);
                Ok(())
            }
            async fn subscribe(
                &self,
                _topic: &str,
                _handler: Box<dyn Fn(String) + Send + Sync>,
            ) -> GarrisonResult<()> {
                Ok(())
            }
        }
        let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
        let channel = Arc::new(CountingChannel {
            count: AtomicUsize::new(0),
        });
        let server = DefaultSsoServer::new(dao, "test-sso-secret-key-for-unit-tests-01")
            .expect("secret 非空构造应成功")
            .with_channel(channel.clone());
        server.push_message("1001", "hello").await.unwrap();
        server.push_message("1002", "world").await.unwrap();
        assert_eq!(channel.count.load(Ordering::SeqCst), 2);
    }

    /// push_message 的 topic 用 SHA-256 指纹而非原始 login_id(PII 脱敏),且确定性(同输入同 topic、不同输入不同 topic)。
    #[tokio::test]
    async fn push_message_topic_masks_login_id() {
        /// 捕获 push topic 的 channel。
        struct TopicCapturingChannel {
            topics: std::sync::Mutex<Vec<String>>,
        }
        #[async_trait]
        impl SsoChannel for TopicCapturingChannel {
            async fn push(&self, topic: &str, _message: &str) -> GarrisonResult<()> {
                self.topics.lock().unwrap().push(topic.to_string());
                Ok(())
            }
            async fn subscribe(
                &self,
                _topic: &str,
                _handler: Box<dyn Fn(String) + Send + Sync>,
            ) -> GarrisonResult<()> {
                Ok(())
            }
        }
        let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
        let channel = Arc::new(TopicCapturingChannel {
            topics: std::sync::Mutex::new(Vec::new()),
        });
        let server = DefaultSsoServer::new(dao, "test-sso-secret-key-for-unit-tests-01")
            .expect("secret 非空构造应成功")
            .with_channel(channel.clone());

        // login_id 含 PII 形式(邮箱)
        server.push_message("user@example.com", "m1").await.unwrap();
        server.push_message("user@example.com", "m2").await.unwrap();
        server.push_message("13800138000", "m3").await.unwrap();

        let topics = channel.topics.lock().unwrap();
        assert_eq!(topics.len(), 3);
        for t in topics.iter() {
            assert!(
                t.starts_with("sso:user:"),
                "topic 应保留 sso:user: 前缀,实际: {}",
                t
            );
            assert!(
                !t.contains("user@example.com") && !t.contains("13800138000"),
                "topic 不得包含原始 login_id(PII),实际: {}",
                t
            );
        }
        assert_eq!(topics[0], topics[1], "同 login_id 应映射到相同 topic");
        assert_ne!(topics[0], topics[2], "不同 login_id 应映射到不同 topic");
    }

    /// 空 secret 构造返回 InvalidParam 而非 panic。
    #[test]
    fn new_rejects_empty_secret_with_invalid_param() {
        let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
        let result = DefaultSsoServer::new(dao, "");
        match result {
            Err(GarrisonError::InvalidParam(msg)) => {
                assert!(
                    msg.contains("sso-server-secret-empty"),
                    "错误消息应含 sso-server-secret-empty 前缀,实际: {}",
                    msg
                );
            },
            Err(other) => panic!("期望 InvalidParam,实际: {:?}", other),
            Ok(_) => panic!("空 secret 不应构造成功"),
        }
    }

    /// 短于 32 字节的 secret 返回 InvalidParam(与 qrlogin/protocol-sign 下限对齐,弱密钥可被持票攻击者离线爆破后伪造签名)。
    #[test]
    fn new_rejects_short_secret_with_invalid_param() {
        let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
        let result = DefaultSsoServer::new(dao, "a".repeat(31));
        match result {
            Err(GarrisonError::InvalidParam(msg)) => {
                assert!(
                    msg.contains("sso-server-secret-too-short"),
                    "错误消息应含 sso-server-secret-too-short 前缀,实际: {}",
                    msg
                );
            },
            Err(other) => panic!("期望 InvalidParam,实际: {:?}", other),
            Ok(_) => panic!("31 字节 secret 不应构造成功"),
        }
        let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
        assert!(
            DefaultSsoServer::new(dao, "a".repeat(32)).is_ok(),
            "32 字节 secret 应构造成功"
        );
    }

    // pub/sub 消息信封(HMAC 认证 + seq 防重放)

    /// 捕获 push 消息体的 channel(信封测试用)。
    struct MessageCapturingChannel {
        messages: std::sync::Mutex<Vec<String>>,
    }
    #[async_trait]
    impl SsoChannel for MessageCapturingChannel {
        async fn push(&self, _topic: &str, message: &str) -> GarrisonResult<()> {
            self.messages.lock().unwrap().push(message.to_string());
            Ok(())
        }
        async fn subscribe(
            &self,
            _topic: &str,
            _handler: Box<dyn Fn(String) + Send + Sync>,
        ) -> GarrisonResult<()> {
            Ok(())
        }
    }

    /// push_message 发布侧封装 HMAC 信封:订阅侧 verify_sso_message 验签取回原始 payload,且 seq 随发布单调递增。
    #[tokio::test]
    async fn push_message_seals_hmac_envelope_and_verifies() {
        let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
        let channel = Arc::new(MessageCapturingChannel {
            messages: std::sync::Mutex::new(Vec::new()),
        });
        let server = DefaultSsoServer::new(dao, "test-sso-secret-key-for-unit-tests-01")
            .expect("secret 非空构造应成功")
            .with_channel(channel.clone());
        server.push_message("1001", "kickout-notify").await.unwrap();
        server.push_message("1001", "perm-changed").await.unwrap();

        let messages = channel.messages.lock().unwrap();
        assert_eq!(messages.len(), 2);
        let mut last_seq = 0u64;
        let payload1 = verify_sso_message(
            "test-sso-secret-key-for-unit-tests-01",
            &messages[0],
            &mut last_seq,
        )
        .expect("信封验签应通过");
        assert_eq!(payload1, "kickout-notify");
        let payload2 = verify_sso_message(
            "test-sso-secret-key-for-unit-tests-01",
            &messages[1],
            &mut last_seq,
        )
        .expect("第二封信封验签应通过");
        assert_eq!(payload2, "perm-changed");
        // seq 单调递增由 verify 的重放检查间接保证(第二次通过说明 seq2 > seq1)
    }

    /// 篡改 payload 的信封被拒绝(HMAC 不匹配,fail-closed)。
    #[tokio::test]
    async fn verify_sso_message_rejects_tampered_payload() {
        let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
        let channel = Arc::new(MessageCapturingChannel {
            messages: std::sync::Mutex::new(Vec::new()),
        });
        let server = DefaultSsoServer::new(dao, "test-sso-secret-key-for-unit-tests-01")
            .expect("secret 非空构造应成功")
            .with_channel(channel.clone());
        server.push_message("1001", "original").await.unwrap();

        let raw = channel.messages.lock().unwrap()[0].clone();
        let tampered = raw.replace("original", "forged");
        assert_ne!(tampered, raw);
        let mut last_seq = 0u64;
        let result = verify_sso_message(
            "test-sso-secret-key-for-unit-tests-01",
            &tampered,
            &mut last_seq,
        );
        match result {
            Err(GarrisonError::InvalidToken(msg)) => assert!(
                msg.contains("sso-message-hmac-verify"),
                "篡改 payload 应报 sso-message-hmac-verify,实际: {msg}"
            ),
            other => panic!("期望 InvalidToken,实际: {:?}", other),
        }
    }

    /// 重放旧 seq 的信封被拒绝(seq 单调防重放)。
    #[tokio::test]
    async fn verify_sso_message_rejects_replayed_seq() {
        let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
        let channel = Arc::new(MessageCapturingChannel {
            messages: std::sync::Mutex::new(Vec::new()),
        });
        let server = DefaultSsoServer::new(dao, "test-sso-secret-key-for-unit-tests-01")
            .expect("secret 非空构造应成功")
            .with_channel(channel.clone());
        server.push_message("1001", "m1").await.unwrap();
        server.push_message("1001", "m2").await.unwrap();

        let messages = channel.messages.lock().unwrap();
        let mut last_seq = 0u64;
        // 正常顺序:m1(seq0)→ m2(seq1)
        verify_sso_message(
            "test-sso-secret-key-for-unit-tests-01",
            &messages[0],
            &mut last_seq,
        )
        .unwrap();
        verify_sso_message(
            "test-sso-secret-key-for-unit-tests-01",
            &messages[1],
            &mut last_seq,
        )
        .unwrap();
        // 重放第一封(seq0 <= last_seq=1)→ 拒绝
        let replay = verify_sso_message(
            "test-sso-secret-key-for-unit-tests-01",
            &messages[0],
            &mut last_seq,
        );
        match replay {
            Err(GarrisonError::InvalidToken(msg)) => assert!(
                msg.contains("sso-message-seq-replay"),
                "重放旧 seq 应报 sso-message-seq-replay,实际: {msg}"
            ),
            other => panic!("期望 InvalidToken,实际: {:?}", other),
        }
        // 伪造的高 seq 信封同样被拒:先验签后查 seq,伪造 hmac 不可通过
        let forged = serde_json::json!({
            "payload": "forged",
            "hmac": "AAAA",
            "seq": 9999u64
        })
        .to_string();
        let forged_result = verify_sso_message(
            "test-sso-secret-key-for-unit-tests-01",
            &forged,
            &mut last_seq,
        );
        assert!(
            matches!(forged_result, Err(GarrisonError::InvalidToken(_))),
            "伪造信封应被拒绝"
        );
    }

    /// 非 JSON / 缺字段的消息体被拒绝(信封格式 fail-closed)。
    #[tokio::test]
    async fn verify_sso_message_rejects_malformed_envelope() {
        let mut last_seq = 0u64;
        let result = verify_sso_message(
            "test-sso-secret-key-for-unit-tests-01",
            "plain-message",
            &mut last_seq,
        );
        match result {
            Err(GarrisonError::InvalidToken(msg)) => assert!(
                msg.contains("sso-message-envelope-format"),
                "非信封消息应报 sso-message-envelope-format,实际: {msg}"
            ),
            other => panic!("期望 InvalidToken,实际: {:?}", other),
        }
    }

    // SsoServer 与 SsoClient 通过共享 GarrisonDao 间接通信

    /// SsoServer 签发的 ticket 可被 SsoClient 校验(共享 DAO)。
    #[tokio::test]
    async fn server_and_client_communicate_via_shared_dao() {
        let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
        let server = DefaultSsoServer::new(dao.clone(), "test-sso-secret-key-for-unit-tests-01")
            .expect("secret 非空构造应成功");
        let ticket = server.issue_ticket("1001", 2001).await.unwrap();
        let client = SsoClient::new(dao, "test-sso-secret-key-for-unit-tests-01")
            .expect("secret 非空构造应成功");
        let login_id = client.validate_ticket(&ticket, 2001).await.unwrap();
        assert_eq!(login_id, "1001");
    }

    /// SsoClient 签发的 ticket 可被 SsoServer 校验(共享 DAO,反向)。
    #[tokio::test]
    async fn client_and_server_communicate_via_shared_dao() {
        let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
        let client = SsoClient::new(dao.clone(), "test-sso-secret-key-for-unit-tests-01")
            .expect("secret 非空构造应成功");
        let ticket = client.issue_ticket("1001", 2001).await.unwrap();
        let server = DefaultSsoServer::new(dao, "test-sso-secret-key-for-unit-tests-01")
            .expect("secret 非空构造应成功");
        let login_id = server.validate_ticket(&ticket, 2001).await.unwrap();
        assert_eq!(login_id, "1001");
    }
}