garrison 0.9.0

Garrison - 面向 Rust 生态的一站式身份认证鉴权框架
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
// Copyright (c) 2026 Kirky.X🌠
// SPDX-License-Identifier: Apache-2.0

//! JwtHandler 实现:JWT 签发、校验、刷新。
//!
//! 类型定义见 [`JwtHandler`](crate::protocol::jwt::JwtHandler)。

use crate::error::{GarrisonError, GarrisonResult};
use jsonwebtoken::{decode, encode, Algorithm, DecodingKey, EncodingKey, Header, Validation};
use serde::de::DeserializeOwned;
use serde::Serialize;
use std::time::{SystemTime, UNIX_EPOCH};

use super::{GarrisonJwtClaims, JwtHandler};

/// JWT 签名密钥最小长度(字节,256 位匹配 HS256 强度,OWASP / NIST SP 800-117):
/// 短于此阈值可被暴力破解,导致 JWT 伪造。
const MIN_SECRET_BYTES: usize = 32;

/// JWT 密钥材料(crate 内私有):决定 sign/verify 的密钥来源与算法白名单。
///
/// 算法必须与密钥类型一致(如 RSA 密钥只能配 RS 系算法),防止
/// alg confusion / 算法替换攻击;匹配约束由 [`validate_algorithm_match`] 强制。
/// PEM 内容在 Debug 输出中脱敏(防私钥泄漏到日志)。
pub(crate) enum KeyMaterial {
    /// 对称 HMAC:`secret` 字段即密钥(HS256/HS384/HS512)。
    Hs,
    /// RSA PKCS#1 私钥 PEM(RS256/RS384/RS512)。
    RsaPkcs1Pem(String),
    /// EC 私钥 PEM(ES256/ES384)。
    EcPem(String),
    /// Ed25519 私钥 PEM(EdDSA)。
    EdPem(String),
}

impl KeyMaterial {
    /// 该密钥类型允许的算法白名单(fail-closed 语义:不在白名单即拒绝)。
    pub(crate) fn allowed_algorithms(&self) -> &'static [Algorithm] {
        match self {
            KeyMaterial::Hs => &[Algorithm::HS256, Algorithm::HS384, Algorithm::HS512],
            KeyMaterial::RsaPkcs1Pem(_) => &[Algorithm::RS256, Algorithm::RS384, Algorithm::RS512],
            KeyMaterial::EcPem(_) => &[Algorithm::ES256, Algorithm::ES384],
            KeyMaterial::EdPem(_) => &[Algorithm::EdDSA],
        }
    }
}

impl std::fmt::Debug for KeyMaterial {
    /// PEM 内容脱敏:错误消息 / 日志中不得出现私钥原文。
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            KeyMaterial::Hs => write!(f, "KeyMaterial::Hs"),
            KeyMaterial::RsaPkcs1Pem(_) => write!(f, "KeyMaterial::RsaPkcs1Pem(<redacted>"),
            KeyMaterial::EcPem(_) => write!(f, "KeyMaterial::EcPem(<redacted>"),
            KeyMaterial::EdPem(_) => write!(f, "KeyMaterial::EdPem(<redacted>"),
        }
    }
}

/// JWT 公钥参数(JWKS 导出用,无私钥成分)。
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum JwkPublicKey {
    /// RSA:模数 n 与指数 e(base64url,JWK 口径)。
    Rsa {
        /// RSA 模数 n(base64url,RFC 7518 §6.3.1)。
        n: String,
        /// RSA 公钥指数 e(base64url,RFC 7518 §6.3.1)。
        e: String,
    },
    /// EC:曲线名、坐标 x/y(base64url,JWK 口径)。
    Ec {
        /// 曲线标识(P-256 / P-384,RFC 7518 §6.2.1.1)。
        crv: &'static str,
        /// 公钥 x 坐标(base64url,RFC 7518 §6.2.1.2)。
        x: String,
        /// 公钥 y 坐标(base64url,RFC 7518 §6.2.1.3)。
        y: String,
    },
    /// OKP(Ed25519):公钥 x(base64url,JWK 口径)。
    Okp {
        /// Ed25519 公钥(base64url,RFC 8037 §2)。
        x: String,
    },
}

/// 校验签名算法与密钥类型匹配(fail-closed,白名单见
/// [`KeyMaterial::allowed_algorithms`])。
pub(crate) fn validate_algorithm_match(
    key_material: &KeyMaterial,
    algorithm: Algorithm,
) -> GarrisonResult<()> {
    if key_material.allowed_algorithms().contains(&algorithm) {
        Ok(())
    } else {
        Err(GarrisonError::Config(format!(
            "jwt-key-algorithm-mismatch::key={:?}::alg={:?}",
            key_material, algorithm
        )))
    }
}

