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
//! 多租户隔离上下文。
//!
//! 提供 `TenantContext`(`tenant_id` + 来源标识)、`TenantSource`(Header / Subdomain / Claim)、
//! `TENANT` task_local(跨 async 调用传播)与 `TenantResolver` trait(三种实现)。
//!
//! 类型本身不依赖 `tenant-isolation` feature gate(关闭时仍可构造),仅 DAO key 前缀与
//! Repository SQL 过滤由 feature 控制。

use async_trait::async_trait;
use http::HeaderMap;
use std::collections::HashMap;

use crate::error::{GarrisonError, GarrisonResult};

/// 租户上下文来源标识,便于排障与审计。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TenantSource {
    /// 从 `X-Tenant-Id` 请求头提取。
    Header,
    /// 从 `Host` 头的子域名提取并查映射表。
    Subdomain,
    /// 从 `Authorization: Bearer <jwt>` 的 `tenant_id` claim 提取。
    Claim,
}

/// 租户上下文:携带 `tenant_id` 与解析来源,经 `TENANT` task_local 在 async 调用链中传播。
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TenantContext {
    /// 租户 ID(0 表示默认/全局租户,单租户部署使用)。
    pub tenant_id: i64,
    /// 解析来源(Header / Subdomain / Claim)。
    pub resolved_from: TenantSource,
}

/// 租户上下文 task_local:`TENANT.scope(ctx, future)` 进入上下文,`TENANT.get()` 取当前
/// `TenantContext`,`TENANT.try_get()` 在无上下文时返回 `Err`(不 panic)。
//
// `task_local!` 宏展开产生的项不接受 `///`(rustc unused_doc_comments)也不继承外部 `#[allow]`;
// 项目级 `#![warn(missing_docs)]` 在 clippy `-D warnings` 下升级为 deny,故把 `task_local!` 包在
// 内部 module 中并加 `#[allow(missing_docs)]`,文档说明放在 module 外上方。
#[allow(missing_docs)]
mod tenant_local {
    use super::TenantContext;

    tokio::task_local! {
        pub static TENANT: TenantContext;
    }
}

pub use tenant_local::TENANT;

/// 读取当前 task_local 中的 tenant_id(无上下文时返回 `None`,不 panic)。
///
/// 与 [`current_tenant_id_or_error`] 的差异:本函数把「无租户上下文」交给调用方显式处理,用于多租户
/// 严格隔离场景(审计日志写入应报错、缓存 key 前缀不应静默退化为 `tenant:0:`),避免隔离被静默绕过。
pub fn current_tenant_id_strict() -> Option<i64> {
    TENANT.try_get().ok().map(|ctx| ctx.tenant_id)
}

/// 读取当前 task_local 中的 tenant_id(无上下文时返回 `Err(Config)`,fail-closed)。
///
/// 与 [`current_tenant_id_strict`] 的差异:本函数强制返回错误,用于多租户严格隔离的权限校验
/// (`AuthRequest` 构造)与缓存 key 前缀生成,避免多租户环境下 `tenant_id=0` 命中默认租户数据、
/// 绕过租户隔离(失败显性化)。
pub fn current_tenant_id_or_error() -> GarrisonResult<i64> {
    current_tenant_id_strict()
        .ok_or_else(|| GarrisonError::Config("ctx-tenant-context-missing::".into()))
}

/// Token-Session `attrs` 中记录会话绑定租户的保留键。
///
/// - **绑定**:会话创建(`create_token_session_inner`)时若存在 `TENANT` task_local 上下文,则将该租户 ID
///   (十进制字符串)写入本 attr;无上下文不写(非多租户部署语义不变)。
/// - **校验**:`check_login` 在租户上下文存在**且**会话已绑定时比对一致性,不匹配即拒绝
///   (`stp-check-login-tenant-mismatch`);会话无绑定(旧会话 / 升级兼容)行为不变。
/// - **形态**:attr 值恒为 `i64::to_string()` 规范十进制,按字符串比较;`__` 前缀保留命名空间,业务方 attrs 不得占用。
pub const SESSION_TENANT_ATTR_KEY: &str = "__garrison_tenant_id";

