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_mlkem::mlkem1024;
#[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, FormatMode, PolicyMode};
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,
        Some(cli.format),
        cli.quiet,
        cli.schema_version,
        cli.policy,
        cli.machine,
    );
    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::Record { command } => record(command, &app_config),
        Command::Scan { command } => scan(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(cmd) => migrate_vault_with(&cmd, &app_config),
        Command::Selftest => self_test(),
        Command::Completions(cmd) => completions(cmd),
        Command::HelpMan => help_man(),
        Command::Version => version_info(),
    }
}

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
}

#[derive(Args, Default)]
struct MigrateCommand {
    /// Target PQ KEM label (e.g., ml-kem-1024|kyber1024|next)
    #[arg(long)]
    pq: Option<String>,
    /// Target AEAD suite (e.g., xchacha20poly1305|aes256gcm)
    #[arg(long)]
    aead: Option<String>,
    /// Print what would change without rewriting
    #[arg(long, default_value_t = false)]
    dry_run: bool,
}

fn migrate_vault_with(cmd: &MigrateCommand, config: &AppConfig) -> Result<()> {
    let (mut vault, pass) = load_vault_with_prompt(config)?;
    if vault.file.version == VAULT_VERSION {
        // Accept future flags but no‑op if already latest
    }
    // Validate requested algorithms; this is future‑proofing only.
    if let Some(pq) = &cmd.pq {
        let pq_norm = pq.to_ascii_lowercase();
        if pq_norm != "kyber1024" && pq_norm != "ml-kem-1024" && pq_norm != "next" {
            bail!("unsupported pq target: {pq}");
        }
        if pq_norm == "next" {
            eprintln!("warning: pq=next reserved for future migration; no-op");
        }
        if pq_norm != "kyber1024" && pq_norm != "ml-kem-1024" {
            eprintln!("warning: pq target not currently implemented; no-op");
        }
    }
    if let Some(aead) = &cmd.aead {
        let aead_norm = aead.to_ascii_lowercase();
        if aead_norm != "xchacha20poly1305" && aead_norm != "aes256gcm" {
            bail!("unsupported aead target: {aead}");
        }
        if aead_norm == "aes256gcm" {
            eprintln!("warning: aes256gcm migration not implemented yet; no-op");
        }
    }

    if cmd.dry_run {
        println!("Dry-run: would migrate vault to version {}", VAULT_VERSION);
        if let Some(pq) = &cmd.pq { println!("PQ target: {} (validated/forward-compatible)", pq); }
        if let Some(aead) = &cmd.aead { println!("AEAD target: {} (validated/forward-compatible)", aead); }
        println!("Action: recompute header MAC and write .int/.epoch sidecars");
        return Ok(());
    }
    // Perform in-place metadata bump and MAC refresh
    vault.file.version = VAULT_VERSION;
    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,
    /// Output format for non-secret command results
    #[arg(long, value_enum, global = true, default_value_t = config::FormatMode::Text)]
    format: config::FormatMode,
    /// Suppress warnings and non-essential notices
    #[arg(long, global = true, default_value_t = false, alias = "no-banner")]
    quiet: bool,
    /// JSON schema version for machine-readable output
    #[arg(long, global = true)]
    schema_version: Option<u32>,
    /// Passphrase policy for new/changed secrets
    #[arg(long, value_enum, global = true)]
    policy: Option<config::PolicyMode>,
    /// Machine mode: force quiet JSON for non-secret outputs
    #[arg(long, global = true, default_value_t = false)]
    machine: 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,
    },
    /// Record maintenance
    Record {
        #[command(subcommand)]
        command: RecordCommand,
    },
    /// Backup utilities
    Backup {
        #[command(subcommand)]
        command: BackupCommand,
    },
    /// Scan for weak/duplicate passwords (offline)
    Scan {
        #[command(subcommand)]
        command: ScanCommand,
    },
    /// 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(MigrateCommand),
    /// Run embedded self-tests
    Selftest,
    /// Generate shell completion scripts
    Completions(CompletionsCommand),
    /// Print a man page to stdout
    HelpMan,
    /// Print extended version and feature set
    Version,
}

#[derive(Args)]
struct CompletionsCommand {
    /// Target shell
    #[arg(value_enum)]
    shell: clap_complete::Shell,
}

#[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>,
    /// Print what would be written without creating files
    #[arg(long, default_value_t = false)]
    dry_run: bool,
}

#[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,
    /// Time-to-live in seconds before clearing clipboard (used with --clipboard)
    #[arg(long)]
    clipboard_ttl: Option<u64>,
    /// Emit an otpauth:// URI for TOTP records
    #[arg(long, default_value_t = false)]
    otpauth: bool,
    /// Print an ASCII QR for the otpauth:// URI (requires --confirm-qr)
    #[arg(long, default_value_t = false)]
    qr: bool,
    /// Explicit confirmation to print QR codes in terminal
    #[arg(long, default_value_t = false)]
    confirm_qr: 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(Subcommand)]
enum RecordCommand {
    /// Edit record metadata (title, tags, notes)
    Edit(RecordEditCommand),
    /// Delete a record by UUID
    Delete(RecordDeleteCommand),
}

#[derive(Args, Default)]
struct RecordEditCommand {
    /// Record UUID to edit
    id: Uuid,
    /// Set title (empty to clear)
    #[arg(long)]
    title: Option<String>,
    /// Add tags (comma-separated)
    #[arg(long, value_delimiter = ',')]
    add_tag: Vec<String>,
    /// Remove tags (comma-separated)
    #[arg(long, value_delimiter = ',')]
    rm_tag: Vec<String>,
    /// Set metadata notes (empty to clear)
    #[arg(long)]
    notes: Option<String>,
}

#[derive(Args, Default)]
struct RecordDeleteCommand {
    /// Record UUID to delete
    id: Uuid,
    /// Do not prompt for confirmation
    #[arg(long, default_value_t = false)]
    force: bool,
}

#[derive(Subcommand)]
enum ScanCommand {
    /// Analyze passwords for weakness and duplication
    Passwords(ScanPasswordsCommand),
}

#[derive(Args, Default)]
struct ScanPasswordsCommand {
    /// Report duplicate passwords across records
    #[arg(long, default_value_t = true)]
    duplicates: bool,
    /// Report very weak passwords (zxcvbn score < 3)
    #[arg(long, default_value_t = true)]
    weak: bool,
}