/// 从 RSA 私钥 PEM(PKCS#8 `BEGIN PRIVATE KEY` 或 PKCS#1 `BEGIN RSA PRIVATE KEY`)
/// 提取公钥组件 `(n, e)` 的 base64url 编码(JWK 口径,jsonwebtoken
/// `DecodingKey::from_rsa_components` 期望该格式)。
///
/// 仅做 DER 结构解析(无 RSA 运算):剥去 BEGIN/END 头尾行与空白,按 RFC 7468
/// 标准 Base64(非 URL-safe)解码得 DER 字节。
fn pem_to_der(pem: &str) -> GarrisonResult<Vec<u8>> {
    use base64::Engine;

    let body: String = pem
        .lines()
        .filter(|line| !line.starts_with("-----"))
        .collect::<Vec<_>>()
        .join("");
    base64::engine::general_purpose::STANDARD
        .decode(body.trim())
        .map_err(|e| GarrisonError::Internal(format!("jwt-rsa-pem-invalid::{}", e)))
}

fn extract_rsa_public_components(pem: &str) -> GarrisonResult<(String, String)> {
    use base64::Engine;
    use pkcs8::der::Decode;

    let der = pem_to_der(pem)?;
    // PKCS#8("BEGIN PRIVATE KEY"):PrivateKeyInfo.private_key(OCTET STRING)
    // 内嵌 PKCS#1 RSAPrivateKey DER;PKCS#1("BEGIN RSA PRIVATE KEY"):整段即
    // RsaPrivateKey DER。按 PEM label 区分。
    let key = if pem.contains("BEGIN RSA PRIVATE KEY") {
        pkcs1::RsaPrivateKey::from_der(&der)
    } else {
        let pki = pkcs8::PrivateKeyInfo::from_der(&der)
            .map_err(|e| GarrisonError::Internal(format!("jwt-rsa-pem-invalid::{}", e)))?;
        pkcs1::RsaPrivateKey::from_der(pki.private_key)
    }
    .map_err(|e| GarrisonError::Internal(format!("jwt-rsa-pem-invalid::{}", e)))?;

    let b64 = |data: &[u8]| base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(data);
    Ok((
        b64(key.modulus.as_bytes()),
        b64(key.public_exponent.as_bytes()),
    ))
}

/// 从 EC 私钥 PEM(PKCS#8)提取 SEC1 未压缩公钥字节(`0x04 ‖ X ‖ Y`)。
///
/// PKCS#8 EC 的 private_key 为 RFC 5915 `ECPrivateKey` DER;若其中内嵌公钥
/// (`publicKey` 位串,V2 可选)则直接取用,否则按曲线 OID 分派做标量乘法计算。
/// 仅支持 P-256 / P-384(对应 ES256 / ES384)。
fn extract_ec_public_sec1(pem: &str) -> GarrisonResult<Vec<u8>> {
    use pkcs8::der::asn1::ObjectIdentifier;
    use pkcs8::der::Decode;

    const OID_P256: ObjectIdentifier = ObjectIdentifier::new_unwrap("1.2.840.10045.3.1.7");
    const OID_P384: ObjectIdentifier = ObjectIdentifier::new_unwrap("1.3.132.0.34");

    let der = pem_to_der(pem)?;
    let pki = pkcs8::PrivateKeyInfo::from_der(&der)
        .map_err(|e| GarrisonError::Internal(format!("jwt-ec-pem-invalid::{}", e)))?;
    let ec = sec1::EcPrivateKey::from_der(pki.private_key)
        .map_err(|e| GarrisonError::Internal(format!("jwt-ec-pem-invalid::{}", e)))?;

    // RFC 5915 V2 密钥内嵌公钥位串时直接取用(无运算)
    if let Some(pub_bytes) = ec.public_key {
        return Ok(pub_bytes.to_vec());
    }

    // 曲线 OID 判定后做标量乘法计算公钥点
    let oid = pki
        .algorithm
        .parameters
        .and_then(|any| any.decode_as::<ObjectIdentifier>().ok())
        .ok_or_else(|| GarrisonError::Internal("jwt-ec-curve-missing::".to_string()))?;
    if oid == OID_P256 {
        let secret = p256::SecretKey::from_slice(ec.private_key)
            .map_err(|e| GarrisonError::Internal(format!("jwt-ec-pem-invalid::{}", e)))?;
        Ok(secret.public_key().to_sec1_bytes().to_vec())
    } else if oid == OID_P384 {
        let secret = p384::SecretKey::from_slice(ec.private_key)
            .map_err(|e| GarrisonError::Internal(format!("jwt-ec-pem-invalid::{}", e)))?;
        Ok(secret.public_key().to_sec1_bytes().to_vec())
    } else {
        Err(GarrisonError::Internal(format!(
            "jwt-ec-curve-unsupported::{oid}"
        )))
    }
}