/// 租户解析器 trait:从 HTTP 请求头解析 `TenantContext`。
///
/// 三种实现:`HeaderTenantResolver`(`X-Tenant-Id`)/ `SubdomainTenantResolver`(`Host` 子域名 + mapping)
/// / `ClaimTenantResolver`(`Authorization: Bearer <jwt>` 的 `tenant_id` claim)。
///
/// 接受框架无关的 `&HeaderMap`(actix / warp / axum 均基于 http crate);失败时返回 `GarrisonError`,
/// 不静默默认 0(失败显性化)。
#[async_trait]
pub trait TenantResolver: Send + Sync {
    /// 从请求头解析租户上下文;header 缺失 / 格式错误 / JWT 验证失败等均返回 `Err`。
    async fn resolve(&self, headers: &HeaderMap) -> GarrisonResult<TenantContext>;
}

/// Header 租户解析器:从 `X-Tenant-Id` 请求头提取 `tenant_id`(i64)。
///
/// header 缺失返回 `ctx-tenant-id-missing::`,非 i64 返回 `GarrisonError::Config`;不默认 0
/// (失败显性化),缺失即报错,避免租户隔离被静默绕过。
#[derive(Debug, Clone, Default)]
pub struct HeaderTenantResolver;

#[async_trait]
impl TenantResolver for HeaderTenantResolver {
    async fn resolve(&self, headers: &HeaderMap) -> GarrisonResult<TenantContext> {
        let value = headers
            .get("X-Tenant-Id")
            .ok_or_else(|| GarrisonError::Config("ctx-tenant-id-missing::".into()))?;
        let raw = value
            .to_str()
            .map_err(|e| GarrisonError::Config(format!("ctx-tenant-id-not-ascii::{e}")))?;
        let tenant_id = raw
            .parse::<i64>()
            .map_err(|e| GarrisonError::Config(format!("ctx-tenant-id-invalid::`{raw}`: {e}")))?;
        Ok(TenantContext {
            tenant_id,
            resolved_from: TenantSource::Header,
        })
    }
}

/// Subdomain 租户解析器:从 `Host` 请求头取第一段作为 subdomain,查 `mapping` 表得到 `tenant_id`。
///
/// Host 缺失返回 `ctx-host-missing::`,subdomain 未命中返回 `ctx-host-unknown-subdomain::`;
/// Host 含端口(如 `tenant42.example.com:8080`)先 strip port 再提取;不默认 0(失败显性化),
/// 未命中即报错,避免租户隔离被静默绕过。
#[derive(Debug, Clone, Default)]
pub struct SubdomainTenantResolver {
    /// subdomain → tenant_id 映射表(如 `{"tenant42": 42}`)。
    pub mapping: HashMap<String, i64>,
}

#[async_trait]
impl TenantResolver for SubdomainTenantResolver {
    async fn resolve(&self, headers: &HeaderMap) -> GarrisonResult<TenantContext> {
        let host = headers
            .get("Host")
            .ok_or_else(|| GarrisonError::Config("ctx-host-missing::".into()))?
            .to_str()
            .map_err(|e| GarrisonError::Config(format!("ctx-host-not-ascii::{e}")))?;
        // strip port: `tenant42.example.com:8080` → `tenant42.example.com`
        // IPv6 字面量(RFC 3986):`[::1]:8080` 先取方括号内地址,
        // 不能用 `split(':').next()`(会截断出 `[`,导致 IPv6 请求必然 unknown subdomain)。
        let hostname = if host.starts_with('[') {
            host.split_once(']')
                .map(|(inner, _)| inner)
                .filter(|s| !s.is_empty())
                .unwrap_or(host)
        } else {
            host.split(':').next().unwrap_or(host)
        };
        let subdomain = hostname.split('.').next().unwrap_or(hostname);
        if subdomain.is_empty() {
            return Err(GarrisonError::Config(format!(
                "ctx-host-empty-subdomain::{host}"
            )));
        }
        let tenant_id = *self.mapping.get(subdomain).ok_or_else(|| {
            GarrisonError::Config(format!("ctx-host-unknown-subdomain::{subdomain}"))
        })?;
        Ok(TenantContext {
            tenant_id,
            resolved_from: TenantSource::Subdomain,
        })
    }
}

