stenoxide-cli 3.24.3

//! Command line front-end of `stenoxide`.
//!
//! Four subcommands, three of which read the password interactively:
//!
//! ```text
//! stenoxide scan     ./photos --recursive
//! stenoxide embed    --input cover.png --output stego.png   < message.txt
//! stenoxide embed    --input cover.png --output stego.png --payload secret.zip
//! stenoxide extract  --input stego.png                      > message.txt
//! stenoxide extract  --input stego.png --payload-out secret.zip
//! stenoxide generate --output container.png --input message.txt
//! stenoxide generate --output container.png --input big.bin --width 2500 --height 2500
//! ```
//!
//! # The experimental public-key mode
//!
//! Compiled only when the `pqc` feature is enabled — `cargo install
//! stenoxide-cli --features pqc`, or `cargo build -p stenoxide-cli --features
//! pqc` from a checkout — and absent from every release binary until the mode
//! is finished. It adds one subcommand and one flag to each of two others:
//!
//! ```text
//! stenoxide keygen   --public me.pub --private me.key
//! stenoxide generate --output container.png --input message.txt --recipient them.pub
//! stenoxide extract  --input container.png --identity me.key
//! ```
//!
//! The recipient publishes `me.pub` and keeps `me.key`. A sender needs only the
//! public file, and there is no password to agree on beforehand. It applies to
//! `generate` alone: `embed` has a design question of its own to settle before
//! it can offer the same thing, and offering half of it would be worse than
//! offering none.
//!
//! The passphrase that protects a private key file is local to the machine it
//! is on. It is not the password of the symmetric modes and it is never shared
//! with anybody; every prompt that reads one says so, because confusing the two
//! is the mistake waiting to be made.
//!
//! The payload has always been arbitrary bytes rather than text, so the file
//! forms are not a new capability so much as the end of a shell redirection the
//! user had to arrange themselves. They change nothing about what is embedded:
//! an image produced with `--payload` is indistinguishable from one produced by
//! piping the same bytes in.
//!
//! # Why nothing secret is an argument
//!
//! Neither the password nor the message can be passed on the command line. A
//! password given as an argument survives in the shell history, in the process
//! table for as long as the process runs, and in whatever the shell's own
//! logging does with the line — three places the user cannot wipe and did not
//! choose. The password is therefore read from the terminal with echo disabled
//! and the message from standard input, which leaves no trace whether it is
//! piped in or typed. Typing it is in fact the more private of the two: a
//! message given to `echo` is a command line like any other and lands in the
//! shell's history. See [`read_plaintext`] for how a typed message is ended.
//!
//! A path is not a secret, and `--payload` does not weaken any of that: what
//! reaches the command line is where the file is, never a byte of what is in
//! it.
//!
//! # Why the recovered file is named by whoever extracts it
//!
//! `--payload-out` takes a full path, and the sender has no say in it: the
//! payload carries no file name, because nothing but the bytes is hidden. The
//! extension is recovered from the content instead, against a closed table. The
//! reasoning — which is about the recipient's disk and about paths built from
//! untrusted input, not about cryptography — is in the [`payload`] module.
//!
//! # Why the container is validated before the password is asked for
//!
//! The pipeline would refuse an unusable container anyway, but it does so after
//! it has stretched the password — so a user who picked the wrong file would
//! have typed their passphrase for nothing and be told why only afterwards.
//! Both subcommands therefore load and validate the image first and only prompt
//! once it is known to be usable. Nothing about the security of the operation
//! changes: the pipeline runs the very same gates again on the path it is
//! given, and it is the pipeline's verdict, not this one, that decides whether
//! anything is embedded.
//!
//! # Why `generate` is a subcommand and not an offer
//!
//! `embed` needs a container, and the tempting interface is to notice that it
//! was given none and offer to make one. It is the wrong place for it twice
//! over. A user who omitted `--input` made a typo and is not asking to change
//! their security model, so the offer would turn a slip into a hurried
//! decision; and the operation that fits behind such a prompt is *generate,
//! then embed*, which is the weaker of the two constructions by a wide margin —
//! roughly 7 KB of capacity against 1.4 MB, and a detectable container against
//! one that provably is not. The convenient path would deliver the worse mode.
//!
//! Discoverability belongs in `scan` instead: when it walks a directory and
//! accepts nothing at all, it says so in one line. That user has already
//! demonstrated that they looked.
//!
//! # Why the two subcommands report failure so differently
//!
//! Embedding is a local operation whose failures are the user's to fix — a
//! container that is too small, a message that does not fit, an unwritable
//! output path — so its errors are printed in full.
//!
//! Extraction is not. Its three failure modes are a wrong password, an image
//! that carries nothing, and a payload that was damaged in transit, and telling
//! them apart is exactly the oracle an attacker holding an intercepted image
//! wants: it would confirm that the image is a container at all, and turn a
//! password search into a test with a yes-or-no answer. So extraction prints
//! one sentence and never says which of the three happened.
//!
//! # The one thing extraction says beyond that sentence
//!
//! A recovered payload with no `--payload-out` goes to standard output, and a
//! payload that is binary cannot go to a *terminal*: a Windows console rejects
//! bytes that are not valid UTF-8, and a Unix terminal would be sprayed with
//! control codes. So a binary payload bound for a terminal is announced instead
//! of written. That notice reveals the extraction succeeded — but so does a text
//! payload printed to the same terminal, and so does any file written under
//! `--payload-out`; success is inherent in producing the plaintext. The single
//! sentence still covers the three failures and every post-success write error
//! on the redirected path, which is all it ever protected. See
//! [`write_recovered_to_stdout`].

#![deny(clippy::unwrap_used)]
#![deny(clippy::expect_used)]
#![deny(clippy::panic)]
#![deny(missing_docs)]

use std::io::{self, BufRead, IsTerminal, Read, Write};
use std::path::{Path, PathBuf};
use std::process::ExitCode;

use clap::{Args, CommandFactory, Parser, Subcommand};
use clap_complete::aot::{generate, Shell};
use zeroize::Zeroizing;

use stenoxide_core::cost::hill::HillCostProvider;
use stenoxide_core::cost::CostProvider;
#[cfg(feature = "pqc")]
use stenoxide_core::crypto::aead::XChaCha20Poly1305Cipher;
#[cfg(feature = "pqc")]
use stenoxide_core::crypto::kdf::Argon2Kdf;
#[cfg(feature = "pqc")]
use stenoxide_core::crypto::kem::{Identity, KemError, RecipientKey};
#[cfg(feature = "pqc")]
use stenoxide_core::generate::generate_container_for_recipient;
use stenoxide_core::generate::{
    generate_container, ContainerDimensions, GenerateError, GenerateReport, DEFAULT_CONTAINER_SIDE,
    MIN_CONTAINER_SIDE,
};
use stenoxide_core::image_io::buffer::ImageBuffer;
use stenoxide_core::image_io::phash::{compute_stable_phash, PHashError, PHashSalt};
use stenoxide_core::image_io::validate::{load_and_validate, ValidationError};
use stenoxide_core::pipeline::{EmbedPipeline, EmbedReport, PipelineError};
use stenoxide_core::stego::sizer::{compute_capacity, EmbeddingMode, SizerError};

mod payload;
mod progress;
mod scan;

/// The one thing the user is told when extraction fails, whatever the cause.
///
/// See the module documentation: distinguishing a wrong password from an image
/// that carries no payload would answer, for free, the question an attacker is
/// actually asking.
const EXTRACTION_FAILED: &str = "Could not extract the payload.";

/// Prompt shown when the password is read from the terminal.
const PASSWORD_PROMPT: &str = "Password: ";

/// Prompt shown when an existing private key file has to be unlocked.
///
/// It names the file rather than saying "passphrase", because the whole risk
/// here is a user reaching for the password they hide messages under.
#[cfg(feature = "pqc")]
const KEY_PASSPHRASE_PROMPT: &str = "Passphrase for the private key file: ";

/// Prompt shown for the second reading of a new passphrase.
#[cfg(feature = "pqc")]
const KEY_PASSPHRASE_REPEAT_PROMPT: &str = "Repeat it: ";

/// What is said before a passphrase for a new key file is asked for.
///
/// Three sentences, and each of them exists because of a specific way this goes
/// wrong: reusing the message password, expecting a correspondent to be asked
/// for this, and losing it. Plain ASCII, like [`TYPING_GUIDANCE`], for the same
/// reason.
#[cfg(feature = "pqc")]
const KEY_PASSPHRASE_GUIDANCE: &str = "\
This passphrase protects the private key file on this machine and nothing else.
It is not the password used to hide a message, it never travels, and nobody you
send the public key to is ever asked for it.
There is no recovery: lose it and everything sent to this key is unreadable.
";

/// The line that ends a message typed at the terminal.
///
/// The convention `mail` established, chosen over end of file for the reason
/// given in [`read_plaintext`]: it is ordinary text, so no shell can intercept
/// it on its way to this process.
const END_OF_MESSAGE: &str = ".";

/// The long help of `generate`, which has one thing it must say.
///
/// A user reaches this subcommand because nothing they own can be used as a
/// container, and the mode answers a narrower question than they are likely to
/// assume. It hides *which* of several generated containers carries a message,
/// completely and provably. It does not hide that the file was generated: it
/// looks like a synthetic texture, and a folder of them is conspicuous in a way
/// no analysis of any single file needs to be.
const GENERATE_LONG_ABOUT: &str = "\
Build a container around a message instead of hiding it inside an existing image.

For when there is no usable photograph — a camera that only writes JPEG, no way
to move pictures across from a phone. The container is drawn sample by sample,
each one conditioned on the ciphertext bit it carries, so a container holding a
message and one holding nothing are draws from the same distribution and no
detector can separate them. It carries about 1.4 MB, against the 8 KB an image
of the same size admits by embedding.

The default container is 2000x2000, the smallest and least conspicuous the mode
draws. A payload that does not fit needs a larger one: raise --width and
--height together (each at least 2000). Capacity grows with the pixel count, so
the error printed when a payload overflows names a size that would hold it.

It does not hide that the container was generated. It looks like a synthetic
texture, and a folder full of them is itself the thing worth explaining. Prefer
a photograph of your own that has never been published, whenever you have one.";

/// The long help of `keygen`, which has three things it must say.
///
/// What the two files are for, that the passphrase on the private one is local,
/// and that the whole mode is unfinished. The last is not a disclaimer for its
/// own sake: someone who publishes a key today is making a commitment that this
/// program is not yet in a position to honour across versions.
#[cfg(feature = "pqc")]
const KEYGEN_LONG_ABOUT: &str = "\
Generate a key pair, so that people can hide messages for you without agreeing
on a password with you first.

The public file is meant to be published: put it in a profile, paste it into a
chat, send it wherever. Anyone holding it can run

  stenoxide generate --recipient <that file> --output container.png

and only the holder of the private file can read the result. The message key is
drawn fresh for every container and owes nothing to the image, so reusing a
picture is harmless here rather than merely discouraged.

The private file is protected by a passphrase that is local to this machine. It
is not the password used to hide a message, it never travels, and nobody you
send the public key to is ever asked for it. There is no recovery.

EXPERIMENTAL. The file format is not settled and a later release may not read
keys generated today. Do not build anything on it yet.";

/// The line `embed` adds when it refuses the photograph it was given.
///
/// The same pointer `scan` prints when it accepts nothing, from the other side:
/// there, a user who looked is told that `generate` exists; here, a user who
/// picked one file straight away is told that there is a way to find out which
/// of the others would have worked. It is offered only by `embed`, because it
/// answers a question only that user is asking — see [`describe_embed_rejection`].
///
/// The leading newline and seven spaces are the continuation indent every
/// multi-line message in this file already uses, so the advice lines up under
/// the sentence it belongs to rather than under `Error:`.
const ANOTHER_CONTAINER_HINT: &str = "\n       \
     stenoxide scan <folder> reports which of your other photos can be used.";

