sefy 0.10.0

//! Command-line surface: what `sefy` accepts and what each option means.

use clap::{Args, Parser, Subcommand, ValueEnum};
use std::path::PathBuf;

/// An inconspicuous encrypted store for notes, credentials and files.
#[derive(Debug, Parser)]
#[command(name = "sefy", version, about, long_about = None)]
pub struct Cli {
    /// Vault file to work on; falls back to $SEFY_VAULT.
    ///
    /// There is deliberately no default path: a vault at a predictable
    /// location would be exactly the giveaway the format avoids.
    #[arg(
        long,
        short = 'f',
        global = true,
        env = "SEFY_VAULT",
        value_name = "FILE"
    )]
    pub vault: Option<PathBuf>,

    /// Read the master password from this environment variable.
    ///
    /// For scripts and CI. Passing a password as an argument is not supported:
    /// it would land in the shell history and in every process listing.
    #[arg(long, global = true, value_name = "VAR")]
    pub password_env: Option<String>,

    /// What to do. Omitted, sefy opens an interactive picker over the vault.
    #[command(subcommand)]
    pub command: Option<Command>,
}

/// What the user asked sefy to do.
#[derive(Debug, Subcommand)]
pub enum Command {
    /// Create a new vault.
    Init,

    /// Add an item to the vault.
    Add {
        #[command(subcommand)]
        kind: AddKind,
    },

    /// Copy a secret to the clipboard, or print it with --stdout.
    Get(GetArgs),

    /// Show an item without revealing its secret fields.
    Show {
        /// Item id, exact title, or text to search for.
        reference: String,
    },

    /// List items in the vault.
    Ls(ListArgs),

    /// Search items by text, kind and tags.
    Find(FindArgs),

    /// Change an item's title, contents or tags.
    Edit(EditArgs),

    /// Remove an item.
    Rm {
        /// Item id, exact title, or text to search for.
        reference: String,

        /// Do not ask for confirmation.
        #[arg(long, short = 'y')]
        yes: bool,
    },

    /// Write a stored file back to disk.
    Extract {
        /// Item id, exact title, or text to search for.
        reference: String,

        /// Where to write it; defaults to the stored filename in the current
        /// directory.
        #[arg(long, short = 'o', value_name = "PATH")]
        output: Option<PathBuf>,

        /// Overwrite the destination if it exists.
        #[arg(long)]
        force: bool,
    },

    /// List the tags in use.
    Tags,

    /// Generate a password or a passphrase and copy it to the clipboard.
    ///
    /// No vault is needed unless the result is kept with --save, which stores
    /// it as a new login in the same gesture.
    Gen(GenArgs),

    /// Open an item's site and copy its password to the clipboard.
    ///
    /// The two halves of signing in, in the order they are used: the browser
    /// loads while the password waits to be pasted.
    Open(OpenArgs),

    /// Copy a record's one-time password to the clipboard.
    ///
    /// With --set, store the key a site shows when two-factor sign-in is
    /// turned on first; with --qr, draw the key for a phone to scan.
    Otp(OtpArgs),

    /// Hand over a record's fields one at a time, in the order a form asks.
    ///
    /// A login gives its login, then its password, then a fresh one-time
    /// code: each goes to the clipboard, and Enter moves to the next.
    Fill(FillArgs),

    /// Show what and where this vault is, without revealing any of it.
    ///
    /// Counts, versions and the last transfer - never a title or a value. It
    /// answers the question asked after a new machine, a restore or a week
    /// away: is this the right file, is everything in it, and has it reached
    /// the other side lately.
    Status,

    /// Write the vault's contents out as plain, unencrypted JSON.
    Export {
        /// Where to write it; omit to print to stdout.
        #[arg(long, short = 'o', value_name = "PATH")]
        output: Option<PathBuf>,

        /// Required: acknowledge that this writes every secret in the clear.
        ///
        /// Export exists so a vault is never a trap, but the file it produces
        /// is exactly as sensitive as the vault — and unlike the vault, it
        /// protects nothing. A warning printed after the fact would be too
        /// late, so the acknowledgement comes first.
        #[arg(long)]
        i_know_this_writes_plaintext: bool,

        /// Overwrite the destination if it exists.
        #[arg(long)]
        force: bool,
    },