/// Claim 租户解析器:从 `Authorization: Bearer <jwt>` 提取 JWT,验证签名(HS256)+ exp 后解码 `tenant_id` claim。
///
/// Authorization 缺失、非 Bearer scheme(大小写不敏感,RFC 7235)、签名验证失败、`tenant_id` claim 缺失
/// 均返回 `GarrisonError::InvalidToken`;配置了 `expected_issuers` / `expected_audiences` 时同时校验 `iss` / `aud`。
///
/// 门控在 `protocol-jwt` feature 下(依赖 `jsonwebtoken` crate),不默认 0(失败显性化)。**多租户安全建议**:
/// 多服务共享同一 HS256 secret 时必须经 `with_expected_issuers` 配置期望 `iss`,防其他服务签发的合法 JWT
/// 被跨服务重放;`aud` 同理(jsonwebtoken 对 token 带 `aud` 而本地未配置期望值时默认 fail-closed 拒绝)。
#[cfg(feature = "protocol-jwt")]
#[derive(Clone)]
pub struct ClaimTenantResolver {
    /// JWT 验签密钥(HS256)。
    ///
    /// 手动实现 `Debug`(非 derive):`{:?}` 输出时脱敏为 `<redacted>`,防止密钥经日志 / 调试输出明文泄露。
    pub jwt_secret: String,
    /// 可选:期望的 `iss`(issuer)claim 集合。非空时启用 issuer 校验(fail-closed)。
    pub expected_issuers: Vec<String>,
    /// 可选:期望的 `aud`(audience)claim 集合。非空时启用 audience 校验(fail-closed)。
    pub expected_audiences: Vec<String>,
}

#[cfg(feature = "protocol-jwt")]
impl std::fmt::Debug for ClaimTenantResolver {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("ClaimTenantResolver")
            .field("jwt_secret", &"<redacted>")
            .field("expected_issuers", &self.expected_issuers)
            .field("expected_audiences", &self.expected_audiences)
            .finish()
    }
}

#[cfg(feature = "protocol-jwt")]
impl ClaimTenantResolver {
    /// 构造 ClaimTenantResolver。
    pub fn new(jwt_secret: String) -> Self {
        Self {
            jwt_secret,
            expected_issuers: Vec::new(),
            expected_audiences: Vec::new(),
        }
    }

    /// 配置期望的 `iss`(issuer)claim 集合(builder 模式):非空时 token 的 `iss` 缺失或不匹配即拒绝;
    /// 多服务共享 secret 时建议配置,防跨服务 token 重放。
    pub fn with_expected_issuers(mut self, issuers: Vec<String>) -> Self {
        self.expected_issuers = issuers;
        self
    }

    /// 配置期望的 `aud`(audience)claim 集合(builder 模式):非空时 token 的 `aud` 缺失或不匹配即拒绝。
    pub fn with_expected_audiences(mut self, audiences: Vec<String>) -> Self {
        self.expected_audiences = audiences;
        self
    }
}

/// JWT claims 中仅提取 `tenant_id` 字段。
///
/// `exp` 由 `jsonwebtoken` 自动验证,这里只反序列化 `tenant_id`,缺失时 serde 报错转为 `InvalidToken`。
#[cfg(feature = "protocol-jwt")]
#[derive(serde::Deserialize)]
struct TenantClaims {
    tenant_id: i64,
}

#[cfg(feature = "protocol-jwt")]
#[async_trait]
impl TenantResolver for ClaimTenantResolver {
    async fn resolve(&self, headers: &HeaderMap) -> GarrisonResult<TenantContext> {
        use jsonwebtoken::{decode, Algorithm, DecodingKey, Validation};

        let auth = headers
            .get("Authorization")
            .ok_or_else(|| GarrisonError::InvalidToken("ctx-auth-header-missing::".into()))?
            .to_str()
            .map_err(|e| GarrisonError::InvalidToken(format!("ctx-auth-not-ascii::{e}")))?;
        // 解析 `<scheme> <token>`,scheme 大小写不敏感(RFC 7235)
        let mut parts = auth.splitn(2, ' ');
        let scheme = parts
            .next()
            .ok_or_else(|| GarrisonError::InvalidToken("ctx-auth-header-empty::".into()))?;
        let jwt = parts
            .next()
            .ok_or_else(|| GarrisonError::InvalidToken("ctx-auth-token-missing::".into()))?;
        if !scheme.eq_ignore_ascii_case("Bearer") {
            return Err(GarrisonError::InvalidToken(format!(
                "ctx-auth-scheme-unsupported::`{scheme}`"
            )));
        }
        let key = DecodingKey::from_secret(self.jwt_secret.as_bytes());
        let mut validation = Validation::new(Algorithm::HS256);
        validation.validate_exp = true;
        validation.leeway = 0;
        // 配置了期望 iss 才启用;启用后 token 的 iss 缺失或不匹配均拒绝(jsonwebtoken fail-closed)
        if !self.expected_issuers.is_empty() {
            validation.set_issuer(&self.expected_issuers);
        }
        // 配置了期望 aud 才显式设置白名单;未配置时保留库默认(token 不带 aud 可通过,
        // token 带 aud 而本地未配置期望值时拒绝,fail-closed)
        if !self.expected_audiences.is_empty() {
            validation.set_audience(&self.expected_audiences);
        }
        let data = decode::<TenantClaims>(jwt, &key, &validation).map_err(|e| {
            GarrisonError::InvalidToken(format!("ctx-tenant-jwt-verify-failed::{e}"))
        })?;
        Ok(TenantContext {
            tenant_id: data.claims.tenant_id,
            resolved_from: TenantSource::Claim,
        })
    }
}