/// What the user is told before they are expected to type a message.
///
/// Plain ASCII on purpose: this is printed before anything else knows whether
/// the console can render a nicer mark, and a guidance line that arrives as a
/// row of question marks would defeat its own point.
///
/// # Why it says a submitted line cannot be edited
///
/// Because the arrow keys look as though they should. They reach the console's
/// own line editor, which recalls what was typed at the *shell* — so a user
/// trying to correct the line above finds a command from their history where
/// their message was, and no way back to it. Saying so costs one line and is
/// cheaper than discovering it halfway through a message.
///
/// # Why there is no line editor here
///
/// Every candidate worth taking brings a history with it, and a history is a
/// place the secret message can end up written down, in memory or on disk. That
/// is the same surface the password and the message avoid by never being
/// arguments. The way to revise a message before hiding it is to write it in a
/// file, which is what the flag named below is for — `-p` in both subcommands
/// that read a typed message, where the long forms differ.
const TYPING_GUIDANCE: &str = "\
Message to hide. It may span as many lines as you need.
Finish with a line containing a single dot:  .
A line you have sent cannot be edited; to revise one first, put the message in
a file and pass it with -p.
";

/// The whole of what `stenoxide --help` prints.
///
/// `clap` replaces rather than extends: the moment `long_about` has content it
/// becomes the entire body of the long help, and the sentence `about` carries
/// would simply vanish from it. So that sentence opens this text — read from the
/// manifest, the same place `about` reads it, rather than copied where the two
/// could drift apart — and the examples follow. The short help is untouched and
/// still prints that one sentence alone.
///
/// What the examples add is the one thing the list of commands underneath
/// cannot: the order. A reader sees four verbs and no indication that `scan`
/// comes first and `extract` last.
///
/// `completions` and `man` are deliberately left out. They are installation
/// utilities rather than steps of the flow, they are already visible in the list
/// clap prints below, and naming them here would dilute the only thing this text
/// exists to say.
const CLI_LONG_ABOUT: &str = concat!(
    env!("CARGO_PKG_DESCRIPTION"),
    "\n\n",
    "Find a photograph that can hold a message, hide one in it, read it back:\n\n",
    "  stenoxide scan ./photos\n",
    "  stenoxide embed --input photo.png --output stego.png\n",
    "  stenoxide extract --input stego.png\n\n",
    "When none of the photographs can be used, stenoxide generate builds a\n",
    "container around the message instead."
);

/// Hide encrypted messages inside lossless images.
#[derive(Parser)]
#[command(name = "stenoxide", version, about, long_about = CLI_LONG_ABOUT)]
struct Cli {
    /// Operation to perform.
    #[command(subcommand)]
    command: Command,
}

/// The operations the front-end exposes.
///
/// # The short flags, and the collision they had to resolve
///
/// A letter means the same thing in every subcommand that has it. That rule is
/// worth more than covering every flag, because a short form is memorised once
/// and typed everywhere, and one that meant two things would be worse than none.
///
/// `--input` already means three things. In `embed` it is the container, in
/// `extract` it is the stego image, and in `generate` it is the file to hide.
/// Giving all three `-i` would have set that inconsistency in a single letter.
/// Renaming any of the long forms was not an option — they are the interface
/// this program already shipped — so the letters follow the *meaning*:
///
/// - `-i` — the image being read: `embed --input`, `extract --input`. Never
///   `generate`, which reads no image.
/// - `-o` — where the result of the operation goes: `embed --output`,
///   `generate --output`, `extract --payload-out`.
/// - `-p` — the file to hide: `embed --payload`, and `generate --input`, where
///   the letter does not match the long form but does match what the flag is
///   for, which is the thing being fixed.
/// - `-f` — `--force`, everywhere it exists.
///
/// `-h` is `--help` and is never taken. That rules out a short form for
/// `generate --height`, and `--width` goes without one too rather than leave a
/// pair of flags where one half is abbreviated and the other is not.
#[derive(Subcommand)]
enum Command {
    /// Report which images can be used as containers, and how much each can
    /// carry.
    Scan(ScanArgs),
    /// Hide a message, read from standard input, inside a PNG container.
    Embed {
        /// Container image: the photo the message is hidden inside. Must be a
        /// PNG of at least 2000x2000 pixels that has never been
        /// JPEG-compressed.
        #[arg(long, short = 'i', value_name = "PATH")]
        input: PathBuf,
        // Why there is no default, and why one will not be added. A name
        // derived from the container — cover.png becoming cover.stego.png —
        // writes the link between the two files into the filesystem, which is
        // the one relationship this program exists not to reveal. A random name
        // leaks nothing but leaves a file the user did not ask for, in a place
        // they did not choose and then have to go looking for. What the
        // requirement costs is one immediate retry against a clap error that
        // already prints the full usage, which is the cheapest of the three.
        /// Where to write the resulting stego image: the full path, file name
        /// included. Always written as PNG. There is no default, because a name
        /// derived from the container would record the link between the two on
        /// disk.
        #[arg(long, short = 'o', value_name = "PATH")]
        output: PathBuf,
        /// File to hide. Read from standard input when absent; when given,
        /// standard input is not read at all and any redirection is ignored.
        #[arg(long, short = 'p', value_name = "PATH")]
        payload: Option<PathBuf>,
        /// Overwrite the output file if it already exists.
        #[arg(long, short = 'f')]
        force: bool,
    },
    /// Build a container around a message, for when there is no usable photo.
    #[command(long_about = GENERATE_LONG_ABOUT)]
    Generate {
        /// Where to write the container: the full path, file name included.
        /// Always written as PNG.
        #[arg(long, short = 'o', value_name = "PATH")]
        output: PathBuf,
        /// File to hide. Read from standard input when absent; when given,
        /// standard input is not read at all and any redirection is ignored.
        ///
        /// Its short form is -p, the letter every subcommand uses for the file
        /// being hidden, rather than -i, which is the image being read.
        #[arg(long, short = 'p', value_name = "PATH")]
        input: Option<PathBuf>,
        /// Width of the container to draw, in pixels. Defaults to 2000, the
        /// smallest — and least conspicuous — the mode will produce; raise it,
        /// together with --height, only when a payload does not fit. Must be at
        /// least 2000.
        #[arg(long, value_name = "PIXELS", default_value_t = DEFAULT_CONTAINER_SIDE,
              value_parser = clap::value_parser!(u32).range(i64::from(MIN_CONTAINER_SIDE)..))]
        width: u32,
        /// Height of the container to draw, in pixels. Defaults to 2000. Must be
        /// at least 2000; a larger container carries more, in proportion to its
        /// pixel count.
        #[arg(long, value_name = "PIXELS", default_value_t = DEFAULT_CONTAINER_SIDE,
              value_parser = clap::value_parser!(u32).range(i64::from(MIN_CONTAINER_SIDE)..))]
        height: u32,
        /// EXPERIMENTAL. Public key file of the recipient, from stenoxide
        /// keygen. When given, no password is asked for: the message key is
        /// encapsulated to this key and travels inside the container, which
        /// costs 1568 bytes of capacity.
        // No short form. The letters are spoken for and this flag is too new to
        // spend one of the few that are left; see the map on this enum.
        #[cfg(feature = "pqc")]
        #[arg(long, value_name = "PATH")]
        recipient: Option<PathBuf>,
        /// Overwrite the output file if it already exists.
        #[arg(long, short = 'f')]
        force: bool,
    },
    /// Generate a key pair, so others can hide messages for you without a
    /// shared password. EXPERIMENTAL.
    #[cfg(feature = "pqc")]
    #[command(long_about = KEYGEN_LONG_ABOUT)]
    Keygen {
        /// Where to write the public key: the file to publish. The full path,
        /// file name included.
        #[arg(long, value_name = "PATH")]
        public: PathBuf,
        /// Where to write the private key: the file to keep. The full path,
        /// file name included.
        #[arg(long, value_name = "PATH")]
        private: PathBuf,
        /// Overwrite the two output files if they already exist. Replacing a
        /// key pair destroys everything that was ever encrypted to it.
        #[arg(long, short = 'f')]
        force: bool,
    },
    /// Recover a hidden message from a stego image and write it to standard
    /// output.
    Extract {
        /// The stego image to read.
        #[arg(long, short = 'i', value_name = "PATH")]
        input: PathBuf,
        /// EXPERIMENTAL. Private key file to read the container with, from
        /// stenoxide keygen. When given, no password is asked for: the
        /// container is read with this identity instead. The passphrase you are
        /// prompted for unlocks the key file and nothing else.
        #[cfg(feature = "pqc")]
        #[arg(long, value_name = "PATH")]
        identity: Option<PathBuf>,
        /// Where to write the recovered payload, the hidden file or message.
        /// Written to standard output when absent. A directory receives a file
        /// named after the type of the content; a path without an extension is
        /// given one.
        // Its short form is `-o` because that is the letter for where the
        // result goes; see the map on the enum. It is not spelled out in the
        // help the way `generate --input` is, because there the letter does not
        // match the long form and here it does.
        #[arg(long, short = 'o', value_name = "PATH")]
        payload_out: Option<PathBuf>,
        /// Overwrite the output file if it already exists.
        #[arg(long, short = 'f', requires = "payload_out")]
        force: bool,
    },
    /// Write a shell completion script to standard output.
    ///
    /// The script and nothing else, so that it can be sourced directly —
    /// `source <(stenoxide completions bash)` — or saved wherever the shell
    /// looks for its completions.
    Completions {
        /// Shell the script is written for.
        #[arg(value_name = "SHELL", value_enum)]
        shell: Shell,
    },
    /// Write the manual page to standard output.
    ///
    /// The roff source of `stenoxide.1`, for a packager to redirect into a
    /// file: `stenoxide man > stenoxide.1`. It is produced at run time rather
    /// than by a build script because a build script compiles as a separate
    /// crate and cannot see the command definition it would have to describe.
    ///
    /// # Why there is one page and not one per subcommand
    ///
    /// The page rendered is the root command, whose SUBCOMMANDS section lists
    /// every verb with its summary. Separate `stenoxide-embed.1` style pages
    /// are deliberately not produced, and this subcommand takes no argument
    /// asking for one: a single page is what `man stenoxide` finds, and it is
    /// the whole of what this tool needs to document. The absence is a
    /// decision, not an oversight.
    Man,
}

/// Everything `stenoxide scan` accepts.
#[derive(Args)]
struct ScanArgs {
    /// File, directory or glob pattern to examine. Defaults to the working
    /// directory.
    #[arg(value_name = "PATH", default_value = ".")]
    path: String,
    /// Also list the images that cannot be used, with the reason.
    #[arg(long, short = 'a')]
    all: bool,
    /// Descend into subdirectories.
    #[arg(long, short = 'r')]
    recursive: bool,
    /// Write the result as JSON, and nothing else.
    #[arg(long)]
    json: bool,
}

/// Where `generate` gets the key it encrypts under.
///
/// A type rather than an `Option<&Path>` threaded through the run function: the
/// second variant does not exist in a default build, and reducing "which mode"
/// to one value decided in `main` keeps the rest of the program from asking the
/// question twice and answering it differently.
enum GenerateKeySource {
    /// A password read from the terminal. The default, and the only mode a
    /// release binary offers.
    Password,
    /// A recipient's public key file. No password is read at all.
    #[cfg(feature = "pqc")]
    Recipient(PathBuf),
}

/// Where `extract` gets the key it decrypts with. The counterpart of
/// [`GenerateKeySource`].
enum ExtractKeySource {
    /// A password read from the terminal.
    Password,
    /// A private key file, unlocked by its own local passphrase.
    #[cfg(feature = "pqc")]
    Identity(PathBuf),
}