#[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,
    /// Print only the header row for the selected kind
    #[arg(long, default_value_t = false)]
    schema: bool,
}

#[derive(Subcommand)]
enum RecoveryCommand {
    /// Split a secret into Shamir shares
    Split(RecoverySplitCommand),
    /// Combine Shamir shares back into the original secret
    Combine(RecoveryCombineCommand),
    /// Verify a set of shares without emitting the secret
    Verify(RecoveryVerifyCommand),
    /// Diagnose share-set format and health
    Doctor(RecoveryDoctorCommand),
}

#[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,
    /// Print an ASCII QR for each share token (requires --confirm-qr)
    #[arg(long, default_value_t = false)]
    qr: bool,
    /// Explicit confirmation to print QR codes to terminal
    #[arg(long, default_value_t = false)]
    confirm_qr: bool,
    /// Append a short Base32 Crockford checksum as a trailing comment
    #[arg(long, default_value_t = false)]
    with_checksum: 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(Args)]
struct RecoveryVerifyCommand {
    /// Reconstruction threshold (usually matches value used during split)
    #[arg(long)]
    threshold: u8,
    /// Comma-separated list of shares (e.g., 1-<base64>[ # chk: ...],2-<base64>)
    #[arg(long)]
    shares: String,
    /// Share-set ID printed during split (base32)
    #[arg(long)]
    set_id: Option<String>,
    /// Use duress channel
    #[arg(long, default_value_t = false)]
    duress: bool,
}

#[derive(Args)]
struct RecoveryDoctorCommand {
    /// Reconstruction threshold
    #[arg(long)]
    threshold: u8,
    /// Comma-separated list of shares
    #[arg(long)]
    shares: String,
    /// Share-set ID, if available
    #[arg(long)]
    set_id: Option<String>,
    /// 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),
    /// Diagnose TOTP drift and parameters for a record
    Doctor(TotpDoctorCommand),
}

#[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 TotpDoctorCommand {
    /// Record UUID containing the TOTP secret
    id: Uuid,
    /// Optional reference Unix time to compare with system clock
    #[arg(long)]
    ref_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,
        /// Optional Ed25519 public key to verify detached signature
        #[arg(long)]
        pub_key: Option<std::path::PathBuf>,
    },
    /// Sign the integrity tag with an Ed25519 key (writes .int.sig)
    Sign {
        #[arg(long)]
        path: std::path::PathBuf,
        /// Path to Ed25519 secret key (64-byte hex or base64)
        #[arg(long)]
        key: std::path::PathBuf,
        /// Optionally write the derived public key to this path
        #[arg(long)]
        pub_out: Option<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) = mlkem1024::keypair();
    let (shared_key, kem_ct) = mlkem1024::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_mac_mismatch");
                }
            }

            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 = mlkem1024::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) = mlkem1024::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) = mlkem1024::keypair();
    let (shared_key, kem_ct) = mlkem1024::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 the KEK derived above
        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-mlkem provides from_bytes constructors; validate sizes via constructor errors
fn expect_pk(data: &[u8]) -> Result<mlkem1024::PublicKey> {
    mlkem1024::PublicKey::from_bytes(data).map_err(|_| anyhow!("invalid public key length").into())
}

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

fn expect_ct(data: &[u8]) -> Result<mlkem1024::Ciphertext> {
    mlkem1024::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!("aead_auth_fail"))?;
    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>> {
    // Proactively print prompt to stderr for PTY/expect compatibility, then read silently
    {
        use std::io::Write as _;
        let _ = io::stderr().write_all(prompt.as_bytes());
        let _ = io::stderr().flush();
    }
    match prompt_password("") {
        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, policy: PolicyMode, quiet: bool) -> Result<()> {
    use unicode_normalization::UnicodeNormalization;
    let norm: String = passphrase.nfkc().collect();
    let (min_len, min_score) = match policy {
        PolicyMode::Moderate => (14usize, 3u8),
        PolicyMode::Strict => (18usize, 4u8),
    };
    let length = norm.chars().count();
    if length < min_len {
        bail!(
            "passphrase_policy_violation: requires >= {min_len} characters (got {length})"
        );
    }
    // 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_policy_violation: too common");
    }
    let unique: std::collections::HashSet<char> = norm.chars().collect();
    if unique.len() < 6 {
        bail!("passphrase_policy_violation: too few unique characters");
    }
    let estimate = zxcvbn(&norm, &[])
        .map_err(|err| anyhow!("failed to evaluate passphrase strength: {err}"))?;
    let score = estimate.score();
    if score < min_score {
        let guesses_log10 = estimate.guesses_log10();
        let entropy_bits = (guesses_log10 * 3.321_928_094_887_362).round();
        if !quiet {
            if let Some(fb) = estimate.feedback() {
                if let Some(w) = fb.warning() {
                    eprintln!("warning: {}", w);
                }
                for s in fb.suggestions() {
                    eprintln!("suggestion: {}", s);
                }
            }
            eprintln!(
                "policy {} requires score >= {} (got {}), ~{} bits entropy.",
                match policy { PolicyMode::Moderate => "moderate", PolicyMode::Strict => "strict" },
                min_score,
                score,
                entropy_bits as i64,
            );
        }
        bail!("passphrase_policy_violation: insufficient strength (score {score})");
    }
    Ok(())
}