    /// Add the contents of an export to this vault.
    ///
    /// An entry the vault already holds under the same identity is skipped, so
    /// importing the same export twice does not duplicate it. Contents are
    /// never overwritten: an export may well be older than what is here, and
    /// bringing newer contents across is what `merge` is for.
    Import {
        /// Export file to read; omit to read from stdin.
        #[arg(value_name = "PATH")]
        input: Option<PathBuf>,
    },

    /// Fold another vault file into this one.
    ///
    /// For two copies that drifted apart: items missing here are copied across,
    /// newer contents from there replace older ones here, and an item changed
    /// on both sides is kept twice rather than resolved by guesswork. Nothing
    /// is ever deleted — "gone from there" and "added here" look identical from
    /// this side.
    Merge {
        /// The other vault file.
        #[arg(value_name = "FILE")]
        other: PathBuf,

        /// Read the other vault's password from this environment variable.
        ///
        /// Distinct from --password-env: a copy from another machine may well
        /// be under a different password, and reusing one variable for both
        /// would make that impossible to express.
        #[arg(long, value_name = "VAR")]
        other_password_env: Option<String>,
    },

    /// Replace the master password.
    ChangePassword {
        /// Read the *new* password from this environment variable.
        ///
        /// Distinct from --password-env, which carries the current one: with a
        /// single variable the "new" password would be the old one.
        #[arg(long, value_name = "VAR")]
        new_password_env: Option<String>,
    },

    /// Send this vault to the remote, replacing the copy there.
    ///
    /// The file that travels is the sealed one; the transport carrying it never
    /// sees the master password or a single item.
    Push(RemoteArgs),

    /// Fetch the remote copy and fold it into this vault.
    ///
    /// The two are merged rather than one replacing the other: items missing
    /// here are copied across, newer contents replace older ones, and an item
    /// changed on both sides is kept twice. Nothing local is deleted.
    Pull(PullArgs),

    /// Pull, then push: take what is at the remote, then publish the result.
    ///
    /// The everyday gesture on a machine that is one of several. The order is
    /// not a preference — pushing first would replace the remote copy with one
    /// that never saw its contents.
    Sync(PullArgs),

    /// Inspect the transports installed on this machine.
    Plugin {
        #[command(subcommand)]
        action: PluginAction,
    },

    /// Print a shell completion script.
    Completions {
        /// Shell to generate for.
        shell: clap_complete::Shell,
    },
}

/// Which transport to use, and what the remote copy is called.
#[derive(Debug, Args)]
pub struct RemoteArgs {
    /// Transport to use, by its short name; omit when only one is installed.
    ///
    /// There is no configuration file to record a default in — sefy keeps
    /// nothing on disk but the vault and its plugins — so the choice is either
    /// obvious or stated.
    #[arg(long, short = 'p', value_name = "NAME", env = "SEFY_TRANSPORT")]
    pub transport: Option<String>,

    /// What the remote copy is called.
    ///
    /// A transport needs some handle for the thing it stores, and the local
    /// file name is a poor one: a vault is deliberately named like anything
    /// else, and on a shared remote two machines' "notes.bak" would collide.
    #[arg(
        long,
        value_name = "NAME",
        env = "SEFY_REMOTE_NAME",
        default_value = "vault"
    )]
    pub name: String,
}

/// A pull or a sync: a transport, a remote name, and the remote's password.
#[derive(Debug, Args)]
pub struct PullArgs {
    #[command(flatten)]
    pub remote: RemoteArgs,

