password-auth: replace VerifyError with Error enum (#429)

`VerifyError` was previously the return type for the `verify_password`
function which has two distinct error cases:

- Password hash failed to parse
- Password is invalid

This commit replaces `VerifyError` with an `Error` enum which captures
both cases.

It leverages the `ParseError` type which was added in #428.

password-auth/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "password-auth"
-version = "0.1.1"
+version = "0.2.0-pre"
 description = """
 Password authentication library with a focus on simplicity and ease-of-use,
 with support for Argon2, PBKDF2, and scrypt password hashing algorithms

password-auth/src/errors.rs

@@ -1,9 +1,41 @@
 //! Error types.
 
+use alloc::string::ToString;
 use core::fmt;
 
-/// Password hash parse errors.
+/// Error type.
 #[derive(Clone, Copy, Debug)]
+pub enum Error {
+    /// Password hash parsing errors.
+    Parse(ParseError),
+
+    /// Password is invalid.
+    PasswordInvalid,
+}
+
+impl fmt::Display for Error {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Parse(err) => write!(f, "{err}"),
+            Self::PasswordInvalid => write!(f, "password is invalid"),
+        }
+    }
+}
+
+#[cfg(feature = "std")]
+impl std::error::Error for Error {}
+
+impl From<ParseError> for Error {
+    fn from(err: ParseError) -> Error {
+        Error::Parse(err)
+    }
+}
+
+/// Password hash parse errors.
+// This type has no public constructor and deliberately keeps
+// `password_hash::Error` out of the public API so it can evolve
+// independently (e.g. get to 1.0 faster)
+#[derive(Clone, Copy)]
 pub struct ParseError(password_hash::Error);
 
 impl ParseError {
@@ -13,24 +45,19 @@ impl ParseError {
     }
 }
 
-impl fmt::Display for ParseError {
+impl fmt::Debug for ParseError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        write!(f, "{}", &self.0)
+        f.debug_tuple("ParseError")
+            .field(&self.0.to_string())
+            .finish()
     }
 }
 
-#[cfg(feature = "std")]
-impl std::error::Error for ParseError {}
-
-/// Password hash verification errors.
-#[derive(Clone, Copy, Debug)]
-pub struct VerifyError;
-
-impl fmt::Display for VerifyError {
+impl fmt::Display for ParseError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        f.write_str("password verification error")
+        write!(f, "{}", &self.0)
     }
 }
 
 #[cfg(feature = "std")]
-impl std::error::Error for VerifyError {}
+impl std::error::Error for ParseError {}

password-auth/src/lib.rs

@@ -23,7 +23,7 @@ extern crate std;
 
 mod errors;
 
-pub use crate::errors::{ParseError, VerifyError};
+pub use crate::errors::{Error, ParseError};
 
 use alloc::string::{String, ToString};
 use password_hash::{ParamsString, PasswordHash, PasswordHasher, PasswordVerifier, SaltString};
@@ -78,8 +78,8 @@ fn generate_phc_hash<'a>(
 /// - `Ok(())` if the password hash verified successfully
 /// - `Err(VerifyError)` if the hash didn't parse successfully or the password
 ///   failed to verify against the hash.
-pub fn verify_password(password: impl AsRef<[u8]>, hash: &str) -> Result<(), VerifyError> {
-    let hash = PasswordHash::new(hash).map_err(|_| VerifyError)?;
+pub fn verify_password(password: impl AsRef<[u8]>, hash: &str) -> Result<(), Error> {
+    let hash = PasswordHash::new(hash).map_err(ParseError::new)?;
 
     let algs: &[&dyn PasswordVerifier] = &[
         #[cfg(feature = "argon2")]
@@ -91,7 +91,7 @@ pub fn verify_password(password: impl AsRef<[u8]>, hash: &str) -> Result<(), Ver
     ];
 
     hash.verify_password(algs, password)
-        .map_err(|_| VerifyError)
+        .map_err(|_| Error::PasswordInvalid)
 }
 
 /// Determine if the given password hash is using the recommended algorithm and