feat: add platform auth jwt adapter
This commit is contained in:
10
server-rs/crates/platform-auth/Cargo.toml
Normal file
10
server-rs/crates/platform-auth/Cargo.toml
Normal file
@@ -0,0 +1,10 @@
|
||||
[package]
|
||||
name = "platform-auth"
|
||||
edition.workspace = true
|
||||
version.workspace = true
|
||||
license.workspace = true
|
||||
|
||||
[dependencies]
|
||||
jsonwebtoken = "9"
|
||||
serde = { version = "1", features = ["derive"] }
|
||||
time = { version = "0.3", features = ["std"] }
|
||||
@@ -1,34 +1,71 @@
|
||||
# platform-auth 平台适配 crate 占位说明
|
||||
# platform-auth 鉴权平台适配 crate 说明
|
||||
|
||||
日期：`2026-04-20`
|
||||
日期：`2026-04-21`
|
||||
|
||||
## 1. crate 职责
|
||||
|
||||
`platform-auth` 是鉴权平台适配 crate，后续负责：
|
||||
`platform-auth` 是 Rust 工作区中的鉴权平台适配 crate，当前与后续负责：
|
||||
|
||||
1. JWT 签发与校验适配
|
||||
2. refresh cookie 读写与轮换适配
|
||||
3. 手机验证码发送与校验适配
|
||||
4. 微信 OAuth 相关平台适配
|
||||
5. 供 `module-auth` 与 `crates/api-server` 复用的鉴权基础设施能力
|
||||
1. Access token JWT 的 claims 结构、签发与校验适配。
|
||||
2. refresh cookie 的读写、签名与轮换适配。
|
||||
3. 手机验证码发送、校验与外部 provider 适配。
|
||||
4. 微信 OAuth start / callback 的平台调用适配。
|
||||
5. 供 `module-auth` 与 `crates/api-server` 复用的鉴权基础设施能力。
|
||||
|
||||
## 2. 当前阶段说明
|
||||
## 2. 当前阶段已落地内容
|
||||
|
||||
当前提交仅完成目录占位，不提前进入 JWT、Cookie、短信与微信平台实现。
|
||||
本阶段已经完成 JWT 基础能力首版落地：
|
||||
|
||||
后续与本 crate 直接相关的任务包括：
|
||||
1. 新增 `JwtConfig`，统一管理 `issuer`、`secret` 与 access token TTL。
|
||||
2. 新增 `AccessTokenClaimsInput` 与 `AccessTokenClaims`，把文档中冻结的 `iss/sub/sid/provider/roles/ver/phone_verified/binding_status/display_name` 映射到 Rust 结构。
|
||||
3. 新增 `sign_access_token(...)`，按 `HS256` 签发 access token。
|
||||
4. 新增 `verify_access_token(...)`，统一校验 `iss/sub/exp/iat` 与 JWT 签名。
|
||||
5. 增加单元测试，覆盖基本签发/校验、issuer 不匹配与空角色拒绝。
|
||||
|
||||
1. 落地 JWT claims、签发与校验适配
|
||||
2. 落地 refresh cookie 读取、写入与轮换适配
|
||||
3. 落地短信发送、校验与风控适配
|
||||
4. 落地微信 OAuth start / callback 适配
|
||||
当前阶段仍未进入：
|
||||
|
||||
当前优先冻结依据：
|
||||
1. refresh cookie 读写与轮换。
|
||||
2. 短信 provider 适配。
|
||||
3. 微信 OAuth 适配。
|
||||
4. `module-auth` 领域规则与数据库真相读取。
|
||||
|
||||
1. [../../../docs/technical/OIDC_JWT_CLAIMS_DESIGN_2026-04-21.md](../../../docs/technical/OIDC_JWT_CLAIMS_DESIGN_2026-04-21.md)
|
||||
## 3. 本阶段 API
|
||||
|
||||
## 3. 边界约束
|
||||
当前开放给工作区其它 crate 的最小 API：
|
||||
|
||||
1. `JwtConfig::new(...)`
|
||||
2. `AccessTokenClaims::from_input(...)`
|
||||
3. `sign_access_token(...)`
|
||||
4. `verify_access_token(...)`
|
||||
5. `AuthProvider`
|
||||
6. `BindingStatus`
|
||||
|
||||
## 4. 配置口径
|
||||
|
||||
当前 `api-server` 接入时采用以下环境变量口径：
|
||||
|
||||
1. `GENARRATIVE_JWT_ISSUER`
|
||||
默认值：`https://auth.genarrative.local`
|
||||
2. `GENARRATIVE_JWT_SECRET`
|
||||
默认值：`genarrative-dev-secret`
|
||||
3. `GENARRATIVE_JWT_ACCESS_TOKEN_TTL_SECONDS`
|
||||
默认值：`7200`
|
||||
4. 兼容读取旧变量：`JWT_ISSUER`、`JWT_SECRET`、`JWT_EXPIRES_IN`
|
||||
|
||||
说明：
|
||||
|
||||
1. `JWT_EXPIRES_IN` 当前兼容 `2h`、`30m`、`900` 这类简单时长格式。
|
||||
2. 当前阶段保持 `HS256`，优先保证与旧 Node 方案迁移平滑。
|
||||
|
||||
## 5. 边界约束
|
||||
|
||||
1. `platform-auth` 只承接平台适配，不承接 `module-auth` 的业务规则和状态真相。
|
||||
2. 鉴权状态最终由 `module-auth` 与 `crates/spacetime-module` 管理，前端接口由 `crates/api-server` 暴露。
|
||||
3. 不允许把短信、微信、Cookie、JWT 等外部细节重新散落到多个业务模块中各自实现。
|
||||
2. `sub` 必须是稳定 `user_id`，`sid` 必须是会话 ID，不能退化为一次 token 的随机 ID。
|
||||
3. 不允许把手机号、openid、refresh token hash、风控状态等敏感或高频变化字段塞进 JWT。
|
||||
4. 鉴权状态最终由 `module-auth` 与 `crates/spacetime-module` 管理，前端接口由 `crates/api-server` 暴露。
|
||||
5. 不允许把短信、微信、Cookie、JWT 等外部细节重新散落到多个业务模块中各自实现。
|
||||
|
||||
## 6. 关联文档
|
||||
|
||||
1. [../../../docs/technical/OIDC_JWT_CLAIMS_DESIGN_2026-04-21.md](../../../docs/technical/OIDC_JWT_CLAIMS_DESIGN_2026-04-21.md)
|
||||
2. [../../../docs/technical/PLATFORM_AUTH_JWT_ADAPTER_DESIGN_2026-04-21.md](../../../docs/technical/PLATFORM_AUTH_JWT_ADAPTER_DESIGN_2026-04-21.md)
|
||||
|
||||
377
server-rs/crates/platform-auth/src/lib.rs
Normal file
377
server-rs/crates/platform-auth/src/lib.rs
Normal file
@@ -0,0 +1,377 @@
|
||||
use std::{collections::HashSet, error::Error, fmt};
|
||||
|
||||
use jsonwebtoken::{
|
||||
Algorithm, DecodingKey, EncodingKey, Header, Validation, decode, encode, errors::ErrorKind,
|
||||
};
|
||||
use serde::{Deserialize, Serialize};
|
||||
use time::{Duration, OffsetDateTime};
|
||||
|
||||
pub const ACCESS_TOKEN_ALGORITHM: Algorithm = Algorithm::HS256;
|
||||
pub const DEFAULT_ACCESS_TOKEN_TTL_SECONDS: u64 = 2 * 60 * 60;
|
||||
|
||||
// 鉴权 provider 直接冻结成文档中约定的枚举，避免后续在多个 crate 内重复发明字符串字面量。
|
||||
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "snake_case")]
|
||||
pub enum AuthProvider {
|
||||
Password,
|
||||
Phone,
|
||||
Wechat,
|
||||
}
|
||||
|
||||
// 绑定状态只保留当前 JWT 需要透传的最小快照，不把完整账号状态枚举直接泄漏到 token 中。
|
||||
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
|
||||
#[serde(rename_all = "snake_case")]
|
||||
pub enum BindingStatus {
|
||||
Active,
|
||||
PendingBindPhone,
|
||||
}
|
||||
|
||||
// 用于签发 access token 的领域输入，和最终 JWT claims 解耦，避免业务层手动拼 iat/exp/iss。
|
||||
#[derive(Clone, Debug, PartialEq, Eq)]
|
||||
pub struct AccessTokenClaimsInput {
|
||||
pub user_id: String,
|
||||
pub session_id: String,
|
||||
pub provider: AuthProvider,
|
||||
pub roles: Vec<String>,
|
||||
pub token_version: u64,
|
||||
pub phone_verified: bool,
|
||||
pub binding_status: BindingStatus,
|
||||
pub display_name: Option<String>,
|
||||
}
|
||||
|
||||
// 直接映射最终 JWT payload，字段名与文档冻结口径保持一致。
|
||||
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
|
||||
pub struct AccessTokenClaims {
|
||||
pub iss: String,
|
||||
pub sub: String,
|
||||
pub sid: String,
|
||||
pub provider: AuthProvider,
|
||||
pub roles: Vec<String>,
|
||||
pub ver: u64,
|
||||
pub phone_verified: bool,
|
||||
pub binding_status: BindingStatus,
|
||||
#[serde(skip_serializing_if = "Option::is_none")]
|
||||
pub display_name: Option<String>,
|
||||
pub iat: u64,
|
||||
pub exp: u64,
|
||||
}
|
||||
|
||||
// 统一承载 JWT 配置，避免 secret、issuer、ttl 在 api-server 与后续模块里散落。
|
||||
#[derive(Clone, Debug, PartialEq, Eq)]
|
||||
pub struct JwtConfig {
|
||||
issuer: String,
|
||||
secret: String,
|
||||
access_token_ttl_seconds: u64,
|
||||
}
|
||||
|
||||
#[derive(Debug, PartialEq, Eq)]
|
||||
pub enum JwtError {
|
||||
InvalidConfig(&'static str),
|
||||
InvalidClaims(&'static str),
|
||||
SignFailed(String),
|
||||
VerifyFailed(String),
|
||||
}
|
||||
|
||||
impl JwtConfig {
|
||||
pub fn new(
|
||||
issuer: String,
|
||||
secret: String,
|
||||
access_token_ttl_seconds: u64,
|
||||
) -> Result<Self, JwtError> {
|
||||
let issuer = issuer.trim().to_string();
|
||||
let secret = secret.trim().to_string();
|
||||
|
||||
if issuer.is_empty() {
|
||||
return Err(JwtError::InvalidConfig("JWT issuer 不能为空"));
|
||||
}
|
||||
|
||||
if secret.is_empty() {
|
||||
return Err(JwtError::InvalidConfig("JWT secret 不能为空"));
|
||||
}
|
||||
|
||||
if access_token_ttl_seconds == 0 {
|
||||
return Err(JwtError::InvalidConfig(
|
||||
"JWT access token 过期时间必须大于 0",
|
||||
));
|
||||
}
|
||||
|
||||
Ok(Self {
|
||||
issuer,
|
||||
secret,
|
||||
access_token_ttl_seconds,
|
||||
})
|
||||
}
|
||||
|
||||
pub fn issuer(&self) -> &str {
|
||||
&self.issuer
|
||||
}
|
||||
|
||||
pub fn access_token_ttl_seconds(&self) -> u64 {
|
||||
self.access_token_ttl_seconds
|
||||
}
|
||||
}
|
||||
|
||||
impl AccessTokenClaims {
|
||||
pub fn from_input(
|
||||
input: AccessTokenClaimsInput,
|
||||
config: &JwtConfig,
|
||||
issued_at: OffsetDateTime,
|
||||
) -> Result<Self, JwtError> {
|
||||
let user_id = normalize_required_field(input.user_id, "JWT sub 不能为空")?;
|
||||
let session_id = normalize_required_field(input.session_id, "JWT sid 不能为空")?;
|
||||
let roles = normalize_roles(input.roles)?;
|
||||
let display_name = normalize_optional_field(input.display_name);
|
||||
|
||||
let issued_at_unix = issued_at.unix_timestamp();
|
||||
if issued_at_unix < 0 {
|
||||
return Err(JwtError::InvalidClaims("JWT iat 不能早于 Unix epoch"));
|
||||
}
|
||||
|
||||
let expires_at = issued_at
|
||||
.checked_add(Duration::seconds(
|
||||
i64::try_from(config.access_token_ttl_seconds()).map_err(|_| {
|
||||
JwtError::InvalidConfig("JWT access token 过期时间超出 i64 上限")
|
||||
})?,
|
||||
))
|
||||
.ok_or(JwtError::InvalidConfig("JWT 过期时间计算溢出"))?;
|
||||
|
||||
let expires_at_unix = expires_at.unix_timestamp();
|
||||
if expires_at_unix <= issued_at_unix {
|
||||
return Err(JwtError::InvalidClaims("JWT exp 必须晚于 iat"));
|
||||
}
|
||||
|
||||
let claims = Self {
|
||||
iss: config.issuer().to_string(),
|
||||
sub: user_id,
|
||||
sid: session_id,
|
||||
provider: input.provider,
|
||||
roles,
|
||||
ver: input.token_version,
|
||||
phone_verified: input.phone_verified,
|
||||
binding_status: input.binding_status,
|
||||
display_name,
|
||||
iat: issued_at_unix as u64,
|
||||
exp: expires_at_unix as u64,
|
||||
};
|
||||
|
||||
claims.validate_for_config(config)?;
|
||||
Ok(claims)
|
||||
}
|
||||
|
||||
pub fn user_id(&self) -> &str {
|
||||
&self.sub
|
||||
}
|
||||
|
||||
pub fn session_id(&self) -> &str {
|
||||
&self.sid
|
||||
}
|
||||
|
||||
pub fn token_version(&self) -> u64 {
|
||||
self.ver
|
||||
}
|
||||
|
||||
pub fn validate_for_config(&self, config: &JwtConfig) -> Result<(), JwtError> {
|
||||
if self.iss.trim() != config.issuer() {
|
||||
return Err(JwtError::InvalidClaims("JWT iss 与当前配置不一致"));
|
||||
}
|
||||
|
||||
normalize_required_field(self.sub.clone(), "JWT sub 不能为空")?;
|
||||
normalize_required_field(self.sid.clone(), "JWT sid 不能为空")?;
|
||||
normalize_roles(self.roles.clone())?;
|
||||
|
||||
if self.exp <= self.iat {
|
||||
return Err(JwtError::InvalidClaims("JWT exp 必须晚于 iat"));
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
|
||||
pub fn sign_access_token(
|
||||
claims: &AccessTokenClaims,
|
||||
config: &JwtConfig,
|
||||
) -> Result<String, JwtError> {
|
||||
claims.validate_for_config(config)?;
|
||||
|
||||
let header = Header {
|
||||
alg: ACCESS_TOKEN_ALGORITHM,
|
||||
typ: Some("JWT".to_string()),
|
||||
..Header::default()
|
||||
};
|
||||
|
||||
encode(
|
||||
&header,
|
||||
claims,
|
||||
&EncodingKey::from_secret(config.secret.as_bytes()),
|
||||
)
|
||||
.map_err(|error| JwtError::SignFailed(format!("JWT 签发失败：{error}")))
|
||||
}
|
||||
|
||||
pub fn verify_access_token(token: &str, config: &JwtConfig) -> Result<AccessTokenClaims, JwtError> {
|
||||
let token = token.trim();
|
||||
if token.is_empty() {
|
||||
return Err(JwtError::VerifyFailed("JWT 不能为空".to_string()));
|
||||
}
|
||||
|
||||
let mut validation = Validation::new(ACCESS_TOKEN_ALGORITHM);
|
||||
validation.required_spec_claims = HashSet::from([
|
||||
"exp".to_string(),
|
||||
"iat".to_string(),
|
||||
"iss".to_string(),
|
||||
"sub".to_string(),
|
||||
]);
|
||||
validation.set_issuer(&[config.issuer()]);
|
||||
|
||||
let decoded = decode::<AccessTokenClaims>(
|
||||
token,
|
||||
&DecodingKey::from_secret(config.secret.as_bytes()),
|
||||
&validation,
|
||||
)
|
||||
.map_err(map_verify_error)?;
|
||||
|
||||
decoded.claims.validate_for_config(config)?;
|
||||
Ok(decoded.claims)
|
||||
}
|
||||
|
||||
impl fmt::Display for JwtError {
|
||||
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||
match self {
|
||||
Self::InvalidConfig(message) | Self::InvalidClaims(message) => f.write_str(message),
|
||||
Self::SignFailed(message) | Self::VerifyFailed(message) => f.write_str(message),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl Error for JwtError {}
|
||||
|
||||
fn normalize_required_field(
|
||||
value: String,
|
||||
error_message: &'static str,
|
||||
) -> Result<String, JwtError> {
|
||||
let value = value.trim().to_string();
|
||||
if value.is_empty() {
|
||||
return Err(JwtError::InvalidClaims(error_message));
|
||||
}
|
||||
|
||||
Ok(value)
|
||||
}
|
||||
|
||||
fn normalize_optional_field(value: Option<String>) -> Option<String> {
|
||||
value.and_then(|field| {
|
||||
let field = field.trim().to_string();
|
||||
if field.is_empty() {
|
||||
return None;
|
||||
}
|
||||
|
||||
Some(field)
|
||||
})
|
||||
}
|
||||
|
||||
fn normalize_roles(roles: Vec<String>) -> Result<Vec<String>, JwtError> {
|
||||
let roles = roles
|
||||
.into_iter()
|
||||
.map(|role| role.trim().to_string())
|
||||
.filter(|role| !role.is_empty())
|
||||
.collect::<Vec<_>>();
|
||||
|
||||
if roles.is_empty() {
|
||||
return Err(JwtError::InvalidClaims("JWT roles 至少包含一个角色"));
|
||||
}
|
||||
|
||||
Ok(roles)
|
||||
}
|
||||
|
||||
fn map_verify_error(error: jsonwebtoken::errors::Error) -> JwtError {
|
||||
let message = match error.kind() {
|
||||
ErrorKind::ExpiredSignature => "JWT 已过期".to_string(),
|
||||
ErrorKind::InvalidIssuer => "JWT 发行者不匹配".to_string(),
|
||||
ErrorKind::InvalidSignature => "JWT 签名无效".to_string(),
|
||||
ErrorKind::InvalidAlgorithm => "JWT 算法不匹配".to_string(),
|
||||
ErrorKind::InvalidToken => "JWT 非法".to_string(),
|
||||
ErrorKind::ImmatureSignature => "JWT 尚未生效".to_string(),
|
||||
ErrorKind::MissingRequiredClaim(claim) => format!("JWT 缺少必填字段：{claim}"),
|
||||
_ => format!("JWT 校验失败：{error}"),
|
||||
};
|
||||
|
||||
JwtError::VerifyFailed(message)
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
fn build_jwt_config() -> JwtConfig {
|
||||
JwtConfig::new(
|
||||
"https://auth.genarrative.local".to_string(),
|
||||
"genarrative-dev-secret".to_string(),
|
||||
DEFAULT_ACCESS_TOKEN_TTL_SECONDS,
|
||||
)
|
||||
.expect("jwt config should be valid")
|
||||
}
|
||||
|
||||
fn build_claims_input() -> AccessTokenClaimsInput {
|
||||
AccessTokenClaimsInput {
|
||||
user_id: "usr_123".to_string(),
|
||||
session_id: "sess_456".to_string(),
|
||||
provider: AuthProvider::Wechat,
|
||||
roles: vec!["user".to_string()],
|
||||
token_version: 3,
|
||||
phone_verified: false,
|
||||
binding_status: BindingStatus::PendingBindPhone,
|
||||
display_name: Some("微信旅人".to_string()),
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn round_trip_sign_and_verify_access_token() {
|
||||
let config = build_jwt_config();
|
||||
let claims =
|
||||
AccessTokenClaims::from_input(build_claims_input(), &config, OffsetDateTime::now_utc())
|
||||
.expect("claims should build");
|
||||
|
||||
let token = sign_access_token(&claims, &config).expect("token should sign");
|
||||
let verified = verify_access_token(&token, &config).expect("token should verify");
|
||||
|
||||
assert_eq!(verified, claims);
|
||||
assert_eq!(verified.user_id(), "usr_123");
|
||||
assert_eq!(verified.session_id(), "sess_456");
|
||||
assert_eq!(verified.token_version(), 3);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn verify_rejects_invalid_issuer() {
|
||||
let config = build_jwt_config();
|
||||
let claims =
|
||||
AccessTokenClaims::from_input(build_claims_input(), &config, OffsetDateTime::now_utc())
|
||||
.expect("claims should build");
|
||||
let token = sign_access_token(&claims, &config).expect("token should sign");
|
||||
let other_config = JwtConfig::new(
|
||||
"https://auth.other.local".to_string(),
|
||||
"genarrative-dev-secret".to_string(),
|
||||
DEFAULT_ACCESS_TOKEN_TTL_SECONDS,
|
||||
)
|
||||
.expect("other config should be valid");
|
||||
|
||||
let error = verify_access_token(&token, &other_config).expect_err("issuer should mismatch");
|
||||
|
||||
assert_eq!(
|
||||
error,
|
||||
JwtError::VerifyFailed("JWT 发行者不匹配".to_string())
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn build_claims_rejects_empty_roles() {
|
||||
let error = AccessTokenClaims::from_input(
|
||||
AccessTokenClaimsInput {
|
||||
roles: Vec::new(),
|
||||
..build_claims_input()
|
||||
},
|
||||
&build_jwt_config(),
|
||||
OffsetDateTime::now_utc(),
|
||||
)
|
||||
.expect_err("empty roles should be rejected");
|
||||
|
||||
assert_eq!(error, JwtError::InvalidClaims("JWT roles 至少包含一个角色"));
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user