black_bagg/

lib.rs

use std::env;
use std::fmt;
use std::fs::{self, File, OpenOptions};
use std::io::{self, Read, Write};
use std::ops::{Deref, DerefMut};
use std::path::{Path, PathBuf};

use crate::error::{Error, Result};
use anyhow::{anyhow, Context};
use argon2::{Algorithm, Argon2, Params, Version};
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::{DateTime, Utc};
use ciborium::{de::from_reader, ser::into_writer};
use clap::{Args, Parser, Subcommand, ValueEnum};
use directories::BaseDirs;
use fd_lock::RwLock;
#[cfg(feature = "pq")]
use pqcrypto_kyber::kyber1024;
#[cfg(feature = "pq")]
use pqcrypto_traits::kem::{Ciphertext as _, PublicKey as _, SecretKey as _, SharedSecret as _};
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 uuid::Uuid;
use zeroize::{Zeroize, ZeroizeOnDrop, Zeroizing};
use zxcvbn::zxcvbn;

#[cfg(feature = "agent-keychain")]
mod agent;
mod config;
pub mod error;
mod memory;
mod output;
mod shamir;
#[cfg(feature = "tui")]
mod tui;

use config::{AppConfig, EmitMode};
use output::write_bytes_tty;
use output::{emit_totp_code, ensure_interactive_or_override, render_sensitive, write_line_tty};
use shamir::{combine_secret, split_secret};

const VAULT_VERSION: u32 = 2;
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 AAD_RDEK: &[u8] = b"black-bag::record-dek";
const AAD_SECRET: &[u8] = b"black-bag::record-secret";
const SECRET_MARKER: &[u8; 4] = b"BBE1";
const PAD_MAGIC: &[u8; 8] = b"BBPAD1\0\0";
const DEFAULT_TIME_COST: u32 = 10;
const DEFAULT_LANES: u32 = 4;
const MAX_FIELD_BYTES: usize = 8 * 1024; // 8 KiB
const MAX_NOTE_BYTES: usize = 256 * 1024; // 256 KiB
const MAX_VAULT_FILE_BYTES: u64 = 64 * 1024 * 1024; // 64 MiB
const MAX_PAYLOAD_PLAINTEXT_BYTES: usize = 32 * 1024 * 1024; // 32 MiB
const MAX_RECORDS: usize = 100_000;
const MAX_TAGS_PER_RECORD: usize = 64;
const MAX_TAG_LEN: usize = 128;
const MAX_TITLE_LEN: usize = 256;

pub fn run() -> Result<()> {
    let cli = Cli::parse();
    let app_config = AppConfig::from_sources(
        cli.unsafe_stdout,
        cli.require_mlock,
        cli.emit,
        cli.agent,
        cli.unsafe_clipboard,
        cli.duress,
    );
    apply_process_hardening();
    // Touch fields to avoid false dead_code warnings in some analyses
    let _ = app_config.unsafe_clipboard;
    let _ = app_config.duress;
    match cli.command {
        Command::Init(cmd) => init_vault(cmd, &app_config),
        Command::Add(cmd) => add_record(cmd, &app_config),
        Command::List(cmd) => list_records(cmd, &app_config),
        Command::Get(cmd) => get_record(cmd, &app_config),
        Command::Rotate(cmd) => rotate_vault(cmd, &app_config),
        Command::Doctor(cmd) => doctor(cmd, &app_config),
        Command::Export { command } => export(command, &app_config),
        Command::Recovery { command } => recovery(command, &app_config),
        Command::Totp { command } => totp(command, &app_config),
        Command::Backup { command } => backup(command, &app_config),
        Command::Passwd(cmd) => passwd(cmd, &app_config),
        #[cfg(feature = "tui")]
        Command::Tui => Ok(tui::app::run(&app_config)?),
        Command::Migrate => migrate_vault(&app_config),
        Command::Selftest => self_test(),
    }
}

fn apply_process_hardening() {
    #[cfg(unix)]
    unsafe {
        // Disable core dumps
        let lim = libc::rlimit { rlim_cur: 0, rlim_max: 0 };
        let _ = libc::setrlimit(libc::RLIMIT_CORE, &lim);
        // Linux: undumpable
        #[cfg(target_os = "linux")]
        {
            let _ = libc::prctl(libc::PR_SET_DUMPABLE, 0, 0, 0, 0);
            // Detect active tracer via /proc/self/status
            if let Ok(mut f) = std::fs::File::open("/proc/self/status") {
                use std::io::Read as _;
                let mut s = String::new();
                let _ = f.read_to_string(&mut s);
                if let Some(line) = s.lines().find(|l| l.starts_with("TracerPid:")) {
                    let val = line.split(':').nth(1).unwrap_or("0").trim();
                    if val != "0" && std::env::var_os("BLACK_BAG_ALLOW_DEBUG").is_none() {
                        eprintln!("debugger detected; refusing to run (set BLACK_BAG_ALLOW_DEBUG=1 to override)");
                        std::process::exit(1);
                    }
                }
            }
        }
        // macOS: deny debugger attach
        #[cfg(target_os = "macos")]
        {
            const PT_DENY_ATTACH: libc::c_int = 31;
            let _ = libc::ptrace(PT_DENY_ATTACH, 0, std::ptr::null_mut(), 0);
        }
    }
}

fn constant_time_eq(a: &[u8], b: &[u8]) -> bool {
    if a.len() != b.len() {
        return false;
    }
    let mut diff: u8 = 0;
    for (x, y) in a.iter().zip(b.iter()) {
        diff |= x ^ y;
    }
    diff == 0
}

fn migrate_vault(config: &AppConfig) -> Result<()> {
    let (mut vault, pass) = load_vault_with_prompt(config)?;
    if vault.file.version == VAULT_VERSION {
        println!("Already at latest version {}", VAULT_VERSION);
        return Ok(());
    }
    vault.file.version = VAULT_VERSION;
    // Recompute header MAC under current passphrase
    let kek = derive_kek(&pass, &vault.file.header.argon)?;
    vault.file.header.header_mac = Some(compute_header_mac(&vault.file.header, kek.as_slice()));
    vault.save(&pass, config)?;
    println!("Migration complete to version {}", VAULT_VERSION);
    Ok(())
}

#[derive(Parser)]
#[command(name = "black-bag", version, about = "Ultra-secure zero-trace CLI vault", long_about = None)]
struct Cli {
    /// Allow secrets to flow to stdout (unsafe; prefer TTY)
    #[arg(long, global = true, default_value_t = false)]
    unsafe_stdout: bool,
    /// Require page-locked memory; abort if locking fails
    #[arg(long, global = true, default_value_t = false)]
    require_mlock: bool,
    /// Preferred output target for sensitive data (requires --unsafe-stdout for stdout/json)
    #[arg(long, value_enum, global = true)]
    emit: Option<EmitMode>,
    /// Optional agent integration (feature-gated backends)
    #[arg(long, value_enum, global = true)]
    agent: Option<config::AgentMode>,
    /// Allow copying secrets to clipboard (dangerous)
    #[arg(long, global = true, default_value_t = false)]
    unsafe_clipboard: bool,
    /// Use duress vault path (separate ciphertext)
    #[arg(long, global = true, default_value_t = false)]
    duress: bool,
    #[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,
    },
    /// Export data (requires --unsafe-stdout for secrets)
    Export {
        #[command(subcommand)]
        command: ExportCommand,
    },
    /// Backup utilities
    Backup {
        #[command(subcommand)]
        command: BackupCommand,
    },
    /// Change master passphrase and/or Argon2 parameters
    Passwd(PasswordCommand),
    /// Minimal TUI (feature-gated)
    #[cfg(feature = "tui")]
    Tui,
    /// Migrate vault to latest on-disk version
    Migrate,
    /// 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,
    /// Argon2 lanes: integer or "auto" for CPU count capped to 8
    #[arg(long)]
    argon_lanes: Option<String>,
}

#[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>,
    /// Fuzzy match the query against summary text
    #[arg(long, default_value_t = false)]
    fuzzy: bool,
}

#[derive(Args)]
struct GetCommand {
    /// Record UUID to inspect
    id: Uuid,
    /// Reveal sensitive fields (requires TTY)
    #[arg(long)]
    reveal: bool,
    /// Copy primary secret to clipboard (requires --unsafe-clipboard)
    #[arg(long, default_value_t = false)]
    clipboard: bool,
}

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

#[derive(Args, Default)]
struct PasswordCommand {
    /// Optionally override Argon2 memory cost in KiB during passphrase change
    #[arg(long)]
    mem_kib: Option<u32>,
    /// Optionally override Argon2 lanes (integer or "auto")
    #[arg(long)]
    argon_lanes: Option<String>,
    /// Rekey the data encryption key (re-encrypts entire payload)
    #[arg(long, default_value_t = false)]
    rekey_dek: bool,
}

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

#[derive(Subcommand)]
enum ExportCommand {
    /// Export records to CSV (requires --unsafe-stdout)
    Csv(ExportCsvCommand),
}

#[derive(Args)]
struct ExportCsvCommand {
    /// Filter by record kind
    #[arg(long, value_enum)]
    kind: Option<RecordKind>,
    /// Comma-separated list of fields to include
    #[arg(long, value_delimiter = ',')]
    fields: Vec<String>,
    /// Allow exporting secrets (strongly discouraged)
    #[arg(long, default_value_t = false)]
    include_secrets: 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,
    /// Use duress channel
    #[arg(long, default_value_t = false)]
    duress: bool,
}

#[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,
    /// Share-set ID printed during split (base32)
    #[arg(long)]
    set_id: Option<String>,
    /// Emit raw binary secret to the TTY instead of base64 text
    #[arg(long, default_value_t = false)]
    raw: bool,
    /// Use duress channel
    #[arg(long, default_value_t = false)]
    duress: bool,
}

