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
// Copyright (c) 2026 Kirky.X🌠
// SPDX-License-Identifier: Apache-2.0

//! 权限校验层测试。

use super::mock::MockInterface;
use super::*;
use std::collections::HashMap;

/// 创建 PermissionCheckerDefault 实例(账号 1001 持有 user:read/user:write 权限 + admin/user 角色)。
fn make_checker() -> PermissionCheckerDefault {
    let interface = MockInterface::new()
        .with_perms("1001", vec!["user:read", "user:write"])
        .with_roles("1001", vec!["admin", "user"]);
    let interface_arc: Arc<dyn GarrisonInterface> = Arc::new(interface);
    PermissionCheckerDefault::new(interface_arc)
}

// has_permission 测试

/// has_permission 持有权限返回 true。
#[tokio::test]
async fn has_permission_held_returns_true() {
    let checker = make_checker();
    assert!(checker.has_permission("1001", "user:read").await.unwrap());
}

/// has_permission 未持有权限返回 false。
#[tokio::test]
async fn has_permission_not_held_returns_false() {
    let checker = make_checker();
    assert!(!checker.has_permission("1001", "user:delete").await.unwrap());
}

/// has_permission 空字符串返回 InvalidParam 错误(锁定错误变体与错误码,防其他变体蒙混)。
#[tokio::test]
async fn has_permission_empty_string_returns_error() {
    let checker = make_checker();
    let result = checker.has_permission("1001", "").await;
    assert!(
        matches!(result, Err(GarrisonError::InvalidParam(ref msg)) if msg.contains("core-perm-empty")),
        "has_permission 空字符串应返回 InvalidParam(core-perm-empty),实际: {:?}",
        result
    );
}

// has_role 测试

/// has_role 持有角色返回 true。
#[tokio::test]
async fn has_role_held_returns_true() {
    let checker = make_checker();
    assert!(checker.has_role("1001", "admin").await.unwrap());
}

/// has_role 未持有角色返回 false。
#[tokio::test]
async fn has_role_not_held_returns_false() {
    let checker = make_checker();
    assert!(!checker.has_role("1001", "superadmin").await.unwrap());
}

/// has_role 对 role 做 NFC 规范化(与 has_permission 对齐):NFD 形式应规范化后匹配 NFC
/// 存储,防视觉同形字符串绕过角色校验。
#[tokio::test]
async fn has_role_normalizes_unicode() {
    let interface = MockInterface::new().with_roles("1001", vec!["rol\u{00e9}1"]);
    let interface_arc: Arc<dyn GarrisonInterface> = Arc::new(interface);
    let checker = PermissionCheckerDefault::new(interface_arc);

    let nfd = "role\u{0301}1";
    let nfc = "rol\u{00e9}1";

    assert!(
        checker.has_role("1001", nfd).await.unwrap(),
        "NFD 形式应规范化后匹配 NFC role"
    );
    assert!(
        checker.has_role("1001", nfc).await.unwrap(),
        "NFC 形式应直接匹配"
    );
}

// check_permission 测试

/// check_permission 持有权限返回 Ok(())。
#[tokio::test]
async fn check_permission_held_returns_ok() {
    let checker = make_checker();
    assert!(checker.check_permission("1001", "user:read").await.is_ok());
}

/// check_permission 未持有权限返回 NotPermission 错误。
#[tokio::test]
async fn check_permission_not_held_returns_error() {
    let checker = make_checker();
    let result = checker.check_permission("1001", "user:delete").await;
    assert!(result.is_err());
    match result.err() {
        Some(GarrisonError::NotPermission(_)) => {},
        other => panic!("期望 NotPermission,实际: {:?}", other),
    }
}

// check_role 测试

/// check_role 持有角色返回 Ok(())。
#[tokio::test]
async fn check_role_held_returns_ok() {
    let checker = make_checker();
    assert!(checker.check_role("1001", "admin").await.is_ok());
}

