garrison 0.8.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
# Garrison 架构设计文档

> Garrison 是面向 Rust 生态的身份认证鉴权框架。
>
> - 版本:0.7.0(微服务架构 + ABAC/Cedar + OAuth2 Server + 架构加固 + 依赖优化:backend-remote / Auth Server / ABAC 引擎 / OAuth2 Server 4 端点 / secure-sanitize / 错误类型统一 / mod.rs 加固)
> - 运行时:tokio 1.x
> - Web 适配:axum 0.8 / actix-web 4 / warp 0.4
> - 存储:dbnexus 0.4(SQLite / PostgreSQL / MySQL + auto-migrate)+ Repository 层(10 trait + SqliteRepository,tenant_id 隔离)
> - 缓存:oxcache 0.3(L1 内存 + L2 redis,per-entry TTL + ttl_sync 查询)
> - License:Apache-2.0
> 配置相关字段说明详见 [configuration.md]./CONFIGURATION.md;开发规范详见 [development.md]./DEVELOPMENT.md。

---

## 一、架构概览

Garrison 采用 **双抽象层 + 全局单例** 架构,核心设计目标:

1. 业务代码只面向 trait 编程,存储后端可平滑替换;
2. 启动时一次性注入依赖,运行期零状态调用,业务代码通过 `GarrisonManager` 静态 API 即可使用。

### 1.1 双抽象层

- **DAO 抽象层**:`GarrisonDao` trait 屏蔽存储后端差异,底层由 `dbnexus`(数据库)+ `oxcache`(缓存)实现,切换 SQLite / PostgreSQL / MySQL 时上层无需改动。
- **缓存抽象层**:`oxcache` 0.3 提供 L1(oxcache 内存层)+ L2(redis 分布式)两级缓存,支持 per-entry TTL 精细化过期控制,对上层呈现统一 `get / set / remove` 语义。

### 1.2 全局单例

- `GarrisonManager` 通过 `parking_lot::RwLock` 持有 `Arc<GarrisonLogicDefault>`(v0.5.2 起 `GarrisonLogic` trait 拆分为 `GarrisonCore` base trait + 5 个子 trait:`SessionLogic` / `PermissionLogic` / `TokenLogic` / `MfaLogic` / `PasswordLogic`),启动时调用 `GarrisonManager::init()` 一次性注入 dao / config / interface。
- `GarrisonLogicFactoryEntry` 通过 `inventory::submit!` 在编译期注册,运行时由 `inventory::iter` 选取默认实现。
- `GarrisonUtil` 暴露静态方法(`login` / `check_login` / `logout` 等),内部全部委托 `GARRISON_MANAGER` 单例,业务侧零状态调用。

### 1.3 双模会话

Garrison 同时维护两种会话维度:

- **Account-Session**:以 `login_id` 为 key,存储账号级长生命周期数据(角色、权限、用户画像)。
- **Token-Session**:以 `token` 为 key,存储该次登录的临时数据(设备、登录时间、临时授权)。

由 `is_share` / `is_concurrent` 配置控制多端共享与并发登录策略。

---

## 二、模块划分

Garrison 分为四层模块,由 feature flag 控制编译裁剪:

```mermaid
graph TB
    subgraph CoreLayer["核心模块(always on)"]
        core[core<br/>token / permission / auth]
        stp[stp<br/>GarrisonCore + 5 个子 trait / GarrisonUtil]
        session[session<br/>GarrisonSession]
        config[config<br/>GarrisonConfig]
        context[context<br/>task_local 上下文]
        dao[dao<br/>GarrisonDao trait]
        strategy[strategy<br/>GarrisonPermissionStrategy]
        manager[manager<br/>GarrisonManager 单例]
        annotation[annotation<br/>注解枚举]
        router[router<br/>GarrisonRouter]
        json[json<br/>JSON 模板]
        exception[exception<br/>异常类型]
        plugin[plugin<br/>插件 trait]
        account[account<br/>凭证 / 密码策略 / 锁定 / 认证流]
        listener[listener<br/>事件监听器]
        error[error<br/>GarrisonError]
        health[health<br/>健康检查]
        state[state<br/>运行时状态]
        i18n[i18n<br/>国际化基础层]
        constants[constants<br/>常量定义]
        prelude[prelude<br/>预导入]
    end

    subgraph ProtocolLayer["协议层(feature 门控)"]
        protocol-jwt[protocol-jwt]
        oauth2[protocol-oauth2]
        sso[protocol-sso]
        sign[protocol-sign]
        apikey[protocol-apikey]
        temp[protocol-temp]
        oidc[protocol-oidc<br/>0.4.0 新增]
        scope-handler[oauth2-scope-handler<br/>0.4.0 新增]
        sso-server[protocol-sso-server<br/>0.4.0 新增]
    end

    subgraph ExtensionLayer["扩展层(feature 门控,0.4.0 新增)"]
        alone-cache[alone-cache<br/>多实例隔离]
        parameter-query[parameter-query<br/>参数化查询]
    end

    subgraph SecureLayer["安全层(feature 门控)"]
        secure-totp[secure-totp]
        secure-sign[secure-sign]
        httpbasic[secure-httpbasic]
        httpdigest[secure-httpdigest]
        sms[sms-rate-limit]
        confusable[secure-confusable]
        masking[secure-masking]
        sanitize[secure-sanitize]
        xss[secure-xss]
    end

    subgraph InfraLayer["基础设施"]
        oxcache[oxcache 0.3<br/>L1 内存 + L2 redis]
        dbnexus[dbnexus 0.4<br/>SQLite / PostgreSQL / MySQL + auto-migrate]
        sdforge[sdforge 0.4<br/>声明式路由]
        trait-kit[trait-kit 0.3<br/>typestate DI]
    end

    subgraph ServerLayer["服务器层(feature 门控)"]
        auth-server[auth-server<br/>独立认证服务器]
        oauth2-server[oauth2-server<br/>OAuth2 授权服务器]
        grpc[grpc<br/>gRPC 拦截器]
        backend-remote[backend-remote<br/>远程后端]
    end

    subgraph WebLayer["Web 安全层(feature 门控)"]
        web-axum[web-axum<br/>axum 适配]
        web-actix[web-actix<br/>actix-web 适配]
        web-warp[web-warp<br/>warp 适配]
        waf[web-waf<br/>WAF]
        cors[web-cors<br/>CORS]
        csrf[web-csrf<br/>CSRF]
    end

    subgraph Observable["可观测性(feature 门控)"]
        listener-events[listener<br/>事件监听]
        metrics[metrics-prometheus<br/>Prometheus 指标]
        tracing[tracing-log<br/>结构化日志]
        otlp[observability-otlp<br/>OTLP 分布式追踪]
    end

    CoreLayer --> InfraLayer
    ProtocolLayer --> CoreLayer
    ExtensionLayer --> CoreLayer
    SecureLayer --> CoreLayer
    Observable --> CoreLayer
    ServerLayer --> CoreLayer
    ServerLayer --> InfraLayer
    WebLayer --> CoreLayer
```

### 2.1 核心模块(always on,无 feature flag)

| 模块 | 职责 |
|------|------|
| `core/` | 核心层:`core/token`(Token 生成校验)、`core/permission`(权限校验)、`core/auth`(登录鉴权) |
| `stp/` | `GarrisonCore` + 5 个子 trait(`SessionLogic` / `PermissionLogic` / `TokenLogic` / `MfaLogic` / `PasswordLogic`)+ `GarrisonInterface` trait + `GarrisonUtil` 静态门面 |
| `session/` | `GarrisonSession` 会话模型(Account + Token 双模) |
| `config/` | `GarrisonConfig` 全局配置 + 热更新 |
| `context/` | `GarrisonContext` 请求上下文抽象 + axum 适配器 + task_local |
| `dao/` | `GarrisonDao` trait + dbnexus 实现 |
| `strategy/` | `GarrisonPermissionStrategy` 权限策略 |
| `manager/` | `GarrisonManager` 全局单例 + inventory 编译期注册 |
| `annotation/` | 鉴权注解枚举 |
| `router/` | `GarrisonRouter` + Interceptor 路由拦截 |
| `json/` | JSON 模板与序列化抽象 |
| `exception/` | 框架异常类型 |
| `plugin/` | `GarrisonPlugin` trait 与编译期注册 |

### 2.2 协议层(feature 门控,默认关闭)