/// 从 Ed25519 私钥 PEM(PKCS#8,RFC 8410)提取 32 字节种子。
///
/// RFC 8410 §7:Ed25519 的 PrivateKeyInfo.private_key OCTET STRING 内容直接是
/// 种子字节(无嵌套 DER 结构),纯字节拷贝即可。
fn extract_ed25519_seed(pem: &str) -> GarrisonResult<[u8; 32]> {
    use pkcs8::der::Decode;

    let der = pem_to_der(pem)?;
    let pki = pkcs8::PrivateKeyInfo::from_der(&der)
        .map_err(|e| GarrisonError::Internal(format!("jwt-ed-pem-invalid::{}", e)))?;
    // RFC 8410:private_key OCTET STRING 的内容是 CurvePrivateKey 的 DER 编码
    // (即又一具 OCTET STRING:0x04 0x20 + 32 字节种子),需再剥一层
    let inner = pkcs8::der::asn1::OctetStringRef::from_der(pki.private_key)
        .map_err(|e| GarrisonError::Internal(format!("jwt-ed-pem-invalid::{}", e)))?;
    inner
        .as_bytes()
        .try_into()
        .map_err(|_| GarrisonError::Internal("jwt-ed-seed-len::".to_string()))
}

/// 从 RSA 私钥 PEM 构造验签密钥(提取公钥组件,无私钥运算)。
fn rsa_decoding_key(pem: &str) -> GarrisonResult<DecodingKey> {
    let (n, e) = extract_rsa_public_components(pem)?;
    DecodingKey::from_rsa_components(&n, &e)
        .map_err(|e| GarrisonError::Internal(format!("jwt-rsa-key::{}", e)))
}

/// 从 EC 私钥 PEM 构造验签密钥(标量乘法计算 SEC1 公钥点)。
fn ec_decoding_key(pem: &str) -> GarrisonResult<DecodingKey> {
    let sec1 = extract_ec_public_sec1(pem)?;
    // from_ec_der 为原样字节入口,验证端内部用 VerifyingKey::from_sec1_bytes 消费
    Ok(DecodingKey::from_ec_der(&sec1))
}

/// 从 Ed25519 私钥 PEM 构造验签密钥(种子推导公钥,base64url)。
fn ed_decoding_key(pem: &str) -> GarrisonResult<DecodingKey> {
    use base64::Engine;

    let seed = extract_ed25519_seed(pem)?;
    let signing = ed25519_dalek::SigningKey::from_bytes(&seed);
    let b64 = |data: &[u8]| base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(data);
    DecodingKey::from_ed_components(&b64(signing.verifying_key().as_bytes()))
        .map_err(|e| GarrisonError::Internal(format!("jwt-ed-key::{}", e)))
}

/// 将 jsonwebtoken 验证错误映射为框架错误(错误消息只含错误类别,不含
/// token 内容/密钥,防泄漏)。
fn map_verify_error(e: jsonwebtoken::errors::Error) -> GarrisonError {
    let msg = e.to_string();
    if msg.contains("ExpiredSignature") {
        GarrisonError::ExpiredToken(format!("jwt-expired::{}", e))
    } else if msg.contains("ImmatureSignature") || msg.contains("nbf") {
        // nbf 为未来时间 → ImmatureSignature
        GarrisonError::InvalidToken(format!("jwt-not-yet-valid::{}", e))
    } else {
        GarrisonError::InvalidToken(format!("jwt-invalid::{}", e))
    }
}

/// 由 Ed25519 种子推导公钥并编码为 JWK 口径 OKP 参数(base64url)。
fn ed_jwk_from_seed(seed: &[u8; 32]) -> JwkPublicKey {
    use base64::Engine;

    let signing = ed25519_dalek::SigningKey::from_bytes(seed);
    JwkPublicKey::Okp {
        x: base64::engine::general_purpose::URL_SAFE_NO_PAD
            .encode(signing.verifying_key().as_bytes()),
    }
}

