use crate::dao::GarrisonDao;
use crate::error::{GarrisonError, GarrisonResult};
#[cfg(feature = "listener")]
use crate::listener::{GarrisonEvent, GarrisonListenerManager};
use std::sync::Arc;
use std::time::{SystemTime, UNIX_EPOCH};
use uuid::Uuid;
use super::{ApiKeyHandler, ApiKeyInfo};
const LAST_USED_UPDATE_THROTTLE_SECS: i64 = 60;
pub(crate) fn default_namespace() -> String {
"default".to_string()
}
fn sha256_hex(input: &str) -> String {
use sha2::{Digest, Sha256};
use std::fmt::Write;
let mut hasher = Sha256::new();
hasher.update(input.as_bytes());
let digest = hasher.finalize();
let mut out = String::with_capacity(64);
for byte in digest {
let _ = write!(out, "{:02x}", byte);
}
out
}
pub(crate) fn idx_key_for(key_id: &str) -> String {
format!("garrison:apikey:idx:{}", key_id)
}
#[cfg(feature = "listener")]
pub(crate) fn public_key_ref(key: &str) -> String {
match key.split_once('.') {
Some((key_id, _)) => key_id.to_string(),
None => {
let prefix: String = key.chars().take(8).collect();
format!("{}\u{2026}", prefix)
},
}
}
fn validate_namespace(namespace: &str) -> GarrisonResult<()> {
if namespace.is_empty() {
return Err(GarrisonError::InvalidParam(
"apikey-namespace-empty".to_string(),
));
}
if namespace.len() > 64 {
return Err(GarrisonError::InvalidParam(format!(
"apikey-namespace-too-long::{}",
namespace.len()
)));
}
if !namespace
.chars()
.all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-')
{
return Err(GarrisonError::InvalidParam(format!(
"apikey-namespace-invalid-chars::{}",
namespace
)));
}
if namespace == "idx" {
return Err(GarrisonError::InvalidParam(
"apikey-namespace-reserved::idx".to_string(),
));
}
Ok(())
}
impl ApiKeyHandler {
pub fn new(dao: Arc<dyn GarrisonDao>) -> Self {
Self {
dao,
#[cfg(feature = "listener")]
listener_manager: None,
allowed_scopes: None,
track_last_used: false,
}
}
#[cfg(feature = "listener")]
pub fn with_listener_manager(mut self, lm: Arc<GarrisonListenerManager>) -> Self {
self.listener_manager = Some(lm);
self
}
pub fn with_allowed_scopes(mut self, allowed: Vec<String>) -> Self {
self.allowed_scopes = Some(allowed);
self
}
pub fn with_last_used_tracking(mut self, enabled: bool) -> Self {
self.track_last_used = enabled;
self
}
pub async fn generate(
&self,
login_id: impl Into<String>,
scopes: Vec<String>,
timeout: i64,
) -> GarrisonResult<String> {
self.generate_internal(login_id, &default_namespace(), scopes, timeout, None, None)
.await
}
pub async fn generate_with_namespace(
&self,
login_id: impl Into<String>,
namespace: &str,
scopes: Vec<String>,
timeout: i64,
) -> GarrisonResult<String> {
self.generate_internal(login_id, namespace, scopes, timeout, None, None)
.await
}
pub async fn generate_with_options(
&self,
login_id: impl Into<String>,
namespace: &str,
scopes: Vec<String>,
timeout: i64,
owner_id: Option<String>,
rate_limit: Option<u32>,
) -> GarrisonResult<String> {
self.generate_internal(login_id, namespace, scopes, timeout, owner_id, rate_limit)
.await
}
async fn generate_internal(
&self,
login_id: impl Into<String>,
namespace: &str,
scopes: Vec<String>,
timeout: i64,
owner_id: Option<String>,
rate_limit: Option<u32>,
) -> GarrisonResult<String> {
let login_id: String = login_id.into();
if timeout <= 0 {
return Err(GarrisonError::InvalidParam(
"apikey-timeout-positive".to_string(),
));
}
validate_namespace(namespace)?;
if let Some(allowed) = &self.allowed_scopes {
for scope in &scopes {
if !allowed.iter().any(|a| a == scope) {
return Err(GarrisonError::InvalidParam(format!(
"apikey-scope-not-allowed::{}",
scope
)));
}
}
}
let now = current_ts()?;
let key_id = Uuid::new_v4().simple().to_string();
let key_secret = Uuid::new_v4().simple().to_string();
let info = ApiKeyInfo {
login_id: login_id.clone(),
scopes,
expire_at: now + timeout,
revoked: false,
namespace: namespace.to_string(),
key_id: key_id.clone(),
secret_hash: sha256_hex(&key_secret),
owner_id: owner_id.or(Some(login_id)),
last_used_at: None,
rate_limit,
};
let value = serde_json::to_string(&info)
.map_err(|e| GarrisonError::Internal(format!("apikey-serialize::{}", e)))?;
let dao_key = format!("garrison:apikey:{}:{}", namespace, key_id);
self.dao.set(&dao_key, &value, timeout as u64).await?;
let idx_key = idx_key_for(&key_id);
self.dao.set(&idx_key, &dao_key, timeout as u64).await?;
Ok(format!("{}.{}", key_id, key_secret))
}
pub async fn verify(&self, key: &str) -> GarrisonResult<ApiKeyInfo> {
let (dao_key, value, secret) = self.lookup(key).await?;
let info = self.decode_and_check(&value, secret.as_deref())?;
self.maybe_touch_last_used(&dao_key, &info).await;
Ok(info)
}
pub async fn verify_with_namespace(
&self,
key: &str,
namespace: &str,
) -> GarrisonResult<ApiKeyInfo> {
validate_namespace(namespace)?;
let (dao_key, value, secret) =
match key.split_once('.') {
Some((key_id, key_secret)) => {
let dao_key = format!("garrison:apikey:{}:{}", namespace, key_id);
let value = self.dao.get(&dao_key).await?.ok_or_else(|| {
GarrisonError::InvalidToken("apikey-not-found".to_string())
})?;
(dao_key, value, Some(key_secret.to_string()))
},
None => {
let dao_key = format!("garrison:apikey:{}:{}", namespace, key);
let value = self.dao.get(&dao_key).await?.ok_or_else(|| {
GarrisonError::InvalidToken("apikey-not-found".to_string())
})?;
(dao_key, value, None)
},
};
let info = self.decode_and_check(&value, secret.as_deref())?;
if info.namespace != namespace {
return Err(GarrisonError::InvalidToken(format!(
"apikey-namespace-mismatch::{}::{}",
namespace, info.namespace
)));
}
self.maybe_touch_last_used(&dao_key, &info).await;
Ok(info)
}
async fn lookup(&self, key: &str) -> GarrisonResult<(String, String, Option<String>)> {
if let Some((key_id, key_secret)) = key.split_once('.') {
let idx_key = idx_key_for(key_id);
if let Some(dao_key) = self.dao.get(&idx_key).await? {
if let Some(value) = self.dao.get(&dao_key).await? {
return Ok((dao_key, value, Some(key_secret.to_string())));
}
}
}
let idx_key = idx_key_for(key);
if let Some(dao_key) = self.dao.get(&idx_key).await? {
if let Some(value) = self.dao.get(&dao_key).await? {
return Ok((dao_key, value, None));
}
}
let old_dao_key = format!("garrison:apikey:{}", key);
if let Some(value) = self.dao.get(&old_dao_key).await? {
return Ok((old_dao_key, value, None));
}
Err(GarrisonError::InvalidToken("apikey-not-found".to_string()))
}
fn decode_and_check(&self, value: &str, secret: Option<&str>) -> GarrisonResult<ApiKeyInfo> {
let info: ApiKeyInfo = serde_json::from_str(value)
.map_err(|e| GarrisonError::Internal(format!("apikey-deserialize::{}", e)))?;
if info.revoked {
return Err(GarrisonError::InvalidToken("apikey-revoked".to_string()));
}
let now = current_ts()?;
if info.expire_at <= now {
return Err(GarrisonError::ExpiredToken("apikey-expired".to_string()));
}
if !info.secret_hash.is_empty() {
let provided = secret
.ok_or_else(|| GarrisonError::InvalidToken("apikey-secret-missing".to_string()))?;
let computed = sha256_hex(provided);
if !crate::secure::ct_eq::constant_time_eq(
computed.as_bytes(),
info.secret_hash.as_bytes(),
) {
return Err(GarrisonError::InvalidToken(
"apikey-secret-mismatch".to_string(),
));
}
} else {
tracing::warn!(
"apikey legacy empty-secret-hash rejected (login_id={}, namespace={}); \
migrate to v0.7.x dual-segment key format",
info.login_id,
info.namespace
);
return Err(GarrisonError::InvalidToken(
"apikey-legacy-secret-required".to_string(),
));
}
Ok(info)
}
async fn maybe_touch_last_used(&self, dao_key: &str, info: &ApiKeyInfo) {
if !self.track_last_used {
return;
}
let now = match current_ts() {
Ok(n) => n,
Err(_) => return,
};
let stale = info
.last_used_at
.is_none_or(|t| now - t > LAST_USED_UPDATE_THROTTLE_SECS);
if !stale {
return;
}
let current = match self.dao.get(dao_key).await {
Ok(Some(v)) => v,
Ok(None) => return, Err(e) => {
tracing::warn!(dao_key = %dao_key, error = %e, "apikey last_used_at re-read 失败(不影响校验)");
return;
},
};
let mut updated: ApiKeyInfo = match serde_json::from_str(¤t) {
Ok(i) => i,
Err(e) => {
tracing::warn!(error = %e, "apikey last_used_at 反序列化失败(不影响校验)");
return;
},
};
if updated.revoked {
return;
}
updated.last_used_at = Some(now);
match serde_json::to_string(&updated) {
Ok(v) => {
if let Err(e) = self.dao.update(dao_key, &v).await {
tracing::warn!(dao_key = %dao_key, error = %e, "apikey last_used_at 更新失败(不影响校验)");
}
},
Err(e) => {
tracing::warn!(error = %e, "apikey last_used_at 序列化失败(不影响校验)");
},
}
}
pub async fn revoke(&self, key: &str) -> GarrisonResult<()> {
let (dao_key, _value, _secret) = self.lookup(key).await?;
self.revoke_at(&dao_key).await
}
async fn revoke_at(&self, dao_key: &str) -> GarrisonResult<()> {
let value = self.dao.get(dao_key).await?;
let value =
value.ok_or_else(|| GarrisonError::InvalidToken("apikey-not-found".to_string()))?;
let mut info: ApiKeyInfo = serde_json::from_str(&value)
.map_err(|e| GarrisonError::Internal(format!("apikey-deserialize::{}", e)))?;
info.revoked = true;
let new_value = serde_json::to_string(&info)
.map_err(|e| GarrisonError::Internal(format!("apikey-serialize::{}", e)))?;
self.dao.update(dao_key, &new_value).await
}
pub async fn list_by_namespace(&self, namespace: &str) -> GarrisonResult<Vec<ApiKeyInfo>> {
validate_namespace(namespace)?;
let pattern = format!("garrison:apikey:{}:*", namespace);
let dao_keys = self.dao.keys(&pattern).await?;
let mut result = Vec::with_capacity(dao_keys.len());
for dao_key in dao_keys {
let value = self.dao.get(&dao_key).await?;
if let Some(v) = value {
let info: ApiKeyInfo = serde_json::from_str(&v)
.map_err(|e| GarrisonError::Internal(format!("apikey-deserialize::{}", e)))?;
if !info.revoked {
result.push(info);
}
}
}
Ok(result)
}
pub async fn get_keys_older_than(
&self,
namespace: &str,
cutoff_ts: i64,
) -> GarrisonResult<Vec<ApiKeyInfo>> {
let all = self.list_by_namespace(namespace).await?;
Ok(all
.into_iter()
.filter(|info| info.last_used_at.is_none_or(|t| t < cutoff_ts))
.collect())
}
pub async fn update_last_used(&self, key: &str) -> GarrisonResult<()> {
let (dao_key, value, _secret) = self.lookup(key).await?;
let mut info: ApiKeyInfo = serde_json::from_str(&value)
.map_err(|e| GarrisonError::Internal(format!("apikey-deserialize::{}", e)))?;
if info.revoked {
return Err(GarrisonError::InvalidToken("apikey-revoked".to_string()));
}
let now = current_ts()?;
if info.expire_at <= now {
return Err(GarrisonError::ExpiredToken("apikey-expired".to_string()));
}
info.last_used_at = Some(now);
let new_value = serde_json::to_string(&info)
.map_err(|e| GarrisonError::Internal(format!("apikey-serialize::{}", e)))?;
self.dao.update(&dao_key, &new_value).await
}
pub async fn rotate(&self, old_key: &str) -> GarrisonResult<String> {
let info = self.verify(old_key).await?;
self.revoke(old_key).await?;
let now = current_ts()?;
let remaining_ttl = info.expire_at - now;
if remaining_ttl <= 0 {
return Err(GarrisonError::ExpiredToken(
"apikey-expired-cannot-rotate".to_string(),
));
}
let new_key = self
.generate_internal(
info.login_id,
&info.namespace,
info.scopes,
remaining_ttl,
info.owner_id,
info.rate_limit,
)
.await?;
#[cfg(feature = "listener")]
if let Some(lm) = &self.listener_manager {
lm.broadcast(&GarrisonEvent::TokenRotate {
old_key: public_key_ref(old_key),
new_key: public_key_ref(&new_key),
request_context: None,
})
.await;
}
Ok(new_key)
}
}
fn current_ts() -> GarrisonResult<i64> {
SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|d| d.as_secs() as i64)
.map_err(|e| GarrisonError::Internal(format!("apikey-clock::{}", e)))
}
#[cfg(test)]
mod lost_revoke_tests {
use super::super::mock::MockDao;
use super::{ApiKeyHandler, ApiKeyInfo};
use crate::dao::GarrisonDao;
use crate::error::GarrisonError;
use std::sync::Arc;
#[tokio::test]
async fn maybe_touch_does_not_resurrect_revoked_key() {
let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
let handler = ApiKeyHandler::new(dao.clone()).with_last_used_tracking(true);
let token = handler
.generate("user1", vec!["read".to_string()], 3600)
.await
.unwrap();
let (key_id, _) = token.split_once('.').unwrap();
let dao_key = format!("garrison:apikey:default:{}", key_id);
handler.revoke(&token).await.unwrap();
let mut stale: ApiKeyInfo =
serde_json::from_str(&dao.get(&dao_key).await.unwrap().unwrap()).unwrap();
stale.revoked = false;
stale.last_used_at = None;
handler.maybe_touch_last_used(&dao_key, &stale).await;
let after: ApiKeyInfo =
serde_json::from_str(&dao.get(&dao_key).await.unwrap().unwrap()).unwrap();
assert!(
after.revoked,
"maybe_touch_last_used 不得复活已吊销的 key(lost-revoke)"
);
}
#[tokio::test]
async fn update_last_used_rejects_revoked_key() {
let dao: Arc<dyn GarrisonDao> = Arc::new(MockDao::new());
let handler = ApiKeyHandler::new(dao).with_last_used_tracking(true);
let token = handler.generate("user1", vec![], 3600).await.unwrap();
handler.revoke(&token).await.unwrap();
let err = handler.update_last_used(&token).await.unwrap_err();
assert!(
matches!(err, GarrisonError::InvalidToken(_)),
"revoked key 的 update_last_used 应返回 InvalidToken,got: {:?}",
err
);
}
}