    /// Read the *remote* copy's master password from this environment variable.
    ///
    /// Only needed when the two differ. Unlike `merge`, which folds in a file
    /// from anywhere, a pull brings back a copy of *this* vault, and the same
    /// password is the ordinary case — so it is what sefy uses unless told
    /// otherwise here or with --ask-remote-password.
    #[arg(long, value_name = "VAR", conflicts_with = "ask_remote_password")]
    pub remote_password_env: Option<String>,

    /// Ask for the remote copy's password instead of reusing this vault's.
    #[arg(long)]
    pub ask_remote_password: bool,
}

/// What to do with plugins.
#[derive(Debug, Subcommand)]
pub enum PluginAction {
    /// List the plugins sefy can see, and say why any of them is unusable.
    List {
        /// Also print where sefy looked.
        #[arg(long)]
        paths: bool,
    },
}

/// The kind of item being added.
#[derive(Debug, Subcommand)]
pub enum AddKind {
    /// A free-form note.
    Note {
        /// What to call it.
        title: String,

        /// The text; omit to read it from stdin, or pass --editor.
        #[arg(long, short = 't', conflicts_with = "editor")]
        text: Option<String>,

        /// Write the note in $EDITOR.
        #[arg(long, short = 'e')]
        editor: bool,

        /// Tags to attach; repeat or separate with commas.
        #[arg(long, value_delimiter = ',')]
        tag: Vec<String>,
    },

    /// A login, its password and where it is used.
    #[command(alias = "credential")]
    Login {
        /// What to call it.
        title: String,

        /// Username, email, or whatever the service calls it.
        #[arg(long, short = 'l')]
        login: String,

        /// Where the account lives.
        #[arg(long, short = 'u')]
        url: Option<String>,

        /// Shared secret for time-based one-time passwords.
        #[arg(long)]
        totp: Option<String>,

        /// Anything else worth remembering.
        #[arg(long)]
        notes: Option<String>,

        /// Read the item's password from this environment variable instead of
        /// prompting.
        ///
        /// Deliberately separate from the global --password-env, which carries
        /// the master password.
        #[arg(long = "item-password-env", value_name = "VAR")]
        item_password_env: Option<String>,

        /// Tags to attach; repeat or separate with commas.
        #[arg(long, value_delimiter = ',')]
        tag: Vec<String>,
    },

    /// A payment card.
    ///
    /// The number, the CVV and the PIN are secret: they are asked for rather
    /// than passed as options, so they stay out of the shell history and out of
    /// every process listing on the machine.
    Card {
        /// What to call it.
        title: String,

        /// Name embossed on the card.
        #[arg(long)]
        holder: Option<String>,

        /// Expiry date, as printed on the card.
        #[arg(long)]
        expiry: Option<String>,

        /// Anything else worth remembering.
        #[arg(long)]
        notes: Option<String>,

        /// Do not ask for the CVV.
        #[arg(long)]
        no_cvv: bool,

        /// Do not ask for the PIN.
        #[arg(long)]
        no_pin: bool,

        /// Read the card number from this environment variable instead of
        /// prompting.
        #[arg(long, value_name = "VAR")]
        number_env: Option<String>,

        /// Read the CVV from this environment variable instead of prompting.
        #[arg(long, value_name = "VAR", conflicts_with = "no_cvv")]
        cvv_env: Option<String>,

        /// Read the PIN from this environment variable instead of prompting.
        #[arg(long, value_name = "VAR", conflicts_with = "no_pin")]
        pin_env: Option<String>,

        /// Tags to attach; repeat or separate with commas.
        #[arg(long, value_delimiter = ',')]
        tag: Vec<String>,
    },

