Skip to main content

garrison/
lib.rs

1// Copyright (c) 2026 Kirky.X🌠
2// SPDX-License-Identifier: Apache-2.0
3
4#![doc(html_root_url = "https://docs.rs/garrison/latest")]
5#![allow(rustdoc::invalid_rust_codeblocks)]
6
7//! # Garrison
8//!
9//! Garrison 是一个面向 Rust 生态的一站式身份认证鉴权框架。
10//!
11//! ## 快速开始
12//!
13//! 最小可用示例:初始化管理器 → 登录 → 校验登录状态 → 校验权限 → 登出。
14//! 以下 doctest 随 `cargo test --doc` 持续验证,可直接复制使用;`InMemoryDao` 为进程内实现,
15//! 生产请换 `GarrisonDaoOxcache` / `GarrisonDaoDbnexus` 等持久化后端。
16//!
17//! ```rust
18//! use async_trait::async_trait;
19//! use garrison::prelude::*;
20//! use std::sync::Arc;
21//!
22//! // 1. 业务方实现 GarrisonInterface(提供权限/角色数据)
23//! struct MyInterface;
24//!
25//! #[async_trait]
26//! impl GarrisonInterface for MyInterface {
27//! async fn get_permission_list(&self, _login_id: &str) -> GarrisonResult<Vec<String>> {
28//! Ok(vec!["user:read".into(), "user:write".into()])
29//! }
30//! async fn get_role_list(&self, _login_id: &str) -> GarrisonResult<Vec<String>> {
31//! Ok(vec!["user".into()])
32//! }
33//! }
34//!
35//! # fn main() -> GarrisonResult<()> {
36//! # tokio::runtime::Builder::new_current_thread()
37//! # .enable_all()
38//! # .build()
39//! # .expect("runtime 初始化恒成功")
40//! # .block_on(run())?;
41//! # Ok(())
42//! # }
43//!
44//! # async fn run() -> GarrisonResult<()> {
45//! use garrison::context::tenant::{TenantContext, TenantSource, TENANT};
46//!
47//! // 2. 准备依赖(dao / config / interface)
48//! let dao: Arc<dyn GarrisonDao> = Arc::new(garrison::dao::InMemoryDao::new());
49//! let config = Arc::new(GarrisonConfig::default_config());
50//! let interface: Arc<dyn GarrisonInterface> = Arc::new(MyInterface);
51//!
52//! // 3. 初始化全局管理器
53//! GarrisonManager::builder()
54//! .dao(dao)
55//! .config(config)
56//! .interface(interface)
57//! .build()
58//! .await?;
59//!
60//! // 租户上下文:tenant-isolation feature 启用时必需;单租户部署用 tenant_id=0
61//! let tenant = TenantContext {
62//! tenant_id: 0,
63//! resolved_from: TenantSource::Header,
64//! };
65//!
66//! TENANT.scope(tenant, async {
67//! // 4. 执行登录:生成 token 并写入会话
68//! // 注意:login / check_login 依赖 task_local 上下文中的当前 token,
69//! // 通常由 web 中间件(如 axum middleware)设置。
70//! let token = with_current_token(
71//! String::new(),
72//! GarrisonUtil::login("1001", &LoginParams::default()),
73//! )
74//! .await?;
75//!
76//! // 5. 校验登录状态
77//! with_current_token(token.clone(), async {
78//! assert!(GarrisonUtil::check_login().await?);
79//!
80//! // 6. 读取当前登录主体 / 校验权限
81//! let login_id = GarrisonUtil::get_login_id().await?;
82//! assert_eq!(login_id.as_deref(), Some("1001"));
83//! GarrisonUtil::check_permission("user:read").await?;
84//!
85//! // 7. 登出
86//! GarrisonUtil::logout().await?;
87//! Ok::<(), GarrisonError>(())
88//! })
89//! .await?;
90//! # Ok::<(), GarrisonError>(())
91//! # })
92//! # .await
93//! # }
94//! ```
95//!
96//! ## 特性
97//!
98//! Garrison 通过 Cargo feature flags 控制各能力域的编译:
99//!
100//! | 类别 | Feature | 说明 |
101//! |:---|:---|:---|
102//! | 默认 | `default` | `backend-embedded`(仅启用进程内认证后端;`development` 可一键启用常用组合) |
103//! | 缓存 | `cache-memory` / `cache-redis` | 基于 oxcache 的 L1(内存) + L2(redis),均启用 oxcache(语义别名) |
104//! | 数据库 | `db-sqlite` | 基于 dbnexus + auto-migrate |
105//! | Web 框架 | `web-axum` / `web-actix` / `web-warp` | 路由拦截器与 extractor 适配 |
106//! | 协议层 | `protocol-jwt` / `protocol-oauth2` / `protocol-sso` / `protocol-sign` / `protocol-apikey` / `protocol-temp` / `protocol-qrlogin` | 鉴权协议插件 |
107//! | 安全模块 | `secure-totp` / `secure-sign` / `protocol-httpbasic` / `protocol-httpdigest` | TOTP / 签名 / Basic / Digest |
108//! | 可观测性 | `listener` / `tracing-log` / `metrics-prometheus` | 事件监听 / 日志 / 指标 |
109//! | 聚合 | `full` / `production` / `development` | 一键启用一组特性 |
110//!
111//! ## 模块概览
112//!
113//! - **核心扩展**(always on):[`core::token`](`Token` trait + `TokenStyleFactory`)、[`core::auth`](`AuthLogic` + `DefaultAuthLogic`)、[`core::permission`](`PermissionChecker` + 默认实现)、[`plugin`](编译期插件注册)、[`strategy`](权限策略扩展)、[`session`](SSO / OAuth2 / 临时凭证关联)
114//! - **协议层**(特性门控):jwt(HS256/HS512)/ oauth2(Authorization Code / Client Credentials / Password)/ sso(一次性 60s ticket)/ sign(HMAC-SHA256 + 防重放窗口)/ apikey / temp
115//! - **安全模块**(特性门控):totp(RFC 6238,±1 窗口)/ sign / httpbasic / httpdigest
116//! - **可观测性**:`listener`(`GarrisonEvent` + `Listener`,Login / Logout / PermissionCheck / Kickout 事件)
117//!
118//! ## 特性域
119//!
120//! 100+ feature flag 分域:登录认证 / 权限认证(RBAC + ABAC)/ Session / 协议层(OAuth2 / SSO / JWT /
121//! Sign / API Key / Temp / OIDC / SAML)/ 安全模块(TOTP / 签名 / Basic / Digest / Unicode 检测 / 脱敏 /
122//! XSS / 常量时间比较)/ 账号安全引擎 / Web 适配 / 安全防护套件 / 可观测性 / 服务器层 / 社交与扫码登录 /
123//! 插件化扩展。
124//!
125//! ## 架构
126//!
127//! 双抽象层 + 全局单例:`dbnexus`([`GarrisonDao`] 屏蔽 SQLite / PostgreSQL / MySQL 差异)与 `oxcache`
128//! (L1 内存 + L2 redis,承载 Token-Session 与 Account-Session);[`GarrisonManager`] 持全局
129//! `Arc<GarrisonLogicDefault>`(`arc_swap::ArcSwapOption`,读路径无锁、支持覆盖式重建),启动时经
130//! [`GarrisonManager::builder`] 链式注入 dao / config / interface,`GarrisonLogicFactory` 经 `inventory`
131//! 编译期注册、运行时选取,[`GarrisonUtil`] 静态方法委托全局单例。
132//!
133//! ## 使用示例
134//!
135//! ```toml
136//! [dependencies]
137//! garrison = { version = "0.9", features = ["web-axum", "protocol-jwt"] }
138//! ```
139//!
140//! ```rust
141//! use garrison::prelude::*;
142//!
143//! // 通过 prelude 引入核心类型(LoginParams / GarrisonDaoOxcache /
144//! // Annotation / with_current_token / current_token 均已入 prelude)
145//! let _config: GarrisonConfig = GarrisonConfig::default_config();
146//! ```
147
148#![cfg_attr(docsrs, feature(doc_cfg))]
149#![warn(missing_docs)]
150
151// 核心模块(always on,无 feature flag)
152
153/// 常量定义模块,提供 DAO key 前缀等类型安全枚举。
154pub mod constants;
155
156/// 核心模块,包含认证、权限、Token 的核心抽象。
157pub mod core;
158
159/// Stp 模块,提供 GarrisonLogicDefault / GarrisonInterface / GarrisonUtil + 5 个子 trait。
160pub mod stp;
161
162/// 注解模块,定义鉴权注解枚举。
163pub mod annotation;
164
165/// 路由模块,提供路由器与拦截器抽象。
166pub mod router;
167
168/// DAO 模块,定义持久化数据访问抽象层。
169pub mod dao;
170
171/// limiteron 适配器模块,将 GarrisonDao 桥接到 limiteron Storage/BanStorage/DistributedLimiter trait。
172///
173/// 无条件编译:`GarrisonDaoDistributedLimiter` 是防爆破计数公共基座(invitation 锁定器在任意 feature
174/// 面下均委托它),`limiteron` 为非 optional 依赖;子模块各自门控(ban → `firewall-ddos`,
175/// circuit/fallback → `backend-remote`)。`firewall` / `oauth2-server` 传递启用 `dep:limiteron`,
176/// 防火墙与密码限流统一走 limiteron(禁止手写限流实现)。
177pub mod limiteron;
178
179/// 策略模块,提供鉴权策略与防火墙策略。
180pub mod strategy;
181
182/// 会话模块,提供 GarrisonSession 会话模型。
183pub mod session;
184
185/// 数据合规模块(GDPR / 个保法数据主体权利编排);启用 `data-erasure` 时编译,提供按主体
186/// (login_id / IP)擦除框架管辖内数据的 [`compliance::erasure::DataErasureService`] 与擦除报告,
187/// 数据清单与责任边界见 `docs/DATA_COMPLIANCE.md`。
188#[cfg(feature = "data-erasure")]
189pub mod compliance;
190
191/// 缓存模块,提供三层缓存架构(L1 oxcache 内存 + L2 DAO + L3 interface);启用 `three-tier-cache`
192/// 时编译,提供 [`UserCacheService`] 加速权限 / 角色 / 用户信息查询。
193///
194/// [`UserCacheService`]: crate::cache::three_tier::UserCacheService
195#[cfg(feature = "three-tier-cache")]
196pub mod cache;
197
198/// 状态机模块,提供 [`state::TokenState`](5 状态 + 6 条合法转换)与 [`state::UserStatus`]
199/// (5 状态 + 9 条合法转换);独立于 Session / User 模块,不集成。
200pub mod state;
201
202/// 配置模块,提供 GarrisonConfig 全局配置。
203pub mod config;
204
205/// 健康检查模块,提供 liveness/readiness 探针与依赖项健康检测。
206pub mod health;
207
208/// 单根二进制的 CLI 面(sdforge CliBuilder + inventory 注册 + dispatch):
209/// `healthcheck`(无条件)/ `serve`(auth-server)/ 运维命令组(cli-ops)。
210pub mod cli;
211
212/// 上下文模块,提供请求/响应/存储上下文抽象。
213pub mod context;
214
215/// JSON 模块,提供 JSON 模板与序列化抽象。
216pub mod json;
217
218/// 异常模块,定义框架异常类型。
219pub mod exception;
220
221/// 管理器模块,提供全局管理器单例。
222pub mod manager;
223
224/// 插件模块,定义插件 trait 与编译期注册。
225pub mod plugin;
226
227/// 可观测性模块,提供 Prometheus 指标 / 结构化 JSON 日志 / OpenTelemetry 分布式追踪;对应 feature
228/// (`metrics-prometheus` / `otlp` / `tracing-log`)未启用时模块仍可导入但 API 为 no-op。
229#[cfg(any(
230    feature = "metrics-prometheus",
231    feature = "otlp",
232    feature = "tracing-log"
233))]
234pub mod observability;
235
236/// gRPC 鉴权拦截器模块(`grpc` feature):`tonic::Interceptor` 实现,从 gRPC 请求 metadata
237/// 提取 Authorization Bearer token 并执行鉴权。
238#[cfg(feature = "grpc")]
239pub mod grpc;
240
241/// 国际化模块(fluent-rs):异常消息中英文切换,默认 `Zh`,经 `set_locale(GarrisonLocale::En)`
242/// 切至英文。
243pub mod i18n;
244
245/// 声明式 JSON 测试套件模块(`garrison-testing` feature):提供 [`JsonTestSuite`] / [`JsonTestCase`] /
246/// [`TestReport`],从 JSON 文件加载用例并运行 [`Authorizer`] trait(依赖 `authorize-api`)。
247///
248/// [`JsonTestSuite`]: crate::testing::JsonTestSuite
249/// [`JsonTestCase`]: crate::testing::JsonTestCase
250/// [`TestReport`]: crate::testing::TestReport
251/// [`Authorizer`]: crate::core::permission::Authorizer
252/// [`AuthRequest`]: crate::core::permission::AuthRequest
253/// [`Decision`]: crate::core::permission::Decision
254#[cfg(feature = "garrison-testing")]
255pub mod testing;
256
257/// actix-web 框架适配模块(`web-actix` feature):GarrisonRouter + FromRequest extractor +
258/// GarrisonMiddleware 完整集成,与 axum 适配对齐。
259#[cfg(feature = "web-actix")]
260pub mod web_actix;
261
262/// warp 框架适配模块(`web-warp` feature):GarrisonRouter + Filter extractor + GarrisonRejection
263/// 完整集成,与 axum/actix-web 适配对齐。
264#[cfg(feature = "web-warp")]
265pub mod web_warp;
266
267/// Web 安全中间件模块,提供 WAF / CORS / CSRF / 安全响应头等能力;子模块独立 feature-gated:
268/// `web-cors`(CORS)/ `web-csrf`(CSRF)/ `web-security-headers`(HTTP 安全响应头)/ `web-axum`(X-Request-ID)。
269#[cfg(any(
270    feature = "web-axum",
271    feature = "firewall-waf",
272    feature = "web-cors",
273    feature = "web-csrf",
274    feature = "web-security-headers",
275    feature = "firewall-waf"
276))]
277pub mod web;
278
279// 可选模块(特性门控)
280
281/// 监听器模块,提供事件监听抽象。
282#[cfg(feature = "listener")]
283pub mod listener;
284
285/// Credit 计量模块(多租户配额消费统计、告警、周期重置)。
286#[cfg(feature = "credit-metering")]
287pub mod credit;
288
289/// 安全模块,提供 TOTP / 签名 / Basic / Digest / Unicode 同形异义字检测 / 敏感数据脱敏 验证。
290#[cfg(any(
291    feature = "secure-totp",
292    feature = "secure-sign",
293    feature = "protocol-httpbasic",
294    feature = "protocol-httpdigest",
295    feature = "secure-confusable",
296    feature = "secure-masking",
297    feature = "secure-xss",
298    feature = "secure-sanitize",
299    feature = "secure-ct-eq",
300    feature = "sms-rate-limit",
301    feature = "email-verification",
302    feature = "field-encryption",
303))]
304pub mod secure;
305
306/// 账号安全引擎模块:凭证模型 SPI / 密码策略套件 / 用户级双态锁定 / AuthenticationFlow DSL
307/// (分别经 `account-credential` / `account-policy` / `account-lockout` / `account-authflow` 门控);
308/// 与 `secure/`(密码学原语)互补,提供账号生命周期安全能力。
309pub mod account;
310
311/// 协议层模块,包含各协议插件子模块;重依赖子模块(oauth2/sso/jwt/sign/apikey/temp)在
312/// `protocol/mod.rs` 内自行按 feature 门控,`protocol::social`(扩展点契约类型)无 feature 依赖,始终编译。
313pub mod protocol;
314
315/// 认证后端抽象模块(`backend-embedded` / `backend-remote` 任一):`AuthBackend` trait +
316/// `BackendEmbedded`(进程内认证,委托 GarrisonManager)或 `BackendRemote`(HTTP 客户端连远程 Auth Server)。
317#[cfg(any(feature = "backend-embedded", feature = "backend-remote"))]
318pub mod backend;
319
320/// ABAC 策略引擎模块(`abac` feature,依赖 `cedar-policy`):`AbacEngine` 基于 Cedar 策略语言。
321///
322/// feature 关闭时提供 `check_abac_with_policy` fail-closed stub(无 abac attr:no-op allow;
323/// 有 abac attr 但 feature 关闭:`Err(Config)`),保证宏 `#[check_permission(permission = "...", abac = "...")]`
324/// 生成的代码在任意 feature 组合下均可编译。ABAC 是 RBAC 的增量校验层:RBAC 通过后再检查,不替换 RBAC。
325pub mod abac;
326
327/// Auth Server 模块(`auth-server` feature):双端口 axum 服务器,外网端口 login / logout / refresh
328/// (面向用户),内网端口 check-* / get-* / kickout 等(服务间调用,需 X-API-Key)。
329#[cfg(feature = "auth-server")]
330pub mod server;
331
332/// OAuth2 Server 模块(`oauth2-server` feature):授权服务器(AS)实现,4 端点 + 4 种 grant type +
333/// PKCE;与 `protocol::oauth2`(OAuth2 客户端 / RP 角色,向外部 AS 请求 token)互补。
334#[cfg(feature = "oauth2-server")]
335pub mod oauth2_server;
336
337// 公共入口
338
339/// 预导出模块,包含最常用的类型与 trait。
340pub mod prelude;
341
342/// 错误类型定义模块。
343pub mod error;
344
345pub use prelude::*;
346
347// 多租户隔离类型 re-export
348
349/// 多租户上下文类型与解析器。
350pub use context::tenant::{
351    HeaderTenantResolver, SubdomainTenantResolver, TenantContext, TenantResolver, TenantSource,
352    TENANT,
353};
354
355/// JWT claim 租户解析器(需 `protocol-jwt` feature)。
356#[cfg(feature = "protocol-jwt")]
357pub use context::tenant::ClaimTenantResolver;
358
359/// 登录主体(携带 login_id,由 web 框架 extractor 填充)。
360pub use context::GarrisonPrincipal;
361
362// 状态机类型 re-export
363// `Mode`(AnnotationMode)位于 annotation 模块而非 state,故此处仅 re-export 两个状态类型。
364
365/// Token 生命周期状态(Issued / Active / Expired / Revoked / Refreshed)。
366pub use state::TokenState;
367
368/// 用户账号状态(Pending / Active / Suspended / Inactive / Deleted)。
369pub use state::UserStatus;
370
371// 角色层级
372
373/// 角色层级表行结构(child_role → parent_role + tenant_id)。
374pub use dao::repository::role_hierarchy::RoleHierarchyRecord;
375
376/// 角色层级服务(TC 预计算 + 缓存 + 增量失效,需任一 db 后端 feature)。
377#[cfg(any(feature = "db-sqlite", feature = "db-postgres", feature = "db-mysql"))]
378pub use dao::repository::role_hierarchy::RoleHierarchyService;
379
380// Dbnexus Repository re-export
381
382/// 用户表 Repository(app_user)。
383#[cfg(any(feature = "db-sqlite", feature = "db-postgres", feature = "db-mysql"))]
384pub use dao::repository::sqlite::DbnexusUserRepository;
385
386/// 角色表 Repository(app_role)。
387#[cfg(any(feature = "db-sqlite", feature = "db-postgres", feature = "db-mysql"))]
388pub use dao::repository::sqlite::DbnexusRoleRepository;
389
390/// 权限表 Repository(app_permission,全局表无 tenant_id)。
391#[cfg(any(feature = "db-sqlite", feature = "db-postgres", feature = "db-mysql"))]
392pub use dao::repository::sqlite::DbnexusPermissionRepository;
393
394/// 用户-角色关联表 Repository(app_user_role)。
395#[cfg(any(feature = "db-sqlite", feature = "db-postgres", feature = "db-mysql"))]
396pub use dao::repository::sqlite::DbnexusUserRoleRepository;
397
398/// 角色-权限关联表 Repository(app_role_permission)。
399#[cfg(any(feature = "db-sqlite", feature = "db-postgres", feature = "db-mysql"))]
400pub use dao::repository::sqlite::DbnexusRolePermissionRepository;
401
402/// 认证方式表 Repository(app_auth_method)。
403#[cfg(any(feature = "db-sqlite", feature = "db-postgres", feature = "db-mysql"))]
404pub use dao::repository::sqlite::DbnexusAuthMethodRepository;
405
406/// 会话表 Repository(app_session)。
407#[cfg(any(feature = "db-sqlite", feature = "db-postgres", feature = "db-mysql"))]
408pub use dao::repository::sqlite::DbnexusSessionRepository;
409
410/// 登录日志表 Repository(app_login_log)。
411#[cfg(any(feature = "db-sqlite", feature = "db-postgres", feature = "db-mysql"))]
412pub use dao::repository::sqlite::DbnexusLoginLogRepository;
413
414/// 用户扩展信息表 Repository(app_user_ext)。
415#[cfg(any(feature = "db-sqlite", feature = "db-postgres", feature = "db-mysql"))]
416pub use dao::repository::sqlite::DbnexusUserExtRepository;
417
418// 事件派发事务绑定(OnCommit 语义)
419// `DispatchOutcome` 不入根 re-export,经 `garrison::listener::DispatchOutcome` 访问(同 `GarrisonEvent` 策略)。
420
421/// 事件派发事务 guard(OnCommit 语义:数据库事务 commit 成功后才按 FIFO 派发缓冲事件;rollback/丢弃 guard 时事件不派发)。
422#[cfg(all(
423    feature = "listener",
424    any(feature = "db-sqlite", feature = "db-postgres", feature = "db-mysql")
425))]
426pub use dao::GarrisonEventTx;
427
428// JWT RefreshToken Rotation
429
430/// RefreshToken 表行结构(hash chain:token_hash + parent_token_hash)。
431#[cfg(feature = "protocol-jwt")]
432pub use protocol::jwt::refresh::RefreshTokenRecord;
433
434/// Refresh token 重用三级分类(RecentPrev / OrphanedBranch / StaleLineage)。
435#[cfg(feature = "protocol-jwt")]
436pub use protocol::jwt::refresh::RefreshTokenReuseSubtype;
437
438/// RefreshToken Rotation 服务(rotate + detect_reuse + revoke_chain,需 `protocol-jwt` + `db-sqlite`)。
439#[cfg(all(feature = "protocol-jwt", feature = "db-sqlite"))]
440pub use protocol::jwt::refresh::RefreshTokenRotation;
441
442// 审计日志
443
444/// 审计日志配置(掩码字段 + 保留天数 + 异步写入开关)。
445#[cfg(feature = "audit-log")]
446pub use listener::audit::AuditConfig;
447
448/// `audit_logs` 表行结构(tenant_id / event_type / login_id / metadata / success / created_at)。
449#[cfg(all(feature = "audit-log", feature = "db-sqlite"))]
450pub use listener::audit::AuditEntry;
451
452/// 审计日志查询条件(tenant_id / event_type / from / to,全 Option 复合过滤)。
453#[cfg(all(feature = "audit-log", feature = "db-sqlite"))]
454pub use listener::audit::AuditQuery;
455
456/// 审计日志监听器(实现 `GarrisonListener`,持久化 `GarrisonEvent` 到 `audit_logs` 表)。
457#[cfg(all(feature = "audit-log", feature = "db-sqlite"))]
458pub use listener::audit::AuditLogListener;
459
460/// 审计事件防篡改 HMAC 链(吸收自 inklog `ArchiveChain`;随机盐链首,
461/// 任一事件篡改/删除/重排/伪造即校验失败)。
462#[cfg(feature = "audit-log")]
463pub use listener::audit_chain::{AuditChainEntry, AuditEventChain};
464
465// 社交登录
466
467/// 社交登录服务提供方 trait(get_authorization_url / exchange_token / get_user_info)。
468pub use protocol::social::SocialLoginProvider;
469
470/// 社交用户信息(provider + provider_user_id + union_id + raw JSON)。
471pub use protocol::social::SocialUserInfo;
472
473/// 内置社交登录平台名称常量模块(WECHAT / ALIPAY / WECHAT_MINI_APP);外部 crate 自定义
474/// provider 应使用自己的常量(如 `pub const HUAWEI: &str = "huawei"`),避免与内置 provider 冲突。
475pub use protocol::social::provider_names;
476
477/// 社交登录注册中心(register / unregister / get / list + 委托调用 + SocialProviderResolver 实现);
478/// 允许外部 crate 注册自定义 `SocialLoginProvider` 实现(如华为 Account Kit),扩展点契约类型
479/// 无 feature 门控,内置 provider 实现(`WechatProvider` / `AlipayProvider`)仍需对应 feature。
480pub use protocol::social::registry::SocialLoginService;
481
482/// 微信扫码登录 provider(需 `social-wechat` feature)。
483#[cfg(feature = "social-wechat")]
484pub use protocol::social::wechat::WechatProvider;
485
486/// 微信小程序登录 provider(需 `social-wechat` feature)。
487#[cfg(feature = "social-wechat")]
488pub use protocol::social::wechat::WechatMiniAppProvider;
489
490/// 支付宝授权登录 provider(需 `social-alipay` feature)。
491#[cfg(feature = "social-alipay")]
492pub use protocol::social::alipay::AlipayProvider;
493
494/// 社交账号绑定服务(find_or_create,需 `db-sqlite`/`db-postgres`/`db-mysql` 任一 +
495/// `social-wechat`/`social-alipay` 任一 feature)。
496#[cfg(all(
497    any(feature = "db-sqlite", feature = "db-postgres", feature = "db-mysql"),
498    any(feature = "social-wechat", feature = "social-alipay")
499))]
500pub use protocol::social::SocialBindingService;
501
502// Keycloak OIDC RP
503
504/// Keycloak OIDC RP 配置(base_url / client_id / client_secret / redirect_uri)。
505#[cfg(feature = "keycloak-oidc")]
506pub use protocol::oauth2::keycloak::KeycloakConfig;
507
508/// Keycloak OIDC 依赖方(discover / verify_id_token / exchange_code)。
509#[cfg(feature = "keycloak-oidc")]
510pub use protocol::oauth2::keycloak::KeycloakProvider;
511
512/// Keycloak id_token 的 claims(sub / exp / realm_access / resource_access / tenant_id)。
513#[cfg(feature = "keycloak-oidc")]
514pub use protocol::oauth2::keycloak::KeycloakClaims;
515
516/// Keycloak token endpoint 响应(access_token / refresh_token / id_token / expires_in)。
517#[cfg(feature = "keycloak-oidc")]
518pub use protocol::oauth2::keycloak::KeycloakTokenSet;
519
520/// Keycloak realm 访问信息(roles 列表)。
521#[cfg(feature = "keycloak-oidc")]
522pub use protocol::oauth2::keycloak::RealmAccess;
523
524// 安全防护套件
525
526/// 防火墙策略 trait(IP 级安全检查契约)。
527#[cfg(feature = "firewall")]
528pub use strategy::firewall::GarrisonFirewallStrategy;
529
530/// 防火墙上下文(IP / login_id / tenant_id)。
531#[cfg(feature = "firewall")]
532pub use strategy::firewall::FirewallContext;
533
534/// 防火墙策略注册条目(inventory 收集,仅含 name)。
535#[cfg(feature = "firewall")]
536pub use strategy::firewall::StrategyRegistration;
537
538/// 暴力破解防护策略 + 配置。
539#[cfg(feature = "firewall-bruteforce")]
540pub use strategy::firewall::{BruteForceConfig, BruteForceStrategy};
541
542/// 速率限制策略 + 配置 + 作用域枚举。
543#[cfg(feature = "firewall-ratelimit")]
544pub use strategy::firewall::{RateLimitConfig, RateLimitScope, RateLimitStrategy};
545
546/// 异地登录检测策略 + 配置。
547#[cfg(feature = "firewall-anomalous")]
548pub use strategy::firewall::{AnomalousConfig, AnomalousLoginStrategy};
549
550/// DDoS 防护策略 + 配置。
551#[cfg(feature = "firewall-ddos")]
552pub use strategy::firewall::{DDoSConfig, DDoSStrategy};
553
554/// GeoIP 地理位置拦截策略 + 配置。
555#[cfg(feature = "firewall-geoip")]
556pub use strategy::firewall::{GeoIPConfig, GeoIPStrategy};
557
558/// 地理坐标 + GeoLookup / CountryLookup trait(anomalous / geoip 共享)。
559#[cfg(any(feature = "firewall-anomalous", feature = "firewall-geoip"))]
560pub use strategy::firewall::{CountryLookup, GeoCoord, GeoLookup};
561
562// 过程宏注解
563
564/// 过程宏注解模块(`annotation-macros` feature):re-export `garrison-macros` 的
565/// `#[proc_macro_attribute]` 宏(check_login / check_permission / check_role / check_access_token /
566/// check_client_token / check_temp_token / check_api_key / check_mfa / check_abac / check_disable 等)。
567/// 宏将 async fn 包装为 wrapper,在 body 前插入 `GarrisonUtil::check_*()` 调用,
568/// 失败时返回 `axum::response::Response`(401/403)。
569///
570/// # 示例
571///
572/// ```ignore
573/// use garrison::check_login;
574/// use axum::response::IntoResponse;
575///
576/// #[check_login]
577/// async fn handler() -> impl IntoResponse {
578/// "hello"
579/// }
580/// ```
581#[cfg(feature = "annotation-macros")]
582pub use garrison_macros::{
583    check_abac, check_access_token, check_api_key, check_client_token, check_disable, check_login,
584    check_login_forge, check_mfa, check_permission, check_permission_forge, check_role,
585    check_role_forge, check_temp_token,
586};
587
588// MSRV 元数据守卫(仅测试)
589
590/// `rust-version` 单一事实源守卫:该字段是发布契约,仓库内四处编码同一数值,任一处漂移即
591/// 复现「声明 1.85、依赖面需 1.97.1」型矛盾——cargo 以 `rustc ... is not supported by the
592/// following packages` 拒绝低于依赖面要求的工具链,故声明值必须是依赖图可满足的最低工具链:
593/// 根清单 `[package]` / `[workspace.package]`(macros、examples 经前者继承)、`clippy.toml`
594/// 的 `msrv`(lint 据此判定 API 可用性)、CI 测试矩阵的 MSRV 腿及其门控步骤(以声明值编译
595/// 锁定依赖图,是声明与依赖面一致性的实测门禁)、README 双语徽章(用户侧口径)。
596#[cfg(test)]
597mod msrv_guard {
598    /// 按路径取 TOML 字符串值(缺键返回 `None`,由调用方给出可读失败信息)。
599    fn toml_str<'a>(value: &'a toml::Value, path: &[&str]) -> Option<&'a str> {
600        let mut cur = value;
601        for key in path {
602            cur = cur.get(*key)?;
603        }
604        cur.as_str()
605    }
606
607    fn cargo_toml() -> toml::Value {
608        toml::from_str(include_str!("../Cargo.toml")).expect("根 Cargo.toml 应为合法 TOML")
609    }
610
611    fn declared_msrv() -> String {
612        toml_str(&cargo_toml(), &["package", "rust-version"])
613            .expect("根 Cargo.toml 的 [package] 应声明 rust-version")
614            .to_string()
615    }
616
617    /// 枚举 `text` 中全部「`prefix` 之后到下一处 `delimiter`」片段,用于比对同一标记的多处取值。
618    fn extract_values<'a>(text: &'a str, prefix: &str, delimiter: &str) -> Vec<&'a str> {
619        let mut out = Vec::new();
620        let mut rest = text;
621        while let Some(idx) = rest.find(prefix) {
622            let tail = &rest[idx + prefix.len()..];
623            let Some(end) = tail.find(delimiter) else {
624                break;
625            };
626            out.push(&tail[..end]);
627            rest = &tail[end..];
628        }
629        out
630    }
631
632    #[test]
633    fn msrv_single_source_of_truth_manifest_and_clippy() {
634        let msrv = declared_msrv();
635        assert_eq!(
636            toml_str(&cargo_toml(), &["workspace", "package", "rust-version"]),
637            Some(msrv.as_str()),
638            "[workspace.package].rust-version 必须与 [package].rust-version 一致(macros/examples 经此继承)"
639        );
640        let clippy: toml::Value =
641            toml::from_str(include_str!("../clippy.toml")).expect("clippy.toml 应为合法 TOML");
642        assert_eq!(
643            toml_str(&clippy, &["msrv"]),
644            Some(msrv.as_str()),
645            "clippy.toml 的 msrv 必须与 Cargo.toml 的 rust-version 一致,否则 lint 按错误 MSRV 判定 API 可用性"
646        );
647    }
648
649    #[test]
650    fn msrv_single_source_of_truth_ci_and_badge() {
651        let msrv = declared_msrv();
652        let ci = include_str!("../.github/workflows/ci.yml");
653        let matrix = format!("rust: [{msrv}, stable, beta]");
654        assert!(
655            ci.contains(&matrix),
656            "ci.yml 测试矩阵的 MSRV 腿未钉在声明值(期望 `{matrix}`):该腿以声明值编译锁定依赖图,声明与依赖面不一致时先在此暴露"
657        );
658        // 门控步骤(Linux 独占的 run 维度补齐)必须整体切到声明值:只改矩阵行会留下旧值门控
659        let gates = extract_values(ci, "matrix.rust == '", "'");
660        assert!(
661            !gates.is_empty(),
662            "ci.yml 未找到 MSRV 腿门控步骤(`matrix.rust == '<版本>'`)"
663        );
664        let stale: Vec<&str> = gates.iter().copied().filter(|v| *v != msrv).collect();
665        assert!(
666            stale.is_empty(),
667            "ci.yml 的 MSRV 腿门控步骤仍钉在旧值 {stale:?}(声明值为 {msrv})"
668        );
669        for (name, text) in [
670            ("README.md", include_str!("../README.md")),
671            ("README_EN.md", include_str!("../README_EN.md")),
672        ] {
673            let badges = extract_values(text, "badge/rust-", "%2B");
674            assert_eq!(
675                badges,
676                vec![msrv.as_str()],
677                "{name} 的 Rust 徽章必须唯一且等于 Cargo.toml 的 rust-version(实际 {badges:?},声明值 {msrv})"
678            );
679        }
680    }
681}