refactor(server)!: typed CredentialValidator API + builder method

Reshape the public surface introduced earlier in this PR before it
lands, to avoid a future breaking touch when ironrdp-server's
anyhow-removal pass arrives. Mirrors the post-Devolutions#1264 hand-rolled
error pattern (Display + core::error::Error impls, no thiserror).

Trait signature was `Result<bool>` (i.e. anyhow::Result through the
file-level `use anyhow::Result`). Two issues:

- New public surface depending on anyhow at a moment when the
  workspace is moving the other way (Devolutions#1277 just removed anyhow from
  rdpsnd-native).
- `Ok(true)` vs `Ok(false)` is stringly typed at the call site: a
  bare bool with no semantic clue.

New shape:

- `CredentialDecision::{Accept, Reject}` for the binary outcome.
- `CredentialValidationError` wrapping any `core::error::Error +
  Send + Sync` for the case where the validator backend itself
  failed (LDAP unreachable, PAM transport error, etc.). Manual
  Display + Error impls; source chains through.
- `validate(&self, &Credentials) -> Result<CredentialDecision,
  CredentialValidationError>`.

The accept/reject/backend-error trichotomy is now explicit at every
call site. Rejection is no longer an error; backend failure is.
Log + bail strings updated to match the trichotomy.

Also addresses the API consistency note: every other configurable
on `RdpServerBuilder<BuilderDone>` goes through `with_*` on the
builder. Added `with_credential_validator(Option<Arc<dyn ...>>)`
following the same shape as `with_connection_handler`. The
post-construction `set_credential_validator` setter is kept (now
takes `Option` to match the field and the builder's setter shape)
for dynamic reconfiguration after `build()`.

Tests for the trait, the `CredentialDecision` enum, the error
wrapper's source chaining, and the `Send + Sync + 'static` bounds
through `Arc<dyn _>` live in
`crates/ironrdp-testsuite-core/tests/server/credential_validator.rs`,
matching the canonical IronRDP split: public-API tests in
`ironrdp-testsuite-core`, inline `#[cfg(test)]` only for
crate-internal behavior (per the `autodetect.rs` precedent which
has both: inline tests on internal state machine, public-API tests
in `testsuite-core/tests/server/autodetect.rs`).

Verification: `cargo xtask check fmt/lints/tests/typos/locks` all
pass; new tests pass in the testsuite-core harness (4 added).

Refs Devolutions#1154, Devolutions#1150, Devolutions#1155.

Author: glamberson

crates/ironrdp-server/src/builder.rs

@@ -1,4 +1,5 @@
 use core::net::SocketAddr;
+use std::sync::Arc;
 
 use anyhow::Result;
 use ironrdp_pdu::rdp::capability_sets::{BitmapCodecs, server_codecs_capabilities};
@@ -9,7 +10,7 @@ use super::display::{DesktopSize, RdpServerDisplay};
 #[cfg(feature = "egfx")]
 use super::gfx::GfxServerFactory;
 use super::handler::{KeyboardEvent, MouseEvent, RdpServerInputHandler};
-use super::server::{ConnectionHandler, RdpServer, RdpServerOptions, RdpServerSecurity};
+use super::server::{ConnectionHandler, CredentialValidator, RdpServer, RdpServerOptions, RdpServerSecurity};
 use crate::{DisplayUpdate, RdpServerDisplayUpdates, SoundServerFactory};
 
 pub struct WantsAddr {}
@@ -35,6 +36,7 @@ pub struct BuilderDone {
     cliprdr_factory: Option<Box<dyn CliprdrServerFactory>>,
     sound_factory: Option<Box<dyn SoundServerFactory>>,
     connection_handler: Option<Box<dyn ConnectionHandler>>,
+    credential_validator: Option<Arc<dyn CredentialValidator>>,
     #[cfg(feature = "egfx")]
     gfx_factory: Option<Box<dyn GfxServerFactory>>,
 }
@@ -130,6 +132,7 @@ impl RdpServerBuilder<WantsDisplay> {
                 sound_factory: None,
                 cliprdr_factory: None,
                 connection_handler: None,
+                credential_validator: None,
                 codecs: server_codecs_capabilities(&[]).expect("can't panic for &[]"),
                 max_request_size: RdpServerOptions::DEFAULT_MAX_REQUEST_SIZE,
                 #[cfg(feature = "egfx")]
@@ -148,6 +151,7 @@ impl RdpServerBuilder<WantsDisplay> {
                 sound_factory: None,
                 cliprdr_factory: None,
                 connection_handler: None,
+                credential_validator: None,
                 codecs: server_codecs_capabilities(&[]).expect("can't panic for &[]"),
                 max_request_size: RdpServerOptions::DEFAULT_MAX_REQUEST_SIZE,
                 #[cfg(feature = "egfx")]
@@ -198,8 +202,23 @@ impl RdpServerBuilder<BuilderDone> {
         self
     }
 
+    /// Set a credential validator for TLS-mode connections.
+    ///
+    /// When set, credentials received from the client during
+    /// `SecureSettingsExchange` (`ClientInfoPdu`) are passed to this
+    /// validator before the session is established. Rejection or a backend
+    /// error closes the connection. Pass `None` (the default) to skip
+    /// validation entirely.
+    ///
+    /// Not used for CredSSP/Hybrid connections (those use pre-loaded
+    /// credentials for NTLM challenge-response).
+    pub fn with_credential_validator(mut self, validator: Option<Arc<dyn CredentialValidator>>) -> Self {
+        self.state.credential_validator = validator;
+        self
+    }
+
     pub fn build(self) -> RdpServer {
-        RdpServer::new(
+        let mut server = RdpServer::new(
             RdpServerOptions {
                 addr: self.state.addr,
                 security: self.state.security,
@@ -213,7 +232,9 @@ impl RdpServerBuilder<BuilderDone> {
             self.state.connection_handler,
             #[cfg(feature = "egfx")]
             self.state.gfx_factory,
-        )
+        );
+        server.set_credential_validator(self.state.credential_validator);
+        server
     }
 }
 

crates/ironrdp-server/src/lib.rs

@@ -33,8 +33,8 @@ pub use handler::{KeyboardEvent, MouseEvent, RdpServerInputHandler};
 #[cfg(feature = "helper")]
 pub use helper::TlsIdentityCtx;
 pub use server::{
-    ConnectionHandler, CredentialValidator, Credentials, PostConnectionAction, RdpServer, RdpServerOptions,
-    RdpServerSecurity, ServerEvent, ServerEventSender,
+    ConnectionHandler, CredentialDecision, CredentialValidationError, CredentialValidator, Credentials,
+    PostConnectionAction, RdpServer, RdpServerOptions, RdpServerSecurity, ServerEvent, ServerEventSender,
 };
 pub use sound::{RdpsndServerHandler, RdpsndServerMessage, SoundServerFactory};
 

crates/ironrdp-server/src/server.rs

@@ -1,3 +1,4 @@
+use core::fmt;
 use core::net::SocketAddr;
 use core::time::Duration;
 use std::rc::Rc;
@@ -87,6 +88,55 @@ pub trait ConnectionHandler: Send {
     }
 }
 
+/// Outcome of a successful [`CredentialValidator::validate`] call.
+///
+/// A rejection from a working validator is not an error: the validator did
+/// its job and decided the credentials do not authenticate. Backend failures
+/// (LDAP unreachable, PAM transport broken, database connection lost) are
+/// reported via [`CredentialValidationError`] instead.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CredentialDecision {
+    /// Credentials accepted; the connection proceeds.
+    Accept,
+    /// Credentials rejected; the connection is closed.
+    Reject,
+}
+
+/// Error returned by a [`CredentialValidator`] when the validator backend
+/// itself fails (rather than the credentials being invalid).
+///
+/// Wraps any [`core::error::Error`] from the backend (LDAP/PAM/DB/etc.) so
+/// the trait does not require a particular error library in implementors or
+/// consumers.
+#[derive(Debug)]
+pub struct CredentialValidationError {
+    source: Box<dyn core::error::Error + Send + Sync>,
+}
+
+impl CredentialValidationError {
+    /// Wrap a backend error as a credential-validation failure.
+    pub fn new<E>(source: E) -> Self
+    where
+        E: core::error::Error + Send + Sync + 'static,
+    {
+        Self {
+            source: Box::new(source),
+        }
+    }
+}
+
+impl fmt::Display for CredentialValidationError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str("credential validator backend failure")
+    }
+}
+
+impl core::error::Error for CredentialValidationError {
+    fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
+        Some(&*self.source)
+    }
+}
+
 /// Server-side credential validator for TLS-mode connections.
 ///
 /// Called during connection setup when the server receives client credentials
