use crate::action::ActionContext;
use crate::transport::client_ip::client_ip_identity;
use async_trait::async_trait;
use hmac::{Hmac, Mac};
use rand_core::{OsRng, RngCore};
use schemars::JsonSchema;
use serde::Serialize;
use sha2::Sha256;
use std::fmt;
use std::sync::Arc;
use yang_base::BaseError;
const RESERVE_SEND_SCRIPT: &str = r#"
local cooldown_ttl = redis.call('TTL', KEYS[4])
if cooldown_ttl > 0 then
return {2, cooldown_ttl}
end
local retry_after = 0
local exceeded = 0
for index = 1, 3 do
local current = redis.call('INCR', KEYS[index])
if current == 1 then
redis.call('EXPIRE', KEYS[index], ARGV[1])
end
local ttl = redis.call('TTL', KEYS[index])
if ttl < 1 then
redis.call('EXPIRE', KEYS[index], ARGV[1])
ttl = tonumber(ARGV[1])
end
if current > tonumber(ARGV[index + 1]) then
exceeded = 1
if ttl > retry_after then
retry_after = ttl
end
end
end
if exceeded == 1 then
return {1, retry_after}
end
redis.call('SET', KEYS[4], '1', 'EX', ARGV[5], 'NX')
return {0, tonumber(ARGV[5])}
"#;
const VERIFY_AND_CONSUME_SCRIPT: &str = r#"
local value = redis.call('GET', KEYS[1])
if not value then
return 0
end
local separator = string.find(value, ':', 1, true)
if not separator then
redis.call('DEL', KEYS[1])
return 0
end
local expected = string.sub(value, 1, separator - 1)
local attempts = tonumber(string.sub(value, separator + 1))
if not attempts then
redis.call('DEL', KEYS[1])
return 0
end
if expected == ARGV[1] then
redis.call('DEL', KEYS[1])
return 1
end
attempts = attempts + 1
if attempts >= tonumber(ARGV[2]) then
redis.call('DEL', KEYS[1])
return -2
end
redis.call('SET', KEYS[1], expected .. ':' .. attempts, 'KEEPTTL')
return -1
"#;
const DELETE_IF_CURRENT_SCRIPT: &str = r#"
local value = redis.call('GET', KEYS[1])
if value and string.sub(value, 1, string.len(ARGV[1]) + 1) == ARGV[1] .. ':' then
return redis.call('DEL', KEYS[1])
end
return 0
"#;
const VERIFY_ONLY_SCRIPT: &str = r#"
local value = redis.call('GET', KEYS[1])
if not value then
return 0
end
local separator = string.find(value, ':', 1, true)
if not separator then
return 0
end
local expected = string.sub(value, 1, separator - 1)
local attempts = tonumber(string.sub(value, separator + 1))
if not attempts then
return 0
end
if expected == ARGV[1] then
return 1
end
attempts = attempts + 1
if attempts >= tonumber(ARGV[2]) then
redis.call('DEL', KEYS[1])
return -2
end
redis.call('SET', KEYS[1], expected .. ':' .. attempts, 'KEEPTTL')
return -1
"#;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EmailDeliveryError {
InvalidMessage,
Unavailable,
}
impl fmt::Display for EmailDeliveryError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::InvalidMessage => formatter.write_str("邮件内容无效"),
Self::Unavailable => formatter.write_str("邮件服务暂不可用"),
}
}
}
impl std::error::Error for EmailDeliveryError {}
#[async_trait]
pub trait RegistrationEmailSender: Send + Sync + 'static {
async fn send_registration_code(
&self,
recipient: &str,
code: &str,
expires_in_seconds: u64,
) -> Result<(), EmailDeliveryError>;
}
#[derive(Clone)]
pub struct RegistrationEmailSenderHandle(Arc<dyn RegistrationEmailSender>);
impl RegistrationEmailSenderHandle {
pub fn new<T>(sender: T) -> Self
where
T: RegistrationEmailSender,
{
Self(Arc::new(sender))
}
pub fn from_arc(sender: Arc<dyn RegistrationEmailSender>) -> Self {
Self(sender)
}
pub async fn send_registration_code(
&self,
recipient: &str,
code: &str,
expires_in_seconds: u64,
) -> Result<(), EmailDeliveryError> {
self.0
.send_registration_code(recipient, code, expires_in_seconds)
.await
}
}
impl fmt::Debug for RegistrationEmailSenderHandle {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("RegistrationEmailSenderHandle")
.finish_non_exhaustive()
}
}
#[async_trait]
pub trait VerificationCodeSender: Send + Sync + 'static {
async fn send_verification_code(
&self,
recipient: &str,
code: &str,
expires_in_seconds: u64,
) -> Result<(), EmailDeliveryError>;
}
#[derive(Clone)]
pub struct VerificationCodeSenderHandle(Arc<dyn VerificationCodeSender>);
impl VerificationCodeSenderHandle {
pub fn new<T>(sender: T) -> Self
where
T: VerificationCodeSender,
{
Self(Arc::new(sender))
}
pub fn from_arc(sender: Arc<dyn VerificationCodeSender>) -> Self {
Self(sender)
}
pub async fn send_verification_code(
&self,
recipient: &str,
code: &str,
expires_in_seconds: u64,
) -> Result<(), EmailDeliveryError> {
self.0
.send_verification_code(recipient, code, expires_in_seconds)
.await
}
}
impl fmt::Debug for VerificationCodeSenderHandle {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("VerificationCodeSenderHandle")
.finish_non_exhaustive()
}
}
#[derive(Clone)]
pub struct EmailVerificationConfig {
pub redis_key_prefix: String,
pub secret: String,
pub ttl_seconds: u64,
pub resend_cooldown_seconds: u64,
pub max_attempts: u32,
pub code_digits: usize,
pub send_window_seconds: u64,
pub send_ip_attempts: u64,
pub send_email_attempts: u64,
pub send_global_attempts: u64,
pub send_metric_name: &'static str,
pub verify_metric_name: &'static str,
}
impl fmt::Debug for EmailVerificationConfig {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("EmailVerificationConfig")
.field("redis_key_prefix", &self.redis_key_prefix)
.field("secret", &"[REDACTED]")
.field("ttl_seconds", &self.ttl_seconds)
.field("resend_cooldown_seconds", &self.resend_cooldown_seconds)
.field("max_attempts", &self.max_attempts)
.field("code_digits", &self.code_digits)
.field("send_window_seconds", &self.send_window_seconds)
.field("send_ip_attempts", &self.send_ip_attempts)
.field("send_email_attempts", &self.send_email_attempts)
.field("send_global_attempts", &self.send_global_attempts)
.field("send_metric_name", &self.send_metric_name)
.field("verify_metric_name", &self.verify_metric_name)
.finish()
}
}
#[derive(Debug, Clone, Serialize, JsonSchema)]
pub struct RegistrationEmailCodeAccepted {
pub accepted: bool,
pub expires_in: u64,
pub resend_after: u64,
}
pub fn normalize_email(value: &str) -> Result<String, BaseError> {
let normalized = value.trim().to_ascii_lowercase();
if normalized.is_empty() || normalized.len() > 254 || !normalized.is_ascii() {
return Err(invalid_email());
}
let Some((local, domain)) = normalized.split_once('@') else {
return Err(invalid_email());
};
let local_valid = !local.is_empty()
&& local.len() <= 64
&& !local.starts_with('.')
&& !local.ends_with('.')
&& !local.contains("..")
&& local.bytes().all(|byte| {
byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'%' | b'+' | b'-')
});
let labels = domain.split('.').collect::<Vec<_>>();
let domain_valid = labels.len() >= 2
&& labels.iter().all(|label| {
!label.is_empty()
&& !label.starts_with('-')
&& !label.ends_with('-')
&& label
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || byte == b'-')
})
&& labels.last().is_some_and(|label| {
label.len() >= 2 && label.bytes().all(|byte| byte.is_ascii_alphabetic())
});
if !local_valid || !domain_valid {
return Err(invalid_email());
}
Ok(normalized)
}
pub struct RegistrationEmailVerification<'a> {
config: &'a EmailVerificationConfig,
}
impl<'a> RegistrationEmailVerification<'a> {
pub fn from_context(ctx: &'a ActionContext) -> Result<Self, BaseError> {
Self::from_config(ctx.tools().config::<EmailVerificationConfig>()?)
}
pub fn from_config(config: &'a EmailVerificationConfig) -> Result<Self, BaseError> {
if !(1..=9).contains(&config.code_digits) {
return Err(BaseError::ConfigError(
"邮箱验证码位数必须在 1..=9 范围内".to_string(),
));
}
Ok(Self { config })
}
pub async fn request(
&self,
ctx: &ActionContext,
email: &str,
deliver: bool,
) -> Result<RegistrationEmailCodeAccepted, BaseError> {
self.request_inner(ctx, email, deliver, None).await
}
pub async fn request_via(
&self,
ctx: &ActionContext,
email: &str,
deliver: bool,
sender: &VerificationCodeSenderHandle,
) -> Result<RegistrationEmailCodeAccepted, BaseError> {
self.request_inner(ctx, email, deliver, Some(sender)).await
}
async fn request_inner(
&self,
ctx: &ActionContext,
email: &str,
deliver: bool,
sender: Option<&VerificationCodeSenderHandle>,
) -> Result<RegistrationEmailCodeAccepted, BaseError> {
let fingerprint = email_fingerprint(&self.config.secret, email);
let prefix = self.key_prefix();
let keys = [
format!(
"{prefix}:send:ip:{}",
client_ip_fingerprint(&self.config.secret, ctx)
),
format!("{prefix}:send:email:{fingerprint}"),
format!("{prefix}:send:global"),
format!("{prefix}:cooldown:{fingerprint}"),
];
let args = [
self.config.send_window_seconds.to_string(),
self.config.send_ip_attempts.to_string(),
self.config.send_email_attempts.to_string(),
self.config.send_global_attempts.to_string(),
self.config.resend_cooldown_seconds.to_string(),
];
let cache = ctx.tools().cache()?;
let decision: (i64, i64) = cache
.eval_script(&cache.script(RESERVE_SEND_SCRIPT), &keys, &args)
.await?;
if decision.0 != 0 {
#[cfg(feature = "metrics")]
metrics::counter!(
self.config.send_metric_name,
"result" => if decision.0 == 2 { "cooldown" } else { "limited" }
)
.increment(1);
return Err(BaseError::RateLimitExceeded {
retry_after_seconds: u64::try_from(decision.1).unwrap_or(1).max(1),
});
}
if !deliver {
#[cfg(feature = "metrics")]
metrics::counter!(self.config.send_metric_name, "result" => "suppressed").increment(1);
return Ok(self.accepted());
}
let code = generate_code(self.config.code_digits);
let digest = code_digest(&self.config.secret, email, &code);
let code_key = format!("{prefix}:code:{fingerprint}");
cache
.setex(
code_key.clone(),
i64::try_from(self.config.ttl_seconds).map_err(|_| {
BaseError::ConfigError("邮箱验证码 TTL 超出 Redis 范围".to_string())
})?,
format!("{digest}:0"),
)
.await?;
let send_result = match sender {
Some(sender) => {
sender
.send_verification_code(email, &code, self.config.ttl_seconds)
.await
}
None => {
ctx.tools()
.extension::<RegistrationEmailSenderHandle>()?
.send_registration_code(email, &code, self.config.ttl_seconds)
.await
}
};
if send_result.is_err() {
let _: i64 = cache
.eval_script(
&cache.script(DELETE_IF_CURRENT_SCRIPT),
&[code_key],
&[digest],
)
.await?;
#[cfg(feature = "metrics")]
metrics::counter!(self.config.send_metric_name, "result" => "failed").increment(1);
return Err(delivery_unavailable());
}
#[cfg(feature = "metrics")]
metrics::counter!(self.config.send_metric_name, "result" => "sent").increment(1);
Ok(self.accepted())
}
pub async fn consume(
&self,
ctx: &ActionContext,
email: &str,
code: &str,
) -> Result<(), BaseError> {
let (key, digest) = self.verify_material(email, code)?;
let cache = ctx.tools().cache()?;
let result: i64 = cache
.eval_script(
&cache.script(VERIFY_AND_CONSUME_SCRIPT),
&[key],
&[digest, self.config.max_attempts.to_string()],
)
.await?;
if result != 1 {
#[cfg(feature = "metrics")]
metrics::counter!(self.config.verify_metric_name, "result" => "denied").increment(1);
return Err(invalid_code());
}
#[cfg(feature = "metrics")]
metrics::counter!(self.config.verify_metric_name, "result" => "consumed").increment(1);
Ok(())
}
pub async fn verify_only(
&self,
ctx: &ActionContext,
email: &str,
code: &str,
) -> Result<(), BaseError> {
let (key, digest) = self.verify_material(email, code)?;
let cache = ctx.tools().cache()?;
let result: i64 = cache
.eval_script(
&cache.script(VERIFY_ONLY_SCRIPT),
&[key],
&[digest, self.config.max_attempts.to_string()],
)
.await?;
if result != 1 {
#[cfg(feature = "metrics")]
metrics::counter!(self.config.verify_metric_name, "result" => "denied").increment(1);
return Err(invalid_code());
}
#[cfg(feature = "metrics")]
metrics::counter!(self.config.verify_metric_name, "result" => "peeked").increment(1);
Ok(())
}
fn verify_material(&self, email: &str, code: &str) -> Result<(String, String), BaseError> {
if code.len() != self.config.code_digits || !code.bytes().all(|byte| byte.is_ascii_digit())
{
return Err(invalid_code());
}
let fingerprint = email_fingerprint(&self.config.secret, email);
let key = format!("{}:code:{fingerprint}", self.key_prefix());
let digest = code_digest(&self.config.secret, email, code);
Ok((key, digest))
}
fn key_prefix(&self) -> &str {
&self.config.redis_key_prefix
}
fn accepted(&self) -> RegistrationEmailCodeAccepted {
RegistrationEmailCodeAccepted {
accepted: true,
expires_in: self.config.ttl_seconds,
resend_after: self.config.resend_cooldown_seconds,
}
}
}
fn generate_code(code_digits: usize) -> String {
let code_space = 10_u32.pow(u32::try_from(code_digits).unwrap_or(6));
let unbiased_upper_bound = u32::MAX - (u32::MAX % code_space);
let value = loop {
let candidate = OsRng.next_u32();
if candidate < unbiased_upper_bound {
break candidate % code_space;
}
};
format!("{value:0code_digits$}")
}
fn client_ip_fingerprint(secret: &str, ctx: &ActionContext) -> String {
keyed_digest(
secret,
&[
b"registration-email-ip-v1",
client_ip_identity(ctx).as_bytes(),
],
)
}
fn email_fingerprint(secret: &str, email: &str) -> String {
keyed_digest(secret, &[b"registration-email-key-v1", email.as_bytes()])
}
fn code_digest(secret: &str, email: &str, code: &str) -> String {
keyed_digest(
secret,
&[
b"registration-email-code-v1",
email.as_bytes(),
code.as_bytes(),
],
)
}
fn keyed_digest(secret: &str, parts: &[&[u8]]) -> String {
let mut hasher = Hmac::<Sha256>::new_from_slice(secret.as_bytes())
.unwrap_or_else(|_| unreachable!("HMAC-SHA256 接受任意长度密钥"));
for part in parts {
hasher.update(&(part.len() as u64).to_be_bytes());
hasher.update(part);
}
hasher
.finalize()
.into_bytes()
.iter()
.map(|byte| format!("{byte:02x}"))
.collect()
}
fn invalid_email() -> BaseError {
BaseError::ParamInvalid("email".to_string(), "邮箱格式无效".to_string())
}
fn invalid_code() -> BaseError {
BaseError::ParamInvalid(
"email_code".to_string(),
"邮箱验证码无效或已过期".to_string(),
)
}
fn delivery_unavailable() -> BaseError {
BaseError::UpstreamUnavailable("邮件服务暂不可用".to_string())
}
#[cfg(test)]
mod tests {
use super::*;
const CODE_DIGITS: usize = 6;
#[test]
fn email_is_canonical_ascii_and_rejects_ambiguous_shapes() {
assert_eq!(
normalize_email(" Alice.Tag+demo@Example.COM ")
.unwrap_or_else(|error| panic!("合法邮箱应规范化: {error}")),
"alice.tag+demo@example.com"
);
for invalid in [
"alice@example",
"alice@@example.com",
".alice@example.com",
"alice..tag@example.com",
"alice@-example.com",
"用户@example.com",
] {
assert!(normalize_email(invalid).is_err(), "应拒绝 {invalid:?}");
}
}
#[test]
fn generated_code_and_redis_material_do_not_expose_plaintext_identity() {
let code = generate_code(CODE_DIGITS);
assert_eq!(code.len(), CODE_DIGITS);
assert!(code.bytes().all(|byte| byte.is_ascii_digit()));
let email = "alice@example.com";
let secret = "independent-email-verification-secret-32-bytes";
let fingerprint = email_fingerprint(secret, email);
let digest = code_digest(secret, email, &code);
assert_eq!(fingerprint.len(), 64);
assert_eq!(digest.len(), 64);
assert!(!fingerprint.contains(email));
assert!(!digest.contains(email));
assert!(!digest.contains(&code));
}
#[test]
fn config_debug_redacts_the_secret() {
let config = EmailVerificationConfig {
redis_key_prefix: "app:test:registration-email".to_string(),
secret: "independent-email-verification-secret-32-bytes".to_string(),
ttl_seconds: 600,
resend_cooldown_seconds: 60,
max_attempts: 5,
code_digits: CODE_DIGITS,
send_window_seconds: 3600,
send_ip_attempts: 20,
send_email_attempts: 5,
send_global_attempts: 1000,
send_metric_name: "test_registration_email_total",
verify_metric_name: "test_registration_email_verify_total",
};
let debug = format!("{config:?}");
assert!(!debug.contains("independent-email-verification-secret"));
assert!(debug.contains("[REDACTED]"));
}
}