| 模块 | Feature | 说明 | 引入版本 |
|------|---------|------|---------|
| `protocol/jwt` | `protocol-jwt` | JWT 签发与验证(HS256/HS512 + refresh) | 0.2.0 |
| `protocol/oauth2` | `protocol-oauth2` | OAuth2 四种模式(授权码 / 客户端凭证 / 密码 / RefreshToken) | 0.2.0(0.4.0 扩展 RefreshToken) |
| `protocol/sso` | `protocol-sso` | SSO 单点登录 ticket(一次性 60s TTL) | 0.2.0 |
| `protocol/sign` | `protocol-sign` | API 签名 + nonce 防重放 | 0.2.0 |
| `protocol/apikey` | `protocol-apikey` | API Key 认证(生成/校验/吊销/轮换) | 0.2.0 |
| `protocol/temp` | `protocol-temp` | 临时凭证(issue/get/revoke/consume) | 0.2.0 |
| `protocol/oauth2/oidc` | `protocol-oidc` | OIDC id_token 签发/验证 + discovery + 三重防重放(iss/aud/nonce) | 0.4.0 |
| `protocol/oauth2/scope` | `oauth2-scope-handler` | `ScopeHandler` trait + `ScopeRegistry` 注册表,OAuth2Client 委托校验 | 0.4.0 |
| `protocol/sso/server` | `protocol-sso-server` | `SsoServer` trait + `CenterIdConverter` + `SsoChannel` + `DefaultSsoServer` | 0.4.0 |
| `protocol/sso/saml` | `protocol-sso` | SAML 2.0 骨架:`SamlProvider` trait + `DefaultSamlProvider`(quick-xml 解析) | 0.6.0 |
| `protocol/sso/oidc` | `protocol-sso` | OIDC RP 骨架:`OidcProvider` trait + `DefaultOidcProvider`(discovery + token exchange) | 0.6.0 |
| `protocol/sso/channel` | `cache-redis` + `protocol-sso-server` | `RedisPubSubSsoChannel`:Redis pub/sub 跨实例 SsoChannel 实现 | 0.6.0 |

### 2.3 扩展层(feature 门控,默认关闭,0.4.0 新增)

| 模块 | Feature | 说明 |
|------|---------|------|
| `dao/alone_cache` | `alone-cache` | `AloneCache` 装饰器(实现 GarrisonDao,key_prefix 隔离)+ `AloneCacheManager`(多实例管理) |
| `stp/parameter` | `parameter-query` | `ParameterQuery` trait + `ParameterQueryBuilder`(链式 with_login_id/with_device/with_token + async check_permission/check_role) |

### 2.4 安全层(feature 门控,默认关闭)

| 模块 | Feature | 说明 |
|------|---------|------|
| `secure/totp` | `secure-totp` | TOTP 动态验证码(RFC 6238) |
| `secure/sign` | `secure-sign` | HMAC 签名工具 |
| `secure/httpbasic` | `secure-httpbasic` | HTTP Basic 认证 |
| `secure/httpdigest` | `secure-httpdigest` | HTTP Digest 认证 |
| `secure/sms` | `sms-rate-limit` | SMS 验证码限速 |
| `secure/confusable` | `secure-confusable` | Unicode 同形异义字检测 |
| `secure/masking` | `secure-masking` | 敏感数据脱敏(regex 真实脱敏) |
| `secure/sanitize` | `secure-sanitize` | 通用输入消毒 |
| `secure/xss` | `secure-xss` | XSS 防护 |

---

## 三、关键 trait 关系图

Garrison 的核心抽象通过 trait 解耦,业务方实现 trait 即可接入:

```mermaid
graph LR
    BC[GarrisonCore<br/>base trait]
    SL[SessionLogic<br/>会话逻辑 trait]
    PL[PermissionLogic<br/>权限逻辑 trait]
    TL[TokenLogic<br/>Token 逻辑 trait]
    ML[MfaLogic<br/>MFA 逻辑 trait]
    PWL[PasswordLogic<br/>密码逻辑 trait]
    BI[GarrisonInterface<br/>业务数据源 trait]
    BD[GarrisonDao<br/>持久化抽象 trait]
    BS[GarrisonSession<br/>会话模型]
    BCtx[GarrisonContext<br/>请求上下文 trait]
    BFS[GarrisonPermissionStrategy<br/>权限策略 trait]
    BM[GarrisonManager<br/>全局单例]
    BU[GarrisonUtil<br/>静态门面]

    BU --> BM
    BM --> BLD[GarrisonLogicDefault<br/>聚合实现]
    BLD --> BC
    SL --> BC
    PL --> SL
    TL --> SL
    ML --> SL
    PWL --> SL
    BLD --> BS
    BLD --> BFS
    BLD --> BCtx
    BS --> BD
    BLD --> BI
    BD --> oxcache[oxcache 0.3<br/>L1 内存 + L2 redis]
    BD --> dbnexus[dbnexus 0.4<br/>SQLite / PostgreSQL / MySQL]
```