@@ -96,10 +146,41 @@ pub trait ConnectionHandler: Send {
 /// Implement this trait to validate credentials against external systems
 /// (PAM, LDAP, database, etc.). For blocking backends, wrap the call in
 /// `tokio::task::spawn_blocking` to avoid stalling the async runtime.
+///
+/// # Example
+///
+/// ```ignore
+/// use std::sync::Arc;
+/// use ironrdp_server::{
+///     CredentialDecision, CredentialValidationError, CredentialValidator, Credentials,
+/// };
+///
+/// struct StaticValidator {
+///     expected_user: String,
+///     expected_password: String,
+/// }
+///
+/// impl CredentialValidator for StaticValidator {
+///     fn validate(
+///         &self,
+///         creds: &Credentials,
+///     ) -> Result<CredentialDecision, CredentialValidationError> {
+///         if creds.username == self.expected_user && creds.password == self.expected_password {
+///             Ok(CredentialDecision::Accept)
+///         } else {
+///             Ok(CredentialDecision::Reject)
+///         }
+///     }
+/// }
+/// ```
 pub trait CredentialValidator: Send + Sync {
     /// Validate credentials received from the client.
-    /// Return `Ok(true)` to accept, `Ok(false)` to reject.
-    fn validate(&self, credentials: &Credentials) -> Result<bool>;
+    ///
+    /// Return `Ok(CredentialDecision::Accept)` to permit the connection,
+    /// `Ok(CredentialDecision::Reject)` to refuse it. Return
+    /// `Err(CredentialValidationError::new(_))` only when the validator
+    /// itself could not produce a decision (backend system error).
+    fn validate(&self, credentials: &Credentials) -> Result<CredentialDecision, CredentialValidationError>;
 }
 
 #[derive(Clone)]
@@ -387,15 +468,23 @@ impl RdpServer {
         builder::RdpServerBuilder::new()
     }
 
-    /// Set a credential validator for TLS-mode connections.
+    /// Set or clear the credential validator for TLS-mode connections.
+    ///
+    /// When set, credentials received from the client during
+    /// `SecureSettingsExchange` are validated through this callback before
+    /// the session is established. If the validator returns
+    /// [`CredentialDecision::Reject`] (or a [`CredentialValidationError`]),
+    /// the connection is rejected. Passing `None` clears any previously
+    /// configured validator.
     ///
-    /// When set, credentials received from the client during `SecureSettingsExchange`
-    /// are validated through this callback before the session is established.
-    /// If validation fails, the connection is rejected.
+    /// Most callers should configure the validator at construction time via
+    /// the builder's `with_credential_validator` method
+    /// ([`RdpServer::builder`]); this setter exists for dynamic
+    /// post-construction reconfiguration.
     ///
     /// Not used for CredSSP/Hybrid connections (those use pre-loaded credentials).
-    pub fn set_credential_validator(&mut self, validator: Arc<dyn CredentialValidator>) {
-        self.credential_validator = Some(validator);
+    pub fn set_credential_validator(&mut self, validator: Option<Arc<dyn CredentialValidator>>) {
+        self.credential_validator = validator;
     }
 
     pub fn event_sender(&self) -> &mpsc::UnboundedSender<ServerEvent> {
@@ -988,16 +1077,16 @@ impl RdpServer {
         if let Some(validator) = &self.credential_validator {
             if let Some(creds) = &result.credentials {
                 match validator.validate(creds) {
-                    Ok(true) => {
-                        debug!("Credential validation succeeded");
+                    Ok(CredentialDecision::Accept) => {
+                        debug!("Credential validation accepted");
                     }
-                    Ok(false) => {
-                        warn!("Credential validation failed");
-                        bail!("credential validation failed");
+                    Ok(CredentialDecision::Reject) => {
+                        warn!("Credential validation rejected");
+                        bail!("credential validation rejected");
                     }
                     Err(e) => {
-                        error!(error = %e, "Credential validator error");
-                        bail!("credential validation error");
+                        error!(error = %e, "Credential validator backend error");
+                        bail!("credential validation backend error");
                     }
                 }
             } else {

crates/ironrdp-testsuite-core/tests/server/credential_validator.rs

@@ -0,0 +1,70 @@
+use core::fmt;
+use std::sync::Arc;
+
+use ironrdp_server::{CredentialDecision, CredentialValidationError, CredentialValidator, Credentials};
+
+fn fixed_creds() -> Credentials {
+    Credentials {
+        username: "alice".to_owned(),
+        password: "hunter2".to_owned(),
+        domain: None,
+    }
+}
+
+struct AlwaysAccept;
+impl CredentialValidator for AlwaysAccept {
+    fn validate(&self, _: &Credentials) -> Result<CredentialDecision, CredentialValidationError> {
+        Ok(CredentialDecision::Accept)
+    }
+}
+
+struct AlwaysReject;
+impl CredentialValidator for AlwaysReject {
+    fn validate(&self, _: &Credentials) -> Result<CredentialDecision, CredentialValidationError> {
+        Ok(CredentialDecision::Reject)
+    }
+}
+
+#[derive(Debug)]
+struct BackendDown;
+impl fmt::Display for BackendDown {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str("ldap server unreachable")
+    }
+}
+impl core::error::Error for BackendDown {}
+
+struct AlwaysBackendError;
+impl CredentialValidator for AlwaysBackendError {
+    fn validate(&self, _: &Credentials) -> Result<CredentialDecision, CredentialValidationError> {
+        Err(CredentialValidationError::new(BackendDown))
+    }
+}
+
+#[test]
+fn validator_accept_returns_accept() {
+    let v = AlwaysAccept;
+    assert_eq!(v.validate(&fixed_creds()).unwrap(), CredentialDecision::Accept);
+}
+
+#[test]
+fn validator_reject_returns_reject() {
+    let v = AlwaysReject;
+    assert_eq!(v.validate(&fixed_creds()).unwrap(), CredentialDecision::Reject);
+}
+
+#[test]
+fn validator_backend_error_propagates_source() {
+    let v = AlwaysBackendError;
+    let err = v.validate(&fixed_creds()).expect_err("expected backend error");
+    assert_eq!(err.to_string(), "credential validator backend failure");
+    let inner = core::error::Error::source(&err).expect("source must be Some");
+    assert_eq!(inner.to_string(), "ldap server unreachable");
+}
+
+#[test]
+fn validator_can_be_held_behind_arc_dyn() {
+    // Exercises the Send + Sync + 'static bounds the trait promises through Arc<dyn _>.
+    let v: Arc<dyn CredentialValidator> = Arc::new(AlwaysAccept);
+    assert_eq!(v.validate(&fixed_creds()).unwrap(), CredentialDecision::Accept);
+}

crates/ironrdp-testsuite-core/tests/server/mod.rs

@@ -1,3 +1,4 @@
 mod acceptor;
 mod autodetect;
+mod credential_validator;
 mod fast_path;