envseal 0.3.13

//! Passphrase-protected master key management.
//!
//! The master key is the root of all encryption in envseal.
//! It is a random 32-byte key, encrypted at rest by a wrapping key
//! derived from a user-entered passphrase via Argon2id.
//!
//! # Key Hierarchy
//!
//! ```text
//! passphrase (entered via GUI popup — agent cannot access)
//!   → Argon2id(passphrase, argon2_salt) → wrapping_key
//!     → AES-256-GCM(wrapping_key, master_key) → encrypted on disk
//!       → master_key used for all vault encryption
//!       → master_key used for HMAC signing of policy.toml
//! ```
//!
//! # File Format: `master.key`
//!
//! ```text
//! [16 bytes: argon2_salt] [12 bytes: nonce] [N bytes: ciphertext+tag]
//! ```

use std::fs;
use std::path::{Path, PathBuf};

/// Per-vault-root mutex guarding `create_master_key_with`. Two
/// threads racing in the same process for the same root both used
/// to observe `master.key` missing, both generated fresh master
/// keys, and the second `fs::rename` overwrote the first; every
/// secret stored under the lost key became permanently
/// undecryptable. Serializing under a per-root `Arc<Mutex<()>>`
/// closes the in-process side; the same call path also acquires a
/// cross-process advisory lock on `<root>/vault.lock` so two CLI
/// invocations from the same shell synchronize too.
///
/// Mirrors the audit log's `append_locks` pattern. LRU-bounded at
/// 256 distinct roots.
fn vault_init_lock_for(root: &Path) -> std::sync::Arc<std::sync::Mutex<()>> {
    use std::collections::HashMap;
    use std::sync::{Mutex, OnceLock};

    static LOCKS: OnceLock<Mutex<HashMap<std::path::PathBuf, std::sync::Arc<Mutex<()>>>>> =
        OnceLock::new();
    let map = LOCKS.get_or_init(|| Mutex::new(HashMap::new()));
    let key = std::fs::canonicalize(root).unwrap_or_else(|_| root.to_path_buf());
    let mut guard = map
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner);
    if let Some(existing) = guard.get(&key) {
        return existing.clone();
    }
    if guard.len() >= 256 {
        // Bound the map. Drop one arbitrary entry; an in-flight
        // creation that holds a clone of the Arc keeps its mutex
        // alive across eviction.
        if let Some(victim) = guard.keys().next().cloned() {
            guard.remove(&victim);
        }
    }
    let lock = std::sync::Arc::new(Mutex::new(()));
    guard.insert(key, lock.clone());
    lock
}

/// Hard cap on the on-disk `master.key` file. The largest legitimate
/// envelope is the v3 FIDO2-wrapped form: `ESV3` magic + a few hundred
/// bytes of credential id + nonce + AEAD-tagged 32-byte master key.
/// 64 KiB is two orders of magnitude beyond that and stops a hostile
/// filesystem swap from forcing envseal to read a multi-GB file into
/// RAM during unlock — defense-in-depth against pre-AEAD denial-of-
/// service. Every legitimate master.key path validates magic + length
/// after the read; this cap just bounds the read itself.
const MASTER_KEY_MAX_BYTES: u64 = 64 * 1024;

/// Read a `master.key` file with a hard byte cap. Equivalent to
/// `std::fs::read` for files within the cap; for oversized files
/// returns the same `io::Error` shape as a malformed read so callers
/// can keep their existing error handling.
fn read_master_key_capped(path: &Path) -> std::io::Result<Vec<u8>> {
    use std::io::Read;
    let f = fs::File::open(path)?;
    // M/L batch (audit, May 2026): refuse master.key files with
    // more than one hard link. An attacker with write access to
    // the parent dir can `ln <root>/master.key <attacker>/copy`
    // BEFORE envseal opens the vault, then read the AEAD-wrapped
    // bytes from the copy as soon as envseal has it open. The
    // wrap is still keyed to the device hardware seal so the
    // copy is useless without our process — but the property we
    // want is "the file at this path was always reachable only
    // through this path." nlink > 1 violates that and we surface
    // the tamper as an io::Error::PermissionDenied so the
    // caller's existing error path triggers.
    #[cfg(unix)]
    {
        use std::os::unix::fs::MetadataExt;
        let meta = f.metadata()?;
        if meta.nlink() > 1 {
            return Err(std::io::Error::new(
                std::io::ErrorKind::PermissionDenied,
                format!(
                    "master.key has {} hard links — refusing to load. Someone created \
                     a hard link to your vault key. Run `find / -inum {}` to identify \
                     the foreign reference, then re-create the vault.",
                    meta.nlink(),
                    meta.ino()
                ),
            ));
        }
    }
    #[cfg(windows)]
    {
        use std::os::windows::io::AsRawHandle;
        use windows_sys::Win32::Storage::FileSystem::{
            GetFileInformationByHandle, BY_HANDLE_FILE_INFORMATION,
        };
        let mut info: BY_HANDLE_FILE_INFORMATION = unsafe { std::mem::zeroed() };
        let ok = unsafe {
            GetFileInformationByHandle(f.as_raw_handle().cast::<core::ffi::c_void>(), &mut info)
        };
        if ok != 0 && info.nNumberOfLinks > 1 {
            return Err(std::io::Error::new(
                std::io::ErrorKind::PermissionDenied,
                format!(
                    "master.key has {} hard links — refusing to load. Someone created \
                     a hard link to your vault key.",
                    info.nNumberOfLinks
                ),
            ));
        }
    }
    let mut out = Vec::new();
    f.take(MASTER_KEY_MAX_BYTES).read_to_end(&mut out)?;
    Ok(out)
}

use aes_gcm::aead::{Aead, OsRng};
use aes_gcm::{AeadCore, Aes256Gcm, Key, KeyInit};
use argon2::{Algorithm, Argon2, Params, Version};
use hkdf::Hkdf;
use rand::RngCore;
use sha2::Sha256;
use zeroize::Zeroizing;
// `Zeroize` is only consumed inside the Linux `try_memfd_secret` path
// where we explicitly clear the stack copy of the master key after
// migrating it into `memfd_secret`-protected memory. Gating the
// import keeps it from being a dead-code warning on macOS/Windows.
#[cfg(target_os = "linux")]
use zeroize::Zeroize;

use crate::error::Error;
use crate::gui;
use crate::vault::hardware::{self, Backend, DeviceKeystore};

/// Argon2id salt length in bytes.
const ARGON2_SALT_LEN: usize = 16;

/// AES-256-GCM nonce length in bytes.
const NONCE_LEN: usize = 12;

/// Master key length in bytes (AES-256).
const MASTER_KEY_LEN: usize = 32;

/// Minimum passphrase length in characters.
const MIN_PASSPHRASE_LEN: usize = 8;

/// A zeroizing wrapper around the 32-byte master key.
///
/// The key is held in protected memory:
/// - Linux 5.14+: `memfd_secret()` — memory unmapped from kernel page tables,
///   invisible to root via `/proc/pid/mem`, ptrace, and core dumps.
/// - Older Linux / macOS: `mlock()` — prevents swap but visible to root.
///
/// Zeroed on drop via the `Zeroizing` wrapper.
pub struct MasterKey {
    /// The raw key bytes. Zeroized on drop.
    bytes: Zeroizing<[u8; MASTER_KEY_LEN]>,

    /// If true, the key is stored in a `memfd_secret` region.
    /// On drop, we close the fd instead of calling munlock.
    #[cfg(target_os = "linux")]
    in_secret_mem: bool,

    /// The `memfd_secret` file descriptor (if allocated).
    #[cfg(target_os = "linux")]
    secret_fd: Option<i32>,
    /// Pointer to mapped `memfd_secret` region.
    #[cfg(target_os = "linux")]
    secret_ptr: Option<usize>,
}

impl MasterKey {
    /// Get the key as an AES-256-GCM key reference.
    pub fn as_aes_key(&self) -> &Key<Aes256Gcm> {
        Key::<Aes256Gcm>::from_slice(self.as_bytes())
    }

    /// Get the raw key bytes (for HMAC signing).
    pub fn as_bytes(&self) -> &[u8; MASTER_KEY_LEN] {
        #[cfg(target_os = "linux")]
        {
            if self.in_secret_mem {
                if let Some(ptr) = self.secret_ptr {
                    // SAFETY: ptr points to a valid memfd_secret region containing the key
                    return unsafe { &*(ptr as *const [u8; MASTER_KEY_LEN]) };
                }
            }
        }
        &self.bytes
    }

    /// Protect the key bytes using the strongest available mechanism for the
    /// running OS.
    ///
    /// - **Linux 5.14+**: `memfd_secret()` — memory unmapped from kernel page
    ///   tables, invisible to root via `/proc/pid/mem`, ptrace, and core
    ///   dumps.
    /// - **Linux (older) / macOS**: `mlock()` — prevents swap; on Linux also
    ///   `MADV_DONTDUMP` to keep the page out of any future core dump.
    /// - **Windows**: `VirtualLock` — analogous to `mlock`, prevents the
    ///   working set page holding the key from being paged out to disk.
    ///
    /// # Audit H4 — loud-fail on total fallback
    ///
    /// If none of the platform-specific mechanisms succeeds (kernel too
    /// old, ulimit too tight, no `CAP_IPC_LOCK`, Windows page-quota
    /// exhausted, etc.) the master key remains in a regular pageable
    /// allocation — readable from `/proc/<pid>/mem` by anything with
    /// the same UID, and potentially swappable to disk. That is a
    /// material weakening of the threat model and the operator must
    /// know about it. We emit a `memory.protection.unavailable` signal
    /// through the unified guard pipeline so it surfaces in the
    /// startup audit, doctor, and audit log — not silently into the
    /// void as before.
    fn protect(&mut self) {
        let mut any_succeeded = false;

        #[cfg(target_os = "linux")]
        {
            if self.try_memfd_secret() {
                return;
            }
        }

        // Fallback: mlock (all Unix platforms) + MADV_DONTDUMP. mlock
        // returns 0 on success, -1 on failure; we surface the failure
        // through the signal pipeline rather than burying it.
        #[cfg(unix)]
        {
            // SAFETY: bytes is a stable allocation of MASTER_KEY_LEN
            // bytes for the lifetime of the MasterKey.
            let rc =
                unsafe { libc::mlock(self.bytes.as_ptr().cast::<libc::c_void>(), MASTER_KEY_LEN) };
            if rc == 0 {
                any_succeeded = true;
            }
        }

        // ALWAYS ON: Mark key pages as DONTDUMP (belt-and-suspenders)
        #[cfg(target_os = "linux")]
        {
            crate::guard::mark_dontdump(self.bytes.as_ptr(), MASTER_KEY_LEN);
        }

        // Windows: VirtualLock pins the page in physical memory (no swap).
        // Best-effort — a page-cap quota or insufficient privilege will
        // make this fail; we accept the unprotected fallback rather than
        // refusing to open the vault, but we *announce* the fallback so
        // the operator's audit log and doctor view show it.
        #[cfg(windows)]
        {
            // SAFETY: bytes is a stable allocation of MASTER_KEY_LEN
            // bytes for the lifetime of the MasterKey. VirtualLock
            // returns nonzero on success.
            let ok = unsafe {
                use windows_sys::Win32::System::Memory::VirtualLock;
                VirtualLock(self.bytes.as_ptr() as *mut std::ffi::c_void, MASTER_KEY_LEN)
            } != 0;
            if ok {
                any_succeeded = true;
            }
        }

        if !any_succeeded {
            announce_memory_protection_unavailable();
        }
    }

