black_bag/

lib.rs

use std::collections::HashSet;
use std::convert::TryInto;
use std::env;
use std::ffi::OsString;
use std::fmt;
use std::fs::{self, File, OpenOptions};
use std::io::{self, Read, Write};
use std::path::{Path, PathBuf};
use std::sync::{Mutex, MutexGuard, OnceLock};

use anyhow::{anyhow, bail, Context, Result};
use argon2::{Algorithm, Argon2, Params, Version};
use base32::Alphabet::Rfc4648;
use base64::engine::general_purpose::STANDARD as BASE64;
use base64::Engine as _;
use chacha20poly1305::aead::{Aead, KeyInit, Payload};
use chacha20poly1305::{Key, XChaCha20Poly1305, XNonce};
use chrono::serde::ts_seconds_option;
use chrono::{DateTime, Duration, Utc};
use ciborium::{de::from_reader, ser::into_writer};
use clap::{Args, Parser, Subcommand, ValueEnum};
use directories::BaseDirs;
use ed25519_dalek::Signer;
use ed25519_dalek::{
    Signature as Ed25519Signature, SigningKey as Ed25519SigningKey, Verifier,
    VerifyingKey as Ed25519VerifyingKey,
};
use fd_lock::{RwLock, RwLockReadGuard, RwLockWriteGuard};
use is_terminal::IsTerminal;
use kem::{Decapsulate, Encapsulate};
use ml_kem::{array::Array, Ciphertext, Encoded, EncodedSizeUser, KemCore, MlKem1024};
use rand::{rngs::OsRng, RngCore};
use rpassword::prompt_password;
use serde::{Deserialize, Serialize};
use serde_json::json;
use tempfile::NamedTempFile;
use totp_rs::{Algorithm as TotpAlgorithmLib, Secret as TotpSecret, TOTP};
use typenum::Unsigned;
use uuid::Uuid;
use vsss_rs::Gf256;
use zeroize::{Zeroize, ZeroizeOnDrop, Zeroizing};

#[cfg(all(unix, feature = "mlock"))]
mod memlock {
    use libc::{mlock, munlock};
    use std::io;

    #[inline]
    pub fn lock_region(ptr: *const u8, len: usize) -> io::Result<()> {
        if len == 0 {
            return Ok(());
        }
        let rc = unsafe { mlock(ptr as *const _, len) };
        if rc == 0 {
            Ok(())
        } else {
            Err(io::Error::last_os_error())
        }
    }

    #[inline]
    pub fn unlock_region(ptr: *const u8, len: usize) {
        if len == 0 {
            return;
        }
        let _ = unsafe { munlock(ptr as *const _, len) };
    }

    pub struct RegionGuard {
        ptr: *const u8,
        len: usize,
    }

    impl RegionGuard {
        pub fn new(ptr: *const u8, len: usize) -> Option<Self> {
            match lock_region(ptr, len) {
                Ok(()) => Some(Self { ptr, len }),
                Err(_) => None,
            }
        }
    }

    impl Drop for RegionGuard {
        fn drop(&mut self) {
            unlock_region(self.ptr, self.len);
        }
    }
}

#[cfg(unix)]
use std::mem::MaybeUninit;
#[cfg(unix)]
use std::os::unix::io::AsRawFd;

#[cfg(feature = "pq")]
use pqcrypto_mldsa::mldsa87::{
    self, DetachedSignature as MlDsaDetachedSignature, PublicKey as MlDsaPublicKey,
    SecretKey as MlDsaSecretKey,
};
#[cfg(feature = "pq")]
use pqcrypto_traits::sign::{DetachedSignature as _, PublicKey as _, SecretKey as _};

use subtle::ConstantTimeEq;

const VAULT_VERSION: u32 = 1;
const AAD_DEK: &[u8] = b"black-bag::sealed-dek";
const AAD_DK: &[u8] = b"black-bag::sealed-dk";
const AAD_PAYLOAD: &[u8] = b"black-bag::payload";
const DEFAULT_TIME_COST: u32 = 3;
const DEFAULT_LANES: u32 = 1;
const MIN_ARGON_MEM_KIB: u32 = 131_072;
const AUTH_GRACE_FAILURES: u32 = 5;
const AUTH_BACKOFF_BASE_SECS: i64 = 2;
const AUTH_MAX_BACKOFF_SECS: i64 = 300;
const INTEGRITY_KEY_CONTEXT: &str = "black-bag::integrity-key::v1";

#[cfg(feature = "pq")]
const SIG_CTX: &[u8] = b"black-bag::backup-integrity::ml-dsa87::v1";

pub fn run() -> Result<()> {
    let cli = Cli::parse();
    match cli.command {
        Command::Init(cmd) => init_vault(cmd),
        Command::Add(cmd) => add_record(cmd),
        Command::List(cmd) => list_records(cmd),
        Command::Get(cmd) => get_record(cmd),
        Command::Rotate(cmd) => rotate_vault(cmd),
        Command::Doctor(cmd) => doctor(cmd),
        Command::Recovery { command } => recovery(command),
        Command::Totp { command } => totp(command),
        Command::Backup { command } => backup(command),
        Command::Version => show_version(),
        Command::Selftest => self_test(),
    }
}

#[derive(Parser)]
#[command(name = "black-bag", version, about = "Ultra-secure zero-trace CLI vault", long_about = None)]
struct Cli {
    #[command(subcommand)]
    command: Command,
}

#[derive(Subcommand)]
enum Command {
    /// Initialize a new vault
    Init(InitCommand),
    /// Add a record to the vault
    Add(AddCommand),
    /// List records (masked summaries)
    List(ListCommand),
    /// Inspect a record by UUID
    Get(GetCommand),
    /// Rewrap the master key with fresh randomness
    Rotate(RotateCommand),
    /// Print health diagnostics
    Doctor(DoctorCommand),
    /// Manage Shamir recovery shares
    Recovery {
        #[command(subcommand)]
        command: RecoveryCommand,
    },
    /// Work with stored TOTP secrets
    Totp {
        #[command(subcommand)]
        command: TotpCommand,
    },
    /// Manage backup integrity sidecars and signatures
    Backup {
        #[command(subcommand)]
        command: BackupCommand,
    },
    /// Show build and feature information
    Version,
    /// Run embedded self-tests
    Selftest,
}

#[derive(Args)]
struct InitCommand {
    /// Argon2 memory cost in KiB (default: 262144 => 256 MiB)
    #[arg(long, default_value_t = 262_144)]
    mem_kib: u32,
}

#[derive(Args)]
struct ListCommand {
    /// Filter by record kind
    #[arg(long, value_enum)]
    kind: Option<RecordKind>,
    /// Filter by tag (case-insensitive substring match)
    #[arg(long)]
    tag: Option<String>,
    /// Full-text query over metadata fields
    #[arg(long)]
    query: Option<String>,
}

#[derive(Args)]
struct GetCommand {
    /// Record UUID to inspect
    id: Uuid,
    /// Reveal sensitive fields (requires TTY)
    #[arg(long)]
    reveal: bool,
}

#[derive(Args, Default)]
struct RotateCommand {
    /// Optionally override Argon2 memory cost in KiB during rotation
    #[arg(long)]
    mem_kib: Option<u32>,
}

#[derive(Args)]
struct DoctorCommand {
    /// Emit machine-readable JSON instead of human text
    #[arg(long)]
    json: bool,
}

#[derive(Subcommand)]
enum RecoveryCommand {
    /// Split a secret into Shamir shares
    Split(RecoverySplitCommand),
    /// Combine Shamir shares back into the original secret
    Combine(RecoveryCombineCommand),
}

#[derive(Args)]
struct RecoverySplitCommand {
    /// Threshold required to reconstruct the secret
    #[arg(long, default_value_t = 3)]
    threshold: u8,
    /// Total number of shares to produce
    #[arg(long, default_value_t = 5)]
    shares: u8,
}

#[derive(Args)]
struct RecoveryCombineCommand {
    /// Reconstruction threshold (usually matches value used during split)
    #[arg(long)]
    threshold: u8,
    /// Comma-separated list of shares (e.g., 1-<base64>,2-<base64>)
    #[arg(long)]
    shares: String,
}

#[derive(Subcommand)]
enum TotpCommand {
    /// Generate a TOTP code for the specified record
    Code(TotpCodeCommand),
}

#[derive(Args)]
struct TotpCodeCommand {
    /// Record UUID containing the TOTP secret
    id: Uuid,
    /// Unix timestamp (seconds) to use instead of now
    #[arg(long)]
    time: Option<i64>,
}

#[derive(Subcommand)]
enum BackupCommand {
    /// Verify integrity (and optional signature) for a vault backup
    Verify(BackupVerifyCommand),
    /// Sign the integrity tag with an Ed25519 or ML-DSA-87 key
    Sign(BackupSignCommand),
    /// Generate an ML-DSA-87 keypair (requires --features pq)
    #[cfg(feature = "pq")]
    Keygen(BackupKeygenCommand),
}

#[derive(Args)]
struct BackupVerifyCommand {
    /// Path to the vault ciphertext (e.g., vault.cbor)
    #[arg(long)]
    path: PathBuf,
    /// Optional public key file (Ed25519 or ML-DSA-87)
    #[arg(long)]
    pub_key: Option<PathBuf>,
}

#[derive(Args)]
struct BackupSignCommand {
    /// Path to the vault ciphertext (e.g., vault.cbor)
    #[arg(long)]
    path: PathBuf,
    /// Secret key file (Ed25519 or ML-DSA-87)
    #[arg(long)]
    key: PathBuf,
    /// Emit derived public key (base64) to this path
    #[arg(long)]
    pub_out: Option<PathBuf>,
}

#[cfg(feature = "pq")]
#[derive(Args)]
struct BackupKeygenCommand {
    /// Output path for the ML-DSA-87 public key (base64)
    #[arg(long)]
    pub_out: PathBuf,
    /// Output path for the ML-DSA-87 secret key (base64)
    #[arg(long)]
    sk_out: PathBuf,
}

#[derive(Args)]
struct AddCommand {
    #[command(subcommand)]
    record: AddRecord,
}

#[derive(Subcommand)]
enum AddRecord {
    /// Add a login/password record
    Login(AddLogin),
    /// Add a contact record
    Contact(AddContact),
    /// Add an identity document record
    Id(AddIdentity),
    /// Add a secure note
    Note(AddNote),
    /// Add a bank account record
    Bank(AddBank),
    /// Add a Wi-Fi profile record
    Wifi(AddWifi),
    /// Add an API credential record
    Api(AddApi),
    /// Add a cryptocurrency wallet record
    Wallet(AddWallet),
    /// Add a TOTP secret
    Totp(AddTotp),
    /// Add an SSH key record
    Ssh(AddSsh),
    /// Add a PGP key record
    Pgp(AddPgp),
    /// Add a recovery kit record
    Recovery(AddRecovery),
}

#[derive(Args)]
struct CommonRecordArgs {
    /// Optional title for the record
    #[arg(long)]
    title: Option<String>,
    /// Comma-separated list of tags
    #[arg(long, value_delimiter = ',')]
    tags: Vec<String>,
    /// Optional free-form notes (stored alongside metadata)
    #[arg(long)]
    notes: Option<String>,
}

#[derive(Args)]
struct AddLogin {
    #[command(flatten)]
    common: CommonRecordArgs,
    #[arg(long)]
    username: Option<String>,
    #[arg(long)]
    url: Option<String>,
}

#[derive(Args)]
struct AddContact {
    #[command(flatten)]
    common: CommonRecordArgs,
    #[arg(long, required = true)]
    full_name: String,
    #[arg(long, value_delimiter = ',')]
    emails: Vec<String>,
    #[arg(long, value_delimiter = ',')]
    phones: Vec<String>,
}

#[derive(Args)]
struct AddIdentity {
    #[command(flatten)]
    common: CommonRecordArgs,
    #[arg(long)]
    id_type: Option<String>,
    #[arg(long)]
    name_on_doc: Option<String>,
    #[arg(long)]
    number: Option<String>,
    #[arg(long)]
    issuing_country: Option<String>,
    #[arg(long)]
    expiry: Option<String>,
}

#[derive(Args)]
struct AddNote {
    #[command(flatten)]
    common: CommonRecordArgs,
}