    /// An SSH key pair and its passphrase.
    ///
    /// The private key is read from a file rather than typed: it is multi-line
    /// and would not survive a prompt. It is stored as a field, not as an
    /// attachment, so `sefy get` can hand it to a command directly.
    SshKey {
        /// What to call it.
        title: String,

        /// Private key file to read.
        #[arg(long, value_name = "PATH")]
        private_key: PathBuf,

        /// Public key file to read; defaults to the private key's path with
        /// `.pub` appended, when such a file is there.
        #[arg(long, value_name = "PATH")]
        public_key: Option<PathBuf>,

        /// Where the key is used.
        #[arg(long)]
        host: Option<String>,

        /// Anything else worth remembering.
        #[arg(long)]
        notes: Option<String>,

        /// Do not ask for the passphrase; for a key that has none.
        #[arg(long)]
        no_passphrase: bool,

        /// Read the passphrase from this environment variable instead of
        /// prompting.
        #[arg(long, value_name = "VAR", conflicts_with = "no_passphrase")]
        passphrase_env: Option<String>,

        /// Tags to attach; repeat or separate with commas.
        #[arg(long, value_delimiter = ',')]
        tag: Vec<String>,
    },

    /// A Wi-Fi network: ssid, password, security, notes.
    ///
    /// The password is asked for; the other fields are passed with --set.
    Wifi(RecordArgs),

    /// A token for an API: token, url, scopes, expires, notes.
    ///
    /// The token is asked for; the other fields are passed with --set.
    ApiToken(RecordArgs),

    /// A bank account: account, holder, bank, routing, notes.
    ///
    /// The account number is asked for; the other fields are passed with
    /// --set.
    Bank(RecordArgs),

    /// A file, stored byte for byte.
    File {
        /// File to read.
        path: PathBuf,

        /// What to call it; defaults to the file name.
        #[arg(long, short = 'T')]
        title: Option<String>,

        /// Tags to attach; repeat or separate with commas.
        #[arg(long, value_delimiter = ',')]
        tag: Vec<String>,
    },
}

/// Arguments of the kinds that are nothing but their fields.
///
/// A kind like this is a row in the template table: which fields it has, which
/// are secret. The command line follows from the row rather than growing a
/// flag per field, so the next kind costs no new options.
#[derive(Debug, Args)]
pub struct RecordArgs {
    /// What to call it.
    pub title: String,

    /// Set a field: `--set ssid=Home`. Repeat for several.
    ///
    /// Secret fields are refused here and asked for instead, so they stay out
    /// of the shell history. A name the kind does not have is kept as an
    /// extra field.
    #[arg(long, value_name = "NAME=VALUE")]
    pub set: Vec<String>,

    /// Read a secret field from an environment variable instead of asking:
    /// `--secret-env password=WIFI_KEY`.
    #[arg(long, value_name = "NAME=VAR")]
    pub secret_env: Vec<String>,

    /// Do not ask for this secret field.
    #[arg(long, value_name = "NAME")]
    pub skip: Vec<String>,

    /// Tags to attach; repeat or separate with commas.
    #[arg(long, value_delimiter = ',')]
    pub tag: Vec<String>,
}

/// Arguments of `sefy get`.
#[derive(Debug, Args)]
pub struct GetArgs {
    /// Item id, exact title, or text to search for.
    pub reference: String,

    /// Which field to take from a record.
    ///
    /// Any field the record carries, by name. Omitted, sefy takes the kind's
    /// own secret: a login's password, a card's number, an SSH key's private
    /// key.
    #[arg(long, value_name = "NAME")]
    pub field: Option<String>,

    /// Print the secret instead of copying it to the clipboard.
    ///
    /// Convenient for pipes, but the secret then lives in the terminal
    /// scrollback.
    #[arg(long)]
    pub stdout: bool,

    /// Seconds before the clipboard is cleared again; 0 leaves it there.
    ///
    /// sefy waits that long before exiting, and clears the clipboard only if
    /// the secret is still the value sitting on it.
    #[arg(long, value_name = "SECONDS", default_value_t = 45)]
    pub clear_after: u64,
}