    /// Attempt to store the key in `memfd_secret` memory.
    ///
    /// Returns true if successful, false if the syscall is unavailable
    /// (older kernel, `CONFIG_SECRETMEM` disabled, etc.).
    #[cfg(target_os = "linux")]
    fn try_memfd_secret(&mut self) -> bool {
        // memfd_secret() syscall number (x86_64)
        #[cfg(target_arch = "x86_64")]
        const SYS_MEMFD_SECRET: libc::c_long = 447;

        #[cfg(target_arch = "aarch64")]
        const SYS_MEMFD_SECRET: libc::c_long = 447;

        // Only proceed on known architectures
        #[cfg(not(any(target_arch = "x86_64", target_arch = "aarch64")))]
        {
            return false;
        }

        #[cfg(any(target_arch = "x86_64", target_arch = "aarch64"))]
        unsafe {
            // Create a memfd_secret file descriptor
            // MUST pass O_CLOEXEC, otherwise execve() preserves the FD
            // into the untrusted child process, exposing the plaintext Master Key!
            let fd = libc::syscall(SYS_MEMFD_SECRET, libc::O_CLOEXEC as u32);
            if fd < 0 {
                // Syscall not available — kernel too old or secretmem disabled
                return false;
            }
            #[allow(clippy::cast_possible_truncation)]
            let fd = fd as i32;

            // Set the size to hold the master key
            #[allow(clippy::cast_possible_wrap)]
            let key_size = MASTER_KEY_LEN as libc::off_t;
            if libc::ftruncate(fd, key_size) != 0 {
                libc::close(fd);
                return false;
            }

            // Map the secret memory
            let ptr = libc::mmap(
                std::ptr::null_mut(),
                MASTER_KEY_LEN,
                libc::PROT_READ | libc::PROT_WRITE,
                libc::MAP_SHARED,
                fd,
                0,
            );

            if ptr == libc::MAP_FAILED {
                libc::close(fd);
                return false;
            }

            // Copy key bytes into the secret memory region
            std::ptr::copy_nonoverlapping(self.bytes.as_ptr(), ptr.cast::<u8>(), MASTER_KEY_LEN);

            // Update self.bytes to point to... actually, since self.bytes is
            // a fixed array we can't change its address. Instead, we copy into
            // the secret region and zeroize the original location.
            // The key is now in BOTH locations briefly — zeroize the stack copy.
            // (The Zeroizing wrapper will handle the in-struct copy on drop.)

            self.in_secret_mem = true;
            self.secret_fd = Some(fd);
            self.secret_ptr = Some(ptr as usize);

            // Note: we keep the key in self.bytes for API compatibility.
            // The secret mmap region is the primary copy that is root-invisible.
            // Zeroize the stack copy immediately to prevent root-access leak.
            self.bytes.zeroize();
            // On drop, we zeroize and munmap the secret region.

            true
        }
    }
}

impl Drop for MasterKey {
    fn drop(&mut self) {
        #[cfg(target_os = "linux")]
        {
            if self.in_secret_mem {
                if let Some(ptr) = self.secret_ptr {
                    let ptr = ptr as *mut libc::c_void;
                    unsafe {
                        libc::explicit_bzero(ptr, MASTER_KEY_LEN);
                        libc::munmap(ptr, MASTER_KEY_LEN);
                    }
                }
                if let Some(fd) = self.secret_fd {
                    unsafe {
                        // The secret region was mapped from the fd
                        // Closing the fd + the Zeroizing wrapper handles cleanup
                        libc::close(fd);
                    }
                }
                // Don't munlock — memfd_secret doesn't use mlock
                // Zeroizing wrapper handles zeroing self.bytes
                return;
            }
        }

        // Fallback: munlock the mlock'd region
        #[cfg(unix)]
        unsafe {
            libc::munlock(self.bytes.as_ptr().cast::<libc::c_void>(), MASTER_KEY_LEN);
        }

        // Windows: undo the VirtualLock we performed in `protect`.
        #[cfg(windows)]
        unsafe {
            use windows_sys::Win32::System::Memory::VirtualUnlock;
            VirtualUnlock(self.bytes.as_ptr() as *mut std::ffi::c_void, MASTER_KEY_LEN);
        }
        // Zeroizing wrapper handles the actual zeroing.
    }
}

/// Announce, exactly once per process, that no memory-protection
/// mechanism succeeded for the master key.
///
/// Routed through the unified Signal pipeline so the message lands
/// in the audit log, the doctor view, and (because it's a `Warn`
/// signal at the highest tier) in the next startup audit. We
/// deduplicate via a single `AtomicBool` so subsequent vault opens in
/// the same process do not re-emit the warning.
fn announce_memory_protection_unavailable() {
    use std::sync::atomic::{AtomicBool, Ordering};
    static ANNOUNCED: AtomicBool = AtomicBool::new(false);
    if ANNOUNCED.swap(true, Ordering::AcqRel) {
        return;
    }
    let _ = crate::guard::emit_signal_inline(
        crate::guard::Signal::new(
            crate::guard::SignalId::new("memory.protection.unavailable"),
            crate::guard::Category::DiskPermissions,
            crate::guard::Severity::Warn,
            "master-key memory is not protected",
            "all platform memory-protection mechanisms (memfd_secret, mlock, \
             VirtualLock) failed; the master key is in regular pageable \
             memory and may be readable from /proc/<pid>/mem or swapped to \
             disk. Likely cause: ulimit -l 0 (no CAP_IPC_LOCK), an SELinux \
             policy that denies mlock, or a Windows page-quota cap.",
            "raise the per-process locked-memory limit (e.g. `ulimit -l \
             unlimited` or `setcap cap_ipc_lock+ep $(which envseal)`); on \
             Windows, run as a user with `SeLockMemoryPrivilege`",
        ),
        &crate::security_config::load_system_defaults(),
    );
}

impl std::fmt::Debug for MasterKey {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("MasterKey")
            .field("bytes", &"[REDACTED]")
            .finish()
    }
}

/// Create a `MasterKey` from raw bytes — **test / fuzzing only**.
///
/// # ⚠️ Security warning (audit M21)
///
/// This bypasses the passphrase, hardware seal, and FIDO2 layers
/// entirely. It exists so integration tests in `core/tests/` can
/// drive the vault state machine without a real GUI / authenticator,
/// and for `cargo-fuzz`. It is gated behind:
///
/// 1. The `test-backdoors` cargo feature, which is only enabled by
///    the dev-dependency alias in `core/Cargo.toml`. A regular
///    `cargo build` (release or debug) does **not** see this method.
/// 2. A runtime guard ([`assert_test_backdoor_safe`]) that aborts
///    the process if this constructor is reached outside a Cargo
///    test / fuzz / bench harness or without an explicit
///    `ENVSEAL_TEST_BACKDOORS_OK=1` opt-in. A compromised build that
///    flips `--features test-backdoors` for a release binary will
///    therefore fail to actually use the backdoor at runtime,
///    rather than silently exposing `Vault::open_with_key`.
// C6: gate the test-only constructor at compile time so a release
// binary (which is built without `--features test-backdoors`) does
// not contain the symbol at all. A downstream consumer or
// compromised build script that flips the feature on a release
// build is now visible to anyone running `nm` on the binary; the
// runtime guard inside the body remains as defense-in-depth.
#[cfg(any(test, feature = "test-backdoors"))]
#[doc(hidden)]
impl MasterKey {
    /// Create a `MasterKey` directly from raw bytes (testing only).
    ///
    /// Aborts the process when invoked outside a recognized test /
    /// fuzz / bench environment — see [`assert_test_backdoor_safe`].
    pub fn from_test_bytes(bytes: [u8; MASTER_KEY_LEN]) -> Self {
        crate::test_backdoors::assert_test_backdoor_safe();
        let mut key = Self {
            bytes: Zeroizing::new(bytes),
            #[cfg(target_os = "linux")]
            in_secret_mem: false,
            #[cfg(target_os = "linux")]
            secret_fd: None,
            #[cfg(target_os = "linux")]
            secret_ptr: None,
        };
        key.protect();
        key
    }
}

/// Path to the master key file within a vault root.
pub fn master_key_path(root: &Path) -> PathBuf {
    root.join("master.key")
}

/// Load or create the master key.
///
/// On first run: prompts for a new passphrase via GUI, generates a random
/// master key, wraps it with the passphrase, and writes to disk.
///
/// On subsequent runs: prompts for the passphrase via GUI and unwraps
/// the stored master key.
///
/// CLI/MCP callers use this. Desktop GUI callers use
/// [`open_master_key_with_passphrase`] (which dispatches to the
/// private `create_master_key_with` / `unlock_master_key_with`
/// helpers as appropriate) so the passphrase comes from the
/// in-window egui modal instead of a platform GUI dialog.
pub fn open_master_key(root: &Path) -> Result<MasterKey, Error> {
    let mk_path = master_key_path(root);
    if !mk_path.exists() {
        return create_master_key(root, &mk_path);
    }
    // Audit H5: if `master.key` exists but parses as neither a valid
    // v2 (hardware) envelope nor a long-enough v1 inner blob, refuse
    // to silently delete it. Silent deletion is dangerous: a bad
    // backup, a partial filesystem write, or a stray-byte attack
    // could otherwise be turned into an "envseal happily creates a
    // new vault and loses every secret" event with no audit trail.
    // Surface a hard error and an audit-logged event; the operator
    // can recover the file from backup or run the explicit
    // `envseal emergency-revoke` flow if they really do want a fresh
    // start.
    match read_master_key_capped(&mk_path) {
        Err(e) => Err(Error::StorageIo(e)),
        Ok(raw) => {
            if crate::vault::hardware::parse_v2(&raw).is_ok() {
                return unlock_master_key(&mk_path);
            }
            let min_v1_len = ARGON2_SALT_LEN + NONCE_LEN;
            if raw.len() >= min_v1_len {
                return unlock_master_key(&mk_path);
            }
            let _ = crate::audit::log_required_at(
                root,
                &crate::audit::AuditEvent::SignalRecorded {
                    tier: "Lockdown".to_string(),
                    classification: format!(
                        "critical [vault.master_key.corrupt] {} bytes (need >= {min_v1_len}); \
                         refusing to auto-delete",
                        raw.len()
                    ),
                },
            );
            Err(Error::CryptoFailure(format!(
                "master.key at {} is too short to be valid ({} bytes; need >= {min_v1_len}). \
                 envseal refuses to silently delete it — a partial write or corrupted backup \
                 could otherwise cause every stored secret to be lost without warning. \
                 To start fresh, explicitly remove the file yourself \
                 (`rm {}/master.key`), or restore the file from a backup. \
                 If you intend to wipe the vault, use `envseal emergency-revoke`.",
                mk_path.display(),
                raw.len(),
                root.display(),
            )))
        }
    }
}

/// Unlock or create the master key using a caller-supplied passphrase.
///
/// Same as [`open_master_key`] but never prompts via the platform GUI —
/// callers (typically the desktop GUI) supply the passphrase themselves.
/// Refuses to create a new vault when one already exists; refuses to
/// unlock when none exists. The caller decides which path applies.
///
/// # Errors
/// `Error::SecretAlreadyExists` if the caller asks to create but a
/// vault is already initialized; `Error::SecretNotFound` for unlock
/// against a missing vault; underlying crypto errors otherwise.
pub fn open_master_key_with_passphrase(
    root: &Path,
    passphrase: &Zeroizing<String>,
) -> Result<MasterKey, Error> {
    let mk_path = master_key_path(root);
    if !mk_path.exists() {
        return create_master_key_with(root, &mk_path, passphrase);
    }

    // Audit H5: same hard-fail policy as `open_master_key`. We
    // refuse to silently delete a too-short master.key. The desktop
    // GUI surfaces the returned `CryptoFailure` directly, so the
    // user sees the explanation instead of an unprompted "vault
    // was reset" surprise.
    match read_master_key_capped(&mk_path) {
        Err(e) => Err(Error::StorageIo(e)),
        Ok(raw) => {
            if crate::vault::hardware::parse_v2(&raw).is_ok() {
                return audit_wrong_passphrase(root, unlock_master_key_with(&mk_path, passphrase));
            }
            let min_v1_len = ARGON2_SALT_LEN + NONCE_LEN;
            if raw.len() >= min_v1_len {
                return audit_wrong_passphrase(root, unlock_master_key_with(&mk_path, passphrase));
            }
            let _ = crate::audit::log_required_at(
                root,
                &crate::audit::AuditEvent::SignalRecorded {
                    tier: "Lockdown".to_string(),
                    classification: format!(
                        "critical [vault.master_key.corrupt] {} bytes (need >= {min_v1_len}); \
                         refusing to auto-delete",
                        raw.len()
                    ),
                },
            );
            Err(Error::CryptoFailure(format!(
                "master.key at {} is too short to be valid ({} bytes; need >= {min_v1_len}). \
                 envseal refuses to silently delete it — restore from backup, or explicitly \
                 remove the file yourself if you intend to start over.",
                mk_path.display(),
                raw.len(),
            )))
        }
    }
}

