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
# 📘 Garrison API 参考

本参考文档收录 Garrison 的公开 API:全局管理器与静态门面、业务回调 trait、存储层 trait、注解宏、错误类型以及特性门控模块。文档假设启用了相应 feature;未启用时对应 API 不参与编译。在线文档(docs.rs 自动生成):<https://docs.rs/garrison>。

> 适用版本:0.9.0(0.9.0-rc.4 新增限流后端 API 见文末)。完整签名以 rustdoc 为准,本文按「模块 → trait/类型 → 方法表」组织,供快速定位。

## 📋 目录

- [概述](#-概述)
- [prelude 预导出](#-prelude-预导出)
- [全局管理器](#-全局管理器)
- [静态门面 GarrisonUtil](#️-静态门面-garrisonutil)
- [token 上下文](#-token-上下文)
- [业务回调 GarrisonInterface](#-业务回调-garrisoninterface)
- [存储层 GarrisonDao](#️-存储层-garrisondao)
- [权限策略](#-权限策略)
- [会话与状态](#-会话与状态)
- [Web 集成与注解宏](#-web-集成与注解宏)
- [插件与监听器](#-插件与监听器)
- [Repository 层](#️-repository-层)
- [密码哈希器(account-credential)](#-密码哈希器account-credential)
- [错误类型](#-错误类型)
- [模块地图](#️-模块地图)
- [相关文档](#-相关文档)

---

## 🎯 概述

<div align="center">

<img src="assets/api-structure.svg" alt="API 结构" width="800">

</div>

### API 设计原则

| 原则 | 说明 |
|:-----|:-----|
| **静态门面** | 业务代码只与 `GarrisonManager`(初始化一次)和 `GarrisonUtil`(静态方法)打交道 |
| **回调注入** | 框架不假定数据来源,权限 / 角色数据经 `GarrisonInterface` 回调由业务方提供 |
| **trait 可替换** | `GarrisonDao`、`GarrisonPermissionStrategy`、`GarrisonPlugin`、`GarrisonListener` 均可自定义实现替换默认行为 |
| **feature 门控** | 可选能力(协议、防火墙、Web 适配等)按 feature 独立编译;功能矩阵见 [README · 特性标志](../README.md#-特性标志) |

### 导入方式

```rust
use garrison::prelude::*;          // 核心 API 一步到位
use garrison::stp::with_current_token; // token 上下文(prelude 亦含)
```

---

## 📦 prelude 预导出

`garrison::prelude`(`src/prelude.rs`)聚合最常用类型,`use garrison::prelude::*` 即可覆盖 README 最小示例的全部依赖:

| 导出项 | 说明 |
|--------|------|
| `GarrisonConfig` | 配置类型 |
| `GarrisonContext` / `GarrisonRequest` / `GarrisonResponse` / `GarrisonStorage` | 上下文抽象 |
| `AuthRequest` / `Decision` / `DecisionReason` | 授权请求与决策(`core-advanced`) |
| `GarrisonDao` | 存储 trait |
| `GarrisonError` / `GarrisonResult` | 错误类型与 Result 别名 |
| `GarrisonManager` | 全局管理器 |
| `GarrisonPlugin` | 插件 trait |
| `GarrisonInterceptor` / `GarrisonRouter` | 路由与拦截器 |
| `GarrisonSession` | 会话 |
| `GarrisonPermissionStrategy` / `GarrisonPermissionStrategyDefault` | 权限策略 trait 与默认实现 |
| `Annotation` | 注解(`annotation-macros`) |
| `GarrisonDaoOxcache` | oxcache DAO 实现(`cache-*`) |
| `LoginParams` | 登录参数 |
| `with_current_token` / `current_token` | token 上下文 |
| `CreditMeteringListener` 等 | 计量监听(`credit-metering`) |

---

## 🏢 全局管理器

`GarrisonManager`(`src/manager/`)— 全局单例,内部逻辑经 `arc_swap::ArcSwapOption` 无锁读取。

```rust
GarrisonManager::builder()
    .dao(dao)               // Arc<dyn GarrisonDao>
    .config(config)         // Arc<GarrisonConfig>
    .interface(interface)   // Arc<dyn GarrisonInterface>
    .build().await?;        // 初始化全局单例
```

| 项 | 说明 |
|----|------|
| `GarrisonManager::builder()` | 返回 builder;启用任一 `firewall-*` 时自动注入防火墙检查钩子 |
| 初始化时序 | 全局只可 `build()` 一次;并发初始化为 CAS 语义 |
| 后端模式 | `backend-embedded`(默认,进程内认证)/ `backend-remote`(HTTP 调用远程 Auth Server,含熔断) |

---

## 🛠️ 静态门面 GarrisonUtil

`GarrisonUtil`(`src/stp/util/mod.rs`)— 全部为关联函数,读取当前 task_local token 上下文执行。以下为实际公开 API(按主题分组):

### 登录 / 登出

| 方法 | 说明 |
|------|------|
| `login(id, params: &LoginParams) -> GarrisonResult<String>` | 登录并返回 token |
| `login_simple(id) -> GarrisonResult<String>` | 默认参数登录 |
| `logout() -> GarrisonResult<()>` | 登出当前 token |
| `logout_by_login_id(login_id) -> GarrisonResult<()>` | 按主体登出 |
| `kickout(login_id) -> GarrisonResult<()>` | 踢人下线 |
| `kickout_by_token(token) -> GarrisonResult<()>` | 按 token 踢出 |
| `login_by_token(token) -> GarrisonResult<()>` | 以既有 token 恢复登录态 |
| `invalidate_sessions_after_password_change(...) -> GarrisonResult<()>` | 改密后失效历史会话 |

### 登录态校验

| 方法 | 说明 |
|------|------|
| `check_login() -> GarrisonResult<bool>` | 校验登录状态,未登录抛 `NotLogin` |
| `check_login_sync() -> GarrisonResult<bool>` | 同步版本 |
| `get_login_id() -> GarrisonResult<Option<String>>` | 当前主体 |
| `get_login_id_by_token(token) -> GarrisonResult<Option<String>>` | 按 token 查主体 |

### 权限 / 角色

| 方法 | 说明 |
|------|------|
| `check_permission(permission) -> GarrisonResult<()>` | 校验权限,失败抛 `NotPermission` |
| `check_role(role) -> GarrisonResult<()>` | 校验角色,失败抛 `NotRole` |
| `check_permission_sync(perm)` / `check_role_sync(role)` | 同步版本 |
| `has_permission(permission) -> GarrisonResult<bool>` / `has_role(role)` | 布尔版 |
| `get_permission_list() -> GarrisonResult<Vec<String>>` / `get_role_list()` | 读取当前主体权限 / 角色列表 |

### Token 与协议

| 方法 | 说明 | Feature |
|------|------|---------|
| `verify_token(token) -> GarrisonResult<String>` | 验证 token | — |
| `revoke_token(token) -> GarrisonResult<()>` | 吊销 token(RFC 7009 语义) | — |
| `refresh_token(token) -> GarrisonResult<String>` | RefreshToken 轮换 | `protocol-jwt` |
| `check_access_token()` / `check_client_token()` / `check_temp_token()` | OAuth2 三类 token 校验 | `protocol-oauth2` |
| `check_api_key(namespace) -> GarrisonResult<()>` | API Key 校验(feature 关闭时 fail-closed 返回 `Config` 错误) | `protocol-apikey` |

**Refresh token 重用检测与宽限窗口**(`RefreshTokenRotation`,`protocol-jwt` + `db-sqlite` feature;SQL 面向 SQLite,服务整体 `db-sqlite` 门控):旧 token 重放按三级分类处置(`RecentPrev`/`OrphanedBranch` 按配置分派、`StaleLineage` 恒吊销整条 chain),完整处置表见 [THREAT.md](THREAT.md)。相关 `GarrisonConfig` 字段:

| 字段 | 默认 | 说明 |
|------|------|------|
| `recent_reuse_behaviour` | `TheftDetected` | `RecentPrev`/`OrphanedBranch` 重用处置:`TheftDetected` 吊销整条 chain + `TokenRevoked`;`Unauthorised` 仅拒绝本次(401)不吊销。非法值启动期 fail-fast |
| `refresh_grace_period_secs` | `0`(关闭) | 宽限窗口秒数——窗口内已轮换旧 token 再次呈现返回既有新 token(不重旋转,容忍并发双刷;兑现凭据进程内暂存,多实例仅签发实例命中) |
| `refresh_grace_max_uses` | `1` | 窗口内同一旧 token 最大宽限兑现次数,耗尽后的窗口内重放按 `recent_reuse_behaviour` 处置(默认吊销整条 chain);仅窗口 >0 时生效 |

对应环境变量:`GARRISON_RECENT_REUSE_BEHAVIOUR` / `GARRISON_REFRESH_GRACE_PERIOD_SECS` / `GARRISON_REFRESH_GRACE_MAX_USES`。**生效前提**:上述字段由注入的 `RefreshTokenRotation` 读取——应用经 `TokenHandler::with_refresh_rotation` 注入轮换服务时须同步以 `with_reuse_behaviour` / `with_grace_window` 装配配置值(框架默认不自动装配,未注入时 refresh 走 DAO 退化路径,配置不生效)。

### OAuth2 discovery 与 JWKS 多 kid 轮换(`oauth2-server`)

**Discovery 端点**(`OAuth2State::oidc_discovery_enabled`,默认跟随 `protocol-oidc` feature,可运行时覆写):`GET /.well-known/openid-configuration`(OIDC Discovery 1.0)与 `GET /.well-known/oauth-authorization-server`(RFC 8414)。issuer 未配置或开关关闭 → 404(fail-closed)。元数据从实际能力派生(非静态模板):

| 字段 | 派生来源 |
|------|---------|
| `issuer` / `authorization_endpoint` / `token_endpoint` 等端点路径 | `OAuth2State::issuer` + 固定路由 |
| `grant_types_supported` | token 端点既有能力(authorization_code/refresh_token/client_credentials);`password` 仅在装配方注入 password verifier 并置位 `password_grant_advertised` 后宣告 |
| `scopes_supported` | 注册客户端 scope 并集(运行时查询派生;派生失败 500 显性暴露,空集回退 `openid`) |
| `jwks_uri` / `jwks_algorithms`(id_token 签名算法) | 仅在实际发布 JWKS 时出现(防死链误导客户端) |
| `code_challenge_methods_supported` | PKCE 强制开启 → 仅 `S256` |

响应带 `Cache-Control: public, max-age=300`。

**JWKS 多 kid 轮换**(`oauth2_server::jwks::JwksKeystore`,注入 `OAuth2State::jwks_keystore` 后 JWKS 端点优先从库发布):钥三态 `Active`(签名)/ `Passive`(退役保留验证,仍发布)/ `Disabled`(移出发布与验证面)。三视图语义:签名取 Active、验证取 Active∪Passive(`kid` 命中 Passive 旧钥验证成功;缺失回退 Active;未知 kid 显性报错)、JWKS 输出取 Active∪Passive。轮换经 DAO `compare_and_swap` 账本提交(防多实例竞态:并发轮换恰一成功,失败方读到胜者后的一致状态);Passive 超 `jwks_retention_secs`(默认 7200 = 2× access token TTL,见 [CONFIGURATION.md](CONFIGURATION.md))转 Disabled 并移出 JWKS。JWKS 端点 `Cache-Control: max-age` 按 retention 的一半动态计算。

### authorize 两段式票据与 consent 记忆(`oauth2-server`,R18)

**两段式流程**:`GET /oauth2/authorize` 校验通过(response_type/PKCE S256/redirect 白名单)→ 签发 32 字符随机票据暂存完整请求(TTL 600s)→ `LoginRequired` 重定向登录页(`return_to=/oauth2/authorize/resume?ticket=...`)→ 登录成功后 `GET /oauth2/authorize/resume?ticket=...` 凭会话身份原子消费票据续流签发授权码。票据不绑定主体(续流主体以会话为准);消费一次性(二次消费/过期/未知统一 `invalid_ticket` 显性拒绝,无状态泄露)。

**prompt 语义**(OIDC Core §3.1.2.1,`AuthorizeRequest.prompt` 字段显式出现时生效):`none` → 未登录或 consent 不足一律 `interaction_required`(不弹任何交互页);`login` → 已登录也强制重走登录往返。

**consent 记忆**:键 `oauth2:consent:{tenant}:{user}:{client}` 持久化已授 scope 集合 + 属性快照双粒度哈希(ATTRIBUTE_NAME / ATTRIBUTE_VALUE,SHA-512,`with_attribute_granularity` 可配)。再次授权:请求 scope ⊆ 已授且属性快照未变 → 免征询直接放行;新增 scope → 合并为超集;快照不可解析 → fail-safe 重新征询。`reconcile_consents` 清理已删 client 的孤儿行,幂等;框架 `listen()` 启动时自动执行(fail-open:失败仅告警不阻断启动,下次启动或运维显式调用重试)。

**装配契约**:prompt=none 静默续期以空属性视图比对快照——经征询页批准(非空属性视图)的用户需部署方传入一致属性视图,否则重新触发 `interaction_required`(fail-safe,文档见 `with_consent_url`)。

### 二次认证与封禁

| 方法 | 说明 |
|------|------|
| `check_safe() -> GarrisonResult<()>` | 校验二次认证完成度,未完成抛 `NotSafe { reason }` |
| `check_disable() -> GarrisonResult<()>` | 校验账号封禁状态,被封禁抛 `DisableService { service, until }` |

> 另有 `garrison::stp::util::init_backend(backend)` 初始化后端(`backend-*` 架构面)。

---

## 🎯 token 上下文

`garrison::stp`(`src/stp/context.rs`)— task_local 携带当前 token,Web 中间件已自动绑定:

| 函数 | 说明 |
|------|------|
| `with_current_token(token, fut)` | 在 `fut` 执行期间绑定 token(链式可嵌套) |
| `current_token()` | 读取当前 token(`Option<String>`) |

---

## 🔌 业务回调 GarrisonInterface

`garrison::GarrisonInterface`(`src/stp/interface.rs`)— 业务方实现,提供权限 / 角色数据。

| 方法 | 默认实现 | 说明 |
|------|----------|------|
| `get_permission_list(&self, login_id) -> GarrisonResult<Vec<String>>` | 必须实现 | 指定主体的权限标识列表 |
| `get_role_list(&self, login_id) -> GarrisonResult<Vec<String>>` | 必须实现 | 指定主体的角色标识列表 |
| `get_permission_list_with_type(&self, login_id, login_type)` | 委托 `get_permission_list` | 多账号体系按 `login_type` 隔离(默认策略传入 `with_login_type` 配置的值) |
| `get_role_list_with_type(&self, login_id, login_type)` | 委托 `get_role_list` | 同上(角色维度) |

数据来源由业务方自定(数据库 / 配置 / 外部服务);`GarrisonPermissionStrategyDefault` 拿到列表后做字符串匹配。

---

## 🗄️ 存储层 GarrisonDao

`garrison::GarrisonDao`(`src/dao/mod.rs`)— 统一 KV 抽象,屏蔽 oxcache / dbnexus 后端差异。核心方法(全部 `async`,返回 `GarrisonResult`):

### 基础 KV

| 方法 | 说明 |
|------|------|
| `get(key) -> Option<String>` | 读取 |
| `set(key, value, ttl_seconds)` | 写入(带 TTL) |
| `set_permanent(key, value)` | 永久写入(默认实现 `set` ttl=0) |
| `set_if_absent(key, value, ttl_seconds)` | 不存在才写入(原子语义) |
| `update(key, value)` | 更新(保留原 TTL) |
| `expire(key, seconds)` | 重设 TTL |
| `get_timeout(key) -> Option<Duration>` | 读取剩余 TTL(默认实现返回 `NotImplemented`) |
| `get_with_ttl(key) -> Option<(String, Option<Duration>)>` | 值 + 剩余 TTL |
| `delete(key)` | 删除 |
| `keys(pattern) -> Vec<String>` | 按模式列举 |
| `rename(old_key, new_key)` | 重命名(缺键返回 `InvalidParam`,原子保留原 TTL) |
| `get_and_delete(key) -> Option<String>` | 原子取出并删除 |
| `incr(key, ttl_seconds) -> u64` / `decr(key) -> u64` | 原子计数 |

### 扩展契约

| 方法 | 说明 | Feature |
|------|------|---------|
| `compare_and_update_if_greater(...)` | 数值比较后更新(限流计数基座) | — |
| `compare_and_swap(...)` | CAS | — |
| `find_social_binding(...)` / `insert_social_binding(...)` | 社交账号绑定 | `social-*` |
| `query_role_hierarchy_edges(...)` / `insert_role_hierarchy_edge(...)` / `delete_role_hierarchy_edge(...)` | 角色层级边存储 | — |
| `eval_lua(...)` | Lua 脚本(redis 面下透传) | `cache-redis` |
| `insert_credit_consumption(...)` / `query_credit_consumption(...)` | 计量消费记录 | `credit-metering` |

### 内置实现

| 类型 | Feature | 说明 |
|------|---------|------|
| `GarrisonDaoOxcache` | `cache-memory` / `cache-redis` | L1 内存(per-entry TTL,精确语义:显式 `ttl_jitter(0.0)`)+ L2 redis |
| dbnexus DAO | `db-sqlite` / `db-postgres` / `db-mysql` | SQL 持久化 + Repository 层(见下) |
| 内存 Mock DAO | — | `src/stp/mock.rs`(测试用) |

### 契约测试套件 `dao::testing`

多后端同一把尺子:组断言函数库按能力分层,`dao_conformance_tests!` 宏对每个
`GarrisonDao` 实现(内置或自定义)实例化运行。`cfg(test)` 下随单元测试执行;
`testing` feature 构建面开放给下游复用。

| 组断言函数 | 能力层 | 内容 |
|-----------|--------|------|
| `run_basic(&Arc<dyn GarrisonDao>, prefix)` | `basic` | get/set/update/delete/expire、永久键、get_with_ttl 三态、incr/decr 全语义、CAS-if-greater、rename(缺键 `InvalidParam`) |
| `run_atomic(&Arc<dyn GarrisonDao>, prefix)` | `atomic` | set_if_absent / get_and_delete / compare_and_swap 单线程原子语义 |
| `run_concurrent(&Arc<dyn GarrisonDao>, prefix)` | `concurrent` | multi_thread 真并发:SETNX 恰一赢家、GETDEL 一次性消费、incr/decr 返回值排列恰一、CAS 单调 |
| `run_ttl(&Arc<dyn GarrisonDao>, prefix)` | `ttl` | 过期不复活、update/rename/incr 保留原窗口、`expire(k, 0)` 转永久(墙钟,单次 sleep 3s) |
| `run_keys(&Arc<dyn GarrisonDao>, prefix)` | `keys` | glob `*`/`?` 精确匹配、空 Vec、delete/rename 扫描同步 |

一行接入(自定义后端):

```rust
garrison::dao_conformance_tests! {
    backend: my_dao,
    make: || async { MyDao::new().await.map(|d| Arc::new(d) as Arc<dyn GarrisonDao>) },
    caps: [basic, atomic, concurrent],   // 未声明的层不生成测试
    // serial: true,                      // 可选:#[serial_test::serial](仅测试构建)
    // ignore: "requires X",             // 可选:#[ignore = "..."]
}
```

`make` 每测试新建空实例(每测试全新存储,兼容共享存储后端);全部键名以
`<backend>:` 前缀隔离;构造失败 panic(fail-loud)。

---

## 🧮 权限策略

`garrison::GarrisonPermissionStrategy`(`src/strategy/`)— 鉴权决策入口,可整体替换:

| 项 | 说明 |
|----|------|
| `GarrisonPermissionStrategyDefault` | 默认实现:经 `GarrisonInterface` 回调取数据后字符串匹配;`with_login_type` 设置多账号 login_type |
| `firewall_hook_injected()` | 诊断方法,返回防火墙钩子是否已被 builder 注入 |
| ABAC | `abac` feature:Cedar DSL 策略引擎(`garrison::abac`),`#[check_abac]` 注解 + `set_abac_missing_feature_policy` 逃生门 |
| 决策溯源 | `core-advanced`:`authorize(AuthRequest) -> Decision`(`Allow` / `Deny` + `DecisionReason`) |

---

## 💼 会话与状态

| 类型 | 说明 |
|------|------|
| `GarrisonSession`(`src/session/`) | 会话操作面;`session::dao()` 无 feature 门控,对 crate 内 `pub(crate)` 开放(调用方含 `protocol-apikey` / `db-postgres` / `db-mysql` / `cache-redis` / `protocol-jwt`) |
| `TokenState`(`src/state/`,crate 根 re-export) | token 状态机 |
| `UserStatus` | 用户状态枚举(同样经 crate 根 re-export) |
| `GarrisonPrincipal` / `TenantContext` / `TENANT`(`src/context/`) | 请求主体与租户上下文(`tenant-isolation`);`TENANT.scope(tenant, fut)` 进入租户作用域 |
| `ClaimTenantResolver` | 从 claim 解析租户的 resolver |

---

## 🌐 Web 集成与注解宏

### 路由与拦截

| 类型 | 说明 |
|------|------|
| `GarrisonRouter` | 统一路由抽象;actix 面提供 `with_tenant_resolver(resolver)` / `with_header_tenant()` |
| `GarrisonInterceptor` | 请求拦截器,进入 `GarrisonUtil` 静态 API |
| `garrison::web`(`web-axum`) | axum extractor 与中间件 |
| `garrison::web_actix` / `garrison::web_warp` | actix-web / warp 适配 |
| `garrison::grpc`(`grpc`) | tonic auth layer |

### Set-Cookie 单一构建点(context 层,always-on)

`garrison::context::cookie` — 全部 Set-Cookie 写路径(三框架适配器、axum 续签中间件、CSRF 中间件)的唯一产出点,纯函数、无框架依赖:

| 类型 / 函数 | 说明 |
|------|------|
| `CookieScope` | SameSite × HttpOnly 合法组合封闭枚举:`LaxHttpOnly` / `StrictHttpOnly` / `NoneHttpOnly`(HttpOnly 恒定) |
| `CookiePath` | 路径作用域:`Root`(`Path=/`)/ `Of(String)`(预留:短时 token 限定路径,当前无生产写点) |
| `CookieType` | 构建参数(`name` / `scope` / `path` / `domain` / `max_age`);`CookieType::token(&config)` 承接会话 token cookie,`session(name, &config)` 承接其他会话 cookie;`resolved_name(secure)` 输出读侧解析名 |
| `build_set_cookie_value(&CookieType, value, secure)` | 构建 Set-Cookie 值;校验失败时返回错误,调用方不得产出任何 Set-Cookie |
| `token_cookie_name(&config)` | 会话 token cookie 读侧统一入口(与写侧产出同名) |

不变式(由构建点强制,写点无法绕过):

1. **HttpOnly 恒定**:三个 `CookieScope` 变体均输出 HttpOnly。
2. **SameSite 白名单 fail-fast**:非 `["Lax", "Strict", "None"]` 返回错误(合法值与启动期配置校验白名单 `COOKIE_SAME_SITE_VALUES` 一一对应,由跨引用测试锁定漂移)。
3. **None→Lax 降级**:`cookie_secure=false`(非 Secure 上下文确定性信号)时 `SameSite=None` 降级为 `Lax`(warn 一次)。
4. **production 前缀**:`production` feature + Secure 上下文时,`Path=/` 且无 Domain → `__Host-<name>`;限定路径或带 Domain → `__Secure-<name>`;http 降级无前缀。读侧必须经 `token_cookie_name` / `CookieType::resolved_name` 同名解析。
5. **注入防护**:name/value 复用 `validate_cookie_name_value`,拒绝 `;`、控制字符等分隔符;path 拒 `;` 与控制字符,domain 仅允许主机名字符(字母数字连字符点)。

### 注解宏(`annotation-macros` feature,过程宏 crate `garrison-macros`)

13 个属性宏(wrapper 生成 axum `Response`):10 个 axum wrapper 宏 + 3 个 sdforge `#[forge]` 路由变体。

| 宏 | 对应校验 |
|----|----------|
| `#[check_login]` | 登录态(`NotLogin` → 401) |
| `#[check_role("...")]` / `#[check_permission("...")]` | 角色 / 权限 |
| `#[check_access_token]` / `#[check_client_token]` / `#[check_temp_token]` | OAuth2 token 类型 |
| `#[check_api_key("...")]` | API Key(feature 关闭时 fail-closed) |
| `#[check_disable]` | 封禁状态 |
| `#[check_mfa]` | 二次认证 |
| `#[check_abac(policy = "...")]` | ABAC 策略(`abac`) |
| `#[check_login_forge]` / `#[check_role_forge]` / `#[check_permission_forge]` | sdforge 动态路由变体 |

---

## 🧩 插件与监听器

| trait | 注册方式 | 说明 |
|-------|----------|------|
| `GarrisonPlugin`(`src/plugin/`) | `inventory::submit!` 编译期注册 | 生命周期钩子注入 |
| `GarrisonListener`(`src/listener/`) | `inventory::submit!` 编译期注册 | 31 个事件变体(Login / Logout / Kickout / PermissionCheck / RoleCheck / TokenExpired / LoginFailure / PasswordRehashed / TokenRefresh / RevokeToken / SessionTimeout / AccountLocked / FirewallBlock / TokenRotate / TempCredentialConsumed / SocialLogin / TenantSwitch / DeviceBlock / DeviceUnblock / ConfigReload / AnomalousLoginDetected / Replaced / CreditConsumed / CreditAlert / InvitationCreated / InvitationRevoked / InvitationRedeemed / QrLoginCreated / QrLoginScanned / QrLoginConfirmed / QrLoginCancelled);trait 侧为单一 `async fn on_event` 回调(非逐事件钩子),事件载荷 token 已统一掩码 |
| `AuditLogListener` / `AuditConfig` / `AuditEntry` / `AuditQuery`(`listener::audit`,`audit-log`) | — | 审计日志监听与查询 |

---

## 🗃️ Repository 层

`db-*` feature 下经 `src/dao/repository/` 提供类型化仓储(13 trait),lib.rs 顶层 re-export 其中 9 个 SQLite 实现:

| Re-export | 说明 |
|-----------|------|
| `DbnexusUserRepository` / `DbnexusRoleRepository` / `DbnexusPermissionRepository` | 用户 / 角色 / 权限 |
| `DbnexusUserRoleRepository` / `DbnexusRolePermissionRepository` | 关联表 |
| `DbnexusAuthMethodRepository` / `DbnexusSessionRepository` / `DbnexusLoginLogRepository` / `DbnexusUserExtRepository` | 认证方式 / 会话 / 登录日志 / 扩展字段 |
| `UserIdentifierRepository`(`app_user_identifier`) | 登录标识(phone / email)原子防重注册。`register` 唯一约束冲突按**租户作用域**回查归属(`find_owner_in_tenant`,SQL 带 `tenant_id` 谓词):同租户冲突返回 `Taken { by_user_id }`;跨租户冲突返回中性 `Registered`(不带 `by_user_id`,不向他租户泄露归属)。`find_owner` 为全局维度反查原语(多租户部署中不可信输入须改用 `find_owner_in_tenant`,避免泄露他租户 user_id) |
| `UserDeviceRepository`(`app_user_device`) | 设备注册与 `MAX_DEVICES` 上限 |
| `WebauthnCredentialRepository`(`app_webauthn_credential`) | WebAuthn 凭据绑定与查询 |
| `PasswordHistoryRepository`(`app_password_history`) | 历史密码 hash(`account-policy` 重用拒绝) |
| `RoleHierarchyService` / `RoleHierarchyRecord` | 角色层级(SQL 占位符按后端自适应) |
| `init_dbnexus_with_pool_config(url, PoolConfig)` | 经 dbnexus `DbPoolBuilder` 透传连接池参数(max/min connections、超时) |

协议层补充 re-export:`RefreshTokenRecord` / `RefreshTokenRotation`(`protocol-jwt`)。

---

## 🔑 密码哈希器(`account-credential`)

`account::credential::password` 提供 `PasswordHasher` trait 与内置实现(`config.password_hasher.build_hasher()` 工厂一键构造):

| API | 说明 |
|-----|------|
| `PasswordHasher::hash(password) / verify(password, hash)` | 同步哈希 / 校验(慢哈希调用点包 `spawn_blocking` 使用) |
| `PasswordHasher::concurrency_gate() -> Option<&Arc<Semaphore>>` | 并发闸门探针(默认 `None`,自定义实现零改动);返回 `Some` 时由池化封装按 permit 串行化哈希执行 |
| `Argon2Hasher::with_params(m, t, p).with_pool(pool_size)` | Argon2id 哈希器 + 并发令牌池(`pool_size` 0 钳制为 1);默认无池(向后兼容) |
| `BcryptHasher::with_cost(cost)` | bcrypt 哈希器,**不入池**(单次执行工作区 KB 级,池化无内存防护收益) |
| `PasswordCredential::verify(input)` | 凭证校验:`spawn_blocking` 下沉 + 有池时受 permit 约束;排队不拒绝 |

**并发令牌池行为注记**:permit 在 `spawn_blocking` 前 async 获取并**移入闭包**——permit 存活期 == 哈希执行期,调用方 future 被取消时孤儿 blocking 任务继续持有 permit 直至完成,Argon2 内存驻留上界在任何取消时序下恒等于 `pool_size × m_cost`(不超卖);等待中的调用异步排队(不拒绝);信号量 `close()` 后显性返回 `Internal("account-argon2-pool-closed::...")`,不静默成功。池大小经 `password_hasher.argon2_pool_size` 配置(区间 `[1, 256]`,默认 1)。

---

## ❗ 错误类型

`garrison::GarrisonError`(`src/error.rs`,`thiserror` 派生)— 统一错误枚举,`GarrisonResult<T> = Result<T, GarrisonError>`。

Display 行为:i18n 基础层无条件编译,`to_string()` 按线程本地 locale 切换中英文(缺省跟随系统语言检测)。

| 变体 | HTTP 语义 | 说明 |
|------|-----------|------|
| `NotLogin(String)` | 401 | 未登录 |
| `NotPermission(String)` / `NotRole(String)` | 403 | 无权限 / 无角色 |
| `InvalidToken(String)` / `ExpiredToken(String)` / `TokenRevoked(String)` | 401 | token 无效 / 过期 / 已吊销(RFC 7009) |
| `Dao(String)` | 500 | 存储层错误 |
| `Config(String)` | 500 | 配置错误(含 fail-closed 的 feature 缺失,如未启用 `protocol-apikey` 时调用 `check_api_key`) |
| `Internal(String)` | 500 | 内部错误 |
| `Session(String)` | 500 | 会话创建 / 查询 / 过期 / 续期错误 |
| `Annotation(String)` | 500 | 注解校验失败 / 组合冲突 |
| `Context(String)` | 500 | GarrisonContext / Request / Response / Storage 异常 |
| `Exception(Box<GarrisonException>)` | — | 业务异常(Box 装载控制枚举体积,越过 `result_large_err` 阈值) |
| `OAuth2(String)` | 500 | OAuth2 协议错误(`error_id` 为 `oauth.error`——格式约束不含数字,故模块段用词根 `oauth`) |
| `Network(String)` / `InvalidResponse(String)` | 502 | 网络层 / 上游响应解析失败(语义互斥) |
| `InvalidParam(String)` | 400 | 参数无效 |
| `NotImplemented(String)` | 501 | default 实现未覆盖 |
| `FirewallBlocked(String)` | 403 | 防火墙拦截(携带 strategy 名与原因,供 audit-log 订阅) |
| `DisableService { service, until }` | 403 | 账号封禁(`until = None` 为永久;不泄露 user_id / tenant_id) |
| `NotSafe { reason }` | 400 | 未完成二次认证(如 `MFA_TOTP_REQUIRED`) |
| `InvalidStateTransition { from, to }` | 500 | 状态机非法转换 |
| `SmsRateLimitExceeded { window }` / `SmsVerifyMaxAttempts` / `SmsCodeNotFound` / `SmsChannelRecycled` | 429/400 | 短信验证码(`sms-rate-limit`) |
| `EmailRateLimitExceeded { window }` 等 | 429/400 | 邮箱验证(`email-verification` 门控变体) |
| `RateLimited { retry_after_secs }` | 429 | 网关层限流(携带 `Retry-After` 响应头;`server` 限流中间件与 limiteron 桥接使用) |

### 统一错误响应体(R04)

`GarrisonError` / `GarrisonException` 的 HTTP 错误响应体(三框架 axum / actix-web / warp 形状一致):

```json
{
  "error_code": "NOT_LOGIN",
  "error_id": "auth.not_login",
  "message": "Not logged in",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

- `error_code`:**旧码**(`UPPER_SNAKE_CASE`),冻结原值继续输出,不 deprecate。
- `error_id`:**新码**(模块前缀 `<module>.<snake>`),新旧并存;单一事实来源为
  `parts_and_msg_key` 私有函数(逐 arm 显式静态书写,非自动派生)。API 为
  `GarrisonError::prefixed_code()`。
- `request_id`:当前请求的 request id(`X-Request-ID` 中间件注入 task-local)。
  **无 request id 时该字段省略**(omitempty 语义)。
- `Exception` 变体额外含 `code` 字段(`i32` 业务码)。
- `message`:i18n 化通用描述,不含变体 detail(防泄露)。

旧码 → `error_id` 对照表(全量,`Exception` 变体按业务 `code` 三分为 `exception.*`):

| 旧 error_code | error_id | 旧 error_code | error_id |
|---------------|----------|---------------|----------|
| `NOT_LOGIN` | `auth.not_login` | `NOT_SAFE` | `auth.not_safe` |
| `INVALID_TOKEN` | `auth.invalid_token` | `INVALID_STATE_TRANSITION` | `state.invalid_transition` |
| `TOKEN_REVOKED` | `auth.token_revoked` | `RATE_LIMITED` | `ratelimit.rate_limited` |
| `EXPIRED_TOKEN` | `auth.expired_token` | `SMS_RATE_LIMIT_EXCEEDED` | `sms.rate_limit_exceeded` |
| `NOT_PERMISSION` | `auth.not_permission` | `SMS_VERIFY_MAX_ATTEMPTS` | `sms.verify_max_attempts` |
| `NOT_ROLE` | `auth.not_role` | `SMS_CODE_NOT_FOUND` | `sms.code_not_found` |
| `DAO_ERROR` | `dao.error` | `SMS_CHANNEL_RECYCLED` | `sms.channel_recycled` |
| `CONFIG_ERROR` | `config.error` | `EMAIL_RATE_LIMIT_EXCEEDED` | `email.rate_limit_exceeded` |
| `INTERNAL_ERROR` | `internal.error` | `EMAIL_VERIFY_MAX_ATTEMPTS` | `email.verify_max_attempts` |
| `SESSION_ERROR` | `session.error` | `EMAIL_CODE_NOT_FOUND` | `email.code_not_found` |
| `ANNOTATION_ERROR` | `annotation.error` | `EMAIL_CHANNEL_RECYCLED` | `email.channel_recycled` |
| `CONTEXT_ERROR` | `context.error` | `CREDIT_INSUFFICIENT` | `credit.insufficient` |
| `OAUTH2_ERROR` | `oauth.error` | `NOT_LOGIN`(Exception -1) | `exception.not_login` |
| `NETWORK_ERROR` | `network.error` | `NOT_PERMISSION`(Exception -2) | `exception.not_permission` |
| `INVALID_RESPONSE` | `network.invalid_response` | `EXCEPTION`(其他) | `exception.default` |
| `INVALID_PARAM` | `validation.invalid_param` | | |
| `NOT_IMPLEMENTED` | `internal.not_implemented` | | |
| `FIREWALL_BLOCKED` | `firewall.blocked` | | |
| `DISABLE_SERVICE` | `account.disable_service` | | |

响应头语义(头名为**固定常量,非配置项**,见 ADR-0004):

| 头 | 语义 | 条件 |
|----|------|------|
| `X-Request-ID` | 回传请求标识(入站合法原样回传;非法/缺失回传生成的 UUID v4) | 挂载 request id 中间件后所有响应 |
| `Retry-After` | delta-seconds 整数秒(下限 1),仅 `RateLimited` 变体 | `retry_after_secs()` 为 `Some` |

入站 `X-Request-ID` 校验(不可信输入):非空、长度 ≤ 128、全部可见 ASCII
(`0x21..=0x7E`);CRLF / 非 ASCII / 超长即丢弃重新生成,防 header / 日志注入。

---

## 🗺️ 模块地图

`src/lib.rs` 公开模块(无标注为总编译核心;其余按 feature 门控,功能矩阵见 [README · 特性标志](../README.md#-特性标志)):

| 模块 | 说明 |
|------|------|
| `stp` | 静态门面层(登录 / 校验 / token 上下文 / util) |
| `core` / `manager` / `strategy` / `session` / `dao` | 核心引擎 |
| `annotation` / `router` | 注解与路由 |
| `config` / `context` / `state` / `json` / `exception` / `constants` / `error` / `prelude` | 配置 / 上下文 / 状态 / JSON 模板 / 异常 / 常量 / 错误 / 预导出 |
| `plugin` / `listener` | 插件 / 事件监听 |
| `cache`(`cache-*`) | 缓存后端 |
| `limiteron` | 分布式限流适配(无条件编译,公共基座) |
| `credit`(`credit-metering`) | 计量 |
| `secure`(`secure-*`) | 安全工具集 |
| `account`(`account-*`) | 账号安全引擎 |
| `protocol`(`protocol-*`) | 认证协议层 |
| `protocol::qrlogin`(`protocol-qrlogin`) | 第一方扫码登录(两票分离状态机 + HMAC 签名票据) |
| `abac`(`abac`) | Cedar 属性访问控制 |
| `compliance`(`data-erasure`) | 数据擦除服务与擦除报告 |
| `web` / `web_actix` / `web_warp`(`web-*`) | Web 框架适配 |
| `server`(`auth-server`) | 独立认证服务器 |
| `oauth2_server`(`oauth2-server`) | OAuth2 Server |
| `backend`(`backend-*`) | 后端架构(embedded / remote / kit) |
| `grpc`(`grpc`) | gRPC 拦截器 |
| `observability`(`tracing-log` / `metrics-prometheus` / `otlp`) | 可观测性 |
| `health` | 健康检查 |
| `testing`(`testing`) | 测试辅助(验收矩阵配套) |

`protocol::qrlogin`(`protocol-qrlogin`)经 `GarrisonAuthServer::with_qrlogin` 装配后暴露 4 个 HTTP 端点(create / poll 匿名,scan / confirm 需 Bearer App 会话 token):

| 端点 | 认证 | 说明 |
|------|------|------|
| `POST /qrlogin/create` | 匿名 | Web 端创建扫码会话(响应含 qr_id + bind_token 双票) |
| `POST /qrlogin/poll` | 匿名 | 双票轮询,Confirmed 时原子消费 bind_token 兑换并签发会话 |
| `POST /qrlogin/scan` | Bearer App token | App 扫码,服务端锁定扫码者身份(失败 401) |
| `POST /qrlogin/confirm` | Bearer App token | App 确认(强制确认者与扫码者一致,不信任请求体) |

---

## 🆕 rc.3 安全审计整改新增能力 API

> 以下为 0.9.0-rc.3 新增/扩充的公开 API 速览(完整签名以 rustdoc 为准),按能力域归并。

### 落库字段静态加密(`secure::encryption`,`field-encryption`)

`CryptoValue`(`enc:v1:<key_id>:<base64(nonce|ciphertext)>` 编解码:`encode` / `decode` / `is_clean` / `is_digest_form`)· `AadBinding`(绑定 `garrison:{tenant}:{table}:{key}`)· `FieldCipher`(`encrypt` / `decrypt` / `seal` / `open`)· 密钥提供者 `StaticFieldKeyProvider`(`new` / `with_primary`)与 `ConfersFieldKeyProvider`(`from_key_entries`)· `FieldEncryptionDao`(透明加解密切换 DAO)· 运维报告 `ChangeKeyReport` / `CheckKeyReport`。

### WebAuthn / Passkey(`protocol::webauthn`,`protocol-webauthn`)

`WebauthnService`(注册/认证仪式编排)· `RelyingParty`(从 issuer 派生 rp_id/origins)· `WebauthnCredential`(`to_row` / `from_row` / `to_passkey`)· `ChallengeStore`(一次性消费防重放)· `ChallengePayload` / `FactorPurpose` / `FactorPolicy` / `WebauthnConfig`(passwordless / second_factor 双 policy)· `WebauthnAuthentication` · `WebauthnCeremonyError`。

### 找回密码(`account::password_reset`,`account-password-reset`)

`ActionTokenService`(`issue` / `verify` / `with_ttl` / `with_rate_limit`)· `ActionTokenClaims` · `ActionTokenConsumer`(一次性消费)· `IssuedActionToken` · `EmailResetMailSender`(防枚举,复用 email-verification 设施)。

### OIDC Back-Channel Logout(`oauth2_server::backchannel`,`backchannel-logout`)

`BackChannelLogoutListener`(挂 session 登出事件入队)· `BackChannelDeliverer`(`queue` / `issue` / `spawn_drain_loop` / `has_activity` / `retry_backoff_millis` / `with_backoff` / `with_queue`;禁止跟随重定向 + 指数退避)。

### MFA / step-up 编排基座(`stp::mfa`,`mfa-recovery` 等)

`AmrEntry`(会话因子账本)· `RequiredActionProvider`(三段式 trait:evaluate→challenge→process)及其 `TotpRequiredActionProvider` / `WebauthnRequiredActionProvider` 实现 · `RequiredActionChallenge` / `RequiredActionContext` · `RecoveryCodeManager`(verify/consume 分离、CAS 原子消费)· `MfaChainDecision` · `resolve_mfa_chain` / `validate_mfa_chains` / `first_unmet_chain_factor` / `ledger_max_aal` / `assert_freshness` / `amr_claim`。

### 弃用配置键注册表(`config::deprecation`,always-on)

`Deprecation`(`key` / `since_version` / `new_key` / `auto_map` / `map_fn`)· `apply_deprecations`(加载期迁移/告警,`current_version ≥ 1.0.0` 起 fail-closed)· `is_mappable`。

---

## 🆕 rc.4 限流后端切换新增 API(`rate-limit-redis`)

| 项 | 说明 |
|----|------|
| `limiteron::LimiterBackend` | 限流执行面 trait(`DistributedLimiter` 超集):`atomic_check_and_incr` / `reset_prefix` / `allow_sliding_window`(`firewall-ratelimit` 门控) |
| `limiteron::LimiterRuntime` | 限流运行时(`limiter()` / `storage()`);`dao(dao)` 为默认 DAO 后端;`from_config(&GarrisonConfig, dao).await` 按 `rate_limit_backend` 选择 Memory/Redis |
| `limiteron::RedisLimiterBackend` | Redis 运行时(`rate-limit-redis` 门控):oxcache `RedisBackend` + limiteron `RedisDistributedLimiter`;实现 `LimiterBackend` + `Storage` |
| `strategy::firewall::RateLimitStrategy::with_runtime` | 以显式运行时构造策略 |
| `strategy::firewall::RateLimitStrategy::from_garrison_config` | 按应用配置构造(`rate-limit-redis` 门控);连接失败 fail-closed |
| `strategy::hooks::GarrisonFirewallCheckHookDefault::with_limiter_backend` | 为登录防火墙 hook 注入独立限流后端 |

## 📚 相关文档

| 文档 | 说明 |
|------|------|
| [📖 用户指南](USER_GUIDE.md) | 从安装到进阶的完整使用教程 |
| [🏗️ 架构文档](ARCHITECTURE.md) | 设计原则、模块划分与数据流 |
| [⚙️ 配置指南](CONFIGURATION.md) | `GarrisonConfig` 全量配置项 |
| [🧪 测试场景矩阵](TEST_SCENARIOS.md) | 验收场景穷举与特性组合矩阵 |
| [💻 在线 API 文档](https://docs.rs/garrison) | docs.rs 自动生成的最新文档 |