#[derive(Args)]
struct AddBank {
    #[command(flatten)]
    common: CommonRecordArgs,
    #[arg(long)]
    institution: Option<String>,
    #[arg(long)]
    account_name: Option<String>,
    #[arg(long)]
    routing_number: Option<String>,
}

#[derive(Args)]
struct AddWifi {
    #[command(flatten)]
    common: CommonRecordArgs,
    #[arg(long)]
    ssid: Option<String>,
    #[arg(long)]
    security: Option<String>,
    #[arg(long)]
    location: Option<String>,
}

#[derive(Args)]
struct AddApi {
    #[command(flatten)]
    common: CommonRecordArgs,
    #[arg(long)]
    service: Option<String>,
    #[arg(long)]
    environment: Option<String>,
    #[arg(long)]
    access_key: Option<String>,
    #[arg(long, value_delimiter = ',')]
    scopes: Vec<String>,
}

#[derive(Args)]
struct AddWallet {
    #[command(flatten)]
    common: CommonRecordArgs,
    #[arg(long)]
    asset: Option<String>,
    #[arg(long)]
    address: Option<String>,
    #[arg(long)]
    network: Option<String>,
}

#[derive(Args)]
struct AddTotp {
    #[command(flatten)]
    common: CommonRecordArgs,
    /// Optional issuer string (display only)
    #[arg(long)]
    issuer: Option<String>,
    /// Optional account/name label (display only)
    #[arg(long)]
    account: Option<String>,
    /// Base32-encoded secret; omit to be prompted securely
    #[arg(long)]
    secret: Option<String>,
    /// Number of digits (6-8)
    #[arg(long, default_value_t = 6)]
    digits: u8,
    /// Seconds per step
    #[arg(long, default_value_t = 30)]
    step: u64,
    /// Allowed skew (number of steps on each side)
    #[arg(long, default_value_t = 1)]
    skew: u8,
    /// Hash algorithm
    #[arg(long, value_enum, default_value_t = TotpAlgorithm::Sha1)]
    algorithm: TotpAlgorithm,
}

#[derive(Args)]
struct AddSsh {
    #[command(flatten)]
    common: CommonRecordArgs,
    #[arg(long)]
    label: Option<String>,
    #[arg(long)]
    comment: Option<String>,
}

#[derive(Args)]
struct AddPgp {
    #[command(flatten)]
    common: CommonRecordArgs,
    #[arg(long)]
    label: Option<String>,
    #[arg(long)]
    fingerprint: Option<String>,
}

#[derive(Args)]
struct AddRecovery {
    #[command(flatten)]
    common: CommonRecordArgs,
    #[arg(long)]
    description: Option<String>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, ValueEnum, Hash)]
#[serde(rename_all = "snake_case")]
#[clap(rename_all = "snake_case")]
enum RecordKind {
    Login,
    Contact,
    Id,
    Note,
    Bank,
    Wifi,
    Api,
    Wallet,
    Totp,
    Ssh,
    Pgp,
    Recovery,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, ValueEnum)]
#[serde(rename_all = "lowercase")]
enum TotpAlgorithm {
    Sha1,
    Sha256,
    Sha512,
}

impl TotpAlgorithm {
    fn to_lib(self) -> TotpAlgorithmLib {
        match self {
            TotpAlgorithm::Sha1 => TotpAlgorithmLib::SHA1,
            TotpAlgorithm::Sha256 => TotpAlgorithmLib::SHA256,
            TotpAlgorithm::Sha512 => TotpAlgorithmLib::SHA512,
        }
    }
}

impl fmt::Display for TotpAlgorithm {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            TotpAlgorithm::Sha1 => f.write_str("sha1"),
            TotpAlgorithm::Sha256 => f.write_str("sha256"),
            TotpAlgorithm::Sha512 => f.write_str("sha512"),
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
struct Record {
    id: Uuid,
    created_at: DateTime<Utc>,
    updated_at: DateTime<Utc>,
    title: Option<String>,
    tags: Vec<String>,
    metadata_notes: Option<String>,
    data: RecordData,
}

impl Record {
    fn new(
        data: RecordData,
        title: Option<String>,
        tags: Vec<String>,
        notes: Option<String>,
    ) -> Self {
        let now = Utc::now();
        Self {
            id: Uuid::new_v4(),
            created_at: now,
            updated_at: now,
            title,
            tags,
            metadata_notes: notes,
            data,
        }
    }

    fn kind(&self) -> RecordKind {
        self.data.kind()
    }

    fn matches_tag(&self, tag: &str) -> bool {
        let tag_lower = tag.to_ascii_lowercase();
        self.tags
            .iter()
            .any(|t| t.to_ascii_lowercase().contains(&tag_lower))
    }

    fn matches_query(&self, needle: &str) -> bool {
        let haystack = [
            self.title.as_deref().unwrap_or_default(),
            self.metadata_notes.as_deref().unwrap_or_default(),
            &self.data.summary_text(),
        ]
        .join("\n")
        .to_ascii_lowercase();
        haystack.contains(&needle.to_ascii_lowercase())
    }
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(tag = "kind", rename_all = "snake_case")]
enum RecordData {
    Login {
        username: Option<String>,
        url: Option<String>,
        password: Sensitive,
    },
    Contact {
        full_name: String,
        emails: Vec<String>,
        phones: Vec<String>,
    },
    Id {
        id_type: Option<String>,
        name_on_doc: Option<String>,
        number: Option<String>,
        issuing_country: Option<String>,
        expiry: Option<String>,
        secret: Option<Sensitive>,
    },
    Note {
        body: Sensitive,
    },
    Bank {
        institution: Option<String>,
        account_name: Option<String>,
        routing_number: Option<String>,
        account_number: Sensitive,
    },
    Wifi {
        ssid: Option<String>,
        security: Option<String>,
        location: Option<String>,
        passphrase: Sensitive,
    },
    Api {
        service: Option<String>,
        environment: Option<String>,
        access_key: Option<String>,
        secret_key: Sensitive,
        scopes: Vec<String>,
    },
    Wallet {
        asset: Option<String>,
        address: Option<String>,
        network: Option<String>,
        secret_key: Sensitive,
    },
    Totp {
        issuer: Option<String>,
        account: Option<String>,
        secret: Sensitive,
        digits: u8,
        step: u64,
        skew: u8,
        algorithm: TotpAlgorithm,
    },
    Ssh {
        label: Option<String>,
        private_key: Sensitive,
        comment: Option<String>,
    },
    Pgp {
        label: Option<String>,
        fingerprint: Option<String>,
        armored_private_key: Sensitive,
    },
    Recovery {
        description: Option<String>,
        payload: Sensitive,
    },
}

impl RecordData {
    fn kind(&self) -> RecordKind {
        match self {
            RecordData::Login { .. } => RecordKind::Login,
            RecordData::Contact { .. } => RecordKind::Contact,
            RecordData::Id { .. } => RecordKind::Id,
            RecordData::Note { .. } => RecordKind::Note,
            RecordData::Bank { .. } => RecordKind::Bank,
            RecordData::Wifi { .. } => RecordKind::Wifi,
            RecordData::Api { .. } => RecordKind::Api,
            RecordData::Wallet { .. } => RecordKind::Wallet,
            RecordData::Totp { .. } => RecordKind::Totp,
            RecordData::Ssh { .. } => RecordKind::Ssh,
            RecordData::Pgp { .. } => RecordKind::Pgp,
            RecordData::Recovery { .. } => RecordKind::Recovery,
        }
    }