/// Create a new master key protected by a passphrase + the strongest
/// available hardware key store on this device.
fn create_master_key(root: &Path, mk_path: &Path) -> Result<MasterKey, Error> {
    let passphrase =
        gui::request_passphrase(true, &crate::security_config::load_system_defaults())?;
    create_master_key_with(root, mk_path, &passphrase)
}

/// Same as [`create_master_key`] but takes the passphrase as a parameter
/// so the desktop GUI can supply it from its own in-window modal.
///
/// # C7 race handling
///
/// Two simultaneous `envseal store` calls on a fresh vault used to
/// both observe `master.key` missing, both generate a fresh key,
/// and the second `fs::rename` would overwrite the first. Every
/// secret stored under the lost key was permanently undecryptable.
/// We now serialize under a per-vault advisory lock and re-check
/// `mk_path.exists()` while holding it; if the file appeared
/// between the caller's first check and this point, we re-enter
/// the unlock path with the supplied passphrase instead of
/// generating a second master key. The on-disk write itself uses
/// `O_EXCL` / `CREATE_NEW` so even if the lock layer is somehow bypassed
/// (e.g. by a future refactor that drops the lock), the second
/// writer's open fails closed rather than overwriting silently.
fn create_master_key_with(
    root: &Path,
    mk_path: &Path,
    passphrase: &Zeroizing<String>,
) -> Result<MasterKey, Error> {
    // Serialize all create_master_key_with calls per vault root.
    // In-process via a HashMap-of-Mutex; cross-process via the
    // shared `vault.lock` advisory lock file. The audit log uses
    // the same pattern; see `audit::log::append_lock_for`.
    let init_lock = vault_init_lock_for(root);
    let _proc_guard = init_lock
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner);
    let xprocess_lock_path = root.join("vault.lock");
    let _xprocess_lock =
        crate::config::persistence::advisory_lock::acquire(&xprocess_lock_path, true).map_err(
            |e| Error::CryptoFailure(format!("vault init cross-process lock acquire failed: {e}")),
        )?;

    // While we hold the lock, the file may have been created by a
    // peer who acquired the lock first. If so, take the unlock path
    // with the same passphrase.
    if mk_path.exists() {
        return unlock_master_key_with(mk_path, passphrase);
    }

    validate_passphrase(passphrase)?;

    // Generate random master key
    let mut master_bytes = [0u8; MASTER_KEY_LEN];
    OsRng.fill_bytes(&mut master_bytes);

    // Generate random Argon2 salt
    let mut argon2_salt = [0u8; ARGON2_SALT_LEN];
    OsRng.fill_bytes(&mut argon2_salt);

    // Derive wrapping key from passphrase
    let wrapping_key = derive_wrapping_key(passphrase, &argon2_salt)?;

    // Encrypt master key with wrapping key
    let cipher = Aes256Gcm::new(Key::<Aes256Gcm>::from_slice(wrapping_key.as_ref()));
    let nonce = Aes256Gcm::generate_nonce(&mut OsRng);
    let ciphertext = cipher
        .encrypt(&nonce, master_bytes.as_ref())
        .map_err(|e| Error::CryptoFailure(format!("failed to wrap master key: {e}")))?;

    // Inner v1 envelope: argon2_salt || nonce || ciphertext+tag
    let mut inner = Vec::with_capacity(ARGON2_SALT_LEN + NONCE_LEN + ciphertext.len());
    inner.extend_from_slice(&argon2_salt);
    inner.extend_from_slice(&nonce);
    inner.extend_from_slice(&ciphertext);

    fs::create_dir_all(root)?;
    write_master_file(mk_path, &inner)?;

    let mut key = MasterKey {
        bytes: Zeroizing::new(master_bytes),
        #[cfg(target_os = "linux")]
        in_secret_mem: false,
        #[cfg(target_os = "linux")]
        secret_fd: None,
        #[cfg(target_os = "linux")]
        secret_ptr: None,
    };
    key.protect();
    master_bytes.fill(0);
    argon2_salt.fill(0);

    // Zeroize the wrapping key
    drop(wrapping_key);

    Ok(key)
}

/// H batch 4 (audit, May 2026): persistent unlock-failure
/// counter. The previous design only tracked failures in
/// process-local atomics; spawning N envseal processes gave
/// N× the rate limit. The counter is now persisted to
/// `<root>/.unlock_failures` so two processes share the same
/// budget. Format: `count:last_attempt_unix_ts` (plain ASCII —
/// the values are non-sensitive metadata, not secrets).
fn unlock_failure_path(root_or_mk: &Path) -> std::path::PathBuf {
    // mk_path is `<root>/master.key`; failures live next to it.
    root_or_mk.parent().map_or_else(
        || std::path::PathBuf::from(".unlock_failures"),
        |p| p.join(".unlock_failures"),
    )
}

fn read_unlock_failures(path: &Path) -> (u32, u64) {
    let Ok(s) = std::fs::read_to_string(path) else {
        return (0, 0);
    };
    let trimmed = s.trim();
    let mut parts = trimmed.splitn(2, ':');
    let count = parts
        .next()
        .and_then(|c| c.parse::<u32>().ok())
        .unwrap_or(0);
    let ts = parts
        .next()
        .and_then(|t| t.parse::<u64>().ok())
        .unwrap_or(0);
    (count, ts)
}

fn write_unlock_failures(path: &Path, count: u32, ts: u64) {
    use std::io::Write as _;
    // Best-effort: a write failure here doesn't compromise the
    // lock (the in-memory retry loop still bounds attempts at
    // MAX_UNLOCK_ATTEMPTS). The persistent counter is defense in
    // depth against process-respawn evasion.
    //
    // Symlink-destruction defense: route through a tmp+rename so
    // an attacker who plants a symlink at `path` (a sibling of
    // master.key in the vault root) cannot redirect this write to
    // an arbitrary file. fs::rename replaces the symlink rather
    // than following it, and the tmp file is created in the same
    // directory with O_EXCL so we don't clobber an attacker-planted
    // tmp either.
    let body = format!("{count}:{ts}");
    let pid = std::process::id();
    let nanos = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map_or(0, |d| d.as_nanos());
    let tmp_name = format!(".unlock_failures.tmp.{pid}.{nanos}");
    let tmp = path.with_file_name(tmp_name);
    if let Ok(mut f) = crate::file::atomic_open::create_new_no_traverse(&tmp) {
        if f.write_all(body.as_bytes()).is_ok() && f.sync_all().is_ok() {
            drop(f);
            if std::fs::rename(&tmp, path).is_err() {
                let _ = std::fs::remove_file(&tmp);
            }
        } else {
            drop(f);
            let _ = std::fs::remove_file(&tmp);
        }
    }
}

/// Block the calling thread for an exponentially-growing window
/// based on the persistent failure count. Conservative bounds so
/// a typo doesn't lock the operator out for an hour. Backoff
/// curve matches the OWASP guidance for KDF-already-slow
/// passphrase prompts:
///   <  3 failures: no extra wait (Argon2id alone is ~0.5s)
///   3, 4 failures: +1s
///   5, 6, 7:       +5s
///   8, 9:          +15s
///   10–19:         +60s
///   20+:           +300s
fn unlock_failure_backoff(count: u32) -> std::time::Duration {
    use std::time::Duration;
    match count {
        0..=2 => Duration::from_millis(0),
        3 | 4 => Duration::from_secs(1),
        5..=7 => Duration::from_secs(5),
        8 | 9 => Duration::from_secs(15),
        10..=19 => Duration::from_secs(60),
        _ => Duration::from_secs(300),
    }
}

fn now_unix_ts() -> u64 {
    std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map_or(0, |d| d.as_secs())
}

/// Unlock an existing master key by asking for the passphrase.
///
/// On v2 files, the inner envelope is first unwrapped by the active
/// hardware backend; if the file was sealed on a different device, the
/// hardware unseal fails with a descriptive `CryptoFailure` and the
/// passphrase is never even prompted for. This is the "sudo can't read
/// the key from another machine" guarantee.
///
/// Files that aren't a parseable v2 envelope are rejected as corrupted.
///
/// Loops on wrong-passphrase up to [`MAX_UNLOCK_ATTEMPTS`] times,
/// re-rendering the platform dialog with an inline "Incorrect
/// passphrase" hint between attempts. Without this loop a single
/// typo bounced the user all the way back to the CLI with a cryptic
/// `decryption failed` error and no way to retry without re-running
/// the original command. Hard-fail crypto errors (corrupted file,
/// hardware-seal mismatch, etc.) are returned immediately without
/// burning retries — only `wrong passphrase` decryption failures
/// trigger the loop.
fn unlock_master_key(mk_path: &Path) -> Result<MasterKey, Error> {
    let cfg = crate::security_config::load_system_defaults();
    let mut prev_error: Option<String> = None;
    let failures_path = unlock_failure_path(mk_path);
    // H batch 4: read the persistent counter ONCE per CLI
    // invocation; every wrong-passphrase iteration below
    // increments and applies the backoff. After MAX_UNLOCK_ATTEMPTS
    // we return without resetting — the persistent count carries
    // across process spawns so a script that re-runs the binary
    // can't dodge the backoff.
    let (initial_count, _last_ts) = read_unlock_failures(&failures_path);
    let backoff = unlock_failure_backoff(initial_count);
    if !backoff.is_zero() {
        eprintln!(
            "envseal: {} prior failed unlock(s), waiting {}s before prompting",
            initial_count,
            backoff.as_secs()
        );
        std::thread::sleep(backoff);
    }
    for attempt in 1..=MAX_UNLOCK_ATTEMPTS {
        let passphrase = gui::request_passphrase_with_hint(false, prev_error.as_deref(), &cfg)?;

        // Hot-fast path: try the legacy unlock. v1/v2 vaults
        // succeed here; v3 vaults fail closed with Fido2Required so
        // we can pick up the hardware path below without
        // double-prompting for the passphrase.
        let result = unlock_master_key_with(mk_path, &passphrase);

        // v3 vault dispatch — only available when the build
        // includes the `fido2-hardware` feature. Otherwise we let
        // the underlying Fido2Required propagate so the operator
        // sees a clear "rebuild with --features fido2-hardware"
        // message via the CLI.
        #[cfg(feature = "fido2-hardware")]
        let result = match result {
            Err(Error::Fido2Required) => {
                let mut auth = crate::vault::fido2_hardware::HwAuthenticator::discover()?;
                fido2_unlock::unlock_master_key_with_fido2(mk_path, &passphrase, &mut auth)
            }
            other => other,
        };

        match result {
            Ok(key) => {
                // H batch 4: clear the persistent failure counter
                // on a successful unlock so the next run starts
                // from zero. Best-effort; a write failure here
                // doesn't compromise the unlock that just happened.
                write_unlock_failures(&failures_path, 0, now_unix_ts());
                return Ok(key);
            }
            Err(Error::CryptoFailure(msg)) if msg.contains("wrong passphrase") => {
                // H batch 4: bump the persistent counter on every
                // wrong-passphrase iteration, so two parallel
                // envseal invocations share one budget instead of
                // each getting MAX_UNLOCK_ATTEMPTS independently.
                let (cur, _) = read_unlock_failures(&failures_path);
                let next = cur.saturating_add(1);
                write_unlock_failures(&failures_path, next, now_unix_ts());
                // Audit the failure so a brute-force run leaves an
                // on-the-record trail. The chain ensures the entries
                // can't be silently rewritten; deleting the log
                // itself rotates a `audit.log.corrupted-*` sibling
                // that ctf_doctor flags. We use SignalRecorded
                // rather than a dedicated variant so the existing
                // policy / signal-override pipeline applies — an
                // operator who wants to escalate this to a Block
                // under Lockdown can do so via security.toml.
                let _ = crate::audit::log(&crate::audit::AuditEvent::SignalRecorded {
                    tier: format!("{:?}", cfg.tier),
                    classification: format!(
                        "warn [vault.unlock.wrong_passphrase] attempt {attempt}/{MAX_UNLOCK_ATTEMPTS}"
                    ),
                });
                let remaining = MAX_UNLOCK_ATTEMPTS - attempt;
                if remaining == 0 {
                    return Err(Error::CryptoFailure(format!(
                        "wrong passphrase after {MAX_UNLOCK_ATTEMPTS} attempts"
                    )));
                }
                prev_error = Some(format!(
                    "Incorrect passphrase. {remaining} attempt{} left.",
                    if remaining == 1 { "" } else { "s" }
                ));
            }
            Err(e) => return Err(e),
        }
    }
    // Loop exit without a return is unreachable given the bounds above,
    // but keep an explicit fallback so the function always returns.
    Err(Error::UserDenied)
}