/// Arguments of `sefy gen`.
#[derive(Debug, Args)]
pub struct GenArgs {
    /// Length in characters.
    #[arg(
        long,
        short = 'n',
        value_name = "N",
        default_value_t = 20,
        conflicts_with = "words"
    )]
    pub length: usize,

    /// Leave out upper-case letters.
    #[arg(long, conflicts_with_all = ["words", "pronounceable"])]
    pub no_uppercase: bool,

    /// Leave out digits.
    #[arg(long, conflicts_with_all = ["words", "pronounceable"])]
    pub no_digits: bool,

    /// Leave out symbols, for the sites that refuse them.
    #[arg(long, conflicts_with_all = ["words", "pronounceable"])]
    pub no_symbols: bool,

    /// Alternate consonants and vowels, so it can be read out and typed.
    ///
    /// Weaker per character than the default: check the bits it reports and
    /// make it longer to match.
    #[arg(long, conflicts_with = "words")]
    pub pronounceable: bool,

    /// Make a passphrase of this many words instead of a password.
    ///
    /// For a secret typed by hand: a master password, a disk encryption key.
    #[arg(long, short = 'w', value_name = "N")]
    pub words: Option<usize>,

    /// Which word list a passphrase is drawn from.
    #[arg(long, value_enum, default_value = "en", requires = "words")]
    pub lang: WordList,

    /// What goes between the words of a passphrase.
    #[arg(long, value_name = "TEXT", default_value = "-", requires = "words")]
    pub separator: String,

    /// Store the result as a new login under this title.
    #[arg(long, value_name = "TITLE")]
    pub save: Option<String>,

    /// The login of the saved record.
    #[arg(long, short = 'l', requires = "save")]
    pub login: Option<String>,

    /// Where the saved account lives.
    #[arg(long, short = 'u', requires = "save")]
    pub url: Option<String>,

    /// Tags for the saved record; repeat or separate with commas.
    #[arg(long, value_delimiter = ',', requires = "save")]
    pub tag: Vec<String>,

    /// Print the result instead of copying it to the clipboard.
    ///
    /// The description goes to stderr, so a pipe receives the secret alone.
    #[arg(long)]
    pub stdout: bool,

    /// Seconds before the clipboard is cleared again; 0 leaves it there.
    #[arg(long, value_name = "SECONDS", default_value_t = 45)]
    pub clear_after: u64,
}

/// A passphrase word list, as spelled on the command line.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub enum WordList {
    /// The EFF large wordlist: 7776 words, 12.9 bits each.
    En,
    /// Russian Diceware 4d6: 1296 words, 10.3 bits each.
    Ru,
}

impl From<WordList> for sefy_core::Language {
    fn from(list: WordList) -> Self {
        match list {
            WordList::En => Self::English,
            WordList::Ru => Self::Russian,
        }
    }
}

/// Arguments of `sefy open`.
#[derive(Debug, Args)]
pub struct OpenArgs {
    /// Item id, exact title, or text to search for.
    pub reference: String,

    /// Open the site without touching the clipboard.
    #[arg(long)]
    pub no_password: bool,

    /// Seconds before the clipboard is cleared again; 0 leaves it there.
    #[arg(long, value_name = "SECONDS", default_value_t = 45)]
    pub clear_after: u64,
}

/// Arguments of `sefy otp`.
#[derive(Debug, Args)]
pub struct OtpArgs {
    /// Item id, exact title, or text to search for.
    pub reference: String,

    /// Store a key on the record first; it is asked for and never echoed.
    ///
    /// Paste the otpauth:// link a setup QR code carries, or the text key the
    /// page shows beside it. The first code follows, for the site that asks
    /// for one to confirm.
    #[arg(long)]
    pub set: bool,

    /// Read the key to store from this environment variable instead of
    /// asking.
    #[arg(long, value_name = "VAR")]
    pub key_env: Option<String>,

    /// Draw the key as a QR code, for an authenticator app on a phone.
    ///
    /// The picture is the key itself: it is drawn only on a terminal and
    /// cleared from the screen once Enter is pressed.
    #[arg(long, conflicts_with = "stdout")]
    pub qr: bool,

    /// Print the code instead of copying it to the clipboard.
    #[arg(long)]
    pub stdout: bool,

