use super::{Credential, CredentialModel, CredentialType};
use crate::constants::DaoKeyPrefix;
use crate::dao::GarrisonDao;
use crate::error::{GarrisonError, GarrisonResult};
use crate::secure::ct_eq::constant_time_eq;
use async_trait::async_trait;
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
const CODE_COUNT: usize = 10;
const CODE_BYTES: usize = 8;
#[derive(Debug, Clone, Serialize, Deserialize)]
struct BackupCodeSecretData {
codes: Vec<String>,
}
impl BackupCodeSecretData {
fn from_json(secret_data: &str) -> GarrisonResult<Self> {
serde_json::from_str(secret_data)
.map_err(|e| GarrisonError::InvalidParam(format!("account-backup-deserialize::{}", e)))
}
}
fn sha256_hex(input: &str) -> String {
let mut hasher = Sha256::new();
hasher.update(input.as_bytes());
let result = hasher.finalize();
result.iter().map(|b| format!("{:02x}", b)).collect()
}
fn normalize(input: &str) -> String {
input.to_uppercase().replace('-', "")
}
fn format_code(base32_str: &str) -> String {
format!(
"{}-{}-{}",
&base32_str[..4],
&base32_str[4..8],
&base32_str[8..12]
)
}
#[cfg_attr(
feature = "credential-zeroize",
derive(zeroize::Zeroize, zeroize::ZeroizeOnDrop)
)]
pub struct BackupCodeCredential {
model: CredentialModel,
}
impl BackupCodeCredential {
pub fn new(model: CredentialModel) -> Self {
Self { model }
}
pub fn generate(login_id: &str) -> GarrisonResult<(BackupCodeCredential, Vec<String>)> {
let mut codes = Vec::with_capacity(CODE_COUNT);
let mut hashes = Vec::with_capacity(CODE_COUNT);
for _ in 0..CODE_COUNT {
let mut bytes = [0u8; CODE_BYTES];
getrandom::fill(&mut bytes).expect("OS CSPRNG 不可用");
let encoded = base32::encode(base32::Alphabet::Rfc4648 { padding: false }, &bytes);
let formatted = format_code(&encoded);
let normalized = normalize(&formatted);
codes.push(formatted);
hashes.push(sha256_hex(&normalized));
}
let secret_data = serde_json::to_string(&BackupCodeSecretData { codes: hashes })
.map_err(|e| GarrisonError::Internal(format!("account-backup-serialize::{}", e)))?;
let model = CredentialModel {
id: uuid::Uuid::new_v4().to_string(),
user_id: login_id.to_string(),
credential_type: "backup_code".to_string(),
secret_data,
label: None,
created_at: chrono::Utc::now().timestamp(),
enabled: true,
priority: 0,
};
Ok((BackupCodeCredential { model }, codes))
}
#[tracing::instrument(skip(self, input, dao), fields(user_id = %self.model.user_id))]
pub async fn verify_and_consume(
&mut self,
input: &str,
dao: &dyn GarrisonDao,
) -> GarrisonResult<bool> {
const MAX_CAS_RETRIES: u32 = 5;
let key = format!(
"{}{}:{}",
DaoKeyPrefix::Cred,
self.model.user_id,
self.model.id
);
let input_hash = sha256_hex(&normalize(input));
for attempt in 0..MAX_CAS_RETRIES {
let old_json = match dao.get(&key).await? {
Some(j) => j,
None => {
return Err(GarrisonError::InvalidParam(format!(
"credential-backup-code-not-found::{}",
key
)))
},
};
let model: CredentialModel = serde_json::from_str(&old_json)
.map_err(|e| GarrisonError::Internal(format!("account-cred-deserialize::{}", e)))?;
let mut data = BackupCodeSecretData::from_json(&model.secret_data)?;
if let Some(idx) = data
.codes
.iter()
.position(|h| constant_time_eq(h.as_bytes(), input_hash.as_bytes()))
{
data.codes.remove(idx);
let new_secret = serde_json::to_string(&data).map_err(|e| {
GarrisonError::Internal(format!("account-backup-serialize::{}", e))
})?;
let mut updated_model = model.clone();
updated_model.secret_data = new_secret.clone();
let updated_json = serde_json::to_string(&updated_model).map_err(|e| {
GarrisonError::Internal(format!("account-cred-serialize::{}", e))
})?;
if dao
.compare_and_swap(&key, Some(&old_json), &updated_json, 0)
.await?
{
self.model.secret_data = new_secret;
tracing::info!(
user_id = %self.model.user_id,
remaining = data.codes.len(),
attempt = attempt + 1,
"backup code consumed via atomic CAS"
);
return Ok(true);
}
tracing::debug!(
attempt = attempt + 1,
max_retries = MAX_CAS_RETRIES,
"CAS conflict on backup code consume, retrying"
);
} else {
return Ok(false);
}
}
Err(GarrisonError::Internal(format!(
"backup_code CAS retry exhausted after {} attempts: {}",
MAX_CAS_RETRIES, key
)))
}
}
#[async_trait]
impl Credential for BackupCodeCredential {
fn credential_type(&self) -> CredentialType {
"backup_code"
}
fn to_model(&self) -> CredentialModel {
self.model.clone()
}
async fn verify(&self, input: &str) -> GarrisonResult<bool> {
let data = BackupCodeSecretData::from_json(&self.model.secret_data)?;
let input_hash = sha256_hex(&normalize(input));
Ok(data
.codes
.iter()
.any(|h| constant_time_eq(h.as_bytes(), input_hash.as_bytes())))
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::dao::tests::MockDao;
async fn store_in_dao(cred: &BackupCodeCredential, dao: &MockDao) {
let model = cred.to_model();
let key = format!("cred:{}:{}", model.user_id, model.id);
let json = serde_json::to_string(&model).expect("序列化应成功");
dao.set_permanent(&key, &json)
.await
.expect("DAO 写入应成功");
}
#[test]
fn generate_returns_10_codes() {
let (cred, codes) = BackupCodeCredential::generate("alice").expect("generate 应成功");
assert_eq!(codes.len(), 10, "应生成 10 个备份码");
assert_eq!(
cred.credential_type(),
"backup_code",
"credential_type 应为 backup_code"
);
}
#[test]
fn generate_codes_have_correct_format() {
let (_, codes) = BackupCodeCredential::generate("alice").expect("generate 应成功");
for code in &codes {
assert_eq!(
code.len(),
14,
"备份码应为 14 字符(XXXX-XXXX-XXXX),实际: {}",
code
);
let parts: Vec<&str> = code.split('-').collect();
assert_eq!(parts.len(), 3, "备份码应有 3 段,实际: {}", code);
for part in &parts {
assert_eq!(part.len(), 4, "每段应为 4 字符,实际: {}", part);
assert!(
part.chars()
.all(|c| c.is_ascii_uppercase() || c.is_ascii_digit()),
"每段应为 Base32 字符(A-Z, 2-7),实际: {}",
part
);
}
}
}
#[test]
fn generate_codes_are_unique() {
let (_, codes) = BackupCodeCredential::generate("alice").expect("generate 应成功");
let unique: std::collections::HashSet<_> = codes.iter().collect();
assert_eq!(unique.len(), 10, "10 个备份码应互不重复");
}
#[test]
fn credential_type_returns_backup_code() {
let (cred, _) = BackupCodeCredential::generate("alice").expect("generate 应成功");
assert_eq!(cred.credential_type(), "backup_code");
}
#[test]
fn to_model_returns_original() {
let (cred, _) = BackupCodeCredential::generate("alice").expect("generate 应成功");
let model = cred.to_model();
assert_eq!(model.user_id, "alice");
assert_eq!(model.credential_type, "backup_code");
assert!(model.secret_data.contains("codes"));
assert!(model.enabled);
}
#[tokio::test]
async fn verify_and_consume_correct_code() {
let (mut cred, codes) = BackupCodeCredential::generate("alice").expect("generate 应成功");
let dao = MockDao::new();
store_in_dao(&cred, &dao).await;
let result = cred
.verify_and_consume(&codes[0], &dao)
.await
.expect("verify_and_consume 应成功");
assert!(result, "正确备份码应校验通过");
}
#[tokio::test]
async fn verify_and_consume_rejects_used_code() {
let (mut cred, codes) = BackupCodeCredential::generate("alice").expect("generate 应成功");
let dao = MockDao::new();
store_in_dao(&cred, &dao).await;
let first = cred
.verify_and_consume(&codes[0], &dao)
.await
.expect("首次校验应成功");
assert!(first, "首次应通过");
let second = cred
.verify_and_consume(&codes[0], &dao)
.await
.expect("二次校验应成功");
assert!(!second, "已使用的备份码应被拒绝(一次性使用)");
}
#[tokio::test]
async fn verify_and_consume_wrong_code_returns_false() {
let (mut cred, _) = BackupCodeCredential::generate("alice").expect("generate 应成功");
let dao = MockDao::new();
store_in_dao(&cred, &dao).await;
let result = cred
.verify_and_consume("WRONG-CODE-XXXX", &dao)
.await
.expect("verify_and_consume 应成功");
assert!(!result, "错误备份码应返回 false");
}
#[tokio::test]
async fn verify_and_consume_normalizes_input() {
let (mut cred, codes) = BackupCodeCredential::generate("alice").expect("generate 应成功");
let dao = MockDao::new();
store_in_dao(&cred, &dao).await;
let normalized = codes[0].replace('-', "");
let result = cred
.verify_and_consume(&normalized, &dao)
.await
.expect("verify_and_consume 应成功");
assert!(result, "不含连字符的输入应校验通过");
}
#[tokio::test]
async fn verify_and_consume_lowercase_input() {
let (mut cred, codes) = BackupCodeCredential::generate("alice").expect("generate 应成功");
let dao = MockDao::new();
store_in_dao(&cred, &dao).await;
let lower = codes[0].to_lowercase();
let result = cred
.verify_and_consume(&lower, &dao)
.await
.expect("verify_and_consume 应成功");
assert!(result, "小写输入应校验通过(规范化转大写)");
}
#[tokio::test]
async fn verify_correct_code() {
let (cred, codes) = BackupCodeCredential::generate("alice").expect("generate 应成功");
let result = cred.verify(&codes[0]).await.expect("verify 应成功");
assert!(result, "正确备份码应校验通过");
}
#[tokio::test]
async fn verify_wrong_code() {
let (cred, _) = BackupCodeCredential::generate("alice").expect("generate 应成功");
let result = cred.verify("WRONG-CODE-XXXX").await.expect("verify 应成功");
assert!(!result, "错误备份码应返回 false");
}
#[tokio::test]
async fn verify_does_not_consume() {
let (cred, codes) = BackupCodeCredential::generate("alice").expect("generate 应成功");
let dao = MockDao::new();
store_in_dao(&cred, &dao).await;
let verify_result = cred.verify(&codes[0]).await.expect("verify 应成功");
assert!(verify_result, "verify 应通过");
let mut cred = cred;
let consume_result = cred
.verify_and_consume(&codes[0], &dao)
.await
.expect("verify_and_consume 应成功");
assert!(consume_result, "verify 不应消费备份码");
}
#[tokio::test]
async fn verify_sees_consumption_by_same_instance() {
let (mut cred, codes) = BackupCodeCredential::generate("alice").expect("generate 应成功");
let dao = MockDao::new();
store_in_dao(&cred, &dao).await;
let consumed = cred
.verify_and_consume(&codes[0], &dao)
.await
.expect("verify_and_consume 应成功");
assert!(consumed, "首次消费应通过");
let verify_consumed = cred.verify(&codes[0]).await.expect("verify 应成功");
assert!(
!verify_consumed,
"已消费码 verify 应返回 false(内存快照已同步)"
);
let verify_remaining = cred.verify(&codes[1]).await.expect("verify 应成功");
assert!(verify_remaining, "未消费码 verify 应仍返回 true");
}
#[test]
fn constant_time_eq_comparison_semantics() {
let h = sha256_hex("AAAA-AAAA-AAAA");
assert!(
constant_time_eq(h.as_bytes(), h.as_bytes()),
"相同哈希应相等"
);
assert!(
!constant_time_eq(h.as_bytes(), sha256_hex("BBBB-BBBB-BBBB").as_bytes()),
"不同哈希应不等"
);
assert!(
!constant_time_eq(h.as_bytes(), b"short"),
"长度不等应返回 false"
);
assert!(constant_time_eq(b"", b""), "空串应相等");
}
#[tokio::test]
async fn usable_as_dyn_credential() {
let (cred, codes) = BackupCodeCredential::generate("alice").expect("generate 应成功");
let dyn_cred: Box<dyn Credential> = Box::new(cred);
assert_eq!(dyn_cred.credential_type(), "backup_code");
let result = dyn_cred.verify(&codes[0]).await.expect("verify 应成功");
assert!(result, "dyn Credential 正确备份码应校验通过");
}
#[tokio::test]
async fn invalid_secret_data_returns_error() {
let model = CredentialModel {
id: "bad".to_string(),
user_id: "alice".to_string(),
credential_type: "backup_code".to_string(),
secret_data: "not-json".to_string(),
label: None,
created_at: 0,
enabled: true,
priority: 0,
};
let cred = BackupCodeCredential::new(model);
let result = cred.verify("XXXX-XXXX-XXXX").await;
assert!(result.is_err(), "非法 secret_data 应返回错误");
}
#[tokio::test]
async fn consume_all_codes_then_reject() {
let (mut cred, codes) = BackupCodeCredential::generate("alice").expect("generate 应成功");
let dao = MockDao::new();
store_in_dao(&cred, &dao).await;
for code in &codes {
let result = cred
.verify_and_consume(code, &dao)
.await
.expect("verify_and_consume 应成功");
assert!(result, "每个备份码首次使用应通过: {}", code);
}
let result = cred
.verify_and_consume(&codes[0], &dao)
.await
.expect("verify_and_consume 应成功");
assert!(!result, "全部消费后应返回 false");
}
#[tokio::test]
async fn concurrent_consume_same_code_only_one_succeeds() {
use std::sync::Arc;
let (cred, codes) = BackupCodeCredential::generate("alice").expect("generate 应成功");
let mock_dao = MockDao::new();
store_in_dao(&cred, &mock_dao).await;
let dao: Arc<dyn GarrisonDao> = Arc::new(mock_dao);
let code = codes[0].clone();
let mut cred1 = BackupCodeCredential::new(cred.to_model());
let mut cred2 = BackupCodeCredential::new(cred.to_model());
let dao1 = dao.clone();
let dao2 = dao.clone();
let code1 = code.clone();
let code2 = code.clone();
let (r1, r2) = tokio::join!(
cred1.verify_and_consume(&code1, dao1.as_ref()),
cred2.verify_and_consume(&code2, dao2.as_ref()),
);
let ok1 = r1.expect("调用 1 不应报错");
let ok2 = r2.expect("调用 2 不应报错");
assert!(
ok1 ^ ok2,
"并发消费同一备份码应仅一个成功(XOR),实际: ok1={}, ok2={}",
ok1,
ok2
);
}
}