// 测试专用 helper(测试桩显式设置 TENANT scope,避免 fail-closed 误触发)

/// 测试专用:用默认 `TenantContext { tenant_id: 0, resolved_from: Header }` 包裹 future。
///
/// `tenant-isolation` feature 启用时 `GarrisonLogicDefault::check_permission` 会调用
/// `current_tenant_id_or_error()`(fail-closed);permission 测试验证的是权限逻辑而非 tenant 隔离
/// (隔离另有专门测试),故显式设置默认 TENANT scope 作为测试桩,而非在生产代码里用 `unwrap_or(0)`
/// 规避(失败必须显性化)。
///
/// # 使用
///
/// ```ignore
/// #[tokio::test]
/// async fn my_permission_test() {
/// with_default_tenant(async {
/// // 此处调用 check_permission / has_permission / handler
/// }).await;
/// }
/// ```
///
/// # 门控
///
/// `#[cfg(any(test, feature = "testing"))]`:单元测试与集成测试(tests/ 外部二进制)均可用。
#[cfg(any(test, feature = "testing"))]
pub async fn with_default_tenant<F, R>(f: F) -> R
where
    F: std::future::Future<Output = R>,
{
    let ctx = TenantContext {
        tenant_id: 0,
        resolved_from: TenantSource::Header,
    };
    TENANT.scope(ctx, f).await
}

#[cfg(test)]
mod tests {
    use super::*;

    /// `TenantContext` 携带 tenant_id 与来源标识,字段可读。
    #[test]
    fn tenant_context_constructs_with_tenant_id_and_source() {
        let ctx = TenantContext {
            tenant_id: 42,
            resolved_from: TenantSource::Header,
        };
        assert_eq!(ctx.tenant_id, 42);
        assert!(matches!(ctx.resolved_from, TenantSource::Header));
    }

    /// `HeaderTenantResolver` 从 `X-Tenant-Id: 42` 提取 `tenant_id == 42`。
    #[tokio::test]
    async fn header_tenant_resolver_extracts_x_tenant_id() {
        let mut headers = http::HeaderMap::new();
        headers.insert("X-Tenant-Id", "42".parse().expect("valid header value"));
        let ctx = HeaderTenantResolver
            .resolve(&headers)
            .await
            .expect("X-Tenant-Id 存在时应解析成功");
        assert_eq!(ctx.tenant_id, 42);
        assert!(matches!(ctx.resolved_from, TenantSource::Header));
    }

    /// HeaderTenantResolver 在 header 缺失时返回 Config 错误(不默认 0)。
    #[tokio::test]
    async fn header_tenant_resolver_returns_config_error_when_header_missing() {
        let headers = http::HeaderMap::new();
        let result = HeaderTenantResolver.resolve(&headers).await;
        assert!(matches!(result, Err(GarrisonError::Config(_))));
    }

    /// HeaderTenantResolver 在 header 非法 i64 时返回 Config 错误。
    #[tokio::test]
    async fn header_tenant_resolver_returns_config_error_when_header_not_i64() {
        let mut headers = http::HeaderMap::new();
        headers.insert("X-Tenant-Id", "not-a-number".parse().unwrap());
        let result = HeaderTenantResolver.resolve(&headers).await;
        assert!(matches!(result, Err(GarrisonError::Config(_))));
    }

    /// `TENANT.scope` 内的 `TENANT.get()` 取到进入 scope 时传入的 `TenantContext`。
    #[tokio::test]
    async fn tenant_scope_enter_returns_context_value() {
        let ctx = TenantContext {
            tenant_id: 42,
            resolved_from: TenantSource::Header,
        };
        let tenant_id = TENANT.scope(ctx, async { TENANT.get().tenant_id }).await;
        assert_eq!(tenant_id, 42);
    }