/// Number of times the unlock dialog will re-prompt on wrong
/// passphrase before giving up. Three matches the OS-level lockscreen
/// behavior most operators are conditioned to expect.
const MAX_UNLOCK_ATTEMPTS: u32 = 3;

/// Same as [`unlock_master_key`] but takes the passphrase as a parameter
/// so the desktop GUI can supply it from its own in-window modal.
fn unlock_master_key_with(
    mk_path: &Path,
    passphrase: &Zeroizing<String>,
) -> Result<MasterKey, Error> {
    let raw = read_master_key_capped(mk_path)?;

    let inner = read_inner_envelope_at(&raw, Some(mk_path))?;

    // v3 envelopes (FIDO2-enrolled vaults) cannot be unlocked through
    // the passphrase-only path — they require an authenticator. Surface
    // a precise error so the caller can prompt the user to attach a key
    // (or use the v3-aware unlock entry point).
    #[cfg(feature = "fido2")]
    if crate::vault::fido2::is_v3(&inner) {
        return Err(Error::Fido2Required);
    }

    unlock_master_key_v1_inner(&inner, passphrase)
}

/// Wrap an unlock result so a wrong-passphrase failure leaves an
/// on-the-record audit entry under the supplied vault root. The
/// `unlock_master_key` retry loop already logs failures it sees on
/// the GUI-prompt path; this helper covers the
/// `open_master_key_with_passphrase` path used by the desktop GUI
/// worker, which the loop never reaches.
fn audit_wrong_passphrase(
    root: &Path,
    result: Result<MasterKey, Error>,
) -> Result<MasterKey, Error> {
    if let Err(Error::CryptoFailure(msg)) = &result {
        if msg.contains("wrong passphrase") {
            let cfg = crate::security_config::load_system_defaults();
            let _ = crate::audit::log_required_at(
                root,
                &crate::audit::AuditEvent::SignalRecorded {
                    tier: format!("{:?}", cfg.tier),
                    classification:
                        "warn [vault.unlock.wrong_passphrase] caller-supplied passphrase rejected"
                            .to_string(),
                },
            );
        }
    }
    result
}

/// Decrypt the master key from a v1 inner blob.
///
/// The v1 inner layout is `[argon2_salt(16)][nonce(12)][ciphertext+tag]`
/// — the original layout shipped before the v2 hardware wrap and v3
/// FIDO2 wrap were added. v2 master.key files carry this same payload
/// inside a hardware envelope; v3 master.key files use a different
/// inner layout that this function does not handle.
fn unlock_master_key_v1_inner(
    inner: &[u8],
    passphrase: &Zeroizing<String>,
) -> Result<MasterKey, Error> {
    let min_len = ARGON2_SALT_LEN + NONCE_LEN;
    if inner.len() < min_len {
        return Err(Error::CryptoFailure(
            "master.key file corrupted: too short".to_string(),
        ));
    }

    let argon2_salt = &inner[..ARGON2_SALT_LEN];
    let nonce_bytes = &inner[ARGON2_SALT_LEN..ARGON2_SALT_LEN + NONCE_LEN];
    let ciphertext = &inner[ARGON2_SALT_LEN + NONCE_LEN..];

    let wrapping_key = derive_wrapping_key(passphrase, argon2_salt)?;

    decrypt_master_key_with_wrap(wrapping_key, nonce_bytes, ciphertext)
}

/// AES-GCM-decrypt the master key bytes given a 32-byte wrapping key,
/// nonce, and ciphertext, then move the plaintext into the protected
/// `MasterKey` storage.
///
/// Shared by the v1 and v3 unlock paths so the AES-GCM error mapping,
/// the master-key-length check, and the `MasterKey::protect()` call
/// live in exactly one place — fixing a bug here fixes both paths.
fn decrypt_master_key_with_wrap(
    wrapping_key: Zeroizing<[u8; 32]>,
    nonce_bytes: &[u8],
    ciphertext: &[u8],
) -> Result<MasterKey, Error> {
    let cipher = Aes256Gcm::new(Key::<Aes256Gcm>::from_slice(wrapping_key.as_ref()));
    let nonce = aes_gcm::Nonce::from_slice(nonce_bytes);

    let master_bytes_vec = Zeroizing::new(cipher.decrypt(nonce, ciphertext).map_err(|_| {
        Error::CryptoFailure(
            "wrong passphrase or corrupted master.key — decryption failed".to_string(),
        )
    })?);

    if master_bytes_vec.len() != MASTER_KEY_LEN {
        return Err(Error::CryptoFailure(format!(
            "master key has wrong length: expected {MASTER_KEY_LEN}, got {}",
            master_bytes_vec.len()
        )));
    }

    let mut master_bytes = [0u8; MASTER_KEY_LEN];
    master_bytes.copy_from_slice(&master_bytes_vec);

    let mut key = MasterKey {
        bytes: Zeroizing::new(master_bytes),
        #[cfg(target_os = "linux")]
        in_secret_mem: false,
        #[cfg(target_os = "linux")]
        secret_fd: None,
        #[cfg(target_os = "linux")]
        secret_ptr: None,
    };
    key.protect();
    master_bytes.fill(0);

    // Zeroize the wrapping key.
    drop(wrapping_key);

    Ok(key)
}

/// Derive a dedicated HMAC key from the master key using HKDF-SHA256.
///
/// Never falls back to the raw master key — domain separation must hold.
pub fn derive_hmac_key(master_key: &[u8; 32]) -> Result<Zeroizing<[u8; 32]>, Error> {
    let hk = Hkdf::<Sha256>::new(Some(b"envseal-hmac-salt-v1"), master_key);
    // Wrap the output in Zeroizing so a forged-HMAC-grade secondary
    // key (effectively as sensitive as the master key for the
    // policy / security_config integrity domain) is wiped from the
    // caller's stack on drop. Every caller already passes the value
    // by reference into `compute_hmac` / `Hmac::new_from_slice` so
    // the migration is transparent.
    let mut out = Zeroizing::new([0u8; 32]);
    hk.expand(b"envseal-policy-security-hmac", out.as_mut())
        .map_err(|_| {
            Error::CryptoFailure(
                "HKDF-derived HMAC key expansion failed (invalid output length)".to_string(),
            )
        })?;
    Ok(out)
}

/// Derive a 32-byte wrapping key from a passphrase using Argon2id.
///
/// Parameters (OWASP recommended):
/// - Memory: 64 MiB
/// - Iterations: 3
/// - Parallelism: 4
fn derive_wrapping_key(passphrase: &str, salt: &[u8]) -> Result<Zeroizing<[u8; 32]>, Error> {
    let params = Params::new(
        65536, // 64 MiB memory
        3,     // 3 iterations
        4,     // 4 parallel lanes
        Some(32),
    )
    .map_err(|e| Error::CryptoFailure(format!("invalid argon2 params: {e}")))?;

    let argon2 = Argon2::new(Algorithm::Argon2id, Version::V0x13, params);

    let mut output = Zeroizing::new([0u8; 32]);
    argon2
        .hash_password_into(passphrase.as_bytes(), salt, output.as_mut())
        .map_err(|e| Error::CryptoFailure(format!("argon2id derivation failed: {e}")))?;

    Ok(output)
}

/// Validate passphrase meets minimum security requirements.
fn validate_passphrase(passphrase: &str) -> Result<(), Error> {
    if passphrase.len() < MIN_PASSPHRASE_LEN {
        return Err(Error::CryptoFailure(format!(
            "passphrase too short: minimum {MIN_PASSPHRASE_LEN} characters required"
        )));
    }
    Ok(())
}

/// Change the passphrase protecting the master key.
///
/// Requires the current passphrase to unlock, then re-wraps with
/// the new passphrase.
pub fn change_passphrase(root: &Path) -> Result<(), Error> {
    let mk_path = master_key_path(root);
    if !mk_path.exists() {
        return Err(Error::CryptoFailure(
            "no master key found — store a secret first".to_string(),
        ));
    }

    // Unlock with current passphrase
    let master_key = unlock_master_key(&mk_path)?;

    // Get new passphrase
    let new_passphrase =
        gui::request_passphrase(true, &crate::security_config::load_system_defaults())?;
    validate_passphrase(&new_passphrase)?;

    // Generate new salt
    let mut new_salt = [0u8; ARGON2_SALT_LEN];
    OsRng.fill_bytes(&mut new_salt);

    // Derive new wrapping key
    let wrapping_key = derive_wrapping_key(&new_passphrase, &new_salt)?;

    // Re-encrypt master key
    let cipher = Aes256Gcm::new(Key::<Aes256Gcm>::from_slice(wrapping_key.as_ref()));
    let nonce = Aes256Gcm::generate_nonce(&mut OsRng);
    let ciphertext = cipher
        .encrypt(&nonce, master_key.as_bytes().as_ref())
        .map_err(|e| Error::CryptoFailure(format!("failed to re-wrap master key: {e}")))?;

    // Write new master.key (re-wrapped with hardware seal)
    let mut inner = Vec::with_capacity(ARGON2_SALT_LEN + NONCE_LEN + ciphertext.len());
    inner.extend_from_slice(&new_salt);
    inner.extend_from_slice(&nonce);
    inner.extend_from_slice(&ciphertext);

    write_master_file(&mk_path, &inner)?;

    Ok(())
}