fn main() -> ExitCode {
    let cli = Cli::parse();

    let outcome = match &cli.command {
        Command::Scan(args) => scan::run(args),
        Command::Embed {
            input,
            output,
            payload,
            force,
        } => run_embed(input, output, payload.as_deref(), *force),
        Command::Generate {
            output,
            input,
            width,
            height,
            #[cfg(feature = "pqc")]
            recipient,
            force,
        } => {
            #[cfg(feature = "pqc")]
            let source = match recipient {
                Some(path) => GenerateKeySource::Recipient(path.clone()),
                None => GenerateKeySource::Password,
            };
            #[cfg(not(feature = "pqc"))]
            let source = GenerateKeySource::Password;

            run_generate(output, input.as_deref(), *width, *height, *force, &source)
        }
        #[cfg(feature = "pqc")]
        Command::Keygen {
            public,
            private,
            force,
        } => run_keygen(public, private, *force),
        Command::Extract {
            input,
            #[cfg(feature = "pqc")]
            identity,
            payload_out,
            force,
        } => {
            #[cfg(feature = "pqc")]
            let source = match identity {
                Some(path) => ExtractKeySource::Identity(path.clone()),
                None => ExtractKeySource::Password,
            };
            #[cfg(not(feature = "pqc"))]
            let source = ExtractKeySource::Password;

            run_extract(input, payload_out.as_deref(), *force, &source)
        }
        Command::Completions { shell } => run_completions(*shell),
        Command::Man => run_man(),
    };

    match outcome {
        Ok(()) => ExitCode::SUCCESS,
        Err(message) => {
            // On stderr, so that a caller redirecting stdout to a file gets the
            // message rather than a file with an error in it.
            eprintln!("{message}");
            ExitCode::FAILURE
        }
    }
}

/// Reads the password from the terminal with echo disabled.
///
/// The bytes are moved into a [`Zeroizing`] the moment they arrive, so the only
/// copy that outlives this function is one that wipes itself. The `String`
/// `rpassword` returns is consumed by [`String::into_bytes`], which reuses its
/// allocation instead of leaving a second copy behind.
///
/// # Errors
///
/// Returns a message describing why the terminal could not be read.
fn read_password() -> Result<Zeroizing<Vec<u8>>, String> {
    rpassword::prompt_password(PASSWORD_PROMPT)
        .map(|password| Zeroizing::new(password.into_bytes()))
        .map_err(|err| format!("Error: could not read the password: {err}"))
}

/// Reads the local passphrase that protects a private key file.
///
/// # Why it repeats the question
///
/// `repeat` is `true` exactly when a new file is being sealed. It asks a
/// second time and compares the two — the one defense against a typo that
/// cannot be seen, in a passphrase there is no recovering from losing. It is
/// false when opening an existing file, which is an operation that already has
/// a confirmation step: the MAC verifies or it doesn't.
///
/// # Errors
///
/// Returns a message describing why the terminal could not be read, or why the
/// two passes did not match.
#[cfg(feature = "pqc")]
fn read_local_passphrase(repeat: bool) -> Result<Zeroizing<Vec<u8>>, String> {
    let passphrase = rpassword::prompt_password(KEY_PASSPHRASE_PROMPT)
        .map(|passphrase| Zeroizing::new(passphrase.into_bytes()))
        .map_err(|err| format!("Error: could not read the passphrase: {err}"))?;

    if repeat {
        let repeated = rpassword::prompt_password(KEY_PASSPHRASE_REPEAT_PROMPT)
            .map(|passphrase| Zeroizing::new(passphrase.into_bytes()))
            .map_err(|err| format!("Error: could not read the passphrase: {err}"))?;

        if *passphrase != *repeated {
            return Err(
                "Error: passphrases do not match. The key file was not created.".to_string(),
            );
        }
    }

    Ok(passphrase)
}

/// Reads the message to hide from standard input.
///
/// Two situations arrive at the same file descriptor, and they are not served
/// by the same code:
///
/// - **A pipe or a redirection.** `echo … | stenoxide embed`, or `< message.txt`.
///   Every byte is message, end of file arrives on its own, and nothing needs
///   to be said to anybody. Read to the end and change nothing.
///
/// - **A terminal.** Nothing was piped in, so what the program is waiting for
///   is a person typing. "Until end of file" then means "until the user sends
///   one", and that is a worse instruction than it looks: `Ctrl+Z` on Windows
///   only counts on an otherwise empty line, and PowerShell's line editor
///   claims the key for undo, so the shell most Windows users are in never
///   delivers it. The honest instruction is one they cannot act on — and until
///   they are given any instruction at all, what they see is a cursor sitting
///   under a password prompt with nothing to say the program wants anything,
///   which reads as a hang.
///
/// So the terminal path states what it wants and accepts a terminator no line
/// editor can intercept, because it is ordinary text: a line holding a single
/// dot, as `mail` has done for decades. End of file still ends the message for
/// the terminals that do send it; it is simply no longer the only way out.
///
/// # Errors
///
/// Returns a message describing why standard input could not be read.
fn read_plaintext() -> Result<Zeroizing<Vec<u8>>, String> {
    let stdin = io::stdin();

    if stdin.is_terminal() {
        // On stderr, like every other thing said to the person at the keyboard:
        // it keeps `embed` usable with its stdout redirected, and it is the
        // stream the progress indicators already respect.
        eprint!("{TYPING_GUIDANCE}");

        let message = collect_typed_lines(&mut stdin.lock())
            .map_err(|err| format!("Error: could not read the message you typed: {err}"))?;

        // Confirms that the terminator was recognised and that something was
        // captured, at the one moment the user can still do something about it
        // — the next thing that happens is a minute inside Argon2id and HILL.
        eprintln!("Read {} bytes.", message.len());

        return Ok(message);
    }

    let mut plaintext = Zeroizing::new(Vec::new());

    stdin
        .lock()
        .read_to_end(&mut plaintext)
        .map_err(|err| format!("Error: could not read the message from standard input: {err}"))?;

    Ok(plaintext)
}

/// Accumulates typed lines until [`END_OF_MESSAGE`] or end of file.
///
/// Split out from [`read_plaintext`] so that the terminator can be asserted
/// against a buffer rather than against a console nobody can drive from a test.
///
/// # Errors
///
/// Returns whatever the underlying reader failed with.
fn collect_typed_lines(input: &mut impl BufRead) -> io::Result<Zeroizing<Vec<u8>>> {
    let mut message = Zeroizing::new(Vec::new());
    let mut line = Zeroizing::new(Vec::new());

    loop {
        line.clear();

        // Bytes rather than `read_line`, which insists on valid UTF-8 and would
        // turn a message typed on a console running some other code page into
        // an error. What the user typed is what gets hidden.
        if input.read_until(b'\n', &mut line)? == 0 {
            break;
        }

        if strip_line_ending(&line) == END_OF_MESSAGE.as_bytes() {
            break;
        }

        message.extend_from_slice(&line);
    }

    // The newline that submitted the last line belongs to the terminator rather
    // than to the message: someone who typed one line and closed it with a dot
    // meant one line, not one line and an empty second one.
    let without_trailing_newline = strip_line_ending(&message).len();
    message.truncate(without_trailing_newline);

    Ok(message)
}

/// A line without its ending, under either of the two conventions.
///
/// A Windows console submits `\r\n` and everything else submits `\n`; neither
/// pair of bytes is something the user typed, so neither may decide whether the
/// line is the terminator.
fn strip_line_ending(line: &[u8]) -> &[u8] {
    let line = match line.strip_suffix(b"\n") {
        Some(rest) => rest,
        None => line,
    };

    match line.strip_suffix(b"\r") {
        Some(rest) => rest,
        None => line,
    }
}

/// Loads a container and reports an unusable one in words the user can act on.
///
/// # Errors
///
/// Returns the message to print, already phrased for a terminal; see
/// [`describe_rejection`].
fn load_container(path: &Path) -> Result<ImageBuffer, String> {
    load_and_validate(path).map_err(|error| describe_rejection(path, &error))
}

/// Loads a container for `embed`, which has one more thing to say than
/// [`load_container`].
///
/// # Errors
///
/// Returns the message to print, already phrased for a terminal; see
/// [`describe_embed_rejection`].
fn load_container_for_embed(path: &Path) -> Result<ImageBuffer, String> {
    load_and_validate(path).map_err(|error| describe_embed_rejection(path, &error))
}

/// Turns a validation failure into advice.
///
/// The layer that refused says what is wrong with the file, which is the right
/// thing for a library to report and half of what a person at a terminal needs:
/// the other half is what to do instead. Only the cases with an actionable
/// answer are rewritten here — converting a JPEG, picking a larger image — and
/// everything else keeps the sentence the layer wrote, because inventing advice
/// for a corrupt file would be noise.
fn describe_rejection(path: &Path, error: &ValidationError) -> String {
    let file = path.display();

    match error {
        ValidationError::JpegDetected => format!(
            "Error: {file} is a JPEG and cannot be used as a container.\n       \
             Convert it to PNG first: magick input.jpg output.png\n       \
             Note that a PNG converted from a JPEG is refused as well; the \
             container must never have been JPEG-compressed."
        ),
        ValidationError::WebpDetected => format!(
            "Error: {file} is a WebP and cannot be used as a container.\n       \
             Only PNG containers that have never been through a lossy codec are \
             supported."
        ),
        ValidationError::NotPng => format!(
            "Error: {file} is not a PNG image.\n       \
             Containers must be PNG files of at least 2000x2000 pixels."
        ),
        ValidationError::ImageTooSmall { width, height, min } => format!(
            "Error: {file} is {width}x{height}, which is too small.\n       \
             Both sides must be at least {min} pixels."
        ),
        ValidationError::ImageTooLarge {
            width,
            height,
            pixels,
            max,
        } => format!(
            "Error: {file} is {width}x{height}, which is {} megapixels.\n       \
             Analysing an image that size needs more memory than this limit \
             allows,\n       \
             so it is refused immediately rather than left to exhaust the \
             machine.\n       \
             The maximum is {} megapixels; scale it down or use another photo.",
            pixels / (1024 * 1024),
            max / (1024 * 1024)
        ),
        ValidationError::UnsupportedColorSpace { .. } => format!(
            "Error: the pixel layout of {file} is not supported.\n       \
             Use an 8-bit or 16-bit RGB, RGBA or grayscale PNG."
        ),
        ValidationError::JpegArtifactsDetected { .. } => format!(
            "Error: {file} was JPEG-compressed at some point and re-saved as a \
             PNG.\n       \
             The 8x8 block grid it left behind is exactly what a steganalyst \
             looks for.\n       \
             Use a photo straight from a camera that was never saved as a JPEG."
        ),
        ValidationError::IoError(_) | ValidationError::DecodingError(_) => {
            format!("Error: {file}: {error}")
        }
    }
}

/// The rejection as `embed` reports it: [`describe_rejection`], plus a way to
/// find a container that would work.
///
/// A layer above that function rather than a change to it, because the very
/// same text serves `extract` — [`load_container`] is called by both — and there
/// the advice would answer a question nobody asked. Whoever runs `extract` was
/// handed one particular image and is trying to recover what is in it; they are
/// not looking through a folder for a better photograph, and `scan` has nothing
/// to offer them.
///
/// Only the refusals that are about *this image* are extended. A file that
/// cannot be read, or whose PNG stream is malformed, is a broken file rather
/// than a wrong choice of photograph: that user needs their file back, not a
/// different one, and pointing them at `scan` would be changing the subject.
fn describe_embed_rejection(path: &Path, error: &ValidationError) -> String {
    let message = describe_rejection(path, error);

    match error {
        ValidationError::JpegDetected
        | ValidationError::WebpDetected
        | ValidationError::NotPng
        | ValidationError::ImageTooSmall { .. }
        | ValidationError::ImageTooLarge { .. }
        | ValidationError::UnsupportedColorSpace { .. }
        | ValidationError::JpegArtifactsDetected { .. } => {
            format!("{message}{ANOTHER_CONTAINER_HINT}")
        }
        ValidationError::IoError(_) | ValidationError::DecodingError(_) => message,
    }
}