    /// `TENANT.try_get()` 无 scope 时返回 Err(不 panic):DAO key 前缀逻辑的兜底条件。
    #[tokio::test]
    async fn tenant_try_get_returns_err_when_no_scope() {
        assert!(TENANT.try_get().is_err());
    }

    /// `current_tenant_id_strict` 未进入 `TENANT.scope` 时返回 `None`(不 panic):
    /// 要求调用方显式处理无上下文场景,避免租户隔离被静默绕过(失败显性化)。
    #[tokio::test]
    async fn strict_returns_none_without_scope() {
        assert_eq!(current_tenant_id_strict(), None);
    }

    /// `current_tenant_id_strict` 在 `TENANT.scope` 内返回 `Some(42)`。
    #[tokio::test]
    async fn strict_returns_some_with_scope() {
        let ctx = TenantContext {
            tenant_id: 42,
            resolved_from: TenantSource::Header,
        };
        let result = TENANT
            .scope(ctx, async { current_tenant_id_strict() })
            .await;
        assert_eq!(result, Some(42));
    }

    // current_tenant_id_or_error 测试
    /// 无 `TENANT.scope` 时返回 `Err(Config)`(fail-closed),避免租户隔离被静默绕过。
    #[tokio::test]
    async fn or_error_returns_err_when_no_scope() {
        let result = current_tenant_id_or_error();
        assert!(
            result.is_err(),
            "无 scope 时应 fail-closed 返回 Err: {:?}",
            result.ok()
        );
        match result {
            Err(GarrisonError::Config(msg)) => {
                assert!(
                    msg.contains("ctx-tenant-context-missing") || msg.contains("租户隔离"),
                    "错误消息应含 'ctx-tenant-context-missing' 或 '租户隔离',实际: {}",
                    msg
                );
            },
            Err(other) => panic!("期望 Config 错误,实际: {:?}", other),
            Ok(_) => panic!("期望 Err(fail-closed),实际 Ok"),
        }
    }

    /// `TENANT.scope` 内返回 `Ok(42)`。
    #[tokio::test]
    async fn or_error_returns_ok_with_scope() {
        let ctx = TenantContext {
            tenant_id: 42,
            resolved_from: TenantSource::Header,
        };
        let result = TENANT
            .scope(ctx, async { current_tenant_id_or_error() })
            .await;
        assert!(result.is_ok(), "scope 内应返回 Ok: {:?}", result.err());
        assert_eq!(result.unwrap(), 42);
    }

    /// 各 tenant_id 边界值(0 默认租户、i64::MAX)均正确读取:函数只依赖 scope 是否存在。
    #[tokio::test]
    async fn or_error_handles_various_tenant_ids() {
        // tenant_id = 0(合法的默认租户,scope 已进入)
        let ctx0 = TenantContext {
            tenant_id: 0,
            resolved_from: TenantSource::Header,
        };
        let result0 = TENANT
            .scope(ctx0, async { current_tenant_id_or_error() })
            .await;
        assert!(result0.is_ok(), "tenant_id=0 + scope 应 Ok");
        assert_eq!(result0.unwrap(), 0);

        // tenant_id = i64::MAX(边界值)
        let ctx_max = TenantContext {
            tenant_id: i64::MAX,
            resolved_from: TenantSource::Header,
        };
        let result_max = TENANT
            .scope(ctx_max, async { current_tenant_id_or_error() })
            .await;
        assert!(result_max.is_ok());
        assert_eq!(result_max.unwrap(), i64::MAX);
    }

    /// `Host: tenant42.example.com` + 映射 `{"tenant42": 42}` → `tenant_id == 42`。
    #[tokio::test]
    async fn subdomain_tenant_resolver_extracts_from_host() {
        let mut headers = http::HeaderMap::new();
        headers.insert("Host", "tenant42.example.com".parse().unwrap());
        let resolver = SubdomainTenantResolver {
            mapping: std::collections::HashMap::from([("tenant42".to_string(), 42)]),
        };
        let ctx = resolver
            .resolve(&headers)
            .await
            .expect("Host 含已知 subdomain 时应解析成功");
        assert_eq!(ctx.tenant_id, 42);
        assert!(matches!(ctx.resolved_from, TenantSource::Subdomain));
    }