#[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(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>,
    /// Read base32 secret from file
    #[arg(long, value_name = "PATH")]
    secret_file: Option<std::path::PathBuf>,
    /// Read base32 secret from stdin (no prompt)
    #[arg(long, default_value_t = false)]
    secret_stdin: bool,
    /// Read otpauth:// TOTP URI from stdin (safer than argv)
    #[arg(long, default_value_t = false)]
    otpauth_stdin: bool,
    /// Print an ASCII QR to the TTY (requires --confirm-qr)
    #[arg(long, default_value_t = false)]
    qr: bool,
    /// Explicit confirmation to print QR in terminal
    #[arg(long, default_value_t = false)]
    confirm_qr: bool,
    /// 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(Subcommand)]
enum BackupCommand {
    /// Verify non-secret integrity tag of a vault backup sidecar
    Verify {
        #[arg(long)]
        path: std::path::PathBuf,
    },
}

#[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,
    #[serde(default)]
    sealed_rdek: Option<AeadBlob>,
}

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,
            sealed_rdek: None,
        }
    }

    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 {
        Self {
            data: value.to_vec(),
        }
    }

    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<String> {
        Ok(String::from_utf8(self.data.clone())?)
    }
}

fn cap_sensitive(name: &str, s: &Sensitive, max: usize) -> Result<()> {
    if s.as_slice().len() > max {
        bail!("{name} too large (>{} bytes)", max);
    }
    Ok(())
}

impl Drop for Sensitive {
    fn drop(&mut self) {
        self.data.zeroize();
    }
}

impl ZeroizeOnDrop for Sensitive {}

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

#[derive(Serialize, Deserialize, Clone)]
struct VaultHeader {
    created_at: DateTime<Utc>,
    updated_at: DateTime<Utc>,
    #[serde(default)]
    epoch: u64,
    argon: ArgonState,
    kem_public: Vec<u8>,
    kem_ciphertext: Vec<u8>,
    sealed_decapsulation: AeadBlob,
    sealed_dek: AeadBlob,
    /// MAC over selected header fields, keyed by KEK (derived from passphrase).
    /// Absent in v1 vaults; verified when present.
    #[serde(default)]
    header_mac: Option<[u8; 32]>,
}

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

#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
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: Zeroizing<[u8; 32]>,
    #[cfg(feature = "mlock")]
    _dek_lock: Option<crate::memory::MlockGuard>,
}

impl Vault {
    fn find_index(&self, id: &Uuid) -> Option<usize> {
        let mut found = None;
        for (idx, record) in self.payload.records.iter().enumerate() {
            if constant_time_uuid_eq(&record.id, id) && found.is_none() {
                found = Some(idx);
            }
        }
        found
    }

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

        if mem_kib < 32_768 {
            bail!("mem-kib must be at least 32768 (32 MiB)");
        }

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

        let argon_lanes = match lanes_choice {
            Some(s) if s.eq_ignore_ascii_case("auto") => {
                let cpus = num_cpus::get().min(8) as u32;
                cpus.max(DEFAULT_LANES)
            }
            Some(s) => s.parse::<u32>().unwrap_or(DEFAULT_LANES).max(DEFAULT_LANES),
            None => {
                let cpus = num_cpus::get().min(8) as u32;
                cpus.max(DEFAULT_LANES)
            }
        };

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

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

        let (ek, dk) = kyber1024::keypair();
        let (shared_key, kem_ct) = kyber1024::encapsulate(&ek);

        let mut dek = Zeroizing::new([0u8; 32]);
        OsRng.fill_bytes(&mut *dek);

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

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

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

        let mut header = VaultHeader {
            created_at: Utc::now(),
            updated_at: Utc::now(),
            epoch: 1,
            argon,
            kem_public: ek.as_bytes().to_vec(),
            kem_ciphertext: kem_ct.as_bytes().to_vec(),
            sealed_decapsulation,
            sealed_dek,
            header_mac: None,
        };

        // Compute header MAC (keyed by KEK) for metadata authenticity
        header.header_mac = Some(compute_header_mac(&header, kek.as_slice()));

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

        write_vault(path, &file)
    }

    fn load(path: &Path, passphrase: &Zeroizing<String>, config: &AppConfig) -> Result<Self> {
        if !path.exists() {
            bail!("vault not initialized");
        }

        let buf = Zeroizing::new(read_vault_bytes(path)?);
        let vault_file: VaultFile = match from_reader(buf.as_slice()) {
            Ok(file) => file,
            Err(err) => return Err(unlock_failure(err)),
        };

        if vault_file.version != VAULT_VERSION && vault_file.version != 1 {
            return Err(unlock_failure(anyhow!(
                "unsupported vault version {}",
                vault_file.version
            )));
        }

        let result = (|| -> Result<Self> {
            let kek = derive_kek(passphrase, &vault_file.header.argon)?;
            #[cfg(feature = "mlock")]
            let _kek_lock = crate::memory::try_lock_slice(kek.as_slice(), config.require_mlock)?;

            // Verify header integrity (when MAC is present) before any decryption
            if let Some(stored) = &vault_file.header.header_mac {
                let computed = compute_header_mac(&vault_file.header, kek.as_slice());
                if !constant_time_eq(stored, &computed) {
                    bail!("header integrity check failed");
                }
            }

            let dk_bytes = Zeroizing::new(decrypt_blob(
                kek.as_slice(),
                &vault_file.header.sealed_decapsulation,
                AAD_DK,
            )?);
            #[cfg(feature = "mlock")]
            let _dk_bytes_lock =
                crate::memory::try_lock_slice(dk_bytes.as_slice(), config.require_mlock)?;
            let dk = expect_sk(dk_bytes.as_slice())?;
            let kem_ct = expect_ct(&vault_file.header.kem_ciphertext)?;
            let shared = kyber1024::decapsulate(&kem_ct, &dk);
            #[cfg(feature = "mlock")]
            let _shared_lock =
                crate::memory::try_lock_slice(shared.as_bytes(), config.require_mlock)?;

            let dek_bytes = Zeroizing::new(decrypt_blob(
                shared.as_bytes(),
                &vault_file.header.sealed_dek,
                AAD_DEK,
            )?);
            #[cfg(feature = "mlock")]
            let _sealed_dek_lock =
                crate::memory::try_lock_slice(dek_bytes.as_slice(), config.require_mlock)?;
            if dek_bytes.len() != 32 {
                bail!("invalid dek length");
            }
            let mut dek = Zeroizing::new([0u8; 32]);
            (&mut *dek).copy_from_slice(dek_bytes.as_slice());
            #[cfg(feature = "mlock")]
            let dek_guard = crate::memory::try_lock_slice(dek.as_ref(), config.require_mlock)?;

            let payload: VaultPayload =
                decrypt_payload_with_config(dek.as_ref(), &vault_file.payload, config)?;
            // Unwrap per-record secrets after load for runtime use
            let mut payload = payload;
            unwrap_payload_after_load(&mut payload, dek.as_ref())?;
            // Anti-rollback: compare epoch sidecar (best-effort)
            if let Ok(seen) = read_epoch_sidecar(path) {
                if vault_file.header.epoch < seen {
                    if std::env::var_os("BLACK_BAG_STRICT_ROLLBACK").is_some() {
                        bail!("vault appears rolled back");
                    } else {
                        eprintln!("warning: vault epoch behind last seen; possible rollback");
                    }
                }
            }

            // Optional stronger anti-rollback via keychain (when compiled with agent-keychain)
            #[cfg(feature = "agent-keychain")]
            {
                if let Some(stored) = maybe_agent_get_epoch(config, path) {
                    if vault_file.header.epoch < stored {
                        if std::env::var_os("BLACK_BAG_ALLOW_ROLLBACK").is_none() {
                            bail!("vault appears rolled back (keychain)");
                        }
                    }
                }
                maybe_agent_store_epoch(config, path, vault_file.header.epoch);
            }

            Ok(Self {
                path: path.to_path_buf(),
                file: vault_file,
                payload,
                dek,
                #[cfg(feature = "mlock")]
                _dek_lock: dek_guard,
            })
        })();

        result.map_err(unlock_failure)
    }

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

        // Wrap secrets for storage using per-record rDEKs in a shadow copy
        let storage_payload = wrap_payload_for_storage(&self.payload, self.dek.as_ref())?;
        let payload_blob =
            encrypt_payload_with_config(self.dek.as_ref(), &storage_payload, config)?;
        self.file.payload = payload_blob;

        let kek = derive_kek(passphrase, &self.file.header.argon)?;
        #[cfg(feature = "mlock")]
        let _kek_lock = crate::memory::try_lock_slice(kek.as_slice(), config.require_mlock)?;

        let dk_bytes = Zeroizing::new(decrypt_blob(
            kek.as_slice(),
            &self.file.header.sealed_decapsulation,
            AAD_DK,
        )?);
        #[cfg(feature = "mlock")]
        let _dk_lock = crate::memory::try_lock_slice(dk_bytes.as_slice(), config.require_mlock)?;
        let dk = expect_sk(dk_bytes.as_slice())?;
        let ek = expect_pk(&self.file.header.kem_public)?;
        let (shared, kem_ct) = kyber1024::encapsulate(&ek);
        #[cfg(feature = "mlock")]
        let _shared_lock = crate::memory::try_lock_slice(shared.as_bytes(), config.require_mlock)?;

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

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

        // Refresh header MAC under KEK
        self.file.header.header_mac = Some(compute_header_mac(&self.file.header, kek.as_slice()));

        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>,
        fuzzy: bool,
    ) -> Vec<&Record> {
        #[allow(clippy::redundant_closure)]
        let matcher = if fuzzy {
            Some(fuzzy_matcher::skim::SkimMatcherV2::default())
        } else {
            None
        };
        self.payload
            .records
            .iter()
            .filter_map(|rec| {
                if let Some(k) = kind {
                    if rec.kind() != k {
                        return None;
                    }
                }
                if let Some(t) = tag {
                    if !rec.matches_tag(t) {
                        return None;
                    }
                }
                if let Some(q) = query {
                    let passed = if fuzzy {
                        use fuzzy_matcher::FuzzyMatcher;
                        let matcher = matcher.as_ref().unwrap();
                        let hay = [
                            rec.title.as_deref().unwrap_or_default(),
                            rec.metadata_notes.as_deref().unwrap_or_default(),
                            &rec.data.summary_text(),
                        ]
                        .join("\n");
                        matcher.fuzzy_match(&hay, q).is_some()
                    } else {
                        rec.matches_query(q)
                    };
                    if !passed {
                        return None;
                    }
                }
                Some(rec)
            })
            .collect()
    }

    fn get(&mut self, id: Uuid) -> Option<&mut Record> {
        self.find_index(&id)
            .and_then(move |idx| self.payload.records.get_mut(idx))
    }

    fn get_ref(&self, id: Uuid) -> Option<&Record> {
        self.find_index(&id)
            .and_then(|idx| self.payload.records.get(idx))
    }

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

        let (ek, dk) = kyber1024::keypair();
        let (shared_key, kem_ct) = kyber1024::encapsulate(&ek);

        let kek = derive_kek(passphrase, &self.file.header.argon)?;
        #[cfg(feature = "mlock")]
        let _kek_lock = crate::memory::try_lock_slice(kek.as_slice(), config.require_mlock)?;
        #[cfg(feature = "mlock")]
        let _shared_lock =
            crate::memory::try_lock_slice(shared_key.as_bytes(), config.require_mlock)?;

        let sealed_dek = encrypt_blob(shared_key.as_bytes(), self.dek.as_ref(), AAD_DEK)?;
        let sealed_decapsulation = encrypt_blob(kek.as_slice(), dk.as_bytes(), AAD_DK)?;

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

        // Update header MAC with new KEK (same passphrase)
        let kek = derive_kek(passphrase, &self.file.header.argon)?;
        self.file.header.header_mac = Some(compute_header_mac(&self.file.header, kek.as_slice()));

        Ok(())
    }

    fn stats(&self) -> VaultStats {
        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,
        }
    }
}