/// Runs the embedding path.
///
/// # Errors
///
/// Returns the message to print when the container is unusable, the destination
/// cannot receive a file, the payload file cannot be read, the message does not
/// fit, or the stego image cannot be written. Most of the text comes from the
/// layer that refused, which already phrases its failures for a user; see
/// [`describe_embed_failure`] for the one case that is rewritten.
fn run_embed(
    input: &Path,
    output: &Path,
    payload: Option<&Path>,
    force: bool,
) -> Result<(), String> {
    // Before anything is asked of the user: a container that will be refused is
    // refused now, rather than after a passphrase has been typed for nothing.
    drop(load_container_for_embed(input)?);

    // And the destination, for the same reason and at the same cost. Everything
    // this checks was knowable before the first byte was read; leaving it to the
    // write means learning it after the passphrase, the message and a minute of
    // Argon2id and HILL, with nothing to show for any of it.
    refuse_unwritable_output(output, force)?;

    // And for the same reason, a payload path that cannot be read is settled
    // here too — a mistyped path is exactly as much a wasted passphrase as a
    // JPEG is. The handle is kept rather than the verdict: reopening by path
    // after the prompt would leave a window in which the file that was checked
    // and the file that is read need not be the same one.
    let source = match payload {
        Some(path) => Some((payload::open_payload_file(path)?, path)),
        None => None,
    };

    let password = read_password()?;

    // With `--payload` standard input is not touched at all, redirected or not.
    let plaintext = match source {
        Some((handle, path)) => payload::read_payload_file(handle, path)?,
        None => read_plaintext()?,
    };

    if plaintext.is_empty() {
        return Err("Error: the message is empty; nothing to hide.".to_string());
    }

    // Embedding spends most of a minute on a large container — Argon2id at 128
    // MiB, then a HILL analysis of every pixel — with nothing to show for it
    // until it finishes. An indicator here reveals nothing: the work is a
    // function of the container's size and the payload's length, and the report
    // printed below states both.
    let activity = progress::Activity::start();

    let outcome = EmbedPipeline::default_secure().embed(input, plaintext, password, output);

    activity.finish();

    let report = outcome.map_err(|err| describe_embed_failure(&err))?;

    print_report(&report, output);
    Ok(())
}

/// Turns an embedding failure into the sentence the user reads.
///
/// Only one case is rewritten, on the same principle as [`describe_rejection`]:
/// the sizer knows the three numbers that make the refusal actionable but is
/// forbidden from printing them, because the same type answers a question about
/// a container the user may not own. At this end of the program the container
/// is theirs and the numbers are the whole answer.
///
/// The figure quoted is the payload *after* compression and encryption, and the
/// message says so. Reporting the file's size instead would tell a user that
/// their 30 KB of notes do not fit in a container that admits 22 KB, which is
/// false: Zstandard runs first, and text collapses.
///
/// Two other refusals are left in the words their own layer wrote and given the
/// pointer at `scan` that [`describe_embed_rejection`] adds, for the same
/// reason: a container too smooth to hide anything in, and one whose perceptual
/// hash will not survive the embedding, are both verdicts on this photograph and
/// on no other. They arrive here rather than at the validation gate because
/// neither can be decided without analysing every pixel. This function is
/// reached only from `run_embed`, so the pointer stays out of `extract` as it
/// does there.
fn describe_embed_failure(error: &PipelineError) -> String {
    match error {
        PipelineError::Sizer(SizerError::PayloadTooLarge {
            payload,
            available,
            deficit,
        }) => format!(
            "Error: the payload does not fit in this container.\n       \
             Compressed and encrypted it is {payload} bytes; the container \
             admits {available}.\n       \
             It is {deficit} bytes over.\n       \
             That first figure is the payload after compression, not the size \
             of the file:\n       \
             text shrinks a great deal, so a much larger file may still fit and \
             a smaller one may not.\n       \
             Use a container of higher resolution; stenoxide scan reports what \
             each one can carry."
        ),
        PipelineError::Cost(_)
        | PipelineError::PHash(PHashError::InsufficientStability { .. }) => {
            format!("Error: {error}.{ANOTHER_CONTAINER_HINT}")
        }
        other => format!("Error: {other}"),
    }
}

/// Runs the generative path.
///
/// The shape of [`run_embed`] minus the container: the payload is settled
/// before the passphrase is asked for, for the same reason, and there is no
/// image to validate because there is no image yet.
///
/// The requested size is settled first of all — before even the payload — so
/// that `--width 1999` is refused instantly rather than after a file has been
/// read and a passphrase typed. `clap` has already held each side to the 2000
/// floor; this is where the two are checked against the pixel ceiling together.
///
/// # Errors
///
/// Returns the message to print when the size is out of range, the destination
/// cannot receive a file, the payload file cannot be read, the payload does not
/// fit, or the container cannot be generated or written.
fn run_generate(
    output: &Path,
    input: Option<&Path>,
    width: u32,
    height: u32,
    force: bool,
    key_source: &GenerateKeySource,
) -> Result<(), String> {
    // In a release build the source can only ever be the password, but the
    // parameter exists so that one signature serves both builds.
    #[cfg(not(feature = "pqc"))]
    let _ = key_source;

    let dimensions =
        ContainerDimensions::new(width, height).map_err(|err| describe_generate_failure(&err))?;

    // Settled before the prompt, exactly as in `run_embed`: a destination that
    // cannot receive a file is knowable now, and generation is the slowest thing
    // this program does to find it out at the end.
    refuse_unwritable_output(output, force)?;

    // A payload path that cannot be read is settled before the prompt, exactly
    // as in `run_embed`: a mistyped path is a wasted passphrase either way, and
    // the handle is kept so that the file checked and the file read are one.
    let source = match input {
        Some(path) => Some((payload::open_payload_file(path)?, path)),
        None => None,
    };

    let plaintext = match source {
        Some((handle, path)) => payload::read_payload_file(handle, path)?,
        None => read_plaintext()?,
    };

    if plaintext.is_empty() {
        return Err("Error: the message is empty; nothing to hide.".to_string());
    }

    // Generation is the slowest thing this program does — two renders of twelve
    // million samples, the container gates over four megapixels, and a PNG of
    // incompressible content — and it says nothing while it works. The
    // indicator reveals nothing either: the cost is a function of a fixed
    // container size and of how many candidate textures the gates refuse.
    let activity = progress::Activity::start();

    // The two modes disagree on where the key comes from and on nothing else.
    // Both draw it before the container, because neither derives it from the
    // image, and both draw it after the payload: everything that can be settled
    // before a key is read is settled first, so that nothing is read for a
    // payload that turns out to be empty.
    #[cfg(feature = "pqc")]
    let outcome = match key_source {
        GenerateKeySource::Password => {
            let password = read_password()?;
            generate_container(plaintext, password, dimensions, output)
        }
        GenerateKeySource::Recipient(path) => {
            let recipient = read_recipient_key(path)?;
            generate_container_for_recipient(plaintext, &recipient, dimensions, output)
        }
    };
    #[cfg(not(feature = "pqc"))]
    let outcome = {
        let password = read_password()?;
        generate_container(plaintext, password, dimensions, output)
    };

    activity.finish();

    let report = outcome.map_err(|err| describe_generate_failure(&err))?;

    print_generate_report(&report, output);
    Ok(())
}

/// Reads a recipient's public key file.
///
/// The file is checked and read in one step rather than existence-checked and
/// then read: a file that is replaced between the two would pass the check and
/// be read from the wrong thing, and this is the one place in the program
/// where a file's *contents* are trusted as identity.
///
/// # Errors
///
/// Returns a message naming the path and why it was refused.
#[cfg(feature = "pqc")]
fn read_recipient_key(path: &Path) -> Result<RecipientKey, String> {
    let text = std::fs::read_to_string(path)
        .map_err(|err| format!("Error: could not read {}: {err}", path.display()))?;

    RecipientKey::from_public_file(&text)
        .map_err(|err| format!("Error: {} is not a usable recipient key: {err}", path.display()))
}

/// Turns a failure of the generator into the sentence the user reads.
///
/// Two cases are rewritten, and the rest keep the sentence their own layer
/// wrote. The capacity refusal is rewritten on the same principle as
/// [`describe_embed_failure`]: the figure quoted is the payload *after*
/// compression, and a message that did not say so would read as a false claim
/// about the size of the user's file. It now also names a larger container that
/// would fit and the two flags that ask for one — the whole point of the size
/// being a parameter is undone if the error does not say it is.
///
/// The out-of-range refusal is rewritten only to prefix it with `Error:` and to
/// name the two flags, so that a user who reached for them and overshot is
/// pointed back at the range rather than left with a bare library sentence.
fn describe_generate_failure(error: &GenerateError) -> String {
    match error {
        GenerateError::PayloadTooLarge {
            payload,
            available,
            deficit,
            recommended_side,
        } => describe_payload_too_large(*payload, *available, *deficit, *recommended_side),
        GenerateError::DimensionsOutOfRange { .. } => format!(
            "Error: {error}.\n       \
             Set the size with --width and --height; both must be at least 2000 \
             pixels."
        ),
        other => format!("Error: {other}"),
    }
}

/// The capacity refusal, with a container size to reach for.
///
/// The advice is the reason the size became a parameter: rather than "your
/// payload is too large, full stop", it quotes a square that would hold this
/// payload and the flags that ask for it. The suggestion is square because one
/// figure describes a square; a user who wants a different shape now knows the
/// area to aim for and can spend it on whatever width and height they like.
fn describe_payload_too_large(
    payload: usize,
    available: usize,
    deficit: usize,
    recommended_side: Option<u32>,
) -> String {
    let advice = match recommended_side {
        Some(side) => format!(
            "A larger container would hold it: at about {side}x{side} it fits.\n       \
             Ask for one with  --width {side} --height {side}  (both must be at \
             least 2000).\n       \
             Any width and height whose area is at least that will do; the \
             suggestion is square only because one number is easier to quote."
        ),
        // No permitted container is large enough. This is the payload's size,
        // not a dial the user can turn, so it is said plainly rather than
        // dressed up as a resolution to reach for.
        None => "No permitted container is large enough for a payload this size; \
                 a generated container is capped at 128 megapixels.\n       \
                 Split the payload, or compress it further before hiding it."
            .to_owned(),
    };

    format!(
        "Error: the payload does not fit in the requested container.\n       \
         Compressed and encrypted it is {payload} bytes; the container admits \
         {available}.\n       \
         It is {deficit} bytes over.\n       \
         That first figure is the payload after compression, not the size of \
         the file.\n       \
         {advice}"
    )
}

/// Prints what the generation did, on stdout.
///
/// The last line is not decoration. Someone reaching this subcommand has no
/// usable photograph and is likely to read "undetectable" as covering more than
/// it does, so the one thing the mode does not do is said where it cannot be
/// missed.
fn print_generate_report(report: &GenerateReport, output: &Path) {
    let (width, height) = report.image_dimensions;

    println!("Container generated at {}", output.display());
    println!("  Image dimensions: {width}x{height}");
    println!(
        "  Payload carried:  {} of {} bytes, compressed",
        report.payload_bytes, report.capacity_bytes
    );
    println!(
        "\nThis container does not hide that it was generated. It hides which of \
         several\ngenerated containers carries a message. Prefer an unpublished \
         photograph of your\nown whenever you have one."
    );
}

/// Prints what the embedding did, on stdout.
fn print_report(report: &EmbedReport, output: &Path) {
    let (width, height) = report.image_dimensions;

    println!("Stego image written to {}", output.display());
    println!("  Image dimensions: {width}x{height}");
    println!("  Pixels modified:  {}", report.pixels_modified);
    println!("  Payload embedded: {} bytes", report.payload_bytes);
    println!("  Effective rate:   {:.6} bpp", report.effective_bpp);
}