    /// SubdomainTenantResolver 在 mapping 未命中时返回 Config 错误。
    #[tokio::test]
    async fn subdomain_tenant_resolver_returns_config_error_when_mapping_miss() {
        let mut headers = http::HeaderMap::new();
        headers.insert("Host", "unknown.example.com".parse().unwrap());
        let resolver = SubdomainTenantResolver {
            mapping: std::collections::HashMap::from([("tenant42".to_string(), 42)]),
        };
        let result = resolver.resolve(&headers).await;
        assert!(matches!(result, Err(GarrisonError::Config(_))));
    }

    /// SubdomainTenantResolver 在 Host 缺失时返回 Config 错误。
    #[tokio::test]
    async fn subdomain_tenant_resolver_returns_config_error_when_host_missing() {
        let headers = http::HeaderMap::new();
        let resolver = SubdomainTenantResolver {
            mapping: std::collections::HashMap::new(),
        };
        let result = resolver.resolve(&headers).await;
        assert!(matches!(result, Err(GarrisonError::Config(_))));
    }

    /// SubdomainTenantResolver 处理带端口的 Host(如 tenant42.example.com:8080)。
    #[tokio::test]
    async fn subdomain_tenant_resolver_strips_port_from_host() {
        let mut headers = http::HeaderMap::new();
        headers.insert("Host", "tenant42.example.com:8080".parse().unwrap());
        let resolver = SubdomainTenantResolver {
            mapping: std::collections::HashMap::from([("tenant42".to_string(), 42)]),
        };
        let ctx = resolver
            .resolve(&headers)
            .await
            .expect("带端口的 Host 应正确提取 subdomain");
        assert_eq!(ctx.tenant_id, 42);
    }

    /// IPv6 字面量 Host(`[::1]:8080`)不得被 `split(':').next()` 截断出 `[`;
    /// IPv6 主机无 subdomain 语义,应报 unknown-subdomain 错误而非 panic 或误配。
    #[tokio::test]
    async fn subdomain_tenant_resolver_handles_ipv6_host_without_panic() {
        let mut headers = http::HeaderMap::new();
        headers.insert("Host", "[::1]:8080".parse().unwrap());
        let resolver = SubdomainTenantResolver {
            mapping: std::collections::HashMap::from([("tenant42".to_string(), 42)]),
        };
        // hostname 解析为 "::1"(非 "["),走 unknown-subdomain 错误路径
        let result = resolver.resolve(&headers).await;
        match result {
            Err(GarrisonError::Config(msg)) => {
                assert!(
                    msg.contains("ctx-host-unknown-subdomain"),
                    "IPv6 Host 应走 unknown-subdomain 路径,实际: {msg}"
                );
                assert!(
                    msg.contains("::1"),
                    "错误消息应包含完整 IPv6 地址而非 '[',实际: {msg}"
                );
            },
            Err(other) => panic!("期望 Config 错误,实际: {:?}", other),
            Ok(_) => panic!("IPv6 地址不在 mapping 中应报错"),
        }
    }

    /// 裸 IPv6 Host(无端口 `[::1]`)同样正确解析。
    #[tokio::test]
    async fn subdomain_tenant_resolver_handles_ipv6_host_without_port() {
        let mut headers = http::HeaderMap::new();
        headers.insert("Host", "[2001:db8::1]".parse().unwrap());
        let resolver = SubdomainTenantResolver {
            mapping: std::collections::HashMap::new(),
        };
        let result = resolver.resolve(&headers).await;
        assert!(
            matches!(result, Err(GarrisonError::Config(_))),
            "裸 IPv6 Host 不应 panic,应返回 Config 错误"
        );
    }

    /// 含 `tenant_id: 42` 的合法 JWT 解析出 `tenant_id == 42`。
    #[cfg(feature = "protocol-jwt")]
    #[tokio::test]
    async fn claim_tenant_resolver_extracts_from_jwt_claim() {
        use jsonwebtoken::{encode, Algorithm, EncodingKey, Header};

        #[derive(serde::Serialize)]
        struct Claims {
            tenant_id: i64,
            exp: i64,
        }

        let secret = "test-secret-claim";
        let claims = Claims {
            tenant_id: 42,
            exp: 9999999999,
        };
        let header = Header::new(Algorithm::HS256);
        let key = EncodingKey::from_secret(secret.as_bytes());
        let jwt = encode(&header, &claims, &key).expect("encode jwt");

        let mut headers = http::HeaderMap::new();
        headers.insert(
            "Authorization",
            format!("Bearer {jwt}").parse().expect("valid header value"),
        );

        let resolver = ClaimTenantResolver::new(secret.to_string());
        let ctx = resolver
            .resolve(&headers)
            .await
            .expect("valid JWT 应解析成功");
        assert_eq!(ctx.tenant_id, 42);
        assert!(matches!(ctx.resolved_from, TenantSource::Claim));
    }