/// Wrap the passphrase-encrypted inner blob with the active hardware
/// keystore and write the resulting v2 file atomically.
///
/// The sequence is:
/// 1. Seal under the active hardware backend.
/// 2. Pack into the v2 envelope.
/// 3. Write to a `master.key.tmp.<pid>.<nanos>` sibling file with the
///    owner-only permissions/ACL applied at create time (no umask
///    race window).
/// 4. `fsync` the bytes.
/// 5. Atomically `rename` over the existing `master.key`.
///
/// A power loss before step 5 leaves the previous master.key intact
/// and the tmp file orphaned (the tmp filename is unique, so two
/// concurrent rotations don't collide). A power loss after step 5
/// has the new file fully durable.
fn write_master_file(mk_path: &Path, inner: &[u8]) -> Result<(), Error> {
    let keystore = DeviceKeystore::select();
    let backend = keystore.backend();
    // Audit H3: refuse to create or rotate a vault when the device
    // returned `Backend::None` (no DPAPI / Secure Enclave / TPM 2.0
    // available) unless the operator explicitly opted in. The
    // previous behaviour was to silently fall back to passphrase-only
    // sealing — the threat model documented in README/THESIS assumes
    // the master.key envelope is bound to *this device*, and a
    // silent no-hardware fallback weakens that assumption without
    // the operator knowing. The env var name is verbose so it cannot
    // be set by accident and is easy to grep for in audit logs.
    // Recognized test/fuzz/bench environments bypass the refusal so
    // CI runners without a TPM / SEP / DPAPI can exercise the rest
    // of the vault state machine. End-user binaries hit the block.
    //
    // C2 (audit, May 2026): the previous implementation also accepted
    // any executable whose path contained `target/`. An attacker
    // could install `envseal` to `/opt/target/envseal` (or rename
    // their build directory) and silently bypass the hardware-seal
    // requirement. The path-string heuristic is removed; only signals
    // that an end-user attacker cannot fabricate are trusted:
    //   - `cfg!(test)` is compile-time (release binaries can't flip).
    //   - `CARGO_TARGET_TMPDIR` is set by cargo test at runtime.
    //   - `CARGO_FUZZ_TARGET` is set by cargo-fuzz at runtime.
    //   - `ENVSEAL_ACCEPT_NO_HARDWARE_SEAL` is the explicit opt-in
    //     for operators who genuinely lack hardware seal AND have
    //     accepted the residual risk in their threat model.
    let in_test_env = cfg!(test)
        || std::env::var("CARGO_TARGET_TMPDIR").is_ok()
        || std::env::var("CARGO_FUZZ_TARGET").is_ok()
        || std::env::var("ENVSEAL_TEST_BACKDOORS_OK").is_ok();
    if matches!(backend, hardware::Backend::None)
        && std::env::var("ENVSEAL_ACCEPT_NO_HARDWARE_SEAL").is_err()
        && !in_test_env
    {
        let _ = crate::audit::log_required_at(
            mk_path.parent().unwrap_or(std::path::Path::new(".")),
            &crate::audit::AuditEvent::SignalRecorded {
                tier: "Hardened".to_string(),
                classification: "critical [vault.no_hardware_seal] refused master.key write — \
                     no DPAPI / Secure Enclave / TPM 2.0 available"
                    .to_string(),
            },
        );
        return Err(Error::HardwareSealFailed(format!(
            "no hardware-sealing backend is available on this machine \
             (no DPAPI / Secure Enclave / TPM 2.0). envseal refuses to \
             write {} as a passphrase-only vault by default — that downgrade \
             would silently weaken the on-disk threat model. \n\
             \n\
             To proceed anyway (e.g. on a CI runner or a VM without a vTPM), \
             set ENVSEAL_ACCEPT_NO_HARDWARE_SEAL=1 in your environment and \
             rerun the command. The operator who sets that flag is \
             acknowledging that a master.key on this machine is protected \
             only by the Argon2id-wrapped passphrase, not also by a \
             device-bound seal.",
            mk_path.display(),
        )));
    }
    let sealed = keystore
        .seal(inner)
        .map_err(|e| Error::HardwareSealFailed(format!("seal of master.key failed: {e}")))?;
    let envelope = hardware::pack_v2(backend, &sealed);

    let parent = mk_path.parent().ok_or_else(|| {
        Error::CryptoFailure(format!(
            "master.key path {} has no parent — cannot stage atomic write",
            mk_path.display()
        ))
    })?;
    fs::create_dir_all(parent)?;

    let tmp_path = atomic_tmp_path(mk_path);

    #[cfg(unix)]
    {
        use std::io::Write;
        use std::os::unix::fs::OpenOptionsExt;
        // create_new(true) → fails if the tmp already exists, eliminating
        // the chance of writing into a file another process owns.
        let mut f = fs::OpenOptions::new()
            .create_new(true)
            .write(true)
            .mode(0o600)
            .open(&tmp_path)?;
        f.write_all(&envelope)?;
        f.sync_all()?;
        // Drop the file handle before rename so Windows-style file-locking
        // (no-op on Unix) cannot interfere.
        drop(f);
    }
    #[cfg(not(unix))]
    {
        if let Err(e) = fs::write(&tmp_path, &envelope) {
            // Best-effort cleanup of any partial tmp before propagating.
            let _ = fs::remove_file(&tmp_path);
            return Err(Error::StorageIo(e));
        }
        // Apply NTFS owner-only DACL on the tmp BEFORE rename so the
        // final master.key never exists with a permissive ACL.
        #[cfg(windows)]
        {
            let _ = crate::policy::windows_acl::set_owner_only_dacl(&tmp_path);
        }
    }

    // C7: when creating a new master.key (vs rotating an existing
    // one), use a fail-on-exists rename so a concurrent peer that
    // raced through the in-process and cross-process locks somehow
    // still cannot silently overwrite our work. On Unix we use
    // `link()` (which never overwrites) followed by `unlink(tmp)`;
    // on Windows we use `MoveFileExW` without REPLACE_EXISTING.
    //
    // For ROTATION (mk_path already exists), the regular replacing
    // rename is correct behaviour and is what callers want.
    if mk_path.exists() {
        if let Err(e) = fs::rename(&tmp_path, mk_path) {
            let _ = fs::remove_file(&tmp_path);
            return Err(Error::StorageIo(e));
        }
    } else if let Err(e) = exclusive_publish(&tmp_path, mk_path) {
        let _ = fs::remove_file(&tmp_path);
        return Err(e);
    }

    // Best-effort: fsync the parent dir on Unix so the rename is durable.
    #[cfg(unix)]
    {
        if let Ok(dir) = fs::File::open(parent) {
            let _ = dir.sync_all();
        }
    }

    Ok(())
}

/// Move `tmp` to `dst` with strict no-overwrite semantics. Used by
/// the creation path of `write_master_file` to defend against the
/// C7 race where two concurrent vault inits both stage a tmp and
/// the second one's rename clobbers the first one's master.key.
#[cfg(unix)]
fn exclusive_publish(tmp: &Path, dst: &Path) -> Result<(), Error> {
    // POSIX `link(2)` never overwrites: if `dst` exists, link returns
    // EEXIST and we surface it as an Err. After link succeeds, the
    // tmp inode is reachable under both names; unlinking tmp leaves
    // dst pointing at the file we just wrote.
    fs::hard_link(tmp, dst).map_err(|e| {
        if e.kind() == std::io::ErrorKind::AlreadyExists {
            Error::CryptoFailure(format!(
                "master.key at {} appeared while we were writing — \
                 a concurrent vault init won the race; refusing to \
                 overwrite",
                dst.display()
            ))
        } else {
            Error::StorageIo(e)
        }
    })?;
    let _ = fs::remove_file(tmp);
    Ok(())
}

#[cfg(windows)]
fn exclusive_publish(tmp: &Path, dst: &Path) -> Result<(), Error> {
    use std::os::windows::ffi::OsStrExt;
    use windows_sys::Win32::Storage::FileSystem::{MoveFileExW, MOVEFILE_WRITE_THROUGH};
    let tmp_w: Vec<u16> = tmp
        .as_os_str()
        .encode_wide()
        .chain(std::iter::once(0))
        .collect();
    let dst_w: Vec<u16> = dst
        .as_os_str()
        .encode_wide()
        .chain(std::iter::once(0))
        .collect();
    // Without MOVEFILE_REPLACE_EXISTING, MoveFileExW fails with
    // ERROR_ALREADY_EXISTS if dst is present — exactly the
    // semantics we want for the no-overwrite create path.
    // SAFETY: both wide strings are NUL-terminated and live for the call.
    let ok = unsafe { MoveFileExW(tmp_w.as_ptr(), dst_w.as_ptr(), MOVEFILE_WRITE_THROUGH) };
    if ok == 0 {
        let err = std::io::Error::last_os_error();
        if err.kind() == std::io::ErrorKind::AlreadyExists {
            return Err(Error::CryptoFailure(format!(
                "master.key at {} appeared while we were writing — \
                 a concurrent vault init won the race; refusing to \
                 overwrite",
                dst.display()
            )));
        }
        return Err(Error::StorageIo(err));
    }
    Ok(())
}

#[cfg(not(any(unix, windows)))]
fn exclusive_publish(tmp: &Path, dst: &Path) -> Result<(), Error> {
    if dst.exists() {
        return Err(Error::CryptoFailure(format!(
            "master.key at {} appeared while we were writing — \
             refusing to overwrite",
            dst.display()
        )));
    }
    fs::rename(tmp, dst).map_err(Error::StorageIo)
}

/// Build a unique tmp filename for the atomic master.key rotation.
/// `(pid, nanos)` is unique enough — concurrent rotations from the
/// same process within the same nanosecond would collide, but that
/// requires nanosecond-resolution clock contention from a single
/// thread which the standard library prevents.
fn atomic_tmp_path(mk_path: &Path) -> std::path::PathBuf {
    use std::sync::atomic::{AtomicU64, Ordering};
    use std::time::{SystemTime, UNIX_EPOCH};
    static TMP_COUNTER: AtomicU64 = AtomicU64::new(0);
    let pid = std::process::id();
    let nanos = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map_or(0, |d| d.as_nanos());
    let counter = TMP_COUNTER.fetch_add(1, Ordering::Relaxed);
    let thread_id = format!("{:?}", std::thread::current().id());
    let mut p = mk_path.to_path_buf();
    let stem = mk_path
        .file_name()
        .and_then(|s| s.to_str())
        .unwrap_or("master.key");
    p.set_file_name(format!("{stem}.tmp.{pid}.{nanos}.{counter}.{thread_id}"));
    p
}

/// Read a master.key file and return the inner passphrase-wrapped
/// blob.
///
/// v2 is the canonical on-disk format. However, vaults created before
/// the v2 envelope was introduced wrote the raw inner blob
/// (`argon2_salt || nonce || ciphertext+tag`) directly — no magic,
/// no backend id, no length prefix. We call that the "legacy v1"
/// layout.
///
/// When [`hardware::parse_v2`] rejects the blob (missing magic), we
/// check whether the file is a plausible v1 inner blob (≥ 28 bytes =
/// `ARGON2_SALT_LEN + NONCE_LEN` minimum). If so, we accept it as-is
/// and transparently upgrade the file to v2 on disk so subsequent
/// unlocks go through the normal path. This makes the upgrade
/// seamless for existing users.
#[cfg(test)]
fn read_inner_envelope(raw: &[u8]) -> Result<Vec<u8>, Error> {
    read_inner_envelope_at(raw, None)
}

/// Inner implementation that optionally receives the `master.key`
/// path so it can perform the v1→v2 on-disk upgrade.
fn read_inner_envelope_at(raw: &[u8], mk_path: Option<&Path>) -> Result<Vec<u8>, Error> {
    if let Ok(env) = hardware::parse_v2(raw) {
        let keystore = DeviceKeystore::select();
        let active = keystore.backend();
        if env.backend != Backend::None && env.backend != active {
            return Err(Error::DeviceMismatch {
                sealed_by: env.backend.name().to_string(),
                active: active.name().to_string(),
            });
        }
        // An envelope produced by Backend::None is a no-op outer wrap —
        // the sealed bytes ARE the inner blob. Anything else routes
        // through the active backend's unseal.
        if env.backend == Backend::None {
            Ok(env.sealed.to_vec())
        } else {
            keystore.unseal(env.sealed).map_err(|e| {
                Error::HardwareSealFailed(format!(
                    "unseal of master.key failed — likely a different user logon, \
                     a different physical device, or a wiped TPM/SEP keypair: {e}"
                ))
            })
        }
    } else {
        // ── Legacy v1 migration ──────────────────────────────
        // Pre-v2 master.key files are raw inner blobs:
        //   [16 bytes argon2_salt] [12 bytes nonce] [N bytes ciphertext+tag]
        // Minimum plausible size = 16 + 12 = 28 (a ciphertext of
        // zero length is degenerate but structurally valid).
        let min_v1_len = ARGON2_SALT_LEN + NONCE_LEN;
        if raw.len() < min_v1_len {
            return Err(Error::CryptoFailure(
                "master.key is too short to be a valid v1 or v2 file — \
                 the vault may be corrupted"
                    .to_string(),
            ));
        }
        eprintln!(
            "envseal: ℹ️  detected legacy (pre-v2) master.key — \
             upgrading to v2 envelope format on disk"
        );
        // The raw bytes ARE the inner blob in v1 — accept them.
        let inner = raw.to_vec();
        // Best-effort on-disk upgrade: re-wrap through
        // write_master_file which seals with the active hardware
        // backend and writes a proper v2 envelope.
        if let Some(path) = mk_path {
            if let Err(e) = write_master_file(path, &inner) {
                eprintln!(
                    "envseal: ⚠️  v1→v2 on-disk upgrade failed \
                     (vault still usable, will retry next unlock): {e}"
                );
            }
        }
        Ok(inner)
    }
}

/// Report the active hardware keystore backend on this device. Used
/// by `envseal doctor` and the audit log to surface the actual
/// protection tier the user is getting.
pub fn active_backend() -> Backend {
    DeviceKeystore::select().backend()
}