impl Drop for Vault {
    fn drop(&mut self) {
        self.dek.zeroize();
    }
}

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

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| anyhow!("argon2 derivation failed: {e}"))?;
    Ok(output)
}

// pqcrypto-kyber provides from_bytes constructors; validate sizes via constructor errors
fn expect_pk(data: &[u8]) -> Result<kyber1024::PublicKey> {
    kyber1024::PublicKey::from_bytes(data).map_err(|_| anyhow!("invalid public key length").into())
}

fn expect_sk(data: &[u8]) -> Result<kyber1024::SecretKey> {
    kyber1024::SecretKey::from_bytes(data).map_err(|_| anyhow!("invalid secret key length").into())
}

fn expect_ct(data: &[u8]) -> Result<kyber1024::Ciphertext> {
    kyber1024::Ciphertext::from_bytes(data).map_err(|_| anyhow!("invalid ciphertext length").into())
}

fn compute_header_mac(header: &VaultHeader, kek: &[u8]) -> [u8; 32] {
    use blake3::derive_key;
    // Build a canonical buffer of selected fields
    let mut buf = Vec::new();
    buf.extend_from_slice(header.created_at.to_rfc3339().as_bytes());
    buf.extend_from_slice(header.updated_at.to_rfc3339().as_bytes());
    buf.extend_from_slice(&header.argon.mem_cost_kib.to_be_bytes());
    buf.extend_from_slice(&header.argon.time_cost.to_be_bytes());
    buf.extend_from_slice(&header.argon.lanes.to_be_bytes());
    buf.extend_from_slice(&header.argon.salt);
    buf.extend_from_slice(&header.epoch.to_be_bytes());
    buf.extend_from_slice(&header.kem_public);
    buf.extend_from_slice(&header.kem_ciphertext);
    // Include AEAD headers to bind values
    buf.extend_from_slice(&header.sealed_decapsulation.nonce);
    buf.extend_from_slice(&header.sealed_decapsulation.ciphertext);
    buf.extend_from_slice(&header.sealed_dek.nonce);
    buf.extend_from_slice(&header.sealed_dek.ciphertext);
    let key = derive_key("black-bag header mac", kek);
    let mut hasher = blake3::Hasher::new_keyed(&key);
    hasher.update(&buf);
    *hasher.finalize().as_bytes()
}

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 })
}

#[cfg(test)]
fn encrypt_blob_with_nonce(key: &[u8], plaintext: &[u8], aad: &[u8], nonce: [u8; 24]) -> Result<AeadBlob> {
    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_with_config(
    dek: &[u8],
    payload: &VaultPayload,
    config: &AppConfig,
) -> Result<AeadBlob> {
    let mut buf = Zeroizing::new(Vec::new());
    into_writer(payload, &mut *buf).context("failed to serialize payload")?;
    let block = std::env::var("BLACK_BAG_PAD_BLOCK")
        .ok()
        .and_then(|v| v.parse::<usize>().ok())
        .unwrap_or(64 * 1024);
    let padded = apply_padding(buf.as_slice(), block)?;
    #[cfg(feature = "mlock")]
    let _guard = crate::memory::try_lock_slice(padded.as_slice(), config.require_mlock)?;
    encrypt_blob(dek, padded.as_slice(), AAD_PAYLOAD)
}

fn decrypt_payload_with_config(
    dek: &[u8],
    blob: &AeadBlob,
    config: &AppConfig,
) -> Result<VaultPayload> {
    let plaintext = Zeroizing::new(decrypt_blob(dek, blob, AAD_PAYLOAD)?);
    if plaintext.len() > MAX_PAYLOAD_PLAINTEXT_BYTES {
        bail!("payload too large");
    }
    #[cfg(feature = "mlock")]
    let _guard = crate::memory::try_lock_slice(plaintext.as_slice(), config.require_mlock)?;
    let inner = strip_padding(plaintext.as_slice())?;
    let payload: VaultPayload = from_reader(inner).context("failed to parse payload")?;
    enforce_payload_limits(&payload)?;
    Ok(payload)
}

fn apply_padding(data: &[u8], block: usize) -> Result<Zeroizing<Vec<u8>>> {
    if block == 0 {
        return Ok(Zeroizing::new(data.to_vec()));
    }
    let header_len = PAD_MAGIC.len() + 8;
    let total = header_len + data.len();
    let mut out = Zeroizing::new(Vec::with_capacity(total + block));
    out.extend_from_slice(PAD_MAGIC);
    out.extend_from_slice(&(data.len() as u64).to_le_bytes());
    out.extend_from_slice(data);
    let padded_len = ((out.len() + block - 1) / block) * block;
    let pad_needed = padded_len - out.len();
    if pad_needed > 0 {
        let mut pad = vec![0u8; pad_needed];
        OsRng.fill_bytes(&mut pad);
        out.extend_from_slice(&pad);
    } else {
        let mut pad = vec![0u8; block];
        OsRng.fill_bytes(&mut pad);
        out.extend_from_slice(&pad);
    }
    Ok(out)
}

fn strip_padding<'a>(plaintext: &'a [u8]) -> Result<&'a [u8]> {
    if plaintext.len() >= PAD_MAGIC.len() + 8 && &plaintext[..PAD_MAGIC.len()] == PAD_MAGIC {
        let mut len_bytes = [0u8; 8];
        len_bytes.copy_from_slice(&plaintext[PAD_MAGIC.len()..PAD_MAGIC.len() + 8]);
        let cbor_len = u64::from_le_bytes(len_bytes) as usize;
        let start = PAD_MAGIC.len() + 8;
        if start + cbor_len > plaintext.len() {
            bail!("invalid padded payload length");
        }
        Ok(&plaintext[start..start + cbor_len])
    } else {
        Ok(plaintext)
    }
}

fn wrap_payload_for_storage(src: &VaultPayload, dek: &[u8]) -> Result<VaultPayload> {
    let mut out = src.clone();
    for rec in out.records.iter_mut() {
        process_record_wrap(rec, dek)?;
    }
    Ok(out)
}

fn unwrap_payload_after_load(payload: &mut VaultPayload, dek: &[u8]) -> Result<()> {
    for rec in payload.records.iter_mut() {
        process_record_unwrap(rec, dek)?;
    }
    Ok(())
}

fn process_record_wrap(rec: &mut Record, dek: &[u8]) -> Result<()> {
    // Ensure rDEK
    let rdek = if let Some(sealed) = &rec.sealed_rdek {
        let bytes = decrypt_blob(dek, sealed, AAD_RDEK)?;
        Zeroizing::new(bytes)
    } else {
        let mut r = [0u8; 32];
        OsRng.fill_bytes(&mut r);
        let r_vec = Zeroizing::new(r.to_vec());
        rec.sealed_rdek = Some(encrypt_blob(dek, r_vec.as_slice(), AAD_RDEK)?);
        r_vec
    };
    wrap_record_secrets(&mut rec.data, rdek.as_slice())
}

fn process_record_unwrap(rec: &mut Record, dek: &[u8]) -> Result<()> {
    if let Some(sealed) = &rec.sealed_rdek {
        let rdek = Zeroizing::new(decrypt_blob(dek, sealed, AAD_RDEK)?);
        unwrap_record_secrets(&mut rec.data, rdek.as_slice())?;
    }
    Ok(())
}

fn wrap_record_secrets(data: &mut RecordData, rdek: &[u8]) -> Result<()> {
    match data {
        RecordData::Login { password, .. } => wrap_sensitive(password, rdek)?,
        RecordData::Contact { .. } => {}
        RecordData::Id { secret, .. } => {
            if let Some(s) = secret {
                wrap_sensitive(s, rdek)?;
            }
        }
        RecordData::Note { body } => wrap_sensitive(body, rdek)?,
        RecordData::Bank { account_number, .. } => wrap_sensitive(account_number, rdek)?,
        RecordData::Wifi { passphrase, .. } => wrap_sensitive(passphrase, rdek)?,
        RecordData::Api { secret_key, .. } => wrap_sensitive(secret_key, rdek)?,
        RecordData::Wallet { secret_key, .. } => wrap_sensitive(secret_key, rdek)?,
        RecordData::Totp { secret, .. } => wrap_sensitive(secret, rdek)?,
        RecordData::Ssh { private_key, .. } => wrap_sensitive(private_key, rdek)?,
        RecordData::Pgp {
            armored_private_key,
            ..
        } => wrap_sensitive(armored_private_key, rdek)?,
        RecordData::Recovery { payload, .. } => wrap_sensitive(payload, rdek)?,
    }
    Ok(())
}