    /// ClaimTenantResolver 在 Authorization 缺失时返回 InvalidToken。
    #[cfg(feature = "protocol-jwt")]
    #[tokio::test]
    async fn claim_tenant_resolver_returns_invalid_token_when_auth_missing() {
        let headers = http::HeaderMap::new();
        let resolver = ClaimTenantResolver::new("secret".to_string());
        let result = resolver.resolve(&headers).await;
        assert!(matches!(result, Err(GarrisonError::InvalidToken(_))));
    }

    /// ClaimTenantResolver 在 JWT 签名验证失败时返回 InvalidToken。
    #[cfg(feature = "protocol-jwt")]
    #[tokio::test]
    async fn claim_tenant_resolver_returns_invalid_token_when_signature_bad() {
        use jsonwebtoken::{encode, Algorithm, EncodingKey, Header};

        #[derive(serde::Serialize)]
        struct Claims {
            tenant_id: i64,
            exp: i64,
        }

        let signing_secret = "secret-a";
        let verifying_secret = "secret-b"; // 不匹配
        let jwt = encode(
            &Header::new(Algorithm::HS256),
            &Claims {
                tenant_id: 42,
                exp: 9999999999,
            },
            &EncodingKey::from_secret(signing_secret.as_bytes()),
        )
        .expect("encode jwt");

        let mut headers = http::HeaderMap::new();
        headers.insert("Authorization", format!("Bearer {jwt}").parse().unwrap());
        let resolver = ClaimTenantResolver::new(verifying_secret.to_string());
        let result = resolver.resolve(&headers).await;
        assert!(matches!(result, Err(GarrisonError::InvalidToken(_))));
    }

    /// ClaimTenantResolver 在 tenant_id claim 缺失时返回 InvalidToken。
    #[cfg(feature = "protocol-jwt")]
    #[tokio::test]
    async fn claim_tenant_resolver_returns_invalid_token_when_claim_missing() {
        use jsonwebtoken::{encode, Algorithm, EncodingKey, Header};

        #[derive(serde::Serialize)]
        struct Claims {
            exp: i64,
            // 故意没有 tenant_id
        }

        let secret = "test-secret-no-claim";
        let jwt = encode(
            &Header::new(Algorithm::HS256),
            &Claims { exp: 9999999999 },
            &EncodingKey::from_secret(secret.as_bytes()),
        )
        .expect("encode jwt");

        let mut headers = http::HeaderMap::new();
        headers.insert("Authorization", format!("Bearer {jwt}").parse().unwrap());
        let resolver = ClaimTenantResolver::new(secret.to_string());
        let result = resolver.resolve(&headers).await;
        assert!(matches!(result, Err(GarrisonError::InvalidToken(_))));
    }

    /// ClaimTenantResolver 接受小写 bearer scheme(RFC 7235 大小写不敏感)。
    #[cfg(feature = "protocol-jwt")]
    #[tokio::test]
    async fn claim_tenant_resolver_accepts_lowercase_bearer_scheme() {
        use jsonwebtoken::{encode, Algorithm, EncodingKey, Header};

        #[derive(serde::Serialize)]
        struct Claims {
            tenant_id: i64,
            exp: i64,
        }

        let secret = "test-secret-lower";
        let jwt = encode(
            &Header::new(Algorithm::HS256),
            &Claims {
                tenant_id: 42,
                exp: 9999999999,
            },
            &EncodingKey::from_secret(secret.as_bytes()),
        )
        .expect("encode jwt");

        let mut headers = http::HeaderMap::new();
        headers.insert("Authorization", format!("bearer {jwt}").parse().unwrap());
        let resolver = ClaimTenantResolver::new(secret.to_string());
        let ctx = resolver
            .resolve(&headers)
            .await
            .expect("小写 bearer scheme 应被接受");
        assert_eq!(ctx.tenant_id, 42);
    }