/// Runs the extraction path.
///
/// # Errors
///
/// Returns [`EXTRACTION_FAILED`], and nothing else, for every failure of the
/// pipeline. The error value is dropped without being formatted: a message
/// assembled from it would say which layer refused, which is the distinction
/// this function exists to withhold.
///
/// The pre-flight load is the one exception, and it is not one in substance: a
/// file that is not a PNG at all, or that no decoder can read, is not a stego
/// image anybody could have produced, and saying so reveals nothing an attacker
/// could not determine by opening the file themselves.
///
/// A successful extraction whose binary payload is bound for a terminal returns a
/// distinct guidance message instead; see [`write_recovered_to_stdout`] for why
/// that is not the oracle the failure sentence avoids.
fn run_extract(
    input: &Path,
    payload_out: Option<&Path>,
    force: bool,
    key_source: &ExtractKeySource,
) -> Result<(), String> {
    // As in `run_generate`: one signature for both builds, and the value can
    // only be the password in a release build.
    #[cfg(not(feature = "pqc"))]
    let _ = key_source;

    drop(load_container(input)?);

    if let Some(path) = payload_out {
        if !force {
            refuse_existing_destination(path)?;
        }
    }

    // The indeterminate indicator, and only that one. It names no stage and
    // reads identically whether the extraction is about to succeed or about to
    // fail; a staged bar here would announce which of the three failure modes
    // occurred, which is precisely what this function exists to withhold. See
    // the `progress` module.
    let activity = progress::Activity::start();

    // In the asymmetric mode there is no password to read at all. The identity
    // is instead unlocked before the work begins — an operation that is
    // separate from the extraction and reports its own failures, because it is
    // the one place a wrong passphrase can be told apart from a container that
    // carries nothing. See `Identity::open` for why that is not the oracle.
    #[cfg(feature = "pqc")]
    let outcome = match key_source {
        ExtractKeySource::Password => {
            let password = read_password()?;
            EmbedPipeline::default_secure().extract(input, password)
        }
        ExtractKeySource::Identity(path) => {
            let identity = read_identity(path)?;
            EmbedPipeline::default_secure().extract_with_identity(input, &identity)
        }
    };
    #[cfg(not(feature = "pqc"))]
    let outcome = {
        let password = read_password()?;
        EmbedPipeline::default_secure().extract(input, password)
    };

    // Both modes collapse to the same sentence, and the asymmetric mode does
    // so on purpose: a wrong identity, a container carrying nothing and a
    // damaged payload are deliberately one answer. Only the unlock above, over
    // a file the user owns, is allowed to say more.
    let outcome = outcome.map_err(|_| EXTRACTION_FAILED.to_string());

    // Cleared before the result is inspected, so that the last frame drawn is
    // the same one on both paths.
    activity.finish();

    let (plaintext, _report) = outcome?;

    // The buffer is still the `Zeroizing` the pipeline handed over, and it stays
    // one until the write is done: both destinations take a borrow of it, so no
    // copy of the plaintext is made that would outlive this function.
    match payload_out {
        Some(path) => write_recovered_file(path, plaintext.as_slice(), force),
        None => write_recovered_to_stdout(plaintext.as_slice()),
    }
}

/// Generates a key pair and writes the two files.
///
/// The public file is written first: it is the regenerable half, so if the
/// second write fails the pair is re-made rather than lost.
///
/// # Errors
///
/// Returns a message naming the step that failed, whether that is a
/// destination that already exists, the system generator, the sealing of the
/// private file, or a filesystem refusal.
#[cfg(feature = "pqc")]
fn run_keygen(public_path: &Path, private_path: &Path, force: bool) -> Result<(), String> {
    // Both destinations are settled before a single byte is drawn: a name that
    // already exists is knowable now, and the generator is the one step of this
    // command that has nothing to do with the filesystem.
    refuse_unwritable_output(public_path, force)?;
    refuse_unwritable_output(private_path, force)?;

    // The guidance is said before the first prompt so that a passphrase is
    // never typed before the reader knows what it protects.
    eprint!("{KEY_PASSPHRASE_GUIDANCE}");

    let passphrase = read_local_passphrase(true)?;

    let activity = progress::Activity::start();

    let identity = Identity::generate().map_err(|err| format!("Error: {err}"))?;

    // The seal pays one Argon2id at the production cost; the file passphrase is
    // exactly the kind of secret that cost exists to stretch, so nothing here
    // is substituted for speed.
    let public = identity.recipient().to_public_file();
    let private = identity
        .seal(
            &passphrase,
            &Argon2Kdf::default_secure(),
            &XChaCha20Poly1305Cipher::new(),
        )
        .map_err(|err| format!("Error: {err}"))?;
    drop(identity);

    activity.finish();

    // The public key is written with the same `create_new` discipline as any
    // payload file: an existing name is refused by the open rather than by a
    // preceding check, so the file that is overwritten is never the file that
    // was checked.
    payload::write_payload_file(public_path, public.as_bytes(), force)
        .map_err(|err| format!("Error: could not write {}: {err}", public_path.display()))?;
    payload::write_payload_file(private_path, private.as_bytes(), force)
        .map_err(|err| format!("Error: could not write {}: {err}", private_path.display()))?;

    eprintln!(
        "\nThe public key is in {}.",
        public_path.display()
    );
    eprintln!(
        "Send that file to anyone who wants to hide a message for you; it is meant to be published.",
    );
    eprintln!(
        "The private key is in {}. It stays on this machine.",
        private_path.display()
    );

    Ok(())
}

/// Unlocks a private key file, reading its own local passphrase.
///
/// The file is read and unlocked as one step rather than existence-checked and
/// then read: a file that is replaced between the two would be read from the
/// wrong thing, and this is the one place in the program where a file's
/// contents are trusted as identity.
///
/// # Errors
///
/// Returns a message naming the path and why it was refused. A wrong
/// passphrase is told apart from a damaged file, because the file is the
/// user's own and the distinction costs nothing to an adversary.
#[cfg(feature = "pqc")]
fn read_identity(path: &Path) -> Result<Identity, String> {
    // The file is read before the passphrase is asked for, so that a mistyped
    // path costs nothing but the message about it — the same "settled before
    // the prompt" discipline as everywhere else in this program.
    let text = std::fs::read_to_string(path)
        .map_err(|err| format!("Error: could not read {}: {err}", path.display()))?;

    let passphrase = read_local_passphrase(false)?;

    Identity::open(
        &text,
        &passphrase,
        &Argon2Kdf::default_secure(),
        &XChaCha20Poly1305Cipher::new(),
    )
    .map_err(|err| match err {
        KemError::WrongPassphrase => {
            format!("Error: the passphrase did not unlock {}.", path.display())
        }
        other => format!("Error: {} is not a usable identity: {other}", path.display()),
    })
}

/// Refuses a destination that already exists, before the password is asked for.
///
/// This check and the `create_new` inside [`payload::write_payload_file`] ask
/// the same question and are reported in opposite ways, which looks like an
/// inconsistency and is the opposite of one.
///
/// This one runs *before* anything has been attempted. At this point the
/// program does not yet know whether the password is right — it has not been
/// typed — so naming the file reveals nothing about the extraction. It is
/// ordinary, useful advice: the user mistyped a path or forgot `--force`, and
/// they are told so while it still costs them nothing.
///
/// The one inside the writer runs *after* a successful extraction, and by then
/// any message specific to it would be an admission that the password was
/// correct. So the file that appears in the gap between the two checks — a rare
/// race, but the rule takes no exceptions for rarity — is reported as
/// [`EXTRACTION_FAILED`], with everything else.
///
/// # Errors
///
/// Returns the message to print when `path` exists and is not a directory.
fn refuse_existing_destination(path: &Path) -> Result<(), String> {
    // A directory is not a collision: the payload is written *inside* it, under
    // a name that depends on content nobody has extracted yet.
    if path.is_dir() || !path.exists() {
        return Ok(());
    }

    Err(format!(
        "Error: {} already exists and would be overwritten.\n       \
         Choose another path, or pass --force to replace it.",
        path.display()
    ))
}

/// Refuses a destination `embed` and `generate` cannot write their image to.
///
/// # Why this is not [`refuse_existing_destination`]
///
/// The two ask what looks like the same question of the same kind of path, and
/// they have to answer it differently, because the destinations are not the same
/// kind of thing.
///
/// `extract` writes a payload whose *name* it derives from the content, so a
/// directory is a perfectly ordinary destination there: the file is written
/// inside it. That function therefore has to let a directory through, and
/// teaching it to refuse one would break the case it exists to serve.
///
/// `embed` and `generate` write an image to a path the user named in full. A
/// directory is not a destination they can complete — no name is derived from
/// anything — so it is a mistake, and the only useful answer is to say so. The
/// two functions are kept apart rather than given a flag because a shared
/// implementation would hold a condition that reverses the verdict on the one
/// case that separates them, which is the shape that gets edited wrong later.
///
/// # Why the missing folder is not created
///
/// Naming a folder that is not there is as likely to be a typo as an
/// instruction, and creating directories nobody asked for is the same silent
/// write this check exists to remove. The folder is named and nothing is
/// touched.
///
/// # Errors
///
/// Returns the message to print when `path` is a directory, when the folder that
/// would contain it does not exist, or when it already exists and `force` was not
/// given. The first two are refused whatever `force` says: that flag answers
/// "replace what is there", and neither of them is a file to replace.
fn refuse_unwritable_output(path: &Path, force: bool) -> Result<(), String> {
    if path.is_dir() {
        return Err(format!(
            "Error: {} is a directory, and --output names the file to write.\n       \
             Give the whole path, file name included: --output {}",
            path.display(),
            path.join("stego.png").display()
        ));
    }

    // An empty parent is what a bare file name yields, and it means the working
    // directory, which exists by definition.
    if let Some(parent) = path.parent() {
        if !parent.as_os_str().is_empty() && !parent.is_dir() {
            return Err(format!(
                "Error: the folder {} does not exist.\n       \
                 Create it first, or choose a path inside a folder that is \
                 already there.",
                parent.display()
            ));
        }
    }

    if !force && path.exists() {
        return Err(format!(
            "Error: {} already exists and would be overwritten.\n       \
             Choose another path, or pass --force to replace it.",
            path.display()
        ));
    }

    Ok(())
}

/// Writes the recovered payload to disk, and says nothing at all.
///
/// Success is silence and exit code zero: the user asked for a file, they got a
/// file, and a report printed alongside it would be one more thing to redirect.
///
/// # Errors
///
/// Returns [`EXTRACTION_FAILED`], whatever went wrong. A full disk, a directory
/// that stopped being writable and a destination that appeared a moment ago all
/// print the sentence a wrong password prints, because by this line the
/// extraction has already succeeded and any message specific to the write would
/// say so.
fn write_recovered_file(requested: &Path, plaintext: &[u8], force: bool) -> Result<(), String> {
    let destination = payload::resolve_output_path(requested, plaintext);

    payload::write_payload_file(&destination, plaintext, force)
        .map_err(|_| EXTRACTION_FAILED.to_string())
}

/// What extraction should do with a recovered payload bound for standard output.
#[derive(Debug, PartialEq, Eq)]
enum StdoutDelivery {
    /// Write the bytes to standard output unchanged.
    Raw,
    /// Refuse: the payload is binary and standard output is a terminal.
    RefuseBinary,
}

/// Decides how a recovered payload reaches standard output.
///
/// The bytes go out raw whenever standard output is **not** a terminal — a
/// redirection or a pipe takes binary and text alike, and that path must never
/// change, because it is the whole way a binary payload is captured
/// (`extract > payload.bin`). Only a payload that is *both* binary *and* bound
/// for an interactive terminal is refused: a terminal cannot render it. On
/// Windows the console rejects bytes that are not valid UTF-8 outright — the
/// write fails, which is the bug this function exists to turn into a clear
/// message — and on a Unix terminal the same bytes would reset colours, move the
/// cursor and ring the bell.
///
/// "Binary" is "not valid UTF-8", the same test [`payload::detect_extension`]
/// draws between a `txt` and a `bin` payload, so the two agree on what counts as
/// text.
fn stdout_delivery(stdout_is_terminal: bool, plaintext: &[u8]) -> StdoutDelivery {
    if stdout_is_terminal && std::str::from_utf8(plaintext).is_err() {
        StdoutDelivery::RefuseBinary
    } else {
        StdoutDelivery::Raw
    }
}

/// Writes a recovered payload to standard output, or explains why it will not.
///
/// Two destinations wear the same file descriptor and are not served the same
/// way, as in [`read_plaintext`]:
///
/// - **A pipe or a redirection.** `extract > payload.bin`, or a pipe into
///   another program. Every byte matters and the payload goes out raw whatever
///   it contains. A write that fails here — a broken pipe, a full disk — folds
///   into [`EXTRACTION_FAILED`] like every other post-success write error, so it
///   cannot become an admission that the password was right.
///
/// - **A terminal.** A person is watching. A text payload is shown; a binary one
///   is announced rather than dumped, with the two ways to capture it, for the
///   reasons in [`stdout_delivery`].
///
/// # Why the terminal notice is not the oracle the failure sentence avoids
///
/// The notice reveals that extraction succeeded — but a text payload shown on
/// the same terminal reveals exactly as much, and so does a file that appears
/// under `--payload-out` or a redirection. Success is inherent in producing the
/// plaintext and cannot be hidden from whoever runs the command. What the single
/// [`EXTRACTION_FAILED`] sentence hides is *which* of the three failures happened
/// and whether a post-success *write* failed on the redirected path; the notice
/// is a refusal decided *before* any write and touches neither.
///
/// # Errors
///
/// Returns [`EXTRACTION_FAILED`] when the raw write fails, and the binary-payload
/// guidance when standard output is a terminal the payload cannot be shown on.
fn write_recovered_to_stdout(plaintext: &[u8]) -> Result<(), String> {
    match stdout_delivery(io::stdout().is_terminal(), plaintext) {
        // The payload is whatever the sender put in, written as raw bytes rather
        // than through a string conversion that would corrupt anything not valid
        // UTF-8.
        StdoutDelivery::Raw => io::stdout()
            .write_all(plaintext)
            .and_then(|()| io::stdout().flush())
            .map_err(|_| EXTRACTION_FAILED.to_string()),
        StdoutDelivery::RefuseBinary => Err(binary_payload_notice(plaintext)),
    }
}