fn unwrap_record_secrets(data: &mut RecordData, rdek: &[u8]) -> Result<()> {
    match data {
        RecordData::Login { password, .. } => unwrap_sensitive(password, rdek)?,
        RecordData::Contact { .. } => {}
        RecordData::Id { secret, .. } => {
            if let Some(s) = secret {
                unwrap_sensitive(s, rdek)?;
            }
        }
        RecordData::Note { body } => unwrap_sensitive(body, rdek)?,
        RecordData::Bank { account_number, .. } => unwrap_sensitive(account_number, rdek)?,
        RecordData::Wifi { passphrase, .. } => unwrap_sensitive(passphrase, rdek)?,
        RecordData::Api { secret_key, .. } => unwrap_sensitive(secret_key, rdek)?,
        RecordData::Wallet { secret_key, .. } => unwrap_sensitive(secret_key, rdek)?,
        RecordData::Totp { secret, .. } => unwrap_sensitive(secret, rdek)?,
        RecordData::Ssh { private_key, .. } => unwrap_sensitive(private_key, rdek)?,
        RecordData::Pgp {
            armored_private_key,
            ..
        } => unwrap_sensitive(armored_private_key, rdek)?,
        RecordData::Recovery { payload, .. } => unwrap_sensitive(payload, rdek)?,
    }
    Ok(())
}

fn enforce_payload_limits(payload: &VaultPayload) -> Result<()> {
    if payload.records.len() > MAX_RECORDS {
        bail!("too many records");
    }
    for rec in &payload.records {
        if rec.tags.len() > MAX_TAGS_PER_RECORD {
            bail!("too many tags");
        }
        for t in &rec.tags {
            if t.len() > MAX_TAG_LEN { bail!("tag too long"); }
        }
        if let Some(t) = &rec.title { if t.len() > MAX_TITLE_LEN { bail!("title too long"); } }
        if let Some(n) = &rec.metadata_notes { if n.len() > MAX_NOTE_BYTES { bail!("notes too large"); } }
        match &rec.data {
            RecordData::Login{ username, url, password } => {
                if let Some(u)=username { if u.len()>2048 { bail!("username too long"); } }
                if let Some(u)=url { if u.len()>4096 { bail!("url too long"); } }
                if password.as_slice().len() > MAX_FIELD_BYTES { bail!("password too large"); }
            }
            RecordData::Contact{ full_name, emails, phones } => {
                if full_name.len()>1024 { bail!("full name too long"); }
                if emails.len()>256 || phones.len()>256 { bail!("too many contact entries"); }
            }
            RecordData::Id{ secret, .. } => {
                if let Some(s)=secret { if s.as_slice().len() > MAX_FIELD_BYTES { bail!("id secret too large"); } }
            }
            RecordData::Note{ body } => { if body.as_slice().len() > MAX_NOTE_BYTES { bail!("note too large"); } }
            RecordData::Bank{ account_number, .. } => { if account_number.as_slice().len() > MAX_FIELD_BYTES { bail!("account number too large"); } }
            RecordData::Wifi{ passphrase, .. } => { if passphrase.as_slice().len() > MAX_FIELD_BYTES { bail!("wifi passphrase too large"); } }
            RecordData::Api{ secret_key, .. } => { if secret_key.as_slice().len() > MAX_FIELD_BYTES { bail!("api secret too large"); } }
            RecordData::Wallet{ secret_key, .. } => { if secret_key.as_slice().len() > MAX_FIELD_BYTES { bail!("wallet secret too large"); } }
            RecordData::Totp{ secret, .. } => { if secret.as_slice().len() > MAX_FIELD_BYTES { bail!("totp secret too large"); } }
            RecordData::Ssh{ private_key, .. } => { if private_key.as_slice().len() > MAX_NOTE_BYTES { bail!("ssh key too large"); } }
            RecordData::Pgp{ armored_private_key, .. } => { if armored_private_key.as_slice().len() > MAX_NOTE_BYTES { bail!("pgp key too large"); } }
            RecordData::Recovery{ payload, .. } => { if payload.as_slice().len() > MAX_NOTE_BYTES { bail!("recovery payload too large"); } }
        }
    }
    Ok(())
}

fn wrap_sensitive(s: &mut Sensitive, rdek: &[u8]) -> Result<()> {
    // If already wrapped, skip
    if s.data.len() >= 4 && &s.data[..4] == SECRET_MARKER {
        return Ok(());
    }
    let blob = encrypt_blob(rdek, s.as_slice(), AAD_SECRET)?;
    let mut out = Vec::with_capacity(4 + 24 + blob.ciphertext.len());
    out.extend_from_slice(SECRET_MARKER);
    out.extend_from_slice(&blob.nonce);
    out.extend_from_slice(&blob.ciphertext);
    s.data = out;
    Ok(())
}

fn unwrap_sensitive(s: &mut Sensitive, rdek: &[u8]) -> Result<()> {
    if s.data.len() >= 4 && &s.data[..4] == SECRET_MARKER {
        if s.data.len() < 4 + 24 {
            bail!("wrapped secret too short");
        }
        let mut nonce = [0u8; 24];
        nonce.copy_from_slice(&s.data[4..28]);
        let ct = s.data[28..].to_vec();
        let blob = AeadBlob {
            nonce,
            ciphertext: ct,
        };
        let pt = decrypt_blob(rdek, &blob, AAD_SECRET)?;
        s.data = pt;
    }
    Ok(())
}

fn encrypt_payload(dek: &[u8], payload: &VaultPayload) -> Result<AeadBlob> {
    encrypt_payload_with_config(dek, payload, &AppConfig::default())
}

fn decrypt_payload(dek: &[u8], blob: &AeadBlob) -> Result<VaultPayload> {
    decrypt_payload_with_config(dek, blob, &AppConfig::default())
}

fn vault_path_with_cfg(config: &AppConfig) -> Result<PathBuf> {
    if let Ok(path) = env::var(if config.duress {
        "BLACK_BAG_VAULT_DURESS_PATH"
    } else {
        "BLACK_BAG_VAULT_PATH"
    }) {
        let pb = PathBuf::from(path);
        if let Some(parent) = pb.parent() {
            fs::create_dir_all(parent).context("failed to create vault directory")?;
        }
        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).context("failed to create vault directory")?;
    let path = dir.join("vault.cbor");
    if config.duress {
        let stem = path.file_stem().and_then(|s| s.to_str()).unwrap_or("vault");
        Ok(path.with_file_name(format!("{}.duress.cbor", stem)))
    } else {
        Ok(path)
    }
}

fn prompt_passphrase(prompt: &str, config: &AppConfig) -> Result<Zeroizing<String>> {
    match prompt_password(prompt) {
        Ok(value) => {
            if value.trim().is_empty() {
                bail!("passphrase cannot be empty");
            }
            Ok(Zeroizing::new(value))
        }
        Err(_) if config.unsafe_stdout => {
            let mut stderr = io::stderr();
            stderr.write_all(prompt.as_bytes())?;
            stderr.write_all(b"\n")?;
            stderr.flush()?;
            let mut line = String::new();
            io::stdin().read_line(&mut line)?;
            let line = line.trim_end_matches(&['\r', '\n'][..]).to_string();
            if line.trim().is_empty() {
                bail!("passphrase cannot be empty");
            }
            Ok(Zeroizing::new(line))
        }
        Err(err) => Err(err.into()),
    }
}

fn ensure_passphrase_strength(passphrase: &str) -> Result<()> {
    use unicode_normalization::UnicodeNormalization;
    let norm: String = passphrase.nfkc().collect();
    if norm.chars().count() < 14 {
        bail!("passphrase must be at least 14 characters");
    }
    // quick rejects for common patterns
    const COMMON: &[&str] = &[
        "password","123456","123456789","qwerty","letmein","iloveyou","admin","welcome","monkey","abc123","1q2w3e4r","dragon","sunshine","princess","football","password1","zaq12wsx","qwertyuiop","passw0rd","baseball"
    ];
    let lower = norm.to_ascii_lowercase();
    if COMMON.iter().any(|w| lower.contains(w)) {
        bail!("passphrase too common");
    }
    let unique: std::collections::HashSet<char> = norm.chars().collect();
    if unique.len() < 6 {
        bail!("passphrase has too few unique characters");
    }
    let estimate = zxcvbn(&norm, &[])
        .map_err(|err| anyhow!("failed to evaluate passphrase strength: {err}"))?;
    if estimate.score() < 3 {
        bail!(
            "passphrase too weak (score {} of 4). Use a longer, less predictable passphrase.",
            estimate.score()
        );
    }
    Ok(())
}

fn init_vault(cmd: InitCommand, config: &AppConfig) -> Result<()> {
    let path = vault_path_with_cfg(config)?;
    let pass1 = prompt_passphrase("Master passphrase: ", config)?;
    ensure_passphrase_strength(pass1.as_str())?;
    let pass2 = prompt_passphrase("Confirm passphrase: ", config)?;
    if pass1.as_str() != pass2.as_str() {
        bail!("passphrases do not match");
    }
    Vault::init(
        &path,
        &pass1,
        cmd.mem_kib,
        config,
        cmd.argon_lanes.as_deref(),
    )?;
    maybe_agent_store(config, &path, pass1.as_str());
    println!("Initialized vault");
    Ok(())
}

struct LockedPassphrase {
    inner: Zeroizing<String>,
    #[cfg(feature = "mlock")]
    _guard: Option<crate::memory::MlockGuard>,
}

impl LockedPassphrase {
    fn new(value: Zeroizing<String>, config: &AppConfig) -> Result<Self> {
        #[cfg(feature = "mlock")]
        let guard = crate::memory::try_lock_slice(value.as_bytes(), config.require_mlock)?;
        Ok(Self {
            inner: value,
            #[cfg(feature = "mlock")]
            _guard: guard,
        })
    }
}