    fn summary_text(&self) -> String {
        match self {
            RecordData::Login { username, url, .. } => format!(
                "user={} url={}",
                username.as_deref().unwrap_or("-"),
                url.as_deref().unwrap_or("-")
            ),
            RecordData::Contact {
                full_name,
                emails,
                phones,
            } => format!(
                "{} | emails={} | phones={}",
                full_name,
                if emails.is_empty() {
                    "-".to_string()
                } else {
                    emails.join(",")
                },
                if phones.is_empty() {
                    "-".to_string()
                } else {
                    phones.join(",")
                }
            ),
            RecordData::Id {
                id_type,
                number,
                expiry,
                ..
            } => format!(
                "type={} number={} expiry={}",
                id_type.as_deref().unwrap_or("-"),
                number.as_deref().unwrap_or("-"),
                expiry.as_deref().unwrap_or("-")
            ),
            RecordData::Note { .. } => "secure note".to_string(),
            RecordData::Bank {
                institution,
                account_name,
                routing_number,
                ..
            } => format!(
                "institution={} account={} routing={}",
                institution.as_deref().unwrap_or("-"),
                account_name.as_deref().unwrap_or("-"),
                routing_number.as_deref().unwrap_or("-")
            ),
            RecordData::Wifi {
                ssid,
                security,
                location,
                ..
            } => format!(
                "ssid={} security={} location={}",
                ssid.as_deref().unwrap_or("-"),
                security.as_deref().unwrap_or("-"),
                location.as_deref().unwrap_or("-")
            ),
            RecordData::Api {
                service,
                environment,
                scopes,
                ..
            } => format!(
                "service={} env={} scopes={}",
                service.as_deref().unwrap_or("-"),
                environment.as_deref().unwrap_or("-"),
                if scopes.is_empty() {
                    "-".to_string()
                } else {
                    scopes.join(",")
                }
            ),
            RecordData::Wallet {
                asset,
                address,
                network,
                ..
            } => format!(
                "asset={} address={} network={}",
                asset.as_deref().unwrap_or("-"),
                address.as_deref().unwrap_or("-"),
                network.as_deref().unwrap_or("-")
            ),
            RecordData::Totp {
                issuer,
                account,
                digits,
                step,
                ..
            } => format!(
                "issuer={} account={} digits={} step={}",
                issuer.as_deref().unwrap_or("-"),
                account.as_deref().unwrap_or("-"),
                digits,
                step
            ),
            RecordData::Ssh { label, comment, .. } => format!(
                "label={} comment={}",
                label.as_deref().unwrap_or("-"),
                comment.as_deref().unwrap_or("-")
            ),
            RecordData::Pgp {
                label, fingerprint, ..
            } => format!(
                "label={} fingerprint={}",
                label.as_deref().unwrap_or("-"),
                fingerprint.as_deref().unwrap_or("-")
            ),
            RecordData::Recovery { description, .. } => {
                format!("description={}", description.as_deref().unwrap_or("-"))
            }
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
struct Sensitive {
    #[serde(with = "serde_bytes")]
    data: Vec<u8>,
}

impl Sensitive {
    fn new_from_utf8(value: &[u8]) -> Self {
        let v = value.to_vec();
        #[cfg(all(unix, feature = "mlock"))]
        {
            // Best-effort lock of the sensitive buffer for its lifetime.
            let _ = memlock::lock_region(v.as_ptr(), v.len());
        }
        Self { data: v }
    }

    fn from_string(value: &str) -> Self {
        Self::new_from_utf8(value.as_bytes())
    }

    fn as_slice(&self) -> &[u8] {
        &self.data
    }

    fn expose_utf8(&self) -> Result<Zeroizing<String>> {
        Ok(Zeroizing::new(String::from_utf8(self.data.clone())?))
    }
}

impl Drop for Sensitive {
    fn drop(&mut self) {
        self.data.zeroize();
        #[cfg(all(unix, feature = "mlock"))]
        {
            memlock::unlock_region(self.data.as_ptr(), self.data.len());
        }
    }
}

impl ZeroizeOnDrop for Sensitive {}

#[derive(Serialize, Deserialize, Clone, Default)]
#[serde(default)]
struct AuthLimiter {
    failures: u32,
    #[serde(with = "ts_seconds_option")]
    lock_until: Option<DateTime<Utc>>,
}

impl AuthLimiter {
    fn enforce(&self) -> Result<()> {
        if let Some(until) = self.lock_until {
            let now = Utc::now();
            if until > now {
                let remaining = (until - now).num_seconds().max(1);
                bail!(
                    "vault temporarily locked; wait {} seconds before retrying",
                    remaining
                );
            }
        }
        Ok(())
    }

    fn register_failure(&mut self) -> bool {
        let previous_failures = self.failures;
        let previous_lock = self.lock_until;

        if let Some(until) = self.lock_until {
            if Utc::now() >= until {
                self.lock_until = None;
            }
        }

        self.failures = self.failures.saturating_add(1);

        if self.failures > AUTH_GRACE_FAILURES {
            let exponent = (self.failures - AUTH_GRACE_FAILURES).min(16);
            let scale = 1_i64 << exponent.saturating_sub(1);
            let delay = (AUTH_BACKOFF_BASE_SECS * scale).min(AUTH_MAX_BACKOFF_SECS);
            self.lock_until = Some(Utc::now() + Duration::seconds(delay));
        } else {
            self.lock_until = None;
        }

        previous_failures != self.failures || previous_lock != self.lock_until
    }

    fn register_success(&mut self) -> bool {
        let changed = self.failures != 0 || self.lock_until.is_some();
        self.failures = 0;
        self.lock_until = None;
        changed
    }
}

#[derive(Serialize, Deserialize, Clone)]
struct VaultFile {
    version: u32,
    header: VaultHeader,
    payload: AeadBlob,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum VaultAccess {
    ReadOnly,
    ReadWrite,
}

impl VaultAccess {
    fn requires_exclusive(self) -> bool {
        matches!(self, VaultAccess::ReadWrite)
    }
}

enum VaultLockGuard<'a> {
    Shared(RwLockReadGuard<'a, File>),
    Exclusive(RwLockWriteGuard<'a, File>),
}

#[derive(Serialize, Deserialize, Clone)]
struct VaultHeader {
    created_at: DateTime<Utc>,
    updated_at: DateTime<Utc>,
    argon: ArgonState,
    kem_public: Vec<u8>,
    kem_ciphertext: Vec<u8>,
    sealed_decapsulation: AeadBlob,
    sealed_dek: AeadBlob,
    #[serde(default)]
    auth: AuthLimiter,
    #[serde(default)]
    passphrase_last_rotated: Option<DateTime<Utc>>,
}

#[derive(Serialize, Deserialize, Clone)]
struct ArgonState {
    mem_cost_kib: u32,
    time_cost: u32,
    lanes: u32,
    salt: [u8; 32],
}

#[derive(Serialize, Deserialize, Clone)]
struct AeadBlob {
    nonce: [u8; 24],
    ciphertext: Vec<u8>,
}

#[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq)]
struct VaultPayload {
    records: Vec<Record>,
    record_counter: u64,
}

struct Vault {
    path: PathBuf,
    file: VaultFile,
    payload: VaultPayload,
    dek: Box<Zeroizing<[u8; 32]>>,
}

fn read_file_bytes(path: &Path, label: &str) -> Result<Zeroizing<Vec<u8>>> {
    let mut buf = Zeroizing::new(Vec::new());
    let mut file =
        File::open(path).map_err(|e| resource_io_error(e, &format!("failed to open {}", label)))?;
    file.read_to_end(&mut buf)
        .map_err(|e| resource_io_error(e, &format!("failed to read {}", label)))?;
    Ok(buf)
}

fn read_vault_file(path: &Path) -> Result<VaultFile> {
    let journal = journal_path(path);
    let journal_exists = journal.exists();
    let vault_exists = path.exists();
    if !journal_exists && !vault_exists {
        bail!("vault not initialized at {}", path.display());
    }

    if journal_exists {
        let buf = read_file_bytes(&journal, &format!("journal {}", journal.display()))?;
        let vault: VaultFile =
            from_reader(buf.as_slice()).context("failed to parse journaled vault")?;
        if vault.version != VAULT_VERSION {
            bail!("unsupported vault version {}", vault.version);
        }
        write_atomic(path, buf.as_slice()).context("failed to finalize journal into vault")?;
        if let Err(err) = fs::remove_file(&journal) {
            if err.kind() != io::ErrorKind::NotFound {
                return Err(resource_io_error(err, "failed to remove vault journal"));
            }
        }
        return Ok(vault);
    }

    let buf = read_file_bytes(path, &format!("vault {}", path.display()))?;
    let vault_file: VaultFile = from_reader(buf.as_slice()).context("failed to parse vault")?;
    if vault_file.version != VAULT_VERSION {
        bail!("unsupported vault version {}", vault_file.version);
    }
    Ok(vault_file)
}

impl Vault {
    fn init(path: &Path, passphrase: &Zeroizing<String>, mem_kib: u32) -> Result<()> {
        if path.exists() {
            bail!("vault already exists at {}", path.display());
        }

        if mem_kib < MIN_ARGON_MEM_KIB {
            bail!(
                "mem-kib must be at least {} ({} MiB)",
                MIN_ARGON_MEM_KIB,
                MIN_ARGON_MEM_KIB / 1024
            );
        }

        let mut salt = [0u8; 32];
        OsRng.fill_bytes(&mut salt);

        let argon = ArgonState {
            mem_cost_kib: mem_kib,
            time_cost: DEFAULT_TIME_COST,
            lanes: DEFAULT_LANES,
            salt,
        };

        let kek = derive_kek(passphrase, &argon)?;

        let (dk, ek) = <MlKem1024 as KemCore>::generate(&mut OsRng);
        let (kem_ct, shared_key_raw) = ek
            .encapsulate(&mut OsRng)
            .map_err(|e| anyhow!("ml-kem encapsulate failed: {e:?}"))?;
        let shared_key = Zeroizing::new(shared_key_raw.as_slice().to_vec());

        let mut dek_bytes = [0u8; 32];
        OsRng.fill_bytes(&mut dek_bytes);
        let dek = Box::new(Zeroizing::new(dek_bytes));
        #[cfg(all(unix, feature = "mlock"))]
        {
            let slice: &[u8] = &**dek;
            let _ = memlock::lock_region(slice.as_ptr(), slice.len());
        }

        let sealed_dek = encrypt_blob(shared_key.as_slice(), &**dek, AAD_DEK)?;

        let dk_bytes = dk.as_bytes();
        let sealed_decapsulation = encrypt_blob(kek.as_slice(), dk_bytes.as_slice(), AAD_DK)?;

        let payload = VaultPayload {
            records: Vec::new(),
            record_counter: 0,
        };
        let payload_blob = encrypt_payload(dek.as_ref().as_ref(), &payload)?;

        let created = Utc::now();
        let header = VaultHeader {
            created_at: created,
            updated_at: created,
            argon,
            kem_public: ek.as_bytes().to_vec(),
            kem_ciphertext: kem_ct.to_vec(),
            sealed_decapsulation,
            sealed_dek,
            auth: AuthLimiter::default(),
            passphrase_last_rotated: Some(created),
        };

        let file = VaultFile {
            version: VAULT_VERSION,
            header,
            payload: payload_blob,
        };

        write_vault(path, &file)
    }

    #[cfg_attr(not(test), allow(dead_code))]
    fn load(path: &Path, passphrase: &Zeroizing<String>) -> Result<Self> {
        let vault_file = read_vault_file(path)?;
        Self::from_parts(path, passphrase, vault_file).map_err(|(_, err)| err)
    }

    fn from_parts(
        path: &Path,
        passphrase: &Zeroizing<String>,
        mut vault_file: VaultFile,
    ) -> std::result::Result<Self, (Box<VaultFile>, anyhow::Error)> {
        if vault_file.header.passphrase_last_rotated.is_none() {
            vault_file.header.passphrase_last_rotated = Some(vault_file.header.created_at);
        }

        let mut vault_file_slot = Some(vault_file);
        let result = (|| -> Result<Self> {
            let vault_file_ref = vault_file_slot
                .as_ref()
                .expect("vault file must be available until success");

            let kek = derive_kek(passphrase, &vault_file_ref.header.argon)?;
            let dk_bytes = Zeroizing::new(decrypt_blob(
                kek.as_slice(),
                &vault_file_ref.header.sealed_decapsulation,
                AAD_DK,
            )?);
            type DecapKey = <MlKem1024 as KemCore>::DecapsulationKey;
            let dk_encoded = expect_encoded::<DecapKey>(dk_bytes.as_slice(), "decapsulation key")?;
            let dk = DecapKey::from_bytes(&dk_encoded);

            let kem_ct = expect_ciphertext(&vault_file_ref.header.kem_ciphertext)?;
            let shared_raw = dk
                .decapsulate(&kem_ct)
                .map_err(|_| anyhow!("ml-kem decapsulation failed"))?;
            let shared = Zeroizing::new(shared_raw.as_slice().to_vec());

            let dek_bytes = Zeroizing::new(decrypt_blob(
                shared.as_slice(),
                &vault_file_ref.header.sealed_dek,
                AAD_DEK,
            )?);
            if dek_bytes.len() != 32 {
                bail!("invalid dek length");
            }
            let mut dek_array = [0u8; 32];
            dek_array.copy_from_slice(dek_bytes.as_slice());
            let dek = Box::new(Zeroizing::new(dek_array));
            #[cfg(all(unix, feature = "mlock"))]
            {
                let slice: &[u8] = &**dek;
                let _ = memlock::lock_region(slice.as_ptr(), slice.len());
            }

            let payload: VaultPayload = decrypt_payload(&**dek, &vault_file_ref.payload)?;
            let vault_file = vault_file_slot
                .take()
                .expect("vault file consumed exactly once on success");

            Ok(Self {
                path: path.to_path_buf(),
                file: vault_file,
                payload,
                dek,
            })
        })();

        match result {
            Ok(vault) => Ok(vault),
            Err(err) => {
                let vault_file = vault_file_slot
                    .take()
                    .expect("vault file should remain available on error");
                Err((Box::new(vault_file), err))
            }
        }
    }

    fn save(&mut self, passphrase: &Zeroizing<String>) -> Result<()> {
        self.file.header.updated_at = Utc::now();

        let payload_blob = encrypt_payload(&**self.dek, &self.payload)?;
        self.file.payload = payload_blob;

        let kek = derive_kek(passphrase, &self.file.header.argon)?;

        let dk_bytes = Zeroizing::new(decrypt_blob(
            kek.as_slice(),
            &self.file.header.sealed_decapsulation,
            AAD_DK,
        )?);
        type DecapKey = <MlKem1024 as KemCore>::DecapsulationKey;
        let dk_encoded = expect_encoded::<DecapKey>(dk_bytes.as_slice(), "decapsulation key")?;
        let dk = DecapKey::from_bytes(&dk_encoded);
        let (kem_ct, shared_raw) = {
            type EncKey = <MlKem1024 as KemCore>::EncapsulationKey;
            let ek_encoded =
                expect_encoded::<EncKey>(&self.file.header.kem_public, "encapsulation key")?;
            let ek = EncKey::from_bytes(&ek_encoded);
            ek.encapsulate(&mut OsRng)
                .map_err(|e| anyhow!("ml-kem encapsulate failed: {e:?}"))?
        };
        let shared = Zeroizing::new(shared_raw.as_slice().to_vec());

        let sealed_dek = encrypt_blob(shared.as_slice(), &**self.dek, AAD_DEK)?;
        let sealed_decapsulation = encrypt_blob(kek.as_slice(), dk.as_bytes().as_slice(), AAD_DK)?;

        self.file.header.kem_ciphertext = kem_ct.to_vec();
        self.file.header.sealed_dek = sealed_dek;
        self.file.header.sealed_decapsulation = sealed_decapsulation;

        write_vault(&self.path, &self.file)
    }

    fn add_record(&mut self, record: Record) {
        self.payload.record_counter = self.payload.record_counter.saturating_add(1);
        self.payload.records.push(record);
    }

    fn list(
        &self,
        kind: Option<RecordKind>,
        tag: Option<&str>,
        query: Option<&str>,
    ) -> Vec<&Record> {
        self.payload
            .records
            .iter()
            .filter(|rec| kind.map(|k| rec.kind() == k).unwrap_or(true))
            .filter(|rec| tag.map(|t| rec.matches_tag(t)).unwrap_or(true))
            .filter(|rec| query.map(|q| rec.matches_query(q)).unwrap_or(true))
            .collect()
    }

    fn get_ref(&self, id: Uuid) -> Option<&Record> {
        self.payload.records.iter().find(|rec| rec.id == id)
    }

    fn rotate(&mut self, passphrase: &Zeroizing<String>, mem_kib: Option<u32>) -> Result<()> {
        if let Some(mem) = mem_kib {
            if mem < MIN_ARGON_MEM_KIB {
                bail!(
                    "mem-kib must be at least {} ({} MiB)",
                    MIN_ARGON_MEM_KIB,
                    MIN_ARGON_MEM_KIB / 1024
                );
            }
            self.file.header.argon.mem_cost_kib = mem;
            OsRng.fill_bytes(&mut self.file.header.argon.salt);
        }

        let (dk, ek) = <MlKem1024 as KemCore>::generate(&mut OsRng);
        let (kem_ct, shared_key_raw) = ek
            .encapsulate(&mut OsRng)
            .map_err(|e| anyhow!("ml-kem encapsulate failed: {e:?}"))?;
        let shared_key = Zeroizing::new(shared_key_raw.as_slice().to_vec());

        let kek = derive_kek(passphrase, &self.file.header.argon)?;
        let sealed_dek = encrypt_blob(shared_key.as_slice(), &**self.dek, AAD_DEK)?;
        let sealed_decapsulation = encrypt_blob(kek.as_slice(), dk.as_bytes().as_slice(), AAD_DK)?;

        self.file.header.kem_public = ek.as_bytes().to_vec();
        self.file.header.kem_ciphertext = kem_ct.to_vec();
        self.file.header.sealed_dek = sealed_dek;
        self.file.header.sealed_decapsulation = sealed_decapsulation;
        self.file.header.passphrase_last_rotated = Some(Utc::now());

        Ok(())
    }

    fn stats(&self) -> VaultStats {
        let rotated_at = self
            .file
            .header
            .passphrase_last_rotated
            .unwrap_or(self.file.header.created_at);
        VaultStats {
            created_at: self.file.header.created_at,
            updated_at: self.file.header.updated_at,
            record_count: self.payload.records.len(),
            argon_mem_kib: self.file.header.argon.mem_cost_kib,
            argon_time_cost: self.file.header.argon.time_cost,
            argon_lanes: self.file.header.argon.lanes,
            passphrase_last_rotated: rotated_at,
        }
    }
}

impl Drop for Vault {
    fn drop(&mut self) {
        self.dek.as_mut().zeroize();
        #[cfg(all(unix, feature = "mlock"))]
        {
            let slice: &[u8] = &**self.dek;
            memlock::unlock_region(slice.as_ptr(), slice.len());
        }
    }
}

struct VaultStats {
    created_at: DateTime<Utc>,
    updated_at: DateTime<Utc>,
    record_count: usize,
    argon_mem_kib: u32,
    argon_time_cost: u32,
    argon_lanes: u32,
    passphrase_last_rotated: DateTime<Utc>,
}

fn derive_kek(passphrase: &Zeroizing<String>, argon: &ArgonState) -> Result<Zeroizing<[u8; 32]>> {
    let params = Params::new(argon.mem_cost_kib, argon.time_cost, argon.lanes, Some(32))
        .map_err(|e| anyhow!("invalid Argon2 parameters: {e}"))?;
    let argon2 = Argon2::new(Algorithm::Argon2id, Version::V0x13, params);
    let mut output = Zeroizing::new([0u8; 32]);
    argon2
        .hash_password_into(passphrase.as_bytes(), &argon.salt, output.as_mut())
        .map_err(|e| {
            let msg = e.to_string();
            if msg.to_ascii_lowercase().contains("memory") {
                anyhow!(
                    "argon2 derivation failed: insufficient memory available for requested parameters ({msg})"
                )
            } else {
                anyhow!("argon2 derivation failed: {msg}")
            }
        })?;
    Ok(output)
}

fn expect_encoded<T>(data: &[u8], label: &str) -> Result<Encoded<T>>
where
    T: EncodedSizeUser,
{
    let expected = <T as EncodedSizeUser>::EncodedSize::USIZE;
    Array::try_from_iter(data.iter().copied()).map_err(|_| {
        anyhow!(
            "invalid {label} length: expected {expected}, got {}",
            data.len()
        )
    })
}

fn expect_ciphertext(data: &[u8]) -> Result<Ciphertext<MlKem1024>> {
    let expected = <MlKem1024 as KemCore>::CiphertextSize::USIZE;
    Array::try_from_iter(data.iter().copied()).map_err(|_| {
        anyhow!(
            "invalid ciphertext length: expected {expected}, got {}",
            data.len()
        )
    })
}

fn encrypt_blob(key: &[u8], plaintext: &[u8], aad: &[u8]) -> Result<AeadBlob> {
    let mut nonce = [0u8; 24];
    OsRng.fill_bytes(&mut nonce);
    let cipher = XChaCha20Poly1305::new(Key::from_slice(key));
    let ciphertext = cipher
        .encrypt(
            XNonce::from_slice(&nonce),
            Payload {
                msg: plaintext,
                aad,
            },
        )
        .map_err(|_| anyhow!("encryption failed"))?;
    Ok(AeadBlob { nonce, ciphertext })
}

fn decrypt_blob(key: &[u8], blob: &AeadBlob, aad: &[u8]) -> Result<Vec<u8>> {
    let cipher = XChaCha20Poly1305::new(Key::from_slice(key));
    let plaintext = cipher
        .decrypt(
            XNonce::from_slice(&blob.nonce),
            Payload {
                msg: &blob.ciphertext,
                aad,
            },
        )
        .map_err(|_| anyhow!("decryption failed"))?;
    Ok(plaintext)
}

fn encrypt_payload(dek: &[u8], payload: &VaultPayload) -> Result<AeadBlob> {
    let mut buf = Vec::new();
    into_writer(payload, &mut buf).context("failed to serialize payload")?;
    encrypt_blob(dek, &buf, AAD_PAYLOAD)
}

fn decrypt_payload(dek: &[u8], blob: &AeadBlob) -> Result<VaultPayload> {
    let plaintext = decrypt_blob(dek, blob, AAD_PAYLOAD)?;
    let payload: VaultPayload =
        from_reader(plaintext.as_slice()).context("failed to parse payload")?;
    Ok(payload)
}

fn vault_path() -> Result<PathBuf> {
    if let Ok(path) = env::var("BLACK_BAG_VAULT_PATH") {
        let pb = PathBuf::from(path);
        if let Some(parent) = pb.parent() {
            fs::create_dir_all(parent)
                .with_context(|| format!("failed to create {}", parent.display()))?;
        }
        return Ok(pb);
    }
    let base = BaseDirs::new().ok_or_else(|| anyhow!("unable to resolve base directory"))?;
    let dir = base.config_dir().join("black_bag");
    fs::create_dir_all(&dir).with_context(|| format!("failed to create {}", dir.display()))?;
    Ok(dir.join("vault.cbor"))
}

fn audit_log_path() -> Option<PathBuf> {
    env::var("BLACK_BAG_AUDIT_LOG").ok().map(PathBuf::from)
}

fn write_audit_event(event: &str, details: serde_json::Value) {
    let Some(path) = audit_log_path() else {
        return;
    };
    if let Some(parent) = path.parent() {
        if fs::create_dir_all(parent).is_err() {
            return;
        }
    }
    if let Ok(mut file) = OpenOptions::new().create(true).append(true).open(&path) {
        let payload = json!({
            "timestamp": Utc::now().to_rfc3339(),
            "event": event,
            "details": details,
        });
        if let Ok(line) = serde_json::to_string(&payload) {
            let _ = writeln!(file, "{}", line);
        }
    }
}

fn lock_file_for(path: &Path) -> Result<File> {
    let mut lock_name: OsString = path.as_os_str().to_os_string();
    lock_name.push(".lock");
    let lock_path = PathBuf::from(lock_name);
    if let Some(parent) = lock_path.parent() {
        fs::create_dir_all(parent)
            .with_context(|| format!("failed to create {}", parent.display()))?;
    }
    OpenOptions::new()
        .read(true)
        .write(true)
        .create(true)
        .truncate(true)
        .open(&lock_path)
        .with_context(|| format!("failed to open lock file {}", lock_path.display()))
}

fn process_write_lock() -> &'static Mutex<()> {
    static PROCESS_LOCK: OnceLock<Mutex<()>> = OnceLock::new();
    PROCESS_LOCK.get_or_init(|| Mutex::new(()))
}

fn with_vault<F, R>(access: VaultAccess, f: F) -> Result<R>
where
    F: FnOnce(&mut Vault, &Zeroizing<String>) -> Result<R>,
{
    let pass = prompt_passphrase("Master passphrase: ")?;
    with_vault_with_pass(access, pass, f)
}

fn with_vault_with_pass<F, R>(access: VaultAccess, pass: Zeroizing<String>, f: F) -> Result<R>
where
    F: FnOnce(&mut Vault, &Zeroizing<String>) -> Result<R>,
{
    let path = vault_path()?;

    #[cfg(all(unix, feature = "mlock"))]
    let _pass_guard = {
        // Lock the passphrase bytes for the duration of this operation.
        let bytes = pass.as_bytes();
        memlock::RegionGuard::new(bytes.as_ptr(), bytes.len())
    };

    let _process_guard: Option<MutexGuard<'static, ()>> = if access.requires_exclusive() {
        Some(process_write_lock().lock().unwrap())
    } else {
        None
    };

    let lock_file = lock_file_for(&path)?;
    let mut lock = RwLock::new(lock_file);
    let guard = if access.requires_exclusive() {
        VaultLockGuard::Exclusive(lock.write()?)
    } else {
        VaultLockGuard::Shared(lock.read()?)
    };
    let mut vault_file = read_vault_file(&path)?;
    if vault_file.header.passphrase_last_rotated.is_none() {
        vault_file.header.passphrase_last_rotated = Some(vault_file.header.created_at);
    }
    if let Err(err) = vault_file.header.auth.enforce() {
        write_audit_event(
            "auth-lockout",
            json!({
                "path": path.display().to_string(),
                "failures": vault_file.header.auth.failures,
                "lockUntil": vault_file
                    .header
                    .auth
                    .lock_until
                    .map(|ts| ts.to_rfc3339()),
            }),
        );
        match guard {
            VaultLockGuard::Shared(g) => drop(g),
            VaultLockGuard::Exclusive(g) => drop(g),
        }
        return Err(err);
    }

    match Vault::from_parts(&path, &pass, vault_file) {
        Ok(mut vault) => {
            let failure_snapshot = vault.file.header.auth.failures;
            let lock_snapshot = vault.file.header.auth.lock_until.map(|ts| ts.to_rfc3339());
            let auth_cleared = vault.file.header.auth.register_success();
            write_audit_event(
                "auth-success",
                json!({
                    "path": path.display().to_string(),
                    "failuresBefore": failure_snapshot,
                    "cleared": auth_cleared,
                    "previousLockUntil": lock_snapshot,
                }),
            );
            let result = f(&mut vault, &pass);
            let persist_result = if auth_cleared {
                write_vault(&path, &vault.file)
            } else {
                Ok(())
            };

            let outcome = match (result, persist_result) {
                (Ok(value), Ok(())) => Ok(value),
                (Ok(_), Err(err)) => Err(err.context("failed to persist unlock metadata")),
                (Err(err), Ok(())) => Err(err),
                (Err(err), Err(persist_err)) => {
                    let persist_str = persist_err.to_string();
                    Err(err.context(format!("failed to persist unlock metadata: {persist_str}")))
                }
            };

            drop(vault);
            match guard {
                VaultLockGuard::Shared(g) => drop(g),
                VaultLockGuard::Exclusive(g) => drop(g),
            }
            outcome
        }
        Err((vault_file_box, err)) => {
            let mut vault_file = *vault_file_box;
            let updated = vault_file.header.auth.register_failure();
            write_audit_event(
                "auth-failure",
                json!({
                    "path": path.display().to_string(),
                    "failures": vault_file.header.auth.failures,
                    "lockUntil": vault_file
                        .header
                        .auth
                        .lock_until
                        .map(|ts| ts.to_rfc3339()),
                    "error": err.to_string(),
                }),
            );
            let persist_result = if updated {
                write_vault(&path, &vault_file)
            } else {
                Ok(())
            };
            match guard {
                VaultLockGuard::Shared(g) => drop(g),
                VaultLockGuard::Exclusive(g) => drop(g),
            }
            match persist_result {
                Ok(()) => Err(err),
                Err(persist_err) => {
                    let persist_str = persist_err.to_string();
                    Err(err.context(format!("failed to persist unlock metadata: {persist_str}")))
                }
            }
        }
    }
}

fn prompt_passphrase(prompt: &str) -> Result<Zeroizing<String>> {
    let value = prompt_password(prompt)?;
    if value.trim().is_empty() {
        bail!("passphrase cannot be empty");
    }
    Ok(Zeroizing::new(value))
}

fn init_vault(cmd: InitCommand) -> Result<()> {
    let path = vault_path()?;
    let pass1 = prompt_passphrase("Master passphrase: ")?;
    let pass2 = prompt_passphrase("Confirm passphrase: ")?;
    if pass1.as_bytes().ct_eq(pass2.as_bytes()).unwrap_u8() != 1 {
        bail!("passphrases do not match");
    }
    #[cfg(all(unix, feature = "mlock"))]
    let _guards = {
        let pass1_bytes = pass1.as_bytes();
        let pass2_bytes = pass2.as_bytes();
        let g1 = memlock::RegionGuard::new(pass1_bytes.as_ptr(), pass1_bytes.len());
        let g2 = memlock::RegionGuard::new(pass2_bytes.as_ptr(), pass2_bytes.len());
        (g1, g2)
    };
    let lock_file = lock_file_for(&path)?;
    let mut lock = RwLock::new(lock_file);
    let _guard = lock.write()?;
    Vault::init(&path, &pass1, cmd.mem_kib)?;
    println!("Initialized vault at {}", path.display());
    Ok(())
}

fn add_record(cmd: AddCommand) -> Result<()> {
    let pass = prompt_passphrase("Master passphrase: ")?;
    let record = prepare_record(cmd.record)?;
    with_vault_with_pass(VaultAccess::ReadWrite, pass, move |vault, pass_ref| {
        vault.add_record(record);
        vault.save(pass_ref)?;
        println!("Record added");
        Ok(())
    })
}

fn prepare_record(record: AddRecord) -> Result<Record> {
    match record {
        AddRecord::Login(args) => {
            let CommonRecordArgs { title, tags, notes } = args.common;
            let password = prompt_hidden("Password: ")?;
            Ok(Record::new(
                RecordData::Login {
                    username: args.username,
                    url: args.url,
                    password,
                },
                title,
                tags,
                notes,
            ))
        }
        AddRecord::Contact(args) => {
            let CommonRecordArgs { title, tags, notes } = args.common;
            Ok(Record::new(
                RecordData::Contact {
                    full_name: args.full_name,
                    emails: args.emails,
                    phones: args.phones,
                },
                title,
                tags,
                notes,
            ))
        }
        AddRecord::Id(args) => {
            let CommonRecordArgs { title, tags, notes } = args.common;
            let secret = prompt_optional_hidden("Sensitive document secret (optional): ")?;
            Ok(Record::new(
                RecordData::Id {
                    id_type: args.id_type,
                    name_on_doc: args.name_on_doc,
                    number: args.number,
                    issuing_country: args.issuing_country,
                    expiry: args.expiry,
                    secret,
                },
                title,
                tags,
                notes,
            ))
        }
        AddRecord::Note(args) => {
            let CommonRecordArgs { title, tags, notes } = args.common;
            let body = prompt_multiline("Secure note body (Ctrl-D to finish): ")?;
            Ok(Record::new(RecordData::Note { body }, title, tags, notes))
        }
        AddRecord::Bank(args) => {
            let CommonRecordArgs { title, tags, notes } = args.common;
            let account_number = prompt_hidden("Account number / secret: ")?;
            Ok(Record::new(
                RecordData::Bank {
                    institution: args.institution,
                    account_name: args.account_name,
                    routing_number: args.routing_number,
                    account_number,
                },
                title,
                tags,
                notes,
            ))
        }
        AddRecord::Wifi(args) => {
            let CommonRecordArgs { title, tags, notes } = args.common;
            let passphrase = prompt_hidden("Wi-Fi passphrase: ")?;
            Ok(Record::new(
                RecordData::Wifi {
                    ssid: args.ssid,
                    security: args.security,
                    location: args.location,
                    passphrase,
                },
                title,
                tags,
                notes,
            ))
        }
        AddRecord::Api(args) => {
            let CommonRecordArgs { title, tags, notes } = args.common;
            let secret = prompt_hidden("Secret key: ")?;
            Ok(Record::new(
                RecordData::Api {
                    service: args.service,
                    environment: args.environment,
                    access_key: args.access_key,
                    secret_key: secret,
                    scopes: args.scopes,
                },
                title,
                tags,
                notes,
            ))
        }
        AddRecord::Wallet(args) => {
            let CommonRecordArgs { title, tags, notes } = args.common;
            let secret = prompt_hidden("Wallet secret material: ")?;
            Ok(Record::new(
                RecordData::Wallet {
                    asset: args.asset,
                    address: args.address,
                    network: args.network,
                    secret_key: secret,
                },
                title,
                tags,
                notes,
            ))
        }
        AddRecord::Totp(args) => {
            let AddTotp {
                common,
                issuer,
                account,
                secret,
                digits,
                step,
                skew,
                algorithm,
            } = args;
            if !(6..=8).contains(&digits) {
                bail!("digits must be between 6 and 8");
            }
            if step == 0 {
                bail!("step must be greater than zero");
            }
            let CommonRecordArgs { title, tags, notes } = common;
            let secret_bytes = match secret {
                Some(s) => parse_totp_secret(&s)?,
                None => {
                    let input = prompt_hidden("Base32 secret: ")?;
                    let value = input.expose_utf8()?;
                    parse_totp_secret(value.as_str())?
                }
            };
            let totp_secret = Sensitive { data: secret_bytes };
            build_totp_instance(
                &totp_secret,
                digits,
                step,
                skew,
                algorithm,
                &issuer,
                &account,
            )?;
            Ok(Record::new(
                RecordData::Totp {
                    issuer,
                    account,
                    secret: totp_secret,
                    digits,
                    step,
                    skew,
                    algorithm,
                },
                title,
                tags,
                notes,
            ))
        }
        AddRecord::Ssh(args) => {
            let CommonRecordArgs { title, tags, notes } = args.common;
            let private_key = prompt_multiline_hidden("Paste private key (Ctrl-D to finish): ")?;
            Ok(Record::new(
                RecordData::Ssh {
                    label: args.label,
                    private_key,
                    comment: args.comment,
                },
                title,
                tags,
                notes,
            ))
        }
        AddRecord::Pgp(args) => {
            let CommonRecordArgs { title, tags, notes } = args.common;
            let armored =
                prompt_multiline_hidden("Paste armored private key (Ctrl-D to finish): ")?;
            Ok(Record::new(
                RecordData::Pgp {
                    label: args.label,
                    fingerprint: args.fingerprint,
                    armored_private_key: armored,
                },
                title,
                tags,
                notes,
            ))
        }
        AddRecord::Recovery(args) => {
            let CommonRecordArgs { title, tags, notes } = args.common;
            let payload = prompt_multiline_hidden("Paste recovery payload (Ctrl-D to finish): ")?;
            Ok(Record::new(
                RecordData::Recovery {
                    description: args.description,
                    payload,
                },
                title,
                tags,
                notes,
            ))
        }
    }
}
fn list_records(cmd: ListCommand) -> Result<()> {
    let ListCommand { kind, tag, query } = cmd;
    with_vault(VaultAccess::ReadOnly, move |vault, _| {
        let list = vault.list(kind, tag.as_deref(), query.as_deref());
        if list.is_empty() {
            println!("No matching records");
            return Ok(());
        }
        for record in list {
            println!(
                "{} | {} | {} | tags=[{}] | {}",
                record.id,
                record.kind(),
                record.title.as_deref().unwrap_or("(untitled)"),
                if record.tags.is_empty() {
                    String::new()
                } else {
                    record.tags.join(",")
                },
                record.data.summary_text()
            );
        }
        Ok(())
    })
}

fn get_record(cmd: GetCommand) -> Result<()> {
    let GetCommand { id, reveal } = cmd;
    with_vault(VaultAccess::ReadOnly, move |vault, _| {
        if let Some(record) = vault.get_ref(id) {
            println!("id: {}", record.id);
            println!("kind: {}", record.kind());
            if let Some(title) = &record.title {
                println!("title: {}", title);
            }
            if !record.tags.is_empty() {
                println!("tags: {}", record.tags.join(","));
            }
            if let Some(notes) = &record.metadata_notes {
                println!("notes: {}", notes);
            }
            if reveal {
                if !io::stdout().is_terminal() {
                    bail!("--reveal requires an interactive TTY");
                }
                render_sensitive(record)?;
            } else {
                println!("(Sensitive fields hidden; re-run with --reveal on a TTY)");
            }
            Ok(())
        } else {
            bail!("record {} not found", id);
        }
    })
}

fn render_sensitive(record: &Record) -> Result<()> {
    match &record.data {
        RecordData::Login { password, .. } => {
            let password = password.expose_utf8()?;
            println!("password: {}", password.as_str());
        }
        RecordData::Contact { .. } => {}
        RecordData::Id { secret, .. } => {
            if let Some(secret) = secret {
                let secret = secret.expose_utf8()?;
                println!("secret: {}", secret.as_str());
            }
        }
        RecordData::Note { body } => {
            let body = body.expose_utf8()?;
            println!("note:\n{}", body.as_str());
        }
        RecordData::Bank { account_number, .. } => {
            let account_number = account_number.expose_utf8()?;
            println!("account_number: {}", account_number.as_str());
        }
        RecordData::Wifi { passphrase, .. } => {
            let passphrase = passphrase.expose_utf8()?;
            println!("passphrase: {}", passphrase.as_str());
        }
        RecordData::Api { secret_key, .. } => {
            let secret_key = secret_key.expose_utf8()?;
            println!("secret_key: {}", secret_key.as_str());
        }
        RecordData::Wallet { secret_key, .. } => {
            let secret_key = secret_key.expose_utf8()?;
            println!("secret_key: {}", secret_key.as_str());
        }
        RecordData::Totp {
            issuer,
            account,
            secret,
            digits,
            step,
            skew,
            algorithm,
        } => {
            let base32 = base32::encode(Rfc4648 { padding: false }, secret.as_slice());
            println!("secret_base32: {}", base32);
            if let Some(issuer) = issuer {
                println!("issuer: {}", issuer);
            }
            if let Some(account) = account {
                println!("account: {}", account);
            }
            println!("digits: {}", digits);
            println!("step: {}s", step);
            println!("skew: {}", skew);
            println!("algorithm: {}", algorithm);
            if let Ok(totp) =
                build_totp_instance(secret, *digits, *step, *skew, *algorithm, issuer, account)
            {
                if let Ok(code) = totp.generate_current() {
                    println!("current_code: {}", code);
                    if let Ok(ttl) = totp.ttl() {
                        println!("ttl: {}s", ttl);
                    }
                }
            }
        }
        RecordData::Ssh { private_key, .. } => {
            let private_key = private_key.expose_utf8()?;
            println!("private_key:\n{}", private_key.as_str());
        }
        RecordData::Pgp {
            armored_private_key,
            ..
        } => {
            let armored_private_key = armored_private_key.expose_utf8()?;
            println!("pgp_private_key:\n{}", armored_private_key.as_str());
        }
        RecordData::Recovery { payload, .. } => {
            let payload = payload.expose_utf8()?;
            println!("recovery_payload:\n{}", payload.as_str());
        }
    }
    Ok(())
}

fn parse_totp_secret(input: &str) -> Result<Vec<u8>> {
    let cleaned: String = input
        .chars()
        .filter(|c| !c.is_whitespace() && *c != '-')
        .collect();
    if cleaned.is_empty() {
        bail!("secret cannot be empty");
    }
    let encoded = cleaned.to_uppercase();
    TotpSecret::Encoded(encoded)
        .to_bytes()
        .map_err(|_| anyhow!("invalid base32-encoded secret"))
}

fn build_totp_instance(
    secret: &Sensitive,
    digits: u8,
    step: u64,
    skew: u8,
    algorithm: TotpAlgorithm,
    issuer: &Option<String>,
    account: &Option<String>,
) -> Result<TOTP> {
    let account_name = account.as_deref().unwrap_or_default().to_owned();
    TOTP::new(
        algorithm.to_lib(),
        usize::from(digits),
        skew,
        step,
        secret.as_slice().to_vec(),
        issuer.as_ref().map(|s| s.to_owned()),
        account_name,
    )
    .map_err(|err| anyhow!("failed to construct TOTP: {err}"))
}

fn split_secret(secret: &[u8], threshold: u8, share_count: u8) -> Result<Vec<Vec<u8>>> {
    if threshold == 0 {
        bail!("threshold must be at least 1");
    }
    if share_count == 0 {
        bail!("share count must be at least 1");
    }
    if share_count < threshold {
        bail!("share count must be greater than or equal to threshold");
    }
    if threshold == 1 {
        return Ok((1..=share_count)
            .map(|id| {
                let mut share = Vec::with_capacity(secret.len() + 1);
                share.push(id);
                share.extend_from_slice(secret);
                share
            })
            .collect());
    }
    let rng = OsRng;
    Gf256::split_array(threshold as usize, share_count as usize, secret, rng)
        .map_err(|err| anyhow!("failed to split secret shares: {err}"))
}

fn combine_secret(threshold: u8, shares: &[Vec<u8>]) -> Result<Vec<u8>> {
    if threshold == 0 {
        bail!("threshold must be at least 1");
    }
    if shares.len() < threshold as usize {
        bail!("not enough shares provided");
    }
    // Deduplicate by id and take the first `threshold` usable shares
    let mut seen = HashSet::new();
    let mut usable: Vec<Vec<u8>> = Vec::with_capacity(threshold as usize);
    for raw in shares {
        if raw.len() < 2 {
            bail!("share payload too short");
        }
        let id = raw[0];
        if id == 0 {
            bail!("share identifier must be non-zero");
        }
        if seen.insert(id) {
            usable.push(raw.to_vec());
            if usable.len() == threshold as usize {
                break;
            }
        }
    }
    if usable.len() < threshold as usize {
        bail!("not enough unique shares to reconstruct secret");
    }
    if threshold == 1 {
        return Ok(usable[0][1..].to_vec());
    }
    Gf256::combine_array(&usable).map_err(|err| anyhow!("failed to reconstruct secret: {err}"))
}

fn rotate_vault(cmd: RotateCommand) -> Result<()> {
    with_vault(VaultAccess::ReadWrite, move |vault, pass| {
        vault.rotate(pass, cmd.mem_kib)?;
        vault.save(pass)?;
        println!("Rotation complete");
        Ok(())
    })
}

fn doctor(cmd: DoctorCommand) -> Result<()> {
    with_vault(VaultAccess::ReadOnly, move |vault, _| {
        let stats = vault.stats();
        #[cfg(all(unix, feature = "mlock"))]
        let (mlock_enabled, mlock_ok, mlock_error) = {
            let probe = [0u8; 32];
            match memlock::lock_region(probe.as_ptr(), probe.len()) {
                Ok(()) => {
                    memlock::unlock_region(probe.as_ptr(), probe.len());
                    (true, true, None)
                }
                Err(e) => (true, false, Some(e.to_string())),
            }
        };
        #[cfg(not(all(unix, feature = "mlock")))]
        let (mlock_enabled, mlock_ok, mlock_error) = (false, false, None::<String>);
        if cmd.json {
            let payload = json!({
                "ready": true,
                "recordCount": stats.record_count,
                "argonMemKib": stats.argon_mem_kib,
                "argonTimeCost": stats.argon_time_cost,
                "argonLanes": stats.argon_lanes,
                "createdAt": stats.created_at.to_rfc3339(),
                "updatedAt": stats.updated_at.to_rfc3339(),
                "passphraseLastRotated": stats.passphrase_last_rotated.to_rfc3339(),
                "mlock": {
                    "enabled": mlock_enabled,
                    "ok": mlock_ok,
                    "error": mlock_error,
                },
            });
            println!("{}", payload);
        } else {
            println!("status: ready");
            println!("records: {}", stats.record_count);
            println!("created: {}", stats.created_at);
            println!("updated: {}", stats.updated_at);
            println!("passphrase last rotated: {}", stats.passphrase_last_rotated);
            println!(
                "argon2: mem={} KiB, time={}, lanes={}",
                stats.argon_mem_kib, stats.argon_time_cost, stats.argon_lanes
            );
            if mlock_enabled {
                if mlock_ok {
                    println!("mlock: enabled and working");
                } else if let Some(err) = mlock_error {
                    println!("mlock: enabled but failed ({}). Check OS limits.", err);
                }
            } else {
                println!("mlock: not supported in this build/OS");
            }
        }
        Ok(())
    })
}

fn recovery(cmd: RecoveryCommand) -> Result<()> {
    match cmd {
        RecoveryCommand::Split(args) => {
            if args.threshold == 0 || args.threshold > args.shares {
                bail!("threshold must be between 1 and number of shares");
            }
            let secret = prompt_hidden("Secret to split: ")?;
            let shares = split_secret(secret.as_slice(), args.threshold, args.shares)?;
            for share in shares {
                let (id, data) = share
                    .split_first()
                    .ok_or_else(|| anyhow!("invalid share structure"))?;
                let encoded = BASE64.encode(data);
                println!("{}-{}", id, encoded);
            }
            Ok(())
        }
        RecoveryCommand::Combine(args) => {
            if args.threshold == 0 {
                bail!("threshold must be at least 1");
            }
            let mut shares = Vec::new();
            for part in args
                .shares
                .split(',')
                .map(str::trim)
                .filter(|s| !s.is_empty())
            {
                let (id, data) = part
                    .split_once('-')
                    .ok_or_else(|| anyhow!("invalid share format: {part}"))?;
                let identifier: u8 = id.parse().context("invalid share identifier")?;
                if identifier == 0 {
                    bail!("share identifier must be between 1 and 255");
                }
                let mut decoded = BASE64.decode(data).context("invalid base64 in share")?;
                if decoded.is_empty() {
                    bail!("share payload cannot be empty");
                }
                let mut share = Vec::with_capacity(decoded.len() + 1);
                share.push(identifier);
                share.append(&mut decoded);
                shares.push(share);
            }
            if shares.len() < args.threshold as usize {
                bail!(
                    "insufficient shares provided (need at least {})",
                    args.threshold
                );
            }
            let secret = combine_secret(args.threshold, &shares)?;
            println!("{}", String::from_utf8_lossy(&secret));
            Ok(())
        }
    }
}

fn totp(cmd: TotpCommand) -> Result<()> {
    match cmd {
        TotpCommand::Code(args) => totp_code(args),
    }
}

fn totp_code(args: TotpCodeCommand) -> Result<()> {
    let TotpCodeCommand { id, time } = args;
    with_vault(VaultAccess::ReadOnly, move |vault, _| {
        let record = vault
            .get_ref(id)
            .ok_or_else(|| anyhow!("record {} not found", id))?;
        let (issuer, account, secret, digits, step, skew, algorithm) = match &record.data {
            RecordData::Totp {
                issuer,
                account,
                secret,
                digits,
                step,
                skew,
                algorithm,
            } => (issuer, account, secret, *digits, *step, *skew, *algorithm),
            _ => bail!("record {} is not a TOTP secret", id),
        };

        let totp = build_totp_instance(secret, digits, step, skew, algorithm, issuer, account)?;
        let code = if let Some(ts) = time {
            if ts < 0 {
                bail!("time must be non-negative");
            }
            totp.generate(ts as u64)
        } else {
            totp.generate_current()?
        };
        println!("code: {}", code);
        if time.is_none() {
            let ttl = totp.ttl()?;
            println!("ttl: {}s", ttl);
        }
        Ok(())
    })
}

fn backup(cmd: BackupCommand) -> Result<()> {
    match cmd {
        BackupCommand::Verify(args) => backup_verify(args),
        BackupCommand::Sign(args) => backup_sign(args),
        #[cfg(feature = "pq")]
        BackupCommand::Keygen(args) => backup_keygen(args),
    }
}

fn show_version() -> Result<()> {
    let version = env!("CARGO_PKG_VERSION");
    let profile = option_env!("PROFILE").unwrap_or("unknown");
    let target = option_env!("TARGET").unwrap_or("unknown");

    let mut features = Vec::new();
    if cfg!(feature = "mlock") {
        features.push("mlock");
    } else {
        features.push("no-mlock");
    }
    if cfg!(feature = "pq") {
        features.push("pq");
    } else {
        features.push("no-pq");
    }
    if cfg!(feature = "fuzzing") {
        features.push("fuzzing");
    }
    if cfg!(feature = "fhe") {
        features.push("fhe");
    }

    println!("black-bag {version}");
    println!("profile: {profile}");
    println!("target: {target}");
    println!("features: {}", features.join(", "));
    Ok(())
}

fn backup_verify(cmd: BackupVerifyCommand) -> Result<()> {
    let bytes = fs::read(&cmd.path)
        .with_context(|| format!("failed to read vault at {}", cmd.path.display()))?;
    let vault: VaultFile = from_reader(bytes.as_slice()).context("failed to parse vault")?;
    let expected = compute_public_integrity_tag(&bytes, &vault.header.kem_public);
    let actual = read_integrity_sidecar(&cmd.path)?;
    if actual.ct_eq(&expected).unwrap_u8() != 1 {
        bail!("integrity check failed: .int does not match vault payload");
    }

    if let Some(pub_key) = cmd.pub_key.as_deref() {
        let sig = read_integrity_signature_sidecar(&cmd.path)?;
        verify_integrity_signature(&expected, pub_key, &sig)?;
        println!("Integrity and signature verified");
    } else {
        println!("Integrity verified");
    }
    Ok(())
}

fn backup_sign(cmd: BackupSignCommand) -> Result<()> {
    let bytes = fs::read(&cmd.path)
        .with_context(|| format!("failed to read vault at {}", cmd.path.display()))?;
    let vault: VaultFile = from_reader(bytes.as_slice()).context("failed to parse vault")?;
    let tag = match read_integrity_sidecar(&cmd.path) {
        Ok(tag) => tag,
        Err(_) => {
            let computed = compute_public_integrity_tag(&bytes, &vault.header.kem_public);
            write_integrity_sidecar(&cmd.path, &computed)?;
            computed
        }
    };

    let key_bytes = read_key_bytes(&cmd.key)?;
    let pub_out = cmd.pub_out.as_deref();

    if try_sign_ed25519(&key_bytes, &tag, pub_out, &cmd.path)? {
        println!("Wrote Ed25519 signature sidecar");
        return Ok(());
    }

    #[cfg(feature = "pq")]
    {
        if try_sign_mldsa(&key_bytes, &tag, pub_out, &cmd.path)? {
            println!("Wrote ML-DSA-87 signature sidecar");
            return Ok(());
        }
    }

    bail!(
        "unsupported signing key size: expected 32/64 bytes (Ed25519) or ML-DSA-87 secret key length"
    )
}

#[cfg(feature = "pq")]
fn backup_keygen(cmd: BackupKeygenCommand) -> Result<()> {
    let (pk, sk) = mldsa87::keypair();
    fs::write(&cmd.pub_out, BASE64.encode(pk.as_bytes()))
        .with_context(|| format!("failed to write {}", cmd.pub_out.display()))?;
    let mut secret_blob = Vec::with_capacity(pk.as_bytes().len() + sk.as_bytes().len());
    secret_blob.extend_from_slice(pk.as_bytes());
    secret_blob.extend_from_slice(sk.as_bytes());
    fs::write(&cmd.sk_out, BASE64.encode(secret_blob))
        .with_context(|| format!("failed to write {}", cmd.sk_out.display()))?;
    println!("Generated ML-DSA-87 keypair");
    Ok(())
}

fn compute_public_integrity_tag(bytes: &[u8], kem_public: &[u8]) -> [u8; 32] {
    let key = blake3::derive_key(INTEGRITY_KEY_CONTEXT, kem_public);
    let tag = blake3::keyed_hash(&key, bytes);
    let mut out = [0u8; 32];
    out.copy_from_slice(tag.as_bytes());
    out
}

fn integrity_sidecar_path(path: &Path) -> PathBuf {
    let mut os = path.as_os_str().to_os_string();
    os.push(".int");
    PathBuf::from(os)
}

fn integrity_signature_sidecar_path(path: &Path) -> PathBuf {
    let mut os = path.as_os_str().to_os_string();
    os.push(".int.sig");
    PathBuf::from(os)
}

fn write_integrity_sidecar(path: &Path, tag: &[u8; 32]) -> Result<()> {
    let sidecar = integrity_sidecar_path(path);
    let mut file =
        File::create(&sidecar).with_context(|| format!("failed to write {}", sidecar.display()))?;
    writeln!(file, "{}", BASE64.encode(tag))
        .with_context(|| format!("failed to write {}", sidecar.display()))
}

fn read_integrity_sidecar(path: &Path) -> Result<[u8; 32]> {
    let sidecar = integrity_sidecar_path(path);
    let mut contents = String::new();
    File::open(&sidecar)
        .with_context(|| format!("integrity sidecar missing at {}", sidecar.display()))?
        .read_to_string(&mut contents)
        .with_context(|| format!("failed to read {}", sidecar.display()))?;
    let trimmed = contents.trim();
    if trimmed.is_empty() {
        bail!("integrity sidecar at {} is empty", sidecar.display());
    }
    let decoded = if let Ok(bytes) = BASE64.decode(trimmed) {
        bytes
    } else if trimmed.len() == 64 && trimmed.chars().all(|c| c.is_ascii_hexdigit()) {
        hex::decode(trimmed).context("invalid hex in integrity sidecar")?
    } else {
        bail!(
            "integrity sidecar at {} is not valid base64/hex",
            sidecar.display()
        );
    };
    if decoded.len() != 32 {
        bail!("integrity sidecar length mismatch (expected 32 bytes)");
    }
    let mut out = [0u8; 32];
    out.copy_from_slice(&decoded);
    Ok(out)
}

fn write_integrity_signature_sidecar(path: &Path, sig: &[u8]) -> Result<()> {
    let sidecar = integrity_signature_sidecar_path(path);
    let mut file =
        File::create(&sidecar).with_context(|| format!("failed to write {}", sidecar.display()))?;
    writeln!(file, "{}", BASE64.encode(sig))
        .with_context(|| format!("failed to write {}", sidecar.display()))
}

fn read_integrity_signature_sidecar(path: &Path) -> Result<Vec<u8>> {
    let sidecar = integrity_signature_sidecar_path(path);
    let mut contents = String::new();
    File::open(&sidecar)
        .with_context(|| format!("signature sidecar missing at {}", sidecar.display()))?
        .read_to_string(&mut contents)
        .with_context(|| format!("failed to read {}", sidecar.display()))?;
    let trimmed = contents.trim();
    if trimmed.is_empty() {
        bail!("signature sidecar at {} is empty", sidecar.display());
    }
    BASE64
        .decode(trimmed)
        .context("signature sidecar is not valid base64")
}

fn read_key_bytes(path: &Path) -> Result<Vec<u8>> {
    let raw = fs::read(path)
        .with_context(|| format!("failed to read key material from {}", path.display()))?;
    if let Ok(text) = std::str::from_utf8(&raw) {
        let trimmed = text.trim();
        if trimmed.is_empty() {
            bail!("key file {} is empty", path.display());
        }
        if let Ok(bytes) = BASE64.decode(trimmed) {
            return Ok(bytes);
        }
        if trimmed.len() % 2 == 0 && trimmed.chars().all(|c| c.is_ascii_hexdigit()) {
            return hex::decode(trimmed).context("invalid hex encoding in key file");
        }
    }
    Ok(raw)
}

fn verify_signature_with_key_bytes(tag: &[u8; 32], pk_bytes: &[u8], sig: &[u8]) -> Result<()> {
    if pk_bytes.len() == 32 {
        let vk = Ed25519VerifyingKey::from_bytes(
            pk_bytes
                .try_into()
                .map_err(|_| anyhow!("invalid Ed25519 public key length"))?,
        )
        .map_err(|e| anyhow!("invalid Ed25519 public key: {e}"))?;
        let sig_array: [u8; 64] = sig
            .try_into()
            .map_err(|_| anyhow!("invalid Ed25519 signature length"))?;
        let signature = Ed25519Signature::from_bytes(&sig_array);
        vk.verify(tag, &signature)
            .map_err(|_| anyhow!("Ed25519 signature verification failed"))?;
        return Ok(());
    }

    #[cfg(feature = "pq")]
    {
        if pk_bytes.len() == mldsa87::public_key_bytes() {
            let pk = MlDsaPublicKey::from_bytes(pk_bytes)
                .map_err(|_| anyhow!("invalid ML-DSA-87 public key bytes"))?;
            let ds = MlDsaDetachedSignature::from_bytes(sig)
                .map_err(|_| anyhow!("invalid ML-DSA-87 signature bytes"))?;
            mldsa87::verify_detached_signature_ctx(&ds, tag, SIG_CTX, &pk)
                .map_err(|_| anyhow!("ML-DSA-87 signature verification failed"))?;
            return Ok(());
        }
    }

    bail!("unsupported public key size for signature verification")
}

fn try_sign_ed25519(
    key_bytes: &[u8],
    tag: &[u8; 32],
    pub_out: Option<&Path>,
    vault_path: &Path,
) -> Result<bool> {
    let signing_key = match key_bytes.len() {
        32 => {
            let array: [u8; 32] = key_bytes
                .try_into()
                .map_err(|_| anyhow!("invalid Ed25519 secret key length"))?;
            Ed25519SigningKey::from_bytes(&array)
        }
        64 => {
            let array: [u8; 64] = key_bytes
                .try_into()
                .map_err(|_| anyhow!("invalid Ed25519 keypair length"))?;
            Ed25519SigningKey::from_keypair_bytes(&array)
                .map_err(|_| anyhow!("invalid Ed25519 keypair bytes"))?
        }
        _ => return Ok(false),
    };

    let signature: Ed25519Signature = signing_key.sign(tag);
    let sig_bytes = signature.to_bytes();
    write_integrity_signature_sidecar(vault_path, sig_bytes.as_ref())?;
    if let Some(out) = pub_out {
        let vk = signing_key.verifying_key();
        fs::write(out, BASE64.encode(vk.as_bytes()))
            .with_context(|| format!("failed to write {}", out.display()))?;
    }
    Ok(true)
}

#[cfg(feature = "pq")]
fn try_sign_mldsa(
    key_bytes: &[u8],
    tag: &[u8; 32],
    pub_out: Option<&Path>,
    vault_path: &Path,
) -> Result<bool> {
    let sk_len = mldsa87::secret_key_bytes();
    let pk_len = mldsa87::public_key_bytes();

    let (sk_material, pk_material) = if key_bytes.len() == sk_len {
        (key_bytes, None)
    } else if key_bytes.len() == sk_len + pk_len {
        (&key_bytes[pk_len..], Some(&key_bytes[..pk_len]))
    } else {
        return Ok(false);
    };

    let sk = MlDsaSecretKey::from_bytes(sk_material)
        .map_err(|_| anyhow!("invalid ML-DSA-87 secret key bytes"))?;
    let signature = mldsa87::detached_sign_ctx(tag, SIG_CTX, &sk);
    write_integrity_signature_sidecar(vault_path, signature.as_bytes())?;

    if let Some(out) = pub_out {
        let pk_slice = pk_material
            .ok_or_else(|| anyhow!("secret key does not embed an ML-DSA-87 public key"))?;
        fs::write(out, BASE64.encode(pk_slice))
            .with_context(|| format!("failed to write {}", out.display()))?;
    }
    Ok(true)
}

fn verify_integrity_signature(tag: &[u8; 32], pub_key_path: &Path, sig: &[u8]) -> Result<()> {
    let pk_bytes = read_key_bytes(pub_key_path)?;
    verify_signature_with_key_bytes(tag, &pk_bytes, sig)
}

fn self_test() -> Result<()> {
    let mut sample = [0u8; 32];
    OsRng.fill_bytes(&mut sample);
    let secret = Sensitive::new_from_utf8(&sample);
    let record = Record::new(
        RecordData::Note { body: secret },
        Some("Self-test".into()),
        vec!["selftest".into()],
        None,
    );
    let payload = VaultPayload {
        records: vec![record],
        record_counter: 1,
    };

    let mut dek = [0u8; 32];
    OsRng.fill_bytes(&mut dek);
    let blob = encrypt_payload(&dek, &payload)?;
    let recovered = decrypt_payload(&dek, &blob)?;
    anyhow::ensure!(recovered.records.len() == 1, "self-test failed");
    println!("Self-test passed");
    Ok(())
}

fn prompt_hidden(prompt: &str) -> Result<Sensitive> {
    let value = Zeroizing::new(prompt_password(prompt)?);
    Ok(Sensitive::from_string(value.as_str()))
}

fn prompt_optional_hidden(prompt: &str) -> Result<Option<Sensitive>> {
    let value = Zeroizing::new(prompt_password(prompt)?);
    if value.trim().is_empty() {
        Ok(None)
    } else {
        Ok(Some(Sensitive::from_string(value.as_str())))
    }
}

fn prompt_multiline(prompt: &str) -> Result<Sensitive> {
    eprintln!("{}", prompt);
    read_multiline(false)
}

fn prompt_multiline_hidden(prompt: &str) -> Result<Sensitive> {
    eprintln!("{}", prompt);
    read_multiline(true)
}

fn read_multiline(hidden: bool) -> Result<Sensitive> {
    let hide_output = hidden && io::stdin().is_terminal();
    #[cfg(unix)]
    let mut echo_guard: Option<EchoModeGuard> = None;
    if hide_output {
        #[cfg(unix)]
        {
            echo_guard = Some(EchoModeGuard::disable()?);
        }
        #[cfg(not(unix))]
        {
            bail!("hidden multiline prompts are not supported on this platform; pipe the input instead");
        }
    }

    let mut buffer = Zeroizing::new(Vec::new());
    io::stdin().read_to_end(&mut buffer)?;
    #[cfg(unix)]
    if hide_output {
        let _ = echo_guard.take();
        eprintln!();
    }
    while buffer.last().copied() == Some(b'\n') {
        buffer.pop();
    }
    Ok(Sensitive::new_from_utf8(&buffer))
}

#[cfg(unix)]
struct EchoModeGuard {
    fd: i32,
    original: libc::termios,
}

#[cfg(unix)]
impl EchoModeGuard {
    fn disable() -> Result<Self> {
        let stdin = io::stdin();
        let fd = stdin.as_raw_fd();
        let mut term = MaybeUninit::<libc::termios>::uninit();
        if unsafe { libc::tcgetattr(fd, term.as_mut_ptr()) } != 0 {
            Result::<(), io::Error>::Err(io::Error::last_os_error())
                .context("failed to read terminal attributes")?;
        }
        let mut current = unsafe { term.assume_init() };
        let original = current;
        current.c_lflag &= !libc::ECHO;
        if unsafe { libc::tcsetattr(fd, libc::TCSANOW, &current) } != 0 {
            Result::<(), io::Error>::Err(io::Error::last_os_error())
                .context("failed to disable terminal echo")?;
        }
        Ok(Self { fd, original })
    }
}

#[cfg(unix)]
impl Drop for EchoModeGuard {
    fn drop(&mut self) {
        let _ = unsafe { libc::tcsetattr(self.fd, libc::TCSANOW, &self.original) };
    }
}

#[cfg(feature = "fuzzing")]
pub fn fuzz_try_payload(bytes: &[u8]) {
    let _ = ciborium::de::from_reader::<VaultPayload, _>(bytes);
}

#[cfg(feature = "fuzzing")]
pub fn fuzz_verify_signature(bytes: &[u8]) {
    if bytes.len() < 34 {
        return;
    }
    let mut tag = [0u8; 32];
    tag.copy_from_slice(&bytes[..32]);
    let remainder = &bytes[32..];
    if remainder.len() < 2 {
        return;
    }
    let split = (remainder[0] as usize % (remainder.len() - 1)) + 1;
    let (pk_bytes, sig_bytes) = remainder.split_at(split);
    let _ = verify_signature_with_key_bytes(&tag, pk_bytes, sig_bytes);
}

fn resource_io_error(err: io::Error, context: &str) -> anyhow::Error {
    if let Some(code) = err.raw_os_error() {
        match code {
            24 => {
                return anyhow!(
                    "{}: file descriptor limit reached (Too many open files - EMFILE)",
                    context
                )
            }
            12 => {
                return anyhow!("{}: insufficient system memory (ENOMEM)", context);
            }
            _ => {}
        }
    }
    anyhow!("{}: {}", context, err)
}

fn journal_path(path: &Path) -> PathBuf {
    let mut os = path.as_os_str().to_os_string();
    os.push(".journal");
    PathBuf::from(os)
}

fn write_synced_file(path: &Path, buf: &[u8]) -> Result<()> {
    let mut file = File::create(path)
        .map_err(|e| resource_io_error(e, &format!("failed to create {}", path.display())))?;
    file.write_all(buf)
        .map_err(|e| resource_io_error(e, &format!("failed to write {}", path.display())))?;
    file.sync_all()
        .map_err(|e| resource_io_error(e, &format!("failed to sync {}", path.display())))?;
    Ok(())
}

fn write_atomic(path: &Path, buf: &[u8]) -> Result<()> {
    let parent = path.parent().ok_or_else(|| anyhow!("invalid vault path"))?;
    fs::create_dir_all(parent)
        .map_err(|e| resource_io_error(e, &format!("failed to create {}", parent.display())))?;
    let mut tmp = NamedTempFile::new_in(parent)
        .map_err(|e| resource_io_error(e, "failed to create temporary vault file"))?;
    tmp.as_file_mut()
        .write_all(buf)
        .map_err(|e| resource_io_error(e, "failed to write temporary vault file"))?;
    tmp.as_file_mut()
        .sync_all()
        .map_err(|e| resource_io_error(e, "failed to sync temporary vault file"))?;
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        tmp.as_file_mut()
            .set_permissions(fs::Permissions::from_mode(0o600))
            .map_err(|e| resource_io_error(e, "failed to set vault permissions"))?;
    }
    tmp.persist(path)
        .map_err(|e| resource_io_error(e.error, "failed to persist vault"))?;
    File::open(path)
        .and_then(|f| f.sync_all())
        .map_err(|e| resource_io_error(e, &format!("failed to sync {}", path.display())))?;
    Ok(())
}

fn write_vault(path: &Path, file: &VaultFile) -> Result<()> {
    let mut buf = Vec::new();
    into_writer(file, &mut buf).context("failed to serialize vault")?;
    let parent = path.parent().ok_or_else(|| anyhow!("invalid vault path"))?;
    fs::create_dir_all(parent)
        .map_err(|e| resource_io_error(e, &format!("failed to create {}", parent.display())))?;
    let journal = journal_path(path);
    write_synced_file(&journal, &buf)?;
    write_atomic(path, &buf)?;
    if let Err(err) = fs::remove_file(&journal) {
        if err.kind() != io::ErrorKind::NotFound {
            return Err(resource_io_error(err, "failed to remove vault journal"));
        }
    }
    Ok(())
}

impl fmt::Display for RecordKind {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let label = match self {
            RecordKind::Login => "login",
            RecordKind::Contact => "contact",
            RecordKind::Id => "id",
            RecordKind::Note => "note",
            RecordKind::Bank => "bank",
            RecordKind::Wifi => "wifi",
            RecordKind::Api => "api",
            RecordKind::Wallet => "wallet",
            RecordKind::Totp => "totp",
            RecordKind::Ssh => "ssh",
            RecordKind::Pgp => "pgp",
            RecordKind::Recovery => "recovery",
        };
        f.write_str(label)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use proptest::prelude::*;
    use proptest::proptest;
    use proptest::strategy::Strategy;
    use serial_test::serial;
    use std::env;
    use std::path::PathBuf;
    use tempfile::tempdir;

    fn prepare(passphrase: &str) -> Result<(tempfile::TempDir, PathBuf, Zeroizing<String>)> {
        let dir = tempdir()?;
        let vault_path = dir.path().join("vault.cbor");
        env::set_var("BLACK_BAG_VAULT_PATH", &vault_path);
        let pass = Zeroizing::new(passphrase.to_string());
        Ok((dir, vault_path, pass))
    }

    fn cleanup() {
        env::remove_var("BLACK_BAG_VAULT_PATH");
    }

    fn arb_ascii_string(max: usize) -> impl Strategy<Value = String> {
        proptest::collection::vec(proptest::char::range('a', 'z'), 0..=max)
            .prop_map(|chars| chars.into_iter().collect())
    }

    fn arb_note_record() -> impl Strategy<Value = Record> {
        (
            proptest::option::of(arb_ascii_string(12)),
            proptest::collection::vec(arb_ascii_string(8), 0..3),
            arb_ascii_string(48),
        )
            .prop_map(|(title, tags, body)| {
                Record::new(
                    RecordData::Note {
                        body: Sensitive::from_string(&body),
                    },
                    title,
                    tags,
                    None,
                )
            })
    }

    proptest! {
        #[test]
        fn encrypt_blob_roundtrip_prop(
            key_bytes in proptest::array::uniform32(any::<u8>()),
            data in proptest::collection::vec(any::<u8>(), 0..256),
            aad in proptest::collection::vec(any::<u8>(), 0..32),
        ) {
            let blob = encrypt_blob(&key_bytes, &data, &aad).unwrap();
            let decrypted = decrypt_blob(&key_bytes, &blob, &aad).unwrap();
            prop_assert_eq!(decrypted, data);
        }

        #[test]
        fn payload_roundtrip_prop(
            key_bytes in proptest::array::uniform32(any::<u8>()),
            records in proptest::collection::vec(arb_note_record(), 0..3),
        ) {
            let payload = VaultPayload {
                records: records.clone(),
                record_counter: records.len() as u64,
            };
            let blob = encrypt_payload(&key_bytes, &payload).unwrap();
            let decoded = decrypt_payload(&key_bytes, &blob).unwrap();
            prop_assert_eq!(decoded, payload);
        }
    }

    #[test]
    #[serial]
    fn vault_round_trip_note() -> Result<()> {
        let (_tmp, vault_path, pass) = prepare("correct horse battery staple")?;
        Vault::init(&vault_path, &pass, MIN_ARGON_MEM_KIB)?;

        let mut vault = Vault::load(&vault_path, &pass)?;
        let record = Record::new(
            RecordData::Note {
                body: Sensitive::from_string("mission ops"),
            },
            Some("Ops Note".into()),
            vec!["mission".into()],
            None,
        );
        let record_id = record.id;
        vault.add_record(record);
        vault.save(&pass)?;

        drop(vault);
        let vault = Vault::load(&vault_path, &pass)?;
        let notes = vault.list(Some(RecordKind::Note), None, None);
        assert_eq!(notes.len(), 1);
        assert_eq!(notes[0].id, record_id);
        assert_eq!(notes[0].title.as_deref(), Some("Ops Note"));
        assert!(notes[0].matches_tag("mission"));

        cleanup();
        Ok(())
    }

    #[test]
    #[serial]
    fn totp_round_trip() -> Result<()> {
        let (_tmp, vault_path, pass) = prepare("totp-pass")?;
        Vault::init(&vault_path, &pass, MIN_ARGON_MEM_KIB)?;

        let secret_bytes = parse_totp_secret("JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP")?;
        let mut vault = Vault::load(&vault_path, &pass)?;
        let record = Record::new(
            RecordData::Totp {
                issuer: Some("TestIssuer".into()),
                account: Some("test@example".into()),
                secret: Sensitive { data: secret_bytes },
                digits: 6,
                step: 30,
                skew: 1,
                algorithm: TotpAlgorithm::Sha1,
            },
            Some("TOTP".into()),
            vec![],
            None,
        );
        let record_id = record.id;
        vault.add_record(record);
        vault.save(&pass)?;

        drop(vault);
        let vault = Vault::load(&vault_path, &pass)?;
        let record = vault
            .get_ref(record_id)
            .ok_or_else(|| anyhow!("TOTP record missing"))?;
        let code = match &record.data {
            RecordData::Totp {
                issuer,
                account,
                secret,
                digits,
                step,
                skew,
                algorithm,
            } => build_totp_instance(secret, *digits, *step, *skew, *algorithm, issuer, account)?
                .generate(59),
            _ => bail!("expected totp record"),
        };
        let expected = TOTP::new(
            TotpAlgorithmLib::SHA1,
            6,
            1,
            30,
            parse_totp_secret("JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP")?,
            Some("TestIssuer".into()),
            "test@example".into(),
        )
        .unwrap()
        .generate(59);
        assert_eq!(code, expected);

        cleanup();
        Ok(())
    }

    #[test]
    #[serial]
    fn vault_rotation_changes_wrapped_keys() -> Result<()> {
        let (_tmp, vault_path, pass) = prepare("rotate-all-the-things")?;
        Vault::init(&vault_path, &pass, MIN_ARGON_MEM_KIB)?;

        let mut vault = Vault::load(&vault_path, &pass)?;
        let record = Record::new(
            RecordData::Api {
                service: Some("intel-api".into()),
                environment: Some("prod".into()),
                access_key: Some("AKIA-123".into()),
                secret_key: Sensitive::from_string("super-secret"),
                scopes: vec!["read".into(), "write".into()],
            },
            Some("API".into()),
            vec!["read".into()],
            None,
        );
        vault.add_record(record);
        let before = vault.file.header.sealed_dek.ciphertext.to_vec();
        vault.rotate(&pass, Some(MIN_ARGON_MEM_KIB))?;
        vault.save(&pass)?;
        let after = vault.file.header.sealed_dek.ciphertext.to_vec();
        assert_ne!(before, after);

        drop(vault);
        let vault = Vault::load(&vault_path, &pass)?;
        let apis = vault.list(Some(RecordKind::Api), Some("read"), None);
        assert_eq!(apis.len(), 1);
        assert!(apis[0].data.summary_text().contains("intel-api"));

        cleanup();
        Ok(())
    }

    #[test]
    fn recovery_split_combine_roundtrip() -> Result<()> {
        let secret = b"ultra-secret";
        let shares = split_secret(secret, 3, 5)?;
        let recovered = combine_secret(3, &shares)?;
        assert_eq!(recovered, secret);
        Ok(())
    }

    #[test]
    fn split_secret_requires_threshold_shares() -> Result<()> {
        let secret = b"deg-guard";
        let shares = split_secret(secret, 3, 5)?;
        for i in 0..shares.len() {
            for j in (i + 1)..shares.len() {
                let subset = vec![shares[i].to_vec(), shares[j].to_vec()];
                let recovered = combine_secret(2, &subset)?;
                assert_ne!(recovered.as_slice(), secret);
            }
        }
        Ok(())
    }

    #[test]
    #[serial]
    fn backup_sign_verify_ed25519() -> Result<()> {
        let (tmp, vault_path, pass) = prepare("backup-ed25519")?;
        Vault::init(&vault_path, &pass, MIN_ARGON_MEM_KIB)?;

        let sk_path = tmp.path().join("ed25519.sk");
        let mut sk_bytes = [0u8; 32];
        OsRng.fill_bytes(&mut sk_bytes);
        fs::write(&sk_path, BASE64.encode(sk_bytes))?;
        let pub_path = tmp.path().join("ed25519.pub");

        backup_sign(BackupSignCommand {
            path: vault_path.to_path_buf(),
            key: sk_path,
            pub_out: Some(pub_path.to_path_buf()),
        })?;

        backup_verify(BackupVerifyCommand {
            path: vault_path.to_path_buf(),
            pub_key: Some(pub_path),
        })?;

        cleanup();
        Ok(())
    }

    #[cfg(feature = "pq")]
    #[test]
    #[serial]
    fn backup_sign_verify_mldsa87() -> Result<()> {
        let (tmp, vault_path, pass) = prepare("backup-mldsa87")?;
        Vault::init(&vault_path, &pass, MIN_ARGON_MEM_KIB)?;

        let (pk, sk) = mldsa87::keypair();
        let sk_path = tmp.path().join("mldsa.sk");
        let pk_path = tmp.path().join("mldsa.pub");
        let mut secret_blob = Vec::with_capacity(pk.as_bytes().len() + sk.as_bytes().len());
        secret_blob.extend_from_slice(pk.as_bytes());
        secret_blob.extend_from_slice(sk.as_bytes());
        fs::write(&sk_path, BASE64.encode(&secret_blob))?;
        fs::write(&pk_path, BASE64.encode(pk.as_bytes()))?;

        backup_sign(BackupSignCommand {
            path: vault_path.to_path_buf(),
            key: sk_path,
            pub_out: Some(pk_path.to_path_buf()),
        })?;

        backup_verify(BackupVerifyCommand {
            path: vault_path.to_path_buf(),
            pub_key: Some(pk_path),
        })?;

        cleanup();
        Ok(())
    }
}