/// 将 SEC1 未压缩公钥字节(`0x04 ‖ X ‖ Y`)拆分为 JWK 口径的 EC 公钥参数。
fn ec_jwk_from_sec1(sec1: &[u8]) -> GarrisonResult<JwkPublicKey> {
    use base64::Engine;

    // SEC1 未压缩点:0x04 ‖ X ‖ Y(X/Y 等长,故总长必为奇数)
    if sec1.first() != Some(&0x04) || sec1.len() < 3 || sec1.len().is_multiple_of(2) {
        return Err(GarrisonError::Internal("jwt-ec-sec1-format::".to_string()));
    }
    let coord = (sec1.len() - 1) / 2;
    let b64 = |data: &[u8]| base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(data);
    let crv = match coord {
        32 => "P-256",
        48 => "P-384",
        _ => {
            return Err(GarrisonError::Internal(
                "jwt-ec-curve-unsupported::".to_string(),
            ))
        },
    };
    Ok(JwkPublicKey::Ec {
        crv,
        x: b64(&sec1[1..1 + coord]),
        y: b64(&sec1[1 + coord..]),
    })
}

impl JwtHandler {
    /// 创建新的 JWT 处理器,默认采用 HS256 算法(空密钥在 `sign` 时拒绝)。
    pub fn new(secret: impl Into<String>) -> Self {
        Self {
            secret: secret.into(),
            algorithm: Algorithm::HS256,
            device: None,
            key_material: KeyMaterial::Hs,
            amr: None,
            auth_time: None,
            tid: None,
        }
    }

    /// 设置签发租户绑定(签发时写入 claims 的 `tid` claim)。
    ///
    /// crate 内租户上下文签发路径专用(`GarrisonLogicDefault::generate_token`):
    /// `check_login_stateless` 从验签 claims 直接读取校验(无需二次验签探测)。
    /// 未调用时签发格式与既有 token 逐字节一致(不带 `tid`)。
    #[must_use]
    pub(crate) fn with_tid(mut self, tid: i64) -> Self {
        self.tid = Some(tid);
        self
    }

    /// 导出公钥参数(JWKS 端点用;无私钥成分)。
    ///
    /// 对称密钥(Hs)无可公开成分,返回 `Ok(None)`;非对称密钥返回
    /// [`JwkPublicKey`]。kid 由调用方按 RFC 7638 thumbprint 计算。
    pub fn export_public_jwk_parts(&self) -> GarrisonResult<Option<JwkPublicKey>> {
        match &self.key_material {
            KeyMaterial::Hs => Ok(None),
            KeyMaterial::RsaPkcs1Pem(pem) => {
                let (n, e) = extract_rsa_public_components(pem)?;
                Ok(Some(JwkPublicKey::Rsa { n, e }))
            },
            KeyMaterial::EcPem(pem) => {
                let sec1 = extract_ec_public_sec1(pem)?;
                ec_jwk_from_sec1(&sec1).map(Some)
            },
            KeyMaterial::EdPem(pem) => {
                let seed = extract_ed25519_seed(pem)?;
                Ok(Some(ed_jwk_from_seed(&seed)))
            },
        }
    }

    /// 按算法名与私钥 PEM 构建 handler(config 透传共用入口)。
    ///
    /// `stp/token` 与 `core/token::TokenStyleFactory` 共用本分派逻辑,消除
    /// 构造分派重复;算法名非法或算法与密钥材料不匹配时 fail-fast。
    pub(crate) fn from_algorithm_parts(
        algorithm: &str,
        jwt_secret: &str,
        rsa_pem: Option<&str>,
        ec_pem: Option<&str>,
        ed_pem: Option<&str>,
    ) -> GarrisonResult<Self> {
        let base = JwtHandler::new(jwt_secret);
        match algorithm {
            "HS256" => base.try_with_algorithm(Algorithm::HS256),
            "HS384" => base.try_with_algorithm(Algorithm::HS384),
            "HS512" => base.try_with_algorithm(Algorithm::HS512),
            "RS256" => base
                .with_rsa_private_pem(rsa_pem.unwrap_or(""))
                .and_then(|h| h.try_with_algorithm(Algorithm::RS256)),
            "ES256" => base
                .with_ec_pem(ec_pem.unwrap_or(""))
                .and_then(|h| h.try_with_algorithm(Algorithm::ES256)),
            "EdDSA" => base
                .with_ed_pem(ed_pem.unwrap_or(""))
                .and_then(|h| h.try_with_algorithm(Algorithm::EdDSA)),
            other => Err(GarrisonError::Config(format!(
                "config-jwt-algorithm-unsupported::{other}"
            ))),
        }
    }