    /// ClaimTenantResolver 的 Debug 输出必须脱敏 jwt_secret。
    #[cfg(feature = "protocol-jwt")]
    #[test]
    fn claim_tenant_resolver_debug_redacts_jwt_secret() {
        let resolver = ClaimTenantResolver::new("super-secret-value".to_string());
        let debug = format!("{:?}", resolver);
        assert!(
            !debug.contains("super-secret-value"),
            "Debug 输出不得包含明文 jwt_secret,实际: {debug}"
        );
        assert!(
            debug.contains("<redacted>"),
            "Debug 输出应包含脱敏占位符,实际: {debug}"
        );
    }

    /// 配置了 expected_issuers 时,iss 不匹配的 JWT 应被拒绝。
    #[cfg(feature = "protocol-jwt")]
    #[tokio::test]
    async fn claim_tenant_resolver_rejects_wrong_issuer_when_configured() {
        use jsonwebtoken::{encode, Algorithm, EncodingKey, Header};

        #[derive(serde::Serialize)]
        struct Claims {
            tenant_id: i64,
            exp: i64,
            iss: String,
        }

        let secret = "test-secret-issuer";
        let jwt = encode(
            &Header::new(Algorithm::HS256),
            &Claims {
                tenant_id: 42,
                exp: 9999999999,
                iss: "attacker-service".to_string(),
            },
            &EncodingKey::from_secret(secret.as_bytes()),
        )
        .expect("encode jwt");

        let mut headers = http::HeaderMap::new();
        headers.insert("Authorization", format!("Bearer {jwt}").parse().unwrap());
        let resolver = ClaimTenantResolver::new(secret.to_string())
            .with_expected_issuers(vec!["garrison-auth".to_string()]);
        let result = resolver.resolve(&headers).await;
        assert!(
            matches!(result, Err(GarrisonError::InvalidToken(_))),
            "iss 不匹配的 JWT 应被拒绝(防跨服务 token 重放)"
        );
    }

    /// 配置了 expected_issuers 时,iss 匹配的 JWT 应通过。
    #[cfg(feature = "protocol-jwt")]
    #[tokio::test]
    async fn claim_tenant_resolver_accepts_matching_issuer_when_configured() {
        use jsonwebtoken::{encode, Algorithm, EncodingKey, Header};

        #[derive(serde::Serialize)]
        struct Claims {
            tenant_id: i64,
            exp: i64,
            iss: String,
        }

        let secret = "test-secret-issuer-ok";
        let jwt = encode(
            &Header::new(Algorithm::HS256),
            &Claims {
                tenant_id: 7,
                exp: 9999999999,
                iss: "garrison-auth".to_string(),
            },
            &EncodingKey::from_secret(secret.as_bytes()),
        )
        .expect("encode jwt");

        let mut headers = http::HeaderMap::new();
        headers.insert("Authorization", format!("Bearer {jwt}").parse().unwrap());
        let resolver = ClaimTenantResolver::new(secret.to_string())
            .with_expected_issuers(vec!["garrison-auth".to_string()]);
        let ctx = resolver.resolve(&headers).await.expect("iss 匹配应通过");
        assert_eq!(ctx.tenant_id, 7);
    }

    /// 配置了 expected_audiences 时,aud 不匹配的 JWT 应被拒绝。
    #[cfg(feature = "protocol-jwt")]
    #[tokio::test]
    async fn claim_tenant_resolver_rejects_wrong_audience_when_configured() {
        use jsonwebtoken::{encode, Algorithm, EncodingKey, Header};

        #[derive(serde::Serialize)]
        struct Claims {
            tenant_id: i64,
            exp: i64,
            aud: String,
        }

        let secret = "test-secret-aud";
        let jwt = encode(
            &Header::new(Algorithm::HS256),
            &Claims {
                tenant_id: 42,
                exp: 9999999999,
                aud: "other-service".to_string(),
            },
            &EncodingKey::from_secret(secret.as_bytes()),
        )
        .expect("encode jwt");

        let mut headers = http::HeaderMap::new();
        headers.insert("Authorization", format!("Bearer {jwt}").parse().unwrap());
        let resolver = ClaimTenantResolver::new(secret.to_string())
            .with_expected_audiences(vec!["tenant-service".to_string()]);
        let result = resolver.resolve(&headers).await;
        assert!(
            matches!(result, Err(GarrisonError::InvalidToken(_))),
            "aud 不匹配的 JWT 应被拒绝"
        );
    }
}