/// check_role 未持有角色返回 NotRole 错误。
#[tokio::test]
async fn check_role_not_held_returns_error() {
    let checker = make_checker();
    let result = checker.check_role("1001", "superadmin").await;
    assert!(result.is_err());
    match result.err() {
        Some(GarrisonError::NotRole(_)) => {},
        other => panic!("期望 NotRole,实际: {:?}", other),
    }
}

// has_any_permission 测试

/// has_any_permission 任一匹配返回 true。
#[tokio::test]
async fn has_any_permission_any_match_returns_true() {
    let checker = make_checker();
    assert!(
        checker
            .has_any_permission("1001", &["user:read", "user:delete"])
            .await
    );
}

/// has_any_permission 全不匹配返回 false。
#[tokio::test]
async fn has_any_permission_no_match_returns_false() {
    let checker = make_checker();
    assert!(
        !checker
            .has_any_permission("1001", &["user:delete", "user:create"])
            .await
    );
}

// has_all_permissions 测试

/// has_all_permissions 全部匹配返回 true。
#[tokio::test]
async fn has_all_permissions_all_match_returns_true() {
    let checker = make_checker();
    assert!(
        checker
            .has_all_permissions("1001", &["user:read", "user:write"])
            .await
    );
}

/// has_all_permissions 部分匹配返回 false。
#[tokio::test]
async fn has_all_permissions_partial_match_returns_false() {
    let checker = make_checker();
    assert!(
        !checker
            .has_all_permissions("1001", &["user:read", "user:delete"])
            .await
    );
}

/// has_all_permissions 空列表返回 true(vacuous truth)。
#[tokio::test]
async fn has_all_permissions_empty_list_returns_true() {
    let checker = make_checker();
    assert!(checker.has_all_permissions("1001", &[]).await);
}

// authorize 测试

/// authorize 权限匹配时返回 allowed=true 的 Decision(reason=ExplicitAllow)。
#[tokio::test]
async fn authorize_returns_decision_with_allowed_true_when_permission_matches() {
    let checker = make_checker();
    let request = AuthRequest::new("1001", "user:read");
    let decision = PermissionChecker::authorize(&checker, &request)
        .await
        .expect("authorize ok");
    assert!(decision.allowed);
    assert_eq!(decision.reason, DecisionReason::ExplicitAllow);
}

/// authorize 在权限不匹配时返回 allowed=false + NoMatchingPermission。
#[tokio::test]
async fn authorize_returns_deny_when_permission_not_matched() {
    let checker = make_checker();
    let request = AuthRequest::new("1001", "user:delete");
    let decision = PermissionChecker::authorize(&checker, &request)
        .await
        .expect("authorize ok");
    assert!(!decision.allowed);
    assert_eq!(decision.reason, DecisionReason::NoMatchingPermission);
}

/// authorize 在权限字符串为空时返回 InvalidParam 错误。
#[tokio::test]
async fn authorize_returns_error_for_empty_permission() {
    let checker = make_checker();
    let request = AuthRequest::new("1001", "");
    let result = PermissionChecker::authorize(&checker, &request).await;
    assert!(result.is_err());
    match result.err() {
        Some(GarrisonError::InvalidParam(_)) => {},
        other => panic!("期望 InvalidParam,实际: {:?}", other),
    }
}

/// check_permission 与 authorize 行为一致:allowed=true → Ok(()),allowed=false → Err(NotPermission)。
#[tokio::test]
async fn check_permission_delegates_to_authorize_and_returns_allowed() {
    let checker = make_checker();

    let req_ok = AuthRequest::new("1001", "user:read");
    let decision_ok = PermissionChecker::authorize(&checker, &req_ok)
        .await
        .expect("authorize ok");
    assert!(decision_ok.allowed);
    assert!(checker.check_permission("1001", "user:read").await.is_ok());

    let req_no = AuthRequest::new("1001", "user:delete");
    let decision_no = PermissionChecker::authorize(&checker, &req_no)
        .await
        .expect("authorize ok");
    assert!(!decision_no.allowed);
    assert!(checker
        .check_permission("1001", "user:delete")
        .await
        .is_err());
}

