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
# ⚙️ Garrison 配置指南

> Garrison 配置由 `GarrisonConfig` 统一管理,支持三级配置源合并与 `tokio::sync::watch` 热更新能力。
>
> - 适用版本:0.9.0-rc.4(核心配置 + JWT / 签名 / SSO / remember-me / Redis 部署模式 / 多租户 / 账号安全引擎 / 微服务架构 / ABAC / OAuth2 Server 等扩展配置;rc.4 起 `rate_limit_backend` 真正驱动限流后端切换)
> - 配置类型:`GarrisonConfig`,实现 `serde::Serialize / Deserialize`
> 架构设计详见 [🏗️ 架构文档](./ARCHITECTURE.md);部署配置详见 [🚀 部署指南](./DEPLOYMENT.md)。

## 📋 目录

- [配置源优先级](#-配置源优先级)
- [完整配置项表](#-完整配置项表)
- [配置文件示例](#-配置文件示例)
- [热更新机制](#-热更新机制)
- [配置校验规则](#-配置校验规则)

---

## 🎯 配置源优先级

<div align="center">

<img src="assets/config-priority.svg" alt="配置优先级" width="800">

</div>

Garrison 配置按以下优先级合并(**高优先级覆盖低优先级**):

```text
环境变量 (GARRISON_*)  >  toml 文件 (garrison.toml)  >  代码默认值 (GarrisonConfig::default_config())
```

| 优先级 | 来源 | 说明 |
|--------|------|------|
| 高 | 环境变量 | 以 `GARRISON_` 前缀 + 字段名大写下划线形式,例如 `GARRISON_TIMEOUT`、`GARRISON_JWT_SECRET` |
| 中 | toml 文件 | 通过 `GarrisonConfig::load(Some(path))` 加载 toml 文件(基于 confers 0.6,文件加载改用 confers `FileSource`——confers 0.6.0-rc.4 起已放行 Windows 盘符前缀,手写的 `TomlContentSource` workaround 已删除) |
| 低 | 代码默认值 | `GarrisonConfig::default_config()` 内联的默认值 |

> 三源合并在 `GarrisonConfig::load()` 阶段完成:先加载 toml(`None` 时使用代码默认值),再由环境变量覆盖,最后 `validate()` 校验。

---

## 📋 完整配置项表

### 2.1 核心配置(0.1.0)

| 字段名 | 类型 | 默认值 | 环境变量 | 说明 |
|--------|------|--------|----------|------|
| `timeout` | `i64` | `2592000` | `GARRISON_TIMEOUT` | 会话超时秒数(默认 30 天,必须 > 0) |
| `active_timeout` | `i64` | `-1` | `GARRISON_ACTIVE_TIMEOUT` | 活跃超时秒数,`-1` 表示不启用(跟随整体会话超时) |
| `is_share` | `bool` | `false` | `GARRISON_IS_SHARE` | 同账号多端是否共享会话 |
| `is_concurrent` | `bool` | `true` | `GARRISON_IS_CONCURRENT` | 是否允许并发登录 |
| `token_name` | `String` | `"garrison_token"` | `GARRISON_TOKEN_NAME` | Cookie / Header 中的 token 字段名 |
| `token_style` | `String` | `"uuid"` | `GARRISON_TOKEN_STYLE` | Token 风格,可选 `uuid` / `random_64` / `simple` / `jwt` |
| `is_read_cookie` | `bool` | `true` | `GARRISON_IS_READ_COOKIE` | 是否从 Cookie 读取 Token |
| `is_read_header` | `bool` | `true` | `GARRISON_IS_READ_HEADER` | 是否从 Header 读取 Token |
| `is_write_header` | `bool` | `true` | `GARRISON_IS_WRITE_HEADER` | 是否在登录后写入 Header |
| `throw_on_not_login` | `bool` | `true` | `GARRISON_THROW_ON_NOT_LOGIN` | 未登录时是否抛出异常(`false` 时返回 `false`) |
| `cookie_secure` | `bool` | `true`(`development` profile 为 `false`) | `GARRISON_COOKIE_SECURE` | Cookie 是否标记 `Secure`(仅 HTTPS 传输);默认随 profile:启用 `development` 聚合特性为 `false`(本地 HTTP 调试),其余为 `true`(rc.4 起,两种 profile 均可显式覆盖) |
| `cookie_same_site` | `String` | `"Lax"` | `GARRISON_COOKIE_SAME_SITE` | Cookie 的 `SameSite` 策略(`Lax` / `Strict` / `None`;`None` 仅在 `cookie_secure=true` 时生效,非 Secure 上下文构建点降级为 `Lax`) |
| `is_read_body` | `bool` | `false` | `GARRISON_IS_READ_BODY` | 是否从请求体读取 Token |
| `is_write_cookie` | `bool` | `false` | `GARRISON_IS_WRITE_COOKIE` | 是否在续签后将新 Token 写入 Cookie |
| `frontend_separation` | `bool` | `false` | `GARRISON_FRONTEND_SEPARATION` | 是否启用前后端分离模式 |
| `session_hover_timeout` | `i64` | `-1` | `GARRISON_SESSION_HOVER_TIMEOUT` | 会话悬停超时秒数(-1 不启用) |
| `auto_renewal_threshold` | `i64` | `-1` | `GARRISON_AUTO_RENEWAL_THRESHOLD` | 自动续签阈值百分比(-1 不启用,0-100) |
| `token_map_cleanup_interval_secs` | `i64` | `300` | `GARRISON_TOKEN_MAP_CLEANUP_INTERVAL_SECS` | token map 清理间隔秒数 |
| `max_login_count` | `u32` | `0` | `GARRISON_MAX_LOGIN_COUNT` | 最大登录数量(0 不限制) |
| `device_binding_mode` | `String` | `"disabled"` | `GARRISON_DEVICE_BINDING_MODE` | 设备绑定模式(`strict` / `loose` / `disabled`) |
| `replaced_login_exit_mode` | `String` | `"old_device"` | `GARRISON_REPLACED_LOGIN_EXIT_MODE` | 顶人下线策略 |
| `overflow_logout_mode` | `String` | `"logout"` | `GARRISON_OVERFLOW_LOGOUT_MODE` | 溢出处理策略 |
| `audit_mask_mode` | `String` | `"partial"` | `GARRISON_AUDIT_MASK_MODE` | 审计日志脱敏模式 |
| `seed_primary_amr` | `bool` | `true` | `GARRISON_SEED_PRIMARY_AMR` | 登录是否向会话播种主认证因子(`amr=["pwd"]` / AAL 1 / `auth_time`)。默认 `true` 保持「login 即主认证」既有契约;**安全敏感部署建议显式 `false`**——凭证委托 / 零凭证 login 路径并未发生密码校验,播种 `pwd` 会向 amr_ledger 与 JWT claim 断言一次从未发生的认证,误导下游 step-up 判定(`assert_freshness` / `ledger_max_aal`)。关闭后会话 `amr_ledger` 为空、`auth_time` 为 `None`、JWT 不携带 `amr`/`auth_time` claim(MFA step-up 追加不受影响) |
| `login_id_max_len` | `u32` | `255` | `GARRISON_LOGIN_ID_MAX_LEN` | stp 登录收口(`login` / `login_with_token` / `login_by_token`)的 login_id 字节长度上限,超限拒绝签发会话;`0` = 框架层不限。HTTP 请求层 `LoginRequest` 反序列化恒按 255 封顶(wire 层不读运行时配置),本配置只可进一步收紧 |
| `require_tenant_bound_jwt` | `bool` | `false` | `GARRISON_REQUIRE_TENANT_BOUND_JWT` | 严格收口:Stateless JWT(`token_style="jwt"` + `jwt_mode=Stateless`)在租户上下文内必须携带签发租户绑定 claim `tid`。默认 `false`——无 `tid` 的存量 token(无租户上下文签发 / 历史签发)放行(向后兼容,绑定语义随 token 自然轮替收敛);`true` 时 `check_login_stateless` 对无 `tid` token 显性拒绝(`stp-check-login-tenant-unbound`),封住存量无绑定 token 不受租户约束的窗口(jti 黑名单跨请求租户命名空间 miss 的吊销逃逸面)。无租户上下文部署不受影响;开启前应确认存量 token 已轮替(或可接受其显性失效)。覆盖范围见下方「租户绑定严格开关覆盖矩阵」:本项仅作用于 Stateless,会话模式由 `require_session_tenant_binding` 覆盖 |
| `require_session_tenant_binding` | `bool` | `false` | `GARRISON_REQUIRE_SESSION_TENANT_BINDING` | 严格收口:会话模式(`jwt_mode=Simple` / `Mixin`)在租户上下文内必须持有会话租户绑定(attr `__garrison_tenant_id`)。默认 `false`——无绑定的存量会话(本字段与绑定机制引入前登录产生,含 `remember_me` 90 天长会话)放行(向后兼容;绑定只在登录时刻写入,存量会话只能靠 TTL 自然过期收敛);`true` 时 `check_login` 对无绑定会话显性报错(`stp-check-login-session-tenant-unbound`),封住旧会话不受租户约束的窗口。无租户上下文部署不受影响;开启前应确认存量无绑定会话已轮替(或可接受其显性失效)。覆盖范围见下方「租户绑定严格开关覆盖矩阵」:本项不覆盖 Stateless(由 `require_tenant_bound_jwt` 覆盖) |

#### 租户绑定严格开关覆盖矩阵

两个开关各覆盖一半,**开启其一不代表全部收紧**:

| `jwt_mode` | token 绑定校验 | 会话绑定校验 |
|---|---|---|
| `Stateless` | `require_tenant_bound_jwt`(读 `tid` claim) | 不适用(无会话存储) |
| `Mixin` | 不校验 `tid`(仅验签) | `require_session_tenant_binding` |
| `Simple` | 不适用 | `require_session_tenant_binding` |

绑定只在登录时刻写入(`create_token_session_inner` 在 `TENANT` 上下文存在时写 attr),框架**不做惰性补绑**——`X-Tenant-Id` 为客户端可控输入,补绑等于把「豁免面」换成「钉定型 DoS」。

### 2.2 扩展配置(0.2.0 新增)

| 字段名 | 类型 | 默认值 | 环境变量 | 说明 |
|--------|------|--------|----------|------|
| `jwt_algorithm` | `String` | `"HS256"` | `GARRISON_JWT_ALGORITHM` | JWT 签名算法,白名单 6 值:`HS256` / `HS384` / `HS512` / `RS256` / `ES256` / `EdDSA`(非对称算法需配套对应私钥 PEM 字段) |
| `jwt_secret` | `String` | `""` | `GARRISON_JWT_SECRET` | JWT 签名密钥(启用 `protocol-jwt` 时必填) |
| `sign_window_seconds` | `i64` | `300` | `GARRISON_SIGN_WINDOW_SECONDS` | API 签名时间窗口(秒),防重放 |
| `sso_ticket_ttl_seconds` | `u64` | `60` | `GARRISON_SSO_TICKET_TTL_SECONDS` | SSO ticket 有效期(秒) |

### 2.3 remember-me 配置(0.6.0 新增)

| 字段名 | 类型 | 默认值 | 环境变量 | 说明 |
|--------|------|--------|----------|------|
| `remember_me_enabled` | `bool` | `false` | `GARRISON_REMEMBER_ME_ENABLED` | 是否启用 remember-me 扩展会话超时 |
| `remember_me_timeout` | `i64` | `7776000`(90 天) | `GARRISON_REMEMBER_ME_TIMEOUT` | remember-me 会话超时秒数(必须 > `timeout`) |

### 2.4 多租户隔离配置(0.5.0 新增)

| 字段名 | 类型 | 默认值 | 环境变量 | 说明 |
|--------|------|--------|----------|------|
| `tenant_isolation.enabled` | `bool` | `false` | `GARRISON_TENANT_ISOLATION__ENABLED` | 是否启用多租户隔离 |
| `tenant_isolation.resolver` | `String` | `"header"` | `GARRISON_TENANT_ISOLATION__RESOLVER` | 租户解析器类型(`header` / `subdomain` / `claim`) |

> 启用后需配合 `tenant-isolation` Cargo feature + `tenant_resolution_middleware` 才能生效。

### 2.5 密码哈希配置(password_hasher)

驱动 `Argon2Hasher` / `BcryptHasher` 的构造参数(`config.password_hasher.build_hasher()` 工厂,产出后经 `with_password_hasher` 注入)。默认值即 OWASP 建议档,选型论证见 [ADR-0001](./adr/0001-argon2id-password-hashing.md)。

| 字段名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `password_hasher.algorithm` | `String` | `"argon2id"` | 新哈希算法(`"argon2id"` / `"bcrypt"`);verify 路径按哈希前缀自动识别,不受本字段影响 |
| `password_hasher.argon2_m_cost` | `u32` | `19456` | Argon2id 内存成本(KiB),下限 19456 |
| `password_hasher.argon2_t_cost` | `u32` | `2` | Argon2id 时间成本(迭代次数),下限 1 |
| `password_hasher.argon2_p_cost` | `u32` | `1` | Argon2id 并行度,下限 1 |
| `password_hasher.argon2_pool_size` | `u32` | `1` | Argon2 并发令牌池大小,允许区间 `[1, 256]`;同时执行中的 Argon2 hash/verify 上限,进程内存驻留上界 ≈ `argon2_pool_size × argon2_m_cost` KiB(任何取消时序下不超卖),等待中的调用异步排队不拒绝。默认 1(secure-by-default);bcrypt 不入池(单次执行工作区 KB 级,池化无内存防护收益,CPU DoS 由限流与 cost 校验承担) |
| `password_hasher.bcrypt_cost` | `u32` | `12` | bcrypt cost,允许区间 `[10, 15]` |
| `password_hasher.allow_weak_argon2_params` | `bool` | `false` | 显式风险接受:允许 `argon2_m_cost` 低于 19456(内存受限部署逃生口),放行时输出 warn 日志 |

**校验规则(`validate_core`,fail-closed)**:`algorithm` 白名单外拒绝;Argon2id `m_cost < 19456` 且未显式风险接受拒绝、`t_cost`/`p_cost` 为 0 拒绝、`argon2_pool_size` 越出 `[1, 256]` 拒绝(0 = 零 permit 永久饥饿,fail-fast;256 × 19 MiB ≈ 4.8 GiB 为误配上界);bcrypt cost 越出 `[10, 15]` 拒绝。

**池大小调优**:环境变量 `GARRISON_PASSWORD_HASHER__ARGON2_POOL_SIZE`。容量模型:Argon2id 单次执行驻留内存 ≈ `argon2_m_cost` KiB(默认 19 MiB),`argon2_pool_size = N` 时进程 Argon2 内存上界 ≈ `N × 19 MiB`;**verify 路径的每 permit 驻留上界按存量哈希内嵌 `m_cost` 计(PHC 自描述)**,混合存量部署(新旧参数并存)按 `max(配置 m_cost, 存量 m_cost)` 评估,不能只按配置 `m_cost`;按 `可接受内存预算 ÷ m_cost` 取值,并保持 `pool_size ≤ 登录 QPS 限流阈值`(限流承担 QPS 维度、池承担内存驻留维度,双层防护)。

> 仅影响**新哈希**;存量哈希参数自 PHC 字符串自描述解析(无需迁移即可 verify),参数升级采用"新密码/重登录时重哈希"自然演进。

### 2.6 JWKS 密钥轮换配置

驱动多 kid JWKS 密钥库(`oauth2_server::jwks::JwksKeystore`,注入 `OAuth2State::jwks_keystore` 后生效;单钥静态形态 `jwks_source` 不受本节影响)。钥状态三态:`Active`(签名)/ `Passive`(轮换退役保留验证,仍发布于 JWKS)/ `Disabled`(退役移出发布与验证面)。

| 字段名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `jwks_retention_secs` | `u64` | `7200` | Passive 钥退役保留时长(秒):轮换后旧钥转 Passive,超此时长转 `Disabled` 并移出 JWKS 发布面(存量旧 token 验证自此失败,需重新认证)。默认 7200 = 2 × access token TTL(1h),保证轮换前签发的 access token 在整个有效期内仍可验证。同时决定 JWKS 端点 `Cache-Control: max-age`(取 retention 的一半,工程折中非精确安全界) |

**校验规则(`validate`,fail-closed)**:`0` 拒绝(等价于轮换瞬间退役旧钥,存量 token 验证立即中断)。

**调优**:retention 必须 ≥ access token 有效期(否则旧钥退役早于其签发 token 过期,出现验证失败窗口);放宽验证需求(超长 TTL token)按 `2 × 最大 access TTL` 取值。

### 2.7 密码哈希导入约束(R11)

批量导入 / 凭据写入路径的密码哈希校验门 `validate_imported_hash`(白名单 + 参数上限,越界整体拒绝、错误显性)。防止单次登录 OOM / CPU DoS(对齐 zitadel passwap `ValidateEncodedHash` 防御意图)。

| 约束 | 允许值 | 说明 |
|------|--------|------|
| 格式白名单 | `$argon2id$` / `$2b$` / `$2a$` / `$2y$` 前缀 | 白名单外前缀拒绝(`$argon2i$` 等不再接受导入) |
| `ARGON2_IMPORT_MAX_M_COST` | ≤ 1 GiB(`1_048_576` KiB) | Argon2 内存成本上限 |
| `ARGON2_IMPORT_MAX_T` | ≤ 10 | Argon2 迭代次数上限 |
| `ARGON2_IMPORT_MAX_P` | ≤ 4 | Argon2 并行度上限 |
| bcrypt cost | ≤ 15 | 登录期单次 verify 成本上界 |

**登录期惰性升级**:存量低档位哈希在登录 verify 成功后自动重哈希到当前配置档位(走 Argon2 并发令牌池,失败不阻塞登录)——导入约束只把守入口,存量演进靠惰性升级自然收敛。

### 2.8 弃用配置键(R12)

`src/config/deprecation.rs` 注册表(加载期处置:可映射键自动迁移 + warn;不可映射键 0.x warn 放行、**1.0 起一律报错**):

| 弃用键 | since | 迁移目标 | 处置 |
|--------|-------|---------|------|
| `waf_config` | 0.9.0 | (无——能力移除) | 0.x warn 指引;1.0 起加载报错 |

新弃用键随 Breaking 变更逐键登记(每键一条映射/报错测试);不注册虚构键。

### 2.9 字段静态加密(field-encryption,R17)

启用 `field-encryption` feature 后,选定敏感列(`oauth2:atoken:` / `oauth2:rtoken:` / `oauth2:codeused:` / `totp:seed:`)落库自动加密为 `enc:v1:<key_id>:<base64(nonce|ciphertext)>`(AES-256-GCM,AAD 绑定 `garrison:{tenant}:{table}:{key}`)。密钥复用 config-encryption 既有设施(支持多 key_id);**启用 feature 未配密钥 → 启动 fail-closed Err**。读路径兼容明文遗留行(双读迁移期语义),写路径全加密。密钥轮换用 `change_key` / `check_key` 运维接口(garrison-cli 接线见 R16)。

### 2.10 WebAuthn/Passkey 配置(protocol-webauthn,R07)

`protocol::webauthn::WebauthnConfig`(构造后不可变;经 `WebauthnService::new` 注入)。RP 配置不自立配置项,从 issuer 派生:`rp_id` = issuer URL host、`origins` = [issuer](issuer 变更后 rp_id 跟随)。

| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `issuer` | `String` | 无(必填) | RP 派生源(如 `https://sso.example.com`);非法 URL 显性拒绝 |
| `challenge_ttl_secs` | `u64` | `120` | 仪式 challenge 暂存 TTL(秒);过期后消费显性拒绝(与重放同错误面) |
| `passwordless.enabled` | `bool` | `false` | Passwordless 用途准入;关闭时该用途的注册/认证显性拒绝 |
| `second_factor.enabled` | `bool` | `false` | 2FA 二次认证用途准入(完整 MFA 编排归 R09);2FA 接线点经 `stp::mfa::webauthn_factor::register_webauthn_factor` 注册 |

**Cargo feature**:`protocol-webauthn`(依赖 webauthn-rs 0.5;其 rustc ≥ 1.88 要求已低于本仓 MSRV 1.97.1,工具链口径见 [DEVELOPMENT.md](DEVELOPMENT.md))。

### 2.11 MFA/step-up 编排配置(mfa,R09)

`GarrisonConfig.mfa`(`MfaConfig`)。chain factor 词汇表:`otp` / `webauthn`(`pwd` 为主因子不进 chain);引用未知 factor 启动期 fail-closed 报错。

```toml
[mfa]
global_chain = ["otp"]              # 全局默认链(空 = 不强制 MFA)
recovery_misuse_tolerance = 0       # 恢复码误用豁免额度(默认 0,超限锁定)

[mfa.per_client_chains]
"legacy-client" = []                # 空数组 = 显式禁用(即使全局有默认链)
"admin-console" = ["webauthn"]      # 非空 = 强制该集合
```

| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `mfa.global_chain` | `Vec<String>` | `[]` | 全局默认强制链;空 = 不强制 |
| `mfa.per_client_chains` | `HashMap<String, Vec<String>>` | `{}` | per-client 覆盖(三态语义见上) |
| `mfa.recovery_misuse_tolerance` | `u32` | `0` | 恢复码连续无效 verify 的豁免次数,超过即锁定(fail-closed,正确码也拒绝) |

### 2.12 找回密码配置(account-password-reset,R14)

`account::password_reset` 模块(feature `account-password-reset`,依赖 protocol-jwt + account-credential + account-policy + email-verification)。行为常量与安全不变式:

| 项 | 默认值 | 说明 |
|----|--------|------|
| 防枚举限流窗口 | 3600 秒 | 每标识的请求计数窗口(与 email-verification 小时窗口同口径);未知标识同路径 dummy 签发,响应外形不可区分 |
| ActionToken TTL | 短时效(构造参数) | `purpose=password_reset` 的自包含 JWT;jti 一次性消费(DAO set_if_absent + 原子消费,并发恰一成功) |
| 密码历史比对 | 与 HistoryRule 硬上限对齐(24 条) | 重置成功追加 `app_password_history`;重用历史密码被拒且 token 不消费 |
| restricted 会话 | `pwdreset_restricted` 标记 | 恢复会话仅可达改密端点(其余 403) |

**运维提示**:`app_password_history` 表随 `016_password_history.sql` 迁移创建;注册/常规改密路径的追加由 host 责任接入(保证「上一代密码」在历史中可查)。

### 2.13 JWT 撤销与限流后端配置(0.9.x 新增)

| 字段名 | 类型 | 默认值 | 环境变量 | 说明 |
|--------|------|--------|----------|------|
| `enable_jwt_revocation` | `bool` | `false` | `GARRISON_ENABLE_JWT_REVOCATION` | 启用 JWT 撤销黑名单:`logout` / `kickout` 时将 `jti` 写入 DAO(TTL = 剩余有效期),`check_login_stateless` 验签后前置检查,已撤销返回 `TokenRevoked`;仅 `protocol-jwt` + `token_style="jwt"` 时生效 |
| `allow_stateless_jwt_no_revocation` | `bool` | `false` | `GARRISON_ALLOW_STATELESS_JWT_NO_REVOCATION` | 显式风险接受:允许 `token_style="jwt"` + `JwtMode::Stateless` + 不启用撤销的组合(不可吊销的永久 JWT 凭证;`jwt_mode` 为代码注入的 `JwtMode` 枚举,非配置字段);正常部署应使用 `enable_jwt_revocation=true` 或 `JwtMode::Mixin` |
| `rate_limit_backend` | `String` | `"memory"` | `GARRISON_RATE_LIMIT_BACKEND` | 限流后端选择(`memory` / `redis`)。**生效面**:登录防火墙 hook(`fw:ip:*` / `fw:acct:*` 计数)与 `RateLimitStrategy`(含 `from_garrison_config` / `with_runtime`);`memory` 跟随主 DAO(进程内 oxcache),`redis` 使用独立 Redis 限流运行时(oxcache `RedisBackend` + limiteron `RedisDistributedLimiter`),会话 / token / geo / device 数据仍走主 DAO。`redis` 需 `rate-limit-redis` feature 与 `GARRISON_REDIS_URL`;启动连接失败拒绝启动(fail-closed),运行期错误向上传播。非 TLS `redis://` 受 oxcache 策略约束:生产用 `rediss://`,开发/测试可设 `OXCACHE_ALLOW_INSECURE_REDIS=I_UNDERSTAND_THE_RISKS`。**未覆盖**:`BruteForceStrategy` 封禁账本、`DDoSStrategy`、OAuth2 `/token` 限流、邀请码防爆破、SMS/email 配额、API Key 锁定、账号锁定、auth_server 边缘 `rate_limit_middleware`(进程内令牌桶)仍按各自后端独立运作 |

---

### 2.14 Refresh Token 重用检测与宽限窗口配置(oauth2-server,R06)

驱动 `RefreshTokenRotation`(`TokenHandler::with_refresh_rotation`)的重用检测与并发双刷容忍。重用三级分类:`RecentPrev`(命中存活链头 parent,回溯 1 跳)/ `OrphanedBranch`(回溯 >1 跳)/ `StaleLineage`(无存活血缘,恒按盗用吊销整条 chain,不受本组配置影响)。三项均从 `garrison.toml` 加载。

| 字段名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `recent_reuse_behaviour` | `RecentReuseBehaviour` | `TheftDetected`(toml 值 `theft_detected`) | `RecentPrev` / `OrphanedBranch` 的处置分派:`TheftDetected`(默认,吊销整条 chain + `TokenRevoked`)/ `Unauthorised`(仅拒绝本次请求 401,不吊销 chain);非法值启动期 fail-fast |
| `refresh_grace_period_secs` | `i64` | `0` | 并发双刷宽限窗口秒数(`0` = 关闭)。窗口内已轮换的旧 token 再次呈现时返回轮换签发的既有新 token(不重旋转);兑现凭据进程内暂存不落库,多实例仅签发实例可命中,其余退化为既有重用处置。负值配置校验拒绝 |
| `refresh_grace_max_uses` | `u32` | `1` | 宽限窗口内同一旧 token 的最大兑现次数;预算耗尽后的窗口内重放按 `recent_reuse_behaviour` 处置。仅当 `refresh_grace_period_secs > 0` 时生效;`0` 配置校验拒绝(窗口形同虚设) |

---

## 📝 配置文件示例

### 3.1 `garrison.toml`

在项目根目录创建 `garrison.toml`:

```toml
# Garrison 配置文件
# 详见 docs/CONFIGURATION.md

# 会话策略
timeout = 2592000            # 会话超时 30 天
active_timeout = -1          # -1 表示跟随 timeout
is_share = true              # 同账号多端共享会话
is_concurrent = true         # 允许并发登录

# Token 策略
token_name = "garrison_token"
token_style = "uuid"         # 可选: uuid / random_64 / simple / jwt
is_read_cookie = true
is_read_header = true
is_write_header = true

# 异常行为
throw_on_not_login = true

# Cookie 策略
cookie_secure = true
cookie_same_site = "Lax"

# 0.2.0 扩展(不启用 protocol-* 时可省略)
# jwt_algorithm = "HS256"
# sign_window_seconds = 300
# sso_ticket_ttl_seconds = 60

# 0.6.0 remember-me 扩展会话超时
# remember_me_enabled = false
# remember_me_timeout = 7776000  # 90 天

# 0.5.0 多租户隔离
# [tenant_isolation]
# enabled = false
# resolver = "header"

# 密码哈希参数(默认即 OWASP 建议档,通常无需配置)
# [password_hasher]
# algorithm = "argon2id"       # 可选: argon2id / bcrypt
# argon2_m_cost = 19456        # KiB,下限 19456(低于需 allow_weak_argon2_params = true)
# argon2_t_cost = 2
# argon2_p_cost = 1
# argon2_pool_size = 1         # 并发令牌池,区间 [1, 256];内存上界 ≈ pool_size × m_cost
# bcrypt_cost = 12             # 仅 algorithm = "bcrypt" 时生效,区间 [10, 15]
```

### 3.2 环境变量完整列表

通过 `.env` 或容器环境注入(生产环境建议使用容器/编排平台的环境注入):

```env
# 会话策略
GARRISON_TIMEOUT=2592000
GARRISON_ACTIVE_TIMEOUT=-1
GARRISON_IS_SHARE=true
GARRISON_IS_CONCURRENT=true

# Token 策略
GARRISON_TOKEN_NAME=garrison_token
GARRISON_TOKEN_STYLE=uuid
GARRISON_IS_READ_COOKIE=true
GARRISON_IS_READ_HEADER=true
GARRISON_IS_WRITE_HEADER=true
GARRISON_IS_READ_BODY=false
GARRISON_IS_WRITE_COOKIE=false
GARRISON_THROW_ON_NOT_LOGIN=true

# 前后端分离
GARRISON_FRONTEND_SEPARATION=false

# Cookie 策略
GARRISON_COOKIE_SECURE=true
GARRISON_COOKIE_SAME_SITE=Lax

# 0.2.0 扩展
GARRISON_JWT_SECRET=change-me-in-production
GARRISON_JWT_ALGORITHM=HS256
GARRISON_SIGN_WINDOW_SECONDS=300
GARRISON_SSO_TICKET_TTL_SECONDS=60

# 0.6.0 remember-me
GARRISON_REMEMBER_ME_ENABLED=false
GARRISON_REMEMBER_ME_TIMEOUT=7776000

# 0.9.x JWT 撤销与限流后端
GARRISON_ENABLE_JWT_REVOCATION=false
GARRISON_ALLOW_STATELESS_JWT_NO_REVOCATION=false
GARRISON_RATE_LIMIT_BACKEND=memory

# 会话管理
GARRISON_SESSION_HOVER_TIMEOUT=-1
GARRISON_AUTO_RENEWAL_THRESHOLD=-1
GARRISON_TOKEN_MAP_CLEANUP_INTERVAL_SECS=300
GARRISON_MAX_LOGIN_COUNT=0
GARRISON_DEVICE_BINDING_MODE=disabled

# 多租户隔离
GARRISON_TENANT_ISOLATION__ENABLED=false
GARRISON_TENANT_ISOLATION__RESOLVER=header

# 密码哈希(可选)
GARRISON_PASSWORD_HASHER__ARGON2_POOL_SIZE=1

# 数据库与缓存
# 注意:数据库 URL 不走环境变量——框架不读取 GARRISON_DB_URL,须由宿主编程式传入
# garrison::dao::init_dbnexus(&db_url)(CLI 对应 --db-url 参数)。
GARRISON_REDIS_URL=redis://127.0.0.1:6379/0

# 日志
RUST_LOG=garrison=info
```

> 加载顺序提示:`.env` 文件由应用自行选择 `dotenvy` 之类的 crate 加载,Garrison 只读取进程环境变量;`garrison.toml` 与环境变量同时存在时,环境变量优先。

---

## 🔄 热更新机制

Garrison 通过 `tokio::sync::watch` 通道广播配置变更,订阅方收到通知后响应:

### 4.1 工作流程

```mermaid
graph LR
    A[ConfigLoader::load] --> B[GarrisonConfig 实例]
    B --> C[with_watcher 创建 watch channel]
    C --> D[watch::Sender]
    D --> E[watch::Receiver]
    E --> F[GarrisonManager 订阅]
    F --> G[清空权限缓存 / 重建策略]
```

### 4.2 使用示例

```rust
use garrison::config::GarrisonConfig;

// 创建带 watcher 的配置实例
let config = GarrisonConfig::default_config();

// 订阅配置变更
let mut rx = config.watch().expect("default_config 应有 watcher");

// 闭包式修改配置并广播(自动校验)
config.update(|c| {
    c.timeout = 3600;
}).unwrap();

// 订阅方接收新配置
let new_config = rx.borrow_and_update();
assert_eq!(new_config.timeout, 3600);
```

### 4.3 热更新语义

| 行为 | 是否影响已存在会话 |
|------|---------------------|
| 修改 `timeout` / `active_timeout` | 否,仅影响后续创建的会话 |
| 修改 `token_style` | 否,已签发 token 不受影响 |
| 修改 `is_share` / `is_concurrent` | 否,仅影响后续登录 |
| 修改 `jwt_algorithm` | 否,已签发 JWT 验签按旧密钥失效后才切换 |

> `update()` 闭包修改后的配置会自动通过 `validate()` 校验,非法值将被拒绝且不广播(no-op)。

---

## ✅ 配置校验规则

`GarrisonConfig::validate()` 会执行字段校验,非法值抛出 `GarrisonError::Config`:

| 字段 | 校验规则 | 错误 i18n key(`GarrisonError::Config`) |
|------|----------|--------------|
| `timeout` | 必须 > 0 | `config-timeout-must-positive::` |
| `token_style` | 必须在 `["uuid", "random_64", "simple", "jwt"]` 内 | `config-unknown-token-style::{值}` |
| `token_style=jwt` | `jwt_secret` 不能为空 | `config-jwt-secret-empty::` |
| `token_style=simple` | `jwt_secret` 长度必须 ≥ 32 字节(simple 风格密钥即 HMAC-SHA256 签名密钥,可离线爆破;原 warn 已升级为启动错误) | `config-jwt-secret-too-short::simple (min 32 bytes)::{长度}` |
| `token_style=jwt`(HS 系)/ `simple` | `jwt_secret` 不得命中弱密钥黑名单(16 条常见弱密钥;剥除首尾填充字符后整串比对、忽略大小写,不做子串匹配,不误伤高熵密钥) | `config-jwt-secret-weak::blacklist hit` |
| `GARRISON_CSRF_ENABLED`(环境变量,`web-csrf`) | 仅接受 `true` / `false`(大小写不敏感),其他取值在配置加载(环境变量覆盖阶段)即失败——原 `"1"`/`"yes"` 等 truthy 习惯值会静默禁用 CSRF 防护 | `config-csrf-enabled-unsupported::{值}` |
| `cookie_same_site` | 必须在 `["Lax", "Strict", "None"]` 内 | `config-unknown-cookie-same-site::{值}` |
| `is_share=true` | 要求 `is_concurrent=true` | `config-is-share-requires-concurrent::` |
| `remember_me_timeout` | `remember_me_enabled=true` 时必须 > `timeout`;`remember_me_enabled=false` 时必须 > 0 | `config-remember-me-timeout-mismatch::{值}::{timeout}` / `config-remember-me-timeout-positive::{值}` |
| `auto_renewal_threshold` | 必须为 `-1` 或 `0..=100` | `config-auto-renewal-threshold-invalid::{值}` |
| `device_binding_mode` | 必须在 `["strict", "loose", "disabled"]` 内 | `config-unknown-device-binding-mode::{值}` |

> 环境变量覆盖后也会触发 `validate()`,非法值(如 `GARRISON_TIMEOUT=not-a-number`)会被拒绝并返回 `GarrisonError::Config`。

### Cookie 写入语义(Set-Cookie 单一构建点)

所有 Set-Cookie 写路径(三框架适配器、续签中间件、CSRF 中间件)统一经 `context::cookie` 构建点产出,属性顺序统一为 `name=value; HttpOnly; [Secure; ]SameSite=<ss>; Path=<p>[; Domain=<d>][; Max-Age=<n>]`:

- **白名单 fail-fast**:`cookie_same_site` 非法值在构建点同样被拒绝(合法值与启动期校验白名单 `COOKIE_SAME_SITE_VALUES` 一一对应,由跨引用测试锁定),拒绝后不产出 Set-Cookie。
- **None→Lax 降级**:`cookie_same_site = "None"` 仅在 `cookie_secure = true` 时生效;`cookie_secure = false`(HTTP 调试)时自动降级为 `Lax` 并输出一次 warn——浏览器拒收不带 Secure 的 `SameSite=None`。
- **production 前缀**:启用 `production` feature 且 `cookie_secure = true` 时 cookie 名强制加前缀——`Path=/` 且无 Domain 的 cookie(会话 token、CSRF cookie)为 `__Host-<name>`,限定路径或带 Domain 的为 `__Secure-<name>`;`cookie_secure = false`(http 降级)不加前缀。框架读写两侧同步解析(读侧统一入口 `token_cookie_name`)。**注意**:升级到带此前缀的版本后,在线用户旧 cookie 失效,需重新登录一次;业务侧自行读取 cookie 的代码需改用同名解析。

### 5.1 Redis 部署模式配置(0.6.0 新增)

`RedisDeploymentMode` 枚举覆盖生产环境常见 Redis 拓扑,通过 `RedisConfig` 聚合结构配置(注意:`RedisConfig` 并非 `GarrisonConfig` 的字段,只能编程式传给缓存构建器 `with_redis_config`;环境变量 `GARRISON_REDIS_URL` 仅作用于限流后端 `rate-limit-redis`,不注入缓存侧 `RedisConfig`):

| 模式 | 字段 | 说明 |
|------|------|------|
| `Single` | `url: String` | 单节点模式(默认 `redis://127.0.0.1:6379`) |
| `Sentinel` | `primary_name: String`, `urls: Vec<String>` | 哨兵模式:通过 Sentinel 集群自动故障转移(配置值仍可用旧键 `master_name`,`#[serde(alias)]` 兼容) |
| `Cluster` | `urls: Vec<String>` | 集群模式:Redis Cluster 分片存储(至少 3 个 primary 节点) |
| `PrimaryReplica` | `primary_url: String`, `replica_urls: Vec<String>` | 主从模式:1 primary + N replica,读分离需客户端支持(配置值仍可用旧变体名 `MasterSlave`,`#[serde(alias)]` 兼容) |

`RedisConfig` 完整字段:`mode`(部署模式)/ `password`(认证密码)/ `db`(数据库编号 0-15)/ `connection_timeout_secs`(默认 5)/ `pool_size`(默认 10)。

> ⚠️ **接线状态如实说明**:当前版本缓存侧 Redis L2 尚未实际接线——`with_redis_config` 仅存储配置并输出一次 warn(`src/dao/oxcache_impl.rs` 的 M4 注记),缓存仍走进程内内存;多实例会话共享当前不可用。上述拓扑结构为接口预留,实际生效待后续版本;当前真实消费 Redis 的是限流后端(`rate-limit-redis`)。

---

## 六、各 Feature 的配置说明

Garrison 通过 feature flag 在编译期裁剪,不同 feature 下需要的配置项不同:

| Feature | 默认 | 关联配置项 |
|---------|------|------------|
| `cache-memory` | 关 | 无(使用 oxcache 内存缓存) |
| `cache-redis` | 关 | 缓存侧 Redis 拓扑编程式经 `RedisConfig` + `with_redis_config` 传入(L2 当前仅存储配置未接线,见 §5.1 注);`GARRISON_REDIS_URL` 属限流后端(`rate-limit-redis`) |
| `db-sqlite` | 关 | SQLite 路径由宿主编程式传给 `garrison::dao::init_dbnexus(&db_url)`(无 `GARRISON_DB_URL` 环境变量) |
| `web-axum` | 关 | 启用 axum extractor / router |
| `protocol-jwt` | 关 | `jwt_algorithm`(`GARRISON_JWT_SECRET` 必填) |
| `protocol-oauth2` | 关 | 需配套 oauth2 client 配置 |
| `protocol-sso` | 关 | `sso_ticket_ttl_seconds` |
| `protocol-sign` | 关 | `sign_window_seconds` |
| `protocol-apikey` | 关 | 由 ApiKey dao 管理;自动启用 `dao-key-index`(使 `list_by_namespace` 生产可用);secret 以 sha256 哈希存储;生产建议配 `cache-redis`(AOF),可选 `firewall-bruteforce` 启用 IP 级失败限速 |
| `protocol-temp` | 关 | 临时 token TTL 由调用方指定 |
| `secure-totp` | 关 | TOTP secret 由用户绑定关系存储 |
| `secure-sign` | 关 | 复用 `sign_window_seconds` |
| `protocol-httpbasic` | 关 | 凭据由调用方提供 |
| `protocol-httpdigest` | 关 | nonce / opaque 由内部生成 |

> **⚠️ Refresh Token 轮换退化行为(`db-sqlite` + `oauth2-server` 部署必读)**
>
> `/oauth2/token` 的 refresh grant 始终可用,但其安全强度取决于是否注入
> `RefreshTokenRotation`(`TokenHandler::with_refresh_rotation`):
>
> - **已注入(推荐)**:hash chain 轮换 + reuse detection——盗用的旧 refresh_token
>   被重放时触发整链撤销,攻击者会话即刻失效。
> - **未注入(退化)**:DAO 键值存储(`oauth2:rtoken:` 前缀),无 reuse detection、
>   无链式撤销——旧 token 重放仅因单次消费失败被拒,**不会触发链式撤销**,同链
>   其他 token 不受影响。
>
> 退化形态在两处显性告警(非静默):`OAuth2State::new` 构造完成时输出一次结构性
> warn;每次退化路径刷新输出请求级 warn(`refresh_token rotation not configured`)。
> 生产部署请注入 rotation 消除告警。未启用 `db-sqlite` 的构建不支持轮换注入,
> refresh grant 恒为退化路径(如无 refresh 需求可忽略)。

### 6.0.1 X-Request-ID 请求标识中间件(R04)

> **头名固定非配置**:`X-Request-ID` / `Retry-After` 为编译期常量
> (`context::request_id::REQUEST_ID_HEADER` / `RETRY_AFTER_HEADER`),
> **不提供配置项**——中间件行为一致性与安全校验规则(长度 ≤128 + 可见 ASCII)
> 不应随部署漂移(见 ADR-0004)。

三框架挂载示例:

```toml
# Cargo.toml
[dependencies]
garrison = { version = "0.9.0-rc.4", features = ["web-axum"] } # 或 web-actix / web-warp
```

```rust,ignore
// axum:middleware::from_fn,建议挂最外层(错误体 request_id 覆盖全部下游错误)
use axum::{routing::get, Router};

let app = Router::new()
    .route("/api", get(handler))
    .layer(axum::middleware::from_fn(garrison::web::request_id::request_id_middleware));

// actix-web:Transform wrap
use actix_web::App;

let app = App::new().wrap(garrison::web_actix::RequestIdMiddleware);

// warp:wrap_fn 包装(错误体 request_id 走后置回填,见 ADR-0004)
let routes = routes.with(warp::wrap_fn(garrison::web_warp::with_request_id));
```

行为:入站 `X-Request-ID` 合法(非空、≤128 字节、可见 ASCII)则原样回传,
否则丢弃重新生成 UUID v4;所有响应回传 `X-Request-ID` 头,统一错误体携带
`request_id` 字段;handler 经 `Extension<RequestId>`(axum)或 request
extensions(actix)读取;中间件输出结构化日志(span + 事件均含 `request_id`
字段)。错误响应附带 `Retry-After` 头(仅 `GarrisonError::RateLimited`,
delta-seconds 整数秒,下限 1)。

### 6.1 启用 JWT + Redis 的组合示例

```toml
[dependencies]
garrison = {
    version = "0.9.0-rc.4",
    features = [
        "cache-memory",
        "cache-redis",
        "db-sqlite",
        "web-axum",
        "protocol-jwt",
    ],
}
```

并配套 `garrison.toml`:

```toml
jwt_algorithm = "HS256"
```

与 `.env`:

```env
GARRISON_JWT_SECRET=your-256-bit-secret
GARRISON_REDIS_URL=redis://127.0.0.1:6379/0
```

---

## 六点五、serve 子命令环境变量(src/cli/serve.rs,原 auth_server bin)

经 confers 派生宏从 `GARRISON_*` 读取(`#[config(env_prefix = "GARRISON_")]`,字段名大写映射)。容器部署的逐项注意见 [🚀 部署指南 · 运行环境变量(容器)](./DEPLOYMENT.md#运行环境变量容器)。

| 环境变量 | 默认值 | 说明 |
|---|---|---|
| `GARRISON_EXTERNAL_PORT` / `GARRISON_INTERNAL_PORT` | 8080 / 8081 | 外网 / 内网监听端口 |
| `GARRISON_EXTERNAL_BIND` / `GARRISON_INTERNAL_BIND` | **127.0.0.1** | 外网 / 内网绑定地址(secure-by-default,仅本机可达;容器内须设 `0.0.0.0` 才能被端口映射,镜像已内置该 ENV)。仅接受 IPv4/IPv6 字面量,非法值拒绝启动(fail-closed)。缺省回环由 bin 提供——库层 `AuthServerConfig::default()` 仍为 `0.0.0.0` |
| `GARRISON_TRUSTED_PROXIES` | 空(不信任任何 XFF) | 可信代理 IP 列表(逗号分隔)。仅部署在可信反代之后才配置;配置后 XFF 解析(限速键 / 客户端 IP)才启用。仅接受回环 / RFC 1918 / link-local / IPv6 ULA,非法或公网值拒绝启动 |
| `GARRISON_RATE_LIMIT` | 100 | 外网每 IP 限速(必须 > 0,0 拒绝启动) |
| `GARRISON_INTERNAL_API_KEY` | 无(必填) | 内网 API Key,缺失或为空时 fail-closed 拒绝启动;长度下限由库层 `MIN_INTERNAL_API_KEY_LEN`(32 字节)统一强制 |
| `GARRISON_MAX_LOGIN_COUNT` | **10** | 同账号最大并发会话数(超出踢出最早登录的会话);显式传 `0` = 不限制(覆盖框架 `default_config()` 的 `0`) |
| `GARRISON_SEED_PRIMARY_AMR` | **true** | 登录是否向会话播种主认证因子(`amr=["pwd"]` / AAL 1 / `auth_time`)。安全敏感部署建议显式 `false`——参考部署 login 不校验凭证,默认播种会断言一次从未发生的密码认证,误导下游 step-up 判定 |
| `GARRISON_EXTERNAL_LOGIN_ENABLED` | **false** | **是否启用外网登录端点**。框架 login 不校验凭证(职责边界:凭证校验属业务层,框架只签发会话),默认对 `POST /api/v1/auth/login` 返回 404(secure-by-default)。业务方注入凭证校验后才设为 `true`;仅接受 `true`/`false`(大小写不敏感),非法值拒绝启动 |
| `GARRISON_EXTERNAL_LOGIN_ACK` | 无(条件必填) | 开启外网登录且外网绑定为非回环地址时的显式风险确认:取值必须精确为 `i-understand-no-credential-check`,缺失或不匹配拒绝启动(fail-closed) |
| `GARRISON_STRICT_SECURITY` | **true** | 严格安全档:内网 API Key 长度下限(库层 `MIN_INTERNAL_API_KEY_LEN` = 32 字节)与外网登录暴露未 ACK 均在启动期由库层 `AuthServerConfig::validate()` 拒绝(早于建库与迁移)。`false` 仅作为密钥尚未轮换时的一次性逃生阀,同条件降级为库层告警。本路径经 confers 只接受 `true`/`false`(大小写不敏感),非法值拒绝启动(库层 `AuthServerConfig::default()` 读同名变量时语义不同:非法值告警后回退缺省 `false`) |
| `GARRISON_FIELD_ENCRYPTION_KEYS` | 无(`field-encryption` feature 启用时必填) | 落库敏感字段静态加密密钥表(逗号分隔 `key_id:hex64`,hex64 = 32 字节 AES-256 钥材,首项为主钥);feature 启用但未配置即拒绝启动(fail-closed)。garrison-cli 的同名变量用作 `change-key` / `check-key` 的密钥来源 |
| `GARRISON_FIELD_ENCRYPTION_TENANT` | `default` | 字段加密 AAD 租户段 |
| `GARRISON_WORKER_THREADS` | CPU 核数 | Tokio worker 线程数 |
| `GARRISON_MAX_BLOCKING_THREADS` | 512 | Tokio blocking 线程上限 |

对应库级配置:`AuthServerConfig::external_login_enabled`(`with_external_login_enabled(bool)`)。另有库层(`AuthServerConfig` / `GarrisonAuthServer`)读取的 `GARRISON_HEALTH_DETAILS`、`GARRISON_API_KEY_LOCKOUT_THRESHOLD` / `GARRISON_API_KEY_LOCKOUT_WINDOW_SECS`、`GARRISON_RATE_LIMIT_BACKEND`,同样列入上述部署指南表格。

---

## 📚 相关文档

| 文档 | 说明 |
|------|------|
| [🏗️ 架构文档](./ARCHITECTURE.md) | 设计原则与模块划分 |
| [🚀 部署指南](./DEPLOYMENT.md) | 生产部署注意事项 |
| [🛠️ 开发规范](./DEVELOPMENT.md) | TDD 工作流与代码规范 |