### trait 职责说明

| trait | 职责 | 默认实现 |
|-------|------|---------|
| `GarrisonCore` | base trait(1 方法) | `GarrisonLogicDefault` |
| `SessionLogic` | 会话逻辑:登录、登出、校验、kickout(13 方法,继承 GarrisonCore) | `GarrisonLogicDefault` |
| `PermissionLogic` | 权限逻辑:check_permission / check_role / has_permission / has_role / get_permission_list / get_role_list(6 方法,继承 SessionLogic) | `GarrisonLogicDefault` |
| `TokenLogic` | Token 逻辑:check_access_token / check_client_token / check_temp_token / verify_token / refresh_token(5 方法,继承 SessionLogic) | `GarrisonLogicDefault` |
| `MfaLogic` | MFA 逻辑:二级认证与账号禁用校验(5 async 方法 + 2 关联函数,继承 SessionLogic) | `GarrisonLogicDefault` |
| `PasswordLogic` | 密码逻辑:login_with_password(1 方法,继承 SessionLogic) | `GarrisonLogicDefault` |
| `GarrisonInterface` | 业务数据源接入点:查询用户权限、角色等 | 业务方必须实现 |
| `GarrisonDao` | 持久化抽象:session CRUD、token 映射 + `RedisDeploymentMode` 配置 | dbnexus + oxcache 实现 |
| `GarrisonContext` | 请求上下文:读取当前 token、请求头、Cookie | axum adapter 实现 |
| `GarrisonPermissionStrategy` | 权限策略:`check_permission` 判定 | 框架提供默认实现 |
| `SessionExpiryListener` | 会话过期回调:会话过期时触发异步回调(0.6.0 新增) | 框架提供默认实现 |

> 所有 trait 采用 **trait + Default 模式**:框架提供默认实现,业务方可覆盖。任何组件都可被替换为自定义实现,框架默认实现仅在未被覆盖时生效。

---

## 四、数据流:请求处理链路

以 axum 集成为例,一个受保护请求的完整处理链路:

```mermaid
sequenceDiagram
    participant C as Client
    participant AX as axum middleware
    participant TL as task_local CURRENT_TOKEN
    participant BU as GarrisonUtil
    participant BM as GarrisonManager
    participant BL as GarrisonLogicDefault
    participant BS as GarrisonSession
    participant BD as GarrisonDao
    participant OC as oxcache (L1 内存 + L2 redis)
    participant DB as dbnexus (SQLite / PostgreSQL / MySQL)

    C->>AX: HTTP 请求 (Header/Cookie: garrison_token)
    AX->>TL: 提取 token, CURRENT_TOKEN.scope(token, fut)
    AX->>BU: GarrisonUtil::check_login()
    BU->>BM: 委托 GARRISON_MANAGER.logic()
    BM->>BL: logic.check_login()
    BL->>TL: current_token() 读取 token
    TL-->>BL: Some(token)
    BL->>BS: session.get_token_session(token)
    BS->>BD: dao.get_session(token)
    BD->>OC: L1 内存命中?
    alt L1 命中
        OC-->>BD: 命中返回
    else L1 未命中
        BD->>OC: L2 redis 查询
        OC-->>BD: 返回数据
        BD->>OC: 回填 L1 (per-entry TTL)
    end
    BD-->>BS: TokenSession
    BS-->>BL: 会话数据
    BL->>BL: 校验超时 / 活跃超时 / 并发策略
    alt 校验通过
        BL-->>BM: Ok(())
        BM-->>BU: Ok
        BU-->>AX: 通过
        AX-->>C: 200 业务响应
    else 校验失败
        BL-->>BM: Err(GarrisonError::NotLogin)
        BM-->>BU: Err
        BU-->>AX: Err 抛出
        AX-->>C: 401 / 异常 JSON
    end
```

---

## 五、设计决策

### 1. 为什么用 inventory 编译期注册?