/// check_permission 的错误类型为 NotPermission(不是其他错误)。
#[tokio::test]
async fn check_permission_deny_returns_not_permission_error() {
    let checker = make_checker();
    let result = checker.check_permission("1001", "user:delete").await;
    match result.err() {
        Some(GarrisonError::NotPermission(msg)) => {
            assert!(msg.contains("1001"), "错误消息应含 login_id");
            assert!(msg.contains("user:delete"), "错误消息应含 permission");
        },
        other => panic!("期望 NotPermission,实际: {:?}", other),
    }
}

/// check_role 仍保持原行为(未持有角色返回 NotRole)。
#[tokio::test]
async fn check_role_still_returns_not_role_when_unmatched() {
    let checker = make_checker();
    let result = checker.check_role("1001", "superadmin").await;
    match result.err() {
        Some(GarrisonError::NotRole(_)) => {},
        other => panic!("期望 NotRole,实际: {:?}", other),
    }
}

/// Decision 可从 authorize 序列化为 JSON(端到端 trace 输出验证)。
#[tokio::test]
async fn authorize_decision_serializes_to_json() {
    let checker = make_checker();
    let request = AuthRequest::new("1001", "user:read");
    let decision = PermissionChecker::authorize(&checker, &request)
        .await
        .expect("authorize ok");
    let json = serde_json::to_value(&decision).expect("serialize Decision");
    assert_eq!(json["allowed"], serde_json::json!(true));
    assert_eq!(json["reason"], serde_json::json!("explicit_allow"));
}

// Unicode NFC 规范化 + 长度限制测试

/// check_permission 对 permission 做 NFC 规范化:NFD `"user:e\u{0301}read"` 规范化为 NFC
/// `"user:\u{00e9}read"`(mock 存 NFC 形式),传入 NFD 应规范化后匹配。
#[tokio::test]
async fn check_permission_normalizes_unicode() {
    let interface = MockInterface::new().with_perms("1001", vec!["user:\u{00e9}read"]);
    let interface_arc: Arc<dyn GarrisonInterface> = Arc::new(interface);
    let checker = PermissionCheckerDefault::new(interface_arc);

    let nfd = "user:e\u{0301}read";
    let nfc = "user:\u{00e9}read";

    assert!(
        checker.check_permission("1001", nfd).await.is_ok(),
        "NFD 形式应规范化后匹配 NFC permission"
    );
    assert!(
        checker.check_permission("1001", nfc).await.is_ok(),
        "NFC 形式应直接匹配"
    );
}

/// check_permission 拒绝超过 256 字节的 permission 字符串(防止 DoS)。
#[tokio::test]
async fn check_permission_rejects_over_256_bytes() {
    let long_perm = "x".repeat(300); // 300 字节,超过 256 字节上限
    let checker = make_checker();
    let result = checker.check_permission("1001", &long_perm).await;
    assert!(
        matches!(result, Err(GarrisonError::InvalidParam(_))),
        "超长 permission 应返回 InvalidParam,实际: {:?}",
        result
    );
}

// 覆盖率补充:has_role 空角色 + check_role 错误消息验证

/// has_role 空字符串返回 InvalidParam 错误。
#[tokio::test]
async fn has_role_empty_string_returns_error() {
    let checker = make_checker();
    let result = checker.has_role("1001", "").await;
    assert!(
        matches!(result, Err(GarrisonError::InvalidParam(ref msg)) if msg.contains("core-role-empty")),
        "has_role 空字符串应返回 InvalidParam,实际: {:?}",
        result
    );
}

/// check_role 未持有角色的错误消息含 login_id 与 role。
#[tokio::test]
async fn check_role_deny_message_includes_login_id_and_role() {
    let checker = make_checker();
    let result = checker.check_role("1001", "superadmin").await;
    match result.err() {
        Some(GarrisonError::NotRole(msg)) => {
            assert!(msg.contains("1001"), "错误消息应含 login_id,实际: {}", msg);
            assert!(
                msg.contains("superadmin"),
                "错误消息应含 role,实际: {}",
                msg
            );
        },
        other => panic!("期望 NotRole,实际: {:?}", other),
    }
}

