Skip to main content

auth_framework/storage/
encryption.rs

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/// Serializes the tests in this crate's lib-unit-test binary that
17/// EXPLICITLY read or write `AUTH_STORAGE_ENCRYPTION_KEY`/
18/// `AUTH_STORAGE_ENCRYPTION_KEYS_FILE` via this lock, since those are
19/// process-global state shared across all tests running in parallel
20/// threads within one `cargo test --lib` invocation. Acquire this (and
21/// clean up the env var via [`EncryptionEnvGuard`], not a bare
22/// `set_var`/`remove_var` pair) in any new test that touches those
23/// variables.
24///
25/// **Not a guarantee every such test already does** -- some pre-existing
26/// tests elsewhere in this crate build a persistent storage backend
27/// through the real factory (and therefore read these env vars via
28/// [`StorageEncryption::from_env`]) without taking this lock first; that
29/// gap predates this lock and isn't closed by introducing it.
30/// A `tokio::sync::Mutex`, not `std::sync::Mutex`, because several callers
31/// (in `#[tokio::test]` functions) need to hold this guard across `.await`
32/// points -- use `.lock().await` there, or `.blocking_lock()` in a plain
33/// (non-async) `#[test]`.
34#[cfg(test)]
35pub(crate) static TEST_ENCRYPTION_ENV_LOCK: tokio::sync::Mutex<()> =
36    tokio::sync::Mutex::const_new(());
37
38/// RAII guard that sets `AUTH_STORAGE_ENCRYPTION_KEY` for the lifetime of
39/// the guard and removes it on drop -- including on an early return or a
40/// panic (e.g. from an `assert!`/`.unwrap()` failure), unlike a bare
41/// `set_var` at the top of a test and a `remove_var` at the bottom, which
42/// leaks the variable if the test fails before reaching that last line.
43/// Callers should hold [`TEST_ENCRYPTION_ENV_LOCK`] for the guard's entire
44/// lifetime.
45#[cfg(test)]
46pub(crate) struct EncryptionEnvGuard;
47
48#[cfg(test)]
49impl EncryptionEnvGuard {
50    pub(crate) fn set(key: &str) -> Self {
51        // SAFETY: sound against every caller that ALSO takes
52        // `TEST_ENCRYPTION_ENV_LOCK`; NOT sound otherwise (see the
53        // lock's own doc for which pre-existing tests don't).
54        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        // SAFETY: see `EncryptionEnvGuard::set` -- the same lock is held
66        // for this guard's entire lifetime, including this drop.
67        unsafe {
68            std::env::remove_var("AUTH_STORAGE_ENCRYPTION_KEY");
69        }
70    }
71}
72
73/// Current envelope format version. Bumped whenever the envelope's fields
74/// or decryption rules change in a way that needs disambiguating from
75/// older data still on disk.
76///
77/// * `0` -- the original public `EncryptedStorage`: no `key_id`, no AAD.
78/// * `1` -- versioned `key_id`; AAD is the bare storage key, so the
79///   envelope's own metadata (`v`, `key_id`, `algorithm`) is NOT
80///   authenticated.
81/// * `2` -- AAD binds the metadata too (see [`bound_aad`]).
82///
83/// Versions below the current one are *legacy*: readable only behind the
84/// `allow_legacy_v0` policy (the name is historical; it covers every
85/// pre-current format) and upgraded by [`migrate_kv_to_encrypted`].
86const CURRENT_FORMAT_VERSION: u8 = 2;
87
88/// Format version 1, the first versioned-`key_id` format.
89const FORMAT_V1: u8 = 1;
90
91/// The only algorithm identifier this module reads or writes.
92const ALGORITHM: &str = "AES-256-GCM";
93
94/// The one error text every decryption failure returns. The specific
95/// cause (bad base64, wrong nonce length, unknown key id, failed
96/// authentication, ...) is logged, never returned, so the failure itself
97/// is not an oracle for which check tripped.
98const DECRYPT_FAILED: &str = "Decryption failed";
99
100/// Associated data for a format-v2 envelope: the caller's record AAD
101/// (the storage key) AND the envelope's own `v`, `algorithm` and `key_id`,
102/// each length-prefixed so the concatenation is unambiguous. Binding the
103/// metadata means relabelling an envelope's `key_id`, or rewriting `v` to
104/// downgrade it to a format whose AAD ignores metadata, fails
105/// authentication instead of being trusted.
106fn 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    // Envelopes serialized before this field existed (format version 0,
119    // the original public `EncryptedStorage`: fields `data`/`nonce`/
120    // `algorithm`/`key_derivation`, no `key_id`, no AAD at encryption
121    // time) deserialize with this field absent -- serde DOES call this
122    // function in that case (per `#[serde(default = "...")]`'s actual
123    // behavior), which happens to return the same `0` the bare type
124    // default would. It's spelled out explicitly, rather than relying on
125    // `#[serde(default)]`'s type-default shorthand, so the "absent field
126    // means format version 0" rule is visible at the field's definition
127    // instead of implicit in `u8::default()`.
128    0
129}
130
131/// Encrypted data container with metadata.
132///
133/// `key_id` makes this a versioned envelope: a value encrypted under one key
134/// can still be decrypted after the *current* key rotates, as long as the
135/// old key is still loadable (see [`KeyProvider`]). Writers always use the
136/// current key; readers look up whichever key the envelope names.
137///
138/// `v` and `key_derivation` exist for backward compatibility with the
139/// original, pre-this-redesign public `EncryptedStorage` (format version
140/// 0): that format had no `key_id` and no AAD binding at encryption time.
141/// An envelope with `v == 0` (including any envelope missing the `v` field
142/// entirely, since `#[serde(default)]` fills it with `0`) is decrypted
143/// against every loaded key with an empty AAD, matching the old behavior;
144/// see [`StorageEncryption::decrypt`].
145#[derive(Debug, Clone, Serialize, Deserialize)]
146pub struct EncryptedData {
147    /// Base64 encoded encrypted data
148    pub data: String,
149    /// Base64 encoded nonce/IV (96 bits, randomly generated per encryption)
150    pub nonce: String,
151    /// Algorithm identifier
152    pub algorithm: String,
153    /// Which key (by id) encrypted this value. Empty for format version 0
154    /// (the original `EncryptedStorage`, which had no key-id concept).
155    #[serde(default)]
156    pub key_id: String,
157    /// Envelope format version. `0` (including an absent field, which
158    /// deserializes to `0`) is the original pre-redesign format; `1` is
159    /// the legacy versioned-`key_id` format; `2` is the current format
160    /// (metadata bound into the AAD).
161    #[serde(default = "default_format_version")]
162    pub v: u8,
163    /// Present only for format-version-0 compatibility (the original
164    /// field name was `key_derivation`); current envelopes don't set it.
165    #[serde(default)]
166    pub key_derivation: String,
167}
168
169/// Supplies the encryption key(s) [`StorageEncryption`] uses.
170///
171/// Exists as a seam so the key *source* (env var today) can be swapped for
172/// a KMS or an `age`/`sops`-style file-based secret without touching
173/// [`StorageEncryption`] or [`EncryptedStorage`] at all. See
174/// [`EnvKeyProvider`]'s own docs for the current, deliberately narrow,
175/// implementation and its known limitation.
176pub trait KeyProvider: Send + Sync {
177    /// Load every key this provider knows about, keyed by key id, plus
178    /// which one is current (new writes use this one; any key in the map
179    /// can still be used to decrypt an old envelope that names it).
180    ///
181    /// Returns an error if no usable key can be loaded at all -- callers
182    /// must fail closed on that, never silently fall back to no
183    /// encryption.
184    fn load_keys(&self) -> Result<LoadedKeys>;
185}
186
187/// The result of [`KeyProvider::load_keys`]: every key this provider could
188/// load, and which one is current.
189pub struct LoadedKeys {
190    pub current_key_id: String,
191    /// All loadable keys, including the current one, by key id. A key id
192    /// must not be empty -- [`StorageEncryption::new`] rejects any that
193    /// are, since an empty id can't be told apart from format-version-0
194    /// envelopes (which have no key id at all).
195    pub keys: HashMap<String, [u8; 32]>,
196}
197
198/// Loads encryption keys from environment variables, or from a file if
199/// `AUTH_STORAGE_ENCRYPTION_KEYS_FILE` is set.
200///
201/// **Known limitation (tracked, per CireSnave's ruling on board item 124):**
202/// env vars and files sit on the same host as the data they protect. An
203/// attacker with read access to the process environment or the key file
204/// can decrypt everything this encrypts. This is accepted as a starting
205/// point, not an endpoint -- [`KeyProvider`] exists specifically so a
206/// KMS-backed or `age`/`sops`-backed provider can replace this one later
207/// without any caller-visible change. See `docs/storage-backends.md` for
208/// the same note aimed at operators.
209///
210/// ## Format
211///
212/// - `AUTH_STORAGE_ENCRYPTION_KEY` (required unless the keys file sets
213///   `current`): the current key, base64-encoded, 32 bytes decoded.
214/// - `AUTH_STORAGE_ENCRYPTION_KEY_ID` (optional, defaults to `"1"`): the id
215///   under which `AUTH_STORAGE_ENCRYPTION_KEY` is recorded in new
216///   envelopes.
217/// - `AUTH_STORAGE_ENCRYPTION_KEYS_FILE` (optional): path to a JSON file
218///   `{"current": "<key_id>", "keys": {"<key_id>": "<base64 key>", ...}}`
219///   for rotation -- old keys stay loadable (decrypt-only in practice,
220///   since `current` picks what new writes use) as long as they're listed
221///   here. If set, this takes priority over the two env vars above. On
222///   Unix, a keys file readable by group or other triggers a `tracing::warn!`;
223///   set `AUTH_STORAGE_ENCRYPTION_STRICT_KEY_FILE_PERMISSIONS=1` to make that
224///   a startup error instead. Not checked at all on Windows.
225/// - **The single env var cannot rotate**: it holds one key, so changing it
226///   makes every stored envelope undecryptable. Use the keys file for
227///   anything that will outlive one key; the storage factory warns when the
228///   env-var key protects data that is already encrypted.
229pub 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            // Zeroize every base64 key string before returning -- this
283            // early return must not be the one exit path that skips it.
284            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        // Decode every entry, zeroizing its base64 string regardless of
295        // success or failure, before checking for any error -- so a
296        // failure partway through doesn't leave later entries' strings
297        // (never reached by a `?`-propagating loop) un-zeroized, and
298        // doesn't leave already-decoded key bytes from earlier entries
299        // sitting in `keys` when we return Err below. Pre-sized so
300        // `insert` never triggers a reallocation that could leave a
301        // decoded key copy behind in the old, freed backing array.
302        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
331/// Environment variable that turns the keys-file permission warning into a
332/// startup error. Accepts `1`, `true` or `yes` (any case).
333const STRICT_KEY_FILE_PERMISSIONS_ENV: &str = "AUTH_STORAGE_ENCRYPTION_STRICT_KEY_FILE_PERMISSIONS";
334
335/// `true` when a file mode lets group or other read (or write) the file.
336/// (Only the Unix permission check calls it outside tests.)
337#[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
359/// Checks the keys file's permissions: always warns when it is readable by
360/// group or other (a file-based key readable by others defeats its point),
361/// and fails startup when `strict` is set
362/// (`AUTH_STORAGE_ENCRYPTION_STRICT_KEY_FILE_PERMISSIONS=1`). The default
363/// stays warn-only because permission semantics vary across containers, CI
364/// and Windows; strict mode is the opt-in for deployments that control them.
365/// Unix only: elsewhere there are no group/other mode bits to inspect, so
366/// strict mode logs that it cannot be enforced.
367fn 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
405/// `true` when the key comes from the `AUTH_STORAGE_ENCRYPTION_KEY`
406/// environment variable (no keys file). That source holds exactly one key
407/// and so cannot rotate: replacing it makes every stored envelope
408/// undecryptable. Use a keys file (`AUTH_STORAGE_ENCRYPTION_KEYS_FILE`) for
409/// anything that will outlive one key.
410pub(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
415/// Looks at up to `limit` KV entries of `storage` and reports whether any is
416/// already an encryption envelope. Bounded in the number of values read; the
417/// key listing itself is whatever the backend returns for the empty prefix.
418pub(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
432/// Produces a safe-to-log identifier for a storage key, for error
433/// messages, tracing, and migration reports -- **never** the raw key
434/// itself. In this crate, some storage keys literally ARE bearer
435/// secrets (e.g. `api_key:{raw_api_key}` in
436/// `auth_modular::user_manager`, `device:{device_code}` in
437/// `api::oauth_advanced`), so logging or printing a key name verbatim
438/// can leak a working credential into logs or a terminal.
439///
440/// Keeps the portion up to (not including) the first `:` (the
441/// namespace, e.g. `api_key`, assumed not secret since every KV
442/// namespace convention in this crate puts a fixed literal there) plus
443/// a short, one-way hash of the *full* key, so an operator with direct
444/// storage access can still correlate a reported identifier back to
445/// the real record (by recomputing the same hash over a candidate key)
446/// without the identifier itself being usable as a credential. A key
447/// with no `:` at all has no such non-secret prefix to keep -- it is
448/// replaced with the literal `key`, never the raw key itself.
449fn 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
474/// Storage encryption manager using AES-256-GCM, with per-record random
475/// nonces and associated data (AAD) binding each ciphertext to the storage
476/// key it was stored under -- so a ciphertext copied from one record to
477/// another fails to decrypt instead of silently "succeeding" with the
478/// wrong value.
479///
480/// **Known limitation (replay of an older value under the same key):** AAD
481/// binds a ciphertext to *which record* it belongs to, not to *when* it was
482/// written. Someone who can both read an old ciphertext for a given key and
483/// write to that same key can replay the old value -- AES-GCM's
484/// authentication only proves "this is a genuine envelope for this record,"
485/// not "this is the most recent one." Mitigating this needs a monotonic
486/// counter or timestamp bound into the AAD, not done here (most KV-layer
487/// values in this crate are replaced wholesale on every write, which bounds
488/// but does not eliminate the exposure).
489///
490/// **Zeroization scope (accurate, not aspirational):** this module
491/// zeroizes raw key material and intermediate plaintext it owns on every
492/// exit path it controls (success, a validation error, or an encryption
493/// failure partway through), as soon as it's done with it -- the
494/// `[u8; 32]` key bytes in [`LoadedKeys`] (after the AES-GCM ciphers are
495/// built, or before any validation error returns, including the
496/// "current key id not found" check), [`decode_key`]'s intermediate
497/// decoded `Vec<u8>`, every base64-encoded key string
498/// [`EnvKeyProvider`] reads (file contents and every per-key entry, even
499/// ones after a failure elsewhere in the same batch, and even when the
500/// file's `current` id isn't present in `keys`), and
501/// [`migrate_kv_to_encrypted`]'s intermediate plaintext/raw buffers,
502/// including when the subsequent re-encrypt or write-back fails. It does
503/// **not** zeroize: any copy the standard library or `aes-gcm` makes
504/// internally that this code doesn't control (notably `aes` 0.8.4's own
505/// key-schedule storage inside the `Aes256Gcm` cipher object, which has
506/// no zeroize support in the version this crate depends on; and
507/// `HashMap` growth can in principle leave a stale decoded-key copy in
508/// an old, freed backing allocation during a resize -- mitigated, not
509/// eliminated, in `EnvKeyProvider::load_from_file`'s multi-key decoding
510/// loop (the one production path that decodes a variable, potentially
511/// large number of keys into a map) by pre-sizing it with
512/// `with_capacity`; `EnvKeyProvider::load_keys`' single-env-var path
513/// only ever inserts exactly one entry, so it can't resize at all), or
514/// a plaintext value a public method (`decrypt`,
515/// `decrypt_from_storage`) hands back to its caller (that's the actual
516/// return value the caller needs -- it isn't leftover residue this module
517/// can clean up on the caller's behalf).
518pub struct StorageEncryption {
519    current_key_id: String,
520    ciphers: HashMap<String, Aes256Gcm>,
521}
522
523impl StorageEncryption {
524    /// Create a new encryption manager, loading keys from the given
525    /// provider. Fails closed: if the provider can't load a usable key,
526    /// this returns `Err` rather than any fallback.
527    pub fn new(provider: &dyn KeyProvider) -> Result<Self> {
528        let mut loaded = provider.load_keys()?;
529
530        // Validate first, but zeroize the raw key bytes on EVERY exit
531        // path (including these early validation failures) -- not just
532        // the success path -- so a rejected key never lingers in memory
533        // any longer than the other branch does.
534        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        // The cipher objects above have their own internal copies of the
568        // key material; zeroize the raw bytes we held so they don't sit
569        // around in this struct any longer than necessary.
570        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    /// The id of the key new values are encrypted under.
580    pub fn current_key_id(&self) -> &str {
581        &self.current_key_id
582    }
583
584    /// Create a new encryption manager from the environment (see
585    /// [`EnvKeyProvider`]). Convenience wrapper over `new(&EnvKeyProvider)`.
586    pub fn from_env() -> Result<Self> {
587        Self::new(&EnvKeyProvider)
588    }
589
590    /// Create new encryption manager for testing with a single random key.
591    #[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    /// Generate a new 256-bit encryption key (base64 encoded), suitable for
607    /// `AUTH_STORAGE_ENCRYPTION_KEY` or a keys-file entry.
608    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    /// Encrypt raw bytes. `aad` (associated data) is authenticated but not
618    /// encrypted -- callers should pass the storage key the resulting
619    /// envelope will be stored under, binding the ciphertext to that
620    /// specific record.
621    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        // 96-bit nonce, freshly random every call. NIST SP 800-38D caps a
628        // randomly generated 96-bit IV at 2^32 invocations under a single
629        // key before the collision probability becomes unacceptable (the
630        // "32-bit random IV construction" guidance) -- not the ~2^64/2
631        // birthday bound a naive calculation might suggest. A given
632        // deployment's key should be rotated well before approaching that
633        // count; this crate does not currently track or enforce it.
634        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    /// Decrypt an envelope. `aad` must match exactly what was passed to
660    /// [`Self::encrypt`] (the storage key the envelope is stored under) --
661    /// a mismatch (e.g. a ciphertext copied to a different record) fails
662    /// decryption rather than succeeding with the wrong plaintext.
663    ///
664    /// A format-version-0 envelope (see [`EncryptedData`]) is decrypted
665    /// with an empty AAD against every loaded key in turn, matching the
666    /// original `EncryptedStorage`'s behavior (no AAD, no key id) --
667    /// AES-GCM's authentication tag makes trying the wrong key safe (it
668    /// just fails), so this cannot silently produce the wrong plaintext.
669    pub fn decrypt(&self, encrypted: &EncryptedData, aad: &[u8]) -> Result<Vec<u8>> {
670        // Every failure below returns the SAME error text (`DECRYPT_FAILED`);
671        // the cause is logged only.
672        let fail = |why: &str| -> AuthError {
673            // `key_id` comes from the (possibly attacker-writable) store:
674            // log it Debug-escaped and bounded.
675            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            // Format version 0 (the original EncryptedStorage): no key id,
700            // no AAD. Try every loaded key, in a stable order; the auth tag
701            // rejects wrong ones.
702            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        // v1 authenticated only the bare record AAD; v2 also binds the
724        // envelope's own metadata. Anything else is unknown to this build.
725        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    /// Encrypt raw bytes for storage, serialized as a self-describing
747    /// envelope. `aad` should be the storage key this will be stored
748    /// under. Accepts arbitrary bytes, not just UTF-8 text.
749    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    /// Decrypt a storage envelope produced by [`Self::encrypt_for_storage`].
758    /// `aad` must be the same storage key passed to that call.
759    pub fn decrypt_from_storage(&self, data: &[u8], aad: &[u8]) -> Result<Vec<u8>> {
760        // A stored value that is not even an envelope fails with the same
761        // text as every other decryption failure; the cause is logged.
762        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    /// Parses `data` as one of this module's own serialized envelopes --
773    /// either the current format or the original format-version-0 shape
774    /// (see [`EncryptedData`]) -- without attempting to decrypt it. `None`
775    /// if `data` isn't valid UTF-8 JSON, doesn't name the right algorithm,
776    /// or claims a post-v0 format without a `key_id`.
777    ///
778    /// This is a **shape** check only. A value that parses here but fails
779    /// to decrypt (wrong key, corrupted, or tampered with) is a hard error
780    /// from [`Self::decrypt_from_storage`], never silently treated as
781    /// plaintext.
782    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        // v0 has neither `v` nor `key_id`. Anything claiming a later
790        // format must carry an explicit non-empty `key_id`; without one it
791        // is just plaintext JSON that happens to resemble an envelope.
792        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    /// Key ids in a stable (ascending) order, for deterministic trial
801    /// decryption.
802    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    /// Returns `true` if `data` parses as one of this module's own
809    /// serialized envelopes. Used by [`migrate_kv_to_encrypted`] and
810    /// [`EncryptedStorage::get_kv`] to decide whether a stored value
811    /// should be decrypted at all.
812    pub fn looks_like_envelope(data: &[u8]) -> bool {
813        Self::parse_envelope(data).is_some()
814    }
815}
816
817/// Wrapper for storage backends that adds encryption at rest to the
818/// generic key-value (`store_kv`/`get_kv`) layer.
819///
820/// **Coverage note:** this wraps `store_kv`/`get_kv` only. The dedicated
821/// `store_token`/`store_session` methods (and each backend's own typed
822/// columns for them) are NOT touched by this wrapper -- they delegate to
823/// `inner` unchanged. Encrypting those would need changes to the
824/// `AuthStorage` trait itself (their fields are typed, not opaque bytes),
825/// tracked separately. This wrapper covers everything that already goes
826/// through `store_kv` today: API keys, TOTP secrets, OAuth2 client
827/// registries, MFA codes, and most of the other KV-backed subsystems
828/// found in the storage audit (`docs/STORAGE-AUDIT.md`).
829pub struct EncryptedStorage<T> {
830    inner: T,
831    encryption: StorageEncryption,
832    /// See [`Self::get_kv`]'s doc comment for exactly what this controls.
833    allow_plaintext_reads: bool,
834    /// See [`Self::get_kv`]'s doc comment for exactly what this controls.
835    allow_legacy_v0: bool,
836}
837
838impl<T> EncryptedStorage<T> {
839    /// `allow_plaintext_reads` should be `true` only transiently, while
840    /// migrating an existing deployment's plaintext data (see
841    /// [`migrate_kv_to_encrypted`]) -- it is what makes [`Self::get_kv`]
842    /// tolerate a value that isn't a valid envelope instead of erroring.
843    /// Leaving it `true` permanently means anyone who can write to the
844    /// backing store can overwrite an encrypted value with chosen
845    /// plaintext (or corrupt one) and have it accepted silently, which
846    /// defeats the point of encrypting at rest. Pass `false` for normal
847    /// operation.
848    ///
849    /// `allow_legacy_v0` should likewise be `true` only transiently, while
850    /// migrating pre-existing format-version-0 data: a v0 envelope has no
851    /// AAD binding it to its own storage key, so with this `true`, a
852    /// writer who knows one record's v0 envelope can copy it onto a
853    /// different record's key and it still decrypts -- the exact swap the
854    /// current format's AAD exists to prevent. This flag is independent
855    /// of [`migrate_kv_to_encrypted`]'s own, separate
856    /// `accept_legacy_v0` parameter (that one gates whether migration
857    /// actually *rewrites* a v0 envelope; this one gates whether this
858    /// wrapper's `get_kv` will *read* one at all) -- set this one `true`
859    /// if something needs to read v0 data through this wrapper before,
860    /// or without ever, running migration.
861    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    // Token/session methods — NOT encrypted by this wrapper. See the
886    // "Coverage note" on `EncryptedStorage` itself.
887    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    // Bulk methods — delegate directly to `inner`'s own overrides (if any)
932    // instead of inheriting the `AuthStorage` trait's one-at-a-time default
933    // loop, so a backend that implements real batching here keeps that
934    // benefit even when wrapped. Token/session bulk methods are unaffected
935    // by encryption (see the coverage note above) either way.
936    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    // Key-value methods — encrypted, with the storage key itself as AAD so
953    // a ciphertext can't be swapped between records.
954    async fn get_kv_ttl(&self, key: &str) -> Result<Option<Duration>> {
955        // A TTL is storage metadata, not part of the encrypted value.
956        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    /// Reads back a value stored by [`Self::store_kv`], decrypting it.
992    ///
993    /// A value that **parses as one of this module's envelopes**
994    /// ([`StorageEncryption::looks_like_envelope`]) is always decrypted;
995    /// a decryption failure (wrong key, corrupted, tampered) is a hard
996    /// `Err`, never silently returned as-is.
997    ///
998    /// A value that does **not** parse as an envelope at all is ambiguous:
999    /// it could be genuine pre-encryption plaintext, or it could be a
1000    /// plaintext value an attacker (or a bug) overwrote the encrypted one
1001    /// with. This method only tolerates that ambiguity -- returning the
1002    /// raw bytes as-is -- when `allow_plaintext_reads` is `true`. With it
1003    /// `false` (the default via the storage factory once migration is
1004    /// done), a non-envelope value is also a hard `Err`, so overwriting an
1005    /// encrypted record with plaintext cannot silently succeed.
1006    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        // A TTL is storage metadata, not part of the encrypted value.
1045        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    // Key NAMES are never encrypted (only values) -- pass through
1057    // unchanged so RBAC role reload, maintenance/backup, and analytics
1058    // (all of which call this) keep working once this wrapper is in the
1059    // default path. Without this override, the AuthStorage trait's
1060    // default implementation would fail (it used to return an empty Vec).
1061    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/// Outcome of [`migrate_kv_to_encrypted`].
1071///
1072/// `#[non_exhaustive]`: this is a read-only outcome type, not something
1073/// a caller builds -- only this crate's own tests construct one (with
1074/// `..Default::default()`, which only compiles from *inside* the
1075/// crate), so a later field addition here can never be a breaking
1076/// change for an external caller.
1077#[derive(Debug, Clone, Default, PartialEq, Eq)]
1078#[non_exhaustive]
1079pub struct KvEncryptionMigrationReport {
1080    /// Whether this run was a dry run (no writes performed).
1081    pub dry_run: bool,
1082    /// Total keys examined under the given prefix. Always equal to
1083    /// `already_encrypted + legacy_v0_found + encrypted + vanished +
1084    /// failed.len()`.
1085    pub scanned: u64,
1086    /// Keys that were already a current-format envelope -- left
1087    /// untouched.
1088    pub already_encrypted: u64,
1089    /// Keys that were a LEGACY envelope (format version 0 or 1; the name
1090    /// is historical) that decrypted successfully -- counted here whether
1091    /// or not they were actually rewritten (see `upgraded_from_legacy`).
1092    /// A v0 envelope has no AAD binding its plaintext to this specific
1093    /// record, so this plaintext's association with this key could not
1094    /// be cryptographically verified -- it is exactly as trustworthy as
1095    /// it was before migration, no more, no less. A v1 envelope's AAD
1096    /// does bind the record key (its decryption just verified that), but
1097    /// not its own metadata.
1098    pub legacy_v0_found: u64,
1099    /// Keys whose legacy (v0 or v1) envelope was actually rewritten under
1100    /// the current format. Zero unless this was a real (non-dry) run
1101    /// AND `accept_legacy_v0` was `true` -- see
1102    /// [`migrate_kv_to_encrypted`]'s docs for why that flag exists and
1103    /// what rewriting a v0 envelope does and does not verify.
1104    pub upgraded_from_legacy: u64,
1105    /// Keys that were plaintext (not an envelope at all) and got
1106    /// encrypted (or would have, in a dry run).
1107    pub encrypted: u64,
1108    /// Keys that were read but had vanished by the time of the write-back
1109    /// (concurrent deletion) -- not an error, just skipped.
1110    pub vanished: u64,
1111    /// Format-version-0 records whose envelope could not be decrypted
1112    /// under any loaded key (wrong/missing key, or corrupted). Skipped,
1113    /// not treated as fatal -- the rest of the run still completes.
1114    /// **Only v0 envelopes are decrypt-checked by this function** --
1115    /// a current-format (v1) envelope that can't decrypt (e.g. its key
1116    /// was rotated out) is not migration's concern (it's already in the
1117    /// target format) and is counted in `already_encrypted`, not here.
1118    /// Entries are a **safe identifier** (see [`safe_log_id`]), never the
1119    /// raw storage key -- some keys in this crate are themselves bearer
1120    /// secrets (e.g. `api_key:{raw_key}`).
1121    pub failed: Vec<String>,
1122}
1123
1124/// Options for [`migrate_kv_to_encrypted`]. A named struct rather than
1125/// two adjacent `bool` parameters, specifically so a caller can't
1126/// transpose them -- `(false, true)` instead of `(true, false)` would
1127/// otherwise silently turn an intended dry run into a real upgrade.
1128#[derive(Debug, Clone, Copy, Default)]
1129#[non_exhaustive]
1130pub struct MigrationOptions {
1131    /// Preview only; don't write anything. See
1132    /// [`migrate_kv_to_encrypted`]'s own docs for exactly what a dry run
1133    /// still does (it attempts every decrypt a real run would, for
1134    /// accurate reporting).
1135    pub dry_run: bool,
1136    /// Required, together with `dry_run: false`, to actually rewrite a
1137    /// format-version-0 envelope to the current format. See
1138    /// [`migrate_kv_to_encrypted`]'s own docs for why this is a separate,
1139    /// explicit opt-in.
1140    pub accept_legacy_v0: bool,
1141    /// A backend that cannot report KV TTLs ([`AuthStorage::tracks_kv_ttl`]
1142    /// is `false`) makes a real migration turn every expiring entry into a
1143    /// permanent one. Such a run is refused unless this is `true`.
1144    pub accept_ttl_loss: bool,
1145}
1146
1147impl MigrationOptions {
1148    /// Builder-style setter; see [`Self::with_dry_run`].
1149    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    /// Builder-style setter. `#[non_exhaustive]` means `MigrationOptions {
1155    /// dry_run: true, ..Default::default() }` only compiles *inside*
1156    /// this crate -- a downstream caller needs `let mut o =
1157    /// MigrationOptions::default(); o.dry_run = true;` or this method
1158    /// chain instead: `MigrationOptions::default().with_dry_run(true)`.
1159    pub fn with_dry_run(mut self, dry_run: bool) -> Self {
1160        self.dry_run = dry_run;
1161        self
1162    }
1163
1164    /// Builder-style setter; see [`Self::with_dry_run`] for why this
1165    /// exists instead of a struct literal.
1166    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
1172/// Re-encrypts every already-plaintext value under `prefix` in the given
1173/// KV storage, in place.
1174///
1175/// - **Idempotent and resumable**: a value already in the *current*
1176///   envelope format is left untouched. Re-running this function (e.g.
1177///   after it was interrupted, or because some keys were skipped as
1178///   `failed`) only ever touches the plaintext and not-yet-upgraded v0
1179///   values still remaining -- there's no separate resume cursor to
1180///   manage.
1181/// - **A single undecryptable v0 envelope never aborts the run**: if one
1182///   key's format-version-0 envelope can't be decrypted under any
1183///   loaded key (wrong/missing key, or corrupted -- only v0 envelopes
1184///   are decrypt-checked this way, see
1185///   [`KvEncryptionMigrationReport::failed`]'s own docs), a safe
1186///   identifier for it (never the raw key) is recorded in `failed` and
1187///   it's skipped -- every other key is still processed. Anyone who can
1188///   write one envelope-shaped value under `prefix` can otherwise make
1189///   an `?` on the first failure block the entire run.
1190/// - **Dry-run is accurate, not optimistic**: `dry_run: true` actually
1191///   attempts every decrypt it would need for a real run (it just skips
1192///   the write-back), so its counts -- including `failed` -- match what
1193///   a real run would do, rather than assuming every v0 envelope found
1194///   would succeed.
1195/// - **Format-version-0 upgrades require `accept_legacy_v0: true` AND a
1196///   real (non-dry) run.** A v0 envelope has no AAD, so decrypting it
1197///   proves nothing about *which record* its plaintext actually belongs
1198///   to -- it decrypts successfully under any loaded key regardless of
1199///   where it's stored. **This function cannot detect a v0 envelope
1200///   that's been copied from one record onto another**; it can only
1201///   decrypt-then-re-encrypt whatever is there, inheriting that
1202///   plaintext's association with this key exactly as unverified as it
1203///   was before. `accept_legacy_v0` exists so that upgrading is never a
1204///   silent, implicit side effect of running this function -- an
1205///   operator must explicitly accept that risk. With it `false` (or in
1206///   a dry run), v0 envelopes are still *decrypted* for reporting
1207///   accuracy (see the bullet above) and counted in
1208///   [`KvEncryptionMigrationReport::legacy_v0_found`], but never
1209///   written back; `upgraded_from_legacy` only increases on an actual
1210///   real-run upgrade. Every real upgrade logs one `tracing::warn!` line
1211///   naming a safe identifier for the record (never its raw key or
1212///   value -- see below).
1213/// - **Never logs or reports the raw storage key, plaintext, or
1214///   ciphertext**: in this crate, some storage keys are themselves
1215///   bearer secrets (e.g. `api_key:{raw_api_key}`), so logging a key
1216///   name verbatim can leak a working credential. Everywhere this
1217///   function logs or reports a record (`tracing::warn!` lines,
1218///   [`KvEncryptionMigrationReport::failed`]), it uses a short,
1219///   non-reversible, safe identifier instead of the raw key; callers
1220///   should preserve that if they add their own logging around this.
1221/// - **Not safe to run concurrently with live writes to the same keys**:
1222///   this does a read, then a write-back, with no compare-and-swap. If
1223///   something else writes a fresh value to a key between this function's
1224///   read and write, the write-back here overwrites it with the stale
1225///   value it read. Run this offline, or at least pause writers to the
1226///   given `prefix`, before running it against a live deployment.
1227///
1228/// `storage` and `encryption` are the same values the caller would pass to
1229/// [`EncryptedStorage::new`] -- this function talks to the *inner*,
1230/// unwrapped storage directly, since [`EncryptedStorage::get_kv`] would
1231/// already transparently decrypt (and thus hide which rows still need
1232/// migrating).
1233///
1234/// **TTLs are preserved** on backends that report them
1235/// ([`AuthStorage::tracks_kv_ttl`]): each rewritten entry is stored with
1236/// the remaining TTL it had (read via [`AuthStorage::get_kv_ttl`] before the
1237/// value, so an entry that expires mid-run is skipped, never made
1238/// permanent). A backend that cannot report TTLs would turn every expiring
1239/// entry (OAuth codes, MFA/SMS codes, WebAuthn challenges, rate-limit
1240/// windows, expiring API keys) permanent, so a real (non-dry) run on one is
1241/// **refused** unless [`MigrationOptions::accept_ttl_loss`] is set; if it
1242/// is, scope `prefix` to durable-secret namespaces only. The CLI
1243/// (`security encrypt-kv`) exposes this as `--accept-ttl-loss`.
1244pub 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
1254/// [`migrate_kv_to_encrypted`] for an explicit list of keys instead of a prefix.
1255///
1256/// Use it when the records to encrypt are not the whole of a prefix (for example the TOTP
1257/// secrets, which live under `user:{id}:totp_secret` among other `user:` rows). Every other
1258/// property, including idempotence, TTL preservation and what `options` mean, is that of
1259/// [`migrate_kv_to_encrypted`]; the report's `scanned` is `keys.len()`.
1260pub 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    // A backend that cannot report TTLs would have every expiring entry
1273    // re-stored as permanent. Refuse before touching anything unless the
1274    // caller accepts that; a dry run writes nothing, so it is always fine.
1275    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        // The TTL is read BEFORE the value (see the maintenance snapshot
1292        // code): an entry that expires in between yields a TTL and no value
1293        // (counted as vanished), never a value whose expiry was lost.
1294        let ttl = storage.get_kv_ttl(&key).await?;
1295        let Some(mut raw) = storage.get_kv(&key).await? else {
1296            // Deleted concurrently between list_kv_keys and get_kv.
1297            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            // Format-version-0 envelope: always attempt the decrypt (so
1308            // dry-run reporting is accurate), but never let a failure
1309            // here abort the rest of the run.
1310            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/// What [`rewrap_kv_keys`] did.
1368#[derive(Debug, Clone, Default, PartialEq, Eq)]
1369pub struct KvRewrapReport {
1370    /// Whether this run was a dry run (no writes performed).
1371    pub dry_run: bool,
1372    /// Keys examined.
1373    pub scanned: u64,
1374    /// Envelopes decrypted under an older key and re-encrypted (or, in a dry run, that would be)
1375    /// under the current key.
1376    pub rewrapped: u64,
1377    /// Envelopes already under the current key: left untouched.
1378    pub already_current: u64,
1379    /// Values that are not envelopes at all (plaintext): left untouched. Encrypt them with
1380    /// [`migrate_kv_keys_to_encrypted`] first.
1381    pub plaintext_skipped: u64,
1382    /// Envelopes in a legacy format (version below the current one): left untouched. Upgrade them with
1383    /// [`migrate_kv_keys_to_encrypted`] and `accept_legacy_v0` first.
1384    pub legacy_skipped: u64,
1385    /// Keys deleted between the listing and the read: not an error.
1386    pub vanished: u64,
1387    /// Envelopes that no loaded key could decrypt (or whose binding to their key failed): a safe
1388    /// identifier for each, never the raw key. They are left as they were.
1389    pub failed: Vec<String>,
1390}
1391
1392/// Re-encrypts, under the current key, every current-format envelope in `keys` that is under an
1393/// older key id: the second half of a key rotation (the provider holds the old and the new key and
1394/// names the new one current; run this; then remove the old key).
1395///
1396/// Idempotent and resumable, preserves each value's TTL, never aborts on one undecryptable value,
1397/// and never touches plaintext or legacy-format values (see [`KvRewrapReport`]). A dry run decrypts
1398/// every candidate, so its counts are what a real run would do, and writes nothing.
1399pub 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        // TTL before value, as in the migration: an entry that expires in between is a vanished
1412        // one, never a value whose expiry was lost.
1413        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    /// Proves the AAD actually binds the ciphertext to its storage key:
1477    /// decrypting under a DIFFERENT aad than it was encrypted with must
1478    /// fail, not silently succeed with wrong-but-plausible plaintext. This
1479    /// is the mechanism that stops a ciphertext from being swapped between
1480    /// two records.
1481    #[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    /// Proves nonces are actually random per call, not reused -- the
1495    /// security of AES-GCM depends on this. Encrypts the same plaintext
1496    /// many times and checks every nonce is unique.
1497    #[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    /// A key provider that resolves to no usable key at all must make
1527    /// construction fail, not silently produce a `StorageEncryption` that
1528    /// can't actually encrypt anything (e.g. by skipping encryption).
1529    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        // current_key_id is non-empty and present in the map (so the
1558        // separate, earlier checks for "current_key_id is empty" and
1559        // "current_key_id isn't in the map" don't fire first) -- this
1560        // specifically exercises the "no key in the map has an empty id"
1561        // check via a SECOND entry.
1562        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    /// Key rotation: an envelope encrypted under an OLD key must still
1577    /// decrypt once the current key id has moved on, as long as the old
1578    /// key is still present in the loaded key set.
1579    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        // Now rotate: current key id moves to "2", but "1" is kept around.
1612        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        // New writes use the new key.
1621        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        // The OLD envelope (key_id "1") must still decrypt.
1627        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    /// Format-version-0 compatibility: an envelope shaped like the
1634    /// original (pre-redesign) `EncryptedStorage` produced -- no `key_id`,
1635    /// no `v`, no AAD at encryption time -- must still decrypt under the
1636    /// new `StorageEncryption`, since real deployments may already hold
1637    /// data in that shape.
1638    #[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        // Hand-build a format-version-0 envelope the way the original
1649        // `EncryptedStorage::encrypt` did: no AAD, no key_id, no v.
1650        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    /// Negative case for the v0 downgrade attack: a GENUINE current-format
1675    /// (v1) envelope, with its `v` and `key_id` fields stripped (so it now
1676    /// parses as a v0-shaped envelope), must not be accepted as that
1677    /// record's value. It fails for two independent reasons here -- the
1678    /// policy check (`allow_legacy_v0: false` by default) rejects it before
1679    /// any decryption is attempted, and even without that check the
1680    /// ciphertext itself was sealed with a real (non-empty) AAD, so the v0
1681    /// path's empty-AAD decrypt attempt would fail the authentication tag
1682    /// anyway.
1683    #[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        // Strip the fields a v0 envelope never had, simulating an
1712        // attacker (or a bug) downgrading a real v1 envelope.
1713        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    /// Proves the wrapper actually changes what's on disk/in the backend
1778    /// -- reading through the INNER storage directly (bypassing
1779    /// `EncryptedStorage`) must NOT show the plaintext.
1780    #[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    /// Proves the wrapper's own AAD wiring (not just `StorageEncryption`
1812    /// directly, which `test_decrypt_rejects_wrong_aad` already covers) --
1813    /// swapping two records' raw envelopes in the INNER backend must make
1814    /// both unreadable through the wrapper, because each envelope's AAD no
1815    /// longer matches the key it's stored under. If the wrapper passed a
1816    /// constant (e.g. empty) AAD instead of the real key, this swap would
1817    /// go undetected and both reads would "succeed" with the wrong value.
1818    #[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        // An independent `StorageEncryption` built from the SAME key, used
1832        // only to verify what AAD the wrapper actually used -- never to
1833        // produce the envelopes under test.
1834        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        // The wrapper must have used the storage key itself as AAD: decrypting
1853        // with that exact AAD must succeed...
1854        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        // ...and decrypting the SAME envelope under a DIFFERENT record's key
1863        // name must fail. If the wrapper instead used some constant AAD (the
1864        // exact mutation this test exists to catch), this swap-style check
1865        // would succeed instead of failing.
1866        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    /// A value stored by some pre-encryption version of the framework (or
1878    /// while `storage_encryption.enabled = false`) is readable when
1879    /// `allow_plaintext_reads` is explicitly true (the migration-window
1880    /// setting).
1881    #[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    /// With `allow_plaintext_reads` false (the normal, post-migration
1895    /// setting), a value that isn't a valid envelope -- whether genuine
1896    /// untouched legacy plaintext, a corrupted envelope, or an attacker's
1897    /// overwrite -- must be a hard error, not silently accepted. This is
1898    /// the fix for the finding that an attacker able to write to the
1899    /// backing store could otherwise overwrite an encrypted secret with
1900    /// chosen plaintext and have it accepted forever.
1901    #[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    /// The real fix for the v0-downgrade finding: a format-version-0
1919    /// envelope must be actively rewritten to the current format by
1920    /// migration (not just counted as "already encrypted" and left
1921    /// alone), since nothing else in this crate ever upgrades one.
1922    #[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        // Hand-build a v0 envelope the way the original pre-redesign
1933        // `EncryptedStorage` did (no AAD, no key_id, no v).
1934        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        // The upgraded envelope must decrypt correctly through the
1988        // normal (AAD-bound) path -- not just via the v0 fallback.
1989        let decrypted = encryption
1990            .decrypt(&envelope_after, b"secret:legacy")
1991            .unwrap();
1992        assert_eq!(decrypted, b"v0 secret".to_vec());
1993
1994        // Idempotent: running it again finds nothing left to upgrade.
1995        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    /// Without `accept_legacy_v0`, a decryptable v0 envelope is reported
2012    /// (`legacy_v0_found`) but never written back as the current format --
2013    /// this is the fix for the laundering finding: upgrading must never be
2014    /// an implicit side effect of just running the migration.
2015    #[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        // Real run (not dry), but accept_legacy_v0 is false.
2045        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    /// Fix for the "one bad record aborts the whole run" finding: a v0
2075    /// envelope that fails to decrypt under any loaded key must be
2076    /// skipped and reported by name, not abort processing of the other
2077    /// keys in the same run.
2078    #[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        // A v0-shaped envelope with ciphertext that will NOT decrypt
2089        // under the loaded key (wrong key material entirely).
2090        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        // The bad record itself is untouched (still its original bytes).
2150        let bad_after = storage.get_kv("secret:bad").await.unwrap().unwrap();
2151        assert_eq!(bad_after, bad_v0_json.as_bytes());
2152    }
2153
2154    /// Fix for "dry run lies": a dry run must actually attempt the v0
2155    /// decrypt (not just assume success), so an undecryptable v0 envelope
2156    /// shows up in `failed` during a dry run too, matching what a real
2157    /// run would report.
2158    #[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    /// Fix for the high-severity finding: some storage keys in this
2212    /// crate ARE bearer secrets (`api_key:{raw_key}`), so a safe log
2213    /// identifier must never contain the raw key material -- only the
2214    /// namespace and a hash.
2215    #[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        // Deterministic, so an operator with storage access can
2230        // recompute it to correlate a logged identifier back to a
2231        // specific record.
2232        assert_eq!(id, safe_log_id(&key));
2233    }
2234
2235    /// A key with no `:` at all has no non-secret namespace prefix to
2236    /// keep -- `key.split(':').next()` on a colonless key returns the
2237    /// WHOLE key, which would print the raw secret verbatim. This is
2238    /// the fix for that gap.
2239    #[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    /// Kills the mutation `if !dry_run && accept_legacy_v0` ->
2255    /// `if accept_legacy_v0` (dropping the dry-run check): with
2256    /// accept_legacy_v0 true but dry_run also true, over a DECRYPTABLE
2257    /// v0 record, nothing must be written -- the only existing
2258    /// dry-run-with-flag test used an undecryptable record, which never
2259    /// reaches this branch at all.
2260    #[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        // dry_run: true AND accept_legacy_v0: true.
2290        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        // Dry run must not have written anything.
2353        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    /// Proves idempotency and resumability: running the migration a
2387    /// second time over a mix of already-migrated and still-plaintext
2388    /// keys (simulating an interrupted first run) must not re-encrypt
2389    /// (double-encrypt) the already-done ones, and must finish the rest.
2390    #[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        // Simulate a first run that only got through "secret:a" before
2404        // being interrupted.
2405        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        // Resume: should skip "secret:a" (already encrypted) and finish
2414        // "secret:b".
2415        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        // Running it again changes nothing further.
2440        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    /// The wrapper must report the inner backend's TTL: restore (#121)
2492    /// reads it through the wrapper the framework actually holds.
2493    #[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    // ---- envelope v2 + hardening ------------------------------------------------
2510
2511    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    /// Builds a stored envelope by hand, the way an OLDER writer would have:
2533    /// `aad` is used verbatim (v1 used the bare storage key).
2534    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    /// v2 binds the envelope's own metadata into the AAD: the same key
2570    /// loaded under two ids must NOT let an attacker relabel `key_id`, and
2571    /// rewriting `v` to 1 (a downgrade to the AAD that ignores metadata)
2572    /// must not make a v2 ciphertext verify.
2573    #[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    /// Format v1 (AAD = the bare storage key) is a LEGACY format now: only
2599    /// readable behind the allow-legacy policy, and the migration tool
2600    /// upgrades it to v2.
2601    #[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        // (`MemoryStorage::clone` copies, so re-wrap the migrated storage.)
2649        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    /// After the upgrade, a v2 ciphertext copied onto another record must
2662    /// not decrypt (the AAD still binds it to its own key).
2663    #[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    /// A plaintext JSON value that merely looks like an envelope must not be
2697    /// classified as one: v>=1 needs an explicit non-empty key_id.
2698    #[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        // v2 without a key_id: not an envelope.
2706        assert!(StorageEncryption::parse_envelope(shape(r#","v":2"#).as_bytes()).is_none());
2707        // v1 with an empty key_id: not an envelope.
2708        assert!(
2709            StorageEncryption::parse_envelope(shape(r#","v":1,"key_id":"""#).as_bytes()).is_none()
2710        );
2711        // v2 with a key_id: an envelope.
2712        assert!(
2713            StorageEncryption::parse_envelope(shape(r#","v":2,"key_id":"1""#).as_bytes()).is_some()
2714        );
2715        // The original (v0) shape has neither field and is still recognised.
2716        assert!(StorageEncryption::parse_envelope(shape("").as_bytes()).is_some());
2717    }
2718
2719    /// Every way decryption can fail yields the same error text, so the
2720    /// failure itself is not an oracle for which check tripped.
2721    #[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    // ---- key loading fails closed (review gap) ----------------------------------
2790
2791    fn load_with_env(key: Option<&str>) -> Result<LoadedKeys> {
2792        let _lock = TEST_ENCRYPTION_ENV_LOCK.blocking_lock();
2793        // SAFETY: serialized by TEST_ENCRYPTION_ENV_LOCK.
2794        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        // SAFETY: serialized by TEST_ENCRYPTION_ENV_LOCK (held above).
2803        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            // SAFETY: serialized by TEST_ENCRYPTION_ENV_LOCK.
2847            unsafe {
2848                std::env::set_var("AUTH_STORAGE_ENCRYPTION_KEYS_FILE", &path);
2849            }
2850            let result = EnvKeyProvider.load_keys();
2851            // SAFETY: serialized by TEST_ENCRYPTION_ENV_LOCK (held above).
2852            unsafe { std::env::remove_var("AUTH_STORAGE_ENCRYPTION_KEYS_FILE") };
2853            assert!(result.is_err(), "{name} must fail closed");
2854        }
2855    }
2856
2857    // ---- migration preserves KV TTLs ---------------------------------------------
2858
2859    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    /// A backend that cannot report TTLs must not be migrated silently: a
2928    /// real run would make every expiring entry permanent. It needs an
2929    /// explicit opt-in, and a dry run (which writes nothing) is always fine.
2930    #[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    // ---- keys-file permissions (L4) and env-key rotation warning (L3) ------------
2988
2989    #[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            // SAFETY: serialized by TEST_ENCRYPTION_ENV_LOCK (held above).
3004            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        // SAFETY: serialized by TEST_ENCRYPTION_ENV_LOCK (held above).
3021        unsafe { std::env::remove_var(STRICT_KEY_FILE_PERMISSIONS_ENV) };
3022    }
3023
3024    /// Runs on Unix CI only (Windows has no group/other mode bits).
3025    #[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        // SAFETY: serialized by TEST_ENCRYPTION_ENV_LOCK (held above).
3055        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        // SAFETY: as above.
3061        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        // SAFETY: as above.
3067        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        // SAFETY: as above.
3070        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        // The probe is bounded: with a limit of 0 it looks at nothing.
3097        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}