**问题**:Rust 无反射,无法在运行时枚举 trait 实现并自动选择。若用运行时注册,需要全局可变状态与锁,增加启动复杂度。

**方案**:

- 使用 `inventory::submit!` 宏在编译期把 `GarrisonLogicFactoryEntry` 注册到全局 link list。
- `GarrisonManager::init()` 启动时遍历 `inventory::iter::<GarrisonLogicFactoryEntry>()`,按 `name` 选定默认实现。
- 优点:**无反射、无运行时开销、跨 crate 注册**,与 feature flag 配合实现按需启用。

### 2. 为什么用 task_local 上下文?

**问题**:async 请求级 token 在 `Arc<dyn GarrisonLogic>` 中无法通过参数传递(trait 方法签名固定),若用 thread_local 则跨 `.await` 不安全。

**方案**:

- `context` 模块定义 `CURRENT_TOKEN: tokio::task_local`。
- axum middleware 在请求入口提取 token 后 `CURRENT_TOKEN.scope(token, fut)` 设置。
- `GarrisonUtil::current_token()` 通过 `CURRENT_TOKEN.get()` 取值,自动落到当前请求作用域。
- 优点:无锁、无穿透、跨 `.await` 安全。

### 3. 为什么用 trait + Default 模式?

**问题**:框架需要提供「开箱即用」的默认行为,同时允许业务方按需替换任一组件。

**方案**:

- 所有核心抽象(`GarrisonCore` + 5 个子 trait / `GarrisonDao` / `GarrisonContext` / `GarrisonPermissionStrategy` / `GarrisonListener`)均以 trait 定义。
- 框架提供默认实现,业务方实现 trait 后通过 `GarrisonManager::init()` 注入即可覆盖。
- 优点:扩展点清晰,符合 Rust 的零成本抽象哲学。

### 4. 为什么用双抽象层(DAO + 缓存)?

**问题**:存储后端多样(SQLite/PostgreSQL/MySQL/Redis),缓存策略多变,业务代码不应感知具体后端。

**方案**:

- `GarrisonDao` trait 定义统一接口(`get_session` / `set_session` / `delete_token` 等),底层由 dbnexus + oxcache 实现。
- `oxcache` 作为缓存抽象,L1 为 oxcache 内存层 LRU,L2 为 redis 分布式,per-entry TTL 精细控制。
- 切换存储后端时仅替换 `GarrisonLogicFactoryEntry` 的实现,**上层零改动**。

### 5. 为什么用 feature 门控?

**问题**:协议/安全/可观测层并非所有项目都需要,强行全量编译会带来依赖膨胀。

**方案**:

- 13 个特性域独立编译,通过 `#[cfg(feature = "...")]` 在编译期裁剪。
- 默认 `default = []`(空),仅核心模块总是编译。
- 聚合特性 `full` / `production` / `development` 一键启用一组特性。

---

## 六、扩展点

### 1. 自定义 GarrisonDao 实现

替换存储后端(如 PostgreSQL / MongoDB / 自研存储):

```rust
#[async_trait]
impl GarrisonDao for MyDao {
    async fn get_session(&self, key: &str) -> GarrisonResult<Option<SessionData>> {
        // 自定义查询逻辑
    }
    // ...
}
```

通过 `GarrisonManager::init()` 注入即可,上层业务代码零改动。

### 2. 自定义 GarrisonLogicFactoryEntry

替换核心逻辑(如自定义 token 生成规则、自定义登录策略):

```rust
inventory::submit! {
    GarrisonLogicFactoryEntry {
        name: "my-logic",
        factory: || Arc::new(MyLogic) as Arc<GarrisonLogicDefault>,
    }
}
```

### 3. 自定义 GarrisonPermissionStrategy

替换权限策略(如基于 ABAC、基于外部策略引擎):

```rust
#[async_trait]
impl GarrisonPermissionStrategy for MyStrategy {
    async fn check_permission(&self, login_id: &str, permission: &str) -> bool {
        // 自定义权限判定
    }
}
```

---

## 七、参考

- 配置字段说明:[configuration.md]./CONFIGURATION.md
- 开发规范与 TDD 工作流:[development.md]./DEVELOPMENT.md
- 版本演进规划:[roadmap.md]./ROADMAP.md
- 部署指南:[deployment.md]./DEPLOYMENT.md
- 早期领域建模参考
- specmark specs:`specmark/specs/*`