    /// 切换签名算法(构造期 fail-fast 版本,推荐)。
    ///
    /// 与 [`with_algorithm`](Self::with_algorithm) 的差异:算法与当前密钥材料
    /// 不匹配时立即返回错误,而非延迟到 `sign`/`verify` 时才拒绝。
    pub fn try_with_algorithm(mut self, algorithm: Algorithm) -> GarrisonResult<Self> {
        validate_algorithm_match(&self.key_material, algorithm)?;
        self.algorithm = algorithm;
        Ok(self)
    }

    /// 切换签名算法(builder 兼容版本)。
    ///
    /// 保持既有 builder 签名(返回 `Self`);算法与密钥材料不匹配时**不在
    /// 此处 panic**,而是在 `sign`/`verify` 入口被 `validate_algorithm_match`
    /// 拦截(fail-closed)。新代码推荐 [`try_with_algorithm`](Self::try_with_algorithm)。
    pub fn with_algorithm(mut self, algorithm: Algorithm) -> Self {
        self.algorithm = algorithm;
        self
    }

    /// 设置设备标识(签发时写入 claims 的 `device` 字段)。
    pub fn with_device(mut self, device: impl Into<String>) -> Self {
        self.device = Some(device.into());
        self
    }

    /// 以 RSA PKCS#1/PKCS#8 PEM 私钥切换为非对称签名(RS256/RS384/RS512)。
    ///
    /// 构造期验证 PEM 可解析(fail-fast);PEM 内容存于私有 `KeyMaterial`,
    /// Debug 输出脱敏。切换后默认算法仍为 HS256,须配合
    /// [`try_with_algorithm`](Self::try_with_algorithm)(推荐)或
    /// [`with_algorithm`](Self::with_algorithm) 设置 RS 系算法。
    pub fn with_rsa_private_pem(mut self, pem: impl Into<String>) -> GarrisonResult<Self> {
        let pem = pem.into();
        // 构造期 fail-fast:PEM 可解析性在构造时验证,错误延迟到 sign 期难排查
        EncodingKey::from_rsa_pem(pem.as_bytes())
            .map_err(|e| GarrisonError::Config(format!("jwt-rsa-pem-invalid::{}", e)))?;
        self.key_material = KeyMaterial::RsaPkcs1Pem(pem);
        Ok(self)
    }

    /// 以 EC PEM 私钥切换为非对称签名(ES256/ES384,PKCS#8 格式)。
    ///
    /// 构造期验证 PEM 可解析(fail-fast);PEM 内容存于私有 `KeyMaterial`,
    /// Debug 输出脱敏。须配合 [`try_with_algorithm`](Self::try_with_algorithm)
    /// 设置 ES 系算法。
    pub fn with_ec_pem(mut self, pem: impl Into<String>) -> GarrisonResult<Self> {
        let pem = pem.into();
        EncodingKey::from_ec_pem(pem.as_bytes())
            .map_err(|e| GarrisonError::Config(format!("jwt-ec-pem-invalid::{}", e)))?;
        self.key_material = KeyMaterial::EcPem(pem);
        Ok(self)
    }

    /// 以 Ed25519 私钥 PEM 切换为非对称签名(EdDSA,PKCS#8 格式,RFC 8410)。
    ///
    /// 构造期验证 PEM 可解析(fail-fast);PEM 内容存于私有 `KeyMaterial`,
    /// Debug 输出脱敏。须配合 [`try_with_algorithm`](Self::try_with_algorithm)
    /// 设置 `EdDSA`。
    pub fn with_ed_pem(mut self, pem: impl Into<String>) -> GarrisonResult<Self> {
        let pem = pem.into();
        // 构造期 fail-fast:PKCS#8 结构可解析性验证(种子长度校验在 verify 路径)
        let _parsed_ok = extract_ed25519_seed(&pem)?;
        self.key_material = KeyMaterial::EdPem(pem);
        Ok(self)
    }