impl Deref for LockedPassphrase {
    type Target = Zeroizing<String>;
    fn deref(&self) -> &Self::Target {
        &self.inner
    }
}

impl DerefMut for LockedPassphrase {
    fn deref_mut(&mut self) -> &mut Self::Target {
        &mut self.inner
    }
}

fn load_vault_with_prompt(config: &AppConfig) -> Result<(Vault, LockedPassphrase)> {
    let path = vault_path_with_cfg(config)?;
    // Try agent if configured; validate by attempting load
    if let Some(agent_pass) = maybe_agent_retrieve(config, &path) {
        if let Ok(locked) = LockedPassphrase::new(agent_pass, config) {
            if let Ok(vault) = Vault::load(&path, &locked, config) {
                return Ok((vault, locked));
            }
        }
        eprintln!("warning: cached passphrase invalid; falling back to prompt");
    }
    let pass = prompt_passphrase("Master passphrase: ", config)?;
    let locked = LockedPassphrase::new(pass, config)?;
    let vault = Vault::load(&path, &locked, config)?;
    Ok((vault, locked))
}

fn add_record(cmd: AddCommand, config: &AppConfig) -> Result<()> {
    let (mut vault, pass) = load_vault_with_prompt(config)?;

    let record = match cmd.record {
        AddRecord::Login(args) => {
            let CommonRecordArgs { title, tags, notes } = args.common;
            let password = prompt_hidden("Password: ")?;
            Record::new(
                RecordData::Login {
                    username: args.username,
                    url: args.url,
                    password,
                },
                title,
                tags,
                notes,
            )
        }
        AddRecord::Contact(args) => {
            let CommonRecordArgs { title, tags, notes } = args.common;
            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): ")?;
            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): ")?;
            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: ")?;
            cap_sensitive("account number", &account_number, MAX_FIELD_BYTES)?;
            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: ")?;
            cap_sensitive("wifi passphrase", &passphrase, MAX_FIELD_BYTES)?;
            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: ")?;
            cap_sensitive("api secret", &secret, MAX_FIELD_BYTES)?;
            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: ")?;
            cap_sensitive("wallet secret", &secret, MAX_FIELD_BYTES)?;
            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_file,
                secret_stdin,
                otpauth_stdin,
                qr,
                confirm_qr,
                digits,
                step,
                skew,
                algorithm,
            } = args;
            const TOTP_MIN_DIGITS: u8 = 6;
            const TOTP_MAX_DIGITS: u8 = 8;
            if !(TOTP_MIN_DIGITS..=TOTP_MAX_DIGITS).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, issuer, account, digits, step, algorithm) = if otpauth_stdin {
                use std::io::Read;
                let mut s = String::new();
                std::io::stdin().read_to_string(&mut s)?;
                let parsed = parse_otpauth_uri(&s)?;
                (
                    parsed.secret,
                    parsed.issuer.or(issuer),
                    parsed.account.or(account),
                    parsed.digits,
                    parsed.step,
                    parsed.algorithm,
                )
            } else {
                let sb = read_totp_secret_arg(secret_file.as_ref(), secret_stdin)?;
                (sb, issuer, account, digits, step, algorithm)
            };
            let totp_secret = Sensitive { data: secret_bytes };
            build_totp_instance(
                &totp_secret,
                digits,
                step,
                skew,
                algorithm,
                &issuer,
                &account,
            )?;
            let record = Record::new(
                RecordData::Totp {
                    issuer: issuer.clone(),
                    account: account.clone(),
                    secret: totp_secret,
                    digits,
                    step,
                    skew,
                    algorithm,
                },
                title,
                tags,
                notes,
            );
            if qr {
                if !confirm_qr {
                    bail!("printing QR requires --confirm-qr acknowledgment");
                }
                if let (Some(uri_issuer), Some(uri_account)) = (issuer, account) {
                    let base32 = base32::encode(
                        base32::Alphabet::Rfc4648 { padding: false },
                        record_secret_slice(&record),
                    );
                    let uri = build_otpauth_uri(
                        &uri_issuer,
                        &uri_account,
                        &base32,
                        digits,
                        step,
                        algorithm,
                    );
                    output::print_qr_to_tty(&uri, config)?;
                }
            }
            record
        }
        AddRecord::Ssh(args) => {
            let CommonRecordArgs { title, tags, notes } = args.common;
            let private_key = prompt_multiline_paste(
                "Paste private key (Ctrl-D to finish): (input will be visible)",
            )?;
            cap_sensitive("ssh private key", &private_key, MAX_NOTE_BYTES)?;
            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_paste(
                "Paste armored private key (Ctrl-D to finish): (input will be visible)",
            )?;
            cap_sensitive("pgp private key", &armored, MAX_NOTE_BYTES)?;
            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_paste(
                "Paste recovery payload (Ctrl-D to finish): (input will be visible)",
            )?;
            cap_sensitive("recovery payload", &payload, MAX_NOTE_BYTES)?;
            Record::new(
                RecordData::Recovery {
                    description: args.description,
                    payload,
                },
                title,
                tags,
                notes,
            )
        }
    };

    vault.add_record(record);
    vault.save(&pass, config)?;
    println!("Record added");
    Ok(())
}
fn list_records(cmd: ListCommand, config: &AppConfig) -> Result<()> {
    let (vault, _) = load_vault_with_prompt(config)?;
    let list = vault.list(
        cmd.kind,
        cmd.tag.as_deref(),
        cmd.query.as_deref(),
        cmd.fuzzy,
    );
    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, config: &AppConfig) -> Result<()> {
    let (mut vault, _) = load_vault_with_prompt(config)?;
    match vault.get(cmd.id) {
        Some(record) => {
            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 cmd.clipboard {
                #[cfg(feature = "clipboard")]
                {
                    if !config.unsafe_clipboard {
                        bail!("--clipboard requires --unsafe-clipboard");
                    }
                    copy_primary_secret_to_clipboard(record, config)?;
                    eprintln!("Copied to clipboard; it will be cleared shortly.");
                }
                #[cfg(not(feature = "clipboard"))]
                {
                    bail!("clipboard support disabled at build time");
                }
            } else if cmd.reveal {
                ensure_interactive_or_override(config, "--reveal")?;
                render_sensitive(record, config)?;
            } else {
                println!("(Sensitive fields hidden; re-run with --reveal on a TTY)");
            }
            Ok(())
        }
        None => bail!("operation failed"),
    }
}

#[cfg(feature = "clipboard")]
fn copy_primary_secret_to_clipboard(record: &Record, _config: &AppConfig) -> Result<()> {
    use arboard::Clipboard;
    let text = match &record.data {
        RecordData::Login { password, .. } => password.expose_utf8()?,
        RecordData::Bank { account_number, .. } => account_number.expose_utf8()?,
        RecordData::Wifi { passphrase, .. } => passphrase.expose_utf8()?,
        RecordData::Api { secret_key, .. } => secret_key.expose_utf8()?,
        RecordData::Wallet { secret_key, .. } => secret_key.expose_utf8()?,
        RecordData::Totp { secret, .. } => base32::encode(
            base32::Alphabet::Rfc4648 { padding: false },
            secret.as_slice(),
        ),
        RecordData::Ssh { private_key, .. } => private_key.expose_utf8()?,
        RecordData::Pgp {
            armored_private_key,
            ..
        } => armored_private_key.expose_utf8()?,
        RecordData::Recovery { payload, .. } => payload.expose_utf8()?,
        RecordData::Contact { .. } | RecordData::Id { .. } | RecordData::Note { .. } => {
            bail!("no primary secret available for this record kind");
        }
    };
    let mut cb = Clipboard::new().map_err(|e| anyhow!("clipboard unavailable: {e}"))?;
    cb.set_text(text.clone())
        .map_err(|e| anyhow!("failed to set clipboard: {e}"))?;
    std::thread::spawn(move || {
        std::thread::sleep(std::time::Duration::from_secs(20));
        if let Ok(mut c) = Clipboard::new() {
            let _ = c.set_text(String::new());
        }
    });
    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();
    Ok(TotpSecret::Encoded(encoded)
        .to_bytes()
        .map_err(|_| anyhow!("invalid base32-encoded secret"))?)
}

struct ParsedOtpAuth {
    secret: Vec<u8>,
    digits: u8,
    step: u64,
    algorithm: TotpAlgorithm,
    issuer: Option<String>,
    account: Option<String>,
}

fn parse_otpauth_uri(uri: &str) -> Result<ParsedOtpAuth> {
    let url = url::Url::parse(uri).map_err(|_| anyhow!("invalid otpauth uri"))?;
    if url.scheme() != "otpauth" {
        bail!("not an otpauth uri");
    }
    if url.host_str() != Some("totp") {
        bail!("only totp is supported");
    }
    let label = url.path().trim_start_matches('/');
    let account = if label.is_empty() {
        None
    } else {
        Some(label.to_string())
    };
    let mut secret_opt = None;
    let mut issuer = None;
    let mut digits = 6u8;
    let mut step = 30u64;
    let mut algorithm = TotpAlgorithm::Sha1;
    for (k, v) in url.query_pairs() {
        match k.as_ref() {
            "secret" => {
                secret_opt = Some(parse_totp_secret(v.as_ref())?);
            }
            "issuer" => issuer = Some(v.to_string()),
            "digits" => {
                digits = v.parse::<u8>().unwrap_or(6);
            }
            "period" => {
                step = v.parse::<u64>().unwrap_or(30);
            }
            "algorithm" => {
                algorithm = match v.as_ref().to_ascii_uppercase().as_str() {
                    "SHA256" => TotpAlgorithm::Sha256,
                    "SHA512" => TotpAlgorithm::Sha512,
                    _ => TotpAlgorithm::Sha1,
                };
            }
            _ => {}
        }
    }
    let secret = secret_opt.ok_or_else(|| anyhow!("otpauth missing secret"))?;
    Ok(ParsedOtpAuth {
        secret,
        digits,
        step,
        algorithm,
        issuer,
        account,
    })
}