fn init_vault(cmd: InitCommand, config: &AppConfig) -> Result<()> {
    let path = vault_path_with_cfg(config)?;
    if cmd.dry_run {
        let lanes = if let Some(l) = &cmd.argon_lanes { l.clone() } else { "auto".into() };
        println!("Dry-run: would initialize vault at {}", path.display());
        println!("Argon2 mem={} KiB, lanes={}, time={}", cmd.mem_kib, lanes, DEFAULT_TIME_COST);
        println!("Files: {} (.int + .epoch sidecars)", path.display());
        return Ok(());
    }
    let pass1 = prompt_passphrase("Master passphrase: ", config)?;
    ensure_passphrase_strength(pass1.as_str(), config.policy, config.quiet)?;
    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,
    );
    match config.format {
        FormatMode::Text => {
            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(())
        }
        FormatMode::Json => {
            let items: Vec<serde_json::Value> = list
                .iter()
                .map(|r| {
                    serde_json::json!({
                        "id": r.id,
                        "kind": format!("{}", r.kind()),
                        "title": r.title,
                        "tags": r.tags,
                        "summary": r.data.summary_text(),
                    })
                })
                .collect();
            let payload = serde_json::json!({
                "schema": config.schema_version.to_string(),
                "items": items,
            });
            println!("{}", payload);
            Ok(())
        }
        FormatMode::Ndjson => {
            for r in list {
                let line = serde_json::json!({
                    "schema": config.schema_version.to_string(),
                    "id": r.id,
                    "kind": format!("{}", r.kind()),
                    "title": r.title,
                    "tags": r.tags,
                    "summary": r.data.summary_text(),
                });
                println!("{}", line);
            }
            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");
                    }
                    let ttl = cmd.clipboard_ttl.unwrap_or(20);
                    copy_primary_secret_to_clipboard(record, config, ttl)?;
                    eprintln!(
                        "Copied to clipboard; it will be cleared in {}s. Clipboard is a trap.",
                        ttl
                    );
                }
                #[cfg(not(feature = "clipboard"))]
                {
                    bail!("clipboard support disabled at build time");
                }
            } else if cmd.otpauth {
                // Only valid for TOTP records
                match &record.data {
                    RecordData::Totp { issuer, account, secret, digits, step, algorithm, .. } => {
                        let secret_b32 = base32::encode(base32::Alphabet::Rfc4648 { padding: false }, secret.as_slice());
                        let uri = build_otpauth_uri(
                            issuer.as_deref().unwrap_or(""),
                            account.as_deref().unwrap_or(""),
                            &secret_b32,
                            *digits, *step, *algorithm,
                        );
                        match config.emit {
                            EmitMode::Tty => {
                                write_line_tty(&uri, config)?;
                                if cmd.qr {
                                    if !cmd.confirm_qr { bail!("printing QR requires --confirm-qr acknowledgment"); }
                                    output::print_qr_to_tty(&uri, config)?;
                                }
                            }
                            EmitMode::Json | EmitMode::Stdout => {
                                if !config.unsafe_stdout { bail!("--otpauth with non-TTY emit requires --unsafe-stdout"); }
                                let payload = json!({
                                    "schema": config.schema_version.to_string(),
                                    "otpauth": uri,
                                });
                                println!("{}", payload);
                            }
                        }
                        return Ok(())
                    }
                    _ => bail!("otpauth only supported for TOTP records"),
                }
            } 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, ttl_secs: u64) -> 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(ttl_secs));
        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(), config.policy, config.quiet)?;
    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 path = vault_path_with_cfg(config)?;
    let (vault, _) = load_vault_with_prompt(config)?;
    let stats = vault.stats();
    let header_mac_verified = vault.file.header.header_mac.is_some();

    let mut critical = Vec::new();
    let mut warnings = Vec::new();

    if let Some(parent) = path.parent() {
        #[cfg(unix)]
        {
            use std::os::unix::fs::MetadataExt;
            if let Ok(meta) = fs::metadata(parent) {
                let mode = meta.mode() & 0o777;
                if (mode & 0o022) != 0 {
                    critical.push("vault directory permissions are too broad");
                }
                if meta.uid() != unsafe { libc::getuid() } {
                    critical.push("vault directory not owned by current user");
                }
            }
        }
        #[cfg(windows)]
        {
            if let Err(_) = ensure_secure_dir_permissions(parent) {
                warnings.push("vault directory ACLs may be too permissive");
            }
        }
    }

    let int_path = integrity_sidecar_path(&path);
    if !int_path.exists() {
        warnings.push("integrity sidecar (.int) missing; run backup verify or save vault again");
    }

    if let Ok(meta) = fs::metadata(&path) {
        if meta.len() > MAX_VAULT_FILE_BYTES {
            critical.push("vault file size exceeds sanity threshold");
        }
    }

    #[cfg(feature = "mlock")]
    {
        let probe = [0u8; 32];
        match crate::memory::try_lock_slice(&probe, false) {
            Ok(_) => {}
            Err(_) => warnings.push("mlock unavailable; enable caps/limits or omit --require-mlock"),
        }
    }

    let mut swap = "unknown".to_string();
    #[cfg(target_os = "linux")]
    {
        if let Ok(s) = std::fs::read_to_string("/proc/meminfo") {
            if let Some(line) = s.lines().find(|l| l.starts_with("SwapTotal:")) {
                swap = line.trim().to_string();
            }
        }
    }
    #[cfg(target_os = "macos")]
    {
        if let Ok(out) = std::process::Command::new("/usr/sbin/sysctl").args(["vm.swapusage"]).output() {
            if out.status.success() {
                swap = String::from_utf8_lossy(&out.stdout).trim().to_string();
            }
        }
    }

    let mut rng_ok = true;
    let mut buf = [0u8; 16];
    if let Err(_) = OsRng.try_fill_bytes(&mut buf) { rng_ok = false; critical.push("OS RNG unavailable"); }

    let ready = critical.is_empty();

    if cmd.json || matches!(config.format, FormatMode::Json | FormatMode::Ndjson) {
        let payload = json!({
            "schema": config.schema_version.to_string(),
            "ready": ready,
            "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,
            "swap": swap,
            "rng": if rng_ok { "ok" } else { "fail" },
            "warnings": warnings,
            "critical": critical,
        });
        println!("{}", payload);
    } else {
        println!("status: {}", if ready { "ready" } else { "issues" });
        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)" }
        );
        println!("swap: {}", swap);
        if !warnings.is_empty() { eprintln!("warnings: {}", warnings.join("; ")); }
        if !critical.is_empty() { eprintln!("critical: {}", critical.join("; ")); }
    }

    if ready { Ok(()) } else { bail!("doctor found critical issues") }
}

fn completions(cmd: CompletionsCommand) -> Result<()> {
    use clap::CommandFactory;
    let mut command = Cli::command();
    let bin = command.get_name().to_string();
    clap_complete::generate(cmd.shell, &mut command, bin, &mut std::io::stdout());
    Ok(())
}

fn help_man() -> Result<()> {
    use clap::CommandFactory;
    let command = Cli::command();
    let man = clap_mangen::Man::new(command);
    let mut out: Vec<u8> = Vec::new();
    man.render(&mut out)?;
    print!("{}", String::from_utf8_lossy(&out));
    Ok(())
}