/// FIDO2-aware vault creation and unlock entry points.
///
/// These are gated behind the `fido2` cargo feature so the default
/// build is unaffected. Behavior:
///
/// - [`create_master_key_with_fido2`] — enroll the supplied
///   authenticator, derive the v3 wrapping key from
///   passphrase + hmac-secret, write a v3 envelope.
/// - [`open_master_key_with_passphrase_and_fido2`] — dispatch on the
///   inner blob magic: v3 vaults consume the authenticator, v1/v2
///   vaults bypass it (no FIDO2 prompt).
///
/// The functions exist alongside the existing passphrase-only
/// variants; consumers that don't know about FIDO2 keep working
/// against v1 / v2 vaults exactly as before.
#[cfg(feature = "fido2")]
pub mod fido2_unlock {
    use super::{
        decrypt_master_key_with_wrap, derive_wrapping_key, master_key_path, read_inner_envelope_at,
        unlock_master_key_v1_inner, validate_passphrase, write_master_file, MasterKey,
        ARGON2_SALT_LEN, MASTER_KEY_LEN, NONCE_LEN,
    };
    use crate::error::Error;
    use crate::vault::fido2;
    use aes_gcm::aead::{Aead, OsRng};
    use aes_gcm::{AeadCore, Aes256Gcm, Key, KeyInit};
    use rand::RngCore;
    use std::fs;
    use std::path::Path;
    use zeroize::Zeroizing;

    /// Relying-party id used when minting credentials. Namespaces
    /// envseal vault credentials apart from any web credentials the
    /// same authenticator may hold.
    pub const RELYING_PARTY_ID: &str = "envseal.local";

    /// Relying-party human-readable name shown by some
    /// authenticators (or accompanying GUIs) during enrollment.
    pub const RELYING_PARTY_NAME: &str = "envseal vault";

    /// Open or create the master key, supplying a FIDO2 authenticator.
    ///
    /// Behavior matches [`super::open_master_key_with_passphrase`]
    /// with an additional dispatch:
    ///
    /// - If the file does not exist, a new v3 vault is created and
    ///   the authenticator is enrolled.
    /// - If the file exists and parses as v3, the authenticator is
    ///   consulted to derive the wrapping key.
    /// - If the file exists and parses as v1/v2, the FIDO2 path is
    ///   bypassed entirely and the legacy unlock proceeds — backwards
    ///   compatibility is automatic for users who add a key to an
    ///   already-initialized vault (they will need to re-key via
    ///   `envseal security fido2-enroll` to migrate to v3, which
    ///   ships in commit 2).
    ///
    /// # Errors
    ///
    /// Returns the same errors as the passphrase-only variant plus
    /// [`Error::Fido2AssertionFailed`] when the authenticator
    /// rejects the assertion.
    pub fn open_master_key_with_passphrase_and_fido2<A>(
        root: &Path,
        passphrase: &Zeroizing<String>,
        authenticator: &mut A,
    ) -> Result<MasterKey, Error>
    where
        A: fido2::Fido2Authenticator,
    {
        let mk_path = master_key_path(root);
        let exists = mk_path.exists();

        // Audit H5: refuse to silently delete a too-short master.key.
        // Mirror the policy of `open_master_key` on the FIDO2 path.
        if exists {
            match super::read_master_key_capped(&mk_path) {
                Err(e) => return Err(Error::StorageIo(e)),
                Ok(raw) => {
                    if crate::vault::hardware::parse_v2(&raw).is_err() {
                        let min_v1_len = ARGON2_SALT_LEN + NONCE_LEN;
                        if raw.len() < min_v1_len {
                            let _ = crate::audit::log_required_at(
                                root,
                                &crate::audit::AuditEvent::SignalRecorded {
                                    tier: "Lockdown".to_string(),
                                    classification: format!(
                                        "critical [vault.master_key.corrupt] {} bytes \
                                         (need >= {min_v1_len}); refusing to auto-delete \
                                         (FIDO2 path)",
                                        raw.len()
                                    ),
                                },
                            );
                            return Err(Error::CryptoFailure(format!(
                                "master.key at {} is too short to be valid ({} bytes; need \
                                 >= {min_v1_len}). envseal refuses to silently delete it; \
                                 restore from backup or explicitly remove the file before \
                                 retrying.",
                                mk_path.display(),
                                raw.len(),
                            )));
                        }
                    }
                }
            }
        }

        if exists {
            unlock_master_key_with_fido2(&mk_path, passphrase, authenticator)
        } else {
            create_master_key_with_fido2(root, &mk_path, passphrase, authenticator)
        }
    }

    /// Create a new v3 master.key by enrolling the supplied
    /// authenticator. Writes a v3 inner blob wrapped by the active
    /// hardware backend exactly the same way the v1 path does — the
    /// only difference is the inner layout.
    pub fn create_master_key_with_fido2<A>(
        root: &Path,
        mk_path: &Path,
        passphrase: &Zeroizing<String>,
        authenticator: &mut A,
    ) -> Result<MasterKey, Error>
    where
        A: fido2::Fido2Authenticator,
    {
        validate_passphrase(passphrase)?;

        // Enroll the authenticator. The credential id is opaque to
        // us; we store it verbatim in the envelope.
        let credential_id = authenticator.make_credential(RELYING_PARTY_ID, RELYING_PARTY_NAME)?;

        // Generate fresh random salts for this vault.
        let mut master_bytes = [0u8; MASTER_KEY_LEN];
        OsRng.fill_bytes(&mut master_bytes);

        let mut argon2_salt = [0u8; ARGON2_SALT_LEN];
        OsRng.fill_bytes(&mut argon2_salt);

        let mut hmac_salt = [0u8; fido2::HMAC_SALT_LEN];
        OsRng.fill_bytes(&mut hmac_salt);

        // Pull the FIDO2 hmac-secret response and combine with the
        // Argon2-derived passphrase half to produce the wrapping key.
        let fido2_secret = authenticator.assert_with_hmac(&credential_id, &hmac_salt)?;
        let argon2_output = derive_wrapping_key(passphrase, &argon2_salt)?;
        let wrapping_key =
            fido2::combine_passphrase_and_fido2(&argon2_output, &fido2_secret, &hmac_salt);

        // Encrypt the master key under the v3 wrapping key.
        let cipher = Aes256Gcm::new(Key::<Aes256Gcm>::from_slice(wrapping_key.as_ref()));
        let nonce = Aes256Gcm::generate_nonce(&mut OsRng);
        let ciphertext = cipher
            .encrypt(&nonce, master_bytes.as_ref())
            .map_err(|e| Error::CryptoFailure(format!("v3: failed to wrap master key: {e}")))?;

        let envelope = fido2::V3Envelope {
            credential_id,
            hmac_salt,
            argon2_salt,
            nonce: nonce.into(),
            ciphertext,
        };
        let inner = fido2::pack(&envelope)?;

        fs::create_dir_all(root)?;
        write_master_file(mk_path, &inner)?;

        let mut key = MasterKey {
            bytes: Zeroizing::new(master_bytes),
            #[cfg(target_os = "linux")]
            in_secret_mem: false,
            #[cfg(target_os = "linux")]
            secret_fd: None,
            #[cfg(target_os = "linux")]
            secret_ptr: None,
        };
        key.protect();
        master_bytes.fill(0);
        argon2_salt.fill(0);
        hmac_salt.fill(0);

        // Best-effort wipe of the temporaries — Zeroizing handles the
        // wrapping key and argon2 output.
        drop(wrapping_key);
        drop(argon2_output);

        Ok(key)
    }

    /// Unlock an existing master.key. v3 envelopes consume the
    /// authenticator; v1/v2 envelopes bypass it via the legacy
    /// passphrase path (so attaching a key to a non-FIDO2 vault is
    /// a no-op until the user re-keys with `fido2-enroll`).
    pub fn unlock_master_key_with_fido2<A>(
        mk_path: &Path,
        passphrase: &Zeroizing<String>,
        authenticator: &mut A,
    ) -> Result<MasterKey, Error>
    where
        A: fido2::Fido2Authenticator,
    {
        let raw = super::read_master_key_capped(mk_path)?;
        let inner = read_inner_envelope_at(&raw, Some(mk_path))?;

        if !fido2::is_v3(&inner) {
            // Legacy v1/v2 vault — FIDO2 not in use here. Use the
            // standard passphrase path. The authenticator parameter
            // is intentionally unused; backwards compat means
            // attaching a key to a non-FIDO2 vault is silent.
            let _ = authenticator;
            return unlock_master_key_v1_inner(&inner, passphrase);
        }

        let env = fido2::parse(&inner)?;
        let cred_hash = credential_id_hash(&env.credential_id);

        // Derive both halves and combine. Argon2 first (slow, cheap
        // failure if passphrase is bad? — no, Argon2 cannot fail on
        // bad passphrase since it just hashes; the actual passphrase
        // check happens in AEAD-decrypt below). FIDO2 second (fast,
        // requires touch — bad passphrase still costs the user a
        // touch, which is acceptable: the touch is the second
        // factor, not a confirmation of the first).
        let argon2_output = derive_wrapping_key(passphrase, &env.argon2_salt)?;
        let fido2_secret = match authenticator.assert_with_hmac(&env.credential_id, &env.hmac_salt)
        {
            Ok(s) => s,
            Err(e) => {
                let _ = crate::audit::log(&crate::audit::AuditEvent::Fido2Unlock {
                    credential_id_hash: cred_hash.clone(),
                    succeeded: false,
                });
                return Err(e);
            }
        };
        let wrapping_key =
            fido2::combine_passphrase_and_fido2(&argon2_output, &fido2_secret, &env.hmac_salt);

        let result = decrypt_master_key_with_wrap(wrapping_key, &env.nonce, &env.ciphertext);
        let _ = crate::audit::log(&crate::audit::AuditEvent::Fido2Unlock {
            credential_id_hash: cred_hash,
            succeeded: result.is_ok(),
        });
        result
    }

    /// Re-wrap an unlocked master key from v1/v2 layout into a v3
    /// envelope, enrolling the supplied authenticator.
    ///
    /// Use case: an existing vault user wants to add a security key
    /// without rotating every stored secret. We keep the master key
    /// bytes identical (so every existing `*.seal` file in the
    /// vault still decrypts) and only change the wrapping layer.
    pub fn enroll_fido2_on_existing_master<A>(
        mk_path: &Path,
        master_key: &MasterKey,
        passphrase: &Zeroizing<String>,
        authenticator: &mut A,
    ) -> Result<(), Error>
    where
        A: fido2::Fido2Authenticator,
    {
        validate_passphrase(passphrase)?;

        let credential_id = authenticator.make_credential(RELYING_PARTY_ID, RELYING_PARTY_NAME)?;

        let mut argon2_salt = [0u8; ARGON2_SALT_LEN];
        OsRng.fill_bytes(&mut argon2_salt);

        let mut hmac_salt = [0u8; fido2::HMAC_SALT_LEN];
        OsRng.fill_bytes(&mut hmac_salt);

        let fido2_secret = authenticator.assert_with_hmac(&credential_id, &hmac_salt)?;
        let argon2_output = derive_wrapping_key(passphrase, &argon2_salt)?;
        let wrapping_key =
            fido2::combine_passphrase_and_fido2(&argon2_output, &fido2_secret, &hmac_salt);

        let cipher = Aes256Gcm::new(Key::<Aes256Gcm>::from_slice(wrapping_key.as_ref()));
        let nonce = Aes256Gcm::generate_nonce(&mut OsRng);
        let ciphertext = cipher
            .encrypt(&nonce, master_key.as_bytes().as_ref())
            .map_err(|e| Error::CryptoFailure(format!("v3 enroll: re-wrap failed: {e}")))?;

        let envelope = fido2::V3Envelope {
            credential_id,
            hmac_salt,
            argon2_salt,
            nonce: nonce.into(),
            ciphertext,
        };
        let inner = fido2::pack(&envelope)?;

        write_master_file(mk_path, &inner)?;

        argon2_salt.fill(0);
        hmac_salt.fill(0);
        drop(wrapping_key);
        drop(argon2_output);
        Ok(())
    }

