webgates_core/credentials/
credentials_verifier.rs

1use super::Credentials;
2use crate::errors_core::Result;
3use crate::verification_result::VerificationResult;
4
5use std::future::Future;
6
7/// Asynchronous credential verification boundary.
8///
9/// Implement this trait to connect `webgates-core` to a password or secret
10/// verification backend, such as a repository plus password-hash store.
11///
12/// This trait is intentionally small and framework-agnostic. Callers provide a
13/// [`Credentials`] value containing an identifier and plaintext secret, and the
14/// implementation returns a [`VerificationResult`] describing whether the secret
15/// matched the stored value.
16///
17/// # Security expectations
18///
19/// Implementations should treat credential verification as a trust-boundary
20/// operation:
21///
22/// - Verify secrets in a way that avoids leaking useful timing differences
23///   between valid and invalid credentials.
24/// - Return [`VerificationResult::Unauthorized`] for logical authentication
25///   failures, including unknown identifiers and secret mismatches.
26/// - Reserve `Err(...)` for infrastructural failures such as storage errors,
27///   unavailable dependencies, or corrupted verification state.
28/// - Avoid logging plaintext secrets or exposing sensitive verification details
29///   in error messages.
30///
31pub trait CredentialsVerifier {
32    /// Verifies the supplied credentials against stored credential state.
33    ///
34    /// # Parameters
35    ///
36    /// - `credentials`: User-supplied identifier and plaintext secret.
37    ///
38    /// # Returns
39    ///
40    /// - `Ok(VerificationResult::Ok)` when the supplied secret matches the
41    ///   stored secret representation.
42    /// - `Ok(VerificationResult::Unauthorized)` when authentication fails for
43    ///   any logical reason.
44    /// - `Err(...)` when verification cannot be completed because of an
45    ///   infrastructural failure.
46    ///
47    /// # Cancellation
48    ///
49    /// Implementations should avoid leaving partial verification work in an
50    /// inconsistent state if the returned future is dropped before completion.
51    fn verify_credentials(
52        &self,
53        credentials: Credentials<uuid::Uuid>,
54    ) -> impl Future<Output = Result<VerificationResult>> + Send;
55}
webgates_core/credentials/credentials_verifier.rs

webgates_core/credentials/
credentials_verifier.rs