    /// Seconds before the clipboard is cleared again; 0 leaves it there.
    #[arg(long, value_name = "SECONDS", default_value_t = 45)]
    pub clear_after: u64,
}

/// Arguments of `sefy fill`.
#[derive(Debug, Args)]
pub struct FillArgs {
    /// Item id, exact title, or text to search for.
    pub reference: String,

    /// Seconds before the last field is cleared from the clipboard; 0 leaves
    /// it there.
    #[arg(long, value_name = "SECONDS", default_value_t = 45)]
    pub clear_after: u64,
}

/// Arguments of `sefy ls`.
#[derive(Debug, Args)]
pub struct ListArgs {
    /// Keep only items of this kind.
    #[arg(long, value_enum)]
    pub kind: Option<Kind>,

    /// Keep only items carrying every one of these tags.
    #[arg(long, value_delimiter = ',')]
    pub tag: Vec<String>,
}

/// Arguments of `sefy find`.
#[derive(Debug, Args)]
pub struct FindArgs {
    /// Text to look for in titles, notes and credential fields.
    ///
    /// The contents of stored files are not searched.
    pub text: Option<String>,

    /// Keep only items of this kind.
    #[arg(long, value_enum)]
    pub kind: Option<Kind>,

    /// Keep only items carrying every one of these tags.
    #[arg(long, value_delimiter = ',')]
    pub tag: Vec<String>,
}

/// Arguments of `sefy edit`.
#[derive(Debug, Args)]
pub struct EditArgs {
    /// Item id, exact title, or text to search for.
    pub reference: String,

    /// New title.
    #[arg(long)]
    pub title: Option<String>,

    /// New text, for a note.
    #[arg(long, short = 't', conflicts_with = "editor")]
    pub text: Option<String>,

    /// Open the note in $EDITOR instead of passing its text on the command
    /// line.
    ///
    /// The draft is written to a temporary file, which is overwritten and
    /// removed as soon as the editor exits — but while the editor is open, that
    /// file holds the note in the clear, and an editor's own swap or backup
    /// files are outside sefy's reach.
    #[arg(long, short = 'e')]
    pub editor: bool,

    /// Set a field of a record: `--set url=https://example.com`.
    ///
    /// Repeat for several. A field the record does not have yet is added, so
    /// this is how a record grows beyond what its kind suggested.
    #[arg(long, value_name = "NAME=VALUE")]
    pub set: Vec<String>,

    /// Prompt for a field's value instead of passing it on the command line:
    /// `--set-secret password`.
    ///
    /// The value is read the way the master password is — never echoed, never
    /// in the shell history — and the field is marked secret.
    #[arg(long, value_name = "NAME")]
    pub set_secret: Vec<String>,

    /// Remove a field from a record.
    #[arg(long, value_name = "NAME")]
    pub unset: Vec<String>,

    /// Replace the item's tags; repeat or separate with commas.
    #[arg(long, value_delimiter = ',')]
    pub tag: Vec<String>,

    /// Remove every tag from the item.
    #[arg(long, conflicts_with = "tag")]
    pub clear_tags: bool,
}

/// Kind of item, as spelled on the command line.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub enum Kind {
    /// A free-form note.
    Note,
    /// An account and its password.
    #[value(alias = "credential")]
    Login,
    /// A payment card.
    Card,
    /// An SSH key pair.
    SshKey,
    /// A Wi-Fi network.
    Wifi,
    /// A token for an API.
    ApiToken,
    /// A bank account.
    Bank,
    /// A stored file.
    File,
}

impl From<Kind> for sefy_core::ItemKind {
    fn from(kind: Kind) -> Self {
        match kind {
            Kind::Note => Self::Note,
            Kind::Login => Self::Login,
            Kind::Card => Self::Card,
            Kind::SshKey => Self::SshKey,
            Kind::Wifi => Self::Wifi,
            Kind::ApiToken => Self::ApiToken,
            Kind::Bank => Self::Bank,
            Kind::File => Self::File,
        }
    }
}