auth-kit

auth-kit 是一个可复用的认证/多租户中间件库（Rust + Axum），用于在多个微服务中统一实现：

• JWT 认证：从 Authorization: Bearer <token> 解析并验证 token，注入 AuthContext
• 租户隔离：从 X-Tenant-ID 解析租户并注入 TenantId，并在同时存在 token 与 header 时强制一致性

该 crate 不包含任何业务逻辑、数据库访问或 RBAC 聚合，仅提供“请求上下文注入 + 类型提取器 + JWT 验证能力”。

依赖与约定

• Web 框架：Axum
• 统一错误类型：common_telemetry::AppError
• 头部约定：
  • Authorization: Bearer <access_token>
  • X-Tenant-ID: <tenant_uuid>

快速开始（在 Axum 中挂载）

推荐链路顺序：

1. authenticate_with_config（注入 AuthContext）
2. resolve_tenant_with_config（注入 TenantId，并校验 header tenant 与 token tenant 一致）

示例：

use axum::{Router, middleware::from_fn_with_state};
use auth_kit::middleware::{
    auth::{self, AuthMiddlewareConfig},
    tenant::{self, TenantMiddlewareConfig},
};

let auth_cfg = AuthMiddlewareConfig {
    skip_exact_paths: vec!["/healthz".to_string()],
    skip_path_prefixes: vec!["/scalar".to_string()],
    jwt: auth_kit::jwt::JwtVerifyConfig::rs256_from_jwks(
        "iam-service",
        "http://127.0.0.1:3000/.well-known/jwks.json",
    )?,
};

let tenant_cfg = TenantMiddlewareConfig {
    skip_exact_paths: vec!["/healthz".to_string()],
    skip_path_prefixes: vec!["/scalar".to_string()],
};

let app = Router::new()
    .layer(from_fn_with_state(tenant_cfg, tenant::resolve_tenant_with_config))
    .layer(from_fn_with_state(auth_cfg, auth::authenticate_with_config));

Handler 中如何使用（类型注入）

AuthContext

AuthContext 会从 request extensions 中提取，如果中间件未运行或缺失认证信息，会返回 AppError::MissingAuthHeader。

use auth_kit::middleware::auth::AuthContext;

pub async fn handler(AuthContext { user_id, tenant_id, .. }: AuthContext) {
    // ...
}

TenantId

TenantId 可从 request extensions 中提取；若不存在，会尝试从 X-Tenant-ID 解析；缺失则返回 AppError::BadRequest("Missing X-Tenant-ID header")。

use auth_kit::middleware::tenant::TenantId;

pub async fn handler(TenantId(tenant_id): TenantId) {
    // ...
}

JWT 验证配置（JwtVerifyConfig）

JwtVerifyConfig 定义在 jwt.rs。

• 静态公钥：rs256_from_pem(issuer, public_key_pem)
• JWKS 拉取：rs256_from_jwks(issuer, jwks_url)（带缓存与降级）
• 对称密钥（调试/兼容）：hs256_from_secret(issuer, secret)

注意点：

• RS256 模式要求 token header 中包含 kid（用于从 JWKS 中选 key）
• issuer 必须与 token 中 iss 一致
• JWKS 目前只支持 RSA + use=sig + alg=RS256

JWKS 缓存策略（当前实现）

• HTTP 超时：1500ms
• 缓存 TTL：300s
• stale-if-error：3600s（JWKS 拉取失败时可在窗口内使用缓存 key 继续验签）

Skip 规则（免鉴权路径）

AuthMiddlewareConfig / TenantMiddlewareConfig 都支持：

• skip_exact_paths：精确路径匹配
• skip_path_prefixes：前缀匹配

用于跳过如 /healthz、/scalar、/.well-known/jwks.json 等公开端点。

端到端验证（推荐）

本库自带一个集成测试，用于验证 RS256 + JWKS 的验签路径：

• 测试文件： jwks_verify.rs
• 运行：

cd /home/shay/project/backend/auth-kit
cargo test

已知限制

• 暂未提供“从环境变量自动组装配置”的辅助函数（建议业务服务自行装配 AuthMiddlewareConfig）
• 暂未实现 ECDSA（ES256）/EdDSA（Ed25519）JWKS 解析