    /// Re-wrap an unlocked master key from v3 back into the v1
    /// passphrase-only layout. Used by `envseal security
    /// fido2-disable` once the user has authenticated to remove
    /// the security-key requirement.
    pub fn disable_fido2_keep_master(
        mk_path: &Path,
        master_key: &MasterKey,
        passphrase: &Zeroizing<String>,
    ) -> Result<(), Error> {
        validate_passphrase(passphrase)?;

        let mut argon2_salt = [0u8; ARGON2_SALT_LEN];
        OsRng.fill_bytes(&mut argon2_salt);

        let wrapping_key = derive_wrapping_key(passphrase, &argon2_salt)?;
        let cipher = Aes256Gcm::new(Key::<Aes256Gcm>::from_slice(wrapping_key.as_ref()));
        let nonce = Aes256Gcm::generate_nonce(&mut OsRng);
        let ciphertext = cipher
            .encrypt(&nonce, master_key.as_bytes().as_ref())
            .map_err(|e| Error::CryptoFailure(format!("v3 disable: re-wrap failed: {e}")))?;

        let mut inner = Vec::with_capacity(ARGON2_SALT_LEN + NONCE_LEN + ciphertext.len());
        inner.extend_from_slice(&argon2_salt);
        inner.extend_from_slice(&nonce);
        inner.extend_from_slice(&ciphertext);

        write_master_file(mk_path, &inner)?;

        argon2_salt.fill(0);
        drop(wrapping_key);
        Ok(())
    }

    /// Inspect a master.key file and report whether it is v3
    /// (FIDO2-enrolled) and, if so, the credential id.
    pub fn fido2_status_at(mk_path: &Path) -> Result<Fido2Status, Error> {
        if !mk_path.exists() {
            return Ok(Fido2Status::NoVault);
        }
        let raw = super::read_master_key_capped(mk_path)?;
        let inner = read_inner_envelope_at(&raw, None)?;
        if !fido2::is_v3(&inner) {
            return Ok(Fido2Status::NotEnrolled);
        }
        let env = fido2::parse(&inner)?;
        Ok(Fido2Status::Enrolled {
            credential_id: env.credential_id,
        })
    }

    /// Return value of [`fido2_status_at`].
    #[derive(Debug, Clone)]
    pub enum Fido2Status {
        /// `master.key` does not exist on disk.
        NoVault,
        /// `master.key` exists but is a v1/v2 envelope.
        NotEnrolled,
        /// `master.key` is a v3 envelope.
        Enrolled {
            /// Opaque credential id stored in the envelope.
            credential_id: Vec<u8>,
        },
    }

    /// Hex-encoded SHA-256 of a credential id. Stable identifier for
    /// audit logs and doctor reports without leaking the raw id.
    #[must_use]
    pub fn credential_id_hash(credential_id: &[u8]) -> String {
        use sha2::Digest;
        use std::fmt::Write as _;
        let digest = sha2::Sha256::digest(credential_id);
        let mut out = String::with_capacity(digest.len() * 2);
        for b in digest {
            let _ = write!(out, "{b:02x}");
        }
        out
    }
}

#[cfg(test)]
mod hardware_seal_tests {
    use super::*;
    use tempfile::tempdir;

    /// Build a synthetic passphrase-wrapped inner blob of the right
    /// minimum size for `read_inner_envelope` plumbing tests.
    /// Contents don't matter — these tests verify the v2 envelope
    /// framing, not the AES-GCM unseal.
    fn synthetic_inner_blob() -> Vec<u8> {
        // 16 (salt) + 12 (nonce) + 48 (ciphertext+tag for 32-byte plain)
        vec![0u8; 16 + 12 + 48]
    }

    #[test]
    fn legacy_v1_blob_accepted_as_migration() {
        // Pre-v2 master.key files (raw inner blob without the ES2\0
        // header) are now accepted as legacy v1 and returned as-is.
        let v1_blob = synthetic_inner_blob();
        let inner = read_inner_envelope(&v1_blob)
            .expect("plausible v1 blob should be accepted for migration");
        assert_eq!(inner, v1_blob);
    }

    #[test]
    fn too_short_blob_rejected() {
        // Blobs shorter than salt+nonce (28 bytes) are rejected even
        // under the v1 migration path.
        let tiny = vec![0u8; 10];
        let err = read_inner_envelope(&tiny).unwrap_err();
        let msg = err.to_string();
        assert!(
            msg.contains("too short") || msg.contains("corrupted"),
            "expected short-file error, got: {msg}"
        );
    }

    #[test]
    fn v2_envelope_with_active_backend_unseals() {
        // Round-trip: build a v2 envelope using the active keystore,
        // then read it back. On Windows this exercises real DPAPI.
        let dir = tempdir().unwrap();
        let mk = dir.path().join("master.key");
        let inner = synthetic_inner_blob();
        write_master_file(&mk, &inner).unwrap();

        let raw = std::fs::read(&mk).unwrap();
        // Must start with the v2 magic.
        assert_eq!(&raw[..4], hardware::V2_MAGIC.as_slice());

        let recovered_inner = read_inner_envelope(&raw).unwrap();
        assert_eq!(recovered_inner, inner);
    }

    #[test]
    fn v2_envelope_with_mismatched_backend_id_is_rejected() {
        // Construct a v2 envelope claiming a backend that isn't this
        // platform's active one. On Windows the active backend is
        // DPAPI, so we mark the envelope as TPM2 — read should fail
        // with a clear error rather than silently feeding garbage to
        // DPAPI.
        let active = active_backend();
        let mismatch = match active {
            Backend::Dpapi => Backend::Tpm2,
            Backend::SecureEnclave | Backend::Tpm2 | Backend::None => Backend::Dpapi,
        };
        if mismatch == active {
            return; // No way to construct a mismatch on this platform — skip.
        }
        let envelope = hardware::pack_v2(mismatch, &synthetic_inner_blob());
        let err = read_inner_envelope(&envelope).unwrap_err();
        match err {
            Error::DeviceMismatch {
                sealed_by,
                active: active_str,
            } => {
                assert_eq!(sealed_by, mismatch.name());
                assert_eq!(active_str, active.name());
            }
            other => panic!("expected DeviceMismatch, got {other:?}"),
        }
    }

    #[test]
    fn v2_envelope_with_none_backend_passes_through() {
        // A v2 envelope explicitly tagged backend=None contains the
        // inner blob unwrapped — should be returned as-is even if
        // the active platform has hardware available.
        let inner = synthetic_inner_blob();
        let envelope = hardware::pack_v2(Backend::None, &inner);
        let recovered = read_inner_envelope(&envelope).unwrap();
        assert_eq!(recovered, inner);
    }

    #[test]
    fn write_master_file_is_atomic_no_tmp_leaks() {
        // After a successful rotation, the only file in the directory
        // should be `master.key` itself — no `master.key.tmp.*` leftover.
        let dir = tempdir().unwrap();
        let mk = dir.path().join("master.key");
        write_master_file(&mk, &synthetic_inner_blob()).unwrap();

        let entries: Vec<_> = std::fs::read_dir(dir.path())
            .unwrap()
            .filter_map(Result::ok)
            .map(|e| e.file_name().to_string_lossy().into_owned())
            .collect();
        assert!(entries.contains(&"master.key".to_string()));
        for name in &entries {
            assert!(
                !name.contains(".tmp."),
                "found leftover tmp file after rotation: {name}"
            );
        }
    }

    #[test]
    fn write_master_file_overwrites_previous_atomically() {
        // Two successive writes leave the second envelope on disk
        // and don't leave any partial state from the first.
        let dir = tempdir().unwrap();
        let mk = dir.path().join("master.key");

        let first = synthetic_inner_blob();
        let mut second = synthetic_inner_blob();
        second[1] = 0xAA; // distinguish from first
        second[2] = 0xBB;

        write_master_file(&mk, &first).unwrap();
        write_master_file(&mk, &second).unwrap();

        let raw_now = std::fs::read(&mk).unwrap();
        let recovered = read_inner_envelope(&raw_now).unwrap();
        assert_eq!(recovered, second);
    }

    #[test]
    fn write_master_file_fails_clean_when_parent_unwritable() {
        // Targeting a path under a non-existent parent that we make
        // read-only forces a write failure. The error must propagate
        // and no garbage tmp file may be left in unrelated locations.
        let dir = tempdir().unwrap();
        let nested = dir.path().join("does/not/exist/master.key");
        // This succeeds because write_master_file creates parent dirs.
        // To force a real failure on Windows where create_dir_all
        // generally works, we instead point at a path whose parent
        // is itself a regular file.
        let blocker = dir.path().join("blocker");
        std::fs::write(&blocker, b"x").unwrap();
        let bad = blocker.join("master.key");
        let _ = nested; // unused on this path

        let result = write_master_file(&bad, &synthetic_inner_blob());
        assert!(
            result.is_err(),
            "writing under a regular-file parent must fail"
        );
    }

    #[test]
    fn atomic_tmp_path_is_unique_per_invocation() {
        let mk = std::path::PathBuf::from("/some/dir/master.key");
        let a = atomic_tmp_path(&mk);
        let b = atomic_tmp_path(&mk);
        assert_ne!(a, b, "two back-to-back calls must differ");
        assert!(a.to_string_lossy().contains("master.key.tmp."));
        // Must contain the atomic counter segment.
        let a_name = a.file_name().unwrap().to_string_lossy();
        assert!(
            a_name.matches('.').count() >= 5,
            "tmp name should have counter/thread segments: {a_name}"
        );
    }

    #[test]
    fn atomic_tmp_path_counter_increments() {
        let mk = std::path::PathBuf::from("/some/dir/master.key");
        let a = atomic_tmp_path(&mk);
        let b = atomic_tmp_path(&mk);
        let a_name = a.file_name().unwrap().to_string_lossy();
        let b_name = b.file_name().unwrap().to_string_lossy();
        // Extract the counter (4th dot-separated field after stem.tmp.pid.nanos)
        let a_counter: u64 = a_name.rsplit('.').nth(1).unwrap().parse().unwrap();
        let b_counter: u64 = b_name.rsplit('.').nth(1).unwrap().parse().unwrap();
        assert!(
            b_counter > a_counter,
            "counter must increase: {a_counter} -> {b_counter}"
        );
    }

    #[test]
    fn write_then_read_corrupted_inner_still_fails_unseal_chain() {
        // Sanity: corrupting the v2 envelope's body makes unseal fail
        // (covered by DPAPI's own tests, but verified here at the
        // keychain layer too).
        let dir = tempdir().unwrap();
        let mk = dir.path().join("master.key");
        write_master_file(&mk, &synthetic_inner_blob()).unwrap();
        let mut raw = std::fs::read(&mk).unwrap();
        // Flip a bit deep inside the sealed body.
        let last = raw.len() - 1;
        raw[last] ^= 0x01;
        let result = read_inner_envelope(&raw);
        // On `Backend::None` corruption is invisible (passthrough);
        // on hardware backends the unseal must reject.
        if active_backend() != Backend::None {
            assert!(result.is_err(), "corrupted envelope must fail to unseal");
        }
    }
}

#[cfg(all(test, feature = "fido2"))]
mod fido2_e2e_tests {
    use super::fido2_unlock::{
        create_master_key_with_fido2, credential_id_hash, disable_fido2_keep_master,
        enroll_fido2_on_existing_master, fido2_status_at,
        open_master_key_with_passphrase_and_fido2, unlock_master_key_with_fido2, Fido2Status,
    };
    use super::*;
    use crate::error::Error;
    use crate::vault::fido2::tests::MockAuthenticator;
    use tempfile::tempdir;

    fn mk_passphrase() -> Zeroizing<String> {
        Zeroizing::new("correct-horse-battery-staple".to_string())
    }

    #[test]
    fn create_then_unlock_with_same_authenticator_succeeds() {
        let dir = tempdir().unwrap();
        let mk = master_key_path(dir.path());
        let mut auth = MockAuthenticator::new([0x42; 32]);

        let pass = mk_passphrase();
        let key1 =
            create_master_key_with_fido2(dir.path(), &mk, &pass, &mut auth).expect("create v3");
        let key1_bytes = *key1.as_bytes();

        let key2 = unlock_master_key_with_fido2(&mk, &pass, &mut auth).expect("unlock v3");
        assert_eq!(
            *key2.as_bytes(),
            key1_bytes,
            "round-trip through v3 envelope must preserve master key bytes"
        );
    }

