1use crate::errors::{AuthError, Result};
2use crate::storage::{AuthStorage, SessionData};
3use crate::tokens::AuthToken;
4use aes_gcm::{
5 Aes256Gcm, Key, KeyInit, Nonce,
6 aead::{Aead, Payload},
7};
8use base64::{Engine, engine::general_purpose::STANDARD as BASE64};
9use serde::{Deserialize, Serialize};
10use std::collections::HashMap;
11use std::env;
12use std::fs;
13use std::time::Duration;
14use zeroize::Zeroize;
15
16#[cfg(test)]
35pub(crate) static TEST_ENCRYPTION_ENV_LOCK: tokio::sync::Mutex<()> =
36 tokio::sync::Mutex::const_new(());
37
38#[cfg(test)]
46pub(crate) struct EncryptionEnvGuard;
47
48#[cfg(test)]
49impl EncryptionEnvGuard {
50 pub(crate) fn set(key: &str) -> Self {
51 unsafe {
55 std::env::set_var("AUTH_STORAGE_ENCRYPTION_KEY", key);
56 std::env::remove_var("AUTH_STORAGE_ENCRYPTION_KEYS_FILE");
57 }
58 Self
59 }
60}
61
62#[cfg(test)]
63impl Drop for EncryptionEnvGuard {
64 fn drop(&mut self) {
65 unsafe {
68 std::env::remove_var("AUTH_STORAGE_ENCRYPTION_KEY");
69 }
70 }
71}
72
73const CURRENT_FORMAT_VERSION: u8 = 2;
87
88const FORMAT_V1: u8 = 1;
90
91const ALGORITHM: &str = "AES-256-GCM";
93
94const DECRYPT_FAILED: &str = "Decryption failed";
99
100fn bound_aad(v: u8, algorithm: &str, key_id: &str, record_aad: &[u8]) -> Vec<u8> {
107 let mut out = Vec::with_capacity(48 + algorithm.len() + key_id.len() + record_aad.len());
108 out.extend_from_slice(b"auth-framework/storage-envelope");
109 out.push(v);
110 for part in [algorithm.as_bytes(), key_id.as_bytes(), record_aad] {
111 out.extend_from_slice(&(part.len() as u32).to_be_bytes());
112 out.extend_from_slice(part);
113 }
114 out
115}
116
117fn default_format_version() -> u8 {
118 0
129}
130
131#[derive(Debug, Clone, Serialize, Deserialize)]
146pub struct EncryptedData {
147 pub data: String,
149 pub nonce: String,
151 pub algorithm: String,
153 #[serde(default)]
156 pub key_id: String,
157 #[serde(default = "default_format_version")]
162 pub v: u8,
163 #[serde(default)]
166 pub key_derivation: String,
167}
168
169pub trait KeyProvider: Send + Sync {
177 fn load_keys(&self) -> Result<LoadedKeys>;
185}
186
187pub struct LoadedKeys {
190 pub current_key_id: String,
191 pub keys: HashMap<String, [u8; 32]>,
196}
197
198pub struct EnvKeyProvider;
230
231impl KeyProvider for EnvKeyProvider {
232 fn load_keys(&self) -> Result<LoadedKeys> {
233 if let Ok(path) = env::var("AUTH_STORAGE_ENCRYPTION_KEYS_FILE") {
234 return Self::load_from_file(&path);
235 }
236
237 let mut key_data = env::var("AUTH_STORAGE_ENCRYPTION_KEY").map_err(|_| {
238 AuthError::config(
239 "No storage encryption key configured: set AUTH_STORAGE_ENCRYPTION_KEY \
240 (or AUTH_STORAGE_ENCRYPTION_KEYS_FILE for multi-key rotation). \
241 Refusing to start rather than silently storing data unencrypted.",
242 )
243 })?;
244 let key_id = env::var("AUTH_STORAGE_ENCRYPTION_KEY_ID").unwrap_or_else(|_| "1".to_string());
245 let key = decode_key(&key_data);
246 key_data.zeroize();
247 let key = key?;
248
249 let mut keys = HashMap::new();
250 keys.insert(key_id.clone(), key);
251 Ok(LoadedKeys {
252 current_key_id: key_id,
253 keys,
254 })
255 }
256}
257
258impl EnvKeyProvider {
259 fn load_from_file(path: &str) -> Result<LoadedKeys> {
260 #[derive(Deserialize)]
261 struct KeysFile {
262 current: String,
263 keys: HashMap<String, String>,
264 }
265
266 check_keys_file_permissions(path, strict_permissions_requested())?;
267
268 let mut contents = fs::read_to_string(path).map_err(|e| {
269 AuthError::config(format!(
270 "Failed to read AUTH_STORAGE_ENCRYPTION_KEYS_FILE '{path}': {e}"
271 ))
272 })?;
273 let parsed: Result<KeysFile> = serde_json::from_str(&contents).map_err(|e| {
274 AuthError::config(format!(
275 "Failed to parse AUTH_STORAGE_ENCRYPTION_KEYS_FILE '{path}': {e}"
276 ))
277 });
278 contents.zeroize();
279 let mut parsed = parsed?;
280
281 if !parsed.keys.contains_key(&parsed.current) {
282 for encoded in parsed.keys.values_mut() {
285 encoded.zeroize();
286 }
287 return Err(AuthError::config(format!(
288 "AUTH_STORAGE_ENCRYPTION_KEYS_FILE '{path}': current key id '{}' \
289 is not present in 'keys'",
290 parsed.current
291 )));
292 }
293
294 let mut keys = HashMap::with_capacity(parsed.keys.len());
303 let mut first_error = None;
304 for (id, mut encoded) in parsed.keys {
305 match decode_key(&encoded) {
306 Ok(key) => {
307 keys.insert(id, key);
308 }
309 Err(e) if first_error.is_none() => {
310 first_error = Some(e);
311 }
312 Err(_) => {}
313 }
314 encoded.zeroize();
315 }
316
317 if let Some(error) = first_error {
318 for key_bytes in keys.values_mut() {
319 key_bytes.zeroize();
320 }
321 return Err(error);
322 }
323
324 Ok(LoadedKeys {
325 current_key_id: parsed.current,
326 keys,
327 })
328 }
329}
330
331const STRICT_KEY_FILE_PERMISSIONS_ENV: &str = "AUTH_STORAGE_ENCRYPTION_STRICT_KEY_FILE_PERMISSIONS";
334
335#[cfg_attr(
338 not(unix),
339 allow(
340 dead_code,
341 reason = "only the Unix permission check calls it outside tests"
342 )
343)]
344fn keys_file_mode_too_open(mode: u32) -> bool {
345 mode & 0o077 != 0
346}
347
348fn strict_permissions_requested() -> bool {
349 env::var(STRICT_KEY_FILE_PERMISSIONS_ENV)
350 .map(|value| {
351 matches!(
352 value.trim().to_ascii_lowercase().as_str(),
353 "1" | "true" | "yes"
354 )
355 })
356 .unwrap_or(false)
357}
358
359fn check_keys_file_permissions(path: &str, strict: bool) -> Result<()> {
368 #[cfg(unix)]
369 {
370 use std::os::unix::fs::PermissionsExt;
371 if let Ok(metadata) = fs::metadata(path) {
372 let mode = metadata.permissions().mode();
373 if keys_file_mode_too_open(mode) {
374 if strict {
375 return Err(AuthError::config(format!(
376 "AUTH_STORAGE_ENCRYPTION_KEYS_FILE '{path}' has mode {:o}: it is \
377 accessible to group or other. Restrict it to the owner (chmod 600) \
378 or unset {STRICT_KEY_FILE_PERMISSIONS_ENV}.",
379 mode & 0o777
380 )));
381 }
382 tracing::warn!(
383 path = path,
384 mode = format!("{mode:o}"),
385 "AUTH_STORAGE_ENCRYPTION_KEYS_FILE is readable by group or other -- \
386 restrict it to the owner only (chmod 600), or set \
387 {STRICT_KEY_FILE_PERMISSIONS_ENV}=1 to make this fatal."
388 );
389 }
390 }
391 }
392 #[cfg(not(unix))]
393 {
394 let _ = path;
395 if strict {
396 tracing::warn!(
397 "{STRICT_KEY_FILE_PERMISSIONS_ENV} is set but key-file permissions cannot be \
398 inspected on this platform; it is not enforced."
399 );
400 }
401 }
402 Ok(())
403}
404
405pub(crate) fn env_key_source_in_use() -> bool {
411 env::var("AUTH_STORAGE_ENCRYPTION_KEYS_FILE").is_err()
412 && env::var("AUTH_STORAGE_ENCRYPTION_KEY").is_ok()
413}
414
415pub(crate) async fn stored_envelopes_exist<S: AuthStorage + ?Sized>(
419 storage: &S,
420 limit: usize,
421) -> Result<bool> {
422 for key in storage.list_kv_keys("").await?.into_iter().take(limit) {
423 if let Some(raw) = storage.get_kv(&key).await?
424 && StorageEncryption::looks_like_envelope(&raw)
425 {
426 return Ok(true);
427 }
428 }
429 Ok(false)
430}
431
432fn safe_log_id(key: &str) -> String {
450 use sha2::{Digest, Sha256};
451 let hash_hex = hex::encode(&Sha256::digest(key.as_bytes())[..8]);
452 match key.split_once(':') {
453 Some((namespace, _)) => format!("{namespace}:{hash_hex}"),
454 None => format!("key:{hash_hex}"),
455 }
456}
457
458fn decode_key(encoded: &str) -> Result<[u8; 32]> {
459 let mut key_bytes = BASE64
460 .decode(encoded)
461 .map_err(|_| AuthError::config("Invalid base64 in storage encryption key"))?;
462 if key_bytes.len() != 32 {
463 key_bytes.zeroize();
464 return Err(AuthError::config(
465 "Storage encryption key must be 32 bytes (256 bits) once base64-decoded",
466 ));
467 }
468 let mut key = [0u8; 32];
469 key.copy_from_slice(&key_bytes);
470 key_bytes.zeroize();
471 Ok(key)
472}
473
474pub struct StorageEncryption {
519 current_key_id: String,
520 ciphers: HashMap<String, Aes256Gcm>,
521}
522
523impl StorageEncryption {
524 pub fn new(provider: &dyn KeyProvider) -> Result<Self> {
528 let mut loaded = provider.load_keys()?;
529
530 let validation_error = if loaded.current_key_id.is_empty() {
535 Some(AuthError::config(
536 "Key provider's current_key_id must not be empty",
537 ))
538 } else if loaded.keys.keys().any(|id| id.is_empty()) {
539 Some(AuthError::config(
540 "Key provider returned a key with an empty id -- an empty id is reserved \
541 to mean \"format-version-0 envelope, no key id at all\"",
542 ))
543 } else if !loaded.keys.contains_key(&loaded.current_key_id) {
544 Some(AuthError::config(format!(
545 "Key provider's current_key_id '{}' is not among the keys it loaded",
546 loaded.current_key_id
547 )))
548 } else {
549 None
550 };
551
552 if let Some(error) = validation_error {
553 for key_bytes in loaded.keys.values_mut() {
554 key_bytes.zeroize();
555 }
556 return Err(error);
557 }
558
559 let ciphers = loaded
560 .keys
561 .iter()
562 .map(|(id, key_bytes)| {
563 let key = Key::<Aes256Gcm>::from_slice(key_bytes);
564 (id.clone(), Aes256Gcm::new(key))
565 })
566 .collect();
567 for key_bytes in loaded.keys.values_mut() {
571 key_bytes.zeroize();
572 }
573 Ok(Self {
574 current_key_id: loaded.current_key_id,
575 ciphers,
576 })
577 }
578
579 pub fn current_key_id(&self) -> &str {
581 &self.current_key_id
582 }
583
584 pub fn from_env() -> Result<Self> {
587 Self::new(&EnvKeyProvider)
588 }
589
590 #[cfg(test)]
592 pub fn new_random() -> Self {
593 use rand::Rng;
594 let mut key_bytes = [0u8; 32];
595 rand::rng().fill_bytes(&mut key_bytes);
596 let key = Key::<Aes256Gcm>::from_slice(&key_bytes);
597 let mut ciphers = HashMap::new();
598 ciphers.insert("test".to_string(), Aes256Gcm::new(key));
599 key_bytes.zeroize();
600 Self {
601 current_key_id: "test".to_string(),
602 ciphers,
603 }
604 }
605
606 pub fn generate_key() -> String {
609 use rand::Rng;
610 let mut key_bytes = [0u8; 32];
611 rand::rng().fill_bytes(&mut key_bytes);
612 let encoded = BASE64.encode(key_bytes);
613 key_bytes.zeroize();
614 encoded
615 }
616
617 pub fn encrypt(&self, plaintext: &[u8], aad: &[u8]) -> Result<EncryptedData> {
622 use rand::Rng;
623 let cipher = self.ciphers.get(&self.current_key_id).ok_or_else(|| {
624 AuthError::internal("Current encryption key missing from loaded cipher set")
625 })?;
626
627 let mut nonce_bytes = [0u8; 12];
635 rand::rng().fill_bytes(&mut nonce_bytes);
636 let nonce = Nonce::from_slice(&nonce_bytes);
637
638 let bound = bound_aad(CURRENT_FORMAT_VERSION, ALGORITHM, &self.current_key_id, aad);
639 let ciphertext = cipher
640 .encrypt(
641 nonce,
642 Payload {
643 msg: plaintext,
644 aad: &bound,
645 },
646 )
647 .map_err(|e| AuthError::internal(format!("Encryption failed: {}", e)))?;
648
649 Ok(EncryptedData {
650 data: BASE64.encode(&ciphertext),
651 nonce: BASE64.encode(nonce_bytes),
652 algorithm: ALGORITHM.to_string(),
653 key_id: self.current_key_id.clone(),
654 v: CURRENT_FORMAT_VERSION,
655 key_derivation: String::new(),
656 })
657 }
658
659 pub fn decrypt(&self, encrypted: &EncryptedData, aad: &[u8]) -> Result<Vec<u8>> {
670 let fail = |why: &str| -> AuthError {
673 tracing::warn!(
676 key_id = ?encrypted.key_id.chars().take(64).collect::<String>(),
677 v = encrypted.v,
678 "storage envelope decryption failed: {why}"
679 );
680 AuthError::internal(DECRYPT_FAILED)
681 };
682
683 if encrypted.algorithm != ALGORITHM {
684 return Err(fail("unsupported algorithm"));
685 }
686
687 let ciphertext = BASE64
688 .decode(&encrypted.data)
689 .map_err(|_| fail("invalid base64 in data"))?;
690 let nonce_bytes = BASE64
691 .decode(&encrypted.nonce)
692 .map_err(|_| fail("invalid base64 in nonce"))?;
693 if nonce_bytes.len() != 12 {
694 return Err(fail("invalid nonce length"));
695 }
696 let nonce = Nonce::from_slice(&nonce_bytes);
697
698 if encrypted.v == 0 {
699 for id in self.sorted_key_ids() {
703 if let Some(cipher) = self.ciphers.get(&id)
704 && let Ok(plaintext) = cipher.decrypt(
705 nonce,
706 Payload {
707 msg: &ciphertext,
708 aad: b"",
709 },
710 )
711 {
712 return Ok(plaintext);
713 }
714 }
715 return Err(fail("no loaded key opens this format-version-0 envelope"));
716 }
717
718 let cipher = self
719 .ciphers
720 .get(&encrypted.key_id)
721 .ok_or_else(|| fail("no loaded key for this key_id (rotated out?)"))?;
722
723 let bound;
726 let effective_aad: &[u8] = match encrypted.v {
727 FORMAT_V1 => aad,
728 CURRENT_FORMAT_VERSION => {
729 bound = bound_aad(encrypted.v, &encrypted.algorithm, &encrypted.key_id, aad);
730 &bound
731 }
732 _ => return Err(fail("unsupported envelope version")),
733 };
734
735 cipher
736 .decrypt(
737 nonce,
738 Payload {
739 msg: &ciphertext,
740 aad: effective_aad,
741 },
742 )
743 .map_err(|_| fail("authentication failed (wrong key, wrong record, or tampered)"))
744 }
745
746 pub fn encrypt_for_storage(&self, data: &[u8], aad: &[u8]) -> Result<Vec<u8>> {
750 let encrypted = self.encrypt(data, aad)?;
751 let serialized = serde_json::to_string(&encrypted).map_err(|e| {
752 AuthError::internal(format!("Failed to serialize encrypted data: {}", e))
753 })?;
754 Ok(serialized.into_bytes())
755 }
756
757 pub fn decrypt_from_storage(&self, data: &[u8], aad: &[u8]) -> Result<Vec<u8>> {
760 let parsed = std::str::from_utf8(data)
763 .map_err(|e| e.to_string())
764 .and_then(|s| serde_json::from_str::<EncryptedData>(s).map_err(|e| e.to_string()));
765 let encrypted = parsed.map_err(|why| {
766 tracing::warn!("stored value is not a readable envelope: {why}");
767 AuthError::internal(DECRYPT_FAILED)
768 })?;
769 self.decrypt(&encrypted, aad)
770 }
771
772 pub fn parse_envelope(data: &[u8]) -> Option<EncryptedData> {
783 let encrypted = std::str::from_utf8(data)
784 .ok()
785 .and_then(|s| serde_json::from_str::<EncryptedData>(s).ok())?;
786 if encrypted.algorithm != ALGORITHM {
787 return None;
788 }
789 let well_formed = if encrypted.v == 0 {
793 encrypted.key_id.is_empty()
794 } else {
795 !encrypted.key_id.is_empty()
796 };
797 well_formed.then_some(encrypted)
798 }
799
800 fn sorted_key_ids(&self) -> Vec<String> {
803 let mut ids: Vec<String> = self.ciphers.keys().cloned().collect();
804 ids.sort();
805 ids
806 }
807
808 pub fn looks_like_envelope(data: &[u8]) -> bool {
813 Self::parse_envelope(data).is_some()
814 }
815}
816
817pub struct EncryptedStorage<T> {
830 inner: T,
831 encryption: StorageEncryption,
832 allow_plaintext_reads: bool,
834 allow_legacy_v0: bool,
836}
837
838impl<T> EncryptedStorage<T> {
839 pub fn new(
862 storage: T,
863 encryption: StorageEncryption,
864 allow_plaintext_reads: bool,
865 allow_legacy_v0: bool,
866 ) -> Self {
867 Self {
868 inner: storage,
869 encryption,
870 allow_plaintext_reads,
871 allow_legacy_v0,
872 }
873 }
874
875 pub fn into_inner(self) -> T {
876 self.inner
877 }
878}
879
880#[async_trait::async_trait]
881impl<T> AuthStorage for EncryptedStorage<T>
882where
883 T: AuthStorage + Send + Sync,
884{
885 async fn store_token(&self, token: &AuthToken) -> Result<()> {
888 self.inner.store_token(token).await
889 }
890
891 async fn get_token(&self, token_id: &str) -> Result<Option<AuthToken>> {
892 self.inner.get_token(token_id).await
893 }
894
895 async fn get_token_by_access_token(&self, access_token: &str) -> Result<Option<AuthToken>> {
896 self.inner.get_token_by_access_token(access_token).await
897 }
898
899 async fn update_token(&self, token: &AuthToken) -> Result<()> {
900 self.inner.update_token(token).await
901 }
902
903 async fn delete_token(&self, token_id: &str) -> Result<()> {
904 self.inner.delete_token(token_id).await
905 }
906
907 async fn list_user_tokens(&self, user_id: &str) -> Result<Vec<AuthToken>> {
908 self.inner.list_user_tokens(user_id).await
909 }
910
911 async fn store_session(&self, session_id: &str, data: &SessionData) -> Result<()> {
912 self.inner.store_session(session_id, data).await
913 }
914
915 async fn get_session(&self, session_id: &str) -> Result<Option<SessionData>> {
916 self.inner.get_session(session_id).await
917 }
918
919 async fn delete_session(&self, session_id: &str) -> Result<()> {
920 self.inner.delete_session(session_id).await
921 }
922
923 async fn list_user_sessions(&self, user_id: &str) -> Result<Vec<SessionData>> {
924 self.inner.list_user_sessions(user_id).await
925 }
926
927 async fn count_active_sessions(&self) -> Result<u64> {
928 self.inner.count_active_sessions().await
929 }
930
931 async fn store_tokens_bulk(&self, tokens: &[AuthToken]) -> Result<()> {
937 self.inner.store_tokens_bulk(tokens).await
938 }
939
940 async fn delete_tokens_bulk(&self, token_ids: &[String]) -> Result<()> {
941 self.inner.delete_tokens_bulk(token_ids).await
942 }
943
944 async fn store_sessions_bulk(&self, sessions: &[(String, SessionData)]) -> Result<()> {
945 self.inner.store_sessions_bulk(sessions).await
946 }
947
948 async fn delete_sessions_bulk(&self, session_ids: &[String]) -> Result<()> {
949 self.inner.delete_sessions_bulk(session_ids).await
950 }
951
952 async fn get_kv_ttl(&self, key: &str) -> Result<Option<Duration>> {
955 self.inner.get_kv_ttl(key).await
957 }
958
959 async fn store_kv(&self, key: &str, value: &[u8], ttl: Option<Duration>) -> Result<()> {
960 let encrypted_value = self.encryption.encrypt_for_storage(value, key.as_bytes())?;
961 self.inner.store_kv(key, &encrypted_value, ttl).await
962 }
963
964 async fn store_kv_if_absent(
965 &self,
966 key: &str,
967 value: &[u8],
968 ttl: Option<Duration>,
969 ) -> Result<bool> {
970 let encrypted_value = self.encryption.encrypt_for_storage(value, key.as_bytes())?;
971 self.inner
972 .store_kv_if_absent(key, &encrypted_value, ttl)
973 .await
974 }
975
976 async fn swap_kv(
977 &self,
978 remove: &[String],
979 key: &str,
980 value: &[u8],
981 ttl: Option<Duration>,
982 ) -> Result<bool> {
983 let encrypted_value = self.encryption.encrypt_for_storage(value, key.as_bytes())?;
984 self.inner.swap_kv(remove, key, &encrypted_value, ttl).await
985 }
986
987 fn supports_atomic_swap(&self) -> bool {
988 self.inner.supports_atomic_swap()
989 }
990
991 async fn get_kv(&self, key: &str) -> Result<Option<Vec<u8>>> {
1007 let Some(raw) = self.inner.get_kv(key).await? else {
1008 return Ok(None);
1009 };
1010
1011 if let Some(envelope) = StorageEncryption::parse_envelope(&raw) {
1012 if envelope.v < CURRENT_FORMAT_VERSION && !self.allow_legacy_v0 {
1013 return Err(AuthError::internal(format!(
1014 "Value for record '{}' uses legacy envelope format version {} (its \
1015 metadata is not bound into the authenticated data), and \
1016 storage_encryption.allow_legacy_v0 is false. Run the migration tool \
1017 (`auth-framework-admin security encrypt-kv --accept-legacy-v0`) to \
1018 upgrade it to the current format, or temporarily set \
1019 storage_encryption.allow_legacy_v0 = true if something else needs to \
1020 read it first.",
1021 safe_log_id(key),
1022 envelope.v
1023 )));
1024 }
1025 let decrypted = self.encryption.decrypt(&envelope, key.as_bytes())?;
1026 return Ok(Some(decrypted));
1027 }
1028
1029 if self.allow_plaintext_reads {
1030 return Ok(Some(raw));
1031 }
1032
1033 Err(AuthError::internal(format!(
1034 "Value for record '{}' is not a valid encrypted envelope, and \
1035 storage_encryption.allow_plaintext_reads is false. If this key genuinely \
1036 predates encryption being enabled, run the migration tool \
1037 (`auth-framework-admin security encrypt-kv`) or temporarily set \
1038 storage_encryption.allow_plaintext_reads = true while migrating.",
1039 safe_log_id(key)
1040 )))
1041 }
1042
1043 fn tracks_kv_ttl(&self) -> bool {
1044 self.inner.tracks_kv_ttl()
1046 }
1047
1048 fn encrypts_kv_at_rest(&self) -> bool {
1049 true
1050 }
1051
1052 async fn delete_kv(&self, key: &str) -> Result<()> {
1053 self.inner.delete_kv(key).await
1054 }
1055
1056 async fn list_kv_keys(&self, prefix: &str) -> Result<Vec<String>> {
1062 self.inner.list_kv_keys(prefix).await
1063 }
1064
1065 async fn cleanup_expired(&self) -> Result<()> {
1066 self.inner.cleanup_expired().await
1067 }
1068}
1069
1070#[derive(Debug, Clone, Default, PartialEq, Eq)]
1078#[non_exhaustive]
1079pub struct KvEncryptionMigrationReport {
1080 pub dry_run: bool,
1082 pub scanned: u64,
1086 pub already_encrypted: u64,
1089 pub legacy_v0_found: u64,
1099 pub upgraded_from_legacy: u64,
1105 pub encrypted: u64,
1108 pub vanished: u64,
1111 pub failed: Vec<String>,
1122}
1123
1124#[derive(Debug, Clone, Copy, Default)]
1129#[non_exhaustive]
1130pub struct MigrationOptions {
1131 pub dry_run: bool,
1136 pub accept_legacy_v0: bool,
1141 pub accept_ttl_loss: bool,
1145}
1146
1147impl MigrationOptions {
1148 pub fn with_accept_ttl_loss(mut self, accept_ttl_loss: bool) -> Self {
1150 self.accept_ttl_loss = accept_ttl_loss;
1151 self
1152 }
1153
1154 pub fn with_dry_run(mut self, dry_run: bool) -> Self {
1160 self.dry_run = dry_run;
1161 self
1162 }
1163
1164 pub fn with_accept_legacy_v0(mut self, accept_legacy_v0: bool) -> Self {
1167 self.accept_legacy_v0 = accept_legacy_v0;
1168 self
1169 }
1170}
1171
1172pub async fn migrate_kv_to_encrypted<S: AuthStorage + ?Sized>(
1245 storage: &S,
1246 encryption: &StorageEncryption,
1247 prefix: &str,
1248 options: MigrationOptions,
1249) -> Result<KvEncryptionMigrationReport> {
1250 let keys = storage.list_kv_keys(prefix).await?;
1251 migrate_kv_keys_to_encrypted(storage, encryption, keys, options).await
1252}
1253
1254pub async fn migrate_kv_keys_to_encrypted<S: AuthStorage + ?Sized>(
1261 storage: &S,
1262 encryption: &StorageEncryption,
1263 keys: Vec<String>,
1264 options: MigrationOptions,
1265) -> Result<KvEncryptionMigrationReport> {
1266 let MigrationOptions {
1267 dry_run,
1268 accept_legacy_v0,
1269 accept_ttl_loss,
1270 } = options;
1271
1272 if !dry_run && !accept_ttl_loss && !storage.tracks_kv_ttl() {
1276 return Err(AuthError::validation(
1277 "This storage backend does not report KV TTLs, so migrating would make every \
1278 expiring entry (OAuth codes, MFA/SMS codes, rate-limit windows, expiring API \
1279 keys, ...) permanent. Scope the prefix to durable secrets and pass \
1280 accept_ttl_loss (CLI: --accept-ttl-loss) to proceed anyway.",
1281 ));
1282 }
1283 let mut report = KvEncryptionMigrationReport {
1284 dry_run,
1285 ..Default::default()
1286 };
1287
1288 report.scanned = keys.len() as u64;
1289
1290 for key in keys {
1291 let ttl = storage.get_kv_ttl(&key).await?;
1295 let Some(mut raw) = storage.get_kv(&key).await? else {
1296 report.vanished += 1;
1298 continue;
1299 };
1300
1301 if let Some(envelope) = StorageEncryption::parse_envelope(&raw) {
1302 if envelope.v >= CURRENT_FORMAT_VERSION {
1303 report.already_encrypted += 1;
1304 continue;
1305 }
1306
1307 match encryption.decrypt(&envelope, key.as_bytes()) {
1311 Err(_) => {
1312 tracing::warn!(
1313 record = %safe_log_id(&key),
1314 "migrate_kv_to_encrypted: could not decrypt format-version-0 \
1315 envelope with any loaded key -- skipping, not aborting the rest \
1316 of the run"
1317 );
1318 report.failed.push(safe_log_id(&key));
1319 }
1320 Ok(mut plaintext) => {
1321 report.legacy_v0_found += 1;
1322 if !dry_run && accept_legacy_v0 {
1323 if envelope.v == 0 {
1324 tracing::warn!(
1325 record = %safe_log_id(&key),
1326 "migrate_kv_to_encrypted: upgrading format-version-0 \
1327 envelope to the current format -- v0 has no AAD, so this \
1328 plaintext's association with this specific key was not \
1329 cryptographically verified by this upgrade"
1330 );
1331 } else {
1332 tracing::info!(
1333 record = %safe_log_id(&key),
1334 v = envelope.v,
1335 "migrate_kv_to_encrypted: upgrading legacy envelope to the \
1336 current format (its AAD bound the record key)"
1337 );
1338 }
1339 let encrypt_result =
1340 encryption.encrypt_for_storage(&plaintext, key.as_bytes());
1341 plaintext.zeroize();
1342 let new_envelope = encrypt_result?;
1343 storage.store_kv(&key, &new_envelope, ttl).await?;
1344 report.upgraded_from_legacy += 1;
1345 } else {
1346 plaintext.zeroize();
1347 }
1348 }
1349 }
1350 continue;
1351 }
1352
1353 report.encrypted += 1;
1354 if !dry_run {
1355 let encrypt_result = encryption.encrypt_for_storage(&raw, key.as_bytes());
1356 raw.zeroize();
1357 let envelope = encrypt_result?;
1358 storage.store_kv(&key, &envelope, ttl).await?;
1359 } else {
1360 raw.zeroize();
1361 }
1362 }
1363
1364 Ok(report)
1365}
1366
1367#[derive(Debug, Clone, Default, PartialEq, Eq)]
1369pub struct KvRewrapReport {
1370 pub dry_run: bool,
1372 pub scanned: u64,
1374 pub rewrapped: u64,
1377 pub already_current: u64,
1379 pub plaintext_skipped: u64,
1382 pub legacy_skipped: u64,
1385 pub vanished: u64,
1387 pub failed: Vec<String>,
1390}
1391
1392pub async fn rewrap_kv_keys<S: AuthStorage + ?Sized>(
1400 storage: &S,
1401 encryption: &StorageEncryption,
1402 keys: Vec<String>,
1403 dry_run: bool,
1404) -> Result<KvRewrapReport> {
1405 let mut report = KvRewrapReport {
1406 dry_run,
1407 scanned: keys.len() as u64,
1408 ..Default::default()
1409 };
1410 for key in keys {
1411 let ttl = storage.get_kv_ttl(&key).await?;
1414 let Some(raw) = storage.get_kv(&key).await? else {
1415 report.vanished += 1;
1416 continue;
1417 };
1418 let Some(envelope) = StorageEncryption::parse_envelope(&raw) else {
1419 report.plaintext_skipped += 1;
1420 continue;
1421 };
1422 if envelope.v < CURRENT_FORMAT_VERSION {
1423 report.legacy_skipped += 1;
1424 continue;
1425 }
1426 if envelope.key_id == encryption.current_key_id() {
1427 report.already_current += 1;
1428 continue;
1429 }
1430 match encryption.decrypt(&envelope, key.as_bytes()) {
1431 Err(_) => {
1432 tracing::warn!(
1433 record = %safe_log_id(&key),
1434 "rewrap_kv_keys: could not decrypt an envelope with any loaded key -- \
1435 leaving it as it is"
1436 );
1437 report.failed.push(safe_log_id(&key));
1438 }
1439 Ok(mut plaintext) => {
1440 if !dry_run {
1441 let encrypted = encryption.encrypt_for_storage(&plaintext, key.as_bytes());
1442 plaintext.zeroize();
1443 storage.store_kv(&key, &encrypted?, ttl).await?;
1444 } else {
1445 plaintext.zeroize();
1446 }
1447 report.rewrapped += 1;
1448 }
1449 }
1450 }
1451 Ok(report)
1452}
1453
1454#[cfg(test)]
1455mod tests {
1456 use super::*;
1457 use crate::storage::MemoryStorage;
1458
1459 #[test]
1460 fn test_key_generation() {
1461 let key = StorageEncryption::generate_key();
1462 assert!(!key.is_empty());
1463 let decoded = BASE64.decode(&key).unwrap();
1464 assert_eq!(decoded.len(), 32);
1465 }
1466
1467 #[test]
1468 fn test_encrypt_decrypt_roundtrip() {
1469 let enc = StorageEncryption::new_random();
1470 let plaintext = b"super secret totp seed, not utf8 safe either: \xff\xfe";
1471 let encrypted = enc.encrypt(plaintext, b"user:alice:totp_secret").unwrap();
1472 let decrypted = enc.decrypt(&encrypted, b"user:alice:totp_secret").unwrap();
1473 assert_eq!(decrypted, plaintext);
1474 }
1475
1476 #[test]
1482 fn test_decrypt_rejects_wrong_aad() {
1483 let enc = StorageEncryption::new_random();
1484 let encrypted = enc
1485 .encrypt(b"alice's secret", b"user:alice:totp_secret")
1486 .unwrap();
1487 let result = enc.decrypt(&encrypted, b"user:bob:totp_secret");
1488 assert!(
1489 result.is_err(),
1490 "decrypting with the wrong AAD (a different record's key) must fail"
1491 );
1492 }
1493
1494 #[test]
1498 fn test_nonces_are_unique_across_many_encryptions() {
1499 let enc = StorageEncryption::new_random();
1500 let mut seen = std::collections::HashSet::new();
1501 for _ in 0..1000 {
1502 let encrypted = enc
1503 .encrypt(b"same plaintext every time", b"same:aad")
1504 .unwrap();
1505 assert_eq!(
1506 BASE64.decode(&encrypted.nonce).unwrap().len(),
1507 12,
1508 "nonce must be 96 bits"
1509 );
1510 assert!(
1511 seen.insert(encrypted.nonce.clone()),
1512 "nonce reused across encryptions -- this breaks AES-GCM's security guarantee"
1513 );
1514 }
1515 }
1516
1517 #[test]
1518 fn test_storage_roundtrip_non_utf8_bytes() {
1519 let enc = StorageEncryption::new_random();
1520 let raw_salt: &[u8] = &[0xDE, 0xAD, 0xBE, 0xEF, 0x00, 0xFF, 0x80, 0x81];
1521 let stored = enc.encrypt_for_storage(raw_salt, b"salt:key").unwrap();
1522 let restored = enc.decrypt_from_storage(&stored, b"salt:key").unwrap();
1523 assert_eq!(restored, raw_salt);
1524 }
1525
1526 struct EmptyKeyProvider;
1530 impl KeyProvider for EmptyKeyProvider {
1531 fn load_keys(&self) -> Result<LoadedKeys> {
1532 Err(AuthError::config("no key configured (test)"))
1533 }
1534 }
1535
1536 #[test]
1537 fn test_construction_fails_closed_with_no_key() {
1538 let result = StorageEncryption::new(&EmptyKeyProvider);
1539 assert!(
1540 result.is_err(),
1541 "StorageEncryption::new must fail, not silently construct an unusable/no-op encryptor"
1542 );
1543 }
1544
1545 struct FixedKeyProvider(LoadedKeys);
1546 impl KeyProvider for FixedKeyProvider {
1547 fn load_keys(&self) -> Result<LoadedKeys> {
1548 Ok(LoadedKeys {
1549 current_key_id: self.0.current_key_id.clone(),
1550 keys: self.0.keys.clone(),
1551 })
1552 }
1553 }
1554
1555 #[test]
1556 fn test_construction_rejects_empty_key_id() {
1557 let mut keys = HashMap::new();
1563 keys.insert("1".to_string(), [1u8; 32]);
1564 keys.insert(String::new(), [2u8; 32]);
1565 let result = StorageEncryption::new(&FixedKeyProvider(LoadedKeys {
1566 current_key_id: "1".to_string(),
1567 keys,
1568 }));
1569 assert!(
1570 result.is_err(),
1571 "an empty key id anywhere in the loaded key set must be rejected (it's reserved \
1572 for format-version-0 envelopes), even when current_key_id itself is valid"
1573 );
1574 }
1575
1576 struct TwoKeyProvider {
1580 current_id: String,
1581 old_key: [u8; 32],
1582 new_key: [u8; 32],
1583 old_id: String,
1584 }
1585 impl KeyProvider for TwoKeyProvider {
1586 fn load_keys(&self) -> Result<LoadedKeys> {
1587 let mut keys = HashMap::new();
1588 keys.insert(self.old_id.clone(), self.old_key);
1589 keys.insert(self.current_id.clone(), self.new_key);
1590 Ok(LoadedKeys {
1591 current_key_id: self.current_id.clone(),
1592 keys,
1593 })
1594 }
1595 }
1596
1597 #[test]
1598 fn test_old_key_still_decrypts_after_rotation() {
1599 let mut keys = HashMap::new();
1600 keys.insert("1".to_string(), [7u8; 32]);
1601 let enc_before_rotation = StorageEncryption::new(&FixedKeyProvider(LoadedKeys {
1602 current_key_id: "1".to_string(),
1603 keys,
1604 }))
1605 .unwrap();
1606 let old_envelope = enc_before_rotation
1607 .encrypt(b"written before rotation", b"some:key")
1608 .unwrap();
1609 assert_eq!(old_envelope.key_id, "1");
1610
1611 let provider = TwoKeyProvider {
1613 current_id: "2".to_string(),
1614 old_id: "1".to_string(),
1615 old_key: [7u8; 32],
1616 new_key: [9u8; 32],
1617 };
1618 let enc_after_rotation = StorageEncryption::new(&provider).unwrap();
1619
1620 let new_envelope = enc_after_rotation
1622 .encrypt(b"written after rotation", b"some:key")
1623 .unwrap();
1624 assert_eq!(new_envelope.key_id, "2");
1625
1626 let decrypted_old = enc_after_rotation
1628 .decrypt(&old_envelope, b"some:key")
1629 .unwrap();
1630 assert_eq!(decrypted_old, b"written before rotation");
1631 }
1632
1633 #[test]
1639 fn test_decrypts_format_version_0_envelope() {
1640 let mut keys = HashMap::new();
1641 keys.insert("1".to_string(), [3u8; 32]);
1642 let enc = StorageEncryption::new(&FixedKeyProvider(LoadedKeys {
1643 current_key_id: "1".to_string(),
1644 keys,
1645 }))
1646 .unwrap();
1647
1648 let cipher = {
1651 let key = Key::<Aes256Gcm>::from_slice(&[3u8; 32]);
1652 Aes256Gcm::new(key)
1653 };
1654 let nonce_bytes = [5u8; 12];
1655 let nonce = Nonce::from_slice(&nonce_bytes);
1656 let ciphertext = cipher
1657 .encrypt(nonce, b"legacy-format plaintext".as_ref())
1658 .unwrap();
1659 let legacy_json = format!(
1660 r#"{{"data":"{}","nonce":"{}","algorithm":"AES-256-GCM","key_derivation":"direct"}}"#,
1661 BASE64.encode(&ciphertext),
1662 BASE64.encode(nonce_bytes)
1663 );
1664
1665 assert!(StorageEncryption::looks_like_envelope(
1666 legacy_json.as_bytes()
1667 ));
1668 let decrypted = enc
1669 .decrypt_from_storage(legacy_json.as_bytes(), b"irrelevant-for-v0")
1670 .unwrap();
1671 assert_eq!(decrypted, b"legacy-format plaintext".to_vec());
1672 }
1673
1674 #[tokio::test]
1684 async fn test_wrapper_rejects_v1_envelope_downgraded_to_look_like_v0() {
1685 let mut keys = HashMap::new();
1686 keys.insert("1".to_string(), [4u8; 32]);
1687 let encryption = StorageEncryption::new(&FixedKeyProvider(LoadedKeys {
1688 current_key_id: "1".to_string(),
1689 keys,
1690 }))
1691 .unwrap();
1692
1693 let inner = MemoryStorage::new();
1694 let wrapped = EncryptedStorage::new(inner, encryption, false, false);
1695
1696 wrapped
1697 .store_kv("user:alice:totp_secret", b"real secret", None)
1698 .await
1699 .unwrap();
1700
1701 let inner = wrapped.into_inner();
1702 let real_envelope: EncryptedData = serde_json::from_slice(
1703 &inner
1704 .get_kv("user:alice:totp_secret")
1705 .await
1706 .unwrap()
1707 .unwrap(),
1708 )
1709 .unwrap();
1710
1711 let downgraded_json = serde_json::json!({
1714 "data": real_envelope.data,
1715 "nonce": real_envelope.nonce,
1716 "algorithm": real_envelope.algorithm,
1717 })
1718 .to_string();
1719 inner
1720 .store_kv("user:alice:totp_secret", downgraded_json.as_bytes(), None)
1721 .await
1722 .unwrap();
1723
1724 let mut keys2 = HashMap::new();
1725 keys2.insert("1".to_string(), [4u8; 32]);
1726 let encryption2 = StorageEncryption::new(&FixedKeyProvider(LoadedKeys {
1727 current_key_id: "1".to_string(),
1728 keys: keys2,
1729 }))
1730 .unwrap();
1731 let wrapped = EncryptedStorage::new(inner, encryption2, false, false);
1732
1733 let result = wrapped.get_kv("user:alice:totp_secret").await;
1734 assert!(
1735 result.is_err(),
1736 "a v1 envelope downgraded to look like v0 must not be accepted as the record's \
1737 value, with allow_legacy_v0 at its default (false)"
1738 );
1739 }
1740
1741 #[tokio::test]
1742 async fn test_list_kv_keys_passes_through_unencrypted() {
1743 let inner = MemoryStorage::new();
1744 inner
1745 .store_kv("prefix:a", b"ignored by this test", None)
1746 .await
1747 .unwrap();
1748 inner
1749 .store_kv("prefix:b", b"ignored by this test", None)
1750 .await
1751 .unwrap();
1752 let wrapped = EncryptedStorage::new(inner, StorageEncryption::new_random(), false, false);
1753
1754 let mut keys = wrapped.list_kv_keys("prefix:").await.unwrap();
1755 keys.sort();
1756 assert_eq!(
1757 keys,
1758 vec!["prefix:a".to_string(), "prefix:b".to_string()],
1759 "list_kv_keys must pass through to the inner backend, not use the trait's \
1760 empty-Vec default"
1761 );
1762 }
1763
1764 #[tokio::test]
1765 async fn test_encrypted_storage_roundtrip() {
1766 let inner = MemoryStorage::new();
1767 let wrapped = EncryptedStorage::new(inner, StorageEncryption::new_random(), false, false);
1768
1769 wrapped
1770 .store_kv("user:alice:totp_secret", b"JBSWY3DPEHPK3PXP", None)
1771 .await
1772 .unwrap();
1773 let value = wrapped.get_kv("user:alice:totp_secret").await.unwrap();
1774 assert_eq!(value, Some(b"JBSWY3DPEHPK3PXP".to_vec()));
1775 }
1776
1777 #[tokio::test]
1781 async fn test_encrypted_storage_actually_encrypts_the_underlying_value() {
1782 let wrapped = EncryptedStorage::new(
1783 MemoryStorage::new(),
1784 StorageEncryption::new_random(),
1785 false,
1786 false,
1787 );
1788
1789 wrapped
1790 .store_kv("user:alice:totp_secret", b"JBSWY3DPEHPK3PXP", None)
1791 .await
1792 .unwrap();
1793
1794 let inner = wrapped.into_inner();
1795 let raw = inner
1796 .get_kv("user:alice:totp_secret")
1797 .await
1798 .unwrap()
1799 .unwrap();
1800 assert_ne!(
1801 raw,
1802 b"JBSWY3DPEHPK3PXP".to_vec(),
1803 "the underlying storage must not hold the plaintext value"
1804 );
1805 assert!(
1806 StorageEncryption::looks_like_envelope(&raw),
1807 "the underlying storage must hold a proper encrypted envelope"
1808 );
1809 }
1810
1811 #[tokio::test]
1819 async fn test_wrapper_rejects_ciphertext_swapped_between_records() {
1820 let mut keys = HashMap::new();
1821 keys.insert("1".to_string(), [11u8; 32]);
1822 let loaded = LoadedKeys {
1823 current_key_id: "1".to_string(),
1824 keys,
1825 };
1826 let encryption_for_wrapper = StorageEncryption::new(&FixedKeyProvider(LoadedKeys {
1827 current_key_id: loaded.current_key_id.clone(),
1828 keys: loaded.keys.clone(),
1829 }))
1830 .unwrap();
1831 let encryption_for_verification =
1835 StorageEncryption::new(&FixedKeyProvider(loaded)).unwrap();
1836
1837 let inner = MemoryStorage::new();
1838 let wrapped = EncryptedStorage::new(inner, encryption_for_wrapper, false, false);
1839
1840 wrapped
1841 .store_kv("user:alice:totp_secret", b"alice-secret", None)
1842 .await
1843 .unwrap();
1844
1845 let inner = wrapped.into_inner();
1846 let raw = inner
1847 .get_kv("user:alice:totp_secret")
1848 .await
1849 .unwrap()
1850 .unwrap();
1851
1852 let decrypted = encryption_for_verification
1855 .decrypt(
1856 &serde_json::from_slice(&raw).unwrap(),
1857 b"user:alice:totp_secret",
1858 )
1859 .unwrap();
1860 assert_eq!(decrypted, b"alice-secret".to_vec());
1861
1862 let wrong_aad_result = encryption_for_verification.decrypt(
1867 &serde_json::from_slice(&raw).unwrap(),
1868 b"user:bob:totp_secret",
1869 );
1870 assert!(
1871 wrong_aad_result.is_err(),
1872 "the wrapper's envelope must not decrypt under a different record's key name -- \
1873 if it does, the wrapper is using a constant AAD instead of the real storage key"
1874 );
1875 }
1876
1877 #[tokio::test]
1882 async fn test_reads_legacy_plaintext_when_allowed() {
1883 let inner = MemoryStorage::new();
1884 inner
1885 .store_kv("legacy:key", b"pre-existing plaintext value", None)
1886 .await
1887 .unwrap();
1888 let wrapped = EncryptedStorage::new(inner, StorageEncryption::new_random(), true, false);
1889
1890 let value = wrapped.get_kv("legacy:key").await.unwrap();
1891 assert_eq!(value, Some(b"pre-existing plaintext value".to_vec()));
1892 }
1893
1894 #[tokio::test]
1902 async fn test_rejects_non_envelope_value_when_plaintext_reads_disallowed() {
1903 let inner = MemoryStorage::new();
1904 inner
1905 .store_kv("user:alice:totp_secret", b"attacker-chosen-plaintext", None)
1906 .await
1907 .unwrap();
1908 let wrapped = EncryptedStorage::new(inner, StorageEncryption::new_random(), false, false);
1909
1910 let result = wrapped.get_kv("user:alice:totp_secret").await;
1911 assert!(
1912 result.is_err(),
1913 "a non-envelope value must be rejected, not silently treated as plaintext, \
1914 when allow_plaintext_reads is false"
1915 );
1916 }
1917
1918 #[tokio::test]
1923 async fn test_migration_upgrades_v0_envelope_to_current_format() {
1924 let mut keys = HashMap::new();
1925 keys.insert("1".to_string(), [6u8; 32]);
1926 let encryption = StorageEncryption::new(&FixedKeyProvider(LoadedKeys {
1927 current_key_id: "1".to_string(),
1928 keys,
1929 }))
1930 .unwrap();
1931
1932 let cipher = {
1935 let key = Key::<Aes256Gcm>::from_slice(&[6u8; 32]);
1936 Aes256Gcm::new(key)
1937 };
1938 let nonce_bytes = [8u8; 12];
1939 let nonce = Nonce::from_slice(&nonce_bytes);
1940 let ciphertext = cipher.encrypt(nonce, b"v0 secret".as_ref()).unwrap();
1941 let v0_json = format!(
1942 r#"{{"data":"{}","nonce":"{}","algorithm":"AES-256-GCM","key_derivation":"direct"}}"#,
1943 BASE64.encode(&ciphertext),
1944 BASE64.encode(nonce_bytes)
1945 );
1946
1947 let storage = MemoryStorage::new();
1948 storage
1949 .store_kv("secret:legacy", v0_json.as_bytes(), None)
1950 .await
1951 .unwrap();
1952
1953 let report = migrate_kv_to_encrypted(
1954 &storage,
1955 &encryption,
1956 "secret:",
1957 MigrationOptions {
1958 dry_run: false,
1959 accept_legacy_v0: true,
1960 ..Default::default()
1961 },
1962 )
1963 .await
1964 .unwrap();
1965 assert_eq!(
1966 report.legacy_v0_found, 1,
1967 "a decryptable v0 envelope must be counted as found"
1968 );
1969 assert_eq!(
1970 report.upgraded_from_legacy, 1,
1971 "with accept_legacy_v0 true on a real run, it must actually be upgraded"
1972 );
1973 assert_eq!(report.already_encrypted, 0);
1974 assert!(report.failed.is_empty());
1975
1976 let raw_after = storage.get_kv("secret:legacy").await.unwrap().unwrap();
1977 let envelope_after: EncryptedData = serde_json::from_slice(&raw_after).unwrap();
1978 assert_eq!(
1979 envelope_after.v, CURRENT_FORMAT_VERSION,
1980 "the stored envelope must now be the current format, not still v0"
1981 );
1982 assert!(
1983 !envelope_after.key_id.is_empty(),
1984 "the upgraded envelope must have a real key_id"
1985 );
1986
1987 let decrypted = encryption
1990 .decrypt(&envelope_after, b"secret:legacy")
1991 .unwrap();
1992 assert_eq!(decrypted, b"v0 secret".to_vec());
1993
1994 let report2 = migrate_kv_to_encrypted(
1996 &storage,
1997 &encryption,
1998 "secret:",
1999 MigrationOptions {
2000 dry_run: false,
2001 accept_legacy_v0: false,
2002 ..Default::default()
2003 },
2004 )
2005 .await
2006 .unwrap();
2007 assert_eq!(report2.upgraded_from_legacy, 0);
2008 assert_eq!(report2.already_encrypted, 1);
2009 }
2010
2011 #[tokio::test]
2016 async fn test_migration_does_not_upgrade_legacy_v0_without_accept_flag() {
2017 let mut keys = HashMap::new();
2018 keys.insert("1".to_string(), [7u8; 32]);
2019 let encryption = StorageEncryption::new(&FixedKeyProvider(LoadedKeys {
2020 current_key_id: "1".to_string(),
2021 keys,
2022 }))
2023 .unwrap();
2024
2025 let cipher = {
2026 let key = Key::<Aes256Gcm>::from_slice(&[7u8; 32]);
2027 Aes256Gcm::new(key)
2028 };
2029 let nonce_bytes = [3u8; 12];
2030 let nonce = Nonce::from_slice(&nonce_bytes);
2031 let ciphertext = cipher.encrypt(nonce, b"v0 secret".as_ref()).unwrap();
2032 let v0_json = format!(
2033 r#"{{"data":"{}","nonce":"{}","algorithm":"AES-256-GCM","key_derivation":"direct"}}"#,
2034 BASE64.encode(&ciphertext),
2035 BASE64.encode(nonce_bytes)
2036 );
2037
2038 let storage = MemoryStorage::new();
2039 storage
2040 .store_kv("secret:legacy", v0_json.as_bytes(), None)
2041 .await
2042 .unwrap();
2043
2044 let report = migrate_kv_to_encrypted(
2046 &storage,
2047 &encryption,
2048 "secret:",
2049 MigrationOptions {
2050 dry_run: false,
2051 accept_legacy_v0: false,
2052 ..Default::default()
2053 },
2054 )
2055 .await
2056 .unwrap();
2057 assert_eq!(
2058 report.legacy_v0_found, 1,
2059 "the v0 envelope must still be detected/decrypted"
2060 );
2061 assert_eq!(
2062 report.upgraded_from_legacy, 0,
2063 "without accept_legacy_v0, nothing must actually be rewritten"
2064 );
2065
2066 let raw_after = storage.get_kv("secret:legacy").await.unwrap().unwrap();
2067 assert_eq!(
2068 raw_after,
2069 v0_json.as_bytes(),
2070 "the stored envelope must be byte-for-byte unchanged without accept_legacy_v0"
2071 );
2072 }
2073
2074 #[tokio::test]
2079 async fn test_migration_skips_undecryptable_v0_envelope_without_aborting() {
2080 let mut keys = HashMap::new();
2081 keys.insert("1".to_string(), [9u8; 32]);
2082 let encryption = StorageEncryption::new(&FixedKeyProvider(LoadedKeys {
2083 current_key_id: "1".to_string(),
2084 keys,
2085 }))
2086 .unwrap();
2087
2088 let bad_cipher = {
2091 let key = Key::<Aes256Gcm>::from_slice(&[0u8; 32]);
2092 Aes256Gcm::new(key)
2093 };
2094 let nonce_bytes = [1u8; 12];
2095 let nonce = Nonce::from_slice(&nonce_bytes);
2096 let bad_ciphertext = bad_cipher
2097 .encrypt(nonce, b"undecryptable".as_ref())
2098 .unwrap();
2099 let bad_v0_json = format!(
2100 r#"{{"data":"{}","nonce":"{}","algorithm":"AES-256-GCM","key_derivation":"direct"}}"#,
2101 BASE64.encode(&bad_ciphertext),
2102 BASE64.encode(nonce_bytes)
2103 );
2104
2105 let storage = MemoryStorage::new();
2106 storage
2107 .store_kv("secret:bad", bad_v0_json.as_bytes(), None)
2108 .await
2109 .unwrap();
2110 storage
2111 .store_kv("secret:good_a", b"plaintext-a", None)
2112 .await
2113 .unwrap();
2114 storage
2115 .store_kv("secret:good_b", b"plaintext-b", None)
2116 .await
2117 .unwrap();
2118
2119 let report = migrate_kv_to_encrypted(
2120 &storage,
2121 &encryption,
2122 "secret:",
2123 MigrationOptions {
2124 dry_run: false,
2125 accept_legacy_v0: true,
2126 ..Default::default()
2127 },
2128 )
2129 .await
2130 .expect("one undecryptable record must not abort the whole migration");
2131
2132 assert_eq!(report.scanned, 3);
2133 assert_eq!(
2134 report.failed,
2135 vec![safe_log_id("secret:bad")],
2136 "the undecryptable record must be named (as a safe identifier, not the raw \
2137 key) in `failed`, not silently dropped"
2138 );
2139 assert_eq!(
2140 report.encrypted, 2,
2141 "the other two plaintext keys must still be processed despite the bad one"
2142 );
2143
2144 let good_a_after = storage.get_kv("secret:good_a").await.unwrap().unwrap();
2145 assert!(StorageEncryption::looks_like_envelope(&good_a_after));
2146 let good_b_after = storage.get_kv("secret:good_b").await.unwrap().unwrap();
2147 assert!(StorageEncryption::looks_like_envelope(&good_b_after));
2148
2149 let bad_after = storage.get_kv("secret:bad").await.unwrap().unwrap();
2151 assert_eq!(bad_after, bad_v0_json.as_bytes());
2152 }
2153
2154 #[tokio::test]
2159 async fn test_migration_dry_run_detects_undecryptable_v0_envelope() {
2160 let mut keys = HashMap::new();
2161 keys.insert("1".to_string(), [5u8; 32]);
2162 let encryption = StorageEncryption::new(&FixedKeyProvider(LoadedKeys {
2163 current_key_id: "1".to_string(),
2164 keys,
2165 }))
2166 .unwrap();
2167
2168 let bad_cipher = {
2169 let key = Key::<Aes256Gcm>::from_slice(&[0u8; 32]);
2170 Aes256Gcm::new(key)
2171 };
2172 let nonce_bytes = [2u8; 12];
2173 let nonce = Nonce::from_slice(&nonce_bytes);
2174 let bad_ciphertext = bad_cipher
2175 .encrypt(nonce, b"undecryptable".as_ref())
2176 .unwrap();
2177 let bad_v0_json = format!(
2178 r#"{{"data":"{}","nonce":"{}","algorithm":"AES-256-GCM","key_derivation":"direct"}}"#,
2179 BASE64.encode(&bad_ciphertext),
2180 BASE64.encode(nonce_bytes)
2181 );
2182
2183 let storage = MemoryStorage::new();
2184 storage
2185 .store_kv("secret:bad", bad_v0_json.as_bytes(), None)
2186 .await
2187 .unwrap();
2188
2189 let dry_report = migrate_kv_to_encrypted(
2190 &storage,
2191 &encryption,
2192 "secret:",
2193 MigrationOptions {
2194 dry_run: true,
2195 accept_legacy_v0: true,
2196 ..Default::default()
2197 },
2198 )
2199 .await
2200 .unwrap();
2201 assert_eq!(
2202 dry_report.failed,
2203 vec![safe_log_id("secret:bad")],
2204 "a dry run must actually attempt the decrypt and report the same failure a \
2205 real run would, not optimistically assume every v0 envelope would succeed"
2206 );
2207 assert_eq!(dry_report.upgraded_from_legacy, 0);
2208 assert_eq!(dry_report.legacy_v0_found, 0);
2209 }
2210
2211 #[test]
2216 fn test_safe_log_id_never_contains_the_raw_secret() {
2217 let raw_secret = "ak_live_super_secret_bearer_token_12345";
2218 let key = format!("api_key:{raw_secret}");
2219 let id = safe_log_id(&key);
2220
2221 assert!(
2222 !id.contains(raw_secret),
2223 "safe_log_id must never contain the raw secret portion of the key, got: {id}"
2224 );
2225 assert!(
2226 id.starts_with("api_key:"),
2227 "safe_log_id should keep the (non-secret) namespace prefix, got: {id}"
2228 );
2229 assert_eq!(id, safe_log_id(&key));
2233 }
2234
2235 #[test]
2240 fn test_safe_log_id_handles_colonless_key_without_leaking_it() {
2241 let raw_secret = "a_bearer_token_with_no_colon_in_it_at_all";
2242 let id = safe_log_id(raw_secret);
2243
2244 assert!(
2245 !id.contains(raw_secret),
2246 "a colonless key must not appear verbatim in its safe_log_id, got: {id}"
2247 );
2248 assert!(
2249 id.starts_with("key:"),
2250 "a colonless key should fall back to the literal 'key:' prefix, got: {id}"
2251 );
2252 }
2253
2254 #[tokio::test]
2261 async fn test_dry_run_with_accept_legacy_v0_does_not_write_a_decryptable_v0_record() {
2262 let mut keys = HashMap::new();
2263 keys.insert("1".to_string(), [4u8; 32]);
2264 let encryption = StorageEncryption::new(&FixedKeyProvider(LoadedKeys {
2265 current_key_id: "1".to_string(),
2266 keys,
2267 }))
2268 .unwrap();
2269
2270 let cipher = {
2271 let key = Key::<Aes256Gcm>::from_slice(&[4u8; 32]);
2272 Aes256Gcm::new(key)
2273 };
2274 let nonce_bytes = [6u8; 12];
2275 let nonce = Nonce::from_slice(&nonce_bytes);
2276 let ciphertext = cipher.encrypt(nonce, b"v0 secret".as_ref()).unwrap();
2277 let v0_json = format!(
2278 r#"{{"data":"{}","nonce":"{}","algorithm":"AES-256-GCM","key_derivation":"direct"}}"#,
2279 BASE64.encode(&ciphertext),
2280 BASE64.encode(nonce_bytes)
2281 );
2282
2283 let storage = MemoryStorage::new();
2284 storage
2285 .store_kv("secret:legacy", v0_json.as_bytes(), None)
2286 .await
2287 .unwrap();
2288
2289 let report = migrate_kv_to_encrypted(
2291 &storage,
2292 &encryption,
2293 "secret:",
2294 MigrationOptions {
2295 dry_run: true,
2296 accept_legacy_v0: true,
2297 ..Default::default()
2298 },
2299 )
2300 .await
2301 .unwrap();
2302
2303 assert_eq!(
2304 report.legacy_v0_found, 1,
2305 "a dry run must still report a decryptable v0 record as found"
2306 );
2307 assert_eq!(
2308 report.upgraded_from_legacy, 0,
2309 "a dry run must never actually upgrade anything, even with accept_legacy_v0 true"
2310 );
2311
2312 let raw_after = storage.get_kv("secret:legacy").await.unwrap().unwrap();
2313 assert_eq!(
2314 raw_after,
2315 v0_json.as_bytes(),
2316 "a dry run with accept_legacy_v0 true must leave the record byte-for-byte \
2317 unchanged"
2318 );
2319 }
2320
2321 #[tokio::test]
2322 async fn test_migration_dry_run_reports_without_writing() {
2323 let storage = MemoryStorage::new();
2324 storage
2325 .store_kv("secret:a", b"plaintext-a", None)
2326 .await
2327 .unwrap();
2328 storage
2329 .store_kv("secret:b", b"plaintext-b", None)
2330 .await
2331 .unwrap();
2332 let encryption = StorageEncryption::new_random();
2333
2334 let report = migrate_kv_to_encrypted(
2335 &storage,
2336 &encryption,
2337 "secret:",
2338 MigrationOptions {
2339 dry_run: true,
2340 accept_legacy_v0: false,
2341 ..Default::default()
2342 },
2343 )
2344 .await
2345 .unwrap();
2346
2347 assert!(report.dry_run);
2348 assert_eq!(report.scanned, 2);
2349 assert_eq!(report.encrypted, 2);
2350 assert_eq!(report.already_encrypted, 0);
2351
2352 let still_plaintext = storage.get_kv("secret:a").await.unwrap().unwrap();
2354 assert_eq!(still_plaintext, b"plaintext-a".to_vec());
2355 }
2356
2357 #[tokio::test]
2358 async fn test_migration_encrypts_plaintext_values() {
2359 let storage = MemoryStorage::new();
2360 storage
2361 .store_kv("secret:a", b"plaintext-a", None)
2362 .await
2363 .unwrap();
2364 let encryption = StorageEncryption::new_random();
2365
2366 let report = migrate_kv_to_encrypted(
2367 &storage,
2368 &encryption,
2369 "secret:",
2370 MigrationOptions {
2371 dry_run: false,
2372 accept_legacy_v0: false,
2373 ..Default::default()
2374 },
2375 )
2376 .await
2377 .unwrap();
2378 assert_eq!(report.encrypted, 1);
2379
2380 let raw = storage.get_kv("secret:a").await.unwrap().unwrap();
2381 assert!(StorageEncryption::looks_like_envelope(&raw));
2382 let decrypted = encryption.decrypt_from_storage(&raw, b"secret:a").unwrap();
2383 assert_eq!(decrypted, b"plaintext-a".to_vec());
2384 }
2385
2386 #[tokio::test]
2391 async fn test_migration_is_idempotent_and_resumable() {
2392 let storage = MemoryStorage::new();
2393 storage
2394 .store_kv("secret:a", b"plaintext-a", None)
2395 .await
2396 .unwrap();
2397 storage
2398 .store_kv("secret:b", b"plaintext-b", None)
2399 .await
2400 .unwrap();
2401 let encryption = StorageEncryption::new_random();
2402
2403 let envelope_a = encryption
2406 .encrypt_for_storage(b"plaintext-a", b"secret:a")
2407 .unwrap();
2408 storage
2409 .store_kv("secret:a", &envelope_a, None)
2410 .await
2411 .unwrap();
2412
2413 let report = migrate_kv_to_encrypted(
2416 &storage,
2417 &encryption,
2418 "secret:",
2419 MigrationOptions {
2420 dry_run: false,
2421 accept_legacy_v0: false,
2422 ..Default::default()
2423 },
2424 )
2425 .await
2426 .unwrap();
2427 assert_eq!(report.scanned, 2);
2428 assert_eq!(report.already_encrypted, 1);
2429 assert_eq!(report.encrypted, 1);
2430
2431 let raw_a_after = storage.get_kv("secret:a").await.unwrap().unwrap();
2432 assert_eq!(
2433 raw_a_after, envelope_a,
2434 "an already-encrypted value must be left byte-for-byte unchanged, not double-encrypted"
2435 );
2436 let raw_b_after = storage.get_kv("secret:b").await.unwrap().unwrap();
2437 assert!(StorageEncryption::looks_like_envelope(&raw_b_after));
2438
2439 let report2 = migrate_kv_to_encrypted(
2441 &storage,
2442 &encryption,
2443 "secret:",
2444 MigrationOptions {
2445 dry_run: false,
2446 accept_legacy_v0: false,
2447 ..Default::default()
2448 },
2449 )
2450 .await
2451 .unwrap();
2452 assert_eq!(report2.already_encrypted, 2);
2453 assert_eq!(report2.encrypted, 0);
2454 }
2455
2456 #[tokio::test]
2457 async fn test_migration_only_touches_matching_prefix() {
2458 let storage = MemoryStorage::new();
2459 storage
2460 .store_kv("secret:a", b"plaintext-a", None)
2461 .await
2462 .unwrap();
2463 storage
2464 .store_kv("other:b", b"plaintext-b", None)
2465 .await
2466 .unwrap();
2467 let encryption = StorageEncryption::new_random();
2468
2469 let report = migrate_kv_to_encrypted(
2470 &storage,
2471 &encryption,
2472 "secret:",
2473 MigrationOptions {
2474 dry_run: false,
2475 accept_legacy_v0: false,
2476 ..Default::default()
2477 },
2478 )
2479 .await
2480 .unwrap();
2481 assert_eq!(report.scanned, 1);
2482
2483 let other_untouched = storage.get_kv("other:b").await.unwrap().unwrap();
2484 assert_eq!(
2485 other_untouched,
2486 b"plaintext-b".to_vec(),
2487 "a key outside the given prefix must not be touched"
2488 );
2489 }
2490
2491 #[tokio::test]
2494 async fn wrapper_passes_kv_ttl_through() {
2495 let wrapped = EncryptedStorage::new(
2496 MemoryStorage::new(),
2497 StorageEncryption::new_random(),
2498 false,
2499 false,
2500 );
2501 wrapped
2502 .store_kv("k", b"v", Some(Duration::from_secs(600)))
2503 .await
2504 .unwrap();
2505 let ttl = wrapped.get_kv_ttl("k").await.unwrap().unwrap();
2506 assert!(ttl > Duration::from_secs(590) && ttl <= Duration::from_secs(600));
2507 }
2508
2509 struct FixedKeys {
2512 current: &'static str,
2513 keys: Vec<(&'static str, [u8; 32])>,
2514 }
2515
2516 impl KeyProvider for FixedKeys {
2517 fn load_keys(&self) -> Result<LoadedKeys> {
2518 Ok(LoadedKeys {
2519 current_key_id: self.current.to_string(),
2520 keys: self
2521 .keys
2522 .iter()
2523 .map(|(id, key)| (id.to_string(), *key))
2524 .collect(),
2525 })
2526 }
2527 }
2528
2529 const KEY_A: [u8; 32] = [0x11; 32];
2530 const KEY_B: [u8; 32] = [0x22; 32];
2531
2532 fn manual_envelope(
2535 key: &[u8; 32],
2536 key_id: &str,
2537 v: u8,
2538 plaintext: &[u8],
2539 aad: &[u8],
2540 ) -> Vec<u8> {
2541 let cipher = Aes256Gcm::new(Key::<Aes256Gcm>::from_slice(key));
2542 let nonce_bytes = [7u8; 12];
2543 let ciphertext = cipher
2544 .encrypt(
2545 Nonce::from_slice(&nonce_bytes),
2546 Payload {
2547 msg: plaintext,
2548 aad,
2549 },
2550 )
2551 .unwrap();
2552 serde_json::to_vec(&EncryptedData {
2553 data: BASE64.encode(ciphertext),
2554 nonce: BASE64.encode(nonce_bytes),
2555 algorithm: "AES-256-GCM".to_string(),
2556 key_id: key_id.to_string(),
2557 v,
2558 key_derivation: String::new(),
2559 })
2560 .unwrap()
2561 }
2562
2563 #[test]
2564 fn new_envelopes_use_format_v2() {
2565 let enc = StorageEncryption::new_random();
2566 assert_eq!(enc.encrypt(b"x", b"k").unwrap().v, 2);
2567 }
2568
2569 #[test]
2574 fn v2_aad_binds_key_id_and_version() {
2575 let enc = StorageEncryption::new(&FixedKeys {
2576 current: "a",
2577 keys: vec![("a", KEY_A), ("b", KEY_A)],
2578 })
2579 .unwrap();
2580 let envelope = enc.encrypt(b"secret", b"rec:1").unwrap();
2581 assert_eq!(enc.decrypt(&envelope, b"rec:1").unwrap(), b"secret");
2582
2583 let mut relabelled = envelope.clone();
2584 relabelled.key_id = "b".to_string();
2585 assert!(
2586 enc.decrypt(&relabelled, b"rec:1").is_err(),
2587 "relabelling key_id must fail authentication"
2588 );
2589
2590 let mut downgraded = envelope.clone();
2591 downgraded.v = 1;
2592 assert!(
2593 enc.decrypt(&downgraded, b"rec:1").is_err(),
2594 "rewriting v to 1 must not make a v2 ciphertext verify"
2595 );
2596 }
2597
2598 #[tokio::test]
2602 async fn v1_envelopes_are_legacy_and_migrate_to_v2() {
2603 let storage = MemoryStorage::new();
2604 storage
2605 .store_kv(
2606 "rec:1",
2607 &manual_envelope(&KEY_A, "1", 1, b"secret", b"rec:1"),
2608 None,
2609 )
2610 .await
2611 .unwrap();
2612 let provider = || FixedKeys {
2613 current: "1",
2614 keys: vec![("1", KEY_A)],
2615 };
2616
2617 let strict = EncryptedStorage::new(
2618 storage.clone(),
2619 StorageEncryption::new(&provider()).unwrap(),
2620 false,
2621 false,
2622 );
2623 assert!(
2624 strict.get_kv("rec:1").await.is_err(),
2625 "v1 must need the legacy policy"
2626 );
2627
2628 let lenient = EncryptedStorage::new(
2629 storage.clone(),
2630 StorageEncryption::new(&provider()).unwrap(),
2631 false,
2632 true,
2633 );
2634 assert_eq!(lenient.get_kv("rec:1").await.unwrap().unwrap(), b"secret");
2635
2636 let report = migrate_kv_to_encrypted(
2637 &storage,
2638 &StorageEncryption::new(&provider()).unwrap(),
2639 "",
2640 MigrationOptions::default().with_accept_legacy_v0(true),
2641 )
2642 .await
2643 .unwrap();
2644 assert_eq!(report.upgraded_from_legacy, 1, "{report:?}");
2645
2646 let raw = storage.get_kv("rec:1").await.unwrap().unwrap();
2647 assert_eq!(StorageEncryption::parse_envelope(&raw).unwrap().v, 2);
2648 let strict_after = EncryptedStorage::new(
2650 storage,
2651 StorageEncryption::new(&provider()).unwrap(),
2652 false,
2653 false,
2654 );
2655 assert_eq!(
2656 strict_after.get_kv("rec:1").await.unwrap().unwrap(),
2657 b"secret"
2658 );
2659 }
2660
2661 #[tokio::test]
2664 async fn upgraded_records_cannot_be_swapped_between_keys() {
2665 let storage = MemoryStorage::new();
2666 for (key, secret) in [("rec:1", &b"one"[..]), ("rec:2", b"two")] {
2667 storage
2668 .store_kv(key, &manual_envelope(&KEY_A, "1", 0, secret, b""), None)
2669 .await
2670 .unwrap();
2671 }
2672 let provider = || FixedKeys {
2673 current: "1",
2674 keys: vec![("1", KEY_A)],
2675 };
2676 migrate_kv_to_encrypted(
2677 &storage,
2678 &StorageEncryption::new(&provider()).unwrap(),
2679 "",
2680 MigrationOptions::default().with_accept_legacy_v0(true),
2681 )
2682 .await
2683 .unwrap();
2684
2685 let swapped = storage.get_kv("rec:1").await.unwrap().unwrap();
2686 storage.store_kv("rec:2", &swapped, None).await.unwrap();
2687 let strict = EncryptedStorage::new(
2688 storage,
2689 StorageEncryption::new(&provider()).unwrap(),
2690 false,
2691 false,
2692 );
2693 assert!(strict.get_kv("rec:2").await.is_err());
2694 }
2695
2696 #[test]
2699 fn envelope_classification_requires_version_and_key_id() {
2700 let shape = |extra: &str| {
2701 format!(
2702 r#"{{"data":"AAAA","nonce":"AAAAAAAAAAAAAAAA","algorithm":"AES-256-GCM"{extra}}}"#
2703 )
2704 };
2705 assert!(StorageEncryption::parse_envelope(shape(r#","v":2"#).as_bytes()).is_none());
2707 assert!(
2709 StorageEncryption::parse_envelope(shape(r#","v":1,"key_id":"""#).as_bytes()).is_none()
2710 );
2711 assert!(
2713 StorageEncryption::parse_envelope(shape(r#","v":2,"key_id":"1""#).as_bytes()).is_some()
2714 );
2715 assert!(StorageEncryption::parse_envelope(shape("").as_bytes()).is_some());
2717 }
2718
2719 #[test]
2722 fn decrypt_failures_share_one_error_text() {
2723 let enc = StorageEncryption::new(&FixedKeys {
2724 current: "a",
2725 keys: vec![("a", KEY_A), ("b", KEY_B)],
2726 })
2727 .unwrap();
2728 let good = enc.encrypt(b"secret", b"rec:1").unwrap();
2729
2730 let mut bad_base64 = good.clone();
2731 bad_base64.data = "!!not base64!!".to_string();
2732 let mut short_nonce = good.clone();
2733 short_nonce.nonce = BASE64.encode([1u8; 4]);
2734 let mut unknown_key = good.clone();
2735 unknown_key.key_id = "zzz".to_string();
2736 let mut wrong_algorithm = good.clone();
2737 wrong_algorithm.algorithm = "ROT13".to_string();
2738 let mut tampered = good.clone();
2739 let mut raw = BASE64.decode(&tampered.data).unwrap();
2740 raw[0] ^= 0x01;
2741 tampered.data = BASE64.encode(raw);
2742
2743 let messages: Vec<String> = [
2744 (&bad_base64, &b"rec:1"[..]),
2745 (&short_nonce, b"rec:1"),
2746 (&unknown_key, b"rec:1"),
2747 (&wrong_algorithm, b"rec:1"),
2748 (&tampered, b"rec:1"),
2749 (&good, b"rec:OTHER"),
2750 ]
2751 .iter()
2752 .map(|(envelope, aad)| enc.decrypt(envelope, aad).unwrap_err().to_string())
2753 .collect();
2754 assert!(
2755 messages.windows(2).all(|w| w[0] == w[1]),
2756 "decrypt failures must be indistinguishable, got: {messages:#?}"
2757 );
2758 }
2759
2760 #[test]
2761 fn legacy_trial_decryption_order_is_stable() {
2762 let enc = StorageEncryption::new(&FixedKeys {
2763 current: "k0",
2764 keys: (0..8)
2765 .map(|i| {
2766 let id: &'static str = Box::leak(format!("k{i}").into_boxed_str());
2767 (id, [i as u8 + 1; 32])
2768 })
2769 .rev()
2770 .collect(),
2771 })
2772 .unwrap();
2773 let ids = enc.sorted_key_ids();
2774 let mut expected = ids.clone();
2775 expected.sort();
2776 assert_eq!(ids, expected);
2777 assert_eq!(ids.len(), 8);
2778 }
2779
2780 #[test]
2781 fn safe_log_id_keeps_eight_hash_bytes() {
2782 let id = safe_log_id("api_key:abc123");
2783 let hash = id.strip_prefix("api_key:").unwrap();
2784 assert_eq!(hash.len(), 16, "8 bytes = 16 hex chars, got {id}");
2785 let colonless = safe_log_id("rawsecret");
2786 assert_eq!(colonless.strip_prefix("key:").unwrap().len(), 16);
2787 }
2788
2789 fn load_with_env(key: Option<&str>) -> Result<LoadedKeys> {
2792 let _lock = TEST_ENCRYPTION_ENV_LOCK.blocking_lock();
2793 unsafe {
2795 std::env::remove_var("AUTH_STORAGE_ENCRYPTION_KEYS_FILE");
2796 match key {
2797 Some(key) => std::env::set_var("AUTH_STORAGE_ENCRYPTION_KEY", key),
2798 None => std::env::remove_var("AUTH_STORAGE_ENCRYPTION_KEY"),
2799 }
2800 }
2801 let result = EnvKeyProvider.load_keys();
2802 unsafe { std::env::remove_var("AUTH_STORAGE_ENCRYPTION_KEY") };
2804 result
2805 }
2806
2807 #[test]
2808 fn malformed_env_keys_fail_closed() {
2809 assert!(load_with_env(None).is_err(), "no key at all");
2810 assert!(load_with_env(Some("")).is_err(), "empty key");
2811 assert!(
2812 load_with_env(Some("!!!not base64!!!")).is_err(),
2813 "bad base64"
2814 );
2815 assert!(
2816 load_with_env(Some(&BASE64.encode([1u8; 16]))).is_err(),
2817 "16-byte key"
2818 );
2819 assert!(
2820 load_with_env(Some(&BASE64.encode([1u8; 33]))).is_err(),
2821 "33-byte key"
2822 );
2823 assert!(load_with_env(Some(&BASE64.encode([1u8; 32]))).is_ok());
2824 }
2825
2826 #[test]
2827 fn malformed_keys_file_fails_closed() {
2828 let dir = tempfile::tempdir().unwrap();
2829 let good = BASE64.encode([3u8; 32]);
2830 let cases: [(&str, String); 4] = [
2831 ("not json", "{{{".to_string()),
2832 (
2833 "current missing from keys",
2834 format!(r#"{{"current":"x","keys":{{"1":"{good}"}}}}"#),
2835 ),
2836 (
2837 "one malformed entry",
2838 format!(r#"{{"current":"1","keys":{{"1":"{good}","2":"short"}}}}"#),
2839 ),
2840 ("empty keys", r#"{"current":"1","keys":{}}"#.to_string()),
2841 ];
2842 let _lock = TEST_ENCRYPTION_ENV_LOCK.blocking_lock();
2843 for (name, body) in cases {
2844 let path = dir.path().join("keys.json");
2845 std::fs::write(&path, body).unwrap();
2846 unsafe {
2848 std::env::set_var("AUTH_STORAGE_ENCRYPTION_KEYS_FILE", &path);
2849 }
2850 let result = EnvKeyProvider.load_keys();
2851 unsafe { std::env::remove_var("AUTH_STORAGE_ENCRYPTION_KEYS_FILE") };
2853 assert!(result.is_err(), "{name} must fail closed");
2854 }
2855 }
2856
2857 fn ttl_provider() -> FixedKeys {
2860 FixedKeys {
2861 current: "1",
2862 keys: vec![("1", KEY_A)],
2863 }
2864 }
2865
2866 #[tokio::test]
2867 async fn migration_preserves_ttl_when_encrypting_plaintext() {
2868 let storage = MemoryStorage::new();
2869 storage
2870 .store_kv("otp:1", b"123456", Some(Duration::from_secs(600)))
2871 .await
2872 .unwrap();
2873 storage.store_kv("durable:1", b"keep", None).await.unwrap();
2874
2875 migrate_kv_to_encrypted(
2876 &storage,
2877 &StorageEncryption::new(&ttl_provider()).unwrap(),
2878 "",
2879 MigrationOptions::default(),
2880 )
2881 .await
2882 .unwrap();
2883
2884 let ttl = storage.get_kv_ttl("otp:1").await.unwrap().unwrap();
2885 assert!(
2886 ttl > Duration::from_secs(590) && ttl <= Duration::from_secs(600),
2887 "TTL must survive migration, got {ttl:?}"
2888 );
2889 assert_eq!(storage.get_kv_ttl("durable:1").await.unwrap(), None);
2890 let raw = storage.get_kv("otp:1").await.unwrap().unwrap();
2891 assert!(
2892 StorageEncryption::looks_like_envelope(&raw),
2893 "must be encrypted"
2894 );
2895 }
2896
2897 #[tokio::test]
2898 async fn legacy_upgrade_preserves_ttl() {
2899 let storage = MemoryStorage::new();
2900 storage
2901 .store_kv(
2902 "rec:1",
2903 &manual_envelope(&KEY_A, "", 0, b"secret", b""),
2904 Some(Duration::from_secs(600)),
2905 )
2906 .await
2907 .unwrap();
2908
2909 migrate_kv_to_encrypted(
2910 &storage,
2911 &StorageEncryption::new(&ttl_provider()).unwrap(),
2912 "",
2913 MigrationOptions::default().with_accept_legacy_v0(true),
2914 )
2915 .await
2916 .unwrap();
2917
2918 let ttl = storage.get_kv_ttl("rec:1").await.unwrap().unwrap();
2919 assert!(ttl > Duration::from_secs(590) && ttl <= Duration::from_secs(600));
2920 let raw = storage.get_kv("rec:1").await.unwrap().unwrap();
2921 assert_eq!(
2922 StorageEncryption::parse_envelope(&raw).unwrap().v,
2923 CURRENT_FORMAT_VERSION
2924 );
2925 }
2926
2927 #[tokio::test]
2931 async fn migration_refuses_backend_that_cannot_report_ttl_without_opt_in() {
2932 let storage = crate::testing::utilities::MockStorage::new();
2933 let encryption = StorageEncryption::new(&ttl_provider()).unwrap();
2934
2935 assert!(
2936 migrate_kv_to_encrypted(&storage, &encryption, "", MigrationOptions::default())
2937 .await
2938 .is_err(),
2939 "a real run on a TTL-blind backend must be refused"
2940 );
2941 assert!(
2942 migrate_kv_to_encrypted(
2943 &storage,
2944 &encryption,
2945 "",
2946 MigrationOptions::default().with_dry_run(true)
2947 )
2948 .await
2949 .is_ok(),
2950 "a dry run writes nothing, so it is allowed"
2951 );
2952 assert!(
2953 migrate_kv_to_encrypted(
2954 &storage,
2955 &encryption,
2956 "",
2957 MigrationOptions::default().with_accept_ttl_loss(true)
2958 )
2959 .await
2960 .is_ok(),
2961 "explicit opt-in proceeds"
2962 );
2963 }
2964
2965 #[tokio::test]
2966 async fn backends_that_honour_ttl_say_so() {
2967 let memory = MemoryStorage::new();
2968 assert!(memory.tracks_kv_ttl());
2969 let wrapped = EncryptedStorage::new(
2970 MemoryStorage::new(),
2971 StorageEncryption::new_random(),
2972 false,
2973 false,
2974 );
2975 assert!(
2976 wrapped.tracks_kv_ttl(),
2977 "the wrapper forwards the inner answer"
2978 );
2979 let shared: std::sync::Arc<dyn AuthStorage> = std::sync::Arc::new(MemoryStorage::new());
2980 assert!(shared.tracks_kv_ttl(), "the Arc impl forwards too");
2981 assert!(
2982 !crate::testing::utilities::MockStorage::new().tracks_kv_ttl(),
2983 "a backend that ignores TTLs must say so"
2984 );
2985 }
2986
2987 #[test]
2990 fn keys_file_mode_check_flags_group_and_other_access() {
2991 for open in [0o644, 0o640, 0o604, 0o660, 0o666, 0o777, 0o601, 0o610] {
2992 assert!(keys_file_mode_too_open(open), "{open:o} must be flagged");
2993 }
2994 for closed in [0o600, 0o400, 0o700, 0o500, 0o200] {
2995 assert!(!keys_file_mode_too_open(closed), "{closed:o} must pass");
2996 }
2997 }
2998
2999 #[test]
3000 fn strict_permissions_env_parsing() {
3001 let _lock = TEST_ENCRYPTION_ENV_LOCK.blocking_lock();
3002 let read = |value: Option<&str>| {
3003 unsafe {
3005 match value {
3006 Some(v) => std::env::set_var(STRICT_KEY_FILE_PERMISSIONS_ENV, v),
3007 None => std::env::remove_var(STRICT_KEY_FILE_PERMISSIONS_ENV),
3008 }
3009 }
3010 strict_permissions_requested()
3011 };
3012 assert!(!read(None));
3013 assert!(!read(Some("")));
3014 assert!(!read(Some("0")));
3015 assert!(!read(Some("no")));
3016 assert!(read(Some("1")));
3017 assert!(read(Some("true")));
3018 assert!(read(Some("TRUE")));
3019 assert!(read(Some("Yes")));
3020 unsafe { std::env::remove_var(STRICT_KEY_FILE_PERMISSIONS_ENV) };
3022 }
3023
3024 #[cfg(unix)]
3026 #[test]
3027 fn keys_file_permissions_strict_mode_fails_startup() {
3028 use std::os::unix::fs::PermissionsExt;
3029 let dir = tempfile::tempdir().unwrap();
3030 let path = dir.path().join("keys.json");
3031 std::fs::write(&path, "{}").unwrap();
3032 let path_str = path.to_str().unwrap();
3033
3034 std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o644)).unwrap();
3035 assert!(
3036 check_keys_file_permissions(path_str, true).is_err(),
3037 "strict + 0644"
3038 );
3039 assert!(
3040 check_keys_file_permissions(path_str, false).is_ok(),
3041 "warn-only + 0644"
3042 );
3043
3044 std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o600)).unwrap();
3045 assert!(
3046 check_keys_file_permissions(path_str, true).is_ok(),
3047 "strict + 0600"
3048 );
3049 }
3050
3051 #[test]
3052 fn env_key_source_detection() {
3053 let _lock = TEST_ENCRYPTION_ENV_LOCK.blocking_lock();
3054 unsafe {
3056 std::env::remove_var("AUTH_STORAGE_ENCRYPTION_KEYS_FILE");
3057 std::env::remove_var("AUTH_STORAGE_ENCRYPTION_KEY");
3058 }
3059 assert!(!env_key_source_in_use(), "no key configured at all");
3060 unsafe { std::env::set_var("AUTH_STORAGE_ENCRYPTION_KEY", "irrelevant") };
3062 assert!(
3063 env_key_source_in_use(),
3064 "no keys file => the env var is the source"
3065 );
3066 unsafe { std::env::set_var("AUTH_STORAGE_ENCRYPTION_KEYS_FILE", "/some/keys.json") };
3068 assert!(!env_key_source_in_use(), "a keys file supports rotation");
3069 unsafe {
3071 std::env::remove_var("AUTH_STORAGE_ENCRYPTION_KEYS_FILE");
3072 std::env::remove_var("AUTH_STORAGE_ENCRYPTION_KEY");
3073 }
3074 }
3075
3076 #[tokio::test]
3077 async fn envelope_probe_finds_stored_envelopes_within_its_limit() {
3078 let enc = StorageEncryption::new_random();
3079 let storage = MemoryStorage::new();
3080 storage
3081 .store_kv("plain:1", b"just text", None)
3082 .await
3083 .unwrap();
3084 assert!(
3085 !stored_envelopes_exist(&storage, 10).await.unwrap(),
3086 "plaintext only"
3087 );
3088
3089 let sealed = enc.encrypt_for_storage(b"secret", b"sealed:1").unwrap();
3090 storage.store_kv("sealed:1", &sealed, None).await.unwrap();
3091 assert!(
3092 stored_envelopes_exist(&storage, 10).await.unwrap(),
3093 "envelope present"
3094 );
3095
3096 assert!(!stored_envelopes_exist(&storage, 0).await.unwrap());
3098 }
3099
3100 #[tokio::test]
3101 async fn encrypted_storage_says_it_encrypts() {
3102 let wrapped = EncryptedStorage::new(
3103 MemoryStorage::new(),
3104 StorageEncryption::new_random(),
3105 false,
3106 false,
3107 );
3108 assert!(wrapped.encrypts_kv_at_rest());
3109 assert!(!MemoryStorage::new().encrypts_kv_at_rest());
3110 let shared: std::sync::Arc<dyn AuthStorage> = std::sync::Arc::new(wrapped);
3111 assert!(shared.encrypts_kv_at_rest(), "the Arc impl forwards");
3112 }
3113}