fn build_otpauth_uri(
    issuer: &str,
    account: &str,
    secret_base32: &str,
    digits: u8,
    step: u64,
    algorithm: TotpAlgorithm,
) -> String {
    let algo = match algorithm {
        TotpAlgorithm::Sha1 => "SHA1",
        TotpAlgorithm::Sha256 => "SHA256",
        TotpAlgorithm::Sha512 => "SHA512",
    };
    format!(
        "otpauth://totp/{}?secret={}&issuer={}&digits={}&period={}&algorithm={}",
        account,
        secret_base32,
        urlencoding::encode(issuer),
        digits,
        step,
        algo
    )
}

fn record_secret_slice(record: &Record) -> &[u8] {
    match &record.data {
        RecordData::Totp { secret, .. } => secret.as_slice(),
        _ => &[],
    }
}

fn read_totp_secret_arg(
    secret_file: Option<&std::path::PathBuf>,
    secret_stdin: bool,
) -> Result<Vec<u8>> {
    if let Some(path) = secret_file {
        let s = std::fs::read_to_string(path)?;
        return parse_totp_secret(s.trim());
    }
    if secret_stdin {
        let mut s = String::new();
        io::stdin().read_to_string(&mut s)?;
        return parse_totp_secret(s.trim());
    }
    let input = prompt_hidden("Base32 secret: ")?;
    let value = Zeroizing::new(input.expose_utf8()?);
    parse_totp_secret(value.as_str())
}

fn build_totp_instance(
    secret: &Sensitive,
    digits: u8,
    step: u64,
    skew: u8,
    algorithm: TotpAlgorithm,
    _issuer: &Option<String>,
    _account: &Option<String>,
) -> Result<TOTP> {
    let secret_bytes = Zeroizing::new(secret.as_slice().to_vec());
    let totp_secret = (*secret_bytes).clone();
    Ok(TOTP::new(
        algorithm.to_lib(),
        usize::from(digits),
        skew,
        step,
        totp_secret,
    )
    .map_err(|err| anyhow!("failed to construct TOTP: {err}"))?)
}

fn rotate_vault(cmd: RotateCommand, config: &AppConfig) -> Result<()> {
    let (mut vault, pass) = load_vault_with_prompt(config)?;
    vault.rotate(&pass, cmd.mem_kib, config)?;
    vault.save(&pass, config)?;
    println!("Rotation complete");
    Ok(())
}

fn passwd(cmd: PasswordCommand, config: &AppConfig) -> Result<()> {
    let (mut vault, old_pass) = load_vault_with_prompt(config)?;

    if let Some(mem) = cmd.mem_kib {
        if mem < 32_768 {
            bail!("mem-kib must be at least 32768 (32 MiB)");
        }
        vault.file.header.argon.mem_cost_kib = mem;
        OsRng.fill_bytes(&mut vault.file.header.argon.salt);
    }
    if let Some(lanes) = cmd.argon_lanes.as_deref() {
        let lanes = if lanes.eq_ignore_ascii_case("auto") {
            (num_cpus::get().min(8) as u32).max(DEFAULT_LANES)
        } else {
            lanes.parse::<u32>().unwrap_or(DEFAULT_LANES).max(DEFAULT_LANES)
        };
        vault.file.header.argon.lanes = lanes;
    }

    let new1 = prompt_passphrase("New passphrase: ", config)?;
    ensure_passphrase_strength(new1.as_str())?;
    let new2 = prompt_passphrase("Confirm new passphrase: ", config)?;
    if new1.as_str() != new2.as_str() {
        bail!("passphrases do not match");
    }

    // derive KEKs
    let old_kek = derive_kek(&old_pass, &vault.file.header.argon)?;
    let new_kek = derive_kek(&new1, &vault.file.header.argon)?;

    // decrypt DK with old KEK, then re-encrypt with new KEK
    let dk_bytes = Zeroizing::new(decrypt_blob(
        old_kek.as_slice(),
        &vault.file.header.sealed_decapsulation,
        AAD_DK,
    )?);
    let sealed_decapsulation = encrypt_blob(new_kek.as_slice(), dk_bytes.as_slice(), AAD_DK)?;
    vault.file.header.sealed_decapsulation = sealed_decapsulation;

    // Optional: rekey DEK and fully re-encrypt payload under the new DEK
    if cmd.rekey_dek {
        let mut new_dek = Zeroizing::new([0u8; 32]);
        OsRng.fill_bytes(&mut *new_dek);
        vault.dek = new_dek;
        #[cfg(feature = "mlock")]
        let _ = crate::memory::try_lock_slice(vault.dek.as_ref(), config.require_mlock)?;
    }

    // Save using the new passphrase
    vault.file.header.header_mac = Some(compute_header_mac(&vault.file.header, new_kek.as_slice()));
    vault.save(&new1, config)?;
    let path = vault_path_with_cfg(config)?;
    maybe_agent_store(config, &path, new1.as_str());
    println!("Master passphrase updated");
    Ok(())
}

#[cfg(feature = "agent-keychain")]
fn agent_label_for_path(path: &Path) -> String {
    use blake3::Hasher;
    let s = path.to_string_lossy();
    let mut h = Hasher::new();
    h.update(s.as_bytes());
    hex::encode(h.finalize().as_bytes())
}

#[cfg(feature = "agent-keychain")]
fn maybe_agent_retrieve(config: &AppConfig, path: &Path) -> Option<Zeroizing<String>> {
    use crate::agent::Agent;
    if matches!(config.agent, config::AgentMode::Keychain) {
        let label = agent_label_for_path(path);
        let agent = crate::agent::KeychainAgent;
        match agent.retrieve_passphrase(&label) {
            Ok(Some(s)) => return Some(Zeroizing::new(s)),
            _ => {}
        }
    }
    None
}

#[cfg(not(feature = "agent-keychain"))]
fn maybe_agent_retrieve(config: &AppConfig, _path: &Path) -> Option<Zeroizing<String>> {
    let _ = config.agent; // avoid unused warning
    None
}

#[cfg(feature = "agent-keychain")]
fn maybe_agent_store(config: &AppConfig, path: &Path, pass: &str) {
    use crate::agent::Agent;
    if matches!(config.agent, config::AgentMode::Keychain) {
        let _ = crate::agent::KeychainAgent.store_passphrase(&agent_label_for_path(path), pass);
    }
}

#[cfg(not(feature = "agent-keychain"))]
fn maybe_agent_store(config: &AppConfig, _path: &Path, _pass: &str) {
    let _ = config.agent; // avoid unused warning
}

#[cfg(feature = "agent-keychain")]
fn maybe_agent_get_epoch(config: &AppConfig, path: &Path) -> Option<u64> {
    use crate::agent::Agent;
    if matches!(config.agent, config::AgentMode::Keychain) {
        let agent = crate::agent::KeychainAgent;
        let label = format!("epoch:{}", agent_label_for_path(path));
        if let Ok(Some(s)) = agent.retrieve_passphrase(&label) {
            if let Ok(v) = s.parse::<u64>() { return Some(v); }
        }
    }
    None
}

#[cfg(feature = "agent-keychain")]
fn maybe_agent_store_epoch(config: &AppConfig, path: &Path, epoch: u64) {
    use crate::agent::Agent;
    if matches!(config.agent, config::AgentMode::Keychain) {
        let agent = crate::agent::KeychainAgent;
        let label = format!("epoch:{}", agent_label_for_path(path));
        let _ = agent.store_passphrase(&label, &epoch.to_string());
    }
}

fn doctor(cmd: DoctorCommand, config: &AppConfig) -> Result<()> {
    let (vault, _) = load_vault_with_prompt(config)?;
    let stats = vault.stats();
    // Header MAC verified during load when present
    let header_mac_verified = vault.file.header.header_mac.is_some();
    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(),
            "headerMacVerified": header_mac_verified,
        });
        println!("{}", payload);
    } else {
        println!("status: ready");
        println!("records: {}", stats.record_count);
        println!("created: {}", stats.created_at);
        println!("updated: {}", stats.updated_at);
        println!(
            "argon2: mem={} KiB, time={}, lanes={}",
            stats.argon_mem_kib, stats.argon_time_cost, stats.argon_lanes
        );
        println!(
            "header-mac: {}",
            if header_mac_verified { "verified" } else { "absent (legacy)" }
        );
    }
    Ok(())
}

fn export(cmd: ExportCommand, config: &AppConfig) -> Result<()> {
    match cmd {
        ExportCommand::Csv(args) => export_csv(args, config),
    }
}

fn export_csv(args: ExportCsvCommand, config: &AppConfig) -> Result<()> {
    if !config.unsafe_stdout {
        bail!("export requires --unsafe-stdout");
    }
    let (vault, _) = load_vault_with_prompt(config)?;
    let mut wtr = csv::Writer::from_writer(std::io::stdout());
    let fields = if args.fields.is_empty() {
        vec![
            "id".to_string(),
            "kind".to_string(),
            "title".to_string(),
            "summary".to_string(),
        ]
    } else {
        args.fields.clone()
    };
    let sensitive: std::collections::HashSet<&str> = [
        "password",
        "secret_key",
        "totp_secret",
        "private_key",
        "pgp_private_key",
        "recovery_payload",
        "account_number",
        "passphrase",
    ]
    .into_iter()
    .collect();
    if !args.include_secrets && fields.iter().any(|f| sensitive.contains(f.as_str())) {
        bail!("exporting secret fields requires --include-secrets");
    }
    wtr.write_record(&fields)?;
    let items = vault.list(args.kind, None, None, false);
    for r in items {
        let mut row = Vec::with_capacity(fields.len());
        for f in &fields {
            let val = match f.as_str() {
                "id" => r.id.to_string(),
                "kind" => format!("{}", r.kind()),
                "title" => r.title.clone().unwrap_or_default(),
                "tags" => {
                    if r.tags.is_empty() {
                        String::new()
                    } else {
                        r.tags.join(",")
                    }
                }
                "summary" => r.data.summary_text(),
                // best-effort per-kind fields
                "username" => match &r.data {
                    RecordData::Login { username, .. } => username.clone().unwrap_or_default(),
                    _ => String::new(),
                },
                "url" => match &r.data {
                    RecordData::Login { url, .. } => url.clone().unwrap_or_default(),
                    _ => String::new(),
                },
                "password" => match &r.data {
                    RecordData::Login { password, .. } => {
                        password.expose_utf8().unwrap_or_default()
                    }
                    _ => String::new(),
                },
                "secret_key" => match &r.data {
                    RecordData::Api { secret_key, .. } => {
                        secret_key.expose_utf8().unwrap_or_default()
                    }
                    RecordData::Wallet { secret_key, .. } => {
                        secret_key.expose_utf8().unwrap_or_default()
                    }
                    _ => String::new(),
                },
                "totp_secret" => match &r.data {
                    RecordData::Totp { secret, .. } => base32::encode(
                        base32::Alphabet::Rfc4648 { padding: false },
                        secret.as_slice(),
                    ),
                    _ => String::new(),
                },
                _ => String::new(),
            };
            row.push(val);
        }
        wtr.write_record(&row)?;
    }
    wtr.flush()?;
    Ok(())
}