fn version_info() -> Result<()> {
    println!("black-bag {}", env!("CARGO_PKG_VERSION"));
    println!("schema: 1");
    println!(
        "pqc: {}",
        if cfg!(feature = "pq") { "on (ml-kem-1024)" } else { "off" }
    );
    println!("aead: xchacha20poly1305");
    println!("argon2id: time=10 lanes>=4 (auto up to 8)");
    println!("features:{}{}{}{}",
        if cfg!(feature = "mlock") { " mlock" } else { "" },
        if cfg!(feature = "tui") { " tui" } else { "" },
        if cfg!(feature = "agent-keychain") { " agent-keychain" } else { "" },
        if cfg!(feature = "clipboard") { " clipboard" } else { "" },
    );
    Ok(())
}

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

fn record(cmd: RecordCommand, config: &AppConfig) -> Result<()> {
    match cmd {
        RecordCommand::Edit(args) => record_edit(args, config),
        RecordCommand::Delete(args) => record_delete(args, config),
    }
}

fn scan(cmd: ScanCommand, config: &AppConfig) -> Result<()> {
    match cmd {
        ScanCommand::Passwords(args) => scan_passwords(args, config),
    }
}

fn scan_passwords(args: ScanPasswordsCommand, config: &AppConfig) -> Result<()> {
    let (vault, _pass) = load_vault_with_prompt(config)?;
    use std::collections::HashMap;
    let mut dup_map: HashMap<u64, Vec<Uuid>> = HashMap::new();
    let mut weak: Vec<(Uuid, u8)> = Vec::new();
    for r in vault.list(None, None, None, true) {
        if let RecordData::Login { password, .. } = &r.data {
            let s = match password.expose_utf8() { Ok(v) => v, Err(_) => continue };
            if args.weak {
                if let Ok(z) = zxcvbn(&s, &[]) {
                    if z.score() < 3 { weak.push((r.id, z.score())); }
                }
            }
            if args.duplicates {
                let mut h = blake3::Hasher::new();
                h.update(s.as_bytes());
                let mut key = [0u8;8];
                key.copy_from_slice(&h.finalize().as_bytes()[..8]);
                let k = u64::from_le_bytes(key);
                dup_map.entry(k).or_default().push(r.id);
            }
        }
    }
    if args.duplicates { dup_map.retain(|_, v| v.len() > 1); }

    if matches!(config.format, FormatMode::Json | FormatMode::Ndjson) {
        let dups: Vec<_> = dup_map.values().map(|ids| {
            json!({ "count": ids.len(), "ids": ids })
        }).collect();
        let payload = json!({
            "schema": config.schema_version.to_string(),
            "duplicates": dups,
            "weak": weak.iter().map(|(id,score)| json!({"id": id, "score": score})).collect::<Vec<_>>()
        });
        println!("{}", payload);
    } else {
        if args.duplicates {
            if dup_map.is_empty() { println!("duplicates: none"); } else {
                println!("duplicates:");
                for ids in dup_map.values() {
                    println!("- {} records share a password: {}", ids.len(), ids.iter().map(|i| i.to_string()).collect::<Vec<_>>().join(","));
                }
            }
        }
        if args.weak {
            if weak.is_empty() { println!("weak: none"); } else {
                println!("weak (score<3): {} records", weak.len());
                for (id, score) in weak { println!("- {} score={}", id, score); }
            }
        }
    }
    Ok(())
}

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() {
        match args.kind {
            Some(RecordKind::Contact) => vec!["id","kind","title","full_name","emails","phones","notes"],
            Some(RecordKind::Id) => vec!["id","kind","title","id_type","name_on_doc","number","issuing_country","expiry","notes"],
            Some(RecordKind::Wifi) => vec!["id","kind","title","ssid","security","location","summary"],
            Some(RecordKind::Api) => vec!["id","kind","title","service","environment","access_key","scopes","summary"],
            Some(RecordKind::Ssh) => vec!["id","kind","title","label","comment","summary"],
            Some(RecordKind::Pgp) => vec!["id","kind","title","label","fingerprint","summary"],
            _ => vec!["id","kind","title","tags","summary"],
        }.into_iter().map(|s| s.to_string()).collect()
    } 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)?;
    if args.schema {
        wtr.flush()?;
        return Ok(());
    }
    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(),
                "notes" => r.metadata_notes.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(),
                },
                "full_name" => match &r.data { RecordData::Contact { full_name, .. } => full_name.clone(), _ => String::new() },
                "emails" => match &r.data { RecordData::Contact { emails, .. } => if emails.is_empty() { String::new() } else { emails.join(",") }, _ => String::new() },
                "phones" => match &r.data { RecordData::Contact { phones, .. } => if phones.is_empty() { String::new() } else { phones.join(",") }, _ => String::new() },
                "id_type" => match &r.data { RecordData::Id { id_type, .. } => id_type.clone().unwrap_or_default(), _ => String::new() },
                "name_on_doc" => match &r.data { RecordData::Id { name_on_doc, .. } => name_on_doc.clone().unwrap_or_default(), _ => String::new() },
                "number" => match &r.data { RecordData::Id { number, .. } => number.clone().unwrap_or_default(), _ => String::new() },
                "issuing_country" => match &r.data { RecordData::Id { issuing_country, .. } => issuing_country.clone().unwrap_or_default(), _ => String::new() },
                "expiry" => match &r.data { RecordData::Id { expiry, .. } => expiry.clone().unwrap_or_default(), _ => String::new() },
                "service" => match &r.data { RecordData::Api { service, .. } => service.clone().unwrap_or_default(), _ => String::new() },
                "environment" => match &r.data { RecordData::Api { environment, .. } => environment.clone().unwrap_or_default(), _ => String::new() },
                "access_key" => match &r.data { RecordData::Api { access_key, .. } => access_key.clone().unwrap_or_default(), _ => String::new() },
                "scopes" => match &r.data { RecordData::Api { scopes, .. } => if scopes.is_empty() { String::new() } else { scopes.join(",") }, _ => String::new() },
                "ssid" => match &r.data { RecordData::Wifi { ssid, .. } => ssid.clone().unwrap_or_default(), _ => String::new() },
                "security" => match &r.data { RecordData::Wifi { security, .. } => security.clone().unwrap_or_default(), _ => String::new() },
                "location" => match &r.data { RecordData::Wifi { location, .. } => location.clone().unwrap_or_default(), _ => String::new() },
                "label" => match &r.data { RecordData::Ssh { label, .. } | RecordData::Pgp { label, .. } => label.clone().unwrap_or_default(), _ => String::new() },
                "comment" => match &r.data { RecordData::Ssh { comment, .. } => comment.clone().unwrap_or_default(), _ => String::new() },
                "fingerprint" => match &r.data { RecordData::Pgp { fingerprint, .. } => fingerprint.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 record_edit(cmd: RecordEditCommand, config: &AppConfig) -> Result<()> {
    let (mut vault, pass) = load_vault_with_prompt(config)?;
    let rec = vault.get(cmd.id).ok_or_else(|| anyhow!("record not found"))?;
    if let Some(t) = cmd.title {
        if t.is_empty() { rec.title = None; } else {
            if t.len() > MAX_TITLE_LEN { bail!("title too long"); }
            rec.title = Some(t);
        }
    }
    if let Some(n) = cmd.notes {
        if n.is_empty() { rec.metadata_notes = None; } else {
            if n.len() > MAX_NOTE_BYTES { bail!("notes too long"); }
            rec.metadata_notes = Some(n);
        }
    }
    if !cmd.add_tag.is_empty() {
        for tag in cmd.add_tag {
            let tag = tag.trim().to_string();
            if tag.is_empty() { continue; }
            if tag.len() > MAX_TAG_LEN { bail!("tag too long"); }
            if rec.tags.len() >= MAX_TAGS_PER_RECORD { bail!("too many tags"); }
            if !rec.tags.iter().any(|t| t.eq_ignore_ascii_case(&tag)) {
                rec.tags.push(tag);
            }
        }
    }
    if !cmd.rm_tag.is_empty() {
        rec.tags.retain(|t| !cmd.rm_tag.iter().any(|r| t.eq_ignore_ascii_case(r)));
    }
    rec.updated_at = Utc::now();
    vault.save(&pass, config)?;
    println!("Record updated");
    Ok(())
}

fn record_delete(cmd: RecordDeleteCommand, config: &AppConfig) -> Result<()> {
    let (mut vault, pass) = load_vault_with_prompt(config)?;
    if !cmd.force {
        ensure_interactive_or_override(config, "record delete")?;
        eprintln!("Type DELETE to confirm deletion of {}:", cmd.id);
        let mut line = String::new();
        io::stdin().read_line(&mut line)?;
        if line.trim() != "DELETE" { bail!("deletion aborted"); }
    }
    if let Some(idx) = vault.find_index(&cmd.id) {
        vault.payload.records.remove(idx);
        vault.save(&pass, config)?;
        println!("Record deleted");
        Ok(())
    } else {
        bail!("record not found")
    }
}

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);
                let token = format!("{}-{}", id, encoded);
                if args.with_checksum {
                    let chk = short_crockford_checksum(token.as_bytes());
                    println!("{}  # chk: {}", token, chk);
                } else {
                    println!("{}", token);
                }
                if args.qr {
                    if !args.confirm_qr { bail!("printing QR requires --confirm-qr acknowledgment"); }
                    output::print_qr_to_tty(&token, _config)?;
                }
            }
            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())
            {
                // strip trailing comments/whitespace
                let token = part
                    .split_whitespace()
                    .next()
                    .unwrap_or("")
                    .split('#')
                    .next()
                    .unwrap_or("");
                let (id, data) = token
                    .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(())
        }
        RecoveryCommand::Verify(args) => {
            std::thread::sleep(std::time::Duration::from_millis(100));
            if args.threshold == 0 { bail!("threshold must be at least 1"); }
            let shares = parse_shares_input(&args.shares)?;
            let purpose = if args.duress { shamir::SharePurpose::Duress } else { shamir::SharePurpose::Normal };
            let status = shamir::audit_shares(args.threshold, &shares, args.set_id.as_deref(), purpose)?;
            let out = match status {
                shamir::AuditStatus::Ok | shamir::AuditStatus::LegacyOnly => "OK",
                shamir::AuditStatus::Mismatch => "mismatch",
                shamir::AuditStatus::Tamper | shamir::AuditStatus::Mixed => "tamper",
            };
            println!("{}", out);
            Ok(())
        }
        RecoveryCommand::Doctor(args) => {
            let shares = parse_shares_input(&args.shares)?;
            let purpose = if args.duress { shamir::SharePurpose::Duress } else { shamir::SharePurpose::Normal };
            let status = shamir::audit_shares(args.threshold, &shares, args.set_id.as_deref(), purpose)?;
            match status {
                shamir::AuditStatus::LegacyOnly => {
                    eprintln!("Detected legacy shares (unauthenticated). Action: re-split to authenticated shares.");
                }
                shamir::AuditStatus::Mixed => {
                    eprintln!("Detected mix of legacy and authenticated shares. Action: re-split entire set; do not combine.");
                }
                shamir::AuditStatus::Mismatch => {
                    eprintln!("Share-set ID mismatch. Action: ensure all shares belong to the same set; re-issue as needed.");
                }
                shamir::AuditStatus::Tamper => {
                    eprintln!("Tamper or corruption detected. Action: check transcription/scans; re-issue affected shares.");
                }
                shamir::AuditStatus::Ok => {
                    eprintln!("OK: authenticated share-set; ready to combine.");
                }
            }
            Ok(())
        }
    }
}