/// 调用默认委托方法覆盖 async_trait wrapper。
#[tokio::test]
async fn mock_interface_default_methods_with_type_coverage() {
    let iface = MockInterface::new();
    let _ = iface
        .get_permission_list_with_type("u1", "default")
        .await
        .unwrap();
    let _ = iface
        .get_role_list_with_type("u1", "default")
        .await
        .unwrap();
}

// 租户感知判定:authorize 消费 AuthRequest.tenant_id

/// 租户感知 interface mock:按 (tenant_id, login_id) 返回权限(模拟业务方覆写
/// `get_permission_list_in_tenant` 的租户隔离数据源)。
struct TenantScopedInterface {
    by_tenant: HashMap<(i64, String), Vec<String>>,
}

#[async_trait]
impl GarrisonInterface for TenantScopedInterface {
    async fn get_permission_list(&self, _login_id: &str) -> GarrisonResult<Vec<String>> {
        Ok(Vec::new())
    }

    async fn get_role_list(&self, _login_id: &str) -> GarrisonResult<Vec<String>> {
        Ok(Vec::new())
    }

    async fn get_permission_list_in_tenant(
        &self,
        tenant_id: i64,
        login_id: &str,
    ) -> GarrisonResult<Vec<String>> {
        Ok(self
            .by_tenant
            .get(&(tenant_id, login_id.to_string()))
            .cloned()
            .unwrap_or_default())
    }
}

/// authorize 默认实现消费 request.tenant_id:租户 1 的 "admin" 持有 doc:delete,
/// 租户 2 的重名 "admin" 不得继承(跨租户互染回归)。
#[tokio::test]
async fn authorize_consumes_request_tenant_id_with_tenant_scoped_source() {
    let mut map = HashMap::new();
    map.insert((1, "admin".to_string()), vec!["doc:delete".to_string()]);
    let checker = PermissionCheckerDefault::new(Arc::new(TenantScopedInterface { by_tenant: map }));

    let mut req = AuthRequest::new("admin", "doc:delete");
    req.tenant_id = 1;
    let decision = PermissionChecker::authorize(&checker, &req).await.unwrap();
    assert!(
        decision.allowed,
        "租户 1 的 admin 应被允许(租户作用域数据源命中)"
    );

    let mut req2 = AuthRequest::new("admin", "doc:delete");
    req2.tenant_id = 2;
    let decision2 = PermissionChecker::authorize(&checker, &req2).await.unwrap();
    assert!(
        !decision2.allowed,
        "租户 2 的重名 admin 不得继承租户 1 的权限"
    );
    assert!(
        matches!(decision2.reason, DecisionReason::NoMatchingPermission),
        "拒绝原因应为 NoMatchingPermission,实际: {:?}",
        decision2.reason
    );
}

/// authorize 在 tenant_id = 0(单租户/未隔离)时保持全局路径行为不变。
#[tokio::test]
async fn authorize_tenant_zero_keeps_global_path_behavior() {
    // 全局数据源持权,租户数据源为空:tenant_id=0 必须走全局路径命中
    let interface = MockInterface::new().with_perms("1001", vec!["user:read"]);
    let checker = PermissionCheckerDefault::new(Arc::new(interface));

    let req = AuthRequest::new("1001", "user:read");
    let decision = PermissionChecker::authorize(&checker, &req).await.unwrap();
    assert!(
        decision.allowed,
        "tenant_id=0 应走全局数据源(行为不变契约)"
    );
}

/// has_permission_in_tenant 默认实现委托 has_permission(未覆写实现行为不变契约)。
#[tokio::test]
async fn has_permission_in_tenant_default_delegates_to_global() {
    let checker = make_checker();
    assert!(
        checker
            .has_permission_in_tenant(42, "1001", "user:read")
            .await
            .unwrap(),
        "默认实现应委托 has_permission(忽略 tenant_id)"
    );
}