fn recovery(cmd: RecoveryCommand, _config: &AppConfig) -> 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 split = if args.duress {
                shamir::split_secret_with_purpose(
                    secret.as_slice(),
                    args.threshold,
                    args.shares,
                    shamir::SharePurpose::Duress,
                )?
            } else {
                split_secret(secret.as_slice(), args.threshold, args.shares)?
            };
            for share in &split.shares {
                let (id, data) = share
                    .split_first()
                    .ok_or_else(|| anyhow!("invalid share structure"))?;
                let encoded = BASE64.encode(data);
                println!("{}-{}", id, encoded);
            }
            println!("# share-set-id {}", split.set_id_base32);
            println!("# record this share-set ID separately; combine will verify it");
            Ok(())
        }
        RecoveryCommand::Combine(args) => {
            // Basic rate-limiting to slow repeated combine attempts
            std::thread::sleep(std::time::Duration::from_millis(200));
            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 = if args.duress {
                shamir::combine_secret_with_purpose(
                    args.threshold,
                    &shares,
                    args.set_id.as_deref(),
                    shamir::SharePurpose::Duress,
                )?
            } else {
                combine_secret(args.threshold, &shares, args.set_id.as_deref())?
            };
            if args.raw {
                ensure_interactive_or_override(_config, "recovery combine --raw")?;
                write_bytes_tty(&secret, _config)?;
            } else {
                let b64 = BASE64.encode(&secret);
                write_line_tty(&b64, _config)?;
            }
            Ok(())
        }
    }
}

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

fn backup(cmd: BackupCommand, _config: &AppConfig) -> Result<()> {
    match cmd {
        BackupCommand::Verify { path } => backup_verify(&path),
    }
}

fn backup_verify(path: &Path) -> Result<()> {
    let bytes = std::fs::read(path)?;
    let file: VaultFile = match from_reader(bytes.as_slice()) {
        Ok(v) => v,
        Err(_) => bail!("failed to parse vault"),
    };
    let expected = read_integrity_sidecar(path)?;
    let actual = compute_public_integrity_tag(&bytes, &file.header.kem_public);
    if expected == actual {
        eprintln!("OK: integrity tag matches");
        Ok(())
    } else {
        bail!("integrity tag mismatch")
    }
}