fn parse_shares_input(input: &str) -> Result<Vec<Vec<u8>>> {
    let mut shares = Vec::new();
    for part in input.split(',').map(str::trim).filter(|s| !s.is_empty()) {
        let token = part
            .split_whitespace()
            .next()
            .unwrap_or("")
            .split('#')
            .next()
            .unwrap_or("");
        let (id, data) = token
            .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);
    }
    Ok(shares)
}

fn short_crockford_checksum(data: &[u8]) -> String {
    use blake3::Hasher;
    let mut h = Hasher::new();
    h.update(data);
    let digest = h.finalize();
    // Take 5 bytes (40 bits), encode Crockford base32 -> 8 chars
    let mut bytes = [0u8; 5];
    bytes.copy_from_slice(&digest.as_bytes()[..5]);
    base32::encode(base32::Alphabet::Crockford, &bytes)
}

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

fn totp_doctor(args: TotpDoctorCommand, config: &AppConfig) -> Result<()> {
    let (mut vault, _pass) = load_vault_with_prompt(config)?;
    let rec = vault.get(args.id).ok_or_else(|| anyhow!("record not found"))?;
    let (issuer, account, secret, digits, step, skew, algorithm) = match &rec.data {
        RecordData::Totp { issuer, account, secret, digits, step, skew, algorithm } =>
            (issuer.clone(), account.clone(), secret.clone(), *digits, *step, *skew, *algorithm),
        _ => bail!("record is not TOTP"),
    };
    let now = Utc::now().timestamp();
    let phase = (now.rem_euclid(step as i64)) as u64;
    let ttl = step.saturating_sub(phase);
    let base32_secret = base32::encode(base32::Alphabet::Rfc4648 { padding: false }, secret.as_slice());
    let uri = build_otpauth_uri(
        issuer.as_deref().unwrap_or(""),
        account.as_deref().unwrap_or(""),
        &base32_secret, digits, step, algorithm,
    );
    let drift = args.ref_time.map(|t| now.saturating_sub(t)).unwrap_or(0);
    if matches!(config.emit, EmitMode::Json | EmitMode::Stdout) {
        if !config.unsafe_stdout { bail!("totp doctor json requires --unsafe-stdout"); }
        let payload = json!({
            "schema": config.schema_version.to_string(),
            "now": now,
            "phase": phase,
            "ttl": ttl,
            "digits": digits,
            "step": step,
            "skew": skew,
            "algorithm": format!("{:?}", algorithm),
            "otpauth": uri,
            "drift": drift,
            "suggestion": if ttl < 2 { "time near boundary; if persistent, check NTP" } else { "ok" },
        });
        println!("{}", payload);
    } else {
        println!("now: {}", now);
        println!("phase: {} of {}", phase, step);
        println!("ttl: {}", ttl);
        println!("digits: {} step: {} skew: {} algo: {:?}", digits, step, skew, algorithm);
        println!("otpauth: {}", uri);
        if ttl < 2 { eprintln!("warning: time near boundary; if persistent, check NTP"); }
        if args.ref_time.is_some() { println!("drift: {}", drift); }
    }
    Ok(())
}