    /// 签发携带 `amr` / `auth_time` claim 的 JWT(MFA 因子账本映射入口)。
    ///
    /// 与 [`sign`](Self::sign) 同一口径,额外写入账本映射结果:`amr` 空切片或
    /// `auth_time` 为 `None` 时对应 claim 不序列化(载荷与既有签发格式一致)。
    /// 签发路径统一经本方法或 `Token::generate_with_amr` 传入账本映射,禁止
    /// 硬编码 claim。
    pub fn sign_with_amr(
        &self,
        login_id: impl Into<String>,
        timeout: i64,
        amr: &[String],
        auth_time: Option<i64>,
    ) -> GarrisonResult<String> {
        let handler = JwtHandler {
            secret: self.secret.clone(),
            algorithm: self.algorithm,
            device: self.device.clone(),
            key_material: match &self.key_material {
                KeyMaterial::Hs => KeyMaterial::Hs,
                KeyMaterial::RsaPkcs1Pem(pem) => KeyMaterial::RsaPkcs1Pem(pem.clone()),
                KeyMaterial::EcPem(pem) => KeyMaterial::EcPem(pem.clone()),
                KeyMaterial::EdPem(pem) => KeyMaterial::EdPem(pem.clone()),
            },
            amr: if amr.is_empty() {
                None
            } else {
                Some(amr.to_vec())
            },
            auth_time,
            tid: self.tid,
        };
        handler.sign(login_id, timeout)
    }

    /// 签发 JWT。
    pub fn sign(&self, login_id: impl Into<String>, timeout: i64) -> GarrisonResult<String> {
        self.sign_with_kid(login_id, timeout, None)
    }

    /// 签发 JWT 并在 header 写入指定 `kid`(多 kid 密钥库签发路径)。
    ///
    /// `kid=None` 时与 [`sign`](Self::sign) 输出完全一致(既有签发格式不变);
    /// `kid=Some` 时 header 携带密钥 ID,供验证方按 kid 路由选择验签钥。
    pub fn sign_with_kid(
        &self,
        login_id: impl Into<String>,
        timeout: i64,
        kid: Option<String>,
    ) -> GarrisonResult<String> {
        let login_id: String = login_id.into();
        self.validate_hs_secret()?;
        if timeout < 0 {
            return Err(GarrisonError::Config(format!(
                "jwt-timeout-negative::{}",
                timeout
            )));
        }
        let now = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .map_err(|e| GarrisonError::Internal(format!("system-clock-error::{}", e)))?
            .as_secs() as i64;
        // 算法-密钥类型匹配校验(fail-closed):防字段被直接改写绕过构造器
        validate_algorithm_match(&self.key_material, self.algorithm)?;
        // 溢出防护:`now + timeout` 在 timeout 接近 i64::MAX 时会溢出
        // (debug panic / release 回绕为负 exp,产生立即过期的 token)。
        // 溢出视为非法参数,fail-fast 返回 InvalidParam。
        let exp = now.checked_add(timeout).ok_or_else(|| {
            GarrisonError::InvalidParam(format!("jwt-timeout-overflow::{}", timeout))
        })?;
        let claims = GarrisonJwtClaims {
            sub: login_id.clone(),
            iat: now,
            exp,
            login_id,
            device: self.device.clone(),
            jti: Some(uuid::Uuid::new_v4().to_string()),
            nbf: Some(now), // 签发时设置 nbf,verify 时强制校验
            amr: self.amr.clone(),
            auth_time: self.auth_time,
            tid: self.tid,
        };
        let header = Header {
            kid,
            ..Header::new(self.algorithm)
        };
        let key = self.encoding_key()?;
        encode(&header, &claims, &key)
            .map_err(|e| GarrisonError::Internal(format!("jwt-sign::{}", e)))
    }

    /// 对称密钥有效性校验(sign / sign_claims 共用):空密钥与低于最小长度
    /// 的密钥 fail-closed(防暴力破解,仅对称路径适用;非对称路径密钥强度由
    /// PEM 位长决定,不在此检查)。
    fn validate_hs_secret(&self) -> GarrisonResult<()> {
        if matches!(self.key_material, KeyMaterial::Hs) && self.secret.is_empty() {
            return Err(GarrisonError::Config("jwt-secret-empty::".to_string()));
        }
        if matches!(self.key_material, KeyMaterial::Hs) && self.secret.len() < MIN_SECRET_BYTES {
            return Err(GarrisonError::Config(format!(
                "jwt-secret-too-short::{}::{}",
                self.secret.len(),
                MIN_SECRET_BYTES
            )));
        }
        Ok(())
    }