fn totp_code(args: TotpCodeCommand, config: &AppConfig) -> Result<()> {
    ensure_interactive_or_override(config, "totp code")?;
    let (vault, _) = load_vault_with_prompt(config)?;
    let record = vault
        .get_ref(args.id)
        .ok_or_else(|| anyhow!("operation failed"))?;
    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!("operation failed"),
    };

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

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)?;
    if recovered.records.len() != 1 {
        bail!("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_paste(prompt: &str) -> Result<Sensitive> {
    eprintln!("{}", prompt);
    read_multiline(true)
}

fn read_multiline(_hidden: bool) -> Result<Sensitive> {
    let mut buffer = Zeroizing::new(Vec::new());
    io::stdin().read_to_end(&mut buffer)?;
    while buffer.last().copied() == Some(b'\n') {
        buffer.pop();
    }
    Ok(Sensitive::new_from_utf8(&buffer))
}

fn lock_handle(path: &Path) -> Result<RwLock<File>> {
    let lock_path = path.with_extension("lock");
    let file = OpenOptions::new()
        .create(true)
        .read(true)
        .write(true)
        .open(&lock_path)
        .context("failed to open lock file")?;
    Ok(RwLock::new(file))
}

fn read_vault_bytes(path: &Path) -> Result<Vec<u8>> {
    let lock = lock_handle(path)?;
    let _guard = lock.read()?;
    let meta = fs::metadata(path).context("failed to stat vault")?;
    if meta.len() > MAX_VAULT_FILE_BYTES {
        bail!("vault too large");
    }
    #[cfg(all(unix, target_os = "linux"))]
    use std::os::unix::fs::OpenOptionsExt;
    #[cfg(all(unix, target_os = "linux"))]
    let mut file = match OpenOptions::new()
        .read(true)
        .custom_flags(libc::O_NOATIME)
        .open(path)
    {
        Ok(f) => f,
        Err(_) => File::open(path).context("failed to open vault")?,
    };
    #[cfg(not(all(unix, target_os = "linux")))]
    let mut file = File::open(path).context("failed to open vault")?;
    let mut buf = Vec::new();
    file.read_to_end(&mut buf)?;
    Ok(buf)
}

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

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

fn write_vault(path: &Path, file: &VaultFile) -> Result<()> {
    let parent = path.parent().ok_or_else(|| anyhow!("invalid vault path"))?;
    fs::create_dir_all(parent)?;
    #[cfg(unix)]
    {
        use std::os::unix::fs::MetadataExt;
        let meta = fs::metadata(parent)?;
        let mode = meta.mode() & 0o777;
        if (mode & 0o022) != 0 {
            bail!("insecure vault directory permissions");
        }
        if meta.uid() != unsafe { libc::getuid() } {
            bail!("vault directory not owned by current user");
        }
    }
    #[cfg(windows)]
    {
        ensure_secure_dir_permissions(parent)?;
    }
    let mut lock = lock_handle(path)?;
    let _guard = lock.write()?;

    // Serialize to a buffer first so we can compute a public integrity sidecar.
    let mut buf = Vec::new();
    into_writer(file, &mut buf).context("failed to serialize vault")?;

    // Write to temporary file atomically.
    let mut tmp = NamedTempFile::new_in(parent)?;
    use std::io::Write as _;
    tmp.as_file_mut().write_all(&buf)?;
    tmp.as_file_mut().sync_all()?;
    #[cfg(unix)]
    {
        use std::os::unix::fs::PermissionsExt;
        tmp.as_file_mut()
            .set_permissions(fs::Permissions::from_mode(0o600))?;
    }
    tmp.persist(path)?;
    sync_dir(parent)?;

    // Compute and write public integrity sidecar (bit-rot detection)
    let tag = compute_public_integrity_tag(&buf, &file.header.kem_public);
    let _ = write_integrity_sidecar(path, tag);
    let _ = write_epoch_sidecar(path, file.header.epoch);
    Ok(())
}

#[cfg(windows)]
fn ensure_secure_dir_permissions(dir: &Path) -> Result<()> {
    use std::ffi::OsStr;
    use std::os::windows::ffi::OsStrExt;
    use windows_sys::Win32::Foundation::{CloseHandle, BOOL, HANDLE, PSID};
    use windows_sys::Win32::Security::Authorization::{
        GetAce, GetAclInformation, ACL, ACL_INFORMATION_CLASS, ACL_REVISION_INFORMATION,
        ACL_REVISION_INFORMATION as ACLRI, AceRevisionInformation, ACCESS_ALLOWED_ACE,
        ACCESS_ALLOWED_ACE_TYPE,
    };
    use windows_sys::Win32::Security::{
        CreateWellKnownSid, EqualSid, GetLengthSid, IsValidSid, WinAuthenticatedUserSid,
        WinWorldSid, OWNER_SECURITY_INFORMATION, DACL_SECURITY_INFORMATION,
    };
    use windows_sys::Win32::Security::{GetNamedSecurityInfoW, SE_FILE_OBJECT};

    unsafe {
        let mut wide: Vec<u16> = OsStr::new(dir.as_os_str())
            .encode_wide()
            .chain(std::iter::once(0))
            .collect();
        let mut owner_sid: PSID = std::ptr::null_mut();
        let mut dacl_ptr: *mut ACL = std::ptr::null_mut();
        let mut sd: *mut core::ffi::c_void = std::ptr::null_mut();
        let rc = GetNamedSecurityInfoW(
            wide.as_mut_ptr(),
            SE_FILE_OBJECT,
            OWNER_SECURITY_INFORMATION | DACL_SECURITY_INFORMATION,
            &mut owner_sid,
            std::ptr::null_mut(),
            &mut dacl_ptr,
            std::ptr::null_mut(),
            &mut sd,
        );
        if rc != 0 {
            bail!("failed to query directory ACL");
        }
        // Best effort: ensure DACL present and doesn't grant access to Everyone/Authenticated Users
        if !dacl_ptr.is_null() {
            // Build well-known SIDs
            let mut world_sid_buf = [0u8; 68];
            let mut world_len = world_sid_buf.len() as u32;
            let ok1 = CreateWellKnownSid(
                WinWorldSid as i32,
                std::ptr::null_mut(),
                world_sid_buf.as_mut_ptr() as PSID,
                &mut world_len,
            );
            let mut auth_sid_buf = [0u8; 68];
            let mut auth_len = auth_sid_buf.len() as u32;
            let ok2 = CreateWellKnownSid(
                WinAuthenticatedUserSid as i32,
                std::ptr::null_mut(),
                auth_sid_buf.as_mut_ptr() as PSID,
                &mut auth_len,
            );
            if ok1 == 0 || ok2 == 0 {
                bail!("failed to construct well-known SIDs");
            }
            // Iterate ACEs
            // Query ACE count by walking until GetAce fails; ACL info helpers are sparse in bindings
            let mut index: u32 = 0;
            loop {
                let mut ace_ptr: *mut core::ffi::c_void = std::ptr::null_mut();
                let ok: BOOL = GetAce(dacl_ptr, index as u32, &mut ace_ptr);
                if ok == 0 {
                    break;
                }
                let header = ace_ptr as *const u8;
                // ACE type at byte 0
                let ace_type = *header;
                if ace_type == ACCESS_ALLOWED_ACE_TYPE as u8 {
                    let ace = ace_ptr as *const ACCESS_ALLOWED_ACE;
                    // SidStart is a u32 offset and then SID data follows the ACCESS_ALLOWED_ACE struct
                    let sid_ptr = (&(*ace)).SidStart.as_ptr() as PSID;
                    if EqualSid(sid_ptr, world_sid_buf.as_mut_ptr() as PSID) != 0
                        || EqualSid(sid_ptr, auth_sid_buf.as_mut_ptr() as PSID) != 0
                    {
                        bail!("insecure vault directory permissions");
                    }
                }
                index += 1;
            }
        }
        // Free security descriptor if allocated
        if !sd.is_null() {
            let _ = windows_sys::Win32::Foundation::LocalFree(sd as isize);
        }
    }
    Ok(())
}

fn sync_dir(dir: &Path) -> Result<()> {
    #[cfg(unix)]
    {
        use std::os::unix::fs::OpenOptionsExt;
        let file = OpenOptions::new()
            .read(true)
            .custom_flags(libc::O_DIRECTORY)
            .open(dir)?;
        file.sync_all()?;
    }
    #[cfg(not(unix))]
    {
        // Windows directories cannot be opened for sync; best effort.
        let _ = dir;
    }
    Ok(())
}

fn integrity_sidecar_path(path: &Path) -> PathBuf {
    let mut p = path.to_path_buf();
    p.set_extension("int");
    p
}

fn compute_public_integrity_tag(vault_bytes: &[u8], kem_public_key: &[u8]) -> [u8; 32] {
    use blake3::derive_key;
    let key = derive_key("black-bag public integrity", kem_public_key);
    let mut hasher = blake3::Hasher::new_keyed(&key);
    hasher.update(vault_bytes);
    *hasher.finalize().as_bytes()
}

fn write_integrity_sidecar(path: &Path, tag: [u8; 32]) -> Result<()> {
    use std::io::Write;
    let sidecar = integrity_sidecar_path(path);
    let mut f = std::fs::File::create(&sidecar)?;
    writeln!(f, "{}", hex::encode(tag))?;
    Ok(())
}

fn read_integrity_sidecar(path: &Path) -> Result<[u8; 32]> {
    use std::io::Read;
    let sidecar = integrity_sidecar_path(path);
    let mut s = String::new();
    std::fs::File::open(&sidecar)?.read_to_string(&mut s)?;
    let bytes = hex::decode(s.trim())?;
    if bytes.len() != 32 {
        bail!("integrity tag wrong length");
    }
    let mut out = [0u8; 32];
    out.copy_from_slice(&bytes);
    Ok(out)
}

fn epoch_sidecar_path(path: &Path) -> PathBuf {
    let mut p = path.to_path_buf();
    p.set_extension("epoch");
    p
}

fn write_epoch_sidecar(path: &Path, epoch: u64) -> Result<()> {
    use std::io::Write;
    let sidecar = epoch_sidecar_path(path);
    let mut f = std::fs::File::create(&sidecar)?;
    writeln!(f, "{}", epoch)?;
    Ok(())
}

fn read_epoch_sidecar(path: &Path) -> Result<u64> {
    use std::io::Read;
    let sidecar = epoch_sidecar_path(path);
    let mut s = String::new();
    std::fs::File::open(&sidecar)?.read_to_string(&mut s)?;
    s.trim().parse::<u64>().map_err(|_| anyhow!("invalid epoch sidecar").into())
}

fn unlock_failure<E: Into<anyhow::Error>>(err: E) -> Error {
    let any = err.into();
    if std::env::var_os("BLACK_BAG_DEBUG").is_some() {
        Error::Anyhow(any.context("failed to unlock vault"))
    } else {
        // Do not leak internals in messages by default
        Error::Anyhow(anyhow!("failed to unlock vault"))
    }
}

fn constant_time_uuid_eq(a: &Uuid, b: &Uuid) -> bool {
    if a.as_bytes().len() != b.as_bytes().len() {
        return false;
    }
    let mut diff = 0u8;
    for (x, y) in a.as_bytes().iter().zip(b.as_bytes()) {
        diff |= x ^ y;
    }
    diff == 0
}

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))
    }

    #[test]
    fn kyber_sizes_match_fips203() -> Result<()> {
        // ML-KEM-1024 (Kyber1024) expected byte sizes
        const PK: usize = 1568;
        const SK: usize = 3168;
        const CT: usize = 1568;
        const SS: usize = 32;
        let (pk, sk) = kyber1024::keypair();
        assert_eq!(pk.as_bytes().len(), PK);
        assert_eq!(sk.as_bytes().len(), SK);
        let (ss, ct) = kyber1024::encapsulate(&pk);
        assert_eq!(ct.as_bytes().len(), CT);
        assert_eq!(ss.as_bytes().len(), SS);
        Ok(())
    }

    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("CorrectHorseBatteryStaple!7")?;
        let config = AppConfig::default();
        Vault::init(&vault_path, &pass, 32_768, &config, None)?;

        let mut vault = Vault::load(&vault_path, &pass, &config)?;
        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, &config)?;

        drop(vault);
        let vault = Vault::load(&vault_path, &pass, &config)?;
        let notes = vault.list(Some(RecordKind::Note), None, None, false);
        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("TotpPassphrase!7")?;
        let config = AppConfig::default();
        Vault::init(&vault_path, &pass, 32_768, &config, None)?;

        let secret_bytes = parse_totp_secret("JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP")?;
        let mut vault = Vault::load(&vault_path, &pass, &config)?;
        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, &config)?;

        drop(vault);
        let vault = Vault::load(&vault_path, &pass, &config)?;
        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")?,
        )
        .unwrap()
        .generate(59);
        assert_eq!(code, expected);

        cleanup();
        Ok(())
    }

    #[test]
    #[serial]
    fn vault_rotation_changes_wrapped_keys() -> Result<()> {
        let (_tmp, vault_path, pass) = prepare("RotateAllTheThings!7")?;
        let config = AppConfig::default();
        Vault::init(&vault_path, &pass, 32_768, &config, None)?;

        let mut vault = Vault::load(&vault_path, &pass, &config)?;
        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.clone();
        vault.rotate(&pass, Some(65_536), &config)?;
        vault.save(&pass, &config)?;
        let after = vault.file.header.sealed_dek.ciphertext.clone();
        assert_ne!(before, after);

        drop(vault);
        let vault = Vault::load(&vault_path, &pass, &config)?;
        let apis = vault.list(Some(RecordKind::Api), Some("read"), None, false);
        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 split = split_secret(secret, 3, 5)?;
        let recovered = combine_secret(3, &split.shares, Some(&split.set_id_base32))?;
        assert_eq!(recovered, secret);
        Ok(())
    }

    #[test]
    #[serial]
    fn header_mac_tamper_detected() -> Result<()> {
        let (_tmp, vault_path, pass) = prepare("HeaderTamper!7")?;
        let config = AppConfig::default();
        Vault::init(&vault_path, &pass, 32_768, &config, None)?;

        // Read, mutate header, write back without fixing header_mac
        let bytes = std::fs::read(&vault_path)?;
        let mut file: VaultFile = ciborium::de::from_reader(bytes.as_slice())
            .map_err(|e| anyhow!("cbor decode: {e}"))?;
        file.header.epoch = file.header.epoch.saturating_add(1);
        let mut out = Vec::new();
        ciborium::ser::into_writer(&file, &mut out).map_err(|e| anyhow!("cbor encode: {e}"))?;
        std::fs::write(&vault_path, &out)?;

        // Enable debug to surface message
        env::set_var("BLACK_BAG_DEBUG", "1");
        let _ = match Vault::load(&vault_path, &pass, &config) {
            Ok(_) => panic!("expected header integrity failure"),
            Err(e) => e,
        };
        cleanup();
        Ok(())
    }

    #[test]
    fn aead_wrong_aad_fails() -> Result<()> {
        let key = [7u8; 32];
        let blob = encrypt_blob(&key, b"hello", b"AAD1")?;
        let err = decrypt_blob(&key, &blob, b"AAD2").unwrap_err().to_string();
        assert!(err.to_ascii_lowercase().contains("decryption failed"));
        Ok(())
    }

    #[test]
    fn aead_bitflip_fails() -> Result<()> {
        let key = [9u8; 32];
        let mut blob = encrypt_blob(&key, b"world", b"AAD").unwrap();
        if !blob.ciphertext.is_empty() {
            blob.ciphertext[0] ^= 0x01;
        }
        let err = decrypt_blob(&key, &blob, b"AAD").unwrap_err().to_string();
        assert!(err.to_ascii_lowercase().contains("decryption failed"));
        Ok(())
    }

    #[test]
    fn encrypt_with_nonce_matches_reference() -> Result<()> {
        let key = [3u8; 32];
        let nonce = [5u8; 24];
        let ours = encrypt_blob_with_nonce(&key, b"kat", b"abc", nonce)?;
        let cipher = XChaCha20Poly1305::new(Key::from_slice(&key));
        let ct = cipher
            .encrypt(XNonce::from_slice(&nonce), Payload { msg: b"kat", aad: b"abc" })
            .map_err(|_| anyhow!("encryption failed"))?;
        assert_eq!(ours.ciphertext, ct);
        assert_eq!(ours.nonce, nonce);
        Ok(())
    }
}