fn backup(cmd: BackupCommand, _config: &AppConfig) -> Result<()> {
    match cmd {
        BackupCommand::Verify { path, pub_key } => backup_verify(&path, pub_key.as_deref()),
        BackupCommand::Sign { path, key, pub_out } => backup_sign(&path, &key, pub_out.as_deref()),
    }
}

fn backup_verify(path: &Path, pub_key_path: Option<&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);
    eprintln!("note: this checks bit-rot, not authenticity; keep vault + .int paired");
    if expected != actual {
        bail!("integrity tag mismatch")
    }
    if let Some(pk) = pub_key_path {
        let sig = read_integrity_signature_sidecar(path)?;
        verify_integrity_signature(&expected, pk, &sig)?;
        eprintln!("OK: signature verified");
    } else {
        eprintln!("OK: integrity tag matches");
    }
    Ok(())
}

fn backup_sign(path: &Path, key_path: &Path, pub_out: Option<&Path>) -> Result<()> {
    use ed25519_dalek::{SigningKey, VerifyingKey, Signer};
    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 tag = match read_integrity_sidecar(path) {
        Ok(t) => t,
        Err(_) => {
            // compute fresh if missing
            let t = compute_public_integrity_tag(&bytes, &file.header.kem_public);
            let _ = write_integrity_sidecar(path, t);
            t
        }
    };
    let sk_bytes = read_key_bytes(key_path)?;
    let sk = if sk_bytes.len() == 32 {
        SigningKey::from_bytes(sk_bytes.as_slice().try_into().map_err(|_| anyhow!("invalid secret key length"))?)
    } else if sk_bytes.len() == 64 {
        SigningKey::from_keypair_bytes(sk_bytes.as_slice().try_into().map_err(|_| anyhow!("invalid secret key length"))?)
            .map_err(|_| anyhow!("invalid keypair bytes"))?
    } else {
        bail!("unsupported key size: expected 32 or 64 bytes")
    };
    let sig = sk.sign(&tag);
    write_integrity_signature_sidecar(path, sig.to_bytes())?;
    let vk: VerifyingKey = sk.verifying_key();
    if let Some(out) = pub_out {
        std::fs::write(out, hex::encode(vk.to_bytes()))?;
    }
    eprintln!("OK: wrote signature sidecar");
    Ok(())
}

fn read_key_bytes(path: &Path) -> Result<Vec<u8>> {
    let s = std::fs::read_to_string(path)?;
    let t = s.trim();
    let hex_ok = t.chars().all(|c| c.is_ascii_hexdigit());
    if hex_ok && (t.len() == 64 || t.len() == 128) {
        return Ok(hex::decode(t)?);
    }
    // try base64
    if let Ok(b) = BASE64.decode(t) { return Ok(b); }
    bail!("unrecognized key encoding (hex or base64)")
}

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

fn write_integrity_signature_sidecar(path: &Path, sig: [u8; 64]) -> Result<()> {
    use std::io::Write;
    let sidecar = integrity_signature_sidecar_path(path);
    let mut f = std::fs::File::create(&sidecar)?;
    writeln!(f, "{}", base64::engine::general_purpose::STANDARD.encode(sig))?;
    Ok(())
}

fn read_integrity_signature_sidecar(path: &Path) -> Result<[u8; 64]> {
    use std::io::Read;
    let sidecar = integrity_signature_sidecar_path(path);
    let mut s = String::new();
    let mut f = std::fs::File::open(&sidecar)
        .map_err(|_| anyhow!("signature sidecar missing; run backup sign --key <sk>"))?;
    f.read_to_string(&mut s)
        .map_err(|_| anyhow!("invalid signature sidecar"))?;
    let bytes = base64::engine::general_purpose::STANDARD
        .decode(s.trim())
        .map_err(|_| anyhow!("invalid signature sidecar"))?;
    if bytes.len() != 64 { bail!("invalid signature length"); }
    let mut out = [0u8; 64];
    out.copy_from_slice(&bytes);
    Ok(out)
}

fn verify_integrity_signature(tag: &[u8; 32], pub_key: &Path, sig: &[u8; 64]) -> Result<()> {
    use ed25519_dalek::{Signature, VerifyingKey, Verifier};
    let pk_bytes = read_key_bytes(pub_key)?;
    if pk_bytes.len() != 32 { bail!("invalid public key length; expected 32 bytes"); }
    let vk = VerifyingKey::from_bytes(pk_bytes.as_slice().try_into().unwrap())
        .map_err(|_| anyhow!("invalid public key"))?;
    let signature = Signature::from_bytes(sig);
    vk.verify(tag, &signature).map_err(|_| anyhow!("integrity signature verification failed").into())
}

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

