{"id":51937351,"url":"https://github.com/kirky-x/garrison","last_synced_at":"2026-07-28T16:01:03.227Z","repository":{"id":372521735,"uuid":"1285344355","full_name":"Kirky-X/garrison","owner":"Kirky-X","description":"Rust identity \u0026 authentication framework inspired by Sa-Token — JWT, OAuth2, session management, role-based permission control, and SSO integration","archived":false,"fork":false,"pushed_at":"2026-07-21T20:12:36.000Z","size":5249,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-21T20:28:22.833Z","etag":null,"topics":["authentication","authorization","jwt","oauth2","rust","sa-token","security"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kirky-X.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"audit.toml","citation":null,"codeowners":".github/CODEOWNERS","security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-30T17:56:41.000Z","updated_at":"2026-07-21T20:14:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Kirky-X/garrison","commit_stats":null,"previous_names":["kirky-x/garrison"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/Kirky-X/garrison","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kirky-X%2Fgarrison","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kirky-X%2Fgarrison/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kirky-X%2Fgarrison/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kirky-X%2Fgarrison/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kirky-X","download_url":"https://codeload.github.com/Kirky-X/garrison/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kirky-X%2Fgarrison/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35999100,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-28T02:00:06.341Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","authorization","jwt","oauth2","rust","sa-token","security"],"created_at":"2026-07-28T16:01:01.913Z","updated_at":"2026-07-28T16:01:03.216Z","avatar_url":"https://github.com/Kirky-X.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- markdownlint-disable MD041 --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./docs/assets/logo.png\" alt=\"Garrison Logo\" width=\"360\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  中文 | \u003ca href=\"./README_EN.md\"\u003eEnglish\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003e面向 Rust 生态的一站式身份认证鉴权框架\u003c/b\u003e\u003cbr/\u003e\n  \u003ca href=\"#quick-start\"\u003e🚀 快速开始\u003c/a\u003e •\n  \u003ca href=\"#features\"\u003e📖 特性\u003c/a\u003e •\n  \u003ca href=\"./docs/ARCHITECTURE.md\"\u003e🏗 架构\u003c/a\u003e •\n  \u003ca href=\"./CHANGELOG.md\"\u003e📝 更新日志\u003c/a\u003e •\n  \u003ca href=\"./docs/CONTRIBUTING.md\"\u003e🤝 贡献\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/crates/v/garrison?label=version\" alt=\"version\" /\u003e\n  \u003cimg src=\"https://img.shields.io/github/license/Kirky-X/garrison?label=license\" alt=\"license\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/MSRV-1.85+-orange\" alt=\"msrv\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/coverage-95%25%2B-brightgreen\" alt=\"coverage\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/tests-4116%2B%20passed-success\" alt=\"tests\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/clippy-zero%20warnings-success\" alt=\"clippy\" /\u003e\n\u003c/p\u003e\n\n\u003c!-- markdownlint-restore MD041 --\u003e\n\n---\n\n## 📑 目录\n\n- [概述](#-概述)\n- [特性](#-特性)\n- [架构](#-架构)\n- [快速开始](#-quick-start)\n  - [前置依赖](#前置依赖)\n  - [安装](#安装)\n  - [最小示例](#最小示例)\n  - [axum 集成示例](#axum-集成示例)\n- [配置](#️-配置)\n- [特性门控](#-特性门控)\n- [API 文档](#-api-文档)\n- [贡献](#-贡献)\n- [路线图](#-路线图)\n- [许可证](#-许可证)\n- [致谢](#-致谢)\n\n---\n\n## 🔭 概述\n\n**Garrison** 是一个面向 Rust 生态的身份认证鉴权框架，\n提供基于 Token 的会话管理、RBAC 权限模型、axum Web 框架集成等核心能力。\n\n框架采用**双抽象层 + 全局单例**架构：\n\n- **dbnexus** 数据库抽象层（SQLite / PostgreSQL / MySQL，由 `GarrisonDao` trait 屏蔽后端差异）\n- **oxcache** 缓存抽象层（L1 内存 + L2 redis，承载会话与 Token 存储）\n- **GarrisonManager** 全局单例，持有 `Arc\u003cGarrisonLogicDefault\u003e`（实现了 6 个子 trait：`GarrisonCore` / `SessionLogic` / `PermissionLogic` / `TokenLogic` / `MfaLogic` / `PasswordLogic`），业务方启动时一次性注入依赖即可使用静态 API\n\n### 适用场景\n\n- **Web 应用认证**：基于 axum/actix/warp 的 Web 服务需要登录认证、权限校验\n- **微服务网关**：API 网关层统一鉴权，支持 JWT/OAuth2/API Key 多种协议\n- **企业级后台**：RBAC 权限模型 + 会话管理 + 审计日志\n- **多端 SSO**：跨子系统单点登录，ticket 模型 + 一次性消费\n\n---\n\n## ✨ 特性\n\n| 特性                | 说明                                                                                              |\n| ------------------- | ------------------------------------------------------------------------------------------------- |\n| ⚡ **零运行时开销** | 编译期 `inventory::submit!` 工厂注册，无反射、无动态加载                                          |\n| 🔒 **完整鉴权链**   | 登录认证 → 权限校验 → 会话管理 → 路由拦截，开箱即用                                               |\n| 📦 **多后端抽象**   | `GarrisonDao` + `oxcache` + `dbnexus`，切换存储后端零业务代码改动                                 |\n| 🔧 **可插拔扩展**   | trait + Default 实现模式，替换任意组件（DAO / 策略 / 逻辑）无需改业务                             |\n| 🎯 **Feature 门控** | 40+ 个特性域独立 feature flag，按需编译减小体积                                                   |\n| 📊 **高可观测**     | `tracing` 日志 + `listener` 事件订阅 + `prometheus` 指标（可选）                                  |\n| 🧪 **高覆盖**       | 4116+ 个测试通过（4051 lib + 65 E2E），95%+ 行覆盖率，clippy 零警告                               |\n| 🌐 **Web 框架适配** | axum/actix/warp 三框架注解式 extractor（`CheckLogin` / `CheckRole` / `CheckPermission` + 过程宏） |\n\n### 特性域覆盖（0.4.0~0.6.0 协议层与生产能力补齐）\n\n| 特性域                         | 状态                       | 说明                                                                                                                                                                                                                             |\n| ------------------------------ | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 登录认证                       | ✅ 0.1.0 完成              | 基于 Token 的会话管理                                                                                                                                                                                                            |\n| 权限认证                       | ✅ 0.1.0 完成              | RBAC 权限模型                                                                                                                                                                                                                    |\n| Session 会话                   | ✅ 0.1.0 完成              | 双模会话生命周期管理（Account + Token）                                                                                                                                                                                          |\n| 路由拦截鉴权                   | ✅ 0.1.0 完成              | axum Web 框架适配                                                                                                                                                                                                                |\n| JWT                            | ✅ 0.2.0 完成              | JSON Web Token 签发与验证（HS256/HS512 + refresh）                                                                                                                                                                               |\n| OAuth2                         | ✅ 0.2.0 完成              | 授权码 / 客户端凭证 / 密码模式 + 0.4.0 RefreshToken                                                                                                                                                                              |\n| 单点登录 (SSO)                 | ✅ 0.2.0 完成              | ticket 模型单点登录（一次性 60s TTL）                                                                                                                                                                                            |\n| 微服务网关鉴权                 | ✅ 0.2.0 完成              | API 签名 + nonce 防重放                                                                                                                                                                                                          |\n| API 接口鉴权                   | ✅ 0.2.0 完成              | API Key 生成 / 校验 / 吊销 / 轮换                                                                                                                                                                                                |\n| 临时凭证                       | ✅ 0.2.0 完成              | 短期 token + issue/get/revoke/consume                                                                                                                                                                                            |\n| TOTP 动态验证码                | ✅ 0.2.0 完成              | RFC 6238 二次验证                                                                                                                                                                                                                |\n| Basic 认证                     | ✅ 0.2.0 完成              | HTTP Basic Auth (RFC 7617)                                                                                                                                                                                                       |\n| Digest 认证                    | ✅ 0.2.0 完成              | HTTP Digest Auth (RFC 7616)                                                                                                                                                                                                      |\n| 插件化扩展                     | ✅ 0.2.0 完成              | `GarrisonPlugin` trait + inventory 注册                                                                                                                                                                                          |\n| 事件监听器                     | ✅ 0.2.0 完成 / 0.4.2 扩展 | `GarrisonListener` trait + 15 个事件变体（0.4.2 新增 9 个）                                                                                                                                                                      |\n| OIDC（OpenID Connect）         | ✅ 0.4.0 完成              | id_token 签发/验证 + discovery + 三重防重放                                                                                                                                                                                      |\n| OAuth2 Scope Handler           | ✅ 0.4.0 完成              | `ScopeHandler` trait + `ScopeRegistry` 注册表                                                                                                                                                                                    |\n| SSO Server 独立抽象            | ✅ 0.4.0 完成              | `SsoServer` trait + `CenterIdConverter` + `SsoChannel`                                                                                                                                                                           |\n| AloneCache 多实例隔离          | ✅ 0.4.0 完成              | `AloneCache` 装饰器 + `AloneCacheManager`                                                                                                                                                                                        |\n| ParameterQuery 参数化查询      | ✅ 0.4.0 完成              | `ParameterQuery` trait + Builder + async check_permission/check_role                                                                                                                                                             |\n| ~~LoginId newtype~~            | ❌ 0.5.2 删除              | ~~`LoginId` enum（Numeric/String），公开 API 接受 `impl Into\u003cLoginId\u003e`~~ 全栈迁移到 `String`/`\u0026str`                                                                                                                              |\n| Repository 层                  | ✅ 0.4.2 完成              | 9 个 Repository trait + SqliteRepository（tenant_id 隔离）                                                                                                                                                                       |\n| 密码哈希                       | ✅ 0.4.2 完成              | `PasswordHasher` trait + Argon2/Bcrypt 实现 + 自动识别                                                                                                                                                                           |\n| 密码登录                       | ✅ 0.4.2 完成              | `login_with_password` 整合 Repository + PasswordHasher                                                                                                                                                                           |\n| 多账户 login_type              | ✅ 0.4.2 完成              | `get_permission_list_with_type` / `get_role_list_with_type`                                                                                                                                                                      |\n| JWT 三模式                     | ✅ 0.4.2 完成              | `JwtMode` Stateless/Mixin/Simple                                                                                                                                                                                                 |\n| API Key namespace              | ✅ 0.4.2 完成              | `garrison:apikey:\u003cnamespace\u003e:\u003ckey\u003e` 多租户隔离                                                                                                                                                                                   |\n| SSO TOCTOU 修复                | ✅ 0.4.2 完成              | `GarrisonDao::get_and_delete` 原子消费                                                                                                                                                                                           |\n| kickout_by_device              | ✅ 0.4.2 完成              | 按设备维度踢出会话                                                                                                                                                                                                               |\n| ActixContext 适配器            | ✅ 0.4.2 完成              | actix-web 4 4 件套（ActixContext/Request/Response/Storage）                                                                                                                                                                      |\n| WarpContext 适配器             | ✅ 0.4.2 完成              | warp 0.4 4 件套（WarpContext/Request/Response/Storage）                                                                                                                                                                          |\n| Strategy Registry              | ✅ 0.4.2 完成              | 6 个策略 trait + `Strategy` 注册表 + Manager 集成                                                                                                                                                                                |\n| 过程宏注解                     | ✅ 0.4.2 完成              | 10 个属性宏：`#[check_login]` / `#[check_permission]` / `#[check_role]` / `#[check_access_token]` / `#[check_client_token]` / `#[check_temp_token]` / `#[check_api_key]` / `#[check_mfa]` / `#[check_abac]` / `#[check_disable]` |\n| OAuth 2.1 PKCE                 | ✅ 0.4.2 完成              | RFC 7636 S256 方法，旧方法标记 deprecated                                                                                                                                                                                        |\n| Token Introspection            | ✅ 0.4.2 完成              | RFC 7662 远程 token 状态查询                                                                                                                                                                                                     |\n| 多租户隔离                     | ✅ 0.5.0 完成              | `tenant_id` 字段 + `task_local!` TenantContext + Repository 强制过滤                                                                                                                                                             |\n| 社交登录                       | ✅ 0.5.0 完成              | 微信扫码 / 支付宝 Provider + SocialBinding 表                                                                                                                                                                                    |\n| 审计日志                       | ✅ 0.5.0 完成              | `audit_logs` 表 + 14 个 listener 事件订阅 + 自动脱敏                                                                                                                                                                             |\n| RefreshToken Rotation          | ✅ 0.5.0 完成              | SHA-256 hash chain + parentTokenHash + 重用检测                                                                                                                                                                                  |\n| 安全防护套件                   | ✅ 0.5.0 完成              | 5 个 FirewallStrategy + MaxMindDb 生产后端                                                                                                                                                                                       |\n| 角色层级                       | ✅ 0.5.0 完成              | `role_hierarchy` 表 + TC 预计算 + 登录时缓存权限并集                                                                                                                                                                             |\n| 决策溯源                       | ✅ 0.5.0 完成              | `Decision{allowed, reason, errors}` + `authorize()` API                                                                                                                                                                          |\n| Keycloak OIDC RP               | ✅ 0.5.0 完成              | `KeycloakProvider` discovery + JWKS 验签                                                                                                                                                                                         |\n| PostgreSQL 后端                | ✅ 0.5.0 完成              | `db-postgres` feature + backend-agnostic SQL                                                                                                                                                                                     |\n| MySQL 后端                     | ✅ 0.5.3 完成              | `db-mysql` feature + testcontainers 集成测试                                                                                                                                                                                     |\n| 账号安全引擎                   | ✅ 0.6.0 完成              | `account/` 模块 + Credential SPI + PasswordPolicyEngine + UserLockoutStrategy + AuthenticationFlow DSL                                                                                                                           |\n| remember-me 扩展超时           | ✅ 0.6.1 完成              | `remember_me_enabled` / `remember_me_timeout` 配置 + login 参数                                                                                                                                                                  |\n| Redis 部署模式                 | ✅ 0.6.1 完成              | `RedisDeploymentMode` 枚举（Single/Sentinel/Cluster/MasterSlave）                                                                                                                                                                |\n| 身份切换 switch_to             | ✅ 0.6.1 完成              | `switch_to(login_id)` 会话身份切换                                                                                                                                                                                               |\n| Token 置换 renew_to_equivalent | ✅ 0.6.1 完成              | 等效 Token 置换（保留会话状态）                                                                                                                                                                                                  |\n| OAuth2 注解                    | ✅ 0.6.1 完成              | `Annotation::CheckAccessToken` / `CheckClientToken`                                                                                                                                                                              |\n| 路由分组 group()               | ✅ 0.6.1 完成              | `GarrisonRouter::group(prefix, annotation, f)`                                                                                                                                                                                   |\n| 会话过期回调                   | ✅ 0.6.1 完成              | `SessionExpiryListener` trait + `add_expiry_listener`                                                                                                                                                                            |\n| SAML 2.0 骨架                  | ✅ 0.6.1 完成              | `SamlProvider` trait + `DefaultSamlProvider`（quick-xml 解析）                                                                                                                                                                   |\n| OIDC RP 骨架                   | ✅ 0.6.1 完成              | `OidcProvider` trait + `DefaultOidcProvider`（discovery + token exchange）                                                                                                                                                       |\n| Redis pub/sub SsoChannel       | ✅ 0.6.1 完成              | `RedisPubSubSsoChannel`（PUBLISH/SUBSCRIBE 跨实例通信）                                                                                                                                                                          |\n\n---\n\n## 🏗 架构\n\n```mermaid\ngraph TD\n    User[\"业务代码\"] --\u003e Util[\"GarrisonUtil 静态 API\"]\n    Util --\u003e Manager[\"GarrisonManager 单例\"]\n    Manager --\u003e     Logic[\"GarrisonLogicDefault\"]\n    Logic --\u003e Session[\"GarrisonSession\"]\n    Logic --\u003e Strategy[\"GarrisonPermissionStrategy\"]\n    Session --\u003e Dao[\"GarrisonDao trait\"]\n    Strategy --\u003e Interface[\"GarrisonInterface 业务回调\"]\n    Dao --\u003e Oxcache[\"oxcache (L1 内存 + L2 redis)\"]\n    Dao --\u003e Dbnexus[\"dbnexus (SQLite)\"]\n    Logic --\u003e Plugin[\"GarrisonPlugin (inventory)\"]\n    Logic --\u003e Listener[\"GarrisonListener (inventory)\"]\n    Annotation[\"axum 注解\u003cbr/\u003eCheckLogin / CheckRole / CheckPermission\"] --\u003e Logic\n    Router[\"GarrisonRouter\"] --\u003e Interceptor[\"GarrisonInterceptor\"]\n    Interceptor --\u003e Util\n```\n\n核心模块说明：\n\n- `stp/`：核心 API（6 个子 trait：`GarrisonCore` / `SessionLogic` / `PermissionLogic` / `TokenLogic` / `MfaLogic` / `PasswordLogic` + `GarrisonUtil` 静态委托 + task_local 上下文）\n- `garrison-session`：双模会话管理（Account-Session + Token-Session）\n- `garrison-strategy`：权限校验策略（`GarrisonPermissionStrategy` trait）\n- `garrison-manager`：全局单例 + inventory 工厂注册\n- `garrison-annotation`：axum extractor 注解系统\n- `garrison-router`：axum Router 包装 + middleware 拦截\n- `garrison-dao`：`GarrisonDao` trait + oxcache / dbnexus 实现\n\n完整架构设计见 [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)。\n\n---\n\n## 🚀 Quick Start\n\n### 前置依赖\n\n| 依赖       | 版本         | 说明                                 |\n| ---------- | ------------ | ------------------------------------ |\n| Rust       | \u003e= 1.85      | 工具链（部分 deps 要求 edition2024） |\n| cargo      | 随 Rust 安装 | 包管理器                             |\n| libssl-dev | 系统包       | `cargo tarpaulin` 覆盖率工具需要     |\n| pkg-config | 系统包       | `cargo tarpaulin` 覆盖率工具需要     |\n\n\u003e 注：运行时无需额外系统依赖，`oxcache` 与 `dbnexus` 均为纯 Rust 实现。\n\n### 安装\n\n在 `Cargo.toml` 中添加依赖：\n\n```toml\n[dependencies]\ngarrison = { version = \"0.8\", features = [\"web-axum\"] }\ntokio = { version = \"1\", features = [\"full\"] }\n```\n\n如需启用全部协议层与安全模块：\n\n```toml\n[dependencies]\ngarrison = { version = \"0.8\", features = [\"full\"] }\n```\n\n### 最小示例\n\n完整业务场景：初始化管理器 → 执行登录 → 校验登录状态 → 登出。\n\n```rust\nuse std::sync::Arc;\nuse garrison::prelude::*;\nuse async_trait::async_trait;\n\n// 1. 业务方实现 GarrisonInterface（提供权限/角色数据）\nstruct MyInterface;\n#[async_trait]\nimpl GarrisonInterface for MyInterface {\n    async fn get_permission_list(\u0026self, _login_id: i64) -\u003e GarrisonResult\u003cVec\u003cString\u003e\u003e {\n        Ok(vec![\"user:read\".into(), \"user:write\".into()])\n    }\n    async fn get_role_list(\u0026self, _login_id: i64) -\u003e GarrisonResult\u003cVec\u003cString\u003e\u003e {\n        Ok(vec![\"user\".into()])\n    }\n}\n\n#[tokio::main]\nasync fn main() -\u003e GarrisonResult\u003c()\u003e {\n    // 2. 准备依赖\n    let dao: Arc\u003cdyn GarrisonDao\u003e = Arc::new(GarrisonDaoOxcache::new().await?);\n    let config = Arc::new(GarrisonConfig::default_config());\n    let interface: Arc\u003cdyn GarrisonInterface\u003e = Arc::new(MyInterface);\n\n    // 3. 初始化全局管理器（覆盖式注入 dao / config / interface）\n    GarrisonManager::init(dao, config, interface)?;\n\n    // 4. 在 task_local 上下文中执行登录\n    let token = garrison::stp::with_current_token(\n        String::new(),\n        GarrisonUtil::login(\"1001\", \u0026LoginParams::default()),\n    ).await?;\n    println!(\"登录成功，token = {}\", token);\n\n    // 5. 校验登录状态\n    let logged_in = garrison::stp::with_current_token(\n        token.clone(),\n        GarrisonUtil::check_login(),\n    ).await?;\n    assert!(logged_in);\n\n    // 6. 校验权限\n    let has_perm = garrison::stp::with_current_token(\n        token.clone(),\n        GarrisonUtil::check_permission(\"user:read\"),\n    ).await?;\n    assert!(has_perm);\n\n    // 7. 登出\n    garrison::stp::with_current_token(\n        token.clone(),\n        GarrisonUtil::logout(),\n    ).await?;\n\n    Ok(())\n}\n```\n\n**预期输出：**\n\n```text\n登录成功，token = a1b2c3d4e5f6...\n```\n\n### axum 集成示例\n\n完整 Web 应用示例见 [examples/src/bin/axum_integration.rs](./examples/src/bin/axum_integration.rs)（253 行），包含：\n\n- `GarrisonRouter` 包装 axum Router\n- 4 个 `route_protected` 路由（带 `CheckLogin` / `CheckRole\u003cAdminRole\u003e` / `CheckPermission\u003cReadPerm\u003e` 注解）\n- axum middleware 自动从 Authorization header 提取 token 并设置 task_local\n\n\u003e examples 已重组为独立 workspace member（`garrison-examples` crate），运行方式：\n\u003e `cargo run -p garrison-examples --bin \u003cname\u003e --features full`。0.4.0 新增 5 个 example\n\u003e （`oidc_handler` / `scope_handler` / `sso_server` / `alone_cache` / `parameter_query`），\n\u003e 完整列表见 [examples/README](./examples/)。\n\n---\n\n## ⚙️ 配置\n\n`GarrisonConfig` 支持三级配置源（优先级从高到低）：\n\n1. **环境变量**：`GARRISON_TIMEOUT` / `GARRISON_ACTIVE_TIMEOUT` / `GARRISON_TOKEN_NAME` 等\n2. **toml 配置文件**：`garrison.toml`（通过 `GarrisonConfig::load(Some(path))` 加载）\n3. **代码默认值**：`GarrisonConfig::default_config()`\n\n核心配置项：\n\n| 字段                 | 默认值             | 说明                                                  |\n| -------------------- | ------------------ | ----------------------------------------------------- |\n| `timeout`            | `2592000`（30 天） | 会话超时秒数                                          |\n| `active_timeout`     | `-1`（不启用）     | 活跃超时秒数，-1 表示跟随 `timeout`                   |\n| `is_share`           | `false`            | 同账号多端共享会话                                    |\n| `is_concurrent`      | `true`             | 允许同账号并发登录                                    |\n| `token_name`         | `garrison_token`   | Cookie / Header 名                                    |\n| `token_style`        | `random_64`        | Token 风格（`uuid` / `random_64` / `simple` / `jwt`） |\n| `throw_on_not_login` | `true`             | 未登录时抛异常而非返回 false                          |\n\n支持通过 `tokio::sync::watch` 实现配置热更新，详见 [docs/CONFIGURATION.md](./docs/CONFIGURATION.md)。\n\n---\n\n## 🎛 特性门控\n\n| 特性                          | 默认 | 引入版本 | 说明                                                                                                                                                                                                                             |\n| ----------------------------- | :--: | :------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `backend-embedded`            |  ✅  |  0.7.0   | 内嵌后端模式（进程内认证，委托 GarrisonManager）                                                                                                                                                                                 |\n| `backend-remote`              |  ❌  |  0.7.0   | 远程后端适配器（通过 HTTP 调用远程 Auth Server）                                                                                                                                                                                 |\n| `backend-kit`                 |  ❌  |  0.7.0   | trait-kit typestate DI 构建                                                                                                                                                                                                      |\n| `auth-server`                 |  ❌  |  0.7.0   | 独立认证服务器（含 sdforge 声明式路由 + TLS）                                                                                                                                                                                    |\n| `abac`                        |  ❌  |  0.7.0   | 基于 Cedar DSL 的属性访问控制引擎                                                                                                                                                                                                |\n| `oauth2-server`               |  ❌  |  0.7.0   | 完整 OAuth2 Server 4 端点（authorize/token/revoke/introspect）                                                                                                                                                                   |\n| `cache-memory`                |  ❌  |  0.1.0   | 内存缓存后端（oxcache 内存层）                                                                                                                                                                                                   |\n| `cache-redis`                 |  ❌  |  0.1.0   | Redis 缓存后端（oxcache L2）                                                                                                                                                                                                     |\n| `db-sqlite`                   |  ❌  |  0.1.0   | SQLite 数据库后端（dbnexus + auto-migrate）                                                                                                                                                                                      |\n| `db-postgres`                 |  ❌  |  0.5.0   | PostgreSQL 后端                                                                                                                                                                                                                  |\n| `db-mysql`                    |  ❌  |  0.5.3   | MySQL 后端                                                                                                                                                                                                                       |\n| `web-axum`                    |  ❌  |  0.1.0   | axum Web 框架适配                                                                                                                                                                                                                |\n| `web-actix`                   |  ❌  |  0.4.2   | actix-web Web 框架适配                                                                                                                                                                                                           |\n| `web-warp`                    |  ❌  |  0.4.2   | warp Web 框架适配                                                                                                                                                                                                                |\n| `web-waf`                     |  ❌  |  0.6.4   | WAF 级 Web 防火墙中间件                                                                                                                                                                                                          |\n| `web-cors`                    |  ❌  |  0.6.4   | CORS 跨域中间件                                                                                                                                                                                                                  |\n| `web-csrf`                    |  ❌  |  0.6.4   | CSRF 防护中间件                                                                                                                                                                                                                  |\n| `protocol-jwt`                |  ❌  |  0.2.0   | JWT 签发与验证（HS256/HS512 + refresh）                                                                                                                                                                                          |\n| `protocol-oauth2`             |  ❌  |  0.2.0   | OAuth2 四种模式（含 RefreshToken）                                                                                                                                                                                               |\n| `protocol-sso`                |  ❌  |  0.2.0   | SSO 单点登录 ticket                                                                                                                                                                                                              |\n| `protocol-sign`               |  ❌  |  0.2.0   | API 签名 + nonce 防重放                                                                                                                                                                                                          |\n| `protocol-apikey`             |  ❌  |  0.2.0   | API Key 认证                                                                                                                                                                                                                     |\n| `protocol-temp`               |  ❌  |  0.2.0   | 临时凭证                                                                                                                                                                                                                         |\n| `protocol-oidc`               |  ❌  |  0.4.0   | OIDC id_token 签发/验证 + discovery                                                                                                                                                                                              |\n| `protocol-zeroize`            |  ❌  |  0.4.2   | 协议层密钥零化（Drop 时清零 secret 字段）                                                                                                                                                                                        |\n| `oauth2-scope-handler`        |  ❌  |  0.4.0   | OAuth2 ScopeHandler 注册表                                                                                                                                                                                                       |\n| `protocol-sso-server`         |  ❌  |  0.4.0   | SSO Server 独立抽象 + CenterIdConverter                                                                                                                                                                                          |\n| `secure-saml`                 |  ❌  |  0.5.0   | SAML 2.0 骨架（rsa 签名验证）                                                                                                                                                                                                    |\n| `alone-cache`                 |  ❌  |  0.4.0   | AloneCache 多 Redis 实例隔离装饰器                                                                                                                                                                                               |\n| `parameter-query`             |  ❌  |  0.4.0   | ParameterQuery 参数化查询 + Builder                                                                                                                                                                                              |\n| `secure-totp`                 |  ❌  |  0.2.0   | TOTP 动态验证码 (RFC 6238)                                                                                                                                                                                                       |\n| `secure-sign`                 |  ❌  |  0.2.0   | HMAC-SHA256/SHA512 工具                                                                                                                                                                                                          |\n| `secure-httpbasic`            |  ❌  |  0.2.0   | HTTP Basic 认证 (RFC 7617)                                                                                                                                                                                                       |\n| `secure-httpdigest`           |  ❌  |  0.2.0   | HTTP Digest 认证 (RFC 7616)                                                                                                                                                                                                      |\n| `secure-confusable`           |  ❌  |  0.5.1   | Unicode 同形异义字检测                                                                                                                                                                                                           |\n| `secure-masking`              |  ❌  |  0.6.2   | 敏感数据脱敏（regex 真实脱敏）                                                                                                                                                                                                   |\n| `secure-xss`                  |  ❌  |  0.6.2   | XSS 防护                                                                                                                                                                                                                         |\n| `secure-sanitize`             |  ❌  |  0.6.2   | 通用输入消毒                                                                                                                                                                                                                     |\n| `secure-simple-token`         |  ❌  |  0.7.1   | SimpleTokenStyle HMAC-SHA256 签名                                                                                                                                                                                                |\n| `sms-rate-limit`              |  ❌  |  0.6.2   | SMS 验证码限速                                                                                                                                                                                                                   |\n| `account-credential`          |  ❌  |  0.6.0   | 凭证模型 SPI（Argon2/Bcrypt）                                                                                                                                                                                                    |\n| `account-credential-zeroize`  |  ❌  |  0.6.0   | 凭证模型 zeroize 扩展                                                                                                                                                                                                            |\n| `account-policy`              |  ❌  |  0.6.0   | 密码策略引擎                                                                                                                                                                                                                     |\n| `account-lockout`             |  ❌  |  0.6.0   | 用户锁定策略                                                                                                                                                                                                                     |\n| `account-authflow`            |  ❌  |  0.6.0   | AuthenticationFlow DSL                                                                                                                                                                                                           |\n| `listener`                    |  ❌  |  0.2.0   | 事件监听器（15 个事件变体，0.4.2 扩展）                                                                                                                                                                                          |\n| `tracing-log`                 |  ❌  |  0.1.0   | tracing 日志桥接                                                                                                                                                                                                                 |\n| `metrics-prometheus`          |  ❌  |  0.3.0   | Prometheus 指标                                                                                                                                                                                                                  |\n| `observability-otlp`          |  ❌  |  0.3.0   | OpenTelemetry OTLP 分布式追踪                                                                                                                                                                                                    |\n| `audit-inklog`                |  ❌  |  0.7.0   | inklog 结构化审计日志                                                                                                                                                                                                            |\n| `grpc`                        |  ❌  |  0.3.0   | gRPC 鉴权拦截器（tonic::Interceptor）                                                                                                                                                                                            |\n| `annotation-macros`           |  ❌  |  0.4.2   | 10 个属性宏：`#[check_login]` / `#[check_permission]` / `#[check_role]` / `#[check_access_token]` / `#[check_client_token]` / `#[check_temp_token]` / `#[check_api_key]` / `#[check_mfa]` / `#[check_abac]` / `#[check_disable]` |\n| `tenant-isolation`            |  ❌  |  0.5.0   | 多租户逻辑隔离                                                                                                                                                                                                                   |\n| `social-wechat`               |  ❌  |  0.5.0   | 微信扫码社交登录                                                                                                                                                                                                                 |\n| `social-alipay`               |  ❌  |  0.5.0   | 支付宝授权社交登录                                                                                                                                                                                                               |\n| `audit-log`                   |  ❌  |  0.5.0   | 审计日志持久化                                                                                                                                                                                                                   |\n| `firewall`                    |  ❌  |  0.5.0   | 安全防护基础 trait                                                                                                                                                                                                               |\n| `firewall-bruteforce`         |  ❌  |  0.5.0   | 暴力破解防护策略                                                                                                                                                                                                                 |\n| `firewall-ratelimit`          |  ❌  |  0.5.0   | 限流策略                                                                                                                                                                                                                         |\n| `rate-limit-redis`            |  ❌  |  0.6.4   | Redis 限流后端                                                                                                                                                                                                                   |\n| `firewall-anomalous`          |  ❌  |  0.5.0   | 异常登录检测                                                                                                                                                                                                                     |\n| `firewall-geoip`              |  ❌  |  0.5.0   | GeoIP 策略                                                                                                                                                                                                                       |\n| `firewall-ddos`               |  ❌  |  0.5.0   | DDoS 防护策略                                                                                                                                                                                                                    |\n| `firewall-waf`                |  ❌  |  0.6.4   | WAF 级防火墙                                                                                                                                                                                                                     |\n| `firewall-maxminddb`          |  ❌  |  0.5.3   | MaxMindDb 生产后端                                                                                                                                                                                                               |\n| `anomalous-detector-dual`     |  ❌  |  0.6.2   | 异常登录双引擎检测                                                                                                                                                                                                               |\n| `keycloak-oidc`               |  ❌  |  0.5.0   | Keycloak OIDC RP 集成                                                                                                                                                                                                            |\n| `decision-trace`              |  ❌  |  0.4.2   | 决策溯源                                                                                                                                                                                                                         |\n| `authorize-api`               |  ❌  |  0.5.1   | 请求对象式授权 API                                                                                                                                                                                                               |\n| `manager-explicit`            |  ❌  |  0.5.1   | 显式 Manager API                                                                                                                                                                                                                 |\n| `permission-registry`         |  ❌  |  0.5.1   | 权限注册表                                                                                                                                                                                                                       |\n| `safe-defaults`               |  ❌  |  0.6.7   | forbid 优先语义（safe-defaults）                                                                                                                                                                                                 |\n| `security-alert`              |  ❌  |  0.6.5   | 安全告警系统                                                                                                                                                                                                                     |\n| `device-binding`              |  ❌  |  0.6.5   | 设备绑定                                                                                                                                                                                                                         |\n| `safe-auth`                   |  ❌  |  0.6.5   | 二级认证瞬态标记                                                                                                                                                                                                                 |\n| `dynamic-active-timeout`      |  ❌  |  0.6.2   | 动态活跃超时                                                                                                                                                                                                                     |\n| `three-tier-cache`            |  ❌  |  0.6.7   | 三层缓存架构                                                                                                                                                                                                                     |\n| `login-token-map-persistence` |  ❌  |  0.6.6   | login_token_map 持久化                                                                                                                                                                                                           |\n| `anonymous-session`           |  ❌  |  0.6.6   | 匿名 Session                                                                                                                                                                                                                     |\n| `session-search`              |  ❌  |  0.6.6   | 会话搜索                                                                                                                                                                                                                         |\n| `tls`                         |  ❌  |  0.7.0   | HTTPS/TLS 终止（axum-server rustls）                                                                                                                                                                                             |\n| `miette`                      |  ❌  |  0.5.1   | miette 富错误                                                                                                                                                                                                                    |\n| `i18n`                        |  ❌  |  0.3.0   | 国际化基础层（fluent-rs）                                                                                                                                                                                                        |\n| `i18n-icu`                    |  ❌  |  0.3.0   | ICU4X 增强层（复数 + 日期 + 数字本地化）                                                                                                                                                                                         |\n| `full`                        |  ❌  |    —     | 聚合所有特性                                                                                                                                                                                                                     |\n| `production`                  |  ❌  |    —     | 生产环境推荐组合                                                                                                                                                                                                                 |\n| `development`                 |  ❌  |    —     | 开发环境组合                                                                                                                                                                                                                     |\n\n---\n\n## 📚 API 文档\n\n- **在线文档**：[https://docs.rs/garrison](https://docs.rs/garrison)\n- **本地生成**：`cargo doc --no-deps --features full --open`\n- **示例代码**（独立 workspace member，`cargo run -p garrison-examples --bin \u003cname\u003e --features full`）：\n  - [examples/src/bin/basic_login.rs](./examples/src/bin/basic_login.rs)：完整业务场景（167 行）\n  - [examples/src/bin/axum_integration.rs](./examples/src/bin/axum_integration.rs)：完整 Web 应用（253 行）\n  - [examples/src/bin/oidc_handler.rs](./examples/src/bin/oidc_handler.rs)：OIDC id_token 签发/验证（0.4.0 新增）\n  - [examples/src/bin/scope_handler.rs](./examples/src/bin/scope_handler.rs)：ScopeHandler 注册表（0.4.0 新增）\n  - [examples/src/bin/sso_server.rs](./examples/src/bin/sso_server.rs)：SSO Server 独立抽象（0.4.0 新增）\n  - [examples/src/bin/alone_cache.rs](./examples/src/bin/alone_cache.rs)：AloneCache 多实例隔离（0.4.0 新增）\n  - [examples/src/bin/parameter_query.rs](./examples/src/bin/parameter_query.rs)：ParameterQuery 参数化查询（0.4.0 新增）\n  - 完整列表见 [examples/src/lib.rs](./examples/src/lib.rs) 模块声明\n\n---\n\n## 🤝 贡献\n\n欢迎所有形式的贡献！请先阅读 [贡献指南](./docs/CONTRIBUTING.md)。\n\n### 提交 Issue\n\n- 使用 [Issue 模板](https://github.com/Kirky-X/garrison/issues/new/choose)（Bug Report / Feature Request）\n- 描述问题时请提供复现步骤与 Rust 版本\n\n### 提交 PR\n\n1. Fork 本仓库\n2. 创建特性分支：`git checkout -b feat/your-feature`\n3. 遵循 [Conventional Commits](https://conventionalcommits.org/zh-hans/) 规范提交\n4. 确保 `cargo test --features full` + `cargo clippy -- -D warnings` 通过\n5. 创建 Pull Request\n\n### 开发规范\n\n- **TDD 工作流**：先写接口 → 写测试 → 实现 → 测试通过 → commit\n- **clippy**：零警告（`-D warnings`）\n- **文档**：所有 public API 必须有 `///` 文档注释\n- **测试串行化**：修改全局 `GarrisonManager` 单例的测试需标注 `#[serial_test::serial]`\n\n### 测试\n\nGarrison 提供三层测试体系：单元测试（3787+ 个 lib）+ E2E 测试（65+ 个，含 API 矩阵 / 性能基线 / 渗透测试）+ doc-tests。\n\n```bash\n# 单元测试 + 集成测试\ncargo test --features full\n\n# E2E 测试（含 API 矩阵 + 渗透测试，不含 #[ignore] 性能测试）\ncargo test --test e2e --features \"full testing\" -- --nocapture\n\n# 性能基线测试（#[ignore] 默认不跑，需显式触发）\ncargo test --test e2e --features \"full testing\" -- --ignored perf_ --test-threads=1 --nocapture\n\n# 一键执行 E2E + 性能 + 渗透 + 生成综合报告\nbash scripts/e2e_run.sh\n```\n\nE2E 测试覆盖 API 接口矩阵（happy/errors/boundary/authz_boundary）、性能基线（P99\u003c200ms/1000RPS）、渗透测试（7 类攻击 × N payload），所有 HTTP 交互通过 `RecordingClient` 抓包到 `logs/e2e_http.jsonl`，最终由 `scripts/e2e_analyze.py` 聚合生成 `logs/e2e_final_report.md`。详细说明详见 [E2E / 性能 / 渗透测试](./docs/DEVELOPMENT.md#e2e--性能--渗透测试)。\n\n---\n\n## 🗺 路线图\n\n- [x] **v0.1.0**（2026-06-30）核心基础设施：登录认证 + 权限校验 + 双模会话 + axum 集成\n- [x] **v0.2.0**（2026-07-01）协议与安全层：JWT / OAuth2 / SSO / Sign / API Key / TOTP / Basic / Digest + 插件系统 + 事件监听器\n- [x] **v0.2.1**（2026-07-01）auto-wire 修复 + 协议层边界测试 + examples 工程化重组\n- [x] **v0.3.0** 生态完善与可观测：OpenTelemetry OTLP + gRPC 拦截器 + i18n + metrics-prometheus\n- [x] **v0.4.0**（2026-07-02）0.2.0 协议层遗留 gap 补齐：OIDC / ScopeHandler / SsoServer / AloneCache / ParameterQuery（gap #4 注解系统延后至 0.5.0+）\n- [x] **v0.4.2**（2026-07-05）gap closure：dao 扩展 / strategy-registry / jwt-modes / oauth-2-1 / token-introspection / apikey-namespace / sso-toctou / password-login / 注解宏\n- [x] **v0.5.0**（2026-07-06）生产刚需版：多租户 / 社交登录 / 审计日志 / Token Rotation / 安全防护 / 角色层级 / 决策溯源 / Keycloak OIDC RP / PostgreSQL\n- [x] **v0.5.2**（2026-07-08）架构重构：GarrisonLogic trait 拆分为 6 个子 trait + LoginId 迁移到 String\n- [x] **v0.5.3**（2026-07-09）功能补全：oxcache 升级 / stp 完整拆分 / MySQL 后端 / Firewall MaxMindDb\n- [x] **v0.6.0**（2026-07-09）账号安全引擎：account/ 模块 + Credential SPI + PasswordPolicyEngine + AuthenticationFlow DSL + remember-me / Redis 部署模式 / switch_to / SAML 2.0 / OIDC RP / Redis pub/sub SsoChannel\n- [x] **v0.7.0**（2026-07-17）微服务架构 + ABAC/Cedar + OAuth2 Server：backend-remote / Auth Server / ABAC 引擎 / OAuth2 Server 4 端点 + 架构加固 + 依赖优化\n- [x] **v0.7.1**（2026-07-21）安全修复 + 架构加固：21 项安全修复（secure-simple-token、SimpleTokenStyle 防伪造、OIDC aud 数组兼容、switch_to 账户会话清理、session corrupt-json 健壮性等）\n- [x] **v0.7.2**（2026-07-21）跨平台修复 + 安全加固：Windows confers 路径校验修复 + gitleaks 集成 + GarrisonConfig::load 7 项安全防护\n- [x] **v0.7.3**（2026-07-22）宏拓展 + 版本同步：新增 `#[check_disable]` 宏 + garrison-macros 版本同步至 0.7.3 + 新增 `dao_session!` 内部 macro_rules! 宏消除 DAO 层样板代码（53 处调用点，节省 ~350 行） + 文档一致性修复\n- [x] **v0.8.0**（2026-07-24）安全加固 + 发布前审查修复：API Key 安全退化修复（CWE-916 哈希存储 / CWE-307 IP 限速 / IDOR 多租户 / legacy fail-closed）+ jwt_secret 弱密钥拒绝 + 常量时间比较公共原语（secure-ct-eq）+ CSPRNG 统一 OsRng + singleflight 锁清理（CWE-770）+ SQL 占位符状态机 + 发布前审查修复（lost-revoke TOCTOU、ct_eq 统一、update_last_used 对称、sha256_hex 优化、rotate 并发文档化等）\n- [ ] **v1.0.0** 稳定版：API 冻结 + 性能基准 + 生产案例\n\n完整规划见 [docs/ROADMAP.md](./docs/ROADMAP.md)。\n\n---\n\n## 📄 许可证\n\n本项目基于 [Apache-2.0](./LICENSE) 许可证开源。\n\n为何选择 Apache-2.0 而非 MIT：Apache-2.0 包含专利授权条款，更适合企业级框架使用。\n\n---\n\n## 🙏 致谢\n\n- [Sa-Token](https://github.com/dromara/sa-token)：Java 生态的认证鉴权框架，为本项目早期领域建模提供参考\n- [axum](https://github.com/tokio-rs/axum)：tokio 团队出品的 Rust Web 框架\n- [oxcache](https://github.com/Kirky-X/oxcache)：Rust 多级缓存库（L1 内存 + L2 redis）\n- [dbnexus](https://github.com/Kirky-X/dbnexus)：Rust 数据库抽象层（SQLite / PostgreSQL / MySQL）\n- [inventory](https://github.com/dtolnay/inventory)：David Tolnay 的编译期插件注册库\n\n---\n\n\u003cp align=\"center\"\u003e\n  Built with ❤️ by \u003ca href=\"https://github.com/Kirky-X\"\u003eKirky.X\u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkirky-x%2Fgarrison","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkirky-x%2Fgarrison","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkirky-x%2Fgarrison/lists"}