use crate::error::BaseError;
use crate::token::TokenClaims;
use jsonwebtoken::{
decode, decode_header, encode, Algorithm, DecodingKey, EncodingKey, Header, Validation,
};
use std::collections::{HashMap, HashSet};
use std::time::{SystemTime, UNIX_EPOCH};
use yang_db::RedisClient;
const MAX_SYMMETRIC_KEYRING_KEYS: usize = 8;
const MAX_KEY_ID_BYTES: usize = 64;
const MIN_HMAC_SECRET_BYTES: usize = 32;
pub(crate) const REVOCATION_WATERMARK_MIN_TTL_SECONDS: u64 = 90 * 24 * 60 * 60;
pub(crate) fn current_unix_timestamp() -> Result<u64, BaseError> {
SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|d| d.as_secs())
.map_err(|e| BaseError::ConfigError(format!("系统时钟异常,早于 UNIX_EPOCH: {}", e)))
}
fn build_validation(algorithm: Algorithm, issuer: &str, audience: &str) -> Validation {
let mut validation = Validation::new(algorithm);
validation.algorithms = vec![algorithm];
validation.set_issuer(&[issuer]);
validation.set_audience(&[audience]);
let mut required_claims = HashSet::new();
required_claims.insert("exp".to_string());
required_claims.insert("iss".to_string());
required_claims.insert("aud".to_string());
validation.required_spec_claims = required_claims;
validation.leeway = 0;
validation
}
enum VerificationKeys {
Single(DecodingKey),
Keyring(HashMap<String, DecodingKey>),
}
fn validate_hmac_algorithm(algorithm: Algorithm, context: &str) -> Result<(), BaseError> {
if !matches!(
algorithm,
Algorithm::HS256 | Algorithm::HS384 | Algorithm::HS512
) {
return Err(BaseError::TokenKeyInvalid(format!(
"{context} 仅支持 HS256、HS384、HS512"
)));
}
Ok(())
}
fn validate_key_id(key_id: &str) -> Result<(), BaseError> {
if key_id.is_empty()
|| key_id.len() > MAX_KEY_ID_BYTES
|| !key_id
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-'))
{
return Err(BaseError::TokenKeyInvalid(
"kid 必须是 1..=64 字节的 ASCII 字母、数字、点、下划线或连字符".to_string(),
));
}
Ok(())
}
fn validate_hmac_secret(secret: &str) -> Result<(), BaseError> {
if secret.len() < MIN_HMAC_SECRET_BYTES {
return Err(BaseError::TokenKeyInvalid(format!(
"HMAC secret 至少需要 {MIN_HMAC_SECRET_BYTES} 字节"
)));
}
Ok(())
}
fn invalid_key_selection() -> BaseError {
BaseError::TokenVerifyFailed(jsonwebtoken::errors::Error::from(
jsonwebtoken::errors::ErrorKind::InvalidToken,
))
}
pub struct TokenManager {
encoding_key: EncodingKey,
verification_keys: VerificationKeys,
algorithm: Algorithm,
issuer: String,
audience: String,
access_token_expiry: u64,
refresh_token_expiry: u64,
validation: Validation,
jwt_header: Header,
revocation_cache: Option<RedisClient>,
}
impl TokenManager {
pub fn new_symmetric(
secret: &str,
algorithm: Algorithm,
issuer: String,
audience: String,
access_token_expiry: u64,
refresh_token_expiry: u64,
) -> Result<Self, BaseError> {
validate_hmac_algorithm(algorithm, "new_symmetric")?;
validate_hmac_secret(secret)?;
let mut jwt_header = Header::new(algorithm);
jwt_header.typ = Some("JWT".to_string());
Ok(Self {
encoding_key: EncodingKey::from_secret(secret.as_bytes()),
verification_keys: VerificationKeys::Single(DecodingKey::from_secret(
secret.as_bytes(),
)),
algorithm,
validation: build_validation(algorithm, &issuer, &audience),
issuer,
audience,
access_token_expiry,
refresh_token_expiry,
jwt_header,
revocation_cache: None,
})
}
#[allow(clippy::too_many_arguments)]
pub fn new_symmetric_keyring(
active_key_id: String,
active_secret: &str,
retiring_keys: Vec<(String, String)>,
algorithm: Algorithm,
issuer: String,
audience: String,
access_token_expiry: u64,
refresh_token_expiry: u64,
) -> Result<Self, BaseError> {
validate_hmac_algorithm(algorithm, "对称 Token keyring")?;
validate_key_id(&active_key_id)?;
validate_hmac_secret(active_secret)?;
if retiring_keys.len() + 1 > MAX_SYMMETRIC_KEYRING_KEYS {
return Err(BaseError::TokenKeyInvalid(format!(
"Token keyring 最多允许 {MAX_SYMMETRIC_KEYRING_KEYS} 把密钥"
)));
}
let mut verification_keys = HashMap::with_capacity(retiring_keys.len() + 1);
verification_keys.insert(
active_key_id.clone(),
DecodingKey::from_secret(active_secret.as_bytes()),
);
for (key_id, secret) in retiring_keys {
validate_key_id(&key_id)?;
validate_hmac_secret(&secret)?;
if verification_keys
.insert(key_id, DecodingKey::from_secret(secret.as_bytes()))
.is_some()
{
return Err(BaseError::TokenKeyInvalid(
"Token keyring 的 kid 必须唯一".to_string(),
));
}
}
let mut jwt_header = Header::new(algorithm);
jwt_header.typ = Some("JWT".to_string());
jwt_header.kid = Some(active_key_id);
Ok(Self {
encoding_key: EncodingKey::from_secret(active_secret.as_bytes()),
verification_keys: VerificationKeys::Keyring(verification_keys),
algorithm,
validation: build_validation(algorithm, &issuer, &audience),
issuer,
audience,
access_token_expiry,
refresh_token_expiry,
jwt_header,
revocation_cache: None,
})
}
pub fn new_asymmetric(
private_key: &str,
public_key: &str,
algorithm: Algorithm,
issuer: String,
audience: String,
access_token_expiry: u64,
refresh_token_expiry: u64,
) -> Result<Self, BaseError> {
let encoding_key = EncodingKey::from_rsa_pem(private_key.as_bytes())
.map_err(|e| BaseError::TokenKeyInvalid(format!("私钥无效: {}", e)))?;
let decoding_key = DecodingKey::from_rsa_pem(public_key.as_bytes())
.map_err(|e| BaseError::TokenKeyInvalid(format!("公钥无效: {}", e)))?;
let mut jwt_header = Header::new(algorithm);
jwt_header.typ = Some("JWT".to_string());
Ok(Self {
encoding_key,
verification_keys: VerificationKeys::Single(decoding_key),
algorithm,
validation: build_validation(algorithm, &issuer, &audience),
issuer,
audience,
access_token_expiry,
refresh_token_expiry,
jwt_header,
revocation_cache: None,
})
}
pub(crate) fn attach_revocation_cache(&mut self, cache: RedisClient) {
self.revocation_cache = Some(cache);
}
pub(crate) fn revocation_cache(&self) -> Result<&RedisClient, BaseError> {
self.revocation_cache
.as_ref()
.ok_or(BaseError::RedisNotInitialized)
}
pub fn generate_access_token(
&self,
subject: &str,
custom_claims: serde_json::Value,
) -> Result<String, BaseError> {
let now = current_unix_timestamp()?;
self.generate_access_token_at(subject, custom_claims, now)
}
pub fn generate_refresh_token(&self, subject: &str) -> Result<String, BaseError> {
let now = current_unix_timestamp()?;
self.generate_refresh_token_at(subject, serde_json::Value::Null, now)
}
pub fn generate_refresh_token_with_claims(
&self,
subject: &str,
custom_claims: serde_json::Value,
) -> Result<String, BaseError> {
let now = current_unix_timestamp()?;
self.generate_refresh_token_at(subject, custom_claims, now)
}
pub fn generate_token_pair(
&self,
subject: &str,
custom_claims: serde_json::Value,
) -> Result<(String, String), BaseError> {
self.generate_token_pair_with_refresh_claims(
subject,
custom_claims,
serde_json::Value::Null,
)
}
pub fn generate_token_pair_with_refresh_claims(
&self,
subject: &str,
access_claims: serde_json::Value,
refresh_claims: serde_json::Value,
) -> Result<(String, String), BaseError> {
let now = current_unix_timestamp()?;
self.generate_token_pair_at(subject, access_claims, refresh_claims, now)
}
pub(crate) fn generate_token_pair_at(
&self,
subject: &str,
access_claims: serde_json::Value,
refresh_claims: serde_json::Value,
now: u64,
) -> Result<(String, String), BaseError> {
let access_token = self.generate_access_token_at(subject, access_claims, now)?;
let refresh_token = self.generate_refresh_token_at(subject, refresh_claims, now)?;
Ok((access_token, refresh_token))
}
fn generate_access_token_at(
&self,
subject: &str,
custom_claims: serde_json::Value,
now: u64,
) -> Result<String, BaseError> {
let claims = TokenClaims {
iss: self.issuer.clone(),
sub: subject.to_string(),
aud: self.audience.clone(),
exp: now + self.access_token_expiry,
nbf: now,
iat: now,
jti: uuid::Uuid::new_v4().to_string(),
token_type: crate::token::TokenType::Access,
custom: custom_claims,
};
encode(&self.jwt_header, &claims, &self.encoding_key)
.map_err(BaseError::TokenGenerateFailed)
}
fn generate_refresh_token_at(
&self,
subject: &str,
custom_claims: serde_json::Value,
now: u64,
) -> Result<String, BaseError> {
let claims = TokenClaims {
iss: self.issuer.clone(),
sub: subject.to_string(),
aud: self.audience.clone(),
exp: now + self.refresh_token_expiry,
nbf: now,
iat: now,
jti: uuid::Uuid::new_v4().to_string(),
token_type: crate::token::TokenType::Refresh,
custom: custom_claims,
};
encode(&self.jwt_header, &claims, &self.encoding_key)
.map_err(BaseError::TokenGenerateFailed)
}
pub(crate) fn revocation_watermark_ttl(&self) -> u64 {
self.refresh_token_expiry
.max(self.access_token_expiry)
.max(REVOCATION_WATERMARK_MIN_TTL_SECONDS)
}
pub fn verify_token(&self, token: &str) -> Result<TokenClaims, BaseError> {
let decoding_key = match &self.verification_keys {
VerificationKeys::Single(key) => key,
VerificationKeys::Keyring(keys) => {
let header = decode_header(token).map_err(BaseError::TokenParseFailed)?;
if header.alg != self.algorithm {
return Err(invalid_key_selection());
}
let key_id = header.kid.as_deref().ok_or_else(invalid_key_selection)?;
keys.get(key_id).ok_or_else(invalid_key_selection)?
}
};
let token_data = decode::<TokenClaims>(token, decoding_key, &self.validation)?;
Ok(token_data.claims)
}
#[deprecated(
since = "0.1.0",
note = "此方法跳过所有 JWT 安全验证(签名/过期/签发者),仅可用于调试日志和单元测试。鉴权路径必须使用 verify_token 或 verify_token_checked。"
)]
pub fn parse_token_unsafe(&self, token: &str) -> Result<TokenClaims, BaseError> {
let header = jsonwebtoken::decode_header(token).map_err(BaseError::TokenParseFailed)?;
let mut validation = jsonwebtoken::Validation::new(header.alg);
validation.insecure_disable_signature_validation();
validation.validate_exp = false;
validation.validate_nbf = false;
validation.validate_aud = false;
validation.required_spec_claims.clear();
let token_data = jsonwebtoken::decode::<TokenClaims>(
token,
&jsonwebtoken::DecodingKey::from_secret(&[]),
&validation,
)
.map_err(BaseError::TokenParseFailed)?;
Ok(token_data.claims)
}
pub fn is_token_expiring_soon(
&self,
token: &str,
threshold_secs: u64,
) -> Result<bool, BaseError> {
let claims = self.verify_token(token)?;
let now = current_unix_timestamp()?;
let remaining = claims.exp.saturating_sub(now);
Ok(remaining < threshold_secs)
}
#[deprecated(
since = "0.1.0",
note = "此方法不轮换 Refresh Token(旧 token 在过期前始终可用,且不触发复用检测/家族撤销)。刷新请使用 RefreshAction,或 TokenManager::rotate_refresh_token / rotate_refresh_token_from_claims。"
)]
pub async fn refresh_access_token(
&self,
refresh_token: &str,
custom_claims: serde_json::Value,
) -> Result<String, BaseError> {
let claims = self
.verify_token_checked(refresh_token, crate::token::TokenType::Refresh)
.await?;
self.generate_access_token(&claims.sub, custom_claims)
}
pub async fn rotate_refresh_token(
&self,
old_refresh: &str,
custom_claims: serde_json::Value,
) -> Result<(String, String), BaseError> {
self.rotate_refresh_token_with_refresh_claims(
old_refresh,
custom_claims,
serde_json::Value::Null,
)
.await
}
pub async fn rotate_refresh_token_with_refresh_claims(
&self,
old_refresh: &str,
access_claims: serde_json::Value,
refresh_claims: serde_json::Value,
) -> Result<(String, String), BaseError> {
let old_claims = self
.verify_token_checked(old_refresh, crate::token::TokenType::Refresh)
.await?;
self.rotate_refresh_token_from_claims_with_refresh_claims(
&old_claims,
access_claims,
refresh_claims,
)
.await
}
pub async fn rotate_refresh_token_from_claims(
&self,
old_claims: &TokenClaims,
custom_claims: serde_json::Value,
) -> Result<(String, String), BaseError> {
self.rotate_refresh_token_from_claims_with_refresh_claims(
old_claims,
custom_claims,
serde_json::Value::Null,
)
.await
}
pub async fn rotate_refresh_token_from_claims_with_refresh_claims(
&self,
old_claims: &TokenClaims,
access_claims: serde_json::Value,
refresh_claims: serde_json::Value,
) -> Result<(String, String), BaseError> {
if old_claims.token_type != crate::token::TokenType::Refresh {
return Err(BaseError::TokenTypeInvalid(
"期望 refresh token".to_string(),
));
}
let now = current_unix_timestamp()?;
if old_claims.exp <= now {
return Err(BaseError::TokenExpired);
}
let ttl = old_claims.exp - now;
if !self.try_revoke_once(&old_claims.jti, ttl).await? {
self.revoke_by_subject(&old_claims.sub).await?;
return Err(BaseError::TokenRevoked);
}
self.generate_token_pair_at(&old_claims.sub, access_claims, refresh_claims, now)
}
}
impl std::fmt::Debug for TokenManager {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
let (verification_mode, verification_key_count) = match &self.verification_keys {
VerificationKeys::Single(_) => ("single", 1),
VerificationKeys::Keyring(keys) => ("keyring", keys.len()),
};
f.debug_struct("TokenManager")
.field("algorithm", &self.algorithm)
.field("issuer", &self.issuer)
.field("audience", &self.audience)
.field("access_token_expiry", &self.access_token_expiry)
.field("refresh_token_expiry", &self.refresh_token_expiry)
.field("verification_mode", &verification_mode)
.field("verification_key_count", &verification_key_count)
.field("active_key_id", &self.jwt_header.kid)
.field("validation", &self.validation)
.finish_non_exhaustive()
}
}