#[cfg(feature = "fuzzing")]
pub fn fuzz_try_otpauth(bytes: &[u8]) {
    use std::borrow::Cow;
    let s = String::from_utf8_lossy(bytes);
    let input: Cow<str> = match &s {
        Cow::Borrowed(b) => Cow::Borrowed(*b),
        Cow::Owned(o) => Cow::Owned(o.replace('\0', "")),
    };
    let _ = parse_otpauth_uri(&input);
}

#[cfg(feature = "fuzzing")]
pub fn fuzz_try_parse_shares(bytes: &[u8]) {
    let s = String::from_utf8_lossy(bytes).to_string();
    let _ = parse_shares_input(&s);
}

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() {
        // In debug, expose the underlying error for testing/diagnostics
        Error::Anyhow(any)
    } 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 mlkem_sizes_match_fips203() -> Result<()> {
        // ML-KEM-1024 expected byte sizes
        const PK: usize = 1568;
        const SK: usize = 3168;
        const CT: usize = 1568;
        const SS: usize = 32;
        let (pk, sk) = mlkem1024::keypair();
        assert_eq!(pk.as_bytes().len(), PK);
        assert_eq!(sk.as_bytes().len(), SK);
        let (ss, ct) = mlkem1024::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 specific error message
        env::set_var("BLACK_BAG_DEBUG", "1");
        let err = match Vault::load(&vault_path, &pass, &config) {
            Ok(_) => panic!("expected header_mac_mismatch"),
            Err(e) => e.to_string(),
        };
        assert!(err.contains("header_mac_mismatch"));
        cleanup();
        Ok(())
    }

    #[test]
    #[serial]
    fn header_mac_field_corruptions() -> Result<()> {
        use ciborium::{de::from_reader as de, ser::into_writer as ser};
        let (_tmp, vault_path, pass) = prepare("HeaderFieldTamper!7")?;
        let config = AppConfig::default();
        Vault::init(&vault_path, &pass, 32_768, &config, None)?;

        let bytes = std::fs::read(&vault_path)?;
        let original: VaultFile = de(bytes.as_slice()).map_err(|e| anyhow!("cbor decode: {e}"))?;
        let mut cases: Vec<Box<dyn Fn(&mut VaultFile)>> = Vec::new();
        cases.push(Box::new(|h| h.header.created_at = h.header.created_at - chrono::TimeDelta::seconds(1)));
        cases.push(Box::new(|h| h.header.updated_at = h.header.updated_at + chrono::TimeDelta::seconds(1)));
        cases.push(Box::new(|h| h.header.argon.mem_cost_kib = h.header.argon.mem_cost_kib.saturating_add(1)));
        cases.push(Box::new(|h| h.header.argon.time_cost = h.header.argon.time_cost.saturating_add(1)));
        cases.push(Box::new(|h| h.header.argon.lanes = h.header.argon.lanes.saturating_add(1)));
        cases.push(Box::new(|h| h.header.argon.salt[0] ^= 0x01));
        cases.push(Box::new(|h| h.header.epoch = h.header.epoch.saturating_add(1)));
        cases.push(Box::new(|h| if !h.header.kem_public.is_empty() { h.header.kem_public[0] ^= 0x01 }));
        cases.push(Box::new(|h| if !h.header.kem_ciphertext.is_empty() { h.header.kem_ciphertext[0] ^= 0x01 }));
        cases.push(Box::new(|h| h.header.sealed_decapsulation.nonce[0] ^= 0x01));
        cases.push(Box::new(|h| if !h.header.sealed_decapsulation.ciphertext.is_empty() { h.header.sealed_decapsulation.ciphertext[0] ^= 0x01 }));
        cases.push(Box::new(|h| h.header.sealed_dek.nonce[0] ^= 0x01));
        cases.push(Box::new(|h| if !h.header.sealed_dek.ciphertext.is_empty() { h.header.sealed_dek.ciphertext[0] ^= 0x01 }));

        std::env::set_var("BLACK_BAG_DEBUG", "1");
        for mutate in cases.into_iter() {
            let mut tampered = original.clone();
            mutate(&mut tampered);
            let mut out = Vec::new();
            ser(&tampered, &mut out).map_err(|e| anyhow!("cbor encode: {e}"))?;
            std::fs::write(&vault_path, &out)?;
            let err = match Vault::load(&vault_path, &pass, &config) {
                Ok(_) => panic!("expected header_mac_mismatch"),
                Err(e) => e.to_string(),
            };
            assert!(err.contains("header_mac_mismatch"));
        }

        cleanup();
        Ok(())
    }

    #[test]
    #[serial]
    fn payload_corruption_yields_aead_error() -> Result<()> {
        use ciborium::{de::from_reader as de, ser::into_writer as ser};
        let (_tmp, vault_path, pass) = prepare("PayloadTamper!7")?;
        let config = AppConfig::default();
        Vault::init(&vault_path, &pass, 32_768, &config, None)?;
        // Add a small record so payload exists
        let mut vault = Vault::load(&vault_path, &pass, &config)?;
        vault.add_record(Record::new(RecordData::Note { body: Sensitive::from_string("x") }, None, vec![], None));
        vault.save(&pass, &config)?;
        drop(vault);

        let bytes = std::fs::read(&vault_path)?;
        let mut file: VaultFile = de(bytes.as_slice()).map_err(|e| anyhow!("cbor decode: {e}"))?;
        if !file.payload.ciphertext.is_empty() {
            file.payload.ciphertext[0] ^= 0x01;
        }
        let mut out = Vec::new();
        ser(&file, &mut out).map_err(|e| anyhow!("cbor encode: {e}"))?;
        std::fs::write(&vault_path, &out)?;
        std::env::set_var("BLACK_BAG_DEBUG", "1");
        let err = match Vault::load(&vault_path, &pass, &config) {
            Ok(_) => panic!("expected aead_auth_fail"),
            Err(e) => e.to_string(),
        };
        assert!(err.contains("aead_auth_fail"));
        cleanup();
        Ok(())
    }

    #[test]
    fn strict_policy_rejects_weak_on_init_check() {
        // Quiet to avoid noisy stderr during tests
        let err = ensure_passphrase_strength("shortpass", PolicyMode::Strict, true)
            .unwrap_err()
            .to_string();
        assert!(err.contains("passphrase_policy_violation"));
    }

    #[test]
    fn moderate_policy_accepts_reasonable_passphrase() -> Result<()> {
        ensure_passphrase_strength(
            "TrulyLongPassphrase#2025!alphaPHI",
            PolicyMode::Moderate,
            true,
        )?;
        Ok(())
    }

    #[test]
    fn doctor_fails_on_bad_dir_perms() -> Result<()> {
        use std::os::unix::fs::PermissionsExt;
        let tmp = tempfile::tempdir()?;
        let dir = tmp.path();
        // Create world-writable directory
        std::fs::set_permissions(dir, std::fs::Permissions::from_mode(0o777))?;
        let vault_path = dir.join("badperms.cbor");
        std::env::set_var("BLACK_BAG_VAULT_PATH", &vault_path);
        let config = AppConfig::default();
        // Doctor should report critical and fail before prompting
        let err = doctor(DoctorCommand { json: false }, &config).unwrap_err().to_string();
        std::env::remove_var("BLACK_BAG_VAULT_PATH");
        assert!(err.to_ascii_lowercase().contains("doctor"));
        Ok(())
    }

    use proptest::prelude::*;
    proptest! {
        #[test]
        fn header_mutations_fail_unlock(mem_cost in 32768u32..131072u32, t in 1u32..3u32, lanes in 4u32..9u32) {
            let (_tmp, vault_path, pass) = prepare("PropHeader!7").unwrap();
            let mut config = AppConfig::default();
            Vault::init(&vault_path, &pass, mem_cost, &config, Some(&lanes.to_string())).unwrap();
            let bytes = std::fs::read(&vault_path).unwrap();
            let mut file: VaultFile = from_reader(bytes.as_slice()).unwrap();
            match t % 5 {
                0 => file.header.argon.mem_cost_kib = file.header.argon.mem_cost_kib.saturating_add(1),
                1 => file.header.argon.time_cost = file.header.argon.time_cost.saturating_add(1),
                2 => file.header.argon.lanes = file.header.argon.lanes.saturating_add(1),
                3 => if !file.header.kem_public.is_empty() { file.header.kem_public[0] ^= 0x01 },
                _ => file.header.epoch = file.header.epoch.saturating_add(1),
            }
            let mut out = Vec::new();
            ciborium::ser::into_writer(&file, &mut out).unwrap();
            std::fs::write(&vault_path, &out).unwrap();
            std::env::set_var("BLACK_BAG_DEBUG", "1");
            let err = match Vault::load(&vault_path, &pass, &config) {
                Ok(_) => panic!("expected failure"),
                Err(e) => e.to_string(),
            };
            assert!(err.contains("header_mac_mismatch") || err.contains("aead_auth_fail"));
            std::env::remove_var("BLACK_BAG_DEBUG");
        }
    }

    #[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.contains("aead_auth_fail"));
        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.contains("aead_auth_fail"));
        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(())
    }

    #[test]
    fn print_header_mac_kat() -> Result<()> {
        use chrono::TimeZone;
        let header = VaultHeader {
            created_at: Utc.with_ymd_and_hms(2023, 1, 2, 3, 4, 5).unwrap(),
            updated_at: Utc.with_ymd_and_hms(2023, 1, 2, 3, 4, 6).unwrap(),
            epoch: 42,
            argon: ArgonState {
                mem_cost_kib: 32_768,
                time_cost: 10,
                lanes: 4,
                salt: {
                    let mut s = [0u8;32];
                    for (i,b) in s.iter_mut().enumerate() { *b = i as u8; }
                    s
                },
            },
            kem_public: vec![1,2,3,4],
            kem_ciphertext: vec![5,6,7],
            sealed_decapsulation: AeadBlob { nonce: [9u8;24], ciphertext: vec![10,11] },
            sealed_dek: AeadBlob { nonce: [12u8;24], ciphertext: vec![13,14,15] },
            header_mac: None,
        };
        let kek = [0xAAu8; 32];
        let mac = compute_header_mac(&header, &kek);
        assert_eq!(hex::encode(mac), "09fc2ba4d7078309d97386c469c0c0f395e57da6fea9e9ba23e3b692e6ea7a94");
        Ok(())
    }

    #[test]
    fn backup_sign_and_verify_happy_and_failures() -> Result<()> {
        use ed25519_dalek::SigningKey;
        use rand::rngs::OsRng;
        use rand::RngCore as _;
        // Prepare a vault
        let (_tmp, vault_path, pass) = prepare("BackupSign!7")?;
        let config = AppConfig::default();
        Vault::init(&vault_path, &pass, 32_768, &config, None)?;
        // Compute integrity sidecar
        let bytes = std::fs::read(&vault_path)?;
        let file: VaultFile = match from_reader(bytes.as_slice()) {
            Ok(v) => v,
            Err(_) => bail!("failed to parse vault"),
        };
        let tag = compute_public_integrity_tag(&bytes, &file.header.kem_public);
        write_integrity_sidecar(&vault_path, tag)?;
        // Generate key
        let mut seed = [0u8; 32];
        OsRng.fill_bytes(&mut seed);
        let sk = SigningKey::from_bytes(&seed);
        let sk_bytes = sk.to_keypair_bytes();
        let sk_path = vault_path.with_extension("sk");
        std::fs::write(&sk_path, hex::encode(sk_bytes))?;
        let pk_hex = hex::encode(sk.verifying_key().to_bytes());
        let pk_path = vault_path.with_extension("pk");
        std::fs::write(&pk_path, &pk_hex)?;
        // Sign
        backup_sign(&vault_path, &sk_path, None)?;
        // Verify OK
        backup_verify(&vault_path, Some(&pk_path))?;
        // Wrong signature
        let bad_sig_path = integrity_signature_sidecar_path(&vault_path);
        std::fs::write(&bad_sig_path, base64::engine::general_purpose::STANDARD.encode([0u8;64]))?;
        let err = backup_verify(&vault_path, Some(&pk_path)).unwrap_err().to_string();
        assert!(err.contains("signature"));
        // Missing signature sidecar
        std::fs::remove_file(&bad_sig_path)?;
        let err = read_integrity_signature_sidecar(&vault_path).unwrap_err().to_string();
        assert!(err.contains("signature sidecar missing"));
        Ok(())
    }
}