/// The notice a binary payload bound for a terminal gets instead of its bytes.
///
/// It names the type, because the program already knows it:
/// [`payload::detect_extension`] is what puts a name on the file written under
/// `--payload-out`, and reading it here costs nothing and turns "binary data,
/// try `> payload.bin`" into an example the user can paste. Nothing new is
/// revealed by it — by this line the extraction has already succeeded and the
/// plaintext is in the caller's hands; see [`write_recovered_to_stdout`] for why
/// that is not the oracle the single failure sentence avoids.
///
/// Both ways of capturing the payload are kept, in the same order they were
/// offered in: naming the type is an improvement to the example, not a
/// replacement for the advice.
fn binary_payload_notice(plaintext: &[u8]) -> String {
    let extension = payload::detect_extension(plaintext);

    // `bin` is the table's way of saying it recognised nothing, so there is no
    // type to name and the sentence keeps the words it always used.
    let described = if extension == payload::BINARY_EXTENSION {
        "binary data".to_owned()
    } else {
        format!("{} data", extension.to_uppercase())
    };

    format!(
        "The payload is {} bytes of {described} and will not be written to the terminal.\n       \
         Redirect it to a file (for example: > payload.{extension}) or pass --payload-out PATH.",
        plaintext.len()
    )
}

/// Writes the completion script for `shell` to standard output.
///
/// # Errors
///
/// Returns the message to print when standard output cannot be written.
fn run_completions(shell: Shell) -> Result<(), String> {
    write_artifact(&completion_script(shell), "completion script")
}

/// The completion script for `shell`, as the bytes that make it up.
///
/// Rendered into memory rather than straight onto standard output for two
/// reasons. The generator writes through an interface that cannot report a
/// failure, so a closed pipe would end the process on its terms rather than on
/// this program's; and a buffer is something a test can read back, which a
/// console is not.
fn completion_script(shell: Shell) -> Vec<u8> {
    let mut command = Cli::command();
    let name = command.get_name().to_string();
    let mut script = Vec::new();

    generate(shell, &mut command, name, &mut script);

    script
}

/// Writes the manual page to standard output.
///
/// # Errors
///
/// Returns the message to print when the page cannot be rendered or standard
/// output cannot be written.
fn run_man() -> Result<(), String> {
    write_artifact(&manual_page()?, "manual page")
}

/// The roff source of `stenoxide.1`, as the bytes that make it up.
///
/// One page, for the root command; see the `man` subcommand for why there is no
/// page per subcommand.
///
/// # Errors
///
/// Returns the message to print when the renderer fails, which for a buffer in
/// memory it cannot — the case is carried rather than discarded so that no
/// failure of the layer below is swallowed here.
fn manual_page() -> Result<Vec<u8>, String> {
    let mut page = Vec::new();

    clap_mangen::Man::new(Cli::command())
        .render(&mut page)
        .map_err(|err| format!("Error: could not render the manual page: {err}"))?;

    Ok(page)
}

/// Writes a generated artifact to standard output, and nothing besides it.
///
/// No banner, no progress line, no blank line of courtesy. What is written here
/// is read by a shell being asked to source it or by a packager's redirection
/// into a `.1` file, and a single byte of this program's own would break the
/// first and corrupt the second. Only the failure speaks, and it speaks on
/// stderr like everything else addressed to a person.
///
/// # Errors
///
/// Returns the message to print when standard output cannot be written, naming
/// `what` was being written.
fn write_artifact(bytes: &[u8], what: &str) -> Result<(), String> {
    io::stdout()
        .write_all(bytes)
        .and_then(|()| io::stdout().flush())
        .map_err(|err| format!("Error: could not write the {what}: {err}"))
}

/// Payload bytes `image` can carry after encryption, and the salt its
/// perceptual hash derives.
///
/// `None` when a layer above the loader refuses the container, which is a
/// verdict of "unusable" rather than a capacity of zero.
///
/// The salt is returned rather than discarded because the gate below already
/// computes it, and because it is the only thing that can tell a caller holding
/// two containers that they are one container: the key and the nonce come from
/// this value and the password, so two images that produce it are
/// indistinguishable to the derivation. `scan` uses it for exactly that.
///
/// # Why the hash is checked here and not only the cost map
///
/// A uniform image passes every gate of layer 1 — it is a PNG, it is large
/// enough, and it carries no block structure — and the cost model accepts it
/// too: cost is the reciprocal of texture energy, so a flat container yields
/// the *highest* cost everywhere and clears a floor written to catch images
/// that are high-energy everywhere. What refuses it is the perceptual hash,
/// whose 64 coefficients all pile up around a near-zero median.
///
/// That makes the hash a load-bearing part of the answer rather than a detail
/// of the embedding path: without it `scan` would report a smooth photograph as
/// a usable container and `embed` would refuse the very same file.
fn analyse_container(image: &ImageBuffer) -> Option<(usize, PHashSalt)> {
    let salt = compute_stable_phash(image).ok()?;

    let cost_map = HillCostProvider::new().compute(image).ok()?;

    Some((
        compute_capacity(&cost_map, EmbeddingMode::Symmetric).available_bytes(),
        salt,
    ))
}

/// Whether the terminal can be expected to render the marks `scan` prints.
///
/// A pipe gets the Unicode forms unconditionally: its consumer is a file or
/// another program, and the encoding of a terminal that is not attached says
/// nothing about what that consumer can read. A Windows console gets them only
/// when its code page is UTF-8, because the legacy pages have no glyph for
/// either mark and would print a question mark or a box.
fn terminal_renders_unicode() -> bool {
    #[cfg(windows)]
    {
        if io::stdout().is_terminal() {
            // 65001 is CP_UTF8. Read through the same call the console itself
            // is configured with rather than through an environment variable,
            // which a shell may set without the console honouring it.
            return console_output_code_page() == 65_001;
        }
    }

    true
}

/// The code page the Windows console is writing in.
#[cfg(windows)]
fn console_output_code_page() -> u32 {
    // The one foreign call in this crate, and the reason it is here rather than
    // behind a dependency: asking the console what it can print is a single
    // parameterless query, and pulling in a Windows API crate to make it would
    // be a larger surface than the question deserves.
    extern "system" {
        fn GetConsoleOutputCP() -> u32;
    }

    // SAFETY: `GetConsoleOutputCP` takes no arguments, returns a plain integer,
    // touches no memory the caller owns and cannot fail — a process with no
    // console attached gets zero, which this crate reads as "not UTF-8".
    #[allow(unsafe_code)]
    unsafe {
        GetConsoleOutputCP()
    }
}

#[cfg(test)]
mod tests {
    #![allow(clippy::expect_used)]

    use clap::ValueEnum;
    use stenoxide_core::cost::hill::CostError;

    use super::*;

    /// Runs the typed-message reader over what a console would have delivered.
    fn typed(keystrokes: &str) -> String {
        let mut input = io::Cursor::new(keystrokes.as_bytes().to_vec());
        let message = collect_typed_lines(&mut input).expect("a cursor cannot fail to read");

        String::from_utf8(message.to_vec()).expect("the fixtures are all UTF-8")
    }

    /// A dot on its own line ends the message and is not part of it.
    ///
    /// The whole reason the terminator exists: `Ctrl+Z` never reaches this
    /// process under PowerShell, so if this line did not end the message there
    /// would be no way to finish one at a Windows prompt.
    #[test]
    fn a_lone_dot_ends_the_message() {
        assert_eq!(typed("a secret\n.\n"), "a secret");
        assert_eq!(typed("a secret\r\n.\r\n"), "a secret");
    }

    /// Anything typed after the terminator is not read.
    ///
    /// The reader stops at the dot rather than draining the stream, so that
    /// whatever the user types next belongs to their shell and not to a message
    /// they thought they had already closed.
    #[test]
    fn nothing_after_the_terminator_is_taken() {
        assert_eq!(typed("kept\n.\nnot this\n"), "kept");
    }

    /// A message may span lines, blank ones included.
    #[test]
    fn the_message_may_span_several_lines() {
        assert_eq!(typed("one\ntwo\n\nfour\n.\n"), "one\ntwo\n\nfour");
    }

    /// End of file still ends the message, terminator or not.
    ///
    /// The dot is an addition rather than a replacement: a terminal that does
    /// deliver `Ctrl+D` or `Ctrl+Z` keeps working exactly as it used to.
    #[test]
    fn end_of_file_still_ends_the_message() {
        assert_eq!(typed("a secret\n"), "a secret");
        assert_eq!(typed("no newline at all"), "no newline at all");
        assert_eq!(typed(""), "");
    }

    /// A dot is only a terminator on a line of its own.
    ///
    /// Ordinary prose ends in one constantly, and a message truncated at its
    /// first full stop would be a data-loss bug in the name of convenience.
    #[test]
    fn a_dot_within_a_line_is_text() {
        assert_eq!(
            typed("Meet me at six. Bring it.\n.\n"),
            "Meet me at six. Bring it."
        );
        assert_eq!(typed("..\n.\n"), "..");
        assert_eq!(typed(" .\n.\n"), " .");
    }

    /// Typing only the terminator produces nothing.
    ///
    /// Which is what makes `run_embed`'s empty-message check the thing that
    /// reports it, rather than the pipeline failing later over a payload nobody
    /// meant to send.
    #[test]
    fn a_message_that_is_only_the_terminator_is_empty() {
        assert!(typed(".\n").is_empty());
    }

    /// Bytes that are not valid UTF-8 survive the trip.
    ///
    /// A console running a legacy code page hands over whatever it hands over,
    /// and the message is bytes to everything downstream of here.
    #[test]
    fn invalid_utf8_is_carried_through_unchanged() {
        let mut input = io::Cursor::new(b"caf\xe9\n.\n".to_vec());
        let message = collect_typed_lines(&mut input).expect("a cursor cannot fail to read");

        assert_eq!(message.as_slice(), b"caf\xe9");
    }

    /// A payload that does not fit is told the three numbers, and what they mean.
    ///
    /// The sizer refuses without naming any of them, deliberately, because the
    /// same type answers questions about containers the caller may not own. At
    /// this end of the program the container is the user's and the numbers are
    /// the entire answer — but only if the message also says that the figure is
    /// the *compressed* payload, because otherwise it reads as a claim about
    /// their file that is simply false.
    #[test]
    fn a_payload_that_does_not_fit_is_told_by_how_much() {
        let message = describe_embed_failure(&PipelineError::Sizer(SizerError::PayloadTooLarge {
            payload: 30_000,
            available: 22_016,
            deficit: 7_984,
        }));

        assert!(message.contains("30000"), "got: {message}");
        assert!(message.contains("22016"), "got: {message}");
        assert!(message.contains("7984"), "got: {message}");
        assert!(
            message.contains("after compression"),
            "the message must not read as a claim about the file's size: {message}"
        );
        assert!(message.contains("stenoxide scan"), "got: {message}");
    }

    /// Every other pipeline failure keeps the sentence its own layer wrote.
    #[test]
    fn other_failures_are_printed_as_the_layer_phrased_them() {
        let error = PipelineError::Validation(ValidationError::NotPng);
        let message = describe_embed_failure(&error);

        assert_eq!(message, format!("Error: {error}"));
    }

