/// A boxed error from an underlying implementation.
///
/// Errors from CipherBox's dependencies are carried in this opaque form so
/// that replacing a dependency never changes CipherBox's public API. The
/// underlying error remains available through [`std::error::Error::source`].
pub type BoxError = Box<dyn std::error::Error + Send + Sync + 'static>;

/// Error types that can occur when using CipherBox operations.
///
/// This enum covers all possible errors from cryptographic operations,
/// I/O operations, and serialization/deserialization. It is non-exhaustive so
/// that future versions can report new conditions without a breaking change.
#[derive(thiserror::Error, Debug)]
#[non_exhaustive]
pub enum Error {
    /// The input does not begin with the CipherBox signature.
    #[error("Invalid storage signature")]
    InvalidSignature,
    /// The data uses a storage format version this build does not support.
    #[error("Unsupported storage format version {0}")]
    UnsupportedVersion(u8),
    /// The stored key derivation parameters are invalid or exceed the limits
    /// this build accepts.
    #[error("Unsupported key derivation parameters")]
    UnsupportedKdfParameters,
    /// The stored key commitment did not match the one derived from the
    /// supplied password, indicating a wrong password or tampered data.
    #[error("Key commitment verification failed")]
    CommitmentMismatch,
    /// The encrypted data failed authentication, indicating it has been
    /// tampered with or corrupted.
    #[error("Encrypted data failed authentication")]
    Authentication,
    /// The data could not be encrypted because it exceeds the cipher's
    /// maximum message length.
    #[error("Encryption failed")]
    Encryption,
    /// Deriving a key from the password failed, for example because the
    /// required memory could not be allocated.
    #[error("Key derivation failed: {0}")]
    KeyDerivation(#[source] BoxError),
    /// The value could not be serialized.
    #[error("Serialization failed: {0}")]
    Serialization(#[source] BoxError),
    /// The decrypted data could not be deserialized as the requested type.
    #[error("Deserialization failed: {0}")]
    Deserialization(#[source] BoxError),
    /// I/O operation failed.
    #[error(transparent)]
    IO(#[from] std::io::Error),
}