    /// 以本 handler 的密钥材料与算法签发**调用方自定义**的 claims(crate 内部
    /// 复用通道,不对外导出)。
    ///
    /// `sign` 只能签发 [`GarrisonJwtClaims`];OIDC Back-Channel Logout 等需要
    /// 不同 claim 集(如 `events` / `aud`、且不得携带 `login_id` 等身份扩展)的
    /// 签发方经本通道复用同一密钥材料与算法-密钥匹配校验,避免旁路重造
    /// EncodingKey 构造逻辑。校验与 `sign` 完全一致:对称密钥空/过短 fail-closed、
    /// 算法-密钥类型匹配校验。
    ///
    /// 注意:本方法**不做** exp/iat 等标准时间字段填充——由调用方的 claims
    /// 结构自行携带,语义由调用方定义。
    // 唯一生产调用方为 backchannel(backchannel-logout 门控);仅启用
    // protocol-jwt 而无 backchannel-logout 的组合(compile 矩阵 jwt-ct-eq、
    // oauth2-redis lib 面)只剩测试调用,按仓库 cfg_attr 先例定向豁免。
    #[cfg_attr(not(any(test, feature = "backchannel-logout")), allow(dead_code))]
    pub(crate) fn sign_claims<T: Serialize>(&self, claims: &T) -> GarrisonResult<String> {
        self.validate_hs_secret()?;
        validate_algorithm_match(&self.key_material, self.algorithm)?;
        let header = Header::new(self.algorithm);
        let key = self.encoding_key()?;
        encode(&header, claims, &key)
            .map_err(|e| GarrisonError::Internal(format!("jwt-sign-claims::{}", e)))
    }

    /// 按密钥材料构造签名密钥(sign 路径)。
    fn encoding_key(&self) -> GarrisonResult<EncodingKey> {
        Ok(match &self.key_material {
            KeyMaterial::Hs => EncodingKey::from_secret(self.secret.as_bytes()),
            KeyMaterial::RsaPkcs1Pem(pem) => EncodingKey::from_rsa_pem(pem.as_bytes())
                .map_err(|e| GarrisonError::Internal(format!("jwt-rsa-key::{}", e)))?,
            KeyMaterial::EcPem(pem) => EncodingKey::from_ec_pem(pem.as_bytes())
                .map_err(|e| GarrisonError::Internal(format!("jwt-ec-key::{}", e)))?,
            KeyMaterial::EdPem(pem) => EncodingKey::from_ed_pem(pem.as_bytes())
                .map_err(|e| GarrisonError::Internal(format!("jwt-ed-key::{}", e)))?,
        })
    }

    /// 按密钥材料构造验签密钥(verify 路径;非对称从私钥提取公钥成分)。
    fn decoding_key(&self) -> GarrisonResult<DecodingKey> {
        match &self.key_material {
            KeyMaterial::Hs => Ok(DecodingKey::from_secret(self.secret.as_bytes())),
            // 非对称路径:jsonwebtoken 验证端只接受公钥(RSA 公钥组件/SEC1 点/Ed 公钥),
            // 由各辅助函数从私钥 PEM 推导;garrison 代码不接触 rsa crate 解密 API
            // (RUSTSEC-2023-0071 仅影响其解密路径)
            KeyMaterial::RsaPkcs1Pem(pem) => rsa_decoding_key(pem),
            KeyMaterial::EcPem(pem) => ec_decoding_key(pem),
            KeyMaterial::EdPem(pem) => ed_decoding_key(pem),
        }
    }

    /// 私钥 PEM 访问器(crate 内快照导出用)。
    ///
    /// 对称钥(Hs)无私钥 PEM,返回 `None`。返回值为敏感材料,
    /// 调用方不得写入日志或调试输出。
    pub(crate) fn private_pem(&self) -> Option<&str> {
        match &self.key_material {
            KeyMaterial::Hs => None,
            KeyMaterial::RsaPkcs1Pem(pem) => Some(pem),
            KeyMaterial::EcPem(pem) => Some(pem),
            KeyMaterial::EdPem(pem) => Some(pem),
        }
    }