    /// A container refused for this image alone points at `scan`.
    ///
    /// Every rejection that says something about *this photograph* — its
    /// format, its size, its pixel layout, the JPEG grid in it — is a rejection
    /// the user answers by choosing a different one, and `scan` is how they find
    /// which of theirs would do. The reason the whole list is pinned rather than
    /// one case: the hint is added per variant, so a variant left out is a user
    /// who reaches the same dead end through a different door.
    #[test]
    fn a_rejected_photograph_is_pointed_at_scan() {
        let path = Path::new("photo.png");
        let rejections = [
            ValidationError::JpegDetected,
            ValidationError::WebpDetected,
            ValidationError::NotPng,
            ValidationError::ImageTooSmall {
                width: 800,
                height: 600,
                min: 2_000,
            },
            ValidationError::ImageTooLarge {
                width: 20_000,
                height: 20_000,
                pixels: 400_000_000,
                max: 134_217_728,
            },
            ValidationError::UnsupportedColorSpace {
                found: "Rgb32F".to_owned(),
            },
            ValidationError::JpegArtifactsDetected { ratio: 1.8 },
        ];

        for error in &rejections {
            let message = describe_embed_rejection(path, error);

            assert!(
                message.contains("stenoxide scan"),
                "{error:?} must point at scan, got: {message}"
            );
            // The advice is added to the existing explanation, never in place
            // of it: the user still has to be told what was wrong with the file.
            assert!(
                message.starts_with(&describe_rejection(path, error)),
                "the original explanation must survive, got: {message}"
            );
        }
    }

    /// A file that is broken is not told to go and find another one.
    ///
    /// The distinction the hint rests on: a missing file and a malformed PNG are
    /// problems with the file itself, and a user whose disk failed mid-copy is
    /// not choosing between photographs.
    #[test]
    fn a_broken_file_is_not_pointed_at_scan() {
        let path = Path::new("photo.png");
        let broken = [
            ValidationError::IoError(io::Error::new(io::ErrorKind::NotFound, "no such file")),
            ValidationError::DecodingError("truncated stream".to_owned()),
        ];

        for error in &broken {
            let message = describe_embed_rejection(path, error);

            assert_eq!(
                message,
                describe_rejection(path, error),
                "{error:?} must be reported exactly as it always was"
            );
        }
    }

    /// Extraction reports a rejected image exactly as it always did.
    ///
    /// The hint belongs to `embed` alone. Somebody running `extract` was given
    /// one image and wants what is inside it; telling them to scan a folder for
    /// a better photograph would answer a question they did not ask, which is
    /// why the advice is a layer above the shared description rather than in it.
    #[test]
    fn extraction_keeps_the_plain_rejection() {
        let path = Path::new("stego.png");
        let message = describe_rejection(path, &ValidationError::NotPng);

        assert!(
            !message.contains("stenoxide scan"),
            "the shared description must stay free of the embed hint, got: {message}"
        );
    }

    /// A container too smooth, or too unstable, to embed in points at `scan`.
    ///
    /// These two refusals arrive after the analysis rather than at the door,
    /// because neither can be decided without reading every pixel — but they say
    /// the same thing as the rejections above: this photograph will not do. The
    /// sentence the layer wrote is kept in full; only the way out is added.
    #[test]
    fn an_untextured_container_is_pointed_at_scan() {
        let smooth = PipelineError::Cost(CostError::ExcessiveSmoothRegions { ratio: 0.42 });
        let message = describe_embed_failure(&smooth);

        assert!(message.contains("too smooth"), "got: {message}");
        assert!(message.contains("stenoxide scan"), "got: {message}");

        let unstable = PipelineError::PHash(PHashError::InsufficientStability {
            unstable_bits: 3,
            threshold: 0.05,
        });
        let message = describe_embed_failure(&unstable);

        assert!(message.contains("perceptually unstable"), "got: {message}");
        assert!(message.contains("stenoxide scan"), "got: {message}");
    }

    /// An oversized generated payload is told the numbers and a size to reach.
    ///
    /// The generator's counterpart of the embed test above, plus the one thing
    /// this mode adds: the size is a parameter, so the message names a container
    /// that would fit and the two flags that ask for it. Quoting the numbers but
    /// not the way out would leave the user with a resolution they cannot act on.
    #[test]
    fn an_oversized_generated_payload_names_a_size_and_the_flags() {
        let message = describe_generate_failure(&GenerateError::PayloadTooLarge {
            payload: 1_782_778,
            available: 1_499_980,
            deficit: 282_798,
            recommended_side: Some(2_200),
        });

        assert!(message.contains("1782778"), "got: {message}");
        assert!(message.contains("1499980"), "got: {message}");
        assert!(message.contains("282798"), "got: {message}");
        assert!(
            message.contains("after compression"),
            "the message must not read as a claim about the file's size: {message}"
        );
        // The way out: a concrete size and the flags that request it.
        assert!(message.contains("2200x2200"), "got: {message}");
        assert!(message.contains("--width 2200"), "got: {message}");
        assert!(message.contains("--height 2200"), "got: {message}");
    }

    /// A payload no container can hold is told so plainly, with no size to chase.
    ///
    /// The `None` recommendation is not "try a bigger number"; it is the pixel
    /// ceiling, so the advice has to change from a resolution to a suggestion to
    /// split or compress the payload.
    #[test]
    fn a_payload_beyond_every_container_is_told_plainly() {
        let message = describe_generate_failure(&GenerateError::PayloadTooLarge {
            payload: 60_000_000,
            available: 1_499_980,
            deficit: 58_500_020,
            recommended_side: None,
        });

        assert!(message.contains("No permitted container"), "got: {message}");
        assert!(message.contains("128 megapixels"), "got: {message}");
        assert!(!message.contains("--width"), "no size to reach: {message}");
    }

    /// An out-of-range size is prefixed and pointed back at the two flags.
    #[test]
    fn an_out_of_range_size_names_the_flags() {
        let message = describe_generate_failure(&GenerateError::DimensionsOutOfRange {
            width: 1_500,
            height: 3_000,
            min_side: MIN_CONTAINER_SIDE,
            max_pixels: stenoxide_core::generate::MAX_CONTAINER_PIXELS,
        });

        assert!(message.starts_with("Error:"), "got: {message}");
        assert!(message.contains("1500x3000"), "got: {message}");
        assert!(message.contains("--width"), "got: {message}");
        assert!(message.contains("--height"), "got: {message}");
    }

    /// A destination that is not there yet, and a directory, are both fine.
    ///
    /// The directory case is the one worth pinning: the payload is written
    /// *inside* it under a name that depends on content nobody has extracted
    /// yet, so treating it as a collision would refuse a command that is
    /// perfectly well formed.
    #[test]
    fn only_an_existing_file_blocks_the_destination() {
        let directory = tempfile::TempDir::new().expect("temporary directory");

        assert!(refuse_existing_destination(directory.path()).is_ok());
        assert!(refuse_existing_destination(&directory.path().join("new.zip")).is_ok());

        let taken = directory.path().join("taken.zip");
        std::fs::write(&taken, b"already here").expect("fixture write");

        let message =
            refuse_existing_destination(&taken).expect_err("an existing file must be refused");
        assert!(message.contains("taken.zip"), "got: {message}");
        assert!(message.contains("--force"), "got: {message}");
    }

    /// A redirection or a pipe takes binary and text alike.
    ///
    /// The path a binary payload is captured through — `extract > payload.bin` —
    /// and the one that must never start sniffing content, because its consumer
    /// is a file or another program that asked for every byte.
    #[test]
    fn a_redirection_takes_binary_and_text_alike() {
        assert_eq!(stdout_delivery(false, b"plain text"), StdoutDelivery::Raw);
        assert_eq!(
            stdout_delivery(false, &[0xFF, 0xD8, 0xFF, 0xE0]),
            StdoutDelivery::Raw,
            "a redirection must take a JPEG's bytes unchanged"
        );
    }

    /// A terminal shows text and refuses binary.
    ///
    /// The bug this fixes: a JPEG begins `FF D8 FF`, which is invalid UTF-8, and
    /// a Windows console cannot be handed it — the write fails and the extraction
    /// looks like it failed when it did not.
    #[test]
    fn a_terminal_shows_text_but_refuses_binary() {
        assert_eq!(
            stdout_delivery(true, b"a readable message"),
            StdoutDelivery::Raw
        );
        assert_eq!(
            stdout_delivery(true, &[0xFF, 0xD8, 0xFF, 0xE0]),
            StdoutDelivery::RefuseBinary
        );
    }

    /// Accented text is still text on a terminal.
    ///
    /// The binary test is UTF-8 validity, not ASCII, so a message with accents
    /// is shown rather than refused.
    #[test]
    fn accented_text_is_shown_on_a_terminal() {
        assert_eq!(
            stdout_delivery(true, "café — ñandú".as_bytes()),
            StdoutDelivery::Raw
        );
    }

    /// Every shell the generator supports produces a script.
    ///
    /// The list is walked rather than spelled out, so that a shell added by a
    /// future release of the generator is covered the day it appears.
    #[test]
    fn every_supported_shell_gets_a_script() {
        for shell in Shell::value_variants() {
            let script = completion_script(*shell);

            assert!(!script.is_empty(), "{shell} produced no completion script");
        }
    }

    /// The manual page carries the title macro every man page opens with.
    ///
    /// A cheap guard against the failure that would matter: anything printed to
    /// standard output that is not the page itself ends up inside the `.1` file
    /// a packager redirects, and a message would be as invisible there as it is
    /// obvious here. The macro is looked for rather than required at the very
    /// start of the file because the renderer emits the two-line apostrophe
    /// definition every roff page carries ahead of it.
    #[test]
    fn the_manual_page_is_roff() {
        let page = manual_page().expect("a page rendered into memory cannot fail");
        let page = String::from_utf8(page).expect("the page is UTF-8");

        assert!(page.contains(".TH stenoxide 1"), "no title macro in: {page}");
        assert!(page.contains(".SH NAME"), "no name section in: {page}");
    }

    /// Nothing precedes the artifact on standard output.
    ///
    /// The direct check of the rule these two subcommands exist under: the very
    /// first line is already the script or the page. A banner, or a blank line
    /// of courtesy, would break `source <(stenoxide completions bash)` and
    /// corrupt a redirected manual page — and would pass every other test here.
    #[test]
    fn the_first_line_is_already_the_artifact() {
        let script = completion_script(Shell::Bash);
        let script = String::from_utf8(script).expect("the script is UTF-8");
        let first = script.lines().next().unwrap_or_default();

        assert!(
            first.starts_with('#') || first.starts_with('_'),
            "a bash script opens with a comment or a function, got: {first:?}"
        );

        let page = manual_page().expect("a page rendered into memory cannot fail");
        let page = String::from_utf8(page).expect("the page is UTF-8");
        let first = page.lines().next().unwrap_or_default();

        assert!(
            first.starts_with('.'),
            "a roff page opens with a control line, got: {first:?}"
        );
    }

    /// The command definition still parses every argument it used to.
    ///
    /// Two subcommands were added beside the four that do the work; this pins
    /// that they were added and nothing was disturbed — the flags of `embed`
    /// and `extract` keep their names, and the definition itself stays
    /// internally consistent, which is what `debug_assert` on a `clap` command
    /// checks.
    #[test]
    fn the_existing_arguments_are_untouched() {
        Cli::command().debug_assert();

        let cli = Cli::try_parse_from([
            "stenoxide",
            "embed",
            "--input",
            "cover.png",
            "--output",
            "stego.png",
            "--payload",
            "secret.zip",
        ])
        .expect("the embed arguments must keep parsing");

        assert!(
            matches!(
                cli.command,
                Command::Embed { input, output, payload, force }
                    if input == Path::new("cover.png")
                        && output == Path::new("stego.png")
                        && payload.as_deref() == Some(Path::new("secret.zip"))
                        && !force
            ),
            "embed must still parse into the same three paths"
        );
    }