    #[test]
    fn unlock_v3_without_authenticator_returns_fido2_required() {
        let dir = tempdir().unwrap();
        let mk = master_key_path(dir.path());
        let mut auth = MockAuthenticator::new([0x77; 32]);

        let pass = mk_passphrase();
        let _ = create_master_key_with_fido2(dir.path(), &mk, &pass, &mut auth).unwrap();

        // Try to unlock through the legacy passphrase-only path —
        // must surface Fido2Required, not silently fall through.
        let err = unlock_master_key_with(&mk, &pass).unwrap_err();
        assert!(
            matches!(err, Error::Fido2Required),
            "expected Fido2Required, got {err:?}"
        );
    }

    #[test]
    fn unlock_v3_with_wrong_authenticator_fails() {
        let dir = tempdir().unwrap();
        let mk = master_key_path(dir.path());
        let mut enroll = MockAuthenticator::new([0xAA; 32]);

        let pass = mk_passphrase();
        let _ = create_master_key_with_fido2(dir.path(), &mk, &pass, &mut enroll).unwrap();

        // A different authenticator (different device key) cannot
        // produce the right hmac-secret output. The credential id
        // it doesn't recognize → assertion fails. Even if we
        // construct a mock that recognizes the id, the per-credential
        // key would differ and the AES-GCM unwrap would fail. Both
        // failure modes are acceptable; assert that one of them
        // happens (i.e. unlock is not successful).
        let mut wrong = MockAuthenticator::new([0xBB; 32]);
        let result = unlock_master_key_with_fido2(&mk, &pass, &mut wrong);
        assert!(result.is_err(), "wrong authenticator must not unlock");
    }

    #[test]
    fn unlock_v3_with_wrong_passphrase_fails() {
        let dir = tempdir().unwrap();
        let mk = master_key_path(dir.path());
        let mut auth = MockAuthenticator::new([0xCC; 32]);

        let pass = mk_passphrase();
        let _ = create_master_key_with_fido2(dir.path(), &mk, &pass, &mut auth).unwrap();

        let bad_pass = Zeroizing::new("wrong-passphrase".to_string());
        let result = unlock_master_key_with_fido2(&mk, &bad_pass, &mut auth);
        match result {
            Err(Error::CryptoFailure(msg)) => assert!(
                msg.contains("decryption failed"),
                "expected decrypt error, got {msg}"
            ),
            other => panic!("expected CryptoFailure, got {other:?}"),
        }
    }

    #[test]
    fn open_with_fido2_creates_when_missing_and_unlocks_when_present() {
        let dir = tempdir().unwrap();
        let mut auth = MockAuthenticator::new([0xDE; 32]);
        let pass = mk_passphrase();

        // Missing → create.
        let key1 = open_master_key_with_passphrase_and_fido2(dir.path(), &pass, &mut auth).unwrap();
        let key1_bytes = *key1.as_bytes();

        // Present → unlock.
        let key2 = open_master_key_with_passphrase_and_fido2(dir.path(), &pass, &mut auth).unwrap();
        assert_eq!(*key2.as_bytes(), key1_bytes);
    }

    #[test]
    fn enroll_then_unlock_preserves_master_key_bytes() {
        // The whole point of `enroll_fido2_on_existing_master` is
        // that the master key bytes survive the re-wrap, so every
        // existing vaulted secret stays decryptable. Pin that
        // contract.
        let dir = tempdir().unwrap();
        let mk = master_key_path(dir.path());
        let pass = mk_passphrase();

        let key_v1 = create_master_key_with(dir.path(), &mk, &pass).unwrap();
        let bytes_v1 = *key_v1.as_bytes();
        drop(key_v1);

        // Enroll a mock authenticator on top.
        let mut auth = MockAuthenticator::new([0x10; 32]);
        let key_v1_again = open_master_key_with_passphrase(dir.path(), &pass).unwrap();
        enroll_fido2_on_existing_master(&mk, &key_v1_again, &pass, &mut auth).unwrap();
        drop(key_v1_again);

        // The vault is now v3.
        match fido2_status_at(&mk).unwrap() {
            Fido2Status::Enrolled { .. } => {}
            other => panic!("expected v3 after enroll, got {other:?}"),
        }

        // Unlock through the FIDO2 path — bytes must match.
        let key_v3 = unlock_master_key_with_fido2(&mk, &pass, &mut auth).unwrap();
        assert_eq!(
            *key_v3.as_bytes(),
            bytes_v1,
            "enrollment must not rotate the master key bytes"
        );
    }

    #[test]
    fn enroll_then_disable_round_trips_back_to_v1() {
        let dir = tempdir().unwrap();
        let mk = master_key_path(dir.path());
        let pass = mk_passphrase();

        let key_v1 = create_master_key_with(dir.path(), &mk, &pass).unwrap();
        let bytes_original = *key_v1.as_bytes();
        drop(key_v1);

        // Enroll.
        let mut auth = MockAuthenticator::new([0x20; 32]);
        let key_for_enroll = open_master_key_with_passphrase(dir.path(), &pass).unwrap();
        enroll_fido2_on_existing_master(&mk, &key_for_enroll, &pass, &mut auth).unwrap();
        drop(key_for_enroll);
        assert!(matches!(
            fido2_status_at(&mk).unwrap(),
            Fido2Status::Enrolled { .. }
        ));

        // Disable.
        let key_for_disable = unlock_master_key_with_fido2(&mk, &pass, &mut auth).unwrap();
        disable_fido2_keep_master(&mk, &key_for_disable, &pass).unwrap();
        drop(key_for_disable);
        assert!(matches!(
            fido2_status_at(&mk).unwrap(),
            Fido2Status::NotEnrolled
        ));

        // Standard unlock must work again, with the original bytes.
        let key_after = open_master_key_with_passphrase(dir.path(), &pass).unwrap();
        assert_eq!(*key_after.as_bytes(), bytes_original);
    }

    #[test]
    fn fido2_status_at_reports_no_vault_when_file_missing() {
        let dir = tempdir().unwrap();
        let mk = master_key_path(dir.path());
        match fido2_status_at(&mk).unwrap() {
            Fido2Status::NoVault => {}
            other => panic!("expected NoVault, got {other:?}"),
        }
    }

    #[test]
    fn fido2_status_at_reports_not_enrolled_for_v1_vault() {
        let dir = tempdir().unwrap();
        let mk = master_key_path(dir.path());
        let pass = mk_passphrase();
        let _ = create_master_key_with(dir.path(), &mk, &pass).unwrap();
        match fido2_status_at(&mk).unwrap() {
            Fido2Status::NotEnrolled => {}
            other => panic!("expected NotEnrolled, got {other:?}"),
        }
    }

    #[test]
    fn credential_id_hash_is_stable_64_hex_chars() {
        let id = b"opaque-credential-bytes-of-some-length-32+bytes";
        let h = credential_id_hash(id);
        assert_eq!(h.len(), 64);
        assert!(h.chars().all(|c| c.is_ascii_hexdigit()));

        // Same input → same hash.
        assert_eq!(h, credential_id_hash(id));

        // Different input → different hash.
        let different = credential_id_hash(b"different-credential");
        assert_ne!(h, different);
    }

    #[test]
    fn enroll_disable_repeats_with_fresh_credential_each_cycle() {
        // Enroll, disable, enroll again — the second enrollment
        // must succeed with a fresh credential id (not be silently
        // blocked by stale state).
        let dir = tempdir().unwrap();
        let mk = master_key_path(dir.path());
        let pass = mk_passphrase();
        let _ = create_master_key_with(dir.path(), &mk, &pass).unwrap();

        let mut auth1 = MockAuthenticator::new([0x33; 32]);
        let key = open_master_key_with_passphrase(dir.path(), &pass).unwrap();
        enroll_fido2_on_existing_master(&mk, &key, &pass, &mut auth1).unwrap();
        drop(key);
        let Fido2Status::Enrolled {
            credential_id: cred1,
        } = fido2_status_at(&mk).unwrap()
        else {
            panic!("not enrolled after first enroll");
        };

        let key = unlock_master_key_with_fido2(&mk, &pass, &mut auth1).unwrap();
        disable_fido2_keep_master(&mk, &key, &pass).unwrap();
        drop(key);

        // Fresh authenticator (different device key) for second enrollment.
        let mut auth2 = MockAuthenticator::new([0x44; 32]);
        let key = open_master_key_with_passphrase(dir.path(), &pass).unwrap();
        enroll_fido2_on_existing_master(&mk, &key, &pass, &mut auth2).unwrap();
        let Fido2Status::Enrolled {
            credential_id: cred2,
        } = fido2_status_at(&mk).unwrap()
        else {
            panic!("not enrolled after second enroll");
        };

        assert_ne!(
            cred1, cred2,
            "second enrollment with a different authenticator must yield a different credential id"
        );
    }

    #[test]
    fn unlock_v3_with_corrupted_envelope_fails_clean() {
        // Truncating the v3 envelope after enrollment must fail
        // with a clean parse error, not panic.
        let dir = tempdir().unwrap();
        let mk = master_key_path(dir.path());
        let pass = mk_passphrase();
        let mut auth = MockAuthenticator::new([0x55; 32]);
        let _ = create_master_key_with_fido2(dir.path(), &mk, &pass, &mut auth).unwrap();

        // Truncate the file to ~half its size.
        let raw = std::fs::read(&mk).unwrap();
        let truncated = &raw[..raw.len() / 2];
        std::fs::write(&mk, truncated).unwrap();

        let result = unlock_master_key_with_fido2(&mk, &pass, &mut auth);
        assert!(result.is_err(), "truncated v3 envelope must fail to unlock");
    }

    #[test]
    fn fido2_path_does_not_disturb_legacy_v1_vault() {
        // A v1 vault (created without FIDO2) must still unlock
        // through the FIDO2-aware entry point — the authenticator
        // is silently bypassed because the inner blob is not v3.
        // This is the LAW 2 backwards-compat guarantee: existing
        // users who upgrade to a FIDO2-capable client don't see a
        // disruption until they explicitly enroll a key.
        let dir = tempdir().unwrap();
        let mk = master_key_path(dir.path());
        let pass = mk_passphrase();
        let key1 = create_master_key_with(dir.path(), &mk, &pass).unwrap();
        let key1_bytes = *key1.as_bytes();
        drop(key1);

        let mut auth = MockAuthenticator::new([0xEF; 32]);
        let key2 =
            unlock_master_key_with_fido2(&mk, &pass, &mut auth).expect("v1 vault must still open");
        assert_eq!(*key2.as_bytes(), key1_bytes);
    }
}

#[cfg(test)]
mod master_key_tests {
    use super::*;

    #[test]
    fn different_keys_different_aes() {
        let key1 = MasterKey::from_test_bytes([0x01; 32]);
        let key2 = MasterKey::from_test_bytes([0x02; 32]);
        assert_ne!(
            key1.as_aes_key(),
            key2.as_aes_key(),
            "Fix: different bytes must produce different AES keys"
        );
    }

    #[test]
    fn master_key_as_aes_key_length() {
        let key = MasterKey::from_test_bytes([0x42; 32]);
        let aes_key = key.as_aes_key();
        assert_eq!(aes_key.len(), 32, "Fix: AES-256 key must be 32 bytes");
    }

    #[test]
    fn master_key_debug_redacts() {
        let key = MasterKey::from_test_bytes([0xAA; 32]);
        let debug = format!("{key:?}");
        assert!(
            debug.contains("REDACTED"),
            "Fix: Debug must not leak key bytes"
        );
        assert!(
            !debug.contains("170"),
            "Fix: raw byte values must not appear in debug"
        );
        assert!(
            !debug.contains("0xaa"),
            "Fix: hex bytes must not appear in debug"
        );
    }

    #[test]
    fn master_key_zeroizes_on_drop() {
        let key = MasterKey::from_test_bytes([0xFF; 32]);
        // Key is alive — bytes should be 0xFF
        assert_eq!(key.as_bytes()[0], 0xFF);
        assert_eq!(key.as_bytes()[31], 0xFF);
        // After drop, Zeroizing ensures zeroing — we can't observe this
        // from outside, but we verify the type implements Drop correctly
        // by ensuring drop doesn't panic
        drop(key);
    }

    #[test]
    fn test_key_deterministic() {
        let key1 = MasterKey::from_test_bytes([0x42; 32]);
        let key2 = MasterKey::from_test_bytes([0x42; 32]);
        assert_eq!(
            key1.as_bytes(),
            key2.as_bytes(),
            "Fix: same input bytes must produce same key"
        );
    }
}