    /// 校验 JWT 并返回 Claims。
    ///
    /// 失败分类:secret 为空/过短返回 `Config`,过期返回 `ExpiredToken`,
    /// 签名/格式/算法校验失败返回 `InvalidToken`。
    pub fn verify(&self, token: &str) -> GarrisonResult<GarrisonJwtClaims> {
        // 空密钥/过短密钥检查仅对称路径适用(与 sign 一致):config 层允许
        // 非对称算法下 jwt_secret 留空作占位(密钥强度由 PEM 决定),无条件
        // 检查会误拒该合法配置
        self.validate_hs_secret()?;
        // 算法-密钥类型匹配校验(fail-closed):防字段被直接改写绕过构造器
        validate_algorithm_match(&self.key_material, self.algorithm)?;
        let key = self.decoding_key()?;
        let mut validation = Validation::new(self.algorithm);
        validation.validate_exp = true;
        // 拒绝 nbf 为未来的 token;leeway=0:不容忍时钟偏差,过期立即拒绝(安全框架默认严格)
        validation.validate_nbf = true;
        validation.leeway = 0;
        let decoded: jsonwebtoken::TokenData<GarrisonJwtClaims> =
            decode(token, &key, &validation).map_err(map_verify_error)?;
        Ok(decoded.claims)
    }

    /// 刷新 JWT:验证旧 token 后以其 claims 签发新 token。
    pub fn refresh(&self, token: &str, new_timeout: i64) -> GarrisonResult<String> {
        let claims = self.verify(token)?;
        self.sign(claims.login_id, new_timeout)
    }

    /// 签发携带自定义 claims 的 JWT(复用同一密钥材料与算法配置)。
    ///
    /// [`Self::sign`] 固定签发 [`GarrisonJwtClaims`];需要扩展 claim 集
    /// (如找回密码 ActionToken 的 `purpose` claim)的模块经本方法以同一
    /// 密钥/算法签发。空密钥与最小密钥长度检查、算法-密钥类型匹配校验
    /// 与 `sign` 完全一致(fail-closed)。
    pub fn sign_custom<T: serde::Serialize>(&self, claims: &T) -> GarrisonResult<String> {
        self.ensure_symmetric_secret_usable()?;
        validate_algorithm_match(&self.key_material, self.algorithm)?;
        let header = Header::new(self.algorithm);
        let key = self.encoding_key()?;
        encode(&header, claims, &key)
            .map_err(|e| GarrisonError::Internal(format!("jwt-sign::{}", e)))
    }

    /// 校验携带自定义 claims 的 JWT。
    ///
    /// 校验语义与 [`Self::verify`] 一致:`validate_exp = true`、`leeway = 0`
    /// (过期立即拒绝,不容忍时钟偏差)、算法-密钥类型匹配校验。
    /// 过期返回 [`GarrisonError::ExpiredToken`],签名/格式非法返回
    /// [`GarrisonError::InvalidToken`]。
    pub fn verify_custom<T: DeserializeOwned>(&self, token: &str) -> GarrisonResult<T> {
        self.ensure_symmetric_secret_usable()?;
        validate_algorithm_match(&self.key_material, self.algorithm)?;
        let key = self.decoding_key()?;
        let mut validation = Validation::new(self.algorithm);
        validation.validate_exp = true;
        // 与 verify 一致:leeway=0,过期立即拒绝(安全框架默认严格)
        validation.leeway = 0;
        let decoded: jsonwebtoken::TokenData<T> =
            decode(token, &key, &validation).map_err(map_verify_error)?;
        Ok(decoded.claims)
    }

    /// 对称路径密钥可用性检查(空密钥/短密钥拒绝),`sign` / `verify` /
    /// `sign_custom` / `verify_custom` 四入口共用。
    ///
    /// 空密钥检查仅对称路径适用:config 层允许非对称算法下 `jwt_secret` 留空
    /// 作占位(密钥强度由 PEM 决定),无条件检查会误拒该合法配置。
    fn ensure_symmetric_secret_usable(&self) -> GarrisonResult<()> {
        if matches!(self.key_material, KeyMaterial::Hs) {
            if self.secret.is_empty() {
                return Err(GarrisonError::Config("jwt-secret-empty::".to_string()));
            }
            if self.secret.len() < MIN_SECRET_BYTES {
                return Err(GarrisonError::Config(format!(
                    "jwt-secret-too-short::{}::{}",
                    self.secret.len(),
                    MIN_SECRET_BYTES
                )));
            }
        }
        Ok(())
    }
}

// Drop 零化仅在 `protocol-zeroize` feature 下编译:启用后密钥内存在 handler 析构时
// 被覆写;未启用时随普通 String 释放、内容不保证被清除(可能残留已释放堆块 /
// swap / core dump)。保持 feature 结构(零开销默认构建);`secret` 字段的可读性
// 风险见 `JwtHandler::secret` 字段文档。
#[cfg(feature = "protocol-zeroize")]
impl Drop for JwtHandler {
    fn drop(&mut self) {
        use zeroize::Zeroize;
        self.secret.zeroize();
    }
}