    /// Every short flag parses to exactly what its long form parses to.
    ///
    /// Written as whole command lines rather than as a table of letters,
    /// because what has to hold is that the two spellings are interchangeable —
    /// a short form attached to the wrong field would still be a valid flag and
    /// would still parse, and only the value it lands in tells them apart. The
    /// short line is built by substitution, so the two differ in nothing else.
    #[test]
    fn every_short_flag_means_what_its_long_form_means() {
        let cases: &[(&[&str], &[&str])] = &[
            (
                &[
                    "stenoxide",
                    "embed",
                    "--input",
                    "cover.png",
                    "--output",
                    "stego.png",
                    "--payload",
                    "secret.zip",
                    "--force",
                ],
                &[
                    "stenoxide", "embed", "-i", "cover.png", "-o", "stego.png", "-p", "secret.zip",
                    "-f",
                ],
            ),
            (
                &[
                    "stenoxide",
                    "extract",
                    "--input",
                    "stego.png",
                    "--payload-out",
                    "secret.zip",
                    "--force",
                ],
                &[
                    "stenoxide",
                    "extract",
                    "-i",
                    "stego.png",
                    "-o",
                    "secret.zip",
                    "-f",
                ],
            ),
            (
                &[
                    "stenoxide",
                    "generate",
                    "--output",
                    "container.png",
                    "--input",
                    "message.txt",
                    "--force",
                ],
                &[
                    "stenoxide",
                    "generate",
                    "-o",
                    "container.png",
                    "-p",
                    "message.txt",
                    "-f",
                ],
            ),
            (
                &["stenoxide", "scan", "./photos", "--all", "--recursive"],
                &["stenoxide", "scan", "./photos", "-a", "-r"],
            ),
        ];

        for (long, short) in cases {
            let spelled_out = Cli::try_parse_from(*long).map(|cli| format!("{:?}", Rendered(&cli)));
            let abbreviated = Cli::try_parse_from(*short).map(|cli| format!("{:?}", Rendered(&cli)));

            assert_eq!(
                spelled_out.as_deref().ok(),
                abbreviated.as_deref().ok(),
                "{short:?} must parse to what {long:?} parses to"
            );
            assert!(spelled_out.is_ok(), "{long:?} stopped parsing");
        }
    }

    /// Every field of a parsed command line, as text two parses can be compared
    /// on.
    ///
    /// `Command` carries paths and flags and derives nothing, and deriving
    /// `Debug` on it for the sake of one test would put a formatter on a type
    /// that holds the user's file names. Rendering it here keeps that where the
    /// test is.
    struct Rendered<'cli>(&'cli Cli);

    impl std::fmt::Debug for Rendered<'_> {
        fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
            match &self.0.command {
                Command::Scan(args) => write!(
                    formatter,
                    "scan {} all={} recursive={} json={}",
                    args.path, args.all, args.recursive, args.json
                ),
                Command::Embed {
                    input,
                    output,
                    payload,
                    force,
                } => write!(
                    formatter,
                    "embed {} {} {payload:?} force={force}",
                    input.display(),
                    output.display()
                ),
                Command::Generate {
                    output,
                    input,
                    width,
                    height,
                    #[cfg(feature = "pqc")]
                    recipient,
                    force,
                } => {
                    #[cfg(feature = "pqc")]
                    let recipient = match recipient {
                        Some(path) => format!(" recipient={}", path.display()),
                        None => String::new(),
                    };
                    #[cfg(not(feature = "pqc"))]
                    let recipient = String::new();
                    write!(
                        formatter,
                        "generate {} {input:?} {width}x{height} force={force}{recipient}",
                        output.display()
                    )
                }
                #[cfg(feature = "pqc")]
                Command::Keygen {
                    public,
                    private,
                    force,
                } => write!(
                    formatter,
                    "keygen {} {} force={force}",
                    public.display(),
                    private.display()
                ),
                Command::Extract {
                    input,
                    #[cfg(feature = "pqc")]
                    identity,
                    payload_out,
                    force,
                } => {
                    #[cfg(feature = "pqc")]
                    let identity = match identity {
                        Some(path) => format!(" identity={}", path.display()),
                        None => String::new(),
                    };
                    #[cfg(not(feature = "pqc"))]
                    let identity = String::new();
                    write!(
                        formatter,
                        "extract {} {payload_out:?} force={force}{identity}",
                        input.display()
                    )
                }
                Command::Completions { shell } => write!(formatter, "completions {shell}"),
                Command::Man => write!(formatter, "man"),
            }
        }
    }

    /// `-h` is `--help` in every subcommand, and nothing else ever takes it.
    ///
    /// The one letter that cannot be reassigned: a user who types it expects the
    /// help, and `generate --height` is exactly the flag that would have been
    /// tempting to give it to.
    #[test]
    fn the_help_letter_is_never_reassigned() {
        for subcommand in ["scan", "embed", "extract", "generate"] {
            let outcome = Cli::try_parse_from(["stenoxide", subcommand, "-h"])
                .err()
                .map(|error| error.kind());

            assert_eq!(
                outcome,
                Some(clap::error::ErrorKind::DisplayHelp),
                "-h must print the help of {subcommand}"
            );
        }
    }

    /// A directory is refused as an output, and `--force` does not change that.
    ///
    /// The reported failure: `--output .\5-salida\` was accepted, the passphrase
    /// and the message were typed, a minute of Argon2id and HILL was spent, and
    /// the operating system refused the write at the end. Everything needed to
    /// say no was on disk before any of it started.
    #[test]
    fn a_directory_is_not_an_output_path() {
        let directory = tempfile::TempDir::new().expect("temporary directory");

        for force in [false, true] {
            let message = refuse_unwritable_output(directory.path(), force)
                .expect_err("a directory cannot receive the image");

            assert!(message.contains("is a directory"), "got: {message}");
            // The way out is the whole point: the user has to be told that the
            // flag takes a file name, and shown one.
            assert!(message.contains("--output"), "got: {message}");
            assert!(message.contains("stego.png"), "got: {message}");
        }
    }

    /// An existing file is refused, and `--force` is what replaces it.
    ///
    /// Without the check the write truncates it silently and reports success,
    /// which destroys the stego image that was there and the message it carried.
    #[test]
    fn an_existing_output_is_refused_unless_forced() {
        let directory = tempfile::TempDir::new().expect("temporary directory");
        let taken = directory.path().join("stego.png");
        std::fs::write(&taken, b"an earlier stego image").expect("fixture write");

        let message =
            refuse_unwritable_output(&taken, false).expect_err("an existing file must be refused");
        assert!(message.contains("stego.png"), "got: {message}");
        assert!(message.contains("already exists"), "got: {message}");
        assert!(message.contains("--force"), "got: {message}");

        assert!(
            refuse_unwritable_output(&taken, true).is_ok(),
            "--force is what replaces a file that is already there"
        );
    }

    /// A folder that is not there is named, and is not created.
    ///
    /// `--force` does not apply: there is no file to replace, and creating the
    /// folder would be exactly the write nobody asked for that this check exists
    /// to remove.
    #[test]
    fn a_missing_folder_is_named_and_left_alone() {
        let directory = tempfile::TempDir::new().expect("temporary directory");
        let missing = directory.path().join("nowhere");
        let destination = missing.join("stego.png");

        for force in [false, true] {
            let message = refuse_unwritable_output(&destination, force)
                .expect_err("a missing folder must be refused");

            assert!(message.contains("nowhere"), "got: {message}");
            assert!(message.contains("does not exist"), "got: {message}");
        }

        assert!(!missing.exists(), "the folder must not have been created");
    }

    /// A free path in a folder that exists is accepted, bare name included.
    ///
    /// The bare name is the case a naive parent check gets wrong: `stego.png`
    /// has an empty parent, which is the working directory rather than a folder
    /// that is missing.
    #[test]
    fn a_free_destination_is_accepted() {
        let directory = tempfile::TempDir::new().expect("temporary directory");

        assert!(refuse_unwritable_output(&directory.path().join("stego.png"), false).is_ok());
        assert!(refuse_unwritable_output(Path::new("stego.png"), false).is_ok());
    }

    /// `extract` keeps the destination rules it always had.
    ///
    /// The two checks look alike and disagree about a directory on purpose: a
    /// payload is written *inside* one, under a name derived from its content,
    /// so refusing it here would break the case that function exists for.
    #[test]
    fn extraction_still_accepts_a_directory_as_a_destination() {
        let directory = tempfile::TempDir::new().expect("temporary directory");

        assert!(refuse_existing_destination(directory.path()).is_ok());
        assert!(
            refuse_unwritable_output(directory.path(), false).is_err(),
            "the two must not have been collapsed into one"
        );
    }

    /// The long help opens with the short one and names the four verbs in order.
    ///
    /// Two failures this guards against, both invisible until someone runs the
    /// binary. Dropping the description would silently remove it from
    /// `--help` — `clap` replaces the short text with the long one rather than
    /// printing both — and rewording the examples until a verb disappears would
    /// leave the flow half-explained, which is the whole reason the text exists.
    #[test]
    fn the_long_help_opens_with_the_short_one() {
        assert!(
            CLI_LONG_ABOUT.starts_with(env!("CARGO_PKG_DESCRIPTION")),
            "the long help must open with the sentence -h prints, got: {CLI_LONG_ABOUT}"
        );

        for verb in ["scan", "embed", "extract", "generate"] {
            assert!(
                CLI_LONG_ABOUT.contains(&format!("stenoxide {verb}")),
                "the flow must still name {verb}, got: {CLI_LONG_ABOUT}"
            );
        }

        // The two installation utilities stay out: they are not steps of the
        // flow, and the list of commands clap prints below already has them.
        assert!(
            !CLI_LONG_ABOUT.contains("completions") && !CLI_LONG_ABOUT.contains("stenoxide man"),
            "the quickstart is about the four verbs only, got: {CLI_LONG_ABOUT}"
        );
    }

    /// The notice names the type it recognised, and offers it as the extension.
    ///
    /// The program already knew: the same table names the file written under
    /// `--payload-out`. Saying "binary data" and suggesting `payload.bin` for a
    /// ZIP was throwing away an answer it had in hand.
    #[test]
    fn the_binary_notice_names_the_type_it_recognised() {
        let mut archive = vec![0x50, 0x4B, 0x03, 0x04, 0x14, 0x00];
        archive.resize(267, 0x00);

        let notice = binary_payload_notice(&archive);

        assert!(notice.contains("267 bytes"), "got: {notice}");
        assert!(notice.contains("ZIP data"), "got: {notice}");
        assert!(notice.contains("> payload.zip"), "got: {notice}");
        // Both ways of capturing it survive naming the type.
        assert!(notice.contains("--payload-out"), "got: {notice}");
    }

    /// A type the table does not recognise keeps the words it always had.
    ///
    /// `bin` is not a type; it is the table saying it matched nothing, and a
    /// notice announcing "BIN data" would be inventing an answer.
    #[test]
    fn an_unrecognised_payload_is_still_called_binary_data() {
        let notice = binary_payload_notice(&[0x80, 0x91, 0xA2, 0xB3]);

        assert!(notice.contains("binary data"), "got: {notice}");
        assert!(notice.contains("> payload.bin"), "got: {notice}");
        assert!(!notice.contains("BIN data"), "got: {notice}");
    }

    /// The guidance says that a line already sent is gone.
    ///
    /// The arrow keys reach the console's own editor and recall the shell's
    /// history, so the correction a user reaches for silently replaces their
    /// message with a command. The way out named is the file, because a line
    /// editor here would bring a history the message could be written into.
    #[test]
    fn the_guidance_says_a_sent_line_cannot_be_taken_back() {
        assert!(
            TYPING_GUIDANCE.contains("cannot be edited"),
            "got: {TYPING_GUIDANCE:?}"
        );
        assert!(
            TYPING_GUIDANCE.contains("-p"),
            "the way out must be named: {TYPING_GUIDANCE:?}"
        );
    }

    /// The guidance names the terminator it expects.
    ///
    /// A guard against the obvious future edit: rewording the guidance without
    /// noticing that the dot is load-bearing would leave the user with a prompt
    /// that tells them to do something the reader does not implement.
    #[test]
    fn the_guidance_states_how_to_finish() {
        assert!(
            TYPING_GUIDANCE.contains(END_OF_MESSAGE),
            "the guidance must name the terminator, got: {TYPING_GUIDANCE:?}"
        );
        assert!(
            TYPING_GUIDANCE.is_ascii(),
            "the guidance is printed before the console's code page is known"
        );
    }
}