garrison 0.9.0

Garrison - 面向 Rust 生态的一站式身份认证鉴权框架
Documentation
// Copyright (c) 2026 Kirky.X🌠
// SPDX-License-Identifier: Apache-2.0

//! JWT 协议插件模块:基于 `jsonwebtoken` 10 实现签发、校验与刷新。
//!
//! 仅在启用 `protocol-jwt` 特性时编译。

/// RefreshToken Rotation 子模块。
pub mod refresh;

/// 多 kid 密钥库子模块(KeyStatus 三态 + JwkSet 三视图)。
pub mod keystore;

/// JwtHandler 实现(签发/校验/刷新)。
mod handler;

// pub(crate):`verify_ok` 墙钟回跳容错包装被其他模块的单测复用
// (同 `dao::tests::MockDao` 的仓库先例)。
#[cfg(test)]
pub(crate) mod tests;

use handler::KeyMaterial;

pub use handler::JwkPublicKey;
pub use keystore::{
    kid_for, rfc7638_kid, JwkEntryView, JwkSet, KeyRotationOutcome, KeySnapshot, KeyStatus,
};

use jsonwebtoken::Algorithm;
use serde::{Deserialize, Serialize};

/// Garrison JWT Claims 载荷。
///
/// 标准字段 `sub` / `iat` / `exp` 之外,携带 `login_id` / `device` 扩展字段,
/// 以及 `jti`(RFC 7519 §4.1.7)保证同一秒内签发的 token 唯一。
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GarrisonJwtClaims {
    /// 主体标识(与 login_id 字符串一致)。
    pub sub: String,

    /// 签发时间(Unix 秒)。
    pub iat: i64,

    /// 过期时间(Unix 秒)。
    pub exp: i64,

    /// Garrison 登录标识(字符串形式,与 sub 一致)。
    pub login_id: String,

    /// 可选设备标识。
    pub device: Option<String>,

    /// JWT 唯一标识(RFC 7519 §4.1.7)。
    ///
    /// `sign` 时自动生成 UUID;`Option` 兼容不含 `jti` 的外部签发 token(该
    /// claim 本身可选),保证同一秒内为同一用户签发的 token 仍唯一(rotation 语义)。
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub jti: Option<String>,

    /// Not Before(RFC 7519 §4.1.5)。
    ///
    /// `sign` 时自动设置为当前时间。`verify` 启用 `validate_nbf = true` 后,
    /// `nbf` 为未来时间时拒绝 token(ImmatureSignature)。字段为 `Option` 以
    /// 兼容不含 `nbf` 的外部签发 token(该 claim 可选,缺失时 jsonwebtoken
    /// 跳过 nbf 校验)。
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub nbf: Option<i64>,

    /// 认证方法引用(RFC 8176 `amr` claim)。
    ///
    /// 来自会话因子账本(如 `["pwd","otp"]`)。字段为 `Option` 以兼容
    /// 不携带账本映射的签发路径——`None` 时整体跳过序列化,载荷与
    /// 历史格式保持一致。
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub amr: Option<Vec<String>>,

    /// 主认证时刻(OIDC Core `auth_time` claim,Unix 秒)。
    ///
    /// 来自会话 `auth_time`;为 `None` 时整体跳过序列化。
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub auth_time: Option<i64>,

    /// 签发租户绑定(多租户部署的 Stateless JWT 补口)。
    ///
    /// 签发时写入签发租户 ID(`GarrisonLogicDefault::generate_token` 经
    /// `JwtHandler::with_tid` 接线);`check_login_stateless` 从验签 claims 直接
    /// 读取并校验与请求租户一致——客户端可控的请求租户头不得携他租户签发的
    /// JWT 跨租户复用,否则 jti 黑名单随请求租户命名空间错位形成吊销逃逸。
    /// `Option` 向后兼容存量 token:无租户签发时不序列化(载荷与既有格式逐字节
    /// 一致),历史 token 无 `tid` 解析为 `None`(verify 行为不变)。
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub tid: Option<i64>,
    // 找回密码扩展 claim(password_owner/password_token_type/password_purpose)
    // 审查后移除:ActionToken 自有 claims 结构承载流程语义,GarrisonJwtClaims
    // 上的同名扩展从未被写入非 None 值(无校验死代码,诱导未来无 enforcement
    // 的写入);登录 token 与动作令牌的互串由必填字段结构性阻断。
}

/// JWT 处理器,封装密钥与签名算法以供复用。
///
/// 默认采用 HS256 算法,可通过 `with_algorithm` 切换为 HS512 等。
/// 通过 `with_device` 设置设备标识,签发时写入 claims。
pub struct JwtHandler {
    /// 签名密钥。
    ///
    /// # 安全注意
    ///
    /// 任何持有 handler 的代码都能直接读出原始密钥——视为敏感对象,仅在可信
    /// 边界内传递,不写日志或序列化输出。Drop 零化仅在 `protocol-zeroize`
    /// feature 下生效(见 `handler.rs`):未启用时密钥内存随普通 `String`
    /// 释放,不保证被覆写。
    pub secret: String,
    /// 签名算法(默认 HS256)。
    pub algorithm: Algorithm,
    /// 可选设备标识(签发时写入 claims)。
    pub device: Option<String>,
    /// 可选 `amr` claim(RFC 8176 认证方法引用,经 [`sign_with_amr`](crate::protocol::jwt::JwtHandler::sign_with_amr) 写入)。
    pub amr: Option<Vec<String>>,
    /// 可选 `auth_time` claim(OIDC 主认证时刻,经 [`sign_with_amr`](crate::protocol::jwt::JwtHandler::sign_with_amr) 写入)。
    pub auth_time: Option<i64>,
    /// 可选签发租户绑定(签发时写入 claims `tid`,builder [`with_tid`](JwtHandler::with_tid) 设置)。
    ///
    /// `pub(crate)`:租户上下文签发属框架内部职责(`GarrisonLogicDefault::generate_token`),
    /// 不对外暴露租户语义注入点。默认 `None`,签发格式与既有 token 一致。
    pub(crate) tid: Option<i64>,
    /// 密钥材料(crate 内私有):决定 sign/verify 的密钥来源与算法白名单。
    ///
    /// `new()` 默认 [`KeyMaterial::Hs`](crate::protocol::jwt::KeyMaterial);非对称
    /// 密钥经 `with_rsa_private_pem` / `with_ec_pem` / `with_ed_pem` 构造器注入
    /// (见 `handler.rs`)。算法与密钥类型的匹配约束见 `validate_algorithm_match`。
    pub(crate) key_material: KeyMaterial,
}