use crate::errors::{AuthError, Result};
use crate::storage::{AuthStorage, SessionData};
use crate::tokens::AuthToken;
use aes_gcm::{
Aes256Gcm, Key, KeyInit, Nonce,
aead::{Aead, Payload},
};
use base64::{Engine, engine::general_purpose::STANDARD as BASE64};
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::env;
use std::fs;
use std::time::Duration;
use zeroize::Zeroize;
#[cfg(test)]
pub(crate) static TEST_ENCRYPTION_ENV_LOCK: tokio::sync::Mutex<()> =
tokio::sync::Mutex::const_new(());
#[cfg(test)]
pub(crate) struct EncryptionEnvGuard;
#[cfg(test)]
impl EncryptionEnvGuard {
pub(crate) fn set(key: &str) -> Self {
unsafe {
std::env::set_var("AUTH_STORAGE_ENCRYPTION_KEY", key);
std::env::remove_var("AUTH_STORAGE_ENCRYPTION_KEYS_FILE");
}
Self
}
}
#[cfg(test)]
impl Drop for EncryptionEnvGuard {
fn drop(&mut self) {
unsafe {
std::env::remove_var("AUTH_STORAGE_ENCRYPTION_KEY");
}
}
}
const CURRENT_FORMAT_VERSION: u8 = 2;
const FORMAT_V1: u8 = 1;
const ALGORITHM: &str = "AES-256-GCM";
const DECRYPT_FAILED: &str = "Decryption failed";
fn bound_aad(v: u8, algorithm: &str, key_id: &str, record_aad: &[u8]) -> Vec<u8> {
let mut out = Vec::with_capacity(48 + algorithm.len() + key_id.len() + record_aad.len());
out.extend_from_slice(b"auth-framework/storage-envelope");
out.push(v);
for part in [algorithm.as_bytes(), key_id.as_bytes(), record_aad] {
out.extend_from_slice(&(part.len() as u32).to_be_bytes());
out.extend_from_slice(part);
}
out
}
fn default_format_version() -> u8 {
0
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EncryptedData {
pub data: String,
pub nonce: String,
pub algorithm: String,
#[serde(default)]
pub key_id: String,
#[serde(default = "default_format_version")]
pub v: u8,
#[serde(default)]
pub key_derivation: String,
}
pub trait KeyProvider: Send + Sync {
fn load_keys(&self) -> Result<LoadedKeys>;
}
pub struct LoadedKeys {
pub current_key_id: String,
pub keys: HashMap<String, [u8; 32]>,
}
pub struct EnvKeyProvider;
impl KeyProvider for EnvKeyProvider {
fn load_keys(&self) -> Result<LoadedKeys> {
if let Ok(path) = env::var("AUTH_STORAGE_ENCRYPTION_KEYS_FILE") {
return Self::load_from_file(&path);
}
let mut key_data = env::var("AUTH_STORAGE_ENCRYPTION_KEY").map_err(|_| {
AuthError::config(
"No storage encryption key configured: set AUTH_STORAGE_ENCRYPTION_KEY \
(or AUTH_STORAGE_ENCRYPTION_KEYS_FILE for multi-key rotation). \
Refusing to start rather than silently storing data unencrypted.",
)
})?;
let key_id = env::var("AUTH_STORAGE_ENCRYPTION_KEY_ID").unwrap_or_else(|_| "1".to_string());
let key = decode_key(&key_data);
key_data.zeroize();
let key = key?;
let mut keys = HashMap::new();
keys.insert(key_id.clone(), key);
Ok(LoadedKeys {
current_key_id: key_id,
keys,
})
}
}
impl EnvKeyProvider {
fn load_from_file(path: &str) -> Result<LoadedKeys> {
#[derive(Deserialize)]
struct KeysFile {
current: String,
keys: HashMap<String, String>,
}
check_keys_file_permissions(path, strict_permissions_requested())?;
let mut contents = fs::read_to_string(path).map_err(|e| {
AuthError::config(format!(
"Failed to read AUTH_STORAGE_ENCRYPTION_KEYS_FILE '{path}': {e}"
))
})?;
let parsed: Result<KeysFile> = serde_json::from_str(&contents).map_err(|e| {
AuthError::config(format!(
"Failed to parse AUTH_STORAGE_ENCRYPTION_KEYS_FILE '{path}': {e}"
))
});
contents.zeroize();
let mut parsed = parsed?;
if !parsed.keys.contains_key(&parsed.current) {
for encoded in parsed.keys.values_mut() {
encoded.zeroize();
}
return Err(AuthError::config(format!(
"AUTH_STORAGE_ENCRYPTION_KEYS_FILE '{path}': current key id '{}' \
is not present in 'keys'",
parsed.current
)));
}
let mut keys = HashMap::with_capacity(parsed.keys.len());
let mut first_error = None;
for (id, mut encoded) in parsed.keys {
match decode_key(&encoded) {
Ok(key) => {
keys.insert(id, key);
}
Err(e) if first_error.is_none() => {
first_error = Some(e);
}
Err(_) => {}
}
encoded.zeroize();
}
if let Some(error) = first_error {
for key_bytes in keys.values_mut() {
key_bytes.zeroize();
}
return Err(error);
}
Ok(LoadedKeys {
current_key_id: parsed.current,
keys,
})
}
}
const STRICT_KEY_FILE_PERMISSIONS_ENV: &str = "AUTH_STORAGE_ENCRYPTION_STRICT_KEY_FILE_PERMISSIONS";
#[cfg_attr(not(unix), allow(dead_code))]
fn keys_file_mode_too_open(mode: u32) -> bool {
mode & 0o077 != 0
}
fn strict_permissions_requested() -> bool {
env::var(STRICT_KEY_FILE_PERMISSIONS_ENV)
.map(|value| {
matches!(
value.trim().to_ascii_lowercase().as_str(),
"1" | "true" | "yes"
)
})
.unwrap_or(false)
}
fn check_keys_file_permissions(path: &str, strict: bool) -> Result<()> {
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt;
if let Ok(metadata) = fs::metadata(path) {
let mode = metadata.permissions().mode();
if keys_file_mode_too_open(mode) {
if strict {
return Err(AuthError::config(format!(
"AUTH_STORAGE_ENCRYPTION_KEYS_FILE '{path}' has mode {:o}: it is \
accessible to group or other. Restrict it to the owner (chmod 600) \
or unset {STRICT_KEY_FILE_PERMISSIONS_ENV}.",
mode & 0o777
)));
}
tracing::warn!(
path = path,
mode = format!("{mode:o}"),
"AUTH_STORAGE_ENCRYPTION_KEYS_FILE is readable by group or other -- \
restrict it to the owner only (chmod 600), or set \
{STRICT_KEY_FILE_PERMISSIONS_ENV}=1 to make this fatal."
);
}
}
}
#[cfg(not(unix))]
{
let _ = path;
if strict {
tracing::warn!(
"{STRICT_KEY_FILE_PERMISSIONS_ENV} is set but key-file permissions cannot be \
inspected on this platform; it is not enforced."
);
}
}
Ok(())
}
pub(crate) fn env_key_source_in_use() -> bool {
env::var("AUTH_STORAGE_ENCRYPTION_KEYS_FILE").is_err()
&& env::var("AUTH_STORAGE_ENCRYPTION_KEY").is_ok()
}
pub(crate) async fn stored_envelopes_exist<S: AuthStorage + ?Sized>(
storage: &S,
limit: usize,
) -> Result<bool> {
for key in storage.list_kv_keys("").await?.into_iter().take(limit) {
if let Some(raw) = storage.get_kv(&key).await?
&& StorageEncryption::looks_like_envelope(&raw)
{
return Ok(true);
}
}
Ok(false)
}
fn safe_log_id(key: &str) -> String {
use sha2::{Digest, Sha256};
let hash_hex = hex::encode(&Sha256::digest(key.as_bytes())[..8]);
match key.split_once(':') {
Some((namespace, _)) => format!("{namespace}:{hash_hex}"),
None => format!("key:{hash_hex}"),
}
}
fn decode_key(encoded: &str) -> Result<[u8; 32]> {
let mut key_bytes = BASE64
.decode(encoded)
.map_err(|_| AuthError::config("Invalid base64 in storage encryption key"))?;
if key_bytes.len() != 32 {
key_bytes.zeroize();
return Err(AuthError::config(
"Storage encryption key must be 32 bytes (256 bits) once base64-decoded",
));
}
let mut key = [0u8; 32];
key.copy_from_slice(&key_bytes);
key_bytes.zeroize();
Ok(key)
}
pub struct StorageEncryption {
current_key_id: String,
ciphers: HashMap<String, Aes256Gcm>,
}
impl StorageEncryption {
pub fn new(provider: &dyn KeyProvider) -> Result<Self> {
let mut loaded = provider.load_keys()?;
let validation_error = if loaded.current_key_id.is_empty() {
Some(AuthError::config(
"Key provider's current_key_id must not be empty",
))
} else if loaded.keys.keys().any(|id| id.is_empty()) {
Some(AuthError::config(
"Key provider returned a key with an empty id -- an empty id is reserved \
to mean \"format-version-0 envelope, no key id at all\"",
))
} else if !loaded.keys.contains_key(&loaded.current_key_id) {
Some(AuthError::config(format!(
"Key provider's current_key_id '{}' is not among the keys it loaded",
loaded.current_key_id
)))
} else {
None
};
if let Some(error) = validation_error {
for key_bytes in loaded.keys.values_mut() {
key_bytes.zeroize();
}
return Err(error);
}
let ciphers = loaded
.keys
.iter()
.map(|(id, key_bytes)| {
let key = Key::<Aes256Gcm>::from_slice(key_bytes);
(id.clone(), Aes256Gcm::new(key))
})
.collect();
for key_bytes in loaded.keys.values_mut() {
key_bytes.zeroize();
}
Ok(Self {
current_key_id: loaded.current_key_id,
ciphers,
})
}
pub fn from_env() -> Result<Self> {
Self::new(&EnvKeyProvider)
}
#[cfg(test)]
pub fn new_random() -> Self {
use rand::Rng;
let mut key_bytes = [0u8; 32];
rand::rng().fill_bytes(&mut key_bytes);
let key = Key::<Aes256Gcm>::from_slice(&key_bytes);
let mut ciphers = HashMap::new();
ciphers.insert("test".to_string(), Aes256Gcm::new(key));
key_bytes.zeroize();
Self {
current_key_id: "test".to_string(),
ciphers,
}
}
pub fn generate_key() -> String {
use rand::Rng;
let mut key_bytes = [0u8; 32];
rand::rng().fill_bytes(&mut key_bytes);
let encoded = BASE64.encode(key_bytes);
key_bytes.zeroize();
encoded
}
pub fn encrypt(&self, plaintext: &[u8], aad: &[u8]) -> Result<EncryptedData> {
use rand::Rng;
let cipher = self.ciphers.get(&self.current_key_id).ok_or_else(|| {
AuthError::internal("Current encryption key missing from loaded cipher set")
})?;
let mut nonce_bytes = [0u8; 12];
rand::rng().fill_bytes(&mut nonce_bytes);
let nonce = Nonce::from_slice(&nonce_bytes);
let bound = bound_aad(CURRENT_FORMAT_VERSION, ALGORITHM, &self.current_key_id, aad);
let ciphertext = cipher
.encrypt(
nonce,
Payload {
msg: plaintext,
aad: &bound,
},
)
.map_err(|e| AuthError::internal(format!("Encryption failed: {}", e)))?;
Ok(EncryptedData {
data: BASE64.encode(&ciphertext),
nonce: BASE64.encode(nonce_bytes),
algorithm: ALGORITHM.to_string(),
key_id: self.current_key_id.clone(),
v: CURRENT_FORMAT_VERSION,
key_derivation: String::new(),
})
}
pub fn decrypt(&self, encrypted: &EncryptedData, aad: &[u8]) -> Result<Vec<u8>> {
let fail = |why: &str| -> AuthError {
tracing::warn!(
key_id = ?encrypted.key_id.chars().take(64).collect::<String>(),
v = encrypted.v,
"storage envelope decryption failed: {why}"
);
AuthError::internal(DECRYPT_FAILED)
};
if encrypted.algorithm != ALGORITHM {
return Err(fail("unsupported algorithm"));
}
let ciphertext = BASE64
.decode(&encrypted.data)
.map_err(|_| fail("invalid base64 in data"))?;
let nonce_bytes = BASE64
.decode(&encrypted.nonce)
.map_err(|_| fail("invalid base64 in nonce"))?;
if nonce_bytes.len() != 12 {
return Err(fail("invalid nonce length"));
}
let nonce = Nonce::from_slice(&nonce_bytes);
if encrypted.v == 0 {
for id in self.sorted_key_ids() {
if let Some(cipher) = self.ciphers.get(&id)
&& let Ok(plaintext) = cipher.decrypt(
nonce,
Payload {
msg: &ciphertext,
aad: b"",
},
)
{
return Ok(plaintext);
}
}
return Err(fail("no loaded key opens this format-version-0 envelope"));
}
let cipher = self
.ciphers
.get(&encrypted.key_id)
.ok_or_else(|| fail("no loaded key for this key_id (rotated out?)"))?;
let bound;
let effective_aad: &[u8] = match encrypted.v {
FORMAT_V1 => aad,
CURRENT_FORMAT_VERSION => {
bound = bound_aad(encrypted.v, &encrypted.algorithm, &encrypted.key_id, aad);
&bound
}
_ => return Err(fail("unsupported envelope version")),
};
cipher
.decrypt(
nonce,
Payload {
msg: &ciphertext,
aad: effective_aad,
},
)
.map_err(|_| fail("authentication failed (wrong key, wrong record, or tampered)"))
}
pub fn encrypt_for_storage(&self, data: &[u8], aad: &[u8]) -> Result<Vec<u8>> {
let encrypted = self.encrypt(data, aad)?;
let serialized = serde_json::to_string(&encrypted).map_err(|e| {
AuthError::internal(format!("Failed to serialize encrypted data: {}", e))
})?;
Ok(serialized.into_bytes())
}
pub fn decrypt_from_storage(&self, data: &[u8], aad: &[u8]) -> Result<Vec<u8>> {
let parsed = std::str::from_utf8(data)
.map_err(|e| e.to_string())
.and_then(|s| serde_json::from_str::<EncryptedData>(s).map_err(|e| e.to_string()));
let encrypted = parsed.map_err(|why| {
tracing::warn!("stored value is not a readable envelope: {why}");
AuthError::internal(DECRYPT_FAILED)
})?;
self.decrypt(&encrypted, aad)
}
pub fn parse_envelope(data: &[u8]) -> Option<EncryptedData> {
let encrypted = std::str::from_utf8(data)
.ok()
.and_then(|s| serde_json::from_str::<EncryptedData>(s).ok())?;
if encrypted.algorithm != ALGORITHM {
return None;
}
let well_formed = if encrypted.v == 0 {
encrypted.key_id.is_empty()
} else {
!encrypted.key_id.is_empty()
};
well_formed.then_some(encrypted)
}
fn sorted_key_ids(&self) -> Vec<String> {
let mut ids: Vec<String> = self.ciphers.keys().cloned().collect();
ids.sort();
ids
}
pub fn looks_like_envelope(data: &[u8]) -> bool {
Self::parse_envelope(data).is_some()
}
}
pub struct EncryptedStorage<T> {
inner: T,
encryption: StorageEncryption,
allow_plaintext_reads: bool,
allow_legacy_v0: bool,
}
impl<T> EncryptedStorage<T> {
pub fn new(
storage: T,
encryption: StorageEncryption,
allow_plaintext_reads: bool,
allow_legacy_v0: bool,
) -> Self {
Self {
inner: storage,
encryption,
allow_plaintext_reads,
allow_legacy_v0,
}
}
pub fn into_inner(self) -> T {
self.inner
}
}
#[async_trait::async_trait]
impl<T> AuthStorage for EncryptedStorage<T>
where
T: AuthStorage + Send + Sync,
{
async fn store_token(&self, token: &AuthToken) -> Result<()> {
self.inner.store_token(token).await
}
async fn get_token(&self, token_id: &str) -> Result<Option<AuthToken>> {
self.inner.get_token(token_id).await
}
async fn get_token_by_access_token(&self, access_token: &str) -> Result<Option<AuthToken>> {
self.inner.get_token_by_access_token(access_token).await
}
async fn update_token(&self, token: &AuthToken) -> Result<()> {
self.inner.update_token(token).await
}
async fn delete_token(&self, token_id: &str) -> Result<()> {
self.inner.delete_token(token_id).await
}
async fn list_user_tokens(&self, user_id: &str) -> Result<Vec<AuthToken>> {
self.inner.list_user_tokens(user_id).await
}
async fn store_session(&self, session_id: &str, data: &SessionData) -> Result<()> {
self.inner.store_session(session_id, data).await
}
async fn get_session(&self, session_id: &str) -> Result<Option<SessionData>> {
self.inner.get_session(session_id).await
}
async fn delete_session(&self, session_id: &str) -> Result<()> {
self.inner.delete_session(session_id).await
}
async fn list_user_sessions(&self, user_id: &str) -> Result<Vec<SessionData>> {
self.inner.list_user_sessions(user_id).await
}
async fn count_active_sessions(&self) -> Result<u64> {
self.inner.count_active_sessions().await
}
async fn store_tokens_bulk(&self, tokens: &[AuthToken]) -> Result<()> {
self.inner.store_tokens_bulk(tokens).await
}
async fn delete_tokens_bulk(&self, token_ids: &[String]) -> Result<()> {
self.inner.delete_tokens_bulk(token_ids).await
}
async fn store_sessions_bulk(&self, sessions: &[(String, SessionData)]) -> Result<()> {
self.inner.store_sessions_bulk(sessions).await
}
async fn delete_sessions_bulk(&self, session_ids: &[String]) -> Result<()> {
self.inner.delete_sessions_bulk(session_ids).await
}
async fn get_kv_ttl(&self, key: &str) -> Result<Option<Duration>> {
self.inner.get_kv_ttl(key).await
}
async fn store_kv(&self, key: &str, value: &[u8], ttl: Option<Duration>) -> Result<()> {
let encrypted_value = self.encryption.encrypt_for_storage(value, key.as_bytes())?;
self.inner.store_kv(key, &encrypted_value, ttl).await
}
async fn get_kv(&self, key: &str) -> Result<Option<Vec<u8>>> {
let Some(raw) = self.inner.get_kv(key).await? else {
return Ok(None);
};
if let Some(envelope) = StorageEncryption::parse_envelope(&raw) {
if envelope.v < CURRENT_FORMAT_VERSION && !self.allow_legacy_v0 {
return Err(AuthError::internal(format!(
"Value for record '{}' uses legacy envelope format version {} (its \
metadata is not bound into the authenticated data), and \
storage_encryption.allow_legacy_v0 is false. Run the migration tool \
(`auth-framework-admin security encrypt-kv --accept-legacy-v0`) to \
upgrade it to the current format, or temporarily set \
storage_encryption.allow_legacy_v0 = true if something else needs to \
read it first.",
safe_log_id(key),
envelope.v
)));
}
let decrypted = self.encryption.decrypt(&envelope, key.as_bytes())?;
return Ok(Some(decrypted));
}
if self.allow_plaintext_reads {
return Ok(Some(raw));
}
Err(AuthError::internal(format!(
"Value for record '{}' is not a valid encrypted envelope, and \
storage_encryption.allow_plaintext_reads is false. If this key genuinely \
predates encryption being enabled, run the migration tool \
(`auth-framework-admin security encrypt-kv`) or temporarily set \
storage_encryption.allow_plaintext_reads = true while migrating.",
safe_log_id(key)
)))
}
fn tracks_kv_ttl(&self) -> bool {
self.inner.tracks_kv_ttl()
}
fn encrypts_kv_at_rest(&self) -> bool {
true
}
async fn delete_kv(&self, key: &str) -> Result<()> {
self.inner.delete_kv(key).await
}
async fn list_kv_keys(&self, prefix: &str) -> Result<Vec<String>> {
self.inner.list_kv_keys(prefix).await
}
async fn cleanup_expired(&self) -> Result<()> {
self.inner.cleanup_expired().await
}
}
#[derive(Debug, Clone, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct KvEncryptionMigrationReport {
pub dry_run: bool,
pub scanned: u64,
pub already_encrypted: u64,
pub legacy_v0_found: u64,
pub upgraded_from_legacy: u64,
pub encrypted: u64,
pub vanished: u64,
pub failed: Vec<String>,
}
#[derive(Debug, Clone, Copy, Default)]
#[non_exhaustive]
pub struct MigrationOptions {
pub dry_run: bool,
pub accept_legacy_v0: bool,
pub accept_ttl_loss: bool,
}
impl MigrationOptions {
pub fn with_accept_ttl_loss(mut self, accept_ttl_loss: bool) -> Self {
self.accept_ttl_loss = accept_ttl_loss;
self
}
pub fn with_dry_run(mut self, dry_run: bool) -> Self {
self.dry_run = dry_run;
self
}
pub fn with_accept_legacy_v0(mut self, accept_legacy_v0: bool) -> Self {
self.accept_legacy_v0 = accept_legacy_v0;
self
}
}
pub async fn migrate_kv_to_encrypted<S: AuthStorage + ?Sized>(
storage: &S,
encryption: &StorageEncryption,
prefix: &str,
options: MigrationOptions,
) -> Result<KvEncryptionMigrationReport> {
let MigrationOptions {
dry_run,
accept_legacy_v0,
accept_ttl_loss,
} = options;
if !dry_run && !accept_ttl_loss && !storage.tracks_kv_ttl() {
return Err(AuthError::validation(
"This storage backend does not report KV TTLs, so migrating would make every \
expiring entry (OAuth codes, MFA/SMS codes, rate-limit windows, expiring API \
keys, ...) permanent. Scope the prefix to durable secrets and pass \
accept_ttl_loss (CLI: --accept-ttl-loss) to proceed anyway.",
));
}
let mut report = KvEncryptionMigrationReport {
dry_run,
..Default::default()
};
let keys = storage.list_kv_keys(prefix).await?;
report.scanned = keys.len() as u64;
for key in keys {
let ttl = storage.get_kv_ttl(&key).await?;
let Some(mut raw) = storage.get_kv(&key).await? else {
report.vanished += 1;
continue;
};
if let Some(envelope) = StorageEncryption::parse_envelope(&raw) {
if envelope.v >= CURRENT_FORMAT_VERSION {
report.already_encrypted += 1;
continue;
}
match encryption.decrypt(&envelope, key.as_bytes()) {
Err(_) => {
tracing::warn!(
record = %safe_log_id(&key),
"migrate_kv_to_encrypted: could not decrypt format-version-0 \
envelope with any loaded key -- skipping, not aborting the rest \
of the run"
);
report.failed.push(safe_log_id(&key));
}
Ok(mut plaintext) => {
report.legacy_v0_found += 1;
if !dry_run && accept_legacy_v0 {
if envelope.v == 0 {
tracing::warn!(
record = %safe_log_id(&key),
"migrate_kv_to_encrypted: upgrading format-version-0 \
envelope to the current format -- v0 has no AAD, so this \
plaintext's association with this specific key was not \
cryptographically verified by this upgrade"
);
} else {
tracing::info!(
record = %safe_log_id(&key),
v = envelope.v,
"migrate_kv_to_encrypted: upgrading legacy envelope to the \
current format (its AAD bound the record key)"
);
}
let encrypt_result =
encryption.encrypt_for_storage(&plaintext, key.as_bytes());
plaintext.zeroize();
let new_envelope = encrypt_result?;
storage.store_kv(&key, &new_envelope, ttl).await?;
report.upgraded_from_legacy += 1;
} else {
plaintext.zeroize();
}
}
}
continue;
}
report.encrypted += 1;
if !dry_run {
let encrypt_result = encryption.encrypt_for_storage(&raw, key.as_bytes());
raw.zeroize();
let envelope = encrypt_result?;
storage.store_kv(&key, &envelope, ttl).await?;
} else {
raw.zeroize();
}
}
Ok(report)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::storage::MemoryStorage;
#[test]
fn test_key_generation() {
let key = StorageEncryption::generate_key();
assert!(!key.is_empty());
let decoded = BASE64.decode(&key).unwrap();
assert_eq!(decoded.len(), 32);
}
#[test]
fn test_encrypt_decrypt_roundtrip() {
let enc = StorageEncryption::new_random();
let plaintext = b"super secret totp seed, not utf8 safe either: \xff\xfe";
let encrypted = enc.encrypt(plaintext, b"user:alice:totp_secret").unwrap();
let decrypted = enc.decrypt(&encrypted, b"user:alice:totp_secret").unwrap();
assert_eq!(decrypted, plaintext);
}
#[test]
fn test_decrypt_rejects_wrong_aad() {
let enc = StorageEncryption::new_random();
let encrypted = enc
.encrypt(b"alice's secret", b"user:alice:totp_secret")
.unwrap();
let result = enc.decrypt(&encrypted, b"user:bob:totp_secret");
assert!(
result.is_err(),
"decrypting with the wrong AAD (a different record's key) must fail"
);
}
#[test]
fn test_nonces_are_unique_across_many_encryptions() {
let enc = StorageEncryption::new_random();
let mut seen = std::collections::HashSet::new();
for _ in 0..1000 {
let encrypted = enc
.encrypt(b"same plaintext every time", b"same:aad")
.unwrap();
assert_eq!(
BASE64.decode(&encrypted.nonce).unwrap().len(),
12,
"nonce must be 96 bits"
);
assert!(
seen.insert(encrypted.nonce.clone()),
"nonce reused across encryptions -- this breaks AES-GCM's security guarantee"
);
}
}
#[test]
fn test_storage_roundtrip_non_utf8_bytes() {
let enc = StorageEncryption::new_random();
let raw_salt: &[u8] = &[0xDE, 0xAD, 0xBE, 0xEF, 0x00, 0xFF, 0x80, 0x81];
let stored = enc.encrypt_for_storage(raw_salt, b"salt:key").unwrap();
let restored = enc.decrypt_from_storage(&stored, b"salt:key").unwrap();
assert_eq!(restored, raw_salt);
}
struct EmptyKeyProvider;
impl KeyProvider for EmptyKeyProvider {
fn load_keys(&self) -> Result<LoadedKeys> {
Err(AuthError::config("no key configured (test)"))
}
}
#[test]
fn test_construction_fails_closed_with_no_key() {
let result = StorageEncryption::new(&EmptyKeyProvider);
assert!(
result.is_err(),
"StorageEncryption::new must fail, not silently construct an unusable/no-op encryptor"
);
}
struct FixedKeyProvider(LoadedKeys);
impl KeyProvider for FixedKeyProvider {
fn load_keys(&self) -> Result<LoadedKeys> {
Ok(LoadedKeys {
current_key_id: self.0.current_key_id.clone(),
keys: self.0.keys.clone(),
})
}
}
#[test]
fn test_construction_rejects_empty_key_id() {
let mut keys = HashMap::new();
keys.insert("1".to_string(), [1u8; 32]);
keys.insert(String::new(), [2u8; 32]);
let result = StorageEncryption::new(&FixedKeyProvider(LoadedKeys {
current_key_id: "1".to_string(),
keys,
}));
assert!(
result.is_err(),
"an empty key id anywhere in the loaded key set must be rejected (it's reserved \
for format-version-0 envelopes), even when current_key_id itself is valid"
);
}
struct TwoKeyProvider {
current_id: String,
old_key: [u8; 32],
new_key: [u8; 32],
old_id: String,
}
impl KeyProvider for TwoKeyProvider {
fn load_keys(&self) -> Result<LoadedKeys> {
let mut keys = HashMap::new();
keys.insert(self.old_id.clone(), self.old_key);
keys.insert(self.current_id.clone(), self.new_key);
Ok(LoadedKeys {
current_key_id: self.current_id.clone(),
keys,
})
}
}
#[test]
fn test_old_key_still_decrypts_after_rotation() {
let mut keys = HashMap::new();
keys.insert("1".to_string(), [7u8; 32]);
let enc_before_rotation = StorageEncryption::new(&FixedKeyProvider(LoadedKeys {
current_key_id: "1".to_string(),
keys,
}))
.unwrap();
let old_envelope = enc_before_rotation
.encrypt(b"written before rotation", b"some:key")
.unwrap();
assert_eq!(old_envelope.key_id, "1");
let provider = TwoKeyProvider {
current_id: "2".to_string(),
old_id: "1".to_string(),
old_key: [7u8; 32],
new_key: [9u8; 32],
};
let enc_after_rotation = StorageEncryption::new(&provider).unwrap();
let new_envelope = enc_after_rotation
.encrypt(b"written after rotation", b"some:key")
.unwrap();
assert_eq!(new_envelope.key_id, "2");
let decrypted_old = enc_after_rotation
.decrypt(&old_envelope, b"some:key")
.unwrap();
assert_eq!(decrypted_old, b"written before rotation");
}
#[test]
fn test_decrypts_format_version_0_envelope() {
let mut keys = HashMap::new();
keys.insert("1".to_string(), [3u8; 32]);
let enc = StorageEncryption::new(&FixedKeyProvider(LoadedKeys {
current_key_id: "1".to_string(),
keys,
}))
.unwrap();
let cipher = {
let key = Key::<Aes256Gcm>::from_slice(&[3u8; 32]);
Aes256Gcm::new(key)
};
let nonce_bytes = [5u8; 12];
let nonce = Nonce::from_slice(&nonce_bytes);
let ciphertext = cipher
.encrypt(nonce, b"legacy-format plaintext".as_ref())
.unwrap();
let legacy_json = format!(
r#"{{"data":"{}","nonce":"{}","algorithm":"AES-256-GCM","key_derivation":"direct"}}"#,
BASE64.encode(&ciphertext),
BASE64.encode(nonce_bytes)
);
assert!(StorageEncryption::looks_like_envelope(
legacy_json.as_bytes()
));
let decrypted = enc
.decrypt_from_storage(legacy_json.as_bytes(), b"irrelevant-for-v0")
.unwrap();
assert_eq!(decrypted, b"legacy-format plaintext".to_vec());
}
#[tokio::test]
async fn test_wrapper_rejects_v1_envelope_downgraded_to_look_like_v0() {
let mut keys = HashMap::new();
keys.insert("1".to_string(), [4u8; 32]);
let encryption = StorageEncryption::new(&FixedKeyProvider(LoadedKeys {
current_key_id: "1".to_string(),
keys,
}))
.unwrap();
let inner = MemoryStorage::new();
let wrapped = EncryptedStorage::new(inner, encryption, false, false);
wrapped
.store_kv("user:alice:totp_secret", b"real secret", None)
.await
.unwrap();
let inner = wrapped.into_inner();
let real_envelope: EncryptedData = serde_json::from_slice(
&inner
.get_kv("user:alice:totp_secret")
.await
.unwrap()
.unwrap(),
)
.unwrap();
let downgraded_json = serde_json::json!({
"data": real_envelope.data,
"nonce": real_envelope.nonce,
"algorithm": real_envelope.algorithm,
})
.to_string();
inner
.store_kv("user:alice:totp_secret", downgraded_json.as_bytes(), None)
.await
.unwrap();
let mut keys2 = HashMap::new();
keys2.insert("1".to_string(), [4u8; 32]);
let encryption2 = StorageEncryption::new(&FixedKeyProvider(LoadedKeys {
current_key_id: "1".to_string(),
keys: keys2,
}))
.unwrap();
let wrapped = EncryptedStorage::new(inner, encryption2, false, false);
let result = wrapped.get_kv("user:alice:totp_secret").await;
assert!(
result.is_err(),
"a v1 envelope downgraded to look like v0 must not be accepted as the record's \
value, with allow_legacy_v0 at its default (false)"
);
}
#[tokio::test]
async fn test_list_kv_keys_passes_through_unencrypted() {
let inner = MemoryStorage::new();
inner
.store_kv("prefix:a", b"ignored by this test", None)
.await
.unwrap();
inner
.store_kv("prefix:b", b"ignored by this test", None)
.await
.unwrap();
let wrapped = EncryptedStorage::new(inner, StorageEncryption::new_random(), false, false);
let mut keys = wrapped.list_kv_keys("prefix:").await.unwrap();
keys.sort();
assert_eq!(
keys,
vec!["prefix:a".to_string(), "prefix:b".to_string()],
"list_kv_keys must pass through to the inner backend, not use the trait's \
empty-Vec default"
);
}
#[tokio::test]
async fn test_encrypted_storage_roundtrip() {
let inner = MemoryStorage::new();
let wrapped = EncryptedStorage::new(inner, StorageEncryption::new_random(), false, false);
wrapped
.store_kv("user:alice:totp_secret", b"JBSWY3DPEHPK3PXP", None)
.await
.unwrap();
let value = wrapped.get_kv("user:alice:totp_secret").await.unwrap();
assert_eq!(value, Some(b"JBSWY3DPEHPK3PXP".to_vec()));
}
#[tokio::test]
async fn test_encrypted_storage_actually_encrypts_the_underlying_value() {
let wrapped = EncryptedStorage::new(
MemoryStorage::new(),
StorageEncryption::new_random(),
false,
false,
);
wrapped
.store_kv("user:alice:totp_secret", b"JBSWY3DPEHPK3PXP", None)
.await
.unwrap();
let inner = wrapped.into_inner();
let raw = inner
.get_kv("user:alice:totp_secret")
.await
.unwrap()
.unwrap();
assert_ne!(
raw,
b"JBSWY3DPEHPK3PXP".to_vec(),
"the underlying storage must not hold the plaintext value"
);
assert!(
StorageEncryption::looks_like_envelope(&raw),
"the underlying storage must hold a proper encrypted envelope"
);
}
#[tokio::test]
async fn test_wrapper_rejects_ciphertext_swapped_between_records() {
let mut keys = HashMap::new();
keys.insert("1".to_string(), [11u8; 32]);
let loaded = LoadedKeys {
current_key_id: "1".to_string(),
keys,
};
let encryption_for_wrapper = StorageEncryption::new(&FixedKeyProvider(LoadedKeys {
current_key_id: loaded.current_key_id.clone(),
keys: loaded.keys.clone(),
}))
.unwrap();
let encryption_for_verification =
StorageEncryption::new(&FixedKeyProvider(loaded)).unwrap();
let inner = MemoryStorage::new();
let wrapped = EncryptedStorage::new(inner, encryption_for_wrapper, false, false);
wrapped
.store_kv("user:alice:totp_secret", b"alice-secret", None)
.await
.unwrap();
let inner = wrapped.into_inner();
let raw = inner
.get_kv("user:alice:totp_secret")
.await
.unwrap()
.unwrap();
let decrypted = encryption_for_verification
.decrypt(
&serde_json::from_slice(&raw).unwrap(),
b"user:alice:totp_secret",
)
.unwrap();
assert_eq!(decrypted, b"alice-secret".to_vec());
let wrong_aad_result = encryption_for_verification.decrypt(
&serde_json::from_slice(&raw).unwrap(),
b"user:bob:totp_secret",
);
assert!(
wrong_aad_result.is_err(),
"the wrapper's envelope must not decrypt under a different record's key name -- \
if it does, the wrapper is using a constant AAD instead of the real storage key"
);
}
#[tokio::test]
async fn test_reads_legacy_plaintext_when_allowed() {
let inner = MemoryStorage::new();
inner
.store_kv("legacy:key", b"pre-existing plaintext value", None)
.await
.unwrap();
let wrapped = EncryptedStorage::new(inner, StorageEncryption::new_random(), true, false);
let value = wrapped.get_kv("legacy:key").await.unwrap();
assert_eq!(value, Some(b"pre-existing plaintext value".to_vec()));
}
#[tokio::test]
async fn test_rejects_non_envelope_value_when_plaintext_reads_disallowed() {
let inner = MemoryStorage::new();
inner
.store_kv("user:alice:totp_secret", b"attacker-chosen-plaintext", None)
.await
.unwrap();
let wrapped = EncryptedStorage::new(inner, StorageEncryption::new_random(), false, false);
let result = wrapped.get_kv("user:alice:totp_secret").await;
assert!(
result.is_err(),
"a non-envelope value must be rejected, not silently treated as plaintext, \
when allow_plaintext_reads is false"
);
}
#[tokio::test]
async fn test_migration_upgrades_v0_envelope_to_current_format() {
let mut keys = HashMap::new();
keys.insert("1".to_string(), [6u8; 32]);
let encryption = StorageEncryption::new(&FixedKeyProvider(LoadedKeys {
current_key_id: "1".to_string(),
keys,
}))
.unwrap();
let cipher = {
let key = Key::<Aes256Gcm>::from_slice(&[6u8; 32]);
Aes256Gcm::new(key)
};
let nonce_bytes = [8u8; 12];
let nonce = Nonce::from_slice(&nonce_bytes);
let ciphertext = cipher.encrypt(nonce, b"v0 secret".as_ref()).unwrap();
let v0_json = format!(
r#"{{"data":"{}","nonce":"{}","algorithm":"AES-256-GCM","key_derivation":"direct"}}"#,
BASE64.encode(&ciphertext),
BASE64.encode(nonce_bytes)
);
let storage = MemoryStorage::new();
storage
.store_kv("secret:legacy", v0_json.as_bytes(), None)
.await
.unwrap();
let report = migrate_kv_to_encrypted(
&storage,
&encryption,
"secret:",
MigrationOptions {
dry_run: false,
accept_legacy_v0: true,
..Default::default()
},
)
.await
.unwrap();
assert_eq!(
report.legacy_v0_found, 1,
"a decryptable v0 envelope must be counted as found"
);
assert_eq!(
report.upgraded_from_legacy, 1,
"with accept_legacy_v0 true on a real run, it must actually be upgraded"
);
assert_eq!(report.already_encrypted, 0);
assert!(report.failed.is_empty());
let raw_after = storage.get_kv("secret:legacy").await.unwrap().unwrap();
let envelope_after: EncryptedData = serde_json::from_slice(&raw_after).unwrap();
assert_eq!(
envelope_after.v, CURRENT_FORMAT_VERSION,
"the stored envelope must now be the current format, not still v0"
);
assert!(
!envelope_after.key_id.is_empty(),
"the upgraded envelope must have a real key_id"
);
let decrypted = encryption
.decrypt(&envelope_after, b"secret:legacy")
.unwrap();
assert_eq!(decrypted, b"v0 secret".to_vec());
let report2 = migrate_kv_to_encrypted(
&storage,
&encryption,
"secret:",
MigrationOptions {
dry_run: false,
accept_legacy_v0: false,
..Default::default()
},
)
.await
.unwrap();
assert_eq!(report2.upgraded_from_legacy, 0);
assert_eq!(report2.already_encrypted, 1);
}
#[tokio::test]
async fn test_migration_does_not_upgrade_legacy_v0_without_accept_flag() {
let mut keys = HashMap::new();
keys.insert("1".to_string(), [7u8; 32]);
let encryption = StorageEncryption::new(&FixedKeyProvider(LoadedKeys {
current_key_id: "1".to_string(),
keys,
}))
.unwrap();
let cipher = {
let key = Key::<Aes256Gcm>::from_slice(&[7u8; 32]);
Aes256Gcm::new(key)
};
let nonce_bytes = [3u8; 12];
let nonce = Nonce::from_slice(&nonce_bytes);
let ciphertext = cipher.encrypt(nonce, b"v0 secret".as_ref()).unwrap();
let v0_json = format!(
r#"{{"data":"{}","nonce":"{}","algorithm":"AES-256-GCM","key_derivation":"direct"}}"#,
BASE64.encode(&ciphertext),
BASE64.encode(nonce_bytes)
);
let storage = MemoryStorage::new();
storage
.store_kv("secret:legacy", v0_json.as_bytes(), None)
.await
.unwrap();
let report = migrate_kv_to_encrypted(
&storage,
&encryption,
"secret:",
MigrationOptions {
dry_run: false,
accept_legacy_v0: false,
..Default::default()
},
)
.await
.unwrap();
assert_eq!(
report.legacy_v0_found, 1,
"the v0 envelope must still be detected/decrypted"
);
assert_eq!(
report.upgraded_from_legacy, 0,
"without accept_legacy_v0, nothing must actually be rewritten"
);
let raw_after = storage.get_kv("secret:legacy").await.unwrap().unwrap();
assert_eq!(
raw_after,
v0_json.as_bytes(),
"the stored envelope must be byte-for-byte unchanged without accept_legacy_v0"
);
}
#[tokio::test]
async fn test_migration_skips_undecryptable_v0_envelope_without_aborting() {
let mut keys = HashMap::new();
keys.insert("1".to_string(), [9u8; 32]);
let encryption = StorageEncryption::new(&FixedKeyProvider(LoadedKeys {
current_key_id: "1".to_string(),
keys,
}))
.unwrap();
let bad_cipher = {
let key = Key::<Aes256Gcm>::from_slice(&[0u8; 32]);
Aes256Gcm::new(key)
};
let nonce_bytes = [1u8; 12];
let nonce = Nonce::from_slice(&nonce_bytes);
let bad_ciphertext = bad_cipher
.encrypt(nonce, b"undecryptable".as_ref())
.unwrap();
let bad_v0_json = format!(
r#"{{"data":"{}","nonce":"{}","algorithm":"AES-256-GCM","key_derivation":"direct"}}"#,
BASE64.encode(&bad_ciphertext),
BASE64.encode(nonce_bytes)
);
let storage = MemoryStorage::new();
storage
.store_kv("secret:bad", bad_v0_json.as_bytes(), None)
.await
.unwrap();
storage
.store_kv("secret:good_a", b"plaintext-a", None)
.await
.unwrap();
storage
.store_kv("secret:good_b", b"plaintext-b", None)
.await
.unwrap();
let report = migrate_kv_to_encrypted(
&storage,
&encryption,
"secret:",
MigrationOptions {
dry_run: false,
accept_legacy_v0: true,
..Default::default()
},
)
.await
.expect("one undecryptable record must not abort the whole migration");
assert_eq!(report.scanned, 3);
assert_eq!(
report.failed,
vec![safe_log_id("secret:bad")],
"the undecryptable record must be named (as a safe identifier, not the raw \
key) in `failed`, not silently dropped"
);
assert_eq!(
report.encrypted, 2,
"the other two plaintext keys must still be processed despite the bad one"
);
let good_a_after = storage.get_kv("secret:good_a").await.unwrap().unwrap();
assert!(StorageEncryption::looks_like_envelope(&good_a_after));
let good_b_after = storage.get_kv("secret:good_b").await.unwrap().unwrap();
assert!(StorageEncryption::looks_like_envelope(&good_b_after));
let bad_after = storage.get_kv("secret:bad").await.unwrap().unwrap();
assert_eq!(bad_after, bad_v0_json.as_bytes());
}
#[tokio::test]
async fn test_migration_dry_run_detects_undecryptable_v0_envelope() {
let mut keys = HashMap::new();
keys.insert("1".to_string(), [5u8; 32]);
let encryption = StorageEncryption::new(&FixedKeyProvider(LoadedKeys {
current_key_id: "1".to_string(),
keys,
}))
.unwrap();
let bad_cipher = {
let key = Key::<Aes256Gcm>::from_slice(&[0u8; 32]);
Aes256Gcm::new(key)
};
let nonce_bytes = [2u8; 12];
let nonce = Nonce::from_slice(&nonce_bytes);
let bad_ciphertext = bad_cipher
.encrypt(nonce, b"undecryptable".as_ref())
.unwrap();
let bad_v0_json = format!(
r#"{{"data":"{}","nonce":"{}","algorithm":"AES-256-GCM","key_derivation":"direct"}}"#,
BASE64.encode(&bad_ciphertext),
BASE64.encode(nonce_bytes)
);
let storage = MemoryStorage::new();
storage
.store_kv("secret:bad", bad_v0_json.as_bytes(), None)
.await
.unwrap();
let dry_report = migrate_kv_to_encrypted(
&storage,
&encryption,
"secret:",
MigrationOptions {
dry_run: true,
accept_legacy_v0: true,
..Default::default()
},
)
.await
.unwrap();
assert_eq!(
dry_report.failed,
vec![safe_log_id("secret:bad")],
"a dry run must actually attempt the decrypt and report the same failure a \
real run would, not optimistically assume every v0 envelope would succeed"
);
assert_eq!(dry_report.upgraded_from_legacy, 0);
assert_eq!(dry_report.legacy_v0_found, 0);
}
#[test]
fn test_safe_log_id_never_contains_the_raw_secret() {
let raw_secret = "ak_live_super_secret_bearer_token_12345";
let key = format!("api_key:{raw_secret}");
let id = safe_log_id(&key);
assert!(
!id.contains(raw_secret),
"safe_log_id must never contain the raw secret portion of the key, got: {id}"
);
assert!(
id.starts_with("api_key:"),
"safe_log_id should keep the (non-secret) namespace prefix, got: {id}"
);
assert_eq!(id, safe_log_id(&key));
}
#[test]
fn test_safe_log_id_handles_colonless_key_without_leaking_it() {
let raw_secret = "a_bearer_token_with_no_colon_in_it_at_all";
let id = safe_log_id(raw_secret);
assert!(
!id.contains(raw_secret),
"a colonless key must not appear verbatim in its safe_log_id, got: {id}"
);
assert!(
id.starts_with("key:"),
"a colonless key should fall back to the literal 'key:' prefix, got: {id}"
);
}
#[tokio::test]
async fn test_dry_run_with_accept_legacy_v0_does_not_write_a_decryptable_v0_record() {
let mut keys = HashMap::new();
keys.insert("1".to_string(), [4u8; 32]);
let encryption = StorageEncryption::new(&FixedKeyProvider(LoadedKeys {
current_key_id: "1".to_string(),
keys,
}))
.unwrap();
let cipher = {
let key = Key::<Aes256Gcm>::from_slice(&[4u8; 32]);
Aes256Gcm::new(key)
};
let nonce_bytes = [6u8; 12];
let nonce = Nonce::from_slice(&nonce_bytes);
let ciphertext = cipher.encrypt(nonce, b"v0 secret".as_ref()).unwrap();
let v0_json = format!(
r#"{{"data":"{}","nonce":"{}","algorithm":"AES-256-GCM","key_derivation":"direct"}}"#,
BASE64.encode(&ciphertext),
BASE64.encode(nonce_bytes)
);
let storage = MemoryStorage::new();
storage
.store_kv("secret:legacy", v0_json.as_bytes(), None)
.await
.unwrap();
let report = migrate_kv_to_encrypted(
&storage,
&encryption,
"secret:",
MigrationOptions {
dry_run: true,
accept_legacy_v0: true,
..Default::default()
},
)
.await
.unwrap();
assert_eq!(
report.legacy_v0_found, 1,
"a dry run must still report a decryptable v0 record as found"
);
assert_eq!(
report.upgraded_from_legacy, 0,
"a dry run must never actually upgrade anything, even with accept_legacy_v0 true"
);
let raw_after = storage.get_kv("secret:legacy").await.unwrap().unwrap();
assert_eq!(
raw_after,
v0_json.as_bytes(),
"a dry run with accept_legacy_v0 true must leave the record byte-for-byte \
unchanged"
);
}
#[tokio::test]
async fn test_migration_dry_run_reports_without_writing() {
let storage = MemoryStorage::new();
storage
.store_kv("secret:a", b"plaintext-a", None)
.await
.unwrap();
storage
.store_kv("secret:b", b"plaintext-b", None)
.await
.unwrap();
let encryption = StorageEncryption::new_random();
let report = migrate_kv_to_encrypted(
&storage,
&encryption,
"secret:",
MigrationOptions {
dry_run: true,
accept_legacy_v0: false,
..Default::default()
},
)
.await
.unwrap();
assert!(report.dry_run);
assert_eq!(report.scanned, 2);
assert_eq!(report.encrypted, 2);
assert_eq!(report.already_encrypted, 0);
let still_plaintext = storage.get_kv("secret:a").await.unwrap().unwrap();
assert_eq!(still_plaintext, b"plaintext-a".to_vec());
}
#[tokio::test]
async fn test_migration_encrypts_plaintext_values() {
let storage = MemoryStorage::new();
storage
.store_kv("secret:a", b"plaintext-a", None)
.await
.unwrap();
let encryption = StorageEncryption::new_random();
let report = migrate_kv_to_encrypted(
&storage,
&encryption,
"secret:",
MigrationOptions {
dry_run: false,
accept_legacy_v0: false,
..Default::default()
},
)
.await
.unwrap();
assert_eq!(report.encrypted, 1);
let raw = storage.get_kv("secret:a").await.unwrap().unwrap();
assert!(StorageEncryption::looks_like_envelope(&raw));
let decrypted = encryption.decrypt_from_storage(&raw, b"secret:a").unwrap();
assert_eq!(decrypted, b"plaintext-a".to_vec());
}
#[tokio::test]
async fn test_migration_is_idempotent_and_resumable() {
let storage = MemoryStorage::new();
storage
.store_kv("secret:a", b"plaintext-a", None)
.await
.unwrap();
storage
.store_kv("secret:b", b"plaintext-b", None)
.await
.unwrap();
let encryption = StorageEncryption::new_random();
let envelope_a = encryption
.encrypt_for_storage(b"plaintext-a", b"secret:a")
.unwrap();
storage
.store_kv("secret:a", &envelope_a, None)
.await
.unwrap();
let report = migrate_kv_to_encrypted(
&storage,
&encryption,
"secret:",
MigrationOptions {
dry_run: false,
accept_legacy_v0: false,
..Default::default()
},
)
.await
.unwrap();
assert_eq!(report.scanned, 2);
assert_eq!(report.already_encrypted, 1);
assert_eq!(report.encrypted, 1);
let raw_a_after = storage.get_kv("secret:a").await.unwrap().unwrap();
assert_eq!(
raw_a_after, envelope_a,
"an already-encrypted value must be left byte-for-byte unchanged, not double-encrypted"
);
let raw_b_after = storage.get_kv("secret:b").await.unwrap().unwrap();
assert!(StorageEncryption::looks_like_envelope(&raw_b_after));
let report2 = migrate_kv_to_encrypted(
&storage,
&encryption,
"secret:",
MigrationOptions {
dry_run: false,
accept_legacy_v0: false,
..Default::default()
},
)
.await
.unwrap();
assert_eq!(report2.already_encrypted, 2);
assert_eq!(report2.encrypted, 0);
}
#[tokio::test]
async fn test_migration_only_touches_matching_prefix() {
let storage = MemoryStorage::new();
storage
.store_kv("secret:a", b"plaintext-a", None)
.await
.unwrap();
storage
.store_kv("other:b", b"plaintext-b", None)
.await
.unwrap();
let encryption = StorageEncryption::new_random();
let report = migrate_kv_to_encrypted(
&storage,
&encryption,
"secret:",
MigrationOptions {
dry_run: false,
accept_legacy_v0: false,
..Default::default()
},
)
.await
.unwrap();
assert_eq!(report.scanned, 1);
let other_untouched = storage.get_kv("other:b").await.unwrap().unwrap();
assert_eq!(
other_untouched,
b"plaintext-b".to_vec(),
"a key outside the given prefix must not be touched"
);
}
#[tokio::test]
async fn wrapper_passes_kv_ttl_through() {
let wrapped = EncryptedStorage::new(
MemoryStorage::new(),
StorageEncryption::new_random(),
false,
false,
);
wrapped
.store_kv("k", b"v", Some(Duration::from_secs(600)))
.await
.unwrap();
let ttl = wrapped.get_kv_ttl("k").await.unwrap().unwrap();
assert!(ttl > Duration::from_secs(590) && ttl <= Duration::from_secs(600));
}
struct FixedKeys {
current: &'static str,
keys: Vec<(&'static str, [u8; 32])>,
}
impl KeyProvider for FixedKeys {
fn load_keys(&self) -> Result<LoadedKeys> {
Ok(LoadedKeys {
current_key_id: self.current.to_string(),
keys: self
.keys
.iter()
.map(|(id, key)| (id.to_string(), *key))
.collect(),
})
}
}
const KEY_A: [u8; 32] = [0x11; 32];
const KEY_B: [u8; 32] = [0x22; 32];
fn manual_envelope(
key: &[u8; 32],
key_id: &str,
v: u8,
plaintext: &[u8],
aad: &[u8],
) -> Vec<u8> {
let cipher = Aes256Gcm::new(Key::<Aes256Gcm>::from_slice(key));
let nonce_bytes = [7u8; 12];
let ciphertext = cipher
.encrypt(
Nonce::from_slice(&nonce_bytes),
Payload {
msg: plaintext,
aad,
},
)
.unwrap();
serde_json::to_vec(&EncryptedData {
data: BASE64.encode(ciphertext),
nonce: BASE64.encode(nonce_bytes),
algorithm: "AES-256-GCM".to_string(),
key_id: key_id.to_string(),
v,
key_derivation: String::new(),
})
.unwrap()
}
#[test]
fn new_envelopes_use_format_v2() {
let enc = StorageEncryption::new_random();
assert_eq!(enc.encrypt(b"x", b"k").unwrap().v, 2);
}
#[test]
fn v2_aad_binds_key_id_and_version() {
let enc = StorageEncryption::new(&FixedKeys {
current: "a",
keys: vec![("a", KEY_A), ("b", KEY_A)],
})
.unwrap();
let envelope = enc.encrypt(b"secret", b"rec:1").unwrap();
assert_eq!(enc.decrypt(&envelope, b"rec:1").unwrap(), b"secret");
let mut relabelled = envelope.clone();
relabelled.key_id = "b".to_string();
assert!(
enc.decrypt(&relabelled, b"rec:1").is_err(),
"relabelling key_id must fail authentication"
);
let mut downgraded = envelope.clone();
downgraded.v = 1;
assert!(
enc.decrypt(&downgraded, b"rec:1").is_err(),
"rewriting v to 1 must not make a v2 ciphertext verify"
);
}
#[tokio::test]
async fn v1_envelopes_are_legacy_and_migrate_to_v2() {
let storage = MemoryStorage::new();
storage
.store_kv(
"rec:1",
&manual_envelope(&KEY_A, "1", 1, b"secret", b"rec:1"),
None,
)
.await
.unwrap();
let provider = || FixedKeys {
current: "1",
keys: vec![("1", KEY_A)],
};
let strict = EncryptedStorage::new(
storage.clone(),
StorageEncryption::new(&provider()).unwrap(),
false,
false,
);
assert!(
strict.get_kv("rec:1").await.is_err(),
"v1 must need the legacy policy"
);
let lenient = EncryptedStorage::new(
storage.clone(),
StorageEncryption::new(&provider()).unwrap(),
false,
true,
);
assert_eq!(lenient.get_kv("rec:1").await.unwrap().unwrap(), b"secret");
let report = migrate_kv_to_encrypted(
&storage,
&StorageEncryption::new(&provider()).unwrap(),
"",
MigrationOptions::default().with_accept_legacy_v0(true),
)
.await
.unwrap();
assert_eq!(report.upgraded_from_legacy, 1, "{report:?}");
let raw = storage.get_kv("rec:1").await.unwrap().unwrap();
assert_eq!(StorageEncryption::parse_envelope(&raw).unwrap().v, 2);
let strict_after = EncryptedStorage::new(
storage,
StorageEncryption::new(&provider()).unwrap(),
false,
false,
);
assert_eq!(
strict_after.get_kv("rec:1").await.unwrap().unwrap(),
b"secret"
);
}
#[tokio::test]
async fn upgraded_records_cannot_be_swapped_between_keys() {
let storage = MemoryStorage::new();
for (key, secret) in [("rec:1", &b"one"[..]), ("rec:2", b"two")] {
storage
.store_kv(key, &manual_envelope(&KEY_A, "1", 0, secret, b""), None)
.await
.unwrap();
}
let provider = || FixedKeys {
current: "1",
keys: vec![("1", KEY_A)],
};
migrate_kv_to_encrypted(
&storage,
&StorageEncryption::new(&provider()).unwrap(),
"",
MigrationOptions::default().with_accept_legacy_v0(true),
)
.await
.unwrap();
let swapped = storage.get_kv("rec:1").await.unwrap().unwrap();
storage.store_kv("rec:2", &swapped, None).await.unwrap();
let strict = EncryptedStorage::new(
storage,
StorageEncryption::new(&provider()).unwrap(),
false,
false,
);
assert!(strict.get_kv("rec:2").await.is_err());
}
#[test]
fn envelope_classification_requires_version_and_key_id() {
let shape = |extra: &str| {
format!(
r#"{{"data":"AAAA","nonce":"AAAAAAAAAAAAAAAA","algorithm":"AES-256-GCM"{extra}}}"#
)
};
assert!(StorageEncryption::parse_envelope(shape(r#","v":2"#).as_bytes()).is_none());
assert!(
StorageEncryption::parse_envelope(shape(r#","v":1,"key_id":"""#).as_bytes()).is_none()
);
assert!(
StorageEncryption::parse_envelope(shape(r#","v":2,"key_id":"1""#).as_bytes()).is_some()
);
assert!(StorageEncryption::parse_envelope(shape("").as_bytes()).is_some());
}
#[test]
fn decrypt_failures_share_one_error_text() {
let enc = StorageEncryption::new(&FixedKeys {
current: "a",
keys: vec![("a", KEY_A), ("b", KEY_B)],
})
.unwrap();
let good = enc.encrypt(b"secret", b"rec:1").unwrap();
let mut bad_base64 = good.clone();
bad_base64.data = "!!not base64!!".to_string();
let mut short_nonce = good.clone();
short_nonce.nonce = BASE64.encode([1u8; 4]);
let mut unknown_key = good.clone();
unknown_key.key_id = "zzz".to_string();
let mut wrong_algorithm = good.clone();
wrong_algorithm.algorithm = "ROT13".to_string();
let mut tampered = good.clone();
let mut raw = BASE64.decode(&tampered.data).unwrap();
raw[0] ^= 0x01;
tampered.data = BASE64.encode(raw);
let messages: Vec<String> = [
(&bad_base64, &b"rec:1"[..]),
(&short_nonce, b"rec:1"),
(&unknown_key, b"rec:1"),
(&wrong_algorithm, b"rec:1"),
(&tampered, b"rec:1"),
(&good, b"rec:OTHER"),
]
.iter()
.map(|(envelope, aad)| enc.decrypt(envelope, aad).unwrap_err().to_string())
.collect();
assert!(
messages.windows(2).all(|w| w[0] == w[1]),
"decrypt failures must be indistinguishable, got: {messages:#?}"
);
}
#[test]
fn legacy_trial_decryption_order_is_stable() {
let enc = StorageEncryption::new(&FixedKeys {
current: "k0",
keys: (0..8)
.map(|i| {
let id: &'static str = Box::leak(format!("k{i}").into_boxed_str());
(id, [i as u8 + 1; 32])
})
.rev()
.collect(),
})
.unwrap();
let ids = enc.sorted_key_ids();
let mut expected = ids.clone();
expected.sort();
assert_eq!(ids, expected);
assert_eq!(ids.len(), 8);
}
#[test]
fn safe_log_id_keeps_eight_hash_bytes() {
let id = safe_log_id("api_key:abc123");
let hash = id.strip_prefix("api_key:").unwrap();
assert_eq!(hash.len(), 16, "8 bytes = 16 hex chars, got {id}");
let colonless = safe_log_id("rawsecret");
assert_eq!(colonless.strip_prefix("key:").unwrap().len(), 16);
}
fn load_with_env(key: Option<&str>) -> Result<LoadedKeys> {
let _lock = TEST_ENCRYPTION_ENV_LOCK.blocking_lock();
unsafe {
std::env::remove_var("AUTH_STORAGE_ENCRYPTION_KEYS_FILE");
match key {
Some(key) => std::env::set_var("AUTH_STORAGE_ENCRYPTION_KEY", key),
None => std::env::remove_var("AUTH_STORAGE_ENCRYPTION_KEY"),
}
}
let result = EnvKeyProvider.load_keys();
unsafe { std::env::remove_var("AUTH_STORAGE_ENCRYPTION_KEY") };
result
}
#[test]
fn malformed_env_keys_fail_closed() {
assert!(load_with_env(None).is_err(), "no key at all");
assert!(load_with_env(Some("")).is_err(), "empty key");
assert!(
load_with_env(Some("!!!not base64!!!")).is_err(),
"bad base64"
);
assert!(
load_with_env(Some(&BASE64.encode([1u8; 16]))).is_err(),
"16-byte key"
);
assert!(
load_with_env(Some(&BASE64.encode([1u8; 33]))).is_err(),
"33-byte key"
);
assert!(load_with_env(Some(&BASE64.encode([1u8; 32]))).is_ok());
}
#[test]
fn malformed_keys_file_fails_closed() {
let dir = tempfile::tempdir().unwrap();
let good = BASE64.encode([3u8; 32]);
let cases: [(&str, String); 4] = [
("not json", "{{{".to_string()),
(
"current missing from keys",
format!(r#"{{"current":"x","keys":{{"1":"{good}"}}}}"#),
),
(
"one malformed entry",
format!(r#"{{"current":"1","keys":{{"1":"{good}","2":"short"}}}}"#),
),
("empty keys", r#"{"current":"1","keys":{}}"#.to_string()),
];
let _lock = TEST_ENCRYPTION_ENV_LOCK.blocking_lock();
for (name, body) in cases {
let path = dir.path().join("keys.json");
std::fs::write(&path, body).unwrap();
unsafe {
std::env::set_var("AUTH_STORAGE_ENCRYPTION_KEYS_FILE", &path);
}
let result = EnvKeyProvider.load_keys();
unsafe { std::env::remove_var("AUTH_STORAGE_ENCRYPTION_KEYS_FILE") };
assert!(result.is_err(), "{name} must fail closed");
}
}
fn ttl_provider() -> FixedKeys {
FixedKeys {
current: "1",
keys: vec![("1", KEY_A)],
}
}
#[tokio::test]
async fn migration_preserves_ttl_when_encrypting_plaintext() {
let storage = MemoryStorage::new();
storage
.store_kv("otp:1", b"123456", Some(Duration::from_secs(600)))
.await
.unwrap();
storage.store_kv("durable:1", b"keep", None).await.unwrap();
migrate_kv_to_encrypted(
&storage,
&StorageEncryption::new(&ttl_provider()).unwrap(),
"",
MigrationOptions::default(),
)
.await
.unwrap();
let ttl = storage.get_kv_ttl("otp:1").await.unwrap().unwrap();
assert!(
ttl > Duration::from_secs(590) && ttl <= Duration::from_secs(600),
"TTL must survive migration, got {ttl:?}"
);
assert_eq!(storage.get_kv_ttl("durable:1").await.unwrap(), None);
let raw = storage.get_kv("otp:1").await.unwrap().unwrap();
assert!(
StorageEncryption::looks_like_envelope(&raw),
"must be encrypted"
);
}
#[tokio::test]
async fn legacy_upgrade_preserves_ttl() {
let storage = MemoryStorage::new();
storage
.store_kv(
"rec:1",
&manual_envelope(&KEY_A, "", 0, b"secret", b""),
Some(Duration::from_secs(600)),
)
.await
.unwrap();
migrate_kv_to_encrypted(
&storage,
&StorageEncryption::new(&ttl_provider()).unwrap(),
"",
MigrationOptions::default().with_accept_legacy_v0(true),
)
.await
.unwrap();
let ttl = storage.get_kv_ttl("rec:1").await.unwrap().unwrap();
assert!(ttl > Duration::from_secs(590) && ttl <= Duration::from_secs(600));
let raw = storage.get_kv("rec:1").await.unwrap().unwrap();
assert_eq!(
StorageEncryption::parse_envelope(&raw).unwrap().v,
CURRENT_FORMAT_VERSION
);
}
#[tokio::test]
async fn migration_refuses_backend_that_cannot_report_ttl_without_opt_in() {
let storage = crate::testing::utilities::MockStorage::new();
let encryption = StorageEncryption::new(&ttl_provider()).unwrap();
assert!(
migrate_kv_to_encrypted(&storage, &encryption, "", MigrationOptions::default())
.await
.is_err(),
"a real run on a TTL-blind backend must be refused"
);
assert!(
migrate_kv_to_encrypted(
&storage,
&encryption,
"",
MigrationOptions::default().with_dry_run(true)
)
.await
.is_ok(),
"a dry run writes nothing, so it is allowed"
);
assert!(
migrate_kv_to_encrypted(
&storage,
&encryption,
"",
MigrationOptions::default().with_accept_ttl_loss(true)
)
.await
.is_ok(),
"explicit opt-in proceeds"
);
}
#[tokio::test]
async fn backends_that_honour_ttl_say_so() {
let memory = MemoryStorage::new();
assert!(memory.tracks_kv_ttl());
let wrapped = EncryptedStorage::new(
MemoryStorage::new(),
StorageEncryption::new_random(),
false,
false,
);
assert!(
wrapped.tracks_kv_ttl(),
"the wrapper forwards the inner answer"
);
let shared: std::sync::Arc<dyn AuthStorage> = std::sync::Arc::new(MemoryStorage::new());
assert!(shared.tracks_kv_ttl(), "the Arc impl forwards too");
assert!(
!crate::testing::utilities::MockStorage::new().tracks_kv_ttl(),
"a backend that ignores TTLs must say so"
);
}
#[test]
fn keys_file_mode_check_flags_group_and_other_access() {
for open in [0o644, 0o640, 0o604, 0o660, 0o666, 0o777, 0o601, 0o610] {
assert!(keys_file_mode_too_open(open), "{open:o} must be flagged");
}
for closed in [0o600, 0o400, 0o700, 0o500, 0o200] {
assert!(!keys_file_mode_too_open(closed), "{closed:o} must pass");
}
}
#[test]
fn strict_permissions_env_parsing() {
let _lock = TEST_ENCRYPTION_ENV_LOCK.blocking_lock();
let read = |value: Option<&str>| {
unsafe {
match value {
Some(v) => std::env::set_var(STRICT_KEY_FILE_PERMISSIONS_ENV, v),
None => std::env::remove_var(STRICT_KEY_FILE_PERMISSIONS_ENV),
}
}
strict_permissions_requested()
};
assert!(!read(None));
assert!(!read(Some("")));
assert!(!read(Some("0")));
assert!(!read(Some("no")));
assert!(read(Some("1")));
assert!(read(Some("true")));
assert!(read(Some("TRUE")));
assert!(read(Some("Yes")));
unsafe { std::env::remove_var(STRICT_KEY_FILE_PERMISSIONS_ENV) };
}
#[cfg(unix)]
#[test]
fn keys_file_permissions_strict_mode_fails_startup() {
use std::os::unix::fs::PermissionsExt;
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("keys.json");
std::fs::write(&path, "{}").unwrap();
let path_str = path.to_str().unwrap();
std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o644)).unwrap();
assert!(
check_keys_file_permissions(path_str, true).is_err(),
"strict + 0644"
);
assert!(
check_keys_file_permissions(path_str, false).is_ok(),
"warn-only + 0644"
);
std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600)).unwrap();
assert!(
check_keys_file_permissions(path_str, true).is_ok(),
"strict + 0600"
);
}
#[test]
fn env_key_source_detection() {
let _lock = TEST_ENCRYPTION_ENV_LOCK.blocking_lock();
unsafe {
std::env::remove_var("AUTH_STORAGE_ENCRYPTION_KEYS_FILE");
std::env::remove_var("AUTH_STORAGE_ENCRYPTION_KEY");
}
assert!(!env_key_source_in_use(), "no key configured at all");
unsafe { std::env::set_var("AUTH_STORAGE_ENCRYPTION_KEY", "irrelevant") };
assert!(
env_key_source_in_use(),
"no keys file => the env var is the source"
);
unsafe { std::env::set_var("AUTH_STORAGE_ENCRYPTION_KEYS_FILE", "/some/keys.json") };
assert!(!env_key_source_in_use(), "a keys file supports rotation");
unsafe {
std::env::remove_var("AUTH_STORAGE_ENCRYPTION_KEYS_FILE");
std::env::remove_var("AUTH_STORAGE_ENCRYPTION_KEY");
}
}
#[tokio::test]
async fn envelope_probe_finds_stored_envelopes_within_its_limit() {
let enc = StorageEncryption::new_random();
let storage = MemoryStorage::new();
storage
.store_kv("plain:1", b"just text", None)
.await
.unwrap();
assert!(
!stored_envelopes_exist(&storage, 10).await.unwrap(),
"plaintext only"
);
let sealed = enc.encrypt_for_storage(b"secret", b"sealed:1").unwrap();
storage.store_kv("sealed:1", &sealed, None).await.unwrap();
assert!(
stored_envelopes_exist(&storage, 10).await.unwrap(),
"envelope present"
);
assert!(!stored_envelopes_exist(&storage, 0).await.unwrap());
}
#[tokio::test]
async fn encrypted_storage_says_it_encrypts() {
let wrapped = EncryptedStorage::new(
MemoryStorage::new(),
StorageEncryption::new_random(),
false,
false,
);
assert!(wrapped.encrypts_kv_at_rest());
assert!(!MemoryStorage::new().encrypts_kv_at_rest());
let shared: std::sync::Arc<dyn AuthStorage> = std::sync::Arc::new(wrapped);
assert!(shared.encrypts_kv_at_rest(), "the Arc impl forwards");
}
}